文章目录项目概览OpenCode 是什么核心特性安装运行宏观架构四层结构模块拆解核心包一览核心模块详解 (packages/opencode/src/)入口与命令会话与对话核心Agent 系统Tool 工具系统Provider 模型适配层Skills 技能系统基础设施辅助功能数据流主线扩展与开发学习 OpenCode 的源码是理解现代 AI 编程代理Coding Agent内部工作原理的绝佳途径。它不仅是热门的开源项目更因其架构清晰、模块化程度高被视为“可读性强的教科书”。官方仓库github.com/anomalyco/opencode说明文档https://opencode.ai/docs/zh-cn/项目概览OpenCode 是什么OpenCode 是一个开源的 AI 编码代理旨在通过自然语言交互协助开发者完成编写、调试、重构等任务。核心特性多模式 Agent内置build默认有完整权限、plan只读用于分析等模式。多平台支持提供 CLI、桌面应用、Web 应用和 VS Code 扩展。多模型兼容通过统一抽象层支持 OpenAI、Anthropic、Google 等 75 家 LLM 提供商。企业级能力包括 Git 集成、项目级配置、插件系统等。安装运行技术栈核心语言TypeScript运行时Bun构建工具Turbo (Monorepo)前端框架SolidJS桌面端Tauri (或 Electron)安装运行快速安装npm i -g opencode-ailatest然后 opencode源码开发bun install bun dev# 非交互模式发送提示词后自动退出bun dev run你的提示词# 指定模型bun dev run-mprovider/model你的提示词# 继续上次会话bun dev run-c你的提示词# 附加文件bun dev run-fpath/to/file分析这个文件# 交互模式bun dev run-i你的提示词常用参数 参数 说明 runmessage直接传提示词-mprovider/model 指定模型-c/--continue继续上次会话-s/--sessionID 指定会话 ID-f/--file附加文件-i/--interactive交互模式--command执行斜杠命令--formatjson JSON 格式输出宏观架构四层结构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核心层数据库DrizzleSQLite、session runner、system-context、provider、plugin、PTY、filesystem 等packages/tui终端 UI基于 OpenTUI SolidJS 的终端交互界面packages/llmLLM 协议层Effect Schema 驱动支持 OpenAI/Anthropic/Gemini/Bedrock 等多协议多 providerpackages/appWeb 应用SolidJS Vitepackages/desktopElectron 桌面应用packages/serverHTTP 服务端packages/web官网Astropackages/sdk/jsJavaScript SDKpackages/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和压缩compactionsession/llm/LLM 请求适配层ai-sdk.tsAI SDK 路径、native-request.ts/native-runtime.ts自研 LLM 包路径、request.ts请求构建session/prompt/各 provider/模式的 system prompt 模板anthropic、gpt、gemini、plan、codex 等 13 个 .txtsession/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/MCPModel 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、profileauth/用户认证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等生命周期钩子。