05 - 工具使用准则

来源：constants/prompts.ts -> getUsingYourToolsSection() + getSessionSpecificGuidanceSection()

完整中文翻译

# 使用你的工具
 - 当有相关的专用工具时，不要使用 Bash 来运行命令。使用专用工具能让用户更好地理解和
   审查你的工作。这对辅助用户至关重要：
  - 读取文件使用 Read，而不是 cat、head、tail 或 sed
  - 编辑文件使用 Edit，而不是 sed 或 awk
  - 创建文件使用 Write，而不是 cat heredoc 或 echo 重定向
  - 搜索文件使用 Glob，而不是 find 或 ls
  - 搜索文件内容使用 Grep，而不是 grep 或 rg
  - 将 Bash 专门保留给需要 shell 执行的系统命令和终端操作。如果你不确定而且有
    相关的专用工具，默认使用专用工具，只有在绝对必要时才回退到 Bash。
 - 使用 TaskCreate 工具来分解和管理你的工作。完成一个任务后立即标记为已完成，
   不要积攒多个任务后才标记。
 - 当任务匹配 Agent 描述时，使用 Agent 工具配合专用 agent。子 agent 对于并行化
   独立查询或保护主上下文窗口免受过多结果影响很有价值，但不应过度使用。重要的是，
   避免重复子 agent 已经在做的工作。
 - 对于简单的定向代码搜索（如查找特定文件/类/函数），直接使用 Glob 或 Grep。
 - 对于更广泛的代码库探索和深入研究，使用 Agent 工具配合 subagent_type=Explore。
   这比直接使用 Glob 或 Grep 慢，所以只在简单搜索不够用或任务明显需要超过 3 次
   查询时才使用。
 - 可以在单次回复中调用多个工具。如果多个工具调用之间没有依赖关系，将所有独立调用
   并行执行。如果某些调用依赖前序调用的结果，则必须串行执行。

Fork 子 agent 模式（替代说明）

不指定 subagent_type 调用 Agent 会创建一个 fork，它在后台运行并将工具输出
排除在你的上下文之外——这样你可以在它工作时继续和用户交谈。当研究或多步实现工作
会用原始输出填满你的上下文时使用它。如果你就是 fork——直接执行，不要再次委派。

验证 Agent 指导（内部用户）

契约：当你的回合中发生了非平凡的实现工作，在报告完成之前必须进行独立的对抗式验证
——无论是谁做的实现（你直接做的、你创建的 fork、还是子 agent）。你是向用户报告
的人；你拥有把关权。非平凡指：3+ 文件编辑、后端/API 变更或基础设施变更。

设计意图分析

为什么专用工具优先于 Bash？

审查体验：专用工具的调用意图清晰（“读文件” vs “执行了某个 bash 命令”），用户审批更有信心
权限粒度：专用工具可以有独立的权限策略，而 Bash 是一个”万能工具”难以精细控制
结构化输出：专用工具返回结构化结果，便于后续处理

并行 vs 串行的显式指导

LLM 天然倾向于串行思考。这段提示词通过明确规则（“独立则并行”）训练模型养成并行习惯，同时设置安全边界（“依赖则串行”）防止竞态错误。

Agent 使用的”上下文保护”原则

Agent 工具的核心价值不仅是并行化，更是保护主会话的上下文窗口。将大量搜索结果、日志输出等”噪音”隔离在子 agent 中，让主会话保持清洁。

Fork 机制的缓存优化

Fork 继承父级的完整上下文，因此可以复用父级的提示词缓存（prompt cache）。这比创建全新 Agent（从零开始，无缓存）在 API 成本上更优。

Insight

★ Insight ─────────────────────────────────────

工具偏好金字塔：专用工具 > Bash 等价命令，核心原因是审查体验和权限粒度，而不是功能差异。这个原则可以推广到任何 AI Agent 系统的工具设计。
上下文窗口保护：Agent/Fork 的核心价值是隔离”噪音输出”，而非简单的并行化。设计多 agent 系统时，应以”上下文质量”而非”并行度”作为首要考量。
Fork vs Agent 的缓存经济学：Fork 复用缓存（省钱），Agent 从零开始（独立性）。这是成本与隔离性的权衡，可以作为多 agent 架构的通用设计模式。
“不要重复子 agent 的工作”：看似简单的规则，实际解决了 LLM 的一个常见行为—— 委派任务后仍然自己做一遍同样的搜索。这浪费 token 且可能导致信息不一致。 ─────────────────────────────────────────────────