> ## 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. # Benutzerdefinierte Richtlinien > Erstellen, testen und deployen Sie JavaScript- oder TypeScript-Richtlinien für agentenspezifische Fehler. Benutzerdefinierte Richtlinien verwandeln ein Fehlermuster aus Ihren Traces oder Audits in eine Entscheidung, die während der Arbeit eines Agenten ausgeführt wird. Eine Richtlinie kann eine Aktion erlauben, dem Agenten Hinweise geben oder die Aktion blockieren, bevor sie einen weiteren Vorfall verursacht. Verwenden Sie eine benutzerdefinierte Richtlinie, wenn das Verhalten von Ihren Tools, Pfaden, Befehlen, Umgebungen oder Betriebsregeln abhängt. Prüfen Sie zuerst den [Katalog der integrierten Richtlinien](/de/policies/builtin-catalog), um keine bereits vorhandene Kontrolle neu zu erstellen. ## Eine benutzerdefinierte Richtlinie erstellen 1. Gehen Sie zu **Admin → policy editor**, wählen Sie **New policy** aus und beschreiben Sie den Fehler, den Sie verhindern möchten. 2. Fügen Sie den Richtlinienquellcode hinzu und testen Sie erwartete Treffer sowie unbedenkliche Nicht-Treffer im Editor. Beheben Sie alle Validierungsfehler. 3. Speichern Sie den Entwurf und wählen Sie **Publish version**, um eine unveränderliche Version zu erstellen. 4. Gehen Sie zu **Admin → enforcement**, deployen Sie die Version auf einem Testrechner im **observe**-Modus und überprüfen Sie die Entscheidungen unter **Observe → policy**, bevor Sie die Richtlinie durchsetzen. Der Policy-Editor zum Erstellen und Veröffentlichen einer benutzerdefinierten Richtlinie. 1. Erstellen Sie `.failproofai/policies/checkout-policies.ts`. Der Dateiname muss auf `policies.js`, `policies.mjs` oder `policies.ts` enden. 2. Registrieren Sie eine oder mehrere Richtlinien mit `customPolicies.add()`. 3. Validieren und installieren Sie die Datei mit `failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project`. 4. Lösen Sie eine passende Aktion und eine unbedenkliche Aktion aus. Führen Sie `failproofai policies` aus und prüfen Sie dann die zugeordneten Entscheidungen unter **Observe → policy**. ## Mit einer engen Regel beginnen Diese Richtlinie blockiert destruktive Kubernetes-Befehle nur dann, wenn der Befehl auf die Produktionsumgebung abzielt. Alles außerhalb dieses genauen Fehlermusters gibt `allow()` zurück. ```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.", ); }, }); ``` Gute Richtlinien sind eng genug, um sie in einem Satz zu erklären. Treffen Sie auf die beobachtbare Aktion – nicht auf die vermutete Absicht des Agenten – und geben Sie `allow()` zurück, sobald die Regel nicht zutrifft. ## Eine Entscheidung wählen | Hilfsfunktion | Ergebnis | Verwendung | | ------------------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `allow(reason?)` | Die Operation wird fortgesetzt. | Die Richtlinie gilt nicht oder die Aktion ist unbedenklich. | | `instruct(reason)` | Die Operation wird fortgesetzt, mit Hinweisen sofern der Harness dies unterstützt. | Sie möchten den Agenten zu einem besseren Ansatz leiten, ohne eine Invariante durchzusetzen. | | `deny(reason)` | Die Operation wird blockiert, wenn das Ereignis und der Harness das Blockieren unterstützen. | Die Aktion darf nicht fortgesetzt werden. | Schreiben Sie den Grund für den Agenten, der sich erholen muss. Erläutern Sie, was erkannt wurde und was stattdessen getan werden soll. Verwenden Sie `instruct()` nicht für eine Sicherheitsgrenze. Die Übermittlung von Hinweisen variiert je nach Agent-Harness. Verwenden Sie `deny()`, wenn die Aktion verhindert werden muss. ## Das Policy-Objekt ```ts theme={null} customPolicies.add({ name: "policy-name", description: "What this policy prevents", match: { events: ["PreToolUse"] }, fn: async (ctx) => allow(), }); ``` | Feld | Erforderlich | Beschreibung | | -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ | | `name` | Ja | Stabiler Bezeichner für die Richtlinie. Namen müssen dateiübergreifend eindeutig sein. | | `description` | Nein | Lesbare Beschreibung des Zwecks, die in Richtlinienübersichten und Entscheidungen angezeigt wird. | | `match.events` | Nein | Ereignistypen, die die Richtlinie aufrufen. Wird `match` weggelassen, wird sie für jedes verfügbare Ereignis aufgerufen. | | `fn` | Ja | Synchrone oder asynchrone Funktion, die ein `allow`-, `instruct`- oder `deny`-Ergebnis zurückgibt. | Filtern Sie Tools innerhalb von `fn`. `match.toolNames` ist kein Teil des öffentlichen Typs für benutzerdefinierte Richtlinien. ## Policy-Kontext Jede Richtlinie erhält einen `PolicyContext`. | Feld | Typ | Inhalt | | ----------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `eventType` | `HookEventType` | Normalisiertes Ereignis, das aktuell ausgewertet wird. | | `toolName` | `string \| undefined` | Kanonischer Tool-Name, z. B. `Bash`, `Read`, `Write` oder `Edit`. | | `toolInput` | `Record \| undefined` | Kanonische Eingabe für den aktuellen Tool-Aufruf. | | `payload` | `Record` | Vollständiger normalisierter Ereignis-Payload. | | `session` | `SessionMetadata \| undefined` | Sitzungs-ID, Arbeitsverzeichnis, Transcript-Pfad, Berechtigungsmodus und Harness-Metadaten, sofern verfügbar. | | `cli` | `string \| undefined` | Quell-Agent-Harness, z. B. `claude`, `codex` oder `cursor`. | | `params` | `Record` | Parameter integrierter Richtlinien. Benutzerdefinierte Richtlinien erhalten derzeit ein leeres Objekt. | Behandeln Sie jeden optionalen Wert als tatsächlich optional. Nicht alle Agent-Versionen und Ereignistypen stellen dieselben Felder bereit. ### Häufige Tool-Eingaben Failproof AI normalisiert gängige Tools über unterstützte Harnesses hinweg, sodass eine Richtlinie in der Regel eine einheitliche Eingabeform verwenden kann. | Tool | Häufige Felder | | ------- | --------------------------------------- | | `Bash` | `command` | | `Read` | `file_path` | | `Write` | `file_path`, `content` | | `Edit` | `file_path`, `old_string`, `new_string` | | `Grep` | `pattern`, `path` | Verwenden Sie defensive Typumwandlung, da Tool-Eingabewerte als `unknown` typisiert sind: ```ts theme={null} const command = String(ctx.toolInput?.command ?? ""); const filePath = String(ctx.toolInput?.file_path ?? ""); ``` ## Das Ereignis wählen | Ereignis | Ausführungszeitpunkt | Typische Verwendung | | ----------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `PreToolUse` | Vor der Ausführung eines Tools. | Befehle, Schreibzugriffe, Lesezugriffe und externe Aktionen blockieren oder steuern. | | `PostToolUse` | Nachdem ein Tool zurückgekehrt ist. | Ergebnisse prüfen, bevor sie den Agenten erreichen. Ein deny blockiert das gesamte Ergebnis; einzelne Felder werden nicht herausgefiltert. | | `PermissionRequest` | Wenn der Agent eine Berechtigung anfordert. | Organisationsspezifische Berechtigungsregeln anwenden. | | `UserPromptSubmit` | Bevor ein eingereichter Prompt fortgesetzt wird. | Unzulässige Anweisungen ablehnen oder Workflow-Hinweise hinzufügen. | | `Stop` | Wenn der Agent versucht, die Arbeit abzuschließen. | Eine erreichbare Abschlussbedingung voraussetzen, z. B. einen lokalen Verifizierungsschritt. | | `SubagentStop` | Wenn ein Subagent versucht, die Arbeit abzuschließen. | Delegierte Arbeit prüfen, bevor sie zum übergeordneten Agenten zurückkehrt. | | `SessionStart` / `SessionEnd` | An Sitzungsgrenzen. | Zustand auf Sitzungsebene aufzeichnen oder prüfen. | Die Verfügbarkeit von Ereignissen und das Blockierverhalten hängen vom Agent-Harness ab. Lesen Sie [Agent harnesses](/de/reference/harnesses), bevor Sie sich bei einem gemischten Fleet auf ein Ereignis verlassen. `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` und `Setup`. ## Häufige Richtlinienmuster erstellen ### Schreibzugriffe auf geschützte Pfade blockieren ```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."); }, }); ``` ### Nicht-blockierende Hinweise geben ```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."); }, }); ``` ### Sitzungsabschluss absichern ```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."); } }, }); ``` Ein abgelehntes `Stop`-Ereignis kann dazu führen, dass der Agent es erneut versucht. Sichern Sie nur Bedingungen ab, die der Agent in der aktuellen Umgebung erfüllen kann, und begrenzen Sie jeden Subprocess- oder Netzwerkaufruf. ## Richtliniendateien laden ### Konventionsdateien Konventionsdateien werden automatisch geladen: ```text theme={null} /.failproofai/policies/security-policies.ts ~/.failproofai/policies/personal-policies.mjs ``` * Projekt- und Benutzer-Richtlinienverzeichnisse werden beide geladen. * Dateien werden innerhalb jedes Verzeichnisses alphabetisch geladen. * Eine Datei muss auf `policies.js`, `policies.mjs` oder `policies.ts` enden. * Mehrere `customPolicies.add()`-Aufrufe in einer Datei werden unterstützt. * Relative Importe aus lokalen Modulen werden unterstützt. * Projektrichtlinien können eingecheckt werden, sodass dieselben Regeln dem Repository folgen. ### Explizite Dateien Verwenden Sie explizite Pfade, wenn die Validierung oder Konfiguration die Eingabedatei direkt benennen soll: ```bash theme={null} failproofai policies --install \ --custom ./security.policies.ts \ --custom ./workflow.policies.ts \ --scope project ``` Explizite Dateien werden zuerst geladen, gefolgt von Projekt-Konventionsdateien und dann Benutzer-Konventionsdateien. Eine Datei, die über beide Pfade gefunden wird, wird nur einmal geladen. ## Validieren und testen Die Validierung führt das Modul über den Produktions-Loader aus und bestätigt, dass mindestens eine Richtlinie registriert wird. ```bash theme={null} failproofai policies --install \ --custom ./.failproofai/policies/checkout-policies.ts \ --scope project failproofai policies ``` Die Validierung erkennt fehlende Dateien, Syntaxfehler, nicht aufgelöste Importe, Ausnahmen auf oberster Ebene und Modul-Lade-Timeouts. Sie beweist jedoch nicht, dass Ihre Match-Logik korrekt ist. Testen Sie mindestens diese Fälle: * Eine Aktion, die treffen muss und den beabsichtigten Richtliniengrund erzeugen soll. * Eine ähnliche, aber unbedenkliche Aktion, die `allow()` zurückgeben muss. * Fehlende oder fehlerhafte Tool-Felder. * Abweichende Befehlssyntax, Pfade, Anführungszeichen, Groß-/Kleinschreibung und Leerzeichen. * Ein nicht verfügbarer Subprocess oder eine nicht verfügbare Netzwerkabhängigkeit. Ordnen Sie das Ergebnis Ihrer benutzerdefinierten Richtlinie unter **Observe → policy** zu. Ein blockierter Test ist nicht ausreichend, wenn eine andere integrierte Richtlinie die Entscheidung getroffen hat. ## Laufzeitverhalten * Integrierte Richtlinien werden vor benutzerdefinierten Richtlinien ausgewertet. * Das erste `deny` stoppt die weitere Richtlinienauswertung. * Mehrere `instruct`-Ergebnisse können kombiniert werden, wenn keine Richtlinie das Ereignis ablehnt. * Eine Richtlinienfunktion hat eine Ausführungsfrist von 10 Sekunden. * Eine ausgelöste Ausnahme oder ein Timeout wird protokolliert und als `allow()` behandelt. * Eine Konventionsdatei, die nicht geladen werden kann, wird übersprungen; andere benutzerdefinierte Dateien und integrierte Richtlinien werden weiterhin ausgeführt. * Das Laden von Modulen auf oberster Ebene hat ebenfalls eine Frist von 10 Sekunden. * Im Cloud-Observe-Modus wird die Richtlinie ausgeführt, aber eine Nicht-allow-Entscheidung wird aufgezeichnet, ohne sie durchzusetzen. Halten Sie Richtlinienmodule deterministisch und schnell. Vermeiden Sie Netzwerkaufrufe oder Server-Starts auf oberster Ebene. Begrenzen Sie die Arbeit innerhalb von `fn`, fangen Sie Abhängigkeitsfehler ab und entscheiden Sie bewusst, ob ein solcher Fehler die Operation erlauben oder ablehnen soll. ## API-Exporte | Export | Zweck | | ---------------------------- | ---------------------------------------------------------------------- | | `customPolicies.add(policy)` | Eine benutzerdefinierte Richtlinie beim Laden des Moduls registrieren. | | `allow(reason?)` | Die Operation erlauben. | | `instruct(reason)` | Die Operation erlauben und Hinweise bereitstellen, sofern unterstützt. | | `deny(reason)` | Die Operation blockieren, sofern unterstützt. | | `getCustomHooks()` | Die aktuell im Modul-Registry registrierten Richtlinien zurückgeben. | | `clearCustomHooks()` | Das Registry leeren, hauptsächlich für Tests und Loader. | TypeScript exportiert `PolicyContext`, `PolicyResult`, `CustomHook`, `PolicyDecision` und `PolicyFunction`. Veröffentlichen Sie eine Version, deployen Sie sie im Observe-Modus, überprüfen Sie Entscheidungen und wechseln Sie zur Durchsetzung.