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

Chính sách tùy chỉnh chuyển đổi một mẫu 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 các tools, đường dẫn, lệnh, môi trường hoặc quy tắc hoạt động của bạn. Kiểm tra gói chính sách Failproof AI trước để bạn không tạo lại một điều khiển hiện có.

Soạn thả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 mà 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 chỉnh sửa. 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.
Đi đến Admin → enforcement, triển khai phiên bản sang một máy kiểm tra trong chế độ observe, và xác minh các quyết định của nó dưới Observe → policy trước khi áp dụng nó.

Tạo .failproofai/policies/checkout-policies.ts. Tên file 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 file 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 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á hoại chỉ khi lệnh nhắm mục tiêu sản xuất. Mọi thứ bên 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 với hành động có thể quan sát được — không phải ý định mà 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

Helper	Kết quả	Sử dụng nó 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ợ.	Bạn muốn hướng dẫn agent hướng tới một cách tiếp cận tốt hơn mà không áp dụng 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 tiếp tục.

Viết lý do cho agent phải phục hồi. 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 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ữ các tên duy nhất trên các file.
`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á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 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 được chuẩn hóa hiện đang được đánh giá.
`toolName`	`string \| undefined`	Tên tool 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 tool hiện tại.
`payload`	`Record<string, unknown>`	Toàn bộ tải trọng sự kiện được chuẩn hóa.
`session`	`SessionMetadata \| undefined`	ID phiên, thư mục làm việc, đường dẫn phiên ghi âm, chế độ quyền hạn, và siêu dữ liệu harness khi có sẵn.
`cli`	`string \| undefined`	Harness agent nguồ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. Các chính sách tùy chỉnh hiện tại nhận một đối tượng rỗ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 tool phổ biến

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

Tool	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 việc chuyển đổi phòng thủ vì các giá trị đầu vào tool đượ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 tool thực thi.	Chặn hoặc hướng dẫn các lệnh, ghi, đọc, và hành động bên ngoài.
`PostToolUse`	Sau khi một tool trả về.	Kiểm tra các kết quả trước khi chúng tiếp cận agent. Một deny chặn toàn bộ kết quả; nó không loại bỏ các trường được chọn.
`PermissionRequest`	Khi agent yêu cầu quyền hạn.	Áp dụng các quy tắc quyền hạn cụ thể của 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 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ể đạt được, như một bước xác minh cục bộ.
`SubagentStop`	Khi một subagent cố gắng kết thúc.	Chặn công việc được ủy thác trước khi nó trả về cho cha mẹ.
`SessionStart` / `SessionEnd`	Tại các ranh giới phiên.	Ghi nhận 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 hạm đội hỗn hợp.

Tất cả cá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.

Soạn thảo các mẫu chính sách phổ biến

Chặn ghi vào đườ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.");
  },
});

Chặn 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ể khiến agent thử lại. Chỉ chặn 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 gọi con quy trình hoặc mạng.

Tải các file chính sách

File quy ước

Các file 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 file tải theo thứ tự bảng chữ cái trong mỗi thư mục.
Một file 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 file được hỗ trợ.
Các nhập 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ùng các quy tắc theo kho lưu trữ.

File tường minh

Sử dụng các đường dẫn tường minh khi xác thực hoặc cấu hình phải đặt tên file đầu vào trực tiếp:

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

Các file tường minh tải trước tiên, theo sau là các file quy ước của dự án và sau đó là các file quy ước của người dùng. Một file đượ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 file bị thiếu, lỗi cú pháp, nhập không được giải quyết, 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 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 tool bị thiếu hoặc sai đị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 phụ thuộc con quy trình hoặ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 dưới 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.
Cái deny đầu tiên dừng đánh giá chính sách tiếp theo.
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 là được ghi nhận và được coi là allow().
Một file quy ước không tải được bị bỏ qua; các file 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 nhận quyết định không phải là allow mà không áp dụng nó.

Giữ các mô-đun chính sách xác định và nhanh. Tránh các lệnh gọi mạng cấp cao nhất hoặc khởi động máy chủ. Giới hạn công việc bên trong fn, bắt các lỗi phụ thuộc, và chọn có chủ ý xem liệu lỗi đó có 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ý một 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 đ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ó trong chế độ quan sát, xác minh các quyết định, và chuyển sang thực thi.

Connect your agents

Reference

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

Soạn thả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 tool phổ biến

Chọn sự kiện

Soạn thảo các mẫu chính sách phổ biến

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

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

Chặn hoàn thành phiên

Tải các file chính sách

File quy ước

File tường minh

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

​Soạn thả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 tool phổ biến

​Chọn sự kiện

​Soạn thảo các mẫu chính sách phổ biến

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

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

​Chặn hoàn thành phiên

​Tải các file chính sách

​File quy ước

​File tường minh

​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

Soạn thả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 tool phổ biến

Chọn sự kiện

Soạn thảo các mẫu chính sách phổ biến

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

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

Chặn hoàn thành phiên

Tải các file chính sách

File quy ước

File tường minh

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

Hành vi thời gian chạy

Xuất API