opencode 整体架构分析

opencode 整体架构文档opencode 是一个开源的 AI 编程 Agent对标 Claude Code终端 / 桌面 / Web 多端 UI 本地后台服务 多 Provider LLM 接入 插件 / MCP / Skill 扩展生态。本文从结构、流程、上下文、通讯、特色工具五个维度说明其整体设计并重点拆解子代理、skill/MCP、三层记忆与上下文压缩的内部实现。一、整体结构1.1 仓库布局Bun monorepoTurborepo 管理约 60 个包分为三大板块板块包职责引擎schema纯类型与事件定义零逻辑protocolRPC 协议分组对外的 HTTP API 契约core引擎本体会话、Agent、指令、工具、MCP、skill、权限、事件总线aiLLM 客户端抽象多 provider、压缩、tool-history、图像等模态plugin插件公共 API给第三方写插件用util/effect-drizzle-sqlite/http-recorder共享工具、DB 封装、录制回放服务与接入serverHTTP API 服务端持有引擎与数据库client生成的前端客户端代码生成产物禁手改sdk对外 SDK组合 Client/Core/Serverfunction/enterpriseFaaS / 企业部署形态codemodeEffect 原生的沙箱代码执行界面cli命令入口启动 TUI / 无头 / 后台服务tui终端 UIopentui SolidappWeb / 桌面渲染前端desktop桌面壳Electronsession-ui/ui/theme共享组件、组件库、主题 tokengui-extensions编辑器扩展GUI 集成console/stats管理后台 / 统计数据另有services/官网、更新服务与sdks/VS Code 扩展。1.2 分层依赖严格单向schema纯类型零逻辑 ↑ ↑ protocol core ──→ ai ↑ ↑ client ←──────── server ↑ cli / tui / app只准依赖 client schema protocol禁止触碰 core/server依赖纪律AGENTS.md 强制约束UI 层永远通过协议访问引擎不做进程内直连client是生成代码协议或 ServerHttpApi变更后bun run generate重新生成不允许手改运行时依赖方向Schema → Protocol → Server单向Client 可依赖 Schema/Protocolsdk组合三者默认分支v2新分支/worktree/PR 默认对齐v2。1.3 核心领域概念概念说明Session一次会话的聚合根Root所有消息/事件/状态以 Session 为边界跨进程按 ID 定位Agent行为配置系统提示、可用工具、权限、模型、步数上限。分primary独立会话的主代理与subagent子代理两种模式Location工作目录作用域。工具、权限、文件系统、MCP、技能、虚拟环境均按 Location 隔离——同一进程可同时服务多个项目目录互不串扰Project / Workspace项目与工作区的持久化身份管理目录归属与配置层级Job后台任务注册表承载子代理、后台 shell 的启动与崩溃恢复Bus事件总线durable 事件先落库再广播事件溯源Event Sourcing入口State/Transform可重放的注册表模式工具 / 技能 / MCP / Agent 的注册-覆盖-卸载全走同一机制——后注册覆盖先注册卸载自动回退到上一个二、核心流程2.1 一个回合Turn的生命周期用户输入 │ ▼ ① 准入Admissionprompt 先作为 durable 事件写入收件箱session inbox │ —— 先落库再调度崩溃不丢 ▼ ② 唤醒Wake执行协调器被 advisory 唤醒 │ 同 Session 的重复唤醒合并不同 Session 并发执行有写前 claim ▼ ③ Drain进入对应 Location加载历史、Agent、模型、指令、工具 ▼ ④ Step 循环一个 Step 一次逻辑 LLM 调用 │ ├─ 每步前重新加载历史 估算 token超预算先压缩 │ ├─ 组装 system messages tools发起流式调用 │ ├─ 工具调用多个可并发但每个结果 durable 落库后才继续 │ └─ 工具结果回填 → 下一个 Step编排从不交给内存态 tool loop ▼ ⑤ 结算步数用尽 / 无更多工具调用 / 用户打断 → Session 空闲释放写前 claim两个关键机制一个 Step 多次物理尝试physical attempt限流重试、流中断续传、超长触发压缩重建都不消耗新的逻辑步额度assistant 消息 ID 在泛化重试时保持不变。写前执行声明claim进程开始忙一个 Session 时落一条恢复标记正常结束完成/失败/用户打断释放进程死亡则保留。启动时据此恢复中断的顶层会话带每条执行的持久化 attempt 计数。2.2 输入交付词汇steer vs queue新输入有两种交付模式在安全步边界生效steer默认插队转向优先于队列项最多插到第一次转向控制之前在空闲边界 steer 也优先queue排队Session 空闲边界逐条投递空闲边界若无 steer 则每轮投递一条再让运行器决定是否续跑。手动/compact、会话搬迁等控制指令也走同一收件箱构成交付边界。收件箱项在排队与转向之间允许取消/变更新用户输入表态会重置所选 Agent 的步数额度。2.3 子代理流程subagent主 Agent 调用subagent工具时内部实现如下详见第五节校验嵌套深度沿 parentID 向上数祖先depth ≥ 配置上限默认 1即默认不允许嵌套即失败创建独立子 Session记 parentID模型选择优先级显式指定 model Agent 配置的 model 继承父会话 model新子会话注入开场白You are a subagent spawned by another session.不带父上下文——调用方需自带全部背景前台阻塞jobs.block等子会话跑完取子会话最后一条 assistant 文本返回包装进subagent sessionID... statecompleted若父被中断则同时中断并取消子代理后台立即返回statusrunning sessionID批注不要轮询子会话完成后向父会话投递一条synthetic 通知消息subagent sessionID... state...带 source/meta唤醒父级继续去重键childSessionID:startedAt续聊同一子代理传入sessionID且该会话的 parentID 等于当前会话即复用仅追加新 prompt不加开场白期间模型/Agent 可被切换动态清单每次请求前把当前可用的子 Agent 清单 描述拼进工具描述里过滤掉 primary/hidden/被权限拒绝的提示里明确用户点名的陌生名字多半是模型名应传入模型参数。2.4 配置发现流程启动时从全局目录~/.config/opencode兼容~/.claude、~/.agents和项目目录.opencode、.agents、.claude及opencode.json/.jsonc向上查找配置文件与指令文件AGENTS.md 等自带文件 watcher 热重载。配置系统由大约 20 个配置插件组成每个领域Agent / MCP / Skill / Provider …一个用与第三方插件完全相同的机制喂数据。三、上下文Context管理3.1 一次 LLM 请求的上下文构成┌─────────────────────────────────────────┐ │ System 提示 内置指令日期/环境 │ │ 发现的指令AGENTS.md… │ │ Agent 自定义 prompt │ │ 技能清单available_skills│ │ MCP server 指令 │ │ 以上均为 Instructions 组的渲染│ ├─────────────────────────────────────────┤ │ Messages 指令 epoch 基线渲染的初始值 │ │ 历史的 System 更新消息delta │ │ 会话历史用户/助手/工具文本或工具结果│ │ 若压缩过conversation-checkpoint 占首条 │ ├─────────────────────────────────────────┤ │ Tools 内置工具 插件工具 MCP 工具 │ │ 请求时快照注册变化不影响在途请求 │ └─────────────────────────────────────────┘3.2 记忆分层重点全部记忆共用同一个 SQLitedrizzle后端三层差异在作用域与持久性层机制生命周期实现落点短期每次请求对指令源做一次并发read()后拼装上下文内置core/date、core/environment就是典型每次现读的源外加会话消息投影与收件箱待发项单次请求instructions源的实时read()中期指令值增量value delta每类指令源算 SHA-256 哈希只持久化变更的 delta 与新增 blob正文按内容寻址去重存储AGENTS.md 改一个字不复制整文件投影到instruction_state/instruction_entry指令 epoch以压缩为边界推进epoch 基线作为每次请求首条渲染值单会话内跨压缩instruction-state/instruction-entry投影 instruction_blob表长期①durable 事件日志事件溯源所有状态可折叠重放UI 崩溃恢复靠它②KV 存储sqlite 键值库插件storage域的底座get/set/remove/scan③指令文件AGENTS.md / 全局配置跨会话永久注入④ Agent/Skill/MCP 配置本身跨会话永久bus事件日志 kv表 全局/项目指令发现中期记忆的关键设计是值增量每次模型调用前读全部指令源、哈希、只持久化变更的 delta。epoch 只在压缩结束时推进——epoch_start前移、initial_values基线滑动到当前值会话搬迁也保留 epoch让目标会话的指令变更保持时序提交回滚则清除。3.3 上下文压缩Compaction触发auto每步前对完整请求估算 tokenestimateContext达到模型窗口上限默认 10% 余量即压缩紧邻已完成的压缩之后、或 checkpoint 后的首个实测 prompt 之前不压缩overflowprovider 明确拒绝上下文超长且输出尚未开始允许一次机会压缩后重建同一逻辑 Step第二次溢出则失败终止manual用户/compact命令进收件箱投递时触发。两条策略按模型compaction设置选择结构化总结默认用专门的内置compactionAgent把旧历史总结进固定模板模板分节为Objective / Requirements / Decisions / Work State / Next Move / Relevant Files / Important Context采用滚动式合并旧 checkpoint同时保留最近约 15k token 的原文recent。之后每次请求开头加一条conversation-checkpoint含summary与recent-context。原生压缩provider 自带的上下文续接机制trigger / endpoint 两种机制由 AI 客户端层LLMClient.compact/canCompact承载引擎只管路由、重试、用量与 checkpoint 持久化需要稳定的 route provenance。溢出重试预算SHRINK_STEPS [0.7, 0.5, 0.35]——首次溢出前目标就已压到估算值的 70%每次too long 拒绝按上次 × step再次缩小35% 用尽仍失败则终止。EPOCH 联动压缩结束Compaction.Ended写 durable 消息行同时调用advanceEpoch推进指令 epoch。不可变性完整转写永不删除——压缩只改写模型可见的活跃历史所有消息持久化在session_message表历史加载以最近一次完成的压缩为第一条消息但存储记录完整保留。四、通讯4.1 客户端-服务端架构┌──────┐ HTTP RPC ┌──────────┐ 进程内 ┌───────┐ │ TUI │ ──────────→ │ Server │ ──────────→ │ Core │ → LLM Provider │ Web │ (生成客户端)│ (HttpApi)│ (Effect 服务)│(引擎) │ → MCP / FS / Shell │ 桌面 │ ←────────── │ │ │ │ └──────┘ 事件流(SSE) └──────────┘ └───────┘后台服务持有引擎与数据库多端 UI 只是协议消费者协议按领域分组session / message / mcp / skill / tool / config …约 30 组与引擎领域一一对应。4.2 事件体系双通道durable 事件先写 sqlite 再广播带聚合内单调序列号投影器在发布事务内同步执行事件与投影原子提交支持log重放断线后按 watermark 续传UI 刷新 / 崩溃恢复都靠它live 事件流式文本、reasoning、工具进度等瞬态增量只在本实例内广播、不保证重放。4.3 MCP 接入传输两种stdio自研 transport帧上限 16 MiBstderr 排空保留 1000 字符尾关闭时先SIGTERM、2 秒后升级SIGKILL出站帧走有界队列cap 64Streamable HTTPMCP-Session-Id会话 terminate 清理。工具注册server 名做净化非[A-Za-z0-9_-]替换为_工具全名server_tool注册进统一工具注册表与本地工具同构同一 schema / 权限 assert / 输出截断管道MCP 发布ToolsChanged时 debounce 100ms 后整表 reload保持插件覆盖优先级MCP prompts可调用模板带 server 标记 PromptsChangedMCP resources暴露为opencode_list_mcp_resources/opencode_read_mcp_resource两个内置工具底层把resources与resourceTemplates合并成资源目录OAuth / elicitation远程 server 注册为 OAuth 集成按sha1(name\0url)键控凭据变化自动重连elicitation 表单把 JSON-schema 属性映射为表单字段支持外链 URL 模式。4.4 插件体系插件 define({ id, effect })拿到约 20 个 domain 的上下文tool / skill / session / mcp / permission / storage / vcs / worktree / websearch …内置功能本身也是插件subagent、skill、bash 与第三方工具走完全相同的注册路径没有特权代码三种插件源本地 Bun 模块、Node 模块、npm 包工具 / 技能 / MCP / Agent 注册全部走可重放 Transform 机制支持热插拔与覆盖回退。五、特色工具专项实现5.1 subagent —— 子代理派发详见 2.3。要点独立子会话 模型优先级显式 Agent 配置 继承父、前台阻塞 / 后台 synthetic 通知、sessionID续聊可切模型、嵌套深度默认 1、动态子 Agent 清单注入工具描述。会话分类general/explore→ subagent 模式build/compaction/title/summary→ primary 模式。5.2 skill —— 技能加载本质是指令注入不是代码执行——技能目录里的脚本由模型用普通 shell 工具自己跑。发现扫描配置目录里{*.md, **/SKILL.md}解析 frontmatter Markdown 正文技能 id 为目录名SKILL.md或文件名autoinvoke由元数据opencode/autoinvoke决定disable-model-invocation强制为关来源本地目录含watch监听、100ms debounce 重扫与远程下载读远端index.json缓存到~/.cache/skills/hash带.opencode-version版本化原子更新注入读取SKILL.md内容 采样文件清单前 10 个文件渲染成skill_content name...块含# Skill:、正文、基目录、采样提示、skill_files作为技能的结果返回或直接被调用时注入运行清单系统提示里始终维护available_skills清单变更用 diff 增量下发——新增渲染New skills are available…“移除渲染no longer available and must not be used”有变更就把整表作废重发。5.3 question —— 结构化提问向用户发起带选项的表单提问支持多问、多选、推荐项标注用于执行中获取确认/澄清代替模型自问自答或胡乱猜。5.4 patch / file-diff —— 代码修改与差异patch对文件做受控修改含 BOM 处理、格式化器联动、写后校验file-diff生成文件差异视图模型与 UI 双方共用统一 diff 语义。5.5 opencode 工具族 —— 自省与自管理models列出/筛选可用模型、session_rename/session_move改名与搬迁、worktree_create / list / removeGit worktree 管理配合隔离实验。5.6 mcp-resource 工具族opencode_list_mcp_resources/opencode_read_mcp_resource枚举与读取 MCP server 暴露的资源自定义 URI scheme 的文档、记录等适合用户提到一个非本地文件的东西的场景。5.7 基础工具箱文件read / write / edit / glob / grepLocation 作用域内走权限系统shell后台进程管理、输出尾部保留 全量输出落盘引用超长输出不爆上下文webfetch / websearch网页抓取渲染为 Markdown外部内容视为数据与网络搜索所有工具输出统一做模型侧截断默认头尾保留、中间省略标记超长内容进托管存储。六、安全与权限统一权限系统每个工具调用前assertaction resources 可记忆的允许规则用户可放行一次或永久保存Location 作用域的文件系统访问工具拿不到作用域外的路径UI 层与引擎层严格隔离客户端无进程内直连引擎的通道MCP 输入做路径穿越 / URL 校验技能下载有版本化原子更新staging backup 回滚。七、小结opencode 的架构可浓缩为四句话事件溯源 投影一切先落 durable 事件、投影原子提交状态靠折叠崩溃可恢复、UI 可重放。Location 作用域一个进程服务多目录工具 / 权限 / 上下文按目录隔离。一切皆插件配置、内置工具、MCP、技能走同一套可重放注册机制无特权路径。上下文即预算指令是值增量、记忆分三层、压缩双策略 阶梯重试——引擎对模型能看什么的每个字节都有明确账本。