> ## 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 gui 启动本地 CC Safety Net 仪表板，并通过概览、活动、策略、规则、集成和设置六个视图检查判定、编辑策略和管理智能体 hook。

`cc-safety-net gui` 打开本地仪表板。使用它来审查本机上的决策并编辑您的策略，而无需手动编辑 JSON。仪表板可帮助您查找被阻止的内容、被阻止的原因以及可以更改的内容。

本页说明你可以在仪表板中执行的操作，以及哪些操作具有破坏性。它不重复底层格式：`policy.json` schema 见[策略](/docs/zh-Hans/configuration/policy)，rulebook 编写见[自定义规则](/docs/zh-Hans/configuration/custom-rules)，审计记录 schema 见[审计日志](/docs/zh-Hans/reference/audit-log)。

## 启动仪表板

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

该命令打印仪表板 URL，然后在默认浏览器中打开它：

```text theme={"dark"}
CC Safety Net policy GUI: http://127.0.0.1:52341/?token=...
```

当您想要在不启动浏览器的情况下获取 URL 时，请传递 `--no-open` - 例如通过 SSH、在容器中，或者当您希望将 URL 粘贴到特定的浏览器配置文件中时：

```bash theme={"dark"}
cc-safety-net gui --no-open
```

`--no-open` 是除 `-h, --help` 之外的唯一标志。任何其他参数都会被 `Usage: cc-safety-net gui [--no-open]` 和非零退出代码拒绝。

如果浏览器无法启动，那也不是致命的 - 该命令会打印底层错误，后跟 `Open this URL manually: <url>` 并继续提供服务。服务器在前台运行，直到您使用 `Ctrl-C` 停止它。

### 本地环回范围

仪表板不是托管服务。它的服务器仅侦听本地环回接口：

* 服务器仅在临时端口上绑定到 **`127.0.0.1`**。 LAN 上的任何内容都无法访问它。
* 每次启动都会生成一个嵌入在 URL 中的新随机令牌。每个请求都必须携带该令牌，并且每个状态更改请求也必须将其作为请求标头发送。没有它的请求将被拒绝，并显示 `403`。
* 通过 `cache-control: no-store` 提供响应。

该页面本身不会对其数据发出出站请求 - 它呈现的所有内容都来自本地策略文件和审核日志。唯一的例外是选择加入：概述中显示的更新检查和 GitHub 星号操作。

<Note>
  由于令牌是每次启动时生成的，因此您在上一个会话中添加书签的 URL 将不起作用。再次运行 `cc-safety-net gui` 以获取新的。
</Note>

## 六个视图

侧边栏有六个视图，散列路由，因此您可以在会话中链接或添加书签：

| 查看     | 它回答什么                       |
| ------ | --------------------------- |
| **概述** | CC Safety Net 最近在这台机器上做了什么？ |
| **活动** | 分析了哪些单独的命令，每个命令发生了什么？       |
| **策略** | CC Safety Net 应阻止什么？        |
| **规则** | 当前实际执行哪些自定义 rulebook 规则？    |
| **集成** | 本机上哪些编码智能体已安装 hook？         |
| **设置** | 文件保存在哪里、日志保存多长时间以及如何重置？     |

无法识别的哈希值会退回到概览。集成和规则会在您第一次访问时加载其数据。

## 概述

概述总结了**保留的窗口**，而不是生命周期的总数。该窗口是最近 7 天，或者当保留时间短于 7 天时的整个保留窗口。标题指出了它使用的窗口，如 `Last N day(s)`。

**图块。** 两个计数器 - **已阻止** 和 **已分析** - 每个计数器都有一个从最旧到最新运行的每日迷你图。每个迷你图都会缩放到其自身的最大值，因此这两个图块在视觉上无法相互比较；阅读数字，而不是条形高度。

**保护状态。** 卡片显示安全级别；override 偏离 preset 时会添加 `· Customized`；同时报告活动规则数和机密保护状态。此卡只反映**已保存**的状态。策略视图中暂存的未保存开关在保存前不会改变它。破坏性命令保护或机密保护关闭时，或配置中的某项无法加载而正在执行 fallback 配置时，会显示横幅。

