源码学习路径
这是 OpenCode 源码的引导式课程。下面 8 个模块按自底向上顺序排列：从地基（配置、Provider、权限）开始，经过集成层（MCP、LSP），到核心引擎（Agent），最后是用户可见的接口（Command、CLI）。
每章是对一个模块架构、类型、核心流程和设计权衡的深度解析（3000-4000 字）。按顺序阅读可获得完整心智模型，也可直接跳到你需要的模块。
前置技能
阅读源码前，请确认你熟悉以下内容：
| 技能 | 重要度 | 原因 |
|---|---|---|
| TypeScript | 必需 | 代码库完全类型化，类型是主要文档 |
| Promises / async-await | 必需 | 几乎所有操作都是异步的（LLM 流、文件 I/O、工具执行） |
| Node.js streams | 重要 | LLM 响应和会话事件都是流式的 |
| Git / 终端 | 有帮助 | 你需要 clone 仓库并在本地调试 |
| React / Vue | 不需要 | TUI 不是 web 框架，你不需要前端技能 |
时间预期
| 目标 | 时间 | 学完后你能做到 |
|---|---|---|
| 理解一个模块 | ~30 分钟 | 读完一章并解释该模块做什么 |
| 追踪完整请求 | ~1 周 | 理清一个 prompt 如何从 CLI → Session → Agent → Provider → Tool → 响应 |
| 修改功能 | ~1 个月 | 改变某个行为（如新增权限规则）并让它正常工作 |
| 编写扩展 | 1-3 个月 | 构建插件、自定义工具或向核心贡献 |
8 个章节（按顺序）
基础设施 — 地基层
-
Config · 入门 · ~25 分钟 配置如何加载：六层优先级、Zod schema、JSONC 解析、热重载。从这里开始——其他所有模块都依赖配置。
-
Provider · 入门 · ~20 分钟 模型抽象层：OpenCode 如何通过 Vercel AI SDK 对接 75+ LLM，无需为每个 provider 写 HTTP 客户端。
-
Permission · 中级 · ~25 分钟 安全闸门：三层决策（允许/拒绝/询问）、通配符匹配、级联拒绝、批量批准。
集成层 — 外部协议
-
MCP · 中级 · ~25 分钟 外部工具通道：三种传输层、OAuth 2.0 + PKCE、MCP 工具如何变成 AI SDK 动态工具。
-
LSP · 中级 · ~25 分钟 IDE 级代码理解：Effect Service 架构、30+ 语言服务器定义、诊断能力。
核心 — 执行引擎
- Agent · 高级 · ~30 分钟 配置与执行的分离：Agent 是配置定义，Session 驱动循环。并发控制、错误处理、状态管理。
接口 — 用户接触的入口
-
Command · 高级 · ~20 分钟 命令即配置而非函数：四个来源（内置、Config、MCP prompts、Skills），模板驱动执行。
-
CLI · 高级 · ~25 分钟 入口点：Yargs 命令树、双模设计（TUI worker vs 非交互 run）、SSE 事件桥接。
从哪开始
如果你刚接触代码库：从 Config 开始。
如果你想理解 prompt 如何变成代码编辑：跳到 Agent 并沿调用链回溯。
如果你想用新工具扩展 OpenCode：读 MCP 和 Command。