English | 中文版
把「請 AI 記得守規則」變成會實際攔截的檢查。
Harness Guard 是一套給 AI coding agent 使用的 guardrail kit：提供 5 個 hook、12 套 workflow skills、Claude / Gemini 規則檔範本，以及可重現安裝與 live-fire 驗證腳本。Windows 是本 fork 的主要強化方向。
本 repo fork 自 agentcrew-academy/harness-starter-kit；上游來源、改寫範圍與 attribution 見 FORK.md 與 NOTICE。
提示詞裡的規則會隨長對話被稀釋；hook 則是在 agent 動手前後或準備結束時由程式執行的檢查。
Harness Guard 專注在幾個容易造成實際損失的情境：
- 說「測試過了」卻沒有可對帳的測試紀錄。
- 測試失敗後仍因錯誤的 shell 串接繼續 commit / push。
- 對主分支強推、誤刪根目錄或
.git、把.env/ 私鑰送出去。 - 收工前沒有通過專案指定的 lint / check。
- 需要明確禁止 emoji 的文件或程式碼工作流。
這些 guardrail 是額外防線，不是 sandbox，也不是形式化安全政策。規則以模式比對與 agent hook 介面實作，仍可能有誤判或漏判。
| Hook | 作用 |
|---|---|
claim-guard |
記錄搜尋／測試／改檔等工具證據，結束前對帳完成宣稱；最後一次驗證之後又改過檔，該驗證不算數 |
test-gate-guard |
阻止測試與 git commit / git push 用 ; 或換行錯誤串接 |
danger-zone-guard |
攔截特定災難性刪除、保護分支強推與敏感檔外洩 |
lint-gate |
turn 結束前執行專案指定檢查；Windows 可用 .lint-gate.json 啟用 |
no-emoji-guard |
在指定寫入流程中阻止 emoji；屬偏好型 guardrail，可不安裝 |
完整 hook 介面與平台版本見 hooks/。
同一個 Bash／Read 呼叫連續重複 3 次、中間沒有任何其他工具呼叫時擋下；中間夾一次改檔（或其他被登記的工具）就歸零，所以正常的「跑測試、改檔、再跑測試」不受影響。它逼 agent 換做法，而不是原樣重試。一支檔案同時服務 Claude Code、Codex、Cursor 與 Antigravity，各自用該 agent 的 deny 格式回應；門檻用環境變數 ANTI_DOOM_LOOP_THRESHOLD 調整，任何錯誤一律放行。
它不在預設清單、也不計入上面的 5 個；用 --hooks anti-doom-loop-guard（或 --hooks all）才會安裝。例如只裝它：
python scripts/install.py --dry-run --agent codex --hooks anti-doom-loop-guard
python scripts/install.py --agent codex --hooks anti-doom-loop-guardexplain、polite、first-principles、checkpoint、neat-freak、review-loop、info-diet、asd-ste100、iso-24495、phantom-pushback、verification-protocol、task-orchestrator。
這些是可選的工作流程，不是五個安全 hook 的必要依賴。內容在 skills/。
| Agent / 環境 | Hooks | Skills / Rules | 安裝方式 |
|---|---|---|---|
| Claude Code | 5 個 hook；Windows 會選 Python 版本；另可選裝 anti-doom-loop-guard |
~/.claude/skills/ + CLAUDE 規則範本 |
install.py 自動安裝 |
| OpenAI Codex | 5 個 hook；Windows 用 Python 版並寫入絕對路徑；另可選裝 anti-doom-loop-guard（PreToolUse，只計 shell 指令） |
~/.agents/skills/ |
install.py --agent codex |
| Google Antigravity / Gemini | 5 個 hook 加選裝的 anti-doom-loop-guard，各自登記為 hooks.json 裡的具名 hook：PreToolUse 可否決、Stop 可用 continue 擋下結束；claim-guard 查驗端靠讀 transcript，格式官方未文件化（見 docs/antigravity-install.md） |
skills + GEMINI.md 範本 |
install.py --agent antigravity 安裝 skills；--hooks <名稱> 安裝 hook |
| Cursor | 5 個 hook，寫入 ~/.cursor/hooks.json（Cursor 扁平格式）；另可選裝 anti-doom-loop-guard（preToolUse） |
~/.cursor/skills/；若本機已有 ~/.agents/skills/ 也會一併合併 |
install.py --agent cursor |
因此 --agent all 目前代表 Claude Code + Antigravity + Cursor + Codex。Cursor 的 stop 不能否決已結束的回合，所以 claim-guard / lint-gate 在 Cursor 上改為 follow-up，不是 veto。
先預覽，不修改任何設定：
python scripts/install.py --dry-run --hooks all --skills all確認後正式安裝：
python scripts/install.py --hooks all --skills allpython scripts/install.py --dry-run --agent antigravity --skills all
python scripts/install.py --agent antigravity --skills all不帶 --hooks 時 Antigravity 只裝 skills。要裝 hook，明確指定名稱（danger-zone-guard、test-gate-guard、no-emoji-guard、claim-guard、lint-gate、anti-doom-loop-guard，或 all）：
python scripts/install.py --dry-run --agent antigravity --hooks danger-zone-guard,test-gate-guard,no-emoji-guard,claim-guard,lint-gate
python scripts/install.py --agent antigravity --hooks danger-zone-guard,test-gate-guard,no-emoji-guard,claim-guard,lint-gate會把腳本放進 ~/.gemini/config/hooks/，並在 ~/.gemini/config/hooks.json 合併一筆以 hook 名稱為 key 的登記（先備份到 ~/.gemini/backups/、寫完讀回驗證）。Antigravity 的 hook 命令可能被它自己直接切字串（內建文件寫的是 cmd /c／sh -c，但沒有保證能去引號），所以命令不加引號，路徑也不能含空白，兩種解讀下都能執行；含空白時安裝器會拒絕，請用 --gemini-dir 指到沒有空白的位置。hooks.json 若還留著 Claude Code 版面的頂層 hooks 區塊（Antigravity 會整份拒絕），安裝器直接拒絕寫入並說明，不會假裝裝好。herdr 自己的 herdr-agent-state.ps1 不在安裝範圍內。細節與每個 hook 的限制見 docs/antigravity-install.md。
python scripts/install.py --dry-run --agent cursor --hooks all --skills all
python scripts/install.py --agent cursor --hooks all --skills allCursor 使用者層 hook 寫在 ~/.cursor/hooks.json。shell 攔截走 beforeShellExecution；emoji 攔截走 preToolUse（Write）；anti-doom-loop-guard 走 preToolUse（Shell|Read|Write|Delete）。細節見 docs/cursor-install.md。
python scripts/install.py --dry-run --agent codex --hooks all --skills all
python scripts/install.py --agent codex --hooks all --skills all安裝器會合併進既有的 ~/.codex/hooks.json，並使用絕對路徑的 python／python3，避免 Windows 上 python3 ~/.codex/hooks/... 那種無聲失敗。skills 依 Codex 現行使用者層契約安裝到 ~/.agents/skills/；既有的 legacy ~/.codex/skills/ 不會自動刪除或搬移。
Hooks 預設啟用；若曾關閉，請在 config.toml 設定 [features].hooks = true。新增或修改註冊後，在 Codex 執行 /hooks 檢視並信任目前定義。verify-install.py 會直接 live-fire 腳本，但不能代替 TUI 的 trust 檢查。
python scripts/install.py --dry-run --agent all --hooks all --skills all
python scripts/install.py --agent all --hooks all --skills all安裝程式會盡量合併而不是覆蓋既有設定；Claude Code 正式寫入前會備份 settings.json。既有同名 skill 預設不覆蓋，除非明確使用 --force。
但 hook 腳本本身是整支覆蓋的，所以「直接改腳本裡的設定」會在下次安裝時被洗掉，而且是往「又開始擋了」的方向洗，不會有任何提示。要能撐過重裝的設定放在腳本旁邊的 JSON 檔，安裝程式永遠不碰那些檔案：
.lint-gate.json 也是同樣的道理，只是它放在專案根目錄。設定檔壞掉時一律回到內建預設（也就是繼續擋），因為打錯字不該變成一種悄悄關掉護欄的方式。
Claude Code hook 安裝後，重新啟動 agent，再跑：
python scripts/verify-install.py這支工具不只讀設定檔，而會對已安裝 hook 餵合成 payload，確認它真的執行並產生預期的 allow / block 行為。exit code 0 才代表它檢查到的項目通過。
它主要驗證 Claude Code hook 與 Antigravity skills 目錄，並在本機已安裝時檢查 Cursor / Codex 的設定檔與 live-fire 行為；anti-doom-loop-guard 在四個 agent 上都會用各自的 payload 與 deny 格式 live-fire。Antigravity 已登記的每個 hook 都會檢查登記版面並用 Antigravity 形狀的 payload live-fire 一次放行、一次攔截。
Windows 原生環境不要直接使用依賴 jq 的 shell 版本。安裝器會替 Claude Code 選擇 Python 版本，避免 hook 因 jq 缺失或 WSL bash 路徑而 fail-open。
詳細說明見 docs/windows-install.md。Antigravity / Gemini 見 docs/antigravity-install.md。
這個 repo 的程式會修改 agent 設定，且 hook 會攔截後續操作。安裝任何網路下載的 guardrail 前，都應先閱讀腳本或要求 agent 解釋它會：
- 複製哪些檔案。
- 修改哪些設定。
- 在什麼事件阻擋操作。
- 如何停用與移除。
不需要全裝。先裝真正對你的風險有價值的 guardrail，比把所有規則堆進 agent 更好。
可以把這個 repo 網址交給 AI coding agent，請它先閱讀 AGENTS.md，用白話解釋要改哪些檔案，先執行 dry-run，再逐項安裝。不要要求 agent 略過預覽與驗證。
本 repo 的 CI 會在 Linux 與 Windows 執行核心 Python syntax / regression checks、安裝器 dry-run 契約測試，以及既有 hook 測試。
主要回歸測試：
python hooks/danger-zone-guard/tests/run-tests.py
python hooks/test-gate-guard/tests/run-tests.py
python hooks/tests/run-encoding-tests.py
python -m unittest discover -s tests -p "test_*.py"維護與安裝規則見 AGENTS.md；版本沿革見 CHANGELOG.md。
這五個 repo 各自治理 AI coding 的一層，可以單獨用，也可以疊起來用：
| 層 | Repo | 做什麼 |
|---|---|---|
| 供應鏈 | SkillSpector | 裝進來之前先掃：agent skill 的漏洞與惡意樣式偵測，輸出風險分數與 SAFE／CAUTION／DO_NOT_INSTALL 建議 |
| 派工決策 | agent-advisor | 風險分流路由 solo／delegate／audit／full：決定這件事要不要派工、派給誰 |
| 動作攔截 | Harness Guard（你在這裡） | agent runtime hook，在動手前後與收工時實際攔截危險指令、無證據宣稱、紅燈提交 |
| 產出品質 | ai-quality-gates | 可執行規格與量化門檻：覆蓋率、突變測試、圈複雜度、依賴結構、有界 loop policy |
| 交付流程 | paulsha-cortex | 多 Agent lifecycle：Candidate → Verify → Independent Review → Delivery → CompletionRecord |
相鄰但不同層：agent-governance-toolkit 治理的是上線後自主運行的 agent——政策強制、零信任身分、沙箱執行與可稽核記錄——不是寫程式的 coding agent。opencodex 是供應商代理，決定這些 agent 背後能跑哪些 LLM，本身不約束 agent 行為。
本 repo 是 agent-relay 多 Agent 派工與驗收流水線的一環（角色：阻擋 hook）。與 agent-relay 的整合規劃中（Phase 3）。協定規格與所有相關 repo 的總目錄見 agent-relay。
MIT License，見 LICENSE。原作者、fork 來源與改寫自其他作品的 attribution 見 NOTICE。