**健康状态条。** 报告检测到的智能体中是否有活动 hook、是否检测到智能体但没有活动 hook，或完全没有检测到智能体 hook。它还会显示可用更新。需要处理问题时，它会链接到集成视图。

**阻止次数最多的命令和规则。** 两个面板各显示前五项，统计窗口与指标卡相同。选择命令后会跳到活动视图，并应用一个可移除的精确命令签名过滤条件，只显示阻止记录。选择规则时会按命名空间跳转：`custom.*` rule ID 进入规则视图；内置 rule ID 进入活动视图，并预填到搜索框。

**防护错误。** 当窗口中有拒绝来自评估失败而不是策略时，会显示按钮 `N guard error(s) in the last N days — commands blocked because evaluation failed, not by policy. Click to view.`。选择后会打开活动视图，并过滤为错误判定。这些拒绝属于 fail-closed：CC Safety Net 无法完成分析，因此拒绝命令。如果反复出现，请参阅[故障排除](/docs/zh-Hans/guides/troubleshooting)。

## 活动

活动视图按时间倒序列出本地审计日志中的命令。命令在写入时、任何内容到达日志前进行机密遮盖。遮盖仅覆盖已识别的凭证形式，因此条目仍可能包含路径、主机名和名称。分享此视图中的内容前，请参阅[审计日志](/docs/zh-Hans/reference/audit-log#秘密-redaction)，了解记录 schema 和准确的遮盖范围。

### 时间窗口由保留期决定

时间窗口选择器**不是固定选项集合**。它根据配置的审计日志保留期计算：候选窗口为 7、30、90、180 和 365 天，只保留严格短于保留期的值；保留期本身始终作为最宽的选项追加。这样，任何选项都不会承诺显示已被保留期清理删除的历史记录，同时完整日志始终可访问。

| 保留期      | 提供的窗口           |
| -------- | --------------- |
| 5 天      | 5               |
| 14 天     | 7, 14           |
| 30 天（默认） | 7、30            |
| 90 天     | 7、30、90         |
| 365 天    | 7、30、90、180、365 |

窗口按完整的本地日历日计算，即今天加之前的若干天，因此概览中的每日 sparkline bucket 之和与总数完全一致。请求超过保留期的窗口会被拒绝；缩短保留期后，当前选择会自动收窄。保留期的配置和执行方式见[审计日志](/docs/zh-Hans/reference/audit-log#保留)。

### 过滤器

* **Window** — 上面描述的保留派生选择器。
* **决策芯片** — 始终为 `All`、`Blocked` 和 `Allowed`； `Errors` 仅当窗口包含保护错误时； `Likely false positive` 仅当启发式找到候选者时。启发式标记带有失败阶段的拒绝，或者在同一会话中被拒绝两次或多次的命令签名。
* **智能体 chip** — 只有窗口内出现至少两个不同的已知智能体时才显示，并提供 `All agents` chip 用于清除过滤。
* **命令条件** — 精确匹配命令签名且只显示阻止记录的过滤条件。从概览点击后添加，可在此处移除。
* **搜索** — 顶栏框 (`Filter by rule or command`) 将规则 ID 和命令文本作为不区分大小写的子字符串进行匹配。

重新加载时，无效过滤条件会自动修复。如果已过滤的智能体不再出现，或窗口内不再有错误或疑似误报，对应条件会重置，而不是显示空列表。

### 刷新

刷新按钮会同时重新加载**概览和活动**，因此指标卡与活动列表不会不一致。按钮会保持很短的最小旋转时间，使快速的本地刷新仍能明确显示为一次操作。

### 渲染条目与计数

活动列表最多呈现 **500 个条目**。上限按判定类别分配：每类保证获得一半容量，并把未使用的容量借给另一类。因此，大量拒绝不会让允许记录完全消失。

计数不受 500 条显示上限影响。Chip、指标卡和排名面板使用服务器端完整窗口聚合，与列表实际呈现的内容无关。页脚用 `Showing X of Y entries from the last N day(s)` 同时说明显示数和总数；发生截断时再添加 `(capped at 500, newest of each decision)`。

只有一种情况会使计数本身不完整：某些审计日志来源无法读取时，页脚会追加 `N audit log source(s) could not be read, so this list is incomplete.`。聚合也会缺少这些条目，因此在来源恢复可读前，列表和计数都只能视为下限，不能视为总数。

<Note>
  在扫描列表得出结论之前，请先阅读页脚。 `Showing 500 of 4,120` 表示列表是最近的切片，而每个切片和图块仍反映所有 4,120 个条目。
</Note>

### 每个条目的操作

每个条目都显示判定 badge（`Blocked`、`Allowed` 或 `Error`）、智能体 badge、rule ID chip、相对时间戳，以及把原始日志条目复制为 JSON 的按钮。长命令会截断，并提供 Show more 开关。复制内容是原始审计记录；字段说明见[审计日志](/docs/zh-Hans/reference/audit-log#记录模式)。

拒绝的条目提供**报告误报**，这会打开一个对话框，准备预填充的**公共** GitHub 问题。在继续之前，命令和日志条目都是可编辑的，您的项目路径将替换为 `<project>`，主目录将替换为 `~`，并且在您自己在 GitHub 上提交之前不会提交任何内容。

允许的条目提供**将来阻止此**，这会使用该命令预先填充规则视图上的提示编辑器。它不会自行创建规则 - 请参阅下面的 [Rules](#规则)。

## 策略

策略视图用于选择 CC Safety Net 应阻止的内容。此视图中的所有内容都是**内置**保护：安全 preset、破坏性命令规则，以及 CC Safety Net 自带的机密保护模式。自定义 rulebook 属于独立机制，不在此处编辑。

此视图写入文件的完整字段约定见[策略](/docs/zh-Hans/configuration/policy)。

### 已保存与未保存

编辑会累积在草稿中，并且仅在保存时应用。

* 只要草稿与磁盘上的内容不同，策略视图上就会出现一个保存栏，并带有 **丢弃** 和 **保存**。
* `Unsaved policy changes · Review` 芯片出现在每个其他视图的顶部栏中，并在单击时跳转到此处。
* 草稿在浏览器会话中重新加载后仍然存在。保存、丢弃、修复或重置都会将其清除。
* 离开未保存更改的页面会首先提示您。

保存会写入策略文件并报告其写入的路径。虽然磁盘上的策略有任何错误，但表单不会显示您的文件：每个控件都会呈现内置默认值，而不是运行时仍在从磁盘中抢救的有效值 - 只有原始 JSON 镜像仍然显示文件的实际内容。在该状态下，保存被拒绝（`Repair policy before saving changes.`），因此屏幕上的默认值无法从此处覆盖您的文件 - 先修复，然后保存。修复后，表单将使用修复保留的设置重新加载。

### 测试命令

将 shell 命令粘贴到 **测试命令** 以查看它是否会被阻止。该测试根据您的**当前未保存的编辑**进行评估，因此您可以在提交更改之前检查更改。

该测试还强制执行从磁盘加载的自定义规则手册规则，即使规则手册无法从仪表板编辑。将其视为真正决策的预览，而不仅仅是内置层的预览。对于来自终端的相同分析，请参见[`explain`](/docs/zh-Hans/reference/cli-commands#explain)。

### 安全 preset

此视图提供三个安全 preset，界面标签为 **Standard**、**Strict** 和 **Paranoid**。它们是工作区后续自定义所继承的默认值，严格程度逐级提高。各 preset 和能力的准确变化以[模式](/docs/zh-Hans/configuration/modes)为准。

提高保护的环境变量在此处作为通知显示，因此看起来低于您所看到的行为的级别是解释性的，而不是令人困惑的。默认情况下折叠的“高级覆盖”部分公开了预设解析的各个功能 - 失败关闭、偏执的 `rm -rf` 检查和偏执的解释器 - 因此您可以在不更改预设的情况下提高或降低一项功能。工作流程异常与安全级别分开配置。

### 破坏性命令保护

此区域包含 master switch，并把规则分为四个可折叠 tier：

| 等级            | 子标签                            |
| ------------- | ------------------------------ |
| **始终执行**      | 无法通过任何预设、规则覆盖或允许路径禁用           |
| **在每个预设中均可用** | 无需额外功能                         |
| **严格的等级**     | 继承自 Fail 关闭                    |
| **偏执层**       | 继承自 Paranoid rm 或 Paranoid 解释器 |

每一层都开始塌陷；在策略视图上搜索会自动打开具有匹配项的每个层。 **始终强制**层没有开关，也没有每规则复选框 - 其标头将其规则计为 `N protections`，并且内部的每个规则都标记为 `Always enforced`，并带有 `?` 示例弹出窗口。

三个可配置层在标题中显示 `N on · N off` 计数，旁边是标记为 `All <tier> protections` 的层开关。当该层中的至少一个规则打开时，会检查该开关；当主开关关闭时，该开关会被禁用。翻转它会写入相同的每条规则，批量覆盖单个复选框使用的内容 - 最终匹配其继承值的规则不会保留覆盖 - 因此没有单独存储的组设置。

当主开关打开时，面板摘要显示为 `N active, N disabled`。关闭它会用 `Configurable protection disabled. Catastrophic protections remain active; saved rule settings and allow paths are preserved.` 代替——即使如此，始终强制层仍然会阻塞。

每张可配置规则卡片都有 `?` 弹窗，其中给出该规则阻止的具体命令示例。状态行说明当前值的来源。例如，`Off — destructive-command protection disabled` 表示 master switch 优先于你的 override。

切换规则会存储显式 `on` 或 `off` override。把规则恢复为继承值时会**删除** override，而不是存储冗余值。每条规则还提供 `Use inherited setting` 直接完成此操作。面板标题中的 `Restore defaults` 会一次清除所有 override。

**允许路径**位于此面板中。针对列出的路径的递归删除不会被阻止，这就是 `/tmp` 可行的原因。条目必须是绝对目录或 `~/` 前缀的目录，并且您的主目录将被拒绝 - 请参阅 [允许路径](/docs/zh-Hans/configuration/policy#允许路径) 了解完整的验证表和 [允许的命令](/docs/zh-Hans/reference/allowed-commands#配置的允许路径) 了解允许路径的作用和不放松的情况。

### 机密保护

此区域包含 master switch 和按类别分组的 per-pattern 复选框，范围从默认敏感路径（主目录路径、凭证 basename、扩展名和变体）到 **Coding CLI credential** 和 **Coding CLI config** 位置。每个组标题是可折叠按钮，显示 `N on · N off`；旁边的组开关标记为 `All <category> protections`。它与破坏性规则 tier 开关行为相同：组内任一规则开启时即为选中，master switch 关闭时禁用，并批量写入 per-rule override。组默认折叠，策略搜索时会自动展开包含匹配项的组。

保护文字文件路径的规则带有一个 `?` 按钮，可打开“受保护的路径”弹出窗口，其中准确列出了规则所涵盖的路径。

并非每个规则都默认为打开。 **编码 CLI 配置**规则发布 **关闭** — 设置和 MCP 配置文件内嵌凭据，但代理将它们作为日常工作进行编辑，因此您可以选择每个规则。仅当复选框偏离规则的默认值时，复选框才会存储覆盖：选中默认关闭规则会写入 `on` 覆盖，取消选中会删除覆盖，而对于默认打开规则，取消选中会写入 `off` 并重新选中会删除覆盖。

当主开关打开时，面板摘要显示为 `N active, N disabled`。关闭时，显示为 `Protection disabled. Saved rule settings and deny paths are preserved.`

**Deny path** 位于此面板。机密保护开启时，配置路径及其内部所有内容都会被阻止。Deny path 依赖 master switch；关闭机密保护会停止执行这些路径。可接受的条目形式见[拒绝路径](/docs/zh-Hans/configuration/policy#拒绝路径)。

### 要求确认的操作

单独的规则切换、预设更改以及添加或删除路径都在草稿中暂存，并由 **保存** 控制，因此不会单独确认。仪表板为减少保护或丢弃配置的操作保留模式确认：

| 行动         | 确认告诉您什么                                                    |
| ---------- | ---------------------------------------------------------- |
| 关闭破坏性命令保护  | 可配置的内置破坏性 Git、文件系统和执行保护将停止阻止，直到您打开此设置。始终强制执行的保护和自定义规则仍然有效。 |
| 关闭机密保护     | 默认敏感路径、Coding CLI credential 位置和 deny path 将停止阻止访问，直到重新开启。 |
| 恢复破坏性规则默认值 | 所有内置破坏性命令规则都将返回到其继承的预设设置。                                  |
| 恢复秘密规则默认值  | 所有内置秘密规则将返回到其继承的预设设置。                                      |
| 放弃未保存的更改   | 自上次保存以来的所有更改都将被恢复。                                         |
| 维修政策       | 编写规范策略 JSON；保留有效设置并丢弃无效字段。                                 |
| 重置政策       | 默认策略 JSON 将在配置的路径中恢复。                                      |
| 缩短保留期      | 早于新窗口的审核条目将在下次扫描时删除并且无法恢复。                                 |

默认情况下，“取消”在每个对话框中都是焦点。

<Warning>
  关闭破坏性命令保护或机密保护后，该层中的所有可配置规则都会停止阻止，直到重新开启。只有始终执行的破坏性规则 tier 会继续阻止。应优先使用单项规则 override 或较低的 preset，而不是关闭 master switch。
</Warning>

### 修复

当磁盘上的策略文件有错误时，此视图上会显示 **可用策略修复** 横幅，并带有 `Repair` 按钮。 Repair 写入规范的 JSON，保留每个有效设置并丢弃无效字段。如果根本无法解析 JSON，则会恢复默认值。当加载的策略没有错误时，该按钮处于惰性状态。

<Warning>
  修复会丢弃无效字段，并在无法解析文件时恢复为默认值。如果该文件包含您关心的手写配置，请在修复之前将其复制到安全的地方。
</Warning>

### 重置

重置操作有意**不放在**此视图中。它位于“设置”的“危险区域”下。

## 规则

规则视图显示你自己编写的自定义 rulebook，与策略视图中的内置保护不同。Rulebook 格式、作用域、override 和验证方式见[自定义规则](/docs/zh-Hans/configuration/custom-rules)；本页不重复这些内容。

<Warning>
  规则视图**不是** rulebook 编辑器。CC Safety Net 绝不会从仪表板写入 rulebook。此视图以只读方式显示实际执行的规则，并生成 prompt 文本，供你复制给负责编写规则的编码智能体。
</Warning>

### Rulebook 面板（只读）

每张 rulebook 卡片显示名称、版本 badge、与名称不同时的 source spec、作用域（`All projects` 或 `This project`）以及规则数。

规则被列为**强制执行、覆盖后**。被覆盖禁用的规则仍然属于其规则手册并保留在规则手册的列表中，但它会从呈现的规则中删除 - 因此您在此处阅读的是有效的规则手册，而不是文件内容。刷新按钮从磁盘重新读取。

当未配置规则手册时，面板会将您指向 `cc-safety-net rule init`。当规则手册存在但所有规则手册都被删除时，它会这样说并将您发送到诊断。

### 诊断

没有问题时，诊断面板会隐藏。面板出现时，其中的错误表示某个 rulebook 已被**丢弃**，其规则未执行。你编写的规则未触发时，应先检查这里。

### Prompt composer（仅复制）

Composer 为编码智能体构建 prompt。唯一操作是**复制 prompt**。此视图中没有创建、保存或写入控件，服务器也没有写入 rulebook 的路由。

输入：

* **范围** — `Project` 或 `All projects`。
* **项目路径** — 仅在项目范围中显示，预填充仪表板启动的目录。如果本机目录选择器可用，则该字段是只读的，并带有 `Choose…` 按钮；如果选择器在运行时不可用，则该字段将变为可编辑。
* **请求** — 描述您想要的规则。规则匹配命令、可选子命令和确切参数，而不是文件路径或模式。
* **示例** — 用于建议规则、阻止命令和验证现有规则的一键式启动器。

生成的提示告诉您的代理使用 CC Safety Net 技能，或运行 `cc-safety-net rule doc` 并将该输出视为事实来源。它包含范围、项目路径和现有规则手册的名称，以便代理选择尚未声明的名称。它故意仅携带\*\*规则手册名称 - 没有规则名称、阻止的参数、原因或版本在该文本中离开您的计算机。

当规则尚未加载、请求为空或选择没有项目路径的项目范围时，复制将被拒绝，并显示特定消息。

## 集成

集成视图为本机上的每个编码智能体安装或删除 CC Safety Net hook。**智能体**面板列出检测到的 CLI 及其 hook 状态。每个智能体的连接方式见[集成架构](/docs/zh-Hans/guides/integration-architecture)，GUI 外的等效步骤见[安装](/docs/zh-Hans/installation)。

| 状态       | 意义                           | 提供的行动       |
| -------- | ---------------------------- | ----------- |
| **已安装**  | 挂钩已配置并处于活动状态。                | `Uninstall` |
| **已禁用**  | CLI 位于此计算机上，但未配置挂钩。          | `Enable`    |
| **未经检查** | 已检测到 CLI，但无法读取其状态文件，因此其状态未知。 | `Install`   |
| **未安装**  | CLI 位于这台机器上，没有钩子。            | `Install`   |
| **未检测到** | 在此计算机上未找到 CLI。               | 无           |

`Not inspected` 带有一个工具提示，说明了这一点：`This runtime's state file could not be read, so its status is unknown.` CLI 本身已找到，因此仍然提供安装。

检测控制操作：当未检测到 CLI 时，根本不提供任何按钮，因为没有任何东西可以安装挂钩。安装和卸载是序列化的，因此两个操作不能交叉，并且在其请求正在进行时该按钮被禁用。故障报告 `Install failed` 或 `Uninstall failed`，而不是静默恢复。

刷新按钮会重新检测每个智能体，适合在安装 CLI 或手动编辑智能体配置后使用。下方的**系统**面板报告 CC Safety Net 版本、Node.js 版本和本机检测到的平台。

## 设置

设置包括外观、文件位置和维护。

**外观。** 主题控件按 `Auto → Light → Dark` 循环。该偏好存储在浏览器中，不写入策略。

**文件。** 两个只读行显示 CC Safety Net 在此计算机上读取和写入的位置：策略文件和审核日志目录。

**审核日志保留。** 审核记录要保留多少天 - 请参阅[审核日志](/docs/zh-Hans/reference/audit-log#保留)，了解可接受的范围、记录的内容以及扫描如何强制实施。与策略视图不同，保留**在更改时立即保存** - 后面没有保存栏。当策略视图有未保存的更改时，无法保存；首先保存或丢弃它们。与“策略保存”按钮不同，当磁盘策略出现错误时，此控件**不会**被阻止 - 并且因为表单在该状态下保留默认值，所以更改保留会在文件上写入所有默认文档，仅包含新的保留。在接触保留之前修复策略。

<Warning>
  缩短保留时间是不可逆转的。早于新窗口的审核条目将在下一次扫描时被删除并且无法恢复，并且“活动”视图只能回溯至新值。仪表板会要求您在缩短之前进行确认，确认信息会命名它将修剪的日志目录。首先导出您需要的任何内容 - 每个条目在活动源中都有一个“复制为 JSON”按钮。
</Warning>

**策略 JSON。** 策略控件的只读镜像，带有复制按钮。它反映了策略视图上的控件 - 它是检查和共享的镜子，而不是第二个编辑器。

**版本。** 单个只读行显示您正在运行的 CC Safety Net 版本。

**危险区域。** 单个操作，**重置策略**，可在配置的路径中恢复默认策略 JSON。

<Warning>
  重置会放弃您保存的配置。每个预设选择、规则覆盖、允许路径和拒绝路径都会返回默认值，并且无法撤消。重置仅影响策略文件 - 您的自定义规则手册是单独的文件，不会受到影响。
</Warning>

<Note>
  对于策略文件架构，请参阅 [Policy](/docs/zh-Hans/configuration/policy);对于规则手册创作，请参阅[自定义规则](/docs/zh-Hans/configuration/custom-rules)；有关审核日志格式和保留行为，请参阅[审核日志](/docs/zh-Hans/reference/audit-log)；对于 `gui` 和所有其他命令，请参阅 [CLI 命令](/docs/zh-Hans/reference/cli-commands)。
</Note>