> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # Chính sách tùy chỉnh > Tạo, kiểm tra và triển khai chính sách JavaScript hoặc TypeScript cho các lỗi cụ thể của agent của bạn. 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](/vi/policies/builtin-catalog) 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 1. Đi đến **Admin → policy editor**, chọn **New policy**, và mô tả lỗi bạn muốn ngăn chặn. 2. 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. 3. Lưu bản nháp và chọn **Publish version** để tạo một phiên bản không thay đổi. 4. Đ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. Trình soạn chính sách được sử dụng để tạo và xuất bản chính sách tùy chỉnh. 1. 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`. 2. Đăng ký một hoặc nhiều chính sách với `customPolicies.add()`. 3. Xác thực và cài đặt tệp với `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`. 4. 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()`. ```ts theme={null} 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 ```ts theme={null} 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 \| undefined` | Đầu vào chính tắc cho lệnh gọi công cụ hiện tại. | | `payload` | `Record` | 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` | 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`: ```ts theme={null} 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](/vi/reference/harnesses) trước khi dựa vào một sự kiện trên một hạm đội hỗn hợp. `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ệ ```ts theme={null} 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 ```ts theme={null} 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 ```ts theme={null} 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: ```text theme={null} /.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: ```bash theme={null} 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. ```bash theme={null} 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`. 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.