核心概念
| 术语 | 定义 |
|---|---|
| PreToolUse hook | 工具执行前运行的 hook。CC Safety Net 对每个智能体使用 PreToolUse 或等效事件，以在执行前检查 shell 命令。请参阅工作原理。 |
| 故障时关闭（Fail-closed） | 当防护无法得出可信结论时，会拒绝该次工具调用，而不是允许它：例如意外分析错误、格式错误或过大的 hook 输入、空命令、解析器限制，或 strict 模式下无法解析的命令。无效配置不属于故障时关闭，而是进入降级状态。请参阅设计原则和安全模型。 |
| 决策（Decision） | 防护对单次工具调用给出的允许或拒绝结果。当审计日志记录命令决策时，会写入一条审计记录，其中包含规则 ID、有效安全级别和降级运行时的后备状态。请参阅审计日志。 |
| 命令段（Segment） | 复合命令中由 shell 运算符（&&、||、|、;、换行符）分隔出的单个命令。引擎按顺序分析命令段，并在段之间传递相关状态，例如有效工作目录。如果一个命令段被阻止，则整个命令会被拒绝。请参阅分析引擎。 |
| 分析引擎（Analysis engine） | 与平台无关的核心，它解析命令字符串并决定是否阻止。每个智能体集成都将输入交给同一个引擎。请参阅分析引擎。 |
| 集成模型（Integration model） | CC Safety Net 在编码智能体内的执行方式：标准输入 hook 子进程、智能体加载的插件、进程内扩展或事件插件。集成模型会改变智能体调用 CC Safety Net 的方式。所有集成都使用同一个分析引擎。请参阅集成架构。 |
配置
| 术语 | 定义 |
|---|---|
| 策略（Policy） | 设置文档 policy.json，默认路径为 ~/.cc-safety-net/policy.json。它包含安全预设、能力覆盖、worktree 模式、破坏性命令保护、机密保护和审计保留期。自定义规则不存放在此文件中。请参阅策略。 |
| 策略快照（Policy snapshot） | 每次工具调用时，由策略文件、rule.json、lockfile 和经过摘要验证的规则簿缓存组合成的有效运行时策略。加载过程不写入、不发起网络请求，也不缓存。它仅解析为 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 中允许，但启用故障时关闭行为后会被阻止。请参阅分析引擎。 |
递归删除和路径
模式
| 术语 | 定义 |
|---|---|
| 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 模式时，即策略文件中的 workflow.worktree_mode 或 CC_SAFETY_NET_WORKTREE=1，在确认的 linked Git worktree 内允许选定的本地 Git 丢弃命令。当 CC Safety Net 无法验证 worktree 时，不会应用放宽。请参阅模式。 |
规则
| 术语 | 定义 |
|---|---|
| 规则簿（Rulebook） | 包含自定义阻止规则、元数据和可选 fixture 的 JSON 文件。它在 rule.json 中配置为源，通过 SHA-256 摘要固定在 lockfile 中，并从经过验证的缓存执行。规则簿名称在用户和项目范围内全局占用。请参阅自定义规则。 |
| 透明包装器（Transparent wrapper） | 在 rule.json 的 transparent_wrappers 中声明的命令。分析会穿透它，以到达它执行的受保护命令。包装器位于 rule.json 而不是规则簿中，因此被丢弃的规则簿会保留它们，但无法读取的 rule.json 会丢失该范围的包装器。请参阅自定义规则。 |
| Lockfile | 跟踪规则簿源摘要和缓存内容的 JSON 文件（rule.lock）。用于检测过期或被篡改的规则簿。请参阅自定义规则。 |
如需规则簿、规则、fixture 和 lockfile 的正式 schema，请参阅自定义规则参考。有关
policy.json schema，请参阅策略。有关 explain --json 返回的 JSON 结构，请参阅Explain 跟踪。