序章：为什么拆 opencode？
这个系列解决什么问题
2025-2026 年，AI Coding Agent 从一个概念变成了工程师日常工具。Claude Code、codex、opencode、Cursor 等工具层出不穷。
但如果你不是只满足于"用它"，而是想理解——
- AI Agent 的核心循环到底怎么工作的？
- 工具调用、权限控制、上下文管理这些机制背后是什么？
- 如果让我自己设计一个 Agent，架构该怎么拆？
你会发现：市面上几乎没有系统性讲源码的资料。
- 论文很多，但离代码太远
- 闭源产品多（Claude Code / codex / Cursor），源码看不到
- 开源项目大（LangChain 等数十万行），从哪看起都不知道
这个系列就是为了填补这个缺口——用一本"书"的篇幅，把一个生产级 AI Coding Agent 的源码，逐模块逐行拆给你看。
为什么选 opencode
在众多 AI Coding Agent 开源项目中，我选 opencode v1.17.7 作为拆解目标，因为：
| 条件 | opencode | 其他 |
|---|---|---|
| 完全开源 | ✅ 真实可跑的源码 | Claude Code ❌ 闭源 |
| 代码规模适中 | ~50 个核心源文件，适合"读完" | LangChain 太庞大 |
| 架构清晰 | monorepo + Effect-ts，模块边界分明 | 很多项目架构混乱 |
| 独特设计 | Skill/Plugin/权限分层，学得到真东西 | 很多项目只是 API 封装 |
| 可横向对比 | 容易对比 Claude Code/codex 的设计取舍 | 闭源产品无法直接对比 |
一句话：opencode 是当前能找到的、最适合当"教材"的 AI Agent 开源项目。
60 篇学完，你能获得什么
| 能力 | 对应章节 | 为什么重要 |
|---|---|---|
| 理解 Agent 核心循环 | 04 Agent / 05 Session | Agent = while + tool call，但工业级远不止 |
| 掌握 Tool 系统设计 | 06 Tool | "一切皆工具"的架构模式，可复用 |
| 学会 Effect-ts 实战 | 12 Effect-ts | 函数式 DI + 类型安全错误处理 |
| 看懂权限分层设计 | 10 Permission | 每次工具调用背后的安全博弈 |
| 理解 MCP 协议落地 | 09 MCP | 开放协议在真实项目中的集成方式 |
| 能写一个最小 Agent | 14 手写还原 | 第12章用 ≤200 行代码验证所有理解 |
更深层的是： 60 篇读完后，你再去看任何一个 AI Agent 项目（Claude Code/codex/Continue 等），都不会觉得"黑盒"了。因为你已经建好了心智模型——知道一个 Agent 必须解决哪些问题、每种方案各有什么取舍。
怎么读这个系列
| 角色 | 推荐路径 | 预估耗时 |
|---|---|---|
| 快速了解全貌 | 00 → 每章 README | 2 小时 |
| Agent 应用开发者 | 00 → 01 → 04 → 05 → 06 → 14 | 20 小时 |
| 后端/架构学习者 | 00 → 01 → 12 → 10 → 02 → 07 | 15 小时 |
| AI 工具链集成者 | 00 → 01 → 06 → 08 → 09 → 11 | 12 小时 |
| 逐篇通读 | 全部 60 篇 | 60+ 小时 |
每篇文章独立可读，也可以按章连续阅读。每章 README 有完整的知识地图。
源码版本
| 项目 | 版本 | 说明 |
|---|---|---|
| opencode | v1.17.7 | 每篇文章标注 文件:行号，直接可跟 |
| 仓库地址 | github.com/anomalyco/opencode | |
| 本地镜像 | sources/opencode/ |
本系列基于此版本 |
系列约定
- 每篇文章聚焦一个机制，不贪多
- 核心代码展示 ≤25 行骨架，不贴整段
- 每篇回答"为什么这样设计"，不是只讲"做了什么"
- 大章首篇有三角对比（opencode vs Claude Code vs codex）
- 系列围绕 packages/opencode/src，不涉及 app/web/console 等 UI 包
准备好了？我们从第一章开始——先俯瞰这 25 个 packages 的全貌。
📺 公众号「Ai拆代码的曹操」 🌟 知识星球「Ai拆代码的曹操」
