第 10 章工具协议、注册与 ToolSearchbuildTool() 的抽象之美

// Tool.ts:362-695 (简化展示)
export type Tool<
  Input extends AnyObject = AnyObject,
  Output = unknown,
  P extends ToolProgressData = ToolProgressData,
> = {
  // ── 身份标识 ──
  readonly name: string
  aliases?: string[]
  searchHint?: string           // ToolSearch 关键词匹配用

  // ── Schema 定义 ──
  readonly inputSchema: Input   // Zod schema
  readonly inputJSONSchema?: ToolInputJSONSchema  // MCP 工具直接用 JSON Schema
  outputSchema?: z.ZodType<unknown>

  // ── 核心方法 ──
  call(args, context, canUseTool, parentMessage, onProgress?): Promise<ToolResult<Output>>
  description(input, options): Promise<string>
  prompt(options): Promise<string>

  // ── 安全与权限 ──
  validateInput?(input, context): Promise<ValidationResult>
  checkPermissions(input, context): Promise<PermissionResult>
  isReadOnly(input): boolean
  isDestructive?(input): boolean
  isConcurrencySafe(input): boolean
  isEnabled(): boolean

  // ── UI 渲染协议（6 个 render 方法）──
  renderToolUseMessage(input, options): React.ReactNode
  renderToolResultMessage?(content, progressMessages, options): React.ReactNode
  renderToolUseProgressMessage?(progressMessages, options): React.ReactNode
  renderToolUseRejectedMessage?(input, options): React.ReactNode
  renderToolUseErrorMessage?(result, options): React.ReactNode
  renderGroupedToolUse?(toolUses, options): React.ReactNode | null

  // ── 结果序列化 ──
  mapToolResultToToolResultBlockParam(content, toolUseID): ToolResultBlockParam

  // ── 辅助方法 ──
  maxResultSizeChars: number
  userFacingName(input): string
  getPath?(input): string
  toAutoClassifierInput(input): unknown
  // ...更多
}

模型发出 tool_use → renderToolUseMessage（展示工具调用意图）
                  → renderToolUseProgressMessage（展示执行进度）
                  → renderToolResultMessage（展示结果）
                  → renderToolUseRejectedMessage（用户拒绝时）
                  → renderToolUseErrorMessage（执行出错时）
                  → renderGroupedToolUse（多个同类工具批量展示）

// Tool.ts:757-792
const TOOL_DEFAULTS = {
  isEnabled: () => true,
  isConcurrencySafe: (_input?: unknown) => false,  // 假设不安全
  isReadOnly: (_input?: unknown) => false,          // 假设写入
  isDestructive: (_input?: unknown) => false,
  checkPermissions: (input, _ctx?) =>
    Promise.resolve({ behavior: 'allow', updatedInput: input }),
  toAutoClassifierInput: (_input?: unknown) => '',
  userFacingName: (_input?: unknown) => '',
}

export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {
  return {
    ...TOOL_DEFAULTS,
    userFacingName: () => def.name,
    ...def,
  } as BuiltTool<D>
}

// Tool.ts:707-726
// 可以有默认值的方法列表
type DefaultableToolKeys =
  | 'isEnabled'
  | 'isConcurrencySafe'
  | 'isReadOnly'
  | 'isDestructive'
  | 'checkPermissions'
  | 'toAutoClassifierInput'
  | 'userFacingName'

// ToolDef：这些方法变为可选
export type ToolDef<...> =
  Omit<Tool<...>, DefaultableToolKeys> &
  Partial<Pick<Tool<...>, DefaultableToolKeys>>

// BuiltTool<D>：类型层模拟 { ...TOOL_DEFAULTS, ...def }
type BuiltTool<D> = Omit<D, DefaultableToolKeys> & {
  [K in DefaultableToolKeys]-?: K extends keyof D
    ? undefined extends D[K]
      ? ToolDefaults[K]   // D 没提供 → 用默认值类型
      : D[K]              // D 提供了 → 用 D 的类型
    : ToolDefaults[K]
}

