Tool 系统实现机制

export interface Info<Parameters extends z.ZodType = z.ZodType, M extends Metadata = Metadata> {
  id: string // 工具唯一标识符
  init: (ctx?: InitContext) => Promise<{
    description: string // 工具描述（传递给 LLM）
    parameters: Parameters // Zod 参数 schema
    execute(
      args: z.infer<Parameters>, // 解析后的参数
      ctx: Context<Metadata>, // 执行上下文
    ): Promise<{
      title: string // 返回结果的标题
      metadata: M // 元数据
      output: string // 文本输出
      attachments?: MessageV2.FilePart[] // 附件文件
    }>
    formatValidationError?(error: z.ZodError): string // 自定义错误格式化
  }>
}

export type Context<M extends Metadata = Metadata> = {
  sessionID: string // 当前会话 ID
  messageID: string // 当前消息 ID
  agent: string // 当前 Agent 名称
  abort: AbortSignal // 中止信号
  callID?: string // 工具调用 ID
  extra?: { [key: string]: any } // 额外上下文数据

  // 更新元数据
  metadata(input: { title?: string; metadata?: M }): void

  // 权限检查
  ask(input: Omit<PermissionNext.Request, "id" | "sessionID" | "tool">): Promise<void>
}

export interface Metadata {
  [key: string]: any // 灵活的键值对
}

export interface InitContext {
  agent?: Agent.Info // 初始化时提供的 Agent 信息
}

export function define<Parameters extends z.ZodType, Result extends Metadata>(
  id: string, // 工具 ID
  init: Info<Parameters, Result>["init"] | Awaited<ReturnType<Info<Parameters, Result>["init"]>>,
): Info<Parameters, Result>

