> ## Documentation Index
> Fetch the complete documentation index at: https://ccsafetynet.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CC Safety Net 如何拦截和阻止破坏性命令

> 一次工具调用的生命周期：智能体发出请求、集成拦截、按顺序保护与分析、返回允许或阻止、审计记录，以及判定出乎预期时该去哪里查看。

CC Safety Net 位于编码智能体与受保护工具之间。每个受支持的工具操作都会在执行前接受检查。允许的操作继续执行，被阻止的操作会返回一条带处理建议的结果。本页说明一次工具调用的完整流程。

把各个智能体接入 CC Safety Net 的那层集成，见[集成架构](/docs/zh-Hans/guides/integration-architecture)。

## 一次工具调用的生命周期

<Steps>
  <Step title="智能体准备工具调用">
    智能体决定运行某项操作。它可能是 `git reset --hard` 这样的 shell 命令，也可能是文件写入、编辑、搜索或 patch。然后，智能体把操作交给自己的工具层。
  </Step>

  <Step title="集成拦截调用">
    该智能体对应的 CC Safety Net 集成会在工具执行前、操作系统看到它之前接收这次调用。部分智能体把 CC Safety Net 作为短生命周期的子进程 hook 调用，另一些则在进程内以插件或扩展的形式加载它。两种方式运行的是同一套防护。哪个智能体采用哪种模型，请参阅[集成架构](/docs/zh-Hans/guides/integration-architecture)。
  </Step>

  <Step title="CC Safety Net 检查操作">
    CC Safety Net 在深度、大小和字段数量的限制内读取工具输入。它只解析一次输入，然后按[按顺序检查的内容](#按顺序检查的内容)中的固定次序逐阶段运行。这个次序不随智能体而变。
  </Step>

  <Step title="返回允许或阻止结果">
    安全的调用会正常执行。被阻止的调用不会运行。智能体会收到一条消息，其中写明原因、触发阻止的命令和后续操作。请参阅[阻止消息的形式](#阻止消息的形式)。
  </Step>

  <Step title="判定可供审计">
    拒绝判定会追加到本地审计日志。当配置的审计范围包含允许判定时，符合条件的允许命令判定也会记录下来。请参阅[审计记录](#审计记录)。
  </Step>
</Steps>

## 按顺序检查的内容

每次工具调用都会按以下顺序走过同样的阶段：

1. **有界输入提取。** 在深度、节点数、键数和大小限制内，从工具输入中读出命令。超过任一限制就阻止调用，避免无界遍历。
2. **单次解析。** 命令只解析一次，并生成后续阶段共用的结构化事实。解析器预算耗尽时，所有安全级别都会阻止调用。
3. **策略文件保护。** 任何会修改或删除 CC Safety Net 自己的 `policy.json`、其目录或祖先目录的操作都会被直接阻止。
4. **Git 元数据保护。** 任何会删除、移动、覆盖或 patch 仓库 `.git` 元数据或 hooks 目录的操作都会被直接阻止，包括从工作目录内部发起的操作。
5. **加载配置。** 解析出你的策略、rulebook 和安全级别。
6. **敏感路径保护。** 对照内置的敏感位置（`.env`、`~/.ssh`、云服务和编码 CLI 的凭证文件）以及你配置的拒绝路径，检查命令、路径、搜索和 patch。
7. **破坏性命令分析。** 把命令拆成命令段，展开包装器和解释器，再交给对应的分析器分类。分析器覆盖 `git`、`rm`、`Remove-Item`、`find`、`xargs`、`parallel`、设备命令和自定义规则。

第 3 和第 4 步有意在第 5 步**之前**运行。这两项保护始终启用，配置无法削弱它们，因为它们在读取配置前就已生效。第 6 步由策略控制，因此你可以禁用它或用自己的拒绝路径扩展它。

同一序列的维护者视角，包括阶段名称和证据，见[架构](/docs/zh-Hans/guides/architecture#the-ordered-guard-stages)；分类器的内部机制见[分析引擎](/docs/zh-Hans/guides/analysis-engine)。

## 为什么分析意图，而不是匹配字符串

CC Safety Net 分析命令*做什么*，而不是它*长什么样*。它会解析可执行文件、子命令、标志和参数，再按该可执行文件的选项语法进行分析。

| 命令 | 实际作用 | 结果 |
| - | - | - |
| `git checkout -b feature` | 创建新分支 | **允许** |
| `git checkout -- file` | 丢弃文件中未提交的更改 | **阻止** |

两者都以 `git checkout` 开头。如果不重复实现 Git 的选项逻辑，简单的前缀规则无法区分这两种结果。结构化分析还能应对调换顺序的标志（`rm -r -f /`）、shell 包装器（`sh -c "rm -rf /"`）和解释器单行命令（`python -c 'import os; os.system("rm -rf /")'`）。CC Safety Net 最多会展开并重新分析 10 层嵌套命令。

本页不会列出每一条规则。完整阻止行为矩阵见[被阻止的命令](/docs/zh-Hans/reference/blocked-commands)，有意允许的内容见[被允许的命令](/docs/zh-Hans/reference/allowed-commands)。

<span id="what-a-block-looks-like" />

## 阻止消息的形式

智能体会以工具结果的形式收到这条阻止消息：

```text theme={"dark"}
BLOCKED by CC Safety Net

Reason: git checkout -- discards uncommitted changes permanently. Use 'git stash' first.

Rule: git.checkout-double-dash

Command: git checkout -- src/main.py

Do not retry the blocked form. Continue the task using the safer alternative described above.
```

`Rule:` 行给出阻止该调用的规则或[固定拒绝](/docs/zh-Hans/reference/destructive-rules#fixed-denial-ids)的 ID。只有 hook 输入缺失或无法解析为 JSON 而被阻止时，消息中才没有这一行。消息还可能包含 `Tool:` 名称、触发阻止的 `Segment:`、因执行目录而拒绝时的 `Working directory:`，以及回退配置生效时的 `Config warning:`。命令和命令段只保留摘录。消息离开进程前，所有内容都会经过机密脱敏。

阻止不会结束智能体会话。消息会作为普通工具结果返回，引导智能体继续任务，避免反复尝试命令变体。结尾指令由规则的 intent 决定：

| Intent | 告知智能体的操作 |
| - | - |
| `hard_stop` | 不得以任何方式重试或绕过；报告阻止，然后继续任务的其余部分 |
| `use_alternative` | 不要重试被阻止的形式；改用原因中指定的更安全替代方案继续 |
| `scope_down` | 使用更窄且明确的目标重试；如果确实需要范围广的操作，则上报给用户 |
| `manual_only` | 向用户请求明确许可，并由用户手动运行 |
| `stop_and_explain` | 不要暴力尝试其他变体；简化或重组命令，或报告阻止 |

这些消息为何这样写，以及为何指令只是建议、执行始终由防护负责，见[设计原则](/docs/zh-Hans/guides/design-principles#denials-that-keep-the-agent-on-task)。

### 消息改为询问而不是阻止时

在 Claude Code 中，standard 模式无法验证的命令会以权限提示的形式交给你，而不是直接阻止。消息字段保持不变，只有首行和末行不同：

```text theme={"dark"}
CC Safety Net could not verify this command

Reason: shell execution source cannot be verified safely. Use a literal command string or ask the user to run it manually.

Command: eval "$CMD"

Segment: eval $CMD

Approve only if you expected this command.
```

末行取代了 intent 指令，因为这一次由你来判断，而不是智能体。批准后命令会执行，拒绝则不会；无论哪种结果，审计日志都按拒绝记录这次调用。哪些拒绝可以变成询问、在 Claude Code 的哪些权限模式下生效，见[集成架构](/docs/zh-Hans/guides/integration-architecture#when-claude-code-asks-instead-of-denying)。

## 审计记录

CC Safety Net 始终把拒绝记入本地审计日志，默认还会记录允许的命令判定。用以下命令读取日志：

```bash theme={"dark"}
npx cc-safety-net logs
```

日志位置、每条记录包含什么、记录保留多久，以及写入前具体会脱敏哪些内容，都在[审计日志参考](/docs/zh-Hans/reference/audit-log)中说明。

## 判定出乎预期时

<Steps>
  <Step title="询问原因">
    `npx cc-safety-net explain "<command>"` 会对一条命令重放分析过程，显示命中了哪条规则以及原因。加上 `--json` 可获得结构化跟踪。
  </Step>

  <Step title="检查保护是否确实生效">
    `npx cc-safety-net status` 会在一屏之内输出 `ready` 或 `degraded`，并把所有未生效的项列在 `Not active` 下，其中包括已禁用的 Claude Code 插件。`degraded` 表示某个配置来源被拒绝，当前执行的是回退配置。哪些生效、哪些没有，以及如何修复，见[配置恢复](/docs/zh-Hans/configuration/recovery)。`npx cc-safety-net doctor` 会给出完整报告。
  </Step>

  <Step title="调整或报告">
    如果阻止本身没错，只是对你的工作流过于严格，可以改用别的[安全模式](/docs/zh-Hans/configuration/modes)，或为个别规则添加覆盖。如果安全的命令被阻止，或破坏性命令没被阻止，请参阅[故障排除](/docs/zh-Hans/guides/troubleshooting)和[安全策略](/docs/zh-Hans/security)，了解该向哪里报告。
  </Step>
</Steps>

## 本页未涵盖的内容

CC Safety Net 只分析智能体发起的工具调用。它看不到任意二进制文件内部、未配置或不透明的命令代理，以及网络活动中的行为。它是静态的执行前策略检查，不是操作系统沙箱或权限边界。绕过已安装集成的命令也不受保护。完整列表和缓解措施见[已知限制](/docs/zh-Hans/guides/known-limitations)。

接下来，请参阅[集成架构](/docs/zh-Hans/guides/integration-architecture)，了解每个智能体如何连接到 CC Safety Net。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.