Chính sách tùy chỉnh

Chính sách tùy chỉnh chuyển đổi mô hình lỗi từ traces hoặc audits của bạn thành một quyết định chạy trong khi agent hoạt động. Một chính sách có thể cho phép một hành động, cung cấp hướng dẫn cho agent, hoặc từ chối hành động trước khi nó gây ra một sự cố khác. Sử dụng chính sách tùy chỉnh khi hành vi phụ thuộc vào tools, đường dẫn, lệnh, môi trường hoặc quy tắc vận hành của bạn. Kiểm tra danh mục chính sách tích hợp sẵn trước để tránh tái tạo một điều khiển hiện có.

Tạo chính sách tùy chỉnh

Dashboard
CLI

Đi đến Admin → policy editor, chọn New policy, và mô tả lỗi bạn muốn ngăn chặn.
Thêm mã nguồn chính sách, sau đó kiểm tra các kết quả khớp dự kiến và các kết quả không khớp an toàn trong trình editor. Giải quyết mọi lỗi xác thực.
Lưu bản nháp và chọn Publish version để tạo một phiên bản không thay đổi.
Đi đến Admin → enforcement, triển khai phiên bản tới một máy test trong chế độ observe, và xác minh các quyết định của nó trong Observe → policy trước khi thực thi.

Tạo .failproofai/policies/checkout-policies.ts. Tên tệp phải kết thúc bằng policies.js, policies.mjs, hoặc policies.ts.
Đăng ký một hoặc nhiều chính sách với customPolicies.add().
Xác thực và cài đặt tệp với failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project.
Kích hoạt một hành động khớp và một hành động an toàn. Chạy failproofai policies, sau đó kiểm tra các quyết định được ghi nhận trong Observe → policy.

Bắt đầu với một quy tắc hẹp

Chính sách này chặn các lệnh Kubernetes phá hoại chỉ khi lệnh nhắm mục tiêu sản xuất. Mọi thứ ngoài chế độ lỗi chính xác đó trả về 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.",
    );
  },
});

Những chính sách tốt đủ hẹp để giải thích trong một câu. Khớp hành động quan sát được—không phải ý định bạn hy vọng agent có—và trả về allow() ngay khi quy tắc không áp dụng.

Chọn một quyết định

Trợ giúp	Kết quả	Sử dụng khi
`allow(reason?)`	Hành động tiếp tục.	Chính sách không áp dụng hoặc hành động là an toàn.
`instruct(reason)`	Hành động tiếp tục với hướng dẫn nơi harness hỗ trợ nó.	Bạn muốn hướng dẫn agent đến một cách tiếp cận tốt hơn mà không thực thi một bất biến.
`deny(reason)`	Hành động bị chặn khi sự kiện và harness hỗ trợ chặn.	Hành động không được tiếp tục.

Viết lý do cho agent phải khôi phục. Giải thích những gì được phát hiện và nó nên làm gì thay vào đó.

Không sử dụng instruct() cho ranh giới an toàn. Việc phân phát hướng dẫn khác nhau tùy theo agent harness. Sử dụng deny() khi hành động phải được ngăn chặn.

Đối tượng chính sách

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

Trường	Bắt buộc	Mô tả
`name`	Có	Định danh ổn định cho chính sách. Giữ các tên duy nhất trên các tệp.
`description`	Không	Mục đích dễ đọc được hiển thị trong danh sách chính sách và quyết định.
`match.events`	Không	Các loại sự kiện gọi chính sách. Bỏ qua `match` gọi nó cho mọi sự kiện có sẵn.
`fn`	Có	Hàm đồng bộ hoặc không đồng bộ trả về kết quả `allow`, `instruct`, hoặc `deny`.

Lọc tools bên trong fn. match.toolNames không phải là một phần của loại chính sách tùy chỉnh công cộng.

Ngữ cảnh chính sách

Mỗi chính sách nhận một PolicyContext.

Trường	Loại	Nó chứa
`eventType`	`HookEventType`	Sự kiện bình thường hóa hiện đang được đánh giá.
`toolName`	`string \| undefined`	Tên công cụ chính tắc như `Bash`, `Read`, `Write`, hoặc `Edit`.
`toolInput`	`Record<string, unknown> \| undefined`	Đầu vào chính tắc cho lệnh gọi công cụ hiện tại.
`payload`	`Record<string, unknown>`	Tải trọng sự kiện bình thường hóa hoàn chỉnh.
`session`	`SessionMetadata \| undefined`	ID phiên, thư mục làm việc, đường dẫn bản ghi, chế độ quyền hạn và siêu dữ liệu harness khi có sẵn.
`cli`	`string \| undefined`	Harness agent nguồn, chẳng hạn như `claude`, `codex`, hoặc `cursor`.
`params`	`Record<string, unknown>`	Các tham số chính sách tích hợp sẵn. Chính sách tùy chỉnh hiện nhận một đối tượng trống.

