架构 · 模块 · 文件结构

系统架构深度解析

opencode 采用清晰的五层架构，Monorepo 多包组织，Plan + Build 双 Agent 协作模式。本文详解各层职责、包结构、模块设计、Provider 矩阵与命名约定。

🏗️ 五层分层架构

opencode 的整体设计遵循严格的分层原则，每层只与相邻层交互，保证关注点分离与可测试性。数据流从上到下：用户输入 → Agent 编排 → LLM 推理 → 工具执行 → 技能扩展。

L1
入口层 — Entry Layer
CLI (opencode) · Desktop App (Tauri Beta) · Web Console (SST)
packages/opencode · packages/app · packages/console
↕ 请求 / 响应流
L2
Agent 层 — Agent Layer
Plan Agent (只读分析) + Build Agent (全权执行) · Session 管理
src/agent/ · src/session/
↕ LLM API 调用
L3
Provider 层 — Provider Layer
Claude · GPT · Gemini · Ollama · GitHub Copilot · 任意 OAI 兼容
src/provider/
↕ 工具调用 / 结果
L4
工具执行层 — Tool Layer
文件读写 · Shell 执行 · 代码搜索 · 浏览器 · LSP 集成 · Git 操作
src/tool/
↕ 技能注入 / 上下文扩展
L5
Skill / Plugin 层 — Extension Layer
SKILL.md 技能 · config.json 插件 · AGENTS.md 项目提示 · system.transform 钩子
src/skill/ · .opencode/
📦 核心模块详解
🤖
agent/
src/agent/
Plan Agent 与 Build Agent 的实现。管理 Agent 生命周期、工具权限策略、任务分解与并行执行逻辑。
💾
session/
src/session/
Session 的创建、持久化、恢复与共享。管理对话历史、消息序列化和 session ID 追踪。
🔌
provider/
src/provider/
统一 LLM Provider 适配层。抽象不同 API 格式（Anthropic、OpenAI、Gemini），提供统一的流式/非流式接口。
🔧
tool/
src/tool/
所有工具实现：read_file、write_file、execute_command、search_files、web_fetch、grep、git 操作等。
🧩
skill/
src/skill/
SKILL.md 解析、语义匹配引擎和技能注入器。在 session 启动时扫描并按上下文相关性注入技能。
🖥️
ui/
src/ui/
基于 Ink（React for CLI）的终端 UI。包含聊天界面、输入框、工具输出渲染、主题系统等组件。
⚙️
app/
src/app/
应用入口与配置加载器。解析 opencode.json、.opencode/config.json，合并全局与项目级配置。
📡
sdk/
packages/sdk/
客户端 SDK，供第三方集成 opencode 能力。提供程序化 API 访问 agent、session、tool 等核心功能。
🌐
console/
packages/console/
Web 控制台后端（SST Serverless）。处理 session 共享、团队协作视图，部署于 opencode.ai。
🤖 Plan Agent vs Build Agent

双 Agent 模式是 opencode 区别于单 Agent 工具的核心设计。通过将"分析"与"执行"解耦，显著降低了代码修改的误操作风险，同时提升了复杂任务的计划质量。

🔍 Plan Agent
只读分析 · 方案制定
  • ✓ 访问 read_file、grep、search_files
  • ✓ 深度扫描代码库结构
  • ✓ 理解依赖关系与影响范围
  • ✓ 生成结构化实施步骤
  • ✓ 识别潜在冲突与风险点
  • ✓ 列出需要修改的文件清单
  • ✗ 无写入权限
  • ✗ 无 shell 执行权限
  • ✗ 不调用浏览器工具
🔨 Build Agent
全权执行 · 代码实现
  • ✓ 全工具访问（继承 Plan 工具集）
  • ✓ write_file、create_file、delete_file
  • ✓ execute_command（Shell 执行）
  • ✓ LSP 集成（类型检查、自动补全）
  • ✓ web_fetch（网页内容获取）
  • ✓ git 操作（add、commit、diff）
  • ✓ 按 Plan Agent 输出逐步执行
  • ✓ 验证每步执行结果
💡
在简单任务（如"解释这段代码"）中，Plan Agent 可能被跳过，直接由 Build Agent（以只读模式）响应。双 Agent 模式在复杂多文件修改任务中效果最为显著。
🔌 Provider 支持矩阵
Anthropic
Claude Opus/Sonnet/Haiku
OpenAI
GPT-4o · o1 · o3 · o4-mini
Google
Gemini 2.0 Flash · Pro
Ollama
Llama · Qwen · Mistral (本地)
GitHub Copilot
通过 GitHub token
Azure OpenAI
企业部署 GPT 系列
LM Studio
本地 OpenAI 兼容服务
Groq
高速推理 Llama/Mixtral
Together AI
开源模型云端推理
Fireworks
高性能开源模型
Perplexity
联网搜索增强模型
自定义端点
任意 OpenAI 兼容 API
🔧 工具分类
📂 文件操作
  • read_file
  • write_file
  • create_file
  • delete_file
  • list_directory
  • move_file
🔍 搜索 / 分析
  • search_files (glob)
  • grep (正则搜索)
  • find_in_file
  • semantic_search
  • list_symbols (LSP)
⚡ 执行 / Shell
  • execute_command
  • run_tests
  • git_add / git_commit
  • git_diff / git_log
  • git_status