// tools/GlobTool/GlobTool.ts:57-198
export const GlobTool = buildTool({
  name: GLOB_TOOL_NAME,
  searchHint: 'find files by name pattern or wildcard',
  maxResultSizeChars: 100_000,

  async description() { return DESCRIPTION },

  // ── Schema（延迟求值）──
  get inputSchema(): InputSchema { return inputSchema() },
  get outputSchema(): OutputSchema { return outputSchema() },

  // ── 覆盖默认值 ──
  isConcurrencySafe() { return true },   // 只读搜索，可以并发
  isReadOnly() { return true },          // 不会修改文件

  // ── 工具特有逻辑 ──
  async validateInput({ path }): Promise<ValidationResult> {
    if (path) {
      const absolutePath = expandPath(path)
      // UNC 路径安全检查，防止 NTLM 凭据泄露
      if (absolutePath.startsWith('\\\\') || absolutePath.startsWith('//')) {
        return { result: true }
      }
      // 验证目录存在
      // ...
    }
    return { result: true }
  },

  async checkPermissions(input, context) {
    return checkReadPermissionForTool(GlobTool, input, ...)
  },

  async call(input, { abortController, getAppState, globLimits }) {
    const { files, truncated } = await glob(
      input.pattern,
      GlobTool.getPath(input),
      { limit: globLimits?.maxResults ?? 100 },
      abortController.signal,
    )
    return { data: { filenames: files.map(toRelativePath), ... } }
  },

  // ── UI 委托给独立文件 ──
  renderToolUseMessage,       // 来自 ./UI.tsx
  renderToolResultMessage,    // 复用 GrepTool 的实现
  renderToolUseErrorMessage,  // 来自 ./UI.tsx
  // ...
} satisfies ToolDef<InputSchema, Output>)

// utils/lazySchema.ts
export function lazySchema<T>(factory: () => T): () => T {
  let cached: T | undefined
  return () => (cached ??= factory())
}

// tools.ts:193-251
export function getAllBaseTools(): Tools {
  return [
    AgentTool,
    TaskOutputTool,
    BashTool,
    // 嵌入式搜索工具存在时，移除 Glob/Grep
    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),
    ExitPlanModeV2Tool,
    FileReadTool,
    FileEditTool,
    FileWriteTool,
    NotebookEditTool,
    WebFetchTool,
    TodoWriteTool,
    WebSearchTool,
    // ... 更多工具
    // 条件注册
    ...(process.env.USER_TYPE === 'ant' ? [ConfigTool] : []),
    ...(SleepTool ? [SleepTool] : []),
    ...cronTools,
    ...(isToolSearchEnabledOptimistic() ? [ToolSearchTool] : []),
    // 测试专用
    ...(process.env.NODE_ENV === 'test' ? [TestingPermissionTool] : []),
  ]
}

// tools.ts:25-28
const SleepTool =
  feature('PROACTIVE') || feature('KAIROS')
    ? require('./tools/SleepTool/SleepTool.js').SleepTool
    : null

// tools.ts:16-19
const REPLTool =
  process.env.USER_TYPE === 'ant'
    ? require('./tools/REPLTool/REPLTool.js').REPLTool
    : null

// tools.ts:325-326 (getTools 内部)
const isEnabled = allowedTools.map(_ => _.isEnabled())
return allowedTools.filter((_, i) => isEnabled[i])

编译期 DCE → 模块加载时环境变量 → 运行时 isEnabled() → 权限 deny rules

// tools.ts:271-327
export const getTools = (permissionContext: ToolPermissionContext): Tools => {
  // 1. 简单模式：只有 Bash, Read, Edit
  if (isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) {
    return filterToolsByDenyRules([BashTool, FileReadTool, FileEditTool], ...)
  }

  // 2. 获取所有基础工具（排除特殊工具）
  const tools = getAllBaseTools().filter(tool => !specialTools.has(tool.name))

  // 3. 应用 deny rules 过滤
  let allowedTools = filterToolsByDenyRules(tools, permissionContext)

  // 4. REPL 模式过滤：隐藏被 REPL 包装的原始工具
  if (isReplModeEnabled()) { /* ... */ }

  // 5. isEnabled() 过滤
  return allowedTools.filter((_, i) => isEnabled[i])
}

