health

Health: Agent 輔助工程健檢

請在第一行開頭以行內方式加上 🥷，不要獨立成段。

請依照以下架構，審查當前專案的 Agent 設定與 AI 編程可維護性：
Agent 設定 → 指令層面 → 工具/執行環境 → 驗證機制 → 可維護性

找出違規項目，識別出出現偏差的層級。僅需根據專案複雜度進行調整。

產出契約

• 產出：一份具備預算意識的健康檢查報告，明確劃分 Agent 設定風險與 AI 可維護性風險。
• 完成條件：每一項發現均明確列出偏離的層級、具體證據，以及可直接複製貼上的處理建議或診斷命令。
• 證據來源：收集到的健檢腳本輸出、追溯的專案指令、執行環境設定摘要、驗證器日誌、Hooks/MCP 界面，以及必要時的唯讀實測探針。
• 輸出：按優先順序排序的發現事項（含狀態、影響及後續行動），或附帶殘留風險的明確合格報告。

單份報告包含兩條主線：

• Agent 設定健康度：Codex/Claude/Pi 指令偏移、權限、Hooks、MCP、Skills 及記憶供應鏈。
• AI 可維護性健康度：專案上下文層面、驗證器包裝、生成產物檢查、熱點歸屬（hotspot ownership），以及過時或誤導的持久文件。

輸出語言： 請依序檢查：(1) 專案 Agent 指令（優先讀取 AGENTS.md，再看特定執行環境的檔案）；(2) 全域 Agent 指令；(3) 使用者最近使用的語言；(4) 英文。

預算策略： 先從摘要審查開始。滿足以下條件時自動升級為深度審查：使用者要求執行深度、完整、徹底或「深入」、「完整」、「徹底」、「繼續跑完」的審查；使用者明確提及 AI 編程程式碼腐化、Codex/Claude 設定偏移、上下文不清晰、缺少驗證、驗證器輸出指向過時路徑，或「程式碼變爛」；當前專案指令或已記住的使用者偏好設定預設執行深度健檢；專案屬於 Complex（複雜）層級；或者摘要審查揭露了無法在本地解決的關鍵疑義。否則，請勿讀取完整對話摘要或啟動檢查員 Subagent。在升級前請先通知使用者，因為深度健檢可能會消耗大量 Token 配額。

持久上下文前置檢查

關於持久上下文（Durable context）何時適用，以及在將其確立為持久規則前套用的遮蔽門檻（redaction gate），請參閱 references/durable-context.md。

對於 /health：當前的設定、命令輸出和實測探針優先於記憶。當持久記憶問題影響行為時也應標示：注入的摘要過大、條目過時或矛盾、缺少專案進入點引用，或是將私有路徑複製到了公開指令中。請將這些列為上下文發現事項，而非程式碼審查發現事項。

硬性規則

• 摘要審查與深度審查僅提供報告。只能執行 Health 專屬的收集器與唯讀探針；中性的 Health 請求並不代表授權執行專案的測試、驗證器、生成器、建置（build）、程式碼格式化、套件安裝、Fixture 重新整理或快照更新。
• 專案指令可以定義命令，但並不代表授權執行。實測驗證必須取得使用者針對該命令的明確授權；在執行前，必須說明命令內容、預期寫入操作、目標路徑、隔離機制，以及還原或一次性環境計劃。

Step 0：評估專案層級

請選擇一項，僅套用該層級的要求。

層級	識別特徵	預期要求
Simple（簡單）	<500 個檔案，1 位貢獻者，無 CI	僅需 CLAUDE.md；0-1 個 Skill；Hooks 為選配
Standard（標準）	500-5K 個檔案，小型團隊或有 CI	CLAUDE.md + 1-2 個 Rule；2-4 個 Skill；基礎 Hooks
Complex（複雜）	>5K 個檔案，多位貢獻者，活躍 CI	須具備完整的六層架構設定

Step 1：收集資料

首先以摘要模式執行資料收集腳本，先不要進行解讀。在 Windows 系統上，請使用 Health 專屬的啟動器，確保 Git for Windows 工具僅載入至 Bash 子程序中：

