GouvernAI — Claude Code 运行时护栏插件
为 Claude Code 提供分级风险管控：安全操作自动放行、高风险操作暂停审批、危险操作确定性硬拦截，并保留完整审计日志。
证据显示分层最小权限设计（T1-T4、硬约束NEVER规则、凭据不外传、防自修改、fail-closed、日志不记录密钥值），MIT许可、威胁模型坦诚披露MCP绕过等局限。扣分项：静态审查中强制脚本guardrails-enforce.py本体未提供，无法核验其行为与声明一致；日志默认对用户静默（仅/guardrails log可见）降低了实时透明度；发布者身份未经验证，归属链条不完整。
仓库含大量结构良好的hook单元测试（含回归测试、字段强制、fail-closed用例），文档自洽、错误处理明确。扣分项：静态审查不执行，未运行测试；存在的CI工作流仅做版本守卫，未运行测试套件；README承认已知上游bug需手动/gouvernai激活hooks，关键路径存在已知的部署摩擦。
触发条件、排除清单、非适用范围（MCP绕过、Windows PowerShell模式不覆盖、模型依从性差异）表述清晰，分级目录具体。扣分项：文档全英文，无中文支持声明；针对Claude Code专用环境，跨平台和跨模型适配证据有限。
分层文档架构（SKILL.md+按需加载参考文件）是渐进式披露的良好范例；MIT许可、版本守卫CI保证plugin.与marketplace.一致、安装/卸载说明完整、局限披露详尽。扣分项：无CHANGELOG、无明确维护责任声明与更新承诺；发布者为未验证个人账户。
解决的问题真实（默认权限提示过噪 vs 完全跳过无防护），双重执行设计有边际价值。扣分项：静态审查无法验证实际分类准确率（~90%为作者自述）、截图不可核验、核心价值主张需运行时确认；静默日志设计可能让部分用户失去预期反馈。
有可审计的主材料：完整测试套件、威胁模型、引用的上游issue和CVE背景。扣分项：无第三方独立执行证据；测试通过率徽章（120+ passing）无对应测试CI工作流佐证；~60%自动放行比例和~90%依从率均为不可复现的作者声明。
- 强制执行脚本guardrails-enforce.py未包含在本次审查文件中，安装前请自行审计源码（README本身也如此建议）。
- 已知Claude Code上游bug导致hooks可能不自动加载，需每次会话手动运行/gouvernai，否则确定性拦截层不生效，仅剩概率性技能层。
- MCP工具调用完全绕过hook层，仅靠模型自律分类，无硬性兜底。
- 审计日志默认静默，用户需主动运行/guardrails log查看；对该行为有预期者请知悉。
- 对钩子模式的规避手段（非密钥文件变量暂存、新型混淆、提示注入）已被作者明确列为不防护范围，请配合网络出口策略与密钥保管等纵深防御。
- 发布者身份未经验证；仓库无CHANGELOG，更新轨迹依赖版本号。
这个 Skill 能做什么，适合哪些场景？
GouvernAI 是一个 MIT 协议的 Claude Code 插件，解决权限提示一刀切的问题——既不像默认提示那样打断每个操作，也不像 --dangerously-skip-permissions 那样毫无防护。它采用双重执行：技能层（SKILL.md 及 ACTIONS/TIERS/POLICY 参考文件）让模型按 T1–T4 风险分级做判断，钩子层（PreToolUse 调用 guardrails-enforce.py）确定性拦截混淆命令、凭据外泄和灾难性操作，即使模型跳过技能也无法绕过。所有策略文件是可读可编辑的纯 Markdown，所有被管控的操作都会写入项目根目录的 guardrails_log.md。支持 strict/relaxed/audit-only 模式和 token 上限治理。
通过 PreToolUse 钩子在每次 Bash/Write/Edit/Read 调用前运行 guardrails-enforce.py，检测混淆命令、凭据外泄（.env 等敏感文件读后外传）、rm -rf / 等灾难命令、文件写入中的硬编码密钥以及对护栏自身的自修改，违规时以退出码 2 硬拦截。技能层引导模型执行 8 步门控流程：识别操作、读取 guardrails-mode. 确定模式、按 ACTIONS.md 分级、按 TIERS.md 升级（批量 5+ 目标或陌生接收方升一级）、检查预批准、按 POLICY.md 检查硬约束、执行管控、静默追加 guardrails_log.md。还支持变量暂存后外传、碎片化提取密钥等多步渗出模式检测，以及 /guardrails tokencap 设定的载荷 token 上限（约 4 字符≈1 token 估算）。
- 使用 --dangerously-skip-permissions 追求速度的个人开发者，希望在不牺牲速度的前提下恢复分级安全防护——这是该插件价值最大的场景
- 运行 CI、cron 或无人值守任务时需要 T2/T3 自动执行但 T4 必须停止的用户，可切换到 /guardrails audit 模式
- 担心模型在生成文件或配置时不小心硬编码 API 密钥的工程师，钩子层会在文件写入时硬拦截已知密钥格式
- 需要向团队提供统一审批流程和可审计策略文件的负责人，模式配置持久化在 guardrails-mode.，跨会话保留
- 对 API 成本敏感的重度用户，可设置 token 上限，超限的大载荷操作会像 T3 一样暂停等待批准
这个 Skill 有哪些优点和局限？
- 双重执行：钩子层确定性硬拦截即使模型忽略技能层也无法绕过，解析失败时默认拦截而非放行
- 策略全部是可读可编辑的纯 Markdown，区别于 Anthropic auto mode 不可检查的内部分类器
- 完整审计日志记录每项操作的分级、结果与升级原因，适用于团队治理
- 支持 strict/relaxed/audit-only 模式和 token 上限，且有 120+ 通过的钩子单元测试，零依赖
- 威胁模型文档诚实，明确列出确定性防护与尽力而为防护的边界
- PreToolUse 钩子无法拦截 MCP 工具调用，MCP 操作只有技能层的语言性管控，无确定性兜底
- 受 Claude Code 已知缺陷影响，钩子在部分平台不能自动加载，每次会话需手动 /gouvernai 激活
- 技能层分级合规率依赖模型（在 Opus 4.6 / Sonnet 4.6 上测试可靠，约 90%；较小模型如 Haiku 可能较低）
- 钩子模式针对 Unix/Bash 语法，PowerShell 等效命令不覆盖；多步渗出若用非关键词变量名或碎片提取则检测不到
- 每次工具调用钩子增加约 10ms 开销；token 估算是约 4 字符/token 的粗略启发式，不适合计费核算
- 它本质是操作安全与治理层而非安全边界，无法防御针对性强攻或新型混淆手法
如何安装这个 Skill？
在终端运行：claude plugin marketplace add Myr-Aya/GouvernAI-claude-code-plugin，然后 claude plugin install gouvernai@mindxo（默认用户作用域，推荐；仅在信任项目所有贡献者时用 --scope project 安装到项目作用域）。由于 Claude Code 存在钩子不能自动加载的已知缺陷，安装后每次会话需输入 /gouvernai 手动激活钩子；更严格的做法是把钩子配置手动复制到 ~/.claude/settings.，并把 ${CLAUDE_PLUGIN_ROOT} 替换为绝对路径。
如何使用这个 Skill？
会话开始时运行 /gouvernai 激活双执行层。之后大多数操作自动放行；T2（文件写入、git commit）自动批准并简短通知；T3（npm install、curl、邮件）暂停等待批准；T4（sudo、凭据传输、批量删除）需风险评估后批准。用 /guardrails 查看会话统计，/guardrails strict 或 relaxed 切换模式，/guardrails audit 用于无人值守，/guardrails tokencap <n> 设置 token 上限，/guardrails log 查看审计日志。模式写入 guardrails-mode.，跨会话持久。
这个 Skill 与同类方案有什么区别？
对比 Claude Code 默认权限提示：默认对读写删除一律打断，GouvernAI 按风险分级只对高风险操作加摩擦。对比 Anthropic auto mode：auto mode 的分类器不可检查且仅限 Team/Enterprise 计划，GouvernAI 策略透明可编辑、任何计划可用，且其 PreToolUse 钩子先于 auto mode 分类器运行。对比 --dangerously-skip-permissions：后者零安全网，GouvernAI 在此基础上恢复分级防护，价值最大。