Coi mọi giá trị tùy chọn là thực sự tùy chọn. Các phiên bản agent và loại sự kiện không cung cấp các trường giống nhau.

Đầu vào công cụ phổ biến

Failproof AI bình thường hóa các công cụ phổ biến trên các harness được hỗ trợ để một chính sách thường có thể sử dụng một hình dạng đầu vào.

Công cụ	Trường thông thường
`Bash`	`command`
`Read`	`file_path`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Grep`	`pattern`, `path`

Sử dụng ép kiểu phòng chống vì các giá trị đầu vào công cụ được nhập là unknown:

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

Chọn sự kiện

Sự kiện	Khi nó chạy	Sử dụng điển hình
`PreToolUse`	Trước khi một công cụ thực thi.	Chặn hoặc hướng dẫn lệnh, ghi, đọc và hành động bên ngoài.
`PostToolUse`	Sau khi một công cụ trả về.	Kiểm tra kết quả trước khi chúng đến agent. Một deny chặn toàn bộ kết quả; nó không làm biến mất các trường được chọn.
`PermissionRequest`	Khi agent yêu cầu quyền.	Áp dụng các quy tắc quyền đặc trưng cho tổ chức.
`UserPromptSubmit`	Trước khi một lời nhắc được gửi tiếp tục.	Từ chối các hướng dẫn bị cấm hoặc thêm hướng dẫn quy trình.
`Stop`	Khi agent cố gắng kết thúc.	Yêu cầu một điều kiện hoàn thành có thể đạt được, chẳng hạn như một bước xác minh cục bộ.
`SubagentStop`	Khi một subagent cố gắng kết thúc.	Ghi lại công việc được ủy quyền trước khi nó quay lại cha mẹ.
`SessionStart` / `SessionEnd`	Tại các ranh giới phiên.	Ghi hoặc kiểm tra trạng thái cấp phiên.

Tính khả dụng sự kiện và hành vi chặn phụ thuộc vào agent harness. Xem Agent harnesses trước khi dựa vào một sự kiện trên một hạm đội hỗn hợp.

Tất cả tên sự kiện chính sách

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, và Setup.

Tạo các mô hình chính sách phổ biến

Chặn ghi vào các đường dẫn được bảo vệ

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.");
  },
});

Cung cấp hướng dẫn không chặn

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.");
  },
});

Ghi lại hoàn thành phiên

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.");
    }
  },
});

Một sự kiện Stop bị từ chối có thể làm cho agent thử lại. Chỉ ghi lại một điều kiện mà agent có thể thỏa mãn trong môi trường hiện tại, và ràng buộc mọi lệnh gọi tiến trình con hoặc mạng.

Tải tệp chính sách

Tệp quy ước

Tệp quy ước tải tự động:

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

Cả thư mục chính sách dự án và người dùng đều được tải.
Các tệp tải theo thứ tự bảng chữ cái trong mỗi thư mục.
Một tệp phải kết thúc bằng policies.js, policies.mjs, hoặc policies.ts.
Nhiều lệnh gọi customPolicies.add() trong một tệp được hỗ trợ.
Nhập tương đối từ các mô-đun cục bộ được hỗ trợ.
Chính sách dự án có thể được cam kết để các quy tắc tương tự theo kho lưu trữ.

Tệp rõ ràng

Sử dụng các đường dẫn rõ ràng khi xác thực hoặc cấu hình nên đặt tên tệp nhập trực tiếp:

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

Các tệp rõ ràng tải trước, theo sau là các tệp quy ước dự án và sau đó là các tệp quy ước người dùng. Một tệp được phát hiện thông qua cả hai đường dẫn được tải một lần.

Xác thực và kiểm tra

Xác thực thực thi mô-đun thông qua trình tải sản xuất và xác nhận rằng nó đăng ký ít nhất một chính sách.

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

Xác thực bắt các tệp bị thiếu, lỗi cú pháp, nhập chưa được giải quyết, các ngoại lệ cấp cao nhất và hết thời gian tải mô-đun. Nó không chứng minh rằng logic khớp của bạn là chính xác. Kiểm tra ít nhất các trường hợp này:

Một hành động phải khớp và tạo lý do chính sách dự kiến.
Một hành động gần nhưng an toàn phải trả về allow().
Trường công cụ bị thiếu hoặc không đúng định dạng.
Cú pháp lệnh thay thế, đường dẫn, trích dẫn, casing và khoảng trắng.
Một tiến trình con hoặc phụ thuộc mạng không có sẵn.

Ghi nhận kết quả cho chính sách tùy chỉnh của bạn trong Observe → policy. Một bài kiểm tra bị chặn không đủ nếu một chính sách tích hợp sẵn khác đã đưa ra quyết định.

Hành vi thời gian chạy

Các chính sách tích hợp sẵn đánh giá trước các chính sách tùy chỉnh.
Deny đầu tiên dừng đánh giá chính sách thêm.
Nhiều kết quả instruct có thể được kết hợp khi không có chính sách nào từ chối sự kiện.
Một hàm chính sách có thời hạn thực thi 10 giây.
Một ngoại lệ bị ném hoặc hết thời gian được ghi nhật ký và được coi là allow().
Một tệp quy ước không tải được bỏ qua; các tệp tùy chỉnh khác và chính sách tích hợp sẵn tiếp tục.
Tải mô-đun cấp cao nhất cũng có thời hạn 10 giây.
Chế độ quan sát đám mây chạy chính sách nhưng ghi lại quyết định không cho phép mà không thực thi nó.

Giữ các mô-đun chính sách xác định và nhanh chóng. Tránh các lệnh gọi mạng cấp cao nhất hoặc khởi động máy chủ. Ràng buộc công việc bên trong fn, bắt các lỗi phụ thuộc và chọn cách cố ý liệu lỗi đó nên cho phép hay từ chối hành động.

Xuất API

Xuất	Mục đích
`customPolicies.add(policy)`	Đăng ký một chính sách tùy chỉnh khi mô-đun tải.
`allow(reason?)`	Cho phép hành động.
`instruct(reason)`	Cho phép hành động và cung cấp hướng dẫn nơi được hỗ trợ.
`deny(reason)`	Chặn hành động nơi được hỗ trợ.
`getCustomHooks()`	Trả về các chính sách hiện đang được đăng ký trong sổ đăng ký mô-đun.
`clearCustomHooks()`	Xóa sổ đăng ký đó, chủ yếu cho các bài kiểm tra và trình tải.

TypeScript xuất PolicyContext, PolicyResult, CustomHook, PolicyDecision, và PolicyFunction.

Triển khai chính sách tùy chỉnh

Xuất bản một phiên bản, triển khai nó ở chế độ quan sát, xác minh quyết định và chuyển sang thực thi.

Connect your agents

Reference

HTTP API

Chính sách tùy chỉnh

Tạo chính sách tùy chỉnh

Bắt đầu với một quy tắc hẹp

Chọn một quyết định

Đối tượng chính sách

Ngữ cảnh chính sách

Đầu vào công cụ phổ biến

Chọn sự kiện

Tạo các mô hình chính sách phổ biến

Chặn ghi vào các đường dẫn được bảo vệ

Cung cấp hướng dẫn không chặn

Ghi lại hoàn thành phiên

Tải tệp chính sách

Tệp quy ước

Tệp rõ ràng

Xác thực và kiểm tra

Hành vi thời gian chạy

Xuất API

Triển khai chính sách tùy chỉnh

​Tạo chính sách tùy chỉnh

​Bắt đầu với một quy tắc hẹp

​Chọn một quyết định

​Đối tượng chính sách

​Ngữ cảnh chính sách

​Đầu vào công cụ phổ biến

​Chọn sự kiện

​Tạo các mô hình chính sách phổ biến

​Chặn ghi vào các đường dẫn được bảo vệ

​Cung cấp hướng dẫn không chặn

​Ghi lại hoàn thành phiên

​Tải tệp chính sách

​Tệp quy ước

​Tệp rõ ràng

​Xác thực và kiểm tra

​Hành vi thời gian chạy

​Xuất API

Triển khai chính sách tùy chỉnh

Tạo chính sách tùy chỉnh

Bắt đầu với một quy tắc hẹp

Chọn một quyết định

Đối tượng chính sách

Ngữ cảnh chính sách

Đầu vào công cụ phổ biến

Chọn sự kiện

Tạo các mô hình chính sách phổ biến

Chặn ghi vào các đường dẫn được bảo vệ

Cung cấp hướng dẫn không chặn

Ghi lại hoàn thành phiên

Tải tệp chính sách

Tệp quy ước

Tệp rõ ràng

Xác thực và kiểm tra

Hành vi thời gian chạy

Xuất API