failproofai 0.0.2 → 0.0.3

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

@@ -0,0 +1,142 @@
+---
+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

@@ -0,0 +1,253 @@
+---
+title: 示例
+description: "如何为 Claude Code 和 Agents SDK 设置 Hook"
+icon: book-open
+---
+
+适用于常见场景的即用型示例，每个示例均说明安装方式及预期效果。
+
+---
+
+## 为 Claude Code 设置 Hook
+
+Failproof AI 通过 [hooks 系统](https://docs.anthropic.com/en/docs/claude-code/hooks)与 Claude Code 集成。运行 `failproofai policies --install` 后，它会在 Claude Code 的 `settings.json` 中注册 Hook 命令，这些命令将在每次工具调用时触发。
+
+<Steps>
+  <Step title="安装 failproofai">
+    ```bash
+    npm install -g failproofai
+    ```
+  </Step>
+  <Step title="启用所有内置策略">
+    ```bash
+    failproofai policies --install
+    ```
+  </Step>
+  <Step title="验证 Hook 已注册">
+    ```bash
+    cat ~/.claude/settings.json | grep failproofai
+    ```
+
+    你应该能看到 `PreToolUse`、`PostToolUse`、`Notification` 和 `Stop` 事件对应的 Hook 条目。
+  </Step>
+  <Step title="运行 Claude Code">
+    ```bash
+    claude
+    ```
+
+    策略现在会在每次工具调用时自动执行。可以尝试让 Claude 运行 `sudo rm -rf /`，该命令将被拦截。
+  </Step>
+</Steps>
+
+---
+
+## 为 Agents SDK 设置 Hook
+
+如果你正在使用 [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) 开发，同样可以通过编程方式使用相同的 Hook 系统。
+
+<Steps>
+  <Step title="在项目中安装 failproofai">
+    ```bash
+    npm install failproofai
+    ```
+  </Step>
+  <Step title="在 Agent 中配置 Hook">
+    在创建 Agent 进程时传入 Hook 命令。Hook 的触发方式与 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 获取输出之前对其进行脱敏处理。
+
+---
+
+## 在 Agent 需要关注时发送 Slack 提醒
+
+使用 Notification Hook 将空闲提醒转发至 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 {
+      // never block the agent if Slack is unreachable
+    }
+
+    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 的团队成员都将自动应用这些规则。
+
+---
+
+## 更多示例
+
+仓库中的 [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) 目录包含以下内容：
+
+| 文件 | 内容说明 |
+|------|---------------|
+| `policies-basic.js` | 基础策略——拦截生产环境写入、强制推送、管道脚本执行 |
+| `policies-notification.js` | 针对空闲通知和会话结束的 Slack 提醒 |
+| `policies-advanced/index.js` | 传递式导入、异步 Hook、PostToolUse 输出脱敏、Stop 事件处理 |

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

@@ -0,0 +1,38 @@
+---
+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

@@ -0,0 +1,134 @@
+---
+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-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>

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

@@ -0,0 +1,57 @@
+---
+title: Failproof AI
+description: "管理钩子与策略，让你的 AI 智能体保持可靠并自主运行"
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+为 **Claude Code** 和 **Agents SDK** 提供钩子与策略，让你的 AI 智能体保持可靠并自主运行。
+
+AI 智能体的失败方式往往是可预测的：执行破坏性命令、泄露密钥、偏离任务、陷入循环，或直接推送到主分支。一旦无人看管，小问题就会接连爆发。
+
+Failproof AI 通过**策略**来解决这些问题——这些规则会钩入每一次智能体工具调用，能够**检测故障**、**缓解故障**（拦截、指令纠正、脱敏处理），并在需要关注时**提醒你**。本地仪表板让你事后随时查看所有详情。
+
+一切均在本地运行，数据不会离开你的机器。
+
+## 开始使用
+
+<CardGroup cols={2}>
+
+<Card title="26 条内置策略" icon="shield" href="/zh/built-in-policies">
+  开箱即用：拦截破坏性命令、防止密钥泄露、将智能体限制在项目边界内，以及更多功能。
+</Card>
+
+<Card title="自定义策略" icon="code" href="/zh/custom-policies">
+  使用简洁的 allow / deny / instruct API，用 JavaScript 编写你自己的规则。
+</Card>
+
+<Card title="智能体监控" icon="chart-line" href="/zh/dashboard">
+  查看智能体在你离开期间做了什么。浏览会话、检查工具调用、查看策略触发记录。
+</Card>
+
+<Card title="轻松配置" icon="gear" href="/zh/configuration">
+  无需编写代码即可调整任意策略。按项目或全局设置白名单、受保护分支或阈值。
+</Card>
+
+</CardGroup>
+
+## 快速上手
+
+<CodeGroup>
+
+```bash npm
+npm install -g failproofai
+```
+
+```bash bun
+bun add -g failproofai
+```
+
+</CodeGroup>
+
+```bash
+failproofai policies --install   # enable policies
+failproofai                      # launch the dashboard
+```
+
+完整的操作流程请参阅[入门指南](/zh/getting-started)。

package/.next/standalone/docs/zh/package-aliases.mdx

@@ -0,0 +1,82 @@
+---
+title: 包别名
+description: "已注册的防拼写错误别名及其工作原理"
+icon: copy
+---
+
+## 官方包
+
+npm 的正式包名为 **`failproofai`**：
+
+```bash
+npm install -g failproofai
+# or
+bun add -g failproofai
+```
+
+---
+
+## 为什么我们持有这些别名
+
+供应链攻击中，拼写抢注（typosquatting）是一种常见手段——恶意攻击者注册一个与热门包名仅有一个按键之差的包名，不知情的用户在安装时一旦输错，便会运行攻击者控制的代码，并获得完整的系统访问权限。这正是 Failproof AI 所要防范的威胁。
+
+为消除这一攻击面，**我们在 npm 上抢先注册了 `failproofai` 的所有常见拼写错误和格式变体**。这些包名均无法被第三方注册。每个别名都是一个轻量代理，安装后会自动委托给真正的 `failproofai` 包。
+
+---
+
+## 已注册的别名
+
+**格式变体** —— "failproof ai" 的不同写法：
+
+| 包名 | 状态 |
+|---------|--------|
+| `failproof` | ✅ 已发布 |
+| `failproof-ai` | ⏳ 等待 npm 审核 |
+| `fail-proof-ai` | ⏳ 等待 npm 审核 |
+| `failproof_ai` | ⏳ 等待 npm 审核 |
+| `fail_proof_ai` | ⏳ 等待 npm 审核 |
+| `fail-proofai` | ⏳ 等待 npm 审核 |
+
+**`failprof*` 拼写错误** —— "proof" 中缺少一个 `o`：
+
+| 包名 | 状态 |
+|---------|--------|
+| `failprof` | ✅ 已发布 |
+| `failprof-ai` | ✅ 已发布 |
+| `failprofai` | ⏳ 等待 npm 审核 |
+| `fail-prof-ai` | ⏳ 等待 npm 审核 |
+| `failprof_ai` | ⏳ 等待 npm 审核 |
+
+**`faliproof*` 拼写错误** —— `a` 和 `i` 互换位置：
+
+| 包名 | 状态 |
+|---------|--------|
+| `faliproof` | ✅ 已发布 |
+| `faliproof-ai` | ✅ 已发布 |
+| `faliproofai` | ⏳ 等待 npm 审核 |
+
+> **为什么显示"等待审核"？** npm 的防滥用政策会拦截那些在去除标点符号并经过相似度检测后与已有包名规范化为同一字符串的新包名。我们已联系 npm 支持团队，申请以防抢注为由保留这些名称，获批后将正式激活。
+
+您可以通过以下命令验证任意已发布的别名均归我们所有：
+
+```bash
+npm info failproof
+# Look for: "ExosphereHost Inc." in the maintainers field
+```
+
+---
+
+## 别名的工作原理
+
+每个别名包的工作方式如下：
+
+1. 将 `failproofai` 列为依赖项——安装时会运行真正的包（包括其 `postinstall` 钩子配置）
+2. 暴露一个与自身同名的可执行文件（例如 `failprof-ai`），将所有参数代理转发给 `failproofai` 二进制文件
+
+代理逻辑仅为两行 Node 脚本，没有任何业务逻辑、网络请求，也不会收集 `failproofai` 本身行为之外的任何数据。
+
+---
+
+## 如果您发现我们遗漏的包名
+
+请在 [exospherehost/failproofai](https://github.com/exospherehost/failproofai/issues) 提交 issue，我们会及时注册。