架构 - FailproofAI

本文档介绍 failproofai 的内部工作原理：钩子系统如何拦截 Agent 工具调用、配置如何加载与合并、策略如何评估，以及控制台如何监控 Agent 活动。

概述

failproofai 包含两个独立子系统：

钩子处理器 - 一个高速 CLI 子进程，Claude Code 在每次 Agent 工具调用时都会调用它。负责评估策略并返回决策。
Agent 监控器（控制台） - 一个用于监控 Agent 会话和管理策略的 Next.js Web 应用。

两个子系统共享 ~/.failproofai/ 和项目 .failproofai/ 目录中的配置文件，但它们以独立进程运行，仅通过文件系统进行通信。

钩子处理器

与 Claude Code 的集成

运行 failproofai policies --install 后，它会将如下条目写入 ~/.claude/settings.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "failproofai --hook PreToolUse"
          }
        ]
      }
    ],
    "PostToolUse": [ ... ]
  }
}

Claude Code 随后会在每次工具调用前将 failproofai --hook PreToolUse 作为子进程调用，并通过 stdin 传递 JSON 载荷。

载荷格式

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
  "cwd": "/home/user/myproject",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "sudo apt install nodejs" }
}

对于 PostToolUse 事件，载荷还会包含 tool_result 字段，其中包含工具的输出内容。处理器对 stdin 强制执行 1 MB 的限制。超出此限制的载荷将被丢弃，所有策略隐式允许通过。

响应格式

拒绝（PreToolUse）：

{
  "hookSpecificOutput": {
    "permissionDecision": "deny",
    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
  }
}

拒绝（PostToolUse）：

{
  "hookSpecificOutput": {
    "additionalContext": "Blocked by failproofai because: API key detected in output"
  }
}

指令（除 Stop 外的任何事件）：

{
  "hookSpecificOutput": {
    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
  }
}

Stop 事件的指令：

退出码：2
原因写入 stderr（而非 stdout）

允许：

退出码：0
stdout 为空

带消息的允许： allow(message) 允许策略在操作被允许时向 Claude 回传信息性上下文。钩子处理器将以下 JSON 写入 stdout（这不是配置文件——这是处理器向 Claude Code 的响应，与 deny 和 instruct 响应方式相同）：

// 由钩子处理器进程写入 stdout
{
  "hookSpecificOutput": {
    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
  }
}

退出码：0（操作被允许）
当多个策略返回带消息的 allow 时，消息将以换行符拼接为单个 additionalContext 字符串
若没有策略提供消息，stdout 为空（与之前相同）

处理流水线

src/hooks/handler.ts 实现了完整的处理流水线：

stdin JSON
  → 解析载荷（最大 1 MB）
  → 提取会话元数据（session_id、cwd、tool_name、tool_input 等）
  → readMergedHooksConfig(cwd)    ← 合并项目 + 本地 + 全局配置
  → 注册已启用的内置策略并解析参数
  → 从 customPoliciesPath 加载自定义策略（如已设置）
  → 将自定义策略注册到策略注册表
  → 评估所有策略（先评估内置策略，再评估自定义策略）
      → 首个 deny 立即短路退出
      → instruct 决策持续累积
      → allow 消息持续累积
  → 将 JSON 决策写入 stdout
  → 将事件持久化到 ~/.failproofai/hook-activity.jsonl
  → 退出

对于典型载荷，整个过程在 100ms 内完成，无需调用任何 LLM。

配置加载

src/hooks/hooks-config.ts 实现了三层配置加载。

[1] {cwd}/.failproofai/policies-config.json        ← 项目级（最高优先级）
[2] {cwd}/.failproofai/policies-config.local.json  ← 本地级
[3] ~/.failproofai/policies-config.json             ← 全局级（最低优先级）

合并逻辑：

