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

# 在 Cursor 中安装 CC Safety Net

> 用一个全局 preToolUse hook 在 Cursor IDE 和 Cursor CLI 中安装 CC Safety Net，了解它覆盖的范围、如何卸载，以及如何解决 Claude Code 插件或原生 Cursor 插件导致的重复检查。

运行 `npx -y cc-safety-net@latest install --cursor`。它会在全局 Cursor hooks 配置 `~/.cursor/hooks.json` 中添加一个 `preToolUse` hook，因此该 hook 会保护所有项目中的 Cursor IDE 和 Cursor CLI 会话。然后运行 `npx cc-safety-net doctor`，确认 hook 已生效。该 hook 是 fail closed 的：hook 无法做出决策时，Cursor 会拒绝工具调用。

## 在 Cursor 中安装 CC Safety Net

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

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

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

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

hook 就位后，`doctor` 输出中 Cursor 一行显示 `Detected`、`Configured` 和 `Verified`。

## Cursor 安装会改动什么

安装程序在 `~/.cursor/hooks.json` 的 `hooks.preToolUse` 下写入以下条目，所在文档的版本为 `"version": 1`：

```json theme={"dark"}
{ "command": "npx -y cc-safety-net hook --cursor", "timeout": 30, "failClosed": true }
```

如果安装无法识别该文件的版本或结构，会报错失败，而不是改写文件。再次运行安装会只保留一个托管条目，并删除重复项。

## Cursor hook 检查什么

hook 检查 Cursor 的 `Shell` 工具调用，在每条命令运行前对其进行分析。Cursor 的 `working_directory` 必须位于工作区根目录之内。如果该字段已声明却缺失，或者指向根目录之外，hook 会拒绝该调用。

## Cursor 检查失败时会怎样

该条目设置了 `failClosed: true`，因此 hook 无法判定的工具调用会被 Cursor 拒绝。hook 的 `timeout` 为 30 秒。

## 从 Cursor 卸载 CC Safety Net

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

卸载只删除托管的 hook 条目，`~/.cursor/hooks.json` 中的其他内容保持不变。

如果磁盘上有[原生 Cursor 插件](#cursor-through-a-native-cursor-plugin)，卸载也会将其删除：运行 `cursor-agent plugin marketplace remove cc-safety-net`，删除 `~/.cursor/plugins/` 下该插件的文件，并在报告中加入以下内容：

```text theme={"dark"}
Removed the cc-safety-net marketplace from your Cursor account.
If /plugins in cursor-agent still lists CC Safety Net as installed, uninstall it there.
```

## Cursor 运行 CC Safety Net 的其他途径

Cursor 还可以通过另外两条途径运行 CC Safety Net，`install --cursor` 不会配置其中任何一条。如果其中一条在运行，同时 hook 也已就位，Cursor 会把每次工具调用检查两遍。`doctor` 会报告这两条途径，但无法判断 Cursor 是否真的在运行它们。

### 通过 Claude Code 插件保护 Cursor

[Claude Code 插件](/docs/zh-Hans/installation/claude-code.md)中还包含一个 Cursor 插件，带有同样的 `failClosed` hook。Cursor 导入 Claude Code 插件时会运行它。Cursor 只从 `<home>/.claude` 导入，因此这条途径会忽略 `CLAUDE_CONFIG_DIR` 和 `CLAUDE_CODE_PLUGIN_CACHE_DIR`。

如果 `install --cursor` 的 hook 也已配置，`doctor` 会输出：

```text theme={"dark"}
Warning (Cursor): The Claude Code plugin also runs this check in Cursor, so every tool call is checked twice. Cursor runs the Claude Code plugin only while it imports Claude Code plugins, which doctor cannot check. If Cursor runs it, run `cc-safety-net uninstall --cursor` to remove this hook.
```

如果只有这个插件一条途径，`doctor` 会把 Cursor 计为 `Configured`，并警告 Cursor 只在导入 Claude Code 插件期间运行该插件。如果 Cursor 不再导入这些插件，请运行 `install --cursor`。这种情况下，[`update`](/docs/zh-Hans/reference/cli/update) 不会添加 `npx` hook，安装选择器也会把 Cursor 显示为 `already installed`。

### 通过原生 Cursor 插件保护 Cursor

你也可以通过 `cursor-agent` 把 CC Safety Net 作为原生 Cursor 插件添加到 Cursor，它会以个人市场的形式注册到你的 Cursor 账户。Cursor 会把市场插件固定在添加时的那个提交上，因此 `cc-safety-net update` 无法把它更新到新版本。而 `npx` hook 每次调用都会解析到当前版本。

插件下载的文件位于 `~/.cursor/plugins/cache/cc-safety-net` 下时，`doctor` 会把它计入。Cursor 在你卸载插件后仍会保留这些文件，因此它们并不能证明插件仍在运行。如果 `install --cursor` 的 hook 也已配置，`doctor` 会输出：

```text theme={"dark"}
Warning (Cursor): The Cursor plugin also runs this check, so every tool call is checked twice. Cursor records enabled plugins on your Cursor account, which doctor cannot check, and keeps a plugin's files after it is uninstalled. Cursor pins marketplace plugins to the commit they were added at, so `cc-safety-net update` cannot update this plugin, while the npx hook (`cc-safety-net install --cursor`) stays current. If the plugin is installed, run `cc-safety-net uninstall --cursor`, uninstall CC Safety Net from /plugins in cursor-agent, then run `cc-safety-net install --cursor`.
```

如果只有这个插件一条途径，`doctor` 会把 Cursor 计为 `Configured`，但仍会警告它无法检查插件是否已启用，并且 `update` 无法更新该插件。如果 `cursor-agent` 的 `/plugins` 中没有把 CC Safety Net 列为已安装，请运行 `install --cursor`。这种情况下，`update` 不会添加 `npx` hook。

## Cursor hook 故障排除

* **`doctor` 警告某个 hook 条目被改动。** 你或其他工具编辑了托管条目，例如它的 `timeout` 或 `failClosed`。再次运行 `install --cursor` 即可重写该条目。相关警告见[托管 hook 漂移](/docs/zh-Hans/reference/cli/doctor.md#managed-hook-drift)。
* **`doctor` 报告 `Failed to parse Cursor hooks config`。** `~/.cursor/hooks.json` 不是有效的 JSON。修正该文件后重新安装。见 [hook 配置解析错误](/docs/zh-Hans/reference/cli/doctor.md#hook-config-parse-errors)。
* **选择器把 Cursor 显示为 `CLI not installed`。** 选择器会先运行 `cursor --version`，失败后再运行 `cursor-agent --version`。请确保两者之一在 `PATH` 上。


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