项目总览：从浏览器到 Agent 系统

这条路线从用户能直接感知的页面行为出发，逐步进入框架、构建、运行时和后端，最后把模型能力接入一个有权限边界、可测试、可恢复的 Agent 系统。六个阶段并非互不相关的技术目录：后一阶段始终以前一阶段已经解释清楚的事实为输入。

六个阶段怎样衔接

阅读时可以顺序推进，也可以从当前故障反向查找。页面语义、样式和浏览器请求先看 Web 基础；状态更新、首屏与水合看前端框架；模块、资源和发布看构建工具；进程、权限和宿主 API 看运行时；事务、重试和后台任务看后端；检索质量、工具调用与模型安全则进入 Agent 阶段。

贯穿项目怎样演进

路线使用同一个技术目录服务串联各阶段。开始时，它只是一个可访问、可搜索的静态页面；随后用不同框架实现相同交互，借此比较状态和渲染方式；构建阶段追踪这些源码如何变成 HTML、JavaScript、CSS 和其他资源；运行时阶段把读取能力放进不同 JavaScript 宿主；后端阶段补上可靠的 API、持久化与任务处理；Agent 阶段再增加检索、引用和受控工具调用。

项目范围会随学习目标扩展，但不会提前加入无关业务。用户体系、收藏、学习进度和计费只有在它们能帮助解释认证、授权、写入或恢复时才值得引入。这样每次变化都有明确原因，示例也不会因为功能堆积而遮住技术本身。

比较技术时看什么

语法和单次跑分只能说明很小一部分问题。选型时应先写清用户任务、部署环境、团队经验和无法妥协的约束，再观察以下差异：

• 概念模型是否清楚，团队能否定位错误发生在哪一层。
• 类型、错误和并发如何表达，失败后能否安全恢复。
• 调试、测试和升级是否有稳定入口。
• 性能数据在什么机器、版本、输入和缓存条件下取得。
• 部署、招聘、迁移和长期维护成本是否可以接受。

比较结论应带条件。例如“适合静态内容较多、交互岛较少的站点”比“性能最好”更有用；“团队依赖某个 Node 原生扩展，因此暂不迁移到边缘宿主”也比罗列功能更接近真实决策。

前三个阶段怎样交接

Web 基础给出浏览器事实：页面语义、请求与取消、缓存与存储、权限、时间和渲染。前端框架在这些事实之上安排组件、路由、状态、服务端读取和客户端接管。构建工具再把入口、模块关系、动态资源、Source Map 和发布规则转成实际产物。

以“编辑一条记录并在另一台设备看到确认结果”为例：浏览器层要说明表单、键盘操作、Fetch、离线记录和网络失败；框架层要说明草稿由谁拥有、服务端数据怎样读取、冲突怎样显示；构建层要说明编辑器和 Worker 进入哪些资源，旧页面在新版本发布后还能否加载。任何一层没有定义版本、作用范围和恢复方式，问题都会被推给下一层，用更复杂的代码弥补。

遇到问题时，可以保留一份简短记录：用户做了什么、URL 和输入是什么、当前身份与数据版本是什么、页面加载了哪次构建、关键请求或操作 ID 是什么、用户最终看到了成功、失败还是冲突。它不要求保存所有日志，却足以让维护者从症状回到可验证的输入。

什么时候重新审视原来的选择

当用户任务从阅读变成高频编辑、系统进入多租户、开始使用 SSR 或边缘部署、需要离线与实时协作，或者框架、构建器、运行时发生大版本升级时，原来的结论都需要重新核对。发布事故暴露出缓存、权限、旧资源或 Source Map 问题，也说明某个边界此前没有写清。

复审的目的不是频繁换工具，而是确认原来的条件是否还成立。若确实需要迁移，应把变化拆成能够验证和回退的小步，并始终以用户任务是否正确完成作为判断依据。

走完整条路线后，读者应能从一个用户可见问题出发，依次检查浏览器、框架、构建、运行时、后端和模型系统，并指出第一个错误事实及其负责人。面对新的框架、工具或模型时，也能把宣传术语还原成输入、输出、权限、状态、成本和恢复路径。