文章目录
学习 OpenCode 的源码，是理解现代 AI 编程代理（Coding Agent）内部工作原理的绝佳途径。它不仅是热门的开源项目，更因其架构清晰、模块化程度高，被视为"可读性强的教科书"。
项目概览：OpenCode 是什么？
OpenCode 是一个开源的 AI 编码代理，旨在通过自然语言交互协助开发者完成编写、调试、重构等任务。
-
核心特性：
- 多模式 Agent ：内置
build（默认，有完整权限）、plan（只读，用于分析）等模式。 - 多平台支持：提供 CLI、桌面应用、Web 应用和 VS Code 扩展。
- 多模型兼容：通过统一抽象层支持 OpenAI、Anthropic、Google 等 75+ 家 LLM 提供商。
- 企业级能力：包括 Git 集成、项目级配置、插件系统等。
- 多模式 Agent ：内置
-
技术栈：
- 核心语言：TypeScript
- 运行时：Bun
- 构建工具：Turbo (Monorepo)
- 前端框架：SolidJS
- 桌面端：Tauri (或 Electron)
宏观架构：四层结构
OpenCode 采用清晰的客户端-服务器（C/S）架构，自上而下分为四层：
- 客户端层 (Client Layer)：负责用户交互，主要是终端 TUI，也包括桌面应用和 IDE 插件。
- 核心服务层 (Core Service Layer)：OpenCode 的"大脑"，负责任务调度、代理管理和工具执行。
- 扩展层 (Extension Layer)：通过插件系统和配置管理实现功能扩展。
- 模型适配层 (Model Adapter Layer)：通过统一接口对接各种 LLM 提供商。
模块拆解
核心包一览
| 包名 | 职责 |
|---|---|
packages/opencode |
主入口，整合 session、agent、tool、config、MCP、permission 等业务逻辑 |
packages/core |
核心层，数据库（Drizzle+SQLite）、session runner、system-context、provider、plugin、PTY、filesystem 等 |
packages/tui |
终端 UI，基于 OpenTUI + SolidJS 的终端交互界面 |
packages/llm |
LLM 协议层，Effect Schema 驱动，支持 OpenAI/Anthropic/Gemini/Bedrock 等多协议多 provider |
packages/app |
Web 应用（SolidJS + Vite） |
packages/desktop |
Electron 桌面应用 |
packages/server |
HTTP 服务端 |
packages/web |
官网（Astro） |
packages/sdk/js |
JavaScript SDK |
packages/ui |
共享 UI 组件库 |
packages/plugin |
插件系统 |
packages/console |
控制台应用 |
packages/stats |
统计服务 |
核心模块详解 (packages/opencode/src/)
项目的核心逻辑主要集中在 packages/opencode/src/ 目录下。按职责分为以下几层：
入口与命令
| 模块 | 职责 |
|---|---|
index.ts |
主入口 |
cli/ |
CLI 入口，使用 yargs 解析命令，如 run（执行对话）、serve（启动服务）等；包含命令定义、TUI 启动、升级、网络、heap 调试 |
会话与对话核心
| 模块 | 职责 |
|---|---|
session/ |
核心中的核心：session 生命周期、prompt 提交与调度、LLM 调用编排（AI SDK + native 双路径）、消息模型、compaction 压缩、retry/revert、tool 调度、system prompt 组装、reminders 注入；支持会话分叉（fork）、回滚（revert）和压缩（compaction） |
session/llm/ |
LLM 请求适配层：ai-sdk.ts（AI SDK 路径）、native-request.ts/native-runtime.ts（自研 LLM 包路径）、request.ts（请求构建） |
session/prompt/ |
各 provider/模式的 system prompt 模板（anthropic、gpt、gemini、plan、codex 等 13 个 .txt） |
session/processor.ts |
工具调用的状态机（pending → running → completed/error）和 Doom Loop 检测（默认阈值 3 次循环则中断） |
Agent 系统
| 模块 | 职责 |
|---|---|
agent/ |
Agent 定义与协作：primary（主代理）、subagent（子代理）等类型；核心是代理模式工作流，将复杂任务拆解给主、子代理协作完成；不同 Agent 有精细的权限规则，例如对 .env 文件的操作会触发询问 |
agent/prompt/ |
Agent 专属 prompt 模板 |
Tool 工具系统
| 模块 | 职责 |
|---|---|
tool/ |
AI 可调用的"手"和"脚"（40 个文件）：shell、read、write、edit、grep、glob、apply_patch、webfetch、websearch、skill、task、todo、question、plan、lsp、mcp-websearch 等；每个工具都用 Zod 定义参数，并配有权限系统进行访问控制 |
tool/registry.ts |
工具注册表 |
tool/schema.ts |
工具 schema 定义 |
Provider 模型适配层
| 模块 | 职责 |
|---|---|
provider/ |
Provider 注册与调度、认证（auth）、模型状态管理、请求转换（transform）、错误处理；通过 Vercel AI SDK 统一调用不同 LLM，是实现多模型兼容的关键 |
Skills 技能系统
| 模块 | 职责 |
|---|---|
skill/ |
OpenCode 的特色功能 ，执行流程分三步：① 技能发现与注册 ：扫描 .opencode/skill/ 等目录；② LLM 决策调用 ：LLM 根据技能描述选择合适的执行；③ 内容延续生成：基于技能输出结果继续工作 |
基础设施
| 模块 | 职责 |
|---|---|
config/ |
配置系统：agent、command、plugin、TUI、路径、变量解析、markdown 解析 |
storage/ |
本地存储 schema 与持久化 |
server/ |
基于 Hono 框架提供 HTTP 服务，默认监听 4096 端口；路由、SSE 事件推送、mDNS 发现、TUI 事件桥接、项目投影器 |
mcp/ |
MCP（Model Context Protocol）集成：catalog、auth、OAuth 回调 |
plugin/ |
插件加载与集成：GitHub Copilot、OpenAI、Azure、Cloudflare、xAI、Snowflake、TUI 插件、PTY 环境适配 |
permission/ |
权限评估：工具调用的允许/拒绝/询问决策 |
lsp/ |
LSP 客户端：语言服务启动、诊断、代码智能 |
project/ |
项目引导与实例管理：bootstrap、instance 上下文/层/运行时/存储、VCS 检测 |
bus/ |
全局事件总线 |
辅助功能
| 模块 | 职责 |
|---|---|
acp/ |
Agent Client Protocol：外部 agent 协议适配（session、tool、permission、event、profile） |
auth/ |
用户认证 |
ide/ |
IDE 集成（VSCode 等编辑器连接） |
git/ |
Git 操作封装 |
share/ |
Session 分享功能 |
sync/ |
数据同步 |
snapshot/ |
快照管理 |
image/ |
图片处理 |
worktree/ |
Git worktree 管理 |
patch/ |
补丁应用 |
format/ |
代码格式化 |
command/ |
斜杠命令系统 |
question/ |
用户交互式提问 |
background/ |
后台任务 |
数据流主线
Skill 与普通工具的关键区别：
- 普通工具：LLM 调用 → 执行 → 返回结构化结果
- Skill 工具：LLM 调用 → 加载 SKILL.md 内容 → 注入到后续上下文 → LLM 基于技能指令继续工作
skill工具本质上是上下文注入器，改变 LLM 后续行为。而普通工具是执行器，直接产生结果
扩展与开发
OpenCode 设计了四个主要的扩展点，无需修改核心代码即可实现定制：
- 自定义命令 (Custom Commands)
- 自定义代理 (Custom Agents)
- 自定义模式 (Custom Modes)
- 自定义插件 (Custom Plugins)
插件系统基于 @opencode-ai/plugin 包，可以订阅 tool.execute.before/after 等生命周期钩子。