failproofai 0.0.6-beta.2 → 0.0.6-beta.4

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

@@ -1,142 +0,0 @@
----
-title: 控制台
-description: "监控 Agent 会话、查看工具调用并管理策略"
-icon: chart-line
----
-
-failproofai 控制台是一个本地 Web 应用，用于监控 AI Agent 会话和管理策略。随时查看 Agent 在后台执行了哪些操作。
-
----
-
-## 启动控制台
-
-```bash
-failproofai
-```
-
-访问地址：`http://localhost:8020`。
-
-控制台直接从文件系统读取数据——包括 Claude Code 项目文件夹和 failproofai 配置文件。所有数据均不会上传至远程服务。
-
----
-
-## 页面说明
-
-### 项目
-
-列出本机上所有已发现的 Claude Code 项目。项目从 `~/.claude/projects/`（或 `CLAUDE_PROJECTS_PATH` 环境变量指定的路径）中自动发现。
-
-每个项目展示以下信息：
-- 项目名称（从文件夹路径派生）
-- 会话数量
-- 最近一次会话活动的日期
-
-点击项目可查看其下所有会话。
-
-### 会话
-
-列出某个项目下的所有会话。每个会话展示：
-- 会话 ID
-- 开始和结束时间戳
-- 工具调用次数
-- Hook 活动次数（触发的策略数量）
-
-可使用日期范围筛选器和会话 ID 搜索来缩小列表范围。会话列表支持分页。
-
-点击会话可打开会话查看器。
-
-### 会话查看器
-
-会话查看器回答了自主 Agent 最核心的问题：Agent 做了什么，是否按预期执行？它以时间线形式展示会话中发生的所有事件：
-
-- **消息** — Claude 的文本回复和用户提示
-- **工具调用** — Claude 调用的每个工具，包含其输入和输出
-- **策略活动** — 针对每次工具调用，显示哪些策略触发以及返回了什么决策
-
-顶部统计栏显示会话时长、工具调用总次数，以及 Hook 决策汇总（allow / deny / instruct 的数量统计）。
-
-可通过下载按钮将会话导出为 ZIP 或 JSONL 文件。
-
-### 策略
-
-包含两个选项卡，用于管理策略和查看活动记录。
-
-<Tabs>
-  <Tab title="策略选项卡">
-  - 单击即可启用或禁用某条策略（写入 `~/.failproofai/policies-config.json`）
-  - 展开策略以配置其参数（适用于支持 `policyParams` 的策略）
-  - 为指定作用域安装或移除 Hook
-  - 设置自定义策略文件路径
-  </Tab>
-  <Tab title="活动选项卡">
-  - 跨所有会话的所有 Hook 事件完整分页历史记录
-  - 可按策略名称、会话 ID、工具名称或决策进行搜索
-  - 每行显示：时间戳、策略名称、决策、工具名称、会话 ID，以及 deny/instruct 决策的原因
-  </Tab>
-</Tabs>
-
----
-
-## 自动刷新
-
-控制台顶部导航栏提供自动刷新开关。启用后，当前页面将定期刷新，实时显示新增的会话和策略活动。这对于监控长时间运行的自主 Agent 会话尤为重要。
-
----
-
-## 禁用页面
-
-如果只需要控制台的部分功能，可将 `FAILPROOFAI_DISABLE_PAGES` 设置为以逗号分隔的页面名称列表：
-
-```bash
-FAILPROOFAI_DISABLE_PAGES=policies failproofai
-```
-
-有效值：`policies`、`projects`。
-
----
-
-## 主题
-
-控制台支持亮色和暗色模式，可通过导航栏中的按钮切换。偏好设置存储在浏览器的本地存储中。
-
----
-
-## 配置项目路径
-
-默认情况下，控制台从标准的 Claude Code 项目目录读取数据。如需自定义设置，可覆盖该路径：
-
-```bash
-CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
-```
-
----
-
-## 从非 localhost 主机访问
-
-在**开发模式**（`npm run dev`）下运行控制台，并通过非 `localhost` 的主机名访问时——例如自定义域名、远程 IP 或隧道 URL——可能会看到如下警告：
-
-```text
-⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
-```
-
-这是 Next.js 阻止跨域访问其 HMR（热模块重载）WebSocket 的行为，该功能仅在开发模式下存在。如需允许特定主机访问，请使用 `--allowed-origins` 参数：
-
-```bash
-npm run dev -- --allowed-origins dashboard.example.com
-```
-
-如需允许多个主机或 IP，以逗号分隔传入：
-
-```bash
-npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
-```
-
-也可以通过设置 `FAILPROOFAI_ALLOWED_DEV_ORIGINS` 环境变量来实现：
-
-```bash
-FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
-```
-
-<Note>
-此设置仅适用于开发模式。运行 `failproofai`（生产模式）时，不存在 HMR WebSocket，也不存在跨域开发资源问题。
-</Note>

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

