版本说明
这一页说明三件事：
- 这本书基于哪一份源码来写
- 这本书希望解决什么问题
- 阅读时哪些地方应当视为“当前实现状态”，而不是长期承诺
源码基线
本书基于当前仓库中的 OpenCode 源码整理，阅读入口统一指向官方仓库：
- GitHub 仓库：
anomalyco/opencode - 文中源码链接分支：
dev - 电子书站点位置：
docs/book/
这意味着本书首先是一份“基于当前实现的源码带读”，而不是脱离仓库现实的 Agent 理论教材。
写作范围
这本书重点解释的是：
- OpenCode 当前仓库怎样组织 Agent 运行时
- 多模型、工具、会话、MCP、UI、持久化等能力怎样落到真实代码
- 一个面向开发工作流的 Agent 产品，为什么会长成今天这套工程结构
这本书刻意不把重心放在：
- 泛泛介绍 LLM、Prompt、RAG 等通用概念
- 脱离当前仓库去设计“更理想”的未来架构
- 把尚未在代码里落地的能力写成既成事实
阅读边界
阅读本书时，建议默认采用下面这个判断原则：
- 文中明确指向文件和代码路径的内容，优先视为“当前已实现”。
- 文中写明“实验性”“当前状态”“更适合理解为”的内容，优先视为“基于现状的工程判断”。
- 如果仓库未来发生重构，章节里的结构理解方法通常仍然有价值，但具体文件路径和实现细节可能变化。
为什么统一指向 dev
本书中的源码链接统一指向 dev 分支，不指向 main，原因很简单：
- 当前仓库默认开发分支是
dev - 这样更接近真实迭代状态
- 也能减少读者点开链接后发现“代码对不上”的情况
如何理解“当前实现状态”
在 Agent 项目里，有些能力天然变化很快，例如：
- provider 支持范围
- MCP 集成方式
- LSP 能力完整度
- 云端产品边界
因此本书更强调：
- 先理解当前代码怎样工作
- 再提炼背后的设计原则
- 最后再判断哪些东西适合迁移到自己的项目
这比一开始追求“写一份永远不过时的文档”更现实。
适合谁
这本书最适合下面三类读者：
- 想系统理解 Agent 工程实现的初学者
- 想从真实仓库学习大型 TypeScript 项目拆分方式的工程师
- 想基于 OpenCode 继续做扩展、实验或贡献的开发者
推荐使用方式
如果你准备把这本书当作源码带读材料，我建议这样使用：
- 先看 阅读地图，选一条路线。
- 每一篇先抓“入口文件 + 主链路 + 最容易误解的点”。
- 遇到和代码不一致的地方，以当前仓库源码为准。
最后说明
本书的目标不是替你记住每一个文件，而是帮你建立一种更可靠的阅读方法：
- 先定边界
- 再抓主链路
- 再回到实现细节
如果你能把这套方法迁移到自己的 Agent 项目里，这本书就已经达成目的。