第 06 章：工具的注册与发现

import { z } from 'zod'

const UserSchema = z.object({
  name: z.string(),                    // 必填字符串
  age: z.number().optional(),          // 可选数字
  role: z.enum(['admin', 'user']),     // 枚举
})

type User = z.infer<typeof UserSchema>
// 等价于: { name: string; age?: number; role: 'admin' | 'user' }

const result = UserSchema.safeParse({ name: 'Alice', role: 'admin' })
if (result.success) {
  console.log(result.data)  // { name: 'Alice', role: 'admin' }
}

// → src/Tool.ts 的 Tool 类型（简化版，展示核心字段）
export type Tool<
  Input extends AnyObject = AnyObject,
  Output = unknown,
  P extends ToolProgressData = ToolProgressData,
> = {
  // === 基础属性 ===
  readonly name: string                   // 工具名，如 "Bash"
  aliases?: string[]                      // 别名（重命名后向后兼容）

  // === 核心方法 ===
  call(args, context, canUseTool, parentMessage, onProgress?): Promise<ToolResult<Output>>
  description(input, options): Promise<string>
  readonly inputSchema: Input             // Zod schema

  // === 行为标记 ===
  isReadOnly(input): boolean              // 是否只读（影响并发策略）
  isConcurrencySafe(input): boolean       // 是否并发安全
  isDestructive?(input): boolean          // 是否破坏性操作
  isEnabled(): boolean                    // 当前是否启用

  // === 中断行为 ===
  interruptBehavior?(): 'cancel' | 'block' // 用户发新消息时：取消 or 等待

  // === 其他 ===
  maxResultSizeChars?: number             // 结果持久化阈值
}

// → src/Tool.ts 的 buildTool() 函数（简化版）
const TOOL_DEFAULTS = {
  isEnabled: () => true,
  isConcurrencySafe: (_input?: unknown) => false,
  isReadOnly: (_input?: unknown) => false,
  isDestructive: (_input?: unknown) => false,
}

export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {
  return {
    ...TOOL_DEFAULTS,   // 先铺上默认值
    userFacingName: () => def.name,
    ...def,             // 然后用具体实现覆盖
  } as BuiltTool<D>
}

// → src/tools/BashTool/BashTool.tsx 的 fullInputSchema（简化版）
const fullInputSchema = lazySchema(() => z.strictObject({
  command: z.string().describe('The command to execute'),
  timeout: z.number().optional().describe('Optional timeout in milliseconds'),
  description: z.string().optional().describe('Clear, concise description...'),
  run_in_background: z.boolean().optional(),
  dangerouslyDisableSandbox: z.boolean().optional(),
}))

// → src/tools/BashTool/BashTool.tsx
// Always omit _simulatedSedEdit from the model-facing schema. It is an internal-only
// field set by SedEditPermissionRequest after the user approves a sed edit preview.
const inputSchema = lazySchema(() => fullInputSchema().omit({
  _simulatedSedEdit: true
}))

export const BashTool = buildTool({
  name: 'Bash',
  searchHint: 'execute shell commands',
  maxResultSizeChars: 30_000,  // 超过 30K 字符时结果存到文件
  isReadOnly(input) {
    const result = checkReadOnlyConstraints(input)
    return result.behavior === 'allow'
  },
  isConcurrencySafe(input) {
    return this.isReadOnly?.(input) ?? false  // 只读命令才能并发
  },
  async call(args, context, canUseTool, parentMessage) {
    // ...执行 bash 命令的完整逻辑
  },
})

// → src/tools.ts 的 getAllBaseTools() 函数（简化版）
export function getAllBaseTools(): Tools {
  return [
    // === 核心工具（始终存在）===
    AgentTool,               // 子代理
    BashTool,                // Shell 命令
    FileReadTool,            // 读文件
    FileEditTool,            // 编辑文件
    FileWriteTool,           // 写文件
    NotebookEditTool,        // Jupyter notebook

    // === 条件工具（feature flag 控制）===
    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),
    ...(isWorktreeModeEnabled() ? [EnterWorktreeTool, ExitWorktreeTool] : []),
    ...(isAgentSwarmsEnabled() ? [TeamCreateTool, TeamDeleteTool] : []),
    ...(SleepTool ? [SleepTool] : []),
    ...(ToolSearchTool ? [ToolSearchTool] : []),
    // ... 其余 20+ 个工具
  ]
}

// → src/tools.ts 的 getTools() 函数（简化版）
export const getTools = (permissionContext: ToolPermissionContext): Tools => {
  // --bare 模式：只有 Bash + Read + Edit
  if (process.env.CLAUDE_CODE_SIMPLE) {
    return [BashTool, FileReadTool, FileEditTool]
  }

  const tools = getAllBaseTools().filter(tool => !specialTools.has(tool.name))
  let allowedTools = filterToolsByDenyRules(tools, permissionContext)
  return allowedTools.filter((_, i) => allowedTools[i].isEnabled())
}

// → src/tools.ts 的 assembleToolPool() 函数（简化版）
export function assembleToolPool(
  permissionContext: ToolPermissionContext,
  mcpTools: Tool[],
): Tools {
  const builtinTools = getTools(permissionContext)
  const allowedMcpTools = filterToolsByDenyRules(mcpTools, permissionContext)

  const seen = new Set(builtinTools.map(t => t.name))
  const dedupedMcp = allowedMcpTools.filter(t => !seen.has(t.name))

  // 各自排序后合并（排序保证 prompt cache 稳定性）
  return [...builtinTools.sort(byName), ...dedupedMcp.sort(byName)]
}

console.log('[DEBUG] Active tools:', result.map(t => t.name).join(', '))
console.log('[DEBUG] Tool count:', result.length)

for (const tool of result) {
  try {
    const ro = tool.isReadOnly({})
    console.log(`[DEBUG] ${tool.name}: isReadOnly=${ro}`)
  } catch { /* 有些工具需要具体输入 */ }
}

console.log('[DEBUG] BashTool inputSchema:', JSON.stringify(inputSchema(), null, 2))