@@ -1,307 +0,0 @@
----
-title: 示例
-description: "如何为 Claude Code 和 Agents SDK 设置钩子"
-icon: book-open
----
-
-开箱即用的常见场景示例，每个示例均说明了安装方式及预期效果。
-
----
-
-## 为 Claude Code 设置钩子
-
-Failproof AI 通过 [钩子系统](https://docs.anthropic.com/en/docs/claude-code/hooks) 与 Claude Code 集成。运行 `failproofai policies --install` 后，它会在 Claude Code 的 `settings.json` 中注册钩子命令，并在每次工具调用时触发。
-
-<Steps>
-  <Step title="安装 failproofai">
-    ```bash
-    npm install -g failproofai
-    ```
-  </Step>
-  <Step title="启用所有内置策略">
-    ```bash
-    failproofai policies --install
-    ```
-  </Step>
-  <Step title="验证钩子已注册">
-    ```bash
-    cat ~/.claude/settings.json | grep failproofai
-    ```
-
-    你应该能看到 `PreToolUse`、`PostToolUse`、`Notification` 和 `Stop` 事件的钩子条目。
-  </Step>
-  <Step title="运行 Claude Code">
-    ```bash
-    claude
-    ```
-
-    策略现在会在每次工具调用时自动运行。你可以尝试让 Claude 执行 `sudo rm -rf /`，该命令将被拦截。
-  </Step>
-</Steps>
-
----
-
-## 为 Agents SDK 设置钩子
-
-如果你正在使用 [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) 进行开发，可以通过编程方式使用相同的钩子系统。
-
-<Steps>
-  <Step title="在项目中安装 failproofai">
-    ```bash
-    npm install failproofai
-    ```
-  </Step>
-  <Step title="在 Agent 中配置钩子">
-    在创建 Agent 进程时传入钩子命令。钩子的触发方式与 Claude Code 中完全一致——通过 stdin/stdout JSON：
-
-    ```bash
-    failproofai --hook PreToolUse   # 每次工具调用前触发
-    failproofai --hook PostToolUse  # 每次工具调用后触发
-    ```
-  </Step>
-  <Step title="为 Agent 编写自定义策略">
-    ```javascript
-    import { customPolicies, allow, deny } from "failproofai";
-
-    customPolicies.add({
-      name: "limit-to-project-dir",
-      description: "Keep the agent inside the project directory",
-      match: { events: ["PreToolUse"] },
-      fn: async (ctx) => {
-        const path = String(ctx.toolInput?.file_path ?? "");
-        if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
-          return deny("Agent is restricted to the project directory");
-        }
-        return allow();
-      },
-    });
-    ```
-  </Step>
-  <Step title="安装自定义策略">
-    ```bash
-    failproofai policies --install --custom ./my-agent-policies.js
-    ```
-  </Step>
-</Steps>
-
----
-
-## 阻止破坏性命令
-
-最常见的配置——防止 Agent 造成不可逆的破坏。
-
-```bash
-failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
-```
-
-各策略说明：
-- `block-sudo` — 阻止所有 `sudo` 命令
-- `block-rm-rf` — 阻止递归删除文件
-- `block-force-push` — 阻止 `git push --force`
-- `block-curl-pipe-sh` — 阻止将远程脚本通过管道传给 Shell 执行
-
----
-
-## 防止密钥泄漏
-
-阻止 Agent 在工具输出中查看或泄漏凭证。
-
-```bash
-failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
-```
-
-这些策略在 `PostToolUse` 阶段触发——工具运行完毕后，会在 Agent 看到输出之前对其进行清理。
-
----
-
-## 通过 Slack 接收 Agent 待处理提醒
-
-使用通知钩子将空闲提醒转发到 Slack。
-
-```javascript
-import { customPolicies, allow, instruct } from "failproofai";
-
-customPolicies.add({
-  name: "slack-on-idle",
-  description: "Alert Slack when the agent is waiting for input",
-  match: { events: ["Notification"] },
-  fn: async (ctx) => {
-    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
-    if (!webhookUrl) return allow();
-
-    const message = String(ctx.payload?.message ?? "Agent is waiting");
-    const project = ctx.session?.cwd ?? "unknown";
-
-    try {
-      await fetch(webhookUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          text: `*${message}*\nProject: \`${project}\``,
-        }),
-        signal: AbortSignal.timeout(5000),
-      });
-    } catch {
-      // 如果 Slack 不可达，绝不阻塞 Agent
-    }
-
-    return allow();
-  },
-});
-```
-
-安装方式：
-
-```bash
-SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js
-```
-
----
-
-## 将 Agent 限制在指定分支
-
-防止 Agent 切换分支或推送到受保护的分支。
-
-```javascript
-import { customPolicies, allow, deny } from "failproofai";
-
-customPolicies.add({
-  name: "stay-on-branch",
-  description: "Prevent the agent from checking out other branches",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const cmd = String(ctx.toolInput?.command ?? "");
-    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
-      return deny("Stay on the current branch. Create a new branch with -b if needed.");
-    }
-    return allow();
-  },
-});
-```
-
----
-
-## 提交前要求运行测试
-
-提醒 Agent 在提交之前先运行测试。
-
-```javascript
-import { customPolicies, allow, instruct } from "failproofai";
-
-customPolicies.add({
-  name: "test-before-commit",
-  description: "Remind the agent to run tests before committing",
-  match: { events: ["PreToolUse"] },
-  fn: async (ctx) => {
-    if (ctx.toolName !== "Bash") return allow();
-    const cmd = String(ctx.toolInput?.command ?? "");
-    if (/git\s+commit/.test(cmd)) {
-      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
-    }
-    return allow();
-  },
-});
-```
-
----
-
-## 锁定生产仓库
-
-在项目中提交一份项目级配置文件，让团队中每位开发者都使用相同的策略。
-
-在仓库中创建 `.failproofai/policies-config.json`：
-
-```json
-{
-  "enabledPolicies": [
-    "block-sudo",
-    "block-rm-rf",
-    "block-force-push",
-    "block-push-master",
-    "block-env-files",
-    "sanitize-api-keys",
-    "sanitize-jwt"
-  ],
-  "policyParams": {
-    "block-push-master": {
-      "protectedBranches": ["main", "release", "production"]
-    }
-  }
-}
-```
-
-然后提交：
-
-```bash
-git add .failproofai/policies-config.json
-git commit -m "Add failproofai team policies"
-```
-
-所有已安装 failproofai 的团队成员将自动应用这些规则。
-
----
-
-## 通过约定策略构建全组织的质量标准
-
-最具影响力的配置方式：将 `.failproofai/policies/` 目录提交到仓库，并在其中编写针对项目量身定制的策略。每位团队成员都会自动获取——无需执行安装命令，无需修改配置。
-
-<Steps>
-  <Step title="创建目录并添加策略">
-    ```bash
-    mkdir -p .failproofai/policies
-    ```
-
-    ```js
-    // .failproofai/policies/team-policies.mjs
-    import { customPolicies, allow, deny, instruct } from "failproofai";
-
-    // 强制使用团队指定的包管理器
-    // （也可以启用内置的 prefer-package-manager 策略）
-    customPolicies.add({
-      name: "enforce-bun",
-      match: { events: ["PreToolUse"] },
-      fn: async (ctx) => {
-        if (ctx.toolName !== "Bash") return allow();
-        const cmd = String(ctx.toolInput?.command ?? "");
-        if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm.");
-        return allow();
-      },
-    });
-
-    // 提醒 Agent 在提交前运行测试
-    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
-    git add .failproofai/policies/
-    git commit -m "Add team quality policies"
-    ```
-  </Step>
-  <Step title="持续优化">
-    随着团队遇到新的故障模式，不断添加策略并推送。每个人在下次 `git pull` 时即可获取更新。这些策略将成为一套随团队共同成长的活态质量标准。
-  </Step>
-</Steps>
-
----
-
-## 更多示例
-
-仓库中的 [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) 目录包含以下内容：
-
-| 文件 | 说明 |
-|------|------|
-| `policies-basic.js` | 入门策略——阻止写入生产环境、强制推送和管道脚本 |
-| `policies-notification.js` | 空闲通知和会话结束时发送 Slack 提醒 |
-| `policies-advanced/index.js` | 传递性导入、异步钩子、PostToolUse 输出清理、Stop 事件处理 |

package/.next/standalone/docs/zh/for-agents.mdx

@@ -1,38 +0,0 @@
----
-title: "适用于 Agent"
-description: "一条命令即可将 Failproof AI 知识添加到你的编程 Agent 中。支持 Claude Code、Cursor、Windsurf 等。"
----
-
-一条命令即可将完整的 Failproof AI 参考文档添加到你的编程 Agent 中。支持 Claude Code、Cursor、Windsurf 以及任何其他支持技能（skills）的 Agent。
-
-```bash
-npx skills add https://docs.befailproof.ai
-```
-
-`npx skills` 会自动检测你已安装的 Agent，并以每个 Agent 对应的正确格式添加该技能。
-
-## 技能涵盖的内容
-
-| 领域 | 包含内容 |
-|------|----------------|
-| 策略（Policies） | 内置策略名称、事件类型、参数、启用/禁用 |
-| 自定义策略 | `customPolicies.add()`、匹配过滤器、`allow`/`deny`/`instruct` API |
-| 上下文对象 | `ctx.eventType`、`ctx.toolName`、`ctx.toolInput`、`ctx.session` |
-| 配置 | `policies-config.json` 结构、作用域合并、`policyParams` |
-| CLI | `failproofai policies --install`、`--uninstall`、`--custom`、作用域 |
-| 控制台 | 会话查看器、策略活动、环境变量 |
-| 架构 | Hook 处理器流程、退出码、stdin/stdout 约定 |
-
-## 技能内容是否完整？
-
-Mintlify 会从导航中所有页面生成 `llms.txt`。Failproof AI 文档覆盖了完整的 API——每一条策略、选项和示例均已收录。如果你发现有遗漏，源文件位于 `https://docs.befailproof.ai/llms-full.txt`。
-
-如需针对性的上下文内容，可直接链接到特定页面：
-
-```bash
-# 仅获取自定义策略 API
-npx skills add https://docs.befailproof.ai/custom-policies
-
-# 仅获取内置策略
-npx skills add https://docs.befailproof.ai/built-in-policies
-```

