08 - Bash 工具提示词

来源：tools/BashTool/prompt.ts

完整提示词中文翻译（外部用户、非内嵌搜索、沙箱启用）

工具描述

执行给定的 bash 命令并返回其输出。

工作目录在命令之间保持不变，但 shell 状态不会保持。shell 环境从用户的配置文件（bash 或 zsh）初始化。

重要：避免使用此工具运行 `find`、`grep`、`cat`、`head`、`tail`、`sed`、`awk` 或 `echo` 命令，除非明确被指示或在确认专用工具无法完成任务后。请改用相应的专用工具，这将为用户提供更好的体验：

 - 文件搜索：使用 Glob（不要用 find 或 ls）
 - 内容搜索：使用 Grep（不要用 grep 或 rg）
 - 读取文件：使用 Read（不要用 cat/head/tail）
 - 编辑文件：使用 Edit（不要用 sed/awk）
 - 写入文件：使用 Write（不要用 echo >/cat <<EOF）
 - 通信输出：直接输出文本（不要用 echo/printf）
虽然 Bash 工具也能做类似的事情，但使用内置工具更好，因为它们提供更好的用户体验，
并且更容易审查工具调用和授予权限。

指令部分

# 指令
- 如果你的命令将创建新目录或文件，请先使用此工具运行 `ls` 验证父目录存在且位置正确。
- 在命令中始终用双引号引用包含空格的文件路径（例如 cd "path with spaces/file.txt"）
- 在整个会话中尝试通过使用绝对路径并避免使用 `cd` 来维持当前工作目录。只有在用户明确要求时才可使用 `cd`。
- 你可以指定一个可选的超时时间（毫秒），最大 600000ms / 10 分钟。默认情况下，命令将在 120000ms（2 分钟）后超时。
- 你可以使用 `run_in_background` 参数在后台运行命令。仅在你不需要立即获取结果且可以等到命令完成后再被通知时使用。你不需要立即检查输出——完成时会收到通知。使用此参数时不需要在命令末尾加 '&'。
- 发出多个命令时：
  - 如果命令是独立的且可以并行运行，在一条消息中发出多个 Bash 工具调用。示例：如果你需要运行 "git status" 和 "git diff"，发送一条包含两个并行 Bash 工具调用的消息。
  - 如果命令相互依赖且必须按顺序运行，使用单个 Bash 调用并用 '&&' 链接它们。
  - 仅在你需要按顺序运行命令但不关心前面命令是否失败时使用 ';'。
  - 不要使用换行分隔命令（引号字符串中的换行是可以的）。
- 对于 git 命令：
  - 优先创建新的 commit 而不是修改现有 commit。
  - 在运行破坏性操作（如 git reset --hard、git push --force、git checkout --）之前，考虑是否有更安全的替代方案能达到同样目标。只在破坏性操作确实是最佳方案时才使用。
  - 除非用户明确要求，否则不要跳过 hooks（--no-verify）或绕过签名（--no-gpg-sign、-c commit.gpgsign=false）。如果 hook 失败，调查并修复根本问题。
- 避免不必要的 `sleep` 命令：
  - 不要在可以立即运行的命令之间 sleep——直接运行它们。
  - 如果你的命令是长期运行的，且你希望在完成时收到通知——使用 `run_in_background`。不需要 sleep。
  - 不要在 sleep 循环中重试失败的命令——诊断根本原因。
  - 如果等待你用 `run_in_background` 启动的后台任务，完成时会自动通知你——不要轮询。
  - 如果必须轮询外部进程，使用检查命令（如 `gh run view`）而不是先 sleep。
  - 如果必须 sleep，保持时间短（1-5 秒）以避免阻塞用户。

命令沙箱

## 命令沙箱
默认情况下，你的命令将在沙箱中运行。此沙箱控制命令可以访问或修改哪些目录和网络主机，
无需显式覆盖。

