Tool 参考手册

文件操作

Read

字段	值
名称	`Read`
类别	文件操作
描述	从本地文件系统读取文件。支持文本文件、图像（PNG、JPG）、PDF 和 Jupyter notebook（.ipynb）。

输入参数：

参数	类型	必填	描述
`file_path`	`string`	✅	要读取文件的绝对路径
`offset`	`number`	❌	开始读取的行号（从 1 开始）
`limit`	`number`	❌	最大读取行数

输出： 带行号的文件内容（cat -n 格式）。图像以视觉方式呈现。PDF 逐页处理。

Edit

字段	值
名称	`Edit`
类别	文件操作
描述	对文件执行精确字符串替换。需要事先 Read 该文件。

输入参数：

参数	类型	必填	描述
`file_path`	`string`	✅	要修改文件的绝对路径
`old_string`	`string`	✅	要替换的精确文本（在文件中必须唯一）
`new_string`	`string`	✅	替换后的文本
`replace_all`	`boolean`	❌	替换所有匹配项（默认：false）

输出： 带周围上下文的编辑确认信息。

Write

字段	值
名称	`Write`
类别	文件操作
描述	向本地文件系统写入（覆盖）文件。如果文件已存在，需要事先 Read。

输入参数：

参数	类型	必填	描述
`file_path`	`string`	✅	要写入文件的绝对路径
`content`	`string`	✅	要写入的完整内容

输出： 文件写入成功的确认信息。

NotebookEdit

字段	值
名称	`NotebookEdit`
类别	文件操作
描述	在 Jupyter notebook（.ipynb 文件）中创建、替换或删除单元格。

输入参数：

参数	类型	必填	描述
`notebook_path`	`string`	✅	notebook 文件的绝对路径
`new_source`	`string`	✅	单元格的新源内容
`cell_id`	`string`	❌	要编辑或在其后插入的单元格 ID
`cell_type`	`"code" \| "markdown"`	❌	单元格类型（插入时必填）
`edit_mode`	`"replace" \| "insert" \| "delete"`	❌	编辑类型（默认：replace）

输出： notebook 修改的确认信息。

搜索与导航

Glob

字段	值
名称	`Glob`
类别	搜索与导航
描述	快速文件模式匹配。返回按修改时间排序的匹配文件路径。

输入参数：

参数	类型	必填	描述
`pattern`	`string`	✅	匹配的 glob 模式（例如 `*/.ts`、`src/*/.tsx`）
`path`	`string`	❌	要搜索的目录（默认：当前工作目录）

输出： 匹配文件路径列表，按修改时间排序。

Grep

字段	值
名称	`Grep`
类别	搜索与导航
描述	使用正则表达式搜索文件内容。基于 ripgrep 构建。

输入参数：

参数	类型	必填	描述
`pattern`	`string`	✅	要搜索的正则表达式模式
`path`	`string`	❌	要搜索的文件或目录（默认：当前工作目录）
`output_mode`	`"content" \| "files_with_matches" \| "count"`	❌	输出格式（默认：files_with_matches）
`glob`	`string`	❌	文件 glob 过滤器（例如 `*.ts`）
`type`	`string`	❌	文件类型过滤器（例如 `js`、`py`）
`-i`	`boolean`	❌	大小写不敏感搜索
`-n`	`boolean`	❌	显示行号（默认：true）
`-A`	`number`	❌	匹配后的行数
`-B`	`number`	❌	匹配前的行数
`-C`	`number`	❌	匹配前后的行数（context）
`multiline`	`boolean`	❌	启用多行匹配
`head_limit`	`number`	❌	将输出限制为前 N 条记录
`offset`	`number`	❌	跳过前 N 条记录

输出： 根据 output_mode 返回匹配内容、文件路径或计数。

Shell 执行

Bash

字段	值
名称	`Bash`
类别	Shell 执行
描述	在持久化 shell 会话中执行 bash 命令。受 27 层安全检查约束。

输入参数：

参数	类型	必填	描述
`command`	`string`	✅	要执行的 bash 命令
`description`	`string`	❌	命令用途的简要描述
`timeout`	`number`	❌	超时时间（毫秒，最大：600,000，默认：120,000）
`run_in_background`	`boolean`	❌	在后台运行，完成时通知
`dangerouslyDisableSandbox`	`boolean`	❌	禁用沙箱模式（需要显式 flag）

输出： 命令的 stdout 和 stderr。超过 30,000 字符时截断。

Web 与网络

WebSearch

字段	值
名称	`WebSearch`
类别	Web 与网络
描述	搜索网络获取最新信息。返回带标题、URL 和摘要的搜索结果。

输入参数：

参数	类型	必填	描述
`query`	`string`	✅	搜索 query（最少 2 个字符）
`allowed_domains`	`string[]`	❌	仅包含这些域名的结果
`blocked_domains`	`string[]`	❌	排除这些域名的结果

输出： 带标题、URL 和内容摘要的搜索结果。

WebFetch

字段	值
名称	`WebFetch`
类别	Web 与网络
描述	抓取 URL 并处理其内容。将 HTML 转换为 Markdown 以便分析。

输入参数：

参数	类型	必填	描述
`url`	`string (URI)`	✅	格式完整的 URL
`prompt`	`string`	✅	描述要从页面中提取什么信息的 prompt

输出： 基于 prompt 的处理内容。大型内容可能被摘要。

任务管理

TodoWrite