package/.next/standalone/docs/zh/getting-started.mdx

@@ -1,186 +0,0 @@
----
-title: 快速开始
-description: "安装 failproofai，启用策略，让你的 Agent 稳定运行"
-icon: rocket
----
-
-## 环境要求
-
-- **Node.js** >= 20.9.0
-- **Bun** >= 1.3.0（可选，仅在从源码构建时需要）
-
----
-
-## 安装
-
-<CodeGroup>
-
-```bash npm
-npm install -g failproofai
-```
-
-```bash bun
-bun add -g failproofai
-```
-
-</CodeGroup>
-
----
-
-## 快速上手
-
-<Steps>
-  <Step title="启用策略">
-    策略是在每次 Agent 工具调用前后执行的规则，能够在破坏性命令、密钥泄露及其他故障模式造成损害之前将其拦截。
-
-    ```bash
-    failproofai policies --install
-    ```
-
-    该命令会将 hook 条目写入 Claude Code 的 `settings.json`。你也可以仅为单个项目安装，或选择特定策略：
-
-    ```bash
-    failproofai policies --install --scope project
-    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
-    ```
-  </Step>
-  <Step title="验证安装">
-    ```bash
-    failproofai policies
-    ```
-
-    显示所有策略、启用状态及已配置的参数。
-  </Step>
-  <Step title="启动控制台">
-    ```bash
-    failproofai
-    ```
-
-    在 `http://localhost:8020` 打开本地控制台，你可以在此浏览会话记录、查看工具调用详情并管理策略。
-  </Step>
-  <Step title="运行你的 Agent">
-    像往常一样启动 Claude Code。如果 Agent 尝试执行风险操作，failproofai 会自动拦截。你可以让其在无人值守的情况下运行，之后在控制台中回顾发生的一切。
-  </Step>
-</Steps>
-
----
-
-## 策略工作原理
-
-每当 Agent 运行工具时，Claude Code 会以子进程方式调用 failproofai：
-
-```text
-Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
-                                                 evaluates policies
-                                                 writes decision to stdout
-```
-
-每条策略会返回以下三种决策之一：
-
-- **allow** - Agent 正常继续执行
-- **deny** - 操作被拦截，并将原因告知 Agent
-- **instruct** - 向 Agent 的提示词中追加额外的上下文信息
-
-<Note>
-策略在你的本地进程中运行，不会向任何远程服务发送数据。
-</Note>
-
----
-
-## 使用约定式策略为团队制定统一规范
-
-在团队中建立质量标准最快的方式是使用 `.failproofai/policies/` 约定目录。只需将策略文件放入该目录，它们会自动加载——无需任何标志、配置变更或安装命令。
-
-<Steps>
-  <Step title="创建策略目录">
-    ```bash
-    mkdir -p .failproofai/policies
-    ```
-  </Step>
-  <Step title="添加策略文件">
-    复制示例文件或编写你自己的策略：
-
-    ```bash
-    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
-    ```
-
-    或者新建一个策略文件：
-
-    ```js
-    // .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
-    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
-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="Agent 监控" icon="chart-line" href="/zh/dashboard">
-  监控会话并查看策略活动记录
-</Card>
-
-</CardGroup>