系统要求
- Node.js >= 20.9.0
- Bun >= 1.3.0（可选，仅在从源码构建时需要）
npm install -g failproofai
快速上手
启用策略
策略是在每次智能体工具调用前后执行的规则。它们能在破坏性命令、密钥泄露及其他故障发生之前将其拦截。failproofai policies --install
~/.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 生成的插件 shim 以及 ~/.config/opencode/opencode.json 的 plugin 数组中的注册条目、Pi 的 ~/.pi/agent/settings.json，或 Gemini CLI 的 ~/.gemini/settings.json）。如果检测到多个已安装的 CLI，系统会提示你选择；也可以通过 --cli claude codex copilot cursor opencode pi gemini（任意子集）跳过提示。GitHub Copilot CLI、Cursor Agent、OpenCode、Pi 和 Gemini CLI 的支持目前处于 测试阶段 — 分别使用 --cli copilot、--cli cursor、--cli opencode、--cli pi 或 --cli gemini 进行安装。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 gemini --scope project
failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
启动控制台
在 http://localhost:8020 打开本地控制台，你可以在此浏览会话记录、查看工具调用详情并管理策略。 运行智能体
像往常一样启动 Claude Code。如果智能体尝试执行危险操作，failproofai 会自动拦截。你可以让它在无人值守的情况下运行，事后在控制台中查看发生了什么。
策略的工作原理
每次智能体执行工具时，Claude Code 会将 failproofai 作为子进程调用：
Claude Code → failproofai --hook PreToolUse → reads stdin JSON
evaluates policies
writes decision to stdout
- allow — 智能体正常继续执行
- deny — 操作被阻止，智能体会收到阻止原因说明
- instruct — 在智能体的提示中追加额外上下文
策略在本地进程中运行，不会向远程服务发送任何数据。
使用约定式策略建立团队规范
在团队中快速建立质量标准的最便捷方式是使用 .failproofai/policies/ 约定目录。只需将策略文件放入该目录，它们就会自动加载——无需任何标志、配置变更或安装命令。
创建策略目录
mkdir -p .failproofai/policies
添加策略文件
复制示例文件或自行编写：cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
// .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();
},
});
提交到 Git
git add .failproofai/policies/
git commit -m "Add team quality policies"
将 .failproofai/policies/ 提交到代码仓库，让整个团队共享相同的标准。随着团队发现新的故障模式，只需添加策略并推送——所有人在下次 git pull 时即可获得更新。随着时间推移，这些策略将成为持续演进的质量标准。
数据存储
所有配置和日志均保存在本地机器上：
| 路径 | 存储内容 |
|---|
~/.failproofai/policies-config.json | 全局策略配置 |
~/.failproofai/hook-activity.jsonl | Hook 执行历史 |
~/.failproofai/hook.log | 自定义 hook 错误的调试日志 |
.failproofai/policies-config.json | 项目级配置（可提交到仓库） |
.failproofai/policies-config.local.json | 个人覆盖配置（已加入 gitignore） |
failproofai policies --uninstall
~/.claude/settings.json 中移除 hook 条目。~/.failproofai/ 中的配置文件将被保留。
后续步骤
自定义策略
使用 JavaScript 编写自己的策略
