AI 程式設計 Agent 可以執行 Shell 後，最大的風險之一不是程式碼寫錯，而是在錯誤目錄執行刪除、覆蓋或 Git 清理命令。Destructive Command Guard，簡稱 dcg，會作為工具呼叫前置 Hook 檢查命令，在執行前攔截高風險操作。
專案地址：Dicklesworthstone/destructive_command_guard
快速答案
dcg 支援 Codex CLI、Claude Code、Gemini CLI、Copilot CLI、Cursor 等工具。它適合作為額外防線，但不是完整沙箱：Agent 仍可能把危險操作寫進指令碼，部分執行路徑也可能繞過 Hook。
Linux、macOS 和 WSL 的快速安裝：
|
|
遠端安裝指令碼應先審查。安裝器會下載對應平臺二進位制、校驗雜湊，併合並支援的 Agent Hook 配置，而不是直接覆蓋合法的現有 JSON。
Codex 中怎樣工作
對支援 Hooks 的 Codex CLI，安裝器會向 ~/.codex/hooks.json 合併 PreToolUse Hook。安裝完成後開啟一次 Codex 的 /hooks 介面確認信任。
當 Agent 準備執行命令時，dcg 會：
- 解析工具呼叫的 JSON；
- 提取並規範化 Shell 命令；
- 快速排除明顯安全的命令；
- 用規則識別刪除、覆蓋、強制重置等風險；
- 返回允許、拒絕或需要人工確認。
給倉庫增加預提交掃描
除了實時 Hook，還可以掃描將要提交的指令碼和工作流：
|
|
團隊匯入時建議先採用“高嚴重度才失敗”的保守策略，觀察誤報後再擴大到 Makefile、Dockerfile 和更多 Shell 指令碼。
安裝後如何驗證
不要用真實刪除命令測試。可以讓 Agent 解釋一條明顯危險的模擬命令，並觀察 Hook 是否在執行前給出阻止資訊。隨後檢查：
dcg是否位於PATH；- Agent 的 Hook 配置是否為有效 JSON；
/hooks是否顯示並信任該 Hook；- 原有 Hook 是否仍然存在；
- 普通只讀命令是否沒有明顯延遲。
安裝方式與平臺差異
Linux、macOS 和 WSL 可以使用 Shell 安裝器。原生 Windows 應使用倉庫提供的 install.ps1，不要在 PowerShell 中硬套 Bash 命令。
安裝前建議：
- 開啟指令碼檢查下載地址；
- 備份 Agent 的 Hook 配置；
- 記錄現有
PATH； - 確認安裝版本和校驗機制；
- 在測試賬戶或測試環境先執行；
- 安裝後檢視配置差異。
Easy Mode 會嘗試自動檢測並配置支援的 Agent。團隊環境更適合先使用 --no-configure 只安裝二進位制，再人工稽核各工具的 Hook 合併。
Codex Hook 的完整檢查
新版 Codex CLI 使用 ~/.codex/hooks.json 中的 PreToolUse Hook。配置完成後：
- 確認 JSON 能正常解析；
- 檢查原有 Hooks 沒有被刪除；
- 在 Codex 中開啟
/hooks； - 明確信任 dcg Hook；
- 用無破壞性的模擬請求測試阻止流程；
- 檢視普通命令是否仍可透過。
如果 /hooks 沒有顯示，不要假設保護已經生效。檢查 Codex 版本、功能支援和實際配置路徑。
哪些命令容易被攔截
dcg 關注可能造成不可恢復損失的 Git 和 Shell 操作，例如遞迴刪除、強制清理、覆蓋歷史和針對寬泛目錄的危險命令。實際規則會更新，應以當前版本為準。
一個命令是否危險，不只看命令名，還要看引數和目標：
|
|
不要為了繞過誤報把命令拆成多個更隱蔽步驟。應修正規則、使用明確目標或交給人工執行。
Scan 模式怎樣用於程式碼庫
實時 Hook 保護 Agent 當前準備執行的命令，dcg scan 則檢查倉庫中可能執行的 Shell 片段，包括指令碼、CI 工作流、Dockerfile 和 Makefile。
首次匯入建議：
|
|
只讓高置信度嚴重問題阻止提交。觀察一段時間後，再把範圍擴大到：
|
|
不要第一天就把所有 Warning 設為 CI 失敗，否則誤報會促使團隊直接關閉工具。
預提交 Hook 與 CI 的職責
本地預提交
反饋快，適合在提交前發現新增危險命令，但使用者可用 --no-verify 繞過，也可能沒有安裝 Hook。
CI 掃描
由倉庫統一執行，更適合形成強制規則。CI 中應固定 dcg 版本、驗證下載，並只掃描本次差異或明確路徑，避免結果隨上游變化。
Agent PreToolUse
在命令執行前阻止，保護的是當前工作區。它無法替代 CI 對倉庫內容的持續檢查。
三者解決的時間點不同，可以同時使用。
Allowlist 應怎樣管理
某些專案確實需要清理構建目錄或重置臨時環境。不要關閉整個 dcg，應為範圍明確、可驗證的命令建立最小例外：
- 只允許專案內特定臨時目錄；
- 不使用環境變數拼接寬泛根路徑；
- 先解析並輸出絕對路徑；
- 對生產目錄不設永久例外；
- 例外進入版本控制和程式碼評審；
- 定期刪除不再需要的規則。
安全例外的目標是縮小誤報，不是讓 Agent 獲得通用繞過通道。
怎樣測試而不破壞資料
不要在真實倉庫執行 git reset --hard 或遞迴刪除。可使用臨時測試倉庫和虛擬命令引數，觀察 dcg 的解析輸出。測試至少包括：
- 普通只讀命令被允許；
- 明顯危險命令被阻止；
- 目標範圍明確的清理命令按預期處理；
- 非法 Hook JSON 不會被靜默放行；
- 超時或無法判斷時進入人工確認；
- 原有 Hook 仍正常工作。
為什麼 Hook 不是完整沙箱
Hook 只能檢查它看到的工具呼叫。以下路徑仍可能繞過：
- Agent 寫入指令碼後由其他程序執行；
- IDE 或外掛使用未接入的終端介面；
- 程式透過 API 刪除雲端資源；
- 容器內命令影響掛載的宿主機目錄；
- 憑據洩露後在另一臺機器操作；
- 使用者主動使用
--no-verify。
因此作業系統許可權、容器掛載、雲 IAM、備份和審批仍然必須存在。
更新與回滾
可使用：
|
|
團隊不應在所有開發機上無計劃自動更新規則。先在測試倉庫驗證新版本的誤報和相容性，再分批升級。回滾需要保留舊版本號和配置備份。
故障排查矩陣
| 現象 | 可能原因 | 處理 |
|---|---|---|
dcg 找不到 |
PATH 未更新 | 新開終端並檢查安裝目錄 |
| Codex 不呼叫 Hook | 版本或 hooks.json 路徑錯誤 |
檢查 /hooks 與配置 |
| 原有 Hook 消失 | 合併異常 | 恢復備份，手工合併 |
| 普通命令被攔截 | 規則誤報 | 縮小命令範圍並報告案例 |
| 危險指令碼未攔截 | 實際執行路徑不可見 | 增加 Scan、許可權和沙箱 |
| CI 結果不穩定 | 使用浮動版本 | 固定 dcg 版本和規則 |
它不能解決什麼
Hook 不是作業系統許可權邊界。官方也提示，Agent 可以先寫入指令碼再執行，Codex 的部分統一執行路徑可能尚未全部攔截。因此仍需配合：
- 非管理員賬戶；
- 限定工作目錄；
- Git 分支或工作樹；
- 重要資料備份；
- 刪除和推送操作的人工審批；
- 容器或虛擬機器隔離。
常見問題
安裝器會覆蓋我的 Hooks 嗎？
官方實現會嘗試合併；若現有 JSON 無效或結構異常，會保留原檔案並報告錯誤。安裝前仍應備份配置。
為什麼危險命令沒有被攔截？
檢查命令是否走了受支援的 Hook 路徑。若 Agent 把操作封裝進指令碼、應用內部工具或未覆蓋的執行介面，dcg 可能無法看到最終命令。
dcg 會明顯拖慢每次命令嗎？
專案設計為快速 Hook，並設定絕對處理時間上限。實際延遲仍應在自己的終端和規則集上測量；若明顯變慢，檢查日誌和其他 Hook。
可以只在 CI 安裝，不裝到開發機嗎？
可以掃描倉庫內容，但無法在本地 Agent 真正執行命令前攔截。高許可權 Agent 環境仍建議配置 PreToolUse Hook。
緊急情況下如何處理誤攔截？
先確認命令目標和可恢復性，再由人手動執行或建立最小臨時例外。不要讓 Agent 自動尋找繞過方法。
總結
dcg 能降低 Agent 誤執行危險 Git 和 Shell 命令的機率，尤其適合已經允許 Codex 或 Claude Code 執行終端的環境。但它應被視為安全帶，不是保險箱；真正可靠的方案仍是最小許可權、目錄隔離、備份和人工審批共同生效。