enabledPolicies - 对三个文件的并集去重
policyParams - 按策略键名，第一个定义该键的文件完全优先
customPoliciesPath - 第一个定义该值的文件优先
llm - 第一个定义该值的文件优先

Web 控制台使用 readHooksConfig()（仅全局配置）进行读写，因为它不以项目 cwd 调用。

策略评估

src/hooks/policy-evaluator.ts 按顺序依次运行策略。对于每条策略：

查找策略的 params 模式（如有）。
从合并配置中读取 policyParams[policy.name]。
将用户提供的值覆盖到模式默认值之上，生成 ctx.params。
以解析后的上下文调用 policy.fn(ctx)。
若结果为 deny，立即停止并返回该决策。
若结果为 instruct，累积消息并继续。
若结果为 allow，继续到下一条策略。

所有策略运行完毕后：

若有任何 deny 返回，输出 deny 响应。
若收集到任何 instruct 返回，输出单个 instruct 响应，所有消息拼接在一起。
否则，输出 allow 响应（stdout 为空，退出码 0）。

内置策略

src/hooks/builtin-policies.ts 将全部 39 条内置策略定义为 BuiltinPolicyDefinition 对象：

interface BuiltinPolicyDefinition {
  name: string;
  description: string;
  fn: (ctx: PolicyContext) => PolicyResult;
  match: {
    events: HookEventType[];
    tools?: string[];
  };
  defaultEnabled: boolean;
  category: string;
  beta?: boolean;
  params?: PolicyParamsSchema;
}

接受 params 的策略会声明一个 PolicyParamsSchema，其中包含每个参数的类型和默认值。策略评估器在调用 fn 之前将解析后的值注入 ctx.params。策略函数读取 ctx.params 时无需空值保护，因为默认值始终优先应用。策略内部的模式匹配使用解析后的命令 token（argv），而非原始字符串匹配。这可以防止通过 Shell 操作符注入绕过（例如，针对 sudo systemctl status * 的模式不会因在命令后追加 ; rm -rf / 而被绕过）。

自定义策略

src/hooks/custom-hooks-registry.ts 实现了一个基于 globalThis 的注册表：

const REGISTRY_KEY = "__failproofai_custom_hooks__";

export const customPolicies = {
  add(hook: CustomHook): void { ... }
};

export function getCustomHooks(): CustomHook[] { ... }
export function clearCustomHooks(): void { ... }  // 用于测试

src/hooks/custom-hooks-loader.ts 加载用户的策略文件：

从配置中读取 customPoliciesPath；若不存在则跳过。
解析为绝对路径；检查文件是否存在。
将所有 from "failproofai" 的导入重写为实际的 dist 路径，使 customPolicies 解析到同一个 globalThis 注册表。
递归重写传递性本地导入以确保 ESM 兼容性。
写入临时 .mjs 文件并 import() 入口文件。
调用 getCustomHooks() 获取已注册的钩子。
在 finally 块中清理所有临时文件。

发生任何错误（文件未找到、语法错误、导入失败）时，错误将记录到 ~/.failproofai/hook.log，加载器返回空数组。内置策略不受影响。自定义策略在所有内置策略之后评估。自定义策略的 deny 仍会短路后续自定义策略（但所有内置策略此时已完成评估）。

活动日志

每次钩子事件后，处理器会向 ~/.failproofai/hook-activity.jsonl 追加一行 JSONL：

{
  "timestamp": "2026-04-06T12:34:56.789Z",
  "sessionId": "abc123",
  "eventType": "PreToolUse",
  "toolName": "Bash",
  "policyName": "block-sudo",
  "decision": "deny",
  "reason": "sudo command blocked by failproofai",
  "durationMs": 12
}

每条记录对应一条做出非 allow 决策的策略。Allow 决策不记录日志（以保持文件精简）。

控制台架构

控制台是一个 Next.js 16 应用，使用 App Router，结合 React Server Components 和 Server Actions。

