工具系统参考

file_read

能力：

• 读取完整文件内容或指定行范围
• 在修改前理解代码的关键工具
• 通过范围指定高效处理大文件

使用场景：

• 在编辑前读取配置文件
• 理解现有实现模式
• 查看测试文件以了解覆盖范围

示例：

# Read entire file
file_read("src/components/Button.tsx")

# Read specific range for large files
file_read("package-lock.json", start_line=1, max_lines=50)

file_edit

能力：

• 使用精确字符串匹配进行精准文本替换
• 通过 multiple 标志进行多处替换操作
• 保留文件结构和格式

使用场景：

• 更新函数实现
• 修改配置值
• 跨文件重构变量名

最佳实践： 用于定向修改。对于完整重写，请改用 file_write。

file_write

能力：

• 从零创建新文件
• 完全替换现有文件内容
• 处理任意基于文本的格式

使用场景：

• 生成新组件或模块
• 创建配置文件
• 编写测试文件

警告： 会完全覆盖现有文件。如需部分修改，请使用 file_edit。

glob

能力：

• 查找匹配模式的文件：**/*.ts、src/**/*.js
• 按目录路径过滤
• 通过排除模式缩小结果范围
• 控制结果数量

使用场景：

• 查找项目中的所有组件
• 定位测试文件
• 跨目录识别配置文件

示例模式：

**/*.tsx          # All TypeScript React files
src/**/*.test.js  # All test files in src
**/config.*       # All config files anywhere

grep_content

能力：

• 使用正则模式搜索文件内容
• 显示匹配前/后的上下文行（-B、-A 标志）
• 忽略大小写搜索
• 通过 glob 模式按文件类型过滤

使用场景：

• 查找函数定义
• 定位 API 端点实现
• 搜索特定错误信息
• 识别安全模式

示例：

# Find authentication-related code
grep_content("auth.*login", glob="**/*.ts")

# Search with context
grep_content("TODO", glob="src/**", context_before=2, context_after=2)

grep_file

能力：

• 列出包含匹配项的文件
• 当你只需要文件位置时比 grep_content 更快
• 支持正则模式
• 通过 glob 按文件类型过滤

使用场景：

• 识别哪些文件需要重构
• 查找导入特定模块的文件
• 定位含有已弃用模式的文件

最佳实践： 先用 grep_file 识别相关文件，再用 file_read 进行详细检查。

list_dir

能力：

• 显示目录层级
• 通过 max_depth 参数控制深度
• 通过排除模式过滤输出

使用场景：

• 理解项目结构
• 验证目录组织
• 查找特定子目录

bash

能力：

• 执行 shell 命令
• 最大超时：120 秒（2 分钟，硬性限制）
• 用 && 链接有依赖关系的命令
• 提供描述性摘要以增强清晰度

使用场景：

• 运行测试
• 构建项目
• 安装依赖
• Git 操作
• 数据库迁移

示例：

# Run tests
bash("npm test", timeout=60000, summary="Run Jest test suite")

# Chain dependent commands
bash("npm install && npm run build", timeout=120000)

安全性： 命令以用户权限执行。请在手动接受模式下审查命令。

spawn_subagent

能力：

• 在隔离的上下文中启动专门的子智能体
• 类型：explorer、verifier、code-reviewer
• 委派复杂任务而不污染主上下文
• 并行执行子智能体以提升效率

使用场景：

• explorer： 在大型代码库中搜索模式
• verifier： 验证实现逻辑
• code-reviewer： 安全与质量评估

最佳实践： 将探索性研究委派给 Explorer 子智能体，以保留主对话上下文。

todo_update

能力：

• 创建和管理任务列表
• 更新任务状态（pending、in_progress、completed）
• 在复杂实现中追踪进度

使用场景：

• 拆解多步骤功能
• 追踪重构进度
• 管理迁移任务

web_search

能力：

• 查询互联网搜索引擎
• 控制结果数量
• 按时效性过滤（最近天数）

使用场景：

• 查找陌生 API 的文档
• 研究错误信息
• 查看当前最佳实践

