OpenCode 源码解析 · 第 6 讲
OpenCode 源码解析 第 6 讲：Tool 工具注册与执行——LLM 的"手"与"眼" 基于 dev 分支源码 · 2026-07-12 一、工具系统：LLM 的能力边界 前五讲我们覆盖了 OpenCode 的整体架构、CLI 入口、Session 核心、Server 网络层和 Plugin 插件系统。这一讲进入 Tool 工具注册与执行系统 ——这是 LLM 与外部世界交互的核心通道，也是 OpenCode 最关键的运行时组件之一。 📦 本讲核心文件 packages/opencode/src/tool/tool.ts （183 行）— 工具定义抽象 packages/opencode/src/tool/registry.ts （420 行）— 工具注册表服务 packages/opencode/src/tool/truncate.ts （156 行）— 输出截断与持久化 packages/core/src/tool/tool.ts （162 行）— V2 工具定义与结算 packages/core/src/tool/registry.ts （147 行）— V2 Location 作用域注册表 packages/core/src/tool/builtins.ts （48 行）— 内置工具集合 工具实现文件 28 个，总计约 4825 行 二、工具系统的双层架构 OpenCode 的工具系统分为两层： V1 层 （packages/opencode/src/tool/）面向当前运行时， V2 层 （packages/core/src/tool/）面向下一代 Location 作用域架构。两层并行存在，V2 正在逐步接管核心能力。 V2 Core 层 (packages/core/src/tool/) ⬇️ 提供基础抽象 Tool.make() — 不透明工具值 ⬇️ ApplicationTools — 进程级注册 ⬇️ ToolRegistry — Location 级注册 + 结算 ⬇️ Materialization — 定义导出 + 执行结算 V1 Opencode 层 (packages/opencode/src/tool/) ⬇️ 当前活跃运行时 Tool.define() — 工具定义 ⬇️ ToolRegistry — 内置 + 插件 + 自定义工具 ⬇️ Truncate — 输出截断与持久化 三、V1 工具定义抽象 tool.ts 定义了工具的核心抽象，包括 Def （工具定义）、 Info （工具信息）、 Context （执行上下文）和 ExecuteResult （执行结果）。 1. 工具定义接口 📄 tool.ts (第 55-65 行) export interface Def< Parameters extends Schema.Decoder<unknown> = Schema.Decoder<unknown>, M extends Metadata = Metadata, > { id: string description: string parameters: Parameters jsonSchema?: JSONSchema7 execute(args: Schema.Schema.Type<Parameters>, ctx: Context): Effect.Effect<ExecuteResult<M>> formatValidationError?(error: unknown): string } 设计要点： 每个工具声明 Parameters （Effect Schema 解码器）定义输入参数类型， execute 返回 Effect.Effect 而非 Promise，使工具执行天然嵌入 Effect 错误处理与追踪管线。 2. Tool.define() 工厂函数 📄 tool.ts (第 151-169 行) export function define< Parameters extends Schema.Decoder<unknown>, Result extends Metadata, R, ID extends string = string, >( id: …
阅读全文：OpenCode 源码解析 第 6 讲