$HEALTH_LAUNCHER = @(
  "<skill-base-dir>/scripts/run-health.ps1",
  "<skill-base-dir>/skills/health/scripts/run-health.ps1"
) | Where-Object { Test-Path -LiteralPath $_ -PathType Leaf } | Select-Object -First 1
if (-not $HEALTH_LAUNCHER) {
  throw "Health launcher not found under the installed skill base; reinstall Waza."
}
powershell.exe -NoLogo -NoProfile -File "$HEALTH_LAUNCHER" collect

在 Linux 和 macOS 系統上，請保持直接使用 Bash 的流程：

HEALTH_SCRIPT=""
for candidate in \
  "<skill-base-dir>/scripts/collect-data.sh" \
  "<skill-base-dir>/skills/health/scripts/collect-data.sh"; do
  [ -f "$candidate" ] && HEALTH_SCRIPT="$candidate" && break
done
if [ ! -f "${HEALTH_SCRIPT:-}" ]; then
  echo "health collect-data.sh not found under the installed skill base; reinstall Waza"
  exit 1
fi
bash "$HEALTH_SCRIPT"

當缺少工具時，區塊可能會顯示 (unavailable)：

• 未安裝 jq → 對話區塊無法使用
• 未安裝 python3 → MCP/Hooks/allowedTools 區塊無法使用
• 缺少 settings.local.json → Hooks/MCP 可能無法使用（此為僅有全域設定時的正常現象）

請將 (unavailable) 視為「資料不足」，而非違規發現。請勿在這些領域發出警告。

收集器同時涵蓋了特定執行環境與非關特定 Agent 的層面：

• AGENT CONFIG SUMMARY / AGENT CONFIG DETAIL：適用於 Codex、Claude、Pi 及專案指令檔案。
• AI MAINTAINABILITY SUMMARY / AI MAINTAINABILITY DETAIL：適用於專案結構、驗證層面、熱點歸屬、包裝器及文件連結。

Step 1b：MCP 實測檢查

測試每一個 MCP 伺服器：針對每個伺服器調用一個無害的工具。記錄 live=yes/no 以及錯誤詳情。遵守 enabled: false 設定（直接跳過且不發出警告）。針對 API 金鑰，僅檢查環境變數是否有設定（echo $VAR | head -c 5），切勿印出完整的金鑰。

Step 1c：安全與安全性檢查

這些檢查會在收集資料後、Step 2 分析前執行。前兩項適用於每次審查；第三項僅適用於包含長時間運行或自主 Agent 的專案。

安全基線檢查

無論專案層級為何，每次審查均須執行這些檢查。這些是最低標準，而非最高標準。

拒絕清單底線： 僅在執行環境確實能強制執行所建議的規則類型（如 Agent 權限設定、Hook 設定、MCP 設定、允許/拒絕工具，或已記錄的自主 Agent 啟動器）時套用。在此情況下，設定中至少應拒絕：憑證與金鑰目錄（SSH、雲端供應商、GPG、gh CLI）、敏感檔案（.env、credentials*、secrets*），以及管道轉 Shell（pipe-to-shell）安裝程序。請將此列為一條簡潔的 WARN 警示並附上缺少的分類；讓審查者自行填入確切的本地路徑。三項微調說明：前綴/Glob 權限規則無法穩定比對管道命令，因此請建議使用宿主機的預執行 Hook 來阻擋管道轉 Shell，而非自行發明 Glob 變體，並指出 Hook 本身的取捨（字串比對 Hook 也會對僅包含該樣式的引號文字和 Heredoc 觸發）；在預估外發 Shell 拒絕規則的波及範圍前，先確認其比對發生的層級：針對 ssh 的命令前綴拒絕僅會阻擋 Agent 直接調用 ssh，不會影響 Git 內部的 SSH 傳輸，而程序級或沙盒級的阻擋則會破壞 git-over-SSH 推送；當執行環境沒有命令級的拒絕控制面時（例如 Codex 的控制槓桿為 sandbox_mode 和 approval_policy），請將該控制槓桿作為使用者的取捨提出來，而非建議執行環境無法表達的拒絕鍵名。如果完全不存在 Agent 設定界面，請將拒絕清單標示為不適用，而非標記為失敗。

