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 发现了什么。
• 仍然被阻止或有风险的内容。
• 存在的证据。
• 用户必须执行的确切下一步命令。

在没有命令输出证明的情况下，不要声称保护、审批或发布就绪状态。