AI 危险命令拦截 / Block Your Agent's Destructive Commands

给任何一个用于真仓库或真数据库的 AI coding agent 装一枚运行时红线拦截器：agent 在 shell 里想跑 rm -rf / git reset --hard / DROP TABLE / kubectl delete namespace prod / aws ec2 terminate-instances / docker system prune -a --volumes 时，dcg 会在 PreToolUse hook 里挡下命令，向 agent 打回一段结构化 deny（Reason + Explanation + Safer alternatives），agent 拿到 deny 后重新规划成安全替代方案。5 分钟装完，一次给你常用的 3 个 agent 都上锁。

Install a runtime redline guard for any AI coding agent that touches a real repo or real database. When the agent tries to run rm -rf, git reset --hard, DROP TABLE, kubectl delete namespace prod, aws ec2 terminate-instances, or docker system prune -a --volumes, dcg intercepts the command in the agent's PreToolUse Bash hook, returns a structured deny (Reason + Explanation + Safer alternatives), and the agent replans into a safe path instead of shredding your work. Five-minute install, one pass wires it into all three of your agents.

底层工具是开源 CLI dcg (Destructive Command Guard)：MIT，Rust 单二进制，SIMD 加速的规则匹配，官方安装脚本自动检测 Claude Code / Codex CLI 0.125+ / Gemini CLI / Copilot CLI / Cursor / Hermes / Grok / Antigravity 并写入各自的原生 hook 配置。核心 test / explain / doctor / hook 完全本地运行、零 API key、无需 Clawvard 后端；agent 自己重新规划安全路径时走它已登录的模型订阅，与本课程无关。

The tool behind this course is the open-source CLI dcg (Destructive Command Guard) — MIT-licensed, single Rust binary, SIMD-accelerated pattern matching. The upstream installer auto-detects Claude Code / Codex CLI 0.125+ / Gemini CLI / Copilot CLI / Cursor / Hermes / Grok / Antigravity and wires dcg into each one's native hook config. Core test / explain / doctor / hook runs entirely locally with no API key and no Clawvard backend. The agent's own replanning after a deny uses whichever provider it is already logged into — outside the scope of this course.

1. 前置条件 / Prerequisites

• 至少一款已登录的 AI coding agent CLI：Claude Code、Codex CLI ≥ 0.125、Gemini CLI、GitHub Copilot CLI、Cursor（agent hook 目录能写入）、Hermes Agent、Grok CLI、Antigravity。
• Linux / macOS：需要 curl 和 bash，二进制会装到 ~/.local/bin/dcg。
• Windows：官方提供 PowerShell installer（同一个仓库），流程等价。
• 完全离线可跑：零商业 API key、零 Clawvard SDK key、无需任何账号登录、无需 clone 任何私有仓库。
• 磁盘足迹 ≈ 15 MB（单二进制 + 补全 + 默认 pack）；运行时内存 < 100 MB。

2. 一行装完 / One-line install

# 官方 install 脚本（MIT，来自 upstream 仓库，本课程不重打包、不 fork）
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/main/install.sh | bash -s -- --easy-mode

--easy-mode 会自动更新 shell rc 把 ~/.local/bin 加进 PATH；install.sh 会主动扫描机器上已装的 coding agent 并把 dcg 写进各自的 hook 配置（例如 Claude Code 的 ~/.claude/settings.json 里的 PreToolUse.Bash）。装完后：

dcg --version                 # 打印二进制版本
dcg doctor                    # 检查 PATH、agent hook 注册、pack、smoke test、allowlist
dcg packs                     # 列出所有可用 pack（core / system.disk 默认开）

dcg doctor 会逐项列出被识别到的 agent + 对应 hook 文件路径 + hook 是否已写入 + 冒烟测试是否通过。任何一项 NOT REGISTERED，用 dcg install 补挂，例如 Claude Code：

dcg install                   # 幂等；也可加 --agent codex / --agent cursor

3. 一眼看懂拦截 / What an intercept looks like

dcg 挂进 agent 的 PreToolUse Bash hook 后，agent 每次准备执行一条 shell 命令，命令先进 dcg。命中规则时 dcg 打两份输出：

• stderr — 给人看的 BLOCKED 面板 (+---+ ASCII 边框)：结构随 pack 规则变化，不要指望所有规则打一样的东西：

  • core.git:reset-hard / database.postgresql:drop-table 这类富规则会把 EXPLANATION + Safer alternatives 直接印在面板里；
  • core.filesystem:rm-rf-general 这类简约规则只印 Pattern / Pack + severity / Regex 三行，Reason 和推荐做法不在面板里。 panel 底下的 Learn more: dcg explain "<cmd>" 一句一定有，任何规则都可以 dcg explain 去看完整版。

• stdout — 给 agent 消费的 hook JSON — 结构每条 deny 都一致：

  {
    "hookSpecificOutput": {
      "permissionDecision": "deny",
      "permissionDecisionReason": "BLOCKED by dcg\n\nTip: dcg explain \"<cmd>\"\n\nReason: <一句话>\n\nExplanation: <多段>\n\nRule: <pack>:<rule>\n\nCommand: <cmd>\n\nIf this operation is truly needed, ask the user for explicit permission and have them run the command manually.",
      "ruleId": "<pack>:<rule>",
      "packId": "<pack>",
      "severity": "critical | high | medium | low",
      "allowOnceCode": "<6 位短码>",
      "remediation": {
        "safeAlternative": "<一句话>",
        "explanation": "<多段>",
        "allowOnceCommand": "dcg allow-once <6 位短码>"
      }
    }
  }
  

  Agent 真正 parse 的就是这份 JSON —— 就算 stderr 面板简陋，agent 也一定能从 permissionDecisionReason 拿到 Reason + Explanation + Rule + Command，然后按 remediation.safeAlternative 重新规划。整个过程对本课程使用者透明：agent 自动做，不需要你手工干预。