// tools.ts:345-367 — 合并内置工具与 MCP 工具
export function assembleToolPool(
  permissionContext: ToolPermissionContext,
  mcpTools: Tools,
): Tools {
  const builtInTools = getTools(permissionContext)
  const allowedMcpTools = filterToolsByDenyRules(mcpTools, permissionContext)

  // 按名称排序（prompt cache 稳定性），built-in 优先
  const byName = (a: Tool, b: Tool) => a.name.localeCompare(b.name)
  return uniqBy(
    [...builtInTools].sort(byName).concat(allowedMcpTools.sort(byName)),
    'name',
  )
}

// tools.ts:62-72
// Lazy require to break circular dependency:
// tools.ts -> TeamCreateTool/TeamDeleteTool -> ... -> tools.ts
const getTeamCreateTool = () =>
  require('./tools/TeamCreateTool/TeamCreateTool.js')
    .TeamCreateTool as typeof import('./tools/TeamCreateTool/TeamCreateTool.js').TeamCreateTool

// services/tools/toolOrchestration.ts:91-116
function partitionToolCalls(
  toolUseMessages: ToolUseBlock[],
  toolUseContext: ToolUseContext,
): Batch[] {
  return toolUseMessages.reduce((acc: Batch[], toolUse) => {
    const tool = findToolByName(toolUseContext.options.tools, toolUse.name)
    const parsedInput = tool?.inputSchema.safeParse(toolUse.input)
    const isConcurrencySafe = parsedInput?.success
      ? (() => {
          try {
            return Boolean(tool?.isConcurrencySafe(parsedInput.data))
          } catch {
            return false  // 解析失败 → 保守处理
          }
        })()
      : false

    // 连续的并发安全工具合并为一个 batch
    if (isConcurrencySafe && acc[acc.length - 1]?.isConcurrencySafe) {
      acc[acc.length - 1]!.blocks.push(toolUse)
    } else {
      acc.push({ isConcurrencySafe, blocks: [toolUse] })
    }
    return acc
  }, [])
}

// services/tools/toolOrchestration.ts:19-82
export async function* runTools(...): AsyncGenerator<MessageUpdate, void> {
  for (const { isConcurrencySafe, blocks } of partitionToolCalls(...)) {
    if (isConcurrencySafe) {
      // 并发执行，事后按序应用 contextModifier
      for await (const update of runToolsConcurrently(blocks, ...)) {
        yield { message: update.message, newContext: currentContext }
      }
    } else {
      // 串行执行
      for await (const update of runToolsSerially(blocks, ...)) {
        yield { message: update.message, newContext: currentContext }
      }
    }
  }
}

// Tool.ts:158-300 (核心字段)
export type ToolUseContext = {
  options: {
    tools: Tools              // 当前可用的所有工具
    commands: Command[]       // 可用的斜杠命令
    mcpClients: MCPServerConnection[]
    mainLoopModel: string     // 当前模型
    thinkingConfig: ThinkingConfig
    isNonInteractiveSession: boolean
    // ...
  }
  abortController: AbortController   // 取消信号
  readFileState: FileStateCache      // 文件状态缓存（LRU）
  getAppState(): AppState            // 获取全局状态
  setAppState(f): void               // 修改全局状态
  messages: Message[]                // 当前对话历史
  setInProgressToolUseIDs: (f) => void
  // ...
}

// tools/ToolSearchTool/prompt.ts:62-108
export function isDeferredTool(tool: Tool): boolean {
  // 显式 opt-out：alwaysLoad = true 的工具永远不延迟
  if (tool.alwaysLoad === true) return false

  // MCP 工具：总是延迟（按需发现）
  if (tool.isMcp === true) return true

  // ToolSearch 自身：永远不延迟（模型需要它来加载其他工具）
  if (tool.name === TOOL_SEARCH_TOOL_NAME) return false

  // Agent 工具在 fork 模式下：不延迟（第一轮就需要）
  if (feature('FORK_SUBAGENT') && tool.name === AGENT_TOOL_NAME) {
    if (m.isForkSubagentEnabled()) return false
  }

  // 其他：通过 shouldDefer 标记
  return tool.shouldDefer === true
}

