failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,199 @@
+---
+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 条目写入你已安装的 Agent 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` 生成的插件垫片及 `~/.config/opencode/opencode.json` `plugin` 数组中的注册条目、Pi 的 `~/.pi/agent/settings.json`、Hermes 的 `~/.hermes/config.yaml`、OpenClaw 的 `~/.openclaw/openclaw.json`、Factory Droid 的 `~/.factory/hooks.json`、Devin CLI 的 `~/.config/devin/config.json`、Antigravity CLI 的 `~/.gemini/config/hooks.json`，以及 Goose 自动发现的插件目录 `~/.agents/plugins/failproofai/hooks/hooks.json`）。如果检测到多个 CLI，将弹出选择提示；传入 `--cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose`（任意子集）可跳过提示。
+
+    GitHub Copilot CLI、Cursor Agent、OpenCode 和 Pi 的支持目前处于 **Beta** 阶段 —— 分别使用 `--cli copilot`、`--cli cursor`、`--cli opencode` 或 `--cli pi` 安装。Hermes（hermes-agent，一个 Slack/Telegram 网关）使用 `--cli hermes` 以用户级别安装，**同时**也是一个离线审计数据源。OpenClaw（openclaw 网关，一个自托管多渠道助手）使用 `--cli openclaw` 以用户级别安装 —— 执行通过其进程内插件 hook（`before_agent_finalize` 是真正的轮次结束门控，因此 `require-*-before-stop` 内置规则会生效）—— **同时**也是一个离线审计数据源。Factory Droid（`droid`）使用 `--cli factory` 安装（用户 + 项目级别），**同时**也是一个离线审计数据源。Devin CLI（`devin`，Cognition）使用 `--cli devin` 安装（用户 + 项目级别），**同时**也是一个离线审计数据源。Antigravity CLI（`agy`）使用 `--cli antigravity` 安装（用户 + 项目级别），**同时**也是一个离线审计数据源。Goose（代号 goose，Block）使用 `--cli goose` 安装（用户 + 项目级别）—— 安装程序会在 `~/.agents/plugins/failproofai/` 创建插件目录，Goose 会自动发现该目录，**同时**也是一个离线审计数据源。
+
+    ```bash
+    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 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 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/local-policies/policies-config.json` | 全局策略配置 |
+| `~/.failproofai/hook-activity/` | Hook 执行历史（分页 JSONL） |
+| `~/.failproofai/logs/` | 自定义 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-old/zh/introduction.mdx

@@ -0,0 +1,57 @@
+---
+title: "Failproof AI"
+description: "FailproofAI 为 AI 智能体内置 39 条失效策略，一次安装即可捕获循环、密钥泄露、破坏性工具调用等问题。"
+---
+
+[![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai)
+
+用于 **AI 故障处理**、**错误恢复** 和 **LLM 可靠性** 的钩子与策略。让你的 AI 智能体在 **Claude Code**、**OpenAI Codex**、**GitHub Copilot**、**Cursor Agent**、**OpenCode**、**Pi**、**Hermes**、**OpenClaw**、**Factory Droid**、**Devin CLI**、**Antigravity CLI** 以及 **Agents SDK** 上稳定、自主地持续运行。
+
+AI 智能体的失效方式往往是可预测的：执行破坏性命令、泄露密钥、偏离任务、陷入循环，或直接推送到主分支。若无人值守，小故障会接连引发服务中断、凭证泄露和数据丢失。
+
+FailproofAI 通过**策略**来解决这些问题。这些规则挂钩于智能体的每一次工具调用，**检测故障**、**加以缓解**（阻断、指导、净化），并在需要关注时**及时提醒你**。本地仪表盘让你可以事后回顾每一次工具调用、智能体故障及恢复动作。
+
+会话记录和策略评估均保存在本地。仅当你主动使用在线功能（如认证审计提醒或邀请功能）时，数据才会被发送。
+
+## 开始使用
+
+<CardGroup cols={2}>
+
+<Card title="39 条内置策略" 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 (or skip — `failproofai` will offer to set them up on first run)
+failproofai                      # launch the dashboard
+```
+
+完整流程请参阅[快速入门](/zh/getting-started)指南。

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