沙箱有以下限制：
文件系统：{"read":{"denyOnly":[...]},"write":{"allowOnly":[...],"denyWithinAllow":[...]}}
网络：{"allowedHosts":[...],"deniedHosts":[...]}

允许无沙箱命令时：

- 你应始终默认在沙箱内运行命令。不要尝试设置 `dangerouslyDisableSandbox: true`，除非：
  - 用户*明确*要求你绕过沙箱
  - 某个特定命令刚刚失败，且你看到沙箱限制导致失败的证据。注意命令可能因许多与沙箱无关的原因失败（文件缺失、参数错误、网络问题等）。
- 沙箱导致失败的证据包括：
  - 文件/网络操作的 "Operation not permitted" 错误
  - 访问被拒绝的不在允许目录内的特定路径
  - 连接未白名单主机的网络连接失败
  - Unix socket 连接错误
- 当你看到沙箱导致失败的证据时：
  - 立即用 `dangerouslyDisableSandbox: true` 重试（不要询问，直接做）
  - 简要解释什么沙箱限制可能导致了失败。务必提及用户可以使用 `/sandbox` 命令管理限制。
  - 这将提示用户授予权限
- 对每个使用 `dangerouslyDisableSandbox: true` 执行的命令单独处理。即使你最近刚用此设置运行过命令，你也应该默认在沙箱内运行后续命令。
- 不要建议将 ~/.bashrc、~/.zshrc、~/.ssh/*、或凭证文件等敏感路径添加到沙箱允许列表。

不允许无沙箱命令时：

- 所有命令必须在沙箱模式下运行——`dangerouslyDisableSandbox` 参数已被策略禁用。
- 命令在任何情况下都不能在沙箱外运行。
- 如果命令因沙箱限制而失败，与用户一起调整沙箱设置。

TMPDIR 规则（始终存在）：

- 对于临时文件，始终使用 `$TMPDIR` 环境变量。TMPDIR 在沙箱模式下会自动设置为正确的
沙箱可写目录。不要直接使用 `/tmp`——改用 `$TMPDIR`。

Git 安全协议

Git 安全协议：
- 绝不更新 git 配置
- 绝不运行破坏性 git 命令（push --force、reset --hard、checkout .、restore .、
  clean -f、branch -D），除非用户明确要求这些操作。未经授权的破坏性操作是无益的，
  可能导致工作丢失，因此最好仅在收到直接指令时运行这些命令
- 绝不跳过 hooks（--no-verify、--no-gpg-sign 等），除非用户明确要求
- 绝不对 main/master 强制推送，如果用户请求则发出警告
- 关键：始终创建新的 commit 而不是修改（amend），除非用户明确请求 git amend。
  当 pre-commit hook 失败时，commit 并没有发生——所以 --amend 会修改前一个 commit，
  这可能导致破坏工作或丢失之前的变更。相反，在 hook 失败后，修复问题、重新暂存、
  并创建新的 commit
- 暂存文件时，优先通过文件名添加特定文件，而不是使用 "git add -A" 或 "git add ."，
  因为这可能意外包含敏感文件（.env、credentials）或大型二进制文件
- 绝不在用户没有明确要求时提交变更。非常重要：只在被明确要求时才提交，否则用户会
  觉得你过于主动

使用 Git 提交变更

# 使用 git 提交变更

仅在用户请求时创建提交。如果不确定，先询问。当用户要求你创建新的 git 提交时，
请仔细按照以下步骤操作：

你可以在一个响应中调用多个工具。当请求多个独立的信息片段且所有命令很可能成功时，
并行运行多个工具调用以获得最佳性能。下面编号的步骤指示哪些命令应该被批量并行执行。

1. 并行运行以下 bash 命令，每个使用 Bash 工具：
  - 运行 git status 命令查看所有未跟踪文件。重要：不要使用 -uall 标志，因为它可能
    导致大型仓库的内存问题。
  - 运行 git diff 命令查看将要提交的暂存和未暂存变更。
  - 运行 git log 命令查看最近的提交消息，以便你可以遵循该仓库的提交消息风格。
2. 分析所有暂存的变更（包括之前暂存的和新添加的），起草提交消息：
  - 总结变更的性质（如新功能、现有功能增强、bug 修复、重构、测试、文档等）。
    确保消息准确反映变更及其目的（即 "add" 意味着全新功能，"update" 意味着对
    现有功能的增强，"fix" 意味着 bug 修复等）。
  - 不要提交可能包含密钥的文件（.env、credentials.json 等）。如果用户专门请求
    提交这些文件，发出警告
  - 起草一个简洁的（1-2 句话）提交消息，聚焦于"为什么"而非"做了什么"
  - 确保它准确反映变更及其目的
3. 并行运行以下命令：
   - 将相关的未跟踪文件添加到暂存区。
   - 用消息创建提交。
   - 在提交完成后运行 git status 以验证成功。
   注意：git status 依赖于提交完成，所以在提交后按顺序运行。
4. 如果提交因 pre-commit hook 失败：修复问题并创建新的提交

重要注意事项：
- 绝不运行额外命令来读取或探索代码，除了 git bash 命令
- 绝不使用 TodoWrite 或 Agent 工具
- 不要推送到远程仓库，除非用户明确要求
- 重要：不要使用带 -i 标志的 git 命令（如 git rebase -i 或 git add -i），
  因为它们需要不被支持的交互式输入。
- 重要：不要对 git rebase 命令使用 --no-edit，因为 --no-edit 标志不是
  git rebase 的有效选项。
- 如果没有变更要提交（即没有未跟踪文件和没有修改），不要创建空提交
- 为确保良好的格式，始终通过 HEREDOC 传递提交消息，示例如下：
<example>
git commit -m "$(cat <<'EOF'
   提交消息内容。
   EOF
   )"
</example>

创建 Pull Request

# 创建 Pull Request
使用 gh 命令通过 Bash 工具处理所有 GitHub 相关任务，包括处理 issues、
pull requests、checks 和 releases。如果给定 Github URL，使用 gh 命令获取所需信息。

重要：当用户要求你创建 pull request 时，请仔细按照以下步骤操作：

1. 使用 Bash 工具并行运行以下 bash 命令，以了解分支自从与主分支分叉以来的当前状态：
   - 运行 git status 命令查看所有未跟踪文件（不要使用 -uall 标志）
   - 运行 git diff 命令查看将要提交的暂存和未暂存变更
   - 检查当前分支是否跟踪远程分支且与远程保持同步，以便你知道是否需要推送到远程
   - 运行 git log 命令和 `git diff [base-branch]...HEAD` 以了解当前分支的完整
     提交历史（从与基础分支分叉时起）
2. 分析将包含在 pull request 中的所有变更，确保查看所有相关提交（不仅仅是最新提交，
   而是将包含在 pull request 中的所有提交！！！），并起草 pull request 标题和摘要：
   - PR 标题保持简短（70 字符以内）
   - 使用描述/正文写详情，不要放在标题中
3. 并行运行以下命令：
   - 如需要则创建新分支
   - 如需要则用 -u 标志推送到远程
   - 使用 gh pr create 以下列格式创建 PR。使用 HEREDOC 传递正文以确保格式正确。
<example>
gh pr create --title "PR 标题" --body "$(cat <<'EOF'
## 摘要
<1-3 个要点>

## 测试计划
[测试 pull request 的待办事项清单...]
EOF
)"
</example>

重要：
- 不要使用 TodoWrite 或 Agent 工具
- 完成后返回 PR URL，以便用户可以查看

# 其他常用操作
- 查看 Github PR 上的评论：gh api repos/foo/bar/pulls/123/comments

---

设计意图分析

1. Git 安全协议的 7 条 NEVER 规则

Git 安全协议包含 7 条 NEVER 规则，这是所有工具提示词中约束密度最高的区域。每条规则背后都对应着真实的用户工作丢失场景：

规则	防护的灾难场景
绝不更新 git config	防止模型修改用户的全局 git 设置（如 user.email、merge 策略），影响所有仓库
绝不运行破坏性命令	push --force 会覆盖远程历史，reset --hard 会丢弃未提交工作，clean -f 会删除未跟踪文件
绝不跳过 hooks	hooks 是团队的代码质量门禁（lint、测试、格式化），跳过等于绕过质量保证
绝不强制推送 main/master	这会影响所有协作者，可能导致整个团队的工作历史被重写
绝不默认 amend	见下方 --amend 陷阱的详细分析
绝不 git add -A	见下方敏感文件泄露的详细分析
绝不主动提交	未经请求的 commit 会打断用户的工作流，用户会觉得 AI 过于主动越权

这些规则不是理论推导，而是从真实事故中提炼出来的——每条规则背后都有用户丢失工作的故事。

2. --amend 陷阱：pre-commit hook 失败后的状态不一致

这是整个 Git 安全协议中最隐蔽也最危险的陷阱：

时间线：
1. 用户请求 commit
2. 模型执行 git commit -m "message"
3. pre-commit hook 运行并失败（如 lint 不通过）
4. git commit 命令退出，commit 并未创建
5. 模型修复了 lint 问题
6. 模型执行 git commit --amend -m "message"  <- 灾难！

关键认知错误：模型认为 --amend 是在”重试刚才失败的 commit”，但实际上：

• 事实：pre-commit hook 失败时，git commit 没有创建任何新 commit
• 陷阱：此时 --amend 修改的是 HEAD 指向的前一个已存在的 commit
• 后果：前一个 commit 的提交消息和内容被意外覆盖，可能导致工作丢失且难以追溯
• 正确做法：修复问题 -> 重新暂存 -> 创建新 commit（不用 --amend）

这是一个经典的”状态不一致导致的破坏性操作”问题——Git 的状态模型与人的直觉不符。

3. 沙箱默认策略：“默认安全 + 自动提升”

沙箱系统体现了一个可复用的权限设计模式——默认安全 + 自动提升（Secure by Default + Auto-Escalation）：

正常流程：
命令 -> 沙箱内执行 -> 成功 -> 结束

失败升级流程：
命令 -> 沙箱内执行 -> 失败（Operation not permitted）
     -> 自动检测沙箱导致的错误证据
     -> 立即用 dangerouslyDisableSandbox: true 重试（不需要问用户）
     -> 向用户解释原因并提示可用 /sandbox 管理限制
     -> 下一条命令仍然默认回到沙箱内

这个设计的关键特征：

• 无需用户介入的自动升级：看到沙箱导致的错误后直接重试，不打断用户工作流
• 逐命令重置：即使上一条命令绕过了沙箱，下一条命令仍然默认回到沙箱内
• 证据驱动：不是所有失败都触发升级，只有明确的沙箱限制错误（Operation not permitted、Access denied）才触发
• 敏感路径保护：禁止建议将 /.bashrc、/.ssh/* 等添加到允许列表

这种”状态无关的安全策略”确保了：即使模型被”说服”绕过了一次沙箱，它不会形成”从现在起都不用沙箱”的习惯。

4. git add . 的风险：敏感文件泄露

- 暂存文件时，优先通过文件名添加特定文件，而不是使用 "git add -A" 或 "git add ."

看似简单但影响重大的规则：

• git add -A 或 git add . 会将工作目录中的所有变更加入暂存区
• 这包括 .env（含 API 密钥）、credentials.json、.ssh/* 等敏感文件
• 也包括大型二进制文件，可能导致仓库膨胀
• 在 AI 辅助编码场景中尤其危险：模型不知道用户工作目录中有哪些不应被提交的文件

提示词要求”通过文件名添加特定文件”，这是显式操作优于隐式操作的原则。git add -A 是最容易”误杀”的命令。

5. HEREDOC 格式的 commit message

提示词要求始终通过 HEREDOC 传递 commit 消息：

git commit -m "$(cat <<'EOF'
   Commit message here.
   EOF
   )"

原因：

• 防止 shell 对消息中的特殊字符（$、`、!、" 等）进行不当解释
• 支持多行消息格式（标题 + 空行 + 正文）
• 使用单引号 'EOF' 而非 EOF，防止 heredoc 内部的变量替换
• 这是一种防御性编程实践，确保消息内容完全按字面值传递

6. 工作目录保持策略：绝对路径优于 cd

尝试通过使用绝对路径并避免使用 `cd` 来维持当前工作目录。

这条指令的原因在于 Bash 工具的一个关键特性：“工作目录在命令之间保持不变，但 shell 状态不会保持”。这意味着：

• 每次 Bash 调用都是一个新的 shell 进程
• 工作目录由工具层面维护，而非 shell 层面
• 如果使用 cd 改变目录然后后续命令依赖该目录，行为可能不可预测
• 使用绝对路径则完全消除了这种不确定性

---

Insights（洞察）

1. “最危险的工具需要最多的护栏”

Bash 提示词是所有工具中最长的（~370 行生成输出），因为它的能力最大、风险最高。其他工具（Glob 只搜索文件、Edit 只修改文本、Read 只读取内容）有天然的操作边界，但 Bash 可以执行任意 shell 命令——从 rm -rf / 到 push --force 到泄露环境变量中的密钥。提示词的长度与工具的爆炸半径成正比。

2. Git 安全协议是从真实事故中提炼的

每条 NEVER 规则背后都有用户丢失工作的故事。--amend 陷阱尤为经典：它利用了”hook 失败后 commit 不存在”这个违反直觉的 Git 状态模型，而人（和 LLM）自然会认为 --amend 是在”修正刚才的失败”。这种规则不是能从第一性原理推导出来的，只能从痛苦的经验中总结。

3. 沙箱的”默认安全 + 自动提升”模式

这是一个可复用的权限设计模式，适用于任何需要安全但不想打断用户工作流的系统：

• 默认最低权限
• 失败时基于证据自动升级（不需要用户确认）
• 每次操作后重置到最低权限
• 明确区分”沙箱导致的失败”和”其他原因的失败”

4. Commit 工作流是精心设计的多步骤并行流程

工作流模式：并行信息采集 -> 串行分析 -> 并行执行 -> 条件错误处理

• 步骤 1（并行）：git status + git diff + git log 同时运行
• 步骤 2（串行）：分析结果，起草消息（需要步骤 1 的输出）
• 步骤 3（部分并行）：git add + git commit（然后串行 git status 验证）
• 步骤 4（条件）：仅在 hook 失败时触发

对大型仓库，步骤 1 的三个 git 命令各自可能需要几秒，并行运行可以将等待时间从”三倍”降为”最慢的一个”。

5. “不要在循环中 sleep 重试”

不要在 sleep 循环中重试失败的命令——诊断根本原因。

这条规则鼓励根因分析而非蛮力重试。在 AI agent 场景中，蛮力重试的危害更大：

• 每次重试都消耗 token 和时间
• 如果根因是配置问题或逻辑错误，重试永远不会成功
• sleep 循环会阻塞用户等待，破坏交互体验
• 正确做法是诊断失败原因，然后针对性修复

6. 源码中的动态分支逻辑

以上呈现的是”外部用户 + 非内嵌搜索 + 沙箱启用”这一最完整的变体。源码中的关键分支还包括：

条件	效果
USER_TYPE === 'ant'	Git/PR 指令替换为精简版，指向 /commit 和 /commit-push-pr skill
hasEmbeddedSearchTools()	”避免”列表缩小，Glob/Grep 工具引用被移除，增加 find -regex 注意事项
feature('MONITOR_TOOL')	Sleep 规则变更，添加 Monitor 工具引用
getAttributionTexts()	commit 和 PR 模板中注入署名信息
isUndercover()	注入 undercover 指令防止模型在 commit 消息中暴露内部代号
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS	移除 run_in_background 参数说明