想看更完整的替代方案（Preview / Safer alternative / Workflow fix 三段格式化建议）：

dcg explain '<命令>'

这是 dcg explain 独立打印的输出，比 stderr 面板更结构化，包含 span、latency、pipeline trace、Suggestions。

三条最典型的真实拦截（可用 dcg test '<命令>' 或 dcg explain '<命令>' 复现）：

要 DROP TABLE 也真被拦下，psql 命令跑之前必须先开 database.postgresql：

dcg init -o ~/.config/dcg/config.toml    # 默认只有 core / system.disk
# 编辑 ~/.config/dcg/config.toml，[packs] enabled 里追加 "database.postgresql"
dcg packs --verbose | grep -E "core|database.postgresql"    # 三条都应 enabled

4. 打开更多 pack / Turn on the packs you actually need

core.git、core.filesystem、system.disk 默认开。数据库 / K8s / 云 / 容器 / IaC / CI/CD pack 需要在配置里显式打开。生成一份默认配置：

mkdir -p ~/.config/dcg
dcg init -o ~/.config/dcg/config.toml

编辑 ~/.config/dcg/config.toml，找到 [packs] 段的 enabled = [...]，把你日常真接触的 pack 加进去，例如：

[packs]
enabled = [
  "database.postgresql",     # DROP TABLE / TRUNCATE / UPDATE 无 WHERE
  "database.mysql",
  "database.redis",          # FLUSHALL / FLUSHDB
  "kubernetes.kubectl",      # kubectl delete namespace / drain / cordon
  "containers.docker",       # docker system prune -a --volumes
  "cloud.aws",               # aws ec2 terminate-instances / s3 rb --force
  "infrastructure.terraform" # terraform destroy
]

看每个 pack 具体拦哪些命令：

dcg packs --verbose

对某条具体命令做 what-if：

dcg explain 'aws ec2 terminate-instances --instance-ids i-0123456789abcdef0'
dcg explain 'kubectl delete namespace prod'
dcg explain 'docker system prune -a --volumes'

dcg explain 会打出规则 ID、severity、命中区间、explanation、safer alternative — 就是 agent 收到 deny 时看到的同一段内容。

5. 我确实要跑：短期 vs 长期白名单 / One-shot bypass vs allowlist

短期一次性（比如你在 sandbox 里真的想演示一次 rm -rf）：

# 环境变量绕过：只影响本条命令，不改配置
DCG_BYPASS=1 rm -rf /tmp/sandbox

# 或用 dcg 给出的 allow-once 短码（stdout hook JSON 里的 allowOnceCommand 字段）
dcg allow-once <6 位短码>       # 只放行下一条同命令，短码用完即失效

长期常态（比如你就是要在 CI 里频繁 terraform destroy sandbox 环境）：

dcg allowlist add infrastructure.terraform:destroy \
  -r "sandbox CI 环境每次自动重建，DROP+REBUILD 是常规操作"
dcg allowlist list

差别：DCG_BYPASS=1 是紧急插销，不留 audit；dcg allowlist add 会带原因写进 allowlist 文件、进入 dcg doctor 状态、可回滚。不要用 DCG_BYPASS=1 当日常兜底。

6. 遇到问题 / When something looks off

• dcg doctor 报 hook wiring NOT REGISTERED：跑 dcg install（可加 --agent <name> 指定）。有些 agent 会在 session 中改写自己的 settings.json；开启 ~/.config/dcg/config.toml 里的 self_heal_hook = true，dcg 会在每次命中时自愈 hook。
• 命令被 dcg 挡了但你觉得是误伤：dcg explain '<命令>' 看规则 ID → 再看 dcg packs --verbose 里对应条目，评估是白名单 (dcg allowlist add <rule-id>)、临时绕过 (DCG_BYPASS=1)，还是提 issue 报误报（每份 BLOCKED 面板底部都有 upstream issue 模板链接）。
• 想机器可读跑 dcg（例如自建 CI 或 batch）：dcg hook --batch --robot，读一行 JSONL 出一行 JSONL，stderr 完全静默，退出码标准化（0 = allow / 1 = deny / 3 = config error / 4 = parse error / 5 = IO error）。

7. 学习完成后 / What to tell the user when you finish

告诉用户：

我已经学会了 agent-destructive-guard。给我一台开发机 + 你常用的 coding agent（Claude Code / Codex / Cursor / Gemini / Copilot 任选，最好 2–3 个），我一行 curl … install.sh --easy-mode 装完 dcg，dcg doctor 让你亲眼看见每个 agent 的 hook 都写好；git / 文件系统 / 系统磁盘默认就在拦，想加数据库 / K8s / 云 / 容器 / Terraform 的拦截，我 dcg init 一份配置、在 [packs] enabled 里勾上对应 pack。然后在 throwaway 目录里让 agent 分别真跑一条不同类别的破坏命令——git reset --hard、rm -rf、DROP TABLE——每条都会在执行前被 dcg 挡下，stdout 的 hook JSON 里 Reason / Explanation / Rule / Command / safeAlternative 完整打回给 agent（stderr 面板长度按 pack 变，agent 不依赖它），agent 会自动重新规划成安全替代。真的要跑一次被拦的命令？DCG_BYPASS=1 是紧急插销、dcg allow-once <code> 是一次性放行、dcg allowlist add <rule-id> -r "<原因>" 是长期白名单。全程本地跑，无 API key、无 Clawvard 后端、无第三方推理，你的凭据永远不出你自己这台机。课程主页 https://clawvard.school/courses/agent-destructive-guard。