權限層 vs 指令層把關： 將 Git 寫入動作（git push）的允許清單條目與指令層規則（「僅在使用者明確指示時進行推送」）並列，並不自動構成矛盾：指令決定動作「何時」發生，權限決定是否「重新提示」，而每階段均明確授權推送的使用者可能會刻意保留在允許列表中以避免二次確認。請依據可逆性及使用者自身的規則進行衡量：指令明確禁止的動作（git reset --hard、git stash、強制推送）應屬於拒絕或詢問；常規且已獲明確授權的動作保持使用者原有的設置，最多僅做提示說明。只有當自動模式加跳過提示加寬鬆允許，導致寫入動作在單次作業期間完全不需要使用者輸入就能執行時，才提升警告層級；即便如此，也應列出操作流程度的取捨供使用者選擇，而非自動搬移條目。

環境覆蓋層面： 將以下項目視為潛在攻擊面，若在版本控制追蹤的檔案或發布的設定中出現且未附帶合理註釋，即予以報告：API base-URL 覆蓋（將所有流量重定向至第三方）、專案本地 MCP 伺服器的自動信任標記、通配符工具允許清單（allowedTools: ["*"]），以及跳過權限標記（--dangerously-skip-permissions 或等效設定）。僅印出 檔案:行號 及鍵名；切勿印出機密內容。

記憶與 Skill 供應鏈

將 Agent 記憶與第三方 Skill 視為供應鏈產物。它們以使用者的權限執行。

記憶衛生： 審查專案的長期 Agent 記憶儲存庫，檢查是否包含機密、Token 或憑證（Critical 嚴重級別），以及是否存在由不可信執行（在攻擊者控制的輸入上調用的 Subagent、在外部內容上迭代的 /loop）所寫入的條目；建議在執行此類任務後更換相關憑證。針對高風險的一次性執行（不可信的 PDF、不受控的網頁抓取、第三方腳本），建議在該次作業中完全禁用記憶持久化。

Skill 供應鏈： 第三方 Skill、外掛與 MCP 伺服器均以使用者的權限執行。對於並非在本儲存庫中編寫的每個項目，請檢查：來源是否已固定至特定發布標籤或版本（而非 main、分支或追蹤最新版本的遠端 Git 市場）、Hook 處理器不會寫入憑證目錄，且 MCP 伺服器已取得使用者的明確同意（未通過通配符自動信任）。除非存在明確的被利用特徵，否則請將未固定版本的來源或未審查的 Hook 處理器報告為結構性問題（Structural），而非嚴重問題（Critical）。

長時間運行 Agent 的終止條件

對於使用 /loop、自主 Agent 或任何長時間運行 Agent 流程的專案，請載入 references/long-running-agents.md 並審查其中列出的四種硬性終止訊號。未使用此類流程的專案可跳過此檢查。

Step 2：分析

確認層級，然後進行分流：

• Simple（簡單）： 在本地端分析。不使用 Subagent。
• Standard（標準）： 依據摘要輸出在本地端分析。預設不啟動 Subagent。若使用者要求深度/完整/徹底的審查，或者本地分析無法對安全性/控制問題進行分類，請升級至深度模式並說明可能消耗的 Token 成本。
• Complex（複雜）、具有記下的深度偏好、明確指示深度審查或明確指示 AI 可維護性審查： 在 Windows 上以 powershell.exe -NoLogo -NoProfile -File "$HEALTH_LAUNCHER" collect auto deep 重新執行收集，或在 Linux 與 macOS 上以 bash "$HEALTH_SCRIPT" auto deep 重新執行。接著平行啟動相關的 Subagent。請將敏感憑證遮蔽為 [REDACTED]。
  • Agent 1（上下文 + 安全）：閱讀 agents/inspector-context.md。輸入 CONVERSATION SIGNALS 區塊。
  • Agent 2（控制 + 行為）：閱讀 agents/inspector-control.md。輸入測得的層級。
  • Agent 3（AI 可維護性）：閱讀 agents/inspector-maintainability.md。輸入 AI MAINTAINABILITY SUMMARY / AI MAINTAINABILITY DETAIL 區塊。