工具系统

// src/Tool.ts 核心类型定义
export interface Tool<TInput = unknown, TOutput = unknown> {
  name: string                    // 工具唯一标识
  description: string             // 给 AI 的工具描述
  
  // 输入验证 Schema（Zod v4）
  inputSchema: z.ZodType<TInput>
  
  // 执行逻辑
  execute(
    input: TInput,
    context: ToolUseContext
  ): Promise<ToolResult>
  
  // UI 渲染（可选）
  renderToolUse?(input: TInput): ReactNode
  renderToolResult?(result: ToolResult): ReactNode
  
  // 权限相关
  isReadOnly?: boolean            // 是否只读工具
  requiresPermission?: boolean    // 是否需要权限确认
}

interface ToolUseContext {
  abortController: AbortController  // 取消控制
  permissionMode: PermissionMode    // 当前权限模式
  canUseTool: CanUseToolFn         // 权限检查函数
  options: ToolUseOptions          // 工具选项
  fileStateCache: FileStateCache   // 文件状态缓存
  // ... 更多上下文
}

type ToolResult = {
  type: 'tool_result'
  tool_use_id: string
  content: string | ContentBlock[]
  is_error?: boolean
}

// src/tools.ts（简化）
export function getTools(context: ToolRegistrationContext): Tools {
  return [
    new BashTool(context),
    new FileReadTool(context),
    new FileEditTool(context),
    new FileWriteTool(context),
    new GlobTool(context),
    new GrepTool(context),
    new WebSearchTool(context),
    new WebFetchTool(context),
    new AgentTool(context),
    new AskUserQuestionTool(context),
    // ... 更多工具
    
    // Feature flag 控制的工具
    ...(feature('AGENT_TRIGGERS') ? cronTools : []),
    ...(feature('PROACTIVE') ? [new SleepTool(context)] : []),
  ]
}

tools/BashTool/
├── BashTool.ts          # 工具主类
├── bashToolHelpers.ts   # 辅助函数
├── BashOutput.tsx       # 输出渲染组件
└── test/                # 测试

// 简化的 BashTool 实现
class BashTool implements Tool<BashInput, BashOutput> {
  name = 'Bash'
  description = 'Execute a bash command...'
  
  inputSchema = z.object({
    command: z.string().describe('The command to execute'),
    timeout: z.number().optional(),
    working_directory: z.string().optional(),
  })
  
  async execute(input: BashInput, context: ToolUseContext) {
    // 1. 权限检查
    const permission = await context.canUseTool(this.name, input)
    if (permission === 'deny') return { error: 'Permission denied' }
    
    // 2. 执行命令
    const result = await execa(input.command, {
      cwd: input.working_directory,
      timeout: input.timeout,
      signal: context.abortController.signal,
    })
    
    // 3. 返回结果
    return {
      stdout: result.stdout,
      stderr: result.stderr,
      exitCode: result.exitCode,
    }
  }
}

// MCP 工具发现流程
1. 读取 MCP 配置 (.claude/mcp-configs/)
2. 连接 MCP 服务器 (stdio/SSE)
3. 调用 tools/list 获取工具列表
4. 为每个 MCP 工具创建 MCPTool 实例
5. 注册到工具注册表

// src/Tool.ts
function toolMatchesName(tool: Tool, name: string): boolean {
  // 精确匹配
  if (tool.name === name) return true
  // 别名匹配
  if (tool.aliases?.includes(name)) return true
  return false
}