OpenCode 学习路径指南

从入门到精通的系统学习路线。

🎯 学习目标

通过本指南，你将：

✅ 理解 OpenCode 的整体架构
✅ 掌握核心模块的工作原理
✅ 能够扩展或贡献代码

📚 准备工作：快速入门

在开始之前，建议先阅读：👉 快速入门指南 ⏱️ 30分钟

快速入门会帮你：

✅ 理解 OpenCode 是什么
✅ 运行你的第一次对话
✅ 掌握核心概念

📊 学习路径选择

根据你的目标选择路径：

目标	推荐路径	预计时间	难度
快速了解	路径 A	1-2 小时	⭐
深入开发	路径 B	1-2 天	⭐⭐⭐
扩展生态	路径 C	半天	⭐⭐

路径 A: 快速了解 ⏱️ 1-2 小时 ⭐

适合: 产品经理、技术负责人、评估者

Step 1: 系统全景 (15 min)

📖 阅读快速入门指南 ⏱️ 30min - 先从这里开始
🖼️ 查看系统架构图
📖 阅读 Monorepo 结构解析 ⏱️ 15min

Step 2: 核心流程 (45 min)

🧠 阅读 Agent 生命周期 ⏱️ 20min
⚡ 阅读状态同步机制 ⏱️ 15min
🔌 阅读插件加载流程 ⏱️ 10min

Step 3: 协议理解 (30 min)

📖 阅读 ACP 协议 ⏱️ 15min - 编辑器集成
📖 阅读 MCP 协议 ⏱️ 15min - 工具扩展
📖 阅读 LSP 协议 ⏱️ 10min - 代码智能

Step 4: 动手体验 (30 min)

# 安装并运行
curl -fsSL https://opencode.ai/install | bash
opencode run
 
# 尝试几个简单的任务
- 创建一个文件
- 搜索代码
- 查看会话历史

路径 B: 深入开发 ⏱️ 1-2 天 ⭐⭐⭐

适合: 想要贡献代码或二次开发的工程师

Phase 1: 核心理解 (3-4 小时)

1.1 核心 Agent ⏱️ 2小时

📖 packages/opencode ⏱️ 60min - 必读，核心中的核心
- 先读 Module 0: 架构总览
- 再读 Module 1-4: 系列课程
📖 内部模块: Agent 定义 ⏱️ 30min
📖 内部模块: 配置系统 ⏱️ 30min
📖 内部模块: 权限系统 ⏱️ 30min

1.2 通信层 ⏱️ 1.5小时

📖 packages/sdk ⏱️ 45min
- 理解 OpenAPI 生成
- 理解 SSE 事件流
📖 内部模块: 事件总线 ⏱️ 15min
📖 内部模块: Session ⏱️ 30min

Phase 2: 客户端实现 (3-4 小时)

2.1 Web App ⏱️ 2小时

📖 packages/app ⏱️ 60min
📖 packages/ui ⏱️ 60min

2.2 Desktop ⏱️ 1小时

📖 packages/desktop ⏱️ 60min

2.3 编辑器集成 ⏱️ 1小时

📖 VS Code 扩展 ⏱️ 30min
📖 ACP 协议 ⏱️ 30min - 已在 Phase 1 阅读过

Phase 3: 关键机制 (2-3 小时)

按优先级阅读：

⭐⭐⭐⭐⭐ 📖 快照系统 ⏱️ 30min - Git 集成
⭐⭐⭐⭐ 📖 技能系统 ⏱️ 20min - 指令模板
⭐⭐⭐⭐ 📖 终端模拟 ⏱️ 30min - PTY 管理
⭐⭐⭐ 📖 分享功能 ⏱️ 20min - 云端同步
⭐⭐⭐ 📖 工作树 ⏱️ 20min - 沙箱环境

Phase 4: 动手实践 (可选，2-3小时)

# 克隆并运行
git clone https://github.com/anomalyco/opencode.git
cd opencode
bun install
bun dev
 
# 尝试以下任务
1. 添加一个新的内置工具
2. 创建一个自定义 Agent
3. 修改 Agent 的 System Prompt
4. 调试一个 Session 的执行流程

Phase 5: 实战案例 (可选，3-4小时)

📖 浏览 Cookbook 并完成至少2个案例：

路径 C: 扩展生态 ⏱️ 半天 ⭐⭐

适合: 想要开发插件或集成的开发者

Step 1: 插件基础 (30 min)

📖 packages/plugin ⏱️ 20min - 插件接口定义
📖 插件加载流程 ⏱️ 10min

Step 2: 实战案例 (60 min)

📖 packages/slack ⏱️ 30min - Slack Bot 实现
📖 GitHub Action ⏱️ 30min - CI/CD 集成

Step 3: 核心扩展点 (30 min)

📖 技能系统 (SKILL.md) ⏱️ 15min
📖 分享功能 ⏱️ 15min

Step 4: 开发你的插件 (60 min)

参考 Cookbook 完成第一个插件：

// my-plugin.ts
import { z } from "zod"
 
export default async function plugin({ client, $ }) {
  return {
    tool: {
      "my-tool": {
        description: "我的自定义工具",
        parameters: z.object({ input: z.string() }),
        async execute({ input }) {
          return `处理结果: ${input}`
        }
      }
    }
  }
}

Step 5: 调试和测试 (30 min)

# 本地测试插件
opencode run --plugin ./my-plugin.ts
 
# 测试工具调用
> 使用 my-tool 处理 "Hello World"

📚 完整文档索引

按模块分类

类别	文档列表
入门	快速入门, FAQ
架构	系统架构, Monorepo结构
Packages	opencode, sdk, app, desktop, ui, plugin, console, web, slack, extensions, util, function
Internals	agent, permission, snapshot, skill, share, pty, bus, config, project, utilities
Concepts	ACP协议, MCP协议, LSP协议
Flows	agent生命周期, 状态同步, 插件加载, 工具执行, 权限流程, 快照回滚, 错误处理
Integrations	VS Code, GitHub Action
Cookbook	创建自定义Agent, 集成MCP Server, 调试会话

按优先级排序

优先级	文档	理由
⭐⭐⭐⭐⭐	快速入门	必读第一站
⭐⭐⭐⭐⭐	opencode	核心中的核心
⭐⭐⭐⭐	agent, sdk	理解 Agent 和通信
⭐⭐⭐	config, permission	配置和安全
⭐⭐⭐	fast-started	快速上手
⭐⭐	plugin, skill	扩展能力
⭐	其他辅助模块	按需阅读

🎯 学习进度追踪

使用以下 Checklist 追踪你的学习进度：

路径 A: 快速了解

路径 B: 深入开发

路径 C: 扩展生态

🛠️ 实践建议

阅读代码入口: 从 packages/opencode/src/index.ts 开始
运行项目: bun dev 并观察日志输出
设置断点: 在关键函数处暂停，理解执行流程
记录笔记: 将理解记录到 docs/ 目录
动手实验: 在 examples/ 创建测试脚本
查看 Cookbook: 实战案例是最好的老师
遇到问题: 查阅 FAQ 或在社区提问

📞 获取帮助

📖 文档: 完整文档索引
❓ 常见问题: FAQ
🍳 实战案例: Cookbook
💬 社区: GitHub Discussions