export const MyTool = Tool.define("my-tool", async (initCtx) => ({
  description: "Tool description for LLM",
  parameters: z.object({
    param1: z.string().describe("Parameter description"),
  }),
  async execute(args, ctx) {
    // 工具执行逻辑
    return {
      title: "Result title",
      metadata: {},
      output: "Result output",
    }
  },
})

// packages/opencode/src/tool/tool.ts:53-84
init: async (initCtx) => {
  const toolInfo = init instanceof Function ? await init(initCtx) : init
  const execute = toolInfo.execute

  // 包装 execute 函数以添加参数验证和输出截断
  toolInfo.execute = async (args, ctx) => {
    // 参数验证
    try {
      toolInfo.parameters.parse(args)
    } catch (error) {
      if (error instanceof z.ZodError && toolInfo.formatValidationError) {
        throw new Error(toolInfo.formatValidationError(error), { cause: error })
      }
      throw new Error(
        `The ${id} tool was called with invalid arguments: ${error}.`,
        { cause: error },
      )
    }

    // 执行工具
    const result = await execute(args, ctx)

    // 输出截断
    if (result.metadata.truncated !== undefined) {
      return result
    }
    const truncated = await Truncate.output(result.output, {}, initCtx?.agent)
    return {
      ...result,
      output: truncated.content,
      metadata: {
        ...result.metadata,
        truncated: truncated.truncated,
        ...(truncated.truncated && { outputPath: truncated.outputPath }),
      },
    }
  }

  return toolInfo
},

// 步骤：
1. 参数验证（Zod schema parse）
2. 调用原始 execute 函数
3. 输出截断（如果工具未自己处理）
4. 返回结果

export const state = Instance.state(async () => {
  const custom = [] as Tool.Info[]
  const glob = new Bun.Glob("{tool,tools}/*.{js,ts}")

  // 1. 加载自定义工具（tool.js, tools.js）
  for (const dir of await Config.directories()) {
    for await (const match of glob.scan({ cwd: dir, ... })) {
      const namespace = path.basename(match, path.extname(match))
      const mod = await import(match)
      for (const [id, def] of Object.entries<ToolDefinition>(mod)) {
        custom.push(fromPlugin(id === "default" ? namespace : `${namespace}_${id}`, def))
      }
    }
  }

  // 2. 加载插件工具
  const plugins = await Plugin.list()
  for (const plugin of plugins) {
    for (const [id, def] of Object.entries(plugin.tool ?? {})) {
      custom.push(fromPlugin(id, def))
    }
  }

  return { custom }
})

function fromPlugin(id: string, def: ToolDefinition): Tool.Info {
  return {
    id,
    init: async (initCtx) => ({
      parameters: z.object(def.args), // 将定义转换为 Zod schema
      description: def.description,
      execute: async (args, ctx) => {
        const result = await def.execute(args as any, ctx)

        // 应用输出截断
        const out = await Truncate.output(result, {}, initCtx?.agent)
        return {
          title: "",
          output: out.truncated ? out.content : result,
          metadata: {
            truncated: out.truncated,
            outputPath: out.truncated ? out.outputPath : undefined,
          },
        }
      },
    }),
  }
}

export async function register(tool: Tool.Info) {
  const { custom } = await state()
  const idx = custom.findIndex((t) => t.id === tool.id)

  if (idx >= 0) {
    custom.splice(idx, 1, tool) // 替换现有工具
    return
  }

  custom.push(tool) // 添加新工具
}

export async function all(): Promise<Tool.Info[]> {
  const custom = await state().then((x) => x.custom)
  const config = await Config.get()

  return [
    InvalidTool, // 总是第一个（错误处理）

    // 基于客户端类型过滤
    ...(["app", "cli", "desktop"].includes(Flag.OPENCODE_CLIENT) ? [QuestionTool] : []),

    // 核心工具
    BashTool,
    ReadTool,
    GlobTool,
    GrepTool,
    EditTool,
    WriteTool,
    TaskTool,
    WebFetchTool,
    TodoWriteTool,
    TodoReadTool,
    WebSearchTool,
    CodeSearchTool,
    SkillTool,
    ApplyPatchTool,

    // 基于实验性标志过滤
    ...(Flag.OPENCODE_EXPERIMENTAL_LSP_TOOL ? [LspTool] : []),
    ...(config.experimental?.batch_tool === true ? [BatchTool] : []),
    ...(Flag.OPENCODE_EXPERIMENTAL_PLAN_MODE && Flag.OPENCODE_CLIENT === "cli" ? [PlanExitTool, PlanEnterTool] : []),

    // 自定义和插件工具
    ...custom,
  ]
}

export async function ids() {
  return all().then((x) => x.map((t) => t.id))
}

export async function tools(model: { providerID: string; modelID: string }, agent?: Agent.Info) {
  const tools = await all()

  const result = await Promise.all(
    tools
      .filter((t) => {
        // 1. 过滤 websearch/codesearch（仅对特定提供商启用）
        if (t.id === "codesearch" || t.id === "websearch") {
          return model.providerID === "opencode" || Flag.OPENCODE_ENABLE_EXA
        }

        // 2. 过滤 patch/edit/write（基于模型）
        const usePatch =
          model.modelID.includes("gpt-") && !model.modelID.includes("oss") && !model.modelID.includes("gpt-4")
        if (t.id === "apply_patch") return usePatch
        if (t.id === "edit" || t.id === "write") return !usePatch

        return true
      })
      .map(async (t) => {
        // 3. 初始化每个工具（传递 Agent 上下文）
        using _ = log.time(t.id)
        return {
          id: t.id,
          ...(await t.init({ agent })),
        }
      }),
  )

  return result
}

export type Context<M extends Metadata = Metadata> = {
  // ...

  // 权限检查方法
  ask(input: Omit<PermissionNext.Request, "id" | "sessionID" | "tool">): Promise<void>
}

async execute(params, ctx) {
  // 检查权限
  await ctx.ask({
    permission: "read",
    patterns: ["*.ts", "*.js"],
    always: ["package.json"],
  })

  // 执行工具逻辑
  // ...
}

const result = await execute(args, ctx)

// 如果工具未设置 metadata.truncated，则自动截断
if (result.metadata.truncated !== undefined) {
  return result
}

const truncated = await Truncate.output(result.output, {}, initCtx?.agent)
return {
  ...result,
  output: truncated.content,
  metadata: {
    ...result.metadata,
    truncated: truncated.truncated,
    ...(truncated.truncated && { outputPath: truncated.outputPath }),
  },
}

async execute(params, ctx) {
  // 工具自己处理截断
  const truncated = await Truncate.output(largeOutput, {}, agent)

  return {
    title: "Result",
    metadata: {
      truncated: truncated.truncated,  // 👈 标记为已处理
      outputPath: truncated.outputPath,
    },
    output: truncated.content,
  }
}

try {
  toolInfo.parameters.parse(args)
} catch (error) {
  if (error instanceof z.ZodError && toolInfo.formatValidationError) {
    throw new Error(toolInfo.formatValidationError(error), { cause: error })
  }

  throw new Error(`The ${id} tool was called with invalid arguments: ${error}.`, { cause: error })
}

export const MyTool = Tool.define("my-tool", async (initCtx) => ({
  description: "Tool description",
  parameters: z.object({
    /* ... */
  }),

  // 自定义错误格式化
  formatValidationError(error: z.ZodError): string {
    return `参数错误：${error.message}\n请检查：${error.errors.map((e) => e.message).join(", ")}`
  },

  async execute(args, ctx) {
    // ...
  },
}))

// packages/opencode/src/tool/my-tool.ts
export const MyTool = Tool.define("my-tool", {
  description: "My custom tool",
  parameters: z.object({
    input: z.string(),
  }),
  async execute(args, ctx) {
    return {
      title: "Result",
      metadata: {},
      output: "Processed: " + args.input,
    }
  },
})

import { ToolRegistry } from "@/tool/registry"
import { Tool } from "@/tool/tool"

const customTool: Tool.Info = {
  id: "custom-tool",
  init: async () => ({
    description: "Dynamic tool",
    parameters: z.object({
      /* ... */
    }),
    async execute(args, ctx) {
      return { title: "", metadata: {}, output: "" }
    },
  }),
}

await ToolRegistry.register(customTool)

const allTools = await ToolRegistry.all()
console.log(`Total tools: ${allTools.length}`)

const toolIds = await ToolRegistry.ids()
console.log(`Tool IDs: ${toolIds.join(", ")}`)

const filteredTools = await ToolRegistry.tools({ providerID: "anthropic", modelID: "claude-3-5-sonnet" }, agent)
console.log(`Available tools: ${filteredTools.length}`)

parameters: z.object({
  path: z.string().describe("File path to read"),
  offset: z.number().optional().describe("Start line number"),
  limit: z.number().optional().describe("Number of lines to read"),
})

async execute(params, ctx) {
  await ctx.ask({
    permission: "read",
    patterns: [params.filepath],
  })

  // 执行操作
}

return {
  title: "File processed",
  metadata: {
    filepath: params.path,
    size: stats.size,
    lines: content.split("\n").length,
    truncated: false,
  },
  output: content,
}

formatValidationError(error: z.ZodError): string {
  const issues = error.errors.map(e =>
    `${e.path.join('.')} - ${e.message}`
  ).join('\n')
  return `Invalid parameters:\n${issues}\n\nExample usage:\n{...}`
}