《深入 OpenCode》——目录与纲要
模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 工具: OpenCode 生成日期: 2025-02-17 GitHub: https://github.com/0xtresser/OpenCode-Book
全书结构概览
截止 OpenCode 1.2.5 版本。
本书共分为 五个部分、十八个章节，从基础概念到源码剖析、从核心机制到生态扩展、从理论到实践，系统性地讲解 OpenCode 的架构设计与实现原理。
第一部分：基础篇
第1-3章
背景、安装、整体架构
~1.5万字
第二部分：核心架构篇
第4-8章
Session、Tool、Agent、Provider、MCP
~3万字
第三部分：关键机制篇
第9-12章
权限、Snapshot、事件总线、TUI
~2万字
第四部分：生态篇
第13-16章
插件系统、oh-my-opencode、IDE 扩展
~2万字
第五部分：实践篇
第17-18章
动手实验、设计哲学与未来展望
~1.5万字
第一部分：基础篇
第1章 AI 编程助手的时代背景
引导读者理解 OpenCode 诞生的技术背景和产业语境。
1.1.1 代码补全的演进：从 IntelliSense 到 Copilot
1.1.2 大语言模型（LLM）在软件工程中的应用
1.1.3 "Agentic Coding" 的定义与范式转变
衍生解释：什么是 Agent？与传统的 Chatbot 有什么区别？Agent 的核心能力——工具调用（Tool Use）、规划（Planning）、反思（Reflection）
1.2.1 云端 IDE 型：Cursor、Windsurf
1.2.2 CLI 型：OpenCode、Aider、Codex CLI
1.2.3 嵌入式型：GitHub Copilot、Codeium
1.2.4 各类方案的技术权衡分析
1.3.1 "终端优先"的设计思路
1.3.2 多模型（Multi-Provider）支持的商业与技术考量
1.3.3 开放的插件生态：Plugin、Skill、MCP
1.3.4 本书的目标读者与阅读路线图
第2章 项目结构与开发环境
搭建开发环境，建立对项目整体结构的宏观认知。
2.1.1 克隆仓库与分支策略
2.1.2 Bun 运行时简介与安装
衍生解释：Bun 是什么？与 Node.js 的异同，为什么 OpenCode 选择 Bun 而非 Node
2.1.3 依赖安装与首次构建（
bun install、turbo.json）2.1.4 Nix Flake 环境配置（
flake.nix、flake.lock）
2.2.1 根目录文件解读（
package.json、tsconfig.json、turbo.json、sst.config.ts）2.2.2
packages/目录总览——17 个子包的职责划分衍生解释：什么是 Monorepo？Turborepo 的工作原理
子包路径职责opencodepackages/opencode/核心引擎（CLI + Server + 所有业务逻辑）
apppackages/app/Web 前端（基于 SolidJS）
uipackages/ui/共享 UI 组件库
sdkpackages/sdk/TypeScript SDK（OpenAPI 生成）
pluginpackages/plugin/插件接口类型定义
webpackages/web/官方网站（基于 Astro）
consolepackages/console/云控制台
enterprisepackages/enterprise/企业版功能
containerspackages/containers/Docker 容器化支持
desktoppackages/desktop/桌面应用（基于 Tauri）
functionpackages/function/Serverless 函数
identitypackages/identity/品牌资源
scriptpackages/script/构建脚本工具
slackpackages/slack/Slack 集成
extensionspackages/extensions/IDE 扩展（Zed）
docspackages/docs/文档
utilpackages/util/公共工具函数
2.2.3
sdks/vscode/—— VSCode 扩展2.2.4
infra/—— SST 基础设施即代码
2.3 核心包
packages/opencode/src/的模块地图2.3.1 全部 37 个模块目录概览
模块职责概述agent/Agent 定义、Prompt 模板
session/会话管理、消息处理、Compaction、LLM 调用
tool/所有内置工具的实现
provider/多 LLM Provider 适配层
mcp/Model Context Protocol 客户端实现
permission/权限控制系统
config/配置加载与合并
cli/命令行界面与 TUI
server/HTTP Server 与路由
bus/事件总线
storage/本地持久化
snapshot/Git 快照系统
plugin/插件加载器
skill/Skill 发现与管理
project/项目实例管理
lsp/LSP 客户端
acp/Agent Client Protocol
patch/Diff/Patch 工具
pty/伪终端
shell/Shell 执行环境
scheduler/定时任务调度器
share/会话分享
worktree/Git Worktree 管理
auth/认证系统
command/自定义命令
question/交互式问答
其他
id/、flag/、env/、global/、format/、file/、bun/、util/、installation/2.3.2 模块间依赖关系图（DAG 分析）
2.3.3
Instance状态管理模式详解衍生解释：单例模式（Singleton Pattern）在服务端 TypeScript 中的实践
第3章 整体架构设计
从全局视角理解 OpenCode 的架构分层与数据流动。
3.1.1 为什么 CLI 工具也需要 Server？——内嵌 HTTP Server 的设计动机
3.1.2 Server 的实现：基于 Hono 框架的路由系统（
server/server.ts、server/routes/）3.1.3 API 路由一览：
session、config、project、provider、mcp、permission、pty、file、question3.1.4 Server-Sent Events（SSE）实时推送机制（
server/event.ts）衍生解释：什么是 SSE？与 WebSocket 的区别
3.2.1 用户消息 → Session.chat() → SessionPrompt.prompt() → LLM.stream()
3.2.2 流式响应处理：
SessionProcessor的 Agentic Loop3.2.3 工具调用循环：Tool Call → Execute → Result → Continue
3.2.4 完整的请求-响应时序图
3.3.1
project/模块：instance.ts、project.ts、state.ts、vcs.ts、bootstrap.ts3.3.2
Instance.state()模式——实例级状态隔离的实现3.3.3 多项目并发场景下的状态管理
3.4.1 配置优先级链（由低到高）：
Remote
.well-known/opencode（组织默认值）全局配置
~/.config/opencode/opencode.json自定义配置（
OPENCODE_CONFIG环境变量）项目配置
opencode.json.opencode/目录配置内联配置（
OPENCODE_CONFIG_CONTENT）企业托管配置（最高优先级）
3.4.2 JSONC 解析与配置合并策略（
mergeConfigConcatArrays）3.4.3 Zod Schema 驱动的配置校验
3.4.4 Markdown 格式配置支持（
config/markdown.ts）3.4.5
Flag模块：环境变量与功能开关
第二部分：核心架构篇
第4章 Session（会话）系统
会话是 OpenCode 的核心抽象——理解它就理解了整个对话管理机制。
4.1.1
Session.Info的 Zod Schema 定义id、slug、projectID、directory、parentIDtitle、versiontime（created、updated、compacting、archived）summary（additions、deletions、files、diffs）share（URL）
4.1.2 父子会话关系：
parentID与 Sub-agent 会话4.1.3 会话的 Fork 机制（
getForkedTitle）
4.2.1
MessageV2命名空间详解User消息结构Assistant消息结构（含tokens统计：input、output、cache.read、cache.write）
4.2.2 多模态 Part 类型系统
TextPart：文本内容ReasoningPart：思考链内容（含time.start、time.end）ToolPart：工具调用（含pending、running、completed、error四种状态）FilePart：文件附件
4.2.3 消息版本迁移策略（
message.ts→message-v2.ts）
4.3.1
prompt()方法的完整执行流程4.3.2 系统指令（Instruction）注入机制
AGENTS.md / CLAUDE.md / CONTEXT.md 文件扫描
全局指令 vs 项目级指令 vs 目录级指令
InstructionPrompt.get()的向上查找逻辑（globUp）
4.3.3 消息预处理与格式化
4.4 SessionProcessor：Agentic Loop 的核心
4.4.1 流式处理的状态机
reasoning-start/delta/end→ 思考链处理text-delta→ 文本增量tool-call-start/delta/end→ 工具调用处理
4.4.2 工具执行循环
工具调用 → 权限检查 → 执行 → 结果收集
Doom Loop 检测（
DOOM_LOOP_THRESHOLD = 3）衍生解释：什么是 Doom Loop？AI Agent 陷入无限循环的问题及解决策略
4.4.3 Snapshot 触发时机
4.4.4 Retry 机制（
session/retry.ts）4.4.5 重试与错误恢复策略
4.5.1 为什么需要 Compaction？——Token 限制与上下文溢出问题
衍生解释：LLM 的上下文窗口（Context Window）是什么？Token 计算方式
4.5.2 溢出检测算法：
isOverflow()的实现COMPACTION_BUFFER = 20_000tokenscontext window - reserved的可用空间计算
4.5.3 Prune 策略：工具输出的渐进式清理
PRUNE_MINIMUM = 20_000、PRUNE_PROTECT = 40_000向后遍历、保护最近工具调用的输出
PRUNE_PROTECTED_TOOLS = ["skill"]
4.5.4 Compaction 执行流程：用模型生成摘要替代旧消息
4.5.5 Token 估算工具（
util/token.ts）
4.6.1
SessionStatus：idle、busy、pending状态转换4.6.2
SessionSummary：diff 摘要生成4.6.3 Session 的 Revert 机制（
session/revert.ts）
第5章 Tool（工具）系统
工具是 Agent 与外部世界交互的唯一途径。
5.1.1
Tool.Info接口：id、init、execute5.1.2
Tool.Context上下文：sessionID、messageID、agent、abort、messages、metadata、ask5.1.3
Tool.define()工厂函数——参数校验、自动截断的统一处理5.1.4 工具输出截断机制（
truncation.ts）衍生解释：为什么需要截断？输出过长对 LLM 推理的负面影响
5.2.1 内置工具注册表
5.2.2 从
.opencode/tool/和.opencode/tools/目录加载自定义工具5.2.3 从 Plugin 加载工具
5.2.4 MCP 工具注入
5.2.5
fromPlugin()适配器：统一 Plugin 工具定义到内部Tool.Info格式
5.3.1 文件操作类
read.ts：文件读取（支持行号偏移、限制行数）write.ts：文件写入edit.ts：精确字符串替换编辑multiedit.ts：批量编辑glob.ts：文件模式匹配搜索grep.ts：正则内容搜索ls.ts：目录列表
5.3.2 执行类
bash.ts：Shell 命令执行命令注入防护
超时处理
PTY 集成
batch.ts：批量工具调用（并行执行多个工具）
5.3.3 代码智能类
lsp.ts：LSP 操作集合goto_definition、find_references、document_symbols、workspace_symbolsdiagnostics、prepare_rename、rename
codesearch.ts：代码搜索
5.3.4 网络类
webfetch.ts：URL 内容获取websearch.ts：网络搜索
5.3.5 Agent 协作类
task.ts：子 Agent 任务委托创建子会话（
Session.createwithparentID）Agent 权限过滤
结果返回与 session_id 回传
question.ts：向用户发起交互式提问
5.3.6 辅助类
todo.ts：Todo 列表管理（TodoWriteTool+TodoReadTool）skill.ts：Skill 加载工具plan.ts：Plan 模式进入/退出（PlanEnterTool+PlanExitTool）apply_patch.ts：Diff Patch 应用
5.3.7 工具的 Prompt Template（
.txt文件系统）每个工具对应一个
.txt描述文件模板变量替换机制
5.4.1
ctx.ask()的调用时机与流程5.4.2 权限请求的用户交互流程
第6章 Agent 系统
Agent 是赋予 LLM "性格"和"能力边界"的抽象。
6.1.1
Agent.Info的定义：name、description、mode（primary/subagent/all）model（modelID+providerID）permission（权限规则集）prompt（Agent 专属 Prompt）temperature、topPsteps（最大步数限制）native、hidden、color、variant
6.2.1
buildAgent 的默认权限配置"*": "allow"—— 默认允许所有工具doom_loop: "ask"—— 循环检测external_directory的保护策略.env文件的读取限制
6.2.2 Agent 权限的合并逻辑：默认权限 + 用户权限
6.3.1 标题生成（
prompt/title.txt）6.3.2 摘要生成（
prompt/summary.txt）6.3.3 上下文压缩（
prompt/compaction.txt）6.3.4 探索型 Agent（
prompt/explore.txt）6.3.5 代码生成（
generate.txt）
6.4.1
SystemPrompt.provider()—— 按模型选择 Prompt 模板Claude 系列 →
anthropic.txtGPT 系列 →
beast.txtGemini 系列 →
gemini.txtGPT-5 →
codex_header.txt其他模型 →
qwen.txt（无 Todo 支持版本）
6.4.2
SystemPrompt.environment()—— 运行环境信息注入6.4.3 Prompt 的分层拼接逻辑（
LLM.stream()中的system数组组装）
6.5.1 通过
opencode.json的agent字段定义6.5.2 通过
.opencode/agents/目录定义6.5.3 Plugin 注入 Agent 的机制
第7章 Provider（多模型适配层）
理解 OpenCode 如何统一对接 20+ 个 LLM Provider。
7.1.1 为什么选择
ai(Vercel AI SDK) 作为 LLM 抽象层？衍生解释：Vercel AI SDK 的核心概念——
streamText、generateObject、LanguageModel、Tool7.1.2
LanguageModelV2接口的统一化
7.2.1
BUNDLED_PROVIDERS内置 Provider 列表（20+ 个 SDK）：@ai-sdk/anthropic、@ai-sdk/openai、@ai-sdk/google、@ai-sdk/azure@ai-sdk/amazon-bedrock、@ai-sdk/google-vertex@ai-sdk/xai、@ai-sdk/mistral、@ai-sdk/groq@ai-sdk/deepinfra、@ai-sdk/cerebras、@ai-sdk/cohere@ai-sdk/togetherai、@ai-sdk/perplexity、@ai-sdk/vercel@openrouter/ai-sdk-provider@ai-sdk/gateway@gitlab/gitlab-ai-providerGitHub Copilot（自定义适配）
7.2.2
Provider.getLanguage()—— 从配置解析到 LanguageModel 实例7.2.3 自定义 Provider 注册（动态安装 npm 包）
7.3.1
models.ts—— models.dev 集成模型能力描述（
modalities、context window、max output）模型搜索（
fuzzysort模糊匹配）
7.3.2
Provider.Model类型：id、providerID、api、limit
7.4.1 消息格式标准化（
normalizeMessages）Anthropic 对空消息的限制处理
不同 Provider 的
providerOptions映射（sdkKey）
7.4.2 输出 Token 上限管理（
OUTPUT_TOKEN_MAX = 32_000）7.4.3 Schema 差异化转换
JSON Schema 适配
Tool 定义格式转换
7.5.1
LLM.stream()完整实现解析System Prompt 组装
wrapLanguageModel中间件应用Provider-specific 选项注入
streamText()调用与参数构成
7.5.2 认证体系（
auth/）：API Key、OAuth 两种模式7.5.3 Codex 模式特殊处理
第8章 MCP（Model Context Protocol）
MCP 是 OpenCode 连接外部工具生态的核心协议。
8.1.1 MCP 的设计目标与核心概念
衍生解释：MCP（Model Context Protocol）是什么？它解决什么问题？与 Function Calling 的区别
8.1.2 三种传输方式：Stdio、SSE、StreamableHTTP
8.1.3 MCP 的核心原语：Tool、Resource、Prompt
8.2.1
mcp/index.ts源码解析@modelcontextprotocol/sdk的Client类使用StdioClientTransport：标准输入输出传输SSEClientTransport：Server-Sent Events 传输StreamableHTTPClientTransport：HTTP 流传输
8.2.2 MCP Server 连接管理
连接状态机：
connected/disabled/connecting/errorToolsChanged事件监听与动态工具更新超时处理（
DEFAULT_TIMEOUT = 30_000）
8.2.3 MCP 工具转换为内部 Tool 格式
8.3.1
mcp/auth.ts：认证凭据存储8.3.2
mcp/oauth-provider.ts：OAuth Provider 实现8.3.3
mcp/oauth-callback.ts：OAuth 回调处理
8.4.1
mcpServers配置项结构8.4.2 MCP Resource 模型
第三部分：关键机制篇
第9章 权限控制系统
安全是 AI Agent 的生命线——深入理解 OpenCode 如何控制 Agent 的行为边界。
9.1.1 三种权限动作：
allow、deny、ask9.1.2
PermissionNext.Rule：permission+pattern+action9.1.3
Ruleset：规则集合与合并策略
9.2.1
PermissionNext.evaluate()的实现9.2.2 Wildcard 模式匹配（
util/wildcard.ts）9.2.3
~和$HOME路径展开
9.3.1 Agent 默认权限
9.3.2 用户配置权限
9.3.3 Session 运行时授权
9.3.4
always选项——永久授权记忆
9.4.1
PermissionNext.Request数据结构9.4.2 Permission 请求 → TUI 弹窗 → 用户响应 → 存储决策
9.4.3
arity.ts——权限粒度控制
9.5.1 Bash 工具：命令级权限
9.5.2 Edit/Write 工具：文件路径级权限
9.5.3 Read 工具：
.env文件的特殊保护9.5.4 Task 工具：Sub-agent 调度权限
9.5.5 外部目录访问控制（
external_directory）
第10章 Snapshot 与文件系统
理解 OpenCode 如何安全地管理文件变更与回滚。
10.1.1 设计目标：每次文件变更前创建快照，实现细粒度回滚
10.1.2 独立 Git 仓库策略：
.opencode/snapshot/下的隐藏 Git 目录10.1.3
Snapshot.track()：创建快照的实现10.1.4
Snapshot.restore()：恢复快照的实现10.1.5
Snapshot.diff()：变更对比10.1.6 自动清理机制（
Scheduler定时任务，gc --prune=7.days）
10.2.1
file/index.ts：文件操作核心10.2.2
file/ignore.ts：.gitignore 规则解析10.2.3
file/ripgrep.ts：ripgrep 集成（目录树生成）10.2.4
file/watcher.ts：文件变更监听10.2.5
file/time.ts：文件时间戳管理
10.3.1
patch/index.ts：Diff 补丁的生成与应用10.3.2
apply_patch工具的实现细节
10.4.1 Git Worktree 的概念与应用场景
衍生解释：什么是 Git Worktree？
10.4.2
worktree/index.ts的实现
第11章 事件总线与调度器
理解模块间解耦通信的核心机制。
11.1.1 发布-订阅模式概述
衍生解释：Pub/Sub 模式在软件系统中的应用
11.1.2
BusEvent.define()—— 类型安全的事件定义11.1.3
Bus.publish()—— 事件发布（本地 + 全局两级广播）11.1.4
Bus.subscribe()/Bus.once()—— 事件订阅11.1.5 通配符订阅（
"*"）11.1.6
GlobalBus：跨 Instance 的全局事件通道11.1.7 实例销毁时的事件清理
11.2.1 Session 相关事件：创建、更新、消息、压缩、分享、错误
11.2.2 MCP 相关事件：工具变更、浏览器打开失败
11.2.3 Permission 相关事件：权限请求
11.2.4 Server 相关事件：实例销毁
11.2.5 Config 变更事件
11.3.1
Scheduler.register()—— 任务注册11.3.2 实例级（
instance）vs 全局级（global）任务11.3.3 非阻塞定时器（
timer.unref()）11.3.4 实际应用场景：Snapshot 清理、Session 过期处理
第12章 命令行界面与 TUI
从用户交互角度理解 OpenCode 的前端实现。
12.1.1 入口文件
index.ts→cli/bootstrap.ts12.1.2
cli/cmd/cmd.ts—— 子命令注册12.1.3 各子命令概览：
run、serve、web、auth、mcp、models、session、export、import、generate、github、pr、stats、upgrade、uninstall、acp、agent
12.2.1 基于 Ink（React for CLI）的终端渲染
衍生解释：什么是 Ink？React 渲染器（Renderer）的概念
12.2.2
cli/cmd/tui/app.tsx：TUI 应用入口12.2.3 组件架构：
tui/component/12.2.4 路由系统：
tui/routes/12.2.5 上下文管理：
tui/context/12.2.6 事件系统：
TuiEvent12.2.7 Worker 线程模型（
tui/worker.ts、tui/thread.ts）
12.3.1 基于 SolidJS 的 Web 前端（
packages/app/）衍生解释：SolidJS 与 React 的异同
12.3.2 共享 UI 组件库（
packages/ui/）12.3.3 Web UI 与 Server 的实时通信
12.4.1
run子命令：Pipeline / CI 场景12.4.2
generate子命令：代码生成模式
第四部分：生态篇
第13章 Plugin 系统
理解 OpenCode 的可扩展性核心——Plugin 架构。
13.1.1
@opencode-ai/plugin包的类型定义Plugin类型：(ctx: PluginInput) => Promise<Hooks>PluginInput：client、project、worktree、directory、serverUrl、$Hooks接口：全部生命周期钩子
13.2.1
tool：注册自定义工具13.2.2
config：配置注入13.2.3
chat.params：LLM 调用参数拦截13.2.4
chat.message：消息拦截与修改13.2.5
experimental.chat.messages.transform：消息列表变换13.2.6
event：事件监听13.2.7
tool.execute.before/tool.execute.after：工具执行前后钩子13.2.8
experimental.session.compacting：压缩过程钩子
13.3.1 内置 Plugin：
CodexAuthPlugin、CopilotAuthPlugin、GitlabAuthPlugin13.3.2 npm 包 Plugin：通过
BunProc.install()动态安装13.3.3 本地文件 Plugin：
file://协议加载13.3.4 Plugin 加载的容错处理
13.4.1
@opencode-ai/sdk—— TypeScript 客户端 SDK13.4.2
createOpencodeClient()的使用方式13.4.3 基于 OpenAPI 规范的自动生成
第14章 Skill 系统
Skill 是 Agent 能力的模块化扩展单元。
14.1.1 Skill 文件格式：Markdown
14.1.2 Skill 目录发现机制（
skill/discovery.ts）全局 Skill 目录：
~/.config/opencode/skills/项目 Skill 目录：
.opencode/skills/
14.1.3 Skill 元数据：
name、description、trigger
14.2.1
Skill.dirs()—— 搜索路径构建14.2.2
SkillTool—— 通过skill工具加载 Skill 内容到上下文14.2.3 Skill 与 Agent Prompt 的关系
14.3.1 自定义 Slash Command 机制（
command/模块）14.3.2 Command 模板系统（
command/template/）14.3.3 从
.opencode/commands/目录加载
第15章 oh-my-opencode 深度剖析
作为 OpenCode 生态中最复杂的第三方 Plugin，oh-my-opencode 展示了 Plugin 系统的全部威力。
15.1.1 oh-my-opencode 的定位："Batteries-Included" 增强插件
15.1.2 核心特性概览：多 Agent 编排、后台并行、LSP/AST 工具
15.1.3 目录结构：
src/agents/、src/tools/、src/hooks/、src/features/、src/plugin/、src/mcp/、src/config/
15.2.1
src/index.ts—— Plugin 入口createHooks()、createManagers()、createTools()三大初始化步骤createPluginInterface()构建最终 Hook 接口
15.2.2 配置加载（
plugin-config.ts）全局配置 + 项目配置合并
部分配置容错解析（
parseConfigPartially）JSONC 支持与配置迁移
15.2.3
OhMyOpenCodeConfig配置 Schema（config/schema/）Agent 配置、Category 配置、Skill 配置
Background Task、Browser Automation、tmux
Ralph Loop、Notification、Websearch 等
15.3.1 Agent 分类与角色设计
Agent角色模式成本Sisyphus
主 Agent / 编排者
primary
EXPENSIVE
Oracle
高级技术顾问
subagent
EXPENSIVE
Explore
代码库搜索专家
subagent
FREE
Librarian
外部资源搜索
subagent
CHEAP
Prometheus
任务规划器
subagent
EXPENSIVE
Metis
预规划分析师
subagent
EXPENSIVE
Momus
方案评审专家
subagent
EXPENSIVE
Hephaestus
工匠型执行者
subagent
—
Atlas
项目导航器
subagent
—
Sisyphus Junior
轻量级任务执行
subagent
CHEAP
Multimodal Looker
多模态分析
subagent
—
15.3.2 Agent 动态 Prompt 构建器（
dynamic-agent-prompt-builder.ts）buildKeyTriggersSection()：Key Trigger 段构建buildToolSelectionTable()：工具选择表构建buildExploreSection()/buildLibrarianSection()：搜索 Agent 段构建buildDelegationTable()：委托决策表构建buildCategorySkillsDelegationGuide()：Category + Skill 委托指南buildOracleSection()：Oracle 使用指南categorizeTools()：工具分类
15.3.3 Sisyphus 主 Agent 详解（
agents/sisyphus.ts）行为指令（Phase 0-3）
意图分类（Trivial / Explicit / Exploratory / Open-ended / Ambiguous）
委托协议：6 段结构（TASK / EXPECTED OUTCOME / REQUIRED TOOLS / MUST DO / MUST NOT DO / CONTEXT）
Session 连续性策略
15.3.4 Oracle 咨询 Agent（
agents/oracle.ts）决策框架（Pragmatic Minimalism）
输出冗余控制规范
三层响应结构（Essential / Expanded / Deep）
15.3.5 Prometheus 规划 Agent（
agents/prometheus/）系统 Prompt（
system-prompt.ts）计划生成（
plan-generation.ts）计划模板（
plan-template.ts）面试模式（
interview-mode.ts）高精度模式（
high-accuracy-mode.ts）行为总结（
behavioral-summary.ts）身份约束（
identity-constraints.ts）
15.3.6 Agent Builder（
agents/agent-builder.ts）——统一的 Agent 构建工厂15.3.7 环境上下文注入（
agents/env-context.ts）
15.4.1 工具列表与实现
工具功能ast-grep/AST 级代码搜索与替换
background-task/后台任务管理（获取输出、取消）
call-omo-agent/直接调用 OhMyOpenCode Agent
delegate-task/任务委托
glob/增强版文件模式匹配
grep/增强版内容搜索
hashline-edit/基于行号哈希的精确编辑
interactive-bash/tmux 交互式终端
look-at/多模态文件分析
lsp/LSP 集成工具
session-manager/会话历史管理
skill-mcp/Skill 内嵌 MCP 服务调用
skill/Skill 加载
slashcommand/斜杠命令
task/增强版任务委托
15.4.2 AST-Grep 工具深入分析
衍生解释：什么是 AST（抽象语法树）？AST 级代码搜索的优势
15.4.3 Hashline Edit 的创新设计
15.5.1 Hook 分类
上下文注入类：
directory-agents-injector、directory-readme-injector、rules-injector、compaction-context-injector错误恢复类：
edit-error-recovery、json-error-recovery、anthropic-context-window-limit-recovery、session-recoveryAgent 管理类：
agent-usage-reminder、category-skill-reminder、unstable-agent-babysitter会话管理类：
context-window-monitor、preemptive-compaction、compaction-todo-preserver、session-notification输出控制类：
tool-output-truncator、thinking-block-validator、think-mode任务管理类：
todo-continuation-enforcer、task-reminder、task-resume-info、tasks-todowrite-disabler自动化类：
auto-slash-command、ralph-loop、start-work、stop-continuation-guard环境适配类：
non-interactive-env、interactive-bash-session其他类：
keyword-detector、comment-checker、hashline-read-enhancer、write-existing-file-guard、question-label-truncator、background-notification、delegate-task-retry
15.5.2 核心 Hook 实现剖析
preemptive-compaction：先发制人的上下文压缩context-window-monitor：上下文窗口监控ralph-loop：自我驱动的持续工作循环todo-continuation-enforcer：Todo 任务持续执行保障edit-error-recovery：编辑失败自动恢复unstable-agent-babysitter：不稳定子 Agent 保姆监控
15.6.1 后台 Agent 系统（
features/background-agent/）Spawner：子会话创建器
Manager：后台任务管理器
Poller：任务轮询器
Concurrency 控制
Parent Session 结果通知
15.6.2 Boulder 状态管理（
features/boulder-state/）持久化工作状态的概念
15.6.3 Claude Tasks 系统（
features/claude-tasks/）15.6.4 内置 Skill 系统（
features/builtin-skills/）git-master：Git 操作增强frontend-ui-ux：前端 UI/UX 指导dev-browser：浏览器自动化agent-browser：Agent 浏览器
15.6.5 内置 Command 系统（
features/builtin-commands/）模板系统与 Slash Command
15.6.6 tmux Sub-agent 管理（
features/tmux-subagent/）决策引擎（
decision-engine.ts）网格布局规划（
grid-planning.ts）Pane 管理与分割
子 Agent 的 tmux 可视化
15.6.7 Skill MCP Manager（
features/skill-mcp-manager/）15.6.8 MCP OAuth（
features/mcp-oauth/）15.6.9 Context Injector（
features/context-injector/）
15.7.1
plugin/chat-params.ts：Anthropic Effort 等级注入15.7.2
plugin/chat-message.ts：消息预处理15.7.3
plugin/messages-transform.ts：消息列表变换15.7.4
plugin/event.ts：事件处理15.7.5
plugin/tool-execute-before.ts：工具执行前拦截15.7.6
plugin/tool-execute-after.ts：工具执行后处理15.7.7
plugin/session-agent-resolver.ts：Session-Agent 映射15.7.8
plugin/available-categories.ts：Category 定义15.7.9
plugin/tool-registry.ts：工具注册表
15.8.1 Context7 集成（
mcp/context7.ts）15.8.2 Grep.app 集成（
mcp/grep-app.ts）15.8.3 Web Search 集成（
mcp/websearch.ts）
第16章 IDE 扩展与 ACP
理解 OpenCode 如何与各类 IDE 集成。
16.1.1
sdks/vscode/架构概述16.1.2 与 OpenCode Server 的通信
16.1.3 核心功能实现
16.2.1
packages/extensions/zed/配置16.2.2
extension.toml声明格式
16.3 ACP（Agent Client Protocol）
16.3.1 ACP 协议简介
衍生解释：ACP 与 MCP 的区别——一个面向 Agent 消费者，一个面向 Agent 工具提供者
16.3.2
acp/agent.ts：Agent 接口实现初始化与能力协商
Session 生命周期管理
Prompt 处理与响应
16.3.3
acp/session.ts：ACP Session 到 OpenCode Session 的映射16.3.4
acp/types.ts：类型定义16.3.5 当前限制与未来规划
第五部分：实践篇
第17章 动手实验
通过五个递进式实验，从零到一构建 AI 编程助手的关键组件。
17.1.1 目标：搭建基于 Vercel AI SDK 的终端对话程序
17.1.2 实现步骤：
初始化 Bun 项目
安装
ai和@ai-sdk/openai实现
streamText流式对话添加多轮对话上下文管理
17.1.3 知识点：LLM API 调用、流式处理、消息历史
17.2 实验二：为 CLI 工具添加 Tool Use 能力
17.2.1 目标：实现文件读写和 Shell 执行三个工具
17.2.2 实现步骤：
定义 Tool Schema（Zod）
实现 Tool 执行函数
集成到
streamText的tools参数实现 Agentic Loop（工具调用 → 执行 → 结果回传 → 继续对话）
17.2.3 知识点：Function Calling、工具定义、循环调用
17.3.1 目标：使用
@modelcontextprotocol/sdk创建自定义 MCP Server17.3.2 实现步骤：
创建 Stdio Transport Server
注册自定义 Tool（如 GitHub API 搜索）
将 MCP Server 配置到 OpenCode 中测试
17.3.3 知识点：MCP 协议实现、Server/Client 架构
17.4.1 目标：实现一个带 Hook 和自定义工具的 Plugin
17.4.2 实现步骤：
使用
@opencode-ai/plugin类型定义实现
chat.messageHook（自动注入项目规范）实现
tool.execute.beforeHook（操作日志记录）注册自定义工具
本地调试与发布
17.4.3 知识点：Plugin 接口、Hook 生命周期、工具注册
17.5.1 目标：模仿 oh-my-opencode 的核心架构，实现主 Agent + 子 Agent 编排
17.5.2 实现步骤：
设计 Agent 角色与 Prompt
实现 Task 工具（子会话创建与管理）
实现后台并行 Agent 调度
添加 Session 持续性（session_id 回传）
17.5.3 知识点：Agent 编排、并行执行、会话管理
第18章 设计哲学、最佳实践与未来展望
总结全书，提炼设计智慧，展望未来方向。
18.1.1 "一切皆 Namespace" —— TypeScript Namespace 的大量使用
18.1.2 "Instance State" 模式 —— 无 class 的状态管理
18.1.3 "Zod 驱动" —— Schema-first 的数据模型
18.1.4 "Txt 模板" —— Prompt 与代码分离
18.1.5 "嵌入式 Server" —— CLI 工具的 Web 化趋势
18.2.1 "Prompt Engineering as Code" —— 将 Prompt 工程化
18.2.2 "Hook 即策略" —— 53 个 Hook 的设计哲学
18.2.3 "Agent 人格化" —— 从希腊神话到工程实践
18.2.4 "防御式编程" —— 错误恢复与兜底策略
18.3.1 Prompt 工程最佳实践
System Prompt 的分层架构
按模型差异化适配
工具描述的重要性
18.3.2 安全性最佳实践
权限最小化原则
文件操作的沙箱化
Snapshot 作为安全网
18.3.3 性能优化
上下文窗口管理（Compaction + Prune）
Token 节约策略
并行工具执行
18.3.4 用户体验
流式响应的重要性
进度可见性（Todo、Status）
错误恢复的透明度
18.4.1 从 CLI 到多端（Desktop / Web / IDE）
18.4.2 多 Agent 协作的演进方向
18.4.3 ACP 生态的潜力
18.4.4 AI Agent 安全性的未解之题
18.4.5 从工具到同事——AI 编程助手的终极形态
附录
附录 A：OpenCode 配置参考手册
完整的
opencode.json配置项列表与说明
附录 B：oh-my-opencode 配置参考手册
完整的
oh-my-opencode.json配置项列表与说明
附录 C：内置工具 API 参考
每个内置工具的参数、返回值、权限要求
附录 D：MCP 协议快速参考
核心概念、传输方式、消息格式
附录 E：术语表
LLM、Token、Context Window、Function Calling、Agent、MCP、ACP、LSP、AST、SSE、Monorepo、TUI 等术语释义
附录 F：推荐阅读与资源
官方文档链接
相关论文与文章
开源项目推荐
源码文件索引
本书涉及的关键源码文件速查表
第4章 Session
session/index.ts、session/processor.ts、session/llm.ts、session/compaction.ts、session/system.ts、session/instruction.ts、session/prompt.ts、session/message-v2.ts、session/retry.ts、session/revert.ts、session/status.ts、session/summary.ts、session/todo.ts
第5章 Tool
tool/tool.ts、tool/registry.ts、tool/truncation.ts、tool/bash.ts、tool/edit.ts、tool/read.ts、tool/write.ts、tool/glob.ts、tool/grep.ts、tool/task.ts、tool/lsp.ts、tool/webfetch.ts、tool/websearch.ts、tool/todo.ts、tool/skill.ts、tool/plan.ts、tool/batch.ts、tool/question.ts、tool/apply_patch.ts、tool/multiedit.ts、tool/codesearch.ts
第6章 Agent
agent/agent.ts、agent/prompt/*.txt、session/prompt/*.txt
第7章 Provider
provider/provider.ts、provider/transform.ts、provider/models.ts、provider/auth.ts、provider/error.ts、provider/sdk/copilot/
第8章 MCP
mcp/index.ts、mcp/auth.ts、mcp/oauth-provider.ts、mcp/oauth-callback.ts
第9章 Permission
permission/next.ts、permission/index.ts、permission/arity.ts
第10章 Snapshot
snapshot/index.ts、file/index.ts、file/ignore.ts、file/ripgrep.ts、file/watcher.ts、patch/index.ts、worktree/index.ts
第11章 Bus
bus/index.ts、bus/bus-event.ts、bus/global.ts、scheduler/index.ts
第12章 CLI/TUI
cli/bootstrap.ts、cli/cmd/*.ts、cli/cmd/tui/app.tsx、cli/cmd/tui/component/、cli/cmd/tui/routes/
第13章 Plugin
plugin/index.ts、plugin/codex.ts、plugin/copilot.ts
第14章 Skill
skill/index.ts、skill/skill.ts、skill/discovery.ts、command/index.ts
第15章 oh-my-opencode
oh-my-opencode/src/index.ts、agents/*.ts、tools/*、hooks/*、features/*、plugin/*、mcp/*、config/*
第16章 IDE/ACP
acp/agent.ts、acp/session.ts、acp/types.ts、sdks/vscode/、extensions/zed/
Last updated