hol-guard

HOL Guard

HOL Guard 可在工具執行前保護本地 AI 工作平台。當使用者需要 AI 防毒行為、本地批准審查、Codex 保護、Claude Code 保護、MCP 安全檢查、技能/套件驗證，或來自 hol-guard 與 plugin-scanner 的發佈閘門時，請使用此技能。

嚴格規則

• 絕不讀取 .env 檔案。
• 絕不繞過 Guard 的批准。
• 在 Guard 命令證明狀態之前，不要將工作區標記為已保護。
• 偏好使用可逆的 Guard 命令，而非直接編輯工作平台配置。
• 除非 hol-guard 命令擁有該變更的所有權，否則不要修改使用者層級的工作平台配置。
• 將掃描器失敗視為真實問題，直到檢查完畢。
• 保留使用者現有的變更，在編輯儲存庫中的內容前，請先檢查 git status --short。

安裝檢查

分別檢查兩個 CLI：

command -v hol-guard
command -v plugin-scanner

如果缺少 hol-guard 且使用者要求執行階段設定，請優先使用：

pipx install hol-guard

如果缺少 plugin-scanner 且使用者要求掃描，請安裝獨立的掃描器發行套件：

pipx install plugin-scanner

不要假設 hol-guard 發行套件會提供 plugin-scanner 命令。如果無法使用 pipx，請說明建議安裝獨立的 CLI，而不是無聲地更改使用者的 Python 環境。

執行階段安裝完成後：

hol-guard status
hol-guard detect --json

保護本地工作平台

以下流程適用於 Codex、Claude Code、Copilot CLI、Cursor、Gemini、Hermes、OpenClaw、OpenCode 或 Antigravity。

hol-guard bootstrap
hol-guard install <harness>
hol-guard run <harness> --dry-run
hol-guard run <harness>
hol-guard status

工作平台名稱：

• codex
• claude-code
• copilot
• cursor
• gemini
• hermes
• openclaw
• opencode
• antigravity

工作平台別名：

• claude 對應到 claude-code
• gemini-cli 對應到 gemini
• open-code 對應到 opencode
• open-claw 對應到 openclaw
• copilot-cli 對應到 copilot

如有可用的工作平台專用啟動指令，請使用：

hol-guard hermes bootstrap

Claude Code

當工作區包含 .claude/settings.local.json、.claude/agents、Claude 鉤子、.mcp.json 或 Claude 管理的工具核准介面時使用此流程。

hol-guard install claude-code
hol-guard run claude-code --dry-run
hol-guard run claude-code
hol-guard doctor claude-code --json

Claude Code 是一級 Guard 目標。優先使用 Guard 擁有的 Claude 鉤子，而非直接手動編輯 Claude 配置。

Codex

當工作區包含 Codex 配置、.codex/hooks.json、Codex MCP 伺服器或 Codex App/CLI 工具流程時使用此流程。

hol-guard install codex
hol-guard run codex --dry-run
hol-guard run codex
hol-guard doctor codex --json

Codex 支援 Guard 擁有的 PreToolUse Bash 鉤子，以及在可行情況下的同聊天 MCP 引出。

其他工作平台

對以下平台使用相同的 Guard 流程：

• Copilot CLI：hol-guard install copilot
• Cursor：hol-guard install cursor
• Gemini CLI：hol-guard install gemini
• Hermes：hol-guard hermes bootstrap
• OpenClaw：hol-guard install openclaw
• OpenCode：hol-guard install opencode
• Antigravity：hol-guard install antigravity

批准作業

如果 Guard 封鎖或排隊工作：

hol-guard approvals
hol-guard approvals open
hol-guard receipts
hol-guard diff <harness>

如果僅能使用終端機解決：

hol-guard approvals approve <request-id>
hol-guard approvals deny <request-id>

只有在閱讀風險原因並瞭解所請求的範圍後，才能批准。

證據作業

當使用者需要證明、稽核軌跡或交接工件時，使用證據命令：

hol-guard receipts
hol-guard inventory
hol-guard abom --format json
hol-guard events
hol-guard explain <artifact-id>

對於雲端同步，請保持選用並由使用者主導：

hol-guard connect
hol-guard connect status
hol-guard connect repair
hol-guard sync

掃描插件或技能套件

對 Codex 插件、Claude Code 專案表面、.agents 市集、技能、MCP 伺服器配置以及發佈閘門使用掃描器模式。

plugin-scanner lint .
plugin-scanner verify .

如果要掃描特定套件：

plugin-scanner lint <path>
plugin-scanner verify <path>

如果目標是包含 .agents/plugins/marketplace.json 的 Codex 市集根目錄，請掃描儲存庫根目錄，以便能夠發現本機插件條目。

掃描器目標指引：

• Codex 插件：掃描包含 .codex-plugin/plugin.json 的儲存庫根目錄或插件資料夾。
• Codex 市集：掃描包含 .agents/plugins/marketplace.json 的儲存庫根目錄。
• Claude Code 專案：掃描包含 .claude/、.mcp.json、鉤子或代理資料夾的工作區根目錄。
• MCP 伺服器套件：掃描包含伺服器配置和套件中繼資料的套件根目錄。
• 技能套件：掃描包含 SKILL.md 的資料夾。
• 混合代理工作區：掃描儲存庫根目錄，以便同時發現本機插件、技能、MCP 和工作平台配置表面。

常見除錯命令

hol-guard doctor
hol-guard doctor <harness> --json
hol-guard detect --json
hol-guard settings show
hol-guard explain install-connect
plugin-scanner verify . --json

回應模式

使用 Guard 時，請回報：

• 執行了什麼命令。
• Guard 發現了什麼。
• 仍有什麼被封鎖或存在風險。
• 有哪些證據存在。
• 如果使用者必須採取行動，下一步的確切命令是什麼。

在沒有命令輸出證明的情況下，不得聲稱已保護、已批准或已準備好發佈。