以本地
opencode-dev源码快照为对象，参考dg-ai-notes对 Pi-Agent 的“概念 → 源码 → 设计取舍”方式，拆解 OpenCode 的运行时、Session V2、上下文工程、工具系统、Provider、HTTP API、事件回放和多端 UI。
在线阅读：https://hanqing.github.io/opencode-dev-notes/
OpenCode 是一个完整的开源 AI coding agent 产品，而不是只有一个 SDK。它同时处理：
- 多项目 / 多工作区 / 多 worktree 的会话隔离；
- 可恢复、可重放的 Session 与消息投影；
- System Context、Context Epoch、自动压缩和工具输出治理；
- Provider / model catalog / native continuation / AI SDK 的兼容；
- TUI、Web、Desktop、ACP、SDK 和远程 HTTP Server；
- 权限、插件、MCP、LSP、skills、commands、subagents 和发布系统。
因此本拆解不把 OpenCode 简化成“模型 + 工具循环”，而是把它看成一条由持久化事实驱动的产品运行链：
用户输入
→ HttpApi / CLI / TUI / SDK
→ Session 输入箱（durable inbox）
→ Session Runner 在安全边界提升 prompt
→ System Context + Session History
→ LLM provider turn
→ assistant / tool / event 持久化
→ 工具结算与继续运行
→ SSE / sync / SDK / TUI / Web 投影
- 分析对象：
/Users/hanqing/CliX/opencode-dev工作区快照。 - 采集时间：2026-08-02（Asia/Shanghai）。
- 上游仓库：
anomalyco/opencode，默认开发分支为dev。 - 说明：OpenCode 的
dev分支持续演进；文中路径和解释以本地快照为准，源码链接默认指向上游dev分支，可能随上游移动。
| 章节 | 主题 | 关键问题 |
|---|---|---|
| 01 总览 | 产品与运行时全景 | OpenCode 到底由哪些边界组成？ |
| 02 分层 | Workspace packages 与依赖漏斗 | 为什么 Schema、Core、Server、Client 要分开？ |
| 03 Server 与 API | Effect HTTP、Location、SDK | UI 如何调用同一个后端？ |
| 04 Session V2 | 输入箱、Runner、Provider Turn | 一次 prompt 如何变成可恢复的执行？ |
| 05 上下文工程 | System Context、Epoch、History、Compaction | 窗口有限时系统如何保持正确？ |
| 06 LLM 与 Provider | Canonical LLM IR、协议适配、模型选择 | 多供应商差异被隔离在哪里？ |
| 07 工具与安全 | Tool Registry、权限、输出、MCP/LSP | Agent 的“手脚”如何被约束？ |
| 08 事件与回放 | Event V2、投影、SSE、Sync | 为什么 UI 不直接读取执行过程？ |
| 09 持久化与工作区 | SQLite、Project、Location、Snapshot | 数据和运行时状态如何落盘？ |
| 10 多端 UI | TUI、App、Web、Desktop、ACP | 同一 API 如何支撑多个宿主？ |
| 11 扩展与发布 | Config、Agent、Plugin、Skill、构建 | OpenCode 如何变成可扩展产品？ |
| 12 阅读方法 | 源码导航、设计决策、术语表 | 下一次改代码从哪里开始？ |
AGENTS.md：依赖方向、测试、V2 Session 约束。CONTEXT.md：System Context、Context Epoch、Session Drain 等术语。packages/core/src/session/runner/llm.ts：Session V2 的 provider-turn 编排。packages/opencode/src/server/routes/instance/httpapi/api.ts：HTTP API 组合入口。- OpenCode 官方 Agents 文档：用户可见的 agent / permission 语义。
本仓库文档内容采用 CC BY-SA 4.0；OpenCode 源码版权和许可证归上游项目所有。本仓库只复述和引用必要的代码结构，不重新分发 OpenCode 源码。