global-agent-guardrails

全局 Agent 防护措施

在执行前拦截灾难性 Shell 命令。一份模式文件供所有 Agent 共用的钩子脚本或原生适配器使用。这可以防范意外操作，但无法防范恶意 Agent（例如，python -c "shutil.rmtree(...)" 这样的混淆代码可能绕过正则表达式）。

Cloudroom 内置了基于此方案的 Command Guard，且默认启用。

文件映射

此配置由一份共享模式列表、一个防护脚本、一个测试套件和特定于 Agent 的适配器组成。请将它们放在工具对应的用户级配置位置。

检查安装情况

确认共享防护脚本和模式文件均已就位，然后运行测试套件；测试结果应显示没有失败项。

如果文件缺失，请根据项目文档中的接线说明重新构建。

添加或调整模式

1. 编辑共享模式文件。使用 POSIX ERE（grep -E）。使用 [[:space:]]，不要使用 \s——适配器可能会将 [:space:] 转换为 JS/Python 中的 \s，并以多行模式编译。
2. 在测试套件中添加拦截和放行用例，然后运行测试；所有测试都必须通过。
3. 确认新模式可在每个适配器的正则表达式引擎中编译。
4. 使用方应在每次执行命令时重新读取模式。如果 Agent 使用原生拦截列表，请酌情同步相应更改。

只拦截灾难性命令（不可逆的数据丢失、磁盘擦除、仓库删除）。可恢复的本地命令应保持允许；避免过度拦截。

各 Agent 接线配置（用户全局）

通过每个 Agent 文档中介绍的钩子或原生命令拦截机制进行配置。在支持的情况下，将钩子指向共享防护脚本；应将设置合并到现有配置中，而不是覆盖配置。如果路径展开行为不一致，请在配置中使用绝对路径。

注意事项

• 某些 Agent 会将钩子信任状态与配置内容绑定。更改钩子配置后，请遵循 Agent 文档中规定的信任或审批流程。
• 某些后台或工作环境无法执行本地钩子脚本。请查阅 Agent 文档，了解其失败时的行为和限制。
• 不同 Agent 的插件钩子清单、启用方式和失败行为各不相同；请保持适配器简洁，并遵循各工具的公开文档。
• 适配器应妥善处理错误，避免模式文件损坏时意外拦截所有命令。
• 原生拦截列表的语义各不相同：有些条目会要求确认，有些则会阻止执行。对于灾难性命令，应使用适当的最强机制。
• 确保防护脚本从每个集成所用的载荷格式中读取命令。
• 适配器正则表达式可能需要启用多行模式，这样 ^ 才会像 grep 一样匹配每一行 Shell 命令。
• 误报类别： 如果无害命令的参数文本中包含看似危险的字符串，该命令可能会被拦截。解决方法：将文本放入文件，并在命令中引用该文件。
• 某些 Agent 或远程／后台执行环境可能不支持本地钩子。请查阅相关 Agent 文档，了解当前支持情况。

端到端验证

在临时的非 Git 目录中使用安全探测：要求 Agent 运行一个如果执行就会被拦截的命令。防护拦截表示防护生效；仓库上下文错误则表示探测未能测试防护。

直接运行防护脚本的测试套件，确认灾难性命令会被拦截。