failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/zh/configuration.mdx

@@ -0,0 +1,266 @@
+---
+title: 配置
+description: "配置文件格式、三级作用域系统及合并规则"
+icon: gear
+---
+
+failproofai 使用 JSON 配置文件来控制哪些策略处于激活状态、策略的行为方式，以及从何处加载自定义策略。配置设计上便于与团队共享——将其提交到代码仓库，每位开发者都能获得相同的智能体安全防护。
+
+---
+
+## 配置作用域
+
+配置共有三个作用域，按优先级顺序依次评估：
+
+| 作用域 | 文件路径 | 用途 |
+|-------|-----------|---------|
+| **project** | `.failproofai/policies-config.json` | 按仓库配置，提交至版本控制 |
+| **local** | `.failproofai/policies-config.local.json` | 个人按仓库覆盖配置，已添加至 gitignore |
+| **global** | `~/.failproofai/policies-config.json` | 跨所有项目的用户级默认配置 |
+
+当 failproofai 收到钩子事件时，它会加载并合并当前工作目录下存在的所有三个文件。
+
+### 合并规则
+
+**`enabledPolicies`** — 取三个作用域的并集。在任意级别启用的策略均处于激活状态。
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← 去重后的并集
+```
+
+**`policyParams`** — 对于给定策略，最先定义参数的作用域完全优先。策略参数内部不会进行深度合并。
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project 优先，global 被忽略
+```
+
+```text
+project:  （无 block-sudo 条目）
+local:    （无 block-sudo 条目）
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← 回退至 global
+```
+
+**`customPoliciesPaths` / `customPoliciesPath`** — 最先定义任意一种形式的作用域优先。
+
+**`disabledCustomPolicies`** — 取所有作用域的并集。当你在仪表板中关闭来自显式或约定策略文件中的某个策略时，仪表板会将带来源限定符的 ID 写入此处。未列出的策略默认保持启用；ID 包含来源文件信息，因此多个文件中同名的策略可以独立控制。
+
+**`llm`** — 最先定义的作用域优先。
+
+---
+
+## 配置文件格式
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "sanitize-jwt",
+    "block-env-files",
+    "block-read-outside-cwd"
+  ],
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    },
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "prod"]
+    },
+    "block-rm-rf": {
+      "allowPaths": ["/tmp"]
+    },
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company"]
+    },
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
+      ]
+    },
+    "warn-large-file-write": {
+      "thresholdKb": 512
+    }
+  },
+  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
+}
+```
+
+---
+
+## 字段参考
+
+### `enabledPolicies`
+
+类型：`string[]`
+
+要启用的策略名称列表。名称必须与 `failproofai policies` 所显示的策略标识符完全匹配。完整列表请参见[内置策略](/zh/built-in-policies)。
+
+不在 `enabledPolicies` 中的策略均为非激活状态，即便其在 `policyParams` 中存在条目也是如此。
+
+### `policyParams`
+
+类型：`Record<string, Record<string, unknown>>`
+
+按策略的参数覆盖配置。外层键为策略名称，内层键为各策略专有配置项。每个策略的可用参数均在[内置策略](/zh/built-in-policies)中有说明。
+
+若策略有参数但你未指定，则使用策略的内置默认值。未配置 `policyParams` 的用户与旧版本行为完全一致。
+
+策略参数块中的未知键在钩子触发时会被静默忽略，但在运行 `failproofai policies` 时会被标记为警告。
+
+#### `hint`（通用配置项）
+
+类型：`string`（可选）
+
+当策略返回 `deny` 或 `instruct` 时，附加到原因中的提示消息。可用于向 Claude 提供可操作的指导，而无需修改策略本身。
+
+适用于所有策略类型——内置策略、自定义策略（`custom/`）、项目约定策略（`.failproofai-project/`）或用户约定策略（`.failproofai-user/`）。
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Try creating a fresh branch instead."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "Use apt-get directly without sudo."
+    },
+    "custom/my-policy": {
+      "hint": "Ask the user for approval first."
+    }
+  }
+}
+```
+
+当 `block-force-push` 拒绝操作时，Claude 会看到：*"Force-pushing is blocked. Try creating a fresh branch instead."*
+
+非字符串值和空字符串会被静默忽略。若未设置 `hint`，行为保持不变（向后兼容）。
+
+### `customPoliciesPath`
+
+类型：`string`（绝对路径）
+
+包含自定义钩子策略的 JavaScript 文件路径。该字段由 `failproofai policies --install --custom <path>` 自动设置（路径在存储前会被解析为绝对路径）。
+
+每次钩子事件触发时，该文件都会重新加载，不进行缓存。编写详情请参见[自定义策略](/zh/custom-policies)。
+
+### 基于约定的策略
+
+除显式的 `customPoliciesPath` 外，failproofai 还会自动发现并加载 `.failproofai/policies/` 目录中的策略文件：
+
+| 级别 | 目录 | 作用域 |
+|-------|-----------|-------|
+| 项目级 | `.failproofai/policies/` | 通过版本控制与团队共享 |
+| 用户级 | `~/.failproofai/policies/custom-policies/` | 个人使用，适用于所有项目 |
+
+<Note>
+  用户级目录在主目录重组时下移了一层。升级后首次运行任意 `failproofai`
+  命令时，旧路径 `~/.failproofai/policies/` 下的文件会自动移入
+  `custom-policies/`，且命令会告知你移动了哪些文件。
+</Note>
+
+**文件匹配规则：** 仅加载匹配 `*policies.{js,mjs,ts}` 的文件（例如 `security-policies.mjs`、`workflow-policies.js`），目录中的其他文件会被忽略。
+
+**无需配置：** 约定策略无需在 `policies-config.json` 中添加任何条目。只需将文件放入目录，下次钩子事件触发时即会自动加载。
+
+**联合加载：** 项目级和用户级约定目录均会被扫描，两个级别的所有匹配文件都会被加载（与 `customPoliciesPath` 使用首个作用域优先的规则不同）。
+
+更多详情和示例请参见[自定义策略](/zh/custom-policies)。
+
+### `llm`
+
+类型：`object`（可选）
+
+供需要进行 AI 调用的策略使用的 LLM 客户端配置。大多数场景下无需配置。
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## 通过 CLI 管理配置
+
+`policies --install` 和 `policies --uninstall` 命令写入智能体 CLI 的钩子设置文件（钩子入口点），而 `policies-config.json` 则是你直接管理的文件。两者相互独立：
+
+- **智能体 CLI 设置** — 告知智能体在每次工具调用时执行 `failproofai --hook <event>`：
+  - **Claude Code**：`~/.claude/settings.json`（用户级）、`<cwd>/.claude/settings.json`（项目级）、`<cwd>/.claude/settings.local.json`（本地级）
+  - **OpenAI Codex**：`~/.codex/hooks.json`（用户级）、`<cwd>/.codex/hooks.json`（项目级）——Codex 没有 `local` 作用域
+  - **GitHub Copilot CLI _(beta)_**：`~/.copilot/hooks/failproofai.json`（用户级）、`<cwd>/.github/hooks/failproofai.json`（项目级）——Copilot 没有 `local` 作用域。钩子条目使用 Copilot 的操作系统键控 `bash`/`powershell` 命令字段及 `timeoutSec`；文件带有顶层 `version: 1` 标记。Copilot CLI 支持处于 **beta** 阶段，我们正在针对更多真实会话验证 `events.jsonl` 记录模式（公开文档中未予说明）。**VS Code Copilot Chat 智能体模式（预览版）** 通过 `chat.hookFilesLocations` 设置从 `.github/hooks/*.json`、`~/.copilot/hooks/*.json` 和 `~/.claude/settings.json` 读取钩子配置，使用与 Claude 相同的 `{hookSpecificOutput:{permissionDecision:"deny",…}}` 协议——这正是 `copilot` 集成和 `claude` 集成（`~/.claude/settings.json`）已写入的路径，因此 `failproofai policies --install --cli copilot`（或 `--cli claude`）**无需单独的 `vscode` 集成即可在 VS Code 智能体模式下强制执行**（已通过 VS Code 发现日志实时确认）。
+  - **Cursor Agent _(beta)_**：`~/.cursor/hooks.json`（用户级）、`<cwd>/.cursor/hooks.json`（项目级）——Cursor 没有 `local` 作用域。钩子条目使用 Claude 风格的 `{type, command, timeout}` 格式（无 `bash`/`powershell` 分离），但按照 Cursor 的[钩子模式](https://cursor.com/docs/hooks)以驼峰命名的事件键（`preToolUse`、`beforeSubmitPrompt` 等）存储于每个 Cursor 事件的扁平数组中；文件带有顶层 `version: 1` 标记。处理器通过 `CURSOR_EVENT_MAP` 将驼峰命名规范化为帕斯卡命名，使现有内置策略无需修改即可触发。Cursor Agent 支持处于 **beta** 阶段，我们正在针对更多真实安装验证 Cursor 的磁盘转录格式（公开文档中未予说明）。
+  - **OpenCode _(beta)_**：`~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs`（用户级）、`<cwd>/.opencode/opencode.json` + `<cwd>/.opencode/plugins/failproofai.mjs`（项目级）——OpenCode 没有 `local` 作用域。与其他五个 CLI 不同，OpenCode **没有外部命令钩子系统**：它通过 `opencode.json` 中的 `plugin: []` 数组显式注册来加载进程内 JS/TS 插件（从 `.opencode/plugins/` 自动发现**不是** opencode v1.14.33 上插件加载的方式）。安装时会放置一个小型生成的插件垫片，该垫片以子进程方式调用 failproofai 二进制文件，并将二进制文件的 Claude 风格 JSON 响应转换为插件语义：工具事件拒绝时 `throw new Error()`（取消工具调用），instruct 及 `Stop`/`SubagentStop` 拒绝时 `client.session.prompt(...)`（将拒绝原因作为下一条用户消息提交——这是唯一的强制重试通道，因为 `session.idle` 仅用于通知，从中抛出异常无效），allow 时无操作。垫片在转发给二进制文件前会规范化工具名称（小写转帕斯卡命名，通过 `OPENCODE_TOOL_MAP`）和工具输入参数键（驼峰转蛇形命名，通过 `OPENCODE_TOOL_INPUT_MAP`，适用于 `Read`/`Write`/`Edit`，例如 `filePath` → `file_path`、`oldString` → `old_string`），因此路径检查内置策略如 `block-read-outside-cwd`、`block-env-files` 和 `block-secrets-write` 在 OpenCode 工具调用中可正常触发。会话存储于 `~/.local/share/opencode/opencode.db` 的 opencode SQLite 数据库中；仪表板的会话查看器通过 `opencode db --format json` 和 `opencode export <id>` 读取它们。OpenCode 支持处于 **beta** 阶段，我们正在跨版本和更多真实会话验证其行为。请参阅 [OpenCode 插件文档](https://opencode.ai/docs/plugins/)。
+  - **Pi _(beta)_**：`~/.pi/agent/settings.json`（用户级）、`<cwd>/.pi/settings.json`（项目级）——Pi 没有 `local` 作用域。Pi 在启动时加载 TypeScript 扩展包；设置文件是一个扁平字符串数组 `{"packages": ["./relative/path", …]}`。failproofai 写入一个指向其捆绑 `pi-extension/` 目录的 packages 数组条目。该扩展在内部订阅 Pi 的 `tool_call`/`user_bash`/`input`/`session_start` 事件，并以子进程方式调用 `failproofai --hook <Event> --cli pi`；处理器通过 `PI_EVENT_MAP` 将下划线小写蛇形命名规范化为帕斯卡命名，使现有内置策略无需修改即可触发。工具输入参数也通过 `PI_TOOL_INPUT_MAP` 进行规范化（Pi 的 Read/Write/Edit 传递 `path` 而非 `file_path`；映射顶层键使 `block-env-files` 和 `block-secrets-write` 得以触发——`block-read-outside-cwd` 已有 `path` 回退机制）。Pi 支持处于 **beta** 阶段，待 Pi 的扩展 API 和会话日志布局稳定后会进一步完善。
+  - **Hermes (hermes-agent)**：`~/.hermes/config.yaml`（**仅用户作用域**——Hermes 没有项目/本地配置）。Hermes 是一个 Slack/Telegram **网关**，因此一次安装即可拦截来自所有平台（Slack/Telegram/cli/cron）**及**内部子智能体的工具调用。钩子条目是一个 `{command, timeout}` 对（超时单位为**秒**），位于以 Hermes 蛇形命名事件（`pre_tool_call`/`post_tool_call`/`on_session_start`/`on_session_end`/`subagent_stop`）为键的 `hooks:` 映射下；处理器通过 `HERMES_EVENT_MAP` 规范化事件名称，通过 `HERMES_TOOL_MAP` 规范化工具名称，使内置策略无需修改即可触发。配置通过保留注释的 YAML `Document` 往返编辑，以保留运营者的其他设置；安装时设置 `hooks_auto_accept: true`，使无头网关（无 TTY）在无需同意提示的情况下运行钩子。评估器输出 Hermes 的 `{"decision":"block","reason"}` stdout 协议（Hermes 忽略退出码）。**限制：** Hermes 没有轮次结束 `Stop` 事件，因此 `require-*-before-stop` 内置策略对其永不触发（不适用，而非故障）；`instruct` 降级为允许并记录日志（无附加上下文通道）；输出密钥脱敏（`sanitize-*`）无法通过 shell 钩子协议重写工具输出。Hermes **同时也是**离线**审计**来源——仪表板直接从 `~/.hermes/state.db` 读取其网关会话。
+  - **OpenClaw (openclaw gateway)**：`~/.openclaw/openclaw.json`（**仅用户作用域**——OpenClaw 没有项目/本地配置）。与 Hermes 类似，OpenClaw 是一个自托管的多渠道**网关**，因此一次安装即可拦截来自所有渠道及其内部子智能体的工具调用。强制执行通过 OpenClaw 的**进程内插件钩子**运行（其基于文件的内部钩子仅用于观察，无法阻止），因此——与 OpenCode/Pi 类似——failproofai 提供了一个静态 `openclaw-plugin/` 包，以异步方式生成 failproofai 二进制文件并转换判决结果。安装时在 `openclaw.json` 的 `plugins.load.paths[]` 中注册所提供的插件目录，并在 `plugins.entries.failproofai` 下启用它（带有 `hooks.allowConversationAccess: true`，原始对话钩子必需）。评估器输出扁平的 `{permission, reason}` 判决，垫片将其映射到每个钩子的原生返回形式：`before_tool_call → {block:true, blockReason}`（**PreToolUse**）、`before_agent_run → {outcome:"block", reason}`（**UserPromptSubmit**）和 `before_agent_finalize → {action:"revise", reason}`（**Stop**——一个真正的轮次结束门控，因此 `require-*-before-stop` 内置策略**在 OpenClaw 上强制执行**，与 Hermes 不同）。事件和工具名称在二进制端通过 `OPENCLAW_EVENT_MAP`/`OPENCLAW_TOOL_MAP`（`exec→Bash`、`read→Read` 等）规范化，使内置策略无需修改即可触发；垫片在任何生成/解析/超时错误时失败并放行。OpenClaw **同时也是**离线**审计**来源——仪表板读取 `~/.openclaw/agents/<agentId>/sessions/<uuid>.jsonl` 中的 JSONL 会话。
+  - **Factory Droid (`droid`)**：`~/.factory/hooks.json`（用户级）、`<cwd>/.factory/hooks.json`（项目级）——Factory 没有 `local` 作用域。droid 采用 Claude 风格的外部命令钩子系统，但经针对 droid v0.171.0 的实时验证，有两个特殊之处：（1）事件名称位于 `hooks.json` 的**顶层**——**没有 `"hooks"` 包装器**（droid 会拒绝它）；工具事件（`PreToolUse`/`PostToolUse`）带有 `"matcher": "*"`，非工具事件则省略它。（2）拒绝由钩子**退出码 2 + stderr** 驱动，而非 JSON 决策——评估器的 `factory` 分支对工具/提示事件返回退出码 2，仅在轮次结束 `Stop` 事件时返回 `{decision:"block", reason}`（droid 唯一的强制重试通道）。事件已是帕斯卡命名（无事件映射），负载为 Claude 蛇形命名；仅工具名称通过 `FACTORY_TOOL_MAP`（`Execute→Bash`、`Create→Write`、`FetchUrl→WebFetch` 等）规范化。Factory **同时也是**离线**审计**来源——仪表板读取 `~/.factory/sessions/<encoded-cwd>/<sessionId>.jsonl` 中的磁盘 JSONL 会话。
+  - **Devin CLI (`devin`，Cognition)**：`~/.config/devin/config.json`（用户级）、`<cwd>/.devin/config.json`（项目级）——Devin 没有 `local` 作用域。经针对 devin v3000.1.27 的实时验证，Devin 是一个**纯 Claude 克隆**：使用标准 Claude `"hooks"` 包装器模式（写入时保留合并，因此配置文件的其他键——`org_id`、`theme_mode` 等——得以保留），已是帕斯卡命名的事件（无事件映射，无处理器分支），以及 Claude 蛇形命名的 stdin 负载（无需规范化）。评估器的 `devin` 分支对**每个**事件在退出码 0 时以 `{"decision":"block","reason"}` JSON 输出到 stdout 进行拒绝（已验证——该块覆盖了 `--permission-mode dangerous`）；在轮次结束 `Stop` 事件中，原因携带 MANDATORY-ACTION 强制重试措辞，使 `require-*-before-stop` 内置策略得以强制执行。仅工具名称通过 `DEVIN_TOOL_MAP`（`exec→Bash`；`tool_input.command` 已是规范形式）规范化。Devin **同时也是**离线**审计**来源——仪表板读取 `~/.local/share/devin/cli/sessions.db` 中的 SQLite 会话（每个 `sessions` 行携带真实的 `working_directory`，因此会话像 Claude 一样按项目工作目录分组）。
+  - **Antigravity CLI (`agy`)**：`~/.gemini/config/hooks.json`（用户级）、`<cwd>/.agents/hooks.json`（项目级）——Antigravity 没有 `local` 作用域。与 Factory/Devin 不同，Antigravity 有其**自己的**协议（非 Claude 克隆），经针对 agy v1.1.2 的实时验证。`hooks.json` 使用**命名钩子**模式：顶层键为钩子*名称*（`"failproofai"`），其值为事件→处理器映射——工具事件（`PreToolUse`/`PostToolUse`）将处理器包装在 `{matcher:"*", hooks:[…]}` 中，而 `PreInvocation`/`Stop` 为**扁平**处理器数组（其他命名钩子得以保留）。stdin 负载为**驼峰命名的 protojson**（`toolCall:{name,args}`、`conversationId`、`workspacePaths`、`transcriptPath`）——failproofai 在策略运行前将其规范化为蛇形命名，并通过 `ANTIGRAVITY_TOOL_INPUT_MAP` 映射 `run_command` 的帕斯卡命名参数（`CommandLine`/`Cwd`）。评估器的 `antigravity` 分支使用 Antigravity **自己的**响应形式：`{decision:"deny", reason}` 阻止工具/提示（退出码 0），`{decision:"continue", reason}` 在轮次结束 `Stop` 时重新进入循环（使 `require-*-before-stop` 内置策略得以强制执行），`{injectSteps:[{ephemeralMessage}]}` 在 `PreInvocation`（→ `UserPromptSubmit`）时注入指令。工具名称通过 `ANTIGRAVITY_TOOL_MAP`（`run_command→Bash`、`view_file→Read` 等）规范化。Antigravity **同时也是**离线**审计**来源——仪表板读取 `~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/transcript_full.jsonl` 中的纯 JSONL 转录（对话索引位于 `conversation_summaries.db`）。
+  - **Goose (代号 goose，Block)**：`~/.agents/plugins/failproofai/hooks/hooks.json`（用户级）、`<cwd>/.agents/plugins/failproofai/hooks/hooks.json`（项目级）——Goose 没有 `local` 作用域。强制执行使用 Goose 的**钩子**系统，即跨智能体的 **Open Plugins** 规范：安装程序只需放置 `failproofai` 插件目录，Goose 在启动时自动发现并将其自注册到 `~/.config/goose/config.yaml`。`hooks.json` 使用带有顶层 `"hooks"` 包装器的 Open Plugins 模式，且每个事件上都**省略**了匹配器——裸 `"*"` 是一个无效正则表达式，不匹配任何内容（经针对 goose v1.43.0 的实时验证）。事件名称已是帕斯卡命名（无事件映射）；stdin 负载使用 `event`/`working_dir`，处理器将其规范化为 `hook_event_name`/`cwd`。评估器的 `goose` 分支在退出码 0 时以 `{"decision":"block","reason"}` JSON 输出到 stdout 进行拒绝，仅在 **`PreToolUse`** 事件上生效（goose ≥ v1.37.0 中提供）——该事件对 shell 工具**以及委托子智能体内部**均会触发，因此它是唯一足够的拒绝点；任何其他钩子错误均**失败并放行**。Goose **没有 `Stop` 事件**，因此 `require-*-before-stop` 内置策略不适用（与 Hermes 相同）。工具名称通过 `GOOSE_TOOL_MAP`（`shell→Bash`、`write→Write`、`todo__todo_write→TodoWrite` 等）规范化，路径键通过 `GOOSE_TOOL_INPUT_MAP`（`path`/`source` → `file_path`）规范化。Goose **同时也是**离线**审计**来源——仪表板读取 `~/.local/share/goose/sessions/sessions.db` 中的 SQLite 会话（每个 `sessions` 行携带真实的 `working_dir`，因此会话像 Devin 一样按项目工作目录分组；`--no-session` 临时运行会被过滤）。
+- **`policies-config.json`** — 告知 failproofai 评估哪些策略以及使用什么参数（跨所有智能体 CLI 共享）
+
+传入 `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` 以指定目标智能体（多个可用空格分隔或重复传入）：
+
+```bash
+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 hermes --scope user
+failproofai policies --install --cli openclaw --scope user
+failproofai policies --install --cli factory --scope project
+failproofai policies --install --cli devin --scope project
+failproofai policies --install --cli antigravity --scope project
+failproofai policies --install --cli goose --scope project
+failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose
+```
+
+省略 `--cli` 时，`failproofai` 会检测已安装的智能体 CLI（`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`）：
+
+- **检测到一个 CLI** — 自动选择该 CLI，无需提示。
+- **在交互式终端中检测到多个 CLI** — 显示方向键单选提示，分组为 `Detected (N)` 区域（包含一个`Install for all N detected` 聚合行及各个已检测到的 CLI）和 `Not installed (M) · install hooks ahead of time` 区域，列出所有未检测到的支持 CLI 作为预安装选项（↑↓ 移动，Enter 选择，^C 退出）。卸载流程仅显示 Detected 区域。
+- **在非交互式运行中检测到多个 CLI**（CI 环境、无 TTY）— 为所有检测到的 CLI 安装，无需提示。
+- **未检测到任何 CLI** — 回退至 `claude`，并警告在 PATH 中未找到智能体二进制文件；钩子命令仍会写入，待安装后立即生效。
+
+你可以随时直接编辑 `policies-config.json`；更改会在下次钩子事件时立即生效，无需重启。
+
+---
+
+## 示例：带团队默认配置的项目级配置
+
+将 `.failproofai/policies-config.json` 提交到你的代码仓库：
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-push-master",
+    "sanitize-api-keys",
+    "block-env-files"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "hotfix"]
+    }
+  }
+}
+```
+
+每位开发者可以创建 `.failproofai/policies-config.local.json`（已添加至 gitignore）用于个人覆盖配置，而不影响其他团队成员。

package/.next/standalone/docs-old/zh/custom-policies.mdx

@@ -0,0 +1,358 @@
+---
+title: 自定义策略
+description: "用 JavaScript 编写自己的策略——强制执行项目规范、防止漂移、检测失败、与外部系统集成"
+icon: code
+---
+
+自定义策略让你可以为任意 Agent 行为编写规则：强制执行项目规范、防止状态漂移、拦截破坏性操作、检测卡死的 Agent，或与 Slack、审批工作流等系统集成。它们使用与内置策略相同的 Hook 事件系统以及 `allow`、`deny`、`instruct` 决策机制。
+
+---
+
+## 快速示例
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  description: "Block writes to paths containing 'production'",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) {
+      return deny("Writes to production paths are blocked");
+    }
+    return allow();
+  },
+});
+```
+
+安装：
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## 加载自定义策略的两种方式
+
+### 方式一：基于约定（推荐）
+
+将 `*policies.{js,mjs,ts}` 文件放入 `.failproofai/policies/` 目录，它们会被自动加载——无需任何标志或配置变更。这与 git hooks 的工作方式类似：放入文件，即可生效。
+
+```
+# 项目级别——提交到 git，团队共享
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# 用户级别——个人使用，适用于所有项目
+~/.failproofai/policies/my-policies.mjs
+```
+
+**工作原理：**
+- 项目目录和用户目录均会被扫描（取并集，而非优先匹配第一个作用域）
+- 各目录内的文件按字母顺序加载，可用 `01-`、`02-` 前缀控制顺序
+- 仅加载匹配 `*policies.{js,mjs,ts}` 的文件，其他文件会被忽略
+- 每个文件独立加载（单个文件失败不影响其他文件）
+- 可与显式 `--custom` 及内置策略共同使用
+
+<Tip>
+基于约定的策略是为团队建立质量标准的最简方式。将 `.failproofai/policies/` 提交到 git，每位团队成员即可自动获得相同的规则——无需逐人配置。随着团队不断发现新的失败模式，只需添加策略并推送。久而久之，这些策略将成为一份随每次贡献持续完善的活质量标准。
+</Tip>
+
+### 方式二：显式指定文件路径
+
+```bash
+# 安装时指定自定义策略文件
+failproofai policies --install --custom ./my-policies.js
+
+# 替换自定义策略路径
+failproofai policies --install --custom ./new-policies.js
+
+# 配置多个显式文件（按标志顺序加载）
+failproofai policies --install --custom ./security.js --custom ./workflow.js
+
+# 从配置中移除所有显式自定义策略路径
+failproofai policies --uninstall --custom
+```
+
+解析后的绝对路径以 `customPoliciesPaths` 字段存储在 `policies-config.json` 中。重复使用 `--custom` 可配置多个文件。使用旧版 `customPoliciesPath` 字段的现有配置仍可正常工作。文件在每次 Hook 事件时重新加载，事件之间不存在缓存。
+
+每个已注册的策略都会在控制台中显示独立的开关。关闭某个策略时，其含源文件限定的 ID 会被记录到 `disabledCustomPolicies`；对应文件及其他策略仍会继续加载，仅禁用的策略会在事件匹配前被排除。跨文件重名的策略拥有独立的开关。
+
+### 同时使用两种方式
+
+基于约定的策略与显式 `--custom` 文件可以共存。加载顺序如下：
+
+1. 显式 `customPoliciesPaths` 文件（按配置顺序）
+2. 项目约定文件（`{cwd}/.failproofai/policies/`，按字母顺序）
+3. 用户约定文件（`~/.failproofai/policies/`，按字母顺序）
+
+---
+
+## API
+
+### 导入
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+注册一个策略。在同一文件中可多次调用以注册多个策略。
+
+```ts
+customPolicies.add({
+  name: string;                         // 必填 - 唯一标识符
+  description?: string;                 // 显示在 `failproofai policies` 输出中
+  match?: { events?: HookEventType[] }; // 按事件类型过滤；省略则匹配所有事件
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### 决策辅助函数
+
+| 函数 | 效果 | 适用场景 |
+|----------|--------|----------|
+| `allow()` | 静默允许该操作 | 操作安全，无需任何提示 |
+| `deny(message)` | 拦截该操作 | Agent 不应执行此操作 |
+| `instruct(message)` | 添加上下文但不拦截 | 为 Agent 提供额外上下文以保持正轨 |
+
+`deny(message)` —— 消息会以 `"Blocked by failproofai:"` 为前缀呈现给 Claude。单次 `deny` 会短路所有后续评估。
+
+`instruct(message)` —— 消息会附加到 Claude 当前工具调用的上下文中。所有 `instruct` 消息会被累积后统一传递。
+
+<Tip>
+你可以通过在 `policyParams` 中添加 `hint` 字段，为任意 `deny` 或 `instruct` 消息追加额外指引——无需修改代码。这对自定义（`custom/`）、项目约定（`.failproofai-project/`）和用户约定（`.failproofai-user/`）策略同样适用。详见[配置 → hint](/zh/configuration#hint-cross-cutting)。
+</Tip>
+
+### 信息性 allow 消息
+
+`allow(message)` 在允许操作的同时，向 Claude 发送一条信息性消息。该消息通过 Hook 处理器 stdout 响应中的 `additionalContext` 传递——与 `instruct` 使用相同的机制，但语义不同：它是状态更新，而非警告。
+
+| 函数 | 效果 | 适用场景 |
+|----------|--------|----------|
+| `allow(message)` | 允许操作并向 Claude 发送上下文 | 确认检查通过，或说明某项检查被跳过的原因 |
+
+使用场景：
+- **状态确认：** `allow("All CI checks passed.")` —— 告知 Claude 一切正常
+- **失败开放说明：** `allow("GitHub CLI not installed, skipping CI check.")` —— 告知 Claude 某项检查被跳过的原因，使其获得完整上下文
+- **多条消息累积：** 如果多个策略各自返回 `allow(message)`，所有消息将以换行符连接后统一传递
+
+```js
+customPolicies.add({
+  name: "confirm-branch-status",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    const cwd = ctx.session?.cwd;
+    if (!cwd) return allow("No working directory, skipping branch check.");
+
+    // ... check branch status ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### `PolicyContext` 字段
+
+| 字段 | 类型 | 描述 |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`、`"PostToolUse"`、`"Notification"`、`"Stop"` |
+| `toolName` | `string \| undefined` | 被调用的工具（如 `"Bash"`、`"Write"`、`"Read"`） |
+| `toolInput` | `Record<string, unknown> \| undefined` | 工具的输入参数 |
+| `payload` | `Record<string, unknown>` | 来自 Claude Code 的完整原始事件载荷 |
+| `session` | `SessionMetadata \| undefined` | 会话上下文（见下文） |
+
+### `SessionMetadata` 字段
+
+| 字段 | 类型 | 描述 |
+|-------|------|-------------|
+| `sessionId` | `string` | Claude Code 会话标识符 |
+| `cwd` | `string` | Claude Code 会话的工作目录 |
+| `transcriptPath` | `string` | 会话 JSONL 记录文件的路径 |
+
+### 事件类型
+
+| 事件 | 触发时机 | `toolInput` 内容 |
+|-------|--------------|----------------------|
+| `PreToolUse` | Claude 执行工具前 | 工具的输入（如 Bash 对应 `{ command: "..." }`） |
+| `PostToolUse` | 工具执行完成后 | 工具的输入 + `tool_result`（输出内容） |
+| `Notification` | Claude 发送通知时 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` —— Hook 必须始终返回 `allow()`，无法拦截通知 |
+| `Stop` | Claude 会话结束时 | 空 |
+
+---
+
+## 评估顺序
+
+策略按以下顺序进行评估：
+
+1. 内置策略（按定义顺序）
+2. 来自 `customPoliciesPath` 的显式自定义策略（按 `.add()` 调用顺序）
+3. 项目 `.failproofai/policies/` 中的约定策略（文件按字母顺序，文件内按 `.add()` 顺序）
+4. 用户 `~/.failproofai/policies/` 中的约定策略（文件按字母顺序，文件内按 `.add()` 顺序）
+
+<Note>
+首个 `deny` 会短路所有后续策略。所有 `instruct` 消息会被累积后统一传递。
+</Note>
+
+---
+
+## 传递性导入
+
+自定义策略文件可以使用相对路径导入本地模块：
+
+```js
+// my-policies.js
+import { isBlockedPath } from "./utils.js";
+import { checkApproval } from "./approval-client.js";
+
+customPolicies.add({
+  name: "approval-gate",
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
+    return approved ? allow() : deny("Approval required for this command");
+  },
+});
+```
+
+所有从入口文件可达的相对导入均会被解析。其实现方式是将 `from "failproofai"` 的导入重写为实际的 dist 路径，并创建临时 `.mjs` 文件以确保 ESM 兼容性。
+
+---
+
+## 事件类型过滤
+
+使用 `match.events` 限制策略的触发时机：
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // 仅在会话结束时触发
+    // ctx.session.transcriptPath 包含完整的会话日志
+    return allow();
+  },
+});
+```
+
+完全省略 `match` 则对所有事件类型均触发。
+
+---
+
+## 错误处理与失败模式
+
+自定义策略采用**失败开放**原则：错误不会阻止内置策略运行，也不会导致 Hook 处理器崩溃。
+
+| 失败情况 | 行为 |
+|---------|----------|
+| `customPoliciesPath` 未设置 | 不运行显式自定义策略；约定策略和内置策略照常继续 |
+| 文件未找到 | 警告记录到 `~/.failproofai/hook.log`；内置策略继续运行 |
+| 语法/导入错误（显式） | 错误记录到 `~/.failproofai/hook.log`；显式自定义策略跳过 |
+| 语法/导入错误（约定） | 错误记录；该文件跳过，其他约定文件仍正常加载 |
+| `fn` 运行时抛出异常 | 错误记录；该 Hook 视为 `allow`；其他 Hook 继续运行 |
+| `fn` 执行超过 10 秒 | 超时记录；视为 `allow` |
+| 约定目录不存在 | 不运行约定策略；不报错 |
+
+<Tip>
+要调试自定义策略错误，可监听日志文件：
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## 完整示例：多个策略
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// 防止 Agent 写入 secrets/ 目录
+customPolicies.add({
+  name: "block-secrets-dir",
+  description: "Prevent agent from writing to secrets/ directory",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
+    return allow();
+  },
+});
+
+// 保持 Agent 正轨：提交前验证测试
+customPolicies.add({
+  name: "remind-test-before-commit",
+  description: "Keep the agent on track: verify tests pass before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
+    }
+    return allow();
+  },
+});
+
+// 在冻结期内防止计划外的依赖变更
+customPolicies.add({
+  name: "dependency-freeze",
+  description: "Prevent unplanned dependency changes during freeze period",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
+    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
+      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
+    }
+    return allow();
+  },
+});
+
+export { customPolicies };
+```
+
+---
+
+## 示例文件
+
+`examples/` 目录包含开箱即用的策略文件：
+
+| 文件 | 内容 |
+|------|----------|
+| `examples/policies-basic.js` | 五个入门策略，涵盖常见 Agent 失败模式 |
+| `examples/policies-advanced/index.js` | 高级模式：传递性导入、异步调用、输出脱敏和会话结束 Hook |
+| `examples/convention-policies/security-policies.mjs` | 基于约定的安全策略（拦截 .env 写入、防止 git 历史重写） |
+| `examples/convention-policies/workflow-policies.mjs` | 基于约定的工作流策略（测试提醒、文件写入审计） |
+
+### 使用显式文件示例
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### 使用基于约定的示例
+
+```bash
+# 复制到项目级别
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# 或复制到用户级别
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+无需安装命令——文件将在下次 Hook 事件时自动被识别加载。