5.2 ToolRegistry：工具注册与发现

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2025-02-17

---

ToolRegistry（tool/registry.ts）管理所有可用工具的注册和发现。工具来源有四种。

5.2.1 内置工具注册表

OpenCode 内置了 20+ 个工具，在 registry.ts 中直接导入：

import { BashTool } from "./bash"
import { EditTool } from "./edit"
import { GlobTool } from "./glob"
import { GrepTool } from "./grep"
import { ReadTool } from "./read"
import { WriteTool } from "./write"
import { TaskTool } from "./task"
import { TodoWriteTool, TodoReadTool } from "./todo"
import { WebFetchTool } from "./webfetch"
import { WebSearchTool } from "./websearch"
import { BatchTool } from "./batch"
import { SkillTool } from "./skill"
import { QuestionTool } from "./question"
import { LspTool } from "./lsp"
import { CodeSearchTool } from "./codesearch"
import { PlanEnterTool, PlanExitTool } from "./plan"
import { ApplyPatchTool } from "./apply_patch"

这些工具覆盖了文件操作、命令执行、代码智能、网络、Agent 协作等全部场景。

5.2.2 从项目目录加载自定义工具

用户可以在项目中创建自定义工具：

const glob = new Bun.Glob("{tool,tools}/*.{js,ts}")
const matches = await Config.directories().then(dirs =>
  dirs.flatMap(dir => [
    ...glob.scanSync({ cwd: dir, absolute: true, followSymlinks: true, dot: true })
  ]),
)

扫描路径包括：

• .opencode/tool/*.ts

• .opencode/tools/*.ts

自定义工具的格式：

// .opencode/tools/my-tool.ts
export default {
  description: "我的自定义工具",
  parameters: z.object({ query: z.string() }),
  async execute(args, ctx) {
    return { title: "查询结果", output: "...", metadata: {} }
  }
}

5.2.3 从 Plugin 加载工具

Plugin 可以通过 tool 字段注册工具：

const plugins = await Plugin.list()
for (const plugin of plugins) {
  for (const [id, def] of Object.entries(plugin.tool ?? {})) {
    custom.push(fromPlugin(id, def))
  }
}

5.2.4 MCP 工具注入

通过 MCP 协议连接的外部 Server 也可以提供工具。这些工具在 Session 的 loop() 函数中被动态注入。MCP 工具的详细机制将在第8章讨论。

5.2.5 fromPlugin() 适配器

Plugin 和自定义工具的定义格式（ToolDefinition）与内部格式（Tool.Info）略有不同。fromPlugin() 负责转换：

function fromPlugin(id: string, def: ToolDefinition): Tool.Info {
  return Tool.define(id, async (initCtx) => {
    const toolDef = typeof def === "function" ? await def(/* context */) : def
    return {
      description: toolDef.description,
      parameters: z.object(toolDef.parameters),
      async execute(args, ctx) {
        const result = await toolDef.execute(args, /* plugin context */)
        return {
          title: result.title ?? id,
          output: result.output,
          metadata: result.metadata ?? {},
        }
      },
    }
  })
}

这确保了无论工具来自哪里——内置、自定义、Plugin 还是 MCP——在 Session 层面看到的都是统一的 Tool.Info 接口。

5.2.6 工具过滤与可见性

不是所有工具都对所有 Agent 可见。在 loop() 函数中，工具列表会根据 Agent 的权限规则过滤：

// 简化版逻辑
const allTools = await ToolRegistry.list()
const filteredTools = allTools.filter(tool => {
  const permission = PermissionNext.evaluate(tool.id, "*", agent.permission)
  return permission.action !== "deny"
})

有些工具被标记为 hidden（如 plan-enter、plan-exit），不会出现在工具列表中，只在特定条件下启用。