opencode 是什么——本书的贯穿案例
形态、架构、阅读地图
学 AI 产品设计有两条路。
第一条是自上而下——读 paper（ReAct、Reflexion、AutoGPT）、看 demo（OpenAI 的 cookbook、Anthropic 的官方例子）。理论清晰——但脱离工程现实——demo 里的 Agent 跟生产环境的 Agent 是两种东西。
第二条是自下而上——挑一个真实开源 Agent，从入口到细节读到底。看到所有的"理论之外"——错误处理、性能优化、UI 集成、跨平台、多 provider 适配、用户体验细节。
本书走第二条——opencode 是那个"贯穿全书的真实案例"。
一、为什么选 opencode 而不是其他 Agent
可以学的开源 Agent 不只 opencode：
- Aider——Python 写的命令行 Agent
- Continue——VSCode 集成的 Agent
- Goose——Square 开源的 Agent 框架
- SWE-agent——Princeton 学术界的 Agent
- opencode——Anomaly Innovations 公司的开源产品
每个都有可学的地方——为什么选 opencode 当本书主线？
理由 1：完整性
opencode 不只是 CLI——它有 TUI（终端图形界面）、Web UI（浏览器）、ACP（编辑器集成协议）、SDK。这意味着我们能看到 AI Agent 在不同 UI 形态下的设计——server 怎么驱动多端、UI 怎么消费 server 事件、协议层怎么对接编辑器。
这种"形态完整"让 opencode 适合作为教学样本——单一形态的 Agent（比如 Aider 只有 CLI）能教的东西少很多。
理由 2：跨多 LLM provider
opencode 对接 10 个 LLM provider（Anthropic、OpenAI、Google、Bedrock、Cerebras、Cloudflare、GitHub Copilot、OpenRouter、xAI、Azure）。这意味着它必须直面"LLM 之间的真实差异"——不能假设单一模型的行为。
被迫面对多样性的产品会暴露出更多有意思的设计选择——比如 5 张脸 prompt 的设计（1.3 章）、10 个 protocol adapter 的实现（第 6 篇）。
单 provider 的 Agent（比如 Claude Code 只用 Claude）能教的协议层东西少很多。
理由 3：开源
所有代码可读——每个设计判断都可以追溯到 commit 和 PR。这本书引用的代码路径、行号、prompt 文本——你都可以自己去 GitHub 上验证。
闭源产品（Cursor、Devin）我们只能"猜"——开源 opencode 我们能"看"。
理由 4：规模合适
太小的 Agent（500 行代码）能教的不多。太大的 Agent（百万行）读不完。opencode 大约 15 万行 TypeScript——中等规模——一个工程师不可能短时间读完——但完全可以按主题分章节阅读。
理由 5：生产级
opencode 不是研究 demo——它是个有真实用户的开源产品（GitHub 176K stars，写作时）——里面有大量"生产环境"才会有的细节——错误处理、性能优化、用户体验、跨平台兼容性。这些在 demo 里看不到。
二、opencode 的项目背景
opencode 由一家叫 Anomaly Innovations 的公司开发。Anomaly 还做其他几款 AI 产品——但 opencode 是他们最有影响力的开源项目。
公司由几个之前在 SST（Serverless Stack）的工程师创办——他们有大量"开发者工具 + 开源社区"的经验。这个背景影响了 opencode 的产品姿态——它面向开发者、强调可定制、开放生态。
如果换成"金融 Agent"或"医疗 Agent"——产品姿态会完全不同——更封闭、更监管、更黑盒。理解 opencode 是个"开发者工具"——能解释它的很多设计选择（比如开源 prompt、开放 plugin、强调 cost 透明）。
三、opencode 的形态
opencode 不止一个东西——它有几种运行形态。
形态 1：CLI 模式
opencode run "fix the broken test" —— 跑一次性任务。命令行启动、做任务、退出。
适合自动化场景——CI 里跑、脚本里调、定时任务。
形态 2：TUI 模式
opencode tui（或直接 opencode）—— 启动一个全屏终端界面。
左边消息时间线、右边状态。可以用键盘快捷键切 session、切 model、切 agent。
适合开发者日常用——终端友好、不离开终端就能用 AI。
形态 3：Web 模式
opencode serve 启动 HTTP server——用户在浏览器里访问。
适合多用户场景——一个 server 多人共享、或者远程访问。
形态 4：ACP 模式
opencode acp —— 作为 Agent Client Protocol 的服务端运行。
ACP 是一个开放的"AI Agent 协议"——Zed、JetBrains 等编辑器可以通过它接 AI Agent。opencode 实现了 ACP——成为这些编辑器的 AI backend。
关键设计：四种形态共享同一个 server。不是四个独立产品——是一个 server 暴露多种接口。这是个核心设计选择——我们在第 9 篇详细看。
四、opencode 的核心代码组织
opencode 是个 TypeScript monorepo——用 Bun（一个比 Node.js 快几倍的 JS 运行时）做 runtime。打开 packages 目录——主要的包：
packages/opencode/——主进程（session、tool、prompt、provider adapter）packages/core/——核心抽象（schema、event bus、permission、database）packages/tui/——终端界面（基于 OpenTUI）packages/app/——Web 界面（Solid.js + TanStack Query）packages/ui/——TUI 和 Web 共用组件库packages/sdk/——外部应用用的 TypeScript SDKpackages/llm/——LLM provider adapter（10 个 adapter）packages/server/——HTTP server（REST API + SSE）
这种划分对你"读这本书时该看哪部分代码"很有帮助——后面每一章引用代码路径时——你能很快定位到哪个包。
五、opencode 的"AI 核心机制"分布在几个关键文件
如果你想自己读 opencode 源码——这些是"地图"：
5 张脸的 prompt 文件——在 packages/opencode/src/session/prompt/：
anthropic.txt——Claude 系列gpt.txt——OpenAI 非推理模型gemini.txt——Google Gemini 系列beast.txt——推理模型的"野兽模式"default.txt——兜底
第 1 篇用 10 章详细拆这 5 张脸。
15 个工具的实现——在 packages/opencode/src/tool/：每个工具一个 .ts（实现）+ 一个 .txt（给 LLM 看的描述）。
第 3 篇用 10 章详细拆这 15 个工具。
主循环——在 packages/opencode/src/session/prompt.ts 的 runLoop 函数。这是 opencode 的"心脏"——所有 AI 行为都是这个循环跑出来的。
第 2 篇用 8 章详细拆主循环及相关机制。
Provider 适配层——在 packages/llm/src/protocols/：10 个 adapter，分别处理 Claude / GPT / Gemini / Bedrock 等的 API 差异。
第 6 篇用 8 章详细对比 10 个 adapter。
Permission 系统——在 packages/core/src/permission.ts：3 状态（allow/ask/deny）× 3 层（defaults/config/user）的权限矩阵。
第 7 篇用 7 章详细讲 Permission。
Event Stream——在 packages/core/src/event.ts：31 种事件类型的总线，驱动 UI 实时更新。
第 9 篇用 7 章详细讲 Event Stream + 多端架构。
读这本书时——每个章节会反复引用这些文件。后面读起来你会对每个路径越来越熟。
六、读这本书的方式
这本书有 95 章——一天读 1-2 章，2 个月读完。
每篇 7-10 章，主题相对独立——你不需要严格按顺序读。如果你只关心某个主题（比如 prompt engineering 或 tool 设计）——可以只读那一篇。
但第 0 篇（这 6 章）必读——它是基础铺垫——后面所有篇都假设你已经懂了 LLM、Chatbot、Agent 的差别、HTTP 层是什么、token 是什么、system prompt 怎么工作、tool calling 怎么实现。
读到这一章——你已经基本完成第 0 篇——可以进入后面的"深水区"。
七、读完这本书你会知道什么
读完整本书——你会知道：
关于 AI 产品的认识：
- AI Agent 跟普通 Chatbot 在结构上的本质差别
- 一个生产级 AI Agent 必须解决的工程问题
- prompt engineering 的真实做法（不是网上流传的"prompt 模板")
- 工具设计、错误处理、权限管理的核心机制
- multi-provider 适配的真实复杂度
- multi-agent 编排的设计选择
- Event Stream、Server-driven UI、SSE 协议的实战
- 8 条 AI Agent 设计的产品哲学主线
- 5 条 prompt engineering 原则
关于自己产品的判断：
- 设计自己的 AI 产品时该问哪些问题
- 怎么从 tool 集判断 Agent 能力
- 怎么权衡 context 成本 vs 质量
- 怎么设计 multi-agent 协作
- 怎么管理 token 经济学
但有几件事这本书不会给你：
- 你的 AI 产品该怎么设计的具体答案——这取决于你的用户和场景
- LLM 内部架构的细节（Transformer 怎么工作）——这是另一本书的话题
- 怎么训练自己的 LLM——这是另一个领域
- 怎么用现成的框架（LangChain、LlamaIndex）快速搭 AI 应用——这本书的颗粒度更深
八、准备好了，进入第 1 篇
第 0 篇我们铺完了。
你现在懂了——
- LLM、Chatbot、Agent 三层完全不同
- 一次 AI 对话在 HTTP 层是什么样
- token 是 AI 产品的"石油"
- system prompt 是 LLM 的"出厂设置"
- tool calling 是 LLM 跟世界互动的协议
- opencode 是个怎样的贯穿案例
接下来第 1 篇——我们进入 AI Agent 设计里最被低估也最有趣的一层——prompt engineering。
第 1 篇会用 10 章拆 opencode 的 5 张脸 prompt——anthropic、gpt、gemini、beast、default。每张脸是对一类模型"病症"的"处方"。
如果你已经读过本书的样章《五张脸的瞬间》——你大概知道这一篇的味道。如果还没读——也不影响——1.1 会从原理讲起。
准备好了。进入正篇。