自定义策略

自定义策略能将你在追踪记录或审计中发现的故障模式，转化为 Agent 工作时实时执行的决策。策略可以允许某个操作、向 Agent 提供指导，或在操作引发新的问题之前将其拒绝。当行为取决于你的工具、路径、命令、环境或操作规范时，请使用自定义策略。建议先查阅 Failproof AI 策略包，避免重复创建已有的控制规则。

编写自定义策略

控制台
CLI

前往 Admin → 策略编辑器，选择 新建策略，描述你希望防范的故障场景。
添加策略代码，然后在编辑器中测试预期匹配项和安全的非匹配项，解决所有验证错误。
保存草稿并选择 发布版本 以创建一个不可变版本。
前往 Admin → 执行，以观察模式将该版本部署到测试机器，并在 Observe → policy 下验证其决策，确认无误后再正式执行。

创建 .failproofai/policies/checkout-policies.ts。文件名必须以 policies.js、policies.mjs 或 policies.ts 结尾。
使用 customPolicies.add() 注册一个或多个策略。
使用 failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project 验证并安装文件。
触发一个匹配的操作和一个安全操作。运行 failproofai policies，然后在 Observe → policy 下查看归因决策。

从精确的规则开始

以下策略仅在命令指向生产环境时才会拦截破坏性的 Kubernetes 命令。不属于该故障模式的情况均返回 allow()。

import { customPolicies, allow, deny } from "failproofai";

const DESTRUCTIVE_KUBECTL = /\bkubectl\s+(delete|replace)\b/i;
const PRODUCTION_TARGET = /(?:--context|--namespace|-n)\s+(prod|production)\b/i;

customPolicies.add({
  name: "block-destructive-production-kubectl",
  description: "Block destructive Kubernetes commands against production",
  match: { events: ["PreToolUse"] },
  fn: async ({ toolName, toolInput }) => {
    if (toolName !== "Bash") return allow();

    const command = String(toolInput?.command ?? "");
    if (!DESTRUCTIVE_KUBECTL.test(command)) return allow();
    if (!PRODUCTION_TARGET.test(command)) return allow();

    return deny(
      "Destructive production Kubernetes commands require the approved deployment workflow.",
    );
  },
});

好的策略应该精确到能用一句话说清楚。匹配可观测的操作——而非你期望 Agent 的意图——并在规则不适用时尽早返回 allow()。

选择决策类型

辅助函数	结果	使用场景
`allow(reason?)`	操作继续执行。	策略不适用或操作是安全的。
`instruct(reason)`	操作继续执行，并在支持的运行环境中向 Agent 提供指导。	希望引导 Agent 采取更好的方式，而不强制执行某个不变量。
`deny(reason)`	在事件和运行环境支持拦截的情况下，操作被阻止。	操作不应继续进行。

为需要恢复的 Agent 撰写说明原因。解释检测到了什么，以及应该改为做什么。

不要将 instruct() 用于安全边界。指导的传递方式因 Agent 运行环境而异。当操作必须被阻止时，请使用 deny()。

策略对象

customPolicies.add({
  name: "policy-name",
  description: "What this policy prevents",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => allow(),
});

字段	是否必填	描述
`name`	是	策略的稳定标识符。请确保跨文件的名称唯一。
`description`	否	在策略列表和决策中显示的人类可读用途说明。
`match.events`	否	触发该策略的事件类型。省略 `match` 则对所有可用事件触发。
`fn`	是	同步或异步函数，返回 `allow`、`instruct` 或 `deny` 结果。

请在 fn 内部过滤工具。match.toolNames 不属于公开的自定义策略类型。

策略上下文

每个策略都会接收一个 PolicyContext。

