> ## 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.

# 在 Factory Droid 中安装 CC Safety Net

> 通过 ~/.factory/hooks.json 中的一个 PreToolUse hook 在 Factory Droid 中安装 CC Safety Net，了解安装如何带入旧版文件和 settings.json 中的 hook、hook 检查什么，以及卸载如何恢复原有的 hook 集合。

运行 `npx -y cc-safety-net@latest install --droid`。它会在 `~/.factory/hooks.json` 中添加一个 `PreToolUse` hook，让每次工具调用都先经过 CC Safety Net。然后运行 `npx cc-safety-net doctor`，确认 hook 已生效。Factory Droid 的 hook 是 fail open：崩溃、超时或缺少 `npx` 时，调用照常执行。

## 在 Factory Droid 中安装 CC Safety Net

**1. 运行安装程序**

```bash theme={"dark"}
npx -y cc-safety-net@latest install --droid
```

**2. 确认 hook 已生效**

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

## Factory Droid 安装会改动什么

安装程序在 `~/.factory/hooks.json` 顶层的 `PreToolUse` 数组中写入以下托管条目：

```json theme={"dark"}
{ "hooks": [{ "type": "command", "command": "npx -y cc-safety-net hook --droid", "timeout": 30 }] }
```

* 该条目既不带 matcher，也不带 `commandRegex`，因此到达 hook 的不只是 `Execute`，而是每一次工具调用。
* 安装会保留 `hooks.json` 中其他所有键、hook 事件和 `PreToolUse` 条目，从不写入 `~/.factory/settings.json` 或旧版的 `~/.factory/hooks/hooks.json`。
* Droid 允许在 `hooks.json` 中写注释和尾随逗号。安装和卸载写回的是普通 JSON，因此其中的注释会丢失。

### 安装如何初始化新的 Factory Droid hooks.json

`hooks.json` 一旦存在，Droid 就不再读取旧版的 `~/.factory/hooks/hooks.json`；`hooks.json` 中的 `PreToolUse` 列表还会遮蔽 `~/.factory/settings.json` 中的同名列表。因此 `hooks.json` 还不存在时，安装会先把旧版文件中的所有 hook 事件带入新文件。旧版文件没有 `PreToolUse` hook 时，改为带入 `settings.json` 中的 `PreToolUse` hook。这样原有的 hook 会继续运行。

## Factory Droid hook 检查什么

* `Execute` 是唯一的命令工具，hook 会自动识别它的 shell 方言。
* 对其他工具，hook 检查工具输入中的受保护路径。

对允许的调用，hook 不输出任何内容，因此 Factory Droid 自己的权限提示照常生效。

## Factory Droid 检查失败时会怎样

Factory Droid 的 hook 是 fail open。只有退出码 2 或明确的 deny 决策才能阻止工具调用。0 和 2 以外的退出码、崩溃、超时或缺少 `npx` 时，调用照常执行。CC Safety Net 拒绝时以退出码 2 退出，因此其他 hook 返回的允许无法推翻它。

启用企业级设置 `allowManagedHooksOnly` 后，Droid 会忽略用户级和项目级 hook，`install --droid` 写入的 hook 也就不会运行。

## Factory Droid 的覆盖限制

项目已验证 hook 能覆盖 `Execute` 和文件类工具，但尚未验证 `Task` 子智能体、`Loop` 和自动化工具的调用是否会到达 hook。

## 从 Factory Droid 卸载 CC Safety Net

```bash theme={"dark"}
npx -y cc-safety-net@latest uninstall --droid
```

卸载只移除托管处理程序。安装时从旧版文件或 `settings.json` 带入的 hook 会保留，因此卸载后生效的 hook 与安装前一致。

## Factory Droid 故障排除

读取的文件有问题时，安装会停止，不写入任何内容，并指出该文件。`doctor` 以 `Error (Factory Droid): <message>` 的形式打印 `hooks.json` 的解析错误，并以 `1` 退出。仅有注释不算解析错误。修复该文件后重新运行安装。

| 问题 | 消息 |
| - | - |
| 文件无法解析 | `Failed to parse Factory Droid hooks config <path>: <reason>` |
| `hooks.json` 或旧版文件的根不是 JSON 对象 | `Factory Droid hooks config <path> must be a JSON object` |
| 其中的 `PreToolUse` 不是数组 | `Factory Droid hooks config <path> "PreToolUse" must be an array` |

如果 `doctor` 警告 hook 条目被改动，请重新运行安装。警告列表见[托管 hook 漂移](/docs/zh-Hans/reference/cli/doctor.md#managed-hook-drift)。


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