第8章 · 54个工具逐一拆解

第8章 · 54个工具逐一拆解

8.1 文件操作组

FileReadTool —— 读取文件内容。支持行号范围（offset/limit）、PDF页面范围、Jupyter Notebook渲染、图片二进制读取。实现了文件大小预检查，超大文件自动截断并提示使用行号范围。

FileWriteTool —— 写入/创建文件。执行前检查：目标目录是否存在、文件是否已被其他工具锁定。写入后触发微压缩（删除同一文件的过时读取缓存）。

FileEditTool —— 精确字符串替换。核心逻辑：查找 old_string 的唯一匹配位置，替换为 new_string。如果 old_string 不唯一，返回错误要求提供更多上下文。支持 replace_all 模式。并发编辑检测：如果文件在上次读取后被外部修改，发出警告。

GlobTool —— 文件模式匹配。使用 fast-glob 库，支持 **/*.ts 等模式。结果按修改时间排序。

GrepTool —— 内容搜索。基于 ripgrep（rg），支持正则、文件类型过滤、上下文行、多行匹配。输出模式：content（显示匹配行）、files_with_matches（仅文件路径）、count（计数）。

8.2 执行组

BashTool —— Shell命令执行。经过25项安全检查（详见第9章）。支持超时配置（最大600秒）、后台执行、工作目录设置。输出截断：超长输出自动写入临时文件并返回路径。

PowerShellTool —— Windows PowerShell执行。类似BashTool但针对Windows环境优化。

REPLTool —— 虚拟机执行（ANT专用）。在受控的VM沙箱中执行代码片段，不同于直接的Bash执行。提供更强的隔离和更快的启动。

8.3 Agent组

AgentTool —— 核心的子Agent生成工具。支持三种隔离模式：

1. Worktree隔离：创建Git Worktree，子Agent在独立分支工作。完成后自动清理（无变更时）或返回变更分支。
2. 远程隔离（ANT专用）：在CCR环境中启动完全隔离的远程Agent。
3. CWD覆盖：最轻量的隔离——仅限制子Agent的工作目录。

子Agent可以配置独立的MCP服务器（内联或引用）、自定义系统提示、特定的工具子集。

SendMessageTool —— Agent间消息传递。在多Agent场景中，Agent之间通过此工具通信。支持按Agent名称或ID寻址。

8.4 Web组

WebSearchTool —— Web搜索。调用Anthropic的搜索API，返回结构化的搜索结果。支持域名过滤（允许/阻止列表）。

WebFetchTool —— URL内容获取。获取网页内容并通过小模型进行摘要。支持HTML→Markdown转换、重定向跟随、15分钟缓存。

8.5 MCP组

MCPTool —— MCP工具调用的模板。运行时被 mcpClient.ts 动态覆盖，每个连接的MCP服务器生成独立的工具实例。工具名格式：mcp__serverName__toolName。

ListMcpResourcesTool —— 列出MCP服务器提供的资源。

ReadMcpResourceTool —— 读取特定MCP资源。

McpAuthTool —— MCP服务器的OAuth认证流程。

8.6 任务管理组

TaskCreateTool —— 创建后台任务。支持的任务类型：local_bash、local_agent、remote_agent。每种类型有不同的创建参数和执行环境。

TaskGetTool —— 获取任务状态和详情。

TaskListTool —— 列出所有活跃任务。

TaskOutputTool —— 获取任务的完整输出。

TaskStopTool —— 停止运行中的任务。

TaskUpdateTool —— 更新任务参数（如发送消息给运行中的Agent任务）。

8.7 团队组

TeamCreateTool —— 创建多Agent团队。在tmux中生成新的Agent实例，配置团队名称和角色。

TeamDeleteTool —— 删除团队及其所有Agent实例。

8.8 模式切换组

EnterPlanModeTool —— 进入计划模式。在此模式下，模型只能读取和搜索，不能修改文件或执行命令。用于安全的代码分析和规划。

ExitPlanModeTool —— 退出计划模式，恢复完整工具权限。

EnterWorktreeTool —— 进入Git Worktree隔离。创建独立分支，所有后续操作在隔离环境中执行。

ExitWorktreeTool —— 退出Worktree，合并或放弃变更。

8.9 KAIROS专属组

SleepTool —— AI主动睡眠。当KAIROS模式下没有待处理的工作时，Claude调用此工具进入等待状态。下一个 <tick> 或外部事件将唤醒它。支持用户中断。

SendUserFileTool —— 主动向用户发送文件。KAIROS模式下Claude可以主动将生成的文件推送给用户。

PushNotificationTool —— 推送通知到用户设备。KAIROS完成任务后可以通知用户。

SubscribePRTool —— 订阅GitHub PR事件。KAIROS通过此工具感知代码变更，决定是否需要介入（如代码审查、CI修复）。

8.10 其他工具

ScheduleCronTool —— 定时任务调度。支持cron表达式，让Claude Code按计划自动执行任务。

SkillTool —— 技能调用。从内置或用户自定义的技能库中加载并执行特定技能。

LSPTool —— Language Server Protocol操作。支持go-to-definition、find-references、hover等LSP操作，通过文件扩展名自动路由到对应的语言服务器。

BriefTool —— KAIROS的精简交互工具。将Claude的输出浓缩为简短的用户可见消息，减少在自主模式下的输出噪音。

TodoWriteTool —— 任务列表管理。维护结构化的待办事项列表，支持状态追踪（pending/in_progress/completed）。

SyntheticOutputTool —— 生成合成输出。用于在特定场景下生成格式化的输出内容。

NotebookEditTool —— Jupyter Notebook编辑。理解Cell结构（code/markdown/output），支持精确的Cell级编辑操作。

ConfigTool —— 配置管理（ANT专用）。支持读取和修改Claude Code的运行时配置。

RemoteTriggerTool —— 远程触发器。在Bridge模式下触发远程操作。

ToolSearchTool —— 工具搜索（延迟加载枢纽）。搜索并加载延迟工具的Schema。

---