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

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

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

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`	ID הסשן, תיקיית עבודה, נתיב תמלול, מצב הרשאה ומטא-נתונים של השקה כאשר זמינים.
`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`	בגבולות הסשן.	הקלט או בדוק מצב ברמת הסשן.

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

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

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()`	בטל את השדורי זה, בעיקר לבדיקות ו loaders.

TypeScript מייצא PolicyContext, PolicyResult, CustomHook, PolicyDecision ו PolicyFunction.

פרוס מדיניות מותאמות

פרסם גרסה, פרוס אותה במצב התבוננות, אימת החלטות, ועבור לאכיפה.

Connect your agents

Reference

HTTP API

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

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

התחל עם כלל צר

בחר החלטה

אובייקט מדיניות

הקשר מדיניות

קלטים כלים נפוצים

בחר את האירוע

כתוב דפוסי מדיניות נפוצים

חסום כתיבות לנתיבים מוגנים

תן הנחיה שאינה חוסמת

סגור השלמת סשן

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

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

קובצים מפורשים

אימות וביקורת

התנהגות ריצה

ייצוא API

פרוס מדיניות מותאמות

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

​התחל עם כלל צר

​בחר החלטה

​אובייקט מדיניות

​הקשר מדיניות

​קלטים כלים נפוצים

​בחר את האירוע

​כתוב דפוסי מדיניות נפוצים

​חסום כתיבות לנתיבים מוגנים

​תן הנחיה שאינה חוסמת

​סגור השלמת סשן

​קובצי מדיניות טעינה

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

​קובצים מפורשים

​אימות וביקורת

​התנהגות ריצה

​ייצוא API

פרוס מדיניות מותאמות

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

התחל עם כלל צר

בחר החלטה

אובייקט מדיניות

הקשר מדיניות

קלטים כלים נפוצים

בחר את האירוע

כתוב דפוסי מדיניות נפוצים

חסום כתיבות לנתיבים מוגנים

תן הנחיה שאינה חוסמת

סגור השלמת סשן

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

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

קובצים מפורשים

אימות וביקורת

התנהגות ריצה

ייצוא API