מדיניות מותאמות

מדיניות מותאמת הופכת דפוס כשל מהעקבות או הביקורות שלך להחלטה שרצה כשהסוכן עובד. מדיניות יכולה לאפשר פעולה, לתת הנחיות לסוכן, או לשלול את הפעולה לפני שהיא גורמת לעוד תקרית. השתמש במדיניות מותאמת כשההתנהגות תלויה בכלים, בנתיבים, בפקודות, בסביבות או בכללי תפעול שלך. בדוק קודם את קטלוג המדיניות המובנה כדי שלא תשחזור בקרה קיימת.

כתוב מדיניות מותאמת

Dashboard
CLI

עבור אל Admin → policy editor, בחר New policy, ותאר את הכשל שברצונך למנוע.
הוסף את קוד המדיניות, ולאחר מכן בדוק התאמות צפויות וללא התאמות בטוחות בעורך. פתור כל שגיאת אימות.
שמור את הטיוטה ובחר Publish version כדי ליצור גרסה בלתי ניתנת לשינוי.
עבור אל Admin → enforcement, פרוס את הגרסה למכונת בדיקה ב-observe מצב, ובדוק את ההחלטות שלה תחת 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.",
    );
  },
});

מדיניות טובה צר מספיק כדי להסביר במשפט אחד. התאם את הפעולה הניתנת לתצפית—לא הכוונה שאתה מקווה שהסוכן היה—והחזר allow() ברגע שהכלל לא חל.

בחר החלטה

עוזר	תוצאה	השתמש בה כאשר
`allow(reason?)`	הפעולה ממשיכה.	המדיניות לא חלה או הפעולה בטוחה.
`instruct(reason)`	הפעולה ממשיכה עם הנחיות בעבור מקום שבו רתיעה תומכת בכך.	אתה רוצה לכוונן את הסוכן לכיוון גישה טובה יותר ללא כפיית משתנה.
`deny(reason)`	הפעולה חסומה כאשר האירוע ורתיעה תומכים בחסימה.	הפעולה לא חייבת להמשיך.

כתוב את ההנמקה לסוכן שחייב להתאוחד. הסבר מה גילוי וממה עליו לעשות במקום זאת.

אל תשתמש ב-instruct() לגבול בטיחות. הספקת הנחיות משתנה לפי רתיעת סוכן. השתמש ב-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`	מזהה הפעלה, ספריית עבודה, נתיב שלוג, מצב הרשאה, ומטא-נתוני רתיעה כאשר זמין.
`cli`	`string \| undefined`	סוכן רתיעה מקור, כגון `claude`, `codex`, או `cursor`.
`params`	`Record<string, unknown>`	פרמטרי מדיניות מובנים. מדיניות מותאמת כרגע מקבלת אובייקט ריק.

התייחס לכל ערך אופציונלי כאופציונלי באמת. גרסאות סוכן וסוגי אירועים לא כולם מספקים את אותם שדות.

קלט כלים נפוץ

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`	לאחר שכלי חוזר.	בדוק תוצאות לפני שהן מגיעות לסוכן. שלילה חוסמת את התוצאה כולה; היא לא מחסלת שדות נבחרים.
`PermissionRequest`	כאשר הסוכן מבקש הרשאה.	החל כללי הרשאה ספציפיים לארגון.
`UserPromptSubmit`	לפני המשך הנושא שהוגש.	דחה הנחיות אסורות או הוסף הנחיות זרימת עבודה.
`Stop`	כאשר הסוכן מנסה לסיים.	דרוש תנאי השלמה בר הישג, כגון שלב אימות מקומי.
`SubagentStop`	כאשר סוכן משנה מנסה לסיים.	שער עבודה מופקדת לפני שחוזרת להורה.
`SessionStart` / `SessionEnd`	בגבולות הפעלה.	רשום או בדוק מצב ברמת ההפעלה.

זמינות אירוע והתנהגות חסימה תלויים ברתיעת סוכן. ראה סוכן רתיעות לפני שאתה מסתמך על אירוע בפני קרקע מעורבבת.

שמות אירוע מדיניות כל

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 שלול יכול לגרום לסוכן לנסות שוב. שער רק בתנאי שהסוכן יכול להשביח בסביבה הנוכחית, וקשור כל קריאה תהליך או רשת.

טען קבצי מדיניות

קבצי קונבנציה

קבצי קונבנציה טעונים באופן אוטומטי:

<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 שניות.
מצב תצפית ענן מריץ את המדיניות אך רושם החלטה שאינה ללא כפיית הביצוע.

שמור מודולי מדיניות דטרמיניסטי ומהיר. הימנע מקריאות רשת ברמה עליונה או הפעלה של שרת. עבודה קשורה בתוך fn, תופסת כשלים בתלות, ובחר בכוונה הייתה כשל זה צריך לאפשר או לשלול את הפעולה.

ייצוא 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