> ## Documentation Index
> Fetch the complete documentation index at: https://exosphere-auto-translate-docs-20260623-1106.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始

> 安装 failproofai，启用策略，让你的智能体稳定运行

## 系统要求

* **Node.js** >= 20.9.0
* **Bun** >= 1.3.0（可选，仅在从源码构建时需要）

***

## 安装

<CodeGroup>
  ```bash npm theme={null}
  npm install -g failproofai
  ```

  ```bash bun theme={null}
  bun add -g failproofai
  ```
</CodeGroup>

***

## 快速上手

<Steps>
  <Step title="启用策略">
    策略是在每次智能体工具调用前后执行的规则。它们能在破坏性命令、密钥泄露及其他故障发生之前将其拦截。

    ```bash theme={null}
    failproofai policies --install
    ```

    该命令会将 hook 条目写入已安装的智能体 CLI 中（Claude Code 的 `~/.claude/settings.json`、OpenAI Codex 的 `~/.codex/hooks.json`、GitHub Copilot CLI 的 `~/.copilot/hooks/failproofai.json`、Cursor Agent 的 `~/.cursor/hooks.json`、OpenCode 在 `~/.config/opencode/plugins/failproofai.mjs` 生成的插件 shim 以及 `~/.config/opencode/opencode.json` 的 `plugin` 数组中的注册条目、Pi 的 `~/.pi/agent/settings.json`，或 Gemini CLI 的 `~/.gemini/settings.json`）。如果检测到多个已安装的 CLI，系统会提示你选择；也可以通过 `--cli claude codex copilot cursor opencode pi gemini`（任意子集）跳过提示。

    GitHub Copilot CLI、Cursor Agent、OpenCode、Pi 和 Gemini CLI 的支持目前处于 **测试阶段** — 分别使用 `--cli copilot`、`--cli cursor`、`--cli opencode`、`--cli pi` 或 `--cli gemini` 进行安装。

    ```bash theme={null}
    failproofai policies --install --scope project
    failproofai policies --install --cli codex --scope project
    failproofai policies --install --cli copilot --scope project
    failproofai policies --install --cli cursor --scope project
    failproofai policies --install --cli opencode --scope project
    failproofai policies --install --cli pi --scope project
    failproofai policies --install --cli gemini --scope project
    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
    ```
  </Step>

  <Step title="验证安装">
    ```bash theme={null}
    failproofai policies
    ```

    显示所有策略、是否已启用，以及已配置的参数。
  </Step>

  <Step title="启动控制台">
    ```bash theme={null}
    failproofai
    ```

    在 `http://localhost:8020` 打开本地控制台，你可以在此浏览会话记录、查看工具调用详情并管理策略。
  </Step>

  <Step title="运行智能体">
    像往常一样启动 Claude Code。如果智能体尝试执行危险操作，failproofai 会自动拦截。你可以让它在无人值守的情况下运行，事后在控制台中查看发生了什么。
  </Step>
</Steps>

***

## 策略的工作原理

每次智能体执行工具时，Claude Code 会将 failproofai 作为子进程调用：

```text theme={null}
Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
                                                 evaluates policies
                                                 writes decision to stdout
```

每条策略会返回以下三种决策之一：

* **allow** — 智能体正常继续执行
* **deny** — 操作被阻止，智能体会收到阻止原因说明
* **instruct** — 在智能体的提示中追加额外上下文

<Note>
  策略在本地进程中运行，不会向远程服务发送任何数据。
</Note>

***

## 使用约定式策略建立团队规范

在团队中快速建立质量标准的最便捷方式是使用 `.failproofai/policies/` 约定目录。只需将策略文件放入该目录，它们就会自动加载——无需任何标志、配置变更或安装命令。

<Steps>
  <Step title="创建策略目录">
    ```bash theme={null}
    mkdir -p .failproofai/policies
    ```
  </Step>

  <Step title="添加策略文件">
    复制示例文件或自行编写：

    ```bash theme={null}
    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
    ```

    或者创建一个新文件：

    ```js theme={null}
    // .failproofai/policies/team-policies.mjs
    import { customPolicies, allow, deny, instruct } from "failproofai";

    customPolicies.add({
      name: "test-before-commit",
      match: { events: ["PreToolUse"] },
      fn: async (ctx) => {
        if (ctx.toolName !== "Bash") return allow();
        if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
          return instruct("Run tests before committing.");
        }
        return allow();
      },
    });
    ```
  </Step>

  <Step title="提交到 Git">
    ```bash theme={null}
    git add .failproofai/policies/
    git commit -m "Add team quality policies"
    ```

    所有已安装 failproofai 的团队成员都会自动获取这些策略，无需额外的个人配置。
  </Step>
</Steps>

<Tip>
  将 `.failproofai/policies/` 提交到代码仓库，让整个团队共享相同的标准。随着团队发现新的故障模式，只需添加策略并推送——所有人在下次 `git pull` 时即可获得更新。随着时间推移，这些策略将成为持续演进的质量标准。
</Tip>

***

## 数据存储

所有配置和日志均保存在本地机器上：

| 路径                                        | 存储内容                  |
| ----------------------------------------- | --------------------- |
| `~/.failproofai/policies-config.json`     | 全局策略配置                |
| `~/.failproofai/hook-activity.jsonl`      | Hook 执行历史             |
| `~/.failproofai/hook.log`                 | 自定义 hook 错误的调试日志      |
| `.failproofai/policies-config.json`       | 项目级配置（可提交到仓库）         |
| `.failproofai/policies-config.local.json` | 个人覆盖配置（已加入 gitignore） |

***

## 卸载

```bash theme={null}
failproofai policies --uninstall
```

从 `~/.claude/settings.json` 中移除 hook 条目。`~/.failproofai/` 中的配置文件将被保留。

***

## 后续步骤

<CardGroup cols={2}>
  <Card title="配置说明" icon="gear" href="/zh/configuration">
    作用域与配置文件格式
  </Card>

  <Card title="内置策略" icon="shield" href="/zh/built-in-policies">
    全部 26 条策略及其参数说明
  </Card>

  <Card title="自定义策略" icon="code" href="/zh/custom-policies">
    使用 JavaScript 编写自己的策略
  </Card>

  <Card title="智能体监控" icon="chart-line" href="/zh/dashboard">
    监控会话并查看策略活动记录
  </Card>
</CardGroup>