V2 Core 层 (packages/core/src/tool/)

⬇️ 提供基础抽象

Tool.make() — 不透明工具值

⬇️

ApplicationTools — 进程级注册

⬇️

ToolRegistry — Location 级注册 + 结算

⬇️

Materialization — 定义导出 + 执行结算

V1 Opencode 层 (packages/opencode/src/tool/)

⬇️ 当前活跃运行时

Tool.define() — 工具定义

⬇️

ToolRegistry — 内置 + 插件 + 自定义工具

⬇️

Truncate — 输出截断与持久化

📄 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
}

📄 tool.ts (第 151-169 行)

export function define<
  Parameters extends Schema.Decoder<unknown>,
  Result extends Metadata,
  R,
  ID extends string = string,
>(
  id: ID,
  init: Effect.Effect<Init<Parameters, Result>, never, R>,
): Effect.Effect<Info<Parameters, Result>, never, R | Truncate.Service | Agent.Service> & { id: ID } {
  return Object.assign(
    Effect.gen(function* () {
      const resolved = yield* init
      const truncate = yield* Truncate.Service
      const agents = yield* Agent.Service
      return { id, init: wrap(id, resolved, truncate, agents) }
    }),
    { id },
  )
}

📄 tool.ts (第 99-149 行)

function wrap<Parameters extends Schema.Decoder<unknown>, Result extends Metadata>(
  id: string,
  init: Init<Parameters, Result>,
  truncate: Truncate.Interface,
  agents: Agent.Interface,
) {
  return () =>
    Effect.gen(function* () {
      const toolInfo = typeof init === "function" ? { ...(yield* init()) } : { ...init }
      // 编译一次解析器闭包，避免每次调用重新分配
      const decode = Schema.decodeUnknownEffect(toolInfo.parameters)
      const execute = toolInfo.execute
      toolInfo.execute = (args, ctx) => {
        return Effect.gen(function* () {
          const decoded = yield* decode(args).pipe(
            Effect.mapError((error) =>
              new InvalidArgumentsError({
                tool: id,
                detail: toolInfo.formatValidationError
                  ? toolInfo.formatValidationError(error)
                  : String(error),
              }),
            ),
          )
          const result = yield* execute(decoded, ctx)
          // 自动截断输出
          const agent = yield* agents.get(ctx.agent)
          const truncated = yield* truncate.output(result.output, {}, agent)
          return {
            ...result,
            output: truncated.content,
            metadata: { ...result.metadata, truncated: truncated.truncated,
              ...(truncated.truncated && { outputPath: truncated.outputPath }),
            },
          }
        }).pipe(Effect.orDie, Effect.withSpan("Tool.execute", { attributes: attrs }))
      }
      return toolInfo
    })
}

📄 registry.ts (第 266-278 行)

const tools: Interface["tools"] = Effect.fn("ToolRegistry.tools")(function* (input) {
  const filtered = (yield* all()).filter((tool) => {
    // WebSearch 仅在 OpenCode 内置 Provider 或 Exa/Parallel 标志开启时可用
    if (tool.id === WebSearchTool.id) {
      return webSearchEnabled(input.providerID, { exa: flags.enableExa, parallel: flags.enableParallel })
    }
    // GPT 模型使用 apply_patch 而非 edit/write（非 GPT-4）
    const usePatch =
      input.modelID.includes("gpt-") && !input.modelID.includes("oss") && !input.modelID.includes("gpt-4")
    if (tool.id === ApplyPatchTool.id) return usePatch
    if (tool.id === EditTool.id || tool.id === WriteTool.id) return !usePatch
    return true
  })
  // ...
})

📄 registry.ts (第 171-185 行)

const matches = dirs.flatMap((dir) =>
  Glob.scanSync("{tool,tools}/*.{js,ts}", { cwd: dir, absolute: true, dot: true, symlink: true }),
)
for (const match of matches) {
  const namespace = path.basename(match, path.extname(match))
  const mod = yield* Effect.promise(() => import(pathToFileURL(match).href))
  for (const [id, def] of Object.entries(mod)) {
    if (!isPluginTool(def)) continue
    custom.push(fromPlugin(id === "default" ? namespace : `${namespace}_${id}`, def))
  }
}

📄 core/src/tool/tool.ts (第 71-132 行)

export function make<
  Input extends SchemaType<any>,
  Output extends SchemaType<any>,
  Structured extends SchemaType<any> = Output,
>(config: Config<Input, Output, Structured>): Definition<Input, Structured> {
  const tool = Object.freeze({}) as Definition<Input, Structured>
  const definitions = new Map<string, ToolDefinition>()
  runtimes.set(tool, {
    definition: (name) => {
      const cached = definitions.get(name)
      if (cached) return cached
      return new ToolDefinition({
        name,
        description: config.description,
        inputSchema: toJsonSchema(config.input),
        outputSchema: toJsonSchema(config.structured ?? config.output),
      })
    },
    settle: (call, context) =>
      Schema.decodeUnknownEffect(config.input)(call.input).pipe(
        Effect.flatMap((input) => config.execute(input, context).pipe(
          Effect.flatMap((output) =>
            Schema.encodeEffect(config.output)(output)),
        )),
      ),
  })
  return tool
}

📄 core/src/tool/registry.ts (第 42-125 行)

const registryLayer = Layer.effect(
  Service,
  Effect.gen(function* () {
    const applications = yield* ApplicationTools.Service
    const resources = yield* ToolOutputStore.Service
    type Registration = { readonly identity: object; readonly tool: AnyTool }
    const local = new Map<string, Array<{ readonly token: object; readonly registration: Registration }>>()

    const settleWith = Effect.fn("ToolRegistry.settle")(function* (input, advertised?) {
      const registration =
        local.get(input.call.name)?.at(-1)?.registration
        ?? applications.entries().get(input.call.name)
      if (!registration)
        return { result: { type: "error", value: `Unknown tool: ${input.call.name}` } }
      // 执行结算 + 输出边界管理
      const pending = yield* settle(registration.tool, input.call, {
        sessionID: input.sessionID, agent: input.agent,
        assistantMessageID: input.assistantMessageID, toolCallID: input.call.id,
      })
      const bounded = yield* resources.bound({ sessionID, toolCallID, output })
      return { result, output: bounded.output, outputPaths: bounded.outputPaths }
    })
    // ...
  }),
)

📄 edit.ts (第 47-56 行)

export const Parameters = Schema.Struct({
  filePath: Schema.String.annotate({ description: "The absolute path to the file to modify" }),
  oldString: Schema.String.annotate({ description: "The text to replace" }),
  newString: Schema.String.annotate({
    description: "The text to replace it with (must be different from oldString)",
  }),
  replaceAll: Schema.optional(Schema.Boolean).annotate({
    description: "Replace all occurrences of oldString (default false)",
  }),
})

LLM 生成工具调用

⬇️

ToolRegistry.tools() — 获取工具列表

⬇️

wrap().execute() — 参数解码 + Schema 校验

⬇️

ctx.ask() — 权限请求（如需）

⬇️

工具实际执行（文件操作/命令/网络等）

⬇️

Truncate.output() — 输出截断与持久化

⬇️

ExecuteResult — 返回给 LLM 继续对话