核心概念
| 术语 | 定义 |
|---|---|
| PreToolUse hook | 工具执行前运行的 hook。CC Safety Net 对每个智能体使用 PreToolUse 或等效事件，以在执行前检查 shell 命令。请参阅工作原理。 |
| Fail-closed | 当防护无法得出可信的决策时，会拒绝该次工具调用，而不是允许它：例如意外的分析错误、格式错误或过大的 hook 输入、空命令、解析器限制，或 strict 模式下无法解析的命令。无效配置不属于 fail-closed，而是进入降级状态。请参阅设计原则和安全模型。 |
| 决策（Decision） | 防护对单次工具调用给出的允许或拒绝结果。当审计日志记录命令决策时，会写入一条审计记录，其中包含规则 ID、有效安全级别和降级运行时的后备状态。请参阅审计日志。 |
| 命令段（Segment） | 复合命令中由 shell 运算符（&&、||、|、;、换行符）分隔出的单个命令。引擎按顺序分析命令段，并在段之间传递相关状态，例如有效工作目录。如果一个命令段被阻止，则整个命令会被拒绝。请参阅分析引擎。 |
| 分析引擎（Analysis engine） | 解析命令字符串并决定是否阻止的跨平台组件。所有智能体集成都接入同一个引擎。请参阅分析引擎。 |
| 集成模型（Integration model） | CC Safety Net 在编码智能体内的执行方式：标准输入 hook 子进程、智能体加载的插件、进程内扩展或事件插件。集成模型会改变智能体调用 CC Safety Net 的方式。所有集成都使用同一个分析引擎。请参阅集成架构。 |
配置
| 术语 | 定义 |
|---|---|
| 策略（Policy） | 设置文档 policy.json，默认路径为 ~/.cc-safety-net/policy.json。它包含安全预设、能力覆盖、worktree 模式、破坏性命令保护、机密保护和审计保留期。自定义规则不存放在此文件中。请参阅策略。 |
| 项目策略（Project policy） | 项目根目录中可选的 .cc-safety-net/policy.json。它是稀疏文件：只设置自己列出的字段，省略的字段沿用用户策略的值。它没有 audit 部分，审计设置仅属于用户范围。写入它与写入用户策略文件一样会被拒绝。请参阅策略。 |
| 生效策略（Effective policy） | 用户策略叠加项目策略后的结果。safety.level、workflow.worktree_mode 以及项目设定的每个 enabled 标志都以项目值为准；按规则 ID 合并各条 override；allow_paths 和 deny_paths 取两个范围的并集。项目削弱的每个字段各占一行报告。请参阅策略。 |
| 策略快照（Policy snapshot） | 每次工具调用时，由用户和项目策略文件、各范围的 rule.json，以及每个已配置来源的 rulebook 文件组合成的有效运行时策略。加载过程不写入、不发起网络请求，也不缓存。它仅解析为 ready 或 degraded 两种状态之一。请参阅配置恢复。 |
| 预设（Preset） | safety.level 值，即 standard、strict 或 paranoid，它提供继承的能力默认值。当覆盖产生不匹配任何预设的组合时，报告的有效级别为 custom。请参阅模式。 |
| 能力（Capability） | 从预设继承且可单独设置的保护行为：fail_closed、paranoid_rm 或 paranoid_interpreters。策略文件中的 safety.overrides 可以提高或降低能力；旧版环境变量只能提高能力。请参阅模式。 |
| 降级（Degraded） | 配置来源被拒绝时进入的策略快照状态。无法验证的来源会被丢弃或回退到保护性默认值，普通工作继续，所有诊断界面都会报告该状态。另一个状态是 ready。请参阅配置恢复。 |
Shell 命令形式
| 术语 | 定义 |
|---|---|
| Shell 包装器（Shell wrapper） | 包装另一个命令的 shell 命令，例如 bash -c 'git reset --hard'。CC Safety Net 递归分析包装的命令，最多 10 层。请参阅被阻止的命令。 |
| 解释器单行命令（Interpreter one-liner） | 类似 python -c 'import os; os.system("rm -rf /")' 的命令，它内联执行代码。默认会检测这类命令并分析其中的危险模式。请参阅被阻止的命令。 |
| 动态替换（Dynamic substitution） | 依赖运行时展开的命令值或结构，例如 $(...)、<(...) 或 $VAR。CC Safety Net 根据命令类型和安全级别处理动态替换。某些形式在 standard 模式下允许，但启用 fail-closed 行为后会被阻止。请参阅分析引擎。 |
递归删除和路径
模式
| 术语 | 定义 |
|---|---|
| Strict 模式 | strict 预设，它启用 fail_closed 能力，因此会拒绝无法安全分析的命令。在策略文件中设置 safety.level，或使用 CC_SAFETY_NET_STRICT=1 提高该级别。请参阅模式。 |
| Paranoid 模式 | paranoid 预设，它在 strict 基础上增加 paranoid_rm 和 paranoid_interpreters 能力。在策略文件中设置 safety.level，或使用 CC_SAFETY_NET_PARANOID、CC_SAFETY_NET_PARANOID_RM 和 CC_SAFETY_NET_PARANOID_INTERPRETERS 提高单项能力。请参阅模式。 |
| Worktree 放宽（Worktree relaxation） | 启用 worktree 模式后，可在已确认的 linked Git worktree 内允许部分本地 Git 丢弃命令。可通过策略文件中的 workflow.worktree_mode 或 CC_SAFETY_NET_WORKTREE=1 启用。当 CC Safety Net 无法验证 worktree 时，不会应用这项放宽。请参阅模式。 |
规则
| 术语 | 定义 |
|---|---|
| Rulebook | 包含自定义阻止规则、元数据和可选 fixture 的 JSON 文件。它在 rule.json 中配置为来源，位于该范围 .cc-safety-net 目录下的 rules/<name>/rulebook.json。运行时每次工具调用都读取它，因此保存后的编辑从下一条命令起生效。它的 name 必须与列出它的来源一致。rulebook 名称在用户和项目两个范围内全局占用。请参阅自定义规则。 |
| 透明包装器（Transparent wrapper） | 在 rule.json 的 transparent_wrappers 中声明的命令。分析会穿透它，以到达它执行的受保护命令。包装器位于 rule.json 而不是 rulebook 中，因此 rulebook 被丢弃后包装器依然保留，但 rule.json 无法读取时会丢失该范围的包装器。请参阅自定义规则。 |
| 落盘 rulebook（Vendored rulebook） | rule add 和 rule update 验证远程 rulebook 后写入使用方自己 rules/<name>/rulebook.json 的那份副本。它是仓库中的普通文件，人可以直接阅读，更新改了什么也能从 diff 看出来。只有 rule add 和 rule update 会访问网络，运行时只读取这个文件。请参阅自定义规则。 |
如需 rulebook、规则和 fixture 的正式 schema，请参阅自定义规则参考页。有关
policy.json schema，请参阅策略。有关 explain --json 返回的 JSON 结构，请参阅 Explain 跟踪。