🌐 网络 / 浏览器
  • web_fetch
  • browser_navigate
  • browser_screenshot
  • browser_click
  • browser_extract
📁 Monorepo 文件结构

opencode 使用 Bun Workspaces 管理 Monorepo，所有包位于 packages/ 目录，共享类型定义与工具函数。

opencode/ # 项目根目录 ├── packages/ │ ├── opencode/ # 主包：CLI + TUI │ │ ├── src/ │ │ │ ├── app/ # 入口 + 配置加载 │ │ │ │ ├── index.ts # CLI 入口点 │ │ │ │ └── config.ts # 配置解析与合并 │ │ │ ├── agent/ # Plan + Build Agent │ │ │ │ ├── plan.ts # Plan Agent 实现 │ │ │ │ ├── build.ts # Build Agent 实现 │ │ │ │ └── loop.ts # Agent 执行循环 │ │ │ ├── session/ # Session 管理 │ │ │ │ ├── session.ts # Session 数据结构 │ │ │ │ ├── store.ts # 持久化存储 │ │ │ │ └── share.ts # 共享发布逻辑 │ │ │ ├── provider/ # LLM Provider 适配 │ │ │ │ ├── anthropic.ts # Anthropic Claude │ │ │ │ ├── openai.ts # OpenAI / 兼容端点 │ │ │ │ ├── google.ts # Google Gemini │ │ │ │ ├── ollama.ts # Ollama 本地模型 │ │ │ │ └── index.ts # Provider 注册表 │ │ │ ├── tool/ # 工具实现集 │ │ │ │ ├── file.ts # 文件读写工具 │ │ │ │ ├── shell.ts # Shell 执行工具 │ │ │ │ ├── search.ts # 代码搜索工具 │ │ │ │ ├── browser.ts # 浏览器工具 │ │ │ │ ├── git.ts # Git 操作工具 │ │ │ │ └── lsp.ts # LSP 集成工具 │ │ │ ├── skill/ # Skill 系统 │ │ │ │ ├── loader.ts # SKILL.md 加载解析 │ │ │ │ ├── matcher.ts # 语义相关性匹配 │ │ │ │ └── injector.ts # System Prompt 注入 │ │ │ └── ui/ # Terminal UI (Ink) │ │ │ ├── App.tsx # 根 React 组件 │ │ │ ├── Chat.tsx # 聊天界面组件 │ │ │ ├── Input.tsx # 输入框组件 │ │ │ └── Theme.tsx # 主题管理 │ │ ├── package.json │ │ └── tsconfig.json │ ├── app/ # Desktop App (Tauri Beta) │ ├── console/ # Web Console (SST) │ ├── function/ # Serverless 函数 │ ├── sdk/ # 客户端 SDK │ └── ui/ # 共享 UI 组件 ├── .opencode/ # 项目级 opencode 配置 │ └── config.json ├── AGENTS.md # 项目 system prompt ├── SKILL.md # 根级技能定义 ├── package.json # Bun Workspaces 根配置 └── bun.lockb # Bun lockfile
🧩 SKILL.md 格式规范

SKILL.md 使用 YAML frontmatter 声明元数据，正文为 Markdown 格式的技能内容。opencode 解析 name 和 description 用于语义匹配。

--- name: frontend-design description: Use when building React/UI components, styling with Tailwind, or designing user interfaces --- # SKILL.md 内容从这里开始 # 整个文件内容会被注入到 system prompt ## 前端开发规范 ### 技术栈 - React 18 + TypeScript - Tailwind CSS（禁止使用内联 style） - shadcn/ui 组件库 ### 组件设计原则 1. 单一职责，每个组件只做一件事 2. Props 接口必须明确类型定义 3. 使用 React.memo 避免不必要重渲染
💡
语义匹配机制：opencode 在 session 启动时，将当前项目的文件结构、已有代码特征与所有技能的 description 进行向量相似度比较，自动注入最相关的技能。用户无需手动 @ 触发，AI 会"感知"应该用哪些技能。
📏 命名约定

opencode 代码库严格遵循以下命名约定，贡献代码时请确保一致性。

PascalCase PlanAgent · BuildAgent · SessionStore 类、Agent、React 组件
camelCase executeCommand · loadSkill · createSession 函数、变量、方法
kebab-case plan-agent.ts · skill-loader.ts 文件名、目录名
UPPER_SNAKE_CASE MAX_TOKENS · DEFAULT_MODEL 常量、环境变量
UPPERCASE.md SKILL.md · AGENTS.md · CLAUDE.md 配置型 Markdown 文件
📝 架构决策说明
决策选择原因
运行时 Bun 原生 TypeScript 执行无需编译、内置包管理器、启动速度快 3x
TUI 框架 Ink (React for CLI) 组件化 UI 设计、React 生态复用、声明式状态管理
Monorepo 工具 Bun Workspaces 零配置多包管理，无需 Turborepo / Nx 等额外工具
Desktop Tauri Rust 壳轻量（相比 Electron），Web 前端复用
双 Agent 模式 Plan + Build 分离分析与写入降低风险，Plan Agent 输出可供用户审查
Plugin 格式 SKILL.md 纯 Markdown 无编程门槛，技能与代码解耦易于维护
opencode · Anomaly / SST · github.com/sst/opencode 深度文档 · 2026-05-22