字段	类型	内容说明
`eventType`	`HookEventType`	当前正在评估的标准化事件。
`toolName`	`string \| undefined`	规范工具名称，如 `Bash`、`Read`、`Write` 或 `Edit`。
`toolInput`	`Record<string, unknown> \| undefined`	当前工具调用的规范输入。
`payload`	`Record<string, unknown>`	完整的标准化事件载荷。
`session`	`SessionMetadata \| undefined`	会话 ID、工作目录、记录路径、权限模式以及可用时的运行环境元数据。
`cli`	`string \| undefined`	来源 Agent 运行环境，如 `claude`、`codex` 或 `cursor`。
`params`	`Record<string, unknown>`	内置策略参数。自定义策略当前接收的是空对象。

请将所有可选值视为真正可选。不同的 Agent 版本和事件类型并不一定提供相同的字段。

常用工具输入

Failproof AI 在支持的运行环境中对常用工具进行了标准化处理，因此策略通常可以使用统一的输入结构。

工具	常用字段
`Bash`	`command`
`Read`	`file_path`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Grep`	`pattern`, `path`

由于工具输入值的类型为 unknown，请使用防御性类型转换：

const command = String(ctx.toolInput?.command ?? "");
const filePath = String(ctx.toolInput?.file_path ?? "");

选择事件类型

事件	触发时机	典型用途
`PreToolUse`	工具执行之前。	拦截或引导命令、写入、读取及外部操作。
`PostToolUse`	工具返回之后。	在结果传递给 Agent 之前检查结果。deny 会阻止整个结果，而不是屏蔽特定字段。
`PermissionRequest`	Agent 请求权限时。	应用组织特定的权限规则。
`UserPromptSubmit`	提交的提示词继续执行之前。	拒绝禁止的指令或添加工作流指导。
`Stop`	Agent 尝试结束任务时。	要求满足可达的完成条件，例如本地验证步骤。
`SubagentStop`	子 Agent 尝试结束时。	在委托工作返回父 Agent 之前进行门控。
`SessionStart` / `SessionEnd`	会话边界时。	记录或检查会话级别的状态。

事件可用性和拦截行为取决于 Agent 运行环境。在混合机群中依赖某个事件之前，请参阅 Agent 运行环境。

所有策略事件名称

SessionStart、SessionEnd、UserPromptSubmit、PreToolUse、PermissionRequest、PermissionDenied、PostToolUse、PostToolUseFailure、Notification、SubagentStart、SubagentStop、TaskCreated、TaskCompleted、Stop、StopFailure、TeammateIdle、InstructionsLoaded、ConfigChange、CwdChanged、FileChanged、WorktreeCreate、WorktreeRemove、PreCompact、PostCompact、Elicitation、ElicitationResult、UserPromptExpansion、PostToolBatch 和 Setup。

常见策略模式示例

阻止对受保护路径的写入

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "block-generated-file-edits",
  description: "Require generated files to be changed through their generator",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();

    const filePath = String(ctx.toolInput?.file_path ?? "");
    if (!/(^|\/)(dist|generated)\//.test(filePath)) return allow();

    return deny("Edit the source and run the generator instead of changing generated output.");
  },
});

提供非阻断性指导

import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "prefer-reviewed-deploy-command",
  description: "Guide agents toward the reviewed deployment wrapper",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();

    const command = String(ctx.toolInput?.command ?? "");
    if (!/^kubectl\s+apply\b/.test(command.trim())) return allow();

    return instruct("Use ./scripts/deploy-reviewed instead of invoking kubectl directly.");
  },
});

对会话完成进行门控

import { execFileSync } from "node:child_process";
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "require-clean-typecheck",
  description: "Require the project typecheck to pass before the agent finishes",
  match: { events: ["Stop"] },
  fn: async (ctx) => {
    const cwd = ctx.session?.cwd;
    if (!cwd) return allow();

    try {
      execFileSync("bunx", ["tsc", "--noEmit"], {
        cwd,
        stdio: "ignore",
        timeout: 8_000,
      });
      return allow();
    } catch {
      return deny("Fix the typecheck errors before finishing the task.");
    }
  },
});

被拒绝的 Stop 事件可能导致 Agent 重试。请只对 Agent 在当前环境中能够满足的条件进行门控，并为所有子进程或网络调用设置超时限制。

加载策略文件

约定文件

约定文件会自动加载：

<project>/.failproofai/policies/security-policies.ts
~/.failproofai/policies/personal-policies.mjs

项目和用户策略目录均会被加载。
文件在各目录内按字母顺序加载。
文件名必须以 policies.js、policies.mjs 或 policies.ts 结尾。
一个文件中支持多次调用 customPolicies.add()。
支持从本地模块进行相对导入。
项目策略可以提交到版本库，使相同规则随代码库一同传递。

显式文件

当验证或配置需要直接指定入口文件时，使用显式路径：

failproofai policies --install \
  --custom ./security.policies.ts \
  --custom ./workflow.policies.ts \
  --scope project

显式文件优先加载，其次是项目约定文件，最后是用户约定文件。同一个文件通过两种路径发现时只加载一次。

验证和测试

验证过程会通过生产加载器执行模块，并确认其至少注册了一个策略。

failproofai policies --install \
  --custom ./.failproofai/policies/checkout-policies.ts \
  --scope project
failproofai policies

验证能捕获缺失的文件、语法错误、未解析的导入、顶层异常和模块加载超时。但它无法证明你的匹配逻辑是否正确。至少测试以下场景：

一个必须匹配并产生预期策略原因的操作。
一个临近但安全、必须返回 allow() 的操作。
缺失或格式错误的工具字段。
不同的命令语法、路径、引号、大小写和空白字符。
子进程或网络依赖不可用的情况。

在 Observe → policy 下将结果归因于你的自定义策略。如果决策是由其他内置策略做出的，则被拦截的测试不能算作有效验证。

运行时行为

内置策略在自定义策略之前评估。
第一个 deny 会停止后续的策略评估。
当没有策略拒绝事件时，多个 instruct 结果可以合并。
策略函数有 10 秒的执行时限。
抛出的异常或超时会被记录日志并视为 allow()。
加载失败的约定文件会被跳过；其他自定义文件和内置策略继续执行。
顶层模块加载同样有 10 秒的时限。
云端观察模式会运行策略，但会记录非 allow 决策而不实际执行拦截。

保持策略模块的确定性和高效性。避免顶层网络调用或服务启动。在 fn 内限制工作量、捕获依赖故障，并有意识地决定故障时应 allow 还是 deny 操作。

API 导出

导出	用途
`customPolicies.add(policy)`	在模块加载时注册一个自定义策略。
`allow(reason?)`	允许该操作。
`instruct(reason)`	允许操作并在支持的环境中提供指导。
`deny(reason)`	在支持的环境中阻止该操作。
`getCustomHooks()`	返回当前在模块注册表中注册的策略。
`clearCustomHooks()`	清除该注册表，主要用于测试和加载器。

TypeScript 导出 PolicyContext、PolicyResult、CustomHook、PolicyDecision 和 PolicyFunction。

部署自定义策略

发布版本、以观察模式部署、验证决策，然后切换到强制执行模式。

Connect your agents

Reference

编写自定义策略

从精确的规则开始

选择决策类型

策略对象

策略上下文

常用工具输入

选择事件类型

常见策略模式示例

阻止对受保护路径的写入

提供非阻断性指导

对会话完成进行门控

加载策略文件

约定文件

显式文件

验证和测试

运行时行为

API 导出

部署自定义策略

​编写自定义策略

​从精确的规则开始

​选择决策类型

​策略对象

​策略上下文

​常用工具输入

​选择事件类型

​常见策略模式示例

​阻止对受保护路径的写入

​提供非阻断性指导

​对会话完成进行门控

​加载策略文件

​约定文件

​显式文件

​验证和测试

​运行时行为

​API 导出

部署自定义策略

编写自定义策略

从精确的规则开始

选择决策类型

策略对象

策略上下文

常用工具输入

选择事件类型

常见策略模式示例

阻止对受保护路径的写入

提供非阻断性指导

对会话完成进行门控

加载策略文件

约定文件

显式文件

验证和测试

运行时行为

API 导出