web_fetch

能力：

• 获取网页内容
• 用特定查询分析内容
• 提取结构化信息

使用场景：

• 阅读文档页面
• 分析 API 文档
• 从教程中提取示例

数据格式

构建与包文件

file_read 效率

最佳实践：

• 对超过 500 行的文件使用行范围，避免上下文过载
• 仅读取任务所需的相关部分
• 对于大文件，先用 grep_content 识别相关行号

# Good: Read specific section
file_read("large-config.json", start_line=100, max_lines=50)

# Less efficient: Read entire large file
file_read("large-config.json")  # May consume excessive context

file_edit 精确性

最佳实践：

• 确保字符串精确匹配，避免编辑失败
• 对于多处类似修改，使用 multiple=true 标志
• 编辑前验证文件路径

file_write 安全性

最佳实践：

• 仔细核对路径，防止意外覆盖
• 仅用于新文件或完整重写
• 如需修改，优先使用 file_edit 以确保安全

glob 模式精确性

最佳实践：

• 使用具体模式缩小范围：用 src/**/*.ts 而非 **/*
• 用排除模式排除目录：!**/node_modules/**
• 限制结果数量以避免输出过多

# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)

# Less efficient: Too broad
glob("**/*")  # Returns thousands of results

grep 策略

推荐工作流：

1. 用 grep_file 识别相关文件
2. 用 file_read 读取特定文件
3. 当需要周边上下文时使用 grep_content

性能提示：

• 正则模式可能比字面字符串更慢
• 忽略大小写的搜索更慢
• 将上下文行（-A、-B）限制在必要范围内

bash 最佳实践

安全的命令执行：

• 为命令描述提供清晰的摘要
• 为长时间运行的操作设置合适的超时
• 用 && 链接有依赖关系的命令
• 仔细审查破坏性命令（rm、drop、truncate）

# Good: Clear summary, reasonable timeout
bash("npm run build", timeout=120000, summary="Build production bundle")

# Good: Chained dependencies
bash("npm install && npm run test", timeout=180000)

安全注意事项

关键安全规则：

• 命令以用户权限执行
• 切勿运行不可信的命令
• 在共享代码库中使用手动接受模式进行审查
• 避免暴露凭据或敏感数据的命令

子智能体委派效率

何时使用子智能体：

• Explorer： 代码库搜索、架构问题（节省主上下文）
• Verifier： 快速验证检查（隔离验证）
• Code-reviewer： 安全与质量审查（详细分析）
• General： 复杂的多步骤任务（并行执行）

最佳实践： 将探索性和研究性任务委派给子智能体，以便为活跃的开发工作保留主对话上下文。

上下文管理

策略性工具使用：

• 有策略地读取文件——只读所需内容
• 使用子智能体进行后台研究
• 在长会话中监控上下文消耗
• 用 todo_update 将复杂操作拆分为步骤

高效工作流：

1. 规划： 用 glob/grep 确定范围
2. 读取： 仅读取相关文件/部分
3. 执行： 在合适时委派给子智能体
4. 验证： 用 Verifier 子智能体进行快速检查

文件大小限制

大文件处理： 超大文件（>10,000 行）应分段读取，以避免：

• 上下文窗口耗尽
• 响应时间变慢
• 内存问题

工具超时默认值

工具限制：

• Bash 超时： 最大 120 秒（2 分钟）
• 文件操作： 无大小限制（大文件自动分批读取）
• 大文件处理： 大于 256KB 的文件仅返回前 256KB 内容
• 搜索结果： glob 或 grep_content 结果无限制
• 并发子智能体： 并行执行无限制

超时配置：

• 为长时间运行的操作设置明确的超时
• 监控挂起的进程
• 超过 2 分钟超时的命令将被终止

并发操作

并行执行： 多个子智能体可并行运行，以更快完成复杂操作。主智能体会自动处理协调。

性能优势：

• 减少多步骤任务的总执行时间
• 高效利用资源
• 自动任务编排
• 并发子智能体数量无限制