app/
  layout.tsx                  ← 根布局（主题、遥测、导航）
  projects/page.tsx           ← Server 组件：列出所有 Claude 项目
  project/[name]/page.tsx     ← Server 组件：列出项目中的会话
  project/[name]/session/
    [sessionId]/page.tsx      ← Server 组件：渲染会话查看器
  policies/page.tsx           ← Client 组件：策略管理 + 活动日志
  actions/
    get-hooks-config.ts       ← 读取配置 + 策略列表
    update-hooks-config.ts    ← 切换策略开关
    update-policy-params.ts   ← 更新策略参数
    get-hook-activity.ts      ← 分页/搜索活动日志
    install-hooks-web.ts      ← 从浏览器安装/移除钩子
  api/
    download/[project]/[session]/route.ts   ← 按 CLI 会话导出（JSONL 或 JSON）

数据流：

页面组件调用 lib/projects.ts 和 lib/log-entries.ts 直接从文件系统读取项目/会话数据（读取操作无 API 层）。
策略页面使用 Server Actions 处理所有变更操作（切换、参数更新、安装/移除）。
会话查看器解析 Claude 的 JSONL 转录格式，并渲染消息和工具调用的时间线。

关键设计决策：

无数据库——所有持久化状态存储在纯文本文件中（~/.failproofai/、~/.claude/projects/）。
变更操作使用 Server Actions——无需为 CRUD 操作构建 REST API。
读取页面使用 React Server Components——更快的首屏加载，无需客户端数据获取 bundle。
仅在需要交互性时使用 Client 组件（策略切换、活动搜索、日志查看器）。

文件结构

failproofai/
├── bin/
│   └── failproofai.mjs           # CLI 路由（hook / dashboard / install 等）
├── src/hooks/
│   ├── handler.ts                # 钩子事件流水线
│   ├── builtin-policies.ts       # 39 条策略定义
│   ├── policy-evaluator.ts       # 策略执行引擎
│   ├── policy-registry.ts        # 策略注册与查找
│   ├── policy-types.ts           # TypeScript 接口定义
│   ├── hooks-config.ts           # 多层配置加载
│   ├── custom-hooks-registry.ts  # 基于 globalThis 的钩子注册表
│   ├── custom-hooks-loader.ts    # 用户 JS 钩子的 ESM 加载器
│   ├── manager.ts                # 安装/移除/列出操作
│   ├── install-prompt.ts         # 交互式策略选择提示
│   ├── hook-logger.ts            # 记录日志到 hook.log
│   ├── hook-activity-store.ts    # 将活动持久化到 hook-activity.jsonl
│   └── llm-client.ts             # LLM API 客户端（用于 AI 驱动的策略）
├── app/                          # Next.js 控制台（页面 + Server Actions）
├── lib/                          # 共享工具函数
│   ├── projects.ts               # 从文件系统枚举 Claude 项目
│   ├── log-entries.ts            # 解析 Claude 转录 JSONL 格式
│   ├── paths.ts                  # 解析系统路径
│   └── ...
├── components/                   # 共享 React UI 组件
├── contexts/                     # React context 提供者（主题、自动刷新、遥测）
├── examples/                     # 自定义钩子示例文件
└── __tests__/                    # 单元测试与端到端测试

快速开始

核心概念

CLI

工具

进阶

架构

概述

钩子处理器

与 Claude Code 的集成

载荷格式

响应格式

处理流水线

配置加载

策略评估

内置策略

自定义策略

活动日志

控制台架构

文件结构

​概述

​钩子处理器

​与 Claude Code 的集成

​载荷格式

​响应格式

​处理流水线

​配置加载

​策略评估

​内置策略

​自定义策略

​活动日志

​控制台架构

​文件结构

概述

钩子处理器

与 Claude Code 的集成

载荷格式

响应格式

处理流水线

配置加载

策略评估

内置策略

自定义策略

活动日志

控制台架构

文件结构