11 - 工具描述提示词

来源：各 tools/*/prompt.ts 文件

---

完整中文翻译

文件编辑工具（Edit）

执行文件中的精确字符串替换。

用法：
- 编辑前必须至少使用 Read 工具读取过文件。未读取就尝试编辑会报错。
- 编辑从 Read 输出中获取的文本时，确保保留行号前缀之后的精确缩进。
- 始终优先编辑现有文件。除非明确要求，不要创建新文件。
- 除非用户要求，不要在文件中添加 emoji。
- 如果 old_string 在文件中不唯一，编辑将失败。提供更多上下文使其唯一，
  或使用 replace_all。
- 使用 replace_all 在整个文件中替换和重命名字符串。

文件写入工具（Write）

向本地文件系统写入文件。

- 会覆盖已存在的同路径文件。
- 如果是现有文件，必须先用 Read 读取。
- 修改现有文件优先使用 Edit（只发送差异）。
- 除非用户明确要求，永远不要创建文档文件（*.md）或 README。

文件读取工具（Read）

从本地文件系统读取文件。
- 必须使用绝对路径。
- 默认读取前 2000 行。
- 已知需要的部分就只读那部分。
- 可以读取图片（PNG、JPG）、PDF、Jupyter notebook。
- 只能读文件，不能读目录。

Glob 工具

- 快速文件模式匹配，适用于任何大小的代码库
- 支持 glob 模式如 "**/*.js"
- 按修改时间排序返回匹配的文件路径

Grep 工具

基于 ripgrep 的强大搜索工具
- 始终使用 Grep 进行搜索。永远不要通过 Bash 调用 grep 或 rg。
- 支持完整的正则表达式语法
- 默认单行匹配，跨行匹配需要 multiline: true

Web Search 工具

关键要求 - 强制性：
回答用户问题后，必须包含 "Sources:" 部分，列出所有相关 URL 作为 markdown 超链接。

Web Fetch 工具

重要：如果有 MCP 提供的 web fetch 工具，优先使用它们。
- HTTP URL 自动升级为 HTTPS
- 结果缓存 15 分钟
- GitHub URL 优先使用 gh CLI

---

设计意图分析

”先读后改”的强制约束

Edit 和 Write 工具都要求先 Read——这不是建议，而是硬性约束（不 Read 就报错）。 原因：LLM 可能基于记忆中过时的文件内容进行编辑，导致破坏性修改。 强制 Read 确保编辑基于最新的文件状态。

“不要创建 README/md 文件”

LLM 有一个显著的行为倾向：在完成任何任务后”顺便”创建一个 README 或文档文件。 这条规则直接对抗这种倾向，因为用户通常不需要 AI 自动生成的文档。

Grep 的”永远不要用 Bash”

即使在技术上 rg 命令可以通过 Bash 执行，但使用专用 Grep 工具的好处是：

• 权限控制更精细
• 输出结构化（方便后续处理）
• 用户审查更清晰

Web Search 的强制来源引用

这解决了一个关键的可信度问题：用户需要知道信息来自哪里以便验证。 “Sources:” 部分是强制性的，确保每次搜索结果都可追溯。

---

Insight

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

1. 强制前置条件：“先读后改”不是提示词建议，而是工具层面的硬约束。 这比”请先读文件再编辑”有效得多。
2. 对抗默认行为：“不要创建 README”直接对抗 LLM 的”过度文档化”倾向。 识别并显式抑制 LLM 的不良默认行为是提示词工程的核心技能。
3. 结构化 > 自由格式：专用工具返回结构化结果，比 Bash 的自由格式输出 更适合 AI 系统处理。
4. 可追溯性原则：Web Search 强制引用来源，体现了 AI 系统输出应可追溯、 可验证的设计原则。 ─────────────────────────────────────────────────