规则配置文件位置
CC Safety Net 从两个范围加载rulebook并合并它们：- 用户范围 —
~/.cc-safety-net/rules/rule.json（使用rule init --global创建）。将此用于适用于每个项目的个人默认值。 - 项目范围 — 项目根目录中的
.cc-safety-net/rules/rule.json。将其用于特定于团队或项目的规则，你可以提交到版本控制。
project-rules 等裸名称引用。 GitHub rulebook源使用 owner/repo#ref/<rulebook-name> 并指向该存储库中的 .cc-safety-net/rules/<rulebook-name>/rulebook.json。
范围合并行为
- 两个范围的 rulebook被合并，首先是用户范围。
- 重复的活动rulebook 名称由第一个声明解析。 首先加载用户范围，因此它声明的名称会影响同名的项目rulebook；后面的 rulebook根本没有提供任何规则，而不是部分模仿第一个rulebook。冲突被报告为警告，这会将运行时置于
degraded状态 - 重命名其中一个并运行rule sync。由于冲突已解决而不是致命的，因此一个作用域的rule sync仍然会在另一个作用域已使用的名称上成功。 - 每个范围的
overrides适用于该范围自己的规则。 命名用户范围规则的项目覆盖将被忽略并显示警告，并且该规则保持其用户配置状态 - 项目配置无法禁用或重写用户规则。 - 与已知规则不匹配的覆盖键将被忽略并发出警告；其他覆盖和规则保持其配置状态。
- 两个范围的
transparent_wrappers联合。
管理rulebook源
rulebook源由rule.json 的 rules 数组中的条目引用。有两种：
- 本地来源 — 一个简单的名称，如
project-rules。rulebook位于.cc-safety-net/rules/project-rules/rulebook.json（项目）或~/.cc-safety-net/rules/project-rules/rulebook.json（用户）。本地源必须保留在其配置目录中。 - GitHub 源 -
owner/repo#ref/<rulebook-name>，指向该存储库和参考中的.cc-safety-net/rules/<rulebook-name>/rulebook.json。
rule 命令添加、更新和删除源，而不是手动编辑 rule.json 和lockfile：
--global（-g）以对用户范围而不是项目范围进行操作。请参阅 CLI 命令 了解每个 rule 子命令、其选项及其退出行为。
资源限制
rules 数组每个范围最多可容纳 64 源。具有更多条目的 rule.json 无法通过单个错误 Rule config exceeds CC Safety Net's safe source limit. 进行验证 - 过大的数组没有逐项逐项列出，并且整个范围的配置像任何其他无效的 rule.json 一样被删除。
rule sync 在固定预算下运行：它同时处理最多 4 源，一次运行最多发出 131 GitHub 请求，并在所有源中读取最多 64 MiB 响应字节。超出预算会停止 Rule synchronization exceeds CC Safety Net's safe resource limits. 的运行
锁定和缓存
每个配置的源都通过 SHA-256 digest固定在rule.lock 文件中，其rulebook 缓存在 .cc-safety-net/cache/rulebooks/ 下。在运行时，CC Safety Net 根据digest验证缓存的 rulebook，并且在验证期间不会写入、获取或缓存任何内容。
验证失败时会发生什么取决于哪一侧损坏：
- 缺少锁文件、缺少锁条目、缺少缓存条目、digest不匹配或无法解析的缓存的 rulebook会删除该源。在你运行
rule sync之前，它不会贡献任何规则。所有其他经过验证的源和每个内置保护都会继续应用，普通命令也会继续运行。删除的源会将运行时置于degraded中，而不是阻塞工作。 - 偏离其固定 digest 的本地源（包括磁盘上丢失、无法解析或模式无效的源）不是故障状态。运行时仅读取经过 digest 验证的缓存 rulebook，而不会重新读取本地副本。在运行
rule sync之前，待处理的本地编辑不会处于活动状态。完整的rule sync和rule verify仍然拒绝无效或符号链接的本地源。
透明包装器
如果你的团队通过rtk 等包装器运行命令，则分析默认会看到包装器，而不是下面的命令。在 transparent_wrappers 中列出包装器可以让 CC Safety Net 查看可见的受保护子命令，因此内置分析和自定义规则都适用于 rtk git reset --hard 和 rtk docker system prune ，就像它们适用于裸命令一样。
使用 rule wrapper 子命令配置包装器，而不是手动编辑 rule.json：
- 没有内置默认值。 仅配置你有意信任的包装器。
- 包装器名称必须与
^[a-zA-Z][a-zA-Z0-9_-]*$匹配，并且在文件中必须唯一。 - 保留命令不能是包装器：
git、busybox、内置分析命令rm、find、xargs和parallel、每个 shell 包装器、每个解释器和 awk 解释器。 - 解包在包装器标志和
VAR=value分配之后找到第一个“可保护”子命令，或者紧接在显式--之后的标记。本身无法保护的孩子不会被解开。 - 这里未列出的包装器，或者重写或隐藏其子命令而不是执行可见子命令的包装器，仍然没有解包。只有顶级危险文本回退扫描可以捕获此类命令。
创建你的第一个自定义规则
创建启动项目规则配置：.cc-safety-net/rules/rule.json — 其中尚未配置 rulebook 源：
--example 以在 .cc-safety-net/rules/example-rules/rulebook.json 处编写非活动示例rulebook。仅当该文件尚不存在且 rule init 不引用它时才会写入它，因此你必须将其添加为源以使其处于活动状态：
.cc-safety-net/rules/project-rules/rulebook.json 并将其注册到 npx -y cc-safety-net rule add project-rules。这使得 rule.json 看起来像这样：
rule sync 使编辑的 rulebook处于活动状态。 rule verify 然后检查活动配置。
现在，你的自定义消息将阻止 git add -A、git add --all 和 git add .。
rule.json schema
顶层 rule.json 选择哪些rulebook处于活动状态、应用覆盖并声明透明包装器。它与 policy.json 分开，policy.json 配置安全级别、内置保护、允许和拒绝路径以及审计保留 — 请参阅该文件的策略。
integer
必填
schema版本。必须是
1。object
规则覆盖由
<rulebook-name>/<rule-name> 键入的规则。值可以是用于禁用规则的 "off"，也可以是用于替换规则的阻止消息的对象。对象形式需要 reason 并接受可选的 intent；省略的 intent 会使规则本身的意图保持不变。rule.json 编辑器支持
CC Safety Net 发布了 rule.json 的 JSON schema，该schema是根据运行时验证的同一schema生成的。将你的编辑器指向它以完成和验证：
rule.json 字段 - version、rules、overrides 和 transparent_wrappers。运行 rule verify 会将此 $schema 引用添加到缺少的有效规则配置中。 policy.json 没有已发布的schema。
Rulebook 结构
每个 rulebook都位于其自己的rulebook.json 文件中。
integer
必填
rulebookschema版本。必须是
1。string
必填
rulebook 名称。必须与本地目录名称或 GitHub 源名称匹配。
string
必填
rulebook版本字符串。
string
rulebook的人类可读描述。
string
rulebook作者。
array
必填
允许此rulebook定义规则的命令。
array
可选的 rulebook fixture。请参阅 Fixture 结构。fixture 用于记录预期行为。CC Safety Net 验证其结构，但不运行它们。
规则 schema
string
必填
在 rulebook中是独一无二的。必须以字母开头，后跟字母、数字、连字符或下划线。最多 64 个字符。
string
必填
要匹配的基本命令。必须列在
allowed_commands 中。string
要匹配的子命令，例如
add 或 install。如果省略，则匹配任何子命令。array
必填
触发块的参数（至少需要一个）。
string
必填
被阻止时显示消息。最多 256 个字符。
string
智能体行为意图附加到块消息页脚。
hard_stop、use_alternative、scope_down、manual_only 或 stop_and_explain 之一。默认为 manual_only。Fixture 结构
fixture是预期行为的可选文档。它们仅经过形状验证； CC Safety Net 不执行它们。string
必填
Shell 命令fixture。
string
必填
blocked 或 allowed。string
规则预计会阻止该命令。对于阻塞的装置是必需的。
匹配行为
CC Safety Net 使用以下匹配规则：- 命令规范化：命令在匹配之前被简化为其基本名称。
/usr/local/bin/npm与"command": "npm"匹配。 - 子命令检测：子命令是命令后面的第一个非选项参数。在
git --no-pager add -A中，子命令是add。 - 参数匹配：
block_args中的参数按字面匹配。没有正则表达式或 glob 支持。 - 短选项扩展：捆绑的短标志在匹配之前解绑。
-Ap被视为-A和-p。 - 长选项匹配：长选项使用精确的字符串匹配。
--all-files不匹配--all。 - 任何参数匹配：如果
block_args中存在任何单个参数，则命令将被阻止。 - 仅添加：自定义规则只能添加新的限制。它们无法绕过内置保护。
已知限制：
-Cfoo 被视为 -C -f -o -o，而不是 -C foo。阻止 -f 可能会对附加选项值产生误报。示例
阻止全局 npm 安装
阻止全局 npm 安装
阻止智能体全局安装包：
阻止危险的 docker 命令
阻止危险的 docker 命令
块
docker system prune：一个 rulebook 中的多个规则
一个 rulebook 中的多个规则
阻止消息格式
阻止消息的形式说明完整的阻止消息布局。自定义规则添加的是带有rulebook 名称和规则名称的前缀，因此你可以知道哪个rulebook产生了该块：<rulebook-name>/<rule-name>。这也是你在 rule.json overrides 中用于禁用规则 ("off") 或替换其原因的密钥。
验证你的 rulebook
创建或编辑 rulebook后，使用以下方法验证它们：rule sync为配置的 rulebook源重建锁和缓存。rule verify检查配置、lock 和缓存状态、本地 rulebook，以及可共享的 GitHub 源 rulebook 目录。它不获取远程内容。
迁移旧配置
旧版内联配置文件（.safety-net.json 和 ~/.cc-safety-net/config.json）不再在运行时加载。
旧规则永远不会在原来的位置执行，也不会阻碍工作。运行时根本不检查遗留文件，因此在保护时间不会显示任何内容 -
npx -y cc-safety-net rule verify 是关于剩余遗留文件的警告。升级后运行它。
rule migrate 自动创建基于 rulebook的布局：
无效的自定义规则配置
无法验证的自定义规则配置将被丢弃，不会强制执行，并且永远不会变成拒绝。普通命令继续运行，所有其他经过验证的源继续执行，并且每个内置保护仍然适用。运行时将自身报告为degraded，因此情况是可见的。
因为丢弃源会移除拒绝而不是添加拒绝，所以此类故障本身不会造成操作阻碍。npx cc-safety-net status 是快速的日常检查。完整的故障回退矩阵、诊断字符串、报告界面和修复顺序见配置恢复。