@@ -0,0 +1,82 @@
+---
+title: 包别名
+description: "已注册的防错字抢注别名及其工作原理"
+icon: copy
+---
+
+## 官方包
+
+npm 的正式包名为 **`failproofai`**：
+
+```bash
+npm install -g failproofai
+# or
+bun add -g failproofai
+```
+
+---
+
+## 为什么我们持有这些别名
+
+错字抢注是一种常见的供应链攻击手段——恶意行为者注册与热门包名仅差一个按键的包名，毫无防备的用户在安装时一旦拼错命令，就会以完整系统权限运行攻击者控制的代码。这正是 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` 列为依赖项——因此真正的包会被安装，其二进制文件也会随之可用
+2. 暴露一个与自身同名的二进制文件（例如 `failprof-ai`），将所有参数代理转发给 `failproofai` 二进制文件
+
+代理脚本仅有两行 Node 代码，不含任何逻辑处理、网络请求或超出 `failproofai` 本身的数据收集行为。
+
+---
+
+## 如果您发现我们遗漏的包名
+
+请在 [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) 提交 Issue，我们会及时注册。

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

@@ -0,0 +1,260 @@
+---
+title: 测试
+description: "单元测试、E2E 测试及测试辅助工具"
+icon: flask-vial
+---
+
+failproofai 包含两套测试：**单元测试**（快速、使用 mock）和**端到端测试**（真实子进程调用）。
+
+---
+
+## 运行测试
+
+```bash
+# 单次运行所有单元测试
+bun run test:run
+
+# 以监听模式运行单元测试
+bun run test
+
+# 运行 E2E 测试（需要先完成配置，见下文）
+bun run test:e2e
+
+# 类型检查（不编译）
+bunx tsc --noEmit
+
+# 代码检查
+bun run lint
+```
+
+---
+
+## 单元测试
+
+单元测试位于 `__tests__/` 目录，使用 [Vitest](https://vitest.dev) 和 `jsdom`。
+
+```text
+__tests__/
+  hooks/
+    builtin-policies.test.ts      # 各内置策略的逻辑
+    hooks-config.test.ts          # 配置加载与作用域合并
+    policy-evaluator.test.ts      # 参数注入与求值顺序
+    custom-hooks-registry.test.ts # globalThis 注册表的增删改查
+    custom-hooks-loader.test.ts   # ESM 加载器、传递导入、错误处理
+    manager.test.ts               # install/remove/list 操作
+  components/
+    sessions-list.test.tsx        # 会话列表组件
+    project-list.test.tsx         # 项目列表组件
+    ...
+  lib/
+    logger.test.ts
+    paths.test.ts
+    date-filters.test.ts
+    telemetry.test.ts
+    ...
+  actions/
+    get-hooks-config.test.ts
+    get-hook-activity.test.ts
+    ...
+  contexts/
+    ThemeContext.test.tsx
+    AutoRefreshContext.test.tsx
+```
+
+### 编写策略单元测试
+
+```typescript
+import { describe, it, expect, beforeEach } from "vitest";
+import { getBuiltinPolicies } from "../../src/hooks/builtin-policies";
+import { allow, deny } from "../../src/hooks/policy-types";
+
+describe("block-sudo", () => {
+  const policy = getBuiltinPolicies().find((p) => p.name === "block-sudo")!;
+
+  it("denies sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo apt install nodejs" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(deny("sudo command blocked by failproofai"));
+  });
+
+  it("allows non-sudo commands", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "ls -la" },
+      params: { allowPatterns: [] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+
+  it("allows patterns in allowPatterns", () => {
+    const ctx = {
+      eventType: "PreToolUse" as const,
+      payload: {},
+      toolName: "Bash",
+      toolInput: { command: "sudo systemctl status nginx" },
+      params: { allowPatterns: ["sudo systemctl status"] },
+    };
+    expect(policy.fn(ctx)).toEqual(allow());
+  });
+});
+```
+
+---
+
+## 端到端测试
+
+E2E 测试将真实的 `failproofai` 二进制文件作为子进程调用，通过 stdin 传入 JSON payload，并对 stdout 输出和退出码进行断言。这覆盖了 Claude Code 所使用的完整集成路径。
+
+### 配置
+
+E2E 测试直接从仓库源码运行二进制文件。在首次运行之前，需要构建自定义 hook 文件在导入 `'failproofai'` 时所依赖的 CJS 包：
+
+```bash
+bun build src/index.ts --outdir dist --target node --format cjs
+```
+
+然后运行测试：
+
+```bash
+bun run test:e2e
+```
+
+每当修改公共 hook API（`src/hooks/custom-hooks-registry.ts`、`src/hooks/policy-helpers.ts` 或 `src/hooks/policy-types.ts`）后，都需要重新构建 `dist/`。
+
+### E2E 测试结构
+
+```text
+__tests__/e2e/
+  helpers/
+    hook-runner.ts      # 启动二进制文件、传入 payload JSON、捕获退出码 + stdout + stderr
+    fixture-env.ts      # 每个测试独立的临时目录与配置文件
+    payloads.ts         # 符合 Claude 格式的各事件类型 payload 工厂函数
+  hooks/
+    builtin-policies.e2e.test.ts   # 各内置策略的真实子进程测试
+    custom-hooks.e2e.test.ts       # 自定义 hook 的加载与求值
+    config-scopes.e2e.test.ts      # 跨项目/本地/全局的配置合并
+    policy-params.e2e.test.ts      # 各参数化策略的参数注入
+```
+
+### 使用 E2E 辅助工具
+
+**`FixtureEnv`** - 每个测试独立的隔离环境：
+
+```typescript
+import { createFixtureEnv } from "../helpers/fixture-env";
+
+const env = createFixtureEnv();
+// env.cwd    - 临时目录；作为 payload.cwd 传入，用于加载 .failproofai/policies-config.json
+// env.home   - 隔离的 home 目录；不会读取真实的 ~/.failproofai
+
+env.writeConfig({
+  enabledPolicies: ["block-sudo"],
+  policyParams: {
+    "block-sudo": { allowPatterns: ["sudo systemctl status"] },
+  },
+});
+```
+
+`createFixtureEnv()` 会自动注册 `afterEach` 清理逻辑。
+
+**`runHook`** - 调用二进制文件：
+
+```typescript
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+const result = await runHook(
+  "PreToolUse",
+  Payloads.preToolUse.bash("sudo apt install nodejs", env.cwd),
+  { homeDir: env.home }
+);
+
+expect(result.exitCode).toBe(0);
+expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+```
+
+**`Payloads`** - 现成的 payload 工厂函数：
+
+```typescript
+Payloads.preToolUse.bash(command, cwd)
+Payloads.preToolUse.write(filePath, content, cwd)
+Payloads.preToolUse.read(filePath, cwd)
+Payloads.postToolUse.bash(command, output, cwd)
+Payloads.postToolUse.read(filePath, content, cwd)
+Payloads.notification(message, cwd)
+Payloads.stop(cwd)
+```
+
+### 编写 E2E 测试
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { createFixtureEnv } from "../helpers/fixture-env";
+import { runHook } from "../helpers/hook-runner";
+import { Payloads } from "../helpers/payloads";
+
+describe("block-rm-rf (E2E)", () => {
+  it("denies rm -rf", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm -rf /", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny");
+  });
+
+  it("allows non-recursive rm", async () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-rm-rf"] });
+
+    const result = await runHook(
+      "PreToolUse",
+      Payloads.preToolUse.bash("rm /tmp/file.txt", env.cwd),
+      { homeDir: env.home }
+    );
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).toBe("");  // allow → 空 stdout
+  });
+});
+```
+
+### E2E 响应格式
+
+| 决策 | 退出码 | stdout |
+|----------|-----------|--------|
+| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` |
+| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` |
+| Instruct（非 Stop）| `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` |
+| Stop instruct | `2` | 空 stdout；原因输出到 stderr |
+| Allow | `0` | 空字符串 |
+
+### Vitest 配置
+
+E2E 测试使用 `vitest.config.e2e.mts`，配置如下：
+
+- `environment: "node"` - 无需浏览器全局变量
+- `pool: "forks"` - 真正的进程隔离（测试会启动子进程）
+- `testTimeout: 20_000` - 每个测试 20 秒超时（含二进制启动 + hook 求值）
+
+`forks` 池非常重要：基于线程的 worker 共享 `globalThis`，可能干扰子进程启动类的测试，而基于进程的 forks 可以避免这一问题。
+
+---
+
+## CI
+
+合并前必须通过完整的 CI 流程（`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`）。E2E 测试套件作为独立的 CI 任务并行运行。
+
+完整的合并前检查清单请参阅 [Contributing](../CONTRIBUTING.md)。