failproofai 0.0.2 → 0.0.3

package/.next/standalone/docs/zh/cli/list-policies.mdx

@@ -0,0 +1,31 @@
+---
+title: 列出策略
+description: "查看已启用的策略、其参数以及自定义策略"
+---
+
+```bash
+failproofai policies
+```
+
+显示所有策略及其状态、已配置的参数和自定义策略。
+
+## 示例输出
+
+```text
+Failproof AI Hook Policies (user)
+
+  Status  Name                          Description
+  ──────  ──────────────────────────────────────────────────────────────
+  ✓       block-sudo                    Block sudo commands
+            allowPatterns: ["sudo systemctl status"]
+  ✓       block-rm-rf                   Block recursive deletions
+  ✗       block-curl-pipe-sh            Block curl|bash patterns
+  ✓       sanitize-api-keys             Redact API keys from output
+            additionalPatterns: [{ regex: "MY_TOKEN_...", label: "..." }]
+
+  ── Custom Policies (/home/alice/myproject/my-policies.js) ──────────────
+  ✓       require-jira-ticket           Block commits without ticket
+  ✓       approval-gate                 Approval gate for destructive ops
+```
+
+`policyParams` 中的未知键会在此处标记出来，帮助你尽早发现拼写错误。

package/.next/standalone/docs/zh/cli/remove-policies.mdx

@@ -0,0 +1,44 @@
+---
+title: 卸载策略
+description: "从 Claude Code 的设置中移除 hook 条目"
+---
+
+```bash
+failproofai policies --uninstall [policy-names...] [options]
+```
+
+从 Claude Code 的 `settings.json` 中移除 failproofai hook 条目。
+
+别名：`failproofai p -u`
+
+## 选项
+
+| 标志 | 描述 |
+|------|------|
+| `--scope user` | 从全局设置中移除（默认） |
+| `--scope project` | 从项目设置中移除 |
+| `--scope local` | 从本地设置中移除 |
+| `--scope all` | 同时从所有作用域中移除 |
+| `--custom` / `-c` | 从配置中清除 `customPoliciesPath` |
+| `--beta` | 仅从配置中移除 beta 策略 |
+
+## 行为说明
+
+- **不指定策略名称** — 从设置文件中移除所有 failproofai hook 条目
+- **指定具体名称** — 禁用对应策略，但保留已安装的 hook
+
+## 示例
+
+```bash
+# 全局移除所有 hook
+failproofai policies --uninstall
+
+# 禁用特定策略（保留已安装的 hook）
+failproofai policies --uninstall block-sudo
+
+# 从所有作用域中移除 hook
+failproofai policies --uninstall --scope all
+
+# 清除自定义策略路径
+failproofai policies --uninstall --custom
+```

package/.next/standalone/docs/zh/cli/version.mdx

@@ -0,0 +1,12 @@
+---
+title: 查看版本
+description: "打印已安装的 failproofai 版本"
+---
+
+```bash
+failproofai --version
+# or
+failproofai -v
+```
+
+打印已安装的版本号。

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

