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

Chính sách tùy chỉnh chuyển một mô hình lỗi từ các trace hoặc audit 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 các công cụ, đường dẫn, lệnh, môi trường hoặc quy tắc hoạt động của bạn. Hãy kiểm tra danh mục chính sách tích hợp 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

Chuyển đế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 mong đợi và các kết quả không khớp an toàn trong trình soạn thảo. 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 bất biến.
Chuyển đến Admin → enforcement, triển khai phiên bản tới một máy thử nghiệm ở chế độ observe và xác minh các quyết định của nó dưới 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 bằng 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 quy cho dưới 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á hủy chỉ khi lệnh nhắm vào production. 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.",
    );
  },
});

Các 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?)`	Hoạt độ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)`	Hoạt độ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)`	Hoạt động bị chặn khi sự kiện và harness hỗ trợ chặn.	Hành động không được phép 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 thế.

Không sử dụng instruct() cho ranh giới an toàn. Việc cung cấp hướng dẫn khác nhau tùy theo harness agent. 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ữ tên duy nhất trong các tệp.
`description`	Không	Mục đích có thể đọc được của con người đượ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 công cụ 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 khai.

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 gì
`eventType`	`HookEventType`	Sự kiện chuẩn hóa hiện đang được đánh giá.
`toolName`	`string \| undefined`	Tên công cụ chính thức như `Bash`, `Read`, `Write` hoặc `Edit`.
`toolInput`	`Record<string, unknown> \| undefined`	Đầu vào chính thức cho lệnh gọi công cụ hiện tại.
`payload`	`Record<string, unknown>`	Tải trọng sự kiện chuẩn hóa hoàn chỉnh.
`session`	`SessionMetadata \| undefined`	ID phiên, thư mục làm việc, đường dẫn transcript, chế độ quyề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. Các chính sách tùy chỉnh hiện tại 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à các 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 chuẩn 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ụ	Các trường phổ biến
`Bash`	`command`
`Read`	`file_path`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Grep`	`pattern`, `path`

Sử dụng chuyển đổi phòng thủ vì các giá trị đầu vào công cụ được gõ 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 mất công dụng 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ụ thể của tổ chức.
`UserPromptSubmit`	Trước khi một prompt đượ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 làm việc.
`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ể truy cập đượ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 công việc được ủy quyền trước khi nó trở lại parent.
`SessionStart` / `SessionEnd`	Tại 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 harness agent. Xem Agent harnesses trước khi dựa vào một sự kiện trên một lực lượng 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 công việc 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 công việc trên một điều kiện mà agent có thể thỏa mãn trong môi trường hiện tại và giới hạn mọi lệnh con hoặc cuộc gọi 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 của 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ợ.
Các nhập khẩu tương đối từ các mô-đun cục bộ được hỗ trợ.
Các chính sách của dự án có thể được cam kết để các quy tắc tương tự theo dõi kho lưu trữ.

Tệp rõ ràng

Sử dụng đườ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 tiên, theo sau là tệp quy ước dự án và sau đó là 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 hiện 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 khẩu chưa giải quyết, ngoại lệ cấp cao nhất và thời gian chờ 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 ra lý do chính sách dự định.
Một hành động gần đó nhưng an toàn phải trả về allow().
Các trường công cụ bị thiếu hoặc định dạng không đúng.
Cú pháp lệnh thay thế, đường dẫn, dấu ngoặc, casing và khoảng trắng.
Một quá trình con hoặc phụ thuộc mạng không có sẵn.

Quy cho kết quả cho chính sách tùy chỉnh của bạn dưới Observe → policy. Một bài kiểm tra bị chặn là không đủ nếu một chính sách tích hợp 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 được đánh giá trước các chính sách tùy chỉnh.
Lần 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 hiện 10 giây.
Một ngoại lệ được ném hoặc thời gian chờ được ghi nhật ký và được coi là allow().
Một tệp quy ước không tải được bị bỏ qua; các tệp tùy chỉnh khác và chính sách tích hợp 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 phải là allow 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 cuộc gọi mạng cấp cao nhất hoặc khởi động máy chủ. Công việc ràng buộc bên trong fn, bắt các lỗi phụ thuộc và chọn có chủ ý liệu lỗi đó nên cho phép hay từ chối hoạt động.

Xuất API

Xuất	Mục đích
`customPolicies.add(policy)`	Đăng ký chính sách tùy chỉnh khi mô-đun tải.
`allow(reason?)`	Cho phép hoạt động.
`instruct(reason)`	Cho phép hoạt động và cung cấp hướng dẫn nơi được hỗ trợ.
`deny(reason)`	Chặn hoạt động nơi được hỗ trợ.
`getCustomHooks()`	Trả về các chính sách hiện đượ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 các 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 đến thực thi.

Connect your agents

Reference

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 công việc 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 các 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 công việc 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 các 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 công việc 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