<available-deferred-tools>
mcp__slack__slack_send_message
mcp__slack__slack_list_conversations
mcp__github__create_pull_request
...
</available-deferred-tools>

// tools/ToolSearchTool/ToolSearchTool.ts:304-471 (核心逻辑)
export const ToolSearchTool = buildTool({
  name: TOOL_SEARCH_TOOL_NAME,
  isEnabled() { return isToolSearchEnabledOptimistic() },
  isConcurrencySafe() { return true },
  isReadOnly() { return true },

  async call(input, { options: { tools }, getAppState }) {
    const { query, max_results = 5 } = input
    const deferredTools = tools.filter(isDeferredTool)

    // 模式一：select:Name1,Name2 — 精确选择
    const selectMatch = query.match(/^select:(.+)$/i)
    if (selectMatch) {
      // 直接按名称查找
      // ...
    }

    // 模式二：关键词搜索
    const matches = await searchToolsWithKeywords(query, deferredTools, tools, max_results)
    return buildSearchResult(matches, query, deferredTools.length)
  },

  // 返回 tool_reference 块，API 会展开为完整工具定义
  mapToolResultToToolResultBlockParam(content, toolUseID) {
    return {
      type: 'tool_result',
      tool_use_id: toolUseID,
      content: content.matches.map(name => ({
        type: 'tool_reference',
        tool_name: name,
      })),
    }
  },
})

// tools/ToolSearchTool/ToolSearchTool.ts:259-301
// 评分权重
// - name 部分精确匹配：MCP 12 分 / 普通 10 分
// - name 部分包含匹配：MCP 6 分 / 普通 5 分
// - searchHint 匹配：4 分
// - description 匹配：2 分

// GlobTool.ts
searchHint: 'find files by name pattern or wildcard'

// FileReadTool.ts
searchHint: 'read files, images, PDFs, notebooks'

// utils/toolSearch.ts:172-198
// ENABLE_TOOL_SEARCH    Mode
// auto / auto:1-99      tst-auto（超过阈值才延迟）
// true / auto:0         tst（总是延迟）
// false / auto:100      standard（从不延迟）
// (unset)               tst（默认：总是延迟 MCP 和 shouldDefer 工具）

// utils/toolSearch.ts:104-109
function getAutoToolSearchTokenThreshold(model: string): number {
  const contextWindow = getContextWindowForModel(model, betas)
  const percentage = getAutoToolSearchPercentage() / 100
  return Math.floor(contextWindow * percentage)
}

tools/
├── GlobTool/
│   ├── GlobTool.ts      # 工具定义（buildTool + call 逻辑）
│   ├── prompt.ts        # 工具名常量 + description 文本
│   └── UI.tsx           # render* 方法的实现
├── BashTool/
│   ├── BashTool.tsx     # 主文件
│   ├── prompt.ts        # description + 超时配置
│   ├── UI.tsx           # 渲染逻辑
│   ├── bashPermissions.ts    # 权限匹配逻辑
│   ├── bashSecurity.ts       # AST 安全分析
│   ├── commandSemantics.ts   # 命令语义分类
│   ├── shouldUseSandbox.ts   # 沙箱决策
│   └── ...（18 个文件）
├── FileReadTool/
│   ├── FileReadTool.ts
│   ├── prompt.ts
│   ├── UI.tsx
│   ├── limits.ts        # 读取限制配置
│   └── imageProcessor.ts
├── shared/             # 跨工具复用的子模块（gitOperationTracking、spawnMultiAgent）
├── utils.ts            # 工具间共享的 tagMessagesWithToolUseID / getToolUseIDFromParentMessage
└── ...（其余各工具目录见附录 A）

// 模式抽象
const DEFAULTS = {
  isReadOnly: () => false,      // 默认假设不安全
  canRunConcurrently: () => false,
}

function buildPlugin(def) {
  return { ...DEFAULTS, ...def }
}

编译期 feature() → 模块加载时 env check → 运行时 isEnabled() → 权限 deny rules