From a2ec95d350cedc6cdb2458f26c8da503321be5ba Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 30 Jul 2026 11:31:25 +0000 Subject: [PATCH] docs: update translations for changed English sources --- docs/ar/configuration.mdx | 137 +++++++++++----------- docs/ar/custom-policies.mdx | 150 ++++++++++++------------ docs/ar/dashboard.mdx | 89 ++++++++------- docs/de/configuration.mdx | 116 ++++++++++--------- docs/de/custom-policies.mdx | 151 +++++++++++++------------ docs/de/dashboard.mdx | 74 ++++++------ docs/es/configuration.mdx | 112 ++++++++++-------- docs/es/custom-policies.mdx | 117 ++++++++++--------- docs/es/dashboard.mdx | 56 ++++----- docs/fr/configuration.mdx | 90 ++++++++------- docs/fr/custom-policies.mdx | 109 +++++++++--------- docs/fr/dashboard.mdx | 76 +++++++------ docs/he/configuration.mdx | 141 ++++++++++++----------- docs/he/custom-policies.mdx | 146 ++++++++++++------------ docs/he/dashboard.mdx | 112 +++++++++--------- docs/hi/configuration.mdx | 133 ++++++++++++---------- docs/hi/custom-policies.mdx | 201 +++++++++++++++++---------------- docs/hi/dashboard.mdx | 102 +++++++++-------- docs/it/configuration.mdx | 139 ++++++++++++----------- docs/it/custom-policies.mdx | 136 +++++++++++----------- docs/it/dashboard.mdx | 79 ++++++------- docs/ja/configuration.mdx | 120 +++++++++++--------- docs/ja/custom-policies.mdx | 135 +++++++++++----------- docs/ja/dashboard.mdx | 86 +++++++------- docs/ko/configuration.mdx | 114 ++++++++++--------- docs/ko/custom-policies.mdx | 139 ++++++++++++----------- docs/ko/dashboard.mdx | 78 ++++++------- docs/pt-br/configuration.mdx | 102 ++++++++++------- docs/pt-br/custom-policies.mdx | 129 +++++++++++---------- docs/pt-br/dashboard.mdx | 58 +++++----- docs/ru/configuration.mdx | 130 +++++++++++---------- docs/ru/custom-policies.mdx | 171 ++++++++++++++-------------- docs/ru/dashboard.mdx | 91 +++++++-------- docs/tr/configuration.mdx | 142 ++++++++++++----------- docs/tr/custom-policies.mdx | 183 +++++++++++++++--------------- docs/tr/dashboard.mdx | 93 +++++++-------- docs/vi/configuration.mdx | 123 +++++++++++--------- docs/vi/custom-policies.mdx | 117 ++++++++++--------- docs/vi/dashboard.mdx | 66 +++++------ docs/zh/configuration.mdx | 104 +++++++++-------- docs/zh/custom-policies.mdx | 117 ++++++++++--------- docs/zh/dashboard.mdx | 90 +++++++-------- 42 files changed, 2568 insertions(+), 2286 deletions(-) diff --git a/docs/ar/configuration.mdx b/docs/ar/configuration.mdx index 9c277024..5c6b78af 100644 --- a/docs/ar/configuration.mdx +++ b/docs/ar/configuration.mdx @@ -1,62 +1,63 @@ --- ---- -title: التكوين -description: "تنسيق ملف الإعدادات، ونظام النطاقات الثلاثة، وقواعد الدمج" +title: الإعدادات +description: "صيغة ملف الإعدادات، ونظام الثلاث نطاقات، وقواعد الدمج" icon: gear --- -يستخدم failproofai ملفات إعدادات JSON للتحكم في السياسات المفعلة وكيفية عملها ومن أين يتم تحميل السياسات المخصصة. صُمم التكوين ليكون سهل المشاركة مع فريقك - التزمه في مستودعك وسيحصل كل مطور على نفس شبكة الأمان للوكيل. +يستخدم failproofai ملفات إعدادات JSON للتحكم في السياسات النشطة وكيفية عملها ومن أين يتم تحميل السياسات المخصصة. تم تصميم الإعدادات لتكون سهلة المشاركة مع فريقك - التزم بها في مستودعك وسيحصل كل مطور على نفس شبكة الأمان للوكيل. --- -## نطاقات التكوين +## نطاقات الإعدادات -هناك ثلاثة نطاقات للتكوين، يتم تقييمها بترتيب الأولوية: +هناك ثلاثة نطاقات إعدادات، يتم تقييمها بترتيب الأولوية: | النطاق | مسار الملف | الغرض | |-------|-----------|---------| -| **المشروع** | `.failproofai/policies-config.json` | إعدادات خاصة بكل مستودع، مرتبطة بمراقبة الإصدار | -| **محلي** | `.failproofai/policies-config.local.json` | تجاوزات شخصية لكل مستودع، مستبعدة من git | +| **المشروع** | `.failproofai/policies-config.json` | إعدادات لكل مستودع، مرتبطة بالتحكم في الإصدارات | +| **محلي** | `.failproofai/policies-config.local.json` | تجاوزات شخصية لكل مستودع، مضافة إلى gitignore | | **عام** | `~/.failproofai/policies-config.json` | الإعدادات الافتراضية على مستوى المستخدم عبر جميع المشاريع | -عندما يتلقى failproofai حدث hook، يقوم بتحميل ودمج جميع الملفات الثلاثة الموجودة للدليل العامل الحالي. +عندما يتلقى failproofai حدث hook، يقوم بتحميل ودمج جميع الملفات الثلاثة الموجودة للمجلد العامل الحالي. ### قواعد الدمج -**`enabledPolicies`** - اتحاد جميع النطاقات الثلاثة. السياسة المفعلة على أي مستوى تكون نشطة. +**`enabledPolicies`** - اتحاد جميع النطاقات الثلاثة. السياسة المفعلة في أي مستوى تكون نشطة. ```text project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← اتحاد منقى من التكرارات +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← اتحاد مخصص للتكرار ``` -**`policyParams`** - أول نطاق يحدد معاملات سياسة معينة يفوز بالكامل. لا يوجد دمج عميق للقيم داخل معاملات السياسة. +**`policyParams`** - النطاق الأول الذي يحدد المعاملات لسياسة معينة يفوز تماماً. لا يوجد دمج عميق للقيم ضمن معاملات السياسة. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← المشروع يفوز، يتم تجاهل العام +resolved: { allowPatterns: ["sudo apt-get update"] } ← يفوز المشروع، يتم تجاهل العام ``` ```text -project: (لا توجد إدخالة block-sudo) -local: (لا توجد إدخالة block-sudo) +project: (no block-sudo entry) +local: (no block-sudo entry) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← ينتقل إلى العام +resolved: { allowPatterns: ["sudo systemctl status"] } ← يسقط إلى العام ``` -**`customPoliciesPath`** - أول نطاق يحدده يفوز. +**`customPoliciesPaths` / `customPoliciesPath`** - النطاق الأول الذي يحدد أي نموذج يفوز. + +**`disabledCustomPolicies`** - اتحاد عبر جميع النطاقات. لوحة التحكم تكتب معرف مؤهل بالمصدر هنا عندما تقوم بإيقاف تشغيل سياسة فردية من ملف سياسة صريح أو قائم على الاتفاقية. البيانات السياسية غير المدرجة تبقى مفعلة بشكل افتراضي؛ المعرفات تتضمن ملف المصدر حتى يمكن التحكم في السياسات بنفس الاسم في ملفات متعددة بشكل مستقل. -**`llm`** - أول نطاق يحدده يفوز. +**`llm`** - النطاق الأول الذي يحدده يفوز. --- -## تنسيق ملف الإعدادات +## صيغة ملف الإعدادات ```json { @@ -103,27 +104,27 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← ينتقل إلى ا النوع: `string[]` -قائمة أسماء السياسات المراد تفعيلها. يجب أن تطابق الأسماء بالضبط معرفات السياسات التي تظهر من خلال `failproofai policies`. انظر [السياسات المدمجة](/ar/built-in-policies) للحصول على القائمة الكاملة. +قائمة بأسماء السياسات المراد تفعيلها. يجب أن تطابق الأسماء بالضبط معرفات السياسات التي تعرضها `failproofai policies`. انظر [السياسات المدمجة](/ar/built-in-policies) للحصول على القائمة الكاملة. -السياسات غير الموجودة في `enabledPolicies` تكون غير نشطة، حتى لو كان لديها إدخالات في `policyParams`. +السياسات غير المدرجة في `enabledPolicies` غير نشطة، حتى لو كان لديها مدخلات في `policyParams`. ### `policyParams` النوع: `Record>` -تجاوزات المعاملات لكل سياسة. المفتاح الخارجي هو اسم السياسة؛ والمفاتيح الداخلية خاصة بكل سياسة. تتوثق كل سياسة معاملاتها المتاحة في [السياسات المدمجة](/ar/built-in-policies). +تجاوزات معاملات لكل سياسة. المفتاح الخارجي هو اسم السياسة؛ المفاتيح الداخلية خاصة بكل سياسة. توثق كل سياسة معاملاتها المتاحة في [السياسات المدمجة](/ar/built-in-policies). -إذا كانت السياسة لها معاملات ولم تحددها، يتم استخدام الإعدادات المدمجة الافتراضية للسياسة. المستخدمون الذين لا يقومون بتكوين `policyParams` على الإطلاق يحصلون على سلوك متطابق مع الإصدارات السابقة. +إذا كانت السياسة لديها معاملات ولكنك لم تحددها، يتم استخدام القيم الافتراضية المدمجة في السياسة. المستخدمون الذين لا يقومون بتكوين `policyParams` على الإطلاق يحصلون على سلوك مطابق للإصدارات السابقة. -المفاتيح غير المعروفة داخل كتلة معاملات السياسة يتم تجاهلها بصمت في وقت حدث الخطاف ولكن يتم الإشارة إليها كتحذيرات عند تشغيل `failproofai policies`. +المفاتيح غير المعروفة داخل كتلة معاملات السياسة يتم تجاهلها بصمت عند تشغيل الـ hook ولكن يتم الإبلاغ عنها كتحذيرات عند تشغيل `failproofai policies`. -#### `hint` (شامل) +#### `hint` (عابر) النوع: `string` (اختياري) -رسالة يتم إلحاقها بالسبب عندما تعيد السياسة `deny` أو `instruct`. استخدمها لإعطاء Claude إرشادات قابلة للتنفيذ دون تعديل السياسة نفسها. +رسالة مضافة إلى السبب عندما تعيد السياسة `deny` أو `instruct`. استخدمها لإعطاء Claude توجيهات قابلة للتنفيذ دون تعديل السياسة نفسها. -يعمل مع أي نوع سياسة — مدمجة، مخصصة (`custom/`)، اتفاقية المشروع (`.failproofai-project/`)، أو اتفاقية المستخدم (`.failproofai-user/`). +يعمل مع أي نوع سياسة — مدمج، مخصص (`custom/`)، اتفاقية المشروع (`.failproofai-project/`)، أو اتفاقية المستخدم (`.failproofai-user/`). ```json { @@ -136,38 +137,38 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← ينتقل إلى ا "hint": "استخدم apt-get مباشرة بدون sudo." }, "custom/my-policy": { - "hint": "اطلب موافقة المستخدم أولاً." + "hint": "اطلب من المستخدم الموافقة أولاً." } } } ``` -عندما ترفض `block-force-push`، يرى Claude: *"فرض الدفع محظور. حاول إنشاء فرع جديد بدلاً من ذلك."* +عندما يرفض `block-force-push`، يرى Claude: *"الدفع القسري محظور. حاول إنشاء فرع جديد بدلاً من ذلك."* -القيم غير النصية والنصوص الفارغة يتم تجاهلها بصمت. إذا لم يتم تعيين `hint`، السلوك لا يتغير (متوافق مع الإصدارات السابقة). +القيم غير النصية والسلاسل الفارغة يتم تجاهلها بصمت. إذا لم يتم تعيين `hint`، السلوك لم يتغير (متوافق للخلف). ### `customPoliciesPath` النوع: `string` (مسار مطلق) -مسار ملف JavaScript يحتوي على سياسات خطاف مخصصة. يتم تعيينه تلقائياً بواسطة `failproofai policies --install --custom ` (يتم حل المسار إلى مطلق قبل التخزين). +المسار إلى ملف JavaScript يحتوي على سياسات hook مخصصة. يتم تعيين هذا تلقائياً بواسطة `failproofai policies --install --custom ` (يتم حل المسار إلى مطلق قبل التخزين). -يتم تحميل الملف مجدداً في كل حدث خطاف - لا يوجد تخزين مؤقت. انظر [السياسات المخصصة](/ar/custom-policies) لتفاصيل الإنشاء. +يتم تحميل الملف بشكل جديد في كل حدث hook - لا يوجد تخزين مؤقت. انظر [السياسات المخصصة](/ar/custom-policies) للحصول على تفاصيل الإنشاء. -### سياسات قائمة على الاتفاقية +### السياسات القائمة على الاتفاقية -بالإضافة إلى `customPoliciesPath` الصريح، يقوم failproofai تلقائياً باكتشاف وتحميل ملفات السياسات من دلائل `.failproofai/policies/`: +بالإضافة إلى `customPoliciesPath` الصريح، يقوم failproofai تلقائياً باكتشاف وتحميل ملفات السياسات من مجلدات `.failproofai/policies/`: -| المستوى | الدليل | النطاق | -|-------|---------|-------| -| المشروع | `.failproofai/policies/` | مشاركة مع الفريق عبر مراقبة الإصدار | +| المستوى | المجلد | النطاق | +|-------|-----------|-------| +| المشروع | `.failproofai/policies/` | مشاركة مع الفريق عبر التحكم في الإصدارات | | المستخدم | `~/.failproofai/policies/` | شخصي، ينطبق على جميع المشاريع | -**مطابقة الملفات:** يتم تحميل الملفات فقط التي تتطابق مع `*policies.{js,mjs,ts}` (مثلاً `security-policies.mjs`, `workflow-policies.js`). تُتجاهل الملفات الأخرى في الدليل. +**مطابقة الملفات:** يتم تحميل الملفات فقط التي تطابق `*policies.{js,mjs,ts}` (مثل `security-policies.mjs`، `workflow-policies.js`). الملفات الأخرى في المجلد يتم تجاهلها. -**لا حاجة لإعدادات:** سياسات الاتفاقية لا تتطلب إدخالات في `policies-config.json`. فقط ضع ملفات في الدليل وسيتم التقاطها في حدث الخطاف التالي. +**لا يلزم تكوين:** سياسات الاتفاقية لا تتطلب مدخلات في `policies-config.json`. فقط ضع الملفات في المجلد وسيتم التقاطها في حدث الـ hook التالي. -**تحميل الاتحاد:** يتم البحث في دلائل الاتفاقية للمشروع والمستخدم. يتم تحميل جميع الملفات المطابقة من كلا المستويين (على عكس `customPoliciesPath` الذي يستخدم أول نطاق يفوز). +**التحميل المتحد:** يتم مسح مجلدات الاتفاقية للمشروع والمستخدم. يتم تحميل جميع الملفات المطابقة من كلا المستويين (على عكس `customPoliciesPath` الذي يستخدم أول نطاق يفوز). انظر [السياسات المخصصة](/ar/custom-policies) لمزيد من التفاصيل والأمثلة. @@ -175,7 +176,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← ينتقل إلى ا النوع: `object` (اختياري) -إعدادات عميل LLM للسياسات التي تقوم بعمليات استدعاء ذكية. غير مطلوبة لمعظم الإعدادات. +تكوين عميل LLM للسياسات التي تقوم بإجراء استدعاءات AI. غير مطلوب لمعظم الإعدادات. ```json { @@ -190,19 +191,24 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← ينتقل إلى ا ## إدارة الإعدادات من سطر الأوامر -تقوم أوامر `policies --install` و `policies --uninstall` بالكتابة إلى ملف إعدادات خطاف عميل الوكيل (نقاط دخول الخطاف)، بينما `policies-config.json` هو الملف الذي تديره مباشرة. الاثنان منفصلان: - -- **إعدادات عميل الوكيل** — يخبر الوكيل باستدعاء `failproofai --hook ` في كل استخدام أداة: - - **Claude Code**: `~/.claude/settings.json` (مستخدم), `/.claude/settings.json` (مشروع), `/.claude/settings.local.json` (محلي) - - **OpenAI Codex**: `~/.codex/hooks.json` (مستخدم), `/.codex/hooks.json` (مشروع) — Codex ليس له نطاق محلي - - **GitHub Copilot CLI _(نسخة تجريبية)_**: `~/.copilot/hooks/failproofai.json` (مستخدم), `/.github/hooks/failproofai.json` (مشروع) — Copilot ليس له نطاق محلي. إدخالات الخطاف تستخدم حقول أوامر Copilot المفتاحة بنظام التشغيل `bash`/`powershell` مع `timeoutSec`؛ يحمل الملف علامة `version: 1` على المستوى الأعلى. دعم GitHub Copilot CLI **نسخة تجريبية** بينما نتحقق من مخطط سجل `events.jsonl` (الذي لا تحدده المستندات العامة) مقابل جلسات حقيقية أكثر. - - **Cursor Agent _(نسخة تجريبية)_**: `~/.cursor/hooks.json` (مستخدم), `/.cursor/hooks.json` (مشروع) — Cursor ليس له نطاق محلي. إدخالات الخطاف تستخدم نموذج `{type, command, timeout}` على شكل Claude (لا انقسام `bash`/`powershell`)، لكن يتم تخزينها تحت مفاتيح أحداث camelCase (`preToolUse`, `beforeSubmitPrompt`, …) في مصفوفة مسطحة وفقاً [لمخطط الخطافات](https://cursor.com/docs/hooks) الخاص بـ Cursor؛ يحمل الملف علامة `version: 1` على المستوى الأعلى. يقوم المعالج بتحويل camelCase → PascalCase عبر `CURSOR_EVENT_MAP` بحيث تعمل السياسات المدمجة الموجودة بدون تغيير. دعم Cursor Agent **نسخة تجريبية** بينما نتحقق من نسخة Cursor على القرص (غير محددة في المستندات العامة) مقابل عمليات تثبيت حقيقية أكثر. - - **OpenCode _(نسخة تجريبية)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (مستخدم), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (مشروع) — OpenCode ليس له نطاق محلي. على عكس المحررات الخمسة الأخرى، OpenCode **ليس له نظام خطاف أوامر خارجية**: يحمل في الذاكرة مكوّنات JavaScript/TypeScript مسجلة بشكل صريح عبر مصفوفة `plugin: []` في `opencode.json` (الاكتشاف التلقائي من `.opencode/plugins/` **ليس** كيف يتم تحميل المكونات على opencode v1.14.33). التثبيت ينقط مكون شيم صغير يستدعي ثنائي failproofai عبر subprocess ويترجم استجابة JSON على شكل Claude الخاصة بالثنائي إلى دلالات المكون: `throw new Error()` لرفض حدث الأداة (يلغي استدعاء الأداة)، `client.session.prompt(...)` للتعليمات **و** لرفض `Stop` / `SubagentStop` (يرسل سبب الرفض كرسالة المستخدم التالية — القناة الوحيدة للإعادة القسرية منذ أن `session.idle` إخطار فقط والرمي منه لا يعمل)، بدون عملية للسماح. يقوم الشيم بتحويل أسماء الأدوات (lowercase → PascalCase عبر `OPENCODE_TOOL_MAP`) ومفاتيح حجج إدخال الأداة (camelCase → snake_case عبر `OPENCODE_TOOL_INPUT_MAP` لـ `Read` / `Write` / `Edit`، مثلاً `filePath` → `file_path`, `oldString` → `old_string`) قبل إعادة التوجيه إلى الثنائي، بحيث تعمل عمليات التحقق من المسارات المدمجة مثل `block-read-outside-cwd`, `block-env-files`, و `block-secrets-write` بدون تغيير على استدعاءات أداة OpenCode. الجلسات تعيش في قاعدة بيانات OpenCode SQLite في `~/.local/share/opencode/opencode.db`؛ عارض الجلسات في لوحة التحكم يقرأها عبر `opencode db --format json` و `opencode export `. دعم OpenCode **نسخة تجريبية** بينما نتحقق من السلوك عبر الإصدارات ومقابل جلسات حقيقية أكثر. انظر [مستندات مكونات OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(نسخة تجريبية)_**: `~/.pi/agent/settings.json` (مستخدم), `/.pi/settings.json` (مشروع) — Pi ليس له نطاق محلي. يحمل Pi حزم ملحقات TypeScript عند البدء؛ ملف الإعدادات مصفوفة نصية مسطحة `{"packages": ["./relative/path", …]}`. يكتب failproofai إدخالة مصفوفة حزم واحدة تشير إلى دليل `pi-extension/` المجمع الخاص به. يشترك الملحق داخلياً في أحداث Pi `tool_call` / `user_bash` / `input` / `session_start` ويقذف إلى `failproofai --hook --cli pi`؛ يقوم المعالج بتحويل underscore_lower_snake_case → PascalCase عبر `PI_EVENT_MAP` بحيث تعمل السياسات المدمجة الموجودة بدون تغيير. يتم أيضاً تحويل حجج إدخال الأداة عبر `PI_TOOL_INPUT_MAP` (تسليم Pi للقراءة / الكتابة / التحرير `path` بدلاً من `file_path`؛ تعيين المفتاح على المستوى الأعلى يسمح بتشغيل `block-env-files` و `block-secrets-write` — `block-read-outside-cwd` كان لديه بالفعل بديل `path`). دعم Pi **نسخة تجريبية** بينما تستقر ملحقات Pi API وتخطيط سجل الجلسة. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**نطاق المستخدم فقط** — Hermes ليس له إعدادات المشروع/المحلي). Hermes هو **بوابة** Slack/Telegram، لذلك تثبيت واحد يعترض استدعاءات الأدوات من كل منصة (Slack/Telegram/cli/cron) **و** الوكلاء الفرعيين الداخليين. إدخالات الخطاف هي زوج `{command, timeout}` (المهلة الزمنية **بالثواني**) تحت خريطة `hooks:` مفتاحها بأحداث snake_case من Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); يقوم المعالج بتحويل الأحداث عبر `HERMES_EVENT_MAP` وأسماء الأدوات عبر `HERMES_TOOL_MAP` بحيث تعمل السياسات المدمجة بدون تغيير. يتم تحرير الإعدادات من خلال استدارة YAML `Document` حفاظاً على التعليقات بحيث تبقى الإعدادات الأخرى للمشغل، والتثبيت يعيّن `hooks_auto_accept: true` بحيث تعمل بوابة بدون رأس (لا TTY) الخطافات بدون موجه موافقة. يصدر المقيّم عقد stdout الخاص بـ Hermes `{"decision":"block","reason"}` (يتجاهل Hermes أكواد الخروج). **القيود:** Hermes ليس له حدث نهاية الدور `Stop`، لذا فإن المدمجات `require-*-before-stop` لن تعمل أبداً لـ Hermes (غير قابلة للتطبيق، وليس كسر)؛ `instruct` تنخفض إلى السماح مع ملاحظة مسجلة (لا قناة سياق إضافية)؛ وإعادة تسمية سرية الإخراج (`sanitize-*`) لا يمكن إعادة كتابة إخراج الأداة على عقد shell-hook. Hermes هو **أيضاً** مصدر **تدقيق** غير متصل — لوحة التحكم تقرأ جلسات بوابتها مباشرة من `~/.hermes/state.db`. -- **`policies-config.json`** — يخبر failproofai بالسياسات التي يجب تقييمها وبأية معاملات (مشاركة عبر جميع عملاء الوكيل) - -مرر `--cli claude|codex|copilot|cursor|opencode|pi|hermes` لاستهداف وكيل محدد (مفصول بمسافات أو متكرر لأي مجموعة فرعية): +تقوم أوامر `policies --install` و `policies --uninstall` بالكتابة إلى ملف إعدادات hook لـ CLI الوكيل الخاص بك (نقاط دخول hook)، بينما `policies-config.json` هو الملف الذي تديره مباشرة. الاثنان منفصلان: + +- **إعدادات CLI للوكيل** — يخبر الوكيل باستدعاء `failproofai --hook ` في كل استخدام أداة: + - **Claude Code**: `~/.claude/settings.json` (مستخدم)، `/.claude/settings.json` (مشروع)، `/.claude/settings.local.json` (محلي) + - **OpenAI Codex**: `~/.codex/hooks.json` (مستخدم)، `/.codex/hooks.json` (مشروع) — Codex لا يوجد لديه نطاق محلي + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (مستخدم)، `/.github/hooks/failproofai.json` (مشروع) — Copilot ليس لديه نطاق محلي. مدخلات Hook تستخدم حقول أوامر Copilot المفتاحة حسب نظام التشغيل `bash`/`powershell` مع `timeoutSec`؛ الملف يحمل علامة `version: 1` على المستوى الأعلى. دعم Copilot CLI هو **beta** بينما نتحقق من مخطط سجل `events.jsonl` (الذي لا تحدده المستندات العامة) مقابل جلسات أكثر من الواقع. **وضع عامل VS Code Copilot Chat (معاينة)** يقرأ تكوينات hook من `.github/hooks/*.json`، `~/.copilot/hooks/*.json`، و `~/.claude/settings.json` (يحكمه إعداد `chat.hookFilesLocations`) باستخدام نفس عقد Claude الشكل `{hookSpecificOutput:{permissionDecision:"deny",…}}` — المسارات الدقيقة التي كتبتها هذه التكاملة `copilot` والتكاملة `claude` (`~/.claude/settings.json`) بالفعل، لذا `failproofai policies --install --cli copilot` (أو `--cli claude`) **بالفعل تفرض في وضع عامل VS Code** بدون تكامل `vscode` منفصل (مؤكد مباشرة من سجلات اكتشاف VS Code). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (مستخدم)، `/.cursor/hooks.json` (مشروع) — Cursor ليس لديه نطاق محلي. مدخلات Hook تستخدم نموذج Claude الشكل `{type, command, timeout}` (لا يوجد تقسيم `bash`/`powershell`)، لكن مخزنة تحت مفاتيح أحداث camelCase (`preToolUse`، `beforeSubmitPrompt`، …) في مصفوفة مسطحة لكل مخطط hooks في Cursor في [docs](https://cursor.com/docs/hooks)؛ الملف يحمل علامة `version: 1` على المستوى الأعلى. يقوم المعالج بتطبيع camelCase → PascalCase عبر `CURSOR_EVENT_MAP` بحيث تطلق السياسات المدمجة الموجودة دون تغيير. دعم Cursor Agent هو **beta** بينما نتحقق من نص Cursor على تنسيق على الجرم (غير محدد في المستندات العامة) مقابل عمليات تثبيت أكثر من الواقع. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (مستخدم)، `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (مشروع) — OpenCode ليس لديه نطاق محلي. على عكس CLIs الخمسة الأخرى، OpenCode **لا يوجد لديها نظام hook أمر خارجي**: يتم تحميل المكونات الإضافية JS/TS داخل العملية بشكل صريح مسجلة عبر المصفوفة `plugin: []` في `opencode.json` (الاكتشاف التلقائي من `.opencode/plugins/` **ليس** كيفية تحميل المكونات الإضافية على opencode v1.14.33). التثبيت يسقط shimstone متولد صغير يسدد الثنائي failproofai ويترجم استجابة JSON الشكل Claude للثنائي مرة أخرى إلى دلالات المكون الإضافي: `throw new Error()` لـ deny حدث أداة (إلغاء استدعاء الأداة)، `client.session.prompt(...)` ل instruct و ل deny `Stop` / `SubagentStop` (يرسل سبب الرفض كرسالة المستخدم التالية — القناة الوحيدة لإعادة المحاولة القسرية لأن `session.idle` للإخطار فقط والرمي من البداية لا تغيير)، و no-op ل allow. يقوم الطراز بتطبيع أسماء الأدوات (lowercase → PascalCase عبر `OPENCODE_TOOL_MAP`) ومفاتيح إدخال الأداة (camelCase → snake_case عبر `OPENCODE_TOOL_INPUT_MAP` ل `Read` / `Write` / `Edit`، مثل `filePath` → `file_path`، `oldString` → `old_string`) قبل الإعادة إلى الثنائي، لذا فإن builtins التحقق من المسار مثل `block-read-outside-cwd`، `block-env-files`، و `block-secrets-write` تطلق دون تغيير على استدعاءات أداة OpenCode. الجلسات تعيش في قاعدة بيانات SQLite الخاصة بـ opencode في `~/.local/share/opencode/opencode.db`؛ عارض الجلسات في لوحة التحكم يقرأها عبر `opencode db --format json` و `opencode export `. دعم OpenCode هو **beta** بينما نتحقق من السلوك عبر الإصدارات ومقابل جلسات أكثر من الواقع. انظر [مستندات مكونات OpenCode الإضافية](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (مستخدم)، `/.pi/settings.json` (مشروع) — Pi ليس لديه نطاق محلي. يقوم Pi بتحميل حزم ملحقات TypeScript عند بدء التشغيل؛ ملف الإعدادات عبارة عن مصفوفة سلاسل مسطحة `{"packages": ["./relative/path", …]}`. يكتب failproofai مدخل مصفوفة packages واحد يشير إلى مجلد `pi-extension/` المجمع. الملحق داخلياً يشترك في أحداث Pi `tool_call` / `user_bash` / `input` / `session_start` ويقوم بـ shell out إلى `failproofai --hook --cli pi`؛ يقوم المعالج بتطبيع underscore_lower_snake_case → PascalCase عبر `PI_EVENT_MAP` بحيث تطلق السياسات المدمجة الموجودة دون تغيير. يتم تطبيع وسيطات إدخال الأداة أيضاً عبر `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit توصيل `path` بدلاً من `file_path`؛ تمكين المفتاح على المستوى الأعلى يسمح ل `block-env-files` و `block-secrets-write` بالإطلاق — `block-read-outside-cwd` كانت بالفعل تحتوي على fallback `path`). دعم Pi هو **beta** بينما تستقر واجهة برمجة تطبيقات تمديد Pi وتخطيط السجل على الجرم. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**نطاق المستخدم فقط** — Hermes ليس لديها تكوين مشروع/محلي). Hermes بوابة **Slack/Telegram**، لذا يعترض تثبيت واحد استدعاءات الأداة من كل منصة (Slack/Telegram/cli/cron) **و** وكلاء فرعيين داخليين. مدخلات Hook عبارة عن زوج `{command, timeout}` (انتظار بـ **ثوانٍ**) تحت خريطة `hooks:` مفتاح بأحداث Hermes snake_case (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`)؛ يقوم المعالج بتطبيع الأحداث عبر `HERMES_EVENT_MAP` وأسماء الأدوات عبر `HERMES_TOOL_MAP` بحيث تطلق السياسات المدمجة دون تغيير. يتم تحرير التكوين من خلال جولة `Document` YAML محفوظة بالتعليق حتى تنجو إعدادات المشغل الأخرى، والتثبيت يعين `hooks_auto_accept: true` بحيث تعمل البوابة بدون رأس (لا TTY) hooks بدون استثارة موافقة. يُصدر المقيّم عقد `{"decision":"block","reason"}` stdout الخاص بـ Hermes (يتجاهل Hermes أكواد الخروج). **القيود:** Hermes ليس لديها حدث نهاية دور `Stop`، لذا فإن builtins `require-*-before-stop` لم تطلق أبداً عليها (غير قابل للتطبيق، وليس معطوباً)؛ `instruct` تنخفض إلى السماح بسجل ملاحظة (لا قناة سياق إضافية)؛ وإعادة صياغة سر الإخراج (`sanitize-*`) لا يمكنها إعادة كتابة إخراج الأداة على عقد shell-hook. Hermes هو **أيضاً** مصدر تدقيق غير متصل — يقرأ لوحة التحكم جلسات البوابة الخاصة به مباشرة من `~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**نطاق المستخدم فقط** — OpenClaw ليس لديها تكوين مشروع/محلي). مثل Hermes، OpenClaw بوابة متعددة القنوات **ذاتية الاستضافة**، لذا يعترض تثبيت واحد استدعاءات الأداة من كل قناة ووكلائها الفرعيين الداخليين. الإنفاذ يعمل من خلال خطافات **داخل العملية** الخاصة بـ OpenClaw (الخطافات القائمة على الملفات الداخلية للملاحظة فقط ولا يمكنها الحجب)، لذا — مثل OpenCode/Pi — يشحن failproofai مجلد `openclaw-plugin/` ثابت يقوم بمكافحة مستنسخ ثنائي failproofai ويترجم الحكم. التثبيت يسجل مجلد المكون الإضافي المشحون في `openclaw.json` `plugins.load.paths[]` ويمكّنه تحت `plugins.entries.failproofai` (مع `hooks.allowConversationAccess: true`، مطلوب للخطافات الحوار الخام). يُصدر المقيّم حكم `{permission, reason}` مسطح ويحول الطراز إلى شكل عودة كل خطاف الأصلي: `before_tool_call → {block:true, blockReason}` (**PreToolUse**)، `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**)، و `before_agent_finalize → {action:"revise", reason}` (**Stop** — بوابة دور حقيقية، لذا builtins `require-*-before-stop` **تطبق** على OpenClaw، على عكس Hermes). الأحداث وأسماء الأدوات تطبيع جانب ثنائي عبر `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`، `read→Read`، …) بحيث تطلق السياسات المدمجة دون تغيير؛ الطراز فشل مفتوح على أي خطأ spawn/parse/timeout. OpenClaw هو **أيضاً** مصدر تدقيق غير متصل — يقرأ لوحة التحكم جلسات JSONL الخاصة به في `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (مستخدم)، `/.factory/hooks.json` (مشروع) — Factory ليس لديها نطاق محلي. يشحن droid نظام hook أمر خارجي على غرار Claude، لكن مع اثنين من الغريبة المؤكدة مباشرة ضد droid v0.171.0: (1) أسماء الأحداث تعيش في **المستوى الأعلى** من `hooks.json` — هناك **لا `"hooks"` حافظة** (droid يرفضها)؛ أحداث الأداة (`PreToolUse`/`PostToolUse`) حمل `"matcher": "*"`، أحداث غير الأداة تحذف. (2) الحجب يقوده hook **كود الخروج 2 + stderr**، وليس قرار JSON — فرع المقيّم `factory` يعود الخروج 2 لأحداث أداة/موجه و `{decision:"block", reason}` فقط على حدث نهاية الدور `Stop` (قناة إعادة المحاولة القسرية الوحيدة في droid). الأحداث بالفعل PascalCase (لا خريطة أحداث) والحمل Claude snake_case؛ فقط أسماء الأدوات تطبيع عبر `FACTORY_TOOL_MAP` (`Execute→Bash`، `Create→Write`، `FetchUrl→WebFetch`، …). Factory هو **أيضاً** مصدر تدقيق غير متصل — يقرأ لوحة التحكم جلسات JSONL على الجرم في `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (مستخدم)، `/.devin/config.json` (مشروع) — Devin ليس لديه نطاق محلي. Devin هو **نسخة Claude خالصة** مؤكدة مباشرة ضد devin v3000.1.27: إنه يستخدم مخطط محفوظ Claude القياسي `"hooks"` (الكتابات محفوظة الدمج بحيث تبقى المفاتيح الأخرى في ملف الإعدادات — `org_id`، `theme_mode`، … — تنجو)، أسماء الأحداث PascalCase بالفعل (لا خريطة أحداث، لا فرع معالج)، وحمل stdin Claude snake_case (لا تطبيع). فرع المقيّم `devin` يرفض مع `{"decision":"block","reason"}` JSON على stdout عند الخروج 0 لـ **كل** حدث (مؤكد — رفع الحجب تجاوز `--permission-mode dangerous`)؛ على حدث نهاية الدور `Stop` السبب يحمل صياغة إجراء إلزامي لإعادة المحاولة القسرية بحيث تطبق builtins `require-*-before-stop`. فقط أسماء الأدوات تطبيع عبر `DEVIN_TOOL_MAP` (`exec→Bash`؛ `tool_input.command` بالفعل قانوني). Devin هو **أيضاً** مصدر تدقيق غير متصل — يقرأ لوحة التحكم جلسات SQLite في `~/.local/share/devin/cli/sessions.db` (كل صف `sessions` يحمل حقيقي `working_directory`، بحيث تتجمع الجلسات حسب المشروع cwd مثل Claude). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (مستخدم)، `/.agents/hooks.json` (مشروع) — Antigravity ليس لديها نطاق محلي. على عكس Factory/Devin، Antigravity لديها **عقد خاص بها** (وليس نسخة Claude)، مؤكدة مباشرة ضد agy v1.1.2. `hooks.json` يستخدم مخطط **named-hook**: المفتاح على المستوى الأعلى هو اسم hook *name* (`"failproofai"`) قيمته خريطة event→handlers — أحداث الأداة (`PreToolUse`/`PostToolUse`) تلف المعالجات في `{matcher:"*", hooks:[…]}`، بينما `PreInvocation`/`Stop` هي مصفوفات معالج **مسطحة** (يتم الاحتفاظ بخطافات named الأخرى). حمل stdin هو **protojson camelCase** (`toolCall:{name,args}`، `conversationId`، `workspacePaths`، `transcriptPath`) — يطبع failproofai إلى snake_case قبل تشغيل السياسات، ويحول PascalCase args الخاصة بـ `run_command` (`CommandLine`/`Cwd`) عبر `ANTIGRAVITY_TOOL_INPUT_MAP`. فرع المقيّم `antigravity` يستخدم أشكال الاستجابة **الخاصة بـ Antigravity**: `{decision:"deny", reason}` يحجب أداة/موجه (الخروج 0)، `{decision:"continue", reason}` على حدث نهاية الدور `Stop` يعود إلى الحلقة (بحيث تطبق builtins `require-*-before-stop`)، و `{injectSteps:[{ephemeralMessage}]}` يحقن تعليماً على `PreInvocation` (→ `UserPromptSubmit`). أسماء الأدوات تطبيع عبر `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`، `view_file→Read`، …). Antigravity هو **أيضاً** مصدر تدقيق غير متصل — يقرأ لوحة التحكم نصوصه العادي-JSONL في `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (فهرس المحادثة في `conversation_summaries.db`). + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (مستخدم)، `/.agents/plugins/failproofai/hooks/hooks.json` (مشروع) — Goose ليس لديها نطاق محلي. الإنفاذ يستخدم نظام **hooks** الخاص بـ Goose، مواصفة **Open Plugins** عبر الوكيل: المثبت فقط يسقط مجلد المكون الإضافي `failproofai` وGoose auto-يكتشفها عند بدء التشغيل (تسجيل نفسها في `~/.config/goose/config.yaml`). `hooks.json` يستخدم مخطط Open Plugins **مع** حافظة `"hooks"` على المستوى الأعلى، والمطابق **حذفت** على كل حدث — فارغ `"*"` هو regex غير صالح لا يطابق شيء (مؤكد مباشرة ضد goose v1.43.0). أسماء الأحداث بالفعل PascalCase (لا خريطة أحداث)؛ حمل stdin يستخدم `event`/`working_dir`، الذي يطبعه المعالج إلى `hook_event_name`/`cwd`. فرع المقيّم `goose` يرفض مع `{"decision":"block","reason"}` JSON على stdout عند الخروج 0، يشرف على حدث **`PreToolUse`** فقط (شحنت في goose ≥ v1.37.0) — الذي ينطلق لأداة shell **وداخل وكلاء فرعيين مفوضين**، بحيث يكون نقطة الحجب الكافية الوحيدة؛ أي خطأ hook آخر فشل **مفتوح**. Goose ليس لديها حدث `Stop`**، بحيث لا ينطبق builtin `require-*-before-stop` (مثل Hermes). أسماء الأدوات تطبيع عبر `GOOSE_TOOL_MAP` (`shell→Bash`، `write→Write`، `todo__todo_write→TodoWrite`، …) ومفاتيح المسار عبر `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose هو **أيضاً** مصدر تدقيق غير متصل — يقرأ لوحة التحكم جلسات SQLite في `~/.local/share/goose/sessions/sessions.db` (كل صف `sessions` يحمل حقيقي `working_dir`، بحيث تتجمع الجلسات حسب cwd المشروع مثل Devin؛ يتم تصفية تشغيلات `--no-session` scratch). +- **`policies-config.json`** — يخبر failproofai السياسات التي يجب تقييمها والمعاملات (مشتركة عبر جميع CLIs للوكيل) + +مرر `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` لاستهداف وكيل معين (مفصولة بمسافة أو متكررة لأي مجموعة فرعية): ```bash failproofai policies --install --cli codex --scope project @@ -211,21 +217,26 @@ failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli hermes --scope user -failproofai policies --install --cli claude codex copilot cursor opencode pi +failproofai policies --install --cli openclaw --scope user +failproofai policies --install --cli factory --scope project +failproofai policies --install --cli devin --scope project +failproofai policies --install --cli antigravity --scope project +failproofai policies --install --cli goose --scope project +failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -عندما يتم حذف `--cli`، يكتشف failproofai عملاء الوكيل المثبتة (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`): +عند حذف `--cli`، يكتشف `failproofai` CLIs للوكيل المثبتة (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): -- **تم اكتشاف عميل واحد** — يختار ذلك العميل تلقائياً بدون فور. -- **عملاء متعددة مكتشفة** في محطة طرفية تفاعلية — يعرض موجه اختيار مفرد بمفاتيح الأسهم مجمع في قسم `Detected (N)` (مع صف إجمالي للتثبيت لكل عميل مكتشفة N + كل عميل مكتشفة بشكل فردي) وقسم `Not installed (M) · install hooks ahead of time` يسرد كل عميل مكتشفة مدعومة كخيار تثبيت آجل (↑↓ للتحريك، أدخل للاختيار، ^C للخروج). يعرض تدفق الإلغاء قسم Detected فقط. -- **عملاء متعددة مكتشفة** في تشغيل غير تفاعلي (CI، لا TTY) — يثبت لجميع العملاء المكتشفة بدون فور. -- **لم يتم اكتشاف أي** — ينخفض إلى `claude`، مع تحذير بأنه لم يتم العثور على ثنائي وكيل في PATH؛ أمر الخطاف لا يزال مكتوباً بحيث ينشط بمجرد تثبيت واحد. +- **CLI واحد يتم الكشف عنه** — يختار تلقائياً ذلك CLI بدون موجه. +- **CLIs متعددة يتم الكشف عنها** في محطة تفاعلية — يعرض موجه تحديد مفتاح سهم واحد مجمع في قسم `Detected (N)` (مع صف دالة مجمعة `Install for all N detected` + كل CLI مكتشف بشكل فردي) وقسم `Not installed (M) · install hooks ahead of time` يسرد كل CLI مدعوم غير مكتشف كخيار تثبيت إلى الأمام (↑↓ للتحرك، أدخل للاختيار، ^C للخروج). يعرض تدفق الإلغاء قسم Detected فقط. +- **CLIs متعددة يتم الكشف عنها** في تشغيل غير تفاعلي (CI، لا TTY) — يثبت لجميع CLIs المكتشفة بدون موجه. +- **بلا** — ينخفض إلى `claude`، مع تحذير بأن لا CLI للوكيل تم العثور عليه في PATH؛ أمر الخطاف لا يزال مكتوباً بحيث ينشط حالما تثبت واحد. -يمكنك تحرير `policies-config.json` مباشرة في أي وقت؛ التغييرات تصبح نافذة فوراً في حدث الخطاف التالي بدون حاجة إلى إعادة تشغيل. +يمكنك تحرير `policies-config.json` مباشرة في أي وقت؛ التغييرات تدخل حيز التنفيذ على الفور في حدث الخطاف التالي بدون الحاجة إلى إعادة تشغيل. --- -## مثال: إعدادات على مستوى المشروع مع إعدادات افتراضية للفريق +## مثال: إعداد على مستوى المشروع مع افتراضيات الفريق التزم `.failproofai/policies-config.json` بمستودعك: @@ -246,4 +257,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi } ``` -يمكن لكل مطور بعد ذلك إنشاء `.failproofai/policies-config.local.json` (مستبعد من git) لتجاوزات شخصية بدون التأثير على زملائك. \ No newline at end of file +يمكن لكل مطور بعد ذلك إنشاء `.failproofai/policies-config.local.json` (gitignored) لتجاوزات شخصية دون التأثير على زملاء الفريق. \ No newline at end of file diff --git a/docs/ar/custom-policies.mdx b/docs/ar/custom-policies.mdx index cb5f7749..0ec8d9e3 100644 --- a/docs/ar/custom-policies.mdx +++ b/docs/ar/custom-policies.mdx @@ -1,10 +1,11 @@ --- +--- title: السياسات المخصصة -description: "اكتب سياساتك الخاصة في JavaScript - فرض الاتفاقيات، منع الانجراف، كشف الأعطال، التكامل مع الأنظمة الخارجية" +description: "اكتب قواعدك الخاصة في JavaScript - فرض المعايير، منع الانجراف، كشف الأعطال، التكامل مع الأنظمة الخارجية" icon: code --- -تتيح لك السياسات المخصصة كتابة قواعد لأي سلوك وكيل: فرض اتفاقيات المشروع، منع الانجراف، إغلاق العمليات المدمرة، كشف الوكلاء العالقين، أو التكامل مع Slack وسير عمل الموافقة وغير ذلك. تستخدم نفس نظام أحداث الخطاف وقرارات `allow` و `deny` و `instruct` التي تستخدمها السياسات المدمجة. +تتيح لك السياسات المخصصة كتابة قواعد لأي سلوك وكيل: فرض معايير المشروع، منع الانجراف، التحكم في العمليات المدمرة، كشف الوكلاء العالقين، أو التكامل مع Slack وسير العمل والموافقات وغيرها. فهي تستخدم نفس نظام حدث الخطافات وقرارات `allow` و `deny` و `instruct` المدمجة في السياسات المدمجة. --- @@ -39,50 +40,55 @@ failproofai policies --install --custom ./my-policies.js ## طريقتان لتحميل السياسات المخصصة -### الخيار 1: المستند على الاتفاقية (موصى به) +### الخيار 1: المبني على الاتفاقية (موصى به) -ضع ملفات `*policies.{js,mjs,ts}` في `.failproofai/policies/` وسيتم تحميلها تلقائياً — لا تحتاج إلى أعلام أو تغييرات إعدادات. يعمل هذا مثل git hooks: ضع ملفاً وبالتالي يعمل. +ضع ملفات `*policies.{js,mjs,ts}` في `.failproofai/policies/` وسيتم تحميلها تلقائياً — لا توجد أعلام أو تغييرات في الإعدادات المطلوبة. يعمل هذا مثل git hooks: ضع ملفاً، ويعمل ببساطة. ``` -# مستوى المشروع — يتم الالتزام به على git، مشاركته مع الفريق +# Project level — committed to git, shared with the team .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# مستوى المستخدم — شخصي، ينطبق على جميع المشاريع +# User level — personal, applies to all projects ~/.failproofai/policies/my-policies.mjs ``` **كيف يعمل:** -- يتم فحص كلا المديرين (الدمج — وليس first-scope-wins) -- يتم تحميل الملفات أبجدياً ضمن كل دليل. استخدم البادئة `01-` و `02-` للتحكم في الترتيب +- يتم مسح كلا المجلدين (الاتحاد — وليس النطاق الأول فقط) +- يتم تحميل الملفات أبجدياً داخل كل مجلد. استخدم البادئة `01-` أو `02-` للتحكم في الترتيب - يتم تحميل الملفات التي تطابق `*policies.{js,mjs,ts}` فقط؛ يتم تجاهل الملفات الأخرى -- يتم تحميل كل ملف بشكل مستقل (fail-open لكل ملف) +- يتم تحميل كل ملف بشكل مستقل (فتح فاشل لكل ملف) - يعمل جنباً إلى جنب مع السياسات الصريحة `--custom` والسياسات المدمجة -سياسات الاتفاقية هي الطريقة الأسهل لبناء معيار جودة لمؤسستك. التزم `.failproofai/policies/` إلى git وكل عضو في الفريق يحصل على نفس القواعد تلقائياً — لا حاجة لإعداد لكل مطور. مع اكتشاف فريقك لأنماط فشل جديدة، أضف سياسة وادفع. بمرور الوقت تصبح هذه معيار جودة حي يتحسن باستمرار مع كل مساهمة. +سياسات الاتفاقية هي أسهل طريقة لبناء معيار جودة لمنظمتك. اجعل `.failproofai/policies/` في git وسيحصل كل عضو في الفريق على نفس القواعد تلقائياً — لا توجد عملية إعداد لكل مطور. مع اكتشاف فريقك لأنماط فشل جديدة، أضف سياسة وادفع. بمرور الوقت، تصبح هذه معيار جودة حي يتحسن مع كل مساهمة. ### الخيار 2: مسار الملف الصريح ```bash -# التثبيت مع ملف سياسات مخصص +# Install with a custom policies file failproofai policies --install --custom ./my-policies.js -# استبدال مسار ملف السياسات +# Replace the custom policy paths failproofai policies --install --custom ./new-policies.js -# إزالة مسار السياسات المخصصة من الإعدادات +# Configure multiple explicit files (loaded in flag order) +failproofai policies --install --custom ./security.js --custom ./workflow.js + +# Remove all explicit custom policy paths from config failproofai policies --uninstall --custom ``` -يتم تخزين المسار المطلق الذي تم حله في `policies-config.json` باسم `customPoliciesPath`. يتم تحميل الملف بشكل جديد في كل حدث خطاف - لا يوجد caching بين الأحداث. +يتم تخزين المسارات المطلقة المحلولة في `policies-config.json` باسم `customPoliciesPaths`. كرر `--custom` لتكوين ملفات متعددة. تستمر الإعدادات الموجودة التي تستخدم الحقل `customPoliciesPath` القديم في العمل. يتم تحميل الملفات بشكل جديد في كل حدث خطاف — لا يوجد تخزين مؤقت بين الأحداث. + +تظهر كل سياسة مسجلة مع مفتاح التبديل الخاص بها في لوحة التحكم. سيؤدي إيقاف السياسة إلى تسجيل معرّف مؤهل المصدر في `disabledCustomPolicies`؛ يستمر الملف وسياساته الأخرى في التحميل، بينما يتم استبعاد السياسة المعطلة قبل مطابقة الحدث. لأسماء السياسات المكررة عبر الملفات تبديلات مستقلة. ### استخدام كليهما معاً -يمكن للسياسات المستندة على الاتفاقية والملف الصريح `--custom` أن يتعايشا. ترتيب التحميل: +يمكن لسياسات الاتفاقية وملفات `--custom` الصريحة أن توجد معاً. ترتيب التحميل: -1. ملف `customPoliciesPath` الصريح (إن تم تكوينه) +1. ملفات `customPoliciesPaths` الصريحة (بالترتيب المكون) 2. ملفات اتفاقية المشروع (`{cwd}/.failproofai/policies/`، أبجدي) 3. ملفات اتفاقية المستخدم (`~/.failproofai/policies/`، أبجدي) @@ -98,45 +104,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -تسجيل سياسة. استدعِ هذا عدة مرات حسب الحاجة لسياسات متعددة في نفس الملف. +تسجل سياسة. استدعِ هذا عدة مرات حسب الحاجة لسياسات متعددة في نفس الملف. ```ts customPolicies.add({ - name: string; // مطلوب - معرّف فريد - description?: string; // موضح في مخرجات `failproofai policies` - match?: { events?: HookEventType[] }; // تصفية حسب نوع الحدث؛ احذف لمطابقة الكل + name: string; // required - unique identifier + description?: string; // shown in `failproofai policies` output + match?: { events?: HookEventType[] }; // filter by event type; omit to match all fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` ### مساعدات القرار -| الدالة | التأثير | الاستخدام عندما | +| الدالة | التأثير | الاستخدام | |----------|--------|----------| -| `allow()` | السماح بالعملية بصمت | الإجراء آمن، لا حاجة لرسالة | -| `deny(message)` | حظر العملية | يجب ألا يتخذ الوكيل هذا الإجراء | -| `instruct(message)` | إضافة سياق بدون حظر | إعطاء الوكيل سياقاً إضافياً للبقاء على المسار | +| `allow()` | السماح بالعملية بدون تحذير | الإجراء آمن، لا توجد رسالة مطلوبة | +| `deny(message)` | حجب العملية | يجب ألا يتخذ الوكيل هذا الإجراء | +| `instruct(message)` | إضافة السياق بدون حجب | أعطِ الوكيل سياقاً إضافياً للبقاء على المسار الصحيح | -`deny(message)` - تظهر الرسالة أمام Claude مع البادئة `Blocked by failproofai:`. رفض واحد يختصر كل التقييم الإضافي. +`deny(message)` - تظهر الرسالة لـ Claude مع البادئة `"Blocked by failproofai:"`. يؤدي `deny` واحد إلى اختصار كل التقييم الإضافي. -`instruct(message)` - يتم إلحاق الرسالة بسياق Claude لاستدعاء الأداة الحالي. يتم تجميع جميع رسائل `instruct` وتسليمها معاً. +`instruct(message)` - يتم إضافة الرسالة إلى سياق Claude لاستدعاء الأداة الحالية. يتم تجميع كل رسائل `instruct` وتسليمها معاً. -يمكنك إلحاق إرشادات إضافية برسالة `deny` أو `instruct` بإضافة حقل `hint` في `policyParams` — لا حاجة لتغيير الكود. يعمل هذا للسياسات المخصصة (`custom/`)، واتفاقية المشروع (`.failproofai-project/`)، واتفاقية المستخدم (`.failproofai-user/`) أيضاً. انظر [التكوين → hint](/ar/configuration#hint-cross-cutting) للتفاصيل. +يمكنك إضافة إرشادات إضافية لأي رسالة `deny` أو `instruct` بإضافة حقل `hint` في `policyParams` — لا توجد حاجة لتغيير الكود. يعمل هذا أيضاً مع سياسات المخصص (`custom/`) واتفاقية المشروع (`.failproofai-project/`) واتفاقية المستخدم (`.failproofai-user/`). انظر [الإعدادات → hint](/ar/configuration#hint-cross-cutting) للتفاصيل. ### رسائل السماح المعلوماتية -`allow(message)` يسمح بالعملية **و** يرسل رسالة معلوماتية مرة أخرى إلى Claude. يتم تسليم الرسالة كـ `additionalContext` في استجابة stdout معالج الخطاف — نفس الآلية المستخدمة من قبل `instruct`، لكن بشكل معنوي مختلف: إنها تحديث حالة، وليس تحذيراً. +`allow(message)` تسمح بالعملية **و** ترسل رسالة معلومات إلى Claude. يتم تسليم الرسالة باسم `additionalContext` في استجابة stdout لمعالج الخطاف — نفس الآلية المستخدمة بواسطة `instruct`، لكن مختلفة دلالياً: إنها تحديث حالة، وليست تحذير. -| الدالة | التأثير | الاستخدام عندما | +| الدالة | التأثير | الاستخدام | |----------|--------|----------| -| `allow(message)` | السماح وإرسال السياق إلى Claude | تأكيد نجاح فحص، أو شرح سبب تخطي فحص | +| `allow(message)` | السماح وإرسال السياق إلى Claude | تأكيد فحص نجح، أو شرح سبب تخطي الفحص | حالات الاستخدام: -- **تأكيدات الحالة:** `allow("All CI checks passed.")` — أخبر Claude أن كل شيء أخضر -- **شروحات fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — أخبر Claude لماذا تم تخطي فحص حتى يكون لديه السياق الكامل -- **تراكم الرسائل المتعددة:** إذا أرجعت عدة سياسات `allow(message)`، يتم دمج جميع الرسائل بأسطر جديدة وتسليمها معاً +- **تأكيدات الحالة:** `allow("All CI checks passed.")` — يخبر Claude أن كل شيء صحيح +- **شروح الفتح الفاشل:** `allow("GitHub CLI not installed, skipping CI check.")` — يخبر Claude لماذا تم تخطي الفحص بحيث يكون لديه سياق كامل +- **تجميع الرسائل المتعددة:** إذا أعادت عدة سياسات `allow(message)`، يتم دمج جميع الرسائل بفواصل أسطر وتسليمها معاً ```js customPolicies.add({ @@ -159,10 +165,10 @@ customPolicies.add({ | الحقل | النوع | الوصف | |-------|------|-------------| -| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | +| `eventType` | `string` | `"PreToolUse"`، `"PostToolUse"`، `"Notification"`، `"Stop"` | | `toolName` | `string \| undefined` | الأداة التي يتم استدعاؤها (مثل `"Bash"`، `"Write"`، `"Read"`) | -| `toolInput` | `Record \| undefined` | معاملات إدخال الأداة | -| `payload` | `Record` | حمل الحدث الخام الكامل من Claude Code | +| `toolInput` | `Record \| undefined` | معاملات الإدخال للأداة | +| `payload` | `Record` | حمولة الحدث الخام الكاملة من Claude Code | | `session` | `SessionMetadata \| undefined` | سياق الجلسة (انظر أدناه) | ### حقول `SessionMetadata` @@ -171,15 +177,15 @@ customPolicies.add({ |-------|------|-------------| | `sessionId` | `string` | معرّف جلسة Claude Code | | `cwd` | `string` | مجلد العمل لجلسة Claude Code | -| `transcriptPath` | `string` | مسار ملف النسخ الكاملة JSONL للجلسة | +| `transcriptPath` | `string` | المسار إلى ملف النقل JSONL للجلسة | ### أنواع الأحداث -| الحدث | متى يتم تشغيله | محتويات `toolInput` | +| الحدث | متى يطلق | محتويات `toolInput` | |-------|--------------|----------------------| -| `PreToolUse` | قبل تشغيل Claude لأداة | إدخال الأداة (مثل `{ command: "..." }` لـ Bash) | -| `PostToolUse` | بعد اكتمال أداة | إدخال الأداة + `tool_result` (الإخراج) | -| `Notification` | عندما يرسل Claude إشعاراً | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - يجب أن تُرجع الخطافات دائماً `allow()`، لا يمكنها حظر الإشعارات | +| `PreToolUse` | قبل أن يقوم Claude بتشغيل أداة | إدخال الأداة (مثل `{ command: "..." }` لـ Bash) | +| `PostToolUse` | بعد اكتمال الأداة | إدخال الأداة + `tool_result` (الإخراج) | +| `Notification` | عندما يرسل Claude إخطاراً | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - يجب أن تعود الخطافات دائماً `allow()`، لا يمكنها حجب الإخطارات | | `Stop` | عند انتهاء جلسة Claude | فارغ | --- @@ -190,18 +196,18 @@ customPolicies.add({ 1. السياسات المدمجة (بترتيب التعريف) 2. السياسات المخصصة الصريحة من `customPoliciesPath` (بترتيب `.add()`) -3. سياسات الاتفاقية من `.failproofai/policies/` للمشروع (الملفات أبجدياً، بترتيب `.add()` بداخلها) -4. سياسات الاتفاقية من `~/.failproofai/policies/` للمستخدم (الملفات أبجدياً، بترتيب `.add()` بداخلها) +3. سياسات الاتفاقية من المشروع `.failproofai/policies/` (ملفات أبجدية، ترتيب `.add()` داخل) +4. سياسات الاتفاقية من المستخدم `~/.failproofai/policies/` (ملفات أبجدية، ترتيب `.add()` داخل) -أول رفض `deny` يختصر جميع السياسات اللاحقة. يتم تجميع جميع رسائل `instruct` وتسليمها معاً. +يؤدي أول `deny` إلى اختصار جميع السياسات اللاحقة. يتم تجميع جميع رسائل `instruct` وتسليمها معاً. --- -## الاستيرادات المتعدية +## الاستيرادات الانتقالية -يمكن لملفات السياسات المخصصة استيراد وحدات محلية باستخدام مسارات نسبية: +يمكن لملفات السياسات المخصصة استيراد الوحدات المحلية باستخدام المسارات النسبية: ```js // my-policies.js @@ -218,46 +224,46 @@ customPolicies.add({ }); ``` -يتم حل جميع الاستيرادات النسبية التي يمكن الوصول إليها من ملف الإدخال. يتم تنفيذ هذا بإعادة كتابة استيرادات `from "failproofai"` إلى مسار dist الفعلي وإنشاء ملفات `.mjs` مؤقتة لضمان التوافقية ESM. +يتم حل جميع الواردات النسبية التي يمكن الوصول إليها من ملف الإدخال. يتم تنفيذ هذا بإعادة كتابة استيرادات `from "failproofai"` إلى مسار dist الفعلي وإنشاء ملفات `.mjs` مؤقتة لضمان توافق ESM. --- ## تصفية نوع الحدث -استخدم `match.events` لتحديد متى يتم تشغيل السياسة: +استخدم `match.events` للحد من وقت تطلق السياسة: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // يتم التشغيل فقط عند انتهاء الجلسة - // ctx.session.transcriptPath يحتوي على سجل الجلسة الكامل + // Only fires when the session ends + // ctx.session.transcriptPath contains the full session log return allow(); }, }); ``` -احذف `match` بالكامل للتشغيل على كل نوع حدث. +حذف `match` بالكامل لتطلق في كل نوع حدث. --- ## معالجة الأخطاء وأنماط الفشل -السياسات المخصصة **fail-open**: الأخطاء لا تحظر السياسات المدمجة أو تعطل معالج الخطاف. +السياسات المخصصة **فتح فاشل**: الأخطاء لا تحجب السياسات المدمجة أو تتعطل معالج الخطاف. | الفشل | السلوك | |---------|----------| -| `customPoliciesPath` غير محدد | لا تعمل السياسات المخصصة الصريحة؛ تستمر السياسات المدمجة والاتفاقية بشكل طبيعي | -| الملف غير موجود | تحذير مسجل إلى `~/.failproofai/hook.log`؛ تستمر السياسات المدمجة | -| خطأ بناء الجملة/الاستيراد (صريح) | خطأ مسجل إلى `~/.failproofai/hook.log`؛ السياسات المخصصة الصريحة متخطاة | -| خطأ بناء الجملة/الاستيراد (اتفاقية) | خطأ مسجل؛ هذا الملف متخطى، الملفات الأخرى تحمل بشكل طبيعي | -| `fn` يرمي في وقت التشغيل | خطأ مسجل؛ يتم التعامل مع هذا الخطاف كـ `allow`؛ يستمر الخطافات الأخرى | -| `fn` يستغرق أكثر من 10 ثواني | انتهاء وقت مسجل؛ معامل كـ `allow` | -| دليل الاتفاقية مفقود | لا تعمل سياسات الاتفاقية؛ لا خطأ | +| `customPoliciesPath` لم يتم تعيينه | لا تعمل سياسات مخصصة صريحة؛ تستمر السياسات المدمجة والاتفاقية بشكل طبيعي | +| الملف غير موجود | يتم تسجيل التحذير إلى `~/.failproofai/hook.log`؛ تستمر المدمجة | +| خطأ بناء الجملة/الاستيراد (صريح) | يتم تسجيل الخطأ إلى `~/.failproofai/hook.log`؛ يتم تخطي السياسات المخصصة الصريحة | +| خطأ بناء الجملة/الاستيراد (اتفاقية) | يتم تسجيل الخطأ؛ يتم تخطي ذلك الملف، لا تزال الملفات الأخرى تحمل | +| `fn` يرمي في الوقت الفعلي | يتم تسجيل الخطأ؛ يتم التعامل مع هذا الخطاف مثل `allow`؛ تستمر الخطافات الأخرى | +| `fn` يستغرق أطول من 10 ثوان | يتم تسجيل انقطاع المهلة الزمنية؛ يتم التعامل مثل `allow` | +| مجلد الاتفاقية مفقود | لا تعمل سياسات الاتفاقية؛ لا خطأ | -لتصحيح أخطاء السياسات المخصصة، راقب ملف السجل: +لتصحيح أخطاء السياسة المخصصة، اراقب ملف السجل: ```bash tail -f ~/.failproofai/hook.log @@ -272,7 +278,7 @@ tail -f ~/.failproofai/hook.log // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// منع الوكيل من الكتابة إلى دليل secrets/ +// Prevent agent from writing to secrets/ directory customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -285,7 +291,7 @@ customPolicies.add({ }, }); -// إبقاء الوكيل على المسار: التحقق من الاختبارات قبل الالتزام +// Keep the agent on track: verify tests before committing customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +306,7 @@ customPolicies.add({ }, }); -// منع تغييرات المكتبات غير المخطط لها أثناء فترة التجميد +// Prevent unplanned dependency changes during freeze customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -321,16 +327,16 @@ export { customPolicies }; --- -## أمثلة +## الأمثلة -يحتوي دليل `examples/` على ملفات سياسات جاهزة للتشغيل: +يحتوي مجلد `examples/` على ملفات سياسات جاهزة للتشغيل: | الملف | المحتويات | |------|----------| -| `examples/policies-basic.js` | خمس سياسات مبدئية تغطي أنماط فشل الوكيل الشائعة | -| `examples/policies-advanced/index.js` | أنماط متقدمة: استيرادات متعدية، استدعاءات غير متزامنة، كشط الإخراج، وخطافات نهاية الجلسة | -| `examples/convention-policies/security-policies.mjs` | سياسات أمان مستندة على الاتفاقية (حظر كتابات .env، منع إعادة كتابة سجل git) | -| `examples/convention-policies/workflow-policies.mjs` | سياسات سير عمل مستندة على الاتفاقية (تذكيرات الاختبار، ملفات التدقيق الكتابة) | +| `examples/policies-basic.js` | خمس سياسات بدء تشغيل تغطي أنماط فشل الوكيل الشائعة | +| `examples/policies-advanced/index.js` | أنماط متقدمة: الواردات الانتقالية، الاستدعاءات غير المتزامنة، تنظيف الإخراج، والخطافات الخاصة بنهاية الجلسة | +| `examples/convention-policies/security-policies.mjs` | سياسات أمان مبنية على الاتفاقية (حجب كتابة .env، منع إعادة كتابة سجل git) | +| `examples/convention-policies/workflow-policies.mjs` | سياسات سير العمل المبنية على الاتفاقية (تذكيرات الاختبار، كتابة ملفات التدقيق) | ### استخدام أمثلة الملفات الصريحة @@ -338,14 +344,14 @@ export { customPolicies }; failproofai policies --install --custom ./examples/policies-basic.js ``` -### استخدام أمثلة مستندة على الاتفاقية +### استخدام أمثلة مبنية على الاتفاقية ```bash -# نسخ إلى مستوى المشروع +# Copy to project level mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# أو نسخ إلى مستوى المستخدم +# Or copy to user level mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` diff --git a/docs/ar/dashboard.mdx b/docs/ar/dashboard.mdx index bc7e94f0..ff9951b9 100644 --- a/docs/ar/dashboard.mdx +++ b/docs/ar/dashboard.mdx @@ -1,10 +1,11 @@ --- +--- title: لوحة التحكم description: "مراقبة جلسات الوكيل، ومراجعة استدعاءات الأدوات، وإدارة السياسات" icon: chart-line --- -لوحة تحكم failproofai هي تطبيق ويب محلي لمراقبة جلسات وكيل الذكاء الاصطناعي لديك وإدارة السياسات. شاهد ما فعلته وكلاؤك أثناء غيابك. +لوحة التحكم في failproofai هي تطبيق ويب محلي لمراقبة جلسات وكيل الذكاء الاصطناعي الخاص بك وإدارة السياسات. شاهد ما فعله وكلاؤك أثناء غيابك. --- @@ -14,9 +15,9 @@ icon: chart-line failproofai ``` -يتم فتحها على `http://localhost:8020`. +يفتح على `http://localhost:8020`. -تقرأ لوحة التحكم بيانات المشروع المحلية والجلسات وبيانات تكوين failproofai مباشرة من نظام الملفات. الميزات المصادقة الاختيارية، مثل تذكيرات التدقيق والدعوات، ترسل المعلومات المطلوبة لتلك الطلبات (بما في ذلك عناوين البريد الإلكتروني) إلى واجهات برمجية بعيدة. +تقرأ لوحة التحكم بيانات المشروع والجلسة وإعدادات failproofai المحلية مباشرة من نظام الملفات. تُرسل الميزات المصادقة الاختيارية، مثل تذكيرات التدقيق والدعوات، المعلومات المطلوبة لتلك الطلبات (بما في ذلك عناوين البريد الإلكتروني) إلى واجهات برمجية بعيدة. --- @@ -24,97 +25,99 @@ failproofai ### المشاريع -يسرد جميع مشاريع Claude Code و OpenAI Codex و GitHub Copilot CLI _(beta)_ و Cursor Agent _(beta)_ و OpenCode _(beta)_ و Pi _(beta)_ و Hermes و OpenClaw و Factory Droid و Devin و Antigravity و Goose الموجودة على جهازك. يتم اكتشاف مشاريع Claude من `~/.claude/projects/` (أو المسار المحدد بواسطة `CLAUDE_PROJECTS_PATH`); يتم اكتشاف مشاريع Codex من خلال مسح كل نسخة أصلية ضمن `~/.codex/sessions///
/*.jsonl` وتجميعها حسب `cwd` المسجل في السجل الأول لكل جلسة; يتم اكتشاف مشاريع Copilot CLI من خلال مسح كل `~/.copilot/session-state//workspace.yaml` (قابلة للتكوين عبر `COPILOT_HOME`) وتجميعها حسب حقل `cwd`; يتم اكتشاف مشاريع Cursor Agent من خلال مسح البيانات الوصفية لكل جلسة ضمن `~/.cursor/agent-sessions//` (قابلة للتكوين عبر `CURSOR_HOME`، مع المسح بحثاً عن `conversations/` و `sessions/` كخيارات بديلة) للبحث عن كمية عددية `cwd` في `meta.json` / `session.json` / `workspace.yaml`; يتم اكتشاف مشاريع OpenCode من خلال الاستعلام عن قاعدة بيانات SQLite الخاصة بها على `~/.local/share/opencode/opencode.db` عبر `opencode db --format json` (نحن نقرأ جداول `session` و `project` ونجمعها حسب `project_id`); يتم اكتشاف مشاريع Pi من خلال مسح نصوص JSONL لكل جلسة ضمن `~/.pi/agent/sessions//_.jsonl` (قابلة للتكوين عبر `PI_SESSIONS_DIR`) وسحب `cwd` من السجل الأول لكل جلسة; يتم قراءة جلسات بوابة Hermes مباشرة من متجرها SQLite على `~/.hermes/state.db` (قابلة للتكوين عبر `HERMES_DB_PATH`) وتجميعها في مشاريع `hermes-` حسب `source` (Slack/Telegram/cli/cron — جلسات البوابة لا تحتوي على cwd); يتم قراءة جلسات بوابة OpenClaw من `~/.openclaw/agents//sessions/*.jsonl` وتجميعها في مشاريع `openclaw-` (أيضاً بدون cwd); يتم اكتشاف مشاريع Factory Droid من نصوص JSONL على `~/.factory/sessions//*.jsonl` وتجميعها حسب cwd; مشاريع Devin من قاعدة بيانات SQLite الخاصة بها على `~/.local/share/devin/cli/sessions.db` (مجمعة حسب `working_directory` لكل جلسة); مشاريع Antigravity من نصوص JSONL على `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` وتجميعها حسب cwd; ومشاريع Goose من قاعدة بيانات SQLite الخاصة بها على `~/.local/share/goose/sessions/sessions.db` (مجمعة حسب `working_dir` لكل جلسة). يتم عرض المشروع الذي استخدمته واجهات برمجية متعددة كصف واحد مع جميع الشارات المطابقة. استخدم القائمة المنسدلة **CLI** فوق الجدول للتصفية حسب واجهة برمجية وكيل محددة; يحافظ عنوان URL على اختيارك كـ `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +يسرد جميع مشاريع Claude Code و OpenAI Codex و GitHub Copilot CLI _(beta)_ و Cursor Agent _(beta)_ و OpenCode _(beta)_ و Pi _(beta)_ و Hermes و OpenClaw و Factory Droid و Devin و Antigravity و Goose الموجودة على جهازك. يتم اكتشاف مشاريع Claude من `~/.claude/projects/` (أو المسار المحدد بـ `CLAUDE_PROJECTS_PATH`)؛ يتم اكتشاف مشاريع Codex بفحص كل النصوص تحت `~/.codex/sessions///
/*.jsonl` وتجميعها حسب `cwd` المسجل في السجل الأول لكل جلسة؛ يتم اكتشاف مشاريع Copilot CLI بفحص كل `~/.copilot/session-state//workspace.yaml` (قابل للتكوين عبر `COPILOT_HOME`) وتجميعها حسب حقل `cwd`؛ يتم اكتشاف مشاريع Cursor Agent بفحص البيانات الوصفية لكل جلسة تحت `~/.cursor/agent-sessions//` (قابل للتكوين عبر `CURSOR_HOME`، مع اختبار `conversations/` و `sessions/` كبدائل) بحثاً عن قيمة `cwd` في `meta.json` / `session.json` / `workspace.yaml`؛ يتم اكتشاف مشاريع OpenCode من خلال الاستعلام عن قاعدة بيانات SQLite الخاصة به على `~/.local/share/opencode/opencode.db` عبر `opencode db --format json` (نقرأ جداول `session` و `project` ونجمعها حسب `project_id`)؛ يتم اكتشاف مشاريع Pi بفحص نسخ JSONL لكل جلسة تحت `~/.pi/agent/sessions//_.jsonl` (قابل للتكوين عبر `PI_SESSIONS_DIR`) واستخراج `cwd` من السجل الأول لكل جلسة؛ يتم قراءة جلسات بوابة Hermes مباشرة من مخزن SQLite لكل ملف تعريف — `~/.hermes/state.db` بالإضافة إلى `~/.hermes/profiles//state.db` (قابل للتجاوز عبر `HERMES_HOME` أو `HERMES_DB_PATH` لقاعدة بيانات واحدة) — وتجميعها في مشاريع `hermes--` حسب الملف الشخصي و `source` (Slack/Telegram/cli/cron — جلسات البوابة بدون cwd)؛ يتم قراءة جلسات بوابة OpenClaw من `~/.openclaw/agents//sessions/*.jsonl` وتجميعها في مشاريع `openclaw--` حسب الوكيل والقناة (بدون cwd أيضاً)؛ يتم اكتشاف مشاريع Factory Droid من نصوص JSONL في `~/.factory/sessions//*.jsonl` وتجميعها حسب cwd؛ مشاريع Devin من قاعدة بيانات SQLite الخاصة بها في `~/.local/share/devin/cli/sessions.db` (مجمعة حسب `working_directory` لكل جلسة)؛ مشاريع Antigravity من نصوص JSONL في `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` وتجميعها حسب cwd؛ ومشاريع Goose من قاعدة بيانات SQLite الخاصة بها في `~/.local/share/goose/sessions/sessions.db` (مجمعة حسب `working_dir` لكل جلسة). يظهر المشروع الذي استُخدم بواسطة عدة CLIs كصف واحد مع جميع الشارات المتطابقة. استخدم القائمة المنسدلة **CLI** فوق الجدول لتصفية حسب CLI وكيل معين؛ يحتفظ الرابط باختيارك كـ `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. + +Hermes و OpenClaw محدودة بنطاق المستخدم وليس لديها دليل عمل للتجميع حسبه، لذا تظهران كـ **شجرة مجلدات قابلة للطي** — الملف الشخصي (أو الوكيل) على المستوى الأعلى، قنواته تحتها — بينما يبقى كل CLI قائم على cwd صفاً مسطحاً. تجمع صفوف المجلدات عدد الجلسات والنشاط الأكثر حداثة لكل شيء تحتها، والمجلدات المطويّة يتم تذكرها بين الزيارات، والبحث عن كلمات رئيسية يوسع أي شيء يتطابق معه. يعرض كل مشروع: - اسم المشروع (مشتق من مسار المجلد) -- شارة CLI — `Claude Code` (برتقالي)، `OpenAI Codex` (بنفسجي)، `GitHub Copilot` (أزرق)، `Cursor Agent` (أخضر زمردي)، `OpenCode` (كهرماني)، `Pi` (وردي)، و/أو `Hermes` (نيلي) -- تاريخ أحدث نشاط جلسة +- شارة CLI — `Claude Code` (برتقالي)، `OpenAI Codex` (بنفسجي)، `GitHub Copilot` (أزرق)، `Cursor Agent` (زمردي)، `OpenCode` (عنبري)، `Pi` (وردي)، و/أو `Hermes` (نيلي) +- تاريخ نشاط الجلسة الأكثر حداثة انقر على مشروع لرؤية جلساته. ### الجلسات -يسرد جميع الجلسات ضمن مشروع. تعرض كل جلسة: +يسرد جميع الجلسات داخل مشروع. تعرض كل جلسة: - معرّف الجلسة -- الطوابع الزمنية للبداية والنهاية +- طوابع زمنية البداية والنهاية - عدد استدعاءات الأدوات -- عدد أنشطة Hook (السياسات التي تم تشغيلها) +- عدد نشاط السنّارة (السياسات التي تم تفعيلها) -استخدم مرشح نطاق التاريخ والبحث عن معرّف الجلسة لتضييق القائمة. يتم ترقيم الجلسات. +استخدم مرشح نطاق التاريخ وبحث معرّف الجلسة لتضييق القائمة. الجلسات مقسمة إلى صفحات. انقر على جلسة لفتح عارض الجلسة. ### عارض الجلسة -يجيب عارض الجلسة على السؤال الرئيسي للوكلاء المستقلين: ماذا فعل الوكيل، وهل بقي على المسار الصحيح؟ تشير شارة CLI بجوار الرأس إلى ما إذا كانت الجلسة نسخة أصلية من Claude Code أو OpenAI Codex أو GitHub Copilot CLI أو Cursor Agent أو OpenCode أو Pi أو Hermes أو OpenClaw أو Factory Droid أو Devin أو Antigravity أو Goose. يظهر خط زمني لكل ما حدث في الجلسة: +يجيب عارض الجلسة على السؤال الرئيسي للوكلاء المستقلين: ماذا فعل الوكيل، وهل بقي على المسار الصحيح؟ شارة CLI بجانب الرأس تشير إلى ما إذا كانت الجلسة نسخة Claude Code أم OpenAI Codex أم GitHub Copilot CLI أم Cursor Agent أم OpenCode أم Pi أم Hermes أم OpenClaw أم Factory Droid أم Devin أم Antigravity أم Goose. يعرض جدول زمني لكل ما حدث في جلسة: -- **الرسائل** - استجابات Claude النصية وتوجيهات المستخدم -- **استدعاءات الأدوات** - كل أداة استدعاها Claude، مع إدخالها وإخراجها -- **نشاط السياسة** - لكل استدعاء أداة، السياسات التي تم تشغيلها والقرار الذي أرجعته +- **الرسائل** - استجابات Claude النصية وطلبات المستخدم +- **استدعاءات الأدوات** - كل أداة استدعاها Claude، مع مدخلاتها ومخرجاتها +- **نشاط السياسة** - لكل استدعاء أداة، السياسات التي تم تفعيلها والقرار الذي أرجعته -يعرض شريط الإحصائيات في الأعلى مدة الجلسة وإجمالي استدعاءات الأدوات وملخص قرارات Hook (عد allow / deny / instruct). +يعرض شريط الإحصائيات في الأعلى مدة الجلسة وإجمالي استدعاءات الأدوات وملخصاً لقرارات السنّارة (عدد allow / deny / instruct). -انقر على زر **Download Logs** لتصدير الجلسة. بالنسبة لجلسات Claude Code و Codex و Copilot و Cursor و Pi، تحصل على نسخة JSONL الأصلية على القرص بالبايت; بالنسبة لـ OpenCode (التي تعيش جلساتها في SQLite، وليس على القرص)، تحصل على مستند JSON يعكس جداول `session` / `messages` / `parts` الأساسية. +انقر على زر **Download Logs** لتصدير الجلسة. بالنسبة لجلسات Claude Code و Codex و Copilot و Cursor و Pi تحصل على نسخة JSONL الأصلية على القرص بالبايت الكامل؛ بالنسبة لـ OpenCode (التي تعيش جلساتها في SQLite وليس على القرص) تحصل على مستند JSON يعكس جداول `session` / `messages` / `parts` الأساسية. ### التدقيق -تقرير مدفوع بالشخصية لكيفية تصرف وكيلك بالفعل عبر الجلسات السابقة. يشغل نفس الفحص كما في CLI `failproofai audit` لكنه يعرضها كملصق واحد قابل للمشاركة على شاشة واحدة + أربعة أقسام أسفل الطية: +تقرير موجه بالشخصية حول كيفية تصرف وكيلك فعلياً عبر الجلسات السابقة. يشغل نفس الفحص مثل CLI `failproofai audit` لكنه يعرضه كملصق واحد قابل للمشاركة على الشاشة + أربعة أقسام أسفل الطي: -1. **ملصق** — يملأ أول عرض محمول. منطقة PNG التقاط نفسها الاحتواء مع علامة failproof_ai + تسمية التدقيق · فهرس النموذج الأصلي (`№ NN of 08`) + تاريخ التدقيق · درجة عددية (0–100) + حبة ترتيب مئوي (`top 15%`) · اسم النموذج الأصلي (أحدها `the optimist`، `the cowboy`، `the explorer`، `the goldfish`، `the paranoid architect`، `the precision builder`، `the hammer`، `the ghost`) + شريط 3 كلمات · `// only N% of agents are this archetype` سطر الندرة · بلاط sigil بحجم 8×8 بكسل · تذييل `audit yours → failproof.ai`. ثلاثة أزرار مشاركة تجلس خارج صندوق الالتقاط مباشرة: `post your archetype` (X intent)، `share on linkedin`، `download poster`. يعمل الالتقاط من خلال `html-to-image` لذا يطابق PNG عرض الشاشة بكسل لبكسل (حدود مخططة، قناع شعار SVG، تدرجات، مقاييس الخط — كل محفوظ). +1. **الملصق** — يملأ عرض الجهاز الأول. منطقة التقاط PNG مكتفية ذاتياً مع شعار failproof_ai + تسمية التدقيق · مؤشر النموذج الأولي (`№ NN من 08`) + تاريخ التدقيق · درجة رقمية (0–100) + حبة ترتيب النسبة المئوية (`top 15%`) · اسم النموذج الأولي (أحدها `the optimist` أو `the cowboy` أو `the explorer` أو `the goldfish` أو `the paranoid architect` أو `the precision builder` أو `the hammer` أو `the ghost`) + شريط كلمات مفتاحية 3 · سطر ندرة `// only N% of agents are this archetype` · بلاط sigil 8×8 بكسل · تذييل `audit yours → failproof.ai`. ثلاث أزرار مشاركة تجلس خارج صندوق التقاط: `post your archetype` (X intent) و `share on linkedin` و `download poster`. يتم تنفيذ التقاط من خلال `html-to-image` بحيث يطابق PNG العرض على الشاشة بكسل تلو كسل (حدود متقطعة وقناع شعار SVG والتدرجات ومقاييس الخط — جميعها محفوظة). -2. **نقاط القوة** — قائمة صف هادئة لسلوكيات وكيلك التي يفعلها بالفعل بشكل صحيح، مشتقة من بيانات التدقيق المباشر (معدل استدعاء أداة نظيف، بدون دفع مباشر إلى main، بدون تسرب بيانات اعتماد، بدون عواصف إعادة محاولة) — يتم عرض كل منها فقط عندما تكون السياسة ذات الصلة لها سجل نظيف عبر نافذة التدقيق. +2. **نقاط القوة** — قائمة صف هادئة ✓ للسلوكيات التي يفعلها وكيلك بالفعل بشكل صحيح، مشتقة من بيانات التدقيق الحية (معدل استدعاء أداة نظيف، بدون دفع مباشر إلى الفرع الرئيسي، بدون تسريب بيانات اعتماد، بدون عواصف إعادة محاولة) — كل واحدة تُعرض فقط عندما تكون السياسة ذات الصلة لها سجل نظيف عبر نافذة التدقيق. -3. **الغرائب** — جدول ما تسرب، مرتب حسب الخطورة: `when · what slipped + the policy that would've caught it · severity pill · seen`، حيث يقرأ التكرار `new` (مرة واحدة)، `N× seen` (2–9 مرات)، أو `recurring` (10+). +3. **الخصائص** — جدول ما تسرب، مرتب حسب الشدة: `when · what slipped + the policy that would've caught it · severity pill · seen`، حيث يُقرأ التكرار كـ `new` (مرة واحدة) أو `N× seen` (2–9 مرات) أو `recurring` (10+). -4. **كيفية التحسين** — قائمة صف هادئة، واحدة لكل سياسة موصى بها: اسم السياسة بأبيض، وصف سطر واحد، أمر التثبيت + زر نسخ على الجانب الأيمن. يقرأ رأس القسم `enable all N → projected · ` (الدرجة التي ستصل إليها مع تطبيق كل إصلاح)، وزر `[install all]` الخاص به ينسخ أمر `failproofai policy add a b c …` المدمج لكل سياسة موصى بها. +4. **كيفية التحسن** — قائمة صف هادئة، واحدة لكل سياسة موصى بها: اسم السياسة بالأبيض، وصف سطر واحد، أمر التثبيت + زر نسخ على الجانب الأيمن. يقرأ رأس القسم `enable all N → projected · ` (الدرجة التي ستصل إليها مع تطبيق كل إصلاح)، وزر `[install all]` الخاص به ينسخ أمر `failproofai policy add a b c …` المدمج لكل سياسة موصى بها. -5. **عد بشكل أفضل** — بطاقتان جنباً إلى جنب. اليسار: قم بتعيين تذكير (منتقي الإيقاع `3d` / `7d` / `14d` / `30d`; يستمر عبر `/api/auth/reminder` بمجرد المصادقة). اليمين: فتح مزايا failproof — `invite a friend` يفتح نمطاً يأخذ قائمة بريد إلكتروني للأصدقاء مفصولة بفواصل/مسافات/أسطر جديدة (الحد الأقصى 10 لكل إرسال)، POSTs إلى `/api/audit/invite`، والذي يعيد توجيهها إلى `/v0/invite` في خادم api الخاص بـ `POST`. يرسل خادم api بريداً إلكترونياً واحداً لكل مستقبل من `invite@failproof.ai` مع نسخة المرسل (Cc) و `Reply-To` محددة، لذا يرى المستقبل من قام بدعوتهم والمرسل يحصل على نسخة في صندوق الوارد الخاص به. يتم توجيه المستخدمين المجهولين من خلال `AuthDialog` أولاً بحيث يكون البريد الإلكتروني للمرسل معروفاً قبل إرسال الدعوات. استحقاق / تحقيق المزايا هو متابعة. +5. **عد أفضل** — بطاقتان جنباً إلى جنب. اليسار: اضبط تذكيراً (منتقي متوازن `3d` / `7d` / `14d` / `30d`؛ ثابت من خلال `/api/auth/reminder` بمجرد المصادقة عليه). اليمين: افتح مزايا failproof — يفتح `invite a friend` حوارياً يأخذ قائمة رسائل بريد صديق مفصولة بفواصل/مسافات/أسطر جديدة (بحد أقصى 10 لكل إرسال)، POSTs لها إلى `/api/audit/invite`، والتي توجه إلى `POST /v0/invite` الخاص بـ api-server. يرسل api-server بريداً إلكترونياً واحداً لكل مستقبل من `invite@failproof.ai` مع نسخ المرسل وضبط `Reply-To`، حتى يرى المستقبل من دعاهم والمرسل يحصل على نسخة في صندوق الوارد الخاص به. يتم توجيه المستخدمين المجهولين من خلال `AuthDialog` أولاً بحيث يكون البريد الإلكتروني للمرسل معروفاً قبل ذهاب الدعوات. الاستحقاق/تتمة المزايا عبارة عن متابعة. -يتم تشغيله بواسطة وقت `failproofai audit` - انظر [Audit CLI](/ar/cli/audit) لمحرك الفحص الأساسي والعلامات المدعومة والثوابت الثابتة المخزنة مؤقتاً لكل نسخة أصلية. تقوم لوحة التحكم بتخزين النتيجة الأحدث مؤقتاً على `~/.failproofai/audit-dashboard.json` (الوضع `0600`، موضع واحد، تكتب التشغيلات الجديدة فوق) بحيث تكون إعادة الزيارات فورية; **يتم رفض كل من ذاكرة التخزين المؤقتة لكل نسخة أصلية وكل النتائج عند القراءة بمجرد أن تصبح أقدم من 7 أيام** لذا لا تقدم لوحة التحكم أبداً بصمت نتيجة قديمة بسنة — بعد TTL `/audit` يسقط من خلال حالته الفارغة ويطالب بتشغيل طازج. بالنقر على `[ re-audit now ]` بالقرب من أسفل التقرير، يتم POST إلى `/api/audit/run` مع `noCache: true` — إعادة التدقيق تتجاوز ذاكرة التخزين المؤقتة لكل نسخة أصلية وتعيد مسح كل نسخة أصلية من الصفر بدلاً من إرجاع النتيجة المخزنة مؤقتاً بصمت — وتقوم لوحة التحكم باستطلاع `/api/audit/status` عند 1Hz حتى ينتهي التشغيل; يتم تثبيت شريط تقدم وردي لزج في أعلى عرض المنفذ أثناء التشغيل مع مؤقت مضي الوقت، والنتيجة الطازجة تتبادل في الموضع عند النجاح (لا يوجد إعادة تحميل كاملة للصفحة; إعادة التدقيق الفاشلة تترك التقرير السابق سليماً). في حالة الفشل، يتحول الشريط إلى اللون الأحمر مع النسخ المشفرة من `RerunError.kind` (`timeout` / `network` / `post_failed`). يتم عرض الحالة الفارغة (بدون ذاكرة تخزين مؤقتة أو منتهية الصلاحية) وحالة الجلسات الصفرية (توجد ذاكرة تخزين مؤقتة لكن الفحص لم يعثر على نصوص أصلية) بشكل منفصل. +يتم تشغيله بواسطة وقت `failproofai audit` — انظر [Audit CLI](/ar/cli/audit) لمحرك المسح الأساسي والأعلام المدعومة وثوابت ذاكرة التخزين المؤقت لكل نسخة. تخزن لوحة التحكم آخر نتيجة مؤقتة في `~/.failproofai/audit-dashboard.json` (الوضع `0600`، فتحة واحدة، التشغيلات الجديدة تستبدل) بحيث تكون إعادة الزيارات فورية؛ **يتم رفض كل من ذاكرة التخزين المؤقت لكل نسخة وذاكرة النتيجة الكاملة عند القراءة بمجرد أن تتجاوز 7 أيام** بحيث لا تخدم لوحة التحكم أبداً نتيجة قديمة بصمت — بعد انتهاء الصلاحية `/audit` تسقط إلى حالتها الفارغة وتطالب بتشغيل جديد. انقر على `[ re-audit now ]` بالقرب من أسفل التقرير POSTs `/api/audit/run` مع `noCache: true` — إعادة التدقيق تتجاوز ذاكرة التخزين المؤقت لكل نسخة وتعيد فحص كل نسخة من الصفر بدلاً من إرجاع النتيجة المخزنة مؤقتاً بصمت — ولوحة التحكم تستقصي `/api/audit/status` بـ 1Hz حتى ينتهي التشغيل؛ شريط تقدم وردي لزج ينتقد إلى أعلى عرض الجهاز أثناء التشغيل مع مؤقت مضى، والنتيجة الطازجة تتبدل في مكانها بنجاح (بدون إعادة تحميل صفحة كاملة؛ إعادة تدقيق فاشلة تترك التقرير السابق سليماً). عند الفشل يتحول الشريط إلى اللون الأحمر مع نسخ مفتاح من `RerunError.kind` (`timeout` / `network` / `post_failed`). يتم عرض الحالة الفارغة (بدون ذاكرة تخزين مؤقت أو منتهية الصلاحية) وحالة عدم وجود جلسات (توجد ذاكرة تخزين مؤقت لكن المسح لم يعثر على نسخ) بشكل منفصل. ### السياسات -صفحة ذات تبويبتين لإدارة السياسات ومراجعة النشاط. +صفحة ذات تبويبين لإدارة السياسات ومراجعة النشاط. - - اختر من لوحة واحدة واجهات برمجية وكيل متعددة التي تحمي failproofai — Claude Code و OpenAI Codex و GitHub Copilot و Cursor Agent و OpenCode و Pi و Hermes كل منها لديه صف مع حالة التثبيت (`Active` / `Detected` / `Inactive`)، مسار إعدادات النطاق الخاص بالمستخدم، وتأكيد ذو ألوان العلامة التجارية. تحقق أو قم بإلغاء تحديد واجهات البرمجة التي تريدها وانقر فوق `Apply changes` لتثبيت/إلغاء تثبيت الفرق في خطوة واحدة. واجهات برمجية التي يتم اكتشاف ملفاتها الثنائية على PATH يتم تحديد مسبق لها. - - التبديل بين السياسات الفردية بضغطة واحدة (يكتب إلى `~/.failproofai/policies-config.json` — مشترك عبر كل CLI مثبت) - - قم بتوسيع سياسة لتكوين معاملات الخاصة بها (للسياسات التي تدعم `policyParams`) - - تعيين مسار ملف السياسات المخصصة + - اختر متعدد التحديد أي CLIs من وكيل يحمي failproofai من لوحة واحدة — Claude Code و OpenAI Codex و GitHub Copilot و Cursor Agent و OpenCode و Pi و Hermes جميعاً لديهم صف مع حالة التثبيت (`Active` / `Detected` / `Inactive`)، مسار إعدادات نطاق المستخدم، وضبط ملون حسب العلامة التجارية. اختر أو أزل تحديد CLIs التي تريدها وانقر على `Apply changes` لتثبيت/إلغاء تثبيت الفارق في خطوة واحدة. CLIs التي تم اكتشاف ثنائيها على PATH يتم فحصها مسبقاً. + - بدّل السياسات الفردية على أو إيقاف بنقرة واحدة (يكتب إلى `~/.failproofai/policies-config.json` — مشترك عبر كل CLI مثبت) + - وسّع سياسة لتكوين معاملات بحث المياه (للسياسات التي تدعم `policyParams`) + - ضبط مسار ملف السياسات المخصص - - السجل الكامل المرقم لكل حدث hook تم تشغيله عبر جميع الجلسات - - التصفية حسب القرار ونوع الحدث واجهة برمجية (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose) أو اسم السياسة أو معرف الجلسة - - يعرض كل صف: الطابع الزمني، اسم السياسة، القرار، شارة CLI (برتقالي = Claude Code، بنفسجي = OpenAI Codex، أزرق = GitHub Copilot، أخضر زمردي = Cursor Agent، كهرماني = OpenCode، وردي = Pi، نيلي = Hermes، أخضر لازوردي = OpenClaw، وردي فاتح = Factory Droid، بنفسجي = Devin، سماوي = Antigravity، أخضر فاتح = Goose)، اسم الأداة، معرف الجلسة، والسبب لقرارات deny/instruct - - انقر على معرف الجلسة لفتح النسخة الأصلية — يكتشف العارض تلقائياً واجهة برمجية محددة التي أطلقت Hook (Claude `~/.claude/projects/…`، Codex `~/.codex/sessions/…`، Copilot CLI `~/.copilot/session-state//events.jsonl`، Cursor Agent `~/.cursor/agent-sessions//events.jsonl`، OpenCode `~/.local/share/opencode/opencode.db`، Pi `~/.pi/agent/sessions//.jsonl`، Hermes `~/.hermes/state.db`، OpenClaw `~/.openclaw/agents//sessions/*.jsonl`، Factory Droid `~/.factory/sessions//.jsonl`، Devin `~/.local/share/devin/cli/sessions.db`، Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`، Goose `~/.local/share/goose/sessions/sessions.db`) ويعرض شارة CLI المطابقة في الرأس + - سجل تاريخ مكتمل مقسم إلى صفحات لكل حدث سنّارة تم تفعيله عبر جميع الجلسات + - تصفية حسب القرار أو نوع الحدث أو CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose) أو اسم السياسة أو معرّف الجلسة + - يعرض كل صف: الطابع الزمني، اسم السياسة، القرار، شارة CLI (برتقالي = Claude Code، بنفسجي = OpenAI Codex، أزرق = GitHub Copilot، زمردي = Cursor Agent، عنبري = OpenCode، وردي = Pi، نيلي = Hermes، تركواز = OpenClaw، وردي = Factory Droid، بنفسجي = Devin، سماوي = Antigravity، أخضر ليموني = Goose)، اسم الأداة، معرّف الجلسة، والسبب لقرارات deny/instruct + - انقر على معرّف جلسة لفتح النسخة الخاصة بها — يكتشف العارض تلقائياً أي CLI أطلق السنّارة (Claude `~/.claude/projects/…`، Codex `~/.codex/sessions/…`، Copilot CLI `~/.copilot/session-state//events.jsonl`، Cursor Agent `~/.cursor/agent-sessions//events.jsonl`، OpenCode `~/.local/share/opencode/opencode.db`، Pi `~/.pi/agent/sessions//.jsonl`، Hermes `~/.hermes/state.db`، OpenClaw `~/.openclaw/agents//sessions/*.jsonl`، Factory Droid `~/.factory/sessions//.jsonl`، Devin `~/.local/share/devin/cli/sessions.db`، Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`، Goose `~/.local/share/goose/sessions/sessions.db`) ويعرض شارة CLI المطابقة في الرأس --- -## التحديث التلقائي +## الانتعاش التلقائي -تحتوي لوحة التحكم على تبديل التحديث التلقائي في التنقل العلوي. عند التفعيل، يتم تحديث الصفحة الحالية بشكل دوري لعرض الجلسات الجديدة ونشاط السياسة عند ظهوره. ضروري لمراقبة جلسات الوكيل المستقل طويلة المدى. +تحتوي لوحة التحكم على تبديل انتعاش تلقائي في التنقل الأعلى. عند تفعيله، تنعش الصفحة الحالية بشكل دوري لإظهار جلسات جديدة ونشاط سياسة جديد عند ظهوره. ضروري لمراقبة جلسات وكيل مستقلة طويلة الأمد. --- ## تعطيل الصفحات -إذا كنت تحتاج فقط إلى بعض أجزاء لوحة التحكم، قم بتعيين `FAILPROOFAI_DISABLE_PAGES` إلى قائمة مفصولة بفواصل من أسماء الصفحات: +إذا كنت تحتاج فقط إلى بعض أجزاء لوحة التحكم، اضبط `FAILPROOFAI_DISABLE_PAGES` على قائمة مفصولة بفواصل من أسماء الصفحات: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai ``` -القيم الصحيحة: `policies`، `projects`، `audit`. +القيم الصحيحة: `policies` أو `projects` أو `audit`. --- ## تكوين مسار المشاريع -بشكل افتراضي، تقرأ لوحة التحكم من دليل مشاريع Claude Code القياسي. قم بتجاوزه للإعدادات المخصصة: +افتراضياً، تقرأ لوحة التحكم من دليل مشاريع Claude Code القياسي. تجاوزه بحثاً عن الإعدادات المخصصة: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -122,32 +125,32 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## الوصول من مضيف غير localhost +## الوصول من مضيف غير محلي -عند تشغيل لوحة التحكم في **وضع dev** (`npm run dev`) والوصول إليها من اسم مضيف آخر غير `localhost` - على سبيل المثال، مجال مخصص أو عنوان IP بعيد أو عنوان URL مجهول الهوية - قد تراى تحذيراً مثل: +عند تشغيل لوحة التحكم في **وضع dev** (`npm run dev`) والوصول إليها من اسم مضيف بخلاف `localhost` - على سبيل المثال، نطاق مخصص أو IP بعيد أو عنوان URL عبر نفق — قد ترى تحذيراً مثل: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -هذا هو Next.js الذي يحجب الوصول متعدد الأصول إلى websocket HMR (إعادة تحميل الوحدة الساخنة) الخاص به، وهي ميزة خاصة بـ dev فقط. للسماح بمضيفك، استخدم العلم `--allowed-origins`: +هذا هو Next.js يحظر الوصول عبر الأصل إلى مورد HMR الخاص به (إعادة تحميل الوحدة الساخنة)، وهي ميزة dev فقط. للسماح بمضيفك، استخدم العلم `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -للعديد من المضيفين أو عناوين IP، قم بتمرير قائمة مفصولة بفواصل: +لعدة مضيفين أو IPs، مرر قائمة مفصولة بفواصل: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -يمكنك أيضاً تعيين متغير البيئة `FAILPROOFAI_ALLOWED_DEV_ORIGINS` بدلاً من ذلك: +يمكنك أيضاً ضبط متغير البيئة `FAILPROOFAI_ALLOWED_DEV_ORIGINS` بدلاً من ذلك: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -ينطبق هذا فقط على وضع dev. عند تشغيل `failproofai` (وضع الإنتاج)، لا يوجد websocket HMR ولا توجد مشكلة مورد dev متعدد الأصول. +هذا ينطبق فقط على وضع dev. عند تشغيل `failproofai` (وضع الإنتاج)، لا توجد أي أداة HMR websocket ولا توجد مشكلة مورد dev عبر الأصل. \ No newline at end of file diff --git a/docs/de/configuration.mdx b/docs/de/configuration.mdx index 95dae70a..102b5e52 100644 --- a/docs/de/configuration.mdx +++ b/docs/de/configuration.mdx @@ -4,25 +4,25 @@ description: "Konfigurationsdateiformat, Drei-Scope-System und Zusammenführungs icon: gear --- -failproofai verwendet JSON-Konfigurationsdateien, um zu steuern, welche Richtlinien aktiv sind, wie sie sich verhalten und woher benutzerdefinierte Richtlinien geladen werden. Die Konfiguration ist darauf ausgelegt, einfach mit Ihrem Team geteilt zu werden – committen Sie sie in Ihr Repository und jeder Entwickler erhält dasselbe Sicherheitsnetz für den Agenten. +failproofai verwendet JSON-Konfigurationsdateien, um zu steuern, welche Richtlinien aktiv sind, wie sie sich verhalten und von wo benutzerdefinierte Richtlinien geladen werden. Die Konfiguration ist so gestaltet, dass sie einfach mit dem Team geteilt werden kann – committe sie in dein Repository und jeder Entwickler erhält dasselbe Sicherheitsnetz für den Agenten. --- -## Konfigurationsscopes +## Konfigurationsbereiche -Es gibt drei Konfigurationsscopes, die in Prioritätsreihenfolge ausgewertet werden: +Es gibt drei Konfigurationsbereiche, die in Prioritätsreihenfolge ausgewertet werden: -| Scope | Dateipfad | Zweck | -|-------|-----------|-------| -| **project** | `.failproofai/policies-config.json` | Repository-spezifische Einstellungen, per Versionsverwaltung committet | -| **local** | `.failproofai/policies-config.local.json` | Persönliche Overrides pro Repository, per .gitignore ausgeschlossen | -| **global** | `~/.failproofai/policies-config.json` | Benutzerweite Standardeinstellungen für alle Projekte | +| Bereich | Dateipfad | Zweck | +|---------|-----------|-------| +| **project** | `.failproofai/policies-config.json` | Repository-spezifische Einstellungen, in die Versionskontrolle eingecheckt | +| **local** | `.failproofai/policies-config.local.json` | Persönliche repository-spezifische Überschreibungen, per .gitignore ausgeschlossen | +| **global** | `~/.failproofai/policies-config.json` | Benutzerweite Standardwerte für alle Projekte | -Wenn failproofai ein Hook-Ereignis empfängt, lädt und führt es alle drei Dateien zusammen, die für das aktuelle Arbeitsverzeichnis existieren. +Wenn failproofai ein Hook-Ereignis empfängt, lädt und fügt es alle drei Dateien zusammen, die für das aktuelle Arbeitsverzeichnis vorhanden sind. ### Zusammenführungsregeln -**`enabledPolicies`** – die Vereinigung aller drei Scopes. Eine Richtlinie, die auf irgendeiner Ebene aktiviert ist, ist aktiv. +**`enabledPolicies`** – die Vereinigung aller drei Bereiche. Eine Richtlinie, die auf irgendeiner Ebene aktiviert ist, ist aktiv. ```text project: ["block-sudo"] @@ -32,7 +32,7 @@ global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← deduplizierte Vereinigung ``` -**`policyParams`** – der erste Scope, der Parameter für eine bestimmte Richtlinie definiert, gewinnt vollständig. Es gibt kein tiefes Zusammenführen von Werten innerhalb der Parameter einer Richtlinie. +**`policyParams`** – der erste Bereich, der Parameter für eine bestimmte Richtlinie definiert, gewinnt vollständig. Es gibt kein tiefes Zusammenführen von Werten innerhalb der Parameter einer Richtlinie. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -42,16 +42,20 @@ resolved: { allowPatterns: ["sudo apt-get update"] } ← project gewinnt, glob ``` ```text -project: (kein block-sudo Eintrag) -local: (kein block-sudo Eintrag) +project: (kein block-sudo-Eintrag) +local: (kein block-sudo-Eintrag) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← fällt auf global zurück ``` -**`customPoliciesPath`** – der erste Scope, der diesen definiert, gewinnt. +**`customPoliciesPaths` / `customPoliciesPath`** – der erste Bereich, der eine der beiden Formen definiert, gewinnt. -**`llm`** – der erste Scope, der diesen definiert, gewinnt. +**`disabledCustomPolicies`** – Vereinigung über alle Bereiche. Das Dashboard schreibt eine +quellenqualifizierte ID hierher, wenn du eine einzelne Richtlinie aus einer +expliziten oder konventionsbasierten Richtliniendatei deaktivierst. Nicht aufgeführte Richtlinien bleiben standardmäßig aktiviert; IDs enthalten die Quelldatei, damit gleichnamige Richtlinien in mehreren Dateien unabhängig gesteuert werden können. + +**`llm`** – der erste Bereich, der es definiert, gewinnt. --- @@ -102,7 +106,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← fällt auf global zu Typ: `string[]` -Liste der zu aktivierenden Richtliniennamen. Die Namen müssen exakt mit den Richtlinienbezeichnern übereinstimmen, die `failproofai policies` anzeigt. Eine vollständige Liste finden Sie unter [Integrierte Richtlinien](/de/built-in-policies). +Liste der zu aktivierenden Richtliniennamen. Die Namen müssen genau mit den Richtlinienbezeichnern übereinstimmen, die von `failproofai policies` angezeigt werden. Die vollständige Liste findest du unter [Integrierte Richtlinien](/de/built-in-policies). Richtlinien, die nicht in `enabledPolicies` enthalten sind, sind inaktiv, auch wenn sie Einträge in `policyParams` haben. @@ -110,19 +114,19 @@ Richtlinien, die nicht in `enabledPolicies` enthalten sind, sind inaktiv, auch w Typ: `Record>` -Richtlinienspezifische Parameterüberschreibungen. Der äußere Schlüssel ist der Richtlinienname; die inneren Schlüssel sind richtlinienspezifisch. Jede Richtlinie dokumentiert ihre verfügbaren Parameter unter [Integrierte Richtlinien](/de/built-in-policies). +Parameterüberschreibungen pro Richtlinie. Der äußere Schlüssel ist der Richtlinienname; die inneren Schlüssel sind richtlinienspezifisch. Jede Richtlinie dokumentiert ihre verfügbaren Parameter unter [Integrierte Richtlinien](/de/built-in-policies). -Wenn eine Richtlinie Parameter hat, Sie diese aber nicht angeben, werden die integrierten Standardwerte der Richtlinie verwendet. Benutzer, die `policyParams` überhaupt nicht konfigurieren, erhalten dasselbe Verhalten wie in früheren Versionen. +Wenn eine Richtlinie Parameter hat, du diese aber nicht angibst, werden die integrierten Standardwerte der Richtlinie verwendet. Benutzer, die `policyParams` überhaupt nicht konfigurieren, erhalten identisches Verhalten wie in früheren Versionen. -Unbekannte Schlüssel im Parameterblock einer Richtlinie werden zum Zeitpunkt des Hook-Aufrufs stillschweigend ignoriert, aber bei der Ausführung von `failproofai policies` als Warnungen markiert. +Unbekannte Schlüssel im Parameterblock einer Richtlinie werden zum Zeitpunkt des Hook-Auslösens stillschweigend ignoriert, aber als Warnungen markiert, wenn du `failproofai policies` ausführst. #### `hint` (übergreifend) Typ: `string` (optional) -Eine Nachricht, die an den Grund angehängt wird, wenn eine Richtlinie `deny` oder `instruct` zurückgibt. Damit können Sie Claude handlungsrelevante Hinweise geben, ohne die Richtlinie selbst zu ändern. +Eine Nachricht, die dem Grund angehängt wird, wenn eine Richtlinie `deny` oder `instruct` zurückgibt. Damit kannst du Claude handlungsrelevante Hinweise geben, ohne die Richtlinie selbst zu ändern. -Funktioniert mit jedem Richtlinientyp – integriert, benutzerdefiniert (`custom/`), Projektkonvention (`.failproofai-project/`) oder Benutzerkonvention (`.failproofai-user/`). +Funktioniert mit allen Richtlinientypen – integriert, benutzerdefiniert (`custom/`), Projektkonvention (`.failproofai-project/`) oder Benutzerkonvention (`.failproofai-user/`). ```json { @@ -141,9 +145,9 @@ Funktioniert mit jedem Richtlinientyp – integriert, benutzerdefiniert (`custom } ``` -Wenn `block-force-push` ablehnt, sieht Claude: *„Force-Pushing ist blockiert. Try creating a fresh branch instead."* +Wenn `block-force-push` verweigert, sieht Claude: *„Force-pushing is blocked. Try creating a fresh branch instead."* -Nicht-String-Werte und leere Strings werden stillschweigend ignoriert. Wenn `hint` nicht gesetzt ist, bleibt das Verhalten unverändert (abwärtskompatibel). +Nicht-String-Werte und leere Zeichenketten werden stillschweigend ignoriert. Wenn `hint` nicht gesetzt ist, ist das Verhalten unverändert (rückwärtskompatibel). ### `customPoliciesPath` @@ -151,24 +155,24 @@ Typ: `string` (absoluter Pfad) Pfad zu einer JavaScript-Datei mit benutzerdefinierten Hook-Richtlinien. Dieser wird automatisch von `failproofai policies --install --custom ` gesetzt (der Pfad wird vor der Speicherung in einen absoluten Pfad aufgelöst). -Die Datei wird bei jedem Hook-Ereignis neu geladen – es gibt kein Caching. Weitere Details zur Erstellung finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies). +Die Datei wird bei jedem Hook-Ereignis neu geladen – es gibt kein Caching. Weitere Informationen zur Erstellung findest du unter [Benutzerdefinierte Richtlinien](/de/custom-policies). ### Konventionsbasierte Richtlinien Zusätzlich zum expliziten `customPoliciesPath` erkennt und lädt failproofai automatisch Richtliniendateien aus `.failproofai/policies/`-Verzeichnissen: -| Ebene | Verzeichnis | Scope | -|-------|-------------|-------| -| Projekt | `.failproofai/policies/` | Per Versionsverwaltung mit dem Team geteilt | +| Ebene | Verzeichnis | Bereich | +|-------|-------------|---------| +| Projekt | `.failproofai/policies/` | Mit dem Team über die Versionskontrolle geteilt | | Benutzer | `~/.failproofai/policies/` | Persönlich, gilt für alle Projekte | -**Dateiabgleich:** Es werden nur Dateien geladen, die dem Muster `*policies.{js,mjs,ts}` entsprechen (z. B. `security-policies.mjs`, `workflow-policies.js`). Andere Dateien im Verzeichnis werden ignoriert. +**Dateiabgleich:** Es werden nur Dateien geladen, die auf `*policies.{js,mjs,ts}` passen (z. B. `security-policies.mjs`, `workflow-policies.js`). Andere Dateien im Verzeichnis werden ignoriert. -**Keine Konfiguration erforderlich:** Konventionsrichtlinien benötigen keine Einträge in `policies-config.json`. Legen Sie einfach Dateien in das Verzeichnis und sie werden beim nächsten Hook-Ereignis erkannt. +**Keine Konfiguration nötig:** Konventionsrichtlinien erfordern keine Einträge in `policies-config.json`. Lege die Dateien einfach im Verzeichnis ab und sie werden beim nächsten Hook-Ereignis aufgenommen. -**Vereinigtes Laden:** Sowohl das Projekt- als auch das Benutzerkonventionsverzeichnis werden durchsucht. Alle passenden Dateien aus beiden Ebenen werden geladen (im Gegensatz zu `customPoliciesPath`, das das Prinzip „erster Scope gewinnt" verwendet). +**Vereinigtes Laden:** Sowohl das Projekt- als auch das Benutzerkonventionsverzeichnis werden durchsucht. Alle passenden Dateien aus beiden Ebenen werden geladen (im Gegensatz zu `customPoliciesPath`, das das Prinzip „erster Bereich gewinnt" verwendet). -Weitere Details und Beispiele finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies). +Weitere Details und Beispiele findest du unter [Benutzerdefinierte Richtlinien](/de/custom-policies). ### `llm` @@ -189,19 +193,24 @@ LLM-Client-Konfiguration für Richtlinien, die KI-Aufrufe durchführen. Für die ## Konfiguration über die CLI verwalten -Die Befehle `policies --install` und `policies --uninstall` schreiben in die Hook-Einstellungsdatei Ihrer Agenten-CLI (die Hook-Einstiegspunkte), während `policies-config.json` die Datei ist, die Sie direkt verwalten. Die beiden sind voneinander getrennt: +Die Befehle `policies --install` und `policies --uninstall` schreiben in die Hook-Einstellungsdatei deiner Agenten-CLI (die Hook-Einstiegspunkte), während `policies-config.json` die Datei ist, die du direkt verwaltest. Beides sind separate Konzepte: -- **Agenten-CLI-Einstellungen** – weist den Agenten an, bei jeder Toolnutzung `failproofai --hook ` aufzurufen: +- **Agenten-CLI-Einstellungen** — weist den Agenten an, bei jeder Toolnutzung `failproofai --hook ` aufzurufen: - **Claude Code**: `~/.claude/settings.json` (Benutzer), `/.claude/settings.json` (Projekt), `/.claude/settings.local.json` (lokal) - - **OpenAI Codex**: `~/.codex/hooks.json` (Benutzer), `/.codex/hooks.json` (Projekt) – Codex hat keinen `local`-Scope - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (Benutzer), `/.github/hooks/failproofai.json` (Projekt) – Copilot hat keinen `local`-Scope. Hook-Einträge verwenden Copilots betriebssystemspezifische `bash`/`powershell`-Befehlsfelder mit `timeoutSec`; die Datei enthält einen `version: 1`-Marker auf oberster Ebene. Die Unterstützung von Copilot CLI ist **beta**, während wir das `events.jsonl`-Aufzeichnungsschema (das in der öffentlichen Dokumentation nicht spezifiziert ist) anhand weiterer realer Sitzungen überprüfen. - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (Benutzer), `/.cursor/hooks.json` (Projekt) – Cursor hat keinen `local`-Scope. Hook-Einträge verwenden die Claude-ähnliche `{type, command, timeout}`-Form (ohne `bash`/`powershell`-Aufteilung), werden aber unter camelCase-Ereignisschlüsseln (`preToolUse`, `beforeSubmitPrompt`, …) in einem flachen Array gemäß Cursors [Hooks-Schema](https://cursor.com/docs/hooks) gespeichert; die Datei enthält einen `version: 1`-Marker auf oberster Ebene. Der Handler kanonisiert camelCase → PascalCase über `CURSOR_EVENT_MAP`, sodass bestehende integrierte Richtlinien unverändert ausgelöst werden. Die Unterstützung von Cursor Agent ist **beta**, während wir Cursors On-Disk-Transkriptformat (in der öffentlichen Dokumentation nicht spezifiziert) anhand weiterer realer Installationen überprüfen. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (Benutzer), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (Projekt) – OpenCode hat keinen `local`-Scope. Im Gegensatz zu den anderen fünf CLIs verfügt OpenCode über **kein externes Befehls-Hook-System**: Es lädt In-Process-JS/TS-Plugins, die explizit über das `plugin: []`-Array in `opencode.json` registriert werden (automatische Erkennung aus `.opencode/plugins/` ist **nicht** die Art, wie Plugins in opencode v1.14.33 geladen werden). Die Installation legt ein kleines generiertes Plugin-Shim ab, das den failproofai-Binary als Subprozess aufruft und die JSON-Antwort im Claude-Format des Binaries zurück in Plugin-Semantik übersetzt: `throw new Error()` für tool-event deny (bricht den Tool-Aufruf ab), `client.session.prompt(...)` für instruct UND für `Stop` / `SubagentStop` deny (reicht den Ablehnungsgrund als nächste Benutzernachricht ein – der einzige Force-Retry-Kanal, da `session.idle` nur eine Benachrichtigung ist und das Werfen einer Exception dort ein No-op ist), und No-op für allow. Das Shim kanonisiert sowohl Tool-Namen (Kleinbuchstaben → PascalCase über `OPENCODE_TOOL_MAP`) als auch Tool-Input-Argumentschlüssel (camelCase → snake_case über `OPENCODE_TOOL_INPUT_MAP` für `Read` / `Write` / `Edit`, z. B. `filePath` → `file_path`, `oldString` → `old_string`), bevor es an das Binary weiterleitet, sodass pfadprüfende Builtins wie `block-read-outside-cwd`, `block-env-files` und `block-secrets-write` bei OpenCode-Tool-Aufrufen unverändert ausgelöst werden. Sitzungen werden in OpenCodes SQLite-Datenbank unter `~/.local/share/opencode/opencode.db` gespeichert; der Session-Viewer des Dashboards liest sie über `opencode db --format json` und `opencode export `. Die OpenCode-Unterstützung ist **beta**, während wir das Verhalten versionsübergreifend und anhand weiterer realer Sitzungen überprüfen. Siehe die [OpenCode-Plugin-Dokumentation](https://opencode.ai/docs/plugins/). - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (Benutzer), `/.pi/settings.json` (Projekt) – Pi hat keinen `local`-Scope. Pi lädt TypeScript-Erweiterungspakete beim Start; die Einstellungsdatei ist ein flaches String-Array `{"packages": ["./relative/path", …]}`. failproofai schreibt einen einzelnen packages-Array-Eintrag, der auf sein gebündeltes `pi-extension/`-Verzeichnis zeigt. Die Erweiterung abonniert intern Pis `tool_call` / `user_bash` / `input` / `session_start`-Ereignisse und ruft `failproofai --hook --cli pi` als Shell-Befehl auf; der Handler kanonisiert Ereignisse über `PI_EVENT_MAP` von underscore_lower_snake_case → PascalCase, sodass bestehende integrierte Richtlinien unverändert ausgelöst werden. Tool-Input-Argumente werden ebenfalls über `PI_TOOL_INPUT_MAP` kanonisiert (Pis Read / Write / Edit liefern `path` statt `file_path`; die Zuordnung des obersten Schlüssels lässt `block-env-files` und `block-secrets-write` auslösen – `block-read-outside-cwd` hatte bereits einen `path`-Fallback). Die Pi-Unterstützung ist **beta**, während sich Pis Erweiterungs-API und das Sitzungslog-Layout stabilisieren. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**nur Benutzer-Scope** – Hermes hat keine Projekt-/lokale Konfiguration). Hermes ist ein Slack/Telegram-**Gateway**, daher fängt eine Installation Tool-Aufrufe von jeder Plattform (Slack/Telegram/cli/cron) **und** internen Subagenten ab. Hook-Einträge sind ein `{command, timeout}`-Paar (Timeout in **Sekunden**) unter einem `hooks:`-Map, der nach Hermes' snake_case-Ereignissen (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) geordnet ist; der Handler kanonisiert Ereignisse über `HERMES_EVENT_MAP` und Tool-Namen über `HERMES_TOOL_MAP`, sodass integrierte Richtlinien unverändert ausgelöst werden. Die Konfiguration wird durch einen kommentarerhaltenden YAML-`Document`-Round-trip bearbeitet, sodass die anderen Einstellungen des Betreibers erhalten bleiben, und die Installation setzt `hooks_auto_accept: true`, sodass das kopflose Gateway (kein TTY) die Hooks ohne Zustimmungsaufforderung ausführt. Der Auswerter gibt Hermes' stdout-Vertrag `{"decision":"block","reason"}` aus (Hermes ignoriert Exit-Codes). **Einschränkungen:** Hermes hat kein turn-end-`Stop`-Ereignis, daher werden die `require-*-before-stop`-Builtins für Hermes nie ausgelöst (nicht anwendbar, nicht defekt); `instruct` wird zu allow-with-logged-note herabgestuft (kein additional-context-Kanal); und Output-Secret-Redaktion (`sanitize-*`) kann Tool-Output über den Shell-Hook-Vertrag nicht umschreiben. Hermes ist **auch** eine Offline-**Audit**-Quelle – das Dashboard liest seine Gateway-Sitzungen direkt aus `~/.hermes/state.db`. -- **`policies-config.json`** – teilt failproofai mit, welche Richtlinien ausgewertet werden sollen und mit welchen Parametern (geteilt über alle Agenten-CLIs) - -Übergeben Sie `--cli claude|codex|copilot|cursor|opencode|pi|hermes`, um einen bestimmten Agenten anzusprechen (durch Leerzeichen getrennt oder wiederholt für eine beliebige Teilmenge): + - **OpenAI Codex**: `~/.codex/hooks.json` (Benutzer), `/.codex/hooks.json` (Projekt) — Codex hat keinen `local`-Bereich + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (Benutzer), `/.github/hooks/failproofai.json` (Projekt) — Copilot hat keinen `local`-Bereich. Hook-Einträge verwenden die OS-schlüsselbasierten `bash`/`powershell`-Befehlsfelder von Copilot mit `timeoutSec`; die Datei trägt einen Top-Level-`version: 1`-Marker. Die Copilot-CLI-Unterstützung ist **Beta**, während wir das `events.jsonl`-Datensatzschema (das in der offiziellen Dokumentation nicht spezifiziert ist) gegen mehr reale Sitzungen verifizieren. **VS Code Copilot Chat Agent-Modus (Preview)** liest Hook-Konfigurationen aus `.github/hooks/*.json`, `~/.copilot/hooks/*.json` und `~/.claude/settings.json` (gesteuert durch die Einstellung `chat.hookFilesLocations`) mit demselben Claude-förmigen `{hookSpecificOutput:{permissionDecision:"deny",…}}`-Vertrag — genau die Pfade, in die diese `copilot`-Integration und die `claude`-Integration (`~/.claude/settings.json`) bereits schreiben, sodass `failproofai policies --install --cli copilot` (oder `--cli claude`) **bereits im VS Code Agent-Modus durchgesetzt wird**, ohne dass eine separate `vscode`-Integration nötig ist (live aus VS Codes Discovery-Logs bestätigt). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (Benutzer), `/.cursor/hooks.json` (Projekt) — Cursor hat keinen `local`-Bereich. Hook-Einträge verwenden die Claude-förmige `{type, command, timeout}`-Form (keine `bash`/`powershell`-Aufteilung), werden aber unter camelCase-Ereignisschlüsseln (`preToolUse`, `beforeSubmitPrompt`, …) in einem flachen Array gemäß Cursors [Hooks-Schema](https://cursor.com/docs/hooks) gespeichert; die Datei trägt einen Top-Level-`version: 1`-Marker. Der Handler kanonisiert camelCase → PascalCase über `CURSOR_EVENT_MAP`, sodass bestehende integrierte Richtlinien unverändert auslösen. Die Cursor-Agent-Unterstützung ist **Beta**, während wir Cursors On-Disk-Transkriptformat (in der offiziellen Dokumentation nicht spezifiziert) gegen mehr reale Installationen verifizieren. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (Benutzer), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (Projekt) — OpenCode hat keinen `local`-Bereich. Im Gegensatz zu den anderen fünf CLIs hat OpenCode **kein externes-Befehl-Hook-System**: Es lädt In-Process-JS/TS-Plugins, die explizit über das `plugin: []`-Array in `opencode.json` registriert werden (Auto-Discovery aus `.opencode/plugins/` ist **nicht** die Art, wie Plugins in opencode v1.14.33 geladen werden). Die Installation legt ein kleines generiertes Plugin-Shim ab, das das failproofai-Binary als Unterprozess aufruft und die Claude-förmige JSON-Antwort des Binaries zurück in Plugin-Semantik übersetzt: `throw new Error()` für Tool-Event-Deny (bricht den Tool-Aufruf ab), `client.session.prompt(...)` für instruct UND für `Stop`/`SubagentStop`-Deny (reicht den Verweigerungsgrund als nächste Benutzernachricht ein — der einzige Force-Retry-Kanal, da `session.idle` nur Benachrichtigung ist und ein Throw daraus ein No-Op ist) und No-Op für allow. Das Shim kanonisiert sowohl Tool-Namen (Kleinbuchstaben → PascalCase über `OPENCODE_TOOL_MAP`) als auch Tool-Input-Arg-Schlüssel (camelCase → snake_case über `OPENCODE_TOOL_INPUT_MAP` für `Read`/`Write`/`Edit`, z. B. `filePath` → `file_path`, `oldString` → `old_string`), bevor es an das Binary weiterleitet, sodass pfadprüfende Builtins wie `block-read-outside-cwd`, `block-env-files` und `block-secrets-write` bei OpenCode-Tool-Aufrufen unverändert auslösen. Sitzungen leben in openCodes SQLite-Datenbank unter `~/.local/share/opencode/opencode.db`; der Sitzungsviewer des Dashboards liest sie über `opencode db --format json` und `opencode export `. Die OpenCode-Unterstützung ist **Beta**, während wir das Verhalten über Versionen und gegen mehr reale Sitzungen verifizieren. Siehe die [OpenCode-Plugin-Dokumentation](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (Benutzer), `/.pi/settings.json` (Projekt) — Pi hat keinen `local`-Bereich. Pi lädt TypeScript-Erweiterungspakete beim Start; die Einstellungsdatei ist ein flaches String-Array `{"packages": ["./relative/path", …]}`. failproofai schreibt einen einzigen packages-Array-Eintrag, der auf sein gebündeltes `pi-extension/`-Verzeichnis zeigt. Die Erweiterung abonniert intern Pis `tool_call`/`user_bash`/`input`/`session_start`-Ereignisse und ruft `failproofai --hook --cli pi` auf; der Handler kanonisiert underscore_lower_snake_case → PascalCase über `PI_EVENT_MAP`, sodass bestehende integrierte Richtlinien unverändert auslösen. Tool-Input-Args werden auch über `PI_TOOL_INPUT_MAP` kanonisiert (Pis Read/Write/Edit liefern `path` statt `file_path`; das Mapping des Top-Level-Schlüssels lässt `block-env-files` und `block-secrets-write` auslösen — `block-read-outside-cwd` hatte bereits einen `path`-Fallback). Die Pi-Unterstützung ist **Beta**, während sich Pis Extension-API und das Session-Log-Layout stabilisieren. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**nur Benutzerbereich** — Hermes hat keine Projekt-/lokale Konfiguration). Hermes ist ein Slack/Telegram-**Gateway**, sodass eine Installation Tool-Aufrufe von jeder Plattform (Slack/Telegram/cli/cron) **und** internen Subagenten abfängt. Hook-Einträge sind ein `{command, timeout}`-Paar (Timeout in **Sekunden**) unter einer `hooks:`-Map, die durch Hermes' snake_case-Ereignisse (`pre_tool_call`/`post_tool_call`/`on_session_start`/`on_session_end`/`subagent_stop`) indiziert ist; der Handler kanonisiert Ereignisse über `HERMES_EVENT_MAP` und Tool-Namen über `HERMES_TOOL_MAP`, sodass integrierte Richtlinien unverändert auslösen. Die Konfiguration wird über einen kommentarerhaltenden YAML-`Document`-Round-Trip bearbeitet, damit die anderen Einstellungen des Betreibers erhalten bleiben, und die Installation setzt `hooks_auto_accept: true`, damit das Headless-Gateway (kein TTY) die Hooks ohne Zustimmungsaufforderung ausführt. Der Evaluator gibt Hermes' `{"decision":"block","reason"}`-stdout-Vertrag aus (Hermes ignoriert Exit-Codes). **Einschränkungen:** Hermes hat kein turn-end-`Stop`-Ereignis, sodass die `require-*-before-stop`-Builtins niemals für es auslösen (nicht anwendbar, nicht kaputt); `instruct` degradiert zu allow-with-logged-note (kein additional-context-Kanal); und Output-Secret-Redaktion (`sanitize-*`) kann die Tool-Ausgabe über den Shell-Hook-Vertrag nicht umschreiben. Hermes ist **auch** eine Offline-**Audit**-Quelle — das Dashboard liest seine Gateway-Sitzungen direkt aus `~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**nur Benutzerbereich** — OpenClaw hat keine Projekt-/lokale Konfiguration). Wie Hermes ist OpenClaw ein selbst gehostetes Multi-Channel-**Gateway**, sodass eine Installation Tool-Aufrufe von jedem Kanal und seinen internen Subagenten abfängt. Die Durchsetzung läuft über OpenClaws **In-Process-Plugin-Hooks** (seine dateibasierten internen Hooks sind nur zur Beobachtung und können nicht blockieren), sodass — wie OpenCode/Pi — failproofai ein statisches `openclaw-plugin/`-Paket mitliefert, das das failproofai-Binary async-spawnt und das Urteil übersetzt. Die Installation registriert das mitgelieferte Plugin-Verzeichnis in `openclaw.json`'s `plugins.load.paths[]` und aktiviert es unter `plugins.entries.failproofai` (mit `hooks.allowConversationAccess: true`, erforderlich für die Raw-Conversation-Hooks). Der Evaluator gibt ein flaches `{permission, reason}`-Urteil aus und das Shim ordnet es der nativen Rückgabeform jedes Hooks zu: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**) und `before_agent_finalize → {action:"revise", reason}` (**Stop** — ein echtes turn-end-Gate, sodass die `require-*-before-stop`-Builtins **auf OpenClaw durchgesetzt werden**, anders als bei Hermes). Ereignisse und Tool-Namen werden binärseitig über `OPENCLAW_EVENT_MAP`/`OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) kanonisiert, sodass integrierte Richtlinien unverändert auslösen; das Shim versagt offen bei jedem Spawn/Parse/Timeout-Fehler. OpenClaw ist **auch** eine Offline-**Audit**-Quelle — das Dashboard liest seine JSONL-Sitzungen unter `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (Benutzer), `/.factory/hooks.json` (Projekt) — Factory hat keinen `local`-Bereich. droid liefert ein Claude-ähnliches externes-Befehl-Hook-System, aber mit zwei Besonderheiten, die live gegen droid v0.171.0 verifiziert wurden: (1) Ereignisnamen befinden sich auf der **obersten Ebene** von `hooks.json` — es gibt **keinen `"hooks"`-Wrapper** (droid lehnt einen ab); Tool-Ereignisse (`PreToolUse`/`PostToolUse`) tragen `"matcher": "*"`, Nicht-Tool-Ereignisse lassen es weg. (2) Deny wird durch Hook-**Exit-Code 2 + stderr** gesteuert, nicht durch eine JSON-Entscheidung — der `factory`-Zweig des Evaluators gibt Exit 2 für Tool/Prompt-Ereignisse zurück und `{decision:"block", reason}` nur beim turn-end-`Stop`-Ereignis (droits einziger Force-Retry-Kanal). Ereignisse sind bereits PascalCase (keine Ereignis-Map) und die Nutzlast ist Claude snake_case; nur Tool-Namen werden über `FACTORY_TOOL_MAP` kanonisiert (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory ist **auch** eine Offline-**Audit**-Quelle — das Dashboard liest seine On-Disk-JSONL-Sitzungen unter `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (Benutzer), `/.devin/config.json` (Projekt) — Devin hat keinen `local`-Bereich. Devin ist ein **reiner Claude-Klon**, live gegen devin v3000.1.27 verifiziert: Es verwendet das Standard-Claude-`"hooks"`-Wrapper-Schema (Schreibvorgänge sind merge-erhaltend, sodass die anderen Schlüssel der Konfigurationsdatei — `org_id`, `theme_mode`, … — erhalten bleiben), bereits-PascalCase-Ereignisnamen (keine Ereignis-Map, kein Handler-Zweig) und eine Claude-snake_case-stdin-Nutzlast (keine Normalisierung). Der `devin`-Zweig des Evaluators verweigert mit `{"decision":"block","reason"}`-JSON auf stdout bei Exit 0 für **jedes** Ereignis (verifiziert — der Block überschrieb `--permission-mode dangerous`); beim turn-end-`Stop`-Ereignis trägt der Grund den MANDATORY-ACTION-Force-Retry-Wortlaut, sodass die `require-*-before-stop`-Builtins durchgesetzt werden. Nur Tool-Namen werden über `DEVIN_TOOL_MAP` kanonisiert (`exec→Bash`; `tool_input.command` ist bereits kanonisch). Devin ist **auch** eine Offline-**Audit**-Quelle — das Dashboard liest seine SQLite-Sitzungen unter `~/.local/share/devin/cli/sessions.db` (jede `sessions`-Zeile trägt ein echtes `working_directory`, sodass Sitzungen nach Projekt-cwd wie Claude gruppiert werden). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (Benutzer), `/.agents/hooks.json` (Projekt) — Antigravity hat keinen `local`-Bereich. Im Gegensatz zu Factory/Devin hat Antigravity seinen **eigenen** Vertrag (kein Claude-Klon), live gegen agy v1.1.2 verifiziert. `hooks.json` verwendet ein **named-hook**-Schema: Der Top-Level-Schlüssel ist ein Hook-*Name* (`"failproofai"`), dessen Wert eine Ereignis→Handler-Map ist — Tool-Ereignisse (`PreToolUse`/`PostToolUse`) umschließen Handler in `{matcher:"*", hooks:[…]}`, während `PreInvocation`/`Stop` **flache** Handler-Arrays sind (andere named Hooks werden beibehalten). Die stdin-Nutzlast ist **camelCase-Protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai normalisiert sie zu snake_case, bevor Richtlinien ausgeführt werden, und ordnet die PascalCase-Args von `run_command` (`CommandLine`/`Cwd`) über `ANTIGRAVITY_TOOL_INPUT_MAP` zu. Der `antigravity`-Zweig des Evaluators verwendet Antigravitys **eigene** Antwortformen: `{decision:"deny", reason}` blockiert ein Tool/Prompt (Exit 0), `{decision:"continue", reason}` beim turn-end-`Stop` betritt die Schleife erneut (sodass die `require-*-before-stop`-Builtins durchgesetzt werden) und `{injectSteps:[{ephemeralMessage}]}` injiziert eine Anweisung bei `PreInvocation` (→ `UserPromptSubmit`). Tool-Namen kanonisieren über `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity ist **auch** eine Offline-**Audit**-Quelle — das Dashboard liest seine Plain-JSONL-Transkripte unter `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (Konversationsindex in `conversation_summaries.db`). + - **Goose (Codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (Benutzer), `/.agents/plugins/failproofai/hooks/hooks.json` (Projekt) — Goose hat keinen `local`-Bereich. Die Durchsetzung verwendet Gooses **Hooks**-System, die cross-agent-**Open-Plugins**-Spezifikation: Der Installer legt einfach das `failproofai`-Plugin-Verzeichnis ab und Goose erkennt es beim Start automatisch (registriert es selbst in `~/.config/goose/config.yaml`). Die `hooks.json` verwendet ein Open-Plugins-Schema **mit** einem Top-Level-`"hooks"`-Wrapper, und der Matcher wird bei jedem Ereignis **weggelassen** — ein bloßes `"*"` ist ein ungültiger Regex, der nichts matched (live gegen goose v1.43.0 verifiziert). Ereignisnamen sind bereits PascalCase (keine Ereignis-Map); die stdin-Nutzlast verwendet `event`/`working_dir`, die der Handler zu `hook_event_name`/`cwd` normalisiert. Der `goose`-Zweig des Evaluators verweigert mit `{"decision":"block","reason"}`-JSON auf stdout bei Exit 0, was nur beim **`PreToolUse`**-Ereignis berücksichtigt wird (eingeführt in goose ≥ v1.37.0) — das für das Shell-Tool **und innerhalb delegierter Subagenten** auslöst, sodass es der einzige ausreichende Deny-Punkt ist; jeder andere Hook-Fehler versagt **offen**. Goose hat **kein `Stop`-Ereignis**, sodass die `require-*-before-stop`-Builtins nicht anwendbar sind (wie bei Hermes). Tool-Namen kanonisieren über `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) und Pfadschlüssel über `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose ist **auch** eine Offline-**Audit**-Quelle — das Dashboard liest seine SQLite-Sitzungen unter `~/.local/share/goose/sessions/sessions.db` (jede `sessions`-Zeile trägt ein echtes `working_dir`, sodass Sitzungen nach Projekt-cwd wie Devin gruppiert werden; `--no-session`-Scratch-Runs werden herausgefiltert). +- **`policies-config.json`** — weist failproofai an, welche Richtlinien ausgewertet und mit welchen Parametern (gemeinsam über alle Agenten-CLIs) + +Übergib `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`, um einen bestimmten Agenten anzusprechen (durch Leerzeichen getrennt oder wiederholt für eine beliebige Teilmenge): ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +219,28 @@ failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli hermes --scope user -failproofai policies --install --cli claude codex copilot cursor opencode pi +failproofai policies --install --cli openclaw --scope user +failproofai policies --install --cli factory --scope project +failproofai policies --install --cli devin --scope project +failproofai policies --install --cli antigravity --scope project +failproofai policies --install --cli goose --scope project +failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -Wenn `--cli` weggelassen wird, erkennt `failproofai` automatisch, welche Agenten-CLIs installiert sind (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`): +Wenn `--cli` weggelassen wird, erkennt `failproofai` automatisch, welche Agenten-CLIs installiert sind (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): -- **Eine CLI erkannt** – wählt diese CLI automatisch ohne Rückfrage aus. -- **Mehrere CLIs erkannt** in einem interaktiven Terminal – zeigt eine Einzelauswahl-Eingabeaufforderung mit Pfeiltasten an, die in einen Abschnitt `Erkannt (N)` (mit einer `Für alle N erkannten installieren`-Sammelzeile + jeder erkannten CLI einzeln) und einen Abschnitt `Nicht installiert (M) · Hooks vorab installieren` unterteilt ist, der alle nicht erkannten unterstützten CLIs als Vorwärts-Installationsoption auflistet (↑↓ zum Bewegen, Enter zum Auswählen, ^C zum Beenden). Der Deinstallationsablauf zeigt nur den Abschnitt „Erkannt" an. -- **Mehrere CLIs erkannt** in einem nicht-interaktiven Lauf (CI, kein TTY) – installiert für alle erkannten CLIs ohne Rückfrage. -- **Keine erkannt** – fällt auf `claude` zurück, mit einer Warnung, dass kein Agenten-Binary im PATH gefunden wurde; der Hook-Befehl wird trotzdem geschrieben, sodass er aktiviert wird, sobald Sie einen installieren. +- **Eine CLI erkannt** — wählt diese CLI automatisch ohne Nachfrage. +- **Mehrere CLIs erkannt** in einem interaktiven Terminal — zeigt eine Pfeil-Einzel-Auswahl-Eingabeaufforderung an, gruppiert in einen Abschnitt `Detected (N)` (mit einer aggregierten Zeile `Install for all N detected` + jede erkannte CLI einzeln) und einen Abschnitt `Not installed (M) · install hooks ahead of time`, der alle nicht erkannten unterstützten CLIs als Voraus-Installationsoption auflistet (↑↓ zum Bewegen, Enter zum Auswählen, ^C zum Beenden). Der Deinstallationsablauf zeigt nur den Detected-Abschnitt. +- **Mehrere CLIs erkannt** in einem nicht-interaktiven Lauf (CI, kein TTY) — installiert für alle erkannten CLIs ohne Nachfrage. +- **Keine erkannt** — fällt auf `claude` zurück, mit einer Warnung, dass kein Agenten-Binary in PATH gefunden wurde; der Hook-Befehl wird trotzdem geschrieben, sodass er aktiviert wird, sobald du eine installierst. -Sie können `policies-config.json` jederzeit direkt bearbeiten; Änderungen treten sofort beim nächsten Hook-Ereignis in Kraft, ohne dass ein Neustart erforderlich ist. +Du kannst `policies-config.json` jederzeit direkt bearbeiten; Änderungen wirken sich sofort beim nächsten Hook-Ereignis aus, ohne dass ein Neustart erforderlich ist. --- ## Beispiel: Konfiguration auf Projektebene mit Team-Standardwerten -Committen Sie `.failproofai/policies-config.json` in Ihr Repository: +Checke `.failproofai/policies-config.json` in dein Repository ein: ```json { @@ -245,4 +259,4 @@ Committen Sie `.failproofai/policies-config.json` in Ihr Repository: } ``` -Jeder Entwickler kann dann `.failproofai/policies-config.local.json` (per .gitignore ausgeschlossen) für persönliche Overrides erstellen, ohne Teammitglieder zu beeinflussen. \ No newline at end of file +Jeder Entwickler kann dann `.failproofai/policies-config.local.json` (per .gitignore ausgeschlossen) für persönliche Überschreibungen erstellen, ohne Teamkollegen zu beeinflussen. \ No newline at end of file diff --git a/docs/de/custom-policies.mdx b/docs/de/custom-policies.mdx index 9411c78e..c7ab222c 100644 --- a/docs/de/custom-policies.mdx +++ b/docs/de/custom-policies.mdx @@ -1,10 +1,10 @@ --- -title: Benutzerdefinierte Richtlinien +title: Eigene Richtlinien description: "Schreibe eigene Richtlinien in JavaScript – Konventionen durchsetzen, Drift verhindern, Fehler erkennen, externe Systeme integrieren" icon: code --- -Benutzerdefinierte Richtlinien ermöglichen es dir, Regeln für beliebiges Agentenverhalten zu schreiben: Projektkonventionen durchsetzen, Drift verhindern, destruktive Operationen kontrollieren, feststeckende Agenten erkennen oder Integrationen mit Slack, Genehmigungsworkflows und mehr umsetzen. Sie verwenden dasselbe Hook-Ereignissystem und die gleichen `allow`-, `deny`- und `instruct`-Entscheidungen wie eingebaute Richtlinien. +Eigene Richtlinien ermöglichen es dir, Regeln für jedes Agentenverhalten zu definieren: Projektkonventionen durchsetzen, Drift verhindern, destruktive Operationen absichern, feststeckende Agenten erkennen oder Slack, Genehmigungsworkflows und mehr integrieren. Sie verwenden dasselbe Hook-Event-System und dieselben `allow`-, `deny`- und `instruct`-Entscheidungen wie die eingebauten Richtlinien. --- @@ -37,14 +37,14 @@ failproofai policies --install --custom ./my-policies.js --- -## Zwei Wege zum Laden benutzerdefinierter Richtlinien +## Zwei Wege zum Laden eigener Richtlinien ### Option 1: Konventionsbasiert (empfohlen) -Lege `*policies.{js,mjs,ts}`-Dateien in `.failproofai/policies/` ab und sie werden automatisch geladen – keine Flags oder Konfigurationsänderungen erforderlich. Das funktioniert wie Git-Hooks: Datei ablegen, fertig. +Lege `*policies.{js,mjs,ts}`-Dateien in `.failproofai/policies/` ab – sie werden automatisch geladen, ohne Flags oder Konfigurationsänderungen. Das funktioniert wie Git-Hooks: Datei ablegen, fertig. ``` -# Projektebene — ins Git eingecheckt, wird mit dem Team geteilt +# Projektebene — in Git eingecheckt, im Team geteilt .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs @@ -53,36 +53,41 @@ Lege `*policies.{js,mjs,ts}`-Dateien in `.failproofai/policies/` ab und sie werd ``` **So funktioniert es:** -- Sowohl Projekt- als auch Benutzerverzeichnisse werden durchsucht (Vereinigung – kein Gewinnen durch den ersten Scope) -- Dateien werden innerhalb jedes Verzeichnisses alphabetisch geladen. Mit `01-`, `02-` etc. lässt sich die Reihenfolge steuern -- Nur Dateien, die `*policies.{js,mjs,ts}` entsprechen, werden geladen; andere Dateien werden ignoriert +- Sowohl Projekt- als auch Benutzerverzeichnisse werden durchsucht (Vereinigung – kein Vorrang nach Scope) +- Dateien werden innerhalb jedes Verzeichnisses alphabetisch geladen. Mit `01-`, `02-` kann die Reihenfolge gesteuert werden +- Nur Dateien, die auf `*policies.{js,mjs,ts}` passen, werden geladen; andere Dateien werden ignoriert - Jede Datei wird unabhängig geladen (fail-open pro Datei) -- Funktioniert neben explizitem `--custom` und eingebauten Richtlinien +- Funktioniert zusammen mit explizitem `--custom` und eingebauten Richtlinien -Konventionsbasierte Richtlinien sind der einfachste Weg, einen Qualitätsstandard für deine Organisation aufzubauen. Checke `.failproofai/policies/` ins Git ein und jedes Teammitglied erhält automatisch dieselben Regeln – kein individuelles Setup nötig. Wenn dein Team neue Fehlermuster entdeckt, füge einfach eine Richtlinie hinzu und pushe. Mit der Zeit werden diese zu einem lebendigen Qualitätsstandard, der sich mit jedem Beitrag weiterentwickelt. +Konventionsbasierte Richtlinien sind der einfachste Weg, einen Qualitätsstandard für deine Organisation aufzubauen. Checke `.failproofai/policies/` in Git ein, und jedes Teammitglied erhält automatisch dieselben Regeln – ohne individuelle Einrichtung. Wenn dein Team neue Fehlermuster entdeckt, füge eine Richtlinie hinzu und pushe. Mit der Zeit werden diese zu einem lebendigen Qualitätsstandard, der mit jedem Beitrag besser wird. ### Option 2: Expliziter Dateipfad ```bash -# Mit einer benutzerdefinierten Richtliniendatei installieren +# Mit einer eigenen Richtliniendatei installieren failproofai policies --install --custom ./my-policies.js -# Den Richtliniendateipfad ersetzen +# Die eigenen Richtlinienpfade ersetzen failproofai policies --install --custom ./new-policies.js -# Den benutzerdefinierten Richtlinienpfad aus der Konfiguration entfernen +# Mehrere explizite Dateien konfigurieren (in der Reihenfolge der Flags geladen) +failproofai policies --install --custom ./security.js --custom ./workflow.js + +# Alle expliziten eigenen Richtlinienpfade aus der Konfiguration entfernen failproofai policies --uninstall --custom ``` -Der aufgelöste absolute Pfad wird in `policies-config.json` als `customPoliciesPath` gespeichert. Die Datei wird bei jedem Hook-Ereignis frisch geladen – es gibt kein Caching zwischen Ereignissen. +Aufgelöste absolute Pfade werden in `policies-config.json` als `customPoliciesPaths` gespeichert. `--custom` kann mehrfach angegeben werden, um mehrere Dateien zu konfigurieren. Bestehende Konfigurationen, die das veraltete Feld `customPoliciesPath` verwenden, funktionieren weiterhin. Dateien werden bei jedem Hook-Event frisch geladen – es gibt kein Caching zwischen Events. + +Jede registrierte Richtlinie erscheint mit einem eigenen Schalter im Dashboard. Wird eine Richtlinie deaktiviert, wird ihre quellenqualifizierte ID in `disabledCustomPolicies` eingetragen; die Datei und ihre anderen Richtlinien werden weiterhin geladen, während die deaktivierte Richtlinie vor dem Event-Matching ausgeschlossen wird. Richtliniennamen, die in mehreren Dateien vorkommen, haben unabhängige Schalter. -### Beide Varianten zusammen verwenden +### Beides zusammen verwenden -Konventionsbasierte Richtlinien und die explizite `--custom`-Datei können nebeneinander existieren. Ladereihenfolge: +Konventionsbasierte Richtlinien und explizite `--custom`-Dateien können nebeneinander existieren. Ladereihenfolge: -1. Explizite `customPoliciesPath`-Datei (sofern konfiguriert) +1. Explizite `customPoliciesPaths`-Dateien (in konfigurierter Reihenfolge) 2. Projektkonventionsdateien (`{cwd}/.failproofai/policies/`, alphabetisch) 3. Benutzerkonventionsdateien (`~/.failproofai/policies/`, alphabetisch) @@ -102,41 +107,41 @@ Registriert eine Richtlinie. Kann beliebig oft aufgerufen werden, um mehrere Ric ```ts customPolicies.add({ - name: string; // erforderlich - eindeutiger Bezeichner - description?: string; // wird in der `failproofai policies`-Ausgabe angezeigt - match?: { events?: HookEventType[] }; // nach Ereignistyp filtern; weglassen für alle Ereignisse + name: string; // required - unique identifier + description?: string; // shown in `failproofai policies` output + match?: { events?: HookEventType[] }; // filter by event type; omit to match all fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` ### Entscheidungs-Hilfsfunktionen -| Funktion | Wirkung | Wann verwenden | -|----------|---------|----------------| -| `allow()` | Operation lautlos zulassen | Die Aktion ist sicher, keine Meldung nötig | -| `deny(message)` | Operation blockieren | Der Agent sollte diese Aktion nicht ausführen | -| `instruct(message)` | Kontext hinzufügen ohne zu blockieren | Dem Agenten zusätzlichen Kontext geben, um auf Kurs zu bleiben | +| Funktion | Wirkung | Verwendung | +|----------|---------|-----------| +| `allow()` | Operation stillschweigend erlauben | Die Aktion ist sicher, keine Nachricht nötig | +| `deny(message)` | Operation blockieren | Der Agent soll diese Aktion nicht ausführen | +| `instruct(message)` | Kontext hinzufügen ohne zu blockieren | Dem Agenten zusätzlichen Kontext geben, damit er auf Kurs bleibt | -`deny(message)` – die Nachricht erscheint bei Claude mit dem Präfix `"Blocked by failproofai:"`. Ein einzelnes `deny` schließt alle weiteren Auswertungen kurz. +`deny(message)` – die Nachricht erscheint bei Claude mit dem Präfix `"Blocked by failproofai:"`. Ein einzelnes `deny` bricht die gesamte weitere Auswertung ab. -`instruct(message)` – die Nachricht wird dem Claude-Kontext für den aktuellen Tool-Aufruf angehängt. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam übermittelt. +`instruct(message)` – die Nachricht wird für den aktuellen Tool-Aufruf an Claudes Kontext angehängt. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam zugestellt. -Du kannst jeder `deny`- oder `instruct`-Nachricht zusätzliche Hinweise hinzufügen, indem du ein `hint`-Feld in `policyParams` setzt – ohne Codeänderung. Das funktioniert auch für benutzerdefinierte (`custom/`), Projektkonventions- (`.failproofai-project/`) und Benutzerkonventions- (`.failproofai-user/`) Richtlinien. Siehe [Konfiguration → hint](/de/configuration#hint-cross-cutting) für Details. +Zu jeder `deny`- oder `instruct`-Nachricht kann zusätzliche Anleitung hinzugefügt werden, indem ein `hint`-Feld in `policyParams` gesetzt wird – ohne Codeänderung. Dies funktioniert auch für eigene (`custom/`), Projektkonventions- (`.failproofai-project/`) und Benutzerkonventionsrichtlinien (`.failproofai-user/`). Weitere Details unter [Konfiguration → hint](/de/configuration#hint-cross-cutting). -### Informelle allow-Nachrichten +### Informative allow-Nachrichten -`allow(message)` erlaubt die Operation **und** sendet eine informelle Nachricht an Claude zurück. Die Nachricht wird als `additionalContext` in der stdout-Antwort des Hook-Handlers übermittelt – derselbe Mechanismus wie bei `instruct`, jedoch semantisch verschieden: Es handelt sich um ein Statusupdate, nicht um eine Warnung. +`allow(message)` erlaubt die Operation **und** sendet eine informative Nachricht an Claude zurück. Die Nachricht wird als `additionalContext` in der Hook-Handler-Antwort über stdout zugestellt – derselbe Mechanismus wie bei `instruct`, aber semantisch unterschiedlich: Es ist eine Statusmeldung, keine Warnung. -| Funktion | Wirkung | Wann verwenden | -|----------|---------|----------------| -| `allow(message)` | Erlauben und Kontext an Claude senden | Eine bestandene Prüfung bestätigen oder erklären, warum eine Prüfung übersprungen wurde | +| Funktion | Wirkung | Verwendung | +|----------|---------|-----------| +| `allow(message)` | Erlauben und Kontext an Claude senden | Bestätigen, dass eine Prüfung bestanden wurde, oder erklären, warum eine Prüfung übersprungen wurde | Anwendungsfälle: - **Statusbestätigungen:** `allow("All CI checks passed.")` – teilt Claude mit, dass alles in Ordnung ist -- **Fail-open-Erklärungen:** `allow("GitHub CLI not installed, skipping CI check.")` – teilt Claude mit, warum eine Prüfung übersprungen wurde, damit der Agent vollständigen Kontext hat -- **Mehrere Nachrichten häufen sich an:** Wenn mehrere Richtlinien jeweils `allow(message)` zurückgeben, werden alle Nachrichten mit Zeilenumbrüchen verbunden und gemeinsam übermittelt +- **Fail-open-Erklärungen:** `allow("GitHub CLI not installed, skipping CI check.")` – teilt Claude mit, warum eine Prüfung übersprungen wurde, damit er vollständigen Kontext hat +- **Mehrere Nachrichten werden akkumuliert:** Wenn mehrere Richtlinien jeweils `allow(message)` zurückgeben, werden alle Nachrichten mit Zeilenumbrüchen verbunden und gemeinsam zugestellt ```js customPolicies.add({ @@ -146,7 +151,7 @@ customPolicies.add({ const cwd = ctx.session?.cwd; if (!cwd) return allow("No working directory, skipping branch check."); - // ... Branch-Status prüfen ... + // ... check branch status ... if (allPushed) { return allow("Branch is up to date with remote."); } @@ -158,27 +163,27 @@ customPolicies.add({ ### `PolicyContext`-Felder | Feld | Typ | Beschreibung | -|------|-----|--------------| +|------|-----|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | | `toolName` | `string \| undefined` | Das aufgerufene Tool (z. B. `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | Die Eingabeparameter des Tools | -| `payload` | `Record` | Vollständige rohe Ereignisnutzlast von Claude Code | +| `payload` | `Record` | Vollständige rohe Event-Payload von Claude Code | | `session` | `SessionMetadata \| undefined` | Sitzungskontext (siehe unten) | ### `SessionMetadata`-Felder | Feld | Typ | Beschreibung | -|------|-----|--------------| -| `sessionId` | `string` | Claude Code-Sitzungsbezeichner | +|------|-----|-------------| +| `sessionId` | `string` | Claude Code-Sitzungskennung | | `cwd` | `string` | Arbeitsverzeichnis der Claude Code-Sitzung | | `transcriptPath` | `string` | Pfad zur JSONL-Transkriptdatei der Sitzung | -### Ereignistypen +### Event-Typen -| Ereignis | Wann es ausgelöst wird | `toolInput`-Inhalt | -|----------|------------------------|-------------------| -| `PreToolUse` | Bevor Claude ein Tool ausführt | Die Tool-Eingabe (z. B. `{ command: "..." }` für Bash) | -| `PostToolUse` | Nachdem ein Tool abgeschlossen ist | Die Tool-Eingabe + `tool_result` (die Ausgabe) | +| Event | Wann es ausgelöst wird | Inhalt von `toolInput` | +|-------|----------------------|----------------------| +| `PreToolUse` | Bevor Claude ein Tool ausführt | Die Eingabe des Tools (z. B. `{ command: "..." }` für Bash) | +| `PostToolUse` | Nachdem ein Tool abgeschlossen hat | Die Eingabe des Tools + `tool_result` (die Ausgabe) | | `Notification` | Wenn Claude eine Benachrichtigung sendet | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` – Hooks müssen immer `allow()` zurückgeben, sie können Benachrichtigungen nicht blockieren | | `Stop` | Wenn die Claude-Sitzung endet | Leer | @@ -189,19 +194,19 @@ customPolicies.add({ Richtlinien werden in dieser Reihenfolge ausgewertet: 1. Eingebaute Richtlinien (in Definitionsreihenfolge) -2. Explizite benutzerdefinierte Richtlinien aus `customPoliciesPath` (in `.add()`-Reihenfolge) -3. Konventionsbasierte Richtlinien aus dem Projektverzeichnis `.failproofai/policies/` (Dateien alphabetisch, `.add()`-Reihenfolge innerhalb) -4. Konventionsbasierte Richtlinien aus dem Benutzerverzeichnis `~/.failproofai/policies/` (Dateien alphabetisch, `.add()`-Reihenfolge innerhalb) +2. Explizite eigene Richtlinien aus `customPoliciesPath` (in `.add()`-Reihenfolge) +3. Konventionsrichtlinien aus dem Projekt `.failproofai/policies/` (Dateien alphabetisch, `.add()`-Reihenfolge innerhalb) +4. Konventionsrichtlinien aus dem Benutzerverzeichnis `~/.failproofai/policies/` (Dateien alphabetisch, `.add()`-Reihenfolge innerhalb) -Das erste `deny` schließt alle nachfolgenden Richtlinien kurz. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam übermittelt. +Das erste `deny` bricht alle nachfolgenden Richtlinien ab. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam zugestellt. --- ## Transitive Importe -Benutzerdefinierte Richtliniendateien können lokale Module über relative Pfade importieren: +Eigene Richtliniendateien können lokale Module mit relativen Pfaden importieren: ```js // my-policies.js @@ -218,13 +223,13 @@ customPolicies.add({ }); ``` -Alle von der Einstiegsdatei aus erreichbaren relativen Importe werden aufgelöst. Dies wird durch das Umschreiben von `from "failproofai"`-Importen auf den tatsächlichen dist-Pfad und das Erstellen temporärer `.mjs`-Dateien implementiert, um ESM-Kompatibilität sicherzustellen. +Alle relativen Importe, die von der Einstiegsdatei aus erreichbar sind, werden aufgelöst. Dies wird implementiert, indem `from "failproofai"`-Importe auf den tatsächlichen dist-Pfad umgeschrieben und temporäre `.mjs`-Dateien erstellt werden, um ESM-Kompatibilität sicherzustellen. --- -## Ereignistypfilterung +## Event-Typ-Filterung -Verwende `match.events`, um einzuschränken, wann eine Richtlinie ausgelöst wird: +Mit `match.events` kann eingeschränkt werden, wann eine Richtlinie ausgelöst wird: ```js customPolicies.add({ @@ -238,26 +243,26 @@ customPolicies.add({ }); ``` -Lasse `match` vollständig weg, um bei jedem Ereignistyp auszulösen. +`match` vollständig weglassen, um bei jedem Event-Typ auszulösen. --- -## Fehlerbehandlung und Ausfallverhalten +## Fehlerbehandlung und Fehlermodi -Benutzerdefinierte Richtlinien sind **fail-open**: Fehler blockieren niemals eingebaute Richtlinien und bringen den Hook-Handler nicht zum Absturz. +Eigene Richtlinien sind **fail-open**: Fehler blockieren niemals eingebaute Richtlinien oder bringen den Hook-Handler zum Absturz. | Fehler | Verhalten | -|--------|-----------| -| `customPoliciesPath` nicht gesetzt | Keine expliziten benutzerdefinierten Richtlinien werden ausgeführt; Konventionsrichtlinien und eingebaute Richtlinien laufen normal weiter | -| Datei nicht gefunden | Warnung wird in `~/.failproofai/hook.log` protokolliert; eingebaute Richtlinien laufen weiter | -| Syntax-/Importfehler (explizit) | Fehler wird in `~/.failproofai/hook.log` protokolliert; explizite benutzerdefinierte Richtlinien werden übersprungen | -| Syntax-/Importfehler (Konvention) | Fehler wird protokolliert; diese Datei wird übersprungen, andere Konventionsdateien werden weiterhin geladen | -| `fn` wirft zur Laufzeit | Fehler wird protokolliert; dieser Hook wird als `allow` behandelt; andere Hooks laufen weiter | -| `fn` dauert länger als 10 Sekunden | Timeout wird protokolliert; als `allow` behandelt | +|--------|----------| +| `customPoliciesPath` nicht gesetzt | Keine expliziten eigenen Richtlinien werden ausgeführt; Konventionsrichtlinien und eingebaute Richtlinien laufen normal weiter | +| Datei nicht gefunden | Warnung in `~/.failproofai/hook.log` protokolliert; eingebaute Richtlinien laufen weiter | +| Syntax-/Importfehler (explizit) | Fehler in `~/.failproofai/hook.log` protokolliert; explizite eigene Richtlinien übersprungen | +| Syntax-/Importfehler (Konvention) | Fehler protokolliert; diese Datei übersprungen, andere Konventionsdateien werden weiterhin geladen | +| `fn` wirft zur Laufzeit | Fehler protokolliert; dieser Hook wird als `allow` behandelt; andere Hooks laufen weiter | +| `fn` dauert länger als 10 Sekunden | Timeout protokolliert; wird als `allow` behandelt | | Konventionsverzeichnis fehlt | Keine Konventionsrichtlinien werden ausgeführt; kein Fehler | -Um Fehler in benutzerdefinierten Richtlinien zu debuggen, beobachte die Protokolldatei: +Um Fehler in eigenen Richtlinien zu debuggen, beobachte die Protokolldatei: ```bash tail -f ~/.failproofai/hook.log @@ -272,7 +277,7 @@ tail -f ~/.failproofai/hook.log // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// Verhindert, dass der Agent in das Verzeichnis secrets/ schreibt +// Prevent agent from writing to secrets/ directory customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -285,7 +290,7 @@ customPolicies.add({ }, }); -// Hält den Agenten auf Kurs: Tests vor dem Commit überprüfen +// Keep the agent on track: verify tests before committing customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +305,7 @@ customPolicies.add({ }, }); -// Verhindert ungeplante Abhängigkeitsänderungen während einer Freeze-Periode +// Prevent unplanned dependency changes during freeze customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -323,14 +328,14 @@ export { customPolicies }; ## Beispiele -Das Verzeichnis `examples/` enthält sofort einsatzbereite Richtliniendateien: +Das Verzeichnis `examples/` enthält sofort einsetzbare Richtliniendateien: | Datei | Inhalt | |-------|--------| -| `examples/policies-basic.js` | Fünf Einstiegsrichtlinien für häufige Agenten-Fehlermuster | -| `examples/policies-advanced/index.js` | Fortgeschrittene Muster: transitive Importe, asynchrone Aufrufe, Ausgabebereinigung und Sitzungsende-Hooks | -| `examples/convention-policies/security-policies.mjs` | Konventionsbasierte Sicherheitsrichtlinien (Blockierung von .env-Schreibvorgängen, Verhinderung von Git-History-Rewrites) | -| `examples/convention-policies/workflow-policies.mjs` | Konventionsbasierte Workflow-Richtlinien (Test-Erinnerungen, Überwachung von Datei-Schreibvorgängen) | +| `examples/policies-basic.js` | Fünf Starter-Richtlinien für häufige Agentenfehlermodi | +| `examples/policies-advanced/index.js` | Fortgeschrittene Muster: transitive Importe, asynchrone Aufrufe, Output-Bereinigung und Sitzungsende-Hooks | +| `examples/convention-policies/security-policies.mjs` | Konventionsbasierte Sicherheitsrichtlinien (blockiert .env-Schreibzugriffe, verhindert Umschreiben der Git-Historie) | +| `examples/convention-policies/workflow-policies.mjs` | Konventionsbasierte Workflow-Richtlinien (Test-Erinnerungen, Protokollierung von Dateischreibzugriffen) | ### Explizite Dateibeispiele verwenden @@ -350,4 +355,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -Kein Installationsbefehl erforderlich – die Dateien werden beim nächsten Hook-Ereignis automatisch erkannt. \ No newline at end of file +Kein Installationsbefehl nötig – die Dateien werden beim nächsten Hook-Event automatisch erkannt. \ No newline at end of file diff --git a/docs/de/dashboard.mdx b/docs/de/dashboard.mdx index 820ba98b..0d2ebacc 100644 --- a/docs/de/dashboard.mdx +++ b/docs/de/dashboard.mdx @@ -1,10 +1,10 @@ --- title: Dashboard -description: "Agent-Sitzungen überwachen, Tool-Aufrufe einsehen und Richtlinien verwalten" +description: "Agent-Sitzungen überwachen, Tool-Aufrufe prüfen und Richtlinien verwalten" icon: chart-line --- -Das failproofai Dashboard ist eine lokale Webanwendung zur Überwachung Ihrer KI-Agent-Sitzungen und zur Verwaltung von Richtlinien. Sehen Sie nach, was Ihre Agenten in Ihrer Abwesenheit getan haben. +Das failproofai-Dashboard ist eine lokale Webanwendung zur Überwachung Ihrer KI-Agent-Sitzungen und zur Verwaltung von Richtlinien. Sehen Sie, was Ihre Agenten in Ihrer Abwesenheit getan haben. --- @@ -16,7 +16,7 @@ failproofai Öffnet sich unter `http://localhost:8020`. -Das Dashboard liest lokale Projekt-, Sitzungs- und failproofai-Konfigurationsdaten direkt vom Dateisystem. Optionale authentifizierte Funktionen, wie Audit-Erinnerungen und Einladungen, übermitteln die für diese Anfragen benötigten Informationen (einschließlich E-Mail-Adressen) an Remote-APIs. +Das Dashboard liest lokale Projekt-, Sitzungs- und failproofai-Konfigurationsdaten direkt aus dem Dateisystem. Optionale authentifizierte Funktionen, wie Audit-Erinnerungen und Einladungen, senden die für diese Anfragen benötigten Informationen (einschließlich E-Mail-Adressen) an Remote-APIs. --- @@ -24,11 +24,13 @@ Das Dashboard liest lokale Projekt-, Sitzungs- und failproofai-Konfigurationsdat ### Projekte -Listet alle auf Ihrem Rechner gefundenen Claude Code-, OpenAI Codex-, GitHub Copilot CLI- _(Beta)_, Cursor Agent- _(Beta)_, OpenCode- _(Beta)_, Pi- _(Beta)_, Hermes-, OpenClaw-, Factory Droid-, Devin-, Antigravity- und Goose-Projekte auf. Claude-Projekte werden aus `~/.claude/projects/` (oder dem über `CLAUDE_PROJECTS_PATH` gesetzten Pfad) ermittelt; Codex-Projekte werden durch Scannen aller Transkripte unter `~/.codex/sessions///
/*.jsonl` und Gruppierung nach dem im ersten Datensatz jeder Sitzung gespeicherten `cwd` gefunden; Copilot CLI-Projekte werden durch Scannen jeder `~/.copilot/session-state//workspace.yaml` (konfigurierbar über `COPILOT_HOME`) und Gruppierung nach dem `cwd`-Feld ermittelt; Cursor Agent-Projekte werden durch Scannen von sitzungsspezifischen Metadaten unter `~/.cursor/agent-sessions//` (konfigurierbar über `CURSOR_HOME`, mit `conversations/` und `sessions/` als Fallbacks) nach einem `cwd`-Skalar in `meta.json` / `session.json` / `workspace.yaml` gefunden; OpenCode-Projekte werden durch Abfrage seiner SQLite-Datenbank unter `~/.local/share/opencode/opencode.db` via `opencode db --format json` ermittelt (es werden die Tabellen `session` und `project` gelesen und nach `project_id` gruppiert); Pi-Projekte werden durch Scannen von sitzungsspezifischen JSONL-Transkripten unter `~/.pi/agent/sessions//_.jsonl` (konfigurierbar über `PI_SESSIONS_DIR`) und Auslesen des `cwd` aus dem ersten Datensatz jeder Sitzung gefunden; Hermes Gateway-Sitzungen werden direkt aus dem SQLite-Speicher unter `~/.hermes/state.db` (konfigurierbar über `HERMES_DB_PATH`) gelesen und nach `source` (Slack/Telegram/cli/cron — Gateway-Sitzungen haben kein cwd) in `hermes-`-Projekte gruppiert; OpenClaw Gateway-Sitzungen werden aus `~/.openclaw/agents//sessions/*.jsonl` gelesen und in `openclaw-`-Projekte gruppiert (ebenfalls ohne cwd); Factory Droid-Projekte werden aus den JSONL-Transkripten unter `~/.factory/sessions//*.jsonl` ermittelt und nach cwd gruppiert; Devin-Projekte aus seiner SQLite-Datenbank unter `~/.local/share/devin/cli/sessions.db` (gruppiert nach dem `working_directory` jeder Sitzung); Antigravity-Projekte aus den JSONL-Transkripten unter `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` und nach cwd gruppiert; und Goose-Projekte aus seiner SQLite-Datenbank unter `~/.local/share/goose/sessions/sessions.db` (gruppiert nach dem `working_dir` jeder Sitzung). Ein Projekt, das von mehreren CLIs verwendet wurde, wird als einzelne Zeile mit allen passenden Badges dargestellt. Verwenden Sie das **CLI**-Dropdown über der Tabelle, um nach einer bestimmten Agent-CLI zu filtern; die URL behält Ihre Auswahl als `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` bei. +Listet alle Claude Code-, OpenAI Codex-, GitHub Copilot CLI- _(Beta)_, Cursor Agent- _(Beta)_, OpenCode- _(Beta)_, Pi- _(Beta)_, Hermes-, OpenClaw-, Factory Droid-, Devin-, Antigravity- und Goose-Projekte auf, die auf Ihrem Rechner gefunden wurden. Claude-Projekte werden aus `~/.claude/projects/` entdeckt (oder dem Pfad, der durch `CLAUDE_PROJECTS_PATH` gesetzt wurde); Codex-Projekte werden durch das Scannen aller Transkripte unter `~/.codex/sessions///
/*.jsonl` und Gruppierung nach dem im ersten Datensatz jeder Sitzung aufgezeichneten `cwd` entdeckt; Copilot CLI-Projekte werden durch das Scannen jeder `~/.copilot/session-state//workspace.yaml` (konfigurierbar über `COPILOT_HOME`) und Gruppierung nach dem `cwd`-Feld entdeckt; Cursor Agent-Projekte werden durch das Scannen sitzungsspezifischer Metadaten unter `~/.cursor/agent-sessions//` (konfigurierbar über `CURSOR_HOME`, mit `conversations/` und `sessions/` als Fallbacks) nach einem `cwd`-Skalar in `meta.json` / `session.json` / `workspace.yaml` entdeckt; OpenCode-Projekte werden durch Abfragen seiner SQLite-Datenbank unter `~/.local/share/opencode/opencode.db` via `opencode db --format json` entdeckt (wir lesen die Tabellen `session` und `project` und gruppieren nach `project_id`); Pi-Projekte werden durch das Scannen sitzungsspezifischer JSONL-Transkripte unter `~/.pi/agent/sessions//_.jsonl` (konfigurierbar über `PI_SESSIONS_DIR`) und Auslesen des `cwd` aus dem ersten Datensatz jeder Sitzung entdeckt; Hermes-Gateway-Sitzungen werden direkt aus dem SQLite-Store jedes Profils gelesen — `~/.hermes/state.db` plus `~/.hermes/profiles//state.db` (überschreibbar über `HERMES_HOME` oder `HERMES_DB_PATH` für eine einzelne Datenbank) — und nach Profil und `source` (Slack/Telegram/cli/cron — Gateway-Sitzungen haben kein cwd) in `hermes--`-Projekte gruppiert; OpenClaw-Gateway-Sitzungen werden aus `~/.openclaw/agents//sessions/*.jsonl` gelesen und nach Agent und Kanal in `openclaw--`-Projekte gruppiert (ebenfalls ohne cwd); Factory Droid-Projekte werden aus den JSONL-Transkripten unter `~/.factory/sessions//*.jsonl` entdeckt und nach cwd gruppiert; Devin-Projekte aus seiner SQLite-Datenbank unter `~/.local/share/devin/cli/sessions.db` (gruppiert nach `working_directory` jeder Sitzung); Antigravity-Projekte aus den JSONL-Transkripten unter `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` und nach cwd gruppiert; und Goose-Projekte aus seiner SQLite-Datenbank unter `~/.local/share/goose/sessions/sessions.db` (gruppiert nach `working_dir` jeder Sitzung). Ein Projekt, das von mehreren CLIs verwendet wurde, wird als einzelne Zeile mit allen passenden Badges angezeigt. Verwenden Sie das **CLI**-Dropdown über der Tabelle, um nach einer bestimmten Agent-CLI zu filtern; die URL speichert Ihre Auswahl als `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. + +Hermes und OpenClaw sind benutzerspezifisch und haben kein Arbeitsverzeichnis zur Gruppierung, daher werden sie als **aufklappbarer Ordnerbaum** dargestellt — Profil (oder Agent) auf der obersten Ebene, seine Kanäle darunter — während jede cwd-basierte CLI als flache Zeile dargestellt wird. Ordnerzeilen summieren die Sitzungsanzahl und die neueste Aktivität aller enthaltenen Elemente, eingeklappte Ordner werden zwischen Besuchen gespeichert, und eine Schlüsselwortsuche klappt alle Treffer auf. Jedes Projekt zeigt: -- Projektname (abgeleitet vom Ordnerpfad) -- Ein CLI-Badge — `Claude Code` (orange), `OpenAI Codex` (lila), `GitHub Copilot` (blau), `Cursor Agent` (smaragdgrün), `OpenCode` (bernstein), `Pi` (pink) und/oder `Hermes` (indigo) +- Projektname (abgeleitet aus dem Ordnerpfad) +- Ein CLI-Badge — `Claude Code` (orange), `OpenAI Codex` (lila), `GitHub Copilot` (blau), `Cursor Agent` (smaragd), `OpenCode` (bernstein), `Pi` (pink) und/oder `Hermes` (indigo) - Datum der letzten Sitzungsaktivität Klicken Sie auf ein Projekt, um seine Sitzungen anzuzeigen. @@ -37,54 +39,54 @@ Klicken Sie auf ein Projekt, um seine Sitzungen anzuzeigen. Listet alle Sitzungen innerhalb eines Projekts auf. Jede Sitzung zeigt: - Sitzungs-ID -- Start- und Endzeitpunkt +- Start- und Endzeitstempel - Anzahl der Tool-Aufrufe -- Anzahl der Hook-Aktivitäten (ausgelöste Richtlinien) +- Hook-Aktivitätszähler (ausgelöste Richtlinien) -Verwenden Sie den Datumsbereichsfilter und die Sitzungs-ID-Suche, um die Liste einzugrenzen. Sitzungen sind paginiert. +Verwenden Sie den Datumsbereichsfilter und die Sitzungs-ID-Suche, um die Liste einzugrenzen. Sitzungen werden seitenweise angezeigt. -Klicken Sie auf eine Sitzung, um den Sitzungs-Viewer zu öffnen. +Klicken Sie auf eine Sitzung, um den Sitzungsviewer zu öffnen. -### Sitzungs-Viewer +### Sitzungsviewer -Der Sitzungs-Viewer beantwortet die zentrale Frage bei autonomen Agenten: Was hat der Agent getan, und ist er auf Kurs geblieben? Ein CLI-Badge neben dem Header gibt an, ob es sich um ein Claude Code-, OpenAI Codex-, GitHub Copilot CLI-, Cursor Agent-, OpenCode-, Pi-, Hermes-, OpenClaw-, Factory Droid-, Devin-, Antigravity- oder Goose-Transkript handelt. Er zeigt eine Zeitleiste aller Ereignisse in einer Sitzung: +Der Sitzungsviewer beantwortet die zentrale Frage bei autonomen Agenten: Was hat der Agent getan, und ist er auf Kurs geblieben? Ein CLI-Badge neben der Überschrift zeigt an, ob die Sitzung ein Claude Code-, OpenAI Codex-, GitHub Copilot CLI-, Cursor Agent-, OpenCode-, Pi-, Hermes-, OpenClaw-, Factory Droid-, Devin-, Antigravity- oder Goose-Transkript ist. Er zeigt eine Zeitleiste aller Ereignisse in einer Sitzung: - **Nachrichten** - Claudes Textantworten und Benutzeranfragen -- **Tool-Aufrufe** - Jedes von Claude aufgerufene Tool, mit Ein- und Ausgabe -- **Richtlinienaktivität** - Für jeden Tool-Aufruf: welche Richtlinien ausgelöst wurden und welche Entscheidung sie zurückgegeben haben +- **Tool-Aufrufe** - Jedes von Claude aufgerufene Tool, mit Eingabe und Ausgabe +- **Richtlinienaktivität** - Für jeden Tool-Aufruf, welche Richtlinien ausgelöst wurden und welche Entscheidung sie zurückgegeben haben -Die Statistikleiste oben zeigt Sitzungsdauer, Gesamtanzahl der Tool-Aufrufe und eine Zusammenfassung der Hook-Entscheidungen (Anzahl von allow / deny / instruct). +Die Statistikleiste oben zeigt Sitzungsdauer, Gesamtzahl der Tool-Aufrufe und eine Zusammenfassung der Hook-Entscheidungen (allow / deny / instruct-Anzahl). -Klicken Sie auf die Schaltfläche **Logs herunterladen**, um die Sitzung zu exportieren. Bei Claude Code-, Codex-, Copilot-, Cursor- und Pi-Sitzungen erhalten Sie das originale JSONL-Transkript auf dem Datenträger Byte für Byte; bei OpenCode (dessen Sitzungen in SQLite, nicht auf dem Datenträger gespeichert sind) erhalten Sie ein JSON-Dokument, das die zugrundeliegenden Tabellen `session` / `messages` / `parts` widerspiegelt. +Klicken Sie auf die Schaltfläche **Logs herunterladen**, um die Sitzung zu exportieren. Bei Claude Code-, Codex-, Copilot-, Cursor- und Pi-Sitzungen erhalten Sie das originale JSONL-Transkript auf der Festplatte byte-für-byte; bei OpenCode (dessen Sitzungen in SQLite und nicht auf der Festplatte gespeichert sind) erhalten Sie ein JSON-Dokument, das die zugrunde liegenden Tabellen `session` / `messages` / `parts` widerspiegelt. ### Audit -Ein charaktergetriebener Bericht darüber, wie sich Ihr Agent tatsächlich über vergangene Sitzungen hinweg verhalten hat. Führt denselben Scan wie die `failproofai audit`-CLI aus, stellt ihn aber als einseitiges, teilbares Poster + vier unterhalb des sichtbaren Bereichs liegende Abschnitte dar: +Ein persönlichkeitsgetriebener Bericht darüber, wie sich Ihr Agent tatsächlich über vergangene Sitzungen hinweg verhalten hat. Führt denselben Scan wie die `failproofai audit`-CLI aus, rendert ihn jedoch als einseitiges, teilbares Poster + vier Abschnitte darunter: -1. **Poster** — füllt den ersten Viewport. Eigenständiger PNG-Erfassungsbereich mit dem failproof_ai-Wortzeichen + Audit-Label · Archetyp-Index (`№ NN of 08`) + Audit-Datum · numerischer Score (0–100) + Perzentil-Rang-Pill (`top 15%`) · der Archetyp-Name (einer von `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + 3-Keyword-Streifen · `// only N% of agents are this archetype`-Rarität-Zeile · 8×8-Pixel-Sigil-Kachel · `audit yours → failproof.ai`-Fußzeile. Drei Teilen-Schaltflächen befinden sich knapp außerhalb des Erfassungsbereichs: `post your archetype` (X Intent), `share on linkedin`, `download poster`. Die Erfassung erfolgt über `html-to-image`, sodass das PNG pixelgenau mit der Bildschirmdarstellung übereinstimmt (gestrichelte Rahmen, SVG-Logo-Maske, Verläufe, Schriftmetriken — alles erhalten). -2. **Stärken** — ruhige ✓-Zeilenliste von Verhaltensweisen, die Ihr Agent bereits richtig macht, abgeleitet aus den Live-Audit-Daten (saubere Tool-Aufruf-Rate, keine direkten Pushes auf main, null Credential-Leaks, null Retry-Stürme) — jede wird nur angezeigt, wenn die entsprechende Richtlinie im Audit-Zeitraum eine saubere Bilanz hat. -3. **Eigenheiten** — Tabelle der durchgeschlüpften Probleme, nach Schweregrad gerankt: `wann · was durchgeschlüpft ist + die Richtlinie, die es abgefangen hätte · Schweregrad-Pill · gesehen`, wobei die Wiederholung als `new` (einmal), `N× seen` (2–9 Mal) oder `recurring` (10+) angegeben wird. -4. **Verbesserungsvorschläge** — ruhige Zeilenliste, eine pro empfohlener Richtlinie: Richtlinienname in Weiß, einzeilige Beschreibung, Installationsbefehl + Kopierschaltfläche auf der rechten Seite. Der Abschnittsheader lautet `enable all N → projected · ` (der Score, den Sie mit allen angewendeten Korrekturen erreichen würden), und die Schaltfläche `[install all]` kopiert den kombinierten `failproofai policy add a b c …`-Befehl für jede empfohlene Richtlinie. -5. **Komm besser zurück** — zwei nebeneinander stehende Karten. Links: Erinnerung setzen (`3d` / `7d` / `14d` / `30d` Kadenz-Auswahl; wird nach Authentifizierung über `/api/auth/reminder` gespeichert). Rechts: failproof-Vorteile freischalten — `invite a friend` öffnet ein Modal, das eine komma-, leerzeichen- oder zeilengetrennte Liste von Freundes-E-Mails akzeptiert (max. 10 pro Sendung), sendet sie per POST an `/api/audit/invite`, was an den `POST /v0/invite` des API-Servers weitergeleitet wird. Der API-Server sendet eine E-Mail pro Empfänger von `invite@failproof.ai` mit dem Absender in Cc und gesetztem `Reply-To`, sodass der Empfänger sieht, wer ihn eingeladen hat, und der Absender eine Kopie in seinem Posteingang erhält. Anonyme Benutzer werden zunächst durch den `AuthDialog` geleitet, damit die E-Mail-Adresse des Absenders bekannt ist, bevor Einladungen verschickt werden. Berechtigungs-/Vorteils-Einlösung ist ein Folgeschritt. +1. **Poster** — füllt den ersten Viewport. Eigenständige PNG-Erfassungsregion mit dem failproof_ai-Wortmarke + Audit-Label · Archetypindex (`№ NN of 08`) + Audit-Datum · numerische Punktzahl (0–100) + Perzentil-Rang-Pille (`top 15%`) · der Archetypname (einer von `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + 3-Schlüsselwort-Streifen · `// only N% of agents are this archetype` Seltenheitszeile · 8×8-Pixel-Sigillen-Kachel · `audit yours → failproof.ai`-Fußzeile. Drei Share-Buttons befinden sich knapp außerhalb der Erfassungsbox: `post your archetype` (X-Intent), `share on linkedin`, `download poster`. Die Erfassung läuft über `html-to-image`, sodass das PNG pixelgenau der Bildschirmdarstellung entspricht (gestrichelte Rahmen, SVG-Logo-Maske, Verläufe, Schriftmetriken — alles erhalten). +2. **Stärken** — ruhige ✓-Zeilenliste der Verhaltensweisen, die Ihr Agent bereits richtig macht, abgeleitet aus den Live-Audit-Daten (saubere Tool-Aufruf-Rate, keine direkten Pushes zu main, null Credential-Lecks, null Retry-Stürme) — jede wird nur angezeigt, wenn die relevante Richtlinie im Audit-Fenster eine saubere Bilanz hat. +3. **Eigenheiten** — Tabelle der Schlupflöcher, nach Schweregrad sortiert: `wann · was durchgerutscht ist + die Richtlinie, die es abgefangen hätte · Schweregrad-Pille · gesehen`, wobei die Häufigkeit `new` (einmal), `N× seen` (2–9 Mal) oder `recurring` (10+) angibt. +4. **Verbesserungen** — ruhige Zeilenliste, eine pro vorgeschriebener Richtlinie: Richtlinienname in Weiß, einzeilige Beschreibung, Installationsbefehl + Kopierschaltfläche rechts. Die Abschnittsüberschrift lautet `enable all N → projected · ` (die Punktzahl, die Sie mit allen angewendeten Fixes erreichen würden), und die Schaltfläche `[install all]` kopiert den kombinierten `failproofai policy add a b c …`-Befehl für jede vorgeschriebene Richtlinie. +5. **Besser wiederkommen** — zwei nebeneinanderliegende Karten. Links: Eine Erinnerung setzen (`3d` / `7d` / `14d` / `30d`-Intervallauswahl; bleibt über `/api/auth/reminder` nach Authentifizierung erhalten). Rechts: Failproof-Vorteile freischalten — `invite a friend` öffnet ein Modal, das eine komma-/leerzeichen-/zeilenumbruch-getrennte Liste von Freundes-E-Mails akzeptiert (maximal 10 pro Versand), sendet einen POST an `/api/audit/invite`, der an den `POST /v0/invite` des API-Servers weitergeleitet wird. Der API-Server sendet eine E-Mail pro Empfänger von `invite@failproof.ai`, mit dem Absender im CC und `Reply-To` gesetzt, sodass der Empfänger sieht, wer ihn eingeladen hat, und der Absender eine Kopie in seinem Posteingang erhält. Anonyme Benutzer werden zuerst durch den `AuthDialog` geleitet, damit die E-Mail des Absenders bekannt ist, bevor Einladungen versendet werden. Berechtigungen / Vorteils-Erfüllung folgt zu einem späteren Zeitpunkt. -Wird von der `failproofai audit`-Laufzeit gesteuert — siehe [Audit CLI](/de/cli/audit) für die zugrundeliegende Scan-Engine, unterstützte Flags und Transkript-Cache-Invarianten. Das Dashboard speichert das neueste Ergebnis unter `~/.failproofai/audit-dashboard.json` (Modus `0600`, einzelner Slot, neue Läufe überschreiben), sodass erneute Besuche sofort laden; **sowohl der Transkript-Cache als auch der Gesamtergebnis-Cache werden beim Lesen verworfen, sobald sie älter als 7 Tage sind**, damit das Dashboard nie stillschweigend ein wochenaltes Ergebnis ausliefert — nach Ablauf der TTL fällt `/audit` in seinen Leerzustand zurück und fordert einen neuen Lauf an. Ein Klick auf `[ re-audit now ]` am unteren Ende des Berichts sendet einen POST an `/api/audit/run` mit `noCache: true` — ein Re-Audit umgeht den Transkript-Cache und scannt jedes Transkript von Grund auf neu, anstatt stillschweigend das gecachte Ergebnis zurückzugeben — und das Dashboard fragt `/api/audit/status` mit 1Hz ab, bis der Lauf abgeschlossen ist; während des Laufs heftet sich ein pinker Fortschrittsstreifen mit einem Zeitmesser oben im Viewport fest, und das neue Ergebnis tauscht sich bei Erfolg an Ort und Stelle aus (kein vollständiges Neuladen der Seite; ein fehlgeschlagener Re-Audit lässt den vorherigen Bericht intakt). Bei einem Fehler wird der Streifen rot mit einem Text, der auf `RerunError.kind` (`timeout` / `network` / `post_failed`) basiert. Leerzustand (kein Cache oder abgelaufen) und Null-Sitzungen-Zustand (Cache vorhanden, aber der Scan fand keine Transkripte) werden separat angezeigt. +Wird durch die `failproofai audit`-Laufzeit angetrieben — siehe [Audit CLI](/de/cli/audit) für die zugrunde liegende Scan-Engine, unterstützte Flags und per-Transkript-Cache-Invarianten. Das Dashboard speichert das neueste Ergebnis unter `~/.failproofai/audit-dashboard.json` (Modus `0600`, einzelner Slot, neue Ausführungen überschreiben) zwischen, sodass erneute Besuche sofort sind; **sowohl die per-Transkript- als auch die Gesamtergebnis-Caches werden beim Lesen abgelehnt, sobald sie älter als 7 Tage sind**, sodass das Dashboard nie stillschweigend ein wochenaltes Ergebnis anzeigt — nach Ablauf der TTL fällt `/audit` in seinen leeren Zustand und fordert eine neue Ausführung an. Ein Klick auf `[ re-audit now ]` unten im Bericht sendet einen POST an `/api/audit/run` mit `noCache: true` — ein erneuter Audit umgeht den per-Transkript-Cache und scannt jedes Transkript von Grund auf neu, anstatt stillschweigend das gecachte Ergebnis zurückzugeben — und das Dashboard fragt `/api/audit/status` mit 1 Hz ab, bis die Ausführung abgeschlossen ist; ein anhaftender pinker Fortschrittsstreifen heftet sich während der Ausführung mit einem Zeitmesser an den oberen Rand des Viewports, und das neue Ergebnis tauscht sich bei Erfolg an Ort und Stelle aus (kein vollständiges Neuladen der Seite; ein fehlgeschlagener erneuter Audit lässt den vorherigen Bericht intakt). Bei einem Fehler wird der Streifen rot mit einem Text, der auf `RerunError.kind` abgestimmt ist (`timeout` / `network` / `post_failed`). Leerer Zustand (kein Cache oder abgelaufen) und Null-Sitzungen-Zustand (Cache vorhanden, aber der Scan fand keine Transkripte) werden separat angezeigt. ### Richtlinien -Eine zweiseitige Seite zur Verwaltung von Richtlinien und Überprüfung von Aktivitäten. +Eine zweireihige Seite zur Verwaltung von Richtlinien und Überprüfung von Aktivitäten. - - Wählen Sie über ein einzelnes Panel aus, welche Agent-CLIs failproofai schützt — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi und Hermes haben je eine Zeile mit Installationsstatus (`Active` / `Detected` / `Inactive`), dem benutzerspezifischen Einstellungspfad und einem markenspezifischen Akzent. Aktivieren oder deaktivieren Sie die gewünschten CLIs und klicken Sie auf `Apply changes`, um die Änderungen in einem Schritt zu installieren/deinstallieren. CLIs, deren Binary im PATH erkannt wird, sind vorausgewählt. - - Einzelne Richtlinien mit einem einzigen Klick ein- oder ausschalten (schreibt in `~/.failproofai/policies-config.json` — geteilt von allen installierten CLIs) - - Eine Richtlinie erweitern, um ihre Parameter zu konfigurieren (für Richtlinien, die `policyParams` unterstützen) - - Einen benutzerdefinierten Richtliniendatei-Pfad festlegen + - Wählen Sie mehrere Agent-CLIs aus, die failproofai über ein einzelnes Panel schützt — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi und Hermes haben jeweils eine Zeile mit Installationsstatus (`Active` / `Detected` / `Inactive`), dem benutzerspezifischen Einstellungspfad und einem markenfarbenigen Akzent. Aktivieren oder deaktivieren Sie die gewünschten CLIs und klicken Sie auf `Apply changes`, um die Änderungen in einem Schritt zu installieren/deinstallieren. CLIs, deren Binary im PATH gefunden wird, sind vorab aktiviert. + - Schalten Sie einzelne Richtlinien mit einem einzigen Klick ein oder aus (schreibt in `~/.failproofai/policies-config.json` — gemeinsam genutzt von jeder installierten CLI) + - Erweitern Sie eine Richtlinie, um ihre Parameter zu konfigurieren (für Richtlinien, die `policyParams` unterstützen) + - Legen Sie einen benutzerdefinierten Richtliniendateipfad fest - - Vollständiger paginierter Verlauf jedes Hook-Ereignisses, das über alle Sitzungen hinweg ausgelöst wurde + - Vollständig seitenweise aufgelisteter Verlauf jedes Hook-Ereignisses, das über alle Sitzungen ausgelöst wurde - Filtern nach Entscheidung, Ereignistyp, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(Beta)_ / Cursor Agent _(Beta)_ / OpenCode _(Beta)_ / Pi _(Beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), Richtlinienname oder Sitzungs-ID - - Jede Zeile zeigt: Zeitstempel, Richtlinienname, Entscheidung, CLI-Badge (orange = Claude Code, lila = OpenAI Codex, blau = GitHub Copilot, smaragdgrün = Cursor Agent, bernstein = OpenCode, pink = Pi, indigo = Hermes, türkis = OpenClaw, rose = Factory Droid, violett = Devin, cyan = Antigravity, lindgrün = Goose), Tool-Name, Sitzungs-ID und der Grund für deny/instruct-Entscheidungen - - Klicken Sie auf eine Sitzungs-ID, um ihr Transkript zu öffnen — der Viewer erkennt automatisch, welche CLI den Hook ausgelöst hat (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) und zeigt das passende CLI-Badge im Header an + - Jede Zeile zeigt: Zeitstempel, Richtlinienname, Entscheidung, CLI-Badge (orange = Claude Code, lila = OpenAI Codex, blau = GitHub Copilot, smaragd = Cursor Agent, bernstein = OpenCode, pink = Pi, indigo = Hermes, petrol = OpenClaw, rosa = Factory Droid, violett = Devin, cyan = Antigravity, limette = Goose), Tool-Name, Sitzungs-ID und den Grund für deny/instruct-Entscheidungen + - Klicken Sie auf eine Sitzungs-ID, um ihr Transkript zu öffnen — der Viewer erkennt automatisch, welche CLI den Hook ausgelöst hat (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) und rendert das passende CLI-Badge in der Kopfzeile @@ -92,7 +94,7 @@ Eine zweiseitige Seite zur Verwaltung von Richtlinien und Überprüfung von Akti ## Automatische Aktualisierung -Das Dashboard verfügt über einen Auto-Refresh-Schalter in der oberen Navigation. Wenn aktiviert, aktualisiert sich die aktuelle Seite regelmäßig, um neue Sitzungen und Richtlinienaktivitäten anzuzeigen, sobald sie auftreten. Unverzichtbar für die Überwachung lang laufender autonomer Agent-Sitzungen. +Das Dashboard verfügt über einen Schalter für die automatische Aktualisierung in der oberen Navigation. Wenn aktiviert, wird die aktuelle Seite regelmäßig aktualisiert, um neue Sitzungen und Richtlinienaktivitäten anzuzeigen, sobald sie auftreten. Unverzichtbar für die Überwachung langfristiger autonomer Agent-Sitzungen. --- @@ -120,13 +122,13 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## Zugriff von einem Nicht-localhost-Host -Wenn Sie das Dashboard im **Dev-Modus** (`npm run dev`) betreiben und von einem anderen Hostnamen als localhost darauf zugreifen — zum Beispiel einer benutzerdefinierten Domain, einer Remote-IP oder einer getunnelten URL — sehen Sie möglicherweise eine Warnung wie: +Wenn Sie das Dashboard im **Dev-Modus** (`npm run dev`) ausführen und von einem anderen Hostnamen als `localhost` darauf zugreifen — zum Beispiel einer benutzerdefinierten Domain, einer Remote-IP oder einer getunnelten URL — sehen Sie möglicherweise eine Warnung wie: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Dies ist Next.js, das den ursprungsübergreifenden Zugriff auf seinen HMR-Websocket (Hot Module Reload) blockiert, was eine reine Dev-Funktion ist. Um Ihren Host zuzulassen, verwenden Sie das `--allowed-origins`-Flag: +Dies ist Next.js, das den Cross-Origin-Zugriff auf seinen HMR-WebSocket (Hot Module Reload) blockiert, was eine reine Dev-Funktion ist. Um Ihren Host zuzulassen, verwenden Sie das Flag `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -138,12 +140,12 @@ Für mehrere Hosts oder IPs übergeben Sie eine kommagetrennte Liste: npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -Sie können auch die Umgebungsvariable `FAILPROOFAI_ALLOWED_DEV_ORIGINS` verwenden: +Sie können auch die Umgebungsvariable `FAILPROOFAI_ALLOWED_DEV_ORIGINS` stattdessen setzen: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Dies gilt nur für den Dev-Modus. Beim Ausführen von `failproofai` (Produktionsmodus) gibt es keinen HMR-Websocket und kein ursprungsübergreifendes Dev-Ressourcenproblem. +Dies gilt nur für den Dev-Modus. Beim Ausführen von `failproofai` (Produktionsmodus) gibt es keinen HMR-WebSocket und kein Cross-Origin-Dev-Ressourcenproblem. \ No newline at end of file diff --git a/docs/es/configuration.mdx b/docs/es/configuration.mdx index 47c4236c..be866e4b 100644 --- a/docs/es/configuration.mdx +++ b/docs/es/configuration.mdx @@ -1,28 +1,28 @@ --- title: Configuración -description: "Formato de archivo de configuración, sistema de tres ámbitos y reglas de combinación" +description: "Formato del archivo de configuración, sistema de tres niveles y reglas de fusión" icon: gear --- -failproofai utiliza archivos de configuración JSON para controlar qué políticas están activas, cómo se comportan y desde dónde se cargan las políticas personalizadas. La configuración está diseñada para compartirse fácilmente con tu equipo: confírmala en tu repositorio y todos los desarrolladores tendrán la misma red de seguridad para el agente. +failproofai utiliza archivos de configuración JSON para controlar qué políticas están activas, cómo se comportan y desde dónde se cargan las políticas personalizadas. La configuración está diseñada para compartirse fácilmente con tu equipo: confírmala en tu repositorio y todos los desarrolladores obtendrán la misma red de seguridad para el agente. --- -## Ámbitos de configuración +## Niveles de configuración -Existen tres ámbitos de configuración, evaluados en orden de prioridad: +Existen tres niveles de configuración, evaluados en orden de prioridad: -| Ámbito | Ruta del archivo | Propósito | -|--------|-----------------|-----------| +| Nivel | Ruta del archivo | Propósito | +|-------|-----------------|-----------| | **project** | `.failproofai/policies-config.json` | Configuración por repositorio, confirmada en control de versiones | -| **local** | `.failproofai/policies-config.local.json` | Sobreescrituras personales por repositorio, ignoradas por git | -| **global** | `~/.failproofai/policies-config.json` | Valores predeterminados de usuario para todos los proyectos | +| **local** | `.failproofai/policies-config.local.json` | Sobreescrituras personales por repositorio, en gitignore | +| **global** | `~/.failproofai/policies-config.json` | Valores predeterminados a nivel de usuario para todos los proyectos | -Cuando failproofai recibe un evento de hook, carga y combina los tres archivos que existen para el directorio de trabajo actual. +Cuando failproofai recibe un evento de hook, carga y fusiona los tres archivos que existan para el directorio de trabajo actual. -### Reglas de combinación +### Reglas de fusión -**`enabledPolicies`** — la unión de los tres ámbitos. Una política habilitada en cualquier nivel está activa. +**`enabledPolicies`** — la unión de los tres niveles. Una política habilitada en cualquier nivel está activa. ```text project: ["block-sudo"] @@ -32,26 +32,28 @@ global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← unión sin duplicados ``` -**`policyParams`** — el primer ámbito que define parámetros para una política determinada gana por completo. No hay combinación profunda de valores dentro de los parámetros de una política. +**`policyParams`** — el primer nivel que define parámetros para una política determinada gana por completo. No se realiza una fusión profunda de valores dentro de los parámetros de una política. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← project gana, global se ignora +resolved: { allowPatterns: ["sudo apt-get update"] } ← project gana, global ignorado ``` ```text -project: (sin entrada para block-sudo) -local: (sin entrada para block-sudo) +project: (sin entrada de block-sudo) +local: (sin entrada de block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← se aplica global como respaldo +resolved: { allowPatterns: ["sudo systemctl status"] } ← se aplica global ``` -**`customPoliciesPath`** — el primer ámbito que lo defina gana. +**`customPoliciesPaths` / `customPoliciesPath`** — el primer nivel que define cualquiera de las dos formas gana. -**`llm`** — el primer ámbito que lo defina gana. +**`disabledCustomPolicies`** — unión de todos los niveles. El panel escribe aquí un ID calificado por origen cuando desactivas una política individual desde un archivo de políticas explícito o por convención. Las políticas no listadas permanecen habilitadas por defecto; los IDs incluyen el archivo origen para que las políticas con el mismo nombre en múltiples archivos puedan controlarse de forma independiente. + +**`llm`** — el primer nivel que lo define gana. --- @@ -104,25 +106,25 @@ Tipo: `string[]` Lista de nombres de políticas a habilitar. Los nombres deben coincidir exactamente con los identificadores de política que muestra `failproofai policies`. Consulta [Políticas integradas](/es/built-in-policies) para ver la lista completa. -Las políticas que no están en `enabledPolicies` están inactivas, aunque tengan entradas en `policyParams`. +Las políticas que no estén en `enabledPolicies` están inactivas, incluso si tienen entradas en `policyParams`. ### `policyParams` Tipo: `Record>` -Sobreescrituras de parámetros por política. La clave exterior es el nombre de la política; las claves internas son específicas de cada política. Cada política documenta sus parámetros disponibles en [Políticas integradas](/es/built-in-policies). +Sobreescrituras de parámetros por política. La clave externa es el nombre de la política; las claves internas son específicas de cada política. Cada política documenta sus parámetros disponibles en [Políticas integradas](/es/built-in-policies). -Si una política tiene parámetros pero no los especificas, se utilizan los valores predeterminados integrados de la política. Los usuarios que no configuran `policyParams` en absoluto obtienen un comportamiento idéntico al de versiones anteriores. +Si una política tiene parámetros pero no los especificas, se usan los valores predeterminados integrados de la política. Los usuarios que no configuren `policyParams` en absoluto obtendrán un comportamiento idéntico al de versiones anteriores. -Las claves desconocidas dentro del bloque de parámetros de una política se ignoran silenciosamente en el momento de la ejecución del hook, pero se marcan como advertencias cuando ejecutas `failproofai policies`. +Las claves desconocidas dentro del bloque de parámetros de una política se ignoran silenciosamente al momento de disparar el hook, pero se marcan como advertencias cuando ejecutas `failproofai policies`. #### `hint` (transversal) Tipo: `string` (opcional) -Un mensaje que se añade al motivo cuando una política devuelve `deny` o `instruct`. Úsalo para darle a Claude orientación accionable sin modificar la política en sí. +Un mensaje que se agrega al motivo cuando una política devuelve `deny` o `instruct`. Úsalo para darle a Claude orientación accionable sin modificar la política en sí. -Funciona con cualquier tipo de política: integrada, personalizada (`custom/`), convención de proyecto (`.failproofai-project/`) o convención de usuario (`.failproofai-user/`). +Funciona con cualquier tipo de política — integrada, personalizada (`custom/`), convención de proyecto (`.failproofai-project/`), o convención de usuario (`.failproofai-user/`). ```json { @@ -141,17 +143,17 @@ Funciona con cualquier tipo de política: integrada, personalizada (`custom/`), } ``` -Cuando `block-force-push` deniega, Claude ve: *"Se ha bloqueado el force-push. Try creating a fresh branch instead."* +Cuando `block-force-push` deniega, Claude ve: *"Force-pushing is blocked. Try creating a fresh branch instead."* -Los valores que no son cadenas de texto y las cadenas vacías se ignoran silenciosamente. Si no se define `hint`, el comportamiento no cambia (compatible con versiones anteriores). +Los valores que no sean cadenas de texto y las cadenas vacías se ignoran silenciosamente. Si `hint` no está configurado, el comportamiento no cambia (compatible con versiones anteriores). ### `customPoliciesPath` Tipo: `string` (ruta absoluta) -Ruta a un archivo JavaScript que contiene políticas de hook personalizadas. Este valor lo establece automáticamente `failproofai policies --install --custom ` (la ruta se resuelve a absoluta antes de almacenarse). +Ruta a un archivo JavaScript que contiene políticas de hook personalizadas. Se establece automáticamente mediante `failproofai policies --install --custom ` (la ruta se resuelve a absoluta antes de almacenarse). -El archivo se carga de nuevo en cada evento de hook; no hay caché. Consulta [Políticas personalizadas](/es/custom-policies) para ver los detalles de creación. +El archivo se carga de nuevo en cada evento de hook — no hay caché. Consulta [Políticas personalizadas](/es/custom-policies) para detalles de autoría. ### Políticas basadas en convenciones @@ -160,13 +162,13 @@ Además del `customPoliciesPath` explícito, failproofai descubre y carga autom | Nivel | Directorio | Ámbito | |-------|-----------|--------| | Proyecto | `.failproofai/policies/` | Compartido con el equipo mediante control de versiones | -| Usuario | `~/.failproofai/policies/` | Personal, se aplica a todos los proyectos | +| Usuario | `~/.failproofai/policies/` | Personal, aplica a todos los proyectos | -**Coincidencia de archivos:** Solo se cargan los archivos que coincidan con `*policies.{js,mjs,ts}` (p. ej., `security-policies.mjs`, `workflow-policies.js`). Los demás archivos del directorio se ignoran. +**Coincidencia de archivos:** Solo se cargan los archivos que coincidan con `*policies.{js,mjs,ts}` (por ejemplo, `security-policies.mjs`, `workflow-policies.js`). Los demás archivos en el directorio se ignoran. -**Sin configuración necesaria:** Las políticas de convención no requieren entradas en `policies-config.json`. Simplemente coloca los archivos en el directorio y se detectarán en el próximo evento de hook. +**Sin configuración necesaria:** Las políticas por convención no requieren entradas en `policies-config.json`. Solo coloca los archivos en el directorio y se detectarán en el próximo evento de hook. -**Carga por unión:** Se analizan tanto el directorio de convenciones del proyecto como el del usuario. Se cargan todos los archivos coincidentes de ambos niveles (a diferencia de `customPoliciesPath`, que usa el primero que gana por ámbito). +**Carga por unión:** Se analizan tanto el directorio de convenciones del proyecto como el del usuario. Se cargan todos los archivos coincidentes de ambos niveles (a diferencia de `customPoliciesPath`, que usa el primer nivel que gana). Consulta [Políticas personalizadas](/es/custom-policies) para más detalles y ejemplos. @@ -174,7 +176,7 @@ Consulta [Políticas personalizadas](/es/custom-policies) para más detalles y e Tipo: `object` (opcional) -Configuración del cliente LLM para políticas que realizan llamadas a IA. No es necesario en la mayoría de los casos. +Configuración del cliente LLM para políticas que realizan llamadas a IA. No es necesario para la mayoría de las configuraciones. ```json { @@ -189,19 +191,24 @@ Configuración del cliente LLM para políticas que realizan llamadas a IA. No es ## Gestión de la configuración desde la CLI -Los comandos `policies --install` y `policies --uninstall` escriben en el archivo de configuración de hooks de tu CLI de agente (los puntos de entrada del hook), mientras que `policies-config.json` es el archivo que gestionas directamente. Son dos cosas separadas: +Los comandos `policies --install` y `policies --uninstall` escriben en el archivo de configuración de hooks de tu CLI de agente (los puntos de entrada del hook), mientras que `policies-config.json` es el archivo que gestionas directamente. Los dos son independientes: -- **Configuración de la CLI del agente** — indica al agente que llame a `failproofai --hook ` en cada uso de herramienta: +- **Configuración de la CLI del agente** — le indica al agente que llame a `failproofai --hook ` en cada uso de herramienta: - **Claude Code**: `~/.claude/settings.json` (usuario), `/.claude/settings.json` (proyecto), `/.claude/settings.local.json` (local) - **OpenAI Codex**: `~/.codex/hooks.json` (usuario), `/.codex/hooks.json` (proyecto) — Codex no tiene ámbito `local` - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (usuario), `/.github/hooks/failproofai.json` (proyecto) — Copilot no tiene ámbito `local`. Las entradas de hook usan los campos de comando `bash`/`powershell` de Copilot según el sistema operativo con `timeoutSec`; el archivo lleva un marcador `version: 1` de nivel superior. El soporte de Copilot CLI está en **beta** mientras verificamos el esquema de registros `events.jsonl` (que la documentación pública no especifica) con más sesiones reales. - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (usuario), `/.cursor/hooks.json` (proyecto) — Cursor no tiene ámbito `local`. Las entradas de hook usan la forma de Claude `{type, command, timeout}` (sin división `bash`/`powershell`), pero almacenadas bajo claves de evento en camelCase (`preToolUse`, `beforeSubmitPrompt`, …) en un array plano según el [esquema de hooks de Cursor](https://cursor.com/docs/hooks); el archivo lleva un marcador `version: 1` de nivel superior. El manejador canonicaliza camelCase → PascalCase mediante `CURSOR_EVENT_MAP`, de modo que las políticas integradas existentes se activan sin cambios. El soporte de Cursor Agent está en **beta** mientras verificamos el formato en disco de la transcripción de Cursor (no especificado en la documentación pública) con más instalaciones reales. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (usuario), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (proyecto) — OpenCode no tiene ámbito `local`. A diferencia de las otras cinco CLIs, OpenCode **no tiene un sistema de hooks de comandos externos**: carga plugins JS/TS en proceso registrados explícitamente mediante el array `plugin: []` en `opencode.json` (el autodescubrimiento desde `.opencode/plugins/` **no** es cómo se cargan los plugins en opencode v1.14.33). La instalación coloca un pequeño shim de plugin generado que llama al binario failproofai como subproceso y traduce la respuesta JSON de forma Claude del binario de vuelta a la semántica del plugin: `throw new Error()` para denegar eventos de herramienta (cancela la llamada a la herramienta), `client.session.prompt(...)` para instruct Y para `Stop` / `SubagentStop` deny (envía el motivo de denegación como el siguiente mensaje del usuario — el único canal de reintento forzado, ya que `session.idle` es solo notificación y lanzar desde él es un no-op), y no-op para allow. El shim canonicaliza tanto los nombres de herramientas (minúsculas → PascalCase mediante `OPENCODE_TOOL_MAP`) como las claves de argumentos de entrada de herramientas (camelCase → snake_case mediante `OPENCODE_TOOL_INPUT_MAP` para `Read` / `Write` / `Edit`, p. ej. `filePath` → `file_path`, `oldString` → `old_string`) antes de reenviar al binario, de modo que las políticas integradas de verificación de rutas como `block-read-outside-cwd`, `block-env-files` y `block-secrets-write` se activan sin cambios en las llamadas a herramientas de OpenCode. Las sesiones viven en la base de datos SQLite de opencode en `~/.local/share/opencode/opencode.db`; el visor de sesiones del panel las lee mediante `opencode db --format json` y `opencode export `. El soporte de OpenCode está en **beta** mientras verificamos el comportamiento en distintas versiones y con más sesiones reales. Consulta la [documentación de plugins de OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (usuario), `/.pi/settings.json` (proyecto) — Pi no tiene ámbito `local`. Pi carga paquetes de extensiones TypeScript al inicio; el archivo de configuración es un array de cadenas plano `{"packages": ["./relative/path", …]}`. failproofai escribe una única entrada en el array de packages apuntando a su directorio `pi-extension/` integrado. La extensión se suscribe internamente a los eventos `tool_call` / `user_bash` / `input` / `session_start` de Pi y ejecuta `failproofai --hook --cli pi` como proceso hijo; el manejador canonicaliza eventos de snake_case en minúsculas → PascalCase mediante `PI_EVENT_MAP` para que las políticas integradas existentes se activen sin cambios. Los argumentos de entrada de herramientas también se canonizan mediante `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit entregan `path` en lugar de `file_path`; mapear la clave de nivel superior permite que `block-env-files` y `block-secrets-write` se activen — `block-read-outside-cwd` ya tenía un respaldo con `path`). El soporte de Pi está en **beta** mientras la API de extensiones de Pi y el diseño del registro de sesiones se estabilizan. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**solo ámbito de usuario** — Hermes no tiene configuración de proyecto/local). Hermes es una **pasarela** de Slack/Telegram, por lo que una instalación intercepta las llamadas a herramientas de todas las plataformas (Slack/Telegram/cli/cron) **y** de los subagentes internos. Las entradas de hook son un par `{command, timeout}` (tiempo de espera en **segundos**) bajo un mapa `hooks:` indexado por los eventos snake_case de Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); el manejador canonicaliza los eventos mediante `HERMES_EVENT_MAP` y los nombres de herramientas mediante `HERMES_TOOL_MAP` para que las políticas integradas se activen sin cambios. La configuración se edita mediante un round-trip YAML `Document` que preserva los comentarios, de modo que los demás ajustes del operador sobreviven, y la instalación establece `hooks_auto_accept: true` para que la pasarela sin cabeza (sin TTY) ejecute los hooks sin solicitud de consentimiento. El evaluador emite el contrato stdout `{"decision":"block","reason"}` de Hermes (Hermes ignora los códigos de salida). **Limitaciones:** Hermes no tiene un evento `Stop` de fin de turno, por lo que las políticas integradas `require-*-before-stop` nunca se activan para él (no aplicable, no roto); `instruct` degrada a allow con nota registrada (sin canal de contexto adicional); y la redacción de secretos en la salida (`sanitize-*`) no puede reescribir la salida de herramientas a través del contrato de hook de shell. Hermes es también una fuente de **auditoría** sin conexión — el panel lee sus sesiones de pasarela directamente desde `~/.hermes/state.db`. -- **`policies-config.json`** — indica a failproofai qué políticas evaluar y con qué parámetros (compartido entre todas las CLIs de agentes) - -Pasa `--cli claude|codex|copilot|cursor|opencode|pi|hermes` para apuntar a un agente específico (separados por espacios o repetidos para cualquier subconjunto): + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (usuario), `/.github/hooks/failproofai.json` (proyecto) — Copilot no tiene ámbito `local`. Las entradas de hook usan los campos de comando `bash`/`powershell` con clave por sistema operativo de Copilot con `timeoutSec`; el archivo incluye un marcador de nivel superior `version: 1`. El soporte de Copilot CLI está en **beta** mientras verificamos el esquema de registros `events.jsonl` (que la documentación pública no especifica) frente a más sesiones reales. **El modo de agente de VS Code Copilot Chat (Preview)** lee configuraciones de hook desde `.github/hooks/*.json`, `~/.copilot/hooks/*.json` y `~/.claude/settings.json` (gobernado por la configuración `chat.hookFilesLocations`) usando el mismo contrato con forma Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — exactamente las rutas que esta integración `copilot` y la integración `claude` (`~/.claude/settings.json`) ya escriben, por lo que `failproofai policies --install --cli copilot` (o `--cli claude`) **ya se aplica en el modo de agente de VS Code** sin necesidad de una integración `vscode` separada (confirmado en vivo desde los registros de descubrimiento de VS Code). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (usuario), `/.cursor/hooks.json` (proyecto) — Cursor no tiene ámbito `local`. Las entradas de hook usan la forma con forma Claude `{type, command, timeout}` (sin división `bash`/`powershell`), pero almacenadas bajo claves de evento en camelCase (`preToolUse`, `beforeSubmitPrompt`, …) en un array plano según el [esquema de hooks](https://cursor.com/docs/hooks) de Cursor; el archivo incluye un marcador de nivel superior `version: 1`. El manejador canonicaliza camelCase → PascalCase mediante `CURSOR_EVENT_MAP` para que las políticas integradas existentes se disparen sin cambios. El soporte de Cursor Agent está en **beta** mientras verificamos el formato de transcripción en disco de Cursor (no especificado en la documentación pública) frente a más instalaciones reales. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (usuario), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (proyecto) — OpenCode no tiene ámbito `local`. A diferencia de las otras cinco CLIs, OpenCode **no tiene un sistema de hooks de comandos externos**: carga plugins JS/TS en proceso registrados explícitamente mediante el array `plugin: []` en `opencode.json` (la detección automática desde `.opencode/plugins/` **no** es cómo se cargan los plugins en opencode v1.14.33). La instalación deposita un pequeño shim de plugin generado que llama al binario de failproofai como subproceso y traduce la respuesta JSON con forma Claude del binario de vuelta a la semántica del plugin: `throw new Error()` para la denegación de eventos de herramienta (cancela la llamada a la herramienta), `client.session.prompt(...)` para instruct Y para la denegación de `Stop` / `SubagentStop` (envía el motivo de denegación como el siguiente mensaje de usuario — el único canal de reintento forzado ya que `session.idle` es solo de notificación y lanzar desde él no tiene efecto), y sin operación para allow. El shim canonicaliza tanto los nombres de herramientas (minúsculas → PascalCase mediante `OPENCODE_TOOL_MAP`) como las claves de argumentos de entrada de herramientas (camelCase → snake_case mediante `OPENCODE_TOOL_INPUT_MAP` para `Read` / `Write` / `Edit`, por ejemplo `filePath` → `file_path`, `oldString` → `old_string`) antes de enviarlos al binario, para que las políticas integradas de verificación de rutas como `block-read-outside-cwd`, `block-env-files` y `block-secrets-write` se disparen sin cambios en las llamadas a herramientas de OpenCode. Las sesiones viven en la base de datos SQLite de opencode en `~/.local/share/opencode/opencode.db`; el visor de sesiones del panel las lee mediante `opencode db --format json` y `opencode export `. El soporte de OpenCode está en **beta** mientras verificamos el comportamiento en diferentes versiones y frente a más sesiones reales. Consulta la [documentación de plugins de OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (usuario), `/.pi/settings.json` (proyecto) — Pi no tiene ámbito `local`. Pi carga paquetes de extensiones TypeScript al inicio; el archivo de configuración es un array de cadenas plano `{"packages": ["./relative/path", …]}`. failproofai escribe una única entrada en el array de packages que apunta a su directorio `pi-extension/` incluido. La extensión se suscribe internamente a los eventos `tool_call` / `user_bash` / `input` / `session_start` de Pi y ejecuta `failproofai --hook --cli pi`; el manejador canonicaliza underscore_lower_snake_case → PascalCase mediante `PI_EVENT_MAP` para que las políticas integradas existentes se disparen sin cambios. Los argumentos de entrada de herramientas también se canonizan mediante `PI_TOOL_INPUT_MAP` (el Read / Write / Edit de Pi entrega `path` en lugar de `file_path`; mapear la clave de nivel superior permite que `block-env-files` y `block-secrets-write` se disparen — `block-read-outside-cwd` ya tenía un fallback a `path`). El soporte de Pi está en **beta** mientras la API de extensiones de Pi y el diseño del registro de sesiones se estabilizan. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**solo ámbito de usuario** — Hermes no tiene configuración de proyecto/local). Hermes es una **puerta de enlace** de Slack/Telegram, por lo que una instalación intercepta las llamadas a herramientas de cada plataforma (Slack/Telegram/cli/cron) **y** los subagentes internos. Las entradas de hook son un par `{command, timeout}` (tiempo de espera en **segundos**) bajo un mapa `hooks:` con clave por los eventos en snake_case de Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); el manejador canonicaliza los eventos mediante `HERMES_EVENT_MAP` y los nombres de herramientas mediante `HERMES_TOOL_MAP` para que las políticas integradas se disparen sin cambios. La configuración se edita mediante un ida y vuelta de `Document` YAML que preserva los comentarios para que la demás configuración del operador sobreviva, y la instalación establece `hooks_auto_accept: true` para que la puerta de enlace sin cabeza (sin TTY) ejecute los hooks sin una solicitud de consentimiento. El evaluador emite el contrato stdout `{"decision":"block","reason"}` de Hermes (Hermes ignora los códigos de salida). **Limitaciones:** Hermes no tiene un evento `Stop` al final del turno, por lo que las políticas integradas `require-*-before-stop` nunca se disparan para él (no aplicable, no está roto); `instruct` se degrada a allow con nota registrada (sin canal de contexto adicional); y la redacción de secretos en la salida (`sanitize-*`) no puede reescribir la salida de herramientas a través del contrato de hook de shell. Hermes es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones de puerta de enlace directamente desde `~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**solo ámbito de usuario** — OpenClaw no tiene configuración de proyecto/local). Al igual que Hermes, OpenClaw es una **puerta de enlace** multicanal autoalojada, por lo que una instalación intercepta las llamadas a herramientas de cada canal y sus subagentes internos. La aplicación se ejecuta a través de los **hooks de plugins en proceso** de OpenClaw (sus hooks internos basados en archivos son solo de observación y no pueden bloquear), por lo que — como OpenCode/Pi — failproofai incluye un paquete estático `openclaw-plugin/` que genera el binario de failproofai de forma asíncrona y traduce el veredicto. La instalación registra el directorio de plugin incluido en `plugins.load.paths[]` de `openclaw.json` y lo habilita bajo `plugins.entries.failproofai` (con `hooks.allowConversationAccess: true`, necesario para los hooks de conversación sin procesar). El evaluador emite un veredicto plano `{permission, reason}` y el shim lo mapea a la forma de retorno nativa de cada hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), y `before_agent_finalize → {action:"revise", reason}` (**Stop** — una puerta real al final del turno, por lo que las políticas integradas `require-*-before-stop` **se aplican** en OpenClaw, a diferencia de Hermes). Los eventos y nombres de herramientas se canonizan en el binario mediante `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) para que las políticas integradas se disparen sin cambios; el shim falla abierto ante cualquier error de generación/análisis/tiempo de espera. OpenClaw es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones JSONL en `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (usuario), `/.factory/hooks.json` (proyecto) — Factory no tiene ámbito `local`. droid incluye un sistema de hooks de comandos externos con estilo Claude, pero con dos peculiaridades verificadas en vivo contra droid v0.171.0: (1) los nombres de eventos viven en el **nivel superior** de `hooks.json` — **no hay un envoltorio `"hooks"`** (droid lo rechaza); los eventos de herramienta (`PreToolUse`/`PostToolUse`) llevan `"matcher": "*"`, los eventos que no son de herramienta lo omiten. (2) La denegación se maneja mediante el **código de salida 2 + stderr** del hook, no con una decisión JSON — la rama `factory` del evaluador devuelve salida 2 para eventos de herramienta/prompt y `{decision:"block", reason}` solo en el evento `Stop` al final del turno (el único canal de reintento forzado de droid). Los eventos ya están en PascalCase (sin mapa de eventos) y el payload está en snake_case de Claude; solo los nombres de herramientas se canonizan mediante `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones JSONL en disco en `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (usuario), `/.devin/config.json` (proyecto) — Devin no tiene ámbito `local`. Devin es un **clon puro de Claude** verificado en vivo contra devin v3000.1.27: utiliza el esquema de envoltorio `"hooks"` estándar de Claude (las escrituras preservan la fusión para que las demás claves del archivo de configuración — `org_id`, `theme_mode`, … — sobrevivan), nombres de eventos ya en PascalCase (sin mapa de eventos, sin rama del manejador) y un payload stdin en snake_case de Claude (sin normalización). La rama `devin` del evaluador deniega con `{"decision":"block","reason"}` JSON en stdout en la salida 0 para **cada** evento (verificado — el bloqueo anuló `--permission-mode dangerous`); en el evento `Stop` al final del turno, el motivo lleva el texto de reintento forzado MANDATORY-ACTION para que las políticas integradas `require-*-before-stop` se apliquen. Solo los nombres de herramientas se canonizan mediante `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` ya es canónico). Devin es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones SQLite en `~/.local/share/devin/cli/sessions.db` (cada fila de `sessions` lleva un `working_directory` real, por lo que las sesiones se agrupan por cwd del proyecto como Claude). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (usuario), `/.agents/hooks.json` (proyecto) — Antigravity no tiene ámbito `local`. A diferencia de Factory/Devin, Antigravity tiene su **propio** contrato (no es un clon de Claude), verificado en vivo contra agy v1.1.2. `hooks.json` usa un esquema de **hook con nombre**: la clave de nivel superior es un *nombre* de hook (`"failproofai"`) cuyo valor es un mapa de evento→manejadores — los eventos de herramienta (`PreToolUse`/`PostToolUse`) envuelven los manejadores en `{matcher:"*", hooks:[…]}`, mientras que `PreInvocation`/`Stop` son arrays de manejadores **planos** (otros hooks con nombre se preservan). El payload stdin es **protojson en camelCase** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai lo normaliza a snake_case antes de que se ejecuten las políticas, y mapea los args en PascalCase de `run_command` (`CommandLine`/`Cwd`) mediante `ANTIGRAVITY_TOOL_INPUT_MAP`. La rama `antigravity` del evaluador usa las **propias** formas de respuesta de Antigravity: `{decision:"deny", reason}` bloquea una herramienta/prompt (salida 0), `{decision:"continue", reason}` en el evento `Stop` al final del turno vuelve a entrar al bucle (para que las políticas integradas `require-*-before-stop` se apliquen), y `{injectSteps:[{ephemeralMessage}]}` inyecta una instrucción en `PreInvocation` (→ `UserPromptSubmit`). Los nombres de herramientas se canonizan mediante `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity es **también** una fuente de **auditoría** sin conexión — el panel lee sus transcripciones en JSONL plano en `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (índice de conversaciones en `conversation_summaries.db`). + - **Goose (nombre en clave goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (usuario), `/.agents/plugins/failproofai/hooks/hooks.json` (proyecto) — Goose no tiene ámbito `local`. La aplicación usa el sistema de **hooks** de Goose, la especificación **Open Plugins** entre agentes: el instalador simplemente deposita el directorio del plugin `failproofai` y Goose lo detecta automáticamente al inicio (registrándolo en `~/.config/goose/config.yaml`). El `hooks.json` usa un esquema de Open Plugins **con** un envoltorio `"hooks"` de nivel superior, y el matcher se **omite** en cada evento — un `"*"` simple es una regex inválida que no coincide con nada (verificado en vivo contra goose v1.43.0). Los nombres de eventos ya están en PascalCase (sin mapa de eventos); el payload stdin usa `event`/`working_dir`, que el manejador normaliza a `hook_event_name`/`cwd`. La rama `goose` del evaluador deniega con `{"decision":"block","reason"}` JSON en stdout en la salida 0, respetado en el evento **`PreToolUse`** únicamente (incluido en goose ≥ v1.37.0) — que se dispara para la herramienta shell **y dentro de subagentes delegados**, por lo que es el único punto de denegación suficiente; cualquier otro error de hook falla **abierto**. Goose **no tiene evento `Stop`**, por lo que las políticas integradas `require-*-before-stop` no aplican (como con Hermes). Los nombres de herramientas se canonizan mediante `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) y las claves de rutas mediante `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose es **también** una fuente de **auditoría** sin conexión — el panel lee sus sesiones SQLite en `~/.local/share/goose/sessions/sessions.db` (cada fila de `sessions` lleva un `working_dir` real, por lo que las sesiones se agrupan por cwd del proyecto como Devin; las ejecuciones temporales con `--no-session` se filtran). +- **`policies-config.json`** — le indica a failproofai qué políticas evaluar y con qué parámetros (compartido entre todas las CLIs de agente) + +Pasa `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` para apuntar a un agente específico (separados por espacios o repetidos para cualquier subconjunto): ```bash failproofai policies --install --cli codex --scope project @@ -210,15 +217,20 @@ failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli hermes --scope user -failproofai policies --install --cli claude codex copilot cursor opencode pi +failproofai policies --install --cli openclaw --scope user +failproofai policies --install --cli factory --scope project +failproofai policies --install --cli devin --scope project +failproofai policies --install --cli antigravity --scope project +failproofai policies --install --cli goose --scope project +failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -Cuando se omite `--cli`, `failproofai` detecta qué CLIs de agentes están instaladas (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`): +Cuando se omite `--cli`, `failproofai` detecta qué CLIs de agente están instaladas (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): -- **Una CLI detectada** — la selecciona automáticamente sin solicitar confirmación. -- **Múltiples CLIs detectadas** en un terminal interactivo — muestra un prompt de selección única con teclas de flecha, agrupado en una sección `Detected (N)` (con una fila agregada `Install for all N detected` + cada CLI detectada individualmente) y una sección `Not installed (M) · install hooks ahead of time` que lista cada CLI compatible no detectada como opción de instalación anticipada (↑↓ para moverse, Enter para seleccionar, ^C para salir). El flujo de desinstalación muestra solo la sección Detected. -- **Múltiples CLIs detectadas** en una ejecución no interactiva (CI, sin TTY) — instala para todas las CLIs detectadas sin solicitar confirmación. -- **Ninguna detectada** — recurre a `claude`, con una advertencia de que no se encontró ningún binario de agente en el PATH; el comando de hook se escribe de todas formas para que se active en cuanto instales uno. +- **Una CLI detectada** — la selecciona automáticamente sin preguntar. +- **Múltiples CLIs detectadas** en una terminal interactiva — muestra un prompt de selección única con teclas de flecha agrupado en una sección `Detected (N)` (con una fila agregada `Install for all N detected` + cada CLI detectada individualmente) y una sección `Not installed (M) · install hooks ahead of time` que lista cada CLI compatible no detectada como opción de instalación anticipada (↑↓ para moverse, Enter para seleccionar, ^C para salir). El flujo de desinstalación muestra solo la sección Detected. +- **Múltiples CLIs detectadas** en una ejecución no interactiva (CI, sin TTY) — instala para todas las CLIs detectadas sin preguntar. +- **Ninguna detectada** — vuelve a `claude`, con una advertencia de que no se encontró ningún binario de agente en PATH; el comando de hook se escribe de todos modos para que se active en cuanto instales uno. Puedes editar `policies-config.json` directamente en cualquier momento; los cambios surten efecto inmediatamente en el próximo evento de hook sin necesidad de reiniciar. @@ -245,4 +257,4 @@ Confirma `.failproofai/policies-config.json` en tu repositorio: } ``` -Cada desarrollador puede entonces crear `.failproofai/policies-config.local.json` (ignorado por git) para sobreescrituras personales sin afectar a sus compañeros de equipo. \ No newline at end of file +Cada desarrollador puede entonces crear `.failproofai/policies-config.local.json` (en gitignore) para sobreescrituras personales sin afectar a sus compañeros de equipo. \ No newline at end of file diff --git a/docs/es/custom-policies.mdx b/docs/es/custom-policies.mdx index 01e1b6ff..01171dc1 100644 --- a/docs/es/custom-policies.mdx +++ b/docs/es/custom-policies.mdx @@ -1,10 +1,10 @@ --- -title: Políticas personalizadas -description: "Escribe tus propias políticas en JavaScript: aplica convenciones del proyecto, prevén desviaciones, detecta fallos e intégrate con sistemas externos" +title: Políticas Personalizadas +description: "Escribe tus propias políticas en JavaScript: aplica convenciones, previene desviaciones, detecta fallos e integra con sistemas externos" icon: code --- -Las políticas personalizadas te permiten definir reglas para cualquier comportamiento del agente: aplicar convenciones del proyecto, prevenir desviaciones, bloquear operaciones destructivas, detectar agentes atascados o integrarte con Slack, flujos de aprobación y más. Utilizan el mismo sistema de eventos de hook y las mismas decisiones `allow`, `deny`, `instruct` que las políticas integradas. +Las políticas personalizadas te permiten escribir reglas para cualquier comportamiento del agente: aplicar convenciones del proyecto, prevenir desviaciones, controlar operaciones destructivas, detectar agentes bloqueados o integrarte con Slack, flujos de aprobación y más. Utilizan el mismo sistema de eventos de hook y las mismas decisiones `allow`, `deny`, `instruct` que las políticas integradas. --- @@ -39,9 +39,9 @@ failproofai policies --install --custom ./my-policies.js ## Dos formas de cargar políticas personalizadas -### Opción 1: Basada en convenciones (recomendada) +### Opción 1: Por convención (recomendada) -Coloca archivos `*policies.{js,mjs,ts}` en `.failproofai/policies/` y se cargarán automáticamente, sin necesidad de flags ni cambios de configuración. Funciona como los git hooks: basta con añadir el archivo y ya está. +Coloca archivos `*policies.{js,mjs,ts}` en `.failproofai/policies/` y se cargan automáticamente — sin necesidad de flags ni cambios de configuración. Funciona como los git hooks: coloca un archivo y listo. ``` # Nivel de proyecto — incluido en git, compartido con el equipo @@ -53,38 +53,43 @@ Coloca archivos `*policies.{js,mjs,ts}` en `.failproofai/policies/` y se cargar ``` **Cómo funciona:** -- Se analizan tanto el directorio del proyecto como el del usuario (unión — no gana el primero en alcance) +- Se escanean tanto el directorio del proyecto como el del usuario (unión — no gana el primer scope) - Los archivos se cargan en orden alfabético dentro de cada directorio. Usa prefijos como `01-`, `02-` para controlar el orden - Solo se cargan los archivos que coincidan con `*policies.{js,mjs,ts}`; los demás se ignoran -- Cada archivo se carga de forma independiente (fallo abierto por archivo) +- Cada archivo se carga de forma independiente (fail-open por archivo) - Funciona junto con `--custom` explícito y las políticas integradas -Las políticas por convención son la forma más sencilla de establecer un estándar de calidad para tu organización. Incluye `.failproofai/policies/` en git y todos los miembros del equipo recibirán las mismas reglas automáticamente, sin configuración individual. A medida que el equipo detecte nuevos modos de fallo, añade una política y haz push. Con el tiempo, esto se convierte en un estándar de calidad vivo que mejora con cada contribución. +Las políticas por convención son la forma más sencilla de establecer un estándar de calidad para tu organización. Incluye `.failproofai/policies/` en git y todos los miembros del equipo obtendrán las mismas reglas automáticamente — sin configuración por desarrollador. A medida que el equipo descubra nuevos modos de fallo, añade una política y súbela. Con el tiempo, se convierten en un estándar de calidad vivo que mejora con cada contribución. ### Opción 2: Ruta de archivo explícita ```bash -# Instalar con un archivo de políticas personalizado +# Instalar con un archivo de políticas personalizadas failproofai policies --install --custom ./my-policies.js -# Reemplazar la ruta del archivo de políticas +# Reemplazar las rutas de políticas personalizadas failproofai policies --install --custom ./new-policies.js -# Eliminar la ruta de políticas personalizada de la configuración +# Configurar múltiples archivos explícitos (cargados en el orden de los flags) +failproofai policies --install --custom ./security.js --custom ./workflow.js + +# Eliminar todas las rutas de políticas personalizadas explícitas de la configuración failproofai policies --uninstall --custom ``` -La ruta absoluta resuelta se almacena en `policies-config.json` como `customPoliciesPath`. El archivo se carga de nuevo en cada evento de hook; no hay caché entre eventos. +Las rutas absolutas resueltas se almacenan en `policies-config.json` como `customPoliciesPaths`. Repite `--custom` para configurar múltiples archivos. Las configuraciones existentes que usen el campo heredado `customPoliciesPath` siguen funcionando. Los archivos se cargan de nuevo en cada evento de hook — no hay caché entre eventos. + +Cada política registrada aparece con su propio interruptor en el panel. Desactivar una política registra su ID con el source calificado en `disabledCustomPolicies`; el archivo y sus demás políticas continúan cargándose, mientras que la política desactivada queda excluida antes de la coincidencia de eventos. Los nombres de política duplicados entre archivos tienen interruptores independientes. -### Usar ambas opciones juntas +### Usar ambas formas juntas -Las políticas por convención y el archivo `--custom` explícito pueden coexistir. Orden de carga: +Las políticas por convención y los archivos `--custom` explícitos pueden coexistir. Orden de carga: -1. Archivo `customPoliciesPath` explícito (si está configurado) -2. Archivos de convención del proyecto (`{cwd}/.failproofai/policies/`, alfabético) -3. Archivos de convención del usuario (`~/.failproofai/policies/`, alfabético) +1. Archivos `customPoliciesPaths` explícitos (en el orden configurado) +2. Archivos de convención del proyecto (`{cwd}/.failproofai/policies/`, orden alfabético) +3. Archivos de convención del usuario (`~/.failproofai/policies/`, orden alfabético) --- @@ -98,44 +103,44 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Registra una política. Llámalo tantas veces como necesites para definir múltiples políticas en el mismo archivo. +Registra una política. Llámalo tantas veces como necesites para múltiples políticas en el mismo archivo. ```ts customPolicies.add({ name: string; // obligatorio - identificador único description?: string; // se muestra en la salida de `failproofai policies` - match?: { events?: HookEventType[] }; // filtrar por tipo de evento; omitir para coincidir con todos + match?: { events?: HookEventType[] }; // filtra por tipo de evento; omite para coincidir con todos fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### Funciones de decisión +### Helpers de decisión -| Función | Efecto | Cuándo usarla | +| Función | Efecto | Úsala cuando | |----------|--------|----------| -| `allow()` | Permite la operación sin mostrar mensajes | La acción es segura y no necesita notificación | -| `deny(message)` | Bloquea la operación | El agente no debe realizar esta acción | -| `instruct(message)` | Añade contexto sin bloquear | Proporciona contexto adicional al agente para que siga el camino correcto | +| `allow()` | Permite la operación silenciosamente | La acción es segura, no se necesita mensaje | +| `deny(message)` | Bloquea la operación | El agente no debería realizar esta acción | +| `instruct(message)` | Añade contexto sin bloquear | Da al agente contexto adicional para mantenerlo en curso | -`deny(message)` — el mensaje aparece ante Claude con el prefijo `"Blocked by failproofai:"`. Un solo `deny` interrumpe toda evaluación posterior. +`deny(message)` — el mensaje aparece en Claude con el prefijo `"Blocked by failproofai:"`. Un único `deny` cortocircuita toda evaluación posterior. -`instruct(message)` — el mensaje se añade al contexto de Claude para la llamada a la herramienta actual. Todos los mensajes `instruct` se acumulan y se entregan juntos. +`instruct(message)` — el mensaje se añade al contexto de Claude para la llamada de herramienta actual. Todos los mensajes `instruct` se acumulan y se entregan juntos. -Puedes añadir orientación adicional a cualquier mensaje `deny` o `instruct` mediante el campo `hint` en `policyParams`, sin necesidad de modificar el código. Esto funciona también para políticas personalizadas (`custom/`), de convención de proyecto (`.failproofai-project/`) y de convención de usuario (`.failproofai-user/`). Consulta [Configuración → hint](/es/configuration#hint-cross-cutting) para más detalles. +Puedes añadir orientación adicional a cualquier mensaje `deny` o `instruct` agregando un campo `hint` en `policyParams` — sin necesidad de cambiar el código. Esto también funciona para políticas personalizadas (`custom/`), de convención de proyecto (`.failproofai-project/`) y de convención de usuario (`.failproofai-user/`). Consulta [Configuración → hint](/es/configuration#hint-cross-cutting) para más detalles. ### Mensajes allow informativos -`allow(message)` permite la operación **y** envía un mensaje informativo a Claude. El mensaje se entrega como `additionalContext` en la respuesta stdout del handler del hook, el mismo mecanismo que usa `instruct`, pero con un significado diferente: es una actualización de estado, no una advertencia. +`allow(message)` permite la operación **y** envía un mensaje informativo a Claude. El mensaje se entrega como `additionalContext` en la respuesta stdout del handler del hook — el mismo mecanismo que usa `instruct`, pero semánticamente diferente: es una actualización de estado, no una advertencia. -| Función | Efecto | Cuándo usarla | +| Función | Efecto | Úsala cuando | |----------|--------|----------| -| `allow(message)` | Permite y envía contexto a Claude | Confirmar que una verificación pasó o explicar por qué se omitió | +| `allow(message)` | Permite y envía contexto a Claude | Confirma que una verificación pasó, o explica por qué se omitió | Casos de uso: -- **Confirmaciones de estado:** `allow("All CI checks passed.")` — informa a Claude de que todo está en orden -- **Explicaciones de fallo abierto:** `allow("GitHub CLI not installed, skipping CI check.")` — indica a Claude por qué se omitió una verificación para que tenga el contexto completo +- **Confirmaciones de estado:** `allow("All CI checks passed.")` — informa a Claude que todo está bien +- **Explicaciones de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — informa a Claude por qué se omitió una verificación para que tenga contexto completo - **Los mensajes múltiples se acumulan:** si varias políticas devuelven `allow(message)`, todos los mensajes se unen con saltos de línea y se entregan juntos ```js @@ -163,7 +168,7 @@ customPolicies.add({ | `toolName` | `string \| undefined` | La herramienta que se está llamando (p. ej. `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | Los parámetros de entrada de la herramienta | | `payload` | `Record` | Payload completo del evento raw de Claude Code | -| `session` | `SessionMetadata \| undefined` | Contexto de sesión (ver a continuación) | +| `session` | `SessionMetadata \| undefined` | Contexto de la sesión (ver más abajo) | ### Campos de `SessionMetadata` @@ -173,14 +178,14 @@ customPolicies.add({ | `cwd` | `string` | Directorio de trabajo de la sesión de Claude Code | | `transcriptPath` | `string` | Ruta al archivo de transcripción JSONL de la sesión | -### Tipos de eventos +### Tipos de evento | Evento | Cuándo se dispara | Contenido de `toolInput` | |-------|--------------|----------------------| | `PreToolUse` | Antes de que Claude ejecute una herramienta | La entrada de la herramienta (p. ej. `{ command: "..." }` para Bash) | -| `PostToolUse` | Después de que una herramienta finaliza | La entrada de la herramienta + `tool_result` (la salida) | +| `PostToolUse` | Después de que una herramienta termina | La entrada de la herramienta + `tool_result` (la salida) | | `Notification` | Cuando Claude envía una notificación | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — los hooks siempre deben devolver `allow()`, no pueden bloquear notificaciones | -| `Stop` | Cuando la sesión de Claude termina | Vacío | +| `Stop` | Cuando termina la sesión de Claude | Vacío | --- @@ -190,11 +195,11 @@ Las políticas se evalúan en este orden: 1. Políticas integradas (en orden de definición) 2. Políticas personalizadas explícitas de `customPoliciesPath` (en orden de `.add()`) -3. Políticas de convención del proyecto `.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro de cada archivo) -4. Políticas de convención del usuario `~/.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro de cada archivo) +3. Políticas de convención del proyecto `.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro) +4. Políticas de convención del usuario `~/.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro) -El primer `deny` interrumpe todas las políticas siguientes. Todos los mensajes `instruct` se acumulan y se entregan juntos. +El primer `deny` cortocircuita todas las políticas posteriores. Todos los mensajes `instruct` se acumulan y se entregan juntos. --- @@ -218,46 +223,46 @@ customPolicies.add({ }); ``` -Se resuelven todas las importaciones relativas alcanzables desde el archivo de entrada. Esto se implementa reescribiendo las importaciones `from "failproofai"` a la ruta real de dist y creando archivos `.mjs` temporales para garantizar la compatibilidad con ESM. +Se resuelven todas las importaciones relativas accesibles desde el archivo de entrada. Esto se implementa reescribiendo las importaciones de `from "failproofai"` a la ruta dist real y creando archivos `.mjs` temporales para garantizar la compatibilidad con ESM. --- ## Filtrado por tipo de evento -Usa `match.events` para limitar cuándo se activa una política: +Usa `match.events` para limitar cuándo se dispara una política: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Solo se activa cuando la sesión finaliza + // Solo se dispara cuando termina la sesión // ctx.session.transcriptPath contiene el registro completo de la sesión return allow(); }, }); ``` -Omite `match` completamente para que se active en todos los tipos de eventos. +Omite `match` por completo para disparar en cualquier tipo de evento. --- ## Manejo de errores y modos de fallo -Las políticas personalizadas son de **fallo abierto**: los errores nunca bloquean las políticas integradas ni hacen que el handler del hook falle. +Las políticas personalizadas son **fail-open**: los errores nunca bloquean las políticas integradas ni provocan fallos en el handler del hook. | Fallo | Comportamiento | |---------|----------| | `customPoliciesPath` no configurado | No se ejecutan políticas personalizadas explícitas; las políticas de convención y las integradas continúan normalmente | | Archivo no encontrado | Advertencia registrada en `~/.failproofai/hook.log`; las integradas continúan | -| Error de sintaxis/importación (explícito) | Error registrado en `~/.failproofai/hook.log`; las políticas personalizadas explícitas se omiten | -| Error de sintaxis/importación (convención) | Error registrado; ese archivo se omite, los demás archivos de convención siguen cargándose | +| Error de sintaxis/importación (explícito) | Error registrado en `~/.failproofai/hook.log`; se omiten las políticas personalizadas explícitas | +| Error de sintaxis/importación (convención) | Error registrado; ese archivo se omite, los demás archivos de convención siguen cargando | | `fn` lanza un error en tiempo de ejecución | Error registrado; ese hook se trata como `allow`; los demás hooks continúan | -| `fn` tarda más de 10s | Timeout registrado; se trata como `allow` | -| Directorio de convención no existente | No se ejecutan políticas de convención; sin error | +| `fn` tarda más de 10 segundos | Timeout registrado; se trata como `allow` | +| Directorio de convención inexistente | No se ejecutan políticas de convención; sin error | -Para depurar errores en políticas personalizadas, monitorea el archivo de log: +Para depurar errores de políticas personalizadas, monitorea el archivo de log: ```bash tail -f ~/.failproofai/hook.log @@ -272,7 +277,7 @@ tail -f ~/.failproofai/hook.log // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// Evitar que el agente escriba en el directorio secrets/ +// Prevent agent from writing to secrets/ directory customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -285,7 +290,7 @@ customPolicies.add({ }, }); -// Mantener al agente en el camino correcto: verificar los tests antes de hacer commit +// Keep the agent on track: verify tests before committing customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +305,7 @@ customPolicies.add({ }, }); -// Prevenir cambios de dependencias no planificados durante el período de congelación +// Prevent unplanned dependency changes during freeze customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -329,8 +334,8 @@ El directorio `examples/` contiene archivos de políticas listos para usar: |------|----------| | `examples/policies-basic.js` | Cinco políticas iniciales que cubren los modos de fallo más comunes del agente | | `examples/policies-advanced/index.js` | Patrones avanzados: importaciones transitivas, llamadas asíncronas, limpieza de salida y hooks de fin de sesión | -| `examples/convention-policies/security-policies.mjs` | Políticas de seguridad basadas en convenciones (bloquear escrituras en .env, prevenir reescritura del historial de git) | -| `examples/convention-policies/workflow-policies.mjs` | Políticas de flujo de trabajo basadas en convenciones (recordatorios de tests, auditoría de escrituras de archivos) | +| `examples/convention-policies/security-policies.mjs` | Políticas de seguridad por convención (bloquear escrituras en .env, prevenir reescritura del historial de git) | +| `examples/convention-policies/workflow-policies.mjs` | Políticas de flujo de trabajo por convención (recordatorios de tests, auditoría de escrituras de archivos) | ### Usar los ejemplos con archivo explícito @@ -338,7 +343,7 @@ El directorio `examples/` contiene archivos de políticas listos para usar: failproofai policies --install --custom ./examples/policies-basic.js ``` -### Usar los ejemplos basados en convenciones +### Usar los ejemplos por convención ```bash # Copiar al nivel de proyecto @@ -350,4 +355,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -No se necesita ningún comando de instalación; los archivos se detectan automáticamente en el siguiente evento de hook. \ No newline at end of file +No se necesita ningún comando de instalación — los archivos se detectan automáticamente en el próximo evento de hook. \ No newline at end of file diff --git a/docs/es/dashboard.mdx b/docs/es/dashboard.mdx index cdb2d8eb..70aa883b 100644 --- a/docs/es/dashboard.mdx +++ b/docs/es/dashboard.mdx @@ -4,7 +4,7 @@ description: "Monitorea sesiones de agentes, revisa llamadas a herramientas y ge icon: chart-line --- -El dashboard de failproofai es una aplicación web local para monitorear tus sesiones de agentes de IA y gestionar políticas. Descubre qué hicieron tus agentes mientras no estabas. +El dashboard de failproofai es una aplicación web local para monitorear tus sesiones de agentes de IA y gestionar políticas. Descubre qué hicieron tus agentes mientras estabas ausente. --- @@ -16,7 +16,7 @@ failproofai Se abre en `http://localhost:8020`. -El dashboard lee los datos de configuración del proyecto local, la sesión y failproofai directamente del sistema de archivos. Las funciones autenticadas opcionales, como recordatorios de auditoría e invitaciones, envían la información necesaria para esas solicitudes (incluidas las direcciones de correo electrónico) a APIs remotas. +El dashboard lee los datos de configuración del proyecto local, la sesión y failproofai directamente desde el sistema de archivos. Las funciones opcionales autenticadas, como recordatorios de auditoría e invitaciones, envían la información necesaria para esas solicitudes (incluidas las direcciones de correo electrónico) a APIs remotas. --- @@ -24,11 +24,13 @@ El dashboard lee los datos de configuración del proyecto local, la sesión y fa ### Proyectos -Lista todos los proyectos de Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity y Goose encontrados en tu máquina. Los proyectos de Claude se descubren desde `~/.claude/projects/` (o la ruta definida por `CLAUDE_PROJECTS_PATH`); los proyectos de Codex se descubren escaneando cada transcripción en `~/.codex/sessions///
/*.jsonl` y agrupando por el `cwd` registrado en el primer registro de cada sesión; los proyectos de Copilot CLI se descubren escaneando cada `~/.copilot/session-state//workspace.yaml` (configurable mediante `COPILOT_HOME`) y agrupando por su campo `cwd`; los proyectos de Cursor Agent se descubren escaneando los metadatos por sesión en `~/.cursor/agent-sessions//` (configurable mediante `CURSOR_HOME`, con `conversations/` y `sessions/` como alternativas) buscando un escalar `cwd` en `meta.json` / `session.json` / `workspace.yaml`; los proyectos de OpenCode se descubren consultando su base de datos SQLite en `~/.local/share/opencode/opencode.db` mediante `opencode db --format json` (leemos las tablas `session` y `project` y agrupamos por `project_id`); los proyectos de Pi se descubren escaneando transcripciones JSONL por sesión en `~/.pi/agent/sessions//_.jsonl` (configurable mediante `PI_SESSIONS_DIR`) y extrayendo el `cwd` del primer registro de cada sesión; las sesiones del gateway de Hermes se leen directamente de su almacén SQLite en `~/.hermes/state.db` (configurable mediante `HERMES_DB_PATH`) y se agrupan en proyectos `hermes-` por `source` (Slack/Telegram/cli/cron — las sesiones del gateway no tienen cwd); las sesiones del gateway de OpenClaw se leen desde `~/.openclaw/agents//sessions/*.jsonl` y se agrupan en proyectos `openclaw-` (también sin cwd); los proyectos de Factory Droid se descubren desde las transcripciones JSONL en `~/.factory/sessions//*.jsonl` y se agrupan por cwd; los proyectos de Devin desde su base de datos SQLite en `~/.local/share/devin/cli/sessions.db` (agrupados por el `working_directory` de cada sesión); los proyectos de Antigravity desde las transcripciones JSONL en `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` y agrupados por cwd; y los proyectos de Goose desde su base de datos SQLite en `~/.local/share/goose/sessions/sessions.db` (agrupados por el `working_dir` de cada sesión). Un proyecto que ha sido utilizado por múltiples CLIs se muestra como una sola fila con todas las insignias correspondientes. Usa el menú desplegable **CLI** sobre la tabla para filtrar por un agente CLI específico; la URL preserva tu selección como `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +Lista todos los proyectos de Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity y Goose encontrados en tu máquina. Los proyectos de Claude se descubren desde `~/.claude/projects/` (o la ruta establecida por `CLAUDE_PROJECTS_PATH`); los proyectos de Codex se descubren escaneando cada transcripción en `~/.codex/sessions///
/*.jsonl` y agrupándolos por el `cwd` registrado en el primer registro de cada sesión; los proyectos de Copilot CLI se descubren escaneando cada `~/.copilot/session-state//workspace.yaml` (configurable mediante `COPILOT_HOME`) y agrupándolos por su campo `cwd`; los proyectos de Cursor Agent se descubren escaneando metadatos por sesión en `~/.cursor/agent-sessions//` (configurable mediante `CURSOR_HOME`, con `conversations/` y `sessions/` como rutas alternativas) buscando un escalar `cwd` en `meta.json` / `session.json` / `workspace.yaml`; los proyectos de OpenCode se descubren consultando su base de datos SQLite en `~/.local/share/opencode/opencode.db` mediante `opencode db --format json` (se leen las tablas `session` y `project` y se agrupan por `project_id`); los proyectos de Pi se descubren escaneando transcripciones JSONL por sesión en `~/.pi/agent/sessions//_.jsonl` (configurable mediante `PI_SESSIONS_DIR`) y extrayendo el `cwd` del primer registro de cada sesión; las sesiones del gateway de Hermes se leen directamente del almacén SQLite de cada perfil — `~/.hermes/state.db` más `~/.hermes/profiles//state.db` (reemplazable mediante `HERMES_HOME`, o `HERMES_DB_PATH` para una única base de datos) — y se agrupan en proyectos `hermes--` por perfil y `source` (Slack/Telegram/cli/cron — las sesiones del gateway no tienen cwd); las sesiones del gateway de OpenClaw se leen desde `~/.openclaw/agents//sessions/*.jsonl` y se agrupan en proyectos `openclaw--` por agente y canal (también sin cwd); los proyectos de Factory Droid se descubren desde las transcripciones JSONL en `~/.factory/sessions//*.jsonl` y se agrupan por cwd; los proyectos de Devin desde su base de datos SQLite en `~/.local/share/devin/cli/sessions.db` (agrupados por el `working_directory` de cada sesión); los proyectos de Antigravity desde las transcripciones JSONL en `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` agrupados por cwd; y los proyectos de Goose desde su base de datos SQLite en `~/.local/share/goose/sessions/sessions.db` (agrupados por el `working_dir` de cada sesión). Un proyecto utilizado por varias CLIs se muestra como una única fila con todos los badges correspondientes. Usa el menú desplegable **CLI** sobre la tabla para filtrar por un agente CLI específico; la URL conserva tu selección como `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. + +Hermes y OpenClaw tienen ámbito de usuario y no tienen directorio de trabajo por el que agrupar, por lo que se muestran como un **árbol de carpetas desplegable** — el perfil (o agente) en el nivel superior, sus canales debajo — mientras que todos los CLIs basados en cwd permanecen como filas planas. Las filas de carpetas acumulan el recuento de sesiones y la actividad más reciente de todo lo que contienen; las carpetas colapsadas se recuerdan entre visitas, y una búsqueda por palabras clave expande lo que coincida. Cada proyecto muestra: - Nombre del proyecto (derivado de la ruta de la carpeta) -- Una insignia de CLI — `Claude Code` (naranja), `OpenAI Codex` (morado), `GitHub Copilot` (azul), `Cursor Agent` (esmeralda), `OpenCode` (ámbar), `Pi` (rosa) y/o `Hermes` (índigo) +- Un badge de CLI — `Claude Code` (naranja), `OpenAI Codex` (morado), `GitHub Copilot` (azul), `Cursor Agent` (esmeralda), `OpenCode` (ámbar), `Pi` (rosa) y/o `Hermes` (índigo) - Fecha de la actividad de sesión más reciente Haz clic en un proyecto para ver sus sesiones. @@ -47,44 +49,44 @@ Haz clic en una sesión para abrir el visor de sesión. ### Visor de sesión -El visor de sesión responde la pregunta clave para los agentes autónomos: ¿qué hizo el agente y se mantuvo en curso? Una insignia de CLI junto al encabezado indica si la sesión es una transcripción de Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity o Goose. Muestra una línea de tiempo de todo lo que ocurrió en una sesión: +El visor de sesión responde la pregunta clave para los agentes autónomos: ¿qué hizo el agente y se mantuvo en el camino correcto? Un badge de CLI junto al encabezado indica si la sesión es una transcripción de Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity o Goose. Muestra una línea de tiempo de todo lo que ocurrió en una sesión: -- **Mensajes** - Las respuestas de texto de Claude y los prompts del usuario +- **Mensajes** - Respuestas de texto de Claude y prompts del usuario - **Llamadas a herramientas** - Cada herramienta que Claude invocó, con su entrada y salida - **Actividad de políticas** - Para cada llamada a herramienta, qué políticas se activaron y qué decisión devolvieron -La barra de estadísticas en la parte superior muestra la duración de la sesión, el total de llamadas a herramientas y un resumen de las decisiones de los hooks (recuentos de allow / deny / instruct). +La barra de estadísticas en la parte superior muestra la duración de la sesión, el total de llamadas a herramientas y un resumen de las decisiones de hooks (recuentos de allow / deny / instruct). -Haz clic en el botón **Descargar Logs** para exportar la sesión. Para sesiones de Claude Code, Codex, Copilot, Cursor y Pi obtienes la transcripción JSONL original en disco byte a byte; para OpenCode (cuyas sesiones viven en SQLite, no en disco) obtienes un documento JSON que refleja las tablas subyacentes `session` / `messages` / `parts`. +Haz clic en el botón **Download Logs** para exportar la sesión. Para sesiones de Claude Code, Codex, Copilot, Cursor y Pi obtienes la transcripción JSONL original en disco byte a byte; para OpenCode (cuyas sesiones residen en SQLite, no en disco) obtienes un documento JSON que refleja las tablas subyacentes `session` / `messages` / `parts`. ### Auditoría -Un informe con personalidad propia sobre cómo se ha comportado realmente tu agente a lo largo de sesiones pasadas. Ejecuta el mismo escaneo que el CLI `failproofai audit` pero lo renderiza como un póster de pantalla completa compartible + cuatro secciones debajo del pliegue: +Un informe con personalidad sobre cómo se ha comportado realmente tu agente a lo largo de sesiones pasadas. Ejecuta el mismo análisis que el CLI `failproofai audit` pero lo muestra como un póster compartible en pantalla completa + cuatro secciones debajo del pliegue: -1. **Póster** — ocupa el primer viewport. Región de captura PNG autónoma con el logotipo de failproof_ai + etiqueta de auditoría · índice de arquetipo (`№ NN de 08`) + fecha de auditoría · puntuación numérica (0–100) + píldora de rango percentil (`top 15%`) · el nombre del arquetipo (uno de `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + tira de 3 palabras clave · línea de rareza `// solo el N% de los agentes son este arquetipo` · tesela de símbolo de 8×8 píxeles · pie de página `audit yours → failproof.ai`. Tres botones de compartir se ubican justo fuera del área de captura: `post your archetype` (X intent), `share on linkedin`, `download poster`. La captura se realiza con `html-to-image` para que el PNG coincida píxel a píxel con el renderizado en pantalla (bordes discontinuos, máscara SVG del logotipo, degradados, métricas de fuente — todo preservado). -2. **Fortalezas** — lista de filas con ✓ tranquilas sobre comportamientos que tu agente ya hace bien, derivadas de los datos de auditoría en vivo (tasa limpia de llamadas a herramientas, sin pushes directos a main, cero filtraciones de credenciales, cero tormentas de reintentos) — cada una aparece solo cuando la política relevante tiene un historial limpio durante la ventana de auditoría. -3. **Peculiaridades** — tabla de lo que se escapó, ordenada por severidad: `cuándo · qué se escapó + la política que lo habría detectado · píldora de severidad · visto`, donde la recurrencia se lee como `new` (una vez), `N× seen` (2–9 veces) o `recurring` (10+). -4. **Cómo mejorar** — lista de filas tranquilas, una por política prescrita: nombre de la política en blanco, descripción de una línea, comando de instalación + botón de copiar a la derecha. El encabezado de la sección dice `enable all N → projected · ` (la puntuación que alcanzarías con todas las correcciones aplicadas), y su botón `[install all]` copia el comando combinado `failproofai policy add a b c …` para cada política prescrita. -5. **Vuelve mejor** — dos tarjetas una al lado de la otra. Izquierda: establecer un recordatorio (selector de cadencia `3d` / `7d` / `14d` / `30d`; persiste a través de `/api/auth/reminder` una vez autenticado). Derecha: desbloquear ventajas failproof — `invite a friend` abre un modal que acepta una lista separada por comas/espacios/saltos de línea de correos de amigos (máx. 10 por envío), hace POST a `/api/audit/invite`, que reenvía al servidor API `POST /v0/invite`. El servidor API envía un correo por destinatario desde `invite@failproof.ai` con el remitente en Cc y `Reply-To` configurado, para que el destinatario vea quién lo invitó y el remitente reciba una copia en su bandeja de entrada. Los usuarios anónimos son dirigidos primero al `AuthDialog` para que el correo del remitente sea conocido antes de enviar las invitaciones. El cumplimiento de derechos/ventajas es una tarea de seguimiento. +1. **Póster** — ocupa el primer viewport. Región de captura PNG autónoma con el wordmark failproof_ai + etiqueta de auditoría · índice de arquetipo (`№ NN de 08`) + fecha de auditoría · puntuación numérica (0–100) + píldora de rango percentil (`top 15%`) · el nombre del arquetipo (uno de `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + tira de 3 palabras clave · línea de rareza `// only N% of agents are this archetype` · tile de símbolo de 8×8 píxeles · pie de página `audit yours → failproof.ai`. Tres botones de compartir se ubican justo fuera del área de captura: `post your archetype` (X intent), `share on linkedin`, `download poster`. La captura se realiza mediante `html-to-image` para que el PNG coincida con el renderizado en pantalla píxel a píxel (bordes discontinuos, máscara SVG del logo, degradados, métricas de fuente — todo preservado). +2. **Fortalezas** — lista de filas ✓ serenas con comportamientos que tu agente ya hace bien, derivados de los datos de auditoría en vivo (tasa de llamadas a herramientas limpias, sin pushes directos a main, cero filtraciones de credenciales, cero tormentas de reintentos) — cada una mostrada solo cuando la política relevante tiene un historial limpio en la ventana de auditoría. +3. **Peculiaridades** — tabla de lo que se escapó, ordenado por severidad: `cuando · qué se escapó + la política que lo habría detectado · píldora de severidad · visto`, donde la recurrencia se lee como `new` (una vez), `N× seen` (2–9 veces), o `recurring` (10+). +4. **Cómo mejorar** — lista de filas serenas, una por política prescrita: nombre de política en blanco, descripción de una línea, comando de instalación + botón de copiar a la derecha. El encabezado de la sección dice `enable all N → projected · ` (la puntuación que alcanzarías con todas las correcciones aplicadas), y su botón `[install all]` copia el comando combinado `failproofai policy add a b c …` para cada política prescrita. +5. **Vuelve mejorado** — dos tarjetas lado a lado. Izquierda: establecer un recordatorio (selector de cadencia `3d` / `7d` / `14d` / `30d`; persiste mediante `/api/auth/reminder` una vez autenticado). Derecha: desbloquear ventajas de failproof — `invite a friend` abre un modal que acepta una lista de correos de amigos separados por comas, espacios o saltos de línea (máx. 10 por envío), los publica en `/api/audit/invite`, que reenvía al `POST /v0/invite` del api-server. El api-server envía un correo por destinatario desde `invite@failproof.ai` con el remitente en Cc y `Reply-To` configurado, para que el destinatario vea quién le invitó y el remitente reciba una copia en su bandeja de entrada. Los usuarios anónimos pasan primero por el `AuthDialog` para que el correo del remitente sea conocido antes de enviar invitaciones. El cumplimiento de derechos/ventajas es una tarea pendiente. -Impulsado por el runtime de `failproofai audit` — consulta [Audit CLI](/es/cli/audit) para el motor de escaneo subyacente, los flags admitidos y los invariantes de caché por transcripción. El dashboard almacena en caché el último resultado en `~/.failproofai/audit-dashboard.json` (modo `0600`, ranura única, las nuevas ejecuciones sobreescriben) para que las revisitas sean instantáneas; **tanto la caché por transcripción como la caché del resultado completo se rechazan al leer una vez que tienen más de 7 días** para que el dashboard nunca sirva silenciosamente un resultado de una semana atrás — pasado el TTL, `/audit` cae a su estado vacío y solicita una nueva ejecución. Hacer clic en `[ re-audit now ]` cerca de la parte inferior del informe hace POST a `/api/audit/run` con `noCache: true` — la re-auditoría omite la caché por transcripción y re-escanea cada transcripción desde cero en lugar de devolver silenciosamente el resultado en caché — y el dashboard consulta `/api/audit/status` a 1Hz hasta que finaliza la ejecución; una franja de progreso rosa fija se ancla en la parte superior del viewport durante la ejecución con un temporizador de tiempo transcurrido, y el nuevo resultado se intercambia en su lugar al terminar exitosamente (sin recarga completa de página; una re-auditoría fallida deja el informe anterior intacto). En caso de fallo, la franja se vuelve roja con texto basado en el `RerunError.kind` (`timeout` / `network` / `post_failed`). El estado vacío (sin caché o caducado) y el estado sin sesiones (caché existe pero el escaneo no encontró transcripciones) se muestran por separado. +Impulsado por el runtime de `failproofai audit` — consulta [Audit CLI](/es/cli/audit) para el motor de análisis subyacente, los flags admitidos y los invariantes de caché por transcripción. El dashboard almacena en caché el último resultado en `~/.failproofai/audit-dashboard.json` (modo `0600`, ranura única, las nuevas ejecuciones sobrescriben) para que las visitas posteriores sean instantáneas; **tanto la caché por transcripción como la caché del resultado completo se rechazan al leer una vez que superan los 7 días de antigüedad**, por lo que el dashboard nunca sirve silenciosamente un resultado de una semana — pasado el TTL, `/audit` cae a su estado vacío y solicita una nueva ejecución. Hacer clic en `[ re-audit now ]` cerca de la parte inferior del informe publica `/api/audit/run` con `noCache: true` — la re-auditoría omite la caché por transcripción y vuelve a analizar cada transcripción desde cero en lugar de devolver silenciosamente el resultado en caché — y el dashboard consulta `/api/audit/status` a 1Hz hasta que finaliza la ejecución; una tira de progreso rosa fija se ancla en la parte superior del viewport durante la ejecución con un temporizador transcurrido, y el resultado actualizado reemplaza el anterior al completarse (sin recarga completa de página; una re-auditoría fallida deja el informe anterior intacto). En caso de fallo, la tira se vuelve roja con texto según el `RerunError.kind` (`timeout` / `network` / `post_failed`). El estado vacío (sin caché o expirado) y el estado de cero sesiones (caché existe pero el análisis no encontró transcripciones) se muestran por separado. ### Políticas -Una página de dos pestañas para gestionar políticas y revisar la actividad. +Una página de dos pestañas para gestionar políticas y revisar actividad. - - Selección múltiple de qué CLIs de agentes protege failproofai desde un único panel — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi y Hermes tienen cada uno una fila con el estado de instalación (`Active` / `Detected` / `Inactive`), la ruta de configuración de alcance de usuario y un acento de color de marca. Marca o desmarca los CLIs que deseas y haz clic en `Apply changes` para instalar/desinstalar la diferencia en un solo paso. Los CLIs cuyo binario se detecta en el PATH están marcados previamente. + - Selección múltiple de qué CLIs de agentes protege failproofai desde un único panel — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi y Hermes tienen cada uno una fila con el estado de instalación (`Active` / `Detected` / `Inactive`), la ruta de configuración de ámbito de usuario y un acento de color de marca. Marca o desmarca los CLIs que quieras y haz clic en `Apply changes` para instalar/desinstalar la diferencia en un solo paso. Los CLIs cuyo binario se detecta en PATH vienen pre-marcados. - Activa o desactiva políticas individuales con un solo clic (escribe en `~/.failproofai/policies-config.json` — compartido entre todos los CLIs instalados) - Expande una política para configurar sus parámetros (para políticas que admiten `policyParams`) - - Establece una ruta de archivo de políticas personalizada + - Establece una ruta de archivo de políticas personalizadas - - Historial paginado completo de cada evento de hook que se ha disparado en todas las sesiones + - Historial paginado completo de cada evento de hook que se ha activado en todas las sesiones - Filtra por decisión, tipo de evento, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), nombre de política o ID de sesión - - Cada fila muestra: marca de tiempo, nombre de política, decisión, insignia de CLI (naranja = Claude Code, morado = OpenAI Codex, azul = GitHub Copilot, esmeralda = Cursor Agent, ámbar = OpenCode, rosa = Pi, índigo = Hermes, verde azulado = OpenClaw, rosa intenso = Factory Droid, violeta = Devin, cian = Antigravity, lima = Goose), nombre de herramienta, ID de sesión y el motivo de las decisiones deny/instruct - - Haz clic en un ID de sesión para abrir su transcripción — el visor detecta automáticamente qué CLI disparó el hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) y muestra la insignia de CLI correspondiente en el encabezado + - Cada fila muestra: marca de tiempo, nombre de política, decisión, badge de CLI (naranja = Claude Code, morado = OpenAI Codex, azul = GitHub Copilot, esmeralda = Cursor Agent, ámbar = OpenCode, rosa = Pi, índigo = Hermes, verde azulado = OpenClaw, rosa oscuro = Factory Droid, violeta = Devin, cian = Antigravity, lima = Goose), nombre de herramienta, ID de sesión y el motivo de las decisiones deny/instruct + - Haz clic en un ID de sesión para abrir su transcripción — el visor detecta automáticamente qué CLI activó el hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) y muestra el badge de CLI correspondiente en el encabezado @@ -92,7 +94,7 @@ Una página de dos pestañas para gestionar políticas y revisar la actividad. ## Actualización automática -El dashboard tiene un interruptor de actualización automática en la navegación superior. Cuando está habilitado, la página actual se actualiza periódicamente para mostrar nuevas sesiones y actividad de políticas a medida que aparecen. Esencial para monitorear sesiones de agentes autónomos de larga duración. +El dashboard tiene un botón de actualización automática en la navegación superior. Cuando está activado, la página actual se refresca periódicamente para mostrar nuevas sesiones y actividad de políticas a medida que aparecen. Imprescindible para monitorear sesiones de agentes autónomos de larga duración. --- @@ -110,7 +112,7 @@ Valores válidos: `policies`, `projects`, `audit`. ## Configurar la ruta de proyectos -Por defecto, el dashboard lee desde el directorio estándar de proyectos de Claude Code. Sobreescríbelo para configuraciones personalizadas: +Por defecto, el dashboard lee desde el directorio estándar de proyectos de Claude Code. Puedes reemplazarlo para configuraciones personalizadas: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -118,15 +120,15 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Acceso desde un host que no es localhost +## Acceder desde un host que no sea localhost -Al ejecutar el dashboard en **modo desarrollo** (`npm run dev`) y acceder a él desde un nombre de host distinto de `localhost` — por ejemplo, un dominio personalizado, una IP remota o una URL tunelizada — puede aparecer una advertencia como: +Al ejecutar el dashboard en **modo de desarrollo** (`npm run dev`) y acceder a él desde un hostname distinto de `localhost` — por ejemplo, un dominio personalizado, una IP remota o una URL tunelizada — puedes ver una advertencia como: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Esto ocurre porque Next.js bloquea el acceso de origen cruzado a su websocket de HMR (recarga en caliente de módulos), que es una función exclusiva del modo desarrollo. Para permitir tu host, usa el flag `--allowed-origins`: +Esto es Next.js bloqueando el acceso de origen cruzado a su websocket HMR (recarga en caliente de módulos), que es una función exclusiva del modo de desarrollo. Para permitir tu host, usa el flag `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -145,5 +147,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Esto solo aplica al modo desarrollo. Al ejecutar `failproofai` (modo producción), no hay websocket de HMR ni problemas de recursos de desarrollo de origen cruzado. +Esto solo aplica al modo de desarrollo. Al ejecutar `failproofai` (modo de producción), no hay websocket HMR ni problemas de recursos de desarrollo de origen cruzado. \ No newline at end of file diff --git a/docs/fr/configuration.mdx b/docs/fr/configuration.mdx index 28427cba..1ed0e6fa 100644 --- a/docs/fr/configuration.mdx +++ b/docs/fr/configuration.mdx @@ -1,10 +1,10 @@ --- title: Configuration -description: "Format du fichier de configuration, système à trois niveaux et règles de fusion" +description: "Format du fichier de config, système à trois niveaux et règles de fusion" icon: gear --- -failproofai utilise des fichiers de configuration JSON pour contrôler quelles politiques sont actives, comment elles se comportent et où charger les politiques personnalisées. La configuration est conçue pour être facilement partageable avec votre équipe — commitez-la dans votre dépôt et chaque développeur bénéficie du même filet de sécurité pour l'agent. +failproofai utilise des fichiers de configuration JSON pour contrôler les politiques actives, leur comportement et l'emplacement des politiques personnalisées. La configuration est conçue pour être facilement partagée en équipe — versionnez-la dans votre dépôt et chaque développeur bénéficie du même filet de sécurité pour les agents. --- @@ -14,9 +14,9 @@ Il existe trois niveaux de configuration, évalués par ordre de priorité : | Niveau | Chemin du fichier | Rôle | |--------|-------------------|------| -| **project** | `.failproofai/policies-config.json` | Paramètres par dépôt, committés dans le contrôle de version | -| **local** | `.failproofai/policies-config.local.json` | Substitutions personnelles par dépôt, ignorées par git | -| **global** | `~/.failproofai/policies-config.json` | Valeurs par défaut au niveau utilisateur pour tous les projets | +| **project** | `.failproofai/policies-config.json` | Paramètres par dépôt, versionnés | +| **local** | `.failproofai/policies-config.local.json` | Surcharges personnelles par dépôt, ignorées par git | +| **global** | `~/.failproofai/policies-config.json` | Valeurs par défaut pour tous les projets | Lorsque failproofai reçoit un événement de hook, il charge et fusionne les trois fichiers qui existent pour le répertoire de travail courant. @@ -42,14 +42,16 @@ resolved: { allowPatterns: ["sudo apt-get update"] } ← project l'emporte, gl ``` ```text -project: (pas d'entrée block-sudo) -local: (pas d'entrée block-sudo) +project: (aucune entrée block-sudo) +local: (aucune entrée block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← redescend jusqu'au global +resolved: { allowPatterns: ["sudo systemctl status"] } ← repli sur global ``` -**`customPoliciesPath`** — le premier niveau qui le définit l'emporte. +**`customPoliciesPaths` / `customPoliciesPath`** — le premier niveau qui définit l'une ou l'autre forme l'emporte. + +**`disabledCustomPolicies`** — union de tous les niveaux. Le tableau de bord écrit un identifiant qualifié par la source ici lorsque vous désactivez une politique individuelle provenant d'un fichier de politiques explicite ou issu d'une convention. Les politiques non listées restent activées par défaut ; les identifiants incluent le fichier source afin que des politiques portant le même nom dans plusieurs fichiers puissent être contrôlées indépendamment. **`llm`** — le premier niveau qui le définit l'emporte. @@ -102,7 +104,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← redescend jusqu'au g Type : `string[]` -Liste des noms de politiques à activer. Les noms doivent correspondre exactement aux identifiants de politique affichés par `failproofai policies`. Consultez [Built-in Policies](/fr/built-in-policies) pour la liste complète. +Liste des noms de politiques à activer. Les noms doivent correspondre exactement aux identifiants affichés par `failproofai policies`. Consultez [Politiques intégrées](/fr/built-in-policies) pour la liste complète. Les politiques absentes de `enabledPolicies` sont inactives, même si elles ont des entrées dans `policyParams`. @@ -110,19 +112,19 @@ Les politiques absentes de `enabledPolicies` sont inactives, même si elles ont Type : `Record>` -Substitutions de paramètres par politique. La clé externe est le nom de la politique ; les clés internes sont spécifiques à chaque politique. Chaque politique documente ses paramètres disponibles dans [Built-in Policies](/fr/built-in-policies). +Surcharges de paramètres par politique. La clé externe est le nom de la politique ; les clés internes sont propres à chaque politique. Chaque politique documente ses paramètres disponibles dans [Politiques intégrées](/fr/built-in-policies). -Si une politique possède des paramètres mais que vous ne les spécifiez pas, les valeurs par défaut intégrées de la politique sont utilisées. Les utilisateurs qui ne configurent pas `policyParams` du tout obtiennent un comportement identique aux versions précédentes. +Si une politique possède des paramètres que vous ne spécifiez pas, les valeurs par défaut intégrées à la politique sont utilisées. Les utilisateurs qui ne configurent pas `policyParams` du tout obtiennent un comportement identique aux versions précédentes. -Les clés inconnues dans le bloc de paramètres d'une politique sont silencieusement ignorées lors du déclenchement du hook, mais signalées comme avertissements lorsque vous exécutez `failproofai policies`. +Les clés inconnues dans le bloc de paramètres d'une politique sont silencieusement ignorées au moment du déclenchement du hook, mais signalées comme avertissements lors de l'exécution de `failproofai policies`. #### `hint` (transversal) Type : `string` (optionnel) -Un message ajouté à la raison lorsqu'une politique renvoie `deny` ou `instruct`. Utilisez-le pour donner à Claude des indications exploitables sans modifier la politique elle-même. +Un message ajouté à la raison lorsqu'une politique retourne `deny` ou `instruct`. Utilisez-le pour donner à Claude des indications exploitables sans modifier la politique elle-même. -Fonctionne avec n'importe quel type de politique — intégrée, personnalisée (`custom/`), convention de projet (`.failproofai-project/`) ou convention utilisateur (`.failproofai-user/`). +Fonctionne avec tout type de politique — intégrée, personnalisée (`custom/`), convention de projet (`.failproofai-project/`) ou convention utilisateur (`.failproofai-user/`). ```json { @@ -143,15 +145,15 @@ Fonctionne avec n'importe quel type de politique — intégrée, personnalisée Lorsque `block-force-push` refuse, Claude voit : *« Force-pushing is blocked. Try creating a fresh branch instead. »* -Les valeurs non-chaînes et les chaînes vides sont silencieusement ignorées. Si `hint` n'est pas défini, le comportement reste inchangé (rétrocompatible). +Les valeurs non-chaîne et les chaînes vides sont silencieusement ignorées. Si `hint` n'est pas défini, le comportement reste inchangé (rétrocompatible). ### `customPoliciesPath` Type : `string` (chemin absolu) -Chemin vers un fichier JavaScript contenant des politiques de hook personnalisées. Ce champ est défini automatiquement par `failproofai policies --install --custom ` (le chemin est résolu en absolu avant d'être stocké). +Chemin vers un fichier JavaScript contenant des politiques de hook personnalisées. Ce champ est défini automatiquement par `failproofai policies --install --custom ` (le chemin est résolu en absolu avant d'être enregistré). -Le fichier est chargé à nouveau à chaque événement de hook — il n'y a pas de mise en cache. Consultez [Custom Policies](/fr/custom-policies) pour les détails de création. +Le fichier est rechargé à chaque événement de hook — aucune mise en cache n'est effectuée. Consultez [Politiques personnalisées](/fr/custom-policies) pour les détails de création. ### Politiques basées sur les conventions @@ -162,19 +164,19 @@ En plus du `customPoliciesPath` explicite, failproofai découvre et charge autom | Projet | `.failproofai/policies/` | Partagé avec l'équipe via le contrôle de version | | Utilisateur | `~/.failproofai/policies/` | Personnel, s'applique à tous les projets | -**Correspondance de fichiers :** Seuls les fichiers correspondant à `*policies.{js,mjs,ts}` sont chargés (par exemple `security-policies.mjs`, `workflow-policies.js`). Les autres fichiers du répertoire sont ignorés. +**Correspondance de fichiers :** Seuls les fichiers correspondant à `*policies.{js,mjs,ts}` sont chargés (ex. `security-policies.mjs`, `workflow-policies.js`). Les autres fichiers du répertoire sont ignorés. -**Aucune configuration requise :** Les politiques de convention ne nécessitent aucune entrée dans `policies-config.json`. Déposez simplement des fichiers dans le répertoire et ils seront pris en compte au prochain événement de hook. +**Aucune configuration requise :** Les politiques de convention ne nécessitent aucune entrée dans `policies-config.json`. Déposez simplement les fichiers dans le répertoire et ils seront pris en compte au prochain événement de hook. -**Chargement par union :** Les répertoires de convention du projet et de l'utilisateur sont tous deux analysés. Tous les fichiers correspondants des deux niveaux sont chargés (contrairement à `customPoliciesPath` qui utilise la règle premier-niveau-gagnant). +**Chargement par union :** Les répertoires de convention du projet et de l'utilisateur sont tous deux analysés. Tous les fichiers correspondants des deux niveaux sont chargés (contrairement à `customPoliciesPath` qui applique la règle du premier niveau gagnant). -Consultez [Custom Policies](/fr/custom-policies) pour plus de détails et d'exemples. +Consultez [Politiques personnalisées](/fr/custom-policies) pour plus de détails et d'exemples. ### `llm` Type : `object` (optionnel) -Configuration du client LLM pour les politiques qui effectuent des appels IA. Non requis pour la plupart des configurations. +Configuration du client LLM pour les politiques qui effectuent des appels à l'IA. Non requise pour la plupart des configurations. ```json { @@ -189,19 +191,24 @@ Configuration du client LLM pour les politiques qui effectuent des appels IA. No ## Gestion de la configuration depuis la CLI -Les commandes `policies --install` et `policies --uninstall` écrivent dans le fichier de paramètres des hooks de votre CLI agent (les points d'entrée des hooks), tandis que `policies-config.json` est le fichier que vous gérez directement. Les deux sont distincts : +Les commandes `policies --install` et `policies --uninstall` écrivent dans le fichier de paramètres de hooks de votre CLI agent (les points d'entrée des hooks), tandis que `policies-config.json` est le fichier que vous gérez directement. Les deux sont distincts : - **Paramètres de la CLI agent** — indique à l'agent d'appeler `failproofai --hook ` à chaque utilisation d'outil : - **Claude Code** : `~/.claude/settings.json` (utilisateur), `/.claude/settings.json` (projet), `/.claude/settings.local.json` (local) - **OpenAI Codex** : `~/.codex/hooks.json` (utilisateur), `/.codex/hooks.json` (projet) — Codex n'a pas de niveau `local` - - **GitHub Copilot CLI _(bêta)_** : `~/.copilot/hooks/failproofai.json` (utilisateur), `/.github/hooks/failproofai.json` (projet) — Copilot n'a pas de niveau `local`. Les entrées de hook utilisent les champs de commande `bash`/`powershell` à clé OS de Copilot avec `timeoutSec` ; le fichier porte un marqueur `version: 1` au niveau racine. La prise en charge de Copilot CLI est en **bêta** pendant que nous vérifions le schéma d'enregistrement `events.jsonl` (que la documentation publique ne spécifie pas) contre davantage de sessions réelles. - - **Cursor Agent _(bêta)_** : `~/.cursor/hooks.json` (utilisateur), `/.cursor/hooks.json` (projet) — Cursor n'a pas de niveau `local`. Les entrées de hook utilisent la forme `{type, command, timeout}` inspirée de Claude (sans séparation `bash`/`powershell`), mais stockées sous des clés d'événement en camelCase (`preToolUse`, `beforeSubmitPrompt`, …) dans un tableau plat selon le [schéma de hooks](https://cursor.com/docs/hooks) de Cursor ; le fichier porte un marqueur `version: 1` au niveau racine. Le gestionnaire canonicalise camelCase → PascalCase via `CURSOR_EVENT_MAP` afin que les politiques intégrées existantes se déclenchent sans modification. La prise en charge de Cursor Agent est en **bêta** pendant que nous vérifions le format de transcription sur disque de Cursor (non spécifié dans la documentation publique) contre davantage d'installations réelles. - - **OpenCode _(bêta)_** : `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (utilisateur), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (projet) — OpenCode n'a pas de niveau `local`. Contrairement aux cinq autres CLI, OpenCode **n'a pas de système de hook par commande externe** : il charge des plugins JS/TS en cours de processus explicitement enregistrés via le tableau `plugin: []` dans `opencode.json` (la découverte automatique depuis `.opencode/plugins/` **n'est pas** le mode de chargement des plugins sur opencode v1.14.33). L'installation dépose un petit shim de plugin généré qui appelle le binaire failproofai en sous-processus et traduit la réponse JSON en forme Claude du binaire vers la sémantique du plugin : `throw new Error()` pour le refus d'événement outil (annule l'appel d'outil), `client.session.prompt(...)` pour instruct ET pour le refus `Stop` / `SubagentStop` (soumet le motif de refus comme prochain message utilisateur — le seul canal de nouvelle tentative forcée puisque `session.idle` est uniquement pour les notifications et qu'une exception levée depuis celui-ci est un no-op), et no-op pour allow. Le shim canonicalise les noms d'outils (minuscules → PascalCase via `OPENCODE_TOOL_MAP`) et les clés d'arguments d'entrée d'outil (camelCase → snake_case via `OPENCODE_TOOL_INPUT_MAP` pour `Read` / `Write` / `Edit`, par exemple `filePath` → `file_path`, `oldString` → `old_string`) avant de transmettre au binaire, de sorte que les politiques intégrées de vérification de chemin comme `block-read-outside-cwd`, `block-env-files` et `block-secrets-write` se déclenchent sans modification sur les appels d'outils OpenCode. Les sessions vivent dans la base de données SQLite d'opencode à `~/.local/share/opencode/opencode.db` ; la visionneuse de sessions du tableau de bord les lit via `opencode db --format json` et `opencode export `. La prise en charge d'OpenCode est en **bêta** pendant que nous vérifions le comportement entre les versions et contre davantage de sessions réelles. Consultez la [documentation des plugins OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(bêta)_** : `~/.pi/agent/settings.json` (utilisateur), `/.pi/settings.json` (projet) — Pi n'a pas de niveau `local`. Pi charge des packages d'extension TypeScript au démarrage ; le fichier de paramètres est un tableau de chaînes plat `{"packages": ["./relative/path", …]}`. failproofai écrit une seule entrée dans le tableau packages pointant vers son répertoire `pi-extension/` intégré. L'extension s'abonne en interne aux événements `tool_call` / `user_bash` / `input` / `session_start` de Pi et exécute `failproofai --hook --cli pi` en shell ; le gestionnaire canonicalise les événements underscore_lower_snake_case → PascalCase via `PI_EVENT_MAP` afin que les politiques intégrées existantes se déclenchent sans modification. Les arguments d'entrée d'outil sont également canonicalisés via `PI_TOOL_INPUT_MAP` (les commandes Read / Write / Edit de Pi livrent `path` plutôt que `file_path` ; mapper la clé de niveau supérieur permet à `block-env-files` et `block-secrets-write` de se déclencher — `block-read-outside-cwd` avait déjà un fallback `path`). La prise en charge de Pi est en **bêta** pendant que l'API d'extension de Pi et la disposition du journal de session se stabilisent. - - **Hermes (hermes-agent)** : `~/.hermes/config.yaml` (**niveau utilisateur uniquement** — Hermes n'a pas de configuration projet/local). Hermes est une **passerelle** Slack/Telegram, donc une seule installation intercepte les appels d'outils de toutes les plateformes (Slack/Telegram/cli/cron) **et** des sous-agents internes. Les entrées de hook sont une paire `{command, timeout}` (timeout en **secondes**) sous une map `hooks:` indexée par les événements snake_case de Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) ; le gestionnaire canonicalise les événements via `HERMES_EVENT_MAP` et les noms d'outils via `HERMES_TOOL_MAP` afin que les politiques intégrées se déclenchent sans modification. La configuration est modifiée via un aller-retour `Document` YAML préservant les commentaires, de sorte que les autres paramètres de l'opérateur survivent, et l'installation définit `hooks_auto_accept: true` pour que la passerelle sans tête (sans TTY) exécute les hooks sans invite de consentement. L'évaluateur émet le contrat stdout `{"decision":"block","reason"}` de Hermes (Hermes ignore les codes de sortie). **Limitations :** Hermes n'a pas d'événement `Stop` de fin de tour, donc les politiques intégrées `require-*-before-stop` ne se déclenchent jamais pour lui (non applicable, pas cassé) ; `instruct` se dégrade en allow-avec-note-journalisée (pas de canal de contexte supplémentaire) ; et la redaction des secrets en sortie (`sanitize-*`) ne peut pas réécrire la sortie d'outil via le contrat de hook shell. Hermes est **également** une source d'**audit** hors ligne — le tableau de bord lit ses sessions de passerelle directement depuis `~/.hermes/state.db`. + - **GitHub Copilot CLI _(bêta)_** : `~/.copilot/hooks/failproofai.json` (utilisateur), `/.github/hooks/failproofai.json` (projet) — Copilot n'a pas de niveau `local`. Les entrées de hook utilisent les champs de commande `bash`/`powershell` propres à l'OS de Copilot avec `timeoutSec` ; le fichier porte un marqueur `version: 1` au niveau supérieur. La prise en charge de Copilot CLI est en **bêta** pendant que nous vérifions le schéma des enregistrements `events.jsonl` (non spécifié dans la documentation publique) sur davantage de sessions réelles. **VS Code Copilot Chat en mode agent (Preview)** lit les configurations de hooks depuis `.github/hooks/*.json`, `~/.copilot/hooks/*.json` et `~/.claude/settings.json` (gouverné par le paramètre `chat.hookFilesLocations`) en utilisant le même contrat Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — exactement les chemins que cette intégration `copilot` et l'intégration `claude` (`~/.claude/settings.json`) écrivent déjà, donc `failproofai policies --install --cli copilot` (ou `--cli claude`) **applique déjà les politiques en mode agent VS Code** sans intégration `vscode` séparée (confirmé en direct depuis les journaux de découverte de VS Code). + - **Cursor Agent _(bêta)_** : `~/.cursor/hooks.json` (utilisateur), `/.cursor/hooks.json` (projet) — Cursor n'a pas de niveau `local`. Les entrées de hook utilisent la forme Claude `{type, command, timeout}` (sans séparation `bash`/`powershell`), mais stockées sous des clés d'événements en camelCase (`preToolUse`, `beforeSubmitPrompt`, …) dans un tableau plat selon le [schéma de hooks](https://cursor.com/docs/hooks) de Cursor ; le fichier porte un marqueur `version: 1` au niveau supérieur. Le gestionnaire normalise camelCase → PascalCase via `CURSOR_EVENT_MAP` afin que les politiques intégrées existantes se déclenchent sans modification. La prise en charge de Cursor Agent est en **bêta** pendant que nous vérifions le format de transcription sur disque de Cursor (non spécifié dans la documentation publique) sur davantage d'installations réelles. + - **OpenCode _(bêta)_** : `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (utilisateur), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (projet) — OpenCode n'a pas de niveau `local`. Contrairement aux cinq autres CLI, OpenCode **n'a pas de système de hooks par commandes externes** : il charge des plugins JS/TS en interne, explicitement enregistrés via le tableau `plugin: []` dans `opencode.json` (la découverte automatique depuis `.opencode/plugins/` **ne correspond pas** au fonctionnement des plugins sur opencode v1.14.33). L'installation dépose un petit plugin shim généré qui appelle le binaire failproofai en sous-processus et traduit la réponse JSON de forme Claude du binaire en sémantique de plugin : `throw new Error()` pour le refus d'événement outil (annule l'appel d'outil), `client.session.prompt(...)` pour instruct ET pour le refus `Stop` / `SubagentStop` (soumet la raison du refus comme prochain message utilisateur — le seul canal de forçage de relance puisque `session.idle` est en lecture seule et qu'une exception depuis celui-ci est un no-op), et no-op pour allow. Le shim normalise les noms d'outils (minuscules → PascalCase via `OPENCODE_TOOL_MAP`) et les clés d'arguments d'entrée d'outils (camelCase → snake_case via `OPENCODE_TOOL_INPUT_MAP` pour `Read` / `Write` / `Edit`, ex. `filePath` → `file_path`, `oldString` → `old_string`) avant de transmettre au binaire, de sorte que les politiques intégrées vérifiant les chemins comme `block-read-outside-cwd`, `block-env-files` et `block-secrets-write` se déclenchent sans modification sur les appels d'outils OpenCode. Les sessions sont stockées dans la base de données SQLite d'opencode à `~/.local/share/opencode/opencode.db` ; la visionneuse de sessions du tableau de bord les lit via `opencode db --format json` et `opencode export `. La prise en charge d'OpenCode est en **bêta** pendant que nous vérifions le comportement entre versions et sur davantage de sessions réelles. Consultez la [documentation des plugins OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(bêta)_** : `~/.pi/agent/settings.json` (utilisateur), `/.pi/settings.json` (projet) — Pi n'a pas de niveau `local`. Pi charge des packages d'extension TypeScript au démarrage ; le fichier de paramètres est un tableau de chaînes plat `{"packages": ["./relative/path", …]}`. failproofai écrit une seule entrée dans le tableau packages pointant vers son répertoire `pi-extension/` intégré. L'extension souscrit en interne aux événements `tool_call` / `user_bash` / `input` / `session_start` de Pi et appelle `failproofai --hook --cli pi` en sous-processus ; le gestionnaire normalise underscore_lower_snake_case → PascalCase via `PI_EVENT_MAP` afin que les politiques intégrées existantes se déclenchent sans modification. Les arguments d'entrée d'outils sont également normalisés via `PI_TOOL_INPUT_MAP` (Read / Write / Edit de Pi livrent `path` plutôt que `file_path` ; le mapping de la clé de niveau supérieur permet à `block-env-files` et `block-secrets-write` de se déclencher — `block-read-outside-cwd` disposait déjà d'un repli sur `path`). La prise en charge de Pi est en **bêta** pendant que l'API d'extension de Pi et la disposition des journaux de session se stabilisent. + - **Hermes (hermes-agent)** : `~/.hermes/config.yaml` (**niveau utilisateur uniquement** — Hermes n'a pas de configuration projet/local). Hermes est une **passerelle** Slack/Telegram, donc une seule installation intercepte les appels d'outils de chaque plateforme (Slack/Telegram/cli/cron) **et** des sous-agents internes. Les entrées de hook sont une paire `{command, timeout}` (timeout en **secondes**) sous une map `hooks:` indexée par les événements snake_case de Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) ; le gestionnaire normalise les événements via `HERMES_EVENT_MAP` et les noms d'outils via `HERMES_TOOL_MAP` afin que les politiques intégrées se déclenchent sans modification. La configuration est modifiée via un aller-retour YAML `Document` préservant les commentaires afin que les autres paramètres de l'opérateur survivent, et l'installation définit `hooks_auto_accept: true` pour que la passerelle sans interface (sans TTY) exécute les hooks sans invite de consentement. L'évaluateur émet le contrat stdout `{"decision":"block","reason"}` de Hermes (Hermes ignore les codes de sortie). **Limitations :** Hermes n'a pas d'événement `Stop` de fin de tour, donc les politiques intégrées `require-*-before-stop` ne se déclenchent jamais pour lui (non applicable, non cassé) ; `instruct` se dégrade en allow-avec-note-journalisée (pas de canal de contexte supplémentaire) ; et la rédaction des secrets en sortie (`sanitize-*`) ne peut pas réécrire la sortie d'outil via le contrat de hook shell. Hermes est **aussi** une source d'**audit** hors ligne — le tableau de bord lit ses sessions de passerelle directement depuis `~/.hermes/state.db`. + - **OpenClaw (passerelle openclaw)** : `~/.openclaw/openclaw.json` (**niveau utilisateur uniquement** — OpenClaw n'a pas de configuration projet/local). Comme Hermes, OpenClaw est une **passerelle** multi-canaux auto-hébergée, donc une seule installation intercepte les appels d'outils de chaque canal et de ses sous-agents internes. L'application des politiques passe par les **hooks de plugin en interne** d'OpenClaw (ses hooks internes basés sur des fichiers sont uniquement observatoires et ne peuvent pas bloquer), donc — comme OpenCode/Pi — failproofai livre un package statique `openclaw-plugin/` qui lance de manière asynchrone le binaire failproofai et traduit le verdict. L'installation enregistre le répertoire de plugin livré dans `plugins.load.paths[]` de `openclaw.json` et l'active sous `plugins.entries.failproofai` (avec `hooks.allowConversationAccess: true`, requis pour les hooks de conversation brute). L'évaluateur émet un verdict plat `{permission, reason}` et le shim le mappe à la forme de retour native de chaque hook : `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), et `before_agent_finalize → {action:"revise", reason}` (**Stop** — une vraie porte de fin de tour, donc les politiques intégrées `require-*-before-stop` **s'appliquent** sur OpenClaw, contrairement à Hermes). Les événements et noms d'outils sont normalisés côté binaire via `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) afin que les politiques intégrées se déclenchent sans modification ; le shim échoue en mode ouvert en cas d'erreur de lancement/parsing/timeout. OpenClaw est **aussi** une source d'**audit** hors ligne — le tableau de bord lit ses sessions JSONL à `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)** : `~/.factory/hooks.json` (utilisateur), `/.factory/hooks.json` (projet) — Factory n'a pas de niveau `local`. droid dispose d'un système de hooks par commandes externes de style Claude, mais avec deux particularités vérifiées en direct contre droid v0.171.0 : (1) les noms d'événements sont au **niveau supérieur** de `hooks.json` — il **n'y a pas de wrapper `"hooks"`** (droid le rejette) ; les événements d'outil (`PreToolUse`/`PostToolUse`) portent `"matcher": "*"`, les événements non-outil l'omettent. (2) Le refus est piloté par le **code de sortie 2 + stderr** du hook, pas par une décision JSON — la branche `factory` de l'évaluateur retourne le code de sortie 2 pour les événements outil/prompt et `{decision:"block", reason}` uniquement sur l'événement `Stop` de fin de tour (le seul canal de forçage de relance de droid). Les événements sont déjà en PascalCase (pas de map d'événements) et le payload est en snake_case Claude ; seuls les noms d'outils sont normalisés via `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory est **aussi** une source d'**audit** hors ligne — le tableau de bord lit ses sessions JSONL sur disque à `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)** : `~/.config/devin/config.json` (utilisateur), `/.devin/config.json` (projet) — Devin n'a pas de niveau `local`. Devin est un **clone pur de Claude** vérifié en direct contre devin v3000.1.27 : il utilise le schéma standard avec wrapper `"hooks"` de Claude (les écritures préservent la fusion afin que les autres clés du fichier de configuration — `org_id`, `theme_mode`, … — survivent), des noms d'événements déjà en PascalCase (pas de map d'événements, pas de branche de gestionnaire), et un payload stdin en snake_case Claude (pas de normalisation). La branche `devin` de l'évaluateur refuse avec `{"decision":"block","reason"}` JSON sur stdout au code de sortie 0 pour **chaque** événement (vérifié — le blocage a surchargé `--permission-mode dangerous`) ; sur l'événement `Stop` de fin de tour, la raison porte le libellé de forçage de relance MANDATORY-ACTION afin que les politiques intégrées `require-*-before-stop` s'appliquent. Seuls les noms d'outils sont normalisés via `DEVIN_TOOL_MAP` (`exec→Bash` ; `tool_input.command` est déjà canonique). Devin est **aussi** une source d'**audit** hors ligne — le tableau de bord lit ses sessions SQLite à `~/.local/share/devin/cli/sessions.db` (chaque ligne `sessions` porte un vrai `working_directory`, donc les sessions se regroupent par cwd de projet comme Claude). + - **Antigravity CLI (`agy`)** : `~/.gemini/config/hooks.json` (utilisateur), `/.agents/hooks.json` (projet) — Antigravity n'a pas de niveau `local`. Contrairement à Factory/Devin, Antigravity possède son **propre** contrat (pas un clone Claude), vérifié en direct contre agy v1.1.2. `hooks.json` utilise un schéma de **hooks nommés** : la clé de niveau supérieur est un *nom* de hook (`"failproofai"`) dont la valeur est une map événement→gestionnaires — les événements d'outil (`PreToolUse`/`PostToolUse`) encapsulent les gestionnaires dans `{matcher:"*", hooks:[…]}`, tandis que `PreInvocation`/`Stop` sont des **tableaux plats** de gestionnaires (les autres hooks nommés sont préservés). Le payload stdin est en **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai le normalise en snake_case avant l'exécution des politiques, et mappe les args PascalCase de `run_command` (`CommandLine`/`Cwd`) via `ANTIGRAVITY_TOOL_INPUT_MAP`. La branche `antigravity` de l'évaluateur utilise les **propres** formes de réponse d'Antigravity : `{decision:"deny", reason}` bloque un outil/prompt (code de sortie 0), `{decision:"continue", reason}` sur l'événement `Stop` de fin de tour relance la boucle (donc les politiques intégrées `require-*-before-stop` s'appliquent), et `{injectSteps:[{ephemeralMessage}]}` injecte une instruction sur `PreInvocation` (→ `UserPromptSubmit`). Les noms d'outils sont normalisés via `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity est **aussi** une source d'**audit** hors ligne — le tableau de bord lit ses transcriptions JSONL brutes à `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (index des conversations dans `conversation_summaries.db`). + - **Goose (nom de code goose, Block)** : `~/.agents/plugins/failproofai/hooks/hooks.json` (utilisateur), `/.agents/plugins/failproofai/hooks/hooks.json` (projet) — Goose n'a pas de niveau `local`. L'application des politiques utilise le système de **hooks** de Goose, la spécification inter-agents **Open Plugins** : l'installateur dépose simplement le répertoire de plugin `failproofai` et Goose le découvre automatiquement au démarrage (en l'auto-enregistrant dans `~/.config/goose/config.yaml`). Le `hooks.json` utilise un schéma Open Plugins **avec** un wrapper `"hooks"` au niveau supérieur, et le matcher est **omis** sur chaque événement — un simple `"*"` est une regex invalide qui ne correspond à rien (vérifié en direct contre goose v1.43.0). Les noms d'événements sont déjà en PascalCase (pas de map d'événements) ; le payload stdin utilise `event`/`working_dir`, que le gestionnaire normalise en `hook_event_name`/`cwd`. La branche `goose` de l'évaluateur refuse avec `{"decision":"block","reason"}` JSON sur stdout au code de sortie 0, honoré uniquement sur l'événement **`PreToolUse`** (livré dans goose ≥ v1.37.0) — qui se déclenche pour l'outil shell **et à l'intérieur des sous-agents délégués**, ce qui en fait le seul point de refus suffisant ; toute autre erreur de hook échoue en mode **ouvert**. Goose **n'a pas d'événement `Stop`**, donc les politiques intégrées `require-*-before-stop` ne s'appliquent pas (comme pour Hermes). Les noms d'outils sont normalisés via `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) et les clés de chemin via `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose est **aussi** une source d'**audit** hors ligne — le tableau de bord lit ses sessions SQLite à `~/.local/share/goose/sessions/sessions.db` (chaque ligne `sessions` porte un vrai `working_dir`, donc les sessions se regroupent par cwd de projet comme Devin ; les exécutions isolées `--no-session` sont filtrées). - **`policies-config.json`** — indique à failproofai quelles politiques évaluer et avec quels paramètres (partagé entre toutes les CLI agent) -Passez `--cli claude|codex|copilot|cursor|opencode|pi|hermes` pour cibler un agent spécifique (séparé par des espaces ou répété pour tout sous-ensemble) : +Passez `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` pour cibler un agent spécifique (séparés par des espaces ou répétés pour tout sous-ensemble) : ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +217,28 @@ failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli hermes --scope user -failproofai policies --install --cli claude codex copilot cursor opencode pi +failproofai policies --install --cli openclaw --scope user +failproofai policies --install --cli factory --scope project +failproofai policies --install --cli devin --scope project +failproofai policies --install --cli antigravity --scope project +failproofai policies --install --cli goose --scope project +failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -Lorsque `--cli` est omis, `failproofai` détecte quelles CLI agent sont installées (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`) : +Lorsque `--cli` est omis, `failproofai` détecte quelles CLI agent sont installées (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`) : -- **Une CLI détectée** — sélectionne automatiquement cette CLI sans demander de confirmation. -- **Plusieurs CLI détectées** dans un terminal interactif — affiche une invite de sélection unique par touches fléchées regroupée en une section `Detected (N)` (avec une ligne agrégée `Install for all N detected` + chaque CLI détectée individuellement) et une section `Not installed (M) · install hooks ahead of time` listant chaque CLI prise en charge non détectée comme option d'installation anticipée (↑↓ pour déplacer, Entrée pour sélectionner, ^C pour quitter). Le flux de désinstallation n'affiche que la section Detected. -- **Plusieurs CLI détectées** lors d'une exécution non interactive (CI, sans TTY) — installe pour toutes les CLI détectées sans demander de confirmation. -- **Aucune détectée** — revient à `claude`, avec un avertissement qu'aucun binaire agent n'a été trouvé dans PATH ; la commande de hook est tout de même écrite afin qu'elle s'active dès que vous en installez un. +- **Une seule CLI détectée** — sélectionne automatiquement cette CLI sans demande de confirmation. +- **Plusieurs CLI détectées** dans un terminal interactif — affiche une invite de sélection unique à flèches regroupée en une section `Detected (N)` (avec une ligne agrégée `Install for all N detected` + chaque CLI détectée individuellement) et une section `Not installed (M) · install hooks ahead of time` listant toutes les CLI supportées non détectées comme options d'installation anticipée (↑↓ pour déplacer, Entrée pour sélectionner, ^C pour quitter). Le flux de désinstallation affiche uniquement la section Detected. +- **Plusieurs CLI détectées** dans une exécution non interactive (CI, sans TTY) — installe pour toutes les CLI détectées sans demande de confirmation. +- **Aucune détectée** — repli sur `claude`, avec un avertissement qu'aucun binaire d'agent n'a été trouvé dans le PATH ; la commande de hook est quand même écrite pour qu'elle s'active dès que vous en installez un. -Vous pouvez modifier `policies-config.json` directement à tout moment ; les modifications prennent effet immédiatement au prochain événement de hook, sans redémarrage nécessaire. +Vous pouvez modifier `policies-config.json` directement à tout moment ; les changements prennent effet immédiatement au prochain événement de hook sans redémarrage. --- ## Exemple : configuration au niveau projet avec les valeurs par défaut de l'équipe -Committez `.failproofai/policies-config.json` dans votre dépôt : +Versionnez `.failproofai/policies-config.json` dans votre dépôt : ```json { @@ -245,4 +257,4 @@ Committez `.failproofai/policies-config.json` dans votre dépôt : } ``` -Chaque développeur peut ensuite créer `.failproofai/policies-config.local.json` (ignoré par git) pour des substitutions personnelles sans affecter ses coéquipiers. \ No newline at end of file +Chaque développeur peut ensuite créer `.failproofai/policies-config.local.json` (ignoré par git) pour ses surcharges personnelles sans affecter les membres de l'équipe. \ No newline at end of file diff --git a/docs/fr/custom-policies.mdx b/docs/fr/custom-policies.mdx index 23a6d39c..d6342cde 100644 --- a/docs/fr/custom-policies.mdx +++ b/docs/fr/custom-policies.mdx @@ -1,10 +1,10 @@ --- title: Politiques personnalisées -description: "Écrivez vos propres politiques en JavaScript - appliquer des conventions, prévenir la dérive, détecter les échecs, s'intégrer avec des systèmes externes" +description: "Écrivez vos propres politiques en JavaScript - appliquer des conventions, prévenir la dérive, détecter les défaillances, s'intégrer avec des systèmes externes" icon: code --- -Les politiques personnalisées vous permettent d'écrire des règles pour n'importe quel comportement d'agent : appliquer des conventions de projet, prévenir la dérive, bloquer les opérations destructives, détecter les agents bloqués, ou s'intégrer avec Slack, des workflows d'approbation, et plus encore. Elles utilisent le même système d'événements de hook et les mêmes décisions `allow`, `deny`, `instruct` que les politiques intégrées. +Les politiques personnalisées vous permettent d'écrire des règles pour n'importe quel comportement d'agent : appliquer des conventions de projet, prévenir la dérive, bloquer les opérations destructives, détecter les agents bloqués ou s'intégrer avec Slack, des workflows d'approbation, et plus encore. Elles utilisent le même système d'événements de hook et les mêmes décisions `allow`, `deny`, `instruct` que les politiques intégrées. --- @@ -39,9 +39,9 @@ failproofai policies --install --custom ./my-policies.js ## Deux façons de charger des politiques personnalisées -### Option 1 : Par convention (recommandée) +### Option 1 : Par convention (recommandé) -Déposez des fichiers `*policies.{js,mjs,ts}` dans `.failproofai/policies/` et ils sont chargés automatiquement — aucun indicateur ni modification de configuration nécessaire. Cela fonctionne comme les hooks git : déposez un fichier, ça marche tout de suite. +Déposez des fichiers `*policies.{js,mjs,ts}` dans `.failproofai/policies/` et ils sont chargés automatiquement — aucun flag ni modification de configuration requis. Cela fonctionne comme les hooks git : déposez un fichier, il s'active tout seul. ``` # Niveau projet — commité dans git, partagé avec l'équipe @@ -53,14 +53,14 @@ Déposez des fichiers `*policies.{js,mjs,ts}` dans `.failproofai/policies/` et i ``` **Fonctionnement :** -- Les répertoires du projet et de l'utilisateur sont tous les deux analysés (union — pas de premier-scope-wins) +- Les répertoires projet et utilisateur sont tous deux analysés (union — pas de règle premier-scope-gagne) - Les fichiers sont chargés par ordre alphabétique dans chaque répertoire. Préfixez avec `01-`, `02-` pour contrôler l'ordre - Seuls les fichiers correspondant à `*policies.{js,mjs,ts}` sont chargés ; les autres fichiers sont ignorés - Chaque fichier est chargé indépendamment (fail-open par fichier) -- Fonctionne en parallèle avec les fichiers `--custom` explicites et les politiques intégrées +- Fonctionne en parallèle avec `--custom` explicite et les politiques intégrées -Les politiques de convention sont le moyen le plus simple d'établir un standard de qualité pour votre organisation. Commitez `.failproofai/policies/` dans git et chaque membre de l'équipe reçoit automatiquement les mêmes règles — aucune configuration individuelle nécessaire. Au fur et à mesure que votre équipe découvre de nouveaux modes d'échec, ajoutez une politique et poussez-la. Ces politiques deviennent avec le temps un standard de qualité vivant qui s'améliore à chaque contribution. +Les politiques par convention sont le moyen le plus simple d'établir un standard de qualité pour votre organisation. Committez `.failproofai/policies/` dans git et chaque membre de l'équipe obtient automatiquement les mêmes règles — aucune configuration par développeur requise. Au fur et à mesure que votre équipe découvre de nouveaux modes de défaillance, ajoutez une politique et poussez. Ces politiques deviennent au fil du temps un standard de qualité vivant qui s'améliore à chaque contribution. ### Option 2 : Chemin de fichier explicite @@ -69,22 +69,27 @@ Les politiques de convention sont le moyen le plus simple d'établir un standard # Installer avec un fichier de politiques personnalisées failproofai policies --install --custom ./my-policies.js -# Remplacer le chemin du fichier de politiques +# Remplacer les chemins de politiques personnalisées failproofai policies --install --custom ./new-policies.js -# Supprimer le chemin des politiques personnalisées de la configuration +# Configurer plusieurs fichiers explicites (chargés dans l'ordre des flags) +failproofai policies --install --custom ./security.js --custom ./workflow.js + +# Supprimer tous les chemins de politiques personnalisées explicites de la config failproofai policies --uninstall --custom ``` -Le chemin absolu résolu est stocké dans `policies-config.json` sous la clé `customPoliciesPath`. Le fichier est rechargé à chaque événement de hook - il n'y a pas de mise en cache entre les événements. +Les chemins absolus résolus sont stockés dans `policies-config.json` sous `customPoliciesPaths`. Répétez `--custom` pour configurer plusieurs fichiers. Les configurations existantes utilisant le champ hérité `customPoliciesPath` continuent de fonctionner. Les fichiers sont rechargés à chaque événement de hook — il n'y a pas de mise en cache entre les événements. + +Chaque politique enregistrée apparaît avec son propre interrupteur dans le tableau de bord. Désactiver une politique enregistre son ID qualifié par source dans `disabledCustomPolicies` ; le fichier et ses autres politiques continuent de se charger, tandis que la politique désactivée est exclue avant la correspondance d'événements. Les noms de politiques dupliqués entre fichiers ont des interrupteurs indépendants. ### Utiliser les deux ensemble -Les politiques de convention et le fichier `--custom` explicite peuvent coexister. Ordre de chargement : +Les politiques par convention et les fichiers `--custom` explicites peuvent coexister. Ordre de chargement : -1. Fichier `customPoliciesPath` explicite (si configuré) -2. Fichiers de convention du projet (`{cwd}/.failproofai/policies/`, alphabétique) -3. Fichiers de convention de l'utilisateur (`~/.failproofai/policies/`, alphabétique) +1. Fichiers `customPoliciesPaths` explicites (dans l'ordre configuré) +2. Fichiers de convention du projet (`{cwd}/.failproofai/policies/`, par ordre alphabétique) +3. Fichiers de convention utilisateur (`~/.failproofai/policies/`, par ordre alphabétique) --- @@ -102,41 +107,41 @@ Enregistre une politique. Appelez cette fonction autant de fois que nécessaire ```ts customPolicies.add({ - name: string; // requis - identifiant unique - description?: string; // affiché dans la sortie de `failproofai policies` - match?: { events?: HookEventType[] }; // filtre par type d'événement ; omis pour correspondre à tous + name: string; // required - unique identifier + description?: string; // shown in `failproofai policies` output + match?: { events?: HookEventType[] }; // filter by event type; omit to match all fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### Fonctions d'aide aux décisions +### Fonctions de décision | Fonction | Effet | Utiliser quand | |----------|--------|----------| -| `allow()` | Autorise l'opération silencieusement | L'action est sûre, aucun message nécessaire | -| `deny(message)` | Bloque l'opération | L'agent ne doit pas effectuer cette action | -| `instruct(message)` | Ajoute du contexte sans bloquer | Fournir à l'agent un contexte supplémentaire pour rester sur la bonne voie | +| `allow()` | Autoriser l'opération silencieusement | L'action est sûre, aucun message nécessaire | +| `deny(message)` | Bloquer l'opération | L'agent ne doit pas effectuer cette action | +| `instruct(message)` | Ajouter du contexte sans bloquer | Donner à l'agent du contexte supplémentaire pour rester sur la bonne voie | -`deny(message)` - le message apparaît à Claude préfixé par `"Blocked by failproofai:"`. Un seul `deny` court-circuite toute évaluation ultérieure. +`deny(message)` — le message apparaît à Claude préfixé par `"Blocked by failproofai:"`. Un seul `deny` court-circuite toute évaluation ultérieure. -`instruct(message)` - le message est ajouté au contexte de Claude pour l'appel d'outil en cours. Tous les messages `instruct` sont accumulés et délivrés ensemble. +`instruct(message)` — le message est ajouté au contexte de Claude pour l'appel d'outil en cours. Tous les messages `instruct` sont accumulés et délivrés ensemble. -Vous pouvez ajouter des instructions supplémentaires à n'importe quel message `deny` ou `instruct` en ajoutant un champ `hint` dans `policyParams` — aucune modification de code nécessaire. Cela fonctionne également pour les politiques personnalisées (`custom/`), les politiques de convention de projet (`.failproofai-project/`) et les politiques de convention utilisateur (`.failproofai-user/`). Voir [Configuration → hint](/fr/configuration#hint-cross-cutting) pour plus de détails. +Vous pouvez ajouter des instructions supplémentaires à n'importe quel message `deny` ou `instruct` en ajoutant un champ `hint` dans `policyParams` — aucune modification de code requise. Cela fonctionne également pour les politiques personnalisées (`custom/`), les politiques de convention de projet (`.failproofai-project/`) et les politiques de convention utilisateur (`.failproofai-user/`). Consultez [Configuration → hint](/fr/configuration#hint-cross-cutting) pour plus de détails. -### Messages allow informationnels +### Messages allow informatifs -`allow(message)` autorise l'opération **et** envoie un message informationnel à Claude. Le message est délivré sous forme d'`additionalContext` dans la réponse stdout du gestionnaire de hook — le même mécanisme utilisé par `instruct`, mais sémantiquement différent : c'est une mise à jour de statut, pas un avertissement. +`allow(message)` autorise l'opération **et** envoie un message informatif à Claude. Le message est délivré en tant que `additionalContext` dans la réponse stdout du gestionnaire de hook — le même mécanisme utilisé par `instruct`, mais sémantiquement différent : il s'agit d'une mise à jour de statut, pas d'un avertissement. | Fonction | Effet | Utiliser quand | |----------|--------|----------| -| `allow(message)` | Autorise et envoie du contexte à Claude | Confirmer qu'une vérification a réussi, ou expliquer pourquoi une vérification a été ignorée | +| `allow(message)` | Autoriser et envoyer du contexte à Claude | Confirmer qu'une vérification a réussi, ou expliquer pourquoi une vérification a été ignorée | -Cas d'usage : +Cas d'utilisation : - **Confirmations de statut :** `allow("All CI checks passed.")` — indique à Claude que tout est en ordre -- **Explications fail-open :** `allow("GitHub CLI not installed, skipping CI check.")` — indique à Claude pourquoi une vérification a été ignorée pour qu'il dispose du contexte complet -- **Accumulation de plusieurs messages :** si plusieurs politiques retournent chacune `allow(message)`, tous les messages sont joints avec des sauts de ligne et délivrés ensemble +- **Explications fail-open :** `allow("GitHub CLI not installed, skipping CI check.")` — indique à Claude pourquoi une vérification a été ignorée afin qu'il dispose de tout le contexte +- **Accumulation de messages :** si plusieurs politiques retournent chacune `allow(message)`, tous les messages sont joints avec des sauts de ligne et délivrés ensemble ```js customPolicies.add({ @@ -162,7 +167,7 @@ customPolicies.add({ | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | | `toolName` | `string \| undefined` | L'outil appelé (ex. `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | Les paramètres d'entrée de l'outil | -| `payload` | `Record` | Charge utile brute complète de l'événement provenant de Claude Code | +| `payload` | `Record` | Payload brut complet de l'événement provenant de Claude Code | | `session` | `SessionMetadata \| undefined` | Contexte de session (voir ci-dessous) | ### Champs de `SessionMetadata` @@ -189,9 +194,9 @@ customPolicies.add({ Les politiques sont évaluées dans cet ordre : 1. Politiques intégrées (dans l'ordre de définition) -2. Politiques personnalisées explicites depuis `customPoliciesPath` (dans l'ordre des `.add()`) -3. Politiques de convention du projet `.failproofai/policies/` (fichiers alphabétiques, ordre des `.add()` à l'intérieur) -4. Politiques de convention de l'utilisateur `~/.failproofai/policies/` (fichiers alphabétiques, ordre des `.add()` à l'intérieur) +2. Politiques personnalisées explicites depuis `customPoliciesPath` (dans l'ordre `.add()`) +3. Politiques de convention du projet `.failproofai/policies/` (fichiers par ordre alphabétique, ordre `.add()` à l'intérieur) +4. Politiques de convention utilisateur `~/.failproofai/policies/` (fichiers par ordre alphabétique, ordre `.add()` à l'intérieur) Le premier `deny` court-circuite toutes les politiques suivantes. Tous les messages `instruct` sont accumulés et délivrés ensemble. @@ -224,21 +229,21 @@ Tous les imports relatifs accessibles depuis le fichier d'entrée sont résolus. ## Filtrage par type d'événement -Utilisez `match.events` pour limiter le déclenchement d'une politique : +Utilisez `match.events` pour limiter quand une politique se déclenche : ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Se déclenche uniquement à la fin de la session + // Ne se déclenche que lorsque la session se termine // ctx.session.transcriptPath contient le journal complet de la session return allow(); }, }); ``` -Omettez entièrement `match` pour se déclencher à chaque type d'événement. +Omettez `match` entièrement pour se déclencher à chaque type d'événement. --- @@ -248,13 +253,13 @@ Les politiques personnalisées sont **fail-open** : les erreurs ne bloquent jama | Défaillance | Comportement | |---------|----------| -| `customPoliciesPath` non défini | Aucune politique personnalisée explicite ne s'exécute ; les politiques de convention et les politiques intégrées continuent normalement | -| Fichier introuvable | Avertissement enregistré dans `~/.failproofai/hook.log` ; les politiques intégrées continuent | -| Erreur de syntaxe/import (explicite) | Erreur enregistrée dans `~/.failproofai/hook.log` ; les politiques personnalisées explicites ignorées | -| Erreur de syntaxe/import (convention) | Erreur enregistrée ; ce fichier ignoré, les autres fichiers de convention se chargent quand même | -| `fn` lève une exception à l'exécution | Erreur enregistrée ; ce hook traité comme `allow` ; les autres hooks continuent | -| `fn` prend plus de 10s | Timeout enregistré ; traité comme `allow` | -| Répertoire de convention manquant | Aucune politique de convention ne s'exécute ; aucune erreur | +| `customPoliciesPath` non défini | Aucune politique personnalisée explicite n'est exécutée ; les politiques de convention et les politiques intégrées continuent normalement | +| Fichier introuvable | Avertissement journalisé dans `~/.failproofai/hook.log` ; les politiques intégrées continuent | +| Erreur de syntaxe/import (explicite) | Erreur journalisée dans `~/.failproofai/hook.log` ; politiques personnalisées explicites ignorées | +| Erreur de syntaxe/import (convention) | Erreur journalisée ; ce fichier ignoré, les autres fichiers de convention se chargent quand même | +| `fn` lève une exception à l'exécution | Erreur journalisée ; ce hook traité comme `allow` ; les autres hooks continuent | +| `fn` prend plus de 10s | Timeout journalisé ; traité comme `allow` | +| Répertoire de convention manquant | Aucune politique de convention n'est exécutée ; aucune erreur | Pour déboguer les erreurs de politiques personnalisées, surveillez le fichier de log : @@ -285,7 +290,7 @@ customPolicies.add({ }, }); -// Maintenir l'agent sur la bonne voie : vérifier les tests avant de commiter +// Maintenir l'agent sur la bonne voie : vérifier les tests avant de committer customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -327,18 +332,18 @@ Le répertoire `examples/` contient des fichiers de politiques prêts à l'emplo | Fichier | Contenu | |------|----------| -| `examples/policies-basic.js` | Cinq politiques de démarrage couvrant les modes d'échec courants des agents | -| `examples/policies-advanced/index.js` | Modèles avancés : imports transitifs, appels asynchrones, épuration des sorties et hooks de fin de session | -| `examples/convention-policies/security-policies.mjs` | Politiques de sécurité basées sur la convention (bloquer les écritures .env, empêcher la réécriture de l'historique git) | -| `examples/convention-policies/workflow-policies.mjs` | Politiques de workflow basées sur la convention (rappels de tests, audit des écritures de fichiers) | +| `examples/policies-basic.js` | Cinq politiques de démarrage couvrant les modes de défaillance courants des agents | +| `examples/policies-advanced/index.js` | Modèles avancés : imports transitifs, appels asynchrones, nettoyage des sorties et hooks de fin de session | +| `examples/convention-policies/security-policies.mjs` | Politiques de sécurité par convention (blocage des écritures .env, prévention de la réécriture de l'historique git) | +| `examples/convention-policies/workflow-policies.mjs` | Politiques de workflow par convention (rappels de tests, audit des écritures de fichiers) | -### Utiliser les exemples de fichiers explicites +### Utiliser les exemples avec fichier explicite ```bash failproofai policies --install --custom ./examples/policies-basic.js ``` -### Utiliser les exemples basés sur la convention +### Utiliser les exemples par convention ```bash # Copier au niveau du projet @@ -350,4 +355,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -Aucune commande d'installation nécessaire — les fichiers sont récupérés automatiquement lors du prochain événement de hook. \ No newline at end of file +Aucune commande d'installation requise — les fichiers sont récupérés automatiquement au prochain événement de hook. \ No newline at end of file diff --git a/docs/fr/dashboard.mdx b/docs/fr/dashboard.mdx index cb6180c0..6a93bf26 100644 --- a/docs/fr/dashboard.mdx +++ b/docs/fr/dashboard.mdx @@ -1,10 +1,10 @@ --- title: Tableau de bord -description: "Surveillez les sessions d'agents, examinez les appels d'outils et gérez les politiques" +description: "Surveiller les sessions d'agent, examiner les appels d'outils et gérer les politiques" icon: chart-line --- -Le tableau de bord failproofai est une application web locale permettant de surveiller vos sessions d'agents IA et de gérer les politiques. Consultez ce que vos agents ont fait pendant votre absence. +Le tableau de bord failproofai est une application web locale pour surveiller vos sessions d'agent IA et gérer les politiques. Voyez ce que vos agents ont fait pendant votre absence. --- @@ -16,7 +16,7 @@ failproofai S'ouvre à l'adresse `http://localhost:8020`. -Le tableau de bord lit directement les données de configuration locales du projet, des sessions et de failproofai depuis le système de fichiers. Les fonctionnalités optionnelles authentifiées, telles que les rappels d'audit et les invitations, envoient les informations nécessaires à ces requêtes (y compris les adresses e-mail) vers des API distantes. +Le tableau de bord lit les données locales du projet, de la session et de la configuration failproofai directement depuis le système de fichiers. Les fonctionnalités optionnelles authentifiées, telles que les rappels d'audit et les invitations, envoient les informations nécessaires à ces requêtes (y compris les adresses e-mail) vers des API distantes. --- @@ -24,50 +24,52 @@ Le tableau de bord lit directement les données de configuration locales du proj ### Projets -Liste tous les projets Claude Code, OpenAI Codex, GitHub Copilot CLI _(bêta)_, Cursor Agent _(bêta)_, OpenCode _(bêta)_, Pi _(bêta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity et Goose trouvés sur votre machine. Les projets Claude sont découverts depuis `~/.claude/projects/` (ou le chemin défini par `CLAUDE_PROJECTS_PATH`) ; les projets Codex sont découverts en analysant chaque transcript sous `~/.codex/sessions///
/*.jsonl` et regroupés par le `cwd` enregistré dans le premier enregistrement de chaque session ; les projets Copilot CLI sont découverts en analysant chaque `~/.copilot/session-state//workspace.yaml` (configurable via `COPILOT_HOME`) et regroupés par son champ `cwd` ; les projets Cursor Agent sont découverts en analysant les métadonnées par session sous `~/.cursor/agent-sessions//` (configurable via `CURSOR_HOME`, avec `conversations/` et `sessions/` sondés comme alternatives) pour un scalaire `cwd` dans `meta.json` / `session.json` / `workspace.yaml` ; les projets OpenCode sont découverts en interrogeant sa base de données SQLite à `~/.local/share/opencode/opencode.db` via `opencode db --format json` (nous lisons les tables `session` et `project` et regroupons par `project_id`) ; les projets Pi sont découverts en analysant les transcripts JSONL par session sous `~/.pi/agent/sessions//_.jsonl` (configurable via `PI_SESSIONS_DIR`) et en extrayant le `cwd` du premier enregistrement de chaque session ; les sessions de la passerelle Hermes sont lues directement depuis sa base SQLite à `~/.hermes/state.db` (configurable via `HERMES_DB_PATH`) et regroupées en projets `hermes-` par `source` (Slack/Telegram/cli/cron — les sessions de passerelle n'ont pas de cwd) ; les sessions de la passerelle OpenClaw sont lues depuis `~/.openclaw/agents//sessions/*.jsonl` et regroupées en projets `openclaw-` (également sans cwd) ; les projets Factory Droid sont découverts à partir des transcripts JSONL dans `~/.factory/sessions//*.jsonl` et regroupés par cwd ; les projets Devin depuis sa base SQLite à `~/.local/share/devin/cli/sessions.db` (regroupés par `working_directory` de chaque session) ; les projets Antigravity depuis les transcripts JSONL dans `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` et regroupés par cwd ; et les projets Goose depuis sa base SQLite à `~/.local/share/goose/sessions/sessions.db` (regroupés par `working_dir` de chaque session). Un projet utilisé par plusieurs CLI s'affiche sur une seule ligne avec tous les badges correspondants. Utilisez le menu déroulant **CLI** au-dessus du tableau pour filtrer par un agent CLI spécifique ; l'URL conserve votre sélection sous la forme `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +Liste tous les projets Claude Code, OpenAI Codex, GitHub Copilot CLI _(bêta)_, Cursor Agent _(bêta)_, OpenCode _(bêta)_, Pi _(bêta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity et Goose trouvés sur votre machine. Les projets Claude sont découverts depuis `~/.claude/projects/` (ou le chemin défini par `CLAUDE_PROJECTS_PATH`) ; les projets Codex sont découverts en analysant chaque transcript sous `~/.codex/sessions///
/*.jsonl` et en les regroupant par le `cwd` enregistré dans le premier enregistrement de chaque session ; les projets Copilot CLI sont découverts en analysant chaque `~/.copilot/session-state//workspace.yaml` (configurable via `COPILOT_HOME`) et en les regroupant par leur champ `cwd` ; les projets Cursor Agent sont découverts en analysant les métadonnées par session sous `~/.cursor/agent-sessions//` (configurable via `CURSOR_HOME`, avec `conversations/` et `sessions/` sondés comme alternatives) pour un scalaire `cwd` dans `meta.json` / `session.json` / `workspace.yaml` ; les projets OpenCode sont découverts en interrogeant sa base de données SQLite à `~/.local/share/opencode/opencode.db` via `opencode db --format json` (nous lisons les tables `session` et `project` et les regroupons par `project_id`) ; les projets Pi sont découverts en analysant les transcripts JSONL par session sous `~/.pi/agent/sessions//_.jsonl` (configurable via `PI_SESSIONS_DIR`) et en extrayant le `cwd` du premier enregistrement de chaque session ; les sessions de passerelle Hermes sont lues directement depuis le stockage SQLite de chaque profil — `~/.hermes/state.db` plus `~/.hermes/profiles//state.db` (remplaçable via `HERMES_HOME`, ou `HERMES_DB_PATH` pour une base de données unique) — et regroupées en projets `hermes--` par profil et `source` (Slack/Telegram/cli/cron — les sessions de passerelle n'ont pas de cwd) ; les sessions de passerelle OpenClaw sont lues depuis `~/.openclaw/agents//sessions/*.jsonl` et regroupées en projets `openclaw--` par agent et canal (également sans cwd) ; les projets Factory Droid sont découverts à partir des transcripts JSONL à `~/.factory/sessions//*.jsonl` et regroupés par cwd ; les projets Devin depuis sa base de données SQLite à `~/.local/share/devin/cli/sessions.db` (regroupés par le `working_directory` de chaque session) ; les projets Antigravity depuis les transcripts JSONL à `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` et regroupés par cwd ; et les projets Goose depuis sa base de données SQLite à `~/.local/share/goose/sessions/sessions.db` (regroupés par le `working_dir` de chaque session). Un projet utilisé par plusieurs CLI s'affiche sur une seule ligne avec tous les badges correspondants. Utilisez le menu déroulant **CLI** au-dessus du tableau pour filtrer par un agent CLI spécifique ; l'URL conserve votre sélection sous la forme `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. + +Hermes et OpenClaw sont à portée utilisateur et n'ont pas de répertoire de travail pour le regroupement, ils s'affichent donc sous forme d'**arborescence de dossiers rétractable** — profil (ou agent) au niveau supérieur, ses canaux en dessous — tandis que chaque CLI basé sur un cwd reste une ligne plate. Les lignes de dossier totalisent le nombre de sessions et l'activité la plus récente de tout ce qu'elles contiennent, les dossiers réduits sont mémorisés entre les visites, et une recherche par mot-clé développe ce qui correspond. Chaque projet affiche : -- Le nom du projet (dérivé du chemin du dossier) -- Un badge CLI — `Claude Code` (orange), `OpenAI Codex` (violet), `GitHub Copilot` (bleu), `Cursor Agent` (vert émeraude), `OpenCode` (ambre), `Pi` (rose) et/ou `Hermes` (indigo) -- La date de la dernière activité de session +- Nom du projet (dérivé du chemin du dossier) +- Un badge CLI — `Claude Code` (orange), `OpenAI Codex` (violet), `GitHub Copilot` (bleu), `Cursor Agent` (émeraude), `OpenCode` (ambre), `Pi` (rose) et/ou `Hermes` (indigo) +- Date de l'activité de session la plus récente Cliquez sur un projet pour voir ses sessions. ### Sessions Liste toutes les sessions d'un projet. Chaque session affiche : -- L'identifiant de session -- Les horodatages de début et de fin -- Le nombre d'appels d'outils -- Le nombre d'activités de hook (politiques déclenchées) +- ID de session +- Horodatages de début et de fin +- Nombre d'appels d'outils +- Nombre d'activités de hook (politiques déclenchées) -Utilisez le filtre de plage de dates et la recherche par identifiant de session pour affiner la liste. Les sessions sont paginées. +Utilisez le filtre de plage de dates et la recherche par ID de session pour affiner la liste. Les sessions sont paginées. -Cliquez sur une session pour ouvrir le visualiseur de session. +Cliquez sur une session pour ouvrir le visualisateur de session. -### Visualiseur de session +### Visualisateur de session -Le visualiseur de session répond à la question clé pour les agents autonomes : qu'a fait l'agent, et est-il resté dans les rails ? Un badge CLI à côté de l'en-tête indique si la session est un transcript Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity ou Goose. Il affiche une chronologie de tout ce qui s'est passé durant une session : +Le visualisateur de session répond à la question clé pour les agents autonomes : qu'a fait l'agent, et est-il resté dans les rails ? Un badge CLI à côté de l'en-tête indique si la session est un transcript Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity ou Goose. Il affiche une chronologie de tout ce qui s'est passé dans une session : - **Messages** - Les réponses textuelles de Claude et les invites utilisateur - **Appels d'outils** - Chaque outil invoqué par Claude, avec ses entrées et sorties -- **Activité des politiques** - Pour chaque appel d'outil, quelles politiques ont été déclenchées et quelle décision elles ont rendue +- **Activité des politiques** - Pour chaque appel d'outil, quelles politiques se sont déclenchées et quelle décision elles ont rendue -La barre de statistiques en haut affiche la durée de la session, le nombre total d'appels d'outils et un résumé des décisions de hook (comptes allow / deny / instruct). +La barre de statistiques en haut affiche la durée de la session, le nombre total d'appels d'outils et un résumé des décisions de hook (nombre de allow / deny / instruct). -Cliquez sur le bouton **Télécharger les logs** pour exporter la session. Pour les sessions Claude Code, Codex, Copilot, Cursor et Pi, vous obtenez le transcript JSONL original sur disque octet par octet ; pour OpenCode (dont les sessions résident dans SQLite et non sur disque), vous obtenez un document JSON reproduisant les tables sous-jacentes `session` / `messages` / `parts`. +Cliquez sur le bouton **Télécharger les journaux** pour exporter la session. Pour les sessions Claude Code, Codex, Copilot, Cursor et Pi, vous obtenez le transcript JSONL original sur disque octet par octet ; pour OpenCode (dont les sessions résident dans SQLite, pas sur disque), vous obtenez un document JSON reflétant les tables `session` / `messages` / `parts` sous-jacentes. ### Audit -Un rapport au style personnalisé de la façon dont votre agent s'est réellement comporté au fil des sessions passées. Exécute la même analyse que le CLI `failproofai audit` mais la restitue sous la forme d'une affiche partageable plein écran + quatre sections en dessous du pli : +Un rapport personnalisé décrivant comment votre agent s'est réellement comporté au fil des sessions passées. Exécute le même scan que le CLI `failproofai audit` mais l'affiche sous forme d'une affiche partageable plein écran + quatre sections sous le pli : -1. **Affiche** — occupe le premier viewport. Zone de capture PNG autonome avec le logotype failproof_ai + libellé d'audit · index d'archétype (`№ NN of 08`) + date d'audit · score numérique (0–100) + pastille de rang percentile (`top 15%`) · le nom de l'archétype (parmi `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + banderole de 3 mots-clés · ligne de rareté `// only N% of agents are this archetype` · tuile sigil 8×8 pixels · pied de page `audit yours → failproof.ai`. Trois boutons de partage se trouvent juste à l'extérieur de la zone de capture : `post your archetype` (intention X), `share on linkedin`, `download poster`. La capture passe par `html-to-image` de sorte que le PNG correspond au rendu à l'écran pixel par pixel (bordures en pointillés, masque logo SVG, dégradés, métriques de police — tout est préservé). -2. **Points forts** — liste de comportements que votre agent fait déjà correctement, présentés sous forme de lignes avec ✓, dérivés des données d'audit en direct (taux d'appels d'outils propres, aucun push direct vers main, zéro fuite d'identifiants, zéro tempête de nouvelles tentatives) — chaque élément n'apparaît que lorsque la politique correspondante présente un bilan irréprochable sur la fenêtre d'audit. -3. **Particularités** — tableau de ce qui a passé à travers les mailles, classé par gravité : `quand · ce qui a passé + la politique qui l'aurait intercepté · pastille de gravité · vu`, où la récurrence indique `new` (une fois), `N× seen` (2–9 fois), ou `recurring` (10+). -4. **Comment s'améliorer** — liste de lignes calmes, une par politique prescrite : nom de la politique en blanc, description en une ligne, commande d'installation + bouton de copie sur la droite. L'en-tête de section indique `enable all N → projected · ` (le score que vous atteindriez en appliquant tous les correctifs), et son bouton `[install all]` copie la commande combinée `failproofai policy add a b c …` pour chaque politique prescrite. -5. **Revenez amélioré** — deux cartes côte à côte. À gauche : définir un rappel (sélecteur de cadence `3d` / `7d` / `14d` / `30d` ; persiste via `/api/auth/reminder` une fois authentifié). À droite : débloquer les avantages failproof — `invite a friend` ouvre une fenêtre modale qui accepte une liste d'e-mails d'amis séparés par des virgules, espaces ou sauts de ligne (max 10 par envoi), les envoie par POST à `/api/audit/invite`, qui les transmet au `POST /v0/invite` de l'api-server. L'api-server envoie un e-mail par destinataire depuis `invite@failproof.ai` avec l'expéditeur en Cc et `Reply-To` défini, de sorte que le destinataire voit qui l'a invité et l'expéditeur reçoit une copie dans sa boîte de réception. Les utilisateurs anonymes sont d'abord redirigés vers le `AuthDialog` afin que l'e-mail de l'expéditeur soit connu avant l'envoi des invitations. La gestion des droits et avantages est prévue dans une prochaine étape. +1. **Affiche** — remplit le premier viewport. Zone de capture PNG autonome avec le logo failproof_ai + étiquette d'audit · index d'archétype (`№ NN of 08`) + date d'audit · score numérique (0–100) + pastille de rang percentile (`top 15%`) · le nom de l'archétype (l'un de `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + bande de 3 mots-clés · ligne de rareté `// only N% of agents are this archetype` · tuile de sigil 8×8 pixels · pied de page `audit yours → failproof.ai`. Trois boutons de partage se trouvent juste à l'extérieur de la zone de capture : `post your archetype` (intention X), `share on linkedin`, `download poster`. La capture passe par `html-to-image` afin que le PNG corresponde pixel par pixel au rendu à l'écran (bordures en pointillés, masque de logo SVG, dégradés, métriques de police — tout est préservé). +2. **Points forts** — liste de comportements que votre agent fait déjà correctement, dérivés des données d'audit en direct (taux d'appels d'outils propres, aucun push direct vers main, aucune fuite d'identifiants, aucune tempête de réessais) — chacun affiché uniquement lorsque la politique concernée a un bilan impeccable sur la fenêtre d'audit. +3. **Particularités** — tableau de ce qui a échappé au contrôle, classé par gravité : `when · what slipped + the policy that would've caught it · severity pill · seen`, où la récurrence indique `new` (une fois), `N× seen` (2–9 fois), ou `recurring` (10+). +4. **Comment s'améliorer** — liste de lignes, une par politique prescrite : nom de la politique en blanc, description en une ligne, commande d'installation + bouton de copie sur le côté droit. L'en-tête de section indique `enable all N → projected · ` (le score que vous atteindriez en appliquant tous les correctifs), et son bouton `[install all]` copie la commande combinée `failproofai policy add a b c …` pour chaque politique prescrite. +5. **Revenez mieux préparé** — deux cartes côte à côte. Gauche : définir un rappel (sélecteur de cadence `3d` / `7d` / `14d` / `30d` ; persiste via `/api/auth/reminder` une fois authentifié). Droite : débloquer les avantages failproof — `invite a friend` ouvre une fenêtre modale qui accepte une liste d'e-mails d'amis séparés par des virgules, espaces ou sauts de ligne (max 10 par envoi), les envoie via POST à `/api/audit/invite`, qui transmet au `POST /v0/invite` du serveur API. Le serveur API envoie un e-mail à chaque destinataire depuis `invite@failproof.ai` avec l'expéditeur en Cc et `Reply-To` défini, de sorte que le destinataire voit qui l'a invité et que l'expéditeur reçoit une copie dans sa boîte de réception. Les utilisateurs anonymes sont redirigés vers `AuthDialog` d'abord afin que l'e-mail de l'expéditeur soit connu avant l'envoi des invitations. Les droits / avantages feront l'objet d'un suivi. -Propulsé par le runtime `failproofai audit` — consultez [Audit CLI](/fr/cli/audit) pour le moteur d'analyse sous-jacent, les options supportées et les invariants de cache par transcript. Le tableau de bord met en cache le dernier résultat dans `~/.failproofai/audit-dashboard.json` (mode `0600`, emplacement unique, les nouvelles exécutions écrasent) afin que les revisites soient instantanées ; **les deux caches — par transcript et résultat global — sont rejetés à la lecture une fois qu'ils ont plus de 7 jours**, de sorte que le tableau de bord ne renvoie jamais silencieusement un résultat vieux d'une semaine — au-delà de la TTL, `/audit` revient à son état vide et invite à une nouvelle exécution. Cliquer sur `[ re-audit now ]` en bas du rapport envoie un POST à `/api/audit/run` avec `noCache: true` — la ré-analyse contourne le cache par transcript et réanalyse chaque transcript depuis zéro plutôt que de retourner silencieusement le résultat mis en cache — et le tableau de bord interroge `/api/audit/status` à 1 Hz jusqu'à la fin de l'exécution ; une bande de progression rose collante se fixe en haut du viewport pendant l'exécution avec un minuteur écoulé, et le nouveau résultat remplace l'ancien en place en cas de succès (sans rechargement complet de la page ; un échec de ré-analyse laisse le rapport précédent intact). En cas d'échec, la bande devient rouge avec un message adapté au `RerunError.kind` (`timeout` / `network` / `post_failed`). L'état vide (aucun cache ou expiré) et l'état zéro session (cache présent mais l'analyse n'a trouvé aucun transcript) sont présentés séparément. +Piloté par le moteur d'exécution `failproofai audit` — voir [Audit CLI](/fr/cli/audit) pour le moteur de scan sous-jacent, les options prises en charge et les invariants de cache par transcript. Le tableau de bord met en cache le dernier résultat à `~/.failproofai/audit-dashboard.json` (mode `0600`, emplacement unique, les nouvelles exécutions écrasent) afin que les revisites soient instantanées ; **les deux caches — par transcript et résultat global — sont rejetés à la lecture dès qu'ils ont plus de 7 jours**, de sorte que le tableau de bord ne serve jamais silencieusement un résultat vieux d'une semaine — passé le TTL, `/audit` passe à son état vide et invite à une nouvelle exécution. Cliquer sur `[ re-audit now ]` en bas du rapport envoie un POST à `/api/audit/run` avec `noCache: true` — le ré-audit contourne le cache par transcript et ré-analyse chaque transcript depuis le début plutôt que de retourner silencieusement le résultat mis en cache — et le tableau de bord interroge `/api/audit/status` à 1 Hz jusqu'à la fin de l'exécution ; une bande de progression rose collante se fixe en haut du viewport pendant l'exécution avec un minuteur écoulé, et le nouveau résultat s'affiche en place après succès (sans rechargement complet de la page ; un ré-audit échoué laisse le rapport précédent intact). En cas d'échec, la bande devient rouge avec un message basé sur le `RerunError.kind` (`timeout` / `network` / `post_failed`). L'état vide (pas de cache ou expiré) et l'état zéro session (cache existant mais le scan n'a trouvé aucun transcript) sont affichés séparément. ### Politiques @@ -75,16 +77,16 @@ Une page à deux onglets pour gérer les politiques et examiner l'activité. - - Sélectionnez les CLI d'agent que failproofai protège depuis un seul panneau — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi et Hermes ont chacun une ligne avec le statut d'installation (`Active` / `Detected` / `Inactive`), le chemin des paramètres de portée utilisateur, et un accent coloré à la marque. Cochez ou décochez les CLI souhaités et cliquez sur `Apply changes` pour installer/désinstaller les différences en une seule étape. Les CLI dont le binaire est détecté dans le PATH sont pré-cochés. - - Activez ou désactivez des politiques individuelles d'un simple clic (écrit dans `~/.failproofai/policies-config.json` — partagé entre tous les CLI installés) + - Sélectionnez en plusieurs fois les CLI d'agents que failproofai protège depuis un seul panneau — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi et Hermes ont chacun une ligne avec le statut d'installation (`Active` / `Detected` / `Inactive`), le chemin des paramètres à portée utilisateur et un accent coloré à la marque. Cochez ou décochez les CLI souhaités et cliquez sur `Apply changes` pour installer/désinstaller les différences en une seule étape. Les CLI dont le binaire est détecté dans le PATH sont pré-cochés. + - Activez ou désactivez les politiques individuelles en un seul clic (écrit dans `~/.failproofai/policies-config.json` — partagé entre chaque CLI installé) - Développez une politique pour configurer ses paramètres (pour les politiques qui prennent en charge `policyParams`) - Définissez un chemin de fichier de politiques personnalisé - Historique paginé complet de chaque événement de hook déclenché dans toutes les sessions - - Filtrez par décision, type d'événement, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(bêta)_ / Cursor Agent _(bêta)_ / OpenCode _(bêta)_ / Pi _(bêta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), nom de politique ou identifiant de session - - Chaque ligne affiche : horodatage, nom de la politique, décision, badge CLI (orange = Claude Code, violet = OpenAI Codex, bleu = GitHub Copilot, vert émeraude = Cursor Agent, ambre = OpenCode, rose = Pi, indigo = Hermes, sarcelle = OpenClaw, rose vif = Factory Droid, violet foncé = Devin, cyan = Antigravity, vert citron = Goose), nom de l'outil, identifiant de session et la raison des décisions deny/instruct - - Cliquez sur un identifiant de session pour ouvrir son transcript — le visualiseur détecte automatiquement quel CLI a déclenché le hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) et affiche le badge CLI correspondant dans l'en-tête + - Filtrer par décision, type d'événement, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(bêta)_ / Cursor Agent _(bêta)_ / OpenCode _(bêta)_ / Pi _(bêta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), nom de politique ou ID de session + - Chaque ligne affiche : horodatage, nom de la politique, décision, badge CLI (orange = Claude Code, violet = OpenAI Codex, bleu = GitHub Copilot, émeraude = Cursor Agent, ambre = OpenCode, rose = Pi, indigo = Hermes, bleu-vert = OpenClaw, rose vif = Factory Droid, violet = Devin, cyan = Antigravity, citron vert = Goose), nom de l'outil, ID de session et la raison des décisions deny/instruct + - Cliquez sur un ID de session pour ouvrir son transcript — le visualisateur détecte automatiquement quel CLI a déclenché le hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) et affiche le badge CLI correspondant dans l'en-tête @@ -92,7 +94,7 @@ Une page à deux onglets pour gérer les politiques et examiner l'activité. ## Actualisation automatique -Le tableau de bord dispose d'un bouton d'activation de l'actualisation automatique dans la navigation supérieure. Lorsqu'elle est activée, la page actuelle se rafraîchit périodiquement pour afficher les nouvelles sessions et l'activité des politiques au fur et à mesure. Indispensable pour surveiller des sessions d'agents autonomes de longue durée. +Le tableau de bord dispose d'un bouton d'actualisation automatique dans la navigation supérieure. Lorsqu'il est activé, la page actuelle s'actualise périodiquement pour afficher les nouvelles sessions et l'activité des politiques au fur et à mesure qu'elles apparaissent. Indispensable pour surveiller les sessions d'agents autonomes de longue durée. --- @@ -110,7 +112,7 @@ Valeurs valides : `policies`, `projects`, `audit`. ## Configurer le chemin des projets -Par défaut, le tableau de bord lit depuis le répertoire standard des projets Claude Code. Remplacez-le pour des configurations personnalisées : +Par défaut, le tableau de bord lit depuis le répertoire de projets Claude Code standard. Remplacez-le pour des configurations personnalisées : ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -118,21 +120,21 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Accès depuis un hôte non-localhost +## Accéder depuis un hôte autre que localhost -Lorsque vous exécutez le tableau de bord en **mode développement** (`npm run dev`) et que vous y accédez depuis un nom d'hôte autre que `localhost` — par exemple, un domaine personnalisé, une IP distante ou une URL tunnelisée — vous pouvez voir un avertissement tel que : +Lors de l'exécution du tableau de bord en **mode développement** (`npm run dev`) et de l'accès depuis un nom d'hôte autre que `localhost` — par exemple, un domaine personnalisé, une IP distante ou une URL tunnélisée — vous pouvez voir un avertissement tel que : ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Il s'agit de Next.js bloquant l'accès cross-origin à son websocket HMR (hot module reload), qui est une fonctionnalité réservée au développement. Pour autoriser votre hôte, utilisez l'option `--allowed-origins` : +Il s'agit de Next.js qui bloque l'accès cross-origin à son websocket HMR (rechargement à chaud des modules), une fonctionnalité réservée au développement. Pour autoriser votre hôte, utilisez l'option `--allowed-origins` : ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -Pour plusieurs hôtes ou adresses IP, passez une liste séparée par des virgules : +Pour plusieurs hôtes ou IP, passez une liste séparée par des virgules : ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 @@ -145,5 +147,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Ceci ne s'applique qu'au mode développement. Lors de l'exécution de `failproofai` (mode production), il n'y a ni websocket HMR ni problème de ressource de développement cross-origin. +Cela s'applique uniquement au mode développement. Lors de l'exécution de `failproofai` (mode production), il n'y a pas de websocket HMR ni de problème de ressource dev cross-origin. \ No newline at end of file diff --git a/docs/he/configuration.mdx b/docs/he/configuration.mdx index f1f81270..66c8600e 100644 --- a/docs/he/configuration.mdx +++ b/docs/he/configuration.mdx @@ -1,44 +1,45 @@ --- -title: הגדרות -description: "פורמט קובץ הגדרות, מערכת תלת-היקף, וכללי מיזוג" +--- +title: תצורה +description: "פורמט קובץ תצורה, מערכת תלת-היקף, וכללי מיזוג" icon: gear --- -failproofai משתמש בקובצי הגדרות JSON כדי לשלוט באילו מדיניות פעילה, כיצד הן מתנהגות, ומאיפה מדיניות מותאמת אישית נטענת. ההגדרות מעוצבות להיות קלות לשיתוף עם הצוות שלך - בצע commit אליהם למאגר שלך וכל מפתח יקבל את אותה רשת הבטיחות עבור agent. +failproofai משתמש בקובצי תצורה JSON לשליטה באילו מדיניויות פעילות, כיצד הן מתנהגות, ומיכן מדיניויות מותאמות אישית נטענות. התצורה תוכננה להיות קלה לשיתוף עם הצוות שלך - בצע commit אותה לסכום הרפוזיטורי שלך וכל מפתח יקבל את אותה רשת בטיחות של agents. --- -## היקפי הגדרות +## היקפי תצורה -יש שלושה היקפי הגדרות, המוערכים לפי סדר עדיפויות: +יש שלוש היקפי תצורה, המוערכים בסדר עדיפות: -| היקף | נתיב קובץ | מטרה | +| היקף | נתיב הקובץ | תכלית | |-------|-----------|---------| -| **project** | `.failproofai/policies-config.json` | הגדרות לכל מאגר, בcomit לשליטה בגרסאות | -| **local** | `.failproofai/policies-config.local.json` | עקיפה אישית לכל מאגר, מתוך gitignore | -| **global** | `~/.failproofai/policies-config.json` | ברירות מחדל ברמת משתמש לכל הפרויקטים | +| **project** | `.failproofai/policies-config.json` | הגדרות לכל ריפוזיטורי, מוכנסות לשליטה בגרסאות | +| **local** | `.failproofai/policies-config.local.json` | עקיפות אישיות לכל ריפוזיטורי, בחזקת gitignore | +| **global** | `~/.failproofai/policies-config.json` | ברירות מחדל ברמת משתמש בכל הפרויקטים | -כאשר failproofai מקבל אירוע hook, הוא טוען ומוזג את כל שלושת הקובצים שקיימים בספריית העבודה הנוכחית. +כאשר failproofai מקבל אירוע ווק, הוא טוען וממזג את כל שלושת הקובצים הקיימים בתיקיה בעבודה הנוכחית. ### כללי מיזוג -**`enabledPolicies`** - האיחוד של כל שלושת ההיקפים. מדיניות שמופעלת בכל רמה פעילה. +**`enabledPolicies`** - איחוד של כל שלוש היקפים. מדיניות שהופעלה בכל רמה פעילה. ```text project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← deduplicated union +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← איחוד מוסר כפילויות ``` -**`policyParams`** - ההיקף הראשון שמגדיר פרמטרים לmדיניות מסוימת מנצח לחלוטין. אין מיזוג עמוק של ערכים בתוך הפרמטרים של המדיניות. +**`policyParams`** - היקף ראשון המגדיר פרמטרים למדיניות נתונה מנצח לחלוטין. אין מיזוג עמוק של ערכים בתוך הפרמטרים של מדיניות. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← project מנצח, global מתוספר +resolved: { allowPatterns: ["sudo apt-get update"] } ← project מנצח, global מתעלם ``` ```text @@ -46,16 +47,18 @@ project: (no block-sudo entry) local: (no block-sudo entry) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← יורד לכלל הglobal +resolved: { allowPatterns: ["sudo systemctl status"] } ← מתגלגל אל global ``` -**`customPoliciesPath`** - ההיקף הראשון שמגדיר אותו מנצח. +**`customPoliciesPaths` / `customPoliciesPath`** - היקף ראשון המגדיר כל צורה מנצח. + +**`disabledCustomPolicies`** - איחוד בכל היקפים. לוח הבקרה כותב מזהה מוסמך מקור כאן כאשר אתה מכבה מדיניות בודדת מקובץ מדיניויות מפורש או קונוונציה. מדיניויות שלא רשומות נשארות מופעלות כברירת מחדל; מזהים כוללים את קובץ המקור כדי שמדיניויות בעלות שם זהה בקבצים מרובים יוכלו להיות מבוקרות בעצמאות. -**`llm`** - ההיקף הראשון שמגדיר אותו מנצח. +**`llm`** - היקף ראשון המגדיר זה מנצח. --- -## פורמט קובץ הגדרות +## פורמט קובץ תצורה ```json { @@ -102,27 +105,27 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← יורד לכלל ה סוג: `string[]` -רשימת שמות המדיניות שיש להפעיל. השמות חייבים להתאים בדיוק לזהויות המדיניות המוצגות על ידי `failproofai policies`. ראה [Built-in Policies](/he/built-in-policies) לקבלת הרשימה המלאה. +רשימה של שמות מדיניויות להפעלה. שמות חייבים להתאים בדיוק למזהי המדיניות המוצגים על ידי `failproofai policies`. ראה [Built-in Policies](/he/built-in-policies) לרשימה המלאה. -מדיניות שלא ב`enabledPolicies` אינן פעילות, גם אם יש להן רשומות ב`policyParams`. +מדיניויות שלא ב-`enabledPolicies` אינן פעילות, גם אם יש להם ערכים ב-`policyParams`. ### `policyParams` סוג: `Record>` -עקיפות פרמטרים לכל מדיניות. המפתח החיצוני הוא שם המדיניות; המפתחות הפנימיים ספציפיים למדיניות. כל מדיניות מתעדת את הפרמטרים הזמינים שלה ב[Built-in Policies](/he/built-in-policies). +עקיפות פרמטרים לכל מדיניות. המפתח החיצוני הוא שם המדיניות; המפתחות הפנימיים הם ספציפיים למדיניות. כל מדיניות תיעד את הפרמטרים הזמינים שלה ב-[Built-in Policies](/he/built-in-policies). -אם למדיניות יש פרמטרים אך אתה לא מציין אותם, משמשים ברירות המחדל המובנות של המדיניות. משתמשים שאינם מגדירים את `policyParams` כלל מקבלים התנהגות זהה לגרסאות קודמות. +אם למדיניות יש פרמטרים אך לא תציין אותם, נעשה שימוש בברירות המחדל המובנות של המדיניות. משתמשים שלא מגדירים `policyParams` בכלל מקבלים התנהגות זהה לגרסאות קודמות. -מפתחות לא ידועים בתוך בלוק הפרמטרים של מדיניות מתעלמים בשקט בזמן הפעלת hook אך מסומנים כאזהרות כאשר אתה מריץ `failproofai policies`. +מפתחות לא ידועים בתוך בלוק הפרמטרים של מדיניות מתעלמים בשתיקה בעת התנקות, אך מסומנים כאזהרות כאשר אתה מריץ `failproofai policies`. -#### `hint` (חוצה פעולות) +#### `hint` (cross-cutting) -סוג: `string` (בחירה) +סוג: `string` (optional) -הודעה שצורפה לסיבה כאשר מדיניות מחזירה `deny` או `instruct`. השתמש בה כדי לתן לClaude הדרכה פעולה ישירה ללא שינוי המדיניות עצמה. +הודעה מצורפת לסיבה כאשר מדיניות מחזירה `deny` או `instruct`. השתמש בו כדי לתת ל-Claude הדרכה פעולה ללא שינוי המדיניות עצמה. -עובד עם כל סוג מדיניות — מובנה, מותאם אישית (`custom/`), מוסכמת פרויקט (`.failproofai-project/`), או מוסכמת משתמש (`.failproofai-user/`). +עובד עם כל סוג מדיניות — מובנה, מותאמת אישית (`custom/`), קונוונציית פרויקט (`.failproofai-project/`), או קונוונציית משתמש (`.failproofai-user/`). ```json { @@ -141,40 +144,40 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← יורד לכלל ה } ``` -כאשר `block-force-push` מסרב, Claude רואה: *"Force-pushing is blocked. Try creating a fresh branch instead."* +כאשר `block-force-push` מכחיש, Claude רואה: *"Force-pushing is blocked. Try creating a fresh branch instead."* -ערכים שאינם מחרוזות ומחרוזות ריקות מתעלמים בשקט. אם `hint` לא מוגדר, ההתנהגות לא משתנה (תאימות לאחור). +ערכים שאינם מחרוזות ומחרוזות ריקות מתעלמים בשתיקה. אם `hint` אינו מוגדר, ההתנהגות ללא שינוי (תאימות לאחור). ### `customPoliciesPath` -סוג: `string` (נתיב מוחלט) +סוג: `string` (absolute path) -נתיב לקובץ JavaScript המכיל מדיניות hook מותאמת אישית. זה מוגדר באופן אוטומטי על ידי `failproofai policies --install --custom ` (הנתיב מוחזר לערך מוחלט לפני שנשמר). +נתיב לקובץ JavaScript המכיל מדיניויות ווק מותאמות אישית. זה מוגדר באופן אוטומטי על ידי `failproofai policies --install --custom ` (הנתיב מחזיר לממיר לנתיב מוחלט לפני שמאוחסן). -הקובץ נטען מחדש בכל אירוע hook - אין caching. ראה [Custom Policies](/he/custom-policies) לפרטי כתיבה. +הקובץ נטען מחדש בכל אירוע ווק - אין קביעת מטמון. ראה [Custom Policies](/he/custom-policies) לפרטי יצירה. -### מדיניות מבוססת מוסכמה +### מדיניויות מבוססות קונוונציה -בנוסף לעקיפה ההפנייה `customPoliciesPath`, failproofai גילוי ויוטען באופן אוטומטי קובצי מדיניות מתיקיות `.failproofai/policies/`: +בנוסף ל-`customPoliciesPath` המפורש, failproofai גוררת ובוחרת אוטומטית קבצי מדיניויות מתיקיות `.failproofai/policies/`: -| רמה | ספרייה | היקף | +| רמה | תיקייה | היקף | |-------|-----------|-------| -| Project | `.failproofai/policies/` | משותף עם צוות דרך שליטה בגרסאות | -| User | `~/.failproofai/policies/` | אישי, חל על כל הפרויקטים | +| פרויקט | `.failproofai/policies/` | משותף עם צוות דרך בקרת גרסאות | +| משתמש | `~/.failproofai/policies/` | אישי, חל על כל הפרויקטים | -**התאמת קובץ:** רק קובצים התואמים ל`*policies.{js,mjs,ts}` נטענים (לדוגמה `security-policies.mjs`, `workflow-policies.js`). קובצים אחרים בספרייה מתעלמים. +**התאמת קובץ:** רק קובצים תואמים ל-`*policies.{js,mjs,ts}` נטענים (למשל `security-policies.mjs`, `workflow-policies.js`). קובצים אחרים בתיקייה מתעלמים. -**אין צורך בהגדרה:** מדיניות מוסכמה אינה דורשת רשומות ב`policies-config.json`. פשוט שים קובצים בספרייה והם אוסף בהתקדמות hook הבא. +**אין תצורה נדרשת:** מדיניויות קונוונציה לא דורשות ערכים ב-`policies-config.json`. פשוט זרוק קובצים לתיקייה והם נבחרים בעת ההתנקות הבאה. -**טעינה איחוד:** גם ספריות מוסכמה של פרויקט וגם משתמש סרוקות. כל קובצים תואמים משתי הרמות נטענים (שלא כמו `customPoliciesPath` אשר משתמש בראשון-היקף-מנצח). +**טעינת איחוד:** שתי תיקיות קונוונציה של פרויקט משתמש סורקות. כל קובצים תואמים משתי הרמות נטענים (בניגוד ל-`customPoliciesPath` שמשתמש בזכיות היקף ראשון). -ראה [Custom Policies](/he/custom-policies) לפרטים נוספים וודוגמאות. +ראה [Custom Policies](/he/custom-policies) לפרטים נוספים ודוגמאות. ### `llm` -סוג: `object` (בחירה) +סוג: `object` (optional) -הגדרות לקוח LLM למדיניות שמבצעות קריאות AI. לא נדרש לרוב ההגדרות. +תצורת לקוח LLM למדיניויות שביצעו שיחות AI. לא נדרש לרוב ההגדרות. ```json { @@ -187,21 +190,26 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← יורד לכלל ה --- -## ניהול הגדרות מ-CLI +## ניהול תצורה מה-CLI -הפקודות `policies --install` ו`policies --uninstall` כותבות לקובץ הגדרות hook של ה-CLI של ה-agent (נקודות הכניסה של hook), בעוד ש`policies-config.json` הוא הקובץ שאתה מנהל ישירות. שניהם נפרדים: +הפקודות `policies --install` ו-`policies --uninstall` כותבות לקובץ הגדרות ווק של ה-CLI של ה-agent שלך (נקודות הכניסה של ווק), בעוד `policies-config.json` הוא הקובץ שאתה מנהל ישירות. השניים נפרדים: -- **הגדרות Agent CLI** — אומרות ל-agent להתקשר ל`failproofai --hook ` בכל שימוש בכלי: +- **הגדרות CLI של Agent** — מספר ל-agent להקרא ל-`failproofai --hook ` בכל שימוש בכלים: - **Claude Code**: `~/.claude/settings.json` (משתמש), `/.claude/settings.json` (פרויקט), `/.claude/settings.local.json` (מקומי) - **OpenAI Codex**: `~/.codex/hooks.json` (משתמש), `/.codex/hooks.json` (פרויקט) — Codex אין לו היקף `local` - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (משתמש), `/.github/hooks/failproofai.json` (פרויקט) — Copilot אין לו היקף `local`. רשומות Hook משתמשות בשדות פקודה `bash`/`powershell` של Copilot עם מפתח OS עם `timeoutSec`; הקובץ נושא סימן `version: 1` ברמה העליונה. תמיכת Copilot CLI היא **beta** בעודנו מאמתים את סכימת רשומת `events.jsonl` (שהדוקים הציבוריים אינם מציינים) מול יותר ישיבות בעולם האמיתי. - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (משתמש), `/.cursor/hooks.json` (פרויקט) — Cursor אין לו היקף `local`. רשומות Hook משתמשות בצורה בעיצוב Claude `{type, command, timeout}` (לא פיצול `bash`/`powershell`), אך מאוחסנות תחת מפתחות אירוע camelCase (`preToolUse`, `beforeSubmitPrompt`, …) במערך שטוח לכל [סכימת hooks של Cursor](https://cursor.com/docs/hooks); הקובץ נושא סימן `version: 1` ברמה העליונה. המטפל מנרמל camelCase → PascalCase דרך `CURSOR_EVENT_MAP` כך שמדיניות מובנות קיימות נשרפות ללא שינוי. תמיכת Cursor Agent היא **beta** בעודנו מאמתים את קובץ הטרנסקריפט של Cursor (לא מצוין בדוקים הציבוריים) מול יותר התקנות בעולם האמיתי. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (משתמש), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (פרויקט) — OpenCode אין לו היקף `local`. בשונה מחמש ה-CLI האחרים, OpenCode **אין לו מערכת hook פקודה חיצונית**: הוא טוען בתוך התהליך תוספי JS/TS שנרשמו במפורש דרך מערך `plugin: []` ב`opencode.json` (גילוי אוטומטי מ`.opencode/plugins/` **אינו** כיצד תוספים נטענים ב-opencode v1.14.33). ההתקנה מושכת שים של תוספון שנוצר בזריעה שקוראות ב-subprocess את הבינארי failproofai ומתרגמת את התגובה JSON בעיצוב Claude של הבינארי חזרה לסמנטיקה של תוספון: `throw new Error()` עבור deny של אירוע כלי (מבטל את קריאת הכלי), `client.session.prompt(...)` עבור instruct וגם עבור deny של `Stop` / `SubagentStop` (משדרת את סיבת הreject כהודעת המשתמש הבאה — הערוץ היחיד כלומל-retry מכיוון ש`session.idle` הוא התראה בלבד ו-throwing ממנו הוא no-op), ו-no-op עבור allow. השם מנרמל גם שמות כלים (אותיות קטנות → PascalCase דרך `OPENCODE_TOOL_MAP`) וגם מפתחות טיעון קלט כלי (camelCase → snake_case דרך `OPENCODE_TOOL_INPUT_MAP` עבור `Read` / `Write` / `Edit`, לדוגמה `filePath` → `file_path`, `oldString` → `old_string`) לפני שליחה קדימה לבינארי, כך שבדיקות נתיב מובנות כמו `block-read-outside-cwd`, `block-env-files`, ו`block-secrets-write` נשרפות ללא שינוי בקריאות כלים OpenCode. ישיבות חיות בבסיס נתונים SQLite של opencode ב`~/.local/share/opencode/opencode.db`; צופה הישיבה של הדשבורד קורא להם דרך `opencode db --format json` ו`opencode export `. תמיכת OpenCode היא **beta** בעודנו מאמתים התנהגות על פני גרסאות ומול יותר ישיבות בעולם האמיתי. ראה את [דוקים של תוספי OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (משתמש), `/.pi/settings.json` (פרויקט) — Pi אין לו היקף `local`. Pi טוען חבילות הרחבה TypeScript בעת ההתחלה; קובץ ההגדרות הוא מערך מחרוזות שטוח `{"packages": ["./relative/path", …]}`. failproofai כותב רשומת מערך פקיות אחת המצביעה על תיקיית `pi-extension/` המכוסה שלה. ההרחבה מחתום פנימית על אירועי `tool_call` / `user_bash` / `input` / `session_start` של Pi ופורקת `failproofai --hook --cli pi`; המטפל מנרמל underscore_lower_snake_case → PascalCase דרך `PI_EVENT_MAP` כך שמדיניות מובנות קיימות נשרפות ללא שינוי. טיעון קלט כלי מנורמל גם דרך `PI_TOOL_INPUT_MAP` (Read / Write / Edit של Pi משדרות `path` ולא `file_path`; מיפוי המפתח ברמה העליונה מאפשר ל`block-env-files` ו`block-secrets-write` נשרפות — `block-read-outside-cwd` כבר היה פנייה חוזרת של `path`). תמיכת Pi היא **beta** בזמן שה-API הרחבה של Pi וסכימת יומן הישיבה מתייצבות. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**היקף משתמש בלבד** — Hermes אין לו תצורת פרויקט/מקומית). Hermes הוא **שער** Slack/Telegram, כך שהתקנה אחת מיירטת קריאות כלים מכל פלטפורמה (Slack/Telegram/cli/cron) **וגם** תוך-אג'נטים. רשומות Hook הן זוג `{command, timeout}` (timeout בשניות) תחת מפת `hooks:` שבאופן events snake_case של Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); המטפל מנרמל אירועים דרך `HERMES_EVENT_MAP` וגם שמות כלים דרך `HERMES_TOOL_MAP` כך שמדיניות מובנות נשרפות ללא שינוי. התצורה נערכת דרך תעודת YAML דורכת-שומרת-הערות `Document` כך שהגדרות אחרות של המנהל שורדות, והתקנה מוגדרת `hooks_auto_accept: true` כך השער חסר-TTY מריץ את ה-hooks ללא בקשת הסכמה. המעריך משדרת חוזה `{"decision":"block","reason"}` stdout של Hermes (Hermes מתעלם מקודי יציאה). **מגבלות:** Hermes אין להשקע stop `Stop` של turn-end, כך שה`require-*-before-stop` מובנה לעולם לא נשרפים עבורו (בלא הגבלה, לא שבור); `instruct` מדרדר ל-allow-עם-logged-note (אין ערוץ הקשר נוסף); ו-redaction-secret של פלט (`sanitize-*`) לא יכול לשכתב פלט כלים דרך חוזה shell-hook. Hermes הוא **גם** מקור ביקורת **offline** — הדשבורד קורא ישיבות שער שלו ישירות מ`~/.hermes/state.db`. -- **`policies-config.json`** — אומר ל-failproofai איזו מדיניות להעריך ועם אילו פרמטרים (משותף על פני כל ה-CLI של ה-agent) - -עבור `--cli claude|codex|copilot|cursor|opencode|pi|hermes` למטרה סוכן ספציפי (space-separated או חוזר לכל תת-קבוצה): + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (משתמש), `/.github/hooks/failproofai.json` (פרויקט) — ל-Copilot אין היקף `local`. ערכי ווק משתמשים בשדות הפקודה `bash`/`powershell` המסומנים ב-OS של Copilot עם `timeoutSec`; הקובץ נושא סמן `version: 1` ברמה העליונה. תמיכת Copilot CLI היא **beta** בזמן שאנחנו מאמתים את סכמת הרשומה `events.jsonl` (שהמסמכים הציבוריים לא מציינים) מול יותר מפגשים בעולם האמיתי. **VS Code Copilot Chat agent mode (Preview)** קורא קונפיגי ווק מ-`.github/hooks/*.json`, `~/.copilot/hooks/*.json`, ו-`~/.claude/settings.json` (מנוהל על ידי ההגדרה `chat.hookFilesLocations`) באמצעות אותו חוזה בעל צורת Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — הנתיבים המדויקים שכבר כותבים ההשתלמה `copilot` זו וההשתלמה `claude` (`~/.claude/settings.json`), אז `failproofai policies --install --cli copilot` (או `--cli claude`) **כבר אוכף במצב ה-agent של VS Code** ללא שום השתלמות `vscode` נפרדת (מאומת live מיומני גילוי של VS Code). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (משתמש), `/.cursor/hooks.json` (פרויקט) — ל-Cursor אין היקף `local`. ערכי ווק משתמשים בצורת `{type, command, timeout}` בעלת צורת Claude (ללא פיצול `bash`/`powershell`), אך מאוחסן תחת מפתחות אירוע camelCase (`preToolUse`, `beforeSubmitPrompt`, …) במערך שטוח לפי סכמת [hooks](https://cursor.com/docs/hooks) של Cursor; הקובץ נושא סמן `version: 1` ברמה העליונה. הטוען מקנן camelCase → PascalCase דרך `CURSOR_EVENT_MAP` כדי שמדיניויות מובנות קיימות יורו ללא שינוי. תמיכת Cursor Agent היא **beta** בזמן שאנחנו מאמתים את התמליל של Cursor על דיסק (לא מצויין בדוקים ציבוריים) מול יותר התקנות בעולם האמיתי. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (משתמש), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (פרויקט) — ל-OpenCode אין היקף `local`. בניגוד לחמשת ה-CLIs האחרים, ל-OpenCode אין **מערכת ווק פקודה חיצונית**: היא טוענת הלאה-תהליך JS/TS תוסף הרשום בבירור דרך המערך `plugin: []` ב-`opencode.json` (גילוי אוטומטי מ-`.opencode/plugins/` הוא **לא** איך תוספים טוענים על opencode v1.14.33). ההתקנה מורידה shimmer של תוסף קטן שנוצר שקורא תת-תהליך לבינריית failproofai ומתרגם את תגובת JSON בעל צורת Claude של הבינרי חזרה לסמנטיקה של תוסף: `throw new Error()` ל-tool-event deny (ביטול קריאת הכלי), `client.session.prompt(...)` עבור הנחיה **ו** `Stop` / `SubagentStop` deny (שומר את סיבת הכחיש כהודעת המשתמש הבאה — ערוץ הכפיית הניסיון היחיד מכיוון ש-`session.idle` הוא notification-only וזריקה ממנו היא no-op), ו-no-op לאפשור. ה-shimmer מקנן שמות כלים (אותיות קטנות → PascalCase דרך `OPENCODE_TOOL_MAP`) ומפתחות טיעון של כלי קלט (camelCase → snake_case דרך `OPENCODE_TOOL_INPUT_MAP` עבור `Read` / `Write` / `Edit`, למשל `filePath` → `file_path`, `oldString` → `old_string`) לפני העברה לבינריית כדי שכלים בודקי נתיבים מובנים כמו `block-read-outside-cwd`, `block-env-files`, ו-`block-secrets-write` יורו ללא שינוי בקריאות כלי OpenCode. פגישות חיות בבסיס הנתונים של SQLite של opencode ב-`~/.local/share/opencode/opencode.db`; מלבן הפעילות של לוח הבקרה קורא אותם דרך `opencode db --format json` ו-`opencode export `. תמיכת OpenCode היא **beta** בזמן שאנחנו מאמתים התנהגות על פני גרסאות ומול יותר פגישות בעולם האמיתי. ראה את [מסמכי תוספי OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (משתמש), `/.pi/settings.json` (פרויקט) — ל-Pi אין היקף `local`. Pi טוען חבילות הרחבה TypeScript בזמן ההתחלה; קובץ ההגדרות הוא מערך מחרוזות שטוח `{"packages": ["./relative/path", …]}`. failproofai כותב ערך מערך חבילה יחיד המצביע על ספריית `pi-extension/` הכרוכה שלו. ההרחבה במקומי מנויה לאירועי `tool_call` / `user_bash` / `input` / `session_start` של Pi ופורקת החוצה `failproofai --hook --cli pi`; הטוען מקנן underscore_lower_snake_case → PascalCase דרך `PI_EVENT_MAP` כדי שמדיניויות מובנות קיימות יורו ללא שינוי. טיעוני כלי קלט מקנן גם דרך `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit משלח `path` ולא `file_path`; מיפוי המפתח ברמה העליונה מאפשר ל-`block-env-files` ו-`block-secrets-write` לירות — `block-read-outside-cwd` כבר היה נפילה `path`). תמיכת Pi היא **beta** בזמן שה-API של הרחבת Pi ופריסת יומן הפגישה מתייצבות. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**רמת משתמש בלבד** — ל-Hermes אין תצורת project/local). Hermes הוא **שער** Slack/Telegram, כך שהתקנה אחת יוצרת קריאות כלים מכל פלטפורמה (Slack/Telegram/cli/cron) **ו** subagents פנימיים. ערכי ווק הם זוג `{command, timeout}` (timeout ב**שניות**) תחת מפה `hooks:` מפתוחה לפי אירועי snake_case של Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); הטוען מקנן אירועים דרך `HERMES_EVENT_MAP` ושמות כלים דרך `HERMES_TOOL_MAP` כדי שמדיניויות מובנות יורו ללא שינוי. התצורה נערכת דרך סיור YAML `Document` שמשמר הערות כדי שההגדרות האחרות של המפעיל שורדות, וההתקנה קובעת `hooks_auto_accept: true` כדי שהשער headless (ללא TTY) מריץ את הווקים ללא הודעת הסכמה. המעריך פולט חוזה stdout של Hermes `{"decision":"block","reason"}` (Hermes מתעלם מקודי יציאה). **מגבלות:** ל-Hermes אין אירוע `Stop` בסיום תור, אז בנויים ה-`require-*-before-stop` לעולמות לא יורים עבורו (לא ישים, לא שבור); `instruct` יורד לאפשור-עם-הערה-רשום (ללא ערוץ הקשר נוסף); וקביעה סודית פלט (`sanitize-*`) לא יכול לכתוב את פלט הכלי על פני חוזה ווק הקליפה. Hermes הוא **גם** מקור ביקורת לא מקוון — לוח הבקרה קורא פגישות שער שלו ישירות מ-`~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**רמת משתמש בלבד** — ל-OpenClaw אין תצורת project/local). כמו Hermes, OpenClaw הוא **שער** בעל מארח עצמי בעל ערוץ מרובה, כך שהתקנה אחת יוצרת קריאות כלים מכל ערוץ ו-subagents פנימיים שלו. הנפיקה פועלת דרך **ווקי תוסף בתהליך** של OpenClaw (הווקים הקובץ-מבוססים הפנימיים שלו הם תצפית בלבד ולא יכולים להחסום), אז — כמו OpenCode/Pi — failproofai משלח ספרייה סטטית `openclaw-plugin/` שאסינכרונית-spawnים את בינריית failproofai ומתרגמת את הפסק דין. ההתקנה רושמת את ספרייה התוסף שמורדת ב-`openclaw.json` של `plugins.load.paths[]` והופעלה תחת `plugins.entries.failproofai` (עם `hooks.allowConversationAccess: true`, נדרש לווקי שיחה גולמיים). המעריך פולט פסק דין שטוח `{permission, reason}` וה-shimmer ממפה אותו לצורה הילידה של כל ווק: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), ו-`before_agent_finalize → {action:"revise", reason}` (**Stop** — שער תור-סוף אמיתי, אז בנויים ה-`require-*-before-stop` **אוכפים** על OpenClaw, בניגוד ל-Hermes). אירועים ושמות כלים קנון צד בינרי דרך `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) כדי שמדיניויות מובנות יורו ללא שינוי; ה-shimmer נכשל פתוח בכל spawn/parse/timeout שגיאה. OpenClaw הוא **גם** מקור ביקורת לא מקוון — לוח הבקרה קורא את פגישות ה-JSONL שלו ב-`~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (משתמש), `/.factory/hooks.json` (פרויקט) — ל-Factory אין היקף `local`. droid משלח מערכת ווק פקודה חיצונית בעלת צורת Claude, אך עם שתי זוטות מאומתות live מול droid v0.171.0: (1) שמות אירוע חיים ברמה **עליונה** של `hooks.json` — אין **קפיצה `"hooks"`** (droid דוחה אחת); אירועי כלים (`PreToolUse`/`PostToolUse`) נושאים `"matcher": "*"`, אירועים שאינם כלים משמיטים אותה. (2) Deny מונע על ידי ווק **קוד יציאה 2 + stderr**, לא JSON qua — ענף ה-`factory` של המעריך מחזיר יציאה 2 עבור אירועי כלי/הנחיה ו-`{decision:"block", reason}` רק על אירוע Stop בסיום התור (ערוץ כפיית הניסיון היחיד של droid). אירועים כבר בעלי צורת PascalCase (ללא מפה אירוע) והעומס הוא Claude snake_case; רק שמות כלים מקנון דרך `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory הוא **גם** מקור ביקורת לא מקוון — לוח הבקרה קורא את פגישות ה-JSONL שלו על-דיסק ב-`~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (משתמש), `/.devin/config.json` (פרויקט) — ל-Devin אין היקף `local`. Devin הוא **עותק Claude טהור** מאומת live מול devin v3000.1.27: הוא משתמש בסכמת Claude `"hooks"`-wrapper סטנדרטית (הכתיבות משמרות-מיזוג כדי שמפתחות אחרים של קובץ התצורה — `org_id`, `theme_mode`, … — שורדות), שמות אירוע כבר בעלי צורת PascalCase (ללא מפת אירוע, ללא ענף טוען), ועומס stdin בעל צורת Claude snake_case (ללא עיבוד). ענף ה-`devin` של המעריך מכחיש עם `{"decision":"block","reason"}` JSON ב-stdout בקוד יציאה 0 עבור **כל** אירוע (מאומת — הבלוק עקף `--permission-mode dangerous`); על אירוע Stop בסיום התור הסיבה נושאת ניסוח הפעולה המחייבת הכפיית הניסיון כדי שבנויים ה-`require-*-before-stop` אוכפים. רק שמות כלים מקנון דרך `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` כבר קנוני). Devin הוא **גם** מקור ביקורת לא מקוון — לוח הבקרה קורא את פגישות SQLite שלו ב-`~/.local/share/devin/cli/sessions.db` (כל שורת `sessions` נושאת `working_directory` אמיתית, כך שפגישות קבוצה לפי cwd פרויקט כמו Claude). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (משתמש), `/.agents/hooks.json` (פרויקט) — ל-Antigravity אין היקף `local`. בניגוד ל-Factory/Devin, ל-Antigravity יש חוזה **שלו** (לא עותק Claude), מאומת live מול agy v1.1.2. `hooks.json` משתמש בסכמה **ווק-בעל-שם**: המפתח ברמה העליונה הוא שם ווק (*"failproofai"*) שערכו הוא מפה אירוע→핸들רים — אירועי כלים (`PreToolUse`/`PostToolUse`) עוטפים핸들רים ב-`{matcher:"*", hooks:[…]}`, בעוד `PreInvocation`/`Stop` הם מערכי **שטוח**핸들רים (ווקים בעלי שם אחרים משומרים). עומס stdin הוא **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai משנה אותו ל-snake_case לפני ריצת מדיניויות, וממפה טיעוני `run_command` בעלי צורת PascalCase (`CommandLine`/`Cwd`) דרך `ANTIGRAVITY_TOOL_INPUT_MAP`. ענף ה-`antigravity` של המעריך משתמש בצורות התגובה **שלו** של Antigravity: `{decision:"deny", reason}` חוסם כלי/הנחיה (יציאה 0), `{decision:"continue", reason}` על אירוע Stop בסיום התור נכנס לולאה (אז בנויים ה-`require-*-before-stop` אוכפים), ו-`{injectSteps:[{ephemeralMessage}]}` מזריק הנחיה ב-`PreInvocation` (→ `UserPromptSubmit`). שמות כלים קנון דרך `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity הוא **גם** מקור ביקורת לא מקוון — לוח הבקרה קורא את תמלילי plain-JSONL שלו ב-`~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (אינדקס שיחה ב-`conversation_summaries.db`). + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (משתמש), `/.agents/plugins/failproofai/hooks/hooks.json` (פרויקט) — ל-Goose אין היקף `local`. הנפיקה משתמשת במערכת **ווקי** של Goose, ספציפיקציה **Open Plugins** חוצת-agent: המתקין פשוט זורק את ספרייה התוסף `failproofai` והוא אוטו-גוררת בזמן ההתחלה (הרשמה עצמית אותו ל-`~/.config/goose/config.yaml`). `hooks.json` משתמש בסכמה **Open Plugins** **עם** קפיצת `"hooks"` ברמה העליונה, והמתאם מושמט בכל אירוע — regex שטוח `"*"` הוא regexאינו תקף שלא תואם כלום (מאומת live מול goose v1.43.0). שמות אירוע כבר בעלי צורת PascalCase (ללא מפת אירוע); עומס stdin משתמש ב-`event`/`working_dir`, שהטוען משנה ל-`hook_event_name`/`cwd`. ענף ה-`goose` של המעריך מכחיש עם `{"decision":"block","reason"}` JSON ב-stdout בקוד יציאה 0, מכובד באירוע **`PreToolUse`** בלבד (משלח בגרסאות ≥ v1.37.0 של goose) — שיורה עבור כלי הקליפה **ובתוך subagents מוקדים**, כך שהוא נקודה הכחיש יחידה מספקת; כל שגיאת ווק אחרת נכשלת **פתוח**. ל-Goose אין **אירוע `Stop`**, אז בנויים ה-`require-*-before-stop` לא חלים (כמו Hermes). שמות כלים קנון דרך `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) ומפתחות נתיבים דרך `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose הוא **גם** מקור ביקורת לא מקוון — לוח הבקרה קורא את פגישות SQLite שלו ב-`~/.local/share/goose/sessions/sessions.db` (כל שורת `sessions` נושאת `working_dir` אמיתית, כך שפגישות קבוצה לפי cwd פרויקט כמו Devin; הפעלות `--no-session` scratch מסוננות). +- **`policies-config.json`** — מספר ל-failproofai אילו מדיניויות להערכה וברבים פרמטרים (משותף בכל CLIs של agent) + +עבור `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` היעד בת-agent ספציפית (מופרדת רווח או חזרה לכל תת-קבוצה): ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +218,28 @@ failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli hermes --scope user -failproofai policies --install --cli claude codex copilot cursor opencode pi +failproofai policies --install --cli openclaw --scope user +failproofai policies --install --cli factory --scope project +failproofai policies --install --cli devin --scope project +failproofai policies --install --cli antigravity --scope project +failproofai policies --install --cli goose --scope project +failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -כאשר `--cli` מושמט, `failproofai` מגלה אילו CLI של agent מותקנות (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`): +כאשר `--cli` מושמט, `failproofai` גוררת אילו agent CLIs מותקנים (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): -- **CLI אחד זוהה** — בחירה אוטומטית של ה-CLI הזה ללא הנחיות. -- **מספר CLI זוהו** בטרמינל אינטראקטיבי — מציג הנחיות בחירה חד-בחירה בחצי-מקלדת מקובצות לחלק `Detected (N)` (עם שורה מצומצמת `Install for all N detected` + כל CLI זוהה בנפרד) וחלק `Not installed (M) · install hooks ahead of time` הרשום כל CLI לא זוהה שנתמך כאפשרות התקנה קדימה (↑↓ להזיז, Enter בחר, ^C יצא). זרימת ההסרה מציגה רק את החלק Detected. -- **מספר CLI זוהו** בריצה לא אינטראקטיבית (CI, ללא TTY) — מתקנת את כל CLI זוהה ללא הנחיות. -- **אף אחד לא זוהה** — יורדת חזרה ל`claude`, עם אזהרה שלא מצא בינארי agent ב-PATH; פקודת ה-hook עדיין נכתבה כך היא מופעלת ברגע שתתקין אחד. +- **CLI אחד גרור** — auto-בוחר את CLI זה ללא הנחיות. +- **CLIs מרובים גרור** בטרמינל אינטראקטיבי — מציג הנחיית בחירה יחידה חץ-מקלדת מקובצת לתוך סעיף `Detected (N)` (עם שורה מוסכמת `Install for all N detected` + כל CLI גרור בנפרד) וסעיף `Not installed (M) · install hooks ahead of time` הרשימות כל CLI שאינו גרור שנתמך כאפשרות התקנה קדימה (↑↓ לתזוזה, הקלד לבחירה, ^C ללא). זרימת ההסרה מציגה רק את סעיף הגרור. +- **CLIs מרובים גרור** בריצה לא אינטראקטיבית (CI, ללא TTY) — מתקנת ל-CLIs גרור בנפרד ללא הנחיות. +- **אין גרור** — חוזר ל-`claude`, עם אזהרה שלא נמצא בינריית agent בPATH; פקודת הווק עדיין כתובה כדי שהיא תופעל כשמתקנת אחד. -אתה יכול לערוך `policies-config.json` ישירות בכל עת; השינויים נכנסים לתוקף מיד באירוע hook הבא ללא צורך בהפעלה מחדש. +אתה יכול לערוך `policies-config.json` ישירות בכל עת; שינויים יופעלו מייד בעת ההתנקות הבאה ללא צורך בהפעלה מחדש. --- -## דוגמה: תצורה ברמת פרויקט עם ברירות ברירת מחדל לצוות +## דוגמה: תצורת ברמת-פרויקט עם ברירות מחדל של צוות -Commit `.failproofai/policies-config.json` למאגר שלך: +שרימט `.failproofai/policies-config.json` לריפוזיטורי שלך: ```json { @@ -245,4 +258,4 @@ Commit `.failproofai/policies-config.json` למאגר שלך: } ``` -כל מפתח יכול ליצור `.failproofai/policies-config.local.json` (מתוך gitignore) לעקיפות אישיות ללא הפרת עמיתים. \ No newline at end of file +כל מפתח יכול אז ליצור `.failproofai/policies-config.local.json` (gitignored) לעקיפות אישיות ללא השפעה על חברי צוות. \ No newline at end of file diff --git a/docs/he/custom-policies.mdx b/docs/he/custom-policies.mdx index a3510f97..1a7235be 100644 --- a/docs/he/custom-policies.mdx +++ b/docs/he/custom-policies.mdx @@ -1,10 +1,11 @@ --- +--- title: מדיניות מותאמות אישית -description: "כתוב את הכללים שלך בJavaScript - אכוף קונוונציות, עצור סטייה, גלה כשלים, השתלב עם מערכות חיצוניות" +description: "כתוב חוקים משלך ב-JavaScript - אכוף קונוונציות, מנע סטייה, גלה כשלים, שלב עם מערכות חיצוניות" icon: code --- -מדיניות מותאמות אישית מאפשרת לך לכתוב כללים לכל התנהגות סוכן: אכוף קונוונציות של פרויקט, עצור סטייה, חסום פעולות הרסניות, גלה סוכנים תקועים, או השתלב עם Slack, זרימות אישור, ועוד. הם משתמשים באותה מערכת אירועי hook וה-`allow`, `deny`, `instruct` כמו מדיניות מובנית. +מדיניות מותאמת אישית מאפשרת לך לכתוב חוקים לכל התנהגות של סוכן: אכוף קונוונציות פרויקט, מנע סטייה, חסום פעולות הרסניות, גלה סוכנים תקועים, או שלב עם Slack, זרימות אישור ועוד. הם משתמשים באותה מערכת אירועי hook ובהחלטות `allow`, `deny`, `instruct` כמו מדיניות מובנית. --- @@ -41,56 +42,61 @@ failproofai policies --install --custom ./my-policies.js ### אפשרות 1: מבוססת קונוונציה (מומלץ) -זרוק קבצים `*policies.{js,mjs,ts}` לתוך `.failproofai/policies/` והם נטענים באופן אוטומטי — אין צורך בדגלים או שינויי תצורה. זה עובד כמו git hooks: זרוק קובץ, זה פשוט עובד. +שחרר קבצי `*policies.{js,mjs,ts}` אל `.failproofai/policies/` והם יטענו באופן אוטומטי — אין צורך בדגלים או שינויי הגדרות. זה עובד כמו git hooks: שחרר קובץ, וזה פשוט עובד. ``` -# Project level — committed to git, shared with the team +# Project level — מחויב ל-git, משותף לצוות .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# User level — personal, applies to all projects +# User level — אישי, חל על כל הפרויקטים ~/.failproofai/policies/my-policies.mjs ``` -**איך זה עובד:** -- שני הספריות של פרויקט ומשתמש נסרקים (union — לא first-scope-wins) -- קבצים נטענים בסדר אלפבתי בתוך כל ספריה. הוסף קידומת עם `01-`, `02-` כדי לשלוט בסדר +**כיצד זה עובד:** +- שתי תיקיות הפרויקט והמשתמש נסרקות (union — לא first-scope-wins) +- קבצים נטענים באופן אלפביתי בתוך כל תיקייה. הקדם עם `01-`, `02-` כדי לשלוט בסדר - רק קבצים התואמים `*policies.{js,mjs,ts}` נטענים; קבצים אחרים מתעלמים -- כל קובץ נטען באופן עצמאי (fail-open לכל קובץ) +- כל קובץ נטען בעצמאות (fail-open לכל קובץ) - עובד לצד `--custom` מפורש ומדיניות מובנית -מדיניות קונוונציה היא הדרך הקלה ביותר לבנות תקן איכות לארגון שלך. Commit `.failproofai/policies/` ל-git וכל חברי הצוות יקבלו את אותם הכללים באופן אוטומטי — אין צורך בהגדרה לכל מפתח. כשהצוות שלך מגלה מצבי כשלים חדשים, הוסף מדיניות ודחוף. עם הזמן אלה הופכים לתקן איכות חי שמשתפר עם כל תרומה. +מדיניות קונוונציה היא הדרך הקלה ביותר לבנות תקן איכות לארגון שלך. עבור `.failproofai/policies/` ל-git וכל חברה בצוות תקבל את אותם חוקים באופן אוטומטי — אין צורך בהגדרה לכל מפתח. כאשר הצוות שלך מגלה מצבי כשל חדשים, הוסף מדיניות והדחף. עם הזמן אלה הופכים לתקן איכות חי שמשתפר עם כל תרומה. ### אפשרות 2: נתיב קובץ מפורש ```bash -# Install with a custom policies file +# התקנה עם קובץ מדיניות מותאם אישית failproofai policies --install --custom ./my-policies.js -# Replace the policies file path +# החלף את נתיבי המדיניות המותאמת אישית failproofai policies --install --custom ./new-policies.js -# Remove the custom policies path from config +# הגדר מספר קבצים מפורשים (טעונים בסדר דגל) +failproofai policies --install --custom ./security.js --custom ./workflow.js + +# הסר את כל נתיבי המדיניות המותאמת אישית המפורשים מהתצורה failproofai policies --uninstall --custom ``` -הנתיב המוחלט המוחזר מאוחסן ב-`policies-config.json` כ-`customPoliciesPath`. הקובץ נטען בטרי בכל אירוע hook - אין caching בין אירועים. +נתיבים מוחלטים שנפתרו מאוחסנים ב-`policies-config.json` כ-`customPoliciesPaths`. חזור על `--custom` כדי להגדיר מספר קבצים. התצורות הקיימות בשימוש בשדה המורשה `customPoliciesPath` ממשיכות לעבוד. קבצים נטענים טריים בכל אירוע hook — אין cache בין אירועים. + +כל מדיניות רשומה מופיעה עם toggle משלה בדשבורד. החלפת מדיניות כבויה רושמת את ה-ID המוקדם לקובץ שלה ב-`disabledCustomPolicies`; הקובץ והמדיניות האחרות שלו ממשיכים לטעון, בעוד המדיניות המוסכמת מוחרגת לפני התאמת אירוע. שמות מדיניות שכפולים על פני קבצים יש toggles עצמאיים. -### שימוש בשניהם יחד +### שימוש בשניהם ביחד -מדיניות קונוונציה וקובץ `--custom` מפורש יכולים להתקיים. סדר טעינה: +מדיניות קונוונציה וקבצי `--custom` מפורשים יכולים להיות קיימים. סדר טעינה: -1. קובץ `customPoliciesPath` מפורש (אם מוגדר) -2. קבצי קונוונציה של פרויקט (`{cwd}/.failproofai/policies/`, בסדר אלפבתי) -3. קבצי קונוונציה של משתמש (`~/.failproofai/policies/`, בסדר אלפבתי) +1. קבצי `customPoliciesPaths` מפורשים (בסדר מוגדר) +2. קבצי קונוונציה של פרויקט (`{cwd}/.failproofai/policies/`, אלפביתי) +3. קבצי קונוונציה של משתמש (`~/.failproofai/policies/`, אלפביתי) --- ## API -### Import +### ייבוא ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -98,7 +104,7 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -רושם מדיניות. קרא זאת כמו שרוצה פעמים רבות עבור מדיניות מרובה באותו קובץ. +רושם מדיניות. קרא זה כמה פעמים לפי הצורך עבור מדיניויות מרובות באותו קובץ. ```ts customPolicies.add({ @@ -109,34 +115,34 @@ customPolicies.add({ }); ``` -### עוזרי החלטות +### עוזרי החלטה -| פונקציה | אפקט | השתמש כאשר | +| פונקציה | השפעה | השתמש כאשר | |----------|--------|----------| | `allow()` | אפשר את הפעולה בשקט | הפעולה בטוחה, אין צורך בהודעה | | `deny(message)` | חסום את הפעולה | הסוכן לא צריך לבצע פעולה זו | -| `instruct(message)` | הוסף הקשר ללא חסימה | תן לסוכן הקשר נוסף כדי להישאר על המסלול | +| `instruct(message)` | הוסף הקשר ללא חסימה | תן לסוכן הקשר נוסף כדי להישאר במסלול | -`deny(message)` - ההודעה מופיעה ל-Claude עם קידומת `"Blocked by failproofai:"`. ה-`deny` יחיד מקצר הערכה נוספת. +`deny(message)` - ההודעה מופיעה ל-Claude עם קידומת `"Blocked by failproofai:"`. ערך `deny` יחיד קוצר את כל ההערכה הנוספת. -`instruct(message)` - ההודעה מצורפת להקשר של Claude לקריאת הכלי הנוכחי. כל הודעות `instruct` מצטברות ומועברות יחד. +`instruct(message)` - ההודעה מצורפת להקשר של Claude לקריאת הכלי הנוכחית. כל הודעות `instruct` מצטברות והם מועברות יחד. -אתה יכול לצרף הנחיה נוספת לכל הודעת `deny` או `instruct` על ידי הוספת שדה `hint` ב-`policyParams` — אין צורך בשינוי קוד. זה עובד עבור מדיניות מותאמת אישית (`custom/`), קונוונציה של פרויקט (`.failproofai-project/`), וקונוונציה של משתמש (`.failproofai-user/`) גם כן. ראה [Configuration → hint](/he/configuration#hint-cross-cutting) לפרטים. +אתה יכול להוסיף הנחיות נוסף לכל הודעת `deny` או `instruct` על ידי הוספת שדה `hint` ב-`policyParams` — אין צורך בשינוי קוד. זה עובד עבור מדיניות מותאמת אישית (`custom/`), קונוונציה של פרויקט (`.failproofai-project/`), וקונוונציה של משתמש (`.failproofai-user/`) גם כן. ראה [Configuration → hint](/he/configuration#hint-cross-cutting) לפרטים. -### הודעות allow אינפורמטיביות +### הודעות allow מידע -`allow(message)` מאפשר את הפעולה **וגם** שולח הודעה אינפורמטיבית חזרה ל-Claude. ההודעה מועברת כ-`additionalContext` בתגובת stdout של מטפל ה-hook — אותו מנגנון המשמש ל-`instruct`, אך שונה מבחינה סמנטית: זה עדכון סטטוס, לא אזהרה. +`allow(message)` מאפשר את הפעולה **וגם** שולח הודעת מידע חזרה ל-Claude. ההודעה משולחת כ-`additionalContext` בתגובת stdout של מטפל ה-hook — אותו מנגנון המשמש את `instruct`, אך שונה מבחינה סמנטית: זהו עדכון סטטוס, לא אזהרה. -| פונקציה | אפקט | השתמש כאשר | +| פונקציה | השפעה | השתמש כאשר | |----------|--------|----------| -| `allow(message)` | אפשר ושלח הקשר ל-Claude | אשר בדיקה עברה, או הסבר למה בדיקה דולגת | +| `allow(message)` | אפשר והשלח הקשר ל-Claude | אשר בדיקה שעברה, או הסבר למה בדיקה דלגה | מקרי שימוש: -- **אישורי סטטוס:** `allow("All CI checks passed.")` — אומר ל-Claude שהכל ירוק -- **הסברי fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — אומר ל-Claude למה בדיקה דלגה כדי שיהיה לו הקשר מלא -- **הודעות מרובות מצטברות:** אם כמה מדיניות כל אחת מחזירה `allow(message)`, כל ההודעות מחוברות עם עלינוליים ומועברות יחד +- **אישור סטטוס:** `allow("All CI checks passed.")` — אומר ל-Claude שהכל ירוק +- **הסברי fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — אומר ל-Claude למה בדיקה דלגה כדי שיהיה להם קשר מלא +- **הודעות מרובות מצטברות:** אם מספר מדיניות חוזר כל אחד `allow(message)`, כל ההודעות מצורפות עם שורות חדשות והן מועברות יחד ```js customPolicies.add({ @@ -160,27 +166,27 @@ customPolicies.add({ | שדה | סוג | תיאור | |-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | הכלי שנקרא (לדוגמה `"Bash"`, `"Write"`, `"Read"`) | +| `toolName` | `string \| undefined` | הכלי הנקרא (למשל `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | פרמטרי הקלט של הכלי | -| `payload` | `Record` | דיפלומת אירוע גולמית מלאה מ-Claude Code | -| `session` | `SessionMetadata \| undefined` | הקשר סשן (ראה להלן) | +| `payload` | `Record` | עומס אירוע גולמי מלא מ-Claude Code | +| `session` | `SessionMetadata \| undefined` | הקשר הסשן (ראה להלן) | ### שדות `SessionMetadata` | שדה | סוג | תיאור | |-------|------|-------------| -| `sessionId` | `string` | מזהה סשן Claude Code | -| `cwd` | `string` | ספרייה עובדת של סשן Claude Code | -| `transcriptPath` | `string` | נתיב לקובץ תמליל JSONL של הסשן | +| `sessionId` | `string` | Claude Code identifier סשן | +| `cwd` | `string` | ספריית עבודה של סשן Claude Code | +| `transcriptPath` | `string` | נתיב לקובץ תדמיר JSONL של הסשן | ### סוגי אירועים -| אירוע | כאשר הוא משתלח | תוכן `toolInput` | +| אירוע | מתי הוא נורה | תוכן `toolInput` | |-------|--------------|----------------------| -| `PreToolUse` | לפני Claude מריץ כלי | הקלט של הכלי (לדוגמה `{ command: "..." }` עבור Bash) | -| `PostToolUse` | לאחר השלמת כלי | הקלט של הכלי + `tool_result` (הפלט) | -| `Notification` | כאשר Claude שולח הודעה | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks חייבים תמיד להחזיר `allow()`, הם לא יכולים לחסום הודעות | -| `Stop` | כאשר הסשן של Claude מסתיים | ריק | +| `PreToolUse` | לפני Claude מפעיל כלי | קלט הכלי (למשל `{ command: "..." }` עבור Bash) | +| `PostToolUse` | לאחר סיום כלי | קלט הכלי + `tool_result` (הפלט) | +| `Notification` | כאשר Claude שולח התראה | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks חייבים תמיד להחזיר `allow()`, הם לא יכולים לחסום התראות | +| `Stop` | כאשר סשן Claude מסתיים | ריק | --- @@ -190,18 +196,18 @@ customPolicies.add({ 1. מדיניות מובנית (בסדר הגדרה) 2. מדיניות מותאמת אישית מפורשת מ-`customPoliciesPath` (בסדר `.add()`) -3. מדיניות קונוונציה מ-`.failproofai/policies/` של פרויקט (קבצים אלפבתיים, סדר `.add()` בתוך) -4. מדיניות קונוונציה מ-`~/.failproofai/policies/` של משתמש (קבצים אלפבתיים, סדר `.add()` בתוך) +3. מדיניות קונוונציה מפרויקט `.failproofai/policies/` (קבצים אלפביתיים, סדר `.add()` בתוך) +4. מדיניות קונוונציה מ-`~/.failproofai/policies/` של משתמש (קבצים אלפביתיים, סדר `.add()` בתוך) -ה-`deny` הראשון מקצר את כל המדיניות הלאה. כל הודעות `instruct` מצטברות ומועברות יחד. +ה-`deny` הראשון קוצר את כל המדיניויות הבאות. כל הודעות `instruct` מצטברות והן מועברות יחד. --- -## ייבוא טרנזיטיבי +## ייבואים עברי -קבצי מדיניות מותאמים אישית יכולים לייבא מודולים מקומיים באמצעות נתיבים יחסיים: +קבצי מדיניות מותאמת אישית יכולים לייבא מודולים מקומיים בשימוש בנתיבים יחסיים: ```js // my-policies.js @@ -218,13 +224,13 @@ customPolicies.add({ }); ``` -כל היבוא יחסי הנגיע מקובץ ההרשמה מתוחזר. זה מיושם על ידי כתיבה מחדש של ייבוא `from "failproofai"` לנתיב dist בפועל ויצירת קבצי `.mjs` זמניים כדי להבטיח תאימות ESM. +כל הייבואים היחסיים הנגישים מקובץ הכניסה נפתרים. זה מיושם על ידי כתיבה מחדש של ייבואי `from "failproofai"` לנתיב dist בפועל ויצירת קבצי `.mjs` זמניים כדי להבטיח תאימות ESM. --- ## סינון סוג אירוע -השתמש ב-`match.events` כדי להגביל מתי מדיניות משתלחת: +השתמש ב-`match.events` כדי להגביל מתי מדיניות נורה: ```js customPolicies.add({ @@ -238,26 +244,26 @@ customPolicies.add({ }); ``` -השמט `match` לחלוטין כדי להיות בעל יכולת בכל סוג אירוע. +השמט `match` לחלוטין כדי לנורות בכל סוג אירוע. --- ## טיפול בשגיאות ומצבי כשל -מדיניות מותאמת אישית היא **fail-open**: שגיאות לעולם לא חוסמות מדיניות מובנית או קורסות מטפל ה-hook. +מדיניות מותאמת אישית היא **fail-open**: שגיאות לעולם לא חוסמות מדיניות מובנית או קורסות את מטפל ה-hook. | כשל | התנהגות | |---------|----------| -| `customPoliciesPath` לא מוגדר | לא מחוגות מדיניות מותאמת אישית מפורשת; מדיניות קונוונציה ומובנית ממשיכות בדרך כלל | -| קובץ לא נמצא | אזהרה מתועדת ל-`~/.failproofai/hook.log`; מובנית ממשיכה | -| שגיאת תחביר/ייבוא (מפורשת) | שגיאה מתועדת ל-`~/.failproofai/hook.log`; מדיניות מותאמת אישית מפורשת דלגת | -| שגיאת תחביר/ייבוא (קונוונציה) | שגיאה מתועדת; קובץ זה דולג, קבצי קונוונציה אחרים עדיין נטענים | -| `fn` זורק בזמן ריצה | שגיאה מתועדת; ה-hook הזה מטופל כ-`allow`; hook אחר ממשיך | -| `fn` לוקח יותר מ-10s | timeout מתועד; מטופל כ-`allow` | -| ספרייה קונוונציה חסרה | לא מחוגות מדיניות קונוונציה; אין שגיאה | +| `customPoliciesPath` לא מוגדר | אין מדיניות מותאמת אישית מפורשת שתפעל; מדיניות קונוונציה ומובנית ממשיכות בדרך כלל | +| קובץ לא נמצא | אזהרה מעובדת ל-`~/.failproofai/hook.log`; מובנית ממשיך | +| שגיאת תחביר/ייבוא (מפורש) | שגיאה מעובדת ל-`~/.failproofai/hook.log`; מדיניות מותאמת אישית מפורשת דלגה | +| שגיאת תחביר/ייבוא (קונוונציה) | שגיאה מעובדת; קובץ זה דלג, קבצי קונוונציה אחרים עדיין טעונים | +| `fn` זורק בזמן ריצה | שגיאה מעובדת; hook זה מטופל כ-`allow`; hook אחרים ממשיכים | +| `fn` לוקח יותר מ-10 שניות | Timeout מעובד; מטופל כ-`allow` | +| תיקיית קונוונציה חסרה | אין מדיניות קונוונציה שתרוץ; ללא שגיאה | -כדי לתפוס שגיאות מדיניות מותאמת אישית, צפה בקובץ היומן: +כדי לתקן שגיאות במדיניות מותאמת אישית, צפה בקובץ היומן: ```bash tail -f ~/.failproofai/hook.log @@ -266,7 +272,7 @@ tail -f ~/.failproofai/hook.log --- -## דוגמה מלאה: מדיניות מרובה +## דוגמה מלאה: מדיניויות מרובות ```js // my-policies.js @@ -323,16 +329,16 @@ export { customPolicies }; ## דוגמאות -ספרייה `examples/` מכילה קבצי מדיניות מוכנים להפעלה: +תיקיית `examples/` מכילה קבצי מדיניות מוכנים להפעלה: | קובץ | תוכן | |------|----------| -| `examples/policies-basic.js` | חמש מדיניות מתחילים המכסות מצבי כשל סוכן נפוצים | -| `examples/policies-advanced/index.js` | דפוסים מתקדמים: ייבוא טרנזיטיבי, קריאות אסינכרוניות, הסרת פלט, וhooks של סיום סשן | -| `examples/convention-policies/security-policies.mjs` | מדיניות אבטחה מבוססת קונוונציה (חסום כתיבות .env, מנע כתיבה מחדש של git history) | -| `examples/convention-policies/workflow-policies.mjs` | מדיניות זרימת עבודה מבוססת קונוונציה (תזכורות בדיקה, קובץ כתיבה ביקורת) | +| `examples/policies-basic.js` | חמש מדיניויות התחלה המכסות מצבי כשל סוכן שכיחים | +| `examples/policies-advanced/index.js` | דפוסים מתקדמים: ייבואים עברי, קריאות אסינכרוניות, גריפת פלט, וחוקי סוף סשן | +| `examples/convention-policies/security-policies.mjs` | מדיניות אבטחה מבוססת קונוונציה (חסום כתיבות .env, מנע כתיבה מחדש של היסטוריית git) | +| `examples/convention-policies/workflow-policies.mjs` | מדיניות זרימת עבודה מבוססת קונוונציה (תזכורות בדיקה, קובץ כתיבות ביקורת) | -### שימוש בדוגמאות קבצים מפורשות +### שימוש בדוגמאות קובץ מפורשות ```bash failproofai policies --install --custom ./examples/policies-basic.js @@ -350,4 +356,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -אין צורך בפקודת התקנה — הקבצים נתונים באופן אוטומטי בהודעת hook הבאה. \ No newline at end of file +אין צורך בפקודת התקנה — הקבצים נתפסים באופן אוטומטי באירוע ה-hook הבא. \ No newline at end of file diff --git a/docs/he/dashboard.mdx b/docs/he/dashboard.mdx index 8149dd5c..527b90b7 100644 --- a/docs/he/dashboard.mdx +++ b/docs/he/dashboard.mdx @@ -1,10 +1,10 @@ --- -title: לוח בקרה -description: "עקוב אחרי הפעלות של סוכנים, בדוק קריאות כלים וניהול של מדיניות" +title: Dashboard +description: "ניטור של הפעלות סוכנים, בדיקה של קריאות כלים וניהול מדיניות" icon: chart-line --- -לוח הבקרה של failproofai היא אפליקציית רשת מקומית לניטור של הפעלות סוכנים בינה מלאכותית וניהול של מדיניות. ראה מה עשו הסוכנים שלך בזמן שלא היית שם. +לוח הבקרה של failproofai היא אפליקציית ווב מקומית לניטור של הפעלות סוכנים בינה מלאכותית וניהול מדיניות. ראו מה עשו הסוכנים שלכם בזמן שלא הייתם כאן. --- @@ -14,103 +14,105 @@ icon: chart-line failproofai ``` -נפתח ב-`http://localhost:8020`. +נפתח ב־`http://localhost:8020`. -לוח הבקרה קורא נתוני פרויקט, הפעלה ותצורת failproofai מקומיים ישירות מהמערכת הקבצים. תכונות שניתן להתאים אליהן (כמו תזכורות ביקורת והזמנות), שולחות את המידע הנדרש לבקשות אלו (כולל כתובות דוא"ל) ל-API ממוקדים. +לוח הבקרה קורא נתוני פרויקט, הפעלה והגדרת failproofai מקומיים ישירות מהמערכת הקבצים. תכונות מאומתות אופציונליות, כמו תזכורות ביקורת והזמנות, שולחות את המידע הנדרש לבקשות אלה (כולל כתובות דוא״ל) ל־API מרוחקים. --- ## עמודים -### פרויקטים +### Projects -מפרטת את כל פרויקטי Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, ו-Goose שנמצאו במחשב שלך. פרויקטי Claude מתגלים מ-`~/.claude/projects/` (או הנתיב שקבוע על ידי `CLAUDE_PROJECTS_PATH`); פרויקטי Codex מתגלים על ידי סריקה של כל תמליל תחת `~/.codex/sessions///
/*.jsonl` וקיבוץ לפי `cwd` המתועד בתיעוד הראשון של כל הפעלה; פרויקטי Copilot CLI מתגלים על ידי סריקה של כל `~/.copilot/session-state//workspace.yaml` (ניתן להגדיר דרך `COPILOT_HOME`) וקיבוץ לפי שדה `cwd`; פרויקטי Cursor Agent מתגלים על ידי סריקה של מטא-נתונים לכל הפעלה תחת `~/.cursor/agent-sessions//` (ניתן להגדיר דרך `CURSOR_HOME`, עם `conversations/` ו-`sessions/` בהחזקה כעותדות) עבור סקלר `cwd` ב-`meta.json` / `session.json` / `workspace.yaml`; פרויקטי OpenCode מתגלים על ידי שאילתה של SQLite DB שלו ב-`~/.local/share/opencode/opencode.db` דרך `opencode db --format json` (אנו קוראים את טבלאות `session` ו-`project` ומקבצים לפי `project_id`); פרויקטי Pi מתגלים על ידי סריקה של תמליל JSONL לכל הפעלה תחת `~/.pi/agent/sessions//_.jsonl` (ניתן להגדיר דרך `PI_SESSIONS_DIR`) והוצאת `cwd` מתיעוד הראשון של כל הפעלה; הפעלות שער Hermes נקראות ישירות מחנות SQLite שלו ב-`~/.hermes/state.db` (ניתן להגדיר דרך `HERMES_DB_PATH`) ומקובצות לפרויקטי `hermes-` לפי `source` (Slack/Telegram/cli/cron — הפעלות של שער אין להן cwd); הפעלות שער OpenClaw נקראות מ-`~/.openclaw/agents//sessions/*.jsonl` ומקובצות לפרויקטי `openclaw-` (גם ללא cwd); פרויקטי Factory Droid מתגלים מתמליל JSONL ב-`~/.factory/sessions//*.jsonl` ומקובצות לפי cwd; פרויקטי Devin מ-SQLite DB שלו ב-`~/.local/share/devin/cli/sessions.db` (מקובצות לפי `working_directory` של כל הפעלה); פרויקטי Antigravity מתמליל JSONL ב-`~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` ומקובצות לפי cwd; ופרויקטי Goose מ-SQLite DB שלו ב-`~/.local/share/goose/sessions/sessions.db` (מקובצות לפי `working_dir` של כל הפעלה). פרויקט ששימש בשימוש על ידי CLI מרובים מוגדר כשורה אחת עם כל התג המתאים. השתמש בתפריט ה-**CLI** מעל הטבלה כדי לסנן לפי סוכן CLI ספציפי; ה-URL משמר את הבחירה שלך כ-`?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +מפרטת את כל פרויקטי Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, וGoose שנמצאו במחשב שלך. פרויקטי Claude מגילים מ־`~/.claude/projects/` (או הנתיב שנקבע על ידי `CLAUDE_PROJECTS_PATH`); פרויקטי Codex מגילים על ידי סריקה של כל תמלול תחת `~/.codex/sessions///
/*.jsonl` וקיבוץ לפי `cwd` שנרשם בתיעוד הראשון של כל הפעלה; פרויקטי Copilot CLI מגילים על ידי סריקה של כל `~/.copilot/session-state//workspace.yaml` (הניתן להגדרה דרך `COPILOT_HOME`) וקיבוץ לפי שדה `cwd`; פרויקטי Cursor Agent מגילים על ידי סריקה של מטא־נתונים לכל הפעלה תחת `~/.cursor/agent-sessions//` (הניתן להגדרה דרך `CURSOR_HOME`, עם `conversations/` ו־`sessions/` כחלופות) עבור סקלר `cwd` ב־`meta.json` / `session.json` / `workspace.yaml`; פרויקטי OpenCode מגילים על ידי שאילתה של מסד הנתונים SQLite שלו ב־`~/.local/share/opencode/opencode.db` דרך `opencode db --format json` (אנו קוראים את הטבלאות `session` ו־`project` וקיבוץ לפי `project_id`); פרויקטי Pi מגילים על ידי סריקה של תמלולי JSONL לכל הפעלה תחת `~/.pi/agent/sessions//_.jsonl` (הניתן להגדרה דרך `PI_SESSIONS_DIR`) וחילוץ ה־`cwd` מהתיעוד הראשון של כל הפעלה; הפעלות שער Hermes נקראות ישירות מאחסון SQLite של כל פרופיל — `~/.hermes/state.db` בתוספת `~/.hermes/profiles//state.db` (ניתן לעקיפה דרך `HERMES_HOME`, או `HERMES_DB_PATH` עבור מסד נתונים יחיד) — וקיבוץ לפרויקטים `hermes--` לפי פרופיל ו־`source` (Slack/Telegram/cli/cron — להפעלות שער Hermes אין cwd); הפעלות שער OpenClaw נקראות מ־`~/.openclaw/agents//sessions/*.jsonl` וקיבוץ לפרויקטים `openclaw--` לפי סוכן וערוץ (גם ללא cwd); פרויקטי Factory Droid מגילים מתמלולי JSONL ב־`~/.factory/sessions//*.jsonl` וקיבוץ לפי cwd; פרויקטי Devin ממסד הנתונים SQLite שלו ב־`~/.local/share/devin/cli/sessions.db` (קיבוץ לפי `working_directory` של כל הפעלה); פרויקטי Antigravity מתמלולי JSONL ב־`~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` וקיבוץ לפי cwd; ופרויקטי Goose ממסד הנתונים SQLite שלו ב־`~/.local/share/goose/sessions/sessions.db` (קיבוץ לפי `working_dir` של כל הפעלה). פרויקט שנעשה בו שימוש על ידי CLI מרובים מופיע כשורה יחידה עם כל התגים תואמים. השתמשו בתפריט **CLI** מעל הטבלה כדי לסנן לפי CLI סוכן ספציפי; כתובת ה־URL שומרת את הבחירה שלכם כ־`?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. + +Hermes ו־OpenClaw מוגדרים לטווח משתמש ואין להם תיקיה עבודה לקיבוץ, אז הם מופיעים כ־**עץ תיקיות שניתן לקיפול** — פרופיל (או סוכן) ברמה העליונה, הערוצים שלו מתחתיו — בעוד שכל CLI מבוסס cwd נשאר בשורה שטוחה. שורות תיקיות מסכמות את מספר ההפעלות וההפעילות האחרונה ביותר של הכל מתחתיהן, תיקיות מקופלות זוכרות את עצמן בין ביקורים, וחיפוש מילה מפתח מרחיב כל עניין תואם. כל פרויקט מציג: -- שם הפרויקט (מנוצג מהנתיב התיקייה) -- תג CLI — `Claude Code` (כתום), `OpenAI Codex` (סגול), `GitHub Copilot` (כחול), `Cursor Agent` (ירוק), `OpenCode` (ענבר), `Pi` (ורוד), ו/או `Hermes` (אינדיגו) -- תאריך של פעילות הפעלה האחרונה +- שם הפרויקט (נגזר מנתיב התיקיה) +- תג CLI — `Claude Code` (כתום), `OpenAI Codex` (סגול), `GitHub Copilot` (כחול), `Cursor Agent` (ירוק־כחלחל), `OpenCode` (ענבר), `Pi` (ורוד), ו/או `Hermes` (אינדיגו) +- תאריך פעילות ההפעלה האחרונה ביותר -לחץ על פרויקט כדי לראות את הפעלותיו. +לחצו על פרויקט כדי לראות את ההפעלות שלו. -### הפעלות +### Sessions -מפרטת את כל ההפעלות בתוך פרויקט. כל הפעלה מציגה: +מפרטת את כל ההפעלות בפרויקט. כל הפעלה מציגה: - מזהה הפעלה - חותמות זמן של התחלה וסיום -- מספר של קריאות כלים -- ספירת פעילות hook (מדיניות שהשתלטה) +- מספר קריאות כלים +- ספירת פעילות hook (מדיניות שהופעלה) -השתמש בחוצץ טווח התאריך וחיפוש מזהה הפעלה כדי לצמצם את הרשימה. הפעלות מחולקות לעמודים. +השתמשו במסנן טווח התאריכים ובחיפוש מזהה הפעלה כדי לצמצם את הרשימה. ההפעלות מחולקות לעמודים. -לחץ על הפעלה כדי לפתוח את כלי הצפייה בהפעלה. +לחצו על הפעלה כדי לפתוח את מציג ההפעלה. -### כלי צפייה בהפעלה +### Session viewer -כלי הצפייה בהפעלה עונה לשאלה הקריטית עבור סוכנים אוטונומיים: מה עשה הסוכן, והאם הוא נשאר בעקבות? תג CLI ליד הכותרת מציין אם ההפעלה היא תמליל של Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, או Goose. הוא מציג ציר זמן של כל מה שקרה בהפעלה: +מציג ההפעלה עונה על השאלה המרכזית עבור סוכנים אוטונומיים: מה עשה הסוכן, והאם הוא נשאר על המסלול? תג CLI לצד הכותרת מציין אם ההפעלה היא תמלול Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, או Goose. זה מציג ציר זמן של כל מה שקרה בהפעלה: -- **הודעות** - תגובות טקסט של Claude והנחיות של משתמש -- **קריאות כלים** - כל כלי שקרא Claude, עם הקלט והפלט שלו -- **פעילות מדיניות** - עבור כל קריאת כלי, איזו מדיניות השתלטה ואיזו החלטה הם החזירו +- **Messages** - תגובות טקסט של Claude וקלטים של משתמש +- **Tool calls** - כל כלי שקרא Claude, עם הקלט והפלט שלו +- **Policy activity** - עבור כל קריאת כלי, אילו מדיניות הופעלו ואיזה החלטה הם החזירו -סרגל הנתונים בחלק העליון מציג משך הפעלה, סך הכל קריאות כלים, וסיכום של החלטות hook (ספירות allow / deny / instruct). +פס הנתונים בחלק העליון מציג משך הפעלה, סך קריאות כלים, וסיכום של החלטות hook (ספירות allow / deny / instruct). -לחץ על כפתור **Download Logs** כדי לייצא את ההפעלה. עבור הפעלות Claude Code, Codex, Copilot, Cursor, ו-Pi תקבל את תמליל JSONL המקורי על הדיסק בדיוק; עבור OpenCode (שהפעלותיו חיות ב-SQLite, לא על הדיסק) תקבל מסמך JSON המשקף את טבלאות `session` / `messages` / `parts` הבסיסיות. +לחצו על כפתור **Download Logs** כדי לייצא את ההפעלה. עבור הפעלות Claude Code, Codex, Copilot, Cursor, וPi אתם מקבלים את תמלול ה־JSONL המקורי על־דיסק בדיוק כמו שהוא; עבור OpenCode (שלהשלות החיות ב־SQLite, לא בדיסק) אתם מקבלים מסמך JSON המשקף את טבלאות `session` / `messages` / `parts` הבסיסיות. -### ביקורת +### Audit -דו"ח מונע על ידי אישיות של כיצד הסוכן שלך באמת התנהג על פני הפעלות קודמות. מריץ את אותה הסריקה כמו CLI `failproofai audit` אך מגדיר אותו כפוסטר בעמוד יחיד בר-שיתוף + ארבעה חלקים מתחת לקפל: +דוח מונע על ידי אישיות של אופן התנהגות הסוכן שלכם בפועל על פני הפעלות קודמות. מריץ את אותה סריקה כמו CLI `failproofai audit` אך מוצג אותו כעמודון בן עמוד יחיד וניתן לשיתוף + ארבע סעיפים מתחת לקיפול: -1. **פוסטר** — ממלא את חלון הצפייה הראשון. אזור התמונה PNG עצמי המכיל את הסמל של failproof_ai + תווית ביקורת · אינדקס אבטיפוס (`№ NN of 08`) + תאריך ביקורת · ניקוד מספרי (0–100) + כדור דירוג אחוזון (`top 15%`) · שם האבטיפוס (אחד מ-`the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + פס 3 מילות מפתח · שורת נדירות `// only N% of agents are this archetype` · אריח סיגיל 8×8 פיקסל · תחתית `audit yours → failproof.ai`. שלושה כפתורי שיתוף יושבים בדיוק מחוץ לתיבת הלכידה: `post your archetype` (כוונת X), `share on linkedin`, `download poster`. הלכידה מתבצעת דרך `html-to-image` כך ש-PNG תואם את העיבוד על המסך פיקסל-לפיקסל (גבולות מקווקווים, מסכת לוגו SVG, שיפועים, מטריקות גופן — כל משמור). -2. **נקודות חוזק** — רשימת שורות רגועה של התנהגויות שהסוכן שלך כבר עושה בצורה נכונה, שנגזרת מנתוני ביקורת חיים (שיעור קריאה כלים נקי, ללא דחיפות ישירות לעיקרון, אפס דיפויי אישור, אפס סערות ניסיון חוזר) — כל אחד מוצג רק כאשר למדיניות הרלוונטית יש שיא נקי על פני חלון הביקורת. -3. **ייחודיות** — טבלה של מה שהחליק, דירוג לפי חומרה: `when · what slipped + the policy that would've caught it · severity pill · seen`, כאשר הישנות נקראת `new` (פעם אחת), `N× seen` (2–9 פעמים), או `recurring` (10+). -4. **כיצד לשפר** — רשימת שורות רגועה, אחת לכל מדיניות קבועה: שם מדיניות בלבן, תיאור שורה אחת, פקודת התקנה + כפתור העתק בצד ימין. כותרת הסעיף קוראת `enable all N → projected · ` (הניקוד שהיית מגיע אליו עם כל התיקון שיושם), וכפתור `[install all]` שלו מעתיק את פקודת `failproofai policy add a b c …` המשולבת עבור כל מדיניות קבועה. -5. **חזור טוב יותר** — שתי כרטיסים זה לצד זה. שמאלה: הגדר תזכורת (בחירה קדנציה `3d` / `7d` / `14d` / `30d`; נשמרת דרך `/api/auth/reminder` ברגע שמאומתת). ימין: פתח את failproof perks — `invite a friend` פותח מודאל שלוקח רשימה מופרדת בפסיקים/רווחים/שדרי קו של דוא"ל חברים (מקסימום 10 לשליחה), POST אותם אל `/api/audit/invite`, המעביר אל `/v0/invite` של שרת ה-api. שרת ה-api שולח דוא"ל אחד לכל נמען מ-`invite@failproof.ai` עם שיתוף CC של השולח ו-`Reply-To` מוגדר, כך שהנמען רואה מי הזמין אותו והשולח מקבל העתק בתיבת הדואר הנכנס. משתמשים אנונימיים מנותבים דרך `AuthDialog` ראשון כך שדוא"ל השולח ידוע לפני שההזמנות יוצאות. זכאות / קיום perks הוא המשך. +1. **Poster** — ממלא את הצפייה הראשונה. אזור לכידת PNG עצמאי עם סמל failproof_ai + תווית ביקורת · אינדקס ארכטיפ (`№ NN of 08`) + תאריך ביקורת · ניקוד מספרי (0–100) + כדור דרגה אחוזונית (`top 15%`) · שם הארכטיפ (אחד מ־`the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + פסת מילות־מפתח של 3 · `// only N% of agents are this archetype` שורת נדירות · אריח סיגיל בגודל 8×8 פיקסל · `audit yours → failproof.ai` כותרת. שלושה כפתורי שיתוף יושבים ממש מחוץ לקופסת הלכידה: `post your archetype` (כוונת X), `share on linkedin`, `download poster`. הלכידה רץ דרך `html-to-image` אז ה־PNG תואם את הרינדור על־מסך פיקסל־לפיקסל (גבולות מקווקו, מסכת לוגו SVG, גרדיאנטים, מדדי גופן — הכל שמור). +2. **Strengths** — רשימת שורה שקטה ✓ של התנהגויות שהסוכן שלכם כבר עושה נכון, נגזרות מנתוני הביקורת החיים (שיעור קריאות כלים נקי, אין דחיפות ישירות ל־main, אפס דלפי אישורים, אפס סערות ניסיון) — כל אחד מופיע רק כאשר למדיניות הרלוונטית יש רקורד נקי על פני חלון הביקורת. +3. **Quirks** — טבלה של מה שחמק, מדורג לפי חומרה: `when · what slipped + the policy that would've caught it · severity pill · seen`, כאשר הישנות קוראת `new` (פעם אחת), `N× seen` (2–9 פעמים), או `recurring` (10+). +4. **How to improve** — רשימת שורה שקטה, אחת לכל מדיניות שנקבעה: שם המדיניות בלבן, תיאור של שורה אחת, פקודת התקנה + כפתור העתק בצד ימין. כותרת הסעיף קוראת `enable all N → projected · ` (הניקוד שהייתם מגיעים אליו עם כל התיקון מיושם), וכפתור `[install all]` שלה מעתיק את הפקודה `failproofai policy add a b c …` המשולבת לכל מדיניות שנקבעה. +5. **Come back better** — שתי כרטיסיות זו לצד זו. שמאל: הגדר תזכורת (בוחר קדנציה של `3d` / `7d` / `14d` / `30d`; נשמר דרך `/api/auth/reminder` לאחר אימות). ימין: פתח את זכויות failproof — `invite a friend` פותח מודאל שלוקח רשימה של כתובות דוא״ל של חברים מופרדות בפסיקים/רווחים/שורות חדשות (מקסימום 10 לכל שליחה), POST אותן ל־`/api/audit/invite`, המעביר ל־`POST /v0/invite` של api-server. api-server שולח דוא״ל אחד לכל נמען מ־`invite@failproof.ai` עם השולח Cc'd וה־`Reply-To` מוגדר, כך שהנמען רואה מי הזמין אותו והשולח מקבל עותק בתיבת הדואר שלו. משתמשים אנונימיים מנותבים דרך `AuthDialog` תחילה כך שדוא״ל השולח ידוע לפני יציאת הזמנות. הזכויות / קיום זכויות הוא עדכון שלאחר מכן. -מונע על ידי זמן ריצת `failproofai audit` — ראה [Audit CLI](/he/cli/audit) לעל ריצת הסריקה הבסיסית, דגלים נתמכים וקביעות מטמון לכל תמליל. לוח הבקרה משמר את התוצאה האחרונה ב-`~/.failproofai/audit-dashboard.json` (מצב `0600`, משבצת אחת, ריצות חדשות כותבות בעיתוי) כך שביקורי חזרה הם מידיים; **גם מטמוני לכל תמליל וגם של כל התוצאה נדחים בקריאה ברגע שהם יותר מעתיקים מ-7 ימים** כך שלוח הבקרה לא שומר תוצאה מלפני שבוע — מעבר ל-TTL `/audit` נופל למצבו הריק ומשאיל ריצה טרייה. לחיצה על `[ re-audit now ]` ליד תחתית הדו"ח POST אל `/api/audit/run` עם `noCache: true` — ביקורת מחדש עוקפת את מטמון לכל תמליל וסורקת מחדש כל תמליל מספריים במקום שתחזיר בשקט את התוצאה במטמון — ולוח הבקרה סוקר `/api/audit/status` ב-1Hz עד שהריצה מסתיימת; פס התקדמות ורוד דבוק מצייד את החלק העליון של חלון הצפייה במהלך הריצה עם טיימר שחלף, והתוצאה הטרייה מתחלפת למקומה בהצלחה (ללא טעינה מלאה בעמוד; ביקורת מחדש שנכשלה משאירה את הדו"ח הקודם שלמה). בכשל הפס הופך לאדום עם העתקה שמפתחתה ל-`RerunError.kind` (`timeout` / `network` / `post_failed`). מצב ריק (ללא מטמון או פג) ומצב אפס-הפעלות (מטמון קיים אך הסריקה לא מצאה תמליל) מוצגים בנפרד. +מונע על ידי זמן ריצה של `failproofai audit` — ראו [Audit CLI](/he/cli/audit) עבור מנוע הסריקה הבסיסי, דגלים נתמכים, ואי־שינוי מטמון לכל תמלול. לוח הבקרה מטמון את התוצאה האחרונה ב־`~/.failproofai/audit-dashboard.json` (מצב `0600`, חריץ יחיד, הריצות החדשות משכתבות) אז ביקורים חוזרים מיידיים; **גם המטמון לכל תמלול וגם התוצאה כוללה נדחים בקריאה ברגע שהם ישנים יותר מ־7 ימים** אז לוח הבקרה לעולם לא משרת בשקט תוצאה של שבוע — עבר ה־TTL `/audit` נופל למצב ריק שלו וומנציא ריצה טרייה. לחיצה על `[ re-audit now ]` בחלק התחתון של הדוח POST `/api/audit/run` עם `noCache: true` — ביקורת חוזרת מעקפת את מטמון התמלול לכל תמלול וסורקת מחדש כל תמלול מאפס במקום שתחזור בשקט את התוצאה המטמונה — ולוח הבקרה שוקלים `/api/audit/status` ב־1Hz עד שהריצה תסתיים; פס התקדמות ורוד דבוק מהדק לחלק העליון של viewport בזמן הריצה עם טיימר שחלף, והתוצאה הטרייה החליפה במקום בהצלחה (אין טעינה מחדש של דף שלם; ביקורת חוזרת שנכשלה משאירה את הדוח הקודם ללא נזק). בכשל הפס הופך לאדום עם העתק מקודד מ־`RerunError.kind` (`timeout` / `network` / `post_failed`). מצב ריק (אין מטמון או פג) ומצב אפס־הפעלות (מטמון קיים אך הסריקה לא מצאה תמלולים) מופיעים בנפרד. -### מדיניות +### Policies -עמוד בעל שתי כרטיסיות לניהול של מדיניות וביקורת של פעילות. +דף בשני־טבים לניהול מדיניות ובדיקת פעילות. - - - בחר מרובות איזה CLI סוכנים failproofai מגן עליו מלוח יחיד — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, ו-Hermes כולם יש שורה עם סטטוס התקנה (`Active` / `Detected` / `Inactive`), נתיב הגדרות ההיקף של משתמש, וברים צבע מותג. בדוק או בטל בדיקה של CLI שאתה רוצה ולחץ על `Apply changes` כדי להתקין/הסרה את ההבדל בשלב אחד. CLI שהבינארי שלו מתגלה ב-PATH מסומנים מראש. - - עבור בין מדיניות בודדות או כיבה בלחיצה יחידה (כתיבה ל-`~/.failproofai/policies-config.json` — משותפת על פני כל CLI מותקן) - - הרחב מדיניות כדי להגדיר את הפרמטרים שלה (עבור מדיניות התומכות ב-`policyParams`) - - הגדר נתיב קובץ מדיניות מותאם אישית + + - בחרו את CLIs מרובים שנוגעים להם failproofai מחלק יחיד — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, וHermes כולם יש שורה עם סטטוס התקנה (`Active` / `Detected` / `Inactive`), נתיב הגדרות ההיקף משתמש, והדגש בצבע מותג. סמנו או בטלו סימון CLIs שאתם רוצים וכפו `Apply changes` כדי להתקין/להסיר התקנה של ההפרש בשלב אחד. CLIs שהבינארי שלהם מגולה ב־PATH מסומנים מראש. + - החלפו מדיניויות בודדות הלוך וחזור עם לחיצה יחידה (כותב ל־`~/.failproofai/policies-config.json` — משותף על פני כל CLI מותקן) + - הרחיבו מדיניות כדי להגדיר את הפרמטרים שלה (עבור מדיניויות התומכות ב־`policyParams`) + - הגדרו נתיב קובץ מדיניות מותאם - - - היסטוריה מעודכנת מלאה של כל אירוע hook שהשתלט על כל ההפעלות - - סנן לפי החלטה, סוג אירוע, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), שם מדיניות, או מזהה הפעלה - - כל שורה מציגה: חותם זמן, שם מדיניות, החלטה, תג CLI (כתום = Claude Code, סגול = OpenAI Codex, כחול = GitHub Copilot, ירוק = Cursor Agent, ענבר = OpenCode, ורוד = Pi, אינדיגו = Hermes, בטורקיז = OpenClaw, ורד = Factory Droid, סגול = Devin, ציאן = Antigravity, ירוק גיר = Goose), שם כלי, מזהה הפעלה, והסיבה להחלטות deny/instruct - - לחץ על מזהה הפעלה כדי לפתוח את התמליל שלו — כלי הצפייה אוטומטית מזהה איזה CLI השתלט בהוק (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) ומגדיר את תג ה-CLI המתאימה בכותרת + + - היסטוריה מלאה מעמודה של כל אירוע hook שהופעל על פני כל ההפעלות + - סננו לפי החלטה, סוג אירוע, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), שם מדיניות, או מזהה הפעלה + - כל שורה מציגה: חותמת זמן, שם מדיניות, החלטה, תג CLI (כתום = Claude Code, סגול = OpenAI Codex, כחול = GitHub Copilot, ירוק־כחלחל = Cursor Agent, ענבר = OpenCode, ורוד = Pi, אינדיגו = Hermes, טיל = OpenClaw, ורד = Factory Droid, סגול = Devin, ציאן = Antigravity, ליים = Goose), שם כלי, מזהה הפעלה, והסיבה להחלטות deny/instruct + - לחצו על מזהה הפעלה כדי לפתוח את התמלול שלה — המציג גוכל מגילה באופן אוטומטי איזה CLI הפעיל את ה־hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) ומוצג את תג CLI התואם בכותרת --- -## ריענון אוטומטי +## Auto-refresh -לוח הבקרה יש כפתור ריענון אוטומטי בניווט העליון. כאשר מופעל, העמוד הנוכחי משתנה מעת לעת כדי להציג הפעלות חדשות ופעילות מדיניות כשהם מופיעים. חיוני לניטור של הפעלות סוכנים אוטונומיים ארוכות טווח. +לוח הבקרה יש החלפת עדכון־אוטומטי בניווט העליון. כאשר מופעל, הדף הנוכחי מתרענן בתקופות כדי להציג הפעלות חדשות ופעילות מדיניות בעוד שהן מופיעות. חיוני לניטור של הפעלות סוכנים אוטונומיים ארוכי־טווח. --- ## השבתת עמודים -אם אתה צריך רק חלקים מסוימים מלוח הבקרה, קבע `FAILPROOFAI_DISABLE_PAGES` לרשימה מופרדת בפסיקים של שמות עמודים: +אם אתם צריכים רק כמה חלקים מלוח הבקרה, הגדרו `FAILPROOFAI_DISABLE_PAGES` לרשימה מופרדת בפסיקים של שמות עמודים: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai ``` -ערכים תקפים: `policies`, `projects`, `audit`. +ערכים חוקיים: `policies`, `projects`, `audit`. --- -## הגדרת נתיב פרויקטים +## הגדרת נתיב הפרויקטים -כברירת מחדל, לוח הבקרה קורא מספריית פרויקטי Claude Code הסטנדרטית. עקוף זה עבור הגדרות מותאמות אישית: +כברירת מחדל, לוח הבקרה קורא מתיקיית הפרויקטים של Claude Code הסטנדרטית. עקיפו אותה עבור הגדרות מותאמות: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,30 +122,30 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## גישה מהוסט שאינו localhost -בעת הפעלת לוח הבקרה ב-**מצב dev** (`npm run dev`) וגישה אליו מהוסט שאינו `localhost` - לדוגמה, דומיין מותאם אישית, IP מרוחק, או URL במנהרה - ייתכן שתראה אזהרה כמו: +בעת הפעלת לוח הבקרה ב־**מצב פיתוח** (`npm run dev`) וגישה אליו משם שינוי שאינו `localhost` - לדוגמה, תחום מותאם, IP מרוחק, או כתובת URL בעדכון - ייתכן שתראו אזהרה כמו: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -זה Next.js חוסם גישה חוצת מקורות ל-HMR (hot module reload) websocket שלו, שהיא תכונה של dev בלבד. כדי לאפשר את ההוסט שלך, השתמש בדגל `--allowed-origins`: +זה Next.js חוסם גישה בין־קדמויות לה־HMR של dev (שדונלוד מודול חם), שהיא תכונה שרק בפיתוח. כדי לאפשר את הערוחש שלך, השתמשו בדגל `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -עבור מספר הוסטים או IP, עבור רשימה מופרדת בפסיקים: +עבור הוסטים או IP מרובים, העבירו רשימה מופרדת בפסיקים: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -אתה יכול גם להגדיר את משתנה הסביבה `FAILPROOFAI_ALLOWED_DEV_ORIGINS` במקום: +אתם יכולים גם להגדיר את משתנה הסביבה `FAILPROOFAI_ALLOWED_DEV_ORIGINS` במקום: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -זה חל רק על מצב dev. בעת הפעלת `failproofai` (מצב ייצור), אין websocket HMR ואין בעיית משאב dev חוצת מקורות. +זה חל רק על מצב פיתוח. בעת הפעלת `failproofai` (מצב ייצור), אין websocket HMR ואין בעיה משאב dev בין־קדמויות. \ No newline at end of file diff --git a/docs/hi/configuration.mdx b/docs/hi/configuration.mdx index f19342cc..771b621e 100644 --- a/docs/hi/configuration.mdx +++ b/docs/hi/configuration.mdx @@ -1,28 +1,29 @@ --- +--- title: कॉन्फ़िगरेशन description: "कॉन्फ़िग फ़ाइल प्रारूप, तीन-स्कोप सिस्टम, और मर्ज नियम" icon: gear --- -failproofai JSON कॉन्फ़िगरेशन फ़ाइलों का उपयोग करता है यह नियंत्रित करने के लिए कि कौन सी नीतियां सक्रिय हैं, वे कैसे व्यवहार करती हैं, और कहां से कस्टम नीतियां लोड की जाती हैं। कॉन्फ़िगरेशन आपकी टीम के साथ साझा करने के लिए आसान बनाया गया है - इसे अपने रेपो में कमिट करें और हर डेवलपर को एक जैसा एजेंट सेफ्टी नेट मिले। +failproofai JSON कॉन्फ़िगरेशन फ़ाइलों का उपयोग करता है यह नियंत्रित करने के लिए कि कौन सी नीतियां सक्रिय हैं, वे कैसे व्यवहार करती हैं, और कहां से कस्टम नीतियां लोड की जाती हैं। कॉन्फ़िगरेशन को आपकी टीम के साथ साझा करना आसान बनाया गया है - इसे अपने रिपॉजिटरी में कमिट करें और हर डेवलपर को समान एजेंट सुरक्षा मिलती है। --- ## कॉन्फ़िगरेशन स्कोप -तीन कॉन्फ़िगरेशन स्कोप हैं, जिनका मूल्यांकन प्राथमिकता क्रम में किया जाता है: +तीन कॉन्फ़िगरेशन स्कोप हैं, प्राथमिकता क्रम में मूल्यांकित: -| स्कोप | फ़ाइल पाथ | उद्देश्य | +| स्कोप | फ़ाइल पथ | उद्देश्य | |-------|-----------|---------| -| **project** | `.failproofai/policies-config.json` | प्रति-रेपो सेटिंग्स, संस्करण नियंत्रण में कमिट की गई | -| **local** | `.failproofai/policies-config.local.json` | व्यक्तिगत प्रति-रेपो ओवरराइड, gitignored | -| **global** | `~/.failproofai/policies-config.json` | उपयोगकर्ता-स्तरीय डिफ़ॉल्ट सभी प्रोजेक्ट्स में | +| **project** | `.failproofai/policies-config.json` | प्रति-रिपॉजिटरी सेटिंग्स, संस्करण नियंत्रण में कमिट की गई | +| **local** | `.failproofai/policies-config.local.json` | व्यक्तिगत प्रति-रिपॉजिटरी ओवरराइड, gitignored | +| **global** | `~/.failproofai/policies-config.json` | सभी प्रोजेक्ट्स में उपयोगकर्ता-स्तरीय डिफ़ॉल्ट | -जब failproofai को एक हुक ईवेंट मिलता है, तो यह सभी तीन फ़ाइलों को लोड और मर्ज करता है जो वर्तमान कार्य निर्देशिका के लिए मौजूद हैं। +जब failproofai को कोई हुक इवेंट प्राप्त होता है, तो यह वर्तमान कार्यकारी निर्देशिका के लिए मौजूद सभी तीन फ़ाइलों को लोड और मर्ज करता है। ### मर्ज नियम -**`enabledPolicies`** - सभी तीन स्कोप का संघ। कोई भी नीति जो किसी भी स्तर पर सक्षम है, सक्रिय होती है। +**`enabledPolicies`** - सभी तीन स्कोप का यूनियन। किसी भी स्तर पर सक्षम की गई नीति सक्रिय है। ```text project: ["block-sudo"] @@ -32,7 +33,7 @@ global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← deduplicated union ``` -**`policyParams`** - पहला स्कोप जो किसी दिए गए नीति के लिए पैरामीटर परिभाषित करता है वह पूरी तरह जीत जाता है। नीति के पैरामीटर के मान में कोई गहरा मर्जिंग नहीं होता। +**`policyParams`** - पहला स्कोप जो किसी दी गई नीति के लिए params परिभाषित करता है पूरी तरह जीत जाता है। किसी नीति के params के भीतर मूल्यों का कोई गहरा मर्जिंग नहीं है। ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -49,9 +50,11 @@ global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← falls through to global ``` -**`customPoliciesPath`** - पहला स्कोप जो इसे परिभाषित करता है, जीत जाता है। +**`customPoliciesPaths` / `customPoliciesPath`** - पहला स्कोप जो किसी भी रूप को परिभाषित करता है जीत जाता है। + +**`disabledCustomPolicies`** - सभी स्कोप में यूनियन। डैशबोर्ड यहां स्रोत-योग्य आईडी लिखता है जब आप एक स्पष्ट या कन्वेंशन नीति फ़ाइल से व्यक्तिगत नीति को बंद कर देते हैं। सूची में नहीं की गई नीतियां डिफ़ॉल्ट रूप से सक्षम रहती हैं; आईडी में स्रोत फ़ाइल शामिल है ताकि कई फ़ाइलों में समान नाम की नीतियों को स्वतंत्र रूप से नियंत्रित किया जा सके। -**`llm`** - पहला स्कोप जो इसे परिभाषित करता है, जीत जाता है। +**`llm`** - पहला स्कोप जो इसे परिभाषित करता है जीत जाता है। --- @@ -96,31 +99,31 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← falls through to glo --- -## फ़ील्ड संदर्भ +## फील्ड संदर्भ ### `enabledPolicies` प्रकार: `string[]` -सक्षम करने के लिए नीति के नाम की सूची। नाम बिल्कुल `failproofai policies` द्वारा दिखाए गए नीति पहचानकर्ता से मेल खाना चाहिए। संपूर्ण सूची के लिए [बिल्ट-इन पॉलिसीज़](/hi/built-in-policies) देखें। +सक्षम करने के लिए नीति के नामों की सूची। नामों को बिल्कुल `failproofai policies` द्वारा दिखाए गए नीति पहचानकर्ताओं से मेल खाना चाहिए। पूरी सूची के लिए [Built-in Policies](/hi/built-in-policies) देखें। -`enabledPolicies` में नहीं होने वाली नीतियां निष्क्रिय होती हैं, भले ही उनके पास `policyParams` में प्रविष्टियां हों। +`enabledPolicies` में नहीं होने वाली नीतियां निष्क्रिय हैं, भले ही उनके पास `policyParams` में प्रविष्टियां हों। ### `policyParams` प्रकार: `Record>` -प्रति-नीति पैरामीटर ओवरराइड। बाहरी कुंजी नीति का नाम है; आंतरिक कुंजियां नीति-विशिष्ट हैं। प्रत्येक नीति [बिल्ट-इन पॉलिसीज़](/hi/built-in-policies) में अपने उपलब्ध पैरामीटर को दस्तावेज़ित करती है। +प्रति-नीति पैरामीटर ओवरराइड। बाहरी कुंजी नीति का नाम है; आंतरिक कुंजियां नीति-विशिष्ट हैं। प्रत्येक नीति [Built-in Policies](/hi/built-in-policies) में अपने उपलब्ध पैरामीटर प्रलेखित करती है। -यदि किसी नीति के पैरामीटर हैं लेकिन आप उन्हें निर्दिष्ट नहीं करते, तो नीति के बिल्ट-इन डिफ़ॉल्ट का उपयोग किया जाता है। वे उपयोगकर्ता जो `policyParams` को बिल्कुल कॉन्फ़िगर नहीं करते, उन्हें पिछले संस्करणों के समान व्यवहार मिलता है। +यदि किसी नीति के पास पैरामीटर हैं लेकिन आप उन्हें निर्दिष्ट नहीं करते हैं, तो नीति के बिल्ट-इन डिफ़ॉल्ट का उपयोग किया जाता है। जो उपयोगकर्ता `policyParams` कॉन्फ़िगर बिल्कुल नहीं करते हैं वे पिछले संस्करणों के समान व्यवहार प्राप्त करते हैं। -नीति के पैरामीटर ब्लॉक के अंदर अज्ञात कुंजियों को हुक-फायर समय पर चुप्पी से अनदेखा किया जाता है लेकिन जब आप `failproofai policies` चलाते हैं तो चेतावनियों के रूप में फ़्लैग किया जाता है। +किसी नीति के params ब्लॉक के अंदर अज्ञात कुंजियां हुक-फायर समय पर मौन रूप से अनदेखी की जाती हैं लेकिन जब आप `failproofai policies` चलाते हैं तो चेतावनियों के रूप में फ्लैग किए जाते हैं। -#### `hint` (क्रॉस-कटिंग) +#### `hint` (cross-cutting) -प्रकार: `string` (वैकल्पिक) +प्रकार: `string` (optional) -एक संदेश जो जोड़ा जाता है कारण जब कोई नीति `deny` या `instruct` देता है। इसका उपयोग Claude को नीति को संशोधित किए बिना कार्रवाई योग्य निर्देशन देने के लिए करें। +एक संदेश जो तब जोड़ा जाता है जब नीति `deny` या `instruct` रिटर्न करती है। Claude को नीति को संशोधित किए बिना कार्यक्षम मार्गदर्शन देने के लिए इसका उपयोग करें। किसी भी नीति प्रकार के साथ काम करता है — बिल्ट-इन, कस्टम (`custom/`), प्रोजेक्ट कन्वेंशन (`.failproofai-project/`), या उपयोगकर्ता कन्वेंशन (`.failproofai-user/`)। @@ -128,53 +131,53 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← falls through to glo { "policyParams": { "block-force-push": { - "hint": "Try creating a fresh branch instead." + "hint": "इसके बजाय एक ताज़ी शाखा बनाने का प्रयास करें।" }, "block-sudo": { "allowPatterns": ["sudo apt-get"], - "hint": "Use apt-get directly without sudo." + "hint": "sudo के बिना सीधे apt-get का उपयोग करें।" }, "custom/my-policy": { - "hint": "Ask the user for approval first." + "hint": "पहले उपयोगकर्ता से अनुमति माँगें।" } } } ``` -जब `block-force-push` अस्वीकार करता है, तो Claude को यह दिखता है: *"Force-pushing is blocked. Try creating a fresh branch instead."* +जब `block-force-push` अस्वीकार करता है, तो Claude देखता है: *Force-pushing को ब्लॉक किया गया है। इसके बजाय एक ताज़ी शाखा बनाने का प्रयास करें।* -गैर-स्ट्रिंग मान और खाली स्ट्रिंग्स को चुप्पी से अनदेखा किया जाता है। यदि `hint` सेट नहीं है, तो व्यवहार अपरिवर्तित रहता है (पश्चविमुखी-संगत)। +गैर-स्ट्रिंग मान और खाली स्ट्रिंग्स को मौन रूप से अनदेखी किया जाता है। यदि `hint` सेट नहीं है, तो व्यवहार अपरिवर्तित है (backward-compatible)। ### `customPoliciesPath` -प्रकार: `string` (निरपेक्ष पाथ) +प्रकार: `string` (absolute path) -कस्टम हुक नीतियों वाली JavaScript फ़ाइल का पाथ। यह स्वचालित रूप से `failproofai policies --install --custom ` द्वारा सेट किया जाता है (पाथ को निरपेक्ष के लिए हल किया जाता है फिर संग्रहीत किया जाता है)। +कस्टम हुक नीतियों वाली JavaScript फ़ाइल का पथ। यह `failproofai policies --install --custom ` द्वारा स्वचालित रूप से सेट किया जाता है (पथ को पूर्ण में हल किया जाता है इससे पहले कि इसे संग्रहीत किया जाए)। -फ़ाइल प्रत्येक हुक ईवेंट पर ताज़ी लोड की जाती है - कोई कैशिंग नहीं है। विस्तार के लिए [कस्टम पॉलिसीज़](/hi/custom-policies) देखें। +फ़ाइल हर हुक इवेंट पर ताज़ी लोड की जाती है - कोई कैशिंग नहीं है। विस्तृत जानकारी के लिए [Custom Policies](/hi/custom-policies) देखें। ### कन्वेंशन-आधारित नीतियां -स्पष्ट `customPoliciesPath` के अलावा, failproofai स्वचालित रूप से `.failproofai/policies/` निर्देशिकाओं से नीति फ़ाइलों की खोज करता है और लोड करता है: +स्पष्ट `customPoliciesPath` के अलावा, failproofai स्वचालित रूप से `.failproofai/policies/` निर्देशिकाओं से नीति फ़ाइलों की खोज और लोड करता है: | स्तर | निर्देशिका | स्कोप | |-------|-----------|-------| -| परियोजना | `.failproofai/policies/` | संस्करण नियंत्रण के माध्यम से टीम के साथ साझा किया गया | -| उपयोगकर्ता | `~/.failproofai/policies/` | व्यक्तिगत, सभी प्रोजेक्ट्स पर लागू | +| Project | `.failproofai/policies/` | संस्करण नियंत्रण के माध्यम से टीम के साथ साझा किया गया | +| User | `~/.failproofai/policies/` | व्यक्तिगत, सभी प्रोजेक्ट्स पर लागू | -**फ़ाइल मिलान:** केवल `*policies.{js,mjs,ts}` से मेल खाने वाली फ़ाइलें लोड की जाती हैं (उदा. `security-policies.mjs`, `workflow-policies.js`)। निर्देशिका में अन्य फ़ाइलें अनदेखी की जाती हैं। +**फ़ाइल मिलान:** केवल `*policies.{js,mjs,ts}` से मेल खाने वाली फ़ाइलें लोड की जाती हैं (उदा। `security-policies.mjs`, `workflow-policies.js`)। निर्देशिका में अन्य फ़ाइलें अनदेखी की जाती हैं। -**कोई कॉन्फ़िग की आवश्यकता नहीं:** कन्वेंशन नीतियों के लिए `policies-config.json` में प्रविष्टियों की आवश्यकता नहीं है। बस निर्देशिका में फ़ाइलें डालें और अगली हुक ईवेंट पर उन्हें चुना जाएगा। +**कोई कॉन्फ़िग की आवश्यकता नहीं:** कन्वेंशन नीतियों को `policies-config.json` में कोई प्रविष्टि की आवश्यकता नहीं है। बस फ़ाइलें निर्देशिका में डालें और वे अगले हुक इवेंट पर उठाई जाती हैं। -**यूनियन लोडिंग:** प्रोजेक्ट और उपयोगकर्ता दोनों कन्वेंशन निर्देशिकाएं स्कैन की जाती हैं। दोनों स्तरों से सभी मेल खाने वाली फ़ाइलें लोड की जाती हैं (`customPoliciesPath` के विपरीत जो पहले-स्कोप-जीत का उपयोग करता है)। +**यूनियन लोडिंग:** प्रोजेक्ट और उपयोगकर्ता दोनों कन्वेंशन निर्देशिकाओं को स्कैन किया जाता है। दोनों स्तरों से सभी मिलने वाली फ़ाइलें लोड की जाती हैं (`customPoliciesPath` के विपरीत जो पहले-स्कोप-जीत का उपयोग करता है)। -अधिक विवरण और उदाहरणों के लिए [कस्टम पॉलिसीज़](/hi/custom-policies) देखें। +अधिक जानकारी और उदाहरणों के लिए [Custom Policies](/hi/custom-policies) देखें। ### `llm` -प्रकार: `object` (वैकल्पिक) +प्रकार: `object` (optional) -उन नीतियों के लिए LLM क्लाइंट कॉन्फ़िगरेशन जो AI कॉल करते हैं। अधिकांश सेटअप के लिए आवश्यक नहीं है। +AI कॉल करने वाली नीतियों के लिए LLM क्लाइंट कॉन्फ़िगरेशन। अधिकांश सेटअप के लिए आवश्यक नहीं है। ```json { @@ -189,19 +192,24 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← falls through to glo ## CLI से कॉन्फ़िगरेशन प्रबंधित करना -`policies --install` और `policies --uninstall` कमांड आपके एजेंट CLI की हुक सेटिंग्स फ़ाइल (हुक एंट्री पॉइंट) में लिखते हैं, जबकि `policies-config.json` वह फ़ाइल है जिसे आप सीधे प्रबंधित करते हैं। दोनों अलग हैं: - -- **एजेंट CLI सेटिंग्स** — एजेंट को बताता है कि प्रत्येक टूल उपयोग पर `failproofai --hook ` को कॉल करना है: - - **Claude Code**: `~/.claude/settings.json` (उपयोगकर्ता), `/.claude/settings.json` (प्रोजेक्ट), `/.claude/settings.local.json` (लोकल) - - **OpenAI Codex**: `~/.codex/hooks.json` (उपयोगकर्ता), `/.codex/hooks.json` (प्रोजेक्ट) — Codex के पास `local` स्कोप नहीं है - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (उपयोगकर्ता), `/.github/hooks/failproofai.json` (प्रोजेक्ट) — Copilot के पास कोई `local` स्कोप नहीं है। हुक एंट्रीज़ Copilot के OS-keyed `bash`/`powershell` कमांड फ़ील्ड का उपयोग करते हैं `timeoutSec` के साथ; फ़ाइल एक टॉप-लेवल `version: 1` मार्कर ले जाती है। Copilot CLI समर्थन **beta** है जबकि हम `events.jsonl` रिकॉर्ड स्कीमा को सत्यापित करते हैं (जिसे सार्वजनिक दस्तावेज़ निर्दिष्ट नहीं करते) अधिक वास्तविक-दुनिया सत्रों के विरुद्ध। - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (उपयोगकर्ता), `/.cursor/hooks.json` (प्रोजेक्ट) — Cursor के पास कोई `local` स्कोप नहीं है। हुक एंट्रीज़ Claude-shaped `{type, command, timeout}` फॉर्म का उपयोग करते हैं (कोई `bash`/`powershell` विभाजन नहीं), लेकिन camelCase ईवेंट कुंजियों के तहत संग्रहीत (`preToolUse`, `beforeSubmitPrompt`, …) Cursor के [hooks schema](https://cursor.com/docs/hooks) के अनुसार एक फ्लैट ऐरे में; फ़ाइल एक टॉप-लेवल `version: 1` मार्कर ले जाती है। हैंडलर camelCase → PascalCase को `CURSOR_EVENT_MAP` के माध्यम से कैनोनिकलाइज़ करता है ताकि मौजूदा बिल्ट-इन नीतियां अपरिवर्तित रूप से चलें। Cursor Agent समर्थन **beta** है जबकि हम Cursor के ट्रांसक्रिप्ट को सत्यापित करते हैं (सार्वजनिक दस्तावेज़ में निर्दिष्ट नहीं) अधिक वास्तविक-दुनिया इंस्टॉल्स के विरुद्ध। - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (उपयोगकर्ता), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (प्रोजेक्ट) — OpenCode के पास कोई `local` स्कोप नहीं है। अन्य पाँच CLI के विपरीत, OpenCode के पास **कोई बाहरी-कमांड हुक सिस्टम नहीं है**: यह JS/TS प्लगइन को `opencode.json` में `plugin: []` ऐरे के माध्यम से स्पष्ट रूप से पंजीकृत करके इन-प्रॉसेस लोड करता है (`.opencode/plugins/` से ऑटो-डिस्कवरी **नहीं** है कि प्लगइन opencode v1.14.33 पर कैसे लोड होते हैं)। इंस्टॉल एक छोटा जेनरेटेड प्लगइन शिम छोड़ता है जो failproofai बाइनरी को subprocess-कॉल करता है और बाइनरी के Claude-shape JSON प्रतिक्रिया को प्लगइन शब्दावली में वापस अनुवाद करता है: `throw new Error()` टूल-ईवेंट deny के लिए (टूल कॉल को रद्द करता है), `client.session.prompt(...)` instruct AND के लिए `Stop` / `SubagentStop` deny (deny कारण को अगले उपयोगकर्ता संदेश के रूप में जमा करता है — एकमात्र force-retry चैनल क्योंकि `session.idle` केवल-अधिसूचना है और इससे throw करना एक no-op है), और allow के लिए no-op। शिम both टूल नाम (lowercase → PascalCase `OPENCODE_TOOL_MAP` के माध्यम से) और tool-input arg कुंजियां (camelCase → snake_case `OPENCODE_TOOL_INPUT_MAP` के माध्यम से `Read` / `Write` / `Edit` के लिए, उदा. `filePath` → `file_path`, `oldString` → `old_string`) कैनोनिकलाइज़ करता है बाइनरी में अग्रेषित करने से पहले, इसलिए path-checking builtins जैसे `block-read-outside-cwd`, `block-env-files`, और `block-secrets-write` OpenCode tool कॉल पर अपरिवर्तित रूप से चलते हैं। सत्र opencode के SQLite DB में `~/.local/share/opencode/opencode.db` में रहते हैं; डैशबोर्ड का सत्र दर्शक `opencode db --format json` और `opencode export ` के माध्यम से उन्हें पढ़ता है। OpenCode समर्थन **beta** है जबकि हम संस्करणों में व्यवहार को सत्यापित करते हैं और अधिक वास्तविक-दुनिया सत्रों के विरुद्ध। [OpenCode plugins docs](https://opencode.ai/docs/plugins/) देखें। - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (उपयोगकर्ता), `/.pi/settings.json` (प्रोजेक्ट) — Pi के पास कोई `local` स्कोप नहीं है। Pi स्टार्टअप पर TypeScript extension पैकेज लोड करता है; सेटिंग्स फ़ाइल एक फ्लैट स्ट्रिंग ऐरे `{"packages": ["./relative/path", …]}` है। failproofai एक single packages-array एंट्री लिखता है जो अपनी bundled `pi-extension/` निर्देशिका की ओर इशारा करता है। एक्सटेंशन आंतरिक रूप से Pi के `tool_call` / `user_bash` / `input` / `session_start` ईवेंट्स की सदस्यता लेता है और `failproofai --hook --cli pi` के लिए shell बाहर निकालता है; हैंडलर underscore_lower_snake_case → PascalCase को `PI_EVENT_MAP` के माध्यम से कैनोनिकलाइज़ करता है ताकि मौजूदा बिल्ट-इन नीतियां अपरिवर्तित रूप से चलें। Tool input args को `PI_TOOL_INPUT_MAP` के माध्यम से भी कैनोनिकलाइज़ किया जाता है (Pi के Read / Write / Edit `path` के बजाय `file_path` प्रदान करते हैं; शीर्ष-स्तरीय कुंजी को मैप करना `block-env-files` और `block-secrets-write` को चलने देता है — `block-read-outside-cwd` पहले से ही एक `path` fallback था)। Pi समर्थन **beta** है जबकि Pi का एक्सटेंशन API और session-log लेआउट स्थिर होता है। - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**उपयोगकर्ता स्कोप केवल** — Hermes के पास कोई project/local कॉन्फ़िग नहीं है)। Hermes एक Slack/Telegram **गेटवे** है, इसलिए एक इंस्टॉल हर प्लेटफॉर्म (Slack/Telegram/cli/cron) **और** आंतरिक subagents से tool कॉल को इंटरसेप्ट करता है। हुक एंट्रीज़ एक `{command, timeout}` pair (**सेकंड में** timeout) हैं एक `hooks:` map के तहत Hermes के snake_case ईवेंट्स द्वारा keyed (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); हैंडलर ईवेंट्स को `HERMES_EVENT_MAP` के माध्यम से और टूल नाम को `HERMES_TOOL_MAP` के माध्यम से कैनोनिकलाइज़ करता है ताकि बिल्ट-इन नीतियां अपरिवर्तित रूप से चलें। कॉन्फ़िग एक comment-preserving YAML `Document` round-trip के माध्यम से संपादित किया जाता है ताकि ऑपरेटर की अन्य सेटिंग्स जीवित रहें, और install `hooks_auto_accept: true` सेट करता है ताकि headless gateway (कोई TTY नहीं) consent प्रॉम्प्ट के बिना हुक चलाए। मूल्यांकनकर्ता Hermes के `{"decision":"block","reason"}` stdout contract उत्सर्जित करता है (Hermes exit कोड को अनदेखा करता है)। **सीमाएं:** Hermes के पास कोई turn-end `Stop` ईवेंट नहीं है, इसलिए `require-*-before-stop` builtins कभी इसके लिए नहीं चलते (inapplicable, broken नहीं); `instruct` allow-with-logged-note में degrade होता है (कोई additional-context चैनल नहीं); और output-secret redaction (`sanitize-*`) shell-hook contract के ऊपर tool output को rewrite नहीं कर सकता। Hermes **भी** एक offline **audit** स्रोत है — डैशबोर्ड अपने gateway सत्रों को सीधे `~/.hermes/state.db` से पढ़ता है। -- **`policies-config.json`** — failproofai को बताता है कि कौन सी नीतियों का मूल्यांकन करना है और किस पैरामीटर के साथ (सभी एजेंट CLIs में साझा) - -एक विशिष्ट एजेंट को target करने के लिए `--cli claude|codex|copilot|cursor|opencode|pi|hermes` पास करें (space-separated या repeated किसी भी subset के लिए): +`policies --install` और `policies --uninstall` आदेश आपके एजेंट CLI की हुक सेटिंग्स फ़ाइल (हुक प्रवेश बिंदु) में लिखते हैं, जबकि `policies-config.json` वह फ़ाइल है जिसे आप सीधे प्रबंधित करते हैं। ये दोनों अलग हैं: + +- **एजेंट CLI सेटिंग्स** — एजेंट को प्रत्येक टूल उपयोग पर `failproofai --hook ` कॉल करने के लिए कहता है: + - **Claude Code**: `~/.claude/settings.json` (user), `/.claude/settings.json` (project), `/.claude/settings.local.json` (local) + - **OpenAI Codex**: `~/.codex/hooks.json` (user), `/.codex/hooks.json` (project) — Codex के पास `local` स्कोप नहीं है + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (user), `/.github/hooks/failproofai.json` (project) — Copilot के पास `local` स्कोप नहीं है। हुक प्रविष्टियां Copilot के OS-keyed `bash`/`powershell` कमांड फील्ड के साथ `timeoutSec` का उपयोग करती हैं; फ़ाइल में शीर्ष-स्तर `version: 1` मार्कर है। Copilot CLI सपोर्ट **beta** है जबकि हम `events.jsonl` रिकॉर्ड स्कीमा (जिसे सार्वजनिक दस्तावेज़ निर्दिष्ट नहीं करते) को अधिक वास्तविक-दुनिया सत्रों के विरुद्ध सत्यापित करते हैं। **VS Code Copilot Chat agent mode (Preview)** हुक कॉन्फ़िग को `.github/hooks/*.json`, `~/.copilot/hooks/*.json`, और `~/.claude/settings.json` से पढ़ता है (`chat.hookFilesLocations` सेटिंग द्वारा शासित) समान Claude-shaped `{hookSpecificOutput:{permissionDecision:"deny",…}}` अनुबंध का उपयोग करते हुए — बिल्कुल वे पथ जो यह `copilot` एकीकरण और `claude` एकीकरण (`~/.claude/settings.json`) पहले से लिखते हैं, इसलिए `failproofai policies --install --cli copilot` (या `--cli claude`) **पहले से ही VS Code एजेंट मोड में लागू करता है** अलग `vscode` एकीकरण की कोई आवश्यकता नहीं (VS Code की खोज लॉग्स से पुष्टि की गई)। + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — Cursor के पास `local` स्कोप नहीं है। हुक प्रविष्टियां Claude-shaped `{type, command, timeout}` रूप का उपयोग करती हैं (`bash`/`powershell` विभाजन नहीं), लेकिन camelCase event keys (`preToolUse`, `beforeSubmitPrompt`, …) के तहत Cursor के [hooks schema](https://cursor.com/docs/hooks) के अनुसार सपाट सरणी में संग्रहीत। फ़ाइल में शीर्ष-स्तर `version: 1` मार्कर है। हैंडलर `CURSOR_EVENT_MAP` के माध्यम से camelCase → PascalCase को सामान्य बनाता है ताकि मौजूदा बिल्ट-इन नीतियां अपरिवर्तित रूप से फायर हों। Cursor Agent सपोर्ट **beta** है जबकि हम Cursor के ट्रांसक्रिप्ट ऑन-डिस्क प्रारूप (सार्वजनिक दस्तावेज़ में निर्दिष्ट नहीं) को अधिक वास्तविक-दुनिया इंस्टॉल के विरुद्ध सत्यापित करते हैं। + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (user), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (project) — OpenCode के पास `local` स्कोप नहीं है। अन्य पांच CLIs के विपरीत, OpenCode के पास **कोई बाहरी-कमांड हुक सिस्टम नहीं है**: यह `opencode.json` में `plugin: []` सरणी के माध्यम से स्पष्ट रूप से पंजीकृत में-प्रक्रिया JS/TS प्लगइन लोड करता है (`.opencode/plugins/` से auto-discovery **नहीं** है कि opencode v1.14.33 पर प्लगइन कैसे लोड होते हैं)। इंस्टॉल एक छोटा जनित प्लगइन शिम डालता है जो failproofai बाइनरी को subprocess-कॉल करता है और बाइनरी की Claude-shape JSON प्रतिक्रिया को प्लगइन शब्दार्थ में वापस अनुवाद करता है: tool-event deny के लिए `throw new Error()` (टूल कॉल को रद्द करता है), instruct के लिए `client.session.prompt(...)` AND `Stop` / `SubagentStop` deny के लिए (अगले उपयोगकर्ता संदेश के रूप में अस्वीकार कारण जमा करता है — एकमात्र force-retry चैनल क्योंकि `session.idle` notification-only है और इससे फेंकना एक no-op है), और allow के लिए no-op। शिम both tool names (lowercase → PascalCase via `OPENCODE_TOOL_MAP`) और tool-input arg keys (camelCase → snake_case via `OPENCODE_TOOL_INPUT_MAP` for `Read` / `Write` / `Edit`, उदा। `filePath` → `file_path`, `oldString` → `old_string`) को सामान्य बनाता है बाइनरी को अग्रेषित करने से पहले, तो पथ-जाँच builtins जैसे `block-read-outside-cwd`, `block-env-files`, और `block-secrets-write` OpenCode टूल कॉल पर अपरिवर्तित रूप से फायर करते हैं। सत्र opencode के SQLite DB में `~/.local/share/opencode/opencode.db` पर रहते हैं; डैशबोर्ड का सत्र दर्शक `opencode db --format json` और `opencode export ` के माध्यम से उन्हें पढ़ता है। OpenCode सपोर्ट **beta** है जबकि हम संस्करणों और अधिक वास्तविक-दुनिया सत्रों के विरुद्ध व्यवहार को सत्यापित करते हैं। [OpenCode plugins docs](https://opencode.ai/docs/plugins/) देखें। + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `/.pi/settings.json` (project) — Pi के पास `local` स्कोप नहीं है। Pi स्टार्टअप पर TypeScript extension packages लोड करता है; सेटिंग्स फ़ाइल एक सपाट स्ट्रिंग सरणी `{"packages": ["./relative/path", …]}` है। failproofai अपनी bundled `pi-extension/` निर्देशिका की ओर इंगित करते हुए एक एकल packages-array प्रविष्टि लिखता है। एक्सटेंशन आंतरिक रूप से Pi के `tool_call` / `user_bash` / `input` / `session_start` इवेंट्स की सदस्यता लेता है और `failproofai --hook --cli pi` को शेल आउट करता है; हैंडलर underscore_lower_snake_case → PascalCase को `PI_EVENT_MAP` के माध्यम से सामान्य बनाता है ताकि मौजूदा बिल्ट-इन नीतियां अपरिवर्तित रूप से फायर हों। Tool input args भी `PI_TOOL_INPUT_MAP` के माध्यम से सामान्य बनाए जाते हैं (Pi का Read / Write / Edit `path` के बजाय `file_path` प्रदान करता है; शीर्ष-स्तर कुंजी मैपिंग `block-env-files` और `block-secrets-write` को फायर करने देता है — `block-read-outside-cwd` पहले से ही एक `path` fallback था)। Pi सपोर्ट **beta** है जबकि Pi के extension API और session-log layout स्थिर होते हैं। + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**केवल user scope** — Hermes के पास project/local कॉन्फ़िग नहीं है)। Hermes एक Slack/Telegram **gateway** है, इसलिए एक इंस्टॉल हर प्लेटफॉर्म (Slack/Telegram/cli/cron) से टूल कॉल को **और** आंतरिक subagents को इंटरसेप्ट करता है। हुक प्रविष्टियां एक `{command, timeout}` जोड़ी हैं (timeout **सेकंड** में) Hermes के snake_case events (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) द्वारा keyed एक `hooks:` मैप के तहत; हैंडलर events को `HERMES_EVENT_MAP` के माध्यम से और tool names को `HERMES_TOOL_MAP` के माध्यम से सामान्य बनाता है ताकि बिल्ट-इन नीतियां अपरिवर्तित रूप से फायर हों। कॉन्फ़िग एक comment-preserving YAML `Document` round-trip के माध्यम से संपादित किया जाता है ताकि ऑपरेटर की अन्य सेटिंग्स बनी रहें, और install `hooks_auto_accept: true` सेट करता है ताकि headless gateway (कोई TTY नहीं) सहमति प्रॉम्प्ट के बिना हुक चलाए। मूल्यांकनकर्ता Hermes के `{"decision":"block","reason"}` stdout अनुबंध को उत्सर्जित करता है (Hermes exit codes को अनदेखी करता है)। **सीमाएं:** Hermes के पास कोई turn-end `Stop` इवेंट नहीं है, इसलिए `require-*-before-stop` builtins इसके लिए कभी नहीं फायर करते हैं (inapplicable, broken नहीं); `instruct` allow-with-logged-note में degrade होता है (कोई अतिरिक्त-context channel नहीं); और output-secret redaction (`sanitize-*`) shell-hook अनुबंध पर टूल आउटपुट को फिर से लिख नहीं सकता। Hermes **भी** एक offline **audit** स्रोत है — डैशबोर्ड `~/.hermes/state.db` से gateway सत्रों को सीधे पढ़ता है। + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**केवल user scope** — OpenClaw के पास project/local कॉन्फ़िग नहीं है)। Hermes की तरह, OpenClaw एक स्व-होस्टेड multi-channel **gateway** है, इसलिए एक इंस्टॉल हर चैनल और अपने आंतरिक subagents से टूल कॉल को इंटरसेप्ट करता है। कार्यान्वयन OpenClaw के **in-process plugin hooks** के माध्यम से चलता है (इसकी फ़ाइल-आधारित आंतरिक hooks observation-only हैं और ब्लॉक नहीं कर सकते), इसलिए — OpenCode/Pi की तरह — failproofai एक static `openclaw-plugin/` पैकेज भेज जो failproofai बाइनरी को async-spawn करता है और verdict को अनुवाद करता है। Install shipped plugin dir को `openclaw.json` के `plugins.load.paths[]` में पंजीकृत करता है और इसे `plugins.entries.failproofai` के तहत सक्षम करता है (`hooks.allowConversationAccess: true` के साथ, raw-conversation hooks के लिए आवश्यक)। मूल्यांकनकर्ता एक सपाट `{permission, reason}` verdict को उत्सर्जित करता है और शिम इसे प्रत्येक हुक के native return shape में मैप करता है: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), और `before_agent_finalize → {action:"revise", reason}` (**Stop** — एक वास्तविक turn-end gate, इसलिए `require-*-before-stop` builtins **लागू करते हैं** OpenClaw पर, Hermes के विपरीत)। Events और tool names binary-side को `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) के माध्यम से सामान्य बनाते हैं ताकि बिल्ट-इन नीतियां अपरिवर्तित रूप से फायर हों; शिम किसी भी spawn/parse/timeout त्रुटि पर open fail होता है। OpenClaw **भी** एक offline **audit** स्रोत है — डैशबोर्ड `~/.openclaw/agents//sessions/.jsonl` पर इसके JSONL सत्रों को पढ़ता है। + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (user), `/.factory/hooks.json` (project) — Factory के पास `local` स्कोप नहीं है। droid एक Claude-style बाहरी-कमांड हुक सिस्टम भेज, लेकिन droid v0.171.0 के विरुद्ध लाइव सत्यापित दो quirks के साथ: (1) event names `hooks.json` के **शीर्ष स्तर** पर रहते हैं — कोई **`"hooks"` wrapper नहीं** है (droid एक को अस्वीकार करता है); tool events (`PreToolUse`/`PostToolUse`) `"matcher": "*"` ले जाते हैं, non-tool events इसे छोड़ते हैं। (2) Deny को हुक **exit code 2 + stderr** द्वारा चलाया जाता है, JSON decision नहीं — मूल्यांकनकर्ता की `factory` branch tool/prompt events के लिए exit 2 रिटर्न करता है और turn-end `Stop` event पर `{decision:"block", reason}` केवल (droid का एकमात्र force-retry channel)। Events पहले से ही PascalCase हैं (कोई event map नहीं) और payload Claude snake_case है; केवल tool names `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …) के माध्यम से सामान्य बनाए जाते हैं। Factory **भी** एक offline **audit** स्रोत है — डैशबोर्ड `~/.factory/sessions//.jsonl` पर इसके on-disk JSONL सत्रों को पढ़ता है। + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (user), `/.devin/config.json` (project) — Devin के पास `local` स्कोप नहीं है। Devin एक **pure Claude-clone** है devin v3000.1.27 के विरुद्ध लाइव सत्यापित: यह standard Claude `"hooks"`-wrapper schema (writes merge-preserving हैं ताकि कॉन्फ़िग फ़ाइल की अन्य keys — `org_id`, `theme_mode`, … — बनी रहें), पहले से ही-PascalCase event names (कोई event map, कोई handler branch नहीं), और Claude snake_case stdin payload (कोई normalization नहीं) का उपयोग करता है। मूल्यांकनकर्ता की `devin` branch **प्रत्येक** event के लिए `{"decision":"block","reason"}` JSON को stdout पर exit 0 पर अस्वीकार करता है (सत्यापित — block ने `--permission-mode dangerous` को ओवरराइड किया); turn-end `Stop` event पर कारण MANDATORY-ACTION force-retry शब्दार्थ ले जाता है ताकि `require-*-before-stop` builtins लागू हों। केवल tool names `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` पहले से ही canonical है) के माध्यम से सामान्य बनाए जाते हैं। Devin **भी** एक offline **audit** स्रोत है — डैशबोर्ड `~/.local/share/devin/cli/sessions.db` पर इसके SQLite सत्रों को पढ़ता है (प्रत्येक `sessions` row एक वास्तविक `working_directory` ले जाता है, इसलिए सत्र Devin जैसी project cwd द्वारा समूह)। + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (user), `/.agents/hooks.json` (project) — Antigravity के पास `local` स्कोप नहीं है। Factory/Devin के विपरीत, Antigravity अपना **स्वयं का** अनुबंध है (Claude-clone नहीं), agy v1.1.2 के विरुद्ध लाइव सत्यापित। `hooks.json` एक **named-hook** schema का उपयोग करता है: शीर्ष-स्तर कुंजी एक हुक *नाम* है (`"failproofai"`) जिसका मान एक event→handlers map है — tool events (`PreToolUse`/`PostToolUse`) handlers को `{matcher:"*", hooks:[…]}` में लपेटते हैं, जबकि `PreInvocation`/`Stop` **सपाट** handler arrays हैं (अन्य named hooks संरक्षित हैं)। stdin payload **camelCase protojson** है (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai इसे नीतियां चलाने से पहले snake_case में सामान्य बनाता है, और `run_command` की PascalCase args (`CommandLine`/`Cwd`) को `ANTIGRAVITY_TOOL_INPUT_MAP` के माध्यम से मैप करता है। मूल्यांकनकर्ता की `antigravity` branch Antigravity की **स्वयं** response shapes का उपयोग करता है: `{decision:"deny", reason}` एक tool/prompt को ब्लॉक करता है (exit 0), `{decision:"continue", reason}` turn-end `Stop` पर लूप में फिर से प्रवेश करता है (इसलिए `require-*-before-stop` builtins लागू करते हैं), और `{injectSteps:[{ephemeralMessage}]}` `PreInvocation` पर एक instruction को इंजेक्ट करता है (→ `UserPromptSubmit`)। Tool names `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …) के माध्यम से सामान्य बनाते हैं। Antigravity **भी** एक offline **audit** स्रोत है — डैशबोर्ड `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` पर इसके plain-JSONL transcripts को पढ़ता है (conversation index `conversation_summaries.db` में)। + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (user), `/.agents/plugins/failproofai/hooks/hooks.json` (project) — Goose के पास `local` स्कोप नहीं है। कार्यान्वयन Goose के **hooks** सिस्टम का उपयोग करता है, cross-agent **Open Plugins** spec: installer बस `failproofai` plugin dir को डालता है और Goose स्टार्टअप पर इसे auto-discovers करता है (इसे `~/.config/goose/config.yaml` में स्व-पंजीकृत करते हुए)। `hooks.json` एक Open Plugins schema **with** एक शीर्ष-स्तर `"hooks"` wrapper का उपयोग करता है, और matcher **हर event पर छोड़ा जाता है** — एक bare `"*"` एक अमान्य regex है जो कुछ से मेल नहीं खाता (goose v1.43.0 के विरुद्ध लाइव सत्यापित)। Event names पहले से ही PascalCase हैं (कोई event map नहीं); stdin payload `event`/`working_dir` का उपयोग करता है, जिसे हैंडलर `hook_event_name`/`cwd` में सामान्य बनाता है। मूल्यांकनकर्ता की `goose` branch `{"decision":"block","reason"}` JSON को stdout पर exit 0 पर अस्वीकार करता है, **`PreToolUse`** event पर केवल सम्मानित (goose ≥ v1.37.0 में भेज) — जो shell tool के लिए **और** delegated subagents के अंदर फायर करता है, इसलिए यह एकमात्र पर्याप्त deny बिंदु है; कोई भी अन्य हुक त्रुटि **open** fail होती है। Goose के पास **कोई `Stop` event नहीं है**, इसलिए `require-*-before-stop` builtins लागू नहीं होते हैं (Hermes की तरह)। Tool names `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) के माध्यम से सामान्य बनाते हैं और path keys `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`) के माध्यम से। Goose **भी** एक offline **audit** स्रोत है — डैशबोर्ड `~/.local/share/goose/sessions/sessions.db` पर इसके SQLite सत्रों को पढ़ता है (प्रत्येक `sessions` row वास्तविक `working_dir` ले जाता है, इसलिए सत्र Devin की तरह project cwd द्वारा समूह; `--no-session` scratch runs फ़िल्टर किए जाते हैं)। +- **`policies-config.json`** — failproofai को बताता है कौन सी नीतियों का मूल्यांकन करना है और किन params के साथ (सभी एजेंट CLIs में साझा) + +एक विशिष्ट एजेंट को लक्ष्य करने के लिए `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` pass करें (space-separated या किसी उपसमूह के लिए दोहराया गया): ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +218,28 @@ failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli hermes --scope user -failproofai policies --install --cli claude codex copilot cursor opencode pi +failproofai policies --install --cli openclaw --scope user +failproofai policies --install --cli factory --scope project +failproofai policies --install --cli devin --scope project +failproofai policies --install --cli antigravity --scope project +failproofai policies --install --cli goose --scope project +failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -जब `--cli` omit किया जाता है, `failproofai` पता लगाता है कि कौन से एजेंट CLIs installed हैं (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`): +जब `--cli` छोड़ा जाता है, तो `failproofai` पहचानता है कौन से एजेंट CLIs इंस्टॉल किए गए हैं (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): -- **एक CLI detected** — prompt के बिना उस CLI को auto-select करता है। -- **Multiple CLIs detected** एक interactive terminal में — एक arrow-key single-select प्रॉम्प्ट दिखाता है एक `Detected (N)` section (एक `Install for all N detected` aggregate row + प्रत्येक detected CLI individually के साथ) और एक `Not installed (M) · install hooks ahead of time` section में grouped (हर undetected supported CLI को एक forward-install विकल्प के रूप में सूचीबद्ध करता है (↑↓ move करने के लिए, Enter select करने के लिए, ^C quit करने के लिए))। uninstall flow केवल Detected section दिखाता है। -- **Multiple CLIs detected** एक non-interactive run में (CI, कोई TTY नहीं) — prompt के बिना सभी detected CLIs के लिए install करता है। -- **None detected** — `claude` को fallback करता है, एक warning के साथ कि कोई एजेंट बाइनरी PATH में नहीं मिला; हुक कमांड अभी भी लिखा जाता है ताकि यह तुरंत सक्रिय हो जाए जब आप एक install करते हैं। +- **एक CLI पहचाना गया** — बिना प्रॉम्प्ट किए उस CLI को auto-select करता है। +- **कई CLIs पहचाने गए** इंटरैक्टिव टर्मिनल में — एक arrow-key एकल-select प्रॉम्प्ट दिखाता है एक `Detected (N)` सेक्शन में समूहीकृत (एक `Install for all N detected` aggregate row + प्रत्येक detected CLI व्यक्तिगत रूप से) और एक `Not installed (M) · install hooks ahead of time` सेक्शन हर undetected supported CLI को forward-install विकल्प के रूप में सूचीबद्ध करता है (↑↓ move, Enter select, ^C quit). Uninstall flow केवल Detected सेक्शन दिखाता है। +- **कई CLIs पहचाने गए** non-interactive run में (CI, कोई TTY नहीं) — बिना प्रॉम्प्ट किए सभी detected CLIs के लिए इंस्टॉल करता है। +- **कोई भी नहीं पहचाना गया** — `claude` पर fallback करता है, एक चेतावनी के साथ कि कोई agent binary PATH में नहीं मिला; हुक कमांड अभी भी लिखा गया है इसलिए यह activate होता है जैसे ही आप एक इंस्टॉल करते हैं। -आप किसी भी समय `policies-config.json` को सीधे edit कर सकते हैं; changes अगली हुक ईवेंट पर तुरंत प्रभावी होते हैं restart की आवश्यकता नहीं है। +आप किसी भी समय `policies-config.json` को सीधे संपादित कर सकते हैं; परिवर्तन अगले हुक इवेंट पर तुरंत प्रभावी होते हैं restart की कोई आवश्यकता नहीं है। --- -## उदाहरण: टीम डिफ़ॉल्ट के साथ प्रोजेक्ट-लेवल कॉन्फ़िग +## उदाहरण: टीम डिफ़ॉल्ट के साथ प्रोजेक्ट-स्तरीय कॉन्फ़िगरेशन -अपने रेपो में `.failproofai/policies-config.json` को कमिट करें: +`.failproofai/policies-config.json` को अपने रिपॉजिटरी में कमिट करें: ```json { @@ -245,4 +258,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi } ``` -प्रत्येक डेवलपर फिर व्यक्तिगत overrides के लिए `.failproofai/policies-config.local.json` (gitignored) बना सकता है बिना teammates को प्रभावित किए। \ No newline at end of file +प्रत्येक डेवलपर तब `.failproofai/policies-config.local.json` (gitignored) को व्यक्तिगत overrides के लिए बना सकता है बिना साथियों को प्रभावित किए। \ No newline at end of file diff --git a/docs/hi/custom-policies.mdx b/docs/hi/custom-policies.mdx index 68696d2a..564c1ec1 100644 --- a/docs/hi/custom-policies.mdx +++ b/docs/hi/custom-policies.mdx @@ -1,10 +1,10 @@ --- -title: कस्टम पॉलिसीज -description: "JavaScript में अपने नियम लिखें - सम्मेलनों को लागू करें, ड्रिफ्ट को रोकें, विफलताओं का पता लगाएं, बाहरी सिस्टम के साथ इंटीग्रेट करें" +title: कस्टम पॉलिसीज़ +description: "JavaScript में अपने नियम लिखें - परियोजना सम्मेलनों को लागू करें, drift को रोकें, विफलताओं का पता लगाएं, बाहरी सिस्टम के साथ एकीकृत करें" icon: code --- -कस्टम पॉलिसीज आपको किसी भी एजेंट व्यवहार के लिए नियम लिखने देती हैं: प्रोजेक्ट सम्मेलनों को लागू करें, ड्रिफ्ट को रोकें, विनाशकारी संचालन को गेट करें, फंसे हुए एजेंटों का पता लगाएं, या Slack, अनुमोदन वर्कफ़्लो और बहुत कुछ के साथ इंटीग्रेट करें। ये बिल्ट-इन पॉलिसीज के समान हुक ईवेंट सिस्टम और `allow`, `deny`, `instruct` निर्णयों का उपयोग करते हैं। +कस्टम पॉलिसीज़ आपको किसी भी एजेंट व्यवहार के लिए नियम लिखने देती हैं: परियोजना सम्मेलनों को लागू करें, drift को रोकें, विनाशकारी संचालन को गेट करें, stuck एजेंट्स का पता लगाएं, या Slack, अनुमोदन वर्कफ़्लो और अन्य के साथ एकीकृत करें। ये built-in पॉलिसीज़ के समान ही hook event सिस्टम और `allow`, `deny`, `instruct` निर्णयों का उपयोग करते हैं। --- @@ -37,54 +37,59 @@ failproofai policies --install --custom ./my-policies.js --- -## कस्टम पॉलिसीज लोड करने के दो तरीके +## कस्टम पॉलिसीज़ लोड करने के दो तरीके -### विकल्प 1: सम्मेलन-आधारित (अनुशंसित) +### विकल्प 1: परंपरा-आधारित (अनुशंसित) -`.failproofai/policies/` में `*policies.{js,mjs,ts}` फाइलें डालें और वे स्वचालित रूप से लोड हो जाती हैं — कोई फ्लैग या कॉन्फ़िग परिवर्तन की आवश्यकता नहीं। यह git हुक्स की तरह काम करता है: एक फाइल डालें, यह बस काम करता है। +`.failproofai/policies/` में `*policies.{js,mjs,ts}` फ़ाइलें ड्रॉप करें और वे स्वचालित रूप से लोड हो जाती हैं — कोई flags या config परिवर्तन की आवश्यकता नहीं। यह git hooks की तरह काम करता है: फ़ाइल ड्रॉप करें, यह बस काम करता है। ``` -# प्रोजेक्ट स्तर — git में कमिट किया गया, टीम के साथ साझा किया गया +# परियोजना स्तर — git में प्रतिबद्ध, टीम के साथ साझा .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# यूजर स्तर — व्यक्तिगत, सभी प्रोजेक्ट्स पर लागू होता है +# उपयोगकर्ता स्तर — व्यक्तिगत, सभी परियोजनाओं पर लागू होता है ~/.failproofai/policies/my-policies.mjs ``` **यह कैसे काम करता है:** -- दोनों प्रोजेक्ट और यूजर डायरेक्ट्रीज को स्कैन किया जाता है (यूनियन — पहली-स्कोप-जीत नहीं) -- फाइलें प्रत्येक डायरेक्ट्री में वर्णानुक्रम में लोड होती हैं। ऑर्डर को नियंत्रित करने के लिए `01-`, `02-` के साथ प्रीफिक्स करें -- केवल `*policies.{js,mjs,ts}` से मेल खाने वाली फाइलें लोड होती हैं; अन्य फाइलें अनदेखी की जाती हैं -- प्रत्येक फाइल स्वतंत्र रूप से लोड होती है (फाइल प्रति फेल-ओपन) -- स्पष्ट `--custom` और बिल्ट-इन पॉलिसीज के साथ काम करता है +- परियोजना और उपयोगकर्ता दोनों निर्देशिकाओं को स्कैन किया जाता है (union — पहले-scope-wins नहीं) +- फ़ाइलें प्रत्येक निर्देशिका के भीतर वर्णक्रम में लोड की जाती हैं। क्रम को नियंत्रित करने के लिए `01-`, `02-` से प्रीफ़िक्स करें +- केवल `*policies.{js,mjs,ts}` से मेल खाने वाली फ़ाइलें लोड की जाती हैं; अन्य फ़ाइलें अनदेखी की जाती हैं +- प्रत्येक फ़ाइल स्वतंत्र रूप से लोड की जाती है (प्रति फ़ाइल fail-open) +- स्पष्ट `--custom` और built-in पॉलिसीज़ के साथ काम करता है -सम्मेलन पॉलिसीज आपके संगठन के लिए गुणवत्ता मानक बनाने का सबसे आसान तरीका है। `.failproofai/policies/` को git में कमिट करें और प्रत्येक टीम सदस्य को स्वचालित रूप से समान नियम मिलते हैं — कोई प्रति-डेवलपर सेटअप आवश्यक नहीं है। जब आपकी टीम नई विफलता मोड की खोज करे, एक पॉलिसी जोड़ें और पुश करें। समय के साथ ये एक जीवंत गुणवत्ता मानक बन जाता है जो हर योगदान के साथ बेहतर होता रहता है। +परंपरा पॉलिसीज़ आपके संगठन के लिए गुणवत्ता मानक बनाने का सबसे आसान तरीका है। `.failproofai/policies/` को git में कमिट करें और हर टीम सदस्य को स्वचालित रूप से समान नियम मिलते हैं — कोई प्रति-डेवलपर सेटअप की आवश्यकता नहीं है। जैसे ही आपकी टीम नई विफलता के मोड खोजती है, एक पॉलिसी जोड़ें और पुश करें। समय के साथ ये एक जीवंत गुणवत्ता मानक बन जाते हैं जो हर योगदान के साथ बेहतर होता रहता है। -### विकल्प 2: स्पष्ट फाइल पाथ +### विकल्प 2: स्पष्ट फ़ाइल पथ ```bash -# कस्टम पॉलिसीज फाइल के साथ इंस्टॉल करें +# कस्टम पॉलिसीज़ फ़ाइल के साथ इंस्टॉल करें failproofai policies --install --custom ./my-policies.js -# पॉलिसीज फाइल पाथ बदलें +# कस्टम पॉलिसी पथों को बदलें failproofai policies --install --custom ./new-policies.js -# कॉन्फ़िग से कस्टम पॉलिसीज पाथ हटाएं +# कई स्पष्ट फ़ाइलों को कॉन्फ़िगर करें (flag क्रम में लोड किया जाता है) +failproofai policies --install --custom ./security.js --custom ./workflow.js + +# config से सभी स्पष्ट कस्टम पॉलिसी पथों को हटाएं failproofai policies --uninstall --custom ``` -समाधान किया गया निरपेक्ष पाथ `policies-config.json` में `customPoliciesPath` के रूप में संग्रहीत होता है। फाइल हर हुक ईवेंट पर ताजा लोड होती है - ईवेंट्स के बीच कोई कैशिंग नहीं होती है। +समाधान किए गए पूर्ण पथ `policies-config.json` में `customPoliciesPaths` के रूप में संग्रहीत किए जाते हैं। कई फ़ाइलों को कॉन्फ़िगर करने के लिए `--custom` दोहराएं। Legacy `customPoliciesPath` फ़ील्ड का उपयोग करने वाली मौजूदा configs काम करती रहेगी। फ़ाइलें हर hook event पर ताज़ी लोड होती हैं - events के बीच कोई caching नहीं है। + +प्रत्येक पंजीकृत पॉलिसी डैशबोर्ड में अपने स्वयं के toggle के साथ दिखाई देती है। किसी पॉलिसी को बंद करने से इसका source-qualified ID `disabledCustomPolicies` में दर्ज किया जाता है; फ़ाइल और इसकी अन्य पॉलिसीज़ लोड होती रहती हैं, जबकि अक्षम पॉलिसी event मिलान से पहले बाहर निकाल दी जाती है। फ़ाइलों में डुप्लिकेट पॉलिसी नामों के स्वतंत्र toggles होते हैं। ### दोनों को एक साथ उपयोग करना -सम्मेलन पॉलिसीज और स्पष्ट `--custom` फाइल सह-अस्तित्व में रह सकते हैं। लोड क्रम: +परंपरा पॉलिसीज़ और स्पष्ट `--custom` फ़ाइलें सह-अस्तित्व में हो सकती हैं। लोड क्रम: -1. स्पष्ट `customPoliciesPath` फाइल (यदि कॉन्फ़िगर की गई हो) -2. प्रोजेक्ट सम्मेलन फाइलें (`{cwd}/.failproofai/policies/`, वर्णानुक्रम) -3. यूजर सम्मेलन फाइलें (`~/.failproofai/policies/`, वर्णानुक्रम) +1. स्पष्ट `customPoliciesPaths` फ़ाइलें (कॉन्फ़िगर किए गए क्रम में) +2. परियोजना परंपरा फ़ाइलें (`{cwd}/.failproofai/policies/`, वर्णक्रम) +3. उपयोगकर्ता परंपरा फ़ाइलें (`~/.failproofai/policies/`, वर्णक्रम) --- @@ -98,45 +103,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -एक पॉलिसी को रजिस्टर करता है। एक ही फाइल में कई पॉलिसीज के लिए जितनी बार चाहें इसे कॉल करें। +एक पॉलिसी को पंजीकृत करता है। एक ही फ़ाइल में कई पॉलिसीज़ के लिए आवश्यकतानुसार कई बार कॉल करें। ```ts customPolicies.add({ - name: string; // आवश्यक - अद्वितीय पहचानकर्ता - description?: string; // `failproofai policies` आउटपुट में दिखाया गया - match?: { events?: HookEventType[] }; // ईवेंट प्रकार द्वारा फ़िल्टर करें; सभी से मेल खाने के लिए छोड़ दें + name: string; // required - unique identifier + description?: string; // shown in `failproofai policies` output + match?: { events?: HookEventType[] }; // filter by event type; omit to match all fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` ### निर्णय सहायक -| फंक्शन | प्रभाव | कब उपयोग करें | +| फ़ंक्शन | प्रभाव | कब उपयोग करें | |----------|--------|----------| -| `allow()` | संचालन को मौन रूप से अनुमति दें | क्रिया सुरक्षित है, कोई संदेश आवश्यक नहीं | -| `deny(message)` | संचालन को ब्लॉक करें | एजेंट को यह क्रिया नहीं लेनी चाहिए | -| `instruct(message)` | ब्लॉक किए बिना संदर्भ जोड़ें | एजेंट को ट्रैक पर रहने के लिए अतिरिक्त संदर्भ दें | +| `allow()` | संचालन को चुप रहकर अनुमति दें | कार्रवाई सुरक्षित है, कोई संदेश की आवश्यकता नहीं | +| `deny(message)` | संचालन को ब्लॉक करें | एजेंट को यह कार्रवाई नहीं करनी चाहिए | +| `instruct(message)` | बिना ब्लॉक किए संदर्भ जोड़ें | एजेंट को track पर रहने के लिए अतिरिक्त संदर्भ दें | -`deny(message)` - संदेश Claude को `"Blocked by failproofai:"` प्रीफिक्स के साथ प्रकट होता है। एक एकल `deny` सभी आगे के मूल्यांकन को शॉर्ट-सर्किट करता है। +`deny(message)` - संदेश Claude के सामने `"Blocked by failproofai:"` prefix के साथ दिखाई देता है। एक एकल `deny` सभी आगे के मूल्यांकन को short-circuit करता है। -`instruct(message)` - संदेश वर्तमान टूल कॉल के लिए Claude के संदर्भ में जोड़ा जाता है। सभी `instruct` संदेश जमा किए जाते हैं और एक साथ दिए जाते हैं। +`instruct(message)` - संदेश वर्तमान tool call के लिए Claude के संदर्भ में जोड़ा जाता है। सभी `instruct` संदेश जमा किए जाते हैं और एक साथ दिए जाते हैं। -आप `policyParams` में एक `hint` फील्ड जोड़कर किसी भी `deny` या `instruct` संदेश को अतिरिक्त मार्गदर्शन जोड़ सकते हैं — कोई कोड परिवर्तन आवश्यक नहीं है। यह कस्टम (`custom/`), प्रोजेक्ट सम्मेलन (`.failproofai-project/`), और यूजर सम्मेलन (`.failproofai-user/`) पॉलिसीज के लिए भी काम करता है। विवरण के लिए [कॉन्फ़िगरेशन → hint](/hi/configuration#hint-cross-cutting) देखें। +आप `policyParams` में `hint` फ़ील्ड जोड़कर किसी भी `deny` या `instruct` संदेश में अतिरिक्त मार्गदर्शन जोड़ सकते हैं — कोई code परिवर्तन की आवश्यकता नहीं है। यह custom (`custom/`), परियोजना परंपरा (`.failproofai-project/`), और उपयोगकर्ता परंपरा (`.failproofai-user/`) पॉलिसीज़ के लिए भी काम करता है। विवरण के लिए [Configuration → hint](/hi/configuration#hint-cross-cutting) देखें। -### सूचनात्मक allow संदेश +### जानकारीपूर्ण allow संदेश -`allow(message)` संचालन की अनुमति देता है **और** Claude को एक सूचनात्मक संदेश वापस भेजता है। संदेश हुक हैंडलर के stdout प्रतिक्रिया में `additionalContext` के रूप में दिया जाता है — `instruct` द्वारा उपयोग की जाने वाली समान तंत्र, लेकिन शब्दार्थ में भिन्न: यह एक चेतावनी नहीं, बल्कि एक स्थिति अपडेट है। +`allow(message)` संचालन को **और** Claude को एक जानकारीपूर्ण संदेश वापस भेजता है। संदेश को hook हैंडलर के stdout response में `additionalContext` के रूप में दिया जाता है — `instruct` द्वारा उपयोग की जाने वाली समान mechanism, लेकिन semantically अलग: यह एक चेतावनी नहीं है, एक status update है। -| फंक्शन | प्रभाव | कब उपयोग करें | +| फ़ंक्शन | प्रभाव | कब उपयोग करें | |----------|--------|----------| -| `allow(message)` | अनुमति दें और Claude को संदर्भ भेजें | एक जांच पास होने की पुष्टि करें, या समझाएं कि एक जांच क्यों छोड़ी गई | +| `allow(message)` | अनुमति दें और Claude को संदर्भ भेजें | जांच पास होने की पुष्टि करें, या बताएं कि जांच क्यों छोड़ दी गई | उपयोग के मामले: -- **स्थिति पुष्टिकरण:** `allow("All CI checks passed.")` — Claude को बताता है कि सब कुछ हरा है -- **फेल-ओपन स्पष्टीकरण:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude को बताता है कि एक जांच क्यों छोड़ी गई ताकि इसे पूरा संदर्भ हो -- **कई संदेश जमा होते हैं:** यदि कई पॉलिसीज प्रत्येक `allow(message)` लौटाती हैं, सभी संदेश नई लाइनों के साथ जुड़ते हैं और एक साथ दिए जाते हैं +- **स्थिति पुष्टि:** `allow("All CI checks passed.")` — Claude को बताएं कि सब कुछ ठीक है +- **Fail-open व्याख्याएं:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude को बताएं कि जांच क्यों छोड़ दी गई ताकि इसे पूरा संदर्भ मिले +- **कई संदेश जमा होते हैं:** यदि कई पॉलिसीज़ प्रत्येक `allow(message)` लौटाती हैं, तो सभी संदेश newlines के साथ जुड़ते हैं और एक साथ दिए जाते हैं ```js customPolicies.add({ @@ -146,7 +151,7 @@ customPolicies.add({ const cwd = ctx.session?.cwd; if (!cwd) return allow("No working directory, skipping branch check."); - // ... शाखा स्थिति की जांच करें ... + // ... check branch status ... if (allPushed) { return allow("Branch is up to date with remote."); } @@ -155,53 +160,53 @@ customPolicies.add({ }); ``` -### `PolicyContext` फील्ड्स +### `PolicyContext` फ़ील्ड -| फील्ड | प्रकार | विवरण | +| फ़ील्ड | प्रकार | विवरण | |-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | कॉल किया जा रहा टूल (जैसे `"Bash"`, `"Write"`, `"Read"`) | -| `toolInput` | `Record \| undefined` | टूल के इनपुट पैरामीटर | -| `payload` | `Record` | Claude Code से पूरा कच्चा ईवेंट पेलोड | -| `session` | `SessionMetadata \| undefined` | सेशन संदर्भ (नीचे देखें) | +| `toolName` | `string \| undefined` | जिस tool को कॉल किया जा रहा है (जैसे `"Bash"`, `"Write"`, `"Read"`) | +| `toolInput` | `Record \| undefined` | tool के input parameters | +| `payload` | `Record` | Claude Code से पूर्ण raw event payload | +| `session` | `SessionMetadata \| undefined` | सत्र संदर्भ (नीचे देखें) | -### `SessionMetadata` फील्ड्स +### `SessionMetadata` फ़ील्ड -| फील्ड | प्रकार | विवरण | +| फ़ील्ड | प्रकार | विवरण | |-------|------|-------------| -| `sessionId` | `string` | Claude Code सेशन पहचानकर्ता | -| `cwd` | `string` | Claude Code सेशन की कार्य निर्देशिका | -| `transcriptPath` | `string` | सेशन की JSONL ट्रांसक्रिप्ट फाइल का पाथ | +| `sessionId` | `string` | Claude Code सत्र identifier | +| `cwd` | `string` | Claude Code सत्र की working directory | +| `transcriptPath` | `string` | सत्र की JSONL transcript फ़ाइल का पथ | -### ईवेंट प्रकार +### Event प्रकार -| ईवेंट | कब फायर होता है | `toolInput` सामग्री | +| Event | कब यह fires होता है | `toolInput` contents | |-------|--------------|----------------------| -| `PreToolUse` | Claude से पहले एक टूल चलाता है | टूल का इनपुट (जैसे Bash के लिए `{ command: "..." }`) | -| `PostToolUse` | एक टूल पूरा होने के बाद | टूल का इनपुट + `tool_result` (आउटपुट) | -| `Notification` | जब Claude एक नोटिफिकेशन भेजता है | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - हुक्स को हमेशा `allow()` लौटाना चाहिए, वे नोटिफिकेशन को ब्लॉक नहीं कर सकते | -| `Stop` | जब Claude सेशन समाप्त होता है | खाली | +| `PreToolUse` | इससे पहले Claude एक tool चलाता है | tool का input (जैसे Bash के लिए `{ command: "..." }`) | +| `PostToolUse` | tool पूरा होने के बाद | tool का input + `tool_result` (output) | +| `Notification` | जब Claude एक notification भेजता है | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks हमेशा `allow()` लौटाना चाहिए, वे notifications को block नहीं कर सकते | +| `Stop` | जब Claude सत्र समाप्त होता है | खाली | --- ## मूल्यांकन क्रम -पॉलिसीज को इस क्रम में मूल्यांकन किया जाता है: +पॉलिसीज़ का मूल्यांकन इस क्रम में किया जाता है: -1. बिल्ट-इन पॉलिसीज (परिभाषा क्रम में) -2. `customPoliciesPath` से स्पष्ट कस्टम पॉलिसीज (`.add()` क्रम में) -3. प्रोजेक्ट `.failproofai/policies/` से सम्मेलन पॉलिसीज (फाइलें वर्णानुक्रम में, `.add()` क्रम में) -4. यूजर `~/.failproofai/policies/` से सम्मेलन पॉलिसीज (फाइलें वर्णानुक्रम में, `.add()` क्रम में) +1. Built-in पॉलिसीज़ (परिभाषा क्रम में) +2. `customPoliciesPath` से स्पष्ट कस्टम पॉलिसीज़ (`.add()` क्रम में) +3. परियोजना `.failproofai/policies/` से परंपरा पॉलिसीज़ (फ़ाइलें वर्णक्रम, उसके भीतर `.add()` क्रम) +4. उपयोगकर्ता `~/.failproofai/policies/` से परंपरा पॉलिसीज़ (फ़ाइलें वर्णक्रम, उसके भीतर `.add()` क्रम) -पहला `deny` सभी बाद की पॉलिसीज को शॉर्ट-सर्किट करता है। सभी `instruct` संदेश जमा किए जाते हैं और एक साथ दिए जाते हैं। +पहला `deny` सभी बाद की पॉलिसीज़ को short-circuit करता है। सभी `instruct` संदेश जमा किए जाते हैं और एक साथ दिए जाते हैं। --- -## ट्रांजिटिव आयात +## Transitive आयात -कस्टम पॉलिसी फाइलें सापेक्ष पाथों का उपयोग करके स्थानीय मॉड्यूल को आयात कर सकती हैं: +कस्टम पॉलिसी फ़ाइलें relative paths का उपयोग करके स्थानीय मॉड्यूल आयात कर सकती हैं: ```js // my-policies.js @@ -218,46 +223,46 @@ customPolicies.add({ }); ``` -प्रविष्टि फाइल से पहुंचने योग्य सभी सापेक्ष आयात समाधान किए जाते हैं। यह `failproofai` आयातों को वास्तविक dist पाथ में फिर से लिखकर और ESM संगतता सुनिश्चित करने के लिए अस्थायी `.mjs` फाइलें बनाकर लागू किया जाता है। +entry file से पहुंचने योग्य सभी relative imports को हल किया जाता है। यह `from "failproofai"` imports को actual dist path में rewrite करके और ESM compatibility सुनिश्चित करने के लिए temporary `.mjs` फ़ाइलें बनाकर लागू किया जाता है। --- -## ईवेंट प्रकार फ़िल्टरिंग +## Event प्रकार filtering -यह सीमित करने के लिए `match.events` का उपयोग करें कि पॉलिसी कब फायर होती है: +`match.events` का उपयोग करके सीमित करें कि कब कोई पॉलिसी fires होती है: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // केवल तब फायर होता है जब सेशन समाप्त होता है - // ctx.session.transcriptPath में पूर्ण सेशन लॉग होता है + // केवल तब fires होता है जब सत्र समाप्त होता है + // ctx.session.transcriptPath में पूर्ण सत्र log होता है return allow(); }, }); ``` -सभी ईवेंट प्रकारों पर फायर करने के लिए `match` को पूरी तरह छोड़ दें। +हर event प्रकार पर fire करने के लिए `match` को पूरी तरह से छोड़ दें। --- -## त्रुटि हैंडलिंग और विफलता मोड +## Error handling और failure मोड -कस्टम पॉलिसीज **फेल-ओपन** हैं: त्रुटियां कभी भी बिल्ट-इन पॉलिसीज को ब्लॉक नहीं करती या हुक हैंडलर को क्रैश नहीं करती हैं। +कस्टम पॉलिसीज़ **fail-open** हैं: errors कभी built-in पॉलिसीज़ को block नहीं करते या hook हैंडलर को crash नहीं करते। | विफलता | व्यवहार | |---------|----------| -| `customPoliciesPath` सेट नहीं है | कोई स्पष्ट कस्टम पॉलिसीज नहीं चलती; सम्मेलन पॉलिसीज और बिल्ट-इन सामान्य रूप से जारी रहते हैं | -| फाइल नहीं मिली | चेतावनी `~/.failproofai/hook.log` में लॉग की जाती है; बिल्ट-इन जारी रहते हैं | -| सिंटैक्स/आयात त्रुटि (स्पष्ट) | त्रुटि `~/.failproofai/hook.log` में लॉग की जाती है; स्पष्ट कस्टम पॉलिसीज छोड़ दी जाती हैं | -| सिंटैक्स/आयात त्रुटि (सम्मेलन) | त्रुटि लॉग की जाती है; वह फाइल छोड़ दी जाती है, अन्य सम्मेलन फाइलें अभी भी लोड होती हैं | -| `fn` रनटाइम पर थ्रो करता है | त्रुटि लॉग की जाती है; वह हुक `allow` के रूप में माना जाता है; अन्य हुक्स जारी रहते हैं | -| `fn` 10 सेकंड से अधिक समय लेता है | समय समाप्त लॉग किया जाता है; `allow` के रूप में माना जाता है | -| सम्मेलन डायरेक्ट्री गायब है | कोई सम्मेलन पॉलिसीज नहीं चलती; कोई त्रुटि नहीं | +| `customPoliciesPath` सेट नहीं है | कोई स्पष्ट कस्टम पॉलिसीज़ नहीं चलती; परंपरा पॉलिसीज़ और built-ins सामान्य रूप से जारी रहते हैं | +| फ़ाइल नहीं मिली | `~/.failproofai/hook.log` में चेतावनी log की जाती है; built-ins जारी रहते हैं | +| Syntax/import error (explicit) | `~/.failproofai/hook.log` में error log किया जाता है; स्पष्ट कस्टम पॉलिसीज़ छोड़ दी जाती हैं | +| Syntax/import error (convention) | Error log किया जाता है; वह फ़ाइल छोड़ दी जाती है, अन्य परंपरा फ़ाइलें अभी भी लोड होती हैं | +| `fn` runtime पर throws करता है | Error log किया जाता है; वह hook `allow` के रूप में माना जाता है; अन्य hooks जारी रहते हैं | +| `fn` 10s से अधिक समय लेता है | Timeout log किया जाता है; `allow` के रूप में माना जाता है | +| परंपरा directory missing है | कोई परंपरा पॉलिसीज़ नहीं चलती; कोई error नहीं | -कस्टम पॉलिसी त्रुटियों को डीबग करने के लिए, लॉग फाइल को देखें: +कस्टम पॉलिसी errors को debug करने के लिए, log फ़ाइल को watch करें: ```bash tail -f ~/.failproofai/hook.log @@ -266,13 +271,13 @@ tail -f ~/.failproofai/hook.log --- -## पूर्ण उदाहरण: कई पॉलिसीज +## पूर्ण उदाहरण: कई पॉलिसीज़ ```js // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// एजेंट को secrets/ डायरेक्ट्री में लिखने से रोकें +// एजेंट को secrets/ directory में लिखने से रोकें customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -285,7 +290,7 @@ customPolicies.add({ }, }); -// एजेंट को ट्रैक पर रखें: कमिट करने से पहले टेस्ट सत्यापित करें +// एजेंट को track पर रखें: commit करने से पहले tests को verify करें customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +305,7 @@ customPolicies.add({ }, }); -// फ्रीज अवधि के दौरान अनियोजित निर्भरता परिवर्तनों को रोकें +// freeze period के दौरान अनियोजित dependency changes को रोकें customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -323,31 +328,31 @@ export { customPolicies }; ## उदाहरण -`examples/` डायरेक्ट्री में तैयार-से-चलाने योग्य पॉलिसी फाइलें हैं: +`examples/` directory में तैयार-चलाने योग्य पॉलिसी फ़ाइलें हैं: -| फाइल | सामग्री | +| फ़ाइल | सामग्री | |------|----------| -| `examples/policies-basic.js` | पांच स्टार्टर पॉलिसीज जो सामान्य एजेंट विफलता मोड्स को कवर करती हैं | -| `examples/policies-advanced/index.js` | उन्नत पैटर्न: ट्रांजिटिव आयात, async कॉल्स, आउटपुट स्क्रबिंग, और सेशन-एंड हुक्स | -| `examples/convention-policies/security-policies.mjs` | सम्मेलन-आधारित सुरक्षा पॉलिसीज (.env लेखन को ब्लॉक करें, git इतिहास पुनर्लेखन को रोकें) | -| `examples/convention-policies/workflow-policies.mjs` | सम्मेलन-आधारित वर्कफ़्लो पॉलिसीज (टेस्ट रिमाइंडर, ऑडिट फाइल लेखन) | +| `examples/policies-basic.js` | पाँच starter पॉलिसीज़ जो सामान्य एजेंट विफलता मोड को cover करती हैं | +| `examples/policies-advanced/index.js` | उन्नत patterns: transitive imports, async calls, output scrubbing, और session-end hooks | +| `examples/convention-policies/security-policies.mjs` | परंपरा-आधारित सुरक्षा पॉलिसीज़ (.env writes को block करें, git history rewriting को रोकें) | +| `examples/convention-policies/workflow-policies.mjs` | परंपरा-आधारित workflow पॉलिसीज़ (test reminders, audit file writes) | -### स्पष्ट फाइल उदाहरणों का उपयोग +### स्पष्ट फ़ाइल उदाहरण का उपयोग करना ```bash failproofai policies --install --custom ./examples/policies-basic.js ``` -### सम्मेलन-आधारित उदाहरणों का उपयोग +### परंपरा-आधारित उदाहरण का उपयोग करना ```bash -# प्रोजेक्ट स्तर पर कॉपी करें +# परियोजना स्तर पर कॉपी करें mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# या यूजर स्तर पर कॉपी करें +# या उपयोगकर्ता स्तर पर कॉपी करें mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -कोई इंस्टॉल कमांड आवश्यक नहीं है — फाइलें अगले हुक ईवेंट पर स्वचालित रूप से उठाई जाती हैं। \ No newline at end of file +कोई install command की आवश्यकता नहीं — फ़ाइलें अगली hook event पर स्वचालित रूप से pick up की जाती हैं। \ No newline at end of file diff --git a/docs/hi/dashboard.mdx b/docs/hi/dashboard.mdx index dbc60f2f..ba77c793 100644 --- a/docs/hi/dashboard.mdx +++ b/docs/hi/dashboard.mdx @@ -1,10 +1,10 @@ --- title: डैशबोर्ड -description: "एजेंट सेशन की निगरानी करें, टूल कॉल की समीक्षा करें, और नीतियों का प्रबंधन करें" +description: "एजेंट सेशन मॉनिटर करें, टूल कॉल्स की समीक्षा करें, और नीतियों को प्रबंधित करें" icon: chart-line --- -failproofai डैशबोर्ड आपके AI एजेंट सेशन की निगरानी करने और नीतियों का प्रबंधन करने के लिए एक स्थानीय वेब एप्लिकेशन है। देखें कि आपके एजेंट आपके दूर रहते हुए क्या करते थे। +failproofai डैशबोर्ड आपके AI एजेंट सेशन को मॉनिटर करने और नीतियों को प्रबंधित करने के लिए एक स्थानीय वेब एप्लिकेशन है। देखें कि आपके एजेंट आपके दूर रहते हुए क्या करते थे। --- @@ -16,101 +16,103 @@ failproofai `http://localhost:8020` पर खुलता है। -डैशबोर्ड स्थानीय प्रोजेक्ट, सेशन, और failproofai कॉन्फ़िगरेशन डेटा सीधे फाइलसिस्टम से पढ़ता है। वैकल्पिक प्रमाणित सुविधाएं, जैसे ऑडिट रिमाइंडर और आमंत्रण, इन अनुरोधों के लिए आवश्यक जानकारी (ईमेल पते सहित) को दूरस्थ API को भेजते हैं। +डैशबोर्ड स्थानीय प्रोजेक्ट, सेशन, और failproofai कॉन्फ़िगरेशन डेटा को सीधे फ़ाइल सिस्टम से पढ़ता है। वैकल्पिक प्रमाणित विशेषताएं, जैसे ऑडिट रिमाइंडर और आमंत्रण, दूरस्थ API को आवश्यक जानकारी (ईमेल पते सहित) भेजते हैं। --- ## पृष्ठ -### प्रोजेक्ट्स +### प्रोजेक्ट -आपकी मशीन पर मिले सभी Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, और Goose प्रोजेक्ट्स को सूचीबद्ध करता है। Claude प्रोजेक्ट्स `~/.claude/projects/` से खोजे जाते हैं (या `CLAUDE_PROJECTS_PATH` द्वारा सेट किए गए पथ से); Codex प्रोजेक्ट्स `~/.codex/sessions///
/*.jsonl` के तहत हर ट्रांसक्रिप्ट को स्कैन करके और प्रत्येक सेशन के पहले रिकॉर्ड में दर्ज `cwd` के आधार पर समूहित करके खोजे जाते हैं; Copilot CLI प्रोजेक्ट्स प्रत्येक `~/.copilot/session-state//workspace.yaml` को स्कैन करके (`COPILOT_HOME` के माध्यम से कॉन्फ़िगरेबल) और इसके `cwd` फील्ड के आधार पर समूहित करके खोजे जाते हैं; Cursor Agent प्रोजेक्ट्स `~/.cursor/agent-sessions//` के तहत प्रति-सेशन मेटाडेटा को स्कैन करके (`CURSOR_HOME` के माध्यम से कॉन्फ़िगरेबल, `conversations/` और `sessions/` को फॉलबैक के रूप में जांचा जाता है) `meta.json` / `session.json` / `workspace.yaml` में `cwd` स्केलर के लिए खोजे जाते हैं; OpenCode प्रोजेक्ट्स `~/.local/share/opencode/opencode.db` पर इसके SQLite DB को `opencode db --format json` के माध्यम से क्वेरी करके खोजे जाते हैं (`session` और `project` टेबल पढ़ते हैं और `project_id` के आधार पर समूहित करते हैं); Pi प्रोजेक्ट्स `~/.pi/agent/sessions//_.jsonl` के तहत प्रति-सेशन JSONL ट्रांसक्रिप्ट को स्कैन करके (`PI_SESSIONS_DIR` के माध्यम से कॉन्फ़िगरेबल) और प्रत्येक सेशन के पहले रिकॉर्ड से `cwd` खींचकर खोजे जाते हैं; Hermes गेटवे सेशन सीधे `~/.hermes/state.db` पर इसके SQLite स्टोर से पढ़े जाते हैं (`HERMES_DB_PATH` के माध्यम से कॉन्फ़िगरेबल) और `source` (Slack/Telegram/cli/cron) के आधार पर `hermes-` प्रोजेक्ट्स में समूहित किए जाते हैं — गेटवे सेशन में कोई cwd नहीं होता; OpenClaw गेटवे सेशन `~/.openclaw/agents//sessions/*.jsonl` से पढ़े जाते हैं और `openclaw-` प्रोजेक्ट्स में समूहित किए जाते हैं (cwd के बिना भी); Factory Droid प्रोजेक्ट्स `~/.factory/sessions//*.jsonl` पर JSONL ट्रांसक्रिप्ट से खोजे जाते हैं और cwd के आधार पर समूहित किए जाते हैं; Devin प्रोजेक्ट्स `~/.local/share/devin/cli/sessions.db` पर इसके SQLite DB से (प्रत्येक सेशन के `working_directory` के आधार पर समूहित); Antigravity प्रोजेक्ट्स `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` पर JSONL ट्रांसक्रिप्ट से और cwd के आधार पर समूहित; और Goose प्रोजेक्ट्स `~/.local/share/goose/sessions/sessions.db` पर इसके SQLite DB से (प्रत्येक सेशन के `working_dir` के आधार पर समूहित)। एक प्रोजेक्ट जिसे कई CLI द्वारा उपयोग किया गया है वह सभी मेलिंग बैज के साथ एक एकल पंक्ति के रूप में प्रस्तुत होता है। तालिका के ऊपर **CLI** ड्रॉपडाउन का उपयोग करके एक विशिष्ट एजेंट CLI द्वारा फ़िल्टर करें; URL आपकी पसंद को `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` के रूप में संरक्षित करता है। +आपकी मशीन पर पाए गए सभी Claude Code, OpenAI Codex, GitHub Copilot CLI _(बीटा)_, Cursor Agent _(बीटा)_, OpenCode _(बीटा)_, Pi _(बीटा)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, और Goose प्रोजेक्ट्स को सूचीबद्ध करता है। Claude प्रोजेक्ट्स `~/.claude/projects/` से खोजे जाते हैं (या `CLAUDE_PROJECTS_PATH` द्वारा निर्धारित पथ); Codex प्रोजेक्ट्स `~/.codex/sessions///
/*.jsonl` के तहत प्रत्येक ट्रांसक्रिप्ट को स्कैन करके और प्रत्येक सेशन के पहले रिकॉर्ड में दर्ज `cwd` द्वारा समूहीकृत करके खोजे जाते हैं; Copilot CLI प्रोजेक्ट्स प्रत्येक `~/.copilot/session-state//workspace.yaml` को स्कैन करके (`COPILOT_HOME` के माध्यम से कॉन्फ़िगर करने योग्य) और इसके `cwd` फील्ड द्वारा समूहीकृत करके खोजे जाते हैं; Cursor Agent प्रोजेक्ट्स `~/.cursor/agent-sessions//` के तहत प्रति-सेशन मेटाडेटा को स्कैन करके (`CURSOR_HOME` के माध्यम से कॉन्फ़िगर करने योग्य, `conversations/` और `sessions/` को फॉलबैक के रूप में जांचते हुए) `meta.json` / `session.json` / `workspace.yaml` में `cwd` स्केलर के लिए खोजे जाते हैं; OpenCode प्रोजेक्ट्स `~/.local/share/opencode/opencode.db` पर इसके SQLite DB को क्वेरी करके (`opencode db --format json` के माध्यम से) खोजे जाते हैं (हम `session` और `project` तालिकाओं को पढ़ते हैं और `project_id` द्वारा समूहीकृत करते हैं); Pi प्रोजेक्ट्स `~/.pi/agent/sessions//_.jsonl` के तहत प्रति-सेशन JSONL ट्रांसक्रिप्ट को स्कैन करके (`PI_SESSIONS_DIR` के माध्यम से कॉन्फ़िगर करने योग्य) और प्रत्येक सेशन के पहले रिकॉर्ड से `cwd` खींचकर खोजे जाते हैं; Hermes गेटवे सेशन्स सीधे हर प्रोफाइल के SQLite स्टोर से पढ़े जाते हैं — `~/.hermes/state.db` प्लस `~/.hermes/profiles//state.db` (`HERMES_HOME` के माध्यम से ओवाराइड करने योग्य, या एकल डेटाबेस के लिए `HERMES_DB_PATH`) — और `hermes--` प्रोजेक्ट्स में प्रोफाइल और `source` (Slack/Telegram/cli/cron — गेटवे सेशन्स के पास कोई cwd नहीं) द्वारा समूहीकृत किए जाते हैं; OpenClaw गेटवे सेशन्स `~/.openclaw/agents//sessions/*.jsonl` से पढ़े जाते हैं और `openclaw--` प्रोजेक्ट्स में एजेंट और चैनल द्वारा समूहीकृत किए जाते हैं (यह भी cwd-रहित); Factory Droid प्रोजेक्ट्स `~/.factory/sessions//*.jsonl` पर JSONL ट्रांसक्रिप्ट्स से खोजे जाते हैं और cwd द्वारा समूहीकृत किए जाते हैं; Devin प्रोजेक्ट्स इसके SQLite DB से `~/.local/share/devin/cli/sessions.db` (प्रत्येक सेशन के `working_directory` द्वारा समूहीकृत); Antigravity प्रोजेक्ट्स `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` पर JSONL ट्रांसक्रिप्ट्स से और cwd द्वारा समूहीकृत; और Goose प्रोजेक्ट्स इसके SQLite DB से `~/.local/share/goose/sessions/sessions.db` (प्रत्येक सेशन के `working_dir` द्वारा समूहीकृत)। एक प्रोजेक्ट जिसका उपयोग कई CLI द्वारा किया गया है, सभी मिलान करने वाले बैज के साथ एक एकल पंक्ति के रूप में प्रदर्शित होता है। किसी विशेष एजेंट CLI द्वारा फ़िल्टर करने के लिए तालिका के ऊपर **CLI** ड्रॉपडाउन का उपयोग करें; URL आपकी पसंद को `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` के रूप में संरक्षित करता है। + +Hermes और OpenClaw उपयोगकर्ता-स्कोप्ड हैं और समूहीकृत करने के लिए कोई कार्यशील निर्देशिका नहीं है, इसलिए वे **संक्षिप्त फ़ोल्डर ट्री** के रूप में प्रदर्शित होते हैं — शीर्ष स्तर पर प्रोफाइल (या एजेंट), इसके नीचे चैनल्स — जबकि हर cwd-आधारित CLI एक सपाट पंक्ति रहती है। फ़ोल्डर पंक्तियां उनके नीचे की हर चीज के सेशन काउंट और सबसे हाल की गतिविधि को समेकित करती हैं, संक्षिप्त फ़ोल्डर विज़िट्स के बीच याद रखे जाते हैं, और कीवर्ड खोज जो कुछ भी मेल खाती है उसे विस्तारित करती है। प्रत्येक प्रोजेक्ट दिखाता है: -- प्रोजेक्ट नाम (फोल्डर पथ से व्युत्पन्न) -- एक CLI बैज — `Claude Code` (नारंगी), `OpenAI Codex` (बैंगनी), `GitHub Copilot` (नीला), `Cursor Agent` (पन्ना हरा), `OpenCode` (एम्बर), `Pi` (गुलाबी), और/या `Hermes` (गहरा नीला) -- सबसे हाल के सेशन गतिविधि की तारीख +- प्रोजेक्ट का नाम (फ़ोल्डर पथ से व्युत्पन्न) +- एक CLI बैज — `Claude Code` (नारंगी), `OpenAI Codex` (बैंगनी), `GitHub Copilot` (नीला), `Cursor Agent` (पन्ना), `OpenCode` (एम्बर), `Pi` (गुलाबी), और/या `Hermes` (इंडिगो) +- सबसे हाल की सेशन गतिविधि की तारीख -एक प्रोजेक्ट पर क्लिक करके इसके सेशन देखें। +सेशन देखने के लिए किसी प्रोजेक्ट पर क्लिक करें। -### सेशन +### सेशन्स -एक प्रोजेक्ट के भीतर सभी सेशन को सूचीबद्ध करता है। प्रत्येक सेशन दिखाता है: +किसी प्रोजेक्ट के भीतर सभी सेशन्स को सूचीबद्ध करता है। प्रत्येक सेशन दिखाता है: - सेशन ID -- शुरुआत और समाप्त समय -- टूल कॉल की संख्या -- हुक गतिविधि की गणना (नीतियां जो फायर हुईं) +- शुरुआत और समाप्ति टाइमस्टैम्प +- टूल कॉल्स की संख्या +- हुक गतिविधि गणना (नीतियां जो चलीं) -तारीख की सीमा फ़िल्टर और सेशन ID खोज का उपयोग करके सूची को संकुचित करें। सेशन पृष्ठाकृत हैं। +सूची को संकीर्ण करने के लिए तारीख श्रेणी फ़िल्टर और सेशन ID खोज का उपयोग करें। सेशन्स पेजिनेटेड हैं। -एक सेशन पर क्लिक करके सेशन व्यूअर खोलें। +सेशन दर्शक को खोलने के लिए किसी सेशन पर क्लिक करें। -### सेशन व्यूअर +### सेशन दर्शक -सेशन व्यूअर स्वायत्त एजेंट के लिए मुख्य प्रश्न का उत्तर देता है: एजेंट ने क्या किया, और क्या यह ट्रैक पर रहा? हेडर के बगल में एक CLI बैज इंगित करता है कि सेशन एक Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, या Goose ट्रांसक्रिप्ट है। यह एक सेशन में हुई हर चीज की एक समयरेखा दिखाता है: +सेशन दर्शक स्वायत्त एजेंट्स के लिए मुख्य प्रश्न का उत्तर देता है: एजेंट ने क्या किया, और क्या यह ट्रैक पर रहा? हेडर के बगल में एक CLI बैज यह दर्शाता है कि सेशन Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, या Goose ट्रांसक्रिप्ट है। यह एक सेशन में हुई हर चीज की एक समयरेखा दिखाता है: -- **संदेश** - Claude के पाठ प्रतिक्रियाएं और उपयोगकर्ता प्रॉम्प्ट -- **टूल कॉल** - प्रत्येक टूल जो Claude ने आह्वान किया, इसके इनपुट और आउटपुट के साथ -- **नीति गतिविधि** - प्रत्येक टूल कॉल के लिए, कौन सी नीतियां फायर हुईं और उन्होंने क्या निर्णय लौटाया +- **संदेश** - Claude के पाठ प्रतिक्रियाएं और उपयोगकर्ता संकेत +- **टूल कॉल्स** - हर टूल जो Claude ने शामिल किया, इसके इनपुट और आउटपुट के साथ +- **नीति गतिविधि** - प्रत्येक टूल कॉल के लिए, कौन सी नीतियां चलीं और उन्होंने क्या निर्णय दिया -शीर्ष पर स्टैट्स बार सेशन अवधि, कुल टूल कॉल, और हुक निर्णयों का सारांश (allow / deny / instruct गणना) दिखाता है। +शीर्ष पर स्टैट्स बार सेशन की अवधि, कुल टूल कॉल्स, और हुक निर्णयों (allow / deny / instruct गणना) का सारांश दिखाता है। -**Download Logs** बटन पर क्लिक करके सेशन को निर्यात करें। Claude Code, Codex, Copilot, Cursor, और Pi सेशन के लिए आप मूल ऑन-डिस्क JSONL ट्रांसक्रिप्ट बाइट-के-लिए-बाइट प्राप्त करते हैं; OpenCode के लिए (जिसके सेशन SQLite में हैं, डिस्क पर नहीं) आप एक JSON दस्तावेज़ प्राप्त करते हैं जो अंतर्निहित `session` / `messages` / `parts` टेबल को प्रतिबिंबित करता है। +सेशन को निर्यात करने के लिए **लॉग डाउनलोड करें** बटन पर क्लिक करें। Claude Code, Codex, Copilot, Cursor, और Pi सेशन्स के लिए आप मूल ऑन-डिस्क JSONL ट्रांसक्रिप्ट बाइट-फॉर-बाइट प्राप्त करते हैं; OpenCode के लिए (जिसके सेशन्स SQLite में रहते हैं, डिस्क पर नहीं) आप अंतर्निहित `session` / `messages` / `parts` तालिकाओं को दर्पण करने वाला एक JSON दस्तावेज़ प्राप्त करते हैं। ### ऑडिट -आपके एजेंट के बारे में एक व्यक्तित्व-संचालित रिपोर्ट कि वह वास्तव में अतीत के सेशन में कैसा व्यवहार कर रहा है। `failproofai audit` CLI के समान स्कैन चलाता है लेकिन इसे एक एकल-स्क्रीन शेयरेबल पोस्टर + चार नीचे-द-फोल्ड सेक्शन के रूप में प्रस्तुत करता है: +एक व्यक्तित्व-संचालित रिपोर्ट कि आपके एजेंट ने पिछले सेशन्स में वास्तव में कैसे व्यवहार किया है। `failproofai audit` CLI के समान स्कैन चलाता है लेकिन इसे एक एकल-स्क्रीन साझा करने योग्य पोस्टर + चार नीचे-द-गुना अनुभागों के रूप में प्रदर्शित करता है: -1. **पोस्टर** — पहले व्यूपोर्ट को भरता है। failproof_ai शब्दचिह्न + ऑडिट लेबल के साथ स्व-निहित PNG-कैप्चर क्षेत्र · आर्कटाइप इंडेक्स (`№ NN of 08`) + ऑडिट तारीख · संख्यात्मक स्कोर (0–100) + प्रतिशत रैंक गोली (`top 15%`) · आर्कटाइप नाम (एक `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost` में से) + 3-कीवर्ड पट्टी · `// only N% of agents are this archetype` दुर्लभता पंक्ति · 8×8 पिक्सेल sigil टाइल · `audit yours → failproof.ai` फुटर। तीन शेयर बटन कैप्चर बॉक्स के बाहर बैठते हैं: `post your archetype` (X intent), `share on linkedin`, `download poster`। कैप्चर `html-to-image` के माध्यम से चलता है इसलिए PNG ऑन-स्क्रीन रेंडर पिक्सल-के-लिए-पिक्सल से मेल खाता है (डैश की गई सीमाएं, SVG लोगो मास्क, ग्रेडिएंट, फॉन्ट मेट्रिक्स — सभी संरक्षित)। -2. **शक्तियां** — शांत ✓ पंक्ति सूची आपके एजेंट के व्यवहार जो पहले से ही सही हैं, लाइव ऑडिट डेटा से व्युत्पन्न (स्वच्छ टूल-कॉल दर, मुख्य के लिए कोई सीधे पुश नहीं, शून्य क्रेडेंशियल लीक, शून्य रिट्राई तूफान) — प्रत्येक केवल तब सामने आया जब प्रासंगिक नीति में ऑडिट विंडो में स्वच्छ रिकॉर्ड होता है। -3. **Quirks** — सारणी कि क्या फिसल गया, गंभीरता के आधार पर रैंक किया गया: `when · what slipped + the policy that would've caught it · severity pill · seen`, जहां पुनरावृत्ति `new` (एक बार), `N× seen` (2–9 बार), या `recurring` (10+) को पढ़ता है। -4. **कैसे सुधारें** — शांत पंक्ति सूची, निर्धारित प्रत्येक नीति के लिए एक: नीति का नाम सफेद में, एक-पंक्ति विवरण, दाईं ओर स्थापन आदेश + कॉपी बटन। सेक्शन हेडर `enable all N → projected · ` को पढ़ता है (वह स्कोर जिस तक आप हर सुधार लागू करने के साथ पहुंचते हैं), और इसका `[install all]` बटन हर निर्धारित नीति के लिए संयुक्त `failproofai policy add a b c …` आदेश को कॉपी करता है। -5. **Come back better** — दो पक्ष-दर-पक्ष कार्ड। बाएं: एक रिमाइंडर सेट करें (`3d` / `7d` / `14d` / `30d` कैडेंस पिकर; `/api/auth/reminder` के माध्यम से प्रमाणित होने के बाद जारी रहता है)। दाएं: failproof सुविधाओं को अनलॉक करें — `invite a friend` एक मोडल खोलता है जो अल्पविराम/स्पेस/न्यूलाइन-अलग सूची को मित्र ईमेल (प्रति भेजे अधिकतम 10) लेता है, उन्हें `/api/audit/invite` को POST करता है, जो api-server के `POST /v0/invite` को अग्रेषित करता है। api-server `invite@failproof.ai` से प्रत्येक प्राप्तकर्ता को एक ईमेल भेजता है जिसमें प्रेषक Cc'd होता है और `Reply-To` सेट होता है, इसलिए प्राप्तकर्ता देखता है कि किसने उन्हें आमंत्रित किया और प्रेषक को उनके इनबॉक्स में एक प्रति मिलता है। गुमनाम उपयोगकर्ता `AuthDialog` के माध्यम से मार्ग किए जाते हैं ताकि आमंत्रण बाहर जाने से पहले प्रेषक की ईमेल ज्ञात हो। Entitlement / perks की पूर्ति एक अनुवर्ती है। +1. **पोस्टर** — पहले व्यूपोर्ट को भरता है। failproof_ai वर्डमार्क + ऑडिट लेबल के साथ स्व-निहित PNG-कैप्चर क्षेत्र · आर्कटाइप इंडेक्स (`№ NN of 08`) + ऑडिट तारीख · संख्यात्मक स्कोर (0–100) + प्रतिशतता रैंक गोली (`top 15%`) · आर्कटाइप का नाम (एक `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost` में से) + 3-कीवर्ड स्ट्रिप · `// only N% of agents are this archetype` दुर्लभता पंक्ति · 8×8 पिक्सल सिगिल टाइल · `audit yours → failproof.ai` फुटर। तीन शेयर बटन कैप्चर बॉक्स के बाहर बैठते हैं: `post your archetype` (X इरादा), `share on linkedin`, `download poster`। कैप्चर `html-to-image` के माध्यम से चलता है इसलिए PNG ऑन-स्क्रीन प्रदर्शन से पिक्सल-फॉर-पिक्सल मेल खाता है (डैश्ड बॉर्डर, SVG लोगो मास्क, ग्रेडिएंट्स, फॉन्ट मेट्रिक्स — सभी संरक्षित)। +2. **मजबूती** — शांत ✓ पंक्ति सूची आपके एजेंट के व्यवहार जो वह पहले से सही करता है, लाइव ऑडिट डेटा से व्युत्पन्न (स्वच्छ टूल-कॉल दर, कोई सीधा मुख्य को पुश नहीं, शून्य प्रमाण पत्र रिसाव, शून्य पुनः प्रयास तूफान) — प्रत्येक केवल तभी सामने आया जब प्रासंगिक नीति ऑडिट विंडो में एक स्वच्छ रिकॉर्ड हो। +3. **विलक्षणताएं** — गंभीरता द्वारा क्रम में क्या सरक गई की तालिका: `when · what slipped + the policy that would've caught it · severity pill · seen`, जहां पुनरावृत्ति `new` (एक बार), `N× seen` (2–9 बार), या `recurring` (10+) पढ़ता है। +4. **सुधार के लिए कैसे** — शांत पंक्ति सूची, निर्धारित नीति प्रति एक: नीति का नाम सफेद में, एक-पंक्ति विवरण, दाईं ओर कॉपी बटन के साथ इंस्टॉल कमांड। अनुभाग हेडर `enable all N → projected · ` (वह स्कोर आप हर सुधार लागू करने के साथ पहुंचेंगे) पढ़ता है, और इसका `[install all]` बटन हर निर्धारित नीति के लिए संयुक्त `failproofai policy add a b c …` कमांड की प्रतिलिपि बनाता है। +5. **बेहतर वापसी** — दो साइड-बाय-साइड कार्ड। बाएं: एक रिमाइंडर सेट करें (`3d` / `7d` / `14d` / `30d` कैडेंस पिकर; `/api/auth/reminder` के माध्यम से प्रमाणित होने पर जारी रहता है)। दाएं: failproof सुविधाएं अनलॉक करें — `invite a friend` एक मोडल खोलता है जो ईमेल पते की अल्पविराम/स्पेस/न्यूलाइन-विभाजित सूची लेता है (प्रति भेजना अधिकतम 10), उन्हें `/api/audit/invite` पर POST करता है, जो api-सर्वर के `POST /v0/invite` को अग्रेषित करता है। api-सर्वर `invite@failproof.ai` से प्रत्येक प्राप्तकर्ता को एक ईमेल भेजता है प्रेषक Cc'd और `Reply-To` सेट के साथ, इसलिए प्राप्तकर्ता देखता है कि किसने उन्हें आमंत्रित किया और प्रेषक को उनके इनबॉक्स में एक प्रति मिलती है। अनाम उपयोगकर्ता आमंत्रण से पहले प्रेषक का ईमेल ज्ञात हो सके इसके लिए `AuthDialog` के माध्यम से रूट किए जाते हैं। हक / सुविधा पूर्ति एक अनुवर्ती है। -`failproofai audit` रनटाइम द्वारा संचालित — अंतर्निहित स्कैन इंजन, समर्थित फ़्लैग, और प्रति-ट्रांसक्रिप्ट कैश अपरिवर्तनीयों के लिए [Audit CLI](/hi/cli/audit) देखें। डैशबोर्ड सबसे हाल के परिणाम को `~/.failproofai/audit-dashboard.json` पर कैश करता है (मोड `0600`, एकल स्लॉट, नए रन अधिलेखित करते हैं) ताकि पुनरावृत्तियां तत्काल हों; **पढ़ने पर एक बार 7 दिनों से पुराने होने के बाद प्रति-ट्रांसक्रिप्ट और पूरे-परिणाम दोनों कैश अस्वीकृत हैं** इसलिए डैशबोर्ड कभी भी एक सप्ताह-पुराने परिणाम को चुपचाप सेवा नहीं देता — TTL के पास `/audit` अपनी खाली स्थिति में गिरता है और एक ताज़ा रन का संकेत देता है। रिपोर्ट के नीचे `[ re-audit now ]` पर क्लिक करने से `/api/audit/run` को `noCache: true` के साथ POST करता है — पुनः-ऑडिट प्रति-ट्रांसक्रिप्ट कैश को बायपास करता है और हर ट्रांसक्रिप्ट को शुरुआत से फिर से स्कैन करता है बजाय कैश किए गए परिणाम को चुपचाप लौटाने के — और डैशबोर्ड 1Hz पर `/api/audit/status` को पोल करता है जब तक रन खत्म नहीं हो जाता; रन के दौरान एक स्टिकी गुलाबी प्रगति पट्टी व्यूपोर्ट के शीर्ष पर पिन करता है एक बीता हुआ टाइमर के साथ, और ताज़ा परिणाम सफलता पर जगह में स्वैप करता है (कोई पूर्ण-पृष्ठ पुनः लोड नहीं; एक विफल पुनः-ऑडिट पूर्व रिपोर्ट को बरकरार रखता है)। विफलता पर पट्टी `RerunError.kind` को बंद करके कॉपी के साथ लाल हो जाता है (`timeout` / `network` / `post_failed`)। खाली स्थिति (कोई कैश नहीं या समाप्त) और शून्य-सेशन स्थिति (कैश मौजूद है लेकिन स्कैन ने कोई ट्रांसक्रिप्ट नहीं पाया) अलग-अलग सामने आते हैं। +`failproofai audit` रनटाइम द्वारा संचालित — अंतर्निहित स्कैन इंजन, समर्थित फ्लैग्स, और प्रति-ट्रांसक्रिप्ट कैश अपरिवर्तनीयों के लिए [Audit CLI](/hi/cli/audit) देखें। डैशबोर्ड नवीनतम परिणाम को `~/.failproofai/audit-dashboard.json` पर कैश करता है (मोड `0600`, एकल स्लॉट, नई रन ओवरराइट करती है) इसलिए पुनः विज़िट तत्काल हैं; **प्रति-ट्रांसक्रिप्ट और संपूर्ण-परिणाम दोनों कैशेस को पढ़ने पर अस्वीकार कर दिया जाता है एक बार जब वे 7 दिन से पुरानी हों** इसलिए डैशबोर्ड कभी भी चुप्पी से सप्ताह पुरानी परिणाम परोसता है — TTL के बाद `/audit` अपने खाली स्थिति में गिरता है और एक ताज़ा रन के लिए संकेत देता है। रिपोर्ट के नीचे के पास `[ re-audit now ]` पर क्लिक करने से `/api/audit/run` को `noCache: true` के साथ POST किया जाता है — पुनः-ऑडिट प्रति-ट्रांसक्रिप्ट कैश को बायपास करता है और हर ट्रांसक्रिप्ट को चुप्पी से कैश की गई परिणाम लौटाने के बजाय खरोंच से पुनः-स्कैन करता है — और डैशबोर्ड रन तक 1Hz पर `/api/audit/status` को पोल करता है; रन के दौरान एक चिपचिपा गुलाबी प्रगति पट्टी व्यूपोर्ट के शीर्ष पर पिन होती है एक विलीन टाइमर के साथ, और ताज़ा परिणाम सफलता पर स्थान पर स्वैप करता है (कोई पूर्ण-पृष्ठ पुनः लोड नहीं; एक विफल पुनः-ऑडिट पूर्व रिपोर्ट को अक्षत छोड़ देता है)। विफलता पर पट्टी `RerunError.kind` की प्रतिलिपि के साथ लाल हो जाती है (`timeout` / `network` / `post_failed`)। खाली स्थिति (कोई कैश नहीं या समाप्त) और शून्य-सेशन स्थिति (कैश मौजूद है लेकिन स्कैन को कोई ट्रांसक्रिप्ट नहीं मिले) को अलग से सामने लाया जाता है। ### नीतियां -नीतियों का प्रबंधन करने और गतिविधि की समीक्षा करने के लिए एक दो-टैब पृष्ठ। +नीतियों को प्रबंधित करने और गतिविधि की समीक्षा करने के लिए एक दो-टैब पृष्ठ। - - - एक एकल पैनल से failproofai कौन से एजेंट CLI की रक्षा करता है इसे बहु-चयन करें — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, और Hermes सभी में स्थापन स्थिति (`Active` / `Detected` / `Inactive`) के साथ एक पंक्ति है, उपयोगकर्ता-दायरा सेटिंग्स पथ, और एक ब्रांड-रंगीन उच्चारण। आप जो CLI चाहते हैं उन्हें चेक या अनचेक करें और `Apply changes` पर क्लिक करके एक चरण में इंस्टॉल/अनइंस्टॉल करें। CLI जिनका बाइनरी PATH पर पाया जाता है वह पूर्व-चेक किए जाते हैं। - - एक एकल क्लिक के साथ अलग-अलग नीतियों को चालू या बंद करें (`~/.failproofai/policies-config.json` में लिखता है — हर स्थापित CLI में साझा) - - एक नीति को इसके पैरामीटर को कॉन्फ़िगर करने के लिए विस्तारित करें (नीतियों के लिए जो `policyParams` को समर्थन करती हैं) + + - एक एकल पैनल से कौन से एजेंट CLI failproofai सुरक्षित करता है यह बहु-चयन करें — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, और Hermes सभी के पास एक पंक्ति है जिसमें इंस्टॉल स्थिति (`Active` / `Detected` / `Inactive`), उपयोगकर्ता-स्कोप सेटिंग्स पथ, और एक ब्रांड-रंग का उच्चारण। वे CLI चेक या अनचेक करें जिन्हें आप चाहते हैं और एक कदम में diff को इंस्टॉल/अनइंस्टॉल करने के लिए `Apply changes` पर क्लिक करें। CLI जिनकी बाइनरी PATH पर खोजी जाती है वे पूर्व-चेक होते हैं। + - एक क्लिक के साथ व्यक्तिगत नीतियों को चालू या बंद करें (`~/.failproofai/policies-config.json` में लिखता है — हर इंस्टॉल किए गए CLI में साझा) + - एक नीति को अपने पैरामीटर को कॉन्फ़िगर करने के लिए विस्तारित करें (नीतियों के लिए जो `policyParams` समर्थन करती हैं) - एक कस्टम नीतियां फ़ाइल पथ सेट करें - - - सभी सेशन में फायर की गई हर हुक घटना का पूर्ण पृष्ठाकृत इतिहास - - निर्णय, घटना प्रकार, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), नीति नाम, या सेशन ID द्वारा फ़िल्टर करें - - प्रत्येक पंक्ति दिखाता है: टाइमस्टैम्प, नीति नाम, निर्णय, CLI बैज (नारंगी = Claude Code, बैंगनी = OpenAI Codex, नीला = GitHub Copilot, पन्ना हरा = Cursor Agent, एम्बर = OpenCode, गुलाबी = Pi, गहरा नीला = Hermes, टील = OpenClaw, गुलाब = Factory Droid, बैंगनी = Devin, सियान = Antigravity, नींबू = Goose), टूल नाम, सेशन ID, और अनुमति/निर्देश निर्णय के कारण - - एक सेशन ID पर क्लिक करके इसके ट्रांसक्रिप्ट को खोलें — व्यूअर स्वचालित रूप से पहचानता है कि कौन सा CLI हुक फायर किया (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) और हेडर में मेलिंग CLI बैज को प्रस्तुत करता है + + - सभी सेशन्स में निकाली गई हर हुक इवेंट का पूर्ण पेजिनेटेड इतिहास + - निर्णय, इवेंट प्रकार, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(बीटा)_ / Cursor Agent _(बीटा)_ / OpenCode _(बीटा)_ / Pi _(बीटा)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), नीति का नाम, या सेशन ID द्वारा फ़िल्टर करें + - प्रत्येक पंक्ति दिखाती है: टाइमस्टैम्प, नीति का नाम, निर्णय, CLI बैज (नारंगी = Claude Code, बैंगनी = OpenAI Codex, नीला = GitHub Copilot, पन्ना = Cursor Agent, एम्बर = OpenCode, गुलाबी = Pi, इंडिगो = Hermes, टील = OpenClaw, गुलाब = Factory Droid, वायलेट = Devin, सियान = Antigravity, लाइम = Goose), टूल का नाम, सेशन ID, और deny/instruct निर्णयों का कारण + - एक ट्रांसक्रिप्ट खोलने के लिए किसी सेशन ID पर क्लिक करें — दर्शक स्वचालित रूप से यह पता लगाता है कि कौन सा CLI हुक को निकाला (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) और हेडर में मिलान करने वाली CLI बैज को प्रदर्शित करता है --- -## स्वचालित ताज़ा करना +## स्वचालित पुनः-ताज़ा -डैशबोर्ड में शीर्ष नेविगेशन में एक स्वचालित-ताज़ा टॉगल है। जब सक्षम किया जाता है, तो वर्तमान पृष्ठ नए सेशन और नीति गतिविधि दिखाने के लिए आवधिक रूप से ताज़ा करता है क्योंकि वे दिखाई देते हैं। लंबे समय तक चलने वाले स्वायत्त एजेंट सेशन की निगरानी के लिए आवश्यक। +डैशबोर्ड में शीर्ष नेविगेशन में एक स्वचालित पुनः-ताज़ा टॉगल है। जब सक्षम हो, वर्तमान पृष्ठ समय-समय पर नए सेशन्स और नीति गतिविधि को प्रदर्शित करने के लिए पुनः-ताज़ा करता है जैसे-जैसे वे प्रकट होते हैं। दीर्घकालीन स्वायत्त एजेंट सेशन्स के मॉनिटरिंग के लिए आवश्यक। --- ## पृष्ठों को अक्षम करना -यदि आपको डैशबोर्ड के केवल कुछ हिस्से की आवश्यकता है, तो `FAILPROOFAI_DISABLE_PAGES` को पृष्ठ नामों की अल्पविराम-अलग सूची में सेट करें: +यदि आपको केवल डैशबोर्ड के कुछ हिस्सों की आवश्यकता है, तो `FAILPROOFAI_DISABLE_PAGES` को पृष्ठ के नामों की अल्पविराम-विभाजित सूची पर सेट करें: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai ``` -मान्य मान: `policies`, `projects`, `audit`। +वैध मान: `policies`, `projects`, `audit`। --- ## प्रोजेक्ट्स पथ को कॉन्फ़िगर करना -डिफ़ॉल्ट रूप से, डैशबोर्ड मानक Claude Code प्रोजेक्ट्स निर्देशिका से पढ़ता है। कस्टम सेटअप के लिए इसे ओवरराइड करें: +डिफ़ॉल्ट रूप से, डैशबोर्ड मानक Claude Code प्रोजेक्ट्स निर्देशिका से पढ़ता है। कस्टम सेटअप के लिए इसे ओवाराइड करें: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -118,21 +120,21 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## एक गैर-localhost होस्ट से एक्सेस करना +## गैर-localhost होस्ट से एक्सेस करना -जब डैशबोर्ड को **dev mode** में (`npm run dev`) चलाते हैं और इसे `localhost` के अलावा किसी अन्य होस्टनाम से एक्सेस करते हैं - उदाहरण के लिए, एक कस्टम डोमेन, एक दूरस्थ IP, या एक टनेल की गई URL — आप इस तरह की चेतावनी देख सकते हैं: +जब **dev मोड** (`npm run dev`) में डैशबोर्ड चला रहे हैं और `localhost` के अलावा किसी अन्य होस्टनाम से इस तक पहुंच रहे हैं - उदाहरण के लिए, एक कस्टम डोमेन, एक दूरस्थ IP, या एक टनल किया गया URL - आप एक चेतावनी देख सकते हैं जैसे: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -यह Next.js अपने HMR (hot module reload) वेबसॉकेट के लिए क्रॉस-ऑरिजिन एक्सेस को ब्लॉक करना है, जो एक dev-only सुविधा है। अपने होस्ट को अनुमति देने के लिए, `--allowed-origins` फ़्लैग का उपयोग करें: +यह Next.js अपने HMR (हॉट मॉड्यूल रीलोड) वेबसॉकेट को क्रॉस-ऑरिजिन एक्सेस से ब्लॉक कर रहा है, जो एक dev-केवल सुविधा है। अपने होस्ट को अनुमति देने के लिए, `--allowed-origins` फ्लैग का उपयोग करें: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -कई होस्ट या IP के लिए, एक अल्पविराम-अलग सूची पास करें: +कई होस्ट्स या IP के लिए, एक अल्पविराम-विभाजित सूची पास करें: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 @@ -145,5 +147,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -यह केवल dev mode पर लागू होता है। जब `failproofai` चलाते हैं (production mode), तो कोई HMR वेबसॉकेट नहीं होता है और कोई क्रॉस-ऑरिजिन dev संसाधन समस्या नहीं होती है। +यह केवल dev मोड पर लागू होता है। `failproofai` (प्रोडक्शन मोड) चलाते समय, कोई HMR वेबसॉकेट नहीं है और कोई क्रॉस-ऑरिजिन dev संसाधन समस्या नहीं है। \ No newline at end of file diff --git a/docs/it/configuration.mdx b/docs/it/configuration.mdx index e9d6f33e..83f4029c 100644 --- a/docs/it/configuration.mdx +++ b/docs/it/configuration.mdx @@ -1,38 +1,39 @@ --- +--- title: Configurazione -description: "Formato file di configurazione, sistema a tre livelli e regole di merge" +description: "Formato del file di configurazione, sistema a tre livelli di scope e regole di merge" icon: gear --- -failproofai utilizza file di configurazione JSON per controllare quali policy sono attive, come si comportano e da dove vengono caricate le policy personalizzate. La configurazione è progettata per essere facile da condividere con il tuo team - commitatela nel tuo repo e ogni sviluppatore avrà la stessa rete di protezione dell'agent. +failproofai utilizza file di configurazione JSON per controllare quali politiche sono attive, come si comportano e da dove vengono caricate le politiche personalizzate. La configurazione è progettata per essere facile da condividere con il tuo team - committala nel tuo repository e ogni sviluppatore avrà la stessa rete di sicurezza degli agenti. --- -## Ambiti di configurazione +## Scope di configurazione -Ci sono tre ambiti di configurazione, valutati in ordine di priorità: +Esistono tre scope di configurazione, valutati in ordine di priorità: -| Ambito | Percorso file | Scopo | -|--------|---------------|-------| -| **project** | `.failproofai/policies-config.json` | Impostazioni per-repo, committate nel version control | -| **local** | `.failproofai/policies-config.local.json` | Override personali per-repo, gitignorate | -| **global** | `~/.failproofai/policies-config.json` | Default a livello utente su tutti i progetti | +| Scope | Percorso file | Scopo | +|-------|-----------|---------| +| **project** | `.failproofai/policies-config.json` | Impostazioni per-repo, committate nel controllo versione | +| **local** | `.failproofai/policies-config.local.json` | Override personali per-repo, gitignored | +| **global** | `~/.failproofai/policies-config.json` | Impostazioni predefinite a livello utente per tutti i progetti | Quando failproofai riceve un evento hook, carica e unisce tutti e tre i file che esistono per la directory di lavoro corrente. ### Regole di merge -**`enabledPolicies`** - l'unione di tutti e tre gli ambiti. Una policy abilitata a qualsiasi livello è attiva. +**`enabledPolicies`** - l'unione di tutti e tre gli scope. Una politica abilitata a qualsiasi livello è attiva. ```text project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← unione deduplificata +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← unione deduplicate ``` -**`policyParams`** - il primo ambito che definisce parametri per una data policy vince interamente. Non c'è merging profondo di valori all'interno dei parametri di una policy. +**`policyParams`** - il primo scope che definisce i parametri per una data politica vince completamente. Non c'è merge profondo dei valori all'interno dei parametri di una politica. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -46,16 +47,18 @@ project: (nessuna voce block-sudo) local: (nessuna voce block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← fallback a global +resolved: { allowPatterns: ["sudo systemctl status"] } ← ricade su global ``` -**`customPoliciesPath`** - il primo ambito che lo definisce vince. +**`customPoliciesPaths` / `customPoliciesPath`** - il primo scope che definisce una delle due forme vince. + +**`disabledCustomPolicies`** - unione tra tutti gli scope. Il dashboard scrive un ID qualificato con la fonte qui quando disattivi una singola politica da un file di politica esplicita o convenzionale. Le politiche non elencate rimangono abilitate per impostazione predefinita; gli ID includono il file di origine in modo che le politiche con lo stesso nome in più file possano essere controllate indipendentemente. -**`llm`** - il primo ambito che lo definisce vince. +**`llm`** - il primo scope che lo definisce vince. --- -## Formato file di configurazione +## Formato del file di configurazione ```json { @@ -96,33 +99,33 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← fallback a global --- -## Riferimento campi +## Riferimento dei campi ### `enabledPolicies` -Type: `string[]` +Tipo: `string[]` -Elenco dei nomi di policy da abilitare. I nomi devono corrispondere esattamente agli identificatori di policy mostrati da `failproofai policies`. Vedi [Built-in Policies](/it/built-in-policies) per l'elenco completo. +Elenco dei nomi delle politiche da abilitare. I nomi devono corrispondere esattamente agli identificatori delle politiche mostrati da `failproofai policies`. Consulta [Built-in Policies](/it/built-in-policies) per l'elenco completo. -Le policy non in `enabledPolicies` sono inattive, anche se hanno voci in `policyParams`. +Le politiche non in `enabledPolicies` sono inattive, anche se hanno voci in `policyParams`. ### `policyParams` -Type: `Record>` +Tipo: `Record>` -Override di parametri per-policy. La chiave esterna è il nome della policy; le chiavi interne sono specifiche della policy. Ogni policy documenta i suoi parametri disponibili in [Built-in Policies](/it/built-in-policies). +Override dei parametri per singola politica. La chiave esterna è il nome della politica; le chiavi interne sono specifiche della politica. Ogni politica documenta i suoi parametri disponibili in [Built-in Policies](/it/built-in-policies). -Se una policy ha parametri ma non li specifichi, vengono utilizzati i default built-in della policy. Gli utenti che non configurano `policyParams` affatto otterranno un comportamento identico alle versioni precedenti. +Se una politica ha parametri ma non li specifichi, vengono utilizzati i valori predefiniti integrati della politica. Gli utenti che non configurano `policyParams` affatto ottengono un comportamento identico alle versioni precedenti. -Le chiavi sconosciute all'interno del blocco dei parametri di una policy sono silenziosamente ignorate al momento dello scatto dell'hook ma segnalate come avvisi quando esegui `failproofai policies`. +Le chiavi sconosciute all'interno del blocco dei parametri di una politica vengono ignorate silenziosamente al momento dell'esecuzione dell'hook, ma segnalate come avvisi quando esegui `failproofai policies`. #### `hint` (cross-cutting) -Type: `string` (optional) +Tipo: `string` (opzionale) -Un messaggio aggiunto alla ragione quando una policy restituisce `deny` o `instruct`. Usalo per fornire a Claude una guida praticabile senza modificare la policy stessa. +Un messaggio aggiunto al motivo quando una politica restituisce `deny` o `instruct`. Usalo per dare a Claude una guida praticabile senza modificare la politica stessa. -Funziona con qualsiasi tipo di policy — built-in, custom (`custom/`), project convention (`.failproofai-project/`), o user convention (`.failproofai-user/`). +Funziona con qualsiasi tipo di politica — integrata, personalizzata (`custom/`), convenzione di progetto (`.failproofai-project/`), o convenzione utente (`.failproofai-user/`). ```json { @@ -135,7 +138,7 @@ Funziona con qualsiasi tipo di policy — built-in, custom (`custom/`), project "hint": "Usa apt-get direttamente senza sudo." }, "custom/my-policy": { - "hint": "Chiedi l'approvazione all'utente prima." + "hint": "Chiedi prima l'approvazione all'utente." } } } @@ -143,38 +146,38 @@ Funziona con qualsiasi tipo di policy — built-in, custom (`custom/`), project Quando `block-force-push` nega, Claude vede: *"Il force-push è bloccato. Prova a creare invece un nuovo branch."* -I valori non-string e le stringhe vuote sono silenziosamente ignorati. Se `hint` non è impostato, il comportamento è invariato (backward-compatible). +I valori non stringa e le stringhe vuote vengono ignorate silenziosamente. Se `hint` non è impostato, il comportamento è invariato (retrocompatibile). ### `customPoliciesPath` -Type: `string` (absolute path) +Tipo: `string` (percorso assoluto) -Percorso di un file JavaScript contenente policy hook personalizzate. Questo è impostato automaticamente da `failproofai policies --install --custom ` (il percorso è risolto ad assoluto prima di essere memorizzato). +Percorso a un file JavaScript contenente politiche hook personalizzate. Viene impostato automaticamente da `failproofai policies --install --custom ` (il percorso viene risolto in assoluto prima di essere archiviato). -Il file viene caricato fresco ad ogni evento hook - non c'è caching. Vedi [Custom Policies](/it/custom-policies) per i dettagli di authoring. +Il file viene caricato di nuovo a ogni evento hook - non c'è caching. Consulta [Custom Policies](/it/custom-policies) per i dettagli di authoring. -### Policy basate su convenzione +### Politiche basate su convenzione -In aggiunta a `customPoliciesPath` esplicito, failproofai scopre automaticamente e carica file di policy dalle directory `.failproofai/policies/`: +Oltre a `customPoliciesPath` esplicito, failproofai scopre e carica automaticamente i file di politica dalle directory `.failproofai/policies/`: -| Livello | Directory | Ambito | -|---------|-----------|--------| -| Project | `.failproofai/policies/` | Condiviso con il team tramite version control | +| Livello | Directory | Scope | +|-------|-----------|-------| +| Project | `.failproofai/policies/` | Condiviso con il team tramite controllo versione | | User | `~/.failproofai/policies/` | Personale, si applica a tutti i progetti | -**Corrispondenza file:** Solo i file che corrispondono a `*policies.{js,mjs,ts}` vengono caricati (ad es. `security-policies.mjs`, `workflow-policies.js`). Gli altri file nella directory sono ignorati. +**Corrispondenza dei file:** Solo i file che corrispondono a `*policies.{js,mjs,ts}` vengono caricati (es. `security-policies.mjs`, `workflow-policies.js`). Gli altri file nella directory vengono ignorati. -**Nessuna configurazione necessaria:** Le policy di convenzione non richiedono voci in `policies-config.json`. Basta inserire i file nella directory e verranno raccolti al prossimo evento hook. +**Nessuna configurazione necessaria:** Le politiche di convenzione non richiedono voci in `policies-config.json`. Basta rilasciare i file nella directory e verranno prelevati al prossimo evento hook. -**Caricamento unione:** Entrambe le directory di convenzione di project e user vengono scansionate. Tutti i file corrispondenti da entrambi i livelli vengono caricati (a differenza di `customPoliciesPath` che usa il primo-ambito-vince). +**Caricamento unione:** Entrambe le directory di convenzione di progetto e utente vengono scansionate. Tutti i file corrispondenti da entrambi i livelli vengono caricati (diversamente da `customPoliciesPath` che usa il primo-scope-vince). -Vedi [Custom Policies](/it/custom-policies) per più dettagli ed esempi. +Consulta [Custom Policies](/it/custom-policies) per maggiori dettagli ed esempi. ### `llm` -Type: `object` (optional) +Tipo: `object` (opzionale) -Configurazione del client LLM per le policy che effettuano chiamate AI. Non richiesta per la maggior parte delle configurazioni. +Configurazione del client LLM per politiche che effettuano chiamate AI. Non richiesto per la maggior parte dei setup. ```json { @@ -189,19 +192,24 @@ Configurazione del client LLM per le policy che effettuano chiamate AI. Non rich ## Gestione della configurazione dalla CLI -I comandi `policies --install` e `policies --uninstall` scrivono nel file di impostazioni hook della CLI del tuo agent (i punti di ingresso dell'hook), mentre `policies-config.json` è il file che gestisci direttamente. I due sono separati: +I comandi `policies --install` e `policies --uninstall` scrivono nel file di impostazioni hook della CLI dell'agente (i punti di ingresso dell'hook), mentre `policies-config.json` è il file che gestisci direttamente. I due sono separati: -- **Impostazioni agent CLI** — dice all'agent di chiamare `failproofai --hook ` ad ogni uso di strumento: +- **Impostazioni agent CLI** — dice all'agente di chiamare `failproofai --hook ` ad ogni tool use: - **Claude Code**: `~/.claude/settings.json` (user), `/.claude/settings.json` (project), `/.claude/settings.local.json` (local) - - **OpenAI Codex**: `~/.codex/hooks.json` (user), `/.codex/hooks.json` (project) — Codex non ha un ambito `local` - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (user), `/.github/hooks/failproofai.json` (project) — Copilot non ha un ambito `local`. Le voci hook usano i campi di comando `bash`/`powershell` di Copilot con chiave OS e `timeoutSec`; il file porta un marcatore `version: 1` di alto livello. Il supporto di Copilot CLI è **beta** mentre verifichiamo lo schema del record `events.jsonl` (che la documentazione pubblica non specifica) rispetto a più sessioni del mondo reale. - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — Cursor non ha un ambito `local`. Le voci hook usano la forma `{type, command, timeout}` a forma di Claude (senza split `bash`/`powershell`), ma memorizzate sotto chiavi di evento camelCase (`preToolUse`, `beforeSubmitPrompt`, …) in un array piatto per lo [schema degli hook](https://cursor.com/docs/hooks) di Cursor; il file porta un marcatore `version: 1` di alto livello. Il gestore canonicalizza camelCase → PascalCase tramite `CURSOR_EVENT_MAP` quindi le policy built-in esistenti si attivano invariate. Il supporto di Cursor Agent è **beta** mentre verifichiamo il formato del transcript di Cursor su disco (non specificato nella documentazione pubblica) rispetto a più installazioni del mondo reale. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (user), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (project) — OpenCode non ha un ambito `local`. A differenza degli altri cinque CLI, OpenCode ha **nessun sistema di hook per comando esterno**: carica plugin JS/TS in-process esplicitamente registrati tramite l'array `plugin: []` in `opencode.json` (l'auto-discovery da `.opencode/plugins/` **non** è come i plugin vengono caricati su opencode v1.14.33). L'installazione rilascia un piccolo shim plugin generato che subprocess-chiama il binario failproofai e traduce la risposta JSON a forma di Claude del binario di nuovo in semantica plugin: `throw new Error()` per tool-event deny (cancella la chiamata dello strumento), `client.session.prompt(...)` per instruct E per deny di `Stop` / `SubagentStop` (invia la ragione di deny come prossimo messaggio utente — l'unico canale force-retry dal momento che `session.idle` è notification-only e gettare da essa è un no-op), e no-op per allow. Lo shim canonicalizza sia i nomi di strumento (lowercase → PascalCase tramite `OPENCODE_TOOL_MAP`) che le chiavi degli argomenti di input dello strumento (camelCase → snake_case tramite `OPENCODE_TOOL_INPUT_MAP` per `Read` / `Write` / `Edit`, ad es. `filePath` → `file_path`, `oldString` → `old_string`) prima di inoltrarsi al binario, così il controllo dei percorsi built-in come `block-read-outside-cwd`, `block-env-files`, e `block-secrets-write` si attivano invariate sulle chiamate agli strumenti di OpenCode. Le sessioni vivono nel DB SQLite di opencode presso `~/.local/share/opencode/opencode.db`; il visualizzatore di sessioni della dashboard li legge tramite `opencode db --format json` e `opencode export `. Il supporto di OpenCode è **beta** mentre verifichiamo il comportamento attraverso versioni e rispetto a più sessioni del mondo reale. Vedi la [documentazione dei plugin di OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `/.pi/settings.json` (project) — Pi non ha un ambito `local`. Pi carica pacchetti di estensioni TypeScript all'avvio; il file di impostazioni è un array di stringhe piatto `{"packages": ["./relative/path", …]}`. failproofai scrive una singola voce dell'array dei pacchetti che punta alla sua directory `pi-extension/` in bundle. L'estensione internamente si sottoscrive agli eventi `tool_call` / `user_bash` / `input` / `session_start` di Pi e guscio fuori a `failproofai --hook --cli pi`; il gestore canonicalizza underscore_lower_snake_case → PascalCase tramite `PI_EVENT_MAP` quindi le policy built-in esistenti si attivano invariate. Gli argomenti di input dello strumento sono anche canonicalizzati tramite `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit forniscono `path` piuttosto che `file_path`; mappare la chiave di top-level lascia che `block-env-files` e `block-secrets-write` si attivino — `block-read-outside-cwd` già aveva un fallback `path`). Il supporto di Pi è **beta** mentre l'API di estensione di Pi e il layout del log di sessione si stabilizzano. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**ambito utente solo** — Hermes non ha configurazione project/local). Hermes è un gateway **Slack/Telegram**, quindi un'installazione intercetta le chiamate di strumento da ogni piattaforma (Slack/Telegram/cli/cron) **e** subagent interni. Le voci hook sono una coppia `{command, timeout}` (timeout in **secondi**) sotto una mappa `hooks:` codificata dagli eventi snake_case di Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); il gestore canonicalizza gli eventi tramite `HERMES_EVENT_MAP` e i nomi di strumento tramite `HERMES_TOOL_MAP` quindi le policy built-in si attivano invariate. La configurazione è modificata tramite una `Document` YAML di preservazione dei commenti round-trip in modo che le altre impostazioni dell'operatore sopravvivano, e l'installazione imposta `hooks_auto_accept: true` così il gateway headless (no TTY) esegue gli hook senza un prompt di consenso. L'evaluator emette il contratto stdout `{"decision":"block","reason"}` di Hermes (Hermes ignora i codici di uscita). **Limitazioni:** Hermes non ha un evento end-turn `Stop`, quindi le policy built-in `require-*-before-stop` non si attivano mai per esso (inapplicabile, non rotto); `instruct` degrada a allow-with-logged-note (nessun canale additional-context); e la redazione di secret di output (`sanitize-*`) non può riscrivere l'output dello strumento sul contratto dell'hook di shell. Hermes è **anche** una fonte di **audit** offline — la dashboard legge le sue sessioni di gateway direttamente da `~/.hermes/state.db`. -- **`policies-config.json`** — dice a failproofai quali policy valutare e con quali parametri (condiviso su tutti gli agent CLI) - -Passa `--cli claude|codex|copilot|cursor|opencode|pi|hermes` per indirizzare un agent specifico (space-separated o ripetuto per qualsiasi subset): + - **OpenAI Codex**: `~/.codex/hooks.json` (user), `/.codex/hooks.json` (project) — Codex non ha uno scope `local` + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (user), `/.github/hooks/failproofai.json` (project) — Copilot non ha uno scope `local`. Le voci hook utilizzano i campi di comando `bash`/`powershell` con chiave OS di Copilot con `timeoutSec`; il file porta un marker `version: 1` a livello superiore. Il supporto di Copilot CLI è **beta** mentre verifichiamo lo schema del record `events.jsonl` (che i documenti pubblici non specificano) rispetto a più sessioni nel mondo reale. **Modalità agente VS Code Copilot Chat (Anteprima)** legge le configurazioni degli hook da `.github/hooks/*.json`, `~/.copilot/hooks/*.json`, e `~/.claude/settings.json` (governato dall'impostazione `chat.hookFilesLocations`) utilizzando lo stesso contratto Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — i percorsi esatti che questa integrazione `copilot` e l'integrazione `claude` (`~/.claude/settings.json`) già scrivono, quindi `failproofai policies --install --cli copilot` (o `--cli claude`) **già applica in modalità agente VS Code** senza una separata integrazione `vscode` necessaria (confermato dal vivo dai log di discovery di VS Code). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — Cursor non ha uno scope `local`. Le voci hook utilizzano il form Claude `{type, command, timeout}` (nessuna divisione `bash`/`powershell`), ma archiviate sotto chiavi di evento camelCase (`preToolUse`, `beforeSubmitPrompt`, …) in un array piatto per lo [schema degli hook](https://cursor.com/docs/hooks) di Cursor; il file porta un marker `version: 1` a livello superiore. L'handler canonicalizza camelCase → PascalCase tramite `CURSOR_EVENT_MAP` in modo che le politiche integrate esistenti si attivino invariate. Il supporto di Cursor Agent è **beta** mentre verifichiamo il transcript di Cursor su disco (non specificato nei documenti pubblici) rispetto a più installazioni nel mondo reale. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (user), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (project) — OpenCode non ha uno scope `local`. A differenza degli altri cinque CLI, OpenCode **non ha un sistema di hook di comando esterno**: carica plugin JS/TS in-process esplicitamente registrati tramite l'array `plugin: []` in `opencode.json` (l'auto-discovery da `.opencode/plugins/` **non** è il modo in cui i plugin si caricano su opencode v1.14.33). L'installazione crea un piccolo shim di plugin generato che effettua una chiamata subprocess del binario failproofai e traduce la risposta JSON di forma Claude del binario in semantica di plugin: `throw new Error()` per tool-event deny (annulla la tool call), `client.session.prompt(...)` per instruct E per deny `Stop` / `SubagentStop` (invia il motivo di deny come prossimo messaggio utente — l'unico canale di force-retry poiché `session.idle` è notification-only e lanciare da esso è un no-op), e no-op per allow. Lo shim canonicalizza sia i nomi dei tool (minuscoli → PascalCase tramite `OPENCODE_TOOL_MAP`) che i tasti di argomento input del tool (camelCase → snake_case tramite `OPENCODE_TOOL_INPUT_MAP` per `Read` / `Write` / `Edit`, es. `filePath` → `file_path`, `oldString` → `old_string`) prima di inoltrarli al binario, quindi le builtin di controllo del percorso come `block-read-outside-cwd`, `block-env-files`, e `block-secrets-write` si attivano invariate sulle tool call di OpenCode. Le sessioni vivono nel database SQLite di opencode su `~/.local/share/opencode/opencode.db`; il visualizzatore di sessioni del dashboard li legge tramite `opencode db --format json` e `opencode export `. Il supporto di OpenCode è **beta** mentre verifichiamo il comportamento tra versioni e rispetto a più sessioni nel mondo reale. Consulta la [documentazione dei plugin OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `/.pi/settings.json` (project) — Pi non ha uno scope `local`. Pi carica pacchetti di estensione TypeScript all'avvio; il file di impostazioni è un array di stringhe piatte `{"packages": ["./relative/path", …]}`. failproofai scrive una singola voce di array di pacchetti che punta alla sua directory `pi-extension/` in bundle. L'estensione internamente si iscrive agli eventi `tool_call` / `user_bash` / `input` / `session_start` di Pi e effettua una chiamata shell a `failproofai --hook --cli pi`; l'handler canonicalizza underscore_lower_snake_case → PascalCase tramite `PI_EVENT_MAP` in modo che le politiche integrate esistenti si attivino invariate. I tasti di argomento input del tool vengono anche canonicalizzati tramite `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit forniscono `path` piuttosto che `file_path`; mappare la chiave di livello superiore consente a `block-env-files` e `block-secrets-write` di attivarsi — `block-read-outside-cwd` aveva già un fallback `path`). Il supporto di Pi è **beta** mentre lo schema di API di estensione di Pi e il layout di session-log si stabilizzano. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**solo scope utente** — Hermes non ha configurazione di progetto/local). Hermes è un **gateway** Slack/Telegram, quindi un'installazione intercetta le tool call da ogni piattaforma (Slack/Telegram/cli/cron) **e** subageniti interni. Le voci hook sono una coppia `{command, timeout}` (timeout in **secondi**) sotto una mappa `hooks:` con chiave per i snake_case events di Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); l'handler canonicalizza gli eventi tramite `HERMES_EVENT_MAP` e i nomi dei tool tramite `HERMES_TOOL_MAP` in modo che le politiche integrate si attivino invariate. La configurazione viene modificata tramite un round-trip di `Document` YAML che preserva i commenti in modo che le altre impostazioni dell'operatore sopravvivono, e l'installazione imposta `hooks_auto_accept: true` in modo che il gateway headless (no TTY) esegua gli hook senza un prompt di consenso. L'evaluator emette il contratto stdout `{"decision":"block","reason"}` di Hermes (Hermes ignora i codici di exit). **Limitazioni:** Hermes non ha un evento `Stop` di fine turno, quindi le builtin `require-*-before-stop` non si attivano mai per esso (inapplicabile, non rotto); `instruct` si degrada a allow-with-logged-note (nessun canale di contesto aggiuntivo); e la redazione di segreti di output (`sanitize-*`) non può riscrivere l'output del tool oltre il contratto di shell-hook. Hermes è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni di gateway direttamente da `~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**solo scope utente** — OpenClaw non ha configurazione di progetto/local). Come Hermes, OpenClaw è un **gateway** multi-canale auto-hosted, quindi un'installazione intercetta le tool call da ogni canale e i suoi subageniti interni. L'applicazione dell'enforcement funziona attraverso i **plugin hook in-process** di OpenClaw (i suoi hook interni basati su file sono solo osservazione e non possono bloccare), quindi — come OpenCode/Pi — failproofai spedisce un pacchetto statico `openclaw-plugin/` che async-spawna il binario failproofai e traduce il verdetto. L'installer registra la directory di plugin spedita in `openclaw.json`'s `plugins.load.paths[]` e l'abilita sotto `plugins.entries.failproofai` (con `hooks.allowConversationAccess: true`, richiesto per i raw-conversation hooks). L'evaluator emette un verdetto `{permission, reason}` piatto e lo shim lo mappa in ogni forma di ritorno nativa dell'hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), e `before_agent_finalize → {action:"revise", reason}` (**Stop** — una vera porta di fine turno, quindi le builtin `require-*-before-stop` **si applica** su OpenClaw, diversamente da Hermes). Gli eventi e i nomi dei tool canonicalizzano lato binario tramite `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) in modo che le politiche integrate si attivino invariate; lo shim fallisce open su qualsiasi errore di spawn/parse/timeout. OpenClaw è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni JSONL su `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (user), `/.factory/hooks.json` (project) — Factory non ha uno scope `local`. droid spedisce un sistema di hook di comando esterno di stile Claude, ma con due particolarità verificate dal vivo rispetto a droid v0.171.0: (1) i nomi degli eventi vivono al **livello superiore** di `hooks.json` — non esiste **nessun wrapper `"hooks"`** (droid lo rifiuta); gli eventi dei tool (`PreToolUse`/`PostToolUse`) portano `"matcher": "*"`, gli eventi non-tool l'omettono. (2) Il Deny è guidato dal **exit code 2 + stderr** dell'hook, non da una decisione JSON — il ramo `factory` dell'evaluator restituisce exit 2 per gli eventi tool/prompt e `{decision:"block", reason}` solo sull'evento `Stop` di fine turno (l'unico canale di force-retry di droid). Gli eventi sono già PascalCase (nessuna mappa di eventi) e il payload è snake_case di Claude; solo i nomi dei tool sono canonicalizzati tramite `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni JSONL su disco su `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (user), `/.devin/config.json` (project) — Devin non ha uno scope `local`. Devin è un **pure Claude-clone** verificato dal vivo rispetto a devin v3000.1.27: utilizza lo schema standard Claude con wrapper `"hooks"` (le scritture sono merge-preserving in modo che le altre chiavi del file di configurazione — `org_id`, `theme_mode`, … — sopravvivano), i nomi degli eventi già-PascalCase (nessuna mappa di eventi, nessun ramo dell'handler), e un payload stdin di snake_case di Claude (nessuna normalizzazione). Il ramo `devin` dell'evaluator nega con JSON `{"decision":"block","reason"}` su stdout con exit 0 per **ogni** evento (verificato — il blocco ha scavalcato `--permission-mode dangerous`); sull'evento `Stop` di fine turno il motivo porta la formulazione MANDATORY-ACTION di force-retry in modo che le builtin `require-*-before-stop` si applichinoá. Solo i nomi dei tool sono canonicalizzati tramite `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` è già canonico). Devin è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni SQLite su `~/.local/share/devin/cli/sessions.db` (ogni riga `sessions` porta una vera `working_directory`, quindi le sessioni si raggruppano per project cwd come Claude). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (user), `/.agents/hooks.json` (project) — Antigravity non ha uno scope `local`. Diversamente da Factory/Devin, Antigravity ha il **suo** contratto (non un Claude-clone), verificato dal vivo rispetto a agy v1.1.2. `hooks.json` utilizza uno **schema di hook nominato**: la chiave di livello superiore è un nome di hook (*`"failproofai"`*) il cui valore è una mappa evento→handlers — gli eventi dei tool (`PreToolUse`/`PostToolUse`) avvolgono gli handler in `{matcher:"*", hooks:[…]}`, mentre `PreInvocation`/`Stop` sono array di handler **piatti** (gli altri hook nominati vengono preservati). Il payload stdin è **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai lo normalizza a snake_case prima che le politiche vengono eseguite, e mappa i tasti di argomento PascalCase (`CommandLine`/`Cwd`) di `run_command` tramite `ANTIGRAVITY_TOOL_INPUT_MAP`. Il ramo `antigravity` dell'evaluator utilizza le **proprie** forme di risposta di Antigravity: `{decision:"deny", reason}` blocca un tool/prompt (exit 0), `{decision:"continue", reason}` sull'evento `Stop` di fine turno ri-entra nel loop (quindi le builtin `require-*-before-stop` si applicano), e `{injectSteps:[{ephemeralMessage}]}` inietta un'istruzione su `PreInvocation` (→ `UserPromptSubmit`). I nomi dei tool canonicalizzano tramite `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity è **anche** una fonte di audit **offline** — il dashboard legge i suoi trascritti in plain-JSONL su `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (indice di conversazione in `conversation_summaries.db`). + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (user), `/.agents/plugins/failproofai/hooks/hooks.json` (project) — Goose non ha uno scope `local`. L'applicazione dell'enforcement utilizza il sistema **hooks** di Goose, lo spec multi-agente **Open Plugins**: l'installer semplicemente crea la directory di plugin `failproofai` e Goose l'auto-scopre all'avvio (auto-registrandola in `~/.config/goose/config.yaml`). Il `hooks.json` utilizza uno schema **con** un wrapper `"hooks"` di livello superiore, e il matcher viene **omesso** su ogni evento — una semplice `"*"` è un'espressione regolare non valida che non corrisponde a nulla (verificato dal vivo rispetto a goose v1.43.0). I nomi degli eventi sono già PascalCase (nessuna mappa di eventi); il payload stdin utilizza `event`/`working_dir`, che l'handler normalizza in `hook_event_name`/`cwd`. Il ramo `goose` dell'evaluator nega con JSON `{"decision":"block","reason"}` su stdout con exit 0, onorato sull'evento **`PreToolUse`** solo (spedito in goose ≥ v1.37.0) — che si attiva per il tool shell **e dentro i subageniti delegati**, in modo che sia il singolo punto di deny sufficiente; qualsiasi altro errore dell'hook fallisce **open**. Goose **non ha un evento `Stop`**, quindi le builtin `require-*-before-stop` non si applicano (come con Hermes). I nomi dei tool canonicalizzano tramite `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) e i tasti del percorso tramite `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose è **anche** una fonte di audit **offline** — il dashboard legge le sue sessioni SQLite su `~/.local/share/goose/sessions/sessions.db` (ogni riga `sessions` porta una vera `working_dir`, quindi le sessioni si raggruppano per project cwd come Devin; le esecuzioni scratch `--no-session` vengono filtrate). +- **`policies-config.json`** — dice a failproofai quali politiche valutare e con quali parametri (condiviso tra tutti i CLI degli agenti) + +Passa `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` per puntare a uno specifico agente (spazio-separato o ripetuto per qualsiasi sottoinsieme): ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +218,28 @@ failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli hermes --scope user -failproofai policies --install --cli claude codex copilot cursor opencode pi +failproofai policies --install --cli openclaw --scope user +failproofai policies --install --cli factory --scope project +failproofai policies --install --cli devin --scope project +failproofai policies --install --cli antigravity --scope project +failproofai policies --install --cli goose --scope project +failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -Quando `--cli` è omesso, `failproofai` rileva quali agent CLI sono installati (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`): +Quando `--cli` viene omesso, `failproofai` rileva quali CLI degli agenti sono installati (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): -- **Un CLI rilevato** — auto-seleziona quel CLI senza chiedere. -- **Più CLI rilevati** in un terminale interattivo — mostra un prompt single-select con tasti freccia raggruppati in una sezione `Detected (N)` (con una riga aggregata `Install for all N detected` + ogni CLI rilevato singolarmente) e una sezione `Not installed (M) · install hooks ahead of time` che elenca ogni CLI non rilevato supportato come opzione forward-install (↑↓ per muoversi, Enter per selezionare, ^C per uscire). Il flusso di disinstallazione mostra solo la sezione Detected. -- **Più CLI rilevati** in un'esecuzione non-interattiva (CI, no TTY) — installa per tutti i CLI rilevati senza chiedere. -- **Nessuno rilevato** — fallback a `claude`, con un avviso che nessun binario di agent è stato trovato in PATH; il comando hook è ancora scritto quindi si attiva non appena ne installi uno. +- **Un CLI rilevato** — auto-seleziona quel CLI senza richiedere. +- **Più CLI rilevati** in un terminale interattivo — mostra un prompt single-select con freccia raggruppato in una sezione `Detected (N)` (con una riga aggregata `Install for all N detected` + ogni CLI rilevato individualmente) e una sezione `Not installed (M) · install hooks ahead of time` che elenca ogni CLI supportato non rilevato come opzione di forward-install (↑↓ per muoversi, Enter per selezionare, ^C per uscire). Il flusso di disinstallazione mostra solo la sezione Detected. +- **Più CLI rilevati** in un'esecuzione non-interattiva (CI, nessun TTY) — installa per tutti i CLI rilevati senza richiedere. +- **Nessuno rilevato** — fallback su `claude`, con un avviso che nessun binario di agente è stato trovato in PATH; il comando dell'hook viene comunque scritto in modo che si attivi non appena ne installi uno. -Puoi modificare `policies-config.json` direttamente in qualsiasi momento; le modifiche hanno effetto immediatamente al prossimo evento hook senza necessità di restart. +Puoi modificare `policies-config.json` direttamente in qualsiasi momento; i cambiamenti hanno effetto immediatamente al prossimo evento hook senza riavvio necessario. --- -## Esempio: configurazione a livello di project con default del team +## Esempio: configurazione a livello di progetto con impostazioni predefinite di team -Committa `.failproofai/policies-config.json` nel tuo repo: +Committare `.failproofai/policies-config.json` al tuo repository: ```json { diff --git a/docs/it/custom-policies.mdx b/docs/it/custom-policies.mdx index 5d7a217b..ef3e2314 100644 --- a/docs/it/custom-policies.mdx +++ b/docs/it/custom-policies.mdx @@ -1,10 +1,11 @@ --- -title: Politiche personalizzate -description: "Scrivi le tue regole in JavaScript - applica convenzioni, previeni derive, rileva fallimenti, integrati con sistemi esterni" +--- +title: Politiche Personalizzate +description: "Scrivi le tue regole in JavaScript - applica convenzioni, previeni derive, rileva anomalie, integra con sistemi esterni" icon: code --- -Le politiche personalizzate ti permettono di scrivere regole per qualsiasi comportamento di agenti: applicare convenzioni di progetto, prevenire derive, bloccare operazioni distruttive, rilevare agenti bloccati, o integrarsi con Slack, flussi di approvazione e altro ancora. Utilizzano lo stesso sistema di eventi hook e le decisioni `allow`, `deny`, `instruct` delle politiche incorporate. +Le politiche personalizzate ti permettono di scrivere regole per qualsiasi comportamento dell'agente: applicare convenzioni di progetto, prevenire derive, bloccare operazioni distruttive, rilevare agenti bloccati o integrarsi con Slack, flussi di approvazione e altro ancora. Utilizzano lo stesso sistema di hook event e le decisioni `allow`, `deny`, `instruct` delle politiche integrate. --- @@ -39,12 +40,12 @@ failproofai policies --install --custom ./my-policies.js ## Due modi per caricare politiche personalizzate -### Opzione 1: Basata su convenzione (consigliato) +### Opzione 1: Basata su convenzione (consigliata) -Rilascia file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e vengono caricati automaticamente — non sono necessari flag o modifiche di configurazione. Funziona come git hooks: rilascia un file e funziona. +Lascia i file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e verranno caricati automaticamente — non sono necessari flag o modifiche di configurazione. Funziona come i git hook: lascia un file e funziona. ``` -# Livello di progetto — committato a git, condiviso con il team +# Livello di progetto — committato su git, condiviso con il team .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs @@ -57,10 +58,10 @@ Rilascia file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e vengono cari - I file vengono caricati alfabeticamente all'interno di ogni directory. Usa il prefisso `01-`, `02-` per controllare l'ordine - Solo i file corrispondenti a `*policies.{js,mjs,ts}` vengono caricati; gli altri file vengono ignorati - Ogni file viene caricato indipendentemente (fail-open per file) -- Funziona insieme a `--custom` espliciti e politiche incorporate +- Funziona insieme alle politiche esplicite `--custom` e integrate -Le politiche di convenzione sono il modo più semplice per costruire uno standard di qualità per la tua organizzazione. Committa `.failproofai/policies/` a git e ogni membro del team ottiene automaticamente le stesse regole — nessuna configurazione per sviluppatore necessaria. Man mano che il tuo team scopre nuove modalità di fallimento, aggiungi una politica e fai il push. Nel tempo questi diventano uno standard di qualità vivo che continua a migliorare con ogni contributo. +Le politiche di convenzione sono il modo più facile per costruire uno standard di qualità per la tua organizzazione. Committi `.failproofai/policies/` su git e ogni membro del team riceve automaticamente le stesse regole — non è necessaria una configurazione per sviluppatore. Man mano che il tuo team scopre nuove modalità di errore, aggiungi una politica e fai un push. Nel tempo questi diventano uno standard di qualità vivo che migliora continuamente ad ogni contributo. ### Opzione 2: Percorso file esplicito @@ -69,20 +70,25 @@ Le politiche di convenzione sono il modo più semplice per costruire uno standar # Installa con un file di politiche personalizzate failproofai policies --install --custom ./my-policies.js -# Sostituisci il percorso del file di politiche +# Sostituisci i percorsi delle politiche personalizzate failproofai policies --install --custom ./new-policies.js -# Rimuovi il percorso delle politiche personalizzate dalla configurazione +# Configura più file espliciti (caricati nell'ordine dei flag) +failproofai policies --install --custom ./security.js --custom ./workflow.js + +# Rimuovi tutti i percorsi delle politiche personalizzate esplicite dalla configurazione failproofai policies --uninstall --custom ``` -Il percorso assoluto risolto viene archiviato in `policies-config.json` come `customPoliciesPath`. Il file viene caricato nuovamente ad ogni evento hook — non c'è caching tra gli eventi. +I percorsi assoluti risolti vengono archiviati in `policies-config.json` come `customPoliciesPaths`. Ripeti `--custom` per configurare più file. Le configurazioni esistenti che utilizzano il campo legacy `customPoliciesPath` continuano a funzionare. I file vengono caricati nuovamente ad ogni evento hook - non c'è cache tra gli eventi. + +Ogni politica registrata appare con il suo interruttore nella dashboard. Disattivare una politica registra il suo ID qualificato dalla sorgente in `disabledCustomPolicies`; il file e le sue altre politiche continuano a caricarsi, mentre la politica disabilitata viene esclusa prima della corrispondenza degli eventi. I nomi delle politiche duplicati tra file hanno interruttori indipendenti. -### Usare entrambi insieme +### Usare insieme entrambi -Le politiche di convenzione e il file `--custom` esplicito possono coesistere. Ordine di caricamento: +Le politiche di convenzione e i file espliciti `--custom` possono coesistere. Ordine di caricamento: -1. File `customPoliciesPath` esplicito (se configurato) +1. File `customPoliciesPaths` espliciti (nell'ordine configurato) 2. File di convenzione di progetto (`{cwd}/.failproofai/policies/`, alfabetici) 3. File di convenzione utente (`~/.failproofai/policies/`, alfabetici) @@ -90,7 +96,7 @@ Le politiche di convenzione e il file `--custom` esplicito possono coesistere. O ## API -### Importazione +### Importa ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -98,7 +104,7 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Registra una politica. Chiamala tutte le volte che è necessario per più politiche nello stesso file. +Registra una politica. Chiama questa funzione tutte le volte che è necessario per più politiche nello stesso file. ```ts customPolicies.add({ @@ -109,34 +115,34 @@ customPolicies.add({ }); ``` -### Helper per decisioni +### Helper di decisione | Funzione | Effetto | Usa quando | |----------|--------|----------| -| `allow()` | Consenti l'operazione silenziosamente | L'azione è sicura, nessun messaggio necessario | -| `deny(message)` | Blocca l'operazione | L'agente non dovrebbe intraprendere questa azione | -| `instruct(message)` | Aggiungi contesto senza bloccare | Dai all'agente contesto aggiuntivo per stare sulla giusta strada | +| `allow()` | Permetti l'operazione silenziosamente | L'azione è sicura, nessun messaggio necessario | +| `deny(message)` | Blocca l'operazione | L'agente non deve intraprendere questa azione | +| `instruct(message)` | Aggiungi contesto senza bloccare | Dai all'agente contesto extra per stare sulla traccia giusta | -`deny(message)` - il messaggio appare a Claude con il prefisso `"Blocked by failproofai:"`. Un singolo `deny` fa cortocircuito su tutta la valutazione successiva. +`deny(message)` - il messaggio appare a Claude preceduto da `"Blocked by failproofai:"`. Un singolo `deny` bypassa tutta la valutazione successiva. `instruct(message)` - il messaggio viene aggiunto al contesto di Claude per la chiamata dello strumento corrente. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme. -Puoi aggiungere una guida aggiuntiva a qualsiasi messaggio `deny` o `instruct` aggiungendo un campo `hint` in `policyParams` — nessuna modifica del codice necessaria. Questo funziona anche per le politiche personalizzate (`custom/`), di convenzione di progetto (`.failproofai-project/`), e di convenzione utente (`.failproofai-user/`). Vedi [Configuration → hint](/it/configuration#hint-cross-cutting) per i dettagli. +Puoi aggiungere linee guida extra a qualsiasi messaggio `deny` o `instruct` aggiungendo un campo `hint` in `policyParams` — nessun cambio di codice necessario. Questo funziona anche per le politiche personalizzate (`custom/`), di convenzione di progetto (`.failproofai-project/`), e di convenzione utente (`.failproofai-user/`). Vedi [Configurazione → hint](/it/configuration#hint-cross-cutting) per i dettagli. ### Messaggi allow informativi -`allow(message)` consente l'operazione **e** invia un messaggio informativo a Claude. Il messaggio viene consegnato come `additionalContext` nella risposta stdout del gestore hook — lo stesso meccanismo utilizzato da `instruct`, ma semanticamente diverso: è un aggiornamento di stato, non un avviso. +`allow(message)` permette l'operazione **e** invia un messaggio informativo back a Claude. Il messaggio viene consegnato come `additionalContext` nella risposta stdout del gestore di hook — lo stesso meccanismo utilizzato da `instruct`, ma semanticamente diverso: è un aggiornamento di stato, non un avviso. | Funzione | Effetto | Usa quando | |----------|--------|----------| -| `allow(message)` | Consenti e invia contesto a Claude | Conferma che un controllo è passato, o spiega perché un controllo è stato saltato | +| `allow(message)` | Permetti e invia contesto a Claude | Conferma che un controllo è passato, o spiega perché un controllo è stato saltato | Casi d'uso: -- **Conferme di stato:** `allow("All CI checks passed.")` — comunica a Claude che tutto è verde -- **Spiegazioni fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — comunica a Claude perché un controllo è stato saltato in modo che abbia il contesto completo -- **Più messaggi si accumulano:** se più politiche restituiscono `allow(message)`, tutti i messaggi vengono uniti con newline e consegnati insieme +- **Conferme di stato:** `allow("All CI checks passed.")` — comunica a Claude che tutto è ok +- **Spiegazioni fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — comunica a Claude perché un controllo è stato saltato così ha il contesto completo +- **I messaggi multipli si accumulano:** se diverse politiche ciascuna restituiscono `allow(message)`, tutti i messaggi vengono uniti con newline e consegnati insieme ```js customPolicies.add({ @@ -160,25 +166,25 @@ customPolicies.add({ | Campo | Tipo | Descrizione | |-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | Lo strumento chiamato (ad es. `"Bash"`, `"Write"`, `"Read"`) | +| `toolName` | `string \| undefined` | Lo strumento in fase di chiamata (es. `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | I parametri di input dello strumento | -| `payload` | `Record` | Payload di evento completo grezzo da Claude Code | -| `session` | `SessionMetadata \| undefined` | Contesto di sessione (vedi sotto) | +| `payload` | `Record` | Payload dell'evento grezzo completo da Claude Code | +| `session` | `SessionMetadata \| undefined` | Contesto della sessione (vedi sotto) | ### Campi `SessionMetadata` | Campo | Tipo | Descrizione | |-------|------|-------------| -| `sessionId` | `string` | Identificatore di sessione Claude Code | -| `cwd` | `string` | Directory di lavoro della sessione Claude Code | -| `transcriptPath` | `string` | Percorso del file trascritto JSONL della sessione | +| `sessionId` | `string` | Identificatore della sessione di Claude Code | +| `cwd` | `string` | Directory di lavoro della sessione di Claude Code | +| `transcriptPath` | `string` | Percorso al file di trascrizione JSONL della sessione | ### Tipi di evento -| Evento | Quando si attiva | Contenuti `toolInput` | +| Evento | Quando si attiva | Contenuti di `toolInput` | |-------|--------------|----------------------| -| `PreToolUse` | Prima che Claude esegua uno strumento | L'input dello strumento (ad es. `{ command: "..." }` per Bash) | -| `PostToolUse` | Dopo il completamento di uno strumento | L'input dello strumento + `tool_result` (l'output) | +| `PreToolUse` | Prima che Claude esegua uno strumento | L'input dello strumento (es. `{ command: "..." }` per Bash) | +| `PostToolUse` | Dopo che uno strumento si completa | L'input dello strumento + `tool_result` (l'output) | | `Notification` | Quando Claude invia una notifica | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - gli hook devono sempre restituire `allow()`, non possono bloccare le notifiche | | `Stop` | Quando la sessione Claude termina | Vuoto | @@ -188,20 +194,20 @@ customPolicies.add({ Le politiche vengono valutate in questo ordine: -1. Politiche incorporate (in ordine di definizione) -2. Politiche personalizzate esplicite da `customPoliciesPath` (in ordine `.add()`) -3. Politiche di convenzione da `.failproofai/policies/` di progetto (file alfabetici, ordine `.add()` all'interno) -4. Politiche di convenzione da `~/.failproofai/policies/` utente (file alfabetici, ordine `.add()` all'interno) +1. Politiche integrate (nell'ordine di definizione) +2. Politiche personalizzate esplicite da `customPoliciesPath` (nell'ordine `.add()`) +3. Politiche di convenzione dal progetto `.failproofai/policies/` (file alfabetici, ordine `.add()` entro) +4. Politiche di convenzione da utente `~/.failproofai/policies/` (file alfabetici, ordine `.add()` entro) -Il primo `deny` fa cortocircuito su tutte le politiche successive. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme. +Il primo `deny` bypassa tutte le politiche successive. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme. --- ## Importazioni transitive -I file di politiche personalizzate possono importare moduli locali usando percorsi relativi: +I file delle politiche personalizzate possono importare moduli locali usando percorsi relativi: ```js // my-policies.js @@ -218,11 +224,11 @@ customPolicies.add({ }); ``` -Tutte le importazioni relative raggiungibili dal file di entry vengono risolte. Questo viene implementato riscrivendo le importazioni `from "failproofai"` al percorso dist effettivo e creando file `.mjs` temporanei per garantire compatibilità ESM. +Tutte le importazioni relative raggiungibili dal file di entry vengono risolte. Questo è implementato riscrivendo le importazioni `from "failproofai"` al percorso dist effettivo e creando file `.mjs` temporanei per garantire la compatibilità ESM. --- -## Filtraggio dei tipi di evento +## Filtro del tipo di evento Usa `match.events` per limitare quando una politica si attiva: @@ -231,33 +237,33 @@ customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Only fires when the session ends - // ctx.session.transcriptPath contains the full session log + // Solo si attiva quando la sessione termina + // ctx.session.transcriptPath contiene il log della sessione completo return allow(); }, }); ``` -Ometti completamente `match` per attivarsi su ogni tipo di evento. +Ometti `match` interamente per attivarsi su ogni tipo di evento. --- ## Gestione degli errori e modalità di fallimento -Le politiche personalizzate sono **fail-open**: gli errori non bloccano mai le politiche incorporate o fanno bloccare il gestore hook. +Le politiche personalizzate sono **fail-open**: gli errori non bloccano mai le politiche integrate o causano crash del gestore hook. -| Fallimento | Comportamento | +| Errore | Comportamento | |---------|----------| -| `customPoliciesPath` non impostato | Nessuna politica personalizzata esplicita viene eseguita; le politiche di convenzione e i built-in continuano normalmente | -| File non trovato | Avviso registrato in `~/.failproofai/hook.log`; i built-in continuano | -| Errore di sintassi/importazione (esplicito) | Errore registrato in `~/.failproofai/hook.log`; le politiche personalizzate esplicite vengono saltate | -| Errore di sintassi/importazione (convenzione) | Errore registrato; quel file saltato, gli altri file di convenzione continuano a caricarsi | -| `fn` genera un errore a runtime | Errore registrato; questo hook trattato come `allow`; gli altri hook continuano | -| `fn` richiede più di 10s | Timeout registrato; trattato come `allow` | +| `customPoliciesPath` non impostato | Nessuna politica personalizzata esplicita viene eseguita; le politiche di convenzione e integrate continuano normalmente | +| File non trovato | Avviso registrato su `~/.failproofai/hook.log`; integrate continuano | +| Errore di sintassi/importazione (esplicito) | Errore registrato su `~/.failproofai/hook.log`; politiche personalizzate esplicite saltate | +| Errore di sintassi/importazione (convenzione) | Errore registrato; quel file saltato, altri file di convenzione ancora caricati | +| `fn` genera errore a runtime | Errore registrato; quello hook trattato come `allow`; altri hook continuano | +| `fn` impiega più di 10s | Timeout registrato; trattato come `allow` | | Directory di convenzione mancante | Nessuna politica di convenzione viene eseguita; nessun errore | -Per eseguire il debug degli errori delle politiche personalizzate, osserva il file di registro: +Per debuggare errori di politiche personalizzate, guarda il file di log: ```bash tail -f ~/.failproofai/hook.log @@ -266,7 +272,7 @@ tail -f ~/.failproofai/hook.log --- -## Esempio completo: più politiche +## Esempio completo: politiche multiple ```js // my-policies.js @@ -327,27 +333,27 @@ La directory `examples/` contiene file di politiche pronti all'uso: | File | Contenuti | |------|----------| -| `examples/policies-basic.js` | Cinque politiche di avvio che coprono modalità di fallimento comuni degli agenti | -| `examples/policies-advanced/index.js` | Modelli avanzati: importazioni transitive, chiamate asincrone, scrubbing dell'output, e hook di fine sessione | +| `examples/policies-basic.js` | Cinque politiche iniziali che coprono modalità di errore comuni dell'agente | +| `examples/policies-advanced/index.js` | Pattern avanzati: importazioni transitive, chiamate async, scrubbing dell'output, hook di fine sessione | | `examples/convention-policies/security-policies.mjs` | Politiche di sicurezza basate su convenzione (blocca scritture .env, previeni riscrittura della cronologia git) | -| `examples/convention-policies/workflow-policies.mjs` | Politiche di flusso di lavoro basate su convenzione (promemoria dei test, file di audit writes) | +| `examples/convention-policies/workflow-policies.mjs` | Politiche di flusso di lavoro basate su convenzione (promemoria test, audit scritture file) | -### Utilizzo di esempi di file espliciti +### Usare esempi di file espliciti ```bash failproofai policies --install --custom ./examples/policies-basic.js ``` -### Utilizzo di esempi basati su convenzione +### Usare esempi basati su convenzione ```bash -# Copy to project level +# Copia a livello di progetto mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# Or copy to user level +# O copia a livello di utente mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -Nessun comando di installazione necessario — i file vengono prelevati automaticamente al prossimo evento hook. \ No newline at end of file +Nessun comando di installazione necessario — i file vengono raccolti automaticamente al prossimo evento hook. \ No newline at end of file diff --git a/docs/it/dashboard.mdx b/docs/it/dashboard.mdx index 3ba9d882..c3f69154 100644 --- a/docs/it/dashboard.mdx +++ b/docs/it/dashboard.mdx @@ -1,10 +1,11 @@ --- +--- title: Dashboard -description: "Monitora le sessioni degli agenti, rivedi le chiamate ai tool e gestisci le policy" +description: "Monitora le sessioni degli agenti, esamina le chiamate ai tool e gestisci le policy" icon: chart-line --- -Il dashboard failproofai è un'applicazione web locale per monitorare le tue sessioni di agenti AI e gestire le policy. Scopri cosa hanno fatto i tuoi agenti mentre eri via. +Il dashboard di failproofai è un'applicazione web locale per monitorare le sessioni dei tuoi agenti AI e gestire le policy. Scopri cosa hanno fatto i tuoi agenti mentre eri via. --- @@ -16,7 +17,7 @@ failproofai Si apre su `http://localhost:8020`. -Il dashboard legge i dati di configurazione del progetto locale, della sessione e di failproofai direttamente dal filesystem. Le funzionalità autenticate opzionali, come i promemoria di audit e gli inviti, inviano le informazioni necessarie per tali richieste (inclusi gli indirizzi email) a API remote. +Il dashboard legge i dati di configurazione locali del progetto, della sessione e di failproofai direttamente dal filesystem. Le funzionalità opzionali autenticate, come i promemoria di audit e gli inviti, inviano le informazioni necessarie per tali richieste (inclusi gli indirizzi email) alle API remote. --- @@ -24,67 +25,69 @@ Il dashboard legge i dati di configurazione del progetto locale, della sessione ### Progetti -Elenca tutti i progetti Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity e Goose trovati sulla tua macchina. I progetti Claude vengono individuati da `~/.claude/projects/` (o dal percorso impostato da `CLAUDE_PROJECTS_PATH`); i progetti Codex vengono individuati eseguendo la scansione di ogni trascrizione in `~/.codex/sessions///
/*.jsonl` e raggruppando per il `cwd` registrato nel primo record di ogni sessione; i progetti Copilot CLI vengono individuati eseguendo la scansione di ogni `~/.copilot/session-state//workspace.yaml` (configurabile tramite `COPILOT_HOME`) e raggruppando per il suo campo `cwd`; i progetti Cursor Agent vengono individuati eseguendo la scansione dei metadati per sessione in `~/.cursor/agent-sessions//` (configurabile tramite `CURSOR_HOME`, con `conversations/` e `sessions/` come fallback) per uno scalare `cwd` in `meta.json` / `session.json` / `workspace.yaml`; i progetti OpenCode vengono individuati interrogando il suo DB SQLite in `~/.local/share/opencode/opencode.db` tramite `opencode db --format json` (leggiamo le tabelle `session` e `project` e raggruppiamo per `project_id`); i progetti Pi vengono individuati eseguendo la scansione delle trascrizioni JSONL per sessione in `~/.pi/agent/sessions//_.jsonl` (configurabile tramite `PI_SESSIONS_DIR`) ed estraendo il `cwd` dal primo record di ogni sessione; le sessioni gateway Hermes vengono lette direttamente dal suo store SQLite in `~/.hermes/state.db` (configurabile tramite `HERMES_DB_PATH`) e raggruppate in progetti `hermes-` per `source` (Slack/Telegram/cli/cron — le sessioni gateway non hanno cwd); le sessioni gateway OpenClaw vengono lette da `~/.openclaw/agents//sessions/*.jsonl` e raggruppate in progetti `openclaw-` (anche senza cwd); i progetti Factory Droid vengono individuati dalle trascrizioni JSONL in `~/.factory/sessions//*.jsonl` e raggruppati per cwd; i progetti Devin dal suo DB SQLite in `~/.local/share/devin/cli/sessions.db` (raggruppati per `working_directory` di ogni sessione); i progetti Antigravity dalle trascrizioni JSONL in `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` e raggruppati per cwd; e i progetti Goose dal suo DB SQLite in `~/.local/share/goose/sessions/sessions.db` (raggruppati per `working_dir` di ogni sessione). Un progetto che è stato utilizzato da più CLI viene visualizzato come una singola riga con tutti i badge corrispondenti. Usa il menu a discesa **CLI** sopra la tabella per filtrare per uno specifico agent CLI; l'URL mantiene la tua selezione come `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +Elenca tutti i progetti Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity e Goose trovati sulla tua macchina. I progetti Claude vengono individuati da `~/.claude/projects/` (o il percorso impostato da `CLAUDE_PROJECTS_PATH`); i progetti Codex vengono individuati scansionando ogni transcript in `~/.codex/sessions///
/*.jsonl` e raggruppando per il `cwd` registrato nel primo record di ogni sessione; i progetti Copilot CLI vengono individuati scansionando ogni `~/.copilot/session-state//workspace.yaml` (configurabile tramite `COPILOT_HOME`) e raggruppando per il suo campo `cwd`; i progetti Cursor Agent vengono individuati scansionando i metadati per sessione in `~/.cursor/agent-sessions//` (configurabile tramite `CURSOR_HOME`, con `conversations/` e `sessions/` come fallback) per uno scalare `cwd` in `meta.json` / `session.json` / `workspace.yaml`; i progetti OpenCode vengono individuati interrogando il suo DB SQLite su `~/.local/share/opencode/opencode.db` tramite `opencode db --format json` (leggiamo le tabelle `session` e `project` e raggruppiamo per `project_id`); i progetti Pi vengono individuati scansionando i transcript JSONL per sessione in `~/.pi/agent/sessions//_.jsonl` (configurabile tramite `PI_SESSIONS_DIR`) e estraendo il `cwd` dal primo record di ogni sessione; le sessioni del gateway Hermes vengono lette direttamente dall'archivio SQLite di ogni profilo — `~/.hermes/state.db` più `~/.hermes/profiles//state.db` (sovrascrivibile tramite `HERMES_HOME` o `HERMES_DB_PATH` per un singolo database) — e raggruppate in progetti `hermes--` per profilo e `source` (Slack/Telegram/cli/cron — le sessioni del gateway non hanno cwd); le sessioni del gateway OpenClaw vengono lette da `~/.openclaw/agents//sessions/*.jsonl` e raggruppate in progetti `openclaw--` per agente e canale (senza cwd); i progetti Factory Droid vengono individuati dai transcript JSONL in `~/.factory/sessions//*.jsonl` e raggruppati per cwd; i progetti Devin dal suo DB SQLite su `~/.local/share/devin/cli/sessions.db` (raggruppati per `working_directory` di ogni sessione); i progetti Antigravity dai transcript JSONL in `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` e raggruppati per cwd; e i progetti Goose dal suo DB SQLite su `~/.local/share/goose/sessions/sessions.db` (raggruppati per il `working_dir` di ogni sessione). Un progetto utilizzato da più CLI appare come una singola riga con tutti i badge corrispondenti. Usa il dropdown **CLI** sopra la tabella per filtrare per uno specifico CLI agente; l'URL preserva la tua selezione come `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. + +Hermes e OpenClaw hanno ambito utente e non hanno una directory di lavoro per raggruppare, quindi vengono visualizzati come un **albero di cartelle espandibile** — profilo (o agente) al livello superiore, i suoi canali sottostanti — mentre ogni CLI basato su cwd rimane una riga piatta. Le righe delle cartelle sommano il conteggio delle sessioni e l'attività più recente di tutto ciò che contengono, le cartelle compresse vengono ricordate tra le visite e una ricerca per parola chiave espande tutto ciò che corrisponde. Ogni progetto mostra: - Nome del progetto (derivato dal percorso della cartella) - Un badge CLI — `Claude Code` (arancione), `OpenAI Codex` (viola), `GitHub Copilot` (blu), `Cursor Agent` (smeraldo), `OpenCode` (ambra), `Pi` (rosa), e/o `Hermes` (indaco) - Data dell'attività di sessione più recente -Fai clic su un progetto per visualizzare le sue sessioni. +Clicca su un progetto per vedere le sue sessioni. ### Sessioni Elenca tutte le sessioni all'interno di un progetto. Ogni sessione mostra: -- ID sessione +- ID della sessione - Timestamp di inizio e fine - Numero di chiamate ai tool -- Conteggio dell'attività degli hook (policy che sono state attivate) +- Conteggio dell'attività hook (policy che hanno scattato) -Utilizza il filtro per intervallo di date e la ricerca per ID sessione per restringere l'elenco. Le sessioni sono impaginate. +Usa il filtro dell'intervallo di date e la ricerca per ID sessione per restringere l'elenco. Le sessioni sono impaginate. -Fai clic su una sessione per aprire il visualizzatore di sessione. +Clicca su una sessione per aprire il visualizzatore della sessione. -### Visualizzatore di sessione +### Visualizzatore della sessione -Il visualizzatore di sessione risponde alla domanda chiave per gli agenti autonomi: cosa ha fatto l'agente e è rimasto in traccia? Un badge CLI accanto all'intestazione indica se la sessione è una trascrizione Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity o Goose. Mostra una cronologia di tutto ciò che è accaduto in una sessione: +Il visualizzatore della sessione risponde alla domanda chiave per gli agenti autonomi: cosa ha fatto l'agente e ha mantenuto la rotta? Un badge CLI accanto all'intestazione indica se la sessione è un transcript Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity o Goose. Mostra una timeline di tutto ciò che è accaduto in una sessione: -- **Messaggi** - Risposte di testo di Claude e prompt dell'utente +- **Messaggi** - Le risposte di testo di Claude e i prompt dell'utente - **Chiamate ai tool** - Ogni tool invocato da Claude, con il suo input e output -- **Attività delle policy** - Per ogni chiamata ai tool, quali policy sono state attivate e quale decisione hanno restituito +- **Attività delle policy** - Per ogni chiamata ai tool, quali policy hanno scattato e quale decisione hanno restituito -La barra delle statistiche in alto mostra la durata della sessione, il numero totale di chiamate ai tool e un riepilogo delle decisioni degli hook (conteggi allow / deny / instruct). +La barra delle statistiche in alto mostra la durata della sessione, il totale delle chiamate ai tool e un riepilogo delle decisioni hook (conteggi allow / deny / instruct). -Fai clic sul pulsante **Download Logs** per esportare la sessione. Per le sessioni Claude Code, Codex, Copilot, Cursor e Pi ottieni la trascrizione JSONL originale su disco byte per byte; per OpenCode (le cui sessioni risiedono in SQLite, non su disco) ottieni un documento JSON che rispecchia le tabelle sottostanti `session` / `messages` / `parts`. +Clicca sul pulsante **Download Logs** per esportare la sessione. Per le sessioni Claude Code, Codex, Copilot, Cursor e Pi ottieni il transcript JSONL originale su disco byte-per-byte; per OpenCode (le cui sessioni risiedono in SQLite, non su disco) ottieni un documento JSON che rispecchia le tabelle sottostanti `session` / `messages` / `parts`. ### Audit -Un rapporto guidato dalla personalità su come il tuo agente si è effettivamente comportato nelle sessioni passate. Esegue la stessa scansione dell'utility CLI `failproofai audit` ma la visualizza come un poster condivisibile a schermo singolo + quattro sezioni sotto il margine di piega: +Un rapporto guidato dalla personalità su come il tuo agente si è effettivamente comportato nelle sessioni passate. Esegue la stessa scansione del CLI `failproofai audit` ma la visualizza come un poster condivisibile a schermo unico + quattro sezioni sotto la piega: -1. **Poster** — riempie il primo viewport. Regione di cattura PNG autonoma con il wordmark failproof_ai + etichetta audit · indice archetipo (`№ NN di 08`) + data audit · punteggio numerico (0–100) + pillola di classificazione percentile (`top 15%`) · il nome dell'archetipo (uno di `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + striscia di 3 parole chiave · `// solo il N% degli agenti è questo archetipo` riga di rarità · sigillo in piastrella di 8×8 pixel · piè di pagina `audit yours → failproof.ai`. Tre pulsanti di condivisione si trovano appena fuori dalla casella di cattura: `post your archetype` (intent X), `share on linkedin`, `download poster`. La cattura viene eseguita attraverso `html-to-image` quindi il PNG corrisponde al rendering sullo schermo pixel per pixel (bordi tratteggiati, maschera logo SVG, gradienti, metriche dei caratteri — tutto conservato). -2. **Strengths** — elenco di righe calme ✓ di comportamenti che il tuo agente già fa bene, derivati dai dati di audit live (tasso di chiamata dei tool pulito, nessun push diretto a main, zero perdite di credenziali, zero tempeste di retry) — ognuno visualizzato solo quando la policy pertinente ha un record pulito nell'intervallo di audit. -3. **Quirks** — tabella di ciò che è sfuggito, classificata per gravità: `when · what slipped + the policy that would've caught it · severity pill · seen`, dove la ricorrenza legge `new` (una volta), `N× seen` (2–9 volte), o `recurring` (10+). -4. **How to improve** — elenco di righe calme, uno per policy prescritta: nome della policy in bianco, descrizione di una riga, comando di installazione + pulsante di copia sul lato destro. L'intestazione della sezione legge `enable all N → projected · ` (il punteggio che raggiungeresti con ogni correzione applicata), e il suo pulsante `[install all]` copia il comando combinato `failproofai policy add a b c …` per ogni policy prescritta. -5. **Come back better** — due schede affiancate. Sinistra: imposta un promemoria (selettore di cadenza `3d` / `7d` / `14d` / `30d`; persiste tramite `/api/auth/reminder` una volta autenticato). Destra: sblocca i vantaggi failproof — `invite a friend` apre un modale che accetta un elenco separato da virgole/spazi/newline di email amiche (max 10 per invio), le POST a `/api/audit/invite`, che inoltrano al `/v0/invite` del server api. Il server api invia un email per destinatario da `invite@failproof.ai` con il mittente in Cc e `Reply-To` impostato, quindi il destinatario vede chi lo ha invitato e il mittente riceve una copia nella sua inbox. Gli utenti anonimi vengono instradati attraverso `AuthDialog` prima in modo che l'email del mittente sia nota prima che gli inviti vengano inviati. La realizzazione dei diritti / vantaggi è un follow-up. +1. **Poster** — riempie il primo viewport. Regione di cattura PNG autonoma con il wordmark di failproof_ai + etichetta audit · indice archhetipo (`№ NN di 08`) + data audit · punteggio numerico (0–100) + pillola di classificazione percentile (`top 15%`) · il nome dell'archetipo (uno tra `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + striscia di 3 parole chiave · linea di rarità `// only N% of agents are this archetype` · sigillo a piastrella di pixel 8×8 · piè di pagina `audit yours → failproof.ai`. Tre pulsanti di condivisione si trovano appena fuori la casella di cattura: `post your archetype` (intent X), `share on linkedin`, `download poster`. La cattura viene eseguita tramite `html-to-image` quindi il PNG corrisponde al rendering su schermo pixel per pixel (bordi tratteggiati, maschera logo SVG, gradienti, metriche caratteri — tutto preservato). +2. **Strengths** — elenco di righe tranquille ✓ dei comportamenti che il tuo agente già fa bene, derivati dai dati di audit live (tasso di chiamata ai tool pulito, nessun push diretto a main, zero perdite di credenziali, zero tempeste di retry) — ciascuno visualizzato solo quando la policy rilevante ha un record pulito nella finestra di audit. +3. **Quirks** — tabella di cosa è passato inosservato, ordinato per gravità: `when · what slipped + the policy that would've caught it · severity pill · seen`, dove la ricorrenza legge `new` (una volta), `N× seen` (2–9 volte), o `recurring` (10+). +4. **How to improve** — elenco di righe tranquille, una per policy prescritta: nome della policy in bianco, descrizione di una riga, comando di installazione + pulsante di copia sul lato destro. L'intestazione della sezione legge `enable all N → projected · ` (il punteggio che raggiungeresti con ogni correzione applicata), e il suo pulsante `[install all]` copia il comando combinato `failproofai policy add a b c …` per ogni policy prescritta. +5. **Come back better** — due schede affiancate. Sinistra: imposta un promemoria (selettore cadenza `3d` / `7d` / `14d` / `30d`; persiste tramite `/api/auth/reminder` una volta autenticato). Destra: sblocca i vantaggi di failproof — `invite a friend` apre una finestra modale che accetta un elenco di email di amici separato da virgola/spazio/nuova riga (max 10 per invio), li invia tramite POST a `/api/audit/invite`, che viene inoltrato al `POST /v0/invite` dell'api-server. L'api-server invia un'email per ogni destinatario da `invite@failproof.ai` con il mittente in Cc e `Reply-To` impostato, quindi il destinatario vede chi lo ha invitato e il mittente riceve una copia nella sua inbox. Gli utenti anonimi vengono instradati tramite `AuthDialog` prima affinché l'email del mittente sia conosciuta prima che gli inviti vengano inviati. L'adempimento dei diritti / vantaggi è un seguito. -Gestito dal runtime `failproofai audit` — vedere [Audit CLI](/it/cli/audit) per il motore di scansione sottostante, i flag supportati e gli invarianti di cache per trascrizione. Il dashboard memorizza nella cache il risultato più recente in `~/.failproofai/audit-dashboard.json` (modalità `0600`, slot singolo, i nuovi run sovrascrivono) quindi i revisit sono istantanei; **sia la cache per trascrizione che il risultato complessivo vengono rifiutati alla lettura una volta che hanno più di 7 giorni** quindi il dashboard non serve mai in silenzio un risultato vecchio di una settimana — dopo il TTL `/audit` ricade nel suo stato vuoto e richiede una nuova esecuzione. Facendo clic su `[ re-audit now ]` vicino al fondo del rapporto POST su `/api/audit/run` con `noCache: true` — il re-audit ignora la cache per trascrizione e scansiona ogni trascrizione da zero piuttosto che restituire silenziosamente il risultato memorizzato nella cache — e il dashboard esegue il polling su `/api/audit/status` a 1Hz fino al completamento dell'esecuzione; una striscia di progresso rosa appiccicosa si fissa nella parte superiore del viewport durante l'esecuzione con un timer trascorso, e il risultato aggiornato si sostituisce in posizione al successo (nessun ricarico della pagina intera; un re-audit fallito lascia il rapporto precedente intatto). In caso di errore la striscia diventa rossa con la copia basata su `RerunError.kind` (`timeout` / `network` / `post_failed`). Lo stato vuoto (nessuna cache o scaduta) e lo stato zero-sessioni (cache esiste ma la scansione non ha trovato trascrizioni) vengono visualizzati separatamente. +Guidato dal runtime `failproofai audit` — vedi [Audit CLI](/it/cli/audit) per il motore di scansione sottostante, i flag supportati e gli invarianti della cache per transcript. Il dashboard memorizza il risultato più recente su `~/.failproofai/audit-dashboard.json` (modalità `0600`, slot singolo, le nuove esecuzioni sovrascrivono) quindi le revisitazioni sono istantanee; **sia la cache per transcript che il risultato completo vengono rifiutati in lettura una volta che hanno più di 7 giorni** quindi il dashboard non serve mai silenziosamente un risultato di una settimana fa — dopo il TTL `/audit` passa allo stato vuoto e richiede una nuova esecuzione. Facendo clic su `[ re-audit now ]` vicino al fondo del rapporto si invia un POST a `/api/audit/run` con `noCache: true` — re-audit bypassa la cache per transcript e ripete la scansione di ogni transcript da zero piuttosto che restituire silenziosamente il risultato memorizzato — e il dashboard esegue il polling di `/api/audit/status` a 1Hz fino al termine dell'esecuzione; una striscia di progresso rosa appiccicatizia si blocca in cima al viewport durante l'esecuzione con un timer trascorso e il risultato aggiornato sostituisce quello precedente (nessun ricaricamento della pagina completa; un re-audit fallito lascia intatto il rapporto precedente). In caso di errore la striscia diventa rossa con copia basata su `RerunError.kind` (`timeout` / `network` / `post_failed`). Lo stato vuoto (nessuna cache o scaduta) e lo stato zero-sessioni (cache esiste ma la scansione non ha trovato transcript) vengono visualizzati separatamente. ### Policy -Una pagina a due schede per gestire le policy e rivedere l'attività. +Una pagina a due schede per gestire le policy e controllare l'attività. - - - Selezione multipla di quali agent CLI failproofai protegge da un singolo pannello — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi e Hermes hanno tutti una riga con stato di installazione (`Active` / `Detected` / `Inactive`), il percorso delle impostazioni nell'ambito dell'utente e un accento di marca colorato. Seleziona o deseleziona i CLI che desideri e fai clic su `Apply changes` per installare/disinstallare la differenza in un unico passaggio. I CLI il cui binario è rilevato su PATH vengono pre-selezionati. - - Attiva o disattiva le singole policy con un singolo clic (scrive su `~/.failproofai/policies-config.json` — condiviso tra ogni CLI installato) - - Espandi una policy per configurare i suoi parametri (per le policy che supportano `policyParams`) - - Imposta un percorso file delle policy personalizzato + + - Selezione multipla di quali CLI agenti failproofai protegge da un singolo pannello — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi e Hermes hanno tutti una riga con stato di installazione (`Active` / `Detected` / `Inactive`), il percorso delle impostazioni con ambito utente e un accento colorato del marchio. Seleziona o deseleziona i CLI che desideri e fai clic su `Apply changes` per installare/disinstallare il diff in un solo passaggio. I CLI il cui binario è rilevato su PATH sono pre-selezionati. + - Attiva o disattiva le singole policy con un solo clic (scrive su `~/.failproofai/policies-config.json` — condiviso tra ogni CLI installato) + - Espandi una policy per configurare i suoi parametri (per policy che supportano `policyParams`) + - Imposta un percorso file di policy personalizzato - - Cronologia completa impaginata di ogni evento hook che si è attivato in tutte le sessioni + - Cronologia impaginata completa di ogni evento hook che ha scattato in tutte le sessioni - Filtra per decisione, tipo di evento, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), nome della policy o ID della sessione - - Ogni riga mostra: timestamp, nome della policy, decisione, badge CLI (arancione = Claude Code, viola = OpenAI Codex, blu = GitHub Copilot, smeraldo = Cursor Agent, ambra = OpenCode, rosa = Pi, indaco = Hermes, verde acqua = OpenClaw, rosa chiaro = Factory Droid, viola = Devin, ciano = Antigravity, lime = Goose), nome del tool, ID della sessione e il motivo delle decisioni deny/instruct - - Fai clic su un ID di sessione per aprire la sua trascrizione — il visualizzatore rileva automaticamente quale CLI ha attivato l'hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) e visualizza il badge CLI corrispondente nell'intestazione + - Ogni riga mostra: timestamp, nome della policy, decisione, badge CLI (arancione = Claude Code, viola = OpenAI Codex, blu = GitHub Copilot, smeraldo = Cursor Agent, ambra = OpenCode, rosa = Pi, indaco = Hermes, teal = OpenClaw, rosa scuro = Factory Droid, viola = Devin, azzurro = Antigravity, verde lime = Goose), nome del tool, ID della sessione e il motivo per le decisioni deny/instruct + - Clicca su un ID sessione per aprire il suo transcript — il visualizzatore rileva automaticamente quale CLI ha attivato l'hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) e visualizza il badge CLI corrispondente nell'intestazione @@ -92,11 +95,11 @@ Una pagina a due schede per gestire le policy e rivedere l'attività. ## Auto-refresh -Il dashboard ha un interruttore di auto-refresh nella navigazione superiore. Quando abilitato, la pagina corrente si aggiorna periodicamente per mostrare nuove sessioni e attività di policy man mano che appaiono. Essenziale per monitorare le sessioni di agenti autonomi di lunga durata. +Il dashboard ha un interruttore auto-refresh nella navigazione superiore. Quando abilitato, la pagina corrente si aggiorna periodicamente per mostrare nuove sessioni e attività di policy man mano che compaiono. Essenziale per monitorare sessioni di agenti autonomi a lunga esecuzione. --- -## Disabilitazione delle pagine +## Disabilitazione di pagine Se hai bisogno solo di alcune parti del dashboard, imposta `FAILPROOFAI_DISABLE_PAGES` su un elenco separato da virgole di nomi di pagine: @@ -110,7 +113,7 @@ Valori validi: `policies`, `projects`, `audit`. ## Configurazione del percorso dei progetti -Per impostazione predefinita, il dashboard legge dalla directory dei progetti Claude Code standard. Sovrascrivi per configurazioni personalizzate: +Per impostazione predefinita, il dashboard legge dalla directory dei progetti Claude Code standard. Sostituiscilo per configurazioni personalizzate: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,13 +123,13 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## Accesso da un host non-localhost -Quando si esegue il dashboard in **modalità dev** (`npm run dev`) e si accede da un nome host diverso da `localhost` - ad esempio, un dominio personalizzato, un IP remoto o un URL con tunnel — potresti visualizzare un avviso come: +Quando esegui il dashboard in **modalità dev** (`npm run dev`) e lo accedi da un hostname diverso da `localhost` - per esempio, un dominio personalizzato, un IP remoto o un URL in tunneling - potresti vedere un avviso come: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Questo è Next.js che blocca l'accesso cross-origin al suo websocket HMR (hot module reload), che è una funzionalità solo per lo sviluppo. Per consentire il tuo host, usa il flag `--allowed-origins`: +Questo è Next.js che blocca l'accesso cross-origin al suo websocket HMR (hot module reload), che è una funzionalità solo di sviluppo. Per consentire il tuo host, usa il flag `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -138,12 +141,12 @@ Per più host o IP, passa un elenco separato da virgole: npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -Puoi anche impostare la variabile d'ambiente `FAILPROOFAI_ALLOWED_DEV_ORIGINS`: +Puoi anche impostare la variabile di ambiente `FAILPROOFAI_ALLOWED_DEV_ORIGINS` in alternativa: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Questo si applica solo alla modalità dev. Quando si esegue `failproofai` (modalità produzione), non c'è websocket HMR e nessun problema di risorsa dev cross-origin. +Questo si applica solo alla modalità di sviluppo. Quando esegui `failproofai` (modalità produzione), non c'è alcun websocket HMR e nessun problema di risorsa dev cross-origin. \ No newline at end of file diff --git a/docs/ja/configuration.mdx b/docs/ja/configuration.mdx index 3249b28b..4ed09477 100644 --- a/docs/ja/configuration.mdx +++ b/docs/ja/configuration.mdx @@ -1,24 +1,24 @@ --- title: 設定 -description: "設定ファイルのフォーマット、3つのスコープ、マージルール" +description: "設定ファイルのフォーマット、3スコープシステム、およびマージルール" icon: gear --- -failproofai は JSON 設定ファイルを使用して、どのポリシーを有効にするか、それらの動作、カスタムポリシーのロード元を制御します。設定はチームと共有しやすい設計になっています。リポジトリにコミットすれば、すべての開発者が同じエージェントの安全網を利用できます。 +failproofai は JSON 設定ファイルを使用して、どのポリシーが有効か、どのように動作するか、カスタムポリシーをどこから読み込むかを制御します。設定はチームと共有しやすいよう設計されています。リポジトリにコミットすれば、すべての開発者が同じエージェントセーフティネットを利用できます。 --- ## 設定スコープ -設定には3つのスコープがあり、優先順位の高い順に評価されます： +優先順位の高い順に評価される3つの設定スコープがあります： -| スコープ | ファイルパス | 目的 | +| スコープ | ファイルパス | 用途 | |-------|-----------|---------| | **project** | `.failproofai/policies-config.json` | リポジトリごとの設定。バージョン管理にコミット | -| **local** | `.failproofai/policies-config.local.json` | 個人用のリポジトリごとの上書き設定。gitignore 対象 | -| **global** | `~/.failproofai/policies-config.json` | すべてのプロジェクトに適用されるユーザーレベルのデフォルト | +| **local** | `.failproofai/policies-config.local.json` | 個人のリポジトリごとの上書き設定。gitignore済み | +| **global** | `~/.failproofai/policies-config.json` | すべてのプロジェクトに適用するユーザーレベルのデフォルト | -failproofai がフックイベントを受信すると、現在の作業ディレクトリに存在する3つのファイルすべてをロードしてマージします。 +failproofai がフックイベントを受信すると、現在の作業ディレクトリに存在する3つのファイルをすべて読み込んでマージします。 ### マージルール @@ -29,10 +29,10 @@ project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← 重複を除いた和集合 +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← 重複除去した和集合 ``` -**`policyParams`** — 特定のポリシーに対してパラメーターを定義した最初のスコープが完全に優先されます。ポリシーのパラメーター内での深いマージは行われません。 +**`policyParams`** — 特定のポリシーのパラメーターを定義している最初のスコープが優先されます。ポリシーのパラメーター内の値は深くマージされません。 ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -42,16 +42,18 @@ resolved: { allowPatterns: ["sudo apt-get update"] } ← project が優先、g ``` ```text -project: (block-sudo のエントリなし) -local: (block-sudo のエントリなし) +project: (block-sudo エントリなし) +local: (block-sudo エントリなし) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← global にフォールスルー ``` -**`customPoliciesPath`** — 最初に定義したスコープが優先されます。 +**`customPoliciesPaths` / `customPoliciesPath`** — どちらかの形式を定義している最初のスコープが優先されます。 -**`llm`** — 最初に定義したスコープが優先されます。 +**`disabledCustomPolicies`** — すべてのスコープの和集合。ダッシュボードが明示的またはコンベンションポリシーファイルから個別のポリシーをオフにすると、ここにソース修飾IDが書き込まれます。リストされていないポリシーはデフォルトで有効のままです。IDにはソースファイルが含まれるため、複数のファイルに同名のポリシーがある場合でも個別に制御できます。 + +**`llm`** — 定義している最初のスコープが優先されます。 --- @@ -100,29 +102,29 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global にフォー ### `enabledPolicies` -型: `string[]` +型：`string[]` 有効にするポリシー名のリスト。名前は `failproofai policies` で表示されるポリシー識別子と完全に一致する必要があります。完全なリストは[組み込みポリシー](/ja/built-in-policies)を参照してください。 -`enabledPolicies` に含まれていないポリシーは、`policyParams` にエントリがあっても無効です。 +`enabledPolicies` に含まれていないポリシーは、`policyParams` にエントリがあっても非アクティブです。 ### `policyParams` -型: `Record>` +型：`Record>` ポリシーごとのパラメーター上書き設定。外側のキーはポリシー名、内側のキーはポリシー固有のものです。各ポリシーで使用可能なパラメーターは[組み込みポリシー](/ja/built-in-policies)に記載されています。 -ポリシーにパラメーターがある場合でも指定しなければ、そのポリシーの組み込みデフォルト値が使用されます。`policyParams` を設定しないユーザーは、以前のバージョンと同じ動作になります。 +ポリシーにパラメーターがあっても指定しない場合、ポリシーの組み込みデフォルト値が使用されます。`policyParams` をまったく設定しないユーザーは、以前のバージョンと同じ動作になります。 -ポリシーのパラメーターブロック内の未知のキーは、フック実行時には無視されますが、`failproofai policies` を実行すると警告として表示されます。 +ポリシーのparamsブロック内の未知のキーは、フック実行時には無視されますが、`failproofai policies` 実行時に警告としてフラグが立てられます。 #### `hint`（横断的設定） -型: `string`（省略可能） +型：`string`（省略可能） -ポリシーが `deny` または `instruct` を返す際に、理由として追記されるメッセージです。ポリシー自体を変更せずに Claude へ具体的な指示を伝えるために使用します。 +ポリシーが `deny` または `instruct` を返したときに理由に追加されるメッセージ。ポリシー自体を変更せずに Claude に実行可能なガイダンスを与えるために使用します。 -組み込み、カスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）など、あらゆるポリシータイプで使用できます。 +組み込み、カスタム（`custom/`）、プロジェクトコンベンション（`.failproofai-project/`）、ユーザーコンベンション（`.failproofai-user/`）など、あらゆるポリシータイプで使用できます。 ```json { @@ -141,40 +143,40 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global にフォー } ``` -`block-force-push` が拒否する場合、Claude には次のように表示されます：*「Force-pushing is blocked. Try creating a fresh branch instead.」* +`block-force-push` が拒否した場合、Claude には次のように表示されます：*「Force-pushing is blocked. Try creating a fresh branch instead.」* -文字列以外の値や空文字列は無視されます。`hint` が設定されていない場合は従来の動作と変わりません（後方互換性あり）。 +文字列以外の値や空文字列は無視されます。`hint` が設定されていない場合、動作は変わりません（後方互換性があります）。 ### `customPoliciesPath` -型: `string`（絶対パス） +型：`string`（絶対パス） カスタムフックポリシーを含む JavaScript ファイルへのパス。`failproofai policies --install --custom ` によって自動的に設定されます（パスは保存前に絶対パスに解決されます）。 -ファイルはフックイベントのたびに再読み込みされます。キャッシュは行われません。作成方法の詳細は[カスタムポリシー](/ja/custom-policies)を参照してください。 +ファイルはフックイベントのたびに新たに読み込まれます。キャッシュはありません。作成の詳細については[カスタムポリシー](/ja/custom-policies)を参照してください。 -### 規約ベースのポリシー +### コンベンションベースのポリシー -明示的な `customPoliciesPath` に加えて、failproofai は `.failproofai/policies/` ディレクトリからポリシーファイルを自動的に検出してロードします： +明示的な `customPoliciesPath` に加えて、failproofai は `.failproofai/policies/` ディレクトリからポリシーファイルを自動的に検出して読み込みます： | レベル | ディレクトリ | スコープ | |-------|-----------|-------| -| プロジェクト | `.failproofai/policies/` | バージョン管理を通じてチームと共有 | +| プロジェクト | `.failproofai/policies/` | バージョン管理でチームと共有 | | ユーザー | `~/.failproofai/policies/` | 個人用。すべてのプロジェクトに適用 | -**ファイルのマッチング:** `*policies.{js,mjs,ts}` に一致するファイルのみロードされます（例：`security-policies.mjs`、`workflow-policies.js`）。ディレクトリ内のその他のファイルは無視されます。 +**ファイルマッチング：** `*policies.{js,mjs,ts}` にマッチするファイルのみ読み込まれます（例：`security-policies.mjs`、`workflow-policies.js`）。ディレクトリ内の他のファイルは無視されます。 -**設定不要:** 規約ポリシーは `policies-config.json` へのエントリが不要です。ディレクトリにファイルを置くだけで、次のフックイベント時に自動的に読み込まれます。 +**設定不要：** コンベンションポリシーは `policies-config.json` へのエントリが不要です。ディレクトリにファイルを置くだけで、次のフックイベント時に自動的に読み込まれます。 -**ユニオンロード:** プロジェクトとユーザーの規約ディレクトリが両方スキャンされます。両方のレベルから一致したすべてのファイルがロードされます（`customPoliciesPath` が最初のスコープ優先なのとは異なります）。 +**ユニオン読み込み：** プロジェクトとユーザーのコンベンションディレクトリの両方がスキャンされます。両方のレベルからすべてのマッチするファイルが読み込まれます（最初のスコープ優先を使用する `customPoliciesPath` とは異なります）。 -詳細と例は[カスタムポリシー](/ja/custom-policies)を参照してください。 +詳細と例については[カスタムポリシー](/ja/custom-policies)を参照してください。 ### `llm` -型: `object`（省略可能） +型：`object`（省略可能） -AI 呼び出しを行うポリシーのための LLM クライアント設定。ほとんどの環境では不要です。 +AI呼び出しを行うポリシー向けの LLM クライアント設定。ほとんどのセットアップでは必要ありません。 ```json { @@ -189,19 +191,24 @@ AI 呼び出しを行うポリシーのための LLM クライアント設定。 ## CLI からの設定管理 -`policies --install` および `policies --uninstall` コマンドはエージェント CLI のフック設定ファイル（フックエントリポイント）に書き込みますが、`policies-config.json` は直接管理するファイルです。両者は別々のものです： - -- **エージェント CLI の設定** — エージェントがツール使用のたびに `failproofai --hook ` を呼び出すよう指示します： - - **Claude Code**: `~/.claude/settings.json`（ユーザー）、`/.claude/settings.json`（プロジェクト）、`/.claude/settings.local.json`（ローカル） - - **OpenAI Codex**: `~/.codex/hooks.json`（ユーザー）、`/.codex/hooks.json`（プロジェクト）— Codex には `local` スコープがありません - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json`（ユーザー）、`/.github/hooks/failproofai.json`（プロジェクト）— Copilot には `local` スコープがありません。フックエントリは Copilot の OS キー付き `bash`/`powershell` コマンドフィールドと `timeoutSec` を使用し、ファイルにはトップレベルの `version: 1` マーカーが付きます。`events.jsonl` レコードスキーマ（公開ドキュメントに記載なし）を実際の使用環境で検証中のため、Copilot CLI のサポートは**ベータ版**です。 - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json`（ユーザー）、`/.cursor/hooks.json`（プロジェクト）— Cursor には `local` スコープがありません。フックエントリは Claude 形式の `{type, command, timeout}` を使用しますが、Cursor の[フックスキーマ](https://cursor.com/docs/hooks)に従いキャメルケースのイベントキー（`preToolUse`、`beforeSubmitPrompt` など）のフラット配列として保存され、ファイルにはトップレベルの `version: 1` マーカーが付きます。ハンドラーは `CURSOR_EVENT_MAP` を通じてキャメルケース → PascalCase に正規化するため、既存の組み込みポリシーはそのまま動作します。Cursor のトランスクリプトのオンディスクフォーマット（公開ドキュメントに未記載）を実際の環境で検証中のため、Cursor Agent のサポートは**ベータ版**です。 - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs`（ユーザー）、`/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs`（プロジェクト）— OpenCode には `local` スコープがありません。他の5つの CLI とは異なり、OpenCode には**外部コマンドフックシステムがありません**。`opencode.json` の `plugin: []` 配列で明示的に登録された JS/TS プラグインをインプロセスでロードします（`.opencode/plugins/` からの自動検出は opencode v1.14.33 でのプラグインロード方法では**ありません**）。インストール時に小さな生成プラグインシムが配置され、failproofai バイナリをサブプロセスで呼び出し、バイナリの Claude 形式 JSON レスポンスをプラグインセマンティクスに変換します：ツールイベントの deny には `throw new Error()`（ツール呼び出しをキャンセル）、instruct および `Stop` / `SubagentStop` の deny には `client.session.prompt(...)`（deny の理由を次のユーザーメッセージとして送信 — `session.idle` が通知専用で例外をスローしても無効なため、強制リトライの唯一のチャネル）、allow には no-op を使用します。シムはツール名（小文字 → `OPENCODE_TOOL_MAP` を通じた PascalCase）とツール入力引数のキー（`OPENCODE_TOOL_INPUT_MAP` を通じたキャメルケース → スネークケース：`Read` / `Write` / `Edit` の `filePath` → `file_path`、`oldString` → `old_string` など）を正規化してからバイナリに転送するため、`block-read-outside-cwd`、`block-env-files`、`block-secrets-write` などのパスチェック組み込みポリシーは OpenCode のツール呼び出しでもそのまま動作します。セッションは `~/.local/share/opencode/opencode.db` の OpenCode の SQLite DB に保存され、ダッシュボードのセッションビューアーは `opencode db --format json` と `opencode export ` を通じて読み取ります。バージョン間の動作や実際の使用環境での検証中のため、OpenCode のサポートは**ベータ版**です。[OpenCode プラグインドキュメント](https://opencode.ai/docs/plugins/)を参照してください。 - - **Pi _(beta)_**: `~/.pi/agent/settings.json`（ユーザー）、`/.pi/settings.json`（プロジェクト）— Pi には `local` スコープがありません。Pi は起動時に TypeScript 拡張パッケージをロードします。設定ファイルはフラットな文字列配列 `{"packages": ["./relative/path", …]}` です。failproofai はバンドルされた `pi-extension/` ディレクトリを指す単一の packages 配列エントリを書き込みます。拡張機能は内部で Pi の `tool_call` / `user_bash` / `input` / `session_start` イベントを購読し、`failproofai --hook --cli pi` をシェルアウトします。ハンドラーは `PI_EVENT_MAP` を通じてアンダースコア付き小文字スネークケース → PascalCase に正規化するため、既存の組み込みポリシーはそのまま動作します。ツール入力引数も `PI_TOOL_INPUT_MAP` を通じて正規化されます（Pi の Read / Write / Edit は `file_path` ではなく `path` を使用。トップレベルキーのマッピングにより `block-env-files` と `block-secrets-write` が動作します — `block-read-outside-cwd` にはすでに `path` フォールバックがあります）。Pi の拡張 API とセッションログのレイアウトが安定化するまで Pi のサポートは**ベータ版**です。 - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml`（**ユーザースコープのみ** — Hermes にはプロジェクト/ローカル設定がありません）。Hermes は Slack/Telegram の**ゲートウェイ**であるため、1回のインストールでSlack/Telegram/cli/cron など全プラットフォームからのツール呼び出しと内部サブエージェントを傍受します。フックエントリは Hermes のスネークケースイベント（`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`）をキーとする `hooks:` マップ下の `{command, timeout}` ペア（タイムアウトは**秒**単位）です。ハンドラーは `HERMES_EVENT_MAP` でイベントを、`HERMES_TOOL_MAP` でツール名を正規化するため、組み込みポリシーはそのまま動作します。設定はコメントを保持する YAML `Document` のラウンドトリップで編集されるため、オペレーターの他の設定は保持されます。インストール時に `hooks_auto_accept: true` が設定されるため、ヘッドレスゲートウェイ（TTY なし）は同意プロンプトなしでフックを実行します。評価器は Hermes の `{"decision":"block","reason"}` stdout 契約を出力します（Hermes は終了コードを無視）。**制限事項:** Hermes にはターン終了の `Stop` イベントがないため、`require-*-before-stop` 組み込みポリシーは動作しません（非適用、バグではありません）。`instruct` は allow-with-logged-note に降格します（追加コンテキストチャネルなし）。出力シークレットのリダクション（`sanitize-*`）はシェルフックの契約上ツール出力を書き換えられません。Hermes は**オフライン監査**ソースでもあり、ダッシュボードはゲートウェイセッションを `~/.hermes/state.db` から直接読み取ります。 -- **`policies-config.json`** — failproofai が評価するポリシーとそのパラメーターを指定します（すべてのエージェント CLI で共有） - -特定のエージェントを対象にするには `--cli claude|codex|copilot|cursor|opencode|pi|hermes` を渡します（スペース区切りまたは繰り返しで複数指定可能）： +`policies --install` と `policies --uninstall` コマンドはエージェント CLI のフック設定ファイル（フックエントリポイント）に書き込みます。一方、`policies-config.json` は直接管理するファイルです。この2つは別々のものです： + +- **エージェント CLI の設定** — ツール使用のたびにエージェントが `failproofai --hook ` を呼び出すよう設定します： + - **Claude Code**：`~/.claude/settings.json`（ユーザー）、`/.claude/settings.json`（プロジェクト）、`/.claude/settings.local.json`（ローカル） + - **OpenAI Codex**：`~/.codex/hooks.json`（ユーザー）、`/.codex/hooks.json`（プロジェクト）— Codex には `local` スコープがありません + - **GitHub Copilot CLI _(ベータ版)_**：`~/.copilot/hooks/failproofai.json`（ユーザー）、`/.github/hooks/failproofai.json`（プロジェクト）— Copilot には `local` スコープがありません。フックエントリは Copilot の OS キー付き `bash`/`powershell` コマンドフィールドと `timeoutSec` を使用し、ファイルにはトップレベルの `version: 1` マーカーが含まれます。Copilot CLI サポートは、公開ドキュメントに仕様のない `events.jsonl` レコードスキーマを実際のセッションでさらに検証中のため、**ベータ版**です。**VS Code Copilot Chat エージェントモード（プレビュー）** は `.github/hooks/*.json`、`~/.copilot/hooks/*.json`、`~/.claude/settings.json`（`chat.hookFilesLocations` 設定で制御）からフック設定を読み込み、Claude 形式の `{hookSpecificOutput:{permissionDecision:"deny",…}}` コントラクトを使用します。これらは `copilot` インテグレーションと `claude` インテグレーション（`~/.claude/settings.json`）がすでに書き込んでいる正確なパスのため、`failproofai policies --install --cli copilot`（または `--cli claude`）は **VS Code エージェントモードでも追加の `vscode` インテグレーションなしにすでに適用されます**（VS Code の検出ログから実際に確認済み）。 + - **Cursor Agent _(ベータ版)_**：`~/.cursor/hooks.json`（ユーザー）、`/.cursor/hooks.json`（プロジェクト）— Cursor には `local` スコープがありません。フックエントリは Claude 形式の `{type, command, timeout}` 形式（`bash`/`powershell` の分割なし）を使用しますが、Cursor の[フックスキーマ](https://cursor.com/docs/hooks)に従ってキャメルケースのイベントキー（`preToolUse`、`beforeSubmitPrompt` など）配下のフラットな配列に格納されます。ファイルにはトップレベルの `version: 1` マーカーが含まれます。ハンドラーは `CURSOR_EVENT_MAP` を介してキャメルケースをパスカルケースに正規化するため、既存の組み込みポリシーは変更なく動作します。Cursor Agent サポートは、公開ドキュメントに仕様のない Cursor のトランスクリプトのディスク上フォーマットを実際のインストールでさらに検証中のため、**ベータ版**です。 + - **OpenCode _(ベータ版)_**：`~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs`（ユーザー）、`/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs`（プロジェクト）— OpenCode には `local` スコープがありません。他の5つの CLI とは異なり、OpenCode には**外部コマンドフックシステムがありません**：`opencode.json` の `plugin: []` 配列で明示的に登録された JS/TS プラグインをインプロセスで読み込みます（`.opencode/plugins/` からの自動検出は opencode v1.14.33 でのプラグイン読み込み方法では**ありません**）。インストール時に、failproofai バイナリをサブプロセスで呼び出し、バイナリの Claude 形式 JSON レスポンスをプラグインセマンティクスに変換する小さな生成プラグインシムを配置します：ツールイベントの拒否には `throw new Error()`（ツール呼び出しをキャンセル）、instruct と `Stop` / `SubagentStop` の拒否には `client.session.prompt(...)`（次のユーザーメッセージとして拒否理由を送信 — `session.idle` は通知のみで、そこからのスローはnopのため、唯一の強制リトライチャンネル）、allow には nop。シムはツール名（小文字→パスカルケース、`OPENCODE_TOOL_MAP` を使用）とツール入力の引数キー（キャメルケース→スネークケース、`Read` / `Write` / `Edit` に `OPENCODE_TOOL_INPUT_MAP` を使用、例：`filePath` → `file_path`、`oldString` → `old_string`）をバイナリへの転送前に正規化するため、`block-read-outside-cwd`、`block-env-files`、`block-secrets-write` などのパスチェック組み込みポリシーは OpenCode のツール呼び出しでも変更なく動作します。セッションは `~/.local/share/opencode/opencode.db` の OpenCode の SQLite DB に格納され、ダッシュボードのセッションビューアーは `opencode db --format json` と `opencode export ` を通じてそれらを読み込みます。OpenCode サポートは、バージョン間の動作と実際のセッションでのさらなる検証のため、**ベータ版**です。[OpenCode プラグインドキュメント](https://opencode.ai/docs/plugins/)を参照してください。 + - **Pi _(ベータ版)_**：`~/.pi/agent/settings.json`（ユーザー）、`/.pi/settings.json`（プロジェクト）— Pi には `local` スコープがありません。Pi は起動時に TypeScript 拡張パッケージを読み込みます。設定ファイルはフラットな文字列配列 `{"packages": ["./relative/path", …]}` です。failproofai はバンドルされた `pi-extension/` ディレクトリを指す単一のパッケージ配列エントリを書き込みます。拡張機能は内部で Pi の `tool_call` / `user_bash` / `input` / `session_start` イベントを購読し、`failproofai --hook --cli pi` をシェルアウトします。ハンドラーは `PI_EVENT_MAP` を介してアンダースコア小文字スネークケースをパスカルケースに正規化するため、既存の組み込みポリシーは変更なく動作します。ツール入力引数も `PI_TOOL_INPUT_MAP` を介して正規化されます（Pi の Read / Write / Edit は `file_path` ではなく `path` を渡します。トップレベルのキーをマッピングすることで `block-env-files` と `block-secrets-write` が動作します — `block-read-outside-cwd` にはすでに `path` フォールバックがありました）。Pi サポートは、Pi の拡張 API とセッションログレイアウトの安定化を待っている間は**ベータ版**です。 + - **Hermes (hermes-agent)**：`~/.hermes/config.yaml`（**ユーザースコープのみ** — Hermes にはプロジェクト/ローカル設定がありません）。Hermes は Slack/Telegram **ゲートウェイ**のため、1回のインストールですべてのプラットフォーム（Slack/Telegram/cli/cron）**および**内部サブエージェントからのツール呼び出しを傍受します。フックエントリは Hermes のスネークケースイベント（`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`）をキーとした `hooks:` マップ配下の `{command, timeout}` ペア（タイムアウトは**秒**単位）です。ハンドラーは `HERMES_EVENT_MAP` でイベントを、`HERMES_TOOL_MAP` でツール名を正規化するため、組み込みポリシーは変更なく動作します。設定はコメント保持 YAML `Document` のラウンドトリップを通じて編集されるため、オペレーターの他の設定が残ります。インストール時に `hooks_auto_accept: true` を設定するため、ヘッドレスゲートウェイ（TTY なし）は同意プロンプトなしにフックを実行します。評価器は Hermes の `{"decision":"block","reason"}` stdout コントラクトを出力します（Hermes は終了コードを無視します）。**制限事項：** Hermes にはターン終了の `Stop` イベントがないため、`require-*-before-stop` 組み込みポリシーは適用されません（適用不可であって、バグではありません）。`instruct` はログ付きの allow に降格します（追加コンテキストチャンネルなし）。出力シークレットのリダクション（`sanitize-*`）はシェルフックコントラクト経由でツール出力を書き換えられません。Hermes は**オフライン監査**ソースでもあります — ダッシュボードはゲートウェイセッションを `~/.hermes/state.db` から直接読み込みます。 + - **OpenClaw (openclaw gateway)**：`~/.openclaw/openclaw.json`（**ユーザースコープのみ** — OpenClaw にはプロジェクト/ローカル設定がありません）。Hermes と同様、OpenClaw は自己ホスト型マルチチャンネル**ゲートウェイ**のため、1回のインストールですべてのチャンネルと内部サブエージェントからのツール呼び出しを傍受します。実施は OpenClaw の**インプロセスプラグインフック**を通じて行われます（ファイルベースの内部フックは観察のみで、ブロックできません）。そのため、OpenCode/Pi と同様に、failproofai は failproofai バイナリを非同期でスポーンし、評決を変換する静的な `openclaw-plugin/` パッケージを同梱しています。インストール時に `openclaw.json` の `plugins.load.paths[]` に同梱プラグインディレクトリを登録し、`plugins.entries.failproofai` 配下で有効化します（生のコンバーセーションフックに必要な `hooks.allowConversationAccess: true` を含む）。評価器はフラットな `{permission, reason}` 評決を出力し、シムは各フックのネイティブな戻り形式にマッピングします：`before_tool_call → {block:true, blockReason}`（**PreToolUse**）、`before_agent_run → {outcome:"block", reason}`（**UserPromptSubmit**）、`before_agent_finalize → {action:"revise", reason}`（**Stop** — 実際のターン終了ゲートのため、`require-*-before-stop` 組み込みポリシーは Hermes と異なり OpenClaw で**適用されます**）。イベントとツール名はバイナリ側で `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP`（`exec→Bash`、`read→Read`、…）を介して正規化されるため、組み込みポリシーは変更なく動作します。スポーン/パース/タイムアウトエラーが発生した場合、シムはフェイルオープンします。OpenClaw は**オフライン監査**ソースでもあります — ダッシュボードは `~/.openclaw/agents//sessions/.jsonl` の JSONL セッションを読み込みます。 + - **Factory Droid (`droid`)**：`~/.factory/hooks.json`（ユーザー）、`/.factory/hooks.json`（プロジェクト）— Factory には `local` スコープがありません。droid は Claude 形式の外部コマンドフックシステムを実装していますが、droid v0.171.0 で実際に確認された2つの特異点があります：(1) イベント名は `hooks.json` の**トップレベル**にあります — **`"hooks"` ラッパーはありません**（droid はそれを拒否します）。ツールイベント（`PreToolUse`/`PostToolUse`）は `"matcher": "*"` を持ちますが、非ツールイベントは持ちません。(2) 拒否はフックの**終了コード2 + stderr** で行われます。JSON decision ではありません — 評価器の `factory` ブランチはツール/プロンプトイベントに対して終了コード2を返し、ターン終了の `Stop` イベント（droid 唯一の強制リトライチャンネル）にのみ `{decision:"block", reason}` を返します。イベントはすでにパスカルケースです（イベントマップなし）。ペイロードは Claude スネークケースです。ツール名のみ `FACTORY_TOOL_MAP`（`Execute→Bash`、`Create→Write`、`FetchUrl→WebFetch`、…）を介して正規化されます。Factory は**オフライン監査**ソースでもあります — ダッシュボードは `~/.factory/sessions//.jsonl` のオンディスク JSONL セッションを読み込みます。 + - **Devin CLI (`devin`、Cognition)**：`~/.config/devin/config.json`（ユーザー）、`/.devin/config.json`（プロジェクト）— Devin には `local` スコープがありません。Devin は devin v3000.1.27 で実際に確認された**純粋な Claude クローン**です：標準の Claude `"hooks"` ラッパースキーマを使用し（書き込みはマージ保持されるため、設定ファイルの他のキー — `org_id`、`theme_mode`、… — が残ります）、すでにパスカルケースのイベント名（イベントマップなし、ハンドラーブランチなし）、Claude スネークケースの stdin ペイロード（正規化なし）を持ちます。評価器の `devin` ブランチはすべてのイベントに対して終了コード0で stdout に `{"decision":"block","reason"}` JSON を出力して拒否します（確認済み — ブロックは `--permission-mode dangerous` を上書きしました）。ターン終了の `Stop` イベントでは、`require-*-before-stop` 組み込みポリシーが適用されるよう、理由に MANDATORY-ACTION の強制リトライ文言が含まれます。ツール名のみ `DEVIN_TOOL_MAP`（`exec→Bash`。`tool_input.command` はすでに正規形式）を介して正規化されます。Devin は**オフライン監査**ソースでもあります — ダッシュボードは `~/.local/share/devin/cli/sessions.db` の SQLite セッションを読み込みます（各 `sessions` 行は実際の `working_directory` を持つため、Claude のようにプロジェクト cwd でセッションをグループ化します）。 + - **Antigravity CLI (`agy`)**：`~/.gemini/config/hooks.json`（ユーザー）、`/.agents/hooks.json`（プロジェクト）— Antigravity には `local` スコープがありません。Factory/Devin とは異なり、Antigravity は**独自の**コントラクトを持ちます（Claude クローンではありません）。agy v1.1.2 で実際に確認済みです。`hooks.json` は**名前付きフック**スキーマを使用します：トップレベルのキーはフック*名前*（`"failproofai"`）で、その値はイベント→ハンドラーマップです — ツールイベント（`PreToolUse`/`PostToolUse`）はハンドラーを `{matcher:"*", hooks:[…]}` でラップしますが、`PreInvocation`/`Stop` は**フラット**なハンドラー配列です（他の名前付きフックは保持されます）。stdin ペイロードは**キャメルケース protojson**（`toolCall:{name,args}`、`conversationId`、`workspacePaths`、`transcriptPath`）です — failproofai はポリシー実行前にスネークケースに正規化し、`ANTIGRAVITY_TOOL_INPUT_MAP` を介して `run_command` のパスカルケース引数（`CommandLine`/`Cwd`）をマッピングします。評価器の `antigravity` ブランチは Antigravity**独自の**レスポンス形式を使用します：`{decision:"deny", reason}` はツール/プロンプトをブロックし（終了コード0）、ターン終了の `Stop` での `{decision:"continue", reason}` はループを再開します（そのため `require-*-before-stop` 組み込みポリシーが適用されます）。`{injectSteps:[{ephemeralMessage}]}` は `PreInvocation`（→ `UserPromptSubmit`）で命令を挿入します。ツール名は `ANTIGRAVITY_TOOL_MAP`（`run_command→Bash`、`view_file→Read`、…）を介して正規化されます。Antigravity は**オフライン監査**ソースでもあります — ダッシュボードは `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` のプレーン JSONL トランスクリプトを読み込みます（コンバーセーションインデックスは `conversation_summaries.db` に格納）。 + - **Goose (コードネーム goose、Block)**：`~/.agents/plugins/failproofai/hooks/hooks.json`（ユーザー）、`/.agents/plugins/failproofai/hooks/hooks.json`（プロジェクト）— Goose には `local` スコープがありません。実施は Goose の**フック**システム（クロスエージェントの **Open Plugins** 仕様）を使用します：インストーラーは `failproofai` プラグインディレクトリを配置するだけで、Goose は起動時に自動検出します（`~/.config/goose/config.yaml` に自己登録します）。`hooks.json` はトップレベルの `"hooks"` ラッパーを持つ Open Plugins スキーマを使用しますが、すべてのイベントでマッチャーは**省略されています** — 裸の `"*"` は無効な正規表現で何にもマッチしません（goose v1.43.0 で実際に確認済み）。イベント名はすでにパスカルケースです（イベントマップなし）。stdin ペイロードは `event`/`working_dir` を使用し、ハンドラーはこれを `hook_event_name`/`cwd` に正規化します。評価器の `goose` ブランチは終了コード0で stdout に `{"decision":"block","reason"}` JSON を出力して拒否します。これは**`PreToolUse`** イベントのみで有効化されます（goose ≥ v1.37.0 で実装）— シェルツール**および委譲されたサブエージェント内**でも動作するため、単一の十分な拒否ポイントです。その他のフックエラーはフェイルオープンします。Goose には **`Stop` イベントがない**ため、`require-*-before-stop` 組み込みポリシーは適用されません（Hermes と同様）。ツール名は `GOOSE_TOOL_MAP`（`shell→Bash`、`write→Write`、`todo__todo_write→TodoWrite`、…）を介して正規化され、パスキーは `GOOSE_TOOL_INPUT_MAP`（`path`/`source` → `file_path`）を介して正規化されます。Goose は**オフライン監査**ソースでもあります — ダッシュボードは `~/.local/share/goose/sessions/sessions.db` の SQLite セッションを読み込みます（各 `sessions` 行は実際の `working_dir` を持つため、Devin のようにプロジェクト cwd でセッションをグループ化します。`--no-session` のスクラッチ実行はフィルタリングされます）。 +- **`policies-config.json`** — どのポリシーを評価し、どのパラメーターで実行するかを failproofai に伝えます（すべてのエージェント CLI で共有） + +特定のエージェントを対象にするには `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` を渡します（任意のサブセットをスペース区切りまたは繰り返して指定）： ```bash failproofai policies --install --cli codex --scope project @@ -210,15 +217,20 @@ failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli hermes --scope user -failproofai policies --install --cli claude codex copilot cursor opencode pi +failproofai policies --install --cli openclaw --scope user +failproofai policies --install --cli factory --scope project +failproofai policies --install --cli devin --scope project +failproofai policies --install --cli antigravity --scope project +failproofai policies --install --cli goose --scope project +failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -`--cli` を省略すると、`failproofai` はインストール済みのエージェント CLI を自動検出します（`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`）： +`--cli` を省略した場合、`failproofai` はインストールされているエージェント CLI を自動検出します（`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`）： -- **CLI が1つ検出された場合** — プロンプトなしでその CLI を自動選択します。 -- **複数の CLI が検出され、インタラクティブターミナルの場合** — `Detected (N)` セクション（`Install for all N detected` の集約行と検出された各 CLI）と `Not installed (M) · install hooks ahead of time` セクション（検出されなかったサポート対象 CLI を前もってインストールするオプションとして一覧表示）にグループ化された矢印キー操作の単一選択プロンプトを表示します（↑↓で移動、Enterで選択、^Cで終了）。アンインストールフローでは Detected セクションのみ表示されます。 -- **複数の CLI が検出され、非インタラクティブ実行（CI、TTY なし）の場合** — プロンプトなしですべての検出された CLI にインストールします。 -- **何も検出されない場合** — エージェントバイナリが PATH に見つからないという警告とともに `claude` にフォールバックします。フックコマンドは書き込まれるため、インストール後すぐに有効になります。 +- **1つの CLI が検出された場合** — プロンプトなしでその CLI を自動選択します。 +- **複数の CLI がインタラクティブターミナルで検出された場合** — 矢印キーによる単一選択プロンプトを表示します。`Detected (N)` セクション（`Install for all N detected` の集約行 + 検出された各 CLI）と `Not installed (M) · install hooks ahead of time` セクション（未検出の対応 CLI をすべて前向きインストールオプションとして一覧表示）にグループ分けされます（↑↓ で移動、Enter で選択、^C で終了）。アンインストールフローでは Detected セクションのみ表示します。 +- **複数の CLI が非インタラクティブ実行（CI、TTY なし）で検出された場合** — プロンプトなしですべての検出された CLI にインストールします。 +- **何も検出されない場合** — エージェントバイナリが PATH に見つからなかったという警告とともに `claude` にフォールバックします。フックコマンドは引き続き書き込まれるため、後からインストールすればすぐにアクティベートされます。 `policies-config.json` はいつでも直接編集できます。変更は次のフックイベント時に即座に反映され、再起動は不要です。 @@ -245,4 +257,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi } ``` -各開発者はチームメートに影響を与えることなく個人用の上書き設定として `.failproofai/policies-config.local.json`（gitignore 対象）を作成できます。 \ No newline at end of file +各開発者はその後、`.failproofai/policies-config.local.json`（gitignore済み）を作成して、チームメンバーに影響を与えることなく個人的な上書き設定を行えます。 \ No newline at end of file diff --git a/docs/ja/custom-policies.mdx b/docs/ja/custom-policies.mdx index 44f1c94d..bd53c839 100644 --- a/docs/ja/custom-policies.mdx +++ b/docs/ja/custom-policies.mdx @@ -1,14 +1,14 @@ --- title: カスタムポリシー -description: "JavaScriptで独自のポリシーを記述する — 規約の適用、ドリフトの防止、障害の検出、外部システムとの連携" +description: "JavaScriptで独自のポリシーを記述する - 規約の強制、ドリフトの防止、障害の検出、外部システムとの統合" icon: code --- -カスタムポリシーを使うと、エージェントのあらゆる動作に対してルールを記述できます。プロジェクトの規約を強制する、ドリフトを防ぐ、破壊的な操作にゲートをかける、スタックしたエージェントを検出する、Slack・承認ワークフローなどと連携する、といった用途に活用できます。組み込みポリシーと同じフックイベントシステムおよび `allow`、`deny`、`instruct` の判定を使用します。 +カスタムポリシーを使用すると、あらゆるエージェントの振る舞いに対してルールを記述できます。プロジェクトの規約を強制する、ドリフトを防止する、破壊的な操作をゲートする、スタックしたエージェントを検出する、Slackや承認ワークフローと統合するといった用途に対応します。組み込みポリシーと同じフックイベントシステムおよび `allow`、`deny`、`instruct` の判定を使用します。 --- -## クイックサンプル +## クイック例 ```js // my-policies.js @@ -37,14 +37,14 @@ failproofai policies --install --custom ./my-policies.js --- -## カスタムポリシーを読み込む2つの方法 +## カスタムポリシーの読み込み方法 ### オプション1: 規約ベース（推奨） -`*policies.{js,mjs,ts}` ファイルを `.failproofai/policies/` に置くだけで自動的に読み込まれます — フラグや設定変更は不要です。gitフックと同じ感覚で、ファイルを置けばすぐに動きます。 +`*policies.{js,mjs,ts}` ファイルを `.failproofai/policies/` に配置するだけで自動的に読み込まれます。フラグや設定変更は不要です。gitフックと同じ仕組みです。ファイルを置けば、そのまま動作します。 ``` -# プロジェクトレベル — gitにコミットしてチームで共有 +# プロジェクトレベル — gitにコミット済み、チームで共有 .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs @@ -53,14 +53,14 @@ failproofai policies --install --custom ./my-policies.js ``` **動作の仕組み:** -- プロジェクトとユーザー両方のディレクトリがスキャンされます（和集合 — スコープ優先ではありません） -- 各ディレクトリ内ではアルファベット順に読み込まれます。`01-`、`02-` のようなプレフィックスで順序を制御できます -- `*policies.{js,mjs,ts}` にマッチするファイルのみ読み込まれ、それ以外は無視されます +- プロジェクトディレクトリとユーザーディレクトリの両方がスキャンされます（和集合 — スコープ優先ではありません） +- ファイルは各ディレクトリ内でアルファベット順に読み込まれます。順序を制御するには `01-`、`02-` などのプレフィックスを付けてください +- `*policies.{js,mjs,ts}` にマッチするファイルのみ読み込まれます。それ以外のファイルは無視されます - 各ファイルは独立して読み込まれます（ファイル単位でフェイルオープン） -- 明示的な `--custom` フラグや組み込みポリシーと併用できます +- 明示的な `--custom` および組み込みポリシーと並行して動作します -規約ポリシーは、組織の品質基準を構築する最も簡単な方法です。`.failproofai/policies/` をgitにコミットすれば、すべてのチームメンバーが自動的に同じルールを適用できます — 開発者ごとのセットアップは不要です。チームが新たな障害パターンを発見するたびにポリシーを追加してプッシュすれば、コントリビューションのたびに改善されていくリビングな品質基準になります。 +規約ポリシーは、組織の品質基準を構築する最も簡単な方法です。`.failproofai/policies/` をgitにコミットすれば、すべてのチームメンバーが自動的に同じルールを受け取ります。開発者ごとのセットアップは不要です。チームが新しい障害パターンを発見するたびにポリシーを追加してプッシュするだけで、コントリビューションのたびに改善し続ける生きた品質基準になっていきます。 ### オプション2: 明示的なファイルパス @@ -69,20 +69,25 @@ failproofai policies --install --custom ./my-policies.js # カスタムポリシーファイルを指定してインストール failproofai policies --install --custom ./my-policies.js -# ポリシーファイルのパスを置き換え +# カスタムポリシーパスを置き換え failproofai policies --install --custom ./new-policies.js -# 設定からカスタムポリシーパスを削除 +# 複数の明示的ファイルを設定（フラグの順序で読み込み） +failproofai policies --install --custom ./security.js --custom ./workflow.js + +# 設定からすべての明示的カスタムポリシーパスを削除 failproofai policies --uninstall --custom ``` -解決された絶対パスは `policies-config.json` の `customPoliciesPath` として保存されます。ファイルはフックイベントのたびに新たに読み込まれ、イベント間でのキャッシュはありません。 +解決された絶対パスは `policies-config.json` の `customPoliciesPaths` に保存されます。複数ファイルを設定するには `--custom` を繰り返します。レガシーの `customPoliciesPath` フィールドを使用した既存の設定も引き続き動作します。ファイルはフックイベントのたびに新たに読み込まれます。イベント間のキャッシュはありません。 + +登録された各ポリシーはダッシュボードに独自のトグルとして表示されます。ポリシーをオフにすると、そのソース修飾IDが `disabledCustomPolicies` に記録されます。ファイルとその他のポリシーは引き続き読み込まれ、無効化されたポリシーのみイベントマッチング前に除外されます。複数のファイルにまたがって重複したポリシー名は、それぞれ独立したトグルを持ちます。 -### 両方を併用する +### 両方を組み合わせる 規約ポリシーと明示的な `--custom` ファイルは共存できます。読み込み順序: -1. 明示的な `customPoliciesPath` ファイル（設定されている場合） +1. 明示的な `customPoliciesPaths` ファイル（設定された順序） 2. プロジェクト規約ファイル（`{cwd}/.failproofai/policies/`、アルファベット順） 3. ユーザー規約ファイル（`~/.failproofai/policies/`、アルファベット順） @@ -98,45 +103,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -ポリシーを登録します。同一ファイルに複数のポリシーを定義する場合は、必要な回数だけ呼び出せます。 +ポリシーを登録します。同一ファイルに複数のポリシーを記述する場合は、必要な回数だけ呼び出してください。 ```ts customPolicies.add({ - name: string; // 必須 — 一意の識別子 - description?: string; // `failproofai policies` の出力に表示される - match?: { events?: HookEventType[] }; // イベントタイプでフィルタ。省略すると全てにマッチ + name: string; // 必須 - 一意の識別子 + description?: string; // `failproofai policies` の出力に表示 + match?: { events?: HookEventType[] }; // イベントタイプでフィルタ。省略すると全イベントにマッチ fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` ### 判定ヘルパー -| 関数 | 効果 | 使用場面 | +| 関数 | 効果 | 使用する場面 | |----------|--------|----------| -| `allow()` | 操作をサイレントに許可 | アクションが安全でメッセージ不要な場合 | -| `deny(message)` | 操作をブロック | エージェントにこのアクションを実行させない場合 | -| `instruct(message)` | ブロックせずにコンテキストを追加 | エージェントに追加コンテキストを渡してトラックに乗せたい場合 | +| `allow()` | 操作をサイレントに許可 | アクションが安全でメッセージが不要な場合 | +| `deny(message)` | 操作をブロック | エージェントがこのアクションを実行すべきでない場合 | +| `instruct(message)` | ブロックせずにコンテキストを追加 | エージェントが軌道を維持するための追加コンテキストを提供する場合 | -`deny(message)` — メッセージは `"Blocked by failproofai:"` というプレフィックスを付けて Claude に表示されます。1つの `deny` が発生すると、それ以降の評価はすべて短絡します。 +`deny(message)` — メッセージは Claude に `"Blocked by failproofai:"` というプレフィックスとともに表示されます。一つの `deny` で以降の全評価がショートサーキットされます。 -`instruct(message)` — メッセージは現在のツール呼び出しに対する Claude のコンテキストに追記されます。すべての `instruct` メッセージは蓄積されて一括して配信されます。 +`instruct(message)` — メッセージは現在のツール呼び出しに対する Claude のコンテキストに追記されます。すべての `instruct` メッセージは蓄積されてまとめて配信されます。 -`deny` または `instruct` メッセージに追加のガイダンスを付け加えるには、`policyParams` の `hint` フィールドを使います — コード変更は不要です。カスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）ポリシーでも機能します。詳細は[設定 → hint](/ja/configuration#hint-cross-cutting)を参照してください。 +`policyParams` の `hint` フィールドを追加することで、コード変更なしに任意の `deny` または `instruct` メッセージに追加ガイダンスを付加できます。これはカスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）ポリシーでも機能します。詳細は [設定 → hint](/ja/configuration#hint-cross-cutting) を参照してください。 -### 情報提供用の allow メッセージ +### 情報提供用のallowメッセージ -`allow(message)` は操作を許可しつつ、情報メッセージを Claude に送信します。メッセージはフックハンドラーの stdout レスポンスの `additionalContext` として配信されます — `instruct` と同じ仕組みですが、意味が異なります。これはステータスの更新であり、警告ではありません。 +`allow(message)` は操作を許可しつつ、Claude に情報メッセージを送信します。メッセージはフックハンドラーのstdoutレスポンスの `additionalContext` として配信されます。これは `instruct` と同じメカニズムを使用しますが、意味的に異なります。警告ではなく、ステータス更新です。 -| 関数 | 効果 | 使用場面 | +| 関数 | 効果 | 使用する場面 | |----------|--------|----------| -| `allow(message)` | 許可してコンテキストを Claude に送信 | チェックが通過したことを確認する、またはチェックがスキップされた理由を説明する | +| `allow(message)` | 許可してClaudeにコンテキストを送信 | チェックが合格したことの確認、またはチェックがスキップされた理由の説明 | ユースケース: -- **ステータス確認:** `allow("All CI checks passed.")` — すべて正常であることを Claude に伝える -- **フェイルオープンの説明:** `allow("GitHub CLI not installed, skipping CI check.")` — チェックがスキップされた理由を Claude に伝えて完全なコンテキストを提供する -- **複数メッセージの蓄積:** 複数のポリシーがそれぞれ `allow(message)` を返した場合、すべてのメッセージは改行で結合されて一括配信されます +- **ステータス確認:** `allow("All CI checks passed.")` — 全て問題ないことを Claude に伝える +- **フェイルオープンの説明:** `allow("GitHub CLI not installed, skipping CI check.")` — チェックがスキップされた理由を Claude に伝え、完全なコンテキストを提供する +- **複数メッセージの蓄積:** 複数のポリシーがそれぞれ `allow(message)` を返した場合、全メッセージが改行で結合されてまとめて配信される ```js customPolicies.add({ @@ -146,7 +151,7 @@ customPolicies.add({ const cwd = ctx.session?.cwd; if (!cwd) return allow("No working directory, skipping branch check."); - // ... ブランチの状態を確認 ... + // ... ブランチのステータスを確認 ... if (allPushed) { return allow("Branch is up to date with remote."); } @@ -171,16 +176,16 @@ customPolicies.add({ |-------|------|-------------| | `sessionId` | `string` | Claude Code セッション識別子 | | `cwd` | `string` | Claude Code セッションの作業ディレクトリ | -| `transcriptPath` | `string` | セッションの JSONL トランスクリプトファイルへのパス | +| `transcriptPath` | `string` | セッションのJSONLトランスクリプトファイルへのパス | ### イベントタイプ | イベント | 発火タイミング | `toolInput` の内容 | |-------|--------------|----------------------| -| `PreToolUse` | Claude がツールを実行する前 | ツールの入力（例: Bash の場合 `{ command: "..." }`） | -| `PostToolUse` | ツールが完了した後 | ツールの入力 + `tool_result`（出力） | -| `Notification` | Claude が通知を送信するとき | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — フックは常に `allow()` を返す必要があり、通知をブロックすることはできません | -| `Stop` | Claude セッションが終了するとき | 空 | +| `PreToolUse` | Claudeがツールを実行する前 | ツールの入力（例: Bashの場合 `{ command: "..." }`） | +| `PostToolUse` | ツールの完了後 | ツールの入力 + `tool_result`（出力） | +| `Notification` | Claudeが通知を送信するとき | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - フックは常に `allow()` を返す必要があり、通知をブロックすることはできません | +| `Stop` | Claudeセッションが終了するとき | 空 | --- @@ -189,12 +194,12 @@ customPolicies.add({ ポリシーは以下の順序で評価されます: 1. 組み込みポリシー（定義順） -2. `customPoliciesPath` からの明示的なカスタムポリシー（`.add()` の順序） +2. `customPoliciesPath` からの明示的カスタムポリシー（`.add()` の順序） 3. プロジェクト `.failproofai/policies/` の規約ポリシー（ファイルはアルファベット順、ファイル内は `.add()` の順序） 4. ユーザー `~/.failproofai/policies/` の規約ポリシー（ファイルはアルファベット順、ファイル内は `.add()` の順序） -最初の `deny` が発生すると以降のポリシーはすべて短絡します。すべての `instruct` メッセージは蓄積されて一括配信されます。 +最初の `deny` で以降のすべてのポリシーがショートサーキットされます。すべての `instruct` メッセージは蓄積されてまとめて配信されます。 --- @@ -218,46 +223,46 @@ customPolicies.add({ }); ``` -エントリファイルから到達可能なすべての相対インポートが解決されます。これは `from "failproofai"` のインポートを実際の dist パスに書き換え、ESM 互換性を確保するために一時的な `.mjs` ファイルを作成することで実装されています。 +エントリファイルから到達可能なすべての相対インポートが解決されます。これは `from "failproofai"` インポートを実際のdistパスに書き換え、ESM互換性を確保するために一時的な `.mjs` ファイルを作成することで実装されています。 --- ## イベントタイプのフィルタリング -`match.events` を使用してポリシーが発火するタイミングを限定できます: +`match.events` を使用して、ポリシーが発火するタイミングを制限できます: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // セッション終了時にのみ発火 - // ctx.session.transcriptPath にセッションの完全なログが含まれます + // セッション終了時のみ発火 + // ctx.session.transcriptPath に完全なセッションログが含まれます return allow(); }, }); ``` -`match` を完全に省略すると、すべてのイベントタイプで発火します。 +すべてのイベントタイプで発火させるには `match` を省略してください。 --- ## エラー処理と障害モード -カスタムポリシーは**フェイルオープン**です: エラーが発生しても組み込みポリシーをブロックしたり、フックハンドラーをクラッシュさせたりすることはありません。 +カスタムポリシーは**フェイルオープン**です。エラーが発生しても、組み込みポリシーがブロックされたりフックハンドラーがクラッシュしたりすることはありません。 | 障害 | 動作 | |---------|----------| -| `customPoliciesPath` が未設定 | 明示的なカスタムポリシーは実行されない。規約ポリシーと組み込みポリシーは通常通り継続 | -| ファイルが見つからない | `~/.failproofai/hook.log` に警告を記録。組み込みポリシーは継続 | -| 構文/インポートエラー（明示的） | `~/.failproofai/hook.log` にエラーを記録。明示的なカスタムポリシーをスキップ | -| 構文/インポートエラー（規約） | エラーを記録。該当ファイルをスキップ。他の規約ファイルは引き続き読み込まれる | -| `fn` が実行時に例外をスロー | エラーを記録。そのフックは `allow` として扱われ、他のフックは継続 | -| `fn` が10秒以上かかる | タイムアウトを記録。`allow` として扱われる | +| `customPoliciesPath` が未設定 | 明示的カスタムポリシーは実行されない。規約ポリシーと組み込みポリシーは通常通り継続 | +| ファイルが見つからない | `~/.failproofai/hook.log` に警告をログ記録。組み込みポリシーは継続 | +| 構文/インポートエラー（明示的） | `~/.failproofai/hook.log` にエラーをログ記録。明示的カスタムポリシーはスキップ | +| 構文/インポートエラー（規約） | エラーをログ記録。そのファイルはスキップされ、他の規約ファイルは引き続き読み込み | +| 実行時に `fn` がスロー | エラーをログ記録。そのフックは `allow` として扱われ、他のフックは継続 | +| `fn` が10秒以上かかる | タイムアウトをログ記録。`allow` として扱われる | | 規約ディレクトリが存在しない | 規約ポリシーは実行されない。エラーなし | -カスタムポリシーのエラーをデバッグするには、ログファイルを監視します: +カスタムポリシーのエラーをデバッグするには、ログファイルを監視してください: ```bash tail -f ~/.failproofai/hook.log @@ -266,13 +271,13 @@ tail -f ~/.failproofai/hook.log --- -## 完全なサンプル: 複数のポリシー +## 完全な例: 複数のポリシー ```js // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// エージェントが secrets/ ディレクトリに書き込むことを防止 +// エージェントがsecrets/ディレクトリに書き込むのを防止 customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -285,7 +290,7 @@ customPolicies.add({ }, }); -// エージェントをトラックに乗せる: コミット前にテストを確認 +// エージェントの軌道を維持: コミット前にテストを確認 customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +305,7 @@ customPolicies.add({ }, }); -// フリーズ期間中の予期しない依存関係の変更を防止 +// フリーズ期間中の予定外の依存関係変更を防止 customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -323,22 +328,22 @@ export { customPolicies }; ## サンプル -`examples/` ディレクトリにはすぐに使えるポリシーファイルが含まれています: +`examples/` ディレクトリには、すぐに実行できるポリシーファイルが含まれています: | ファイル | 内容 | |------|----------| -| `examples/policies-basic.js` | エージェントの一般的な障害モードをカバーする5つのスターターポリシー | +| `examples/policies-basic.js` | よくあるエージェントの障害パターンをカバーする5つのスターターポリシー | | `examples/policies-advanced/index.js` | 高度なパターン: 推移的インポート、非同期呼び出し、出力スクラビング、セッション終了フック | -| `examples/convention-policies/security-policies.mjs` | 規約ベースのセキュリティポリシー（.env への書き込みのブロック、gitヒストリーの書き換え防止） | +| `examples/convention-policies/security-policies.mjs` | 規約ベースのセキュリティポリシー（.envへの書き込みブロック、gitヒストリーの書き換え防止） | | `examples/convention-policies/workflow-policies.mjs` | 規約ベースのワークフローポリシー（テストリマインダー、ファイル書き込みの監査） | -### 明示的なファイルのサンプルを使用する +### 明示的ファイルの例を使用する ```bash failproofai policies --install --custom ./examples/policies-basic.js ``` -### 規約ベースのサンプルを使用する +### 規約ベースの例を使用する ```bash # プロジェクトレベルにコピー @@ -350,4 +355,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -インストールコマンドは不要です — 次のフックイベント時に自動的にファイルが読み込まれます。 \ No newline at end of file +インストールコマンドは不要です。次のフックイベント時にファイルが自動的に読み込まれます。 \ No newline at end of file diff --git a/docs/ja/dashboard.mdx b/docs/ja/dashboard.mdx index adb802e8..bc8c727c 100644 --- a/docs/ja/dashboard.mdx +++ b/docs/ja/dashboard.mdx @@ -4,7 +4,7 @@ description: "エージェントセッションの監視、ツール呼び出し icon: chart-line --- -failproofai ダッシュボードは、AIエージェントセッションの監視とポリシー管理のためのローカルWebアプリケーションです。あなたが離れている間にエージェントが何をしたか確認できます。 +failproofai ダッシュボードは、AIエージェントセッションの監視とポリシー管理を行うローカルWebアプリケーションです。席を外している間にエージェントが何をしたかを確認できます。 --- @@ -16,75 +16,77 @@ failproofai `http://localhost:8020` で開きます。 -ダッシュボードはローカルのプロジェクト、セッション、failproofai 設定データをファイルシステムから直接読み込みます。監査リマインダーや招待などの認証が必要なオプション機能は、そのリクエストに必要な情報（メールアドレスを含む）をリモートAPIに送信します。 +ダッシュボードは、ローカルのプロジェクト・セッション・failproofai 設定データをファイルシステムから直接読み込みます。監査リマインダーや招待などの認証済みオプション機能は、リクエストに必要な情報（メールアドレスを含む）をリモートAPIに送信します。 --- -## ページ +## ページ一覧 ### プロジェクト -マシン上で検出されたすべての Claude Code、OpenAI Codex、GitHub Copilot CLI _(ベータ)_、Cursor Agent _(ベータ)_、OpenCode _(ベータ)_、Pi _(ベータ)_、Hermes、OpenClaw、Factory Droid、Devin、Antigravity、Goose のプロジェクトを一覧表示します。Claude プロジェクトは `~/.claude/projects/`（または `CLAUDE_PROJECTS_PATH` で設定されたパス）から検出されます。Codex プロジェクトは `~/.codex/sessions///
/*.jsonl` 配下のすべてのトランスクリプトをスキャンし、各セッションの最初のレコードに記録された `cwd` でグループ化することで検出されます。Copilot CLI プロジェクトは各 `~/.copilot/session-state//workspace.yaml`（`COPILOT_HOME` で設定可能）をスキャンし、その `cwd` フィールドでグループ化することで検出されます。Cursor Agent プロジェクトは `~/.cursor/agent-sessions//`（`CURSOR_HOME` で設定可能、フォールバックとして `conversations/` と `sessions/` も探索）配下のセッションごとのメタデータをスキャンし、`meta.json` / `session.json` / `workspace.yaml` の `cwd` スカラーから検出されます。OpenCode プロジェクトは `~/.local/share/opencode/opencode.db` にある SQLite DB を `opencode db --format json` 経由でクエリすることで検出されます（`session` テーブルと `project` テーブルを読み込み、`project_id` でグループ化）。Pi プロジェクトは `~/.pi/agent/sessions//_.jsonl`（`PI_SESSIONS_DIR` で設定可能）配下のセッションごとの JSONL トランスクリプトをスキャンし、各セッションの最初のレコードから `cwd` を取得することで検出されます。Hermes ゲートウェイセッションは `~/.hermes/state.db`（`HERMES_DB_PATH` で設定可能）の SQLite ストアから直接読み込まれ、`source`（Slack/Telegram/cli/cron）で `hermes-` プロジェクトにグループ化されます（ゲートウェイセッションには cwd がありません）。OpenClaw ゲートウェイセッションは `~/.openclaw/agents//sessions/*.jsonl` から読み込まれ、`openclaw-` プロジェクトにグループ化されます（こちらも cwd なし）。Factory Droid プロジェクトは `~/.factory/sessions//*.jsonl` の JSONL トランスクリプトから cwd でグループ化して検出されます。Devin プロジェクトは `~/.local/share/devin/cli/sessions.db` の SQLite DB から（各セッションの `working_directory` でグループ化）検出されます。Antigravity プロジェクトは `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` の JSONL トランスクリプトから cwd でグループ化して検出されます。Goose プロジェクトは `~/.local/share/goose/sessions/sessions.db` の SQLite DB から（各セッションの `working_dir` でグループ化）検出されます。複数の CLI で使用されたプロジェクトは、該当するすべてのバッジを持つ1行として表示されます。テーブル上の **CLI** ドロップダウンを使用して特定のエージェント CLI でフィルタリングできます。URLには選択内容が `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` として保持されます。 +マシン上で見つかったすべての Claude Code、OpenAI Codex、GitHub Copilot CLI _(ベータ)_、Cursor Agent _(ベータ)_、OpenCode _(ベータ)_、Pi _(ベータ)_、Hermes、OpenClaw、Factory Droid、Devin、Antigravity、Goose プロジェクトの一覧を表示します。Claude プロジェクトは `~/.claude/projects/`（または `CLAUDE_PROJECTS_PATH` で設定したパス）から検出されます。Codex プロジェクトは `~/.codex/sessions///
/*.jsonl` 以下のすべてのトランスクリプトをスキャンし、各セッションの最初のレコードに記録された `cwd` でグループ化して検出されます。Copilot CLI プロジェクトは各 `~/.copilot/session-state//workspace.yaml`（`COPILOT_HOME` で変更可能）をスキャンし、`cwd` フィールドでグループ化して検出されます。Cursor Agent プロジェクトは `~/.cursor/agent-sessions//`（`CURSOR_HOME` で変更可能。フォールバックとして `conversations/` と `sessions/` も探索）以下のセッションごとのメタデータをスキャンし、`meta.json` / `session.json` / `workspace.yaml` 内の `cwd` スカラーを元に検出されます。OpenCode プロジェクトは `~/.local/share/opencode/opencode.db` の SQLite DB を `opencode db --format json` 経由でクエリし（`session` テーブルと `project` テーブルを読み取り、`project_id` でグループ化）、Pi プロジェクトは `~/.pi/agent/sessions//_.jsonl`（`PI_SESSIONS_DIR` で変更可能）以下のセッションごとの JSONL トランスクリプトをスキャンして各セッションの最初のレコードから `cwd` を取得します。Hermes ゲートウェイセッションは各プロファイルの SQLite ストア（`~/.hermes/state.db` および `~/.hermes/profiles//state.db`、`HERMES_HOME` または単一データベースの場合は `HERMES_DB_PATH` で上書き可能）から直接読み取られ、プロファイルと `source`（Slack/Telegram/cli/cron — ゲートウェイセッションに cwd はなし）ごとに `hermes--` プロジェクトにグループ化されます。OpenClaw ゲートウェイセッションは `~/.openclaw/agents//sessions/*.jsonl` から読み取られ、エージェントとチャンネルごとに `openclaw--` プロジェクトにグループ化されます（こちらも cwd なし）。Factory Droid プロジェクトは `~/.factory/sessions//*.jsonl` の JSONL トランスクリプトから cwd でグループ化して検出されます。Devin プロジェクトは `~/.local/share/devin/cli/sessions.db` の SQLite DB（各セッションの `working_directory` でグループ化）から、Antigravity プロジェクトは `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` の JSONL トランスクリプトから cwd でグループ化して、Goose プロジェクトは `~/.local/share/goose/sessions/sessions.db` の SQLite DB（各セッションの `working_dir` でグループ化）からそれぞれ検出されます。複数の CLI で使用されたプロジェクトは、一行にまとめて対応するバッジが表示されます。テーブル上部の **CLI** ドロップダウンで特定のエージェント CLI によるフィルタリングが可能です。URLには選択内容が `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` として保持されます。 -各プロジェクトに表示される情報： +Hermes と OpenClaw はユーザースコープでグループ化に使用できる作業ディレクトリを持たないため、**折りたたみ可能なフォルダツリー**として表示されます（上位レベルにプロファイルまたはエージェント、その下にチャンネル）。一方、cwd ベースの CLI はすべてフラットな行で表示されます。フォルダ行はその配下のセッション数と最新アクティビティの集計を表示し、折りたたまれたフォルダの状態は訪問間で記憶されます。キーワード検索は一致したものを自動展開します。 + +各プロジェクトに表示される情報: - プロジェクト名（フォルダパスから導出） - CLI バッジ — `Claude Code`（オレンジ）、`OpenAI Codex`（パープル）、`GitHub Copilot`（ブルー）、`Cursor Agent`（エメラルド）、`OpenCode`（アンバー）、`Pi`（ピンク）、`Hermes`（インディゴ） -- 最新セッションアクティビティの日付 +- 最新セッションアクティビティの日時 -プロジェクトをクリックするとセッション一覧が表示されます。 +プロジェクトをクリックするとそのセッション一覧が表示されます。 ### セッション -プロジェクト内のすべてのセッションを一覧表示します。各セッションに表示される情報： +プロジェクト内のすべてのセッション一覧を表示します。各セッションに表示される情報: - セッション ID - 開始・終了タイムスタンプ -- ツール呼び出し数 -- フックアクティビティ数（発火したポリシー数） +- ツール呼び出し回数 +- フックアクティビティ数（発動したポリシー数） -日付範囲フィルターとセッション ID 検索で絞り込みができます。セッションはページネーションされます。 +日付範囲フィルターとセッション ID 検索で絞り込めます。セッションはページネーションされます。 セッションをクリックするとセッションビューアーが開きます。 ### セッションビューアー -セッションビューアーは自律型エージェントにとって最も重要な問いに答えます：エージェントは何をしたのか、そして正しい方向に進んでいたのか。ヘッダーの横にある CLI バッジは、そのセッションが Claude Code、OpenAI Codex、GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Hermes、OpenClaw、Factory Droid、Devin、Antigravity、Goose のどのトランスクリプトかを示します。セッション内で起きたすべての出来事のタイムラインが表示されます： +セッションビューアーは自律型エージェントに関する核心的な問いに答えます：エージェントは何をしたのか、そして意図通りに動いていたのか。ヘッダー横の CLI バッジはセッションが Claude Code、OpenAI Codex、GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Hermes、OpenClaw、Factory Droid、Devin、Antigravity、Goose のいずれのトランスクリプトかを示します。セッション内で起きたすべての出来事をタイムラインで表示します。 -- **メッセージ** - Claude のテキスト応答とユーザープロンプト -- **ツール呼び出し** - Claude が実行したすべてのツール（入力と出力付き） -- **ポリシーアクティビティ** - 各ツール呼び出しに対して、どのポリシーが発火し、どのような判断を返したか +- **メッセージ** — Claude のテキスト応答とユーザープロンプト +- **ツール呼び出し** — Claude が呼び出したすべてのツール（入力と出力を含む） +- **ポリシーアクティビティ** — 各ツール呼び出しに対して、どのポリシーが発動し、どの判断が返されたか -上部の統計バーにはセッション時間、ツール呼び出しの総数、フック判断のサマリー（allow / deny / instruct のカウント）が表示されます。 +上部のステータスバーにはセッション時間、総ツール呼び出し数、フック判断のサマリー（allow / deny / instruct の件数）が表示されます。 -**ログのダウンロード**ボタンをクリックするとセッションをエクスポートできます。Claude Code、Codex、Copilot、Cursor、Pi のセッションではディスク上の元の JSONL トランスクリプトがバイト単位でそのまま取得できます。OpenCode（セッションがディスクではなく SQLite に保存される）では、基になる `session` / `messages` / `parts` テーブルを反映した JSON ドキュメントが取得できます。 +**ログをダウンロード** ボタンをクリックするとセッションをエクスポートできます。Claude Code、Codex、Copilot、Cursor、Pi のセッションではディスク上の元の JSONL トランスクリプトがバイト単位でそのまま取得できます。OpenCode（セッションがディスクではなく SQLite に保存）の場合は、基盤となる `session` / `messages` / `parts` テーブルを反映した JSON ドキュメントが取得できます。 ### 監査 -過去のセッション全体にわたってエージェントが実際にどのように動作していたかを示す、個性駆動型のレポートです。`failproofai audit` CLI と同じスキャンを実行しますが、1画面で共有可能なポスター形式と、その下の4つのセクションとして表示されます： +過去のセッションを通じてエージェントが実際にどのように振る舞っていたかをキャラクター付きレポートで表示します。`failproofai audit` CLI と同じスキャンを実行しますが、単一画面の共有可能なポスターと4つの追加セクションとしてレンダリングします。 -1. **ポスター** — 最初のビューポート全体を占めます。failproof_ai ワードマーク + 監査ラベル · アーキタイプインデックス（`№ NN of 08`）+ 監査日 · 数値スコア（0〜100）+ パーセンタイルランクのピル（`top 15%`）· アーキタイプ名（`the optimist`、`the cowboy`、`the explorer`、`the goldfish`、`the paranoid architect`、`the precision builder`、`the hammer`、`the ghost` のいずれか）+ 3キーワードストリップ · `// only N% of agents are this archetype` レアリティライン · 8×8ピクセルのシジルタイル · `audit yours → failproof.ai` フッターを含む、PNG キャプチャ対応の自己完結型リージョン。キャプチャボックスの外側には3つの共有ボタンがあります：`post your archetype`（X インテント）、`share on linkedin`、`download poster`。キャプチャは `html-to-image` で実行されるため、PNG は画面上のレンダリングと完全に一致します（点線ボーダー、SVG ロゴマスク、グラデーション、フォントメトリクスがすべて保持されます）。 -2. **ストレングス** — エージェントがすでに正しく行っている動作を落ち着いた ✓ 行リストで表示します。ライブ監査データから導出されます（クリーンなツール呼び出し率、メインへの直接プッシュなし、認証情報漏洩ゼロ、リトライストームゼロ）— 関連ポリシーが監査ウィンドウ全体でクリーンな記録を持つ場合のみ表示されます。 -3. **クセ** — 見逃した点を重大度順にランク付けしたテーブル：`発生日時 · 何が漏れたか + それを検知したはずのポリシー · 重大度ピル · 確認回数`。再発状況は `new`（1回）、`N× seen`（2〜9回）、`recurring`（10回以上）と表示されます。 -4. **改善方法** — 推奨ポリシーごとに1行の落ち着いた行リスト：白色のポリシー名、1行の説明、右側にインストールコマンド + コピーボタン。セクションヘッダーには `enable all N → projected · `（すべての修正を適用した場合のスコア）と表示され、`[install all]` ボタンをクリックすると、推奨されるすべてのポリシーを一括インストールする `failproofai policy add a b c …` コマンドがコピーされます。 -5. **次回はもっとよく** — 2つの横並びカード。左：リマインダーの設定（`3d` / `7d` / `14d` / `30d` のケイデンスピッカー、認証後に `/api/auth/reminder` 経由で永続化）。右：failproof 特典のロック解除 — `invite a friend` はモーダルを開き、カンマ・スペース・改行区切りの友人のメールアドレスリスト（1回の送信につき最大10件）を入力して `/api/audit/invite` に POST します。これは api-server の `POST /v0/invite` に転送されます。api-server は `invite@failproof.ai` から各受信者に1通のメールを送信し、送信者が Cc に追加され `Reply-To` が設定されるため、受信者には誰が招待したかが分かり、送信者もコピーを受信トレイで受け取れます。匿名ユーザーは招待が送信される前に送信者のメールアドレスを確認するため、最初に `AuthDialog` にルーティングされます。エンタイトルメント・特典の履行は今後のフォローアップ項目です。 +1. **ポスター** — 最初のビューポートを占領します。failproof_ai ワードマーク + 監査ラベル · アーキタイプインデックス（`№ NN of 08`）+ 監査日 · 数値スコア（0〜100）+ パーセンタイルランクのピル（`top 15%`）· アーキタイプ名（`the optimist`、`the cowboy`、`the explorer`、`the goldfish`、`the paranoid architect`、`the precision builder`、`the hammer`、`the ghost` のいずれか）+ 3キーワードストリップ · `// only N% of agents are this archetype` のレア度ライン · 8×8ピクセルのシジルタイル · `audit yours → failproof.ai` フッターを含む自己完結型の PNG キャプチャ領域。キャプチャボックスの外側に3つのシェアボタン: `post your archetype`（X intent）、`share on linkedin`、`download poster`。キャプチャは `html-to-image` を通じて実行されるため、PNG は画面上のレンダリングとピクセル単位で一致します（破線ボーダー、SVG ロゴマスク、グラデーション、フォントメトリクスはすべて保持されます）。 +2. **強み** — エージェントがすでに正しく行っている動作を落ち着いた ✓ 行リストで表示。ライブ監査データ（クリーンなツール呼び出し率、メインへの直接プッシュなし、資格情報漏洩ゼロ、リトライストームゼロ）から導出され、該当ポリシーが監査ウィンドウ全体でクリーンな記録を持つ場合にのみ表示されます。 +3. **問題点** — 見逃されたことの重大度順テーブル：`いつ · 何が見逃されたか + それを検出するはずだったポリシー · 重大度ピル · 発生回数`。再発回数の表示は `new`（1回）、`N× seen`（2〜9回）、`recurring`（10回以上）です。 +4. **改善方法** — 推奨ポリシーごとに1行のリスト。ポリシー名を白色で表示し、1行の説明、インストールコマンドとコピーボタンを右側に配置。セクションヘッダーには `enable all N → projected · `（すべての修正を適用した場合に到達するスコア）が表示され、`[install all]` ボタンで推奨ポリシー全体の `failproofai policy add a b c …` コマンドをまとめてコピーできます。 +5. **より良い状態で戻ってくる** — 2つの横並びカード。左: リマインダーを設定（`3d` / `7d` / `14d` / `30d` のケイデンスピッカー。認証後に `/api/auth/reminder` を通じて保持）。右: failproof 特典を解除 — `invite a friend` はカンマ/スペース/改行区切りの友人メールアドレスリスト（1回の送信で最大10件）を受け付けるモーダルを開き、`/api/audit/invite` に POST します。これは api-server の `POST /v0/invite` に転送されます。api-server は送信者を Cc に加え `Reply-To` を設定した上で、`invite@failproof.ai` から受信者一人ひとりにメールを送信します。これにより受信者は誰に招待されたかがわかり、送信者は自分の受信トレイにもコピーが届きます。未認証ユーザーはまず `AuthDialog` にルーティングされ、招待送信前に送信者のメールアドレスが確認されます。エンタイトルメント / 特典の履行は今後の対応予定です。 -`failproofai audit` ランタイムによって動作します — 基盤となるスキャンエンジン、サポートされるフラグ、トランスクリプトごとのキャッシュ不変条件については [Audit CLI](/ja/cli/audit) を参照してください。ダッシュボードは最新の結果を `~/.failproofai/audit-dashboard.json`（モード `0600`、単一スロット、新しい実行で上書き）にキャッシュするため、再訪問は即座に表示されます。**トランスクリプトごとのキャッシュと全体結果のキャッシュは、7日以上経過すると読み取り時に拒否されます**。これにより、ダッシュボードが1週間前の結果を無言で返すことはありません — TTL を過ぎると `/audit` は空の状態にフォールスルーして新しい実行を促します。レポート下部の `[ re-audit now ]` をクリックすると `/api/audit/run` に `noCache: true` で POST されます — 再監査はトランスクリプトごとのキャッシュをバイパスし、キャッシュされた結果を無言で返すのではなく、すべてのトランスクリプトを最初からスキャンし直します — ダッシュボードは実行が完了するまで 1Hz で `/api/audit/status` をポーリングします。実行中は経過タイマー付きのスティッキーなピンクのプログレスストリップがビューポート上部に固定表示され、成功すると新しい結果がページ全体をリロードせずにその場で置き換えられます（再監査が失敗した場合は以前のレポートがそのまま残ります）。失敗時はストリップが赤くなり、`RerunError.kind`（`timeout` / `network` / `post_failed`）に応じたコピーが表示されます。空の状態（キャッシュなしまたは期限切れ）とセッションゼロ状態（キャッシュは存在するがスキャンでトランスクリプトが見つからなかった）は別々に表示されます。 +`failproofai audit` ランタイムが動力源です。基盤となるスキャンエンジン、対応フラグ、トランスクリプトごとのキャッシュ不変条件については [Audit CLI](/ja/cli/audit) を参照してください。ダッシュボードは最新結果を `~/.failproofai/audit-dashboard.json`（モード `0600`、1スロット、新しい実行で上書き）にキャッシュするため、再訪問は即時に表示されます。**トランスクリプトごとおよび全体結果のキャッシュは、読み取り時に7日以上経過している場合は拒否されます**。そのため、ダッシュボードが1週間前の結果をサイレントに提供することはありません。TTL を過ぎると `/audit` は空の状態に戻り、新規実行を促します。レポート下部の `[ re-audit now ]` をクリックすると `noCache: true` で `/api/audit/run` に POST され、トランスクリプトごとのキャッシュをバイパスしてすべてのトランスクリプトをゼロから再スキャンします。ダッシュボードは実行完了まで 1Hz で `/api/audit/status` をポーリングします。実行中はビューポート上部に経過タイマー付きのスティッキーなピンク色の進捗ストリップが固定表示され、成功時に新しい結果がその場で差し替わります（ページ全体のリロードなし。再監査が失敗した場合は以前のレポートが維持されます）。失敗時はストリップが赤くなり、`RerunError.kind`（`timeout` / `network` / `post_failed`）に対応したコピーが表示されます。空の状態（キャッシュなしまたは期限切れ）とゼロセッション状態（キャッシュは存在するがスキャンでトランスクリプトが見つからなかった）は個別に表示されます。 ### ポリシー -ポリシーの管理とアクティビティの確認のための2タブページです。 +ポリシーの管理とアクティビティの確認を行う2タブのページです。 - - 1つのパネルから failproofai が保護するエージェント CLI を複数選択できます — Claude Code、OpenAI Codex、GitHub Copilot、Cursor Agent、OpenCode、Pi、Hermes の各行にインストール状態（`Active` / `Detected` / `Inactive`）、ユーザースコープの設定パス、ブランドカラーのアクセントが表示されます。保護したい CLI にチェックを入れ、`Apply changes` をクリックすると差分のインストール・アンインストールが一括で実行されます。PATH 上でバイナリが検出された CLI はあらかじめチェックされます。 - - シングルクリックで個々のポリシーのオン・オフを切り替えられます（`~/.failproofai/policies-config.json` に書き込まれ、インストールされたすべての CLI で共有されます） - - ポリシーを展開してパラメーターを設定できます（`policyParams` をサポートするポリシーの場合） - - カスタムポリシーファイルのパスを設定できます + - 単一パネルから failproofai が保護するエージェント CLI を複数選択 — Claude Code、OpenAI Codex、GitHub Copilot、Cursor Agent、OpenCode、Pi、Hermes のそれぞれに、インストール状態（`Active` / `Detected` / `Inactive`）、ユーザースコープの設定パス、ブランドカラーのアクセントが表示されます。保護したい CLI にチェックを入れて `Apply changes` をクリックすると、差分を一括でインストール/アンインストールできます。PATH 上でバイナリが検出された CLI は事前にチェックされます。 + - 個別のポリシーをクリック1つでオン/オフ切り替え（`~/.failproofai/policies-config.json` に書き込まれ、インストール済みのすべての CLI で共有されます） + - ポリシーを展開してパラメーターを設定（`policyParams` をサポートするポリシーのみ） + - カスタムポリシーファイルのパスを設定 - - すべてのセッションにわたって発火したすべてのフックイベントの完全なページネーション履歴 - - 判断、イベントタイプ、CLI（Claude Code / OpenAI Codex / GitHub Copilot _(ベータ)_ / Cursor Agent _(ベータ)_ / OpenCode _(ベータ)_ / Pi _(ベータ)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose）、ポリシー名、セッション ID でフィルタリング可能 - - 各行に表示される情報：タイムスタンプ、ポリシー名、判断、CLI バッジ（オレンジ = Claude Code、パープル = OpenAI Codex、ブルー = GitHub Copilot、エメラルド = Cursor Agent、アンバー = OpenCode、ピンク = Pi、インディゴ = Hermes、ティール = OpenClaw、ローズ = Factory Droid、バイオレット = Devin、シアン = Antigravity、ライム = Goose）、ツール名、セッション ID、deny/instruct 判断の理由 - - セッション ID をクリックするとそのトランスクリプトが開きます — ビューアーはどの CLI がフックを発火させたか（Claude `~/.claude/projects/…`、Codex `~/.codex/sessions/…`、Copilot CLI `~/.copilot/session-state//events.jsonl`、Cursor Agent `~/.cursor/agent-sessions//events.jsonl`、OpenCode `~/.local/share/opencode/opencode.db`、Pi `~/.pi/agent/sessions//.jsonl`、Hermes `~/.hermes/state.db`、OpenClaw `~/.openclaw/agents//sessions/*.jsonl`、Factory Droid `~/.factory/sessions//.jsonl`、Devin `~/.local/share/devin/cli/sessions.db`、Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`、Goose `~/.local/share/goose/sessions/sessions.db`）を自動検出し、ヘッダーに対応する CLI バッジを表示します + - すべてのセッションにわたって発動したすべてのフックイベントの完全なページネーション履歴 + - 判断、イベントタイプ、CLI（Claude Code / OpenAI Codex / GitHub Copilot _(ベータ)_ / Cursor Agent _(ベータ)_ / OpenCode _(ベータ)_ / Pi _(ベータ)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose）、ポリシー名、セッション ID でフィルタリング + - 各行に表示される情報: タイムスタンプ、ポリシー名、判断、CLI バッジ（オレンジ = Claude Code、パープル = OpenAI Codex、ブルー = GitHub Copilot、エメラルド = Cursor Agent、アンバー = OpenCode、ピンク = Pi、インディゴ = Hermes、ティール = OpenClaw、ローズ = Factory Droid、バイオレット = Devin、シアン = Antigravity、ライム = Goose）、ツール名、セッション ID、deny/instruct 判断の理由 + - セッション ID をクリックするとトランスクリプトが開きます — ビューアーはフックを発動した CLI（Claude `~/.claude/projects/…`、Codex `~/.codex/sessions/…`、Copilot CLI `~/.copilot/session-state//events.jsonl`、Cursor Agent `~/.cursor/agent-sessions//events.jsonl`、OpenCode `~/.local/share/opencode/opencode.db`、Pi `~/.pi/agent/sessions//.jsonl`、Hermes `~/.hermes/state.db`、OpenClaw `~/.openclaw/agents//sessions/*.jsonl`、Factory Droid `~/.factory/sessions//.jsonl`、Devin `~/.local/share/devin/cli/sessions.db`、Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`、Goose `~/.local/share/goose/sessions/sessions.db`）を自動検出し、ヘッダーに対応する CLI バッジをレンダリングします @@ -92,25 +94,25 @@ failproofai ## 自動更新 -ダッシュボードのトップナビゲーションには自動更新トグルがあります。有効にすると、現在のページが定期的に更新され、新しいセッションやポリシーアクティビティが表示されます。長時間実行される自律型エージェントセッションの監視に欠かせない機能です。 +ダッシュボードのトップナビゲーションに自動更新トグルがあります。有効にすると、現在のページが定期的に更新され、新しいセッションやポリシーアクティビティがリアルタイムで表示されます。長時間実行される自律型エージェントセッションの監視に欠かせない機能です。 --- ## ページの無効化 -ダッシュボードの一部のみが必要な場合は、`FAILPROOFAI_DISABLE_PAGES` にページ名をカンマ区切りで設定します： +ダッシュボードの一部のみを使用したい場合は、`FAILPROOFAI_DISABLE_PAGES` にカンマ区切りのページ名リストを設定します。 ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai ``` -有効な値：`policies`、`projects`、`audit`。 +有効な値: `policies`、`projects`、`audit` --- ## プロジェクトパスの設定 -デフォルトでは、ダッシュボードは標準の Claude Code プロジェクトディレクトリから読み込みます。カスタムセットアップの場合は上書きできます： +デフォルトでは、ダッシュボードは標準の Claude Code プロジェクトディレクトリから読み込みます。カスタム設定の場合は上書きしてください。 ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,30 +122,30 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## localhost 以外のホストからのアクセス -**開発モード**（`npm run dev`）でダッシュボードを実行し、`localhost` 以外のホスト名（例：カスタムドメイン、リモートIP、トンネルURL）からアクセスすると、次のような警告が表示される場合があります： +**開発モード**（`npm run dev`）でダッシュボードを実行し、`localhost` 以外のホスト名（カスタムドメイン、リモート IP、トンネルURL など）からアクセスする場合、次のような警告が表示されることがあります。 ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -これは Next.js がその HMR（ホットモジュールリロード）WebSocket へのクロスオリジンアクセスをブロックしているためで、開発専用の機能です。ホストを許可するには `--allowed-origins` フラグを使用してください： +これは Next.js が開発専用機能である HMR（ホットモジュールリロード）ウェブソケットへのクロスオリジンアクセスをブロックしているものです。ホストを許可するには `--allowed-origins` フラグを使用してください。 ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -複数のホストまたはIPの場合は、カンマ区切りのリストで指定します： +複数のホストや IP を許可する場合は、カンマ区切りのリストで渡します。 ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -代わりに `FAILPROOFAI_ALLOWED_DEV_ORIGINS` 環境変数を設定することもできます： +環境変数 `FAILPROOFAI_ALLOWED_DEV_ORIGINS` で設定することもできます。 ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -これは開発モードにのみ適用されます。`failproofai`（本番モード）を実行する場合、HMR WebSocket やクロスオリジン開発リソースの問題は発生しません。 +これは開発モードにのみ適用されます。`failproofai`（本番モード）を実行する場合、HMR ウェブソケットは存在せず、クロスオリジン開発リソースの問題も発生しません。 \ No newline at end of file diff --git a/docs/ko/configuration.mdx b/docs/ko/configuration.mdx index d4a99ddf..bc3ea455 100644 --- a/docs/ko/configuration.mdx +++ b/docs/ko/configuration.mdx @@ -1,28 +1,28 @@ --- title: 설정 -description: "설정 파일 형식, 세 가지 범위 시스템, 그리고 병합 규칙" +description: "설정 파일 형식, 세 가지 범위 시스템, 병합 규칙" icon: gear --- -failproofai는 JSON 설정 파일을 사용하여 어떤 정책이 활성화되어 있는지, 정책이 어떻게 동작하는지, 그리고 커스텀 정책을 어디에서 불러올지를 제어합니다. 설정은 팀과 쉽게 공유할 수 있도록 설계되어 있습니다. 저장소에 커밋하면 모든 개발자가 동일한 에이전트 안전망을 갖게 됩니다. +failproofai는 JSON 설정 파일을 사용하여 어떤 정책이 활성화되는지, 정책이 어떻게 동작하는지, 그리고 커스텀 정책을 어디서 불러올지 제어합니다. 설정은 팀과 쉽게 공유할 수 있도록 설계되었습니다. 저장소에 커밋해두면 모든 개발자가 동일한 에이전트 안전망을 갖게 됩니다. --- ## 설정 범위 -설정 범위는 세 가지이며, 우선순위 순서대로 평가됩니다: +세 가지 설정 범위가 있으며, 우선순위 순서대로 평가됩니다: | 범위 | 파일 경로 | 용도 | -|------|-----------|------| +|-------|-----------|---------| | **project** | `.failproofai/policies-config.json` | 저장소별 설정, 버전 관리에 커밋 | -| **local** | `.failproofai/policies-config.local.json` | 개인 저장소별 오버라이드, gitignore 처리 | +| **local** | `.failproofai/policies-config.local.json` | 개인용 저장소별 오버라이드, gitignore 처리 | | **global** | `~/.failproofai/policies-config.json` | 모든 프로젝트에 적용되는 사용자 수준 기본값 | -failproofai가 훅 이벤트를 수신하면, 현재 작업 디렉터리에 존재하는 세 파일을 모두 로드하여 병합합니다. +failproofai가 훅 이벤트를 수신하면 현재 작업 디렉토리에 대해 존재하는 세 파일을 모두 불러와 병합합니다. ### 병합 규칙 -**`enabledPolicies`** - 세 범위의 합집합입니다. 어느 수준에서든 활성화된 정책은 적용됩니다. +**`enabledPolicies`** - 세 범위 모두의 합집합입니다. 어느 수준에서든 활성화된 정책은 적용됩니다. ```text project: ["block-sudo"] @@ -32,13 +32,13 @@ global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← 중복 제거된 합집합 ``` -**`policyParams`** - 특정 정책에 대해 파라미터를 정의한 첫 번째 범위가 전적으로 우선합니다. 정책 파라미터 내부 값의 깊은 병합은 이루어지지 않습니다. +**`policyParams`** - 특정 정책에 대한 파라미터를 먼저 정의하는 범위가 전부 가져갑니다. 정책 파라미터 내부에서는 깊은 병합이 이루어지지 않습니다. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← project 우선, global 무시 +resolved: { allowPatterns: ["sudo apt-get update"] } ← project가 우선, global은 무시됨 ``` ```text @@ -46,12 +46,14 @@ project: (block-sudo 항목 없음) local: (block-sudo 항목 없음) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← global까지 내려감 +resolved: { allowPatterns: ["sudo systemctl status"] } ← global로 폴스루 ``` -**`customPoliciesPath`** - 이를 정의한 첫 번째 범위가 우선합니다. +**`customPoliciesPaths` / `customPoliciesPath`** - 어느 쪽 형식이든 먼저 정의하는 범위가 우선합니다. -**`llm`** - 이를 정의한 첫 번째 범위가 우선합니다. +**`disabledCustomPolicies`** - 모든 범위에 걸쳐 합집합으로 처리됩니다. 대시보드에서 명시적 또는 컨벤션 정책 파일의 개별 정책을 끄면 소스가 포함된 ID가 여기에 기록됩니다. 목록에 없는 정책은 기본적으로 활성화 상태를 유지하며, ID에 소스 파일이 포함되어 있으므로 여러 파일에서 같은 이름의 정책을 독립적으로 제어할 수 있습니다. + +**`llm`** - 먼저 정의하는 범위가 우선합니다. --- @@ -102,27 +104,27 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global까지 내려 타입: `string[]` -활성화할 정책 이름 목록입니다. 이름은 `failproofai policies`에서 표시되는 정책 식별자와 정확히 일치해야 합니다. 전체 목록은 [기본 제공 정책](/ko/built-in-policies)을 참고하세요. +활성화할 정책 이름 목록입니다. 이름은 `failproofai policies`에서 표시되는 정책 식별자와 정확히 일치해야 합니다. 전체 목록은 [기본 제공 정책](/ko/built-in-policies)을 참조하세요. -`enabledPolicies`에 없는 정책은 `policyParams`에 항목이 있더라도 비활성 상태입니다. +`enabledPolicies`에 포함되지 않은 정책은 `policyParams`에 항목이 있더라도 비활성 상태입니다. ### `policyParams` 타입: `Record>` -정책별 파라미터 오버라이드입니다. 외부 키는 정책 이름이고, 내부 키는 정책별로 다릅니다. 각 정책의 사용 가능한 파라미터는 [기본 제공 정책](/ko/built-in-policies)에 설명되어 있습니다. +정책별 파라미터 오버라이드입니다. 외부 키는 정책 이름이고, 내부 키는 정책별로 다릅니다. 각 정책의 사용 가능한 파라미터는 [기본 제공 정책](/ko/built-in-policies)에 문서화되어 있습니다. -파라미터가 있는 정책에 파라미터를 지정하지 않으면 정책의 기본값이 사용됩니다. `policyParams`를 전혀 설정하지 않은 사용자는 이전 버전과 동일하게 동작합니다. +정책에 파라미터가 있지만 직접 지정하지 않으면 정책의 기본값이 사용됩니다. `policyParams`를 전혀 설정하지 않은 사용자는 이전 버전과 동일한 동작을 경험합니다. -정책 파라미터 블록 내의 알 수 없는 키는 훅 실행 시 무시되지만, `failproofai policies` 실행 시 경고로 표시됩니다. +정책 파라미터 블록 내의 알 수 없는 키는 훅 실행 시 자동으로 무시되지만, `failproofai policies`를 실행할 때 경고로 표시됩니다. -#### `hint` (공통 설정) +#### `hint` (공통 적용) 타입: `string` (선택 사항) -정책이 `deny` 또는 `instruct`를 반환할 때 reason에 추가되는 메시지입니다. 정책 자체를 수정하지 않고도 Claude에게 실행 가능한 안내를 제공할 때 사용합니다. +정책이 `deny` 또는 `instruct`를 반환할 때 사유에 추가되는 메시지입니다. 정책 자체를 수정하지 않고도 Claude에게 실행 가능한 안내를 제공하는 데 사용합니다. -기본 제공, 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 등 모든 정책 유형에서 사용할 수 있습니다. +기본 제공 정책, 커스텀 정책(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 등 모든 정책 유형에서 작동합니다. ```json { @@ -141,40 +143,40 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global까지 내려 } ``` -`block-force-push`가 거부할 경우 Claude는 다음과 같은 메시지를 받습니다: *"Force-pushing is blocked. Try creating a fresh branch instead."* +`block-force-push`가 거부하면 Claude는 다음과 같은 메시지를 받습니다: *"Force-pushing is blocked. Try creating a fresh branch instead."* -문자열이 아닌 값과 빈 문자열은 무시됩니다. `hint`가 설정되지 않으면 동작이 변경되지 않습니다(하위 호환성 유지). +문자열이 아닌 값과 빈 문자열은 자동으로 무시됩니다. `hint`가 설정되지 않으면 동작은 변경되지 않습니다(하위 호환성 유지). ### `customPoliciesPath` 타입: `string` (절대 경로) -커스텀 훅 정책이 포함된 JavaScript 파일의 경로입니다. `failproofai policies --install --custom ` 명령으로 자동 설정됩니다(경로는 저장 전에 절대 경로로 변환됩니다). +커스텀 훅 정책이 포함된 JavaScript 파일의 경로입니다. `failproofai policies --install --custom `를 실행하면 자동으로 설정됩니다(경로는 저장 전에 절대 경로로 변환됩니다). -파일은 훅 이벤트마다 새로 로드되며 캐싱이 없습니다. 작성 방법은 [커스텀 정책](/ko/custom-policies)을 참고하세요. +파일은 매 훅 이벤트마다 새로 불러옵니다. 캐싱은 없습니다. 작성 방법에 대한 자세한 내용은 [커스텀 정책](/ko/custom-policies)을 참조하세요. ### 컨벤션 기반 정책 -명시적인 `customPoliciesPath` 외에도, failproofai는 `.failproofai/policies/` 디렉터리에서 정책 파일을 자동으로 검색하여 로드합니다: +명시적인 `customPoliciesPath` 외에도 failproofai는 `.failproofai/policies/` 디렉토리에서 정책 파일을 자동으로 탐색하고 불러옵니다: -| 수준 | 디렉터리 | 범위 | -|------|-----------|------| +| 수준 | 디렉토리 | 범위 | +|-------|-----------|-------| | 프로젝트 | `.failproofai/policies/` | 버전 관리를 통해 팀과 공유 | | 사용자 | `~/.failproofai/policies/` | 개인용, 모든 프로젝트에 적용 | -**파일 매칭:** `*policies.{js,mjs,ts}` 패턴과 일치하는 파일만 로드됩니다(예: `security-policies.mjs`, `workflow-policies.js`). 디렉터리 내 다른 파일은 무시됩니다. +**파일 매칭:** `*policies.{js,mjs,ts}` 패턴과 일치하는 파일만 불러옵니다(예: `security-policies.mjs`, `workflow-policies.js`). 디렉토리 내 다른 파일은 무시됩니다. -**별도 설정 불필요:** 컨벤션 정책은 `policies-config.json`에 항목을 추가할 필요가 없습니다. 디렉터리에 파일을 넣기만 하면 다음 훅 이벤트 시 자동으로 인식됩니다. +**설정 불필요:** 컨벤션 정책은 `policies-config.json`에 항목을 추가할 필요가 없습니다. 디렉토리에 파일을 넣기만 하면 다음 훅 이벤트에서 자동으로 적용됩니다. -**합집합 로딩:** 프로젝트와 사용자 컨벤션 디렉터리가 모두 스캔됩니다. 두 수준에서 일치하는 모든 파일이 로드됩니다(첫 번째 범위 우선 방식을 사용하는 `customPoliciesPath`와 다릅니다). +**합집합 로딩:** 프로젝트와 사용자 컨벤션 디렉토리 모두 스캔됩니다. 두 수준의 일치하는 파일이 모두 불러와집니다(`customPoliciesPath`의 첫 번째 범위 우선 방식과 다릅니다). -자세한 내용과 예시는 [커스텀 정책](/ko/custom-policies)을 참고하세요. +자세한 내용과 예제는 [커스텀 정책](/ko/custom-policies)을 참조하세요. ### `llm` 타입: `object` (선택 사항) -AI 호출을 수행하는 정책을 위한 LLM 클라이언트 설정입니다. 대부분의 경우 필요하지 않습니다. +AI 호출을 수행하는 정책을 위한 LLM 클라이언트 설정입니다. 대부분의 설정에서는 필요하지 않습니다. ```json { @@ -189,19 +191,24 @@ AI 호출을 수행하는 정책을 위한 LLM 클라이언트 설정입니다. ## CLI에서 설정 관리하기 -`policies --install` 및 `policies --uninstall` 명령은 에이전트 CLI의 훅 설정 파일(훅 진입점)에 기록하며, `policies-config.json`은 직접 관리하는 파일입니다. 두 가지는 별개입니다: +`policies --install`과 `policies --uninstall` 명령은 에이전트 CLI의 훅 설정 파일(훅 진입점)에 씁니다. 반면 `policies-config.json`은 직접 관리하는 파일입니다. 두 가지는 별개입니다: - **에이전트 CLI 설정** — 에이전트가 각 도구 사용 시 `failproofai --hook `를 호출하도록 지시합니다: - **Claude Code**: `~/.claude/settings.json` (사용자), `/.claude/settings.json` (프로젝트), `/.claude/settings.local.json` (로컬) - - **OpenAI Codex**: `~/.codex/hooks.json` (사용자), `/.codex/hooks.json` (프로젝트) — Codex는 `local` 범위가 없습니다 - - **GitHub Copilot CLI _(베타)_**: `~/.copilot/hooks/failproofai.json` (사용자), `/.github/hooks/failproofai.json` (프로젝트) — Copilot에는 `local` 범위가 없습니다. 훅 항목은 Copilot의 OS별 `bash`/`powershell` 명령 필드와 `timeoutSec`를 사용하며, 파일 최상단에 `version: 1` 마커가 있습니다. `events.jsonl` 레코드 스키마(공개 문서에 명시되지 않음)를 더 많은 실제 세션을 통해 검증 중이므로 Copilot CLI 지원은 **베타** 상태입니다. - - **Cursor Agent _(베타)_**: `~/.cursor/hooks.json` (사용자), `/.cursor/hooks.json` (프로젝트) — Cursor에는 `local` 범위가 없습니다. 훅 항목은 Claude 형식의 `{type, command, timeout}` 구조를 사용하지만(`bash`/`powershell` 분리 없음), Cursor의 [훅 스키마](https://cursor.com/docs/hooks)에 따라 camelCase 이벤트 키(`preToolUse`, `beforeSubmitPrompt` 등) 아래 플랫 배열로 저장되며 파일 최상단에 `version: 1` 마커가 있습니다. 핸들러는 `CURSOR_EVENT_MAP`을 통해 camelCase → PascalCase로 정규화하므로 기존 기본 제공 정책이 변경 없이 동작합니다. Cursor의 트랜스크립트 온디스크 형식(공개 문서에 명시되지 않음)을 더 많은 실제 설치를 통해 검증 중이므로 Cursor Agent 지원은 **베타** 상태입니다. - - **OpenCode _(베타)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (사용자), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (프로젝트) — OpenCode에는 `local` 범위가 없습니다. 다른 다섯 CLI와 달리 OpenCode에는 **외부 명령 훅 시스템이 없습니다**: `opencode.json`의 `plugin: []` 배열을 통해 명시적으로 등록된 인프로세스 JS/TS 플러그인을 로드합니다(`.opencode/plugins/`에서의 자동 검색은 opencode v1.14.33에서 플러그인이 로드되는 방식이 **아닙니다**). 설치 시 failproofai 바이너리를 서브프로세스로 호출하고 바이너리의 Claude 형식 JSON 응답을 플러그인 시맨틱으로 변환하는 작은 생성된 플러그인 심을 배치합니다: 도구 이벤트 거부 시 `throw new Error()`(도구 호출 취소), instruct와 `Stop`/`SubagentStop` 거부 시 `client.session.prompt(...)`(거부 이유를 다음 사용자 메시지로 제출 — `session.idle`은 알림 전용이고 거기서 throw는 no-op이므로 유일한 강제 재시도 채널), allow 시 no-op. 심은 도구 이름(소문자 → PascalCase, `OPENCODE_TOOL_MAP` 사용)과 도구 입력 인수 키(camelCase → snake_case, `Read`/`Write`/`Edit`용 `OPENCODE_TOOL_INPUT_MAP` 사용, 예: `filePath` → `file_path`, `oldString` → `old_string`)를 바이너리에 전달하기 전에 정규화하므로 `block-read-outside-cwd`, `block-env-files`, `block-secrets-write` 같은 경로 확인 기본 정책이 OpenCode 도구 호출에서도 변경 없이 동작합니다. 세션은 `~/.local/share/opencode/opencode.db`의 opencode SQLite DB에 저장되며, 대시보드의 세션 뷰어는 `opencode db --format json` 및 `opencode export `를 통해 읽습니다. 버전 간 동작 및 더 많은 실제 세션 검증 중이므로 OpenCode 지원은 **베타** 상태입니다. [OpenCode 플러그인 문서](https://opencode.ai/docs/plugins/)를 참고하세요. - - **Pi _(베타)_**: `~/.pi/agent/settings.json` (사용자), `/.pi/settings.json` (프로젝트) — Pi에는 `local` 범위가 없습니다. Pi는 시작 시 TypeScript 확장 패키지를 로드하며, 설정 파일은 `{"packages": ["./relative/path", …]}` 형식의 플랫 문자열 배열입니다. failproofai는 번들된 `pi-extension/` 디렉터리를 가리키는 단일 packages 배열 항목을 씁니다. 확장은 내부적으로 Pi의 `tool_call`/`user_bash`/`input`/`session_start` 이벤트를 구독하고 `failproofai --hook --cli pi`를 셸아웃합니다. 핸들러는 `PI_EVENT_MAP`을 통해 underscore_lower_snake_case → PascalCase로 이벤트를 정규화하므로 기존 기본 제공 정책이 변경 없이 동작합니다. 도구 입력 인수도 `PI_TOOL_INPUT_MAP`을 통해 정규화됩니다(Pi의 Read/Write/Edit는 `file_path` 대신 `path`를 전달하며, 최상위 키를 매핑하면 `block-env-files`와 `block-secrets-write`가 동작합니다 — `block-read-outside-cwd`는 이미 `path` 폴백이 있었습니다). Pi의 확장 API와 세션 로그 레이아웃이 안정화되는 동안 Pi 지원은 **베타** 상태입니다. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**사용자 범위만** — Hermes에는 프로젝트/로컬 설정이 없습니다). Hermes는 Slack/Telegram **게이트웨이**이므로, 설치 한 번으로 모든 플랫폼(Slack/Telegram/cli/cron)과 내부 서브에이전트의 도구 호출을 가로챕니다. 훅 항목은 Hermes의 snake_case 이벤트(`pre_tool_call`/`post_tool_call`/`on_session_start`/`on_session_end`/`subagent_stop`)를 키로 하는 `hooks:` 맵 아래 `{command, timeout}` 쌍(timeout은 **초** 단위)입니다. 핸들러는 `HERMES_EVENT_MAP`으로 이벤트를, `HERMES_TOOL_MAP`으로 도구 이름을 정규화하므로 기본 제공 정책이 변경 없이 동작합니다. 설정은 주석 보존 YAML `Document` 라운드트립을 통해 편집되므로 운영자의 다른 설정이 유지되며, 설치 시 `hooks_auto_accept: true`로 설정되어 헤드리스 게이트웨이(TTY 없음)가 동의 프롬프트 없이 훅을 실행합니다. 평가기는 Hermes의 `{"decision":"block","reason"}` stdout 계약을 반환합니다(Hermes는 종료 코드를 무시합니다). **제한 사항:** Hermes에는 턴 종료 `Stop` 이벤트가 없으므로 `require-*-before-stop` 기본 정책은 동작하지 않습니다(해당 없음, 오류 아님). `instruct`는 allow-with-logged-note로 격하됩니다(추가 컨텍스트 채널 없음). 출력 시크릿 편집(`sanitize-*`)은 셸 훅 계약으로 도구 출력을 재작성할 수 없습니다. Hermes는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.hermes/state.db`에서 게이트웨이 세션을 직접 읽습니다. -- **`policies-config.json`** — failproofai에게 어떤 정책을 어떤 파라미터로 평가할지 지시합니다(모든 에이전트 CLI에 공통 적용) - -특정 에이전트를 대상으로 하려면 `--cli claude|codex|copilot|cursor|opencode|pi|hermes`를 전달하세요(여러 개는 공백으로 구분하거나 반복 사용): + - **OpenAI Codex**: `~/.codex/hooks.json` (사용자), `/.codex/hooks.json` (프로젝트) — Codex에는 `local` 범위가 없습니다 + - **GitHub Copilot CLI _(베타)_**: `~/.copilot/hooks/failproofai.json` (사용자), `/.github/hooks/failproofai.json` (프로젝트) — Copilot에는 `local` 범위가 없습니다. 훅 항목은 `timeoutSec`과 함께 Copilot의 OS별 `bash`/`powershell` 명령 필드를 사용하며, 파일 최상위에 `version: 1` 마커가 있습니다. Copilot CLI 지원은 **베타** 상태입니다. 공개 문서에 명시되지 않은 `events.jsonl` 레코드 스키마를 더 많은 실제 세션에서 검증하는 중입니다. **VS Code Copilot Chat 에이전트 모드(미리보기)**는 `chat.hookFilesLocations` 설정으로 관리되는 `.github/hooks/*.json`, `~/.copilot/hooks/*.json`, `~/.claude/settings.json`에서 훅 설정을 읽으며, 동일한 Claude 형태의 `{hookSpecificOutput:{permissionDecision:"deny",…}}` 계약을 사용합니다. 이는 `copilot` 통합과 `claude` 통합(`~/.claude/settings.json`)이 이미 쓰는 경로와 동일하므로, `failproofai policies --install --cli copilot` (또는 `--cli claude`)만으로 **VS Code 에이전트 모드에서도 별도의 `vscode` 통합 없이 즉시 적용됩니다** (VS Code의 탐색 로그에서 실제로 확인됨). + - **Cursor Agent _(베타)_**: `~/.cursor/hooks.json` (사용자), `/.cursor/hooks.json` (프로젝트) — Cursor에는 `local` 범위가 없습니다. 훅 항목은 Claude 형태의 `{type, command, timeout}` 구조를 사용하지만(`bash`/`powershell` 분리 없음), Cursor의 [훅 스키마](https://cursor.com/docs/hooks)에 따라 camelCase 이벤트 키(`preToolUse`, `beforeSubmitPrompt` 등) 아래 평탄한 배열로 저장됩니다. 파일 최상위에 `version: 1` 마커가 있습니다. 핸들러는 `CURSOR_EVENT_MAP`을 통해 camelCase → PascalCase로 정규화하므로 기존 기본 제공 정책이 변경 없이 작동합니다. Cursor Agent 지원은 **베타** 상태입니다. Cursor의 온디스크 트랜스크립트 형식(공개 문서에 명시되지 않음)을 더 많은 실제 설치 환경에서 검증하는 중입니다. + - **OpenCode _(베타)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (사용자), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (프로젝트) — OpenCode에는 `local` 범위가 없습니다. 다른 다섯 CLI와 달리 OpenCode에는 **외부 명령 훅 시스템이 없습니다**: `opencode.json`의 `plugin: []` 배열에 명시적으로 등록된 인프로세스 JS/TS 플러그인을 불러옵니다(`.opencode/plugins/`의 자동 탐색은 opencode v1.14.33에서 플러그인을 불러오는 방식이 **아닙니다**). 설치 시 failproofai 바이너리를 서브프로세스로 호출하고 바이너리의 Claude 형태 JSON 응답을 플러그인 시맨틱으로 변환하는 작은 생성 플러그인 심을 배치합니다: 도구 이벤트 거부 시 `throw new Error()`(도구 호출 취소), instruct 및 `Stop` / `SubagentStop` 거부 시 `client.session.prompt(...)`(거부 사유를 다음 사용자 메시지로 제출 — `session.idle`이 알림 전용이고 거기서 throw는 무작동이므로 유일한 강제 재시도 채널), 허용 시 무작동. 심은 도구 이름(`OPENCODE_TOOL_MAP`을 통해 소문자 → PascalCase)과 도구 입력 인수 키(`OPENCODE_TOOL_INPUT_MAP`을 통해 `Read` / `Write` / `Edit`의 camelCase → snake_case, 예: `filePath` → `file_path`, `oldString` → `old_string`)를 바이너리에 전달하기 전에 정규화하므로 `block-read-outside-cwd`, `block-env-files`, `block-secrets-write` 같은 경로 확인 내장 정책이 OpenCode 도구 호출에서도 변경 없이 작동합니다. 세션은 `~/.local/share/opencode/opencode.db`의 OpenCode SQLite DB에 저장됩니다. 대시보드의 세션 뷰어는 `opencode db --format json`과 `opencode export `를 통해 세션을 읽습니다. OpenCode 지원은 **베타** 상태입니다. 버전 간 동작과 더 많은 실제 세션에서 검증하는 중입니다. [OpenCode 플러그인 문서](https://opencode.ai/docs/plugins/)를 참조하세요. + - **Pi _(베타)_**: `~/.pi/agent/settings.json` (사용자), `/.pi/settings.json` (프로젝트) — Pi에는 `local` 범위가 없습니다. Pi는 시작 시 TypeScript 확장 패키지를 불러옵니다. 설정 파일은 평탄한 문자열 배열 `{"packages": ["./relative/path", …]}` 형태입니다. failproofai는 번들된 `pi-extension/` 디렉토리를 가리키는 단일 packages 배열 항목을 씁니다. 확장은 내부적으로 Pi의 `tool_call` / `user_bash` / `input` / `session_start` 이벤트를 구독하고 `failproofai --hook --cli pi`를 쉘아웃합니다. 핸들러는 `PI_EVENT_MAP`을 통해 underscore_lower_snake_case → PascalCase로 정규화하므로 기존 내장 정책이 변경 없이 작동합니다. 도구 입력 인수도 `PI_TOOL_INPUT_MAP`을 통해 정규화됩니다(Pi의 Read / Write / Edit는 `file_path` 대신 `path`를 전달하므로, 최상위 키를 매핑하면 `block-env-files`와 `block-secrets-write`가 작동합니다 — `block-read-outside-cwd`는 이미 `path` 폴백이 있었습니다). Pi 지원은 **베타** 상태입니다. Pi의 확장 API와 세션 로그 레이아웃이 안정화되는 과정에 있습니다. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**사용자 범위만** — Hermes에는 프로젝트/로컬 설정이 없습니다). Hermes는 Slack/Telegram **게이트웨이**이므로, 한 번 설치하면 모든 플랫폼(Slack/Telegram/cli/cron)의 도구 호출 **및** 내부 서브에이전트를 차단합니다. 훅 항목은 Hermes의 snake_case 이벤트(`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) 키 아래 `hooks:` 맵의 `{command, timeout}` 쌍입니다(timeout은 **초** 단위). 핸들러는 `HERMES_EVENT_MAP`을 통해 이벤트를, `HERMES_TOOL_MAP`을 통해 도구 이름을 정규화하므로 내장 정책이 변경 없이 작동합니다. 설정은 주석을 보존하는 YAML `Document` 왕복 방식으로 편집되므로 운영자의 다른 설정이 유지됩니다. 설치 시 `hooks_auto_accept: true`를 설정하여 TTY가 없는 헤드리스 게이트웨이가 동의 프롬프트 없이 훅을 실행합니다. 평가기는 Hermes의 `{"decision":"block","reason"}` stdout 계약을 출력합니다(Hermes는 종료 코드를 무시). **제한 사항:** Hermes에는 턴 종료 `Stop` 이벤트가 없으므로 `require-*-before-stop` 내장 정책은 Hermes에서 실행되지 않습니다(적용 불가, 오류 아님). `instruct`는 allow-with-logged-note로 저하됩니다(추가 컨텍스트 채널 없음). 출력 비밀 교체(`sanitize-*`)는 쉘 훅 계약으로 도구 출력을 재작성할 수 없습니다. Hermes는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.hermes/state.db`에서 게이트웨이 세션을 직접 읽습니다. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**사용자 범위만** — OpenClaw에는 프로젝트/로컬 설정이 없습니다). Hermes와 마찬가지로 OpenClaw는 자체 호스팅 멀티채널 **게이트웨이**이므로, 한 번 설치하면 모든 채널과 내부 서브에이전트의 도구 호출을 차단합니다. 적용은 OpenClaw의 **인프로세스 플러그인 훅**을 통해 이루어집니다(파일 기반 내부 훅은 관찰 전용이며 차단 불가). 따라서 OpenCode/Pi처럼 failproofai는 failproofai 바이너리를 비동기로 스폰하고 판정을 변환하는 정적 `openclaw-plugin/` 패키지를 제공합니다. 설치 시 `openclaw.json`의 `plugins.load.paths[]`에 제공된 플러그인 디렉토리를 등록하고 `plugins.entries.failproofai` 아래 활성화합니다(`hooks.allowConversationAccess: true` 포함, 원시 대화 훅에 필요). 평가기는 평탄한 `{permission, reason}` 판정을 출력하며 심은 각 훅의 기본 반환 형태로 매핑합니다: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), `before_agent_finalize → {action:"revise", reason}` (**Stop** — 실제 턴 종료 게이트이므로 `require-*-before-stop` 내장 정책이 OpenClaw에서 **적용됩니다**, Hermes와 달리). 이벤트와 도구 이름은 `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP`(`exec→Bash`, `read→Read` 등)을 통해 바이너리 측에서 정규화되므로 내장 정책이 변경 없이 작동합니다. 심은 스폰/파싱/타임아웃 오류 시 허용 방향으로 실패합니다. OpenClaw는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.openclaw/agents//sessions/.jsonl`의 JSONL 세션을 읽습니다. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (사용자), `/.factory/hooks.json` (프로젝트) — Factory에는 `local` 범위가 없습니다. droid는 Claude 형태의 외부 명령 훅 시스템을 제공하지만, droid v0.171.0에서 실제 검증된 두 가지 특이점이 있습니다: (1) 이벤트 이름이 `hooks.json`의 **최상위 레벨**에 위치합니다 — **`"hooks"` 래퍼가 없습니다**(droid가 거부). 도구 이벤트(`PreToolUse`/`PostToolUse`)에는 `"matcher": "*"`가 있고, 비도구 이벤트는 생략합니다. (2) 거부는 훅 **종료 코드 2 + stderr**로 구동됩니다. JSON 결정이 아닙니다 — 평가기의 `factory` 브랜치는 도구/프롬프트 이벤트에 종료 코드 2를 반환하고, 턴 종료 `Stop` 이벤트에만 `{decision:"block", reason}`을 반환합니다(droid의 유일한 강제 재시도 채널). 이벤트는 이미 PascalCase입니다(이벤트 맵 없음). 페이로드는 Claude snake_case입니다. 도구 이름만 `FACTORY_TOOL_MAP`을 통해 정규화됩니다(`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch` 등). Factory는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.factory/sessions//.jsonl`의 온디스크 JSONL 세션을 읽습니다. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (사용자), `/.devin/config.json` (프로젝트) — Devin에는 `local` 범위가 없습니다. Devin은 devin v3000.1.27에서 실제 검증된 **순수 Claude 클론**입니다: 표준 Claude `"hooks"` 래퍼 스키마를 사용하며(쓰기는 병합 보존 방식이므로 설정 파일의 다른 키 — `org_id`, `theme_mode` 등 — 가 유지됩니다), 이미 PascalCase 이벤트 이름(이벤트 맵 없음, 핸들러 브랜치 없음), Claude snake_case stdin 페이로드(정규화 없음)를 사용합니다. 평가기의 `devin` 브랜치는 **모든** 이벤트에 대해 종료 코드 0에서 `{"decision":"block","reason"}` JSON을 stdout으로 출력하여 거부합니다(검증됨 — 블록이 `--permission-mode dangerous`를 재정의함). 턴 종료 `Stop` 이벤트에서는 사유에 MANDATORY-ACTION 강제 재시도 문구가 포함되므로 `require-*-before-stop` 내장 정책이 적용됩니다. 도구 이름만 `DEVIN_TOOL_MAP`을 통해 정규화됩니다(`exec→Bash`; `tool_input.command`는 이미 정규형). Devin은 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.local/share/devin/cli/sessions.db`의 SQLite 세션을 읽습니다(각 `sessions` 행에 실제 `working_directory`가 있으므로 Claude처럼 프로젝트 cwd별로 세션이 그룹화됩니다). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (사용자), `/.agents/hooks.json` (프로젝트) — Antigravity에는 `local` 범위가 없습니다. Factory/Devin과 달리 Antigravity는 agy v1.1.2에서 실제 검증된 **자체 계약**을 가집니다(Claude 클론이 아님). `hooks.json`은 **이름 있는 훅** 스키마를 사용합니다: 최상위 키는 훅 *이름*(`"failproofai"`)이며, 그 값은 이벤트→핸들러 맵입니다 — 도구 이벤트(`PreToolUse`/`PostToolUse`)는 핸들러를 `{matcher:"*", hooks:[…]}`로 감싸고, `PreInvocation`/`Stop`은 **평탄한** 핸들러 배열입니다(다른 이름 있는 훅은 보존됩니다). stdin 페이로드는 **camelCase protojson**(`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`)입니다 — failproofai는 정책 실행 전에 snake_case로 정규화하고, `run_command`의 PascalCase 인수(`CommandLine`/`Cwd`)는 `ANTIGRAVITY_TOOL_INPUT_MAP`을 통해 매핑합니다. 평가기의 `antigravity` 브랜치는 Antigravity 자체 응답 형태를 사용합니다: `{decision:"deny", reason}`은 도구/프롬프트를 차단하고(종료 코드 0), `{decision:"continue", reason}`은 턴 종료 `Stop`에서 루프를 재진입하며(`require-*-before-stop` 내장 정책이 적용됨), `{injectSteps:[{ephemeralMessage}]}`는 `PreInvocation`(→ `UserPromptSubmit`)에서 지침을 주입합니다. 도구 이름은 `ANTIGRAVITY_TOOL_MAP`을 통해 정규화됩니다(`run_command→Bash`, `view_file→Read` 등). Antigravity는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl`의 일반 JSONL 트랜스크립트를 읽습니다(대화 인덱스는 `conversation_summaries.db`에 있습니다). + - **Goose (코드명 goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (사용자), `/.agents/plugins/failproofai/hooks/hooks.json` (프로젝트) — Goose에는 `local` 범위가 없습니다. 적용은 Goose의 **훅** 시스템인 크로스에이전트 **Open Plugins** 사양을 사용합니다: 설치기가 `failproofai` 플러그인 디렉토리를 배치하면 Goose가 시작 시 자동으로 탐색합니다(`~/.config/goose/config.yaml`에 자동 등록). `hooks.json`은 **최상위 `"hooks"` 래퍼**가 있는 Open Plugins 스키마를 사용하며, 모든 이벤트에서 matcher가 **생략됩니다** — 단독 `"*"`는 아무것도 매칭하지 않는 유효하지 않은 정규식입니다(goose v1.43.0에서 실제 검증됨). 이벤트 이름은 이미 PascalCase입니다(이벤트 맵 없음). stdin 페이로드는 `event`/`working_dir`를 사용하며, 핸들러가 이를 `hook_event_name`/`cwd`로 정규화합니다. 평가기의 `goose` 브랜치는 종료 코드 0에서 `{"decision":"block","reason"}` JSON을 stdout으로 출력하여 거부하며, **`PreToolUse`** 이벤트에서만 적용됩니다(goose ≥ v1.37.0에서 제공됨) — 셸 도구뿐만 아니라 **위임된 서브에이전트 내부에서도** 실행되므로 단일 충분한 거부 지점입니다. 다른 훅 오류는 **허용 방향으로 실패**합니다. Goose에는 **`Stop` 이벤트가 없으므로** `require-*-before-stop` 내장 정책은 적용되지 않습니다(Hermes와 동일). 도구 이름은 `GOOSE_TOOL_MAP`을 통해 정규화됩니다(`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite` 등). 경로 키는 `GOOSE_TOOL_INPUT_MAP`을 통해 정규화됩니다(`path`/`source` → `file_path`). Goose는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.local/share/goose/sessions/sessions.db`의 SQLite 세션을 읽습니다(각 `sessions` 행에 실제 `working_dir`가 있으므로 Devin처럼 프로젝트 cwd별로 세션이 그룹화됩니다. `--no-session` 임시 실행은 필터링됩니다). +- **`policies-config.json`** — failproofai가 어떤 정책을 어떤 파라미터로 평가할지 지시합니다(모든 에이전트 CLI에서 공유됨) + +특정 에이전트를 지정하려면 `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`를 전달합니다(공백으로 구분하거나 반복 사용하여 일부를 선택): ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +217,28 @@ failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli hermes --scope user -failproofai policies --install --cli claude codex copilot cursor opencode pi +failproofai policies --install --cli openclaw --scope user +failproofai policies --install --cli factory --scope project +failproofai policies --install --cli devin --scope project +failproofai policies --install --cli antigravity --scope project +failproofai policies --install --cli goose --scope project +failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -`--cli`를 생략하면 `failproofai`가 설치된 에이전트 CLI를 자동으로 감지합니다(`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`): +`--cli`를 생략하면 `failproofai`가 설치된 에이전트 CLI를 자동으로 감지합니다(`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): -- **CLI 1개 감지** — 확인 없이 해당 CLI를 자동 선택합니다. -- **여러 CLI 감지** (대화형 터미널) — 화살표 키 단일 선택 프롬프트를 표시합니다. `Detected (N)` 섹션(전체 감지 CLI에 대한 `Install for all N detected` 통합 행 + 각 감지된 CLI 개별 항목)과, 사전 설치를 위한 모든 미감지 지원 CLI를 나열하는 `Not installed (M) · install hooks ahead of time` 섹션으로 구성됩니다(↑↓로 이동, Enter로 선택, ^C로 종료). 제거 흐름은 Detected 섹션만 표시합니다. -- **여러 CLI 감지** (비대화형 실행, TTY 없음, CI 등) — 확인 없이 감지된 모든 CLI에 설치합니다. -- **감지 없음** — `claude`로 폴백하며, PATH에서 에이전트 바이너리를 찾을 수 없다는 경고를 표시합니다. 훅 명령은 그래도 기록되므로 설치 즉시 활성화됩니다. +- **하나의 CLI 감지** — 프롬프트 없이 해당 CLI를 자동 선택합니다. +- **여러 CLI 감지**, 대화형 터미널 — 화살표 키 단일 선택 프롬프트를 표시합니다. `Detected (N)` 섹션(감지된 각 CLI와 `Install for all N detected` 집계 행 포함)과 `Not installed (M) · install hooks ahead of time` 섹션(지원되는 미감지 CLI를 미리 설치 옵션으로 나열)으로 구성됩니다(↑↓로 이동, Enter로 선택, ^C로 종료). 삭제 흐름에는 Detected 섹션만 표시됩니다. +- **여러 CLI 감지**, 비대화형 실행(CI, TTY 없음) — 프롬프트 없이 감지된 모든 CLI에 설치합니다. +- **감지 없음** — `claude`로 폴백하며, PATH에서 에이전트 바이너리를 찾을 수 없다는 경고를 표시합니다. 훅 명령은 그래도 작성되므로 에이전트를 설치하는 즉시 활성화됩니다. -`policies-config.json`은 언제든지 직접 편집할 수 있으며, 변경 사항은 재시작 없이 다음 훅 이벤트부터 즉시 적용됩니다. +`policies-config.json`은 언제든지 직접 편집할 수 있으며, 다음 훅 이벤트부터 재시작 없이 즉시 변경 사항이 적용됩니다. --- ## 예시: 팀 기본값이 포함된 프로젝트 수준 설정 -`.failproofai/policies-config.json`을 저장소에 커밋하세요: +`.failproofai/policies-config.json`을 저장소에 커밋합니다: ```json { @@ -245,4 +257,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi } ``` -각 개발자는 팀원에게 영향을 주지 않고 개인 오버라이드를 위해 `.failproofai/policies-config.local.json`(gitignore 처리)을 생성할 수 있습니다. \ No newline at end of file +각 개발자는 팀원에게 영향을 주지 않고 개인 오버라이드를 위해 `.failproofai/policies-config.local.json`(gitignore 처리됨)을 만들 수 있습니다. \ No newline at end of file diff --git a/docs/ko/custom-policies.mdx b/docs/ko/custom-policies.mdx index f481abbe..14ee0678 100644 --- a/docs/ko/custom-policies.mdx +++ b/docs/ko/custom-policies.mdx @@ -1,14 +1,14 @@ --- title: 커스텀 정책 -description: "JavaScript로 직접 정책을 작성하세요 - 컨벤션 적용, 드리프트 방지, 실패 감지, 외부 시스템 연동" +description: "JavaScript로 직접 정책을 작성하세요 - 컨벤션 강제 적용, 드리프트 방지, 실패 감지, 외부 시스템 연동" icon: code --- -커스텀 정책을 사용하면 에이전트 동작에 관한 규칙을 직접 작성할 수 있습니다. 프로젝트 컨벤션 적용, 드리프트 방지, 위험 작업 차단, 멈춘 에이전트 감지, Slack이나 승인 워크플로 연동 등 다양하게 활용할 수 있습니다. 내장 정책과 동일한 훅 이벤트 시스템과 `allow`, `deny`, `instruct` 결정 방식을 사용합니다. +커스텀 정책을 사용하면 에이전트 동작에 대한 모든 규칙을 직접 작성할 수 있습니다. 프로젝트 컨벤션 강제 적용, 드리프트 방지, 위험한 작업 차단, 멈춘 에이전트 감지, Slack 연동, 승인 워크플로우 등 다양한 용도로 활용할 수 있습니다. 내장 정책과 동일한 훅 이벤트 시스템 및 `allow`, `deny`, `instruct` 결정 방식을 사용합니다. --- -## 빠른 예시 +## 빠른 예제 ```js // my-policies.js @@ -29,7 +29,7 @@ customPolicies.add({ }); ``` -설치: +설치하기: ```bash failproofai policies --install --custom ./my-policies.js @@ -41,26 +41,26 @@ failproofai policies --install --custom ./my-policies.js ### 방법 1: 컨벤션 기반 (권장) -`.failproofai/policies/` 디렉터리에 `*policies.{js,mjs,ts}` 파일을 넣으면 자동으로 불러옵니다 — 별도 플래그나 설정 변경이 필요 없습니다. git hooks처럼 파일만 넣으면 바로 동작합니다. +`.failproofai/policies/` 디렉터리에 `*policies.{js,mjs,ts}` 파일을 넣으면 자동으로 로드됩니다. 별도 플래그나 설정 변경이 필요 없습니다. git hooks처럼 파일을 놓기만 하면 바로 동작합니다. ``` -# 프로젝트 레벨 — git에 커밋하여 팀과 공유 +# 프로젝트 레벨 — git에 커밋되어 팀과 공유됨 .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# 사용자 레벨 — 개인 설정, 모든 프로젝트에 적용 +# 사용자 레벨 — 개인용, 모든 프로젝트에 적용됨 ~/.failproofai/policies/my-policies.mjs ``` **동작 방식:** -- 프로젝트 디렉터리와 사용자 디렉터리를 모두 스캔합니다 (합집합 — 첫 번째 스코프 우선이 아님) -- 각 디렉터리 내에서 파일은 알파벳 순서로 불러옵니다. 순서를 제어하려면 `01-`, `02-` 접두사를 사용하세요 -- `*policies.{js,mjs,ts}` 패턴에 맞는 파일만 불러오며, 나머지 파일은 무시됩니다 -- 각 파일은 독립적으로 불러옵니다 (파일 단위 fail-open) -- 명시적 `--custom` 옵션 및 내장 정책과 함께 동작합니다 +- 프로젝트 디렉터리와 사용자 디렉터리 모두 스캔됩니다 (합집합 — 첫 번째 스코프 우선이 아님) +- 각 디렉터리 내 파일은 알파벳 순서로 로드됩니다. 순서를 제어하려면 `01-`, `02-` 등의 접두사를 사용하세요 +- `*policies.{js,mjs,ts}` 패턴에 매칭되는 파일만 로드되며, 다른 파일은 무시됩니다 +- 각 파일은 독립적으로 로드됩니다 (파일별 fail-open) +- 명시적 `--custom` 및 내장 정책과 함께 동작합니다 -컨벤션 정책은 조직의 품질 기준을 세우는 가장 쉬운 방법입니다. `.failproofai/policies/`를 git에 커밋하면 모든 팀원이 별도 설정 없이 동일한 규칙을 자동으로 적용받습니다. 새로운 실패 패턴을 발견할 때마다 정책을 추가하고 푸시하세요. 시간이 지날수록 기여가 쌓이며 살아있는 품질 기준이 만들어집니다. +컨벤션 정책은 조직의 품질 기준을 구축하는 가장 쉬운 방법입니다. `.failproofai/policies/`를 git에 커밋하면 모든 팀원이 동일한 규칙을 자동으로 적용받습니다. 개발자별 별도 설정이 필요 없습니다. 팀이 새로운 실패 패턴을 발견할 때마다 정책을 추가하고 푸시하면, 시간이 지날수록 매 기여와 함께 발전하는 살아있는 품질 기준이 됩니다. ### 방법 2: 명시적 파일 경로 @@ -69,20 +69,25 @@ failproofai policies --install --custom ./my-policies.js # 커스텀 정책 파일과 함께 설치 failproofai policies --install --custom ./my-policies.js -# 정책 파일 경로 교체 +# 커스텀 정책 경로 교체 failproofai policies --install --custom ./new-policies.js -# 설정에서 커스텀 정책 경로 제거 +# 여러 명시적 파일 설정 (플래그 순서대로 로드됨) +failproofai policies --install --custom ./security.js --custom ./workflow.js + +# 설정에서 모든 명시적 커스텀 정책 경로 제거 failproofai policies --uninstall --custom ``` -변환된 절대 경로는 `policies-config.json`의 `customPoliciesPath`에 저장됩니다. 파일은 매 훅 이벤트마다 새로 불러오며 이벤트 간 캐싱은 없습니다. +해석된 절대 경로는 `policies-config.json`의 `customPoliciesPaths`에 저장됩니다. `--custom`을 반복하여 여러 파일을 설정할 수 있습니다. 레거시 `customPoliciesPath` 필드를 사용하는 기존 설정도 계속 동작합니다. 파일은 매 훅 이벤트마다 새로 로드되며, 이벤트 간 캐싱은 없습니다. + +등록된 각 정책은 대시보드에 개별 토글로 표시됩니다. 정책을 비활성화하면 소스 한정 ID가 `disabledCustomPolicies`에 기록되며, 해당 파일과 다른 정책들은 계속 로드되지만 비활성화된 정책은 이벤트 매칭 전에 제외됩니다. 여러 파일에 걸쳐 중복된 정책 이름은 각각 독립적인 토글을 가집니다. -### 두 방법을 함께 사용하기 +### 두 방법 함께 사용하기 -컨벤션 정책과 명시적 `--custom` 파일은 공존할 수 있습니다. 불러오는 순서: +컨벤션 정책과 명시적 `--custom` 파일은 함께 사용할 수 있습니다. 로드 순서: -1. 명시적 `customPoliciesPath` 파일 (설정된 경우) +1. 명시적 `customPoliciesPaths` 파일 (설정된 순서대로) 2. 프로젝트 컨벤션 파일 (`{cwd}/.failproofai/policies/`, 알파벳 순) 3. 사용자 컨벤션 파일 (`~/.failproofai/policies/`, 알파벳 순) @@ -90,7 +95,7 @@ failproofai policies --uninstall --custom ## API -### 가져오기 +### 임포트 ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -98,45 +103,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -정책을 등록합니다. 같은 파일 내에 여러 정책을 등록하려면 원하는 만큼 호출하세요. +정책을 등록합니다. 같은 파일에 여러 정책을 등록하려면 필요한 만큼 호출하세요. ```ts customPolicies.add({ name: string; // 필수 - 고유 식별자 description?: string; // `failproofai policies` 출력에 표시됨 - match?: { events?: HookEventType[] }; // 이벤트 타입으로 필터링; 생략하면 모두 매칭 + match?: { events?: HookEventType[] }; // 이벤트 타입으로 필터링; 생략 시 모든 이벤트에 매칭 fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### 결정 헬퍼 함수 +### 결정 헬퍼 | 함수 | 효과 | 사용 시점 | |----------|--------|----------| -| `allow()` | 조용히 작업을 허용 | 동작이 안전하고 별도 메시지가 필요 없을 때 | -| `deny(message)` | 작업을 차단 | 에이전트가 이 작업을 수행하면 안 될 때 | -| `instruct(message)` | 차단 없이 컨텍스트 추가 | 에이전트가 올바른 방향을 유지하도록 추가 정보를 줄 때 | +| `allow()` | 작업을 조용히 허용 | 동작이 안전하고 메시지가 필요 없을 때 | +| `deny(message)` | 작업 차단 | 에이전트가 이 동작을 수행하면 안 될 때 | +| `instruct(message)` | 차단 없이 컨텍스트 추가 | 에이전트가 올바른 방향을 유지하도록 추가 정보를 제공할 때 | -`deny(message)` - 메시지는 `"Blocked by failproofai:"` 접두사와 함께 Claude에 표시됩니다. 하나의 `deny`가 발생하면 이후 평가는 모두 생략됩니다. +`deny(message)` - 메시지는 `"Blocked by failproofai:"` 접두사와 함께 Claude에게 표시됩니다. 단 하나의 `deny`가 이후 모든 평가를 중단시킵니다. `instruct(message)` - 메시지는 현재 도구 호출에 대한 Claude의 컨텍스트에 추가됩니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다. -`policyParams`의 `hint` 필드를 추가하면 코드 변경 없이 `deny`나 `instruct` 메시지에 추가 안내를 붙일 수 있습니다. 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 정책 모두에서 동작합니다. 자세한 내용은 [설정 → hint](/ko/configuration#hint-cross-cutting)를 참고하세요. +`deny` 또는 `instruct` 메시지에 추가 안내를 덧붙이려면 `policyParams`의 `hint` 필드를 사용하세요. 코드 수정 없이 적용됩니다. 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 정책 모두에서 동작합니다. 자세한 내용은 [Configuration → hint](/ko/configuration#hint-cross-cutting)를 참조하세요. ### 정보성 allow 메시지 -`allow(message)`는 작업을 허용하면서 **동시에** Claude에 정보성 메시지를 전송합니다. 메시지는 훅 핸들러의 stdout 응답에서 `additionalContext`로 전달됩니다 — `instruct`와 동일한 메커니즘이지만 의미가 다릅니다. 경고가 아닌 상태 업데이트입니다. +`allow(message)`는 작업을 허용하면서 **동시에** Claude에게 정보성 메시지를 전송합니다. 메시지는 훅 핸들러의 stdout 응답에서 `additionalContext`로 전달됩니다. `instruct`와 동일한 메커니즘을 사용하지만 의미적으로 다릅니다. 경고가 아닌 상태 업데이트입니다. | 함수 | 효과 | 사용 시점 | |----------|--------|----------| -| `allow(message)` | 허용하면서 Claude에 컨텍스트 전송 | 검사 통과를 확인하거나, 검사를 건너뛴 이유를 설명할 때 | +| `allow(message)` | 허용하면서 Claude에게 컨텍스트 전송 | 검사가 통과됐음을 확인하거나, 검사를 건너뛴 이유를 설명할 때 | 사용 사례: -- **상태 확인:** `allow("All CI checks passed.")` — 모든 것이 정상임을 Claude에 알림 -- **Fail-open 설명:** `allow("GitHub CLI not installed, skipping CI check.")` — 검사를 건너뛴 이유를 Claude에 알려 완전한 컨텍스트 제공 -- **메시지 누적:** 여러 정책이 각각 `allow(message)`를 반환하면, 모든 메시지가 줄바꿈으로 합쳐져 함께 전달됩니다 +- **상태 확인:** `allow("All CI checks passed.")` — Claude에게 모든 것이 정상임을 알림 +- **Fail-open 설명:** `allow("GitHub CLI not installed, skipping CI check.")` — 검사를 건너뛴 이유를 Claude에게 알려 전체 컨텍스트를 제공 +- **메시지 누적:** 여러 정책이 각각 `allow(message)`를 반환하면, 모든 메시지가 줄바꿈으로 연결되어 함께 전달됨 ```js customPolicies.add({ @@ -146,7 +151,7 @@ customPolicies.add({ const cwd = ctx.session?.cwd; if (!cwd) return allow("No working directory, skipping branch check."); - // ... 브랜치 상태 확인 ... + // ... check branch status ... if (allPushed) { return allow("Branch is up to date with remote."); } @@ -162,7 +167,7 @@ customPolicies.add({ | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | | `toolName` | `string \| undefined` | 호출되는 도구 (예: `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | 도구의 입력 파라미터 | -| `payload` | `Record` | Claude Code에서 전달된 전체 원시 이벤트 페이로드 | +| `payload` | `Record` | Claude Code로부터의 전체 원시 이벤트 페이로드 | | `session` | `SessionMetadata \| undefined` | 세션 컨텍스트 (아래 참조) | ### `SessionMetadata` 필드 @@ -178,8 +183,8 @@ customPolicies.add({ | 이벤트 | 발생 시점 | `toolInput` 내용 | |-------|--------------|----------------------| | `PreToolUse` | Claude가 도구를 실행하기 전 | 도구의 입력 (예: Bash의 경우 `{ command: "..." }`) | -| `PostToolUse` | 도구 실행 완료 후 | 도구의 입력 + `tool_result` (출력) | -| `Notification` | Claude가 알림을 보낼 때 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - 훅은 항상 `allow()`를 반환해야 하며 알림을 차단할 수 없습니다 | +| `PostToolUse` | 도구가 완료된 후 | 도구의 입력 + `tool_result` (출력) | +| `Notification` | Claude가 알림을 보낼 때 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - 훅은 반드시 `allow()`를 반환해야 하며 알림을 차단할 수 없음 | | `Stop` | Claude 세션이 종료될 때 | 비어 있음 | --- @@ -188,20 +193,20 @@ customPolicies.add({ 정책은 다음 순서로 평가됩니다: -1. 내장 정책 (정의된 순서) -2. `customPoliciesPath`의 명시적 커스텀 정책 (`.add()` 호출 순서) +1. 내장 정책 (정의 순서대로) +2. `customPoliciesPath`의 명시적 커스텀 정책 (`.add()` 순서대로) 3. 프로젝트 `.failproofai/policies/`의 컨벤션 정책 (파일 알파벳 순, 파일 내 `.add()` 순서) 4. 사용자 `~/.failproofai/policies/`의 컨벤션 정책 (파일 알파벳 순, 파일 내 `.add()` 순서) -첫 번째 `deny`가 발생하면 이후 모든 정책 평가가 생략됩니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다. +첫 번째 `deny`가 이후 모든 정책 평가를 중단시킵니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다. --- ## 전이적 임포트 -커스텀 정책 파일은 상대 경로를 사용해 로컬 모듈을 임포트할 수 있습니다: +커스텀 정책 파일은 상대 경로를 사용하여 로컬 모듈을 임포트할 수 있습니다: ```js // my-policies.js @@ -218,43 +223,43 @@ customPolicies.add({ }); ``` -엔트리 파일에서 도달 가능한 모든 상대 임포트가 처리됩니다. 내부적으로 `from "failproofai"` 임포트를 실제 dist 경로로 재작성하고 ESM 호환성을 위해 임시 `.mjs` 파일을 생성하는 방식으로 구현됩니다. +엔트리 파일에서 도달 가능한 모든 상대 임포트가 해석됩니다. 이는 `from "failproofai"` 임포트를 실제 dist 경로로 재작성하고, ESM 호환성을 보장하기 위해 임시 `.mjs` 파일을 생성하는 방식으로 구현됩니다. --- ## 이벤트 타입 필터링 -`match.events`를 사용해 정책이 발동하는 시점을 제한할 수 있습니다: +`match.events`를 사용하여 정책이 발동되는 시점을 제한할 수 있습니다: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // 세션이 종료될 때만 발동 - // ctx.session.transcriptPath에 전체 세션 로그가 있습니다 + // 세션이 종료될 때만 발동됨 + // ctx.session.transcriptPath에 전체 세션 로그가 있음 return allow(); }, }); ``` -`match`를 완전히 생략하면 모든 이벤트 타입에서 발동합니다. +`match`를 완전히 생략하면 모든 이벤트 타입에 발동됩니다. --- -## 오류 처리 및 실패 동작 +## 에러 처리 및 실패 모드 -커스텀 정책은 **fail-open** 방식입니다. 오류가 발생해도 내장 정책을 차단하거나 훅 핸들러를 중단시키지 않습니다. +커스텀 정책은 **fail-open** 방식입니다. 에러가 발생해도 내장 정책을 차단하거나 훅 핸들러를 중단시키지 않습니다. | 실패 상황 | 동작 | |---------|----------| | `customPoliciesPath` 미설정 | 명시적 커스텀 정책이 실행되지 않음; 컨벤션 정책과 내장 정책은 정상 동작 | -| 파일을 찾을 수 없음 | `~/.failproofai/hook.log`에 경고 기록; 내장 정책은 계속 실행 | -| 문법/임포트 오류 (명시적) | `~/.failproofai/hook.log`에 오류 기록; 명시적 커스텀 정책 건너뜀 | -| 문법/임포트 오류 (컨벤션) | 오류 기록; 해당 파일 건너뜀, 다른 컨벤션 파일은 계속 불러옴 | -| 런타임에서 `fn` 예외 발생 | 오류 기록; 해당 훅은 `allow`로 처리; 다른 훅은 계속 실행 | -| `fn`이 10초 이상 소요 | 타임아웃 기록; `allow`로 처리 | -| 컨벤션 디렉터리 없음 | 컨벤션 정책 실행 없음; 오류 없음 | +| 파일을 찾을 수 없음 | `~/.failproofai/hook.log`에 경고 기록; 내장 정책은 계속 동작 | +| 구문/임포트 오류 (명시적) | `~/.failproofai/hook.log`에 오류 기록; 명시적 커스텀 정책 건너뜀 | +| 구문/임포트 오류 (컨벤션) | 오류 기록; 해당 파일 건너뜀, 다른 컨벤션 파일은 계속 로드 | +| `fn` 런타임 예외 | 오류 기록; 해당 훅은 `allow`로 처리; 다른 훅은 계속 실행 | +| `fn` 10초 초과 | 타임아웃 기록; `allow`로 처리 | +| 컨벤션 디렉터리 없음 | 컨벤션 정책 미실행; 오류 없음 | 커스텀 정책 오류를 디버깅하려면 로그 파일을 실시간으로 확인하세요: @@ -266,13 +271,13 @@ tail -f ~/.failproofai/hook.log --- -## 전체 예시: 여러 정책 +## 전체 예제: 여러 정책 ```js // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// 에이전트가 secrets/ 디렉터리에 쓰지 못하도록 방지 +// 에이전트가 secrets/ 디렉터리에 쓰는 것을 방지 customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -285,7 +290,7 @@ customPolicies.add({ }, }); -// 에이전트가 커밋 전에 테스트를 확인하도록 안내 +// 에이전트가 올바른 방향을 유지하도록: 커밋 전 테스트 확인 customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -321,33 +326,33 @@ export { customPolicies }; --- -## 예시 파일 +## 예제 파일 -`examples/` 디렉터리에는 바로 실행 가능한 정책 파일들이 포함되어 있습니다: +`examples/` 디렉터리에는 바로 실행 가능한 정책 파일이 포함되어 있습니다: | 파일 | 내용 | |------|----------| -| `examples/policies-basic.js` | 일반적인 에이전트 실패 패턴을 다루는 5가지 기본 정책 | +| `examples/policies-basic.js` | 일반적인 에이전트 실패 모드를 다루는 5가지 기본 정책 | | `examples/policies-advanced/index.js` | 고급 패턴: 전이적 임포트, 비동기 호출, 출력 스크러빙, 세션 종료 훅 | -| `examples/convention-policies/security-policies.mjs` | 컨벤션 기반 보안 정책 (.env 파일 쓰기 차단, git 히스토리 재작성 방지) | -| `examples/convention-policies/workflow-policies.mjs` | 컨벤션 기반 워크플로 정책 (테스트 알림, 파일 쓰기 감사) | +| `examples/convention-policies/security-policies.mjs` | 컨벤션 기반 보안 정책 (.env 쓰기 차단, git 히스토리 재작성 방지) | +| `examples/convention-policies/workflow-policies.mjs` | 컨벤션 기반 워크플로우 정책 (테스트 알림, 파일 쓰기 감사) | -### 명시적 파일 예시 사용 +### 명시적 파일 예제 사용 ```bash failproofai policies --install --custom ./examples/policies-basic.js ``` -### 컨벤션 기반 예시 사용 +### 컨벤션 기반 예제 사용 ```bash -# 프로젝트 레벨로 복사 +# 프로젝트 레벨에 복사 mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# 또는 사용자 레벨로 복사 +# 또는 사용자 레벨에 복사 mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -별도 설치 명령이 필요 없습니다 — 다음 훅 이벤트 시 파일이 자동으로 인식됩니다. \ No newline at end of file +별도의 설치 명령이 필요 없습니다. 다음 훅 이벤트 발생 시 파일이 자동으로 인식됩니다. \ No newline at end of file diff --git a/docs/ko/dashboard.mdx b/docs/ko/dashboard.mdx index 9de6785a..a899433d 100644 --- a/docs/ko/dashboard.mdx +++ b/docs/ko/dashboard.mdx @@ -1,10 +1,10 @@ --- title: 대시보드 -description: "에이전트 세션 모니터링, 도구 호출 검토 및 정책 관리" +description: "에이전트 세션 모니터링, 툴 호출 검토 및 정책 관리" icon: chart-line --- -failproofai 대시보드는 AI 에이전트 세션을 모니터링하고 정책을 관리하기 위한 로컬 웹 애플리케이션입니다. 자리를 비운 동안 에이전트가 무엇을 했는지 확인하세요. +failproofai 대시보드는 AI 에이전트 세션을 모니터링하고 정책을 관리하는 로컬 웹 애플리케이션입니다. 자리를 비운 동안 에이전트가 무엇을 했는지 확인해 보세요. --- @@ -16,7 +16,7 @@ failproofai `http://localhost:8020`에서 열립니다. -대시보드는 로컬 프로젝트, 세션 및 failproofai 구성 데이터를 파일 시스템에서 직접 읽어옵니다. 감사 알림이나 초대 등 인증이 필요한 선택적 기능은 해당 요청에 필요한 정보(이메일 주소 포함)를 원격 API로 전송합니다. +대시보드는 로컬 프로젝트, 세션, failproofai 구성 데이터를 파일 시스템에서 직접 읽습니다. 감사 알림 및 초대와 같은 선택적 인증 기능은 해당 요청에 필요한 정보(이메일 주소 포함)를 원격 API로 전송합니다. --- @@ -24,67 +24,69 @@ failproofai ### 프로젝트 -머신에서 발견된 모든 Claude Code, OpenAI Codex, GitHub Copilot CLI _(베타)_, Cursor Agent _(베타)_, OpenCode _(베타)_, Pi _(베타)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, Goose 프로젝트를 나열합니다. Claude 프로젝트는 `~/.claude/projects/`(또는 `CLAUDE_PROJECTS_PATH`에 설정된 경로)에서 탐색되며, Codex 프로젝트는 `~/.codex/sessions///
/*.jsonl`의 모든 트랜스크립트를 스캔하여 각 세션의 첫 번째 레코드에 기록된 `cwd`로 그룹화해 탐색됩니다. Copilot CLI 프로젝트는 각 `~/.copilot/session-state//workspace.yaml`((`COPILOT_HOME`으로 설정 가능))을 스캔하여 `cwd` 필드로 그룹화해 탐색됩니다. Cursor Agent 프로젝트는 `~/.cursor/agent-sessions//`(`CURSOR_HOME`으로 설정 가능, `conversations/` 및 `sessions/`를 폴백으로 탐색) 아래의 세션별 메타데이터를 스캔하여 `meta.json` / `session.json` / `workspace.yaml`의 `cwd` 스칼라를 찾아 탐색됩니다. OpenCode 프로젝트는 `opencode db --format json`을 통해 `~/.local/share/opencode/opencode.db`의 SQLite DB를 쿼리하여(`session` 및 `project` 테이블을 읽어 `project_id`로 그룹화) 탐색됩니다. Pi 프로젝트는 `~/.pi/agent/sessions//_.jsonl`(`PI_SESSIONS_DIR`로 설정 가능) 아래의 세션별 JSONL 트랜스크립트를 스캔하여 각 세션의 첫 번째 레코드에서 `cwd`를 가져와 탐색됩니다. Hermes 게이트웨이 세션은 `~/.hermes/state.db`(`HERMES_DB_PATH`로 설정 가능)의 SQLite 스토어에서 직접 읽어 `source`(Slack/Telegram/cli/cron — 게이트웨이 세션에는 cwd 없음)로 `hermes-` 프로젝트로 그룹화됩니다. OpenClaw 게이트웨이 세션은 `~/.openclaw/agents//sessions/*.jsonl`에서 읽어 `openclaw-` 프로젝트로 그룹화됩니다(마찬가지로 cwd 없음). Factory Droid 프로젝트는 `~/.factory/sessions//*.jsonl`의 JSONL 트랜스크립트에서 탐색되어 cwd로 그룹화됩니다. Devin 프로젝트는 `~/.local/share/devin/cli/sessions.db`의 SQLite DB에서(`working_directory`로 그룹화), Antigravity 프로젝트는 `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`의 JSONL 트랜스크립트에서 cwd로 그룹화되어 탐색됩니다. Goose 프로젝트는 `~/.local/share/goose/sessions/sessions.db`의 SQLite DB에서 각 세션의 `working_dir`로 그룹화되어 탐색됩니다. 여러 CLI에서 사용된 프로젝트는 일치하는 모든 배지를 포함한 단일 행으로 표시됩니다. 표 위의 **CLI** 드롭다운을 사용하여 특정 에이전트 CLI로 필터링할 수 있으며, URL은 선택 항목을 `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`로 보존합니다. +머신에서 발견된 모든 Claude Code, OpenAI Codex, GitHub Copilot CLI _(베타)_, Cursor Agent _(베타)_, OpenCode _(베타)_, Pi _(베타)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, Goose 프로젝트를 나열합니다. Claude 프로젝트는 `~/.claude/projects/`(또는 `CLAUDE_PROJECTS_PATH`로 지정된 경로)에서 검색됩니다. Codex 프로젝트는 `~/.codex/sessions///
/*.jsonl` 아래의 모든 트랜스크립트를 스캔하고 각 세션 첫 번째 레코드에 기록된 `cwd`로 그룹화합니다. Copilot CLI 프로젝트는 각 `~/.copilot/session-state//workspace.yaml`(`COPILOT_HOME`으로 구성 가능)을 스캔하고 `cwd` 필드로 그룹화합니다. Cursor Agent 프로젝트는 `~/.cursor/agent-sessions//`(`CURSOR_HOME`으로 구성 가능, `conversations/` 및 `sessions/`를 폴백으로 탐색) 아래의 세션별 메타데이터를 스캔하여 `meta.json` / `session.json` / `workspace.yaml`의 `cwd` 스칼라로 검색됩니다. OpenCode 프로젝트는 `opencode db --format json`을 통해 `~/.local/share/opencode/opencode.db`의 SQLite DB를 쿼리하여 검색됩니다(`session` 및 `project` 테이블을 읽고 `project_id`로 그룹화). Pi 프로젝트는 `~/.pi/agent/sessions//_.jsonl`(`PI_SESSIONS_DIR`으로 구성 가능) 아래의 세션별 JSONL 트랜스크립트를 스캔하고 각 세션 첫 번째 레코드에서 `cwd`를 추출합니다. Hermes 게이트웨이 세션은 모든 프로필의 SQLite 스토어(단일 데이터베이스의 경우 `~/.hermes/state.db` 및 `~/.hermes/profiles//state.db`, `HERMES_HOME` 또는 `HERMES_DB_PATH`로 재정의 가능)에서 직접 읽고, 프로필 및 `source`(Slack/Telegram/cli/cron — 게이트웨이 세션에는 cwd가 없음)로 `hermes--` 프로젝트로 그룹화합니다. OpenClaw 게이트웨이 세션은 `~/.openclaw/agents//sessions/*.jsonl`에서 읽고 에이전트 및 채널별로 `openclaw--` 프로젝트로 그룹화됩니다(cwd 없음). Factory Droid 프로젝트는 `~/.factory/sessions//*.jsonl`의 JSONL 트랜스크립트에서 검색되고 cwd로 그룹화됩니다. Devin 프로젝트는 `~/.local/share/devin/cli/sessions.db`의 SQLite DB에서 검색됩니다(각 세션의 `working_directory`로 그룹화). Antigravity 프로젝트는 `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`의 JSONL 트랜스크립트에서 cwd로 그룹화됩니다. Goose 프로젝트는 `~/.local/share/goose/sessions/sessions.db`의 SQLite DB에서 검색됩니다(각 세션의 `working_dir`로 그룹화). 여러 CLI에서 사용된 프로젝트는 일치하는 모든 배지가 표시된 단일 행으로 렌더링됩니다. 테이블 위의 **CLI** 드롭다운을 사용하여 특정 에이전트 CLI로 필터링하세요. URL은 선택 항목을 `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`로 유지합니다. -각 프로젝트에는 다음이 표시됩니다: +Hermes와 OpenClaw는 사용자 범위이며 그룹화할 작업 디렉토리가 없으므로 **접을 수 있는 폴더 트리**로 렌더링됩니다. 최상위에 프로필(또는 에이전트), 그 아래에 채널이 표시됩니다. cwd 기반의 모든 CLI는 평면 행으로 유지됩니다. 폴더 행은 하위 항목의 세션 수와 가장 최근 활동을 합산하며, 접힌 폴더 상태는 방문 간에 기억되고 키워드 검색 시 일치하는 항목이 펼쳐집니다. + +각 프로젝트에 표시되는 내용: - 프로젝트 이름 (폴더 경로에서 파생) -- CLI 배지 — `Claude Code`(주황), `OpenAI Codex`(보라), `GitHub Copilot`(파랑), `Cursor Agent`(에메랄드), `OpenCode`(호박색), `Pi`(분홍), `Hermes`(인디고) 중 하나 이상 +- CLI 배지 — `Claude Code` (주황색), `OpenAI Codex` (보라색), `GitHub Copilot` (파란색), `Cursor Agent` (에메랄드색), `OpenCode` (앰버색), `Pi` (분홍색), 그리고/또는 `Hermes` (인디고색) - 가장 최근 세션 활동 날짜 -프로젝트를 클릭하면 해당 세션을 확인할 수 있습니다. +프로젝트를 클릭하면 해당 세션이 표시됩니다. ### 세션 -프로젝트 내 모든 세션을 나열합니다. 각 세션에는 다음이 표시됩니다: +프로젝트 내 모든 세션을 나열합니다. 각 세션에 표시되는 내용: - 세션 ID - 시작 및 종료 타임스탬프 -- 도구 호출 수 -- 훅 활동 횟수 (실행된 정책 수) +- 툴 호출 횟수 +- 훅 활동 횟수 (실행된 정책) -날짜 범위 필터와 세션 ID 검색을 사용하여 목록을 좁힐 수 있습니다. 세션은 페이지로 나뉩니다. +날짜 범위 필터와 세션 ID 검색을 사용하여 목록을 좁힐 수 있습니다. 세션은 페이지네이션됩니다. 세션을 클릭하면 세션 뷰어가 열립니다. ### 세션 뷰어 -세션 뷰어는 자율 에이전트의 핵심 질문에 답합니다: 에이전트가 무엇을 했으며, 올바른 방향을 유지했는가? 헤더 옆의 CLI 배지는 해당 세션이 Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, Goose 트랜스크립트 중 무엇인지 나타냅니다. 세션에서 발생한 모든 일의 타임라인을 표시합니다: +세션 뷰어는 자율 에이전트의 핵심 질문에 답합니다: 에이전트가 무엇을 했고, 올바른 방향으로 유지됐는가? 헤더 옆의 CLI 배지는 해당 세션이 Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, Goose 트랜스크립트 중 어느 것인지 나타냅니다. 세션에서 발생한 모든 일의 타임라인을 보여줍니다: - **메시지** - Claude의 텍스트 응답 및 사용자 프롬프트 -- **도구 호출** - Claude가 호출한 모든 도구와 입력 및 출력 -- **정책 활동** - 각 도구 호출에 대해 어떤 정책이 실행되었고 어떤 결정을 반환했는지 +- **툴 호출** - Claude가 호출한 모든 툴과 입력 및 출력 +- **정책 활동** - 각 툴 호출에 대해 어떤 정책이 실행되었고 어떤 결정을 반환했는지 -상단의 통계 바에는 세션 지속 시간, 총 도구 호출 수, 훅 결정 요약(allow / deny / instruct 횟수)이 표시됩니다. +상단의 통계 바에는 세션 지속 시간, 총 툴 호출 수, 훅 결정 요약(allow / deny / instruct 횟수)이 표시됩니다. -**Download Logs** 버튼을 클릭하면 세션을 내보낼 수 있습니다. Claude Code, Codex, Copilot, Cursor, Pi 세션의 경우 원본 디스크 상의 JSONL 트랜스크립트를 바이트 단위로 그대로 가져오며, OpenCode(세션이 디스크가 아닌 SQLite에 저장됨)의 경우 기본 `session` / `messages` / `parts` 테이블을 미러링한 JSON 문서를 가져옵니다. +**Download Logs** 버튼을 클릭하면 세션을 내보낼 수 있습니다. Claude Code, Codex, Copilot, Cursor, Pi 세션의 경우 디스크에 저장된 원본 JSONL 트랜스크립트를 바이트 단위 그대로 가져오며, OpenCode(세션이 디스크가 아닌 SQLite에 저장됨)의 경우 기본 `session` / `messages` / `parts` 테이블을 미러링한 JSON 문서를 가져옵니다. ### 감사 -과거 세션에서 에이전트가 실제로 어떻게 행동했는지를 개성 있게 보고합니다. `failproofai audit` CLI와 동일한 스캔을 실행하지만, 전체 화면 공유 가능한 포스터 + 접힌 부분 아래의 네 가지 섹션으로 렌더링합니다: +과거 세션 전반에 걸쳐 에이전트가 실제로 어떻게 동작했는지에 대한 개성 있는 보고서입니다. `failproofai audit` CLI와 동일한 스캔을 실행하지만 단일 화면의 공유 가능한 포스터 + 화면 아래 네 개의 섹션으로 렌더링합니다: -1. **포스터** — 첫 번째 뷰포트를 채웁니다. failproof_ai 워드마크 + 감사 레이블 · 아키타입 인덱스(`№ NN of 08`) + 감사 날짜 · 수치 점수(0–100) + 백분위 순위 필(`top 15%`) · 아키타입 이름(`the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost` 중 하나) + 3개 키워드 스트립 · `// only N% of agents are this archetype` 희귀도 라인 · 8×8 픽셀 시길 타일 · `audit yours → failproof.ai` 푸터를 포함하는 독립형 PNG 캡처 영역. 세 개의 공유 버튼이 캡처 상자 바로 바깥에 위치합니다: `post your archetype`(X 인텐트), `share on linkedin`, `download poster`. 캡처는 `html-to-image`를 통해 실행되므로 PNG가 화면 렌더링과 픽셀 단위로 일치합니다(대시 테두리, SVG 로고 마스크, 그라디언트, 글꼴 메트릭 모두 보존). -2. **강점** — 에이전트가 이미 잘 하고 있는 행동의 차분한 ✓ 행 목록으로, 라이브 감사 데이터(깨끗한 도구 호출 비율, main에 직접 푸시 없음, 자격 증명 유출 없음, 재시도 폭풍 없음)에서 도출됩니다. 관련 정책이 감사 기간 동안 깨끗한 기록을 가진 경우에만 표시됩니다. -3. **특이점** — 심각도 순으로 순위가 매겨진 누락된 항목 표: `when · what slipped + the policy that would've caught it · severity pill · seen`, 재발 횟수는 `new`(1회), `N× seen`(2–9회), `recurring`(10회 이상)으로 표시됩니다. -4. **개선 방법** — 처방된 정책별 한 행씩의 차분한 행 목록: 흰색으로 정책 이름, 한 줄 설명, 오른쪽에 설치 명령 + 복사 버튼. 섹션 헤더에는 `enable all N → projected · `(모든 수정 사항 적용 시 도달할 점수)가 표시되며, `[install all]` 버튼은 모든 처방된 정책에 대한 `failproofai policy add a b c …` 명령을 복사합니다. -5. **더 나은 상태로 돌아오기** — 나란히 배치된 두 개의 카드. 왼쪽: 알림 설정(`3d` / `7d` / `14d` / `30d` 주기 선택기; 인증 후 `/api/auth/reminder`를 통해 유지). 오른쪽: failproof 혜택 잠금 해제 — `invite a friend`는 쉼표/공백/줄바꿈으로 구분된 친구 이메일 목록(전송당 최대 10개)을 받는 모달을 열고, `/api/audit/invite`에 POST하여 api-server의 `POST /v0/invite`로 전달합니다. api-server는 `invite@failproof.ai`에서 수신자마다 한 통의 이메일을 보내며 발신자를 참조하고 `Reply-To`를 설정하므로, 수신자는 누가 초대했는지 알 수 있고 발신자는 받은 편지함에 사본을 받습니다. 익명 사용자는 초대가 발송되기 전에 발신자 이메일을 확인하기 위해 먼저 `AuthDialog`로 이동됩니다. 권한/혜택 이행은 추후 예정입니다. +1. **포스터** — 첫 번째 뷰포트를 채웁니다. failproof_ai 워드마크 + 감사 레이블 · 아키타입 인덱스 (`№ NN of 08`) + 감사 날짜 · 수치 점수 (0–100) + 백분위 순위 필 (`top 15%`) · 아키타입 이름 (`the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost` 중 하나) + 3키워드 스트립 · `// only N% of agents are this archetype` 희귀도 라인 · 8×8 픽셀 시길 타일 · `audit yours → failproof.ai` 푸터가 포함된 독립형 PNG 캡처 영역. 세 개의 공유 버튼이 캡처 영역 바로 외부에 위치합니다: `post your archetype` (X 인텐트), `share on linkedin`, `download poster`. 캡처는 `html-to-image`를 통해 실행되어 PNG가 화면 렌더와 픽셀 단위로 일치합니다(점선 테두리, SVG 로고 마스크, 그라디언트, 폰트 메트릭 — 모두 보존). +2. **강점** — 라이브 감사 데이터에서 파생된, 에이전트가 이미 올바르게 수행하는 동작의 차분한 ✓ 행 목록(깨끗한 툴 호출 비율, main에 직접 푸시 없음, 자격 증명 누출 없음, 재시도 폭풍 없음) — 감사 기간 동안 해당 정책이 깨끗한 기록을 유지할 때만 표시됩니다. +3. **특이 사항** — 누락된 항목의 표, 심각도 순으로 정렬: `when · what slipped + the policy that would've caught it · severity pill · seen`. 재발 횟수는 `new` (한 번), `N× seen` (2–9회), `recurring` (10회 이상)으로 표시됩니다. +4. **개선 방법** — 차분한 행 목록, 처방된 정책 하나당 하나씩: 흰색 정책 이름, 한 줄 설명, 오른쪽에 설치 명령 + 복사 버튼. 섹션 헤더에는 `enable all N → projected · `(모든 수정 사항 적용 시 달성 가능한 점수)가 표시되고, `[install all]` 버튼은 모든 처방된 정책에 대한 `failproofai policy add a b c …` 명령을 복사합니다. +5. **더 나은 상태로 돌아오기** — 두 개의 나란히 배치된 카드. 왼쪽: 알림 설정 (`3d` / `7d` / `14d` / `30d` 주기 선택기; 인증 후 `/api/auth/reminder`를 통해 유지). 오른쪽: failproof 혜택 잠금 해제 — `invite a friend`를 클릭하면 쉼표/공백/줄바꿈으로 구분된 친구 이메일 목록(최대 10개)을 입력하는 모달이 열리며, `/api/audit/invite`로 POST 요청을 보냅니다. 이는 api-server의 `POST /v0/invite`로 전달됩니다. api-server는 `invite@failproof.ai`에서 수신자별로 하나의 이메일을 발송하며, 발신자는 Cc에 포함되고 `Reply-To`가 설정되어 수신자는 초대한 사람을 알 수 있고 발신자는 받은 편지함에서 사본을 받습니다. 익명 사용자는 초대가 발송되기 전에 발신자의 이메일을 확인하기 위해 먼저 `AuthDialog`로 라우팅됩니다. 자격 부여 / 혜택 이행은 후속 작업입니다. -`failproofai audit` 런타임에 의해 구동됩니다 — 기본 스캔 엔진, 지원 플래그, 트랜스크립트별 캐시 불변성에 대한 자세한 내용은 [감사 CLI](/ko/cli/audit)를 참조하세요. 대시보드는 최신 결과를 `~/.failproofai/audit-dashboard.json`(모드 `0600`, 단일 슬롯, 새 실행 시 덮어쓰기)에 캐시하므로 재방문 시 즉시 표시됩니다. **트랜스크립트별 캐시와 전체 결과 캐시 모두 7일보다 오래된 경우 읽기 시 거부됩니다.** 따라서 대시보드가 일주일 된 결과를 자동으로 제공하지 않습니다 — TTL이 지나면 `/audit`는 빈 상태로 폴백하여 새 실행을 요청합니다. 보고서 하단의 `[ re-audit now ]`를 클릭하면 `noCache: true`로 `/api/audit/run`에 POST합니다 — 재감사는 트랜스크립트별 캐시를 우회하고 캐시된 결과를 자동으로 반환하는 대신 처음부터 모든 트랜스크립트를 다시 스캔합니다 — 대시보드는 실행이 완료될 때까지 1Hz로 `/api/audit/status`를 폴링합니다. 실행 중에는 경과 타이머가 포함된 분홍색 진행 표시줄이 뷰포트 상단에 고정되며, 성공 시 새 결과가 제자리에 교체됩니다(전체 페이지 재로드 없음; 재감사 실패 시 이전 보고서가 유지됨). 실패 시 표시줄이 빨간색으로 변하며 `RerunError.kind`(`timeout` / `network` / `post_failed`)에 따른 복사 메시지가 표시됩니다. 빈 상태(캐시 없음 또는 만료됨)와 세션 없음 상태(캐시는 있지만 스캔에서 트랜스크립트를 찾지 못함)는 별도로 표시됩니다. +`failproofai audit` 런타임에 의해 구동됩니다 — 기본 스캔 엔진, 지원 플래그, 트랜스크립트별 캐시 불변성에 대해서는 [Audit CLI](/ko/cli/audit)를 참조하세요. 대시보드는 최신 결과를 `~/.failproofai/audit-dashboard.json`(모드 `0600`, 단일 슬롯, 새 실행 시 덮어씀)에 캐시하여 재방문 시 즉시 표시됩니다. **트랜스크립트별 캐시와 전체 결과 캐시 모두 7일이 지나면 읽을 때 거부됩니다.** 따라서 대시보드는 1주일 이상 된 결과를 조용히 제공하지 않으며, TTL이 지나면 `/audit`이 빈 상태로 폴백되어 새 실행을 안내합니다. 보고서 하단의 `[ re-audit now ]`를 클릭하면 `noCache: true`로 `/api/audit/run`에 POST 요청을 보내며, 재감사는 트랜스크립트별 캐시를 우회하고 캐시된 결과를 조용히 반환하는 대신 모든 트랜스크립트를 처음부터 다시 스캔합니다. 대시보드는 실행이 완료될 때까지 1Hz로 `/api/audit/status`를 폴링하며, 실행 중에는 경과 타이머와 함께 고정된 분홍색 진행 스트립이 뷰포트 상단에 표시됩니다. 성공 시 새 결과가 전체 페이지 새로고침 없이 그 자리에서 교체됩니다. 재감사에 실패하면 스트립이 빨간색으로 바뀌며 `RerunError.kind`(`timeout` / `network` / `post_failed`)에 맞는 메시지가 표시됩니다. 빈 상태(캐시 없음 또는 만료)와 세션 없음 상태(캐시는 있지만 스캔에서 트랜스크립트가 없음)는 별도로 표시됩니다. ### 정책 정책 관리 및 활동 검토를 위한 두 탭 페이지입니다. - - - 단일 패널에서 failproofai가 보호할 에이전트 CLI를 다중 선택 — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Hermes 각각에 설치 상태(`Active` / `Detected` / `Inactive`), 사용자 범위 설정 경로, 브랜드 색상 강조가 있는 행. 원하는 CLI를 체크 또는 체크 해제하고 `Apply changes`를 클릭하면 차이점만 한 번에 설치/제거됩니다. PATH에서 바이너리가 감지된 CLI는 미리 체크됩니다. - - 클릭 한 번으로 개별 정책 켜기/끄기 (`~/.failproofai/policies-config.json`에 기록됨 — 설치된 모든 CLI에서 공유됨) - - 정책을 펼쳐서 매개변수 구성 (`policyParams`를 지원하는 정책의 경우) - - 사용자 정의 정책 파일 경로 설정 + + - 단일 패널에서 failproofai가 보호할 에이전트 CLI를 다중 선택합니다 — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Hermes 모두 설치 상태(`Active` / `Detected` / `Inactive`), 사용자 범위 설정 경로, 브랜드 색상 강조 표시가 있는 행으로 표시됩니다. 원하는 CLI를 체크 또는 체크 해제하고 `Apply changes`를 클릭하면 차이를 한 번에 설치/제거합니다. PATH에서 바이너리가 감지된 CLI는 미리 체크됩니다. + - 클릭 한 번으로 개별 정책을 켜고 끕니다 (`~/.failproofai/policies-config.json`에 기록 — 설치된 모든 CLI에서 공유됨) + - 정책을 펼쳐 매개변수를 구성합니다 (`policyParams`를 지원하는 정책에 해당) + - 커스텀 정책 파일 경로 설정 - - - 모든 세션에서 발생한 모든 훅 이벤트의 전체 페이지 히스토리 - - 결정, 이벤트 유형, CLI(Claude Code / OpenAI Codex / GitHub Copilot _(베타)_ / Cursor Agent _(베타)_ / OpenCode _(베타)_ / Pi _(베타)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), 정책 이름 또는 세션 ID로 필터링 - - 각 행에는 타임스탬프, 정책 이름, 결정, CLI 배지(주황 = Claude Code, 보라 = OpenAI Codex, 파랑 = GitHub Copilot, 에메랄드 = Cursor Agent, 호박색 = OpenCode, 분홍 = Pi, 인디고 = Hermes, 청록 = OpenClaw, 로즈 = Factory Droid, 바이올렛 = Devin, 시안 = Antigravity, 라임 = Goose), 도구 이름, 세션 ID, deny/instruct 결정의 이유가 표시됩니다 - - 세션 ID를 클릭하면 해당 트랜스크립트가 열립니다 — 뷰어는 훅을 실행한 CLI를 자동으로 감지하고(Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) 헤더에 일치하는 CLI 배지를 렌더링합니다 + + - 모든 세션에서 실행된 모든 훅 이벤트의 전체 페이지네이션 기록 + - 결정, 이벤트 유형, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(베타)_ / Cursor Agent _(베타)_ / OpenCode _(베타)_ / Pi _(베타)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), 정책 이름, 또는 세션 ID로 필터링 + - 각 행에 표시되는 내용: 타임스탬프, 정책 이름, 결정, CLI 배지 (주황색 = Claude Code, 보라색 = OpenAI Codex, 파란색 = GitHub Copilot, 에메랄드색 = Cursor Agent, 앰버색 = OpenCode, 분홍색 = Pi, 인디고색 = Hermes, 청록색 = OpenClaw, 로즈색 = Factory Droid, 바이올렛색 = Devin, 시안색 = Antigravity, 라임색 = Goose), 툴 이름, 세션 ID, deny/instruct 결정의 이유 + - 세션 ID를 클릭하면 해당 트랜스크립트가 열립니다 — 뷰어는 훅을 실행한 CLI를 자동 감지하고 (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) 헤더에 일치하는 CLI 배지를 렌더링합니다 @@ -92,7 +94,7 @@ failproofai ## 자동 새로고침 -대시보드 상단 내비게이션에는 자동 새로고침 토글이 있습니다. 활성화하면 현재 페이지가 주기적으로 새로고침되어 새 세션과 정책 활동이 나타나는 즉시 표시됩니다. 장시간 실행되는 자율 에이전트 세션을 모니터링할 때 필수적인 기능입니다. +대시보드에는 상단 내비게이션에 자동 새로고침 토글이 있습니다. 활성화하면 현재 페이지가 주기적으로 새로고침되어 새 세션과 정책 활동이 나타나는 대로 표시됩니다. 장시간 실행되는 자율 에이전트 세션을 모니터링하는 데 필수적입니다. --- @@ -110,7 +112,7 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## 프로젝트 경로 구성 -기본적으로 대시보드는 표준 Claude Code 프로젝트 디렉토리에서 읽습니다. 사용자 정의 설정을 위해 재정의하세요: +기본적으로 대시보드는 표준 Claude Code 프로젝트 디렉토리에서 읽습니다. 커스텀 설정을 위해 재정의하세요: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,13 +122,13 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## localhost가 아닌 호스트에서 접근하기 -**개발 모드**(`npm run dev`)로 대시보드를 실행하고 `localhost` 이외의 호스트명(예: 사용자 정의 도메인, 원격 IP, 터널 URL)에서 접근하는 경우 다음과 같은 경고가 표시될 수 있습니다: +**개발 모드** (`npm run dev`)로 대시보드를 실행하고 `localhost`가 아닌 호스트 이름(예: 커스텀 도메인, 원격 IP, 터널링된 URL)에서 접근하는 경우 다음과 같은 경고가 표시될 수 있습니다: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -이는 Next.js가 개발 전용 기능인 HMR(핫 모듈 리로드) 웹소켓에 대한 교차 출처 접근을 차단하는 것입니다. 호스트를 허용하려면 `--allowed-origins` 플래그를 사용하세요: +이는 Next.js가 개발 전용 기능인 HMR(핫 모듈 리로드) 웹소켓에 대한 크로스 오리진 접근을 차단하는 것입니다. 호스트를 허용하려면 `--allowed-origins` 플래그를 사용하세요: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -145,5 +147,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -이 설정은 개발 모드에만 적용됩니다. `failproofai`(프로덕션 모드)를 실행할 때는 HMR 웹소켓이 없고 교차 출처 개발 리소스 문제도 발생하지 않습니다. +이는 개발 모드에만 적용됩니다. `failproofai`(프로덕션 모드)를 실행할 때는 HMR 웹소켓도 없고 크로스 오리진 개발 리소스 문제도 없습니다. \ No newline at end of file diff --git a/docs/pt-br/configuration.mdx b/docs/pt-br/configuration.mdx index f0d9db1c..201620ca 100644 --- a/docs/pt-br/configuration.mdx +++ b/docs/pt-br/configuration.mdx @@ -4,7 +4,7 @@ description: "Formato do arquivo de configuração, sistema de três escopos e r icon: gear --- -failproofai usa arquivos de configuração JSON para controlar quais políticas estão ativas, como elas se comportam e de onde as políticas personalizadas são carregadas. A configuração foi projetada para ser fácil de compartilhar com sua equipe — faça o commit no seu repositório e todos os desenvolvedores terão a mesma rede de segurança para agentes. +failproofai usa arquivos de configuração JSON para controlar quais políticas estão ativas, como elas se comportam e de onde as políticas personalizadas são carregadas. A configuração foi projetada para ser fácil de compartilhar com sua equipe — faça o commit no repositório e todos os desenvolvedores terão a mesma rede de segurança para o agente. --- @@ -13,12 +13,12 @@ failproofai usa arquivos de configuração JSON para controlar quais políticas Existem três escopos de configuração, avaliados em ordem de prioridade: | Escopo | Caminho do arquivo | Finalidade | -|--------|--------------------|------------| +|--------|-------------------|------------| | **project** | `.failproofai/policies-config.json` | Configurações por repositório, commitadas no controle de versão | -| **local** | `.failproofai/policies-config.local.json` | Substituições pessoais por repositório, incluídas no gitignore | -| **global** | `~/.failproofai/policies-config.json` | Padrões do usuário aplicados em todos os projetos | +| **local** | `.failproofai/policies-config.local.json` | Substituições pessoais por repositório, ignoradas pelo git | +| **global** | `~/.failproofai/policies-config.json` | Padrões no nível do usuário para todos os projetos | -Quando failproofai recebe um evento de hook, ele carrega e mescla os três arquivos que existirem para o diretório de trabalho atual. +Quando failproofai recebe um evento de hook, ele carrega e mescla todos os três arquivos que existem para o diretório de trabalho atual. ### Regras de mesclagem @@ -29,10 +29,10 @@ project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← união sem duplicatas +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← união deduplicada ``` -**`policyParams`** — o primeiro escopo que define os parâmetros para uma política específica vence por completo. Não há mesclagem profunda de valores dentro dos parâmetros de uma política. +**`policyParams`** — o primeiro escopo que define os parâmetros para uma determinada política vence por completo. Não há mesclagem profunda de valores dentro dos parâmetros de uma política. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -42,14 +42,20 @@ resolved: { allowPatterns: ["sudo apt-get update"] } ← project vence, global ``` ```text -project: (sem entrada para block-sudo) -local: (sem entrada para block-sudo) +project: (sem entrada block-sudo) +local: (sem entrada block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← cai para o global ``` -**`customPoliciesPath`** — o primeiro escopo que o define vence. +**`customPoliciesPaths` / `customPoliciesPath`** — o primeiro escopo que define qualquer uma das formas vence. + +**`disabledCustomPolicies`** — união entre todos os escopos. O painel escreve um +ID qualificado pela fonte aqui quando você desativa uma política individual de um +arquivo de política explícito ou de convenção. Políticas não listadas permanecem habilitadas por +padrão; os IDs incluem o arquivo de origem para que políticas com o mesmo nome em múltiplos arquivos +possam ser controladas de forma independente. **`llm`** — o primeiro escopo que o define vence. @@ -102,9 +108,9 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← cai para o global Tipo: `string[]` -Lista de nomes de políticas a serem habilitadas. Os nomes devem corresponder exatamente aos identificadores de política exibidos por `failproofai policies`. Consulte [Políticas Integradas](/pt-br/built-in-policies) para ver a lista completa. +Lista de nomes de políticas a habilitar. Os nomes devem corresponder exatamente aos identificadores de política exibidos por `failproofai policies`. Consulte [Políticas Integradas](/pt-br/built-in-policies) para a lista completa. -Políticas que não estejam em `enabledPolicies` ficam inativas, mesmo que tenham entradas em `policyParams`. +Políticas que não estão em `enabledPolicies` ficam inativas, mesmo que tenham entradas em `policyParams`. ### `policyParams` @@ -112,17 +118,17 @@ Tipo: `Record>` Substituições de parâmetros por política. A chave externa é o nome da política; as chaves internas são específicas de cada política. Cada política documenta seus parâmetros disponíveis em [Políticas Integradas](/pt-br/built-in-policies). -Se uma política tiver parâmetros mas você não os especificar, os padrões internos da política serão usados. Usuários que não configurarem `policyParams` terão comportamento idêntico ao das versões anteriores. +Se uma política tem parâmetros, mas você não os especifica, os padrões integrados da política são usados. Usuários que não configuram `policyParams` têm o comportamento idêntico às versões anteriores. -Chaves desconhecidas dentro do bloco de parâmetros de uma política são silenciosamente ignoradas no momento em que o hook é disparado, mas sinalizadas como avisos ao executar `failproofai policies`. +Chaves desconhecidas dentro do bloco de parâmetros de uma política são silenciosamente ignoradas no momento da execução do hook, mas sinalizadas como avisos quando você executa `failproofai policies`. #### `hint` (transversal) Tipo: `string` (opcional) -Uma mensagem anexada ao motivo quando uma política retorna `deny` ou `instruct`. Use para fornecer orientações práticas a Claude sem modificar a própria política. +Uma mensagem anexada ao motivo quando uma política retorna `deny` ou `instruct`. Use-a para fornecer orientações práticas ao Claude sem modificar a própria política. -Funciona com qualquer tipo de política — integradas, personalizadas (`custom/`), convenções de projeto (`.failproofai-project/`) ou convenções de usuário (`.failproofai-user/`). +Funciona com qualquer tipo de política — integrada, personalizada (`custom/`), convenção de projeto (`.failproofai-project/`) ou convenção do usuário (`.failproofai-user/`). ```json { @@ -143,15 +149,15 @@ Funciona com qualquer tipo de política — integradas, personalizadas (`custom/ Quando `block-force-push` nega, Claude vê: *"Force-pushing is blocked. Try creating a fresh branch instead."* -Valores não-string e strings vazias são silenciosamente ignorados. Se `hint` não estiver definido, o comportamento permanece inalterado (compatível com versões anteriores). +Valores não-string e strings vazias são silenciosamente ignorados. Se `hint` não estiver definido, o comportamento não é alterado (compatível com versões anteriores). ### `customPoliciesPath` Tipo: `string` (caminho absoluto) -Caminho para um arquivo JavaScript contendo políticas de hook personalizadas. Esse campo é configurado automaticamente por `failproofai policies --install --custom ` (o caminho é resolvido para absoluto antes de ser armazenado). +Caminho para um arquivo JavaScript contendo políticas de hook personalizadas. Este campo é definido automaticamente por `failproofai policies --install --custom ` (o caminho é resolvido para absoluto antes de ser armazenado). -O arquivo é carregado do zero a cada evento de hook — não há cache. Consulte [Políticas Personalizadas](/pt-br/custom-policies) para detalhes de autoria. +O arquivo é carregado novamente a cada evento de hook — não há cache. Consulte [Políticas Personalizadas](/pt-br/custom-policies) para detalhes de criação. ### Políticas baseadas em convenção @@ -160,13 +166,13 @@ Além do `customPoliciesPath` explícito, failproofai descobre e carrega automat | Nível | Diretório | Escopo | |-------|-----------|--------| | Projeto | `.failproofai/policies/` | Compartilhado com a equipe via controle de versão | -| Usuário | `~/.failproofai/policies/` | Pessoal, aplicado a todos os projetos | +| Usuário | `~/.failproofai/policies/` | Pessoal, aplica-se a todos os projetos | -**Correspondência de arquivos:** Apenas arquivos que correspondam a `*policies.{js,mjs,ts}` são carregados (por exemplo, `security-policies.mjs`, `workflow-policies.js`). Outros arquivos no diretório são ignorados. +**Correspondência de arquivos:** Somente arquivos que correspondem a `*policies.{js,mjs,ts}` são carregados (ex.: `security-policies.mjs`, `workflow-policies.js`). Outros arquivos no diretório são ignorados. -**Sem configuração necessária:** Políticas de convenção não precisam de entradas em `policies-config.json`. Basta colocar os arquivos no diretório e eles serão detectados no próximo evento de hook. +**Sem configuração necessária:** Políticas de convenção não requerem entradas em `policies-config.json`. Basta colocar os arquivos no diretório e eles serão carregados no próximo evento de hook. -**Carregamento por união:** Os diretórios de convenção do projeto e do usuário são verificados. Todos os arquivos correspondentes de ambos os níveis são carregados (ao contrário de `customPoliciesPath`, que utiliza o primeiro escopo que vencer). +**Carregamento por união:** Tanto os diretórios de convenção do projeto quanto do usuário são escaneados. Todos os arquivos correspondentes de ambos os níveis são carregados (diferente de `customPoliciesPath`, que usa o critério de primeiro escopo vence). Consulte [Políticas Personalizadas](/pt-br/custom-policies) para mais detalhes e exemplos. @@ -174,7 +180,7 @@ Consulte [Políticas Personalizadas](/pt-br/custom-policies) para mais detalhes Tipo: `object` (opcional) -Configuração do cliente LLM para políticas que fazem chamadas de IA. Não é necessário para a maioria das configurações. +Configuração do cliente LLM para políticas que fazem chamadas de IA. Não é necessário na maioria das configurações. ```json { @@ -189,19 +195,24 @@ Configuração do cliente LLM para políticas que fazem chamadas de IA. Não é ## Gerenciando a configuração pela CLI -Os comandos `policies --install` e `policies --uninstall` escrevem no arquivo de configurações de hook do seu agente CLI (os pontos de entrada dos hooks), enquanto `policies-config.json` é o arquivo que você gerencia diretamente. Os dois são independentes: +Os comandos `policies --install` e `policies --uninstall` escrevem no arquivo de configurações de hook da sua CLI de agente (os pontos de entrada do hook), enquanto `policies-config.json` é o arquivo que você gerencia diretamente. Os dois são separados: -- **Configurações do agente CLI** — instrui o agente a chamar `failproofai --hook ` a cada uso de ferramenta: +- **Configurações da CLI do agente** — instrui o agente a chamar `failproofai --hook ` em cada uso de ferramenta: - **Claude Code**: `~/.claude/settings.json` (usuário), `/.claude/settings.json` (projeto), `/.claude/settings.local.json` (local) - - **OpenAI Codex**: `~/.codex/hooks.json` (usuário), `/.codex/hooks.json` (projeto) — o Codex não possui escopo `local` - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (usuário), `/.github/hooks/failproofai.json` (projeto) — o Copilot não possui escopo `local`. As entradas de hook usam os campos de comando `bash`/`powershell` com chave por SO do Copilot com `timeoutSec`; o arquivo carrega um marcador `version: 1` no nível superior. O suporte ao Copilot CLI está em **beta** enquanto verificamos o esquema de registros `events.jsonl` (não especificado na documentação pública) em mais sessões reais. - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (usuário), `/.cursor/hooks.json` (projeto) — o Cursor não possui escopo `local`. As entradas de hook usam o formato Claude `{type, command, timeout}` (sem divisão `bash`/`powershell`), mas armazenadas sob chaves de evento em camelCase (`preToolUse`, `beforeSubmitPrompt`, …) em um array plano, conforme o [esquema de hooks](https://cursor.com/docs/hooks) do Cursor; o arquivo carrega um marcador `version: 1` no nível superior. O handler canonicaliza camelCase → PascalCase via `CURSOR_EVENT_MAP`, de modo que as políticas integradas existentes disparam sem alteração. O suporte ao Cursor Agent está em **beta** enquanto verificamos o formato em disco da transcrição do Cursor (não especificado na documentação pública) em mais instalações reais. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (usuário), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (projeto) — o OpenCode não possui escopo `local`. Diferentemente dos outros cinco CLIs, o OpenCode **não possui sistema de hooks para comandos externos**: ele carrega plugins JS/TS em processo, explicitamente registrados pelo array `plugin: []` no `opencode.json` (a autodescoberta a partir de `.opencode/plugins/` **não** é como os plugins são carregados no opencode v1.14.33). A instalação deposita um pequeno shim de plugin gerado que chama o binário failproofai em subprocesso e traduz a resposta JSON no formato Claude do binário para a semântica do plugin: `throw new Error()` para negação em eventos de ferramenta (cancela a chamada da ferramenta), `client.session.prompt(...)` para instruct E para negação de `Stop` / `SubagentStop` (envia o motivo da negação como a próxima mensagem do usuário — o único canal de força de nova tentativa, já que `session.idle` é apenas de notificação e lançar exceção a partir dele é um no-op), e no-op para allow. O shim canonicaliza nomes de ferramentas (minúsculas → PascalCase via `OPENCODE_TOOL_MAP`) e chaves de argumentos de entrada de ferramentas (camelCase → snake_case via `OPENCODE_TOOL_INPUT_MAP` para `Read` / `Write` / `Edit`, por exemplo `filePath` → `file_path`, `oldString` → `old_string`) antes de encaminhar ao binário, de modo que políticas integradas de verificação de caminho como `block-read-outside-cwd`, `block-env-files` e `block-secrets-write` disparam sem alteração em chamadas de ferramentas do OpenCode. As sessões ficam no banco de dados SQLite do opencode em `~/.local/share/opencode/opencode.db`; o visualizador de sessões do dashboard as lê via `opencode db --format json` e `opencode export `. O suporte ao OpenCode está em **beta** enquanto verificamos o comportamento entre versões e em mais sessões reais. Consulte a [documentação de plugins do OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (usuário), `/.pi/settings.json` (projeto) — o Pi não possui escopo `local`. O Pi carrega pacotes de extensão TypeScript na inicialização; o arquivo de configurações é um array de strings plano `{"packages": ["./relative/path", …]}`. failproofai escreve uma única entrada no array de pacotes apontando para seu diretório `pi-extension/` empacotado. A extensão subscreve internamente aos eventos `tool_call` / `user_bash` / `input` / `session_start` do Pi e executa `failproofai --hook --cli pi` em shell; o handler canonicaliza eventos via `PI_EVENT_MAP` (underscore_lower_snake_case → PascalCase) para que as políticas integradas existentes disparem sem alteração. Os argumentos de entrada de ferramentas também são canonicalizados via `PI_TOOL_INPUT_MAP` (o Read / Write / Edit do Pi entregam `path` em vez de `file_path`; mapear a chave de nível superior permite que `block-env-files` e `block-secrets-write` disparem — `block-read-outside-cwd` já tinha um fallback para `path`). O suporte ao Pi está em **beta** enquanto a API de extensão do Pi e o layout do log de sessão se estabilizam. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**somente escopo de usuário** — o Hermes não possui configuração de projeto/local). O Hermes é um **gateway** para Slack/Telegram, portanto uma única instalação intercepta chamadas de ferramentas de todas as plataformas (Slack/Telegram/cli/cron) **e** de subagentes internos. As entradas de hook são um par `{command, timeout}` (timeout em **segundos**) sob um mapa `hooks:` com chave pelos eventos snake_case do Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); o handler canonicaliza eventos via `HERMES_EVENT_MAP` e nomes de ferramentas via `HERMES_TOOL_MAP` para que as políticas integradas disparem sem alteração. A configuração é editada por meio de uma edição de ida e volta de `Document` YAML que preserva comentários, para que as outras configurações do operador sobrevivam, e a instalação define `hooks_auto_accept: true` para que o gateway headless (sem TTY) execute os hooks sem uma solicitação de consentimento. O avaliador emite o contrato stdout `{"decision":"block","reason"}` do Hermes (o Hermes ignora códigos de saída). **Limitações:** O Hermes não possui evento `Stop` de fim de turno, portanto as políticas integradas `require-*-before-stop` nunca disparam para ele (inaplicável, não quebrado); `instruct` é rebaixado para allow com nota registrada (sem canal de contexto adicional); e a redação de segredos na saída (`sanitize-*`) não pode reescrever a saída das ferramentas pelo contrato de hook de shell. O Hermes é **também** uma fonte de **auditoria** offline — o dashboard lê suas sessões de gateway diretamente de `~/.hermes/state.db`. -- **`policies-config.json`** — informa ao failproofai quais políticas avaliar e com quais parâmetros (compartilhado entre todos os agentes CLI) - -Passe `--cli claude|codex|copilot|cursor|opencode|pi|hermes` para direcionar um agente específico (separado por espaço ou repetido para qualquer subconjunto): + - **OpenAI Codex**: `~/.codex/hooks.json` (usuário), `/.codex/hooks.json` (projeto) — Codex não tem escopo `local` + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (usuário), `/.github/hooks/failproofai.json` (projeto) — Copilot não tem escopo `local`. As entradas de hook usam os campos de comando `bash`/`powershell` com chave de OS do Copilot com `timeoutSec`; o arquivo tem um marcador `version: 1` no nível superior. O suporte ao Copilot CLI está em **beta** enquanto verificamos o esquema de registro `events.jsonl` (que a documentação pública não especifica) contra mais sessões reais. **O modo de agente do VS Code Copilot Chat (Preview)** lê configurações de hook de `.github/hooks/*.json`, `~/.copilot/hooks/*.json` e `~/.claude/settings.json` (governado pela configuração `chat.hookFilesLocations`) usando o mesmo contrato `{hookSpecificOutput:{permissionDecision:"deny",…}}` do Claude — os caminhos exatos que esta integração `copilot` e a integração `claude` (`~/.claude/settings.json`) já escrevem, portanto `failproofai policies --install --cli copilot` (ou `--cli claude`) **já aplica no modo de agente do VS Code** sem necessidade de uma integração `vscode` separada (confirmado ao vivo nos logs de descoberta do VS Code). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (usuário), `/.cursor/hooks.json` (projeto) — Cursor não tem escopo `local`. As entradas de hook usam o formato `{type, command, timeout}` do Claude, mas armazenadas sob chaves de evento em camelCase (`preToolUse`, `beforeSubmitPrompt`, …) em um array plano por escopo do [esquema de hooks](https://cursor.com/docs/hooks) do Cursor; o arquivo tem um marcador `version: 1` no nível superior. O handler canonicaliza camelCase → PascalCase via `CURSOR_EVENT_MAP` para que as políticas integradas existentes sejam disparadas sem alterações. O suporte ao Cursor Agent está em **beta** enquanto verificamos o formato do transcript em disco do Cursor (não especificado na documentação pública) contra mais instalações reais. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (usuário), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (projeto) — OpenCode não tem escopo `local`. Diferente das outras cinco CLIs, OpenCode **não possui sistema de hook de comando externo**: ele carrega plugins JS/TS em processo registrados explicitamente via o array `plugin: []` em `opencode.json` (a autodescoberta de `.opencode/plugins/` **não** é como os plugins carregam no opencode v1.14.33). A instalação cria um pequeno shim de plugin gerado que chama o binário failproofai em subprocesso e traduz a resposta JSON do binário no formato Claude de volta para a semântica de plugin: `throw new Error()` para deny de evento de ferramenta (cancela a chamada de ferramenta), `client.session.prompt(...)` para instruct E para deny de `Stop` / `SubagentStop` (envia o motivo do deny como a próxima mensagem do usuário — o único canal de força de nova tentativa, já que `session.idle` é apenas notificação e lançar exceção a partir dele é um no-op), e no-op para allow. O shim canonicaliza tanto nomes de ferramentas (minúsculas → PascalCase via `OPENCODE_TOOL_MAP`) quanto chaves de argumentos de entrada de ferramenta (camelCase → snake_case via `OPENCODE_TOOL_INPUT_MAP` para `Read` / `Write` / `Edit`, ex.: `filePath` → `file_path`, `oldString` → `old_string`) antes de encaminhar ao binário, para que as políticas integradas de verificação de caminho como `block-read-outside-cwd`, `block-env-files` e `block-secrets-write` sejam disparadas sem alterações nas chamadas de ferramenta do OpenCode. As sessões ficam no banco SQLite do opencode em `~/.local/share/opencode/opencode.db`; o visualizador de sessões do painel as lê via `opencode db --format json` e `opencode export `. O suporte ao OpenCode está em **beta** enquanto verificamos o comportamento entre versões e contra mais sessões reais. Consulte a [documentação de plugins do OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (usuário), `/.pi/settings.json` (projeto) — Pi não tem escopo `local`. Pi carrega pacotes de extensão TypeScript na inicialização; o arquivo de configurações é um array plano de strings `{"packages": ["./relative/path", …]}`. failproofai escreve uma única entrada no array de packages apontando para seu diretório `pi-extension/` empacotado. A extensão internamente assina os eventos `tool_call` / `user_bash` / `input` / `session_start` do Pi e executa `failproofai --hook --cli pi`; o handler canonicaliza underscore_lower_snake_case → PascalCase via `PI_EVENT_MAP` para que as políticas integradas existentes sejam disparadas sem alterações. Os argumentos de entrada de ferramenta também são canonicalizados via `PI_TOOL_INPUT_MAP` (Read / Write / Edit do Pi entregam `path` em vez de `file_path`; o mapeamento da chave de nível superior faz com que `block-env-files` e `block-secrets-write` sejam disparados — `block-read-outside-cwd` já tinha um fallback para `path`). O suporte ao Pi está em **beta** enquanto a API de extensão e o layout de log de sessão do Pi se estabilizam. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**somente escopo de usuário** — Hermes não tem configuração de projeto/local). Hermes é um **gateway** Slack/Telegram, então uma instalação intercepta chamadas de ferramenta de todas as plataformas (Slack/Telegram/cli/cron) **e** subagentes internos. As entradas de hook são um par `{command, timeout}` (timeout em **segundos**) sob um mapa `hooks:` com chave pelos eventos snake_case do Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); o handler canonicaliza eventos via `HERMES_EVENT_MAP` e nomes de ferramentas via `HERMES_TOOL_MAP` para que as políticas integradas sejam disparadas sem alterações. A configuração é editada por meio de um round-trip YAML `Document` com preservação de comentários para que as outras configurações do operador sobrevivam, e a instalação define `hooks_auto_accept: true` para que o gateway sem cabeça (sem TTY) execute os hooks sem um prompt de consentimento. O avaliador emite o contrato stdout `{"decision":"block","reason"}` do Hermes (Hermes ignora códigos de saída). **Limitações:** Hermes não tem evento `Stop` de fim de turno, portanto as políticas integradas `require-*-before-stop` nunca são disparadas (inaplicável, não quebrado); `instruct` degrada para allow-with-logged-note (sem canal de contexto adicional); e a redação de segredos de saída (`sanitize-*`) não pode reescrever a saída de ferramenta pelo contrato de shell-hook. Hermes também é uma fonte **offline** de **auditoria** — o painel lê suas sessões de gateway diretamente de `~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**somente escopo de usuário** — OpenClaw não tem configuração de projeto/local). Como o Hermes, OpenClaw é um **gateway** multi-canal auto-hospedado, então uma instalação intercepta chamadas de ferramenta de todos os canais e seus subagentes internos. A aplicação ocorre por meio dos **hooks de plugin em processo** do OpenClaw (seus hooks internos baseados em arquivo são apenas de observação e não podem bloquear), portanto — como OpenCode/Pi — failproofai envia um pacote estático `openclaw-plugin/` que gera o binário failproofai de forma assíncrona e traduz o veredito. A instalação registra o diretório de plugin enviado em `plugins.load.paths[]` do `openclaw.json` e o habilita em `plugins.entries.failproofai` (com `hooks.allowConversationAccess: true`, necessário para os hooks de conversa bruta). O avaliador emite um veredito plano `{permission, reason}` e o shim o mapeia para a forma de retorno nativa de cada hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**) e `before_agent_finalize → {action:"revise", reason}` (**Stop** — um verdadeiro gate de fim de turno, portanto as políticas integradas `require-*-before-stop` **se aplicam** no OpenClaw, diferente do Hermes). Eventos e nomes de ferramentas são canonicalizados no lado do binário via `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) para que as políticas integradas sejam disparadas sem alterações; o shim falha aberto em qualquer erro de spawn/parse/timeout. OpenClaw também é uma fonte **offline** de **auditoria** — o painel lê suas sessões JSONL em `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (usuário), `/.factory/hooks.json` (projeto) — Factory não tem escopo `local`. droid vem com um sistema de hook de comando externo no estilo Claude, mas com duas peculiaridades verificadas ao vivo contra droid v0.171.0: (1) os nomes de eventos ficam no **nível superior** de `hooks.json` — **não há wrapper `"hooks"`** (droid rejeita um); eventos de ferramenta (`PreToolUse`/`PostToolUse`) carregam `"matcher": "*"`, eventos que não são de ferramenta omitem-no. (2) O deny é conduzido pelo **código de saída 2 + stderr** do hook, não por uma decisão JSON — o ramo `factory` do avaliador retorna saída 2 para eventos de ferramenta/prompt e `{decision:"block", reason}` somente no evento `Stop` de fim de turno (o único canal de força de nova tentativa do droid). Os eventos já estão em PascalCase (sem mapa de eventos) e o payload é snake_case do Claude; apenas os nomes de ferramentas são canonicalizados via `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory também é uma fonte **offline** de **auditoria** — o painel lê suas sessões JSONL em disco em `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (usuário), `/.devin/config.json` (projeto) — Devin não tem escopo `local`. Devin é um **clone puro do Claude** verificado ao vivo contra devin v3000.1.27: usa o esquema padrão de wrapper `"hooks"` do Claude (as escritas preservam a mesclagem para que as outras chaves do arquivo de configuração — `org_id`, `theme_mode`, … — sobrevivam), nomes de eventos já em PascalCase (sem mapa de eventos, sem ramo de handler) e um payload stdin snake_case do Claude (sem normalização). O ramo `devin` do avaliador nega com JSON `{"decision":"block","reason"}` no stdout com saída 0 para **todos** os eventos (verificado — o bloqueio substituiu `--permission-mode dangerous`); no evento `Stop` de fim de turno, o motivo traz a redação de força de nova tentativa MANDATORY-ACTION para que as políticas integradas `require-*-before-stop` se apliquem. Apenas os nomes de ferramentas são canonicalizados via `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` já é canônico). Devin também é uma fonte **offline** de **auditoria** — o painel lê suas sessões SQLite em `~/.local/share/devin/cli/sessions.db` (cada linha `sessions` carrega um `working_directory` real, então as sessões são agrupadas por cwd de projeto como Claude). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (usuário), `/.agents/hooks.json` (projeto) — Antigravity não tem escopo `local`. Diferente de Factory/Devin, Antigravity tem seu **próprio** contrato (não é um clone do Claude), verificado ao vivo contra agy v1.1.2. `hooks.json` usa um esquema de **hook nomeado**: a chave de nível superior é um *nome* de hook (`"failproofai"`) cujo valor é um mapa evento→handlers — eventos de ferramenta (`PreToolUse`/`PostToolUse`) envolvem handlers em `{matcher:"*", hooks:[…]}`, enquanto `PreInvocation`/`Stop` são arrays de handlers **planos** (outros hooks nomeados são preservados). O payload stdin é **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai o normaliza para snake_case antes de as políticas serem executadas, e mapeia os argumentos PascalCase do `run_command` (`CommandLine`/`Cwd`) via `ANTIGRAVITY_TOOL_INPUT_MAP`. O ramo `antigravity` do avaliador usa as formas de resposta **próprias** do Antigravity: `{decision:"deny", reason}` bloqueia uma ferramenta/prompt (saída 0), `{decision:"continue", reason}` no evento `Stop` de fim de turno re-entra no loop (para que as políticas integradas `require-*-before-stop` se apliquem) e `{injectSteps:[{ephemeralMessage}]}` injeta uma instrução em `PreInvocation` (→ `UserPromptSubmit`). Os nomes de ferramentas são canonicalizados via `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity também é uma fonte **offline** de **auditoria** — o painel lê seus transcritos JSONL simples em `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (índice de conversas em `conversation_summaries.db`). + - **Goose (codinome goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (usuário), `/.agents/plugins/failproofai/hooks/hooks.json` (projeto) — Goose não tem escopo `local`. A aplicação usa o sistema de **hooks** do Goose, a especificação **Open Plugins** entre agentes: o instalador apenas cria o diretório de plugin `failproofai` e o Goose o descobre automaticamente na inicialização (registrando-o em `~/.config/goose/config.yaml`). O `hooks.json` usa um esquema Open Plugins **com** um wrapper `"hooks"` no nível superior, e o matcher é **omitido** em todos os eventos — um `"*"` simples é um regex inválido que não corresponde a nada (verificado ao vivo contra goose v1.43.0). Os nomes de eventos já estão em PascalCase (sem mapa de eventos); o payload stdin usa `event`/`working_dir`, que o handler normaliza para `hook_event_name`/`cwd`. O ramo `goose` do avaliador nega com JSON `{"decision":"block","reason"}` no stdout com saída 0, respeitado **apenas no evento `PreToolUse`** (enviado no goose ≥ v1.37.0) — que é disparado para a ferramenta shell **e dentro de subagentes delegados**, sendo assim o único ponto de deny suficiente; qualquer outro erro de hook falha **aberto**. Goose **não tem evento `Stop`**, portanto as políticas integradas `require-*-before-stop` não se aplicam (como no Hermes). Os nomes de ferramentas são canonicalizados via `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) e as chaves de caminho via `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose também é uma fonte **offline** de **auditoria** — o painel lê suas sessões SQLite em `~/.local/share/goose/sessions/sessions.db` (cada linha `sessions` carrega um `working_dir` real, então as sessões são agrupadas por cwd de projeto como Devin; execuções avulsas com `--no-session` são filtradas). +- **`policies-config.json`** — informa ao failproofai quais políticas avaliar e com quais parâmetros (compartilhado entre todas as CLIs de agente) + +Passe `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` para selecionar um agente específico (separados por espaço ou repetidos para qualquer subconjunto): ```bash failproofai policies --install --cli codex --scope project @@ -210,21 +221,26 @@ failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli hermes --scope user -failproofai policies --install --cli claude codex copilot cursor opencode pi +failproofai policies --install --cli openclaw --scope user +failproofai policies --install --cli factory --scope project +failproofai policies --install --cli devin --scope project +failproofai policies --install --cli antigravity --scope project +failproofai policies --install --cli goose --scope project +failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -Quando `--cli` é omitido, `failproofai` detecta quais agentes CLI estão instalados (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`): +Quando `--cli` é omitido, `failproofai` detecta quais CLIs de agente estão instaladas (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): -- **Um CLI detectado** — seleciona automaticamente esse CLI sem solicitar confirmação. -- **Vários CLIs detectados** em um terminal interativo — exibe um prompt de seleção única com teclas de seta, agrupado em uma seção `Detected (N)` (com uma linha agregada `Install for all N detected` + cada CLI detectado individualmente) e uma seção `Not installed (M) · install hooks ahead of time` listando todos os CLIs suportados não detectados como opções de instalação antecipada (↑↓ para mover, Enter para selecionar, ^C para sair). O fluxo de desinstalação exibe apenas a seção Detected. -- **Vários CLIs detectados** em uma execução não interativa (CI, sem TTY) — instala para todos os CLIs detectados sem solicitar confirmação. -- **Nenhum detectado** — retorna para `claude`, com um aviso de que nenhum binário de agente foi encontrado no PATH; o comando de hook ainda é escrito para que seja ativado assim que você instalar um. +- **Uma CLI detectada** — seleciona automaticamente essa CLI sem solicitar confirmação. +- **Múltiplas CLIs detectadas** em um terminal interativo — exibe um prompt de seleção única com teclas de seta, agrupado em uma seção `Detected (N)` (com uma linha agregada `Install for all N detected` + cada CLI detectada individualmente) e uma seção `Not installed (M) · install hooks ahead of time` listando cada CLI suportada não detectada como opção de instalação antecipada (↑↓ para mover, Enter para selecionar, ^C para sair). O fluxo de desinstalação mostra apenas a seção Detected. +- **Múltiplas CLIs detectadas** em uma execução não interativa (CI, sem TTY) — instala para todas as CLIs detectadas sem solicitar confirmação. +- **Nenhuma detectada** — volta para `claude`, com um aviso de que nenhum binário de agente foi encontrado no PATH; o comando de hook ainda é escrito para que seja ativado assim que você instalar um. Você pode editar `policies-config.json` diretamente a qualquer momento; as alterações entram em vigor imediatamente no próximo evento de hook, sem necessidade de reinicialização. --- -## Exemplo: configuração no nível de projeto com padrões da equipe +## Exemplo: configuração de nível de projeto com padrões de equipe Faça o commit de `.failproofai/policies-config.json` no seu repositório: @@ -245,4 +261,4 @@ Faça o commit de `.failproofai/policies-config.json` no seu repositório: } ``` -Cada desenvolvedor pode então criar `.failproofai/policies-config.local.json` (incluído no gitignore) para substituições pessoais sem afetar os colegas de equipe. \ No newline at end of file +Cada desenvolvedor pode então criar `.failproofai/policies-config.local.json` (ignorado pelo git) para substituições pessoais sem afetar os colegas de equipe. \ No newline at end of file diff --git a/docs/pt-br/custom-policies.mdx b/docs/pt-br/custom-policies.mdx index 2bb5a049..1a50ac84 100644 --- a/docs/pt-br/custom-policies.mdx +++ b/docs/pt-br/custom-policies.mdx @@ -1,10 +1,10 @@ --- title: Políticas Personalizadas -description: "Escreva suas próprias políticas em JavaScript — aplique convenções, evite desvios, detecte falhas e integre com sistemas externos" +description: "Escreva suas próprias políticas em JavaScript - aplique convenções, previna desvios, detecte falhas e integre com sistemas externos" icon: code --- -As políticas personalizadas permitem que você escreva regras para qualquer comportamento do agente: aplique convenções do projeto, evite desvios, bloqueie operações destrutivas, detecte agentes travados ou integre com Slack, fluxos de aprovação e muito mais. Elas utilizam o mesmo sistema de eventos de hook e as decisões `allow`, `deny` e `instruct` das políticas integradas. +As políticas personalizadas permitem que você escreva regras para qualquer comportamento do agente: aplicar convenções do projeto, prevenir desvios, controlar operações destrutivas, detectar agentes travados ou integrar com Slack, fluxos de aprovação e muito mais. Elas utilizam o mesmo sistema de eventos de hook e as mesmas decisões `allow`, `deny`, `instruct` das políticas integradas. --- @@ -39,28 +39,28 @@ failproofai policies --install --custom ./my-policies.js ## Duas formas de carregar políticas personalizadas -### Opção 1: Por convenção (recomendado) +### Opção 1: Baseada em convenção (recomendada) -Coloque arquivos `*policies.{js,mjs,ts}` na pasta `.failproofai/policies/` e eles serão carregados automaticamente — sem flags ou alterações de configuração. Funciona como git hooks: basta adicionar o arquivo e ele já funciona. +Coloque arquivos `*policies.{js,mjs,ts}` no diretório `.failproofai/policies/` e eles serão carregados automaticamente — sem flags ou alterações de configuração. Funciona como hooks do git: basta colocar o arquivo e pronto. ``` -# Nível do projeto — commitado no git, compartilhado com a equipe +# Nível de projeto — commitado no git, compartilhado com o time .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# Nível do usuário — pessoal, aplicado a todos os projetos +# Nível de usuário — pessoal, aplica-se a todos os projetos ~/.failproofai/policies/my-policies.mjs ``` **Como funciona:** -- Os diretórios do projeto e do usuário são verificados (união — sem prioridade por escopo) +- Tanto o diretório do projeto quanto o do usuário são verificados (união — não vence o primeiro escopo) - Os arquivos são carregados em ordem alfabética dentro de cada diretório. Use o prefixo `01-`, `02-` para controlar a ordem -- Apenas arquivos que correspondem a `*policies.{js,mjs,ts}` são carregados; outros arquivos são ignorados +- Apenas arquivos que correspondam a `*policies.{js,mjs,ts}` são carregados; outros arquivos são ignorados - Cada arquivo é carregado de forma independente (fail-open por arquivo) - Funciona junto com `--custom` explícito e políticas integradas -As políticas por convenção são a forma mais fácil de estabelecer um padrão de qualidade para sua organização. Faça commit de `.failproofai/policies/` no git e todos os membros da equipe recebem as mesmas regras automaticamente — sem configuração por desenvolvedor. Conforme sua equipe descobre novos tipos de falha, adicione uma política e faça push. Com o tempo, elas se tornam um padrão de qualidade vivo que melhora a cada contribuição. +As políticas por convenção são a forma mais fácil de construir um padrão de qualidade para sua organização. Commite `.failproofai/policies/` no git e cada membro do time recebe as mesmas regras automaticamente — sem configuração individual necessária. À medida que sua equipe descobre novos modos de falha, adicione uma política e faça push. Com o tempo, isso se torna um padrão de qualidade vivo que melhora a cada contribuição. ### Opção 2: Caminho de arquivo explícito @@ -69,20 +69,25 @@ As políticas por convenção são a forma mais fácil de estabelecer um padrão # Instalar com um arquivo de políticas personalizado failproofai policies --install --custom ./my-policies.js -# Substituir o caminho do arquivo de políticas +# Substituir os caminhos de políticas personalizadas failproofai policies --install --custom ./new-policies.js -# Remover o caminho de políticas personalizadas da configuração +# Configurar múltiplos arquivos explícitos (carregados na ordem das flags) +failproofai policies --install --custom ./security.js --custom ./workflow.js + +# Remover todos os caminhos de políticas personalizadas explícitas da configuração failproofai policies --uninstall --custom ``` -O caminho absoluto resolvido é armazenado em `policies-config.json` como `customPoliciesPath`. O arquivo é carregado novamente a cada evento de hook — não há cache entre eventos. +Os caminhos absolutos resolvidos são armazenados em `policies-config.json` como `customPoliciesPaths`. Repita `--custom` para configurar múltiplos arquivos. Configurações existentes que usam o campo legado `customPoliciesPath` continuam funcionando. Os arquivos são carregados novamente a cada evento de hook — não há cache entre eventos. + +Cada política registrada aparece com seu próprio toggle no dashboard. Desativar uma política registra seu ID qualificado por fonte em `disabledCustomPolicies`; o arquivo e suas outras políticas continuam sendo carregados, enquanto a política desativada é excluída antes da correspondência de eventos. Nomes de políticas duplicados entre arquivos possuem toggles independentes. -### Usando as duas opções juntas +### Usando ambas juntas -As políticas por convenção e o arquivo `--custom` explícito podem coexistir. Ordem de carregamento: +As políticas por convenção e os arquivos `--custom` explícitos podem coexistir. Ordem de carregamento: -1. Arquivo `customPoliciesPath` explícito (se configurado) +1. Arquivos `customPoliciesPaths` explícitos (na ordem configurada) 2. Arquivos de convenção do projeto (`{cwd}/.failproofai/policies/`, em ordem alfabética) 3. Arquivos de convenção do usuário (`~/.failproofai/policies/`, em ordem alfabética) @@ -98,44 +103,44 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Registra uma política. Chame quantas vezes precisar para múltiplas políticas no mesmo arquivo. +Registra uma política. Chame quantas vezes forem necessárias para múltiplas políticas no mesmo arquivo. ```ts customPolicies.add({ name: string; // obrigatório - identificador único description?: string; // exibido na saída de `failproofai policies` - match?: { events?: HookEventType[] }; // filtra por tipo de evento; omita para corresponder a todos + match?: { events?: HookEventType[] }; // filtrar por tipo de evento; omitir para corresponder a todos fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### Funções auxiliares de decisão +### Helpers de decisão -| Função | Efeito | Use quando | -|----------|--------|----------| -| `allow()` | Permite a operação silenciosamente | A ação é segura, sem necessidade de mensagem | -| `deny(message)` | Bloqueia a operação | O agente não deve executar esta ação | -| `instruct(message)` | Adiciona contexto sem bloquear | Forneça contexto extra ao agente para mantê-lo no caminho certo | +| Função | Efeito | Quando usar | +|--------|--------|-------------| +| `allow()` | Permite a operação silenciosamente | A ação é segura, nenhuma mensagem necessária | +| `deny(message)` | Bloqueia a operação | O agente não deve realizar esta ação | +| `instruct(message)` | Adiciona contexto sem bloquear | Fornece contexto extra ao agente para mantê-lo no caminho certo | `deny(message)` — a mensagem aparece para Claude com o prefixo `"Blocked by failproofai:"`. Um único `deny` interrompe toda avaliação subsequente. -`instruct(message)` — a mensagem é anexada ao contexto de Claude para a chamada de ferramenta atual. Todas as mensagens `instruct` são acumuladas e entregues juntas. +`instruct(message)` — a mensagem é acrescentada ao contexto de Claude para a chamada de ferramenta atual. Todas as mensagens `instruct` são acumuladas e entregues juntas. -Você pode adicionar orientações extras a qualquer mensagem `deny` ou `instruct` incluindo um campo `hint` em `policyParams` — sem necessidade de alterar o código. Isso funciona também para políticas personalizadas (`custom/`), por convenção do projeto (`.failproofai-project/`) e por convenção do usuário (`.failproofai-user/`). Consulte [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para mais detalhes. +Você pode acrescentar orientações extras a qualquer mensagem `deny` ou `instruct` adicionando um campo `hint` em `policyParams` — sem necessidade de alterar o código. Isso funciona para políticas `custom/`, de convenção de projeto (`.failproofai-project/`) e de convenção de usuário (`.failproofai-user/`) também. Consulte [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para mais detalhes. -### Mensagens allow informativas +### Mensagens informativas de allow -`allow(message)` permite a operação **e** envia uma mensagem informativa para Claude. A mensagem é entregue como `additionalContext` na resposta stdout do hook handler — o mesmo mecanismo usado por `instruct`, mas semanticamente diferente: é uma atualização de status, não um aviso. +`allow(message)` permite a operação **e** envia uma mensagem informativa de volta para Claude. A mensagem é entregue como `additionalContext` na resposta stdout do handler do hook — o mesmo mecanismo usado por `instruct`, mas semanticamente diferente: é uma atualização de status, não um aviso. -| Função | Efeito | Use quando | -|----------|--------|----------| -| `allow(message)` | Permite e envia contexto para Claude | Confirme que uma verificação passou, ou explique por que foi ignorada | +| Função | Efeito | Quando usar | +|--------|--------|-------------| +| `allow(message)` | Permite e envia contexto para Claude | Confirmar que uma verificação passou, ou explicar por que foi ignorada | Casos de uso: -- **Confirmações de status:** `allow("All CI checks passed.")` — informa Claude que tudo está ok -- **Explicações de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — informa Claude por que uma verificação foi ignorada para que ele tenha contexto completo +- **Confirmações de status:** `allow("All CI checks passed.")` — informa a Claude que tudo está em ordem +- **Explicações de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — informa a Claude por que uma verificação foi ignorada, para que tenha contexto completo - **Múltiplas mensagens são acumuladas:** se várias políticas retornarem `allow(message)`, todas as mensagens são unidas com quebras de linha e entregues juntas ```js @@ -146,7 +151,7 @@ customPolicies.add({ const cwd = ctx.session?.cwd; if (!cwd) return allow("No working directory, skipping branch check."); - // ... verificar status do branch ... + // ... check branch status ... if (allPushed) { return allow("Branch is up to date with remote."); } @@ -155,32 +160,32 @@ customPolicies.add({ }); ``` -### Campos de `PolicyContext` +### Campos do `PolicyContext` | Campo | Tipo | Descrição | -|-------|------|-------------| +|-------|------|-----------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | | `toolName` | `string \| undefined` | A ferramenta sendo chamada (ex.: `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | Os parâmetros de entrada da ferramenta | -| `payload` | `Record` | Payload bruto completo do evento do Claude Code | +| `payload` | `Record` | Payload completo do evento bruto do Claude Code | | `session` | `SessionMetadata \| undefined` | Contexto da sessão (veja abaixo) | -### Campos de `SessionMetadata` +### Campos do `SessionMetadata` | Campo | Tipo | Descrição | -|-------|------|-------------| +|-------|------|-----------| | `sessionId` | `string` | Identificador da sessão do Claude Code | | `cwd` | `string` | Diretório de trabalho da sessão do Claude Code | | `transcriptPath` | `string` | Caminho para o arquivo de transcrição JSONL da sessão | -### Tipos de evento +### Tipos de eventos | Evento | Quando dispara | Conteúdo de `toolInput` | -|-------|--------------|----------------------| +|--------|---------------|-------------------------| | `PreToolUse` | Antes de Claude executar uma ferramenta | A entrada da ferramenta (ex.: `{ command: "..." }` para Bash) | | `PostToolUse` | Após a conclusão de uma ferramenta | A entrada da ferramenta + `tool_result` (a saída) | -| `Notification` | Quando Claude envia uma notificação | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks devem sempre retornar `allow()`, não podem bloquear notificações | -| `Stop` | Quando a sessão do Claude encerra | Vazio | +| `Notification` | Quando Claude envia uma notificação | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — os hooks devem sempre retornar `allow()`, não podem bloquear notificações | +| `Stop` | Quando a sessão Claude termina | Vazio | --- @@ -188,10 +193,10 @@ customPolicies.add({ As políticas são avaliadas nesta ordem: -1. Políticas integradas (em ordem de definição) -2. Políticas personalizadas explícitas de `customPoliciesPath` (em ordem de `.add()`) -3. Políticas por convenção do projeto em `.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` internamente) -4. Políticas por convenção do usuário em `~/.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` internamente) +1. Políticas integradas (na ordem de definição) +2. Políticas personalizadas explícitas de `customPoliciesPath` (na ordem de `.add()`) +3. Políticas de convenção do projeto `.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` internamente) +4. Políticas de convenção do usuário `~/.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` internamente) O primeiro `deny` interrompe todas as políticas subsequentes. Todas as mensagens `instruct` são acumuladas e entregues juntas. @@ -218,7 +223,7 @@ customPolicies.add({ }); ``` -Todas as importações relativas alcançáveis a partir do arquivo de entrada são resolvidas. Isso é implementado reescrevendo as importações de `from "failproofai"` para o caminho real do dist e criando arquivos `.mjs` temporários para garantir compatibilidade com ESM. +Todas as importações relativas acessíveis a partir do arquivo de entrada são resolvidas. Isso é implementado reescrevendo as importações `from "failproofai"` para o caminho real do dist e criando arquivos `.mjs` temporários para garantir a compatibilidade com ESM. --- @@ -231,33 +236,33 @@ customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Dispara apenas quando a sessão encerra + // Só dispara quando a sessão termina // ctx.session.transcriptPath contém o log completo da sessão return allow(); }, }); ``` -Omita `match` completamente para disparar em todos os tipos de evento. +Omita `match` completamente para disparar em todo tipo de evento. --- ## Tratamento de erros e modos de falha -As políticas personalizadas são **fail-open**: erros nunca bloqueiam as políticas integradas nem causam falha no hook handler. +As políticas personalizadas são **fail-open**: erros nunca bloqueiam as políticas integradas nem travam o handler do hook. | Falha | Comportamento | -|---------|----------| +|-------|--------------| | `customPoliciesPath` não definido | Nenhuma política personalizada explícita é executada; políticas por convenção e integradas continuam normalmente | | Arquivo não encontrado | Aviso registrado em `~/.failproofai/hook.log`; políticas integradas continuam | | Erro de sintaxe/importação (explícito) | Erro registrado em `~/.failproofai/hook.log`; políticas personalizadas explícitas são ignoradas | | Erro de sintaxe/importação (convenção) | Erro registrado; aquele arquivo é ignorado, outros arquivos de convenção ainda são carregados | -| `fn` lança erro em tempo de execução | Erro registrado; aquele hook é tratado como `allow`; outros hooks continuam | +| `fn` lança exceção em tempo de execução | Erro registrado; aquele hook é tratado como `allow`; outros hooks continuam | | `fn` demora mais de 10s | Timeout registrado; tratado como `allow` | -| Diretório de convenção ausente | Nenhuma política por convenção é executada; sem erro | +| Diretório de convenção ausente | Nenhuma política de convenção é executada; sem erro | -Para depurar erros de políticas personalizadas, monitore o arquivo de log: +Para depurar erros em políticas personalizadas, monitore o arquivo de log: ```bash tail -f ~/.failproofai/hook.log @@ -272,7 +277,7 @@ tail -f ~/.failproofai/hook.log // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// Impede o agente de escrever no diretório secrets/ +// Prevent agent from writing to secrets/ directory customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -285,7 +290,7 @@ customPolicies.add({ }, }); -// Mantém o agente no caminho certo: verifica os testes antes de commitar +// Keep the agent on track: verify tests before committing customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +305,7 @@ customPolicies.add({ }, }); -// Impede mudanças de dependências não planejadas durante o período de freeze +// Prevent unplanned dependency changes during freeze customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -326,11 +331,11 @@ export { customPolicies }; O diretório `examples/` contém arquivos de políticas prontos para uso: | Arquivo | Conteúdo | -|------|----------| -| `examples/policies-basic.js` | Cinco políticas iniciais cobrindo modos de falha comuns de agentes | -| `examples/policies-advanced/index.js` | Padrões avançados: importações transitivas, chamadas assíncronas, filtragem de saída e hooks de fim de sessão | -| `examples/convention-policies/security-policies.mjs` | Políticas de segurança por convenção (bloquear escrita em .env, impedir reescrita do histórico git) | -| `examples/convention-policies/workflow-policies.mjs` | Políticas de fluxo de trabalho por convenção (lembretes de testes, auditoria de escritas em arquivos) | +|---------|----------| +| `examples/policies-basic.js` | Cinco políticas iniciais cobrindo modos comuns de falha de agentes | +| `examples/policies-advanced/index.js` | Padrões avançados: importações transitivas, chamadas assíncronas, limpeza de saída e hooks de encerramento de sessão | +| `examples/convention-policies/security-policies.mjs` | Políticas de segurança baseadas em convenção (bloquear escrita em .env, prevenir reescrita do histórico do git) | +| `examples/convention-policies/workflow-policies.mjs` | Políticas de fluxo de trabalho baseadas em convenção (lembretes de teste, auditoria de escrita em arquivos) | ### Usando exemplos com arquivo explícito diff --git a/docs/pt-br/dashboard.mdx b/docs/pt-br/dashboard.mdx index fc500f1e..34ea316e 100644 --- a/docs/pt-br/dashboard.mdx +++ b/docs/pt-br/dashboard.mdx @@ -16,7 +16,7 @@ failproofai Abre em `http://localhost:8020`. -O dashboard lê dados locais de projetos, sessões e configurações do failproofai diretamente do sistema de arquivos. Funcionalidades autenticadas opcionais, como lembretes de auditoria e convites, enviam as informações necessárias para essas requisições (incluindo endereços de e-mail) para APIs remotas. +O dashboard lê dados locais de projeto, sessão e configuração do failproofai diretamente do sistema de arquivos. Recursos autenticados opcionais, como lembretes de auditoria e convites, enviam as informações necessárias para essas requisições (incluindo endereços de e-mail) para APIs remotas. --- @@ -24,12 +24,14 @@ O dashboard lê dados locais de projetos, sessões e configurações do failproo ### Projetos -Lista todos os projetos Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity e Goose encontrados na sua máquina. Projetos Claude são descobertos a partir de `~/.claude/projects/` (ou do caminho definido por `CLAUDE_PROJECTS_PATH`); projetos Codex são descobertos escaneando todas as transcrições em `~/.codex/sessions///
/*.jsonl` e agrupando pelo `cwd` registrado no primeiro registro de cada sessão; projetos Copilot CLI são descobertos escaneando cada `~/.copilot/session-state//workspace.yaml` (configurável via `COPILOT_HOME`) e agrupando pelo campo `cwd`; projetos Cursor Agent são descobertos escaneando metadados por sessão em `~/.cursor/agent-sessions//` (configurável via `CURSOR_HOME`, com `conversations/` e `sessions/` verificados como fallbacks) em busca de um escalar `cwd` em `meta.json` / `session.json` / `workspace.yaml`; projetos OpenCode são descobertos consultando seu banco SQLite em `~/.local/share/opencode/opencode.db` via `opencode db --format json` (lemos as tabelas `session` e `project` e agrupamos por `project_id`); projetos Pi são descobertos escaneando transcrições JSONL por sessão em `~/.pi/agent/sessions//_.jsonl` (configurável via `PI_SESSIONS_DIR`) e extraindo o `cwd` do primeiro registro de cada sessão; sessões do gateway Hermes são lidas diretamente do seu armazenamento SQLite em `~/.hermes/state.db` (configurável via `HERMES_DB_PATH`) e agrupadas em projetos `hermes-` por `source` (Slack/Telegram/cli/cron — sessões de gateway não possuem cwd); sessões do gateway OpenClaw são lidas de `~/.openclaw/agents//sessions/*.jsonl` e agrupadas em projetos `openclaw-` (também sem cwd); projetos Factory Droid são descobertos a partir das transcrições JSONL em `~/.factory/sessions//*.jsonl` e agrupados por cwd; projetos Devin a partir do seu banco SQLite em `~/.local/share/devin/cli/sessions.db` (agrupados pelo `working_directory` de cada sessão); projetos Antigravity a partir das transcrições JSONL em `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` e agrupados por cwd; e projetos Goose a partir do seu banco SQLite em `~/.local/share/goose/sessions/sessions.db` (agrupados pelo `working_dir` de cada sessão). Um projeto que foi utilizado por múltiplos CLIs é renderizado como uma única linha com todos os badges correspondentes. Use o dropdown **CLI** acima da tabela para filtrar por um agente CLI específico; a URL preserva sua seleção como `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +Lista todos os projetos Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity e Goose encontrados na sua máquina. Projetos Claude são descobertos em `~/.claude/projects/` (ou no caminho definido por `CLAUDE_PROJECTS_PATH`); projetos Codex são descobertos varrendo todas as transcrições em `~/.codex/sessions///
/*.jsonl` e agrupados pelo `cwd` registrado no primeiro registro de cada sessão; projetos Copilot CLI são descobertos varrendo cada `~/.copilot/session-state//workspace.yaml` (configurável via `COPILOT_HOME`) e agrupados pelo campo `cwd`; projetos Cursor Agent são descobertos varrendo metadados por sessão em `~/.cursor/agent-sessions//` (configurável via `CURSOR_HOME`, com `conversations/` e `sessions/` verificados como alternativas) para um escalar `cwd` em `meta.json` / `session.json` / `workspace.yaml`; projetos OpenCode são descobertos consultando seu banco SQLite em `~/.local/share/opencode/opencode.db` via `opencode db --format json` (lemos as tabelas `session` e `project` e agrupamos por `project_id`); projetos Pi são descobertos varrendo transcrições JSONL por sessão em `~/.pi/agent/sessions//_.jsonl` (configurável via `PI_SESSIONS_DIR`) e extraindo o `cwd` do primeiro registro de cada sessão; sessões de gateway Hermes são lidas diretamente do armazenamento SQLite de cada perfil — `~/.hermes/state.db` mais `~/.hermes/profiles//state.db` (substituível via `HERMES_HOME`, ou `HERMES_DB_PATH` para um único banco de dados) — e agrupadas em projetos `hermes--` por perfil e `source` (Slack/Telegram/cli/cron — sessões de gateway não têm cwd); sessões de gateway OpenClaw são lidas de `~/.openclaw/agents//sessions/*.jsonl` e agrupadas em projetos `openclaw--` por agente e canal (também sem cwd); projetos Factory Droid são descobertos a partir das transcrições JSONL em `~/.factory/sessions//*.jsonl` e agrupados por cwd; projetos Devin a partir do banco SQLite em `~/.local/share/devin/cli/sessions.db` (agrupados pelo `working_directory` de cada sessão); projetos Antigravity a partir das transcrições JSONL em `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` e agrupados por cwd; e projetos Goose a partir do banco SQLite em `~/.local/share/goose/sessions/sessions.db` (agrupados pelo `working_dir` de cada sessão). Um projeto utilizado por múltiplos CLIs é renderizado como uma única linha com todos os badges correspondentes. Use o menu suspenso **CLI** acima da tabela para filtrar por um agente CLI específico; a URL preserva sua seleção como `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. + +Hermes e OpenClaw têm escopo de usuário e não possuem diretório de trabalho para agrupamento, portanto são renderizados como uma **árvore de pastas recolhível** — perfil (ou agente) no nível superior, seus canais abaixo — enquanto todos os CLIs baseados em cwd permanecem como linhas planas. Linhas de pasta acumulam a contagem de sessões e a atividade mais recente de tudo que está abaixo delas, pastas recolhidas são lembradas entre visitas, e uma busca por palavra-chave expande o que encontrar. Cada projeto exibe: - Nome do projeto (derivado do caminho da pasta) - Um badge de CLI — `Claude Code` (laranja), `OpenAI Codex` (roxo), `GitHub Copilot` (azul), `Cursor Agent` (esmeralda), `OpenCode` (âmbar), `Pi` (rosa) e/ou `Hermes` (índigo) -- Data da atividade de sessão mais recente +- Data da atividade mais recente na sessão Clique em um projeto para ver suas sessões. @@ -47,27 +49,27 @@ Clique em uma sessão para abrir o visualizador de sessão. ### Visualizador de sessão -O visualizador de sessão responde à pergunta-chave para agentes autônomos: o que o agente fez e ele se manteve no caminho certo? Um badge de CLI ao lado do cabeçalho indica se a sessão é uma transcrição Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity ou Goose. Ele exibe uma linha do tempo de tudo que aconteceu em uma sessão: +O visualizador de sessão responde à pergunta principal para agentes autônomos: o que o agente fez e ele permaneceu no caminho certo? Um badge de CLI ao lado do cabeçalho indica se a sessão é uma transcrição de Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity ou Goose. Ele exibe uma linha do tempo de tudo o que aconteceu em uma sessão: - **Mensagens** - Respostas de texto do Claude e prompts do usuário -- **Chamadas de ferramentas** - Cada ferramenta que o Claude invocou, com sua entrada e saída +- **Chamadas de ferramentas** - Cada ferramenta invocada pelo Claude, com sua entrada e saída - **Atividade de políticas** - Para cada chamada de ferramenta, quais políticas foram acionadas e qual decisão retornaram -A barra de estatísticas no topo exibe a duração da sessão, total de chamadas de ferramentas e um resumo das decisões de hooks (contagens de allow / deny / instruct). +A barra de estatísticas no topo exibe a duração da sessão, total de chamadas de ferramentas e um resumo das decisões de hook (contagens de allow / deny / instruct). -Clique no botão **Download Logs** para exportar a sessão. Para sessões Claude Code, Codex, Copilot, Cursor e Pi você recebe a transcrição JSONL original em disco byte a byte; para OpenCode (cujas sessões ficam no SQLite, não em disco) você recebe um documento JSON espelhando as tabelas subjacentes `session` / `messages` / `parts`. +Clique no botão **Download Logs** para exportar a sessão. Para sessões Claude Code, Codex, Copilot, Cursor e Pi, você recebe a transcrição JSONL original em disco byte a byte; para OpenCode (cujas sessões ficam no SQLite, não em disco) você recebe um documento JSON espelhando as tabelas subjacentes `session` / `messages` / `parts`. ### Auditoria -Um relatório com personalidade sobre como seu agente realmente se comportou ao longo de sessões anteriores. Executa o mesmo escaneamento que o CLI `failproofai audit`, mas o renderiza como um pôster compartilhável em tela única + quatro seções abaixo da dobra: +Um relatório com personalidade sobre como seu agente tem se comportado nas sessões anteriores. Executa a mesma varredura do CLI `failproofai audit`, mas renderiza como um pôster compartilhável em tela única + quatro seções abaixo da dobra: -1. **Pôster** — preenche o primeiro viewport. Região de captura PNG independente com a marca failproof_ai + rótulo de auditoria · índice de arquétipo (`№ NN de 08`) + data da auditoria · pontuação numérica (0–100) + pílula de ranking percentil (`top 15%`) · o nome do arquétipo (um de `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + faixa de 3 palavras-chave · linha de raridade `// only N% of agents are this archetype` · tile de símbolo 8×8 pixels · rodapé `audit yours → failproof.ai`. Três botões de compartilhamento ficam logo fora da caixa de captura: `post your archetype` (intent no X), `share on linkedin`, `download poster`. A captura é feita via `html-to-image`, então o PNG corresponde pixel a pixel ao que está na tela (bordas tracejadas, máscara de logo SVG, gradientes, métricas de fonte — tudo preservado). -2. **Pontos fortes** — lista tranquila com ✓ de comportamentos que seu agente já faz certo, derivados dos dados de auditoria ao vivo (taxa limpa de chamadas de ferramentas, sem pushes diretos para main, zero vazamentos de credenciais, zero tempestades de retentativas) — cada um exibido apenas quando a política relevante tem um histórico limpo ao longo da janela de auditoria. -3. **Peculiaridades** — tabela do que escapou, ordenada por severidade: `quando · o que escapou + a política que teria detectado · pílula de severidade · visto`, onde a recorrência aparece como `new` (uma vez), `N× seen` (2–9 vezes) ou `recurring` (10+). -4. **Como melhorar** — lista tranquila de linhas, uma por política prescrita: nome da política em branco, descrição em uma linha, comando de instalação + botão de cópia à direita. O cabeçalho da seção exibe `enable all N → projected · ` (a pontuação que você alcançaria com todas as correções aplicadas), e seu botão `[install all]` copia o comando combinado `failproofai policy add a b c …` para cada política prescrita. -5. **Volte melhor** — dois cartões lado a lado. Esquerda: defina um lembrete (seletor de cadência `3d` / `7d` / `14d` / `30d`; persiste via `/api/auth/reminder` após autenticação). Direita: desbloqueie vantagens failproof — `invite a friend` abre um modal que aceita uma lista de e-mails de amigos separados por vírgula/espaço/quebra de linha (máximo 10 por envio), faz POST para `/api/audit/invite`, que encaminha para o `POST /v0/invite` do api-server. O api-server envia um e-mail por destinatário a partir de `invite@failproof.ai` com o remetente em Cc e `Reply-To` definido, para que o destinatário veja quem o convidou e o remetente receba uma cópia em sua caixa de entrada. Usuários anônimos são direcionados primeiro pelo `AuthDialog` para que o e-mail do remetente seja conhecido antes que os convites sejam enviados. Direitos / cumprimento de vantagens é um passo seguinte. +1. **Pôster** — preenche o primeiro viewport. Região de captura PNG autossuficiente com a marca failproof_ai + rótulo de auditoria · índice de arquétipo (`№ NN de 08`) + data da auditoria · pontuação numérica (0–100) + pílula de percentil (`top 15%`) · o nome do arquétipo (um de `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + faixa de 3 palavras-chave · linha de raridade `// only N% of agents are this archetype` · tile de símbolo 8×8 pixels · rodapé `audit yours → failproof.ai`. Três botões de compartilhamento ficam logo fora da caixa de captura: `post your archetype` (X intent), `share on linkedin`, `download poster`. A captura é feita via `html-to-image`, então o PNG corresponde pixel a pixel à renderização na tela (bordas tracejadas, máscara de logo SVG, gradientes, métricas de fonte — tudo preservado). +2. **Pontos fortes** — lista de linhas ✓ com os comportamentos que seu agente já faz corretamente, derivados dos dados de auditoria ao vivo (taxa de chamadas de ferramentas limpas, sem pushes diretos para main, zero vazamentos de credenciais, zero tempestades de tentativas) — cada um exibido apenas quando a política relevante tem um histórico limpo durante a janela de auditoria. +3. **Peculiaridades** — tabela do que escapou, classificado por gravidade: `quando · o que escapou + a política que teria capturado · pílula de gravidade · visto`, onde a recorrência indica `new` (uma vez), `N× seen` (2–9 vezes) ou `recurring` (10+). +4. **Como melhorar** — lista de linhas, uma por política prescrita: nome da política em branco, descrição de uma linha, comando de instalação + botão de cópia à direita. O cabeçalho da seção exibe `enable all N → projected · ` (a pontuação que você atingiria com todas as correções aplicadas), e seu botão `[install all]` copia o comando combinado `failproofai policy add a b c …` para cada política prescrita. +5. **Volte melhor** — dois cartões lado a lado. Esquerda: definir um lembrete (seletor de cadência `3d` / `7d` / `14d` / `30d`; persiste via `/api/auth/reminder` após autenticação). Direita: desbloquear benefícios failproof — `invite a friend` abre um modal que aceita uma lista separada por vírgula/espaço/quebra de linha de e-mails de amigos (máx. 10 por envio), POSTa para `/api/audit/invite`, que encaminha para o `POST /v0/invite` do api-server. O api-server envia um e-mail por destinatário de `invite@failproof.ai` com o remetente em Cc e `Reply-To` definido, então o destinatário vê quem o convidou e o remetente recebe uma cópia em sua caixa de entrada. Usuários anônimos são direcionados primeiro pelo `AuthDialog` para que o e-mail do remetente seja conhecido antes dos convites serem enviados. Direitos / cumprimento de benefícios é um acompanhamento. -Alimentado pelo runtime do `failproofai audit` — consulte [Audit CLI](/pt-br/cli/audit) para o mecanismo de escaneamento subjacente, flags suportadas e invariantes de cache por transcrição. O dashboard armazena em cache o último resultado em `~/.failproofai/audit-dashboard.json` (modo `0600`, slot único, novas execuções sobrescrevem) para que revisitas sejam instantâneas; **tanto os caches por transcrição quanto os de resultado completo são rejeitados na leitura quando têm mais de 7 dias**, portanto o dashboard nunca serve silenciosamente um resultado com uma semana de idade — após o TTL, `/audit` cai para seu estado vazio e solicita uma nova execução. Clicar em `[ re-audit now ]` próximo ao final do relatório faz POST em `/api/audit/run` com `noCache: true` — a re-auditoria ignora o cache por transcrição e re-escaneia cada transcrição do zero em vez de retornar silenciosamente o resultado em cache — e o dashboard faz polling em `/api/audit/status` a 1Hz até que a execução termine; uma faixa rosa fixa de progresso se prende ao topo do viewport durante a execução com um temporizador de tempo decorrido, e o resultado atualizado substitui no lugar ao concluir com sucesso (sem recarga de página completa; uma re-auditoria com falha mantém o relatório anterior intacto). Em caso de falha, a faixa fica vermelha com texto baseado no `RerunError.kind` (`timeout` / `network` / `post_failed`). Estado vazio (sem cache ou expirado) e estado de zero sessões (cache existe mas o escaneamento não encontrou transcrições) são exibidos separadamente. +Alimentado pelo runtime `failproofai audit` — veja [Audit CLI](/pt-br/cli/audit) para o mecanismo de varredura subjacente, flags suportadas e invariantes de cache por transcrição. O dashboard armazena em cache o resultado mais recente em `~/.failproofai/audit-dashboard.json` (modo `0600`, slot único, novas execuções sobrescrevem) para que revisitas sejam instantâneas; **tanto o cache por transcrição quanto o de resultado completo são rejeitados na leitura uma vez que tenham mais de 7 dias** para que o dashboard nunca sirva silenciosamente um resultado de uma semana atrás — após o TTL, `/audit` cai para seu estado vazio e solicita uma nova execução. Clicar em `[ re-audit now ]` perto do final do relatório POSTa `/api/audit/run` com `noCache: true` — a re-auditoria ignora o cache por transcrição e reexamina todas as transcrições do zero em vez de retornar silenciosamente o resultado em cache — e o dashboard consulta `/api/audit/status` a 1Hz até a execução terminar; uma faixa de progresso rosa fixa se prende ao topo do viewport durante a execução com um cronômetro decorrido, e o novo resultado é substituído no lugar ao concluir com sucesso (sem recarregamento completo da página; uma re-auditoria com falha mantém o relatório anterior intacto). Em caso de falha, a faixa fica vermelha com texto baseado no `RerunError.kind` (`timeout` / `network` / `post_failed`). Estado vazio (sem cache ou expirado) e estado de zero sessões (cache existe, mas a varredura não encontrou transcrições) são exibidos separadamente. ### Políticas @@ -75,15 +77,15 @@ Uma página com duas abas para gerenciar políticas e revisar atividades. - - Seleção múltipla de quais CLIs de agentes o failproofai protege a partir de um único painel — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi e Hermes têm uma linha com status de instalação (`Active` / `Detected` / `Inactive`), o caminho de configurações no escopo do usuário e um destaque com a cor da marca. Marque ou desmarque os CLIs que deseja e clique em `Apply changes` para instalar/desinstalar a diferença em uma única etapa. CLIs cujo binário é detectado no PATH são pré-marcados. - - Ative ou desative políticas individuais com um único clique (grava em `~/.failproofai/policies-config.json` — compartilhado entre todos os CLIs instalados) + - Seleção múltipla de quais CLIs de agentes o failproofai protege em um único painel — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi e Hermes têm uma linha com status de instalação (`Active` / `Detected` / `Inactive`), o caminho de configurações de escopo de usuário e um destaque com a cor da marca. Marque ou desmarque os CLIs desejados e clique em `Apply changes` para instalar/desinstalar as diferenças em um único passo. CLIs cujo binário é detectado no PATH são pré-marcados. + - Ative ou desative políticas individuais com um único clique (escreve em `~/.failproofai/policies-config.json` — compartilhado entre todos os CLIs instalados) - Expanda uma política para configurar seus parâmetros (para políticas que suportam `policyParams`) - - Defina um caminho de arquivo de políticas personalizado + - Defina um caminho personalizado para o arquivo de políticas - - Histórico completo paginado de todos os eventos de hook que ocorreram em todas as sessões - - Filtre por decisão, tipo de evento, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), nome da política ou ID de sessão - - Cada linha exibe: timestamp, nome da política, decisão, badge de CLI (laranja = Claude Code, roxo = OpenAI Codex, azul = GitHub Copilot, esmeralda = Cursor Agent, âmbar = OpenCode, rosa = Pi, índigo = Hermes, verde-azulado = OpenClaw, rosê = Factory Droid, violeta = Devin, ciano = Antigravity, limão = Goose), nome da ferramenta, ID de sessão e o motivo das decisões deny/instruct + - Histórico paginado completo de cada evento de hook que foi acionado em todas as sessões + - Filtre por decisão, tipo de evento, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), nome de política ou ID de sessão + - Cada linha exibe: timestamp, nome da política, decisão, badge de CLI (laranja = Claude Code, roxo = OpenAI Codex, azul = GitHub Copilot, esmeralda = Cursor Agent, âmbar = OpenCode, rosa = Pi, índigo = Hermes, azul-petróleo = OpenClaw, rose = Factory Droid, violeta = Devin, ciano = Antigravity, lima = Goose), nome da ferramenta, ID de sessão e o motivo para decisões de deny/instruct - Clique em um ID de sessão para abrir sua transcrição — o visualizador detecta automaticamente qual CLI acionou o hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) e renderiza o badge de CLI correspondente no cabeçalho @@ -92,13 +94,13 @@ Uma página com duas abas para gerenciar políticas e revisar atividades. ## Atualização automática -O dashboard possui um botão de atualização automática na navegação superior. Quando ativado, a página atual é atualizada periodicamente para exibir novas sessões e atividades de políticas conforme aparecem. Essencial para monitorar sessões de agentes autônomos de longa duração. +O dashboard tem um botão de alternância de atualização automática na navegação superior. Quando ativado, a página atual é atualizada periodicamente para exibir novas sessões e atividades de políticas conforme aparecem. Essencial para monitorar sessões de agentes autônomos de longa duração. --- -## Desabilitando páginas +## Desativando páginas -Se você precisar apenas de algumas partes do dashboard, defina `FAILPROOFAI_DISABLE_PAGES` com uma lista separada por vírgulas de nomes de páginas: +Se você precisar apenas de algumas partes do dashboard, defina `FAILPROOFAI_DISABLE_PAGES` como uma lista separada por vírgulas de nomes de páginas: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -110,7 +112,7 @@ Valores válidos: `policies`, `projects`, `audit`. ## Configurando o caminho dos projetos -Por padrão, o dashboard lê do diretório padrão de projetos do Claude Code. Substitua para configurações personalizadas: +Por padrão, o dashboard lê do diretório padrão de projetos Claude Code. Substitua para configurações personalizadas: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -118,7 +120,7 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Acessando a partir de um host diferente de localhost +## Acessando a partir de um host que não seja localhost Ao executar o dashboard em **modo dev** (`npm run dev`) e acessá-lo a partir de um hostname diferente de `localhost` — por exemplo, um domínio personalizado, um IP remoto ou uma URL tunelada — você pode ver um aviso como: @@ -126,7 +128,7 @@ Ao executar o dashboard em **modo dev** (`npm run dev`) e acessá-lo a partir de ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Isso é o Next.js bloqueando acesso cross-origin ao seu websocket de HMR (hot module reload), que é um recurso exclusivo do modo dev. Para permitir seu host, use a flag `--allowed-origins`: +Isso é o Next.js bloqueando o acesso cross-origin ao seu websocket HMR (hot module reload), que é um recurso exclusivo do modo dev. Para permitir seu host, use a flag `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -138,12 +140,12 @@ Para múltiplos hosts ou IPs, passe uma lista separada por vírgulas: npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -Você também pode definir a variável de ambiente `FAILPROOFAI_ALLOWED_DEV_ORIGINS`: +Você também pode definir a variável de ambiente `FAILPROOFAI_ALLOWED_DEV_ORIGINS` em vez disso: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Isso se aplica apenas ao modo dev. Ao executar `failproofai` (modo de produção), não há websocket de HMR nem problema de recurso dev cross-origin. +Isso se aplica apenas ao modo dev. Ao executar `failproofai` (modo de produção), não há websocket HMR nem problema de recurso dev cross-origin. \ No newline at end of file diff --git a/docs/ru/configuration.mdx b/docs/ru/configuration.mdx index 5445f018..4cd88f69 100644 --- a/docs/ru/configuration.mdx +++ b/docs/ru/configuration.mdx @@ -1,44 +1,44 @@ --- title: Конфигурация -description: "Формат конфига, трёхуровневая система и правила слияния" +description: "Формат файла конфигурации, трёхуровневая система и правила слияния" icon: gear --- -failproofai использует JSON-файлы конфигурации для управления активными политиками, их поведением и источниками загрузки пользовательских политик. Конфигурация разработана так, чтобы легко делиться ею с командой — просто закоммитьте в репо, и каждый разработчик получит одну и ту же защиту агента. +failproofai использует JSON-файлы конфигурации для управления активными политиками, их поведением и путями загрузки пользовательских политик. Конфигурация разработана так, чтобы её было легко делиться с командой — добавьте её в репозиторий, и каждый разработчик получит одинаковую систему безопасности агента. --- -## Области конфигурации +## Уровни конфигурации -Существуют три области конфигурации, оцениваемые в порядке приоритета: +Существует три уровня конфигурации, оцениваемых по приоритету: -| Область | Путь файла | Назначение | +| Уровень | Путь файла | Назначение | |---------|-----------|-----------| -| **project** | `.failproofai/policies-config.json` | Параметры репо, закоммичены в систему контроля версий | -| **local** | `.failproofai/policies-config.local.json` | Личные переопределения для репо, добавлены в .gitignore | -| **global** | `~/.failproofai/policies-config.json` | Пользовательские значения по умолчанию для всех проектов | +| **Проект** | `.failproofai/policies-config.json` | Параметры репозитория, зафиксированы в системе контроля версий | +| **Локально** | `.failproofai/policies-config.local.json` | Личные переопределения для репозитория, в .gitignore | +| **Глобально** | `~/.failproofai/policies-config.json` | Параметры пользователя по умолчанию для всех проектов | -Когда failproofai получает событие хука, он загружает и объединяет все три файла, существующие для текущей директории. +Когда failproofai получает событие хука, он загружает и объединяет все три файла, которые существуют в текущей директории. ### Правила слияния -**`enabledPolicies`** — объединение всех трёх областей. Политика, активированная на любом уровне, работает. +**`enabledPolicies`** — объединение всех трёх уровней. Политика, активированная на любом уровне, работает. ```text project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← дедублицированное объединение +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← объединение без дубликатов ``` -**`policyParams`** — первая область, которая определяет параметры для конкретной политики, побеждает полностью. Глубокого слияния значений внутри параметров политики не происходит. +**`policyParams`** — побеждает первый уровень, который определил параметры для данной политики. Глубокого слияния значений внутри параметров политики не происходит. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← project побеждает, global игнорируется +resolved: { allowPatterns: ["sudo apt-get update"] } ← побеждает project, global игнорируется ``` ```text @@ -46,12 +46,14 @@ project: (нет записи block-sudo) local: (нет записи block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← переходит к global +resolved: { allowPatterns: ["sudo systemctl status"] } ← падает на global ``` -**`customPoliciesPath`** — первая область, которая её определяет, побеждает. +**`customPoliciesPaths` / `customPoliciesPath`** — побеждает первый уровень, который определил одну из этих форм. -**`llm`** — первая область, которая её определяет, побеждает. +**`disabledCustomPolicies`** — объединение по всем уровням. Панель управления записывает сюда квалифицированный по источнику ID при отключении отдельной политики из явного или условного файла политики. Политики, не указанные в списке, остаются включёнными по умолчанию; ID включают исходный файл, чтобы политики с одинаковыми именами в разных файлах можно было контролировать независимо. + +**`llm`** — побеждает первый уровень, который её определил. --- @@ -102,79 +104,79 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← переходит Тип: `string[]` -Список имён политик для активации. Имена должны точно совпадать с идентификаторами политик, показываемыми `failproofai policies`. Полный список см. в разделе [Built-in Policies](/ru/built-in-policies). +Список имён политик для активации. Имена должны точно совпадать с идентификаторами политик, показываемыми через `failproofai policies`. Полный список см. в [Встроенные политики](/ru/built-in-policies). -Политики, не входящие в `enabledPolicies`, неактивны, даже если у них есть записи в `policyParams`. +Политики, не указанные в `enabledPolicies`, неактивны, даже если имеют записи в `policyParams`. ### `policyParams` Тип: `Record>` -Переопределения параметров для каждой политики. Внешний ключ — имя политики; внутренние ключи — специфичны для политики. Каждая политика документирует свои доступные параметры в разделе [Built-in Policies](/ru/built-in-policies). +Переопределения параметров по политикам. Внешний ключ — имя политики; внутренние ключи — зависят от политики. Каждая политика описывает доступные параметры в [Встроенные политики](/ru/built-in-policies). -Если у политики есть параметры, но вы их не указали, используются встроенные значения по умолчанию политики. Пользователи, которые вообще не настраивают `policyParams`, получают поведение, идентичное предыдущим версиям. +Если политика имеет параметры, но вы их не указали, используются встроенные значения по умолчанию. Пользователи, которые вообще не настраивают `policyParams`, получают идентичное поведение предыдущим версиям. -Неизвестные ключи внутри блока параметров политики молча игнорируются при срабатывании хука, но помечаются как предупреждения при запуске `failproofai policies`. +Неизвестные ключи внутри блока параметров политики молча игнорируются при срабатывании хука, но выводятся как предупреждения при запуске `failproofai policies`. -#### `hint` (кросс-функциональный) +#### `hint` (межполитическое) Тип: `string` (опционально) -Сообщение, добавляемое к причине, когда политика возвращает `deny` или `instruct`. Используйте его, чтобы дать Claude практические рекомендации без изменения самой политики. +Сообщение, добавляемое к причине, когда политика возвращает `deny` или `instruct`. Используйте его, чтобы дать Claude действенное руководство без изменения самой политики. -Работает с любым типом политики — встроенной, пользовательской (`custom/`), конвенции проекта (`.failproofai-project/`) или конвенции пользователя (`.failproofai-user/`). +Работает с любым типом политики — встроенная, пользовательская (`custom/`), условная для проекта (`.failproofai-project/`) или условная для пользователя (`.failproofai-user/`). ```json { "policyParams": { "block-force-push": { - "hint": "Try creating a fresh branch instead." + "hint": "Попробуйте создать свежую ветку." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], - "hint": "Use apt-get directly without sudo." + "hint": "Используйте apt-get напрямую без sudo." }, "custom/my-policy": { - "hint": "Ask the user for approval first." + "hint": "Сначала попросите одобрение пользователя." } } } ``` -Когда `block-force-push` отклоняет, Claude видит: *Force-pushing is blocked. Try creating a fresh branch instead.* +Когда `block-force-push` отказывает, Claude видит: *Force-pushing is blocked. Попробуйте создать свежую ветку.* -Значения не-строкового типа и пустые строки молча игнорируются. Если `hint` не установлен, поведение не изменяется (обратная совместимость). +Нестроковые значения и пустые строки молча игнорируются. Если `hint` не установлен, поведение не изменяется (обратная совместимость). ### `customPoliciesPath` Тип: `string` (абсолютный путь) -Путь к JavaScript-файлу, содержащему пользовательские политики хуков. Это автоматически устанавливается `failproofai policies --install --custom ` (путь разрешается в абсолютный перед сохранением). +Путь к файлу JavaScript, содержащему пользовательские политики хуков. Устанавливается автоматически через `failproofai policies --install --custom ` (путь разрешается в абсолютный перед сохранением). -Файл загружается заново при каждом событии хука — кеширования нет. Подробности авторства см. в разделе [Custom Policies](/ru/custom-policies). +Файл загружается заново при каждом событии хука — кеширования нет. Подробнее см. в [Пользовательские политики](/ru/custom-policies). -### Политики на основе конвенций +### Условные политики -Помимо явного `customPoliciesPath`, failproofai автоматически обнаруживает и загружает файлы политик из директорий `.failproofai/policies/`: +В дополнение к явному `customPoliciesPath`, failproofai автоматически обнаруживает и загружает файлы политик из директорий `.failproofai/policies/`: | Уровень | Директория | Область | -|---------|-----------|--------| -| Project | `.failproofai/policies/` | Общее для команды через систему контроля версий | -| User | `~/.failproofai/policies/` | Личное, применяется ко всем проектам | +|---------|-----------|---------| +| Проект | `.failproofai/policies/` | Совместно с командой через систему контроля версий | +| Пользователь | `~/.failproofai/policies/` | Личное, применяется ко всем проектам | -**Соответствие файлов:** Загружаются только файлы, соответствующие `*policies.{js,mjs,ts}` (например `security-policies.mjs`, `workflow-policies.js`). Другие файлы в директории игнорируются. +**Соответствие файлов:** Загружаются только файлы, соответствующие `*policies.{js,mjs,ts}` (например, `security-policies.mjs`, `workflow-policies.js`). Другие файлы в директории игнорируются. -**Не требуется конфиг:** Политики конвенций не требуют записей в `policies-config.json`. Просто поместите файлы в директорию, и они будут загружены при следующем событии хука. +**Конфиг не требуется:** Условные политики не требуют записей в `policies-config.json`. Просто поместите файлы в директорию, и они загружаются при следующем событии хука. -**Объединённая загрузка:** Сканируются обе директории конвенций (проекта и пользователя). Все соответствующие файлы из обоих уровней загружаются (в отличие от `customPoliciesPath`, который использует правило первой побеждающей области). +**Объединённая загрузка:** Сканируются обе директории условных политик: проекта и пользователя. Все соответствующие файлы с обоих уровней загружаются (в отличие от `customPoliciesPath`, который использует правило «первый уровень победил»). -Подробности и примеры см. в разделе [Custom Policies](/ru/custom-policies). +Подробнее см. в [Пользовательские политики](/ru/custom-policies). ### `llm` Тип: `object` (опционально) -Конфигурация LLM-клиента для политик, которые делают AI-вызовы. Не требуется для большинства установок. +Конфигурация LLM-клиента для политик, которые делают вызовы AI. Не требуется для большинства установок. ```json { @@ -189,19 +191,24 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← переходит ## Управление конфигурацией из CLI -Команды `policies --install` и `policies --uninstall` пишут в файл параметров хука вашего CLI агента (точки входа хуков), а `policies-config.json` — это файл, которым вы управляете напрямую. Это раздельные сущности: +Команды `policies --install` и `policies --uninstall` записывают в файл параметров хуков CLI вашего агента (точки входа хуков), тогда как `policies-config.json` — это файл, который вы управляете напрямую. Это две разные вещи: - **Параметры CLI агента** — указывает агенту вызывать `failproofai --hook ` при каждом использовании инструмента: - **Claude Code**: `~/.claude/settings.json` (пользователь), `/.claude/settings.json` (проект), `/.claude/settings.local.json` (локально) - - **OpenAI Codex**: `~/.codex/hooks.json` (пользователь), `/.codex/hooks.json` (проект) — Codex не имеет локальной области - - **GitHub Copilot CLI _(бета)_**: `~/.copilot/hooks/failproofai.json` (пользователь), `/.github/hooks/failproofai.json` (проект) — Copilot не имеет локальной области. Записи хуков используют поля команд `bash`/`powershell` с ключом ОС и `timeoutSec` Copilot; файл содержит маркер `version: 1` верхнего уровня. Поддержка Copilot CLI находится в **бета-версии**, пока мы проверяем схему записи `events.jsonl` (которую общедоступные документы не указывают) против дополнительных реальных сессий. - - **Cursor Agent _(бета)_**: `~/.cursor/hooks.json` (пользователь), `/.cursor/hooks.json` (проект) — Cursor не имеет локальной области. Записи хуков используют форму с Claude-подобной формой `{type, command, timeout}` (без разделения `bash`/`powershell`), но хранятся под camelCase ключами событий (`preToolUse`, `beforeSubmitPrompt`, …) в плоском массиве согласно [схеме хуков](https://cursor.com/docs/hooks) Cursor; файл содержит маркер `version: 1` верхнего уровня. Обработчик канонизирует camelCase → PascalCase через `CURSOR_EVENT_MAP`, поэтому существующие встроенные политики срабатывают без изменений. Поддержка Cursor Agent находится в **бета-версии**, пока мы проверяем транскрипт Cursor на диске (не указан в общедоступных документах) против дополнительных реальных установок. - - **OpenCode _(бета)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (пользователь), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (проект) — OpenCode не имеет локальной области. В отличие от остальных пяти CLI, OpenCode **не имеет системы внешних команд для хуков**: он загружает в процессе плагины JS/TS, явно зарегистрированные через массив `plugin: []` в `opencode.json` (автообнаружение из `.opencode/plugins/` **не** это как загружаются плагины в opencode v1.14.33). Install помещает маленький сгенерированный шим плагина, который subprocess-вызывает бинарный файл failproofai и переводит JSON-ответ бинарного файла Claude-подобной формы обратно в семантику плагина: `throw new Error()` для отрицания tool-события (отменяет вызов инструмента), `client.session.prompt(...)` для instruct И для отрицания `Stop` / `SubagentStop` (отправляет причину отрицания как следующее пользовательское сообщение — единственный канал force-retry, так как `session.idle` только для уведомления и выброс из неё — это no-op), и no-op для allow. Шим канонизирует названия инструментов (lowercase → PascalCase через `OPENCODE_TOOL_MAP`) и ключи аргументов инструментов (camelCase → snake_case через `OPENCODE_TOOL_INPUT_MAP` для `Read` / `Write` / `Edit`, например `filePath` → `file_path`, `oldString` → `old_string`) перед отправкой в бинарный файл, поэтому встроенные проверки путей вроде `block-read-outside-cwd`, `block-env-files` и `block-secrets-write` срабатывают без изменений для вызовов инструментов OpenCode. Сессии живут в БД SQLite OpenCode в `~/.local/share/opencode/opencode.db`; средство просмотра сессий на панели инструментов читает их через `opencode db --format json` и `opencode export `. Поддержка OpenCode находится в **бета-версии**, пока мы проверяем поведение в разных версиях и против дополнительных реальных сессий. См. [документацию плагинов OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(бета)_**: `~/.pi/agent/settings.json` (пользователь), `/.pi/settings.json` (проект) — Pi не имеет локальной области. Pi загружает пакеты расширений TypeScript при запуске; файл параметров — это плоский массив строк `{"packages": ["./relative/path", …]}`. failproofai записывает одну запись packages-массива, указывающую на встроенную директорию `pi-extension/`. Расширение внутренне подписывается на события Pi `tool_call` / `user_bash` / `input` / `session_start` и shell-вызывает `failproofai --hook --cli pi`; обработчик канонизирует underscore_lower_snake_case → PascalCase через `PI_EVENT_MAP`, поэтому существующие встроенные политики срабатывают без изменений. Аргументы инструментов также канонизируются через `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit доставляют `path` вместо `file_path`; картирование верхнего уровня позволяет `block-env-files` и `block-secrets-write` срабатывать — `block-read-outside-cwd` уже имел fallback для `path`). Поддержка Pi находится в **бета-версии**, пока API расширений Pi и макет журнала сессий стабилизируются. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**только область пользователя** — Hermes не имеет конфига проекта/локально). Hermes — это **шлюз** Slack/Telegram, поэтому одна установка перехватывает вызовы инструментов от каждой платформы (Slack/Telegram/cli/cron) **и** внутренние подагенты. Записи хуков — это пара `{command, timeout}` (timeout в **секундах**) под картой `hooks:` с ключами от snake_case событий Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); обработчик канонизирует события через `HERMES_EVENT_MAP` и названия инструментов через `HERMES_TOOL_MAP`, поэтому встроенные политики срабатывают без изменений. Конфиг редактируется через коммент-сохраняющий YAML round-trip `Document`, поэтому остальные параметры оператора выживают, и install устанавливает `hooks_auto_accept: true`, чтобы headless шлюз (без TTY) запускал хуки без промпта согласия. Оценщик выдаёт контракт `{"decision":"block","reason"}` stdout Hermes (Hermes игнорирует коды выхода). **Ограничения:** Hermes не имеет event end-turn `Stop`, поэтому встроенные `require-*-before-stop` никогда не срабатывают для него (неприменимо, не сломано); `instruct` деградирует до allow-with-logged-note (нет канала дополнительного контекста); и переписывание выходных секретов (`sanitize-*`) не может переписать вывод инструмента через shell-hook контракт. Hermes — **также** оффлайн **audit** источник — панель инструментов читает сессии шлюза напрямую из `~/.hermes/state.db`. + - **OpenAI Codex**: `~/.codex/hooks.json` (пользователь), `/.codex/hooks.json` (проект) — Codex не имеет локального уровня + - **GitHub Copilot CLI _(бета)_**: `~/.copilot/hooks/failproofai.json` (пользователь), `/.github/hooks/failproofai.json` (проект) — Copilot не имеет локального уровня. Записи хуков используют поля команд `bash`/`powershell` Copilot с ключом по ОС и `timeoutSec`; файл несёт маркер верхнего уровня `version: 1`. Поддержка Copilot CLI находится в **бета-версии**, пока мы проверяем схему записей `events.jsonl` (которую общедоступные документы не указывают) на реальных сеансах. **VS Code Copilot Chat агента режим (Preview)** читает конфиги хуков из `.github/hooks/*.json`, `~/.copilot/hooks/*.json` и `~/.claude/settings.json` (управляется параметром `chat.hookFilesLocations`) с использованием того же Claude-подобного контракта `{hookSpecificOutput:{permissionDecision:"deny",…}}` — точные пути, которые уже пишут интеграция `copilot` и интеграция `claude` (`~/.claude/settings.json`), поэтому `failproofai policies --install --cli copilot` (или `--cli claude`) **уже работают в режиме агента VS Code** без отдельной интеграции `vscode` (подтверждено в прямом эфире из журналов обнаружения VS Code). + - **Cursor Agent _(бета)_**: `~/.cursor/hooks.json` (пользователь), `/.cursor/hooks.json` (проект) — Cursor не имеет локального уровня. Записи хуков используют Claude-подобную форму `{type, command, timeout}` (без разделения `bash`/`powershell`), но хранятся под ключами события в camelCase (`preToolUse`, `beforeSubmitPrompt`, …) в плоском массиве согласно [схеме хуков](https://cursor.com/docs/hooks) Cursor; файл несёт маркер верхнего уровня `version: 1`. Обработчик канонизирует camelCase → PascalCase через `CURSOR_EVENT_MAP`, так что существующие встроенные политики срабатывают без изменений. Поддержка Cursor Agent находится в **бета-версии**, пока мы проверяем формат расшифровок Cursor на диске (не указанный в общедоступных документах) на реальных установках. + - **OpenCode _(бета)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (пользователь), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (проект) — OpenCode не имеет локального уровня. В отличие от пяти других CLI, OpenCode **не имеет системы внешних хуков команд**: он загружает встроенные плагины JS/TS, явно зарегистрированные через массив `plugin: []` в `opencode.json` (автообнаружение из `.opencode/plugins/` **не является** способом загрузки плагинов на opencode v1.14.33). Установка размещает небольшой сгенерированный шим плагина, который вызывает двоичный файл failproofai через подпроцесс и переводит Claude-подобный JSON-ответ двоичного файла обратно в семантику плагина: `throw new Error()` для отказа события инструмента (отменяет вызов инструмента), `client.session.prompt(...)` для `instruct` И для `Stop` / `SubagentStop` отказа (отправляет причину отказа как следующее пользовательское сообщение — единственный канал принудительного повтора, так как `session.idle` только уведомление и выброс из неё не работает), и холостой ход для разрешения. Шим канонизирует как имена инструментов (нижний регистр → PascalCase через `OPENCODE_TOOL_MAP`), так и ключи аргументов входа инструмента (camelCase → snake_case через `OPENCODE_TOOL_INPUT_MAP` для `Read` / `Write` / `Edit`, например `filePath` → `file_path`, `oldString` → `old_string`) перед отправкой двоичному файлу, поэтому проверка пути встроенными параметрами типа `block-read-outside-cwd`, `block-env-files` и `block-secrets-write` срабатывает без изменений при вызовах инструмента OpenCode. Сеансы живут в SQLite БД opencode в `~/.local/share/opencode/opencode.db`; просмотр сеансов на панели управления читает их через `opencode db --format json` и `opencode export `. Поддержка OpenCode находится в **бета-версии**, пока мы проверяем поведение между версиями и на реальных сеансах. См. [документацию плагинов OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(бета)_**: `~/.pi/agent/settings.json` (пользователь), `/.pi/settings.json` (проект) — Pi не имеет локального уровня. Pi загружает пакеты расширений TypeScript при запуске; файл параметров — это плоский массив строк `{"packages": ["./relative/path", …]}`. failproofai пишет единую запись массива пакетов, указывающую на его встроенную директорию `pi-extension/`. Расширение внутри подписывается на события `tool_call` / `user_bash` / `input` / `session_start` Pi и вызывает `failproofai --hook --cli pi`; обработчик канонизирует underscore_lower_snake_case → PascalCase через `PI_EVENT_MAP`, так что существующие встроенные политики срабатывают без изменений. Аргументы входа инструмента также канонизируются через `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit передают `path` вместо `file_path`; сопоставление верхнего ключа позволяет `block-env-files` и `block-secrets-write` срабатывать — `block-read-outside-cwd` уже имел резервное значение `path`). Поддержка Pi находится в **бета-версии**, пока API расширения Pi и макет журнала сеансов стабилизируются. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**только область пользователя** — Hermes не имеет конфига проекта/локально). Hermes — это **шлюз** Slack/Telegram, поэтому одна установка перехватывает вызовы инструментов с каждой платформы (Slack/Telegram/cli/cron) **и** внутренние подагенты. Записи хуков — это пара `{command, timeout}` (тайм-аут в **секундах**) под картой `hooks:`, ключами которой являются события Hermes в snake_case (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); обработчик канонизирует события через `HERMES_EVENT_MAP` и имена инструментов через `HERMES_TOOL_MAP`, так что встроенные политики срабатывают без изменений. Конфиг редактируется посредством сохраняющего комментарии раунда YAML `Document`, поэтому другие параметры оператора выживают, и установка устанавливает `hooks_auto_accept: true`, чтобы безголовой шлюз (без TTY) запускал хуки без запроса согласия. Оценивающий вычислитель выстраивает контракт stdout Hermes `{"decision":"block","reason"}` (Hermes игнорирует коды выхода). **Ограничения:** Hermes не имеет события конца хода `Stop`, поэтому встроенные параметры `require-*-before-stop` никогда не срабатывают для неё (неприменимо, не сломано); `instruct` деградирует до разрешить-с-логировано-примечание (нет дополнительного канала контекста); и редактирование секретов выхода (`sanitize-*`) не может переписать выход инструмента через контракт shell-хука. Hermes также является офлайн **источником аудита** — панель управления читает сеансы его шлюза прямо из `~/.hermes/state.db`. + - **OpenClaw (шлюз openclaw)**: `~/.openclaw/openclaw.json` (**только область пользователя** — OpenClaw не имеет конфига проекта/локально). Как и Hermes, OpenClaw — это самостоятельно размещённый мультиканальный **шлюз**, поэтому одна установка перехватывает вызовы инструментов с каждого канала и его внутренних подагентов. Принудительное исполнение осуществляется через **встроенные хуки плагинов** OpenClaw (его файловые внутренние хуки только для наблюдения и не могут блокировать), поэтому — как OpenCode/Pi — failproofai поставляет статический пакет `openclaw-plugin/`, который асинхронно генерирует двоичный файл failproofai и переводит вердикт. Установка регистрирует доставленную директорию плагина в `openclaw.json`'s `plugins.load.paths[]` и активирует её под `plugins.entries.failproofai` (с `hooks.allowConversationAccess: true`, требуется для хуков сырого разговора). Оценивающий вычислитель выстраивает плоский вердикт `{permission, reason}` и шим сопоставляет его с встроенной формой возврата каждого хука: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), и `before_agent_finalize → {action:"revise", reason}` (**Stop** — реальные ворота конца хода, поэтому встроенные параметры `require-*-before-stop` **принудительно исполняют** на OpenClaw, в отличие от Hermes). События и имена инструментов канонизируют двоичную сторону через `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …), так что встроенные политики срабатывают без изменений; шим неудачно открывается при любой ошибке генерации/разбора/тайм-аута. OpenClaw также является офлайн **источником аудита** — панель управления читает его сеансы JSONL в `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (пользователь), `/.factory/hooks.json` (проект) — Factory не имеет локального уровня. droid поставляет систему хуков внешних команд в стиле Claude, но с двумя особенностями, проверенными в прямом эфире на droid v0.171.0: (1) имена событий живут на **верхнем уровне** `hooks.json` — **нет обёртки `"hooks"`** (droid её отклоняет); события инструмента (`PreToolUse`/`PostToolUse`) несут `"matcher": "*"`, события не-инструмента её опускают. (2) Отказ управляется хуком **exit code 2 + stderr**, не JSON вердиктом — ветвь оценивающего вычислителя `factory` возвращает exit 2 для инструмента/подсказки событий и `{decision:"block", reason}` только на событии конца хода `Stop` (единственный канал принудительного повтора droid). События уже PascalCase (нет карты событий) и полезная нагрузка Claude snake_case; только имена инструментов канонизируют через `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory также является офлайн **источником аудита** — панель управления читает его сеансы на диске JSONL в `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (пользователь), `/.devin/config.json` (проект) — Devin не имеет локального уровня. Devin — это **чистый Claude-клон** проверенный в прямом эфире на devin v3000.1.27: он использует стандартную схему Claude с обёрткой `"hooks"` (записи с сохранением слияния, так что другие ключи файла конфига — `org_id`, `theme_mode`, … — выживают), события уже PascalCase (нет карты событий, нет ветви обработчика), и полезная нагрузка stdin Claude snake_case (без нормализации). Ветвь оценивающего вычислителя `devin` отказывает с JSON `{"decision":"block","reason"}` на stdout при exit 0 для **каждого** события (проверено — отказ переопределил `--permission-mode dangerous`); на событии конца хода `Stop` причина несёт обязательные слова принудительного повтора, поэтому встроенные параметры `require-*-before-stop` исполняют. Только имена инструментов канонизируют через `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` уже канонический). Devin также является офлайн **источником аудита** — панель управления читает его сеансы SQLite в `~/.local/share/devin/cli/sessions.db` (каждая строка `sessions` несёт реальный `working_directory`, поэтому сеансы группируются по проекту cwd как Claude). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (пользователь), `/.agents/hooks.json` (проект) — Antigravity не имеет локального уровня. В отличие от Factory/Devin, Antigravity имеет свой **собственный** контракт (не Claude-клон), проверенный в прямом эфире на agy v1.1.2. `hooks.json` использует **схему именованных хуков**: верхний ключ — это имя хука *name* (`"failproofai"`), значение которого — карта событий → обработчики — события инструмента (`PreToolUse`/`PostToolUse`) заворачивают обработчики в `{matcher:"*", hooks:[…]}`, тогда как `PreInvocation`/`Stop` — это **плоские** массивы обработчиков (другие именованные хуки сохраняются). Полезная нагрузка stdin — это **camelCase protojson** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai нормализует её в snake_case перед запуском политик и сопоставляет PascalCase аргументы `run_command` (`CommandLine`/`Cwd`) через `ANTIGRAVITY_TOOL_INPUT_MAP`. Ветвь оценивающего вычислителя `antigravity` использует **собственные** формы ответов Antigravity: `{decision:"deny", reason}` блокирует инструмент/подсказку (exit 0), `{decision:"continue", reason}` на событии конца хода `Stop` повторно входит в цикл (поэтому встроенные параметры `require-*-before-stop` исполняют), и `{injectSteps:[{ephemeralMessage}]}` вводит инструкцию на `PreInvocation` (→ `UserPromptSubmit`). Имена инструментов канонизируют через `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity также является офлайн **источником аудита** — панель управления читает его простые расшифровки JSONL в `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (индекс разговора в `conversation_summaries.db`). + - **Goose (кодовое имя goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (пользователь), `/.agents/plugins/failproofai/hooks/hooks.json` (проект) — Goose не имеет локального уровня. Принудительное исполнение использует систему **хуков** Goose, кросс-агентную спецификацию **Open Plugins**: установщик просто размещает директорию плагина `failproofai`, и Goose её автоматически обнаруживает при запуске (самостоятельно регистрируя её в `~/.config/goose/config.yaml`). `hooks.json` использует схему Open Plugins **с** обёрткой верхнего уровня `"hooks"`, и сопоставитель **опускается** в каждом событии — голый `"*"` — это неправильное регулярное выражение, которое ничему не соответствует (проверено в прямом эфире на goose v1.43.0). Имена событий уже PascalCase (нет карты событий); полезная нагрузка stdin использует `event`/`working_dir`, которые обработчик нормализует в `hook_event_name`/`cwd`. Ветвь оценивающего вычислителя `goose` отказывает с JSON `{"decision":"block","reason"}` на stdout при exit 0, почитается на событии **`PreToolUse`** только (поставляется в goose ≥ v1.37.0) — которое срабатывает для инструмента shell **и внутри делегированных подагентов**, поэтому это единственная достаточная точка отказа; любая другая ошибка хука неудачно открывается. Goose **не имеет события `Stop`**, поэтому встроенные параметры `require-*-before-stop` не применяются (как с Hermes). Имена инструментов канонизируют через `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) и ключи пути через `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose также является офлайн **источником аудита** — панель управления читает его сеансы SQLite в `~/.local/share/goose/sessions/sessions.db` (каждая строка `sessions` несёт реальный `working_dir`, поэтому сеансы группируются по проекту cwd как Devin; scratch-запуски `--no-session` фильтруются). - **`policies-config.json`** — указывает failproofai, какие политики оценивать и с какими параметрами (общее для всех CLI агентов) -Передайте `--cli claude|codex|copilot|cursor|opencode|pi|hermes` для выбора конкретного агента (разделённые пробелом или повторённые для подмножества): +Передайте `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` для нацеливания на конкретного агента (разделённые пробелом или повторённые для любого подмножества): ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +217,28 @@ failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli hermes --scope user -failproofai policies --install --cli claude codex copilot cursor opencode pi +failproofai policies --install --cli openclaw --scope user +failproofai policies --install --cli factory --scope project +failproofai policies --install --cli devin --scope project +failproofai policies --install --cli antigravity --scope project +failproofai policies --install --cli goose --scope project +failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -Когда `--cli` опущен, `failproofai` обнаруживает, какие CLI агентов установлены (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`): +Когда `--cli` опущен, `failproofai` обнаруживает, какие CLI агентов установлены (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): -- **Один CLI обнаружен** — автоматически выбирает тот CLI без запроса. -- **Несколько CLI обнаружено** в интерактивном терминале — показывает однострочный prompt выбора со стрелками, сгруппированный в раздел `Detected (N)` (с агрегированной строкой `Install for all N detected` + каждый обнаруженный CLI отдельно) и раздел `Not installed (M) · install hooks ahead of time`, перечисляющий каждый неподдерживаемый CLI как опцию forward-install (↑↓ для перемещения, Enter для выбора, ^C для выхода). Flow разустановки показывает только раздел Detected. -- **Несколько CLI обнаружено** в неинтерактивном запуске (CI, без TTY) — устанавливает для всех обнаруженных CLI без запроса. -- **Ничего не обнаружено** — возвращается к `claude` с предупреждением, что бинарный файл агента не найден в PATH; команда хука всё ещё записывается, поэтому она активируется, как только вы установите один. +- **Один CLI обнаружен** — автоматически выбирает этот CLI без подсказки. +- **Несколько CLI обнаружено** в интерактивном терминале — показывает подсказку выбора одного стрелочного ключа, сгруппированную в раздел `Detected (N)` (с строкой совокупного `Install for all N detected` + каждый обнаруженный CLI отдельно) и раздел `Not installed (M) · install hooks ahead of time`, в котором перечислены все необнаруженные поддерживаемые CLI как варианты предварительной установки (↑↓ для перемещения, Enter для выбора, ^C для выхода). Поток удаления показывает только раздел Detected. +- **Несколько CLI обнаружено** в неинтерактивном запуске (CI, нет TTY) — устанавливает для всех обнаруженных CLI без подсказки. +- **Ничего не обнаружено** — возвращается к `claude` с предупреждением, что двоичный файл агента не найден в PATH; команда хука всё ещё записывается, чтобы она активировалась, как только вы её установите. -Вы можете редактировать `policies-config.json` напрямую в любой момент; изменения вступают в силу немедленно при следующем событии хука без необходимости перезагрузки. +Вы можете редактировать `policies-config.json` напрямую в любой момент; изменения вступают в силу немедленно на следующем событии хука без необходимости перезагрузки. --- -## Пример: конфиг уровня проекта с командными значениями по умолчанию +## Пример: конфиг уровня проекта с командными параметрами по умолчанию -Закоммитьте `.failproofai/policies-config.json` в ваш репо: +Добавьте `.failproofai/policies-config.json` в ваш репозиторий: ```json { @@ -245,4 +257,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi } ``` -Каждый разработчик может затем создать `.failproofai/policies-config.local.json` (добавлен в .gitignore) для личных переопределений без влияния на товарищей по команде. \ No newline at end of file +Затем каждый разработчик может создать `.failproofai/policies-config.local.json` (в .gitignore) для личных переопределений без влияния на товарищей по команде. \ No newline at end of file diff --git a/docs/ru/custom-policies.mdx b/docs/ru/custom-policies.mdx index 80d086c2..8f8abaa9 100644 --- a/docs/ru/custom-policies.mdx +++ b/docs/ru/custom-policies.mdx @@ -1,10 +1,10 @@ --- title: Пользовательские политики -description: "Напишите свои собственные политики на JavaScript — обеспечьте соответствие соглашениям, предотвратите дрейф, обнаруживайте отказы, интегрируйтесь с внешними системами" +description: "Напишите свои собственные политики на JavaScript — обеспечивайте соблюдение конвенций, предотвращайте дрейф, обнаруживайте сбои, интегрируйтесь с внешними системами" icon: code --- -Пользовательские политики позволяют вам писать правила для любого поведения агента: обеспечивать соблюдение соглашений проекта, предотвращать дрейф, контролировать деструктивные операции, обнаруживать застрявших агентов или интегрироваться с Slack, рабочими процессами одобрения и другим. Они используют ту же систему событий перехвата и решения `allow`, `deny`, `instruct`, что и встроенные политики. +Пользовательские политики позволяют писать правила для любого поведения агента: обеспечивать соблюдение конвенций проекта, предотвращать дрейф, блокировать деструктивные операции, обнаруживать заблокированных агентов или интегрироваться со Slack, рабочими процессами одобрения и многим другим. Они используют ту же систему событий-ловушек и решения `allow`, `deny`, `instruct`, что и встроенные политики. --- @@ -39,52 +39,57 @@ failproofai policies --install --custom ./my-policies.js ## Два способа загрузки пользовательских политик -### Способ 1: На основе соглашений (рекомендуется) +### Вариант 1: На основе соглашений (рекомендуется) -Поместите файлы `*policies.{js,mjs,ts}` в `.failproofai/policies/` — они загружаются автоматически, никаких флагов или изменений конфигурации не требуется. Это работает как git хуки: положите файл, и всё просто работает. +Поместите файлы `*policies.{js,mjs,ts}` в `.failproofai/policies/` и они будут загружены автоматически — без флагов или изменений конфигурации. Это работает как git-хуки: добавьте файл, и всё просто работает. ``` -# Уровень проекта — фиксируется в git, совместно используется командой +# Уровень проекта — добавлено в git, общее для всей команды .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# Уровень пользователя — личный, применяется ко всем проектам +# Пользовательский уровень — личное, применяется ко всем проектам ~/.failproofai/policies/my-policies.mjs ``` **Как это работает:** -- Сканируются оба каталога проекта и пользователя (объединение — не первое совпадение) -- Файлы загружаются в алфавитном порядке в каждом каталоге. Префиксуйте с `01-`, `02-` для управления порядком -- Загружаются только файлы, совпадающие с `*policies.{js,mjs,ts}`; остальные файлы игнорируются -- Каждый файл загружается независимо (отказоустойчивая загрузка для каждого файла) -- Работает вместе с явным `--custom` и встроенными политиками +- Сканируются оба каталога проекта и пользователя (объединение — не первый найденный) +- Файлы загружаются в алфавитном порядке в каждом каталоге. Используйте префиксы `01-`, `02-` для управления порядком +- Загружаются только файлы, соответствующие `*policies.{js,mjs,ts}`; остальные файлы игнорируются +- Каждый файл загружается независимо (открытый отказ для каждого файла) +- Работает вместе с явными флагами `--custom` и встроенными политиками -Политики на основе соглашений — это самый простой способ установить стандарт качества для вашей организации. Зафиксируйте `.failproofai/policies/` в git, и каждый член команды автоматически получит одинаковые правила — никакой предварительной настройки для каждого разработчика не требуется. По мере того как ваша команда обнаруживает новые режимы отказа, добавляйте политику и отправляйте её. Со временем они становятся живым стандартом качества, который совершенствуется с каждым вкладом. +Политики на основе соглашений — это самый простой способ установить стандарт качества для вашей организации. Добавьте `.failproofai/policies/` в git и каждый член команды автоматически получит одинаковые правила — не требуется настройка для отдельных разработчиков. По мере того как ваша команда открывает новые режимы сбоев, добавляйте политику и отправляйте обновление. Со временем они становятся живым стандартом качества, который постоянно совершенствуется с каждым вкладом. -### Способ 2: Явный путь к файлу +### Вариант 2: Явный путь к файлу ```bash -# Установите с пользовательским файлом политик +# Установите с файлом пользовательских политик failproofai policies --install --custom ./my-policies.js -# Замените путь файла политик +# Замените пути пользовательских политик failproofai policies --install --custom ./new-policies.js -# Удалите путь пользовательских политик из конфигурации +# Настройте несколько явных файлов (загружаются в порядке флагов) +failproofai policies --install --custom ./security.js --custom ./workflow.js + +# Удалите все явные пути пользовательских политик из конфигурации failproofai policies --uninstall --custom ``` -Разрешённый абсолютный путь сохраняется в `policies-config.json` как `customPoliciesPath`. Файл загружается заново при каждом событии перехвата — кеширование между событиями отсутствует. +Разрешённые абсолютные пути хранятся в `policies-config.json` как `customPoliciesPaths`. Повторите `--custom` для настройки нескольких файлов. Существующие конфигурации, использующие устаревшее поле `customPoliciesPath`, продолжают работать. Файлы загружаются заново при каждом событии-ловушке — кэширования между событиями нет. + +Каждая зарегистрированная политика отображается с собственным переключателем на панели управления. При отключении политики её квалифицированный источником ID записывается в `disabledCustomPolicies`; файл и его остальные политики продолжают загружаться, а отключённая политика исключается перед сопоставлением событий. Политики с дублирующимися именами в разных файлах имеют независимые переключатели. -### Использование обоих вместе +### Совместное использование обоих способов -Политики на основе соглашений и явный файл `--custom` могут сосуществовать. Порядок загрузки: +Политики на основе соглашений и явные файлы `--custom` могут существовать одновременно. Порядок загрузки: -1. Явный файл `customPoliciesPath` (если настроен) -2. Файлы соглашений проекта (`{cwd}/.failproofai/policies/`, в алфавитном порядке) -3. Файлы соглашений пользователя (`~/.failproofai/policies/`, в алфавитном порядке) +1. Явные файлы `customPoliciesPaths` (в указанном порядке) +2. Файлы проектных соглашений (`{cwd}/.failproofai/policies/`, в алфавитном порядке) +3. Файлы пользовательских соглашений (`~/.failproofai/policies/`, в алфавитном порядке) --- @@ -98,45 +103,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Регистрирует политику. Вызывайте столько раз, сколько нужно для нескольких политик в одном файле. +Регистрирует политику. Вызывайте столько раз, сколько нужно, для нескольких политик в одном файле. ```ts customPolicies.add({ - name: string; // required - unique identifier - description?: string; // shown in `failproofai policies` output - match?: { events?: HookEventType[] }; // filter by event type; omit to match all + name: string; // обязательно - уникальный идентификатор + description?: string; // показывается в выводе `failproofai policies` + match?: { events?: HookEventType[] }; // фильтр по типу события; опустите для соответствия всем fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### Вспомогательные функции решений +### Помощники решений -| Функция | Эффект | Используйте, когда | -|---------|--------|-------------------| -| `allow()` | Разрешить операцию без уведомления | Действие безопасно, сообщение не требуется | +| Функция | Эффект | Используйте когда | +|----------|--------|----------| +| `allow()` | Разрешить операцию молча | Действие безопасно, сообщение не требуется | | `deny(message)` | Заблокировать операцию | Агент не должен выполнять это действие | -| `instruct(message)` | Добавить контекст без блокировки | Дайте агенту дополнительный контекст для сохранения направления | +| `instruct(message)` | Добавить контекст без блокировки | Дать агенту дополнительный контекст для выполнения задачи | -`deny(message)` — сообщение отображается Claude с префиксом `"Blocked by failproofai:"`. Единственное `deny` прекращает все дальнейшие оценки. +`deny(message)` — сообщение появляется Claude с префиксом `"Blocked by failproofai:"`. Единственный `deny` прерывает всю дальнейшую оценку. `instruct(message)` — сообщение добавляется в контекст Claude для текущего вызова инструмента. Все сообщения `instruct` накапливаются и доставляются вместе. -Вы можете добавить дополнительное руководство к любому сообщению `deny` или `instruct`, добавив поле `hint` в `policyParams` — без изменения кода. Это работает для пользовательских (`custom/`), проектных соглашений (`.failproofai-project/`) и пользовательских соглашений (`.failproofai-user/`) политик. См. [Конфигурация → hint](/ru/configuration#hint-cross-cutting) для получения информации. +Вы можете добавить дополнительное руководство к любому сообщению `deny` или `instruct`, добавив поле `hint` в `policyParams` — без изменения кода. Это работает для пользовательских (`custom/`), проектных (``.failproofai-project/``) и пользовательских (``.failproofai-user/``) политик. См. [Configuration → hint](/ru/configuration#hint-cross-cutting) для подробностей. -### Информационные сообщения allow +### Информативные сообщения разрешения -`allow(message)` разрешает операцию **и** отправляет информационное сообщение обратно Claude. Сообщение доставляется как `additionalContext` в ответе stdout обработчика перехвата — тот же механизм, используемый `instruct`, но семантически отличный: это обновление статуса, а не предупреждение. +`allow(message)` разрешает операцию **и** отправляет информативное сообщение обратно Claude. Сообщение доставляется как `additionalContext` в ответе stdout обработчика ловушек — тот же механизм, что используется `instruct`, но семантически другой: это обновление статуса, а не предупреждение. -| Функция | Эффект | Используйте, когда | -|---------|--------|-------------------| -| `allow(message)` | Разрешить и отправить контекст Claude | Подтвердить прохождение проверки или объяснить, почему проверка была пропущена | +| Функция | Эффект | Используйте когда | +|----------|--------|----------| +| `allow(message)` | Разрешить и отправить контекст Claude | Подтвердить прохождение проверки или объяснить причину пропуска | -Случаи использования: -- **Подтверждения статуса:** `allow("All CI checks passed.")` — сообщает Claude, что всё в порядке -- **Объяснения отказоустойчивости:** `allow("GitHub CLI not installed, skipping CI check.")` — сообщает Claude, почему проверка была пропущена, чтобы у него был полный контекст -- **Множественные сообщения накапливаются:** если несколько политик возвращают `allow(message)`, все сообщения объединяются с переводами строк и доставляются вместе +Варианты использования: +- **Подтверждения статуса:** `allow("All CI checks passed.")` — сообщает Claude, что всё хорошо +- **Объяснения открытого отказа:** `allow("GitHub CLI not installed, skipping CI check.")` — сообщает Claude причину пропуска проверки, чтобы он имел полный контекст +- **Несколько сообщений накапливаются:** если несколько политик возвращают `allow(message)`, все сообщения объединяются с новыми строками и доставляются вместе ```js customPolicies.add({ @@ -158,48 +163,48 @@ customPolicies.add({ ### Поля `PolicyContext` | Поле | Тип | Описание | -|------|-----|---------| +|-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | Инструмент, который вызывается (например, `"Bash"`, `"Write"`, `"Read"`) | -| `toolInput` | `Record \| undefined` | Параметры входа инструмента | -| `payload` | `Record` | Полный необработанный полезный груз событий от Claude Code | +| `toolName` | `string \| undefined` | Инструмент, который вызывается (например `"Bash"`, `"Write"`, `"Read"`) | +| `toolInput` | `Record \| undefined` | Входные параметры инструмента | +| `payload` | `Record` | Полный исходный пакет события от Claude Code | | `session` | `SessionMetadata \| undefined` | Контекст сессии (см. ниже) | ### Поля `SessionMetadata` | Поле | Тип | Описание | -|------|-----|---------| +|-------|------|-------------| | `sessionId` | `string` | Идентификатор сессии Claude Code | | `cwd` | `string` | Рабочий каталог сессии Claude Code | -| `transcriptPath` | `string` | Путь к файлу расшифровки JSONL сессии | +| `transcriptPath` | `string` | Путь к файлу стенограммы JSONL сессии | ### Типы событий -| Событие | Когда оно срабатывает | Содержимое `toolInput` | -|--------|----------------------|----------------------| -| `PreToolUse` | Перед запуском инструмента Claude | Входные данные инструмента (например, `{ command: "..." }` для Bash) | -| `PostToolUse` | После завершения инструмента | Входные данные инструмента + `tool_result` (выходные данные) | -| `Notification` | Когда Claude отправляет уведомление | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — перехваты всегда должны возвращать `allow()`, они не могут блокировать уведомления | +| Событие | Когда срабатывает | Содержимое `toolInput` | +|--------|--------------|----------------------| +| `PreToolUse` | До запуска инструмента Claude | Входные данные инструмента (например `{ command: "..." }` для Bash) | +| `PostToolUse` | После завершения инструмента | Входные данные инструмента + `tool_result` (вывод) | +| `Notification` | Когда Claude отправляет уведомление | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - ловушки должны всегда возвращать `allow()`, они не могут блокировать уведомления | | `Stop` | Когда сессия Claude завершается | Пусто | --- ## Порядок оценки -Политики оцениваются в этом порядке: +Политики оцениваются в следующем порядке: 1. Встроенные политики (в порядке определения) 2. Явные пользовательские политики из `customPoliciesPath` (в порядке `.add()`) -3. Политики соглашений из проектной `.failproofai/policies/` (файлы в алфавитном порядке, `.add()` порядок внутри) -4. Политики соглашений из пользовательской `~/.failproofai/policies/` (файлы в алфавитном порядке, `.add()` порядок внутри) +3. Политики проектных соглашений из `.failproofai/policies/` (файлы в алфавитном порядке, `.add()` внутри) +4. Политики пользовательских соглашений из `~/.failproofai/policies/` (файлы в алфавитном порядке, `.add()` внутри) -Первое `deny` прекращает все последующие политики. Все сообщения `instruct` накапливаются и доставляются вместе. +Первый `deny` прерывает все последующие политики. Все сообщения `instruct` накапливаются и доставляются вместе. --- -## Переходящие импорты +## Переходные импорты Файлы пользовательских политик могут импортировать локальные модули, используя относительные пути: @@ -218,7 +223,7 @@ customPolicies.add({ }); ``` -Все относительные импорты, доступные из файла записи, разрешены. Это реализуется путём переписывания импортов `from "failproofai"` на фактический путь dist и создания временных файлов `.mjs` для обеспечения совместимости ESM. +Все относительные импорты, доступные из входного файла, разрешаются. Это реализуется путём переписывания импортов `from "failproofai"` в фактический путь dist и создания временных файлов `.mjs` для обеспечения совместимости ESM. --- @@ -231,33 +236,33 @@ customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Only fires when the session ends - // ctx.session.transcriptPath contains the full session log + // Срабатывает только при завершении сессии + // ctx.session.transcriptPath содержит полный журнал сессии return allow(); }, }); ``` -Опустите `match` полностью, чтобы срабатывать для каждого типа события. +Опустите `match` полностью, чтобы срабатывать на все типы событий. --- ## Обработка ошибок и режимы отказа -Пользовательские политики являются **отказоустойчивыми**: ошибки никогда не блокируют встроенные политики и не сбивают обработчик перехвата. +Пользовательские политики — это **открытый отказ**: ошибки никогда не блокируют встроенные политики и не вызывают крах обработчика ловушек. | Отказ | Поведение | -|-------|----------| -| `customPoliciesPath` не установлен | Явные пользовательские политики не запускаются; встроенные и соглашения продолжают нормально работать | -| Файл не найден | Предупреждение записывается в `~/.failproofai/hook.log`; встроенные продолжают работать | -| Ошибка синтаксиса/импорта (явная) | Ошибка записывается в `~/.failproofai/hook.log`; явные пользовательские политики пропускаются | -| Ошибка синтаксиса/импорта (соглашение) | Ошибка записывается; этот файл пропускается, остальные файлы соглашений всё ещё загружаются | -| `fn` выбрасывает во время выполнения | Ошибка записывается; этот перехват трактуется как `allow`; остальные перехваты продолжают работать | -| `fn` занимает больше 10 сек | Истечение времени записывается; трактуется как `allow` | -| Каталог соглашений отсутствует | Политики соглашений не запускаются; нет ошибки | +|---------|----------| +| `customPoliciesPath` не установлен | Нет явных пользовательских политик; встроенные и политики соглашений продолжают нормально работать | +| Файл не найден | Предупреждение записано в `~/.failproofai/hook.log`; встроенные продолжают работать | +| Ошибка синтаксиса/импорта (явная) | Ошибка записана в `~/.failproofai/hook.log`; явные пользовательские политики пропущены | +| Ошибка синтаксиса/импорта (соглашение) | Ошибка записана; этот файл пропущен, остальные файлы соглашений загружаются | +| `fn` выбрасывает ошибку во время выполнения | Ошибка записана; эта ловушка обрабатывается как `allow`; остальные ловушки продолжают работу | +| `fn` длится более 10 сек | Таймаут записан; обрабатывается как `allow` | +| Каталог соглашений отсутствует | Нет политик соглашений; нет ошибки | -Для отладки ошибок пользовательских политик наблюдайте за файлом журнала: +Для отладки ошибок пользовательских политик просмотрите файл журнала: ```bash tail -f ~/.failproofai/hook.log @@ -272,7 +277,7 @@ tail -f ~/.failproofai/hook.log // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// Prevent agent from writing to secrets/ directory +// Предотвратить запись агента в каталог secrets/ customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -285,7 +290,7 @@ customPolicies.add({ }, }); -// Keep the agent on track: verify tests before committing +// Удерживайте агента на пути: проверьте тесты перед коммитом customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +305,7 @@ customPolicies.add({ }, }); -// Prevent unplanned dependency changes during freeze +// Предотвратить незапланированные изменения зависимостей во время заморозки customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -326,13 +331,13 @@ export { customPolicies }; Каталог `examples/` содержит готовые к использованию файлы политик: | Файл | Содержимое | -|------|-----------| +|------|----------| | `examples/policies-basic.js` | Пять начальных политик, охватывающих распространённые режимы отказа агента | -| `examples/policies-advanced/index.js` | Продвинутые паттерны: переходящие импорты, асинхронные вызовы, очистка выходных данных и перехваты завершения сессии | -| `examples/convention-policies/security-policies.mjs` | Политики безопасности на основе соглашений (блокировка записей .env, предотвращение переписывания истории git) | -| `examples/convention-policies/workflow-policies.mjs` | Политики рабочего процесса на основе соглашений (напоминания о тестах, аудит записей файлов) | +| `examples/policies-advanced/index.js` | Продвинутые шаблоны: переходные импорты, асинхронные вызовы, очистка вывода и ловушки конца сессии | +| `examples/convention-policies/security-policies.mjs` | Политики безопасности на основе соглашений (блокировка записи .env, предотвращение переписи истории git) | +| `examples/convention-policies/workflow-policies.mjs` | Политики рабочих процессов на основе соглашений (напоминания о тестах, аудит записей файлов) | -### Использование примеров явного файла +### Использование примеров явных файлов ```bash failproofai policies --install --custom ./examples/policies-basic.js @@ -341,13 +346,13 @@ failproofai policies --install --custom ./examples/policies-basic.js ### Использование примеров на основе соглашений ```bash -# Copy to project level +# Скопируйте на уровень проекта mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# Or copy to user level +# Или скопируйте на пользовательский уровень mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -Команда установки не требуется — файлы автоматически подбираются при следующем событии перехвата. \ No newline at end of file +Команда установки не требуется — файлы будут загружены автоматически при следующем событии-ловушке. \ No newline at end of file diff --git a/docs/ru/dashboard.mdx b/docs/ru/dashboard.mdx index 4009c657..ef106443 100644 --- a/docs/ru/dashboard.mdx +++ b/docs/ru/dashboard.mdx @@ -1,10 +1,11 @@ --- +--- title: Панель управления -description: "Мониторьте сеансы агентов, проверяйте вызовы инструментов и управляйте политиками" +description: "Мониторьте сеансы агентов, просматривайте вызовы инструментов и управляйте политиками" icon: chart-line --- -Панель управления failproofai — это локальное веб-приложение для мониторинга сеансов вашего AI-агента и управления политиками. Узнайте, что делали ваши агенты, пока вас не было. +Панель управления failproofai — это локальное веб-приложение для мониторинга сеансов ваших AI-агентов и управления политиками. Посмотрите, что делали ваши агенты, пока вас не было. --- @@ -16,7 +17,7 @@ failproofai Открывается по адресу `http://localhost:8020`. -Панель управления считывает данные локального проекта, сеанса и конфигурации failproofai непосредственно из файловой системы. Дополнительные функции с аутентификацией, такие как напоминания об аудите и приглашения, отправляют информацию, необходимую для этих запросов (включая адреса электронной почты), на удалённые API. +Панель управления считывает данные локального проекта, сеанса и конфигурации failproofai непосредственно из файловой системы. Дополнительные функции с аутентификацией, такие как напоминания об аудитах и приглашения, отправляют информацию, необходимую для этих запросов (включая адреса электронной почты), в удаленные API. --- @@ -24,81 +25,83 @@ failproofai ### Проекты -Отображает все проекты Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity и Goose, найденные на вашем компьютере. Проекты Claude обнаруживаются из `~/.claude/projects/` (или пути, установленного через `CLAUDE_PROJECTS_PATH`); проекты Codex обнаруживаются путём сканирования всех транскриптов в `~/.codex/sessions///
/*.jsonl` и группировки по `cwd`, записанному в первой записи сеанса; проекты Copilot CLI обнаруживаются путём сканирования каждого `~/.copilot/session-state//workspace.yaml` (настраивается через `COPILOT_HOME`) и группировки по полю `cwd`; проекты Cursor Agent обнаруживаются путём сканирования метаданных для каждого сеанса в `~/.cursor/agent-sessions//` (настраивается через `CURSOR_HOME`, с `conversations/` и `sessions/` в качестве резервных вариантов) в поиске скаляра `cwd` в `meta.json` / `session.json` / `workspace.yaml`; проекты OpenCode обнаруживаются путём запроса к его SQLite БД в `~/.local/share/opencode/opencode.db` через `opencode db --format json` (мы читаем таблицы `session` и `project` и группируем по `project_id`); проекты Pi обнаруживаются путём сканирования транскриптов JSONL для каждого сеанса в `~/.pi/agent/sessions//_.jsonl` (настраивается через `PI_SESSIONS_DIR`) и извлечения `cwd` из первой записи каждого сеанса; сеансы шлюза Hermes считываются непосредственно из его SQLite хранилища в `~/.hermes/state.db` (настраивается через `HERMES_DB_PATH`) и группируются в проекты `hermes-` по `source` (Slack/Telegram/cli/cron — сеансы шлюза не имеют cwd); сеансы шлюза OpenClaw считываются из `~/.openclaw/agents//sessions/*.jsonl` и группируются в проекты `openclaw-` (также без cwd); проекты Factory Droid обнаруживаются из транскриптов JSONL в `~/.factory/sessions//*.jsonl` и группируются по cwd; проекты Devin из её SQLite БД в `~/.local/share/devin/cli/sessions.db` (группируются по `working_directory` каждого сеанса); проекты Antigravity из транскриптов JSONL в `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` и группируются по cwd; и проекты Goose из её SQLite БД в `~/.local/share/goose/sessions/sessions.db` (группируются по `working_dir` каждого сеанса). Проект, используемый несколькими CLI, отображается в виде одной строки со всеми соответствующими бейджами. Используйте выпадающее меню **CLI** над таблицей для фильтрации по конкретному агенту CLI; URL сохраняет ваш выбор как `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +Список всех проектов Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity и Goose, найденные на вашем компьютере. Проекты Claude обнаруживаются из `~/.claude/projects/` (или из пути, установленного через `CLAUDE_PROJECTS_PATH`); проекты Codex обнаруживаются путем сканирования каждой транскрипции в `~/.codex/sessions///
/*.jsonl` и группировки по `cwd`, записанному в первой записи каждого сеанса; проекты Copilot CLI обнаруживаются путем сканирования каждого `~/.copilot/session-state//workspace.yaml` (настраивается через `COPILOT_HOME`) и группировки по полю `cwd`; проекты Cursor Agent обнаруживаются путем сканирования метаданных для каждого сеанса в `~/.cursor/agent-sessions//` (настраивается через `CURSOR_HOME`, с `conversations/` и `sessions/` как резервные варианты) для поиска скаляра `cwd` в `meta.json` / `session.json` / `workspace.yaml`; проекты OpenCode обнаруживаются путем запроса его БД SQLite в `~/.local/share/opencode/opencode.db` через `opencode db --format json` (мы читаем таблицы `session` и `project` и группируем по `project_id`); проекты Pi обнаруживаются путем сканирования транскрипций JSONL для каждого сеанса в `~/.pi/agent/sessions//_.jsonl` (настраивается через `PI_SESSIONS_DIR`) и извлечения `cwd` из первой записи каждого сеанса; сеансы шлюза Hermes считываются непосредственно из хранилища SQLite каждого профиля — `~/.hermes/state.db` плюс `~/.hermes/profiles//state.db` (переопределяется через `HERMES_HOME` или `HERMES_DB_PATH` для одной базы данных) — и группируются в проекты `hermes--` по профилю и `source` (Slack/Telegram/cli/cron — сеансы шлюза не имеют cwd); сеансы шлюза OpenClaw считываются из `~/.openclaw/agents//sessions/*.jsonl` и группируются в проекты `openclaw--` по агенту и каналу (также без cwd); проекты Factory Droid обнаруживаются из транскрипций JSONL в `~/.factory/sessions//*.jsonl` и группируются по cwd; проекты Devin из его БД SQLite в `~/.local/share/devin/cli/sessions.db` (группируются по `working_directory` каждого сеанса); проекты Antigravity из транскрипций JSONL в `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` и группируются по cwd; проекты Goose из его БД SQLite в `~/.local/share/goose/sessions/sessions.db` (группируются по `working_dir` каждого сеанса). Проект, используемый несколькими CLI, отображается как одна строка со всеми соответствующими значками. Используйте раскрывающееся меню **CLI** над таблицей для фильтрации по определенному агенту CLI; URL сохраняет вашу выборку как `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. + +Hermes и OpenClaw имеют область видимости пользователя и не имеют рабочего каталога для группировки, поэтому они отображаются как **сворачиваемое дерево папок** — профиль (или агент) на верхнем уровне, его каналы ниже — в то время как каждый CLI на основе cwd остается в плоском представлении. Строки папок объединяют количество сеансов и самую последнюю активность всего содержимого, свернутые папки запоминаются между визитами, а поиск по ключевому слову разворачивает все совпадения. Каждый проект показывает: - Имя проекта (производное от пути к папке) -- Бейдж CLI — `Claude Code` (оранжевый), `OpenAI Codex` (фиолетовый), `GitHub Copilot` (синий), `Cursor Agent` (изумрудный), `OpenCode` (янтарный), `Pi` (розовый) и/или `Hermes` (индиго) -- Дата самой свежей активности сеанса +- Значок CLI — `Claude Code` (оранжевый), `OpenAI Codex` (фиолетовый), `GitHub Copilot` (синий), `Cursor Agent` (изумрудный), `OpenCode` (янтарный), `Pi` (розовый) и/или `Hermes` (индиго) +- Дата самой последней активности сеанса Нажмите на проект, чтобы увидеть его сеансы. ### Сеансы -Отображает все сеансы в проекте. Каждый сеанс показывает: +Список всех сеансов в проекте. Каждый сеанс показывает: - ID сеанса -- Временные метки начала и окончания +- Начальные и конечные временные метки - Количество вызовов инструментов -- Счётчик активности хука (политики, которые сработали) +- Количество активностей хука (политики, которые были срабатывали) -Используйте фильтр диапазона дат и поиск по ID сеанса для сужения списка. Сеансы разбиты на страницы. +Используйте фильтр диапазона дат и поиск по ID сеанса для сужения списка. Сеансы разбиваются на страницы. -Нажмите на сеанс, чтобы открыть просмотр сеанса. +Нажмите на сеанс, чтобы открыть средство просмотра сеанса. -### Просмотр сеанса +### Средство просмотра сеанса -Просмотр сеанса ответит на ключевой вопрос для автономных агентов: что сделал агент и остался ли он в курсе? Бейдж CLI рядом с заголовком указывает, является ли сеанс транскриптом Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity или Goose. Он показывает временную шкалу всего, что произошло в сеансе: +Средство просмотра сеанса отвечает на ключевой вопрос для автономных агентов: что делал агент и остался ли он в курсе? Значок CLI рядом с заголовком указывает, является ли сеанс транскрипцией Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity или Goose. Он показывает временную шкалу всего, что произошло в сеансе: -- **Сообщения** - текстовые ответы Claude и подсказки пользователя -- **Вызовы инструментов** - каждый инструмент, который вызвал Claude, с его вводом и выводом -- **Активность политики** - для каждого вызова инструмента, какие политики сработали и какое решение они вернули +- **Сообщения** — текстовые ответы Claude и подсказки пользователя +- **Вызовы инструментов** — каждый инструмент, который Claude вызвал, с его входными и выходными данными +- **Активность политики** — для каждого вызова инструмента, какие политики были срабатывали и какое решение они вернули -Панель статистики в верхней части показывает продолжительность сеанса, общее количество вызовов инструментов и сводку решений хука (количество allow / deny / instruct). +Статистическая полоса вверху показывает продолжительность сеанса, общее количество вызовов инструментов и сводку решений по хукам (количество allow / deny / instruct). -Нажмите кнопку **Download Logs**, чтобы экспортировать сеанс. Для сеансов Claude Code, Codex, Copilot, Cursor и Pi вы получаете исходный транскрипт JSONL на диске байт-в-байт; для OpenCode (чьи сеансы находятся в SQLite, а не на диске) вы получаете JSON-документ, отражающий базовые таблицы `session` / `messages` / `parts`. +Нажмите кнопку **Download Logs**, чтобы экспортировать сеанс. Для сеансов Claude Code, Codex, Copilot, Cursor и Pi вы получаете исходную на диске транскрипцию JSONL побайтово; для OpenCode (чьи сеансы находятся в SQLite, а не на диске) вы получаете документ JSON, отражающий базовые таблицы `session` / `messages` / `parts`. ### Аудит -Доклад, ориентированный на личность, о том, как ваш агент на самом деле вёл себя в прошлых сеансах. Запускает одно и то же сканирование, что и CLI `failproofai audit`, но отображает его как однооэкранный акционный плакат + четыре раздела ниже сгиба: +Отчет, ориентированный на личность, о том, как на самом деле вел себя ваш агент в прошлых сеансах. Запускает то же сканирование, что и CLI `failproofai audit`, но отображает его как единую страницу, которую можно поделить + четыре раздела ниже сгиба: -1. **Плакат** — заполняет первый просмотр. Независимый регион PNG-захвата с логотипом failproof_ai + метка аудита · индекс архетипа (`№ NN из 08`) + дата аудита · числовой балл (0–100) + таблетка процентиля (`top 15%`) · имя архетипа (один из `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + полоса с 3 ключевыми словами · строка редкости `// only N% of agents are this archetype` · сигил-плитка 8×8 пиксель · подвал `audit yours → failproof.ai`. Три кнопки обмена находятся сразу за пределами поля захвата: `post your archetype` (намерение X), `share on linkedin`, `download poster`. Захват выполняется через `html-to-image`, поэтому PNG соответствует экранному рендеру пиксель-в-пиксель (пунктирные границы, маска логотипа SVG, градиенты, метрики шрифта — всё сохраняется). -2. **Сильные стороны** — спокойный ✓ список строк поведения, которое ваш агент уже делает правильно, полученный из данных живого аудита (чистый коэффициент вызовов инструментов, без прямых толчков в main, нулевые утечки учётных данных, нулевые штормы повторных попыток) — каждая отображается только когда соответствующая политика имеет чистую историю в окне аудита. -3. **Особенности** — таблица того, что прошло сквозь пальцы, ранжированная по степени важности: `when · what slipped + the policy that would've caught it · severity pill · seen`, где повторяемость читается как `new` (один раз), `N× seen` (2–9 раз) или `recurring` (10+). -4. **Как улучшить** — спокойный список строк, по одному на рекомендуемую политику: имя политики белым, однострочное описание, команда установки + кнопка копирования с правой стороны. Заголовок раздела читается как `enable all N → projected · ` (балл, который вы достигли бы при применении каждого исправления), и его кнопка `[install all]` копирует объединённую команду `failproofai policy add a b c …` для каждой рекомендуемой политики. -5. **Come back better** — две карточки рядом. Слева: установить напоминание (выбор интервала `3d` / `7d` / `14d` / `30d`; сохраняется через `/api/auth/reminder` после аутентификации). Справа: разблокировать привилегии failproof — `invite a friend` открывает модальное окно, которое принимает список адресов электронной почты друзей, разделённые запятыми/пробелами/новыми строками (максимум 10 за отправку), отправляет их на `/api/audit/invite`, которая перенаправляет на `POST /v0/invite` api-сервера. Api-сервер отправляет одно письмо на получателя с адреса `invite@failproof.ai` с копией отправителю и установленным `Reply-To`, поэтому получатель видит, кто его пригласил, а отправитель получает копию в своем почтовом ящике. Анонимные пользователи маршрутизируются сначала через `AuthDialog`, чтобы электронная почта отправителя была известна до отправки приглашений. Выполнение прав и привилегий — это последующее действие. +1. **Постер** — заполняет первый видеоэкран. Самодостаточный регион PNG-захвата с логотипом failproof_ai + метка аудита · индекс архетипа (`№ NN из 08`) + дата аудита · числовой балл (0–100) + таблетка процентиля (`top 15%`) · имя архетипа (один из `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + полоса из 3 ключевых слов · строка редкости `// только N% агентов имеют этот архетип` · плитка сигилы 8×8 пиксель · нижний колонтитул `audit yours → failproof.ai`. Три кнопки совместного использования находятся снаружи от поля захвата: `post your archetype` (намерение X), `share on linkedin`, `download poster`. Захват работает через `html-to-image`, поэтому PNG совпадает с представлением на экране пиксель в пиксель (пунктирные границы, маска логотипа SVG, градиенты, метрики шрифта — все сохраняется). +2. **Сильные стороны** — спокойный список ✓ поведений, которые ваш агент уже выполняет правильно, полученный из данных живого аудита (чистая коэффициент вызовов инструментов, без прямых пушей в основную ветвь, нет утечек учетных данных, нет грозовых переделов) — каждый поверхностный только когда соответствующая политика имеет чистый учет во всем окне аудита. +3. **Особенности** — таблица того, что проскользнуло, ранжированная по серьезности: `когда · что проскользнуло + политика, которая бы это поймала · таблетка серьезности · видно`, где повторение звучит как `new` (один раз), `N× видно` (2–9 раз) или `recurring` (10+). +4. **Как улучшить** — спокойный список, один на предписанную политику: имя политики белым цветом, односторочное описание, команда установки + кнопка копирования с правой стороны. Заголовок раздела читается как `enable all N → projected · ` (балл, который вы достигнете со всеми исправлениями), и его кнопка `[install all]` копирует объединенную команду `failproofai policy add a b c …` для каждой предписанной политики. +5. **Приходите обратно лучше** — две карточки рядом. Слева: установить напоминание (подборка `3d` / `7d` / `14d` / `30d`; сохраняется через `/api/auth/reminder` один раз аутентифицирован). Справа: разблокировать преимущества failproof — `invite a friend` открывает модальное окно, которое принимает разделенный запятыми/пробел/новой строкой список адресов электронной почты друзей (макс. 10 за отправку), POST их в `/api/audit/invite`, что перенаправляется на `POST /v0/invite` API-сервера. API-сервер отправляет одно письмо на получателя от `invite@failproof.ai` с отправителем Cc'd и `Reply-To` установленным, поэтому получатель видит, кто их пригласил, и отправитель получает копию в своем ящике. Анонимные пользователи маршрутизируются через `AuthDialog` в первую очередь, чтобы адрес электронной почты отправителя был известен перед отправкой приглашений. Выполнение прав/преимуществ — это продолжение. -Управляется временем выполнения `failproofai audit` — см. [Audit CLI](/ru/cli/audit) для механизма базового сканирования, поддерживаемых флагов и инвариантов кэша для каждого транскрипта. Панель управления кэширует последний результат в `~/.failproofai/audit-dashboard.json` (режим `0600`, один слот, новые прогоны перезаписывают) так что повторные посещения происходят мгновенно; **оба кэши (для каждого транскрипта и общий результат) отклоняются при чтении, когда они старше 7 дней**, так что панель управления никогда не молча не служит недельный результат — после TTL `/audit` падает в его пустое состояние и предлагает свежий прогон. Нажимая `[ re-audit now ]` рядом с концом доклада, отправляет POST на `/api/audit/run` с `noCache: true` — повторный аудит обходит кэш для каждого транскрипта и повторно сканирует каждый транскрипт с нуля, а не молча возвращает кэшированный результат — и панель управления опрашивает `/api/audit/status` при 1Hz до завершения прогона; клейкая розовая полоса прогресса прикрепляется к верхней части области просмотра во время прогона с истёкшим таймером, и свежий результат встаёт на место при успехе (без полной перезагрузки страницы; неудачный повторный аудит оставляет предыдущий отчёт в целости). При отказе полоса становится красной с копией, обусловленной `RerunError.kind` (`timeout` / `network` / `post_failed`). Пустое состояние (нет кэша или истёк) и нулевое состояние сеансов (кэш существует, но сканирование не нашло транскриптов) отображаются отдельно. +Управляется `failproofai audit` во время выполнения — см. [Audit CLI](/ru/cli/audit) для базового механизма сканирования, поддерживаемых флагов и инвариантов кэша на транскрипцию. Панель управления кэширует последний результат в `~/.failproofai/audit-dashboard.json` (режим `0600`, один слот, новые запуски перезаписывают), поэтому повторные визиты мгновенны; **как кэш на транскрипцию, так и кэш всего результата отклоняются при чтении один раз они старше 7 дней**, поэтому панель управления никогда не служит молча недельный результат — после TTL `/audit` падает в его пустое состояние и предлагает свежий запуск. Щелчок `[ re-audit now ]` рядом с нижней частью отчета POST `/api/audit/run` с `noCache: true` — переаудит обходит кэш на транскрипцию и повторно сканирует каждую транскрипцию с нуля, а не молча возвращает кэшированный результат — и панель управления опрашивает `/api/audit/status` на 1Hz, пока запуск не завершится; липкая розовая полоса прогресса прикрепляется к верхней части видеоэкрана во время запуска с истекшим таймером, и свежий результат вставляется на месте при успехе (нет полной перезагрузки страницы; неудачный переаудит оставляет предыдущий отчет нетронутым). При отказе полоса становится красной с копией, определенной по `RerunError.kind` (`timeout` / `network` / `post_failed`). Пустое состояние (без кэша или истекшего срока) и состояние нулевых сеансов (кэш существует, но сканирование не обнаружило транскрипций) отображаются отдельно. ### Политики -Двухвкладочная страница для управления политиками и проверки активности. +Двухвкладочная страница для управления политиками и просмотра активности. - - - Мульти-выбор того, какие агенты CLI защищает failproofai с одной панели — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi и Hermes все имеют строку со статусом установки (`Active` / `Detected` / `Inactive`), путём настроек пользовательской области и акцентом с цветом бренда. Установите или снимите флажки для CLI, которые вы хотите, и нажмите `Apply changes`, чтобы установить/удалить различие за один раз. CLI, чей бинарный файл обнаружен в PATH, предварительно проверяются. - - Переключайте отдельные политики с помощью одного щелчка (записывает в `~/.failproofai/policies-config.json` — общие для каждого установленного CLI) - - Разверните политику, чтобы настроить её параметры (для политик, которые поддерживают `policyParams`) + + - Мультиселект, какие CLI агентов failproofai защищает с одной панели — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi и Hermes, все имеют строку со статусом установки (`Active` / `Detected` / `Inactive`), путь к параметрам области видимости пользователя и акцент цвета бренда. Проверьте или снимите флажок CLI, которые вам нужны, и нажмите `Apply changes` для установки/удаления разницы за один шаг. CLI, чьи двоичные файлы обнаруживаются в PATH, предварительно отмечены. + - Переключайте отдельные политики включение/выключение одним щелчком (пишет в `~/.failproofai/policies-config.json` — общее для каждого установленного CLI) + - Разверните политику для настройки ее параметров (для политик, поддерживающих `policyParams`) - Установите пользовательский путь файла политик - - - Полная разбитая на страницы история каждого события хука, которое произошло во всех сеансах - - Фильтровать по решению, типу события, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), названию политики или ID сеанса - - Каждая строка показывает: метку времени, имя политики, решение, бейдж CLI (оранжевый = Claude Code, фиолетовый = OpenAI Codex, синий = GitHub Copilot, изумрудный = Cursor Agent, янтарный = OpenCode, розовый = Pi, индиго = Hermes, сине-зелёный = OpenClaw, розово-красный = Factory Droid, фиолетово-синий = Devin, голубой = Antigravity, лайм = Goose), имя инструмента, ID сеанса и причину решений deny/instruct - - Нажмите на ID сеанса, чтобы открыть его транскрипт — средство просмотра автоматически определяет, какой CLI запустил хук (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) и отображает соответствующий бейдж CLI в заголовке + + - Полная разбитая на страницы история каждого события хука, которое было срабатывало во всех сеансах + - Фильтр по решению, типу события, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), названию политики или ID сеанса + - Каждая строка показывает: временную метку, имя политики, решение, значок CLI (оранжевый = Claude Code, фиолетовый = OpenAI Codex, синий = GitHub Copilot, изумрудный = Cursor Agent, янтарный = OpenCode, розовый = Pi, индиго = Hermes, оттенок = OpenClaw, роза = Factory Droid, фиолетовый = Devin, голубой = Antigravity, лайм = Goose), имя инструмента, ID сеанса и причину решений deny/instruct + - Нажмите на ID сеанса, чтобы открыть его транскрипцию — средство просмотра автоматически обнаруживает, какой CLI срабатил хук (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) и отображает соответствующий значок CLI в заголовке --- -## Авто-обновление +## Автоматическое обновление -Панель управления имеет переключатель авто-обновления в верхней навигации. Если это включено, текущая страница обновляется периодически, чтобы показывать новые сеансы и активность политик при их появлении. Эссенциально для мониторинга долгих сеансов автономного агента. +Панель управления имеет переключатель автоматического обновления в верхней навигации. При включении текущая страница периодически обновляется, чтобы показывать новые сеансы и активность политики по мере их появления. Необходимо для мониторинга долгоживущих сеансов автономных агентов. --- ## Отключение страниц -Если вам нужны только некоторые части панели управления, установите `FAILPROOFAI_DISABLE_PAGES` в разделённый запятыми список имён страниц: +Если вам нужны только некоторые части панели управления, установите `FAILPROOFAI_DISABLE_PAGES` на разделенный запятыми список имен страниц: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -110,7 +113,7 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## Настройка пути к проектам -По умолчанию панель управления читает из стандартного каталога проектов Claude Code. Переопределите его для пользовательских настроек: +По умолчанию панель управления читает из стандартного каталога проектов Claude Code. Переопределите его для пользовательских конфигураций: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,30 +123,30 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## Доступ с хоста, отличного от localhost -При запуске панели управления в **режиме разработки** (`npm run dev`) и доступе к ней с имени хоста, отличного от `localhost` - например, пользовательского домена, удалённого IP или туннелированного URL - вы можете увидеть предупреждение типа: +При запуске панели управления в **режиме разработки** (`npm run dev`) и доступе к ней с имени хоста, отличного от `localhost` — например, пользовательского домена, удаленного IP или туннелированного URL — вы можете увидеть предупреждение типа: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Это Next.js блокирует кросс-источник доступ к своему вебсокету HMR (горячая перезагрузка модулей), который является функцией только для разработки. Чтобы разрешить ваш хост, используйте флаг `--allowed-origins`: +Это Next.js, блокирующий кросс-источниковый доступ к его вебсокету HMR (горячая перезагрузка модулей), которая является функцией только для разработки. Чтобы разрешить ваш хост, используйте флаг `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -Для нескольких хостов или IP передайте разделённый запятыми список: +Для нескольких хостов или IP-адресов передайте разделенный запятыми список: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -Вы также можете установить переменную окружения `FAILPROOFAI_ALLOWED_DEV_ORIGINS` вместо этого: +Вы также можете установить переменную окружения `FAILPROOFAI_ALLOWED_DEV_ORIGINS`: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Это применяется только к режиму разработки. При запуске `failproofai` (режим производства) нет вебсокета HMR и нет проблемы кросс-источник ресурса разработки. +Это применяется только в режиме разработки. При запуске `failproofai` (режим производства) нет вебсокета HMR и нет проблемы с кросс-источниковым ресурсом разработки. \ No newline at end of file diff --git a/docs/tr/configuration.mdx b/docs/tr/configuration.mdx index e426bd8a..b4908564 100644 --- a/docs/tr/configuration.mdx +++ b/docs/tr/configuration.mdx @@ -1,10 +1,10 @@ --- title: Yapılandırma -description: "Yapılandırma dosyası formatı, üç kapsamlı sistem ve birleştirme kuralları" +description: "Yapılandırma dosyası formatı, üç kapsam sistemi ve birleştirme kuralları" icon: gear --- -failproofai, hangi politikaların aktif olduğunu, nasıl davrandıklarını ve özel politikaların nereden yüklendiğini kontrol etmek için JSON yapılandırma dosyalarını kullanır. Yapılandırma, ekibinizle paylaşmak için tasarlanmıştır - bunu repo'nuza kaydedin ve her geliştirici aynı ajan güvenlik ağını alır. +failproofai, hangi politikaların aktif olduğunu, nasıl davrandıklarını ve özel politikaların nereden yüklendiğini kontrol etmek için JSON yapılandırma dosyalarını kullanır. Yapılandırma, takımınızla paylaşmak için tasarlanmıştır - deponuza işleyin ve her geliştirici aynı ajan güvenlik ağına sahip olur. --- @@ -13,45 +13,47 @@ failproofai, hangi politikaların aktif olduğunu, nasıl davrandıklarını ve Üç yapılandırma kapsamı vardır ve öncelik sırasına göre değerlendirilir: | Kapsam | Dosya yolu | Amaç | -|--------|-----------|------| -| **proje** | `.failproofai/policies-config.json` | Her repo için ayarlar, sürüm kontrolüne kaydedilir | -| **yerel** | `.failproofai/policies-config.local.json` | Kişisel her repo geçersiz kılmaları, gitignore'da | -| **genel** | `~/.failproofai/policies-config.json` | Tüm projeler arasında kullanıcı düzeyinde varsayılanlar | +|-------|-----------|---------| +| **project** | `.failproofai/policies-config.json` | Depo başına ayarlar, sürüm kontrolüne işlenir | +| **local** | `.failproofai/policies-config.local.json` | Kişisel depo başına geçersiz kılmalar, gitignored | +| **global** | `~/.failproofai/policies-config.json` | Tüm projeler arasında kullanıcı düzeyinde varsayılanlar | -failproofai bir hook olayı aldığında, mevcut çalışma dizini için mevcut olan üç dosyanın tümünü yükler ve birleştirir. +failproofai bir hook olayı aldığında, mevcut çalışma dizini için var olan üç dosyayı da yükler ve birleştirir. ### Birleştirme kuralları -**`enabledPolicies`** - üç kapsamın tümünün birleşimi. Herhangi bir seviyede etkinleştirilen bir politika etkindir. +**`enabledPolicies`** - üç kapsamın birleşimi. Herhangi bir düzeyde etkinleştirilen bir politika etkindir. ```text -proje: ["block-sudo"] -yerel: ["block-rm-rf"] -genel: ["block-sudo", "sanitize-api-keys"] +project: ["block-sudo"] +local: ["block-rm-rf"] +global: ["block-sudo", "sanitize-api-keys"] -çözüm: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← yinelenenden arındırılmış birleşim +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← yinelenenden arındırılmış birleşim ``` -**`policyParams`** - belirli bir politika için parametreleri tanımlayan ilk kapsam tamamen kazanır. Bir politikanın parametreleri içindeki değerlerin derin birleştirilmesi yoktur. +**`policyParams`** - belirli bir politika için parametreleri tanımlayan ilk kapsam tamamen kazanır. Bir politikanın parametreleri içinde derin birleştirme yoktur. ```text -proje: block-sudo → { allowPatterns: ["sudo apt-get update"] } -genel: block-sudo → { allowPatterns: ["sudo systemctl status"] } +project: block-sudo → { allowPatterns: ["sudo apt-get update"] } +global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -çözüm: { allowPatterns: ["sudo apt-get update"] } ← proje kazanır, genel yok sayılır +resolved: { allowPatterns: ["sudo apt-get update"] } ← project kazanır, global yoksayılır ``` ```text -proje: (block-sudo girişi yok) -yerel: (block-sudo girişi yok) -genel: block-sudo → { allowPatterns: ["sudo systemctl status"] } +project: (block-sudo girişi yok) +local: (block-sudo girişi yok) +global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -çözüm: { allowPatterns: ["sudo systemctl status"] } ← genel'e düşer +resolved: { allowPatterns: ["sudo systemctl status"] } ← global'a düşer ``` -**`customPoliciesPath`** - bunu tanımlayan ilk kapsam kazanır. +**`customPoliciesPaths` / `customPoliciesPath`** - her iki formu da tanımlayan ilk kapsam kazanır. -**`llm`** - bunu tanımlayan ilk kapsam kazanır. +**`disabledCustomPolicies`** - tüm kapsamlar arasında birleşim. Pano, panodan bir bireysel politikayı kapatırken buraya kaynak-nitelikli ID yazar. Listelenmemiş politikalar varsayılan olarak etkindir; kimlikler kaynak dosyayı içerir, böylece birden çok dosyadaki aynı adlı politikalar bağımsız olarak kontrol edilebilir. + +**`llm`** - ilk kapsam kazanır. --- @@ -96,39 +98,39 @@ genel: block-sudo → { allowPatterns: ["sudo systemctl status"] } --- -## Alan referansı +## Alan başvurusu ### `enabledPolicies` Tür: `string[]` -Etkinleştirilecek politika adlarının listesi. Adlar, `failproofai policies` tarafından gösterilen politika tanımlayıcılarıyla tam olarak eşleşmelidir. Tam liste için [Yerleşik Politikalar](/tr/built-in-policies) bölümüne bakın. +Etkinleştirilecek politika adlarının listesi. Adlar, `failproofai policies` tarafından gösterilen politika tanımlayıcılarıyla tam olarak eşleşmelidir. Tam liste için [Yerleşik Politikalar](/tr/built-in-policies) sayfasına bakın. -`enabledPolicies` içinde olmayan politikalar, `policyParams` içinde girdileri olsa bile etkindir değildir. +`enabledPolicies` içinde olmayan politikalar, `policyParams` içinde girişleri olsa bile etkin değildir. ### `policyParams` Tür: `Record>` -Politikaya özgü parametre geçersiz kılmaları. Dış anahtar politika adıdır; iç anahtarlar politikaya özgüdür. Her politika, [Yerleşik Politikalar](/tr/built-in-policies) içinde mevcut parametrelerini belgelendirmektedir. +Politika başına parametre geçersiz kılmaları. Dış anahtar politika adıdır; iç anahtarlar politikaya özgüdür. Her politika, [Yerleşik Politikalar](/tr/built-in-policies) sayfasında mevcut parametrelerini belirtir. -Bir politikanın parametreleri varsa ancak siz bunları belirtmezseniz, politikanın yerleşik varsayılanları kullanılır. `policyParams` hiç yapılandırmayan kullanıcılar önceki sürümlerle özdeş davranış alır. +Bir politikanın parametreleri varsa ancak bunları belirtmezseniz, politikanın yerleşik varsayılanları kullanılır. `policyParams` yapılandırmayan kullanıcılar önceki sürümlerle özdeş davranış alır. -Bir politikanın params bloğu içindeki bilinmeyen anahtarlar hook çalıştırırken sessizce yok sayılır ancak `failproofai policies` çalıştırdığınızda uyarı olarak işaretlenir. +Bir politikanın parametreler bloğunda bilinmeyen anahtarlar hook tetiklendiğinde sessizce yoksayılır ancak `failproofai policies` çalıştırırken uyarı olarak işaretlenir. -#### `hint` (çapraz kesme) +#### `hint` (kesişen) Tür: `string` (isteğe bağlı) -Bir politika `deny` veya `instruct` döndürdüğünde nedene eklenen mesaj. Politikanın kendisini değiştirmeden Claude'a uygulanabilir rehberlik vermek için kullanın. +Bir politika `deny` veya `instruct` döndürdüğünde nedene eklenen bir ileti. Politikanın kendisini değiştirmeden Claude'a işlem yapılabilir rehberlik sağlamak için kullanın. -Herhangi bir politika türüyle çalışır — yerleşik, özel (`custom/`), proje kuralı (`.failproofai-project/`) veya kullanıcı kuralı (`.failproofai-user/`). +Herhangi bir politika türü ile çalışır — yerleşik, özel (`custom/`), proje kuralı (`.failproofai-project/`) veya kullanıcı kuralı (`.failproofai-user/`). ```json { "policyParams": { "block-force-push": { - "hint": "Bunun yerine yeni bir dal oluşturmayı deneyin." + "hint": "Bunun yerine yeni bir şube oluşturmayı deneyin." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], @@ -141,34 +143,34 @@ Herhangi bir politika türüyle çalışır — yerleşik, özel (`custom/`), pr } ``` -`block-force-push` reddettiğinde, Claude şunu görür: *"Zorla itme engellendi. Bunun yerine yeni bir dal oluşturmayı deneyin."* +`block-force-push` reddedildiğinde, Claude şunu görür: *"Force-push engellendi. Bunun yerine yeni bir şube oluşturmayı deneyin."* -Dize olmayan değerler ve boş dizeler sessizce yok sayılır. `hint` ayarlanmadıysa, davranış değişmez (geriye dönük uyumlu). +Dize olmayan değerler ve boş dizeler sessizce yoksayılır. `hint` ayarlanmamışsa davranış değişmez (geriye uyumlu). ### `customPoliciesPath` Tür: `string` (mutlak yol) -Özel hook politikaları içeren JavaScript dosyasının yolu. Bu, `failproofai policies --install --custom ` tarafından otomatik olarak ayarlanır (yol saklanmadan önce mutlak olarak çözümlenir). +Özel hook politikalarını içeren JavaScript dosyasının yolu. Bu, `failproofai policies --install --custom ` tarafından otomatik olarak ayarlanır (yol depolanmadan önce mutlak olarak çözümlenir). -Dosya her hook olayında yeni yüklenir - hiçbir önbellek yoktur. Yazma ayrıntıları için [Özel Politikalar](/tr/custom-policies) bölümüne bakın. +Dosya her hook olayında yeniden yüklenir - hiçbir önbelleğe alma yoktur. Yazma ayrıntıları için [Özel Politikalar](/tr/custom-policies) sayfasına bakın. ### Kural tabanlı politikalar -Açık `customPoliciesPath`'e ek olarak, failproofai `.failproofai/policies/` dizinlerinden politika dosyalarını otomatik olarak keşfeder ve yükler: +Açık `customPoliciesPath` yanında, failproofai otomatik olarak `.failproofai/policies/` dizinlerinden politika dosyalarını keşfeder ve yükler: | Düzey | Dizin | Kapsam | -|------|-------|--------| -| Proje | `.failproofai/policies/` | Sürüm kontrolü aracılığıyla ekiple paylaşılır | -| Kullanıcı | `~/.failproofai/policies/` | Kişisel, tüm projelere uygulanır | +|-------|-----------|-------| +| Proje | `.failproofai/policies/` | Sürüm kontrolü aracılığıyla takımla paylaşılır | +| Kullanıcı | `~/.failproofai/policies/` | Kişisel, tüm projeler için geçerli | -**Dosya eşleşmesi:** Yalnızca `*policies.{js,mjs,ts}` ile eşleşen dosyalar yüklenir (örn. `security-policies.mjs`, `workflow-policies.js`). Dizindeki diğer dosyalar yok sayılır. +**Dosya eşleştirmesi:** Yalnızca `*policies.{js,mjs,ts}` ile eşleşen dosyalar yüklenir (örneğin `security-policies.mjs`, `workflow-policies.js`). Dizindeki diğer dosyalar yoksayılır. -**Yapılandırma gerekmez:** Kural politikaları `policies-config.json` içinde giriş gerektirmez. Dosyaları dizine bırakın ve bir sonraki hook olayında seçilirler. +**Yapılandırma gerekmez:** Kural politikaları `policies-config.json` içinde girişleri gerektirmez. Dosyaları dizine bırakın ve sonraki hook olayında alınırlar. -**Birleşim yükleme:** Hem proje hem de kullanıcı kural dizinleri taranır. Her iki seviyedeki tüm eşleşen dosyalar yüklenir (`customPoliciesPath` ilk kapsam kazanır'dan farklı olarak). +**Birleşik yükleme:** Hem proje hem de kullanıcı kural dizinleri taranır. Her iki seviyedeki tüm eşleşen dosyalar yüklenir (ilk kapsam kazanır kullanan `customPoliciesPath` aksine). -Daha fazla ayrıntı ve örnekler için [Özel Politikalar](/tr/custom-policies) bölümüne bakın. +Daha fazla ayrıntı ve örnek için [Özel Politikalar](/tr/custom-policies) sayfasına bakın. ### `llm` @@ -187,21 +189,26 @@ AI çağrıları yapan politikalar için LLM istemci yapılandırması. Çoğu k --- -## CLI'dan yapılandırma yönetimi +## CLI'dan yapılandırmayı yönetme -`policies --install` ve `policies --uninstall` komutları, ajan CLI'nizin hook ayarları dosyasına (hook giriş noktaları) yazarken `policies-config.json`, doğrudan yönettiğiniz dosyadır. İkisi ayrıdır: +`policies --install` ve `policies --uninstall` komutları, ajan CLI'nizin hook ayarları dosyasına yazarken (hook giriş noktaları), `policies-config.json` doğrudan yönettiğiniz dosyadır. İkisi ayrıdır: -- **Ajan CLI ayarları** — ajanı her araç kullanımında `failproofai --hook ` çağırması için söyler: - - **Claude Code**: `~/.claude/settings.json` (kullanıcı), `/.claude/settings.json` (proje), `/.claude/settings.local.json` (yerel) - - **OpenAI Codex**: `~/.codex/hooks.json` (kullanıcı), `/.codex/hooks.json` (proje) — Codex yerel kapsamı yok - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (kullanıcı), `/.github/hooks/failproofai.json` (proje) — Copilot yerel kapsamı yok. Hook girdileri Copilot'un OS anahtarlı `bash`/`powershell` komut alanlarını `timeoutSec` ile kullanır; dosya üst düzey `version: 1` işaretçisini taşır. Copilot CLI desteği **beta** durumundadır ve `events.jsonl` kayıt şemasını (halk belgeleri belirtmez) daha fazla gerçek dünya oturumuna karşı doğrularız. - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (kullanıcı), `/.cursor/hooks.json` (proje) — Cursor yerel kapsamı yok. Hook girdileri Claude şeklinde `{type, command, timeout}` formunu kullanır (`bash`/`powershell` bölümü yok) ancak camelCase olay anahtarları (`preToolUse`, `beforeSubmitPrompt`, …) altında depolanır, Cursor'un [hooks şemasına](https://cursor.com/docs/hooks) göre düz dizi halinde; dosya üst düzey `version: 1` işaretçisini taşır. İşleyici, `CURSOR_EVENT_MAP` aracılığıyla camelCase → PascalCase'i kanonikleştirir, böylece mevcut yerleşik politikalar değişmeden çalışır. Cursor Agent desteği **beta** durumundadır ve Cursor'un disk üzerindeki transkripti (açık belgelerde belirtilmez) daha fazla gerçek dünya kurulumuna karşı doğrularız. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (kullanıcı), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (proje) — OpenCode yerel kapsamı yok. Diğer beş CLI'den farklı olarak, OpenCode **harici komut hook sistemi olmaz**: `plugin: []` dizisi aracılığıyla açıkça kaydedilen işlem içi JS/TS eklentilerini yükler (`opencode.json` içinde) (`.opencode/plugins/` dan otomatik keşif opencode v1.14.33'de eklentilerin nasıl yüklendiği **değildir**). Kurulum, ikili failproofai'yi subprocess olarak çağıran ve ikili'nin Claude şekli JSON yanıtını eklenti semantiğine geri çeviren küçük bir oluşturulan eklenti parçacığını bırakır: araç olayı reddi için `throw new Error()` (araç çağrısını iptal eder), `instruct` VE `Stop` / `SubagentStop` reddi için `client.session.prompt(...)` (reddi nedeni bir sonraki kullanıcı iletisi olarak gönderir — `session.idle` yalnızca bildirimdir ve bundan atmak no-op olduğundan tek zorla yeniden deneme kanalı), allow için no-op. Parçacık hem araç adlarını (küçük harf → PascalCase, `OPENCODE_TOOL_MAP` aracılığıyla) hem de araç giriş arg anahtarlarını (camelCase → snake_case, `OPENCODE_TOOL_INPUT_MAP` aracılığıyla `Read` / `Write` / `Edit` için, örn. `filePath` → `file_path`, `oldString` → `old_string`) kanonikleştirir, ikili'ye iletmeden önce, yol kontrol yerleşikleri gibi `block-read-outside-cwd`, `block-env-files` ve `block-secrets-write` OpenCode araç çağrılarında değişmeden çalışır. Oturumlar opencode'un SQLite DB'sinde yaşar `~/.local/share/opencode/opencode.db`; pano'nun oturum görüntüleyicisi onları `opencode db --format json` ve `opencode export ` aracılığıyla okur. OpenCode desteği **beta** durumundadır ve sürümler arasında ve daha fazla gerçek dünya oturumlarına karşı davranışı doğrularız. [OpenCode eklentileri belgeleri](https://opencode.ai/docs/plugins/) başlıklı sayfaya bakın. - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (kullanıcı), `/.pi/settings.json` (proje) — Pi yerel kapsamı yok. Pi başlangıçta TypeScript uzantı paketlerini yükler; ayarlar dosyası düz dize dizisidir `{"packages": ["./relative/path", …]}`. failproofai, paketlenmiş `pi-extension/` dizinine işaret eden tek bir packages-dizisi girişi yazar. Uzantı dahili olarak Pi'nin `tool_call` / `user_bash` / `input` / `session_start` olaylarına abone olur ve `failproofai --hook --cli pi`'ye shell çıkışı verir; işleyici underscore_lower_snake_case → PascalCase'i `PI_EVENT_MAP` aracılığıyla kanonikleştirir, böylece mevcut yerleşik politikalar değişmeden çalışır. Araç giriş argları da `PI_TOOL_INPUT_MAP` aracılığıyla kanonikleştirilir (Pi'nin Read / Write / Edit `file_path` yerine `path` iletir; üst düzey anahtarı eşlemek `block-env-files` ve `block-secrets-write`'in çalışmasını sağlar — `block-read-outside-cwd` zaten bir `path` geri dönüşü içeriyordu). Pi desteği **beta** durumundadır, Pi'nin uzantı API'si ve oturum günlüğü düzeni stabilize olurken. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**yalnızca kullanıcı kapsamı** — Hermes proje/yerel yapılandırması yok). Hermes bir Slack/Telegram **ağ geçididir**, bu nedenle bir kurulum her platformdan (Slack/Telegram/cli/cron) araç çağrılarını **ve** iç alt ajanları yakalar. Hook girdileri, Hermes'in snake_case olayları (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`) tarafından anahtarlanan `hooks:` eşlemesi altında `{command, timeout}` çiftidir; işleyici `HERMES_EVENT_MAP` aracılığıyla olayları ve `HERMES_TOOL_MAP` aracılığıyla araç adlarını kanonikleştirir, böylece yerleşik politikalar değişmeden çalışır. Yapılandırma, yorum koruyan YAML `Document` turuna göre düzenlendiğinden işletmenin diğer ayarları kalır ve kurulum, başsız ağ geçidinin (TTY yok) hookları onay istemi olmadan çalıştırması için `hooks_auto_accept: true` ayarlar. Değerlendirici Hermes'in `{"decision":"block","reason"}` stdout sözleşmesini yayar (Hermes çıkış kodlarını yok sayar). **Sınırlamalar:** Hermes'in bir `Stop` olay sonu yoktur, bu nedenle `require-*-before-stop` yerleşikleri bunun için hiçbir zaman çalışmaz (uygulanamaz, kırık değil); `instruct` izin-not-ile-günlüğe-kaydedil'e degrades (ek bağlam kanalı yok); ve çıkış gizli redaksiyonu (`sanitize-*`) shell-hook sözleşmesi üzerinde araç çıkışını yeniden yazamaz. Hermes aynı zamanda çevrimdışı bir **denetim** kaynağıdır — pano, ağ geçidi oturumlarını doğrudan `~/.hermes/state.db`'den okur. -- **`policies-config.json`** — failproofai'ye hangi politikaları değerlendireceğini ve hangi parametrelerle (tüm ajan CLI'ler arasında paylaşılan) söyler +- **Ajan CLI ayarları** — ajana her araç kullanımında `failproofai --hook ` çağırmasını söyler: + - **Claude Code**: `~/.claude/settings.json` (kullanıcı), `/.claude/settings.json` (proje), `/.claude/settings.local.json` (lokal) + - **OpenAI Codex**: `~/.codex/hooks.json` (kullanıcı), `/.codex/hooks.json` (proje) — Codex'in lokal kapsamı yok + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (kullanıcı), `/.github/hooks/failproofai.json` (proje) — Copilot'un lokal kapsamı yok. Hook girişleri, `timeoutSec` ile Copilot'un OS anahtarlı `bash`/`powershell` komut alanlarını kullanır; dosya en üst düzey `version: 1` işaretçisi taşır. Copilot CLI desteği **beta**dir, çünkü `events.jsonl` kayıt şemasını (genel dokümanlar belirtmez) daha fazla gerçek dünya oturumuna karşı doğruluyoruz. **VS Code Copilot Chat ajan modu (Önizleme)**, `.github/hooks/*.json`, `~/.copilot/hooks/*.json` ve `~/.claude/settings.json` (tarafından yönetilen `chat.hookFilesLocations` ayarı) hook konfiglarını aynı Claude şekilli `{hookSpecificOutput:{permissionDecision:"deny",…}}` sözleşmesini kullanarak okur — bu `copilot` entegrasyonunun ve `claude` entegrasyonunun (`~/.claude/settings.json`) zaten yazdığı tam yollar, bu nedenle `failproofai policies --install --cli copilot` (veya `--cli claude`) **VS Code ajan modunda zaten uygulanır** ayrı `vscode` entegrasyonuna gerek olmaksızın (VS Code keşif günlüklerinden canlı olarak doğrulandı). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (kullanıcı), `/.cursor/hooks.json` (proje) — Cursor'un lokal kapsamı yok. Hook girişleri Claude şekilli `{type, command, timeout}` formunu kullanır (`bash`/`powershell` ayrımı yok), ancak Cursor'un [hooks şeması](https://cursor.com/docs/hooks) başına düz bir dizi başına camelCase olay anahtarları (`preToolUse`, `beforeSubmitPrompt`, …) altında depolanır; dosya en üst düzey `version: 1` işaretçisi taşır. İşleyici camelCase → PascalCase'i `CURSOR_EVENT_MAP` aracılığıyla normalleştirir, böylece mevcut yerleşik politikalar değiştirilmeden tetiklenir. Cursor Agent desteği **beta**dir, çünkü Cursor'un diskte yazma transkripsiyonunu (genel dokümanlar belirtmez) daha fazla gerçek dünyadaki kuruluma karşı doğruluyoruz. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (kullanıcı), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (proje) — OpenCode'un lokal kapsamı yok. Diğer beş CLI'dan farklı olarak, OpenCode **harici komut hook sistemi yoktur**: `plugin: []` dizisinde açık olarak kayıtlı işlemde JS/TS eklentilerini yükler (`.opencode/plugins/` saatinden otomatik bulma, OpenCode v1.14.33'te eklentilerin nasıl yüklendiği **değildir**). Kurulum, failproofai ikilisini alt işlem çağıran ve ikilinin Claude şekilli JSON yanıtını eklenti anlamsal biçimine çeviren küçük bir oluşturulan eklenti parçası bırakır: araç olayı reddetmek için `throw new Error()` (araç çağrısını iptal eder), instruct **VE** `Stop` / `SubagentStop` reddetmek için `client.session.prompt(...)` (sonraki kullanıcı iletisi olarak reddetme sebebini gönderir — `session.idle` bildirim yalnızca ve ondan atma bir no-op olduğu için tek zorla yeniden deneme kanalı) ve izin verme için no-op. Parça hem araç adlarını (küçük harf → PascalCase `OPENCODE_TOOL_MAP` aracılığıyla) hem de araç giriş bağımsız değişkeni anahtarlarını (camelCase → snake_case `OPENCODE_TOOL_INPUT_MAP` aracılığıyla `Read` / `Write` / `Edit`, örn. `filePath` → `file_path`, `oldString` → `old_string`) normalleştirir ve yolla kontrol eden yerleşikler olan `block-read-outside-cwd`, `block-env-files` ve `block-secrets-write` OpenCode araç çağrılarında değiştirilmeden tetiklenir. Oturumlar OpenCode'un SQLite veritabanında `~/.local/share/opencode/opencode.db`'de yaşar; panonun oturum görüntüleyicisi onları `opencode db --format json` ve `opencode export ` aracılığıyla okur. OpenCode desteği **beta**dir, çünkü davranışı sürümler arasında ve daha fazla gerçek dünyadaki oturumlara karşı doğruluyoruz. [OpenCode eklentileri dokümanları](https://opencode.ai/docs/plugins/) sayfasına bakın. + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (kullanıcı), `/.pi/settings.json` (proje) — Pi'nin lokal kapsamı yok. Pi başlangıçta TypeScript uzantı paketlerini yükler; ayarlar dosyası düz bir dize dizisi `{"packages": ["./relative/path", …]}`'dir. failproofai, paket dizisine işlenmemiş `pi-extension/` dizinini gösteren tek bir girişi yazar. Uzantı dahili olarak Pi'nin `tool_call` / `user_bash` / `input` / `session_start` olaylarına abone olur ve failproofai `--hook --cli pi`'ye kabuk çıkışı yapar; işleyici alt çizgi_küçük_snake_case → PascalCase'i `PI_EVENT_MAP` aracılığıyla normalleştirir, böylece mevcut yerleşik politikalar değiştirilmeden tetiklenir. Araç giriş bağımsız değişkenleri de `PI_TOOL_INPUT_MAP` aracılığıyla normalleştirilir (Pi'nin Read / Write / Edit, `file_path` yerine `path` sunar; en üst düzey anahtarı eşlemek `block-env-files` ve `block-secrets-write`'ın tetiklenmesini sağlar — `block-read-outside-cwd` zaten `path` geri dönüşüne sahipti). Pi desteği **beta**dir, çünkü Pi'nin uzantı API'si ve oturum günlüğü düzeni stabilize olur. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**yalnızca kullanıcı kapsamı** — Hermes'in proje/lokal yapılandırması yok). Hermes bir Slack/Telegram **ağ geçidi**'dir, bu nedenle bir kurulum her platformdan (Slack/Telegram/cli/cron) araç çağrılarını **ve** dahili alt ajanları engeller. Hook girişleri, Hermes'in snake_case olayları tarafından anahtarlanan bir `hooks:` haritası altında bir `{command, timeout}` çiftidir (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); işleyici `HERMES_EVENT_MAP` ve `HERMES_TOOL_MAP` aracılığıyla olayları ve araç adlarını normalleştirir, böylece yerleşik politikalar değiştirilmeden tetiklenir. Yapılandırma, yorum koruyan YAML `Document` turunu yoluyla düzenlenir, böylece operatörün diğer ayarları hayatta kalır ve kurulum `hooks_auto_accept: true` ayarlar, böylece başsız ağ geçidi (TTY yok) hooks'u bir onay istemesi olmadan çalıştırır. Değerlendirici Hermes'in `{"decision":"block","reason"}` stdout sözleşmesini yayar (Hermes çıkış kodlarını yoksayar). **Sınırlamalar:** Hermes'in turn-end `Stop` olayı yoktur, bu nedenle `require-*-before-stop` yerleşikleri bunun için hiçbir zaman tetiklenmez (uygulanamaz, kırık değil); `instruct` allow-with-logged-note'a düşer (ek bağlam kanalı yok); ve çıktı gizli redaksiyonu (`sanitize-*`) kabuk hook sözleşmesi üzerinde araç çıkışını yeniden yazamaz. Hermes aynı zamanda çevrimdışı **denetim** kaynağıdır — pano, `~/.hermes/state.db`'den doğrudan ağ geçidi oturumlarını okur. + - **OpenClaw (openclaw ağ geçidi)**: `~/.openclaw/openclaw.json` (**yalnızca kullanıcı kapsamı** — OpenClaw'ın proje/lokal yapılandırması yok). Hermes gibi, OpenClaw kendi kendine barındırılan çok kanallı **ağ geçididir**, bu nedenle bir kurulum her kanaldan araç çağrılarını ve dahili alt ajanlarını engeller. Uygulanması OpenClaw'un **işlemde eklenti hooks** (dosya tabanlı dahili hooks yalnızca gözlemdir ve bloke edemez) aracılığıyla çalışır, bu nedenle — OpenCode/Pi gibi — failproofai statik `openclaw-plugin/` paketi gönderir ve failproofai ikilisini asenkron oluşturur ve kararı çevirir. Kurulum, sevk edilen eklenti dizinini `openclaw.json`'in `plugins.load.paths[]` içinde kaydeder ve `plugins.entries.failproofai` altında etkinleştirir (`hooks.allowConversationAccess: true` ile, ham konuşma hooks'u için gerekli). Değerlendirici düz `{permission, reason}` kararını yayar ve parça bunu her hook'un yerel dönüş şekline eşler: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), ve `before_agent_finalize → {action:"revise", reason}` (**Stop** — gerçek bir turn-end kapısı, bu nedenle `require-*-before-stop` yerleşikleri **uygular** OpenClaw'da, Hermes'in aksine). Olaylar ve araç adları `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` aracılığıyla ikilinin tarafından normalleştirilir (`exec→Bash`, `read→Read`, …), böylece yerleşik politikalar değiştirilmeden tetiklenir; parça herhangi bir oluştur/ayrıştır/zaman aşımı hatasında açık başarısız olur. OpenClaw aynı zamanda çevrimdışı **denetim** kaynağıdır — pano, `~/.openclaw/agents//sessions/.jsonl`'de JSONL oturumlarını okur. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (kullanıcı), `/.factory/hooks.json` (proje) — Factory'nin lokal kapsamı yok. droid droid v0.171.0'a karşı canlı olarak doğrulanan iki tuhaflık ile Claude stili harici komut hook sistemini gönderir: (1) olay adları `hooks.json` **en üst düzeyinde** yaşar — **`"hooks"` sarıcı yoktur** (droid bir tanesini reddeder); araç olayları (`PreToolUse`/`PostToolUse`) `"matcher": "*"` taşır, araç olmayan olaylar onu çıkarır. (2) Reddetme hook **çıkış kodu 2 + stderr** tarafından yönelir, JSON kararı değil — değerlendirici'nin `factory` şubesi araç/istem olayları için 2 çıkış verir ve turn-end `Stop` olayında yalnızca `{decision:"block", reason}` (droid'in tek zorla yeniden deneme kanalı). Olaylar zaten PascalCase'dir (olay haritası yok) ve yük Claude snake_case'idir; yalnızca araç adları `FACTORY_TOOL_MAP` aracılığıyla normalleştirilir (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory aynı zamanda çevrimdışı **denetim** kaynağıdır — pano, `~/.factory/sessions//.jsonl`'de diskte JSONL oturumlarını okur. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (kullanıcı), `/.devin/config.json` (proje) — Devin'in lokal kapsamı yok. Devin devin v3000.1.27'ye karşı canlı olarak doğrulanan **saf Claude klonudur**: standart Claude `"hooks"` sarıcı şemasını (yazımlar yapılandırma dosyasının diğer anahtarlarının — `org_id`, `theme_mode`, … — hayatta kalması için koruma sağlar) ve zaten PascalCase olay adlarını (olay haritası yok, işleyici şubesi yok) ve Claude snake_case stdin yükünü (normalleştirme yok) kullanır. Değerlendirici'nin `devin` şubesi **her** olay için çıkış 0'da `{"decision":"block","reason"}` JSON ile reddeder (doğrulandı — bloke `--permission-mode dangerous`'u geçersiz kıldı); turn-end `Stop` olayında sebep, `require-*-before-stop` yerleşiklerinin uygulaması için ZORUNLU EYLEM zorla yeniden deneme ifadesini taşır. Yalnızca araç adları `DEVIN_TOOL_MAP` aracılığıyla normalleştirilir (`exec→Bash`; `tool_input.command` zaten kanonik). Devin aynı zamanda çevrimdışı **denetim** kaynağıdır — pano, `~/.local/share/devin/cli/sessions.db` (her `sessions` satırı gerçek `working_directory` taşır, bu nedenle oturumlar proje cwd'ye göre gruplandırılır Claude gibi) SQLite oturumlarını okur. + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (kullanıcı), `/.agents/hooks.json` (proje) — Antigravity'nin lokal kapsamı yok. Factory/Devin'in aksine, Antigravity agy v1.1.2'ye karşı canlı olarak doğrulanan **kendi** sözleşmesine sahiptir. `hooks.json`, **adlandırılmış hook** şemasını kullanır: en üst düzey anahtar bir hook *adı* (`"failproofai"`) olup, değeri bir olay → işleyiciler haritasıdır — araç olayları (`PreToolUse`/`PostToolUse`) işleyicileri `{matcher:"*", hooks:[…]}`'ye sarmalayır, `PreInvocation`/`Stop` **düz** işleyici dizileridir (diğer adlandırılmış hooks korunur). stdin yükü **camelCase protojson**'dür (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai, politikalar çalışmadan önce snake_case'e normalleştirilir ve `run_command`'nin PascalCase bağımsız değişkenlerini (`CommandLine`/`Cwd`) `ANTIGRAVITY_TOOL_INPUT_MAP` aracılığıyla eşler. Değerlendirici'nin `antigravity` şubesi Antigravity'nin **kendi** yanıt biçimlerini kullanır: `{decision:"deny", reason}` bir araç/istemi (çıkış 0) bloke eder, turn-end `Stop` olayında `{decision:"continue", reason}` döngüyü yeniden girer (bu nedenle `require-*-before-stop` yerleşikleri uygular) ve `{injectSteps:[{ephemeralMessage}]}` `PreInvocation` (→ `UserPromptSubmit`) üzerinde bir talimat enjekte eder. Araç adları `ANTIGRAVITY_TOOL_MAP` aracılığıyla normalleştirilir (`run_command→Bash`, `view_file→Read`, …). Antigravity aynı zamanda çevrimdışı **denetim** kaynağıdır — pano, `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl`'de düz JSONL yazılarını okur (konuşma dizini `conversation_summaries.db` içinde). + - **Goose (kod adı goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (kullanıcı), `/.agents/plugins/failproofai/hooks/hooks.json` (proje) — Goose'un lokal kapsamı yok. Uygulanması Goose'un **hooks** sistemini, çok ajanlar arası **Open Plugins** spesifikasyonunu kullanır: yükleyici sadece `failproofai` eklenti dizinini bırakır ve Goose başlangıçta otomatik olarak keşfeder (bunu `~/.config/goose/config.yaml`'ye kendi kaydedip). `hooks.json`, **`"hooks"` sarıcısı ile** bir Open Plugins şemasını kullanır ve eşleşen her olay üzerinde **çıkarılır** — çıplak `"*"` hiçbir şeyle eşleşen (goose v1.43.0'a karşı canlı olarak doğrulanan) geçersiz bir regex'dir. Olay adları zaten PascalCase'dir (olay haritası yok); stdin yükü `event`/`working_dir` kullanır, işleyici `hook_event_name`/`cwd`'ye normalleştirir. Değerlendirici'nin `goose` şubesi çıkış 0'da `{"decision":"block","reason"}` JSON ile reddeder, **`PreToolUse`** olayında onurlandırılır (goose ≥ v1.37.0'da sevk edilir) — kabuk aracı için **ve temsilci alt ajanlar içinde tetiklenir**, bu nedenle tek yeterli reddetme noktasıdır; diğer herhangi bir hook hatasında başarısız **açılır**. Goose'un **`Stop` olayı yoktur**, bu nedenle `require-*-before-stop` yerleşikleri uygulanmaz (Hermes gibi). Araç adları `GOOSE_TOOL_MAP` aracılığıyla normalleştirilir (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) ve yol anahtarları `GOOSE_TOOL_INPUT_MAP` aracılığıyla (`path`/`source` → `file_path`). Goose aynı zamanda çevrimdışı **denetim** kaynağıdır — pano, `~/.local/share/goose/sessions/sessions.db`'de SQLite oturumlarını okur (her `sessions` satırı gerçek `working_dir` taşır, bu nedenle oturumlar proje cwd'ye göre gruplandırılır Devin gibi; `--no-session` karalama çalışmaları filtrelenir). +- **`policies-config.json`** — failproofai'ye hangi politikaları değerlendirecek ve hangi parametrelerle değerlendirecek söyler (tüm ajan CLI'lar arasında paylaşılan) -Belirli bir ajanı hedeflemek için `--cli claude|codex|copilot|cursor|opencode|pi|hermes` geçin (boşlukla ayrılmış veya herhangi bir altküme için tekrarlanan): +Belirli bir ajana hedef almak için `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` (boşlukla ayrılmış veya herhangi bir alt küme için tekrarlanan) iletir: ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +217,28 @@ failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli hermes --scope user -failproofai policies --install --cli claude codex copilot cursor opencode pi +failproofai policies --install --cli openclaw --scope user +failproofai policies --install --cli factory --scope project +failproofai policies --install --cli devin --scope project +failproofai policies --install --cli antigravity --scope project +failproofai policies --install --cli goose --scope project +failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -`--cli` atlandığında, `failproofai` hangi ajan CLI'lerin yüklendiğini algılar (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`): +`--cli` atlandığında, `failproofai` hangi ajan CLI'larının kurulu olduğunu algılar (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): -- **Bir CLI algılandı** — sor olmadan o CLI'yi otomatik seçer. -- **Etkileşimli bir terminalde birden fazla CLI algılandı** — `Detected (N)` bölümüne gruplandırılmış ok tuşu tek seçim istemi gösterir (algılanan tüm CLI'ler için bir `Tüm N tespit edileni yükle` toplu satırı + her algılanan CLI bireysel olarak) ve her desteklenen CLI'nin yüklenmemiş olan listesini gösteren `Yüklü olmayan (M) · hookları önceden kurma` bölümü (↑↓ taşımak, Enter seçmek, ^C bırakmak için). Kaldırma akışı yalnızca Algılanan bölümü gösterir. -- **Etkileşimli olmayan çalıştırmada birden fazla CLI algılandı** (CI, TTY yok) — sor olmadan tüm algılanan CLI'ler için yükler. -- **Hiçbiri algılanmadı** — `claude`'ye geri döner, PATH'de ajan ikili bulunamadığı konusunda bir uyarı ile; hook komutu hala yazılır, böylece biri yüklendiğin anda etkinleşir. +- **Bir CLI algılandı** — sorguda bulunmadan o CLI'yi otomatik seçer. +- **Birden çok CLI algılandı** etkileşimli terminalde — algılanmış (`N`) bölümü gruplamış (en algılanmış olarak bir toplu satır + her algılanmış CLI ayrı ayrı) ve kurulu olmayan tüm desteklenen CLI'yi (↑↓ hareket etmek, Enter seçmek, ^C çıkmak için) listelemiş olmayan her algılanmış desteklenen CLI'yi (↑↓ taşımak, Enter seçmek, ^C çıkmak için) listelemiş olmayan bir ön kurulum seçeneği olarak listelemiş bir ok tuşu tek seçim istemi gösterir. kaldırma akışı yalnızca Algılanmış bölümü gösterir. +- **Birden çok CLI algılandı** etkileşimli olmayan bir çalışmada (CI, TTY yok) — sorguda bulunmadan algılanmış tüm CLI'ler için kurar. +- **Hiç algılanmadı** — `claude` geçişine döner, PATH'de ajan ikilisi bulunamadığı uyarısı ile; hook komutu hala yazılır, böylece kurduğunuz anda etkinleştirilir. -`policies-config.json`'u doğrudan istediğiniz zaman düzenleyebilirsiniz; değişiklikler bir sonraki hook olayında yeniden başlatma gerekmeden hemen etkili olur. +Herhangi bir zamanda `policies-config.json` dosyasını doğrudan düzenleyebilirsiniz; değişiklikler restart ihtiyacı olmaksızın sonraki hook olayında yürürlüğe girer. --- ## Örnek: takım varsayılanları ile proje düzeyinde yapılandırma -`.failproofai/policies-config.json`'u repo'nuza kaydedin: +`.failproofai/policies-config.json` deponuza işleyin: ```json { @@ -245,4 +257,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi } ``` -Her geliştirici daha sonra, takım arkadaşlarını etkilemeden kişisel geçersiz kılmalar için `.failproofai/policies-config.local.json` (gitignore'da) oluşturabilir. \ No newline at end of file +Her geliştirici daha sonra kişisel geçersiz kılmalar için `.failproofai/policies-config.local.json` (gitignored) oluşturabilir ve takım arkadaşlarını etkilemez. \ No newline at end of file diff --git a/docs/tr/custom-policies.mdx b/docs/tr/custom-policies.mdx index e09c69e8..c6dc6d6b 100644 --- a/docs/tr/custom-policies.mdx +++ b/docs/tr/custom-policies.mdx @@ -1,10 +1,10 @@ --- title: Özel İlkeler -description: "JavaScript'te kendi ilkelerinizi yazın - kuralları uygulayın, kaymaları engelleyin, arızaları tespit edin, dış sistemlerle entegre olun" +description: "JavaScript'te kendi ilkelerinizi yazın - kuralları uygulayın, drift'i önleyin, hataları tespit edin, harici sistemlerle entegre olun" icon: code --- -Özel ilkeler, herhangi bir aracı davranışı için kurallar yazmanızı sağlar: proje kurallarını uygulayın, kaymaları engelleyin, yıkıcı işlemleri kısıtlayın, takılı aracıları tespit edin veya Slack, onay iş akışları ve daha fazlasıyla entegre olun. Yerleşik ilkelerle aynı hook olay sistemini ve `allow`, `deny`, `instruct` kararlarını kullanırlar. +Özel ilkeler, herhangi bir agent davranışı için kurallar yazmanıza olanak tanır: proje kurallarını uygulayın, drift'i önleyin, yıkıcı işlemleri kapıyı kontrol edin, takılı kalan agent'ları tespit edin veya Slack, onay iş akışları ve daha fazlasıyla entegre olun. Yerleşik ilkelerle aynı hook event sistemini ve `allow`, `deny`, `instruct` kararlarını kullanırlar. --- @@ -37,14 +37,14 @@ failproofai policies --install --custom ./my-policies.js --- -## Özel ilkeleri yüklemenin iki yolu +## Özel ilkeleri yüklemek için iki yol -### Seçenek 1: Kurala Dayalı (önerilen) +### Seçenek 1: Kural tabanlı (önerilir) -`*policies.{js,mjs,ts}` dosyalarını `.failproofai/policies/` dizinine koyun ve bunlar otomatik olarak yüklenecektir — hiç bayrak veya yapılandırma değişikliği gerekmez. Bu, git hook'ları gibi çalışır: bir dosya koyun, işe başlar. +`*policies.{js,mjs,ts}` dosyalarını `.failproofai/policies/` içine bırakın ve otomatik olarak yüklenirler — bayrak veya yapılandırma değişikliği gerekmez. Bu, git hook'ları gibi çalışır: dosya bırakın, çalışır. ``` -# Proje seviyesi — git'e kaydedilir, takım tarafından paylaşılır +# Proje seviyesi — git'e commitle, takımla paylaş .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs @@ -53,44 +53,49 @@ failproofai policies --install --custom ./my-policies.js ``` **Nasıl çalışır:** -- Hem proje hem de kullanıcı dizinleri taranır (birleşim — ilk kapsam kazanmaz) -- Dosyalar her dizin içinde alfabetik olarak yüklenir. Sırayı kontrol etmek için `01-`, `02-` ön eki kullanın -- Yalnızca `*policies.{js,mjs,ts}` ile eşleşen dosyalar yüklenir; diğer dosyalar yoksayılır -- Her dosya bağımsız olarak yüklenir (dosya başına açık başarısız olur) -- Açık `--custom` ve yerleşik ilkelerle birlikte çalışır +- Hem proje hem de kullanıcı dizinleri taranır (birleşim — ilk-kapsam-kazanır değil) +- Dosyalar her dizin içinde alfabetik sırayla yüklenir. Sırayı kontrol etmek için `01-`, `02-` öneki kullanın +- Yalnızca `*policies.{js,mjs,ts}` ile eşleşen dosyalar yüklenir; diğer dosyalar yok sayılır +- Her dosya bağımsız olarak yüklenir (dosya başına hata-açık) +- Açık `--custom` ve yerleşik ilkelerle yan yana çalışır -Kurala dayalı ilkeler, kuruluşunuz için bir kalite standardı oluşturmanın en kolay yoludur. `.failproofai/policies/` öğesini git'e işleyin ve her takım üyesi aynı kuralları otomatik olarak alır — geliştirici başına kurulum gerekmez. Takımınız yeni arıza modlarını keşfettikçe, bir ilke ekleyin ve gönderin. Zamanla bunlar, her katkıyla gelişen ve iyileşen canlı bir kalite standardı haline gelir. +Kural tabanlı ilkeler, kuruluşunuz için kalite standardı oluşturmanın en kolay yoludur. `.failproofai/policies/` dizinini git'e commitleyin ve her takım üyesi otomatik olarak aynı kuralları alır — geliştirici başına kurulum gerekmez. Takımınız yeni hata modlarını keşfettikçe, bir ilke ekleyin ve gönderin. Zamanla bunlar, her katkıyla gelişmeye devam eden yaşayan bir kalite standardı haline gelir. ### Seçenek 2: Açık dosya yolu ```bash -# Özel ilkeler dosyası ile yükleyin +# Özel ilkeler dosyasıyla yükleyin failproofai policies --install --custom ./my-policies.js -# İlkeler dosyası yolunu değiştirin +# Özel ilke yollarını değiştirin failproofai policies --install --custom ./new-policies.js -# Yapılandırmadan özel ilkeler yolunu kaldırın +# Birden çok açık dosyayı yapılandırın (bayrak sırasında yüklenir) +failproofai policies --install --custom ./security.js --custom ./workflow.js + +# Config'ten tüm açık özel ilke yollarını kaldırın failproofai policies --uninstall --custom ``` -Çözümlenen mutlak yol, `policies-config.json` içinde `customPoliciesPath` olarak depolanır. Dosya her hook olayında taze yüklenir - olaylar arasında önbelleğe alma yoktur. +Çözümlenen mutlak yollar `policies-config.json` dosyasında `customPoliciesPaths` olarak depolanır. Birden çok dosya yapılandırmak için `--custom` yinelenin. Eski `customPoliciesPath` alanını kullanan mevcut yapılandırmalar çalışmaya devam eder. Dosyalar her hook event'inde yeniden yüklenir — event'ler arasında önbelleğe alma yoktur. + +Her kayıtlı ilke, panoda kendi başına bir geçiş ile görünür. Bir ilkeyi kapatmak, kaynağı-nitelikli kimliğini `disabledCustomPolicies` içinde kaydeder; dosya ve diğer ilkeleri yüklemeye devam ederken, devre dışı ilke event eşleştirmesinden önce hariç tutulur. Dosyalar arasında yinelenen ilke adlarının bağımsız geçişleri vardır. ### Her ikisini birlikte kullanma -Kurala dayalı ilkeler ve açık `--custom` dosyası bir arada bulunabilir. Yükleme sırası: +Kural tabanlı ilkeler ve açık `--custom` dosyaları bir arada bulunabilir. Yükleme sırası: -1. Açık `customPoliciesPath` dosyası (yapılandırılmışsa) -2. Proje kurala dayalı dosyalar (`{cwd}/.failproofai/policies/`, alfabetik) -3. Kullanıcı kurala dayalı dosyalar (`~/.failproofai/policies/`, alfabetik) +1. Açık `customPoliciesPaths` dosyaları (yapılandırılmış sırayla) +2. Proje kural dosyaları (`{cwd}/.failproofai/policies/`, alfabetik) +3. Kullanıcı kural dosyaları (`~/.failproofai/policies/`, alfabetik) --- ## API -### İçe Aktar +### İçe aktarım ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -98,45 +103,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Bir ilkeyi kaydeder. Aynı dosyada birden fazla ilke için gerektiği kadar çağırın. +Bir ilkeyi kaydeder. Aynı dosyada birden çok ilke için gerektiği kadar çağırın. ```ts customPolicies.add({ name: string; // gerekli - benzersiz tanımlayıcı - description?: string; // `failproofai policies` çıkışında gösterilen - match?: { events?: HookEventType[] }; // olay türüne göre filtreleyin; hepsini eşleştirmek için atlayın + description?: string; // `failproofai policies` çıktısında gösterilir + match?: { events?: HookEventType[] }; // event türüne göre filtrele; tümüyle eşleştirmek için atlayın fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### Karar Yardımcıları +### Karar yardımcıları -| İşlev | Efekt | Kullanım zamanı | -|----------|--------|----------| -| `allow()` | İşleme sessizce izin ver | İşlem güvenlidir, mesaj gerekmez | -| `deny(message)` | İşlemi engelle | Aracı bu işlemi yapmamalıdır | -| `instruct(message)` | Engelle olmadan bağlam ekle | Aracıyı doğru yolda tutmak için ekstra bağlam ver | +| İşlev | Etki | Şu durumlarda kullanın | +|-------|------|----------------------| +| `allow()` | İşlemi sessizce izin verin | İşlem güvenlidir, mesaj gerekmez | +| `deny(message)` | İşlemi engelleyin | Agent bu işlemi yapmamalıdır | +| `instruct(message)` | Bloklama olmadan bağlam ekleyin | Agent'a yolunda kalmak için ekstra bağlam verin | -`deny(message)` - mesaj Claude'a `"Blocked by failproofai:"` ön ekiyle görünür. Tek bir `deny` tüm diğer değerlendirmeleri kısaltır. +`deny(message)` - mesaj Claude'a `"Blocked by failproofai:"` önekiyle görünür. Tek bir `deny` tüm sonraki değerlendirmeleri kısa devre yapar. -`instruct(message)` - mesaj Claude'un mevcut araç çağrısı için bağlamına eklenir. Tüm `instruct` mesajları birikimlenir ve birlikte teslim edilir. +`instruct(message)` - mesaj mevcut araç çağrısı için Claude'un bağlamına eklenir. Tüm `instruct` mesajları biriktirilir ve birlikte iletilir. -Herhangi bir `deny` veya `instruct` mesajına ekstra rehberlik ekleyebilirsiniz, `policyParams` içinde bir `hint` alanı ekleyerek — kod değişikliği gerekmez. Bu, özel (`custom/`), proje kurala dayalı (`.failproofai-project/`) ve kullanıcı kurala dayalı (`.failproofai-user/`) ilkelerle de çalışır. Ayrıntılar için [Yapılandırma → hint](/tr/configuration#hint-cross-cutting) bölümüne bakın. +`policyParams` içinde bir `hint` alanı ekleyerek herhangi bir `deny` veya `instruct` mesajına ekstra rehberlik ekleyebilirsiniz — kod değişikliği gerekmez. Bu, özel (`custom/`), proje kural (`.failproofai-project/`) ve kullanıcı kural (`.failproofai-user/`) ilkeleri için de çalışır. Ayrıntılar için [Yapılandırma → hint](/tr/configuration#hint-cross-cutting) bölümüne bakın. -### Bilgilendirici izin mesajları +### Bilgilendirici allow mesajları -`allow(message)` işleme izin verir **ve** Claude'a geri bilgilendirici bir mesaj gönderir. Mesaj, hook işleyicisinin stdout yanıtında `additionalContext` olarak teslim edilir — `instruct` tarafından kullanılan aynı mekanizma, ancak anlamsal olarak farklı: bir uyarı değil, bir durum güncellemesidir. +`allow(message)` işleme izin verir **ve** Claude'a bir bilgilendirici mesaj gönderir. Mesaj, hook handler'ın stdout yanıtında `additionalContext` olarak iletilir — `instruct` tarafından kullanılan mekanizmla aynı, ancak semantik olarak farklı: uyarı değil, durum güncellemesi. -| İşlev | Efekt | Kullanım zamanı | -|----------|--------|----------| -| `allow(message)` | İzin ver ve Claude'a bağlam gönder | Bir kontrolün geçtiğini doğrula veya bir kontrolün neden atlandığını açıkla | +| İşlev | Etki | Şu durumlarda kullanın | +|-------|------|----------------------| +| `allow(message)` | İzin verin ve Claude'a bağlam gönderin | Bir kontrolün geçtiğini onaylayın veya bir kontrolün neden atlanıldığını açıklayın | -Kullanım durumları: +Kullanım örnekleri: - **Durum onayları:** `allow("All CI checks passed.")` — Claude'a her şeyin yeşil olduğunu söyler -- **Açık başarısız açıklamalar:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude'a bir kontrolün neden atlandığını söyler, böylece tam bağlamı vardır -- **Birden fazla mesaj birikmesi:** birkaç ilke her biri `allow(message)` döndürürse, tüm mesajlar satır sonlarıyla birleştirilir ve birlikte teslim edilir +- **Hata-açık açıklamalar:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude'a bir kontrolün neden atlanıldığını söyler +- **Birden çok mesaj birikir:** birkaç ilke her biri `allow(message)` döndürürse, tüm mesajlar yeni satırlarla birleştirilir ve birlikte iletilir ```js customPolicies.add({ @@ -158,29 +163,29 @@ customPolicies.add({ ### `PolicyContext` alanları | Alan | Tür | Açıklama | -|-------|------|-------------| +|------|-----|----------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | Çağrılan araç (ör. `"Bash"`, `"Write"`, `"Read"`) | -| `toolInput` | `Record \| undefined` | Aracın girdi parametreleri | -| `payload` | `Record` | Claude Code'dan tam ham olay yükü | +| `toolName` | `string \| undefined` | Çağrılan araç (örn. `"Bash"`, `"Write"`, `"Read"`) | +| `toolInput` | `Record \| undefined` | Aracın giriş parametreleri | +| `payload` | `Record` | Claude Code'dan tam ham event yükü | | `session` | `SessionMetadata \| undefined` | Oturum bağlamı (aşağıya bakın) | ### `SessionMetadata` alanları | Alan | Tür | Açıklama | -|-------|------|-------------| +|------|-----|----------| | `sessionId` | `string` | Claude Code oturum tanımlayıcısı | | `cwd` | `string` | Claude Code oturumunun çalışma dizini | | `transcriptPath` | `string` | Oturumun JSONL transkript dosyasının yolu | -### Olay türleri +### Event türleri -| Olay | Ne zaman başlatılır | `toolInput` içerikleri | -|------|--------------|----------------------| -| `PreToolUse` | Claude bir aracı çalıştırmadan önce | Aracın girdisi (ör. Bash için `{ command: "..." }`) | +| Event | Ne zaman tetiklenir | `toolInput` içeriği | +|-------|-------------------|----------------------| +| `PreToolUse` | Claude bir araç çalıştırmadan önce | Aracın girdisi (örn. `{ command: "..." }` Bash için) | | `PostToolUse` | Bir araç tamamlandıktan sonra | Aracın girdisi + `tool_result` (çıktı) | -| `Notification` | Claude bir bildirim gönderdiğinde | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hook'lar her zaman `allow()` döndürmelidir, bildirimleri engelleyemezler | -| `Stop` | Claude oturumu sona erdiğinde | Boş | +| `Notification` | Claude bir bildirim gönderdiğinde | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hook'lar her zaman `allow()` dönmelidir, bildirimleri engelleyemez | +| `Stop` | Claude oturumu bittiğinde | Boş | --- @@ -189,19 +194,19 @@ customPolicies.add({ İlkeler şu sırayla değerlendirilir: 1. Yerleşik ilkeler (tanım sırasında) -2. `customPoliciesPath` öğesinden açık özel ilkeler (`.add()` sırasında) -3. Proje `.failproofai/policies/` öğesinden kurala dayalı ilkeler (dosyalar alfabetik, içinde `.add()` sırası) -4. Kullanıcı `~/.failproofai/policies/` öğesinden kurala dayalı ilkeler (dosyalar alfabetik, içinde `.add()` sırası) +2. `customPoliciesPath` dosyalarından açık özel ilkeler (`.add()` sırasında) +3. Proje `.failproofai/policies/` dosyalarından kural ilkeleri (dosyalar alfabetik, içinde `.add()` sırası) +4. Kullanıcı `~/.failproofai/policies/` dosyalarından kural ilkeleri (dosyalar alfabetik, içinde `.add()` sırası) -İlk `deny` tüm sonraki ilkeleri kısaltır. Tüm `instruct` mesajları birikimlenir ve birlikte teslim edilir. +İlk `deny` sonraki tüm ilkeleri kısa devre yapar. Tüm `instruct` mesajları biriktirilir ve birlikte iletilir. --- -## Geçişken içe aktarmalar +## Geçişli içe aktarımlar -Özel ilke dosyaları göreceli yollar kullanarak yerel modülleri içe aktarabilir: +Özel ilke dosyaları, göreli yollar kullanarak yerel modülleri içe aktarabilir: ```js // my-policies.js @@ -218,46 +223,46 @@ customPolicies.add({ }); ``` -Giriş dosyasından ulaşılabilir tüm göreceli içe aktarmalar çözümlenir. Bu, `from "failproofai"` içe aktarmalarını gerçek dist yoluna yeniden yazarak ve ESM uyumluluğunu sağlamak için geçici `.mjs` dosyaları oluşturarak uygulanır. +Giriş dosyasından erişilebilir tüm göreli içe aktarımlar çözümlenir. Bu, `from "failproofai"` içe aktarımlarını gerçek dist yoluna yazarak ve ESM uyumluluğunu sağlamak için geçici `.mjs` dosyaları oluşturarak uygulanır. --- -## Olay türü filtrelemesi +## Event türü filtreleme -Bir ilkenin ne zaman başlatılacağını sınırlamak için `match.events` kullanın: +Bir ilkenin ne zaman tetikleneceğini sınırlamak için `match.events` kullanın: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Sadece oturum sona erdiğinde başlatılır + // Yalnızca oturum sonlandığında tetiklenir // ctx.session.transcriptPath tam oturum günlüğünü içerir return allow(); }, }); ``` -`match` öğesini tamamen atlayarak her olay türünde başlatılmasını sağlayın. +Her event türünde tetiklemek için `match` tamamen atlayın. --- -## Hata yönetimi ve arıza modları +## Hata işleme ve başarısızlık modları -Özel ilkeler **açık başarısız olur**: hatalar hiçbir zaman yerleşik ilkeleri engelleme veya hook işleyiciyi çökmez. +Özel ilkeler **hata-açıktır**: hatalar asla yerleşik ilkeleri engellemez veya hook handler'ı çökmez. -| Arıza | Davranış | -|---------|----------| -| `customPoliciesPath` ayarlanmadı | Açık özel ilkeler çalışmaz; kurala dayalı ilkeler ve yerleşikler normal şekilde devam eder | -| Dosya bulunamadı | Uyarı `~/.failproofai/hook.log` öğesine kaydedilir; yerleşikler devam eder | -| Söz dizimine/içe aktarmaya hata (açık) | Hata `~/.failproofai/hook.log` öğesine kaydedilir; açık özel ilkeler atlanır | -| Söz dizimine/içe aktarmaya hata (kurala dayalı) | Hata kaydedilir; o dosya atlanır, diğer kurala dayalı dosyalar yine de yüklenir | -| `fn` çalışma zamanında hatası oluşturur | Hata kaydedilir; bu hook `allow` olarak değerlendirilir; diğer hook'lar devam eder | -| `fn` 10 saniyeden fazla sürer | Zaman aşımı kaydedilir; `allow` olarak değerlendirilir | -| Kurala dayalı dizin eksik | Kurala dayalı ilkeler çalışmaz; hata yok | +| Başarısızlık | Davranış | +|-------------|----------| +| `customPoliciesPath` ayarlanmamış | Açık özel ilkeler çalışmaz; kural ilkeleri ve yerleşikler normal devam eder | +| Dosya bulunamadı | Uyarı `~/.failproofai/hook.log` dosyasına kaydedilir; yerleşikler devam eder | +| Sözdizimi/içe aktarım hatası (açık) | Hata `~/.failproofai/hook.log` dosyasına kaydedilir; açık özel ilkeler atlanır | +| Sözdizimi/içe aktarım hatası (kural) | Hata kaydedilir; bu dosya atlanır, diğer kural dosyaları yüklenir | +| `fn` çalışma zamanında atılırsa | Hata kaydedilir; bu hook `allow` olarak ele alınır; diğer hook'lar devam eder | +| `fn` 10 saniyeden uzun sürerse | Zaman aşımı kaydedilir; `allow` olarak ele alınır | +| Kural dizini eksikse | Kural ilkeleri çalışmaz; hata yok | -Özel ilke hatalarını hata ayıklamak için günlük dosyasını izleyin: +Özel ilke hatalarını ayıklamak için log dosyasını izleyin: ```bash tail -f ~/.failproofai/hook.log @@ -266,13 +271,13 @@ tail -f ~/.failproofai/hook.log --- -## Tam örnek: birden fazla ilke +## Tam örnek: birden çok ilke ```js // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// Aracının secrets/ dizinine yazmasını engelleyin +// Agent'ın secrets/ dizinine yazmasını önleyin customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -285,7 +290,7 @@ customPolicies.add({ }, }); -// Aracıyı doğru yolda tutun: taahhüt etmeden önce testleri doğrulayın +// Agent'ı yolunda tutun: commitleme öncesi testleri doğrulayın customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +305,7 @@ customPolicies.add({ }, }); -// Dondurma döneminde planlanmamış bağımlılık değişikliklerini engelleyin +// Dondurma süresi boyunca planlanmamış bağımlılık değişikliklerini önleyin customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -323,14 +328,14 @@ export { customPolicies }; ## Örnekler -`examples/` dizini çalışmaya hazır ilke dosyalarını içerir: +`examples/` dizini çalıştırmaya hazır ilke dosyaları içerir: | Dosya | İçerik | -|------|----------| -| `examples/policies-basic.js` | Yaygın aracı arıza modlarını kapsayan beş başlangıç ilkesi | -| `examples/policies-advanced/index.js` | Gelişmiş desenler: geçişken içe aktarmalar, eşzamansız çağrılar, çıktı temizleme ve oturum sonu hook'ları | -| `examples/convention-policies/security-policies.mjs` | Kurala dayalı güvenlik ilkeleri (.env yazışlarını engelle, git tarihini yeniden yazmayı önle) | -| `examples/convention-policies/workflow-policies.mjs` | Kurala dayalı iş akışı ilkeleri (test hatırlatmaları, denetim dosyası yazışları) | +|-------|--------| +| `examples/policies-basic.js` | Yaygın agent başarısızlık modlarını kapsayan beş başlangıç ilkesi | +| `examples/policies-advanced/index.js` | Gelişmiş modeller: geçişli içe aktarımlar, async çağrılar, çıktı temizleme ve oturum sonunda hook'lar | +| `examples/convention-policies/security-policies.mjs` | Kural tabanlı güvenlik ilkeleri (.env yazma engellemesi, git geçmişi yeniden yazma engelleme) | +| `examples/convention-policies/workflow-policies.mjs` | Kural tabanlı iş akışı ilkeleri (test hatırlatıcıları, denetim dosyası yazma) | ### Açık dosya örneklerini kullanma @@ -338,16 +343,16 @@ export { customPolicies }; failproofai policies --install --custom ./examples/policies-basic.js ``` -### Kurala dayalı örnekleri kullanma +### Kural tabanlı örnekleri kullanma ```bash -# Proje seviyesine kopyala +# Proje seviyesine kopyalayın mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# Veya kullanıcı seviyesine kopyala +# Veya kullanıcı seviyesine kopyalayın mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -Yükleme komutu gerekmez — dosyalar bir sonraki hook olayında otomatik olarak alınır. \ No newline at end of file +Yükleme komutu gerekmez — dosyalar sonraki hook event'inde otomatik olarak alınır. \ No newline at end of file diff --git a/docs/tr/dashboard.mdx b/docs/tr/dashboard.mdx index 7d1ad75d..b6598eba 100644 --- a/docs/tr/dashboard.mdx +++ b/docs/tr/dashboard.mdx @@ -1,14 +1,15 @@ --- -title: Kontrol Paneli +--- +title: Dashboard description: "Ajan oturumlarını izleyin, araç çağrılarını gözden geçirin ve politikaları yönetin" icon: chart-line --- -failproofai kontrol paneli, AI ajan oturumlarınızı izlemek ve politikaları yönetmek için yerel bir web uygulamasıdır. Ajanlarınız sizin yokken neler yaptığını görün. +failproofai panosu, yapay zeka ajan oturumlarınızı izlemek ve politikaları yönetmek için yerel bir web uygulamasıdır. Ajanlarınız sizin yokken neler yaptığını görün. --- -## Kontrol panelini başlatma +## Panoyu başlatma ```bash failproofai @@ -16,7 +17,7 @@ failproofai `http://localhost:8020` adresinde açılır. -Kontrol paneli, yerel proje, oturum ve failproofai yapılandırma verilerini doğrudan dosya sisteminden okur. Denetim hatırlatmaları ve davetiyeler gibi isteğe bağlı kimlik doğrulamalı özellikler, bu istekler için gerekli bilgileri (e-posta adresleri dahil) uzak API'lere gönderir. +Dashboard, yerel proje, oturum ve failproofai yapılandırma verilerini doğrudan dosya sisteminden okur. Denetim hatırlatıcıları ve davetiyeler gibi isteğe bağlı kimlik doğrulamalı özellikler, bu istekler için gerekli bilgileri (e-posta adreslerini de dahil) uzak API'lere gönderir. --- @@ -24,81 +25,83 @@ Kontrol paneli, yerel proje, oturum ve failproofai yapılandırma verilerini do ### Projeler -Makinenizde bulunan tüm Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity ve Goose projelerini listeler. Claude projeleri `~/.claude/projects/` dizininden (veya `CLAUDE_PROJECTS_PATH` tarafından ayarlanan yoldan) keşfedilir; Codex projeleri `~/.codex/sessions///
/*.jsonl` altındaki her transkripti tarayarak ve her oturumun ilk kaydında kayıtlı `cwd` ile gruplandırılarak keşfedilir; Copilot CLI projeleri her `~/.copilot/session-state//workspace.yaml` dosyasını (`COPILOT_HOME` aracılığıyla yapılandırılabilir) tarayarak ve `cwd` alanına göre gruplandırılarak keşfedilir; Cursor Agent projeleri `~/.cursor/agent-sessions//` altındaki oturum başına meta verileri tarayarak (`CURSOR_HOME` aracılığıyla yapılandırılabilir, `conversations/` ve `sessions/` yedek olarak kullanılır) `meta.json` / `session.json` / `workspace.yaml` içinde `cwd` skaler değeri arayarak keşfedilir; OpenCode projeleri `~/.local/share/opencode/opencode.db` adresindeki SQLite DB'sini `opencode db --format json` aracılığıyla sorgulayarak keşfedilir (`session` ve `project` tablolarını okuyuz ve `project_id` ile gruplandırırız); Pi projeleri `~/.pi/agent/sessions//_.jsonl` altındaki oturum başına JSONL transkriptlerini (`PI_SESSIONS_DIR` aracılığıyla yapılandırılabilir) tarayarak ve her oturumun ilk kaydından `cwd` çekerek keşfedilir; Hermes ağ geçidi oturumları `~/.hermes/state.db` adresindeki SQLite deposundan doğrudan okunur (`HERMES_DB_PATH` aracılığıyla yapılandırılabilir) ve `source` tarafından (Slack/Telegram/cli/cron) `hermes-` projelerine gruplandırılır — ağ geçidi oturumlarının cwd'si yoktur; OpenClaw ağ geçidi oturumları `~/.openclaw/agents//sessions/*.jsonl` dizininden okunur ve `openclaw-` projelerine gruplandırılır (aynı şekilde cwd'siz); Factory Droid projeleri `~/.factory/sessions//*.jsonl` adresindeki JSONL transkriptlerinden keşfedilir ve cwd ile gruplandırılır; Devin projeleri `~/.local/share/devin/cli/sessions.db` adresindeki SQLite DB'sinden (her oturumun `working_directory` ile gruplandırılır); Antigravity projeleri `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` adresindeki JSONL transkriptlerinden ve cwd ile gruplandırılarak keşfedilir; ve Goose projeleri `~/.local/share/goose/sessions/sessions.db` adresindeki SQLite DB'sinden (her oturumun `working_dir` ile gruplandırılır). Birden çok CLI tarafından kullanılan bir proje, tüm eşleşen rozet ile tek bir satır olarak gösterilir. Belirli bir ajan CLI'sine göre filtrelemek için tablonun üstündeki **CLI** açılır menüsünü kullanın; URL seçiminizi `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` olarak korur. +Makinenizde bulunan tüm Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity ve Goose projelerini listeler. Claude projeleri `~/.claude/projects/` dizininden (veya `CLAUDE_PROJECTS_PATH` ile ayarlanan yoldan) keşfedilir; Codex projeleri `~/.codex/sessions///
/*.jsonl` altındaki her transkripti tarayarak ve her oturumun ilk kaydında kaydedilen `cwd` değerine göre gruplandırılarak keşfedilir; Copilot CLI projeleri her `~/.copilot/session-state//workspace.yaml` dosyasını tarayarak (`COPILOT_HOME` aracılığıyla yapılandırılabilir) ve `cwd` alanına göre gruplandırılarak keşfedilir; Cursor Agent projeleri `~/.cursor/agent-sessions//` altındaki oturum başına meta veriler taranarak (`CURSOR_HOME` aracılığıyla yapılandırılabilir, geri dönüş olarak `conversations/` ve `sessions/` probu yapılır) `meta.json` / `session.json` / `workspace.yaml` içindeki `cwd` değeri için keşfedilir; OpenCode projeleri `~/.local/share/opencode/opencode.db` konumundaki SQLite DB sorgulama yoluyla keşfedilir (`opencode db --format json` komutuyla - `session` ve `project` tablolarını okuyup `project_id` göre gruplandırırız); Pi projeleri `~/.pi/agent/sessions//_.jsonl` altındaki oturum başına JSONL transkriptlerini tarayarak (`PI_SESSIONS_DIR` aracılığıyla yapılandırılabilir) ve her oturumun ilk kaydından `cwd` değerini çekerek keşfedilir; Hermes ağ geçidi oturumları her profilin SQLite deposundan doğrudan okunur — `~/.hermes/state.db` artı `~/.hermes/profiles//state.db` (`HERMES_HOME` veya tek bir veritabanı için `HERMES_DB_PATH` ile geçersiz kılınabilir) — ve profil ve `source` (Slack/Telegram/cli/cron — ağ geçidi oturumlarının cwd değeri yoktur) ile `hermes--` projelerine gruplandırılır; OpenClaw ağ geçidi oturumları `~/.openclaw/agents//sessions/*.jsonl` konumundan okunur ve ajan ve kanal ile `openclaw--` projelerine gruplandırılır (ayrıca cwd'si yoktur); Factory Droid projeleri `~/.factory/sessions//*.jsonl` konumundaki JSONL transkriptlerinden keşfedilir ve cwd değerine göre gruplandırılır; Devin projeleri `~/.local/share/devin/cli/sessions.db` konumundaki SQLite DB'sinden (her oturumun `working_directory` değerine göre gruplandırılır); Antigravity projeleri `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` konumundaki JSONL transkriptlerinden ve cwd değerine göre gruplandırılır; Goose projeleri `~/.local/share/goose/sessions/sessions.db` konumundaki SQLite DB'sinden (her oturumun `working_dir` değerine göre gruplandırılır). Birden fazla CLI tarafından kullanılan bir proje, tüm eşleşen rozetlerle tek bir satır olarak görüntülenir. Tabelonun üstündeki **CLI** açılır menüsünü kullanarak belirli bir ajan CLI'sıne göre filtreleyin; URL seçiminizi `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` olarak saklar. + +Hermes ve OpenClaw kullanıcı kapsamlıdır ve gruplandırılacak çalışma dizini olmadığı için **daraltılabilir klasör ağacı** olarak görüntülenir — profil (veya ajan) en üst düzeyde, kanalları altında — oysa cwd tabanlı her CLI düz bir satır kalır. Klasör satırları altındaki her şeyin oturum sayısını ve en son aktivitesini toplar, daraltılmış klasörler ziyaretler arasında hatırlanır ve anahtar kelime araması eşleştiği her şeyi genişletir. Her proje şunları gösterir: - Proje adı (klasör yolundan türetilmiş) -- CLI rozeti — `Claude Code` (turuncu), `OpenAI Codex` (mor), `GitHub Copilot` (mavi), `Cursor Agent` (yeşilimtırak), `OpenCode` (kehribar), `Pi` (pembe) ve/veya `Hermes` (çivit mavisi) -- En son oturum etkinliğinin tarihi +- CLI rozeti — `Claude Code` (turuncu), `OpenAI Codex` (mor), `GitHub Copilot` (mavi), `Cursor Agent` (zümrüt), `OpenCode` (kehribar), `Pi` (pembe) ve/veya `Hermes` (çivit mavisi) +- En son oturum aktivitesinin tarihi Oturumlarını görmek için bir projeye tıklayın. ### Oturumlar Bir proje içindeki tüm oturumları listeler. Her oturum şunları gösterir: -- Oturum ID'si +- Oturum kimliği - Başlangıç ve bitiş zaman damgaları - Araç çağrılarının sayısı -- Hook etkinlik sayısı (politikaların ateşlenmesi) +- Hook aktivite sayısı (tetiklenen politikalar) -Listeyi daraltmak için tarih aralığı filtresini ve oturum ID'si aramasını kullanın. Oturumlar sayfa bölümlüdür. +Listeyi daraltmak için tarih aralığı filtresini ve oturum kimliği aramasını kullanın. Oturumlar sayfalanmıştır. -Oturum görüntüleyicisini açmak için bir oturuma tıklayın. +Oturum görüntüleyiciyi açmak için bir oturuma tıklayın. -### Oturum görüntüleyicisi +### Oturum görüntüleyici -Oturum görüntüleyicisi, otonom ajanlar için temel soruyu yanıtlar: ajan ne yaptı ve yolda kaldı mı? Başlığın yanındaki CLI rozeti, oturumun Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity veya Goose transkripti olup olmadığını gösterir. Bir oturumda meydana gelen her şeyin zaman çizelgesini gösterir: +Oturum görüntüleyici, otonom ajanlar için ana soruyu yanıtlar: ajan ne yaptı ve doğru yolda mı kaldı? Başlığın yanındaki CLI rozeti, oturumun Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity veya Goose transkripti olup olmadığını gösterir. Bir oturumda gerçekleşen her şeyin bir zaman çizelgesini gösterir: -- **İletiler** - Claude'un metin yanıtları ve kullanıcı istekleri -- **Araç çağrıları** - Claude'un çağırdığı her araç, giriş ve çıkışı ile birlikte -- **Politika etkinliği** - Her araç çağrısı için hangi politikaların ateşlendiği ve hangi kararı döndürdüğü +- **Mesajlar** - Claude'un metin yanıtları ve kullanıcı istekleri +- **Araç çağrıları** - Claude'un çağırdığı her araç, girişi ve çıkışı ile birlikte +- **Politika aktivitesi** - Her araç çağrısı için hangi politikaların tetiklenerek ne kararını döndüğü -Üstteki istatistik çubuğu oturum süresini, toplam araç çağrılarını ve hook kararlarının bir özetini (allow / deny / instruct sayıları) gösterir. +En üstteki istatistik çubuğu oturum süresini, toplam araç çağrılarını ve kanca kararlarının özetini (izin ver / reddet / talimatlı sayıları) gösterir. -Oturumu dışa aktarmak için **İndirme Günlükleri** düğmesine tıklayın. Claude Code, Codex, Copilot, Cursor ve Pi oturumları için orijinal disk üzerindeki JSONL transkriptini byte-for-byte alırsınız; OpenCode oturumları (oturumları SQLite'de, diskte değil) için `session` / `messages` / `parts` tablolarını yansıtan bir JSON belgesi alırsınız. +Oturumu dışa aktarmak için **İndirme Günlükleri** düğmesine tıklayın. Claude Code, Codex, Copilot, Cursor ve Pi oturumları için, asıl disk üzerindeki JSONL transkriptini bayt-için-bayt alırsınız; OpenCode oturumları (SQLite'da yaşayan, disktte değil) için temel alınan `session` / `messages` / `parts` tablolarını yansıtan bir JSON belgesi alırsınız. ### Denetim -Ajanınızın geçmiş oturumlar genelinde gerçekten nasıl davrandığı hakkında kişilik odaklı bir rapor. `failproofai audit` CLI ile aynı taramasını çalıştırır ancak bunu tek ekranlı paylaşılabilir bir poster + dört alt bölüm olarak gösterir: +Ajanınızın geçmiş oturumlar arasında aslında nasıl davrandığına dair kişilik temelli bir rapor. `failproofai audit` CLI ile aynı taramayı çalıştırır ancak bunu tek ekranlı paylaşılabilir bir poster + aşağıda katlanmış dört bölüm olarak gösterir: -1. **Poster** — ilk görüntüleme alanını doldurur. failproof_ai uyumlu yazı tipi + denetim etiketi içeren kendi kendine yeterli PNG-yakalama bölgesi · arketipi indeksi (`№ NN / 08`) + denetim tarihi · sayısal puan (0–100) + yüzdelik sıralama rozeti (`en iyi %15`) · arketipi adı (`iyimser`, `kovboy`, `kaşif`, `balık hafızası`, `paranoid mimar`, `hassas yapı ustası`, `çekiç` veya `hayalet` içinden biri) + 3 anahtar kelime şeridi · `// yalnızca ajanların %N'i bu arketiptedir` nadir kullanım satırı · 8×8 piksel sigil kutucuğu · `denetin → failproof.ai` altbilgisi. Üç paylaş düğmesi yakalama kutusunun hemen dışında yer alır: `arketipi paylaş` (X niyeti), `LinkedIn'de paylaş`, `posteryı indir`. Yakalama `html-to-image` aracılığıyla çalışır, bu nedenle PNG ekranda görünen görüntüyle piksele kadar eşleşir (kesikli kenarlıklar, SVG logo maskesi, degradeler, yazı tipi ölçütleri — tümü korunur). -2. **Güçlü Yönler** — sakin ✓ satır listesi ajanınızın zaten iyi yaptığı davranışlar, canlı denetim verilerinden türetilmiş (temiz araç çağrısı oranı, ana dalına doğrudan itme yok, sıfır kimlik bilgisi sızıntısı, sıfır yeniden deneme fırtınaları) — her biri yalnızca ilgili politikanın denetim penceresi boyunca temiz bir kaydı olduğunda gösterilir. -3. **Tuhaflıklar** — sızdığı şeylerin tablosu, önem derecesine göre sıralanmış: `ne zaman · ne sızdığı + onu yakalayacak politika · önem rozeti · görüldü`, burada yineleme `yeni` (bir kez), `N× görüldü` (2–9 kez) veya `yinelenen` (10+) olarak okunur. -4. **İyileştirme Şekli** — sakin satır listesi, önerilen her politika için bir tane: beyaz renkli politika adı, tek satırlık açıklama, kurulum komutu + sağ tarafta kopyala düğmesi. Bölüm başlığı `tümünü etkinleştir N → öngörülen · ` (her düzeltme uygulanmış durumdaki ulaşacağınız puan) ve `[tümünü yükle]` düğmesi her önerilen politika için birleştirilmiş `failproofai policy add a b c …` komutunu kopyalar. -5. **Daha iyi geri dönün** — yan yana iki kart. Sol: hatırlatıcı ayarlayın (`3d` / `7d` / `14d` / `30d` kadans seçici; kimlik doğrulaması yapıldıktan sonra `/api/auth/reminder` aracılığıyla kalıcı). Sağ: failproof avantajlarının kilidini açın — `bir arkadaşı davet et` virgülle/boşlukla/yeni satırla ayrılmış bir arkadaş e-postaları listesini alan bir modal açar (gönderim başına en fazla 10), bunları `/api/audit/invite` adresine GÖNDERIR, bu da api-sunucusunun `POST /v0/invite` adresine iletilir. API sunucusu `invite@failproof.ai` adresinden her alıcı için bir e-posta gönderir ve gönderen CC olarak ayarlanır ve `Reply-To` belirlenir, bu sayede alıcı kimi davet ettiğini görür ve gönderen gelen kutusunda bir kopya alır. Anonim kullanıcılar davetiyeler gönderilmeden önce gönderenin e-postası bilinmesi için `AuthDialog` aracılığıyla yönlendirilir. Hak / avantaj yerine getirme sonraki bir adımdır. +1. **Poster** — ilk görüntü alanını doldurur. failproof_ai işareti + denetim etiketi içeren bağımsız PNG-yakalama bölgesi · arketip dizini (`№ NN of 08`) + denetim tarihi · sayısal puan (0–100) + yüzdelik sıralama rozeti (`top 15%`) · arketip adı (`the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost` arasından biri) + 3 anahtar kelime şeridi · `// only N% of agents are this archetype` nadirlik satırı · 8×8 piksel sigil döşeme · `audit yours → failproof.ai` altbilgi. Üç paylaşım düğmesi yakalama kutusunun hemen dışında yer alır: `post your archetype` (X intent), `share on linkedin`, `download poster`. Yakalama `html-to-image` aracılığıyla çalışır, böylece PNG ekranda görünen render ile piksel-için-piksel eşleşir (kesikli sınırlar, SVG logo maskesi, degradeler, yazı tipi metrikleri — tümü korunur). +2. **Güçlü Yönler** — sakin ✓ satır listeleri ajanınızın zaten iyi yaptığı davranışlar, canlı denetim verilerinden türetilmiş (temiz araç çağrısı oranı, ana dala doğrudan itme yok, sıfır kimlik bilgisi sızıntısı, sıfır yeniden deneme fırtınası) — ilgili politikanın denetim penceresi boyunca temiz bir rekoru olduğu her zaman yüzeylenmiştir. +3. **Tuhaflıklar** — şu şekilde sıralanmış kaçan şey tablosu: `when · what slipped + the policy that would've caught it · severity pill · seen`, burada tekrarlama `new` (bir kez), `N× seen` (2–9 kez) veya `recurring` (10+) şeklinde okunur. +4. **Nasıl iyileştirilir** — sakin satır listesi, önerilen her politika için bir tane: politika adı beyaz, tek satırlık açıklama, sağ tarafta komut + kopyala düğmesini kurun. Bölüm başlığı `enable all N → projected · ` şeklinde okunur (her düzeltme uygulandığında ulaşacağınız puan) ve `[install all]` düğmesi her önerilen politika için birleştirilmiş `failproofai policy add a b c …` komutunu kopyalar. +5. **Daha iyi şekilde geri dön** — yan yana iki kart. Sol: bir hatırlatıcı ayarlayın (`3d` / `7d` / `14d` / `30d` kadans seçici; kimlik doğrulandıktan sonra `/api/auth/reminder` aracılığıyla devam eder). Sağ: failproof avantajlarının kilidini açın — `invite a friend` virgül/boşluk/yeni satır ile ayrılmış bir arkadaş e-postası listesini alan bir modal açar (gönderi başına maksimum 10), bunları `/api/audit/invite` konumuna POSTlar; bu api-sunucusunun `POST /v0/invite` konumuna yönlendirir. API sunucusu `invite@failproof.ai` adresinden alıcı başına bir e-posta gönderir, gönderici Cc'lenir ve `Reply-To` ayarlanır, böylece alıcı onları kimin davet ettiğini görür ve gönderici gelen kutusunda bir kopya alır. Anonim kullanıcılar davetiyeler gönderilmeden önce gönderenin e-postası bilinecek şekilde önce `AuthDialog` aracılığıyla yönlendirilir. Yetki / avantajlar karşılanması sonraki bir adımdır. -`failproofai audit` çalışması tarafından yönlendirilir — temel tarama motoru, desteklenen bayraklar ve transkript başına önbellek değişmezleri için [Denetim CLI](/tr/cli/audit) sayfasına bakın. Kontrol paneli en son sonucu `~/.failproofai/audit-dashboard.json` adresinde önbelleğe alır (`0600` modu, tek yuva, yeni çalıştırmalar üzerini yazar), böylece yeniden ziyaretler anlıktır; **hem transkript başına hem de bütün sonuç önbellekleri 7 günden eski olduklarında okunma sırasında reddedilir**, bu nedenle kontrol paneli hiçbir zaman sessizce bir haftaeski bir sonuç sunmaz — TTL geçtikten sonra `/audit` boş durumuna devam eder ve taze bir çalıştırma ister. Raporun alt tarafında `[ şimdi yeniden denetim ]` düğmesine tıklamak `/api/audit/run` adresine `noCache: true` ile POST gönderir — yeniden denetim transkript başına önbelleği atlar ve her transkripti sıfırdan yeniden tarar — ve kontrol paneli çalıştırma bitene kadar 1Hz'de `/api/audit/status` adresini yoklar; çalıştırma sırasında görüntüleme alanının en üstüne yapışan pembe bir ilerleme şeridi sabitlenir ve geçen bir zamanlayıcı ile birlikte, yeni sonuç başarı durumunda yerde değişir (tam sayfa yeniden yükleme yok; başarısız yeniden denetim önceki raporu bozulmamış bırakır). Başarısızlıkta şerit `RerunError.kind` (`timeout` / `network` / `post_failed`) kopyası olan kırmızıya döner. Boş durum (önbellek yok veya süresi dolmuş) ve sıfır oturum durumu (önbellek var ancak tarama transkript bulamadı) ayrı ayrı yüzeyde gösterilir. +`failproofai audit` çalışma zamanı tarafından yönlendirilir — temel tarama motoru, desteklenen bayraklar ve transkript başına önbellek değişmezleri için [Denetim CLI](/tr/cli/audit) konusuna bakın. Dashboard, en son sonucu `~/.failproofai/audit-dashboard.json` konumunda önbelleğe alır (mod `0600`, tek yuva, yeni çalıştırmalar üzerine yaz) böylece yeniden ziyaretler anında gerçekleşir; **hem transkript başına hem de tüm sonuç önbellekleri okuma sırasında 7 günden eski olduktan sonra reddedilir**, bu nedenle pano asla sessizce hafta eski bir sonucu sunmaz — TTL'nin ötesinde `/audit` boş durumuna düşer ve yeni bir çalıştırma istenir. Raporun alt kısmına yakın `[ re-audit now ]` öğesine tıklamak `noCache: true` ile `/api/audit/run` öğesine POSTlar — yeniden denetim transkript başına önbelleği atlar ve her transkripti sıfırdan yeniden tarar, sessizce önbelleğe alınan sonucu döndürmek yerine — ve pano çalıştırma bitene kadar 1Hz'de `/api/audit/status` sorusu yapar; çalıştırma sırasında yapışkan bir pembe ilerleme şeridi görüntü alanının üstüne sabitlener, geçen zaman sayacı ile ve başarı üzerine yeni sonuç yerinde değiştirilir (tam sayfa yeniden yükleme yok; başarısız yeniden denetim önceki raporu bozulmaz bırakır). Hata durumunda şerit kırmızıya döner ve kopyası `RerunError.kind` (`timeout` / `network` / `post_failed`) kapalı. Boş durum (önbellek yok veya süresi geçmiş) ve sıfır oturum durumu (önbellek var ancak tarama transkript bulamadı) ayrı olarak yüzeylenmiştir. ### Politikalar -Politikaları yönetmek ve etkinliği gözden geçirmek için iki sekmeli sayfa. +Politikaları yönetmek ve aktiviteyi gözden geçirmek için iki sekme sayfası. - - Tek bir panelden failproofai'nin koruduğu ajan CLI'lerini çoklu seçme — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi ve Hermes'in tümü kurulum durumuna (`Active` / `Detected` / `Inactive`), kullanıcı kapsamı ayarları yoluna ve marka rengli aksan içeren bir satır bulunur. İstediğiniz CLI'leri işaretleyip `Değişiklikleri Uygula` düğmesine tıklayarak farkı bir adımda yükleyin/kaldırın. PATH'ta ikili dosyası algılanan CLI'ler önceden işaretlenmiş olur. - - Tekil politikaları tek tıkla açıp kapatın (`~/.failproofai/policies-config.json` yazılır — yüklü her CLI arasında paylaşılır) - - Bir politikayı genişleterek parametrelerini yapılandırın (`policyParams` desteği olan politikalar için) - - Özel bir politikalar dosyası yolu ayarlayın + - failproofai'nin tek bir panelden koruduğu ajan CLI'lerini çoklu seçin — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi ve Hermes'in hepsinin yükleme durumu (`Active` / `Detected` / `Inactive`), kullanıcı kapsamlı ayarlar yolu ve marka renkli aksanı olan bir satırı vardır. İstediğiniz CLI'leri işaretleyin veya işaretini kaldırın ve `Apply changes` öğesine tıklayarak farkı tek adımda kurun/kaldırın. İkilik PATH'de algılanan CLI'ler önceden işaretlenir. + - Bireysel politikaları tek tıklamayla aç veya kapat (yaz `~/.failproofai/policies-config.json` — kurulan her CLI arasında paylaşılır) + - Bir politikayı genişleterek parametrelerini yapılandırın (`policyParams` destekleyen politikalar için) + - Özel politikalar dosya yolunu ayarla - - - Tüm oturumlar genelinde ateşlenen her hook olayının tam sayfalandırılmış geçmişi - - Kararı, olay türünü, CLI'yi (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), politika adını veya oturum ID'sini göre filtreleyin - - Her satır şunları gösterir: zaman damgası, politika adı, karar, CLI rozeti (turuncu = Claude Code, mor = OpenAI Codex, mavi = GitHub Copilot, yeşilimtırak = Cursor Agent, kehribar = OpenCode, pembe = Pi, çivit mavisi = Hermes, deniz mavisi = OpenClaw, gül = Factory Droid, violet = Devin, cyan = Antigravity, limoni yeşil = Goose), araç adı, oturum ID'si ve deny/instruct kararlarının nedeni - - Transkriptini açmak için oturum ID'sine tıklayın — görüntüleyici hangi CLI'nin hook'u ateşlediğini otomatik olarak algılar (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) ve başlıkta eşleşen CLI rozetini gösterir + + - Tüm oturumlar arasında tetiklenen her kanca olayının tam sayfalandırılmış geçmişi + - Karar, olay türü, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), politika adı veya oturum kimliğine göre filtreleyin + - Her satır şunları gösterir: zaman damgası, politika adı, karar, CLI rozeti (turuncu = Claude Code, mor = OpenAI Codex, mavi = GitHub Copilot, zümrüt = Cursor Agent, kehribar = OpenCode, pembe = Pi, çivit mavisi = Hermes, turkuaz = OpenClaw, gül = Factory Droid, menekşe = Devin, siyan = Antigravity, limon yeşili = Goose), araç adı, oturum kimliği ve reddet/talimatlı kararlarının nedeni + - Transkriptini açmak için oturum kimliğine tıklayın — görüntüleyici hangi CLI'nin kancayı tetiklediğini otomatik olarak algılar (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) ve başlıkta eşleşen CLI rozetini gösterir --- -## Otomatik Yenileme +## Otomatik yenileme -Kontrol paneli üst gezinmede bir otomatik yenileme değiştiricisine sahiptir. Etkinleştirildiğinde, geçerli sayfa yeni oturumlar ve politika etkinlikleri göründüğünde göstermek için periyodik olarak yenilenir. Uzun süre çalışan otonom ajan oturumlarını izlemek için gereklidir. +Panoda üst gezinmede bir otomatik yenileme değiştirici vardır. Etkinleştirildiğinde, geçerli sayfa yeni oturumlar ve politika aktivitesi göründükçe periyodik olarak yenilenir. Uzun süreli otonom ajan oturumlarını izlemek için gereklidir. --- ## Sayfaları devre dışı bırakma -Kontrol panelinin yalnızca bazı kısımlarına ihtiyacınız varsa, `FAILPROOFAI_DISABLE_PAGES` ortam değişkenini virgülle ayrılmış sayfa adlarının bir listesi olarak ayarlayın: +Panodan yalnızca bazı bölümlere ihtiyacınız varsa, `FAILPROOFAI_DISABLE_PAGES` değerini virgülle ayrılmış sayfa adlarının listesine ayarlayın: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -110,7 +113,7 @@ Geçerli değerler: `policies`, `projects`, `audit`. ## Projeler yolunu yapılandırma -Varsayılan olarak, kontrol paneli standart Claude Code projeleri dizininden okur. Özel kurulumlar için bunu geçersiz kılın: +Varsayılan olarak, pano standart Claude Code projeleri dizininden okur. Özel kurulumlar için geçersiz kılın: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -118,32 +121,32 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Localhost olmayan bir konaktan erişim +## Localhost olmayan bir ana bilgisayardan erişim -Kontrol panelini **geliştirme modunda** (`npm run dev`) çalıştırırken ve `localhost` dışında bir ana bilgisayar adından — örneğin özel bir etki alanı, uzak bir IP veya tünel yapılmış bir URL — erişirken şunun gibi bir uyarı görebilirsiniz: +Panoyu **dev modunda** (`npm run dev`) çalıştırırken ve `localhost` dışında bir ana bilgisayar adından — örneğin özel alan, uzak IP veya tünellenen URL — erişirken şöyle bir uyarı görebilirsiniz: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Bu, Next.js'nin HMR (sıcak modül yeniden yükleme) web soketi'ne çapraz kaynaklı erişimi engellemesidir, bu bir yalnızca geliştirme özelliğidir. Konağınıza izin vermek için `--allowed-origins` bayrağını kullanın: +Bu, Next.js'nin HMR (sık modülü yeniden yükle) web soketine yönelik çapraz kaynak erişimini engelleme olup, bu dev'e özgü bir özelliktir. Ana bilgisayarınıza izin vermek için `--allowed-origins` bayrağını kullanın: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -Birden çok konak veya IP için virgülle ayrılmış bir liste geçin: +Birden fazla ana bilgisayar veya IP için virgülle ayrılmış bir liste geçirin: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -Bunun yerine `FAILPROOFAI_ALLOWED_DEV_ORIGINS` ortam değişkenini de ayarlayabilirsiniz: +`FAILPROOFAI_ALLOWED_DEV_ORIGINS` ortam değişkenini de ayarlayabilirsiniz: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Bu yalnızca geliştirme modunda geçerlidir. `failproofai` (üretim modu) çalıştırırken, HMR web soketi yoktur ve çapraz kaynaklı geliştirme kaynağı sorunu yoktur. +Bu yalnızca dev moduna uygulanır. `failproofai` çalıştırılırken (üretim modu) HMR web soketi yoktur ve çapraz kaynak dev kaynağı sorunu yoktur. \ No newline at end of file diff --git a/docs/vi/configuration.mdx b/docs/vi/configuration.mdx index 7b078039..6798754f 100644 --- a/docs/vi/configuration.mdx +++ b/docs/vi/configuration.mdx @@ -4,7 +4,7 @@ description: "Định dạng tệp cấu hình, hệ thống ba phạm vi và qu icon: gear --- -failproofai sử dụng các tệp cấu hình JSON để kiểm soát những chính sách nào đang hoạt động, cách chúng hoạt động như thế nào và nơi tải các chính sách tùy chỉnh. Cấu hình được thiết kế để dễ dàng chia sẻ với nhóm của bạn - cam kết nó vào kho lưu trữ của bạn và mỗi nhà phát triển đều nhận được cùng một lưới bảo vệ cho agent. +failproofai sử dụng các tệp cấu hình JSON để kiểm soát những chính sách nào được kích hoạt, cách chúng hoạt động và nơi tải các chính sách tùy chỉnh. Cấu hình được thiết kế để dễ dàng chia sẻ với nhóm của bạn - lưu nó vào kho lưu trữ và mỗi nhà phát triển sẽ có cùng một lưới bảo vệ đại lý. --- @@ -14,44 +14,46 @@ Có ba phạm vi cấu hình, được đánh giá theo thứ tự ưu tiên: | Phạm vi | Đường dẫn tệp | Mục đích | |-------|-----------|---------| -| **project** | `.failproofai/policies-config.json` | Cài đặt theo kho lưu trữ, được cam kết vào kiểm soát phiên bản | -| **local** | `.failproofai/policies-config.local.json` | Ghi đè cá nhân cho mỗi kho lưu trữ, được gitignored | +| **project** | `.failproofai/policies-config.json` | Cài đặt cho từng kho lưu trữ, được lưu trong kiểm soát phiên bản | +| **local** | `.failproofai/policies-config.local.json` | Ghi đè cá nhân cho từng kho lưu trữ, được gitignore | | **global** | `~/.failproofai/policies-config.json` | Mặc định ở cấp người dùng trên tất cả các dự án | -Khi failproofai nhận được sự kiện hook, nó sẽ tải và hợp nhất cả ba tệp tồn tại cho thư mục làm việc hiện tại. +Khi failproofai nhận được sự kiện hook, nó tải và hợp nhất cả ba tệp tồn tại cho thư mục làm việc hiện tại. ### Quy tắc hợp nhất -**`enabledPolicies`** - hợp nhất tất cả ba phạm vi. Một chính sách được kích hoạt ở bất kỳ cấp độ nào đều hoạt động. +**`enabledPolicies`** - hợp của cả ba phạm vi. Một chính sách được bật ở bất kỳ mức nào đều hoạt động. ```text project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← loại bỏ trùng lặp +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← hợp không lặp lại ``` -**`policyParams`** - phạm vi đầu tiên xác định các tham số cho một chính sách nhất định sẽ thắng hoàn toàn. Không có hợp nhất sâu các giá trị trong các tham số của chính sách. +**`policyParams`** - phạm vi đầu tiên xác định các tham số cho một chính sách nhất định chiến thắng hoàn toàn. Không có hợp nhất sâu của các giá trị trong các tham số của chính sách. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← project thắng, global bị bỏ qua +resolved: { allowPatterns: ["sudo apt-get update"] } ← project chiến thắng, global bị bỏ qua ``` ```text -project: (no block-sudo entry) -local: (no block-sudo entry) +project: (không có mục block-sudo) +local: (không có mục block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← rơi xuống global +resolved: { allowPatterns: ["sudo systemctl status"] } ← lọt xuống global ``` -**`customPoliciesPath`** - phạm vi đầu tiên xác định nó sẽ thắng. +**`customPoliciesPaths` / `customPoliciesPath`** - phạm vi đầu tiên xác định bất kỳ hình thức nào đều chiến thắng. -**`llm`** - phạm vi đầu tiên xác định nó sẽ thắng. +**`disabledCustomPolicies`** - hợp trên tất cả các phạm vi. Bảng điều khiển viết một ID được xác định nguồn ở đây khi bạn tắt một chính sách riêng lẻ từ một tệp chính sách rõ ràng hoặc theo quy ước. Các chính sách không được liệt kê vẫn được bật theo mặc định; ID bao gồm tệp nguồn để có thể kiểm soát các chính sách cùng tên trong nhiều tệp một cách độc lập. + +**`llm`** - phạm vi đầu tiên xác định nó chiến thắng. --- @@ -100,29 +102,29 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← rơi xuống global ### `enabledPolicies` -Loại: `string[]` +Kiểu: `string[]` -Danh sách tên chính sách cần kích hoạt. Tên phải khớp chính xác với các định danh chính sách được hiển thị bởi `failproofai policies`. Xem [Built-in Policies](/vi/built-in-policies) để có danh sách đầy đủ. +Danh sách tên chính sách để bật. Tên phải khớp chính xác với các mã định danh chính sách được hiển thị bởi `failproofai policies`. Xem [Built-in Policies](/vi/built-in-policies) để biết danh sách đầy đủ. -Các chính sách không có trong `enabledPolicies` không hoạt động, ngay cả khi chúng có mục nhập trong `policyParams`. +Các chính sách không nằm trong `enabledPolicies` không hoạt động, ngay cả khi chúng có mục nhập trong `policyParams`. ### `policyParams` -Loại: `Record>` +Kiểu: `Record>` -Ghi đè tham số cho từng chính sách. Khóa bên ngoài là tên chính sách; các khóa bên trong là riêng biệt cho chính sách. Mỗi chính sách ghi lại các tham số có sẵn của nó trong [Built-in Policies](/vi/built-in-policies). +Ghi đè tham số theo chính sách. Khóa bên ngoài là tên chính sách; các khóa bên trong là khóa dành riêng cho chính sách. Mỗi chính sách tài liệu hóa các tham số có sẵn của nó trong [Built-in Policies](/vi/built-in-policies). -Nếu một chính sách có các tham số nhưng bạn không chỉ định chúng, các giá trị mặc định được tích hợp của chính sách sẽ được sử dụng. Người dùng không cấu hình `policyParams` sẽ nhận được hành vi giống hệt với các phiên bản trước đó. +Nếu một chính sách có các tham số nhưng bạn không chỉ định chúng, các mặc định tích hợp của chính sách sẽ được sử dụng. Những người dùng không cấu hình `policyParams` hoàn toàn sẽ nhận được hành vi giống hệt với các phiên bản trước đó. -Các khóa không xác định trong khối tham số của một chính sách bị bỏ qua âm thầm khi hook kích hoạt nhưng được đánh dấu là cảnh báo khi bạn chạy `failproofai policies`. +Các khóa không xác định bên trong khối tham số của chính sách được bỏ qua im lặng khi hook kích hoạt nhưng được đánh dấu là cảnh báo khi bạn chạy `failproofai policies`. #### `hint` (cross-cutting) -Loại: `string` (tùy chọn) +Kiểu: `string` (tùy chọn) -Một thông báo được thêm vào lý do khi một chính sách trả về `deny` hoặc `instruct`. Sử dụng nó để cung cấp cho Claude hướng dẫn có thể thực hiện được mà không cần sửa đổi chính sách. +Một thông báo được thêm vào lý do khi chính sách trả về `deny` hoặc `instruct`. Sử dụng nó để cung cấp hướng dẫn hành động cho Claude mà không cần sửa đổi chính sách. -Hoạt động với bất kỳ loại chính sách nào — built-in, custom (`custom/`), project convention (`.failproofai-project/`), hoặc user convention (`.failproofai-user/`). +Hoạt động với bất kỳ loại chính sách nào — tích hợp sẵn, tùy chỉnh (`custom/`), quy ước dự án (`.failproofai-project/`) hoặc quy ước người dùng (`.failproofai-user/`). ```json { @@ -141,40 +143,40 @@ Hoạt động với bất kỳ loại chính sách nào — built-in, custom (` } ``` -Khi `block-force-push` từ chối, Claude sẽ thấy: *"Force-pushing is blocked. Try creating a fresh branch instead."* +Khi `block-force-push` từ chối, Claude thấy: *"Force-pushing is blocked. Try creating a fresh branch instead."* -Các giá trị không phải chuỗi và chuỗi trống bị bỏ qua âm thầm. Nếu `hint` không được đặt, hành vi không thay đổi (tương thích ngược). +Các giá trị không phải chuỗi và chuỗi trống bị bỏ qua im lặng. Nếu `hint` không được đặt, hành vi không thay đổi (tương thích ngược). ### `customPoliciesPath` -Loại: `string` (đường dẫn tuyệt đối) +Kiểu: `string` (đường dẫn tuyệt đối) -Đường dẫn đến tệp JavaScript chứa các chính sách hook tùy chỉnh. Điều này được đặt tự động bởi `failproofai policies --install --custom ` (đường dẫn được phân giải thành tuyệt đối trước khi được lưu trữ). +Đường dẫn đến tệp JavaScript chứa các chính sách hook tùy chỉnh. Đây được đặt tự động bởi `failproofai policies --install --custom ` (đường dẫn được phân giải thành tuyệt đối trước khi được lưu trữ). -Tệp được tải lại trên mỗi sự kiện hook - không có bộ nhớ cache. Xem [Custom Policies](/vi/custom-policies) để biết chi tiết về tác giả. +Tệp được tải mới trên mỗi sự kiện hook - không có bộ nhớ đệm. Xem [Custom Policies](/vi/custom-policies) để biết chi tiết tác giả. -### Các chính sách dựa trên quy ước +### Chính sách dựa trên quy ước Ngoài `customPoliciesPath` rõ ràng, failproofai tự động phát hiện và tải các tệp chính sách từ các thư mục `.failproofai/policies/`: -| Cấp độ | Thư mục | Phạm vi | +| Mức | Thư mục | Phạm vi | |-------|-----------|-------| -| Project | `.failproofai/policies/` | Chia sẻ với nhóm thông qua kiểm soát phiên bản | -| User | `~/.failproofai/policies/` | Cá nhân, áp dụng cho tất cả các dự án | +| Dự án | `.failproofai/policies/` | Chia sẻ với nhóm thông qua kiểm soát phiên bản | +| Người dùng | `~/.failproofai/policies/` | Cá nhân, áp dụng cho tất cả các dự án | -**Khớp tệp:** Chỉ những tệp khớp với `*policies.{js,mjs,ts}` được tải (ví dụ: `security-policies.mjs`, `workflow-policies.js`). Các tệp khác trong thư mục bị bỏ qua. +**Khớp tệp:** Chỉ các tệp khớp với `*policies.{js,mjs,ts}` được tải (ví dụ: `security-policies.mjs`, `workflow-policies.js`). Các tệp khác trong thư mục bị bỏ qua. -**Không cần cấu hình:** Các chính sách quy ước không cần các mục nhập trong `policies-config.json`. Chỉ cần thả các tệp vào thư mục và chúng sẽ được chọn vào sự kiện hook tiếp theo. +**Không cần cấu hình:** Chính sách quy ước không yêu cầu các mục nhập trong `policies-config.json`. Chỉ cần thả các tệp vào thư mục và chúng sẽ được nhận trên sự kiện hook tiếp theo. -**Tải hợp nhất:** Cả thư mục quy ước dự án và người dùng đều được quét. Tất cả các tệp phù hợp từ cả hai cấp độ được tải (không giống như `customPoliciesPath` sử dụng first-scope-wins). +**Tải hợp:** Cả thư mục quy ước dự án và người dùng đều được quét. Tất cả các tệp phù hợp từ cả hai cấp độ được tải (không giống như `customPoliciesPath` sử dụng chiến thắng phạm vi đầu tiên). Xem [Custom Policies](/vi/custom-policies) để biết thêm chi tiết và ví dụ. ### `llm` -Loại: `object` (tùy chọn) +Kiểu: `object` (tùy chọn) -Cấu hình máy khách LLM cho các chính sách thực hiện các cuộc gọi AI. Không bắt buộc cho hầu hết các bộ cài đặt. +Cấu hình máy khách LLM cho các chính sách thực hiện các lệnh gọi AI. Không bắt buộc đối với hầu hết các thiết lập. ```json { @@ -189,19 +191,25 @@ Cấu hình máy khách LLM cho các chính sách thực hiện các cuộc gọ ## Quản lý cấu hình từ CLI -Các lệnh `policies --install` và `policies --uninstall` ghi vào tệp cài đặt hook của CLI agent của bạn (các điểm nhập hook), trong khi `policies-config.json` là tệp bạn quản lý trực tiếp. Hai loại này là riêng biệt: +Các lệnh `policies --install` và `policies --uninstall` ghi vào tệp cài đặt hook của CLI đại lý của bạn (các điểm vào hook), trong khi `policies-config.json` là tệp bạn quản lý trực tiếp. Hai cái này là riêng biệt: + +- **Cài đặt CLI của Đại lý** — cho phép đại lý gọi `failproofai --hook ` trên mỗi lần sử dụng công cụ: + - **Claude Code**: `~/.claude/settings.json` (người dùng), `/.claude/settings.json` (dự án), `/.claude/settings.local.json` (cục bộ) + - **OpenAI Codex**: `~/.codex/hooks.json` (người dùng), `/.codex/hooks.json` (dự án) — Codex không có phạm vi `local` + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (người dùng), `/.github/hooks/failproofai.json` (dự án) — Copilot không có phạm vi `local`. Các mục nhập hook sử dụng các trường lệnh `bash`/`powershell` do Copilot khóa OS với `timeoutSec`; tệp mang một đánh dấu `version: 1` ở cấp cao nhất. Hỗ trợ Copilot CLI là **beta** trong khi chúng tôi xác minh lược đồ bản ghi `events.jsonl` (mà các tài liệu công khai không chỉ định) so với các phiên làm việc thực tế hơn. **Chế độ tác nhân Copilot Chat của VS Code (Bản xem trước)** đọc các cấu hình hook từ `.github/hooks/*.json`, `~/.copilot/hooks/*.json` và `~/.claude/settings.json` (được quản lý bởi cài đặt `chat.hookFilesLocations`) sử dụng cùng một hợp đồng định hình Claude `{hookSpecificOutput:{permissionDecision:"deny",…}}` — các đường dẫn chính xác mà tích hợp `copilot` này và tích hợp `claude` (`~/.claude/settings.json`) đã ghi, vì vậy `failproofai policies --install --cli copilot` (hoặc `--cli claude`) **đã thực thi trong chế độ tác nhân VS Code** mà không cần tích hợp `vscode` riêng biệt (xác nhận từ nhật ký phát hiện của VS Code). + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (người dùng), `/.cursor/hooks.json` (dự án) — Cursor không có phạm vi `local`. Các mục nhập hook sử dụng dạng giống Claude `{type, command, timeout}` (không phân chia `bash`/`powershell`), nhưng được lưu trữ dưới các khóa sự kiện camelCase (`preToolUse`, `beforeSubmitPrompt`, …) trong một mảng phẳng theo [lược đồ hook](https://cursor.com/docs/hooks) của Cursor. Tệp mang một đánh dấu `version: 1` ở cấp cao nhất. Trình xử lý chuẩn hóa camelCase → PascalCase qua `CURSOR_EVENT_MAP` để các chính sách tích hợp sẵn kích hoạt không thay đổi. Hỗ trợ Cursor Agent là **beta** trong khi chúng tôi xác minh bản ghi Cursor trên đĩa (không được chỉ định trong tài liệu công khai) so với các bản cài đặt thực tế hơn. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (người dùng), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (dự án) — OpenCode không có phạm vi `local`. Khác với năm CLI khác, OpenCode có **không có hệ thống hook lệnh bên ngoài**: nó tải các plugin JS/TS trong quá trình được đăng ký rõ ràng qua mảng `plugin: []` trong `opencode.json` (tự động khám phá từ `.opencode/plugins/` **không phải** cách plugin tải trên opencode v1.14.33). Cài đặt thả một nhóm plugin shim nhỏ được tạo gọi subprocess lệnh nhị phân failproofai và dịch phản hồi JSON định hình Claude của nhị phân trở lại ngữ nghĩa plugin: `throw new Error()` cho công cụ-sự kiện từ chối (hủy lệnh gọi công cụ), `client.session.prompt(...)` cho instruct AND cho `Stop` / `SubagentStop` từ chối (gửi lý do từ chối dưới dạng tin nhắn người dùng tiếp theo — kênh thử lại lực duy nhất vì `session.idle` là thông báo duy nhất và ném từ nó là không hoạt động), và không hoạt động cho phép. Shim chuẩn hóa cả tên công cụ (chữ thường → PascalCase qua `OPENCODE_TOOL_MAP`) và khóa arg đầu vào công cụ (camelCase → snake_case qua `OPENCODE_TOOL_INPUT_MAP` cho `Read` / `Write` / `Edit`, ví dụ: `filePath` → `file_path`, `oldString` → `old_string`) trước khi chuyển tiếp đến nhị phân, vì vậy các kiểm tra đường dẫn tích hợp sẵn như `block-read-outside-cwd`, `block-env-files` và `block-secrets-write` kích hoạt không thay đổi trên các lệnh gọi công cụ OpenCode. Các phiên hoạt động trong DB SQLite của opencode tại `~/.local/share/opencode/opencode.db`; người xem phiên bản bảng điều khiển đọc chúng thông qua `opencode db --format json` và `opencode export `. Hỗ trợ OpenCode là **beta** trong khi chúng tôi xác minh hành vi trên các phiên bản và so với các phiên làm việc thực tế hơn. Xem [tài liệu plugin OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (người dùng), `/.pi/settings.json` (dự án) — Pi không có phạm vi `local`. Pi tải các gói tiện ích mở rộng TypeScript khi khởi động; tệp cài đặt là một mảng chuỗi phẳng `{"packages": ["./relative/path", …]}`. failproofai ghi một mục mảng gói duy nhất trỏ đến thư mục `pi-extension/` được gói của nó. Tiện ích mở rộng bên trong đăng ký các sự kiện `tool_call` / `user_bash` / `input` / `session_start` của Pi và shell ra `failproofai --hook --cli pi`; trình xử lý chuẩn hóa underscore_lower_snake_case → PascalCase qua `PI_EVENT_MAP` để các chính sách tích hợp sẵn kích hoạt không thay đổi. Các arg đầu vào công cụ cũng được chuẩn hóa qua `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit cung cấp `path` thay vì `file_path`; ánh xạ khóa cấp cao nhất cho phép `block-env-files` và `block-secrets-write` kích hoạt — `block-read-outside-cwd` đã có dự phòng `path`). Hỗ trợ Pi là **beta** trong khi API tiện ích mở rộng của Pi và bố cục nhật ký phiên ổn định. + - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**phạm vi người dùng duy nhất** — Hermes không có cấu hình dự án/cục bộ). Hermes là **gateway** Slack/Telegram, vì vậy một bản cài đặt chặn các lệnh gọi công cụ từ mọi nền tảng (Slack/Telegram/cli/cron) **và** các đại lý phụ bên trong. Các mục nhập hook là cặp `{command, timeout}` (timeout tính bằng **giây**) dưới bản đồ `hooks:` được khóa bởi các sự kiện snake_case của Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); trình xử lý chuẩn hóa các sự kiện qua `HERMES_EVENT_MAP` và tên công cụ qua `HERMES_TOOL_MAP` để các chính sách tích hợp sẵn kích hoạt không thay đổi. Cấu hình được chỉnh sửa thông qua vòng lặp YAML `Document` bảo toàn nhận xét để các cài đặt khác của người điều hành tồn tại, và cài đặt `hooks_auto_accept: true` để gateway headless (không TTY) chạy hook mà không cần lời nhắc đồng ý. Bộ đánh giá phát ra hợp đồng stdout Hermes `{"decision":"block","reason"}` (Hermes bỏ qua mã thoát). **Hạn chế:** Hermes không có sự kiện `Stop` cuối lượt, vì vậy các tích hợp sẵn `require-*-before-stop` không bao giờ kích hoạt cho nó (không áp dụng, không bị hỏng); `instruct` suy giảm thành allow-with-logged-note (không kênh ngữ cảnh bổ sung); và redaction bí mật đầu ra (`sanitize-*`) không thể viết lại đầu ra công cụ qua hợp đồng shell-hook. Hermes cũng là **nguồn kiểm toán offline** — bảng điều khiển đọc các phiên gateway của nó trực tiếp từ `~/.hermes/state.db`. + - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**phạm vi người dùng duy nhất** — OpenClaw không có cấu hình dự án/cục bộ). Giống như Hermes, OpenClaw là **gateway** tự lưu trữ đa kênh, vì vậy một bản cài đặt chặn các lệnh gọi công cụ từ mọi kênh và các đại lý bên trong của nó. Thực thi chạy qua **hook plugin trong quá trình** của OpenClaw (hook dựa trên tệp nội bộ của nó chỉ dành cho quan sát và không thể chặn), vì vậy — giống như OpenCode/Pi — failproofai gửi một gói `openclaw-plugin/` tĩnh sinh ra nhị phân failproofai không đồng bộ và dịch bản án. Cài đặt đăng ký thư mục plugin được gửi trong `openclaw.json` của `plugins.load.paths[]` và bật nó dưới `plugins.entries.failproofai` (với `hooks.allowConversationAccess: true`, cần thiết cho các hook cuộc trò chuyện thô). Bộ đánh giá phát ra bản án `{permission, reason}` phẳng và shim ánh xạ nó thành hình dạng trả về của mỗi hook: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), và `before_agent_finalize → {action:"revise", reason}` (**Stop** — một cổng lượt kết thúc thực, vì vậy các tích hợp sẵn `require-*-before-stop` **thực thi** trên OpenClaw, không giống như Hermes). Các sự kiện và tên công cụ chuẩn hóa nhị phân-bên qua `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP` (`exec→Bash`, `read→Read`, …) để các chính sách tích hợp sẵn kích hoạt không thay đổi; shim thất bại mở trên bất kỳ lỗi spawn/parse/timeout nào. OpenClaw cũng là **nguồn kiểm toán offline** — bảng điều khiển đọc các phiên JSONL tại `~/.openclaw/agents//sessions/.jsonl`. + - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (người dùng), `/.factory/hooks.json` (dự án) — Factory không có phạm vi `local`. droid gửi một hệ thống hook lệnh bên ngoài kiểu Claude, nhưng với hai tính kỳ lạ được xác minh trực tiếp so với droid v0.171.0: (1) tên sự kiện sống ở **cấp cao nhất** của `hooks.json` — **không có wrapper `"hooks"`** (droid từ chối một); các sự kiện công cụ (`PreToolUse`/`PostToolUse`) mang `"matcher": "*"`, các sự kiện không phải công cụ bỏ qua nó. (2) Từ chối được điều khiển bởi **mã thoát hook 2 + stderr**, không phải quyết định JSON — nhánh `factory` của bộ đánh giá trả về thoát 2 cho các sự kiện công cụ/nhắc nhở và `{decision:"block", reason}` chỉ trên sự kiện cuối lượt `Stop` (kênh thử lại lực duy nhất của droid). Các sự kiện đã là PascalCase (không có bản đồ sự kiện) và tải trọng là snake_case Claude; chỉ tên công cụ được chuẩn hóa qua `FACTORY_TOOL_MAP` (`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …). Factory cũng là **nguồn kiểm toán offline** — bảng điều khiển đọc các phiên JSONL trên đĩa tại `~/.factory/sessions//.jsonl`. + - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (người dùng), `/.devin/config.json` (dự án) — Devin không có phạm vi `local`. Devin là **bản sao Claude thuần** được xác minh trực tiếp so với devin v3000.1.27: nó sử dụng lược đồ Claude tiêu chuẩn `"hooks"`-wrapper (ghi được bảo toàn hợp nhất để các khóa khác của tệp cấu hình — `org_id`, `theme_mode`, … — tồn tại), các tên sự kiện đã là PascalCase (không có bản đồ sự kiện, không có nhánh trình xử lý) và tải trọng stdin snake_case Claude (không chuẩn hóa). Nhánh `devin` của bộ đánh giá từ chối với JSON `{"decision":"block","reason"}` trên stdout ở thoát 0 cho **mọi** sự kiện (được xác minh — khối ghi đè `--permission-mode dangerous`); trên sự kiện cuối lượt `Stop` lý do mang từ ngữ thử lại lực bắt buộc để các tích hợp sẵn `require-*-before-stop` thực thi. Chỉ tên công cụ được chuẩn hóa qua `DEVIN_TOOL_MAP` (`exec→Bash`; `tool_input.command` đã là canonical). Devin cũng là **nguồn kiểm toán offline** — bảng điều khiển đọc các phiên SQLite tại `~/.local/share/devin/cli/sessions.db` (mỗi hàng `sessions` mang một thực `working_directory`, vì vậy các phiên nhóm theo dự án cwd như Claude). + - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (người dùng), `/.agents/hooks.json` (dự án) — Antigravity không có phạm vi `local`. Không giống như Factory/Devin, Antigravity có **hợp đồng của riêng nó** (không phải bản sao Claude), được xác minh trực tiếp so với agy v1.1.2. `hooks.json` sử dụng lược đồ **hook được đặt tên**: khóa cấp cao nhất là tên hook (*`"failproofai"`) có giá trị là sự kiện → bản đồ trình xử lý — các sự kiện công cụ (`PreToolUse`/`PostToolUse`) gói trình xử lý trong `{matcher:"*", hooks:[…]}`, trong khi `PreInvocation`/`Stop` là **mảng trình xử lý phẳng** (các hook được đặt tên khác được bảo toàn). Tải trọng stdin là **protojson camelCase** (`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`) — failproofai chuẩn hóa nó thành snake_case trước khi các chính sách chạy và ánh xạ arg PascalCase của `run_command` (`CommandLine`/`Cwd`) qua `ANTIGRAVITY_TOOL_INPUT_MAP`. Nhánh `antigravity` của bộ đánh giá sử dụng hình dạng phản hồi **của riêng Antigravity**: `{decision:"deny", reason}` chặn một công cụ/nhắc nhở (thoát 0), `{decision:"continue", reason}` trên sự kiện cuối lượt `Stop` nhập lại vòng lặp (vì vậy các tích hợp sẵn `require-*-before-stop` thực thi), và `{injectSteps:[{ephemeralMessage}]}` tiêm hướng dẫn trên `PreInvocation` (→ `UserPromptSubmit`). Tên công cụ chuẩn hóa qua `ANTIGRAVITY_TOOL_MAP` (`run_command→Bash`, `view_file→Read`, …). Antigravity cũng là **nguồn kiểm toán offline** — bảng điều khiển đọc bản ghi JSONL thuần của nó tại `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` (chỉ mục cuộc trò chuyện trong `conversation_summaries.db`). + - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (người dùng), `/.agents/plugins/failproofai/hooks/hooks.json` (dự án) — Goose không có phạm vi `local`. Thực thi sử dụng hệ thống **hook** của Goose, spécification **Open Plugins** đa tác nhân: trình cài đặt chỉ thả thư mục plugin `failproofai` và Goose tự động phát hiện nó khi khởi động (tự đăng ký nó vào `~/.config/goose/config.yaml`). `hooks.json` sử dụng lược đồ Open Plugins **với** wrapper `"hooks"` cấp cao nhất, và matcher được **bỏ qua** trên mỗi sự kiện — `"*"` trần là regex không hợp lệ không khớp với gì cả (được xác minh trực tiếp so với goose v1.43.0). Tên sự kiện đã là PascalCase (không có bản đồ sự kiện); tải trọng stdin sử dụng `event`/`working_dir`, mà trình xử lý chuẩn hóa thành `hook_event_name`/`cwd`. Nhánh `goose` của bộ đánh giá từ chối với JSON `{"decision":"block","reason"}` trên stdout ở thoát 0, được tôn trọng trên sự kiện **`PreToolUse`** duy nhất (được gửi trong goose ≥ v1.37.0) — kích hoạt cho công cụ shell **và bên trong các đại lý phụ được ủy quyền**, vì vậy nó là điểm từ chối đơn lẻ đủ; bất kỳ lỗi hook khác không hoạt động **mở**. Goose có **không có sự kiện `Stop`**, vì vậy các tích hợp sẵn `require-*-before-stop` không áp dụng (như với Hermes). Tên công cụ chuẩn hóa qua `GOOSE_TOOL_MAP` (`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …) và khóa đường dẫn qua `GOOSE_TOOL_INPUT_MAP` (`path`/`source` → `file_path`). Goose cũng là **nguồn kiểm toán offline** — bảng điều khiển đọc các phiên SQLite tại `~/.local/share/goose/sessions/sessions.db` (mỗi hàng `sessions` mang một thực `working_dir`, vì vậy các phiên nhóm theo dự án cwd như Devin; các lượt `--no-session` bị lọc). -- **Cài đặt Agent CLI** — cho agent biết gọi `failproofai --hook ` trên mỗi tool use: - - **Claude Code**: `~/.claude/settings.json` (user), `/.claude/settings.json` (project), `/.claude/settings.local.json` (local) - - **OpenAI Codex**: `~/.codex/hooks.json` (user), `/.codex/hooks.json` (project) — Codex không có phạm vi `local` - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (user), `/.github/hooks/failproofai.json` (project) — Copilot không có phạm vi `local`. Các mục nhập hook sử dụng các trường lệnh `bash`/`powershell` được khóa bằng OS của Copilot với `timeoutSec`; tệp có dấu hiệu `version: 1` ở cấp cao nhất. Hỗ trợ Copilot CLI đang ở **beta** khi chúng tôi xác minh lược đồ bản ghi `events.jsonl` (không được tài liệu công khai chỉ định) so với các phiên làm việc thực tế hơn. - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — Cursor không có phạm vi `local`. Các mục nhập hook sử dụng dạng `{type, command, timeout}` tương tự Claude (không chia tách `bash`/`powershell`), nhưng được lưu trữ dưới các khóa sự kiện camelCase (`preToolUse`, `beforeSubmitPrompt`, …) trong một mảng phẳng theo [schemas hooks](https://cursor.com/docs/hooks) của Cursor; tệp có dấu hiệu `version: 1` ở cấp cao nhất. Trình xử lý chuẩn hóa camelCase → PascalCase qua `CURSOR_EVENT_MAP` vì vậy các chính sách built-in hiện có kích hoạt không thay đổi. Hỗ trợ Cursor Agent đang ở **beta** khi chúng tôi xác minh định dạng transcript trên đĩa của Cursor (không được chỉ định trong tài liệu công khai) so với các cài đặt thực tế hơn. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (user), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (project) — OpenCode không có phạm vi `local`. Không giống như năm CLI khác, OpenCode **không có hệ thống hook lệnh bên ngoài**: nó tải các plugin JS/TS in-process được đăng ký rõ ràng qua mảng `plugin: []` trong `opencode.json` (tự động phát hiện từ `.opencode/plugins/` **không** là cách các plugin tải trên opencode v1.14.33). Cài đặt thả một shim plugin nhỏ được tạo ra gọi đến nhị phân failproofai qua subprocess và dịch phản hồi JSON hình dạng Claude của nhị phân trở lại ngữ nghĩa plugin: `throw new Error()` cho tool-event deny (hủy lệnh gọi công cụ), `client.session.prompt(...)` cho instruct VÀ cho `Stop` / `SubagentStop` deny (gửi lý do từ chối dưới dạng thông báo người dùng tiếp theo — kênh thử lại buộc duy nhất vì `session.idle` chỉ là thông báo và ném từ nó là no-op), và no-op cho allow. Shim chuẩn hóa cả tên công cụ (chữ thường → PascalCase qua `OPENCODE_TOOL_MAP`) và khóa đối số đầu vào công cụ (camelCase → snake_case qua `OPENCODE_TOOL_INPUT_MAP` cho `Read` / `Write` / `Edit`, ví dụ: `filePath` → `file_path`, `oldString` → `old_string`) trước khi chuyển tiếp đến nhị phân, vì vậy các built-in kiểm tra đường dẫn như `block-read-outside-cwd`, `block-env-files` và `block-secrets-write` kích hoạt không thay đổi trên các lệnh gọi công cụ OpenCode. Các phiên tồn tại trong cơ sở dữ liệu SQLite của opencode tại `~/.local/share/opencode/opencode.db`; người xem phiên của bảng điều khiển đọc chúng qua `opencode db --format json` và `opencode export `. Hỗ trợ OpenCode đang ở **beta** khi chúng tôi xác minh hành vi trên các phiên bản và so với các phiên làm việc thực tế hơn. Xem [tài liệu plugins OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `/.pi/settings.json` (project) — Pi không có phạm vi `local`. Pi tải các gói mở rộng TypeScript khi khởi động; tệp cài đặt là một mảng chuỗi phẳng `{"packages": ["./relative/path", …]}`. failproofai viết một mục nhập mảng package duy nhất trỏ vào thư mục `pi-extension/` được đóng gói của nó. Tiện ích mở rộng bên trong đăng ký các sự kiện `tool_call` / `user_bash` / `input` / `session_start` của Pi và shell ra `failproofai --hook --cli pi`; trình xử lý chuẩn hóa underscore_lower_snake_case → PascalCase qua `PI_EVENT_MAP` vì vậy các chính sách built-in hiện có kích hoạt không thay đổi. Các đối số đầu vào công cụ cũng được chuẩn hóa qua `PI_TOOL_INPUT_MAP` (Read / Write / Edit của Pi cung cấp `path` thay vì `file_path`; ánh xạ khóa cấp cao nhất cho phép `block-env-files` và `block-secrets-write` kích hoạt — `block-read-outside-cwd` đã có fallback `path`). Hỗ trợ Pi đang ở **beta** khi Pi's extension API và layout nhật ký phiên ổn định. - - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**phạm vi người dùng duy nhất** — Hermes không có cấu hình dự án/cục bộ). Hermes là một **cổng** Slack/Telegram, vì vậy một cài đặt chặn các lệnh gọi công cụ từ mọi nền tảng (Slack/Telegram/cli/cron) **và** các subagent nội bộ. Các mục nhập hook là một cặp `{command, timeout}` (timeout tính bằng **giây**) dưới bản đồ `hooks:` được khóa bằng các sự kiện snake_case của Hermes (`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`); trình xử lý chuẩn hóa các sự kiện qua `HERMES_EVENT_MAP` và tên công cụ qua `HERMES_TOOL_MAP` vì vậy các chính sách built-in kích hoạt không thay đổi. Cấu hình được chỉnh sửa thông qua vòng quay YAML `Document` bảo tồn nhận xét vì vậy các cài đặt khác của nhà điều hành sống sót, và cài đặt đặt `hooks_auto_accept: true` vì vậy cổng headless (không TTY) chạy các hook mà không có lời nhắc đồng ý. Trình đánh giá phát hành hợp đồng stdout `{"decision":"block","reason"}` của Hermes (Hermes bỏ qua mã thoát). **Hạn chế:** Hermes không có sự kiện `Stop` kết thúc lượt, vì vậy các built-in `require-*-before-stop` không bao giờ kích hoạt cho nó (không áp dụng được, không bị hỏng); `instruct` suy giảm thành allow-with-logged-note (không có kênh ngữ cảnh bổ sung); và redaction bí mật đầu ra (`sanitize-*`) không thể viết lại đầu ra công cụ trên hợp đồng shell-hook. Hermes cũng là một nguồn **audit** **ngoại tuyến** — bảng điều khiển đọc các phiên cổng của nó trực tiếp từ `~/.hermes/state.db`. -- **`policies-config.json`** — cho failproofai biết những chính sách nào cần đánh giá và với những tham số nào (chia sẻ trên tất cả các CLI agent) +- **`policies-config.json`** — cho failproofai biết chính sách nào để đánh giá và với những tham số nào (được chia sẻ trên tất cả các CLI đại lý) -Chuyển `--cli claude|codex|copilot|cursor|opencode|pi|hermes` để nhắm vào một agent cụ thể (cách nhau bằng dấu cách hoặc lặp lại cho bất kỳ tập con nào): +Chuyển `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` để nhắm vào một đại lý cụ thể (được phân tách bằng dấu cách hoặc lặp lại cho bất kỳ tập con nào): ```bash failproofai policies --install --cli codex --scope project @@ -210,17 +218,22 @@ failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli hermes --scope user -failproofai policies --install --cli claude codex copilot cursor opencode pi +failproofai policies --install --cli openclaw --scope user +failproofai policies --install --cli factory --scope project +failproofai policies --install --cli devin --scope project +failproofai policies --install --cli antigravity --scope project +failproofai policies --install --cli goose --scope project +failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -Khi `--cli` bị bỏ qua, `failproofai` phát hiện những agent CLI nào được cài đặt (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`): +Khi `--cli` được bỏ qua, `failproofai` phát hiện CLI đại lý nào được cài đặt (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`): - **Một CLI được phát hiện** — tự động chọn CLI đó mà không cần nhắc. -- **Nhiều CLI được phát hiện** trong terminal tương tác — hiển thị lời nhắc lựa chọn đơn có mũi tên được nhóm thành phần Detected (N) (với hàng tổng hợp Cài đặt cho tất cả N detected + từng CLI được phát hiện riêng lẻ) và phần Not installed (M) · install hooks ahead of time liệt kê mỗi CLI được hỗ trợ không được phát hiện dưới dạng tùy chọn cài đặt trước (↑↓ để di chuyển, Enter để chọn, ^C để thoát). Dòng gỡ cài đặt chỉ hiển thị phần Detected. -- **Nhiều CLI được phát hiện** trong chạy không tương tác (CI, không TTY) — cài đặt cho tất cả các CLI được phát hiện mà không cần nhắc. -- **Không phát hiện được** — quay lại `claude`, có cảnh báo rằng không tìm thấy nhị phân agent nào trong PATH; lệnh hook vẫn được viết vì vậy nó kích hoạt ngay khi bạn cài đặt một. +- **Nhiều CLI được phát hiện** trong thiết bị đầu cuối tương tác — hiển thị lời nhắc chọn đơn với mũi tên-phím được nhóm thành phần `Detected (N)` (với hàng tổng hợp `Install for all N detected` + từng CLI được phát hiện riêng lẻ) và phần `Not installed (M) · install hooks ahead of time` liệt kê mọi CLI được hỗ trợ nhưng chưa được phát hiện dưới dạng tùy chọn cài đặt phía trước (↑↓ để di chuyển, Enter để chọn, ^C để thoát). Luồng gỡ cài đặt chỉ hiển thị phần Phát hiện. +- **Nhiều CLI được phát hiện** trong lần chạy không tương tác (CI, không TTY) — cài đặt cho tất cả các CLI được phát hiện mà không cần nhắc. +- **Không được phát hiện** — quay lại `claude`, với cảnh báo rằng không tìm thấy nhị phân đại lý nào trong PATH; lệnh hook vẫn được ghi để nó kích hoạt ngay khi bạn cài đặt một. -Bạn có thể chỉnh sửa `policies-config.json` trực tiếp bất kỳ lúc nào; những thay đổi có hiệu lực ngay lập tức vào sự kiện hook tiếp theo mà không cần khởi động lại. +Bạn có thể chỉnh sửa `policies-config.json` trực tiếp bất kỳ lúc nào; các thay đổi có hiệu lực ngay lập tức trên sự kiện hook tiếp theo mà không cần khởi động lại. --- @@ -245,4 +258,4 @@ Cam kết `.failproofai/policies-config.json` vào kho lưu trữ của bạn: } ``` -Mỗi nhà phát triển sau đó có thể tạo `.failproofai/policies-config.local.json` (gitignored) để ghi đè cá nhân mà không ảnh hưởng đến đồng đội. \ No newline at end of file +Mỗi nhà phát triển sau đó có thể tạo `.failproofai/policies-config.local.json` (gitignored) cho các ghi đè cá nhân mà không ảnh hưởng đến các thành viên trong nhóm. \ No newline at end of file diff --git a/docs/vi/custom-policies.mdx b/docs/vi/custom-policies.mdx index ffb18d56..209412d6 100644 --- a/docs/vi/custom-policies.mdx +++ b/docs/vi/custom-policies.mdx @@ -1,10 +1,10 @@ --- -title: Các Chính Sách Tùy Chỉnh -description: "Viết các quy tắc riêng của bạn bằng JavaScript - thực thi quy ước, ngăn chặn sai lệch, phát hiện sự cố, tích hợp với các hệ thống bên ngoài" +title: Chính sách tùy chỉnh +description: "Viết các quy tắc của riêng bạn bằng JavaScript - thực thi quy ước, ngăn chặn dịch chuyển, phát hiện lỗi, tích hợp với các hệ thống bên ngoài" icon: code --- -Các chính sách tùy chỉnh cho phép bạn viết các quy tắc cho bất kỳ hành vi nào của agent: thực thi quy ước dự án, ngăn chặn sai lệch, gated các hoạt động hủy diệt, phát hiện agent bị kẹt, hoặc tích hợp với Slack, quy trình phê duyệt, và nhiều hơn nữa. Chúng sử dụng cùng hệ thống sự kiện hook và các quyết định `allow`, `deny`, `instruct` như các chính sách tích hợp sẵn. +Chính sách tùy chỉnh cho phép bạn viết các quy tắc cho bất kỳ hành vi agent nào: thực thi quy ước dự án, ngăn chặn dịch chuyển, gated cho các hoạt động phá huỷ, phát hiện agent bị kẹt, hoặc tích hợp với Slack, quy trình phê duyệt, và nhiều hơn nữa. Chúng sử dụng cùng một hệ thống sự kiện hook và các quyết định `allow`, `deny`, `instruct` như các chính sách tích hợp. --- @@ -37,11 +37,11 @@ failproofai policies --install --custom ./my-policies.js --- -## Hai cách để tải các chính sách tùy chỉnh +## Hai cách để tải chính sách tùy chỉnh ### Tùy chọn 1: Dựa trên quy ước (được khuyến nghị) -Đặt các tệp `*policies.{js,mjs,ts}` vào `.failproofai/policies/` và chúng sẽ được tải tự động — không cần cờ hoặc thay đổi cấu hình. Điều này hoạt động giống như git hooks: đặt một tệp, nó chỉ hoạt động. +Thả các tệp `*policies.{js,mjs,ts}` vào `.failproofai/policies/` và chúng sẽ được tải tự động — không cần cờ hoặc thay đổi cấu hình. Điều này hoạt động giống như git hooks: thả một tệp, nó hoạt động. ``` # Project level — committed to git, shared with the team @@ -53,14 +53,14 @@ failproofai policies --install --custom ./my-policies.js ``` **Cách nó hoạt động:** -- Cả hai thư mục dự án và người dùng được quét (union — không phải first-scope-wins) -- Các tệp được tải theo thứ tự bảng chữ cái trong mỗi thư mục. Thêm tiền tố `01-`, `02-` để kiểm soát thứ tự -- Chỉ các tệp khớp với `*policies.{js,mjs,ts}` được tải; các tệp khác bị bỏ qua -- Mỗi tệp được tải độc lập (fail-open cho mỗi tệp) -- Hoạt động cùng với các chính sách `--custom` và tích hợp sẵn rõ ràng +- Cả thư mục dự án và người dùng đều được quét (hợp nhất — không phạm vi đầu tiên) +- Các tệp được tải theo thứ tự bảng chữ cái trong mỗi thư mục. Đặt tiền tố bằng `01-`, `02-` để kiểm soát thứ tự +- Chỉ các tệp phù hợp với `*policies.{js,mjs,ts}` được tải; các tệp khác bị bỏ qua +- Mỗi tệp được tải độc lập (mở không lỗi cho mỗi tệp) +- Hoạt động cùng với các chính sách `--custom` và tích hợp rõ ràng -Các chính sách theo quy ước là cách dễ nhất để xây dựng một tiêu chuẩn chất lượng cho tổ chức của bạn. Commit `.failproofai/policies/` vào git và mỗi thành viên trong nhóm sẽ tự động nhận các quy tắc giống nhau — không cần thiết lập cho từng nhà phát triển. Khi nhóm của bạn phát hiện ra các chế độ lỗi mới, hãy thêm một chính sách và đẩy lên. Theo thời gian, chúng trở thành một tiêu chuẩn chất lượng sống động tiếp tục cải thiện với mỗi đóng góp. +Chính sách quy ước là cách dễ nhất để xây dựng một tiêu chuẩn chất lượng cho tổ chức của bạn. Commit `.failproofai/policies/` vào git và mỗi thành viên trong nhóm sẽ tự động nhận cùng các quy tắc — không cần thiết lập cho từng nhà phát triển. Khi nhóm của bạn phát hiện các chế độ lỗi mới, hãy thêm một chính sách và push. Theo thời gian, những chính sách này trở thành một tiêu chuẩn chất lượng sống động không ngừng cải thiện với mỗi đóng góp. ### Tùy chọn 2: Đường dẫn tệp rõ ràng @@ -69,28 +69,33 @@ Các chính sách theo quy ước là cách dễ nhất để xây dựng một # Install with a custom policies file failproofai policies --install --custom ./my-policies.js -# Replace the policies file path +# Replace the custom policy paths failproofai policies --install --custom ./new-policies.js -# Remove the custom policies path from config +# Configure multiple explicit files (loaded in flag order) +failproofai policies --install --custom ./security.js --custom ./workflow.js + +# Remove all explicit custom policy paths from config failproofai policies --uninstall --custom ``` -Đường dẫn tuyệt đối được phân giải được lưu trữ trong `policies-config.json` như `customPoliciesPath`. Tệp được tải mới trên mỗi sự kiện hook - không có bộ nhớ cache giữa các sự kiện. +Các đường dẫn tuyệt đối được giải quyết được lưu trữ trong `policies-config.json` dưới dạng `customPoliciesPaths`. Lặp lại `--custom` để cấu hình nhiều tệp. Các cấu hình hiện tại sử dụng trường `customPoliciesPath` cũ vẫn tiếp tục hoạt động. Các tệp được tải mới trên mỗi sự kiện hook - không có bộ nhớ đệm giữa các sự kiện. + +Mỗi chính sách đã đăng ký xuất hiện với bộ chuyển đổi riêng của nó trong bảng điều khiển. Chuyển đổi một chính sách sẽ ghi lại ID có tên là nguồn trong `disabledCustomPolicies`; tệp và các chính sách khác của nó tiếp tục tải, trong khi chính sách bị vô hiệu hóa bị loại trừ trước khi khớp sự kiện. Các tên chính sách được nhân đôi trên các tệp có các bộ chuyển đổi độc lập. ### Sử dụng cả hai cùng nhau -Các chính sách theo quy ước và tệp `--custom` rõ ràng có thể coexist. Thứ tự tải: +Các chính sách quy ước và các tệp `--custom` rõ ràng có thể coexist. Thứ tự tải: -1. Tệp `customPoliciesPath` rõ ràng (nếu được cấu hình) -2. Các tệp quy ước dự án (`{cwd}/.failproofai/policies/`, theo thứ tự bảng chữ cái) -3. Các tệp quy ước người dùng (`~/.failproofai/policies/`, theo thứ tự bảng chữ cái) +1. Các tệp `customPoliciesPaths` rõ ràng (theo thứ tự được cấu hình) +2. Các tệp quy ước dự án (`{cwd}/.failproofai/policies/`, bảng chữ cái) +3. Các tệp quy ước người dùng (`~/.failproofai/policies/`, bảng chữ cái) --- ## API -### Import +### Nhập ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -98,7 +103,7 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Đăng ký một chính sách. Gọi hàm này bao nhiêu lần tùy ý cho nhiều chính sách trong cùng một tệp. +Đăng ký một chính sách. Gọi hàm này nhiều lần nếu cần cho nhiều chính sách trong cùng một tệp. ```ts customPolicies.add({ @@ -113,30 +118,30 @@ customPolicies.add({ | Hàm | Hiệu ứng | Sử dụng khi | |----------|--------|----------| -| `allow()` | Cho phép hoạt động im lặng | Hành động an toàn, không cần thông báo | +| `allow()` | Cho phép hoạt động im lặng | Hành động an toàn, không cần tin nhắn | | `deny(message)` | Chặn hoạt động | Agent không nên thực hiện hành động này | -| `instruct(message)` | Thêm ngữ cảnh mà không chặn | Cung cấp ngữ cảnh bổ sung cho agent để tiếp tục theo dõi | +| `instruct(message)` | Thêm ngữ cảnh mà không chặn | Cung cấp cho agent ngữ cảnh bổ sung để giữ trên đúng hướng | -`deny(message)` - thông báo xuất hiện cho Claude với tiền tố `"Blocked by failproofai:"`. Một `deny` duy nhất sẽ short-circuit tất cả các đánh giá tiếp theo. +`deny(message)` - tin nhắn xuất hiện cho Claude với tiền tố `"Blocked by failproofai:"`. Một `deny` duy nhất sẽ ngắt tất cả các đánh giá tiếp theo. -`instruct(message)` - thông báo được nối vào ngữ cảnh của Claude cho lệnh gọi công cụ hiện tại. Tất cả các thông báo `instruct` được tích lũy và cung cấp cùng nhau. +`instruct(message)` - tin nhắn được nối vào ngữ cảnh của Claude cho lệnh gọi công cụ hiện tại. Tất cả các tin nhắn `instruct` được tích lũy và gửi cùng nhau. -Bạn có thể nối thêm hướng dẫn vào bất kỳ thông báo `deny` hoặc `instruct` nào bằng cách thêm trường `hint` trong `policyParams` — không cần thay đổi mã. Điều này hoạt động cho các chính sách tùy chỉnh (`custom/`), quy ước dự án (`.failproofai-project/`), và quy ước người dùng (`.failproofai-user/`) cũng vậy. Xem [Configuration → hint](/vi/configuration#hint-cross-cutting) để biết chi tiết. +Bạn có thể nối thêm hướng dẫn vào bất kỳ tin nhắn `deny` hoặc `instruct` nào bằng cách thêm một trường `hint` trong `policyParams` — không cần thay đổi mã. Điều này cũng hoạt động cho các chính sách tùy chỉnh (`custom/`), quy ước dự án (`.failproofai-project/`), và quy ước người dùng (`.failproofai-user/`). Xem [Configuration → hint](/vi/configuration#hint-cross-cutting) để biết chi tiết. -### Thông báo allow thông tin +### Tin nhắn allow thông tin -`allow(message)` cho phép hoạt động **và** gửi thông báo thông tin lại cho Claude. Thông báo được cung cấp như `additionalContext` trong phản hồi stdout của trình xử lý hook — cơ chế tương tự được sử dụng bởi `instruct`, nhưng khác nhau về mặt ngữ nghĩa: đó là một cập nhật trạng thái, không phải một cảnh báo. +`allow(message)` cho phép hoạt động **và** gửi một tin nhắn thông tin lại cho Claude. Tin nhắn được gửi dưới dạng `additionalContext` trong phản hồi stdout của trình xử lý hook — cơ chế tương tự được sử dụng bởi `instruct`, nhưng khác về mặt ngữ nghĩa: đó là cập nhật trạng thái, không phải cảnh báo. | Hàm | Hiệu ứng | Sử dụng khi | |----------|--------|----------| -| `allow(message)` | Cho phép và gửi ngữ cảnh cho Claude | Xác nhận kiểm tra đã vượt qua, hoặc giải thích tại sao kiểm tra bị bỏ qua | +| `allow(message)` | Cho phép và gửi ngữ cảnh cho Claude | Xác nhận kiểm tra đã vượt qua, hoặc giải thích lý do kiểm tra bị bỏ qua | -Trường hợp sử dụng: -- **Xác nhận trạng thái:** `allow("All CI checks passed.")` — cho Claude biết mọi thứ đều bình thường -- **Giải thích fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — cho Claude biết tại sao kiểm tra bị bỏ qua để nó có bối cảnh đầy đủ -- **Nhiều thông báo tích lũy:** nếu một số chính sách mỗi cái trả về `allow(message)`, tất cả thông báo được nối với các dòng mới và cung cấp cùng nhau +Các trường hợp sử dụng: +- **Xác nhận trạng thái:** `allow("All CI checks passed.")` — cho Claude biết mọi thứ đều tốt +- **Giải thích mở không lỗi:** `allow("GitHub CLI not installed, skipping CI check.")` — cho Claude biết lý do kiểm tra bị bỏ qua để nó có toàn bộ ngữ cảnh +- **Nhiều tin nhắn tích lũy:** nếu một số chính sách trả về `allow(message)`, tất cả các tin nhắn được kết hợp bằng các dòng mới và gửi cùng nhau ```js customPolicies.add({ @@ -160,9 +165,9 @@ customPolicies.add({ | Trường | Loại | Mô tả | |-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | Công cụ đang được gọi (ví dụ: `"Bash"`, `"Write"`, `"Read"`) | +| `toolName` | `string \| undefined` | Công cụ được gọi (ví dụ: `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | Các tham số đầu vào của công cụ | -| `payload` | `Record` | Payload sự kiện thô đầy đủ từ Claude Code | +| `payload` | `Record` | Toàn bộ tải sự kiện thô từ Claude Code | | `session` | `SessionMetadata \| undefined` | Ngữ cảnh phiên (xem bên dưới) | ### Các trường `SessionMetadata` @@ -171,14 +176,14 @@ customPolicies.add({ |-------|------|-------------| | `sessionId` | `string` | Định danh phiên Claude Code | | `cwd` | `string` | Thư mục làm việc của phiên Claude Code | -| `transcriptPath` | `string` | Đường dẫn đến tệp bản ghi JSONL của phiên | +| `transcriptPath` | `string` | Đường dẫn đến tệp JSONL thảo luận của phiên | ### Các loại sự kiện | Sự kiện | Khi nó kích hoạt | Nội dung `toolInput` | |-------|--------------|----------------------| | `PreToolUse` | Trước khi Claude chạy một công cụ | Đầu vào của công cụ (ví dụ: `{ command: "..." }` cho Bash) | -| `PostToolUse` | Sau khi một công cụ hoàn tất | Đầu vào của công cụ + `tool_result` (đầu ra) | +| `PostToolUse` | Sau khi một công cụ hoàn thành | Đầu vào của công cụ + `tool_result` (đầu ra) | | `Notification` | Khi Claude gửi một thông báo | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks phải luôn trả về `allow()`, chúng không thể chặn thông báo | | `Stop` | Khi phiên Claude kết thúc | Trống | @@ -188,20 +193,20 @@ customPolicies.add({ Các chính sách được đánh giá theo thứ tự này: -1. Các chính sách tích hợp sẵn (theo thứ tự định nghĩa) -2. Các chính sách tùy chỉnh rõ ràng từ `customPoliciesPath` (theo thứ tự `.add()`) -3. Các chính sách quy ước từ `.failproofai/policies/` dự án (tệp theo thứ tự bảng chữ cái, thứ tự `.add()` bên trong) -4. Các chính sách quy ước từ `~/.failproofai/policies/` người dùng (tệp theo thứ tự bảng chữ cái, thứ tự `.add()` bên trong) +1. Chính sách tích hợp (theo thứ tự định nghĩa) +2. Chính sách tùy chỉnh rõ ràng từ `customPoliciesPath` (theo thứ tự `.add()`) +3. Chính sách quy ước từ dự án `.failproofai/policies/` (tệp theo thứ tự bảng chữ cái, thứ tự `.add()` bên trong) +4. Chính sách quy ước từ người dùng `~/.failproofai/policies/` (tệp theo thứ tự bảng chữ cái, thứ tự `.add()` bên trong) -`deny` đầu tiên short-circuits tất cả các chính sách sau. Tất cả các thông báo `instruct` được tích lũy và cung cấp cùng nhau. +`deny` đầu tiên sẽ ngắt tất cả các chính sách tiếp theo. Tất cả các tin nhắn `instruct` được tích lũy và gửi cùng nhau. --- -## Các import chuyển tiếp +## Nhập transitive -Các tệp chính sách tùy chỉnh có thể import các mô-đun cục bộ bằng cách sử dụng các đường dẫn tương đối: +Các tệp chính sách tùy chỉnh có thể nhập các mô-đun cục bộ bằng các đường dẫn tương đối: ```js // my-policies.js @@ -218,13 +223,13 @@ customPolicies.add({ }); ``` -Tất cả các import tương đối có thể truy cập từ tệp entry được giải quyết. Điều này được thực hiện bằng cách viết lại các import `from "failproofai"` sang đường dẫn dist thực tế và tạo các tệp `.mjs` tạm thời để đảm bảo khả năng tương thích ESM. +Tất cả các nhập tương đối có thể được truy cập từ tệp nhập được giải quyết. Điều này được thực hiện bằng cách viết lại các nhập `from "failproofai"` vào đường dẫn dist thực tế và tạo các tệp `.mjs` tạm thời để đảm bảo tương thích ESM. --- ## Lọc loại sự kiện -Sử dụng `match.events` để giới hạn khi một chính sách kích hoạt: +Sử dụng `match.events` để giới hạn khi nào một chính sách kích hoạt: ```js customPolicies.add({ @@ -244,20 +249,20 @@ Bỏ qua `match` hoàn toàn để kích hoạt trên mọi loại sự kiện. ## Xử lý lỗi và các chế độ lỗi -Các chính sách tùy chỉnh là **fail-open**: các lỗi không bao giờ chặn các chính sách tích hợp sẵn hoặc làm crash trình xử lý hook. +Chính sách tùy chỉnh **mở không lỗi**: lỗi không bao giờ chặn các chính sách tích hợp hoặc làm hỏng trình xử lý hook. | Lỗi | Hành vi | |---------|----------| -| `customPoliciesPath` không được đặt | Không có chính sách tùy chỉnh rõ ràng chạy; các chính sách quy ước và tích hợp sẵn tiếp tục bình thường | -| Tệp không tìm thấy | Cảnh báo được ghi vào `~/.failproofai/hook.log`; tích hợp sẵn tiếp tục | -| Lỗi cú pháp/import (rõ ràng) | Lỗi được ghi vào `~/.failproofai/hook.log`; chính sách tùy chỉnh rõ ràng bị bỏ qua | -| Lỗi cú pháp/import (quy ước) | Lỗi được ghi; tệp đó bị bỏ qua, các tệp quy ước khác vẫn tải | -| `fn` ném lỗi khi chạy | Lỗi được ghi; hook đó được coi là `allow`; các hook khác tiếp tục | -| `fn` mất hơn 10 giây | Timeout được ghi; được coi là `allow` | +| `customPoliciesPath` không được đặt | Không có chính sách tùy chỉnh rõ ràng chạy; các chính sách quy ước và tích hợp tiếp tục bình thường | +| Tệp không tìm thấy | Cảnh báo được ghi vào `~/.failproofai/hook.log`; các tích hợp tiếp tục | +| Lỗi cú pháp/nhập (rõ ràng) | Lỗi được ghi vào `~/.failproofai/hook.log`; các chính sách tùy chỉnh rõ ràng bị bỏ qua | +| Lỗi cú pháp/nhập (quy ước) | Lỗi được ghi; tệp đó bị bỏ qua, các tệp quy ước khác vẫn tải | +| `fn` ném lỗi tại thời gian chạy | Lỗi được ghi; hook đó được coi là `allow`; các hook khác tiếp tục | +| `fn` mất quá 10 giây | Timeout được ghi; được coi là `allow` | | Thư mục quy ước bị thiếu | Không có chính sách quy ước chạy; không có lỗi | -Để gỡ lỗi các lỗi chính sách tùy chỉnh, hãy theo dõi tệp nhật ký: +Để gỡ lỗi các lỗi chính sách tùy chỉnh, hãy xem tệp nhật ký: ```bash tail -f ~/.failproofai/hook.log @@ -328,9 +333,9 @@ Thư mục `examples/` chứa các tệp chính sách sẵn sàng chạy: | Tệp | Nội dung | |------|----------| | `examples/policies-basic.js` | Năm chính sách khởi động bao gồm các chế độ lỗi agent phổ biến | -| `examples/policies-advanced/index.js` | Các mẫu nâng cao: import chuyển tiếp, lệnh gọi không đồng bộ, loại bỏ đầu ra, và hook kết thúc phiên | -| `examples/convention-policies/security-policies.mjs` | Các chính sách bảo mật dựa trên quy ước (chặn ghi .env, ngăn chặn viết lại lịch sử git) | -| `examples/convention-policies/workflow-policies.mjs` | Các chính sách quy trình làm việc dựa trên quy ước (nhắc nhở kiểm tra, tệp kiểm tra lưu trữ) | +| `examples/policies-advanced/index.js` | Các mô hình nâng cao: nhập transitive, lệnh gọi không đồng bộ, xóa đầu ra, và hook kết thúc phiên | +| `examples/convention-policies/security-policies.mjs` | Chính sách bảo mật dựa trên quy ước (chặn ghi .env, ngăn chặn viết lại lịch sử git) | +| `examples/convention-policies/workflow-policies.mjs` | Chính sách quy trình làm việc dựa trên quy ước (nhắc nhở kiểm tra, tệp ghi audit) | ### Sử dụng các ví dụ tệp rõ ràng diff --git a/docs/vi/dashboard.mdx b/docs/vi/dashboard.mdx index 74035dd4..6c13291d 100644 --- a/docs/vi/dashboard.mdx +++ b/docs/vi/dashboard.mdx @@ -4,7 +4,7 @@ description: "Giám sát phiên làm việc của agent, xem lại các lệnh g icon: chart-line --- -Bảng điều khiển failproofai là một ứng dụng web cục bộ để giám sát các phiên làm việc của agent AI và quản lý chính sách. Xem những gì mà các agent của bạn đã làm khi bạn vắng mặt. +Bảng điều khiển failproofai là một ứng dụng web cục bộ để giám sát các phiên làm việc của AI agent và quản lý chính sách. Xem những gì các agent của bạn đã làm trong khi bạn vắng mặt. --- @@ -16,7 +16,7 @@ failproofai Mở tại `http://localhost:8020`. -Bảng điều khiển đọc dữ liệu dự án cục bộ, phiên làm việc và cấu hình failproofai trực tiếp từ hệ thống tệp. Các tính năng được xác thực tùy chọn, chẳng hạn như nhắc nhở kiểm toán và lời mời, gửi thông tin cần thiết cho các yêu cầu đó (bao gồm địa chỉ email) đến các API từ xa. +Bảng điều khiển đọc dữ liệu dự án cục bộ, phiên làm việc và cấu hình failproofai trực tiếp từ hệ thống tệp. Các tính năng tùy chọn có xác thực, như nhắc nhở kiểm toán và lời mời, gửi thông tin cần thiết cho các yêu cầu đó (bao gồm địa chỉ email) đến các API từ xa. --- @@ -24,18 +24,20 @@ Bảng điều khiển đọc dữ liệu dự án cục bộ, phiên làm việ ### Dự án -Liệt kê tất cả Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity và Goose được tìm thấy trên máy của bạn. Các dự án Claude được khám phá từ `~/.claude/projects/` (hoặc đường dẫn được đặt bởi `CLAUDE_PROJECTS_PATH`); các dự án Codex được khám phá bằng cách quét mọi bản ghi ngang hàng dưới `~/.codex/sessions///
/*.jsonl` và nhóm theo `cwd` được ghi trong bản ghi đầu tiên của mỗi phiên; các dự án Copilot CLI được khám phá bằng cách quét mỗi `~/.copilot/session-state//workspace.yaml` (có thể cấu hình qua `COPILOT_HOME`) và nhóm theo trường `cwd` của nó; các dự án Cursor Agent được khám phá bằng cách quét siêu dữ liệu trên mỗi phiên dưới `~/.cursor/agent-sessions//` (có thể cấu hình qua `CURSOR_HOME`, với `conversations/` và `sessions/` được kiểm tra như là phương án dự phòng) để tìm một số vô hướng `cwd` trong `meta.json` / `session.json` / `workspace.yaml`; các dự án OpenCode được khám phá bằng cách truy vấn cơ sở dữ liệu SQLite của nó tại `~/.local/share/opencode/opencode.db` thông qua `opencode db --format json` (chúng tôi đọc bảng `session` và `project` và nhóm theo `project_id`); các dự án Pi được khám phá bằng cách quét bản ghi ngang hàng JSONL trên mỗi phiên dưới `~/.pi/agent/sessions//_.jsonl` (có thể cấu hình qua `PI_SESSIONS_DIR`) và lấy `cwd` từ bản ghi đầu tiên của mỗi phiên; các phiên cổng Hermes được đọc trực tiếp từ kho SQLite của nó tại `~/.hermes/state.db` (có thể cấu hình qua `HERMES_DB_PATH`) và được nhóm vào các dự án `hermes-` theo `source` (Slack/Telegram/cli/cron — các phiên cổng không có cwd); các phiên cổng OpenClaw được đọc từ `~/.openclaw/agents//sessions/*.jsonl` và được nhóm vào các dự án `openclaw-` (cũng không có cwd); các dự án Factory Droid được khám phá từ các bản ghi ngang hàng JSONL tại `~/.factory/sessions//*.jsonl` và được nhóm theo cwd; các dự án Devin từ cơ sở dữ liệu SQLite của nó tại `~/.local/share/devin/cli/sessions.db` (được nhóm theo `working_directory` của mỗi phiên); các dự án Antigravity từ các bản ghi ngang hàng JSONL tại `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` và được nhóm theo cwd; và các dự án Goose từ cơ sở dữ liệu SQLite của nó tại `~/.local/share/goose/sessions/sessions.db` (được nhóm theo `working_dir` của mỗi phiên). Một dự án đã được sử dụng bởi nhiều CLI hiển thị dưới dạng một hàng duy nhất với tất cả các huy hiệu phù hợp. Sử dụng dropdown **CLI** ở trên bảng để lọc theo một CLI agent cụ thể; URL bảo toàn lựa chọn của bạn dưới dạng `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. +Liệt kê tất cả các dự án Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity và Goose được tìm thấy trên máy của bạn. Các dự án Claude được khám phá từ `~/.claude/projects/` (hoặc đường dẫn được đặt bởi `CLAUDE_PROJECTS_PATH`); các dự án Codex được khám phá bằng cách quét mọi bảng ghi âm dưới `~/.codex/sessions///
/*.jsonl` và nhóm theo `cwd` được ghi lại trong bản ghi đầu tiên của mỗi phiên; các dự án Copilot CLI được khám phá bằng cách quét mỗi `~/.copilot/session-state//workspace.yaml` (có thể cấu hình thông qua `COPILOT_HOME`) và nhóm theo trường `cwd` của nó; các dự án Cursor Agent được khám phá bằng cách quét siêu dữ liệu cho mỗi phiên dưới `~/.cursor/agent-sessions//` (có thể cấu hình thông qua `CURSOR_HOME`, với `conversations/` và `sessions/` được thăm dò như các phương án dự phòng) để tìm `cwd` vô hướng trong `meta.json` / `session.json` / `workspace.yaml`; các dự án OpenCode được khám phá bằng cách truy vấn cơ sở dữ liệu SQLite của nó tại `~/.local/share/opencode/opencode.db` thông qua `opencode db --format json` (chúng tôi đọc các bảng `session` và `project` và nhóm theo `project_id`); các dự án Pi được khám phá bằng cách quét các bảng ghi âm JSONL cho mỗi phiên dưới `~/.pi/agent/sessions//_.jsonl` (có thể cấu hình thông qua `PI_SESSIONS_DIR`) và lấy `cwd` từ bản ghi đầu tiên của mỗi phiên; các phiên gateway Hermes được đọc trực tiếp từ kho lưu trữ SQLite của mỗi hồ sơ — `~/.hermes/state.db` cộng với `~/.hermes/profiles//state.db` (có thể ghi đè thông qua `HERMES_HOME` hoặc `HERMES_DB_PATH` cho một cơ sở dữ liệu duy nhất) — và được nhóm thành các dự án `hermes--` theo hồ sơ và `source` (Slack/Telegram/cli/cron — các phiên gateway không có cwd); các phiên gateway OpenClaw được đọc từ `~/.openclaw/agents//sessions/*.jsonl` và được nhóm thành các dự án `openclaw--` theo agent và kênh (cũng không có cwd); các dự án Factory Droid được khám phá từ các bảng ghi âm JSONL tại `~/.factory/sessions//*.jsonl` và được nhóm theo cwd; các dự án Devin từ cơ sở dữ liệu SQLite của nó tại `~/.local/share/devin/cli/sessions.db` (được nhóm theo `working_directory` của mỗi phiên); các dự án Antigravity từ các bảng ghi âm JSONL tại `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` và được nhóm theo cwd; và các dự án Goose từ cơ sở dữ liệu SQLite của nó tại `~/.local/share/goose/sessions/sessions.db` (được nhóm theo `working_dir` của mỗi phiên). Một dự án đã được sử dụng bởi nhiều CLI hiển thị dưới dạng một hàng duy nhất với tất cả các huy hiệu phù hợp. Sử dụng menu thả xuống **CLI** phía trên bảng để lọc theo CLI agent cụ thể; URL bảo tồn lựa chọn của bạn dưới dạng `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`. + +Hermes và OpenClaw có phạm vi người dùng và không có thư mục làm việc để nhóm theo, vì vậy chúng hiển thị dưới dạng **cây thư mục có thể thu gọn** — hồ sơ (hoặc agent) ở cấp cao nhất, các kênh của nó dưới đó — trong khi mọi CLI dựa trên cwd vẫn là một hàng phẳng. Các hàng thư mục cuộn lại số lượng phiên và hoạt động gần đây nhất của tất cả những gì dưới chúng, các thư mục đã thu gọn được ghi nhớ giữa các lần truy cập, và tìm kiếm từ khóa mở rộng bất kỳ thứ gì nó khớp. Mỗi dự án hiển thị: -- Tên dự án (bắt nguồn từ đường dẫn thư mục) -- Huy hiệu CLI — `Claude Code` (cam), `OpenAI Codex` (tím), `GitHub Copilot` (xanh), `Cursor Agent` (ngọc lục bảo), `OpenCode` (hổ phách), `Pi` (hồng), và/hoặc `Hermes` (chàm) +- Tên dự án (dẫn xuất từ đường dẫn thư mục) +- Huy hiệu CLI — `Claude Code` (cam), `OpenAI Codex` (tím), `GitHub Copilot` (xanh lam), `Cursor Agent` (xanh lục), `OpenCode` (hổphách), `Pi` (hồng), và/hoặc `Hermes` (chàm) - Ngày hoạt động phiên gần đây nhất -Nhấp vào một dự án để xem các phiên làm việc của nó. +Nhấp vào một dự án để xem các phiên của nó. ### Phiên làm việc -Liệt kê tất cả các phiên làm việc trong một dự án. Mỗi phiên hiển thị: +Liệt kê tất cả các phiên trong một dự án. Mỗi phiên hiển thị: - ID phiên - Dấu thời gian bắt đầu và kết thúc - Số lượng lệnh gọi công cụ @@ -47,27 +49,27 @@ Nhấp vào một phiên để mở trình xem phiên. ### Trình xem phiên -Trình xem phiên trả lời câu hỏi chính cho các agent tự trị: agent đã làm gì và nó có ở đúng đường hay không? Huy hiệu CLI cạnh tiêu đề cho biết phiên là bản ghi Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity hay Goose. Nó hiển thị một dòng thời gian của mọi thứ xảy ra trong một phiên: +Trình xem phiên trả lời câu hỏi chính cho các agent tự chủ: agent đã làm gì và nó có ở đúng vị trí không? Huy hiệu CLI bên cạnh tiêu đề cho biết phiên đó là bảng ghi âm Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity hay Goose. Nó hiển thị một dòng thời gian của mọi thứ đã xảy ra trong một phiên: -- **Tin nhắn** - Phản hồi văn bản của Claude và lời nhắc của người dùng -- **Lệnh gọi công cụ** - Mỗi công cụ mà Claude gọi, với đầu vào và đầu ra của nó +- **Tin nhắn** - Các phản hồi văn bản của Claude và lời nhắc của người dùng +- **Lệnh gọi công cụ** - Mọi công cụ mà Claude đã gọi, cùng với đầu vào và đầu ra của nó - **Hoạt động chính sách** - Đối với mỗi lệnh gọi công cụ, những chính sách nào đã kích hoạt và quyết định nào mà chúng trả về -Thanh thống kê ở trên cùng hiển thị thời lượng phiên, tổng số lệnh gọi công cụ và tóm tắt quyết định hook (allow / deny / instruct). +Thanh thống kê ở trên cùng hiển thị thời lượng phiên, tổng số lệnh gọi công cụ và tóm tắt các quyết định hook (số lượng allow / deny / instruct). -Nhấp vào nút **Tải xuống nhật ký** để xuất phiên. Đối với các phiên Claude Code, Codex, Copilot, Cursor và Pi, bạn nhận được bản ghi ngang hàng JSONL trên đĩa ban đầu theo từng byte; đối với OpenCode (các phiên của nó nằm trong SQLite, không phải trên đĩa), bạn nhận được một tài liệu JSON phản ánh các bảng `session` / `messages` / `parts` cơ bản. +Nhấp vào nút **Download Logs** để xuất phiên. Đối với các phiên Claude Code, Codex, Copilot, Cursor và Pi, bạn sẽ nhận được bảng ghi âm JSONL trên đĩa ban đầu từng byte; đối với OpenCode (các phiên của nó nằm trong SQLite, không phải trên đĩa), bạn sẽ nhận được tài liệu JSON phản ánh các bảng `session` / `messages` / `parts` cơ bản. ### Kiểm toán -Một báo cáo theo tính cách về cách agent của bạn thực sự hoạt động trên các phiên quá khứ. Chạy cùng một quét như CLI `failproofai audit` nhưng hiển thị nó dưới dạng một áp phích chia sẻ trên một màn hình + bốn phần dưới lớp: +Báo cáo do tính cách thúc đẩy về cách agent của bạn thực sự đã hoạt động trong các phiên trong quá khứ. Chạy cùng một quét với CLI `failproofai audit` nhưng hiển thị nó dưới dạng một tấm áp phích có thể chia sẻ trên một màn hình + bốn phần phía dưới nếp gấp: -1. **Áp phích** — lấp đầy viewport đầu tiên. Vùng chụp PNG tự chứa với nhãn failproof_ai + kiểm toán · chỉ số nguyên mẫu (`№ NN của 08`) + ngày kiểm toán · điểm số (0–100) + xếp hạng phần trăm pill (`top 15%`) · tên nguyên mẫu (một trong `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + dải 3 từ khóa · `// chỉ N% các agent là nguyên mẫu này` dòng hiếm · ô sigil 8×8 pixel · `audit yours → failproof.ai` chân trang. Ba nút chia sẻ nằm ngoài ô chụp: `post your archetype` (ý định X), `share on linkedin`, `download poster`. Chụp chạy qua `html-to-image` vì vậy PNG khớp với kết xuất trên màn hình từng pixel (đường viền nét đứt, mặt nạ logo SVG, gradient, số liệu phông chữ — tất cả được bảo tồn). -2. **Điểm mạnh** — danh sách hàng tĩnh lặng ✓ của các hành vi mà agent của bạn đã làm đúng, bắt nguồn từ dữ liệu kiểm toán trực tiếp (tỷ lệ lệnh gọi công cụ sạch, không có đẩy trực tiếp đến main, không rò rỉ thông tin xác thực, không có bão thử lại) — mỗi hành vi chỉ được hiển thị khi chính sách liên quan có bản ghi sạch trong cửa sổ kiểm toán. -3. **Những điều kỳ quặc** — bảng những gì trượt qua, xếp hạng theo mức độ nghiêm trọng: `when · what slipped + the policy that would've caught it · severity pill · seen`, trong đó sự lặp lại đọc `new` (một lần), `N× seen` (2–9 lần), hoặc `recurring` (10+). -4. **Cách cải thiện** — danh sách hàng tĩnh lặng, mỗi chính sách được quy định: tên chính sách màu trắng, mô tả một dòng, lệnh cài đặt + nút sao chép ở phía bên phải. Tiêu đề phần đọc `enable all N → projected · ` (điểm số bạn sẽ đạt được với mọi sửa chữa được áp dụng), và nút `[install all]` của nó sao chép lệnh `failproofai policy add a b c …` kết hợp cho mọi chính sách được quy định. -5. **Quay lại tốt hơn** — hai thẻ song song. Trái: đặt nhắc nhở (`3d` / `7d` / `14d` / `30d` bộ chọn nhịp độ; vẫn được duy trì thông qua `/api/auth/reminder` sau khi xác thực). Phải: mở khóa các quyền lợi failproof — `invite a friend` mở ra một cửa sổ mô-đun lấy danh sách email bạn bè được phân tách bằng dấu phẩy/khoảng trắng/dòng mới (tối đa 10 trên mỗi lần gửi), POSTs để `/api/audit/invite`, chuyển tiếp đến `POST /v0/invite` của máy chủ api. Máy chủ api gửi một email cho mỗi người nhận từ `invite@failproof.ai` với người gửi Cc và `Reply-To` được đặt, vì vậy người nhận thấy ai mời họ và người gửi nhận được bản sao trong hộp thư đến của họ. Người dùng ẩn danh được định tuyến qua `AuthDialog` trước để email của người gửi được biết trước khi lời mời được gửi đi. Lợi ích / thực hiện quyền lợi là một bước tiếp theo. +1. **Tấm áp phích** — lấp đầy khung nhìn đầu tiên. Vùng chụp PNG tự chứa với biểu tượng failproof_ai + nhãn kiểm toán · chỉ số nguyên mẫu (`№ NN of 08`) + ngày kiểm toán · điểm số (0–100) + viên xếp hạng phần trăm (`top 15%`) · tên nguyên mẫu (một trong `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + dải 3 từ khóa · `// only N% of agents are this archetype` dòng hiếm · dạo dộc sigil 8×8 pixel · chân trang `audit yours → failproof.ai`. Ba nút chia sẻ nằm ngay ngoài hộp chụp: `post your archetype` (ý định X), `share on linkedin`, `download poster`. Chụp chạy qua `html-to-image` vì vậy PNG khớp với kết xuất trên màn hình từng pixel (đường viền gạch ngang, mặt nạ logo SVG, gradient, số liệu phông chữ — tất cả được bảo tồn). +2. **Điểm mạnh** — danh sách hàng tĩnh lặng ✓ của các hành vi mà agent của bạn đã làm tốt, dẫn xuất từ dữ liệu kiểm toán trực tiếp (tỷ lệ lệnh gọi công cụ sạch, không có đẩy trực tiếp tới main, không rò rỉ thông tin xác thực, không có bão thử lại) — mỗi cái chỉ được nổi bật khi chính sách liên quan có hồ sơ sạch trên cửa sổ kiểm toán. +3. **Điều kỳ quặc** — bảng những gì lọt qua, xếp hạng theo mức độ nghiêm trọng: `when · what slipped + the policy that would've caught it · severity pill · seen`, trong đó tần suất lặp lại đọc `new` (một lần), `N× seen` (2–9 lần) hoặc `recurring` (10+). +4. **Cách cải thiện** — danh sách hàng tĩnh lặng, mỗi chính sách được quy định: tên chính sách in trắng, mô tả một dòng, lệnh cài đặt + nút sao chép ở phía bên phải. Tiêu đề phần đọc `enable all N → projected · ` (điểm số bạn sẽ đạt được với mọi bản sửa được áp dụng), và nút `[install all]` của nó sao chép lệnh `failproofai policy add a b c …` kết hợp cho mọi chính sách được quy định. +5. **Quay lại tốt hơn** — hai thẻ bên cạnh nhau. Trái: đặt lời nhắc (`3d` / `7d` / `14d` / `30d` bộ chọn nhịp độ; tồn tại thông qua `/api/auth/reminder` sau khi xác thực). Phải: mở khóa các lợi ích failproof — `invite a friend` mở một modal có danh sách email bạn bè được phân tách bằng dấu phẩy/khoảng trắng/dòng mới (tối đa 10 mỗi lần gửi), POST chúng đến `/api/audit/invite`, được chuyển tiếp đến `POST /v0/invite` của api-server. Api-server gửi một email cho mỗi người nhận từ `invite@failproof.ai` với người gửi được Cc và `Reply-To` được đặt, vì vậy người nhận sẽ thấy ai đã mời họ và người gửi sẽ nhận được một bản sao trong hộp thư đến của họ. Người dùng ẩn danh được định tuyến qua `AuthDialog` trước tiên để địa chỉ email của người gửi được biết trước khi lời mời được gửi đi. Việc hoàn tất quyền lợi/lợi ích là theo dõi. -Được điều khiển bởi thời gian chạy `failproofai audit` — xem [Audit CLI](/vi/cli/audit) để biết công cụ quét cơ bản, các cờ được hỗ trợ và bất biến bộ nhớ cache trên mỗi bản ghi. Bảng điều khiển lưu kết quả mới nhất vào bộ nhớ cache tại `~/.failproofai/audit-dashboard.json` (chế độ `0600`, ô duy nhất, các lần chạy mới ghi đè) vì vậy các lần ghé thăm lại là tức thì; **cả bộ nhớ cache trên mỗi bản ghi và toàn bộ kết quả đều bị từ chối khi đọc sau khi chúng lớn hơn 7 ngày** vì vậy bảng điều khiển không bao giờ yên tĩnh phục vụ kết quả một tuần tuổi — vượt quá TTL `/audit` rơi vào trạng thái trống và nhắc chạy lại. Nhấp vào `[ re-audit now ]` gần cuối báo cáo POSTs `/api/audit/run` với `noCache: true` — kiểm toán lại bỏ qua bộ nhớ cache trên mỗi bản ghi và quét lại mọi bản ghi từ đầu chứ không yên tĩnh trả về kết quả được lưu trong bộ nhớ cache — và bảng điều khiển thăm dò `/api/audit/status` ở 1Hz cho đến khi lần chạy kết thúc; một dải tiến trình màu hồng dính chặt tại đầu viewport trong lần chạy với bộ đếm thời gian đã trôi qua, và kết quả mới được trao đổi tại chỗ khi thành công (không tải lại toàn trang; kiểm toán lại không thành công để lại báo cáo trước đó nguyên vẹn). Khi thất bại, dải chuyển thành màu đỏ với bản sao được khóa từ `RerunError.kind` (`timeout` / `network` / `post_failed`). Trạng thái trống (không có bộ nhớ cache hoặc đã hết hạn) và trạng thái không có phiên (bộ nhớ cache tồn tại nhưng quét không tìm thấy bất kỳ bản ghi nào) được hiển thị riêng. +Được điều khiển bởi thời gian chạy `failproofai audit` — xem [Audit CLI](/vi/cli/audit) để biết công cụ quét cơ bản, các cờ được hỗ trợ và các bất biến bộ nhớ cache cho mỗi bảng ghi âm. Bảng điều khiển lưu vào bộ nhớ cache kết quả mới nhất tại `~/.failproofai/audit-dashboard.json` (chế độ `0600`, một khe, các chạy mới ghi đè) để các lần truy cập lại diễn ra tức thì; **cả bộ nhớ cache cho mỗi bảng ghi âm và toàn bộ kết quả đều bị từ chối khi đọc sau khi chúng cũ hơn 7 ngày** vì vậy bảng điều khiển không bao giờ yên tĩnh phục vụ kết quả cũ một tuần — vượt quá TTL `/audit` rơi vào trạng thái trống của nó và nhắc bạn chạy lại. Nhấp vào `[ re-audit now ]` gần dưới cùng của báo cáo POST `/api/audit/run` với `noCache: true` — kiểm toán lại bỏ qua bộ nhớ cache cho mỗi bảng ghi âm và quét lại mọi bảng ghi âm từ đầu thay vì yên tĩnh trả về kết quả được lưu vào bộ nhớ cache — và bảng điều khiển thăm dò `/api/audit/status` ở 1Hz cho đến khi chạy kết thúc; một dải tiến trình hồng dính ghim đến đầu khung nhìn trong quá trình chạy với bộ định thời đã trôi qua, và kết quả tươi swapin vị trí khi thành công (không tải lại toàn bộ trang; kiểm toán lại không thành công sẽ để báo cáo trước đó không thay đổi). Khi thất bại, dải chuyển sang màu đỏ với sao chép được khóa tắt bởi `RerunError.kind` (`timeout` / `network` / `post_failed`). Trạng thái trống (không có bộ nhớ cache hoặc hết hạn) và trạng thái không có phiên (bộ nhớ cache tồn tại nhưng quét không tìm thấy bảng ghi âm) được bề mặt riêng biệt. ### Chính sách @@ -75,16 +77,16 @@ Một trang hai tab để quản lý chính sách và xem lại hoạt động. - - Chọn nhiều lựa chọn CLI agent nào mà failproofai bảo vệ từ một bảng duy nhất — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi và Hermes đều có một hàng với trạng thái cài đặt (`Active` / `Detected` / `Inactive`), đường dẫn cài đặt phạm vi người dùng và một accent có thương hiệu. Chọn hoặc bỏ chọn các CLI bạn muốn và nhấp vào `Apply changes` để cài đặt/gỡ cài đặt sự khác biệt trong một bước. Các CLI có tệp nhị phân được phát hiện trên PATH được chọn trước. - - Bật hoặc tắt các chính sách cá nhân bằng một lần nhấp (ghi vào `~/.failproofai/policies-config.json` — được chia sẻ trên mọi CLI được cài đặt) - - Mở rộng một chính sách để định cấu hình các tham số của nó (đối với các chính sách hỗ trợ `policyParams`) + - Lựa chọn đa lựa chọn CLI agent nào failproofai bảo vệ từ một bảng duy nhất — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi và Hermes đều có một hàng với trạng thái cài đặt (`Active` / `Detected` / `Inactive`), đường dẫn cài đặt phạm vi người dùng và nhấn mạnh có thương hiệu. Chọn hoặc bỏ chọn các CLI bạn muốn và nhấp vào `Apply changes` để cài đặt/gỡ cài đặt chênh lệch trong một bước. Các CLI có nhị phân được phát hiện trên PATH được kiểm tra trước. + - Bật hoặc tắt các chính sách riêng lẻ bằng một cú nhấp chuột duy nhất (ghi vào `~/.failproofai/policies-config.json` — được chia sẻ trên mọi CLI được cài đặt) + - Mở rộng một chính sách để cấu hình các tham số của nó (đối với các chính sách hỗ trợ `policyParams`) - Đặt đường dẫn tệp chính sách tùy chỉnh - - Lịch sử đầy đủ được phân trang của mọi sự kiện hook đã kích hoạt trên tất cả các phiên + - Lịch sử được phân trang đầy đủ của mọi sự kiện hook đã kích hoạt trên tất cả các phiên - Lọc theo quyết định, loại sự kiện, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), tên chính sách hoặc ID phiên - - Mỗi hàng hiển thị: dấu thời gian, tên chính sách, quyết định, huy hiệu CLI (cam = Claude Code, tím = OpenAI Codex, xanh = GitHub Copilot, ngọc lục bảo = Cursor Agent, hổ phách = OpenCode, hồng = Pi, chàm = Hermes, lục lam = OpenClaw, hoa hồng = Factory Droid, tím = Devin, lục bình = Antigravity, vôi = Goose), tên công cụ, ID phiên và lý do cho các quyết định deny/instruct - - Nhấp vào một ID phiên để mở bản ghi của nó — trình xem tự động phát hiện CLI nào đã kích hoạt hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) và hiển thị huy hiệu CLI phù hợp trong tiêu đề + - Mỗi hàng hiển thị: dấu thời gian, tên chính sách, quyết định, huy hiệu CLI (cam = Claude Code, tím = OpenAI Codex, xanh lam = GitHub Copilot, xanh lục = Cursor Agent, hổphách = OpenCode, hồng = Pi, chàm = Hermes, xanh mòng két = OpenClaw, hồng = Factory Droid, tím = Devin, lục = Antigravity, vôi = Goose), tên công cụ, ID phiên và lý do cho các quyết định deny/instruct + - Nhấp vào ID phiên để mở bảng ghi âm của nó — trình xem tự động phát hiện CLI nào đã kích hoạt hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents//sessions/*.jsonl`, Factory Droid `~/.factory/sessions//.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) và hiển thị huy hiệu CLI phù hợp trong tiêu đề @@ -92,7 +94,7 @@ Một trang hai tab để quản lý chính sách và xem lại hoạt động. ## Làm mới tự động -Bảng điều khiển có một công tắc làm mới tự động trong điều hướng trên cùng. Khi được bật, trang hiện tại sẽ làm mới định kỳ để hiển thị các phiên mới và hoạt động chính sách khi chúng xuất hiện. Thiết yếu cho việc giám sát các phiên agent tự trị chạy dài. +Bảng điều khiển có công tắc làm mới tự động trong thanh điều hướng trên cùng. Khi được bật, trang hiện tại sẽ làm mới định kỳ để hiển thị các phiên và hoạt động chính sách mới khi chúng xuất hiện. Cần thiết để giám sát các phiên agent tự chủ chạy lâu dài. --- @@ -104,13 +106,13 @@ Nếu bạn chỉ cần một số phần của bảng điều khiển, hãy đ FAILPROOFAI_DISABLE_PAGES=policies failproofai ``` -Giá trị hợp lệ: `policies`, `projects`, `audit`. +Các giá trị hợp lệ: `policies`, `projects`, `audit`. --- ## Cấu hình đường dẫn dự án -Theo mặc định, bảng điều khiển đọc từ thư mục dự án Claude Code tiêu chuẩn. Ghi đè nó cho thiết lập tùy chỉnh: +Theo mặc định, bảng điều khiển đọc từ thư mục dự án Claude Code tiêu chuẩn. Ghi đè nó cho các thiết lập tùy chỉnh: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,13 +122,13 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## Truy cập từ máy chủ không phải localhost -Khi chạy bảng điều khiển ở **chế độ phát triển** (`npm run dev`) và truy cập nó từ tên máy chủ khác với `localhost` - ví dụ, một tên miền tùy chỉnh, một IP từ xa hoặc một URL được đường hầm — bạn có thể thấy một cảnh báo như: +Khi chạy bảng điều khiển ở **chế độ dev** (`npm run dev`) và truy cập nó từ tên máy chủ khác với `localhost` - ví dụ, một tên miền tùy chỉnh, một IP từ xa hoặc một URL được đào hạo — bạn có thể thấy cảnh báo như: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Đây là Next.js chặn quyền truy cập đa nguồn gốc vào websocket HMR (hot module reload) của nó, đây là tính năng chỉ dành cho phát triển. Để cho phép máy chủ của bạn, sử dụng cờ `--allowed-origins`: +Đây là Next.js chặn truy cập cross-origin vào websocket HMR (tải lại mô-đun nóng) của nó, đây là tính năng chỉ phát triển. Để cho phép máy chủ của bạn, hãy sử dụng cờ `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -138,12 +140,12 @@ npm run dev -- --allowed-origins dashboard.example.com npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -Bạn cũng có thể đặt biến môi trường `FAILPROOFAI_ALLOWED_DEV_ORIGINS`: +Bạn cũng có thể đặt biến môi trường `FAILPROOFAI_ALLOWED_DEV_ORIGINS` thay thế: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Điều này chỉ áp dụng cho chế độ phát triển. Khi chạy `failproofai` (chế độ sản xuất), không có websocket HMR và không có vấn đề tài nguyên phát triển đa nguồn gốc. +Điều này chỉ áp dụng cho chế độ dev. Khi chạy `failproofai` (chế độ production), không có websocket HMR và không có sự cố tài nguyên dev cross-origin. \ No newline at end of file diff --git a/docs/zh/configuration.mdx b/docs/zh/configuration.mdx index 0202acdc..a145dfcd 100644 --- a/docs/zh/configuration.mdx +++ b/docs/zh/configuration.mdx @@ -1,28 +1,28 @@ --- title: 配置 -description: "配置文件格式、三级作用域系统与合并规则" +description: "配置文件格式、三层作用域系统及合并规则" icon: gear --- -failproofai 使用 JSON 配置文件来控制哪些策略处于启用状态、策略的行为方式，以及自定义策略的加载路径。配置设计上便于团队共享——将其提交到仓库，每位开发者都能获得相同的 AI 代理安全防护。 +failproofai 使用 JSON 配置文件来控制哪些策略处于激活状态、它们的行为方式以及自定义策略的加载位置。配置设计为易于与团队共享——将其提交到代码仓库后，每位开发者都能获得相同的 Agent 安全保障。 --- ## 配置作用域 -共有三个配置作用域，按优先级顺序评估： +共有三个配置作用域，按优先级顺序进行评估： | 作用域 | 文件路径 | 用途 | |-------|-----------|---------| | **project** | `.failproofai/policies-config.json` | 每个仓库的配置，提交到版本控制 | | **local** | `.failproofai/policies-config.local.json` | 个人的仓库级覆盖配置，已加入 gitignore | -| **global** | `~/.failproofai/policies-config.json` | 适用于所有项目的用户级默认配置 | +| **global** | `~/.failproofai/policies-config.json` | 跨所有项目的用户级默认配置 | -当 failproofai 收到 hook 事件时，会加载并合并当前工作目录下所有已存在的三个文件。 +当 failproofai 接收到钩子事件时，它会加载并合并当前工作目录下存在的所有三个文件。 ### 合并规则 -**`enabledPolicies`** — 取三个作用域的并集。任意级别启用的策略都会生效。 +**`enabledPolicies`** — 三个作用域的并集。在任意层级启用的策略均处于激活状态。 ```text project: ["block-sudo"] @@ -32,7 +32,7 @@ global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← 去重后的并集 ``` -**`policyParams`** — 对某个策略最先定义其参数的作用域完全胜出，不会对策略参数内的值进行深度合并。 +**`policyParams`** — 最先定义某策略参数的作用域完全胜出。策略参数内部不进行深度合并。 ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -46,12 +46,14 @@ project: （无 block-sudo 条目） local: （无 block-sudo 条目） global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← 回退到 global +resolved: { allowPatterns: ["sudo systemctl status"] } ← 向下穿透到 global ``` -**`customPoliciesPath`** — 最先定义该字段的作用域胜出。 +**`customPoliciesPaths` / `customPoliciesPath`** — 最先定义任意一种形式的作用域胜出。 -**`llm`** — 最先定义该字段的作用域胜出。 +**`disabledCustomPolicies`** — 所有作用域的并集。当你在仪表板中关闭某个来自显式或约定策略文件的独立策略时，仪表板会在此写入带有来源限定符的 ID。未列出的策略默认保持启用状态；ID 包含来源文件，以便对多个文件中同名策略进行独立控制。 + +**`llm`** — 最先定义它的作用域胜出。 --- @@ -102,27 +104,27 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← 回退到 global 类型：`string[]` -需要启用的策略名称列表。名称必须与 `failproofai policies` 显示的策略标识符完全匹配。完整列表请参见[内置策略](/zh/built-in-policies)。 +要启用的策略名称列表。名称必须与 `failproofai policies` 显示的策略标识符完全匹配。完整列表请参阅[内置策略](/zh/built-in-policies)。 -不在 `enabledPolicies` 中的策略将处于非活跃状态，即便在 `policyParams` 中为其配置了条目也不例外。 +不在 `enabledPolicies` 中的策略均为非激活状态，即使它们在 `policyParams` 中有条目也不例外。 ### `policyParams` 类型：`Record>` -各策略的参数覆盖配置。外层键为策略名称，内层键为各策略专属的配置项。每个策略的可用参数请参见[内置策略](/zh/built-in-policies)。 +每个策略的参数覆盖配置。外层键为策略名称，内层键为策略专用参数。每个策略的可用参数详见[内置策略](/zh/built-in-policies)。 -如果策略有参数但未指定，则使用策略的内置默认值。未配置 `policyParams` 的用户其行为与之前版本完全一致。 +若策略有参数但你未指定，则使用该策略的内置默认值。未配置 `policyParams` 的用户与之前版本的行为完全相同。 -策略参数块中未知的键在 hook 触发时会被静默忽略，但在运行 `failproofai policies` 时会作为警告标记出来。 +策略参数块中未知的键在钩子触发时会被静默忽略，但在运行 `failproofai policies` 时会被标记为警告。 -#### `hint`（通用配置项） +#### `hint`（跨策略通用） 类型：`string`（可选） -当策略返回 `deny` 或 `instruct` 时，附加到原因后面的消息。可用于在不修改策略本身的情况下，向 Claude 提供可操作的指引。 +当策略返回 deny 或 instruct 时，附加到原因末尾的消息。使用它可以为 Claude 提供可操作的指导，而无需修改策略本身。 -适用于任何类型的策略——内置策略、自定义策略（`custom/`）、项目约定策略（`.failproofai-project/`）或用户约定策略（`.failproofai-user/`）。 +适用于所有策略类型——内置策略、自定义策略（`custom/`）、项目约定策略（`.failproofai-project/`）或用户约定策略（`.failproofai-user/`）。 ```json { @@ -141,7 +143,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← 回退到 global } ``` -当 block-force-push 拒绝操作时，Claude 会看到：*"Force-pushing is blocked. Try creating a fresh branch instead."* +当 `block-force-push` 拒绝时，Claude 看到的内容为：*"Force-pushing is blocked. Try creating a fresh branch instead."* 非字符串值和空字符串会被静默忽略。若未设置 `hint`，行为保持不变（向后兼容）。 @@ -149,32 +151,32 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← 回退到 global 类型：`string`（绝对路径） -包含自定义 hook 策略的 JavaScript 文件路径。该值由 `failproofai policies --install --custom ` 自动设置（路径在存储前会被解析为绝对路径）。 +包含自定义钩子策略的 JavaScript 文件路径。此值由 `failproofai policies --install --custom ` 自动设置（路径在存储前会被解析为绝对路径）。 -每次 hook 事件触发时都会重新加载该文件，不进行缓存。有关编写自定义策略的详情，请参见[自定义策略](/zh/custom-policies)。 +该文件在每次钩子事件时都会重新加载，不进行缓存。编写详情请参阅[自定义策略](/zh/custom-policies)。 ### 基于约定的策略 -除了显式的 `customPoliciesPath` 外，failproofai 还会自动发现并加载 `.failproofai/policies/` 目录中的策略文件： +除了显式的 `customPoliciesPath` 之外，failproofai 还会自动从 `.failproofai/policies/` 目录中发现并加载策略文件： -| 级别 | 目录 | 作用域 | +| 层级 | 目录 | 作用域 | |-------|-----------|-------| | 项目级 | `.failproofai/policies/` | 通过版本控制与团队共享 | | 用户级 | `~/.failproofai/policies/` | 个人使用，适用于所有项目 | -**文件匹配：** 仅加载匹配 `*policies.{js,mjs,ts}` 的文件（例如 `security-policies.mjs`、`workflow-policies.js`），目录中的其他文件会被忽略。 +**文件匹配规则：** 仅加载匹配 `*policies.{js,mjs,ts}` 的文件（例如 `security-policies.mjs`、`workflow-policies.js`）。目录中的其他文件会被忽略。 -**无需配置：** 约定策略无需在 `policies-config.json` 中添加任何条目，只需将文件放入对应目录，下次 hook 事件触发时即可自动生效。 +**无需配置：** 约定策略不需要在 `policies-config.json` 中添加任何条目。只需将文件放入目录，下次钩子事件触发时即可自动加载。 -**联合加载：** 项目和用户约定目录都会被扫描，两个级别中所有匹配的文件都会被加载（与 `customPoliciesPath` 采用首个作用域胜出的方式不同）。 +**联合加载：** 项目级和用户级约定目录都会被扫描。两个层级的所有匹配文件均会被加载（不同于 `customPoliciesPath` 的首个作用域胜出规则）。 -更多详情和示例请参见[自定义策略](/zh/custom-policies)。 +更多详情和示例请参阅[自定义策略](/zh/custom-policies)。 ### `llm` 类型：`object`（可选） -供策略进行 AI 调用的 LLM 客户端配置，大多数场景下无需配置。 +用于执行 AI 调用的策略的 LLM 客户端配置。大多数场景下不需要此配置。 ```json { @@ -189,19 +191,24 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← 回退到 global ## 通过 CLI 管理配置 -`policies --install` 和 `policies --uninstall` 命令会写入代理 CLI 的 hook 设置文件（hook 入口点），而 `policies-config.json` 是由你直接管理的文件，两者相互独立： +`policies --install` 和 `policies --uninstall` 命令会写入 Agent CLI 的钩子设置文件（钩子入口点），而 `policies-config.json` 是你直接管理的文件。两者是相互独立的： -- **代理 CLI 设置** — 告知代理在每次工具调用时执行 `failproofai --hook `： +- **Agent CLI 设置** — 告知 Agent 在每次工具调用时执行 `failproofai --hook `： - **Claude Code**：`~/.claude/settings.json`（用户级）、`/.claude/settings.json`（项目级）、`/.claude/settings.local.json`（本地级） - **OpenAI Codex**：`~/.codex/hooks.json`（用户级）、`/.codex/hooks.json`（项目级）——Codex 没有 `local` 作用域 - - **GitHub Copilot CLI _(beta)_**：`~/.copilot/hooks/failproofai.json`（用户级）、`/.github/hooks/failproofai.json`（项目级）——Copilot 没有 `local` 作用域。Hook 条目使用 Copilot 基于操作系统的 `bash`/`powershell` 命令字段，并带有 `timeoutSec`；文件顶层包含 `version: 1` 标记。Copilot CLI 支持目前为 **beta** 版本，我们正在针对更多实际会话验证 `events.jsonl` 记录模式（公开文档中未作说明）。 - - **Cursor Agent _(beta)_**：`~/.cursor/hooks.json`（用户级）、`/.cursor/hooks.json`（项目级）——Cursor 没有 `local` 作用域。Hook 条目使用 Claude 风格的 `{type, command, timeout}` 格式（无 `bash`/`powershell` 拆分），但按照 Cursor 的 [hooks schema](https://cursor.com/docs/hooks) 以驼峰式事件键（`preToolUse`、`beforeSubmitPrompt` 等）存储在扁平数组中；文件顶层包含 `version: 1` 标记。处理器通过 `CURSOR_EVENT_MAP` 将驼峰式键规范化为帕斯卡式，使现有内置策略能够正常触发。Cursor Agent 支持目前为 **beta** 版本，我们正在针对更多实际安装验证 Cursor 的磁盘上转录格式（公开文档未作说明）。 - - **OpenCode _(beta)_**：`~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs`（用户级）、`/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs`（项目级）——OpenCode 没有 `local` 作用域。与其他五种 CLI 不同，OpenCode **没有外部命令 hook 系统**：它通过 `opencode.json` 的 `plugin: []` 数组显式注册来加载进程内 JS/TS 插件（自动发现 `.opencode/plugins/` 目录**不是** opencode v1.14.33 插件的加载方式）。安装时会生成一个小型插件 shim，以子进程方式调用 failproofai 二进制文件，并将二进制文件的 Claude 风格 JSON 响应转换回插件语义：工具事件拒绝时 `throw new Error()`（取消工具调用）；instruct 以及 `Stop` / `SubagentStop` 拒绝时调用 `client.session.prompt(...)`（将拒绝原因作为下一条用户消息提交——这是唯一的强制重试通道，因为 `session.idle` 仅用于通知，从中抛出异常无效）；allow 时不执行任何操作。该 shim 在转发给二进制文件前会规范化工具名称（小写 → 帕斯卡式，通过 `OPENCODE_TOOL_MAP`）和工具输入参数键（驼峰式 → 下划线式，通过 `OPENCODE_TOOL_INPUT_MAP` 适用于 `Read` / `Write` / `Edit`，例如 `filePath` → `file_path`、`oldString` → `old_string`），从而使 `block-read-outside-cwd`、`block-env-files` 和 `block-secrets-write` 等路径检查内置策略在 OpenCode 工具调用中正常触发。会话存储在 `~/.local/share/opencode/opencode.db` 的 SQLite 数据库中；仪表盘的会话查看器通过 `opencode db --format json` 和 `opencode export ` 读取它们。OpenCode 支持目前为 **beta** 版本，我们正在跨版本和更多实际会话中验证其行为。详见 [OpenCode plugins 文档](https://opencode.ai/docs/plugins/)。 - - **Pi _(beta)_**：`~/.pi/agent/settings.json`（用户级）、`/.pi/settings.json`（项目级）——Pi 没有 `local` 作用域。Pi 在启动时加载 TypeScript 扩展包；设置文件是一个扁平字符串数组 `{"packages": ["./relative/path", …]}`。failproofai 在 packages 数组中写入一个指向其捆绑的 `pi-extension/` 目录的条目。该扩展内部订阅 Pi 的 `tool_call` / `user_bash` / `input` / `session_start` 事件，并调用 `failproofai --hook --cli pi`；处理器通过 `PI_EVENT_MAP` 将下划线小写蛇形命名规范化为帕斯卡式，使现有内置策略正常触发。工具输入参数也通过 `PI_TOOL_INPUT_MAP` 规范化（Pi 的 Read / Write / Edit 使用 `path` 而非 `file_path`；映射顶层键后 `block-env-files` 和 `block-secrets-write` 可正常触发——`block-read-outside-cwd` 本身已有 `path` 的回退逻辑）。Pi 支持目前为 **beta** 版本，有待 Pi 的扩展 API 和会话日志格式稳定。 - - **Hermes (hermes-agent)**：`~/.hermes/config.yaml`（**仅用户作用域**——Hermes 没有项目/本地配置）。Hermes 是一个 Slack/Telegram **网关**，因此一次安装即可拦截来自所有平台（Slack/Telegram/cli/cron）**以及**内部子代理的工具调用。Hook 条目是 `hooks:` 映射下的 `{command, timeout}` 对（timeout 单位为**秒**），以 Hermes 的蛇形命名事件为键（`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`）；处理器通过 `HERMES_EVENT_MAP` 规范化事件，通过 `HERMES_TOOL_MAP` 规范化工具名称，使内置策略正常触发。配置通过保留注释的 YAML `Document` 往返编辑，以确保操作者的其他设置不受影响；安装时将 `hooks_auto_accept: true` 设置为 true，以便无头网关（无 TTY）在无需确认提示的情况下运行 hook。评估器输出 Hermes 的 `{"decision":"block","reason"}` stdout 约定（Hermes 忽略退出码）。**限制：** Hermes 没有会话结束 `Stop` 事件，因此 `require-*-before-stop` 内置策略永远不会为其触发（不适用，并非故障）；`instruct` 降级为允许并记录日志（无额外上下文通道）；输出密钥清理（`sanitize-*`）无法通过 shell hook 约定重写工具输出。Hermes **同时**也是一个离线**审计**数据源——仪表盘直接从 `~/.hermes/state.db` 读取其网关会话。 -- **`policies-config.json`** — 告知 failproofai 评估哪些策略及其参数（在所有代理 CLI 之间共享） - -通过 `--cli claude|codex|copilot|cursor|opencode|pi|hermes` 指定目标代理（可用空格分隔或重复指定多个）： + - **GitHub Copilot CLI _(beta)_**：`~/.copilot/hooks/failproofai.json`（用户级）、`/.github/hooks/failproofai.json`（项目级）——Copilot 没有 `local` 作用域。钩子条目使用 Copilot 的操作系统键控 `bash`/`powershell` 命令字段（含 `timeoutSec`）；文件顶层携带 `version: 1` 标记。Copilot CLI 支持目前处于 **beta** 阶段，我们正在对照更多真实会话验证 `events.jsonl` 记录模式（公开文档中未指定）。**VS Code Copilot Chat Agent 模式（Preview）** 从 `.github/hooks/*.json`、`~/.copilot/hooks/*.json` 和 `~/.claude/settings.json`（由 `chat.hookFilesLocations` 设置管理）读取钩子配置，使用与 Claude 相同的 `{hookSpecificOutput:{permissionDecision:"deny",…}}` 协议——这正是 `copilot` 集成和 `claude` 集成（`~/.claude/settings.json`）已经写入的确切路径，因此 `failproofai policies --install --cli copilot`（或 `--cli claude`）**已经在 VS Code Agent 模式中生效**，无需单独的 `vscode` 集成（已通过 VS Code 发现日志实时确认）。 + - **Cursor Agent _(beta)_**：`~/.cursor/hooks.json`（用户级）、`/.cursor/hooks.json`（项目级）——Cursor 没有 `local` 作用域。钩子条目使用 Claude 风格的 `{type, command, timeout}` 形式（无 `bash`/`powershell` 分割），但按照 Cursor 的[钩子模式](https://cursor.com/docs/hooks)存储在驼峰命名事件键（`preToolUse`、`beforeSubmitPrompt` 等）下的扁平数组中；文件顶层携带 `version: 1` 标记。处理程序通过 `CURSOR_EVENT_MAP` 将驼峰命名规范化为帕斯卡命名，使现有内置策略无需修改即可正常触发。Cursor Agent 支持目前处于 **beta** 阶段，我们正在对照更多真实安装验证 Cursor 的会话磁盘格式（公开文档中未指定）。 + - **OpenCode _(beta)_**：`~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs`（用户级），`/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs`（项目级）——OpenCode 没有 `local` 作用域。与其他五个 CLI 不同，OpenCode **没有外部命令钩子系统**：它通过 `opencode.json` 的 `plugin: []` 数组显式注册来加载进程内 JS/TS 插件（从 `.opencode/plugins/` 自动发现**不是** opencode v1.14.33 的插件加载方式）。安装时会生成一个小型插件 shim，通过子进程调用 failproofai 二进制文件，并将二进制文件的 Claude 风格 JSON 响应转换为插件语义：工具事件拒绝时 `throw new Error()`（取消工具调用），instruct 和 `Stop` / `SubagentStop` 拒绝时使用 `client.session.prompt(...)`（将拒绝原因作为下一条用户消息提交——这是唯一的强制重试通道，因为 `session.idle` 仅用于通知且从中抛出异常无效），allow 时不做任何操作。shim 在转发给二进制文件之前会规范化工具名称（小写转帕斯卡命名，通过 `OPENCODE_TOOL_MAP`）和工具输入参数键（驼峰转下划线，通过 `OPENCODE_TOOL_INPUT_MAP`，适用于 `Read` / `Write` / `Edit`，例如 `filePath` → `file_path`、`oldString` → `old_string`），因此 `block-read-outside-cwd`、`block-env-files` 和 `block-secrets-write` 等路径检查内置策略在 OpenCode 工具调用中可无需修改地正常触发。会话存储在 OpenCode 的 SQLite 数据库 `~/.local/share/opencode/opencode.db` 中；仪表板的会话查看器通过 `opencode db --format json` 和 `opencode export ` 读取这些会话。OpenCode 支持目前处于 **beta** 阶段，我们正在跨版本和更多真实会话验证其行为。请参阅 [OpenCode 插件文档](https://opencode.ai/docs/plugins/)。 + - **Pi _(beta)_**：`~/.pi/agent/settings.json`（用户级）、`/.pi/settings.json`（项目级）——Pi 没有 `local` 作用域。Pi 在启动时加载 TypeScript 扩展包；设置文件是一个扁平字符串数组 `{"packages": ["./relative/path", …]}`。failproofai 写入一个指向其捆绑的 `pi-extension/` 目录的 packages 数组条目。该扩展内部订阅 Pi 的 `tool_call` / `user_bash` / `input` / `session_start` 事件，并调用 `failproofai --hook --cli pi`；处理程序通过 `PI_EVENT_MAP` 将下划线小写蛇形命名规范化为帕斯卡命名，使现有内置策略无需修改即可正常触发。工具输入参数也通过 `PI_TOOL_INPUT_MAP` 进行规范化（Pi 的 Read / Write / Edit 使用 `path` 而非 `file_path`；映射顶层键后 `block-env-files` 和 `block-secrets-write` 可正常触发——`block-read-outside-cwd` 已有 `path` 回退逻辑）。Pi 支持目前处于 **beta** 阶段，待 Pi 的扩展 API 和会话日志格式稳定后将正式发布。 + - **Hermes (hermes-agent)**：`~/.hermes/config.yaml`（**仅用户作用域**——Hermes 没有项目/本地配置）。Hermes 是一个 Slack/Telegram **网关**，因此一次安装即可拦截来自每个平台（Slack/Telegram/cli/cron）**以及**内部子 Agent 的工具调用。钩子条目是 `{command, timeout}` 对（超时单位为**秒**），位于以 Hermes 蛇形命名事件（`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`）为键的 `hooks:` 映射下；处理程序通过 `HERMES_EVENT_MAP` 规范化事件，通过 `HERMES_TOOL_MAP` 规范化工具名称，使内置策略无需修改即可正常触发。配置通过保留注释的 YAML `Document` 往返方式进行编辑，以保留操作员的其他设置；安装时设置 `hooks_auto_accept: true`，使无头网关（无 TTY）无需同意提示即可运行钩子。评估器输出 Hermes 的 `{"decision":"block","reason"}` stdout 协议（Hermes 忽略退出码）。**限制：** Hermes 没有轮次结束的 `Stop` 事件，因此 `require-*-before-stop` 内置策略不会为其触发（不适用，而非故障）；`instruct` 降级为 allow 并记录日志（无附加上下文通道）；输出密钥脱敏（`sanitize-*`）无法通过 shell 钩子协议重写工具输出。Hermes **同时**也是一个离线**审计**来源——仪表板直接从 `~/.hermes/state.db` 读取其网关会话。 + - **OpenClaw (openclaw gateway)**：`~/.openclaw/openclaw.json`（**仅用户作用域**——OpenClaw 没有项目/本地配置）。与 Hermes 类似，OpenClaw 是一个自托管的多通道**网关**，因此一次安装即可拦截来自每个通道及其内部子 Agent 的工具调用。执行通过 OpenClaw 的**进程内插件钩子**运行（其基于文件的内部钩子仅用于观察，无法阻止），因此——与 OpenCode/Pi 类似——failproofai 提供了一个静态的 `openclaw-plugin/` 包，通过异步子进程调用 failproofai 二进制文件并转换判决结果。安装时在 `openclaw.json` 的 `plugins.load.paths[]` 中注册提供的插件目录，并在 `plugins.entries.failproofai` 下启用它（含 `hooks.allowConversationAccess: true`，原始对话钩子所必需）。评估器输出扁平的 `{permission, reason}` 判决，shim 将其映射到每个钩子的原生返回形式：`before_tool_call → {block:true, blockReason}`（**PreToolUse**）、`before_agent_run → {outcome:"block", reason}`（**UserPromptSubmit**）、`before_agent_finalize → {action:"revise", reason}`（**Stop**——一个真正的轮次结束门控，因此 `require-*-before-stop` 内置策略在 OpenClaw 上**强制执行**，与 Hermes 不同）。事件和工具名称通过 `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP`（`exec→Bash`、`read→Read` 等）在二进制端规范化，使内置策略无需修改即可正常触发；shim 在任何子进程/解析/超时错误时以开放方式失败。OpenClaw **同时**也是一个离线**审计**来源——仪表板读取 `~/.openclaw/agents//sessions/.jsonl` 中的 JSONL 会话。 + - **Factory Droid (`droid`)**：`~/.factory/hooks.json`（用户级）、`/.factory/hooks.json`（项目级）——Factory 没有 `local` 作用域。droid 提供 Claude 风格的外部命令钩子系统，但有两个经 droid v0.171.0 实时验证的特殊之处：(1) 事件名称位于 `hooks.json` 的**顶层**——**没有 `"hooks"` 包装器**（droid 会拒绝它）；工具事件（`PreToolUse`/`PostToolUse`）携带 `"matcher": "*"`，非工具事件则省略它。(2) 拒绝由钩子**退出码 2 + stderr** 驱动，而非 JSON 决策——评估器的 `factory` 分支对工具/提示事件返回退出码 2，仅在轮次结束 `Stop` 事件（droid 的唯一强制重试通道）时返回 `{decision:"block", reason}`。事件名称已为帕斯卡命名（无事件映射），负载为 Claude 蛇形命名格式；仅通过 `FACTORY_TOOL_MAP`（`Execute→Bash`、`Create→Write`、`FetchUrl→WebFetch` 等）规范化工具名称。Factory **同时**也是一个离线**审计**来源——仪表板读取 `~/.factory/sessions//.jsonl` 中的磁盘 JSONL 会话。 + - **Devin CLI (`devin`, Cognition)**：`~/.config/devin/config.json`（用户级）、`/.devin/config.json`（项目级）——Devin 没有 `local` 作用域。Devin 是经 devin v3000.1.27 实时验证的**纯 Claude 克隆**：它使用标准 Claude 的 `"hooks"` 包装器模式（写入操作保留合并，因此配置文件的其他键——`org_id`、`theme_mode` 等——得以保留），已为帕斯卡命名的事件名称（无事件映射，无处理程序分支），以及 Claude 蛇形命名的 stdin 负载（无需规范化）。评估器的 `devin` 分支在退出码 0 时对**每个**事件以 `{"decision":"block","reason"}` JSON 输出到 stdout（已验证——该 block 覆盖了 `--permission-mode dangerous`）；在轮次结束 `Stop` 事件中，reason 携带 MANDATORY-ACTION 强制重试措辞，使 `require-*-before-stop` 内置策略得以执行。仅通过 `DEVIN_TOOL_MAP`（`exec→Bash`；`tool_input.command` 已为规范格式）规范化工具名称。Devin **同时**也是一个离线**审计**来源——仪表板读取 `~/.local/share/devin/cli/sessions.db` 中的 SQLite 会话（每个 `sessions` 行携带真实的 `working_directory`，因此会话按项目 cwd 分组，与 Claude 类似）。 + - **Antigravity CLI (`agy`)**：`~/.gemini/config/hooks.json`（用户级）、`/.agents/hooks.json`（项目级）——Antigravity 没有 `local` 作用域。与 Factory/Devin 不同，Antigravity 有其**自己的**协议（非 Claude 克隆），经 agy v1.1.2 实时验证。`hooks.json` 使用**命名钩子**模式：顶层键是钩子*名称*（`"failproofai"`），其值是事件→处理程序映射——工具事件（`PreToolUse`/`PostToolUse`）将处理程序包装在 `{matcher:"*", hooks:[…]}` 中，而 `PreInvocation`/`Stop` 是**扁平**处理程序数组（其他命名钩子得以保留）。stdin 负载是**驼峰命名的 protojson**（`toolCall:{name,args}`、`conversationId`、`workspacePaths`、`transcriptPath`）——failproofai 在策略运行前将其规范化为蛇形命名，并通过 `ANTIGRAVITY_TOOL_INPUT_MAP` 映射 `run_command` 的帕斯卡命名参数（`CommandLine`/`Cwd`）。评估器的 `antigravity` 分支使用 Antigravity **自己的**响应形式：`{decision:"deny", reason}` 阻止工具/提示（退出码 0），轮次结束 `Stop` 时的 `{decision:"continue", reason}` 重新进入循环（使 `require-*-before-stop` 内置策略得以执行），`{injectSteps:[{ephemeralMessage}]}` 在 `PreInvocation`（→ `UserPromptSubmit`）时注入指令。工具名称通过 `ANTIGRAVITY_TOOL_MAP`（`run_command→Bash`、`view_file→Read` 等）规范化。Antigravity **同时**也是一个离线**审计**来源——仪表板读取 `~/.gemini/antigravity-cli/brain//.system_generated/logs/transcript_full.jsonl` 中的纯 JSONL 转录文件（对话索引位于 `conversation_summaries.db`）。 + - **Goose (codename goose, Block)**：`~/.agents/plugins/failproofai/hooks/hooks.json`（用户级）、`/.agents/plugins/failproofai/hooks/hooks.json`（项目级）——Goose 没有 `local` 作用域。执行使用 Goose 的**钩子**系统，即跨 Agent 的 **Open Plugins** 规范：安装程序只需放入 `failproofai` 插件目录，Goose 在启动时自动发现并将其自注册到 `~/.config/goose/config.yaml`。`hooks.json` 使用带有顶层 `"hooks"` 包装器的 Open Plugins 模式，且每个事件上**省略**匹配器——裸 `"*"` 是一个无效正则表达式，不匹配任何内容（经 goose v1.43.0 实时验证）。事件名称已为帕斯卡命名（无事件映射）；stdin 负载使用 `event`/`working_dir`，处理程序将其规范化为 `hook_event_name`/`cwd`。评估器的 `goose` 分支在退出码 0 时以 `{"decision":"block","reason"}` JSON 输出到 stdout，仅在 **`PreToolUse`** 事件上生效（goose ≥ v1.37.0 中提供）——该事件对 shell 工具触发，**也在委托的子 Agent 内部触发**，因此它是唯一足够的拒绝点；任何其他钩子错误以开放方式失败。Goose **没有 `Stop` 事件**，因此 `require-*-before-stop` 内置策略不适用（与 Hermes 类似）。工具名称通过 `GOOSE_TOOL_MAP`（`shell→Bash`、`write→Write`、`todo__todo_write→TodoWrite` 等）规范化，路径键通过 `GOOSE_TOOL_INPUT_MAP`（`path`/`source` → `file_path`）规范化。Goose **同时**也是一个离线**审计**来源——仪表板读取 `~/.local/share/goose/sessions/sessions.db` 中的 SQLite 会话（每个 `sessions` 行携带真实的 `working_dir`，因此会话按项目 cwd 分组，与 Devin 类似；`--no-session` 的临时运行会被过滤）。 +- **`policies-config.json`** — 告知 failproofai 要评估哪些策略及其参数（在所有 Agent CLI 间共享） + +传入 `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` 以针对特定 Agent（空格分隔或重复使用以选择任意子集）： ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +217,28 @@ failproofai policies --install --cli cursor --scope project failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli hermes --scope user -failproofai policies --install --cli claude codex copilot cursor opencode pi +failproofai policies --install --cli openclaw --scope user +failproofai policies --install --cli factory --scope project +failproofai policies --install --cli devin --scope project +failproofai policies --install --cli antigravity --scope project +failproofai policies --install --cli goose --scope project +failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose ``` -省略 `--cli` 时，`failproofai` 会自动检测已安装的代理 CLI（`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes`）： +省略 `--cli` 时，`failproofai` 会自动检测已安装的 Agent CLI（`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`）： - **检测到一个 CLI** — 自动选择该 CLI，无需提示。 -- **在交互式终端中检测到多个 CLI** — 显示方向键单选菜单，分为 `Detected (N)` 区域（包含一个"为所有 N 个已检测到的 CLI 安装"的聚合行及各个已检测 CLI）和 `Not installed (M) · install hooks ahead of time` 区域（列出所有未检测到的受支持 CLI 作为提前安装选项）（↑↓ 移动，回车选择，^C 退出）。卸载流程仅显示 Detected 区域。 -- **在非交互式运行中检测到多个 CLI**（CI、无 TTY）— 无需提示，为所有检测到的 CLI 安装。 -- **未检测到任何 CLI** — 回退到 `claude`，并显示在 PATH 中未找到代理二进制文件的警告；hook 命令仍会被写入，一旦安装代理即可生效。 +- **在交互式终端中检测到多个 CLI** — 显示方向键单选提示，分为 `Detected (N)` 分组（含 `Install for all N detected` 汇总行及每个已检测到的 CLI）和 `Not installed (M) · install hooks ahead of time` 分组（列出所有未检测到的支持 CLI，作为预安装选项；↑↓ 移动，Enter 选择，^C 退出）。卸载流程仅显示 Detected 分组。 +- **在非交互式运行（CI、无 TTY）中检测到多个 CLI** — 为所有已检测到的 CLI 安装，无需提示。 +- **未检测到任何 CLI** — 回退到 `claude`，并发出未在 PATH 中找到 Agent 二进制文件的警告；钩子命令仍会写入，一旦安装 Agent 即可激活。 -你可以随时直接编辑 `policies-config.json`，修改将在下一次 hook 事件触发时立即生效，无需重启。 +你可以随时直接编辑 `policies-config.json`；更改在下次钩子事件时立即生效，无需重启。 --- ## 示例：带团队默认配置的项目级配置 -将 `.failproofai/policies-config.json` 提交到你的仓库： +将 `.failproofai/policies-config.json` 提交到你的代码仓库： ```json { @@ -245,4 +257,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi } ``` -每位开发者可以创建 `.failproofai/policies-config.local.json`（已加入 gitignore）进行个人覆盖配置，而不影响其他团队成员。 \ No newline at end of file +每位开发者可以创建 `.failproofai/policies-config.local.json`（已加入 gitignore）进行个人覆盖，而不会影响团队成员。 \ No newline at end of file diff --git a/docs/zh/custom-policies.mdx b/docs/zh/custom-policies.mdx index cb4dd136..68e10202 100644 --- a/docs/zh/custom-policies.mdx +++ b/docs/zh/custom-policies.mdx @@ -1,10 +1,10 @@ --- title: 自定义策略 -description: "用 JavaScript 编写自己的策略——强制执行项目规范、防止配置漂移、检测故障、与外部系统集成" +description: "用 JavaScript 编写自己的策略——强制执行规范、防止配置漂移、检测故障、与外部系统集成" icon: code --- -自定义策略让你可以为任何 Agent 行为编写规则：强制执行项目规范、防止配置漂移、拦截破坏性操作、检测卡死的 Agent，或与 Slack、审批工作流等外部系统集成。它们使用与内置策略相同的 Hook 事件系统以及 `allow`、`deny`、`instruct` 决策。 +自定义策略允许你为任何 Agent 行为编写规则：强制执行项目规范、防止配置漂移、拦截危险操作、检测卡住的 Agent，或与 Slack、审批工作流等系统集成。它们使用与内置策略相同的 Hook 事件系统以及 `allow`、`deny`、`instruct` 决策机制。 --- @@ -41,7 +41,7 @@ failproofai policies --install --custom ./my-policies.js ### 方式一：基于约定（推荐） -将 `*policies.{js,mjs,ts}` 文件放入 `.failproofai/policies/` 目录，它们会被自动加载——无需任何命令行参数或配置变更。这和 git hooks 的用法一样：放入文件即生效。 +将 `*policies.{js,mjs,ts}` 文件放入 `.failproofai/policies/` 目录，它们会被自动加载——无需任何标志或配置更改。这与 Git Hooks 的工作方式类似：放入文件，即刻生效。 ``` # 项目级别——提交到 git，与团队共享 @@ -53,36 +53,41 @@ failproofai policies --install --custom ./my-policies.js ``` **工作原理：** -- 项目目录和用户目录均会被扫描（取并集，而非"第一个作用域优先"） -- 文件在各自目录内按字母顺序加载；可使用 `01-`、`02-` 前缀控制顺序 -- 仅加载匹配 `*policies.{js,mjs,ts}` 的文件，其他文件会被忽略 -- 每个文件独立加载（单文件失败不影响其他文件） +- 项目目录和用户目录均会被扫描（取并集，而非先匹配优先） +- 每个目录内按字母顺序加载文件，可用 `01-`、`02-` 前缀控制顺序 +- 只加载匹配 `*policies.{js,mjs,ts}` 的文件，其他文件会被忽略 +- 每个文件独立加载（单文件出错不影响其他文件） - 可与显式 `--custom` 及内置策略共存 -基于约定的策略是为团队建立质量标准的最简便方式。将 `.failproofai/policies/` 提交到 git，每位团队成员都会自动获得相同的规则，无需任何个人配置。随着团队不断发现新的故障模式，添加策略并推送即可。久而久之，这些策略将成为随着每次贡献持续完善的质量标准。 +基于约定的策略是为组织建立质量标准的最简单方式。将 `.failproofai/policies/` 提交到 git，每位团队成员即可自动获得相同的规则——无需逐个开发者配置。每当团队发现新的故障模式时，添加一条策略并推送即可。随着时间推移，这些策略将成为一套随每次贡献持续完善的质量标准。 ### 方式二：显式指定文件路径 ```bash -# 安装时指定自定义策略文件 +# 使用自定义策略文件进行安装 failproofai policies --install --custom ./my-policies.js -# 替换策略文件路径 +# 替换自定义策略路径 failproofai policies --install --custom ./new-policies.js -# 从配置中移除自定义策略路径 +# 配置多个显式文件（按标志顺序加载） +failproofai policies --install --custom ./security.js --custom ./workflow.js + +# 从配置中移除所有显式自定义策略路径 failproofai policies --uninstall --custom ``` -解析后的绝对路径会作为 `customPoliciesPath` 存储在 `policies-config.json` 中。每次 Hook 事件触发时都会重新加载该文件，事件之间不存在缓存。 +解析后的绝对路径会以 `customPoliciesPaths` 字段存储在 `policies-config.json` 中。重复使用 `--custom` 可配置多个文件。使用旧版 `customPoliciesPath` 字段的现有配置仍可正常工作。文件在每次 Hook 事件时都会重新加载——事件之间不存在缓存。 + +每条已注册的策略都会在仪表板中显示独立的开关。关闭某条策略会将其带源前缀的 ID 记录到 `disabledCustomPolicies` 中；该文件及其他策略继续加载，而被禁用的策略会在事件匹配前被排除。不同文件中重名的策略拥有各自独立的开关。 ### 两种方式同时使用 基于约定的策略与显式 `--custom` 文件可以共存。加载顺序如下： -1. 显式 `customPoliciesPath` 文件（如已配置） +1. 显式 `customPoliciesPaths` 文件（按配置顺序） 2. 项目约定文件（`{cwd}/.failproofai/policies/`，按字母顺序） 3. 用户约定文件（`~/.failproofai/policies/`，按字母顺序） @@ -112,31 +117,31 @@ customPolicies.add({ ### 决策辅助函数 | 函数 | 效果 | 使用场景 | -|------|------|----------| -| `allow()` | 静默允许操作 | 操作安全，无需任何提示 | +|----------|--------|----------| +| `allow()` | 静默允许操作 | 操作安全，无需提示 | | `deny(message)` | 阻止操作 | Agent 不应执行此操作 | -| `instruct(message)` | 添加上下文而不阻止操作 | 为 Agent 提供额外上下文以保持正轨 | +| `instruct(message)` | 添加上下文而不阻止 | 为 Agent 提供额外上下文以保持正轨 | -`deny(message)` —— 消息会以 `"Blocked by failproofai:"` 为前缀显示给 Claude。单条 `deny` 会短路所有后续评估。 +`deny(message)` — 消息将以 `"Blocked by failproofai:"` 为前缀显示给 Claude。单个 `deny` 会短路所有后续评估。 -`instruct(message)` —— 消息会附加到 Claude 当前工具调用的上下文中。所有 `instruct` 消息会被累积并一并发送。 +`instruct(message)` — 消息会追加到 Claude 当前工具调用的上下文中。所有 `instruct` 消息会被汇总后一并发送。 -你可以通过在 `policyParams` 中添加 `hint` 字段，为任意 `deny` 或 `instruct` 消息追加额外说明——无需修改代码。这对自定义策略（`custom/`）、项目约定策略（`.failproofai-project/`）和用户约定策略（`.failproofai-user/`）同样适用。详见 [配置 → hint](/zh/configuration#hint-cross-cutting)。 +你可以通过在 `policyParams` 中添加 `hint` 字段，为任何 `deny` 或 `instruct` 消息附加额外指导——无需修改代码。这同样适用于自定义策略（`custom/`）、项目约定策略（`.failproofai-project/`）和用户约定策略（`.failproofai-user/`）。详见 [配置 → hint](/zh/configuration#hint-cross-cutting)。 -### 信息性 allow 消息 +### 带信息的 allow 消息 -`allow(message)` 允许操作**并**向 Claude 发送一条信息性消息。该消息通过 Hook 处理器 stdout 响应中的 `additionalContext` 传递——与 `instruct` 使用相同的机制，但语义不同：它是状态更新，而非警告。 +`allow(message)` 允许操作**并**向 Claude 发送一条信息性消息。该消息通过 Hook 处理程序 stdout 响应中的 `additionalContext` 字段传递——与 `instruct` 使用相同的机制，但语义不同：它是状态更新，而非警告。 | 函数 | 效果 | 使用场景 | -|------|------|----------| -| `allow(message)` | 允许操作并向 Claude 发送上下文 | 确认某项检查通过，或说明某项检查被跳过的原因 | +|----------|--------|----------| +| `allow(message)` | 允许操作并向 Claude 发送上下文 | 确认检查已通过，或说明为何跳过某项检查 | 使用场景： -- **状态确认：** `allow("All CI checks passed.")` —— 告知 Claude 一切正常 -- **失败开放说明：** `allow("GitHub CLI not installed, skipping CI check.")` —— 告知 Claude 检查被跳过的原因，使其获得完整上下文 -- **多条消息累积：** 若多个策略各自返回 `allow(message)`，所有消息会以换行符连接后一并发送 +- **状态确认：** `allow("All CI checks passed.")` — 告知 Claude 一切正常 +- **故障开放说明：** `allow("GitHub CLI not installed, skipping CI check.")` — 告知 Claude 跳过检查的原因，使其掌握完整上下文 +- **多条消息累积：** 若多条策略各自返回 `allow(message)`，所有消息将以换行符拼接后一并发送 ```js customPolicies.add({ @@ -158,9 +163,9 @@ customPolicies.add({ ### `PolicyContext` 字段 | 字段 | 类型 | 描述 | -|------|------|------| +|-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`、`"PostToolUse"`、`"Notification"`、`"Stop"` | -| `toolName` | `string \| undefined` | 被调用的工具（例如 `"Bash"`、`"Write"`、`"Read"`） | +| `toolName` | `string \| undefined` | 被调用的工具（如 `"Bash"`、`"Write"`、`"Read"`） | | `toolInput` | `Record \| undefined` | 工具的输入参数 | | `payload` | `Record` | 来自 Claude Code 的完整原始事件载荷 | | `session` | `SessionMetadata \| undefined` | 会话上下文（见下文） | @@ -168,18 +173,18 @@ customPolicies.add({ ### `SessionMetadata` 字段 | 字段 | 类型 | 描述 | -|------|------|------| +|-------|------|-------------| | `sessionId` | `string` | Claude Code 会话标识符 | | `cwd` | `string` | Claude Code 会话的工作目录 | -| `transcriptPath` | `string` | 会话 JSONL 对话记录文件的路径 | +| `transcriptPath` | `string` | 会话 JSONL 转录文件的路径 | ### 事件类型 | 事件 | 触发时机 | `toolInput` 内容 | -|------|----------|-----------------| -| `PreToolUse` | Claude 运行工具之前 | 工具的输入（例如 Bash 对应 `{ command: "..." }`） | -| `PostToolUse` | 工具执行完成之后 | 工具的输入 + `tool_result`（输出内容） | -| `Notification` | Claude 发送通知时 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` —— Hook 必须始终返回 `allow()`，不能阻止通知 | +|-------|--------------|----------------------| +| `PreToolUse` | Claude 执行工具之前 | 工具的输入（如 Bash 对应 `{ command: "..." }`） | +| `PostToolUse` | 工具执行完成之后 | 工具的输入 + `tool_result`（输出结果） | +| `Notification` | Claude 发送通知时 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — Hook 必须始终返回 `allow()`，无法阻止通知 | | `Stop` | Claude 会话结束时 | 空 | --- @@ -189,12 +194,12 @@ customPolicies.add({ 策略按以下顺序评估： 1. 内置策略（按定义顺序） -2. 来自 `customPoliciesPath` 的显式自定义策略（按 `.add()` 调用顺序） -3. 项目 `.failproofai/policies/` 中的约定策略（文件按字母顺序，文件内按 `.add()` 顺序） -4. 用户 `~/.failproofai/policies/` 中的约定策略（文件按字母顺序，文件内按 `.add()` 顺序） +2. 来自 `customPoliciesPath` 的显式自定义策略（按 `.add()` 顺序） +3. 项目 `.failproofai/policies/` 的约定策略（文件按字母顺序，文件内按 `.add()` 顺序） +4. 用户 `~/.failproofai/policies/` 的约定策略（文件按字母顺序，文件内按 `.add()` 顺序） -第一条 `deny` 会短路所有后续策略。所有 `instruct` 消息会被累积并一并发送。 +第一个 `deny` 会短路所有后续策略。所有 `instruct` 消息会被汇总后一并发送。 --- @@ -218,13 +223,13 @@ customPolicies.add({ }); ``` -所有从入口文件可达的相对导入均会被解析。其实现方式是将 `from "failproofai"` 的导入重写为实际的 dist 路径，并创建临时 `.mjs` 文件以确保 ESM 兼容性。 +所有从入口文件可达的相对导入都会被解析。实现方式是将 `from "failproofai"` 的导入重写为实际的 dist 路径，并创建临时 `.mjs` 文件以确保 ESM 兼容性。 --- ## 事件类型过滤 -使用 `match.events` 限制策略的触发时机： +使用 `match.events` 限制策略触发的时机： ```js customPolicies.add({ @@ -238,26 +243,26 @@ customPolicies.add({ }); ``` -完全省略 `match` 则对所有事件类型触发。 +完全省略 `match` 则对每种事件类型都触发。 --- ## 错误处理与故障模式 -自定义策略采用**失败开放**原则：错误不会阻止内置策略运行，也不会导致 Hook 处理器崩溃。 +自定义策略采用**故障开放**机制：错误不会阻止内置策略运行，也不会导致 Hook 处理程序崩溃。 | 故障情况 | 行为 | -|----------|------| -| 未设置 `customPoliciesPath` | 不运行显式自定义策略；约定策略和内置策略正常继续 | -| 文件未找到 | 警告记录到 `~/.failproofai/hook.log`；内置策略继续运行 | -| 语法/导入错误（显式） | 错误记录到 `~/.failproofai/hook.log`；跳过显式自定义策略 | -| 语法/导入错误（约定） | 错误记录；跳过该文件，其他约定文件继续加载 | -| `fn` 运行时抛出异常 | 错误记录；该 Hook 视为 `allow`；其他 Hook 继续运行 | -| `fn` 执行超过 10 秒 | 超时记录；视为 `allow` | +|---------|----------| +| `customPoliciesPath` 未设置 | 不运行显式自定义策略；约定策略和内置策略照常运行 | +| 文件未找到 | 警告写入 `~/.failproofai/hook.log`；内置策略继续运行 | +| 语法/导入错误（显式） | 错误写入 `~/.failproofai/hook.log`；跳过显式自定义策略 | +| 语法/导入错误（约定） | 错误写入日志；跳过该文件，其他约定文件继续加载 | +| `fn` 运行时抛出异常 | 错误写入日志；该 Hook 视为 `allow`；其他 Hook 继续执行 | +| `fn` 执行超过 10 秒 | 超时写入日志；视为 `allow` | | 约定目录不存在 | 不运行约定策略；不报错 | -要调试自定义策略错误，可以实时查看日志文件： +要调试自定义策略错误，可监控日志文件： ```bash tail -f ~/.failproofai/hook.log @@ -272,7 +277,7 @@ tail -f ~/.failproofai/hook.log // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// 阻止 Agent 向 secrets/ 目录写入 +// 防止 Agent 写入 secrets/ 目录 customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -285,7 +290,7 @@ customPolicies.add({ }, }); -// 引导 Agent 保持正轨：提交前验证测试 +// 保持 Agent 专注：提交前验证测试 customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +305,7 @@ customPolicies.add({ }, }); -// 在冻结期间防止计划外的依赖变更 +// 冻结期间防止计划外的依赖变更 customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -326,8 +331,8 @@ export { customPolicies }; `examples/` 目录包含可直接运行的策略文件： | 文件 | 内容 | -|------|------| -| `examples/policies-basic.js` | 五条入门策略，覆盖常见 Agent 故障模式 | +|------|----------| +| `examples/policies-basic.js` | 五条入门策略，涵盖常见的 Agent 故障模式 | | `examples/policies-advanced/index.js` | 高级模式：传递性导入、异步调用、输出脱敏、会话结束 Hook | | `examples/convention-policies/security-policies.mjs` | 基于约定的安全策略（阻止 .env 写入、防止 git 历史重写） | | `examples/convention-policies/workflow-policies.mjs` | 基于约定的工作流策略（测试提醒、审计文件写入） | @@ -350,4 +355,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -无需安装命令——文件在下次 Hook 事件触发时会被自动加载。 \ No newline at end of file +无需执行安装命令——文件在下次 Hook 事件时会被自动识别加载。 \ No newline at end of file diff --git a/docs/zh/dashboard.mdx b/docs/zh/dashboard.mdx index 8c52dfc1..883dafd5 100644 --- a/docs/zh/dashboard.mdx +++ b/docs/zh/dashboard.mdx @@ -1,10 +1,10 @@ --- title: 控制台 -description: "监控 Agent 会话、审查工具调用并管理策略" +description: "监控 Agent 会话、查看工具调用并管理策略" icon: chart-line --- -failproofai 控制台是一个本地 Web 应用，用于监控 AI Agent 会话及管理策略。查看 Agent 在后台执行的所有操作。 +failproofai 控制台是一个本地 Web 应用，用于监控 AI Agent 会话和管理策略。查看 Agent 在你离开时所做的一切。 --- @@ -14,77 +14,79 @@ failproofai 控制台是一个本地 Web 应用，用于监控 AI Agent 会话 failproofai ``` -访问地址：`http://localhost:8020`。 +在 `http://localhost:8020` 打开。 -控制台直接从文件系统读取本地项目、会话及 failproofai 配置数据。审计提醒和邀请等可选的认证功能，会将相关请求所需的信息（包括电子邮件地址）发送至远程 API。 +控制台直接从文件系统读取本地项目、会话和 failproofai 配置数据。可选的已认证功能（如审计提醒和邀请）会将相关请求所需的信息（包括电子邮件地址）发送至远程 API。 --- -## 页面说明 +## 页面 ### 项目 -列出本机上所有 Claude Code、OpenAI Codex、GitHub Copilot CLI _(beta)_、Cursor Agent _(beta)_、OpenCode _(beta)_、Pi _(beta)_、Hermes、OpenClaw、Factory Droid、Devin、Antigravity 和 Goose 项目。Claude 项目从 `~/.claude/projects/`（或 `CLAUDE_PROJECTS_PATH` 指定的路径）中发现；Codex 项目通过扫描 `~/.codex/sessions///
/*.jsonl` 下的所有记录，并按每个会话首条记录中的 `cwd` 字段分组；Copilot CLI 项目通过扫描每个 `~/.copilot/session-state//workspace.yaml`（可通过 `COPILOT_HOME` 配置）并按其 `cwd` 字段分组；Cursor Agent 项目通过扫描 `~/.cursor/agent-sessions//`（可通过 `CURSOR_HOME` 配置，同时以 `conversations/` 和 `sessions/` 作为备用路径）下各会话的元数据，从 `meta.json` / `session.json` / `workspace.yaml` 中读取 `cwd` 标量；OpenCode 项目通过 `opencode db --format json` 查询位于 `~/.local/share/opencode/opencode.db` 的 SQLite 数据库（读取 `session` 和 `project` 表，按 `project_id` 分组）；Pi 项目通过扫描 `~/.pi/agent/sessions//_.jsonl`（可通过 `PI_SESSIONS_DIR` 配置）下各会话的 JSONL 记录，并从每个会话首条记录中提取 `cwd`；Hermes 网关会话直接从位于 `~/.hermes/state.db`（可通过 `HERMES_DB_PATH` 配置）的 SQLite 存储中读取，按 `source`（Slack/Telegram/cli/cron）分组为 `hermes-` 项目（网关会话无 cwd）；OpenClaw 网关会话从 `~/.openclaw/agents//sessions/*.jsonl` 读取，分组为 `openclaw-` 项目（同样无 cwd）；Factory Droid 项目从 `~/.factory/sessions//*.jsonl` 的 JSONL 记录中发现，按 cwd 分组；Devin 项目来自位于 `~/.local/share/devin/cli/sessions.db` 的 SQLite 数据库（按每个会话的 `working_directory` 分组）；Antigravity 项目来自 `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` 的 JSONL 记录，按 cwd 分组；Goose 项目来自位于 `~/.local/share/goose/sessions/sessions.db` 的 SQLite 数据库（按每个会话的 `working_dir` 分组）。被多个 CLI 使用的项目会以单行显示，并标注所有匹配的徽标。使用表格上方的 **CLI** 下拉菜单可按特定 Agent CLI 筛选；所选项会以 `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` 的形式保留在 URL 中。 +列出机器上发现的所有 Claude Code、OpenAI Codex、GitHub Copilot CLI _(beta)_、Cursor Agent _(beta)_、OpenCode _(beta)_、Pi _(beta)_、Hermes、OpenClaw、Factory Droid、Devin、Antigravity 和 Goose 项目。Claude 项目从 `~/.claude/projects/`（或由 `CLAUDE_PROJECTS_PATH` 设置的路径）中发现；Codex 项目通过扫描 `~/.codex/sessions///
/*.jsonl` 下的所有记录并按每个会话第一条记录中的 `cwd` 字段分组；Copilot CLI 项目通过扫描每个 `~/.copilot/session-state//workspace.yaml`（可通过 `COPILOT_HOME` 配置）并按 `cwd` 字段分组；Cursor Agent 项目通过扫描 `~/.cursor/agent-sessions//`（可通过 `CURSOR_HOME` 配置，备用路径为 `conversations/` 和 `sessions/`）下的每个会话元数据，从 `meta.json` / `session.json` / `workspace.yaml` 中读取 `cwd` 字段；OpenCode 项目通过 `opencode db --format json` 查询位于 `~/.local/share/opencode/opencode.db` 的 SQLite 数据库（读取 `session` 和 `project` 表并按 `project_id` 分组）；Pi 项目通过扫描 `~/.pi/agent/sessions//_.jsonl`（可通过 `PI_SESSIONS_DIR` 配置）下的每个会话 JSONL 记录并从每个会话的第一条记录中提取 `cwd`；Hermes 网关会话直接从每个配置文件的 SQLite 存储中读取——`~/.hermes/state.db` 加上 `~/.hermes/profiles//state.db`（可通过 `HERMES_HOME` 或单数据库的 `HERMES_DB_PATH` 覆盖）——并按配置文件和 `source`（Slack/Telegram/cli/cron，网关会话无 cwd）分组为 `hermes--` 项目；OpenClaw 网关会话从 `~/.openclaw/agents//sessions/*.jsonl` 读取并按 Agent 和频道分组为 `openclaw--` 项目（同样无 cwd）；Factory Droid 项目从 `~/.factory/sessions//*.jsonl` 的 JSONL 记录中发现并按 cwd 分组；Devin 项目从 `~/.local/share/devin/cli/sessions.db` 的 SQLite 数据库中发现（按每个会话的 `working_directory` 分组）；Antigravity 项目从 `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl` 的 JSONL 记录中发现并按 cwd 分组；Goose 项目从 `~/.local/share/goose/sessions/sessions.db` 的 SQLite 数据库中发现（按每个会话的 `working_dir` 分组）。被多个 CLI 使用的项目会合并为一行并显示所有匹配的徽章。使用表格上方的 **CLI** 下拉菜单按特定 Agent CLI 过滤；URL 会将你的选择保留为 `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`。 + +Hermes 和 OpenClaw 是用户级别的，没有工作目录可供分组，因此以**可折叠文件夹树**的形式呈现——顶层为配置文件（或 Agent），其下为各频道——而所有基于 cwd 的 CLI 保持平铺行显示。文件夹行汇总其下所有内容的会话数量和最近活动时间，折叠状态在访问之间保持记忆，关键词搜索会自动展开匹配项。 每个项目显示： -- 项目名称（从文件夹路径提取） -- CLI 徽标 — `Claude Code`（橙色）、`OpenAI Codex`（紫色）、`GitHub Copilot`（蓝色）、`Cursor Agent`（翠绿色）、`OpenCode`（琥珀色）、`Pi`（粉色）和/或 `Hermes`（靛蓝色） -- 最近会话活动日期 +- 项目名称（从文件夹路径派生） +- CLI 徽章——`Claude Code`（橙色）、`OpenAI Codex`（紫色）、`GitHub Copilot`（蓝色）、`Cursor Agent`（翠绿色）、`OpenCode`（琥珀色）、`Pi`（粉色）和/或 `Hermes`（靛蓝色） +- 最近会话活动的日期 -点击项目可查看其会话列表。 +点击项目可查看其会话。 ### 会话 -列出项目内的所有会话。每个会话显示： +列出项目中的所有会话。每个会话显示： - 会话 ID - 开始和结束时间戳 - 工具调用次数 -- Hook 活动次数（已触发的策略数） +- Hook 活动计数（触发的策略数） -使用日期范围筛选器和会话 ID 搜索来缩小列表范围。会话支持分页显示。 +使用日期范围过滤器和会话 ID 搜索来缩小列表范围。会话以分页方式显示。 点击会话可打开会话查看器。 ### 会话查看器 -会话查看器回答了自主 Agent 的核心问题：Agent 做了什么，是否保持在正轨上？标题旁的 CLI 徽标表明该会话是 Claude Code、OpenAI Codex、GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Hermes、OpenClaw、Factory Droid、Devin、Antigravity 还是 Goose 的记录。它以时间线形式展示会话中发生的一切： +会话查看器回答了自主 Agent 的核心问题：Agent 做了什么，是否保持在正轨上？标题旁的 CLI 徽章指示该会话是 Claude Code、OpenAI Codex、GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Hermes、OpenClaw、Factory Droid、Devin、Antigravity 还是 Goose 的记录。它展示会话中发生的一切的时间线： -- **消息** - Claude 的文本回复和用户提示 -- **工具调用** - Claude 调用的每个工具及其输入输出 -- **策略活动** - 每次工具调用触发了哪些策略，以及策略返回的决策 +- **消息** - Claude 的文本响应和用户提示 +- **工具调用** - Claude 调用的每个工具，包含其输入和输出 +- **策略活动** - 每次工具调用触发了哪些策略及其返回的决策 -顶部的统计栏显示会话时长、工具调用总数，以及 Hook 决策摘要（allow / deny / instruct 计数）。 +顶部统计栏显示会话时长、总工具调用次数以及 hook 决策摘要（allow / deny / instruct 计数）。 -点击 **下载日志** 按钮可导出会话。对于 Claude Code、Codex、Copilot、Cursor 和 Pi 会话，您将获得磁盘上原始的 JSONL 记录文件（字节完全一致）；对于 OpenCode（会话存储在 SQLite 而非磁盘文件中），您将获得一个镜像底层 `session` / `messages` / `parts` 表结构的 JSON 文档。 +点击**下载日志**按钮可导出会话。对于 Claude Code、Codex、Copilot、Cursor 和 Pi 会话，你会获得原始磁盘上的 JSONL 记录（逐字节）；对于 OpenCode（其会话存储在 SQLite 中而非磁盘上），你会获得一个镜像底层 `session` / `messages` / `parts` 表的 JSON 文档。 ### 审计 -一份带有个性化特征的报告，展示 Agent 在过去会话中的实际行为。运行与 `failproofai audit` CLI 相同的扫描逻辑，并以单屏可分享海报 + 四个折叠区块的形式呈现： +一份以个性驱动的报告，反映你的 Agent 在过去会话中的实际行为。运行与 `failproofai audit` CLI 相同的扫描，并以单屏可分享海报 + 四个折叠下方区块的形式呈现： -1. **海报** — 填满第一屏视口。独立的 PNG 截图区域，包含 failproof_ai 字标 + 审计标签 · 原型索引（`№ NN of 08`）+ 审计日期 · 数字评分（0–100）+ 百分位排名标签（`top 15%`）· 原型名称（`the optimist`、`the cowboy`、`the explorer`、`the goldfish`、`the paranoid architect`、`the precision builder`、`the hammer`、`the ghost` 之一）+ 3 个关键词条 · `// only N% of agents are this archetype` 稀有度行 · 8×8 像素印记图块 · `audit yours → failproof.ai` 页脚。截图框外侧有三个分享按钮：`post your archetype`（X 分享）、`share on linkedin`、`download poster`。截图通过 `html-to-image` 生成，PNG 与屏幕渲染像素级一致（虚线边框、SVG 蒙版、渐变、字体度量均完整保留）。 -2. **优势** — 以 ✓ 行的形式平静列出 Agent 已表现良好的行为，源自实时审计数据（工具调用通过率高、未直接推送至主分支、零凭证泄露、零重试风暴）——仅在相关策略在审计窗口内记录清白时才会显示。 -3. **不足** — 按严重程度排列的滑点列表：`时间 · 滑点内容 + 可捕获它的策略 · 严重程度标签 · 出现次数`，其中出现次数标注为 `new`（仅一次）、`N× seen`（2–9 次）或 `recurring`（10 次及以上）。 -4. **改进建议** — 平静列表，每行对应一项推荐策略：策略名称以白色显示，一行描述，右侧为安装命令和复制按钮。区块标题显示 `enable all N → projected · `（应用所有修复后可达到的评分），其 `[install all]` 按钮可复制所有推荐策略的组合安装命令 `failproofai policy add a b c …`。 -5. **下次更好** — 两张并排卡片。左侧：设置提醒（`3d` / `7d` / `14d` / `30d` 周期选择器；通过 `/api/auth/reminder` 在认证后持久化）。右侧：解锁 failproof 特权 — `invite a friend` 打开一个对话框，输入以逗号/空格/换行符分隔的好友邮箱列表（每次最多 10 个），通过 POST 发送至 `/api/audit/invite`，再转发至 api-server 的 `POST /v0/invite`。api-server 从 `invite@failproof.ai` 向每位收件人发送邮件，抄送发件人并设置 `Reply-To`，收件人可看到邀请人信息，发件人也会在收件箱收到副本。匿名用户会先通过 `AuthDialog` 流程，确认发件人邮箱后再发送邀请。权益/特权功能将在后续版本中推出。 +1. **海报** — 填满第一个视口。自包含的 PNG 截图区域，包含 failproof_ai 文字标志 + 审计标签 · 原型索引（`№ NN of 08`）+ 审计日期 · 数字评分（0–100）+ 百分位排名标签（`top 15%`）· 原型名称（`the optimist`、`the cowboy`、`the explorer`、`the goldfish`、`the paranoid architect`、`the precision builder`、`the hammer`、`the ghost` 之一）+ 3 个关键词条 · `// only N% of agents are this archetype` 稀有度说明 · 8×8 像素印记图块 · `audit yours → failproof.ai` 页脚。截图框外有三个分享按钮：`post your archetype`（X 意图）、`share on linkedin`、`download poster`。截图通过 `html-to-image` 实现，确保 PNG 与屏幕渲染像素级一致（虚线边框、SVG 徽标遮罩、渐变、字体度量——全部保留）。 +2. **优势** — 平静的 ✓ 行列表，展示你的 Agent 已经做对的行为，源自实时审计数据（工具调用通过率、未直接推送至主分支、零凭证泄露、零重试风暴）——每项仅在相关策略在审计窗口内保持干净记录时才会显示。 +3. **问题** — 显示漏掉的问题的表格，按严重程度排序：`时间 · 漏掉的问题 + 本可捕获的策略 · 严重程度标签 · 出现次数`，复现次数显示为 `new`（一次）、`N× seen`（2–9 次）或 `recurring`（10 次及以上）。 +4. **改进建议** — 平静的行列表，每行对应一个推荐策略：白色策略名称，一行描述，右侧为安装命令 + 复制按钮。区块标题显示 `enable all N → projected · `（应用所有修复后可达到的评分），其 `[install all]` 按钮可一键复制所有推荐策略的 `failproofai policy add a b c …` 组合命令。 +5. **下次更好** — 两张并排卡片。左侧：设置提醒（`3d` / `7d` / `14d` / `30d` 周期选择器；认证后通过 `/api/auth/reminder` 持久化）。右侧：解锁 failproof 福利——`invite a friend` 打开一个弹窗，接受逗号/空格/换行分隔的好友邮箱列表（每次最多 10 个），POST 至 `/api/audit/invite`，再转发至 api-server 的 `POST /v0/invite`。api-server 从 `invite@failproof.ai` 向每个收件人发送邮件，发件人抄送，并设置 `Reply-To`，收件人可看到邀请人信息，发件人也会在收件箱中收到副本。匿名用户会先被引导至 `AuthDialog`，确保在发出邀请前已知晓发件人邮箱。权益/福利兑现为后续功能。 -由 `failproofai audit` 运行时驱动——扫描引擎、支持的标志及每条记录缓存规则，详见 [审计 CLI](/zh/cli/audit)。控制台将最新结果缓存至 `~/.failproofai/audit-dashboard.json`（权限 `0600`，单槽位，新运行覆盖旧结果），以实现即时回访；**每条记录缓存和整体结果缓存在读取时超过 7 天即失效**，控制台不会静默返回一周前的旧结果——超过 TTL 后，`/audit` 将显示空状态并提示重新运行。点击报告底部的 `[ re-audit now ]` 会向 `/api/audit/run` 发送 `noCache: true` 的 POST 请求——重新审计会绕过每条记录的缓存，从头重新扫描所有记录，而不是静默返回缓存结果——控制台以 1Hz 轮询 `/api/audit/status` 直至运行完成；运行期间，视口顶部会固定显示一条带有计时器的粉色进度条，运行成功后结果就地更新（无需整页刷新；重新审计失败则保留之前的报告）。失败时进度条变红，并根据 `RerunError.kind`（`timeout` / `network` / `post_failed`）显示对应的错误提示。无缓存或缓存过期的空状态，与缓存存在但扫描未发现任何记录的零会话状态，会分别单独展示。 +由 `failproofai audit` 运行时驱动——请参阅 [Audit CLI](/zh/cli/audit) 了解底层扫描引擎、支持的参数和每个记录的缓存不变量。控制台将最新结果缓存在 `~/.failproofai/audit-dashboard.json`（模式 `0600`，单槽，新运行会覆盖），使重复访问即时响应；**每个记录缓存和整体结果缓存在超过 7 天后读取时均会被拒绝**，因此控制台永远不会静默提供一周前的结果——超过 TTL 后 `/audit` 将回落至空状态并提示重新运行。点击报告底部附近的 `[ re-audit now ]` 会向 `/api/audit/run` POST `noCache: true`——重新审计会绕过每个记录的缓存并从头重新扫描所有记录，而非静默返回缓存结果——控制台以 1Hz 轮询 `/api/audit/status` 直至运行完成；运行期间，一个粘性的粉色进度条置顶在视口顶部并显示已用时间，运行成功后新结果就地替换（无需整页刷新；重新审计失败则保留之前的报告）。失败时进度条变为红色，并根据 `RerunError.kind`（`timeout` / `network` / `post_failed`）显示对应文案。空状态（无缓存或已过期）和零会话状态（缓存存在但扫描未找到任何记录）分别单独呈现。 ### 策略 -一个包含两个标签页的页面，用于管理策略和查看活动记录。 +一个两标签页面，用于管理策略和查看活动。 - - - 在单一面板中多选 failproofai 保护的 Agent CLI — Claude Code、OpenAI Codex、GitHub Copilot、Cursor Agent、OpenCode、Pi 和 Hermes 各有一行，显示安装状态（`Active` / `Detected` / `Inactive`）、用户级配置路径以及品牌色调。勾选或取消勾选所需 CLI，点击 `Apply changes` 即可一步完成安装/卸载差异。PATH 中检测到二进制文件的 CLI 会预先勾选。 - - 单击即可启用或禁用单项策略（写入 `~/.failproofai/policies-config.json`——所有已安装的 CLI 共享此配置） - - 展开策略可配置其参数（适用于支持 `policyParams` 的策略） + + - 通过单一面板多选 failproofai 保护的 Agent CLI——Claude Code、OpenAI Codex、GitHub Copilot、Cursor Agent、OpenCode、Pi 和 Hermes 各有一行，显示安装状态（`Active` / `Detected` / `Inactive`）、用户级设置路径和品牌色彩强调。勾选或取消勾选所需的 CLI，点击 `Apply changes` 一步完成安装/卸载差异。PATH 中检测到二进制文件的 CLI 会预先勾选。 + - 一键开启或关闭单个策略（写入 `~/.failproofai/policies-config.json`——在所有已安装的 CLI 之间共享） + - 展开策略以配置其参数（适用于支持 `policyParams` 的策略） - 设置自定义策略文件路径 - - - 所有会话中已触发的每个 Hook 事件的完整分页历史记录 - - 按决策、事件类型、CLI（Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose）、策略名称或会话 ID 筛选 - - 每行显示：时间戳、策略名称、决策、CLI 徽标（橙色 = Claude Code、紫色 = OpenAI Codex、蓝色 = GitHub Copilot、翠绿色 = Cursor Agent、琥珀色 = OpenCode、粉色 = Pi、靛蓝色 = Hermes、青色 = OpenClaw、玫瑰色 = Factory Droid、紫罗兰色 = Devin、青蓝色 = Antigravity、黄绿色 = Goose）、工具名称、会话 ID，以及 deny/instruct 决策的原因 - - 点击会话 ID 可打开对应记录——查看器自动检测触发 Hook 的 CLI（Claude `~/.claude/projects/…`、Codex `~/.codex/sessions/…`、Copilot CLI `~/.copilot/session-state//events.jsonl`、Cursor Agent `~/.cursor/agent-sessions//events.jsonl`、OpenCode `~/.local/share/opencode/opencode.db`、Pi `~/.pi/agent/sessions//.jsonl`、Hermes `~/.hermes/state.db`、OpenClaw `~/.openclaw/agents//sessions/*.jsonl`、Factory Droid `~/.factory/sessions//.jsonl`、Devin `~/.local/share/devin/cli/sessions.db`、Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`、Goose `~/.local/share/goose/sessions/sessions.db`），并在标题中渲染对应的 CLI 徽标 + + - 所有会话中触发的每个 hook 事件的完整分页历史 + - 按决策、事件类型、CLI（Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose）、策略名称或会话 ID 过滤 + - 每行显示：时间戳、策略名称、决策、CLI 徽章（橙色 = Claude Code，紫色 = OpenAI Codex，蓝色 = GitHub Copilot，翠绿色 = Cursor Agent，琥珀色 = OpenCode，粉色 = Pi，靛蓝色 = Hermes，青色 = OpenClaw，玫瑰色 = Factory Droid，紫罗兰色 = Devin，青绿色 = Antigravity，lime 色 = Goose）、工具名称、会话 ID 以及 deny/instruct 决策的原因 + - 点击会话 ID 可打开其记录——查看器自动检测触发 hook 的 CLI（Claude `~/.claude/projects/…`、Codex `~/.codex/sessions/…`、Copilot CLI `~/.copilot/session-state//events.jsonl`、Cursor Agent `~/.cursor/agent-sessions//events.jsonl`、OpenCode `~/.local/share/opencode/opencode.db`、Pi `~/.pi/agent/sessions//.jsonl`、Hermes `~/.hermes/state.db`、OpenClaw `~/.openclaw/agents//sessions/*.jsonl`、Factory Droid `~/.factory/sessions//.jsonl`、Devin `~/.local/share/devin/cli/sessions.db`、Antigravity `~/.gemini/antigravity-cli/brain//…/transcript_full.jsonl`、Goose `~/.local/share/goose/sessions/sessions.db`）并在标题中渲染对应的 CLI 徽章 @@ -92,13 +94,13 @@ failproofai ## 自动刷新 -控制台顶部导航栏提供自动刷新开关。启用后，当前页面会定期刷新，实时显示新会话和策略活动。这对于监控长时间运行的自主 Agent 会话至关重要。 +控制台顶部导航栏中有一个自动刷新开关。启用后，当前页面会定期刷新，以显示新出现的会话和策略活动。这对于监控长时间运行的自主 Agent 会话至关重要。 --- ## 禁用页面 -如果只需要控制台的部分功能，可将 `FAILPROOFAI_DISABLE_PAGES` 设置为以逗号分隔的页面名称列表： +如果你只需要控制台的某些部分，可将 `FAILPROOFAI_DISABLE_PAGES` 设置为以逗号分隔的页面名称列表： ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -110,7 +112,7 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## 配置项目路径 -默认情况下，控制台从标准 Claude Code 项目目录读取数据。如需自定义路径，可通过以下方式覆盖： +默认情况下，控制台从标准 Claude Code 项目目录读取。可为自定义设置覆盖此路径： ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,30 +122,30 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## 从非 localhost 主机访问 -在**开发模式**（`npm run dev`）下运行控制台，并从非 `localhost` 的主机名访问时——例如自定义域名、远程 IP 或隧道 URL——可能会看到如下警告： +在**开发模式**（`npm run dev`）下运行控制台并从 localhost 以外的主机名访问时——例如自定义域名、远程 IP 或隧道 URL——你可能会看到如下警告： ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -这是 Next.js 阻止跨域访问其 HMR（热模块重载）WebSocket 的提示，该功能仅在开发模式下存在。如需允许您的主机，请使用 `--allowed-origins` 标志： +这是 Next.js 阻止跨域访问其 HMR（热模块重载）WebSocket，这是一个仅在开发模式下存在的功能。要允许你的主机，请使用 `--allowed-origins` 参数： ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -如需允许多个主机或 IP，传入以逗号分隔的列表： +对于多个主机或 IP，传入以逗号分隔的列表： ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -也可以改为设置 `FAILPROOFAI_ALLOWED_DEV_ORIGINS` 环境变量： +你也可以改为设置 `FAILPROOFAI_ALLOWED_DEV_ORIGINS` 环境变量： ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -此设置仅适用于开发模式。在运行 `failproofai`（生产模式）时，不存在 HMR WebSocket，也不存在跨域开发资源问题。 +这仅适用于开发模式。在运行 `failproofai`（生产模式）时，不存在 HMR WebSocket 和跨域开发资源问题。 \ No newline at end of file