@@ -0,0 +1,222 @@
+---
+title: 配置
+description: "配置文件格式、三级作用域系统及合并规则"
+icon: gear
+---
+
+failproofai 使用 JSON 配置文件来控制哪些策略处于激活状态、策略的行为方式以及自定义策略的加载位置。配置设计便于与团队共享——将其提交到代码仓库，每位开发者都能获得相同的智能体安全防护网。
+
+---
+
+## 配置作用域
+
+共有三个配置作用域，按优先级顺序进行评估：
+
+| 作用域 | 文件路径 | 用途 |
+|-------|-----------|---------|
+| **project** | `.failproofai/policies-config.json` | 每个代码仓库的配置，提交到版本控制 |
+| **local** | `.failproofai/policies-config.local.json` | 个人级别的仓库覆盖配置，已加入 .gitignore |
+| **global** | `~/.failproofai/policies-config.json` | 适用于所有项目的用户级默认配置 |
+
+当 failproofai 接收到 hook 事件时，会加载并合并当前工作目录下存在的所有三个文件。
+
+### 合并规则
+
+**`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
+```
+
+**`customPoliciesPath`** — 最先定义该字段的作用域优先。
+
+**`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` 的用户将获得与之前版本完全相同的行为。
+
+策略参数块中的未知键在 hook 触发时会被静默忽略，但运行 `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`（绝对路径）
+
+包含自定义 hook 策略的 JavaScript 文件路径。此字段由 `failproofai policies --install --custom <path>` 自动设置（路径在存储前会解析为绝对路径）。
+
+每次 hook 事件触发时都会重新加载该文件，不存在缓存机制。关于编写自定义策略的详情，请参阅[自定义策略](/zh/custom-policies)。
+
+### 基于约定的策略（v0.0.2-beta.7+）
+
+除显式指定的 `customPoliciesPath` 外，failproofai 还会自动发现并加载 `.failproofai/policies/` 目录中的策略文件：
+
+| 级别 | 目录 | 作用域 |
+|-------|-----------|-------|
+| 项目 | `.failproofai/policies/` | 通过版本控制与团队共享 |
+| 用户 | `~/.failproofai/policies/` | 个人级别，适用于所有项目 |
+
+**文件匹配规则：** 仅加载符合 `*policies.{js,mjs,ts}` 模式的文件（例如 `security-policies.mjs`、`workflow-policies.js`），目录中的其他文件将被忽略。
+
+**无需配置：** 约定策略无需在 `policies-config.json` 中添加任何条目。只需将文件放入对应目录，下次 hook 事件触发时即可自动加载。
+
+**联合加载：** 项目级和用户级约定目录都会被扫描。两个级别中所有匹配的文件都会被加载（与 `customPoliciesPath` 的首个作用域优先规则不同）。
+
+更多详情和示例请参阅[自定义策略](/zh/custom-policies)。
+
+### `llm`
+
+类型：`object`（可选）
+
+适用于需要进行 AI 调用的策略的 LLM 客户端配置。大多数场景下无需配置。
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## 通过 CLI 管理配置
+
+`policies --install` 和 `policies --uninstall` 命令会写入 Claude Code 的 `settings.json`（hook 入口点），而 `policies-config.json` 则是由你直接管理的文件。两者相互独立：
+
+- **`settings.json`** — 告知 Claude Code 在每次工具调用时执行 `failproofai --hook <event>`
+- **`policies-config.json`** — 告知 failproofai 要评估哪些策略以及使用什么参数
+
+你可以随时直接编辑 `policies-config.json`，修改将在下次 hook 事件触发时立即生效，无需重启。
+
+---
+
+## 示例：包含团队默认值的项目级配置
+
+将 `.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/zh/custom-policies.mdx

@@ -0,0 +1,357 @@
+---
+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
+```
+
+---
+
+## 两种加载自定义策略的方式
+
+### 方式一：基于约定（推荐，v0.0.2-beta.7+）
+
+将 `*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 --uninstall --custom
+```
+
+解析后的绝对路径以 `customPoliciesPath` 的形式存储在 `policies-config.json` 中。每次 hook 事件都会重新加载该文件——事件之间不存在缓存。
+
+### 同时使用两种方式
+
+基于约定的策略与显式 `--custom` 文件可以共存。加载顺序如下：
+
+1. 显式 `customPoliciesPath` 文件（如已配置）
+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 消息（Beta）
+
+<Note>
+`allow(message)` 是自 v0.0.2-beta.3 起提供的 Beta 功能。API 可能在未来版本中发生变化。早期版本仅支持不带参数的 `allow()`。
+</Note>
+
+`allow(message)` 允许操作**并**向 Claude 发送一条信息性消息。该消息以 `additionalContext` 的形式通过 hook 处理器的 stdout 响应发送——与 `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 事件触发时，文件会被自动加载。