Tool 调用系统

6. 用户输入到 agent 行动的整体链路

runLoop
  -> SessionTools.resolve
  -> ToolRegistry.tools
  -> ProviderTransform.schema
  -> AI SDK tool({ execute })
  -> model tool-call
  -> Tool.Context with ask/metadata
  -> item.execute
  -> processor.completeToolCall

7. 核心源码逐段讲解

Tool.Context

export type Context = {
  sessionID: SessionID
  messageID: MessageID
  agent: string
  abort: AbortSignal
  metadata(input: { title?: string; metadata?: M }): Effect.Effect<void>
  ask(input: Omit<Permission.Request, "id" | "sessionID" | "tool">): Effect.Effect<void>
}

路径：packages/opencode/src/tool/tool.ts:16-26。

Tool.Def

export interface Def<Parameters extends Schema.Decoder<unknown>, M extends Metadata = Metadata> {
  id: string
  description: string
  parameters: Parameters
  execute(args: Schema.Schema.Type<Parameters>, ctx: Context): Effect.Effect<ExecuteResult<M>>
}

路径：packages/opencode/src/tool/tool.ts:35-45。

wrap 校验和截断

const decoded = yield* decode(args)
const result = yield* execute(decoded as Schema.Schema.Type<Parameters>, ctx)
const truncated = yield* truncate.output(result.output, {}, agent)
return { ...result, output: truncated.content, metadata: { ...result.metadata, truncated: truncated.truncated } }

路径：packages/opencode/src/tool/tool.ts:79-130。

内置工具列表

shell/read/glob/grep/edit/write/task/fetch/todo/search/skill/patch/lsp/plan 在 registry 中初始化。来源：packages/opencode/src/tool/registry.ts:229-275。

包装为 AI SDK tool

tools[item.id] = tool({
  description: item.description,
  inputSchema: jsonSchema(schema),
  execute(args, options) {
    const ctx = context(args, options)
    const result = yield* item.execute(args, ctx)
    return { ...result, attachments: result.attachments?.map(addIds) }
  },
})

路径：packages/opencode/src/session/tools.ts:75-116。

8. 关键 TypeScript 语法复习

• 泛型接口：Def<Parameters extends Schema.Decoder<unknown>>
• 条件类型：InferParameters<T>
• Omit：工具 ask 不让调用方传 session/tool id。
• Record<string, AITool>：工具表。
• dynamic import：加载自定义工具文件。

9-10. 架构思想与协作

• Strategy + Registry + Adapter。
• plugin hook 在定义阶段和执行阶段都可介入。
• ProviderTransform 负责按模型调整 schema。
• Session/Processor 提供 messageID、metadata 和 completeToolCall。

11. mini agent 对应代码

function resolveTools(registry, ctxBase) {
  const tools = {}
  for (const item of registry) {
    tools[item.name] = {
      description: item.description,
      inputSchema: item.schema,
      async execute(args, options) {
        const ctx = makeToolContext(ctxBase, options)
        await ctx.ask({ permission: item.name, patterns: ["*"] })
        return item.execute(args, ctx)
      },
    }
  }
  return tools
}