字段	值
名称	`TodoWrite`
类别	任务管理
描述	创建和管理结构化任务列表，用于追踪复杂操作的进度。

输入参数：

参数	类型	必填	描述
`todos`	`TodoItem[]`	✅	完整的更新后任务列表

TodoItem Schema：

字段	类型	必填	描述
`content`	`string`	✅	祈使式任务描述（例如”修复 bug”）
`activeForm`	`string`	✅	进行时形式（例如”正在修复 bug”）
`status`	`"pending" \| "in_progress" \| "completed"`	✅	当前任务状态

输出： 任务列表更新的确认信息。

版本控制

GitStatus

字段	值
名称	`GitStatus`
类别	版本控制
描述	显示工作区状态：已暂存、未暂存和未追踪的文件。

输入参数： 无

输出： 显示文件状态的 git status 输出。

GitDiff

字段	值
名称	`GitDiff`
类别	版本控制
描述	显示提交、工作区和暂存区之间的变更。

输入参数：

参数	类型	必填	描述
`args`	`string`	❌	传递给 `git diff` 的参数（例如 `--staged`、`HEAD~1`）

输出： 统一 diff 输出。

GitLog

字段	值
名称	`GitLog`
类别	版本控制
描述	显示提交日志历史。

输入参数：

参数	类型	必填	描述
`args`	`string`	❌	传递给 `git log` 的参数（例如 `-n 10`、`--oneline`）

输出： 格式化的提交日志。

GitCommit

字段	值
名称	`GitCommit`
类别	版本控制
描述	用已暂存的更改创建 git 提交。

输入参数：

参数	类型	必填	描述
`message`	`string`	✅	提交信息

输出： 提交哈希和摘要。

Agent 管理

Skill

字段	值
名称	`Skill`
类别	Agent 管理
描述	在对话中执行预定义的 skill（工作流模板）。

输入参数：

参数	类型	必填	描述
`skill`	`string`	✅	skill 名称（例如 “commit”、“review-pr”、“pdf”）
`args`	`string`	❌	skill 的可选参数

输出： skill 执行输出（因 skill 而异）。

Fork

字段	值
名称	`Fork`
类别	Agent 管理
描述	为并行子任务生成独立的 sub-agent。共享父级的 prompt cache 前缀。

输入参数：

参数	类型	必填	描述
`task`	`string`	✅	sub-agent 的任务描述
`context`	`string`	❌	共享前缀之外的额外 context
`maxTurns`	`number`	❌	sub-agent 的最大 turn 数（默认：10）

输出： sub-agent 的最终结果。

Coordinator

字段	值
名称	`Coordinator`
类别	Agent 管理
描述	启动一个规划并管理多步骤工作流（带工作 agent）的 coordinator agent。

输入参数：

参数	类型	必填	描述
`goal`	`string`	✅	要完成的高层目标
`maxWorkers`	`number`	❌	最大并发工作者数（默认：3）
`maxRounds`	`number`	❌	最大协调轮次（默认：20）

输出： 所有工作者输出的综合结果。

MCP Tool

MCPTool（动态）

字段	值
名称	不固定（由 MCP 服务器提供）
类别	MCP
描述	从已连接 MCP 服务器动态发现的 tool。schema 由 MCP 服务器定义。

输入参数： 由 MCP 服务器的 tool schema 定义。

输出： 由 MCP 服务器的 tool 响应定义。

其他内置 Tool

以下 tool 构成了 46 个内置 tool 的完整集合：

文件操作（扩展）

Tool	描述
`ListDirectory`	列出路径下的文件和目录及其元数据
`FileInfo`	获取文件元数据：大小、权限、修改时间
`Move`	移动或重命名文件或目录
`Copy`	复制文件或目录

搜索（扩展）

Tool	描述
`FindReferences`	查找代码库中某个符号的所有引用
`GoToDefinition`	跳转到某个符号的定义位置
`ListSymbols`	列出文件中的所有符号（函数、类、类型）

Git（扩展）

Tool	描述
`GitAdd`	暂存文件用于提交
`GitBranch`	列出、创建或删除分支
`GitCheckout`	切换分支或恢复文件
`GitStash`	储藏工作目录的变更
`GitBlame`	逐行显示作者信息
`GitShow`	显示提交详情或特定版本的文件

系统与环境

Tool	描述
`GetWorkingDirectory`	返回当前工作目录
`GetEnvironment`	返回环境信息（操作系统、shell、运行时）
`ReadImage`	读取并分析图像文件
`ReadPDF`	读取并提取 PDF 文件内容

Agent 与工作流

Tool	描述
`TeamSwarm`	启动一组带共享 mailbox 的同伴 agent
`DreamTask`	排队一个推测性后台任务
`TaskOutput`	读取后台任务的输出
`MemoryWrite`	将信息持久化到长期记忆
`MemoryRead`	从长期记忆中检索信息

Tool 类别汇总

类别	数量	permission 级别
文件操作	7	写操作需要审批；读操作自动批准
搜索与导航	5	自动批准（只读）
Shell 执行	1	27 层安全检查
Web 与网络	2	自动批准
任务管理	1	自动批准
版本控制	8	读操作自动批准；写操作需要审批
Agent 管理	4	自动批准（委托给 sub-agent）
MCP	动态	遵循 MCP 服务器配置
系统与环境	4	自动批准（只读）
Agent 与工作流	5	自动批准
合计	~46	—