From 0899671d1e84390081a6f214e89d9d404c78703b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 11 Jul 2026 06:31:33 +0000 Subject: [PATCH 1/2] docs: update translations for changed English sources --- docs/ar/architecture.mdx | 109 +++-- docs/ar/built-in-policies.mdx | 301 +++++++------- docs/ar/cli/audit.mdx | 75 ++-- docs/ar/cli/auth.mdx | 40 +- docs/ar/cli/dashboard.mdx | 11 +- docs/ar/cli/environment-variables.mdx | 25 +- docs/ar/cli/hook.mdx | 16 +- docs/ar/cli/install-policies.mdx | 40 +- docs/ar/cli/list-policies.mdx | 6 +- docs/ar/cli/remove-policies.mdx | 30 +- docs/ar/configuration.mdx | 118 +++--- docs/ar/custom-policies.mdx | 155 ++++--- docs/ar/dashboard.mdx | 99 +++-- docs/ar/examples.mdx | 91 ++-- docs/ar/for-agents.mdx | 29 +- docs/ar/getting-started.mdx | 66 +-- docs/ar/introduction.mdx | 30 +- docs/ar/package-aliases.mdx | 54 +-- docs/ar/testing.mdx | 77 ++-- docs/de/architecture.mdx | 126 +++--- docs/de/built-in-policies.mdx | 164 ++++---- docs/de/cli/audit.mdx | 64 +-- docs/de/cli/auth.mdx | 40 +- docs/de/cli/dashboard.mdx | 6 +- docs/de/cli/environment-variables.mdx | 10 +- docs/de/cli/hook.mdx | 16 +- docs/de/cli/install-policies.mdx | 16 +- docs/de/cli/list-policies.mdx | 6 +- docs/de/cli/remove-policies.mdx | 4 +- docs/de/cli/version.mdx | 2 +- docs/de/configuration.mdx | 92 +++-- docs/de/custom-policies.mdx | 120 +++--- docs/de/dashboard.mdx | 74 ++-- docs/de/examples.mdx | 58 +-- docs/de/for-agents.mdx | 8 +- docs/de/getting-started.mdx | 41 +- docs/de/introduction.mdx | 18 +- docs/de/package-aliases.mdx | 48 +-- docs/de/testing.mdx | 68 +-- docs/es/architecture.mdx | 100 ++--- docs/es/built-in-policies.mdx | 193 +++++---- docs/es/cli/audit.mdx | 78 ++-- docs/es/cli/auth.mdx | 34 +- docs/es/cli/dashboard.mdx | 18 +- docs/es/cli/environment-variables.mdx | 20 +- docs/es/cli/hook.mdx | 14 +- docs/es/cli/install-policies.mdx | 22 +- docs/es/cli/list-policies.mdx | 2 +- docs/es/cli/remove-policies.mdx | 12 +- docs/es/cli/version.mdx | 2 +- docs/es/configuration.mdx | 86 ++-- docs/es/custom-policies.mdx | 116 +++--- docs/es/dashboard.mdx | 58 +-- docs/es/examples.mdx | 46 +-- docs/es/for-agents.mdx | 18 +- docs/es/getting-started.mdx | 47 +-- docs/es/introduction.mdx | 16 +- docs/es/package-aliases.mdx | 40 +- docs/es/testing.mdx | 50 +-- docs/fr/architecture.mdx | 118 +++--- docs/fr/built-in-policies.mdx | 185 +++++---- docs/fr/cli/audit.mdx | 82 ++-- docs/fr/cli/auth.mdx | 36 +- docs/fr/cli/dashboard.mdx | 10 +- docs/fr/cli/environment-variables.mdx | 18 +- docs/fr/cli/hook.mdx | 10 +- docs/fr/cli/install-policies.mdx | 18 +- docs/fr/cli/list-policies.mdx | 2 +- docs/fr/cli/remove-policies.mdx | 14 +- docs/fr/configuration.mdx | 100 ++--- docs/fr/custom-policies.mdx | 94 ++--- docs/fr/dashboard.mdx | 62 +-- docs/fr/examples.mdx | 42 +- docs/fr/for-agents.mdx | 12 +- docs/fr/getting-started.mdx | 37 +- docs/fr/introduction.mdx | 16 +- docs/fr/package-aliases.mdx | 14 +- docs/fr/testing.mdx | 58 +-- docs/he/architecture.mdx | 164 ++++---- docs/he/built-in-policies.mdx | 262 ++++++------ docs/he/cli/audit.mdx | 82 ++-- docs/he/cli/auth.mdx | 39 +- docs/he/cli/dashboard.mdx | 12 +- docs/he/cli/environment-variables.mdx | 37 +- docs/he/cli/hook.mdx | 38 +- docs/he/cli/install-policies.mdx | 34 +- docs/he/cli/list-policies.mdx | 6 +- docs/he/cli/remove-policies.mdx | 21 +- docs/he/cli/version.mdx | 5 +- docs/he/configuration.mdx | 126 +++--- docs/he/custom-policies.mdx | 156 +++---- docs/he/dashboard.mdx | 107 +++-- docs/he/examples.mdx | 77 ++-- docs/he/for-agents.mdx | 32 +- docs/he/getting-started.mdx | 95 ++--- docs/he/introduction.mdx | 22 +- docs/he/package-aliases.mdx | 50 +-- docs/he/testing.mdx | 80 ++-- docs/hi/architecture.mdx | 231 ++++++----- docs/hi/built-in-policies.mdx | 506 +++++++++++------------ docs/hi/cli/audit.mdx | 71 ++-- docs/hi/cli/auth.mdx | 41 +- docs/hi/cli/dashboard.mdx | 2 +- docs/hi/cli/environment-variables.mdx | 18 +- docs/hi/cli/hook.mdx | 14 +- docs/hi/cli/install-policies.mdx | 34 +- docs/hi/cli/list-policies.mdx | 6 +- docs/hi/cli/remove-policies.mdx | 16 +- docs/hi/cli/version.mdx | 4 +- docs/hi/configuration.mdx | 120 +++--- docs/hi/custom-policies.mdx | 182 ++++---- docs/hi/dashboard.mdx | 85 ++-- docs/hi/examples.mdx | 87 ++-- docs/hi/for-agents.mdx | 30 +- docs/hi/getting-started.mdx | 53 +-- docs/hi/introduction.mdx | 29 +- docs/hi/package-aliases.mdx | 56 +-- docs/hi/testing.mdx | 86 ++-- docs/i18n/README.ar.md | 71 ++-- docs/i18n/README.de.md | 61 +-- docs/i18n/README.es.md | 49 ++- docs/i18n/README.fr.md | 54 +-- docs/i18n/README.he.md | 75 ++-- docs/i18n/README.hi.md | 72 ++-- docs/i18n/README.it.md | 73 ++-- docs/i18n/README.ja.md | 51 ++- docs/i18n/README.ko.md | 62 +-- docs/i18n/README.pt-br.md | 39 +- docs/i18n/README.ru.md | 62 +-- docs/i18n/README.tr.md | 64 +-- docs/i18n/README.vi.md | 61 +-- docs/i18n/README.zh.md | 45 +- docs/it/architecture.mdx | 101 ++--- docs/it/built-in-policies.mdx | 354 ++++++++-------- docs/it/cli/audit.mdx | 72 ++-- docs/it/cli/auth.mdx | 40 +- docs/it/cli/dashboard.mdx | 14 +- docs/it/cli/environment-variables.mdx | 25 +- docs/it/cli/hook.mdx | 14 +- docs/it/cli/install-policies.mdx | 22 +- docs/it/cli/list-policies.mdx | 6 +- docs/it/cli/remove-policies.mdx | 22 +- docs/it/cli/version.mdx | 2 +- docs/it/configuration.mdx | 108 ++--- docs/it/custom-policies.mdx | 154 +++---- docs/it/dashboard.mdx | 90 ++-- docs/it/examples.mdx | 71 ++-- docs/it/for-agents.mdx | 22 +- docs/it/getting-started.mdx | 88 ++-- docs/it/introduction.mdx | 24 +- docs/it/package-aliases.mdx | 26 +- docs/it/testing.mdx | 74 ++-- docs/ja/architecture.mdx | 156 +++---- docs/ja/built-in-policies.mdx | 386 ++++++++--------- docs/ja/cli/audit.mdx | 68 +-- docs/ja/cli/auth.mdx | 34 +- docs/ja/cli/dashboard.mdx | 14 +- docs/ja/cli/environment-variables.mdx | 24 +- docs/ja/cli/hook.mdx | 8 +- docs/ja/cli/install-policies.mdx | 36 +- docs/ja/cli/list-policies.mdx | 4 +- docs/ja/cli/remove-policies.mdx | 22 +- docs/ja/cli/version.mdx | 6 +- docs/ja/configuration.mdx | 112 ++--- docs/ja/custom-policies.mdx | 124 +++--- docs/ja/dashboard.mdx | 82 ++-- docs/ja/examples.mdx | 64 +-- docs/ja/for-agents.mdx | 16 +- docs/ja/getting-started.mdx | 51 +-- docs/ja/introduction.mdx | 24 +- docs/ja/package-aliases.mdx | 34 +- docs/ja/testing.mdx | 40 +- docs/ko/architecture.mdx | 138 +++---- docs/ko/built-in-policies.mdx | 344 +++++++-------- docs/ko/cli/audit.mdx | 71 ++-- docs/ko/cli/auth.mdx | 38 +- docs/ko/cli/dashboard.mdx | 6 +- docs/ko/cli/environment-variables.mdx | 14 +- docs/ko/cli/hook.mdx | 18 +- docs/ko/cli/install-policies.mdx | 18 +- docs/ko/cli/list-policies.mdx | 4 +- docs/ko/cli/remove-policies.mdx | 10 +- docs/ko/configuration.mdx | 100 ++--- docs/ko/custom-policies.mdx | 122 +++--- docs/ko/dashboard.mdx | 76 ++-- docs/ko/examples.mdx | 58 +-- docs/ko/for-agents.mdx | 22 +- docs/ko/getting-started.mdx | 49 +-- docs/ko/introduction.mdx | 18 +- docs/ko/package-aliases.mdx | 30 +- docs/ko/testing.mdx | 62 +-- docs/pt-br/architecture.mdx | 76 ++-- docs/pt-br/built-in-policies.mdx | 181 ++++---- docs/pt-br/cli/audit.mdx | 72 ++-- docs/pt-br/cli/auth.mdx | 32 +- docs/pt-br/cli/dashboard.mdx | 4 +- docs/pt-br/cli/environment-variables.mdx | 10 +- docs/pt-br/cli/hook.mdx | 2 +- docs/pt-br/cli/install-policies.mdx | 22 +- docs/pt-br/cli/list-policies.mdx | 6 +- docs/pt-br/cli/remove-policies.mdx | 20 +- docs/pt-br/configuration.mdx | 84 ++-- docs/pt-br/custom-policies.mdx | 110 ++--- docs/pt-br/dashboard.mdx | 62 +-- docs/pt-br/examples.mdx | 52 +-- docs/pt-br/for-agents.mdx | 18 +- docs/pt-br/getting-started.mdx | 23 +- docs/pt-br/introduction.mdx | 18 +- docs/pt-br/package-aliases.mdx | 40 +- docs/pt-br/testing.mdx | 50 +-- docs/ru/architecture.mdx | 212 +++++----- docs/ru/built-in-policies.mdx | 264 ++++++------ docs/ru/cli/audit.mdx | 74 ++-- docs/ru/cli/auth.mdx | 38 +- docs/ru/cli/dashboard.mdx | 12 +- docs/ru/cli/environment-variables.mdx | 22 +- docs/ru/cli/hook.mdx | 16 +- docs/ru/cli/install-policies.mdx | 28 +- docs/ru/cli/list-policies.mdx | 5 +- docs/ru/cli/remove-policies.mdx | 20 +- docs/ru/configuration.mdx | 102 ++--- docs/ru/custom-policies.mdx | 152 +++---- docs/ru/dashboard.mdx | 83 ++-- docs/ru/examples.mdx | 90 ++-- docs/ru/for-agents.mdx | 22 +- docs/ru/getting-started.mdx | 63 +-- docs/ru/introduction.mdx | 26 +- docs/ru/package-aliases.mdx | 40 +- docs/ru/testing.mdx | 67 ++- docs/tr/architecture.mdx | 211 +++++----- docs/tr/built-in-policies.mdx | 257 ++++++------ docs/tr/cli/audit.mdx | 76 ++-- docs/tr/cli/auth.mdx | 41 +- docs/tr/cli/dashboard.mdx | 8 +- docs/tr/cli/environment-variables.mdx | 34 +- docs/tr/cli/hook.mdx | 11 +- docs/tr/cli/install-policies.mdx | 38 +- docs/tr/cli/list-policies.mdx | 20 +- docs/tr/cli/remove-policies.mdx | 22 +- docs/tr/cli/version.mdx | 4 +- docs/tr/configuration.mdx | 120 +++--- docs/tr/custom-policies.mdx | 144 +++---- docs/tr/dashboard.mdx | 82 ++-- docs/tr/examples.mdx | 120 +++--- docs/tr/for-agents.mdx | 24 +- docs/tr/getting-started.mdx | 65 +-- docs/tr/introduction.mdx | 28 +- docs/tr/package-aliases.mdx | 48 +-- docs/tr/testing.mdx | 86 ++-- docs/vi/architecture.mdx | 127 +++--- docs/vi/built-in-policies.mdx | 225 +++++----- docs/vi/cli/audit.mdx | 74 ++-- docs/vi/cli/auth.mdx | 46 +-- docs/vi/cli/dashboard.mdx | 14 +- docs/vi/cli/environment-variables.mdx | 30 +- docs/vi/cli/hook.mdx | 18 +- docs/vi/cli/install-policies.mdx | 30 +- docs/vi/cli/list-policies.mdx | 6 +- docs/vi/cli/remove-policies.mdx | 38 +- docs/vi/cli/version.mdx | 2 +- docs/vi/configuration.mdx | 118 +++--- docs/vi/custom-policies.mdx | 110 ++--- docs/vi/dashboard.mdx | 83 ++-- docs/vi/examples.mdx | 69 ++-- docs/vi/for-agents.mdx | 24 +- docs/vi/getting-started.mdx | 75 ++-- docs/vi/introduction.mdx | 26 +- docs/vi/package-aliases.mdx | 36 +- docs/vi/testing.mdx | 46 +-- docs/zh/architecture.mdx | 140 +++---- docs/zh/built-in-policies.mdx | 230 +++++------ docs/zh/cli/audit.mdx | 63 +-- docs/zh/cli/auth.mdx | 38 +- docs/zh/cli/dashboard.mdx | 8 +- docs/zh/cli/environment-variables.mdx | 4 +- docs/zh/cli/hook.mdx | 10 +- docs/zh/cli/install-policies.mdx | 30 +- docs/zh/cli/list-policies.mdx | 6 +- docs/zh/cli/remove-policies.mdx | 14 +- docs/zh/cli/version.mdx | 2 +- docs/zh/configuration.mdx | 94 ++--- docs/zh/custom-policies.mdx | 114 ++--- docs/zh/dashboard.mdx | 76 ++-- docs/zh/examples.mdx | 72 ++-- docs/zh/for-agents.mdx | 30 +- docs/zh/getting-started.mdx | 61 +-- docs/zh/introduction.mdx | 22 +- docs/zh/package-aliases.mdx | 28 +- docs/zh/testing.mdx | 80 ++-- 289 files changed, 9106 insertions(+), 8910 deletions(-) diff --git a/docs/ar/architecture.mdx b/docs/ar/architecture.mdx index bfa6a8d1..ef1042c7 100644 --- a/docs/ar/architecture.mdx +++ b/docs/ar/architecture.mdx @@ -1,23 +1,22 @@ --- - --- -title: العمارة +title: البنية المعمارية description: "كيفية عمل معالج الخطاف وتحميل الإعدادات وتقييم السياسات بشكل داخلي" icon: sitemap --- -تشرح هذه الوثيقة كيفية عمل failproofai بشكل داخلي: كيفية اعتراض نظام الخطاف لاستدعاءات أدوات الوكيل، وكيفية تحميل ودمج الإعدادات، وكيفية تقييم السياسات، وكيفية مراقبة لوحة التحكم لنشاط الوكيل. +تشرح هذه الوثيقة كيفية عمل failproofai داخليًا: كيف يعترض نظام الخطاف استدعاءات أدوات الوكيل، وكيف يتم تحميل الإعدادات ودمجها، وكيف يتم تقييم السياسات، وكيف تراقب لوحة المعلومات نشاط الوكيل. --- ## نظرة عامة -يمتلك failproofai نظامين فرعيين مستقلين: +يحتوي failproofai على نظامين فرعيين مستقلين: -1. **معالج الخطاف** - عملية سطر أوامر سريعة يستدعيها Claude Code على كل استدعاء أداة وكيل. يقيّم السياسات ويعيد قرارًا. -2. **مراقب الوكيل (لوحة التحكم)** - تطبيق ويب Next.js لمراقبة جلسات الوكيل وإدارة السياسات. +1. **معالج الخطاف** - عملية CLI سريعة يستدعيها Claude Code على كل استدعاء لأداة وكيل. يقيّم السياسات ويعيد قرارًا. +2. **مراقب الوكيل (لوحة المعلومات)** - تطبيق ويب Next.js لمراقبة جلسات الوكيل وإدارة السياسات. -يشترك كلا النظامين الفرعيين في ملفات الإعدادات في `~/.failproofai/` ومجلد `.failproofai/` الخاص بالمشروع، لكنهما يعملان كعمليات منفصلة ويتصلان فقط عبر نظام الملفات. +يشارك كلا النظامين الفرعيين ملفات الإعدادات في `~/.failproofai/` ودليل المشروع `.failproofai/`، لكنهما يعملان كعمليات منفصلة ولا يتواصلان إلا عبر نظام الملفات. --- @@ -46,7 +45,7 @@ icon: sitemap } ``` -ثم يستدعي Claude Code `failproofai --hook PreToolUse` كعملية فرعية قبل كل استدعاء أداة، مرسلاً حمولة JSON عبر stdin. +ثم يستدعي Claude Code `failproofai --hook PreToolUse` كعملية فرعية قبل كل استدعاء أداة، ويمرر حمولة JSON على stdin. ### تنسيق الحمولة @@ -62,9 +61,9 @@ icon: sitemap } ``` -بالنسبة لأحداث `PostToolUse`، تحتوي الحمولة أيضًا على `tool_result` مع مخرجات الأداة. +بالنسبة لأحداث `PostToolUse`، تحتوي الحمولة أيضًا على `tool_result` بمخرجات الأداة. -يفرض المعالج حدًا أقصى لـ stdin بحجم 1 ميجابايت. يتم تجاهل الحمولات التي تتجاوز هذا الحد وجميع السياسات تسمح ضمنيًا. +يفرض المعالج حد أقصى بحجم 1 ميجابايت على stdin. يتم تجاهل الحمولات التي تتجاوز هذا الحد وتسمح جميع السياسات ضمنيًا. ### تنسيق الاستجابة @@ -87,7 +86,7 @@ icon: sitemap } ``` -**توجيه (أي حدث ما عدا Stop):** +**تعليمات (أي حدث ما عدا Stop):** ```json { "hookSpecificOutput": { @@ -96,9 +95,9 @@ icon: sitemap } ``` -**توجيه حدث التوقف:** +**حدث التعليمات الخاص:** - رمز الخروج: `2` -- السبب مكتوب في stderr (وليس stdout) +- السبب المكتوب على stderr (وليس stdout) **السماح:** - رمز الخروج: `0` @@ -106,7 +105,7 @@ icon: sitemap **السماح مع رسالة:** -يسمح `allow(message)` للسياسة بإرسال سياق معلومات إلى Claude حتى عند السماح بالعملية. يكتب معالج الخطاف JSON التالي إلى **stdout** (وليس ملف إعدادات — هذه هي استجابة المعالج لـ Claude Code، تماماً مثل الإجابات على الرفض والتوجيه أعلاه): +يسمح `allow(message)` لسياسة بإرسال سياق معلومات مرة أخرى إلى Claude حتى عند السماح بالعملية. يكتب معالج الخطاف JSON التالي إلى **stdout** (وليس ملف إعدادات — هذه هي استجابة المعالج لـ Claude Code، تمامًا مثل استجابات الرفض والتعليمات أعلاه): ```json // Written to stdout by the hook handler process @@ -116,13 +115,13 @@ icon: sitemap } } ``` -- رمز الخروج: `0` (العملية مسموحة) -- عند عودة عدة سياسات `allow` برسالة، يتم ربط رسائلها بفواصل سطر جديد في سلسلة `additionalContext` واحدة -- إذا لم توفر أي سياسة رسالة، يكون stdout فارغاً (نفس السابق) +- رمز الخروج: `0` (العملية مسموح بها) +- عند إرجاع عدة سياسات `allow` مع رسالة، يتم دمج رسائلها مع فواصل أسطر في سلسلة `additionalContext` واحدة +- إذا لم توفر أي سياسة رسالة، يكون stdout فارغًا (كما هو الحال من قبل) ### خط أنابيب المعالجة -ينفذ `src/hooks/handler.ts` خط الأنابيب الكامل: +تنفذ `src/hooks/handler.ts` خط الأنابيب الكامل: ```text stdin JSON @@ -147,7 +146,7 @@ stdin JSON ## تحميل الإعدادات -يطبق `src/hooks/hooks-config.ts` تحميل الإعدادات بثلاث نطاقات. +تنفذ `src/hooks/hooks-config.ts` تحميل الإعدادات ثلاثي النطاق. ```text [1] {cwd}/.failproofai/policies-config.json ← project (highest priority) @@ -156,39 +155,39 @@ stdin JSON ``` منطق الدمج: -- `enabledPolicies` - اتحاد مزال التكرار عبر جميع الملفات الثلاثة -- `policyParams` - لكل سياسة، الملف الأول الذي يعرّفها يفوز بالكامل -- `customPoliciesPath` - الملف الأول الذي يعرّفه يفوز -- `llm` - الملف الأول الذي يعرّفه يفوز +- `enabledPolicies` - اتحاد مخصص عبر جميع الملفات الثلاثة +- `policyParams` - لكل سياسة، الملف الأول الذي يحددها يفوز بالكامل +- `customPoliciesPath` - الملف الأول الذي يحددها يفوز +- `llm` - الملف الأول الذي يحددها يفوز -تستخدم لوحة تحكم الويب `readHooksConfig()` (العام فقط) للقراءة والكتابة، حيث لا يتم استدعاؤها مع cwd المشروع. +تستخدم لوحة معلومات الويب `readHooksConfig()` (عام فقط) للقراءة والكتابة، حيث لا يتم استدعاؤها مع cwd مشروع. --- ## تقييم السياسة -يشغل `src/hooks/policy-evaluator.ts` السياسات بالترتيب. +تشغيل `src/hooks/policy-evaluator.ts` السياسات بالترتيب. لكل سياسة: -1. البحث عن مخطط `params` الخاص بالسياسة (إن وجد). -2. قراءة `policyParams[policy.name]` من الإعدادات المدمجة. -3. دمج القيم المقدمة من قبل المستخدم فوق الافتراضيات في المخطط لإنتاج `ctx.params`. -4. استدعاء `policy.fn(ctx)` مع السياق المحل. -5. إذا كانت النتيجة `deny`، توقف على الفور وأعد هذا القرار. -6. إذا كانت النتيجة `instruct`، تراكم الرسالة والمتابعة. +1. ابحث عن مخطط `params` الخاص بالسياسة (إن وجد). +2. اقرأ `policyParams[policy.name]` من الإعدادات المدمجة. +3. دمج القيم المتوفرة من المستخدم فوق الافتراضيات الخاصة بالمخطط لإنتاج `ctx.params`. +4. استدعِ `policy.fn(ctx)` مع السياق المحل. +5. إذا كانت النتيجة `deny`، توقف فورًا وأعد هذا القرار. +6. إذا كانت النتيجة `instruct`، جمّع الرسالة وتابع. 7. إذا كانت النتيجة `allow`، انتقل إلى السياسة التالية. بعد تشغيل جميع السياسات: -- إذا تم إرجاع أي `deny`، أصدر استجابة الرفض. -- إذا تم جمع أي عائدات `instruct`، أصدر استجابة توجيه واحدة مع ربط جميع الرسائل. -- وإلا، أصدر استجابة السماح (stdout فارغ، الخروج 0). +- إذا تم إرجاع أي `deny`، صدر استجابة الرفض. +- إذا تم جمع أي استجابات `instruct`، أصدر استجابة تعليمات واحدة مع دمج جميع الرسائل. +- بخلاف ذلك، أصدر استجابة سماح (stdout فارغ، الخروج 0). --- ## السياسات المدمجة -يعرّف `src/hooks/builtin-policies.ts` جميع 39 سياسة مدمجة كائنات `BuiltinPolicyDefinition`: +تحدد `src/hooks/builtin-policies.ts` جميع 39 سياسة مدمجة كائنات `BuiltinPolicyDefinition`: ```typescript interface BuiltinPolicyDefinition { @@ -206,15 +205,15 @@ interface BuiltinPolicyDefinition { } ``` -السياسات التي تقبل `params` تعلن `PolicyParamsSchema` بأنواع وافتراضيات لكل معامل. يحقن مقيّم السياسة القيم المحلة في `ctx.params` قبل استدعاء `fn`. تقرأ دوال السياسة `ctx.params` بدون حماية فارغة لأن الافتراضيات تُطبق دائماً أولاً. +تصرح السياسات التي تقبل `params` بـ `PolicyParamsSchema` مع الأنواع والقيم الافتراضية لكل معامل. يدرج محيّم السياسة القيم المحلولة في `ctx.params` قبل استدعاء `fn`. تقرأ دوال السياسة `ctx.params` دون حماية فارغة لأن الافتراضيات يتم تطبيقها دائمًا أولاً. -يستخدم مطابقة الأنماط داخل السياسات رموز الأوامر المحللة (argv)، وليس مطابقة السلسلة النصية الخام. وهذا يمنع الالتفاف عبر حقن عامل الأوامر (على سبيل المثال، نمط لـ `sudo systemctl status *` لا يمكن الالتفاف عليه بإضافة `; rm -rf /` إلى الأمر). +يستخدم تطابق النمط داخل السياسات رموز الأوامر المحللة (argv)، وليس مطابقة السلسلة الخام. هذا يمنع الالتفاف عبر حقن مشغلات shell (على سبيل المثال، نمط لـ `sudo systemctl status *` لا يمكن التفافه عن طريق إضافة `; rm -rf /` إلى الأمر). --- ## السياسات المخصصة -ينفذ `src/hooks/custom-hooks-registry.ts` سجل مدعوم `globalThis`: +تنفذ `src/hooks/custom-hooks-registry.ts` سجل مدعوم بـ `globalThis`: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -229,17 +228,17 @@ export function clearCustomHooks(): void { ... } // used in tests يحمل `src/hooks/custom-hooks-loader.ts` ملف السياسة الخاص بالمستخدم: -1. اقرأ `customPoliciesPath` من الإعدادات؛ تخطي إذا كان غائباً. +1. اقرأ `customPoliciesPath` من الإعدادات؛ تخطَّ إذا كان غائبًا. 2. حل إلى مسار مطلق؛ تحقق من وجود الملف. -3. أعد كتابة جميع واردات `from "failproofai"` إلى مسار dist الفعلي حتى يتم حل `customPolicies` إلى نفس سجل `globalThis`. -4. أعد كتابة الواردات المحلية العابرة بشكل متكرر لضمان التوافقية ESM. -5. اكتب ملفات `.mjs` مؤقتة و`import()` ملف الدخول. -6. اتصل بـ `getCustomHooks()` لاسترجاع الخطافات المسجلة. +3. أعد كتابة جميع استيرادات `from "failproofai"` إلى مسار dist الفعلي بحيث يتم حل `customPolicies` إلى سجل `globalThis` نفسه. +4. أعد كتابة الاستيرادات المحلية الانتقالية بشكل متكرر لضمان التوافق مع ESM. +5. اكتب ملفات `.mjs` مؤقتة و`import()` ملف الإدخال. +6. استدعِ `getCustomHooks()` لاسترجاع الخطافات المسجلة. 7. نظف جميع الملفات المؤقتة في كتلة `finally`. -في حالة حدوث أي خطأ (ملف غير موجود، خطأ بناء جملة، فشل الاستيراد)، يتم تسجيل الخطأ في `~/.failproofai/hook.log` ويعيد المحمل مصفوفة فارغة. السياسات المدمجة غير متأثرة. +عند أي خطأ (ملف غير موجود، خطأ بناء جملة، فشل استيراد)، يتم تسجيل الخطأ إلى `~/.failproofai/hook.log` ويعيد المحمل مصفوفة فارغة. السياسات المدمجة لم تتأثر. -يتم تقييم السياسات المخصصة بعد جميع السياسات المدمجة. إنكار السياسة المخصصة لا يزال يختصر السياسات المخصصة الإضافية (لكن جميع المدمجة قد عملت بالفعل في تلك النقطة). +يتم تقييم السياسات المخصصة بعد جميع السياسات المدمجة. لا يزال `deny` السياسة المخصصة يختصر السياسات المخصصة الإضافية (لكن جميع المدمجة قد عملت بالفعل في هذه المرحلة). --- @@ -260,13 +259,13 @@ export function clearCustomHooks(): void { ... } // used in tests } ``` -سطر واحد لكل سياسة اتخذت قرار غير سماح. لا يتم تسجيل قرارات السماح (للحفاظ على صغر حجم الملف). +سطر واحد لكل سياسة اتخذت قرارًا بعدم السماح. لا يتم تسجيل قرارات السماح (للحفاظ على حجم الملف صغيرًا). --- -## عمارة لوحة التحكم +## بنية لوحة المعلومات -لوحة التحكم هي تطبيق **Next.js 16** يستخدم App Router مع React Server Components و Server Actions. +لوحة المعلومات عبارة عن تطبيق **Next.js 16** يستخدم App Router مع React Server Components و Server Actions. ```text app/ @@ -288,16 +287,16 @@ app/ **تدفق البيانات:** -- تستدعي مكونات الصفحة `lib/projects.ts` و `lib/log-entries.ts` لقراءة بيانات المشروع/الجلسة مباشرة من نظام الملفات (بدون طبقة API للقراءات). -- تستخدم صفحة السياسات Server Actions لجميع التطبيقات (تبديل، تحديث المعاملات، التثبيت/الإزالة). -- يحلل عارض الجلسة تنسيق نص Claude JSONL ويعرض جدول زمني للرسائل واستدعاءات الأدوات. +- تستدعي مكونات الصفحة `lib/projects.ts` و`lib/log-entries.ts` لقراءة بيانات المشروع/الجلسة مباشرة من نظام الملفات (لا توجد طبقة API للقراءات). +- تستخدم صفحة السياسات Server Actions لجميع التغييرات (تبديل، تحديث المعاملات، التثبيت/الإزالة). +- يحلل عارض الجلسة تنسيق نصوص JSONL الخاص بـ Claude ويرسم خط زمني للرسائل واستدعاءات الأدوات. **قرارات التصميم الرئيسية:** -- بدون قاعدة بيانات - جميع الحالة الدائمة موجودة في ملفات عادية (`~/.failproofai/`، `~/.claude/projects/`). -- Server Actions للتطبيقات - لا حاجة إلى REST API لعمليات CRUD. -- React Server Components لصفحات القراءة - تحميل أولي أسرع، بدون حزمة عميل لجلب البيانات. -- مكونات العميل فقط حيث تكون التفاعلية مطلوبة (تبديلات السياسة، بحث النشاط، عارض السجل). +- لا قاعدة بيانات - جميع الحالات الدائمة موجودة في ملفات عادية (`~/.failproofai/`, `~/.claude/projects/`). +- Server Actions للتغييرات - لا توجد حاجة إلى REST API لعمليات CRUD. +- React Server Components لصفحات القراءة - تحميل أسرع للبداية، لا توجد حزمة عميل لجلب البيانات. +- مكونات العميل فقط حيث تكون التفاعلية مطلوبة (تبديلات السياسة، البحث عن النشاط، عارض السجل). --- diff --git a/docs/ar/built-in-policies.mdx b/docs/ar/built-in-policies.mdx index 80b396a7..1c508863 100644 --- a/docs/ar/built-in-policies.mdx +++ b/docs/ar/built-in-policies.mdx @@ -1,11 +1,10 @@ --- ---- title: السياسات المدمجة -description: "جميع 39 سياسة مدمجة تمنع أوضاع فشل الوكيل الشائعة" +description: "39 سياسة مدمجة تمنع أنماط فشل الوكلاء الشائعة" icon: shield --- -يأتي failproofai مع 39 سياسة مدمجة تمنع أوضاع فشل الوكيل الشائعة. تعمل كل سياسة على نوع حدث خطاف محدد واسم أداة معينة. تقبل تسع عشرة سياسة معاملات تسمح لك بضبط سلوكها دون كتابة أي كود. تفرض خمس سياسات سير عمل خط أنابيب commit → push → PR → CI قبل توقف Claude. +يأتي failproofai مع 39 سياسة مدمجة تمنع أنماط فشل الوكلاء الشائعة. تعمل كل سياسة على نوع حدث hook محدد واسم أداة معين. تقبل تسع عشرة سياسة معاملات تتيح لك ضبط سلوكها دون كتابة أكواد. تفرض خمس سياسات سير عمل خط أنابيب التزام → دفع → طلب دمج → CI قبل توقف Claude. --- @@ -13,28 +12,32 @@ icon: shield يتم تجميع السياسات في فئات: -| الفئة | السياسات | نوع الخطاف | +| الفئة | السياسات | نوع Hook | |----------|----------|-----------| -| [الأوامر الخطيرة](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | -| [أوامر البنية الأساسية](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [الأسرار (معقمات)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [الأوامر الخطرة](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | +| [أوامر البنية التحتية](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | +| [الأسرار (معقّمات)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | | [البيئة](#environment) | block-env-files, protect-env-vars | PreToolUse | -| [الوصول للملفات](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | +| [الوصول إلى الملفات](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | | [قاعدة البيانات](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse | -| [التحذيرات](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | +| [تحذيرات](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | | [مديري الحزم](#package-managers) | prefer-package-manager | PreToolUse | | [سير العمل](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — توقيف الوكيل عن المتابعة. -- **`warn-`** — إعطاء الوكيل سياق إضافي حتى يتمكن من تصحيح نفسه بنفسه. -- **`sanitize-`** — حذف البيانات الحساسة من مخرجات الأداة قبل وصولها للوكيل. +- **`block-`** — إيقاف الوكيل عن المتابعة. +- **`warn-`** — إعطاء الوكيل سياق إضافي حتى يتمكن من تصحيح نفسه. +- **`sanitize-`** — إزالة البيانات الحساسة من مخرجات الأداة قبل أن يراها الوكيل. -### المساحات +### الأسماء الموصوفة -تعيش كل سياسة في فتحة `/`. تنتمي السياسات المدمجة إلى مساحة **`failproofai/`** — على سبيل المثال، `failproofai/sanitize-jwt`. تمنع المساحة الاسمية الاصطدامات عند تحميل سياسات مخصصة أو من جهات خارجية بأسماء قصيرة متشابهة. +تقع كل سياسة في فتحة `/`. تنتمي السياسات المدمجة إلى الفضاء الموصوف +**`failproofai/`** — على سبيل المثال، `failproofai/sanitize-jwt`. يمنع الفضاء الموصوف +التصادمات عند تحميل سياسات مخصصة أو من طرف ثالث +بأسماء قصيرة متشابهة. -في إعدادك، يمكنك الإشارة إلى سياسة مدمجة بواسطة اسمها القصير أو اسمها المؤهل؛ كلا الشكلين يؤديان إلى نفس السياسة: +في ملف التكوين الخاص بك، يمكنك الإشارة إلى سياسة مدمجة باستخدام اسمها القصير أو اسمها +المؤهل؛ كلا الشكلين يحل لنفس السياسة: ```json { @@ -45,33 +48,35 @@ icon: shield } ``` -إذا لم يكن لأي اسم `/`، يعامله failproofai كما ينتمي إلى المساحة الافتراضية `failproofai`. تُحتفظ بالأسماء التي تحتوي بالفعل على `/` (مثل `myorg/foo`، `custom/my-hook`) كما هي. -- **`require-`** — توقيف حدث الإيقاف حتى تتم الشروط. +إذا لم يكن للاسم أي `/`، يعامل failproofai اسمه كتابعاً للفضاء الموصوف الافتراضي +`failproofai`. الأسماء التي تحتوي بالفعل على `/` (مثل `myorg/foo`، +`custom/my-hook`) تُبقى كما هي. +- **`require-`** — منع حدث Stop حتى يتم استيفاء الشروط. --- -كل سياسة تدعم حقل `hint` اختياري في `policyParams`. يتم إلحاق التلميح برسالة deny أو instruct التي يراها Claude، مما يوفر توجيهات قابلة للتنفيذ دون تعديل كود السياسة. يعمل مع السياسات المدمجة والمخصصة والمتعارف عليها. راجع [Configuration → hint](/ar/configuration#hint-cross-cutting) للتفاصيل. +تدعم كل سياسة حقل `hint` اختياري في `policyParams`. يتم إلحاق hint بعنوان الرفض أو التعليمات الذي يراه Claude، مما يوفر إرشادات قابلة للتنفيذ دون تعديل كود السياسة. يعمل مع السياسات المدمجة والمخصصة والاتفاقية. راجع [الإعدادات → hint](/ar/configuration#hint-cross-cutting) للحصول على التفاصيل. --- -## الأوامر الخطيرة +## الأوامر الخطرة -منع الوكلاء من تشغيل العمليات التي يصعب التراجع عنها أو التي قد تضر النظام المضيف. +منع الوكلاء من تشغيل العمليات التي يصعب التراجع عنها أو التي قد تضر بنظام الكمبيوتر. ### `block-sudo` **الحدث:** PreToolUse (Bash) **الافتراضي:** ينكر أي أمر `sudo`. -يحجب الاستدعاءات التي تتضمن كلمة المفتاح `sudo`. يتم مطابقة النمط على رموز الأوامر المحللة، وليس السلسلة الخام، لمنع التحايل عبر حقن عامل الصدفة. +يمنع الاستدعاءات التي تتضمن كلمة `sudo`. يتم مطابقة النمط على رموز الأوامر المحللة، وليس السلسلة الأصلية، لمنع الالتفافة عبر حقن عامل الأغلاف. **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | بادئات أوامر دقيقة مسموحة. يتم مطابقة كل إدخال مقابل رموز argv المحللة. | +| `allowPatterns` | `string[]` | `[]` | بادئات الأوامر الدقيقة المسموحة. يتم مطابقة كل إدخال مقابل رموز argv المحللة. | **مثال:** @@ -85,10 +90,10 @@ icon: shield } ``` -مع هذا الإعداد، `sudo systemctl status nginx` مسموح، لكن `sudo rm /etc/hosts` مرفوض. +مع هذا التكوين، يُسمح بـ `sudo systemctl status nginx`، لكن `sudo rm /etc/hosts` مرفوض. -يتم مطابقة الأنماط مقابل الرموز المحللة، وليس سلسلة الأوامر الخام. هذا يمنع التحايل عبر عوامل الصدفة المضافة (مثل `sudo systemctl status x; rm -rf /` لا تطابق `sudo systemctl status *`). +يتم مطابقة الأنماط مقابل الرموز المحللة، وليس السلسلة الأصلية للأمر. يمنع هذا الالتفافة عبر عوامل الأغلاف المرفقة (مثل `sudo systemctl status x; rm -rf /` لا يطابق `sudo systemctl status *`). --- @@ -96,13 +101,13 @@ icon: shield ### `block-rm-rf` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر `rm -rf`، `rm -fr`، وأشكال الحذف التكراري المشابهة. +**الافتراضي:** ينكر `rm -rf`، `rm -fr`، وأشكال الحذف المتكررة المماثلة. **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | المسارات التي يمكن حذفها بشكل آمن بشكل متكرر (مثل `/tmp`). | +| `allowPaths` | `string[]` | `[]` | المسارات التي يمكن حذفها بشكل متكرر بأمان (مثل `/tmp`). | **مثال:** @@ -121,7 +126,7 @@ icon: shield ### `block-curl-pipe-sh` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر `curl | bash`، `curl | sh`، `wget | bash`، والأنماط المشابهة. +**الافتراضي:** ينكر `curl | bash`، `curl | sh`، `wget | bash`، والأنماط المماثلة. لا توجد معاملات. @@ -130,17 +135,17 @@ icon: shield ### `block-failproofai-commands` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر الأوامر التي قد تلغي تثبيت أو تعطل failproofai نفسه (مثل `npm uninstall failproofai`، `failproofai policies --uninstall`). +**الافتراضي:** ينكر الأوامر التي ستلغي تثبيت أو تعطيل failproofai نفسه (مثل `npm uninstall failproofai`، `failproofai policies --uninstall`). لا توجد معاملات. --- -## أوامر البنية الأساسية +## أوامر البنية التحتية -توقيف وكلاء الترميز من تشغيل CLIs البنية الأساسية أو تفعيل خطوط أنابيب CI/CD. جميع السياسات في هذه الفئة **opt-in** (`defaultEnabled: false`) — الوكلاء الذين يحتاجون بشكل شرعي إلى استدعاء `kubectl`، `terraform`، إلخ لن يتم إزعاجهم ما لم تفعل السياسة. عند التفعيل، يتم رفض كل استدعاء للـ CLI المطابق ما لم تطابق الأمر إدخال في `allowPatterns`. +منع وكلاء البرمجة من تشغيل CLI البنية التحتية أو بدء خطوط أنابيب CI/CD. جميع السياسات في هذه الفئة **اختيارية** (`defaultEnabled: false`) — الوكلاء الذين يحتاجون فعلاً إلى استدعاء `kubectl`، `terraform`، إلخ. لن يتعطلوا ما لم تفعّل السياسة. عند التفعيل، يتم رفض كل استدعاء للأداة المطابقة ما لم يطابق الأمر إدخالاً في `allowPatterns`. -قواعد النمط هي نفسها كما في [`block-sudo`](#block-sudo): يتم مطابقة الرموز مقابل argv المحللة، `*` هو بدل لرمز واحد، وأي أمر يحتوي على عامل صدفة مستقل (`&&`، `||`، `|`، `;`) أو رمز بأحرف صدفة مدمجة يتم رفضه قبل مطابقة القائمة البيضاء لمنع تجاوزات الحقن. +نحو النمط هو نفسه [`block-sudo`](#block-sudo): يتم مطابقة الرموز مقابل argv المحللة، `*` هو حرف بدل لرمز واحد، وأي أمر يحتوي على عامل أغلاف مستقل (`&&`، `||`، `|`، `;`) أو رمز يحتوي على أحرف أغلاف مضمنة يُرفض قبل مطابقة القائمة البيضاء لمنع التفافات الحقن. ### `block-kubectl` @@ -149,9 +154,9 @@ icon: shield **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | بادئات أوامر kubectl مسموحة. | +| `allowPatterns` | `string[]` | `[]` | بادئات أوامر kubectl المسموحة. | **مثال:** @@ -165,7 +170,7 @@ icon: shield } ``` -مع هذا الإعداد، `kubectl get pods` مسموح لكن `kubectl apply -f deploy.yaml` مرفوض. +مع هذا التكوين، يُسمح بـ `kubectl get pods` لكن `kubectl apply -f deploy.yaml` مرفوض. --- @@ -176,9 +181,9 @@ icon: shield **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | بادئات أوامر terraform/tofu مسموحة. | +| `allowPatterns` | `string[]` | `[]` | بادئات أوامر terraform/tofu المسموحة. | **مثال:** @@ -197,13 +202,13 @@ icon: shield ### `block-aws-cli` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر أي استدعاء `aws` CLI. +**الافتراضي:** ينكر أي استدعاء CLI `aws`. **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | بادئات أوامر aws CLI مسموحة. | +| `allowPatterns` | `string[]` | `[]` | بادئات أوامر aws CLI المسموحة. | **مثال:** @@ -222,13 +227,13 @@ icon: shield ### `block-gcloud` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر أي استدعاء `gcloud` (Google Cloud) CLI. +**الافتراضي:** ينكر أي استدعاء CLI `gcloud` (Google Cloud). **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | بادئات أوامر gcloud مسموحة. | +| `allowPatterns` | `string[]` | `[]` | بادئات أوامر gcloud المسموحة. | **مثال:** @@ -247,13 +252,13 @@ icon: shield ### `block-az-cli` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر أي استدعاء `az` (Azure) CLI. +**الافتراضي:** ينكر أي استدعاء CLI `az` (Azure). **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | بادئات أوامر az CLI مسموحة. | +| `allowPatterns` | `string[]` | `[]` | بادئات أوامر az CLI المسموحة. | **مثال:** @@ -276,9 +281,9 @@ icon: shield **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | بادئات أوامر helm مسموحة. | +| `allowPatterns` | `string[]` | `[]` | بادئات أوامر helm المسموحة. | **مثال:** @@ -297,7 +302,7 @@ icon: shield ### `block-gh-pipeline` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر أوامر `gh` CLI الفرعية التالية التي تغير الحالة أو تفعل خطوط الأنابيب: +**الافتراضي:** ينكر أوامر CLI `gh` الفرعية التالية التي تغيّر الحالة أو تبدأ خطوط أنابيب: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -306,13 +311,13 @@ icon: shield - `gh cache delete` - `gh secret set`, `gh secret delete` -أوامر `gh` الفرعية للقراءة فقط مثل `gh pr view`، `gh pr list`، `gh run list`، `gh release view`، و `gh api repos/.../...` **لا** تتطابق مع هذه السياسة — فهي مطلوبة بشكل روتيني لفحوصات سير العمل (بما في ذلك `require-ci-green-before-stop` الخاص بـ failproofai). +أوامر `gh` الفرعية للقراءة فقط مثل `gh pr view`, `gh pr list`, `gh run list`, `gh release view`, و `gh api repos/.../...` **لا** يتطابقون مع هذه السياسة — يُحتاج إليهم بشكل منتظم لفحوصات سير العمل (بما في ذلك `require-ci-green-before-stop` الخاص بـ failproofai). **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | استدعاءات نصية محددة للسماح بها على الرغم من أنها ستكون مرفوضة بخلاف ذلك. | +| `allowPatterns` | `string[]` | `[]` | استدعاءات برمجية محددة للسماح بها رغم أنها كانت ستُرفض. | **مثال:** @@ -328,14 +333,14 @@ icon: shield --- -## الأسرار (معقمات) +## الأسرار (معقّمات) -توقيف الوكلاء من تسريب بيانات الاعتماد في سياقهم أو مخرجاتهم. تعمل سياسات المعقم على أحداث **PostToolUse**. عندما يقوم Claude بتشغيل أمر Bash أو قراءة ملف أو استدعاء أي أداة، تفحص هذه السياسات المخرجات قبل إرجاعها إلى Claude. إذا تم اكتشاف نمط سري، تُرجع السياسة قرار deny الذي يمنع المخرجات من إعادتها. +منع الوكلاء من تسرب بيانات الاعتماد إلى سياقهم أو مخرجاتهم. تعمل سياسات المعقّم على أحداث **PostToolUse**. عندما يشغّل Claude أمر Bash، أو يقرأ ملف، أو يستدعي أي أداة، تفحص هذه السياسات المخرجات قبل إرجاعها إلى Claude. إذا تم كشف نمط سري، تعود السياسة برار الرفض الذي يمنع إرجاع المخرجات. ### `sanitize-jwt` **الحدث:** PostToolUse (جميع الأدوات) -**الافتراضي:** يخفي رموز JWT (ثلاث قطع base64url مفصولة بـ `.`). +**الافتراضي:** يزيل رموز JWT (ثلاثة أجزاء base64url مفصولة بـ `.`). لا توجد معاملات. @@ -344,13 +349,13 @@ icon: shield ### `sanitize-api-keys` **الحدث:** PostToolUse (جميع الأدوات) -**الافتراضي:** يخفي تنسيقات مفاتيح API الشائعة: Anthropic (`sk-ant-`)، OpenAI (`sk-`)، GitHub PATs (`ghp_`)، مفاتيح الوصول AWS (`AKIA`)، مفاتيح Stripe (`sk_live_`، `sk_test_`)، ومفاتيح Google API (`AIza`). +**الافتراضي:** يزيل تنسيقات مفاتيح API الشائعة: Anthropic (`sk-ant-`)، OpenAI (`sk-`)، GitHub PATs (`ghp_`)، مفاتيح AWS (`AKIA`)، مفاتيح Stripe (`sk_live_`, `sk_test_`)، ومفاتيح Google API (`AIza`). **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | أنماط regex إضافية تعامل كأسرار. | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | أنماط regex إضافية لتعاملها كأسرار. | **مثال:** @@ -359,8 +364,8 @@ icon: shield "policyParams": { "sanitize-api-keys": { "additionalPatterns": [ - { "regex": "myco_[A-Za-z0-9]{32}", "label": "مفتاح API داخلي من MyCo" }, - { "regex": "pat_[0-9a-f]{40}", "label": "PAT داخلي" } + { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" }, + { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" } ] } } @@ -372,7 +377,7 @@ icon: shield ### `sanitize-connection-strings` **الحدث:** PostToolUse (جميع الأدوات) -**الافتراضي:** يخفي سلاسل اتصال قاعدة البيانات التي تحتوي على بيانات اعتماد مدمجة (مثل `postgresql://user:password@host/db`). +**الافتراضي:** يزيل سلاسل اتصال قاعدة البيانات التي تحتوي على بيانات اعتماد مضمنة (مثل `postgresql://user:password@host/db`). لا توجد معاملات. @@ -381,7 +386,7 @@ icon: shield ### `sanitize-private-key-content` **الحدث:** PostToolUse (جميع الأدوات) -**الافتراضي:** يخفي كتل PEM (`-----BEGIN PRIVATE KEY-----`، `-----BEGIN RSA PRIVATE KEY-----`، إلخ). +**الافتراضي:** يزيل كتل PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`، إلخ). لا توجد معاملات. @@ -390,7 +395,7 @@ icon: shield ### `sanitize-bearer-tokens` **الحدث:** PostToolUse (جميع الأدوات) -**الافتراضي:** يخفي رؤوس `Authorization: Bearer ` حيث يكون الرمز 20 أو أكثر من الأحرف. +**الافتراضي:** يزيل رؤوس `Authorization: Bearer ` حيث يكون الرمز 20 حرفاً أو أكثر. لا توجد معاملات. @@ -398,14 +403,14 @@ icon: shield ## البيئة -حماية إعدادات البيئة الحساسة من قراءتها أو كشفها من قبل الوكلاء. +حماية إعدادات البيئة الحساسة من القراءة أو الكشف بواسطة الوكلاء. ### `block-env-files` **الحدث:** PreToolUse (Bash, Read) -**الافتراضي:** ينكر قراءة ملفات `.env` عبر `cat .env`، استدعاءات أداة Read مع `.env` كمسار الملف، إلخ. +**الافتراضي:** ينكر قراءة ملفات `.env` عبر `cat .env`، استدعاءات أداة Read بـ `.env` كمسار ملف، إلخ. -لا يحجب `.envrc` أو ملفات بيئية أخرى — فقط الملفات المسماة بدقة `.env`. +لا يمنع `.envrc` أو ملفات بيئية أخرى — فقط الملفات المسماة بالضبط `.env`. لا توجد معاملات. @@ -420,18 +425,18 @@ icon: shield --- -## الوصول للملفات +## الوصول إلى الملفات -إبقاء الوكلاء يعملون داخل حدود المشروع وبعيدًا عن الملفات الحساسة. +إبقاء الوكلاء يعملون داخل حدود المشروع وبعيداً عن الملفات الحساسة. ### `block-read-outside-cwd` **الحدث:** PreToolUse (Read, Bash) -**الافتراضي:** ينكر قراءة الملفات خارج جذر المشروع. الحد هو `CLAUDE_PROJECT_DIR` (يتم تعيينه مرة واحدة في كل جلسة بواسطة Claude Code)، مع رجوع إلى الدليل الحالي للجلسة عندما لا يتم تعيين هذا المتغير. يعني استخدام جذر المشروع بدلاً من `cwd` المباشر أن الحد يبقى مستقرًا حتى بعد أن يقوم Claude بـ `cd` إلى دليل فرعي. +**الافتراضي:** ينكر قراءة الملفات خارج جذر المشروع. الحد هو `CLAUDE_PROJECT_DIR` (يُعيّن مرة واحدة لكل جلسة بواسطة Claude Code)، مع تراجع إلى مجلد العمل الحالي للجلسة عندما يكون المتغير غير مُعيّن. استخدام جذر المشروع بدلاً من `cwd` المباشر يعني أن الحد يبقى ثابتاً حتى بعد أن يقوم Claude بـ `cd` إلى مجلد فرعي. **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| | `allowPaths` | `string[]` | `[]` | بادئات المسارات المطلقة المسموحة حتى لو كانت خارج جذر المشروع. | @@ -452,13 +457,13 @@ icon: shield ### `block-secrets-write` **الحدث:** PreToolUse (Write, Edit) -**الافتراضي:** ينكر الكتابة إلى الملفات المستخدمة عادة للمفاتيح الخاصة والشهادات: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**الافتراضي:** ينكر الكتابة إلى الملفات المستخدمة بشكل شائع للمفاتيح الخاصة والشهادات: `id_rsa`، `id_ed25519`، `*.key`، `*.pem`، `*.p12`، `*.pfx`. **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | أنماط اسم ملف إضافية (نمط glob) للحجب. | +| `additionalPatterns` | `string[]` | `[]` | أنماط أسماء ملفات إضافية (نمط glob) لمنعها. | **مثال:** @@ -476,7 +481,7 @@ icon: shield ## Git -منع الدفع العرضي والدفع القسري وأخطاء الفروع التي يصعب التراجع عنها. +منع الدفع العرضي والدفع القسري وأخطاء الفرع التي يصعب التراجع عنها. ### `block-push-master` @@ -485,7 +490,7 @@ icon: shield **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| | `protectedBranches` | `string[]` | `["main", "master"]` | أسماء الفروع التي لا يمكن الدفع إليها مباشرة. | @@ -502,7 +507,7 @@ icon: shield ``` -للسماح بالدفع إلى جميع الفروع (تعطيل هذه السياسة بشكل فعال دون إزالتها من `enabledPolicies`)، اضبط `protectedBranches: []`. +للسماح بالدفع إلى جميع الفروع (تعطيل هذه السياسة فعلياً دون إزالتها من `enabledPolicies`)، عيّن `protectedBranches: []`. --- @@ -510,13 +515,13 @@ icon: shield ### `block-work-on-main` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر `git commit`, `git merge`, `git rebase`, و `git cherry-pick` أثناء وجود شجرة العمل على `main` أو `master`. لا يتأثر إنشاء الفروع والتبديل بينها (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`). +**الافتراضي:** ينكر `git commit`، `git merge`، `git rebase`، و `git cherry-pick` بينما تكون شجرة العمل على `main` أو `master`. إنشاء الفروع والتبديل بينها (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) لا تتأثر. **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | أسماء الفروع المحمية التي يتم رفض commit/merge/rebase/cherry-pick عليها. | +| `protectedBranches` | `string[]` | `["main", "master"]` | أسماء الفروع التي يتم فيها رفض commit/merge/rebase/cherry-pick. | --- @@ -525,13 +530,13 @@ icon: shield **الحدث:** PreToolUse (Bash) **الافتراضي:** ينكر `git push --force` و `git push -f`. -لا توجد معاملات محددة للسياسة. استخدم [`hint`](/ar/configuration#hint-cross-cutting) متعدد الأغراض لاقتراح بدائل: +لا توجد معاملات خاصة بالسياسة. استخدم [`hint`](/ar/configuration#hint-cross-cutting) عبر جميع المشاريع لاقتراح بدائل: ```json { "policyParams": { "block-force-push": { - "hint": "أنشئ فرع جديد من HEAD الحالي (مثل `git checkout -b `) وادفع ذلك بدلاً من ذلك." + "hint": "أنشئ فرعاً جديداً من HEAD الحالي لديك (مثل `git checkout -b `) وادفعه بدلاً من ذلك." } } } @@ -542,7 +547,7 @@ icon: shield ### `warn-git-amend` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينصح Claude بالمتابعة بحذر عند تشغيل `git commit --amend`. لا يحجب الأمر. +**الافتراضي:** يعلّم Claude بأن يتابع بحذر عند تشغيل `git commit --amend`. لا يمنع الأمر. لا توجد معاملات. @@ -551,7 +556,7 @@ icon: shield ### `warn-git-stash-drop` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينصح Claude بتأكيد قبل تشغيل `git stash drop`. لا يحجب الأمر. +**الافتراضي:** يعلّم Claude بأن يؤكد قبل تشغيل `git stash drop`. لا يمنع الأمر. لا توجد معاملات. @@ -560,7 +565,7 @@ icon: shield ### `warn-all-files-staged` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينصح Claude بمراجعة ما يقوم بتجهيزه عند تشغيل `git add -A` أو `git add .`. لا يحجب الأمر. +**الافتراضي:** يعلّم Claude بأن يراجع ما يقوم بتحضيره عند تشغيل `git add -A` أو `git add .`. لا يمنع الأمر. لا توجد معاملات. @@ -568,12 +573,12 @@ icon: shield ## قاعدة البيانات -التقط العمليات SQL التدميرية قبل تنفيذها على قاعدة البيانات الخاصة بك. +اكتشف العمليات SQL التدميرية قبل تنفيذها ضد قاعدة البيانات الخاصة بك. ### `warn-destructive-sql` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينصح Claude بتأكيد قبل تشغيل SQL تحتوي على `DROP TABLE`, `DROP DATABASE`, أو `DELETE` بدون جملة `WHERE`. +**الافتراضي:** يعلّم Claude بأن يؤكد قبل تشغيل SQL يحتوي على `DROP TABLE`, `DROP DATABASE`, أو `DELETE` بدون جملة `WHERE`. لا توجد معاملات. @@ -582,26 +587,26 @@ icon: shield ### `warn-schema-alteration` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينصح Claude بتأكيد قبل تشغيل جمل `ALTER TABLE`. +**الافتراضي:** يعلّم Claude بأن يؤكد قبل تشغيل بيانات `ALTER TABLE`. لا توجد معاملات. --- -## التحذيرات +## تحذيرات -إعطاء الوكلاء سياق إضافي قبل العمليات المحتملة والمحفوفة بالمخاطر ولكن غير مدمرة. +إعطاء الوكلاء سياقاً إضافياً قبل العمليات المحتملة الخطورة لكن غير التدميرية. ### `warn-large-file-write` **الحدث:** PreToolUse (Write) -**الافتراضي:** ينصح Claude بتأكيد قبل كتابة ملفات أكبر من 1024 كيلوبايت. +**الافتراضي:** يعلّم Claude بأن يؤكد قبل كتابة ملفات أكبر من 1024 كيلوبايت. **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | حد حجم الملف بالكيلوبايت الذي يتم فوقه إصدار تحذير. | +| `thresholdKb` | `number` | `1024` | عتبة حجم الملف بالكيلوبايت التي يُصدر فوقها تحذير. | **مثال:** @@ -616,7 +621,7 @@ icon: shield ``` -يفرض معالج الخطاف حد أقصى لـ stdin قدره 1 ميجابايت على الحمولات. لاختبار هذه السياسة بمحتوى صغير، اضبط `thresholdKb` على قيمة أقل بكثير من 1024. +معالج Hook يفرض حد أقصى 1 MB لـ stdin في حمولات الطلبات. لاختبار هذه السياسة بمحتوى صغير، عيّن `thresholdKb` إلى قيمة أقل بكثير من 1024. --- @@ -624,7 +629,7 @@ icon: shield ### `warn-package-publish` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينصح Claude بتأكيد قبل تشغيل `npm publish`. +**الافتراضي:** يعلّم Claude بأن يؤكد قبل تشغيل `npm publish`. لا توجد معاملات. @@ -633,7 +638,7 @@ icon: shield ### `warn-background-process` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينصح Claude بالحذر عند إطلاق العمليات في الخلفية عبر `nohup`, `&`, `disown`, أو `screen`. +**الافتراضي:** يعلّم Claude بأن يكون حذراً عند إطلاق عمليات الخلفية عبر `nohup`, `&`, `disown`, أو `screen`. لا توجد معاملات. @@ -642,7 +647,7 @@ icon: shield ### `warn-global-package-install` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينصح Claude بتأكيد قبل تشغيل `npm install -g`, `yarn global add`, أو `pip install` بدون بيئة افتراضية. +**الافتراضي:** يعلّم Claude بأن يؤكد قبل تشغيل `npm install -g`, `yarn global add`, أو `pip install` بدون بيئة افتراضية. لا توجد معاملات. @@ -650,23 +655,23 @@ icon: shield ## مديري الحزم -فرض مدير الحزم الذي يُسمح للوكيل باستخدامه. +فرض أي مديري حزم يُسمح للوكيل باستخدامهم. ### `prefer-package-manager` **الحدث:** PreToolUse (Bash) -**الافتراضي:** معطّل. عند التفعيل، يحجب أي أمر مدير حزم ليس في قائمة `allowed` وينصح Claude بإعادة كتابة الأمر باستخدام مدير مسموح. +**الافتراضي:** معطّل. عند التفعيل، يمنع أي أمر مدير حزم ليس في قائمة `allowed` ويخبر Claude بأن يعيد كتابة الأمر باستخدام مدير مسموح. -يكتشف: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. +الكشف عن: pip، pip3، python -m pip، npm، npx، yarn، pnpm، pnpx، bun، bunx، uv، poetry، pipenv، conda، cargo. -| المعامل | النوع | الافتراضي | الوصف | +| معامل | النوع | الافتراضي | الوصف | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | أسماء مديري الحزم المسموحة. يتم حجب أي مدير مكتشف ليس في هذه القائمة. عند كونها فارغة، السياسة بلا تأثير. | -| `blocked` | string[] | `[]` | أسماء مديري إضافية للحجب بخلاف القائمة المدمجة (مثل `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | أسماء مديري الحزم المسموحة. أي مدير مكتشف ليس في هذه القائمة يتم منعه. عندما تكون فارغة، السياسة بلا تأثير. | +| `blocked` | string[] | `[]` | أسماء مديري حزم إضافية لمنعها بخلاف القائمة المدمجة (مثل `['pdm', 'pipx']`). | -تغطي القائمة المحجوبة المدمجة: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. استخدم `blocked` لإضافة مديرين ليسوا في هذه القائمة. +قائمة الحظر المدمجة تغطي: pip، pip3، npm، npx، yarn، pnpm، pnpx، bun، bunx، uv، poetry، pipenv، conda، cargo. استخدم `blocked` لإضافة مديري حزم ليسوا في هذه القائمة. -**إعداد مثالي:** +**مثال التكوين:** ```json { @@ -680,7 +685,7 @@ icon: shield } ``` -مع هذا الإعداد، `pip install flask` و `pdm install flask` كلاهما مرفوض برسالة تنصح Claude باستخدام `uv` أو `bun` بدلاً من ذلك. أوامر مثل `uv pip install flask` مسموحة لأن `uv` في القائمة البيضاء ويتم فحصه أولاً. +مع هذا التكوين، يتم رفض كل من `pip install flask` و `pdm install flask` برسالة تخبر Claude بأن يستخدم `uv` أو `bun` بدلاً من ذلك. أوامر مثل `uv pip install flask` مسموحة لأن `uv` موجود في قائمة التسامح ويتم التحقق منه أولاً. --- @@ -691,7 +696,7 @@ icon: shield ### `warn-repeated-tool-calls` **الحدث:** PreToolUse (جميع الأدوات) -**الافتراضي:** ينصح Claude بإعادة النظر عند استدعاء نفس الأداة 3 مرات أو أكثر بمعاملات متطابقة — علامة شائعة على أن الوكيل عالق في حلقة. +**الافتراضي:** يعلّم Claude بأن يعيد النظر عندما يتم استدعاء نفس الأداة 3 مرات أو أكثر بمعاملات متطابقة — علامة شائعة لأن الوكيل عالق في حلقة. لا توجد معاملات. @@ -699,40 +704,40 @@ icon: shield ## سير العمل -فرض سير عمل منضبط لنهاية الجلسة. تعمل هذه السياسات على حدث **Stop** وترفض الوكيل من التوقف حتى يتم استيفاء كل شرط. تتبع سلسلة تبعيات طبيعية: commit → push → PR → CI. إذا رفضت سياسة ما، يتم تخطي السياسات اللاحقة في السلسلة (الرفض يقطع المسار). +فرض سير عمل منضبط في نهاية الجلسة. تعمل هذه السياسات على حدث **Stop** وترفض الوكيل من التوقف حتى يتم استيفاء كل شرط. تتبع سلسلة تبعية طبيعية: التزام → دفع → طلب دمج → CI. إذا رفضت سياسة، يتم تخطي السياسات اللاحقة في السلسلة (الرفض يقصر الدائرة). -جميع سياسات سير العمل **fail-open**: إذا لم تتوفر الأداة المطلوبة (مثل `gh` غير مثبت، لا توجد نقطة طرفية git)، تسمح السياسة برسالة معلوماتية توضح سبب تخطي الفحص. +جميع سياسات سير العمل **تفشل مفتوحة**: إذا لم تكن الأداة المطلوبة متوفرة (مثل `gh` غير مثبتة، بدون جهاز تحكم git بعيد)، تسمح السياسة برسالة معلوماتية تشرح سبب تخطي الفحص. -### دلالات Stop حسب CLI +### دلالات Stop لكل CLI -يبدو فرض Stop مختلفًا قليلاً عبر سبعة CLIs مدعومة لأن كل واحد يفضح عقد خطاف نقطة نهاية مختلفة. **النتيجة** هي نفسها — الوكيل لا يتمكن من الإفلات من التوقف بينما بوابة سير عمل فاشلة — لكن **الآليات** تختلف. يلخص الجدول أدناه؛ فقط Pi لديها غرابة مرئية للمستخدم تستحق الفهم قبل تفعيل سياسة `require-*-before-stop`. +يبدو إنفاذ Stop مختلفاً قليلاً عبر سبعة CLI مدعومة لأن كل واحد يعرّض عقد hook مختلفاً. النتيجة **متطابقة** — الوكيل لا يهرب من التوقف بينما تفشل بوابة سير العمل — لكن **الميكانيكا** تختلف. يلخص الجدول أدناه؛ فقط Pi لديه خصوصية واضحة للمستخدم تستحق الفهم قبل تفعيل سياسة `require-*-before-stop`. -| CLI | عندما تعمل البوابة | ما تراه | +| CLI | متى تعمل البوابة | ما تراه | |---|---|---| -| Claude Code | حلقة الوكيل نفسها، فورًا | يستمر Claude في العمل — يصحح المشكلة، ثم يحاول الإنهاء مرة أخرى. لا يوجد انقطاع مرئي لك. | -| Codex | حلقة الوكيل نفسها، فورًا | نفس Claude. | -| GitHub Copilot CLI | حلقة الوكيل نفسها، فورًا | نفس Claude (يستخدم قناة إعادة محاولة `{decision:"block", reason}` الخاصة بـ Copilot — تم التحقق من الناحية التجريبية ضد Copilot CLI 1.0.41). | -| Cursor Agent | حلقة الوكيل نفسها، فورًا | نفس Claude (يستخدم قناة `{followup_message}` الخاصة بـ Cursor — مع حد أقصى `loop_limit`، الافتراضي 5 إعادات محاولة). | -| Gemini CLI | حلقة الوكيل نفسها، فورًا | نفس Claude (يستخدم قناة `{decision:"block", reason}` الخاصة بـ Gemini على `AfterAgent`). | -| OpenCode | حلقة الوكيل نفسها، فورًا | نفس Claude (يستخدم استدعاء SDK `client.session.prompt(...)` الخاص بـ OpenCode الموجهة عبر `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **الدور التالي للمستخدم** | **Pi يتوقف بشكل مرئي** عندما تعمل البوابة — تخرج حلقة الوكيل الخاصة به وتعود إلى الطلب. تعمل البوابة بعد ذلك في المرة التالية التي تقدم فيها موجه: يضيف failproofai توجيه `MANDATORY ACTION REQUIRED` إلى موجه نظام هذا الدور، ينصح LLM بإكمال خطوة سير العمل (التزام، الدفع، إلخ) قبل فعل ما طلبته. | +| Claude Code | نفس حلقة الوكيل، فوراً | يستمر Claude في العمل — يصحح المشكلة، ثم يحاول الإنهاء مرة أخرى. لا توقف ظاهر لك. | +| Codex | نفس حلقة الوكيل، فوراً | نفس Claude. | +| GitHub Copilot CLI | نفس حلقة الوكيل، فوراً | نفس Claude (يستخدم قناة إعادة محاولة `{decision:"block", reason}` الخاصة بـ Copilot — تم التحقق منها تجريبياً ضد Copilot CLI 1.0.41). | +| Cursor Agent | نفس حلقة الوكيل، فوراً | نفس Claude (يستخدم قناة `{followup_message}` الخاصة بـ Cursor — محدودة بـ `loop_limit`، افتراضي 5 إعادة محاولات). | +| Gemini CLI | نفس حلقة الوكيل، فوراً | نفس Claude (يستخدم قناة `{decision:"block", reason}` الخاصة بـ Gemini على `AfterAgent`). | +| OpenCode | نفس حلقة الوكيل، فوراً | نفس Claude (يستخدم استدعاء SDK `client.session.prompt(...)` الخاص بـ OpenCode الموجه عبر `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **دور المستخدم التالي** | **يتوقف Pi بشكل واضح** عندما تعمل البوابة — تنهي حلقة الوكيل الخاصة به وتعودين إلى الموجه. تعمل البوابة بعد ذلك في المرة القادمة التي تقدّمين فيها موجهاً: يضيف failproofai توجيهاً `MANDATORY ACTION REQUIRED` إلى موجه نظام هذا الدور، يعلّم LLM بإكمال خطوة سير العمل (التزام، دفع، إلخ) قبل فعل ما طلبتِ. | -**قيد Pi.** حدث `AgentEndEvent` الخاص بـ Pi (المعادل الأعلى مستوى لخطاف `Stop` الخاص بـ Claude) ليس له نوع نتيجة — بحلول الوقت الذي يعمل فيه، كانت حلقة وكيل Pi قد خرجت بالفعل. لا يمكن فرض Pi على إعادة المحاولة في نفس الحلقة بالطريقة التي يمكن بها مع Claude / Copilot / Cursor / Gemini / OpenCode. ينقل failproofai البوابة إلى حدث `before_agent_start` الخاص بـ Pi (الذي يعمل بعد الموجه التالي للمستخدم) بحيث يفرض فحص سير العمل، فقط على الدور التالي بدلاً من الدور الحالي. +**قيد Pi.** `AgentEndEvent` الخاص بـ Pi (المعادل الأعلى لـ hook `Stop` الخاص بـ Claude) لا يملك نوع Result — بحلول الوقت الذي يعمل فيه، تكون حلقة الوكيل الخاصة بـ Pi قد خرجت بالفعل. لا يمكن إجبار Pi على إعادة محاولة نفس الحلقة بالطريقة التي يمكن بها Claude / Copilot / Cursor / Gemini / OpenCode. ينقل failproofai البوابة إلى حدث `before_agent_start` الخاص بـ Pi (الذي يعمل بعد الموجه التالي للمستخدم) لذا يبقى فحص سير العمل مفروضاً، فقط على الدور التالي بدلاً من الحالي. -**ما يعنيه هذا عمليًا:** +**ما يعنيه هذا عملياً:** -- بعد توقف Pi، يتم التقاط سبب الرفض في الذاكرة مفتاح بواسطة معرف جلسة Pi. الموجه التالي الذي تقدمه بالضبط في نفس عملية Pi يستنزفه: يرى LLM التوجيه `MANDATORY ACTION REQUIRED` في أعلى موجه نظامه، يلتزم (أو يدفع / يفتح PR / ينتظر CI)، وفقط بعد ذلك يستمر مع طلبك. سبب الرفض الملتقط هو لقطة واحدة — بمجرد استنزافه، تكون البوابة واضحة. -- البوابة محدودة بعمر عملية Pi. إذا قمت بـ `Ctrl+C` Pi أو خرجت بين الأدوار، يتم إسقاط الإدخال في الذاكرة جنبًا إلى جنب مع العملية والبوابة ضائعة. Claude و Copilot و Cursor و Gemini و OpenCode لها نفس الحد (قتل الوكيل والبوابة ضائعة) — Pi فقط يجعلها أكثر وضوحًا لأن الوكيل يخرج بشكل مرئي قبل عمل البوابة. -- يتم أيضًا مسح رفض معلق على `session_shutdown` لأي سبب (`new` / `resume` / `fork` / `quit`)، بحيث لا يمكن لبوابة قديمة من جلسة سابقة أن تسرب إلى جلسة جديدة بدأت في نفس عملية Pi. +- بعد توقف Pi، يتم التقاط رار الرفض في الذاكرة بمفتاح معرف جلسة Pi. الموجه التالي الذي تقدّمينه بالضبط في نفس عملية Pi يصرفه: يرى LLM توجيه `MANDATORY ACTION REQUIRED` في أعلى موجه النظام الخاص به، يلتزم (أو يدفع / يفتح PR / ينتظر CI)، وفقط بعد ذلك يستمر مع طلبك. رار الرفض المقبوض مرة واحدة — بمجرد صرفه، تكون البوابة واضحة. +- البوابة محدودة بعمر عملية Pi. إذا قمتِ بـ `Ctrl+C` Pi أو أغلقتِ بين الأدوار، يتم حذف الإدخال في الذاكرة مع العملية والبوابة تُفتقد. Claude و Copilot و Cursor و Gemini و OpenCode لديها نفس الحد (اقتل الوكيل والبوابة تُفتقد) — Pi فقط يجعله أكثر وضوحاً لأن الوكيل يخرج بشكل واضح قبل عمل البوابة. +- رار الرفض المعلق يتم مسحه أيضاً على `session_shutdown` لأي سبب (`new` / `resume` / `fork` / `quit`)، لذا بوابة قديمة من جلسة سابقة لا تستطيع التسرب إلى جلسة جديدة بدأت في نفس عملية Pi. -إذا كنت تحتاج إلى إعادة محاولة نفس الحلقة على غرار Claude، قم بتشغيل سياسات `Stop` الخاصة بك ضمن أي من الستة CLIs المدعومة الأخرى. نحن نتابع Pi في المصدر الأعلى لنوع النتيجة المستقبلي على `AgentEndEvent` الذي سيسمح لنا بإغلاق هذه الفجوة. +إذا احتجتِ إلى إعادة محاولة نفس الحلقة بأسلوب Claude، قومي بتشغيل سياسات `Stop` الخاصة بك تحت أي من ستة CLI الأخرى المدعومة. نحن نتابع Pi في المنبع لنوع Result مستقبلي على `AgentEndEvent` الذي سيسمح لنا بإغلاق هذه الفجوة. ### `require-commit-before-stop` **الحدث:** Stop -**الافتراضي:** ينكر التوقف عندما يكون هناك تغييرات غير مرتكبة (ملفات معدلة أو مرحلة أو غير متتبعة). يُرجع رسالة معلوماتية عندما تكون دليل العمل نظيفًا. +**الافتراضي:** ينكر التوقف عندما يكون هناك تغييرات غير مرتكبة (ملفات معدلة أو مرحلة أو غير تتبع). يعيد رسالة معلوماتية عندما يكون مجلد العمل نظيفاً. لا توجد معاملات. @@ -741,13 +746,13 @@ icon: shield ### `require-push-before-stop` **الحدث:** Stop -**الافتراضي:** ينكر التوقف عندما يكون هناك عمليات التزام غير مدفوعة أو عندما لا يحتوي الفرع الحالي على فرع تتبع عن بعد. يقترح `git push -u` لإنشاء فرع تتبع إذا لزم الأمر. يفشل مفتوح إذا لم يتم تكوين أي عن بعد. +**الافتراضي:** ينكر التوقف عندما يكون هناك التزامات غير مدفوعة أو عندما لا يملك الفرع الحالي فرع تتبع بعيد. يقترح `git push -u` لإنشاء فرع تتبع إذا لزم الأمر. يفشل مفتوحاً إذا لم يكن هناك جهاز تحكم مكونة. **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | اسم العن بعد للدفع إليه. | +| `remote` | `string` | `"origin"` | اسم الجهاز البعيد الذي سيتم الدفع إليه. | **مثال:** @@ -766,14 +771,14 @@ icon: shield ### `require-pr-before-stop` **الحدث:** Stop -**الافتراضي:** ينكر التوقف عندما لا يوجد طلب سحب للفرع الحالي، أو عندما يكون طلب السحب الموجود مغلقًا دون دمج. ينصح Claude بإنشاء PR باستخدام `gh pr create`. عندما يتم **دمج** الطلب، تسمح السياسة (تم شحن العمل) والرسالة تلميح للتبديل خارج الفرع (`git checkout main && git pull`). +**الافتراضي:** ينكر التوقف عندما لا يكون هناك طلب دمج للفرع الحالي، أو عندما يكون طلب الدمج الموجود مغلقاً دون دمج. يعلّم Claude بإنشاء PR باستخدام `gh pr create`. عندما يكون PR **مدمجاً**، تسمح السياسة (تم شحن العمل) والرسالة تلمّح إلى التبديل عن الفرع (`git checkout main && git pull`). لا توجد معاملات. -تتطلب هذه السياسة [GitHub CLI](https://cli.github.com/) (`gh`) المثبتة والموثقة. -قم بتشغيل `gh auth login` مع رمز الوصول الشخصي الذي يحتوي على نطاق `repo` للقراءة -الوصول إلى طلبات السحب. إذا لم يتم تثبيت `gh` أو لم يتم التوثيق، تفشل السياسة مفتوحة وتُبلغ عن السبب إلى Claude. +تتطلب هذه السياسة [GitHub CLI](https://cli.github.com/) (`gh`) مثبتاً ومصادقاً. +قم بتشغيل `gh auth login` برمز الوصول الشخصي الذي يملك نطاق `repo` للوصول القراءة إلى +طلبات السحب. إذا لم يكن `gh` مثبتاً أو مصادقاً، تفشل السياسة مفتوحة وتبلّغ عن السبب إلى Claude. --- @@ -781,23 +786,23 @@ icon: shield ### `require-no-conflicts-before-stop` **الحدث:** Stop -**الافتراضي:** ينكر التوقف عندما لا يمكن دمج الفرع الحالي بشكل نظيف في فرع القاعدة. تتحقق السياسة أولاً من أنه يوجد `OPEN` PR على GitHub للفرع — بدون واحد، لا توجد هدف دمج لفرضها، لذا تقصر السياسة بأكملها على السماح. بمجرد تأكيد `OPEN` PR، يعمل مسحان مستقلان: +**الافتراضي:** ينكر التوقف عندما لا يمكن دمج الفرع الحالي بنظافة في فرع القاعدة. تؤكد السياسة أولاً أن هناك PR `OPEN` على GitHub للفرع — بدونها، لا يوجد هدف دمج للفرض، لذا تختصر السياسة بأكملها للسماح. عند تأكيد PR `OPEN`، يعمل مسحان مستقلان: -1. **محلي** — `git merge-tree --write-tree --name-only origin/ HEAD`. عند تضارب، تسمي رسالة الرفض الملفات المتضاربة حتى يعرف Claude بالضبط ما يجب حله. -2. **GitHub** — يعاد استخدام نتيجة `gh pr view --json mergeable,state` المحضرة بالفعل في الفحص المسبق. يمسك بتضاربات أن `origin/` محلي قديم قد يفتقده (مثل هبوط شخص ما في PR متضارب على `main` منذ آخر جلب). يرفض نتيجة `CONFLICTING`. نتيجة `UNKNOWN` ترفض أيضًا وتنصح Claude بالانتظار ~10 ثوان وإعادة الفحص قبل محاولة التوقف مرة أخرى — هذا يمنع النتائج السلبية الكاذبة بينما تعيد GitHub الحساب. +1. **محلي** — `git merge-tree --write-tree --name-only origin/ HEAD`. عند التضارب، تسمي رسالة الرفض الملفات المتضاربة حتى يعرف Claude بالضبط ما يجب حله. +2. **GitHub** — يعيد استخدام نتيجة `gh pr view --json mergeable,state` المجلوبة بالفعل في الفحص المسبق. يمسك التضاربات التي كانت `origin/` محلية قديمة ستفقدها (مثل الهبوط على PR متضارب على `main` منذ آخر جلب). نتيجة `CONFLICTING` ترفض. نتيجة `UNKNOWN` ترفض أيضاً وتعلّم Claude بالانتظار ~10 ثوان وإعادة الفحص قبل محاولة التوقف مرة أخرى — يمنع السلبيات الكاذبة بينما تعيد حساب GitHub. -يتخطى بالكامل (السماح) عند: `gh` غير مثبت، لا يوجد PR للفرع، حالة PR ليست `OPEN` (مثل `MERGED`, `CLOSED`)، أو `gh pr view` يُرجع مخرجات غير قابلة للتحليل. يفشل أيضًا مفتوح عند غياب `origin/` محليًا أو عدم وجود التزامات في الأمام من القاعدة — تلك التجاوزات من الطبقة 1 تستشير المدج المخزن في الذاكرة قبل السماح. +تخطيها بالكامل (سماح) عند: `gh` غير مثبت، لا يوجد PR للفرع، حالة PR ليست `OPEN` (مثل `MERGED`, `CLOSED`)، أو `gh pr view` يرجع مخرجات غير قابلة للتحليل. يفشل أيضاً مفتوحاً عند فقدان `origin/` محلياً أو عند عدم وجود التزامات تقدماً من القاعدة — تلك أمراض مستوى الطبقة 1 تستشير قابلية دمج PR المخزنة مؤقتاً قبل السماح. **المعاملات:** -| المعامل | النوع | الافتراضي | الوصف | +| Param | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | فرع القاعدة للفحص من أجل التضاربات. | +| `baseBranch` | `string` | `"main"` | فرع القاعدة للفحص للتضاربات ضده. | -GitHub CLI (`gh`) مطلوب لهذه السياسة. تستخدم السياسة `gh pr view` لتأكيد وجود PR `OPEN` -قبل تشغيل أي مسح تضارب — بدون `gh`، السياسة تقصر على السماح. قم بتشغيل `gh auth login` مع رمز وصول شخصي له -نطاق `repo` للقراءة للوصول إلى طلبات السحب. +يُطلب GitHub CLI (`gh`) لهذه السياسة. تستخدم السياسة `gh pr view` لتأكيد +وجود PR `OPEN` قبل تشغيل أي مسح تضارب — بدون `gh`، تختصر السياسة للسماح. قم بتشغيل `gh auth login` برمز وصول شخصي يملك +نطاق `repo` للوصول القراءة إلى طلبات السحب. --- @@ -805,14 +810,14 @@ GitHub CLI (`gh`) مطلوب لهذه السياسة. تستخدم السياس ### `require-ci-green-before-stop` **الحدث:** Stop -**الافتراضي:** ينكر التوقف عندما تكون فحوصات CI فاشلة أو تعمل بعد على الفرع الحالي. يفحص كل من سير عمل GitHub Actions والفحوصات من جهات خارجية (مثل CodeRabbit, SonarCloud, Codecov). يعامل `skipped`, `cancelled`, و `neutral` الخلاصات كعدم فشل (الأخير يغطي مثل تنبيهات Socket Security على PRs المساهم الخارجي، حيث يبلغ التطبيق عن محايد بدلاً من النجاح/الفشل). يُرجع رسالة معلوماتية عند نجاح جميع الفحوصات. +**الافتراضي:** ينكر التوقف عندما تكون فحوصات CI فاشلة أو لا تزال تعمل على الفرع الحالي. يفحص كل من تشغيلات سير عمل GitHub Actions وفحوصات الروبوت من طرف ثالث (مثل CodeRabbit، SonarCloud، Codecov). يعتبر `skipped`, `cancelled`, و `neutral` الخلاصات غير فاشلة (الأخير يغطي مثل تنبيهات Socket Security على PRs المساهمين الخارجيين، حيث يبلّغ التطبيق عن neutral بدلاً من النجاح/الفشل بقصد). يعيد رسالة معلوماتية عندما تمر جميع الفحوصات. لا توجد معاملات. -تتطلب هذه السياسة [GitHub CLI](https://cli.github.com/) (`gh`) المثبتة والموثقة. -قم بتشغيل `gh auth login` مع رمز وصول شخصي له نطاق `repo` للقراءة -الوصول إلى سير عمل الإجراءات و Checks API. إذا لم يتم تثبيت `gh` أو لم يتم التوثيق، تفشل السياسة مفتوحة وتُبلغ عن السبب إلى Claude. +تتطلب هذه السياسة [GitHub CLI](https://cli.github.com/) (`gh`) مثبتاً ومصادقاً. +قم بتشغيل `gh auth login` برمز وصول شخصي يملك نطاق `repo` للوصول القراءة إلى +تشغيلات سير عمل Actions وAPI الفحوصات. إذا لم يكن `gh` مثبتاً أو مصادقاً، تفشل السياسة مفتوحة وتبلّغ عن السبب إلى Claude. --- @@ -821,7 +826,7 @@ GitHub CLI (`gh`) مطلوب لهذه السياسة. تستخدم السياس ## تعطيل السياسات الفردية -أزل سياسة محددة من `enabledPolicies` في إعدادك، أو قم بتبديلها في علامة التبويب Policies في لوحة التحكم. +أزل سياسة محددة من `enabledPolicies` في ملف التكوين الخاص بك، أو قم بتبديلها في تبويب السياسات بلوحة البيانات. ```json { @@ -832,4 +837,4 @@ GitHub CLI (`gh`) مطلوب لهذه السياسة. تستخدم السياس } ``` -السياسات غير المدرجة في `enabledPolicies` لا تعمل، حتى إذا كانت إدخالات `policyParams` موجودة لها. \ No newline at end of file +السياسات غير المدرجة في `enabledPolicies` لا تعمل، حتى لو كانت هناك إدخالات `policyParams` موجودة لها. \ No newline at end of file diff --git a/docs/ar/cli/audit.mdx b/docs/ar/cli/audit.mdx index 7a338c22..fd1384a9 100644 --- a/docs/ar/cli/audit.mdx +++ b/docs/ar/cli/audit.mdx @@ -1,23 +1,22 @@ --- ---- -title: تدقيق الجلسات السابقة (نسخة تجريبية) -description: "عد عدد مرات قيام الوكيل بأشياء مهدرة أو محفوفة بالمخاطر عبر النصوص السابقة" +title: تدقيق الجلسات السابقة (تجريبي) +description: "عد عدد المرات التي فعل فيها الوكيل أشياء مهدرة أو محفوفة بالمخاطر عبر النصوص السابقة" --- - **ميزة تجريبية.** يتم شحن التدقيق كنسخة تجريبية أثناء جمعنا للملاحظات المبكرة. - قد يتغير كتالوج الكاشف وتنسيق التقرير قبل الإصدار المستقر التالي. يرجى فتح مشكلة إذا بدا شيء ما غير صحيح. + **ميزة تجريبية.** يشحن التدقيق كإصدار تجريبي بينما نجمع التعليقات المبكرة. + قد يتغير كتالوج الكاشف وتنسيق التقرير قبل الإصدار المستقر التالي. يرجى فتح مشكلة إذا بدا شيء غير صحيح. -يعيد التدقيق تشغيل نصوص وكيل CLI السابقة لديك من خلال محرك سياسة failproofai ويعرض تقرير بصري قابل للمشاركة على **صفحة لوحة المعلومات `/audit`** — نمط وكيلك، درجة من 0 إلى 100، وبالضبط أي السياسات كان يمكن أن تحتفظ بما. +يعيد التدقيق تشغيل نصوص عامل CLI السابقة عبر محرك السياسة الخاص بـ failproofai ويعرض تقريراً مشاركاً وبصرياً على **صفحة لوحة التحكم `/audit`** — نموذج الوكيل الأصلي، نقطة من 0–100، وبالضبط أي سياسات كان يمكن أن تلتقط ماذا. -## تشغيله +## قم بتشغيله -ثلاث طرق للدخول — كلها تؤدي إلى نفس تقرير `/audit`. +ثلاث طرق للدخول — جميعها تصل إلى نفس تقرير `/audit`. -```bash npx (no install) +```bash npx (بدون تثبيت) npx -y failproofai audit ``` @@ -25,7 +24,7 @@ npx -y failproofai audit failproofai audit ``` -```bash failproofai (dashboard) +```bash failproofai (لوحة التحكم) failproofai ``` @@ -33,56 +32,56 @@ failproofai - يجلب `npx -y failproofai audit` failproofai، ويشغل الفحص، ويفتح لوحة المعلومات لك — بدون تثبيت أولاً. + `npx -y failproofai audit` يجلب failproofai، ويقوم بتشغيل الفحص، ويفتح لوحة التحكم لك — لا حاجة لتثبيت شيء مسبقاً. - يشغل `failproofai audit` الفحص في المحطة الطرفية لديك، ثم يفتح `localhost:8020/audit` تلقائياً عند الانتهاء. + `failproofai audit` يقوم بتشغيل الفحص في محطتك، ثم يفتح `localhost:8020/audit` تلقائياً عند انتهائه. - - شغّل `failproofai` وانقر على **Audit** في شريط التنقل (بين Policies و Projects)، أو افتح `/audit` مباشرة. + + قم بتشغيل `failproofai` وانقر على **Audit** في شريط التنقل (بين Policies و Projects)، أو افتح `/audit` مباشرة. - شغّل `failproofai audit -h` (أو `--help`) لرؤية الاستخدام. يعمل التدقيق **بالكامل في وضع عدم الاتصال** — لا حساب أو شبكة مطلوبة — ولوحة المعلومات تستمر في الخدمة حتى تيقفها بـ `Ctrl+C`. + قم بتشغيل `failproofai audit -h` (أو `--help`) لرؤية الاستخدام. يعمل التدقيق **بالكامل بدون اتصال** — لا تحتاج إلى حساب أو شبكة — ولوحة التحكم تستمر في الخدمة حتى توقفها بـ `Ctrl+C`. -تفحص لوحة المعلومات نصوص وكيل CLI السابقة على هذا الجهاز (Claude Code وCodex وCopilot وCursor وOpenCode وPi وGemini) وتبلغ عن عدد مرات قيام الوكيل بأشياء بنيت failproofai لإيقافها — فحوصات متغيرات البيئة والدفع القسري والبادئات الزائدة `cd ` وحلقات sleep-polling وإعادة قراءة الملفات المحررة للتو والمزيد. +تقوم لوحة التحكم بفحص نصوص وكيل CLI السابقة على هذا الجهاز (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) وتقرر كم مرة فعل الوكيل أشياء تم بناء failproofai لإيقافها — فحوصات متغيرات البيئة، الدفعات القسرية، البادئات `cd ` الزائدة، حلقات الانتظار بالنوم، إعادة قراءة الملفات التي تم تحريرها للتو، وغير ذلك. -لكل نص، يتم إعادة تشغيل كل حدث استخدام أداة من خلال 39 سياسة مدمجة **و** من خلال 8 كاشفات خاصة بالتدقيق فقط تحتفظ بالأنماط غير المغطاة حتى الآن بسياسات وقت التشغيل. يتم تجميع الأعداد لكل سياسة / كاشف عبر جميع الجلسات. +لكل نص، يتم إعادة تشغيل كل حدث استخدام أداة عبر السياسات المدمجة البالغ عددها 39 **و** عبر 8 كواشف خاصة بالتدقيق فقط التي تلتقط الأنماط التي لم تغطها السياسات الوقتية بعد. يتم تجميع الأعداد لكل سياسة / كاشف عبر جميع الجلسات. -## ما تحصل عليه +## ما ستحصل عليه -صفحة `/audit` هي **ملصق** على شاشة واحدة وقابل للمشاركة متبوعاً بأربع أقسام أسفل الطية: +صفحة `/audit` عبارة عن **ملصق** واحد على شاشة واحدة وقابل للمشاركة متبوعاً بأربعة أقسام أسفل الصفحة: -1. **الملصق** — هوية وكيلك في لمحة: **نمطه** (واحد من 8 — `optimist` أو `cowboy` أو `explorer` أو `goldfish` أو `paranoid architect` أو `precision builder` أو `hammer` أو `ghost`)، وكلماته الرئيسية الشخصية، ومدى ندرة هذا النمط، و**درجة من 0 إلى 100** مع نطاق طبقة (`S` إلى `bottom tier`). مصممة للمشاركة — انشرها على X أو LinkedIn، أو حملها كملف PNG. -2. **`// strengths`** — ما يفعله وكيلك بالفعل بشكل جيد، كأرقام حقيقية من الفحص (مثلاً clean-tool-call % أو `0` محاولات push-to-main)، تظهر فقط حيث تحتفظ السياسة ذات الصلة بسجل نظيف. -3. **`// quirks`** — ما انزلق: جدول مرتب للسلوكيات التي كانت ستحتفظ بها failproofai — *متى* حدثت آخر مرة، *ما انزلق* (والأداة المدمجة التي كان يمكن أن تحظره)، **شدته**، وعدد مرات *رؤيته* (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — قائمة الإصلاح الموصوفة: صف واحد لكل سياسة مع `failproofai policy add ` قابلة للنسخ واللصق، بالإضافة إلى زر **تثبيت الكل** الذي يمكّن كل توصية في نفس الوقت ويظهر **درجتك المتوقعة** إذا فعلت ذلك. -5. **`// come back better`** — بناء العادة: اضبط **تذكير** إعادة التدقيق عبر البريد الإلكتروني (`3d` / `7d` / `14d` / `30d`) أو أعد التدقيق الآن، و**ادعُ صديقاً** لتشغيل التدقيق الخاص به (مرسل من failproof.ai مع نسخة لك). التذكيرات والدعوات تتطلب تسجيل الدخول — انظر [`failproofai auth`](/ar/cli/auth). +1. **الملصق** — هوية الوكيل للوهلة الأولى: **نموذجه الأصلي** (أحد 8 — `optimist`، `cowboy`، `explorer`، `goldfish`، `paranoid architect`، `precision builder`، `hammer`، `ghost`)، كلماته الأساسية في الشخصية، مدى ندرة هذا النموذج الأصلي، و **نقطة من 0–100** مع فئة (`S` وحتى `bottom tier`). تم بناؤه للمشاركة — انشر على X أو LinkedIn، أو نزّله كملف PNG. +2. **`// strengths`** — ما يفعله الوكيل جيداً بالفعل، كأرقام حقيقية من الفحص (مثل clean-tool-call %، `0` محاولات push-to-main)، موضحة فقط حيث تحتوي السياسة ذات الصلة على سجل نظيف. +3. **`// quirks`** — ما انزلق: جدول مرتب من السلوكيات التي كان يمكن لـ failproofai اكتشافها — *متى* حدثت آخر مرة، *ما انزلق* (والمدمج الذي كان سيحجبه)، *شدتها*، وكم مرة تمت رؤيتها (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — قائمة الإصلاح الموصوف: صف واحد لكل سياسة مع نسخ لصق `failproofai policy add `، بالإضافة إلى زر **install all** يفعّل كل توصية مرة واحدة ويظهر **المجموع المتوقع** الخاص بك إذا فعلت ذلك. +5. **`// come back better`** — بناء العادة: عيّن تذكير إعادة تدقيق بالبريد الإلكتروني **reminder** (`3d` / `7d` / `14d` / `30d`) أو أعد التدقيق الآن، و **ادعُ صديقاً** لتشغيل التدقيق الخاص به (مرسل من failproof.ai، مع نسخة موجهة إليك). تتطلب التذكيرات والدعوات تسجيل الدخول — انظر [`failproofai auth`](/ar/cli/auth). -## كواشف خاصة بالتدقيق فقط +## كواشف التدقيق فقط -تكتشف أنماط السلوك الأحمق غير المفروضة (حتى الآن) في الوقت الفعلي. يتم تشغيلها فقط أثناء التدقيق ولا تحجب أبداً استدعاء أداة مباشرة. +هذه تكتشف أنماط السلوك الحمقاء غير المطبقة (بعد) في الوقت الفعلي. تعمل فقط أثناء التدقيق ولا تحجب أبداً استدعاء أداة مباشرة. -| الكاشف | ما يعده | +| الكاشف | ما يحسبه | |---|---| -| `redundant-cd-cwd` | أوامر Bash تبدأ بـ `cd && …` حتى عندما تعمل الأوامر بالفعل في `cwd`. | +| `redundant-cd-cwd` | أوامر Bash التي تبدأ بـ `cd && …` حتى وإن كانت الأوامر تعمل بالفعل في `cwd`. | | `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` على ملف مصدر واحد — استخدم أداة `Read`. | -| `prefer-edit-over-sed-awk` | تعديلات في المكان `sed -i` / `awk … > file` — استخدم أداة `Edit`. | -| `prefer-write-over-heredoc` | كتابة ملفات Heredoc / متعددة الأسطر `echo > file` — استخدم أداة `Write`. | -| `sleep-polling-loop` | `sleep N` طويل (≥ 30s) أو حلقات استطلاع `while …; sleep …; done`. | -| `find-from-root` | `find /` أو `find /home` أو `find /usr` وما إلى ذلك — حصر النطاق على `cwd`. | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`، تخطي الخطافات. | +| `prefer-edit-over-sed-awk` | تحريرات في الموضع `sed -i` / `awk … > file` — استخدم أداة `Edit`. | +| `prefer-write-over-heredoc` | Heredoc / كتابة الملفات بـ `echo > file` متعدد الأسطر — استخدم أداة `Write`. | +| `sleep-polling-loop` | حلقات الانتظار `sleep N` الطويلة (≥ 30s) أو `while …; sleep …; done`. | +| `find-from-root` | `find /`, `find /home`, `find /usr`، إلخ. — حدد النطاق إلى `cwd` بدلاً من ذلك. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`، يتخطى الخطافات. | | `reread-after-edit` | `Read` لملف تم `Edit`/`Write` للتو في نفس الجلسة. | ## الذاكرات المؤقتة -- **ذاكرة مؤقتة لكل نص** في `~/.failproofai/cache/audit/.json` مفهرسة حسب `(mtime, size, engineVersion, detectorVersion)` — تبطل تلقائياً عندما يتغير النص أو كود السياسة/الكاشف. يخزن كل إدخال أيضاً طابع زمني `cachedAt` كـ **بيانات وصفية TTL** (ليس جزءاً من مفتاح الذاكرة المؤقتة)؛ الإدخالات الأقدم من **7 أيام** يتم رفضها عند القراءة حتى لا تتجاوز النتائج طويلة العمر نية الكاشف المتطورة. -- **ذاكرة مؤقتة للنتيجة الكاملة** في `~/.failproofai/audit-dashboard.json` (الوضع 0600). تسمح لوحة المعلومات بالعرض الفوري عند التنقل دون إعادة التشغيل. يتم رفضها أيضاً عند القراءة بعد **7 أيام TTL** — ثم `/audit` تسقط في حالتها الفارغة وتطلب تشغيل جديد. انقر على `[ re-audit now ]` بالقرب من أسفل التقرير للتحديث — إعادة التدقيق ترسل `noCache: true`، لذا تتجاوز ذاكرة التخزين المؤقت لكل نص وتعيد مسح كل نص بدلاً من إرجاع النتيجة المخزنة مؤقتاً؛ يعرض التشغيل تقدم التقدم عبر شريط لاصق في الأعلى ويستبدل النتيجة في مكانها عند النجاح (بدون إعادة تحميل الصفحة؛ فشل إعادة التدقيق يحتفظ بالتقرير السابق). +- **ذاكرة مؤقتة لكل نص** في `~/.failproofai/cache/audit/.json` مفهرسة حسب `(mtime, size, engineVersion, detectorVersion)` — تُلغى تلقائياً عند تغيير النص أو رمز السياسة/الكاشف. يخزن كل إدخال أيضاً طابع زمني `cachedAt` كـ **بيانات وصفية TTL** (ليست جزءاً من مفتاح الذاكرة المؤقتة)؛ الإدخالات الأقدم من **7 أيام** يتم رفضها عند القراءة حتى لا تتجاوز النتائج طويلة الأجل القصد المتطور للكاشف. +- **ذاكرة مؤقتة للنتيجة الكاملة** في `~/.failproofai/audit-dashboard.json` (mode 0600). تسمح لوحة التحكم بالعرض الفوري عند التنقل دون إعادة التشغيل. يتم رفضها أيضاً عند القراءة بعد **TTL لمدة 7 أيام** — ثم `/audit` تسقط إلى حالتها الفارغة وتطالب بتشغيل جديد. انقر على `[ re-audit now ]` بالقرب من أسفل التقرير للتحديث — تعيد التدقيق ترسل `noCache: true`، لذا فهي تتجاوز ذاكرة التخزين المؤقت لكل نص وتعيد فحص كل نص بدلاً من إرجاع النتيجة المخزنة مؤقتاً؛ التشغيل يتدفق التقدم عبر شريط لاصق في الأعلى ويبدل النتيجة في المكان عند النجاح (لا إعادة تحميل للصفحة؛ فشل إعادة التدقيق يحافظ على التقرير السابق). ## ملاحظات -- **بدون تحوير.** يعيد التدقيق التشغيل في الوضع للقراءة فقط. يتم تخطي `warn-repeated-tool-calls` لأن ملف جانبي لكل جلسة سيتم تعديله بخلاف ذلك. -- **سياسات سير العمل المتجاهلة.** تشغل سياسات `require-*-before-stop` فقط على أحداث `Stop` و `execSync` ضد حالة git المباشرة — ليس لديها تفسير معنوي "ماذا كان سيحدث في 2025"، لذا لا تظهر في أعداد التدقيق. -- **السياسات المخصصة المتجاهلة.** لا يتم إعادة تشغيل الخطافات المخصصة التي يوفرها المستخدم (قد تكون تغيرت منذ الجلسة الأصلية). \ No newline at end of file +- **لا طفرة.** يعاد التدقيق في وضع القراءة فقط. يتم تخطي `warn-repeated-tool-calls` لأن الملف الجانبي لكل جلسة قد يتم تعديله بخلاف ذلك. +- **سياسات سير العمل المتخطاة.** سياسات `require-*-before-stop` تنطلق فقط عند أحداث `Stop` و `execSync` مقابل حالة git المباشرة — ليس لديها تفسير ذي مغزى من نوع "ما كان سيحدث في 2025"، لذا لا تظهر في أعداد التدقيق. +- **السياسات المخصصة المتخطاة.** الخطافات المخصصة التي يوفرها المستخدم لا يتم إعادة تشغيلها (قد تكون قد تغيرت منذ الجلسة الأصلية). \ No newline at end of file diff --git a/docs/ar/cli/auth.mdx b/docs/ar/cli/auth.mdx index 627f8cb1..2b8057db 100644 --- a/docs/ar/cli/auth.mdx +++ b/docs/ar/cli/auth.mdx @@ -1,7 +1,7 @@ --- --- title: تسجيل الدخول -description: "قم بتسجيل الدخول إلى FailproofAI من سطر الأوامر لتفعيل التنبيهات والميزات المخصصة" +description: "سجّل دخولك إلى FailproofAI من واجهة سطر الأوامر لتفعيل التذكيرات والميزات المخصصة" --- ```bash @@ -10,9 +10,9 @@ failproofai auth logout # revoke this session failproofai auth whoami # print the signed-in identity ``` -صيغة العلم القديم `--login` / `--logout` / `--whoami` لا تزال مقبولة كاسم مستعار للتوافق مع الإصدارات السابقة. +صيغة العلم القديمة `--login` / `--logout` / `--whoami` لا تزال مقبولة كحكم توافقي للعودة. -المصادقة اختيارية. السياسات والعرض البياني وصفحة `/audit` وكل ميزة محلية أخرى تعمل بالطريقة ذاتها سواء قمت بتسجيل الدخول أم لا. واجهة تسجيل الدخول موجودة حتى تتمكن الميزات التي **تحتاج** إلى هوية مستقرة (تنبيهات إعادة التدقيق اليوم، والمزيد في المستقبل) من وجود مكان تستند إليه. +المصادقة اختيارية. السياسات واللوحة الإلكترونية وصفحة `/audit` وكل ميزة محلية أخرى تعمل بنفس الطريقة سواء كنت مسجل دخول أم لا. تم إنشاء سطح تسجيل الدخول بحيث تتمتع الميزات التي **تحتاج** إلى هوية مستقرة (تذكيرات إعادة التدقيق اليوم، المزيد في المستقبل) بمكان لتثبيتها. ## تدفق تسجيل الدخول @@ -20,9 +20,9 @@ failproofai auth whoami # print the signed-in identity failproofai auth login ``` -يطلب بريدك الإلكتروني، ويرسل رمز لمرة واحدة مكون من 6 أرقام إلى هذا العنوان، ويطلب الرمز، وعند النجاح يكتب `~/.failproofai/auth.json` (mode `0600`). نفس الجلسة تصبح مرئية بعد ذلك في العرض البياني داخل التطبيق — النقر على `[ set a reminder ]` على `/audit` سيظهرك كمسجل دخول. +يطلب بريدك الإلكتروني، ويرسل رمز التحقق لمرة واحدة مكون من 6 أرقام إلى هذا العنوان، ويطلب الرمز، وعند النجاح يكتب `~/.failproofai/auth.json` (الوضع `0600`). تصبح نفس الجلسة مرئية بعد ذلك للوحة الإلكترونية في التطبيق — سيؤدي النقر على `[ set a reminder ]` على `/audit` إلى رؤيتك مسجل دخول. -يعرض العرض البياني نفس التدفق كمربع حوار مشروط على `/audit` للمستخدمين الذين لا يستخدمون سطر الأوامر. +تعرض لوحة المعلومات نفس التدفق كمربع حوار مشروط على `/audit` للمستخدمين الذين لا يلمسون واجهة سطر الأوامر أبداً. ## تسجيل الخروج @@ -30,7 +30,7 @@ failproofai auth login failproofai auth logout ``` -يلغي الجلسة الحالية على الخادم ويحذف `~/.failproofai/auth.json`. إذا كان خادم api غير قابل للوصول، يتم إزالة الملف المحلي على أي حال — النية المحلية لتسجيل الخروج تفوز دائماً. +يلغي الجلسة الحالية على الخادم ويحذف `~/.failproofai/auth.json`. إذا كان خادم API غير قابل للوصول، يتم إزالة الملف المحلي على أي حال — النية المحلية لتسجيل الخروج تفوز دائماً. ## فحص الهوية @@ -38,11 +38,11 @@ failproofai auth logout failproofai auth whoami ``` -يطبع ` ()` ويخرج 0 عندما توجد جلسة صحيحة، أو `not signed in` ويخرج 1 بخلاف ذلك. ينعش رمز الوصول بصمت في الخلفية إذا كان على بعد دقيقة واحدة من انتهائه الصلاحية. +يطبع ` ()` والخروج 0 عند وجود جلسة صحيحة، أو `not signed in` والخروج 1 وإلا. ينعش رمز الوصول بصمت في الخلفية إذا كان في غضون دقيقة من انتهاء الصلاحية. -## تنبيه إعادة التدقيق المستمر +## تذكير إعادة التدقيق الدائم -عندما تنقر على **`[ set a reminder ]`** على صفحة `/audit` (أو تسجل الدخول عبر المربع الحواري الذي يحرسه الزر)، يكتب العرض البياني ملف مرافق صغير على `~/.failproofai/next-audit.json`: +عندما تنقر على **`[ set a reminder ]`** على صفحة `/audit` (أو تسجيل الدخول عبر المربع الحواري الذي يقيد الزر)، تكتب لوحة المعلومات ملف مرافق صغير في `~/.failproofai/next-audit.json`: ```json { @@ -52,11 +52,11 @@ failproofai auth whoami } ``` -هذا الملف محدد للبريد الإلكتروني الذي تم تعيينه له — تبديل جلسة سطر الأوامر إلى حساب مختلف يخفي أي تنبيه ينتمي للمستخدم السابق. الإزاحة الافتراضية هي **7 أيام**، قابلة للتكوين لاحقاً عندما يتم إطلاق جدول المهام. تم الإنشاء برمز `0600` مثل `auth.json`. +هذا الملف مخصص للبريد الإلكتروني الذي تم تعيينه له — سيؤدي تبديل جلسة CLI إلى حساب مختلف إلى إخفاء أي تذكير يخص المستخدم السابق. الإزاحة الافتراضية هي **7 أيام**، قابلة للتخصيص لاحقاً عند وصول المجدول. تم إنشاؤها بأذونات `0600` مثل `auth.json`. -نقطة نهاية `/api/auth/reminder` للعرض البياني تعرض `GET` (قراءة)، `POST` (تعيين / إعادة جدولة)، و `DELETE` (مسح) وتتطلب جلسة نشطة. +يعرّض نقطة نهاية لوحة المعلومات `/api/auth/reminder` الطلب `GET` (القراءة)، `POST` (التعيين / إعادة الجدولة)، و `DELETE` (المسح) ويتطلب جلسة نشطة. -## ما في `~/.failproofai/auth.json` +## ما يوجد في `~/.failproofai/auth.json` ```json { @@ -68,21 +68,21 @@ failproofai auth whoami } ``` -تم الإنشاء برمز `0600` (قراءة/كتابة خاصة بالمالك). رمز الوصول هو JWT مدة HS256 بمدة ساعة واحدة؛ رمز التحديث هو سلسلة عشوائية معتمة بحجم 256 بت يخزنها الخادم كـ `SHA-256(token)`. يتم الكشف عن إعادة تشغيل رمز التحديث من جانب الخادم وإلغاء كل جلسات المستخدم. +تم إنشاؤها بأذونات `0600` (قراءة/كتابة للمالك فقط). رمز الوصول هو HS256 JWT مدته ساعة واحدة؛ رمز التحديث عبارة عن سلسلة عشوائية معتمة من 256 بت يخزنها الخادم كـ `SHA-256(token)`. يتم الكشف عن إعادة تشغيل رمز التحديث من جانب الخادم ويلغي كل جلسة للمستخدم. ## متغيرات البيئة -| المتغير | الافتراضي | الغرض | +| Variable | Default | Purpose | |---|---|---| -| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | تجاوز عنوان URL الأساسي لخادم api. مفيد للتطوير المحلي مقابل خادم api مستضاف ذاتياً. | -| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | تجاوز حيث يتم تخزين `auth.json`. في الأساس للاختبارات. | +| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | تجاوز عنوان URL الأساسي لخادم API. مفيد للتطوير المحلي مقابل خادم API الذي يستضيفه بنفسه. | +| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | تجاوز حيث يتم تخزين `auth.json`. في الغالب للاختبارات. | -انظر [متغيرات البيئة](/ar/cli/environment-variables) للقائمة الكاملة. +انظر [متغيرات البيئة](/ar/cli/environment-variables) للحصول على القائمة الكاملة. ## استكشاف الأخطاء -**"لم يتمكن من الوصول إلى خادم api"** — لا يمكن لسطر الأوامر فتح اتصال TCP بـ `FAILPROOF_API_URL`. تحقق من شبكتك، أو عيّن `FAILPROOF_API_URL` إذا كنت تقوم بتشغيل خادم api مستضاف ذاتياً. +**"Could not reach the api-server"** — لا يستطيع CLI فتح اتصال TCP بـ `FAILPROOF_API_URL`. تحقق من شبكتك، أو عيّن `FAILPROOF_API_URL` إذا كنت تقوم بتشغيل خادم API الذي تستضيفه بنفسك. -**"تم تجاوز حد المعدل"** — عدد كبير جداً من محاولات تسجيل الدخول في نافذة 15 دقيقة لهذا البريد الإلكتروني (5/بريد) أو IP (20/IP)، أو فترة انتظار إعادة إرسال 30 ثانية بعد الطلب السابق للبريد الإلكتروني ذاته. تتضمن رسالة الخطأ نافذة إعادة المحاولة بالثواني. +**"Rate limited"** — عدد كبير جداً من محاولات تسجيل الدخول في نافذة 15 دقيقة لهذا البريد الإلكتروني (5/البريد الإلكتروني) أو IP (20/IP)، أو فترة إعادة إرسال مدتها 30 ثانية بعد الطلب السابق لنفس البريد الإلكتروني. تتضمن رسالة الخطأ نافذة إعادة المحاولة بالثواني. -**تم رفض الرمز** — كانت OTP خاطئة أو انتهت صلاحيتها أو ضربت الصف قفل التخمين الخاطئ 5 مرات. شغّل `failproofai auth login` مرة أخرى لطلب رمز جديد. \ No newline at end of file +**Code rejected** — كانت كلمة المرور لمرة واحدة خاطئة أو منتهية الصلاحية، أو أن الصف تعرض لقفل 5 تخمينات خاطئة. شغّل `failproofai auth login` مرة أخرى لطلب رمز جديد. \ No newline at end of file diff --git a/docs/ar/cli/dashboard.mdx b/docs/ar/cli/dashboard.mdx index 159c3691..970cff5b 100644 --- a/docs/ar/cli/dashboard.mdx +++ b/docs/ar/cli/dashboard.mdx @@ -1,4 +1,5 @@ --- +--- title: عرض الجلسات description: "قم بتشغيل لوحة التحكم لاستعراض جلسات الوكيل وإدارة السياسات" --- @@ -7,16 +8,16 @@ description: "قم بتشغيل لوحة التحكم لاستعراض جلسا failproofai ``` -يبدأ لوحة التحكم الويب على `http://localhost:8020`. +يبدأ لوحة التحكم على الويب في `http://localhost:8020`. ## الخيارات | العلم | الوصف | |------|-------------| -| `--port ` | المنفذ المراد الاستماع عليه (القيمة الافتراضية: `8020`) | -| `--allowed-origins ` | مضيفين/عناوين IP مفصولة بفواصل مسموحة للوصول إلى موارد التطوير | +| `--port ` | المنفذ الذي سيتم الاستماع عليه (الافتراضي: `8020`) | +| `--allowed-origins ` | قائمة مضيفين/عناوين IP مفصولة بفواصل مسموح لها بالوصول إلى موارد التطوير | -لتوجيه لوحة التحكم إلى مجلد مشروع Claude غير افتراضي، قم بتعيين متغير البيئة `CLAUDE_PROJECTS_PATH` عند بدء التشغيل. +لتوجيه لوحة التحكم إلى مجلد Claude project غير افتراضي، قم بتعيين متغير البيئة `CLAUDE_PROJECTS_PATH` عند التشغيل. ## أمثلة @@ -24,6 +25,6 @@ failproofai # قم بالتشغيل على منفذ مختلف failproofai --port 9000 -# استخدم مسار مشاريع Claude مخصص عبر متغير البيئة +# استخدم مسار Claude projects مخصص عبر متغير البيئة CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/ar/cli/environment-variables.mdx b/docs/ar/cli/environment-variables.mdx index 5e47dad3..1aa9a537 100644 --- a/docs/ar/cli/environment-variables.mdx +++ b/docs/ar/cli/environment-variables.mdx @@ -1,4 +1,5 @@ --- +--- title: متغيرات البيئة description: "تكوين سلوك failproofai باستخدام متغيرات البيئة" --- @@ -9,39 +10,39 @@ description: "تكوين سلوك failproofai باستخدام متغيرات ا |----------|-------------| | `PORT` | منفذ لوحة التحكم (الافتراضي: `8020`) | | `CLAUDE_PROJECTS_PATH` | تجاوز موقع مجلدات مشاريع Claude Code | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | صفحات لوحة التحكم المفصولة بفواصل لإخفاؤها | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | المضيفون/عناوين IP المسموح لها بالوصول إلى موارد التطوير. نفس `--allowed-origins`. | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | صفحات لوحة التحكم المراد إخفاؤها مفصولة بفواصل | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | المضيفون/عناوين IP المسموح لهم بالوصول إلى موارد التطوير. نفس `--allowed-origins`. | ## تسجيل السجلات | المتغير | الوصف | |----------|-------------| | `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | مستوى سجل الخادم (الافتراضي: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | مسار ملف السجل المخصص للخطاف، أو `true` للقيمة الافتراضية (`~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | مسار ملف سجل hook مخصص، أو `true` للقيمة الافتراضية (`~/.failproofai/logs/hooks.log`) | -## بيانات الاستخدام +## جمع البيانات | المتغير | الوصف | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | تعطيل بيانات الاستخدام المجهولة | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | تعطيل جمع بيانات الاستخدام المجهول | ## المصادقة | المتغير | الوصف | |----------|-------------| -| `FAILPROOF_API_URL` | تجاوز عنوان URL الأساسي للخادم الذي تستخدمه `failproofai auth` وحوار مصادقة لوحة التحكم. القيمة الافتراضية `https://api.befailproof.ai`؛ اضبطها على `http://localhost:8080` (أو في أي مكان آخر) عند تشغيل خادم api محلي. | -| `FAILPROOFAI_AUTH_DIR` | تجاوز موقع تخزين `auth.json` (الافتراضي: `~/.failproofai`). مفيد بشكل أساسي للاختبارات المعزولة. | +| `FAILPROOF_API_URL` | تجاوز عنوان URL الأساسي لخادم API الذي يستخدمه `failproofai auth` ومربع حوار مصادقة لوحة التحكم. القيمة الافتراضية `https://api.befailproof.ai`؛ عيّنها إلى `http://localhost:8080` (أو حيثما يكون) عند تشغيل خادم api محلي. | +| `FAILPROOFAI_AUTH_DIR` | تجاوز موقع تخزين `auth.json` (الافتراضي: `~/.failproofai`). مفيد في الغالب للاختبارات المعزولة. | -## مطالبة التشغيل الأول +## طلب التشغيل الأول | المتغير | الوصف | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | تخطي المطالبة التي تعرض تثبيت السياسات عند استدعاء `failproofai` الأول الفارغ | +| `FAILPROOFAI_NO_FIRST_RUN=1` | تخطي الطلب الذي يعرض تثبيت السياسات عند استدعاء `failproofai` الأول الأساسي | -## نموذج اللغة (لتقييم السياسة) +## LLM (لتقييم السياسات) | المتغير | الوصف | |----------|-------------| -| `FAILPROOFAI_LLM_BASE_URL` | نقطة نهاية واجهة برمجة التطبيقات للنموذج (الافتراضي: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | مفتاح واجهة برمجة التطبيقات لسياسات مدعومة بنموذج اللغة | +| `FAILPROOFAI_LLM_BASE_URL` | نقطة نهاية LLM API (الافتراضي: `https://api.openai.com/v1`) | +| `FAILPROOFAI_LLM_API_KEY` | مفتاح API لسياسات مدعومة بـ LLM | | `FAILPROOFAI_LLM_MODEL` | اسم النموذج (الافتراضي: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/ar/cli/hook.mdx b/docs/ar/cli/hook.mdx index 34c37c48..6faf8937 100644 --- a/docs/ar/cli/hook.mdx +++ b/docs/ar/cli/hook.mdx @@ -1,5 +1,5 @@ --- -title: معالج الخطاف (داخلي) +title: معالج Hook (داخلي) description: "العملية الفرعية التي يستدعيها Claude Code عند كل حدث أداة" --- @@ -7,24 +7,24 @@ description: "العملية الفرعية التي يستدعيها Claude Cod failproofai --hook ``` -هذا هو الأمر المسجل في `settings.json` الخاص بـ Claude Code بواسطة `failproofai policies --install`. لا تستدعيه مباشرة عادةً. +هذا هو الأمر المسجل في `settings.json` الخاص بـ Claude Code بواسطة `failproofai policies --install`. عادة لا تستدعيه مباشرة. -يقرأ حمولة JSON من stdin، ويقيّم جميع السياسات المفعلة، ويخرج برمز يشير إلى القرار: +يقرأ حمولة JSON من stdin، ويقيّم جميع السياسات المفعّلة، ويخرج برمز يشير إلى القرار: | رمز الخروج | القرار | التأثير | |-----------|--------|--------| | `0` | `allow` | السماح بالإجراء | | `1` | `deny` | حظر الإجراء - يرى Claude سبب الرفض | -| `2` | `instruct` | حقن التوجيهات في سياق Claude | +| `2` | `instruct` | إدراج الإرشادات في سياق Claude | ### أنواع الأحداث المدعومة | الفئة | الأحداث | -|------|--------| -| **تنفيذ الأدوات** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | +|----------|--------| +| **تنفيذ الأداة** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | | **دورة حياة الجلسة** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | -| **تفاعل المستخدم** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | +| **التفاعل مع المستخدم** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | | **الوكلاء الفرعيون والمهام** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | -| **التكوين** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | +| **الإعدادات** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | | **نظام الملفات** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | | **السياق** | `PreCompact`, `PostCompact` | \ No newline at end of file diff --git a/docs/ar/cli/install-policies.mdx b/docs/ar/cli/install-policies.mdx index 1bc97120..099b8040 100644 --- a/docs/ar/cli/install-policies.mdx +++ b/docs/ar/cli/install-policies.mdx @@ -1,57 +1,57 @@ --- title: تثبيت السياسات -description: "تفعيل السياسات بحيث يتم تشغيلها على كل استدعاء أداة وكيل" +description: "فعّل السياسات لكي تعمل على كل استدعاء أداة وكيل" --- ```bash failproofai policies --install [policy-names...] [options] ``` -يكتب إدخالات hook في ملف إعدادات CLI الوكيل المثبت لديك (Claude Code أو OpenAI Codex أو GitHub Copilot CLI _(beta)_) بحيث يعترض failproofai استدعاءات الأدوات. +يكتب إدخالات خطاف في ملف الإعدادات الخاص بواجهة سطر الأوامر للوكيل المثبتة لديك (Claude Code أو OpenAI Codex أو GitHub Copilot CLI _(beta)_) بحيث يعترض failproofai استدعاءات الأدوات. -الأسماء المختصرة: `failproofai p -i` +الأسماء المستعارة: `failproofai p -i` ## الخيارات | العلم | الوصف | -|------|---------| -| `--cli claude\|codex\|copilot` | CLI الوكيل المراد التثبيت له؛ مفصول بمسافات (مثل `--cli claude codex copilot`) أو متكرر. حذف للكشف عن CLIs المثبتة والطلب منك الاختيار. | -| `--scope user` | التثبيت في ملف الإعدادات ذو النطاق الخاص بالمستخدم (Claude: `~/.claude/settings.json`؛ Codex: `~/.codex/hooks.json`؛ Copilot: `~/.copilot/hooks/failproofai.json`). الافتراضي. | -| `--scope project` | التثبيت في ملف الإعدادات ذو النطاق الخاص بالمشروع (Claude: `/.claude/settings.json`؛ Codex: `/.codex/hooks.json`؛ Copilot: `/.github/hooks/failproofai.json`). | +|------|-------------| +| `--cli claude\|codex\|copilot` | واجهات سطر الأوامر للوكيل المراد التثبيت لها؛ مفصولة بمسافات (مثل `--cli claude codex copilot`) أو مكررة. اتركها فارغة للكشف التلقائي عن واجهات سطر الأوامر المثبتة والمطالبة. | +| `--scope user` | التثبيت في ملف إعدادات النطاق العام (`~/.claude/settings.json` لـ Claude؛ `~/.codex/hooks.json` لـ Codex؛ `~/.copilot/hooks/failproofai.json` لـ Copilot). الخيار الافتراضي. | +| `--scope project` | التثبيت في ملف إعدادات نطاق المشروع (`/.claude/settings.json` لـ Claude؛ `/.codex/hooks.json` لـ Codex؛ `/.github/hooks/failproofai.json` لـ Copilot). | | `--scope local` | Claude فقط — التثبيت في `/.claude/settings.local.json`. Codex و Copilot لا يملكان نطاق `local`. | -| `--custom ` / `-c` | المسار إلى ملف JS يحتوي على سياسات hook مخصصة | +| `--custom ` / `-c` | المسار إلى ملف JavaScript يحتوي على سياسات خطاف مخصصة | ## السلوك -- **بدون أسماء سياسات** - يفتح موجه تفاعلي لاختيار السياسات -- **أسماء محددة** - تفعيل تلك السياسات (مضافة إلى أي سياسات مفعلة بالفعل) -- **`all`** - تفعيل كل سياسة متاحة +- **بدون أسماء سياسات** - يفتح موجه تفاعلي لتحديد السياسات +- **أسماء محددة** - تفعيل تلك السياسات (تضاف إلى أي سياسات مفعلة بالفعل) +- **`all`** - تفعيل كل السياسات المتاحة -التثبيت هو إضافي: تشغيل `--install` مرة أخرى يضيف سياسات جديدة دون إزالة السياسات الموجودة. +التثبيت عملية إضافية: تشغيل `--install` مرة أخرى يضيف سياسات جديدة دون إزالة السياسات الموجودة. ## أمثلة ```bash -# Install all default policies globally (interactive) +# تثبيت جميع السياسات الافتراضية عالميًا (تفاعلي) failproofai policies --install -# Install specific policies for the current project +# تثبيت سياسات محددة للمشروع الحالي failproofai policies --install block-sudo sanitize-api-keys --scope project -# Enable all policies at once +# تفعيل جميع السياسات دفعة واحدة failproofai policies --install all -# Install with a custom policies file +# التثبيت مع ملف سياسات مخصص failproofai policies --install --custom ./my-policies.js -# Install for OpenAI Codex (project scope) +# التثبيت لـ OpenAI Codex (نطاق المشروع) failproofai policies --install --cli codex --scope project -# Install for GitHub Copilot CLI (beta) for the current project +# التثبيت لـ GitHub Copilot CLI (beta) للمشروع الحالي failproofai policies --install --cli copilot --scope project -# Install for all three CLIs at once +# التثبيت لجميع واجهات سطر الأوامر الثلاث في وقت واحد failproofai policies --install --cli claude codex copilot ``` -عند توفير `--custom `، يتم التحقق من صحة الملف فوراً - يجب أن يستدعي `customPolicies.add()` مرة واحدة على الأقل. يتم حفظ المسار المحل في `policies-config.json` باسم `customPoliciesPath`. \ No newline at end of file +عند توفير `--custom `، يتم التحقق من صحة الملف فورًا - يجب أن يستدعي `customPolicies.add()` مرة واحدة على الأقل. يتم حفظ المسار المحل في `policies-config.json` باسم `customPoliciesPath`. \ No newline at end of file diff --git a/docs/ar/cli/list-policies.mdx b/docs/ar/cli/list-policies.mdx index 3f3a5a92..dc4c81ea 100644 --- a/docs/ar/cli/list-policies.mdx +++ b/docs/ar/cli/list-policies.mdx @@ -1,14 +1,14 @@ --- --- title: قائمة السياسات -description: "اطّلع على السياسات المفعّلة وبارامتراتها والسياسات المخصصة" +description: "انظر إلى السياسات المفعّلة وخصائصها والسياسات المخصصة" --- ```bash failproofai policies ``` -يعرض جميع السياسات مع حالتها والمعاملات المعدّة لها والسياسات المخصصة. +يعرض جميع السياسات مع حالتها والخصائص المعدّة والسياسات المخصصة. ## نموذج الإخراج @@ -29,4 +29,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -يتم وضع علامة على المفاتيح غير المعروفة في `policyParams` هنا حتى تتمكن من اكتشاف الأخطاء الإملائية مبكراً. \ No newline at end of file +المفاتيح غير المعروفة في `policyParams` يتم تحديدها هنا حتى تتمكن من اكتشاف الأخطاء الإملائية مبكراً. \ No newline at end of file diff --git a/docs/ar/cli/remove-policies.mdx b/docs/ar/cli/remove-policies.mdx index 9dd78d2f..4047fa18 100644 --- a/docs/ar/cli/remove-policies.mdx +++ b/docs/ar/cli/remove-policies.mdx @@ -1,42 +1,42 @@ --- --- title: إلغاء تثبيت السياسات -description: "إزالة مدخلات الربط من إعدادات Claude Code" +description: "إزالة إدخالات الخطاف من إعدادات Claude Code" --- ```bash failproofai policies --uninstall [policy-names...] [options] ``` -يزيل مدخلات failproofai hook من `settings.json` في Claude Code. +يزيل إدخالات خطاف failproofai من `settings.json` الخاص بـ Claude Code. -الأسماء البديلة: `failproofai p -u` +الأسماء المختصرة: `failproofai p -u` ## الخيارات -| العلم | الوصف | -|------|----------| -| `--scope user` | إزالة من الإعدادات العامة (الافتراضي) | -| `--scope project` | إزالة من إعدادات المشروع | -| `--scope local` | إزالة من الإعدادات المحلية | -| `--scope all` | إزالة من جميع النطاقات في آن واحد | -| `--custom` / `-c` | مسح `customPoliciesPath` من الإعدادات | +| الراية | الوصف | +|------|-------------| +| `--scope user` | الإزالة من الإعدادات العامة (الافتراضي) | +| `--scope project` | الإزالة من إعدادات المشروع | +| `--scope local` | الإزالة من الإعدادات المحلية | +| `--scope all` | الإزالة من جميع النطاقات في نفس الوقت | +| `--custom` / `-c` | مسح `customPoliciesPath` من التكوين | ## السلوك -- **بدون أسماء سياسات** - يزيل جميع مدخلات failproofai hook من ملف الإعدادات -- **أسماء محددة** - يعطل تلك السياسات لكن يحتفظ بالربطات المثبتة +- **بدون أسماء سياسات** - يزيل جميع إدخالات خطاف failproofai من ملف الإعدادات +- **أسماء محددة** - يعطل تلك السياسات لكن يحافظ على الخطافات المثبتة ## أمثلة ```bash -# إزالة جميع الربطات عموماً +# إزالة جميع الخطافات عالمياً failproofai policies --uninstall -# تعطيل سياسة محددة (الاحتفاظ بالربطات المثبتة) +# تعطيل سياسة محددة (مع الحفاظ على الخطافات المثبتة) failproofai policies --uninstall block-sudo -# إزالة الربطات من كل النطاقات +# إزالة الخطافات من كل النطاقات failproofai policies --uninstall --scope all # مسح مسار السياسات المخصصة diff --git a/docs/ar/configuration.mdx b/docs/ar/configuration.mdx index c1857fd8..71fa9a37 100644 --- a/docs/ar/configuration.mdx +++ b/docs/ar/configuration.mdx @@ -1,58 +1,58 @@ --- --- title: التكوين -description: "تنسيق ملف الإعدادات، نظام النطاقات الثلاثة، وقواعد الدمج" +description: "تنسيق ملف الإعدادات، ونظام النطاقات الثلاثة، وقواعد الدمج" icon: gear --- -يستخدم failproofai ملفات تكوين JSON للتحكم في السياسات النشطة وسلوكها وموقع تحميل السياسات المخصصة. تم تصميم التكوين ليكون سهل المشاركة مع فريقك - قم بإرساله إلى مستودع المشروع وسيحصل كل مطور على نفس شبكة الأمان للوكيل. +يستخدم failproofai ملفات إعدادات JSON للتحكم في السياسات المفعلة وكيفية عملها ومن أين يتم تحميل السياسات المخصصة. صُمم التكوين ليكون سهل المشاركة مع فريقك - التزمه في مستودعك وسيحصل كل مطور على نفس شبكة الأمان للوكيل. --- ## نطاقات التكوين -هناك ثلاثة نطاقات تكوين، يتم تقييمها بترتيب الأولوية: +هناك ثلاثة نطاقات للتكوين، يتم تقييمها بترتيب الأولوية: | النطاق | مسار الملف | الغرض | |-------|-----------|---------| -| **المشروع** | `.failproofai/policies-config.json` | إعدادات لكل مستودع، مرسلة للتحكم بالإصدار | -| **محلي** | `.failproofai/policies-config.local.json` | تجاوزات شخصية لكل مستودع، مُضافة لـ gitignore | +| **المشروع** | `.failproofai/policies-config.json` | إعدادات خاصة بكل مستودع، مرتبطة بمراقبة الإصدار | +| **محلي** | `.failproofai/policies-config.local.json` | تجاوزات شخصية لكل مستودع، مستبعدة من git | | **عام** | `~/.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"] } ← المشروع يفوز، يتم تجاهل global +resolved: { allowPatterns: ["sudo apt-get update"] } ← المشروع يفوز، يتم تجاهل العام ``` ```text -project: (no block-sudo entry) -local: (no block-sudo entry) +project: (لا توجد إدخالة block-sudo) +local: (لا توجد إدخالة block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← الانتقال إلى global +resolved: { allowPatterns: ["sudo systemctl status"] } ← ينتقل إلى العام ``` -**`customPoliciesPath`** - النطاق الأول الذي يحدده يفوز. +**`customPoliciesPath`** - أول نطاق يحدده يفوز. -**`llm`** - النطاق الأول الذي يحدده يفوز. +**`llm`** - أول نطاق يحدده يفوز. --- @@ -103,33 +103,33 @@ 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` على الإطلاق يحصلون على سلوك متطابق مع الإصدارات السابقة. -المفاتيح المجهولة داخل كتلة معاملات السياسة يتم تجاهلها بصمت في وقت تشغيل 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 { "policyParams": { "block-force-push": { - "hint": "حاول إنشاء فرع طازج بدلاً من ذلك." + "hint": "حاول إنشاء فرع جديد بدلاً من ذلك." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], @@ -142,32 +142,32 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← الانتقال إ } ``` -عندما يقوم `block-force-push` برفض، يرى Claude: *"دفع القوة مُحظور. حاول إنشاء فرع طازج بدلاً من ذلك."* +عندما ترفض `block-force-push`، يرى Claude: *"فرض الدفع محظور. حاول إنشاء فرع جديد بدلاً من ذلك."* -القيم غير النصية والنصوص الفارغة يتم تجاهلها بصمت. إذا لم يتم تعيين `hint`، يبقى السلوك بدون تغيير (متوافق للخلف). +القيم غير النصية والنصوص الفارغة يتم تجاهلها بصمت. إذا لم يتم تعيين `hint`، السلوك لا يتغير (متوافق مع الإصدارات السابقة). ### `customPoliciesPath` النوع: `string` (مسار مطلق) -مسار ملف JavaScript يحتوي على سياسات hook مخصصة. يتم تعيينه تلقائياً بواسطة `failproofai policies --install --custom ` (يتم حل المسار إلى مطلق قبل تخزينه). +مسار ملف JavaScript يحتوي على سياسات خطاف مخصصة. يتم تعيينه تلقائياً بواسطة `failproofai policies --install --custom ` (يتم حل المسار إلى مطلق قبل التخزين). -يتم تحميل الملف بشكل جديد في كل حدث hook - لا يوجد تخزين مؤقت. انظر [السياسات المخصصة](/ar/custom-policies) لتفاصيل التأليف. +يتم تحميل الملف مجدداً في كل حدث خطاف - لا يوجد تخزين مؤقت. انظر [السياسات المخصصة](/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`. قم فقط بإسقاط الملفات في المجلد وسيتم التقاطها في حدث hook التالي. +**لا حاجة لإعدادات:** سياسات الاتفاقية لا تتطلب إدخالات في `policies-config.json`. فقط ضع ملفات في الدليل وسيتم التقاطها في حدث الخطاف التالي. -**تحميل الاتحاد:** يتم مسح كل من مجلدات الاتفاقيات للمشروع والمستخدم. يتم تحميل جميع الملفات المطابقة من كلا المستويين (بخلاف `customPoliciesPath` الذي يستخدم أولوية النطاق الأول). +**تحميل الاتحاد:** يتم البحث في دلائل الاتفاقية للمشروع والمستخدم. يتم تحميل جميع الملفات المطابقة من كلا المستويين (على عكس `customPoliciesPath` الذي يستخدم أول نطاق يفوز). انظر [السياسات المخصصة](/ar/custom-policies) لمزيد من التفاصيل والأمثلة. @@ -175,7 +175,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← الانتقال إ النوع: `object` (اختياري) -تكوين عميل LLM للسياسات التي تجري استدعاءات AI. غير مطلوب لمعظم الإعدادات. +إعدادات عميل LLM للسياسات التي تقوم بعمليات استدعاء ذكية. غير مطلوبة لمعظم الإعدادات. ```json { @@ -188,21 +188,22 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← الانتقال إ --- -## إدارة التكوين من سطر الأوامر +## إدارة الإعدادات من سطر الأوامر -تقوم أوامر `policies --install` و `policies --uninstall` بالكتابة إلى ملف إعدادات hook الخاص بـ agent CLI (نقاط دخول hook)، بينما `policies-config.json` هو الملف الذي تديره مباشرة. الاثنان منفصلان: +تقوم أوامر `policies --install` و `policies --uninstall` بالكتابة إلى ملف إعدادات خطاف عميل الوكيل (نقاط دخول الخطاف)، بينما `policies-config.json` هو الملف الذي تديره مباشرة. الاثنان منفصلان: -- **إعدادات Agent 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`. إدخالات 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`)، لكن مخزنة تحت مفاتيح الأحداث بـ 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`. بخلاف CLI الستة الأخرى، OpenCode **ليس لديه نظام hook أوامر خارجية**: يقوم بتحميل مكونات JS/TS في العملية والمسجلة بشكل صريح عبر مصفوفة `plugin: []` في `opencode.json` (الاكتشاف التلقائي من `.opencode/plugins/` **ليس** كيفية تحميل المكونات الإضافية على opencode v1.14.33). يسقط التثبيت shim مكون إضافي صغير مُولّد يستدعي ثنائي failproofai بـ subprocess ويترجم استجابة JSON على شكل Claude للثنائي مرة أخرى إلى دلالات المكون الإضافي: `throw new Error()` لأداة-حدث deny (يلغي استدعاء الأداة)، `client.session.prompt(...)` لـ instruct و `Stop` / `SubagentStop` deny (يرسل سبب الرفض كرسالة المستخدم التالية — قناة إعادة المحاولة الوحيدة لأن `session.idle` هي إشعار فقط والرمي منها هو no-op)، و no-op للسماح. يقوم Shim بتشريع أسماء الأدوات (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 DB الخاص بـ 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/` المجمع الخاص به. يشترك الملحق داخلياً في أحداث 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's Read / Write / Edit تسلم `path` بدلاً من `file_path`؛ تعيين المفتاح على المستوى الأعلى يسمح لـ `block-env-files` و `block-secrets-write` بالتطبيق — `block-read-outside-cwd` كان بالفعل لديه احتياطي `path`). دعم Pi في **beta** بينما تستقر API ملحق Pi ومخطط سجل الجلسة. - - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (مستخدم)، `/.gemini/settings.json` (مشروع) — Gemini لا يحتوي على نطاق `local` (يوثق نطاق `system` في `/etc/gemini-cli/settings.json` الذي لا يعرضه failproofai). إدخالات Hook تستخدم نموذج Claude `{type, command, timeout}` ملفوف في مخطط matcher Gemini `{matcher, hooks: [...]}` مع `matcher: "*"` بشكل افتراضي. الأحداث بـ PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`)؛ يقوم المعالج بالتعيين إلى أسماء Claude الأساسية عبر `GEMINI_EVENT_MAP`. أسماء الأدوات بـ snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — يقوم المعالج بالتشريع عبر `GEMINI_TOOL_MAP` بحيث تطلق السياسات المدمجة الموجودة بدون تغيير. يصدر محقق السياسة نموذج Gemini المسطح `{decision: "deny", reason}` (المفضل وفقاً لقاعدة Gemini الذهبية exit-0)، `{hookSpecificOutput: {hookEventName, additionalContext}}` لحقن السياق في BeforeAgent / AfterTool / SessionStart، و `{decision: "block", reason}` في AfterAgent لدلالات إعادة المحاولة الإجبارية. دعم Gemini CLI في **beta** بينما نوسع التغطية الحقيقية. انظر [وثائق hooks Gemini CLI](https://geminicli.com/docs/hooks/). -- **`policies-config.json`** — يخبر failproofai بالسياسات المراد تقييمها والمعاملات التي تستخدمها (مشترك عبر جميع 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 ليس له نطاق محلي. إدخالات الخطاف تستخدم حقول أوامر 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 وتخطيط سجل الجلسة. + - **Gemini CLI _(نسخة تجريبية)_**: `~/.gemini/settings.json` (مستخدم), `/.gemini/settings.json` (مشروع) — Gemini ليس له نطاق محلي (يوثق نطاق `system` على `/etc/gemini-cli/settings.json` الذي لا يعرضه failproofai). إدخالات الخطاف تستخدم نموذج Claude `{type, command, timeout}` ملفوف في مخطط مطابق Gemini `{matcher, hooks: [...]}` مع `matcher: "*"` افتراضياً. الأحداث تكون PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); يقوم المعالج بالتعيين إلى أسماء Claude الأساسية عبر `GEMINI_EVENT_MAP`. أسماء الأدوات تكون snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — يقوم المعالج بتحويلها عبر `GEMINI_TOOL_MAP` بحيث تعمل السياسات المدمجة الموجودة بدون تغيير. يصدر محقق السياسة شكل Gemini المسطح `{decision: "deny", reason}` (مفضل وفقاً لـ Golden Rule للخروج-0 من Gemini)، `{hookSpecificOutput: {hookEventName, additionalContext}}` لحقن السياق على BeforeAgent / AfterTool / SessionStart، و `{decision: "block", reason}` على AfterAgent لدلالات الإعادة القسرية. دعم Gemini CLI **نسخة تجريبية** بينما نوسع التغطية الحقيقية. انظر [مستندات خطافات Gemini CLI](https://geminicli.com/docs/hooks/). + - **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|gemini` لاستهداف وكيل معين (مفصول بمسافات أو متكرر لأي مجموعة فرعية): +مرر `--cli claude|codex|copilot|cursor|opencode|pi|gemini|hermes` لاستهداف وكيل محدد (مفصول بمسافات أو متكرر لأي مجموعة فرعية): ```bash failproofai policies --install --cli codex --scope project @@ -211,23 +212,24 @@ 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 gemini --scope project +failproofai policies --install --cli hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` -عند حذف `--cli`، يكتشف `failproofai` أي CLI وكيل مثبت (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): +عندما يتم حذف `--cli`، يكتشف failproofai عملاء الوكيل المثبتة (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini` / `which hermes`): -- **يتم الكشف عن CLI واحد** — يختار تلك CLI تلقائياً بدون مطالبة. -- **يتم الكشف عن عدة CLI** في جهاز طرفي تفاعلي — يعرض موجه اختيار واحد مع مفاتيح الأسهم معروض بمجموعات في قسم `Detected (N)` (مع صف إجمالي `Install for all N detected` + كل CLI يتم الكشف عنها بشكل فردي) وقسم `Not installed (M) · install hooks ahead of time` يسرد كل CLI مدعومة لم يتم اكتشافها كخيار تثبيت مسبق (↑↓ للتحرك، Enter للتحديد، ^C للخروج). يعرض تدفق الإلغاء القسم المكتشف فقط. -- **يتم الكشف عن عدة CLI** في تشغيل غير تفاعلي (CI، بدون TTY) — يثبت لجميع CLI المكتشفة بدون مطالبة. -- **لم يتم الكشف عن أي** — يرجع إلى `claude`، مع تحذير من أن لم يتم العثور على ثنائي وكيل في PATH؛ أمر hook لا يزال مكتوباً بحيث ينشط بمجرد تثبيت واحد. +- **تم اكتشاف عميل واحد** — يختار ذلك العميل تلقائياً بدون فور. +- **عملاء متعددة مكتشفة** في محطة طرفية تفاعلية — يعرض موجه اختيار مفرد بمفاتيح الأسهم مجمع في قسم `Detected (N)` (مع صف إجمالي للتثبيت لكل عميل مكتشفة N + كل عميل مكتشفة بشكل فردي) وقسم `Not installed (M) · install hooks ahead of time` يسرد كل عميل مكتشفة مدعومة كخيار تثبيت آجل (↑↓ للتحريك، أدخل للاختيار، ^C للخروج). يعرض تدفق الإلغاء قسم Detected فقط. +- **عملاء متعددة مكتشفة** في تشغيل غير تفاعلي (CI، لا TTY) — يثبت لجميع العملاء المكتشفة بدون فور. +- **لم يتم اكتشاف أي** — ينخفض إلى `claude`، مع تحذير بأنه لم يتم العثور على ثنائي وكيل في PATH؛ أمر الخطاف لا يزال مكتوباً بحيث ينشط بمجرد تثبيت واحد. -يمكنك تحرير `policies-config.json` مباشرة في أي وقت؛ تصبح التغييرات فعالة فوراً في حدث hook التالي بدون الحاجة إلى إعادة تشغيل. +يمكنك تحرير `policies-config.json` مباشرة في أي وقت؛ التغييرات تصبح نافذة فوراً في حدث الخطاف التالي بدون حاجة إلى إعادة تشغيل. --- -## مثال: تكوين على مستوى المشروع مع قيم افتراضية الفريق +## مثال: إعدادات على مستوى المشروع مع إعدادات افتراضية للفريق -قم بإرسال `.failproofai/policies-config.json` إلى المستودع: +التزم `.failproofai/policies-config.json` بمستودعك: ```json { @@ -246,4 +248,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi gem } ``` -يمكن لكل مطور بعد ذلك إنشاء `.failproofai/policies-config.local.json` (مضاف لـ gitignore) للتجاوزات الشخصية دون التأثير على زملاء الفريق. \ No newline at end of file +يمكن لكل مطور بعد ذلك إنشاء `.failproofai/policies-config.local.json` (مستبعد من git) لتجاوزات شخصية بدون التأثير على زملائك. \ No newline at end of file diff --git a/docs/ar/custom-policies.mdx b/docs/ar/custom-policies.mdx index ab0bf867..cb5f7749 100644 --- a/docs/ar/custom-policies.mdx +++ b/docs/ar/custom-policies.mdx @@ -1,11 +1,10 @@ --- ---- title: السياسات المخصصة -description: "اكتب سياساتك الخاصة في JavaScript - فرض الاتفاقيات والوقاية من الانجراف واكتشاف الأعطال والتكامل مع الأنظمة الخارجية" +description: "اكتب سياساتك الخاصة في JavaScript - فرض الاتفاقيات، منع الانجراف، كشف الأعطال، التكامل مع الأنظمة الخارجية" icon: code --- -تتيح لك السياسات المخصصة كتابة قواعد لأي سلوك وكيل: فرض اتفاقيات المشروع والوقاية من الانجراف وحجب العمليات المدمرة واكتشاف الوكلاء المحتجزين أو التكامل مع Slack وسير عمل الموافقة والمزيد. تستخدم نفس نظام أحداث الخطاف وقرارات `allow` و `deny` و `instruct` مثل السياسات المدمجة. +تتيح لك السياسات المخصصة كتابة قواعد لأي سلوك وكيل: فرض اتفاقيات المشروع، منع الانجراف، إغلاق العمليات المدمرة، كشف الوكلاء العالقين، أو التكامل مع Slack وسير عمل الموافقة وغير ذلك. تستخدم نفس نظام أحداث الخطاف وقرارات `allow` و `deny` و `instruct` التي تستخدمها السياسات المدمجة. --- @@ -30,7 +29,7 @@ customPolicies.add({ }); ``` -ثبّتها: +قم بتثبيتها: ```bash failproofai policies --install --custom ./my-policies.js @@ -42,56 +41,56 @@ failproofai policies --install --custom ./my-policies.js ### الخيار 1: المستند على الاتفاقية (موصى به) -انقل ملفات `*policies.{js,mjs,ts}` إلى `.failproofai/policies/` وسيتم تحميلها تلقائياً — بدون حاجة إلى علامات أو تغييرات في الإعدادات. يعمل هذا مثل git hooks: انقل ملف، ويعمل فقط. +ضع ملفات `*policies.{js,mjs,ts}` في `.failproofai/policies/` وسيتم تحميلها تلقائياً — لا تحتاج إلى أعلام أو تغييرات إعدادات. يعمل هذا مثل 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}`؛ يتم تجاهل الملفات الأخرى +**كيف يعمل:** +- يتم فحص كلا المديرين (الدمج — وليس first-scope-wins) +- يتم تحميل الملفات أبجدياً ضمن كل دليل. استخدم البادئة `01-` و `02-` للتحكم في الترتيب +- يتم تحميل الملفات التي تطابق `*policies.{js,mjs,ts}` فقط؛ يتم تجاهل الملفات الأخرى - يتم تحميل كل ملف بشكل مستقل (fail-open لكل ملف) -- يعمل إلى جانب السياسات المخصصة والمدمجة الواضحة `--custom` +- يعمل جنباً إلى جنب مع السياسات الصريحة `--custom` والسياسات المدمجة -سياسات الاتفاقية هي أسهل طريقة لبناء معيار جودة لمؤسستك. التزم `.failproofai/policies/` في git وكل عضو في الفريق يحصل على نفس القواعد تلقائياً — لا حاجة إلى إعدادات لكل مطور. مع اكتشاف فريقك لأنماط الفشل الجديدة، أضف سياسة وادفع. بمرور الوقت، تصبح هذه معيار جودة حي يتحسن باستمرار مع كل مساهمة. +سياسات الاتفاقية هي الطريقة الأسهل لبناء معيار جودة لمؤسستك. التزم `.failproofai/policies/` إلى git وكل عضو في الفريق يحصل على نفس القواعد تلقائياً — لا حاجة لإعداد لكل مطور. مع اكتشاف فريقك لأنماط فشل جديدة، أضف سياسة وادفع. بمرور الوقت تصبح هذه معيار جودة حي يتحسن باستمرار مع كل مساهمة. ### الخيار 2: مسار الملف الصريح ```bash -# التثبيت بملف سياسات مخصص +# التثبيت مع ملف سياسات مخصص failproofai policies --install --custom ./my-policies.js -# استبدل مسار ملف السياسات +# استبدال مسار ملف السياسات failproofai policies --install --custom ./new-policies.js # إزالة مسار السياسات المخصصة من الإعدادات failproofai policies --uninstall --custom ``` -يتم تخزين المسار المطلق المحل في `policies-config.json` كـ `customPoliciesPath`. يتم تحميل الملف بشكل جديد في كل حدث خطاف — لا يوجد تخزين مؤقت بين الأحداث. +يتم تخزين المسار المطلق الذي تم حله في `policies-config.json` باسم `customPoliciesPath`. يتم تحميل الملف بشكل جديد في كل حدث خطاف - لا يوجد caching بين الأحداث. -### استخدام الاثنين معاً +### استخدام كليهما معاً -يمكن للسياسات الاتفاقية والملف `--custom` الصريح أن يتعايشوا. ترتيب التحميل: +يمكن للسياسات المستندة على الاتفاقية والملف الصريح `--custom` أن يتعايشا. ترتيب التحميل: -1. ملف `customPoliciesPath` الصريح (إذا تم تكوينه) -2. ملفات اتفاقية المشروع (`{cwd}/.failproofai/policies/`، أبجدياً) -3. ملفات اتفاقية المستخدم (`~/.failproofai/policies/`، أبجدياً) +1. ملف `customPoliciesPath` الصريح (إن تم تكوينه) +2. ملفات اتفاقية المشروع (`{cwd}/.failproofai/policies/`، أبجدي) +3. ملفات اتفاقية المستخدم (`~/.failproofai/policies/`، أبجدي) --- -## واجهة برمجية التطبيقات +## API -### استيراد +### الاستيراد ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -99,45 +98,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()` | السماح بالعملية بصمت | الإجراء آمن، لا حاجة إلى رسالة | -| `deny(message)` | حجب العملية | لا يجب على الوكيل اتخاذ هذا الإجراء | -| `instruct(message)` | إضافة السياق دون الحجب | إعطاء الوكيل سياق إضافي للبقاء على المسار | +| `allow()` | السماح بالعملية بصمت | الإجراء آمن، لا حاجة لرسالة | +| `deny(message)` | حظر العملية | يجب ألا يتخذ الوكيل هذا الإجراء | +| `instruct(message)` | إضافة سياق بدون حظر | إعطاء الوكيل سياقاً إضافياً للبقاء على المسار | -`deny(message)` - تظهر الرسالة في Claude مسبوقة بـ `"Blocked by failproofai:"`. يقطع `deny` واحد كل التقييم الإضافي. +`deny(message)` - تظهر الرسالة أمام Claude مع البادئة `Blocked by failproofai:`. رفض واحد يختصر كل التقييم الإضافي. -`instruct(message)` - يتم إضافة الرسالة إلى سياق Claude للاستدعاء الأداة الحالي. يتم تجميع جميع رسائل `instruct` وتسليمها معاً. +`instruct(message)` - يتم إلحاق الرسالة بسياق Claude لاستدعاء الأداة الحالي. يتم تجميع جميع رسائل `instruct` وتسليمها معاً. -يمكنك إضافة إرشادات إضافية إلى أي رسالة `deny` أو `instruct` بإضافة حقل `hint` في `policyParams` — لا حاجة إلى تغيير الكود. يعمل هذا مع السياسات المخصصة (`custom/`) واتفاقية المشروع (`.failproofai-project/`) واتفاقية المستخدم (`.failproofai-user/`) أيضاً. انظر [Configuration → hint](/ar/configuration#hint-cross-cutting) للتفاصيل. +يمكنك إلحاق إرشادات إضافية برسالة `deny` أو `instruct` بإضافة حقل `hint` في `policyParams` — لا حاجة لتغيير الكود. يعمل هذا للسياسات المخصصة (`custom/`)، واتفاقية المشروع (`.failproofai-project/`)، واتفاقية المستخدم (`.failproofai-user/`) أيضاً. انظر [التكوين → hint](/ar/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 بأن كل شيء أخضر -- **شروحات 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 +159,27 @@ customPolicies.add({ | الحقل | النوع | الوصف | |-------|------|-------------| -| `eventType` | `string` | `"PreToolUse"`، `"PostToolUse"`، `"Notification"`، `"Stop"` | -| `toolName` | `string \| undefined` | الأداة التي يتم استدعاؤها (على سبيل المثال `"Bash"`، `"Write"`، `"Read"`) | +| `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` | الحقل | النوع | الوصف | |-------|------|-------------| -| `sessionId` | `string` | معرف جلسة Claude Code | -| `cwd` | `string` | دليل العمل لجلسة Claude Code | -| `transcriptPath` | `string` | مسار ملف نسخة JSONL للجلسة | +| `sessionId` | `string` | معرّف جلسة Claude Code | +| `cwd` | `string` | مجلد العمل لجلسة Claude Code | +| `transcriptPath` | `string` | مسار ملف النسخ الكاملة JSONL للجلسة | ### أنواع الأحداث | الحدث | متى يتم تشغيله | محتويات `toolInput` | |-------|--------------|----------------------| -| `PreToolUse` | قبل أن يقوم Claude بتشغيل أداة | إدخال الأداة (على سبيل المثال `{ command: "..." }` لـ Bash) | +| `PreToolUse` | قبل تشغيل Claude لأداة | إدخال الأداة (مثل `{ command: "..." }` لـ Bash) | | `PostToolUse` | بعد اكتمال أداة | إدخال الأداة + `tool_result` (الإخراج) | -| `Notification` | عندما يرسل Claude إخطار | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - يجب أن تعيد الخطافات دائماً `allow()`، ولا يمكنها حجب الإخطارات | +| `Notification` | عندما يرسل Claude إشعاراً | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - يجب أن تُرجع الخطافات دائماً `allow()`، لا يمكنها حظر الإشعارات | | `Stop` | عند انتهاء جلسة Claude | فارغ | --- @@ -191,18 +190,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 @@ -219,46 +218,46 @@ customPolicies.add({ }); ``` -يتم حل جميع الاستيرادات النسبية القابلة للوصول من ملف الإدخال. يتم تنفيذ هذا بإعادة كتابة استيرادات `from "failproofai"` إلى مسار التوزيع الفعلي وإنشاء ملفات `.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) => { - // Only fires when the session ends - // ctx.session.transcriptPath contains the full session log + // يتم التشغيل فقط عند انتهاء الجلسة + // ctx.session.transcriptPath يحتوي على سجل الجلسة الكامل return allow(); }, }); ``` -حذف `match` بالكامل للتشغيل على كل نوع حدث. +احذف `match` بالكامل للتشغيل على كل نوع حدث. --- ## معالجة الأخطاء وأنماط الفشل -السياسات المخصصة **fail-open**: الأخطاء لا تحجب السياسات المدمجة أو تعطل معالج الخطاف. +السياسات المخصصة **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 @@ -273,7 +272,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", @@ -286,7 +285,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", @@ -301,7 +300,7 @@ customPolicies.add({ }, }); -// Prevent unplanned dependency changes during freeze +// منع تغييرات المكتبات غير المخطط لها أثناء فترة التجميد customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -328,10 +327,10 @@ export { customPolicies }; | الملف | المحتويات | |------|----------| -| `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` | سياسات سير عمل مستندة على الاتفاقية (تذكيرات الاختبار، ملفات التدقيق الكتابة) | ### استخدام أمثلة الملفات الصريحة @@ -342,13 +341,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/ar/dashboard.mdx b/docs/ar/dashboard.mdx index 2082cff2..fc2633a9 100644 --- a/docs/ar/dashboard.mdx +++ b/docs/ar/dashboard.mdx @@ -1,23 +1,22 @@ --- ---- -title: لوحة المعلومات -description: "مراقبة جلسات الوكيل، مراجعة استدعاءات الأدوات، وإدارة السياسات" +title: لوحة التحكم +description: "راقب جلسات الوكيل، واستعرض استدعاءات الأدوات، وأدر السياسات" icon: chart-line --- -لوحة معلومات failproofai هي تطبيق ويب محلي لمراقبة جلسات وكيل الذكاء الاصطناعي الخاص بك وإدارة السياسات. انظر إلى ما فعله وكلاؤك بينما كنت بعيداً. +لوحة التحكم failproofai عبارة عن تطبيق ويب محلي لمراقبة جلسات وكيل الذكاء الاصطناعي الخاص بك وإدارة السياسات. اطّلع على ما فعله وكلاؤك أثناء غيابك. --- -## بدء لوحة المعلومات +## بدء لوحة التحكم ```bash failproofai ``` -يفتح في `http://localhost:8020`. +يتم فتحها في `http://localhost:8020`. -تقرأ لوحة المعلومات مباشرة من نظام الملفات - مجلدات مشاريع Claude Code وملفات إعدادات failproofai. لا يتم كتابة أي شيء إلى خدمة بعيدة. +تقرأ لوحة التحكم مباشرة من نظام الملفات - مجلدات مشاريع Claude Code وملفات إعدادات failproofai. لا يتم كتابة أي شيء إلى خدمة بعيدة. --- @@ -25,81 +24,81 @@ failproofai ### المشاريع -تسرد جميع مشاريع Claude Code و OpenAI Codex و GitHub Copilot CLI _(beta)_ و Cursor Agent _(beta)_ و OpenCode _(beta)_ و Pi _(beta)_ و Gemini CLI _(beta)_ الموجودة على جهازك. يتم اكتشاف مشاريع 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` من السجل الأول لكل جلسة; يتم اكتشاف مشاريع Gemini CLI بفحص `~/.gemini/tmp//chats/session--.jsonl` (قابل للتكوين عبر `GEMINI_SESSIONS_DIR`) واسترجاع cwd الأساسي من علامة نصية `.project_root` المجاورة. يتم عرض المشروع الذي تم استخدامه بواسطة عدة CLIs كصف واحد مع جميع الشارات المطابقة. استخدم القائمة المنسدلة **CLI** أعلى الجدول للتصفية حسب CLI وكيل معين; يحافظ الرابط على اختيارك كـ `?cli=claude|codex|copilot|cursor|opencode|pi|gemini`. +يسرد جميع مشاريع Claude Code و OpenAI Codex و GitHub Copilot CLI _(إصدار تجريبي)_ و Cursor Agent _(إصدار تجريبي)_ و OpenCode _(إصدار تجريبي)_ و Pi _(إصدار تجريبي)_ و Gemini CLI _(إصدار تجريبي)_ و Hermes الموجودة على جهازك. يتم اكتشاف مشاريع 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` من السجل الأول من كل جلسة; يتم اكتشاف مشاريع Gemini CLI بمسح `~/.gemini/tmp//chats/session--.jsonl` (قابل للتكوين عبر `GEMINI_SESSIONS_DIR`) واسترجاع cwd القانوني من علامة النص المجاورة `.project_root`; تتم قراءة جلسات بوابة Hermes مباشرة من متجرها SQLite في `~/.hermes/state.db` (قابل للتكوين عبر `HERMES_DB_PATH`) وتجميعها في مشاريع `hermes-` حسب `source` (Slack/Telegram/cli/cron — جلسات البوابة لا تحتوي على cwd). يتم عرض المشروع الذي تم استخدامه بواسطة عدة CLIs كصف واحد مع جميع الشارات المطابقة. استخدم القائمة المنسدلة **CLI** فوق الجدول للتصفية حسب CLI وكيل معين; يحافظ عنوان URL على اختيارك كـ `?cli=claude|codex|copilot|cursor|opencode|pi|gemini|hermes`. يعرض كل مشروع: -- اسم المشروع (المشتق من مسار المجلد) -- شارة CLI — `Claude Code` (برتقالي)، `OpenAI Codex` (بنفسجي)، `GitHub Copilot` (أزرق)، `Cursor Agent` (أخضر، `OpenCode` (كهرماني)، `Pi` (وردي)، و/أو `Gemini CLI` (سماوي) -- تاريخ نشاط الجلسة الأخيرة +- اسم المشروع (مشتق من مسار المجلد) +- شارة CLI — `Claude Code` (برتقالي)، `OpenAI Codex` (بنفسجي)، `GitHub Copilot` (أزرق)، `Cursor Agent` (زمردي)، `OpenCode` (كهرماني)، `Pi` (وردي)، `Gemini CLI` (سماوي)، و/أو `Hermes` (نيلي) +- تاريخ آخر نشاط جلسة -انقر فوق مشروع لرؤية جلساته. +انقر على مشروع لمشاهدة جلساته. ### الجلسات -تسرد جميع الجلسات ضمن مشروع. تعرض كل جلسة: +يسرد جميع الجلسات ضمن مشروع. تعرض كل جلسة: - معرف الجلسة -- الطوابع الزمنية للبداية والنهاية +- طوابع زمنية البدء والنهاية - عدد استدعاءات الأدوات -- عدد نشاط hook (السياسات التي تم تفعيلها) +- عدد نشاط الخطاف (السياسات التي تم تشغيلها) -استخدم مرشح نطاق التاريخ والبحث عن معرف الجلسة لتضييق القائمة. يتم تقسيم الجلسات إلى صفحات. +استخدم مرشح نطاق التاريخ وبحث معرف الجلسة لتضييق القائمة. يتم تقسيم الجلسات على صفحات. -انقر فوق جلسة لفتح عارض الجلسة. +انقر على جلسة لفتح عارض الجلسة. ### عارض الجلسة -يجيب عارض الجلسة على السؤال الأساسي للوكلاء المستقلين: ماذا فعل الوكيل، وهل ظل على المسار الصحيح؟ تشير شارة CLI بجانب الرأس إلى ما إذا كانت الجلسة نسخة Claude Code أو OpenAI Codex أو GitHub Copilot CLI أو Cursor Agent أو OpenCode أو Pi أو Gemini CLI. يعرض خطة زمنية لكل ما حدث في جلسة: +يجيب عارض الجلسة على السؤال الأساسي للوكلاء المستقلين: ماذا فعل الوكيل، وهل بقي على المسار الصحيح؟ تشير شارة CLI بجانب الرأس إلى ما إذا كانت الجلسة نسخة Claude Code أو OpenAI Codex أو GitHub Copilot CLI أو Cursor Agent أو OpenCode أو Pi أو Gemini CLI أو Hermes. يعرض جدول زمني لكل ما حدث في جلسة: -- **الرسائل** - الردود النصية من Claude ومحفوزات المستخدم -- **استدعاءات الأدوات** - كل أداة استدعاها Claude، مع إدخالاتها ومخرجاتها -- **نشاط السياسة** - لكل استدعاء أداة، السياسات التي تم تفعيلها والقرار الذي أرجعته +- **الرسائل** - استجابات نصية من Claude ومحفزات المستخدم +- **استدعاءات الأدوات** - كل أداة استدعاها Claude، مع إدخالها وإخراجها +- **نشاط السياسة** - لكل استدعاء أداة، السياسات التي تم تشغيلها والقرار الذي أرجعته -يعرض شريط الإحصائيات في الأعلى مدة الجلسة، إجمالي استدعاءات الأدوات، وملخص قرارات hook (عدادات السماح / الرفض / الإرشاد). +تعرض شريط الإحصائيات في الأعلى مدة الجلسة وإجمالي استدعاءات الأدوات وملخص قرارات الخطاف (عدد السماح/الرفض/التعليمات). -انقر على زر **تنزيل السجلات** لتصدير الجلسة. بالنسبة لجلسات Claude Code و Codex و Copilot و Cursor و Pi و Gemini، تحصل على نسخة النص الأصلية على القرص بالكامل; بالنسبة لـ OpenCode (التي تكون جلساتها في SQLite، وليس على القرص) تحصل على وثيقة JSON تعكس جداول `session` / `messages` / `parts` الأساسية. +انقر على زر **تحميل السجلات** لتصدير الجلسة. بالنسبة لجلسات Claude Code و Codex و Copilot و Cursor و Pi و Gemini، تحصل على نص JSONL الأصلي على القرص بالكامل; بالنسبة لـ OpenCode (التي تعيش جلساتها في SQLite وليس على القرص) تحصل على وثيقة JSON تعكس جداول `session` / `messages` / `parts` الأساسية. ### التدقيق -تقرير بطابع شخصي عن كيفية تصرف وكيلك فعلياً عبر الجلسات الماضية. يقوم بنفس المسح الذي يقوم به CLI `failproofai audit` لكن يعرضه كملصق واحد على الشاشة قابل للمشاركة + أربعة أقسام تحت الطية: +تقرير مدفوع بالشخصية حول كيفية تصرف وكيلك بالفعل عبر الجلسات السابقة. يشغل نفس المسح مثل CLI `failproofai audit` لكن يعرضه كملصق على شاشة واحدة قابل للمشاركة + أربعة أقسام تحت الطي: -1. **الملصق** — يملأ منفذ العرض الأول. منطقة التقاط PNG مكتفية ذاتياً مع علامة failproof_ai · تسمية التدقيق · فهرس النمط الأصلي (`№ NN من 08`) + تاريخ التدقيق · نقطة عددية (0–100) + حبة تصنيف مئوي (`أفضل 15%`) · اسم النمط الأصلي (أحد `المتفائل` أو `الرعديد` أو `المستكشف` أو `سمك الذهب` أو `المهندس المريب` أو `بناء الدقة` أو `المطرقة` أو `الشبح`) + شريط الكلمات الثلاث · `// فقط N% من الوكلاء لديهم هذا النمط الأصلي` سطر الندرة · بلاط sigil 8×8 بكسل · `تدقيق لك → failproof.ai` تذييل. ثلاثة أزرار مشاركة خارج مربع الالتقاط: `انشر نمطك الأصلي` (X intent)، `مشاركة على linkedin`، `تنزيل الملصق`. يتم تشغيل الالتقاط عبر `html-to-image` بحيث يطابق PNG العرض على الشاشة بكسل تلو الآخر (حدود مسسحة، قناع شعار SVG، تدرجات، مقاييس الخط — كل شيء محفوظ). -2. **نقاط القوة** — قائمة صفوف هادئة من السلوكيات التي يقوم بها وكيلك بالفعل بشكل صحيح، مستمدة من بيانات التدقيق المباشر (معدل استدعاء أداة نظيف، بدون دفع مباشر إلى main، تسريب بيانات اعتماد صفري، عدم حدوث عواصف إعادة محاولة) — يتم عرض كل منها فقط عندما تكون السياسة ذات الصلة نظيفة عبر نافذة التدقيق. -3. **المميزات الغريبة** — جدول ما تسرب، مرتب حسب الشدة: `عندما · ما تسرب + السياسة التي كانت ستلتقطه · حبة الشدة · رؤية`، حيث تقرأ التكرار `جديد` (مرة واحدة)، `N× رؤية` (2–9 مرات)، أو `متكرر` (10+). -4. **كيفية التحسن** — قائمة صفوف هادئة، واحد لكل سياسة موصى بها: اسم السياسة بالأبيض، وصف سطر واحد، أمر التثبيت + زر النسخ على الجانب الأيمن. يقرأ رأس القسم `تفعيل الكل N → مشروع · ` (النقطة التي ستصل إليها مع تطبيق كل إصلاح)، وزر `[تثبيت الكل]` الخاص به ينسخ أمر `failproofai policy add a b c …` المدمج لكل سياسة موصى بها. -5. **عودة بشكل أفضل** — بطاقتان جنباً إلى جنب. اليسار: ضبط تذكير (`3d` / `7d` / `14d` / `30d` منتقي الإيقاع; يستمر عبر `/api/auth/reminder` بعد المصادقة). اليمين: فتح مزايا failproof — `دعوة صديق` يفتح نافذة حوار تأخذ قائمة برسائل البريد الإلكتروني للأصدقاء المفصولة بفواصل/مسافات/أسطر جديدة (الحد الأقصى 10 لكل إرسال)، POSTs إلى `/api/audit/invite`، والتي تنقل إلى `POST /v0/invite` في خادم api. يرسل خادم api بريداً إلكترونياً واحداً لكل مستقبل من `invite@failproof.ai` مع إضافة المرسل بـ Cc وتعيين `Reply-To`، بحيث يرى المستقبل من دعاهم والمرسل يحصل على نسخة في صندوق البريد الخاص به. يتم توجيه المستخدمين المجهولين عبر `AuthDialog` أولاً بحيث تكون رسالة البريد الإلكتروني للمرسل معروفة قبل إرسال الدعوات. تحقيق الأحقية / الامتيازات هو المتابعة. +1. **الملصق** — يملأ أول عرض. منطقة PNG محكمة الإغلاق تحتوي على علامة failproof_ai + تسمية التدقيق · فهرس الأنماط (`№ NN من 08`) + تاريخ التدقيق · النقاط الرقمية (0–100) + حبة تصنيف النسبة المئوية (`أفضل 15%`) · اسم النمط (واحد من `المتفائل` أو `رجل الفوضى` أو `المستكشف` أو `سمك الذاكرة القصيرة` أو `معماري بجنون الارتياب` أو `بناء الدقة` أو `المطرقة` أو `الشبح`) + شريط 3 كلمات · `// فقط N% من الوكلاء لديهم هذا النمط` خط الندرة · بلاط sigil بحجم 8×8 بكسل · تذييل `قم بتدقيق ملكك → failproof.ai`. ثلاث أزرار مشاركة تجلس خارج صندوق الالتقاط: `شارك نمطك` (نية X)، `شارك على linkedin`، `تحميل الملصق`. يتم الالتقاط من خلال `html-to-image` لذا فإن PNG يطابق الرسم على الشاشة بكل بكسل (الحدود المقسومة، قناع شعار SVG، التدرجات، مقاييس الخط — كل شيء محفوظ). +2. **نقاط القوة** — قائمة صفوف هادئة من السلوكيات التي يفعلها وكيلك بالفعل بشكل صحيح، مشتقة من بيانات التدقيق المباشرة (معدل استدعاء أداة نظيف، لا دفع مباشر إلى main، صفر تسريب بيانات اعتماد، صفر عواصف إعادة محاولة) — يتم طرح كل واحد فقط عندما تحتوي السياسة ذات الصلة على سجل نظيف عبر نافذة التدقيق. +3. **الفضول** — جدول ما تسلل، مصنف حسب الشدة: `عندما · ما تسلل + السياسة التي كانت ستقبضه · حبة الشدة · مرئي`، حيث تقرأ التكرار `جديد` (مرة واحدة)، `مرئي N×` (2–9 مرات)، أو `متكرر` (10+). +4. **كيفية التحسن** — قائمة صفوف هادئة، واحدة لكل سياسة موصى بها: اسم السياسة بالأبيض، وصف سطر واحد، أمر التثبيت + زر النسخ على الجانب الأيمن. يقرأ رأس القسم `تفعيل الكل N → النتيجة المتوقعة · ` (النتيجة التي ستصل إليها مع تطبيق كل إصلاح)، وزر `[تثبيت الكل]` الخاص به ينسخ أمر `failproofai policy add a b c …` المدمج لكل سياسة موصى بها. +5. **عودة أفضل** — بطاقتان جنباً إلى جنب. اليسار: اضبط تذكيراً (منتقي إيقاع `3d` / `7d` / `14d` / `30d`; يستمر عبر `/api/auth/reminder` بمجرد المصادقة). اليمين: افتح مزايا failproof — `دعوة صديق` يفتح نافذة منفثقة تأخذ قائمة بريد إلكتروني للأصدقاء مفصولة بفاصلة/مسافة/سطر جديد (بحد أقصى 10 لكل إرسال)، POSTs إلى `/api/audit/invite`، التي تعيد إلى `POST /v0/invite` من خادم api. يرسل خادم api رسالة بريد إلكترونية واحدة لكل مستلم من `invite@failproof.ai` مع مرسل Cc وتعيين `Reply-To`، لذا يرى المستلم من دعاك والمرسل يحصل على نسخة في صندوق الوارد الخاص به. يتم توجيه المستخدمين المجهولين عبر `AuthDialog` أولاً بحيث يكون بريد المرسل معروفاً قبل إرسال الدعوات. تحقيق الحقوق/المزايا متابعة. -مدفوع بـ `failproofai audit` runtime — انظر [Audit CLI](/ar/cli/audit) لمحرك المسح الأساسي والأعلام المدعومة وثوابت الذاكرة المؤقتة لكل نسخة. تخزن لوحة المعلومات مؤقتاً أحدث نتيجة في `~/.failproofai/audit-dashboard.json` (الوضع `0600`، فتحة واحدة، تستبدل التشغيلات الجديدة) بحيث تكون الزيارات اللاحقة فورية; **يتم رفض كل من ذاكرة التخزين المؤقت لكل نسخة ونتيجة كاملة عند القراءة بمجرد أن تصبح أقدم من 7 أيام** بحيث لا تخدم لوحة المعلومات أبداً بصمت نتيجة بعمر أسبوع — بعد انتهاء الصلاحية `/audit` يسقط إلى حالته الفارغة ويطالب بتشغيل جديد. النقر على `[ إعادة تدقيق الآن ]` بالقرب من أسفل التقرير POSTs `/api/audit/run` مع `noCache: true` — إعادة التدقيق تجاوز ذاكرة التخزين المؤقت لكل نسخة وتعيد مسح كل نسخة من البداية بدلاً من إرجاع النتيجة المخزنة بصمت — ولوحة المعلومات تستطلع `/api/audit/status` عند 1Hz حتى انتهاء التشغيل; شريط تقدم وردي لزج يدبس إلى أعلى viewport أثناء التشغيل مع مؤقت انقضى، وتبديل النتيجة الطازجة في المكان عند النجاح (بدون إعادة تحميل كاملة للصفحة; إعادة تدقيق فاشلة تترك التقرير السابق سليماً). عند الفشل، يتحول الشريط إلى اللون الأحمر مع نسخ مفتاح من `RerunError.kind` (`timeout` / `network` / `post_failed`). تتم سطح الحالة الفارغة (بدون ذاكرة تخزين مؤقت أو منتهية الصلاحية) والحالة الخالية من الجلسات (توجد ذاكرة تخزين مؤقت ولكن لم يجد المسح نسخ) بشكل منفصل. +مدفوعة بواسطة وقت تشغيل `failproofai audit` — انظر [Audit CLI](/ar/cli/audit) لمحرك المسح الأساسي والأعلام المدعومة وثوابت ذاكرة التخزين المؤقت لكل نص. تخزن لوحة التحكم أحدث نتيجة في `~/.failproofai/audit-dashboard.json` (الوضع `0600`، فتحة واحدة، يؤدي التشغيل الجديد إلى الكتابة فوق) بحيث تكون الزيارات الثانية فورية; **يتم رفض كل من ذاكرة التخزين المؤقت لكل نص والنتيجة الكاملة عند القراءة بمجرد تجاوزها 7 أيام** لذا لا تقدم لوحة التحكم أبداً نتيجة قديمة بصمت — بعد انتهاء TTL `/audit` يسقط إلى حالة فارغة ويطالب بتشغيل جديد. ينقر `[ إعادة تدقيق الآن ]` بالقرب من أسفل التقرير على POST `/api/audit/run` مع `noCache: true` — إعادة التدقيق تتجاوز ذاكرة التخزين المؤقت لكل نص وتعيد مسح كل نص من البداية بدلاً من إرجاع النتيجة المخزنة مؤقتاً بصمت — وتستقصي لوحة التحكم `/api/audit/status` بمعدل 1Hz حتى ينتهي التشغيل; شريط تقدم وردي لاصق يثبت في أعلى viewport أثناء التشغيل مع مؤقت الوقت المنقضي، والنتيجة الجديدة تحل محل مكانها عند النجاح (لا إعادة تحميل للصفحة الكاملة; إعادة تدقيق فاشلة تترك التقرير السابق سليماً). في حالة الفشل، يتحول الشريط إلى اللون الأحمر مع نسخة مفصولة عن `RerunError.kind` (`timeout` / `network` / `post_failed`). الحالة الفارغة (لا ذاكرة تخزين مؤقت أو منتهية الصلاحية) وحالة الصفر الجلسات (توجد ذاكرة التخزين المؤقت ولكن المسح لم يجد نصوصاً) يتم عرضهما بشكل منفصل. ### السياسات -صفحة بلسانين لإدارة السياسات ومراجعة النشاط. +صفحة بتبويبين لإدارة السياسات ومراجعة النشاط. - - - حدد متعدد مع CLIs التي يحمي failproofai من لوحة واحدة — Claude Code و OpenAI Codex و GitHub Copilot و Cursor Agent و OpenCode و Pi و Gemini CLI كلها لها صف يحتوي على حالة التثبيت (`Active` / `Detected` / `Inactive`)، مسار إعدادات نطاق المستخدم، وضفة مميزة بعلامة تجارية. تحقق من مربعات CLIs التي تريدها أو ألغ تحديد مربع الاختيار وانقر فوق `تطبيق التغييرات` لتثبيت/إلغاء تثبيت الفارق في خطوة واحدة. CLIs التي يتم الكشف عن ملف تنفيذي الخاص بها على PATH يتم فحصه مسبقاً. - - بدّل السياسات الفردية على أو إيقاف بنقرة واحدة (يكتب إلى `~/.failproofai/policies-config.json` — مشترك في كل CLI مثبت) - - توسيع سياسة لتكوين معاملات (للسياسات التي تدعم `policyParams`) - - تعيين مسار ملف سياسات مخصص + + - حدد بطاقة متعددة الاختيار CLI الذي يحمي failproofai من لوحة واحدة — Claude Code و OpenAI Codex و GitHub Copilot و Cursor Agent و OpenCode و Pi و Gemini CLI و Hermes لها جميعاً صف مع حالة التثبيت (`نشط` / `مكتشف` / `غير نشط`)، مسار إعدادات نطاق المستخدم، وتمييز ملون العلامة التجارية. قم بتحديد أو إلغاء تحديد CLIs التي تريد وانقر `تطبيق التغييرات` لتثبيت/إلغاء تثبيت الفرق في خطوة واحدة. CLIs التي تم اكتشاف ملفها الثنائي على PATH يتم تحديدها مسبقاً. + - بدّل السياسات الفردية على أو بيقاف مع نقرة واحدة (يكتب إلى `~/.failproofai/policies-config.json` — مشترك عبر كل CLI مثبت) + - قم بتوسيع سياسة لتكوين معاملات (للسياسات التي تدعم `policyParams`) + - عيّن مسار ملف سياسات مخصص - - - سجل مخزن بالكامل في صفحات لكل حدث hook تم تشغيله عبر جميع الجلسات - - تصفية حسب القرار ونوع الحدث و CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Gemini CLI _(beta)_) واسم السياسة أو معرف الجلسة - - يعرض كل صف: الطابع الزمني، اسم السياسة، القرار، شارة CLI (برتقالي = Claude Code، بنفسجي = OpenAI Codex، أزرق = GitHub Copilot، أخضر = Cursor Agent، كهرماني = OpenCode، وردي = Pi، سماوي = Gemini CLI)، اسم الأداة، معرف الجلسة، والسبب لقرارات الرفض/الإرشاد - - انقر فوق معرف الجلسة لفتح نسختها — يكتشف العارض تلقائياً أي 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`، Gemini CLI `~/.gemini/tmp//chats/.jsonl`) ويعرض شارة CLI المطابقة في الرأس + + - السجل الكامل المقسم على صفحات لكل حدث خطاف تم تشغيله عبر جميع الجلسات + - التصفية حسب القرار ونوع الحدث و CLI (Claude Code / OpenAI Codex / GitHub Copilot _(إصدار تجريبي)_ / Cursor Agent _(إصدار تجريبي)_ / OpenCode _(إصدار تجريبي)_ / Pi _(إصدار تجريبي)_ / Gemini CLI _(إصدار تجريبي)_ / Hermes) واسم السياسة أو معرف الجلسة + - يعرض كل صف: الطابع الزمني واسم السياسة والقرار وشارة CLI (برتقالي = Claude Code، بنفسجي = OpenAI Codex، أزرق = GitHub Copilot، زمردي = Cursor Agent، كهرماني = OpenCode، وردي = Pi، سماوي = Gemini CLI، نيلي = Hermes) واسم الأداة ومعرف الجلسة وسبب قرارات الرفض/التعليمات + - انقر على معرف جلسة لفتح النص الخاص به — الكاشف التلقائي للعارض 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`، Gemini CLI `~/.gemini/tmp//chats/.jsonl`، Hermes `~/.hermes/state.db`) ويعرض شارة CLI المطابقة في الرأس --- -## الإنعاش التلقائي +## التحديث التلقائي -تحتوي لوحة المعلومات على مبدل إنعاش تلقائي في التنقل العلوي. عند تفعيله، تنعش الصفحة الحالية بشكل دوري لعرض جلسات جديدة ونشاط سياسة جديدة عند ظهورها. ضروري لمراقبة جلسات وكيل مستقلة طويلة التشغيل. +تحتوي لوحة التحكم على مفتاح التحديث التلقائي في التنقل العلوي. عند التفعيل، يتم تحديث الصفحة الحالية بشكل دوري لإظهار جلسات جديدة ونشاط سياسة جديد وهو يظهر. ضروري لمراقبة جلسات الوكيل المستقل طويلة الأجل. --- ## تعطيل الصفحات -إذا كنت تحتاج فقط إلى بعض أجزاء لوحة المعلومات، اضبط `FAILPROOFAI_DISABLE_PAGES` على قائمة مفصولة بفواصل من أسماء الصفحات: +إذا كنت تحتاج فقط إلى بعض أجزاء لوحة التحكم، فاضبط `FAILPROOFAI_DISABLE_PAGES` على قائمة مفصولة بفواصل من أسماء الصفحات: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -111,7 +110,7 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## تكوين مسار المشاريع -بشكل افتراضي، تقرأ لوحة المعلومات من دليل مشاريع Claude Code القياسي. استبدله للإعدادات المخصصة: +بشكل افتراضي، تقرأ لوحة التحكم من دليل مشاريع Claude Code القياسي. تجاوزه للإعدادات المخصصة: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -121,19 +120,19 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## الوصول من مضيف غير محلي -عند تشغيل لوحة المعلومات في **وضع dev** (`npm run dev`) والوصول إليها من اسم مضيف بخلاف `localhost` - على سبيل المثال، مجال مخصص أو IP بعيدة أو URL موصولة — قد تظهر تحذير مثل: +عند تشغيل لوحة التحكم في **وضع التطوير** (`npm run dev`) والوصول إليها من hostname بخلاف `localhost` - على سبيل المثال، نطاق مخصص أو IP بعيد أو عنوان URL يتم نفقه - قد تراى تحذيراً مثل: ```text -⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". +⚠ طلب cross-origin محظور لمورد Next.js dev /_next/webpack-hmr من dashboard.example.com. ``` -هذا هو Next.js يمنع الوصول عبر الأصول إلى مورد HMR dev الخاص به (إعادة تحميل الوحدة الساخنة)، وهي ميزة dev فقط. للسماح لمضيفك، استخدم العلم `--allowed-origins`: +هذا هو Next.js الذي يحظر الوصول cross-origin إلى HMR (hot module reload) websocket، وهي ميزة dev فقط. للسماح بمضيفك، استخدم علم `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -لعدة مضيفات أو IPs، مرر قائمة مفصولة بفواصل: +لعدة مضيفين أو IPs، مرر قائمة مفصولة بفواصل: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 @@ -146,5 +145,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -هذا ينطبق فقط على وضع dev. عند تشغيل `failproofai` (وضع الإنتاج)، لا يوجد websocket HMR ولا مشكلة مورد dev عبر الأصول. +هذا ينطبق فقط على وضع التطوير. عند تشغيل `failproofai` (وضع الإنتاج)، لا يوجد HMR websocket ولا مشكلة مورد dev cross-origin. \ No newline at end of file diff --git a/docs/ar/examples.mdx b/docs/ar/examples.mdx index be3b889e..6de4fca3 100644 --- a/docs/ar/examples.mdx +++ b/docs/ar/examples.mdx @@ -1,16 +1,17 @@ --- +--- title: أمثلة description: "كيفية إعداد hooks لـ Claude Code و Agents SDK" icon: book-open --- -أمثلة جاهزة للاستخدام لسيناريوهات شائعة. يوضح كل منها كيفية التثبيت وما يمكن توقعه. +أمثلة جاهزة للاستخدام للسيناريوهات الشائعة. يوضح كل منها كيفية التثبيت وما يمكن توقعه. --- ## إعداد hooks لـ Claude Code -يتكامل Failproof AI مع Claude Code عبر [نظام hooks الخاص به](https://docs.anthropic.com/en/docs/claude-code/hooks). عند تشغيل `failproofai policies --install`، يسجل أوامر hook في ملف `settings.json` الخاص بـ Claude Code التي تُشغّل عند كل استدعاء أداة. +يتكامل Failproof AI مع Claude Code عبر [نظام hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). عند تشغيل `failproofai policies --install`، يسجل أوامر hook في `settings.json` الخاص بـ Claude Code التي تُشغَّل عند كل استدعاء أداة. @@ -28,14 +29,14 @@ icon: book-open cat ~/.claude/settings.json | grep failproofai ``` - يجب أن ترى إدخالات hook لأحداث `PreToolUse` و `PostToolUse` و `Notification` و `Stop`. + يجب أن تشاهد مدخلات hook لأحداث `PreToolUse`، `PostToolUse`، `Notification`، و `Stop`. ```bash claude ``` - تعمل السياسات الآن تلقائياً عند كل استدعاء أداة. جرب طلب Claude بتشغيل `sudo rm -rf /` - سيتم حظره. + تعمل السياسات تلقائياً عند كل استدعاء أداة. جرّب طلب Claude لتشغيل `sudo rm -rf /` - سيتم حجبه. @@ -52,7 +53,7 @@ icon: book-open ``` - مرر أوامر hook عند إنشاء عملية الوكيل. تُشغّل الـ hooks بنفس الطريقة كما في Claude Code - عبر JSON في stdin/stdout: + مرّر أوامر hook عند إنشاء عملية وكيلك. تُشغَّل hooks بنفس الطريقة كما هو الحال في Claude Code - عبر JSON على stdin/stdout: ```bash failproofai --hook PreToolUse # يُستدعى قبل كل أداة @@ -65,12 +66,12 @@ icon: book-open customPolicies.add({ name: "limit-to-project-dir", - description: "Keep the agent inside the project directory", + description: "ابقِ الوكيل داخل مجلد المشروع", match: { events: ["PreToolUse"] }, fn: async (ctx) => { const path = String(ctx.toolInput?.file_path ?? ""); if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) { - return deny("Agent is restricted to the project directory"); + return deny("الوكيل مقيد بمجلد المشروع"); } return allow(); }, @@ -86,51 +87,51 @@ icon: book-open --- -## حظر الأوامر المدمرة +## حجب الأوامر التدميرية -الإعداد الأكثر شيوعاً - منع الوكلاء من إلحاق الضرر الذي لا يمكن إرجاعه. +الإعداد الأكثر شيوعاً - منع الوكلاء من إلحاق الضرر الذي لا يمكن عكسه. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` -ما تفعله: -- `block-sudo` - يحظر جميع أوامر `sudo` -- `block-rm-rf` - يحظر حذف الملفات العودية -- `block-force-push` - يحظر `git push --force` -- `block-curl-pipe-sh` - يحظر توجيه النصوص البعيدة إلى shell +ما يفعله هذا: +- `block-sudo` - يحجب جميع أوامر `sudo` +- `block-rm-rf` - يحجب حذف الملفات العودي +- `block-force-push` - يحجب `git push --force` +- `block-curl-pipe-sh` - يحجب توجيه السكريبتات البعيدة إلى الـ shell --- -## منع تسرب الأسرار +## منع تسريب الأسرار -منع الوكلاء من رؤية أو تسرب بيانات اعتماد من مخرجات الأداة. +منع الوكلاء من رؤية أو تسريب بيانات الاعتماد في مخرجات الأداة. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -تُشغّل على `PostToolUse` - بعد تشغيل الأداة، تُنظّف المخرجات قبل أن يراها الوكيل. +تعمل هذه على `PostToolUse` - بعد تشغيل أداة، تقوم بتنظيف المخرجات قبل أن يراها الوكيل. --- -## الحصول على تنبيهات Slack عندما يحتاج الوكلاء إلى الاهتمام +## احصل على تنبيهات Slack عند احتياج الوكلاء إلى الاهتمام -استخدم hook الإشعار لإعادة توجيه تنبيهات عدم النشاط إلى Slack. +استخدم notification hook لإعادة توجيه تنبيهات عدم النشاط إلى Slack. ```javascript import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "slack-on-idle", - description: "Alert Slack when the agent is waiting for input", + description: "تنبيه Slack عندما يكون الوكيل في انتظار إدخال", match: { events: ["Notification"] }, fn: async (ctx) => { const webhookUrl = process.env.SLACK_WEBHOOK_URL; if (!webhookUrl) return allow(); - const message = String(ctx.payload?.message ?? "Agent is waiting"); - const project = ctx.session?.cwd ?? "unknown"; + const message = String(ctx.payload?.message ?? "الوكيل في انتظار"); + const project = ctx.session?.cwd ?? "غير معروف"; try { await fetch(webhookUrl, { @@ -142,7 +143,7 @@ customPolicies.add({ signal: AbortSignal.timeout(5000), }); } catch { - // never block the agent if Slack is unreachable + // لا تحجب الوكيل أبداً إذا كان Slack غير متاح } return allow(); @@ -150,7 +151,7 @@ customPolicies.add({ }); ``` -ثبته: +ثبّته: ```bash SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js @@ -158,7 +159,7 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c --- -## الحفاظ على الوكلاء على فرع معين +## إبقاء الوكلاء على فرع معين منع الوكلاء من تبديل الفروع أو الدفع إلى الفروع المحمية. @@ -167,13 +168,13 @@ import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "stay-on-branch", - description: "Prevent the agent from checking out other branches", + description: "منع الوكيل من التحقق من فروع أخرى", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); if (/git\s+checkout\s+(?!-b)/.test(cmd)) { - return deny("Stay on the current branch. Create a new branch with -b if needed."); + return deny("ابقَ على الفرع الحالي. أنشئ فرع جديد بـ -b إذا لزم الأمر."); } return allow(); }, @@ -182,7 +183,7 @@ customPolicies.add({ --- -## مطالبة الوكلاء بتشغيل الاختبارات قبل الالتزام +## اطلب الاختبارات قبل الالتزام ذكّر الوكلاء بتشغيل الاختبارات قبل الالتزام. @@ -191,13 +192,13 @@ import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "test-before-commit", - description: "Remind the agent to run tests before committing", + description: "تذكير الوكيل بتشغيل الاختبارات قبل الالتزام", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); if (/git\s+commit/.test(cmd)) { - return instruct("Run tests before committing. Use `npm test` or `bun test` first."); + return instruct("شغّل الاختبارات قبل الالتزام. استخدم `npm test` أو `bun test` أولاً."); } return allow(); }, @@ -208,7 +209,7 @@ customPolicies.add({ ## قفل مستودع الإنتاج -ألزم إعداد على مستوى المشروع حتى يحصل كل مطور في فريقك على نفس السياسات. +التزم بتكوين على مستوى المشروع بحيث يحصل كل مطور في فريقك على نفس السياسات. أنشئ `.failproofai/policies-config.json` في مستودعك: @@ -231,20 +232,20 @@ customPolicies.add({ } ``` -ثم ألزمه: +ثم التزم بها: ```bash git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -كل عضو في الفريق لديه failproofai مثبت سيختار هذه القواعد تلقائياً. +كل عضو في الفريق لديه failproofai مثبت سيختار هذه القواعس تلقائياً. --- -## بناء معيار جودة على مستوى المنظمة باستخدام سياسات الاتفاقية +## بناء معيار جودة على مستوى المؤسسة باستخدام سياسات الاتفاقية -الإعداد الأكثر تأثيراً: ألزم `.failproofai/policies/` في مستودعك مع سياسات مصممة خصيصاً لمشروعك. يحصل كل عضو في الفريق عليها تلقائياً — بدون أوامر تثبيت، بدون تغييرات في الإعدادات. +الإعداد الأكثر تأثيراً: التزم بـ `.failproofai/policies/` في مستودعك مع سياسات مخصصة لمشروعك. يحصل كل عضو في الفريق عليها تلقائياً — بدون أوامر تثبيت ولا تغييرات تكوين. @@ -256,41 +257,41 @@ git commit -m "Add failproofai team policies" // .failproofai/policies/team-policies.mjs import { customPolicies, allow, deny, instruct } from "failproofai"; - // Enforce your team's preferred package manager - // (or enable the built-in prefer-package-manager policy instead) + // طبّق مدير الحزم المفضل لفريقك + // (أو فعّل سياسة prefer-package-manager المدمجة بدلاً من ذلك) customPolicies.add({ name: "enforce-bun", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); - if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm."); + if (/\bnpm\b/.test(cmd)) return deny("استخدم bun بدلاً من npm."); return allow(); }, }); - // Remind the agent to run tests before committing + // ذكّر الوكيل بتشغيل الاختبارات قبل الالتزام customPolicies.add({ name: "test-before-commit", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) { - return instruct("Run tests before committing."); + return instruct("شغّل الاختبارات قبل الالتزام."); } return allow(); }, }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - عندما يواجه فريقك أنماط فشل جديدة، أضف سياسات واضغط. يحصل الجميع على التحديث عند `git pull` التالي. تصبح هذه السياسات معياراً للجودة يتطور مع فريقك. + عندما يواجه فريقك حالات فشل جديدة، أضف سياسات والدفع. يحصل الجميع على التحديث عند `git pull` التالي. تصبح هذه السياسات معياراً حياً للجودة ينمو مع فريقك. @@ -302,6 +303,6 @@ git commit -m "Add failproofai team policies" | الملف | ما يوضحه | |------|----------| -| `policies-basic.js` | سياسات البداية - حظر عمليات الكتابة في الإنتاج، الدفع القسري، النصوص المعاد توجيهها | -| `policies-notification.js` | تنبيهات Slack لإشعارات عدم النشاط ونهاية الجلسة | -| `policies-advanced/index.js` | الواردات الانتقالية، hooks غير المتزامنة، تنظيف مخرجات PostToolUse، معالجة حدث Stop | \ No newline at end of file +| `policies-basic.js` | سياسات بدء التشغيل - حجب كتابات الإنتاج والدفع القسري والسكريبتات الموجهة | +| `policies-notification.js` | تنبيهات Slack لإخطارات عدم النشاط ونهاية الجلسة | +| `policies-advanced/index.js` | الواردات الانتقالية، hooks غير متزامنة، تنظيف مخرجات PostToolUse، معالجة حدث Stop | \ No newline at end of file diff --git a/docs/ar/for-agents.mdx b/docs/ar/for-agents.mdx index 94503803..b7b5c202 100644 --- a/docs/ar/for-agents.mdx +++ b/docs/ar/for-agents.mdx @@ -1,36 +1,37 @@ --- +--- title: "للوكلاء" -description: "أضف معرفة Failproof AI إلى وكيل الترميز الخاص بك بأمر واحد. يعمل مع Claude Code و Cursor و Windsurf والمزيد." +description: "أضف مرجع Failproof AI الكامل إلى وكيلك البرمجي بأمر واحد. يعمل مع Claude Code و Cursor و Windsurf والمزيد." --- -أضف المرجع الكامل لـ Failproof AI إلى وكيل الترميز الخاص بك بأمر واحد. يعمل مع Claude Code و Cursor و Windsurf وأي وكيل آخر يدعم المهارات. +أضف المرجع الكامل لـ Failproof AI إلى وكيلك البرمجي بأمر واحد. يعمل مع Claude Code و Cursor و Windsurf وأي وكيل آخر يدعم المهارات. ```bash npx skills add https://docs.befailproof.ai ``` -يكتشف `npx skills` الوكلاء المثبتين لديك ويضيف المهارة بالصيغة الصحيحة لكل واحد تلقائياً. +يكتشف `npx skills` أي وكلاء لديك مثبتة ويضيف المهارة بالصيغة الصحيحة لكل منها تلقائياً. ## ما الذي تغطيه المهارة -| المجال | ما هو مضمّن | -|------|------------| -| السياسات | أسماء السياسات المدمجة وأنواع الأحداث والمعاملات والتفعيل/التعطيل | -| السياسات المخصصة | `customPolicies.add()`وعوامل التطابق و API `allow`/`deny`/`instruct` | +| المجال | ما هو مدرج | +|------|----------------| +| السياسات | أسماء السياسات المدمجة وأنواع الأحداث والمعاملات وتفعيل/تعطيل | +| السياسات المخصصة | `customPolicies.add()` وفلاتر المطابقة وواجهة برمجة التطبيقات `allow`/`deny`/`instruct` | | كائن السياق | `ctx.eventType` و `ctx.toolName` و `ctx.toolInput` و `ctx.session` | -| التكوين | هيكل `policies-config.json` ودمج الأنطقة و `policyParams` | -| واجهة سطر الأوامر | `failproofai policies --install` و `--uninstall` و `--custom` والأنطقة | -| لوحة التحكم | عارض الجلسة ونشاط السياسة والمتغيرات البيئية | -| العمارة | تدفق معالج الخطاف ورموز الخروج وعقد stdin/stdout | +| الإعدادات | بنية `policies-config.json` ودمج النطاق و `policyParams` | +| سطر الأوامر | `failproofai policies --install` و `--uninstall` و `--custom` والنطاقات | +| لوحة المعلومات | عارض الجلسات ونشاط السياسة والمتغيرات البيئية | +| البنية المعمارية | تدفق معالج الخطاف وأكواد الخروج وعقد stdin/stdout | ## هل المهارة كاملة؟ -يقوم Mintlify بإنشاء `llms.txt` من جميع الصفحات في التنقل. توثيق Failproof AI يغطي API الكامل - كل سياسة وخيار ومثال مضمّن. إذا وجدت شيئاً مفقوداً، فالمصدر موجود في `https://docs.befailproof.ai/llms-full.txt`. +يُنشئ Mintlify ملف `llms.txt` من جميع الصفحات في التنقل. تغطي مستندات Failproof AI كامل واجهة برمجة التطبيقات - كل سياسة وخيار ومثال مدرج. إذا وجدت شيئاً مفقوداً، فالمصدر موجود في `https://docs.befailproof.ai/llms-full.txt`. -للحصول على سياق مستهدف، قم بالربط المباشر إلى صفحة محددة: +للحصول على سياق موجه، قم بالربط المباشر إلى صفحة معينة: ```bash -# API السياسات المخصصة فقط +# واجهة برمجة التطبيقات للسياسات المخصصة فقط npx skills add https://docs.befailproof.ai/custom-policies # السياسات المدمجة فقط diff --git a/docs/ar/getting-started.mdx b/docs/ar/getting-started.mdx index fc43612a..350cf141 100644 --- a/docs/ar/getting-started.mdx +++ b/docs/ar/getting-started.mdx @@ -1,4 +1,5 @@ --- +--- title: البدء السريع description: "ثبّت failproofai، فعّل السياسات، واترك وكلاءك يعملون بموثوقية" icon: rocket @@ -7,7 +8,7 @@ icon: rocket ## المتطلبات - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (اختياري - مطلوب فقط عند البناء من المصدر) +- **Bun** >= 1.3.0 (اختياري - مطلوب فقط للبناء من المصدر) --- @@ -30,16 +31,16 @@ bun add -g failproofai ## البدء السريع - - السياسات هي قواعد تعمل قبل وبعد كل استدعاء أداة للوكيل. تعترض الأوامر التدميرية وتسريب الأسرار وأوضاع الفشل الأخرى قبل أن تسبب ضررًا. + + السياسات هي قواعد تعمل قبل وبعد كل استدعاء أداة لدى الوكيل. تلتقط الأوامر الضارة، تسرب الأسرار، وأوضاع الفشل الأخرى قبل أن تسبب ضررًا. ```bash failproofai policies --install ``` - يكتب هذا إدخالات hooks في واجهات سطر الأوامر المثبتة للوكيل (ملف Claude Code `~/.claude/settings.json`، ملف OpenAI Codex `~/.codex/hooks.json`، ملف GitHub Copilot CLI `~/.copilot/hooks/failproofai.json`، ملف Cursor Agent `~/.cursor/hooks.json`، ملف المكون الإضافي المُنشأ من OpenCode في `~/.config/opencode/plugins/failproofai.mjs` بالإضافة إلى إدخال تسجيل في مصفوفة `plugin` الخاصة بـ `~/.config/opencode/opencode.json`، ملف Pi `~/.pi/agent/settings.json`، أو ملف Gemini CLI `~/.gemini/settings.json`). عندما يكون هناك أكثر من واحد، ستُطلب منك الخيارات؛ مرر `--cli claude codex copilot cursor opencode pi gemini` (أي مجموعة جزئية) لتخطي الطلب. + يكتب هذا إدخالات hook في أدوات الوكيل المثبتة لديك (ملف Claude Code `~/.claude/settings.json`، ملف OpenAI Codex `~/.codex/hooks.json`، ملف GitHub Copilot CLI `~/.copilot/hooks/failproofai.json`، ملف Cursor Agent `~/.cursor/hooks.json`، مكون OpenCode المولد في `~/.config/opencode/plugins/failproofai.mjs` بالإضافة إلى إدخال التسجيل في مصفوفة `plugin` في `~/.config/opencode/opencode.json`، ملف Pi `~/.pi/agent/settings.json`، ملف Gemini CLI `~/.gemini/settings.json`، أو ملف Hermes `~/.hermes/config.yaml`). عند وجود أكثر من واحد ستُطلب منك المتابعة؛ مرر `--cli claude codex copilot cursor opencode pi gemini hermes` (أي مجموعة فرعية) لتخطي الطلب. - دعم GitHub Copilot CLI و Cursor Agent و OpenCode و Pi و Gemini CLI هو **إصدار تجريبي** — ثبّت باستخدام `--cli copilot` أو `--cli cursor` أو `--cli opencode` أو `--cli pi` أو `--cli gemini`. + دعم GitHub Copilot CLI و Cursor Agent و OpenCode و Pi و Gemini CLI موجود في مرحلة **تجريبية** — ثبّت باستخدام `--cli copilot` أو `--cli cursor` أو `--cli opencode` أو `--cli pi` أو `--cli gemini`. يثبّت Hermes (hermes-agent، بوابة Slack/Telegram) بنطاق المستخدم باستخدام `--cli hermes` وهو أيضًا **مصدر تدقيق** دون اتصال. ```bash failproofai policies --install --scope project @@ -49,25 +50,26 @@ bun add -g failproofai failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project + failproofai policies --install --cli hermes --scope user failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` - + ```bash failproofai policies ``` - يعرض كل سياسة، وما إذا كانت مفعلة، وأي معاملات مُكوّنة. + يعرض كل سياسة، وما إذا كانت مفعّلة، وأي معاملات مُعدّة. - + ```bash failproofai ``` - يفتح لوحة معلومات محلية على `http://localhost:8020` حيث يمكنك استعراض الجلسات وفحص استدعاءات الأدوات وإدارة السياسات. + يفتح لوحة معلومات محلية على `http://localhost:8020` حيث يمكنك استعراض الجلسات، فحص استدعاءات الأدوات، وإدارة السياسات. - - شغّل Claude Code كالمعتاد. إذا حاول الوكيل فعل شيء محفوف بالمخاطر، فإن failproofai سيعترضه تلقائيًا. اتركه يعمل بدون مراقبة واستعرض ما حدث في لوحة المعلومات. + + شغّل Claude Code كالمعتاد. إذا حاول الوكيل فعل شيء محفوف بالمخاطر، سيعترضه failproofai تلقائيًا. اتركه يعمل دون إشراف واستعرض ما حدث في لوحة المعلومات. @@ -83,30 +85,30 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON writes decision to stdout ``` -تُرجع كل سياسة واحدة من ثلاث قرارات: +كل سياسة تعيد أحد ثلاث قرارات: -- **allow** - يستمر الوكيل بشكل طبيعي -- **deny** - يتم حجب الإجراء، يُخبر الوكيل السبب -- **instruct** - يتم إضافة سياق إضافي إلى مطالبة الوكيل +- **allow** - يمضي الوكيل بشكل طبيعي +- **deny** - يتم حظر الإجراء، يُخبر الوكيل السبب +- **instruct** - يتم إضافة سياق إضافي إلى فوري الوكيل -تعمل السياسات في عمليتك المحلية. لا يتم إرسال أي شيء إلى خدمة بعيدة. +تعمل السياسات في عمليتك المحلية. لا شيء يُرسل إلى خدمة بعيدة. --- -## اضبط سياسات الفريق باستخدام السياسات المبنية على الاتفاقيات +## إعداد سياسات الفريق باستخدام السياسات المستندة إلى الاتفاقية -أسرع طريقة لإنشاء معايير الجودة عبر فريقك هي اتفاقية `.failproofai/policies/`. أسقط ملفات السياسات في هذا المجلد وسيتم تحميلها تلقائيًا — لا أعلام، لا تغييرات في الإعدادات، لا أوامر تثبيت. +أسرع طريقة لإنشاء معايير الجودة عبر فريقك هي اتفاقية `.failproofai/policies/`. ضع ملفات السياسة في هذا الدليل وسيتم تحميلها تلقائيًا — لا أعلام، لا تغييرات إعدادات، لا أوامر تثبيت. - + ```bash mkdir -p .failproofai/policies ``` - - انسخ الأمثلة الأولية أو اكتب ملفاتك الخاصة: + + انسخ أمثلة المبتدئين أو اكتب خاصتك: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -131,43 +133,43 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - كل عضو في الفريق لديه failproofai مثبتًا سيستقبل هذه السياسات تلقائيًا. لا توجد حاجة لإعداد لكل مطور. + كل فرد من فريقك الذي لديه failproofai مثبت سيستقبل هذه السياسات تلقائيًا. لا يلزم إعداد لكل مطور. -التزم بـ `.failproofai/policies/` في مستودعك حتى يشارك الفريق بأكمله نفس المعايير. مع اكتشاف فريقك لأوضاع فشل جديدة، أضف سياسات واضغط — سيحصل الجميع على التحديث في `git pull` التالي. بمرور الوقت، تصبح هذه السياسات معيارًا جودة حيًا يستمر في التحسن. +التزم بـ `.failproofai/policies/` في مستودعك حتى يتشارك الفريق بأكمله نفس المعايير. كلما اكتشف فريقك أوضاع فشل جديدة، أضف سياسات وادفع — الجميع يحصلون على التحديث في `git pull` التالي. بمرور الوقت تصبح هذه السياسات معيار جودة حي يستمر في التحسن. --- ## تخزين البيانات -تبقى جميع الإعدادات والسجلات على جهازك: +جميع الإعدادات والسجلات تبقى على جهازك: | المسار | ما يخزنه | -|------|---------| +|------|-------------| | `~/.failproofai/policies-config.json` | إعدادات السياسة العامة | | `~/.failproofai/hook-activity.jsonl` | سجل تنفيذ Hook | -| `~/.failproofai/hook.log` | سجل تصحيح أخطاء أداة Hook المخصصة | -| `.failproofai/policies-config.json` | إعدادات كل مشروع (مرتكبة) | -| `.failproofai/policies-config.local.json` | التجاوزات الشخصية (مُستثناة من git) | +| `~/.failproofai/hook.log` | سجل تصحيح أخطاء Hook المخصص | +| `.failproofai/policies-config.json` | إعدادات لكل مشروع (مُلتزم به) | +| `.failproofai/policies-config.local.json` | تجاوزات شخصية (مُستثناة من git) | --- -## الإزالة +## إلغاء التثبيت ```bash failproofai policies --uninstall ``` -يزيل إدخالات hooks من `~/.claude/settings.json`. يتم الاحتفاظ بملفات الإعدادات في `~/.failproofai/`. +يزيل إدخالات hook من `~/.claude/settings.json`. ملفات الإعدادات في `~/.failproofai/` يتم الاحتفاظ بها. --- @@ -188,7 +190,7 @@ failproofai policies --uninstall - راقب الجلسات واستعرض نشاط السياسة + مراقبة الجلسات واستعرض نشاط السياسة \ No newline at end of file diff --git a/docs/ar/introduction.mdx b/docs/ar/introduction.mdx index ac044f4c..2475e146 100644 --- a/docs/ar/introduction.mdx +++ b/docs/ar/introduction.mdx @@ -1,41 +1,41 @@ --- title: "Failproof AI" -description: "FailproofAI يوفر 39 سياسة فشل مدمجة للعملاء الذين يعملون بالذكاء الاصطناعي تعترض الحلقات، وتسرب الأسرار، واستدعاءات الأدوات المدمرة، والمزيد في تثبيت واحد فقط." +description: "FailproofAI يوفر للوكلاء الذكيين 39 سياسة فشل مدمجة تكتشف الحلقات وتسرب الأسرار واستدعاءات الأدوات المدمرة والمزيد في تثبيت واحد." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -خطافات وسياسات لـ **معالجة فشل الذكاء الاصطناعي** و**استرجاع الأخطاء** و**موثوقية النماذج اللغوية الكبيرة**. اجعل عملاء الذكاء الاصطناعي لديك موثوقين وتشغيلهم بشكل مستقل عبر **Claude Code** و**OpenAI Codex** و**GitHub Copilot** و**Cursor Agent** و**OpenCode** و**Pi** و**Gemini CLI** و**Agents SDK**. +الخطافات والسياسات لـ **معالجة أعطال الذكاء الاصطناعي** و **استرجاع الأخطاء** و **موثوقية نماذج اللغة الكبيرة**. حافظ على موثوقية وكلائك الذكيين والعمل بشكل مستقل عبر **Claude Code** و **OpenAI Codex** و **GitHub Copilot** و **Cursor Agent** و **OpenCode** و **Pi** و **Gemini CLI** و **Hermes** و **Agents SDK**. -عملاء الذكاء الاصطناعي يفشلون بطرق يمكن التنبؤ بها. يقومون بتشغيل أوامر مدمرة، وتسريب الأسرار، والانجراف عن المهمة، والعلوق في حلقات، أو الدفع المباشر إلى الفرع الرئيسي. إذا تركت دون رقابة، فقد تتحول الإخفاقات الصغيرة إلى أعطال، وتسريب بيانات اعتماد، وفقدان العمل. +الوكلاء الذكيون يفشلون بطرق يمكن التنبؤ بها. يقومون بتنفيذ أوامر مدمرة، تسرب الأسرار، الانجراف عن المهمة الأساسية، الوقوع في حلقات، أو الدفع مباشرة إلى الفرع الرئيسي. إذا تركت دون مراقبة، فإن الأعطال الصغيرة قد تؤدي إلى انقطاعات، تسرب بيانات الاعتماد، وفقدان العمل. -FailproofAI يحل هذه المشكلة باستخدام **السياسات**. هذه القواعد تتواصل مع كل استدعاء أداة للعميل لـ **كشف الفشل** و**التخفيف منه** (حظر، تعليمات، تنظيف)، و**تنبيهك** عند احتياج شيء ما إلى الانتباه. لوحة تحكم محلية تتيح لك مراجعة كل استدعاء أداة وفشل عميل وإجراء استرجاع بعد ذلك. +FailproofAI يحل هذه المشكلة عبر **السياسات**. هذه القواعد تتصل بكل استدعاء أداة من الوكيل لـ **الكشف عن الأعطال** و **تخفيفها** (حظر، توجيه، تعقيم) و **تنبيهك** عند الحاجة للاهتمام. لوحة معلومات محلية تسمح لك باستعراض كل استدعاء أداة وفشل وكيل وإجراء استرجاع بعد ذلك. -لا تترك البيانات جهازك. +لا تغادر أي بيانات جهازك. -## ابدأ +## ابدأ الآن - حظر الأوامر المدمرة، ومنع تسريب الأسرار، والحفاظ على العملاء داخل حدود المشروع، والمزيد. كل ذلك في الصندوق. + حظر الأوامر المدمرة، منع تسرب الأسرار، إبقاء الوكلاء داخل حدود المشروع، والمزيد. كل ذلك جاهز من البداية. - اكتب قواعلك الخاصة في JavaScript بواسطة واجهة برمجة تطبيقات بسيطة allow / deny / instruct. + اكتب قواعدك الخاصة في JavaScript باستخدام واجهة برمجية بسيطة allow / deny / instruct. - - انظر إلى ما فعله عملاؤك أثناء غيابك. استعرض الجلسات، وفتش استدعاءات الأدوات، وراجع حيث أطلقت السياسات. + + انظر إلى ما فعله وكلائك أثناء غيابك. استعرض الجلسات، افحص استدعاءات الأدوات، راجع المكان الذي تم تطبيق السياسات فيه. - اضبط أي سياسة بدون كود. قم بتعيين قوائم السماح أو الفروع المحمية أو الحدود لكل مشروع أو عالميًا. + ضبط أي سياسة دون كود. عيّن قوائم السماح أو الفروع المحمية أو العتبات لكل مشروع أو عالميًا. -## البدء السريع +## ابدأ بسرعة @@ -50,8 +50,8 @@ bun add -g failproofai ```bash -failproofai policies --install # enable policies (or skip — `failproofai` will offer to set them up on first run) -failproofai # launch the dashboard +failproofai policies --install # تفعيل السياسات (أو تخطي — سيقدم failproofai تعيينها عند التشغيل الأول) +failproofai # إطلاق لوحة المعلومات ``` -انظر إلى دليل [البدء](/ar/getting-started) للحصول على الشرح الكامل. \ No newline at end of file +راجع دليل [البدء](/ar/getting-started) للحصول على الشرح الكامل. \ No newline at end of file diff --git a/docs/ar/package-aliases.mdx b/docs/ar/package-aliases.mdx index 07513868..d9e87f14 100644 --- a/docs/ar/package-aliases.mdx +++ b/docs/ar/package-aliases.mdx @@ -1,6 +1,6 @@ --- -title: اسم الحزم المستعارة -description: "الأسماء المستعارة المسجلة لمنع محاكاة الأخطاء وكيفية عملها" +title: اسماء الحزم البديلة +description: "الاسماء البديلة المسجلة لمنع هجمات التصيد وكيفية عملها" icon: copy --- @@ -10,54 +10,54 @@ icon: copy ```bash npm install -g failproofai -# أو +# or bun add -g failproofai ``` --- -## لماذا نمتلك أسماء الأسماء المستعارة +## لماذا نمتلك أسماء البدائل -محاكاة الأخطاء (typosquatting) هي هجوم شائع على سلسلة التوريد حيث يقوم ممثل خبيث بتسجيل اسم حزمة يبعد ضغطة واحدة عن حزمة شهيرة. المستخدمون الذين لا يتوقعون ذلك والذين يخطئون في كتابة أمر التثبيت ينتهي بهم الحال إلى تشغيل كود يتحكم به المهاجم بإمكانية الوصول الكامل إلى النظام - وهو بالضبط نوع التهديد الذي صُمم Failproof AI للدفاع ضده. +التصيد بالحزم هو هجوم شائع في سلسلة التوريد حيث يسجل مهاجم اسم حزمة يختلف بضغطة مفتاح واحدة عن حزمة شهيرة. يجد المستخدمون الذين يخطئون في كتابة أمر التثبيت أنفسهم يشغلون كوداً يسيطر عليه المهاجم بصلاحيات النظام الكاملة - وهذا تماماً نوع التهديد الذي صُممت Failproof AI للدفاع ضده. -لإزالة هذا السطح، **نمتلك مسبقاً جميع الأخطاء الإملائية الشائعة ومتغيرات التنسيق** لـ `failproofai` على npm. لا يمكن لأي طرف ثالث تسجيل أي من هذه الأسماء. كل واحد منها هو وكيل خفيف يثبت ويفوض إلى حزمة `failproofai` الحقيقية. +لاستبعاد هذا السطح الهجومي، **نمتلك مسبقاً جميع الأخطاء الإملائية الشائعة والمتغيرات الصيغية** لـ `failproofai` على npm. لا يمكن لأي طرف ثالث تسجيل أي من هذه الأسماء. كل واحد منها عبارة عن بروكسي بسيط يثبت الحزمة الحقيقية ويفوض إليها. --- -## الأسماء المستعارة المسجلة +## الأسماء البديلة المسجلة -**متغيرات التنسيق** - طرق مختلفة لكتابة "failproof ai": +**متغيرات الصيغة** - طرق مختلفة لكتابة "failproof ai": | الحزمة | الحالة | |---------|--------| | `failproof` | ✅ منشورة | -| `failproof-ai` | ⏳ قيد انتظار دعم npm | -| `fail-proof-ai` | ⏳ قيد انتظار دعم npm | -| `failproof_ai` | ⏳ قيد انتظار دعم npm | -| `fail_proof_ai` | ⏳ قيد انتظار دعم npm | -| `fail-proofai` | ⏳ قيد انتظار دعم npm | +| `failproof-ai` | ⏳ في انتظار دعم npm | +| `fail-proof-ai` | ⏳ في انتظار دعم npm | +| `failproof_ai` | ⏳ في انتظار دعم npm | +| `fail_proof_ai` | ⏳ في انتظار دعم npm | +| `fail-proofai` | ⏳ في انتظار دعم npm | -**أخطاء `failprof*`** - حرف واحد مفقود من "proof": +**أخطاء `failprof*`** - حرف `o` واحد ناقص من "proof": | الحزمة | الحالة | |---------|--------| | `failprof` | ✅ منشورة | | `failprof-ai` | ✅ منشورة | -| `failprofai` | ⏳ قيد انتظار دعم npm | -| `fail-prof-ai` | ⏳ قيد انتظار دعم npm | -| `failprof_ai` | ⏳ قيد انتظار دعم npm | +| `failprofai` | ⏳ في انتظار دعم npm | +| `fail-prof-ai` | ⏳ في انتظار دعم npm | +| `failprof_ai` | ⏳ في انتظار دعم npm | -**أخطاء `faliproof*`** - حروف `a` و `i` مقلوبة: +**أخطاء `faliproof*`** - تبديل `a` و `i`: | الحزمة | الحالة | |---------|--------| | `faliproof` | ✅ منشورة | | `faliproof-ai` | ✅ منشورة | -| `faliproofai` | ⏳ قيد انتظار دعم npm | +| `faliproofai` | ⏳ في انتظار دعم npm | -> **لماذا قيد الانتظار؟** سياسة npm لمنع البريد العشوائي تحظر الأسماء التي تتطابق مع نفس السلسلة النصية للحزمة الموجودة بعد إزالة علامات الترقيم وتشغيل فحوصات التشابه. لقد تواصلنا مع فريق دعم npm لحجز هذه الأسماء لأغراض منع محاكاة الأخطاء. سيتم تفعيلها بمجرد الموافقة عليها. +> **لماذا قيد الانتظار؟** سياسة منع الرسائل غير المرغوبة على npm تحظر الأسماء التي تتطابق مع اسم حزمة موجود بعد إزالة الترقيم والتحقق من التشابه. لقد تواصلنا مع دعم npm لحجز هذه الأسماء لأغراض مكافحة التصيد. سيتم تفعيلها بمجرد الموافقة عليها. -يمكنك التحقق من أن أي اسم مستعار منشور مملوك لنا: +يمكنك التحقق من أن أي اسم بديل منشور مملوك لنا: ```bash npm info failproof @@ -66,17 +66,17 @@ npm info failproof --- -## كيف تعمل الأسماء المستعارة +## كيفية عمل الأسماء البديلة -كل حزمة مستعارة: +كل حزمة بديلة: -1. تدرج `failproofai` كمتطلب اعتماد - بحيث تعمل الحزمة الحقيقية (بما في ذلك إعداد `postinstall` hook الخاص بها) عند التثبيت -2. تكشف عن ملف تنفيذي يطابق اسمها الخاص (على سبيل المثال `failprof-ai`) يفوض جميع المعاملات إلى ملف تنفيذي `failproofai` +1. تسرد `failproofai` كتبعية - بحيث يتم تشغيل الحزمة الحقيقية (بما في ذلك إعداد هوك `postinstall` الخاص بها) عند التثبيت +2. تكشف عن ملف تنفيذي يطابق اسمها الخاص (مثل `failprof-ai`) والذي يفوض جميع الوسائط إلى ملف `failproofai` التنفيذي -الوكيل هو سكريبت Node من سطرين؛ لا توجد منطق، لا استدعاءات شبكة، ولا جمع بيانات فيما وراء ما تفعله `failproofai` بنفسها. +البروكسي عبارة عن سكريبت Node بسطتين؛ لا توجد منطق، لا استدعاءات شبكة، وليس هناك جمع بيانات بعيداً عما تقوم به `failproofai` نفسها. --- ## إذا وجدت اسماً فاتنا -افتح مشكلة في [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) وسنقوم بتسجيله. \ No newline at end of file +افتح مشكلة على [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) وسنقوم بتسجيله. \ No newline at end of file diff --git a/docs/ar/testing.mdx b/docs/ar/testing.mdx index 9d8fc9c2..6188cf69 100644 --- a/docs/ar/testing.mdx +++ b/docs/ar/testing.mdx @@ -1,10 +1,11 @@ --- +--- title: الاختبار -description: "اختبارات الوحدة واختبارات E2E ومساعدات الاختبار" +description: "اختبارات الوحدة واختبارات End-to-End ومساعدات الاختبار" icon: flask-vial --- -يحتوي failproofai على مجموعتي اختبار: **اختبارات الوحدة** (سريعة، مع محاكاة) و**اختبارات end-to-end** (استدعاءات subprocess فعلية). +failproofai يحتوي على مجموعتي اختبار: **اختبارات الوحدة** (سريعة، معزولة) و**اختبارات End-to-End** (استدعاءات subprocess حقيقية). --- @@ -20,10 +21,10 @@ bun run test # تشغيل اختبارات E2E (يتطلب إعدادًا - انظر أدناه) bun run test:e2e -# فحص النوع دون البناء +# التحقق من الأنواع بدون بناء bunx tsc --noEmit -# التحقق من الأسلوب +# التحقق من أسلوب الكود bun run lint ``` @@ -31,7 +32,7 @@ bun run lint ## اختبارات الوحدة -تقع اختبارات الوحدة في `__tests__/` وتستخدم [Vitest](https://vitest.dev) مع `jsdom`. +اختبارات الوحدة توجد في `__tests__/` وتستخدم [Vitest](https://vitest.dev) مع `jsdom`. ```text __tests__/ @@ -39,9 +40,9 @@ __tests__/ builtin-policies.test.ts # منطق السياسة لكل سياسة مدمجة hooks-config.test.ts # تحميل الإعدادات ودمج النطاقات policy-evaluator.test.ts # حقن المعاملات وترتيب التقييم - custom-hooks-registry.test.ts # إضافة/الحصول على/مسح سجل globalThis - custom-hooks-loader.test.ts # محمل ESM والاستيرادات المتعدية ومعالجة الأخطاء - manager.test.ts # عمليات التثبيت/الإزالة/القائمة + custom-hooks-registry.test.ts # سجل globalThis للإضافة والحصول والحذف + custom-hooks-loader.test.ts # محمل ESM والاستيرادات المتداخلة ومعالجة الأخطاء + manager.test.ts # عمليات التثبيت والإزالة والقائمة components/ sessions-list.test.tsx # مكون قائمة الجلسات project-list.test.tsx # مكون قائمة المشاريع @@ -108,13 +109,13 @@ describe("block-sudo", () => { --- -## اختبارات end-to-end +## اختبارات End-to-End -تستدعي اختبارات E2E الملف الثنائي الفعلي `failproofai` كـ subprocess، وترسل حمولة JSON إلى stdin، وتتحقق من مخرجات stdout وكود الخروج. يختبر هذا مسار التكامل الكامل الذي يستخدمه Claude Code. +اختبارات E2E تستدعي ملف التنفيذ `failproofai` الحقيقي كـ subprocess، وتنقل حمولة JSON إلى stdin، وتتحقق من مخرجات stdout ورمز الخروج. هذا يختبر مسار التكامل الكامل الذي يستخدمه Claude Code. ### الإعداد -تشغل اختبارات E2E الملف الثنائي مباشرة من مصدر المستودع. قبل التشغيل الأول، قم ببناء حزمة CJS التي تستخدمها ملفات الخطاف المخصصة عند استيرادها من `'failproofai'`: +اختبارات E2E تشغل الملف التنفيذي مباشرة من مصدر المستودع. قبل التشغيل الأول، بناء حزمة CJS التي تستخدمها ملفات hook المخصصة عند الاستيراد من `'failproofai'`: ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -126,20 +127,20 @@ bun build src/index.ts --outdir dist --target node --format cjs bun run test:e2e ``` -أعد بناء `dist/` كلما غيرت واجهة برمجية عامة للخطاف (`src/hooks/custom-hooks-registry.ts` أو `src/hooks/policy-helpers.ts` أو `src/hooks/policy-types.ts`). +أعد بناء `dist/` كلما غيرت واجهة برمجية hook عامة (`src/hooks/custom-hooks-registry.ts` أو `src/hooks/policy-helpers.ts` أو `src/hooks/policy-types.ts`). -### بنية اختبار E2E +### هيكل اختبار E2E ```text __tests__/e2e/ helpers/ - hook-runner.ts # توليد الملف الثنائي، أنابيب حمولة JSON، التقاط كود الخروج + stdout + stderr - fixture-env.ts # بيئة معزولة لكل اختبار مع ملفات إعدادات - payloads.ts # مصانع الحمول الدقيقة من Claude لكل نوع حدث + hook-runner.ts # استدعاء الملف التنفيذي، نقل JSON للحمولة، التقاط رمز الخروج والمخرجات والأخطاء + fixture-env.ts # دليل مؤقت معزول لكل اختبار مع ملفات الإعدادات + payloads.ts # مصانع الحمولة الدقيقة لكل نوع حدث hooks/ - builtin-policies.e2e.test.ts # كل سياسة مدمجة مع subprocess فعلي - custom-hooks.e2e.test.ts # تحميل الخطاف المخصص والتقييم - config-scopes.e2e.test.ts # دمج الإعدادات عبر المشروع/المحلي/العام + builtin-policies.e2e.test.ts # كل سياسة مدمجة مع subprocess حقيقي + custom-hooks.e2e.test.ts # تحميل وتقييم hook مخصص + config-scopes.e2e.test.ts # دمج الإعدادات عبر المشروع والمحلي والعام policy-params.e2e.test.ts # حقن المعاملات لكل سياسة بمعاملات ``` @@ -151,8 +152,8 @@ __tests__/e2e/ import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - مجلد مؤقت؛ مرر كـ payload.cwd لالتقاط .failproofai/policies-config.json -// env.home - مجلد منزلي معزول؛ لا يتسرب ~/.failproofai الفعلي +// env.cwd - دليل مؤقت؛ مرره كـ payload.cwd للتقاط .failproofai/policies-config.json +// env.home - دليل home معزول؛ لا تسريب حقيقي لـ ~/.failproofai env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -162,9 +163,9 @@ env.writeConfig({ }); ``` -يسجل `createFixtureEnv()` تنظيف `afterEach` تلقائيًا. +`createFixtureEnv()` يسجل تنظيف `afterEach` تلقائيًا. -**`runHook`** - استدعاء الملف الثنائي: +**`runHook`** - استدعاء الملف التنفيذي: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +181,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - مصانع حمول جاهزة: +**`Payloads`** - مصانع الحمولة الجاهزة: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -226,35 +227,35 @@ describe("block-rm-rf (E2E)", () => { ); expect(result.exitCode).toBe(0); - expect(result.stdout).toBe(""); // allow → empty stdout + expect(result.stdout).toBe(""); // السماح → stdout فارغ }); }); ``` ### أشكال استجابات E2E -| القرار | كود الخروج | stdout | +| القرار | رمز الخروج | stdout | |----------|-----------|--------| -| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | -| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | -| Instruct (غير Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop instruct | `2` | stdout فارغ؛ السبب في stderr | -| Allow | `0` | سلسلة فارغة | +| `PreToolUse` رفض | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | +| `PostToolUse` رفض | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | +| تعليمات (بدون Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | +| تعليمات Stop | `2` | stdout فارغ؛ السبب في stderr | +| السماح | `0` | سلسلة فارغة | ### إعداد Vitest -تستخدم اختبارات E2E `vitest.config.e2e.mts` مع: +اختبارات E2E تستخدم `vitest.config.e2e.mts` مع: -- `environment: "node"` - لا توجد متغيرات عامة للمتصفح المطلوبة -- `pool: "forks"` - عزل عملية حقيقي (اختبارات توليد subprocesses) -- `testTimeout: 20_000` - 20 ثانية لكل اختبار (بدء الملف الثنائي + تقييم الخطاف) +- `environment: "node"` - لا توجد متغيرات عامة للمتصفح مطلوبة +- `pool: "forks"` - عزل العملية الحقيقي (الاختبارات تستدعي subprocesses) +- `testTimeout: 20_000` - 20 ثانية لكل اختبار (بدء التشغيل + تقييم hook) -تجمع `forks` مهمة: العمال المستندة إلى الخيط تشارك `globalThis`، مما قد يتداخل مع اختبارات التي تولد subprocesses. تتجنب forks القائمة على العملية هذا. +حوض `forks` مهم: العمال المستندة إلى الخيوط تشارك `globalThis`، مما قد يتداخل مع الاختبارات التي تستدعي subprocess. العمليات المستقلة تتجنب هذا. --- ## CI -يجب نجاح التشغيل الكامل لـ CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) قبل الدمج. تعمل مجموعة E2E كمهمة CI منفصلة بالتوازي. +يجب أن يمر التشغيل الكامل لـ CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) قبل دمج الكود. مجموعة E2E تعمل كعمل CI منفصل بالتوازي. -انظر [المساهمة](../CONTRIBUTING.md) للحصول على قائمة التحقق الكاملة قبل الدمج. \ No newline at end of file +انظر [المساهمة](../CONTRIBUTING.md) لقائمة التحقق الكاملة قبل الدمج. \ No newline at end of file diff --git a/docs/de/architecture.mdx b/docs/de/architecture.mdx index f9e39a1b..2348c377 100644 --- a/docs/de/architecture.mdx +++ b/docs/de/architecture.mdx @@ -4,18 +4,18 @@ description: "Wie der Hook-Handler, das Laden der Konfiguration und die Richtlin icon: sitemap --- -Dieses Dokument erklärt, wie failproofai intern arbeitet: wie das Hook-System Agent-Tool-Aufrufe abfängt, wie die Konfiguration geladen und zusammengeführt wird, wie Richtlinien ausgewertet werden und wie das Dashboard die Agentenaktivität überwacht. +Dieses Dokument erklärt, wie failproofai intern funktioniert: wie das Hook-System Agenten-Tool-Aufrufe abfängt, wie die Konfiguration geladen und zusammengeführt wird, wie Richtlinien ausgewertet werden und wie das Dashboard die Agenten-Aktivität überwacht. --- -## Übersicht +## Überblick failproofai besteht aus zwei unabhängigen Subsystemen: -1. **Hook-Handler** – Ein schneller CLI-Subprozess, den Claude Code bei jedem Agent-Tool-Aufruf aufruft. Er wertet Richtlinien aus und gibt eine Entscheidung zurück. -2. **Agent Monitor (Dashboard)** – Eine Next.js-Webanwendung zur Überwachung von Agentensitzungen und zur Verwaltung von Richtlinien. +1. **Hook-Handler** – Ein schneller CLI-Subprozess, den Claude Code bei jedem Agenten-Tool-Aufruf aufruft. Er wertet Richtlinien aus und gibt eine Entscheidung zurück. +2. **Agent Monitor (Dashboard)** – Eine Next.js-Webanwendung zur Überwachung von Agentensitzungen und Verwaltung von Richtlinien. -Beide Subsysteme teilen Konfigurationsdateien in `~/.failproofai/` und im `.failproofai/`-Verzeichnis des Projekts, laufen aber als separate Prozesse und kommunizieren ausschließlich über das Dateisystem. +Beide Subsysteme teilen sich Konfigurationsdateien in `~/.failproofai/` und im `.failproofai/`-Verzeichnis des Projekts, laufen jedoch als separate Prozesse und kommunizieren ausschließlich über das Dateisystem. --- @@ -23,7 +23,7 @@ Beide Subsysteme teilen Konfigurationsdateien in `~/.failproofai/` und im `.fail ### Integration mit Claude Code -Wenn Sie `failproofai policies --install` ausführen, werden folgende Einträge in `~/.claude/settings.json` geschrieben: +Wenn Sie `failproofai policies --install` ausführen, schreibt es Einträge wie diese in `~/.claude/settings.json`: ```json { @@ -44,7 +44,7 @@ Wenn Sie `failproofai policies --install` ausführen, werden folgende Einträge } ``` -Claude Code ruft dann `failproofai --hook PreToolUse` vor jedem Tool-Aufruf als Subprozess auf und übergibt eine JSON-Nutzlast über stdin. +Claude Code ruft dann `failproofai --hook PreToolUse` als Subprozess vor jedem Tool-Aufruf auf und übergibt dabei eine JSON-Nutzlast über stdin. ### Nutzlastformat @@ -62,11 +62,11 @@ Claude Code ruft dann `failproofai --hook PreToolUse` vor jedem Tool-Aufruf als Bei `PostToolUse`-Ereignissen enthält die Nutzlast zusätzlich `tool_result` mit der Ausgabe des Tools. -Der Handler begrenzt die stdin-Eingabe auf 1 MB. Nutzlasten, die diesen Wert überschreiten, werden verworfen, und alle Richtlinien erlauben die Ausführung implizit. +Der Handler erzwingt ein stdin-Limit von 1 MB. Nutzlasten, die dieses überschreiten, werden verworfen, und alle Richtlinien erlauben implizit. ### Antwortformat -**Ablehnen (PreToolUse):** +**Verweigern (PreToolUse):** ```json { "hookSpecificOutput": { @@ -76,7 +76,7 @@ Der Handler begrenzt die stdin-Eingabe auf 1 MB. Nutzlasten, die diesen Wert üb } ``` -**Ablehnen (PostToolUse):** +**Verweigern (PostToolUse):** ```json { "hookSpecificOutput": { @@ -85,7 +85,7 @@ Der Handler begrenzt die stdin-Eingabe auf 1 MB. Nutzlasten, die diesen Wert üb } ``` -**Anweisen (jedes Ereignis außer Stop):** +**Anweisen (beliebiges Ereignis außer Stop):** ```json { "hookSpecificOutput": { @@ -94,17 +94,17 @@ Der Handler begrenzt die stdin-Eingabe auf 1 MB. Nutzlasten, die diesen Wert üb } ``` -**Stop-Ereignis anweisen:** +**Stop-Ereignis instruct:** - Exit-Code: `2` -- Begründung wird in stderr (nicht stdout) geschrieben +- Begründung wird in stderr geschrieben (nicht stdout) **Erlauben:** - Exit-Code: `0` -- Leere stdout-Ausgabe +- Leeres stdout **Erlauben mit Nachricht:** -`allow(message)` ermöglicht es einer Richtlinie, informativen Kontext an Claude zurückzusenden, auch wenn die Operation erlaubt ist. Der Hook-Handler schreibt das folgende JSON auf **stdout** (keine Konfigurationsdatei – dies ist die Antwort des Handlers an Claude Code, genau wie Ablehnen- und Anweisen-Antworten oben): +`allow(message)` ermöglicht es einer Richtlinie, informativen Kontext an Claude zurückzusenden, selbst wenn die Operation erlaubt ist. Der Hook-Handler schreibt folgendes JSON auf **stdout** (keine Konfigurationsdatei – dies ist die Antwort des Handlers an Claude Code, genau wie deny- und instruct-Antworten oben): ```json // Written to stdout by the hook handler process @@ -114,9 +114,9 @@ Der Handler begrenzt die stdin-Eingabe auf 1 MB. Nutzlasten, die diesen Wert üb } } ``` -- Exit-Code: `0` (die Operation wird erlaubt) +- Exit-Code: `0` (Operation ist erlaubt) - Wenn mehrere Richtlinien `allow` mit einer Nachricht zurückgeben, werden ihre Nachrichten mit Zeilenumbrüchen zu einem einzigen `additionalContext`-String zusammengefügt -- Wenn keine Richtlinie eine Nachricht liefert, ist stdout leer (wie bisher) +- Wenn keine Richtlinie eine Nachricht liefert, ist stdout leer (wie zuvor) ### Verarbeitungspipeline @@ -125,17 +125,17 @@ Der Handler begrenzt die stdin-Eingabe auf 1 MB. Nutzlasten, die diesen Wert üb ```text stdin JSON → Nutzlast parsen (max. 1 MB) - → Sitzungsmetadaten extrahieren (session_id, cwd, tool_name, tool_input usw.) - → readMergedHooksConfig(cwd) ← Projekt- + lokale + globale Konfiguration zusammenführen - → aktivierte integrierte Richtlinien mit aufgelösten Parametern registrieren - → benutzerdefinierte Richtlinien aus customPoliciesPath laden (falls angegeben) + → Sitzungsmetadaten extrahieren (session_id, cwd, tool_name, tool_input, etc.) + → readMergedHooksConfig(cwd) ← führt Projekt- + lokale + globale Konfiguration zusammen + → aktivierte eingebaute Richtlinien mit aufgelösten Parametern registrieren + → benutzerdefinierte Richtlinien aus customPoliciesPath laden (falls gesetzt) → benutzerdefinierte Richtlinien in die Richtlinienregistrierung eintragen - → alle Richtlinien auswerten (erst integrierte, dann benutzerdefinierte) - → erstes deny bricht sofort ab + → alle Richtlinien auswerten (eingebaute zuerst, dann benutzerdefinierte) + → erstes deny bricht ab → instruct-Entscheidungen werden gesammelt → allow-Nachrichten werden gesammelt → JSON-Entscheidung auf stdout schreiben - → Ereignis in ~/.failproofai/hook-activity.jsonl persistieren + → Ereignis in ~/.failproofai/hook-activity.jsonl speichern → beenden ``` @@ -143,9 +143,9 @@ Der gesamte Prozess läuft bei typischen Nutzlasten ohne LLM-Aufrufe in unter 10 --- -## Konfigurationsladung +## Laden der Konfiguration -`src/hooks/hooks-config.ts` implementiert das Laden der Konfiguration aus drei Bereichen. +`src/hooks/hooks-config.ts` implementiert das dreistufige Laden der Konfiguration. ```text [1] {cwd}/.failproofai/policies-config.json ← Projekt (höchste Priorität) @@ -154,8 +154,8 @@ Der gesamte Prozess läuft bei typischen Nutzlasten ohne LLM-Aufrufe in unter 10 ``` Zusammenführungslogik: -- `enabledPolicies` – deduplizierte Vereinigung aus allen drei Dateien -- `policyParams` – pro Richtlinien-Schlüssel gewinnt die erste Datei, die ihn definiert, vollständig +- `enabledPolicies` – deduplizierte Vereinigung aller drei Dateien +- `policyParams` – pro Richtlinienschlüssel gewinnt die erste Datei, die ihn definiert, vollständig - `customPoliciesPath` – die erste Datei, die diesen Wert definiert, gewinnt - `llm` – die erste Datei, die diesen Wert definiert, gewinnt @@ -171,22 +171,22 @@ Für jede Richtlinie: 1. Das `params`-Schema der Richtlinie nachschlagen (falls vorhanden). 2. `policyParams[policy.name]` aus der zusammengeführten Konfiguration lesen. -3. Benutzerdefinierte Werte über die Schema-Standardwerte zusammenführen, um `ctx.params` zu erzeugen. +3. Benutzerdefinierte Werte über die Schema-Standardwerte legen, um `ctx.params` zu erzeugen. 4. `policy.fn(ctx)` mit dem aufgelösten Kontext aufrufen. -5. Wenn das Ergebnis `deny` ist, sofort abbrechen und diese Entscheidung zurückgeben. -6. Wenn das Ergebnis `instruct` ist, die Nachricht sammeln und fortfahren. -7. Wenn das Ergebnis `allow` ist, zur nächsten Richtlinie übergehen. +5. Ist das Ergebnis `deny`, sofort abbrechen und diese Entscheidung zurückgeben. +6. Ist das Ergebnis `instruct`, die Nachricht sammeln und fortfahren. +7. Ist das Ergebnis `allow`, zur nächsten Richtlinie übergehen. Nachdem alle Richtlinien ausgeführt wurden: -- Falls ein `deny` zurückgegeben wurde, die Ablehnungsantwort ausgeben. -- Falls `instruct`-Rückgaben gesammelt wurden, eine einzelne Anweisungsantwort mit allen zusammengefügten Nachrichten ausgeben. -- Andernfalls eine Erlauben-Antwort ausgeben (leere stdout-Ausgabe, Exit 0). +- Wurde ein `deny` zurückgegeben, die deny-Antwort ausgeben. +- Wurden `instruct`-Rückgaben gesammelt, eine einzelne instruct-Antwort mit allen zusammengefügten Nachrichten ausgeben. +- Andernfalls eine allow-Antwort ausgeben (leeres stdout, Exit-Code 0). --- -## Integrierte Richtlinien +## Eingebaute Richtlinien -`src/hooks/builtin-policies.ts` definiert alle 39 integrierten Richtlinien als `BuiltinPolicyDefinition`-Objekte: +`src/hooks/builtin-policies.ts` definiert alle 39 eingebauten Richtlinien als `BuiltinPolicyDefinition`-Objekte: ```typescript interface BuiltinPolicyDefinition { @@ -204,9 +204,9 @@ interface BuiltinPolicyDefinition { } ``` -Richtlinien, die `params` akzeptieren, deklarieren ein `PolicyParamsSchema` mit Typen und Standardwerten für jeden Parameter. Der Richtlinien-Evaluator injiziert aufgelöste Werte in `ctx.params`, bevor er `fn` aufruft. Richtlinienfunktionen lesen `ctx.params` ohne Null-Prüfung, da Standardwerte immer zuerst angewendet werden. +Richtlinien, die `params` akzeptieren, deklarieren ein `PolicyParamsSchema` mit Typen und Standardwerten für jeden Parameter. Der Richtlinienauswerter fügt aufgelöste Werte in `ctx.params` ein, bevor `fn` aufgerufen wird. Richtlinienfunktionen lesen `ctx.params` ohne Null-Prüfung, da Standardwerte immer zuerst angewendet werden. -Musterabgleiche innerhalb von Richtlinien verwenden geparste Befehls-Tokens (argv) statt einfachem String-Matching. Dadurch werden Umgehungen durch Shell-Operator-Injection verhindert (z. B. kann ein Muster für `sudo systemctl status *` nicht durch Anhängen von `; rm -rf /` an den Befehl umgangen werden). +Die Mustererkennung innerhalb von Richtlinien verwendet geparste Befehlstoken (argv), keine reine Zeichenkettensuche. Dies verhindert Umgehungsversuche durch Shell-Operator-Injektion (z. B. kann ein Muster für `sudo systemctl status *` nicht durch Anhängen von `; rm -rf /` an den Befehl umgangen werden). --- @@ -229,21 +229,21 @@ export function clearCustomHooks(): void { ... } // used in tests 1. `customPoliciesPath` aus der Konfiguration lesen; überspringen, falls nicht vorhanden. 2. Auf absoluten Pfad auflösen; prüfen, ob die Datei existiert. -3. Alle `from "failproofai"`-Importe auf den tatsächlichen dist-Pfad umschreiben, sodass `customPolicies` auf dieselbe `globalThis`-Registrierung zeigt. +3. Alle `from "failproofai"`-Importe zum tatsächlichen dist-Pfad umschreiben, damit `customPolicies` auf dieselbe `globalThis`-Registrierung verweist. 4. Transitive lokale Importe rekursiv umschreiben, um ESM-Kompatibilität sicherzustellen. 5. Temporäre `.mjs`-Dateien schreiben und die Einstiegsdatei per `import()` laden. 6. `getCustomHooks()` aufrufen, um registrierte Hooks abzurufen. 7. Alle temporären Dateien in einem `finally`-Block bereinigen. -Bei jedem Fehler (Datei nicht gefunden, Syntaxfehler, Import-Fehler) wird der Fehler in `~/.failproofai/hook.log` protokolliert und der Loader gibt ein leeres Array zurück. Integrierte Richtlinien sind davon nicht betroffen. +Bei einem Fehler (Datei nicht gefunden, Syntaxfehler, Import-Fehler) wird der Fehler in `~/.failproofai/hook.log` protokolliert und der Loader gibt ein leeres Array zurück. Eingebaute Richtlinien sind nicht betroffen. -Benutzerdefinierte Richtlinien werden nach allen integrierten Richtlinien ausgewertet. Ein `deny` einer benutzerdefinierten Richtlinie unterbricht zwar weitere benutzerdefinierte Richtlinien (alle integrierten wurden zu diesem Zeitpunkt jedoch bereits ausgeführt). +Benutzerdefinierte Richtlinien werden nach allen eingebauten Richtlinien ausgewertet. Ein `deny` einer benutzerdefinierten Richtlinie bricht weitere benutzerdefinierte Richtlinien ab (alle eingebauten wurden jedoch zu diesem Zeitpunkt bereits ausgeführt). --- ## Aktivitätsprotokollierung -Nach jedem Hook-Ereignis fügt der Handler eine JSONL-Zeile an `~/.failproofai/hook-activity.jsonl` an: +Nach jedem Hook-Ereignis hängt der Handler eine JSONL-Zeile an `~/.failproofai/hook-activity.jsonl` an: ```json { @@ -258,7 +258,7 @@ Nach jedem Hook-Ereignis fügt der Handler eine JSONL-Zeile an `~/.failproofai/h } ``` -Pro Richtlinie, die eine Nicht-Erlauben-Entscheidung getroffen hat, wird eine Zeile geschrieben. Erlauben-Entscheidungen werden nicht protokolliert (um die Dateigröße gering zu halten). +Eine Zeile pro Richtlinie, die eine Nicht-allow-Entscheidung getroffen hat. Allow-Entscheidungen werden nicht protokolliert (um die Datei klein zu halten). --- @@ -278,7 +278,7 @@ app/ get-hooks-config.ts ← Konfiguration + Richtlinienliste lesen update-hooks-config.ts ← Richtlinie aktivieren/deaktivieren update-policy-params.ts ← Richtlinienparameter aktualisieren - get-hook-activity.ts ← Aktivitätsprotokoll blättern/durchsuchen + get-hook-activity.ts ← Aktivitätsprotokoll seitenweise abrufen/durchsuchen install-hooks-web.ts ← Hooks über den Browser installieren/entfernen api/ download/[project]/[session]/route.ts ← Sitzungsexport pro CLI (JSONL oder JSON) @@ -286,16 +286,16 @@ app/ **Datenfluss:** -- Seitenkomponenten rufen `lib/projects.ts` und `lib/log-entries.ts` auf, um Projekt-/Sitzungsdaten direkt aus dem Dateisystem zu lesen (keine API-Schicht für Lesevorgänge). -- Die Policies-Seite verwendet Server Actions für alle Mutationen (Umschalten, Parameteraktualisierung, Installieren/Entfernen). -- Der Sitzungs-Viewer parst das JSONL-Transkriptformat von Claude und rendert eine Zeitleiste mit Nachrichten und Tool-Aufrufen. +- Seitenkomponenten rufen `lib/projects.ts` und `lib/log-entries.ts` auf, um Projekt-/Sitzungsdaten direkt aus dem Dateisystem zu lesen (keine API-Schicht für Lesezugriffe). +- Die Policies-Seite verwendet Server Actions für alle Mutationen (Umschalten, Parameter-Aktualisierung, Installieren/Entfernen). +- Der Sitzungsbetrachter parst das JSONL-Transkriptformat von Claude und rendert eine Zeitleiste mit Nachrichten und Tool-Aufrufen. **Wichtige Designentscheidungen:** - Keine Datenbank – alle persistenten Zustände liegen in einfachen Dateien (`~/.failproofai/`, `~/.claude/projects/`). -- Server Actions für Mutationen – keine REST-API für CRUD-Operationen erforderlich. -- React Server Components für Leseseiten – schnelleres initiales Laden, kein Client-Bundle für das Datenabrufen. -- Client-Komponenten nur dort, wo Interaktivität benötigt wird (Richtlinien-Umschalter, Aktivitätssuche, Log-Viewer). +- Server Actions für Mutationen – kein REST-API für CRUD-Operationen erforderlich. +- React Server Components für Leseseiten – schnelleres erstes Laden, kein Client-Bundle für das Datenabrufen. +- Client-Komponenten nur dort, wo Interaktivität benötigt wird (Richtlinien-Umschalter, Aktivitätssuche, Log-Betrachter). --- @@ -304,29 +304,29 @@ app/ ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # CLI-Router (Hook / Dashboard / Install / usw.) +│ └── failproofai.mjs # CLI-Router (hook / dashboard / install / etc.) ├── src/hooks/ │ ├── handler.ts # Hook-Ereignis-Pipeline │ ├── builtin-policies.ts # 39 Richtliniendefinitionen -│ ├── policy-evaluator.ts # Richtlinien-Ausführungsengine -│ ├── policy-registry.ts # Richtlinienregistrierung und -suche -│ ├── policy-types.ts # TypeScript-Interfaces -│ ├── hooks-config.ts # Mehrstufiges Konfigurationsladen +│ ├── policy-evaluator.ts # Richtlinienausführungs-Engine +│ ├── policy-registry.ts # Richtlinienregistrierung und -nachschlage +│ ├── policy-types.ts # TypeScript-Schnittstellen +│ ├── hooks-config.ts # Mehrstufiges Laden der Konfiguration │ ├── custom-hooks-registry.ts # globalThis-basierte Hook-Registrierung │ ├── custom-hooks-loader.ts # ESM-Loader für benutzerdefinierte JS-Hooks -│ ├── manager.ts # Installations-, Entfernungs- und Listenoperationen -│ ├── install-prompt.ts # Interaktive Richtlinienauswahlabfrage +│ ├── manager.ts # Installieren / Entfernen / Auflisten +│ ├── install-prompt.ts # Interaktive Richtlinienauswahl-Eingabeaufforderung │ ├── hook-logger.ts # Protokollierung in hook.log -│ ├── hook-activity-store.ts # Aktivität in hook-activity.jsonl persistieren +│ ├── hook-activity-store.ts # Aktivität in hook-activity.jsonl speichern │ └── llm-client.ts # LLM-API-Client (für KI-gestützte Richtlinien) ├── app/ # Next.js-Dashboard (Seiten + Server Actions) -├── lib/ # Gemeinsame Hilfsprogramme +├── lib/ # Gemeinsam genutzte Hilfsprogramme │ ├── projects.ts # Claude-Projekte aus dem Dateisystem aufzählen │ ├── log-entries.ts # Claude-Transkript-JSONL-Format parsen │ ├── paths.ts # Systempfade auflösen │ └── ... -├── components/ # Gemeinsame React-UI-Komponenten -├── contexts/ # React-Context-Provider (Theme, Auto-Refresh, Telemetrie) -├── examples/ # Beispieldateien für benutzerdefinierte Hooks +├── components/ # Gemeinsam genutzte React-UI-Komponenten +├── contexts/ # React-Kontextanbieter (Theme, Auto-Refresh, Telemetrie) +├── examples/ # Beispiel-Dateien für benutzerdefinierte Hooks └── __tests__/ # Unit- und E2E-Tests ``` \ No newline at end of file diff --git a/docs/de/built-in-policies.mdx b/docs/de/built-in-policies.mdx index 38dd2cc2..c7bbeca4 100644 --- a/docs/de/built-in-policies.mdx +++ b/docs/de/built-in-policies.mdx @@ -1,10 +1,10 @@ --- title: Integrierte Richtlinien -description: "Alle 39 integrierten Richtlinien, die häufige Fehlerquellen von Agenten abfangen" +description: "Alle 39 integrierten Richtlinien, die häufige Fehlerszenarien von Agenten abfangen" icon: shield --- -failproofai enthält 39 integrierte Richtlinien, die häufige Fehlerquellen von Agenten abfangen. Jede Richtlinie wird bei einem bestimmten Hook-Ereignistyp und Tool-Namen ausgelöst. Neunzehn Richtlinien akzeptieren Parameter, mit denen Sie ihr Verhalten anpassen können, ohne Code zu schreiben. Fünf Workflow-Richtlinien erzwingen eine Commit → Push → PR → CI-Pipeline, bevor Claude anhält. +failproofai enthält 39 integrierte Richtlinien, die häufige Fehlerszenarien von Agenten abfangen. Jede Richtlinie wird für einen bestimmten Hook-Ereignistyp und Toolnamen ausgelöst. Neunzehn Richtlinien akzeptieren Parameter, mit denen Sie ihr Verhalten anpassen können, ohne Code zu schreiben. Fünf Workflow-Richtlinien erzwingen eine Commit → Push → PR → CI-Pipeline, bevor Claude anhält. --- @@ -15,8 +15,8 @@ Richtlinien sind in Kategorien gruppiert: | Kategorie | Richtlinien | Hook-Typ | |----------|----------|-----------| | [Gefährliche Befehle](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | -| [Infrastrukturbefehle](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [Geheimnisse (Sanitizer)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [Infra-Befehle](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | +| [Secrets (Sanitizer)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | | [Umgebung](#environment) | block-env-files, protect-env-vars | PreToolUse | | [Dateizugriff](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | @@ -27,13 +27,13 @@ Richtlinien sind in Kategorien gruppiert: - **`block-`** — verhindert, dass der Agent fortfährt. - **`warn-`** — gibt dem Agenten zusätzlichen Kontext, damit er sich selbst korrigieren kann. -- **`sanitize-`** — bereinigt sensible Daten aus der Tool-Ausgabe, bevor der Agent sie sieht. +- **`sanitize-`** — entfernt vertrauliche Daten aus der Tool-Ausgabe, bevor der Agent sie sieht. ### Namespaces -Jede Richtlinie befindet sich in einem `/`-Slot. Integrierte Richtlinien gehören zum **`failproofai/`**-Namespace — zum Beispiel `failproofai/sanitize-jwt`. Der Namespace verhindert Kollisionen, wenn Sie auch benutzerdefinierte oder Drittanbieter-Richtlinien mit ähnlichen Kurznamen laden. +Jede Richtlinie befindet sich in einem `/`-Slot. Integrierte Richtlinien gehören zum **`failproofai/`**-Namespace — zum Beispiel `failproofai/sanitize-jwt`. Der Namespace verhindert Konflikte, wenn Sie auch benutzerdefinierte oder Drittanbieter-Richtlinien mit ähnlichen Kurznamen laden. -In Ihrer Konfiguration können Sie auf eine integrierte Richtlinie entweder mit ihrem Kurznamen oder ihrem qualifizierten Namen verweisen; beide Formen lösen sich zur selben Richtlinie auf: +In Ihrer Konfiguration können Sie eine integrierte Richtlinie entweder über ihren Kurznamen oder ihren qualifizierten Namen referenzieren; beide Formen lösen sich zur gleichen Richtlinie auf: ```json { @@ -44,13 +44,13 @@ In Ihrer Konfiguration können Sie auf eine integrierte Richtlinie entweder mit } ``` -Enthält ein Name kein `/`, behandelt failproofai ihn als zum Standard-Namespace `failproofai` gehörend. Namen, die bereits ein `/` enthalten (z. B. `myorg/foo`, `custom/my-hook`), werden unverändert übernommen. +Wenn ein Name kein `/` enthält, behandelt failproofai ihn als zum Standard-Namespace `failproofai` gehörend. Namen, die bereits ein `/` enthalten (z.B. `myorg/foo`, `custom/my-hook`), werden unverändert übernommen. - **`require-`** — blockiert das Stop-Ereignis, bis die Bedingungen erfüllt sind. --- -Jede Richtlinie unterstützt ein optionales `hint`-Feld in `policyParams`. Der Hinweis wird an die deny- oder instruct-Nachricht angehängt, die Claude sieht, und gibt handlungsorientierte Hinweise, ohne den Richtliniencode zu ändern. Funktioniert mit integrierten, benutzerdefinierten und konventionsbasierten Richtlinien. Siehe [Konfiguration → hint](/de/configuration#hint-cross-cutting) für Details. +Jede Richtlinie unterstützt ein optionales `hint`-Feld in `policyParams`. Der Hinweis wird an die deny- oder instruct-Nachricht angehängt, die Claude sieht, und gibt umsetzbare Anweisungen, ohne den Richtliniencode zu ändern. Funktioniert mit integrierten, benutzerdefinierten und konventionsbasierten Richtlinien. Weitere Informationen finden Sie unter [Konfiguration → hint](/de/configuration#hint-cross-cutting). --- @@ -64,7 +64,7 @@ Verhindert, dass Agenten Operationen ausführen, die schwer rückgängig zu mach **Ereignis:** PreToolUse (Bash) **Standard:** Verweigert jeden `sudo`-Befehl. -Blockiert Aufrufe, die das `sudo`-Schlüsselwort enthalten. Der Musterabgleich erfolgt auf geparsten Befehls-Tokens, nicht auf dem Rohstring, um Umgehungsversuche durch Shell-Operator-Injection zu verhindern. +Blockiert Aufrufe, die das Schlüsselwort `sudo` enthalten. Der Musterabgleich erfolgt auf geparsten Befehls-Tokens, nicht auf dem rohen String, um Umgehungsversuche über Shell-Operator-Injektion zu verhindern. **Parameter:** @@ -87,7 +87,7 @@ Blockiert Aufrufe, die das `sudo`-Schlüsselwort enthalten. Der Musterabgleich e Mit dieser Konfiguration ist `sudo systemctl status nginx` erlaubt, aber `sudo rm /etc/hosts` wird verweigert. -Muster werden gegen geparste Tokens abgeglichen, nicht gegen den Rohbefehlsstring. Dies verhindert Umgehungsversuche durch angehängte Shell-Operatoren (z. B. `sudo systemctl status x; rm -rf /` entspricht nicht `sudo systemctl status *`). +Muster werden gegen geparste Tokens abgeglichen, nicht gegen den rohen Befehlsstring. Dies verhindert Umgehungsversuche über angehängte Shell-Operatoren (z.B. führt `sudo systemctl status x; rm -rf /` nicht zu einer Übereinstimmung mit `sudo systemctl status *`). --- @@ -101,7 +101,7 @@ Muster werden gegen geparste Tokens abgeglichen, nicht gegen den Rohbefehlsstrin | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Pfade, die sicher rekursiv gelöscht werden dürfen (z. B. `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Pfade, die sicher rekursiv gelöscht werden dürfen (z.B. `/tmp`). | **Beispiel:** @@ -129,17 +129,17 @@ Keine Parameter. ### `block-failproofai-commands` **Ereignis:** PreToolUse (Bash) -**Standard:** Verweigert Befehle, die failproofai selbst deinstallieren oder deaktivieren würden (z. B. `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Standard:** Verweigert Befehle, die failproofai selbst deinstallieren oder deaktivieren würden (z.B. `npm uninstall failproofai`, `failproofai policies --uninstall`). Keine Parameter. --- -## Infrastrukturbefehle +## Infra-Befehle -Verhindert, dass Coding-Agenten Infrastruktur-CLIs ausführen oder CI/CD-Pipelines auslösen. Alle Richtlinien in dieser Kategorie sind **opt-in** (`defaultEnabled: false`) — Agenten, die legitim `kubectl`, `terraform` usw. aufrufen müssen, werden nicht beeinträchtigt, es sei denn, Sie aktivieren die Richtlinie. Wenn aktiviert, wird jeder Aufruf der entsprechenden CLI verweigert, es sei denn, der Befehl entspricht einem Eintrag in `allowPatterns`. +Verhindert, dass Coding-Agenten Infrastruktur-CLIs ausführen oder CI/CD-Pipelines auslösen. Alle Richtlinien in dieser Kategorie sind **opt-in** (`defaultEnabled: false`) — Agenten, die legitimerweise `kubectl`, `terraform` usw. aufrufen müssen, werden nicht beeinträchtigt, es sei denn, Sie aktivieren die Richtlinie. Wenn aktiviert, wird jeder Aufruf der entsprechenden CLI verweigert, sofern der Befehl nicht einem Eintrag in `allowPatterns` entspricht. -Die Mustergrammatik ist dieselbe wie bei [`block-sudo`](#block-sudo): Tokens werden gegen geparste argv abgeglichen, `*` ist ein Platzhalter für ein Token, und jeder Befehl, der einen eigenständigen Shell-Operator (`&&`, `||`, `|`, `;`) oder ein Token mit eingebetteten Shell-Metazeichen enthält, wird vor dem Allowlist-Abgleich abgelehnt, um Injection-Umgehungsversuche zu verhindern. +Die Muster-Grammatik ist dieselbe wie bei [`block-sudo`](#block-sudo): Tokens werden gegen geparste argv abgeglichen, `*` ist ein Platzhalter für ein Token, und jeder Befehl, der einen eigenständigen Shell-Operator (`&&`, `||`, `|`, `;`) oder ein Token mit eingebetteten Shell-Metazeichen enthält, wird vor dem Allowlist-Abgleich abgelehnt, um Injektionsumgehungen zu verhindern. ### `block-kubectl` @@ -171,7 +171,7 @@ Mit dieser Konfiguration ist `kubectl get pods` erlaubt, aber `kubectl apply -f ### `block-terraform` **Ereignis:** PreToolUse (Bash) -**Standard:** Verweigert jeden `terraform`- oder `tofu`-Aufruf (OpenTofu). +**Standard:** Verweigert jeden `terraform`- oder `tofu`-(OpenTofu-)Aufruf. **Parameter:** @@ -221,7 +221,7 @@ Mit dieser Konfiguration ist `kubectl get pods` erlaubt, aber `kubectl apply -f ### `block-gcloud` **Ereignis:** PreToolUse (Bash) -**Standard:** Verweigert jeden `gcloud`-CLI-Aufruf (Google Cloud). +**Standard:** Verweigert jeden `gcloud`-(Google Cloud-)CLI-Aufruf. **Parameter:** @@ -246,7 +246,7 @@ Mit dieser Konfiguration ist `kubectl get pods` erlaubt, aber `kubectl apply -f ### `block-az-cli` **Ereignis:** PreToolUse (Bash) -**Standard:** Verweigert jeden `az`-CLI-Aufruf (Azure). +**Standard:** Verweigert jeden `az`-(Azure-)CLI-Aufruf. **Parameter:** @@ -296,7 +296,7 @@ Mit dieser Konfiguration ist `kubectl get pods` erlaubt, aber `kubectl apply -f ### `block-gh-pipeline` **Ereignis:** PreToolUse (Bash) -**Standard:** Verweigert die folgenden `gh`-CLI-Unterbefehle, die den Zustand ändern oder Pipelines auslösen: +**Standard:** Verweigert die folgenden `gh`-CLI-Unterbefehle, die den Zustand verändern oder Pipelines auslösen: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -305,13 +305,13 @@ Mit dieser Konfiguration ist `kubectl get pods` erlaubt, aber `kubectl apply -f - `gh cache delete` - `gh secret set`, `gh secret delete` -Schreibgeschützte `gh`-Unterbefehle wie `gh pr view`, `gh pr list`, `gh run list`, `gh release view` und `gh api repos/.../...` werden von dieser Richtlinie **nicht** erfasst — sie werden routinemäßig für Workflow-Prüfungen benötigt (einschließlich failproofais eigenem `require-ci-green-before-stop`). +Schreibgeschützte `gh`-Unterbefehle wie `gh pr view`, `gh pr list`, `gh run list`, `gh release view` und `gh api repos/.../...` werden von dieser Richtlinie **nicht** erfasst — sie werden routinemäßig für Workflow-Prüfungen benötigt (einschließlich failproofai's eigenem `require-ci-green-before-stop`). **Parameter:** | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Bestimmte skriptierte Aufrufe, die erlaubt werden sollen, auch wenn sie andernfalls verweigert würden. | +| `allowPatterns` | `string[]` | `[]` | Bestimmte skriptgesteuerte Aufrufe, die erlaubt werden sollen, obwohl sie sonst verweigert würden. | **Beispiel:** @@ -327,9 +327,9 @@ Schreibgeschützte `gh`-Unterbefehle wie `gh pr view`, `gh pr list`, `gh run lis --- -## Geheimnisse (Sanitizer) +## Secrets (Sanitizer) -Verhindert, dass Agenten Anmeldeinformationen in ihren Kontext oder ihre Ausgabe weitergeben. Sanitizer-Richtlinien werden bei **PostToolUse**-Ereignissen ausgelöst. Wenn Claude einen Bash-Befehl ausführt, eine Datei liest oder ein Tool aufruft, prüfen diese Richtlinien die Ausgabe, bevor sie an Claude zurückgegeben wird. Wenn ein Geheimnis-Muster erkannt wird, gibt die Richtlinie eine Verweigerungsentscheidung zurück, die verhindert, dass die Ausgabe weitergeleitet wird. +Verhindert, dass Agenten Zugangsdaten in ihren Kontext oder ihre Ausgabe einschleusen. Sanitizer-Richtlinien werden bei **PostToolUse**-Ereignissen ausgelöst. Wenn Claude einen Bash-Befehl ausführt, eine Datei liest oder ein Tool aufruft, prüfen diese Richtlinien die Ausgabe, bevor sie an Claude zurückgegeben wird. Wenn ein Secret-Muster erkannt wird, gibt die Richtlinie eine Verweigerungsentscheidung zurück, die verhindert, dass die Ausgabe weitergeleitet wird. ### `sanitize-jwt` @@ -343,13 +343,13 @@ Keine Parameter. ### `sanitize-api-keys` **Ereignis:** PostToolUse (alle Tools) -**Standard:** Schwärzt gängige API-Schlüsselformate: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS-Zugriffsschlüssel (`AKIA`), Stripe-Schlüssel (`sk_live_`, `sk_test_`) und Google-API-Schlüssel (`AIza`). +**Standard:** Schwärzt gängige API-Key-Formate: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS-Zugriffsschlüssel (`AKIA`), Stripe-Schlüssel (`sk_live_`, `sk_test_`) und Google API-Schlüssel (`AIza`). **Parameter:** | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Zusätzliche Regex-Muster, die als Geheimnisse behandelt werden sollen. | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Zusätzliche Regex-Muster, die als Secrets behandelt werden sollen. | **Beispiel:** @@ -371,7 +371,7 @@ Keine Parameter. ### `sanitize-connection-strings` **Ereignis:** PostToolUse (alle Tools) -**Standard:** Schwärzt Datenbankverbindungsstrings, die eingebettete Anmeldeinformationen enthalten (z. B. `postgresql://user:password@host/db`). +**Standard:** Schwärzt Datenbankverbindungszeichenfolgen, die eingebettete Zugangsdaten enthalten (z.B. `postgresql://user:password@host/db`). Keine Parameter. @@ -397,12 +397,12 @@ Keine Parameter. ## Umgebung -Schützt sensible Umgebungskonfigurationen davor, von Agenten gelesen oder offengelegt zu werden. +Schützt vertrauliche Umgebungskonfigurationen davor, von Agenten gelesen oder offengelegt zu werden. ### `block-env-files` **Ereignis:** PreToolUse (Bash, Read) -**Standard:** Verweigert das Lesen von `.env`-Dateien über `cat .env`, Read-Tool-Aufrufe mit `.env` als Dateipfad usw. +**Standard:** Verweigert das Lesen von `.env`-Dateien über `cat .env`, `Read`-Tool-Aufrufe mit `.env` als Dateipfad usw. Blockiert nicht `.envrc` oder andere umgebungsnahe Dateien — nur Dateien, die exakt `.env` heißen. @@ -421,12 +421,12 @@ Keine Parameter. ## Dateizugriff -Hält Agenten innerhalb der Projektgrenzen und fernab von sensiblen Dateien. +Hält Agenten innerhalb der Projektgrenzen und fernab von vertraulichen Dateien. ### `block-read-outside-cwd` **Ereignis:** PreToolUse (Read, Bash) -**Standard:** Verweigert das Lesen von Dateien außerhalb des Projektstamms. Die Grenze ist `CLAUDE_PROJECT_DIR` (einmal pro Sitzung von Claude Code gesetzt), mit einem Fallback auf das aktuelle Arbeitsverzeichnis der Sitzung, wenn diese Variable nicht gesetzt ist. Die Verwendung des Projektstamms anstelle des Live-`cwd` bedeutet, dass die Grenze auch dann stabil bleibt, wenn Claude in ein Unterverzeichnis wechselt. +**Standard:** Verweigert das Lesen von Dateien außerhalb des Projektstamms. Die Grenze ist `CLAUDE_PROJECT_DIR` (einmalig pro Sitzung von Claude Code gesetzt), mit einem Fallback auf das aktuelle Arbeitsverzeichnis der Sitzung, wenn diese Variable nicht gesetzt ist. Die Verwendung des Projektstamms anstelle des Live-`cwd` bedeutet, dass die Grenze stabil bleibt, auch nachdem Claude in ein Unterverzeichnis gewechselt hat. **Parameter:** @@ -451,7 +451,7 @@ Hält Agenten innerhalb der Projektgrenzen und fernab von sensiblen Dateien. ### `block-secrets-write` **Ereignis:** PreToolUse (Write, Edit) -**Standard:** Verweigert Schreibvorgänge in Dateien, die häufig für private Schlüssel und Zertifikate verwendet werden: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Standard:** Verweigert Schreibvorgänge in Dateien, die üblicherweise für private Schlüssel und Zertifikate verwendet werden: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Parameter:** @@ -501,7 +501,7 @@ Verhindert versehentliche Pushes, Force-Pushes und Branch-Fehler, die schwer rü ``` -Um das Pushen auf alle Branches zu erlauben (was diese Richtlinie effektiv deaktiviert, ohne sie aus `enabledPolicies` zu entfernen), setzen Sie `protectedBranches: []`. +Um das Pushen auf alle Branches zu erlauben (wodurch diese Richtlinie effektiv deaktiviert wird, ohne sie aus `enabledPolicies` zu entfernen), setzen Sie `protectedBranches: []`. --- @@ -509,7 +509,7 @@ Um das Pushen auf alle Branches zu erlauben (was diese Richtlinie effektiv deakt ### `block-work-on-main` **Ereignis:** PreToolUse (Bash) -**Standard:** Verweigert `git commit`, `git merge`, `git rebase` und `git cherry-pick`, während sich der Working Tree auf `main` oder `master` befindet. Branch-Erstellung und -Wechsel (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) sind nicht betroffen. +**Standard:** Verweigert `git commit`, `git merge`, `git rebase` und `git cherry-pick`, wenn sich der Working Tree auf `main` oder `master` befindet. Branch-Erstellung und -Wechsel (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) sind nicht betroffen. **Parameter:** @@ -524,7 +524,7 @@ Um das Pushen auf alle Branches zu erlauben (was diese Richtlinie effektiv deakt **Ereignis:** PreToolUse (Bash) **Standard:** Verweigert `git push --force` und `git push -f`. -Keine richtlinienspezifischen Parameter. Verwenden Sie das übergreifende [`hint`](/de/configuration#hint-cross-cutting), um Alternativen vorzuschlagen: +Keine richtlinienspezifischen Parameter. Verwenden Sie den übergreifenden [`hint`](/de/configuration#hint-cross-cutting), um Alternativen vorzuschlagen: ```json { @@ -550,7 +550,7 @@ Keine Parameter. ### `warn-git-stash-drop` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, vor dem Ausführen von `git stash drop` zu bestätigen. Blockiert den Befehl nicht. +**Standard:** Weist Claude an, vor der Ausführung von `git stash drop` zu bestätigen. Blockiert den Befehl nicht. Keine Parameter. @@ -567,12 +567,12 @@ Keine Parameter. ## Datenbank -Erkennt destruktive SQL-Operationen, bevor sie gegen Ihre Datenbank ausgeführt werden. +Fängt destruktive SQL-Operationen ab, bevor sie gegen Ihre Datenbank ausgeführt werden. ### `warn-destructive-sql` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, zu bestätigen, bevor SQL ausgeführt wird, das `DROP TABLE`, `DROP DATABASE` oder `DELETE` ohne `WHERE`-Klausel enthält. +**Standard:** Weist Claude an, vor der Ausführung von SQL mit `DROP TABLE`, `DROP DATABASE` oder `DELETE` ohne `WHERE`-Klausel zu bestätigen. Keine Parameter. @@ -581,7 +581,7 @@ Keine Parameter. ### `warn-schema-alteration` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, zu bestätigen, bevor `ALTER TABLE`-Anweisungen ausgeführt werden. +**Standard:** Weist Claude an, vor der Ausführung von `ALTER TABLE`-Anweisungen zu bestätigen. Keine Parameter. @@ -594,13 +594,13 @@ Gibt Agenten zusätzlichen Kontext vor potenziell riskanten, aber nicht destrukt ### `warn-large-file-write` **Ereignis:** PreToolUse (Write) -**Standard:** Weist Claude an, zu bestätigen, bevor Dateien größer als 1024 KB geschrieben werden. +**Standard:** Weist Claude an, vor dem Schreiben von Dateien größer als 1024 KB zu bestätigen. **Parameter:** | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | Dateigrößenschwellenwert in Kilobyte, ab dem eine Warnung ausgegeben wird. | +| `thresholdKb` | `number` | `1024` | Dateigröße in Kilobyte, ab der eine Warnung ausgegeben wird. | **Beispiel:** @@ -615,7 +615,7 @@ Gibt Agenten zusätzlichen Kontext vor potenziell riskanten, aber nicht destrukt ``` -Der Hook-Handler erzwingt ein stdin-Limit von 1 MB für Payloads. Um diese Richtlinie mit kleinem Inhalt zu testen, setzen Sie `thresholdKb` auf einen Wert deutlich unterhalb von 1024. +Der Hook-Handler erzwingt ein stdin-Limit von 1 MB für Payloads. Um diese Richtlinie mit kleinen Inhalten zu testen, setzen Sie `thresholdKb` auf einen Wert deutlich unter 1024. --- @@ -623,7 +623,7 @@ Der Hook-Handler erzwingt ein stdin-Limit von 1 MB für Payloads. Um diese Richt ### `warn-package-publish` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, zu bestätigen, bevor `npm publish` ausgeführt wird. +**Standard:** Weist Claude an, vor der Ausführung von `npm publish` zu bestätigen. Keine Parameter. @@ -641,7 +641,7 @@ Keine Parameter. ### `warn-global-package-install` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, zu bestätigen, bevor `npm install -g`, `yarn global add` oder `pip install` ohne virtuelle Umgebung ausgeführt wird. +**Standard:** Weist Claude an, vor der Ausführung von `npm install -g`, `yarn global add` oder `pip install` ohne virtuelle Umgebung zu bestätigen. Keine Parameter. @@ -654,16 +654,16 @@ Legt fest, welche Paketmanager der Agent verwenden darf. ### `prefer-package-manager` **Ereignis:** PreToolUse (Bash) -**Standard:** Deaktiviert. Wenn aktiviert, blockiert es jeden Paketmanager-Befehl, der nicht in der `allowed`-Liste steht, und weist Claude an, den Befehl mit einem erlaubten Manager umzuschreiben. +**Standard:** Deaktiviert. Wenn aktiviert, blockiert alle Paketmanager-Befehle, die nicht in der `allowed`-Liste stehen, und teilt Claude mit, den Befehl mit einem erlaubten Manager umzuschreiben. Erkennt: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | Parameter | Typ | Standard | Beschreibung | |-----------|------|---------|-------------| | `allowed` | string[] | `[]` | Erlaubte Paketmanager-Namen. Jeder erkannte Manager, der nicht in dieser Liste steht, wird blockiert. Wenn leer, ist die Richtlinie wirkungslos. | -| `blocked` | string[] | `[]` | Zusätzliche Manager-Namen, die über die integrierte Liste hinaus blockiert werden sollen (z. B. `['pdm', 'pipx']`). | +| `blocked` | string[] | `[]` | Zusätzliche Manager-Namen, die über die integrierte Liste hinaus blockiert werden sollen (z.B. `['pdm', 'pipx']`). | -Die integrierte Blockliste umfasst: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Verwenden Sie `blocked`, um Manager hinzuzufügen, die nicht in dieser Liste enthalten sind. +Die integrierte Blockliste umfasst: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Verwenden Sie `blocked`, um Manager hinzuzufügen, die nicht in dieser Liste sind. **Beispielkonfiguration:** @@ -679,18 +679,18 @@ Die integrierte Blockliste umfasst: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, } ``` -Mit dieser Konfiguration werden `pip install flask` und `pdm install flask` beide verweigert, mit einer Meldung, die Claude auffordert, stattdessen `uv` oder `bun` zu verwenden. Befehle wie `uv pip install flask` sind erlaubt, da `uv` in der Allowlist steht und zuerst geprüft wird. +Mit dieser Konfiguration werden `pip install flask` und `pdm install flask` beide verweigert, mit einer Nachricht, die Claude auffordert, stattdessen `uv` oder `bun` zu verwenden. Befehle wie `uv pip install flask` sind erlaubt, da `uv` in der Allowlist steht und zuerst geprüft wird. --- ## KI-Verhalten -Erkennt, wenn Agenten feststecken oder sich unerwartet verhalten. +Erkennt, wenn Agenten stecken bleiben oder sich unerwartet verhalten. ### `warn-repeated-tool-calls` **Ereignis:** PreToolUse (alle Tools) -**Standard:** Weist Claude an, neu zu überlegen, wenn dasselbe Tool 3+ Mal mit identischen Parametern aufgerufen wird — ein häufiges Zeichen dafür, dass der Agent in einer Schleife feststeckt. +**Standard:** Weist Claude an, seine Vorgehensweise zu überdenken, wenn dasselbe Tool drei oder mehr Mal mit identischen Parametern aufgerufen wird — ein häufiges Zeichen dafür, dass der Agent in einer Schleife steckt. Keine Parameter. @@ -698,40 +698,40 @@ Keine Parameter. ## Workflow -Erzwingt einen disziplinierten Workflow am Sitzungsende. Diese Richtlinien werden beim **Stop**-Ereignis ausgelöst und verhindern, dass der Agent anhält, bis jede Bedingung erfüllt ist. Sie folgen einer natürlichen Abhängigkeitskette: Commit → Push → PR → CI. Wenn eine Richtlinie verweigert, werden spätere Richtlinien in der Kette übersprungen (Kurzschluss bei Verweigerung). +Erzwingt einen disziplinierten Workflow am Sitzungsende. Diese Richtlinien werden beim **Stop**-Ereignis ausgelöst und verhindern, dass der Agent anhält, bis jede Bedingung erfüllt ist. Sie folgen einer natürlichen Abhängigkeitskette: Commit → Push → PR → CI. Wenn eine Richtlinie verweigert, werden spätere Richtlinien in der Kette übersprungen (Deny bricht ab). -Alle Workflow-Richtlinien sind **fail-open**: Wenn das erforderliche Tool nicht verfügbar ist (z. B. `gh` nicht installiert, kein Git-Remote), erlaubt die Richtlinie den Vorgang mit einer informativen Meldung, die erklärt, warum die Prüfung übersprungen wurde. +Alle Workflow-Richtlinien sind **fail-open**: Wenn das erforderliche Tool nicht verfügbar ist (z.B. `gh` nicht installiert, kein git-Remote), erlaubt die Richtlinie mit einer informativen Nachricht, die erklärt, warum die Prüfung übersprungen wurde. ### Stop-Semantik je CLI -Die Stop-Durchsetzung sieht bei den sieben unterstützten CLIs etwas unterschiedlich aus, da jede eine andere Vertragsform für den Hook "Agent fertig" bereitstellt. Das **Ergebnis** ist dasselbe — der Agent kommt nicht damit durch, anzuhalten, während ein Workflow-Gate fehlschlägt — aber die **Mechanik** unterscheidet sich. Die folgende Tabelle fasst dies zusammen; nur Pi hat eine für den Benutzer sichtbare Besonderheit, die es wert ist, sie zu verstehen, bevor Sie eine `require-*-before-stop`-Richtlinie aktivieren. +Die Stop-Durchsetzung sieht bei den sieben unterstützten CLIs etwas unterschiedlich aus, da jede eine andere Vertragsgestaltung für den Hook „Agent fertig" bietet. Das **Ergebnis** ist dasselbe — der Agent kommt nicht damit durch, anzuhalten, während ein Workflow-Gate fehlschlägt — aber die **Mechanik** unterscheidet sich. Die folgende Tabelle fasst dies zusammen; nur Pi hat eine für Benutzer sichtbare Besonderheit, die Sie verstehen sollten, bevor Sie eine `require-*-before-stop`-Richtlinie aktivieren. -| CLI | Wann das Gate ausgelöst wird | Was Sie sehen | +| CLI | Wann das Gate auslöst | Was Sie sehen | |---|---|---| -| Claude Code | Dieselbe Agentenschleife, sofort | Claude arbeitet weiter — behebt das Problem und versucht dann erneut zu beenden. Für Sie keine sichtbare Unterbrechung. | -| Codex | Dieselbe Agentenschleife, sofort | Wie bei Claude. | -| GitHub Copilot CLI | Dieselbe Agentenschleife, sofort | Wie bei Claude (verwendet Copilots `{decision:"block", reason}`-Retry-Kanal — empirisch gegen Copilot CLI 1.0.41 verifiziert). | -| Cursor Agent | Dieselbe Agentenschleife, sofort | Wie bei Claude (verwendet Cursors `{followup_message}`-Kanal — begrenzt durch `loop_limit`, Standard 5 Wiederholungen). | -| Gemini CLI | Dieselbe Agentenschleife, sofort | Wie bei Claude (verwendet Geminis `{decision:"block", reason}`-Kanal bei `AfterAgent`). | -| OpenCode | Dieselbe Agentenschleife, sofort | Wie bei Claude (verwendet OpenCodes `client.session.prompt(...)`-SDK-Aufruf, weitergeleitet über `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **Nächste Benutzerrunde** | **Pi hält sichtbar an**, wenn das Gate ausgelöst wird — seine Agentenschleife wird beendet und Sie kehren zur Eingabeaufforderung zurück. Das Gate wird dann beim nächsten Mal ausgelöst, wenn Sie eine Eingabeaufforderung senden: failproofai stellt eine `MANDATORY ACTION REQUIRED`-Direktive an den Beginn des System-Prompts dieser Runde und weist das LLM an, den Workflow-Schritt (Commit, Push usw.) abzuschließen, bevor es das Angeforderte tut. | +| Claude Code | Gleiche Agentenschleife, sofort | Claude arbeitet weiter — behebt das Problem, versucht dann erneut zu beenden. Für Sie keine sichtbare Unterbrechung. | +| Codex | Gleiche Agentenschleife, sofort | Wie Claude. | +| GitHub Copilot CLI | Gleiche Agentenschleife, sofort | Wie Claude (verwendet Copilots `{decision:"block", reason}`-Wiederholungskanal — empirisch verifiziert gegen Copilot CLI 1.0.41). | +| Cursor Agent | Gleiche Agentenschleife, sofort | Wie Claude (verwendet Cursors `{followup_message}`-Kanal — begrenzt auf `loop_limit`, standardmäßig 5 Wiederholungen). | +| Gemini CLI | Gleiche Agentenschleife, sofort | Wie Claude (verwendet Geminis `{decision:"block", reason}`-Kanal auf `AfterAgent`). | +| OpenCode | Gleiche Agentenschleife, sofort | Wie Claude (verwendet OpenCodes `client.session.prompt(...)`-SDK-Aufruf, der über `hookSpecificOutput.additionalContext` geleitet wird). | +| **Pi (pi-coding-agent)** | **Nächster Benutzerturn** | **Pi hält sichtbar an**, wenn das Gate auslöst — seine Agentenschleife beendet sich und Sie gelangen zurück zur Eingabeaufforderung. Das Gate löst dann beim nächsten Absenden einer Eingabe aus: failproofai stellt eine `MANDATORY ACTION REQUIRED`-Direktive an den Systempromt dieses Turns voran und weist das LLM an, den Workflow-Schritt (Commit, Push usw.) abzuschließen, bevor es das Gewünschte tut. | -**Pi-Einschränkung.** Pis `AgentEndEvent` (das Upstream-Äquivalent von Claudes `Stop`-Hook) hat keinen Result-Typ — wenn er ausgelöst wird, ist Pis Agentenschleife bereits beendet. Pi kann nicht gezwungen werden, dieselbe Schleife zu wiederholen, wie es Claude / Copilot / Cursor / Gemini / OpenCode können. failproofai verschiebt das Gate auf Pis `before_agent_start`-Ereignis (das nach der nächsten Benutzereingabe ausgelöst wird), damit die Workflow-Prüfung weiterhin erzwungen wird, allerdings erst in der nächsten Runde statt in der aktuellen. +**Pi-Einschränkung.** Pis `AgentEndEvent` (das Upstream-Äquivalent zu Claudes `Stop`-Hook) hat keinen Result-Typ — wenn er auslöst, hat Pis Agentenschleife bereits beendet. Pi kann nicht dazu gezwungen werden, dieselbe Schleife zu wiederholen, wie es Claude / Copilot / Cursor / Gemini / OpenCode können. failproofai verlagert das Gate auf Pis `before_agent_start`-Ereignis (das nach der nächsten Benutzereingabe auslöst), sodass die Workflow-Prüfung trotzdem greift, nur beim nächsten Turn statt beim aktuellen. **Was das in der Praxis bedeutet:** -- Nachdem Pi anhält, wird der Verweigerungsgrund im Arbeitsspeicher gespeichert, indexiert nach der Pi-Sitzungs-ID. Die nächste Eingabeaufforderung, die Sie in demselben Pi-Prozess senden, leert diesen Speicher: Das LLM sieht die `MANDATORY ACTION REQUIRED`-Direktive am Anfang seines System-Prompts, führt einen Commit durch (oder Push / öffnet den PR / wartet auf CI) und fährt dann erst mit Ihrer Anfrage fort. Der gespeicherte Verweigerungsgrund ist einmalig — sobald er geleert wurde, ist das Gate frei. -- Das Gate ist an die Lebensdauer des Pi-Prozesses gebunden. Wenn Sie Pi zwischen den Runden mit `Ctrl+C` beenden oder schließen, wird der Speichereintrag zusammen mit dem Prozess verworfen und das Gate wird verpasst. Claude, Copilot, Cursor, Gemini und OpenCode haben dieselbe Einschränkung (Agent beenden und das Gate wird verpasst) — Pi macht es nur sichtbarer, weil der Agent sichtbar beendet wird, bevor das Gate ausgelöst wird. -- Ein ausstehender Verweigerungsgrund wird auch bei `session_shutdown` aus beliebigem Grund (`new` / `resume` / `fork` / `quit`) gelöscht, sodass ein veraltetes Gate aus einer früheren Sitzung nicht in eine neue Sitzung im selben Pi-Prozess übertragen werden kann. +- Nachdem Pi anhält, wird der Ablehnungsgrund im Speicher gespeichert, indexiert nach Pi-Sitzungs-ID. Die nächste Eingabe, die Sie im selben Pi-Prozess absenden, entleert ihn: Das LLM sieht die `MANDATORY ACTION REQUIRED`-Direktive am Anfang seines Systemprompts, führt einen Commit durch (oder Push / öffnet den PR / wartet auf CI) und fährt erst dann mit Ihrer Anfrage fort. Der gespeicherte Ablehnungsgrund ist einmalig — sobald entleert, ist das Gate frei. +- Das Gate ist durch die Prozesslebensdauer von Pi begrenzt. Wenn Sie Pi zwischen den Turns mit `Ctrl+C` beenden oder schließen, wird der In-Memory-Eintrag zusammen mit dem Prozess gelöscht und das Gate wird verfehlt. Claude, Copilot, Cursor, Gemini und OpenCode haben dieselbe Einschränkung (Agent beenden und das Gate wird verfehlt) — bei Pi ist es nur sichtbarer, weil der Agent sichtbar beendet wird, bevor das Gate auslöst. +- Ein ausstehender Deny wird auch bei `session_shutdown` aus beliebigem Grund (`new` / `resume` / `fork` / `quit`) gelöscht, sodass ein veraltetes Gate einer vorherigen Sitzung nicht in eine neue Sitzung überlaufen kann, die im selben Pi-Prozess gestartet wurde. -Wenn Sie Claude-ähnliche Wiederholungen in derselben Schleife benötigen, führen Sie Ihre `Stop`-Richtlinien unter einer der anderen sechs unterstützten CLIs aus. Wir verfolgen Pi Upstream auf einen zukünftigen Result-Typ bei `AgentEndEvent`, der es uns ermöglichen würde, diese Lücke zu schließen. +Wenn Sie das Claude-ähnliche Wiederholen in derselben Schleife benötigen, führen Sie Ihre `Stop`-Richtlinien unter einer der anderen sechs unterstützten CLIs aus. Wir verfolgen Pi upstream auf einen zukünftigen Result-Typ bei `AgentEndEvent`, der es uns ermöglichen würde, diese Lücke zu schließen. ### `require-commit-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Anhalten, wenn uncommittete Änderungen vorhanden sind (geänderte, gestagete oder nicht verfolgte Dateien). Gibt eine informative Meldung zurück, wenn das Arbeitsverzeichnis sauber ist. +**Standard:** Verweigert das Anhalten, wenn nicht committete Änderungen vorhanden sind (geänderte, gestagete oder nicht verfolgte Dateien). Gibt eine informative Nachricht zurück, wenn das Arbeitsverzeichnis sauber ist. Keine Parameter. @@ -740,13 +740,13 @@ Keine Parameter. ### `require-push-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Anhalten, wenn es unpushed Commits gibt oder wenn der aktuelle Branch keinen Remote-Tracking-Branch hat. Schlägt `git push -u` vor, um bei Bedarf einen Tracking-Branch zu erstellen. Fails open, wenn kein Remote konfiguriert ist. +**Standard:** Verweigert das Anhalten, wenn nicht gepushte Commits vorhanden sind oder wenn der aktuelle Branch keinen Remote-Tracking-Branch hat. Schlägt bei Bedarf `git push -u` vor, um einen Tracking-Branch zu erstellen. Fail-open, wenn kein Remote konfiguriert ist. **Parameter:** | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | Remote-Name, auf den gepusht werden soll. | +| `remote` | `string` | `"origin"` | Remote-Name, zu dem gepusht wird. | **Beispiel:** @@ -765,14 +765,14 @@ Keine Parameter. ### `require-pr-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Anhalten, wenn kein Pull Request für den aktuellen Branch existiert oder wenn der vorhandene PR ohne Merge geschlossen wurde. Weist Claude an, einen PR mit `gh pr create` zu erstellen. Wenn der PR **gemergt** ist, erlaubt die Richtlinie den Vorgang (die Arbeit ist ausgeliefert) und der Hinweis empfiehlt, den Branch zu wechseln (`git checkout main && git pull`). +**Standard:** Verweigert das Anhalten, wenn kein Pull Request für den aktuellen Branch existiert oder wenn der vorhandene PR ohne Merge geschlossen wurde. Weist Claude an, einen PR mit `gh pr create` zu erstellen. Wenn der PR **gemergt** wurde, erlaubt die Richtlinie (die Arbeit ist ausgeliefert) und die Nachricht gibt den Hinweis, den Branch zu wechseln (`git checkout main && git pull`). Keine Parameter. -Diese Richtlinie erfordert, dass [GitHub CLI](https://cli.github.com/) (`gh`) installiert und authentifiziert ist. +Diese Richtlinie erfordert die Installation und Authentifizierung von [GitHub CLI](https://cli.github.com/) (`gh`). Führen Sie `gh auth login` mit einem persönlichen Zugriffstoken aus, das den `repo`-Scope für Lesezugriff auf -Pull Requests hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, schlägt die Richtlinie offen fehl und meldet den Grund an Claude. +Pull Requests hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, ist die Richtlinie fail-open und meldet den Grund an Claude. --- @@ -780,12 +780,12 @@ Pull Requests hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, s ### `require-no-conflicts-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Anhalten, wenn der aktuelle Branch nicht sauber in den Basis-Branch gemergt werden kann. Die Richtlinie prüft zunächst, ob auf GitHub ein `OPEN`-PR für den Branch existiert — ohne einen solchen gibt es kein Merge-Ziel, das erzwungen werden müsste, sodass die gesamte Richtlinie mit allow kurzgeschlossen wird. Sobald ein `OPEN`-PR bestätigt ist, werden zwei unabhängige Prüfungen durchgeführt: +**Standard:** Verweigert das Anhalten, wenn der aktuelle Branch nicht konfliktfrei in den Basis-Branch gemergt werden kann. Die Richtlinie bestätigt zunächst, dass für den Branch ein `OPEN`-PR auf GitHub vorhanden ist — ohne einen solchen gibt es kein Merge-Ziel zum Erzwingen, sodass die gesamte Richtlinie allow zurückgibt. Sobald ein `OPEN`-PR bestätigt wurde, laufen zwei unabhängige Prüfungen: -1. **Lokal** — `git merge-tree --write-tree --name-only origin/ HEAD`. Bei einem Konflikt nennt die Verweigerungsmeldung die betroffenen Dateien, damit Claude genau weiß, was aufgelöst werden muss. -2. **GitHub** — verwendet das bereits für die Vorprüfung abgerufene Ergebnis von `gh pr view --json mergeable,state`. Erkennt Konflikte, die ein veraltetes lokales `origin/` verpasst hätte (z. B. wenn jemand einen konfliktierenden PR auf `main` gemergt hat, seit dem letzten Fetch). Ein `CONFLICTING`-Ergebnis verweigert. Ein `UNKNOWN`-Ergebnis verweigert ebenfalls und weist Claude an, etwa 10 Sekunden zu warten und erneut zu prüfen, bevor ein weiterer Stoppversuch unternommen wird — dies verhindert falsch-negative Ergebnisse, während GitHub neu berechnet. +1. **Lokal** — `git merge-tree --write-tree --name-only origin/ HEAD`. Bei einem Konflikt nennt die Deny-Nachricht die konfliktbehafteten Dateien, damit Claude genau weiß, was zu lösen ist. +2. **GitHub** — verwendet das bereits beim Vorcheck abgerufene `gh pr view --json mergeable,state`-Ergebnis erneut. Fängt Konflikte ab, die ein veraltetes lokales `origin/` übersehen würde (z.B. wenn jemand einen konfliktbehafteten PR auf `main` seit dem letzten Fetch gemergt hat). Ein `CONFLICTING`-Ergebnis verweigert. Ein `UNKNOWN`-Ergebnis verweigert ebenfalls und weist Claude an, etwa 10 Sekunden zu warten und erneut zu prüfen, bevor ein erneuter Stoppversuch unternommen wird — dies verhindert falsche Negative, während GitHub neu berechnet. -Wird vollständig übersprungen (erlaubt), wenn: `gh` nicht installiert ist, kein PR für den Branch existiert, der PR-Status nicht `OPEN` ist (z. B. `MERGED`, `CLOSED`), oder `gh pr view` nicht parsierbare Ausgabe liefert. Schlägt auch offen fehl, wenn `origin/` lokal fehlt oder wenn keine Commits vor der Basis vorhanden sind — diese Layer-1-Fallbacks konsultieren trotzdem die gecachte PR-Merge-Fähigkeit, bevor sie erlauben. +Überspringt vollständig (erlaubt), wenn: `gh` nicht installiert ist, kein PR für den Branch vorhanden ist, der PR-Status nicht `OPEN` ist (z.B. `MERGED`, `CLOSED`), oder `gh pr view` nicht parsbare Ausgabe liefert. Fail-open auch wenn `origin/` lokal fehlt oder wenn keine Commits vor dem Basis-Branch vorhanden sind — diese Layer-1-Durchfälle konsultieren trotzdem die zwischengespeicherte PR-Zusammenführbarkeit, bevor sie erlauben. **Parameter:** @@ -794,7 +794,9 @@ Wird vollständig übersprungen (erlaubt), wenn: `gh` nicht installiert ist, kei | `baseBranch` | `string` | `"main"` | Basis-Branch, gegen den auf Konflikte geprüft wird. | -GitHub CLI (`gh`) ist für diese Richtlinie erforderlich. Die Richtlinie verwendet `gh pr view`, um zu bestätigen, dass ein `OPEN`-PR existiert, bevor eine Konfliktprüfung durchgeführt wird — ohne `gh` schließt die Richtlinie mit allow kurz. Führen Sie `gh auth login` mit einem persönlichen Zugriffstoken aus, das den `repo`-Scope für Lesezugriff auf Pull Requests hat. +GitHub CLI (`gh`) ist für diese Richtlinie erforderlich. Die Richtlinie verwendet `gh pr view`, um zu bestätigen, +dass ein `OPEN`-PR vorhanden ist, bevor eine Konfliktprüfung durchgeführt wird — ohne `gh` gibt die Richtlinie +allow zurück. Führen Sie `gh auth login` mit einem persönlichen Zugriffstoken aus, das den `repo`-Scope für Lesezugriff auf Pull Requests hat. --- @@ -802,14 +804,14 @@ GitHub CLI (`gh`) ist für diese Richtlinie erforderlich. Die Richtlinie verwend ### `require-ci-green-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Anhalten, wenn CI-Prüfungen fehlschlagen oder auf dem aktuellen Branch noch laufen. Prüft sowohl GitHub Actions-Workflow-Runs als auch Drittanbieter-Bot-Prüfungen (z. B. CodeRabbit, SonarCloud, Codecov). Behandelt `skipped`, `cancelled` und `neutral` als nicht fehlgeschlagen (letzteres deckt z. B. Socket Security-Warnungen bei PRs externer Mitwirkender ab, bei denen die App absichtlich neutral statt Erfolg/Fehler meldet). Gibt eine informative Meldung zurück, wenn alle Prüfungen bestanden sind. +**Standard:** Verweigert das Anhalten, wenn CI-Prüfungen fehlschlagen oder auf dem aktuellen Branch noch ausgeführt werden. Prüft sowohl GitHub Actions-Workflow-Runs als auch Drittanbieter-Bot-Prüfungen (z.B. CodeRabbit, SonarCloud, Codecov). Behandelt `skipped`-, `cancelled`- und `neutral`-Abschlüsse als nicht fehlerhaft (letzteres deckt z.B. Socket Security-Meldungen bei PRs externer Mitwirkender ab, bei denen die App absichtlich neutral statt success/failure meldet). Gibt eine informative Nachricht zurück, wenn alle Prüfungen bestanden sind. Keine Parameter. -Diese Richtlinie erfordert, dass [GitHub CLI](https://cli.github.com/) (`gh`) installiert und authentifiziert ist. +Diese Richtlinie erfordert die Installation und Authentifizierung von [GitHub CLI](https://cli.github.com/) (`gh`). Führen Sie `gh auth login` mit einem persönlichen Zugriffstoken aus, das den `repo`-Scope für Lesezugriff auf -Actions-Workflow-Runs und die Checks-API hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, schlägt die Richtlinie offen fehl und meldet den Grund an Claude. +Actions-Workflow-Runs und die Checks API hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, ist die Richtlinie fail-open und meldet den Grund an Claude. --- @@ -818,7 +820,7 @@ Actions-Workflow-Runs und die Checks-API hat. Wenn `gh` nicht installiert oder n ## Einzelne Richtlinien deaktivieren -Entfernen Sie eine bestimmte Richtlinie aus `enabledPolicies` in Ihrer Konfiguration oder deaktivieren Sie sie im Dashboard-Tab Richtlinien. +Entfernen Sie eine bestimmte Richtlinie aus `enabledPolicies` in Ihrer Konfiguration, oder deaktivieren Sie sie im Dashboard-Tab „Policies". ```json { diff --git a/docs/de/cli/audit.mdx b/docs/de/cli/audit.mdx index db6a1fe2..833e1a9d 100644 --- a/docs/de/cli/audit.mdx +++ b/docs/de/cli/audit.mdx @@ -1,25 +1,25 @@ --- title: Vergangene Sitzungen prüfen (Beta) -description: "Wie oft der Agent in vergangenen Transkripten verschwenderische oder riskante Aktionen ausgeführt hat" +description: "Zähle, wie oft der Agent bei vergangenen Transkripten verschwenderische oder riskante Aktionen durchgeführt hat" --- - **Beta-Funktion.** Das Audit wird als Beta ausgeliefert, während wir erstes Feedback sammeln. + **Beta-Funktion.** Das Audit wird als Beta ausgeliefert, während wir frühes Feedback sammeln. Der Detektor-Katalog und das Berichtsformat können sich vor dem nächsten stabilen Release ändern. Bitte öffne ein Issue, wenn etwas nicht stimmt. -Das Audit spielt vergangene Agent-CLI-Transkripte durch die Richtlinien-Engine von failproofai ab -und erstellt einen teilbaren, visuellen Bericht auf der **`/audit`-Dashboard-Seite** — -den Archetyp deines Agenten, einen Score von 0–100 und genau, welche Richtlinien was abgefangen hätten. +Das Audit spielt vergangene Agent-CLI-Transkripte durch die Richtlinien-Engine von failproofai +ab und erstellt einen teilbaren, visuellen Bericht auf der **`/audit`-Dashboard-Seite** – +den Archetyp deines Agenten, einen Score von 0–100 und genau welche Richtlinien was abgefangen hätten. ## Ausführen -Drei Einstiegswege — alle landen im gleichen `/audit`-Bericht. +Drei Einstiegsmöglichkeiten – alle landen im selben `/audit`-Bericht. -```bash npx (keine Installation) +```bash npx (no install) npx -y failproofai audit ``` @@ -27,7 +27,7 @@ npx -y failproofai audit failproofai audit ``` -```bash failproofai (Dashboard) +```bash failproofai (dashboard) failproofai ``` @@ -36,60 +36,60 @@ failproofai `npx -y failproofai audit` lädt failproofai herunter, führt den Scan durch und öffnet das - Dashboard — ohne vorherige Installation. + Dashboard für dich – nichts muss vorab installiert werden. `failproofai audit` führt den Scan im Terminal aus und öffnet anschließend automatisch `localhost:8020/audit`. - Starte `failproofai` und klicke in der Navigationsleiste auf **Audit** (zwischen Policies und + Führe `failproofai` aus und klicke in der Navigationsleiste auf **Audit** (zwischen Policies und Projects), oder öffne `/audit` direkt. - Führe `failproofai audit -h` (oder `--help`) aus, um die Nutzungshinweise anzuzeigen. Das Audit läuft **vollständig - offline** — kein Konto und keine Netzwerkverbindung erforderlich — und das Dashboard bleibt aktiv, + Führe `failproofai audit -h` (oder `--help`) aus, um die Verwendung anzuzeigen. Das Audit läuft **vollständig + offline** – kein Account oder Netzwerk erforderlich – und das Dashboard bleibt aktiv, bis du es mit `Ctrl+C` beendest. -Das Dashboard scannt vergangene Agent-CLI-Transkripte auf diesem Rechner (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) und zeigt, wie oft der Agent Dinge getan hat, die failproofai verhindern soll — Umgebungsvariablen-Prüfungen, Force-Pushes, redundante `cd `-Präfixe, Sleep-Polling-Schleifen, erneutes Lesen gerade bearbeiteter Dateien und mehr. +Das Dashboard scannt vergangene Agent-CLI-Transkripte auf diesem Rechner (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) und meldet, wie oft der Agent Dinge getan hat, die failproofai unterbinden soll – Env-Var-Prüfungen, Force-Pushes, redundante `cd `-Präfixe, Sleep-Polling-Schleifen, erneutes Einlesen gerade bearbeiteter Dateien und mehr. -Für jedes Transkript wird jedes Tool-Use-Ereignis durch die 39 eingebauten Richtlinien **und** durch 8 Audit-exklusive Detektoren abgespielt, die Muster erkennen, die noch nicht durch Laufzeitrichtlinien abgedeckt sind. Die Zählungen werden pro Richtlinie / Detektor über alle Sitzungen hinweg aggregiert. +Für jedes Transkript wird jedes Tool-Use-Ereignis durch die 39 eingebauten Richtlinien **und** durch 8 Audit-exklusive Detektoren abgespielt, die Muster erkennen, die noch nicht von Laufzeit-Richtlinien abgedeckt werden. Die Zählungen werden pro Richtlinie bzw. Detektor über alle Sitzungen hinweg aggregiert. ## Was du erhältst -Die `/audit`-Seite ist ein einseitiges, teilbares **Poster**, gefolgt von vier Abschnitten unterhalb des sichtbaren Bereichs: +Die `/audit`-Seite ist ein einseitiges, teilbares **Poster**, gefolgt von vier Abschnitten darunter: -1. **Poster** — die Identität deines Agenten auf einen Blick: sein **Archetyp** (einer von 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), seine Persona-Schlüsselwörter, wie selten dieser Archetyp ist, und ein **Score von 0–100** mit einem Stufenband (`S` bis `bottom tier`). Zum Teilen gedacht — poste es auf X oder LinkedIn oder lade es als PNG herunter. -2. **`// strengths`** — was dein Agent bereits gut macht, als echte Zahlen aus dem Scan (z. B. Clean-Tool-Call-%, `0` Push-to-Main-Versuche), nur angezeigt, wenn die entsprechende Richtlinie eine saubere Bilanz hat. -3. **`// quirks`** — was durchgeglitten ist: eine nach Rang sortierte Tabelle der Verhaltensweisen, die failproofai abgefangen hätte — *wann* es zuletzt vorkam, *was durchgeglitten ist* (und das eingebaute Tool, das es blockiert hätte), dessen *Schweregrad* und wie oft es *gesehen* wurde (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — die vorgeschriebene Verbesserungsliste: eine Zeile pro Richtlinie mit einem kopierfertigen `failproofai policy add `, plus einem **Alle installieren**-Button, der alle Empfehlungen auf einmal aktiviert und deinen **prognostizierten Score** anzeigt. -5. **`// come back better`** — die Gewohnheit aufbauen: eine E-Mail-**Erinnerung** für ein erneutes Audit setzen (`3d` / `7d` / `14d` / `30d`) oder jetzt erneut prüfen, und **einen Freund einladen**, sein eigenes Audit durchzuführen (gesendet von failproof.ai, Cc an dich). Erinnerungen und Einladungen erfordern eine Anmeldung — siehe [`failproofai auth`](/de/cli/auth). +1. **Poster** – die Identität deines Agenten auf einen Blick: sein **Archetyp** (einer von 8 – `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), seine Persona-Schlüsselwörter, wie selten dieser Archetyp ist, und ein **0–100-Score** mit Bandebene (`S` bis `bottom tier`). Zum Teilen gemacht – poste es auf X oder LinkedIn oder lade es als PNG herunter. +2. **`// strengths`** – was dein Agent bereits gut macht, als echte Zahlen aus dem Scan (z. B. Clean-Tool-Call-%, `0` Push-to-Main-Versuche), wird nur angezeigt, wenn die entsprechende Richtlinie eine saubere Bilanz hat. +3. **`// quirks`** – was durchgerutscht ist: eine nach Rang geordnete Tabelle von Verhaltensweisen, die failproofai abgefangen hätte – *wann* es zuletzt passiert ist, *was durchgerutscht ist* (und die eingebaute Richtlinie, die es blockiert hätte), der *Schweregrad* und wie oft es *gesehen* wurde (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** – die vorgeschlagene Korrekturreihenfolge: eine Zeile pro Richtlinie mit einem kopierbaren `failproofai policy add `, plus einem **Alle installieren**-Button, der jede Empfehlung auf einmal aktiviert und deinen **projizierten Score** anzeigt, wenn du das tätest. +5. **`// come back better`** – bau dir die Gewohnheit auf: setze eine E-Mail-**Erinnerung** für eine erneute Prüfung (`3d` / `7d` / `14d` / `30d`) oder prüfe jetzt erneut, und **lade einen Freund ein**, sein eigenes Audit durchzuführen (gesendet von failproof.ai, mit dir in Cc). Erinnerungen und Einladungen erfordern eine Anmeldung – siehe [`failproofai auth`](/de/cli/auth). ## Audit-exklusive Detektoren -Diese erkennen Muster für dummes Verhalten, die (noch) nicht in Echtzeit durchgesetzt werden. Sie laufen nur während des Audits und blockieren nie einen Live-Tool-Aufruf. +Diese erkennen Muster für unkluge Verhaltensweisen, die (noch) nicht in Echtzeit erzwungen werden. Sie laufen nur während des Audits und blockieren niemals einen Live-Tool-Aufruf. | Detektor | Was er zählt | |---|---| -| `redundant-cd-cwd` | Bash-Befehle, die mit `cd && …` beginnen, obwohl Befehle bereits in `cwd` ausgeführt werden. | -| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` auf einer einzelnen Quelldatei — verwende stattdessen das `Read`-Tool. | -| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` direkte Bearbeitungen — verwende stattdessen das `Edit`-Tool. | -| `prefer-write-over-heredoc` | Heredoc / mehrzeilige `echo > file`-Dateioperationen — verwende stattdessen das `Write`-Tool. | -| `sleep-polling-loop` | Lange `sleep N`-Befehle (≥ 30s) oder `while …; sleep …; done`-Polling-Schleifen. | -| `find-from-root` | `find /`, `find /home`, `find /usr` usw. — auf `cwd` eingrenzen. | +| `redundant-cd-cwd` | Bash-Befehle, die mit `cd && …` beginnen, obwohl Befehle bereits in `cwd` laufen. | +| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` auf einer einzelnen Quelldatei – verwende stattdessen das `Read`-Tool. | +| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` In-place-Bearbeitungen – verwende stattdessen das `Edit`-Tool. | +| `prefer-write-over-heredoc` | Heredoc / mehrzeiliges `echo > file` zum Schreiben von Dateien – verwende stattdessen das `Write`-Tool. | +| `sleep-polling-loop` | Langes `sleep N` (≥ 30s) oder `while …; sleep …; done` Polling-Schleifen. | +| `find-from-root` | `find /`, `find /home`, `find /usr` usw. – auf `cwd` beschränken. | | `git-commit-no-verify` | `git commit … --no-verify` / `-n`, wodurch Hooks übersprungen werden. | | `reread-after-edit` | `Read` einer Datei, die in derselben Sitzung gerade per `Edit`/`Write` bearbeitet wurde. | ## Caches -- **Transkript-spezifischer Cache** unter `~/.failproofai/cache/audit/.json`, indiziert nach `(mtime, size, engineVersion, detectorVersion)` — wird automatisch invalidiert, wenn das Transkript oder der Richtlinien-/Detektor-Code sich ändert. Jeder Eintrag speichert auch einen `cachedAt`-Zeitstempel als **TTL-Metadaten** (nicht Teil des Cache-Schlüssels); Einträge, die älter als **7 Tage** sind, werden beim Lesen abgelehnt, damit langlebige Ergebnisse nicht die Weiterentwicklung der Detektoren überdauern. -- **Gesamtergebnis-Cache** unter `~/.failproofai/audit-dashboard.json` (Modus 0600). Ermöglicht sofortiges Rendern des Dashboards bei der Navigation ohne erneuten Scan. Ebenfalls nach dem **7-Tage-TTL** abgelehnt — `/audit` fällt dann in seinen leeren Zustand zurück und fordert einen neuen Scan an. Klicke auf `[ re-audit now ]` unten im Bericht zum Aktualisieren — Re-Audit sendet `noCache: true`, umgeht damit den transkriptspezifischen Cache und scannt alle Transkripte neu, anstatt das gecachte Ergebnis zurückzugeben; der Lauf streamt den Fortschritt über einen festen oberen Streifen und tauscht das Ergebnis bei Erfolg an Ort und Stelle aus (kein Seitenneulade; ein fehlgeschlagenes Re-Audit behält den vorherigen Bericht). +- **Pro-Transkript-Cache** unter `~/.failproofai/cache/audit/.json`, per `(mtime, size, engineVersion, detectorVersion)` indiziert – wird automatisch invalidiert, wenn sich das Transkript oder der Richtlinien-/Detektorcode ändert. Jeder Eintrag speichert auch einen `cachedAt`-Zeitstempel als **TTL-Metadaten** (kein Teil des Cache-Schlüssels); Einträge, die älter als **7 Tage** sind, werden beim Lesen abgelehnt, damit langlebige Ergebnisse nicht die Weiterentwicklung der Detektoren überdauern. +- **Gesamtergebnis-Cache** unter `~/.failproofai/audit-dashboard.json` (Modus 0600). Ermöglicht ein sofortiges Rendern des Dashboards beim Navigieren, ohne einen erneuten Scan durchzuführen. Wird beim Lesen ebenfalls nach dem **7-Tage-TTL** abgelehnt – `/audit` fällt dann in seinen leeren Zustand zurück und fordert einen neuen Scan an. Klicke auf `[ re-audit now ]` unten im Bericht, um zu aktualisieren – ein erneutes Audit sendet `noCache: true`, umgeht also den Pro-Transkript-Cache und scannt alle Transkripte erneut, anstatt das zwischengespeicherte Ergebnis zurückzugeben; der Lauf streamt den Fortschritt über einen fixierten oberen Streifen und tauscht das Ergebnis bei Erfolg an Ort und Stelle aus (kein Seitenneuladen; ein fehlgeschlagenes erneutes Audit behält den vorherigen Bericht). ## Hinweise -- **Keine Mutation.** Das Audit wird im Nur-Lese-Modus abgespielt. `warn-repeated-tool-calls` wird übersprungen, da dessen sitzungsspezifische Hilfsdatei andernfalls geändert würde. -- **Workflow-Richtlinien übersprungen.** `require-*-before-stop`-Richtlinien werden nur bei `Stop`-Ereignissen ausgelöst und führen `execSync` gegen den Live-Git-Status aus — sie haben keine sinnvolle Interpretation im Sinne von 2025, daher erscheinen sie nicht in den Audit-Zählungen. -- **Benutzerdefinierte Richtlinien übersprungen.** Vom Benutzer bereitgestellte benutzerdefinierte Hooks werden nicht abgespielt (sie können sich seit der ursprünglichen Sitzung geändert haben). \ No newline at end of file +- **Keine Mutation.** Das Audit wird im Read-only-Modus wiedergegeben. `warn-repeated-tool-calls` wird übersprungen, da sein sitzungsbegleitender Sidecar sonst modifiziert würde. +- **Workflow-Richtlinien übersprungen.** `require-*-before-stop`-Richtlinien werden nur bei `Stop`-Ereignissen ausgelöst und führen `execSync` gegen den Live-Git-Status aus – sie haben keine sinnvolle Interpretation im Sinne von "was wäre 2025 passiert", daher erscheinen sie nicht in den Audit-Zählungen. +- **Benutzerdefinierte Richtlinien übersprungen.** Vom Benutzer bereitgestellte benutzerdefinierte Hooks werden nicht wiedergegeben (sie können sich seit der ursprünglichen Sitzung geändert haben). \ No newline at end of file diff --git a/docs/de/cli/auth.mdx b/docs/de/cli/auth.mdx index 00dcfe5f..a438538b 100644 --- a/docs/de/cli/auth.mdx +++ b/docs/de/cli/auth.mdx @@ -1,27 +1,27 @@ --- title: Anmelden -description: "Bei FailproofAI über die CLI anmelden, um Erinnerungen und personalisierte Funktionen zu aktivieren" +description: "Melden Sie sich von der CLI bei Failproof AI an, um Erinnerungen und personalisierte Funktionen zu aktivieren" --- ```bash failproofai auth login # E-Mail + Einmalcode -failproofai auth logout # diese Sitzung widerrufen -failproofai auth whoami # angemeldete Identität ausgeben +failproofai auth logout # Diese Sitzung widerrufen +failproofai auth whoami # Angemeldete Identität ausgeben ``` -Die veraltete Flag-Schreibweise `--login` / `--logout` / `--whoami` wird zur Rückwärtskompatibilität weiterhin als Alias akzeptiert. +Die ältere Form `--login` / `--logout` / `--whoami` als Flag wird aus Rückwärtskompatibilitätsgründen weiterhin als Alias akzeptiert. -Die Authentifizierung ist optional. Richtlinien, das Dashboard, die `/audit`-Seite und alle anderen lokalen Funktionen verhalten sich identisch, egal ob Sie angemeldet sind oder nicht. Die Anmeldefunktion existiert, damit Features, die eine **stabile Identität benötigen** (heute: Wiederholen von Audit-Erinnerungen, in Zukunft mehr), einen Ankerpunkt haben. +Die Authentifizierung ist optional. Richtlinien, das Dashboard, die `/audit`-Seite und alle anderen lokalen Funktionen arbeiten unabhängig davon, ob Sie angemeldet sind oder nicht, auf genau dieselbe Weise. Die Anmeldefunktion existiert, damit Funktionen, die eine **stabile Identität benötigen** (heute erneute Audit-Erinnerungen, in Zukunft mehr), einen Ankerpunkt haben. -## Anmeldeablauf +## Anmeldevorgang ```bash failproofai auth login ``` -Fordert Ihre E-Mail-Adresse an, sendet einen 6-stelligen Einmalcode an diese Adresse, fragt den Code ab und schreibt bei Erfolg `~/.failproofai/auth.json` (Modus `0600`). Die gleiche Sitzung ist dann im In-App-Dashboard sichtbar — ein Klick auf `[ set a reminder ]` unter `/audit` erkennt Sie als angemeldet. +Fordert zur Eingabe Ihrer E-Mail-Adresse auf, sendet einen 6-stelligen Einmalcode an diese Adresse, fragt nach dem Code und schreibt bei Erfolg `~/.failproofai/auth.json` (Modus `0600`). Die gleiche Sitzung ist dann im In-App-Dashboard sichtbar — ein Klick auf `[ set a reminder ]` in `/audit` erkennt Sie als angemeldet. -Das Dashboard stellt den gleichen Ablauf als modalen Dialog auf `/audit` für Nutzer bereit, die die CLI nie verwenden. +Das Dashboard bietet denselben Ablauf als modalen Dialog auf `/audit` für Nutzer, die die CLI nie verwenden. ## Abmelden @@ -29,7 +29,7 @@ Das Dashboard stellt den gleichen Ablauf als modalen Dialog auf `/audit` für Nu failproofai auth logout ``` -Widerruft die aktuelle Sitzung auf dem Server und löscht `~/.failproofai/auth.json`. Ist der API-Server nicht erreichbar, wird die lokale Datei trotzdem entfernt — der lokale Abmeldewunsch hat immer Vorrang. +Widerruft die aktuelle Sitzung auf dem Server und löscht `~/.failproofai/auth.json`. Wenn der API-Server nicht erreichbar ist, wird die lokale Datei trotzdem entfernt — die lokale Absicht zum Abmelden hat immer Vorrang. ## Identitätsprüfung @@ -37,11 +37,11 @@ Widerruft die aktuelle Sitzung auf dem Server und löscht `~/.failproofai/auth.j failproofai auth whoami ``` -Gibt ` ()` aus und beendet sich mit Exitcode 0, wenn eine gültige Sitzung besteht, oder gibt `not signed in` aus und beendet sich mit Exitcode 1 andernfalls. Erneuert das Zugriffstoken im Hintergrund automatisch, wenn es innerhalb einer Minute abläuft. +Gibt ` ()` aus und beendet sich mit Code 0, wenn eine gültige Sitzung vorhanden ist, oder gibt `not signed in` aus und beendet sich mit Code 1. Erneuert das Zugriffstoken im Hintergrund automatisch, wenn es weniger als eine Minute bis zum Ablauf hat. ## Wiederkehrende Audit-Erinnerung -Wenn Sie auf der `/audit`-Seite auf **`[ set a reminder ]`** klicken (oder sich über den Modal anmelden, den die Schaltfläche voraussetzt), schreibt das Dashboard eine kleine Begleitdatei unter `~/.failproofai/next-audit.json`: +Wenn Sie auf der `/audit`-Seite auf **`[ set a reminder ]`** klicken (oder sich über den modalen Dialog anmelden, den die Schaltfläche einblendet), schreibt das Dashboard eine kleine Begleitdatei unter `~/.failproofai/next-audit.json`: ```json { @@ -51,9 +51,9 @@ Wenn Sie auf der `/audit`-Seite auf **`[ set a reminder ]`** klicken (oder sich } ``` -Diese Datei ist an die E-Mail-Adresse gebunden, für die sie erstellt wurde — wird die CLI-Sitzung auf ein anderes Konto umgestellt, werden Erinnerungen des vorherigen Nutzers ausgeblendet. Der Standardabstand beträgt **7 Tage** und ist später konfigurierbar, sobald der Scheduler verfügbar ist. Wird wie `auth.json` mit `0600`-Berechtigungen erstellt. +Diese Datei ist auf die E-Mail-Adresse beschränkt, für die sie erstellt wurde — wenn die CLI-Sitzung auf ein anderes Konto umgestellt wird, werden alle Erinnerungen des vorherigen Nutzers ausgeblendet. Der Standardabstand beträgt **7 Tage** und kann später konfiguriert werden, sobald der Scheduler verfügbar ist. Erstellt mit `0600`-Berechtigungen wie `auth.json`. -Der `/api/auth/reminder`-Endpunkt des Dashboards bietet `GET` (lesen), `POST` (setzen / neu planen) und `DELETE` (löschen) und erfordert eine aktive Sitzung. +Der `/api/auth/reminder`-Endpunkt des Dashboards stellt `GET` (lesen), `POST` (setzen / neu planen) und `DELETE` (löschen) bereit und erfordert eine aktive Sitzung. ## Inhalt von `~/.failproofai/auth.json` @@ -67,21 +67,21 @@ Der `/api/auth/reminder`-Endpunkt des Dashboards bietet `GET` (lesen), `POST` (s } ``` -Wird mit `0600`-Berechtigungen erstellt (nur Eigentümer kann lesen/schreiben). Das Zugriffstoken ist ein 1-stündiges HS256-JWT; das Refresh-Token ist eine undurchsichtige 256-Bit-Zufallszeichenfolge, die der Server als `SHA-256(token)` speichert. Mehrfache Verwendung eines Refresh-Tokens wird serverseitig erkannt und widerruft alle Sitzungen des Nutzers. +Erstellt mit `0600`-Berechtigungen (nur Eigentümer kann lesen/schreiben). Das Zugriffstoken ist ein 1-stündiges HS256-JWT; das Refresh-Token ist ein opaker 256-Bit-Zufallsstring, den der Server als `SHA-256(token)` speichert. Missbrauch von Refresh-Tokens wird serverseitig erkannt und widerruft alle Sitzungen des Nutzers. ## Umgebungsvariablen | Variable | Standard | Zweck | |---|---|---| -| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | Überschreibt die Basis-URL des API-Servers. Nützlich für die lokale Entwicklung gegen einen selbst gehosteten API-Server. | -| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | Überschreibt den Speicherort von `auth.json`. Hauptsächlich für Tests. | +| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | Basis-URL des API-Servers überschreiben. Nützlich für die lokale Entwicklung gegen einen selbst gehosteten API-Server. | +| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | Speicherort von `auth.json` überschreiben. Hauptsächlich für Tests. | -Unter [Umgebungsvariablen](/de/cli/environment-variables) finden Sie die vollständige Liste. +Die vollständige Liste finden Sie unter [Umgebungsvariablen](/de/cli/environment-variables). ## Fehlerbehebung -**„Could not reach the api-server"** — die CLI kann keine TCP-Verbindung zu `FAILPROOF_API_URL` herstellen. Überprüfen Sie Ihre Netzwerkverbindung oder setzen Sie `FAILPROOF_API_URL`, wenn Sie einen selbst gehosteten API-Server betreiben. +**„Could not reach the api-server"** — die CLI kann keine TCP-Verbindung zu `FAILPROOF_API_URL` herstellen. Überprüfen Sie Ihr Netzwerk oder setzen Sie `FAILPROOF_API_URL`, wenn Sie einen selbst gehosteten API-Server betreiben. -**„Rate limited"** — zu viele Anmeldeversuche in einem 15-Minuten-Fenster für diese E-Mail-Adresse (5/E-Mail) oder IP-Adresse (20/IP), oder eine 30-sekündige Wiederholungssperre nach der letzten Anfrage für dieselbe E-Mail. Die Fehlermeldung enthält das Wiederholen-nach-Intervall in Sekunden. +**„Rate limited"** — zu viele Anmeldeversuche innerhalb eines 15-Minuten-Fensters für diese E-Mail-Adresse (5/E-Mail) oder IP (20/IP), oder eine 30-Sekunden-Wartezeit nach der vorherigen Anfrage für dieselbe E-Mail-Adresse. Die Fehlermeldung enthält die Wiederholungswartezeit in Sekunden. -**Code abgelehnt** — der OTP war falsch, abgelaufen oder der Eintrag hat die Sperrgrenze von 5 Fehlversuchen erreicht. Führen Sie `failproofai auth login` erneut aus, um einen neuen Code anzufordern. \ No newline at end of file +**Code abgelehnt** — das Einmalpasswort war falsch, abgelaufen oder der Eintrag hat seine Sperrgrenze von 5 Fehlversuchen erreicht. Führen Sie `failproofai auth login` erneut aus, um einen neuen Code anzufordern. \ No newline at end of file diff --git a/docs/de/cli/dashboard.mdx b/docs/de/cli/dashboard.mdx index d3fba1fa..14d1b747 100644 --- a/docs/de/cli/dashboard.mdx +++ b/docs/de/cli/dashboard.mdx @@ -13,10 +13,10 @@ Startet das Web-Dashboard unter `http://localhost:8020`. | Flag | Beschreibung | |------|--------------| -| `--port ` | Port, auf dem gehorcht werden soll (Standard: `8020`) | -| `--allowed-origins ` | Kommagetrennte Hosts/IPs, die auf Dev-Ressourcen zugreifen dürfen | +| `--port ` | Port, auf dem gehorcht wird (Standard: `8020`) | +| `--allowed-origins ` | Durch Komma getrennte Hosts/IPs, die auf Entwicklungsressourcen zugreifen dürfen | -Um das Dashboard auf einen nicht standardmäßigen Claude-Projektordner auszurichten, setzen Sie beim Starten die Umgebungsvariable `CLAUDE_PROJECTS_PATH`. +Um das Dashboard auf einen nicht standardmäßigen Claude-Projektordner zu verweisen, setzen Sie beim Start die Umgebungsvariable `CLAUDE_PROJECTS_PATH`. ## Beispiele diff --git a/docs/de/cli/environment-variables.mdx b/docs/de/cli/environment-variables.mdx index b0e786f7..1cb2c1dd 100644 --- a/docs/de/cli/environment-variables.mdx +++ b/docs/de/cli/environment-variables.mdx @@ -1,6 +1,6 @@ --- title: Umgebungsvariablen -description: "Konfiguriere das Verhalten von failproofai mit Umgebungsvariablen" +description: "Das Verhalten von failproofai mit Umgebungsvariablen konfigurieren" --- ## Dashboard @@ -8,7 +8,7 @@ description: "Konfiguriere das Verhalten von failproofai mit Umgebungsvariablen" | Variable | Beschreibung | |----------|-------------| | `PORT` | Dashboard-Port (Standard: `8020`) | -| `CLAUDE_PROJECTS_PATH` | Überschreibt den Speicherort der Claude Code-Projektordner | +| `CLAUDE_PROJECTS_PATH` | Überschreibt den Pfad, unter dem Claude Code-Projektordner gesucht werden | | `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Kommagetrennte Liste von Dashboard-Seiten, die ausgeblendet werden sollen | | `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hosts/IPs, die auf Entwicklungsressourcen zugreifen dürfen. Entspricht `--allowed-origins`. | @@ -17,7 +17,7 @@ description: "Konfiguriere das Verhalten von failproofai mit Umgebungsvariablen" | Variable | Beschreibung | |----------|-------------| | `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Server-Protokollierungsstufe (Standard: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | Benutzerdefinierter Pfad zur Hook-Protokolldatei oder `true` für den Standardpfad (`~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | Benutzerdefinierter Pfad zur Hook-Protokolldatei oder `true` für den Standard (`~/.failproofai/logs/hooks.log`) | ## Telemetrie @@ -29,14 +29,14 @@ description: "Konfiguriere das Verhalten von failproofai mit Umgebungsvariablen" | Variable | Beschreibung | |----------|-------------| -| `FAILPROOF_API_URL` | Überschreibt die Basis-URL des API-Servers, die von `failproofai auth` und dem Dashboard-Authentifizierungsdialog verwendet wird. Standard ist `https://api.befailproof.ai`; bei einem lokalen API-Server auf `http://localhost:8080` (oder den entsprechenden Wert) setzen. | +| `FAILPROOF_API_URL` | Überschreibt die Basis-URL des API-Servers, die von `failproofai auth` und dem Dashboard-Authentifizierungsdialog verwendet wird. Standardmäßig `https://api.befailproof.ai`; auf `http://localhost:8080` (oder einen anderen Wert) setzen, wenn ein lokaler API-Server verwendet wird. | | `FAILPROOFAI_AUTH_DIR` | Überschreibt den Speicherort von `auth.json` (Standard: `~/.failproofai`). Hauptsächlich für isolierte Tests nützlich. | ## Erststart-Eingabeaufforderung | Variable | Beschreibung | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | Überspringt die Eingabeaufforderung, die beim ersten Aufruf von `failproofai` ohne Argumente anbietet, Richtlinien zu installieren | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Überspringt die Eingabeaufforderung, die beim ersten einfachen `failproofai`-Aufruf die Installation von Richtlinien anbietet | ## LLM (für die Richtlinienauswertung) diff --git a/docs/de/cli/hook.mdx b/docs/de/cli/hook.mdx index 581faffd..6f1207a2 100644 --- a/docs/de/cli/hook.mdx +++ b/docs/de/cli/hook.mdx @@ -1,26 +1,26 @@ --- title: Hook-Handler (intern) -description: "Der Unterprozess, den Claude Code bei jedem Tool-Event aufruft" +description: "Der Subprozess, den Claude Code bei jedem Tool-Ereignis aufruft" --- ```bash failproofai --hook ``` -Dies ist der Befehl, der durch `failproofai policies --install` in der `settings.json` von Claude Code registriert wird. Normalerweise rufen Sie diesen Befehl nicht direkt auf. +Dies ist der Befehl, der in Claude Codes `settings.json` durch `failproofai policies --install` registriert wird. Normalerweise rufen Sie diesen nicht direkt auf. -Liest eine JSON-Nutzlast von stdin, wertet alle aktivierten Richtlinien aus und beendet sich mit einem Exit-Code, der die Entscheidung angibt: +Liest eine JSON-Nutzlast von stdin, wertet alle aktivierten Richtlinien aus und beendet sich mit einem Code, der die Entscheidung anzeigt: | Exit-Code | Entscheidung | Auswirkung | |-----------|--------------|------------| | `0` | `allow` | Aktion erlauben | -| `1` | `deny` | Aktion blockieren – Claude erhält den Ablehnungsgrund | -| `2` | `instruct` | Hinweise in den Kontext von Claude einschleusen | +| `1` | `deny` | Aktion blockieren – Claude sieht den Ablehnungsgrund | +| `2` | `instruct` | Hinweise in Claudes Kontext einschleusen | -### Unterstützte Event-Typen +### Unterstützte Ereignistypen -| Kategorie | Events | -|-----------|--------| +| Kategorie | Ereignisse | +|-----------|------------| | **Tool-Ausführung** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | | **Sitzungslebenszyklus** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | | **Benutzerinteraktion** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | diff --git a/docs/de/cli/install-policies.mdx b/docs/de/cli/install-policies.mdx index 24d976fb..3a4e55b0 100644 --- a/docs/de/cli/install-policies.mdx +++ b/docs/de/cli/install-policies.mdx @@ -1,13 +1,13 @@ --- title: Richtlinien installieren -description: "Richtlinien aktivieren, damit sie bei jedem Agent-Tool-Aufruf ausgeführt werden" +description: "Richtlinien aktivieren, damit sie bei jedem Agenten-Tool-Aufruf ausgeführt werden" --- ```bash failproofai policies --install [policy-names...] [options] ``` -Schreibt Hook-Einträge in die Einstellungsdatei der installierten Agent-CLI (Claude Code, OpenAI Codex oder GitHub Copilot CLI _(Beta)_), damit failproofai Tool-Aufrufe abfängt. +Schreibt Hook-Einträge in die Einstellungsdatei der installierten Agenten-CLI (Claude Code, OpenAI Codex oder GitHub Copilot CLI _(Beta)_), sodass failproofai Tool-Aufrufe abfängt. Aliase: `failproofai p -i` @@ -15,19 +15,19 @@ Aliase: `failproofai p -i` | Flag | Beschreibung | |------|-------------| -| `--cli claude\|codex\|copilot` | Agent-CLI(s), für die installiert werden soll; leerzeichen-getrennt (z. B. `--cli claude codex copilot`) oder mehrfach angegeben. Weglassen, um installierte CLIs automatisch zu erkennen und eine Auswahl anzuzeigen. | -| `--scope user` | Installiert in die benutzerweite Einstellungsdatei (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Standard. | -| `--scope project` | Installiert in die projektweite Einstellungsdatei (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | +| `--cli claude\|codex\|copilot` | Agenten-CLI(s), für die installiert werden soll; durch Leerzeichen getrennt (z. B. `--cli claude codex copilot`) oder wiederholt angegeben. Weglassen, um installierte CLIs automatisch zu erkennen und eine Auswahl anzuzeigen. | +| `--scope user` | In die benutzerweite Einstellungsdatei installieren (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Standard. | +| `--scope project` | In die projektweite Einstellungsdatei installieren (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | | `--scope local` | Nur Claude — installiert in `/.claude/settings.local.json`. Codex und Copilot unterstützen keinen `local`-Scope. | | `--custom ` / `-c` | Pfad zu einer JS-Datei mit benutzerdefinierten Hook-Richtlinien | ## Verhalten -- **Keine Richtliniennamen** – öffnet eine interaktive Auswahl zum Wählen von Richtlinien +- **Keine Richtliniennamen** – öffnet eine interaktive Eingabeaufforderung zur Auswahl von Richtlinien - **Bestimmte Namen** – aktiviert diese Richtlinien (werden zu bereits aktivierten hinzugefügt) - **`all`** – aktiviert alle verfügbaren Richtlinien -Die Installation ist additiv: erneutes Ausführen von `--install` fügt neue Richtlinien hinzu, ohne bestehende zu entfernen. +Die Installation ist additiv: Ein erneuter Aufruf von `--install` fügt neue Richtlinien hinzu, ohne bestehende zu entfernen. ## Beispiele @@ -47,7 +47,7 @@ failproofai policies --install --custom ./my-policies.js # Für OpenAI Codex installieren (Projekt-Scope) failproofai policies --install --cli codex --scope project -# Für GitHub Copilot CLI (Beta) im aktuellen Projekt installieren +# Für GitHub Copilot CLI (Beta) für das aktuelle Projekt installieren failproofai policies --install --cli copilot --scope project # Für alle drei CLIs gleichzeitig installieren diff --git a/docs/de/cli/list-policies.mdx b/docs/de/cli/list-policies.mdx index 43bb73ce..534d2c25 100644 --- a/docs/de/cli/list-policies.mdx +++ b/docs/de/cli/list-policies.mdx @@ -1,13 +1,13 @@ --- title: Richtlinien auflisten -description: "Zeigt an, welche Richtlinien aktiviert sind, ihre Parameter und benutzerdefinierte Richtlinien" +description: "Zeigt, welche Richtlinien aktiv sind, ihre Parameter und benutzerdefinierte Richtlinien" --- ```bash failproofai policies ``` -Zeigt alle Richtlinien mit ihrem Status, konfigurierten Parametern und benutzerdefinierten Richtlinien an. +Zeigt alle Richtlinien mit ihrem Status, den konfigurierten Parametern und benutzerdefinierten Richtlinien. ## Beispielausgabe @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -Unbekannte Schlüssel in `policyParams` werden hier markiert, damit Tippfehler frühzeitig erkannt werden können. \ No newline at end of file +Unbekannte Schlüssel in `policyParams` werden hier hervorgehoben, damit Tippfehler frühzeitig erkannt werden können. \ No newline at end of file diff --git a/docs/de/cli/remove-policies.mdx b/docs/de/cli/remove-policies.mdx index 9cf3fa9e..2d287109 100644 --- a/docs/de/cli/remove-policies.mdx +++ b/docs/de/cli/remove-policies.mdx @@ -14,7 +14,7 @@ Aliase: `failproofai p -u` ## Optionen | Flag | Beschreibung | -|------|--------------| +|------|-------------| | `--scope user` | Aus den globalen Einstellungen entfernen (Standard) | | `--scope project` | Aus den Projekteinstellungen entfernen | | `--scope local` | Aus den lokalen Einstellungen entfernen | @@ -24,7 +24,7 @@ Aliase: `failproofai p -u` ## Verhalten - **Keine Richtliniennamen** – entfernt alle failproofai-Hook-Einträge aus der Einstellungsdatei -- **Bestimmte Namen** – deaktiviert diese Richtlinien, behält die Hooks jedoch installiert +- **Bestimmte Namen** – deaktiviert diese Richtlinien, behält die Hooks aber installiert ## Beispiele diff --git a/docs/de/cli/version.mdx b/docs/de/cli/version.mdx index dff7a73f..b0b5db88 100644 --- a/docs/de/cli/version.mdx +++ b/docs/de/cli/version.mdx @@ -1,6 +1,6 @@ --- title: Version prüfen -description: "Die installierte failproofai-Version ausgeben" +description: "Installierte failproofai-Version ausgeben" --- ```bash diff --git a/docs/de/configuration.mdx b/docs/de/configuration.mdx index 74a011e9..a0b1ad6a 100644 --- a/docs/de/configuration.mdx +++ b/docs/de/configuration.mdx @@ -1,28 +1,28 @@ --- title: Konfiguration -description: "Konfigurationsdateiformat, Drei-Scope-System und Merge-Regeln" +description: "Konfigurationsdateiformat, Drei-Scope-System und Zusammenführungsregeln" icon: gear --- -failproofai verwendet JSON-Konfigurationsdateien, um festzulegen, welche Richtlinien aktiv sind, wie sie sich verhalten und woher benutzerdefinierte Richtlinien geladen werden. Die Konfiguration ist so gestaltet, dass sie einfach im Team geteilt werden kann – 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 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. --- -## Konfigurationsbereiche +## Konfigurationsscopes -Es gibt drei Konfigurationsbereiche, die in Prioritätsreihenfolge ausgewertet werden: +Es gibt drei Konfigurationsscopes, die in Prioritätsreihenfolge ausgewertet werden: -| Bereich | Dateipfad | Zweck | -|---------|-----------|-------| -| **project** | `.failproofai/policies-config.json` | Repository-spezifische Einstellungen, in die Versionsverwaltung 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 | +| 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 | -Wenn failproofai ein Hook-Ereignis empfängt, lädt und merged es alle drei Dateien, die für das aktuelle Arbeitsverzeichnis vorhanden sind. +Wenn failproofai ein Hook-Ereignis empfängt, lädt und führt es alle drei Dateien zusammen, die für das aktuelle Arbeitsverzeichnis existieren. -### Merge-Regeln +### Zusammenführungsregeln -**`enabledPolicies`** – die Vereinigung aller drei Bereiche. Eine Richtlinie, die auf irgendeiner Ebene aktiviert ist, ist aktiv. +**`enabledPolicies`** – die Vereinigung aller drei Scopes. 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 Bereich, der Parameter für eine bestimmte Richtlinie definiert, gewinnt vollständig. Es gibt kein tiefes Mergen von Werten innerhalb der Parameter einer Richtlinie. +**`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. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -42,16 +42,16 @@ 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 Bereich, der diesen Wert definiert, gewinnt. +**`customPoliciesPath`** – der erste Scope, der diesen definiert, gewinnt. -**`llm`** – der erste Bereich, der diesen Wert definiert, gewinnt. +**`llm`** – der erste Scope, der diesen definiert, gewinnt. --- @@ -102,7 +102,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 von `failproofai policies` angezeigt werden. Eine vollständige Liste finden Sie unter [Integrierte Richtlinien](/de/built-in-policies). +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). Richtlinien, die nicht in `enabledPolicies` enthalten sind, sind inaktiv, auch wenn sie Einträge in `policyParams` haben. @@ -110,17 +110,17 @@ Richtlinien, die nicht in `enabledPolicies` enthalten sind, sind inaktiv, auch w Typ: `Record>` -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). +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). -Wenn eine Richtlinie Parameter hat, Sie diese aber nicht angeben, werden die eingebauten Standardwerte der Richtlinie verwendet. Benutzer, die `policyParams` gar nicht konfigurieren, erhalten ein identisches Verhalten wie in früheren Versionen. +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. -Unbekannte Schlüssel innerhalb des Parameterblocks einer Richtlinie werden zum Zeitpunkt der Hook-Ausführung stillschweigend ignoriert, werden jedoch als Warnungen markiert, wenn Sie `failproofai policies` ausführen. +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. #### `hint` (übergreifend) Typ: `string` (optional) -Eine Meldung, die an den Grund angehängt wird, wenn eine Richtlinie `deny` oder `instruct` zurückgibt. Verwenden Sie sie, um Claude handlungsrelevante Hinweise zu geben, ohne die Richtlinie selbst zu ändern. +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. Funktioniert mit jedem Richtlinientyp – integriert, benutzerdefiniert (`custom/`), Projektkonvention (`.failproofai-project/`) oder Benutzerkonvention (`.failproofai-user/`). @@ -151,22 +151,22 @@ 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 Informationen zur Erstellung finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies). +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). ### Konventionsbasierte Richtlinien Zusätzlich zum expliziten `customPoliciesPath` erkennt und lädt failproofai automatisch Richtliniendateien aus `.failproofai/policies/`-Verzeichnissen: -| Ebene | Verzeichnis | Bereich | -|-------|-------------|---------| -| Projekt | `.failproofai/policies/` | Mit dem Team über Versionsverwaltung geteilt | +| Ebene | Verzeichnis | Scope | +|-------|-------------|-------| +| Projekt | `.failproofai/policies/` | Per Versionsverwaltung mit dem Team geteilt | | Benutzer | `~/.failproofai/policies/` | Persönlich, gilt für alle Projekte | -**Dateiabgleich:** Es werden nur Dateien geladen, die `*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 dem Muster `*policies.{js,mjs,ts}` entsprechen (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 aufgenommen. +**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. -**Vereinigtes Laden:** Sowohl Projekt- als auch Benutzerkonventionsverzeichnisse werden durchsucht. Alle passenden Dateien aus beiden Ebenen werden geladen (im Gegensatz zu `customPoliciesPath`, das das Prinzip „erster Bereich 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 Scope gewinnt" verwendet). Weitere Details und Beispiele finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies). @@ -189,19 +189,20 @@ 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 Ihres Agenten-CLIs (die Hook-Einstiegspunkte), während `policies-config.json` die Datei ist, die Sie direkt verwalten. Beide sind voneinander getrennt: +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: -- **Agenten-CLI-Einstellungen** — weist den Agenten an, bei jeder Werkzeugnutzung `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`-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 betriebssystemabhängigen `bash`/`powershell`-Befehlsfelder von Copilot mit `timeoutSec`; die Datei enthält einen `version: 1`-Marker auf oberster Ebene. Die Unterstützung für Copilot CLI ist **beta**, während wir das `events.jsonl`-Aufzeichnungsschema (das in den öffentlichen Docs nicht spezifiziert ist) anhand weiterer realer Sitzungen verifizieren. - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (Benutzer), `/.cursor/hooks.json` (Projekt) — Cursor hat keinen `local`-Bereich. Hook-Einträge verwenden die Claude-ähnliche Form `{type, command, timeout}` (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 `version: 1`-Marker auf oberster Ebene. Der Handler kanonisiert camelCase → PascalCase über `CURSOR_EVENT_MAP`, sodass bestehende eingebaute Richtlinien unverändert ausgelöst werden. Die Unterstützung für Cursor Agent ist **beta**, während wir Cursors On-Disk-Transkriptformat (in den öffentlichen Docs nicht spezifiziert) anhand weiterer realer 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 sechs CLIs verfügt OpenCode über **kein externes Befehlshook-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** der Weg, wie Plugins in opencode v1.14.33 geladen werden). Die Installation legt einen kleinen generierten Plugin-Shim ab, der die failproofai-Binärdatei als Subprocess aufruft und die Claude-ähnliche JSON-Antwort der Binärdatei 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 (sendet den Ablehnungsgrund als nächste Benutzernachricht – der einzige Force-Retry-Kanal, da `session.idle` nur benachrichtigend ist und ein Throw daraus ein No-Op ist), und No-Op für allow. Der Shim kanonisiert sowohl Werkzeugnamen (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 die Binärdatei weitergeleitet wird, 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 Sitzungs-Viewer des Dashboards liest sie über `opencode db --format json` und `opencode export `. Die Unterstützung für OpenCode ist **beta**, während wir das Verhalten über verschiedene Versionen und mehr reale Sitzungen hinweg verifizieren. Siehe die [OpenCode-Plugins-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 einzelnen packages-Array-Eintrag, der auf sein gebündeltes `pi-extension/`-Verzeichnis verweist. Die Erweiterung abonniert intern Pis `tool_call`/`user_bash`/`input`/`session_start`-Ereignisse und ruft `failproofai --hook --cli pi` als Shell-Prozess auf; der Handler kanonisiert underscore_lower_snake_case → PascalCase über `PI_EVENT_MAP`, sodass bestehende eingebaute 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 Abbildung 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 Erweiterungs-API und das Sitzungsprotokoll-Layout stabilisieren. - - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (Benutzer), `/.gemini/settings.json` (Projekt) — Gemini hat keinen `local`-Bereich (es dokumentiert einen `system`-Bereich unter `/etc/gemini-cli/settings.json`, den failproofai nicht bereitstellt). Hook-Einträge verwenden Claudes `{type, command, timeout}`-Form, eingebettet in Geminis `{matcher, hooks: [...]}`-Matcher-Schema mit standardmäßig `matcher: "*"`. Ereignisse sind PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); der Handler bildet sie über `GEMINI_EVENT_MAP` auf kanonische Claude-Namen ab. Werkzeugnamen sind snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) – der Handler kanonisiert über `GEMINI_TOOL_MAP`, sodass bestehende eingebaute Richtlinien unverändert ausgelöst werden. Der Richtlinienauswerter gibt Geminis flache `{decision: "deny", reason}`-Form aus (bevorzugt gemäß Geminis „Golden Rule" exit-0-Vertrag), `{hookSpecificOutput: {hookEventName, additionalContext}}` für Kontexteinschleusung bei BeforeAgent/AfterTool/SessionStart, und `{decision: "block", reason}` bei AfterAgent für Force-Retry-Semantik. Die Unterstützung für Gemini CLI ist **beta**, während wir die reale Abdeckung ausweiten. Siehe die [Gemini CLI Hooks-Dokumentation](https://geminicli.com/docs/hooks/). -- **`policies-config.json`** — teilt failproofai mit, welche Richtlinien ausgewertet werden sollen und mit welchen Parametern (gilt für alle Agenten-CLIs) + - **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 sechs 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. + - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (Benutzer), `/.gemini/settings.json` (Projekt) – Gemini hat keinen `local`-Scope (es dokumentiert einen `system`-Scope unter `/etc/gemini-cli/settings.json`, den failproofai nicht verfügbar macht). Hook-Einträge verwenden Claudes `{type, command, timeout}`-Form, eingebettet in Geminis `{matcher, hooks: [...]}`-Matcher-Schema mit standardmäßig `matcher: "*"`. Ereignisse sind PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); der Handler ordnet sie über `GEMINI_EVENT_MAP` kanonischen Claude-Namen zu. Tool-Namen sind snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) – der Handler kanonisiert über `GEMINI_TOOL_MAP`, sodass bestehende integrierte Richtlinien unverändert ausgelöst werden. Der Richtlinienauswerter gibt Geminis flache `{decision: "deny", reason}`-Form aus (bevorzugt gemäß Geminis „Goldener Regel" exit-0-Vertrag), `{hookSpecificOutput: {hookEventName, additionalContext}}` für Kontext-Injection bei BeforeAgent / AfterTool / SessionStart, und `{decision: "block", reason}` bei AfterAgent für Force-Retry-Semantik. Die Gemini CLI-Unterstützung ist **beta**, während wir die reale Abdeckung ausweiten. Siehe die [Gemini CLI Hooks-Dokumentation](https://geminicli.com/docs/hooks/). + - **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|gemini`, um einen bestimmten Agenten auszuwählen (leerzeichen-getrennt oder mehrfach für eine beliebige Teilmenge): +Übergeben Sie `--cli claude|codex|copilot|cursor|opencode|pi|gemini|hermes`, um einen bestimmten Agenten anzusprechen (durch Leerzeichen getrennt oder wiederholt für eine beliebige Teilmenge): ```bash failproofai policies --install --cli codex --scope project @@ -210,15 +211,16 @@ 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 gemini --scope project +failproofai policies --install --cli hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` -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 gemini`): +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 gemini` / `which hermes`): -- **Eine CLI erkannt** — wählt diese CLI automatisch ohne Nachfrage aus. -- **Mehrere CLIs erkannt** in einem interaktiven Terminal — zeigt eine Pfeilauswahl-Eingabeaufforderung an, gruppiert in einen Abschnitt `Erkannt (N)` (mit einer aggregierten Zeile `Für alle N erkannten installieren` + jede erkannte CLI einzeln) und einen Abschnitt `Nicht installiert (M) · Hooks vorab installieren`, der jede nicht erkannte unterstützte CLI als Vorab-Installationsoption aufführt (↑↓ zum Bewegen, Enter zum Auswählen, ^C zum Beenden). Der Deinstallationsablauf zeigt nur den Abschnitt „Erkannt". -- **Mehrere CLIs erkannt** in einer nicht-interaktiven Ausführung (CI, kein TTY) — installiert für alle erkannten CLIs ohne Nachfrage. -- **Keine erkannt** — fällt auf `claude` zurück, mit einer Warnung, dass keine Agenten-Binärdatei im PATH gefunden wurde; der Hook-Befehl wird dennoch geschrieben, sodass er aktiviert wird, sobald Sie eine installieren. +- **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. 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. @@ -245,4 +247,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 Überschreibungen erstellen, ohne Teamkollegen zu beeinflussen. \ No newline at end of file +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 diff --git a/docs/de/custom-policies.mdx b/docs/de/custom-policies.mdx index f35874e8..9411c78e 100644 --- a/docs/de/custom-policies.mdx +++ b/docs/de/custom-policies.mdx @@ -4,7 +4,7 @@ description: "Schreibe eigene Richtlinien in JavaScript – Konventionen durchse icon: code --- -Benutzerdefinierte Richtlinien ermöglichen es dir, Regeln für beliebiges Agentenverhalten zu schreiben: Projektkonventionen durchsetzen, Drift verhindern, destruktive Operationen absichern, feststeckende Agenten erkennen oder Integrationen mit Slack, Freigabe-Workflows und mehr umsetzen. Sie verwenden dasselbe Hook-Event-System und dieselben Entscheidungen `allow`, `deny`, `instruct` wie die eingebauten Richtlinien. +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. --- @@ -37,14 +37,14 @@ failproofai policies --install --custom ./my-policies.js --- -## Zwei Wege, benutzerdefinierte Richtlinien zu laden +## Zwei Wege zum Laden benutzerdefinierter 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. ``` -# Projektebene — wird in Git eingecheckt und mit dem Team geteilt +# Projektebene — ins Git eingecheckt, wird mit dem Team geteilt .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs @@ -53,14 +53,14 @@ Lege `*policies.{js,mjs,ts}`-Dateien in `.failproofai/policies/` ab und sie werd ``` **So funktioniert es:** -- Sowohl Projekt- als auch Benutzerverzeichnisse werden durchsucht (Vereinigung – nicht nach dem Prinzip „erstes Scope gewinnt") -- Dateien werden alphabetisch innerhalb jedes Verzeichnisses geladen. Mit dem Präfix `01-`, `02-` lässt sich die Reihenfolge steuern -- Nur Dateien, die auf `*policies.{js,mjs,ts}` passen, werden geladen; andere Dateien werden ignoriert +- 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 - Jede Datei wird unabhängig geladen (fail-open pro Datei) -- Funktioniert zusammen mit expliziten `--custom`- und eingebauten Richtlinien +- Funktioniert neben explizitem `--custom` und eingebauten Richtlinien -Konventionsrichtlinien 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 – kein individuelles Setup nötig. Wenn dein Team neue Fehlerquellen entdeckt, füge eine Richtlinie hinzu und pushe sie. Im Laufe der Zeit entsteht so ein lebendiger 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/` 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. ### Option 2: Expliziter Dateipfad @@ -69,22 +69,22 @@ Konventionsrichtlinien sind der einfachste Weg, einen Qualitätsstandard für de # Mit einer benutzerdefinierten Richtliniendatei installieren failproofai policies --install --custom ./my-policies.js -# Den Pfad zur Richtliniendatei ersetzen +# Den Richtliniendateipfad ersetzen failproofai policies --install --custom ./new-policies.js # Den benutzerdefinierten Richtlinienpfad 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-Event neu geladen – es gibt kein Caching zwischen Events. +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. -### Beide Methoden kombinieren +### Beide Varianten zusammen verwenden -Konventionsrichtlinien und die explizite `--custom`-Datei können nebeneinander existieren. Ladereihenfolge: +Konventionsbasierte Richtlinien und die explizite `--custom`-Datei können nebeneinander existieren. Ladereihenfolge: -1. Explizite `customPoliciesPath`-Datei (falls konfiguriert) -2. Projektbezogene Konventionsdateien (`{cwd}/.failproofai/policies/`, alphabetisch) -3. Benutzerbezogene Konventionsdateien (`~/.failproofai/policies/`, alphabetisch) +1. Explizite `customPoliciesPath`-Datei (sofern konfiguriert) +2. Projektkonventionsdateien (`{cwd}/.failproofai/policies/`, alphabetisch) +3. Benutzerkonventionsdateien (`~/.failproofai/policies/`, alphabetisch) --- @@ -98,13 +98,13 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Registriert eine Richtlinie. Kann mehrfach aufgerufen werden, um mehrere Richtlinien in derselben Datei zu definieren. +Registriert eine Richtlinie. Kann beliebig oft aufgerufen werden, um mehrere Richtlinien in derselben Datei zu definieren. ```ts customPolicies.add({ - name: string; // erforderlich – eindeutiger Bezeichner - description?: string; // wird in der Ausgabe von `failproofai policies` angezeigt - match?: { events?: HookEventType[] }; // nach Event-Typ filtern; weglassen, um alle zu treffen + 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 fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` @@ -113,30 +113,30 @@ customPolicies.add({ | Funktion | Wirkung | Wann verwenden | |----------|---------|----------------| -| `allow()` | Operation lautlos zulassen | 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, um ihn auf Kurs zu halten | +| `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 | -`deny(message)` – die Nachricht erscheint bei Claude mit dem Präfix `"Blocked by failproofai:"`. Ein einziges `deny` bricht die gesamte weitere Auswertung ab. +`deny(message)` – die Nachricht erscheint bei Claude mit dem Präfix `"Blocked by failproofai:"`. Ein einzelnes `deny` schließt alle weiteren Auswertungen kurz. -`instruct(message)` – die Nachricht wird dem Kontext von Claude für den aktuellen Tool-Aufruf hinzugefügt. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam übermittelt. +`instruct(message)` – die Nachricht wird dem Claude-Kontext für den aktuellen Tool-Aufruf angehängt. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam übermittelt. -Du kannst jeder `deny`- oder `instruct`-Nachricht zusätzliche Hinweise hinzufügen, indem du ein `hint`-Feld in `policyParams` angibst – ohne Codeänderung. Das funktioniert auch für benutzerdefinierte (`custom/`), projektbezogene Konventionsrichtlinien (`.failproofai-project/`) und benutzerbezogene Konventionsrichtlinien (`.failproofai-user/`). Weitere Details unter [Konfiguration → hint](/de/configuration#hint-cross-cutting). +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. -### Informationelle Allow-Nachrichten +### Informelle allow-Nachrichten -`allow(message)` lässt die Operation **durch** und sendet gleichzeitig eine informationelle Nachricht an Claude. Die Nachricht wird als `additionalContext` in der stdout-Antwort des Hook-Handlers übermittelt – derselbe Mechanismus wie bei `instruct`, aber semantisch anders: Es ist ein Statusupdate, keine Warnung. +`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. | Funktion | Wirkung | Wann verwenden | |----------|---------|----------------| -| `allow(message)` | Zulassen und Kontext an Claude senden | Bestätigen, dass eine Prüfung bestanden wurde, oder erklären, warum eine Prüfung übersprungen wurde | +| `allow(message)` | Erlauben und Kontext an Claude senden | Eine bestandene Prüfung bestätigen oder erklären, warum eine Prüfung übersprungen wurde | Anwendungsfälle: -- **Statusbestätigungen:** `allow("All CI checks passed.")` – teilt Claude mit, dass alles grün ist -- **Fail-Open-Erklärungen:** `allow("GitHub CLI not installed, skipping CI check.")` – erklärt Claude, warum eine Prüfung übersprungen wurde, damit es den vollen Kontext hat -- **Mehrere Nachrichten werden gesammelt:** Wenn mehrere Richtlinien jeweils `allow(message)` zurückgeben, werden alle Nachrichten mit Zeilenumbrüchen verbunden und gemeinsam übermittelt +- **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 ```js customPolicies.add({ @@ -146,7 +146,7 @@ customPolicies.add({ const cwd = ctx.session?.cwd; if (!cwd) return allow("No working directory, skipping branch check."); - // ... check branch status ... + // ... Branch-Status prüfen ... if (allPushed) { return allow("Branch is up to date with remote."); } @@ -162,23 +162,23 @@ customPolicies.add({ | `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 Event-Payload von Claude Code | +| `payload` | `Record` | Vollständige rohe Ereignisnutzlast von Claude Code | | `session` | `SessionMetadata \| undefined` | Sitzungskontext (siehe unten) | ### `SessionMetadata`-Felder | Feld | Typ | Beschreibung | |------|-----|--------------| -| `sessionId` | `string` | Claude Code-Sitzungskennung | +| `sessionId` | `string` | Claude Code-Sitzungsbezeichner | | `cwd` | `string` | Arbeitsverzeichnis der Claude Code-Sitzung | | `transcriptPath` | `string` | Pfad zur JSONL-Transkriptdatei der Sitzung | -### Event-Typen +### Ereignistypen -| 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 ist | Die Eingabe des Tools + `tool_result` (die Ausgabe) | +| 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) | | `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 | @@ -190,16 +190,16 @@ Richtlinien werden in dieser Reihenfolge ausgewertet: 1. Eingebaute Richtlinien (in Definitionsreihenfolge) 2. Explizite benutzerdefinierte 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) +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) -Das erste `deny` bricht die Auswertung aller nachfolgenden Richtlinien ab. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam übermittelt. +Das erste `deny` schließt alle nachfolgenden Richtlinien kurz. Alle `instruct`-Nachrichten werden gesammelt und gemeinsam übermittelt. --- -## Transitive Imports +## Transitive Importe Benutzerdefinierte Richtliniendateien können lokale Module über relative Pfade importieren: @@ -218,13 +218,13 @@ customPolicies.add({ }); ``` -Alle relativen Imports, die von der Einstiegsdatei aus erreichbar sind, werden aufgelöst. Dies wird durch Umschreiben von `from "failproofai"`-Importen auf den tatsächlichen dist-Pfad und Erstellen temporärer `.mjs`-Dateien implementiert, um ESM-Kompatibilität sicherzustellen. +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. --- -## Event-Typ-Filterung +## Ereignistypfilterung -Mit `match.events` lässt sich einschränken, wann eine Richtlinie ausgelöst wird: +Verwende `match.events`, um einzuschränken, wann eine Richtlinie ausgelöst wird: ```js customPolicies.add({ @@ -238,7 +238,7 @@ customPolicies.add({ }); ``` -`match` vollständig weglassen, um bei jedem Event-Typ auszulösen. +Lasse `match` vollständig weg, um bei jedem Ereignistyp auszulösen. --- @@ -246,18 +246,18 @@ customPolicies.add({ Benutzerdefinierte Richtlinien sind **fail-open**: Fehler blockieren niemals eingebaute Richtlinien und bringen den Hook-Handler nicht zum Absturz. -| Fehlerfall | Verhalten | -|-----------|-----------| +| 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 weiter geladen | +| 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; wird als `allow` behandelt | +| `fn` dauert länger als 10 Sekunden | Timeout wird protokolliert; als `allow` behandelt | | Konventionsverzeichnis fehlt | Keine Konventionsrichtlinien werden ausgeführt; kein Fehler | -Um Fehler in benutzerdefinierten Richtlinien zu debuggen, beobachte die Log-Datei: +Um Fehler in benutzerdefinierten Richtlinien zu debuggen, beobachte die Protokolldatei: ```bash tail -f ~/.failproofai/hook.log @@ -285,7 +285,7 @@ customPolicies.add({ }, }); -// Hält den Agenten auf Kurs: Tests vor dem Commit prüfen +// Hält den Agenten auf Kurs: Tests vor dem Commit überprüfen customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +300,7 @@ customPolicies.add({ }, }); -// Verhindert ungeplante Abhängigkeitsänderungen während eines Freeze +// Verhindert ungeplante Abhängigkeitsänderungen während einer Freeze-Periode customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -323,14 +323,14 @@ export { customPolicies }; ## Beispiele -Das Verzeichnis `examples/` enthält sofort ausführbare Richtliniendateien: +Das Verzeichnis `examples/` enthält sofort einsatzbereite Richtliniendateien: | Datei | Inhalt | |-------|--------| -| `examples/policies-basic.js` | Fünf Einstiegsrichtlinien für häufige Agentenausfälle | -| `examples/policies-advanced/index.js` | Fortgeschrittene Muster: transitive Imports, 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, Audit-Dateioperationen) | +| `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) | ### Explizite Dateibeispiele verwenden @@ -350,4 +350,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -Kein Installationsbefehl nötig – die Dateien werden beim nächsten Hook-Event automatisch erkannt. \ No newline at end of file +Kein Installationsbefehl erforderlich – die Dateien werden beim nächsten Hook-Ereignis automatisch erkannt. \ No newline at end of file diff --git a/docs/de/dashboard.mdx b/docs/de/dashboard.mdx index 14509310..610aaa73 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: "Agentensitzungen ü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, was Ihre Agenten in Ihrer Abwesenheit getan haben. +Das failproofai Dashboard ist eine lokale Webanwendung zur Überwachung Ihrer KI-Agentensitzungen und 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 direkt aus dem Dateisystem – aus Ihren Claude Code-Projektordnern und den failproofai-Konfigurationsdateien. Es werden keine Daten an einen Remote-Dienst übertragen. +Das Dashboard liest direkt vom Dateisystem – aus Ihren Claude Code-Projektordnern und den failproofai-Konfigurationsdateien. Es werden keine Daten an einen externen Dienst übertragen. --- @@ -24,11 +24,11 @@ Das Dashboard liest direkt aus dem Dateisystem – aus Ihren Claude Code-Projekt ### Projekte -Listet alle Claude Code-, OpenAI Codex-, GitHub Copilot CLI- _(Beta)_, Cursor Agent- _(Beta)_, OpenCode- _(Beta)_, Pi- _(Beta)_ und Gemini CLI- _(Beta)_ Projekte auf, die auf Ihrem Computer gefunden wurden. Claude-Projekte werden aus `~/.claude/projects/` ermittelt (oder dem Pfad, der über `CLAUDE_PROJECTS_PATH` gesetzt wurde); Codex-Projekte werden durch Durchsuchen aller Transkripte unter `~/.codex/sessions///
/*.jsonl` und Gruppierung nach dem `cwd`-Feld im ersten Datensatz jeder Sitzung erkannt; Copilot CLI-Projekte werden durch Durchsuchen von `~/.copilot/session-state//workspace.yaml` (konfigurierbar über `COPILOT_HOME`) und Gruppierung nach dem `cwd`-Feld gefunden; Cursor Agent-Projekte werden durch Durchsuchen der 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` erkannt; OpenCode-Projekte werden durch Abfrage der 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 Durchsuchen der sitzungsspezifischen JSONL-Transkripte unter `~/.pi/agent/sessions//_.jsonl` (konfigurierbar über `PI_SESSIONS_DIR`) und Auslesen des `cwd`-Werts aus dem ersten Datensatz jeder Sitzung erkannt; Gemini CLI-Projekte werden durch Durchsuchen von `~/.gemini/tmp//chats/session--.jsonl` (konfigurierbar über `GEMINI_SESSIONS_DIR`) und Wiederherstellung des kanonischen cwd aus dem benachbarten `.project_root`-Textmarker gefunden. Ein Projekt, das von mehreren CLIs verwendet wurde, wird als einzelne Zeile mit allen zugehörigen Badges dargestellt. 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|gemini`. +Listet alle Claude Code-, OpenAI Codex-, GitHub Copilot CLI- _(Beta)_, Cursor Agent- _(Beta)_, OpenCode- _(Beta)_, Pi- _(Beta)_, Gemini CLI- _(Beta)_ und Hermes-Projekte auf, die auf Ihrem Rechner gefunden wurden. Claude-Projekte werden aus `~/.claude/projects/` erkannt (oder dem über `CLAUDE_PROJECTS_PATH` festgelegten Pfad); Codex-Projekte werden durch Scannen aller Transkripte unter `~/.codex/sessions///
/*.jsonl` ermittelt und nach dem `cwd` des ersten Eintrags jeder Sitzung gruppiert; Copilot CLI-Projekte werden durch Scannen von `~/.copilot/session-state//workspace.yaml` (konfigurierbar über `COPILOT_HOME`) und Gruppierung nach dem dortigen `cwd`-Feld erkannt; Cursor Agent-Projekte werden durch Scannen der 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` erkannt; OpenCode-Projekte werden durch Abfrage der SQLite-Datenbank unter `~/.local/share/opencode/opencode.db` via `opencode db --format json` ermittelt (dabei 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 Eintrag jeder Sitzung erkannt; Gemini CLI-Projekte werden durch Scannen von `~/.gemini/tmp//chats/session--.jsonl` (konfigurierbar über `GEMINI_SESSIONS_DIR`) und Rückgewinnung des kanonischen cwd aus dem benachbarten `.project_root`-Textmarker erkannt; Hermes-Gateway-Sitzungen werden direkt aus dem SQLite-Store 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. Ein Projekt, das von mehreren CLIs genutzt wurde, wird als einzelne Zeile mit allen zugehörigen Badges angezeigt. Verwenden Sie das **CLI**-Dropdown über der Tabelle, um nach einer bestimmten Agenten-CLI zu filtern; die URL speichert Ihre Auswahl als `?cli=claude|codex|copilot|cursor|opencode|pi|gemini|hermes`. 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 `Gemini CLI` (himmelblau) +- Ein CLI-Badge — `Claude Code` (orange), `OpenAI Codex` (lila), `GitHub Copilot` (blau), `Cursor Agent` (smaragd), `OpenCode` (bernstein), `Pi` (pink), `Gemini CLI` (himmelblau) und/oder `Hermes` (indigo) - Datum der letzten Sitzungsaktivität Klicken Sie auf ein Projekt, um dessen Sitzungen anzuzeigen. @@ -41,50 +41,50 @@ Listet alle Sitzungen innerhalb eines Projekts auf. Jede Sitzung zeigt: - Anzahl der Tool-Aufrufe - Anzahl der Hook-Aktivitäten (ausgelöste Richtlinien) -Verwenden Sie den Datumsbereichsfilter und die Sitzungs-ID-Suche, um die Liste einzuschränken. Sitzungen werden seitenweise angezeigt. +Verwenden Sie den Datumsbereichsfilter und die Sitzungs-ID-Suche, um die Liste einzugrenzen. Sitzungen werden paginiert 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 entscheidende Frage bei autonomen Agenten: Was hat der Agent getan, und hat er sich auf Kurs gehalten? Ein CLI-Badge neben der Überschrift zeigt an, ob es sich um ein Claude Code-, OpenAI Codex-, GitHub Copilot CLI-, Cursor Agent-, OpenCode-, Pi- oder Gemini CLI-Transkript handelt. Er zeigt eine Zeitachse aller Ereignisse 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 es sich um ein Claude Code-, OpenAI Codex-, GitHub Copilot CLI-, Cursor Agent-, OpenCode-, Pi-, Gemini CLI- oder Hermes-Transkript handelt. Er zeigt eine Zeitleiste aller Ereignisse einer Sitzung: -- **Nachrichten** – Claudes Textantworten und Benutzereingaben -- **Tool-Aufrufe** – Jeder 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 +- **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 getroffen haben -Die Statusleiste oben zeigt Sitzungsdauer, Gesamtanzahl der Tool-Aufrufe und eine Zusammenfassung der Hook-Entscheidungen (Anzahl 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-, Pi- und Gemini-Sitzungen erhalten Sie das originale JSONL-Transkript vom Datenträger Byte für Byte; bei OpenCode (dessen Sitzungen in SQLite statt auf dem Datenträger gespeichert sind) erhalten Sie ein JSON-Dokument, das die zugrunde liegenden Tabellen `session` / `messages` / `parts` abbildet. +Klicken Sie auf **Logs herunterladen**, um die Sitzung zu exportieren. Für Claude Code-, Codex-, Copilot-, Cursor-, Pi- und Gemini-Sitzungen erhalten Sie das originale JSONL-Transkript vom Datenträger byte-genau; für OpenCode (dessen Sitzungen in SQLite und nicht auf dem Datenträger gespeichert sind) erhalten Sie ein JSON-Dokument, das die zugrundeliegenden Tabellen `session` / `messages` / `parts` widerspiegelt. ### Audit -Ein persönlichkeitsbasierter Bericht darüber, wie sich Ihr Agent tatsächlich über vergangene Sitzungen hinweg verhalten hat. Führt denselben Scan wie das `failproofai audit`-CLI aus, stellt das Ergebnis jedoch als einzeln anzeigbares, teilbares Poster dar – ergänzt durch vier Abschnitte unterhalb des sichtbaren Bereichs: +Ein persönlichkeitsgesteuerter Bericht darüber, wie sich Ihr Agent tatsächlich über vergangene Sitzungen hinweg verhalten hat. Führt denselben Scan wie der `failproofai audit`-CLI durch, stellt ihn jedoch als einzeiligen teilbaren Poster + vier darunter liegende Abschnitte dar: -1. **Poster** — füllt den ersten Viewport. Eigenständiger PNG-Erfassungsbereich mit dem failproof_ai-Schriftzug + Audit-Label · Archetyp-Index (`№ NN von 08`) + Audit-Datum · numerischer Score (0–100) + Perzentilrang-Pille (`top 15%`) · der Archetyp-Name (eines 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`-Seltenheitszeile · 8×8-Pixel-Siegel-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 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 an main, keine Credential-Leaks, keine Retry-Stürme) — jede Zeile erscheint nur, wenn die relevante Richtlinie über das gesamte Audit-Fenster hinweg ein sauberes Protokoll aufweist. -3. **Eigenheiten** — Tabelle der durchgerutschten Probleme, nach Schweregrad gerankt: `Zeitpunkt · was durchrutschte + die Richtlinie, die es abgefangen hätte · Schweregrad-Pille · gesehen`, wobei die Häufigkeit als `new` (einmal), `N× seen` (2–9 Mal) oder `recurring` (10+) angegeben wird. -4. **So verbessern Sie sich** — ruhige Zeilenliste, eine pro empfohlener Richtlinie: Richtlinienname in Weiß, einzeilige Beschreibung, Installationsbefehl + Kopier-Schaltfläche auf der rechten Seite. Die Abschnittsüberschrift lautet `enable all N → projected · ` (der Score, den Sie mit allen Korrekturen erreichen würden), und die Schaltfläche `[install all]` kopiert den kombinierten `failproofai policy add a b c …`-Befehl für alle empfohlenen Richtlinien. -5. **Kommen Sie besser zurück** — zwei nebeneinander angeordnete Karten. Links: Erinnerung setzen (`3d` / `7d` / `14d` / `30d` Intervall-Auswahl; wird über `/api/auth/reminder` nach Authentifizierung gespeichert). Rechts: failproof-Vorteile freischalten — `invite a friend` öffnet ein Modal, das eine komma-/leerzeichen-/zeilentrennte Liste von Freundes-E-Mail-Adressen entgegennimmt (max. 10 pro Versand), diese per POST an `/api/audit/invite` sendet, was an den api-server's `POST /v0/invite` 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 im Posteingang erhält. Anonyme Benutzer werden zuerst durch den `AuthDialog` geleitet, damit die E-Mail-Adresse des Absenders bekannt ist, bevor Einladungen verschickt werden. Berechtigungs-/Vorteilsabwicklung folgt in einem späteren Schritt. +1. **Poster** — füllt den ersten Viewport. Eigenständiger PNG-Erfassungsbereich mit dem failproof_ai-Schriftzug + Audit-Label · Archetyp-Index (`№ NN of 08`) + Audit-Datum · numerischer Score (0–100) + Perzentil-Rangpille (`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-Schlagwort-Streifen · `// only N% of agents are this archetype`-Seltenheitszeile · 8×8-Pixel-Sigil-Kachel · `audit yours → failproof.ai`-Fußzeile. Drei Share-Buttons 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 der Bildschirmdarstellung entspricht (gestrichelte Rahmen, SVG-Logo-Maske, Farbverläufe, Schriftmetriken – alles erhalten). +2. **Stärken** — ruhige ✓-Zeilenliste mit Verhaltensweisen, die Ihr Agent bereits richtig macht, abgeleitet aus den Live-Audit-Daten (saubere Tool-Aufruf-Rate, keine direkten Pushes auf main, null Zugangsdaten-Lecks, null Wiederholungs-Stürme) — jede wird nur angezeigt, wenn die zugehörige Richtlinie im Audit-Zeitraum eine einwandfreie Bilanz hat. +3. **Eigenheiten** — Tabelle mit dem, was durchgerutscht ist, nach Schwere sortiert: `wann · was durchgerutscht ist + die Richtlinie, die es hätte abfangen können · Schwere-Pille · gesehen`, wobei die Häufigkeit `new` (einmal), `N× seen` (2–9 Mal) oder `recurring` (10+) anzeigt. +4. **So verbessern Sie sich** — ruhige Zeilenliste, eine pro empfohlener Richtlinie: Richtlinienname in Weiß, einzeilige Beschreibung, Installationsbefehl + Kopier-Button auf der rechten Seite. Die Abschnittsüberschrift lautet `enable all N → projected · ` (der Score, den Sie mit allen Korrekturen erreichen würden), und der `[install all]`-Button kopiert den kombinierten `failproofai policy add a b c …`-Befehl für alle empfohlenen Richtlinien. +5. **Kommen Sie besser zurück** — zwei nebeneinander liegende Karten. Links: Erinnerung setzen (`3d` / `7d` / `14d` / `30d`-Kadenz-Auswahl; wird über `/api/auth/reminder` nach Authentifizierung gespeichert). Rechts: failproof-Vorteile freischalten — `invite a friend` öffnet ein Modal, das eine komma-/leerzeichen-/zeilenumbruch-getrennte Liste von Freundes-E-Mails akzeptiert (max. 10 pro Sendung), sendet diese per POST an `/api/audit/invite`, der sie an den `POST /v0/invite`-Endpunkt des API-Servers weiterleitet. Der API-Server sendet eine E-Mail pro Empfänger von `invite@failproof.ai` mit dem Absender in 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 zunächst durch den `AuthDialog` geleitet, damit die Absender-E-Mail vor dem Versand der Einladungen bekannt ist. Berechtigungen/Vorteile-Erfüllung ist ein Folgeschritt. -Betrieben durch die `failproofai audit`-Laufzeit — siehe [Audit CLI](/de/cli/audit) für die zugrunde liegende Scan-Engine, unterstützte Flags und sitzungsspezifische Cache-Invarianten. Das Dashboard speichert das neueste Ergebnis unter `~/.failproofai/audit-dashboard.json` (Modus `0600`, einzelner Slot, neue Läufe überschreiben) im Cache, sodass erneute Aufrufe sofort erfolgen; **sowohl der sitzungsspezifische als auch der gesamte Ergebnis-Cache werden beim Lesen verworfen, sobald sie älter als 7 Tage sind**, sodass das Dashboard nie stillschweigend ein wochenaltes Ergebnis liefert — nach Ablauf der TTL fällt `/audit` in seinen leeren Zustand zurück und fordert einen neuen Scan an. Ein Klick auf `[ re-audit now ]` am unteren Ende des Berichts sendet POST an `/api/audit/run` mit `noCache: true` — ein erneuter Audit umgeht den sitzungsspezifischen 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 der Lauf abgeschlossen ist; ein pinker Fortschrittsstreifen wird während des Laufs mit einem Elapsed-Timer oben im Viewport angeheftet, und das neue Ergebnis wird nach Erfolg direkt eingetauscht (kein vollständiger Seitenneuladevorgang; ein fehlgeschlagener erneuter Audit lässt den vorherigen Bericht unverändert). Bei einem Fehler wird der Streifen rot mit einem auf `RerunError.kind` abgestimmten Text (`timeout` / `network` / `post_failed`). Leerer Zustand (kein Cache oder abgelaufen) und Nullsitzungszustand (Cache vorhanden, aber der Scan hat keine Transkripte gefunden) werden separat angezeigt. +Betrieben vom `failproofai audit`-Runtime — siehe [Audit CLI](/de/cli/audit) für die zugrundeliegende Scan-Engine, unterstützte Flags und Transkript-spezifische Cache-Invarianten. Das Dashboard speichert das neueste Ergebnis unter `~/.failproofai/audit-dashboard.json` (Modus `0600`, einzelner Slot, neue Läufe überschreiben), sodass Revisits sofort erfolgen; **sowohl der Transkript-spezifische als auch der Gesamt-Ergebnis-Cache werden beim Lesen abgelehnt, sobald sie älter als 7 Tage sind**, sodass das Dashboard niemals still ein wochealtes Ergebnis ausliefert — nach Ablauf der TTL fällt `/audit` in seinen leeren Zustand 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` — der Re-Audit umgeht den Transkript-Cache und scannt jedes Transkript von Grund auf neu, anstatt das gecachte Ergebnis still zurückzugeben — und das Dashboard fragt `/api/audit/status` mit 1 Hz ab, bis der Lauf abgeschlossen ist; ein anheftender pinker Fortschrittsstreifen fixiert sich während des Laufs oben im Viewport mit einem Laufzeit-Timer, 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 unberührt). Bei einem Fehler wird der Streifen rot mit Text, der auf `RerunError.kind` abgestimmt ist (`timeout` / `network` / `post_failed`). Leerzustand (kein Cache oder abgelaufen) und Null-Sitzungszustand (Cache existiert, aber der Scan fand keine Transkripte) werden separat angezeigt. ### Richtlinien -Eine Seite mit zwei Tabs zur Verwaltung von Richtlinien und zur Überprüfung von Aktivitäten. +Eine zweiseitige Seite zur Verwaltung von Richtlinien und Überprüfung der Aktivität. - - - Wählen Sie in einem einzigen Panel aus, welche Agent-CLIs failproofai schützen soll — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi und Gemini CLI haben jeweils eine Zeile mit Installationsstatus (`Active` / `Detected` / `Inactive`), dem benutzerspezifischen Einstellungspfad und einem markenfarbenakzentuierten 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 vorab ausgewählt. - - Aktivieren oder deaktivieren Sie einzelne Richtlinien mit einem Klick (schreibt in `~/.failproofai/policies-config.json` — gilt für alle installierten CLIs) + + - Wählen Sie in einem einzelnen Panel aus, welche Agenten-CLIs failproofai schützt — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Gemini CLI und Hermes haben jeweils eine Zeile mit Installationsstatus (`Active` / `Detected` / `Inactive`), dem benutzerbereichs-spezifischen Einstellungspfad und einem markenfarbigen 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 Binärdatei im PATH erkannt wird, sind vorab aktiviert. + - Aktivieren oder deaktivieren Sie einzelne Richtlinien mit einem einzigen Klick (schreibt in `~/.failproofai/policies-config.json` — gemeinsam genutzt von allen installierten CLIs) - Erweitern Sie eine Richtlinie, um ihre Parameter zu konfigurieren (für Richtlinien, die `policyParams` unterstützen) - - Legen Sie einen benutzerdefinierten Pfad für die Richtliniendatei fest + - Legen Sie einen benutzerdefinierten Richtliniendateipfad fest - - - Vollständige seitenweise Historie aller Hook-Ereignisse, die über alle Sitzungen hinweg ausgelöst wurden - - Filtern nach Entscheidung, Ereignistyp, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(Beta)_ / Cursor Agent _(Beta)_ / OpenCode _(Beta)_ / Pi _(Beta)_ / Gemini CLI _(Beta)_), 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, himmelblau = Gemini CLI), Tool-Name, Sitzungs-ID und den Grund für deny/instruct-Entscheidungen - - Klicken Sie auf eine Sitzungs-ID, um das 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`) und zeigt das passende CLI-Badge in der Kopfzeile an + + - Vollständige paginierte Historie aller Hook-Ereignisse, die in allen Sitzungen ausgelöst wurden + - Filtern nach Entscheidung, Ereignistyp, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(Beta)_ / Cursor Agent _(Beta)_ / OpenCode _(Beta)_ / Pi _(Beta)_ / Gemini CLI _(Beta)_ / Hermes), Richtlinienname oder Sitzungs-ID + - Jede Zeile zeigt: Zeitstempel, Richtlinienname, Entscheidung, CLI-Badge (orange = Claude Code, lila = OpenAI Codex, blau = GitHub Copilot, smaragd = Cursor Agent, bernstein = OpenCode, pink = Pi, himmelblau = Gemini CLI, indigo = Hermes), Tool-Name, Sitzungs-ID und den Grund für deny/instruct-Entscheidungen + - Klicken Sie auf eine Sitzungs-ID, um das zugehörige 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`, Hermes `~/.hermes/state.db`) und zeigt das passende CLI-Badge in der Überschrift an @@ -92,7 +92,7 @@ Eine Seite mit zwei Tabs zur Verwaltung von Richtlinien und zur Überprüfung vo ## Automatische Aktualisierung -Das Dashboard verfügt über eine Umschalttaste 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 erscheinen. Unverzichtbar für die Überwachung langläufiger autonomer Agent-Sitzungen. +Das Dashboard verfügt über eine Auto-Refresh-Umschalttaste 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 langläufiger autonomer Agentensitzungen. --- @@ -110,7 +110,7 @@ Gültige Werte: `policies`, `projects`, `audit`. ## Projektpfad konfigurieren -Standardmäßig liest das Dashboard aus dem Standard-Claude Code-Projektverzeichnis. Überschreiben Sie es für benutzerdefinierte Setups: +Standardmäßig liest das Dashboard aus dem standardmäßigen Claude Code-Projektverzeichnis. Überschreiben Sie dies für benutzerdefinierte Setups: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,13 +120,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`) ausführen und von einem anderen Hostnamen als `localhost` darauf zugreifen — zum Beispiel einer benutzerdefinierten Domain, einer Remote-IP oder einer getunnelten URL — wird möglicherweise eine Warnung angezeigt 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 — kann folgende Warnung auftreten: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Hierbei blockiert Next.js den ursprungsübergreifenden Zugriff auf seinen HMR-WebSocket (Hot Module Reload), der eine reine Entwicklungsfunktion ist. Um Ihren Host zuzulassen, verwenden Sie das Flag `--allowed-origins`: +Dies ist Next.js, das den cross-origin-Zugriff auf seinen HMR-WebSocket (Hot Module Reload) blockiert, eine reine Entwicklungsfunktion. Um Ihren Host zuzulassen, verwenden Sie das Flag `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -138,12 +138,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` setzen: +Sie können stattdessen auch die Umgebungsvariable `FAILPROOFAI_ALLOWED_DEV_ORIGINS` 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 keine ursprungsübergreifenden Dev-Ressourcenprobleme. +Dies gilt nur für den Dev-Modus. Beim Ausführen von `failproofai` (Produktionsmodus) gibt es keinen HMR-WebSocket und kein cross-origin-Entwicklungsressourcenproblem. \ No newline at end of file diff --git a/docs/de/examples.mdx b/docs/de/examples.mdx index b21bac70..61822f28 100644 --- a/docs/de/examples.mdx +++ b/docs/de/examples.mdx @@ -1,16 +1,16 @@ --- title: Beispiele -description: "Hooks für Claude Code und das Agents SDK einrichten" +description: "Wie man Hooks für Claude Code und das Agents SDK einrichtet" icon: book-open --- -Sofort einsetzbare Beispiele für häufige Szenarien. Jedes zeigt, wie man es installiert und was zu erwarten ist. +Sofort einsetzbare Beispiele für häufige Szenarien. Jedes Beispiel zeigt, wie man es installiert und was zu erwarten ist. --- ## Hooks für Claude Code einrichten -Failproof AI integriert sich in Claude Code über dessen [Hooks-System](https://docs.anthropic.com/en/docs/claude-code/hooks). Wenn Sie `failproofai policies --install` ausführen, registriert es Hook-Befehle in der `settings.json` von Claude Code, die bei jedem Tool-Aufruf ausgelöst werden. +Failproof AI integriert sich mit Claude Code über dessen [Hooks-System](https://docs.anthropic.com/en/docs/claude-code/hooks). Wenn du `failproofai policies --install` ausführst, werden Hook-Befehle in der `settings.json` von Claude Code registriert, die bei jedem Tool-Aufruf ausgelöst werden. @@ -23,19 +23,19 @@ Failproof AI integriert sich in Claude Code über dessen [Hooks-System](https:// failproofai policies --install ``` - + ```bash cat ~/.claude/settings.json | grep failproofai ``` - Sie sollten Hook-Einträge für `PreToolUse`, `PostToolUse`, `Notification` und `Stop`-Ereignisse sehen. + Du solltest Hook-Einträge für `PreToolUse`, `PostToolUse`, `Notification` und `Stop`-Ereignisse sehen. ```bash claude ``` - Richtlinien werden nun automatisch bei jedem Tool-Aufruf ausgeführt. Bitten Sie Claude, `sudo rm -rf /` auszuführen – der Befehl wird blockiert. + Richtlinien werden jetzt automatisch bei jedem Tool-Aufruf ausgeführt. Versuch, Claude zu bitten, `sudo rm -rf /` auszuführen – es wird blockiert. @@ -43,23 +43,23 @@ Failproof AI integriert sich in Claude Code über dessen [Hooks-System](https:// ## Hooks für das Agents SDK einrichten -Wenn Sie mit dem [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) entwickeln, können Sie dasselbe Hook-System programmatisch nutzen. +Wenn du mit dem [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) entwickelst, kannst du dasselbe Hook-System programmatisch nutzen. - + ```bash npm install failproofai ``` - - Übergeben Sie Hook-Befehle beim Erstellen Ihres Agent-Prozesses. Die Hooks werden genauso ausgelöst wie in Claude Code – über stdin/stdout JSON: + + Übergib Hook-Befehle beim Erstellen deines Agenten-Prozesses. Die Hooks werden genauso ausgelöst wie in Claude Code – über stdin/stdout JSON: ```bash failproofai --hook PreToolUse # wird vor jedem Tool aufgerufen failproofai --hook PostToolUse # wird nach jedem Tool aufgerufen ``` - + ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -88,15 +88,15 @@ Wenn Sie mit dem [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) ent ## Destruktive Befehle blockieren -Das häufigste Setup – verhindert, dass Agenten irreversible Schäden anrichten. +Das häufigste Setup – verhindert, dass Agenten irreversiblen Schaden anrichten. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` -Was das bewirkt: +Was dies bewirkt: - `block-sudo` – blockiert alle `sudo`-Befehle -- `block-rm-rf` – blockiert das rekursive Löschen von Dateien +- `block-rm-rf` – blockiert rekursives Löschen von Dateien - `block-force-push` – blockiert `git push --force` - `block-curl-pipe-sh` – blockiert das Weiterleiten von Remote-Skripten an die Shell @@ -104,7 +104,7 @@ Was das bewirkt: ## Geheimnis-Lecks verhindern -Verhindert, dass Agenten Anmeldedaten in der Tool-Ausgabe sehen oder weitergeben. +Verhindert, dass Agenten Zugangsdaten in der Tool-Ausgabe sehen oder weitergeben. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens @@ -114,9 +114,9 @@ Diese werden bei `PostToolUse` ausgelöst – nachdem ein Tool ausgeführt wurde --- -## Slack-Benachrichtigungen erhalten, wenn Agenten Aufmerksamkeit benötigen +## Slack-Benachrichtigungen erhalten, wenn Agenten Aufmerksamkeit brauchen -Verwenden Sie den Notification-Hook, um Leerlauf-Benachrichtigungen an Slack weiterzuleiten. +Verwende den Notification-Hook, um Leerlauf-Benachrichtigungen an Slack weiterzuleiten. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -142,7 +142,7 @@ customPolicies.add({ signal: AbortSignal.timeout(5000), }); } catch { - // den Agent niemals blockieren, wenn Slack nicht erreichbar ist + // den Agenten niemals blockieren, wenn Slack nicht erreichbar ist } return allow(); @@ -160,7 +160,7 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c ## Agenten auf einem Branch halten -Verhindert, dass Agenten Branches wechseln oder auf geschützte Branches pushen. +Verhindert, dass Agenten Branches wechseln oder in geschützte Branches pushen. ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -182,7 +182,7 @@ customPolicies.add({ --- -## Tests vor Commits verlangen +## Tests vor Commits voraussetzen Erinnert Agenten daran, vor einem Commit Tests auszuführen. @@ -208,9 +208,9 @@ customPolicies.add({ ## Ein Produktions-Repository absichern -Committen Sie eine projektweite Konfiguration, damit alle Entwickler in Ihrem Team dieselben Richtlinien erhalten. +Lege eine projektweite Konfiguration fest, sodass alle Entwickler in deinem Team dieselben Richtlinien erhalten. -Erstellen Sie `.failproofai/policies-config.json` in Ihrem Repository: +Erstelle `.failproofai/policies-config.json` in deinem Repository: ```json { @@ -242,9 +242,9 @@ Jedes Teammitglied, das failproofai installiert hat, übernimmt diese Regeln aut --- -## Einen teamweiten Qualitätsstandard mit Konventionsrichtlinien aufbauen +## Einen organisationsweiten Qualitätsstandard mit Convention Policies aufbauen -Das wirkungsvollste Setup: Committen Sie `.failproofai/policies/` in Ihr Repository mit auf Ihr Projekt zugeschnittenen Richtlinien. Jedes Teammitglied erhält sie automatisch – keine Installationsbefehle, keine Konfigurationsänderungen. +Das wirkungsvollste Setup: Committe `.failproofai/policies/` in dein Repository mit auf dein Projekt zugeschnittenen Richtlinien. Jedes Teammitglied erhält sie automatisch – keine Installationsbefehle, keine Konfigurationsänderungen. @@ -290,7 +290,7 @@ Das wirkungsvollste Setup: Committen Sie `.failproofai/policies/` in Ihr Reposit ``` - Wenn Ihr Team auf neue Fehlerquellen stößt, fügen Sie Richtlinien hinzu und pushen Sie. Alle erhalten das Update beim nächsten `git pull`. Diese Richtlinien werden zu einem lebendigen Qualitätsstandard, der mit Ihrem Team wächst. + Sobald euer Team auf neue Fehlerquellen stößt, fügt Richtlinien hinzu und pusht sie. Alle erhalten das Update beim nächsten `git pull`. Diese Richtlinien werden zu einem lebendigen Qualitätsstandard, der mit eurem Team wächst. @@ -301,7 +301,7 @@ Das wirkungsvollste Setup: Committen Sie `.failproofai/policies/` in Ihr Reposit Das Verzeichnis [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) im Repository enthält: | Datei | Inhalt | -|------|---------------| -| `policies-basic.js` | Einstiegsrichtlinien – Produktions-Writes blockieren, Force-Push, weitergeleitete Skripte | -| `policies-notification.js` | Slack-Benachrichtigungen bei Leerlauf und Sitzungsende | -| `policies-advanced/index.js` | Transitive Imports, asynchrone Hooks, PostToolUse-Ausgabebereinigung, Stop-Event-Behandlung | \ No newline at end of file +|-------|--------| +| `policies-basic.js` | Grundlegende Richtlinien – Produktions-Schreibzugriffe, Force-Push und Piped-Skripte blockieren | +| `policies-notification.js` | Slack-Benachrichtigungen für Leerlauf-Meldungen und Sitzungsende | +| `policies-advanced/index.js` | Transitive Imports, asynchrone Hooks, PostToolUse-Ausgabenbereinigung, Stop-Ereignisbehandlung | \ No newline at end of file diff --git a/docs/de/for-agents.mdx b/docs/de/for-agents.mdx index cf29b604..cda1b72f 100644 --- a/docs/de/for-agents.mdx +++ b/docs/de/for-agents.mdx @@ -3,25 +3,25 @@ title: "Für Agenten" description: "Failproof AI-Wissen in einem Befehl zu deinem Coding-Agenten hinzufügen. Funktioniert mit Claude Code, Cursor, Windsurf und mehr." --- -Füge die vollständige Failproof AI-Referenz in einem Befehl zu deinem Coding-Agenten hinzu. Funktioniert mit Claude Code, Cursor, Windsurf und jedem anderen Agenten, der Skills unterstützt. +Füge die vollständige Failproof AI-Referenz in einem einzigen Befehl zu deinem Coding-Agenten hinzu. Funktioniert mit Claude Code, Cursor, Windsurf und jedem anderen Agenten, der Skills unterstützt. ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` erkennt automatisch, welche Agenten du installiert hast, und fügt den Skill für jeden im richtigen Format hinzu. +`npx skills` erkennt automatisch, welche Agenten installiert sind, und fügt den Skill für jeden im richtigen Format hinzu. ## Was der Skill abdeckt | Bereich | Inhalt | |---------|--------| | Policies | Integrierte Policy-Namen, Event-Typen, Parameter, aktivieren/deaktivieren | -| Benutzerdefinierte Policies | `customPolicies.add()`, Match-Filter, `allow`/`deny`/`instruct`-API | +| Custom policies | `customPolicies.add()`, Match-Filter, `allow`/`deny`/`instruct`-API | | Context-Objekt | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | | Konfiguration | `policies-config.json`-Struktur, Scope-Zusammenführung, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, Scopes | | Dashboard | Session-Viewer, Policy-Aktivität, Umgebungsvariablen | -| Architektur | Hook-Handler-Flow, Exit-Codes, stdin/stdout-Vertrag | +| Architektur | Hook-Handler-Ablauf, Exit-Codes, stdin/stdout-Vertrag | ## Ist der Skill vollständig? diff --git a/docs/de/getting-started.mdx b/docs/de/getting-started.mdx index 67601c0a..4499b6f3 100644 --- a/docs/de/getting-started.mdx +++ b/docs/de/getting-started.mdx @@ -1,13 +1,13 @@ --- title: Erste Schritte -description: "failproofai installieren, Richtlinien aktivieren und Agenten zuverlässig ausführen" +description: "Installiere failproofai, aktiviere Richtlinien und lass deine Agenten zuverlässig arbeiten" icon: rocket --- ## Voraussetzungen - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (optional – nur beim Erstellen aus dem Quellcode erforderlich) +- **Bun** >= 1.3.0 (optional – nur zum Kompilieren aus dem Quellcode erforderlich) --- @@ -31,15 +31,15 @@ bun add -g failproofai - Richtlinien sind Regeln, die vor und nach jedem Werkzeugaufruf eines Agenten ausgeführt werden. Sie erkennen destruktive Befehle, den Abfluss von Geheimnissen und andere Fehlerquellen, bevor Schaden entsteht. + Richtlinien sind Regeln, die vor und nach jedem Agenten-Tool-Aufruf ausgeführt werden. Sie erkennen destruktive Befehle, den Abfluss von Geheimnissen und andere Fehlerquellen, bevor sie Schaden anrichten können. ```bash failproofai policies --install ``` - Damit werden Hook-Einträge in die installierten Agent-CLIs geschrieben (Claude Code's `~/.claude/settings.json`, OpenAI Codex's `~/.codex/hooks.json`, GitHub Copilot CLI's `~/.copilot/hooks/failproofai.json`, Cursor Agent's `~/.cursor/hooks.json`, OpenCode's generierter Plugin-Shim unter `~/.config/opencode/plugins/failproofai.mjs` sowie ein Registrierungseintrag im `plugin`-Array von `~/.config/opencode/opencode.json`, Pi's `~/.pi/agent/settings.json` oder Gemini CLI's `~/.gemini/settings.json`). Sind mehrere vorhanden, wird eine Auswahl angezeigt; übergeben Sie `--cli claude codex copilot cursor opencode pi gemini` (beliebige Teilmenge), um die Auswahl zu überspringen. + Damit werden Hook-Einträge in die installierten Agenten-CLIs geschrieben (Claude Codes `~/.claude/settings.json`, OpenAI Codex' `~/.codex/hooks.json`, GitHub Copilot CLIs `~/.copilot/hooks/failproofai.json`, Cursor Agents `~/.cursor/hooks.json`, OpenCodes generiertem Plugin-Shim unter `~/.config/opencode/plugins/failproofai.mjs` sowie einem Registrierungseintrag im `plugin`-Array von `~/.config/opencode/opencode.json`, Pis `~/.pi/agent/settings.json`, Gemini CLIs `~/.gemini/settings.json` oder Hermes' `~/.hermes/config.yaml`). Sind mehrere installiert, wirst du zur Auswahl aufgefordert; übergib `--cli claude codex copilot cursor opencode pi gemini hermes` (beliebige Teilmenge), um die Abfrage zu überspringen. - Die Unterstützung für GitHub Copilot CLI, Cursor Agent, OpenCode, Pi und Gemini CLI befindet sich im **Beta**-Stadium – Installation mit `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi` oder `--cli gemini`. + Unterstützung für GitHub Copilot CLI, Cursor Agent, OpenCode, Pi und Gemini CLI ist **Beta** – Installation mit `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi` oder `--cli gemini`. Hermes (hermes-agent, ein Slack/Telegram-Gateway) wird im Benutzerbereich mit `--cli hermes` installiert und ist **ebenfalls** eine Offline-Auditquelle. ```bash failproofai policies --install --scope project @@ -49,6 +49,7 @@ bun add -g failproofai failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project + failproofai policies --install --cli hermes --scope user failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` @@ -57,17 +58,17 @@ bun add -g failproofai failproofai policies ``` - Zeigt alle Richtlinien, ob sie aktiviert sind und welche Parameter konfiguriert wurden. + Zeigt alle Richtlinien, ihren Aktivierungsstatus und konfigurierte Parameter an. ```bash failproofai ``` - Öffnet ein lokales Dashboard unter `http://localhost:8020`, in dem Sie Sitzungen durchsuchen, Werkzeugaufrufe untersuchen und Richtlinien verwalten können. + Öffnet ein lokales Dashboard unter `http://localhost:8020`, in dem du Sitzungen durchsuchen, Tool-Aufrufe einsehen und Richtlinien verwalten kannst. - Starten Sie Claude Code wie gewohnt. Versucht der Agent etwas Riskantes, greift failproofai automatisch ein. Lassen Sie ihn unbeaufsichtigt laufen und überprüfen Sie anschließend im Dashboard, was passiert ist. + Starte Claude Code wie gewohnt. Versucht der Agent etwas Riskantes, greift failproofai automatisch ein. Lass ihn unbeaufsichtigt laufen und prüfe anschließend im Dashboard, was passiert ist. @@ -75,7 +76,7 @@ bun add -g failproofai ## So funktionieren Richtlinien -Jedes Mal, wenn ein Agent ein Werkzeug aufruft, startet Claude Code failproofai als Unterprozess: +Jedes Mal, wenn ein Agent ein Tool ausführt, ruft Claude Code failproofai als Subprozess auf: ```text Claude Code → failproofai --hook PreToolUse → reads stdin JSON @@ -86,18 +87,18 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON Jede Richtlinie gibt eine von drei Entscheidungen zurück: - **allow** – der Agent fährt normal fort -- **deny** – die Aktion wird blockiert, der Agent erhält eine Begründung +- **deny** – die Aktion wird blockiert, der Agent erfährt den Grund - **instruct** – dem Prompt des Agenten wird zusätzlicher Kontext hinzugefügt -Richtlinien werden in Ihrem lokalen Prozess ausgeführt. Es werden keine Daten an einen externen Dienst übertragen. +Richtlinien laufen in deinem lokalen Prozess. Es werden keine Daten an einen externen Dienst gesendet. --- ## Team-Richtlinien mit konventionsbasierten Richtlinien einrichten -Der schnellste Weg, teamweite Qualitätsstandards einzuführen, ist die `.failproofai/policies/`-Konvention. Legen Sie Richtliniendateien in dieses Verzeichnis, und sie werden automatisch geladen – ohne Flags, ohne Konfigurationsänderungen, ohne Installationsbefehle. +Der schnellste Weg, einheitliche Qualitätsstandards im Team einzuführen, ist die `.failproofai/policies/`-Konvention. Lege Richtliniendateien in dieses Verzeichnis und sie werden automatisch geladen – keine Flags, keine Konfigurationsänderungen, keine Installationsbefehle. @@ -106,13 +107,13 @@ Der schnellste Weg, teamweite Qualitätsstandards einzuführen, ist die `.failpr ``` - Kopieren Sie die Starter-Beispiele oder schreiben Sie eigene: + Kopiere die Beispieldateien oder schreibe eigene: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ ``` - Oder erstellen Sie eine neue: + Oder erstelle eine neue: ```js // .failproofai/policies/team-policies.mjs @@ -137,26 +138,26 @@ Der schnellste Weg, teamweite Qualitätsstandards einzuführen, ist die `.failpr git commit -m "Add team quality policies" ``` - Jedes Teammitglied, das failproofai installiert hat, übernimmt diese Richtlinien automatisch. Es ist keine individuelle Einrichtung pro Entwickler erforderlich. + Alle Teammitglieder, die failproofai installiert haben, erhalten diese Richtlinien automatisch. Kein individuelles Setup erforderlich. -Checken Sie `.failproofai/policies/` in Ihr Repository ein, damit das gesamte Team dieselben Standards teilt. Wenn Ihr Team neue Fehlerquellen entdeckt, fügen Sie Richtlinien hinzu und pushen Sie – alle erhalten das Update beim nächsten `git pull`. Mit der Zeit werden diese Richtlinien zu einem lebendigen Qualitätsstandard, der sich kontinuierlich verbessert. +Checke `.failproofai/policies/` in dein Repository ein, damit das gesamte Team dieselben Standards verwendet. Wenn neue Fehlerquellen entdeckt werden, füge Richtlinien hinzu und pushe sie – alle erhalten das Update beim nächsten `git pull`. Im Laufe der Zeit werden diese Richtlinien zu einem lebendigen Qualitätsstandard, der sich kontinuierlich verbessert. --- ## Datenspeicherung -Alle Konfigurationen und Protokolle verbleiben auf Ihrem Rechner: +Alle Konfigurationen und Protokolle verbleiben auf deinem Rechner: | Pfad | Inhalt | |------|--------| | `~/.failproofai/policies-config.json` | Globale Richtlinienkonfiguration | | `~/.failproofai/hook-activity.jsonl` | Hook-Ausführungsverlauf | | `~/.failproofai/hook.log` | Debug-Protokoll für benutzerdefinierte Hook-Fehler | -| `.failproofai/policies-config.json` | Projektspezifische Konfiguration (eingecheckt) | +| `.failproofai/policies-config.json` | Projektbezogene Konfiguration (eingecheckt) | | `.failproofai/policies-config.local.json` | Persönliche Überschreibungen (per gitignore ausgeschlossen) | --- @@ -184,10 +185,10 @@ Entfernt Hook-Einträge aus `~/.claude/settings.json`. Konfigurationsdateien in - Eigene Richtlinien in JavaScript schreiben + Schreibe eigene Richtlinien in JavaScript - + Sitzungen überwachen und Richtlinienaktivitäten einsehen diff --git a/docs/de/introduction.mdx b/docs/de/introduction.mdx index dcb78255..c0c06daa 100644 --- a/docs/de/introduction.mdx +++ b/docs/de/introduction.mdx @@ -1,24 +1,24 @@ --- title: "Failproof AI" -description: "FailproofAI stattet KI-Agenten mit 39 eingebauten Fehlerrichtlinien aus, die Schleifen, geheime Datenlecks, destruktive Tool-Aufrufe und mehr bei einer einzigen Installation abfangen." +description: "FailproofAI gibt KI-Agenten 39 integrierte Fehlerrichtlinien, die Schleifen, Secret-Leaks, destruktive Tool-Aufrufe und mehr mit einer einzigen Installation abfangen." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -Hooks und Richtlinien für **KI-Fehlerbehandlung**, **Fehlerbehebung** und **LLM-Zuverlässigkeit**. Halten Sie Ihre KI-Agenten zuverlässig und autonom am Laufen – mit **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI** und dem **Agents SDK**. +Hooks und Richtlinien für **KI-Fehlerbehandlung**, **Fehlerbehebung** und **LLM-Zuverlässigkeit**. Halten Sie Ihre KI-Agenten zuverlässig und autonom am Laufen – für **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, **Hermes** und das **Agents SDK**. -KI-Agenten scheitern auf vorhersehbare Weise. Sie führen destruktive Befehle aus, geben Geheimnisse preis, verlieren den Fokus, stecken in Schleifen fest oder pushen direkt auf main. Ohne Aufsicht eskalieren kleine Fehler zu Ausfällen, geleakten Zugangsdaten und verlorener Arbeit. +KI-Agenten scheitern auf vorhersehbare Weisen. Sie führen destruktive Befehle aus, geben Secrets preis, weichen von ihrer Aufgabe ab, stecken in Schleifen fest oder pushen direkt in den main-Branch. Werden diese Fehler nicht behoben, können kleine Probleme zu Ausfällen, geleakten Zugangsdaten und verlorenem Code führen. -FailproofAI löst dieses Problem mit **Richtlinien**. Diese Regeln klinken sich in jeden Tool-Aufruf des Agenten ein, um **Fehler zu erkennen**, **sie zu beheben** (blockieren, anweisen, bereinigen) und **Sie zu benachrichtigen**, wenn etwas Aufmerksamkeit erfordert. Ein lokales Dashboard ermöglicht es Ihnen, jeden Tool-Aufruf, jeden Agentenfehler und jede Wiederherstellungsaktion im Nachhinein zu überprüfen. +FailproofAI löst dieses Problem mit **Richtlinien**. Diese Regeln haken sich in jeden Agent-Tool-Aufruf ein, um **Fehler zu erkennen**, **zu beheben** (blockieren, anweisen, bereinigen) und **Sie zu benachrichtigen**, wenn etwas Aufmerksamkeit erfordert. Ein lokales Dashboard ermöglicht es Ihnen, jeden Tool-Aufruf, jeden Agentenfehler und jede Wiederherstellungsmaßnahme im Nachhinein zu überprüfen. -Es verlassen keine Daten Ihren Rechner. +Keine Daten verlassen Ihren Computer. ## Erste Schritte - - Destruktive Befehle blockieren, das Durchsickern von Geheimnissen verhindern, Agenten innerhalb der Projektgrenzen halten und vieles mehr. Alles sofort einsatzbereit. + + Destruktive Befehle blockieren, Secret-Leaks verhindern, Agenten innerhalb der Projektgrenzen halten und mehr. Alles direkt einsatzbereit. @@ -26,7 +26,7 @@ Es verlassen keine Daten Ihren Rechner. - Sehen Sie, was Ihre Agenten in Ihrer Abwesenheit getan haben. Sitzungen durchsuchen, Tool-Aufrufe untersuchen, nachverfolgen, wo Richtlinien ausgelöst wurden. + Sehen Sie, was Ihre Agenten in Ihrer Abwesenheit getan haben. Sitzungen durchsuchen, Tool-Aufrufe untersuchen und überprüfen, wo Richtlinien ausgelöst wurden. @@ -54,4 +54,4 @@ failproofai policies --install # enable policies (or skip — `failproofai` wi failproofai # launch the dashboard ``` -Die vollständige Anleitung finden Sie im [Erste-Schritte-Leitfaden](/de/getting-started). \ No newline at end of file +Eine vollständige Anleitung finden Sie im [Erste-Schritte-Leitfaden](/de/getting-started). \ No newline at end of file diff --git a/docs/de/package-aliases.mdx b/docs/de/package-aliases.mdx index 0b5e4bcc..0c779c38 100644 --- a/docs/de/package-aliases.mdx +++ b/docs/de/package-aliases.mdx @@ -1,6 +1,6 @@ --- -title: Paket-Aliase -description: "Registrierte Tippfehler-Schutz-Aliase und wie sie funktionieren" +title: Package-Aliase +description: "Registrierte Aliase zur Typosquatting-Prävention und wie sie funktionieren" icon: copy --- @@ -10,17 +10,17 @@ Das kanonische npm-Paket ist **`failproofai`**: ```bash npm install -g failproofai -# or +# oder bun add -g failproofai ``` --- -## Warum wir die Alias-Namen besitzen +## Warum wir die Aliasnamen besitzen -Typosquatting ist ein verbreiteter Supply-Chain-Angriff, bei dem ein böswilliger Akteur einen Paketnamen registriert, der sich nur um einen Tastendruck von einem bekannten Paket unterscheidet. Unvorsichtige Nutzer, die den Installationsbefehl falsch eintippen, führen dadurch angreifergesteuerten Code mit vollem Systemzugriff aus – genau die Art von Bedrohung, gegen die Failproof AI entwickelt wurde. +Typosquatting ist ein verbreiteter Angriff auf die Software-Lieferkette, bei dem ein böswilliger Akteur einen Paketnamen registriert, der sich nur um einen Tastendruck vom Original unterscheidet. Ahnungslose Nutzer, die beim Installationsbefehl einen Tippfehler machen, führen dadurch Code unter der Kontrolle des Angreifers mit vollem Systemzugriff aus – genau die Art von Bedrohung, gegen die Failproof AI entwickelt wurde. -Um diese Angriffsfläche zu eliminieren, **besitzen wir präventiv alle gängigen Schreibfehler und Formatierungsvarianten** von `failproofai` auf npm. Keiner dieser Namen kann von Dritten registriert werden. Jeder davon ist ein einfacher Proxy, der das eigentliche `failproofai`-Paket installiert und an dieses delegiert. +Um diese Angriffsfläche zu beseitigen, **registrieren wir vorbeugend alle gängigen Schreibvarianten und Formatierungsvarianten** von `failproofai` auf npm. Keiner dieser Namen kann von Dritten registriert werden. Jeder ist ein schlanker Proxy, der das echte `failproofai`-Paket installiert und an dieses delegiert. --- @@ -31,37 +31,37 @@ Um diese Angriffsfläche zu eliminieren, **besitzen wir präventiv alle gängige | Paket | Status | |-------|--------| | `failproof` | ✅ Veröffentlicht | -| `failproof-ai` | ⏳ npm-Freigabe ausstehend | -| `fail-proof-ai` | ⏳ npm-Freigabe ausstehend | -| `failproof_ai` | ⏳ npm-Freigabe ausstehend | -| `fail_proof_ai` | ⏳ npm-Freigabe ausstehend | -| `fail-proofai` | ⏳ npm-Freigabe ausstehend | +| `failproof-ai` | ⏳ Ausstehend (npm-Freigabe) | +| `fail-proof-ai` | ⏳ Ausstehend (npm-Freigabe) | +| `failproof_ai` | ⏳ Ausstehend (npm-Freigabe) | +| `fail_proof_ai` | ⏳ Ausstehend (npm-Freigabe) | +| `fail-proofai` | ⏳ Ausstehend (npm-Freigabe) | -**`failprof*`-Tippfehler** – fehlendes `o` in „proof": +**`failprof*`-Tippfehler** – fehlendes „o" in „proof": | Paket | Status | |-------|--------| | `failprof` | ✅ Veröffentlicht | | `failprof-ai` | ✅ Veröffentlicht | -| `failprofai` | ⏳ npm-Freigabe ausstehend | -| `fail-prof-ai` | ⏳ npm-Freigabe ausstehend | -| `failprof_ai` | ⏳ npm-Freigabe ausstehend | +| `failprofai` | ⏳ Ausstehend (npm-Freigabe) | +| `fail-prof-ai` | ⏳ Ausstehend (npm-Freigabe) | +| `failprof_ai` | ⏳ Ausstehend (npm-Freigabe) | -**`faliproof*`-Tippfehler** – vertauschte Buchstaben `a` und `i`: +**`faliproof*`-Tippfehler** – vertauschtes „a" und „i": | Paket | Status | |-------|--------| | `faliproof` | ✅ Veröffentlicht | | `faliproof-ai` | ✅ Veröffentlicht | -| `faliproofai` | ⏳ npm-Freigabe ausstehend | +| `faliproofai` | ⏳ Ausstehend (npm-Freigabe) | -> **Warum ausstehend?** Die Spam-Schutzrichtlinie von npm blockiert Namen, die nach dem Entfernen von Satzzeichen und nach Ähnlichkeitsprüfungen auf denselben String wie ein bestehendes Paket normalisiert werden. Wir haben den npm-Support kontaktiert, um diese Namen für Anti-Squatting-Zwecke zu reservieren. Sie werden nach Genehmigung freigeschaltet. +> **Warum ausstehend?** Die Spam-Prävention von npm blockiert Namen, die nach dem Entfernen von Satzzeichen und Ähnlichkeitsprüfungen auf denselben String wie ein bestehendes Paket normalisiert werden. Wir haben den npm-Support kontaktiert, um diese Namen für Anti-Squatting-Zwecke zu reservieren. Sie werden nach Genehmigung freigeschaltet. Sie können überprüfen, ob ein veröffentlichter Alias uns gehört: ```bash npm info failproof -# Look for: "ExosphereHost Inc." in the maintainers field +# Suchen Sie nach: "ExosphereHost Inc." im Feld maintainers ``` --- @@ -70,13 +70,13 @@ npm info failproof Jedes Alias-Paket: -1. Listet `failproofai` als Abhängigkeit – sodass das eigentliche Paket (einschließlich seiner `postinstall`-Hook-Einrichtung) bei der Installation ausgeführt wird -2. Stellt eine ausführbare Datei bereit, die dem eigenen Namen entspricht (z. B. `failprof-ai`) und alle Argumente an das `failproofai`-Binary weiterleitet +1. Listet `failproofai` als Abhängigkeit auf – damit wird das echte Paket (einschließlich der `postinstall`-Hook-Einrichtung) bei der Installation ausgeführt +2. Stellt eine ausführbare Datei bereit, die dem eigenen Namen entspricht (z. B. `failprof-ai`) und alle Argumente an die `failproofai`-Binärdatei weiterleitet -Der Proxy ist ein zweizeiliges Node-Skript; es gibt keine Logik, keine Netzwerkaufrufe und keine Datenerfassung über das hinaus, was `failproofai` selbst tut. +Der Proxy ist ein zweizeiliges Node-Skript; es enthält keine Logik, keine Netzwerkaufrufe und keine Datenerfassung über das hinaus, was `failproofai` selbst tut. --- -## Falls Sie einen Namen finden, den wir übersehen haben +## Falls Sie einen fehlenden Namen entdecken -Öffnen Sie ein Issue unter [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) und wir werden ihn registrieren. \ No newline at end of file +Öffnen Sie ein Issue unter [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) und wir registrieren ihn. \ No newline at end of file diff --git a/docs/de/testing.mdx b/docs/de/testing.mdx index 77f312d5..3b55000e 100644 --- a/docs/de/testing.mdx +++ b/docs/de/testing.mdx @@ -1,10 +1,10 @@ --- -title: Tests -description: "Unit-Tests, E2E-Tests und Test-Hilfsmittel" +title: Testen +description: "Unit-Tests, E2E-Tests und Test-Hilfsfunktionen" icon: flask-vial --- -failproofai verfügt über zwei Test-Suites: **Unit-Tests** (schnell, gemockt) und **End-to-End-Tests** (echte Subprozessaufrufe). +failproofai verfügt über zwei Test-Suites: **Unit-Tests** (schnell, gemockt) und **End-to-End-Tests** (echte Subprocess-Aufrufe). --- @@ -17,13 +17,13 @@ bun run test:run # Unit-Tests im Watch-Modus ausführen bun run test -# E2E-Tests ausführen (erfordert Einrichtung – siehe unten) +# E2E-Tests ausführen (erfordert Setup – siehe unten) bun run test:e2e # Typprüfung ohne Build bunx tsc --noEmit -# Linting +# Lint bun run lint ``` @@ -37,14 +37,14 @@ Unit-Tests befinden sich in `__tests__/` und verwenden [Vitest](https://vitest.d __tests__/ hooks/ builtin-policies.test.ts # Policy-Logik für jede eingebaute Policy - hooks-config.test.ts # Konfigurationsladen und Scope-Zusammenführung - policy-evaluator.test.ts # Parameter-Injektion und Auswertungsreihenfolge - custom-hooks-registry.test.ts # globalThis registry add/get/clear - custom-hooks-loader.test.ts # ESM loader, transitive imports, error handling - manager.test.ts # install/remove/list operations + hooks-config.test.ts # Config-Laden und Scope-Zusammenführung + policy-evaluator.test.ts # Parameter-Injection und Auswertungsreihenfolge + custom-hooks-registry.test.ts # globalThis-Registry add/get/clear + custom-hooks-loader.test.ts # ESM-Loader, transitive Imports, Fehlerbehandlung + manager.test.ts # install/remove/list-Operationen components/ - sessions-list.test.tsx # Session-Listen-Komponente - project-list.test.tsx # Projektlisten-Komponente + sessions-list.test.tsx # Session-Listenkomponente + project-list.test.tsx # Projektlistenkomponente ... lib/ logger.test.ts @@ -110,11 +110,11 @@ describe("block-sudo", () => { ## End-to-End-Tests -E2E-Tests rufen das echte `failproofai`-Binary als Subprozess auf, leiten eine JSON-Nutzlast an stdin weiter und prüfen die stdout-Ausgabe sowie den Exit-Code. Damit wird der vollständige Integrationspfad getestet, den Claude Code verwendet. +E2E-Tests rufen das echte `failproofai`-Binary als Subprocess auf, leiten eine JSON-Nutzlast an stdin weiter und prüfen die stdout-Ausgabe sowie den Exit-Code. Damit wird der vollständige Integrationspfad getestet, den Claude Code verwendet. -### Einrichtung +### Setup -E2E-Tests führen das Binary direkt aus dem Repository-Quellcode aus. Vor dem ersten Durchlauf muss das CJS-Bundle erstellt werden, das benutzerdefinierte Hook-Dateien verwenden, wenn sie aus `'failproofai'` importieren: +E2E-Tests führen das Binary direkt aus dem Repository-Quellcode aus. Vor dem ersten Durchlauf muss das CJS-Bundle gebaut werden, das Custom-Hook-Dateien verwenden, wenn sie aus `'failproofai'` importieren: ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -133,26 +133,26 @@ bun run test:e2e ```text __tests__/e2e/ helpers/ - hook-runner.ts # Binary starten, Nutzlast-JSON weiterleiten, Exit-Code + stdout + stderr erfassen - fixture-env.ts # Pro Test isolierte temporäre Verzeichnisse mit Konfigurationsdateien - payloads.ts # Claude-konforme Nutzlast-Factories für jeden Event-Typ + hook-runner.ts # Binary starten, Payload-JSON einleiten, Exit-Code + stdout + stderr erfassen + fixture-env.ts # Pro-Test isolierte temporäre Verzeichnisse mit Konfigurationsdateien + payloads.ts # Claude-genaue Payload-Factories für jeden Event-Typ hooks/ - builtin-policies.e2e.test.ts # Jede eingebaute Policy mit echtem Subprozess - custom-hooks.e2e.test.ts # Laden und Auswerten benutzerdefinierter Hooks - config-scopes.e2e.test.ts # Konfigurationszusammenführung über project/local/global - policy-params.e2e.test.ts # Parameter-Injektion für jede parametrisierte Policy + builtin-policies.e2e.test.ts # Jede eingebaute Policy mit echtem Subprocess + custom-hooks.e2e.test.ts # Laden und Auswertung von Custom Hooks + config-scopes.e2e.test.ts # Config-Zusammenführung über project/local/global + policy-params.e2e.test.ts # Parameter-Injection für jede parametrisierte Policy ``` -### Die E2E-Hilfsmittel verwenden +### Die E2E-Hilfsfunktionen verwenden -**`FixtureEnv`** – isolierte Umgebung pro Test: +**`FixtureEnv`** – isolierte Testumgebung pro Test: ```typescript import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); // env.cwd - temporäres Verzeichnis; als payload.cwd übergeben, um .failproofai/policies-config.json zu laden -// env.home - isoliertes Home-Verzeichnis; kein echtes ~/.failproofai wird eingelesen +// env.home - isoliertes Home-Verzeichnis; kein echtes ~/.failproofai wird eingeschleust env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** – vorgefertigte Nutzlast-Factories: +**`Payloads`** – vorgefertigte Payload-Factories: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -226,7 +226,7 @@ describe("block-rm-rf (E2E)", () => { ); expect(result.exitCode).toBe(0); - expect(result.stdout).toBe(""); // allow → leerer stdout + expect(result.stdout).toBe(""); // allow → leeres stdout }); }); ``` @@ -234,27 +234,27 @@ describe("block-rm-rf (E2E)", () => { ### E2E-Antwortformate | Entscheidung | Exit-Code | stdout | -|----------|-----------|--------| +|--------------|-----------|--------| | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | | Instruct (kein Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop instruct | `2` | leerer stdout; Begründung in stderr | -| Allow | `0` | leere Zeichenkette | +| Stop instruct | `2` | leeres stdout; Grund in stderr | +| Allow | `0` | leerer String | ### Vitest-Konfiguration E2E-Tests verwenden `vitest.config.e2e.mts` mit: - `environment: "node"` – keine Browser-Globals erforderlich -- `pool: "forks"` – echte Prozessisolierung (Tests starten Subprozesse) +- `pool: "forks"` – echte Prozessisolierung (Tests starten Subprocesse) - `testTimeout: 20_000` – 20 Sekunden pro Test (Binary-Start + Hook-Auswertung) -Der `forks`-Pool ist wichtig: Thread-basierte Worker teilen sich `globalThis`, was Konflikte mit Tests verursachen kann, die Subprozesse starten. Prozessbasierte Forks vermeiden dieses Problem. +Der `forks`-Pool ist wichtig: Thread-basierte Workers teilen sich `globalThis`, was bei Tests, die Subprocesse starten, zu Konflikten führen kann. Prozessbasierte Forks vermeiden dies. --- ## CI -Der vollständige CI-Durchlauf (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) muss vor dem Mergen erfolgreich abgeschlossen werden. Die E2E-Suite läuft als separater CI-Job parallel dazu. +Der vollständige CI-Durchlauf (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) muss bestanden werden, bevor ein Merge möglich ist. Die E2E-Suite läuft als separater CI-Job parallel dazu. -Siehe [Contributing](../CONTRIBUTING.md) für die vollständige Checkliste vor dem Mergen. \ No newline at end of file +Siehe [Contributing](../CONTRIBUTING.md) für die vollständige Prüfliste vor dem Merge. \ No newline at end of file diff --git a/docs/es/architecture.mdx b/docs/es/architecture.mdx index e724fc93..70ae702b 100644 --- a/docs/es/architecture.mdx +++ b/docs/es/architecture.mdx @@ -4,7 +4,7 @@ description: "Cómo funcionan internamente el manejador de hooks, la carga de co icon: sitemap --- -Este documento explica cómo funciona failproofai internamente: cómo el sistema de hooks intercepta las llamadas a herramientas del agente, cómo se carga y combina la configuración, cómo se evalúan las políticas y cómo el dashboard monitorea la actividad del agente. +Este documento explica cómo funciona failproofai internamente: cómo el sistema de hooks intercepta las llamadas a herramientas del agente, cómo se carga y fusiona la configuración, cómo se evalúan las políticas y cómo el panel de control monitorea la actividad del agente. --- @@ -13,9 +13,9 @@ Este documento explica cómo funciona failproofai internamente: cómo el sistema failproofai tiene dos subsistemas independientes: 1. **Manejador de hooks** - Un subproceso CLI rápido que Claude Code invoca en cada llamada a herramienta del agente. Evalúa las políticas y devuelve una decisión. -2. **Monitor de agentes (Dashboard)** - Una aplicación web Next.js para monitorear sesiones de agentes y gestionar políticas. +2. **Monitor de agentes (Panel de control)** - Una aplicación web Next.js para monitorear sesiones del agente y gestionar políticas. -Ambos subsistemas comparten archivos de configuración en `~/.failproofai/` y en el directorio `.failproofai/` del proyecto, pero se ejecutan como procesos separados y se comunican únicamente a través del sistema de archivos. +Ambos subsistemas comparten archivos de configuración en `~/.failproofai/` y el directorio `.failproofai/` del proyecto, pero se ejecutan como procesos separados y se comunican únicamente a través del sistema de archivos. --- @@ -44,7 +44,7 @@ Cuando ejecutas `failproofai policies --install`, escribe entradas como esta en } ``` -Claude Code luego invoca `failproofai --hook PreToolUse` como subproceso antes de cada llamada a herramienta, pasando un payload JSON en stdin. +Claude Code entonces invoca `failproofai --hook PreToolUse` como subproceso antes de cada llamada a herramienta, pasando un payload JSON por stdin. ### Formato del payload @@ -60,13 +60,13 @@ Claude Code luego invoca `failproofai --hook PreToolUse` como subproceso antes d } ``` -Para los eventos `PostToolUse`, el payload también contiene `tool_result` con la salida de la herramienta. +Para eventos `PostToolUse`, el payload también contiene `tool_result` con la salida de la herramienta. El manejador impone un límite de 1 MB en stdin. Los payloads que superen este límite se descartan y todas las políticas permiten implícitamente. ### Formato de respuesta -**Deny (PreToolUse):** +**Denegar (PreToolUse):** ```json { "hookSpecificOutput": { @@ -76,7 +76,7 @@ El manejador impone un límite de 1 MB en stdin. Los payloads que superen este l } ``` -**Deny (PostToolUse):** +**Denegar (PostToolUse):** ```json { "hookSpecificOutput": { @@ -85,7 +85,7 @@ El manejador impone un límite de 1 MB en stdin. Los payloads que superen este l } ``` -**Instruct (cualquier evento excepto Stop):** +**Instruir (cualquier evento excepto Stop):** ```json { "hookSpecificOutput": { @@ -94,15 +94,15 @@ El manejador impone un límite de 1 MB en stdin. Los payloads que superen este l } ``` -**Instruct en evento Stop:** +**Instruir en evento Stop:** - Código de salida: `2` - El motivo se escribe en stderr (no en stdout) -**Allow:** +**Permitir:** - Código de salida: `0` - stdout vacío -**Allow con mensaje:** +**Permitir con mensaje:** `allow(message)` permite que una política envíe contexto informativo de vuelta a Claude incluso cuando la operación está permitida. El manejador de hooks escribe el siguiente JSON en **stdout** (no en un archivo de configuración — esta es la respuesta del manejador a Claude Code, igual que las respuestas de deny e instruct anteriores): @@ -115,7 +115,7 @@ El manejador impone un límite de 1 MB en stdin. Los payloads que superen este l } ``` - Código de salida: `0` (la operación está permitida) -- Cuando múltiples políticas devuelven `allow` con un mensaje, sus mensajes se unen con saltos de línea en una sola cadena `additionalContext` +- Cuando varias políticas devuelven `allow` con un mensaje, sus mensajes se unen con saltos de línea en una única cadena `additionalContext` - Si ninguna política proporciona un mensaje, stdout está vacío (igual que antes) ### Pipeline de procesamiento @@ -124,9 +124,9 @@ El manejador impone un límite de 1 MB en stdin. Los payloads que superen este l ```text stdin JSON - → analizar payload (máx. 1 MB) + → parsear payload (máx. 1 MB) → extraer metadatos de sesión (session_id, cwd, tool_name, tool_input, etc.) - → readMergedHooksConfig(cwd) ← combina config del proyecto + local + global + → readMergedHooksConfig(cwd) ← fusiona configuración de proyecto + local + global → registrar políticas integradas habilitadas con parámetros resueltos → cargar políticas personalizadas desde customPoliciesPath (si está definido) → registrar políticas personalizadas en el registro de políticas @@ -139,27 +139,27 @@ stdin JSON → salir ``` -Todo el proceso se ejecuta en menos de 100 ms para payloads típicos, sin llamadas a LLM. +Todo el proceso se ejecuta en menos de 100ms para payloads típicos sin llamadas a LLM. --- ## Carga de configuración -`src/hooks/hooks-config.ts` implementa la carga de configuración en tres ámbitos. +`src/hooks/hooks-config.ts` implementa la carga de configuración en tres alcances. ```text [1] {cwd}/.failproofai/policies-config.json ← proyecto (mayor prioridad) [2] {cwd}/.failproofai/policies-config.local.json ← local -[3] ~/.failproofai/policies-config.json ← global (menor prioridad) +[3] ~/.failproofai/policies-config.json ← global (menor prioridad) ``` -Lógica de combinación: +Lógica de fusión: - `enabledPolicies` - unión deduplicada de los tres archivos -- `policyParams` - por clave de política, gana completamente el primer archivo que la defina -- `customPoliciesPath` - gana el primer archivo que lo defina -- `llm` - gana el primer archivo que lo defina +- `policyParams` - por clave de política, gana completamente el primer archivo que la define +- `customPoliciesPath` - gana el primer archivo que la define +- `llm` - gana el primer archivo que lo define -El dashboard web usa `readHooksConfig()` (solo global) para leer y escribir, ya que no se invoca con un cwd de proyecto. +El panel de control web utiliza `readHooksConfig()` (solo global) para leer y escribir, ya que no se invoca con un cwd de proyecto. --- @@ -170,14 +170,14 @@ El dashboard web usa `readHooksConfig()` (solo global) para leer y escribir, ya Para cada política: 1. Buscar el esquema `params` de la política (si tiene uno). -2. Leer `policyParams[policy.name]` desde la configuración combinada. -3. Combinar los valores proporcionados por el usuario sobre los valores predeterminados del esquema para producir `ctx.params`. +2. Leer `policyParams[policy.name]` de la configuración fusionada. +3. Combinar los valores proporcionados por el usuario sobre los valores por defecto del esquema para producir `ctx.params`. 4. Llamar a `policy.fn(ctx)` con el contexto resuelto. 5. Si el resultado es `deny`, detener inmediatamente y devolver esa decisión. 6. Si el resultado es `instruct`, acumular el mensaje y continuar. 7. Si el resultado es `allow`, continuar con la siguiente política. -Después de que se ejecuten todas las políticas: +Después de ejecutar todas las políticas: - Si se devolvió algún `deny`, emitir la respuesta de denegación. - Si se recopilaron respuestas `instruct`, emitir una única respuesta instruct con todos los mensajes unidos. - En caso contrario, emitir una respuesta allow (stdout vacío, salida 0). @@ -204,9 +204,9 @@ interface BuiltinPolicyDefinition { } ``` -Las políticas que aceptan `params` declaran un `PolicyParamsSchema` con tipos y valores predeterminados para cada parámetro. El evaluador de políticas inyecta los valores resueltos en `ctx.params` antes de llamar a `fn`. Las funciones de política leen `ctx.params` sin necesidad de verificar nulos, porque los valores predeterminados siempre se aplican primero. +Las políticas que aceptan `params` declaran un `PolicyParamsSchema` con tipos y valores por defecto para cada parámetro. El evaluador de políticas inyecta los valores resueltos en `ctx.params` antes de llamar a `fn`. Las funciones de política leen `ctx.params` sin comprobaciones de nulidad porque los valores por defecto siempre se aplican primero. -La coincidencia de patrones dentro de las políticas usa tokens de comando analizados (argv), no comparación de cadenas sin procesar. Esto evita la evasión mediante inyección de operadores de shell (por ejemplo, un patrón para `sudo systemctl status *` no puede ser eludido agregando `; rm -rf /` al comando). +La coincidencia de patrones dentro de las políticas utiliza tokens de comando parseados (argv), no coincidencia de cadenas sin procesar. Esto evita que se omitan mediante inyección de operadores de shell (por ejemplo, un patrón para `sudo systemctl status *` no puede ser evadido añadiendo `; rm -rf /` al comando). --- @@ -227,8 +227,8 @@ export function clearCustomHooks(): void { ... } // used in tests `src/hooks/custom-hooks-loader.ts` carga el archivo de políticas del usuario: -1. Leer `customPoliciesPath` desde la configuración; omitir si está ausente. -2. Resolver a ruta absoluta; verificar que el archivo existe. +1. Leer `customPoliciesPath` de la configuración; omitir si no está presente. +2. Resolver a ruta absoluta; comprobar que el archivo existe. 3. Reescribir todas las importaciones `from "failproofai"` a la ruta dist real para que `customPolicies` resuelva al mismo registro `globalThis`. 4. Reescribir recursivamente las importaciones locales transitivas para garantizar compatibilidad con ESM. 5. Escribir archivos `.mjs` temporales e importar el archivo de entrada con `import()`. @@ -237,13 +237,13 @@ export function clearCustomHooks(): void { ... } // used in tests Ante cualquier error (archivo no encontrado, error de sintaxis, fallo de importación), el error se registra en `~/.failproofai/hook.log` y el cargador devuelve un array vacío. Las políticas integradas no se ven afectadas. -Las políticas personalizadas se evalúan después de todas las políticas integradas. Un `deny` de una política personalizada sigue cortocircuitando las políticas personalizadas restantes (pero todas las integradas ya se habrán ejecutado en ese punto). +Las políticas personalizadas se evalúan después de todas las políticas integradas. Un `deny` de una política personalizada sigue cortocircuitando las políticas personalizadas posteriores (pero en ese punto todos los integrados ya se han ejecutado). --- ## Registro de actividad -Después de cada evento de hook, el manejador agrega una línea JSONL a `~/.failproofai/hook-activity.jsonl`: +Después de cada evento de hook, el manejador añade una línea JSONL a `~/.failproofai/hook-activity.jsonl`: ```json { @@ -262,18 +262,18 @@ Una línea por política que tomó una decisión distinta de allow. Las decision --- -## Arquitectura del dashboard +## Arquitectura del panel de control -El dashboard es una aplicación **Next.js 16** que utiliza App Router con React Server Components y Server Actions. +El panel de control es una aplicación **Next.js 16** que utiliza el App Router con React Server Components y Server Actions. ```text app/ layout.tsx ← Layout raíz (tema, telemetría, navegación) - projects/page.tsx ← Componente servidor: listar todos los proyectos Claude - project/[name]/page.tsx ← Componente servidor: listar sesiones en un proyecto + projects/page.tsx ← Componente de servidor: lista todos los proyectos de Claude + project/[name]/page.tsx ← Componente de servidor: lista sesiones de un proyecto project/[name]/session/ - [sessionId]/page.tsx ← Componente servidor: renderizar visor de sesión - policies/page.tsx ← Componente cliente: gestión de políticas + registro de actividad + [sessionId]/page.tsx ← Componente de servidor: renderiza el visor de sesión + policies/page.tsx ← Componente de cliente: gestión de políticas + registro de actividad actions/ get-hooks-config.ts ← Leer configuración + lista de políticas update-hooks-config.ts ← Activar/desactivar política @@ -281,21 +281,21 @@ app/ get-hook-activity.ts ← Paginar/buscar en el registro de actividad install-hooks-web.ts ← Instalar/eliminar hooks desde el navegador api/ - download/[project]/[session]/route.ts ← Exportación de sesión CLI (JSONL o JSON) + download/[project]/[session]/route.ts ← Exportación de sesión por CLI (JSONL o JSON) ``` **Flujo de datos:** -- Los componentes de página llaman a `lib/projects.ts` y `lib/log-entries.ts` para leer datos de proyectos/sesiones directamente desde el sistema de archivos (sin capa API para lecturas). -- La página de políticas usa Server Actions para todas las mutaciones (activar/desactivar, actualizar parámetros, instalar/eliminar). -- El visor de sesión analiza el formato de transcripción JSONL de Claude y renderiza una línea de tiempo de mensajes y llamadas a herramientas. +- Los componentes de página llaman a `lib/projects.ts` y `lib/log-entries.ts` para leer datos de proyectos/sesiones directamente desde el sistema de archivos (sin capa API para las lecturas). +- La página de políticas utiliza Server Actions para todas las mutaciones (activar/desactivar, actualizar parámetros, instalar/eliminar). +- El visor de sesión parsea el formato de transcripción JSONL de Claude y renderiza una línea de tiempo de mensajes y llamadas a herramientas. **Decisiones de diseño clave:** - Sin base de datos: todo el estado persistente está en archivos planos (`~/.failproofai/`, `~/.claude/projects/`). - Server Actions para mutaciones: no se necesita API REST para operaciones CRUD. - React Server Components para páginas de lectura: carga inicial más rápida, sin bundle de cliente para la obtención de datos. -- Componentes cliente solo donde se necesita interactividad (toggles de políticas, búsqueda de actividad, visor de logs). +- Componentes de cliente solo donde se necesita interactividad (toggles de políticas, búsqueda de actividad, visor de logs). --- @@ -311,22 +311,22 @@ failproofai/ │ ├── policy-evaluator.ts # Motor de ejecución de políticas │ ├── policy-registry.ts # Registro y búsqueda de políticas │ ├── policy-types.ts # Interfaces TypeScript -│ ├── hooks-config.ts # Carga de configuración multi-ámbito +│ ├── hooks-config.ts # Carga de configuración multi-alcance │ ├── custom-hooks-registry.ts # Registro de hooks respaldado por globalThis │ ├── custom-hooks-loader.ts # Cargador ESM para hooks JS del usuario -│ ├── manager.ts # Operaciones de instalación / eliminación / listado +│ ├── manager.ts # Operaciones de instalar / eliminar / listar │ ├── install-prompt.ts # Prompt interactivo de selección de políticas │ ├── hook-logger.ts # Registro en hook.log │ ├── hook-activity-store.ts # Persistir actividad en hook-activity.jsonl -│ └── llm-client.ts # Cliente API LLM (para políticas potenciadas por IA) -├── app/ # Dashboard Next.js (páginas + server actions) +│ └── llm-client.ts # Cliente de API LLM (para políticas con IA) +├── app/ # Panel de control Next.js (páginas + server actions) ├── lib/ # Utilidades compartidas -│ ├── projects.ts # Enumerar proyectos Claude desde el sistema de archivos -│ ├── log-entries.ts # Analizar formato JSONL de transcripción Claude +│ ├── projects.ts # Enumerar proyectos de Claude desde el sistema de archivos +│ ├── log-entries.ts # Parsear el formato de transcripción JSONL de Claude │ ├── paths.ts # Resolver rutas del sistema │ └── ... -├── components/ # Componentes React UI compartidos +├── components/ # Componentes de UI React compartidos ├── contexts/ # Proveedores de contexto React (tema, auto-refresco, telemetría) ├── examples/ # Archivos de hooks personalizados de ejemplo -└── __tests__/ # Pruebas unitarias y E2E +└── __tests__/ # Tests unitarios y E2E ``` \ No newline at end of file diff --git a/docs/es/built-in-policies.mdx b/docs/es/built-in-policies.mdx index f8f8daa4..5644f1c6 100644 --- a/docs/es/built-in-policies.mdx +++ b/docs/es/built-in-policies.mdx @@ -1,10 +1,10 @@ --- -title: Políticas integradas -description: "Las 39 políticas integradas que detectan los modos de fallo más comunes en agentes" +title: Políticas Integradas +description: "Las 39 políticas integradas que detectan los fallos más comunes de los agentes" icon: shield --- -failproofai incluye 39 políticas integradas que detectan los modos de fallo más comunes en agentes. Cada política se activa en un tipo de evento de hook específico y en una herramienta determinada. Diecinueve políticas aceptan parámetros que permiten ajustar su comportamiento sin escribir código. Cinco políticas de flujo de trabajo exigen un pipeline de commit → push → PR → CI antes de que Claude se detenga. +failproofai incluye 39 políticas integradas que detectan los fallos más comunes de los agentes. Cada política se activa en un tipo de evento de hook específico y en un nombre de herramienta determinado. Diecinueve políticas aceptan parámetros que permiten ajustar su comportamiento sin necesidad de escribir código. Cinco políticas de flujo de trabajo imponen una cadena commit → push → PR → CI antes de que Claude se detenga. --- @@ -26,14 +26,18 @@ Las políticas están agrupadas en categorías: | [Flujo de trabajo](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | - **`block-`** — impide que el agente continúe. -- **`warn-`** — proporciona contexto adicional al agente para que pueda corregirse. -- **`sanitize-`** — elimina datos sensibles de la salida de la herramienta antes de que el agente la vea. +- **`warn-`** — proporciona al agente contexto adicional para que pueda corregirse. +- **`sanitize-`** — elimina datos sensibles del resultado de la herramienta antes de que el agente lo vea. ### Espacios de nombres -Cada política reside en un slot `/`. Las políticas integradas pertenecen al espacio de nombres **`failproofai/`** — por ejemplo, `failproofai/sanitize-jwt`. El espacio de nombres evita colisiones cuando también se cargan políticas personalizadas o de terceros con nombres cortos similares. +Cada política reside en un espacio `/`. Las políticas integradas pertenecen al +espacio de nombres **`failproofai/`** — por ejemplo, `failproofai/sanitize-jwt`. El +espacio de nombres evita colisiones cuando también se cargan políticas personalizadas o de terceros +con nombres cortos similares. -En la configuración puedes referirte a una política integrada por su nombre corto o su nombre completo; ambas formas resuelven a la misma política: +En la configuración puedes referirte a una política integrada por su nombre corto o su +nombre calificado; ambas formas apuntan a la misma política: ```json { @@ -44,7 +48,9 @@ En la configuración puedes referirte a una política integrada por su nombre co } ``` -Si un nombre no contiene `/`, failproofai lo trata como perteneciente al espacio de nombres predeterminado `failproofai`. Los nombres que ya contienen `/` (p. ej. `myorg/foo`, `custom/my-hook`) se mantienen tal cual. +Si un nombre no contiene `/`, failproofai lo trata como perteneciente al espacio de nombres +predeterminado `failproofai`. Los nombres que ya contienen `/` (p. ej. `myorg/foo`, +`custom/my-hook`) se mantienen tal cual. - **`require-`** — bloquea el evento Stop hasta que se cumplan las condiciones. --- @@ -57,20 +63,20 @@ Todas las políticas admiten un campo opcional `hint` en `policyParams`. El hint ## Comandos peligrosos -Impide que los agentes ejecuten operaciones difíciles de deshacer o que podrían dañar el sistema anfitrión. +Evita que los agentes ejecuten operaciones difíciles de deshacer o que puedan dañar el sistema anfitrión. ### `block-sudo` **Evento:** PreToolUse (Bash) **Comportamiento por defecto:** Deniega cualquier comando `sudo`. -Bloquea invocaciones que incluyan la palabra clave `sudo`. La coincidencia de patrones se realiza sobre tokens de comando analizados, no sobre la cadena sin procesar, para evitar elusión mediante inyección de operadores de shell. +Bloquea invocaciones que incluyen la palabra clave `sudo`. La coincidencia de patrones se realiza sobre los tokens del comando analizado, no sobre la cadena en bruto, para evitar bypass mediante inyección de operadores de shell. **Parámetros:** | Parámetro | Tipo | Valor por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comando exactos que están permitidos. Cada entrada se compara con los tokens argv analizados. | +| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos exactos que están permitidos. Cada entrada se compara contra los tokens argv analizados. | **Ejemplo:** @@ -84,10 +90,10 @@ Bloquea invocaciones que incluyan la palabra clave `sudo`. La coincidencia de pa } ``` -Con esta configuración, `sudo systemctl status nginx` está permitido, pero `sudo rm /etc/hosts` es denegado. +Con esta configuración, `sudo systemctl status nginx` está permitido, pero `sudo rm /etc/hosts` se deniega. -Los patrones se comparan con los tokens analizados, no con la cadena de comando sin procesar. Esto previene la elusión mediante operadores de shell añadidos (p. ej. `sudo systemctl status x; rm -rf /` no coincide con `sudo systemctl status *`). +Los patrones se comparan contra tokens analizados, no contra la cadena de comando en bruto. Esto evita bypass mediante operadores de shell añadidos (p. ej. `sudo systemctl status x; rm -rf /` no coincide con `sudo systemctl status *`). --- @@ -101,7 +107,7 @@ Los patrones se comparan con los tokens analizados, no con la cadena de comando | Parámetro | Tipo | Valor por defecto | Descripción | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Rutas que es seguro eliminar de forma recursiva (p. ej. `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Rutas que pueden eliminarse de forma recursiva de manera segura (p. ej. `/tmp`). | **Ejemplo:** @@ -129,7 +135,7 @@ Sin parámetros. ### `block-failproofai-commands` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Deniega comandos que desinstalarían o desactivarían failproofai (p. ej. `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Comportamiento por defecto:** Deniega comandos que desinstalarían o deshabilitarían failproofai (p. ej. `npm uninstall failproofai`, `failproofai policies --uninstall`). Sin parámetros. @@ -137,9 +143,9 @@ Sin parámetros. ## Comandos de infraestructura -Impide que los agentes de programación ejecuten CLIs de infraestructura o activen pipelines de CI/CD. Todas las políticas de esta categoría son **opt-in** (`defaultEnabled: false`) — los agentes que legítimamente necesiten llamar a `kubectl`, `terraform`, etc. no se verán interrumpidos a menos que habilites la política. Cuando está habilitada, cualquier invocación de la CLI correspondiente es denegada a menos que el comando coincida con una entrada en `allowPatterns`. +Impide que los agentes de código ejecuten CLIs de infraestructura o activen pipelines de CI/CD. Todas las políticas de esta categoría están **desactivadas por defecto** (`defaultEnabled: false`) — los agentes que legítimamente necesiten llamar a `kubectl`, `terraform`, etc. no se verán afectados a menos que habilites la política. Cuando está habilitada, cualquier invocación del CLI correspondiente se deniega a menos que el comando coincida con una entrada en `allowPatterns`. -La gramática de patrones es la misma que en [`block-sudo`](#block-sudo): los tokens se comparan con argv analizado, `*` es un comodín para un token, y cualquier comando que contenga un operador de shell independiente (`&&`, `||`, `|`, `;`) o un token con metacaracteres de shell embebidos es rechazado antes de la comprobación de la lista de permitidos para prevenir inyecciones. +La gramática de patrones es la misma que en [`block-sudo`](#block-sudo): los tokens se comparan contra argv analizado, `*` es un comodín para un token, y cualquier comando que contenga un operador de shell independiente (`&&`, `||`, `|`, `;`) o un token con metacaracteres de shell incrustados se rechaza antes de la comprobación de la lista de permitidos para evitar bypass por inyección. ### `block-kubectl` @@ -150,7 +156,7 @@ La gramática de patrones es la misma que en [`block-sudo`](#block-sudo): los to | Parámetro | Tipo | Valor por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos kubectl que están permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos kubectl permitidos. | **Ejemplo:** @@ -164,7 +170,7 @@ La gramática de patrones es la misma que en [`block-sudo`](#block-sudo): los to } ``` -Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply -f deploy.yaml` es denegado. +Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply -f deploy.yaml` se deniega. --- @@ -177,7 +183,7 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply | Parámetro | Tipo | Valor por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos terraform/tofu que están permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos terraform/tofu permitidos. | **Ejemplo:** @@ -196,13 +202,13 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply ### `block-aws-cli` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Deniega cualquier invocación de la CLI `aws`. +**Comportamiento por defecto:** Deniega cualquier invocación del CLI `aws`. **Parámetros:** | Parámetro | Tipo | Valor por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos de la CLI aws que están permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos del CLI aws permitidos. | **Ejemplo:** @@ -221,13 +227,13 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply ### `block-gcloud` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Deniega cualquier invocación de la CLI `gcloud` (Google Cloud). +**Comportamiento por defecto:** Deniega cualquier invocación del CLI `gcloud` (Google Cloud). **Parámetros:** | Parámetro | Tipo | Valor por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos gcloud que están permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos gcloud permitidos. | **Ejemplo:** @@ -246,13 +252,13 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply ### `block-az-cli` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Deniega cualquier invocación de la CLI `az` (Azure). +**Comportamiento por defecto:** Deniega cualquier invocación del CLI `az` (Azure). **Parámetros:** | Parámetro | Tipo | Valor por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos de la CLI az que están permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos del CLI az permitidos. | **Ejemplo:** @@ -277,7 +283,7 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply | Parámetro | Tipo | Valor por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos helm que están permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos helm permitidos. | **Ejemplo:** @@ -296,7 +302,7 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply ### `block-gh-pipeline` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Deniega los siguientes subcomandos de la CLI `gh` que mutan estado o activan pipelines: +**Comportamiento por defecto:** Deniega los siguientes subcomandos del CLI `gh` que modifican estado o activan pipelines: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -305,13 +311,13 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply - `gh cache delete` - `gh secret set`, `gh secret delete` -Los subcomandos de `gh` de solo lectura como `gh pr view`, `gh pr list`, `gh run list`, `gh release view` y `gh api repos/.../...` **no** son interceptados por esta política — son necesarios habitualmente para comprobaciones de flujo de trabajo (incluida la propia `require-ci-green-before-stop` de failproofai). +Los subcomandos de solo lectura de `gh` como `gh pr view`, `gh pr list`, `gh run list`, `gh release view` y `gh api repos/.../...` **no** son interceptados por esta política — son habitualmente necesarios para verificaciones de flujo de trabajo (incluido el propio `require-ci-green-before-stop` de failproofai). **Parámetros:** | Parámetro | Tipo | Valor por defecto | Descripción | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Invocaciones específicas programadas que se permiten aunque de otro modo serían denegadas. | +| `allowPatterns` | `string[]` | `[]` | Invocaciones específicas permitidas aunque normalmente serían denegadas. | **Ejemplo:** @@ -329,7 +335,7 @@ Los subcomandos de `gh` de solo lectura como `gh pr view`, `gh pr list`, `gh run ## Secretos (sanitizadores) -Impide que los agentes filtren credenciales a su contexto o salida. Las políticas sanitizadoras se activan en eventos **PostToolUse**. Cuando Claude ejecuta un comando Bash, lee un archivo o llama a cualquier herramienta, estas políticas inspeccionan la salida antes de que sea devuelta a Claude. Si se detecta un patrón de secreto, la política devuelve una decisión de denegación que impide que la salida sea devuelta. +Evita que los agentes filtren credenciales en su contexto o salida. Las políticas sanitizadoras se activan en eventos **PostToolUse**. Cuando Claude ejecuta un comando Bash, lee un archivo o llama a cualquier herramienta, estas políticas inspeccionan la salida antes de devolvérsela a Claude. Si se detecta un patrón de secreto, la política devuelve una decisión de deny que impide que la salida sea retornada. ### `sanitize-jwt` @@ -343,7 +349,7 @@ Sin parámetros. ### `sanitize-api-keys` **Evento:** PostToolUse (todas las herramientas) -**Comportamiento por defecto:** Redacta formatos comunes de claves API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), claves de acceso AWS (`AKIA`), claves Stripe (`sk_live_`, `sk_test_`) y claves de Google API (`AIza`). +**Comportamiento por defecto:** Redacta formatos comunes de claves de API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), claves de acceso AWS (`AKIA`), claves Stripe (`sk_live_`, `sk_test_`) y claves de Google API (`AIza`). **Parámetros:** @@ -371,7 +377,7 @@ Sin parámetros. ### `sanitize-connection-strings` **Evento:** PostToolUse (todas las herramientas) -**Comportamiento por defecto:** Redacta cadenas de conexión de bases de datos que contienen credenciales embebidas (p. ej. `postgresql://user:password@host/db`). +**Comportamiento por defecto:** Redacta cadenas de conexión a bases de datos que contienen credenciales incrustadas (p. ej. `postgresql://user:password@host/db`). Sin parámetros. @@ -397,14 +403,14 @@ Sin parámetros. ## Entorno -Protege la configuración de entorno sensible para que los agentes no puedan leerla ni exponerla. +Protege la configuración sensible del entorno para que los agentes no puedan leerla ni exponerla. ### `block-env-files` **Evento:** PreToolUse (Bash, Read) **Comportamiento por defecto:** Deniega la lectura de archivos `.env` mediante `cat .env`, llamadas a la herramienta `Read` con `.env` como ruta de archivo, etc. -No bloquea `.envrc` ni otros archivos relacionados con el entorno: solo archivos con el nombre exacto `.env`. +No bloquea `.envrc` ni otros archivos relacionados con el entorno — solo archivos cuyo nombre exacto sea `.env`. Sin parámetros. @@ -426,7 +432,7 @@ Mantiene a los agentes dentro de los límites del proyecto y alejados de archivo ### `block-read-outside-cwd` **Evento:** PreToolUse (Read, Bash) -**Comportamiento por defecto:** Deniega la lectura de archivos fuera del directorio raíz del proyecto. El límite es `CLAUDE_PROJECT_DIR` (establecido una vez por sesión por Claude Code), con un fallback al directorio de trabajo actual de la sesión cuando esa variable no está definida. Usar la raíz del proyecto en lugar del `cwd` activo garantiza que el límite sea estable incluso después de que Claude haga `cd` a un subdirectorio. +**Comportamiento por defecto:** Deniega la lectura de archivos fuera de la raíz del proyecto. El límite es `CLAUDE_PROJECT_DIR` (establecido una vez por sesión por Claude Code), con un fallback al directorio de trabajo actual de la sesión cuando esa variable no está definida. Usar la raíz del proyecto en lugar del `cwd` activo significa que el límite se mantiene estable incluso después de que Claude haga `cd` a un subdirectorio. **Parámetros:** @@ -451,13 +457,13 @@ Mantiene a los agentes dentro de los límites del proyecto y alejados de archivo ### `block-secrets-write` **Evento:** PreToolUse (Write, Edit) -**Comportamiento por defecto:** Deniega escrituras en archivos habitualmente usados para claves privadas y certificados: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Comportamiento por defecto:** Deniega escrituras en archivos comúnmente utilizados para claves privadas y certificados: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Parámetros:** | Parámetro | Tipo | Valor por defecto | Descripción | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | Patrones de nombre de archivo adicionales (estilo glob) que bloquear. | +| `additionalPatterns` | `string[]` | `[]` | Patrones de nombre de archivo adicionales (estilo glob) a bloquear. | **Ejemplo:** @@ -475,7 +481,7 @@ Mantiene a los agentes dentro de los límites del proyecto y alejados de archivo ## Git -Evita pushes accidentales, force-pushes y errores de rama difíciles de deshacer. +Previene pushes accidentales, force-pushes y errores de rama que son difíciles de deshacer. ### `block-push-master` @@ -501,7 +507,7 @@ Evita pushes accidentales, force-pushes y errores de rama difíciles de deshacer ``` -Para permitir el push a todas las ramas (deshabilitando efectivamente esta política sin eliminarla de `enabledPolicies`), establece `protectedBranches: []`. +Para permitir push a todas las ramas (deshabilitando efectivamente esta política sin eliminarla de `enabledPolicies`), establece `protectedBranches: []`. --- @@ -509,7 +515,7 @@ Para permitir el push a todas las ramas (deshabilitando efectivamente esta polí ### `block-work-on-main` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Deniega `git commit`, `git merge`, `git rebase` y `git cherry-pick` cuando el árbol de trabajo está en `main` o `master`. La creación y el cambio de ramas (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) no se ven afectados. +**Comportamiento por defecto:** Deniega `git commit`, `git merge`, `git rebase` y `git cherry-pick` mientras el árbol de trabajo esté en `main` o `master`. La creación y el cambio de ramas (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) no se ven afectados. **Parámetros:** @@ -524,7 +530,7 @@ Para permitir el push a todas las ramas (deshabilitando efectivamente esta polí **Evento:** PreToolUse (Bash) **Comportamiento por defecto:** Deniega `git push --force` y `git push -f`. -Sin parámetros específicos de política. Usa el [`hint`](/es/configuration#hint-cross-cutting) transversal para sugerir alternativas: +Sin parámetros específicos de política. Usa el campo transversal [`hint`](/es/configuration#hint-cross-cutting) para sugerir alternativas: ```json { @@ -541,7 +547,7 @@ Sin parámetros específicos de política. Usa el [`hint`](/es/configuration#hin ### `warn-git-amend` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Instruye a Claude para que proceda con cuidado al ejecutar `git commit --amend`. No bloquea el comando. +**Comportamiento por defecto:** Instruye a Claude a proceder con cautela al ejecutar `git commit --amend`. No bloquea el comando. Sin parámetros. @@ -550,7 +556,7 @@ Sin parámetros. ### `warn-git-stash-drop` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Instruye a Claude para que confirme antes de ejecutar `git stash drop`. No bloquea el comando. +**Comportamiento por defecto:** Instruye a Claude a confirmar antes de ejecutar `git stash drop`. No bloquea el comando. Sin parámetros. @@ -559,7 +565,7 @@ Sin parámetros. ### `warn-all-files-staged` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Instruye a Claude para que revise qué está añadiendo al stage cuando ejecuta `git add -A` o `git add .`. No bloquea el comando. +**Comportamiento por defecto:** Instruye a Claude a revisar qué está añadiendo al área de stage cuando ejecuta `git add -A` o `git add .`. No bloquea el comando. Sin parámetros. @@ -567,12 +573,12 @@ Sin parámetros. ## Base de datos -Detecta operaciones SQL destructivas antes de que se ejecuten contra tu base de datos. +Intercepta operaciones SQL destructivas antes de que se ejecuten en tu base de datos. ### `warn-destructive-sql` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Instruye a Claude para que confirme antes de ejecutar SQL que contenga `DROP TABLE`, `DROP DATABASE` o `DELETE` sin cláusula `WHERE`. +**Comportamiento por defecto:** Instruye a Claude a confirmar antes de ejecutar SQL que contenga `DROP TABLE`, `DROP DATABASE` o `DELETE` sin cláusula `WHERE`. Sin parámetros. @@ -581,7 +587,7 @@ Sin parámetros. ### `warn-schema-alteration` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Instruye a Claude para que confirme antes de ejecutar sentencias `ALTER TABLE`. +**Comportamiento por defecto:** Instruye a Claude a confirmar antes de ejecutar sentencias `ALTER TABLE`. Sin parámetros. @@ -589,18 +595,18 @@ Sin parámetros. ## Advertencias -Proporciona contexto adicional a los agentes antes de operaciones potencialmente arriesgadas pero no destructivas. +Proporciona a los agentes contexto adicional antes de operaciones potencialmente arriesgadas pero no destructivas. ### `warn-large-file-write` **Evento:** PreToolUse (Write) -**Comportamiento por defecto:** Instruye a Claude para que confirme antes de escribir archivos de más de 1024 KB. +**Comportamiento por defecto:** Instruye a Claude a confirmar antes de escribir archivos de más de 1024 KB. **Parámetros:** | Parámetro | Tipo | Valor por defecto | Descripción | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | Umbral de tamaño de archivo en kilobytes por encima del cual se emite una advertencia. | +| `thresholdKb` | `number` | `1024` | Umbral de tamaño de archivo en kilobytes a partir del cual se emite una advertencia. | **Ejemplo:** @@ -615,7 +621,7 @@ Proporciona contexto adicional a los agentes antes de operaciones potencialmente ``` -El manejador de hooks impone un límite de 1 MB en stdin para los payloads. Para probar esta política con contenido pequeño, establece `thresholdKb` a un valor muy inferior a 1024. +El manejador de hooks impone un límite de 1 MB en stdin para los payloads. Para probar esta política con contenido pequeño, establece `thresholdKb` a un valor muy por debajo de 1024. --- @@ -623,7 +629,7 @@ El manejador de hooks impone un límite de 1 MB en stdin para los payloads. Para ### `warn-package-publish` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Instruye a Claude para que confirme antes de ejecutar `npm publish`. +**Comportamiento por defecto:** Instruye a Claude a confirmar antes de ejecutar `npm publish`. Sin parámetros. @@ -632,7 +638,7 @@ Sin parámetros. ### `warn-background-process` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Instruye a Claude para que sea cuidadoso al lanzar procesos en segundo plano mediante `nohup`, `&`, `disown` o `screen`. +**Comportamiento por defecto:** Instruye a Claude a tener cuidado al lanzar procesos en segundo plano mediante `nohup`, `&`, `disown` o `screen`. Sin parámetros. @@ -641,7 +647,7 @@ Sin parámetros. ### `warn-global-package-install` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Instruye a Claude para que confirme antes de ejecutar `npm install -g`, `yarn global add` o `pip install` sin un entorno virtual. +**Comportamiento por defecto:** Instruye a Claude a confirmar antes de ejecutar `npm install -g`, `yarn global add` o `pip install` sin un entorno virtual. Sin parámetros. @@ -649,21 +655,21 @@ Sin parámetros. ## Gestores de paquetes -Controla qué gestores de paquetes puede usar el agente. +Impone qué gestores de paquetes puede utilizar el agente. ### `prefer-package-manager` **Evento:** PreToolUse (Bash) -**Comportamiento por defecto:** Deshabilitado. Cuando está habilitado, bloquea cualquier comando de gestor de paquetes que no esté en la lista `allowed` e indica a Claude que reescriba el comando usando un gestor permitido. +**Comportamiento por defecto:** Desactivado. Cuando está habilitado, bloquea cualquier comando de gestor de paquetes que no esté en la lista `allowed` e indica a Claude que reescriba el comando usando un gestor permitido. Detecta: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | Parámetro | Tipo | Valor por defecto | Descripción | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | Nombres de gestores de paquetes permitidos. Cualquier gestor detectado que no esté en esta lista es bloqueado. Si está vacío, la política no hace nada. | -| `blocked` | string[] | `[]` | Nombres de gestores adicionales que bloquear más allá de la lista integrada (p. ej. `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | Nombres de gestores de paquetes permitidos. Cualquier gestor detectado que no esté en esta lista será bloqueado. Cuando está vacía, la política no tiene efecto. | +| `blocked` | string[] | `[]` | Nombres de gestores adicionales a bloquear más allá de la lista integrada (p. ej. `['pdm', 'pipx']`). | -La lista de bloqueo integrada incluye: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Usa `blocked` para añadir gestores que no estén en esta lista. +La lista de bloqueo integrada incluye: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Usa `blocked` para añadir gestores que no están en esta lista. **Ejemplo de configuración:** @@ -679,18 +685,18 @@ La lista de bloqueo integrada incluye: pip, pip3, npm, npx, yarn, pnpm, pnpx, bu } ``` -Con esta configuración, tanto `pip install flask` como `pdm install flask` son denegados con un mensaje indicando a Claude que use `uv` o `bun` en su lugar. Comandos como `uv pip install flask` están permitidos porque `uv` está en la lista de permitidos y se comprueba primero. +Con esta configuración, tanto `pip install flask` como `pdm install flask` se deniegan con un mensaje que indica a Claude que use `uv` o `bun` en su lugar. Comandos como `uv pip install flask` están permitidos porque `uv` está en la lista de permitidos y se comprueba primero. --- -## Comportamiento de IA +## Comportamiento de la IA -Detecta cuándo los agentes se bloquean o se comportan de forma inesperada. +Detecta cuándo los agentes se quedan atascados o se comportan de forma inesperada. ### `warn-repeated-tool-calls` **Evento:** PreToolUse (todas las herramientas) -**Comportamiento por defecto:** Instruye a Claude para que reconsidere cuando la misma herramienta es llamada 3 o más veces con parámetros idénticos, lo que es una señal habitual de que el agente está atrapado en un bucle. +**Comportamiento por defecto:** Instruye a Claude a reconsiderar cuando la misma herramienta se llama 3 o más veces con parámetros idénticos — señal habitual de que el agente está atrapado en un bucle. Sin parámetros. @@ -698,34 +704,34 @@ Sin parámetros. ## Flujo de trabajo -Impone un flujo de trabajo disciplinado al final de la sesión. Estas políticas se activan en el evento **Stop** y bloquean al agente para que no se detenga hasta que se cumpla cada condición. Siguen una cadena de dependencias natural: commit → push → PR → CI. Si una política deniega, las políticas posteriores en la cadena se omiten (la denegación produce un cortocircuito). +Impone un flujo de trabajo disciplinado al final de la sesión. Estas políticas se activan en el evento **Stop** y deniegan al agente detenerse hasta que se cumpla cada condición. Siguen una cadena de dependencias natural: commit → push → PR → CI. Si una política deniega, las políticas posteriores en la cadena se omiten (la denegación cortocircuita la cadena). -Todas las políticas de flujo de trabajo son **fail-open**: si la herramienta requerida no está disponible (p. ej. `gh` no instalado, sin remote de git), la política permite con un mensaje informativo explicando por qué se omitió la comprobación. +Todas las políticas de flujo de trabajo son **fail-open**: si la herramienta requerida no está disponible (p. ej. `gh` no está instalado, no hay remote de git), la política permite con un mensaje informativo explicando por qué se omitió la comprobación. ### Semántica de Stop por CLI -La aplicación de Stop se ve ligeramente diferente en los siete CLIs compatibles porque cada uno expone un contrato de hook de "agente terminado" distinto. El **resultado** es el mismo — el agente no puede detenerse mientras una condición de flujo de trabajo no se cumple — pero la **mecánica** difiere. La tabla siguiente resume las diferencias; solo Pi tiene una particularidad visible para el usuario que vale la pena entender antes de habilitar una política `require-*-before-stop`. +La aplicación del Stop se ve ligeramente diferente entre los siete CLIs compatibles porque cada uno expone un contrato de hook distinto para "el agente ha terminado". El **resultado** es el mismo — el agente no puede detenerse mientras una condición de flujo de trabajo esté fallando — pero los **mecanismos** difieren. La tabla a continuación resume esto; solo Pi tiene un comportamiento visible para el usuario que vale la pena entender antes de habilitar una política `require-*-before-stop`. | CLI | Cuándo se activa la condición | Lo que ves | |---|---|---| -| Claude Code | En el mismo bucle del agente, inmediatamente | Claude continúa trabajando — resuelve el problema y luego intenta terminar de nuevo. No hay interrupción visible para ti. | +| Claude Code | En el mismo bucle del agente, inmediatamente | Claude continúa trabajando — soluciona el problema y luego intenta terminar de nuevo. No hay interrupción visible para ti. | | Codex | En el mismo bucle del agente, inmediatamente | Igual que Claude. | | GitHub Copilot CLI | En el mismo bucle del agente, inmediatamente | Igual que Claude (usa el canal de reintento `{decision:"block", reason}` de Copilot — verificado empíricamente contra Copilot CLI 1.0.41). | -| Cursor Agent | En el mismo bucle del agente, inmediatamente | Igual que Claude (usa el canal `{followup_message}` de Cursor — limitado por `loop_limit`, 5 reintentos por defecto). | +| Cursor Agent | En el mismo bucle del agente, inmediatamente | Igual que Claude (usa el canal `{followup_message}` de Cursor — limitado a `loop_limit`, por defecto 5 reintentos). | | Gemini CLI | En el mismo bucle del agente, inmediatamente | Igual que Claude (usa el canal `{decision:"block", reason}` de Gemini en `AfterAgent`). | | OpenCode | En el mismo bucle del agente, inmediatamente | Igual que Claude (usa la llamada SDK `client.session.prompt(...)` de OpenCode enrutada a través de `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **En el siguiente turno del usuario** | **Pi se detiene visiblemente** cuando se activa la condición — su bucle de agente termina y se te devuelve el prompt. La condición se activa la próxima vez que envíes un prompt: failproofai antepone una directiva `MANDATORY ACTION REQUIRED` al system prompt de ese turno, instruyendo al LLM para que complete el paso del flujo de trabajo (commit, push, etc.) antes de hacer lo que pediste. | +| **Pi (pi-coding-agent)** | **En el siguiente turno del usuario** | **Pi se detiene visiblemente** cuando se activa la condición — su bucle de agente termina y se te devuelve el prompt. La condición se activa la próxima vez que envíes un prompt: failproofai antepone una directiva `MANDATORY ACTION REQUIRED` al system prompt de ese turno, instruyendo al LLM a completar el paso del flujo de trabajo (commit, push, etc.) antes de hacer lo que pediste. | -**Limitación de Pi.** El `AgentEndEvent` de Pi (el equivalente upstream del hook `Stop` de Claude) no tiene tipo Result — en el momento en que se activa, el bucle del agente de Pi ya ha terminado. Pi no puede ser forzado a reintentar el mismo bucle como Claude / Copilot / Cursor / Gemini / OpenCode. failproofai desplaza la condición al evento `before_agent_start` de Pi (que se activa después del siguiente prompt del usuario) para que la comprobación del flujo de trabajo siga aplicándose, solo en el siguiente turno en lugar del actual. +**Limitación de Pi.** El `AgentEndEvent` de Pi (el equivalente upstream del hook `Stop` de Claude) no tiene tipo Result — para cuando se activa, el bucle del agente de Pi ya ha terminado. Pi no puede ser forzado a reintentar el mismo bucle como Claude / Copilot / Cursor / Gemini / OpenCode. failproofai traslada la condición al evento `before_agent_start` de Pi (que se activa después del siguiente prompt del usuario) para que la comprobación del flujo de trabajo siga siendo efectiva, solo en el siguiente turno en lugar del actual. -**Qué significa esto en la práctica:** +**Lo que esto significa en la práctica:** -- Después de que Pi se detiene, la razón de denegación se captura en memoria indexada por el id de sesión de Pi. El próximo prompt que envíes en el mismo proceso de Pi la consume: el LLM ve la directiva `MANDATORY ACTION REQUIRED` en la parte superior de su system prompt, realiza el commit (o push / abre el PR / espera al CI), y solo entonces continúa con tu solicitud. La razón de denegación capturada es de un solo uso — una vez consumida, la condición queda libre. -- La condición está limitada por la vida útil del proceso de Pi. Si haces `Ctrl+C` a Pi o sales entre turnos, la entrada en memoria se elimina junto con el proceso y la condición se pierde. Claude, Copilot, Cursor, Gemini y OpenCode tienen el mismo límite (terminar el agente hace que se pierda la condición) — Pi simplemente lo hace más visible porque el agente termina visiblemente antes de que la condición se active. -- Una denegación pendiente también se elimina en `session_shutdown` por cualquier razón (`new` / `resume` / `fork` / `quit`), por lo que una condición obsoleta de una sesión anterior no puede filtrarse a una nueva sesión iniciada en el mismo proceso de Pi. +- Después de que Pi se detenga, el motivo de la denegación se captura en memoria indexado por el id de sesión de Pi. El siguiente prompt que envíes en el mismo proceso de Pi lo drena: el LLM ve la directiva `MANDATORY ACTION REQUIRED` al inicio de su system prompt, hace el commit (o push / abre el PR / espera a CI), y solo entonces continúa con tu solicitud. El motivo de denegación capturado es de un solo uso — una vez drenado, la condición queda libre. +- La condición está limitada por el tiempo de vida del proceso de Pi. Si haces `Ctrl+C` en Pi o sales entre turnos, la entrada en memoria se descarta junto con el proceso y la condición se pierde. Claude, Copilot, Cursor, Gemini y OpenCode tienen el mismo límite (matar el agente hace que se pierda la condición) — Pi simplemente lo hace más visible porque el agente termina visiblemente antes de que se active la condición. +- Una denegación pendiente también se limpia en `session_shutdown` por cualquier motivo (`new` / `resume` / `fork` / `quit`), de modo que una condición obsoleta de una sesión anterior no puede filtrarse a una sesión nueva iniciada en el mismo proceso de Pi. -Si necesitas el reintento en el mismo bucle al estilo de Claude, ejecuta tus políticas `Stop` bajo cualquiera de los otros seis CLIs compatibles. Estamos monitorizando Pi upstream por un futuro tipo Result en `AgentEndEvent` que nos permitiría cerrar esta brecha. +Si necesitas el reintento en el mismo bucle al estilo Claude, ejecuta tus políticas de `Stop` bajo cualquiera de los otros seis CLIs compatibles. Estamos siguiendo Pi upstream para un futuro tipo Result en `AgentEndEvent` que nos permitiría cerrar esta brecha. ### `require-commit-before-stop` @@ -740,7 +746,7 @@ Sin parámetros. ### `require-push-before-stop` **Evento:** Stop -**Comportamiento por defecto:** Deniega la detención cuando hay commits sin enviar o cuando la rama actual no tiene rama de seguimiento remota. Sugiere `git push -u` para crear una rama de seguimiento si es necesario. Falla abierto si no hay remote configurado. +**Comportamiento por defecto:** Deniega la detención cuando hay commits sin subir o cuando la rama actual no tiene una rama de seguimiento remota. Sugiere `git push -u` para crear una rama de seguimiento si es necesario. Falla de forma abierta si no hay remote configurado. **Parámetros:** @@ -765,13 +771,14 @@ Sin parámetros. ### `require-pr-before-stop` **Evento:** Stop -**Comportamiento por defecto:** Deniega la detención cuando no existe ninguna pull request para la rama actual, o cuando la PR existente está cerrada sin fusionar. Instruye a Claude para crear una PR con `gh pr create`. Cuando la PR está **fusionada**, la política permite (el trabajo se ha enviado) y el mensaje sugiere cambiar de rama (`git checkout main && git pull`). +**Comportamiento por defecto:** Deniega la detención cuando no existe un pull request para la rama actual, o cuando el PR existente está cerrado sin haberse fusionado. Instruye a Claude a crear un PR con `gh pr create`. Cuando el PR está **fusionado**, la política lo permite (el trabajo está publicado) y el mensaje sugiere cambiar de la rama (`git checkout main && git pull`). Sin parámetros. -Esta política requiere [GitHub CLI](https://cli.github.com/) (`gh`) instalado y autenticado. -Ejecuta `gh auth login` con un token de acceso personal que tenga ámbito `repo` para acceso de lectura a pull requests. Si `gh` no está instalado o no está autenticado, la política falla abierto e informa la razón a Claude. +Esta política requiere que el [CLI de GitHub](https://cli.github.com/) (`gh`) esté instalado y autenticado. +Ejecuta `gh auth login` con un token de acceso personal que tenga el scope `repo` para acceso de lectura a +pull requests. Si `gh` no está instalado o no está autenticado, la política falla de forma abierta e informa del motivo a Claude. --- @@ -779,12 +786,12 @@ Ejecuta `gh auth login` con un token de acceso personal que tenga ámbito `repo` ### `require-no-conflicts-before-stop` **Evento:** Stop -**Comportamiento por defecto:** Deniega la detención cuando la rama actual no puede fusionarse limpiamente en la rama base. La política primero confirma que existe una PR `OPEN` en GitHub para la rama — sin una, no hay objetivo de fusión que aplicar, por lo que toda la política produce cortocircuito y permite. Una vez confirmada una PR `OPEN`, se ejecutan dos comprobaciones independientes: +**Comportamiento por defecto:** Deniega la detención cuando la rama actual no puede fusionarse limpiamente con la rama base. La política primero confirma que existe un PR `OPEN` en GitHub para la rama — sin uno, no hay un destino de fusión que aplicar, por lo que toda la política cortocircuita a allow. Una vez confirmado un PR `OPEN`, se ejecutan dos comprobaciones independientes: -1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`. En caso de conflicto, el mensaje de denegación nombra los archivos en conflicto para que Claude sepa exactamente qué resolver. -2. **GitHub** — reutiliza el resultado de `gh pr view --json mergeable,state` ya obtenido en la precomprobación. Detecta conflictos que un `origin/` local desactualizado pasaría por alto (p. ej. alguien aterrizó una PR conflictiva en `main` desde la última actualización). Un resultado `CONFLICTING` deniega. Un resultado `UNKNOWN` también deniega e instruye a Claude para que espere ~10 segundos y vuelva a comprobar antes de intentar detenerse de nuevo — esto previene falsos negativos mientras GitHub recalcula. +1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`. En caso de conflicto, el mensaje de denegación nombra los archivos conflictivos para que Claude sepa exactamente qué resolver. +2. **GitHub** — reutiliza el resultado de `gh pr view --json mergeable,state` ya obtenido en la precomprobación. Detecta conflictos que un `origin/` local obsoleto podría pasar por alto (p. ej. alguien fusionó un PR conflictivo en `main` desde el último fetch). Un resultado `CONFLICTING` deniega. Un resultado `UNKNOWN` también deniega e instruye a Claude a esperar ~10 segundos y volver a comprobar antes de intentar detenerse de nuevo — esto previene falsos negativos mientras GitHub recalcula. -Se omite completamente (permite) cuando: `gh` no está instalado, no existe PR para la rama, el estado de la PR no es `OPEN` (p. ej. `MERGED`, `CLOSED`), o `gh pr view` devuelve una salida no analizable. También falla abierto cuando `origin/` no existe localmente o cuando no hay commits por delante de la base — esos fallbacks de Capa 1 aún consultan la fusionabilidad de la PR en caché antes de permitir. +Se omite completamente (permite) cuando: `gh` no está instalado, no existe PR para la rama, el estado del PR no es `OPEN` (p. ej. `MERGED`, `CLOSED`), o `gh pr view` devuelve una salida no parseable. También falla de forma abierta cuando `origin/` falta localmente o cuando no hay commits por delante de la base — esos fallbacks de Capa 1 aún consultan la fusionabilidad del PR en caché antes de permitir. **Parámetros:** @@ -793,7 +800,10 @@ Se omite completamente (permite) cuando: `gh` no está instalado, no existe PR p | `baseBranch` | `string` | `"main"` | Rama base contra la que comprobar los conflictos. | -GitHub CLI (`gh`) es necesario para esta política. La política usa `gh pr view` para confirmar que existe una PR `OPEN` antes de ejecutar cualquier comprobación de conflictos — sin `gh`, la política produce cortocircuito y permite. Ejecuta `gh auth login` con un token de acceso personal que tenga ámbito `repo` para acceso de lectura a pull requests. +El CLI de GitHub (`gh`) es necesario para esta política. La política usa `gh pr view` para confirmar +que existe un PR `OPEN` antes de ejecutar cualquier comprobación de conflictos — sin `gh`, la política +cortocircuita a allow. Ejecuta `gh auth login` con un token de acceso personal que tenga el scope `repo` +para acceso de lectura a pull requests. --- @@ -801,22 +811,23 @@ GitHub CLI (`gh`) es necesario para esta política. La política usa `gh pr view ### `require-ci-green-before-stop` **Evento:** Stop -**Comportamiento por defecto:** Deniega la detención cuando las comprobaciones de CI están fallando o aún en ejecución en la rama actual. Comprueba tanto las ejecuciones de flujo de trabajo de GitHub Actions como las comprobaciones de bots de terceros (p. ej. CodeRabbit, SonarCloud, Codecov). Trata las conclusiones `skipped`, `cancelled` y `neutral` como no fallidas (este último cubre p. ej. alertas de Socket Security en PRs de colaboradores externos, donde la aplicación intencionalmente reporta neutral en lugar de éxito/fallo). Devuelve un mensaje informativo cuando todas las comprobaciones pasan. +**Comportamiento por defecto:** Deniega la detención cuando las comprobaciones de CI están fallando o aún en ejecución en la rama actual. Comprueba tanto los workflow runs de GitHub Actions como las comprobaciones de bots de terceros (p. ej. CodeRabbit, SonarCloud, Codecov). Trata las conclusiones `skipped`, `cancelled` y `neutral` como no fallidas (esta última cubre, por ejemplo, alertas de Socket Security en PRs de colaboradores externos, donde la aplicación intencionalmente reporta neutral en lugar de success/failure). Devuelve un mensaje informativo cuando todas las comprobaciones pasan. Sin parámetros. -Esta política requiere [GitHub CLI](https://cli.github.com/) (`gh`) instalado y autenticado. -Ejecuta `gh auth login` con un token de acceso personal que tenga ámbito `repo` para acceso de lectura a ejecuciones de flujo de trabajo de Actions y la API de Checks. Si `gh` no está instalado o no está autenticado, la política falla abierto e informa la razón a Claude. +Esta política requiere que el [CLI de GitHub](https://cli.github.com/) (`gh`) esté instalado y autenticado. +Ejecuta `gh auth login` con un token de acceso personal que tenga el scope `repo` para acceso de lectura a +workflow runs de Actions y la API de Checks. Si `gh` no está instalado o no está autenticado, la política falla de forma abierta e informa del motivo a Claude. --- --- -## Deshabilitar políticas individuales +## Desactivar políticas individuales -Elimina una política específica de `enabledPolicies` en tu configuración, o desactívala en la pestaña Policies del panel de control. +Elimina una política específica de `enabledPolicies` en tu configuración, o desactívala desde la pestaña Policies del dashboard. ```json { @@ -827,4 +838,4 @@ Elimina una política específica de `enabledPolicies` en tu configuración, o d } ``` -Las políticas que no aparezcan en `enabledPolicies` no se ejecutan, aunque existan entradas en `policyParams` para ellas. \ No newline at end of file +Las políticas que no aparecen en `enabledPolicies` no se ejecutan, aunque existan entradas para ellas en `policyParams`. \ No newline at end of file diff --git a/docs/es/cli/audit.mdx b/docs/es/cli/audit.mdx index db80aa99..0694d437 100644 --- a/docs/es/cli/audit.mdx +++ b/docs/es/cli/audit.mdx @@ -1,27 +1,24 @@ --- -title: Auditar sesiones anteriores (beta) -description: "Cuenta con qué frecuencia el agente realizó acciones innecesarias o arriesgadas en transcripciones pasadas" +title: Auditar sesiones pasadas (beta) +description: "Cuenta con qué frecuencia el agente hizo cosas innecesarias o arriesgadas en transcripciones anteriores" --- - **Función beta.** La auditoría se lanza como beta mientras recopilamos - comentarios iniciales. El catálogo de detectores y el formato del informe - pueden cambiar antes del próximo corte estable. Por favor, abre un issue si - algo no parece correcto. + **Función beta.** La auditoría se lanza en versión beta mientras recopilamos comentarios iniciales. + El catálogo de detectores y el formato del informe pueden cambiar antes del próximo corte estable. + Por favor, abre un issue si algo parece incorrecto. -La auditoría reproduce tus transcripciones pasadas del agente-CLI a través del -motor de políticas de failproofai y genera un informe visual y compartible en -la **página del panel `/audit`** — el arquetipo de tu agente, una puntuación -de 0 a 100, y exactamente qué políticas habrían detectado qué. +La auditoría reproduce tus transcripciones pasadas del agente CLI a través del motor de políticas de failproofai +y genera un informe visual y compartible en la **página del panel `/audit`** — el arquetipo de tu agente, una puntuación del 0 al 100, y exactamente qué políticas habrían detectado qué. -## Ejecución +## Ejecutarla -Tres formas de acceder — todas llevan al mismo informe `/audit`. +Tres formas de iniciarla — todas llevan al mismo informe `/audit`. -```bash npx (no install) +```bash npx (sin instalación) npx -y failproofai audit ``` @@ -29,7 +26,7 @@ npx -y failproofai audit failproofai audit ``` -```bash failproofai (dashboard) +```bash failproofai (panel) failproofai ``` @@ -37,61 +34,60 @@ failproofai - `npx -y failproofai audit` descarga failproofai, ejecuta el análisis y abre - el panel por ti — no necesitas instalar nada antes. + `npx -y failproofai audit` descarga failproofai, ejecuta el análisis y abre el + panel automáticamente — sin necesidad de instalar nada antes. `failproofai audit` ejecuta el análisis en tu terminal y luego abre - `localhost:8020/audit` automáticamente al finalizar. + `localhost:8020/audit` automáticamente al terminar. - Ejecuta `failproofai` y haz clic en **Audit** en la barra de navegación - (entre Policies y Projects), o abre `/audit` directamente. + Ejecuta `failproofai` y haz clic en **Audit** en la barra de navegación (entre Policies y + Projects), o abre `/audit` directamente. - Ejecuta `failproofai audit -h` (o `--help`) para ver el uso. La auditoría - funciona **completamente sin conexión** — no requiere cuenta ni red — y el - panel continúa sirviéndose hasta que lo detengas con `Ctrl+C`. + Ejecuta `failproofai audit -h` (o `--help`) para ver el uso. La auditoría funciona **completamente + sin conexión** — no requiere cuenta ni red — y el panel sigue activo hasta que lo detengas con `Ctrl+C`. -El panel analiza las transcripciones pasadas del agente CLI en esta máquina (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) e informa con qué frecuencia el agente realizó acciones que failproofai está diseñado para detener — comprobaciones de variables de entorno, push forzados, prefijos redundantes `cd `, bucles de sondeo con sleep, re-lectura de archivos recién editados, y más. +El panel analiza las transcripciones pasadas del agente CLI en esta máquina (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) e informa con qué frecuencia el agente hizo cosas que failproofai está diseñado para detener — comprobaciones de variables de entorno, push forzados, prefijos `cd ` redundantes, bucles de sleep-polling, releer archivos recién editados y más. -Por cada transcripción, cada evento de uso de herramienta se reproduce a través de las 39 políticas integradas **y** a través de 8 detectores exclusivos de auditoría que identifican patrones que aún no están cubiertos por las políticas en tiempo de ejecución. Los recuentos se agregan por política / detector en todas las sesiones. +Por cada transcripción, cada evento de uso de herramienta se reproduce a través de las 39 políticas integradas **y** a través de 8 detectores exclusivos de auditoría que capturan patrones que aún no están cubiertos por las políticas en tiempo real. Los recuentos se agregan por política / detector en todas las sesiones. ## Qué obtienes -La página `/audit` es un **póster** de una sola pantalla y compartible, seguido de cuatro secciones debajo del pliegue: +La página `/audit` es un **póster** de pantalla única y compartible seguido de cuatro secciones debajo del pliegue: -1. **Póster** — la identidad de tu agente de un vistazo: su **arquetipo** (uno de 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), sus palabras clave de personalidad, qué tan raro es ese arquetipo, y una **puntuación de 0 a 100** con una banda de nivel (de `S` hasta `bottom tier`). Diseñado para compartir — publícalo en X o LinkedIn, o descárgalo como PNG. -2. **`// strengths`** — lo que tu agente ya hace bien, con números reales del análisis (ej. porcentaje de llamadas a herramientas limpias, `0` intentos de push a main), mostrado solo cuando la política relevante tiene un historial limpio. -3. **`// quirks`** — lo que se escapó: una tabla ordenada de comportamientos que failproofai habría detectado — *cuándo* ocurrió por última vez, *qué se escapó* (y la política integrada que lo habría bloqueado), su *gravedad*, y con qué frecuencia se *vio* (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — la lista de correcciones recomendadas: una fila por política con un `failproofai policy add ` listo para copiar y pegar, más un botón **instalar todo** que habilita todas las recomendaciones a la vez y muestra tu **puntuación proyectada** si lo hicieras. -5. **`// come back better`** — construye el hábito: establece un **recordatorio** de reauditoría por correo electrónico (`3d` / `7d` / `14d` / `30d`) o reaudita ahora, e **invita a un amigo** a ejecutar su propia auditoría (enviado desde failproof.ai, con copia a ti). Los recordatorios e invitaciones requieren inicio de sesión — ver [`failproofai auth`](/es/cli/auth). +1. **Póster** — la identidad de tu agente de un vistazo: su **arquetipo** (uno de 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), sus palabras clave de persona, cuán raro es ese arquetipo y una **puntuación del 0 al 100** con una banda de nivel (`S` hasta `bottom tier`). Diseñado para compartir — publícalo en X o LinkedIn, o descárgalo como PNG. +2. **`// strengths`** — lo que tu agente ya hace bien, con números reales del análisis (p. ej., % de llamadas a herramientas limpias, `0` intentos de push a main), mostrado solo donde la política relevante tiene un historial limpio. +3. **`// quirks`** — lo que se escapó: una tabla ordenada de comportamientos que failproofai habría detectado — *cuándo* ocurrió por última vez, *qué se escapó* (y el integrado que lo habría bloqueado), su *severidad* y con qué frecuencia fue *visto* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — la lista de correcciones recomendadas: una fila por política con un `failproofai policy add ` listo para copiar y pegar, más un botón **install all** que habilita todas las recomendaciones a la vez y muestra tu **puntuación proyectada** si lo hicieras. +5. **`// come back better`** — construye el hábito: configura un **recordatorio** por correo electrónico para volver a auditar (`3d` / `7d` / `14d` / `30d`) o vuelve a auditar ahora, e **invita a un amigo** a ejecutar su propia auditoría (enviado desde failproof.ai, con copia a ti). Los recordatorios e invitaciones requieren inicio de sesión — consulta [`failproofai auth`](/es/cli/auth). ## Detectores exclusivos de auditoría -Estos detectan patrones de comportamiento ineficiente que no están (todavía) aplicados en tiempo real. Solo se ejecutan durante la auditoría y nunca bloquean una llamada a herramienta en vivo. +Estos detectan patrones de "comportamiento ineficiente" que aún no se aplican en tiempo real. Solo se ejecutan durante la auditoría y nunca bloquean una llamada a herramienta en vivo. | Detector | Qué cuenta | |---|---| -| `redundant-cd-cwd` | Comandos Bash que comienzan con `cd && …` aunque los comandos ya se ejecuten en `cwd`. | -| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` sobre un único archivo fuente — usa la herramienta `Read`. | +| `redundant-cd-cwd` | Comandos Bash que comienzan con `cd && …` aunque los comandos ya se ejecutan en `cwd`. | +| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` en un único archivo fuente — usa la herramienta `Read`. | | `prefer-edit-over-sed-awk` | Ediciones en sitio con `sed -i` / `awk … > file` — usa la herramienta `Edit`. | -| `prefer-write-over-heredoc` | Escritura de archivos con heredoc / `echo > file` multilínea — usa la herramienta `Write`. | -| `sleep-polling-loop` | `sleep N` largo (≥ 30s) o bucles de sondeo `while …; sleep …; done`. | -| `find-from-root` | `find /`, `find /home`, `find /usr`, etc. — limita el alcance a `cwd`. | +| `prefer-write-over-heredoc` | Heredoc / `echo > file` multilínea para escribir archivos — usa la herramienta `Write`. | +| `sleep-polling-loop` | `sleep N` largo (≥ 30s) o bucles de polling `while …; sleep …; done`. | +| `find-from-root` | `find /`, `find /home`, `find /usr`, etc. — delimita el alcance a `cwd`. | | `git-commit-no-verify` | `git commit … --no-verify` / `-n`, omitiendo los hooks. | -| `reread-after-edit` | `Read` de un archivo que acaba de ser editado con `Edit`/`Write` en la misma sesión. | +| `reread-after-edit` | `Read` de un archivo que acaba de ser modificado con `Edit`/`Write` en la misma sesión. | ## Cachés -- **Caché por transcripción** en `~/.failproofai/cache/audit/.json` con clave `(mtime, size, engineVersion, detectorVersion)` — se invalida automáticamente cuando la transcripción o el código de política/detector cambia. Cada entrada también almacena una marca de tiempo `cachedAt` como **metadatos TTL** (no forma parte de la clave de caché); las entradas con más de **7 días** de antigüedad se rechazan al leer para que los resultados de larga duración no sobrevivan a la evolución de la lógica de los detectores. -- **Caché de resultado completo** en `~/.failproofai/audit-dashboard.json` (modo 0600). Permite que el panel se renderice instantáneamente al navegar sin volver a ejecutar el análisis. También se rechaza al leer pasado el **TTL de 7 días** — `/audit` entonces cae a su estado vacío y solicita una nueva ejecución. Haz clic en `[ re-audit now ]` cerca de la parte inferior del informe para actualizar — la reauditoría envía `noCache: true`, por lo que omite la caché por transcripción y vuelve a analizar cada transcripción en lugar de devolver el resultado en caché; la ejecución transmite el progreso mediante una barra adhesiva en la parte superior y reemplaza el resultado en su lugar al completarse correctamente (sin recarga de página; una reauditoría fallida conserva el informe anterior). +- **Caché por transcripción** en `~/.failproofai/cache/audit/.json` indexada por `(mtime, size, engineVersion, detectorVersion)` — se invalida automáticamente cuando cambia la transcripción o el código de políticas/detectores. Cada entrada también almacena una marca de tiempo `cachedAt` como **metadatos TTL** (no forma parte de la clave de caché); las entradas con más de **7 días** se rechazan en la lectura para que los resultados de larga duración no sobrevivan a la evolución de los detectores. +- **Caché del resultado completo** en `~/.failproofai/audit-dashboard.json` (modo 0600). Permite que el panel se renderice instantáneamente al navegar sin volver a ejecutar el análisis. También se rechaza al leer pasado el **TTL de 7 días** — `/audit` cae entonces a su estado vacío y solicita una nueva ejecución. Haz clic en `[ re-audit now ]` cerca de la parte inferior del informe para actualizar — la re-auditoría envía `noCache: true`, por lo que omite la caché por transcripción y vuelve a analizar cada transcripción en lugar de devolver el resultado en caché; la ejecución transmite el progreso mediante una barra superior fija y reemplaza el resultado al terminar con éxito (sin recarga de página; una re-auditoría fallida conserva el informe anterior). ## Notas -- **Sin mutación.** La auditoría se reproduce en modo de solo lectura. `warn-repeated-tool-calls` se omite porque su archivo auxiliar por sesión se modificaría de lo contrario. -- **Políticas de flujo de trabajo omitidas.** Las políticas `require-*-before-stop` solo se activan en eventos `Stop` y ejecutan `execSync` contra el estado git activo — no tienen una interpretación significativa de tipo "qué habría pasado en 2025", por lo que no aparecen en los recuentos de auditoría. +- **Sin mutaciones.** La auditoría se reproduce en modo de solo lectura. `warn-repeated-tool-calls` se omite porque de lo contrario se modificaría su sidecar por sesión. +- **Políticas de flujo de trabajo omitidas.** Las políticas `require-*-before-stop` solo se activan en eventos `Stop` y ejecutan `execSync` contra el estado git en vivo — no tienen una interpretación significativa de tipo "qué habría pasado en 2025", por lo que no aparecen en los recuentos de auditoría. - **Políticas personalizadas omitidas.** Los hooks personalizados proporcionados por el usuario no se reproducen (pueden haber cambiado desde la sesión original). \ No newline at end of file diff --git a/docs/es/cli/auth.mdx b/docs/es/cli/auth.mdx index d77ce09d..b882a5d5 100644 --- a/docs/es/cli/auth.mdx +++ b/docs/es/cli/auth.mdx @@ -6,12 +6,12 @@ description: "Inicia sesión en FailproofAI desde la CLI para activar recordator ```bash failproofai auth login # email + código de un solo uso failproofai auth logout # revocar esta sesión -failproofai auth whoami # mostrar la identidad del usuario autenticado +failproofai auth whoami # mostrar la identidad de la sesión activa ``` -La forma antigua con las flags `--login` / `--logout` / `--whoami` sigue aceptándose como alias por compatibilidad retroactiva. +La forma antigua con los flags `--login` / `--logout` / `--whoami` sigue siendo aceptada como alias por compatibilidad con versiones anteriores. -La autenticación es opcional. Las políticas, el panel de control, la página `/audit` y todas las demás funciones locales funcionan exactamente igual independientemente de si has iniciado sesión o no. La funcionalidad de inicio de sesión existe para que las características que **necesitan** una identidad estable (recordatorios de re-auditoría hoy, más en el futuro) tengan un punto de anclaje. +La autenticación es opcional. Las políticas, el panel de control, la página `/audit` y todas las demás funciones locales funcionan exactamente igual estés o no conectado. La pantalla de inicio de sesión existe para que las funciones que **necesitan** una identidad estable (recordatorios de re-auditoría hoy, más en el futuro) tengan un punto de anclaje. ## Flujo de inicio de sesión @@ -19,17 +19,17 @@ La autenticación es opcional. Las políticas, el panel de control, la página ` failproofai auth login ``` -Solicita tu email, envía un código de un solo uso de 6 dígitos a esa dirección, pide el código y, si tiene éxito, escribe `~/.failproofai/auth.json` (modo `0600`). La misma sesión queda visible en el panel de control de la aplicación — al hacer clic en `[ set a reminder ]` en `/audit`, el sistema te reconocerá como autenticado. +Solicita tu correo electrónico, envía un código de 6 dígitos de un solo uso a esa dirección, pide el código y, si es correcto, escribe `~/.failproofai/auth.json` (modo `0600`). La misma sesión queda visible en el panel de control de la aplicación: al hacer clic en `[ set a reminder ]` en `/audit`, el sistema te reconocerá como conectado. -El panel de control expone el mismo flujo como un diálogo modal en `/audit` para los usuarios que nunca usan la CLI. +El panel de control ofrece el mismo flujo como un diálogo modal en `/audit` para los usuarios que nunca usan la CLI. -## Cerrar sesión +## Cierre de sesión ```bash failproofai auth logout ``` -Revoca la sesión actual en el servidor y elimina `~/.failproofai/auth.json`. Si el servidor de API no está disponible, el archivo local se elimina de todos modos — la intención local de cerrar sesión siempre prevalece. +Revoca la sesión actual en el servidor y elimina `~/.failproofai/auth.json`. Si el servidor de la API no está disponible, el archivo local se elimina de todas formas: la intención de cerrar sesión localmente siempre tiene prioridad. ## Verificación de identidad @@ -37,11 +37,11 @@ Revoca la sesión actual en el servidor y elimina `~/.failproofai/auth.json`. Si failproofai auth whoami ``` -Muestra ` ()` y termina con código 0 cuando existe una sesión válida, o `not signed in` y termina con código 1 en caso contrario. Renueva silenciosamente el token de acceso en segundo plano si está a menos de un minuto de expirar. +Imprime ` ()` y termina con código 0 cuando existe una sesión válida, o `not signed in` y termina con código 1 en caso contrario. Renueva silenciosamente el token de acceso en segundo plano si está a menos de un minuto de expirar. -## Recordatorio de re-auditoría persistente +## Recordatorio persistente de re-auditoría -Cuando haces clic en **`[ set a reminder ]`** en la página `/audit` (o inicias sesión a través del modal que activa ese botón), el panel de control escribe un pequeño archivo complementario en `~/.failproofai/next-audit.json`: +Cuando haces clic en **`[ set a reminder ]`** en la página `/audit` (o inicias sesión mediante el modal que activa ese botón), el panel de control escribe un pequeño archivo auxiliar en `~/.failproofai/next-audit.json`: ```json { @@ -51,9 +51,9 @@ Cuando haces clic en **`[ set a reminder ]`** en la página `/audit` (o inicias } ``` -Este archivo está asociado al email con el que se configuró — cambiar la sesión de la CLI a una cuenta diferente oculta cualquier recordatorio que pertenezca al usuario anterior. El desplazamiento predeterminado es de **7 días**, configurable más adelante cuando se implemente el planificador. Se crea con permisos `0600`, igual que `auth.json`. +Este archivo está vinculado al correo con el que se configuró: si cambias la sesión de la CLI a otra cuenta, cualquier recordatorio perteneciente al usuario anterior quedará oculto. El desplazamiento predeterminado es de **7 días**, configurable más adelante cuando se implemente el planificador. Se crea con permisos `0600`, igual que `auth.json`. -El endpoint `/api/auth/reminder` del panel de control expone los métodos `GET` (leer), `POST` (establecer / reprogramar) y `DELETE` (eliminar), y requiere una sesión activa. +El endpoint `/api/auth/reminder` del panel de control expone `GET` (lectura), `POST` (establecer / reprogramar) y `DELETE` (eliminar), y requiere una sesión activa. ## Contenido de `~/.failproofai/auth.json` @@ -67,21 +67,21 @@ El endpoint `/api/auth/reminder` del panel de control expone los métodos `GET` } ``` -Se crea con permisos `0600` (solo lectura/escritura del propietario). El token de acceso es un JWT HS256 con validez de 1 hora; el token de actualización es una cadena aleatoria opaca de 256 bits que el servidor almacena como `SHA-256(token)`. La reutilización del token de actualización se detecta en el servidor y revoca todas las sesiones del usuario. +Se crea con permisos `0600` (solo lectura/escritura del propietario). El token de acceso es un JWT HS256 con validez de 1 hora; el token de actualización es una cadena aleatoria opaca de 256 bits que el servidor almacena como `SHA-256(token)`. La reutilización de tokens de actualización se detecta en el servidor y revoca todas las sesiones del usuario. ## Variables de entorno | Variable | Valor predeterminado | Propósito | |---|---|---| -| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | Reemplaza la URL base del servidor de API. Útil para el desarrollo local contra un servidor de API autohospedado. | +| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | Reemplaza la URL base del servidor de la API. Útil para desarrollo local contra un servidor de API autohospedado. | | `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | Reemplaza la ubicación donde se almacena `auth.json`. Principalmente para pruebas. | Consulta [Variables de entorno](/es/cli/environment-variables) para ver la lista completa. ## Solución de problemas -**"Could not reach the api-server"** — la CLI no puede abrir una conexión TCP a `FAILPROOF_API_URL`. Verifica tu red, o configura `FAILPROOF_API_URL` si estás ejecutando un servidor de API autohospedado. +**"Could not reach the api-server"** — la CLI no puede abrir una conexión TCP con `FAILPROOF_API_URL`. Comprueba tu red o define `FAILPROOF_API_URL` si estás ejecutando un servidor de API autohospedado. -**"Rate limited"** — demasiados intentos de inicio de sesión en una ventana de 15 minutos para ese email (5/email) o IP (20/IP), o un período de espera de 30 segundos para reenviar tras la solicitud anterior del mismo email. El mensaje de error incluye el tiempo de espera antes de reintentar, expresado en segundos. +**"Rate limited"** — demasiados intentos de inicio de sesión en una ventana de 15 minutos para ese correo (5/correo) o IP (20/IP), o un período de espera de 30 segundos para reenviar después de la solicitud anterior para el mismo correo. El mensaje de error incluye el tiempo de espera en segundos. -**Código rechazado** — el OTP era incorrecto, había expirado o la entrada alcanzó su bloqueo por 5 intentos fallidos. Ejecuta `failproofai auth login` de nuevo para solicitar un código nuevo. \ No newline at end of file +**Código rechazado** — el OTP era incorrecto, había expirado o la entrada alcanzó el bloqueo tras 5 intentos fallidos. Ejecuta `failproofai auth login` de nuevo para solicitar un nuevo código. \ No newline at end of file diff --git a/docs/es/cli/dashboard.mdx b/docs/es/cli/dashboard.mdx index fa5f3d0b..81fef207 100644 --- a/docs/es/cli/dashboard.mdx +++ b/docs/es/cli/dashboard.mdx @@ -1,29 +1,29 @@ --- title: Ver sesiones -description: "Inicia el panel de control para explorar sesiones de agentes y gestionar políticas" +description: "Inicia el panel de control para explorar las sesiones del agente y gestionar las políticas" --- ```bash failproofai ``` -Inicia el panel de control web en `http://localhost:8020`. +Inicia el panel web en `http://localhost:8020`. ## Opciones -| Indicador | Descripción | -|-----------|-------------| -| `--port ` | Puerto en el que escuchar (predeterminado: `8020`) | -| `--allowed-origins ` | Hosts/IPs separados por comas con acceso permitido a los recursos de desarrollo | +| Flag | Descripción | +|------|-------------| +| `--port ` | Puerto en el que escuchar (por defecto: `8020`) | +| `--allowed-origins ` | Hosts/IPs separados por comas con acceso permitido a recursos de desarrollo | -Para apuntar el panel de control a una carpeta de proyecto Claude distinta a la predeterminada, establece la variable de entorno `CLAUDE_PROJECTS_PATH` al iniciarlo. +Para apuntar el panel a una carpeta de proyectos de Claude que no sea la predeterminada, establece la variable de entorno `CLAUDE_PROJECTS_PATH` al iniciar. ## Ejemplos ```bash -# Iniciar en un puerto diferente +# Launch on a different port failproofai --port 9000 -# Usar una ruta de proyectos Claude personalizada mediante variable de entorno +# Use a custom Claude projects path via environment variable CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/es/cli/environment-variables.mdx b/docs/es/cli/environment-variables.mdx index 17657dc6..d9d111a1 100644 --- a/docs/es/cli/environment-variables.mdx +++ b/docs/es/cli/environment-variables.mdx @@ -1,6 +1,6 @@ --- title: Variables de entorno -description: "Configura el comportamiento de failproofai mediante variables de entorno" +description: "Configura el comportamiento de failproofai con variables de entorno" --- ## Dashboard @@ -8,16 +8,16 @@ description: "Configura el comportamiento de failproofai mediante variables de e | Variable | Descripción | |----------|-------------| | `PORT` | Puerto del dashboard (por defecto: `8020`) | -| `CLAUDE_PROJECTS_PATH` | Reemplaza la ubicación donde se buscan las carpetas de proyectos de Claude Code | +| `CLAUDE_PROJECTS_PATH` | Sobreescribe la ubicación donde se buscan las carpetas de proyectos de Claude Code | | `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Páginas del dashboard a ocultar, separadas por comas | | `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hosts/IPs con acceso a recursos de desarrollo. Equivalente a `--allowed-origins`. | -## Registro (Logging) +## Registro | Variable | Descripción | |----------|-------------| -| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Nivel de registro del servidor (por defecto: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | Ruta personalizada para el archivo de log de hooks, o `true` para usar el predeterminado (`~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Nivel de log del servidor (por defecto: `warn`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | Ruta personalizada del archivo de log de hooks, o `true` para usar el predeterminado (`~/.failproofai/logs/hooks.log`) | ## Telemetría @@ -29,19 +29,19 @@ description: "Configura el comportamiento de failproofai mediante variables de e | Variable | Descripción | |----------|-------------| -| `FAILPROOF_API_URL` | Reemplaza la URL base del servidor de API usada por `failproofai auth` y el diálogo de autenticación del dashboard. Por defecto es `https://api.befailproof.ai`; establécela como `http://localhost:8080` (o la dirección correspondiente) cuando se ejecute un servidor de API local. | -| `FAILPROOFAI_AUTH_DIR` | Reemplaza la ubicación donde se almacena `auth.json` (por defecto: `~/.failproofai`). Principalmente útil para pruebas aisladas. | +| `FAILPROOF_API_URL` | Sobreescribe la URL base del servidor de API utilizada por `failproofai auth` y el diálogo de autenticación del dashboard. Por defecto es `https://api.befailproof.ai`; establece `http://localhost:8080` (o la dirección que corresponda) cuando ejecutes un servidor de API local. | +| `FAILPROOFAI_AUTH_DIR` | Sobreescribe dónde se almacena `auth.json` (por defecto: `~/.failproofai`). Principalmente útil para pruebas aisladas. | -## Mensaje de primera ejecución +## Prompt de primer uso | Variable | Descripción | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | Omite el mensaje que ofrece instalar las políticas en la primera invocación básica de `failproofai` | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Omite el prompt que ofrece instalar políticas en la primera invocación de `failproofai` sin argumentos | ## LLM (para evaluación de políticas) | Variable | Descripción | |----------|-------------| | `FAILPROOFAI_LLM_BASE_URL` | Endpoint de la API del LLM (por defecto: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | Clave de API para las políticas basadas en LLM | +| `FAILPROOFAI_LLM_API_KEY` | Clave de API para políticas basadas en LLM | | `FAILPROOFAI_LLM_MODEL` | Nombre del modelo (por defecto: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/es/cli/hook.mdx b/docs/es/cli/hook.mdx index 3494f5b1..726f89e7 100644 --- a/docs/es/cli/hook.mdx +++ b/docs/es/cli/hook.mdx @@ -1,5 +1,5 @@ --- -title: Manejador de hooks (interno) +title: Manejador de hook (interno) description: "El subproceso que Claude Code invoca en cada evento de herramienta" --- @@ -7,17 +7,17 @@ description: "El subproceso que Claude Code invoca en cada evento de herramienta failproofai --hook ``` -Este es el comando registrado en el archivo `settings.json` de Claude Code por `failproofai policies --install`. Normalmente no se llama directamente. +Este es el comando que `failproofai policies --install` registra en el archivo `settings.json` de Claude Code. Normalmente no se llama directamente. Lee un payload JSON desde stdin, evalúa todas las políticas habilitadas y termina con un código que indica la decisión: | Código de salida | Decisión | Efecto | -|------------------|----------|--------| -| `0` | `allow` | Permite la acción | -| `1` | `deny` | Bloquea la acción — Claude recibe el motivo del rechazo | -| `2` | `instruct` | Inyecta orientación en el contexto de Claude | +|-----------------|----------|--------| +| `0` | `allow` | Permitir la acción | +| `1` | `deny` | Bloquear la acción — Claude recibe el motivo del rechazo | +| `2` | `instruct` | Inyectar orientación en el contexto de Claude | -### Tipos de eventos soportados +### Tipos de eventos compatibles | Categoría | Eventos | |-----------|---------| diff --git a/docs/es/cli/install-policies.mdx b/docs/es/cli/install-policies.mdx index 8d0950d4..09656bfe 100644 --- a/docs/es/cli/install-policies.mdx +++ b/docs/es/cli/install-policies.mdx @@ -7,7 +7,7 @@ description: "Habilita las políticas para que se ejecuten en cada llamada de he failproofai policies --install [policy-names...] [options] ``` -Escribe entradas de hook en el archivo de configuración del CLI de agente instalado (Claude Code, OpenAI Codex o GitHub Copilot CLI _(beta)_) para que failproofai intercepte las llamadas de herramienta. +Escribe entradas de hooks en el archivo de configuración del agente CLI instalado (Claude Code, OpenAI Codex o GitHub Copilot CLI _(beta)_) para que failproofai intercepte las llamadas de herramientas. Alias: `failproofai p -i` @@ -15,30 +15,30 @@ Alias: `failproofai p -i` | Flag | Descripción | |------|-------------| -| `--cli claude\|codex\|copilot` | CLI(s) de agente para los que instalar; separados por espacios (p. ej. `--cli claude codex copilot`) o repetido. Omitir para detectar los CLIs instalados y mostrar un aviso. | -| `--scope user` | Instala en el archivo de configuración de ámbito de usuario (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Por defecto. | +| `--cli claude\|codex\|copilot` | CLI(s) del agente en los que instalar; separados por espacio (p. ej. `--cli claude codex copilot`) o repetidos. Si se omite, detecta los CLIs instalados y solicita confirmación. | +| `--scope user` | Instala en el archivo de configuración de ámbito de usuario (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Valor predeterminado. | | `--scope project` | Instala en el archivo de configuración de ámbito de proyecto (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | | `--scope local` | Solo para Claude — instala en `/.claude/settings.local.json`. Codex y Copilot no tienen ámbito `local`. | -| `--custom ` / `-c` | Ruta a un archivo JS con políticas de hook personalizadas | +| `--custom ` / `-c` | Ruta a un archivo JS que contiene políticas de hooks personalizadas | ## Comportamiento -- **Sin nombres de política** - abre un aviso interactivo para seleccionar políticas -- **Nombres específicos** - habilita esas políticas (se añaden a las que ya estén habilitadas) -- **`all`** - habilita todas las políticas disponibles +- **Sin nombres de política** — abre un selector interactivo para elegir políticas +- **Nombres específicos** — habilita esas políticas (se añaden a las ya habilitadas) +- **`all`** — habilita todas las políticas disponibles -La instalación es acumulativa: volver a ejecutar `--install` agrega nuevas políticas sin eliminar las existentes. +La instalación es acumulativa: ejecutar `--install` de nuevo añade nuevas políticas sin eliminar las existentes. ## Ejemplos ```bash -# Instalar todas las políticas predeterminadas de forma global (interactivo) +# Instalar todas las políticas predeterminadas globalmente (interactivo) failproofai policies --install # Instalar políticas específicas para el proyecto actual failproofai policies --install block-sudo sanitize-api-keys --scope project -# Habilitar todas las políticas a la vez +# Habilitar todas las políticas de una vez failproofai policies --install all # Instalar con un archivo de políticas personalizado @@ -54,4 +54,4 @@ failproofai policies --install --cli copilot --scope project failproofai policies --install --cli claude codex copilot ``` -Cuando se proporciona `--custom `, el archivo se valida inmediatamente — debe llamar a `customPolicies.add()` al menos una vez. La ruta resuelta se guarda en `policies-config.json` como `customPoliciesPath`. \ No newline at end of file +Cuando se proporciona `--custom `, el archivo se valida de inmediato — debe llamar a `customPolicies.add()` al menos una vez. La ruta resuelta se guarda en `policies-config.json` como `customPoliciesPath`. \ No newline at end of file diff --git a/docs/es/cli/list-policies.mdx b/docs/es/cli/list-policies.mdx index 0bf7b902..be6056b0 100644 --- a/docs/es/cli/list-policies.mdx +++ b/docs/es/cli/list-policies.mdx @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -Las claves desconocidas en `policyParams` se señalan aquí para que puedas detectar errores tipográficos a tiempo. \ No newline at end of file +Las claves desconocidas en `policyParams` se marcan aquí para que puedas detectar errores tipográficos con antelación. \ No newline at end of file diff --git a/docs/es/cli/remove-policies.mdx b/docs/es/cli/remove-policies.mdx index 8b84e837..37767e1f 100644 --- a/docs/es/cli/remove-policies.mdx +++ b/docs/es/cli/remove-policies.mdx @@ -7,24 +7,24 @@ description: "Eliminar entradas de hooks de la configuración de Claude Code" failproofai policies --uninstall [policy-names...] [options] ``` -Elimina las entradas de hooks de failproofai del `settings.json` de Claude Code. +Elimina las entradas de hooks de failproofai del archivo `settings.json` de Claude Code. Alias: `failproofai p -u` ## Opciones -| Indicador | Descripción | -|-----------|-------------| +| Bandera | Descripción | +|---------|-------------| | `--scope user` | Eliminar de la configuración global (predeterminado) | | `--scope project` | Eliminar de la configuración del proyecto | | `--scope local` | Eliminar de la configuración local | | `--scope all` | Eliminar de todos los ámbitos a la vez | -| `--custom` / `-c` | Borrar la ruta `customPoliciesPath` de la configuración | +| `--custom` / `-c` | Eliminar `customPoliciesPath` de la configuración | ## Comportamiento -- **Sin nombres de política** — elimina todas las entradas de hooks de failproofai del archivo de configuración -- **Nombres específicos** — deshabilita esas políticas pero mantiene los hooks instalados +- **Sin nombres de política** - elimina todas las entradas de hooks de failproofai del archivo de configuración +- **Nombres específicos** - deshabilita esas políticas pero mantiene los hooks instalados ## Ejemplos diff --git a/docs/es/cli/version.mdx b/docs/es/cli/version.mdx index a7a62b5b..3e17b6fd 100644 --- a/docs/es/cli/version.mdx +++ b/docs/es/cli/version.mdx @@ -1,6 +1,6 @@ --- title: Verificar versión -description: "Muestra la versión instalada de failproofai" +description: "Mostrar la versión instalada de failproofai" --- ```bash diff --git a/docs/es/configuration.mdx b/docs/es/configuration.mdx index b3fbf514..591ada62 100644 --- a/docs/es/configuration.mdx +++ b/docs/es/configuration.mdx @@ -1,10 +1,10 @@ --- title: Configuración -description: "Formato del archivo de configuración, sistema de tres ámbitos y reglas de fusión" +description: "Formato de archivo de configuración, sistema de tres ámbitos y reglas de combinación" icon: gear --- -failproofai usa 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 cada desarrollador tendrá 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 tendrán la misma red de seguridad para el agente. --- @@ -14,13 +14,13 @@ Existen tres ámbitos de configuración, evaluados en orden de prioridad: | Ámbito | Ruta del archivo | Propósito | |--------|-----------------|-----------| -| **proyecto** | `.failproofai/policies-config.json` | Ajustes por repositorio, confirmados en control de versiones | -| **local** | `.failproofai/policies-config.local.json` | Anulaciones personales por repositorio, ignoradas por git | -| **global** | `~/.failproofai/policies-config.json` | Valores predeterminados del usuario en todos los proyectos | +| **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 | -Cuando failproofai recibe un evento de hook, carga y fusiona los tres archivos que existen para el directorio de trabajo actual. +Cuando failproofai recibe un evento de hook, carga y combina los tres archivos que existen para el directorio de trabajo actual. -### Reglas de fusión +### Reglas de combinación **`enabledPolicies`** — la unión de los tres ámbitos. Una política habilitada en cualquier nivel está activa. @@ -29,29 +29,29 @@ project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← unión deduplicada +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← unión sin duplicados ``` -**`policyParams`** — el primer ámbito que define los parámetros para una política dada gana por completo. No hay fusión profunda de valores dentro de los parámetros de una política. +**`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. ```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 ignorado +resolved: { allowPatterns: ["sudo apt-get update"] } ← project gana, global se ignora ``` ```text -project: (sin entrada block-sudo) -local: (sin entrada block-sudo) +project: (sin entrada para block-sudo) +local: (sin entrada para block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← cae hasta global +resolved: { allowPatterns: ["sudo systemctl status"] } ← se aplica global como respaldo ``` -**`customPoliciesPath`** — el primer ámbito que lo define gana. +**`customPoliciesPath`** — el primer ámbito que lo defina gana. -**`llm`** — el primer ámbito que lo define gana. +**`llm`** — el primer ámbito que lo defina gana. --- @@ -104,23 +104,23 @@ 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, incluso si tienen entradas en `policyParams`. +Las políticas que no están en `enabledPolicies` están inactivas, aunque tengan entradas en `policyParams`. ### `policyParams` Tipo: `Record>` -Anulaciones 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). +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). -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. +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. -Las claves desconocidas dentro del bloque de parámetros de una política se ignoran silenciosamente cuando se dispara el 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 en el momento de la ejecución del hook, pero se marcan como advertencias cuando ejecutas `failproofai policies`. #### `hint` (transversal) Tipo: `string` (opcional) -Un mensaje que se agrega al motivo cuando una política devuelve `deny` o `instruct`. Úsalo para dar a Claude orientación accionable sin modificar la política en sí. +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í. Funciona con cualquier tipo de política: integrada, personalizada (`custom/`), convención de proyecto (`.failproofai-project/`) o convención de usuario (`.failproofai-user/`). @@ -141,17 +141,17 @@ Funciona con cualquier tipo de política: integrada, personalizada (`custom/`), } ``` -Cuando `block-force-push` deniega, Claude ve: *"Force-pushing is blocked. Try creating a fresh branch instead."* +Cuando `block-force-push` deniega, Claude ve: *"Se ha bloqueado el force-push. Try creating a fresh branch instead."* -Los valores que no sean cadenas de texto y las cadenas vacías se ignoran silenciosamente. Si `hint` no está definido, el comportamiento no cambia (compatible con versiones anteriores). +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). ### `customPoliciesPath` Tipo: `string` (ruta absoluta) -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). +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). -El archivo se carga de nuevo en cada evento de hook; no hay caché. Consulta [Políticas personalizadas](/es/custom-policies) para 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 ver los detalles de creación. ### Políticas basadas en convenciones @@ -159,14 +159,14 @@ Además del `customPoliciesPath` explícito, failproofai descubre y carga autom | Nivel | Directorio | Ámbito | |-------|-----------|--------| -| Proyecto | `.failproofai/policies/` | Compartido con el equipo a través de control de versiones | -| Usuario | `~/.failproofai/policies/` | Personal, aplica a todos los proyectos | +| Proyecto | `.failproofai/policies/` | Compartido con el equipo mediante control de versiones | +| Usuario | `~/.failproofai/policies/` | Personal, se 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. **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. -**Carga por unión:** Se analizan tanto el directorio de convenciones del proyecto como el del usuario. Todos los archivos coincidentes de ambos niveles se cargan (a diferencia de `customPoliciesPath`, que usa el primer ámbito que gana). +**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). Consulta [Políticas personalizadas](/es/custom-policies) para más detalles y ejemplos. @@ -189,19 +189,20 @@ 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 distintas: +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: -- **Ajustes 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** — 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` con clave por SO de Copilot con `timeoutSec`; el archivo lleva un marcador de nivel superior `version: 1`. La compatibilidad con 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 del mundo real. - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (usuario), `/.cursor/hooks.json` (proyecto) — Cursor no tiene ámbito `local`. Las entradas de hook usan la forma `{type, command, timeout}` del estilo Claude (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 de nivel superior `version: 1`. El manejador canonicaliza camelCase → PascalCase mediante `CURSOR_EVENT_MAP` para que las políticas integradas existentes se activen sin cambios. La compatibilidad con Cursor Agent está en **beta** mientras verificamos el formato en disco de las transcripciones de Cursor (no especificado en la documentación pública) con más instalaciones del mundo real. - - **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 seis 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 como se cargan los plugins en opencode v1.14.33). La instalación coloca un pequeño shim de plugin generado que llama como subproceso al binario de failproofai y traduce la respuesta JSON en forma Claude del binario a la semántica del plugin: `throw new Error()` para denegación de eventos de herramienta (cancela la llamada a la herramienta), `client.session.prompt(...)` para instruct Y para 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 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 de 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 `. La compatibilidad con OpenCode está en **beta** mientras verificamos el comportamiento en distintas versiones y con más sesiones del mundo real. 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 extensión TypeScript al inicio; el archivo de ajustes es un array plano de cadenas `{"packages": ["./relative/path", …]}`. failproofai escribe una única entrada en el array de paquetes 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 lanza `failproofai --hook --cli pi`; el manejador canonicaliza underscore_lower_snake_case → 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` (Read/Write/Edit de Pi 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 una alternativa con `path`). La compatibilidad con Pi está en **beta** mientras la API de extensión de Pi y el diseño del registro de sesiones se estabilizan. - - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (usuario), `/.gemini/settings.json` (proyecto) — Gemini no tiene ámbito `local` (documenta un ámbito `system` en `/etc/gemini-cli/settings.json` que failproofai no expone). Las entradas de hook usan la forma `{type, command, timeout}` de Claude envuelta en el esquema de matcher `{matcher, hooks: [...]}` de Gemini con `matcher: "*"` por defecto. Los eventos son PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); el manejador mapea a nombres canónicos de Claude mediante `GEMINI_EVENT_MAP`. Los nombres de herramientas son snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — el manejador los canonicaliza mediante `GEMINI_TOOL_MAP` para que las políticas integradas existentes se activen sin cambios. El evaluador de políticas emite la forma plana `{decision: "deny", reason}` de Gemini (preferida según el contrato de salida-0 de la "Regla de Oro" de Gemini), `{hookSpecificOutput: {hookEventName, additionalContext}}` para inyección de contexto en BeforeAgent/AfterTool/SessionStart, y `{decision: "block", reason}` en AfterAgent para semántica de reintento forzado. La compatibilidad con Gemini CLI está en **beta** mientras ampliamos la cobertura del mundo real. Consulta la [documentación de hooks de Gemini CLI](https://geminicli.com/docs/hooks/). + - **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 seis 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. + - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (usuario), `/.gemini/settings.json` (proyecto) — Gemini no tiene ámbito `local` (documenta un ámbito `system` en `/etc/gemini-cli/settings.json` que failproofai no expone). Las entradas de hook usan la forma de Claude `{type, command, timeout}` envuelta en el esquema de matcher de Gemini `{matcher, hooks: [...]}` con `matcher: "*"` por defecto. Los eventos están en PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); el manejador los mapea a nombres canónicos de Claude mediante `GEMINI_EVENT_MAP`. Los nombres de herramientas están en snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — el manejador los canonicaliza mediante `GEMINI_TOOL_MAP` para que las políticas integradas existentes se activen sin cambios. El evaluador de políticas emite la forma plana de Gemini `{decision: "deny", reason}` (preferida según el contrato exit-0 de la "Regla de Oro" de Gemini), `{hookSpecificOutput: {hookEventName, additionalContext}}` para inyección de contexto en BeforeAgent / AfterTool / SessionStart, y `{decision: "block", reason}` en AfterAgent para semántica de reintento forzado. El soporte de Gemini CLI está en **beta** mientras ampliamos la cobertura en el mundo real. Consulta la [documentación de hooks de Gemini CLI](https://geminicli.com/docs/hooks/). + - **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|gemini` para apuntar a un agente específico (separados por espacios o repetidos para cualquier subconjunto): +Pasa `--cli claude|codex|copilot|cursor|opencode|pi|gemini|hermes` para apuntar a un agente específico (separados por espacios o repetidos para cualquier subconjunto): ```bash failproofai policies --install --cli codex --scope project @@ -210,17 +211,18 @@ 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 gemini --scope project +failproofai policies --install --cli hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` -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 gemini`): +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 gemini` / `which hermes`): -- **Una CLI detectada** — la selecciona automáticamente sin preguntar. -- **Múltiples CLIs detectadas** en una terminal interactiva — muestra un indicador 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 todas las CLIs compatibles no detectadas como opciones de instalación anticipada (↑↓ para moverse, Enter para seleccionar, ^C para salir). El flujo de desinstalación solo muestra 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** — recurre a `claude`, con una advertencia de que no se encontró ningún binario de agente en PATH; el comando de hook se escribe igualmente para que se active en cuanto instales uno. +- **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. -Puedes editar `policies-config.json` directamente en cualquier momento; los cambios surten efecto de inmediato en el siguiente evento de hook sin necesidad de reiniciar. +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 +247,4 @@ Confirma `.failproofai/policies-config.json` en tu repositorio: } ``` -Cada desarrollador puede luego crear `.failproofai/policies-config.local.json` (ignorado por git) para sus anulaciones 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` (ignorado por git) 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 1cbe5f71..01e1b6ff 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, previene desviaciones, detecta fallos e integra con sistemas externos" +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" icon: code --- -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 mucho más. Utilizan el mismo sistema de eventos de hooks y las mismas decisiones `allow`, `deny`, `instruct` que las políticas integradas. +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. --- @@ -29,7 +29,7 @@ customPolicies.add({ }); ``` -Instálala: +Instálalo: ```bash failproofai policies --install --custom ./my-policies.js @@ -39,12 +39,12 @@ failproofai policies --install --custom ./my-policies.js ## Dos formas de cargar políticas personalizadas -### Opción 1: Basada en convención (recomendada) +### Opción 1: Basada en convenciones (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: suelta un archivo y listo. +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á. ``` -# Nivel de proyecto — se incluye en git, compartido con el equipo +# Nivel de proyecto — incluido en git, compartido con el equipo .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs @@ -53,26 +53,26 @@ Coloca archivos `*policies.{js,mjs,ts}` en `.failproofai/policies/` y se cargar ``` **Cómo funciona:** -- Se escanean tanto el directorio del proyecto como el del usuario (unión — no gana el primero en alcance) -- Los archivos se cargan en orden alfabético dentro de cada directorio. Usa prefijos `01-`, `02-` para controlar el orden +- Se analizan tanto el directorio del proyecto como el del usuario (unión — no gana el primero en alcance) +- 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 (fail-open por archivo) +- Cada archivo se carga de forma independiente (fallo abierto por archivo) - Funciona junto con `--custom` explícito y las políticas integradas -Las políticas de 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 cada miembro del equipo obtendrá las mismas reglas automáticamente, sin configuración individual. A medida que el equipo descubra nuevos modos de fallo, agrega una política y haz push. Con el tiempo, estas se convierten 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 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. ### Opción 2: Ruta de archivo explícita ```bash -# Instalar con un archivo de políticas personalizadas +# Instalar con un archivo de políticas personalizado failproofai policies --install --custom ./my-policies.js # Reemplazar la ruta del archivo de políticas failproofai policies --install --custom ./new-policies.js -# Eliminar la ruta de políticas personalizadas de la configuración +# Eliminar la ruta de políticas personalizada de la configuración failproofai policies --uninstall --custom ``` @@ -80,11 +80,11 @@ La ruta absoluta resuelta se almacena en `policies-config.json` como `customPoli ### Usar ambas opciones juntas -Las políticas de convención y el archivo `--custom` explícito pueden coexistir. Orden de carga: +Las políticas por convención y el archivo `--custom` explícito pueden coexistir. Orden de carga: 1. Archivo `customPoliciesPath` explícito (si está 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) +2. Archivos de convención del proyecto (`{cwd}/.failproofai/policies/`, alfabético) +3. Archivos de convención del usuario (`~/.failproofai/policies/`, alfabético) --- @@ -98,44 +98,44 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Registra una política. Llama a este método tantas veces como necesites para múltiples políticas en el mismo archivo. +Registra una política. Llámalo tantas veces como necesites para definir múltiples políticas en el mismo archivo. ```ts customPolicies.add({ - name: string; // requerido - identificador único + name: string; // obligatorio - identificador único description?: string; // se muestra en la salida de `failproofai policies` - match?: { events?: HookEventType[] }; // filtra por tipo de evento; omitir para coincidir con todos + match?: { events?: HookEventType[] }; // filtrar por tipo de evento; omitir para coincidir con todos fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` ### Funciones de decisión -| Función | Efecto | Úsala cuando | +| Función | Efecto | Cuándo usarla | |----------|--------|----------| -| `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)` | Agrega contexto sin bloquear | Dale al agente contexto adicional para mantenerse en curso | +| `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 | -`deny(message)` — el mensaje aparece ante Claude con el prefijo `"Blocked by failproofai:"`. Un único `deny` interrumpe toda evaluación posterior. +`deny(message)` — el mensaje aparece ante Claude con el prefijo `"Blocked by failproofai:"`. Un solo `deny` interrumpe toda evaluación posterior. -`instruct(message)` — el mensaje se agrega al contexto de Claude para la llamada de 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 a la herramienta actual. Todos los mensajes `instruct` se acumulan y se entregan juntos. -Puedes añadir orientación adicional a cualquier mensaje `deny` o `instruct` agregando un 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` 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. ### 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 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 con un significado diferente: es una actualización de estado, no una advertencia. -| Función | Efecto | Úsala cuando | +| Función | Efecto | Cuándo usarla | |----------|--------|----------| -| `allow(message)` | Permite y envía contexto a Claude | Confirma que una verificación pasó, o explica por qué se omitió | +| `allow(message)` | Permite y envía contexto a Claude | Confirmar que una verificación pasó o explicar por qué se omitió | Casos de uso: -- **Confirmaciones de estado:** `allow("All CI checks passed.")` — le indica a Claude que todo está bien -- **Explicaciones de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — le indica a Claude por qué se omitió una verificación para que tenga contexto completo +- **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 - **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 @@ -162,8 +162,8 @@ customPolicies.add({ | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | | `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` | Carga útil completa del evento raw de Claude Code | -| `session` | `SessionMetadata \| undefined` | Contexto de sesión (ver más abajo) | +| `payload` | `Record` | Payload completo del evento raw de Claude Code | +| `session` | `SessionMetadata \| undefined` | Contexto de sesión (ver a continuación) | ### Campos de `SessionMetadata` @@ -178,7 +178,7 @@ customPolicies.add({ | 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 termina | La entrada de la herramienta + `tool_result` (la salida) | +| `PostToolUse` | Después de que una herramienta finaliza | 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 | @@ -190,11 +190,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 en `.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro de cada uno) -4. Políticas de convención del usuario en `~/.failproofai/policies/` (archivos en orden alfabético, orden de `.add()` dentro de cada uno) +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) -El primer `deny` interrumpe todas las políticas posteriores. Todos los mensajes `instruct` se acumulan y se entregan juntos. +El primer `deny` interrumpe todas las políticas siguientes. Todos los mensajes `instruct` se acumulan y se entregan juntos. --- @@ -224,40 +224,40 @@ Se resuelven todas las importaciones relativas alcanzables desde el archivo de e ## Filtrado por tipo de evento -Usa `match.events` para limitar cuándo se dispara una política: +Usa `match.events` para limitar cuándo se activa una política: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Solo se dispara cuando termina la sesión + // Solo se activa cuando la sesión finaliza // ctx.session.transcriptPath contiene el registro completo de la sesión return allow(); }, }); ``` -Omite `match` por completo para disparar en cada tipo de evento. +Omite `match` completamente para que se active en todos los tipos de eventos. --- ## Manejo de errores y modos de fallo -Las políticas personalizadas son **fail-open**: los errores nunca bloquean las políticas integradas ni hacen fallar el handler del hook. +Las políticas personalizadas son de **fallo abierto**: los errores nunca bloquean las políticas integradas ni hacen que el handler del hook falle. | 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 | Se registra una advertencia en `~/.failproofai/hook.log`; las políticas integradas continúan | -| Error de sintaxis/importación (explícito) | El error se registra en `~/.failproofai/hook.log`; se omiten las políticas personalizadas explícitas | -| Error de sintaxis/importación (convención) | El error se registra; ese archivo se omite, los demás archivos de convención se siguen cargando | -| `fn` lanza un error en tiempo de ejecución | El error se registra; ese hook se trata como `allow`; los demás hooks continúan | -| `fn` tarda más de 10 segundos | Se registra el timeout; se trata como `allow` | -| Directorio de convención inexistente | No se ejecutan políticas de convención; sin error | +| 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 | +| `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 | -Para depurar errores de políticas personalizadas, observa el archivo de log: +Para depurar errores en políticas personalizadas, monitorea el archivo de log: ```bash tail -f ~/.failproofai/hook.log @@ -272,7 +272,7 @@ tail -f ~/.failproofai/hook.log // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// Prevent agent from writing to secrets/ directory +// Evitar que el agente escriba en el directorio secrets/ customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -285,7 +285,7 @@ customPolicies.add({ }, }); -// Keep the agent on track: verify tests before committing +// Mantener al agente en el camino correcto: verificar los tests antes de hacer commit customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +300,7 @@ customPolicies.add({ }, }); -// Prevent unplanned dependency changes during freeze +// Prevenir cambios de dependencias no planificados durante el período de congelación customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -323,14 +323,14 @@ export { customPolicies }; ## Ejemplos -El directorio `examples/` contiene archivos de políticas listos para ejecutar: +El directorio `examples/` contiene archivos de políticas listos para usar: | Archivo | Contenido | |------|----------| -| `examples/policies-basic.js` | Cinco políticas iniciales que cubren los modos de fallo más comunes de los agentes | -| `examples/policies-advanced/index.js` | Patrones avanzados: importaciones transitivas, llamadas asíncronas, limpieza de salida y hooks al final de sesión | -| `examples/convention-policies/security-policies.mjs` | Políticas de seguridad basadas en convención (bloquear escrituras en .env, prevenir reescritura del historial de git) | -| `examples/convention-policies/workflow-policies.mjs` | Políticas de flujo de trabajo basadas en convención (recordatorios de tests, auditoría de escrituras de archivos) | +| `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) | ### Usar los ejemplos con archivo explícito @@ -338,7 +338,7 @@ El directorio `examples/` contiene archivos de políticas listos para ejecutar: failproofai policies --install --custom ./examples/policies-basic.js ``` -### Usar los ejemplos basados en convención +### Usar los ejemplos basados en convenciones ```bash # Copiar al nivel de proyecto @@ -350,4 +350,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 siguiente evento de hook. \ No newline at end of file diff --git a/docs/es/dashboard.mdx b/docs/es/dashboard.mdx index 48ef2be7..b08f724b 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. Consulta lo que hicieron tus agentes mientras no estabas. --- @@ -16,7 +16,7 @@ failproofai Se abre en `http://localhost:8020`. -El dashboard lee directamente del sistema de archivos — tus carpetas de proyectos de Claude Code y los archivos de configuración de failproofai. No se escribe nada en un servicio remoto. +El dashboard lee directamente desde el sistema de archivos: las carpetas de proyectos de Claude Code y los archivos de configuración de failproofai. No se escribe nada en ningún servicio remoto. --- @@ -24,11 +24,11 @@ El dashboard lee directamente del sistema de archivos — tus carpetas de proyec ### Proyectos -Lista todos los proyectos de Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_ y Gemini CLI _(beta)_ 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 transcript 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 valor 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 los transcripts 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; los proyectos de Gemini CLI se descubren escaneando `~/.gemini/tmp//chats/session--.jsonl` (configurable mediante `GEMINI_SESSIONS_DIR`) y recuperando el cwd canónico a partir del marcador de texto `.project_root` adyacente. Un proyecto que ha sido usado por múltiples CLIs se muestra como una sola 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|gemini`. +Lista todos los proyectos de Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Gemini CLI _(beta)_ y Hermes 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 todas las transcripciones en `~/.codex/sessions///
/*.jsonl` y agrupándolas 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 alternativas de búsqueda) para 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; los proyectos de Gemini CLI se descubren escaneando `~/.gemini/tmp//chats/session--.jsonl` (configurable mediante `GEMINI_SESSIONS_DIR`) y recuperando el cwd canónico desde el marcador de texto `.project_root` adyacente; las sesiones del gateway de Hermes se leen directamente desde 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). Un proyecto que haya 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 conserva tu selección como `?cli=claude|codex|copilot|cursor|opencode|pi|gemini|hermes`. Cada proyecto muestra: - Nombre del proyecto (derivado de la ruta de la carpeta) -- Un badge de CLI — `Claude Code` (naranja), `OpenAI Codex` (morado), `GitHub Copilot` (azul), `Cursor Agent` (esmeralda), `OpenCode` (ámbar), `Pi` (rosa) y/o `Gemini CLI` (celeste) +- Una insignia de CLI — `Claude Code` (naranja), `OpenAI Codex` (morado), `GitHub Copilot` (azul), `Cursor Agent` (esmeralda), `OpenCode` (ámbar), `Pi` (rosa), `Gemini CLI` (celeste) 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 +47,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 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 un transcript de Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi o Gemini CLI. 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 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, Gemini CLI o Hermes. 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 -- **Llamadas a herramientas** — Cada herramienta que invocó Claude, con su entrada y salida -- **Actividad de políticas** — Para cada llamada a herramienta, qué políticas se activaron y qué decisión devolvieron +- **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). -Haz clic en el botón **Download Logs** para exportar la sesión. Para sesiones de Claude Code, Codex, Copilot, Cursor, Pi y Gemini obtienes el transcript 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`. +Haz clic en el botón **Descargar Logs** para exportar la sesión. Para sesiones de Claude Code, Codex, Copilot, Cursor, Pi y Gemini 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`. -### Audit +### Auditoría -Un informe con personalidad propia sobre cómo se ha comportado realmente tu agente a lo largo de sesiones anteriores. Ejecuta el mismo análisis que el CLI `failproofai audit` pero lo presenta 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 escaneo que el CLI `failproofai audit` pero lo renderiza como un póster compartible de 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 of 08`) + fecha de auditoría · puntuación numérica (0–100) + pastilla de 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` · mosaico 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 ejecuta a través de `html-to-image`, por lo que el PNG coincide píxel a píxel con lo que se muestra en pantalla (bordes punteados, máscara de logo SVG, degradados, métricas de fuente — todo preservado). -2. **Fortalezas** — lista en calma con marca ✓ de comportamientos que tu agente ya hace bien, derivados de los datos de auditoría en vivo (tasa limpia de llamadas a herramientas, sin push directos a main, cero filtraciones de credenciales, cero tormentas de reintentos) — cada uno se muestra solo cuando la política relevante tiene un historial limpio durante el período de auditoría. -3. **Peculiaridades** — tabla de lo que se pasó por alto, ordenado por severidad: `cuándo · qué se pasó + la política que lo habría detectado · pastilla 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 en calma, una entrada 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 en el lado derecho. 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 todas las políticas prescritas. -5. **Vuelve mejorado** — dos tarjetas lado a lado. Izquierda: configura un recordatorio (selector de cadencia `3d` / `7d` / `14d` / `30d`; persiste a través de `/api/auth/reminder` una vez autenticado). Derecha: desbloquea 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áximo 10 por envío), los envía mediante POST a `/api/audit/invite`, que los 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, de modo que el destinatario ve quién lo invitó y el remitente recibe una copia en su bandeja de entrada. Los usuarios anónimos son dirigidos primero a `AuthDialog` para que el correo del remitente sea conocido antes de enviar las invitaciones. La gestión de derechos y ventajas es un paso posterior. +1. **Póster** — ocupa el primer viewport. Región de captura PNG autocontenida 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 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` · ficha 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 recuadro de captura: `post your archetype` (intención en X), `share on linkedin`, `download poster`. La captura se realiza mediante `html-to-image` para que el PNG coincida píxel a píxel con el renderizado en pantalla (bordes punteados, máscara de logo SVG, degradados, métricas de fuente — todo preservado). +2. **Fortalezas** — lista de comportamientos que tu agente ya hace bien, con una marca de verificación tranquila, derivada de los datos de auditoría en tiempo real (tasa de llamadas a herramientas limpia, sin pushes directos a main, cero filtraciones de credenciales, cero tormentas de reintentos) — cada una se muestra solo cuando la política relevante tiene un historial limpio durante la ventana de auditoría. +3. **Peculiaridades** — tabla de lo que se escapó, ordenado 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 tranquila de filas, 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 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 coma, espacio o salto de línea (máximo 10 por envío), los publica en `/api/audit/invite`, que los reenvía al `POST /v0/invite` del servidor de API. El servidor de API envía un correo por destinatario desde `invite@failproof.ai` con el remitente en Cc y `Reply-To` configurado, de modo que el destinatario vea quién lo invitó y el remitente reciba una copia en su bandeja. Los usuarios anónimos pasan primero por el `AuthDialog` para que el correo del remitente sea conocido antes de enviar las invitaciones. El cumplimiento de derechos y ventajas es un seguimiento pendiente. -Impulsado por el runtime de `failproofai audit` — consulta [Audit CLI](/es/cli/audit) para el motor de análisis subyacente, flags compatibles e invariantes de caché por transcript. El dashboard almacena en caché el último resultado en `~/.failproofai/audit-dashboard.json` (modo `0600`, un solo slot, las nuevas ejecuciones sobreescriben) para que las revisitas sean instantáneas; **tanto la caché por transcript como la caché del resultado completo se rechazan al leerse si tienen más de 7 días**, por lo que el dashboard nunca sirve silenciosamente un resultado de hace una semana — pasado el TTL, `/audit` cae a su estado vacío y solicita una nueva ejecución. Al hacer clic en `[ re-audit now ]` cerca de la parte inferior del informe se envía un POST a `/api/audit/run` con `noCache: true` — la re-auditoría omite la caché por transcript y vuelve a analizar cada transcript desde cero en lugar de devolver silenciosamente el resultado en caché — y el dashboard consulta `/api/audit/status` a 1 Hz hasta que la ejecución finaliza; una banda 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 en su lugar al completarse con éxito (sin recarga de página completa; una re-auditoría fallida deja el informe anterior intacto). En caso de fallo, la banda se vuelve roja con un mensaje según `RerunError.kind` (`timeout` / `network` / `post_failed`). El estado vacío (sin caché o expirado) y el estado de cero sesiones (la caché existe pero el análisis no encontró transcripts) se muestran por separado. +Impulsado por el runtime de `failproofai audit` — consulta [Audit CLI](/es/cli/audit) para el motor de escaneo subyacente, flags compatibles e 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 revisitas sean instantáneas; **tanto las cachés por transcripción como las de 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 hace una semana — pasado el TTL, `/audit` cae a su estado vacío y solicita una ejecución nueva. Al hacer clic en `[ re-audit now ]` cerca de la parte inferior del informe se hace un 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 1 Hz hasta que termina 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 nuevo se intercambia en su lugar al tener éxito (sin recarga de página completa; una re-auditoría fallida deja intacto el informe anterior). En caso de fallo, la tira 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 de cero sesiones (caché existe pero el escaneo no encontró transcripciones) se muestran por separado. ### Políticas -Una página con 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 Gemini CLI tienen cada uno una fila con el estado de instalación (`Active` / `Detected` / `Inactive`), la ruta de configuración del scope 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 PATH se marcan previamente. - - Activa o desactiva políticas individuales con un solo clic (escribe en `~/.failproofai/policies-config.json` — compartido entre todos los CLIs instalados) + - Selección múltiple de los CLIs de agentes que failproofai protege desde un único panel — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Gemini CLI y Hermes tienen 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 desees y haz clic en `Apply changes` para instalar/desinstalar la diferencia en un solo paso. Los CLIs cuyo binario se detecta en PATH se marcan previamente. + - Activa o desactiva políticas individuales con un solo clic (escribe en `~/.failproofai/policies-config.json` — compartido entre cada CLI instalado) - Expande una política para configurar sus parámetros (para políticas que admiten `policyParams`) - Establece una ruta de archivo de políticas personalizadas - Historial completo paginado de cada evento de hook que se ha activado en todas las sesiones - - Filtro por decisión, tipo de evento, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Gemini CLI _(beta)_), nombre de política o ID de sesión - - 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, celeste = Gemini CLI), 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 transcript — 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`) y muestra el badge de CLI correspondiente en el encabezado + - Filtra por decisión, tipo de evento, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Gemini CLI _(beta)_ / Hermes), 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, celeste = Gemini CLI, índigo = Hermes), 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`, Hermes `~/.hermes/state.db`) y renderiza la insignia de CLI correspondiente en el encabezado @@ -92,13 +92,13 @@ Una página con dos pestañas para gestionar políticas y revisar la actividad. ## Actualización automática -El dashboard tiene un botón de actualización automática en la navegación superior. Cuando está habilitado, la página actual se refresca periódicamente para mostrar nuevas sesiones y actividad de políticas a medida que aparecen. Es 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á habilitado, la página actual se actualiza periódicamente para mostrar nuevas sesiones y actividad de políticas a medida que aparecen. Es esencial para monitorear sesiones de agentes autónomos de larga duración. --- ## Deshabilitar páginas -Si solo necesitas algunas partes del dashboard, establece `FAILPROOFAI_DISABLE_PAGES` con una lista de nombres de páginas separados por comas: +Si solo necesitas algunas partes del dashboard, establece `FAILPROOFAI_DISABLE_PAGES` en una lista separada por comas de nombres de páginas: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -110,7 +110,7 @@ Valores válidos: `policies`, `projects`, `audit`. ## Configurar la ruta de proyectos -Por defecto, el dashboard lee del directorio estándar de proyectos de Claude Code. Puedes sobreescribirlo para configuraciones personalizadas: +Por defecto, el dashboard lee desde el directorio de proyectos estándar de Claude Code. Puedes sobreescribirlo para configuraciones personalizadas: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,13 +120,13 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## Acceder desde un host que no sea localhost -Cuando ejecutas el dashboard en **modo dev** (`npm run dev`) y accedes a él desde un hostname distinto de `localhost` — por ejemplo, un dominio personalizado, una IP remota o una URL tunelizada — puede aparecer una advertencia como: +Cuando ejecutas el dashboard en **modo dev** (`npm run dev`) y accedes a él desde un hostname distinto a `localhost` — por ejemplo, un dominio personalizado, una IP remota o una URL tunelizada — es posible que veas una advertencia como: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -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 dev. Para permitir tu host, usa el flag `--allowed-origins`: +Esto es Next.js bloqueando el acceso cross-origin a su websocket de HMR (recarga de módulos en caliente), que es una característica exclusiva del modo dev. Para permitir tu host, usa el flag `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -145,5 +145,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Esto solo aplica al modo dev. Al ejecutar `failproofai` (modo producción), no hay websocket HMR ni problema de recursos dev de origen cruzado. +Esto solo aplica al modo dev. Al ejecutar `failproofai` (modo producción), no hay websocket de HMR ni problema de recursos dev cross-origin. \ No newline at end of file diff --git a/docs/es/examples.mdx b/docs/es/examples.mdx index 76eb44f9..b9e586cd 100644 --- a/docs/es/examples.mdx +++ b/docs/es/examples.mdx @@ -10,7 +10,7 @@ Ejemplos listos para usar en escenarios comunes. Cada uno muestra cómo instalar ## Configurar hooks para Claude Code -Failproof AI se integra con Claude Code a través de su [sistema de hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Cuando ejecutas `failproofai policies --install`, registra comandos de hook en el `settings.json` de Claude Code que se activan en cada llamada a una herramienta. +Failproof AI se integra con Claude Code a través de su [sistema de hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Cuando ejecutas `failproofai policies --install`, registra comandos de hook en el archivo `settings.json` de Claude Code que se disparan en cada llamada a una herramienta. @@ -18,7 +18,7 @@ Failproof AI se integra con Claude Code a través de su [sistema de hooks](https npm install -g failproofai ``` - + ```bash failproofai policies --install ``` @@ -52,7 +52,7 @@ Si estás desarrollando con el [Agents SDK](https://docs.anthropic.com/en/docs/a ``` - Pasa comandos de hook al crear el proceso de tu agente. Los hooks se activan de la misma manera que en Claude Code — mediante JSON por stdin/stdout: + Pasa comandos de hook al crear el proceso de tu agente. Los hooks se disparan de la misma manera que en Claude Code — mediante JSON por stdin/stdout: ```bash failproofai --hook PreToolUse # se llama antes de cada herramienta @@ -88,29 +88,29 @@ Si estás desarrollando con el [Agents SDK](https://docs.anthropic.com/en/docs/a ## Bloquear comandos destructivos -La configuración más habitual: evitar que los agentes causen daños irreversibles. +La configuración más habitual: evita que los agentes causen daños irreversibles. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` -Qué hace cada uno: +Qué hace esto: - `block-sudo` — bloquea todos los comandos `sudo` - `block-rm-rf` — bloquea la eliminación recursiva de archivos - `block-force-push` — bloquea `git push --force` -- `block-curl-pipe-sh` — bloquea la ejecución de scripts remotos mediante pipe al shell +- `block-curl-pipe-sh` — bloquea la canalización de scripts remotos al shell --- ## Prevenir la filtración de secretos -Impide que los agentes vean o filtren credenciales en la salida de las herramientas. +Evita que los agentes vean o filtren credenciales en la salida de las herramientas. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -Estas políticas se activan en `PostToolUse` — después de que se ejecuta una herramienta, limpian la salida antes de que el agente la vea. +Estas se disparan en `PostToolUse` — después de que una herramienta se ejecuta, limpian la salida antes de que el agente la vea. --- @@ -182,9 +182,9 @@ customPolicies.add({ --- -## Requerir pruebas antes de los commits +## Exigir pruebas antes de hacer commits -Recuerda a los agentes que ejecuten las pruebas antes de hacer commit. +Recuerda a los agentes que ejecuten las pruebas antes de confirmar cambios. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -208,7 +208,7 @@ customPolicies.add({ ## Proteger un repositorio de producción -Incluye una configuración a nivel de proyecto en el repositorio para que todos los desarrolladores de tu equipo compartan las mismas políticas. +Confirma una configuración a nivel de proyecto para que todos los desarrolladores de tu equipo apliquen las mismas políticas. Crea `.failproofai/policies-config.json` en tu repositorio: @@ -231,20 +231,20 @@ Crea `.failproofai/policies-config.json` en tu repositorio: } ``` -Luego haz commit: +Luego confírmalo: ```bash git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -Todos los miembros del equipo que tengan failproofai instalado adoptarán estas reglas automáticamente. +Todos los miembros del equipo que tengan failproofai instalado aplicarán estas reglas automáticamente. --- -## Construir un estándar de calidad para toda la organización con políticas de convención +## Establecer un estándar de calidad organizacional con políticas de convención -La configuración más efectiva: incluye `.failproofai/policies/` en tu repositorio con políticas adaptadas a tu proyecto. Todos los miembros del equipo las reciben automáticamente — sin comandos de instalación, sin cambios de configuración. +La configuración con mayor impacto: confirma `.failproofai/policies/` en tu repositorio con políticas adaptadas a tu proyecto. Todos los miembros del equipo las recibirán automáticamente — sin comandos de instalación ni cambios de configuración. @@ -256,8 +256,8 @@ La configuración más efectiva: incluye `.failproofai/policies/` en tu reposito // .failproofai/policies/team-policies.mjs import { customPolicies, allow, deny, instruct } from "failproofai"; - // Imponer el gestor de paquetes preferido del equipo - // (o habilitar la política integrada prefer-package-manager en su lugar) + // Enforce your team's preferred package manager + // (or enable the built-in prefer-package-manager policy instead) customPolicies.add({ name: "enforce-bun", match: { events: ["PreToolUse"] }, @@ -269,7 +269,7 @@ La configuración más efectiva: incluye `.failproofai/policies/` en tu reposito }, }); - // Recordar al agente que ejecute las pruebas antes de hacer commit + // Remind the agent to run tests before committing customPolicies.add({ name: "test-before-commit", match: { events: ["PreToolUse"] }, @@ -283,14 +283,14 @@ La configuración más efectiva: incluye `.failproofai/policies/` en tu reposito }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - A medida que tu equipo encuentre nuevos problemas, agrega políticas y haz push. Todos reciben la actualización en su próximo `git pull`. Estas políticas se convierten en un estándar de calidad vivo que crece junto con tu equipo. + A medida que tu equipo encuentre nuevos casos de fallo, agrega políticas y súbelas. Todos recibirán la actualización en su próximo `git pull`. Estas políticas se convierten en un estándar de calidad vivo que crece junto con tu equipo. @@ -298,10 +298,10 @@ La configuración más efectiva: incluye `.failproofai/policies/` en tu reposito ## Más ejemplos -El directorio [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) del repositorio contiene: +El directorio [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) en el repositorio contiene: | Archivo | Qué muestra | |---------|-------------| -| `policies-basic.js` | Políticas básicas — bloquear escrituras en producción, force-push y scripts mediante pipe | +| `policies-basic.js` | Políticas de inicio — bloquear escrituras en producción, force-push y scripts canalizados | | `policies-notification.js` | Alertas de Slack para notificaciones de inactividad y fin de sesión | -| `policies-advanced/index.js` | Importaciones transitivas, hooks asíncronos, limpieza de salida en PostToolUse y manejo del evento Stop | \ No newline at end of file +| `policies-advanced/index.js` | Importaciones transitivas, hooks asíncronos, limpieza de salida en PostToolUse y gestión del evento Stop | \ No newline at end of file diff --git a/docs/es/for-agents.mdx b/docs/es/for-agents.mdx index f40d806a..7a1f563b 100644 --- a/docs/es/for-agents.mdx +++ b/docs/es/for-agents.mdx @@ -1,9 +1,9 @@ --- title: "Para agentes" -description: "Añade el conocimiento de Failproof AI a tu agente de programación con un solo comando. Compatible con Claude Code, Cursor, Windsurf y más." +description: "Añade el conocimiento de Failproof AI a tu agente de código en un solo comando. Compatible con Claude Code, Cursor, Windsurf y más." --- -Añade la referencia completa de Failproof AI a tu agente de programación con un solo comando. Compatible con Claude Code, Cursor, Windsurf y cualquier otro agente que soporte skills. +Añade la referencia completa de Failproof AI a tu agente de código en un solo comando. Compatible con Claude Code, Cursor, Windsurf y cualquier otro agente que soporte skills. ```bash npx skills add https://docs.befailproof.ai @@ -15,22 +15,22 @@ npx skills add https://docs.befailproof.ai | Área | Qué incluye | |------|-------------| -| Policies | Nombres de políticas integradas, tipos de eventos, parámetros, activar/desactivar | -| Custom policies | `customPolicies.add()`, filtros de coincidencia, API `allow`/`deny`/`instruct` | +| Políticas | Nombres de políticas integradas, tipos de eventos, parámetros, activar/desactivar | +| Políticas personalizadas | `customPolicies.add()`, filtros de coincidencia, API `allow`/`deny`/`instruct` | | Objeto de contexto | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | -| Configuración | Estructura de `policies-config.json`, fusión de scopes, `policyParams` | -| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scopes | -| Dashboard | Visor de sesiones, actividad de políticas, variables de entorno | +| Configuración | Estructura de `policies-config.json`, fusión de ámbitos, `policyParams` | +| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, ámbitos | +| Panel de control | Visor de sesiones, actividad de políticas, variables de entorno | | Arquitectura | Flujo del hook handler, códigos de salida, contrato stdin/stdout | -## ¿Está completo el skill? +## ¿El skill está completo? Mintlify genera `llms.txt` a partir de todas las páginas de la navegación. La documentación de Failproof AI cubre la API completa: cada política, opción y ejemplo está incluido. Si encuentras algo que falta, el origen está en `https://docs.befailproof.ai/llms-full.txt`. Para contexto específico, enlaza directamente a una página concreta: ```bash -# Solo la API de custom policies +# Solo la API de políticas personalizadas npx skills add https://docs.befailproof.ai/custom-policies # Solo las políticas integradas diff --git a/docs/es/getting-started.mdx b/docs/es/getting-started.mdx index e6fbf4d7..51f88320 100644 --- a/docs/es/getting-started.mdx +++ b/docs/es/getting-started.mdx @@ -1,13 +1,13 @@ --- title: Primeros pasos -description: "Instala failproofai, activa las políticas y deja que tus agentes funcionen de forma fiable" +description: "Instala failproofai, activa las políticas y deja que tus agentes funcionen de forma confiable" icon: rocket --- ## Requisitos - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (opcional - solo necesario para compilar desde el código fuente) +- **Bun** >= 1.3.0 (opcional — solo necesario para compilar desde el código fuente) --- @@ -30,16 +30,16 @@ bun add -g failproofai ## Inicio rápido - - Las políticas son reglas que se ejecutan antes y después de cada llamada a una herramienta del agente. Detectan comandos destructivos, filtración de secretos y otros modos de fallo antes de que causen daño. + + Las políticas son reglas que se ejecutan antes y después de cada llamada a una herramienta del agente. Detectan comandos destructivos, filtraciones de secretos y otros modos de fallo antes de que causen daño. ```bash failproofai policies --install ``` - Esto escribe entradas de hooks en los CLIs de agentes que tengas instalados (en `~/.claude/settings.json` de Claude Code, `~/.codex/hooks.json` de OpenAI Codex, `~/.copilot/hooks/failproofai.json` de GitHub Copilot CLI, `~/.cursor/hooks.json` de Cursor Agent, el shim de plugin generado en `~/.config/opencode/plugins/failproofai.mjs` de OpenCode junto con una entrada de registro en el array `plugin` de `~/.config/opencode/opencode.json`, `~/.pi/agent/settings.json` de Pi, o `~/.gemini/settings.json` de Gemini CLI). Si hay más de uno presente, se te pedirá que elijas; pasa `--cli claude codex copilot cursor opencode pi gemini` (cualquier subconjunto) para omitir el aviso. + Esto escribe entradas de hooks en los CLIs de agentes instalados (el `~/.claude/settings.json` de Claude Code, el `~/.codex/hooks.json` de OpenAI Codex, el `~/.copilot/hooks/failproofai.json` de GitHub Copilot CLI, el `~/.cursor/hooks.json` de Cursor Agent, el shim de plugin generado de OpenCode en `~/.config/opencode/plugins/failproofai.mjs` junto con una entrada de registro en el array `plugin` de `~/.config/opencode/opencode.json`, el `~/.pi/agent/settings.json` de Pi, el `~/.gemini/settings.json` de Gemini CLI, o el `~/.hermes/config.yaml` de Hermes). Si hay más de uno presente, se te pedirá que elijas; pasa `--cli claude codex copilot cursor opencode pi gemini hermes` (cualquier subconjunto) para omitir la pregunta. - El soporte de GitHub Copilot CLI, Cursor Agent, OpenCode, Pi y Gemini CLI está en **beta** — instala con `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, o `--cli gemini`. + El soporte para GitHub Copilot CLI, Cursor Agent, OpenCode, Pi y Gemini CLI es **beta** — instala con `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi` o `--cli gemini`. Hermes (hermes-agent, una puerta de enlace para Slack/Telegram) se instala con alcance de usuario mediante `--cli hermes` y es **también** una fuente de auditoría sin conexión. ```bash failproofai policies --install --scope project @@ -49,25 +49,26 @@ bun add -g failproofai failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project + failproofai policies --install --cli hermes --scope user failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` - + ```bash failproofai policies ``` - Muestra todas las políticas, si están activadas y los parámetros configurados. + Muestra todas las políticas, si están habilitadas y los parámetros configurados. - + ```bash failproofai ``` Abre un panel de control local en `http://localhost:8020` donde puedes explorar sesiones, inspeccionar llamadas a herramientas y gestionar políticas. - - Inicia Claude Code como de costumbre. Si el agente intenta algo arriesgado, failproofai lo intercepta automáticamente. Déjalo ejecutarse sin supervisión y revisa lo que ocurrió en el panel de control. + + Inicia Claude Code como de costumbre. Si el agente intenta algo arriesgado, failproofai lo intercepta automáticamente. Déjalo correr desatendido y revisa lo que ocurrió en el panel de control. @@ -85,9 +86,9 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON Cada política devuelve una de tres decisiones: -- **allow** - el agente continúa con normalidad -- **deny** - la acción se bloquea y se le indica al agente el motivo -- **instruct** - se añade contexto adicional al prompt del agente +- **allow** — el agente continúa con normalidad +- **deny** — la acción es bloqueada y se le indica al agente el motivo +- **instruct** — se añade contexto adicional al prompt del agente Las políticas se ejecutan en tu proceso local. No se envía nada a un servicio remoto. @@ -95,18 +96,18 @@ Las políticas se ejecutan en tu proceso local. No se envía nada a un servicio --- -## Configurar políticas de equipo mediante políticas basadas en convenciones +## Configura políticas de equipo con políticas basadas en convenciones La forma más rápida de establecer estándares de calidad en tu equipo es la convención `.failproofai/policies/`. Coloca archivos de políticas en este directorio y se cargan automáticamente — sin flags, sin cambios de configuración, sin comandos de instalación. - + ```bash mkdir -p .failproofai/policies ``` - - Copia los ejemplos iniciales o escribe los tuyos propios: + + Copia los ejemplos de inicio o escribe los tuyos propios: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -131,7 +132,7 @@ La forma más rápida de establecer estándares de calidad en tu equipo es la co }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" @@ -142,7 +143,7 @@ La forma más rápida de establecer estándares de calidad en tu equipo es la co -Confirma `.failproofai/policies/` en tu repositorio para que todo el equipo comparta los mismos estándares. A medida que descubráis nuevos modos de fallo, añade políticas y publícalas — todos recibirán la actualización en su próximo `git pull`. Con el tiempo, estas políticas se convierten en un estándar de calidad vivo que no deja de mejorar. +Confirma `.failproofai/policies/` en tu repositorio para que todo el equipo comparta los mismos estándares. A medida que tu equipo descubra nuevos modos de fallo, añade políticas y haz push — todos recibirán la actualización en su próximo `git pull`. Con el tiempo, estas políticas se convierten en un estándar de calidad vivo que no deja de mejorar. --- @@ -156,8 +157,8 @@ Toda la configuración y los registros permanecen en tu máquina: | `~/.failproofai/policies-config.json` | Configuración global de políticas | | `~/.failproofai/hook-activity.jsonl` | Historial de ejecución de hooks | | `~/.failproofai/hook.log` | Registro de depuración para errores de hooks personalizados | -| `.failproofai/policies-config.json` | Configuración por proyecto (confirmada en el repositorio) | -| `.failproofai/policies-config.local.json` | Overrides personales (incluido en .gitignore) | +| `.failproofai/policies-config.json` | Configuración por proyecto (confirmada en git) | +| `.failproofai/policies-config.local.json` | Sobreescrituras personales (en gitignore) | --- @@ -176,7 +177,7 @@ Elimina las entradas de hooks de `~/.claude/settings.json`. Los archivos de conf - Ámbitos y formato de los archivos de configuración + Alcances y formato del archivo de configuración diff --git a/docs/es/introduction.mdx b/docs/es/introduction.mdx index 3f34054f..b3eabeed 100644 --- a/docs/es/introduction.mdx +++ b/docs/es/introduction.mdx @@ -1,32 +1,32 @@ --- title: "Failproof AI" -description: "FailproofAI proporciona a los agentes de IA 39 políticas de fallos integradas que detectan bucles, filtraciones de secretos, llamadas destructivas a herramientas y más, con una sola instalación." +description: "FailproofAI ofrece a los agentes de IA 39 políticas de fallo integradas que detectan bucles, filtraciones de secretos, llamadas destructivas a herramientas y más, con una sola instalación." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -Hooks y políticas para la **gestión de fallos de IA**, **recuperación de errores** y **fiabilidad de LLM**. Mantén tus agentes de IA fiables y funcionando de forma autónoma en **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI** y el **Agents SDK**. +Hooks y políticas para **manejo de fallos de IA**, **recuperación de errores** y **fiabilidad de LLM**. Mantén tus agentes de IA fiables y funcionando de forma autónoma en **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, **Hermes** y el **Agents SDK**. -Los agentes de IA fallan de maneras predecibles. Ejecutan comandos destructivos, filtran secretos, se desvían de la tarea, quedan atrapados en bucles o hacen push directamente a main. Sin supervisión, los fallos pequeños se encadenan y desencadenan interrupciones del servicio, credenciales expuestas y trabajo perdido. +Los agentes de IA fallan de maneras predecibles. Ejecutan comandos destructivos, filtran secretos, se desvían de sus tareas, quedan atrapados en bucles o hacen push directamente a main. Sin supervisión, los pequeños fallos se convierten en interrupciones del servicio, credenciales expuestas y trabajo perdido. -FailproofAI resuelve esto mediante **políticas**. Estas reglas se enganchan a cada llamada de herramienta del agente para **detectar fallos**, **mitigarlos** (bloquear, instruir, sanear) y **alertarte** cuando algo requiere atención. Un panel de control local te permite revisar después cada llamada a herramienta, fallo del agente y acción de recuperación. +FailproofAI resuelve esto mediante **políticas**. Estas reglas se enganchan en cada llamada a herramientas del agente para **detectar fallos**, **mitigarlos** (bloquear, instruir, sanitizar) y **alertarte** cuando algo requiere tu atención. Un panel de control local te permite revisar después cada llamada a herramientas, cada fallo del agente y cada acción de recuperación. Ningún dato sale de tu máquina. -## Comenzar +## Primeros pasos - Bloquea comandos destructivos, evita la filtración de secretos, mantén los agentes dentro de los límites del proyecto y más. Todo listo desde el primer momento. + Bloquea comandos destructivos, evita filtraciones de secretos, mantén a los agentes dentro de los límites del proyecto y mucho más. Todo listo para usar desde el primer momento. - Escribe tus propias reglas en JavaScript con una sencilla API allow / deny / instruct. + Escribe tus propias reglas en JavaScript con una sencilla API de allow / deny / instruct. - Ve qué hicieron tus agentes mientras no estabas. Navega por sesiones, inspecciona llamadas a herramientas y revisa dónde se activaron las políticas. + Descubre qué hicieron tus agentes mientras no estabas. Navega por sesiones, inspecciona llamadas a herramientas y revisa dónde se activaron las políticas. diff --git a/docs/es/package-aliases.mdx b/docs/es/package-aliases.mdx index d80796d5..1be06f7b 100644 --- a/docs/es/package-aliases.mdx +++ b/docs/es/package-aliases.mdx @@ -10,32 +10,32 @@ El paquete npm canónico es **`failproofai`**: ```bash npm install -g failproofai -# o +# or bun add -g failproofai ``` --- -## Por qué somos dueños de los nombres alias +## Por qué registramos los nombres de alias -El typosquatting es un ataque común a la cadena de suministro en el que un actor malicioso registra un nombre de paquete que difiere en una sola tecla del paquete popular. Los usuarios desprevenidos que escriben mal el comando de instalación terminan ejecutando código controlado por el atacante con acceso completo al sistema — exactamente el tipo de amenaza que Failproof AI está diseñado para defender. +El typosquatting es un ataque común a la cadena de suministro en el que un actor malicioso registra un nombre de paquete que difiere en una sola tecla del paquete popular. Los usuarios que escriben mal el comando de instalación terminan ejecutando código controlado por el atacante con acceso total al sistema — exactamente el tipo de amenaza que Failproof AI está diseñado para combatir. -Para eliminar esta superficie de ataque, **registramos de forma preventiva todos los errores tipográficos comunes y variantes de formato** de `failproofai` en npm. Ninguno de estos nombres puede ser registrado por un tercero. Cada uno es un proxy ligero que instala y delega al paquete real `failproofai`. +Para eliminar esta superficie de ataque, **registramos de forma preventiva todos los errores tipográficos comunes y variantes de formato** de `failproofai` en npm. Ninguno de estos nombres puede ser registrado por terceros. Cada uno es un proxy ligero que instala y delega al paquete real `failproofai`. --- ## Alias registrados -**Variantes de formato** — distintas formas de escribir "failproof ai": +**Variantes de formato** — diferentes formas de escribir "failproof ai": | Paquete | Estado | |---------|--------| | `failproof` | ✅ Publicado | -| `failproof-ai` | ⏳ Pendiente de aprobación de npm | -| `fail-proof-ai` | ⏳ Pendiente de aprobación de npm | -| `failproof_ai` | ⏳ Pendiente de aprobación de npm | -| `fail_proof_ai` | ⏳ Pendiente de aprobación de npm | -| `fail-proofai` | ⏳ Pendiente de aprobación de npm | +| `failproof-ai` | ⏳ Pendiente de aprobación por npm | +| `fail-proof-ai` | ⏳ Pendiente de aprobación por npm | +| `failproof_ai` | ⏳ Pendiente de aprobación por npm | +| `fail_proof_ai` | ⏳ Pendiente de aprobación por npm | +| `fail-proofai` | ⏳ Pendiente de aprobación por npm | **Errores tipográficos `failprof*`** — falta una `o` en "proof": @@ -43,25 +43,25 @@ Para eliminar esta superficie de ataque, **registramos de forma preventiva todos |---------|--------| | `failprof` | ✅ Publicado | | `failprof-ai` | ✅ Publicado | -| `failprofai` | ⏳ Pendiente de aprobación de npm | -| `fail-prof-ai` | ⏳ Pendiente de aprobación de npm | -| `failprof_ai` | ⏳ Pendiente de aprobación de npm | +| `failprofai` | ⏳ Pendiente de aprobación por npm | +| `fail-prof-ai` | ⏳ Pendiente de aprobación por npm | +| `failprof_ai` | ⏳ Pendiente de aprobación por npm | -**Errores tipográficos `faliproof*`** — `a` e `i` transpuestas: +**Errores tipográficos `faliproof*`** — `a` e `i` intercambiadas: | Paquete | Estado | |---------|--------| | `faliproof` | ✅ Publicado | | `faliproof-ai` | ✅ Publicado | -| `faliproofai` | ⏳ Pendiente de aprobación de npm | +| `faliproofai` | ⏳ Pendiente de aprobación por npm | -> **¿Por qué pendiente?** La política anti-spam de npm bloquea nombres que se normalizan a la misma cadena que un paquete existente tras eliminar la puntuación y ejecutar comprobaciones de similitud. Nos hemos puesto en contacto con el soporte de npm para reservar estos nombres con fines anti-typosquatting. Se activarán una vez aprobados. +> **¿Por qué están pendientes?** La política anti-spam de npm bloquea nombres que se normalizan a la misma cadena que un paquete existente tras eliminar la puntuación y aplicar verificaciones de similitud. Hemos contactado con el soporte de npm para reservar estos nombres con fines anti-typosquatting. Se activarán una vez aprobados. -Puedes verificar que cualquier alias publicado es de nuestra propiedad: +Puedes verificar que cualquier alias publicado nos pertenece: ```bash npm info failproof -# Busca: "ExosphereHost Inc." en el campo maintainers +# Look for: "ExosphereHost Inc." in the maintainers field ``` --- @@ -71,9 +71,9 @@ npm info failproof Cada paquete alias: 1. Declara `failproofai` como dependencia — de modo que el paquete real (incluida la configuración de su hook `postinstall`) se ejecuta durante la instalación -2. Expone un binario con su propio nombre (por ejemplo, `failprof-ai`) que redirige todos los argumentos al binario `failproofai` +2. Expone un binario con su propio nombre (p. ej. `failprof-ai`) que reenvía todos los argumentos al binario `failproofai` -El proxy es un script de Node de dos líneas; no contiene lógica, no realiza llamadas de red ni recopila datos más allá de lo que hace `failproofai` por sí mismo. +El proxy es un script de Node de dos líneas; no contiene lógica adicional, no realiza llamadas de red ni recopila datos más allá de lo que hace `failproofai` por sí mismo. --- diff --git a/docs/es/testing.mdx b/docs/es/testing.mdx index 5c365299..482b838b 100644 --- a/docs/es/testing.mdx +++ b/docs/es/testing.mdx @@ -4,11 +4,11 @@ description: "Pruebas unitarias, pruebas E2E y helpers de prueba" icon: flask-vial --- -failproofai tiene dos conjuntos de pruebas: **pruebas unitarias** (rápidas, con mocks) y **pruebas de extremo a extremo** (invocaciones reales de subprocesos). +failproofai cuenta con dos suites de pruebas: **pruebas unitarias** (rápidas, con mocks) y **pruebas end-to-end** (invocaciones reales de subprocesos). --- -## Ejecutar pruebas +## Ejecutar las pruebas ```bash # Ejecutar todas las pruebas unitarias una vez @@ -23,7 +23,7 @@ bun run test:e2e # Verificar tipos sin compilar bunx tsc --noEmit -# Linting +# Lint bun run lint ``` @@ -31,7 +31,7 @@ bun run lint ## Pruebas unitarias -Las pruebas unitarias se encuentran en `__tests__/` y usan [Vitest](https://vitest.dev) con `jsdom`. +Las pruebas unitarias se encuentran en `__tests__/` y utilizan [Vitest](https://vitest.dev) con `jsdom`. ```text __tests__/ @@ -71,7 +71,7 @@ import { allow, deny } from "../../src/hooks/policy-types"; describe("block-sudo", () => { const policy = getBuiltinPolicies().find((p) => p.name === "block-sudo")!; - it("denies sudo commands", () => { + it("deniega comandos sudo", () => { const ctx = { eventType: "PreToolUse" as const, payload: {}, @@ -82,7 +82,7 @@ describe("block-sudo", () => { expect(policy.fn(ctx)).toEqual(deny("sudo command blocked by failproofai")); }); - it("allows non-sudo commands", () => { + it("permite comandos sin sudo", () => { const ctx = { eventType: "PreToolUse" as const, payload: {}, @@ -93,7 +93,7 @@ describe("block-sudo", () => { expect(policy.fn(ctx)).toEqual(allow()); }); - it("allows patterns in allowPatterns", () => { + it("permite patrones incluidos en allowPatterns", () => { const ctx = { eventType: "PreToolUse" as const, payload: {}, @@ -108,13 +108,13 @@ describe("block-sudo", () => { --- -## Pruebas de extremo a extremo +## Pruebas end-to-end -Las pruebas E2E invocan el binario real de `failproofai` como subproceso, envían un payload JSON por stdin y verifican la salida de stdout y el código de salida. Esto prueba el camino de integración completo que utiliza Claude Code. +Las pruebas E2E invocan el binario real de `failproofai` como subproceso, le envían un payload JSON por stdin y verifican la salida en stdout junto con el código de salida. Esto prueba el camino de integración completo que utiliza Claude Code. ### Configuración -Las pruebas E2E ejecutan el binario directamente desde el código fuente del repositorio. Antes de la primera ejecución, compila el bundle CJS que usan los archivos de hooks personalizados cuando importan desde `'failproofai'`: +Las pruebas E2E ejecutan el binario directamente desde el código fuente del repositorio. Antes de la primera ejecución, compila el bundle CJS que utilizan los archivos de hooks personalizados cuando importan desde `'failproofai'`: ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -133,17 +133,17 @@ Recompila `dist/` cada vez que modifiques la API pública de hooks (`src/hooks/c ```text __tests__/e2e/ helpers/ - hook-runner.ts # Inicia el binario, envía el JSON del payload, captura el código de salida + stdout + stderr + hook-runner.ts # Lanza el binario, envía el payload JSON y captura el código de salida + stdout + stderr fixture-env.ts # Directorios temporales aislados por prueba con archivos de configuración - payloads.ts # Fábricas de payloads fieles a Claude para cada tipo de evento + payloads.ts # Fábricas de payloads con la estructura real de Claude para cada tipo de evento hooks/ builtin-policies.e2e.test.ts # Cada política builtin con subproceso real custom-hooks.e2e.test.ts # Carga y evaluación de hooks personalizados - config-scopes.e2e.test.ts # Fusión de configuración entre project/local/global + config-scopes.e2e.test.ts # Fusión de configuración entre scopes: project/local/global policy-params.e2e.test.ts # Inyección de parámetros para cada política parametrizada ``` -### Usar los helpers E2E +### Uso de los helpers E2E **`FixtureEnv`** - entorno aislado por prueba: @@ -152,7 +152,7 @@ import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); // env.cwd - directorio temporal; pásalo como payload.cwd para cargar .failproofai/policies-config.json -// env.home - directorio home aislado; evita que se filtre el ~/.failproofai real +// env.home - directorio home aislado; evita que el ~/.failproofai real interfiera env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -162,7 +162,7 @@ env.writeConfig({ }); ``` -`createFixtureEnv()` registra la limpieza con `afterEach` automáticamente. +`createFixtureEnv()` registra la limpieza con `afterEach` de forma automática. **`runHook`** - invocar el binario: @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - fábricas de payloads predefinidos: +**`Payloads`** - fábricas de payloads predefinidas: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -201,7 +201,7 @@ import { runHook } from "../helpers/hook-runner"; import { Payloads } from "../helpers/payloads"; describe("block-rm-rf (E2E)", () => { - it("denies rm -rf", async () => { + it("deniega rm -rf", async () => { const env = createFixtureEnv(); env.writeConfig({ enabledPolicies: ["block-rm-rf"] }); @@ -215,7 +215,7 @@ describe("block-rm-rf (E2E)", () => { expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); }); - it("allows non-recursive rm", async () => { + it("permite rm sin recursión", async () => { const env = createFixtureEnv(); env.writeConfig({ enabledPolicies: ["block-rm-rf"] }); @@ -234,27 +234,27 @@ describe("block-rm-rf (E2E)", () => { ### Formatos de respuesta E2E | Decisión | Código de salida | stdout | -|----------|------------------|--------| +|----------|-----------------|--------| | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | -| Instruct (no Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | +| Instruct (sin Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | | Stop instruct | `2` | stdout vacío; motivo en stderr | | Allow | `0` | cadena vacía | ### Configuración de Vitest -Las pruebas E2E usan `vitest.config.e2e.mts` con: +Las pruebas E2E utilizan `vitest.config.e2e.mts` con: - `environment: "node"` - no se necesitan globales del navegador - `pool: "forks"` - aislamiento real de procesos (las pruebas lanzan subprocesos) - `testTimeout: 20_000` - 20 segundos por prueba (inicio del binario + evaluación del hook) -El pool `forks` es importante: los workers basados en hilos comparten `globalThis`, lo que puede interferir con las pruebas que lanzan subprocesos. Los forks basados en procesos evitan este problema. +El pool `forks` es importante: los workers basados en hilos comparten `globalThis`, lo que puede interferir con pruebas que lanzan subprocesos. Los forks basados en procesos evitan este problema. --- ## CI -La ejecución completa de CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) debe pasar antes de fusionar cambios. El conjunto de pruebas E2E se ejecuta como un job de CI independiente en paralelo. +La ejecución completa de CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) debe pasar antes de hacer merge. La suite E2E se ejecuta como un job de CI independiente en paralelo. -Consulta [Contributing](../CONTRIBUTING.md) para ver la lista de verificación completa previa a la fusión. \ No newline at end of file +Consulta [Contributing](../CONTRIBUTING.md) para ver el checklist completo previo al merge. \ No newline at end of file diff --git a/docs/fr/architecture.mdx b/docs/fr/architecture.mdx index c1bcf7b6..3690e24e 100644 --- a/docs/fr/architecture.mdx +++ b/docs/fr/architecture.mdx @@ -1,6 +1,6 @@ --- title: Architecture -description: "Fonctionnement interne du gestionnaire de hooks, du chargement de configuration et de l'évaluation des politiques" +description: "Fonctionnement interne du gestionnaire de hooks, du chargement de la configuration et de l'évaluation des politiques" icon: sitemap --- @@ -12,10 +12,10 @@ Ce document explique le fonctionnement interne de failproofai : comment le syst failproofai comporte deux sous-systèmes indépendants : -1. **Gestionnaire de hooks** - Un sous-processus CLI rapide que Claude Code invoque à chaque appel d'outil d'agent. Il évalue les politiques et retourne une décision. +1. **Gestionnaire de hooks** - Un sous-processus CLI rapide que Claude Code invoque à chaque appel d'outil de l'agent. Il évalue les politiques et retourne une décision. 2. **Moniteur d'agents (Tableau de bord)** - Une application web Next.js pour surveiller les sessions d'agents et gérer les politiques. -Les deux sous-systèmes partagent des fichiers de configuration dans `~/.failproofai/` et le répertoire `.failproofai/` du projet, mais ils s'exécutent comme des processus séparés et ne communiquent que via le système de fichiers. +Les deux sous-systèmes partagent des fichiers de configuration dans `~/.failproofai/` et le répertoire `.failproofai/` du projet, mais ils s'exécutent en tant que processus séparés et ne communiquent que via le système de fichiers. --- @@ -23,7 +23,7 @@ Les deux sous-systèmes partagent des fichiers de configuration dans `~/.failpro ### Intégration avec Claude Code -Lorsque vous exécutez `failproofai policies --install`, il inscrit des entrées comme celle-ci dans `~/.claude/settings.json` : +Lorsque vous exécutez `failproofai policies --install`, des entrées comme celle-ci sont écrites dans `~/.claude/settings.json` : ```json { @@ -44,9 +44,9 @@ Lorsque vous exécutez `failproofai policies --install`, il inscrit des entrées } ``` -Claude Code invoque ensuite `failproofai --hook PreToolUse` comme sous-processus avant chaque appel d'outil, en transmettant un payload JSON sur stdin. +Claude Code invoque ensuite `failproofai --hook PreToolUse` en tant que sous-processus avant chaque appel d'outil, en transmettant une charge utile JSON sur stdin. -### Format du payload +### Format de la charge utile ```json { @@ -60,9 +60,9 @@ Claude Code invoque ensuite `failproofai --hook PreToolUse` comme sous-processus } ``` -Pour les événements `PostToolUse`, le payload contient également `tool_result` avec la sortie de l'outil. +Pour les événements `PostToolUse`, la charge utile contient également `tool_result` avec la sortie de l'outil. -Le gestionnaire applique une limite de 1 Mo sur stdin. Les payloads dépassant cette limite sont ignorés et toutes les politiques autorisent implicitement. +Le gestionnaire impose une limite de 1 Mo sur stdin. Les charges utiles dépassant cette taille sont ignorées et toutes les politiques autorisent implicitement. ### Format de réponse @@ -94,9 +94,9 @@ Le gestionnaire applique une limite de 1 Mo sur stdin. Les payloads dépassant c } ``` -**Instruction sur événement Stop :** +**Instruction pour l'événement Stop :** - Code de sortie : `2` -- La raison est écrite sur stderr (et non stdout) +- La raison est écrite sur stderr (pas sur stdout) **Autorisation :** - Code de sortie : `0` @@ -104,7 +104,7 @@ Le gestionnaire applique une limite de 1 Mo sur stdin. Les payloads dépassant c **Autorisation avec message :** -`allow(message)` permet à une politique d'envoyer du contexte informatif à Claude même lorsque l'opération est autorisée. Le gestionnaire de hooks écrit le JSON suivant sur **stdout** (et non dans un fichier de configuration — il s'agit de la réponse du gestionnaire à Claude Code, au même titre que les réponses de refus et d'instruction ci-dessus) : +`allow(message)` permet à une politique d'envoyer du contexte informatif à Claude même lorsque l'opération est autorisée. Le gestionnaire de hooks écrit le JSON suivant sur **stdout** (pas dans un fichier de configuration — c'est la réponse du gestionnaire à Claude Code, tout comme les réponses de refus et d'instruction ci-dessus) : ```json // Written to stdout by the hook handler process @@ -115,8 +115,8 @@ Le gestionnaire applique une limite de 1 Mo sur stdin. Les payloads dépassant c } ``` - Code de sortie : `0` (l'opération est autorisée) -- Lorsque plusieurs politiques retournent `allow` avec un message, leurs messages sont concaténés avec des sauts de ligne en une seule chaîne `additionalContext` -- Si aucune politique ne fournit de message, stdout est vide (comportement inchangé) +- Lorsque plusieurs politiques retournent `allow` avec un message, leurs messages sont joints par des sauts de ligne en une seule chaîne `additionalContext` +- Si aucune politique ne fournit de message, stdout est vide (comme avant) ### Pipeline de traitement @@ -124,22 +124,22 @@ Le gestionnaire applique une limite de 1 Mo sur stdin. Les payloads dépassant c ```text stdin JSON - → parse payload (max 1 MB) - → extract session metadata (session_id, cwd, tool_name, tool_input, etc.) - → readMergedHooksConfig(cwd) ← merges project + local + global config - → register enabled builtin policies with resolved params - → load custom policies from customPoliciesPath (if set) - → register custom policies into policy registry - → evaluate all policies (builtins first, then custom) - → first deny short-circuits - → instruct decisions accumulate - → allow messages accumulate - → write JSON decision to stdout - → persist event to ~/.failproofai/hook-activity.jsonl - → exit + → analyse de la charge utile (max 1 Mo) + → extraction des métadonnées de session (session_id, cwd, tool_name, tool_input, etc.) + → readMergedHooksConfig(cwd) ← fusionne la config projet + locale + globale + → enregistrement des politiques intégrées activées avec les paramètres résolus + → chargement des politiques personnalisées depuis customPoliciesPath (si défini) + → enregistrement des politiques personnalisées dans le registre de politiques + → évaluation de toutes les politiques (intégrées d'abord, puis personnalisées) + → le premier refus court-circuite + → les décisions d'instruction s'accumulent + → les messages d'autorisation s'accumulent + → écriture de la décision JSON sur stdout + → persistance de l'événement dans ~/.failproofai/hook-activity.jsonl + → sortie ``` -L'ensemble du processus s'exécute en moins de 100 ms pour des payloads typiques, sans aucun appel LLM. +L'ensemble du processus s'exécute en moins de 100 ms pour les charges utiles classiques, sans aucun appel LLM. --- @@ -154,7 +154,7 @@ L'ensemble du processus s'exécute en moins de 100 ms pour des payloads typiques ``` Logique de fusion : -- `enabledPolicies` - union dédupliquée des trois fichiers +- `enabledPolicies` - union dédupliquée sur les trois fichiers - `policyParams` - par clé de politique, le premier fichier qui la définit l'emporte entièrement - `customPoliciesPath` - le premier fichier qui la définit l'emporte - `llm` - le premier fichier qui la définit l'emporte @@ -173,20 +173,20 @@ Pour chaque politique : 2. Lire `policyParams[policy.name]` depuis la configuration fusionnée. 3. Fusionner les valeurs fournies par l'utilisateur par-dessus les valeurs par défaut du schéma pour produire `ctx.params`. 4. Appeler `policy.fn(ctx)` avec le contexte résolu. -5. Si le résultat est `deny`, s'arrêter immédiatement et retourner cette décision. +5. Si le résultat est `deny`, arrêter immédiatement et retourner cette décision. 6. Si le résultat est `instruct`, accumuler le message et continuer. 7. Si le résultat est `allow`, passer à la politique suivante. -Une fois toutes les politiques exécutées : +Après l'exécution de toutes les politiques : - Si un `deny` a été retourné, émettre la réponse de refus. - Si des retours `instruct` ont été collectés, émettre une seule réponse d'instruction avec tous les messages joints. -- Sinon, émettre une réponse d'autorisation (stdout vide, code de sortie 0). +- Sinon, émettre une réponse d'autorisation (stdout vide, sortie 0). --- ## Politiques intégrées -`src/hooks/builtin-policies.ts` définit l'ensemble des 39 politiques intégrées sous forme d'objets `BuiltinPolicyDefinition` : +`src/hooks/builtin-policies.ts` définit les 39 politiques intégrées en tant qu'objets `BuiltinPolicyDefinition` : ```typescript interface BuiltinPolicyDefinition { @@ -204,15 +204,15 @@ interface BuiltinPolicyDefinition { } ``` -Les politiques qui acceptent des `params` déclarent un `PolicyParamsSchema` avec les types et les valeurs par défaut de chaque paramètre. L'évaluateur de politiques injecte les valeurs résolues dans `ctx.params` avant d'appeler `fn`. Les fonctions de politique lisent `ctx.params` sans vérification de nullité, car les valeurs par défaut sont toujours appliquées en premier. +Les politiques qui acceptent des `params` déclarent un `PolicyParamsSchema` avec les types et valeurs par défaut de chaque paramètre. L'évaluateur de politiques injecte les valeurs résolues dans `ctx.params` avant d'appeler `fn`. Les fonctions de politique lisent `ctx.params` sans vérification de nullité car les valeurs par défaut sont toujours appliquées en premier. -La correspondance de motifs dans les politiques utilise des tokens de commande analysés (argv), et non une correspondance de chaîne brute. Cela empêche le contournement par injection d'opérateurs shell (par exemple, un motif pour `sudo systemctl status *` ne peut pas être contourné en ajoutant `; rm -rf /` à la commande). +La correspondance de motifs au sein des politiques utilise des jetons de commande analysés (argv), et non une correspondance de chaînes brutes. Cela empêche le contournement via l'injection d'opérateurs shell (par exemple, un motif pour `sudo systemctl status *` ne peut pas être contourné en ajoutant `; rm -rf /` à la commande). --- ## Politiques personnalisées -`src/hooks/custom-hooks-registry.ts` implémente un registre basé sur `globalThis` : +`src/hooks/custom-hooks-registry.ts` implémente un registre adossé à `globalThis` : ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -225,25 +225,25 @@ export function getCustomHooks(): CustomHook[] { ... } export function clearCustomHooks(): void { ... } // used in tests ``` -`src/hooks/custom-hooks-loader.ts` charge le fichier de politiques de l'utilisateur : +`src/hooks/custom-hooks-loader.ts` charge le fichier de politique de l'utilisateur : 1. Lire `customPoliciesPath` depuis la configuration ; ignorer si absent. -2. Résoudre en chemin absolu ; vérifier que le fichier existe. -3. Réécrire tous les imports `from "failproofai"` vers le chemin dist réel afin que `customPolicies` pointe vers le même registre `globalThis`. -4. Réécrire récursivement les imports locaux transitifs pour garantir la compatibilité ESM. +2. Résoudre vers un chemin absolu ; vérifier que le fichier existe. +3. Réécrire toutes les importations `from "failproofai"` vers le chemin dist réel afin que `customPolicies` se résolve vers le même registre `globalThis`. +4. Réécrire récursivement les importations locales transitives pour assurer la compatibilité ESM. 5. Écrire des fichiers `.mjs` temporaires et `import()` le fichier d'entrée. 6. Appeler `getCustomHooks()` pour récupérer les hooks enregistrés. 7. Nettoyer tous les fichiers temporaires dans un bloc `finally`. -En cas d'erreur (fichier introuvable, erreur de syntaxe, échec d'import), l'erreur est consignée dans `~/.failproofai/hook.log` et le chargeur retourne un tableau vide. Les politiques intégrées ne sont pas affectées. +En cas d'erreur (fichier introuvable, erreur de syntaxe, échec d'importation), l'erreur est consignée dans `~/.failproofai/hook.log` et le chargeur retourne un tableau vide. Les politiques intégrées ne sont pas affectées. -Les politiques personnalisées sont évaluées après toutes les politiques intégrées. Un `deny` d'une politique personnalisée court-circuite les politiques personnalisées suivantes (mais toutes les politiques intégrées ont déjà été exécutées à ce stade). +Les politiques personnalisées sont évaluées après toutes les politiques intégrées. Un `deny` d'une politique personnalisée court-circuite toujours les politiques personnalisées suivantes (mais toutes les politiques intégrées ont déjà été exécutées à ce stade). --- ## Journalisation de l'activité -Après chaque événement de hook, le gestionnaire ajoute une ligne JSONL dans `~/.failproofai/hook-activity.jsonl` : +Après chaque événement de hook, le gestionnaire ajoute une ligne JSONL à `~/.failproofai/hook-activity.jsonl` : ```json { @@ -258,7 +258,7 @@ Après chaque événement de hook, le gestionnaire ajoute une ligne JSONL dans ` } ``` -Une ligne par politique ayant rendu une décision autre qu'allow. Les décisions d'autorisation ne sont pas journalisées (pour maintenir la taille du fichier réduite). +Une ligne par politique ayant pris une décision autre que allow. Les décisions allow ne sont pas journalisées (pour garder le fichier compact). --- @@ -272,11 +272,11 @@ app/ projects/page.tsx ← Composant serveur : liste tous les projets Claude project/[name]/page.tsx ← Composant serveur : liste les sessions d'un projet project/[name]/session/ - [sessionId]/page.tsx ← Composant serveur : affiche la visionneuse de session + [sessionId]/page.tsx ← Composant serveur : affiche le visualiseur de session policies/page.tsx ← Composant client : gestion des politiques + journal d'activité actions/ - get-hooks-config.ts ← Lecture de la configuration + liste des politiques - update-hooks-config.ts ← Activation/désactivation des politiques + get-hooks-config.ts ← Lecture de la config + liste des politiques + update-hooks-config.ts ← Activation/désactivation d'une politique update-policy-params.ts ← Mise à jour des paramètres de politique get-hook-activity.ts ← Pagination/recherche dans le journal d'activité install-hooks-web.ts ← Installation/suppression des hooks depuis le navigateur @@ -286,16 +286,16 @@ app/ **Flux de données :** -- Les composants de page appellent `lib/projects.ts` et `lib/log-entries.ts` pour lire les données de projet et de session directement depuis le système de fichiers (pas de couche API pour les lectures). +- Les composants de page appellent `lib/projects.ts` et `lib/log-entries.ts` pour lire les données de projet/session directement depuis le système de fichiers (pas de couche API pour les lectures). - La page Politiques utilise des Server Actions pour toutes les mutations (activation, mise à jour des paramètres, installation/suppression). -- La visionneuse de session analyse le format de transcription JSONL de Claude et affiche une chronologie des messages et des appels d'outils. +- Le visualiseur de session analyse le format de transcript JSONL de Claude et affiche une chronologie des messages et appels d'outils. **Décisions de conception clés :** -- Pas de base de données — tout l'état persistant est dans des fichiers simples (`~/.failproofai/`, `~/.claude/projects/`). -- Server Actions pour les mutations — pas d'API REST nécessaire pour les opérations CRUD. -- React Server Components pour les pages de lecture — chargement initial plus rapide, pas de bundle client pour la récupération des données. -- Composants client uniquement là où l'interactivité est requise (bascules de politiques, recherche dans l'activité, visionneuse de logs). +- Pas de base de données - tout l'état persistant est dans des fichiers simples (`~/.failproofai/`, `~/.claude/projects/`). +- Server Actions pour les mutations - pas d'API REST nécessaire pour les opérations CRUD. +- React Server Components pour les pages de lecture - chargement initial plus rapide, pas de bundle client pour la récupération des données. +- Composants client uniquement là où l'interactivité est nécessaire (bascules de politiques, recherche d'activité, visualiseur de logs). --- @@ -304,7 +304,7 @@ app/ ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # Routeur CLI (hook / dashboard / install / etc.) +│ └── failproofai.mjs # Routeur CLI (hook / tableau de bord / install / etc.) ├── src/hooks/ │ ├── handler.ts # Pipeline d'événements de hook │ ├── builtin-policies.ts # 39 définitions de politiques @@ -312,21 +312,21 @@ failproofai/ │ ├── policy-registry.ts # Enregistrement et recherche de politiques │ ├── policy-types.ts # Interfaces TypeScript │ ├── hooks-config.ts # Chargement de configuration multi-niveaux -│ ├── custom-hooks-registry.ts # Registre de hooks basé sur globalThis +│ ├── custom-hooks-registry.ts # Registre de hooks adossé à globalThis │ ├── custom-hooks-loader.ts # Chargeur ESM pour les hooks JS utilisateur -│ ├── manager.ts # Opérations install / remove / list +│ ├── manager.ts # Opérations d'installation / suppression / listage │ ├── install-prompt.ts # Invite interactive de sélection de politiques -│ ├── hook-logger.ts # Journalisation dans hook.log -│ ├── hook-activity-store.ts # Persistance de l'activité dans hook-activity.jsonl +│ ├── hook-logger.ts # Journalisation vers hook.log +│ ├── hook-activity-store.ts # Persistance de l'activité vers hook-activity.jsonl │ └── llm-client.ts # Client API LLM (pour les politiques alimentées par IA) ├── app/ # Tableau de bord Next.js (pages + server actions) ├── lib/ # Utilitaires partagés │ ├── projects.ts # Énumération des projets Claude depuis le système de fichiers -│ ├── log-entries.ts # Analyse du format JSONL des transcriptions Claude +│ ├── log-entries.ts # Analyse du format JSONL de transcript Claude │ ├── paths.ts # Résolution des chemins système │ └── ... ├── components/ # Composants React UI partagés -├── contexts/ # Fournisseurs de contexte React (thème, actualisation auto, télémétrie) +├── contexts/ # Fournisseurs de contexte React (thème, actualisation automatique, télémétrie) ├── examples/ # Exemples de fichiers de hooks personnalisés └── __tests__/ # Tests unitaires et E2E ``` \ No newline at end of file diff --git a/docs/fr/built-in-policies.mdx b/docs/fr/built-in-policies.mdx index 612d6c78..edefb9c4 100644 --- a/docs/fr/built-in-policies.mdx +++ b/docs/fr/built-in-policies.mdx @@ -1,10 +1,10 @@ --- title: Politiques intégrées -description: "Les 39 politiques intégrées qui interceptent les modes de défaillance courants des agents" +description: "Les 39 politiques intégrées qui interceptent les modes d'échec courants des agents" icon: shield --- -failproofai est livré avec 39 politiques intégrées qui interceptent les modes de défaillance courants des agents. Chaque politique se déclenche sur un type d'événement hook et un nom d'outil spécifiques. Dix-neuf politiques acceptent des paramètres permettant d'affiner leur comportement sans écrire de code. Cinq politiques de workflow imposent un pipeline commit → push → PR → CI avant que Claude ne s'arrête. +failproofai est livré avec 39 politiques intégrées qui interceptent les modes d'échec courants des agents. Chaque politique se déclenche sur un type d'événement hook et un nom d'outil spécifiques. Dix-neuf politiques acceptent des paramètres permettant d'affiner leur comportement sans écrire de code. Cinq politiques de workflow imposent un pipeline commit → push → PR → CI avant que Claude ne s'arrête. --- @@ -15,8 +15,8 @@ Les politiques sont regroupées par catégories : | Catégorie | Politiques | Type de hook | |----------|----------|-----------| | [Commandes dangereuses](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | -| [Commandes d'infrastructure](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [Secrets (assainisseurs)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [Commandes infra](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | +| [Secrets (sanitizers)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | | [Environnement](#environment) | block-env-files, protect-env-vars | PreToolUse | | [Accès aux fichiers](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | @@ -26,14 +26,14 @@ Les politiques sont regroupées par catégories : | [Workflow](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | - **`block-`** — empêche l'agent de poursuivre. -- **`warn-`** — fournit à l'agent un contexte supplémentaire pour qu'il puisse se corriger lui-même. -- **`sanitize-`** — expurge les données sensibles de la sortie de l'outil avant que l'agent ne les voie. +- **`warn-`** — fournit à l'agent du contexte supplémentaire pour qu'il puisse se corriger. +- **`sanitize-`** — nettoie les données sensibles de la sortie d'un outil avant que l'agent ne les voie. ### Espaces de noms -Chaque politique occupe un emplacement `/`. Les politiques intégrées appartiennent à l'espace de noms **`failproofai/`** — par exemple, `failproofai/sanitize-jwt`. L'espace de noms évite les collisions lorsque vous chargez également des politiques personnalisées ou tierces avec des noms courts similaires. +Chaque politique occupe un emplacement `/`. Les politiques intégrées appartiennent à l'espace de noms **`failproofai/`** — par exemple, `failproofai/sanitize-jwt`. L'espace de noms évite les collisions lorsque vous chargez également des politiques personnalisées ou tierces portant des noms courts similaires. -Dans votre configuration, vous pouvez faire référence à une politique intégrée par son nom court ou son nom qualifié ; les deux formes correspondent à la même politique : +Dans votre configuration, vous pouvez désigner une politique intégrée par son nom court ou son nom qualifié ; les deux formes pointent vers la même politique : ```json { @@ -44,27 +44,27 @@ Dans votre configuration, vous pouvez faire référence à une politique intégr } ``` -Si un nom ne contient pas de `/`, failproofai le considère comme appartenant à l'espace de noms par défaut `failproofai`. Les noms qui contiennent déjà un `/` (ex. `myorg/foo`, `custom/my-hook`) sont conservés tels quels. +Si un nom ne contient pas de `/`, failproofai considère qu'il appartient à l'espace de noms par défaut `failproofai`. Les noms contenant déjà un `/` (par ex. `myorg/foo`, `custom/my-hook`) sont conservés tels quels. - **`require-`** — bloque l'événement Stop jusqu'à ce que les conditions soient remplies. --- -Toutes les politiques prennent en charge un champ optionnel `hint` dans `policyParams`. Ce conseil est ajouté au message deny ou instruct que voit Claude, fournissant des indications concrètes sans modifier le code de la politique. Fonctionne avec les politiques intégrées, personnalisées et de convention. Voir [Configuration → hint](/fr/configuration#hint-cross-cutting) pour plus de détails. +Toute politique supporte un champ `hint` optionnel dans `policyParams`. Le hint est ajouté au message deny ou instruct que Claude reçoit, offrant des conseils pratiques sans modifier le code de la politique. Fonctionne avec les politiques intégrées, personnalisées et de convention. Voir [Configuration → hint](/fr/configuration#hint-cross-cutting) pour les détails. --- ## Commandes dangereuses -Empêche les agents d'exécuter des opérations difficiles à annuler ou pouvant endommager le système hôte. +Empêche les agents d'exécuter des opérations difficiles à annuler ou susceptibles d'endommager le système hôte. ### `block-sudo` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse toute commande `sudo`. +**Par défaut :** Bloque toute commande `sudo`. -Bloque les invocations qui incluent le mot-clé `sudo`. La correspondance de motifs est effectuée sur les tokens de commande analysés, et non sur la chaîne brute, pour éviter les contournements par injection d'opérateurs shell. +Bloque les invocations contenant le mot-clé `sudo`. La correspondance de motif s'effectue sur les tokens de commande analysés, et non sur la chaîne brute, afin d'empêcher les contournements par injection d'opérateurs shell. **Paramètres :** @@ -84,10 +84,10 @@ Bloque les invocations qui incluent le mot-clé `sudo`. La correspondance de mot } ``` -Avec cette configuration, `sudo systemctl status nginx` est autorisé, mais `sudo rm /etc/hosts` est refusé. +Avec cette configuration, `sudo systemctl status nginx` est autorisé, mais `sudo rm /etc/hosts` est bloqué. -Les motifs sont comparés aux tokens analysés, et non à la chaîne de commande brute. Cela empêche les contournements via des opérateurs shell ajoutés (ex. `sudo systemctl status x; rm -rf /` ne correspond pas à `sudo systemctl status *`). +Les motifs sont comparés aux tokens analysés, et non à la chaîne de commande brute. Cela empêche les contournements par opérateurs shell ajoutés (par ex. `sudo systemctl status x; rm -rf /` ne correspond pas à `sudo systemctl status *`). --- @@ -95,13 +95,13 @@ Les motifs sont comparés aux tokens analysés, et non à la chaîne de commande ### `block-rm-rf` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse `rm -rf`, `rm -fr` et les formes similaires de suppression récursive. +**Par défaut :** Bloque `rm -rf`, `rm -fr` et les formes similaires de suppression récursive. **Paramètres :** | Paramètre | Type | Défaut | Description | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Chemins dont la suppression récursive est autorisée (ex. `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Chemins dont la suppression récursive est autorisée (par ex. `/tmp`). | **Exemple :** @@ -120,7 +120,7 @@ Les motifs sont comparés aux tokens analysés, et non à la chaîne de commande ### `block-curl-pipe-sh` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse `curl | bash`, `curl | sh`, `wget | bash` et les motifs similaires. +**Par défaut :** Bloque `curl | bash`, `curl | sh`, `wget | bash` et les motifs similaires. Aucun paramètre. @@ -129,22 +129,22 @@ Aucun paramètre. ### `block-failproofai-commands` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse les commandes qui désinstalleraient ou désactiveraient failproofai lui-même (ex. `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Par défaut :** Bloque les commandes qui désinstalleraient ou désactiveraient failproofai lui-même (par ex. `npm uninstall failproofai`, `failproofai policies --uninstall`). Aucun paramètre. --- -## Commandes d'infrastructure +## Commandes infra -Empêche les agents de code d'exécuter des CLI d'infrastructure ou de déclencher des pipelines CI/CD. Toutes les politiques de cette catégorie sont **opt-in** (`defaultEnabled: false`) — les agents ayant légitimement besoin d'appeler `kubectl`, `terraform`, etc. ne seront pas perturbés sauf si vous activez la politique. Une fois activée, toute invocation du CLI correspondant est refusée, sauf si la commande correspond à une entrée dans `allowPatterns`. +Empêche les agents de code d'exécuter des CLI d'infrastructure ou de déclencher des pipelines CI/CD. Toutes les politiques de cette catégorie sont **opt-in** (`defaultEnabled: false`) — les agents qui ont légitimement besoin d'appeler `kubectl`, `terraform`, etc. ne seront pas perturbés, sauf si vous activez explicitement la politique. Une fois activée, toute invocation du CLI correspondant est bloquée, à moins que la commande ne corresponde à une entrée de `allowPatterns`. -La grammaire des motifs est la même que pour [`block-sudo`](#block-sudo) : les tokens sont comparés à l'argv analysé, `*` est un joker pour un token, et toute commande contenant un opérateur shell autonome (`&&`, `||`, `|`, `;`) ou un token avec des métacaractères shell intégrés est rejetée avant la vérification de la liste d'autorisation afin d'éviter les injections. +La grammaire des motifs est identique à celle de [`block-sudo`](#block-sudo) : les tokens sont comparés aux argv analysés, `*` est un joker pour un token, et toute commande contenant un opérateur shell autonome (`&&`, `||`, `|`, `;`) ou un token avec des métacaractères shell intégrés est rejetée avant la vérification de la liste d'autorisation, afin d'éviter les contournements par injection. ### `block-kubectl` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse toute invocation de `kubectl`. +**Par défaut :** Bloque toute invocation de `kubectl`. **Paramètres :** @@ -164,14 +164,14 @@ La grammaire des motifs est la même que pour [`block-sudo`](#block-sudo) : les } ``` -Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply -f deploy.yaml` est refusé. +Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply -f deploy.yaml` est bloqué. --- ### `block-terraform` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse toute invocation de `terraform` ou `tofu` (OpenTofu). +**Par défaut :** Bloque toute invocation de `terraform` ou `tofu` (OpenTofu). **Paramètres :** @@ -196,13 +196,13 @@ Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply - ### `block-aws-cli` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse toute invocation du CLI `aws`. +**Par défaut :** Bloque toute invocation du CLI `aws`. **Paramètres :** | Paramètre | Type | Défaut | Description | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes du CLI aws autorisés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes aws CLI autorisés. | **Exemple :** @@ -221,7 +221,7 @@ Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply - ### `block-gcloud` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse toute invocation du CLI `gcloud` (Google Cloud). +**Par défaut :** Bloque toute invocation du CLI `gcloud` (Google Cloud). **Paramètres :** @@ -246,13 +246,13 @@ Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply - ### `block-az-cli` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse toute invocation du CLI `az` (Azure). +**Par défaut :** Bloque toute invocation du CLI `az` (Azure). **Paramètres :** | Paramètre | Type | Défaut | Description | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes du CLI az autorisés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes az CLI autorisés. | **Exemple :** @@ -271,7 +271,7 @@ Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply - ### `block-helm` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse toute invocation de `helm`. +**Par défaut :** Bloque toute invocation de `helm`. **Paramètres :** @@ -296,7 +296,7 @@ Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply - ### `block-gh-pipeline` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse les sous-commandes CLI `gh` suivantes qui modifient l'état ou déclenchent des pipelines : +**Par défaut :** Bloque les sous-commandes `gh` CLI suivantes qui modifient l'état ou déclenchent des pipelines : - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -305,13 +305,13 @@ Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply - - `gh cache delete` - `gh secret set`, `gh secret delete` -Les sous-commandes `gh` en lecture seule telles que `gh pr view`, `gh pr list`, `gh run list`, `gh release view` et `gh api repos/.../...` **ne sont pas** couvertes par cette politique — elles sont couramment nécessaires pour les vérifications de workflow (y compris le `require-ci-green-before-stop` de failproofai). +Les sous-commandes `gh` en lecture seule telles que `gh pr view`, `gh pr list`, `gh run list`, `gh release view` et `gh api repos/.../...` ne sont **pas** visées par cette politique — elles sont couramment nécessaires pour les vérifications de workflow (y compris `require-ci-green-before-stop` de failproofai). **Paramètres :** | Paramètre | Type | Défaut | Description | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Invocations scriptées spécifiques à autoriser même si elles seraient normalement refusées. | +| `allowPatterns` | `string[]` | `[]` | Invocations scriptées spécifiques à autoriser même si elles seraient normalement bloquées. | **Exemple :** @@ -327,9 +327,9 @@ Les sous-commandes `gh` en lecture seule telles que `gh pr view`, `gh pr list`, --- -## Secrets (assainisseurs) +## Secrets (sanitizers) -Empêche les agents de laisser fuiter des identifiants dans leur contexte ou leur sortie. Les politiques d'assainissement se déclenchent sur les événements **PostToolUse**. Lorsque Claude exécute une commande Bash, lit un fichier ou appelle un outil, ces politiques inspectent la sortie avant qu'elle ne soit retournée à Claude. Si un motif de secret est détecté, la politique retourne une décision deny qui empêche la sortie d'être renvoyée. +Empêche les agents de faire fuiter des identifiants dans leur contexte ou leur sortie. Les politiques sanitizer se déclenchent sur les événements **PostToolUse**. Lorsque Claude exécute une commande Bash, lit un fichier ou appelle un outil quelconque, ces politiques inspectent la sortie avant qu'elle ne soit renvoyée à Claude. Si un motif secret est détecté, la politique retourne une décision deny qui empêche la transmission de la sortie. ### `sanitize-jwt` @@ -371,7 +371,7 @@ Aucun paramètre. ### `sanitize-connection-strings` **Événement :** PostToolUse (tous les outils) -**Par défaut :** Masque les chaînes de connexion de bases de données contenant des identifiants intégrés (ex. `postgresql://user:password@host/db`). +**Par défaut :** Masque les chaînes de connexion aux bases de données contenant des identifiants intégrés (par ex. `postgresql://user:password@host/db`). Aucun paramètre. @@ -389,7 +389,7 @@ Aucun paramètre. ### `sanitize-bearer-tokens` **Événement :** PostToolUse (tous les outils) -**Par défaut :** Masque les en-têtes `Authorization: Bearer ` dont le token fait 20 caractères ou plus. +**Par défaut :** Masque les en-têtes `Authorization: Bearer ` dont le token comporte 20 caractères ou plus. Aucun paramètre. @@ -402,7 +402,7 @@ Protège la configuration d'environnement sensible contre la lecture ou l'exposi ### `block-env-files` **Événement :** PreToolUse (Bash, Read) -**Par défaut :** Refuse la lecture des fichiers `.env` via `cat .env`, les appels à l'outil `Read` avec `.env` comme chemin de fichier, etc. +**Par défaut :** Bloque la lecture des fichiers `.env` via `cat .env`, les appels à l'outil `Read` avec `.env` comme chemin de fichier, etc. Ne bloque pas `.envrc` ni les autres fichiers liés à l'environnement — uniquement les fichiers nommés exactement `.env`. @@ -413,7 +413,7 @@ Aucun paramètre. ### `protect-env-vars` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse les commandes qui affichent les variables d'environnement : `printenv`, `env`, `echo $VAR`. +**Par défaut :** Bloque les commandes qui affichent les variables d'environnement : `printenv`, `env`, `echo $VAR`. Aucun paramètre. @@ -426,7 +426,7 @@ Maintient les agents dans les limites du projet et à l'écart des fichiers sens ### `block-read-outside-cwd` **Événement :** PreToolUse (Read, Bash) -**Par défaut :** Refuse la lecture de fichiers en dehors de la racine du projet. La limite est `CLAUDE_PROJECT_DIR` (définie une fois par session par Claude Code), avec un repli sur le répertoire de travail courant de la session si cette variable n'est pas définie. L'utilisation de la racine du projet plutôt que du `cwd` actif garantit que la limite reste stable même après qu'un `cd` de Claude vers un sous-répertoire. +**Par défaut :** Bloque la lecture de fichiers situés en dehors de la racine du projet. La limite est définie par `CLAUDE_PROJECT_DIR` (défini une fois par session par Claude Code), avec repli sur le répertoire de travail courant de la session si cette variable n'est pas définie. L'utilisation de la racine du projet plutôt que du `cwd` en temps réel garantit une limite stable, même après que Claude se soit déplacé dans un sous-répertoire avec `cd`. **Paramètres :** @@ -451,7 +451,7 @@ Maintient les agents dans les limites du projet et à l'écart des fichiers sens ### `block-secrets-write` **Événement :** PreToolUse (Write, Edit) -**Par défaut :** Refuse les écritures dans les fichiers couramment utilisés pour les clés privées et les certificats : `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Par défaut :** Bloque les écritures dans les fichiers couramment utilisés pour les clés privées et les certificats : `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Paramètres :** @@ -475,12 +475,12 @@ Maintient les agents dans les limites du projet et à l'écart des fichiers sens ## Git -Évite les pushs accidentels, les force-pushs et les erreurs de branche difficiles à annuler. +Prévient les pushs accidentels, les force-pushs et les erreurs de branche difficiles à annuler. ### `block-push-master` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse `git push origin main` et `git push origin master`. +**Par défaut :** Bloque `git push origin main` et `git push origin master`. **Paramètres :** @@ -501,7 +501,7 @@ Maintient les agents dans les limites du projet et à l'écart des fichiers sens ``` -Pour autoriser le push vers toutes les branches (ce qui désactive effectivement cette politique sans la retirer de `enabledPolicies`), définissez `protectedBranches: []`. +Pour autoriser le push sur toutes les branches (ce qui revient à désactiver cette politique sans la retirer de `enabledPolicies`), définissez `protectedBranches: []`. --- @@ -509,22 +509,22 @@ Pour autoriser le push vers toutes les branches (ce qui désactive effectivement ### `block-work-on-main` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse `git commit`, `git merge`, `git rebase` et `git cherry-pick` lorsque l'arbre de travail est sur `main` ou `master`. La création et le changement de branche (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) ne sont pas affectés. +**Par défaut :** Bloque `git commit`, `git merge`, `git rebase` et `git cherry-pick` lorsque l'arbre de travail est sur `main` ou `master`. La création et le changement de branche (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) ne sont pas affectés. **Paramètres :** | Paramètre | Type | Défaut | Description | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Noms de branches sur lesquelles commit/merge/rebase/cherry-pick est refusé. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Noms de branches sur lesquelles commit/merge/rebase/cherry-pick est bloqué. | --- ### `block-force-push` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse `git push --force` et `git push -f`. +**Par défaut :** Bloque `git push --force` et `git push -f`. -Aucun paramètre spécifique à cette politique. Utilisez le [`hint`](/fr/configuration#hint-cross-cutting) transversal pour suggérer des alternatives : +Aucun paramètre spécifique à la politique. Utilisez le [`hint`](/fr/configuration#hint-cross-cutting) transversal pour suggérer des alternatives : ```json { @@ -559,7 +559,7 @@ Aucun paramètre. ### `warn-all-files-staged` **Événement :** PreToolUse (Bash) -**Par défaut :** Demande à Claude de vérifier ce qu'il indexe lorsqu'il exécute `git add -A` ou `git add .`. Ne bloque pas la commande. +**Par défaut :** Demande à Claude de vérifier ce qu'il indexe lors de l'exécution de `git add -A` ou `git add .`. Ne bloque pas la commande. Aucun paramètre. @@ -567,12 +567,12 @@ Aucun paramètre. ## Base de données -Détecte les opérations SQL destructives avant qu'elles ne s'exécutent sur votre base de données. +Intercepte les opérations SQL destructives avant qu'elles ne s'exécutent sur votre base de données. ### `warn-destructive-sql` **Événement :** PreToolUse (Bash) -**Par défaut :** Demande à Claude de confirmer avant d'exécuter du SQL contenant `DROP TABLE`, `DROP DATABASE` ou `DELETE` sans clause `WHERE`. +**Par défaut :** Demande à Claude de confirmer avant d'exécuter un SQL contenant `DROP TABLE`, `DROP DATABASE` ou `DELETE` sans clause `WHERE`. Aucun paramètre. @@ -589,7 +589,7 @@ Aucun paramètre. ## Avertissements -Fournit aux agents un contexte supplémentaire avant des opérations potentiellement risquées mais non destructives. +Fournit aux agents du contexte supplémentaire avant des opérations potentiellement risquées mais non destructives. ### `warn-large-file-write` @@ -615,7 +615,7 @@ Fournit aux agents un contexte supplémentaire avant des opérations potentielle ``` -Le gestionnaire de hook impose une limite de 1 Mo sur les charges utiles stdin. Pour tester cette politique avec un contenu de petite taille, définissez `thresholdKb` à une valeur bien inférieure à 1024. +Le gestionnaire de hook impose une limite de 1 Mo sur les payloads stdin. Pour tester cette politique avec un contenu de petite taille, définissez `thresholdKb` à une valeur bien inférieure à 1024. --- @@ -654,14 +654,14 @@ Impose les gestionnaires de paquets que l'agent est autorisé à utiliser. ### `prefer-package-manager` **Événement :** PreToolUse (Bash) -**Par défaut :** Désactivé. Lorsqu'activé, bloque toute commande de gestionnaire de paquets absent de la liste `allowed` et demande à Claude de réécrire la commande en utilisant un gestionnaire autorisé. +**Par défaut :** Désactivé. Lorsqu'il est activé, bloque toute commande d'un gestionnaire de paquets absent de la liste `allowed` et indique à Claude de réécrire la commande en utilisant un gestionnaire autorisé. Détecte : pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | Paramètre | Type | Défaut | Description | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | Noms de gestionnaires de paquets autorisés. Tout gestionnaire détecté absent de cette liste est bloqué. Si vide, la politique est sans effet. | -| `blocked` | string[] | `[]` | Noms de gestionnaires supplémentaires à bloquer en plus de la liste intégrée (ex. `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | Noms de gestionnaires de paquets autorisés. Tout gestionnaire détecté absent de cette liste est bloqué. Si vide, la politique n'a aucun effet. | +| `blocked` | string[] | `[]` | Noms de gestionnaires supplémentaires à bloquer au-delà de la liste intégrée (par ex. `['pdm', 'pipx']`). | La liste de blocage intégrée couvre : pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Utilisez `blocked` pour ajouter des gestionnaires absents de cette liste. @@ -679,7 +679,7 @@ La liste de blocage intégrée couvre : pip, pip3, npm, npx, yarn, pnpm, pnpx, b } ``` -Avec cette configuration, `pip install flask` et `pdm install flask` sont tous deux refusés avec un message indiquant à Claude d'utiliser `uv` ou `bun` à la place. Les commandes comme `uv pip install flask` sont autorisées car `uv` est dans la liste d'autorisation et est vérifié en premier. +Avec cette configuration, `pip install flask` et `pdm install flask` sont tous deux bloqués avec un message indiquant à Claude d'utiliser `uv` ou `bun` à la place. Les commandes comme `uv pip install flask` sont autorisées car `uv` figure dans la liste d'autorisation et est vérifié en premier. --- @@ -698,40 +698,40 @@ Aucun paramètre. ## Workflow -Impose un workflow de fin de session discipliné. Ces politiques se déclenchent sur l'événement **Stop** et empêchent l'agent de s'arrêter jusqu'à ce que chaque condition soit remplie. Elles suivent une chaîne de dépendances naturelle : commit → push → PR → CI. Si une politique refuse, les politiques suivantes dans la chaîne sont ignorées (court-circuit sur deny). +Impose un workflow de fin de session discipliné. Ces politiques se déclenchent sur l'événement **Stop** et empêchent l'agent de s'arrêter tant que chaque condition n'est pas remplie. Elles suivent une chaîne de dépendance naturelle : commit → push → PR → CI. Si une politique refuse, les politiques suivantes dans la chaîne sont ignorées (court-circuit sur deny). -Toutes les politiques de workflow sont **fail-open** : si l'outil requis n'est pas disponible (ex. `gh` non installé, pas de remote git), la politique autorise avec un message informatif expliquant pourquoi la vérification a été ignorée. +Toutes les politiques de workflow sont **fail-open** : si l'outil requis n'est pas disponible (par ex. `gh` non installé, pas de remote git), la politique autorise avec un message informatif expliquant pourquoi la vérification a été ignorée. ### Sémantique Stop par CLI -L'application du Stop se présente légèrement différemment selon les sept CLI supportés, car chacun expose un contrat de hook différent pour signaler que l'agent a terminé. Le **résultat** est le même — l'agent ne peut pas s'arrêter tant qu'une barrière de workflow est en échec — mais les **mécanismes** diffèrent. Le tableau ci-dessous résume la situation ; seul Pi présente un comportement visible par l'utilisateur qui mérite d'être compris avant d'activer une politique `require-*-before-stop`. +L'application du Stop se présente légèrement différemment selon les sept CLI supportés, car chacun expose un contrat de hook "agent terminé" différent. Le **résultat** est le même — l'agent ne peut pas s'arrêter tant qu'une porte de workflow est en échec — mais les **mécanismes** diffèrent. Le tableau ci-dessous résume la situation ; seul Pi présente une particularité visible par l'utilisateur qu'il convient de comprendre avant d'activer une politique `require-*-before-stop`. -| CLI | Moment du déclenchement | Ce que vous voyez | +| CLI | Quand la porte se déclenche | Ce que vous voyez | |---|---|---| -| Claude Code | Même boucle d'agent, immédiatement | Claude continue de travailler — corrige le problème, puis tente de terminer à nouveau. Aucune interruption visible pour vous. | -| Codex | Même boucle d'agent, immédiatement | Identique à Claude. | -| GitHub Copilot CLI | Même boucle d'agent, immédiatement | Identique à Claude (utilise le canal de relance `{decision:"block", reason}` de Copilot — vérifié empiriquement avec Copilot CLI 1.0.41). | -| Cursor Agent | Même boucle d'agent, immédiatement | Identique à Claude (utilise le canal `{followup_message}` de Cursor — limité par `loop_limit`, 5 relances par défaut). | -| Gemini CLI | Même boucle d'agent, immédiatement | Identique à Claude (utilise le canal `{decision:"block", reason}` de Gemini sur `AfterAgent`). | -| OpenCode | Même boucle d'agent, immédiatement | Identique à Claude (utilise l'appel SDK `client.session.prompt(...)` d'OpenCode routé via `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **Tour utilisateur suivant** | **Pi s'arrête visiblement** lorsque la barrière se déclenche — sa boucle d'agent se termine et vous revenez au prompt. La barrière se déclenche alors la prochaine fois que vous soumettez un prompt : failproofai ajoute en tête une directive `MANDATORY ACTION REQUIRED` au prompt système de ce tour, demandant au LLM de compléter l'étape de workflow (commit, push, etc.) avant de faire ce que vous avez demandé. | +| Claude Code | Dans la même boucle agent, immédiatement | Claude continue de travailler — résout le problème, puis tente de terminer à nouveau. Aucune interruption visible pour vous. | +| Codex | Dans la même boucle agent, immédiatement | Identique à Claude. | +| GitHub Copilot CLI | Dans la même boucle agent, immédiatement | Identique à Claude (utilise le canal de relance `{decision:"block", reason}` de Copilot — vérifié empiriquement contre Copilot CLI 1.0.41). | +| Cursor Agent | Dans la même boucle agent, immédiatement | Identique à Claude (utilise le canal `{followup_message}` de Cursor — limité à `loop_limit`, 5 relances par défaut). | +| Gemini CLI | Dans la même boucle agent, immédiatement | Identique à Claude (utilise le canal `{decision:"block", reason}` de Gemini sur `AfterAgent`). | +| OpenCode | Dans la même boucle agent, immédiatement | Identique à Claude (utilise l'appel SDK `client.session.prompt(...)` d'OpenCode acheminé via `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **Au prochain tour utilisateur** | **Pi s'arrête visiblement** lorsque la porte se déclenche — sa boucle agent se termine et vous êtes renvoyé au prompt. La porte se déclenche ensuite la prochaine fois que vous soumettez un prompt : failproofai ajoute en tête du system prompt de ce tour une directive `MANDATORY ACTION REQUIRED`, demandant au LLM de compléter l'étape de workflow (commit, push, etc.) avant de faire ce que vous avez demandé. | -**Limitation de Pi.** L'`AgentEndEvent` de Pi (l'équivalent en amont du hook `Stop` de Claude) n'a pas de type Result — au moment où il se déclenche, la boucle d'agent de Pi a déjà quitté. Pi ne peut pas être forcé à réessayer la même boucle comme Claude / Copilot / Cursor / Gemini / OpenCode. failproofai déplace la barrière vers l'événement `before_agent_start` de Pi (qui se déclenche après le prochain prompt utilisateur) afin que la vérification du workflow soit toujours appliquée, mais au tour suivant plutôt qu'au tour courant. +**Limitation de Pi.** L'`AgentEndEvent` de Pi (l'équivalent upstream du hook `Stop` de Claude) n'a pas de type Result — au moment où il se déclenche, la boucle agent de Pi a déjà terminé. Pi ne peut pas être forcé à relancer la même boucle comme Claude / Copilot / Cursor / Gemini / OpenCode le peuvent. failproofai déplace la porte vers l'événement `before_agent_start` de Pi (qui se déclenche après le prochain prompt utilisateur) afin que la vérification de workflow s'applique quand même, simplement au tour suivant plutôt qu'au tour courant. **Ce que cela signifie en pratique :** -- Après l'arrêt de Pi, la raison du refus est capturée en mémoire, indexée par l'identifiant de session Pi. Le prochain prompt que vous soumettez dans le même processus Pi la consomme : le LLM voit la directive `MANDATORY ACTION REQUIRED` en tête de son prompt système, effectue le commit (ou le push / ouvre la PR / attend le CI), et ne continue avec votre demande qu'ensuite. La raison de refus capturée est à usage unique — une fois consommée, la barrière est levée. -- La barrière est liée à la durée de vie du processus Pi. Si vous faites `Ctrl+C` sur Pi ou quittez entre les tours, l'entrée en mémoire est supprimée avec le processus et la barrière est manquée. Claude, Copilot, Cursor, Gemini et OpenCode ont la même contrainte (tuer l'agent fait manquer la barrière) — Pi le rend simplement plus visible car l'agent quitte visiblement avant que la barrière ne se déclenche. -- Un refus en attente est également effacé lors d'un `session_shutdown` pour toute raison (`new` / `resume` / `fork` / `quit`), de sorte qu'une barrière obsolète d'une session précédente ne peut pas contaminer une nouvelle session démarrée dans le même processus Pi. +- Après l'arrêt de Pi, la raison du deny est capturée en mémoire, indexée par l'identifiant de session Pi. Le tout prochain prompt soumis dans le même processus Pi la draine : le LLM voit la directive `MANDATORY ACTION REQUIRED` en tête de son system prompt, effectue le commit (ou le push / ouvre la PR / attend le CI), puis continue avec votre demande. La raison du deny capturée est à usage unique — une fois drainée, la porte est levée. +- La porte est bornée par la durée de vie du processus Pi. Si vous faites `Ctrl+C` sur Pi ou quittez entre deux tours, l'entrée en mémoire est perdue avec le processus et la porte est manquée. Claude, Copilot, Cursor, Gemini et OpenCode ont la même contrainte (tuer l'agent fait manquer la porte) — Pi la rend simplement plus visible car l'agent se termine visiblement avant que la porte ne se déclenche. +- Un deny en attente est également effacé à `session_shutdown` pour toute raison (`new` / `resume` / `fork` / `quit`), afin qu'une porte périmée d'une session précédente ne puisse pas fuiter dans une nouvelle session démarrée dans le même processus Pi. -Si vous avez besoin d'une relance dans la même boucle comme avec Claude, exécutez vos politiques `Stop` avec l'un des six autres CLI supportés. Nous suivons l'évolution de Pi en amont pour un futur type Result sur `AgentEndEvent` qui permettrait de combler cet écart. +Si vous avez besoin d'une relance dans la même boucle à la manière de Claude, exécutez vos politiques `Stop` sous l'un des six autres CLI supportés. Nous suivons l'évolution de Pi en amont pour un futur type Result sur `AgentEndEvent` qui nous permettrait de combler cet écart. ### `require-commit-before-stop` **Événement :** Stop -**Par défaut :** Refuse l'arrêt lorsqu'il y a des modifications non commitées (fichiers modifiés, indexés ou non suivis). Retourne un message informatif lorsque le répertoire de travail est propre. +**Par défaut :** Bloque l'arrêt lorsqu'il y a des modifications non commitées (fichiers modifiés, indexés ou non suivis). Retourne un message informatif lorsque le répertoire de travail est propre. Aucun paramètre. @@ -740,13 +740,13 @@ Aucun paramètre. ### `require-push-before-stop` **Événement :** Stop -**Par défaut :** Refuse l'arrêt lorsqu'il y a des commits non pushés ou lorsque la branche courante n'a pas de branche de suivi distante. Suggère `git push -u` pour créer une branche de suivi si nécessaire. Fail-open si aucun remote n'est configuré. +**Par défaut :** Bloque l'arrêt lorsqu'il y a des commits non pushés ou lorsque la branche courante n'a pas de branche de suivi distante. Suggère `git push -u` pour créer une branche de suivi si nécessaire. Fail-open si aucun remote n'est configuré. **Paramètres :** | Paramètre | Type | Défaut | Description | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | Nom du remote vers lequel pusher. | +| `remote` | `string` | `"origin"` | Nom du remote vers lequel pousser. | **Exemple :** @@ -765,13 +765,14 @@ Aucun paramètre. ### `require-pr-before-stop` **Événement :** Stop -**Par défaut :** Refuse l'arrêt lorsqu'aucune pull request n'existe pour la branche courante, ou lorsque la PR existante est fermée sans avoir été fusionnée. Demande à Claude de créer une PR avec `gh pr create`. Lorsque la PR est **fusionnée**, la politique autorise (le travail a été livré) et le message suggère de quitter la branche (`git checkout main && git pull`). +**Par défaut :** Bloque l'arrêt lorsqu'aucune pull request n'existe pour la branche courante, ou lorsque la PR existante est fermée sans avoir été mergée. Demande à Claude de créer une PR avec `gh pr create`. Lorsque la PR est **mergée**, la politique autorise (le travail est livré) et le message suggère de quitter la branche (`git checkout main && git pull`). Aucun paramètre. -Cette politique nécessite que le [GitHub CLI](https://cli.github.com/) (`gh`) soit installé et authentifié. -Exécutez `gh auth login` avec un personal access token disposant de la portée `repo` pour accéder en lecture aux pull requests. Si `gh` n'est pas installé ou non authentifié, la politique est fail-open et en informe Claude. +Cette politique nécessite que [GitHub CLI](https://cli.github.com/) (`gh`) soit installé et authentifié. +Exécutez `gh auth login` avec un personal access token ayant le scope `repo` pour accéder en lecture aux +pull requests. Si `gh` n'est pas installé ou non authentifié, la politique fail-open et signale la raison à Claude. --- @@ -779,21 +780,24 @@ Exécutez `gh auth login` avec un personal access token disposant de la portée ### `require-no-conflicts-before-stop` **Événement :** Stop -**Par défaut :** Refuse l'arrêt lorsque la branche courante ne peut pas fusionner proprement dans la branche de base. La politique confirme d'abord qu'il existe une PR `OPEN` sur GitHub pour la branche — sans PR, il n'y a pas de cible de fusion à appliquer, et la politique court-circuite vers allow. Une fois une PR `OPEN` confirmée, deux sondes indépendantes s'exécutent : +**Par défaut :** Bloque l'arrêt lorsque la branche courante ne peut pas être mergée proprement dans la branche de base. La politique vérifie d'abord l'existence d'une PR `OPEN` sur GitHub pour la branche — sans PR, il n'y a pas de cible de merge à appliquer, donc toute la politique court-circuite vers allow. Une fois une PR `OPEN` confirmée, deux sondes indépendantes s'exécutent : -1. **Locale** — `git merge-tree --write-tree --name-only origin/ HEAD`. En cas de conflit, le message de refus liste les fichiers en conflit pour que Claude sache exactement quoi résoudre. -2. **GitHub** — réutilise le résultat de `gh pr view --json mergeable,state` déjà récupéré lors de la vérification préalable. Détecte les conflits qu'un `origin/` local périmé pourrait manquer (ex. une PR conflictuelle mergée sur `main` depuis le dernier fetch). Un résultat `CONFLICTING` entraîne un refus. Un résultat `UNKNOWN` entraîne également un refus et demande à Claude d'attendre environ 10 secondes et de revérifier avant de tenter de s'arrêter — cela évite les faux négatifs pendant que GitHub recalcule. +1. **Locale** — `git merge-tree --write-tree --name-only origin/ HEAD`. En cas de conflit, le message deny liste les fichiers en conflit afin que Claude sache exactement quoi résoudre. +2. **GitHub** — réutilise le résultat `gh pr view --json mergeable,state` déjà récupéré lors de la prévérification. Détecte les conflits qu'un `origin/` local obsolète manquerait (par ex. si quelqu'un a mergé une PR conflictuelle sur `main` depuis le dernier fetch). Un résultat `CONFLICTING` bloque. Un résultat `UNKNOWN` bloque également et demande à Claude d'attendre ~10 secondes et de revérifier avant de tenter un nouvel arrêt — cela évite les faux négatifs pendant que GitHub recalcule. -Ignore entièrement (autorise) dans les cas suivants : `gh` non installé, aucune PR pour la branche, l'état de la PR n'est pas `OPEN` (ex. `MERGED`, `CLOSED`), ou `gh pr view` retourne une sortie non analysable. Également fail-open lorsque `origin/` est absent localement ou lorsqu'aucun commit n'est en avance sur la base — ces cas de repli de niveau 1 consultent tout de même la fusionnabilité de la PR en cache avant d'autoriser. +Court-circuite entièrement vers allow lorsque : `gh` n'est pas installé, aucune PR n'existe pour la branche, l'état de la PR n'est pas `OPEN` (par ex. `MERGED`, `CLOSED`), ou `gh pr view` retourne une sortie non analysable. Fail-open également lorsque `origin/` est absent localement ou lorsqu'aucun commit n'est en avance sur la base — ces court-circuits de couche 1 consultent quand même la mergeabilité en cache de la PR avant d'autoriser. **Paramètres :** | Paramètre | Type | Défaut | Description | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Branche de base contre laquelle vérifier les conflits. | +| `baseBranch` | `string` | `"main"` | Branche de base par rapport à laquelle vérifier les conflits. | -Le GitHub CLI (`gh`) est requis pour cette politique. La politique utilise `gh pr view` pour confirmer l'existence d'une PR `OPEN` avant d'exécuter toute sonde de conflit — sans `gh`, la politique court-circuite vers allow. Exécutez `gh auth login` avec un personal access token disposant de la portée `repo` pour accéder en lecture aux pull requests. +GitHub CLI (`gh`) est requis pour cette politique. Elle utilise `gh pr view` pour confirmer +l'existence d'une PR `OPEN` avant d'exécuter toute sonde de conflit — sans `gh`, la politique +court-circuite vers allow. Exécutez `gh auth login` avec un personal access token ayant le scope +`repo` pour accéder en lecture aux pull requests. --- @@ -801,13 +805,14 @@ Le GitHub CLI (`gh`) est requis pour cette politique. La politique utilise `gh p ### `require-ci-green-before-stop` **Événement :** Stop -**Par défaut :** Refuse l'arrêt lorsque les vérifications CI sont en échec ou toujours en cours sur la branche courante. Vérifie à la fois les workflows GitHub Actions et les vérifications de bots tiers (ex. CodeRabbit, SonarCloud, Codecov). Considère les conclusions `skipped`, `cancelled` et `neutral` comme non-échouées (cette dernière couvre par exemple les alertes Socket Security sur les PRs de contributeurs externes, où l'application signale intentionnellement neutral plutôt que success/failure). Retourne un message informatif lorsque toutes les vérifications réussissent. +**Par défaut :** Bloque l'arrêt lorsque les vérifications CI échouent ou sont encore en cours sur la branche courante. Vérifie à la fois les exécutions de workflows GitHub Actions et les vérifications de bots tiers (par ex. CodeRabbit, SonarCloud, Codecov). Traite les conclusions `skipped`, `cancelled` et `neutral` comme non-échouantes (cette dernière couvre par ex. les alertes Socket Security sur les PRs de contributeurs externes, où l'application signale intentionnellement neutral plutôt que success/failure). Retourne un message informatif lorsque toutes les vérifications réussissent. Aucun paramètre. -Cette politique nécessite que le [GitHub CLI](https://cli.github.com/) (`gh`) soit installé et authentifié. -Exécutez `gh auth login` avec un personal access token disposant de la portée `repo` pour accéder en lecture aux workflows GitHub Actions et à l'API Checks. Si `gh` n'est pas installé ou non authentifié, la politique est fail-open et en informe Claude. +Cette politique nécessite que [GitHub CLI](https://cli.github.com/) (`gh`) soit installé et authentifié. +Exécutez `gh auth login` avec un personal access token ayant le scope `repo` pour accéder en lecture aux +exécutions de workflows Actions et à l'API Checks. Si `gh` n'est pas installé ou non authentifié, la politique fail-open et signale la raison à Claude. --- @@ -816,7 +821,7 @@ Exécutez `gh auth login` avec un personal access token disposant de la portée ## Désactiver des politiques individuelles -Retirez une politique spécifique de `enabledPolicies` dans votre configuration, ou désactivez-la dans l'onglet Policies du tableau de bord. +Retirez une politique spécifique de `enabledPolicies` dans votre configuration, ou désactivez-la dans l'onglet Politiques du tableau de bord. ```json { diff --git a/docs/fr/cli/audit.mdx b/docs/fr/cli/audit.mdx index efb678b4..50e38288 100644 --- a/docs/fr/cli/audit.mdx +++ b/docs/fr/cli/audit.mdx @@ -1,22 +1,23 @@ --- title: Auditer les sessions passées (bêta) -description: "Comptabiliser la fréquence des comportements inefficaces ou risqués dans les transcriptions passées" +description: "Comptez la fréquence à laquelle l'agent a effectué des actions inutiles ou risquées dans les transcriptions passées" --- - **Fonctionnalité bêta.** L'audit est livré en bêta pendant que nous recueillons les premiers retours. - Le catalogue de détecteurs et le format des rapports sont susceptibles d'évoluer avant la prochaine version stable. - N'hésitez pas à ouvrir un ticket si quelque chose vous semble incorrect. + **Fonctionnalité bêta.** L'audit est publié en version bêta le temps que nous + recueillions les premiers retours. Le catalogue de détecteurs et le format du + rapport sont susceptibles de changer avant la prochaine version stable. + N'hésitez pas à ouvrir une issue si quelque chose vous semble incorrect. -L'audit rejoue vos transcriptions passées de l'agent CLI à travers le moteur de politiques de failproofai -et génère un rapport visuel partageable sur la **page `/audit` du tableau de bord** -— l'archétype de votre agent, un score de 0 à 100, et précisément quelles politiques -auraient détecté quoi. +L'audit rejoue vos transcriptions passées de l'agent CLI à travers le moteur de +politiques de failproofai et génère un rapport visuel partageable sur la **page +du tableau de bord `/audit`** — l'archétype de votre agent, un score de 0 à +100, et précisément quelles politiques auraient détecté quoi. ## Lancer l'audit -Trois façons de procéder — toutes aboutissent au même rapport `/audit`. +Trois façons de démarrer — toutes aboutissent au même rapport `/audit`. @@ -36,61 +37,62 @@ failproofai - `npx -y failproofai audit` télécharge failproofai, lance l'analyse et ouvre le - tableau de bord pour vous — aucune installation préalable nécessaire. + `npx -y failproofai audit` télécharge failproofai, lance l'analyse et ouvre + le tableau de bord pour vous — aucune installation préalable requise. - `failproofai audit` exécute l'analyse dans votre terminal, puis ouvre + `failproofai audit` lance l'analyse dans votre terminal, puis ouvre `localhost:8020/audit` automatiquement une fois terminé. - Lancez `failproofai` et cliquez sur **Audit** dans la barre de navigation (entre Politiques et - Projets), ou ouvrez `/audit` directement. + Lancez `failproofai` et cliquez sur **Audit** dans la barre de navigation + (entre Policies et Projects), ou ouvrez `/audit` directement. - Exécutez `failproofai audit -h` (ou `--help`) pour afficher l'aide. L'audit fonctionne **entièrement - hors ligne** — aucun compte ni connexion réseau requis — et le tableau de bord reste actif - jusqu'à ce que vous l'arrêtiez avec `Ctrl+C`. + Lancez `failproofai audit -h` (ou `--help`) pour afficher l'aide. L'audit + s'exécute **entièrement hors ligne** — aucun compte ni connexion réseau requis + — et le tableau de bord reste actif jusqu'à ce que vous l'arrêtiez avec + `Ctrl+C`. -Le tableau de bord analyse les transcriptions passées de l'agent CLI sur cette machine (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) et indique la fréquence à laquelle l'agent a effectué des actions que failproofai est conçu pour bloquer — vérifications de variables d'environnement, push forcés, préfixes `cd ` redondants, boucles de polling avec sleep, relecture de fichiers venant d'être modifiés, et bien d'autres. +Le tableau de bord analyse les transcriptions passées de l'agent CLI sur cette machine (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) et indique à quelle fréquence l'agent a effectué des actions que failproofai est conçu pour bloquer — vérifications de variables d'environnement, push forcés, préfixes `cd ` redondants, boucles de polling avec sleep, relecture de fichiers venant d'être édités, et bien d'autres. -Pour chaque transcription, chaque événement d'utilisation d'outil est rejoué à travers les 39 politiques intégrées **et** à travers 8 détecteurs réservés à l'audit, qui identifient des comportements non encore couverts par les politiques en temps réel. Les comptages sont agrégés par politique/détecteur sur l'ensemble des sessions. +Pour chaque transcription, chaque événement d'utilisation d'outil est rejoué à travers les 39 politiques intégrées **et** à travers 8 détecteurs exclusifs à l'audit qui repèrent des motifs non encore couverts par les politiques en temps réel. Les comptages sont agrégés par politique / détecteur sur l'ensemble des sessions. ## Ce que vous obtenez -La page `/audit` est une **affiche** sur un seul écran, partageable, suivie de quatre sections sous le pli : +La page `/audit` est une **affiche** plein écran partageable, suivie de quatre sections situées sous le pli : -1. **Affiche** — l'identité de votre agent en un coup d'œil : son **archétype** (parmi 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), ses mots-clés de persona, la rareté de cet archétype, et un **score de 0 à 100** avec une bande de niveau (`S` jusqu'à `bottom tier`). Conçu pour être partagé — publiez sur X ou LinkedIn, ou téléchargez en PNG. -2. **`// strengths`** — ce que votre agent fait déjà bien, sous forme de données réelles issues de l'analyse (ex. : % d'appels d'outils propres, `0` tentatives de push sur main), affiché uniquement lorsque la politique concernée n'a enregistré aucun incident. -3. **`// quirks`** — ce qui a échappé au contrôle : un tableau classé des comportements que failproofai aurait interceptés — *quand* c'est arrivé pour la dernière fois, *ce qui a glissé* (et le détecteur intégré qui l'aurait bloqué), sa *sévérité*, et la fréquence d'apparition (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — la liste des correctifs recommandés : une ligne par politique avec une commande `failproofai policy add ` à copier-coller, plus un bouton **install all** qui active toutes les recommandations d'un coup et affiche votre **score projeté** si vous le faisiez. -5. **`// come back better`** — ancrez la bonne habitude : configurez un **rappel** par e-mail pour relancer l'audit (`3d` / `7d` / `14d` / `30d`) ou relancez-le maintenant, et **invitez un ami** à effectuer le sien (envoyé depuis failproof.ai, en Cc pour vous). Les rappels et invitations nécessitent une connexion — voir [`failproofai auth`](/fr/cli/auth). +1. **Affiche** — l'identité de votre agent en un coup d'œil : son **archétype** (l'un des 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), ses mots-clés de persona, la rareté de cet archétype, et un **score de 0 à 100** avec un niveau (`S` jusqu'à `bottom tier`). Conçue pour être partagée — publiez-la sur X ou LinkedIn, ou téléchargez-la en PNG. +2. **`// strengths`** — ce que votre agent fait déjà bien, exprimé en chiffres réels issus de l'analyse (ex. : taux d'appels d'outils propres, `0` tentative de push sur main), affiché uniquement lorsque la politique concernée affiche un bilan sans faille. +3. **`// quirks`** — ce qui a échappé : un tableau classé des comportements que failproofai aurait détectés — *quand* c'est arrivé la dernière fois, *ce qui a échappé* (et la politique intégrée qui l'aurait bloqué), sa *sévérité*, et la fréquence à laquelle c'a été *observé* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — la liste des correctifs recommandés : une ligne par politique avec un `failproofai policy add ` à copier-coller, ainsi qu'un bouton **install all** qui active toutes les recommandations en une fois et affiche votre **score projeté** si vous le faisiez. +5. **`// come back better`** — ancrez la bonne habitude : définissez un **rappel** par e-mail pour un nouvel audit (`3d` / `7d` / `14d` / `30d`) ou relancez l'audit maintenant, et **invitez un ami** à effectuer son propre audit (envoyé depuis failproof.ai, en Cc à vous). Les rappels et invitations nécessitent une connexion — voir [`failproofai auth`](/fr/cli/auth). -## Détecteurs réservés à l'audit +## Détecteurs exclusifs à l'audit -Ces détecteurs identifient des comportements «inutilement coûteux» qui ne sont pas (encore) appliqués en temps réel. Ils ne s'exécutent que lors de l'audit et ne bloquent jamais un appel d'outil en direct. +Ces détecteurs repèrent des motifs de comportement inefficaces qui ne sont pas (encore) appliqués en temps réel. Ils ne s'exécutent que pendant l'audit et ne bloquent jamais un appel d'outil en direct. -| Détecteur | Ce qu'il comptabilise | +| Détecteur | Ce qu'il compte | |---|---| | `redundant-cd-cwd` | Commandes Bash commençant par `cd && …` alors que les commandes s'exécutent déjà dans `cwd`. | -| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` sur un seul fichier source — utiliser plutôt l'outil `Read`. | -| `prefer-edit-over-sed-awk` | Éditions en place avec `sed -i` / `awk … > file` — utiliser plutôt l'outil `Edit`. | -| `prefer-write-over-heredoc` | Écriture de fichiers avec heredoc / `echo > file` multiligne — utiliser plutôt l'outil `Write`. | -| `sleep-polling-loop` | Longs `sleep N` (≥ 30s) ou boucles de polling `while …; sleep …; done`. | -| `find-from-root` | `find /`, `find /home`, `find /usr`, etc. — limiter la portée à `cwd`. | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, ignorant les hooks. | -| `reread-after-edit` | Lecture (`Read`) d'un fichier qui vient d'être modifié (`Edit`/`Write`) dans la même session. | +| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` sur un seul fichier source — utilisez plutôt l'outil `Read`. | +| `prefer-edit-over-sed-awk` | Modifications en place avec `sed -i` / `awk … > file` — utilisez plutôt l'outil `Edit`. | +| `prefer-write-over-heredoc` | Écriture de fichiers via heredoc / `echo > file` multi-ligne — utilisez plutôt l'outil `Write`. | +| `sleep-polling-loop` | Longues pauses `sleep N` (≥ 30s) ou boucles de polling `while …; sleep …; done`. | +| `find-from-root` | `find /`, `find /home`, `find /usr`, etc. — limitez la portée à `cwd`. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, contournant les hooks. | +| `reread-after-edit` | Lecture (`Read`) d'un fichier qui vient d'être modifié via `Edit`/`Write` dans la même session. | ## Caches -- **Cache par transcription** dans `~/.failproofai/cache/audit/.json`, indexé par `(mtime, size, engineVersion, detectorVersion)` — invalidé automatiquement lorsque la transcription ou le code des politiques/détecteurs change. Chaque entrée stocke également un horodatage `cachedAt` comme **métadonnée de TTL** (non incluse dans la clé de cache) ; les entrées de plus de **7 jours** sont rejetées à la lecture afin que les résultats anciens ne survivent pas à l'évolution des détecteurs. -- **Cache du résultat global** dans `~/.failproofai/audit-dashboard.json` (mode 0600). Permet au tableau de bord de s'afficher instantanément lors de la navigation sans relancer l'analyse. Également rejeté à la lecture au-delà du **TTL de 7 jours** — `/audit` revient alors à son état vide et invite à effectuer une nouvelle analyse. Cliquez sur `[ re-audit now ]` en bas du rapport pour actualiser — ce nouveau passage envoie `noCache: true`, ce qui contourne le cache par transcription et réanalyse toutes les transcriptions au lieu de retourner le résultat mis en cache ; l'exécution diffuse la progression via une bande fixe en haut de l'écran et remplace le résultat en cas de succès (sans rechargement de page ; en cas d'échec, le rapport précédent est conservé). +- **Cache par transcription** dans `~/.failproofai/cache/audit/.json`, indexé par `(mtime, size, engineVersion, detectorVersion)` — invalidé automatiquement lorsque la transcription ou le code des politiques/détecteurs change. Chaque entrée stocke également un horodatage `cachedAt` comme **métadonnée TTL** (ne faisant pas partie de la clé de cache) ; les entrées de plus de **7 jours** sont rejetées à la lecture afin que des résultats anciens ne survivent pas à l'évolution des détecteurs. +- **Cache du résultat global** dans `~/.failproofai/audit-dashboard.json` (mode 0600). Permet au tableau de bord de s'afficher instantanément lors de la navigation sans relancer l'analyse. Également rejeté à la lecture au-delà du **TTL de 7 jours** — `/audit` bascule alors vers son état vide et invite à relancer une analyse. Cliquez sur `[ re-audit now ]` en bas du rapport pour actualiser — le re-audit envoie `noCache: true`, ce qui contourne le cache par transcription et ré-analyse chaque transcription au lieu de retourner le résultat mis en cache ; l'exécution diffuse sa progression via une bannière épinglée en haut et remplace le résultat en place en cas de succès (sans rechargement de page ; un re-audit échoué conserve le rapport précédent). -## Notes +## Remarques -- **Aucune modification.** L'audit rejoue en mode lecture seule. `warn-repeated-tool-calls` est ignoré car son sidecar par session serait autrement modifié. -- **Politiques de workflow ignorées.** Les politiques `require-*-before-stop` se déclenchent uniquement sur les événements `Stop` et via `execSync` sur l'état git en direct — elles n'ont pas d'interprétation pertinente de type «qu'aurait-il pu se passer en 2025», et n'apparaissent donc pas dans les comptages de l'audit. +- **Aucune mutation.** L'audit rejoue en mode lecture seule. `warn-repeated-tool-calls` est ignoré car son fichier sidecar par session serait autrement modifié. +- **Politiques de workflow ignorées.** Les politiques `require-*-before-stop` ne se déclenchent que sur les événements `Stop` et utilisent `execSync` sur l'état git actif — elles n'ont pas d'interprétation significative dans un contexte rétroactif type « qu'aurait-il se passé en 2025 », et n'apparaissent donc pas dans les comptages de l'audit. - **Politiques personnalisées ignorées.** Les hooks personnalisés fournis par l'utilisateur ne sont pas rejoués (ils peuvent avoir changé depuis la session d'origine). \ No newline at end of file diff --git a/docs/fr/cli/auth.mdx b/docs/fr/cli/auth.mdx index d2b72942..b37f71bc 100644 --- a/docs/fr/cli/auth.mdx +++ b/docs/fr/cli/auth.mdx @@ -1,5 +1,5 @@ --- -title: Se connecter +title: Connexion description: "Connectez-vous à FailproofAI depuis la CLI pour activer les rappels et les fonctionnalités personnalisées" --- @@ -9,19 +9,19 @@ failproofai auth logout # révoquer cette session failproofai auth whoami # afficher l'identité connectée ``` -L'ancienne syntaxe avec les flags `--login` / `--logout` / `--whoami` est toujours acceptée comme alias pour la rétrocompatibilité. +L'ancienne forme avec les flags `--login` / `--logout` / `--whoami` est toujours acceptée comme alias pour la rétrocompatibilité. -L'authentification est optionnelle. Les politiques, le tableau de bord, la page `/audit` et toutes les autres fonctionnalités locales fonctionnent exactement de la même façon, que vous soyez connecté ou non. La fonctionnalité de connexion existe pour que les fonctionnalités qui **nécessitent** une identité stable (rappels de ré-audit aujourd'hui, d'autres à venir) aient un point d'ancrage. +L'authentification est optionnelle. Les politiques, le tableau de bord, la page `/audit` et toutes les autres fonctionnalités locales fonctionnent exactement de la même manière que vous soyez connecté ou non. La surface de connexion existe afin que les fonctionnalités qui **nécessitent** une identité stable (rappels de ré-audit aujourd'hui, d'autres à l'avenir) disposent d'un ancrage. -## Processus de connexion +## Flux de connexion ```bash failproofai auth login ``` -Demande votre adresse e-mail, envoie un code à usage unique à 6 chiffres à cette adresse, demande le code, puis en cas de succès écrit `~/.failproofai/auth.json` (mode `0600`). La même session devient alors visible dans le tableau de bord intégré — en cliquant sur `[ set a reminder ]` sur `/audit`, vous serez reconnu comme connecté. +Demande votre adresse e-mail, envoie un code à usage unique à 6 chiffres à cette adresse, vous invite à saisir ce code, puis en cas de succès écrit `~/.failproofai/auth.json` (mode `0600`). La même session est alors visible dans le tableau de bord intégré — en cliquant sur `[ set a reminder ]` dans `/audit`, vous apparaîtrez comme connecté. -Le tableau de bord expose le même processus sous forme de fenêtre modale sur `/audit` pour les utilisateurs qui n'utilisent jamais la CLI. +Le tableau de bord propose le même flux sous forme de boîte de dialogue modale sur `/audit` pour les utilisateurs qui ne touchent jamais à la CLI. ## Déconnexion @@ -37,11 +37,11 @@ Révoque la session actuelle sur le serveur et supprime `~/.failproofai/auth.jso failproofai auth whoami ``` -Affiche ` ()` et quitte avec le code 0 lorsqu'une session valide existe, ou `not signed in` et quitte avec le code 1 dans le cas contraire. Rafraîchit silencieusement le jeton d'accès en arrière-plan s'il expire dans moins d'une minute. +Affiche ` ()` et quitte avec le code 0 lorsqu'une session valide existe, ou `not signed in` et quitte avec le code 1 dans le cas contraire. Actualise silencieusement le jeton d'accès en arrière-plan s'il expire dans moins d'une minute. -## Rappel de ré-audit persistant +## Rappel de ré-audit récurrent -Lorsque vous cliquez sur **`[ set a reminder ]`** sur la page `/audit` (ou que vous vous connectez via la fenêtre modale que le bouton conditionne), le tableau de bord crée un petit fichier complémentaire à `~/.failproofai/next-audit.json` : +Lorsque vous cliquez sur **`[ set a reminder ]`** dans la page `/audit` (ou que vous vous connectez via la boîte de dialogue modale que le bouton conditionne), le tableau de bord écrit un petit fichier complémentaire dans `~/.failproofai/next-audit.json` : ```json { @@ -51,9 +51,9 @@ Lorsque vous cliquez sur **`[ set a reminder ]`** sur la page `/audit` (ou que v } ``` -Ce fichier est associé à l'adresse e-mail pour laquelle il a été défini — changer de session CLI vers un autre compte masque tout rappel appartenant à l'utilisateur précédent. Le délai par défaut est de **7 jours**, configurable ultérieurement lorsque le planificateur sera disponible. Créé avec les permissions `0600` comme `auth.json`. +Ce fichier est rattaché à l'adresse e-mail pour laquelle il a été défini — changer de session CLI pour un autre compte masque tout rappel appartenant à l'utilisateur précédent. Le décalage par défaut est de **7 jours**, configurable ultérieurement lorsque le planificateur sera disponible. Créé avec les permissions `0600` comme `auth.json`. -L'endpoint `/api/auth/reminder` du tableau de bord expose `GET` (lecture), `POST` (définir / reprogrammer) et `DELETE` (supprimer), et nécessite une session active. +Le endpoint `/api/auth/reminder` du tableau de bord expose `GET` (lecture), `POST` (définir / replanifier) et `DELETE` (effacer), et nécessite une session active. ## Contenu de `~/.failproofai/auth.json` @@ -67,21 +67,21 @@ L'endpoint `/api/auth/reminder` du tableau de bord expose `GET` (lecture), `POST } ``` -Créé avec les permissions `0600` (lecture/écriture réservées au propriétaire). Le jeton d'accès est un JWT HS256 valide 1 heure ; le jeton de rafraîchissement est une chaîne aléatoire opaque de 256 bits que le serveur stocke sous la forme `SHA-256(token)`. La réutilisation du jeton de rafraîchissement est détectée côté serveur et révoque toutes les sessions de l'utilisateur. +Créé avec les permissions `0600` (lecture/écriture réservées au propriétaire). Le jeton d'accès est un JWT HS256 valable 1 heure ; le jeton de rafraîchissement est une chaîne aléatoire opaque de 256 bits que le serveur stocke sous la forme `SHA-256(token)`. La réutilisation du jeton de rafraîchissement est détectée côté serveur et révoque toutes les sessions de l'utilisateur. ## Variables d'environnement -| Variable | Valeur par défaut | Utilité | +| Variable | Valeur par défaut | Description | |---|---|---| -| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | Remplace l'URL de base du serveur API. Utile pour le développement local avec un serveur API auto-hébergé. | -| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | Remplace l'emplacement où `auth.json` est stocké. Principalement pour les tests. | +| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | Remplace l'URL de base du serveur API. Utile pour le développement local contre un serveur API auto-hébergé. | +| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | Remplace l'emplacement de stockage de `auth.json`. Principalement utilisé pour les tests. | Consultez [Variables d'environnement](/fr/cli/environment-variables) pour la liste complète. ## Dépannage -**« Could not reach the api-server »** — la CLI ne peut pas établir une connexion TCP vers `FAILPROOF_API_URL`. Vérifiez votre réseau, ou définissez `FAILPROOF_API_URL` si vous utilisez un serveur API auto-hébergé. +**« Could not reach the api-server »** — la CLI ne parvient pas à ouvrir une connexion TCP vers `FAILPROOF_API_URL`. Vérifiez votre réseau, ou définissez `FAILPROOF_API_URL` si vous utilisez un serveur API auto-hébergé. -**« Rate limited »** — trop de tentatives de connexion sur une fenêtre de 15 minutes pour cet e-mail (5/e-mail) ou cette adresse IP (20/IP), ou un délai de renvoi de 30 secondes après la demande précédente pour le même e-mail. Le message d'erreur indique le délai d'attente avant de réessayer en secondes. +**« Rate limited »** — trop de tentatives de connexion dans une fenêtre de 15 minutes pour cette adresse e-mail (5/email) ou cette adresse IP (20/IP), ou un délai de renvoi de 30 secondes après la précédente requête pour la même adresse e-mail. Le message d'erreur indique le délai avant nouvelle tentative en secondes. -**Code refusé** — le code OTP était incorrect, expiré, ou la ligne a atteint son verrouillage après 5 tentatives incorrectes. Exécutez à nouveau `failproofai auth login` pour demander un nouveau code. \ No newline at end of file +**Code refusé** — le code OTP était incorrect, expiré, ou le nombre maximal de 5 mauvaises tentatives a été atteint. Exécutez `failproofai auth login` à nouveau pour demander un nouveau code. \ No newline at end of file diff --git a/docs/fr/cli/dashboard.mdx b/docs/fr/cli/dashboard.mdx index d5223da8..95dc7f29 100644 --- a/docs/fr/cli/dashboard.mdx +++ b/docs/fr/cli/dashboard.mdx @@ -1,22 +1,22 @@ --- title: Voir les sessions -description: "Lancez le tableau de bord pour parcourir les sessions d'agents et gérer les politiques" +description: "Lancez le tableau de bord pour parcourir les sessions d'agent et gérer les politiques" --- ```bash failproofai ``` -Démarre le tableau de bord web à l'adresse `http://localhost:8020`. +Démarre le tableau de bord web sur `http://localhost:8020`. ## Options -| Flag | Description | -|------|-------------| +| Indicateur | Description | +|------------|-------------| | `--port ` | Port d'écoute (par défaut : `8020`) | | `--allowed-origins ` | Hôtes/IPs séparés par des virgules autorisés à accéder aux ressources de développement | -Pour pointer le tableau de bord vers un dossier de projet Claude non standard, définissez la variable d'environnement `CLAUDE_PROJECTS_PATH` au lancement. +Pour pointer le tableau de bord vers un dossier de projet Claude non par défaut, définissez la variable d'environnement `CLAUDE_PROJECTS_PATH` lors du lancement. ## Exemples diff --git a/docs/fr/cli/environment-variables.mdx b/docs/fr/cli/environment-variables.mdx index 0c93e236..b18142a9 100644 --- a/docs/fr/cli/environment-variables.mdx +++ b/docs/fr/cli/environment-variables.mdx @@ -8,9 +8,9 @@ description: "Configurer le comportement de failproofai avec des variables d'env | Variable | Description | |----------|-------------| | `PORT` | Port du tableau de bord (par défaut : `8020`) | -| `CLAUDE_PROJECTS_PATH` | Remplace l'emplacement où sont recherchés les dossiers de projets Claude Code | +| `CLAUDE_PROJECTS_PATH` | Remplacer l'emplacement où les dossiers de projets Claude Code sont recherchés | | `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Pages du tableau de bord à masquer, séparées par des virgules | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hôtes/IPs autorisés à accéder aux ressources de développement. Équivalent à `--allowed-origins`. | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hôtes/IPs autorisés à accéder aux ressources de développement. Identique à `--allowed-origins`. | ## Journalisation @@ -23,25 +23,25 @@ description: "Configurer le comportement de failproofai avec des variables d'env | Variable | Description | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Désactive la télémétrie d'utilisation anonyme | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Désactiver la télémétrie d'utilisation anonyme | ## Authentification | Variable | Description | |----------|-------------| -| `FAILPROOF_API_URL` | Remplace l'URL de base du serveur API utilisée par `failproofai auth` et la boîte de dialogue d'authentification du tableau de bord. Par défaut `https://api.befailproof.ai` ; définir à `http://localhost:8080` (ou autre) lors de l'exécution d'un serveur API local. | -| `FAILPROOFAI_AUTH_DIR` | Remplace l'emplacement où est stocké `auth.json` (par défaut : `~/.failproofai`). Principalement utile pour les tests isolés. | +| `FAILPROOF_API_URL` | Remplacer l'URL de base du serveur API utilisée par `failproofai auth` et la boîte de dialogue d'authentification du tableau de bord. Par défaut `https://api.befailproof.ai` ; définir à `http://localhost:8080` (ou autre) lors de l'exécution d'un serveur API local. | +| `FAILPROOFAI_AUTH_DIR` | Remplacer l'emplacement où `auth.json` est stocké (par défaut : `~/.failproofai`). Principalement utile pour les tests isolés. | -## Invite au premier lancement +## Invite de premier démarrage | Variable | Description | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignore l'invite proposant d'installer les politiques lors du premier appel nu à `failproofai` | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignorer l'invite proposant d'installer les politiques lors de la première invocation simple de `failproofai` | ## LLM (pour l'évaluation des politiques) | Variable | Description | |----------|-------------| -| `FAILPROOFAI_LLM_BASE_URL` | Point de terminaison de l'API LLM (par défaut : `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | Clé API pour les politiques alimentées par LLM | +| `FAILPROOFAI_LLM_BASE_URL` | Point d'accès de l'API LLM (par défaut : `https://api.openai.com/v1`) | +| `FAILPROOFAI_LLM_API_KEY` | Clé API pour les politiques basées sur un LLM | | `FAILPROOFAI_LLM_MODEL` | Nom du modèle (par défaut : `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/fr/cli/hook.mdx b/docs/fr/cli/hook.mdx index 91c0c833..28e4911c 100644 --- a/docs/fr/cli/hook.mdx +++ b/docs/fr/cli/hook.mdx @@ -7,15 +7,15 @@ description: "Le sous-processus que Claude Code appelle à chaque événement d' failproofai --hook ``` -Il s'agit de la commande enregistrée dans le fichier `settings.json` de Claude Code par `failproofai policies --install`. Vous n'avez normalement pas à l'appeler directement. +Il s'agit de la commande enregistrée dans le fichier `settings.json` de Claude Code par `failproofai policies --install`. Vous n'appelez normalement pas cette commande directement. -Lit un payload JSON depuis stdin, évalue toutes les politiques activées, et se termine avec un code indiquant la décision : +Elle lit un payload JSON depuis stdin, évalue toutes les politiques activées, et se termine avec un code indiquant la décision prise : | Code de sortie | Décision | Effet | |----------------|----------|-------| -| `0` | `allow` | Autorise l'action | -| `1` | `deny` | Bloque l'action — Claude voit la raison du refus | -| `2` | `instruct` | Injecte des instructions dans le contexte de Claude | +| `0` | `allow` | Autoriser l'action | +| `1` | `deny` | Bloquer l'action — Claude voit la raison du refus | +| `2` | `instruct` | Injecter des instructions dans le contexte de Claude | ### Types d'événements pris en charge diff --git a/docs/fr/cli/install-policies.mdx b/docs/fr/cli/install-policies.mdx index 4ec0987d..97eb9227 100644 --- a/docs/fr/cli/install-policies.mdx +++ b/docs/fr/cli/install-policies.mdx @@ -1,30 +1,30 @@ --- title: Installer les politiques -description: "Activer les politiques afin qu'elles s'exécutent à chaque appel d'outil de l'agent" +description: "Activer les politiques pour qu'elles s'exécutent à chaque appel d'outil de l'agent" --- ```bash failproofai policies --install [policy-names...] [options] ``` -Écrit des entrées de hook dans le fichier de paramètres de l'agent CLI installé (Claude Code, OpenAI Codex ou GitHub Copilot CLI _(bêta)_) afin que failproofai intercepte les appels d'outils. +Inscrit des entrées de hook dans le fichier de paramètres de votre agent CLI installé (Claude Code, OpenAI Codex, ou GitHub Copilot CLI _(bêta)_) afin que failproofai intercepte les appels d'outils. Alias : `failproofai p -i` ## Options -| Drapeau | Description | -|---------|-------------| -| `--cli claude\|codex\|copilot` | Agent(s) CLI pour lesquels installer ; séparés par des espaces (ex. `--cli claude codex copilot`) ou répétés. Omettez cette option pour détecter les CLIs installés et afficher une invite. | -| `--scope user` | Installe dans le fichier de paramètres de portée utilisateur (Claude : `~/.claude/settings.json` ; Codex : `~/.codex/hooks.json` ; Copilot : `~/.copilot/hooks/failproofai.json`). Par défaut. | -| `--scope project` | Installe dans le fichier de paramètres de portée projet (Claude : `/.claude/settings.json` ; Codex : `/.codex/hooks.json` ; Copilot : `/.github/hooks/failproofai.json`). | +| Indicateur | Description | +|------|-------------| +| `--cli claude\|codex\|copilot` | Agent(s) CLI pour lesquels installer ; séparés par des espaces (ex. `--cli claude codex copilot`) ou répétés. Omettez cet indicateur pour détecter automatiquement les CLI installés et afficher une invite. | +| `--scope user` | Installe dans le fichier de paramètres à portée utilisateur (Claude : `~/.claude/settings.json` ; Codex : `~/.codex/hooks.json` ; Copilot : `~/.copilot/hooks/failproofai.json`). Valeur par défaut. | +| `--scope project` | Installe dans le fichier de paramètres à portée projet (Claude : `/.claude/settings.json` ; Codex : `/.codex/hooks.json` ; Copilot : `/.github/hooks/failproofai.json`). | | `--scope local` | Claude uniquement — installe dans `/.claude/settings.local.json`. Codex et Copilot ne disposent pas d'une portée `local`. | | `--custom ` / `-c` | Chemin vers un fichier JS contenant des politiques de hook personnalisées | ## Comportement - **Aucun nom de politique** — ouvre une invite interactive pour sélectionner les politiques -- **Noms spécifiques** — active ces politiques (ajoutées à celles déjà activées) +- **Noms spécifiques** — active les politiques indiquées (ajoutées à celles déjà activées) - **`all`** — active toutes les politiques disponibles L'installation est additive : exécuter `--install` à nouveau ajoute de nouvelles politiques sans supprimer les existantes. @@ -50,7 +50,7 @@ failproofai policies --install --cli codex --scope project # Installer pour GitHub Copilot CLI (bêta) pour le projet courant failproofai policies --install --cli copilot --scope project -# Installer pour les trois CLIs en une seule fois +# Installer pour les trois CLI en une seule fois failproofai policies --install --cli claude codex copilot ``` diff --git a/docs/fr/cli/list-policies.mdx b/docs/fr/cli/list-policies.mdx index 47d77ff9..8ee0806b 100644 --- a/docs/fr/cli/list-policies.mdx +++ b/docs/fr/cli/list-policies.mdx @@ -7,7 +7,7 @@ description: "Voir quelles politiques sont activées, leurs paramètres et les p failproofai policies ``` -Affiche toutes les politiques avec leur statut, les paramètres configurés et les politiques personnalisées. +Affiche toutes les politiques avec leur statut, leurs paramètres configurés et les politiques personnalisées. ## Exemple de sortie diff --git a/docs/fr/cli/remove-policies.mdx b/docs/fr/cli/remove-policies.mdx index 8a869c8f..85f1b88c 100644 --- a/docs/fr/cli/remove-policies.mdx +++ b/docs/fr/cli/remove-policies.mdx @@ -1,13 +1,13 @@ --- title: Désinstaller les politiques -description: "Supprimer les entrées de hooks des paramètres de Claude Code" +description: "Supprimer les entrées de hook des paramètres de Claude Code" --- ```bash failproofai policies --uninstall [policy-names...] [options] ``` -Supprime les entrées de hooks failproofai du `settings.json` de Claude Code. +Supprime les entrées de hook failproofai du `settings.json` de Claude Code. Alias : `failproofai p -u` @@ -18,24 +18,24 @@ Alias : `failproofai p -u` | `--scope user` | Supprimer des paramètres globaux (par défaut) | | `--scope project` | Supprimer des paramètres du projet | | `--scope local` | Supprimer des paramètres locaux | -| `--scope all` | Supprimer de tous les niveaux en une seule fois | +| `--scope all` | Supprimer de toutes les portées à la fois | | `--custom` / `-c` | Effacer le `customPoliciesPath` de la configuration | ## Comportement -- **Aucun nom de politique** — supprime toutes les entrées de hooks failproofai du fichier de paramètres -- **Noms spécifiques** — désactive ces politiques mais conserve les hooks installés +- **Sans nom de politique** — supprime toutes les entrées de hook failproofai du fichier de paramètres +- **Avec des noms spécifiques** — désactive ces politiques mais conserve les hooks installés ## Exemples ```bash -# Supprimer tous les hooks de façon globale +# Supprimer tous les hooks globalement failproofai policies --uninstall # Désactiver une politique spécifique (conserve les hooks installés) failproofai policies --uninstall block-sudo -# Supprimer les hooks de tous les niveaux +# Supprimer les hooks de toutes les portées failproofai policies --uninstall --scope all # Effacer le chemin des politiques personnalisées diff --git a/docs/fr/configuration.mdx b/docs/fr/configuration.mdx index 765da7c2..81c44d79 100644 --- a/docs/fr/configuration.mdx +++ b/docs/fr/configuration.mdx @@ -1,28 +1,28 @@ --- title: Configuration -description: "Format du fichier de config, système à trois portées et règles de fusion" +description: "Format du fichier de configuration, 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 d'où sont chargées 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 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. --- -## Portées de configuration +## Niveaux de configuration -Il existe trois portées de configuration, évaluées par ordre de priorité : +Il existe trois niveaux de configuration, évalués par ordre de priorité : -| Portée | Chemin du fichier | Objectif | -|--------|-------------------|---------| -| **project** | `.failproofai/policies-config.json` | Paramètres par dépôt, commités dans le contrôle de version | -| **local** | `.failproofai/policies-config.local.json` | Surcharges personnelles par dépôt, ignorées par git | -| **global** | `~/.failproofai/policies-config.json` | Paramètres par défaut au niveau utilisateur pour tous les projets | +| 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 | 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. ### Règles de fusion -**`enabledPolicies`** — l'union des trois portées. Une politique activée à n'importe quel niveau est active. +**`enabledPolicies`** — union des trois niveaux. Une politique activée à n'importe quel niveau est active. ```text project: ["block-sudo"] @@ -32,7 +32,7 @@ global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← union dédupliquée ``` -**`policyParams`** — la première portée qui définit des paramètres pour une politique donnée l'emporte entièrement. Il n'y a pas de fusion profonde des valeurs au sein des paramètres d'une politique. +**`policyParams`** — le premier niveau qui définit des paramètres pour une politique donnée l'emporte entièrement. Il n'y a pas de fusion profonde des valeurs au sein des paramètres d'une politique. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -46,12 +46,12 @@ project: (pas d'entrée block-sudo) local: (pas d'entrée block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← remonte jusqu'au global +resolved: { allowPatterns: ["sudo systemctl status"] } ← redescend jusqu'au global ``` -**`customPoliciesPath`** — la première portée qui le définit l'emporte. +**`customPoliciesPath`** — le premier niveau qui le définit l'emporte. -**`llm`** — la première portée qui le définit l'emporte. +**`llm`** — le premier niveau qui le définit l'emporte. --- @@ -102,7 +102,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← remonte jusqu'au glo Type : `string[]` -Liste des noms de politiques à activer. Les noms doivent correspondre exactement aux identifiants de politique affichés par `failproofai policies`. Consultez [Politiques intégrées](/fr/built-in-policies) pour la liste complète. +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. Les politiques absentes de `enabledPolicies` sont inactives, même si elles ont des entrées dans `policyParams`. @@ -110,19 +110,19 @@ Les politiques absentes de `enabledPolicies` sont inactives, même si elles ont Type : `Record>` -Surcharges 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 [Politiques intégrées](/fr/built-in-policies). +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). -Si une politique possède des paramètres que vous ne spécifiez pas, les valeurs par défaut intégrées de la politique sont utilisées. Les utilisateurs qui ne configurent pas du tout `policyParams` obtiennent un comportement identique aux versions précédentes. +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. -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 lorsque vous exécutez `failproofai policies`. +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`. #### `hint` (transversal) Type : `string` (optionnel) -Un message ajouté à la raison lorsqu'une politique retourne `deny` ou `instruct`. Utilisez-le pour donner à Claude des indications concrètes sans modifier la politique elle-même. +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. -Fonctionne avec tout type de politique — intégrée, personnalisée (`custom/`), convention de projet (`.failproofai-project/`), ou convention utilisateur (`.failproofai-user/`). +Fonctionne avec n'importe quel type de politique — intégrée, personnalisée (`custom/`), convention de projet (`.failproofai-project/`) ou convention utilisateur (`.failproofai-user/`). ```json { @@ -141,40 +141,40 @@ Fonctionne avec tout type de politique — intégrée, personnalisée (`custom/` } ``` -Lorsque `block-force-push` bloque, Claude voit : *« Force-pushing is blocked. Try creating a fresh branch instead. »* +Lorsque `block-force-push` refuse, Claude voit : *« Force-pushing is blocked. Try creating a fresh branch instead. »* -Les valeurs non-chaîne et les chaînes vides sont silencieusement ignorées. Si `hint` n'est pas défini, le comportement est inchangé (rétrocompatible). +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). ### `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 chemin 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 stocké). -Le fichier est rechargé à chaque événement de hook — il n'y a pas de mise en cache. Consultez [Politiques personnalisées](/fr/custom-policies) pour les détails de création. +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. -### Politiques basées sur des conventions +### Politiques basées sur les conventions -En plus du `customPoliciesPath` explicite, failproofai découvre et charge automatiquement les fichiers de politique depuis les répertoires `.failproofai/policies/` : +En plus du `customPoliciesPath` explicite, failproofai découvre et charge automatiquement les fichiers de politiques depuis les répertoires `.failproofai/policies/` : | Niveau | Répertoire | Portée | |--------|------------|--------| | 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 (ex. `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 (par exemple `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 les 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 des 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 parcourus. Tous les fichiers correspondants des deux niveaux sont chargés (contrairement à `customPoliciesPath` qui utilise la règle premier-portée-gagne). +**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). -Consultez [Politiques personnalisées](/fr/custom-policies) pour plus de détails et d'exemples. +Consultez [Custom Policies](/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 à l'IA. Non requis pour la plupart des configurations. +Configuration du client LLM pour les politiques qui effectuent des appels IA. Non requis pour la plupart des configurations. ```json { @@ -189,19 +189,20 @@ Configuration du client LLM pour les politiques qui effectuent des appels à l'I ## Gestion de la configuration depuis la CLI -Les commandes `policies --install` et `policies --uninstall` écrivent dans le fichier de paramètres de hook de votre CLI d'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 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 : -- **Paramètres de la CLI d'agent** — indique à l'agent d'appeler `failproofai --hook ` à chaque utilisation d'outil : +- **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 portée `local` - - **GitHub Copilot CLI _(bêta)_** : `~/.copilot/hooks/failproofai.json` (utilisateur), `/.github/hooks/failproofai.json` (projet) — Copilot n'a pas de portée `local`. Les entrées de hook utilisent les champs de commande `bash`/`powershell` avec clé OS de Copilot et `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 d'enregistrement `events.jsonl` (non spécifié dans la documentation publique) contre davantage de sessions réelles. - - **Cursor Agent _(bêta)_** : `~/.cursor/hooks.json` (utilisateur), `/.cursor/hooks.json` (projet) — Cursor n'a pas de portée `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 de Cursor](https://cursor.com/docs/hooks) ; le fichier porte un marqueur `version: 1` au niveau supérieur. 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 transcript 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 portée `local`. Contrairement aux six autres CLIs, OpenCode **n'a pas de système de hook par commande externe** : il charge des plugins JS/TS in-process explicitement enregistrés via le tableau `plugin: []` dans `opencode.json` (la découverte automatique depuis `.opencode/plugins/` **n'est pas** la façon dont les plugins se chargent 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 de forme Claude du binaire en sémantique de plugin : `throw new Error()` pour le refus d'événement d'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 — seul canal de force-retry puisque `session.idle` est notification uniquement et que lever une exception 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`, 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 résident dans la base SQLite d'opencode à `~/.local/share/opencode/opencode.db` ; le visualiseur 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 sur différentes 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 portée `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/` fourni. 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 sous-processus ; le gestionnaire canonicalise 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` (Read / Write / Edit de Pi utilisent `path` plutôt que `file_path` ; mapper la clé de premier niveau permet à `block-env-files` et `block-secrets-write` de se déclencher — `block-read-outside-cwd` avait déjà 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. - - **Gemini CLI _(bêta)_** : `~/.gemini/settings.json` (utilisateur), `/.gemini/settings.json` (projet) — Gemini n'a pas de portée `local` (il documente une portée `system` à `/etc/gemini-cli/settings.json` que failproofai n'expose pas). Les entrées de hook utilisent la forme Claude `{type, command, timeout}` encapsulée dans le schéma de correspondance Gemini `{matcher, hooks: [...]}` avec `matcher: "*"` par défaut. Les événements sont en PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`) ; le gestionnaire les mappe vers les noms canoniques Claude via `GEMINI_EVENT_MAP`. Les noms d'outils sont en snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — le gestionnaire canonicalise via `GEMINI_TOOL_MAP` afin que les politiques intégrées existantes se déclenchent sans modification. L'évaluateur de politique émet la forme plate Gemini `{decision: "deny", reason}` (privilégiée selon la règle d'or exit-0 de Gemini), `{hookSpecificOutput: {hookEventName, additionalContext}}` pour l'injection de contexte sur BeforeAgent / AfterTool / SessionStart, et `{decision: "block", reason}` sur AfterAgent pour la sémantique de force-retry. La prise en charge de Gemini CLI est en **bêta** pendant que nous élargissons la couverture réelle. Consultez la [documentation des hooks Gemini CLI](https://geminicli.com/docs/hooks/). -- **`policies-config.json`** — indique à failproofai quelles politiques évaluer et avec quels paramètres (partagé entre toutes les CLIs d'agent) + - **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 six 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. + - **Gemini CLI _(bêta)_** : `~/.gemini/settings.json` (utilisateur), `/.gemini/settings.json` (projet) — Gemini n'a pas de niveau `local` (il documente un niveau `system` à `/etc/gemini-cli/settings.json` que failproofai n'expose pas). Les entrées de hook utilisent la forme `{type, command, timeout}` de Claude enveloppée dans le schéma de correspondance `{matcher, hooks: [...]}` de Gemini avec `matcher: "*"` par défaut. Les événements sont en PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`) ; le gestionnaire mappe vers les noms canoniques Claude via `GEMINI_EVENT_MAP`. Les noms d'outils sont en snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — le gestionnaire canonicalise via `GEMINI_TOOL_MAP` afin que les politiques intégrées existantes se déclenchent sans modification. L'évaluateur de politiques émet la forme plate `{decision: "deny", reason}` de Gemini (recommandée selon la règle d'or exit-0 de Gemini), `{hookSpecificOutput: {hookEventName, additionalContext}}` pour l'injection de contexte sur BeforeAgent / AfterTool / SessionStart, et `{decision: "block", reason}` sur AfterAgent pour la sémantique de nouvelle tentative forcée. La prise en charge de Gemini CLI est en **bêta** pendant que nous élargissons la couverture réelle. Consultez la [documentation des hooks Gemini CLI](https://geminicli.com/docs/hooks/). + - **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`. +- **`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|gemini` pour cibler un agent spécifique (séparé par des espaces ou répété pour n'importe quel sous-ensemble) : +Passez `--cli claude|codex|copilot|cursor|opencode|pi|gemini|hermes` pour cibler un agent spécifique (séparé par des espaces ou répété pour tout sous-ensemble) : ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +211,24 @@ 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 gemini --scope project +failproofai policies --install --cli hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` -Lorsque `--cli` est omis, `failproofai` détecte quelles CLIs d'agent sont installées (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`) : +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 gemini` / `which hermes`) : -- **Une seule CLI détectée** — la sélectionne automatiquement sans invite. -- **Plusieurs CLIs 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 préventive (↑↓ pour déplacer, Entrée pour sélectionner, ^C pour quitter). Le flux de désinstallation n'affiche que la section Detected. -- **Plusieurs CLIs détectées** lors d'une exécution non interactive (CI, pas de TTY) — installe pour toutes les CLIs détectées sans invite. -- **Aucune détectée** — repli sur `claude`, avec un avertissement qu'aucun binaire d'agent n'a été trouvé dans PATH ; la commande de hook est tout de même écrite pour s'activer dès que vous en installez une. +- **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. 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. --- -## Exemple : configuration au niveau projet avec des valeurs par défaut d'équipe +## Exemple : configuration au niveau projet avec les valeurs par défaut de l'équipe -Commitez `.failproofai/policies-config.json` dans votre dépôt : +Committez `.failproofai/policies-config.json` dans votre dépôt : ```json { @@ -245,4 +247,4 @@ Commitez `.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 ses surcharges 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 des substitutions personnelles sans affecter ses coéquipiers. \ No newline at end of file diff --git a/docs/fr/custom-policies.mdx b/docs/fr/custom-policies.mdx index 76fab844..23a6d39c 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 - appliquez des conventions, évitez la dérive, détectez les échecs, intégrez des systèmes externes" +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" 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 destructrices, 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. --- @@ -29,7 +29,7 @@ customPolicies.add({ }); ``` -Installez-le : +Installation : ```bash failproofai policies --install --custom ./my-policies.js @@ -41,10 +41,10 @@ failproofai policies --install --custom ./my-policies.js ### Option 1 : Par convention (recommandée) -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 seul. +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. ``` -# Niveau projet — commis dans git, partagé avec l'équipe +# Niveau projet — commité dans git, partagé avec l'équipe .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs @@ -52,15 +52,15 @@ Déposez des fichiers `*policies.{js,mjs,ts}` dans `.failproofai/policies/` et i ~/.failproofai/policies/my-policies.mjs ``` -**Comment ça fonctionne :** -- Les répertoires projet et utilisateur sont tous deux analysés (union — pas de priorité au premier scope trouvé) +**Fonctionnement :** +- Les répertoires du projet et de l'utilisateur sont tous les deux analysés (union — pas de premier-scope-wins) - 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 conjointement avec `--custom` explicite et les politiques intégrées +- Fonctionne en parallèle avec les fichiers `--custom` explicites et les politiques intégrées -Les politiques par 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 obtient automatiquement les mêmes règles — aucune configuration par développeur nécessaire. Au fur et à mesure que votre équipe découvre de nouveaux modes d'échec, ajoutez une politique et poussez. Ces politiques deviennent au fil du temps un standard de qualité vivant qui s'améliore à chaque contribution. +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. ### Option 2 : Chemin de fichier explicite @@ -72,19 +72,19 @@ failproofai policies --install --custom ./my-policies.js # Remplacer le chemin du fichier de politiques failproofai policies --install --custom ./new-policies.js -# Supprimer le chemin de politiques personnalisées de la configuration +# Supprimer le chemin des politiques personnalisées de la configuration failproofai policies --uninstall --custom ``` -Le chemin absolu résolu est stocké dans `policies-config.json` sous la clé `customPoliciesPath`. Le fichier est chargé à nouveau à chaque événement de hook - il n'y a pas de mise en cache entre les événements. +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. ### Utiliser les deux ensemble -Les politiques par convention et le fichier `--custom` explicite peuvent coexister. Ordre de chargement : +Les politiques de convention et le fichier `--custom` explicite 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 utilisateur (`~/.failproofai/policies/`, alphabétique) +3. Fichiers de convention de l'utilisateur (`~/.failproofai/policies/`, alphabétique) --- @@ -98,43 +98,43 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Enregistre une politique. Appelez cette méthode autant de fois que nécessaire pour plusieurs politiques dans le même fichier. +Enregistre une politique. Appelez cette fonction autant de fois que nécessaire pour plusieurs politiques dans le même fichier. ```ts customPolicies.add({ name: string; // requis - identifiant unique description?: string; // affiché dans la sortie de `failproofai policies` - match?: { events?: HookEventType[] }; // filtrer par type d'événement ; omettez pour correspondre à tous + match?: { events?: HookEventType[] }; // filtre par type d'événement ; omis pour correspondre à tous fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` ### Fonctions d'aide aux décisions -| Fonction | Effet | À utiliser quand | +| 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 devrait pas effectuer cette action | -| `instruct(message)` | Ajoute du contexte sans bloquer | Donne à l'agent un contexte supplémentaire pour rester sur la bonne voie | +| `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 | -`deny(message)` - le message apparaît dans Claude précédé de `"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. -Vous pouvez ajouter des conseils 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/`), de convention projet (`.failproofai-project/`) et 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 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. ### Messages allow informationnels -`allow(message)` autorise l'opération **et** envoie un message informationnel à Claude. Le message est délivré en tant que `additionalContext` dans la réponse stdout du gestionnaire de hook — le même mécanisme que `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 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. -| Fonction | Effet | À utiliser quand | +| Fonction | Effet | Utiliser quand | |----------|--------|----------| -| `allow(message)` | Autorise et envoie du contexte à Claude | Confirmer qu'une vérification a réussi, ou expliquer pourquoi elle a été ignorée | +| `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 | -Cas d'utilisation : -- **Confirmations de statut :** `allow("All CI checks passed.")` — indique à Claude que tout est au vert +Cas d'usage : +- **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 @@ -178,7 +178,7 @@ customPolicies.add({ | Événement | Quand il se déclenche | Contenu de `toolInput` | |-------|--------------|----------------------| | `PreToolUse` | Avant que Claude exécute un outil | L'entrée de l'outil (ex. `{ command: "..." }` pour Bash) | -| `PostToolUse` | Après qu'un outil s'est terminé | L'entrée de l'outil + `tool_result` (la sortie) | +| `PostToolUse` | Après la complétion d'un outil | L'entrée de l'outil + `tool_result` (la sortie) | | `Notification` | Quand Claude envoie une notification | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - les hooks doivent toujours retourner `allow()`, ils ne peuvent pas bloquer les notifications | | `Stop` | Quand la session Claude se termine | Vide | @@ -190,8 +190,8 @@ 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 `.add()` à l'intérieur) -4. Politiques de convention utilisateur `~/.failproofai/policies/` (fichiers alphabétiques, ordre `.add()` à l'intérieur) +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) Le premier `deny` court-circuite toutes les politiques suivantes. Tous les messages `instruct` sont accumulés et délivrés ensemble. @@ -218,7 +218,7 @@ customPolicies.add({ }); ``` -Tous les imports relatifs accessibles depuis le fichier d'entrée sont résolus. Cela est implémenté en réécrivant les imports `from "failproofai"` vers le chemin dist réel et en créant des fichiers `.mjs` temporaires pour assurer la compatibilité ESM. +Tous les imports relatifs accessibles depuis le fichier d'entrée sont résolus. Ceci est implémenté en réécrivant les imports `from "failproofai"` vers le chemin dist réel et en créant des fichiers `.mjs` temporaires pour assurer la compatibilité ESM. --- @@ -231,30 +231,30 @@ customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Se déclenche uniquement quand la session se termine + // Se déclenche uniquement à la fin de la session // ctx.session.transcriptPath contient le journal complet de la session return allow(); }, }); ``` -Omettez `match` entièrement pour se déclencher sur chaque type d'événement. +Omettez entièrement `match` pour se déclencher à chaque type d'événement. --- -## Gestion des erreurs et modes d'échec +## Gestion des erreurs et modes de défaillance -Les politiques personnalisées sont **fail-open** : les erreurs ne bloquent jamais les politiques intégrées et ne font pas planter le gestionnaire de hook. +Les politiques personnalisées sont **fail-open** : les erreurs ne bloquent jamais les politiques intégrées ni ne font planter le gestionnaire de hook. -| Échec | Comportement | +| 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 sont ignorées | -| Erreur de syntaxe/import (convention) | Erreur enregistrée ; ce fichier est ignoré, les autres fichiers de convention se chargent quand même | -| `fn` lève une exception à l'exécution | Erreur enregistrée ; ce hook est traité comme `allow` ; les autres hooks continuent | -| `fn` prend plus de 10 secondes | Timeout enregistré ; traité comme `allow` | -| Répertoire de convention manquant | Aucune politique de convention ne s'exécute ; pas d'erreur | +| 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 | Pour déboguer les erreurs de politiques personnalisées, surveillez le fichier de log : @@ -272,7 +272,7 @@ tail -f ~/.failproofai/hook.log // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// Prevent agent from writing to secrets/ directory +// Empêcher l'agent d'écrire dans le répertoire secrets/ customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -285,7 +285,7 @@ customPolicies.add({ }, }); -// Keep the agent on track: verify tests before committing +// Maintenir l'agent sur la bonne voie : vérifier les tests avant de commiter customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +300,7 @@ customPolicies.add({ }, }); -// Prevent unplanned dependency changes during freeze +// Prévenir les changements de dépendances non planifiés pendant le gel customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -328,9 +328,9 @@ 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, nettoyage des sorties et hooks de fin de session | -| `examples/convention-policies/security-policies.mjs` | Politiques de sécurité par convention (bloquer les écritures dans .env, empêcher 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) | +| `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) | ### Utiliser les exemples de fichiers explicites @@ -338,7 +338,7 @@ Le répertoire `examples/` contient des fichiers de politiques prêts à l'emplo failproofai policies --install --custom ./examples/policies-basic.js ``` -### Utiliser les exemples par convention +### Utiliser les exemples basés sur la convention ```bash # Copier au niveau du projet @@ -350,4 +350,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -Aucune commande d'installation nécessaire — les fichiers sont pris en compte automatiquement au prochain événement de hook. \ No newline at end of file +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 diff --git a/docs/fr/dashboard.mdx b/docs/fr/dashboard.mdx index c5452303..1e76570b 100644 --- a/docs/fr/dashboard.mdx +++ b/docs/fr/dashboard.mdx @@ -1,10 +1,10 @@ --- title: Tableau de bord -description: "Surveiller les sessions d'agents, examiner les appels d'outils et gérer les politiques" +description: "Surveillez les sessions d'agents, examinez les appels d'outils et gérez les politiques" icon: chart-line --- -Le tableau de bord failproofai est une application web locale qui vous permet de surveiller vos sessions d'agents IA et de gérer vos politiques. Voyez ce que vos agents ont fait pendant votre absence. +Le tableau de bord failproofai est une application web locale permettant de surveiller vos sessions d'agents IA et de gérer vos politiques. Découvrez 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 depuis le système de fichiers — vos dossiers de projets Claude Code et les fichiers de configuration failproofai. Aucune donnée n'est transmise à un service distant. +Le tableau de bord lit directement depuis le système de fichiers — vos dossiers de projets Claude Code et les fichiers de configuration failproofai. Rien n'est écrit vers un service distant. --- @@ -24,14 +24,14 @@ Le tableau de bord lit directement depuis le système de fichiers — vos dossie ### Projets -Liste tous les projets Claude Code, OpenAI Codex, GitHub Copilot CLI _(bêta)_, Cursor Agent _(bêta)_, OpenCode _(bêta)_, Pi _(bêta)_ et Gemini CLI _(bêta)_ 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/` explorés en solution de repli) 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 projets Gemini CLI sont découverts en analysant `~/.gemini/tmp//chats/session--.jsonl` (configurable via `GEMINI_SESSIONS_DIR`) et en récupérant le cwd canonique depuis le marqueur texte `.project_root` situé dans le même répertoire. Un projet utilisé par plusieurs interfaces 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|gemini`. +Liste tous les projets Claude Code, OpenAI Codex, GitHub Copilot CLI _(bêta)_, Cursor Agent _(bêta)_, OpenCode _(bêta)_, Pi _(bêta)_, Gemini CLI _(bêta)_ et Hermes 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 transcription 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/` comme solutions de repli) 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 transcriptions 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 projets Gemini CLI sont découverts en analysant `~/.gemini/tmp//chats/session--.jsonl` (configurable via `GEMINI_SESSIONS_DIR`) et en récupérant le répertoire de travail canonique depuis le marqueur texte `.project_root` associé ; les sessions de la passerelle Hermes sont lues directement depuis son stockage 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). Un projet utilisé par plusieurs interfaces 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 interface CLI spécifique ; l'URL conserve votre sélection sous la forme `?cli=claude|codex|copilot|cursor|opencode|pi|gemini|hermes`. 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` (émeraude), `OpenCode` (ambre), `Pi` (rose) et/ou `Gemini CLI` (ciel) +- Un badge CLI — `Claude Code` (orange), `OpenAI Codex` (violet), `GitHub Copilot` (bleu), `Cursor Agent` (émeraude), `OpenCode` (ambre), `Pi` (rose), `Gemini CLI` (bleu ciel) et/ou `Hermes` (indigo) - La date de la dernière activité de session -Cliquez sur un projet pour voir ses sessions. +Cliquez sur un projet pour afficher ses sessions. ### Sessions @@ -39,7 +39,7 @@ 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) +- Le nombre d'activités de hooks (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. @@ -47,44 +47,44 @@ Cliquez sur une session pour ouvrir le visualiseur de session. ### Visualiseur de session -Le visualiseur de session répond à la question essentielle pour les agents autonomes : qu'a fait l'agent, et est-il resté sur la bonne voie ? 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 ou Gemini CLI. Il affiche une chronologie de tout ce qui s'est passé durant une session : +Le visualiseur de session répond à la question essentielle pour les agents autonomes : qu'a fait l'agent, et est-il resté dans les limites prévues ? Un badge CLI à côté de l'en-tête indique si la session est une transcription Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Gemini CLI ou Hermes. Il affiche une chronologie de tout ce qui s'est passé lors d'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 retournée +- **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 retournée -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 (comptages 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 journaux** pour exporter la session. Pour les sessions Claude Code, Codex, Copilot, Cursor, Pi et Gemini, 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 reflétant 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, Pi et Gemini, vous obtenez la transcription JSONL originale 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`. ### Audit -Un rapport personnalisé décrivant le comportement réel de votre agent à travers les sessions passées. Exécute la même analyse que la CLI `failproofai audit`, mais le restitue sous la forme d'une affiche partageable plein écran et de quatre sections sous la ligne de flottaison : +Un rapport personnalisé sur la manière dont votre agent s'est réellement comporté au fil des sessions passées. Effectue le même scan que la commande `failproofai audit`, mais le restitue sous forme d'une affiche partageable sur écran unique + quatre sections sous le pli : -1. **Affiche** — occupe le premier viewport. Zone de capture PNG autonome avec le logotype failproof_ai + étiquette d'audit · index d'archétype (`№ NN of 08`) + date d'audit · score numérique (0–100) + pastille de rang en centile (`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`) + 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 en dehors de la zone de capture : `post your archetype` (X intent), `share on linkedin`, `download poster`. La capture est réalisée via `html-to-image` afin que le PNG corresponde pixel pour pixel au rendu à l'écran (bordures en pointillés, masque SVG du logo, dégradés, métriques de police — tout est préservé). -2. **Points forts** — liste de lignes ✓ apaisées décrivant les comportements que votre agent adopte déjà correctement, dérivés des données d'audit en direct (taux d'appels d'outils propre, aucun push direct sur main, zéro fuite de credentials, zéro tempête de tentatives) — chaque point n'est affiché que lorsque la politique concernée affiche un historique propre sur toute la fenêtre d'audit. -3. **Écarts** — tableau de ce qui est passé entre les mailles, classé par gravité : `quand · ce qui a glissé + la politique qui l'aurait intercepté · pastille de gravité · observé`, où la récurrence se lit `new` (une fois), `N× seen` (2–9 fois) ou `recurring` (10+). -4. **Comment s'améliorer** — liste de lignes apaisées, 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 toutes les corrections), et son bouton `[install all]` copie la commande combinée `failproofai policy add a b c …` pour toutes les politiques prescrites. -5. **Revenez mieux armé** — deux cartes côte à côte. À gauche : définir un rappel (sélecteur de cadence `3d` / `7d` / `14d` / `30d` ; persisté 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 les transmet au `POST /v0/invite` du serveur API. Le serveur API envoie un e-mail par destinataire depuis `invite@failproof.ai` avec l'expéditeur en Cc et `Reply-To` configuré, afin que le destinataire voie qui l'a invité et que l'expéditeur reçoive une copie dans sa boîte de réception. Les utilisateurs anonymes sont d'abord redirigés vers l'`AuthDialog` pour que l'e-mail de l'expéditeur soit connu avant l'envoi des invitations. Les droits d'accès et l'exécution des avantages feront l'objet d'une mise à jour ultérieure. +1. **Affiche** — occupe la première fenêtre d'affichage. Zone de capture PNG autonome avec le logo 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`) + bande de 3 mots-clés · ligne de rareté `// only N% of agents are this archetype` · tuile de signe graphique 8×8 pixels · pied de page `audit yours → failproof.ai`. Trois boutons de partage se trouvent juste en dehors de la zone de capture : `post your archetype` (intention X), `share on linkedin`, `download poster`. La capture s'effectue via `html-to-image` de sorte que le PNG correspond pixel pour pixel au rendu à l'écran (bordures en pointillés, masque de logo SVG, dégradés, métriques de polices — tout est conservé). +2. **Points forts** — liste de comportements que votre agent fait déjà correctement, sous forme de lignes avec une coche, dérivés des données d'audit en direct (taux d'appels d'outils propres, aucun push direct sur main, zéro fuite de credentials, zéro boucle de nouvelles tentatives) — chacun n'est affiché que lorsque la politique concernée a un bilan propre sur la fenêtre d'audit. +3. **Particularités** — tableau de ce qui a échappé au contrôle, classé par gravité : `quand · ce qui a échappé + la politique qui l'aurait intercepté · pastille de gravité · observé`, 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 recommandée : nom de la politique en blanc, description en une ligne, commande d'installation + bouton de copie à droite. L'en-tête de la 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 recommandée. +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 des avantages failproof — `invite a friend` ouvre une boîte de dialogue acceptant une liste d'adresses e-mail d'amis séparées par des virgules/espaces/sauts de ligne (max 10 par envoi), les envoie en POST à `/api/audit/invite`, qui les transmet au serveur API via `POST /v0/invite`. Le serveur API envoie un e-mail par destinataire depuis `invite@failproof.ai` avec l'expéditeur en Cc et `Reply-To` configuré, 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 `AuthDialog` afin que l'adresse e-mail de l'expéditeur soit connue avant l'envoi des invitations. La gestion des droits et avantages sera traitée ultérieurement. -Alimenté par le runtime `failproofai audit` — consultez [Audit CLI](/fr/cli/audit) pour le moteur d'analyse 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 dans `~/.failproofai/audit-dashboard.json` (mode `0600`, emplacement unique, les nouvelles exécutions écrasent l'ancien) afin que les revisites soient instantanées ; **les caches par transcript et le cache de 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 délai d'expiration, `/audit` retombe dans son état vide et invite à effectuer une nouvelle analyse. 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 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 banderole de progression rose épinglée reste visible en haut du viewport pendant l'exécution avec un compteur de temps écoulé, et le nouveau résultat se substitue 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 banderole devient rouge avec un message adapté selon le `RerunError.kind` (`timeout` / `network` / `post_failed`). L'état vide (pas de cache ou expiré) et l'état sans sessions (cache existant mais l'analyse n'a trouvé aucun transcript) sont présentés séparément. +Alimenté par le runtime `failproofai audit` — consultez [Audit CLI](/fr/cli/audit) pour le moteur de scan sous-jacent, les options prises en charge et les invariants de cache par transcription. 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 l'ancien) afin que les revisites soient instantanées ; **les caches par transcription et par résultat global sont tous deux rejetés à la lecture s'ils ont plus de 7 jours**, de sorte que le tableau de bord ne sert jamais silencieusement un résultat vieux d'une semaine — passé le 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 transcription et réanalyse chaque transcription 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 épinglée en haut de la fenêtre d'affichage s'affiche 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 ; en cas d'échec de la ré-analyse, le rapport précédent reste 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 sans sessions (cache existant mais le scan n'a trouvé aucune transcription) sont présentés séparément. ### Politiques -Une page à deux onglets pour gérer les politiques et consulter l'activité. +Une page à deux onglets pour gérer les politiques et examiner l'activité. - - Sélectionnez les CLIs d'agents que failproofai protège depuis un panneau unique — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi et Gemini CLI ont chacun une ligne avec l'état d'installation (`Active` / `Detected` / `Inactive`), le chemin des paramètres de portée utilisateur et un accent de couleur de marque. Cochez ou décochez les CLIs souhaités et cliquez sur `Apply changes` pour installer/désinstaller les différences en une seule étape. Les CLIs dont le binaire est détecté dans le PATH sont pré-cochés. - - Activez ou désactivez les politiques individuelles d'un simple clic (écrit dans `~/.failproofai/policies-config.json` — partagé entre tous les CLIs installés) - - Développez une politique pour configurer ses paramètres (pour les politiques qui prennent en charge `policyParams`) + - Sélectionnez plusieurs interfaces CLI d'agents que failproofai protège depuis un seul panneau — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Gemini CLI et Hermes disposent chacun d'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) + - Développez une politique pour configurer ses paramètres (pour les politiques prenant 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)_ / Gemini CLI _(bêta)_), nom de politique ou identifiant de session - - Chaque ligne affiche : horodatage, nom de politique, décision, badge CLI (orange = Claude Code, violet = OpenAI Codex, bleu = GitHub Copilot, émeraude = Cursor Agent, ambre = OpenCode, rose = Pi, ciel = Gemini CLI), nom d'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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`) 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)_ / Gemini CLI _(bêta)_ / Hermes), 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, émeraude = Cursor Agent, ambre = OpenCode, rose = Pi, bleu ciel = Gemini CLI, indigo = Hermes), nom de l'outil, identifiant de session et la raison des décisions deny/instruct + - Cliquez sur un identifiant de session pour ouvrir sa transcription — 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`, Hermes `~/.hermes/state.db`) et affiche le badge CLI correspondant dans l'en-tête @@ -92,7 +92,7 @@ Une page à deux onglets pour gérer les politiques et consulter l'activité. ## Actualisation automatique -Le tableau de bord dispose d'un bouton d'actualisation automatique dans la navigation principale. Lorsqu'il est activé, la page actuelle se rafraîchit 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. +Le tableau de bord dispose d'un bouton de basculement 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. --- @@ -120,13 +120,13 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## Accès depuis un hôte autre que localhost -Lorsque vous exécutez le tableau de bord en **mode développement** (`npm run dev`) et 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 comme : +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 comme : ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Il s'agit de Next.js qui bloque l'accès cross-origin à son websocket HMR (rechargement à chaud des modules), qui est une fonctionnalité réservée au mode développement. Pour autoriser votre hôte, utilisez l'option `--allowed-origins` : +Next.js bloque l'accès cross-origin à son websocket HMR (rechargement à chaud des modules), qui est 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 @@ -145,5 +145,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Ceci 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 de développement cross-origin. +Ceci s'applique uniquement au mode développement. Lorsque vous exécutez `failproofai` (mode production), il n'y a pas de websocket HMR ni de problème de ressource de développement cross-origin. \ No newline at end of file diff --git a/docs/fr/examples.mdx b/docs/fr/examples.mdx index 089071f5..28f9fc0e 100644 --- a/docs/fr/examples.mdx +++ b/docs/fr/examples.mdx @@ -1,10 +1,10 @@ --- title: Exemples -description: "Comment configurer des hooks pour Claude Code et le Agents SDK" +description: "Comment configurer des hooks pour Claude Code et l'Agents SDK" icon: book-open --- -Des exemples prêts à l'emploi pour les scénarios courants. Chacun montre comment installer et ce à quoi s'attendre. +Des exemples prêts à l'emploi pour les scénarios courants. Chacun montre comment installer et à quoi s'attendre. --- @@ -41,9 +41,9 @@ Failproof AI s'intègre à Claude Code via son [système de hooks](https://docs. --- -## Configurer des hooks pour le Agents SDK +## Configurer des hooks pour l'Agents SDK -Si vous développez avec le [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), vous pouvez utiliser le même système de hooks de manière programmatique. +Si vous développez avec l'[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), vous pouvez utiliser le même système de hooks de manière programmatique. @@ -52,7 +52,7 @@ Si vous développez avec le [Agents SDK](https://docs.anthropic.com/en/docs/agen ``` - Passez des commandes de hook lors de la création de votre processus d'agent. Les hooks se déclenchent de la même façon que dans Claude Code — via du JSON sur stdin/stdout : + Passez des commandes de hook lors de la création de votre processus d'agent. Les hooks se déclenchent de la même façon que dans Claude Code — via JSON en stdin/stdout : ```bash failproofai --hook PreToolUse # appelé avant chaque outil @@ -86,7 +86,7 @@ Si vous développez avec le [Agents SDK](https://docs.anthropic.com/en/docs/agen --- -## Bloquer les commandes destructrices +## Bloquer les commandes destructives La configuration la plus courante — empêcher les agents de causer des dommages irréversibles. @@ -98,25 +98,25 @@ Ce que cela fait : - `block-sudo` — bloque toutes les commandes `sudo` - `block-rm-rf` — bloque la suppression récursive de fichiers - `block-force-push` — bloque `git push --force` -- `block-curl-pipe-sh` — bloque l'exécution de scripts distants via un pipe vers le shell +- `block-curl-pipe-sh` — bloque l'exécution directe de scripts distants via un pipe vers le shell --- ## Empêcher la fuite de secrets -Empêchez les agents de voir ou de divulguer des identifiants dans la sortie des outils. +Évitez que les agents voient ou divulguent des identifiants dans la sortie des outils. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -Ces politiques se déclenchent sur `PostToolUse` — après l'exécution d'un outil, elles nettoient la sortie avant que l'agent ne la consulte. +Ces politiques se déclenchent sur `PostToolUse` — après l'exécution d'un outil, elles nettoient la sortie avant que l'agent ne la voie. --- -## Recevoir des alertes Slack lorsque les agents ont besoin d'attention +## Recevoir des alertes Slack quand les agents ont besoin d'attention -Utilisez le hook de notification pour transférer les alertes d'inactivité vers Slack. +Utilisez le hook de notification pour transmettre les alertes d'inactivité à Slack. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -150,7 +150,7 @@ customPolicies.add({ }); ``` -Installez-le : +Installez-la : ```bash SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js @@ -160,7 +160,7 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c ## Maintenir les agents sur une branche -Empêchez les agents de changer de branche ou de pousser vers des branches protégées. +Empêchez les agents de changer de branche ou de pousser sur des branches protégées. ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -184,7 +184,7 @@ customPolicies.add({ ## Exiger des tests avant les commits -Rappeler aux agents d'exécuter les tests avant de faire un commit. +Rappelez aux agents d'exécuter les tests avant de committer. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -208,7 +208,7 @@ customPolicies.add({ ## Verrouiller un dépôt de production -Commitez une configuration au niveau du projet afin que tous les développeurs de votre équipe bénéficient des mêmes politiques. +Commitez une configuration au niveau du projet afin que chaque développeur de votre équipe bénéficie des mêmes politiques. Créez `.failproofai/policies-config.json` dans votre dépôt : @@ -244,7 +244,7 @@ Chaque membre de l'équipe ayant failproofai installé récupérera automatiquem ## Établir un standard qualité à l'échelle de l'organisation avec des politiques de convention -La configuration la plus impactante : commitez `.failproofai/policies/` dans votre dépôt avec des politiques adaptées à votre projet. Tous les membres de l'équipe les récupèrent automatiquement — sans commandes d'installation ni modifications de configuration. +La configuration la plus efficace : commitez `.failproofai/policies/` dans votre dépôt avec des politiques adaptées à votre projet. Chaque membre de l'équipe les obtient automatiquement — sans commandes d'installation, sans modifications de configuration. @@ -256,8 +256,8 @@ La configuration la plus impactante : commitez `.failproofai/policies/` dans vot // .failproofai/policies/team-policies.mjs import { customPolicies, allow, deny, instruct } from "failproofai"; - // Enforce your team's preferred package manager - // (or enable the built-in prefer-package-manager policy instead) + // Impose le gestionnaire de paquets préféré de votre équipe + // (ou activez plutôt la politique intégrée prefer-package-manager) customPolicies.add({ name: "enforce-bun", match: { events: ["PreToolUse"] }, @@ -269,7 +269,7 @@ La configuration la plus impactante : commitez `.failproofai/policies/` dans vot }, }); - // Remind the agent to run tests before committing + // Rappelle à l'agent d'exécuter les tests avant de committer customPolicies.add({ name: "test-before-commit", match: { events: ["PreToolUse"] }, @@ -290,7 +290,7 @@ La configuration la plus impactante : commitez `.failproofai/policies/` dans vot ``` - Au fil des nouveaux problèmes rencontrés par votre équipe, ajoutez des politiques et poussez-les. Tout le monde reçoit la mise à jour au prochain `git pull`. Ces politiques deviennent un standard qualité vivant qui évolue avec votre équipe. + Au fur et à mesure que votre équipe rencontre de nouveaux types d'erreurs, ajoutez des politiques et poussez-les. Tout le monde reçoit la mise à jour au prochain `git pull`. Ces politiques deviennent un standard qualité vivant qui évolue avec votre équipe. @@ -302,6 +302,6 @@ Le répertoire [`examples/`](https://github.com/failproofai/failproofai/tree/mai | Fichier | Ce qu'il illustre | |---------|-------------------| -| `policies-basic.js` | Politiques de base — blocage des écritures en production, des force-push et des scripts piped | +| `policies-basic.js` | Politiques de démarrage — bloquer les écritures en production, les force-push, les scripts pipés | | `policies-notification.js` | Alertes Slack pour les notifications d'inactivité et la fin de session | | `policies-advanced/index.js` | Imports transitifs, hooks asynchrones, nettoyage de la sortie PostToolUse, gestion de l'événement Stop | \ No newline at end of file diff --git a/docs/fr/for-agents.mdx b/docs/fr/for-agents.mdx index 88569c6e..10e57243 100644 --- a/docs/fr/for-agents.mdx +++ b/docs/fr/for-agents.mdx @@ -1,9 +1,9 @@ --- title: "Pour les agents" -description: "Ajoutez les connaissances Failproof AI à votre agent de codage en une seule commande. Compatible avec Claude Code, Cursor, Windsurf et bien d'autres." +description: "Ajoutez la documentation Failproof AI à votre agent de développement en une seule commande. Compatible avec Claude Code, Cursor, Windsurf et bien d'autres." --- -Ajoutez la référence complète de Failproof AI à votre agent de codage en une seule commande. Compatible avec Claude Code, Cursor, Windsurf et tout autre agent prenant en charge les skills. +Ajoutez la référence complète de Failproof AI à votre agent de développement en une seule commande. Compatible avec Claude Code, Cursor, Windsurf et tout autre agent prenant en charge les skills. ```bash npx skills add https://docs.befailproof.ai @@ -13,8 +13,8 @@ npx skills add https://docs.befailproof.ai ## Ce que couvre le skill -| Domaine | Contenu inclus | -|---------|----------------| +| Domaine | Contenu | +|---------|---------| | Politiques | Noms des politiques intégrées, types d'événements, paramètres, activation/désactivation | | Politiques personnalisées | `customPolicies.add()`, filtres de correspondance, API `allow`/`deny`/`instruct` | | Objet de contexte | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | @@ -25,9 +25,9 @@ npx skills add https://docs.befailproof.ai ## Le skill est-il complet ? -Mintlify génère `llms.txt` à partir de toutes les pages de la navigation. La documentation Failproof AI couvre l'API complète — chaque politique, option et exemple est inclus. Si vous constatez qu'il manque quelque chose, la source se trouve à `https://docs.befailproof.ai/llms-full.txt`. +Mintlify génère `llms.txt` à partir de toutes les pages de la navigation. La documentation Failproof AI couvre l'intégralité de l'API — chaque politique, option et exemple est inclus. Si vous constatez qu'il manque quelque chose, la source se trouve à `https://docs.befailproof.ai/llms-full.txt`. -Pour un contexte ciblé, créez un lien directement vers une page spécifique : +Pour un contexte ciblé, faites un lien directement vers une page spécifique : ```bash # Uniquement l'API des politiques personnalisées diff --git a/docs/fr/getting-started.mdx b/docs/fr/getting-started.mdx index eabc11af..38af4f5f 100644 --- a/docs/fr/getting-started.mdx +++ b/docs/fr/getting-started.mdx @@ -1,13 +1,13 @@ --- -title: Prise en main -description: "Installez failproofai, activez les politiques et laissez vos agents s'exécuter en toute fiabilité" +title: Démarrage +description: "Installez failproofai, activez les politiques et laissez vos agents s'exécuter de manière fiable" icon: rocket --- ## Prérequis - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (optionnel - uniquement nécessaire pour compiler depuis les sources) +- **Bun** >= 1.3.0 (optionnel - nécessaire uniquement pour la compilation depuis les sources) --- @@ -31,15 +31,15 @@ bun add -g failproofai - Les politiques sont des règles qui s'exécutent avant et après chaque appel d'outil d'un agent. Elles interceptent les commandes destructrices, les fuites de secrets et autres modes de défaillance avant qu'ils ne causent des dommages. + Les politiques sont des règles qui s'exécutent avant et après chaque appel d'outil d'agent. Elles interceptent les commandes destructrices, les fuites de secrets et d'autres modes d'échec avant qu'ils ne causent des dommages. ```bash failproofai policies --install ``` - Cette commande inscrit des entrées de hook dans vos CLIs d'agents installés (le `~/.claude/settings.json` de Claude Code, le `~/.codex/hooks.json` d'OpenAI Codex, le `~/.copilot/hooks/failproofai.json` de GitHub Copilot CLI, le `~/.cursor/hooks.json` de Cursor Agent, le shim de plugin généré par OpenCode dans `~/.config/opencode/plugins/failproofai.mjs` ainsi qu'une entrée dans le tableau `plugin` de `~/.config/opencode/opencode.json`, le `~/.pi/agent/settings.json` de Pi, ou le `~/.gemini/settings.json` de Gemini CLI). Si plusieurs CLIs sont présents, vous serez invité à en sélectionner un ; passez `--cli claude codex copilot cursor opencode pi gemini` (ou tout sous-ensemble) pour ignorer cette invite. + Cette commande inscrit des entrées de hook dans vos CLIs d'agent installés (le `~/.claude/settings.json` de Claude Code, le `~/.codex/hooks.json` d'OpenAI Codex, le `~/.copilot/hooks/failproofai.json` de GitHub Copilot CLI, le `~/.cursor/hooks.json` de Cursor Agent, le shim de plugin généré par OpenCode à `~/.config/opencode/plugins/failproofai.mjs` ainsi qu'une entrée d'enregistrement dans le tableau `plugin` de `~/.config/opencode/opencode.json`, le `~/.pi/agent/settings.json` de Pi, le `~/.gemini/settings.json` de Gemini CLI, ou le `~/.hermes/config.yaml` de Hermes). Si plusieurs sont présents, une invite s'affichera ; passez `--cli claude codex copilot cursor opencode pi gemini hermes` (tout sous-ensemble) pour ignorer l'invite. - La prise en charge de GitHub Copilot CLI, Cursor Agent, OpenCode, Pi et Gemini CLI est en **bêta** — installez avec `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi` ou `--cli gemini`. + La prise en charge de GitHub Copilot CLI, Cursor Agent, OpenCode, Pi et Gemini CLI est en **bêta** — installez avec `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi` ou `--cli gemini`. Hermes (hermes-agent, une passerelle Slack/Telegram) s'installe en portée utilisateur avec `--cli hermes` et constitue **également** une source d'audit hors ligne. ```bash failproofai policies --install --scope project @@ -49,6 +49,7 @@ bun add -g failproofai failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project + failproofai policies --install --cli hermes --scope user failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` @@ -66,8 +67,8 @@ bun add -g failproofai Ouvre un tableau de bord local à l'adresse `http://localhost:8020` où vous pouvez parcourir les sessions, inspecter les appels d'outils et gérer les politiques. - - Démarrez Claude Code comme d'habitude. Si l'agent tente quelque chose de risqué, failproofai l'intercepte automatiquement. Laissez-le tourner sans surveillance et examinez ce qui s'est passé dans le tableau de bord. + + Démarrez Claude Code comme d'habitude. Si l'agent tente quelque chose de risqué, failproofai l'intercepte automatiquement. Laissez-le tourner sans surveillance et consultez ce qui s'est passé dans le tableau de bord. @@ -75,7 +76,7 @@ bun add -g failproofai ## Fonctionnement des politiques -À chaque fois qu'un agent exécute un outil, Claude Code appelle failproofai comme sous-processus : +Chaque fois qu'un agent exécute un outil, Claude Code appelle failproofai en tant que sous-processus : ```text Claude Code → failproofai --hook PreToolUse → reads stdin JSON @@ -87,7 +88,7 @@ Chaque politique retourne l'une des trois décisions suivantes : - **allow** - l'agent continue normalement - **deny** - l'action est bloquée et l'agent est informé de la raison -- **instruct** - du contexte supplémentaire est ajouté au prompt de l'agent +- **instruct** - du contexte supplémentaire est ajouté à l'invite de l'agent Les politiques s'exécutent dans votre processus local. Rien n'est envoyé à un service distant. @@ -95,9 +96,9 @@ Les politiques s'exécutent dans votre processus local. Rien n'est envoyé à un --- -## Définir des politiques d'équipe avec les politiques par convention +## Configurer les politiques d'équipe avec les politiques basées sur les conventions -La façon la plus rapide d'établir des standards de qualité au sein de votre équipe est la convention `.failproofai/policies/`. Déposez des fichiers de politiques dans ce répertoire et ils sont chargés automatiquement — pas d'options, pas de modifications de configuration, pas de commandes d'installation. +La manière la plus rapide d'établir des standards de qualité au sein de votre équipe est la convention `.failproofai/policies/`. Déposez des fichiers de politique dans ce répertoire et ils sont chargés automatiquement — sans indicateurs, sans modifications de configuration, sans commandes d'installation. @@ -105,8 +106,8 @@ La façon la plus rapide d'établir des standards de qualité au sein de votre mkdir -p .failproofai/policies ``` - - Copiez les exemples de démarrage ou écrivez les vôtres : + + Copiez les exemples de démarrage ou rédigez les vôtres : ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -137,12 +138,12 @@ La façon la plus rapide d'établir des standards de qualité au sein de votre git commit -m "Add team quality policies" ``` - Chaque membre de l'équipe qui a failproofai installé récupère ces politiques automatiquement. Aucune configuration individuelle n'est nécessaire. + Chaque membre de l'équipe ayant failproofai installé récupère ces politiques automatiquement. Aucune configuration par développeur n'est nécessaire. -Committez `.failproofai/policies/` dans votre dépôt pour que toute l'équipe partage les mêmes standards. Au fur et à mesure que votre équipe découvre de nouveaux modes de défaillance, ajoutez des politiques et poussez-les — tout le monde reçoit la mise à jour au prochain `git pull`. Au fil du temps, ces politiques deviennent un standard de qualité vivant qui ne cesse de s'améliorer. +Validez `.failproofai/policies/` dans votre dépôt afin que toute l'équipe partage les mêmes standards. Au fur et à mesure que votre équipe découvre de nouveaux modes d'échec, ajoutez des politiques et poussez — tout le monde reçoit la mise à jour au prochain `git pull`. Au fil du temps, ces politiques deviennent un standard de qualité vivant qui ne cesse de s'améliorer. --- @@ -156,8 +157,8 @@ Toute la configuration et les journaux restent sur votre machine : | `~/.failproofai/policies-config.json` | Configuration globale des politiques | | `~/.failproofai/hook-activity.jsonl` | Historique d'exécution des hooks | | `~/.failproofai/hook.log` | Journal de débogage pour les erreurs de hooks personnalisés | -| `.failproofai/policies-config.json` | Configuration par projet (commitée) | -| `.failproofai/policies-config.local.json` | Remplacements personnels (ignorés par git) | +| `.failproofai/policies-config.json` | Configuration par projet (validée dans git) | +| `.failproofai/policies-config.local.json` | Substitutions personnelles (ignorées par git) | --- diff --git a/docs/fr/introduction.mdx b/docs/fr/introduction.mdx index 25b3fb97..7bafb798 100644 --- a/docs/fr/introduction.mdx +++ b/docs/fr/introduction.mdx @@ -1,15 +1,15 @@ --- title: "Failproof AI" -description: "FailproofAI donne aux agents IA 39 politiques de défaillance intégrées qui détectent les boucles, les fuites de secrets, les appels d'outils destructeurs et bien plus encore, en une seule installation." +description: "FailproofAI offre aux agents IA 39 politiques de sécurité intégrées qui détectent les boucles, les fuites de secrets, les appels d'outils destructeurs, et bien plus encore, en une seule installation." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -Hooks et politiques pour la **gestion des défaillances de l'IA**, la **récupération d'erreurs** et la **fiabilité des LLM**. Gardez vos agents IA fiables et autonomes sur **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI** et le **Agents SDK**. +Hooks et politiques pour la **gestion des défaillances IA**, la **récupération après erreur** et la **fiabilité des LLM**. Gardez vos agents IA fiables et autonomes sur **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, **Hermes** et l'**Agents SDK**. -Les agents IA échouent de manière prévisible. Ils exécutent des commandes destructrices, exposent des secrets, dérivent hors de leur tâche, se retrouvent bloqués dans des boucles ou poussent directement sur main. Sans surveillance, de petites défaillances s'enchaînent et provoquent des pannes, des identifiants compromis et du travail perdu. +Les agents IA échouent de manière prévisible. Ils exécutent des commandes destructrices, exposent des secrets, dérivent hors de leur tâche, se retrouvent bloqués dans des boucles ou poussent directement sur la branche principale. Laissées sans surveillance, de petites défaillances se transforment en pannes, en identifiants compromis et en travail perdu. -FailproofAI résout ce problème grâce à des **politiques**. Ces règles s'accrochent à chaque appel d'outil de l'agent pour **détecter les défaillances**, les **atténuer** (bloquer, instruire, assainir) et **vous alerter** lorsqu'un problème nécessite votre attention. Un tableau de bord local vous permet de consulter chaque appel d'outil, chaque défaillance d'agent et chaque action corrective après coup. +FailproofAI résout ce problème grâce aux **politiques**. Ces règles s'accrochent à chaque appel d'outil de l'agent pour **détecter les défaillances**, **les atténuer** (bloquer, instruire, assainir) et **vous alerter** lorsqu'une intervention est nécessaire. Un tableau de bord local vous permet de consulter chaque appel d'outil, chaque défaillance d'agent et chaque action de récupération après coup. Aucune donnée ne quitte votre machine. @@ -26,11 +26,11 @@ Aucune donnée ne quitte votre machine. - Voyez ce que vos agents ont fait pendant votre absence. Parcourez les sessions, inspectez les appels d'outils, examinez où les politiques se sont déclenchées. + Voyez ce que vos agents ont fait pendant votre absence. Parcourez les sessions, inspectez les appels d'outils, consultez où les politiques ont été déclenchées. - - Ajustez n'importe quelle politique sans code. Définissez des listes d'autorisation, des branches protégées ou des seuils par projet ou de manière globale. + + Ajustez n'importe quelle politique sans code. Définissez des listes d'autorisation, des branches protégées ou des seuils par projet ou globalement. @@ -54,4 +54,4 @@ failproofai policies --install # enable policies (or skip — `failproofai` wi failproofai # launch the dashboard ``` -Consultez le guide [Prise en main](/fr/getting-started) pour une présentation complète. \ No newline at end of file +Consultez le guide [Premiers pas](/fr/getting-started) pour une présentation complète. \ No newline at end of file diff --git a/docs/fr/package-aliases.mdx b/docs/fr/package-aliases.mdx index 9f4e1398..db2dcea3 100644 --- a/docs/fr/package-aliases.mdx +++ b/docs/fr/package-aliases.mdx @@ -16,11 +16,11 @@ bun add -g failproofai --- -## Pourquoi nous possédons les noms d'alias +## Pourquoi nous détenons les noms d'alias -Le typosquatting est une attaque courante sur la chaîne d'approvisionnement logicielle, où un acteur malveillant enregistre un nom de package à une frappe près d'un package populaire. Les utilisateurs qui font une faute de frappe lors de la commande d'installation se retrouvent à exécuter du code contrôlé par l'attaquant avec un accès système complet — exactement le type de menace que Failproof AI est conçu pour contrer. +Le typosquatting est une attaque courante sur la chaîne d'approvisionnement logicielle, où un acteur malveillant enregistre un nom de package qui ne diffère que d'une frappe du package populaire ciblé. Les utilisateurs qui se trompent en tapant la commande d'installation se retrouvent à exécuter du code contrôlé par un attaquant avec un accès complet au système — exactement le type de menace que Failproof AI est conçu pour contrer. -Pour éliminer cette surface d'attaque, **nous possédons de manière préventive toutes les fautes d'orthographe courantes et variantes de formatage** de `failproofai` sur npm. Aucun de ces noms ne peut être enregistré par un tiers. Chacun est un proxy léger qui installe et délègue au vrai package `failproofai`. +Pour éliminer cette surface d'attaque, **nous prenons préventivement possession de toutes les fautes d'orthographe courantes et variantes de formatage** de `failproofai` sur npm. Aucun de ces noms ne peut être enregistré par un tiers. Chacun est un proxy léger qui installe et délègue au véritable package `failproofai`. --- @@ -55,7 +55,7 @@ Pour éliminer cette surface d'attaque, **nous possédons de manière préventiv | `faliproof-ai` | ✅ Publié | | `faliproofai` | ⏳ En attente du support npm | -> **Pourquoi en attente ?** La politique anti-spam de npm bloque les noms qui, après suppression de la ponctuation et vérification de similarité, correspondent à un package existant. Nous avons contacté le support npm pour réserver ces noms à des fins de protection contre le squatting. Ils seront activés une fois approuvés. +> **Pourquoi en attente ?** La politique anti-spam de npm bloque les noms qui se normalisent vers la même chaîne qu'un package existant après suppression de la ponctuation et vérification de similarité. Nous avons contacté le support npm pour réserver ces noms à des fins de protection contre le typosquatting. Ils seront activés une fois approuvés. Vous pouvez vérifier que tout alias publié nous appartient : @@ -70,8 +70,8 @@ npm info failproof Chaque package alias : -1. Liste `failproofai` comme dépendance — ainsi le vrai package (y compris la configuration de son hook `postinstall`) s'exécute lors de l'installation -2. Expose un binaire portant son propre nom (par exemple `failprof-ai`) qui transfère tous les arguments au binaire `failproofai` +1. Liste `failproofai` comme dépendance — ainsi, le véritable package (y compris la configuration de son hook `postinstall`) s'exécute lors de l'installation +2. Expose un binaire portant son propre nom (par ex. `failprof-ai`) qui transmet tous les arguments au binaire `failproofai` Le proxy est un script Node de deux lignes ; il ne contient aucune logique, aucun appel réseau, et ne collecte aucune donnée au-delà de ce que fait `failproofai` lui-même. @@ -79,4 +79,4 @@ Le proxy est un script Node de deux lignes ; il ne contient aucune logique, aucu ## Si vous trouvez un nom que nous avons manqué -Ouvrez une issue sur [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) et nous l'enregistrerons. \ No newline at end of file +Ouvrez un ticket sur [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) et nous l'enregistrerons. \ No newline at end of file diff --git a/docs/fr/testing.mdx b/docs/fr/testing.mdx index 13699617..a3d9feb8 100644 --- a/docs/fr/testing.mdx +++ b/docs/fr/testing.mdx @@ -4,26 +4,26 @@ description: "Tests unitaires, tests E2E et utilitaires de test" icon: flask-vial --- -failproofai dispose de deux suites de tests : les **tests unitaires** (rapides, avec mocks) et les **tests de bout en bout** (invocations réelles de sous-processus). +failproofai dispose de deux suites de tests : des **tests unitaires** (rapides, avec mocks) et des **tests end-to-end** (invocations réelles de sous-processus). --- -## Lancer les tests +## Exécuter les tests ```bash -# Exécuter tous les tests unitaires une seule fois +# Lancer tous les tests unitaires une fois bun run test:run -# Exécuter les tests unitaires en mode watch +# Lancer les tests unitaires en mode watch bun run test -# Exécuter les tests E2E (configuration requise — voir ci-dessous) +# Lancer les tests E2E (nécessite une configuration - voir ci-dessous) bun run test:e2e -# Vérifier les types sans compiler +# Vérifier les types sans compilation bunx tsc --noEmit -# Lint +# Linter bun run lint ``` @@ -36,7 +36,7 @@ Les tests unitaires se trouvent dans `__tests__/` et utilisent [Vitest](https:// ```text __tests__/ hooks/ - builtin-policies.test.ts # Logique de chaque politique intégrée + builtin-policies.test.ts # Logique de politique pour chaque builtin hooks-config.test.ts # Chargement de la config et fusion des scopes policy-evaluator.test.ts # Injection de paramètres et ordre d'évaluation custom-hooks-registry.test.ts # Registre globalThis : add/get/clear @@ -108,13 +108,13 @@ describe("block-sudo", () => { --- -## Tests de bout en bout +## Tests end-to-end -Les tests E2E invoquent le vrai binaire `failproofai` en tant que sous-processus, lui transmettent un payload JSON via stdin et vérifient la sortie stdout ainsi que le code de sortie. Cette approche teste le chemin d'intégration complet utilisé par Claude Code. +Les tests E2E invoquent le véritable binaire `failproofai` en tant que sous-processus, envoient un payload JSON sur stdin et vérifient la sortie stdout ainsi que le code de sortie. Ils testent le chemin d'intégration complet qu'utilise Claude Code. ### Configuration -Les tests E2E exécutent le binaire directement depuis les sources du dépôt. Avant la première exécution, compilez le bundle CJS que les fichiers de hooks personnalisés utilisent lors de l'import depuis `'failproofai'` : +Les tests E2E exécutent le binaire directement depuis les sources du dépôt. Avant le premier lancement, compilez le bundle CJS que les fichiers de hooks personnalisés utilisent lors de leurs imports depuis `'failproofai'` : ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -126,33 +126,33 @@ Puis lancez les tests : bun run test:e2e ``` -Recompilez `dist/` chaque fois que vous modifiez l'API publique des hooks (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` ou `src/hooks/policy-types.ts`). +Recompilez `dist/` à chaque modification de l'API publique des hooks (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` ou `src/hooks/policy-types.ts`). ### Structure des tests E2E ```text __tests__/e2e/ helpers/ - hook-runner.ts # Lance le binaire, transmet le payload JSON, capture le code de sortie + stdout + stderr + hook-runner.ts # Démarre le binaire, envoie le JSON du payload, capture le code de sortie + stdout + stderr fixture-env.ts # Répertoires temporaires isolés par test avec fichiers de config - payloads.ts # Fabriques de payloads fidèles à Claude pour chaque type d'événement + payloads.ts # Factories de payloads fidèles à Claude pour chaque type d'événement hooks/ - builtin-policies.e2e.test.ts # Chaque politique intégrée avec un vrai sous-processus + builtin-policies.e2e.test.ts # Chaque politique builtin avec un vrai sous-processus custom-hooks.e2e.test.ts # Chargement et évaluation des hooks personnalisés - config-scopes.e2e.test.ts # Fusion de config entre les scopes projet/local/global + config-scopes.e2e.test.ts # Fusion de la config entre les scopes projet/local/global policy-params.e2e.test.ts # Injection de paramètres pour chaque politique paramétrée ``` ### Utiliser les utilitaires E2E -**`FixtureEnv`** — environnement isolé par test : +**`FixtureEnv`** - environnement isolé par test : ```typescript import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - répertoire temporaire ; à passer comme payload.cwd pour charger .failproofai/policies-config.json -// env.home - répertoire home isolé ; aucune fuite depuis le vrai ~/.failproofai +// env.cwd - répertoire temporaire ; à passer en payload.cwd pour charger .failproofai/policies-config.json +// env.home - répertoire home isolé ; aucune fuite de ~/.failproofai réel env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -162,9 +162,9 @@ env.writeConfig({ }); ``` -`createFixtureEnv()` enregistre automatiquement le nettoyage via `afterEach`. +`createFixtureEnv()` enregistre automatiquement un nettoyage via `afterEach`. -**`runHook`** — invoquer le binaire : +**`runHook`** - invoquer le binaire : ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** — fabriques de payloads prêtes à l'emploi : +**`Payloads`** - factories de payloads prêtes à l'emploi : ```typescript Payloads.preToolUse.bash(command, cwd) @@ -237,24 +237,24 @@ describe("block-rm-rf (E2E)", () => { |----------|----------------|--------| | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | -| instruct (hors Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | +| Instruct (hors Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | | Stop instruct | `2` | stdout vide ; raison dans stderr | -| allow | `0` | chaîne vide | +| Allow | `0` | chaîne vide | ### Configuration Vitest Les tests E2E utilisent `vitest.config.e2e.mts` avec : -- `environment: "node"` — aucun global de navigateur requis -- `pool: "forks"` — isolation réelle des processus (les tests lancent des sous-processus) -- `testTimeout: 20_000` — 20 secondes par test (démarrage du binaire + évaluation du hook) +- `environment: "node"` - aucune variable globale navigateur requise +- `pool: "forks"` - isolation réelle des processus (les tests lancent des sous-processus) +- `testTimeout: 20_000` - 20 secondes par test (démarrage du binaire + évaluation du hook) -Le pool `forks` est essentiel : les workers basés sur des threads partagent `globalThis`, ce qui peut interférer avec les tests qui lancent des sous-processus. Les forks basés sur des processus évitent ce problème. +Le pool `forks` est important : les workers basés sur des threads partagent `globalThis`, ce qui peut interférer avec les tests qui lancent des sous-processus. Les forks basés sur des processus évitent ce problème. --- ## Intégration continue -L'exécution complète en CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) doit passer avant toute fusion. La suite E2E s'exécute en parallèle dans un job CI distinct. +L'exécution complète de la CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) doit réussir avant toute fusion. La suite E2E s'exécute en tant que job CI séparé, en parallèle. Consultez [Contributing](../CONTRIBUTING.md) pour la liste de vérification complète avant fusion. \ No newline at end of file diff --git a/docs/he/architecture.mdx b/docs/he/architecture.mdx index 52391069..a2801b4f 100644 --- a/docs/he/architecture.mdx +++ b/docs/he/architecture.mdx @@ -1,31 +1,29 @@ --- - ---- -title: ארכיטקטורה -description: "כיצד מטפל ה-hook, טעינת התצורה והערכת המדיניות פועלות בפנים" +title: Architecture +description: "כיצד Handler ה-Hook, טעינת Config, והערכת Policy עובדים באופן פנימי" icon: sitemap --- -מסמך זה מסביר כיצד failproofai פועל בפנים: כיצד מערכת ה-hook מיירטת קריאות כלי סוכן, כיצד תצורה נטענת ומתמזגת, כיצד מדיניות מוערכת, וכיצד לוח הבקרה מעקב אחר פעילות סוכן. +מסמך זה מסביר כיצד failproofai עובד באופן פנימי: כיצד מערכת ה-Hook מיירטת קריאות Tool של Agent, כיצד Config נטען ומוזג, כיצד Policies מוערכות, וכיצד ה-Dashboard עוקב אחרי פעילות Agent. --- -## סקירה כללית +## Overview -ל-failproofai שתי תת-מערכות עצמאיות: +ל-failproofai יש שתי תת-מערכות עצמאיות: -1. **מטפל ה-hook** - תהליך CLI מהיר שClaude Code משדר בכל קריאת כלי סוכן. מעריך מדיניות והחזר החלטה. -2. **Agent Monitor (Dashboard)** - יישום אינטרנט Next.js לניטור הפעלות סוכן וניהול מדיניות. +1. **Hook handler** - CLI subprocess מהיר שClaude Code קורא לו בכל קריאת Tool של Agent. מעריך Policies ומחזיר החלטה. +2. **Agent Monitor (Dashboard)** - אפליקציית Next.js לעקיבה אחרי סשנים של Agent וניהול Policies. -שתי תת-המערכות חולקות קבצי תצורה בתיקיות `~/.failproofai/` ו-`.failproofai/` של הפרויקט, אך הן פועלות כתהליכים נפרדים ותקשרות רק דרך מערכת הקבצים. +שתי התת-מערכות משתפות קבצי Config ב-`~/.failproofai/` ובתיקייה `.failproofai/` של הפרויקט, אך הן רצות כתהליכים נפרדים ותקשרו רק דרך מערכת הקבצים. --- -## מטפל ה-hook +## Hook handler -### שילוב עם Claude Code +### Integration עם Claude Code -כאשר אתה מריץ `failproofai policies --install`, הוא כותב רשומות כמו זו ל-`~/.claude/settings.json`: +כאשר אתה מריץ `failproofai policies --install`, הוא כותב entries כמו זה ל-`~/.claude/settings.json`: ```json { @@ -46,9 +44,9 @@ icon: sitemap } ``` -Claude Code לאחר מכן משדר את `failproofai --hook PreToolUse` כתהליך משנה לפני כל קריאת כלי, תוך העברת מטען JSON על stdin. +Claude Code קורא אחר כך ל-`failproofai --hook PreToolUse` כ-subprocess לפני כל קריאת Tool, ומעביר JSON payload על stdin. -### פורמט מטען +### פורמט Payload ```json { @@ -62,11 +60,11 @@ Claude Code לאחר מכן משדר את `failproofai --hook PreToolUse` כתה } ``` -עבור אירועי `PostToolUse`, המטען מכיל גם `tool_result` עם פלט הכלי. +עבור אירועי `PostToolUse`, ה-payload גם כולל `tool_result` עם Output של ה-Tool. -המטפל אוכף מגבלת stdin של 1 MB. מטענים החוצים זאת מושלכים והכל מדיניות מרומז כן. +ה-Handler אוכף מגבלת stdin של 1 MB. Payloads החוצים זאת מושלכים וכל Policies באופן implicit מאפשרים. -### פורמט תגובה +### Response format **Deny (PreToolUse):** ```json @@ -87,7 +85,7 @@ Claude Code לאחר מכן משדר את `failproofai --hook PreToolUse` כתה } ``` -**Instruct (כל אירוע מלבד Stop):** +**Instruct (כל אירוע למעט Stop):** ```json { "hookSpecificOutput": { @@ -97,16 +95,16 @@ Claude Code לאחר מכן משדר את `failproofai --hook PreToolUse` כתה ``` **Stop event instruct:** -- קוד יציאה: `2` -- סיבה כתובה ל-stderr (לא stdout) +- Exit code: `2` +- Reason כתוב ל-stderr (לא stdout) **Allow:** -- קוד יציאה: `0` +- Exit code: `0` - stdout ריק -**Allow עם הודעה:** +**Allow עם Message:** -`allow(message)` מאפשר למדיניות לשלוח הקשר מידע חזרה ל-Claude גם כאשר הפעולה מותרת. מטפל ה-hook כותב את ה-JSON הבא ל-**stdout** (לא קובץ תצורה — זהו התגובה של מטפל ה-hook ל-Claude Code, בדיוק כמו תגובות deny ו-instruct לעיל): +`allow(message)` מאפשר לPolicy לשלוח Context informational חזרה ל-Claude גם כאשר הפעולה מותרת. ה-Hook Handler כותב את ה-JSON הבא ל-**stdout** (לא קובץ Config — זה ה-Response של ה-Handler ל-Claude Code, בדיוק כמו Deny ו-Instruct responses למעלה): ```json // Written to stdout by the hook handler process @@ -116,13 +114,13 @@ Claude Code לאחר מכן משדר את `failproofai --hook PreToolUse` כתה } } ``` -- קוד יציאה: `0` (הפעולה מותרת) -- כאשר מדיניות מרובות מחזירות `allow` עם הודעה, ההודעות שלהן מחוברות בשורות חדשות ל-`additionalContext` בודד -- אם אין מדיניות המספקת הודעה, stdout ריק (כמו קודם) +- Exit code: `0` (הפעולה מותרת) +- כאשר multiple Policies מחזירות `allow` עם Message, ה-Messages שלהם מצורפות עם newlines לתוך string `additionalContext` יחיד +- אם אף Policy לא מספק Message, stdout ריק (כמו קודם) -### צינור עיבוד +### Processing pipeline -`src/hooks/handler.ts` מיישם את כל הצינור: +`src/hooks/handler.ts` מיישם את כל ה-Pipeline: ```text stdin JSON @@ -141,13 +139,13 @@ stdin JSON → exit ``` -כל התהליך רץ תחת 100ms עבור מטענים טיפוסיים ללא קריאות LLM. +כל התהליך רץ בפחות מ-100ms עבור Payloads טיפוסיים בלי LLM calls. --- -## טעינת תצורה +## Configuration loading -`src/hooks/hooks-config.ts` מיישם טעינת תצורה בתחום שלוש-שלבי. +`src/hooks/hooks-config.ts` מיישם שלוש-scope Config loading. ```text [1] {cwd}/.failproofai/policies-config.json ← project (highest priority) @@ -155,40 +153,40 @@ stdin JSON [3] ~/.failproofai/policies-config.json ← global (lowest priority) ``` -לוגיקת מיזוג: -- `enabledPolicies` - union מפושט בכל שלוש הקבצים -- `policyParams` - לכל-מדיניות מפתח, הקובץ הראשון המגדיר אותו מנצח לחלוטין -- `customPoliciesPath` - הקובץ הראשון המגדיר אותו מנצח -- `llm` - הקובץ הראשון המגדיר אותו מנצח +Merge logic: +- `enabledPolicies` - deduplicated union על כל שלושת הקבצים +- `policyParams` - per-policy key, הקובץ הראשון שמגדיר אותו מנצח לחלוטין +- `customPoliciesPath` - הקובץ הראשון שמגדיר אותו מנצח +- `llm` - הקובץ הראשון שמגדיר אותו מנצח -לוח הבקרה של האינטרנט משתמש ב-`readHooksConfig()` (global בלבד) לקריאה וכתיבה, מכיוון שהוא לא משודר עם cwd של פרויקט. +ה-Web Dashboard משתמש ב-`readHooksConfig()` (global only) לקריאה וכתיבה, מכיוון שהוא לא קרוא עם Project cwd. --- -## הערכת מדיניות +## Policy evaluation -`src/hooks/policy-evaluator.ts` מריץ מדיניות לפי הסדר. +`src/hooks/policy-evaluator.ts` מריץ Policies בסדר. -לכל מדיניות: +עבור כל Policy: -1. חפש את סכמת `params` של המדיניות (אם יש לה). -2. קרא `policyParams[policy.name]` מתוך התצורה המתמזגת. -3. מזג ערכים שסופקו על ידי משתמש על ברירות מחדל של סכמה כדי להפיק `ctx.params`. -4. קרא `policy.fn(ctx)` עם ההקשר שנפתר. -5. אם התוצאה היא `deny`, עצור מיד והחזר החלטה זו. -6. אם התוצאה היא `instruct`, צבור את ההודעה והמשך. -7. אם התוצאה היא `allow`, המשך למדיניות הבאה. +1. חפש את ה-`params` schema של ה-Policy (אם יש לו). +2. קרא `policyParams[policy.name]` מה-Merged Config. +3. Merge user-provided values על schema defaults לייצור `ctx.params`. +4. קרא `policy.fn(ctx)` עם ה-Resolved Context. +5. אם ה-Result הוא `deny`, עצור מיד וחזור בהחלטה זו. +6. אם ה-Result הוא `instruct`, צבור את ה-Message והמשך. +7. אם ה-Result הוא `allow`, המשך ל-Policy הבא. -לאחר שכל המדיניות רצה: -- אם הוחזר `deny` כלשהו, פלוט את תגובת ה-deny. -- אם הוחזר `instruct` כלשהו, פלוט תגובת instruct בודדת עם כל ההודעות מחוברות. -- אחרת, פלוט תגובת allow (stdout ריק, exit 0). +לאחר שכל Policies רצים: +- אם כל `deny` חזר, emit את ה-Deny Response. +- אם כל `instruct` returns נאספו, emit Response `instruct` יחיד עם כל Messages מצורפות. +- אחרת, emit Allow Response (stdout ריק, exit 0). --- -## מדיניות מובנית +## Builtin policies -`src/hooks/builtin-policies.ts` מגדיר את כל 39 המדיניות המובנית כאובייקטי `BuiltinPolicyDefinition`: +`src/hooks/builtin-policies.ts` מגדיר את כל 39 ה-Builtin Policies כ-`BuiltinPolicyDefinition` objects: ```typescript interface BuiltinPolicyDefinition { @@ -206,15 +204,15 @@ interface BuiltinPolicyDefinition { } ``` -מדיניות המקבלת `params` מכריזה על `PolicyParamsSchema` עם סוגים וברירות מחדל לכל פרמטר. מעריך המדיניות מוזרק ערכים שנפתרו ל-`ctx.params` לפני קריאה ל-`fn`. פונקציות מדיניות קוראות `ctx.params` ללא הגנת null כי ברירות מחדל תמיד מיושמות קודם. +Policies שמקבלות `params` מכריזות `PolicyParamsSchema` עם Types וDefaults עבור כל Parameter. ה-Policy Evaluator משדר Resolved Values ל-`ctx.params` לפני קריאה ל-`fn`. Policy Functions קוראות `ctx.params` בלי Null-Guarding כי Defaults תמיד מיושמות ראשון. -התאמת דפוס בתוך מדיניות משתמשת בעטוקנים של פקודה מנותחים (argv), לא התאמת מחרוזת גולמית. זה מונע עוקף דרך הזרקת אופרטור shell (למשל דפוס עבור `sudo systemctl status *` לא יכול להיות bypassed על ידי הוספת `; rm -rf /` לפקודה). +Pattern Matching בתוך Policies משתמש בParsed Command Tokens (argv), לא Raw String Matching. זה מונע Bypass דרך Shell Operator Injection (למשל Pattern עבור `sudo systemctl status *` לא יכול להיות bypassed על ידי Appending `; rm -rf /` לפקודה). --- -## מדיניות מותאמת אישית +## Custom policies -`src/hooks/custom-hooks-registry.ts` מיישם רישום מבוסס `globalThis`: +`src/hooks/custom-hooks-registry.ts` מיישם `globalThis`-backed Registry: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -227,25 +225,25 @@ export function getCustomHooks(): CustomHook[] { ... } export function clearCustomHooks(): void { ... } // used in tests ``` -`src/hooks/custom-hooks-loader.ts` טוען את קובץ המדיניות של המשתמש: +`src/hooks/custom-hooks-loader.ts` טוען את Policy File של ה-User: -1. קרא `customPoliciesPath` מתצורה; דלג אם כןנעדר. -2. פתור לנתיב מוחלט; בדוק שהקובץ קיים. -3. שכתב את כל ייבואי `from "failproofai"` לנתיב dist בפועל כדי ש-`customPolicies` יפתור לאותו רישום `globalThis`. -4. שכתב רקורסיבי ייבואים מקומיים חולפים כדי להבטיח תאימות ESM. -5. כתוב קבצי `.mjs` זמניים ו-`import()` קובץ הערך. -6. קרא `getCustomHooks()` כדי לאחזר hooks שנרשמו. -7. נקה את כל הקבצים הזמניים בבלוק `finally`. +1. קרא `customPoliciesPath` מ-Config; דלג אם חסר. +2. Resolve ל-Absolute Path; בדוק אם הקובץ קיים. +3. כתוב מחדש את כל `from "failproofai"` Imports ל-Actual Dist Path כדי שה-`customPolicies` יתמוקד ל-`globalThis` Registry אותו. +4. כתוב מחדש באופן Recursive Transitive Local Imports כדי להבטיח ESM Compatibility. +5. כתוב Temporary `.mjs` Files ו-`import()` את Entry File. +6. קרא `getCustomHooks()` כדי לאחזר Registered Hooks. +7. נקה את כל Temp Files בבלוק `finally`. -בכל שגיאה (קובץ לא נמצא, שגיאת תחביר, כישלון ייבוא), השגיאה מתועדת ל-`~/.failproofai/hook.log` והמטען מחזיר מערך ריק. מדיניות מובנית אינה מושפעת. +בכל Error (File not found, Syntax Error, Import Failure), ה-Error נרשם ל-`~/.failproofai/hook.log` ו-Loader מחזיר Array ריק. Builtin Policies לא מושפעות. -מדיניות מותאמת אישית מוערכת לאחר כל המדיניות המובנית. ה-deny של מדיניות מותאמת אישית עדיין מפסיק מדיניות מותאמות אישיות נוספות (אבל כל המובנויות כבר רצו בנקודה זו). +Custom Policies מוערכות לאחר כל Builtin Policies. Custom Policy `deny` עדיין Short-Circuits Further Custom Policies (אבל כל ה-Builtins כבר רצו בנקודה זו). --- -## רישום פעילות +## Activity logging -לאחר כל אירוע hook, המטפל מוסיף שורת JSONL ל-`~/.failproofai/hook-activity.jsonl`: +לאחר כל Hook Event, ה-Handler Appends JSONL Line ל-`~/.failproofai/hook-activity.jsonl`: ```json { @@ -260,13 +258,13 @@ export function clearCustomHooks(): void { ... } // used in tests } ``` -שורה אחת לכל מדיניות שעשתה החלטה שאינה allow. החלטות allow אינן מתועדות (כדי לשמור את הקובץ קטן). +שורה אחת לכל Policy שעשה Decide שאינו Allow. Allow Decisions לא נרשמות (כדי לשמור את הקובץ קטן). --- -## ארכיטקטורה לוח הבקרה +## Dashboard architecture -לוח הבקרה הוא יישום **Next.js 16** תוך שימוש ב-App Router עם React Server Components ו-Server Actions. +ה-Dashboard היא אפליקציית **Next.js 16** באמצעות App Router עם React Server Components ו-Server Actions. ```text app/ @@ -286,22 +284,22 @@ app/ download/[project]/[session]/route.ts ← Per-CLI session export (JSONL or JSON) ``` -**זרימת נתונים:** +**Data flow:** -- רכיבי עמוד קוראים `lib/projects.ts` ו-`lib/log-entries.ts` כדי לקרוא נתוני פרויקט/session ישירות מהמערכת קבצים (אין שכבת API לקריאה). -- עמוד המדיניות משתמש ב-Server Actions לכל התמורות (toggle, עדכון params, התקנה/הסרה). -- מסמך ה-session מנתח את פורמט התמלול JSONL של Claude ומעבד ציר זמן של הודעות וקריאות כלי. +- Page Components קוראים ל-`lib/projects.ts` ו-`lib/log-entries.ts` כדי לקרוא Project/Session Data ישירות מ-Filesystem (אין API Layer עבור Reads). +- ה-Policies Page משתמשת ב-Server Actions עבור כל Mutations (Toggle, Params Update, Install/Remove). +- ה-Session Viewer מנתח Claude's JSONL Transcript Format ומרנדר Timeline של Messages וTool Calls. -**החלטות עיצוב מפתח:** +**Key Design Decisions:** -- אין מסד נתונים - כל מצב קבוע נמצא בקבצים רגילים (`~/.failproofai/`, `~/.claude/projects/`). -- Server Actions למוטציות - אין צורך בAPI REST עבור פעולות CRUD. -- React Server Components לעמודי קריאה - קריאה ראשונית מהירה יותר, אין חבילת לקוח עבור הביאת נתונים. -- רכיבי לקוח רק שם צריך אינטראקטיביות (toggles מדיניות, חיפוש פעילות, צופה יומן). +- No Database - כל Persistent State נמצא בקבצים רגילים (`~/.failproofai/`, `~/.claude/projects/`). +- Server Actions לMutations - אין צורך ב-REST API עבור CRUD Operations. +- React Server Components לRead Pages - Fast Initial Load, לא Client Bundle עבור Data Fetching. +- Client Components רק כאשר Interactivity נדרשת (Policy Toggles, Activity Search, Log Viewer). --- -## פריסת קובץ +## File layout ```text failproofai/ diff --git a/docs/he/built-in-policies.mdx b/docs/he/built-in-policies.mdx index f8ddbdc4..38dfc8bc 100644 --- a/docs/he/built-in-policies.mdx +++ b/docs/he/built-in-policies.mdx @@ -1,24 +1,24 @@ --- -title: מדיניות מובנות -description: "כל 39 המדיניות המובנות שלוכדות מצבי כשל נפוצים של סוכנים" +title: מדיניויות מובנות +description: "כל 39 המדיניויות המובנות שתופסות מצבי כשל נפוצים של סוכנים" icon: shield --- -failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי כשל נפוצים של סוכנים. כל מדיניות משתפעת בסוג אירוע hook ספציפי ובשם כלי. תשע-עשרה מדיניות מקבלות פרמטרים המאפשרים לך לכוונן את התנהגותן ללא כתיבת קוד. חמש מדיניות זרימת עבודה אוכפות צינור commit → push → PR → CI לפני שClaude עוצר. +failproofai מגיע עם 39 מדיניויות מובנות שתופסות מצבי כשל נפוצים של סוכנים. כל מדיניות מופעלת על סוג אירוע hook ושם כלי ספציפיים. תשע עשרה מדיניויות מקבלות פרמטרים המאפשרים לכם לכוונן את התנהגותן ללא כתיבת קוד. חמש מדיניויות זרימת עבודה אוכפות צינור commit → push → PR → CI לפני שClaude עוצר. --- ## סקירה כללית -המדיניות מקובצות לקטגוריות: +המדיניויות מסודרות לקטגוריות: -| קטגוריה | מדיניות | סוג Hook | +| קטגוריה | מדיניויות | סוג Hook | |----------|----------|-----------| | [פקודות מסוכנות](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | | [פקודות תשתית](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | | [סודות (מנקים)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | | [סביבה](#environment) | block-env-files, protect-env-vars | PreToolUse | -| [גישה לקבצים](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | +| [גישת קבצים](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | | [בסיס נתונים](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse | | [אזהרות](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | @@ -27,16 +27,17 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי - **`block-`** — עצור את הסוכן מהמשך. - **`warn-`** — תן לסוכן הקשר נוסף כדי שיוכל לתקן את עצמו. -- **`sanitize-`** — נקה נתונים רגישים מפלט הכלי לפני שהסוכן רואה אותו. +- **`sanitize-`** — גרד נתונים רגישים מפלט הכלי לפני שהסוכן רואה אותו. ### מרחבי שמות -כל מדיניות נמצאת בחריץ `/`. מדיניות מובנות שייכות -למרחב השמות **`failproofai/`** — לדוגמה, `failproofai/sanitize-jwt`. מרחב השמות -מונע התנגשויות כשאתה טוען גם מדיניות מותאמות או של צד שלישי -עם שמות קצרים דומים. +כל מדיניות חיה בחריץ `/`. מדיניויות מובנות שייכות למרחב השמות +**`failproofai/`** — לדוגמה, `failproofai/sanitize-jwt`. מרחב השמות מונע +התנגשויות כאשר אתה גם טוען מדיניויות מותאמות או של צד שלישי +בעלות שמות קצרים דומים. -בהגדרה שלך, אתה יכול להתייחס למדיניות מובנית בשם קצר או שם מכוון; שתי הצורות פותרות לאותה מדיניות: +בתצורה שלך אתה יכול להתייחס למדיניות מובנית גם בשם קצר וגם בשם +מוסמך; שני הטפוסים מתפזרים לאותה מדיניות: ```json { @@ -47,34 +48,35 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי } ``` -אם לשם אין `/`, failproofai מתייחס אליו כשייך למרחב השמות ברירת המחדל `failproofai`. שמות שכבר מכילים `/` (לדוגמה `myorg/foo`, -`custom/my-hook`) נשמרים כפי שהם. -- **`require-`** — חסום את אירוע Stop עד שהתנאים מתקיימים. +אם לשם אין `/`, failproofai מתייחס אליו כשייך למרחב השמות +ברירת המחדל `failproofai`. שמות שכבר מכילים `/` (למשל `myorg/foo`, +`custom/my-hook`) נשמרים כמו שהם. +- **`require-`** — חסום את אירוע ה-Stop עד שתנאים מתקיימים. --- -כל מדיניות תומכת בשדה אופציונלי `hint` בתוך `policyParams`. ה-hint מוצמד להודעת deny או instruct שClaude רואה, ונותן הוראות פעולה ללא שינוי קוד המדיניות. עובד עם מדיניות מובנות, מותאמות והנוגות לכנס. ראה [תצורה → hint](/he/configuration#hint-cross-cutting) לפרטים. +כל מדיניות תומכת בשדה `hint` אופציונלי ב-`policyParams`. ה-hint מוסף להודעת ה-deny או ה-instruct שClaude רואה, ונותן הנחיות פעולה ללא שינוי קוד המדיניות. עובד עם מדיניויות מובנות, מותאמות וקונוונציה. ראה [Configuration → hint](/he/configuration#hint-cross-cutting) לפרטים. --- ## פקודות מסוכנות -מנע מסוכנים הרצת פעולות שקשה להשיב אותן או שעלולות לפגוע במערכת המארח. +מנע סוכנים מהפעלת פעולות שקשה לבטל או שעלולות לפגוע במערכת המארחת. ### `block-sudo` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא כל פקודת `sudo`. +**ברירת מחדל:** שוללת כל פקודת `sudo`. -חוסם הפעלות המכילות את מילת המפתח `sudo`. התאמת דפוס מתבצעת על אסימוני פקודה מנותחים, לא על המחרוזת הגולמית, כדי למנוע עקיפה באמצעות הזרקת אופרטורי shell. +חוסם הופעות שמכילות את מילת המפתח `sudo`. התאמת דפוס נעשית על אסימוני פקודה מנותחים, לא על המחרוזת הגולמית, כדי למנוע עקיפה דרך הזרקת אופרטור shell. **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודה מדויקות המותרות. כל רשומה מושווה מול אסימוני argv מנותחים. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודה מדויקות המורשות. כל ערך מותאם לאסימוני argv המנותחים. | **דוגמה:** @@ -88,10 +90,10 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי } ``` -עם הגדרה זו, `sudo systemctl status nginx` מותר, אבל `sudo rm /etc/hosts` נדחה. +עם תצורה זו, `sudo systemctl status nginx` מורשה, אך `sudo rm /etc/hosts` שלול. -דפוסים מושווים מול אסימוני מנותחים, לא מול מחרוזת הפקודה הגולמית. זה מונע עקיפה דרך אופרטורי shell מוצמדים (לדוגמה `sudo systemctl status x; rm -rf /` לא תואם `sudo systemctl status *`). +דפוסים מותאמים לאסימוני מנותחים, לא למחרוזת הפקודה הגולמית. זה מונע עקיפה דרך אופרטורים shell מצורפים (למשל `sudo systemctl status x; rm -rf /` לא תואם ל-`sudo systemctl status *`). --- @@ -99,13 +101,13 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `block-rm-rf` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא `rm -rf`, `rm -fr` וצורות מחיקה רקורסיביות דומות. +**ברירת מחדל:** שוללת `rm -rf`, `rm -fr` וצורות מחיקה רקורסיביות דומות. **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | נתיבים שבטוח למחוק אותם רקורסיבית (לדוגמה `/tmp`). | +| `allowPaths` | `string[]` | `[]` | נתיבים שבטוח למחוק בצורה רקורסיבית (למשל `/tmp`). | **דוגמה:** @@ -124,7 +126,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `block-curl-pipe-sh` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא `curl | bash`, `curl | sh`, `wget | bash` וגם דפוסים דומים. +**ברירת מחדל:** שוללת `curl | bash`, `curl | sh`, `wget | bash` וטפוסים דומים. אין פרמטרים. @@ -133,7 +135,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `block-failproofai-commands` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא פקודות שהיו מסיראות או משביתות את failproofai עצמו (לדוגמה `npm uninstall failproofai`, `failproofai policies --uninstall`). +**ברירת מחדל:** שוללת פקודות שיסירו או יכבו את failproofai עצמו (למשל `npm uninstall failproofai`, `failproofai policies --uninstall`). אין פרמטרים. @@ -141,20 +143,20 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ## פקודות תשתית -עצור סוכנים קוד מהרצת CLIs של תשתית או הדלקת צנרות CI/CD. כל המדיניות בקטגוריה זו הן **opt-in** (`defaultEnabled: false`) — סוכנים שבאמת צריכים להתקשר `kubectl`, `terraform` וכו' לא יופרעו אלא אם אתה משביל את המדיניות. כשהוא משביל, כל הפעלה של ה-CLI התואמת נדחית אלא אם הפקודה תואמת לרשומה ב-`allowPatterns`. +עצור סוכנים קוד מהפעלת CLI תשתית או הטלת קנות CI/CD. כל המדיניויות בקטגוריה זו הן **opt-in** (`defaultEnabled: false`) — סוכנים שכל להם צורך לגיטימי להתקשר ל-`kubectl`, `terraform` וכו' לא יופרעו אלא אם אתה מפעיל את המדיניות. כשמופעלת, כל הופעה של ה-CLI המתאימה שלול אלא אם הפקודה תואמת ערך ב-`allowPatterns`. -דקדוק הדפוס זהה ל-[`block-sudo`](#block-sudo): אסימוני תואמים מול argv מנותחים, `*` הוא wildcard לאסימון אחד, וכל פקודה המכילה אופרטור shell עצמאי (`&&`, `||`, `|`, `;`) או אסימון עם מטא-תווי shell מוטמעים דחויים לפני התאמה לרשימה מותרת כדי למנוע עקיפות הזרקה. +דקדוק הדפוס זהה ל-[`block-sudo`](#block-sudo): אסימוני argv מנותחים מותאמים, `*` הוא כרט עדבר עבור אסימון אחד, וכל פקודה המכילה אופרטור shell עצמאי (`&&`, `||`, `|`, `;`) או אסימון עם תווי shell מובנים שלול לפני התאמת מאימה כדי למנוע עקיפות הזרקה. ### `block-kubectl` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא כל הפעלה של `kubectl`. +**ברירת מחדל:** שוללת כל הופעה של `kubectl`. **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודות kubectl המותרות. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודה kubectl המורשות. | **דוגמה:** @@ -168,20 +170,20 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי } ``` -עם הגדרה זו, `kubectl get pods` מותר אבל `kubectl apply -f deploy.yaml` נדחה. +עם תצורה זו, `kubectl get pods` מורשה אך `kubectl apply -f deploy.yaml` שלול. --- ### `block-terraform` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא כל הפעלה של `terraform` או `tofu` (OpenTofu). +**ברירת מחדל:** שוללת כל הופעה של `terraform` או `tofu` (OpenTofu). **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודות terraform/tofu המותרות. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודה terraform/tofu המורשות. | **דוגמה:** @@ -200,13 +202,13 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `block-aws-cli` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא כל הפעלה של CLI `aws`. +**ברירת מחדל:** שוללת כל הופעה של CLI `aws`. **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודות aws CLI המותרות. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודה aws CLI המורשות. | **דוגמה:** @@ -225,13 +227,13 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `block-gcloud` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא כל הפעלה של CLI `gcloud` (Google Cloud). +**ברירת מחדל:** שוללת כל הופעה של CLI `gcloud` (Google Cloud). **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודות gcloud המותרות. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודה gcloud המורשות. | **דוגמה:** @@ -250,13 +252,13 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `block-az-cli` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא כל הפעלה של CLI `az` (Azure). +**ברירת מחדל:** שוללת כל הופעה של CLI `az` (Azure). **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודות az CLI המותרות. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודה az CLI המורשות. | **דוגמה:** @@ -275,13 +277,13 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `block-helm` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא כל הפעלה של `helm`. +**ברירת מחדל:** שוללת כל הופעה של `helm`. **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודות helm המותרות. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודה helm המורשות. | **דוגמה:** @@ -300,7 +302,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `block-gh-pipeline` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא את תת-הפקודות `gh` CLI הבאות המשנות מצב או מעכבות צנרות: +**ברירת מחדל:** שוללת תת-פקודות `gh` CLI הבאות המשנות מצב או מפעילות קנות: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -309,13 +311,13 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי - `gh cache delete` - `gh secret set`, `gh secret delete` -תת-פקודות `gh` לקריאה בלבד כמו `gh pr view`, `gh pr list`, `gh run list`, `gh release view` ו-`gh api repos/.../...` **לא** מותאמות על ידי מדיניות זו — הן נדרשות בדרך כלל לבדיקות זרימת עבודה (כולל `require-ci-green-before-stop` של failproofai). +תת-פקודות `gh` לקריאה בלבד כגון `gh pr view`, `gh pr list`, `gh run list`, `gh release view` ו-`gh api repos/.../...` **לא** מותאמות למדיניות זו — הן נדרשות בדרך כלל לבדיקות זרימת עבודה (כולל `require-ci-green-before-stop` של failproofai). **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | הפעלות מסקריפט ספציפיות להרשאה למרות שהן אחרת היו נדחות. | +| `allowPatterns` | `string[]` | `[]` | הופעות סקריפט ספציפיות להתיר אפילו אם אחרת יהיו שלול. | **דוגמה:** @@ -333,12 +335,12 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ## סודות (מנקים) -עצור סוכנים מדליפת פרטי הזדהות להקשר או פלט. מדיניות מנקה משתפעת ב**PostToolUse** אירועים. כשClaude מפעיל פקודת Bash, קורא קובץ, או קורא לכל כלי, מדיניות אלה בודקות את הפלט לפני שהוא מוחזר לClaude. אם דפוס סוד מתגלה, המדיניות מחזירה החלטת deny המונעת את הפלט מהעברה חזרה. +עצור סוכנים מדלף credentials להקשרם או לפלט שלהם. מדיניויות מנקה מופעלות על אירועי **PostToolUse**. כאשר Claude מפעיל פקודת Bash, קורא קובץ, או קורא לכל כלי, מדיניויות אלה בוחנות את הפלט לפני שהוא מוחזר ל-Claude. אם דפוס סוד מתגלה, המדיניות מחזירה החלטת deny המונעת את הפלט מהעברה בחזרה. ### `sanitize-jwt` **אירוע:** PostToolUse (כל הכלים) -**ברירת מחדל:** מחפה אסימוני JWT (שלוש קטעי base64url מופרדים ב-`.`). +**ברירת מחדל:** מחווה אסימוני JWT (שלוש קטעי base64url המופרדים ב-`.`). אין פרמטרים. @@ -347,13 +349,13 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `sanitize-api-keys` **אירוע:** PostToolUse (כל הכלים) -**ברירת מחדל:** מחפה פורמטי API key נפוצים: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), מפתחות גישה של AWS (`AKIA`), מפתחות Stripe (`sk_live_`, `sk_test_`), ומפתחות Google API (`AIza`). +**ברירת מחדל:** מחווה פורמטי מפתח API נפוצים: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), מפתחות גישה AWS (`AKIA`), מפתחות Stripe (`sk_live_`, `sk_test_`), ומפתחות Google API (`AIza`). **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | דפוסי regex נוספים להתייחסות כסודות. | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | דפוסי regex נוסף לטיפול כסודות. | **דוגמה:** @@ -362,8 +364,8 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי "policyParams": { "sanitize-api-keys": { "additionalPatterns": [ - { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" }, - { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" } + { "regex": "myco_[A-Za-z0-9]{32}", "label": "מפתח API פנימי של MyCo" }, + { "regex": "pat_[0-9a-f]{40}", "label": "PAT פנימי" } ] } } @@ -375,7 +377,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `sanitize-connection-strings` **אירוע:** PostToolUse (כל הכלים) -**ברירת מחדל:** מחפה מחרוזות חיבור בסיס נתונים המכילות פרטי זעקה משובצים (לדוגמה `postgresql://user:password@host/db`). +**ברירת מחדל:** מחווה מחרוזות חיבור בסיס נתונים המכילות credentials מובנים (למשל `postgresql://user:password@host/db`). אין פרמטרים. @@ -384,7 +386,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `sanitize-private-key-content` **אירוע:** PostToolUse (כל הכלים) -**ברירת מחדל:** מחפה בלוקים PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` וכו'). +**ברירת מחדל:** מחווה בלוקי PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` וכו'). אין פרמטרים. @@ -393,7 +395,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `sanitize-bearer-tokens` **אירוע:** PostToolUse (כל הכלים) -**ברירת מחדל:** מחפה כותרות `Authorization: Bearer ` כאשר האסימון הוא 20 תווים או יותר. +**ברירת מחדל:** מחווה כותרות `Authorization: Bearer ` כאשר האסימון הוא 20 תווים או יותר. אין פרמטרים. @@ -401,14 +403,14 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ## סביבה -הגן על הגדרות סביבה רגישות מקריאה או חשיפה על ידי סוכנים. +הגן על תצורת סביבה רגישה מהקריאה או החשיפה על ידי סוכנים. ### `block-env-files` **אירוע:** PreToolUse (Bash, Read) -**ברירת מחדל:** מוציא קריאה של קבצי `.env` דרך `cat .env`, קריאות כלי `Read` עם `.env` כנתיב הקובץ וכו'. +**ברירת מחדל:** שוללת קריאת קבצי `.env` דרך `cat .env`, קריאות כלי `Read` עם `.env` כנתיב הקובץ, וכו'. -לא חוסם `.envrc` או קבצים אחרים סמוכים לסביבה - רק קבצים בשם בדיוק `.env`. +לא חוסם `.envrc` או קבצים סביבתיים אחרים - רק קבצים בשם בדיוק `.env`. אין פרמטרים. @@ -417,26 +419,26 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `protect-env-vars` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא פקודות המדפיסות משתנים סביבתיים: `printenv`, `env`, `echo $VAR`. +**ברירת מחדל:** שוללת פקודות המדפיסות משתנות סביבה: `printenv`, `env`, `echo $VAR`. אין פרמטרים. --- -## גישה לקבצים +## גישת קבצים -שמור סוכנים עובדים בתוך גבולות פרויקט ובחוץ קבצים רגישים. +שמור סוכנים בתוך גבולות פרויקט והרחק מקבצים רגישים. ### `block-read-outside-cwd` **אירוע:** PreToolUse (Read, Bash) -**ברירת מחדל:** מוציא קריאה של קבצים מחוץ לשורש הפרויקט. הגבול הוא `CLAUDE_PROJECT_DIR` (מוגדר פעם ליחידה על ידי Claude Code), עם חזרה לספריה הנוכחית של הסשן כאשר משתנה זה לא מוגדר. שימוש בשורש הפרויקט ולא ב-`cwd` החי אומר הגבול נשאר יציב אפילו אחרי שClaude `cd`ים לתת-ספרייה. +**ברירת מחדל:** שוללת קריאת קבצים מחוץ לשורש הפרויקט. הגבול הוא `CLAUDE_PROJECT_DIR` (מוגדר פעם אחת ליחידה על ידי Claude Code), עם חזרה לספריה העבודה הנוכחית של הפרקו כאשר משתנה זה לא מוגדר. שימוש בשורש הפרויקט במקום `cwd` החי משמעו שהגבול נשאר יציב אפילו אחרי שClaude `cd`s לתיקייה משנית. **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | קידומות נתיבים מוחלטים המותרים גם אם מחוץ לשורש הפרויקט. | +| `allowPaths` | `string[]` | `[]` | קידומות נתיב מוחלט שמורשות אפילו מחוץ לשורש הפרויקט. | **דוגמה:** @@ -455,13 +457,13 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `block-secrets-write` **אירוע:** PreToolUse (Write, Edit) -**ברירת מחדל:** מוציא כתיבה לקבצים המשמשים בדרך כלל למפתחות פרטיים ותעודות: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**ברירת מחדל:** שוללת כתיבות לקבצים שנמצאים בשימוש נפוץ עבור מפתחות פרטיים וסרטיפיקטים: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | דפוסי שמות קבצים נוספים (סגנון glob) לחסימה. | +| `additionalPatterns` | `string[]` | `[]` | דפוסי שם קובץ נוסף (glob-style) לחסום. | **דוגמה:** @@ -479,12 +481,12 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ## Git -מנע דחיפות תוקפות, דחיפות כפויות וטעויות ענף שקשה להשיב. +מנע דחיפות אקראיות, דחיפות כפויות וטעויות ענף שקשה לבטל. ### `block-push-master` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא `git push origin main` ו-`git push origin master`. +**ברירת מחדל:** שוללת `git push origin main` ו-`git push origin master`. **פרמטרים:** @@ -505,7 +507,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ``` -להרשאה דחיפה לכל הענפים (למעשה השבתה מדיניות זו ללא הסרתה מ-`enabledPolicies`), קבע `protectedBranches: []`. +כדי לאפשר דחיפה לכל הענפים (למעשה השבתה של מדיניות זו ללא הסרתה מ-`enabledPolicies`), הגדר `protectedBranches: []`. --- @@ -513,28 +515,28 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `block-work-on-main` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא `git commit`, `git merge`, `git rebase` ו-`git cherry-pick` בזמן שעץ העבודה נמצא ב-`main` או `master`. יצירת וחלפן ענפים (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) לא מושפעים. +**ברירת מחדל:** שוללת `git commit`, `git merge`, `git rebase` ו-`git cherry-pick` בעוד עץ העבודה נמצא על `main` או `master`. יצירה והחלפת ענפים (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) לא מושפעות. **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | שמות ענפים שבהם commit/merge/rebase/cherry-pick נדחה. | +| `protectedBranches` | `string[]` | `["main", "master"]` | שמות ענפים שעליהם commit/merge/rebase/cherry-pick שלול. | --- ### `block-force-push` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מוציא `git push --force` ו-`git push -f`. +**ברירת מחדל:** שוללת `git push --force` ו-`git push -f`. -אין פרמטרים ספציפיים למדיניות. השתמש ב-[`hint`](/he/configuration#hint-cross-cutting) חוצה-קוטעי להצעת חלופות: +אין פרמטרים ספציפיים למדיניות. השתמש ב-[`hint`](/he/configuration#hint-cross-cutting) חוצה הקטעים כדי להציע חלופות: ```json { "policyParams": { "block-force-push": { - "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b `) and push that instead." + "hint": "צור ענף חדש מה-HEAD הנוכחי שלך (למשל `git checkout -b `) ודחוף את זה במקום." } } } @@ -545,7 +547,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `warn-git-amend` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** משכנע את Claude להמשיך בזהירות בעת הרצת `git commit --amend`. לא חוסם את הפקודה. +**ברירת מחדל:** נוקט Claude להתקדם בזהירות בעת הפעלת `git commit --amend`. לא חוסם את הפקודה. אין פרמטרים. @@ -554,7 +556,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `warn-git-stash-drop` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** משכנע את Claude לאשר לפני הרצת `git stash drop`. לא חוסם את הפקודה. +**ברירת מחדל:** נוקט Claude לאשר לפני הפעלת `git stash drop`. לא חוסם את הפקודה. אין פרמטרים. @@ -563,7 +565,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `warn-all-files-staged` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** משכנע את Claude לבדוק מה הוא משרה כשהוא מריץ `git add -A` או `git add .`. לא חוסם את הפקודה. +**ברירת מחדל:** נוקט Claude לבדוק מה הוא מעלה בזמן הפעלת `git add -A` או `git add .`. לא חוסם את הפקודה. אין פרמטרים. @@ -571,12 +573,12 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ## בסיס נתונים -תפוס פעולות SQL הרסניות לפני שהן מבצעות נגד בסיס הנתונים שלך. +תפוס פעולות SQL הרסניות לפני שהן מתבצעות כנגד מסד הנתונים שלך. ### `warn-destructive-sql` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** משכנע את Claude לאשר לפני הרצת SQL המכיל `DROP TABLE`, `DROP DATABASE` או `DELETE` ללא סעיף `WHERE`. +**ברירת מחדל:** נוקט Claude לאשר לפני הפעלת SQL המכיל `DROP TABLE`, `DROP DATABASE` או `DELETE` ללא סעיף `WHERE`. אין פרמטרים. @@ -585,7 +587,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `warn-schema-alteration` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** משכנע את Claude לאשר לפני הרצת הצהרות `ALTER TABLE`. +**ברירת מחדל:** נוקט Claude לאשר לפני הפעלת הצהרות `ALTER TABLE`. אין פרמטרים. @@ -598,13 +600,13 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `warn-large-file-write` **אירוע:** PreToolUse (Write) -**ברירת מחדל:** משכנע את Claude לאשר לפני כתיבת קבצים גדולים מ-1024 KB. +**ברירת מחדל:** נוקט Claude לאשר לפני כתיבת קבצים גדולים מ-1024 KB. **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | סף גודל קובץ בקילובייטים מעליו מוצאת אזהרה. | +| `thresholdKb` | `number` | `1024` | סף גודל קובץ בקילו-בייטים שמעליו ניתנת אזהרה. | **דוגמה:** @@ -619,7 +621,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ``` -מטפל ה-hook אוכף הגבלה stdin של 1 MB על עומסי. כדי לבדוק מדיניות זו עם תוכן קטן, קבע `thresholdKb` לערך הרבה מתחת ל-1024. +מטפל ה-hook אוכף מגבלת stdin של 1 MB על מטענים. כדי לבדוק מדיניות זו עם תוכן קטן, הגדר `thresholdKb` לערך הרבה מתחת ל-1024. --- @@ -627,7 +629,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `warn-package-publish` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** משכנע את Claude לאשר לפני הרצת `npm publish`. +**ברירת מחדל:** נוקט Claude לאשר לפני הפעלת `npm publish`. אין פרמטרים. @@ -636,7 +638,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `warn-background-process` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** משכנע את Claude להיות זהיר בעת הפעלת תהליכים ברקע דרך `nohup`, `&`, `disown` או `screen`. +**ברירת מחדל:** נוקט Claude להיות זהיר בהשקת תהליכים בתמונה דרך `nohup`, `&`, `disown` או `screen`. אין פרמטרים. @@ -645,7 +647,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `warn-global-package-install` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** משכנע את Claude לאשר לפני הרצת `npm install -g`, `yarn global add` או `pip install` ללא סביבה וירטואלית. +**ברירת מחדל:** נוקט Claude לאשר לפני הפעלת `npm install -g`, `yarn global add` או `pip install` ללא סביבה וירטואלית. אין פרמטרים. @@ -653,23 +655,23 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ## מנהלי חבילות -אכוף איזה מנהלי חבילות הסוכן רשאי להשתמש. +אכוף אילו מנהלי חבילות הסוכן רשאי להשתמש בהם. ### `prefer-package-manager` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מושבתת. כשהוא משביל, חוסם כל פקודת מנהל חבילות שאינה ברשימה `allowed` ואומר ל-Claude לשכתב את הפקודה באמצעות מנהל מותר. +**ברירת מחדל:** בוטל. כשמופעל, חוסם כל פקודת מנהל חבילות שלא ברשימת `allowed` ואומר ל-Claude לשכתב את הפקודה באמצעות מנהל מורשה. מזהה: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | פרמטר | סוג | ברירת מחדל | תיאור | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | שמות מנהלי חבילות מותרים. כל מנהל שהוכר שאינו ברשימה זו נחסום. כשריק, המדיניות היא no-op. | -| `blocked` | string[] | `[]` | שמות מנהלים נוספים לחסימה מעבר לרשימה המובנית (לדוגמה `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | שמות מנהלי חבילות מורשים. כל מנהל מזוהה שלא ברשימה זו מחוסם. כשריק, המדיניות היא no-op. | +| `blocked` | string[] | `[]` | שמות מנהלים נוספים לחסום מעבר לרשימה המובנית (למשל `['pdm', 'pipx']`). | -רשימת החסימה המובנית מכסה: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. השתמש ב-`blocked` לצרף מנהלים שאינם ברשימה זו. +רשימת הבלוק המובנית מכסה: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. השתמש ב-`blocked` להוסיף מנהלים שלא ברשימה זו. -**דוגמה הגדרה:** +**דוגמה תצורה:** ```json { @@ -683,7 +685,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי } ``` -עם הגדרה זו, `pip install flask` ו-`pdm install flask` שניהם נדחים עם הודעה האומרת ל-Claude להשתמש ב-`uv` או `bun` במקום. פקודות כמו `uv pip install flask` מותרות כי `uv` ברשימה המותרת ונבדק תחילה. +עם תצורה זו, `pip install flask` ו-`pdm install flask` שניהם שלול עם הודעה אומרת ל-Claude להשתמש ב-`uv` או `bun` במקום. פקודות כגון `uv pip install flask` מורשות כי `uv` נמצא ברשימה ובודק קודם. --- @@ -694,7 +696,7 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `warn-repeated-tool-calls` **אירוע:** PreToolUse (כל הכלים) -**ברירת מחדל:** משכנע את Claude לשקול מחדש כשאותו כלי נקרא 3+ פעמים עם פרמטרים זהים - סימן נפוץ לסוכן תקוע בלולאה. +**ברירת מחדל:** נוקט Claude להתחשב מחדש כאשר אותו כלי נקרא 3+ פעמים עם פרמטרים זהים - סימן נפוץ שהסוכן תקוע בלולאה. אין פרמטרים. @@ -702,40 +704,40 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ## זרימת עבודה -אכוף זרימת עבודה משומרת בסוף סשן. המדיניות אלה משתפעת בארוע **Stop** ודוחה את הסוכן מהעצירה עד שכל תנאי מתקיימים. הם עוקבים אחרי שרשרת תלות טבעית: commit → push → PR → CI. אם מדיניות דוחה, מדיניות מאוחרות בשרשרת דלולות (deny מקצרת). +אכוף זרימת עבודה משמעתית של סיום פרקו. מדיניויות אלה מופעלות על אירוע **Stop** ושוללות את הסוכן מהעצירה עד שכל תנאי מתקיים. הם עוקבים אחר שרשרת תלות טבעית: commit → push → PR → CI. אם מדיניות שוללת, מדיניויות מאוחרות בשרשרת מדולגות (deny מקצר מעגל). -כל מדיניות זרימת עבודה היא **fail-open**: אם הכלי הנדרש לא זמין (לדוגמה `gh` לא מותקן, אין git remote), המדיניות מאפשרת עם הודעה מידע המסבירה מדוע הבדיקה דלולה. +כל מדיניויות זרימת עבודה הן **fail-open**: אם הכלי הנדרש לא זמין (למשל `gh` לא מותקן, אין ריווח git), המדיניות מורשה עם הודעה אינפורמטיבית המסבירה מדוע הבדיקה דולגה. -### סמנטיקה Stop לכל CLI +### סמנטיקה Stop של לפי-CLI -אכיפת Stop נראית מעט שונה בשבעת CLIs הנתמכים כי לכל אחד מהם חוזה hook אירוע "סוכן סיים" שונה. ה**תוצאה** היא זהה — הסוכן לא יכול להסתלק מהעצירה בזמן ששער זרימת עבודה נכשל — אבל ה**מכניקה** שונה. הטבלה להלן מסכמת; רק Pi בעל quirk גלוי למשתמש שכדאי להבין לפני שאתה משביל מדיניות `require-*-before-stop`. +אכיפת Stop נראית שונה במעט על פני שבעת ה-CLI הנתמכים כי לכל אחד יש חוזה hook של סיום סוכן שונה. ה-**outcome** זהה — הסוכן לא יוצא עם עצירה בזמן שער זרימת עבודה נכשל — אך ה-**mechanics** שונים. הטבלה להלן מסכמת; רק Pi יש פרמיה המשתמש בעיר שכדאי להבין לפני שתאפשר מדיניות `require-*-before-stop`. -| CLI | כשהשער משתפע | מה אתה רואה | +| CLI | כשעוצר השער | מה שאתה רואה | |---|---|---| -| Claude Code | אותה לולאת סוכן, מיד | Claude ממשיך לעבוד — תיקונים בעיה, ואז מנסה לסיים שוב. אין הפסקה גלויה לך. | -| Codex | אותה לולאת סוכן, מיד | זהה ל-Claude. | -| GitHub Copilot CLI | אותה לולאת סוכן, מיד | זהה ל-Claude (משתמש ב-`{decision:"block", reason}` ערוץ ניסיון של Copilot — אומת אמפירי מול Copilot CLI 1.0.41). | -| Cursor Agent | אותה לולאת סוכן, מיד | זהה ל-Claude (משתמש ב-`{followup_message}` ערוץ Cursor — מוגבל ל-`loop_limit`, ברירת מחדל 5 ניסיונות). | -| Gemini CLI | אותה לולאת סוכן, מיד | זהה ל-Claude (משתמש ב-`{decision:"block", reason}` ערוץ Gemini על `AfterAgent`). | -| OpenCode | אותה לולאת סוכן, מיד | זהה ל-Claude (משתמש בקריאה `client.session.prompt(...)` SDK של OpenCode מנותבת דרך `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **סדר משתמש הבא** | **Pi עוצר בצורה גלויה** כשהשער משתפע — לולאת הסוכן שלו יוצאת וחזרת למנהל. השער עוברת בפעם הבאה שאתה שומר הנהלה: failproofai מקדם הנהלה `MANDATORY ACTION REQUIRED` לסדר הזה של מערכת בקרה, משכנעת את ה-LLM להשלים את שלב זרימת העבודה (commit, push וכו') לפני ביצוע כל אחד שביקשת. | +| Claude Code | אותו לולאת סוכן, מיד | Claude ממשיך לעבוד — תקן את הבעיה, ואז מנסה לסיים שוב. אין הפסקה נראית לך. | +| Codex | אותו לולאת סוכן, מיד | זהה ל-Claude. | +| GitHub Copilot CLI | אותו לולאת סוכן, מיד | זהה ל-Claude (משתמש בערוץ ממשכה `{decision:"block", reason}` של Copilot — מאומת אמפיריות נגד Copilot CLI 1.0.41). | +| Cursor Agent | אותו לולאת סוכן, מיד | זהה ל-Claude (משתמש בערוץ `{followup_message}` של Cursor — מתוקבל ב-`loop_limit`, ברירת מחדל 5 ניסיונות חוזרים). | +| Gemini CLI | אותו לולאת סוכן, מיד | זהה ל-Claude (משתמש בערוץ `{decision:"block", reason}` של Gemini על `AfterAgent`). | +| OpenCode | אותו לולאת סוכן, מיד | זהה ל-Claude (משתמש בקריאת SDK `client.session.prompt(...)` של OpenCode מנוטרלת דרך `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **תור משתמש הבא** | **Pi עוצר בצורה נראית** כשהשער עוצר — לולאת הסוכן שלו יוצאת ואתה חוזר ללתזמון. השער אז עוצר בפעם הבאה שאתה שולח תזמון: failproofai מקדים הנחיה `MANDATORY ACTION REQUIRED` לתזמון הסיסטם של הסיבוב הזה, נוקט את ה-LLM להשלים את שלב זרימת העבודה (commit, push, וכו') לפני עשיית מה שביקשת. | -**מגבלת Pi.** `AgentEndEvent` של Pi (השקול במעלה זה של ארוע `Stop` של Claude) אין סוג Result — בתוך הזמן שהוא משתפע, לולאת הסוכן של Pi כבר יצאה. Pi לא יכול להיכפף לניסיון מחדש אותה לולאה בדרך שClaude / Copilot / Cursor / Gemini / OpenCode יכולים. failproofai משחקת את השער ל-`before_agent_start` אירוע Pi (המשתפע אחרי הנהלה משתמש הבא) כך בדיקת זרימת העבודה עדיין אוכפת, רק בסדר הבא ולא זה. +**מגבלה של Pi.** `AgentEndEvent` של Pi (המקבילה הזרם של אירוע `Stop` של Claude) אין סוג תוצאה — ברגע שהוא עוצר, לולאת הסוכן של Pi כבר יצאה. Pi לא יכול להילחם להחזור לאותה לולאה בדרך שClaude / Copilot / Cursor / Gemini / OpenCode יכולים. failproofai מעביר את השער לאירוע `before_agent_start` של Pi (שעוצר אחרי התזמון הבא של המשתמש) כדי שבדיקת זרימת העבודה עדיין אוכפת, רק בסיבוב הבא במקום הנוכחי. **מה זה אומר בפרקטיקה:** -- אחרי שPi עוצר, סיבת הדחיה נלכדה בזכרון מקודד ב-id סשן Pi. ההנהלה הבאה בדיוק שאתה שומר בתהליך Pi זהה זה: ה-LLM רואה הנהלה `MANDATORY ACTION REQUIRED` בחלקה העליון של מערכת בקרה, commits (או דוחפים / פותחים את ה-PR / מחכים ל-CI), וזה רק אחר כך ממשיך עם הבקשה שלך. סיבת דחיה שנלכדה היא חד-שימושית — אחד שנדלה, השער ברור. -- השער מוגבל בחיי תהליך Pi. אם אתה `Ctrl+C` Pi או יוצא בין סדרים, הרשומה בזכרון מושמטת יחד עם התהליך והשער חמוקה. Claude, Copilot, Cursor, Gemini ו-OpenCode יש אותו קשור (הרג את הסוכן והשער חמוקה) — Pi פשוט עושה את זה גלוי יותר כי הסוכן גלויים יוצא לפני שהשער משתפע. -- דחיה תלוי הוא גם ברור על `session_shutdown` לכל סיבה (`new` / `resume` / `fork` / `quit`), אז שער מיושן מסדר קודם לא יכול לדלוף לתוך סדר טרי התחלתי באותו תהליך Pi. +- אחרי שPi עוצר, סיבת ה-deny נתפסה בזיכרון מפתח אחרי מזהה סשן Pi. התזמון הבא בדיוק שאתה שולח באותו תהליך Pi סוך את זה: ה-LLM רואה את ההנחיה `MANDATORY ACTION REQUIRED` בחלק העליון של תזמון הסיסטם שלו, commits (או דוחף / פותח את ה-PR / מחכה ל-CI), רק אחרי כן ממשיך עם בקשתך. סיבת ה-deny שתפסה היא one-shot — ברגע שסוך, השער ברור. +- השער מותחם על ידי חיי תהליך של Pi. אם `Ctrl+C` Pi או יוצא בין סיבובים, הערך בזיכרון בזיכרון מושלך יחד עם התהליך ואת השער מיסה. Claude, Copilot, Cursor, Gemini ו-OpenCode יש את אותו כולמן (הרוג את הסוכן ואת השער מיסה) — Pi פשוט עושה את זה יותר נראית כי הסוכן יוצא בצורה נראית לפני ש-פיר עוצר. +- deny ממתין הוא גם ברור על `session_shutdown` לכל סיבה (`new` / `resume` / `fork` / `quit`), כך שערט שנגרד מסשן קודם לא יכול לדלוף לסשן טרי שהחל באותו תהליך Pi. -אם אתה צריך Claude-סגנון אותו-לולאה ניסיון, הרץ את מדיניות `Stop` שלך תחת כל אחד מהשש CLIs הנתמכים האחרים. אנחנו עוקבים Pi במעלה לעתיד סוג Result על `AgentEndEvent` שיתן לנו לסגור את הפער הזה. +אם אתה צריך retry זהה לClaude של אותו לולאה, הרץ את המדיניויות `Stop` שלך תחת כל אחד משש ה-CLI הנתמכים האחרים. אנחנו עוקבים אחרי Pi קודם לעתיד סוג תוצאה על `AgentEndEvent` שיתן לנו לסגור את הפער הזה. ### `require-commit-before-stop` **אירוע:** Stop -**ברירת מחדל:** מוציא עצירה כשישנם שינויים לא מותחים (קבצים שונויים, בחזקה או לא עקובים). מחזיר הודעת מידע כשספריית העבודה נקייה. +**ברירת מחדל:** שוללת עצירה כשיש שינויים ללא commit (שונה, מעודכן או קבצים שלא במעקב). מחזירה הודעה אינפורמטיבית כשספרית העבודה נקייה. אין פרמטרים. @@ -744,13 +746,13 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `require-push-before-stop` **אירוע:** Stop -**ברירת מחדל:** מוציא עצירה כשישנם commits לא דחופים או כשהענף הנוכחי אין לענף remote עקיבה. מציע `git push -u` ליצירת ענף עקיבה אם נדרש. נופל פתוח אם אין remote מגודר. +**ברירת מחדל:** שוללת עצירה כשיש commits שלא דוחפו או כשלענף הנוכחי אין ענף עקיבה מרחוק. מציע `git push -u` ליצירת ענף עקיבה אם נדרש. נכשל פתוח אם אין ריווח מחוקי. **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | שם remote לדחיפה אליו. | +| `remote` | `string` | `"origin"` | שם ריווח לדחוף אליו. | **דוגמה:** @@ -769,14 +771,13 @@ failproofai מגיע עם 39 מדיניות מובנות שלוכדות מצבי ### `require-pr-before-stop` **אירוע:** Stop -**ברירת מחדל:** מוציא עצירה כשאין pull request לענף הנוכחי, או כשה-PR הקיים סגור ללא מיזוג. משכנע את Claude ליצור PR עם `gh pr create`. כשה-PR **מוזג**, המדיניות מאפשרת (העבודה התשלומה) והודעה רומזת לחלפן את הענף (`git checkout main && git pull`). +**ברירת מחדל:** שוללת עצירה כשאין בקשת משיכה לענף הנוכחי, או כשה-PR הקיים סגור ללא merger. נוקט Claude ליצור PR עם `gh pr create`. כאשר ה-PR **מוזג**, המדיניות מורשה (העבודה נשלחה) והודעה רמזה לעבור את הענף (`git checkout main && git pull`). אין פרמטרים. מדיניות זו דורשת [GitHub CLI](https://cli.github.com/) (`gh`) להיות מותקן ומאומת. -הרץ `gh auth login` עם אסימון גישה אישי שיש `repo` היקף לקריאה גישה ל- -pull requests. אם `gh` לא מותקן או לא מאומת, המדיניות נופלת פתוחה וביוחס סיבה ל-Claude. +הרץ `gh auth login` עם אסימון גישה אישי בעל `repo` scope לגישה קריאה לבקשות משיכה. אם `gh` לא מותקן או לא מאומת, המדיניות כושלת פתוחה ומדווחת את הסיבה ל-Claude. --- @@ -784,24 +785,24 @@ pull requests. אם `gh` לא מותקן או לא מאומת, המדיניות ### `require-no-conflicts-before-stop` **אירוע:** Stop -**ברירת מחדל:** מוציא עצירה כשהענף הנוכחי לא יכול להתמזג בנקיוניות לענף base. המדיניות ראשית מאשרת ישנו `OPEN` PR ב-GitHub לענף — בלעדיו, אין מטרה מזג לאכוף, כל המדיניות קצרה-חוזה להרשאה. פעם `OPEN` PR מאומתת, שניים בדיקות עצמאיות פעם: +**ברירת מחדל:** שוללת עצירה כשהענף הנוכחי לא יכול להתמזג בנקיון לענף הבסיס. המדיניות קודם כל מאשרת שיש `OPEN` PR על GitHub לענף — ללא אחד, אין מטרת merger לאכוף, כל מדיניות קצרה מעגל להתיר. ברגע שה-OPEN` PR מאושר, שני חקירות עצמאיות מופעלות: -1. **ישני** — `git merge-tree --write-tree --name-only origin/ HEAD`. ב-סכסוך, הודעת דחיה שמות הקבצים סכסוכי כדי Claude יודע בדיוק מה פתור. -2. **GitHub** — משתמש כן `gh pr view --json mergeable,state` תוצאה כבר משומשת בבדיקה קודמת. תופסת סכסוכים שישן מקומי `origin/` היה להחמיץ (לדוגמה מישהו נחת סכסוך PR על `main` מאז אחרון לשאול). `CONFLICTING` תוצאה מוציא. `UNKNOWN` תוצאה גם מוציא ומשכנע Claude להמתין ~10 שניות ו-re-check לפני ניסיון לעצור שוב — זה מונע שקרים שליליים בזמן GitHub מחשב מחדש. +1. **מקומי** — `git merge-tree --write-tree --name-only origin/ HEAD`. בסכסוך, הודעת ה-deny שמות קבצי הסכסוך כך Claude יודע בדיוק מה לפתור. +2. **GitHub** — משתמשות שוב בתוצאה `gh pr view --json mergeable,state` שכבר נמשכה בבדיקה מקדימה. תופסת סכסוכים שקובץ `origin/` ישן בתוך היה מיסה (למשל מישהו נחת PR סכסוך על `main` מאז הנתיבה האחרונה). תוצאה `CONFLICTING` שוללת. תוצאה `UNKNOWN` גם שוללת ונוקטת Claude להמתין ~10 שניות ובדוק שוב לפני ניסיון להפסיק שוב — זה מונע false negatives בזמן GitHub recomputes. -דלולות לחלוטין (מאפשרת) כשן: `gh` לא מותקן, אין PR לענף, מצב ה-PR לא `OPEN` (לדוגמה `MERGED`, `CLOSED`), או `gh pr view` מחזירה פלט לא ניתן לפירוש. גם נופלת פתוחה כשן `origin/` חסרה מקומית או כשן אין commits לפני base — אלה שכבה 1 fall-throughs עדיין להתייעץ ה-PR mergability בשמור לפני אחרון. +דוג לחלוטין (מורשה) כאשר: `gh` לא מותקן, אין PR לענף, מצב ה-PR לא `OPEN` (למשל `MERGED`, `CLOSED`), או `gh pr view` מחזירה פלט לא parseable. גם כושל פתוח כאשר `origin/` חסר מקומית או כאשר אין commits לפני בסיס — הנופלים של Layer 1 האלה עדיין בודקים את ה-PR mergeability בחוסן לפני התיר. **פרמטרים:** | פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | ענף base לבדוק סכסוכים נגד. | +| `baseBranch` | `string` | `"main"` | ענף בסיס לבדוק סכסוכים נגד. | -GitHub CLI (`gh`) נדרשת למדיניות זו. המדיניות משתמשת `gh pr view` לאשר -`OPEN` PR קיים לפני הרצת כל בדיקת סכסוך — בלעדי `gh`, המדיניות -קצרה-חוזה להרשאה. הרץ `gh auth login` עם אסימון גישה אישי שיש -`repo` היקף לקריאה גישה ל-pull requests. +GitHub CLI (`gh`) נדרש למדיניות זו. המדיניות משתמשת ב-`gh pr view` לאשר +שה-OPEN` PR קיים לפני הפעלת כל חקירה סכסוך — ללא `gh`, המדיניות +קצר מעגל להתיר. הרץ `gh auth login` עם אסימון גישה אישי בעל `repo` scope +לגישה קריאה לבקשות משיכה. --- @@ -809,23 +810,24 @@ GitHub CLI (`gh`) נדרשת למדיניות זו. המדיניות משתמש ### `require-ci-green-before-stop` **אירוע:** Stop -**ברירת מחדל:** מוציא עצירה כשבדיקות CI נכשלות או עדיין פעימות על הענף הנוכחי. בדוקות שניהם GitHub Actions זרימות עבודה וביוט צד שלישי (לדוגמה CodeRabbit, SonarCloud, Codecov). מטיפול `skipped`, `cancelled` ו`neutral` סיכומים כלא-נכשלים (האחרון מכסה לדוגמה Socket Security אזהרות על מחוץ תורם PRs, שבו האפליקציה בכוונה דיווחים ניטרלי ולא הצלחה/כשל). מחזירה הודעת מידע כשכל בדיקות עברות. +**ברירת מחדל:** שוללת עצירה כשקציני CI נכשלים או עדיין מופעלים בענף הנוכחי. בודקת הן GitHub Actions זרימת עבודה מופעלה וקציני בוט צד שלישי (למשל CodeRabbit, SonarCloud, Codecov). מטפלת `skipped`, `cancelled` ו-`neutral` מסקנות כלא כושל (האחרון מכסה למשל Socket Security alerts על PR של תורמים חיצוניים, היכן האפליקציה בכוונת דיווחים ניטרליים במקום הצלחה/כישלון). מחזירה הודעה אינפורמטיבית כשכל קציני עברו. אין פרמטרים. -מדיניות זו דורשת [GitHub CLI](https://cli.github.com/) (`gh`) להיות מותקן ו מאומת. -הרץ `gh auth login` עם אסימון גישה אישי שיש `repo` היקף לקריאה גישה ל- -Actions זרימות עבודה והבדיקות API. אם `gh` לא מותקן או לא מאומת, המדיניות נופלת פתוחה וביוחס סיבה ל-Claude. +מדיניות זו דורשת [GitHub CLI](https://cli.github.com/) (`gh`) להיות מותקן ומאומת. +הרץ `gh auth login` עם אסימון גישה אישי בעל `repo` scope לגישה קריאה לריצת +זרימות עבודה של Actions והבדיקות API. אם `gh` לא מותקן או לא מאומת, המדיניות +כושלת פתוחה ומדווחת את הסיבה ל-Claude. --- --- -## השבתה מדיניות ספציפיות +## השבתה של מדיניויות בודדות -הסר מדיניות ספציפית מ-`enabledPolicies` בהגדרה שלך, או החלף את זה בטאב מדיניות של לוח המחוונים. +הסר מדיניות ספציפית מ-`enabledPolicies` בתצורה שלך, או כבה אותה בלשונית Policies של ממשק הבקרה. ```json { @@ -836,4 +838,4 @@ Actions זרימות עבודה והבדיקות API. אם `gh` לא מותקן } ``` -מדיניות לא רשומה ב-`enabledPolicies` לא רוצות, אפילו אם רשומות `policyParams` קיימות להם. \ No newline at end of file +מדיניויות שלא רשומות ב-`enabledPolicies` לא מופעלות, אפילו אם ערכי `policyParams` קיימים עבורן. \ No newline at end of file diff --git a/docs/he/cli/audit.mdx b/docs/he/cli/audit.mdx index 8a3adb25..b77abfba 100644 --- a/docs/he/cli/audit.mdx +++ b/docs/he/cli/audit.mdx @@ -1,22 +1,23 @@ --- title: ביקורת על הפעלות קודמות (beta) -description: "ספרו כמה פעמים הסוכן עשה דברים בזבזניים או מסוכנים על פני תמלילים קודמים" +description: "ספור כמה פעמים הסוכן עשה דברים מבוזבזים או מסוכנים על פני תמלילים קודמים" --- - **תכונת Beta.** הביקורת משתלחת כ-beta בזמן שאנחנו אוספים משוב מוקדם. - קטלוג הגלאים וקבוצת הדוחות עלולים להשתנות לפני החתך הקבוע הבא. אנא פתחו issue אם משהו נראה לא בסדר. + **תכונת Beta.** הביקורת משתלחת כ-beta בעוד אנחנו אוספים משוב מוקדם. + הקטלוג של הגלאים וקבוצת הדוח עלולים להשתנות לפני החתך היציב הבא. + אנא פתח כתבה אם משהו נראה לא בסדר. -הביקורת מחזירה את תמלילי agent-CLI הקודמים שלך דרך מנוע המדיניות של failproofai ומעבירה דוח חזותי שניתן לשיתוף על **דף לוח המחוונים `/audit`** — הטיפוס של הסוכן שלך, ניקוד 0–100, והנושאים בדיוק אילו מדיניויות היו תופסות. +הביקורת משמרת מחדש את תמלילי agent-CLI שלך דרך מנוע המדיניות של failproofai וממציאה דוח חזותי שניתן לשיתוף בעמוד לוח המחוונים **`/audit`** — אתחול הסוכן שלך, ניקוד 0–100, ובדיוק אילו מדיניויות היו תופסות מה. -## הריצו אותה +## הפעל אותו -שלוש דרכים — כולן מגיעות לאותו דוח `/audit`. +שלוש דרכים פנימה — כולן נוחתות באותו דוח `/audit`. -```bash npx (no install) +```bash npx (ללא התקנה) npx -y failproofai audit ``` @@ -24,7 +25,7 @@ npx -y failproofai audit failproofai audit ``` -```bash failproofai (dashboard) +```bash failproofai (לוח מחוונים) failproofai ``` @@ -32,56 +33,61 @@ failproofai - `npx -y failproofai audit` מביא את failproofai, מריץ את הסריקה, ופותח את לוח המחוונים עבורכם — לא צריך להתקין קודם. + `npx -y failproofai audit` מביא את failproofai, מריץ את הסריקה, ופותח את + לוח המחוונים עבורך — אין צורך בהתקנה מראש. - - `failproofai audit` מריץ את הסריקה בטרמינל שלכם, ואז פותח את `localhost:8020/audit` באופן אוטומטי כשהוא מסתיים. + + `failproofai audit` מריץ את הסריקה בטרמינל שלך, ואז פותח באופן אוטומטי + את `localhost:8020/audit` כאשר זה מסתיים. - הריצו `failproofai` ולחצו על **Audit** בסרגל הניווט (בין Policies ו-Projects), או פתחו את `/audit` ישירות. + הרץ את `failproofai` ולחץ על **Audit** בסרט הניווט (בין Policies + ו-Projects), או פתח את `/audit` ישירות. - הריצו `failproofai audit -h` (או `--help`) כדי לראות שימוש. הביקורת רצה **לחלוטין בלא אינטרנט** — לא נדרשים חשבון או רשת — ולוח המחוונים ממשיך להיות בשירות עד שתעצרו אותו ב-`Ctrl+C`. + הרץ את `failproofai audit -h` (או `--help`) כדי לראות שימוש. הביקורת פועלת **לחלוטין + במצב לא מקוון** — אין צורך בחשבון או ברשת — ולוח המחוונים ממשיך לשרת + עד שתעצור אותו עם `Ctrl+C`. -לוח המחוונים סורק תמלילי agent CLI קודמים על המכונה הזו (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) ודיווח כמה פעמים הסוכן עשה דברים שfailproofai בנוי כדי להפסיק — בדיקות env-var, push כופים, קידומות `cd ` מיותרות, לולאות sleep-polling, קריאה מחדש של קבצים שנערכו זה עתה, ועוד. +לוח המחוונים סורק תמלילי agent CLI קודמים במכונה זו (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) ודיווח כמה פעמים הסוכן עשה דברים שמבנה failproofai כדי לעצור — בדיקות משתנות סביבה, כפיות דחיפה, קידומות `cd ` מיותרות, לולאות sleep-polling, קריאה חוזרת של קבצים שנערכו זה עתה, ועוד. -לכל תמליל, כל אירוע tool-use מוחזר דרך 39 המדיניויות המובנות **ודרך** 8 גלאים שהם רק לביקורת שתופסים דפוסים שעדיין לא מכוסים על ידי מדיניויות זמן הריצה. הספירות מתרכזות לכל מדיניות / גלאי על פני כל הפעלות. +לכל תמליל, כל אירוע tool-use משמר מחדש דרך 39 המדיניויות המובנות **וגם** דרך 8 גלאים audit-only שתופסים דפוסים שעדיין לא מכוסים על ידי מדיניויות זמן ריצה. הספירות מצטברות לכל מדיניות / גלאי על פני כל הפעלות. -## מה אתם מקבלים +## מה אתה מקבל -דף ה-`/audit` הוא **פוסטר** של מסך יחיד וניתן לשיתוף ואחריו ארבע סעיפים מתחת: +עמוד `/audit` הוא כרזה של מסך יחיד שניתן לשיתוף ואחריו ארבע חלקים מתחת לקפל: -1. **פוסטר** — זהות הסוכן שלך במבט חטוף: **הטיפוס** שלו (אחד משמונה — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), מילות מפתח של הגולם, כמה דיר הטיפוס הזה, וניקוד **0–100** עם פס קטגוריה (`S` עד `bottom tier`). בנוי לשיתוף — פרסמו ב-X או LinkedIn, או הורידו אותו כ-PNG. -2. **`// strengths`** — מה הסוכן שלך כבר עושה טוב, כמספרים אמיתיים מהסריקה (למשל clean-tool-call %, `0` push-to-main attempts), מוצג רק כאשר למדיניות הרלוונטית יש רקורד נקי. -3. **`// quirks`** — מה חמק: טבלה דורגת של התנהגויות שfailproofai היה תופס — *מתי* זה קרה לאחרונה, *מה חמק* (ועל ידי איזה מובנה הוא היה חסום), **`severity`** שלו, וכמה פעמים זה **seen** (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — רשימת התיקוני המרשם: שורה אחת לכל מדיניות עם `failproofai policy add ` להעתקה-הדבקה, בתוספת כפתור **install all** שמאפשר כל המלצה בבת אחת ומציג את **ניקוד היעד** שלך אם הייתם עושים זאת. -5. **`// come back better`** — בנו את ההרגל: קבעו **reminder** בדוא"ל לביקורת חוזרת (`3d` / `7d` / `14d` / `30d`) או בצעו ביקורת מחדש עכשיו, **הזמינו חבר** להריץ ביקורת שלהם שלהם (נשלח מ-failproof.ai, Cc אליכם). הזמנות וזמנות דורשות כניסה — ראו [`failproofai auth`](/he/cli/auth). +1. **כרזה** — זהות הסוכן שלך במבט חטוף: שלו **archetype** (אחד מ-8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), מילות המפתח של הפרסונה שלו, כמה נדיר האתחול הזה, וניקוד **0–100** עם רצועת שכבה (`S` עד `bottom tier`). בנוי לשיתוף — פוסט ל-X או LinkedIn, או הורד אותו כ-PNG. +2. **`// strengths`** — מה הסוכן שלך כבר עושה טוב, כמספרים אמיתיים מהסריקה (למשל clean-tool-call %, `0` push-to-main attempts), מוצג רק כאשר למדיניות הרלוונטית יש רשומה נקייה. +3. **`// quirks`** — מה התפזר: טבלה דורגת של התנהגויות shes failproofai היה תופס — *מתי* זה קרה לאחרונה, *מה התפזר* (וה-builtin שהיה חוסם אותו), שלו *severity*, וכמה פעמים זה היה *seen* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — רשימת התיקון הקבוע: שורה אחת לכל מדיניות עם `failproofai policy add ` העתקה-הדבק, ובנוסף כפתור **install all** שמאפשר כל המלצה בבת אחת ומציג את **projected score** שלך אם עשית. +5. **`// come back better`** — בנה את ההרגל: הגדר דוא"ל לביקורת חוזרת **reminder** (`3d` / `7d` / `14d` / `30d`) או biקורת כעת, והזמן **invite a friend** להפעיל ביקורת משלהם (נשלח מ-failproof.ai, Cc'd אליך). תזכורות והזמנות דורשות כניסה — ראה [`failproofai auth`](/he/cli/auth). -## גלאים לביקורת בלבד +## גלאים audit-only בלבד -אלה מגלים דפוסי "התנהגות טיפשה" שאינם (עדיין) אכופים בזמן אמת. הם רצים רק במהלך הביקורת ולעולם לא חוסמים קריאת כלי חי. +אלה תופסים דפוסי התנהגות "stupid behavior" שאינם (עדיין) מאולצים בזמן אמת. הם פועלים רק במהלך הביקורת ולעולם לא חוסמים קריאת כלי חי. | גלאי | מה זה סופר | |---|---| -| `redundant-cd-cwd` | פקודות Bash המתחילות ב-`cd && …` גם כשפקודות כבר רצות ב-`cwd`. | -| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` בקובץ מקור יחיד — השתמשו בכלי `Read`. | -| `prefer-edit-over-sed-awk` | עריכות in-place של `sed -i` / `awk … > file` — השתמשו בכלי `Edit`. | -| `prefer-write-over-heredoc` | Heredoc / כתיבת רב-שורות `echo > file` לקבצים — השתמשו בכלי `Write`. | -| `sleep-polling-loop` | `sleep N` (≥ 30s) ארוך או `while …; sleep …; done` לולאות הצבעות. | -| `find-from-root` | `find /`, `find /home`, `find /usr` וכו' — טווח ל-`cwd` במקום זאת. | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, דילוג על hooks. | -| `reread-after-edit` | `Read` של קובץ שזה עתה `Edit`/`Write` באותה הפעלה. | +| `redundant-cd-cwd` | פקודות Bash המתחילות ב-`cd && …` למרות שפקודות כבר פועלות ב-`cwd`. | +| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` בקובץ מקור יחיד — השתמש בכלי `Read`. | +| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` עריכות במקום — השתמש בכלי `Edit`. | +| `prefer-write-over-heredoc` | Heredoc / `echo > file` רב-שורות כתיבת קבצים — השתמש בכלי `Write`. | +| `sleep-polling-loop` | `sleep N` ארוך (≥ 30s) או לולאות polling `while …; sleep …; done`. | +| `find-from-root` | `find /`, `find /home`, `find /usr`, וכו' — שדה ל-`cwd` במקום. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, דילוג על ווקפים. | +| `reread-after-edit` | `Read` של קובץ שנערך זה עתה `Edit`/`Write` באותה הפעלה. | -## זיכרונות מטמון +## קשיים -- **מטמון per-transcript** ב-`~/.failproofai/cache/audit/.json` מסומן על ידי `(mtime, size, engineVersion, detectorVersion)` — מבטל באופן אוטומטי כאשר התמליל או הקוד של מדיניות/גלאי משתנים. כל כניסה גם אחסונות חותמת `cachedAt` כמטא נתונים **TTL** (לא חלק מהמפתח של המטמון); כניסות ישנות יותר מ-**7 ימים** מעוכלות בקריאה כך שתוצאות מחיי ארוך לא חיות הערכת גלאים משתנים. -- **מטמון תוצאה שלמה** ב-`~/.failproofai/audit-dashboard.json` (mode 0600). מאפשר ללוח המחוונים להציג באופן מיידי בניווט ללא ריצה מחדש. גם דחוי בקריאה מעבר ל-**7-day TTL** — `/audit` נופל דרך למצב הריק שלו ותוקף ריצה טרייה. לחצו על `[ re-audit now ]` ליד התחתון של הדוח כדי לרענן — ביקורת מחדש שולחת `noCache: true`, אז היא עוקפת את מטמון ה-per-transcript וסורקת מחדש כל תמליל בתור החזרת התוצאה שמטמונה; הריצה זורמת קדימה דרך רצועה דבוקה למעלה וחילופי התוצאה בשנן בהצלחה (לא טעינת דף; ביקורת מחדש נכשלת שומרת את הדוח הקודם). +- **Per-transcript cache** ב-`~/.failproofai/cache/audit/.json` מפותח על ידי `(mtime, size, engineVersion, detectorVersion)` — מבטל באופן אוטומטי כאשר התמליל או קוד המדיניות/הגלאי משתנה. כל ערך גם אחסן חותמת זמן `cachedAt` כ**metadata TTL** (לא חלק ממפתח המטמון); ערכים ישנים יותר מ**7 ימים** נדחים בקריאה כך שתוצאות חיות ארוכות לא חיות מעבר לכוונון הגלאים. +- **Whole-result cache** ב-`~/.failproofai/audit-dashboard.json` (mode 0600). מאפשר ללוח המחוונים להעניק דוח מיידי בניווט מבלי להפעיל מחדש. גם נדחה בקריאה בעבר ה-**7-day TTL** — `/audit` ואז נופל דרך מצב הריק שלו ומזמין ריצה טרייה. לחץ על `[ re-audit now ]` בקרבת התחתון של הדוח כדי לרענן — re-audit שולח `noCache: true`, כך שהוא עוקף את המטמון per-transcript וסורק מחדש כל תמליל במקום להחזיר את התוצאה המטומנה; הריצה זורמת התקדמות דרך רצועה דבקה עליונה ומחליפה את התוצאה במקום בהצלחה (אין טעינת דף מחדש; re-audit כושל שומר על הדוח הקודם). ## הערות -- **ללא מוטציה.** הביקורת מחזירה במצב לקריאה בלבד. `warn-repeated-tool-calls` דולק מכיוון שה-sidecar לכל הפעלה שלו אחרת היה שונה. -- **מדיניויות Workflow דלוקות.** `require-*-before-stop` מדיניויות אש רק על אירועי `Stop` ו-`execSync` כנגד מצב git חי — אין להם פרשנות משמעותית "מה הייתה קורה ב-2025", כך שהם לא מופיעים בספירות ביקורת. -- **מדיניויות מותאמות אישית דולקות.** hooks מותאמים אישית שסופקו על ידי משתמש אינם מחוזרים (הם עשויים להשתנות מאז הפעלה המקורית). \ No newline at end of file +- **ללא תמורה.** הביקורת משמרת במצב קריאה בלבד. `warn-repeated-tool-calls` מדולל מכיוון שה-sidecar לפי הפעלה שלו אחרת היה משתנה. +- **מדיניויות זרימת עבודה דלוגות.** `require-*-before-stop` מדיניויות יורים רק על אירועי `Stop` ו-`execSync` כנגד מצב git חי — להם אין פרשנות משמעותית של "מה היה קורה ב-2025", כך שהם לא מופיעים בספירות הביקורת. +- **מדיניויות מותאמות אישית דלוגות.** וו קסטום המסופק על ידי המשתמש אינו משמר מחדש (הם עלולים להשתנות מאז הפעלה מקורית). \ No newline at end of file diff --git a/docs/he/cli/auth.mdx b/docs/he/cli/auth.mdx index 31a21b88..95697123 100644 --- a/docs/he/cli/auth.mdx +++ b/docs/he/cli/auth.mdx @@ -1,5 +1,4 @@ --- ---- title: התחברות description: "התחבר ל-FailproofAI מה-CLI כדי להפעיל תזכורות ותכונות מותאמות אישית" --- @@ -10,19 +9,19 @@ failproofai auth logout # revoke this session failproofai auth whoami # print the signed-in identity ``` -צורת הדגל הישנה `--login` / `--logout` / `--whoami` עדיין מתקבלת כקנייה לתאימות לאחור. +צורת הדגל המורשת `--login` / `--logout` / `--whoami` עדיין מקובלת כשם חלופי לתאימות לאחור. -האימות הוא אופציונלי. מדיניות, לוח הבקרה, דף `/audit` וכל תכונה מקומית אחרת פועלים בדיוק באותו אופן בין אם אתה מחובר או לא. משטח ההתחברות קיים כדי שתכונות ש**צריכות** זהות יציבה (תזכורות re-audit כיום, עוד בעתיד) יהיו למקום לעוגן. +ההתחברות היא התחייבות כרצונית. מדיניות, לוח בקרה, דף `/audit`, וכל תכונה מקומית אחרת עובדים בדיוק אותו דבר בין אם אתה מחובר או לא. משטח ההתחברות קיים כך שתכונות **שדורשות** זהות יציבה (תזכורות ביקורת חוזר היום, עוד בעתיד) יש להן מקום להטביע. -## זרימת התחברות +## זרימת ההתחברות ```bash failproofai auth login ``` -מבקש את הדוא"ל שלך, שולח קוד חד-פעמי בן 6 ספרות לכתובת זו, מבקש את הקוד, ובהצלחה כותב `~/.failproofai/auth.json` (מצב `0600`). אותה הסדר כניסה גלויה לאחר מכן בלוח הבקרה המובנה — לחיצה על `[ set a reminder ]` ב-`/audit` תראה אותך כמחובר. +מבקש את הדוא״ל שלך, שולח קוד חד-פעמי בן 6 ספרות לכתובת זו, מבקש את הקוד, ובהצלחה כותב `~/.failproofai/auth.json` (מצב `0600`). אותה הפעלה אז נראית בלוח הבקרה בתוך האפליקציה — לחיצה על `[ set a reminder ]` ב-`/audit` תראה אותך כמחובר. -לוח הבקרה חושף את אותה הזרימה כתיבת דיאלוג מודאלית ב-`/audit` למשתמשים שלעולם לא נוגעים ב-CLI. +לוח הבקרה חושף אותה זרימה כדו-שיח מודאלי ב-`/audit` למשתמשים שלעולם לא נוגעים ב-CLI. ## התנתקות @@ -30,7 +29,7 @@ failproofai auth login failproofai auth logout ``` -מבטל את הסדר הנוכחי בשרת ומוחק את `~/.failproofai/auth.json`. אם שרת ה-API אינו זמין, הקובץ המקומי מוסר בכל מקרה — כוונה מקומית להתנתקות תמיד מנצחת. +מבטל את ההפעלה הנוכחית בשרת ומוחק את `~/.failproofai/auth.json`. אם שרת ה-API אינו ניתן להשגה, הקובץ המקומי מוסר בכל זאת — כוונה מקומית להתנתק תמיד מנצחת. ## בדיקת זהות @@ -38,11 +37,11 @@ failproofai auth logout failproofai auth whoami ``` -הדפס ` ()` וצא עם קוד 0 כאשר סדר כניסה תקין קיים, או `not signed in` וצא עם קוד 1 אחרת. מרענן בשתיקה את אסימון הגישה ברקע אם הוא בטווח של דקה מלהיות תוקף שלילי. +הדפס ` ()` ויצא עם קוד 0 כאשר הפעלה תקפה קיימת, או `not signed in` ויצא עם קוד 1 אחרת. רענן בשקט את אסימון הגישה ברקע אם הוא בתוך דקה מפקיעה. -## תזכורת re-audit קבועה +## תזכורת ביקורת חוזר קבועה -כאשר אתה לוחץ על **`[ set a reminder ]`** בדף `/audit` (או מתחבר דרך המודאל שהכפתור משער), לוח הבקרה כותב קובץ קטן מלווה ב-`~/.failproofai/next-audit.json`: +כאשר אתה לוחץ על **`[ set a reminder ]`** בדף `/audit` (או התחברות דרך המודאל שהכפתור מגביל דרכו), לוח הבקרה כותב קובץ בן לוויה קטן ב-`~/.failproofai/next-audit.json`: ```json { @@ -52,11 +51,11 @@ failproofai auth whoami } ``` -קובץ זה מוגבל לדוא"ל שעליו הוגדר — החלפת הסדר כניסה של CLI לחשבון אחר מסתירה כל תזכורת ששייכת למשתמש הקודם. התזה ברירת מחדל היא **7 ימים**, הניתנת להגדרה מאוחר יותר כאשר המתזמן נוחת. נוצר עם הרשאות `0600` כמו `auth.json`. +קובץ זה מתויחס לדוא״ל שלו הוגדר עבור — עבור ההפעלה של ה-CLI ללא הפעלה אחרת מסתיר כל תזכורת ששייכת למשתמש הקודם. ההיסט ברירת המחדל הוא **7 ימים**, סדור מאוחר יותר כאשר המתזמן נוחת. נוצר עם הרשאות `0600` כמו `auth.json`. -נקודת הקצה `/api/auth/reminder` של לוח הבקרה חושפת `GET` (קריאה), `POST` (הגדרה / תזמון מחדש) ו-`DELETE` (ניקוי) וידרוש סדר כניסה פעיל. +נקודת הקצה `/api/auth/reminder` של לוח הבקרה חושפת `GET` (קריאה), `POST` (הגדרה / תזמון מחדש), ו-`DELETE` (ניקוי) ודורשת הפעלה פעילה. -## מה נמצא ב-`~/.failproofai/auth.json` +## מה ב-`~/.failproofai/auth.json` ```json { @@ -68,21 +67,21 @@ failproofai auth whoami } ``` -נוצר עם הרשאות `0600` (קריאה/כתיבה של בעלים בלבד). אסימון הגישה הוא JWT HS256 של שעה אחת; אסימון ההרענון הוא מחרוזת אקראית אטומה של 256 סיביות שהשרת מאחסן כ-`SHA-256(token)`. השדול של אסימון הרענון מגוקח בצד השרת ומבטל כל סדר כניסה למשתמש. +נוצר עם הרשאות `0600` (קריאה/כתיבה בבעלות בלבד). אסימון הגישה הוא JWT HS256 של שעה אחת; אסימון הרענון הוא מחרוזת אקראית אטומה של 256 סיביות ששרת אחסן כ-`SHA-256(token)`. משחק מחדש של אסימון רענון מתגלה בצד השרת ומבטל כל הפעלה עבור המשתמש. ## משתנים סביבה | משתנה | ברירת מחדל | מטרה | |---|---|---| -| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | עקוף את כתובת ה-URL של בסיס שרת ה-API. שימושי להנדסה מקומית כנגד שרת api מתארח עצמי. | -| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | עקוף היכן `auth.json` מאוחסן. בעיקר לבדיקות. | +| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | החלף את URL בסיס שרת ה-API. שימושי לפיתוח מקומי מול שרת API מעוצב עצמאי. | +| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | החלף היכן מאוחסן `auth.json`. בעיקר לבדיקות. | -ראה [משתנים סביבה](/he/cli/environment-variables) לרשימה המלאה. +ראה [משתנים סביבה](/he/cli/environment-variables) לקבלת הרשימה המלאה. ## פתרון בעיות -**"Could not reach the api-server"** — ה-CLI לא יכול לפתוח חיבור TCP ל-`FAILPROOF_API_URL`. בדוק את הרשת שלך, או הגדר `FAILPROOF_API_URL` אם אתה מפעיל שרת api מתארח עצמי. +**"Could not reach the api-server"** — ה-CLI לא יכול לפתוח חיבור TCP ל-`FAILPROOF_API_URL`. בדוק את הרשת שלך, או הגדר `FAILPROOF_API_URL` אם אתה מפעיל שרת API מעוצב עצמאי. -**"Rate limited"** — יותר מדי ניסיונות התחברות בחלון של 15 דקות לאותו הדוא"ל (5/email) או IP (20/IP), או קיבוע של 30 שניות לשיליחה מחדש לאחר הבקשה הקודמת לאותו הדוא"ל. הודעת השגיאה כוללת את חלון retry-after בשניות. +**"Rate limited"** — יותר מדי ניסיונות התחברות בחלון של 15 דקות לדוא״ל זה (5/דוא״ל) או IP (20/IP), או קיזום שלח מחדש של 30 שניות לאחר הבקשה הקודמת לאותו דוא״ל. הודעת השגיאה כוללת את חלון retry-after בשניות. -**Code rejected** — ה-OTP היה שגוי, פג תוקפו, או השורה פגעה בנעילה של 5-ניחוש שגוי שלה. הפעל `failproofai auth login` שוב כדי לבקש קוד טרי. \ No newline at end of file +**Code rejected** — ה-OTP היה שגוי, פקע, או השורה פגעה בנעילה של 5 ניחושים שגויים שלה. הרץ `failproofai auth login` שוב כדי לבקש קוד חדש. \ No newline at end of file diff --git a/docs/he/cli/dashboard.mdx b/docs/he/cli/dashboard.mdx index 082e120b..fd4f36df 100644 --- a/docs/he/cli/dashboard.mdx +++ b/docs/he/cli/dashboard.mdx @@ -7,23 +7,23 @@ description: "הפעל את לוח הבקרה לעיון בהפעלות סוכנ failproofai ``` -מפעיל את לוח הבקרה באתר `http://localhost:8020`. +מפעיל את לוח הבקרה של האתר בכתובת `http://localhost:8020`. ## אפשרויות | דגל | תיאור | |------|-------------| -| `--port ` | הפורט להאזנה אליו (ברירת מחדל: `8020`) | -| `--allowed-origins ` | רשימה מופרדת בפסיקים של שמות משתמן/כתובות IP המורשות לגישה למשאבי הפיתוח | +| `--port ` | הפורט להאזנה (ברירת מחדל: `8020`) | +| `--allowed-origins ` | רשימה מופרדת בפסיקים של בעלי מארחים/כתובות IP המורשים לגשת למשאבי פיתוח | -כדי להצביע את לוח הבקרה לתיקיית Claude project שאינה ברירת המחדל, הגדר את משתנה הסביבה `CLAUDE_PROJECTS_PATH` בעת ההפעלה. +כדי להצביע את לוח הבקרה לתיקיית Claude project שאינה ברירת המחדל, הגדר את משתנה הסביבה `CLAUDE_PROJECTS_PATH` בעת הפעלה. ## דוגמאות ```bash -# הפעל בפורט שונה +# הפעלה על פורט שונה failproofai --port 9000 -# השתמש בנתיב Claude projects מותאם אישית דרך משתנה סביבה +# שימוש בנתיב Claude projects מותאם אישית דרך משתנה סביבה CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/he/cli/environment-variables.mdx b/docs/he/cli/environment-variables.mdx index 8bce8acc..be539294 100644 --- a/docs/he/cli/environment-variables.mdx +++ b/docs/he/cli/environment-variables.mdx @@ -1,47 +1,48 @@ --- -title: משתני סביבה -description: "הגדר את התנהגות failproofai באמצעות משתני סביבה" +--- +title: משתנים סביבה +description: "הגדרת התנהגות failproofai באמצעות משתנים סביבה" --- ## Dashboard | משתנה | תיאור | |----------|-------------| -| `PORT` | יציאת Dashboard (ברירת מחדל: `8020`) | -| `CLAUDE_PROJECTS_PATH` | דרוס את המיקום בו נמצאים תיקיות פרויקט Claude Code | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | דפי Dashboard להסתרה, מופרדים בפסיק | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | שמות מארחים/כתובות IP המורשות לגשת למשאבי פיתוח. זהה ל-`--allowed-origins`. | +| `PORT` | יציאת ה-Dashboard (ברירת מחדל: `8020`) | +| `CLAUDE_PROJECTS_PATH` | דריסת המקום בו נמצאים תיקיות פרויקט Claude Code | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | עמודי Dashboard להסתרה (מופרדים בפסיקים) | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | משרתים/כתובות IP המורשות לגישה למשאבי פיתוח. זהה ל-`--allowed-origins`. | -## רישום (Logging) +## רישום | משתנה | תיאור | |----------|-------------| -| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | רמת רישום השרת (ברירת מחדל: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | נתיב קובץ רישום hook מותאם אישית, או `true` עבור ברירת מחדל (`~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | רמת יומן השרת (ברירת מחדל: `warn`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | נתיב קובץ יומן hook מותאם אישית, או `true` לברירת מחדל (`~/.failproofai/logs/hooks.log`) | -## טלמטריה (Telemetry) +## Telemetry | משתנה | תיאור | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | בטל טלמטריה שימוש אנונימית | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | ביטול טלמטריית שימוש אנונימית | -## אימות (Authentication) +## זיהוי הזהות | משתנה | תיאור | |----------|-------------| -| `FAILPROOF_API_URL` | דרוס את כתובת ה-URL הבסיסית של api-server המשמשת את `failproofai auth` ותיבת הדיאלוג לאימות ה-Dashboard. ברירת המחדל היא `https://api.befailproof.ai`; הגדר ל-`http://localhost:8080` (או כל מקום אחר) בעת הפעלת api-server מקומי. | -| `FAILPROOFAI_AUTH_DIR` | דרוס את המיקום בו מאוחסן `auth.json` (ברירת מחדל: `~/.failproofai`). שימושי בעיקר לבדיקות מבודדות. | +| `FAILPROOF_API_URL` | דריסת כתובת ה-URL הבסיסית של שרת ה-api המשמשת את `failproofai auth` וחלון תיאום הזהות של ה-Dashboard. ברירת מחדל: `https://api.befailproof.ai`; הגדר ל-`http://localhost:8080` (או בכל מקום אחר) כאשר מריצים שרת api מקומי. | +| `FAILPROOFAI_AUTH_DIR` | דריסת המקום בו נשמר `auth.json` (ברירת מחדל: `~/.failproofai`). שימושי בעיקר לבדיקות מבודדות. | -## הנמקה בהרצה ראשונה (First-run prompt) +## הנמקה בהרצה ראשונה | משתנה | תיאור | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | דלג על ההנמקה המציעה להתקין מדיניות בהפעלת `failproofai` ריק ראשונה | +| `FAILPROOFAI_NO_FIRST_RUN=1` | דילוג על ההנמקה המציעה להתקין מדיניויות בהפעלה ראשונה של `failproofai` | ## LLM (להערכת מדיניות) | משתנה | תיאור | |----------|-------------| -| `FAILPROOFAI_LLM_BASE_URL` | נקודת קצה API של LLM (ברירת מחדל: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | מפתח API למדיניות מבוססות LLM | +| `FAILPROOFAI_LLM_BASE_URL` | נקודת קצה של LLM API (ברירת מחדל: `https://api.openai.com/v1`) | +| `FAILPROOFAI_LLM_API_KEY` | מפתח API למדיניויות מופעלות LLM | | `FAILPROOFAI_LLM_MODEL` | שם המודל (ברירת מחדל: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/he/cli/hook.mdx b/docs/he/cli/hook.mdx index c21238e4..0b5ddac3 100644 --- a/docs/he/cli/hook.mdx +++ b/docs/he/cli/hook.mdx @@ -1,25 +1,31 @@ +--- +--- +title: معالج Hook (داخلي) +description: "العملية الفرعية التي يستدعيها Claude Code عند كل حدث أداة" +--- + ```bash failproofai --hook ``` -זהו הפקודה הרשומה ב-`settings.json` של Claude Code על ידי `failproofai policies --install`. בדרך כלל אתה לא קורא לזה ישירות. +هذا هو الأمر المسجل في `settings.json` الخاص بـ Claude Code بواسطة `failproofai policies --install`. لا تستدعيه عادة مباشرة. -קורא payload של JSON מ-stdin, מערך את כל המדיניות המופעלות, ויוצא עם קוד המציין את ההחלטה: +يقرأ حمولة JSON من stdin، ويقيّم جميع السياسات المفعّلة، ويخرج برمز يشير إلى القرار: -| קוד יציאה | החלטה | השפעה | +| رمز الخروج | القرار | التأثير | |-----------|---------|--------| -| `0` | `allow` | אפשר את הפעולה | -| `1` | `deny` | חסום את הפעולה - Claude רואה את סיבת הדחייה | -| `2` | `instruct` | הזריק הנחיות להקשר של Claude | +| `0` | `allow` | السماح بالإجراء | +| `1` | `deny` | حظر الإجراء - يرى Claude سبب الحظر | +| `2` | `instruct` | حقن التوجيهات في سياق Claude | -### סוגי אירועים נתמכים +### أنواع الأحداث المدعومة -| קטגוריה | אירועים | -|----------|---------| -| **ביצוע כלים** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | -| **מחזור חיים הפעלה** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | -| **אינטראקציה של משתמש** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | -| **תת-סוכנים ומשימות** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | -| **תצורה** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | -| **מערכת קבצים** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | -| **הקשר** | `PreCompact`, `PostCompact` | \ No newline at end of file +| الفئة | الأحداث | +|-------|---------| +| **تنفيذ الأداة** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | +| **دورة حياة الجلسة** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | +| **تفاعل المستخدم** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | +| **الوكلاء الفرعيون والمهام** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | +| **التكوين** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | +| **نظام الملفات** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | +| **السياق** | `PreCompact`, `PostCompact` | \ No newline at end of file diff --git a/docs/he/cli/install-policies.mdx b/docs/he/cli/install-policies.mdx index fd766ea5..a82d8d5d 100644 --- a/docs/he/cli/install-policies.mdx +++ b/docs/he/cli/install-policies.mdx @@ -1,44 +1,44 @@ --- title: התקנת מדיניויות -description: "הפעל מדיניויות כך שיפעלו בכל קריאת כלי agent" +description: "אפשר מדיניויות כך שהן יופעלו בכל קריאת כלי של agent" --- ```bash failproofai policies --install [policy-names...] [options] ``` -כותב ערכי hook לקובץ ההגדרות של ה-CLI של agent המותקן שלך (Claude Code, OpenAI Codex, או GitHub Copilot CLI _(beta)_) כדי שה-failproofai יחתוך קריאות כלים. +כותב ערכי hook לקובץ ההגדרות של ה-CLI של agent המותקן שלך (Claude Code, OpenAI Codex, או GitHub Copilot CLI _(beta)_) כדי שfaiproofai יוכל לעכב קריאות כלים. -כנויים: `failproofai p -i` +כינויים: `failproofai p -i` ## אפשרויות | דגל | תיאור | |------|-------------| -| `--cli claude\|codex\|copilot` | CLI(s) של agent להתקנה; מופרדים ברווח (לדוגמה `--cli claude codex copilot`) או חוזרים. השמט כדי לזהות CLIs מותקנים ולבקש אישור. | -| `--scope user` | התקנה לקובץ הגדרות בהיקף משתמש (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). ברירת המחדל. | -| `--scope project` | התקנה לקובץ הגדרות בהיקף פרויקט (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | -| `--scope local` | Claude בלבד — מתקין לתוך `/.claude/settings.local.json`. ל-Codex וCopilot אין היקף `local`. | +| `--cli claude\|codex\|copilot` | CLI(s) של agent להתקנה; מופרדים בחסם (למשל `--cli claude codex copilot`) או חוזרים. השמט כדי לזהות CLIs מותקנים ולבקש. | +| `--scope user` | התקן לקובץ הגדרות בהיקף משתמש (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). ברירת מחדל. | +| `--scope project` | התקן לקובץ הגדרות בהיקף פרויקט (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | +| `--scope local` | Claude בלבד — התקן ל-`/.claude/settings.local.json`. ל-Codex וcopilot אין היקף `local`. | | `--custom ` / `-c` | נתיב לקובץ JS המכיל מדיניויות hook מותאמות אישית | ## התנהגות -- **אין שמות מדיניויות** - פותח הודעה אינטראקטיבית לבחירת מדיניויות -- **שמות ספציפיים** - מפעיל את המדיניויות הללו (מתווספות לכל המדיניויות שכבר מופעלות) -- **`all`** - מפעיל כל מדיניות זמינה +- **אין שמות מדיניויות** - פותח הנחיה אינטראקטיבית לבחירת מדיניויות +- **שמות ספציפיים** - מאפשר מדיניויות אלו (מוסף לכל אלה שכבר מופעלות) +- **`all`** - מאפשר כל מדיניות זמינה -ההתקנה היא תוסיפית: הפעלה חוזרת של `--install` מוסיפה מדיניויות חדשות ללא הסרת קיימות. +התקנה היא תוספת: הפעלת `--install` שוב מוסיפה מדיניויות חדשות ללא הסרת הקיימות. ## דוגמאות ```bash -# התקן את כל המדיניויות המוגדרות כברירת מחדל באופן גלובלי (אינטראקטיבי) +# התקן את כל המדיניויות ברירת המחדל באופן גלובלי (אינטראקטיבי) failproofai policies --install -# התקן מדיניויות ספציפיות עבור הפרויקט הנוכחי +# התקן מדיניויות ספציפיות לפרויקט הנוכחי failproofai policies --install block-sudo sanitize-api-keys --scope project -# הפעל את כל המדיניויות בבת אחת +# אפשר את כל המדיניויות בבת אחת failproofai policies --install all # התקן עם קובץ מדיניויות מותאם אישית @@ -47,11 +47,11 @@ failproofai policies --install --custom ./my-policies.js # התקן עבור OpenAI Codex (היקף פרויקט) failproofai policies --install --cli codex --scope project -# התקן עבור GitHub Copilot CLI (beta) עבור הפרויקט הנוכחי +# התקן עבור GitHub Copilot CLI (beta) לפרויקט הנוכחי failproofai policies --install --cli copilot --scope project -# התקן עבור כל שלושת ה-CLIs בבת אחת +# התקן לשלוש CLI בו זמנית failproofai policies --install --cli claude codex copilot ``` -כאשר `--custom ` מסופק, הקובץ מאומת מיד - עליו לקרוא לפחות פעם אחת ל-`customPolicies.add()`. הנתיב המוקד נשמר ל-`policies-config.json` כ-`customPoliciesPath`. \ No newline at end of file +כאשר `--custom ` מסופק, הקובץ מאומת מיד - הוא חייב לקרוא ל-`customPolicies.add()` לפחות פעם אחת. הנתיב שנפתר נשמר ל-`policies-config.json` כ-`customPoliciesPath`. \ No newline at end of file diff --git a/docs/he/cli/list-policies.mdx b/docs/he/cli/list-policies.mdx index e2126575..79f36851 100644 --- a/docs/he/cli/list-policies.mdx +++ b/docs/he/cli/list-policies.mdx @@ -1,5 +1,5 @@ --- -title: רשימת מדיניויות +title: רישום מדיניויות description: "ראה אילו מדיניויות מופעלות, הפרמטרים שלהן ומדיניויות מותאמות" --- @@ -7,7 +7,7 @@ description: "ראה אילו מדיניויות מופעלות, הפרמטרי failproofai policies ``` -מציג את כל המדיניויות עם סטטוס שלהן, פרמטרים מוגדרים ומדיניויות מותאמות. +מציג את כל המדיניויות עם המצב שלהן, הפרמטרים שהוגדרו, ומדיניויות מותאמות. ## דוגמה של פלט @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -מפתחות לא ידועים ב-`policyParams` מסומנים כאן כדי שתוכל לתפוס טעויות הקלדה בשלב מוקדם. \ No newline at end of file +מפתחות לא ידועים ב־`policyParams` מסומנים כאן כדי שתוכל לתפוס כתיב שגוי בשלב מוקדם. \ No newline at end of file diff --git a/docs/he/cli/remove-policies.mdx b/docs/he/cli/remove-policies.mdx index c2629c4b..15603d34 100644 --- a/docs/he/cli/remove-policies.mdx +++ b/docs/he/cli/remove-policies.mdx @@ -1,14 +1,13 @@ --- ---- -title: הסרת מדיניות -description: "הסרת כניסות hook מ-settings של Claude Code" +title: הסרת policies +description: "הסרת hook entries מהגדרות Claude Code" --- ```bash failproofai policies --uninstall [policy-names...] [options] ``` -הסרת כניסות failproofai hook מה-`settings.json` של Claude Code. +מסירה failproofai hook entries מ-`settings.json` של Claude Code. כינויים: `failproofai p -u` @@ -19,26 +18,26 @@ failproofai policies --uninstall [policy-names...] [options] | `--scope user` | הסרה מהגדרות גלובליות (ברירת מחדל) | | `--scope project` | הסרה מהגדרות פרויקט | | `--scope local` | הסרה מהגדרות מקומיות | -| `--scope all` | הסרה מכל ההיקפים בבת אחת | -| `--custom` / `-c` | ניקוי של `customPoliciesPath` מתצורה | +| `--scope all` | הסרה מכל ההיקפים בו-זמנית | +| `--custom` / `-c` | ניקוי `customPoliciesPath` מהתצורה | ## התנהגות -- **ללא שמות מדיניות** - הסרת כל כניסות failproofai hook מקובץ ההגדרות -- **שמות ספציפיים** - השבתת מדיניות אלה אך שמירה על hooks מותקנים +- **ללא שמות policies** - מסירה את כל failproofai hook entries מקובץ ההגדרות +- **שמות ספציפיים** - מכבה את ה-policies הללו אך משאירה hooks מותקנים ## דוגמאות ```bash -# הסרת כל hooks בעולם +# הסרת כל ה-hooks בעולם failproofai policies --uninstall -# השבתת מדיניות ספציפית (שומרת hooks מותקנים) +# השבתת policy ספציפי (משאירה hooks מותקנים) failproofai policies --uninstall block-sudo # הסרת hooks מכל היקף failproofai policies --uninstall --scope all -# ניקוי נתיב מדיניות מותאמת +# ניקוי נתיב custom policies failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/he/cli/version.mdx b/docs/he/cli/version.mdx index 89b71799..e862f196 100644 --- a/docs/he/cli/version.mdx +++ b/docs/he/cli/version.mdx @@ -1,5 +1,6 @@ --- -title: בדיקת גרסה +--- +title: בדוק גרסה description: "הדפס את גרסת failproofai המותקנת" --- @@ -9,4 +10,4 @@ failproofai --version failproofai -v ``` -הדפס את מספר הגרסה המותקן. \ No newline at end of file +הדפס את מספר הגרסה המותקנת. \ No newline at end of file diff --git a/docs/he/configuration.mdx b/docs/he/configuration.mdx index b52f8929..594357c2 100644 --- a/docs/he/configuration.mdx +++ b/docs/he/configuration.mdx @@ -1,28 +1,28 @@ --- -title: תצורה -description: "פורמט קובץ קונפיגורציה, מערכת בעלת שלוש הערכות, וכללי מיזוג" +title: הגדרות +description: "פורמט קובץ הגדרות, מערכת תלת-היקף, וכללי מיזוג" icon: gear --- -failproofai משתמש בקבצי JSON של תצורה לשליטה בכללים פעילים, בהתנהגותם, ובמקום טעינת כללים מותאמים. התצורה מעוצבת להיות קלה לשיתוף עם הצוות שלך - עמוד אותה בריפו שלך וכל מפתח יקבל את אותו רשת בטיחות לסוכן. +failproofai משתמש בקובצי הגדרות JSON כדי לשלוט באילו מדיניות פעילה, כיצד הן מתנהגות, ומאיפה מדיניות מותאמת אישית נטענת. ההגדרות מעוצבות להיות קלות לשיתוף עם הצוות שלך - בצע commit אליהם למאגר שלך וכל מפתח יקבל את אותה רשת הבטיחות עבור agent. --- -## היקפי תצורה +## היקפי הגדרות -ישנם שלוש היקפי תצורה, המוערכים לפי סדר עדיפויות: +יש שלושה היקפי הגדרות, המוערכים לפי סדר עדיפויות: -| Scope | File path | Purpose | +| היקף | נתיב קובץ | מטרה | |-------|-----------|---------| -| **project** | `.failproofai/policies-config.json` | הגדרות לפי ריפו, תופסות בשליטה גרסאות | -| **local** | `.failproofai/policies-config.local.json` | דריסות אישיות לפי ריפו, gitignored | -| **global** | `~/.failproofai/policies-config.json` | ברירות מחדל ברמת משתמש בכל הפרויקטים | +| **project** | `.failproofai/policies-config.json` | הגדרות לכל מאגר, בcomit לשליטה בגרסאות | +| **local** | `.failproofai/policies-config.local.json` | עקיפה אישית לכל מאגר, מתוך gitignore | +| **global** | `~/.failproofai/policies-config.json` | ברירות מחדל ברמת משתמש לכל הפרויקטים | -כאשר failproofai מקבל אירוע hook, הוא טוען ומוזג את כל שלושת הקבצים שקיימים עבור ספריית העבודה הנוכחית. +כאשר failproofai מקבל אירוע hook, הוא טוען ומוזג את כל שלושת הקובצים שקיימים בספריית העבודה הנוכחית. ### כללי מיזוג -**`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"] ← deduplicated union ``` -**`policyParams`** - ההיקף הראשון שמגדיר פרמטרים לכלל מסוים מנצח לחלוטין. אין מיזוג עמוק של ערכים בתוך פרמטרים של כלל. +**`policyParams`** - ההיקף הראשון שמגדיר פרמטרים לmדיניות מסוימת מנצח לחלוטין. אין מיזוג עמוק של ערכים בתוך הפרמטרים של המדיניות. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← project wins, global ignored +resolved: { allowPatterns: ["sudo apt-get update"] } ← project מנצח, global מתוספר ``` ```text @@ -46,7 +46,7 @@ project: (no block-sudo entry) local: (no block-sudo entry) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← falls through to global +resolved: { allowPatterns: ["sudo systemctl status"] } ← יורד לכלל הglobal ``` **`customPoliciesPath`** - ההיקף הראשון שמגדיר אותו מנצח. @@ -55,7 +55,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← falls through to glo --- -## פורמט קובץ קונפיגורציה +## פורמט קובץ הגדרות ```json { @@ -96,33 +96,33 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← falls through to glo --- -## הפניה לשדות +## התייחסות לשדות ### `enabledPolicies` -Type: `string[]` +סוג: `string[]` -רשימת שמות כללים להפעלה. השמות חייבים להתאים בדיוק למזהי הכללים המוצגים על ידי `failproofai policies`. ראה [Built-in Policies](/he/built-in-policies) לקבלת הרשימה המלאה. +רשימת שמות המדיניות שיש להפעיל. השמות חייבים להתאים בדיוק לזהויות המדיניות המוצגות על ידי `failproofai policies`. ראה [Built-in Policies](/he/built-in-policies) לקבלת הרשימה המלאה. -כללים שאינם ב-`enabledPolicies` אינם פעילים, גם אם יש להם ערכים ב-`policyParams`. +מדיניות שלא ב`enabledPolicies` אינן פעילות, גם אם יש להן רשומות ב`policyParams`. ### `policyParams` -Type: `Record>` +סוג: `Record>` -דריסות פרמטרים לפי כלל. המפתח החיצוני הוא שם הכלל; המפתחות הפנימיים הם ספציפיים לכלל. כל כלל מתעד את הפרמטרים הזמינים שלו ב-[Built-in Policies](/he/built-in-policies). +עקיפות פרמטרים לכל מדיניות. המפתח החיצוני הוא שם המדיניות; המפתחות הפנימיים ספציפיים למדיניות. כל מדיניות מתעדת את הפרמטרים הזמינים שלה ב[Built-in Policies](/he/built-in-policies). -אם לכלל יש פרמטרים אך אתה לא מציין אותם, משתמשים בברירות המחדל המובנות של הכלל. משתמשים שלא מגדירים `policyParams` בכלל מקבלים התנהגות זהה לגרסאות קודמות. +אם למדיניות יש פרמטרים אך אתה לא מציין אותם, משמשים ברירות המחדל המובנות של המדיניות. משתמשים שאינם מגדירים את `policyParams` כלל מקבלים התנהגות זהה לגרסאות קודמות. -מפתחות לא ידועים בתוך בלוק פרמטרים של כלל מתעלמים בשקט בעת הפעלת hook אך מסומנים כאזהרות כאשר אתה מריץ `failproofai policies`. +מפתחות לא ידועים בתוך בלוק הפרמטרים של מדיניות מתעלמים בשקט בזמן הפעלת hook אך מסומנים כאזהרות כאשר אתה מריץ `failproofai policies`. -#### `hint` (cross-cutting) +#### `hint` (חוצה פעולות) -Type: `string` (optional) +סוג: `string` (בחירה) -הודעה שמצורפת לסיבה כאשר כלל מחזיר `deny` או `instruct`. השתמש בה כדי להדריך את Claude עם הנחיות ניתנות לפעולה מבלי לשנות את הכלל עצמו. +הודעה שצורפה לסיבה כאשר מדיניות מחזירה `deny` או `instruct`. השתמש בה כדי לתן לClaude הדרכה פעולה ישירה ללא שינוי המדיניות עצמה. -עובד עם כל סוג כלל — מובנה, מותאם (`custom/`), קונבנציה של פרויקט (`.failproofai-project/`), או קונבנציה של משתמש (`.failproofai-user/`). +עובד עם כל סוג מדיניות — מובנה, מותאם אישית (`custom/`), מוסכמת פרויקט (`.failproofai-project/`), או מוסכמת משתמש (`.failproofai-user/`). ```json { @@ -143,38 +143,38 @@ Type: `string` (optional) כאשר `block-force-push` מסרב, Claude רואה: *"Force-pushing is blocked. Try creating a fresh branch instead."* -ערכים שאינם string ומחרוזות ריקות מתעלמים בשקט. אם `hint` אינו מוגדר, ההתנהגות לא משתנית (תואמת לאחור). +ערכים שאינם מחרוזות ומחרוזות ריקות מתעלמים בשקט. אם `hint` לא מוגדר, ההתנהגות לא משתנה (תאימות לאחור). ### `customPoliciesPath` -Type: `string` (absolute path) +סוג: `string` (נתיב מוחלט) -נתיב לקובץ JavaScript המכיל כללים מותאמים לחטיפה. זה מוגדר באופן אוטומטי על ידי `failproofai policies --install --custom ` (הנתיב מומר להנחלה מוחלטת לפני שהוא מאוחסן). +נתיב לקובץ JavaScript המכיל מדיניות hook מותאמת אישית. זה מוגדר באופן אוטומטי על ידי `failproofai policies --install --custom ` (הנתיב מוחזר לערך מוחלט לפני שנשמר). -הקובץ נטען מחדש בכל אירוע hook - אין קשימון. ראה [Custom Policies](/he/custom-policies) לפרטי יצירה. +הקובץ נטען מחדש בכל אירוע hook - אין caching. ראה [Custom Policies](/he/custom-policies) לפרטי כתיבה. -### כללים מבוססי קונבנציה +### מדיניות מבוססת מוסכמה -בנוסף ל-`customPoliciesPath` המפורש, failproofai גם גילוי ותיקטון באופן אוטומטי קבצי כללים מספריות `.failproofai/policies/`: +בנוסף לעקיפה ההפנייה `customPoliciesPath`, failproofai גילוי ויוטען באופן אוטומטי קובצי מדיניות מתיקיות `.failproofai/policies/`: -| Level | Directory | Scope | +| רמה | ספרייה | היקף | |-------|-----------|-------| -| Project | `.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`. פשוט צניח קבצים לתוך הספרייה והם יילקחו בחדוות אירוע hook הבא. +**אין צורך בהגדרה:** מדיניות מוסכמה אינה דורשת רשומות ב`policies-config.json`. פשוט שים קובצים בספרייה והם אוסף בהתקדמות hook הבא. -**טעינת איחוד:** גם ספריות קונבנציה של פרויקט וגם משתמש נסרקות. כל הקבצים המתאימים משתי הרמות נטענים (בניגוד ל-`customPoliciesPath` שמשתמש בניצחון ההיקף הראשון). +**טעינה איחוד:** גם ספריות מוסכמה של פרויקט וגם משתמש סרוקות. כל קובצים תואמים משתי הרמות נטענים (שלא כמו `customPoliciesPath` אשר משתמש בראשון-היקף-מנצח). -ראה [Custom Policies](/he/custom-policies) לפרטים ודוגמאות נוספים. +ראה [Custom Policies](/he/custom-policies) לפרטים נוספים וודוגמאות. ### `llm` -Type: `object` (optional) +סוג: `object` (בחירה) -תצורת לקוח LLM לכללים העורכים קריאות AI. לא נדרש לרוב ההגדרות. +הגדרות לקוח LLM למדיניות שמבצעות קריאות AI. לא נדרש לרוב ההגדרות. ```json { @@ -187,21 +187,22 @@ Type: `object` (optional) --- -## ניהול תצורה מה-CLI +## ניהול הגדרות מ-CLI -הפקודות `policies --install` ו-`policies --uninstall` כותבות לקובץ הגדרות hook של ה-CLI של הסוכן שלך (נקודות הכניסה של hook), בעוד `policies-config.json` הוא הקובץ שאתה מנהל ישירות. השניים נפרדים: +הפקודות `policies --install` ו`policies --uninstall` כותבות לקובץ הגדרות hook של ה-CLI של ה-agent (נקודות הכניסה של hook), בעוד ש`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`. ערכי Hook משתמשים בשדות הפקודה `bash`/`powershell` של Copilot עם `timeoutSec`; הקובץ נושא סימן `version: 1` ברמה עליונה. תמיכת Copilot CLI היא **beta** בזמן שאנו מאמתים את סכמת רשומות `events.jsonl` (שהתיעוד הציבורי אינו מציין) מול יותר הפעלות בעולם האמיתי. - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — Cursor אין לו היקף `local`. ערכי Hook משתמשים בצורה `{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` (user), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (project) — OpenCode אין לו היקף `local`. בניגוד לשישת ה-CLIs האחרים, OpenCode **אין לו מערכת hook חיצונית**: הוא טוען בתהליך JS/TS plugins שנרשמו במפורש דרך המערך `plugin: []` ב-`opencode.json` (auto-discovery מ-`.opencode/plugins/` אינו כיצד plugins טוענים ב-opencode v1.14.33). Install טוען קובץ זעיר שנוצר של plugin שקורא subprocess לבינארי failproofai ותורגם את התגובה JSON של הבינארי חזרה לסמנטיקה של plugin: `throw new Error()` להכחשת אירוע כלי (מבטל את קריאת הכלי), `client.session.prompt(...)` עבור instruct וגם עבור `Stop` / `SubagentStop` deny (שולח את סיבת ההכחשה כהודעת המשתמש הבאה — ערוץ force-retry היחיד מאז `session.idle` הוא notification-only והשלכת זה אינו פעולה), ו-no-op לאפשרות. קובץ קנוני שם של כלי (lowercase → PascalCase דרך `OPENCODE_TOOL_MAP`) וקלידי arg של כניסת כלי (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** בזמן שאנו מאמתים התנהגות בחדוות וגרסאות מול יותר הפעלות בעולם האמיתי. ראה את [תיעוד plugins של OpenCode](https://opencode.ai/docs/plugins/). - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `/.pi/settings.json` (project) — Pi אין לו היקף `local`. Pi טוען חבילות הרחבה TypeScript בעת ההפעלה; הקובץ הגדרות הוא מערך string שטוח `{"packages": ["./relative/path", …]}`. failproofai כותב ערך מערך packages אחד המצביע על ספרייה `pi-extension/` משובצת שלו. ההרחבה מבחינים פנימיים במחזור subscriptions של Pi כדי `tool_call` / `user_bash` / `input` / `session_start` ופירות לתוך `failproofai --hook --cli pi`; המטפל קנוני underscore_lower_snake_case → PascalCase דרך `PI_EVENT_MAP` כך שכללים מובנים קיימים יורים ללא שינוי. קלידי arg של כניסת כלי גם קנוניים דרך `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit מסירה `path` רמוק מאשר `file_path`; קלידי המפתח העליון מאפשר `block-env-files` ו-`block-secrets-write` לירות — `block-read-outside-cwd` כבר היה `path` fallback). תמיכת Pi היא **beta** בזמן שעומדת ל-stabilize. - - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (user), `/.gemini/settings.json` (project) — Gemini אין לו היקף `local` (הוא מתעד היקף `system` ב-`/etc/gemini-cli/settings.json` אשר failproofai לא חשוף). Hook entries משתמשים בצורה `{type, command, timeout}` של Claude עטופה בסכמת matcher של Gemini `{matcher, hooks: [...]}` עם `matcher: "*"` כברירת מחדל. אירועים הם PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); המטפל ממפה לשמות קנוניים של Claude דרך `GEMINI_EVENT_MAP`. שמות כלים הם snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — המטפל מקנוני דרך `GEMINI_TOOL_MAP` כך שכללים מובנים קיימים יורים ללא שינוי. משקיף מדיניות משיג צורה שטוחה של Gemini `{decision: "deny", reason}` (מועדפת לכל Golden Rule exit-0 של Gemini), `{hookSpecificOutput: {hookEventName, additionalContext}}` להזרקת הקשר ב-BeforeAgent / AfterTool / SessionStart, ו-`{decision: "block", reason}` ב-AfterAgent לסמנטיקה force-retry. תמיכת Gemini CLI היא **beta** בזמן שאנו מגדילים כיסוי בעולם האמיתי. ראה את [תיעוד hooks של Gemini CLI](https://geminicli.com/docs/hooks/). -- **`policies-config.json`** — אומר ל-failproofai אילו כללים להעריך וויים פרמטרים (משותף בכל סוכני CLI) +- **הגדרות 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 משתמשות בשדות פקודה `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 וסכימת יומן הישיבה מתייצבות. + - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (משתמש), `/.gemini/settings.json` (פרויקט) — Gemini אין לו היקף `local` (הוא מתעד היקף `system` ב`/etc/gemini-cli/settings.json` שfalieproofai אינו חושף). רשומות Hook משתמשות בצורה `{type, command, timeout}` של Claude מגולפת בסכימת matcher של Gemini `{matcher, hooks: [...]}` עם `matcher: "*"` כברירת מחדל. אירועים הם PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); המטפל ממפה לשמות הקנוניים של Claude דרך `GEMINI_EVENT_MAP`. שמות כלים הם snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — המטפל מנרמל דרך `GEMINI_TOOL_MAP` כך שמדיניות מובנות קיימות נשרפות ללא שינוי. מעריך המדיניות משדרת צורה שטוחה של Gemini `{decision: "deny", reason}` (מעדיפה לפי הכלל הזהב של Gemini exit-0), `{hookSpecificOutput: {hookEventName, additionalContext}}` להזרקת הקשר על BeforeAgent / AfterTool / SessionStart, ו`{decision: "block", reason}` על AfterAgent עבור סמנטיקת כפיית retry. תמיכת Gemini CLI היא **beta** בעודנו מרחיבים כיסוי בעולם אמיתי. ראה את [דוקים של hooks של Gemini CLI](https://geminicli.com/docs/hooks/). + - **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|gemini` למטרה סוכן ספציפי (space-separated או חוזר לכל תת-קבוצה): +עבור מטרה לחלק agent מסוים העבור space-separated או חוזר על כל תת-קבוצה: ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +211,24 @@ 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 gemini --scope project +failproofai policies --install --cli hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` -כאשר `--cli` מושמט, `failproofai` מגלה אילו סוכני CLI מותקנים (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): +כאשר `--cli` מושמט, `failproofai` מגלה אילו CLI של agent מותקנות (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini` / `which hermes`): -- **CLI אחד detected** — בחר אוטומטי את זה CLI ללא הנמקה. -- **מספר CLIs detected** בטרמינל אינטראקטיבי — מציג בחירה יחידה במקלדת בחצים מקובצת לחלק `Detected (N)` (עם שורה מצטברת `Install for all N detected` + כל CLI detected בנפרד) וחלק `Not installed (M) · install hooks ahead of time` רשימה כל CLI שלא detected כאפשרות forward-install (↑↓ להעברה, Enter לבחירה, ^C לצאת). זרימת ה-uninstall מציגה רק את חלק Detected. -- **מספר CLIs detected** בריצה לא אינטראקטיבית (CI, no TTY) — מתקן להמון detected CLIs ללא הנמקה. -- **None detected** — חוזר ל-`claude`, עם אזהרה שלא binary agent נמצא ב-PATH; פקודת hook עדיין כתובה כך היא מופעלת ברגע שאתה מתקן אחד. +- **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 עדיין נכתבה כך היא מופעלת ברגע שתתקין אחד. -אתה יכול לערוך `policies-config.json` ישירות בכל עת; שינויים ישפיעו מיד על אירוע hook הבא ללא צורך בהפעלה מחדש. +אתה יכול לערוך `policies-config.json` ישירות בכל עת; השינויים נכנסים לתוקף מיד באירוע hook הבא ללא צורך בהפעלה מחדש. --- -## דוגמה: תצורה ברמת פרויקט עם ברירות מחדל של צוות +## דוגמה: תצורה ברמת פרויקט עם ברירות ברירת מחדל לצוות -Commit `.failproofai/policies-config.json` לריפו שלך: +Commit `.failproofai/policies-config.json` למאגר שלך: ```json { @@ -245,4 +247,4 @@ Commit `.failproofai/policies-config.json` לריפו שלך: } ``` -כל מפתח יכול ליצור `.failproofai/policies-config.local.json` (gitignored) עבור דריסות אישיות ללא הפרעה לעמיתים. \ No newline at end of file +כל מפתח יכול ליצור `.failproofai/policies-config.local.json` (מתוך gitignore) לעקיפות אישיות ללא הפרת עמיתים. \ No newline at end of file diff --git a/docs/he/custom-policies.mdx b/docs/he/custom-policies.mdx index 895fdc00..a3510f97 100644 --- a/docs/he/custom-policies.mdx +++ b/docs/he/custom-policies.mdx @@ -1,10 +1,10 @@ --- title: מדיניות מותאמות אישית -description: "כתוב כללים משלך ב-JavaScript - אכוף קונוונציות, מנע סחיפה, גלה כשלים, השתלב עם מערכות חיצוניות" +description: "כתוב את הכללים שלך בJavaScript - אכוף קונוונציות, עצור סטייה, גלה כשלים, השתלב עם מערכות חיצוניות" icon: code --- -מדיניות מותאמות אישית מאפשרת לך לכתוב כללים לכל התנהגות של סוכן: אכוף קונוונציות פרויקט, מנע סחיפה, עצור פעולות הרסניות, גלה סוכנים תקועים, או השתלב עם Slack, זרימות אישור, ועוד. הם משתמשים באותו מערכת אירועי hook וגם בהחלטות `allow`, `deny`, `instruct` כמו המדיניות המובנית. +מדיניות מותאמות אישית מאפשרת לך לכתוב כללים לכל התנהגות סוכן: אכוף קונוונציות של פרויקט, עצור סטייה, חסום פעולות הרסניות, גלה סוכנים תקועים, או השתלב עם Slack, זרימות אישור, ועוד. הם משתמשים באותה מערכת אירועי hook וה-`allow`, `deny`, `instruct` כמו מדיניות מובנית. --- @@ -29,7 +29,7 @@ customPolicies.add({ }); ``` -התקן אותה: +התקנה: ```bash failproofai policies --install --custom ./my-policies.js @@ -41,56 +41,56 @@ failproofai policies --install --custom ./my-policies.js ### אפשרות 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-` כדי לשלוט בסדר -- רק קבצים תואמים ל-`*policies.{js,mjs,ts}` נטענים; קבצים אחרים מתעלמים -- כל קובץ נטען באופן עצמאי (fail-open לקובץ) -- עובד לצד מדיניות מפורשת `--custom` ומדיניות מובנית +- שני הספריות של פרויקט ומשתמש נסרקים (union — לא first-scope-wins) +- קבצים נטענים בסדר אלפבתי בתוך כל ספריה. הוסף קידומת עם `01-`, `02-` כדי לשלוט בסדר +- רק קבצים התואמים `*policies.{js,mjs,ts}` נטענים; קבצים אחרים מתעלמים +- כל קובץ נטען באופן עצמאי (fail-open לכל קובץ) +- עובד לצד `--custom` מפורש ומדיניות מובנית -מדיניות קונוונציה היא הדרך הקלה ביותר לבנות תקן איכות עבור הארגון שלך. הצע `.failproofai/policies/` ל-git וכל חברי הצוות מקבלים אותם כללים באופן אוטומטי — אין צורך בהגדרה לכל מפתח. כשהצוות שלך מגלה אופני כשל חדשים, הוסף מדיניות ודחוף. לאורך זמן אלה הופכים לתקן איכות חי המשתפר עם כל תרומה. +מדיניות קונוונציה היא הדרך הקלה ביותר לבנות תקן איכות לארגון שלך. Commit `.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 --uninstall --custom ``` -הנתיב המוחלט שנפתר מאוחסן ב-`policies-config.json` כ-`customPoliciesPath`. הקובץ נטען בצורה טרייה בכל אירוע hook - אין אחסון זיכרון מטמון בין אירועים. +הנתיב המוחלט המוחזר מאוחסן ב-`policies-config.json` כ-`customPoliciesPath`. הקובץ נטען בטרי בכל אירוע hook - אין caching בין אירועים. ### שימוש בשניהם יחד מדיניות קונוונציה וקובץ `--custom` מפורש יכולים להתקיים. סדר טעינה: 1. קובץ `customPoliciesPath` מפורש (אם מוגדר) -2. קובצי קונוונציה פרויקט (`{cwd}/.failproofai/policies/`, אלפביתי) -3. קובצי קונוונציה משתמש (`~/.failproofai/policies/`, אלפביתי) +2. קבצי קונוונציה של פרויקט (`{cwd}/.failproofai/policies/`, בסדר אלפבתי) +3. קבצי קונוונציה של משתמש (`~/.failproofai/policies/`, בסדר אלפבתי) --- ## API -### ייבוא +### Import ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -98,45 +98,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)` | הוסף הקשר בלי לחסום | תן לסוכן הקשר נוסף כדי להישאר על המסלול | +| `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(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,48 +160,48 @@ customPolicies.add({ | שדה | סוג | תיאור | |-------|------|-------------| | `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` | הכלי שנקרא (לדוגמה `"Bash"`, `"Write"`, `"Read"`) | +| `toolInput` | `Record \| undefined` | פרמטרי הקלט של הכלי | +| `payload` | `Record` | דיפלומת אירוע גולמית מלאה מ-Claude Code | +| `session` | `SessionMetadata \| undefined` | הקשר סשן (ראה להלן) | ### שדות `SessionMetadata` | שדה | סוג | תיאור | |-------|------|-------------| | `sessionId` | `string` | מזהה סשן Claude Code | -| `cwd` | `string` | ספריית עבודה של סשן Claude Code | +| `cwd` | `string` | ספרייה עובדת של סשן Claude Code | | `transcriptPath` | `string` | נתיב לקובץ תמליל JSONL של הסשן | ### סוגי אירועים -| אירוע | מתי הוא נעיר | תוכן `toolInput` | +| אירוע | כאשר הוא משתלח | תוכן `toolInput` | |-------|--------------|----------------------| -| `PreToolUse` | לפני ש-Claude מריץ כלי | קלט הכלי (למשל `{ command: "..." }` עבור Bash) | -| `PostToolUse` | לאחר שכלי משלים | קלט הכלי + `tool_result` (הפלט) | +| `PreToolUse` | לפני Claude מריץ כלי | הקלט של הכלי (לדוגמה `{ command: "..." }` עבור Bash) | +| `PostToolUse` | לאחר השלמת כלי | הקלט של הכלי + `tool_result` (הפלט) | | `Notification` | כאשר Claude שולח הודעה | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks חייבים תמיד להחזיר `allow()`, הם לא יכולים לחסום הודעות | -| `Stop` | כאשר סשן Claude מסתיים | ריק | +| `Stop` | כאשר הסשן של Claude מסתיים | ריק | --- ## סדר הערכה -מדיניויות מוערכות בסדר זה: +מדיניות מוערכת בסדר זה: -1. מדיניויות מובנות (בסדר הגדרה) -2. מדיניויות מותאמות אישית מפורשות מ-`customPoliciesPath` (בסדר `.add()`) -3. מדיניויות קונוונציה מפרויקט `.failproofai/policies/` (קבצים אלפביתיים, סדר `.add()` בתוך) -4. מדיניויות קונוונציה מ-`~/.failproofai/policies/` של משתמש (קבצים אלפביתיים, סדר `.add()` בתוך) +1. מדיניות מובנית (בסדר הגדרה) +2. מדיניות מותאמת אישית מפורשת מ-`customPoliciesPath` (בסדר `.add()`) +3. מדיניות קונוונציה מ-`.failproofai/policies/` של פרויקט (קבצים אלפבתיים, סדר `.add()` בתוך) +4. מדיניות קונוונציה מ-`~/.failproofai/policies/` של משתמש (קבצים אלפבתיים, סדר `.add()` בתוך) -ה-`deny` הראשון מקצר את כל המדיניויות הבאות. כל הודעות `instruct` מצטברות ומסופקות יחד. +ה-`deny` הראשון מקצר את כל המדיניות הלאה. כל הודעות `instruct` מצטברות ומועברות יחד. --- -## ייבואים טרנזיטיביים +## ייבוא טרנזיטיבי -קובצי מדיניות מותאמת אישית יכולים לייבא מודולים מקומיים באמצעות נתיבים יחסיים: +קבצי מדיניות מותאמים אישית יכולים לייבא מודולים מקומיים באמצעות נתיבים יחסיים: ```js // my-policies.js @@ -218,46 +218,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**: שגיאות לעולם לא חוסמות מדיניות מובנית או מקריסות מטפל ה-hook. +מדיניות מותאמת אישית היא **fail-open**: שגיאות לעולם לא חוסמות מדיניות מובנית או קורסות מטפל ה-hook. | כשל | התנהגות | |---------|----------| -| `customPoliciesPath` לא מוגדר | אין מדיניות מותאמת אישית מפורשת שתרוצה; מדיניויות קונוונציה וביטויים מובנים ממשיכים בדרך כלל | -| קובץ לא נמצא | אזהרה מוקדשת ל-`~/.failproofai/hook.log`; ביטויים מובנים ממשיכים | -| שגיאת תחביר/ייבוא (מפורשת) | שגיאה מוקדשת ל-`~/.failproofai/hook.log`; מדיניות מותאמת אישית מפורשת דלגה | -| שגיאת תחביר/ייבוא (קונוונציה) | שגיאה מוקדשת; קובץ זה דלג, קובצי קונוונציה אחרים עדיין טוענים | -| `fn` זורק בזמן ריצה | שגיאה מוקדשת; hook זה מטופל כ-`allow`; hooks אחרים ממשיכים | -| `fn` לוקח יותר מ-10 שניות | timeout מוקדש; מטופל כ-`allow` | -| ספריית קונוונציה חסרה | אין מדיניויות קונוונציה שרוצות; אין שגיאה | +| `customPoliciesPath` לא מוגדר | לא מחוגות מדיניות מותאמת אישית מפורשת; מדיניות קונוונציה ומובנית ממשיכות בדרך כלל | +| קובץ לא נמצא | אזהרה מתועדת ל-`~/.failproofai/hook.log`; מובנית ממשיכה | +| שגיאת תחביר/ייבוא (מפורשת) | שגיאה מתועדת ל-`~/.failproofai/hook.log`; מדיניות מותאמת אישית מפורשת דלגת | +| שגיאת תחביר/ייבוא (קונוונציה) | שגיאה מתועדת; קובץ זה דולג, קבצי קונוונציה אחרים עדיין נטענים | +| `fn` זורק בזמן ריצה | שגיאה מתועדת; ה-hook הזה מטופל כ-`allow`; hook אחר ממשיך | +| `fn` לוקח יותר מ-10s | timeout מתועד; מטופל כ-`allow` | +| ספרייה קונוונציה חסרה | לא מחוגות מדיניות קונוונציה; אין שגיאה | -כדי לנפות שגיאות במדיניות מותאמת אישית, צפו בקובץ היומן: +כדי לתפוס שגיאות מדיניות מותאמת אישית, צפה בקובץ היומן: ```bash tail -f ~/.failproofai/hook.log @@ -266,13 +266,13 @@ tail -f ~/.failproofai/hook.log --- -## דוגמה מלאה: מדיניויות מרובות +## דוגמה מלאה: מדיניות מרובה ```js // 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 +285,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 +300,7 @@ customPolicies.add({ }, }); -// מנע שינויי תלות בלתי מתוכננים במהלך הקפאה +// Prevent unplanned dependency changes during freeze customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -323,16 +323,16 @@ export { customPolicies }; ## דוגמאות -ספריית `examples/` מכילה קובצי מדיניות מוכנים להרצה: +ספרייה `examples/` מכילה קבצי מדיניות מוכנים להפעלה: | קובץ | תוכן | |------|----------| -| `examples/policies-basic.js` | חמש מדיניויות התחלתיות המכסות אופני כשל סוכן נפוצים | -| `examples/policies-advanced/index.js` | דפוסים מתקדמים: ייבואים טרנזיטיביים, קריאות אסינכרוניות, גישול פלט, וqueries hook של סיום סשן | -| `examples/convention-policies/security-policies.mjs` | מדיניויות אבטחה מבוססות קונוונציה (חסום כתיבה של .env, מנע כתיבת מחדש של היסטוריה של git) | -| `examples/convention-policies/workflow-policies.mjs` | מדיניויות זרימת עבודה מבוססות קונוונציה (תזכורות בדיקה, קובצי כתיבה בודקים) | +| `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` | מדיניות זרימת עבודה מבוססת קונוונציה (תזכורות בדיקה, קובץ כתיבה ביקורת) | -### שימוש בדוגמאות קובץ מפורש +### שימוש בדוגמאות קבצים מפורשות ```bash failproofai policies --install --custom ./examples/policies-basic.js @@ -341,13 +341,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/ ``` -אין צורך בפקודת התקנה — הקבצים נבחרים באופן אוטומטי בכל אירוע 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 2b66e534..50ffc990 100644 --- a/docs/he/dashboard.mdx +++ b/docs/he/dashboard.mdx @@ -1,10 +1,11 @@ --- -title: לוח בקרה -description: "מراقبة جلسات الوكيل، مراجعة استدعاءات الأدوات، وإدارة السياسات" +--- +title: לוח הבקרה +description: "עקוב אחר הפעלות של סוכנים, בדוק קריאות כלים וניהול מדיניות" icon: chart-line --- -לוח הבקרה של failproofai הוא יישום אינטרנט מקומי לניטור של جلسات סוכני AI שלך וניהול מדיניויות. ראה מה העשו הסוכנים שלך בזמן שהיית רחוק. +לוח הבקרה של failproofai הוא אפליקציית ווב מקומית לניטור הפעלות סוכני ה-AI שלך וניהול מדיניות. ראה מה עשו הסוכנים שלך בזמן שהיית רחוק. --- @@ -14,81 +15,77 @@ icon: chart-line failproofai ``` -נפתח ב-`http://localhost:8020`. +נפתח בכתובת `http://localhost:8020`. -לוח הבקרה קורא ישירות מקובץ המערכת - תיקיות הפרויקט Claude Code שלך וקובצי הגדרות failproofai. שום דבר לא נכתב לשירות מרחוק. +לוח הבקרה קורא ישירות מקובץ המערכת - תיקיות Claude Code שלך וקובצי הקונפיגורציה של failproofai. שום דבר לא כתוב לשירות מרחוק. --- -## דפים +## עמודים ### Projects -רשימה של כל פרויקטי Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, ו-Gemini CLI _(beta)_ שנמצאו במחשב שלך. פרויקטי Claude מתגלים מ-`~/.claude/projects/` (או המסלול שנקבע על ידי `CLAUDE_PROJECTS_PATH`); פרויקטי Codex מתגלים על ידי סריקת כל תמלול תחת `~/.codex/sessions///
/*.jsonl` וקיבוץ לפי `cwd` המוקלט בתיעוד הראשון של כל סession; פרויקטי Copilot CLI מתגלים על ידי סריקת `~/.copilot/session-state//workspace.yaml` (הניתן להגדרה דרך `COPILOT_HOME`) וקיבוץ לפי שדה `cwd` שלו; פרויקטי Cursor Agent מתגלים על ידי סריקת מטא-נתונים לכל סession תחת `~/.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 לכל סession תחת `~/.pi/agent/sessions//_.jsonl` (הניתן להגדרה דרך `PI_SESSIONS_DIR`) ושימור `cwd` מתיעוד הראשון של כל סession; פרויקטי Gemini CLI מתגלים על ידי סריקת `~/.gemini/tmp//chats/session--.jsonl` (הניתן להגדרה דרך `GEMINI_SESSIONS_DIR`) והחזרת cwd הקנוני מסימן `project_root` הטקסטי הסמוך. פרויקט שהשתמשו בו מספר CLIs מוצג בשורה אחת עם כל התגים המתאימים. השתמש בתפריט הנפתח **CLI** מעל הטבלה כדי לסנן לפי CLI סוכן ספציפי; ה-URL משמר את הבחירה שלך כ-`?cli=claude|codex|copilot|cursor|opencode|pi|gemini`. +מפרט את כל Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Gemini CLI _(beta)_, ו-Hermes שנמצאו במחשב שלך. פרויקטי 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` מתיעוד הראשון של כל הפעלה; פרויקטי Gemini CLI מגולים על ידי סריקת `~/.gemini/tmp//chats/session--.jsonl` (ניתן להגדיר דרך `GEMINI_SESSIONS_DIR`) והחזרת ה-cwd הקנוני ממסמן `.project_root` הסמוך; הפעלות שער Hermes נקראות ישירות מחנות SQLite שלה ב-`~/.hermes/state.db` (ניתן להגדיר דרך `HERMES_DB_PATH`) וקיבוץ לפרויקטי `hermes-` לפי `source` (Slack/Telegram/cli/cron — להפעלות שער אין cwd). פרויקט ששימש מספר CLIs מרואה כשורה יחידה עם כל התגים המתאימים. השתמש בתפריט **CLI** מעל הטבלה לסינון לפי סוכן CLI ספציפי; ה-URL משמר את הבחירה שלך כ-`?cli=claude|codex|copilot|cursor|opencode|pi|gemini|hermes`. כל פרויקט מציג: -- שם הפרויקט (מושא מנתיב התיקייה) -- תג CLI — `Claude Code` (כתום), `OpenAI Codex` (סגול), `GitHub Copilot` (כחול), `Cursor Agent` (זמרד), `OpenCode` (ענבר), `Pi` (ורוד), ו/או `Gemini CLI` (שמיים) -- תאריך של פעילות הסession הקודמת +- שם הפרויקט (מגובש מנתיב התיקייה) +- תג CLI — `Claude Code` (כתום), `OpenAI Codex` (סגול), `GitHub Copilot` (כחול), `Cursor Agent` (אזמרגד), `OpenCode` (ענבר), `Pi` (ורוד), `Gemini CLI` (שמיים), ו/או `Hermes` (אינדיגו) +- תאריך של פעילות הפעלה האחרונה -לחץ על פרויקט כדי לראות את הsessions שלו. +לחץ על פרויקט כדי לראות את הפעלות שלו. ### Sessions -רשימה של כל הsessions בתוך פרויקט. כל סession מציג: -- Session ID -- חותמות זמן התחלה וסיום -- מספר קריאות הכלים -- ספירת פעילות hook (מדיניויות שהופעלו) +מפרט את כל הפעלות בתוך פרויקט. כל הפעלה מציגה: +- מזהה הפעלה +- חותמות זמן של התחלה וסיום +- מספר קריאות כלים +- ספירת פעילות קורא (מדיניות שנשדרה) -השתמש בסנן טווח התאריך וחיפוש Session ID כדי לצמצם את הרשימה. Sessionsים מחולקים לעמודים. +השתמש במסנן טווח התאריכים ובחיפוש מזהה הפעלה כדי לצמצם את הרשימה. הפעלות מחולקות לעמודים. -לחץ על סession כדי לפתוח את מציג הsession. +לחץ על הפעלה כדי לפתוח את מצפה הפעלה. -### מציג Session +### מצפה הפעלה -מציג הsession עונה על השאלה המרכזית עבור סוכנים אוטונומיים: מה עשה הסוכן, והאם הוא נשאר בעקבות? תג CLI ליד הכותרת מציין האם הsession הוא תמלול Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, או Gemini CLI. הוא מציג ציר הזמן של כל מה שקרה בsession: +מצפה הפעלה עונה על השאלה המרכזית לסוכנים אוטונומיים: מה עשה הסוכן, והאם הוא נשאר בעקוב? תג CLI ליד הכותרת מציין אם ההפעלה היא Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Gemini CLI, או תמליל Hermes. הוא מציג ציר הזמן של כל מה שקרה בהפעלה: -- **Messages** - תגובות טקסט של Claude והודעות משתמש -- **Tool calls** - כל כלי שClaude הפעיל, עם הקלט והפלט שלו -- **Policy activity** - לכל קריאת כלי, אילו מדיניויות הופעלו ואיזו החלטה הן החזירו +- **הודעות** - תגובות טקסט של Claude והנחיות משתמש +- **קריאות כלים** - כל כלי שקרא Claude, עם הקלט והפלט שלו +- **פעילות מדיניות** - לכל קריאת כלים, אילו מדיניות נשדרה ואילו החלטה הן החזירו -סרגל הסטטיסטיקה בחלק העליון מציג משך הsession, סך כל קריאות הכלים, וסיכום החלטות hook (ספירות allow / deny / instruct). +סרגל הנתונים בחלק העליון מציג משך הפעלה, סה"כ קריאות כלים, וסיכום החלטות קורא (ספירות allow / deny / instruct). -לחץ על כפתור **Download Logs** כדי לייצא את הsession. עבור Sessionsי Claude Code, Codex, Copilot, Cursor, Pi, ו-Gemini אתה מקבל את תמלול JSONL המקורי בדיסק בתים-בתים; עבור OpenCode (שהsessionsים שלה חיים ב-SQLite, לא בדיסק) אתה מקבל מסמך JSON המשקף את הטבלאות `session` / `messages` / `parts` הבסיסיות. +לחץ על כפתור **Download Logs** כדי לייצא את ההפעלה. עבור Claude Code, Codex, Copilot, Cursor, Pi, ו-Gemini תקבל את תמליל JSONL המקורי על הדיסק בדיוק כפי שהוא; עבור OpenCode (שהפעלות שלה חיות ב-SQLite, לא על הדיסק) תקבל מסמך JSON המשקף את טבלאות `session` / `messages` / `parts` הבסיסיות. ### Audit -דוח מונע בעקבות אישיות איך הסוכן שלך התנהג בפועל על פני sessionsים קודמים. מפעיל את אותה סריקה כמו CLI `failproofai audit` אבל מעניק אותה כפוסטר בן מסך יחיד שניתן לשיתוף + ארבעה חלקים מתחת לקפל: - -1. **Poster** — ממלא את viewport הראשון. אזור PNG בעצמאות המעט עם ה-failproof_ai wordmark + תווית audit · אינדקס archetype (`№ NN of 08`) + תאריך audit · ניקוד מספרי (0–100) + כדור דרגת אחוזון (`top 15%`) · שם archetype (אחד מ-`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 tile של 8×8 פיקסל · `audit yours → failproof.ai` תוחלת. שלושה כפתורי שיתוף יושבים בחוץ מ-capture box: `post your archetype` (X intent), `share on linkedin`, `download poster`. Capture פועל דרך `html-to-image` אז ה-PNG תואם את הרינדור בעל המסך פיקסל-לפיקסל (גבולות מקווקווים, SVG logo mask, gradients, font metrics — הכל משומר). - -2. **Strengths** — שורת רשימה רגועה ✓ של התנהגויות שהסוכן שלך כבר עושה נכון, מביאות מנתוני audit חיוני (קצב קריאת כלים נקי, ללא דחיפות ישירות לראשי, אפס דלפי אישורים, אפס סערות ניסיון) — כל אחת מופיעה רק כאשר למדיניות הרלוונטית יש רקורד נקי על פני חלון ה-audit. - -3. **Quirks** — טבלה של מה שחלף, מדורגת לפי חומרה: `when · what slipped + the policy that would've caught it · severity pill · seen`, כאשר ה-recurrence קורא `new` (פעם אחת), `N× seen` (2–9 פעמים), או `recurring` (10+). - -4. **How to improve** — שורת רשימה רגועה, אחד לכל מדיניות מקבילה: שם מדיניות בלבן, תיאור בשורה אחת, כפתור פקודת התקנה + העתקה בצד ימין. כותרת הסעיף קוראת `enable all N → projected · ` (הניקוד שהייתה תוקף עם כל התיקון המיושם), וכפתור `[install all]` שלו מעתיק את הפקודה `failproofai policy add a b c …` המשולבת לכל מדיניות מקבילה. +דוח מונע על ידי אישיות כיצד סוכן שלך אכן התנהג בהפעלות עבר. מריץ את אותה סריקה כמו CLI של `failproofai audit` אך מעניק לה כל על-מסך בר-שיתוף + ארבעה סעיפים מתחת לקפל: -5. **Come back better** — שתי כרטיסים זה לצד זה. משמאל: הגדרת תזכורת (`3d` / `7d` / `14d` / `30d` בוחר קדנציה; שומר דרך `/api/auth/reminder` ברגע שמאומת). מימין: פתח הטבות failproof — `invite a friend` פותח מודאל שלוקח רשימה מופרדת בפסיק/ספייס/שורה חדשה של אימיילים חברים (מקסימום 10 לשליחה), POSTs להם ל-`/api/audit/invite`, שמעביר לשרת api `POST /v0/invite`. שרת ה-api שולח אימייל אחד לכל מקבל מ-`invite@failproof.ai` עם ה-Cc של השולח וה-`Reply-To` מוגדר, כך שהמקבל רואה מי הזמין אותו והשולח מקבל העתק בתיבת הדואר שלו. משתמשים אנונימיים מעוברים דרך `AuthDialog` תחילה אז אימייל השולח ידוע לפני שההזמנות יוצאות. עמידה / מילוי הטבות הוא מעקב. +1. **Poster** — ממלא את viewport הראשון. אזור תפיסת PNG עצמי עם wordmark 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 intent), `share on linkedin`, `download poster`. התפיסה רצה דרך `html-to-image` כך שה-PNG תואם את העל-מסך בדיוק פיקסל על פיקסל (גבולות מקווקווים, מסיכת לוגו SVG, שיפועים, מטרי גופנים — הכל שמור). +2. **Strengths** — שורת רשימה רגועה ✓ של התנהגויות שהסוכן שלך כבר עושה נכון, הנגזרת מנתוני ביקורת חי (שיעור קריאות כלים נקי, ללא דחיפה ישירה לעיקרי, ללא נזילות זיהויים, ללא סערות ניסיון חוזרות) — כל אחת משטחת רק כאשר למדיניות הרלוונטית רשומה נקייה על פני חלון הביקורת. +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` ברגע שמאומת). ימין: בטל את fullproof perks — `invite a friend` פותח מודאל שלוקח רשימה מופרדת בפסיקים / רווח / שורה חדשה של כתובות דוא"ל של חברים (מקסימום 10 לשליחה), מעלה אותם ל-`/api/audit/invite`, אשר מעביר אותם לאפליקציית `POST /v0/invite` של api-server. ה-api-server שולח דוא"ל אחד לכל נמען מ-`invite@failproof.ai` עם שליחה Cc'd וקביעת `Reply-To`, כך שהנמען רואה מי הזמין אותם והשליחה מקבלת עותק בתיבת הדואר הנכנס שלה. משתמשים אנונימיים מנותבים דרך `AuthDialog` תחילה כך שכתובת הדוא"ל של השליחה ידועה לפני שהזמנות יוצאות. זכאות / fulfillment perks הוא סדר עבודה בעקבות. -מונעות על ידי `failproofai audit` runtime — ראה [Audit CLI](/he/cli/audit) עבור מנוע הסריקה הבסיס, דגלים נתמכים, ובלתי-משתנים cache לכל תמלול. לוח הבקרה משמור את התוצאה העדכנית ביותר ב-`~/.failproofai/audit-dashboard.json` (מצב `0600`, חריץ יחיד, הריצות חדשות משכתבות) אז הביקורים חוזרים מיידיים; **גם ה-per-transcript וגם כל ה-result caches דוחים על קריאה ברגע שהם קדומים יותר מ-7 ימים** אז לוח הבקרה לעולם לא משרת בשקט תוצאה בן שבועות — עבר ה-TTL `/audit` נופל דרך למצב הריק שלו ומתגבר שריקה טרייה. לחיצה על `[ re-audit now ]` ליד תחתית הדוח POSTs `/api/audit/run` עם `noCache: true` — re-audit עוקף את ה-per-transcript cache ומסרק כל תמלול מהעט ​​במקום בשקט להחזיר את התוצאה המטומנת — ולוח הבקרה סוקר `/api/audit/status` ב-1Hz עד שהריצה תסתיים; רצועת התקדמות ורודה דביקה מתלמדת לחלק העליון של ה-viewport במהלך הריצה עם טיימר זמן חלוף, והתוצאה הטרייה משתלבת במקום בהצלחה (לא טעינת עמוד מלא; re-audit כושל משאיר את הדוח הקודם שלם). בכישלון הרצועה הופכת לאדום עם עותק מחובר ל-`RerunError.kind` (`timeout` / `network` / `post_failed`). מצב ריק (אין cache או פקוח) ומצב sessionsים אפס (cache קיים אך הסריקה לא מצאה תמלולים) מוצגים בנפרד. +מונע על ידי זמן ההרצה של `failproofai audit` — ראה [Audit CLI](/he/cli/audit) עבור מנוע הסריקה הבסיסי, דגלים נתמכים, ובלתי ניתנים לשינוי של זיכרון מטמון לכל תמליל. לוח הבקרה שומר את התוצאה האחרונה ב-`~/.failproofai/audit-dashboard.json` (מצב `0600`, חריץ יחיד, הרצות חדשות משכתבות) כך שביקורי חוזרים מיידיים; **גם זיכרון מטמון לכל תמליל וגם תוצאה כוללת נדחו בקריאה ברגע שהם מעבר לגיל של 7 ימים** כך שלוח הבקרה לא משרת בשקט תוצאה בגיל שבוע — עבר ה-TTL `/audit` נופל דרך למצב הריק שלו וזמנים הרצה טרייה. לחיצה על `[ re-audit now ]` ליד תחתית הדוח POSTs `/api/audit/run` עם `noCache: true` — re-audit עוקף את זיכרון המטמון לכל תמליל ועורך סריקה מחדש של כל תמליל מההתחלה ולא משום שמחזירה בשקט את התוצאה המטומנת — לוח הבקרה פולל `/api/audit/status` ב-1Hz עד שההרצה מסיימת; רצועת התקדמות ורודה דביקה קובעת את ראש viewport במהלך ההרצה עם טיימר שחלוף, והתוצאה הטרייה מתחלפת במקום בעת הצלחה (ללא טעינת עמוד מלאה; re-audit כושל משאיר את הדוח הקודם שלם). בעת כשל הרצועה הופכת לאדומה עם עותק מפתח מ-`RerunError.kind` (`timeout` / `network` / `post_failed`). מצב ריק (ללא זיכרון מטמון או פג תוקף) ומצב אפס-הפעלות (זיכרון מטמון קיים אך הסריקה לא מצאה תמליל) משטחים בנפרד. ### Policies -דף שתי-טאב לניהול מדיניויות ובדיקת פעילות. +עמוד דו-כרטיסיה לניהול מדיניות וסקירת פעילות. - - בחר באופן מרובה איזו CLIs סוכן failproofai מגנה מפנל יחיד — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, ו-Gemini CLI כולם יש שורה עם סטטוס התקנה (`Active` / `Detected` / `Inactive`), נתיב הגדרות ה-user-scope, וכן נקודה צבעי-מותג. סמן או בטל סימון CLIs שאתה רוצה ולחץ על `Apply changes` כדי להתקין/להסיר את ההבדל בשלב אחד. CLIs שהבינארי שלהם מתגלה ב-PATH מסומנים מראש. - - החליפו מדיניויות בודדות או כיבוי עם לחיצה יחידה (כתיבה ל-`~/.failproofai/policies-config.json` — משותף על פני כל CLI שהותקן) - - הרחבו מדיניות כדי להגדיר את הפרמטרים שלה (עבור מדיניויות התומכות ב-`policyParams`) - - הגדר נתיב קובץ מדיניויות מותאם + - בחר מספר כלים את סוכני ה-CLI שעליהם failproofai מגן מלוח יחיד — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Gemini CLI, ו-Hermes כולם בעלי שורה עם סטטוס התקנה (`Active` / `Detected` / `Inactive`), נתיב הגדרות הטווח השנייה משתמש, והדגש צבע ממותג. בדוק או בטל את בדיקת ה-CLIs שאתה רוצה לחץ על `Apply changes` כדי להתקין/הסר את ההבדל בשלב אחד. CLIs שהבינארית שלהם מגולה ב-PATH מסומנים מראש. + - כיבוי או הדלקת מדיניות בודדות בלחיצה יחידה (כתיבה ל-`~/.failproofai/policies-config.json` — משותפת לכל CLI מותקן) + - הרחב מדיניות כדי להגדיר את הפרמטרים שלה (עבור מדיניות התומכות `policyParams`) + - קבע נתיב קובץ מדיניות מותאם - - היסטוריה מלאה מחולקת לעמודים של כל אירוע hook שהופעל על פני כל הsessions - - סנן לפי החלטה, סוג אירוע, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Gemini CLI _(beta)_), שם מדיניות, או Session ID - - כל שורה מציגה: חותמת זמן, שם מדיניות, החלטה, תג CLI (כתום = Claude Code, סגול = OpenAI Codex, כחול = GitHub Copilot, זמרד = Cursor Agent, ענבר = OpenCode, ורוד = Pi, שמיים = Gemini CLI), שם כלי, Session ID, והסיבה להחלטות deny/instruct - - לחץ על Session ID כדי לפתוח את התמלול שלו — מציג אוטו-מזהה איזה 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`) וממשיך את תג CLI המתאים בכותרת + - מלא היסטוריית עמודים של כל אירוע קורא שנשדר על כל הפעלות + - סנן לפי החלטה, סוג אירוע, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Gemini CLI _(beta)_ / Hermes), שם מדיניות, או מזהה הפעלה + - כל שורה מציגה: חותמת זמן, שם מדיניות, החלטה, תג CLI (כתום = Claude Code, סגול = OpenAI Codex, כחול = GitHub Copilot, אזמרגד = Cursor Agent, ענבר = OpenCode, ורוד = Pi, שמיים = Gemini CLI, אינדיגו = Hermes), שם כלים, מזהה הפעלה, והסיבה להחלטות 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`, Hermes `~/.hermes/state.db`) ומעניק את תג ה-CLI התואם בכותרת @@ -96,13 +93,13 @@ failproofai ## Auto-refresh -לוח הבקרה יש תיאום toggle auto-refresh בניווט העליון. כאשר הוא מופעל, הדף הנוכחי מתרענן בתדירות כדי להציג sessionsים חדשים ופעילות מדיניות כאשר הם מופיעים. חיוני לניטור של sessionsים סוכנים אוטונומיים ארוכי משך. +לוח הבקרה יש ממתג ריענון אוטומטי בניווט הדף העליון. כאשר הוא מופעל, העמוד הנוכחי מתרענן מעת לעת כדי להציג הפעלות חדשות ופעילות מדיניות כשהם מופיעים. חיוני לניטור הפעלות סוכן אוטונומי ארוכות. --- -## השבתת דפים +## השבתת עמודים -אם אתה צריך רק חלקים מסוימים של לוח הבקרה, הגדר `FAILPROOFAI_DISABLE_PAGES` לרשימה מופרדת בפסיק של שמות דפים: +אם אתה זקוק רק לחלקים מסוימים של לוח הבקרה, קבע `FAILPROOFAI_DISABLE_PAGES` לרשימה מפורדת בפסיקים של שמות עמוד: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -114,7 +111,7 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## הגדרת נתיב הפרויקטים -כברירת מחדל, לוח הבקרה קורא מתיקיית הפרויקטים הסטנדרטית Claude Code. עקוף אותו עבור הגדרות מותאמות: +כברירת מחדל, לוח הבקרה קורא מספריית הפרויקטים הסטנדרטית של Claude Code. עקוף אותה לעיצובים מותאמים: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -122,32 +119,32 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## הגישה מhoست non-localhost +## גישה מהוסט שאינו localhost -כאשר בפעלון לוח הבקרה בעבודה **dev mode** (`npm run dev`) וגישה אליו משם hostname שאינו `localhost` - לדוגמה, תחום מותאם, IP מרחוק, או URL tunneled - אתה עשוי לראות אזהרה כמו: +בעת הפעלת לוח הבקרה ב**מצב פיתוח** (`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 חוסם גישה cross-origin לחוט HMR (hot module reload) שלו, שזה תכונה dev-only. כדי לתת אפשרות לhoust שלך, השתמש בדגל `--allowed-origins`: +זה Next.js החוסם גישה בין-מקור לרשת HMR (hot module reload) שלו, שהיא תכונת פיתוח בלבד. כדי להתיר את הוסט שלך, השתמש בדגל `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -עבור מספר hostsים או IPs, העבור רשימה מופרדת בפסיק: +עבור מספר הוסטים או כתובות 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 mode. כאשר רצים `failproofai` (production mode), אין HMR websocket ואין בעיה cross-origin dev resource. +זה חל רק על מצב פיתוח. בעת הפעלת `failproofai` (מצב ייצור), אין רשת HMR ואין בעיית משאבי פיתוח בין-מקור. \ No newline at end of file diff --git a/docs/he/examples.mdx b/docs/he/examples.mdx index 7a4c243a..d1e93498 100644 --- a/docs/he/examples.mdx +++ b/docs/he/examples.mdx @@ -1,17 +1,16 @@ --- ---- title: דוגמאות description: "כיצד להגדיר hooks עבור Claude Code ו-Agents SDK" icon: book-open --- -דוגמאות מוכנות לשימוש עבור תרחישים נפוצים. כל אחת מהן מציגה כיצד להתקין ומה לצפות לו. +דוגמאות מוכנות לשימוש עבור תרחישים נפוצים. כל אחת מהן מציגה כיצד להתקין ומה לצפות. --- ## הגדרת hooks עבור Claude Code -Failproof AI משתלבת עם Claude Code דרך [מערכת ה-hooks שלו](https://docs.anthropic.com/en/docs/claude-code/hooks). כאשר אתה מריץ `failproofai policies --install`, היא רושמת פקודות hook ב-`settings.json` של Claude Code שמופעלות בכל קריאת כלי. +Failproof AI משתלב עם Claude Code דרך [מערכת ה-hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) שלו. כאשר אתה מריץ `failproofai policies --install`, זה רושם פקודות hook ב-`settings.json` של Claude Code שמופעלות בכל קריאת tool. @@ -19,24 +18,24 @@ Failproof AI משתלבת עם Claude Code דרך [מערכת ה-hooks שלו](h npm install -g failproofai ``` - + ```bash failproofai policies --install ``` - + ```bash cat ~/.claude/settings.json | grep failproofai ``` - אתה אמור לראות ערכי hook עבור אירועים `PreToolUse`, `PostToolUse`, `Notification` ו-`Stop`. + אתה אמור לראות רשומות hook עבור אירועים `PreToolUse`, `PostToolUse`, `Notification`, ו-`Stop`. ```bash claude ``` - המדיניויות פועלות כעת באופן אוטומטי בכל קריאת כלי. נסה לבקש מ-Claude להריץ `sudo rm -rf /` - זה יחסום. + Policies מתבצעים כעת באופן אוטומטי בכל קריאת tool. נסה לבקש מ-Claude להריץ `sudo rm -rf /` - זה ייחסם. @@ -44,7 +43,7 @@ Failproof AI משתלבת עם Claude Code דרך [מערכת ה-hooks שלו](h ## הגדרת hooks עבור Agents SDK -אם אתה בונה עם [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), אתה יכול להשתמש באותה מערכת hook בצורה תכנותית. +אם אתה בונה עם [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), אתה יכול להשתמש באותה מערכת hook באופן תכנותי. @@ -53,14 +52,14 @@ Failproof AI משתלבת עם Claude Code דרך [מערכת ה-hooks שלו](h ``` - העבר פקודות hook כאשר אתה יוצר את תהליך הסוכן. ה-hooks מופעלים באותו אופן כמו ב-Claude Code - דרך stdin/stdout JSON: + העבר פקודות hook בעת יצירת תהליך ה-agent שלך. ה-hooks מתבצעים באותו אופן כמו ב-Claude Code - דרך stdin/stdout JSON: ```bash - failproofai --hook PreToolUse # called before each tool - failproofai --hook PostToolUse # called after each tool + failproofai --hook PreToolUse # נקרא לפני כל tool + failproofai --hook PostToolUse # נקרא אחרי כל tool ``` - + ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -78,7 +77,7 @@ Failproof AI משתלבת עם Claude Code דרך [מערכת ה-hooks שלו](h }); ``` - + ```bash failproofai policies --install --custom ./my-agent-policies.js ``` @@ -87,37 +86,37 @@ Failproof AI משתלבת עם Claude Code דרך [מערכת ה-hooks שלו](h --- -## חסום פקודות הורסות +## חסום פקודות הרסניות -ההגדרה הנפוצה ביותר - מנע מסוכנים לגרום נזק בלתי הפיך. +ההגדרה הנפוצה ביותר - מנע מ-agents לגרום נזק בלא הפיך. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` מה זה עושה: -- `block-sudo` - חוסם את כל פקודות ה-`sudo` +- `block-sudo` - חוסם את כל פקודות `sudo` - `block-rm-rf` - חוסם מחיקת קבצים רקורסיבית - `block-force-push` - חוסם `git push --force` -- `block-curl-pipe-sh` - חוסם העברת סקריפטים מרחוקים אל shell +- `block-curl-pipe-sh` - חוסם הנחת סקריפטים מרוחוקים אל shell --- ## מנע דליפת סודות -עצור סוכנים מלראות או להדליף אישורים בפלט הכלי. +עצור agents מלראות או דליפה של אישורים בפלט tool. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -אלה מופעלים על `PostToolUse` - לאחר שכלי רץ, הם מנקים את הפלט לפני שהסוכן רואה אותו. +אלה מתבצעים על `PostToolUse` - אחרי שתוכנית מתבצעת, הם מנקים את הפלט לפני שה-agent רואה זאת. --- -## קבל התראות Slack כשסוכנים זקוקים לתשומת לב +## קבל התראות Slack כאשר agents צריכים תשומת לב -השתמש ב-notification hook להעברת התראות צפי ל-Slack. +השתמש בה-notification hook כדי להעביר התראות מהמתנה ל-Slack. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -159,9 +158,9 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c --- -## שמור סוכנים על ענף +## שמור על agents בענף -מנע מסוכנים להחליף ענפים או לדחוף לענפים מוגנים. +מנע מ-agents לשנות ענפים או לדחוף לענפים מוגנים. ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -185,7 +184,7 @@ customPolicies.add({ ## דרוש בדיקות לפני commits -תזכור לסוכנים להריץ בדיקות לפני ביצוע commit. +הזכר ל-agents להריץ בדיקות לפני ביצוע commit. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -207,11 +206,11 @@ customPolicies.add({ --- -## נעל מחסן production +## נעל מאגר production -בצע commit של קובץ הגדרות ברמת הפרויקט כדי שכל מפתח בצוות שלך יקבל אותן מדיניויות. +בצע commit של קונפיגורציה ברמת פרויקט כדי שכל מפתח בצוות שלך יקבל את אותם policies. -צור `.failproofai/policies-config.json` בריפו שלך: +צור `.failproofai/policies-config.json` ב-repo שלך: ```json { @@ -232,23 +231,23 @@ customPolicies.add({ } ``` -ואז בצע commit: +אחר כך בצע commit: ```bash git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -כל חבר בצוות שיש לו failproofai מותקן יקטום את הכללים האלה באופן אוטומטי. +כל חברי הצוות שיש להם failproofai מותקן ילקטו את הכללים הללו באופן אוטומטי. --- -## בנה תקן איכות בקנה מידה של ארגון עם מדיניות convention +## בנה תקן איכות ברמת הארגון עם convention policies -ההגדרה בעלת ההשפעה הגדולה ביותר: בצע commit של `.failproofai/policies/` לריפו שלך עם מדיניויות המותאמות לפרויקט שלך. כל חבר בצוות מקבל אותן באופן אוטומטי - ללא פקודות התקנה, ללא שינויי הגדרה. +ההגדרה בעלת ההשפעה הרבה ביותר: בצע commit של `.failproofai/policies/` ל-repo שלך עם policies המותאמים לפרויקט שלך. כל חברי הצוות מקבלים אותם באופן אוטומטי — ללא פקודות התקנה, ללא שינויי הגדרות. - + ```bash mkdir -p .failproofai/policies ``` @@ -291,18 +290,18 @@ git commit -m "Add failproofai team policies" ``` - כאשר הצוות שלך נתקל בהצורות כשל חדשות, הוסף מדיניויות והדחף. כולם מקבלים את העדכון ב-`git pull` הבא שלהם. המדיניויות הללו הופכות לתקן איכות חי שגדל עם הצוות שלך. + כאשר הצוות שלך נתקל באופני כשל חדשים, הוסף policies ודחוף. כולם מקבלים את העדכון ב-`git pull` הבא שלהם. Policies אלה הופכים לתקן איכות חי שגדל עם הצוות שלך. --- -## דוגמאות נוספות +## עוד דוגמאות -תיקייה [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) בריפו מכילה: +התיקייה [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) ב-repo מכילה: -| קובץ | מה הוא מציג | +| קובץ | מה זה מציג | |------|---------------| -| `policies-basic.js` | מדיניויות התחלות - חסום כתיבה production, force-push, סקריפטים מובילים | -| `policies-notification.js` | התראות Slack עבור הודעות צפי וסיום הפעלה | -| `policies-advanced/index.js` | יבואות טרנזיטיביות, hook אסינכרוני, ניקוי פלט PostToolUse, טיפול באירוע Stop | \ No newline at end of file +| `policies-basic.js` | Starter policies - חסום כתיבה לייצור, force-push, סקריפטים מנובעים | +| `policies-notification.js` | התראות Slack להודעות מהמתנה וסיום הסשן | +| `policies-advanced/index.js` | יבוא טרנזיטיבי, async hooks, PostToolUse output scrubbing, טיפול באירוע Stop | \ No newline at end of file diff --git a/docs/he/for-agents.mdx b/docs/he/for-agents.mdx index ecdbfd8e..20dbb4c8 100644 --- a/docs/he/for-agents.mdx +++ b/docs/he/for-agents.mdx @@ -1,38 +1,38 @@ --- -title: "עבור סוכנים" -description: "הוסף ידע של Failproof AI לסוכן הקידוד שלך בפקודה אחת. עובד עם Claude Code, Cursor, Windsurf וועוד." +title: "עבור אג'נטים" +description: "הוסף ידע של Failproof AI לאג'נט הקוד שלך בפקודה אחת. עובד עם Claude Code, Cursor, Windsurf ועוד." --- -הוסף את ההתייחסות המלאה של Failproof AI לסוכן הקידוד שלך בפקודה אחת. עובד עם Claude Code, Cursor, Windsurf וכל סוכן אחר התומך בכישורים. +הוסף את ההתייחסות המלאה של Failproof AI לאג'נט הקוד שלך בפקודה אחת. עובד עם Claude Code, Cursor, Windsurf וכל אג'נט אחר התומך בכישרונות (skills). ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` מגלה אילו סוכנים יש לך מותקנים ומוסיף את הכישור בפורמט הנכון לכל אחד מהם באופן אוטומטי. +`npx skills` מזהה אילו אג'נטים יש לך מותקנים ומוסיף את הכישרון בפורמט הנכון לכל אחד מהם באופן אוטומטי. -## מה הכישור כולל +## מה הכישרון מכסה | תחום | מה כלול | -|------|---------| -| Policies | שמות policy מובנים, סוגי אירועים, פרמטרים, הפעלה/כיבוי | -| Custom policies | `customPolicies.add()`, מסננים התאמה, API של `allow`/`deny`/`instruct` | +|------|----------------| +| Policies | שמות policy מובנים, סוגי אירועים, פרמטרים, הפעלה/השבתה | +| Custom policies | `customPolicies.add()`, match filters, `allow`/`deny`/`instruct` API | | Context object | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | -| Configuration | מבנה `policies-config.json`, מיזוג scopes, `policyParams` | +| Configuration | `policies-config.json` structure, scope merging, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scopes | -| Dashboard | מציג סשן, פעילות policy, משתנים סביבה | -| Architecture | זרימת Hook handler, קודי יציאה, חוזה stdin/stdout | +| Dashboard | Session viewer, policy activity, environment variables | +| Architecture | Hook handler flow, exit codes, stdin/stdout contract | -## האם הכישור שלם? +## האם הכישרון שלם? -Mintlify מייצר `llms.txt` מכל העמודים בניווט. התיעוד של Failproof AI מכסה את ה-API המלא - כל policy, אפשרות וכל דוגמה כלולים. אם אתה מוצא משהו חסר, המקור נמצא ב-`https://docs.befailproof.ai/llms-full.txt`. +Mintlify יוצר `llms.txt` מכל העמודים בניווט. הדוקומנטציה של Failproof AI מכסה את כל ה-API - כל policy, אפשרות וכל דוגמה כלולים. אם אתה מוצא משהו חסר, המקור נמצא ב-`https://docs.befailproof.ai/llms-full.txt`. -להקשר ממוקד, קשר ישירות לעמוד ספציפי: +לצורך הקשר ממוקד, קישור ישירות לעמוד ספציפי: ```bash -# רק Custom policies API +# רק custom policies API npx skills add https://docs.befailproof.ai/custom-policies -# רק ה-built-in policies +# רק built-in policies npx skills add https://docs.befailproof.ai/built-in-policies ``` \ No newline at end of file diff --git a/docs/he/getting-started.mdx b/docs/he/getting-started.mdx index bae3f07c..90d45c29 100644 --- a/docs/he/getting-started.mdx +++ b/docs/he/getting-started.mdx @@ -1,13 +1,13 @@ --- -title: התחלה -description: "התקן את failproofai, הפעל מדיניויות, והתן לאג'נטים שלך לרוץ בצורה אמינה" +title: תחילת עבודה +description: "התקן את failproofai, הפעל מדיניות, והנח לסוכניםשלך לפעול בצורה אמינה" icon: rocket --- ## דרישות - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (אופציונלי - נדרש רק לבנייה מקוד) +- **Bun** >= 1.3.0 (אופציונלי - נדרש רק לבנייה מקוד מקור) --- @@ -30,16 +30,16 @@ bun add -g failproofai ## התחלה מהירה - - מדיניויות הן כללים שרצים לפני ואחרי כל קריאת כלי של אג'נט. הם תופסים פקודות הרסניות, דליפות סודיות, ודפוסי כשל אחרים לפני שהם גורמים נזק. + + מדיניות הן כללים שרצים לפני ואחרי כל קריאה לכלי סוכן. הם תופסים פקודות הורסות, דליפת סודות וטעויות אחרות לפני שהם גורמים לנזק. ```bash failproofai policies --install ``` - פעולה זו כותבת ערכי hook לתוך ממשקי ה-CLI של אג'נט המותקנים (`~/.claude/settings.json` של Claude Code, `~/.codex/hooks.json` של OpenAI Codex, `~/.copilot/hooks/failproofai.json` של GitHub Copilot CLI, `~/.cursor/hooks.json` של Cursor Agent, shim הפלאגין שנוצר של OpenCode ב-`~/.config/opencode/plugins/failproofai.mjs` בתוספת ערך רישום במערך `plugin` של `~/.config/opencode/opencode.json`, `~/.pi/agent/settings.json` של Pi, או `~/.gemini/settings.json` של Gemini CLI). כאשר יותר מאחד קיים תתבקע בחירה; העבר `--cli claude codex copilot cursor opencode pi gemini` (כל תת-קבוצה) כדי לדלג על ההנחיה. + זה כותב ערכי hook ל-CLI של סוכנים מותקנים (Claude Code של `~/.claude/settings.json`, OpenAI Codex של `~/.codex/hooks.json`, GitHub Copilot CLI של `~/.copilot/hooks/failproofai.json`, Cursor Agent של `~/.cursor/hooks.json`, OpenCode של plugin shim שנוצר ב-`~/.config/opencode/plugins/failproofai.mjs` בתוספת ערך רישום במערך `plugin` של `~/.config/opencode/opencode.json`, Pi של `~/.pi/agent/settings.json`, Gemini CLI של `~/.gemini/settings.json`, או Hermes של `~/.hermes/config.yaml`). כאשר יותר מאחד קיים תתבקע לבחור; העבר `--cli claude codex copilot cursor opencode pi gemini hermes` (כל קבוצה משנית) כדי לדלג על ההודעה. - תמיכה GitHub Copilot CLI, Cursor Agent, OpenCode, Pi ו-Gemini CLI היא **beta** — התקן עם `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, או `--cli gemini`. + תמיכה ב-GitHub Copilot CLI, Cursor Agent, OpenCode, Pi ו-Gemini CLI היא **בטא** — התקן עם `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, או `--cli gemini`. Hermes (hermes-agent, שער Slack/Telegram) מותקן בטווח משתמש עם `--cli hermes` והוא **גם** מקור ביקורת לא מקוון. ```bash failproofai policies --install --scope project @@ -49,70 +49,71 @@ bun add -g failproofai failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project + failproofai policies --install --cli hermes --scope user failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` - + ```bash failproofai policies ``` - מציג כל מדיניות, האם היא מופעלת, וכל פרמטר מוגדר. + מציג כל מדיניות, האם היא מופעלת וכל פרמטרים שהוגדרו. - + ```bash failproofai ``` - פותח לוח מחוונים מקומי ב-`http://localhost:8020` שבו אתה יכול לעיין בהפעלות, לבדוק קריאות כלי, ולנהל מדיניויות. + פותח לוח בקרה מקומי ב-`http://localhost:8020` שבו אתה יכול לדפדף בהפעלות, לבדוק קריאות כלים ולנהל מדיניות. - - הפעל את Claude Code כרגיל. אם האג'נט מנסה משהו סוכן, failproofai יחתוך אותו באופן אוטומטי. השאר אותו רץ ללא השגחה וסקור מה קרה בלוח המחוונים. + + הפעל את Claude Code כרגיל. אם הסוכן מנסה משהו מסוכן, failproofai יחתוך אותו באופן אוטומטי. השאר את זה רץ ללא השגחה וסקור מה קרה בלוח הבקרה. --- -## כיצד מדיניויות פועלות +## איך מדיניות עובדת -בכל פעם שאג'נט מפעיל כלי, Claude Code קורא ל-failproofai כתהליך משנה: +בכל פעם שסוכן מפעיל כלי, Claude Code קורא ל-failproofai כתהליך משנה: ```text Claude Code → failproofai --hook PreToolUse → קורא JSON מ-stdin - מעריך מדיניויות - כותב החלטה ל-stdout + מעריך מדיניות + כותב החלטה ל-stdout ``` כל מדיניות מחזירה אחת משלוש החלטות: -- **allow** - האג'נט ממשיך כרגיל -- **deny** - הפעולה חסומה, לאג'נט מסביר למה -- **instruct** - הקשר נוסף מתווסף להנחיה של האג'נט +- **allow** - הסוכן ממשיך כרגיל +- **deny** - הפעולה נחסמת, לסוכן מובא הסבר +- **instruct** - הקשר נוסף נוסף להנמקת הסוכן -מדיניויות רצות בתהליך המקומי שלך. שום דבר לא נשלח לשירות מרחוק. +מדיניות רצה בתהליך המקומי שלך. שום דבר לא נשלח לשירות מרחוק. --- -## הגדר מדיניויות צוות עם מדיניויות מבוססות כנס +## הגדר מדיניות של צוות עם מדיניות מבוססות קונבנציה -הדרך המהירה ביותר לכניסת סטנדרטים איכות על פני הצוות שלך היא כנס `.failproofai/policies/`. זרוק קובצי מדיניויות לתוך הספרייה הזו והם טעונים באופן אוטומטי — אין דגלים, אין שינויי תצורה, אין פקודות התקנה. +הדרך המהירה ביותר לכונן תקנים איכות על פני הצוות שלך היא קונבנציית `.failproofai/policies/`. זרוק קובצי מדיניות לתיקייה זו והם נטענים באופן אוטומטי - ללא דגלים, ללא שינויי תצורה, ללא פקודות התקנה. - + ```bash mkdir -p .failproofai/policies ``` - - העתק את דוגמאות ההתחלה או כתוב שלך: + + העתק דוגמאות ההתחלה או כתוב את שלך: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ ``` - או צור חדש: + או צור אחד חדש: ```js // .failproofai/policies/team-policies.mjs @@ -124,44 +125,44 @@ Claude Code → failproofai --hook PreToolUse → קורא JSON מ-stdin fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) { - return instruct("הפעל בדיקות לפני התחייבות."); + return instruct("הרץ בדיקות לפני ביצוע commit."); } return allow(); }, }); ``` - + ```bash git add .failproofai/policies/ - git commit -m "הוסף מדיניויות איכות צוות" + git commit -m "הוסף מדיניות איכות של צוות" ``` - כל חברה בצוות שיש לה failproofai מותקנת בוחרת את המדיניויות הללו באופן אוטומטי. אין צורך בהגדרה לכל מפתח. + כל חבר בצוות שיש לו failproofai מותקן יקבל את המדיניות הללו באופן אוטומטי. אין צורך בהגדרה לכל מפתח. -התחייב ל-`.failproofai/policies/` למאגר שלך כדי שכל הצוות ישתף את אותם סטנדרטים. כאשר הצוות שלך מגלה דפוסי כשל חדשים, הוסף מדיניויות ודחוף — כולם מקבלים את העדכון בשלהם הבא `git pull`. עם הזמן מדיניויות אלה הופכות לסטנדרט איכות חי שממשיך להשתפר. +בצע commit ל-`.failproofai/policies/` למאגר שלך כדי שהצוות כולו יחלוק את אותם התקנים. כאשר הצוות שלך מגלה אופני כישלון חדשים, הוסף מדיניות ודחוף - כולם מקבלים את העדכון בעל `git pull` הבא שלהם. לאורך זמן מדיניות אלה הופכות לתקן איכות חי המשתפר כל הזמן. --- ## אחסון נתונים -כל התצורה והיומנים נשארים במכונה שלך: +כל תצורה ו-log נשארים במכונה שלך: -| נתיב | מה הוא מאחסן | +| נתיב | מה זה שומר | |------|----------------| | `~/.failproofai/policies-config.json` | תצורת מדיניות גלובלית | -| `~/.failproofai/hook-activity.jsonl` | היסטוריית ביצוע Hook | -| `~/.failproofai/hook.log` | יומן ניפוי לשגיאות hook מותאמות | -| `.failproofai/policies-config.json` | תצורה לכל פרויקט (מחויבת) | -| `.failproofai/policies-config.local.json` | התעלמות אישית (gitignored) | +| `~/.failproofai/hook-activity.jsonl` | היסטוריית הפעלת hook | +| `~/.failproofai/hook.log` | יומן ניפוי באגים לשגיאות hook מותאם אישית | +| `.failproofai/policies-config.json` | תצורה לפי פרויקט (מובא) | +| `.failproofai/policies-config.local.json` | עדכונים אישיים (gitignored) | --- -## הסרה +## הסרת התקנה ```bash failproofai policies --uninstall @@ -171,24 +172,24 @@ failproofai policies --uninstall --- -## שלבים הבאים +## צעדים הבאים - הערכות וקובץ תצורה בפורמט + טווחים וקובץ תצורה בפורמט - - כל 26 המדיניויות עם פרמטרים + + כל 26 מדיניות עם פרמטרים - - כתוב מדיניויות שלך ב-JavaScript + + כתוב את המדיניות שלך ב-JavaScript - - עקוב אחר הפעלות וסקור פעילות מדיניויות + + עקוב אחר הפעלות וסקור פעילות מדיניות \ No newline at end of file diff --git a/docs/he/introduction.mdx b/docs/he/introduction.mdx index 0bffcdf1..90dc6a3d 100644 --- a/docs/he/introduction.mdx +++ b/docs/he/introduction.mdx @@ -1,36 +1,36 @@ --- title: "Failproof AI" -description: "FailproofAI מספקת לסוכני AI 39 מדיניות כישלון מובנות שתופסות לולאות, דיווח של סודות, קריאות כלים הרסניות ועוד בהתקנה יחידה." +description: "FailproofAI מספקת לסוכני AI 39 מדיניויות כשל מובנות שתופסות לולאות, דליפות סודות, קריאות כלים הרסניות ועוד בהתקנה יחידה." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -ווי וחוקים להתמודדות עם **כישלונות AI**, **התאוששות מ־שגיאות**, ו**אמינות LLM**. שמרו על סוכני ה־AI שלכם אמינים וצעדו בצורה עצמאית על־פני **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, ו**Agents SDK**. +hooks ומדיניויות ל**טיפול בכשלי AI**, **התאוששות משגיאות**, ו**אמינות LLM**. שמור על סוכני ה-AI שלך אמינים ופועלים באופן אוטונומי על פני **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, **Hermes**, וה-**Agents SDK**. -סוכני AI נכשלים בדרכים צפויות. הם מריצים פקודות הרסניות, דוללים סודות, חוטפים מהמטרה, נתקעים בלולאות, או דוחפים ישירות לענף הראשי. אם מחזיקים אותם ללא השגחה, כישלונות קטנים מתגברים לתקלות, דיווח של אישורים, והפסד עבודה. +סוכני AI נכשלים בדרכים צפויות. הם מפעילים פקודות הרסניות, מדליפים סודות, חורגים מהמטלה, תקועים בלולאות, או דוחפים ישירות לענף הראשי. אם משאירים ללא פקוח עין, כשלים קטנים מתגברים להפסקות, דליפות אישורים, והפסד עבודה. -FailproofAI פותרת זאת עם **מדיניויות**. כללים אלו חוברים לכל קריאת כלי סוכן כדי **לזהות כישלונות**, **למתן אותם** (חסימה, הוראה, טיהור), ו**להזהיר אתכם** כשמשהו צריך תשומת לב. לוח בקרה מקומי מאפשר לכם לסקור כל קריאת כלי, כישלון סוכן, ופעולת התאוששות לאחר מכן. +FailproofAI פותרת זאת עם **מדיניויות**. כללים אלה מתחברים לכל קריאת כלי סוכן כדי **לגלות כשלים**, **להפחית אותם** (חסום, הנחה, טיהור), ו**התריע עליך** כשמשהו דורש תשומת לב. לוח מחוונים מקומי מאפשר לך לסקור כל קריאת כלי, כשל סוכן, ופעולת התאוששות לאחר מכן. -אף נתון לא משאיר את המחשב שלך. +אין נתונים משאירים את המכונה שלך. ## התחל - חסמו פקודות הרסניות, מנעו דיווח של סודות, שמרו סוכנים בתוך גבולות פרויקט, ועוד. הכל מחוץ לקופסה. + חסום פקודות הרסניות, מנע דליפות סודות, שמור סוכנים בתוך גבולות הפרויקט, ועוד. הכל מחוץ לקופסה. - כתבו כללים משלכם ב־JavaScript עם API פשוט allow / deny / instruct. + כתוב כללים שלך בـ JavaScript עם API פשוט של allow / deny / instruct. - - ראו מה עשו הסוכנים שלכם בזמן שהייתם הרחק. עיינו בהפעלות, בדקו קריאות כלים, בדוקו היכן מדיניויות הפעילו. + + ראה מה עשו הסוכנים שלך בזמן שהיית רחוק. עיין בהפעלות, בדוק קריאות כלים, סקור איפה נשרפו המדיניויות. - התאימו כל מדיניות ללא קוד. הגדרו רשימות אישור, ענפים מוגנים, או סף לפי־פרויקט או בגלובל. + כוונן כל מדיניות ללא קוד. הגדר רשימות אישור, ענפים מוגנים, או סף לפרויקט או בעולם. @@ -54,4 +54,4 @@ failproofai policies --install # enable policies (or skip — `failproofai` wi failproofai # launch the dashboard ``` -ראו את מדריך [התחלת עבודה](/he/getting-started) לסיור מלא. \ No newline at end of file +ראה את מדריך [התחלה](/he/getting-started) להסבר מלא. \ No newline at end of file diff --git a/docs/he/package-aliases.mdx b/docs/he/package-aliases.mdx index cf78a65b..1a9d89dd 100644 --- a/docs/he/package-aliases.mdx +++ b/docs/he/package-aliases.mdx @@ -1,12 +1,12 @@ --- title: כינויי חבילה -description: "כינויים רשומים למניעת typosquat וכיצד הם עובדים" +description: "כינויים שנרשמו למניעת typosquat וכיצד הם עובדים" icon: copy --- -## חבילה רשמית +## החבילה הרשמית -חבילת npm הקנונית היא **`failproofai`**: +החבילה npm הקנונית היא **`failproofai`**: ```bash npm install -g failproofai @@ -16,52 +16,52 @@ bun add -g failproofai --- -## למה אנו בעלים של שמות הכינויים +## מדוע אנחנו בעלים של שמות הכינויים -Typosquatting היא התקפת שרשרת אספקה נפוצה שבה שחקן זדוני רושם שם חבילה שהוא מכה אחת משם חבילה פופולרית. משתמשים שלא חזו על הדבר שטיפלו בהוראת ההתקנה בטעות מוצאים עצמם מריצים קוד שנשלט על ידי התוקף עם גישה מלאה למערכת - בדיוק סוג ההאיום שFailproof AI מעוצב כדי להגן נגדו. +Typosquatting הוא התקפת שרשרת אספקה נפוצה בה שחקן זדוני רושם שם חבילה שנמצא בדקה אחת מחבילה פופולרית. משתמשים חסרי זהירות שטועים בפקודת ההתקנה בסופו של דבר מריצים קוד מכוונן של תוקף עם גישה מלאה למערכת - בדיוק מהסוג של איום שFailproof AI מעוצב כדי להגן עליו. -כדי לחסל משטח זה, **אנו קודם לכן בעלים על כל הטעויות כתיב נפוצות וגרסאות עיצוב** של `failproofai` ב-npm. אף אחד מהשמות הללו לא יכול להיות רשום על ידי צד שלישי. כל אחד מהם הוא פרוקסי דק שמתקין ומעביר לחבילת `failproofai` האמיתית. +כדי לחסל משטח זה, **אנחנו בבעלותנו כל הטעויות הנפוצות וגרסאות עיצוב של `failproofai` ב-npm**. אף אחד משמות אלה לא יכול להיות רשום על ידי צד שלישי. כל אחד מהם הוא פרוקסי דק המתקין ומעביר סמכויות לחבילה `failproofai` האמיתית. --- ## כינויים רשומים -**גרסאות עיצוב** - דרכים שונות לכתיבת "failproof ai": +**גרסאות עיצוב** - דרכים שונות לכתוב "failproof ai": | חבילה | סטטוס | |---------|--------| | `failproof` | ✅ פורסם | -| `failproof-ai` | ⏳ בהמתנה לתמיכת npm | -| `fail-proof-ai` | ⏳ בהמתנה לתמיכת npm | -| `failproof_ai` | ⏳ בהמתנה לתמיכת npm | -| `fail_proof_ai` | ⏳ בהמתנה לתמיכת npm | -| `fail-proofai` | ⏳ בהמתנה לתמיכת npm | +| `failproof-ai` | ⏳ ממתין לתמיכת npm | +| `fail-proof-ai` | ⏳ ממתין לתמיכת npm | +| `failproof_ai` | ⏳ ממתין לתמיכת npm | +| `fail_proof_ai` | ⏳ ממתין לתמיכת npm | +| `fail-proofai` | ⏳ ממתין לתמיכת npm | -**`failprof*` typos** - חסר אחד `o` מ-"proof": +**טעויות `failprof*`** - חסר `o` אחד מ-"proof": | חבילה | סטטוס | |---------|--------| | `failprof` | ✅ פורסם | | `failprof-ai` | ✅ פורסם | -| `failprofai` | ⏳ בהמתנה לתמיכת npm | -| `fail-prof-ai` | ⏳ בהמתנה לתמיכת npm | -| `failprof_ai` | ⏳ בהמתנה לתמיכת npm | +| `failprofai` | ⏳ ממתין לתמיכת npm | +| `fail-prof-ai` | ⏳ ממתין לתמיכת npm | +| `failprof_ai` | ⏳ ממתין לתמיכת npm | -**`faliproof*` typos** - `a` ו-`i` מחליפים מקום: +**טעויות `faliproof*`** - `a` ו-`i` מתחלפים: | חבילה | סטטוס | |---------|--------| | `faliproof` | ✅ פורסם | | `faliproof-ai` | ✅ פורסם | -| `faliproofai` | ⏳ בהמתנה לתמיכת npm | +| `faliproofai` | ⏳ ממתין לתמיכת npm | -> **למה בהמתנה?** מדיניות מניעת הספאם של npm חוסמת שמות המנורמלים לאותו מחרוזת כחבילה קיימת לאחר הסרת סימני פיסוק בדיקות דמיון. פנינו לתמיכת npm לשמור על שמות אלה למטרות נגד typosquatting. הם יופעלו לאחר אישור. +> **מדוע בהמתנה?** מדיניות מניעת הספאם של npm חוסמת שמות המתממשלים לאותו מחרוזת כחבילה קיימת לאחר הסרת סימני פיקטוגרפיה וביצוע בדיקות דמיון. יצרנו קשר עם תמיכת npm כדי להחזיק שמות אלה למטרות אנטי-סקוואטינג. הם יופעלו ברגע שיאושרו. -אתה יכול לאמת שכל כינוי פורסם הוא בעלותנו: +אתה יכול לאמת שכל כינוי פורסם הוא בבעלותנו: ```bash npm info failproof -# חפש: "ExosphereHost Inc." בשדה maintainers +# חפש: "ExosphereHost Inc." בשדה המתחזקים ``` --- @@ -70,13 +70,13 @@ npm info failproof כל חבילת כינוי: -1. מציינת `failproofai` כתלות - ולכן החבילה האמיתית (כולל התקנת ה-hook `postinstall` שלה) רצה בהתקנה -2. חושפת בינארי התואם לשמה שלה (למשל `failproof-ai`) שמעביר כל ארגומנטים לבינארי `failproofai` +1. מפרטת `failproofai` כתלות - כך החבילה האמיתית (כולל הגדרת ה-`postinstall` hook שלה) פועלת בהתקנה +2. חושפת בינארי התואם לשם שלה (למשל `failprof-ai`) המשפעל את כל הארגומנטים לבינארי `failproofai` -הפרוקסי הוא סקריפט Node בן שני שורות; אין לוגיקה, אין קריאות רשת, ואין אוסף נתונים מעבר למה שעצם `failproofai` עושה. +הפרוקסי הוא סקריפט Node בן שתי שורות; אין לוגיקה, אין קריאות רשת, ואין אוסף נתונים מעבר לכל מה ש-`failproofai` עצמו עושה. --- -## אם מצאת שם שהחמצנו +## אם מצאת שם שפספסנו פתח issue ב-[failproofai/failproofai](https://github.com/failproofai/failproofai/issues) ואנחנו נרשום אותו. \ No newline at end of file diff --git a/docs/he/testing.mdx b/docs/he/testing.mdx index 3a588f9a..6a84da0c 100644 --- a/docs/he/testing.mdx +++ b/docs/he/testing.mdx @@ -1,29 +1,29 @@ --- title: בדיקות -description: "בדיקות יחידה, בדיקות end-to-end וכלי עזר לבדיקות" +description: "בדיקות יחידה, בדיקות E2E ועוזרי בדיקה" icon: flask-vial --- -failproofai מכיל שתי חוקי בדיקות: **בדיקות יחידה** (מהירות, עם mocks) ו**בדיקות end-to-end** (הפעלת תהליכי משנה אמיתיים). +failproofai כולל שתי חבילות בדיקה: **בדיקות יחידה** (מהירות, מתואמות) ו**בדיקות מקצה לקצה** (הפעלות תהליך אמיתיות). --- ## הפעלת בדיקות ```bash -# הפעלת כל בדיקות היחידה פעם אחת +# הפעל את כל בדיקות היחידה פעם אחת bun run test:run -# הפעלת בדיקות יחידה במצב watch +# הפעל בדיקות יחידה במצב צפייה bun run test -# הפעלת בדיקות E2E (דורש התקנה - ראה למטה) +# הפעל בדיקות E2E (דורש הגדרה - ראה להלן) bun run test:e2e -# בדיקת סוגים ללא בנייה +# בדוק סוגים ללא בנייה bunx tsc --noEmit -# Lint +# בדוק סטיל bun run lint ``` @@ -31,17 +31,17 @@ bun run lint ## בדיקות יחידה -בדיקות היחידה נמצאות ב-`__tests__/` ומשתמשות ב-[Vitest](https://vitest.dev) עם `jsdom`. +בדיקות יחידה נמצאות ב-`__tests__/` וממשות את [Vitest](https://vitest.dev) עם `jsdom`. ```text __tests__/ hooks/ - builtin-policies.test.ts # לוגיקת מדיניות לכל builtin - hooks-config.test.ts # טעינת קונפיגורציה ומיזוג טווח + builtin-policies.test.ts # לוגיקת מדיניות לכל מדיניות מובנית + hooks-config.test.ts # טעינת תצורה ומיזוג טווח policy-evaluator.test.ts # הזרקת פרמטרים וסדר הערכה - custom-hooks-registry.test.ts # globalThis registry add/get/clear - custom-hooks-loader.test.ts # ESM loader, ייבוא טרנזיטיבי, ניהול שגיאות - manager.test.ts # פעולות install/remove/list + custom-hooks-registry.test.ts # הוספה/קבלה/ניקוי רישום globalThis + custom-hooks-loader.test.ts # טוען ESM, ייבוא מעבר, טיפול בשגיאות + manager.test.ts # פעולות התקנה/הסרה/רשימה components/ sessions-list.test.tsx # רכיב רשימת הפעלות project-list.test.tsx # רכיב רשימת פרויקטים @@ -61,7 +61,7 @@ __tests__/ AutoRefreshContext.test.tsx ``` -### כתיבת בדיקת יחידה של מדיניות +### כתיבת בדיקת יחידה למדיניות ```typescript import { describe, it, expect, beforeEach } from "vitest"; @@ -108,42 +108,42 @@ describe("block-sudo", () => { --- -## בדיקות end-to-end +## בדיקות מקצה לקצה -בדיקות E2E משדרות את הקובץ `failproofai` האמיתי כתהליך משנה, חוצים עומס JSON ל-stdin, ובודקות את פלט stdout וקוד ההחروج. זה בודק את נתיב האינטגרציה המלא שבו Claude Code משתמש. +בדיקות E2E מפעילות את הקובץ `failproofai` האמיתי כתהליך משנה, משדרות מטען JSON ל-stdin, ובוחנות את פלט ה-stdout וקוד היציאה. זה בוחן את נתיב ההשתלבות המלא ש-Claude Code משתמש בו. -### התקנה +### הגדרה -בדיקות E2E משדרות את הקובץ הישירות מקוד המקור של הריפו. לפני ההרצה הראשונה, בנה את ערימת CJS שקובצי hook מותאמים משתמשים בהם בעת ייבוא מ-`'failproofai'`: +בדיקות E2E מפעילות את הקובץ הבינארי ישירות ממקור המאגר. לפני ההפעלה הראשונה, בנה את ערכת ה-CJS שקבצי hook מותאמים משתמשים בהם בעת ייבוא מ-`'failproofai'`: ```bash bun build src/index.ts --outdir dist --target node --format cjs ``` -לאחר מכן, הפעל את הבדיקות: +לאחר מכן הפעל את הבדיקות: ```bash bun run test:e2e ``` -בנה מחדש את `dist/` בכל פעם שאתה משנה את ממשק hook הציבורי (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, או `src/hooks/policy-types.ts`). +בנה מחדש את `dist/` בכל פעם שתשנה את ה-API הציבורי של hook (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, או `src/hooks/policy-types.ts`). ### מבנה בדיקת E2E ```text __tests__/e2e/ helpers/ - hook-runner.ts # שדרות הקובץ, חוצה JSON עומס, קובע קוד יציאה + stdout + stderr - fixture-env.ts # ספריות זמניות מבודדות לכל בדיקה עם קובצי תצורה - payloads.ts # מפעלות עומס מדויקות של Claude לכל סוג אירוע + hook-runner.ts # הפעל את הקובץ הבינארי, שדר JSON מטען, ולכוד קוד יציאה + stdout + stderr + fixture-env.ts # ספריות זמניות מבודדות לכל בדיקה עם קבצי תצורה + payloads.ts # מפעלי מטען בדויקות Claude לכל סוג אירוע hooks/ - builtin-policies.e2e.test.ts # כל מדיניות builtin עם תהליך משנה אמיתי + builtin-policies.e2e.test.ts # כל מדיניות מובנית עם תהליך משנה אמיתי custom-hooks.e2e.test.ts # טעינה והערכה של hook מותאם - config-scopes.e2e.test.ts # מיזוג תצורה על פני פרויקט/מקומי/גלובלי - policy-params.e2e.test.ts # הזרקת פרמטרים לכל מדיניות עם פרמטרים + config-scopes.e2e.test.ts # מיזוג תצורה בין פרויקט/מקומי/גלובלי + policy-params.e2e.test.ts # הזרקת פרמטרים לכל מדיניות שניתנת לפרמטריזציה ``` -### שימוש ב-E2E helpers +### שימוש בעוזרי E2E **`FixtureEnv`** - סביבה מבודדת לכל בדיקה: @@ -151,8 +151,8 @@ __tests__/e2e/ import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - ספריה זמנית; העבר כ-payload.cwd כדי לאסוף את .failproofai/policies-config.json -// env.home - ספריית בית מבודדת; אין דליפה של ~/.failproofai אמיתי +// env.cwd - ספרייה זמנית; העבר כ-payload.cwd כדי לבחור ב-.failproofai/policies-config.json +// env.home - ספרית בית מבודדת; ללא דליפות אמיתיות ~/.failproofai env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -162,9 +162,9 @@ env.writeConfig({ }); ``` -`createFixtureEnv()` רושם `afterEach` ניקיון באופן אוטומטי. +`createFixtureEnv()` רושמת ניקוי `afterEach` באופן אוטומטי. -**`runHook`** - שדרות הקובץ: +**`runHook`** - הפעל את הקובץ הבינארי: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - מפעלות עומס מוכנות: +**`Payloads`** - מפעלי מטען מוכנים: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -237,24 +237,24 @@ describe("block-rm-rf (E2E)", () => { |----------|-----------|--------| | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | -| הוראה (ללא Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop הוראה | `2` | empty stdout; סיבה ב-stderr | -| אישור | `0` | מחרוזת ריקה | +| Instruct (non-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | +| Stop instruct | `2` | stdout ריק; סיבה ב-stderr | +| Allow | `0` | מחרוזת ריקה | ### תצורת Vitest בדיקות E2E משתמשות ב-`vitest.config.e2e.mts` עם: - `environment: "node"` - אין צורך בגלובלים של דפדפן -- `pool: "forks"` - בידוד תהליך אמיתי (בדיקות שדרות תהליכי משנה) -- `testTimeout: 20_000` - 20 שניות לכל בדיקה (הפעלה של קובץ + הערכה של hook) +- `pool: "forks"` - בידוד תהליך אמיתי (בדיקות משדרות תהליכים משניים) +- `testTimeout: 20_000` - 20 שניות לכל בדיקה (הפעלת קובץ בינארי + הערכת hook) -ערימת `forks` חשובה: עובדים מבוססי threads שיתופיים `globalThis`, מה שיכול להפריע לבדיקות שדרות תהליכי משנה. ערימות מבוססות תהליכים מונעות זאת. +ה-`forks` pool חשוב: עובדים מבוססי thread משתפים את `globalThis`, מה שיכול להפריע לבדיקות המשדרות תהליכים משניים. forks מבוססי תהליך מונעים זאת. --- ## CI -הריצה המלאה ב-CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) חייבת לעבור לפני המיזוג. ערימת E2E רצה כעבודת CI נפרדת במקביל. +הריצה המלאה ב-CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) חייבת להעביר לפני מיזוג. הצד E2E פועל כעבודת CI נפרדת במקביל. -ראה [Contributing](../CONTRIBUTING.md) לרשימת הבדיקה המלאה לפני מיזוג. \ No newline at end of file +ראה [תרומה](../CONTRIBUTING.md) לרשימת הבדיקה המלאה לפני מיזוג. \ No newline at end of file diff --git a/docs/hi/architecture.mdx b/docs/hi/architecture.mdx index 7138d02e..8ba48aee 100644 --- a/docs/hi/architecture.mdx +++ b/docs/hi/architecture.mdx @@ -1,12 +1,11 @@ --- - --- title: आर्किटेक्चर -description: "हुक हैंडलर, कॉन्फ़िग लोडिंग, और पॉलिसी मूल्यांकन कैसे काम करते हैं" +description: "हुक हैंडलर, कॉन्फ़िग लोडिंग, और पॉलिसी मूल्यांकन आंतरिक रूप से कैसे काम करते हैं" icon: sitemap --- -यह दस्तावेज़ बताता है कि failproofai आंतरिक रूप से कैसे काम करता है: हुक सिस्टम एजेंट टूल कॉल को कैसे इंटरसेप्ट करता है, कॉन्फ़िग कैसे लोड और मर्ज होता है, पॉलिसीज़ का मूल्यांकन कैसे होता है, और डैशबोर्ड एजेंट गतिविधि की निगरानी कैसे करता है। +यह दस्तावेज़ बताता है कि failproofai आंतरिक रूप से कैसे काम करता है: हुक सिस्टम एजेंट टूल कॉल को कैसे इंटरसेप्ट करता है, कॉन्फ़िग कैसे लोड और मर्ज किया जाता है, पॉलिसीज़ का मूल्यांकन कैसे होता है, और डैशबोर्ड एजेंट गतिविधि को कैसे मॉनिटर करता है। --- @@ -14,10 +13,10 @@ icon: sitemap failproofai के दो स्वतंत्र सबसिस्टम हैं: -1. **हुक हैंडलर** - एक तेज़ CLI सबप्रोसेस जो Claude Code हर एजेंट टूल कॉल पर चलाता है। पॉलिसीज़ का मूल्यांकन करता है और एक निर्णय देता है। -2. **एजेंट मॉनिटर (डैशबोर्ड)** - एजेंट सेशन की निगरानी और पॉलिसीज़ को प्रबंधित करने के लिए एक Next.js वेब एप्लिकेशन। +1. **हुक हैंडलर** - एक तेज़ CLI सबप्रोसेस जिसे Claude Code हर एजेंट टूल कॉल पर आमंत्रित करता है। पॉलिसीज़ का मूल्यांकन करता है और एक निर्णय लौटाता है। +2. **एजेंट मॉनिटर (डैशबोर्ड)** - एजेंट सेशन मॉनिटर करने और पॉलिसीज़ प्रबंधित करने के लिए एक Next.js वेब एप्लीकेशन। -दोनों सबसिस्टम `~/.failproofai/` और प्रोजेक्ट की `.failproofai/` डायरेक्टरी में कॉन्फ़िग फ़ाइलें साझा करते हैं, लेकिन वे अलग-अलग प्रक्रियाओं के रूप में चलते हैं और केवल फ़ाइलसिस्टम के माध्यम से संचार करते हैं। +दोनों सबसिस्टम `~/.failproofai/` और प्रोजेक्ट की `.failproofai/` डायरेक्टरी में कॉन्फ़िग फाइलें साझा करते हैं, लेकिन वे अलग प्रक्रियाओं के रूप में चलते हैं और केवल फाइलसिस्टम के माध्यम से संचार करते हैं। --- @@ -25,7 +24,7 @@ failproofai के दो स्वतंत्र सबसिस्टम ह ### Claude Code के साथ एकीकरण -जब आप `failproofai policies --install` चलाते हैं, तो यह `~/.claude/settings.json` में इस तरह की प्रविष्टियाँ लिखता है: +जब आप `failproofai policies --install` चलाते हैं, तो यह `~/.claude/settings.json` में इस तरह की एंट्रीज़ लिखता है: ```json { @@ -46,7 +45,7 @@ failproofai के दो स्वतंत्र सबसिस्टम ह } ``` -Claude Code फिर हर टूल कॉल से पहले `failproofai --hook PreToolUse` को एक सबप्रोसेस के रूप में चलाता है, stdin पर एक JSON पेलोड भेजता है। +Claude Code फिर प्रत्येक टूल कॉल से पहले एक सबप्रोसेस के रूप में `failproofai --hook PreToolUse` को आमंत्रित करता है, stdin पर एक JSON पेलोड पास करता है। ### पेलोड प्रारूप @@ -62,13 +61,13 @@ Claude Code फिर हर टूल कॉल से पहले `failproofa } ``` -`PostToolUse` इवेंट के लिए, पेलोड में `tool_result` भी होता है जिसमें टूल का आउटपुट होता है। +`PostToolUse` इवेंट्स के लिए, पेलोड में टूल के आउटपुट के साथ `tool_result` भी होता है। -हैंडलर 1 MB stdin लिमिट लागू करता है। इस सीमा से अधिक पेलोड छोड़ दिए जाते हैं और सभी पॉलिसीज़ निहित रूप से अनुमति देती हैं। +हैंडलर 1 MB stdin सीमा लागू करता है। इस सीमा से अधिक पेलोड को त्याग दिया जाता है और सभी पॉलिसीज़ निहित रूप से अनुमति देती हैं। -### रेस्पांस प्रारूप +### प्रतिक्रिया प्रारूप -**Deny (PreToolUse):** +**अस्वीकार (PreToolUse):** ```json { "hookSpecificOutput": { @@ -78,7 +77,7 @@ Claude Code फिर हर टूल कॉल से पहले `failproofa } ``` -**Deny (PostToolUse):** +**अस्वीकार (PostToolUse):** ```json { "hookSpecificOutput": { @@ -87,7 +86,7 @@ Claude Code फिर हर टूल कॉल से पहले `failproofa } ``` -**Instruct (किसी भी ईवेंट को छोड़कर Stop):** +**निर्देश (कोई भी इवेंट स्टॉप को छोड़कर):** ```json { "hookSpecificOutput": { @@ -96,17 +95,17 @@ Claude Code फिर हर टूल कॉल से पहले `failproofa } ``` -**Stop event instruct:** +**स्टॉप इवेंट निर्देश:** - एक्जिट कोड: `2` -- कारण stderr में लिखा गया (stdout में नहीं) +- कारण stderr में लिखा जाता है (stdout में नहीं) -**Allow:** +**अनुमति:** - एक्जिट कोड: `0` - खाली stdout -**संदेश के साथ Allow:** +**संदेश के साथ अनुमति:** -`allow(message)` एक पॉलिसी को Claude को सूचनात्मक संदर्भ वापस भेजने देता है यहाँ तक कि जब ऑपरेशन की अनुमति हो। हुक हैंडलर निम्नलिखित JSON को **stdout** में लिखता है (एक कॉन्फ़िग फ़ाइल में नहीं — यह हैंडलर का Claude Code को रेस्पांस है, जैसे deny और instruct रेस्पांस के ऊपर): +`allow(message)` एक पॉलिसी को ऑपरेशन की अनुमति देते समय भी Claude को सूचनात्मक संदर्भ भेजने देता है। हुक हैंडलर **stdout** में निम्नलिखित JSON लिखता है (कॉन्फ़िग फाइल में नहीं — यह हैंडलर की Claude Code को प्रतिक्रिया है, जैसे अस्वीकार और निर्देश प्रतिक्रिया के समान): ```json // हुक हैंडलर प्रक्रिया द्वारा stdout में लिखा गया @@ -117,78 +116,78 @@ Claude Code फिर हर टूल कॉल से पहले `failproofa } ``` - एक्जिट कोड: `0` (ऑपरेशन की अनुमति है) -- जब कई पॉलिसीज़ संदेश के साथ `allow` देते हैं, तो उनके संदेश नई पंक्तियों के साथ जुड़ जाते हैं एक एकल `additionalContext` स्ट्रिंग में -- अगर कोई पॉलिसी संदेश प्रदान नहीं करती है, तो stdout खाली है (पहले जैसे) +- जब कई पॉलिसीज़ संदेश के साथ `allow` लौटाती हैं, तो उनके संदेश नई पंक्तियों से जुड़े होते हैं एक एकल `additionalContext` स्ट्रिंग में +- यदि कोई पॉलिसी संदेश प्रदान नहीं करती है, तो stdout खाली है (पहले जैसे) ### प्रोसेसिंग पाइपलाइन -`src/hooks/handler.ts` पूरी पाइपलाइन को लागू करता है: +`src/hooks/handler.ts` पूरी पाइपलाइन लागू करता है: ```text stdin JSON - → पेलोड को पार्स करें (अधिकतम 1 MB) - → सेशन मेटाडेटा निकालें (session_id, cwd, tool_name, tool_input, आदि) - → readMergedHooksConfig(cwd) ← प्रोजेक्ट + लोकल + ग्लोबल कॉन्फ़िग को मर्ज करता है - → सक्षम बिल्ट-इन पॉलिसीज़ को हल किए गए पैरामीटर के साथ रजिस्टर करें - → customPoliciesPath से कस्टम पॉलिसीज़ लोड करें (यदि सेट हो) - → कस्टम पॉलिसीज़ को पॉलिसी रजिस्ट्री में रजिस्टर करें - → सभी पॉलिसीज़ का मूल्यांकन करें (पहले बिल्ट-इन्स, फिर कस्टम) - → पहला deny शॉर्ट-सर्किट करता है - → instruct निर्णय जमा होते हैं - → allow संदेश जमा होते हैं - → stdout में JSON निर्णय लिखें - → इवेंट को ~/.failproofai/hook-activity.jsonl में रखें - → एक्जिट करें + → parse payload (max 1 MB) + → extract session metadata (session_id, cwd, tool_name, tool_input, etc.) + → readMergedHooksConfig(cwd) ← merges project + local + global config + → register enabled builtin policies with resolved params + → load custom policies from customPoliciesPath (if set) + → register custom policies into policy registry + → evaluate all policies (builtins first, then custom) + → first deny short-circuits + → instruct decisions accumulate + → allow messages accumulate + → write JSON decision to stdout + → persist event to ~/.failproofai/hook-activity.jsonl + → exit ``` -बिना LLM कॉल के विशिष्ट पेलोड के लिए पूरी प्रक्रिया 100ms में पूरी हो जाती है। +पूरी प्रक्रिया बिना LLM कॉल के विशिष्ट पेलोड्स के लिए 100ms में चलती है। --- ## कॉन्फ़िग लोडिंग -`src/hooks/hooks-config.ts` तीन-स्कोप कॉन्फ़िग लोडिंग को लागू करता है। +`src/hooks/hooks-config.ts` तीन-स्कोप कॉन्फ़िग लोडिंग लागू करता है। ```text -[1] {cwd}/.failproofai/policies-config.json ← प्रोजेक्ट (सर्वोच्च प्राथमिकता) -[2] {cwd}/.failproofai/policies-config.local.json ← लोकल -[3] ~/.failproofai/policies-config.json ← ग्लोबल (सबसे कम प्राथमिकता) +[1] {cwd}/.failproofai/policies-config.json ← project (highest priority) +[2] {cwd}/.failproofai/policies-config.local.json ← local +[3] ~/.failproofai/policies-config.json ← global (lowest priority) ``` मर्ज लॉजिक: -- `enabledPolicies` - सभी तीन फ़ाइलों में डीडुप्लिकेटेड यूनियन -- `policyParams` - प्रति-पॉलिसी कुंजी, पहली फ़ाइल जो इसे परिभाषित करती है पूरी तरह जीतती है -- `customPoliciesPath` - पहली फ़ाइल जो इसे परिभाषित करती है जीतती है -- `llm` - पहली फ़ाइल जो इसे परिभाषित करती है जीतती है +- `enabledPolicies` - तीनों फाइलों में विस्तारित यूनियन +- `policyParams` - प्रति-पॉलिसी की, जो फाइल पहले इसे परिभाषित करती है वह पूरी तरह जीतती है +- `customPoliciesPath` - जो फाइल पहले इसे परिभाषित करती है वह जीतती है +- `llm` - जो फाइल पहले इसे परिभाषित करती है वह जीतती है -वेब डैशबोर्ड पढ़ने और लिखने के लिए `readHooksConfig()` (केवल ग्लोबल) का उपयोग करता है, क्योंकि इसे प्रोजेक्ट cwd के साथ नहीं चलाया जाता है। +वेब डैशबोर्ड पढ़ने और लिखने के लिए `readHooksConfig()` (केवल ग्लोबल) का उपयोग करता है, क्योंकि इसे प्रोजेक्ट cwd के साथ आमंत्रित नहीं किया जाता है। --- ## पॉलिसी मूल्यांकन -`src/hooks/policy-evaluator.ts` क्रम में पॉलिसीज़ चलाता है। +`src/hooks/policy-evaluator.ts` पॉलिसीज़ को क्रम में चलाता है। प्रत्येक पॉलिसी के लिए: -1. पॉलिसी के `params` स्कीमा को देखें (यदि इसके पास है)। -2. मर्ज किए गए कॉन्फ़िग से `policyParams[policy.name]` को पढ़ें। -3. उपयोगकर्ता-प्रदान किए गए मानों को स्कीमा डिफ़ॉल्ट पर मर्ज करें `ctx.params` का उत्पादन करने के लिए। -4. हल किए गए संदर्भ के साथ `policy.fn(ctx)` कॉल करें। -5. यदि परिणाम `deny` है, तो तुरंत रुकें और वह निर्णय दें। +1. पॉलिसी की `params` स्कीमा देखें (यदि इसके पास है)। +2. मर्ज की गई कॉन्फ़िग से `policyParams[policy.name]` पढ़ें। +3. यूजर-प्रदान किए गए मूल्यों को स्कीमा डिफ़ॉल्ट्स के ऊपर मर्ज करें `ctx.params` उत्पन्न करने के लिए। +4. `policy.fn(ctx)` को हल किए गए संदर्भ के साथ कॉल करें। +5. यदि परिणाम `deny` है, तो तुरंत रोकें और वह निर्णय लौटाएं। 6. यदि परिणाम `instruct` है, तो संदेश जमा करें और जारी रखें। 7. यदि परिणाम `allow` है, तो अगली पॉलिसी पर जाएं। सभी पॉलिसीज़ चलने के बाद: -- अगर कोई `deny` दिया गया था, तो deny रेस्पांस उत्सर्जित करें। -- यदि कोई `instruct` रिटर्न एकत्र किए गए हैं, तो सभी संदेशों को जुड़े हुए एकल instruct रेस्पांस उत्सर्जित करें। -- अन्यथा, allow रेस्पांस उत्सर्जित करें (खाली stdout, एक्जिट 0)। +- यदि कोई `deny` लौटाया गया था, तो अस्वीकार प्रतिक्रिया उत्सर्जित करें। +- यदि कोई `instruct` रिटर्न एकत्र किए गए थे, तो सभी संदेशों को जुड़े हुए एकल निर्देश प्रतिक्रिया उत्सर्जित करें। +- अन्यथा, अनुमति प्रतिक्रिया उत्सर्जित करें (खाली stdout, एक्जिट 0)। --- ## बिल्ट-इन पॉलिसीज़ -`src/hooks/builtin-policies.ts` सभी 39 बिल्ट-इन पॉलिसीज़ को `BuiltinPolicyDefinition` ऑब्जेक्ट के रूप में परिभाषित करता है: +`src/hooks/builtin-policies.ts` सभी 39 बिल्ट-इन पॉलिसीज़ को `BuiltinPolicyDefinition` ऑब्जेक्ट्स के रूप में परिभाषित करता है: ```typescript interface BuiltinPolicyDefinition { @@ -206,15 +205,15 @@ interface BuiltinPolicyDefinition { } ``` -जो पॉलिसीज़ `params` स्वीकार करती हैं वे प्रत्येक पैरामीटर के लिए प्रकार और डिफ़ॉल्ट के साथ `PolicyParamsSchema` की घोषणा करती हैं। पॉलिसी मूल्यांकनकर्ता `fn` को कॉल करने से पहले हल किए गए मानों को `ctx.params` में इंजेक्ट करता है। पॉलिसी फ़ंक्शन `ctx.params` को पढ़ते हैं बिना null-गार्डिंग के क्योंकि डिफ़ॉल्ट हमेशा पहले लागू होते हैं। +पॉलिसीज़ जो `params` स्वीकार करती हैं, प्रत्येक पैरामीटर के लिए प्रकार और डिफ़ॉल्ट्स के साथ एक `PolicyParamsSchema` घोषित करती हैं। पॉलिसी मूल्यांकनकर्ता `fn` को कॉल करने से पहले हल किए गए मूल्यों को `ctx.params` में इंजेक्ट करता है। पॉलिसी फ़ंक्शन `ctx.params` को पढ़ते हैं null-गार्डिंग के बिना क्योंकि डिफ़ॉल्ट्स हमेशा पहले लागू होते हैं। -पॉलिसीज़ के अंदर पैटर्न मिलान पार्स किए गए कमांड टोकन (argv) का उपयोग करता है, कच्ची स्ट्रिंग मिलान नहीं। यह शेल ऑपरेटर इंजेक्शन के माध्यम से बाईपास को रोकता है (उदाहरण के लिए `sudo systemctl status *` के लिए एक पैटर्न `; rm -rf /` को अपेंड करके बाईपास नहीं किया जा सकता)। +पॉलिसीज़ के अंदर पैटर्न मिलान पार्स किए गए कमांड टोकन (argv) का उपयोग करता है, कच्ची स्ट्रिंग मिलान नहीं। यह शेल ऑपरेटर इंजेक्शन के माध्यम से बाईपास को रोकता है (उदाहरण के लिए, `sudo systemctl status *` के लिए एक पैटर्न कमांड में `; rm -rf /` जोड़कर बाईपास नहीं किया जा सकता)। --- ## कस्टम पॉलिसीज़ -`src/hooks/custom-hooks-registry.ts` एक `globalThis`-समर्थित रजिस्ट्री को लागू करता है: +`src/hooks/custom-hooks-registry.ts` एक `globalThis`-समर्थित रजिस्ट्री लागू करता है: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -224,28 +223,28 @@ export const customPolicies = { }; export function getCustomHooks(): CustomHook[] { ... } -export function clearCustomHooks(): void { ... } // परीक्षणों में उपयोग किया जाता है +export function clearCustomHooks(): void { ... } // used in tests ``` -`src/hooks/custom-hooks-loader.ts` उपयोगकर्ता की पॉलिसी फ़ाइल लोड करता है: +`src/hooks/custom-hooks-loader.ts` यूजर की पॉलिसी फाइल लोड करता है: -1. कॉन्फ़िग से `customPoliciesPath` पढ़ें; अनुपस्थित होने पर छोड़ें। -2. पूर्ण पथ में हल करें; फ़ाइल मौजूद है यह जाँचें। -3. सभी `from "failproofai"` आयात को वास्तविक dist पथ में फिर से लिखें ताकि `customPolicies` समान `globalThis` रजिस्ट्री को हल करे। -4. ESM संगतता सुनिश्चित करने के लिए संक्रमणीय स्थानीय आयात को पुनरावर्ती रूप से फिर से लिखें। -5. अस्थायी `.mjs` फ़ाइलें लिखें और entry फ़ाइल को `import()` करें। -6. `getCustomHooks()` को कॉल करके पंजीकृत हुक्स को पुनः प्राप्त करें। -7. `finally` ब्लॉक में सभी अस्थायी फ़ाइलें साफ करें। +1. कॉन्फ़िग से `customPoliciesPath` पढ़ें; यदि अनुपस्थित है तो छोड़ें। +2. पूर्ण पथ में हल करें; फाइल अस्तित्व की जांच करें। +3. सभी `from "failproofai"` आयातों को वास्तविक dist पथ में फिर से लिखें ताकि `customPolicies` समान `globalThis` रजिस्ट्री को हल करे। +4. ESM संगतता सुनिश्चित करने के लिए पारगमन स्थानीय आयातों को पुनरावर्ती रूप से फिर से लिखें। +5. अस्थायी `.mjs` फाइलें लिखें और एंट्री फाइल को `import()` करें। +6. पंजीकृत हुक्स पुनः प्राप्त करने के लिए `getCustomHooks()` को कॉल करें। +7. `finally` ब्लॉक में सभी अस्थायी फाइलें साफ करें। -किसी भी त्रुटि पर (फ़ाइल नहीं मिली, syntax त्रुटि, आयात विफलता), त्रुटि को `~/.failproofai/hook.log` में लॉग किया जाता है और लोडर एक खाली सरणी देता है। बिल्ट-इन पॉलिसीज़ प्रभावित नहीं होती हैं। +किसी भी त्रुटि पर (फाइल नहीं मिली, सिंटैक्स त्रुटि, आयात विफलता), त्रुटि को `~/.failproofai/hook.log` में लॉग किया जाता है और लोडर एक खाली सरणी लौटाता है। बिल्ट-इन पॉलिसीज़ प्रभावित नहीं होती हैं। -कस्टम पॉलिसीज़ का मूल्यांकन सभी बिल्ट-इन पॉलिसीज़ के बाद किया जाता है। एक कस्टम पॉलिसी `deny` अभी भी आगे की कस्टम पॉलिसीज़ को शॉर्ट-सर्किट करता है (लेकिन सभी बिल्ट-इन्स पहले ही चल चुकी होती हैं)। +कस्टम पॉलिसीज़ का मूल्यांकन सभी बिल्ट-इन पॉलिसीज़ के बाद किया जाता है। एक कस्टम पॉलिसी `deny` अभी भी आगे की कस्टम पॉलिसीज़ को शॉर्ट-सर्किट करता है (लेकिन इस बिंदु पर सभी बिल्ट-इन्स पहले ही चल चुकी हैं)। --- ## गतिविधि लॉगिंग -प्रत्येक हुक ईवेंट के बाद, हैंडलर `~/.failproofai/hook-activity.jsonl` में एक JSONL पंक्ति को अपेंड करता है: +प्रत्येक हुक इवेंट के बाद, हैंडलर `~/.failproofai/hook-activity.jsonl` में एक JSONL पंक्ति जोड़ता है: ```json { @@ -260,75 +259,75 @@ export function clearCustomHooks(): void { ... } // परीक्षणों } ``` -एक पंक्ति प्रति पॉलिसी जिसने एक गैर-allow निर्णय दिया। Allow निर्णय लॉग नहीं होते हैं (फ़ाइल को छोटा रखने के लिए)। +प्रत्येक पॉलिसी के लिए एक पंक्ति जिसने एक गैर-अनुमति निर्णय दिया। अनुमति निर्णय लॉग नहीं किए जाते हैं (फाइल को छोटा रखने के लिए)। --- ## डैशबोर्ड आर्किटेक्चर -डैशबोर्ड एक **Next.js 16** एप्लिकेशन है जो App Router के साथ React Server Components और Server Actions का उपयोग करता है। +डैशबोर्ड एक **Next.js 16** एप्लीकेशन है जो App Router का उपयोग करता है React Server Components और Server Actions के साथ। ```text app/ - layout.tsx ← रूट लेआउट (थीम, टेलीमेट्री, नेव) - projects/page.tsx ← सर्वर कंपोनेंट: सभी Claude प्रोजेक्ट सूचीबद्ध करें - project/[name]/page.tsx ← सर्वर कंपोनेंट: प्रोजेक्ट में सेशन सूचीबद्ध करें + layout.tsx ← Root layout (theme, telemetry, nav) + projects/page.tsx ← Server component: list all Claude projects + project/[name]/page.tsx ← Server component: list sessions in a project project/[name]/session/ - [sessionId]/page.tsx ← सर्वर कंपोनेंट: सेशन दर्शक रेंडर करें - policies/page.tsx ← क्लाइंट कंपोनेंट: पॉलिसी प्रबंधन + गतिविधि लॉग + [sessionId]/page.tsx ← Server component: render session viewer + policies/page.tsx ← Client component: policy management + activity log actions/ - get-hooks-config.ts ← कॉन्फ़िग + पॉलिसी सूची पढ़ें - update-hooks-config.ts ← पॉलिसी को चालू/बंद करें - update-policy-params.ts ← पॉलिसी पैरामीटर अपडेट करें - get-hook-activity.ts ← गतिविधि लॉग को पेजिनेट/खोजें - install-hooks-web.ts ← ब्राउज़र से हुक्स को इंस्टॉल/हटाएँ + get-hooks-config.ts ← Read config + policy list + update-hooks-config.ts ← Toggle policy on/off + update-policy-params.ts ← Update policy parameters + get-hook-activity.ts ← Paginate/search activity log + install-hooks-web.ts ← Install/remove hooks from the browser api/ - download/[project]/[session]/route.ts ← प्रति-CLI सेशन एक्सपोर्ट (JSONL या JSON) + download/[project]/[session]/route.ts ← Per-CLI session export (JSONL or JSON) ``` -**डेटा प्रवाह:** +**डेटा फ़्लो:** -- पेज कंपोनेंट प्रोजेक्ट/सेशन डेटा को सीधे फ़ाइलसिस्टम से पढ़ने के लिए `lib/projects.ts` और `lib/log-entries.ts` को कॉल करते हैं (पढ़ने के लिए कोई API परत नहीं)। -- पॉलिसीज़ पेज सभी mutations के लिए Server Actions का उपयोग करता है (टॉगल, params अपडेट, इंस्टॉल/हटाएँ)। -- सेशन दर्शक Claude के JSONL ट्रांसक्रिप्ट प्रारूप को पार्स करता है और संदेशों और टूल कॉल की एक टाइमलाइन रेंडर करता है। +- पेज कंपोनेंट्स प्रोजेक्ट/सेशन डेटा सीधे फाइलसिस्टम से पढ़ने के लिए `lib/projects.ts` और `lib/log-entries.ts` को कॉल करते हैं (पढ़ने के लिए कोई API परत नहीं)। +- पॉलिसीज़ पेज सभी म्यूटेशन्स (टॉगल, पैरामीटर अपडेट, इंस्टॉल/निकालें) के लिए Server Actions का उपयोग करता है। +- सेशन व्यूअर Claude के JSONL ट्रांसक्रिप्ट प्रारूप को पार्स करता है और संदेशों और टूल कॉल की एक समयरेखा प्रदान करता है। -**मुख्य डिज़ाइन निर्णय:** +**मुख्य डिजाइन निर्णय:** -- कोई डेटाबेस नहीं - सभी स्थायी स्थिति सादे फ़ाइलों में है (`~/.failproofai/`, `~/.claude/projects/`)। -- Mutations के लिए Server Actions - CRUD संचालन के लिए कोई REST API आवश्यक नहीं। -- पढ़ने के पृष्ठों के लिए React Server Components - तेज़ प्रारंभिक लोड, डेटा फ़ेचिंग के लिए कोई क्लाइंट बंडल नहीं। -- क्लाइंट कंपोनेंट केवल जहाँ आवश्यकता हो (पॉलिसी टॉगल, गतिविधि खोज, लॉग दर्शक)। +- कोई डेटाबेस नहीं - सभी स्थायी स्थिति सादी फाइलों में है (`~/.failproofai/`, `~/.claude/projects/`)। +- म्यूटेशन्स के लिए Server Actions - CRUD ऑपरेशन्स के लिए कोई REST API आवश्यक नहीं। +- पढ़ने वाले पेजों के लिए React Server Components - तेज़ प्रारंभिक लोड, डेटा फेचिंग के लिए कोई क्लाइंट बंडल नहीं। +- क्लाइंट कंपोनेंट्स केवल जहां इंटरएक्टिविटी आवश्यक है (पॉलिसी टॉगल्स, गतिविधि खोज, लॉग व्यूअर)। --- -## फ़ाइल लेआउट +## फाइल लेआउट ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # CLI राउटर (hook / dashboard / install / आदि) +│ └── failproofai.mjs # CLI router (hook / dashboard / install / etc.) ├── src/hooks/ -│ ├── handler.ts # हुक ईवेंट पाइपलाइन -│ ├── builtin-policies.ts # 39 पॉलिसी परिभाषाएं -│ ├── policy-evaluator.ts # पॉलिसी निष्पादन इंजन -│ ├── policy-registry.ts # पॉलिसी पंजीकरण और लुकअप -│ ├── policy-types.ts # TypeScript इंटरफेस -│ ├── hooks-config.ts # मल्टी-स्कोप कॉन्फ़िग लोडिंग -│ ├── custom-hooks-registry.ts # globalThis-समर्थित हुक रजिस्ट्री -│ ├── custom-hooks-loader.ts # उपयोगकर्ता JS हुक्स के लिए ESM लोडर -│ ├── manager.ts # install / remove / list संचालन -│ ├── install-prompt.ts # इंटरैक्टिव पॉलिसी चयन प्रॉम्प्ट -│ ├── hook-logger.ts # hook.log में लॉगिंग -│ ├── hook-activity-store.ts # hook-activity.jsonl में गतिविधि को रखें -│ └── llm-client.ts # LLM API क्लाइंट (AI-संचालित पॉलिसीज़ के लिए) -├── app/ # Next.js डैशबोर्ड (पृष्ठ + Server actions) -├── lib/ # साझा उपयोगिताएँ -│ ├── projects.ts # फ़ाइलसिस्टम से Claude प्रोजेक्ट गणना करें -│ ├── log-entries.ts # Claude ट्रांसक्रिप्ट JSONL प्रारूप को पार्स करें -│ ├── paths.ts # सिस्टम पथ हल करें +│ ├── handler.ts # Hook event pipeline +│ ├── builtin-policies.ts # 39 policy definitions +│ ├── policy-evaluator.ts # Policy execution engine +│ ├── policy-registry.ts # Policy registration and lookup +│ ├── policy-types.ts # TypeScript interfaces +│ ├── hooks-config.ts # Multi-scope config loading +│ ├── custom-hooks-registry.ts # globalThis-backed hook registry +│ ├── custom-hooks-loader.ts # ESM loader for user JS hooks +│ ├── manager.ts # install / remove / list operations +│ ├── install-prompt.ts # Interactive policy selection prompt +│ ├── hook-logger.ts # Logging to hook.log +│ ├── hook-activity-store.ts # Persist activity to hook-activity.jsonl +│ └── llm-client.ts # LLM API client (for AI-powered policies) +├── app/ # Next.js dashboard (pages + server actions) +├── lib/ # Shared utilities +│ ├── projects.ts # Enumerate Claude projects from filesystem +│ ├── log-entries.ts # Parse Claude transcript JSONL format +│ ├── paths.ts # Resolve system paths │ └── ... -├── components/ # साझा React UI कंपोनेंट -├── contexts/ # React context प्रदाता (थीम, ऑटो-रीफ्रेश, टेलीमेट्री) -├── examples/ # उदाहरण कस्टम हुक फ़ाइलें -└── __tests__/ # यूनिट और E2E परीक्षण +├── components/ # Shared React UI components +├── contexts/ # React context providers (theme, auto-refresh, telemetry) +├── examples/ # Example custom hook files +└── __tests__/ # Unit and E2E tests ``` \ No newline at end of file diff --git a/docs/hi/built-in-policies.mdx b/docs/hi/built-in-policies.mdx index 1a3a89b8..a2350188 100644 --- a/docs/hi/built-in-policies.mdx +++ b/docs/hi/built-in-policies.mdx @@ -1,40 +1,40 @@ --- --- -title: Built-in Policies -description: "सभी 39 built-in policies जो common agent failure modes को पकड़ते हैं" +title: अंतर्निहित नीतियाँ +description: "39 अंतर्निहित नीतियाँ जो एजेंट की आम विफलताओं को पकड़ती हैं" icon: shield --- -failproofai 39 built-in policies के साथ आता है जो common agent failure modes को पकड़ते हैं। प्रत्येक policy एक specific hook event type और tool name पर fires करता है। Nineteen policies parameters स्वीकार करती हैं जो आपको code लिखे बिना उनके behavior को tune करने देती हैं। Five workflow policies एक commit → push → PR → CI pipeline enforce करती हैं जिससे पहले कि Claude रुके। +failproofai के साथ 39 अंतर्निहित नीतियाँ आती हैं जो एजेंट की आम विफलताओं को पकड़ती हैं। प्रत्येक नीति एक विशिष्ट हुक ईवेंट प्रकार और उपकरण नाम पर सक्रिय होती है। उन्नीस नीतियाँ पैरामीटर स्वीकार करती हैं जो आपको कोड लिखे बिना उनके व्यवहार को ट्यून करने देती हैं। पाँच वर्कफ़्लो नीतियाँ Claude के रुकने से पहले एक commit → push → PR → CI पाइपलाइन को लागू करती हैं। --- -## Overview +## अवलोकन -Policies को categories में grouped किया गया है: +नीतियाँ श्रेणियों में विभाजित हैं: -| Category | Policies | Hook type | +| श्रेणी | नीतियाँ | हुक प्रकार | |----------|----------|-----------| -| [Dangerous commands](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | -| [Infra commands](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [Secrets (sanitizers)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | -| [Environment](#environment) | block-env-files, protect-env-vars | PreToolUse | -| [File access](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | +| [खतरनाक आदेश](#खतरनाक-आदेश) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | +| [इनफ्रा आदेश](#infra-आदेश) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | +| [गोपनीयता (सैनिटाइज़र)](#गोपनीयता-सैनिटाइज़र) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [वातावरण](#वातावरण) | block-env-files, protect-env-vars | PreToolUse | +| [फाइल एक्सेस](#फाइल-एक्सेस) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | -| [Database](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse | -| [Warnings](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | -| [Package managers](#package-managers) | prefer-package-manager | PreToolUse | -| [Workflow](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | +| [डेटाबेस](#डेटाबेस) | warn-destructive-sql, warn-schema-alteration | PreToolUse | +| [चेतावनियाँ](#चेतावनियाँ) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | +| [पैकेज मैनेजर](#पैकेज-मैनेजर) | prefer-package-manager | PreToolUse | +| [वर्कफ़्लो](#वर्कफ़्लो) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — agent को आगे बढ़ने से रोकता है। -- **`warn-`** — agent को additional context देता है ताकि वह self-correct कर सके। -- **`sanitize-`** — agent को देखने से पहले tool output से sensitive data को scrub करता है। +- **`block-`** — एजेंट को आगे बढ़ने से रोकें। +- **`warn-`** — एजेंट को अतिरिक्त संदर्भ दें ताकि यह स्वयं को ठीक कर सके। +- **`sanitize-`** — एजेंट को देखने से पहले उपकरण आउटपुट से संवेदनशील डेटा हटाएँ। -### Namespaces +### नेमस्पेस -प्रत्येक policy एक `/` slot में रहती है। Built-in policies **`failproofai/`** namespace में belong करती हैं — उदाहरण के लिए, `failproofai/sanitize-jwt`। Namespace collisions को prevent करता है जब आप similar short names वाली custom या third-party policies भी load करते हैं। +प्रत्येक नीति एक `/` स्लॉट में रहती है। अंतर्निहित नीतियाँ **`failproofai/`** नेमस्पेस से संबंधित हैं — उदाहरण के लिए, `failproofai/sanitize-jwt`। नेमस्पेस तब collision को रोकता है जब आप कस्टम या तीसरे पक्ष की नीतियों को समान छोटे नामों के साथ भी लोड करते हैं। -आपके config में आप एक built-in को either its short name या its qualified name से refer कर सकते हैं; दोनों forms same policy को resolve करते हैं: +आपके कॉन्फ़िग में आप अंतर्निहित को उसके छोटे नाम या योग्य नाम दोनों से संदर्भित कर सकते हैं; दोनों रूप एक ही नीति को resolve करते हैं: ```json { @@ -45,35 +45,35 @@ Policies को categories में grouped किया गया है: } ``` -अगर एक name में कोई `/` नहीं है, तो failproofai इसे default namespace `failproofai` में treat करता है। Names जिनमें पहले से एक `/` है (जैसे `myorg/foo`, `custom/my-hook`) को as-is रखा जाता है। -- **`require-`** — Stop event को block करता है जब तक कि conditions पूरी न हों। +यदि किसी नाम में कोई `/` नहीं है, failproofai इसे default नेमस्पेस `failproofai` के अंतर्गत मानता है। नाम जिनमें पहले से `/` है (जैसे `myorg/foo`, `custom/my-hook`) जैसे-जैसे रखे जाते हैं। +- **`require-`** — Stop ईवेंट को ब्लॉक करें जब तक शर्तें पूरी न हों। --- -प्रत्येक policy `policyParams` में एक optional `hint` field को support करती है। Hint को deny या instruct message में append किया जाता है जो Claude देखता है, actionable guidance देता है बिना policy code को modify किए। Built-in, custom, और convention policies के साथ काम करता है। Details के लिए [Configuration → hint](/hi/configuration#hint-cross-cutting) देखें। +प्रत्येक नीति `policyParams` में एक वैकल्पिक `hint` फील्ड का समर्थन करती है। hint को deny या instruct message में जोड़ा जाता है जो Claude देखता है, नीति कोड को संशोधित किए बिना कार्रवाई योग्य मार्गदर्शन देते हुए। अंतर्निहित, कस्टम, और convention नीतियों के साथ काम करता है। विवरण के लिए [Configuration → hint](/hi/configuration#hint-cross-cutting) देखें। --- -## Dangerous commands +## खतरनाक आदेश -Agents को ऐसे operations चलाने से prevent करें जो undo करना मुश्किल हैं या host system को damage कर सकते हैं। +एजेंटों को उन ऑपरेशन चलाने से रोकें जो को पूर्ववत करना कठिन हो या जो होस्ट सिस्टम को नुकसान पहुंचा सकते हैं। ### `block-sudo` -**Event:** PreToolUse (Bash) -**Default:** किसी भी `sudo` command को deny करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** कोई भी `sudo` कमांड deny करता है। -`sudo` keyword को contain करने वाले invocations को block करता है। Pattern matching parsed command tokens पर किया जाता है, raw string पर नहीं, shell operator injection के माध्यम से bypass को prevent करने के लिए। +`sudo` कीवर्ड सहित invocations को ब्लॉक करता है। पैटर्न मिलान कच्ची स्ट्रिंग के बजाय parsed कमांड टोकन पर किया जाता है, shell operator injection के माध्यम से bypass को रोकने के लिए। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Exact command prefixes जो permitted हैं। प्रत्येक entry को parsed argv tokens के विरुद्ध match किया जाता है। | +| `allowPatterns` | `string[]` | `[]` | सटीक कमांड प्रीफ़िक्स जो अनुमत हैं। प्रत्येक entry को parsed argv tokens के विरुद्ध मिलाया जाता है। | -**Example:** +**उदाहरण:** ```json { @@ -85,26 +85,26 @@ Agents को ऐसे operations चलाने से prevent करें } ``` -इस config के साथ, `sudo systemctl status nginx` को allow किया जाता है, लेकिन `sudo rm /etc/hosts` को deny किया जाता है। +इस कॉन्फ़िग के साथ, `sudo systemctl status nginx` अनुमत है, लेकिन `sudo rm /etc/hosts` deny किया जाता है। -Patterns को parsed tokens के विरुद्ध match किया जाता है, raw command string के विरुद्ध नहीं। यह appended shell operators के माध्यम से bypass को prevent करता है (जैसे `sudo systemctl status x; rm -rf /` को `sudo systemctl status *` के विरुद्ध match नहीं किया जाता)। +पैटर्न को कच्ची कमांड स्ट्रिंग के बजाय parsed tokens के विरुद्ध मिलाया जाता है। यह appended shell operators के माध्यम से bypass को रोकता है (उदाहरण के लिए `sudo systemctl status x; rm -rf /` `sudo systemctl status *` से match नहीं करता)। --- ### `block-rm-rf` -**Event:** PreToolUse (Bash) -**Default:** `rm -rf`, `rm -fr`, और similar recursive deletion forms को deny करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `rm -rf`, `rm -fr`, और समान recursive deletion रूपों को deny करता है। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Paths जो recursively delete करने के लिए safe हैं (जैसे `/tmp`)। | +| `allowPaths` | `string[]` | `[]` | पथ जो recursively delete करने के लिए सुरक्षित हैं (उदाहरण के लिए `/tmp`)। | -**Example:** +**उदाहरण:** ```json { @@ -120,40 +120,40 @@ Patterns को parsed tokens के विरुद्ध match किया ### `block-curl-pipe-sh` -**Event:** PreToolUse (Bash) -**Default:** `curl | bash`, `curl | sh`, `wget | bash`, और similar patterns को deny करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `curl | bash`, `curl | sh`, `wget | bash`, और समान patterns को deny करता है। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- ### `block-failproofai-commands` -**Event:** PreToolUse (Bash) -**Default:** Commands को deny करता है जो failproofai को uninstall या disable करेंगे (जैसे `npm uninstall failproofai`, `failproofai policies --uninstall`)। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** उन कमांडों को deny करता है जो failproofai को स्वयं को uninstall या disable करने के लिए होंगे (उदाहरण के लिए `npm uninstall failproofai`, `failproofai policies --uninstall`)। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- -## Infra commands +## infra आदेश -Coding agents को infrastructure CLIs चलाने या CI/CD pipelines trigger करने से रोकें। इस category में सभी policies **opt-in** हैं (`defaultEnabled: false`) — agents जिन्हें legitimately `kubectl`, `terraform`, आदि को call करने की जरूरत है, वे policy के enabled न होने तक disrupted नहीं होंगे। जब enabled हो, तो matched CLI के हर invocation को deny किया जाता है जब तक कि command `allowPatterns` में एक entry से match न हो। +कोडिंग एजेंटों को infrastructure CLIs चलाने या CI/CD pipelines को trigger करने से रोकें। इस श्रेणी में सभी नीतियाँ **opt-in** हैं (`defaultEnabled: false`) — एजेंट जिन्हें वैध रूप से `kubectl`, `terraform`, आदि को कॉल करने की आवश्यकता है, जब तक आप नीति को enable नहीं करते, तब तक बाधित नहीं होंगे। जब enabled हो, तो matched CLI का हर invocation deny किया जाता है जब तक कमांड `allowPatterns` में एक entry से match न हो। -Pattern grammar [`block-sudo`](#block-sudo) जैसा ही है: tokens को parsed argv के विरुद्ध match किया जाता है, `*` एक token के लिए wildcard है, और किसी भी command जिसमें standalone shell operator (`&&`, `||`, `|`, `;`) या embedded shell metacharacters वाला token है, को injection bypasses को prevent करने के लिए allowlist matching से पहले reject किया जाता है। +पैटर्न grammar [`block-sudo`](#block-sudo) के समान है: tokens को parsed argv के विरुद्ध मिलाया जाता है, `*` एक token के लिए wildcard है, और कोई भी कमांड जिसमें एक standalone shell operator (`&&`, `||`, `|`, `;`) या embedded shell metacharacters वाला token है, injection bypasses को रोकने के लिए allowlist matching से पहले reject किया जाता है। ### `block-kubectl` -**Event:** PreToolUse (Bash) -**Default:** किसी भी `kubectl` invocation को deny करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** कोई भी `kubectl` invocation deny करता है। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | kubectl command prefixes जो permitted हैं। | +| `allowPatterns` | `string[]` | `[]` | kubectl कमांड प्रीफ़िक्स जो अनुमत हैं। | -**Example:** +**उदाहरण:** ```json { @@ -165,22 +165,22 @@ Pattern grammar [`block-sudo`](#block-sudo) जैसा ही है: tokens } ``` -इस config के साथ, `kubectl get pods` को allow किया जाता है लेकिन `kubectl apply -f deploy.yaml` को deny किया जाता है। +इस कॉन्फ़िग के साथ, `kubectl get pods` अनुमत है लेकिन `kubectl apply -f deploy.yaml` deny किया जाता है। --- ### `block-terraform` -**Event:** PreToolUse (Bash) -**Default:** किसी भी `terraform` या `tofu` (OpenTofu) invocation को deny करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** कोई भी `terraform` या `tofu` (OpenTofu) invocation deny करता है। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | terraform/tofu command prefixes जो permitted हैं। | +| `allowPatterns` | `string[]` | `[]` | terraform/tofu कमांड प्रीफ़िक्स जो अनुमत हैं। | -**Example:** +**उदाहरण:** ```json { @@ -196,16 +196,16 @@ Pattern grammar [`block-sudo`](#block-sudo) जैसा ही है: tokens ### `block-aws-cli` -**Event:** PreToolUse (Bash) -**Default:** किसी भी `aws` CLI invocation को deny करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** कोई भी `aws` CLI invocation deny करता है। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | aws CLI command prefixes जो permitted हैं। | +| `allowPatterns` | `string[]` | `[]` | aws CLI कमांड प्रीफ़िक्स जो अनुमत हैं। | -**Example:** +**उदाहरण:** ```json { @@ -221,16 +221,16 @@ Pattern grammar [`block-sudo`](#block-sudo) जैसा ही है: tokens ### `block-gcloud` -**Event:** PreToolUse (Bash) -**Default:** किसी भी `gcloud` (Google Cloud) CLI invocation को deny करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** कोई भी `gcloud` (Google Cloud) CLI invocation deny करता है। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | gcloud command prefixes जो permitted हैं। | +| `allowPatterns` | `string[]` | `[]` | gcloud कमांड प्रीफ़िक्स जो अनुमत हैं। | -**Example:** +**उदाहरण:** ```json { @@ -246,16 +246,16 @@ Pattern grammar [`block-sudo`](#block-sudo) जैसा ही है: tokens ### `block-az-cli` -**Event:** PreToolUse (Bash) -**Default:** किसी भी `az` (Azure) CLI invocation को deny करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** कोई भी `az` (Azure) CLI invocation deny करता है। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | az CLI command prefixes जो permitted हैं। | +| `allowPatterns` | `string[]` | `[]` | az CLI कमांड प्रीफ़िक्स जो अनुमत हैं। | -**Example:** +**उदाहरण:** ```json { @@ -271,16 +271,16 @@ Pattern grammar [`block-sudo`](#block-sudo) जैसा ही है: tokens ### `block-helm` -**Event:** PreToolUse (Bash) -**Default:** किसी भी `helm` invocation को deny करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** कोई भी `helm` invocation deny करता है। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | helm command prefixes जो permitted हैं। | +| `allowPatterns` | `string[]` | `[]` | helm कमांड प्रीफ़िक्स जो अनुमत हैं। | -**Example:** +**उदाहरण:** ```json { @@ -296,8 +296,8 @@ Pattern grammar [`block-sudo`](#block-sudo) जैसा ही है: tokens ### `block-gh-pipeline` -**Event:** PreToolUse (Bash) -**Default:** निम्नलिखित `gh` CLI subcommands को deny करता है जो state mutate करते हैं या pipelines trigger करते हैं: +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** निम्नलिखित `gh` CLI subcommands को deny करता है जो state को mutate करते हैं या pipelines को trigger करते हैं: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -306,15 +306,15 @@ Pattern grammar [`block-sudo`](#block-sudo) जैसा ही है: tokens - `gh cache delete` - `gh secret set`, `gh secret delete` -Read-only `gh` subcommands जैसे `gh pr view`, `gh pr list`, `gh run list`, `gh release view`, और `gh api repos/.../...` को इस policy द्वारा match **नहीं** किया जाता है — वे workflow checks के लिए routinely needed हैं (failproofai के अपने `require-ci-green-before-stop` सहित)। +Read-only `gh` subcommands जैसे `gh pr view`, `gh pr list`, `gh run list`, `gh release view`, और `gh api repos/.../...` इस नीति से match **नहीं** होते हैं — वे workflow checks के लिए नियमित रूप से आवश्यक हैं (failproofai का अपना `require-ci-green-before-stop` सहित)। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Specific scripted invocations को allow करने के लिए भले ही वे otherwise deny किए जाएं। | +| `allowPatterns` | `string[]` | `[]` | विशिष्ट scripted invocations जो allow करने के लिए हैं भले ही वे अन्यथा deny किए जाएँ। | -**Example:** +**उदाहरण:** ```json { @@ -328,31 +328,31 @@ Read-only `gh` subcommands जैसे `gh pr view`, `gh pr list`, `gh run list --- -## Secrets (sanitizers) +## गोपनीयता (सैनिटाइज़र) -Agents को अपने context या output में credentials leak करने से रोकें। Sanitizer policies **PostToolUse** events पर fire करती हैं। जब Claude एक Bash command चलाता है, एक file को read करता है, या कोई भी tool को call करता है, तो ये policies output को inspect करती हैं इससे पहले कि वह Claude को return किया जाए। अगर एक secret pattern detect होता है, तो policy एक deny decision return करता है जो output को pass back होने से prevent करता है। +एजेंटों को credentials को अपने context या output में leak करने से रोकें। Sanitizer नीतियाँ **PostToolUse** ईवेंट पर fire होती हैं। जब Claude Bash कमांड चलाता है, फाइल पढ़ता है, या कोई भी tool कॉल करता है, ये नीतियाँ आउटपुट को inspect करती हैं इससे पहले कि यह Claude को वापस दिया जाए। यदि एक secret pattern detect किया जाता है, तो नीति एक deny decision return करती है जो आउटपुट को वापस जाने से रोकता है। ### `sanitize-jwt` -**Event:** PostToolUse (all tools) -**Default:** JWT tokens को redact करता है (three base64url segments separated by `.`)। +**ईवेंट:** PostToolUse (सभी tools) +**डिफ़ॉल्ट:** JWT tokens को redact करता है (तीन base64url segments `.` से separated)। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- ### `sanitize-api-keys` -**Event:** PostToolUse (all tools) -**Default:** Common API key formats को redact करता है: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS access keys (`AKIA`), Stripe keys (`sk_live_`, `sk_test_`), और Google API keys (`AIza`)। +**ईवेंट:** PostToolUse (सभी tools) +**डिफ़ॉल्ट:** सामान्य API key formats को redact करता है: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS access keys (`AKIA`), Stripe keys (`sk_live_`, `sk_test_`), और Google API keys (`AIza`)। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Additional regex patterns को secrets के रूप में treat करने के लिए। | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | अतिरिक्त regex patterns जो secrets के रूप में treat करें। | -**Example:** +**उदाहरण:** ```json { @@ -371,71 +371,71 @@ Agents को अपने context या output में credentials leak क ### `sanitize-connection-strings` -**Event:** PostToolUse (all tools) -**Default:** Database connection strings को redact करता है जिनमें embedded credentials हैं (जैसे `postgresql://user:password@host/db`)। +**ईवेंट:** PostToolUse (सभी tools) +**डिफ़ॉल्ट:** डेटाबेस connection strings को redact करता है जिनमें embedded credentials हैं (उदाहरण के लिए `postgresql://user:password@host/db`)। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- ### `sanitize-private-key-content` -**Event:** PostToolUse (all tools) -**Default:** PEM blocks को redact करता है (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, आदि)। +**ईवेंट:** PostToolUse (सभी tools) +**डिफ़ॉल्ट:** PEM blocks को redact करता है (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, आदि)। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- ### `sanitize-bearer-tokens` -**Event:** PostToolUse (all tools) -**Default:** `Authorization: Bearer ` headers को redact करता है जहाँ token 20 या अधिक characters है। +**ईवेंट:** PostToolUse (सभी tools) +**डिफ़ॉल्ट:** `Authorization: Bearer ` headers को redact करता है जहाँ token 20 या अधिक characters है। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- -## Environment +## वातावरण -Sensitive environment configuration को agents द्वारा read या expose किए जाने से protect करें। +संवेदनशील environment configuration को एजेंटों द्वारा read या expose किए जाने से बचाएँ। ### `block-env-files` -**Event:** PreToolUse (Bash, Read) -**Default:** `.env` files को read करने को deny करता है via `cat .env`, Read tool calls with `.env` as the file path, आदि। +**ईवेंट:** PreToolUse (Bash, Read) +**डिफ़ॉल्ट:** `.env` files को `cat .env`, file path के रूप में `.env` के साथ `Read` tool calls आदि के माध्यम से पढ़ने को deny करता है। -`.envrc` या अन्य environment-adjacent files को block नहीं करता - केवल exactly `.env` नामक files को। +`.envrc` या अन्य environment-adjacent files को नहीं रोकता — केवल exactly `.env` नाम वाली files को। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- ### `protect-env-vars` -**Event:** PreToolUse (Bash) -**Default:** Commands को deny करता है जो environment variables को print करते हैं: `printenv`, `env`, `echo $VAR`। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** उन कमांडों को deny करता है जो environment variables को print करते हैं: `printenv`, `env`, `echo $VAR`। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- -## File access +## फाइल एक्सेस -Agents को project boundaries के अंदर काम करने और sensitive files से दूर रखें। +एजेंटों को project boundaries के भीतर और sensitive files से दूर रखें। ### `block-read-outside-cwd` -**Event:** PreToolUse (Read, Bash) -**Default:** Project root के बाहर files को read करने को deny करता है। Boundary `CLAUDE_PROJECT_DIR` है (Claude Code द्वारा प्रति session में set किया गया), जिसका fallback session के current working directory में है जब वह variable unset हो। Live `cwd` की बजाय project root का use करने का मतलब है कि boundary stable रहता है भले ही Claude किसी subdirectory में `cd` करे। +**ईवेंट:** PreToolUse (Read, Bash) +**डिफ़ॉल्ट:** project root के बाहर की files को पढ़ने को deny करता है। boundary `CLAUDE_PROJECT_DIR` है (एक बार प्रति session Claude Code द्वारा set), जिसमें fallback होता है session के current working directory में जब यह variable unset हो। live `cwd` के बजाय project root का उपयोग करने का मतलब है कि boundary स्थिर रहता है भले ही Claude subdirectory में `cd` कर जाए। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Absolute path prefixes जो permitted हैं भले ही वे project root के बाहर हों। | +| `allowPaths` | `string[]` | `[]` | Absolute path prefixes जो अनुमत हैं भले ही project root के बाहर हों। | -**Example:** +**उदाहरण:** ```json { @@ -451,16 +451,16 @@ Agents को project boundaries के अंदर काम करने औ ### `block-secrets-write` -**Event:** PreToolUse (Write, Edit) -**Default:** Files में writes को deny करता है जो commonly private keys और certificates के लिए use होती हैं: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`। +**ईवेंट:** PreToolUse (Write, Edit) +**डिफ़ॉल्ट:** private keys और certificates के लिए आमतौर पर उपयोग की जाने वाली files को write करने को deny करता है: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | Additional filename patterns (glob-style) को block करने के लिए। | +| `additionalPatterns` | `string[]` | `[]` | अतिरिक्त filename patterns (glob-style) जो block करें। | -**Example:** +**उदाहरण:** ```json { @@ -476,20 +476,20 @@ Agents को project boundaries के अंदर काम करने औ ## Git -Accidental pushes, force-pushes, और branch mistakes को prevent करें जो undo करना मुश्किल हैं। +accidental pushes, force-pushes, और branch mistakes को रोकें जो undo करना कठिन हो। ### `block-push-master` -**Event:** PreToolUse (Bash) -**Default:** `git push origin main` और `git push origin master` को deny करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `git push origin main` और `git push origin master` को deny करता है। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Branch names जो directly को push नहीं किए जा सकते। | +| `protectedBranches` | `string[]` | `["main", "master"]` | Branch नाम जिन्हें directly push नहीं किया जा सकता। | -**Example:** +**उदाहरण:** ```json { @@ -502,36 +502,36 @@ Accidental pushes, force-pushes, और branch mistakes को prevent करे ``` -सभी branches को push करने की allow देने के लिए (effectively इस policy को `enabledPolicies` से remove किए बिना disable करने के लिए), `protectedBranches: []` set करें। +सभी branches को push करने की अनुमति देने के लिए (इस नीति को `enabledPolicies` से remove किए बिना effectively disable करने के लिए), `protectedBranches: []` set करें। --- ### `block-work-on-main` -**Event:** PreToolUse (Bash) -**Default:** `git commit`, `git merge`, `git rebase`, और `git cherry-pick` को deny करता है जबकि working tree `main` या `master` पर है। Branch creation और switching (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) को affected नहीं किया जाता। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `git commit`, `git merge`, `git rebase`, और `git cherry-pick` को deny करता है जबकि working tree `main` या `master` पर हो। Branch creation और switching (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) प्रभावित नहीं होते। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Branch names जिन पर commit/merge/rebase/cherry-pick को deny किया जाता है। | +| `protectedBranches` | `string[]` | `["main", "master"]` | Branch नाम जिन पर commit/merge/rebase/cherry-pick deny किया जाता है। | --- ### `block-force-push` -**Event:** PreToolUse (Bash) -**Default:** `git push --force` और `git push -f` को deny करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `git push --force` और `git push -f` को deny करता है। -कोई policy-specific parameters नहीं। Cross-cutting [`hint`](/hi/configuration#hint-cross-cutting) का use करके alternatives suggest करें: +कोई policy-specific पैरामीटर नहीं। cross-cutting [`hint`](/hi/configuration#hint-cross-cutting) का उपयोग करें alternatives suggest करने के लिए: ```json { "policyParams": { "block-force-push": { - "hint": "अपने current HEAD से एक new branch create करें (जैसे `git checkout -b `) और उसे instead push करें।" + "hint": "अपने current HEAD से एक नई branch बनाएँ (उदाहरण के लिए `git checkout -b `) और उसे push करें।" } } } @@ -541,69 +541,69 @@ Accidental pushes, force-pushes, और branch mistakes को prevent करे ### `warn-git-amend` -**Event:** PreToolUse (Bash) -**Default:** Claude को `git commit --amend` चलाते समय carefully proceed करने के लिए instruct करता है। Command को block नहीं करता। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Claude को सावधानी से proceed करने का instruct करता है जब `git commit --amend` चलाया जाए। कमांड को block नहीं करता। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- ### `warn-git-stash-drop` -**Event:** PreToolUse (Bash) -**Default:** Claude को `git stash drop` चलाने से पहले confirm करने के लिए instruct करता है। Command को block नहीं करता। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Claude को `git stash drop` चलाने से पहले confirm करने का instruct करता है। कमांड को block नहीं करता। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- ### `warn-all-files-staged` -**Event:** PreToolUse (Bash) -**Default:** Claude को review करने के लिए instruct करता है कि वह क्या stage कर रहा है जब `git add -A` या `git add .` चलाता है। Command को block नहीं करता। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Claude को review करने का instruct करता है कि यह क्या stage कर रहा है जब `git add -A` या `git add .` चलाया जाए। कमांड को block नहीं करता। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- -## Database +## डेटाबेस -Destructive SQL operations को catch करें इससे पहले कि वे आपके database के विरुद्ध execute हों। +destructive SQL operations को execute होने से पहले पकड़ें अपने database के विरुद्ध। ### `warn-destructive-sql` -**Event:** PreToolUse (Bash) -**Default:** Claude को `DROP TABLE`, `DROP DATABASE`, या `WHERE` clause के बिना `DELETE` contain करने वाले SQL को confirm करने से पहले instruct करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Claude को confirm करने का instruct करता है SQL चलाने से पहले जिसमें `DROP TABLE`, `DROP DATABASE`, या `WHERE` clause के बिना `DELETE` हो। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- ### `warn-schema-alteration` -**Event:** PreToolUse (Bash) -**Default:** Claude को `ALTER TABLE` statements चलाने से पहले confirm करने के लिए instruct करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Claude को `ALTER TABLE` statements चलाने से पहले confirm करने का instruct करता है। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- -## Warnings +## चेतावनियाँ -Agents को potentially risky लेकिन non-destructive operations से पहले extra context दें। +एजेंटों को potentially risky लेकिन non-destructive operations से पहले extra context दें। ### `warn-large-file-write` -**Event:** PreToolUse (Write) -**Default:** Claude को 1024 KB से बड़ी files को write करने से पहले confirm करने के लिए instruct करता है। +**ईवेंट:** PreToolUse (Write) +**डिफ़ॉल्ट:** Claude को 1024 KB से बड़ी files write करने से पहले confirm करने का instruct करता है। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | File size threshold (kilobytes में) जिससे ऊपर एक warning issue किया जाता है। | +| `thresholdKb` | `number` | `1024` | File size threshold kilobytes में जिसके ऊपर एक warning issue किया जाता है। | -**Example:** +**उदाहरण:** ```json { @@ -616,57 +616,57 @@ Agents को potentially risky लेकिन non-destructive operations स ``` -Hook handler 1 MB stdin limit को payloads पर enforce करता है। इस policy को small content के साथ test करने के लिए, `thresholdKb` को 1024 के well below एक value में set करें। +Hook handler payloads पर 1 MB stdin limit enforce करता है। इस नीति को small content के साथ test करने के लिए, `thresholdKb` को 1024 से काफी कम value में set करें। --- ### `warn-package-publish` -**Event:** PreToolUse (Bash) -**Default:** Claude को `npm publish` चलाने से पहले confirm करने के लिए instruct करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Claude को `npm publish` चलाने से पहले confirm करने का instruct करता है। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- ### `warn-background-process` -**Event:** PreToolUse (Bash) -**Default:** Claude को `nohup`, `&`, `disown`, या `screen` via background processes launch करते समय careful होने के लिए instruct करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Claude को `nohup`, `&`, `disown`, या `screen` के via background processes launch करते समय सावधान रहने का instruct करता है। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- ### `warn-global-package-install` -**Event:** PreToolUse (Bash) -**Default:** Claude को `npm install -g`, `yarn global add`, या `pip install` without a virtual environment चलाने से पहले confirm करने के लिए instruct करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Claude को `npm install -g`, `yarn global add`, या virtual environment के बिना `pip install` चलाने से पहले confirm करने का instruct करता है। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- -## Package managers +## पैकेज मैनेजर -Enforce करें कि agent कौन से package managers use करने की allow दी जाती है। +enforce करें कि एजेंट किस पैकेज मैनेजर को use करने की अनुमति है। ### `prefer-package-manager` -**Event:** PreToolUse (Bash) -**Default:** Disabled। जब enabled हो, तो किसी भी package manager command को block करता है जो `allowed` list में नहीं है और Claude को एक allowed manager का use करके command को rewrite करने के लिए बताता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** Disabled। जब enabled हो, तो `allowed` list में नहीं होने वाली कोई भी पैकेज मैनेजर command को block करता है और Claude को allowed manager का उपयोग करके command को rewrite करने का कहता है। Detects: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo। -| Parameter | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | Allowed package manager names। कोई भी detected manager जो इस list में नहीं है, को block किया जाता है। जब empty हो, policy एक no-op है। | -| `blocked` | string[] | `[]` | Additional manager names को built-in list के beyond block करने के लिए (जैसे `['pdm', 'pipx']`)। | +| `allowed` | string[] | `[]` | अनुमत पैकेज मैनेजर नाम। कोई भी detected manager जो इस list में नहीं है block किया जाता है। जब empty हो, तो नीति एक no-op है। | +| `blocked` | string[] | `[]` | अतिरिक्त मैनेजर नाम जो built-in list के अलावा block करें (उदाहरण के लिए `['pdm', 'pipx']`)। | -Built-in block list में शामिल है: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo। इस list में नहीं managers को append करने के लिए `blocked` का use करें। +Built-in block list covers: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo। इस list में नहीं होने वाले managers को append करने के लिए `blocked` का उपयोग करें। -**Example configuration:** +**उदाहरण कॉन्फ़िगरेशन:** ```json { @@ -680,76 +680,76 @@ Built-in block list में शामिल है: pip, pip3, npm, npx, yarn, } ``` -इस config के साथ, `pip install flask` और `pdm install flask` दोनों को deny किया जाता है एक message के साथ जो Claude को `uv` या `bun` use करने के लिए बताता है। Commands जैसे `uv pip install flask` को allow किया जाता है क्योंकि `uv` allowlist में है और पहले check किया जाता है। +इस कॉन्फ़िग के साथ, `pip install flask` और `pdm install flask` दोनों deny किए जाते हैं Claude को एक message के साथ जो कहता है `uv` या `bun` का उपयोग करने के लिए। `uv pip install flask` जैसी commands अनुमत हैं क्योंकि `uv` allowlist में है और पहले check किया जाता है। --- -## AI behavior +## AI व्यवहार -Detect करें कि जब agents stuck हों या unexpectedly behave करें। +detect करें जब एजेंट stuck हों या unexpectedly behave करें। ### `warn-repeated-tool-calls` -**Event:** PreToolUse (all tools) -**Default:** Claude को reconsider करने के लिए instruct करता है जब same tool को 3+ times identical parameters के साथ call किया जाता है - एक common sign है कि agent एक loop में stuck है। +**ईवेंट:** PreToolUse (सभी tools) +**डिफ़ॉल्ट:** Claude को reconsider करने का instruct करता है जब same tool को 3+ times identical parameters के साथ call किया जाए — एक common sign कि एजेंट एक loop में stuck है। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- -## Workflow +## वर्कफ़्लो -एक disciplined end-of-session workflow को enforce करें। ये policies **Stop** event पर fire करती हैं और agent को stopping से deny करती हैं जब तक कि प्रत्येक condition पूरी न हो। वे एक natural dependency chain को follow करती हैं: commit → push → PR → CI। अगर एक policy deny करती है, तो chain में later policies को skip किया जाता है (deny short-circuits)। +एक disciplined end-of-session workflow को enforce करें। ये नीतियाँ **Stop** event पर fire होती हैं और एजेंट को stop करने से deny करती हैं जब तक प्रत्येक condition meet न हो। वे एक natural dependency chain का follow करती हैं: commit → push → PR → CI। यदि एक नीति deny करती है, तो chain में बाद की नीतियाँ skip किए जाते हैं (deny short-circuits)। -सभी workflow policies **fail-open** हैं: अगर required tool available नहीं है (जैसे `gh` installed न हो, कोई git remote न हो), तो policy allow करती है एक informational message के साथ जो समझाता है कि check को क्यों skip किया गया। +सभी वर्कफ़्लो नीतियाँ **fail-open** हैं: यदि required tool available नहीं है (उदाहरण के लिए `gh` installed नहीं, कोई git remote नहीं), तो नीति allow करती है एक informational message के साथ जो explain करता है कि check क्यों skip किया गया। ### Per-CLI Stop semantics -Stop enforcement सातों supported CLIs में slightly अलग दिखाई देता है क्योंकि प्रत्येक एक अलग expose करता है "agent finished" hook contract। **Outcome** same है — agent stopping से दूर नहीं हो सकता जबकि एक workflow gate failing है — लेकिन **mechanics** अलग हैं। नीचे दी गई table एक summary देती है; केवल Pi के पास एक user-visible quirk है जिसे समझने की जरूरत है इससे पहले कि आप एक `require-*-before-stop` policy को enable करें। +Stop enforcement सातों supported CLIs में थोड़ा अलग दिखता है क्योंकि प्रत्येक एक अलग "agent finished" hook contract expose करता है। **outcome** same है — एजेंट workflow gate failing होने पर stop नहीं हो सकता — लेकिन **mechanics** अलग हैं। नीचे की table summarize करती है; केवल Pi के पास एक user-visible quirk है जो समझने के लायक है इससे पहले आप एक `require-*-before-stop` नीति को enable करें। -| CLI | When the gate fires | What you see | +| CLI | जब gate fires | आप क्या देखते हैं | |---|---|---| -| Claude Code | Same agent loop, immediately | Claude continues working — fixes the issue, then attempts to finish again. No interruption visible to you. | -| Codex | Same agent loop, immediately | Same as Claude. | -| GitHub Copilot CLI | Same agent loop, immediately | Same as Claude (uses Copilot's `{decision:"block", reason}` retry channel — verified empirically against Copilot CLI 1.0.41). | -| Cursor Agent | Same agent loop, immediately | Same as Claude (uses Cursor's `{followup_message}` channel — capped at `loop_limit`, default 5 retries). | -| Gemini CLI | Same agent loop, immediately | Same as Claude (uses Gemini's `{decision:"block", reason}` channel on `AfterAgent`). | -| OpenCode | Same agent loop, immediately | Same as Claude (uses OpenCode's `client.session.prompt(...)` SDK call routed through `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **Next user turn** | **Pi visibly stops** when the gate fires — its agent loop exits and you're returned to the prompt. The gate then fires the next time you submit a prompt: failproofai prepends a `MANDATORY ACTION REQUIRED` directive to that turn's system prompt, instructing the LLM to complete the workflow step (commit, push, etc.) before doing whatever you asked. | +| Claude Code | Same agent loop, immediately | Claude काम करता रहता है — issue को fix करता है, फिर finish करने का दोबारा attempt करता है। आपको कोई interruption दिखाई नहीं देता। | +| Codex | Same agent loop, immediately | Claude के समान। | +| GitHub Copilot CLI | Same agent loop, immediately | Claude के समान (Copilot के `{decision:"block", reason}` retry channel का उपयोग करता है — Copilot CLI 1.0.41 के विरुद्ध empirically verified)। | +| Cursor Agent | Same agent loop, immediately | Claude के समान (Cursor के `{followup_message}` channel का उपयोग करता है — `loop_limit` द्वारा capped, default 5 retries)। | +| Gemini CLI | Same agent loop, immediately | Claude के समान (Gemini के `{decision:"block", reason}` channel का उपयोग करता है `AfterAgent` पर)। | +| OpenCode | Same agent loop, immediately | Claude के समान (OpenCode के `client.session.prompt(...)` SDK call का उपयोग करता है `hookSpecificOutput.additionalContext` के through routed)। | +| **Pi (pi-coding-agent)** | **Next user turn** | **Pi visibly stops** जब gate fires — इसका agent loop exit होता है और आपको prompt में वापस किया जाता है। Gate फिर next time fires जब आप एक prompt submit करते हैं: failproofai एक `MANDATORY ACTION REQUIRED` directive को उस turn के system prompt में prepend करता है, LLM को instruct करते हुए workflow step (commit, push, आदि) को complete करने के लिए आप जो माँगते हैं उससे पहले। | -**Pi limitation।** Pi का `AgentEndEvent` (Claude's `Stop` hook का upstream equivalent) का कोई Result type नहीं है — जिस time it fires तक, Pi का agent loop पहले ही exit हो चुका है। Pi को force नहीं किया जा सकता same loop को retry करने के लिए उसी तरह जैसे Claude / Copilot / Cursor / Gemini / OpenCode को कर सकते हैं। failproofai gate को Pi's `before_agent_start` event में shift करता है (जो next user prompt के बाद fires) ताकि workflow check अभी भी enforce हो, बस current one की बजाय next turn पर। +**Pi limitation.** Pi के `AgentEndEvent` (Claude के `Stop` hook के upstream equivalent) के पास कोई Result type नहीं है — जब यह fires, Pi के agent loop पहले ही exit हो चुका है। Pi को Claude / Copilot / Cursor / Gemini / OpenCode के तरीके से same loop को retry के लिए force नहीं किया जा सकता। failproofai gate को Pi के `before_agent_start` event में shift करता है (जो next user prompt के बाद fires) ताकि workflow check अभी भी enforce हो, बस next turn पर current के बजाय। -**What this means in practice:** +**इसका व्यावहारिक मतलब क्या है:** -- Pi के stop करने के बाद, deny reason को in-memory capture किया जाता है keyed by Pi session id। बिल्कुल next prompt जो आप same Pi process में submit करते हैं वह इसे drains करता है: LLM को अपने system prompt के top पर `MANDATORY ACTION REQUIRED` directive दिखाई देता है, commits (या pushes / PR को open करता है / CI की wait करता है), और केवल तब आपकी request के साथ continue करता है। Captured deny reason one-shot है — एक बार drain होने के बाद, gate clear है। -- Gate Pi की process lifetime से bounded है। अगर आप Pi को `Ctrl+C` करते हैं या turns के बीच quit करते हैं, तो in-memory entry को process के साथ drop किया जाता है और gate को miss किया जाता है। Claude, Copilot, Cursor, Gemini, और OpenCode की same bound है (agent को kill करो और gate miss हो जाता है) — Pi सिर्फ इसे अधिक visible बनाता है क्योंकि agent visibly exit करता है gate के fire होने से पहले। -- एक pending deny को भी किसी भी reason (`new` / `resume` / `fork` / `quit`) से `session_shutdown` पर clear किया जाता है, इसलिए एक stale gate एक prior session से same Pi process में start किए गए fresh session में leak नहीं कर सकता। +- Pi stop करने के बाद, deny reason को in-memory में Pi session id द्वारा keyed capture किया जाता है। बिल्कुल next prompt आप same Pi process में submit करते हैं drains it: LLM को अपने system prompt के top में `MANDATORY ACTION REQUIRED` directive दिखाई देता है, commit करता है (या push / PR खोलता है / CI wait करता है), और फिर ही आपके request के साथ continue करता है। Captured deny reason एक one-shot है — एक बार drain होने के बाद, gate clear है। +- Gate Pi के process lifetime द्वारा bounded है। यदि आप Pi को `Ctrl+C` करते हैं या turns के बीच quit करते हैं, in-memory entry process के साथ drop हो जाता है और gate miss हो जाता है। Claude, Copilot, Cursor, Gemini, और OpenCode के पास same bound है (एजेंट को kill करो और gate miss हो जाता है) — Pi बस इसे अधिक visible बनाता है क्योंकि एजेंट visibly exit होता है gate firing से पहले। +- Pending deny भी `session_shutdown` पर किसी भी कारण के लिए clear किया जाता है (`new` / `resume` / `fork` / `quit`), तो prior session से एक stale gate same Pi process में started fresh session में leak नहीं हो सकता। -अगर आपको Claude-style same-loop retry की जरूरत है, तो अपनी `Stop` policies को किसी अन्य छः supported CLIs के under run करें। हम Pi upstream को track कर रहे हैं future के लिए एक Result type के साथ `AgentEndEvent` पर जो हमें इस gap को close करने देगा। +यदि आपको Claude-style same-loop retry चाहिए, run अपनी `Stop` नीतियों के अंतर्गत किसी और छः supported CLIs के। हम Pi upstream को track कर रहे हैं एक future Result type के लिए `AgentEndEvent` पर जो हमें इस gap को close करने देगा। ### `require-commit-before-stop` -**Event:** Stop -**Default:** Stopping को deny करता है जब uncommitted changes हों (modified, staged, या untracked files)। Working directory clean होने पर एक informational message return करता है। +**ईवेंट:** Stop +**डिफ़ॉल्ट:** Stopping को deny करता है जब uncommitted changes हों (modified, staged, या untracked files)। Informational message return करता है जब working directory clean हो। -कोई parameters नहीं। +कोई पैरामीटर नहीं। --- ### `require-push-before-stop` -**Event:** Stop -**Default:** Stopping को deny करता है जब unpushed commits हों या जब current branch का कोई remote tracking branch न हो। Suggest करता है `git push -u` एक tracking branch create करने के लिए अगर needed है। अगर कोई remote configured न हो तो fail open करता है। +**ईवेंट:** Stop +**डिफ़ॉल्ट:** Stopping को deny करता है जब unpushed commits हों या जब current branch के पास कोई remote tracking branch नहीं हो। Suggest करता है `git push -u` tracking branch create करने के लिए यदि आवश्यक हो। Fails open यदि कोई remote configured नहीं है। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | Remote name जिसे push करना है। | +| `remote` | `string` | `"origin"` | Remote name जिसे push करें। | -**Example:** +**उदाहरण:** ```json { @@ -765,59 +765,59 @@ Stop enforcement सातों supported CLIs में slightly अलग द ### `require-pr-before-stop` -**Event:** Stop -**Default:** Stopping को deny करता है जब current branch के लिए कोई pull request न exist करे, या जब existing PR को बिना merge किए close किया गया हो। Claude को `gh pr create` के साथ एक PR create करने के लिए instruct करता है। जब PR को **merge** किया जाता है, तो policy allow करती है (work ship हो गया है) और message एक hint देता है branch को switch करने के लिए (`git checkout main && git pull`)। +**ईवेंट:** Stop +**डिफ़ॉल्ट:** Stopping को deny करता है जब current branch के लिए कोई pull request exist न हो, या जब existing PR merge किए बिना closed हो। Instruct करता है Claude को `gh pr create` के साथ PR create करने के लिए। जब PR **merged** हो, नीति allow करती है (काम ship हो गया है) और message hint देता है branch को switch करने के लिए (`git checkout main && git pull`)। -कोई parameters नहीं। +कोई पैरामीटर नहीं। -इस policy को [GitHub CLI](https://cli.github.com/) (`gh`) को installed और authenticated होने की जरूरत है। -`gh auth login` को एक personal access token के साथ run करें जिसके पास pull requests को read access करने के लिए `repo` scope है। अगर `gh` installed न हो या authenticated न हो, तो policy fail open करती है और reason को Claude को report करती है। +इस नीति के लिए [GitHub CLI](https://cli.github.com/) (`gh`) को installed और authenticated होना आवश्यक है। +एक personal access token के साथ `gh auth login` चलाएँ जिसके पास `repo` scope हो pull requests में read access के लिए। यदि `gh` installed नहीं है या authenticated नहीं है, तो नीति fail open होती है और Claude को reason report करती है। --- ### `require-no-conflicts-before-stop` -**Event:** Stop -**Default:** Stopping को deny करता है जब current branch को cleanly base branch में merge न किया जा सके। Policy पहले confirm करती है कि GitHub पर branch के लिए एक `OPEN` PR है — बिना एक के, कोई merge target नहीं है enforcement के लिए, इसलिए entire policy short-circuits to allow। एक बार `OPEN` PR confirm हो जाने के बाद, दो independent probes run करते हैं: +**ईवेंट:** Stop +**डिफ़ॉल्ट:** Stopping को deny करता है जब current branch base branch में cleanly merge न हो सकता हो। नीति पहले confirm करती है कि एक `OPEN` PR GitHub पर branch के लिए exist करता है — बिना उसके, कोई merge target नहीं है enforce करने के लिए, तो पूरी नीति short-circuit करके allow होती है। एक बार `OPEN` PR confirm होने के बाद, दो independent probes चलते हैं: -1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`। Conflict पर, deny message conflicted files को name करता है ताकि Claude को exactly पता हो क्या resolve करना है। -2. **GitHub** — `gh pr view --json mergeable,state` result को reuse करता है पहले से fetched। Conflicts को catch करता है जो एक stale local `origin/` को miss करने दे सकते हैं (जैसे कोई `main` पर एक conflicting PR land करने के बाद since last fetch)। एक `CONFLICTING` result deny करता है। एक `UNKNOWN` result भी deny करता है और Claude को ~10 seconds wait करने और फिर से check करने से पहले stop attempt करने से पहले instruct करता है — यह same-loop false negatives को prevent करता है जबकि GitHub recompute करता है। +1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`। Conflict पर, deny message conflicted files को name करता है ताकि Claude को पता चले कि क्या resolve करना है। +2. **GitHub** — `gh pr view --json mergeable,state` result को reuse करता है पहले से ही precheck में fetch किया गया। Conflicts को catch करता है जो एक stale local `origin/` को miss करेगा (उदाहरण के लिए कोई last fetch के बाद `main` पर एक conflicting PR land करता है)। एक `CONFLICTING` result deny करता है। एक `UNKNOWN` result भी deny करता है और Claude को instruct करता है ~10 seconds wait करने और re-check करने के लिए stop attempt करने से पहले — यह false negatives को रोकता है जबकि GitHub recompute करता है। -Entirely skip करता है (allow करता है) जब: `gh` installed न हो, branch के लिए कोई PR न exist करे, PR का state `OPEN` न हो (जैसे `MERGED`, `CLOSED`), या `gh pr view` unparseable output return करे। भी fail open करता है जब `origin/` locally missing हो या जब कोई commits base से ahead न हों — वे Layer 1 fall-throughs अभी भी cached PR mergeability consult करते हैं allow करने से पहले। +Entirely skip (allow) करता है जब: `gh` installed नहीं है, branch के लिए कोई PR exist नहीं है, PR की state `OPEN` नहीं है (उदाहरण के लिए `MERGED`, `CLOSED`), या `gh pr view` unparseable output return करता है। भी fail open करता है जब `origin/` locally missing है या जब कोई commits base से ahead नहीं हैं — वे Layer 1 fall-throughs अभी भी cached PR mergeability को consult करते हैं allow करने से पहले। -**Parameters:** +**पैरामीटर:** -| Param | Type | Default | Description | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Base branch को conflicts के लिए check करने के लिए। | +| `baseBranch` | `string` | `"main"` | Base branch जिसके विरुद्ध conflicts को check करें। | -इस policy के लिए GitHub CLI (`gh`) required है। Policy एक `OPEN` PR को confirm करने के लिए `gh pr view` का use करती है exist करता है कोई conflict probe run करने से पहले — बिना `gh` के, policy short-circuits to allow करती है। `gh auth login` को एक personal access token के साथ run करें जिसके पास pull requests को read access करने के लिए `repo` scope है। +GitHub CLI (`gh`) इस नीति के लिए आवश्यक है। नीति `gh pr view` का उपयोग करता है confirm करने के लिए कि branch के लिए एक `OPEN` PR exist करता है किसी भी conflict probe को चलाने से पहले — बिना `gh` के, नीति short-circuit करके allow करती है। Pull requests में read access के लिए `repo` scope के साथ personal access token के साथ `gh auth login` चलाएँ। --- ### `require-ci-green-before-stop` -**Event:** Stop -**Default:** Stopping को deny करता है जब CI checks fail हों या current branch पर अभी भी run हो रहे हों। दोनों GitHub Actions workflow runs और third-party bot checks को check करता है (जैसे CodeRabbit, SonarCloud, Codecov)। `skipped`, `cancelled`, और `neutral` conclusions को non-failing के रूप में treat करता है (latter example covers जैसे Socket Security alerts on outside contributor PRs, जहाँ app intentionally `neutral` report करता है बजाय success/failure के)। जब सभी checks pass करते हैं एक informational message return करता है। +**ईवेंट:** Stop +**डिफ़ॉल्ट:** Stopping को deny करता है जब CI checks failing या अभी चल रही हों current branch पर। दोनों GitHub Actions workflow runs और third-party bot checks को check करता है (उदाहरण के लिए CodeRabbit, SonarCloud, Codecov)। `skipped`, `cancelled`, और `neutral` conclusions को non-failing के रूप में treat करता है (latter उदाहरण के लिए Socket Security alerts को outside contributor PRs पर cover करता है, जहाँ app intentionally neutral report करता है success/failure के बजाय)। Informational message return करता है जब सभी checks pass करते हैं। -कोई parameters नहीं। +कोई पैरामीटर नहीं। -इस policy को [GitHub CLI](https://cli.github.com/) (`gh`) को installed और authenticated होने की जरूरत है। -`gh auth login` को एक personal access token के साथ run करें जिसके पास `repo` scope है Actions workflow runs और Checks API को read access करने के लिए। अगर `gh` installed न हो या authenticated न हो, तो policy fail open करती है और reason को Claude को report करती है। +यह नीति [GitHub CLI](https://cli.github.com/) (`gh`) को installed और authenticated होना आवश्यक करती है। +Actions workflow runs और Checks API में read access के लिए `repo` scope के साथ personal access token के साथ `gh auth login` चलाएँ। यदि `gh` installed नहीं है या authenticated नहीं है, तो नीति fail open होती है और Claude को reason report करती है। --- --- -## Disabling individual policies +## व्यक्तिगत नीतियों को disable करना -अपने config में `enabledPolicies` से एक specific policy को remove करें, या dashboard के Policies tab में इसे toggle off करें। +अपने कॉन्फ़िग में `enabledPolicies` से एक विशिष्ट नीति को remove करें, या dashboard के Policies tab में इसे toggle off करें। ```json { @@ -828,4 +828,4 @@ Entirely skip करता है (allow करता है) जब: `gh` insta } ``` -Policies जो `enabledPolicies` में listed न हों, run नहीं करती, भले ही `policyParams` entries उनके लिए exist करें। \ No newline at end of file +नीतियाँ जो `enabledPolicies` में listed नहीं हैं run नहीं होती, भले ही `policyParams` entries उनके लिए exist करें। \ No newline at end of file diff --git a/docs/hi/cli/audit.mdx b/docs/hi/cli/audit.mdx index cc83921c..8bbfbf96 100644 --- a/docs/hi/cli/audit.mdx +++ b/docs/hi/cli/audit.mdx @@ -1,22 +1,23 @@ --- -title: पिछले सेशन ऑडिट करें (बीटा) -description: "पिछले ट्रांसक्रिप्ट्स में देखें कि एजेंट कितनी बार बेकार या जोखिम भरे काम करता था" +--- +title: गत सत्रों का ऑडिट (beta) +description: "पिछले ट्रांसक्रिप्ट्स में एजेंट द्वारा कितनी बार अपव्यय या जोखिम भरे काम किए गए, इसकी गणना करें" --- - **बीटा फीचर।** ऑडिट बीटा के रूप में शिप किया जा रहा है जबकि हम शुरुआती फीडबैक एकत्र करते हैं। - डिटेक्टर कैटलॉग और रिपोर्ट फॉर्मेट अगले स्थिर संस्करण से पहले बदल सकते हैं। कृपया एक issue खोलें यदि कुछ गलत लगे। + **बीटा फीचर।** ऑडिट बीटा के रूप में भेजा जा रहा है जबकि हम प्रारंभिक फीडबैक एकत्र कर रहे हैं। + डिटेक्टर कैटलॉग और रिपोर्ट फॉर्मेट अगले स्थिर संस्करण से पहले बदल सकते हैं। यदि कुछ गलत लगे तो कृपया एक issue खोलें। -ऑडिट आपके पिछले एजेंट-CLI ट्रांसक्रिप्ट्स को failproofai के policy इंजन के माध्यम से फिर से चलाता है और **`/audit` डैशबोर्ड पेज** पर एक साझा, विजुअल रिपोर्ट प्रदान करता है — आपके एजेंट का आर्कटाइप, एक 0–100 स्कोर, और बिल्कुल कौन सी पॉलिसीज क्या पकड़ सकती थीं। +ऑडिट आपके पिछले एजेंट-CLI ट्रांसक्रिप्ट्स को failproofai की policy इंजन के माध्यम से फिर से चलाता है और **`/audit` डैशबोर्ड पेज** पर एक साझा करने योग्य, विजुअल रिपोर्ट प्रस्तुत करता है — आपके एजेंट की आर्केटाइप, एक 0–100 स्कोर, और बिल्कुल यह कि कौन-सी policies क्या पकड़ी होती। ## इसे चलाएं -तीन तरीके — सभी एक जैसी `/audit` रिपोर्ट पर पहुंचते हैं। +तीन तरीके हैं — सभी एक ही `/audit` रिपोर्ट पर पहुंचते हैं। -```bash npx (इंस्टॉल न करें) +```bash npx (कोई इंस्टॉल नहीं) npx -y failproofai audit ``` @@ -31,57 +32,57 @@ failproofai - - `npx -y failproofai audit` failproofai को फेच करता है, स्कैन चलाता है, और आपके लिए डैशबोर्ड खोलता है — पहले कुछ भी इंस्टॉल करने की जरूरत नहीं है। + + `npx -y failproofai audit` failproofai को फेच करता है, स्कैन चलाता है, और आपके लिए डैशबोर्ड खोलता है — पहले कुछ इंस्टॉल करने की जरूरत नहीं। - `failproofai audit` आपके टर्मिनल में स्कैन चलाता है, फिर जब यह समाप्त हो तो स्वचालित रूप से `localhost:8020/audit` खोलता है। + `failproofai audit` आपके टर्मिनल में स्कैन चलाता है, फिर समाप्त होने पर `localhost:8020/audit` को स्वचालित रूप से खोलता है। - `failproofai` चलाएं और नेवबार में **Audit** पर क्लिक करें (Policies और Projects के बीच), या सीधे `/audit` खोलें। + `failproofai` चलाएं और navbar में **Audit** पर क्लिक करें (Policies और Projects के बीच), या सीधे `/audit` खोलें। - उपयोग देखने के लिए `failproofai audit -h` (या `--help`) चलाएं। ऑडिट **पूरी तरह ऑफलाइन** चलता है — कोई अकाउंट या नेटवर्क आवश्यक नहीं है — और डैशबोर्ड तब तक सेवा प्रदान करता रहता है जब तक आप इसे `Ctrl+C` से नहीं रोकते। + उपयोग देखने के लिए `failproofai audit -h` (या `--help`) चलाएं। ऑडिट **पूरी तरह ऑफलाइन** चलता है — कोई खाता या नेटवर्क आवश्यक नहीं — और डैशबोर्ड तब तक सेवा देता रहता है जब तक आप इसे `Ctrl+C` से रोक न दें। -डैशबोर्ड इस मशीन पर पिछले एजेंट CLI ट्रांसक्रिप्ट्स को स्कैन करता है (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) और रिपोर्ट करता है कि एजेंट कितनी बार ऐसी चीजें करता था जिन्हें failproofai रोकने के लिए बनाया गया है — env-var चेक्स, force pushes, अनावश्यक `cd ` प्रीफिक्स, sleep-polling loops, बस अभी edit की गई फाइलों को दोबारा पढ़ना, और अधिक। +डैशबोर्ड इस मशीन पर पिछले एजेंट CLI ट्रांसक्रिप्ट्स को स्कैन करता है (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) और रिपोर्ट करता है कि एजेंट ने कितनी बार ऐसी चीजें कीं जिन्हें रोकने के लिए failproofai बनाया गया है — env-var चेक, force push, अनावश्यक `cd ` प्रिफिक्स, sleep-polling लूप, अभी-अभी edited फाइलें दोबारा पढ़ना, और अन्य। -प्रत्येक ट्रांसक्रिप्ट के लिए, हर tool-use इवेंट को 39 बिल्ट-इन पॉलिसीज **और** 8 ऑडिट-केवल डिटेक्टर्स के माध्यम से दोबारा चलाया जाता है जो रनटाइम पॉलिसीज द्वारा अभी तक कवर न किए गए पैटर्न को पकड़ते हैं। गिनती को सभी सेशन्स में प्रति पॉलिसी / डिटेक्टर एकत्र किया जाता है। +प्रत्येक ट्रांसक्रिप्ट के लिए, हर tool-use इवेंट 39 builtin policies के माध्यम से **और** 8 audit-only डिटेक्टर्स के माध्यम से फिर से चलाया जाता है जो ऐसे पैटर्न को पकड़ते हैं जो अभी तक runtime policies द्वारा कवर नहीं हैं। गिनती सभी सत्रों में प्रति policy/डिटेक्टर एकत्र की जाती है। ## आप क्या पाते हैं -`/audit` पेज एक सिंगल-स्क्रीन, साझा **पोस्टर** है जिसके बाद चार नीचे-के-गुंजन सेक्शन हैं: +`/audit` पेज एक एकल-स्क्रीन, साझा करने योग्य **पोस्टर** है जिसके बाद चार नीचे-फोल्ड अनुभाग हैं: -1. **पोस्टर** — एक नज़र में आपके एजेंट की पहचान: इसका **आर्कटाइप** (8 में से एक — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), इसके व्यक्तित्व कीवर्ड्स, वह आर्कटाइप कितना दुर्लभ है, और एक **0–100 स्कोर** एक टियर बैंड के साथ (`S` नीचे `bottom tier` तक)। साझा करने के लिए बनाया गया — X या LinkedIn पर पोस्ट करें, या इसे PNG के रूप में डाउनलोड करें। -2. **`// strengths`** — आपके एजेंट पहले से क्या अच्छी तरह करते हैं, स्कैन से वास्तविक संख्याओं के रूप में (उदा. clean-tool-call %, `0` push-to-main प्रयास), केवल जहां प्रासंगिक पॉलिसी का एक स्वच्छ रिकॉर्ड है। -3. **`// quirks`** — जो छूट गया: failproofai पकड़ सकता था ऐसे व्यवहारों की रैंक की गई तालिका — *कब* यह अंतिम बार हुआ, *क्या छूटा* (और बिल्ट-इन जो इसे ब्लॉक कर सकता था), इसकी *गंभीरता*, और कितनी बार यह *देखा गया* (`new` / `recurring` / `N× seen`)। -4. **`// how to improve`** — प्रस्तावित फिक्स सूची: एक पंक्ति प्रति पॉलिसी कॉपी-पेस्ट `failproofai policy add ` के साथ, प्लस एक **सभी को इंस्टॉल करें** बटन जो हर सिफारिश को एक बार सक्षम करता है और आपके **प्रोजेक्टेड स्कोर** दिखाता है यदि आप ऐसा करते। -5. **`// come back better`** — आदत बनाएं: एक पुनः-ऑडिट ईमेल **रिमाइंडर** सेट करें (`3d` / `7d` / `14d` / `30d`) या अभी पुनः-ऑडिट करें, और **एक दोस्त को आमंत्रित करें** अपना स्वयं का ऑडिट चलाने के लिए (failproof.ai से भेजा गया, आपको Cc किया गया)। रिमाइंडर्स और आमंत्रण साइन-इन की आवश्यकता है — [`failproofai auth`](/hi/cli/auth) देखें। +1. **पोस्टर** — एक नजर में आपके एजेंट की पहचान: इसकी **archetype** (8 में से एक — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), इसके persona keywords, वह archetype कितनी दुर्लभ है, और एक **0–100 स्कोर** with a tier band (`S` से `bottom tier`)। साझा करने के लिए बनाया गया — X या LinkedIn पर पोस्ट करें, या इसे PNG के रूप में डाउनलोड करें। +2. **`// strengths`** — स्कैन से वास्तविक संख्याओं के रूप में आपका एजेंट पहले से क्या अच्छा करता है (जैसे clean-tool-call %, `0` push-to-main प्रयास), केवल तब दिखाया जाता है जब संबंधित policy का स्वच्छ रिकॉर्ड हो। +3. **`// quirks`** — जो फिसल गया: failproofai के पकड़े गए व्यवहारों की एक ranked तालिका — *यह कब* अंतिम बार हुआ, *क्या फिसल गया* (और जो builtin इसे ब्लॉक कर देता), इसकी *severity*, और यह कितनी बार *देखा गया* (`new` / `recurring` / `N× seen`)। +4. **`// how to improve`** — निर्धारित फिक्स सूची: प्रति policy एक पंक्ति copy-paste `failproofai policy add ` के साथ, प्लस एक **install all** बटन जो हर recommendation को एक ही समय में सक्षम करता है और आपका **projected score** दिखाता है यदि आप करें। +5. **`// come back better`** — आदत बनाएं: एक re-audit ईमेल **reminder** सेट करें (`3d` / `7d` / `14d` / `30d`) या अभी फिर से ऑडिट करें, और **एक मित्र को आमंत्रित करें** अपना स्वयं का ऑडिट चलाने के लिए (failproof.ai से भेजा जाता है, आपको Cc किया जाता है)। Reminders और invites को साइन-इन की आवश्यकता है — [`failproofai auth`](/hi/cli/auth) देखें। -## ऑडिट-केवल डिटेक्टर्स +## Audit-only डिटेक्टर्स -ये बेवकूफाना व्यवहार पैटर्न का पता लगाते हैं जो (अभी तक) वास्तविक समय में लागू नहीं किए जाते हैं। वे केवल ऑडिट के दौरान चलते हैं और कभी भी लाइव tool कॉल को ब्लॉक नहीं करते। +ये "stupid behavior" पैटर्न को डिटेक्ट करते हैं जो (अभी तक) रीयल टाइम में enforce नहीं किए जाते हैं। वे केवल ऑडिट के दौरान चलते हैं और कभी live tool call को ब्लॉक नहीं करते हैं। | डिटेक्टर | यह क्या गिनता है | |---|---| -| `redundant-cd-cwd` | Bash कमांड्स जो `cd && …` से शुरू होती हैं भले ही कमांड्स पहले से ही `cwd` में चलती हैं। | -| `prefer-edit-over-read-cat` | एक एकल स्रोत फाइल पर `cat`/`head`/`tail`/`less`/`more` — `Read` टूल का उपयोग करें। | -| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` स्थान पर संपादन — `Edit` टूल का उपयोग करें। | -| `prefer-write-over-heredoc` | फाइलें लिखने वाली Heredoc / बहु-लाइन `echo > file` — `Write` टूल का उपयोग करें। | -| `sleep-polling-loop` | लंबी `sleep N` (≥ 30s) या `while …; sleep …; done` polling loops। | -| `find-from-root` | `find /`, `find /home`, `find /usr`, आदि। — `cwd` के लिए स्कोप करें। | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, हुक्स को छोड़कर। | -| `reread-after-edit` | एक फाइल का `Read` जो सेम सेशन में अभी `Edit`/`Write` था। | +| `redundant-cd-cwd` | `cd && …` से शुरू होने वाली Bash commands भले ही commands पहले से ही `cwd` में चलती हों। | +| `prefer-edit-over-read-cat` | एक एकल source फाइल पर `cat`/`head`/`tail`/`less`/`more` — `Read` tool का उपयोग करें। | +| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` in-place edits — `Edit` tool का उपयोग करें। | +| `prefer-write-over-heredoc` | फाइलें लिखने के लिए Heredoc / multi-line `echo > file` — `Write` tool का उपयोग करें। | +| `sleep-polling-loop` | लंबा `sleep N` (≥ 30s) या `while …; sleep …; done` polling लूप। | +| `find-from-root` | `find /`, `find /home`, `find /usr`, आदि — `cwd` तक स्कोप करें। | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, hooks को छोड़ते हुए। | +| `reread-after-edit` | एक फाइल का `Read` जो उसी सत्र में अभी-अभी `Edit`/`Write` हुई थी। | ## कैशेस -- **प्रति-ट्रांसक्रिप्ट कैश** `~/.failproofai/cache/audit/.json` पर `(mtime, size, engineVersion, detectorVersion)` द्वारा कुंजीकृत — स्वचालित रूप से अमान्य हो जाता है जब ट्रांसक्रिप्ट या पॉलिसी/डिटेक्टर कोड बदलता है। प्रत्येक प्रविष्टि एक `cachedAt` टाइमस्टैम्प भी स्टोर करती है **TTL मेटाडेटा** के रूप में (कैश कुंजी का हिस्सा नहीं); **7 दिन** से पुरानी प्रविष्टियों को पढ़ने पर अस्वीकार किया जाता है ताकि लंबे समय तक चलने वाले परिणाम विकसित होने वाले डिटेक्टर इरादे को आगे न जाएं। -- **पूर्ण-परिणाम कैश** `~/.failproofai/audit-dashboard.json` पर (मोड 0600)। डैशबोर्ड को पुनः-चलाए बिना नेविगेशन पर तुरंत रेंडर करने देता है। **7-दिन TTL** के बाद पढ़ने पर भी अस्वीकार किया जाता है — `/audit` फिर अपनी खाली स्थिति पर गिरता है और एक नया चलाने के लिए संकेत देता है। रिपोर्ट के निचले भाग के पास `[ re-audit now ]` पर क्लिक करें ताज़ा करने के लिए — re-audit `noCache: true` भेजता है, इसलिए यह प्रति-ट्रांसक्रिप्ट कैश को बायपास करता है और कैश किए गए परिणाम को लौटाने के बजाय हर ट्रांसक्रिप्ट को दोबारा स्कैन करता है; चलाना एक स्टिकी शीर्ष पट्टी के माध्यम से प्रगति स्ट्रीम करता है और सफलता पर परिणाम को स्थान पर स्वैप करता है (कोई पेज रीलोड नहीं; एक विफल पुनः-ऑडिट पिछली रिपोर्ट रखता है)। +- **Per-transcript कैश** `~/.failproofai/cache/audit/.json` पर `(mtime, size, engineVersion, detectorVersion)` द्वारा keyed — जब ट्रांसक्रिप्ट या policy/detector कोड बदलता है तो स्वचालित रूप से invalidate होता है। प्रत्येक entry एक `cachedAt` timestamp को **TTL metadata** के रूप में भी स्टोर करता है (कैश key का भाग नहीं); **7 दिन** से पुरानी entries को पढ़ते समय अस्वीकार किया जाता है ताकि लंबे समय तक रहने वाले परिणाम विकसित होने वाले detector intent को पार न करें। +- **Whole-result कैश** `~/.failproofai/audit-dashboard.json` पर (mode 0600)। डैशबोर्ड को re-running के बिना navigation पर तुरंत प्रस्तुत करने देता है। **7-day TTL** के बाद भी पढ़ते समय अस्वीकार किया जाता है — `/audit` तब इसकी empty state में गिरता है और एक fresh run को प्रेरित करता है। रिपोर्ट के नीचे के पास `[ re-audit now ]` पर क्लिक करें refresh के लिए — re-audit `noCache: true` भेजता है, इसलिए यह per-transcript कैश को बाईपास करता है और cached result देने के बजाय हर ट्रांसक्रिप्ट को फिर से स्कैन करता है; run एक sticky top strip के माध्यम से progress स्ट्रीम करता है और success पर परिणाम को जगह में स्वैप करता है (कोई page reload नहीं; एक failed re-audit पिछली रिपोर्ट को रखता है)। ## नोट्स -- **कोई परिवर्तन नहीं।** ऑडिट केवल-पढ़ने मोड में फिर से चलता है। `warn-repeated-tool-calls` को छोड़ दिया जाता है क्योंकि इसका प्रति-सेशन साइडकार अन्यथा संशोधित होगा। -- **वर्कफ्लो पॉलिसीज छोड़ी गई।** `require-*-before-stop` पॉलिसीज केवल `Stop` इवेंट्स और लाइव गिट स्थिति के विरुद्ध `execSync` पर फायर करती हैं — उनका कोई सार्थक 2025 में क्या हुआ होता की व्याख्या नहीं है, इसलिए वे ऑडिट गिनती में दिखाई नहीं देते हैं। -- **कस्टम पॉलिसीज छोड़ी गई।** यूजर-आपूर्ति कस्टम हुक्स को फिर से नहीं चलाया जाता (वे मूल सेशन के बाद से बदल गए हो सकते हैं)। \ No newline at end of file +- **कोई mutation नहीं।** ऑडिट read-only mode में फिर से चलता है। `warn-repeated-tool-calls` को छोड़ दिया जाता है क्योंकि इसका per-session sidecar अन्यथा modify हो जाएगा। +- **Workflow policies छोड़ दिए जाते हैं।** `require-*-before-stop` policies केवल `Stop` events और live git state के विरुद्ध `execSync` पर fire होती हैं — इनका meaningful "what would have happened in 2025" interpretation नहीं है, इसलिए वे audit counts में दिखाई नहीं देते हैं। +- **Custom policies छोड़ दिए जाते हैं।** User-supplied custom hooks को फिर से चलाया नहीं जाता (वे original session के बाद से बदल सकते हैं)। \ No newline at end of file diff --git a/docs/hi/cli/auth.mdx b/docs/hi/cli/auth.mdx index b614cd80..ce01c0dd 100644 --- a/docs/hi/cli/auth.mdx +++ b/docs/hi/cli/auth.mdx @@ -1,7 +1,6 @@ --- ---- title: साइन इन करें -description: "रिमाइंडर और व्यक्तिगत सुविधाओं को सक्षम करने के लिए CLI से FailproofAI में साइन इन करें" +description: "रिमाइंडर और व्यक्तिगतकृत सुविधाएँ सक्षम करने के लिए CLI से FailproofAI में साइन इन करें" --- ```bash @@ -10,19 +9,19 @@ failproofai auth logout # revoke this session failproofai auth whoami # print the signed-in identity ``` -लीगेसी `--login` / `--logout` / `--whoami` फ्लैग फॉर्म अभी भी बैक-कम्पैट के लिए एक उपनाम के रूप में स्वीकार किया जाता है। +पुरानी `--login` / `--logout` / `--whoami` फ्लैग फॉर्म अभी भी पिछड़े संगतता के लिए एक उपनाम के रूप में स्वीकार की जाती है। -प्रमाणीकरण वैकल्पिक है। पॉलिसीज़, डैशबोर्ड, `/audit` पृष्ठ और अन्य सभी स्थानीय सुविधाएं बिल्कुल उसी तरह काम करती हैं चाहे आप साइन इन हों या न हों। लॉगिन सतह इसलिए मौजूद है ताकि जिन सुविधाओं को **स्थिर पहचान की जरूरत है** (आज फिर से ऑडिट रिमाइंडर, भविष्य में और भी अधिक) के पास लंगर डालने के लिए कहीं हो। +प्रमाणीकरण वैकल्पिक है। नीतियां, डैशबोर्ड, `/audit` पृष्ठ, और हर अन्य स्थानीय सुविधा ठीक उसी तरह काम करती है चाहे आप साइन इन हों या नहीं। लॉगिन सतह इसलिए मौजूद है ताकि जिन सुविधाओं को **एक स्थिर पहचान की आवश्यकता है** (आज पुनः-ऑडिट रिमाइंडर, भविष्य में और अधिक) के पास लंगर डालने के लिए कहीं हो। -## साइन-इन फ्लो +## साइन-इन प्रवाह ```bash failproofai auth login ``` -आपके ईमेल के लिए संकेत देता है, उस पते पर एक 6-अंकीय वन-टाइम कोड भेजता है, कोड के लिए संकेत देता है, और सफलता पर `~/.failproofai/auth.json` (मोड `0600`) लिखता है। उसी सेशन को तब इन-ऐप डैशबोर्ड में देखा जा सकता है — `/audit` पर `[ set a reminder ]` क्लिक करने से आप साइन इन दिखेंगे। +आपके ईमेल के लिए संकेत देता है, उस पते पर एक 6-अंकीय एक-बार कोड भेजता है, कोड के लिए संकेत देता है, और सफलता पर `~/.failproofai/auth.json` (मोड `0600`) लिखता है। वही सत्र तब इन-ऐप डैशबोर्ड में दिखाई देता है — `/audit` पर `[ set a reminder ]` पर क्लिक करने से आप साइन इन के रूप में दिखाई देंगे। -डैशबोर्ड उन उपयोगकर्ताओं के लिए `/audit` पर एक मोडल डायलॉग के रूप में समान फ्लो को उजागर करता है जो कभी CLI को छूते नहीं हैं। +डैशबोर्ड उन उपयोगकर्ताओं के लिए `/audit` पर एक मोडल डायलॉग के रूप में समान प्रवाह को उजागर करता है जो कभी CLI को स्पर्श नहीं करते हैं। ## साइन-आउट @@ -30,19 +29,19 @@ failproofai auth login failproofai auth logout ``` -सर्वर पर वर्तमान सेशन को रद्द करता है और `~/.failproofai/auth.json` को हटाता है। यदि api-सर्वर अप्राप्य है, तो स्थानीय फ़ाइल को वैसे भी हटा दिया जाता है — साइन आउट करने का स्थानीय इरादा हमेशा जीतता है। +सर्वर पर वर्तमान सत्र को रद्द करता है और `~/.failproofai/auth.json` को हटाता है। यदि api-server अप्राप्य है, तो स्थानीय फ़ाइल को वैसे भी हटा दिया जाता है — लॉग आउट करने का स्थानीय इरादा हमेशा जीतता है। -## पहचान जांच +## पहचान की जांच ```bash failproofai auth whoami ``` -जब एक वैध सेशन मौजूद होता है तो ` ()` प्रिंट करता है और 0 पर निकलता है, या `not signed in` प्रिंट करता है और 1 पर निकलता है। यदि एक्सेस टोकन समाप्त होने के एक मिनट के भीतर है तो पृष्ठभूमि में चुप चाप ताज़ा करता है। +जब एक वैध सत्र मौजूद हो तो ` ()` प्रिंट करता है और 0 पर बाहर निकलता है, अन्यथा `not signed in` प्रिंट करता है और 1 पर बाहर निकलता है। यदि एक्सेस टोकन समाप्त होने के एक मिनट के भीतर है तो पृष्ठभूमि में चुपचाप एक्सेस टोकन को रीफ्रेश करता है। -## स्थायी फिर से ऑडिट रिमाइंडर +## निरंतर पुनः-ऑडिट रिमाइंडर -जब आप `/audit` पृष्ठ पर **`[ set a reminder ]`** क्लिक करते हैं (या मोडल के माध्यम से साइन इन करते हैं जो बटन गेट्स पर), डैशबोर्ड `~/.failproofai/next-audit.json` पर एक छोटी साथी फ़ाइल लिखता है: +जब आप `/audit` पृष्ठ पर **`[ set a reminder ]`** पर क्लिक करते हैं (या मोडल के माध्यम से साइन इन करते हैं जो बटन गेट्स को करता है), डैशबोर्ड `~/.failproofai/next-audit.json` पर एक छोटी साथी फ़ाइल लिखता है: ```json { @@ -52,9 +51,9 @@ failproofai auth whoami } ``` -यह फ़ाइल उस ईमेल के लिए स्कोप की गई है जिसके लिए इसे सेट किया गया था — CLI सेशन को एक अलग खाते में स्विच करने से पिछले उपयोगकर्ता के संबंधित कोई भी रिमाइंडर छिप जाता है। डिफ़ॉल्ट ऑफसेट **7 दिन** है, स्केड्यूलर आने पर बाद में कॉन्फ़िगर करने योग्य। `auth.json` की तरह `0600` परमिशन के साथ बनाया गया। +यह फ़ाइल उस ईमेल के लिए स्कोप की गई है जिसके लिए इसे सेट किया गया था — CLI सत्र को एक अलग खाते में स्विच करने से पिछले उपयोगकर्ता से संबंधित किसी भी रिमाइंडर को छिपाया जाता है। डिफ़ॉल्ट ऑफसेट **7 दिन** है, जब शेड्यूलर उतरता है तो बाद में कॉन्फ़िगर करने योग्य। `auth.json` की तरह `0600` परमिशन के साथ बनाया गया है। -डैशबोर्ड का `/api/auth/reminder` एंडपॉइंट `GET` (पढ़ें), `POST` (सेट / रीशेड्यूल), और `DELETE` (साफ़ करें) को उजागर करता है और एक सक्रिय सेशन की आवश्यकता होती है। +डैशबोर्ड का `/api/auth/reminder` एंडपॉइंट `GET` (पढ़ना), `POST` (सेट / पुनः शेड्यूल), और `DELETE` (स्पष्ट) को उजागर करता है और एक सक्रिय सत्र की आवश्यकता है। ## `~/.failproofai/auth.json` में क्या है @@ -68,21 +67,21 @@ failproofai auth whoami } ``` -`0600` परमिशन के साथ बनाया गया (केवल मालिक पढ़ें/लिखें)। एक्सेस टोकन एक 1-घंटे का HS256 JWT है; रिफ्रेश टोकन एक अपारदर्शी 256-बिट यादृच्छिक स्ट्रिंग है जिसे सर्वर `SHA-256(token)` के रूप में स्टोर करता है। रिफ्रेश-टोकन रीप्ले सर्वर-साइड पर पहचाना जाता है और उपयोगकर्ता के लिए हर सेशन को रद्द करता है। +`0600` परमिशन के साथ बनाया गया है (केवल मालिक पढ़ने/लिखने में सक्षम)। एक्सेस टोकन एक 1-घंटे का HS256 JWT है; रीफ्रेश टोकन एक अपारदर्शी 256-बिट यादृच्छिक स्ट्रिंग है जो सर्वर `SHA-256(token)` के रूप में स्टोर करता है। रीफ्रेश-टोकन रिप्ले सर्वर-साइड पर पता लगाया जाता है और उपयोगकर्ता के लिए हर सत्र को रद्द करता है। ## पर्यावरण चर | चर | डिफ़ॉल्ट | उद्देश्य | |---|---|---| -| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | api-सर्वर बेस URL को ओवरराइड करें। स्व-होस्ट किए गए api-सर्वर के विरुद्ध स्थानीय विकास के लिए उपयोगी। | -| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | ओवरराइड करें कि `auth.json` कहाँ संग्रहीत है। मुख्यतः परीक्षणों के लिए। | +| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | api-server आधार URL को ओवरराइड करें। स्व-होस्ट किए गए api-server के विरुद्ध स्थानीय विकास के लिए उपयोगी। | +| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | ओवरराइड करें कि `auth.json` कहाँ स्टोर किया गया है। ज्यादातर परीक्षणों के लिए। | -पूर्ण सूची के लिए [पर्यावरण चर](/hi/cli/environment-variables) देखें। +पूरी सूची के लिए [पर्यावरण चर](/hi/cli/environment-variables) देखें। ## समस्या निवारण -**"Could not reach the api-server"** — CLI `FAILPROOF_API_URL` के लिए TCP कनेक्शन नहीं खोल सकता। अपने नेटवर्क की जांच करें, या यदि आप स्व-होस्ट किए गए api-सर्वर चला रहे हैं तो `FAILPROOF_API_URL` सेट करें। +**"Could not reach the api-server"** — CLI `FAILPROOF_API_URL` के लिए TCP कनेक्शन नहीं खोल सकता है। अपने नेटवर्क की जांच करें, या यदि आप एक स्व-होस्ट किए गए api-server चला रहे हैं तो `FAILPROOF_API_URL` सेट करें। -**"Rate limited"** — उस ईमेल के लिए 15 मिनट की विंडो में बहुत सारे लॉगिन प्रयास (5/email) या IP (20/IP), या उसी ईमेल के लिए पिछले अनुरोध के बाद 30-सेकंड का रीसेंड कूलडाउन। त्रुटि संदेश में सेकंड में पुनः प्रयास-बाद की विंडो शामिल होती है। +**"Rate limited"** — उस ईमेल के लिए 15-मिनट की विंडो में बहुत अधिक लॉगिन प्रयास (5/ईमेल) या IP (20/IP), या उसी ईमेल के लिए पिछले अनुरोध के बाद 30-सेकंड की पुनः भेजने की शीतलता। त्रुटि संदेश सेकंड में पुनः प्रयास-बाद की विंडो शामिल करता है। -**Code rejected** — OTP गलत था, समाप्त हो गया, या पंक्ति ने अपने 5-गलत-अनुमान लॉकआउट को हिट किया। ताज़ा कोड के लिए अनुरोध करने के लिए `failproofai auth login` चलाएं। \ No newline at end of file +**Code rejected** — OTP गलत था, समाप्त हो गया था, या पंक्ति को इसके 5-गलत-अनुमान लॉकआउट को मारा गया था। ताजा कोड का अनुरोध करने के लिए `failproofai auth login` चलाएँ। \ No newline at end of file diff --git a/docs/hi/cli/dashboard.mdx b/docs/hi/cli/dashboard.mdx index 049cb1cf..f856412b 100644 --- a/docs/hi/cli/dashboard.mdx +++ b/docs/hi/cli/dashboard.mdx @@ -14,7 +14,7 @@ failproofai | फ्लैग | विवरण | |------|-------------| | `--port ` | सुनने के लिए पोर्ट (डिफ़ॉल्ट: `8020`) | -| `--allowed-origins ` | अल्पविराम-सीमांकित होस्ट/आईपी जो डेव संसाधनों तक पहुंचने की अनुमति हैं | +| `--allowed-origins ` | अल्पविराम से अलग किए गए होस्ट/IP जो dev संसाधनों तक पहुंच की अनुमति देते हैं | डैशबोर्ड को गैर-डिफ़ॉल्ट Claude प्रोजेक्ट फ़ोल्डर पर इंगित करने के लिए, लॉन्च करते समय `CLAUDE_PROJECTS_PATH` पर्यावरण चर सेट करें। diff --git a/docs/hi/cli/environment-variables.mdx b/docs/hi/cli/environment-variables.mdx index ee2a8e5b..6b82f1fe 100644 --- a/docs/hi/cli/environment-variables.mdx +++ b/docs/hi/cli/environment-variables.mdx @@ -8,9 +8,9 @@ description: "पर्यावरण चर के साथ failproofai व | चर | विवरण | |----------|-------------| | `PORT` | डैशबोर्ड पोर्ट (डिफ़ॉल्ट: `8020`) | -| `CLAUDE_PROJECTS_PATH` | Claude Code प्रोजेक्ट फ़ोल्डर कहाँ पाए जाते हैं इसे ओवरराइड करें | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | छिपाने के लिए कॉमा-सीमांकित डैशबोर्ड पृष्ठ | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | विकास संसाधनों तक पहुँच के लिए अनुमत होस्ट/IP। `--allowed-origins` के समान। | +| `CLAUDE_PROJECTS_PATH` | Claude Code प्रोजेक्ट फ़ोल्डर्स कहाँ पाए जाते हैं, इसे ओवरराइड करें | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | छिपाने के लिए अल्पविराम से अलग डैशबोर्ड पेज | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | डेव संसाधनों तक पहुंचने की अनुमति वाले होस्ट/IP। `--allowed-origins` के समान। | ## लॉगिंग @@ -19,24 +19,24 @@ description: "पर्यावरण चर के साथ failproofai व | `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | सर्वर लॉग स्तर (डिफ़ॉल्ट: `warn`) | | `FAILPROOFAI_HOOK_LOG_FILE` | कस्टम हुक लॉग फ़ाइल पथ, या डिफ़ॉल्ट के लिए `true` (`~/.failproofai/logs/hooks.log`) | -## दूरसंचार +## टेलीमेट्री | चर | विवरण | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | अनाम उपयोग दूरसंचार को अक्षम करें | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | अनाम उपयोग टेलीमेट्री अक्षम करें | ## प्रमाणीकरण | चर | विवरण | |----------|-------------| -| `FAILPROOF_API_URL` | `failproofai auth` और डैशबोर्ड प्रमाणीकरण संवाद द्वारा उपयोग किए गए API-सर्वर बेस URL को ओवरराइड करें। डिफ़ॉल्ट `https://api.befailproof.ai` है; स्थानीय API-सर्वर चलाते समय `http://localhost:8080` (या कहीं और) पर सेट करें। | -| `FAILPROOFAI_AUTH_DIR` | ओवरराइड करें कि `auth.json` कहाँ संग्रहीत है (डिफ़ॉल्ट: `~/.failproofai`)। अलग-थलग परीक्षणों के लिए मुख्य रूप से उपयोगी। | +| `FAILPROOF_API_URL` | `failproofai auth` और डैशबोर्ड प्रमाणीकरण संवाद द्वारा उपयोग किए गए api-server बेस URL को ओवरराइड करें। डिफ़ॉल्ट `https://api.befailproof.ai` है; स्थानीय api-server चलाते समय `http://localhost:8080` (या कहीं और) पर सेट करें। | +| `FAILPROOFAI_AUTH_DIR` | `auth.json` कहाँ संग्रहीत है, इसे ओवरराइड करें (डिफ़ॉल्ट: `~/.failproofai`)। मुख्य रूप से पृथक परीक्षणों के लिए उपयोगी। | -## पहली बार प्रॉम्प्ट +## पहली बार चलाने के समय प्रॉम्प्ट | चर | विवरण | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | उस प्रॉम्प्ट को छोड़ें जो पहली बार `failproofai` को निष्पादित करने पर नीतियों को स्थापित करने की पेशकश करता है | +| `FAILPROOFAI_NO_FIRST_RUN=1` | पहली बार के प्रोग्राम इनवोकेशन पर नीतियों को स्थापित करने का प्रस्ताव देने वाले प्रॉम्प्ट को छोड़ें | ## LLM (नीति मूल्यांकन के लिए) diff --git a/docs/hi/cli/hook.mdx b/docs/hi/cli/hook.mdx index bed24113..0ebd8093 100644 --- a/docs/hi/cli/hook.mdx +++ b/docs/hi/cli/hook.mdx @@ -1,20 +1,20 @@ --- -title: हुक हैंडलर (आंतरिक) -description: "सबप्रोसेस जो Claude Code हर टूल ईवेंट पर कॉल करता है" +title: Hook हैंडलर (आंतरिक) +description: "प्रत्येक टूल ईवेंट पर subprocess Claude Code कॉल करता है" --- ```bash failproofai --hook ``` -यह वह कमांड है जो `failproofai policies --install` द्वारा Claude Code के `settings.json` में पंजीकृत की जाती है। आप आमतौर पर इसे सीधे कॉल नहीं करते। +यह वह कमांड है जो `failproofai policies --install` द्वारा Claude Code के `settings.json` में पंजीकृत की जाती है। आप आमतौर पर इसे सीधे कॉल नहीं करते हैं। stdin से एक JSON पेलोड पढ़ता है, सभी सक्षम नीतियों का मूल्यांकन करता है, और निर्णय को दर्शाने वाली एक कोड के साथ बाहर निकलता है: | Exit code | निर्णय | प्रभाव | |-----------|--------|--------| -| `0` | `allow` | कार्रवाई को अनुमति दें | -| `1` | `deny` | कार्रवाई को ब्लॉक करें - Claude को इनकार का कारण दिखता है | +| `0` | `allow` | क्रिया को अनुमति दें | +| `1` | `deny` | क्रिया को ब्लॉक करें - Claude को अस्वीकृति का कारण दिखता है | | `2` | `instruct` | Claude के संदर्भ में मार्गदर्शन इंजेक्ट करें | ### समर्थित ईवेंट प्रकार @@ -22,9 +22,9 @@ stdin से एक JSON पेलोड पढ़ता है, सभी स | श्रेणी | ईवेंट | |----------|--------| | **टूल निष्पादन** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | -| **सत्र जीवनचक्र** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | +| **सेशन जीवनचक्र** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | | **उपयोगकर्ता इंटरैक्शन** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | -| **सबएजेंट और कार्य** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | +| **उप-एजेंट और कार्य** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | | **कॉन्फ़िगरेशन** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | | **फाइल सिस्टम** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | | **संदर्भ** | `PreCompact`, `PostCompact` | \ No newline at end of file diff --git a/docs/hi/cli/install-policies.mdx b/docs/hi/cli/install-policies.mdx index 43ece8da..202d6e86 100644 --- a/docs/hi/cli/install-policies.mdx +++ b/docs/hi/cli/install-policies.mdx @@ -1,5 +1,5 @@ --- -title: policies को इंस्टॉल करें +title: policies इंस्टॉल करें description: "policies को सक्षम करें ताकि वे हर agent tool call पर चलें" --- @@ -7,51 +7,51 @@ description: "policies को सक्षम करें ताकि वे failproofai policies --install [policy-names...] [options] ``` -आपके इंस्टॉल किए गए agent CLI की सेटिंग्स फ़ाइल में hook entries लिखता है (Claude Code, OpenAI Codex, या GitHub Copilot CLI _(beta)_) ताकि failproofai tool calls को इंटरसेप्ट कर सके। +आपके इंस्टॉल किए गए agent CLI की सेटिंग्स फ़ाइल (Claude Code, OpenAI Codex, या GitHub Copilot CLI _(beta)_) में hook एंट्रीज लिखता है ताकि failproofai tool calls को इंटरसेप्ट कर सके। उपनाम: `failproofai p -i` ## विकल्प -| Flag | विवरण | +| फ़्लैग | विवरण | |------|-------------| -| `--cli claude\|codex\|copilot` | Agent CLI(s) जिसके लिए इंस्टॉल करना है; स्पेस-सेपरेटेड (जैसे `--cli claude codex copilot`) या दोहराया गया। छोड़ने के लिए इंस्टॉल किए गए CLIs का पता लगाया जाएगा और प्रॉम्प्ट किया जाएगा। | -| `--scope user` | user-scope सेटिंग्स फ़ाइल में इंस्टॉल करें (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`)। डिफ़ॉल्ट। | -| `--scope project` | project-scope सेटिंग्स फ़ाइल में इंस्टॉल करें (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`)। | -| `--scope local` | केवल Claude — `/.claude/settings.local.json` में इंस्टॉल करता है। Codex और Copilot के पास `local` scope नहीं है। | -| `--custom ` / `-c` | कस्टम hook policies वाली JS फ़ाइल का पाथ | +| `--cli claude\|codex\|copilot` | Agent CLI(s) जिनके लिए इंस्टॉल करना है; स्पेस से अलग (जैसे `--cli claude codex copilot`) या दोहराए गए। छोड़ने पर इंस्टॉल किए गए CLIs का पता लगाया जाएगा और प्रॉम्प्ट दिया जाएगा। | +| `--scope user` | यूजर-स्कोप सेटिंग्स फ़ाइल में इंस्टॉल करें (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`)। डिफ़ॉल्ट। | +| `--scope project` | प्रोजेक्ट-स्कोप सेटिंग्स फ़ाइल में इंस्टॉल करें (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`)। | +| `--scope local` | Claude केवल — `/.claude/settings.local.json` में इंस्टॉल करता है। Codex और Copilot के पास `local` स्कोप नहीं है। | +| `--custom ` / `-c` | कस्टम hook policies वाली JS फ़ाइल का पथ | ## व्यवहार - **कोई policy नाम नहीं** - policies चुनने के लिए एक इंटरैक्टिव प्रॉम्प्ट खोलता है -- **विशिष्ट नाम** - उन policies को सक्षम करता है (पहले से सक्षम किए गए किसी भी में जोड़ा जाता है) -- **`all`** - हर उपलब्ध policy को सक्षम करता है +- **विशिष्ट नाम** - उन policies को सक्षम करता है (पहले से सक्षम किए गए में जोड़ा जाता है) +- **`all`** - सभी उपलब्ध policies को सक्षम करता है -इंस्टॉलेशन जोड़ने वाला है: `--install` को फिर से चलाने से नई policies जोड़ी जाती हैं बिना मौजूदा लोगों को हटाए। +इंस्टॉलेशन योगात्मक है: `--install` को फिर से चलाने से नई policies जोड़ी जाती हैं बिना मौजूदा लोगों को हटाए। ## उदाहरण ```bash -# सभी डिफ़ॉल्ट policies को ग्लोबली इंस्टॉल करें (इंटरैक्टिव) +# सभी डिफ़ॉल्ट policies को globally इंस्टॉल करें (इंटरएक्टिव) failproofai policies --install # वर्तमान प्रोजेक्ट के लिए विशिष्ट policies इंस्टॉल करें failproofai policies --install block-sudo sanitize-api-keys --scope project -# सभी policies को एक साथ सक्षम करें +# सभी policies को एक बार में सक्षम करें failproofai policies --install all # कस्टम policies फ़ाइल के साथ इंस्टॉल करें failproofai policies --install --custom ./my-policies.js -# OpenAI Codex के लिए इंस्टॉल करें (project scope) +# OpenAI Codex के लिए इंस्टॉल करें (प्रोजेक्ट स्कोप) failproofai policies --install --cli codex --scope project -# GitHub Copilot CLI (beta) के लिए वर्तमान प्रोजेक्ट के लिए इंस्टॉल करें +# वर्तमान प्रोजेक्ट के लिए GitHub Copilot CLI (beta) के लिए इंस्टॉल करें failproofai policies --install --cli copilot --scope project -# तीनों CLIs के लिए एक साथ इंस्टॉल करें +# एक बार में तीनों CLIs के लिए इंस्टॉल करें failproofai policies --install --cli claude codex copilot ``` -जब `--custom ` प्रदान किया जाता है, तो फ़ाइल तुरंत validate की जाती है - इसे कम से कम एक बार `customPolicies.add()` को कॉल करना चाहिए। resolved path को `policies-config.json` में `customPoliciesPath` के रूप में सहेजा जाता है। \ No newline at end of file +जब `--custom ` प्रदान किया जाता है, तो फ़ाइल तुरंत सत्यापित की जाती है - इसे कम से कम एक बार `customPolicies.add()` को कॉल करना चाहिए। अनुमानित पथ `policies-config.json` में `customPoliciesPath` के रूप में सहेजा जाता है। \ No newline at end of file diff --git a/docs/hi/cli/list-policies.mdx b/docs/hi/cli/list-policies.mdx index 929b4044..730aaa59 100644 --- a/docs/hi/cli/list-policies.mdx +++ b/docs/hi/cli/list-policies.mdx @@ -1,5 +1,5 @@ --- -title: नीतियों की सूची +title: नीतियों को सूचीबद्ध करें description: "देखें कि कौन सी नीतियां सक्षम हैं, उनके पैरामीटर और कस्टम नीतियां" --- @@ -7,7 +7,7 @@ description: "देखें कि कौन सी नीतियां स failproofai policies ``` -सभी नीतियों को उनकी स्थिति, कॉन्फ़िगर किए गए पैरामीटर और कस्टम नीतियों के साथ दिखाता है। +सभी नीतियों को उनकी स्थिति, कॉन्फ़िगर किए गए पैरामीटर और कस्टम नीतियों के साथ प्रदर्शित करता है। ## नमूना आउटपुट @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -`policyParams` में अज्ञात कुंजियों को यहां फ़्लैग किया जाता है ताकि आप टाइपो को जल्दी पकड़ सकें। \ No newline at end of file +`policyParams` में अज्ञात कुंजियों को यहां फ़्लैग किया जाता है ताकि आप जल्दी टाइपो को पकड़ सकें। \ No newline at end of file diff --git a/docs/hi/cli/remove-policies.mdx b/docs/hi/cli/remove-policies.mdx index 9aa5adc9..70d77307 100644 --- a/docs/hi/cli/remove-policies.mdx +++ b/docs/hi/cli/remove-policies.mdx @@ -7,15 +7,15 @@ description: "Claude Code की सेटिंग्स से हुक ए failproofai policies --uninstall [policy-names...] [options] ``` -failproofai हुक एंट्रीज़ को Claude Code के `settings.json` से हटाता है। +Claude Code के `settings.json` से failproofai हुक एंट्रीज़ को हटाता है। उपनाम: `failproofai p -u` ## विकल्प -| फ्लैग | विवरण | +| फ़्लैग | विवरण | |------|-------------| -| `--scope user` | वैश्विक सेटिंग्स से हटाएं (डिफ़ॉल्ट) | +| `--scope user` | ग्लोबल सेटिंग्स से हटाएं (डिफ़ॉल्ट) | | `--scope project` | प्रोजेक्ट सेटिंग्स से हटाएं | | `--scope local` | स्थानीय सेटिंग्स से हटाएं | | `--scope all` | सभी स्कोप से एक साथ हटाएं | @@ -23,21 +23,21 @@ failproofai हुक एंट्रीज़ को Claude Code के `settin ## व्यवहार -- **कोई नीति का नाम नहीं** - सेटिंग्स फ़ाइल से सभी failproofai हुक एंट्रीज़ को हटाता है -- **विशिष्ट नाम** - उन नीतियों को अक्षम करता है लेकिन हुक इंस्टॉल रखता है +- **कोई नीति के नाम नहीं** - सेटिंग्स फ़ाइल से सभी failproofai हुक एंट्रीज़ को हटाता है +- **विशिष्ट नाम** - उन नीतियों को अक्षम करता है लेकिन हुक को इंस्टॉल रखता है ## उदाहरण ```bash -# सभी हुक्स को वैश्विक रूप से हटाएं +# सभी हुक को ग्लोबली हटाएं failproofai policies --uninstall # किसी विशिष्ट नीति को अक्षम करें (हुक इंस्टॉल रखता है) failproofai policies --uninstall block-sudo -# प्रत्येक स्कोप से हुक्स को हटाएं +# हर स्कोप से हुक हटाएं failproofai policies --uninstall --scope all -# कस्टम नीतियों का पथ साफ़ करें +# कस्टम नीतियों पाथ को साफ़ करें failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/hi/cli/version.mdx b/docs/hi/cli/version.mdx index 407a7e51..542cdf1a 100644 --- a/docs/hi/cli/version.mdx +++ b/docs/hi/cli/version.mdx @@ -1,6 +1,6 @@ --- title: संस्करण जांचें -description: "स्थापित failproofai संस्करण को प्रिंट करें" +description: "स्थापित failproofai संस्करण प्रिंट करें" --- ```bash @@ -9,4 +9,4 @@ failproofai --version failproofai -v ``` -स्थापित संस्करण संख्या को प्रिंट करता है। \ No newline at end of file +स्थापित संस्करण संख्या प्रिंट करता है। \ No newline at end of file diff --git a/docs/hi/configuration.mdx b/docs/hi/configuration.mdx index c7b5bea7..0f0fae5b 100644 --- a/docs/hi/configuration.mdx +++ b/docs/hi/configuration.mdx @@ -4,54 +4,54 @@ description: "कॉन्फ़िग फ़ाइल प्रारूप, icon: gear --- -failproofai JSON कॉन्फ़िगरेशन फ़ाइलों का उपयोग करता है यह नियंत्रित करने के लिए कि कौन सी नीतियां सक्रिय हैं, वे कैसे व्यवहार करती हैं, और कस्टम नीतियां कहां से लोड की जाती हैं। कॉन्फ़िगरेशन आपकी टीम के साथ साझा करना आसान बनाने के लिए डिज़ाइन किया गया है - इसे अपने रेपो में कमिट करें और हर डेवलपर को समान एजेंट सेफ्टी नेट मिलता है। +failproofai JSON कॉन्फ़िगरेशन फ़ाइलों का उपयोग करता है यह नियंत्रित करने के लिए कि कौन सी नीतियां सक्रिय हैं, वे कैसे व्यवहार करती हैं, और कहां से कस्टम नीतियां लोड की जाती हैं। कॉन्फ़िगरेशन आपकी टीम के साथ साझा करने के लिए आसान बनाया गया है - इसे अपने रेपो में कमिट करें और हर डेवलपर को एक जैसा एजेंट सेफ्टी नेट मिले। --- ## कॉन्फ़िगरेशन स्कोप -तीन कॉन्फ़िगरेशन स्कोप हैं, प्राथमिकता क्रम में मूल्यांकन किए गए: +तीन कॉन्फ़िगरेशन स्कोप हैं, जिनका मूल्यांकन प्राथमिकता क्रम में किया जाता है: -| स्कोप | फ़ाइल पथ | उद्देश्य | +| स्कोप | फ़ाइल पाथ | उद्देश्य | |-------|-----------|---------| -| **प्रोजेक्ट** | `.failproofai/policies-config.json` | प्रति-रेपो सेटिंग्स, संस्करण नियंत्रण में कमिट की गई | -| **स्थानीय** | `.failproofai/policies-config.local.json` | व्यक्तिगत प्रति-रेपो ओवरराइड, gitignored | -| **वैश्विक** | `~/.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"] 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"] ← deduplicated union ``` -**`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"] } ← project wins, global ignored ``` ```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"] } ← falls through to global ``` -**`customPoliciesPath`** - पहला स्कोप जो इसे परिभाषित करता है जीतता है। +**`customPoliciesPath`** - पहला स्कोप जो इसे परिभाषित करता है, जीत जाता है। -**`llm`** - पहला स्कोप जो इसे परिभाषित करता है जीतता है। +**`llm`** - पहला स्कोप जो इसे परिभाषित करता है, जीत जाता है। --- @@ -102,79 +102,79 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← वैश्वि प्रकार: `string[]` -सक्षम करने के लिए नीति नामों की सूची। नाम `failproofai policies` द्वारा दिखाए गए नीति पहचानकर्ताओं से बिल्कुल मेल खाने चाहिए। पूर्ण सूची के लिए [बिल्ट-इन नीतियां](/hi/built-in-policies) देखें। +सक्षम करने के लिए नीति के नाम की सूची। नाम बिल्कुल `failproofai policies` द्वारा दिखाए गए नीति पहचानकर्ता से मेल खाना चाहिए। संपूर्ण सूची के लिए [बिल्ट-इन पॉलिसीज़](/hi/built-in-policies) देखें। -`enabledPolicies` में न आने वाली नीतियां निष्क्रिय हैं, भले ही उनके पास `policyParams` में प्रविष्टियां हों। +`enabledPolicies` में नहीं होने वाली नीतियां निष्क्रिय होती हैं, भले ही उनके पास `policyParams` में प्रविष्टियां हों। ### `policyParams` प्रकार: `Record>` -प्रति-नीति पैरामीटर ओवरराइड। बाहरी कुंजी नीति का नाम है; आंतरिक कुंजियां नीति-विशिष्ट हैं। प्रत्येक नीति अपने उपलब्ध पैरामीटर्स को [बिल्ट-इन नीतियों](/hi/built-in-policies) में दस्तावेज़ करती है। +प्रति-नीति पैरामीटर ओवरराइड। बाहरी कुंजी नीति का नाम है; आंतरिक कुंजियां नीति-विशिष्ट हैं। प्रत्येक नीति [बिल्ट-इन पॉलिसीज़](/hi/built-in-policies) में अपने उपलब्ध पैरामीटर को दस्तावेज़ित करती है। -यदि किसी नीति के पैरामीटर हैं लेकिन आप उन्हें निर्दिष्ट नहीं करते हैं, तो नीति के बिल्ट-इन डिफ़ॉल्ट का उपयोग किया जाता है। जो उपयोगकर्ता `policyParams` को बिल्कुल कॉन्फ़िगर नहीं करते वे पिछले संस्करणों के समान व्यवहार प्राप्त करते हैं। +यदि किसी नीति के पैरामीटर हैं लेकिन आप उन्हें निर्दिष्ट नहीं करते, तो नीति के बिल्ट-इन डिफ़ॉल्ट का उपयोग किया जाता है। वे उपयोगकर्ता जो `policyParams` को बिल्कुल कॉन्फ़िगर नहीं करते, उन्हें पिछले संस्करणों के समान व्यवहार मिलता है। -किसी नीति के पैरामीटर ब्लॉक के अंदर अज्ञात कुंजियां हुक-फायर समय पर चुपचाप अनदेखी की जाती हैं लेकिन जब आप `failproofai policies` चलाते हैं तो चेतावनियों के रूप में फ्लैग की जाती हैं। +नीति के पैरामीटर ब्लॉक के अंदर अज्ञात कुंजियों को हुक-फायर समय पर चुप्पी से अनदेखा किया जाता है लेकिन जब आप `failproofai policies` चलाते हैं तो चेतावनियों के रूप में फ़्लैग किया जाता है। #### `hint` (क्रॉस-कटिंग) प्रकार: `string` (वैकल्पिक) -जब नीति `deny` या `instruct` देती है तो कारण में जोड़ा जाने वाला संदेश। Claude को नीति को स्वयं संशोधित किए बिना कार्यवाही योग्य मार्गदर्शन देने के लिए इसका उपयोग करें। +एक संदेश जो जोड़ा जाता है कारण जब कोई नीति `deny` या `instruct` देता है। इसका उपयोग Claude को नीति को संशोधित किए बिना कार्रवाई योग्य निर्देशन देने के लिए करें। -किसी भी नीति प्रकार के साथ काम करता है — बिल्ट-इन, कस्टम (`custom/`), प्रोजेक्ट सम्मेलन (`.failproofai-project/`), या उपयोगकर्ता सम्मेलन (`.failproofai-user/`)। +किसी भी नीति प्रकार के साथ काम करता है — बिल्ट-इन, कस्टम (`custom/`), प्रोजेक्ट कन्वेंशन (`.failproofai-project/`), या उपयोगकर्ता कन्वेंशन (`.failproofai-user/`)। ```json { "policyParams": { "block-force-push": { - "hint": "इसके बजाय एक ताजी शाखा बनाने का प्रयास करें।" + "hint": "Try creating a fresh branch instead." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], - "hint": "sudo के बिना सीधे apt-get का उपयोग करें।" + "hint": "Use apt-get directly without sudo." }, "custom/my-policy": { - "hint": "पहले उपयोगकर्ता से अनुमोदन मांगें।" + "hint": "Ask the user for approval first." } } } ``` -जब `block-force-push` अस्वीकार करता है, Claude देखता है: *"जबरन पुश करना अवरुद्ध है। इसके बजाय एक ताजी शाखा बनाने का प्रयास करें।"* +जब `block-force-push` अस्वीकार करता है, तो Claude को यह दिखता है: *"Force-pushing is blocked. Try creating a fresh branch instead."* -गैर-स्ट्रिंग मानों और खाली स्ट्रिंग्स को चुपचाप अनदेखा किया जाता है। यदि `hint` सेट नहीं है, तो व्यवहार अपरिवर्तित है (पिछड़े-संगत)। +गैर-स्ट्रिंग मान और खाली स्ट्रिंग्स को चुप्पी से अनदेखा किया जाता है। यदि `hint` सेट नहीं है, तो व्यवहार अपरिवर्तित रहता है (पश्चविमुखी-संगत)। ### `customPoliciesPath` -प्रकार: `string` (पूर्ण पथ) +प्रकार: `string` (निरपेक्ष पाथ) -कस्टम हुक नीतियों वाली JavaScript फ़ाइल का पथ। यह `failproofai policies --install --custom ` द्वारा स्वचालित रूप से सेट किया जाता है (पथ संग्रहीत होने से पहले पूर्ण में हल किया जाता है)। +कस्टम हुक नीतियों वाली JavaScript फ़ाइल का पाथ। यह स्वचालित रूप से `failproofai policies --install --custom ` द्वारा सेट किया जाता है (पाथ को निरपेक्ष के लिए हल किया जाता है फिर संग्रहीत किया जाता है)। -फ़ाइल हर हुक ईवेंट पर नई लोड की जाती है - कोई कैशिंग नहीं है। विस्तारों के लिए [कस्टम नीतियां](/hi/custom-policies) देखें। +फ़ाइल प्रत्येक हुक ईवेंट पर ताज़ी लोड की जाती है - कोई कैशिंग नहीं है। विस्तार के लिए [कस्टम पॉलिसीज़](/hi/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` के विपरीत जो पहले-स्कोप-जीत का उपयोग करता है)। -अधिक विवरण और उदाहरणों के लिए [कस्टम नीतियां](/hi/custom-policies) देखें। +अधिक विवरण और उदाहरणों के लिए [कस्टम पॉलिसीज़](/hi/custom-policies) देखें। ### `llm` प्रकार: `object` (वैकल्पिक) -AI कॉल करने वाली नीतियों के लिए LLM क्लाइंट कॉन्फ़िगरेशन। अधिकांश सेटअप के लिए आवश्यक नहीं है। +उन नीतियों के लिए LLM क्लाइंट कॉन्फ़िगरेशन जो AI कॉल करते हैं। अधिकांश सेटअप के लिए आवश्यक नहीं है। ```json { @@ -189,19 +189,20 @@ AI कॉल करने वाली नीतियों के लिए LL ## 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` मार्कर ले जाती है। Copilot CLI समर्थन **बीटा** है जबकि हम `events.jsonl` रिकॉर्ड स्कीमा को सत्यापित करते हैं (जिसे सार्वजनिक दस्तावेज निर्दिष्ट नहीं करते) अधिक वास्तविक दुनिया सत्रों के विरुद्ध। - - **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()` (उपकरण कॉल को रद्द करता है), `client.session.prompt(...)` निर्देश के लिए AND `Stop` / `SubagentStop` अस्वीकार के लिए (अगले उपयोगकर्ता संदेश के रूप में अस्वीकार कारण जमा करता है — एकमात्र बल-पुनः प्रयास चैनल क्योंकि `session.idle` केवल सूचना है और इससे फेंकना एक कोई-ऑप है), और 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 उपकरण कॉल पर अपरिवर्तित रहें। सत्र opencode की SQLite DB पर रहते हैं `~/.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 के पास कोई `local` स्कोप नहीं है। Pi स्टार्टअप पर TypeScript एक्सटेंशन पैकेज लोड करता है; सेटिंग्स फ़ाइल एक सपाट स्ट्रिंग सरणी है `{"packages": ["./relative/path", …]}`. failproofai एक एकल packages-array प्रविष्टि लिखता है जो अपनी बंडल की गई `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 का Read / Write / Edit `file_path` के बजाय `path` प्रदान करता है; शीर्ष-स्तरीय कुंजी को मैपिंग `block-env-files` और `block-secrets-write` को आग लगाने देता है — `block-read-outside-cwd` पहले से ही `path` फॉलबैक था)। Pi समर्थन **बीटा** है जबकि Pi का एक्सटेंशन API और सत्र-लॉग लेआउट स्थिर होता है। - - **Gemini CLI _(बीटा)_**: `~/.gemini/settings.json` (उपयोगकर्ता), `/.gemini/settings.json` (प्रोजेक्ट) — Gemini के पास कोई `local` स्कोप नहीं है (यह `/etc/gemini-cli/settings.json` पर एक `system` स्कोप दस्तावेज़ करता है जिसे failproofai उजागर नहीं करता)। हुक प्रविष्टियां Claude के `{type, command, timeout}` फॉर्म का उपयोग करते हैं Gemini के `{matcher, hooks: [...]}` मेचर स्कीमा में लपेटा जाता है जिसमें `matcher: "*"` डिफ़ॉल्ट है। ईवेंट्स PascalCase हैं (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); हैंडलर `GEMINI_EVENT_MAP` के माध्यम से Claude canonical नामों को मैप करता है। उपकरण के नाम snake_case हैं (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — हैंडलर `GEMINI_TOOL_MAP` के माध्यम से सामान्य करता है ताकि मौजूदा बिल्ट-इन नीतियां अपरिवर्तित रहें। नीति मूल्यांकनकर्ता Gemini का समतल `{decision: "deny", reason}` आकार उत्सर्जित करता है (Gemini के Golden Rule exit-0 अनुबंध के अनुसार पसंदीदा), `{hookSpecificOutput: {hookEventName, additionalContext}}` BeforeAgent / AfterTool / SessionStart पर संदर्भ इंजेक्शन के लिए, और `{decision: "block", reason}` AfterAgent पर बल-पुनः प्रयास शब्दार्थ के लिए। Gemini CLI समर्थन **बीटा** है जबकि हम वास्तविक दुनिया के कवरेज को चौड़ा करते हैं। [Gemini CLI हुक दस्तावेज़](https://geminicli.com/docs/hooks/) देखें। -- **`policies-config.json`** — failproofai को बताता है कि कौन सी नीतियों का मूल्यांकन करना है और किन पैराम्स के साथ (सभी एजेंट CLI में साझा) +- **एजेंट 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 लेआउट स्थिर होता है। + - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (उपयोगकर्ता), `/.gemini/settings.json` (प्रोजेक्ट) — Gemini के पास कोई `local` स्कोप नहीं है (यह `/etc/gemini-cli/settings.json` पर एक `system` स्कोप दस्तावेज़ित करता है जो failproofai उजागर नहीं करता)। हुक एंट्रीज़ Claude के `{type, command, timeout}` फॉर्म का उपयोग करते हैं Gemini के `{matcher, hooks: [...]}` matcher स्कीमा में लपेटा गया `matcher: "*"` के साथ डिफ़ॉल्ट रूप से। ईवेंट्स PascalCase हैं (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); हैंडलर `GEMINI_EVENT_MAP` के माध्यम से Claude canonical नामों में मैप करता है। टूल नाम snake_case हैं (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — हैंडलर `GEMINI_TOOL_MAP` के माध्यम से कैनोनिकलाइज़ करता है ताकि मौजूदा बिल्ट-इन नीतियां अपरिवर्तित रूप से चलें। नीति मूल्यांकनकर्ता Gemini का फ्लैट `{decision: "deny", reason}` shape (Gemini के "Golden Rule" exit-0 contract के अनुसार पसंद किया जाता है), `{hookSpecificOutput: {hookEventName, additionalContext}}` context injection के लिए BeforeAgent / AfterTool / SessionStart पर, और `{decision: "block", reason}` AfterAgent पर force-retry semantics के लिए उत्सर्जित करता है। Gemini CLI समर्थन **beta** है जबकि हम वास्तविक-दुनिया कवरेज को चौड़ा करते हैं। [Gemini CLI hooks docs](https://geminicli.com/docs/hooks/) देखें। + - **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 में साझा) -किसी विशिष्ट एजेंट को लक्षित करने के लिए `--cli claude|codex|copilot|cursor|opencode|pi|gemini` पास करें (स्पेस-अलग या किसी भी सबसेट के लिए दोहराया गया): +एक विशिष्ट एजेंट को target करने के लिए `--cli claude|codex|copilot|cursor|opencode|pi|gemini|hermes` पास करें (space-separated या repeated किसी भी subset के लिए): ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +211,24 @@ 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 gemini --scope project +failproofai policies --install --cli hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` -जब `--cli` छोड़ दिया जाता है, `failproofai` पहचानता है कि कौन से एजेंट CLI स्थापित हैं (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): +जब `--cli` omit किया जाता है, `failproofai` पता लगाता है कि कौन से एजेंट CLIs installed हैं (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini` / `which hermes`): -- **एक CLI पहचाना गया** — बिना संकेत के उस CLI को स्वचालित रूप से चुनता है। -- **एक इंटरैक्टिव टर्मिनल में कई CLI पहचाने गए** — एक तीर-कुंजी एकल-चयन संकेत दिखाता है `Detected (N)` सेक्शन में समूहीकृत (एक `Install for all N detected` समुच्चय पंक्ति + प्रत्येक पहचाने गए CLI अलग) और एक `Not installed (M) · install hooks ahead of time` सेक्शन जो हर अपहचाने गए समर्थित CLI को एक forward-install विकल्प के रूप में सूचीबद्ध करता है (↑↓ स्थानांतरित करने के लिए, Enter चुनने के लिए, ^C बाहर निकलने के लिए)। अनइंस्टॉल प्रवाह केवल डिटेक्टेड सेक्शन दिखाता है। -- **एक गैर-इंटरैक्टिव रन में कई CLI पहचाने गए** (CI, कोई TTY नहीं) — संकेत के बिना सभी पहचाने गए CLI के लिए स्थापित करता है। -- **कोई भी नहीं पहचाना गया** — `claude` में फॉलबैक, एक चेतावनी के साथ कि PATH में कोई एजेंट बाइनरी नहीं मिला; हुक कमांड अभी भी लिखा जाता है ताकि यह सक्रिय हो जाए जैसे ही आप एक स्थापित करते हैं। +- **एक 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 करते हैं। -आप किसी भी समय सीधे `policies-config.json` को संपादित कर सकते हैं; परिवर्तन तुरंत अगली हुक ईवेंट पर प्रभाव डालते हैं पुनरारंभ की आवश्यकता के बिना। +आप किसी भी समय `policies-config.json` को सीधे edit कर सकते हैं; changes अगली हुक ईवेंट पर तुरंत प्रभावी होते हैं restart की आवश्यकता नहीं है। --- -## उदाहरण: टीम डिफ़ॉल्ट के साथ प्रोजेक्ट-स्तरीय कॉन्फ़िगरेशन +## उदाहरण: टीम डिफ़ॉल्ट के साथ प्रोजेक्ट-लेवल कॉन्फ़िग -`.failproofai/policies-config.json` को अपने रेपो में कमिट करें: +अपने रेपो में `.failproofai/policies-config.json` को कमिट करें: ```json { @@ -245,4 +247,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi gem } ``` -प्रत्येक डेवलपर तब `.failproofai/policies-config.local.json` (gitignored) बना सकता है व्यक्तिगत ओवरराइड के लिए सहकर्मियों को प्रभावित किए बिना। \ No newline at end of file +प्रत्येक डेवलपर फिर व्यक्तिगत overrides के लिए `.failproofai/policies-config.local.json` (gitignored) बना सकता है बिना teammates को प्रभावित किए। \ No newline at end of file diff --git a/docs/hi/custom-policies.mdx b/docs/hi/custom-policies.mdx index 497a247d..68696d2a 100644 --- a/docs/hi/custom-policies.mdx +++ b/docs/hi/custom-policies.mdx @@ -1,14 +1,14 @@ --- -title: कस्टम पॉलिसीज़ -description: "JavaScript में अपने नियम लिखें - प्रोजेक्ट कन्वेंशन लागू करें, ड्रिफ्ट रोकें, विफलताएं डिटेक्ट करें, बाहरी सिस्टम्स के साथ इंटीग्रेट करें" +title: कस्टम पॉलिसीज +description: "JavaScript में अपने नियम लिखें - सम्मेलनों को लागू करें, ड्रिफ्ट को रोकें, विफलताओं का पता लगाएं, बाहरी सिस्टम के साथ इंटीग्रेट करें" icon: code --- -कस्टम पॉलिसीज़ आपको किसी भी एजेंट बिहेवियर के लिए नियम लिखने देती हैं: प्रोजेक्ट कन्वेंशन लागू करें, ड्रिफ्ट रोकें, विनाशकारी ऑपरेशन्स को रोकें, फंसे हुए एजेंट्स डिटेक्ट करें, या Slack, अप्रूवल वर्कफ़्लो और अन्य सिस्टम्स के साथ इंटीग्रेट करें। वे बिल्ट-इन पॉलिसीज़ के समान हुक इवेंट सिस्टम और `allow`, `deny`, `instruct` डिसीजन्स का उपयोग करते हैं। +कस्टम पॉलिसीज आपको किसी भी एजेंट व्यवहार के लिए नियम लिखने देती हैं: प्रोजेक्ट सम्मेलनों को लागू करें, ड्रिफ्ट को रोकें, विनाशकारी संचालन को गेट करें, फंसे हुए एजेंटों का पता लगाएं, या Slack, अनुमोदन वर्कफ़्लो और बहुत कुछ के साथ इंटीग्रेट करें। ये बिल्ट-इन पॉलिसीज के समान हुक ईवेंट सिस्टम और `allow`, `deny`, `instruct` निर्णयों का उपयोग करते हैं। --- -## क्विक उदाहरण +## त्वरित उदाहरण ```js // my-policies.js @@ -37,11 +37,11 @@ failproofai policies --install --custom ./my-policies.js --- -## कस्टम पॉलिसीज़ लोड करने के दो तरीके +## कस्टम पॉलिसीज लोड करने के दो तरीके -### विकल्प 1: कन्वेंशन-आधारित (सुझाया गया) +### विकल्प 1: सम्मेलन-आधारित (अनुशंसित) -`*policies.{js,mjs,ts}` फ़ाइलें `.failproofai/policies/` में ड्रॉप करें और वे स्वचालित रूप से लोड हो जाती हैं — कोई फ्लैग्स या कॉन्फ़िग बदलाव की जरूरत नहीं। यह git हुक्स की तरह काम करता है: एक फ़ाइल ड्रॉप करें, और यह बस काम करता है। +`.failproofai/policies/` में `*policies.{js,mjs,ts}` फाइलें डालें और वे स्वचालित रूप से लोड हो जाती हैं — कोई फ्लैग या कॉन्फ़िग परिवर्तन की आवश्यकता नहीं। यह git हुक्स की तरह काम करता है: एक फाइल डालें, यह बस काम करता है। ``` # प्रोजेक्ट स्तर — git में कमिट किया गया, टीम के साथ साझा किया गया @@ -53,44 +53,44 @@ failproofai policies --install --custom ./my-policies.js ``` **यह कैसे काम करता है:** -- प्रोजेक्ट और यूजर दोनों डायरेक्टरीज़ स्कैन की जाती हैं (यूनियन — first-scope-wins नहीं) -- फ़ाइलें प्रत्येक डायरेक्टरी के भीतर वर्णक्रम में लोड होती हैं। ऑर्डर नियंत्रित करने के लिए `01-`, `02-` प्रीफ़िक्स करें -- केवल `*policies.{js,mjs,ts}` से मेल खाने वाली फ़ाइलें लोड होती हैं; अन्य फ़ाइलें अनदेखी की जाती हैं -- प्रत्येक फ़ाइल स्वतंत्र रूप से लोड होती है (प्रति फ़ाइल fail-open) -- स्पष्ट `--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 --uninstall --custom ``` -रिज़ॉल्व किया गया निरपेक्ष पाथ `policies-config.json` में `customPoliciesPath` के रूप में स्टोर किया जाता है। फ़ाइल हर हुक इवेंट पर ताजा लोड होती है - इवेंट्स के बीच कोई कैशिंग नहीं है। +समाधान किया गया निरपेक्ष पाथ `policies-config.json` में `customPoliciesPath` के रूप में संग्रहीत होता है। फाइल हर हुक ईवेंट पर ताजा लोड होती है - ईवेंट्स के बीच कोई कैशिंग नहीं होती है। ### दोनों को एक साथ उपयोग करना -कन्वेंशन पॉलिसीज़ और स्पष्ट `--custom` फ़ाइल एक साथ मौजूद रह सकती हैं। लोड ऑर्डर: +सम्मेलन पॉलिसीज और स्पष्ट `--custom` फाइल सह-अस्तित्व में रह सकते हैं। लोड क्रम: -1. स्पष्ट `customPoliciesPath` फ़ाइल (यदि कॉन्फ़िगर की गई है) -2. प्रोजेक्ट कन्वेंशन फ़ाइलें (`{cwd}/.failproofai/policies/`, वर्णक्रम में) -3. यूजर कन्वेंशन फ़ाइलें (`~/.failproofai/policies/`, वर्णक्रम में) +1. स्पष्ट `customPoliciesPath` फाइल (यदि कॉन्फ़िगर की गई हो) +2. प्रोजेक्ट सम्मेलन फाइलें (`{cwd}/.failproofai/policies/`, वर्णानुक्रम) +3. यूजर सम्मेलन फाइलें (`~/.failproofai/policies/`, वर्णानुक्रम) --- ## API -### इम्पोर्ट +### आयात ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -98,45 +98,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -एक पॉलिसी रजिस्टर करता है। समान फ़ाइल में कई पॉलिसीज़ के लिए आवश्यकतानुसार इसे कॉल करें। +एक पॉलिसी को रजिस्टर करता है। एक ही फाइल में कई पॉलिसीज के लिए जितनी बार चाहें इसे कॉल करें। ```ts customPolicies.add({ - name: string; // आवश्यक - यूनिक आइडेंटिफायर + 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)` - संदेश Claude को `"Blocked by failproofai:"` प्रीफ़िक्स के साथ दिखाई देता है। एक एकल `deny` सभी आगे के मूल्यांकन को शॉर्ट-सर्किट करता है। +`deny(message)` - संदेश Claude को `"Blocked by failproofai:"` प्रीफिक्स के साथ प्रकट होता है। एक एकल `deny` सभी आगे के मूल्यांकन को शॉर्ट-सर्किट करता है। -`instruct(message)` - संदेश वर्तमान टूल कॉल के लिए Claude के संदर्भ में जोड़ा जाता है। सभी `instruct` संदेश जमा किए जाते हैं और एक साथ डिलीवर किए जाते हैं। +`instruct(message)` - संदेश वर्तमान टूल कॉल के लिए Claude के संदर्भ में जोड़ा जाता है। सभी `instruct` संदेश जमा किए जाते हैं और एक साथ दिए जाते हैं। -आप `policyParams` में `hint` फ़ील्ड जोड़कर किसी भी `deny` या `instruct` संदेश में अतिरिक्त निर्देश जोड़ सकते हैं — कोई कोड बदलाव की जरूरत नहीं। यह कस्टम (`custom/`), प्रोजेक्ट कन्वेंशन (`.failproofai-project/`), और यूजर कन्वेंशन (`.failproofai-user/`) पॉलिसीज़ के लिए भी काम करता है। विवरण के लिए [कॉन्फ़िगरेशन → hint](/hi/configuration#hint-cross-cutting) देखें। +आप `policyParams` में एक `hint` फील्ड जोड़कर किसी भी `deny` या `instruct` संदेश को अतिरिक्त मार्गदर्शन जोड़ सकते हैं — कोई कोड परिवर्तन आवश्यक नहीं है। यह कस्टम (`custom/`), प्रोजेक्ट सम्मेलन (`.failproofai-project/`), और यूजर सम्मेलन (`.failproofai-user/`) पॉलिसीज के लिए भी काम करता है। विवरण के लिए [कॉन्फ़िगरेशन → hint](/hi/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 को बताता है कि सब कुछ हरा है +- **फेल-ओपन स्पष्टीकरण:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude को बताता है कि एक जांच क्यों छोड़ी गई ताकि इसे पूरा संदर्भ हो +- **कई संदेश जमा होते हैं:** यदि कई पॉलिसीज प्रत्येक `allow(message)` लौटाती हैं, सभी संदेश नई लाइनों के साथ जुड़ते हैं और एक साथ दिए जाते हैं ```js customPolicies.add({ @@ -146,7 +146,7 @@ customPolicies.add({ const cwd = ctx.session?.cwd; if (!cwd) return allow("No working directory, skipping branch check."); - // ... branch status चेक करें ... + // ... शाखा स्थिति की जांच करें ... if (allPushed) { return allow("Branch is up to date with remote."); } @@ -155,53 +155,53 @@ customPolicies.add({ }); ``` -### `PolicyContext` फ़ील्ड्स +### `PolicyContext` फील्ड्स -| फ़ील्ड | टाइप | विवरण | +| फील्ड | प्रकार | विवरण | |-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | कॉल किया जा रहा टूल (उदा. `"Bash"`, `"Write"`, `"Read"`) | -| `toolInput` | `Record \| undefined` | टूल के इनपुट पैरामीटर्स | -| `payload` | `Record` | Claude Code से पूर्ण raw इवेंट पेलोड | +| `toolName` | `string \| undefined` | कॉल किया जा रहा टूल (जैसे `"Bash"`, `"Write"`, `"Read"`) | +| `toolInput` | `Record \| undefined` | टूल के इनपुट पैरामीटर | +| `payload` | `Record` | Claude Code से पूरा कच्चा ईवेंट पेलोड | | `session` | `SessionMetadata \| undefined` | सेशन संदर्भ (नीचे देखें) | -### `SessionMetadata` फ़ील्ड्स +### `SessionMetadata` फील्ड्स -| फ़ील्ड | टाइप | विवरण | +| फील्ड | प्रकार | विवरण | |-------|------|-------------| -| `sessionId` | `string` | Claude Code सेशन आइडेंटिफायर | -| `cwd` | `string` | Claude Code सेशन की वर्किंग डायरेक्टरी | -| `transcriptPath` | `string` | सेशन की JSONL ट्रांसक्रिप्ट फ़ाइल का पाथ | +| `sessionId` | `string` | Claude Code सेशन पहचानकर्ता | +| `cwd` | `string` | Claude Code सेशन की कार्य निर्देशिका | +| `transcriptPath` | `string` | सेशन की JSONL ट्रांसक्रिप्ट फाइल का पाथ | -### इवेंट टाइप्स +### ईवेंट प्रकार -| इवेंट | कब फायर होता है | `toolInput` सामग्री | +| ईवेंट | कब फायर होता है | `toolInput` सामग्री | |-------|--------------|----------------------| -| `PreToolUse` | Claude से पहले एक टूल चलाता है | टूल का इनपुट (उदा. Bash के लिए `{ command: "..." }`) | +| `PreToolUse` | Claude से पहले एक टूल चलाता है | टूल का इनपुट (जैसे Bash के लिए `{ command: "..." }`) | | `PostToolUse` | एक टूल पूरा होने के बाद | टूल का इनपुट + `tool_result` (आउटपुट) | -| `Notification` | जब Claude एक नोटिफिकेशन भेजता है | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - हुक्स हमेशा `allow()` रिटर्न करना चाहिए, वे नोटिफिकेशन्स को ब्लॉक नहीं कर सकते | +| `Notification` | जब Claude एक नोटिफिकेशन भेजता है | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - हुक्स को हमेशा `allow()` लौटाना चाहिए, वे नोटिफिकेशन को ब्लॉक नहीं कर सकते | | `Stop` | जब Claude सेशन समाप्त होता है | खाली | --- -## मूल्यांकन ऑर्डर +## मूल्यांकन क्रम -पॉलिसीज़ इस ऑर्डर में मूल्यांकन किए जाते हैं: +पॉलिसीज को इस क्रम में मूल्यांकन किया जाता है: -1. बिल्ट-इन पॉलिसीज़ (डेफिनिशन ऑर्डर में) -2. `customPoliciesPath` से स्पष्ट कस्टम पॉलिसीज़ (`.add()` ऑर्डर में) -3. प्रोजेक्ट `.failproofai/policies/` से कन्वेंशन पॉलिसीज़ (फ़ाइलें वर्णक्रम में, `.add()` ऑर्डर के भीतर) -4. यूजर `~/.failproofai/policies/` से कन्वेंशन पॉलिसीज़ (फ़ाइलें वर्णक्रम में, `.add()` ऑर्डर के भीतर) +1. बिल्ट-इन पॉलिसीज (परिभाषा क्रम में) +2. `customPoliciesPath` से स्पष्ट कस्टम पॉलिसीज (`.add()` क्रम में) +3. प्रोजेक्ट `.failproofai/policies/` से सम्मेलन पॉलिसीज (फाइलें वर्णानुक्रम में, `.add()` क्रम में) +4. यूजर `~/.failproofai/policies/` से सम्मेलन पॉलिसीज (फाइलें वर्णानुक्रम में, `.add()` क्रम में) -पहला `deny` सभी सबसे आगे की पॉलिसीज़ को शॉर्ट-सर्किट करता है। सभी `instruct` संदेश जमा किए जाते हैं और एक साथ डिलीवर किए जाते हैं। +पहला `deny` सभी बाद की पॉलिसीज को शॉर्ट-सर्किट करता है। सभी `instruct` संदेश जमा किए जाते हैं और एक साथ दिए जाते हैं। --- -## ट्रांजिटिव इम्पोर्ट्स +## ट्रांजिटिव आयात -कस्टम पॉलिसी फ़ाइलें सापेक्ष पाथ का उपयोग करके स्थानीय मॉड्यूल्स को इम्पोर्ट कर सकती हैं: +कस्टम पॉलिसी फाइलें सापेक्ष पाथों का उपयोग करके स्थानीय मॉड्यूल को आयात कर सकती हैं: ```js // my-policies.js @@ -218,13 +218,13 @@ customPolicies.add({ }); ``` -एंट्री फ़ाइल से पहुंचने योग्य सभी सापेक्ष इम्पोर्ट्स रिज़ॉल्व किए जाते हैं। यह `from "failproofai"` इम्पोर्ट्स को वास्तविक dist पाथ में फिर से लिखकर और ESM कम्पैटिबिलिटी सुनिश्चित करने के लिए अस्थायी `.mjs` फ़ाइलें बनाकर लागू किया जाता है। +प्रविष्टि फाइल से पहुंचने योग्य सभी सापेक्ष आयात समाधान किए जाते हैं। यह `failproofai` आयातों को वास्तविक dist पाथ में फिर से लिखकर और ESM संगतता सुनिश्चित करने के लिए अस्थायी `.mjs` फाइलें बनाकर लागू किया जाता है। --- -## इवेंट टाइप फ़िल्टरिंग +## ईवेंट प्रकार फ़िल्टरिंग -`match.events` का उपयोग करके सीमित करें कि एक पॉलिसी कब फायर हो: +यह सीमित करने के लिए `match.events` का उपयोग करें कि पॉलिसी कब फायर होती है: ```js customPolicies.add({ @@ -238,26 +238,26 @@ customPolicies.add({ }); ``` -हर इवेंट टाइप पर फायर करने के लिए `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 @@ -266,13 +266,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 +285,7 @@ customPolicies.add({ }, }); -// एजेंट को ट्रैक पर रखें: कमिट करने से पहले टेस्ट्स सत्यापित करें +// एजेंट को ट्रैक पर रखें: कमिट करने से पहले टेस्ट सत्यापित करें customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +300,7 @@ customPolicies.add({ }, }); -// फ्रीज़ अवधि के दौरान अनियोजित डिपेंडेंसी बदलाव रोकें +// फ्रीज अवधि के दौरान अनियोजित निर्भरता परिवर्तनों को रोकें customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -323,22 +323,22 @@ export { customPolicies }; ## उदाहरण -`examples/` डायरेक्टरी में तैयार-से-चलने वाली पॉलिसी फ़ाइलें हैं: +`examples/` डायरेक्ट्री में तैयार-से-चलाने योग्य पॉलिसी फाइलें हैं: -| फ़ाइल | सामग्री | +| फाइल | सामग्री | |------|----------| -| `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` | पांच स्टार्टर पॉलिसीज जो सामान्य एजेंट विफलता मोड्स को कवर करती हैं | +| `examples/policies-advanced/index.js` | उन्नत पैटर्न: ट्रांजिटिव आयात, async कॉल्स, आउटपुट स्क्रबिंग, और सेशन-एंड हुक्स | +| `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 +350,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/hi/dashboard.mdx b/docs/hi/dashboard.mdx index 9a360b1b..b3a6c202 100644 --- a/docs/hi/dashboard.mdx +++ b/docs/hi/dashboard.mdx @@ -1,11 +1,10 @@ --- ---- title: डैशबोर्ड description: "एजेंट सेशन की निगरानी करें, टूल कॉल की समीक्षा करें, और नीतियों को प्रबंधित करें" icon: chart-line --- -failproofai डैशबोर्ड आपके AI एजेंट सेशन की निगरानी और नीतियों को प्रबंधित करने के लिए एक स्थानीय वेब एप्लिकेशन है। देखें कि आपके एजेंट आपके दूर रहते हुए क्या कर रहे थे। +failproofai डैशबोर्ड आपके AI एजेंट सेशन की निगरानी करने और नीतियों को प्रबंधित करने के लिए एक स्थानीय वेब एप्लिकेशन है। देखें कि आपके एजेंट आपकी अनुपस्थिति में क्या कर रहे थे। --- @@ -17,58 +16,58 @@ failproofai `http://localhost:8020` पर खुलता है। -डैशबोर्ड सीधे फाइलसिस्टम से पढ़ता है - आपके Claude Code प्रोजेक्ट फोल्डर और failproofai कॉन्फ़िग फाइलें। कुछ भी दूरस्थ सेवा में नहीं लिखा जाता है। +डैशबोर्ड फाइलसिस्टम से सीधे पढ़ता है - आपके Claude Code प्रोजेक्ट फोल्डर और failproofai कॉन्फ़िगरेशन फाइलें। किसी रिमोट सेवा में कुछ नहीं लिखा जाता है। --- ## पृष्ठ -### प्रोजेक्ट्स +### प्रोजेक्ट -आपकी मशीन पर मिले सभी Claude Code, OpenAI Codex, GitHub Copilot CLI _(बीटा)_, Cursor Agent _(बीटा)_, OpenCode _(बीटा)_, Pi _(बीटा)_, और Gemini CLI _(बीटा)_ प्रोजेक्ट की सूची। 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` खींचते हैं; Gemini CLI प्रोजेक्ट `~/.gemini/tmp//chats/session--.jsonl` को स्कैन करके खोजे जाते हैं (`GEMINI_SESSIONS_DIR` के माध्यम से कॉन्फ़िगर करने योग्य) और सहोदर `.project_root` टेक्स्ट मार्कर से विहित cwd को पुनः प्राप्त करते हैं। एक प्रोजेक्ट जो कई CLIs द्वारा उपयोग किया गया है एक एकल पंक्ति के रूप में सभी मिलान बैज के साथ प्रदर्शित होता है। एक विशिष्ट एजेंट CLI द्वारा फ़िल्टर करने के लिए तालिका के ऊपर **CLI** ड्रॉपडाउन का उपयोग करें; URL आपकी चयन को `?cli=claude|codex|copilot|cursor|opencode|pi|gemini` के रूप में सहेजता है। +आपकी मशीन पर मिले सभी Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Gemini CLI _(beta)_, और Hermes प्रोजेक्ट सूचीबद्ध करता है। 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` निकाला जाता है; Gemini CLI प्रोजेक्ट `~/.gemini/tmp//chats/session--.jsonl` को स्कैन करके खोजे जाते हैं (`GEMINI_SESSIONS_DIR` के माध्यम से कॉन्फ़िगर करने योग्य) और अनुवर्ती `.project_root` टेक्स्ट मार्कर से विहित cwd को पुनः प्राप्त किया जाता है; Hermes गेटवे सेशन सीधे इसके SQLite स्टोर से `~/.hermes/state.db` पर पढ़े जाते हैं (`HERMES_DB_PATH` के माध्यम से कॉन्फ़िगर करने योग्य) और `source` के अनुसार `hermes-` प्रोजेक्ट में समूहबद्ध किए जाते हैं (Slack/Telegram/cli/cron — गेटवे सेशन का कोई cwd नहीं है)। एक प्रोजेक्ट जिसे कई CLI द्वारा उपयोग किया गया है, एक एकल पंक्ति के रूप में सभी मेल खाने वाले बैज के साथ प्रदर्शित होता है। सारणी के ऊपर **CLI** ड्रॉपडाउन का उपयोग करके किसी विशिष्ट एजेंट CLI द्वारा फ़िल्टर करें; URL आपके चयन को `?cli=claude|codex|copilot|cursor|opencode|pi|gemini|hermes` के रूप में संरक्षित करता है। प्रत्येक प्रोजेक्ट दिखाता है: -- प्रोजेक्ट नाम (फोल्डर पथ से प्राप्त) -- एक CLI बैज — `Claude Code` (नारंगी), `OpenAI Codex` (बैंगनी), `GitHub Copilot` (नीला), `Cursor Agent` (पन्ना), `OpenCode` (एम्बर), `Pi` (गुलाबी), और/या `Gemini CLI` (आकाश) +- प्रोजेक्ट नाम (फोल्डर पथ से व्युत्पन्न) +- एक CLI बैज — `Claude Code` (नारंगी), `OpenAI Codex` (बैंगनी), `GitHub Copilot` (नीला), `Cursor Agent` (पन्ना), `OpenCode` (एम्बर), `Pi` (गुलाबी), `Gemini CLI` (आसमानी), और/या `Hermes` (गहरा नीला) - सबसे हाल की सेशन गतिविधि की तारीख -इसके सेशन देखने के लिए एक प्रोजेक्ट पर क्लिक करें। +एक प्रोजेक्ट पर क्लिक करके इसके सेशन देखें। ### सेशन -एक प्रोजेक्ट के भीतर सभी सेशन की सूची। प्रत्येक सेशन दिखाता है: +एक प्रोजेक्ट के भीतर सभी सेशन सूचीबद्ध करता है। प्रत्येक सेशन दिखाता है: - सेशन ID -- शुरुआत और अंत का समय +- प्रारंभ और समाप्ति टाइमस्टैम्प - टूल कॉल की संख्या -- हुक गतिविधि की गिनती (नीतियां जो सक्रिय हुईं) +- हुक गतिविधि गणना (नीतियां जो सक्रिय हुईं) -सूची को कम करने के लिए दिनांक सीमा फ़िल्टर और सेशन ID खोज का उपयोग करें। सेशन पृष्ठांकित हैं। +सूची को संकीर्ण करने के लिए दिनांक श्रेणी फ़िल्टर और सेशन ID खोज का उपयोग करें। सेशन पृष्ठांकित हैं। -सेशन दर्शक को खोलने के लिए एक सेशन पर क्लिक करें। +सेशन दर्शक खोलने के लिए एक सेशन पर क्लिक करें। ### सेशन दर्शक -सेशन दर्शक स्वायत्त एजेंटों के लिए मुख्य प्रश्न का उत्तर देता है: एजेंट ने क्या किया, और क्या यह ट्रैक पर रहा? हेडर के बगल में एक CLI बैज यह दर्शाता है कि सेशन Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, या Gemini CLI ट्रांस्क्रिप्ट है। यह एक सेशन में हुई सभी चीजों की एक समयरेखा दिखाता है: +सेशन दर्शक स्वायत्त एजेंट के लिए मुख्य प्रश्न का उत्तर देता है: एजेंट ने क्या किया, और क्या वह ट्रैक पर रहा? शीर्षलेख के बगल में एक CLI बैज इंगित करता है कि सेशन Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Gemini CLI, या Hermes ट्रांसक्रिप्ट है। यह एक सेशन में हुई हर चीज की एक टाइमलाइन दिखाता है: -- **संदेश** - Claude के पाठ प्रतिक्रियाएं और उपयोगकर्ता संकेत -- **टूल कॉल** - हर टूल जिसे Claude ने आह्वान किया, इसके इनपुट और आउटपुट के साथ -- **नीति गतिविधि** - प्रत्येक टूल कॉल के लिए, कौन सी नीतियां सक्रिय हुईं और उन्होंने क्या निर्णय लौटाया +- **संदेश** - Claude के टेक्स्ट प्रतिक्रियाएं और उपयोगकर्ता संकेत +- **टूल कॉल** - हर टूल जो Claude ने आह्वान किया, इसके इनपुट और आउटपुट के साथ +- **नीति गतिविधि** - प्रत्येक टूल कॉल के लिए, कौन सी नीतियां सक्रिय हुईं और उन्होंने कौन सा निर्णय लिया -शीर्ष पर सांख्यिकी पट्टी सेशन की अवधि, कुल टूल कॉल, और हुक निर्णयों का सारांश दिखाती है (allow / deny / instruct गिनती)। +शीर्ष पर सांख्यिकी बार सेशन की अवधि, कुल टूल कॉल, और हुक निर्णयों का सारांश दिखाता है (अनुमति / अस्वीकृति / निर्देश गणना)। -सेशन को निर्यात करने के लिए **डाउनलोड लॉग्स** बटन पर क्लिक करें। Claude Code, Codex, Copilot, Cursor, Pi, और Gemini सेशन के लिए आप मूल ऑन-डिस्क JSONL ट्रांस्क्रिप्ट बाइट-फॉर-बाइट प्राप्त करते हैं; OpenCode के लिए (जिसके सेशन SQLite में रहते हैं, डिस्क पर नहीं) आप एक JSON दस्तावेज़ प्राप्त करते हैं जो अंतर्निहित `session` / `messages` / `parts` तालिकाओं को प्रतिबिंबित करता है। +सेशन निर्यात करने के लिए **डाउनलोड लॉग** बटन पर क्लिक करें। Claude Code, Codex, Copilot, Cursor, Pi, और Gemini सेशन के लिए आप मूल ऑन-डिस्क JSONL ट्रांसक्रिप्ट बाइट-दर-बाइट प्राप्त करते हैं; OpenCode के लिए (जिसके सेशन SQLite में रहते हैं, डिस्क पर नहीं) आप एक JSON दस्तावेज प्राप्त करते हैं जो अंतर्निहित `session` / `messages` / `parts` तालिकाओं को प्रतिबिंबित करता है। ### ऑडिट -आपके एजेंट के व्यक्तित्व-संचालित रिपोर्ट कि वह वास्तव में अतीत के सेशन में कैसे व्यवहार कर रहा है। `failproofai audit` CLI के समान स्कैन चलाता है लेकिन इसे एक एकल-स्क्रीन शेयरयोग्य पोस्टर + चार नीचे-के-गुना अनुभागों के रूप में प्रदर्शित करता है: +आपके एजेंट के पिछले सेशन में वास्तव में कैसे व्यवहार किया गया है, इस बारे में एक व्यक्तित्व-चालित रिपोर्ट। `failproofai audit` CLI के समान स्कैन चलाता है लेकिन इसे एक एकल-स्क्रीन शेयरेबल पोस्टर + चार नीचे-फोल्ड अनुभाग के रूप में प्रदान करता है: -1. **पोस्टर** — पहला व्यूपोर्ट भरता है। Self-contained PNG-capture क्षेत्र 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 पिक्सल sigil टाइल · `audit yours → failproof.ai` पाद लेख। कैप्चर बॉक्स के ठीक बाहर तीन साझा बटन बैठते हैं: `post your archetype` (X intent), `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` में पोस्ट करते हैं, जो api-server के `POST /v0/invite` को अग्रेषित करते हैं। api-server प्रत्येक प्राप्तकर्ता को `invite@failproof.ai` से एक ईमेल भेजता है प्रेषक को Cc किया गया है और `Reply-To` सेट के साथ, इसलिए प्राप्तकर्ता देखता है कि उन्हें किसने आमंत्रित किया और प्रेषक को उनके इनबॉक्स में एक प्रति मिलती है। गुमनाम उपयोगकर्ता `AuthDialog` के माध्यम से रूट किए जाते हैं इसलिए आमंत्रण बाहर जाने से पहले प्रेषक का ईमेल ज्ञात हो। पात्रता / लाभ पूर्ति एक फॉलो-अप है। +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-server के `POST /v0/invite` को अग्रेषित करता है। api-server प्रत्येक प्राप्तकर्ता को `invite@failproof.ai` से एक ईमेल भेजता है प्रेषक Cc'd और `Reply-To` सेट के साथ, इसलिए प्राप्तकर्ता देखता है कि किसने उन्हें आमंत्रित किया और प्रेषक को अपने इनबॉक्स में एक प्रति मिलती है। गुमनाम उपयोगकर्ता `AuthDialog` के माध्यम से रूट किए जाते हैं इसलिए आमंत्रण के बाहर जाने से पहले प्रेषक का ईमेल ज्ञात होता है। अधिकार / विशेषाधिकार पूर्ति एक अनुवर्ती है। -`failproofai audit` रनटाइम द्वारा संचालित — अंतर्निहित स्कैन इंजन, समर्थित फ़्लैग, और प्रति-ट्रांस्क्रिप्ट कैश अपरिवर्तनीय के लिए [ऑडिट CLI](/hi/cli/audit) देखें। डैशबोर्ड सबसे हाल का परिणाम `~/.failproofai/audit-dashboard.json` पर कैश करता है (मोड `0600`, एकल स्लॉट, नए रन ओवरराइट करते हैं) इसलिए पुनः विजिट तत्काल हैं; **प्रति-ट्रांस्क्रिप्ट और संपूर्ण-परिणाम दोनों कैश को पढ़ने पर अस्वीकार कर दिया जाता है एक बार वे 7 दिन से अधिक पुराने हो जाते हैं** इसलिए डैशबोर्ड कभी भी एक सप्ताह पुराना परिणाम मौन रूप से परोसता नहीं है — TTL के बाद `/audit` खाली अवस्था में गिर जाता है और एक ताजा रन का संकेत देता है। रिपोर्ट के नीचे `[ re-audit now ]` पर क्लिक करना `/api/audit/run` को `noCache: true` के साथ पोस्ट करता है — पुनः-ऑडिट प्रति-ट्रांस्क्रिप्ट कैश को बायपास करता है और हर ट्रांस्क्रिप्ट को शुरुआत से फिर से स्कैन करता है मौन रूप से कैश किए गए परिणाम को लौटाने के बजाय — और डैशबोर्ड 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 ]` पर क्लिक करना `noCache: true` के साथ `/api/audit/run` को POST करता है — पुनः-ऑडिट प्रति-ट्रांसक्रिप्ट कैश को बाईपास करता है और प्रत्येक ट्रांसक्रिप्ट को शुरुआत से स्कैन करता है बजाय चुप रहकर कैश किए गए परिणाम को लौटाने के — और डैशबोर्ड रन समाप्त होने तक 1Hz पर `/api/audit/status` को पोल करता है; एक चिपचिपी गुलाबी प्रगति पट्टी रन के दौरान व्यूपोर्ट के शीर्ष पर खुद को पिन करती है एक समय बीता टाइमर के साथ, और सफलता पर ताजा परिणाम जगह में स्वैप करता है (कोई पूर्ण-पृष्ठ पुनः लोड नहीं; एक विफल पुनः-ऑडिट पूर्व रिपोर्ट को अक्षुण्ण छोड़ता है)। विफलता पर पट्टी `RerunError.kind` (`timeout` / `network` / `post_failed`) से कॉपी किए गए लाल हो जाती है। खाली स्थिति (कोई कैश या समाप्त नहीं) और शून्य-सेशन स्थिति (कैश मौजूद है लेकिन स्कैन को कोई ट्रांसक्रिप्ट नहीं मिली) अलग से सामने आती हैं। ### नीतियां @@ -76,16 +75,16 @@ failproofai - - एक पैनल से failproofai जो एजेंट CLIs की सुरक्षा करता है उसे बहु-चयन करें — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, और Gemini CLI सभी के पास स्थापना स्थिति (`Active` / `Detected` / `Inactive`), उपयोगकर्ता-स्कोप सेटिंग्स पथ, और ब्रांड-रंगीन उच्चारण के साथ एक पंक्ति है। उन CLIs को चेक या अनचेक करें जिन्हें आप चाहते हैं और एक ही चरण में स्थापित/अनस्थापित के अंतर को लागू करने के लिए `Apply changes` पर क्लिक करें। CLIs जिनके बाइनरी PATH पर पाए जाते हैं पूर्व-चेक किए जाते हैं। - - एक एकल क्लिक के साथ व्यक्तिगत नीतियों को चालू या बंद करें (`~/.failproofai/policies-config.json` में लिखता है — हर स्थापित CLI के बीच साझा किया जाता है) - - एक नीति का विस्तार करें इसके पैरामीटर को कॉन्फ़िगर करने के लिए (जो नीतियां `policyParams` का समर्थन करती हैं) + - एकल पैनल से failproofai किस एजेंट CLI की रक्षा करता है, इसे बहु-चयन करें — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Gemini CLI, और Hermes सभी के पास स्थापना स्थिति (`Active` / `Detected` / `Inactive`) वाली एक पंक्ति है, उपयोगकर्ता-स्कोप सेटिंग्स पथ, और एक ब्रांड-रंगीन उच्चारण। आप जिन CLI चाहते हैं उन्हें चेक करें या अनचेक करें और `Apply changes` पर क्लिक करके एक चरण में इंस्टॉल/अनइंस्टॉल करने के लिए अंतर लागू करें। CLI जिनके बाइनरी को PATH पर पता चला है, पूर्व-जांच किए जाते हैं। + - एकल क्लिक के साथ व्यक्तिगत नीतियों को चालू या बंद करें (`~/.failproofai/policies-config.json` में लिखते हैं — हर इंस्टॉल किए गए CLI में साझा) + - एक नीति का विस्तार करके इसके पैरामीटर को कॉन्फ़िगर करें (उन नीतियों के लिए जो `policyParams` को समर्थन करती हैं) - एक कस्टम नीति फाइल पथ सेट करें - - सभी सेशन में फायरिंग की गई हर हुक गतिविधि का पूर्ण पृष्ठांकित इतिहास - - निर्णय, घटना प्रकार, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(बीटा)_ / Cursor Agent _(बीटा)_ / OpenCode _(बीटा)_ / Pi _(बीटा)_ / Gemini CLI _(बीटा)_), नीति नाम, या सेशन ID द्वारा फ़िल्टर करें - - प्रत्येक पंक्ति दिखाती है: समय, नीति नाम, निर्णय, CLI बैज (नारंगी = Claude Code, बैंगनी = OpenAI Codex, नीला = GitHub Copilot, पन्ना = Cursor Agent, एम्बर = OpenCode, गुलाबी = Pi, आकाश = Gemini CLI), टूल नाम, सेशन 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`) और हेडर में मिलान CLI बैज प्रदान करता है + - सभी सेशन में फायर किए गए प्रत्येक हुक ईवेंट का पूर्ण पृष्ठांकित इतिहास + - निर्णय, ईवेंट प्रकार, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Gemini CLI _(beta)_ / Hermes), नीति नाम, या सेशन ID द्वारा फ़िल्टर करें + - प्रत्येक पंक्ति दिखाती है: टाइमस्टैम्प, नीति नाम, निर्णय, CLI बैज (नारंगी = Claude Code, बैंगनी = OpenAI Codex, नीला = GitHub Copilot, पन्ना = Cursor Agent, एम्बर = OpenCode, गुलाबी = Pi, आसमानी = Gemini CLI, गहरा नीला = Hermes), टूल नाम, सेशन 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`, Hermes `~/.hermes/state.db`) और शीर्षलेख में मेल खाने वाले CLI बैज को प्रदान करता है @@ -93,13 +92,13 @@ failproofai ## स्वचालित रीफ्रेश -डैशबोर्ड में शीर्ष नेविगेशन में एक स्वचालित-रीफ्रेश टॉगल है। जब सक्षम होता है, तो वर्तमान पृष्ठ नई सेशन और नीति गतिविधि दिखाने के लिए समय-समय पर ताज़ा होता है जैसे ही वे दिखाई देते हैं। दीर्घकालीन स्वायत्त एजेंट सेशन की निगरानी के लिए आवश्यक। +डैशबोर्ड के शीर्ष नेविगेशन में एक स्वचालित-रीफ्रेश टॉगल है। सक्षम होने पर, वर्तमान पृष्ठ नए सेशन और नीति गतिविधि दिखाने के लिए आवधिक रूप से रीफ्रेश होता है जैसे वे प्रकट होते हैं। दीर्घकालिक स्वायत्त एजेंट सेशन की निगरानी के लिए आवश्यक। --- -## पृष्ठों को अक्षम करना +## पृष्ठ अक्षम करना -यदि आपको केवल डैशबोर्ड के कुछ भाग की आवश्यकता है, तो `FAILPROOFAI_DISABLE_PAGES` को पृष्ठ नामों की अल्पविराम-सीमांकित सूची पर सेट करें: +यदि आपको डैशबोर्ड के केवल कुछ भाग की आवश्यकता है, तो `FAILPROOFAI_DISABLE_PAGES` को अल्पविराम-अलग पृष्ठ नामों की सूची पर सेट करें: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -109,7 +108,7 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai --- -## प्रोजेक्ट पथ को कॉन्फ़िगर करना +## प्रोजेक्ट पथ कॉन्फ़िगर करना डिफ़ॉल्ट रूप से, डैशबोर्ड मानक Claude Code प्रोजेक्ट निर्देशिका से पढ़ता है। कस्टम सेटअप के लिए इसे ओवरराइड करें: @@ -119,32 +118,32 @@ 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) websocket के क्रॉस-ऑरिजिन एक्सेस को ब्लॉक कर रहा है, जो एक dev-only सुविधा है। अपने होस्ट को अनुमति देने के लिए, `--allowed-origins` फ़्लैग का उपयोग करें: +यह Next.js इसके HMR (हॉट मॉड्यूल रीलोड) वेबसॉकेट के लिए क्रॉस-ऑरिजिन एक्सेस को ब्लॉक कर रहा है, जो एक dev-only सुविधा है। आपके होस्ट को अनुमति देने के लिए, `--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 mode पर लागू होता है। जब `failproofai` चलाया जाता है (production mode), कोई HMR websocket और कोई क्रॉस-ऑरिजिन dev संसाधन समस्या नहीं है। +यह केवल dev मोड पर लागू होता है। `failproofai` (उत्पादन मोड) चलाते समय, कोई HMR वेबसॉकेट नहीं है और कोई क्रॉस-ऑरिजिन dev संसाधन समस्या नहीं है। \ No newline at end of file diff --git a/docs/hi/examples.mdx b/docs/hi/examples.mdx index 2aa6a139..751ef2ad 100644 --- a/docs/hi/examples.mdx +++ b/docs/hi/examples.mdx @@ -1,17 +1,16 @@ --- ---- title: उदाहरण -description: "Claude Code और Agents SDK के लिए hooks कैसे सेट करें" +description: "Claude Code और Agents SDK के लिए hooks सेट अप करने का तरीका" icon: book-open --- -सामान्य परिदृश्यों के लिए तैयार उदाहरण। प्रत्येक बताता है कि कैसे इंस्टॉल करें और क्या उम्मीद करें। +सामान्य परिदृश्यों के लिए तुरंत उपयोग के लिए तैयार उदाहरण। प्रत्येक दिखाता है कि कैसे इंस्टॉल करें और क्या उम्मीद करनी चाहिए। --- -## Claude Code के लिए hooks सेट करना +## Claude Code के लिए hooks सेट अप करना -Failproof AI Claude Code के साथ अपने [hooks system](https://docs.anthropic.com/en/docs/claude-code/hooks) के माध्यम से एकीकृत होता है। जब आप `failproofai policies --install` चलाते हैं, तो यह Claude Code के `settings.json` में hook commands को पंजीकृत करता है जो हर tool call पर चलते हैं। +Failproof AI Claude Code के साथ इसके [hooks system](https://docs.anthropic.com/en/docs/claude-code/hooks) के माध्यम से एकीकृत होता है। जब आप `failproofai policies --install` चलाते हैं, तो यह Claude Code के `settings.json` में hook कमांड्स को रजिस्टर करता है जो हर tool कॉल पर चलते हैं। @@ -19,32 +18,32 @@ Failproof AI Claude Code के साथ अपने [hooks system](https://do npm install -g failproofai ``` - + ```bash failproofai policies --install ``` - + ```bash cat ~/.claude/settings.json | grep failproofai ``` - आपको `PreToolUse`, `PostToolUse`, `Notification`, और `Stop` events के लिए hook entries दिखनी चाहिए। + आपको `PreToolUse`, `PostToolUse`, `Notification`, और `Stop` events के लिए hook entries दिखाई देने चाहिए। ```bash claude ``` - Policies अब हर tool call पर स्वचालित रूप से चलती हैं। Claude को `sudo rm -rf /` चलाने के लिए कहने का प्रयास करें - यह अवरुद्ध होगा। + Policies अब हर tool कॉल पर स्वचालित रूप से चलते हैं। Claude से `sudo rm -rf /` चलाने के लिए कहने का प्रयास करें - यह ब्लॉक किया जाएगा। --- -## Agents SDK के लिए hooks सेट करना +## Agents SDK के लिए hooks सेट अप करना -यदि आप [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) के साथ बना रहे हैं, तो आप समान hook system को प्रोग्राम के अनुसार उपयोग कर सकते हैं। +यदि आप [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) के साथ निर्माण कर रहे हैं, तो आप समान hook system को प्रोग्रामेटिक रूप से उपयोग कर सकते हैं। @@ -53,11 +52,11 @@ Failproof AI Claude Code के साथ अपने [hooks system](https://do ``` - अपने agent process बनाते समय hook commands पास करें। Hooks उसी तरह चलते हैं जैसे Claude Code में - stdin/stdout JSON के माध्यम से: + अपने agent process को बनाते समय hook कमांड्स पास करें। Hooks Claude Code की तरह ही काम करते हैं - stdin/stdout JSON के माध्यम से: ```bash - failproofai --hook PreToolUse # हर tool से पहले कहा जाता है - failproofai --hook PostToolUse # हर tool के बाद कहा जाता है + failproofai --hook PreToolUse # प्रत्येक tool से पहले कॉल किया जाता है + failproofai --hook PostToolUse # प्रत्येक tool के बाद कॉल किया जाता है ``` @@ -66,19 +65,19 @@ Failproof AI Claude Code के साथ अपने [hooks system](https://do customPolicies.add({ name: "limit-to-project-dir", - description: "Agent को project directory के अंदर रखें", + description: "Agent को प्रोजेक्ट डायरेक्टरी के अंदर रखें", match: { events: ["PreToolUse"] }, fn: async (ctx) => { const path = String(ctx.toolInput?.file_path ?? ""); if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) { - return deny("Agent project directory तक सीमित है"); + return deny("Agent प्रोजेक्ट डायरेक्टरी तक सीमित है"); } return allow(); }, }); ``` - + ```bash failproofai policies --install --custom ./my-agent-policies.js ``` @@ -87,35 +86,35 @@ Failproof AI Claude Code के साथ अपने [hooks system](https://do --- -## विनाशकारी commands को ब्लॉक करें +## विनाशकारी कमांड्स को ब्लॉक करें -सबसे सामान्य सेटअप - agents को अपरिवर्तनीय नुकसान करने से रोकें। +सबसे सामान्य सेटअप - agents को अपरिवर्तनीय नुकसान से बचाएं। ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` यह क्या करता है: -- `block-sudo` - सभी `sudo` commands को अवरुद्ध करता है -- `block-rm-rf` - recursive file deletion को अवरुद्ध करता है -- `block-force-push` - `git push --force` को अवरुद्ध करता है -- `block-curl-pipe-sh` - remote scripts को shell में pipe करने को अवरुद्ध करता है +- `block-sudo` - सभी `sudo` कमांड्स को ब्लॉक करता है +- `block-rm-rf` - recursive file deletion को ब्लॉक करता है +- `block-force-push` - `git push --force` को ब्लॉक करता है +- `block-curl-pipe-sh` - दूरस्थ scripts को shell में piping करने को ब्लॉक करता है --- ## Secret leakage को रोकें -Agents को tool output में credentials देखने या leak करने से रोकें। +Agents को tool output में credentials को देखने या leak करने से रोकें। ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -ये `PostToolUse` पर चलती हैं - एक tool चलने के बाद, वे output को agent के देखने से पहले साफ करती हैं। +ये `PostToolUse` पर चलते हैं - एक tool के चलने के बाद, वे output को agent से देखने से पहले साफ करते हैं। --- -## Agents को attention की आवश्यकता होने पर Slack alerts प्राप्त करें +## जब agents को ध्यान की आवश्यकता हो तो Slack alerts प्राप्त करें Notification hook का उपयोग करके idle alerts को Slack में भेजें। @@ -124,13 +123,13 @@ import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "slack-on-idle", - description: "जब agent input की प्रतीक्षा में हो तो Slack को alert करें", + description: "जब agent input के लिए प्रतीक्षा कर रहा हो तो Slack को alert करें", match: { events: ["Notification"] }, fn: async (ctx) => { const webhookUrl = process.env.SLACK_WEBHOOK_URL; if (!webhookUrl) return allow(); - const message = String(ctx.payload?.message ?? "Agent प्रतीक्षा में है"); + const message = String(ctx.payload?.message ?? "Agent प्रतीक्षा कर रहा है"); const project = ctx.session?.cwd ?? "unknown"; try { @@ -143,7 +142,7 @@ customPolicies.add({ signal: AbortSignal.timeout(5000), }); } catch { - // अगर Slack अप्राप्य है तो कभी भी agent को block न करें + // अगर Slack तक नहीं पहुंचा जा सकता तो कभी भी agent को ब्लॉक न करें } return allow(); @@ -168,7 +167,7 @@ import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "stay-on-branch", - description: "Agent को अन्य branches check out करने से रोकें", + description: "Agent को अन्य branches को checkout करने से रोकें", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); @@ -185,20 +184,20 @@ customPolicies.add({ ## Commits से पहले tests की आवश्यकता करें -Agents को commit करने से पहले tests चलाने के लिए remind करें। +Agents को commit से पहले tests चलाने के लिए याद दिलाएं। ```javascript import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "test-before-commit", - description: "Agent को commit करने से पहले tests चलाने के लिए remind करें", + description: "Agent को commit से पहले tests चलाने के लिए याद दिलाएं", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); if (/git\s+commit/.test(cmd)) { - return instruct("Commit करने से पहले tests चलाएं। पहले `npm test` या `bun test` का उपयोग करें।"); + return instruct("Commit से पहले tests चलाएं। पहले `npm test` या `bun test` का उपयोग करें।"); } return allow(); }, @@ -207,7 +206,7 @@ customPolicies.add({ --- -## Production repo को lock down करें +## एक production repo को lock down करें एक project-level config को commit करें ताकि आपकी team के हर developer को समान policies मिलें। @@ -239,16 +238,16 @@ git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -जिस हर team member के पास failproofai installed है वह स्वचालित रूप से इन नियमों को उठा लेगा। +हर team member जिसके पास failproofai इंस्टॉल है, ये rules स्वचालित रूप से pick up करेगा। --- ## Convention policies के साथ एक org-wide quality standard बनाएं -सबसे प्रभावशाली सेटअप: `.failproofai/policies/` को अपने repo में commit करें अपने project के अनुरूप policies के साथ। हर team member को स्वचालित रूप से ये मिलते हैं — कोई install commands नहीं, कोई config changes नहीं। +सबसे प्रभावशाली सेटअप: अपने repo में `.failproofai/policies/` को commit करें जिसमें आपके project के लिए tailored policies हों। हर team member को वे स्वचालित रूप से मिलते हैं — कोई install कमांड नहीं, कोई config changes नहीं। - + ```bash mkdir -p .failproofai/policies ``` @@ -265,19 +264,19 @@ git commit -m "Add failproofai team policies" fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); - if (/\bnpm\b/.test(cmd)) return deny("npm की बजाय bun का उपयोग करें।"); + if (/\bnpm\b/.test(cmd)) return deny("npm के बजाय bun का उपयोग करें।"); return allow(); }, }); - // Agent को commit करने से पहले tests चलाने के लिए remind करें + // Agent को commit से पहले tests चलाने के लिए याद दिलाएं customPolicies.add({ name: "test-before-commit", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) { - return instruct("Commit करने से पहले tests चलाएं।"); + return instruct("Commit से पहले tests चलाएं।"); } return allow(); }, @@ -290,16 +289,16 @@ git commit -m "Add failproofai team policies" git commit -m "Add team quality policies" ``` - - जैसे-जैसे आपकी team को नए failure modes का सामना करता है, policies जोड़ें और push करें। हर कोई अपने अगले `git pull` पर update प्राप्त करता है। ये policies एक living quality standard बन जाती हैं जो आपकी team के साथ बढ़ती हैं। + + जब आपकी team को नई failure modes का सामना करना पड़े, policies जोड़ें और push करें। हर कोई अपने अगले `git pull` पर update प्राप्त करेगा। ये policies एक living quality standard बन जाते हैं जो आपकी team के साथ बढ़ते हैं। --- -## अधिक उदाहरण +## और उदाहरण -Repo में [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) directory में शामिल हैं: +Repo में [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) डायरेक्टरी में शामिल हैं: | File | यह क्या दिखाता है | |------|---------------| diff --git a/docs/hi/for-agents.mdx b/docs/hi/for-agents.mdx index 4713c24e..a0a76497 100644 --- a/docs/hi/for-agents.mdx +++ b/docs/hi/for-agents.mdx @@ -1,38 +1,38 @@ --- title: "एजेंट्स के लिए" -description: "एक कमांड में अपने कोडिंग एजेंट को Failproof AI ज्ञान जोड़ें। Claude Code, Cursor, Windsurf और अन्य के साथ काम करता है।" +description: "एक कमांड में अपने कोडिंग एजेंट को Failproof AI नॉलेज से जोड़ें। Claude Code, Cursor, Windsurf और अन्य के साथ काम करता है।" --- -एक कमांड में अपने कोडिंग एजेंट को पूरी Failproof AI रेफरेंस जोड़ें। Claude Code, Cursor, Windsurf और किसी भी अन्य एजेंट के साथ काम करता है जो स्किल्स को सपोर्ट करता है। +एक कमांड में अपने कोडिंग एजेंट को पूर्ण Failproof AI संदर्भ से जोड़ें। Claude Code, Cursor, Windsurf और किसी भी अन्य एजेंट के साथ काम करता है जो स्किल्स को सपोर्ट करते हैं। ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` यह डिटेक्ट करता है कि आपके पास कौन से एजेंट इंस्टॉल हैं और प्रत्येक के लिए स्वचालित रूप से सही फॉर्मेट में स्किल जोड़ता है। +`npx skills` आपके द्वारा इंस्टॉल किए गए एजेंट्स को डिटेक्ट करता है और स्किल को प्रत्येक के लिए सही फॉर्मेट में स्वचालित रूप से जोड़ता है। -## स्किल में क्या शामिल है +## स्किल क्या कवर करता है | क्षेत्र | क्या शामिल है | |------|----------------| -| Policies | बिल्ट-इन पॉलिसी के नाम, इवेंट टाइप, पैरामीटर, एनेबल/डिसेबल | -| Custom policies | `customPolicies.add()`, मैच फिल्टर, `allow`/`deny`/`instruct` API | -| Context object | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | -| Configuration | `policies-config.json` संरचना, स्कोप मर्जिंग, `policyParams` | +| नीतियां | बिल्ट-इन पॉलिसी नाम, इवेंट टाइप, पैरामीटर, सक्षम/अक्षम करें | +| कस्टम पॉलिसीज | `customPolicies.add()`, मैच फिल्टर, `allow`/`deny`/`instruct` API | +| संदर्भ ऑब्जेक्ट | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | +| कॉन्फ़िगरेशन | `policies-config.json` संरचना, स्कोप मर्जिंग, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, स्कोप्स | -| Dashboard | सेशन व्यूअर, पॉलिसी एक्टिविटी, एनवायरनमेंट वेरिएबल्स | -| Architecture | हुक हैंडलर फ्लो, एक्जिट कोड्स, stdin/stdout कॉन्ट्रैक्ट | +| डैशबोर्ड | सेशन व्यूअर, पॉलिसी गतिविधि, पर्यावरण चर | +| आर्किटेक्चर | हुक हैंडलर फ्लो, एक्जिट कोड, stdin/stdout कॉन्ट्रैक्ट | -## क्या स्किल संपूर्ण है? +## क्या स्किल पूरी है? -Mintlify नेविगेशन में सभी पृष्ठों से `llms.txt` जेनरेट करता है। Failproof AI डॉक्स पूरी API को कवर करते हैं - हर पॉलिसी, ऑप्शन और उदाहरण शामिल है। यदि आपको कुछ गायब मिले, तो सोर्स `https://docs.befailproof.ai/llms-full.txt` पर है। +Mintlify नेविगेशन में सभी पेजों से `llms.txt` जेनरेट करता है। Failproof AI दस्तावेज़ पूर्ण API को कवर करते हैं - प्रत्येक पॉलिसी, विकल्प और उदाहरण शामिल हैं। यदि आपको कुछ कमी मिलती है, तो स्रोत `https://docs.befailproof.ai/llms-full.txt` पर है। -लक्षित संदर्भ के लिए, सीधे किसी विशिष्ट पृष्ठ से लिंक करें: +लक्षित संदर्भ के लिए, सीधे किसी विशिष्ट पेज से लिंक करें: ```bash -# सिर्फ कस्टम पॉलिसीज API +# केवल कस्टम पॉलिसीज API npx skills add https://docs.befailproof.ai/custom-policies -# सिर्फ बिल्ट-इन पॉलिसीज +# केवल बिल्ट-इन पॉलिसीज npx skills add https://docs.befailproof.ai/built-in-policies ``` \ No newline at end of file diff --git a/docs/hi/getting-started.mdx b/docs/hi/getting-started.mdx index 4eab9a1a..b7f3787d 100644 --- a/docs/hi/getting-started.mdx +++ b/docs/hi/getting-started.mdx @@ -1,13 +1,13 @@ --- title: शुरुआत करें -description: "failproofai इंस्टॉल करें, policies सक्षम करें, और अपने agents को विश्वसनीयता से चलाएं" +description: "failproofai इंस्टॉल करें, policies को सक्षम करें, और अपने agents को विश्वसनीयता से चलाएं" icon: rocket --- ## आवश्यकताएं - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (वैकल्पिक - केवल source से build करने के लिए आवश्यक) +- **Bun** >= 1.3.0 (वैकल्पिक - केवल स्रोत से बनाने के लिए आवश्यक) --- @@ -30,16 +30,16 @@ bun add -g failproofai ## त्वरित शुरुआत - - Policies वे नियम हैं जो प्रत्येक agent tool call से पहले और बाद में चलते हैं। वे destructive commands, secret leakage, और अन्य failure modes को नुकसान पहुंचाने से पहले रोक देते हैं। + + Policies नियम हैं जो हर agent tool call से पहले और बाद में चलते हैं। ये विनाशकारी commands, secret leakage, और अन्य failure modes को नुकसान पहुंचने से पहले पकड़ते हैं। ```bash failproofai policies --install ``` - यह आपके installed agent CLIs में hook entries लिखता है (Claude Code का `~/.claude/settings.json`, OpenAI Codex का `~/.codex/hooks.json`, GitHub Copilot CLI का `~/.copilot/hooks/failproofai.json`, Cursor Agent का `~/.cursor/hooks.json`, OpenCode का generated plugin shim `~/.config/opencode/plugins/failproofai.mjs` और `~/.config/opencode/opencode.json` के `plugin` array में एक registration entry, Pi का `~/.pi/agent/settings.json`, या Gemini CLI का `~/.gemini/settings.json`)। जब एक से अधिक मौजूद हों तो आपसे पूछा जाएगा; prompt को छोड़ने के लिए `--cli claude codex copilot cursor opencode pi gemini` (किसी भी subset) पास करें। + यह आपके इंस्टॉल किए गए agent CLIs में hook entries लिखता है (Claude Code के `~/.claude/settings.json`, OpenAI Codex के `~/.codex/hooks.json`, GitHub Copilot CLI के `~/.copilot/hooks/failproofai.json`, Cursor Agent के `~/.cursor/hooks.json`, OpenCode के generated plugin shim में `~/.config/opencode/plugins/failproofai.mjs` plus `~/.config/opencode/opencode.json` के `plugin` array में एक registration entry, Pi के `~/.pi/agent/settings.json`, Gemini CLI के `~/.gemini/settings.json`, या Hermes के `~/.hermes/config.yaml`)। जब एक से अधिक मौजूद हों तो आपसे prompt किया जाएगा; prompt को छोड़ने के लिए `--cli claude codex copilot cursor opencode pi gemini hermes` (कोई भी subset) पास करें। - GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, और Gemini CLI support **beta** में हैं — `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, या `--cli gemini` के साथ इंस्टॉल करें। + GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, और Gemini CLI सपोर्ट **beta** है — `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, या `--cli gemini` के साथ इंस्टॉल करें। Hermes (hermes-agent, एक Slack/Telegram gateway) user-scope के साथ `--cli hermes` के साथ इंस्टॉल होता है और **साथ ही** एक offline audit source है। ```bash failproofai policies --install --scope project @@ -49,6 +49,7 @@ bun add -g failproofai failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project + failproofai policies --install --cli hermes --scope user failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` @@ -57,17 +58,17 @@ bun add -g failproofai failproofai policies ``` - हर policy, चाहे वह सक्षम है या नहीं, और किसी भी configured parameters को दिखाता है। + हर policy दिखाता है, चाहे वह सक्षम हो, और कोई भी configured parameters। ```bash failproofai ``` - `http://localhost:8020` पर एक local dashboard खोलता है जहां आप sessions browse कर सकते हैं, tool calls inspect कर सकते हैं, और policies manage कर सकते हैं। + `http://localhost:8020` पर एक local dashboard खोलता है जहां आप sessions को ब्राउज कर सकते हैं, tool calls की जांच कर सकते हैं, और policies को manage कर सकते हैं। - Claude Code को सामान्य रूप से शुरू करें। अगर agent कुछ risky करने की कोशिश करता है, तो failproofai इसे स्वचालित रूप से intercept करता है। इसे unattended चलाएं और dashboard में समीक्षा करें कि क्या हुआ। + Claude Code को सामान्य तरीके से शुरू करें। अगर agent कुछ जोखिम भरा करने की कोशिश करता है, तो failproofai इसे स्वचालित रूप से intercept करता है। इसे unattended चलाएं और dashboard में देखें कि क्या हुआ। @@ -75,29 +76,29 @@ bun add -g failproofai ## Policies कैसे काम करती हैं -जब भी एक agent एक tool चलाता है, Claude Code failproofai को एक subprocess के रूप में कॉल करता है: +हर बार जब एक agent किसी tool को चलाता है, Claude Code failproofai को एक subprocess के रूप में कॉल करता है: ```text Claude Code → failproofai --hook PreToolUse → stdin JSON पढ़ता है policies का मूल्यांकन करता है - stdout को decision लिखता है + stdout पर निर्णय लिखता है ``` -प्रत्येक policy तीन decisions में से एक लौटाता है: +प्रत्येक policy तीन निर्णयों में से एक देता है: - **allow** - agent सामान्य रूप से आगे बढ़ता है -- **deny** - action को block किया जाता है, agent को बताया जाता है कि क्यों -- **instruct** - extra context agent के prompt में जोड़ा जाता है +- **deny** - कार्रवाई को ब्लॉक किया जाता है, agent को बताया जाता है कि क्यों +- **instruct** - agent के prompt में extra context जोड़ा जाता है -Policies आपकी local process में चलती हैं। कुछ भी किसी remote service को नहीं भेजा जाता है। +Policies आपकी local process में चलती हैं। कुछ भी remote service को नहीं भेजा जाता है। --- ## Convention-based policies के साथ team policies सेट अप करें -अपनी team में quality standards स्थापित करने का सबसे तेज़ तरीका `.failproofai/policies/` convention है। इस directory में policy files डालें और वे स्वचालित रूप से load हो जाते हैं — कोई flags नहीं, कोई config changes नहीं, कोई install commands नहीं। +अपनी team के across quality standards स्थापित करने का सबसे तेज़ तरीका `.failproofai/policies/` convention है। इस directory में policy files डालें और वे automatically लोड हो जाती हैं — कोई flags नहीं, कोई config changes नहीं, कोई install commands नहीं। @@ -106,7 +107,7 @@ Policies आपकी local process में चलती हैं। कु ``` - Starter examples copy करें या अपने स्वयं के बनाएं: + Starter examples को कॉपी करें या अपने स्वयं के लिखें: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -124,7 +125,7 @@ Policies आपकी local process में चलती हैं। कु fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) { - return instruct("Commit से पहले tests चलाएं।"); + return instruct("Run tests before committing."); } return allow(); }, @@ -134,40 +135,40 @@ Policies आपकी local process में चलती हैं। कु ```bash git add .failproofai/policies/ - git commit -m "Team quality policies जोड़ें" + git commit -m "Add team quality policies" ``` - हर team member जिसके पास failproofai इंस्टॉल है ये policies स्वचालित रूप से उठाता है। कोई per-developer setup की आवश्यकता नहीं है। + हर team member जिसके पास failproofai इंस्टॉल है, ये policies automatically pick up करता है। कोई per-developer setup की आवश्यकता नहीं है। -अपने repo में `.failproofai/policies/` commit करें ताकि पूरी team एक ही standards share करे। जैसे-जैसे आपकी team नए failure modes की खोज करती है, policies जोड़ें और push करें — हर किसी को अपने अगले `git pull` पर update मिल जाता है। समय के साथ ये policies एक living quality standard बन जाती हैं जो likepostulate में सुधार होता रहता है। +अपने repo में `.failproofai/policies/` को commit करें ताकि पूरी team एक ही standards शेयर करे। जैसे-जैसे आपकी team नए failure modes को discover करती है, policies को जोड़ें और push करें — हर कोई अपने अगले `git pull` पर update प्राप्त करता है। समय के साथ ये policies एक living quality standard बन जाती हैं जो बेहतर होती रहती हैं। --- -## Data storage +## डेटा स्टोरेज सभी configuration और logs आपकी machine पर रहते हैं: -| Path | क्या store किया जाता है | +| Path | क्या स्टोर करता है | |------|----------------| | `~/.failproofai/policies-config.json` | Global policy config | | `~/.failproofai/hook-activity.jsonl` | Hook execution history | | `~/.failproofai/hook.log` | Custom hook errors के लिए debug log | | `.failproofai/policies-config.json` | Per-project config (committed) | -| `.failproofai/policies-config.local.json` | Personal overrides (gitignored) | +| `.failproofai/policies-config.local.json` | व्यक्तिगत overrides (gitignored) | --- -## Uninstalling +## अनइंस्टॉल करना ```bash failproofai policies --uninstall ``` -`~/.claude/settings.json` से hook entries को remove करता है। `~/.failproofai/` में config files को रखा जाता है। +`~/.claude/settings.json` से hook entries को हटाता है। `~/.failproofai/` में config files को रखा जाता है। --- diff --git a/docs/hi/introduction.mdx b/docs/hi/introduction.mdx index 8f70047d..1055e6cc 100644 --- a/docs/hi/introduction.mdx +++ b/docs/hi/introduction.mdx @@ -1,41 +1,42 @@ --- +--- title: "Failproof AI" -description: "FailproofAI एआई एजेंट्स को 39 अंतर्निर्मित विफलता नीतियाँ देता है जो लूप्स, सीक्रेट लीक्स, विनाशकारी टूल कॉल्स और बहुत कुछ को एक ही इंस्टॉल में पकड़ते हैं।" +description: "FailproofAI आपके AI एजेंट्स को 39 बिल्ट-इन फेलियर पॉलिसीज देता है जो लूप्स, सीक्रेट लीक्स, डिस्ट्रक्टिव टूल कॉल्स और अन्य समस्याओं को एक सिंगल इंस्टॉल में कैच करता है।" --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -**एआई विफलता हैंडलिंग**, **त्रुटि पुनरुद्धार**, और **एलएलएम विश्वसनीयता** के लिए हुक्स और नीतियाँ। अपने एआई एजेंट्स को **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, और **Agents SDK** में विश्वसनीय और स्वायत्त रूप से चलाते रहें। +**AI फेलियर हैंडलिंग**, **एरर रिकवरी**, और **LLM रिलायबिलिटी** के लिए हुक्स और पॉलिसीज। अपने AI एजेंट्स को **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, **Hermes**, और **Agents SDK** में विश्वसनीय और स्वायत्त रूप से चलाते रहें। -एआई एजेंट्स अनुमानित तरीकों से विफल होते हैं। वे विनाशकारी कमांड चलाते हैं, सीक्रेट्स लीक करते हैं, कार्य से भटक जाते हैं, लूप्स में फंस जाते हैं, या सीधे मुख्य शाखा में पुश करते हैं। अनुपस्थिति में, छोटी विफलताएं व्यापक आउटेज, लीक किए गए क्रेडेंशियल्स और खोए हुए काम में बदल जाती हैं। +AI एजेंट्स पूर्वानुमानित तरीकों से फेल होते हैं। वे डिस्ट्रक्टिव कमांड्स चलाते हैं, सीक्रेट्स लीक करते हैं, अपने टास्क से भटकते हैं, लूप्स में फंसते हैं, या सीधे मेन में पुश करते हैं। जब बिना निरीक्षण के छोड़ दिया जाता है, तो छोटी-मोटी विफलताएं आउटेजेस, लीक किए गए क्रेडेंशियल्स और खोए हुए कार्य में बदल जाती हैं। -FailproofAI इसे **नीतियों** के साथ हल करता है। ये नियम हर एजेंट टूल कॉल में हुक करते हैं ताकि **विफलताओं का पता लगाएँ**, **उन्हें कम करें** (ब्लॉक, निर्देश दें, सैनिटाइज़ करें), और **आपको सतर्क करें** जब कुछ ध्यान की आवश्यकता हो। एक स्थानीय डैशबोर्ड आपको बाद में हर टूल कॉल, एजेंट विफलता और पुनरुद्धार कार्रवाई की समीक्षा करने देता है। +FailproofAI इसे **पॉलिसीज** से हल करता है। ये नियम प्रत्येक एजेंट टूल कॉल में हुक करते हैं ताकि **फेलियर्स को डिटेक्ट** करें, **उन्हें कम करें** (ब्लॉक, इंस्ट्रक्ट, सैनिटाइज), और **आपको अलर्ट** करें जब कुछ ध्यान देने की जरूरत हो। एक लोकल डैशबोर्ड आपको बाद में प्रत्येक टूल कॉल, एजेंट फेलियर और रिकवरी एक्शन की समीक्षा करने देता है। -कोई डेटा आपकी मशीन से बाहर नहीं जाता है। +कोई डेटा आपकी मशीन से बाहर नहीं जाता। ## शुरुआत करें - - विनाशकारी कमांड्स को ब्लॉक करें, सीक्रेट लीकेज को रोकें, एजेंट्स को प्रोजेक्ट सीमाओं के अंदर रखें, और बहुत कुछ। सब कुछ बॉक्स के बाहर। + + डिस्ट्रक्टिव कमांड्स को ब्लॉक करें, सीक्रेट लीकेज रोकें, एजेंट्स को प्रोजेक्ट बाउंड्रीज के अंदर रखें और बहुत कुछ। सब कुछ बॉक्स के बाहर से। - - सरल allow / deny / instruct एपीआई के साथ JavaScript में अपने नियम लिखें। + + सिंपल allow / deny / instruct API के साथ JavaScript में अपने नियम लिखें। - देखें कि आपके एजेंट्स आपकी अनुपस्थिति में क्या करते थे। सेशन ब्राउज़ करें, टूल कॉल्स का निरीक्षण करें, देखें कि नीतियाँ कहाँ लागू हुईं। + देखें कि आपके एजेंट्स आपके दूर रहने के समय क्या करते थे। सेशन्स ब्राउज़ करें, टूल कॉल्स को इंस्पेक्ट करें, समीक्षा करें कि पॉलिसीज कहां फायर हुईं। - किसी भी नीति को बिना कोड के ट्यून करें। प्रति-प्रोजेक्ट या वैश्विक स्तर पर अनुमतिसूचियाँ, सुरक्षित शाखाएँ, या थ्रेशहोल्ड सेट करें। + बिना कोड के किसी भी पॉलिसी को ट्यून करें। अलाउलिस्ट्स, प्रोटेक्टेड ब्रांचेस, या थ्रेशहोल्ड्स प्रति-प्रोजेक्ट या ग्लोबली सेट करें। -## त्वरित शुरुआत +## क्विक स्टार्ट @@ -50,8 +51,8 @@ bun add -g failproofai ```bash -failproofai policies --install # नीतियों को सक्षम करें (या छोड़ें — पहले रन पर `failproofai` सेटअप की पेशकश करेगा) +failproofai policies --install # enable policies (या स्किप करें — `failproofai` पहली रन पर सेट अप करने का ऑफर देगा) failproofai # डैशबोर्ड लॉन्च करें ``` -पूरी व्याख्या के लिए [शुरुआत करने गाइड](/hi/getting-started) देखें। \ No newline at end of file +पूर्ण वॉकथ्रू के लिए [गेटिंग स्टार्टेड](/hi/getting-started) गाइड देखें। \ No newline at end of file diff --git a/docs/hi/package-aliases.mdx b/docs/hi/package-aliases.mdx index f979e9be..2a9712ef 100644 --- a/docs/hi/package-aliases.mdx +++ b/docs/hi/package-aliases.mdx @@ -1,12 +1,12 @@ --- -title: पैकेज एलियासेस -description: "पंजीकृत typosquat-रोकथाम एलियासेस और वे कैसे काम करते हैं" +title: पैकेज एलिएस +description: "पंजीकृत टाइपोस्क्वाट-प्रिवेंशन एलिएस और वे कैसे काम करते हैं" icon: copy --- ## आधिकारिक पैकेज -कैनोनिकल npm पैकेज है **`failproofai`**: +कैनोनिकल npm पैकेज **`failproofai`** है: ```bash npm install -g failproofai @@ -16,67 +16,67 @@ bun add -g failproofai --- -## हम एलियास नामों के मालिक क्यों हैं +## हम एलिएस नाम क्यों रखते हैं -Typosquatting एक सामान्य सप्लाई-चेन हमला है जहां एक दुर्भावनापूर्ण व्यक्ति एक पैकेज नाम पंजीकृत करता है जो एक लोकप्रिय पैकेज से एक कीस्ट्रोक दूर होता है। जो उपयोगकर्ता इंस्टॉल कमांड में गलती करते हैं, वे हमलावर द्वारा नियंत्रित कोड चलाते हैं जिसके पास पूर्ण सिस्टम एक्सेस होता है - बिल्कुल वही तरह का खतरा जिससे Failproof AI की रक्षा के लिए डिज़ाइन किया गया है। +टाइपोस्क्वाटिंग एक आम सप्लाई-चेन अटैक है जहां एक दुर्भावनापूर्ण अभिनेता एक लोकप्रिय पैकेज से एक कीस्ट्रोक दूर एक पैकेज नाम पंजीकृत करता है। जो अनजान उपयोगकर्ता इंस्टॉल कमांड को गलत तरीके से टाइप करते हैं वे पूर्ण सिस्टम एक्सेस के साथ अटैकर-नियंत्रित कोड चलाते हैं - बिल्कुल वह प्रकार का खतरा जिसके खिलाफ Failproof AI की रक्षा करने के लिए डिज़ाइन किया गया है। -इस सतह को खत्म करने के लिए, **हम npm पर `failproofai` के सभी सामान्य गलतियों और फॉर्मेटिंग वेरिएंट्स का पूर्वनिर्धारित मालिकाना है**। इनमें से कोई भी नाम तीसरे पक्ष द्वारा पंजीकृत नहीं किया जा सकता। प्रत्येक एक पतली प्रॉक्सी है जो वास्तविक `failproofai` पैकेज को इंस्टॉल करता है और प्रतिनिधित्व करता है। +इस सतह को खत्म करने के लिए, **हम npm पर `failproofai` के सभी सामान्य गलतियों और फॉर्मेटिंग वेरिएंट को सक्रिय रूप से रखते हैं**। इनमें से कोई भी नाम किसी तीसरे पक्ष द्वारा पंजीकृत नहीं किया जा सकता। प्रत्येक वास्तविक `failproofai` पैकेज को इंस्टॉल करने और सौंपने के लिए एक पतली प्रॉक्सी है। --- -## पंजीकृत एलियासेस +## पंजीकृत एलिएस -**फॉर्मेटिंग वेरिएंट्स** - "failproof ai" लिखने के विभिन्न तरीके: +**फॉर्मेटिंग वेरिएंट** - "failproof ai" को लिखने के विभिन्न तरीके: | पैकेज | स्थिति | |---------|--------| | `failproof` | ✅ प्रकाशित | -| `failproof-ai` | ⏳ npm समर्थन की प्रतीक्षा में | -| `fail-proof-ai` | ⏳ npm समर्थन की प्रतीक्षा में | -| `failproof_ai` | ⏳ npm समर्थन की प्रतीक्षा में | -| `fail_proof_ai` | ⏳ npm समर्थन की प्रतीक्षा में | -| `fail-proofai` | ⏳ npm समर्थन की प्रतीक्षा में | +| `failproof-ai` | ⏳ npm सपोर्ट की प्रतीक्षा में | +| `fail-proof-ai` | ⏳ npm सपोर्ट की प्रतीक्षा में | +| `failproof_ai` | ⏳ npm सपोर्ट की प्रतीक्षा में | +| `fail_proof_ai` | ⏳ npm सपोर्ट की प्रतीक्षा में | +| `fail-proofai` | ⏳ npm सपोर्ट की प्रतीक्षा में | -**`failprof*` typos** - "proof" से एक `o` गायब: +**`failprof*` टाइपो** - "proof" से एक `o` गायब: | पैकेज | स्थिति | |---------|--------| | `failprof` | ✅ प्रकाशित | | `failprof-ai` | ✅ प्रकाशित | -| `failprofai` | ⏳ npm समर्थन की प्रतीक्षा में | -| `fail-prof-ai` | ⏳ npm समर्थन की प्रतीक्षा में | -| `failprof_ai` | ⏳ npm समर्थन की प्रतीक्षा में | +| `failprofai` | ⏳ npm सपोर्ट की प्रतीक्षा में | +| `fail-prof-ai` | ⏳ npm सपोर्ट की प्रतीक्षा में | +| `failprof_ai` | ⏳ npm सपोर्ट की प्रतीक्षा में | -**`faliproof*` typos** - `a` और `i` को स्थानांतरित किया गया: +**`faliproof*` टाइपो** - ट्रांसपोज़्ड `a` और `i`: | पैकेज | स्थिति | |---------|--------| | `faliproof` | ✅ प्रकाशित | | `faliproof-ai` | ✅ प्रकाशित | -| `faliproofai` | ⏳ npm समर्थन की प्रतीक्षा में | +| `faliproofai` | ⏳ npm सपोर्ट की प्रतीक्षा में | -> **प्रतीक्षा में क्यों?** npm की स्पैम-रोकथाम नीति उन नामों को ब्लॉक करती है जो विद्यमान पैकेज के रूप में उसी स्ट्रिंग को सामान्य करते हैं विराम चिह्न को हटाने और समानता जांच चलाने के बाद। हमने इन नामों को एंटी-स्क्वाटिंग उद्देश्यों के लिए आरक्षित करने के लिए npm समर्थन से संपर्क किया है। अनुमोदन के बाद वे सक्रिय किए जाएंगे। +> **प्रतीक्षा में क्यों?** npm की स्पैम-प्रिवेंशन नीति उन नामों को ब्लॉक करती है जो विराम चिन्ह को हटाने और समानता जांच चलाने के बाद एक मौजूदा पैकेज के रूप में सामान्यीकृत होते हैं। हमने anti-squatting उद्देश्यों के लिए इन नामों को आरक्षित करने के लिए npm सपोर्ट से संपर्क किया है। वे मंजूरी मिलने के बाद सक्रिय किए जाएंगे। -आप यह सत्यापित कर सकते हैं कि कोई भी प्रकाशित एलियास हमारा है: +आप सत्यापित कर सकते हैं कि कोई भी प्रकाशित एलिएस हमारे द्वारा स्वामित्व में है: ```bash npm info failproof -# देखें: रखरखाव कर्ताओं क्षेत्र में "ExosphereHost Inc." +# देखें: रखरखाव कर्ताओं फील्ड में "ExosphereHost Inc." ``` --- -## एलियासेस कैसे काम करते हैं +## एलिएस कैसे काम करते हैं -प्रत्येक एलियास पैकेज: +प्रत्येक एलिएस पैकेज: 1. `failproofai` को एक निर्भरता के रूप में सूचीबद्ध करता है - इसलिए वास्तविक पैकेज (इसके `postinstall` हुक सेटअप सहित) इंस्टॉल पर चलता है -2. अपने स्वयं के नाम से मेल खाने वाली एक बाइनरी को expose करता है (जैसे `failprof-ai`) जो सभी तर्कों को `failproofai` बाइनरी को प्रॉक्सी करता है +2. अपने स्वयं के नाम से मेल खाने वाली एक बाइनरी को प्रकट करता है (उदा. `failprof-ai`) जो सभी तर्कों को `failproofai` बाइनरी के लिए प्रॉक्सी करता है -प्रॉक्सी एक दो-लाइन Node स्क्रिप्ट है; कोई तर्क नहीं है, कोई नेटवर्क कॉल नहीं है, और `failproofai` स्वयं क्या करता है उससे परे कोई डेटा संग्रह नहीं है। +प्रॉक्सी एक दो-पंक्ति Node स्क्रिप्ट है; कोई तर्क नहीं, कोई नेटवर्क कॉल नहीं, और `failproofai` स्वयं जो करता है उससे परे कोई डेटा संग्रह नहीं। --- -## यदि आपको कोई नाम मिला जो हमसे छूट गया है +## यदि आप एक नाम पाते हैं जो हमने मिस किया -[failproofai/failproofai](https://github.com/failproofai/failproofai/issues) पर एक समस्या खोलें और हम इसे पंजीकृत करेंगे। \ No newline at end of file +[failproofai/failproofai](https://github.com/failproofai/failproofai/issues) पर एक मुद्दा खोलें और हम इसे पंजीकृत करेंगे। \ No newline at end of file diff --git a/docs/hi/testing.mdx b/docs/hi/testing.mdx index 8fbf1190..4b9f3644 100644 --- a/docs/hi/testing.mdx +++ b/docs/hi/testing.mdx @@ -1,26 +1,26 @@ --- title: परीक्षण -description: "यूनिट परीक्षण, E2E परीक्षण, और परीक्षण सहायक" +description: "यूनिट टेस्ट, E2E टेस्ट, और टेस्ट हेल्पर्स" icon: flask-vial --- -failproofai के दो परीक्षण सेट हैं: **यूनिट परीक्षण** (तेज़, मॉक किए गए) और **end-to-end परीक्षण** (असली subprocess आमंत्रण)। +failproofai के दो टेस्ट सुइट हैं: **यूनिट टेस्ट** (तेज़, मॉक किए गए) और **एंड-टू-एंड टेस्ट** (वास्तविक सबप्रोसेस आह्वान)। --- -## परीक्षण चलाना +## टेस्ट चलाना ```bash -# सभी यूनिट परीक्षण एक बार चलाएं +# एक बार सभी यूनिट टेस्ट चलाएँ bun run test:run -# यूनिट परीक्षण watch मोड में चलाएं +# यूनिट टेस्ट को वॉच मोड में चलाएँ bun run test -# E2E परीक्षण चलाएं (सेटअप आवश्यक है - नीचे देखें) +# E2E टेस्ट चलाएँ (सेटअप की आवश्यकता - नीचे देखें) bun run test:e2e -# प्रकार की जांच बिना बिल्ड किए +# बिल्ड किए बिना टाइप-चेक करें bunx tsc --noEmit # लिंट करें @@ -29,19 +29,19 @@ bun run lint --- -## यूनिट परीक्षण +## यूनिट टेस्ट -यूनिट परीक्षण `__tests__/` में रहते हैं और [Vitest](https://vitest.dev) के साथ `jsdom` का उपयोग करते हैं। +यूनिट टेस्ट `__tests__/` में रहते हैं और [Vitest](https://vitest.dev) को `jsdom` के साथ उपयोग करते हैं। ```text __tests__/ hooks/ - builtin-policies.test.ts # प्रत्येक बिल्ट-इन के लिए नीति तर्क - hooks-config.test.ts # कॉन्फ़िग लोडिंग और स्कोप मर्ज करना + builtin-policies.test.ts # प्रत्येक बिल्टइन के लिए नीति तर्क + hooks-config.test.ts # कॉन्फ़िग लोडिंग और स्कोप मर्जिंग policy-evaluator.test.ts # पैरामीटर इंजेक्शन और मूल्यांकन क्रम custom-hooks-registry.test.ts # globalThis रजिस्ट्री add/get/clear - custom-hooks-loader.test.ts # ESM लोडर, transitive आयात, त्रुटि हैंडलिंग - manager.test.ts # install/remove/list संचालन + custom-hooks-loader.test.ts # ESM लोडर, ट्रांज़िटिव इंपोर्ट, त्रुटि हैंडलिंग + manager.test.ts # install/remove/list ऑपरेशन components/ sessions-list.test.tsx # सत्र सूची घटक project-list.test.tsx # प्रोजेक्ट सूची घटक @@ -61,7 +61,7 @@ __tests__/ AutoRefreshContext.test.tsx ``` -### नीति यूनिट परीक्षण लिखना +### नीति यूनिट टेस्ट लिखना ```typescript import { describe, it, expect, beforeEach } from "vitest"; @@ -108,51 +108,51 @@ describe("block-sudo", () => { --- -## End-to-end परीक्षण +## एंड-टू-एंड टेस्ट -E2E परीक्षण असली `failproofai` बाइनरी को subprocess के रूप में आमंत्रित करते हैं, JSON पेलोड को stdin में पाइप करते हैं, और stdout आउटपुट और exit कोड पर assertion करते हैं। यह उस संपूर्ण एकीकरण पथ को परीक्षण करता है जो Claude Code उपयोग करता है। +E2E टेस्ट वास्तविक `failproofai` बाइनरी को सबप्रोसेस के रूप में आह्वान करते हैं, stdin में JSON पेलोड पाइप करते हैं, और stdout आउटपुट और एक्जिट कोड पर दावे करते हैं। यह उस संपूर्ण एकीकरण पथ का परीक्षण करता है जो Claude Code उपयोग करता है। ### सेटअप -E2E परीक्षण रेपो स्रोत से सीधे बाइनरी चलाते हैं। पहली बार चलाने से पहले, CJS बंडल बनाएं जो कस्टम हुक फाइलें `'failproofai'` से आयात करते समय उपयोग करती हैं: +E2E टेस्ट रेपो स्रोत से सीधे बाइनरी चलाते हैं। पहली बार चलाने से पहले, CJS बंडल बनाएँ जो कस्टम हुक फ़ाइलें `'failproofai'` से आयात करने के समय उपयोग करती हैं: ```bash bun build src/index.ts --outdir dist --target node --format cjs ``` -फिर परीक्षण चलाएं: +फिर टेस्ट चलाएँ: ```bash bun run test:e2e ``` -जब भी आप सार्वजनिक हुक API (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, या `src/hooks/policy-types.ts`) को परिवर्तित करें, `dist/` को पुनः बनाएं। +जब भी आप सार्वजनिक हुक API को बदलें (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, या `src/hooks/policy-types.ts`), तो `dist/` को पुनः बनाएँ। -### E2E परीक्षण संरचना +### E2E टेस्ट संरचना ```text __tests__/e2e/ helpers/ - hook-runner.ts # बाइनरी spawn करें, पेलोड JSON पाइप करें, exit कोड + stdout + stderr कैप्चर करें - fixture-env.ts # प्रति-परीक्षण अलग अस्थायी निर्देशिकाएं कॉन्फ़िग फाइलों के साथ - payloads.ts # प्रत्येक इवेंट प्रकार के लिए Claude-सटीक पेलोड फैक्ट्रीज + hook-runner.ts # बाइनरी को स्पॉन करें, पेलोड JSON पाइप करें, एक्जिट कोड + stdout + stderr कैप्चर करें + fixture-env.ts # कॉन्फ़िग फ़ाइलों के साथ प्रति-टेस्ट अलग-थलग अस्थायी निर्देशिकाएँ + payloads.ts # प्रत्येक ईवेंट प्रकार के लिए Claude-सटीक पेलोड फैक्ट्रीज़ hooks/ - builtin-policies.e2e.test.ts # असली subprocess के साथ प्रत्येक बिल्ट-इन नीति + builtin-policies.e2e.test.ts # वास्तविक सबप्रोसेस के साथ प्रत्येक बिल्टइन नीति custom-hooks.e2e.test.ts # कस्टम हुक लोडिंग और मूल्यांकन - config-scopes.e2e.test.ts # project/local/global में कॉन्फ़िग मर्ज करना - policy-params.e2e.test.ts # प्रत्येक पैरामीटरयुक्त नीति के लिए पैरामीटर इंजेक्शन + config-scopes.e2e.test.ts # प्रोजेक्ट/लोकल/ग्लोबल में कॉन्फ़िग मर्जिंग + policy-params.e2e.test.ts # प्रत्येक पैरामीटराइज्ड नीति के लिए पैरामीटर इंजेक्शन ``` -### E2E सहायकों का उपयोग करना +### E2E हेल्पर्स का उपयोग करना -**`FixtureEnv`** - प्रति-परीक्षण अलग पर्यावरण: +**`FixtureEnv`** - प्रति-टेस्ट अलग-थलग वातावरण: ```typescript import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); // env.cwd - अस्थायी निर्देशिका; .failproofai/policies-config.json उठाने के लिए payload.cwd के रूप में पास करें -// env.home - अलग होम निर्देशिका; कोई वास्तविक ~/.failproofai लीक नहीं होता +// env.home - अलग-थलग होम निर्देशिका; वास्तविक ~/.failproofai लीक नहीं होता है env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -162,9 +162,9 @@ env.writeConfig({ }); ``` -`createFixtureEnv()` स्वचालित रूप से `afterEach` क्लीनअप पंजीकृत करता है। +`createFixtureEnv()` स्वचालित रूप से `afterEach` क्लीनअप रजिस्टर करता है। -**`runHook`** - बाइनरी को आमंत्रित करें: +**`runHook`** - बाइनरी को आह्वान करें: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - तैयार पेलोड फैक्ट्रीज: +**`Payloads`** - तैयार पेलोड फैक्ट्रीज़: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -192,7 +192,7 @@ Payloads.notification(message, cwd) Payloads.stop(cwd) ``` -### E2E परीक्षण लिखना +### E2E टेस्ट लिखना ```typescript import { describe, it, expect } from "vitest"; @@ -226,35 +226,35 @@ describe("block-rm-rf (E2E)", () => { ); expect(result.exitCode).toBe(0); - expect(result.stdout).toBe(""); // allow → खाली stdout + expect(result.stdout).toBe(""); // allow → empty stdout }); }); ``` ### E2E प्रतिक्रिया आकार -| निर्णय | Exit कोड | stdout | +| निर्णय | एक्जिट कोड | stdout | |----------|-----------|--------| | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | | Instruct (non-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop निर्देश | `2` | खाली stdout; stderr में कारण | +| Stop instruct | `2` | खाली stdout; stderr में कारण | | Allow | `0` | खाली स्ट्रिंग | ### Vitest कॉन्फ़िग -E2E परीक्षण `vitest.config.e2e.mts` का उपयोग करते हैं जिसमें है: +E2E टेस्ट `vitest.config.e2e.mts` के साथ उपयोग करते हैं: -- `environment: "node"` - कोई ब्राउज़र globals आवश्यक नहीं -- `pool: "forks"` - सच्चा प्रक्रिया अलगाव (परीक्षण subprocesses spawn करते हैं) -- `testTimeout: 20_000` - प्रति परीक्षण 20s (बाइनरी स्टार्टअप + हुक eval) +- `environment: "node"` - कोई ब्राउज़र ग्लोबल्स की आवश्यकता नहीं +- `pool: "forks"` - वास्तविक प्रक्रिया अलगाव (टेस्ट सबप्रोसेस स्पॉन करते हैं) +- `testTimeout: 20_000` - प्रति टेस्ट 20s (बाइनरी स्टार्टअप + हुक eval) -`forks` पूल महत्वपूर्ण है: thread-आधारित workers `globalThis` साझा करते हैं, जो subprocess-spawning परीक्षणों में हस्तक्षेप कर सकता है। Process-आधारित forks इससे बचते हैं। +`forks` पूल महत्वपूर्ण है: थ्रेड-आधारित वर्कर्स `globalThis` साझा करते हैं, जो सबप्रोसेस-स्पॉनिंग टेस्ट में हस्तक्षेप कर सकता है। प्रक्रिया-आधारित फोर्क्स इससे बचते हैं। --- ## CI -संपूर्ण CI चलाव (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) को मर्ज करने से पहले पास होना आवश्यक है। E2E सेट एक अलग CI कार्य के रूप में समानांतर में चलता है। +पूर्ण CI रन (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) को मर्ज करने से पहले पास होना आवश्यक है। E2E सुइट समानांतर में एक अलग CI जॉब के रूप में चलता है। -पूर्ण प्री-मर्ज चेकलिस्ट के लिए [Contributing](../CONTRIBUTING.md) देखें। \ No newline at end of file +पूर्ण प्री-मर्ज चेकलिस्ट के लिए [योगदान देना](../CONTRIBUTING.md) देखें। \ No newline at end of file diff --git a/docs/i18n/README.ar.md b/docs/i18n/README.ar.md index 7a1f761e..e5f60f40 100644 --- a/docs/i18n/README.ar.md +++ b/docs/i18n/README.ar.md @@ -19,19 +19,19 @@ **الترجمات:** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md) -**حل أعطال وقت التشغيل لوكلاء البرمجة.** -يتكامل مع Claude Code و Codex. يوقف الحلقات اللانهائية والإجراءات الخطيرة وتسريب الأسرار -قبل أن تصبح حوادث. بدون تأخير. يعمل محلياً. +**حل فشل وقت التشغيل لعوامل الترميز.** +ينجذب إلى Claude Code و Codex. يقبض على الحلقات والإجراءات الخطيرة وتسرب الأسرار +قبل أن تصبح حوادث. لا توجد زمن انتظار. يعمل محليًا.

- Failproof AI في العمل + Failproof AI in action

--- -## واجهات سطر الأوامر المدعومة للوكلاء +## واجهات سطر الأوامر المدعومة للعوامل

@@ -80,9 +80,18 @@ Gemini CLI +        + + + + Hermes + +

-> تثبيت الخطافات لواحد أو أي مزيج: `failproofai policies --install --cli opencode pi gemini` (أو `--cli claude codex copilot cursor opencode pi gemini`). تجاهل `--cli` للكشف التلقائي عن واجهات سطر الأوامر المثبتة والمطالبة بها. +> تثبيت الخطافات لواحدة أو أي مزيج: `failproofai policies --install --cli opencode pi gemini` (أو `--cli claude codex copilot cursor opencode pi gemini hermes`). احذف `--cli` للكشف التلقائي عن واجهات سطر الأوامر المثبتة والمطالبة. +> +> **Hermes** (hermes-agent، بوابة Slack/Telegram) مدعومة لكل من **فرض الخطاف الحي** (`--cli hermes` — التثبيت الواحد يعترض استدعاءات الأدوات من كل منصة ووكيل فرعي) والتدقيق غير المتصل **إعادة تشغيل** لجلسات البوابة من قاعدة البيانات الواحدة `~/.hermes/state.db`. --- @@ -90,32 +99,32 @@ ```sh npm install -g failproofai -failproofai policies --install # أو ما عليك سوى تشغيل `failproofai` وقبول المطالبة عند أول تشغيل +failproofai policies --install # أو فقط قم بتشغيل `failproofai` وقبل السؤال الأول failproofai ``` -30 سياسة مدمجة تنشط فوراً. لوحة تحكم في `localhost:8020`. عطّل مطالبة أول تشغيل باستخدام `FAILPROOFAI_NO_FIRST_RUN=1`. +30 سياسة مدمجة تُفعّل فوراً. لوحة التحكم على `localhost:8020`. تعطيل السؤال الأول باستخدام `FAILPROOFAI_NO_FIRST_RUN=1`. --- ## ما الذي يوقفه -| السياسة | ما يمنعه | +| السياسة | ما يحجبه | |---|---| | `block-push-master` | الدفع المباشر إلى `main` / `master` | | `block-force-push` | `git push --force` | -| `block-work-on-main` | التزامات وعمليات دمج وإعادة تأسيس على `main` / `master` | +| `block-work-on-main` | الالتزامات والدمج وإعادة القاعدة على `main` / `master` | | `block-rm-rf` | حذف الملفات بشكل متكرر | -| `sanitize-api-keys` | تسريب مفاتيح API إلى سياق الوكيل | +| `sanitize-api-keys` | مفاتيح واجهة البرمجة تتسرب إلى سياق الوكيل | -→ [جميع السياسات المدمجة البالغ عددها 30](https://docs.befailproof.ai/built-in-policies) +→ [جميع السياسات المدمجة الـ 30](https://docs.befailproof.ai/built-in-policies) --- ## سياساتك الخاصة -ضع ملف في `.failproofai/policies/` — سيتم تحميله تلقائياً، لا حاجة لأي علامات. -التزم به وستحصل الفريق بأكمله عليه في الطلب التالي. +ضع ملف في `.failproofai/policies/` — يتم تحميله تلقائياً، لا توجد علامات مطلوبة. +قم بالالتزام به وسيحصل الفريق بأكمله عليه في الطلب التالي. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -125,19 +134,19 @@ customPolicies.add({ match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolInput?.file_path?.includes("production")) - return deny("الكتابة إلى مسارات الإنتاج محظورة."); + return deny("Writes to production paths are blocked."); return allow(); }, }); ``` -ثلاثة قرارات متاحة لكل سياسة: +ثلاث قرارات متاحة لكل سياسة: | القرار | التأثير | |---|---| | `allow()` | السماح بالعملية | -| `deny(message)` | منعها — ترجع الرسالة إلى الوكيل | -| `instruct(message)` | السماح بها، لكن أضف سياقاً لمطالبة الوكيل التالية | +| `deny(message)` | حجبها — تعود الرسالة إلى الوكيل | +| `instruct(message)` | اسمح بها، لكن أضف سياق إلى موجه الوكيل التالي | → [دليل السياسات المخصصة](https://docs.befailproof.ai/custom-policies) @@ -145,22 +154,22 @@ customPolicies.add({ ## رؤية الجلسة -كل استدعاء أداة يجريها وكيلك يُسجل محلياً. تعرض لوحة التحكم ما تم تشغيله، -وما تم منعه، وما أخبرت به السياسة الوكيل — لذا لن تكون تخميناً +يتم تسجيل كل استدعاء أداة يقوم به الوكيل محليًا. لوحة التحكم توضح ما تم تشغيله، +وما تم حجبه، وما قالته السياسة للوكيل — لذلك لا تخمن عندما يحدث خطأ ما. → [دليل لوحة التحكم](https://docs.befailproof.ai/dashboard) --- -## التوثيق +## الوثائق | | | |---|---| | [البدء السريع](https://docs.befailproof.ai/getting-started) | التثبيت والخطوات الأولى | -| [السياسات المدمجة](https://docs.befailproof.ai/built-in-policies) | جميع السياسات الثلاثون مع المعاملات | -| [السياسات المخصصة](https://docs.befailproof.ai/custom-policies) | اكتب سياساتك الخاصة | +| [السياسات المدمجة](https://docs.befailproof.ai/built-in-policies) | جميع السياسات الـ 30 مع المعاملات | +| [السياسات المخصصة](https://docs.befailproof.ai/custom-policies) | اكتب الخاصة بك | | [التكوين](https://docs.befailproof.ai/configuration) | نطاقات التكوين وقواعد الدمج | | [لوحة التحكم](https://docs.befailproof.ai/dashboard) | مراقب الجلسة ونشاط السياسة | -| [العمارة](https://docs.befailproof.ai/architecture) | كيفية عمل نظام الخطافات | +| [العمارة](https://docs.befailproof.ai/architecture) | كيفية عمل نظام الخطاف | --- @@ -172,17 +181,17 @@ MIT مع [Commons Clause](https://commonsclause.com/) — مجاني للاست ## المساهمة -انظر [CONTRIBUTING.md](./CONTRIBUTING.md). السياسات الجديدة والحالات الحدية والترجمات جميعها مرحب بها. +انظر [CONTRIBUTING.md](./CONTRIBUTING.md). السياسات الجديدة وحالات الحافة والترجمات كلها مرحب بها. -> **بناء قبل أن تبدأ.** شغّل `bun install && bun run build` أولاً. يقوم هذا المستودع بتشغيل -> خطافات failproofai الخاصة به على نفسه، ويحل استيراد `failproofai` مقابل -> حزمة `dist/` المترجمة — بدون بناء ستواجه أخطاء خطافات `Cannot find package 'failproofai'` ->. أعد البناء بعد تغيير `src/`. انظر -> [بناء قبل أن تعمل خطافات dev في المستودع](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **بناء قبل البدء.** قم بتشغيل `bun install && bun run build` أولاً. هذا المستودع يشغل +> خطافات failproofai الخاصة به على نفسه، ويحلون استيراد `failproofai` مقابل +> حزمة `dist/` المترجمة — بدون بناء ستواجه `Cannot find package 'failproofai'` +> أخطاء الخطاف. أعد البناء بعد تغيير `src/`. انظر +> [البناء قبل أن تعمل الخطافات المتضمنة في المستودع](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -بنتج من قبل [Nivedit Jain](https://github.com/NiveditJain) و [Nikita Agarwal](https://github.com/nk-ag). +تم البناء بواسطة [Nivedit Jain](https://github.com/NiveditJain) و[Nikita Agarwal](https://github.com/nk-ag). [befailproof.ai](https://befailproof.ai) diff --git a/docs/i18n/README.de.md b/docs/i18n/README.de.md index a36e57b7..5c6f03dd 100644 --- a/docs/i18n/README.de.md +++ b/docs/i18n/README.de.md @@ -17,9 +17,9 @@ **Übersetzungen:** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md) -**Laufzeit-Fehlerbehebung für Coding-Agenten.** -Klinkt sich in Claude Code und Codex ein. Erkennt Endlosschleifen, gefährliche Aktionen und geheime Datenlecks, -bevor sie zu Vorfällen werden. Keine zusätzliche Latenz. Läuft lokal. +**Laufzeit-Fehlerbehebung für Coding-Agents.** +Klinkt sich in Claude Code und Codex ein. Erkennt Endlosschleifen, gefährliche Aktionen und Secret-Leaks, +bevor sie zu Vorfällen werden. Keine Latenz. Läuft lokal. @@ -29,7 +29,7 @@ bevor sie zu Vorfällen werden. Keine zusätzliche Latenz. Läuft lokal. --- -## Unterstützte Agenten-CLIs +## Unterstützte Agent-CLIs

@@ -78,9 +78,18 @@ bevor sie zu Vorfällen werden. Keine zusätzliche Latenz. Läuft lokal. Gemini CLI +        + + + + Hermes + +

-> Hooks für eine oder mehrere CLIs installieren: `failproofai policies --install --cli opencode pi gemini` (oder `--cli claude codex copilot cursor opencode pi gemini`). `--cli` weglassen, um installierte CLIs automatisch zu erkennen und eine Auswahl zu erhalten. +> Hooks für eine oder eine beliebige Kombination installieren: `failproofai policies --install --cli opencode pi gemini` (oder `--cli claude codex copilot cursor opencode pi gemini hermes`). `--cli` weglassen, um installierte CLIs automatisch zu erkennen und zur Auswahl aufzufordern. +> +> **Hermes** (hermes-agent, ein Slack/Telegram-Gateway) wird sowohl für **Live-Hook-Durchsetzung** (`--cli hermes` — eine Installation fängt Tool-Aufrufe von jeder Plattform und jedem Subagenten ab) als auch für das Offline-**Audit**-Replay seiner Gateway-Sitzungen aus der einzelnen `~/.hermes/state.db` unterstützt. --- @@ -88,23 +97,23 @@ bevor sie zu Vorfällen werden. Keine zusätzliche Latenz. Läuft lokal. ```sh npm install -g failproofai -failproofai policies --install # oder einfach `failproofai` ausführen und beim ersten Start bestätigen +failproofai policies --install # oder einfach `failproofai` ausführen und den Erststart-Prompt bestätigen failproofai ``` -30 integrierte Richtlinien werden sofort aktiv. Dashboard unter `localhost:8020`. Den Erststart-Dialog mit `FAILPROOFAI_NO_FIRST_RUN=1` deaktivieren. +30 integrierte Richtlinien werden sofort aktiviert. Dashboard unter `localhost:8020`. Den Erststart-Prompt mit `FAILPROOFAI_NO_FIRST_RUN=1` deaktivieren. --- ## Was blockiert wird -| Richtlinie | Was sie blockiert | +| Richtlinie | Was wird blockiert | |---|---| | `block-push-master` | Direkte Pushes auf `main` / `master` | | `block-force-push` | `git push --force` | -| `block-work-on-main` | Commits, Merges und Rebases auf `main` / `master` | +| `block-work-on-main` | Commits, Merges, Rebases auf `main` / `master` | | `block-rm-rf` | Rekursives Löschen von Dateien | -| `sanitize-api-keys` | API-Keys, die in den Agenten-Kontext gelangen | +| `sanitize-api-keys` | API-Keys, die in den Agent-Kontext gelangen | → [Alle 30 integrierten Richtlinien](https://docs.befailproof.ai/built-in-policies) @@ -112,8 +121,8 @@ failproofai ## Eigene Richtlinien -Eine Datei in `.failproofai/policies/` ablegen – sie wird automatisch geladen, ohne weitere Optionen. -Ins Repository committen, und das gesamte Team erhält sie beim nächsten Pull. +Eine Datei in `.failproofai/policies/` ablegen — sie wird automatisch geladen, ohne weitere Flags. +Ins Repository committen und das gesamte Team erhält sie beim nächsten Pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -129,23 +138,23 @@ customPolicies.add({ }); ``` -Drei Entscheidungstypen stehen jeder Richtlinie zur Verfügung: +Jede Richtlinie kann eine von drei Entscheidungen treffen: | Entscheidung | Wirkung | |---|---| -| `allow()` | Operation zulassen | -| `deny(message)` | Blockieren – die Nachricht wird an den Agenten zurückgegeben | -| `instruct(message)` | Durchlassen, aber dem nächsten Agenten-Prompt zusätzlichen Kontext hinzufügen | +| `allow()` | Operation erlauben | +| `deny(message)` | Blockieren — die Nachricht wird an den Agent zurückgegeben | +| `instruct(message)` | Durchlassen, aber Kontext zum nächsten Prompt des Agents hinzufügen | -→ [Leitfaden für eigene Richtlinien](https://docs.befailproof.ai/custom-policies) +→ [Anleitung für eigene Richtlinien](https://docs.befailproof.ai/custom-policies) --- ## Sitzungsübersicht -Jeder Tool-Aufruf des Agenten wird lokal protokolliert. Das Dashboard zeigt, was ausgeführt wurde, -was blockiert wurde und was die Richtlinie dem Agenten mitgeteilt hat – damit man bei Problemen -nicht im Dunkeln tappt. → [Dashboard-Leitfaden](https://docs.befailproof.ai/dashboard) +Jeder Tool-Aufruf des Agents wird lokal protokolliert. Das Dashboard zeigt, was ausgeführt wurde, +was blockiert wurde und was die Richtlinie dem Agent mitgeteilt hat — damit kein Rätseln entsteht, +wenn etwas schiefläuft. → [Dashboard-Anleitung](https://docs.befailproof.ai/dashboard) --- @@ -164,18 +173,18 @@ nicht im Dunkeln tappt. → [Dashboard-Leitfaden](https://docs.befailproof.ai/da ## Lizenz -MIT mit [Commons Clause](https://commonsclause.com/) – kostenlos für den internen und persönlichen Gebrauch; der kommerzielle Weiterverkauf von failproofai selbst erfordert eine separate Vereinbarung. Den vollständigen Text findet man in der [LICENSE](./LICENSE)-Datei. +MIT mit [Commons Clause](https://commonsclause.com/) — kostenlos für den internen und persönlichen Gebrauch; der kommerzielle Weiterverkauf von failproofai selbst erfordert eine separate Vereinbarung. Den vollständigen Text in [LICENSE](./LICENSE) nachlesen. --- ## Mitwirken -Siehe [CONTRIBUTING.md](./CONTRIBUTING.md). Neue Richtlinien, Grenzfälle und Übersetzungen sind stets willkommen. +Siehe [CONTRIBUTING.md](./CONTRIBUTING.md). Neue Richtlinien, Randfälle und Übersetzungen sind herzlich willkommen. -> **Vor dem Start bauen.** Zuerst `bun install && bun run build` ausführen. Dieses Repository verwendet -> failproofai's eigene Hooks auf sich selbst, und diese lösen den `failproofai`-Import anhand des -> kompilierten `dist/`-Bundles auf – ohne Build tritt der Hook-Fehler `Cannot find package 'failproofai'` auf. -> Nach Änderungen an `src/` neu bauen. Siehe +> **Vor dem Start bauen.** Zuerst `bun install && bun run build` ausführen. Dieses Repository führt +> die eigenen Hooks von failproofai auf sich selbst aus, und sie lösen den `failproofai`-Import gegen das +> kompilierte `dist/`-Bundle auf — ohne einen Build tritt der Hook-Fehler `Cannot find package 'failproofai'` +> auf. Nach Änderungen an `src/` neu bauen. Siehe > [Build before the in-repo dev hooks will work](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- diff --git a/docs/i18n/README.es.md b/docs/i18n/README.es.md index 3bc9a3fb..8859f6b9 100644 --- a/docs/i18n/README.es.md +++ b/docs/i18n/README.es.md @@ -18,8 +18,8 @@ **Traducciones:** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md) **Resolución de fallos en tiempo de ejecución para agentes de código.** -Se integra con Claude Code y Codex. Detecta bucles, acciones peligrosas y fugas de secretos -antes de que se conviertan en incidentes. Sin latencia. Se ejecuta localmente. +Se integra con Claude Code y Codex. Detecta bucles, acciones peligrosas y filtraciones de secretos +antes de que se conviertan en incidentes. Cero latencia. Se ejecuta localmente. @@ -78,9 +78,18 @@ antes de que se conviertan en incidentes. Sin latencia. Se ejecuta localmente. Gemini CLI +        + + + + Hermes + +

-> Instala hooks para uno o cualquier combinación: `failproofai policies --install --cli opencode pi gemini` (o `--cli claude codex copilot cursor opencode pi gemini`). Omite `--cli` para detectar automáticamente los CLIs instalados y recibir un aviso. +> Instala hooks para uno o cualquier combinación: `failproofai policies --install --cli opencode pi gemini` (o `--cli claude codex copilot cursor opencode pi gemini hermes`). Omite `--cli` para detectar automáticamente los CLIs instalados y recibir una solicitud de confirmación. +> +> **Hermes** (hermes-agent, una pasarela de Slack/Telegram) es compatible tanto con la **aplicación de hooks en vivo** (`--cli hermes` — una sola instalación intercepta las llamadas a herramientas desde cada plataforma y subagente) como con la **auditoría** offline de sus sesiones de pasarela desde el único `~/.hermes/state.db`. --- @@ -88,19 +97,19 @@ antes de que se conviertan en incidentes. Sin latencia. Se ejecuta localmente. ```sh npm install -g failproofai -failproofai policies --install # o simplemente ejecuta `failproofai` y acepta el aviso en el primer uso +failproofai policies --install # o simplemente ejecuta `failproofai` y acepta el aviso de primera ejecución failproofai ``` -30 políticas integradas se activan de inmediato. Panel de control en `localhost:8020`. Desactiva el aviso del primer uso con `FAILPROOFAI_NO_FIRST_RUN=1`. +30 políticas integradas se activan de inmediato. Panel de control en `localhost:8020`. Desactiva el aviso de primera ejecución con `FAILPROOFAI_NO_FIRST_RUN=1`. --- -## Qué bloquea +## Qué detiene | Política | Qué bloquea | |---|---| -| `block-push-master` | Envíos directos a `main` / `master` | +| `block-push-master` | Pushes directos a `main` / `master` | | `block-force-push` | `git push --force` | | `block-work-on-main` | Commits, merges y rebases en `main` / `master` | | `block-rm-rf` | Eliminación recursiva de archivos | @@ -112,8 +121,8 @@ failproofai ## Tus propias políticas -Coloca un archivo en `.failproofai/policies/` — se carga automáticamente, sin necesidad de indicadores. -Confírmalo en el repositorio y todo el equipo lo recibirá en el próximo pull. +Añade un archivo en `.failproofai/policies/` — se carga automáticamente, sin necesidad de flags. +Haz commit y todo el equipo lo obtendrá en el próximo pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -133,17 +142,17 @@ Tres decisiones disponibles para cada política: | Decisión | Efecto | |---|---| -| `allow()` | Permitir la operación | -| `deny(message)` | Bloquearla — el mensaje se devuelve al agente | -| `instruct(message)` | Dejarla pasar, pero agregar contexto al siguiente prompt del agente | +| `allow()` | Permite la operación | +| `deny(message)` | La bloquea — el mensaje se envía de vuelta al agente | +| `instruct(message)` | La deja pasar, pero añade contexto al siguiente prompt del agente | → [Guía de políticas personalizadas](https://docs.befailproof.ai/custom-policies) --- -## Visibilidad de sesión +## Visibilidad de la sesión -Cada llamada a herramientas que realiza tu agente se registra localmente. El panel de control muestra qué se ejecutó, +Cada llamada a herramienta que realiza tu agente se registra localmente. El panel de control muestra qué se ejecutó, qué fue bloqueado y qué le indicó la política al agente — para que no tengas que adivinar cuando algo sale mal. → [Guía del panel de control](https://docs.befailproof.ai/dashboard) @@ -157,7 +166,7 @@ cuando algo sale mal. → [Guía del panel de control](https://docs.befailproof. | [Políticas integradas](https://docs.befailproof.ai/built-in-policies) | Las 30 políticas con sus parámetros | | [Políticas personalizadas](https://docs.befailproof.ai/custom-policies) | Escribe las tuyas propias | | [Configuración](https://docs.befailproof.ai/configuration) | Ámbitos de configuración y reglas de combinación | -| [Panel de control](https://docs.befailproof.ai/dashboard) | Monitor de sesión y actividad de políticas | +| [Panel de control](https://docs.befailproof.ai/dashboard) | Monitor de sesiones y actividad de políticas | | [Arquitectura](https://docs.befailproof.ai/architecture) | Cómo funciona el sistema de hooks | --- @@ -170,12 +179,12 @@ MIT con [Commons Clause](https://commonsclause.com/) — gratuito para uso inter ## Contribuciones -Consulta [CONTRIBUTING.md](./CONTRIBUTING.md). Se aceptan nuevas políticas, casos límite y traducciones. +Consulta [CONTRIBUTING.md](./CONTRIBUTING.md). Son bienvenidas nuevas políticas, casos límite y traducciones. -> **Compila antes de comenzar.** Ejecuta primero `bun install && bun run build`. Este repositorio ejecuta -> los propios hooks de failproofai sobre sí mismo, y estos resuelven la importación de `failproofai` contra el -> paquete compilado en `dist/` — sin una compilación previa obtendrás errores de hook con `Cannot find package 'failproofai'`. -> Vuelve a compilar después de modificar `src/`. Consulta +> **Compila antes de empezar.** Ejecuta primero `bun install && bun run build`. Este repositorio ejecuta +> sus propios hooks de failproofai sobre sí mismo, y resuelven la importación de `failproofai` contra el +> bundle compilado en `dist/` — sin una compilación previa obtendrás errores de hook `Cannot find package 'failproofai'`. +> Recompila después de modificar `src/`. Consulta > [Build before the in-repo dev hooks will work](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- diff --git a/docs/i18n/README.fr.md b/docs/i18n/README.fr.md index 2392d978..47f8ff7e 100644 --- a/docs/i18n/README.fr.md +++ b/docs/i18n/README.fr.md @@ -17,9 +17,9 @@ **Traductions :** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md) -**Résolution des erreurs d'exécution pour les agents de code.** +**Résolution des échecs d'exécution pour les agents de code.** S'intègre à Claude Code et Codex. Détecte les boucles, les actions dangereuses et les fuites de secrets -avant qu'elles ne deviennent des incidents. Zéro latence. Fonctionne en local. +avant qu'ils ne deviennent des incidents. Zéro latence. Fonctionne en local. @@ -29,7 +29,7 @@ avant qu'elles ne deviennent des incidents. Zéro latence. Fonctionne en local. --- -## CLIs d'agents pris en charge +## CLI d'agents pris en charge

@@ -78,9 +78,18 @@ avant qu'elles ne deviennent des incidents. Zéro latence. Fonctionne en local. Gemini CLI +        + + + + Hermes + +

-> Installez les hooks pour un ou plusieurs CLIs au choix : `failproofai policies --install --cli opencode pi gemini` (ou `--cli claude codex copilot cursor opencode pi gemini`). Omettez `--cli` pour détecter automatiquement les CLIs installés et afficher une invite. +> Installez les hooks pour un ou plusieurs CLI au choix : `failproofai policies --install --cli opencode pi gemini` (ou `--cli claude codex copilot cursor opencode pi gemini hermes`). Omettez `--cli` pour détecter automatiquement les CLI installés et recevoir une invite de sélection. +> +> **Hermes** (hermes-agent, une passerelle Slack/Telegram) est pris en charge à la fois pour l'**application des hooks en temps réel** (`--cli hermes` — une seule installation intercepte les appels d'outils de chaque plateforme et sous-agent) et pour la **relecture d'audit** hors ligne de ses sessions de passerelle depuis l'unique `~/.hermes/state.db`. --- @@ -88,7 +97,7 @@ avant qu'elles ne deviennent des incidents. Zéro latence. Fonctionne en local. ```sh npm install -g failproofai -failproofai policies --install # ou lancez simplement `failproofai` et acceptez l'invite au premier démarrage +failproofai policies --install # or just run `failproofai` and accept the first-run prompt failproofai ``` @@ -98,13 +107,13 @@ failproofai ## Ce qu'il bloque -| Politique | Ce qu'elle bloque | +| Politique | Ce qui est bloqué | |---|---| -| `block-push-master` | Les pushes directs vers `main` / `master` | +| `block-push-master` | Les pushs directs vers `main` / `master` | | `block-force-push` | `git push --force` | -| `block-work-on-main` | Les commits, merges et rebases sur `main` / `master` | -| `block-rm-rf` | La suppression récursive de fichiers | -| `sanitize-api-keys` | Les clés API qui fuient dans le contexte de l'agent | +| `block-work-on-main` | Commits, merges, rebases sur `main` / `master` | +| `block-rm-rf` | Suppression récursive de fichiers | +| `sanitize-api-keys` | Fuites de clés API dans le contexte de l'agent | → [Les 30 politiques intégrées](https://docs.befailproof.ai/built-in-policies) @@ -112,7 +121,7 @@ failproofai ## Vos propres politiques -Déposez un fichier dans `.failproofai/policies/` — il se charge automatiquement, sans aucun flag. +Déposez un fichier dans `.failproofai/policies/` — il se charge automatiquement, sans aucun indicateur. Commitez-le et toute l'équipe en bénéficiera au prochain pull. ```js @@ -133,19 +142,19 @@ Trois décisions disponibles pour chaque politique : | Décision | Effet | |---|---| -| `allow()` | Autorise l'opération | -| `deny(message)` | La bloque — le message est renvoyé à l'agent | -| `instruct(message)` | La laisse passer, mais ajoute du contexte au prochain prompt de l'agent | +| `allow()` | Autoriser l'opération | +| `deny(message)` | La bloquer — le message est renvoyé à l'agent | +| `instruct(message)` | La laisser passer, mais ajouter du contexte à la prochaine invite de l'agent | → [Guide des politiques personnalisées](https://docs.befailproof.ai/custom-policies) --- -## Visibilité de la session +## Visibilité des sessions Chaque appel d'outil effectué par votre agent est journalisé localement. Le tableau de bord affiche ce qui s'est exécuté, -ce qui a été bloqué, et ce que la politique a transmis à l'agent — plus besoin de deviner -quand quelque chose tourne mal. → [Guide du tableau de bord](https://docs.befailproof.ai/dashboard) +ce qui a été bloqué, et ce que la politique a transmis à l'agent — afin que vous ne soyez pas dans le flou +en cas de problème. → [Guide du tableau de bord](https://docs.befailproof.ai/dashboard) --- @@ -164,21 +173,18 @@ quand quelque chose tourne mal. → [Guide du tableau de bord](https://docs.befa ## Licence -MIT avec [Commons Clause](https://commonsclause.com/) — gratuit pour un usage interne et personnel ; la revente commerciale de failproofai lui-même nécessite un accord séparé. Voir [LICENSE](./LICENSE) pour le texte complet. +MIT avec [Commons Clause](https://commonsclause.com/) — libre pour un usage interne et personnel ; la revente commerciale de failproofai lui-même nécessite un accord séparé. Voir [LICENSE](./LICENSE) pour le texte complet. --- ## Contribution -Consultez [CONTRIBUTING.md](./CONTRIBUTING.md). Les nouvelles politiques, cas limites et traductions sont les bienvenus. +Voir [CONTRIBUTING.md](./CONTRIBUTING.md). Nouvelles politiques, cas limites et traductions sont les bienvenus. -> **Compilez avant de commencer.** Exécutez d'abord `bun install && bun run build`. Ce dépôt fait tourner -> les propres hooks de failproofai sur lui-même, et ils résolvent l'import `failproofai` depuis le -> bundle compilé `dist/` — sans compilation, vous obtiendrez des erreurs de hook `Cannot find package 'failproofai'`. -> Recompilez après avoir modifié `src/`. Voir +> **Compilez avant de commencer.** Exécutez d'abord `bun install && bun run build`. Ce dépôt utilise ses propres hooks failproofai sur lui-même, et ils résolvent l'import `failproofai` depuis le bundle `dist/` compilé — sans compilation, vous obtiendrez des erreurs de hook `Cannot find package 'failproofai'`. Recompilez après avoir modifié `src/`. Voir > [Build before the in-repo dev hooks will work](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Développé par [Nivedit Jain](https://github.com/NiveditJain) et [Nikita Agarwal](https://github.com/nk-ag). +Créé par [Nivedit Jain](https://github.com/NiveditJain) et [Nikita Agarwal](https://github.com/nk-ag). [befailproof.ai](https://befailproof.ai) diff --git a/docs/i18n/README.he.md b/docs/i18n/README.he.md index 7d1a1118..7022d350 100644 --- a/docs/i18n/README.he.md +++ b/docs/i18n/README.he.md @@ -19,9 +19,9 @@ **תרגומים:** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md) -**פתרון כשלים בזמן ריצה לסוכנים קוד.** -מתחברים ל-Claude Code ו-Codex. תופסים לולאות, פעולות מסוכנות, והדלפות סודות -לפני שהם הופכים לתקריות. אפס עיכוב. רץ באופן מקומי. +**פתרון כשלים בזמן ריצה לסוכני קידוד.** +משתלבים ב-Claude Code וב-Codex. תופסים לולאות, פעולות מסוכנות ודיווחי סודות +לפני שהם הופכים לתקריות. אפס זיכרון זמני. פועל בעמודה השדורה. @@ -31,7 +31,7 @@ --- -## CLIs סוכנים נתמכים +## CLIs של סוכנים נתמכים

@@ -80,9 +80,18 @@ Gemini CLI +        + + + + Hermes + +

-> התקן hook-ים עבור אחד או כל שילוב: `failproofai policies --install --cli opencode pi gemini` (או `--cli claude codex copilot cursor opencode pi gemini`). הוסר `--cli` להתקלת אוטומטית של CLIs מותקנים ושאילתה. +> התקן hooks לאחד או לכל שילוב: `failproofai policies --install --cli opencode pi gemini` (או `--cli claude codex copilot cursor opencode pi gemini hermes`). השמט `--cli` לגילוי אוטומטי של CLIs מותקנים ולהנחיה. +> +> **Hermes** (hermes-agent, שער Slack/Telegram) נתמך גם ל**אכיפת hook חי** (`--cli hermes` — התקנה אחת מיירטת קריאות כלים מכל פלטפורמה וסוכן משנה) וגם **ביקורת** במצב לא מקוון של הפעלות השער שלו מ`~/.hermes/state.db` הבודד. --- @@ -90,11 +99,11 @@ ```sh npm install -g failproofai -failproofai policies --install # או פשוט הרץ `failproofai` וקבל את הודעת ההרצה הראשונה +failproofai policies --install # או פשוט הרץ `failproofai` וקבל את ההנחיה בהפעלה ראשונה failproofai ``` -30 מדיניות מובנות מופעלות מייד. לוח בקרה ב-`localhost:8020`. השבת את הודעת ההרצה הראשונה עם `FAILPROOFAI_NO_FIRST_RUN=1`. +30 מדיניויות מובנות מופעלות מיד. לוח בקרה ב-`localhost:8020`. בטל את הנחיית ההפעלה הראשונה עם `FAILPROOFAI_NO_FIRST_RUN=1`. --- @@ -102,20 +111,20 @@ failproofai | מדיניות | מה זה חוסם | |---|---| -| `block-push-master` | דחיפות ישירות ל-`main` / `master` | +| `block-push-master` | דחיפה ישירה ל-`main` / `master` | | `block-force-push` | `git push --force` | -| `block-work-on-main` | commits, merges, rebases על `main` / `master` | +| `block-work-on-main` | commits, merges, rebases ב-`main` / `master` | | `block-rm-rf` | מחיקת קבצים רקורסיבית | -| `sanitize-api-keys` | API keys הדולפות להקשר הסוכן | +| `sanitize-api-keys` | API keys דולפים להקשר של סוכן | -→ [כל 30 המדיניות המובנות](https://docs.befailproof.ai/built-in-policies) +→ [כל 30 המדיניויות המובנות](https://docs.befailproof.ai/built-in-policies) --- ## המדיניויות שלך -שחרר קובץ ל-`.failproofai/policies/` — זה נטען באופן אוטומטי, ללא דגלים נדרשים. -בצע commit שלו והצוות כולו יקבל אותו בעת ה-pull הבא. +זרוק קובץ ל-`.failproofai/policies/` — הוא טוען באופן אוטומטי, ללא דגלים. +בצע commit וכל הצוות יקבל אותו בפול הבא. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -125,7 +134,7 @@ customPolicies.add({ match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolInput?.file_path?.includes("production")) - return deny("Writes to production paths are blocked."); + return deny("כתיבה לנתיבי production מחסומה."); return allow(); }, }); @@ -135,19 +144,19 @@ customPolicies.add({ | החלטה | השפעה | |---|---| -| `allow()` | אפשר את הפעולה | +| `allow()` | אשר את הפעולה | | `deny(message)` | חסום אותה — ההודעה חוזרת לסוכן | -| `instruct(message)` | תן לזה לעבור, אך הוסף הקשר להודעה הבאה של הסוכן | +| `instruct(message)` | תן לה לעבור, אך הוסף הקשר להנחיה הבאה של הסוכן | -→ [מדריך מדיניות מותאם אישית](https://docs.befailproof.ai/custom-policies) +→ [מדריך מדיניויות מותאמות אישית](https://docs.befailproof.ai/custom-policies) --- -## נראות הפעילות +## גלויות הפעלה -כל קריאת כלי שהסוכן שלך מבצע מתועדת באופן מקומי. לוח הבקרה מציג מה רץ, -מה נחסם, ומה המדיניות אמרה לסוכן — כך שאתה לא מנחש -כשמשהו הולך לא בסדר. → [מדריך לוח הבקרה](https://docs.befailproof.ai/dashboard) +כל קריאת כלים שהסוכן שלך עושה מתועדת בעמודה השדורה. לוח הבקרה מראה מה רץ, +מה היה חסום, ומה המדיניות אמרה לסוכן — כך שאתה לא מנחש +כשמשהו הולך בצעד הלא נכון. → [מדריך לוח הבקרה](https://docs.befailproof.ai/dashboard) --- @@ -155,30 +164,30 @@ customPolicies.add({ | | | |---|---| -| [התחל](https://docs.befailproof.ai/getting-started) | התקנה והצעדים הראשונים | +| [התחלה](https://docs.befailproof.ai/getting-started) | התקנה ושלבים ראשונים | | [מדיניויות מובנות](https://docs.befailproof.ai/built-in-policies) | כל 30 המדיניויות עם פרמטרים | -| [מדיניויות מותאמות](https://docs.befailproof.ai/custom-policies) | כתוב שלך | -| [הגדרה](https://docs.befailproof.ai/configuration) | הגדרות היקף וכללי מיזוג | -| [לוח בקרה](https://docs.befailproof.ai/dashboard) | מנטר פעילות ופעילות מדיניות | -| [אדריכלות](https://docs.befailproof.ai/architecture) | כיצד מערכת ה-hook עובדת | +| [מדיניויות מותאמות אישית](https://docs.befailproof.ai/custom-policies) | כתוב שלך | +| [תצורה](https://docs.befailproof.ai/configuration) | טווחי תצורה וכללי מיזוג | +| [לוח בקרה](https://docs.befailproof.ai/dashboard) | מוניטור הפעלה ופעילות מדיניות | +| [ארכיטקטורה](https://docs.befailproof.ai/architecture) | איך מערכת ה-hook עובדת | --- ## רישיון -MIT עם [Commons Clause](https://commonsclause.com/) — חופשי לשימוש פנימי ואישי; מכירה מחדש מסחרית של failproofai עצמו דורשת הסכמה נפרדת. ראה [LICENSE](./LICENSE) לטקסט המלא. +MIT עם [Commons Clause](https://commonsclause.com/) — חינם לשימוש פנימי ואישי; מכירה מחדש מסחרית של failproofai עצמו דורשת הסכם נפרד. ראה [LICENSE](./LICENSE) לטקסט המלא. --- ## תרומה -ראה [CONTRIBUTING.md](./CONTRIBUTING.md). מדיניויות חדשות, cases קצה, ותרגומים כולם בברכה. +ראה [CONTRIBUTING.md](./CONTRIBUTING.md). מדיניויות חדשות, מקרי קצה, ותרגומים - כלם מובאים בברכה. -> **בנה לפני שתתחיל.** הרץ `bun install && bun run build` תחילה. ריפו זה מריץ -> את hook-ים של failproofai בעצמו, והם פותרים את `failproofai` import כנגד -> bundle `dist/` המהדורה — בלי build תקבל `Cannot find package 'failproofai'` -> hook errors. בנה מחדש אחרי שינוי `src/`. ראה -> [בנה לפני שה-in-repo dev hooks יעבדו](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **בנה לפני שתתחיל.** הרץ `bun install && bun run build` תחילה. המאגר הזה מריץ +> את ה-hooks שלו עצמו, והם פותרים את ייבוא `failproofai` כנגד ה-bundle המחומר `dist/` — +> ללא בנייה תוכל להיתקל בשגיאות hook `Cannot find package 'failproofai'`. בנה מחדש +> לאחר שינוי `src/`. ראה +> [בנה לפני שה-dev hooks בתוך המאגר יעבדו](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- diff --git a/docs/i18n/README.hi.md b/docs/i18n/README.hi.md index 906d2b3a..d25e5512 100644 --- a/docs/i18n/README.hi.md +++ b/docs/i18n/README.hi.md @@ -18,8 +18,8 @@ **अनुवाद:** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md) **कोडिंग एजेंटों के लिए रनटाइम विफलता समाधान।** -Claude Code और Codex में हुक करता है। लूप्स, खतरनाक कार्यों और सीक्रेट लीक को पकड़ता है -इससे पहले कि वे घटनाएं बनें। शून्य विलंबता। स्थानीय रूप से चलता है। +Claude Code और Codex में हुक करता है। लूप, खतरनाक कार्यों और सीक्रेट लीक को +पकड़ता है इससे पहले कि वे समस्या बनें। शून्य विलंबता। स्थानीय रूप से चलता है। @@ -78,9 +78,18 @@ Claude Code और Codex में हुक करता है। लूप् Gemini CLI +        + + + + Hermes + +

-> एक या किसी भी संयोजन के लिए हुक इंस्टॉल करें: `failproofai policies --install --cli opencode pi gemini` (या `--cli claude codex copilot cursor opencode pi gemini`)। स्वचालित रूप से इंस्टॉल किए गए CLIs को खोजने और प्रॉम्प्ट करने के लिए `--cli` को छोड़ें। +> एक या किसी भी संयोजन के लिए हुक इंस्टॉल करें: `failproofai policies --install --cli opencode pi gemini` (या `--cli claude codex copilot cursor opencode pi gemini hermes`)। स्वचालित रूप से स्थापित CLIs का पता लगाने और संकेत देने के लिए `--cli` को छोड़ दें। +> +> **Hermes** (hermes-agent, एक Slack/Telegram गेटवे) **लाइव-हुक प्रवर्तन** (`--cli hermes` — एक इंस्टॉल प्रत्येक प्लेटफॉर्म और सबएजेंट से टूल कॉल को रोकता है) और इसके गेटवे सत्रों की ऑफलाइन **ऑडिट** रिप्ले दोनों के लिए समर्थित है। --- @@ -88,32 +97,32 @@ Claude Code और Codex में हुक करता है। लूप् ```sh npm install -g failproofai -failproofai policies --install # या बस `failproofai` चलाएं और पहली बार चलाने वाले प्रॉम्प्ट को स्वीकार करें +failproofai policies --install # या बस `failproofai` चलाएं और पहली बार के संकेत को स्वीकार करें failproofai ``` -30 बिल्ट-इन पॉलिसीज तुरंत सक्रिय हो जाती हैं। डैशबोर्ड `localhost:8020` पर उपलब्ध है। `FAILPROOFAI_NO_FIRST_RUN=1` के साथ पहली बार चलाने वाले प्रॉम्प्ट को अक्षम करें। +30 बिल्ट-इन नीतियां तुरंत सक्रिय हो जाती हैं। `localhost:8020` पर डैशबोर्ड। पहली बार के संकेत को `FAILPROOFAI_NO_FIRST_RUN=1` के साथ अक्षम करें। --- ## यह क्या रोकता है -| पॉलिसी | यह क्या ब्लॉक करता है | +| नीति | यह क्या ब्लॉक करता है | |---|---| -| `block-push-master` | `main` / `master` को सीधे पुश करना | +| `block-push-master` | `main` / `master` के लिए सीधे पुश | | `block-force-push` | `git push --force` | -| `block-work-on-main` | `main` / `master` पर कमिट, मर्ज, रीबेस करना | -| `block-rm-rf` | पुनरावर्ती फाइल हटाना | -| `sanitize-api-keys` | API कीज़ एजेंट संदर्भ में लीक होना | +| `block-work-on-main` | `main` / `master` पर प्रतिबद्धता, विलय, रीबेस | +| `block-rm-rf` | पुनरावर्ती फ़ाइल हटाना | +| `sanitize-api-keys` | API कुंजियां एजेंट संदर्भ में लीक हो रही हैं | -→ [सभी 30 बिल्ट-इन पॉलिसीज](https://docs.befailproof.ai/built-in-policies) +→ [सभी 30 बिल्ट-इन नीतियां](https://docs.befailproof.ai/built-in-policies) --- -## आपकी अपनी पॉलिसीज +## आपकी अपनी नीतियां -`.failproofai/policies/` में एक फाइल ड्रॉप करें — यह स्वचालित रूप से लोड हो जाती है, किसी फ्लैग की आवश्यकता नहीं। -इसे कमिट करें और पूरी टीम को अगली पुल पर यह मिल जाएगी। +`.failproofai/policies/` में एक फ़ाइल ड्रॉप करें — यह स्वचालित रूप से लोड होती है, किसी फ्लैग की आवश्यकता नहीं है। +इसे प्रतिबद्ध करें और पूरी टीम को अगले पुल पर यह मिल जाता है। ```js import { customPolicies, deny, allow } from "failproofai"; @@ -129,35 +138,35 @@ customPolicies.add({ }); ``` -प्रत्येक पॉलिसी के लिए तीन निर्णय उपलब्ध हैं: +प्रत्येक नीति के लिए तीन निर्णय उपलब्ध हैं: | निर्णय | प्रभाव | |---|---| | `allow()` | ऑपरेशन की अनुमति दें | | `deny(message)` | इसे ब्लॉक करें — संदेश एजेंट को वापस जाता है | -| `instruct(message)` | इसे आगे बढ़ने दें, लेकिन एजेंट के अगले प्रॉम्प्ट में संदर्भ जोड़ें | +| `instruct(message)` | इसे जाने दें, लेकिन एजेंट के अगले प्रॉम्प्ट में संदर्भ जोड़ें | -→ [कस्टम पॉलिसीज गाइड](https://docs.befailproof.ai/custom-policies) +→ [कस्टम नीतियां गाइड](https://docs.befailproof.ai/custom-policies) --- -## सेशन दृश्यमानता +## सत्र दृश्यता -आपका एजेंट जो भी टूल कॉल करता है वह स्थानीय रूप से लॉग किया जाता है। डैशबोर्ड दिखाता है कि क्या चला, -क्या ब्लॉक किया गया, और पॉलिसी ने एजेंट को क्या बताया — इसलिए आप अनुमान नहीं लगा रहे हैं +आपके एजेंट द्वारा किया जाने वाला प्रत्येक टूल कॉल स्थानीय रूप से लॉग किया जाता है। डैशबोर्ड दिखाता है कि क्या चला, +क्या ब्लॉक किया गया, और नीति ने एजेंट को क्या बताया — इसलिए आप अनुमान नहीं लगा रहे हैं जब कुछ गलत हो जाता है। → [डैशबोर्ड गाइड](https://docs.befailproof.ai/dashboard) --- -## डॉक्यूमेंटेशन +## दस्तावेज़ | | | |---|---| -| [शुरुआत करें](https://docs.befailproof.ai/getting-started) | इंस्टॉलेशन और पहले कदम | -| [बिल्ट-इन पॉलिसीज](https://docs.befailproof.ai/built-in-policies) | सभी 30 पॉलिसीज पैरामीटर के साथ | -| [कस्टम पॉलिसीज](https://docs.befailproof.ai/custom-policies) | अपनी खुद की लिखें | +| [शुरुआत करना](https://docs.befailproof.ai/getting-started) | इंस्टॉलेशन और पहले कदम | +| [बिल्ट-इन नीतियां](https://docs.befailproof.ai/built-in-policies) | सभी 30 नीतियां पैरामीटर के साथ | +| [कस्टम नीतियां](https://docs.befailproof.ai/custom-policies) | अपनी खुद की लिखें | | [कॉन्फ़िगरेशन](https://docs.befailproof.ai/configuration) | कॉन्फ़िग स्कोप और मर्ज नियम | -| [डैशबोर्ड](https://docs.befailproof.ai/dashboard) | सेशन मॉनिटर और पॉलिसी गतिविधि | +| [डैशबोर्ड](https://docs.befailproof.ai/dashboard) | सत्र मॉनिटर और नीति गतिविधि | | [आर्किटेक्चर](https://docs.befailproof.ai/architecture) | हुक सिस्टम कैसे काम करता है | --- @@ -170,15 +179,14 @@ customPolicies.add({ ## योगदान -[CONTRIBUTING.md](./CONTRIBUTING.md) देखें। नई पॉलिसीज, एज केस, और अनुवाद सभी स्वागत हैं। +[CONTRIBUTING.md](./CONTRIBUTING.md) देखें। नई नीतियां, किनारे के मामलों और अनुवाद सभी स्वागत है। -> **बिल्ड शुरू करने से पहले।** पहले `bun install && bun run build` चलाएं। यह रेपो -> failproofai के अपने हुक को स्वयं पर चलाता है, और वे `failproofai` इंपोर्ट को संकलित -> `dist/` बंडल के विरुद्ध हल करते हैं — बिल्ड के बिना आपको `Cannot find package 'failproofai'` -> हुक त्रुटियां मिलेंगी। `src/` बदलने के बाद पुनः बिल्ड करें। देखें -> [इन-रेपो डेव हुक काम करने से पहले बिल्ड करें](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)। +> **शुरू करने से पहले बिल्ड करें।** पहले `bun install && bun run build` चलाएं। यह रेपो +> failproofai की अपनी नीतियों को अपने आप पर चलाता है, और वे `failproofai` आयात को संकलित `dist/` बंडल के विरुद्ध हल करते हैं — बिल्ड के बिना आप `Cannot find package 'failproofai'` +> हुक त्रुटियों से टकराएंगे। `src/` के बदलने के बाद फिर से बिल्ड करें। देखें +> [इन-रेपो डेव हुक के काम करने से पहले बिल्ड करें](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)। --- -[Nivedit Jain](https://github.com/NiveditJain) और [Nikita Agarwal](https://github.com/nk-ag) द्वारा निर्मित। +[Nivedit Jain](https://github.com/NiveditJain) और [Nikita Agarwal](https://github.com/nk-ag) द्वारा बनाया गया। [befailproof.ai](https://befailproof.ai) diff --git a/docs/i18n/README.it.md b/docs/i18n/README.it.md index 2beb45e3..c6a4bac7 100644 --- a/docs/i18n/README.it.md +++ b/docs/i18n/README.it.md @@ -17,8 +17,8 @@ **Traduzioni:** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md) -**Risoluzione dei guasti runtime per gli agenti di codifica.** -Si integra con Claude Code e Codex. Cattura i loop, le azioni pericolose e le fughe di segreti +**Risoluzione dei guasti di runtime per gli agenti di codice.** +Si integra con Claude Code e Codex. Cattura loop, azioni pericolose e fughe di segreti prima che diventino incidenti. Latenza zero. Eseguito localmente. @@ -29,7 +29,7 @@ prima che diventino incidenti. Latenza zero. Eseguito localmente. --- -## CLI agente supportati +## CLI degli agenti supportati

@@ -78,9 +78,18 @@ prima che diventino incidenti. Latenza zero. Eseguito localmente. Gemini CLI +        + + + + Hermes + +

-> Installa i hook per uno o qualsiasi combinazione: `failproofai policies --install --cli opencode pi gemini` (oppure `--cli claude codex copilot cursor opencode pi gemini`). Ometti `--cli` per rilevare automaticamente i CLI installati e ricevere un prompt. +> Installa gli hook per uno o qualsiasi combinazione: `failproofai policies --install --cli opencode pi gemini` (o `--cli claude codex copilot cursor opencode pi gemini hermes`). Ometti `--cli` per rilevare automaticamente le CLI installate e ricevere un prompt. +> +> **Hermes** (hermes-agent, un gateway Slack/Telegram) è supportato sia per l'**applicazione dei hook in diretta** (`--cli hermes` — un'unica installazione intercetta le chiamate ai tool da ogni piattaforma e subagente) che per il **controllo** offline della riproduzione delle sue sessioni gateway dal singolo `~/.hermes/state.db`. --- @@ -88,32 +97,32 @@ prima che diventino incidenti. Latenza zero. Eseguito localmente. ```sh npm install -g failproofai -failproofai policies --install # o semplicemente esegui `failproofai` e accetta il primo prompt +failproofai policies --install # oppure esegui semplicemente `failproofai` e accetta il prompt al primo avvio failproofai ``` -30 policy built-in si attivano immediatamente. Dashboard su `localhost:8020`. Disabilita il primo prompt con `FAILPROOFAI_NO_FIRST_RUN=1`. +30 politiche integrate si attivano immediatamente. Dashboard disponibile su `localhost:8020`. Disabilita il prompt al primo avvio con `FAILPROOFAI_NO_FIRST_RUN=1`. --- ## Cosa blocca -| Policy | Cosa blocca | +| Politica | Cosa blocca | |---|---| | `block-push-master` | Push diretti a `main` / `master` | | `block-force-push` | `git push --force` | | `block-work-on-main` | Commit, merge, rebase su `main` / `master` | | `block-rm-rf` | Eliminazione ricorsiva di file | -| `sanitize-api-keys` | Chiavi API che fuggono nel contesto dell'agente | +| `sanitize-api-keys` | Fughe di chiavi API nel contesto dell'agente | -→ [Tutte le 30 policy built-in](https://docs.befailproof.ai/built-in-policies) +→ [Tutte le 30 politiche integrate](https://docs.befailproof.ai/built-in-policies) --- -## Le tue policy +## Le tue politiche personali -Rilascia un file in `.failproofai/policies/` — si carica automaticamente, nessun flag necessario. -Esegui il commit e l'intero team lo riceve al prossimo pull. +Inserisci un file in `.failproofai/policies/` — carica automaticamente, nessun flag necessario. +Committalo e l'intero team lo riceverà al prossimo pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -129,23 +138,23 @@ customPolicies.add({ }); ``` -Tre decisioni disponibili per ogni policy: +Tre decisioni disponibili per ogni politica: | Decisione | Effetto | |---|---| -| `allow()` | Consenti l'operazione | -| `deny(message)` | Bloccalo — il messaggio torna all'agente | -| `instruct(message)` | Lascialo passare, ma aggiungi contesto al prossimo prompt dell'agente | +| `allow()` | Permetti l'operazione | +| `deny(message)` | Bloccala — il messaggio torna all'agente | +| `instruct(message)` | Lasciarla passare, ma aggiungi contesto al prossimo prompt dell'agente | -→ [Guida alle policy personalizzate](https://docs.befailproof.ai/custom-policies) +→ [Guida alle politiche personalizzate](https://docs.befailproof.ai/custom-policies) --- ## Visibilità della sessione -Ogni chiamata di strumento che il tuo agente effettua viene registrata localmente. Il dashboard mostra cosa è stato eseguito, -cosa è stato bloccato e cosa la policy ha detto all'agente — così non stai indovinando -quando qualcosa va male. → [Guida al dashboard](https://docs.befailproof.ai/dashboard) +Ogni chiamata ai tool effettuata dal tuo agente viene registrata localmente. Il dashboard mostra +cosa è stato eseguito, cosa è stato bloccato e cosa ha detto la politica all'agente — così non devi +indovinare quando qualcosa va male. → [Guida al dashboard](https://docs.befailproof.ai/dashboard) --- @@ -153,32 +162,28 @@ quando qualcosa va male. → [Guida al dashboard](https://docs.befailproof.ai/da | | | |---|---| -| [Getting Started](https://docs.befailproof.ai/getting-started) | Installazione e primi passi | -| [Built-in Policies](https://docs.befailproof.ai/built-in-policies) | Tutte le 30 policy con parametri | -| [Custom Policies](https://docs.befailproof.ai/custom-policies) | Scrivi le tue | -| [Configuration](https://docs.befailproof.ai/configuration) | Ambiti di configurazione e regole di merge | -| [Dashboard](https://docs.befailproof.ai/dashboard) | Monitor di sessione e attività policy | -| [Architecture](https://docs.befailproof.ai/architecture) | Come funziona il sistema di hook | +| [Per Iniziare](https://docs.befailproof.ai/getting-started) | Installazione e primi passi | +| [Politiche Integrate](https://docs.befailproof.ai/built-in-policies) | Tutte le 30 politiche con parametri | +| [Politiche Personalizzate](https://docs.befailproof.ai/custom-policies) | Scrivi le tue | +| [Configurazione](https://docs.befailproof.ai/configuration) | Ambiti di configurazione e regole di merge | +| [Dashboard](https://docs.befailproof.ai/dashboard) | Monitor delle sessioni e attività delle politiche | +| [Architettura](https://docs.befailproof.ai/architecture) | Come funziona il sistema di hook | --- ## Licenza -MIT con [Commons Clause](https://commonsclause.com/) — gratuito per uso interno e personale; la rivendita commerciale di failproofai stesso richiede un accordo separato. Vedi [LICENSE](./LICENSE) per il testo completo. +MIT con [Commons Clause](https://commonsclause.com/) — gratuito per uso interno e personale; la rivendita commerciale di failproofai stesso richiede un accordo separato. Consulta [LICENSE](./LICENSE) per il testo completo. --- ## Contribuire -Vedi [CONTRIBUTING.md](./CONTRIBUTING.md). Nuove policy, casi limite e traduzioni sono tutti benvenuti. +Vedi [CONTRIBUTING.md](./CONTRIBUTING.md). Nuove politiche, casi limite e traduzioni sono benvenuti. -> **Compila prima di iniziare.** Esegui `bun install && bun run build` per primo. Questo repository esegue -> i propri hook di failproofai su se stesso, e risolvono l'import `failproofai` rispetto al -> bundle compilato `dist/` — senza una build otterrai errori di hook `Cannot find package 'failproofai'`. -> Ricompila dopo aver modificato `src/`. Vedi -> [Build before the in-repo dev hooks will work](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Compila prima di iniziare.** Esegui prima `bun install && bun run build`. Questo repository esegue i propri hook di failproofai su se stesso e risolvono l'importazione di `failproofai` rispetto al bundle compilato `dist/` — senza una compilazione riceverai errori di hook `Cannot find package 'failproofai'`. Ricompila dopo aver modificato `src/`. Consulta [Build before the in-repo dev hooks will work](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Creato da [Nivedit Jain](https://github.com/NiveditJain) e [Nikita Agarwal](https://github.com/nk-ag). +Realizzato da [Nivedit Jain](https://github.com/NiveditJain) e [Nikita Agarwal](https://github.com/nk-ag). [befailproof.ai](https://befailproof.ai) diff --git a/docs/i18n/README.ja.md b/docs/i18n/README.ja.md index a76c7867..521e8204 100644 --- a/docs/i18n/README.ja.md +++ b/docs/i18n/README.ja.md @@ -18,8 +18,8 @@ **翻訳:** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md) **コーディングエージェントのランタイム障害を解決します。** -Claude Code および Codex にフックし、ループ・危険な操作・シークレットの漏洩を -インシデントになる前にキャッチします。レイテンシーゼロ。ローカル実行。 +Claude Code と Codex にフックして、ループ・危険な操作・シークレット漏洩を +インシデントになる前に検知。レイテンシーゼロ。ローカルで動作。 @@ -78,9 +78,18 @@ Claude Code および Codex にフックし、ループ・危険な操作・シ Gemini CLI +        + + + + Hermes + +

-> 1つまたは複数の組み合わせでフックをインストールできます: `failproofai policies --install --cli opencode pi gemini`（または `--cli claude codex copilot cursor opencode pi gemini`）。`--cli` を省略すると、インストール済みの CLI を自動検出してプロンプトを表示します。 +> 1つまたは任意の組み合わせでフックをインストールできます: `failproofai policies --install --cli opencode pi gemini`（または `--cli claude codex copilot cursor opencode pi gemini hermes`）。`--cli` を省略するとインストール済み CLI を自動検出してプロンプトを表示します。 +> +> **Hermes**（hermes-agent、Slack/Telegram ゲートウェイ）は、**ライブフック強制実行**（`--cli hermes` — 1回のインストールですべてのプラットフォームとサブエージェントのツール呼び出しをインターセプト）と、単一の `~/.hermes/state.db` からのゲートウェイセッションのオフライン**監査**リプレイの両方に対応しています。 --- @@ -88,32 +97,32 @@ Claude Code および Codex にフックし、ループ・危険な操作・シ ```sh npm install -g failproofai -failproofai policies --install # または `failproofai` を実行して初回起動プロンプトに従う +failproofai policies --install # または `failproofai` を実行して初回起動プロンプトに同意 failproofai ``` -30個の組み込みポリシーが即座に有効化されます。ダッシュボードは `localhost:8020` で確認できます。初回起動プロンプトを無効にするには `FAILPROOFAI_NO_FIRST_RUN=1` を設定してください。 +30個の組み込みポリシーが即座に有効化されます。ダッシュボードは `localhost:8020` で確認できます。`FAILPROOFAI_NO_FIRST_RUN=1` を設定すると初回起動プロンプトを無効化できます。 --- -## 防止できること +## ブロックされる操作 -| ポリシー | ブロック対象 | +| ポリシー | ブロックされる内容 | |---|---| | `block-push-master` | `main` / `master` への直接プッシュ | | `block-force-push` | `git push --force` | | `block-work-on-main` | `main` / `master` へのコミット・マージ・リベース | -| `block-rm-rf` | ファイルの再帰的削除 | +| `block-rm-rf` | 再帰的なファイル削除 | | `sanitize-api-keys` | エージェントコンテキストへの API キー漏洩 | -→ [組み込みポリシー全30件](https://docs.befailproof.ai/built-in-policies) +→ [組み込みポリシー一覧（全30件）](https://docs.befailproof.ai/built-in-policies) --- ## 独自ポリシーの作成 -`.failproofai/policies/` にファイルを配置するだけで自動読み込みされます。フラグは不要です。 -コミットしておけば、次回プル時にチーム全員に適用されます。 +`.failproofai/policies/` にファイルを置くだけで自動的に読み込まれます。フラグは不要です。 +コミットすればチーム全員が次回の pull 時に取得できます。 ```js import { customPolicies, deny, allow } from "failproofai"; @@ -129,21 +138,21 @@ customPolicies.add({ }); ``` -各ポリシーで使用できる判定は3種類です: +各ポリシーで使用できる3つの判定: | 判定 | 効果 | |---|---| | `allow()` | 操作を許可する | | `deny(message)` | ブロックする — メッセージがエージェントに返される | -| `instruct(message)` | 通過させつつ、エージェントの次のプロンプトにコンテキストを追加する | +| `instruct(message)` | 通過させるが、エージェントの次のプロンプトにコンテキストを追加する | → [カスタムポリシーガイド](https://docs.befailproof.ai/custom-policies) --- -## セッションの可視性 +## セッションの可視化 -エージェントが行ったすべてのツール呼び出しはローカルに記録されます。ダッシュボードでは、実行された内容・ブロックされた内容・ポリシーがエージェントに伝えた内容を確認できるため、問題発生時に推測に頼る必要がありません。→ [ダッシュボードガイド](https://docs.befailproof.ai/dashboard) +エージェントが行ったすべてのツール呼び出しはローカルに記録されます。ダッシュボードでは実行内容・ブロックされた内容・ポリシーがエージェントに伝えた内容を確認できるため、何か問題が起きたときに推測に頼る必要がありません。→ [ダッシュボードガイド](https://docs.befailproof.ai/dashboard) --- @@ -152,7 +161,7 @@ customPolicies.add({ | | | |---|---| | [はじめに](https://docs.befailproof.ai/getting-started) | インストールと最初のステップ | -| [組み込みポリシー](https://docs.befailproof.ai/built-in-policies) | パラメータ付き全30ポリシー | +| [組み込みポリシー](https://docs.befailproof.ai/built-in-policies) | パラメーター付き全30ポリシー | | [カスタムポリシー](https://docs.befailproof.ai/custom-policies) | 独自ポリシーの作成方法 | | [設定](https://docs.befailproof.ai/configuration) | 設定スコープとマージルール | | [ダッシュボード](https://docs.befailproof.ai/dashboard) | セッションモニターとポリシーアクティビティ | @@ -162,17 +171,17 @@ customPolicies.add({ ## ライセンス -MIT with [Commons Clause](https://commonsclause.com/) — 社内利用および個人利用は無料。failproofai 自体の商業的再販には別途契約が必要です。全文は [LICENSE](./LICENSE) をご覧ください。 +MIT に [Commons Clause](https://commonsclause.com/) を追加 — 社内利用および個人利用は無料。failproofai 自体の商業的な再販には別途契約が必要です。全文は [LICENSE](./LICENSE) をご覧ください。 --- -## コントリビューション +## コントリビュート -[CONTRIBUTING.md](./CONTRIBUTING.md) をご覧ください。新しいポリシー・エッジケース・翻訳はいずれも歓迎します。 +[CONTRIBUTING.md](./CONTRIBUTING.md) をご覧ください。新しいポリシー、エッジケース、翻訳はいずれも歓迎です。 -> **作業前にビルドしてください。** 最初に `bun install && bun run build` を実行してください。このリポジトリは failproofai 自身のフックを自分自身に対して実行しており、`failproofai` のインポートをコンパイル済みの `dist/` バンドルに対して解決します。ビルドを行わないと、`Cannot find package 'failproofai'` というフックエラーが発生します。`src/` を変更した後は再ビルドしてください。詳細は [リポジトリ内開発フックを動作させる前にビルドする](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) をご覧ください。 +> **作業を始める前にビルドしてください。** 最初に `bun install && bun run build` を実行してください。このリポジトリは failproofai 自身のフックを自分自身に対して実行しており、`failproofai` のインポートをコンパイル済みの `dist/` バンドルに対して解決します。ビルドなしでは `Cannot find package 'failproofai'` というフックエラーが発生します。`src/` を変更した後は再ビルドしてください。詳細は [Build before the in-repo dev hooks will work](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) を参照してください。 --- -[Nivedit Jain](https://github.com/NiveditJain) と [Nikita Agarwal](https://github.com/nk-ag) によって開発されました。 +[Nivedit Jain](https://github.com/NiveditJain) と [Nikita Agarwal](https://github.com/nk-ag) により開発。 [befailproof.ai](https://befailproof.ai) diff --git a/docs/i18n/README.ko.md b/docs/i18n/README.ko.md index ae03f5d4..2b49b7e7 100644 --- a/docs/i18n/README.ko.md +++ b/docs/i18n/README.ko.md @@ -17,9 +17,9 @@ **번역:** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md) -**코딩 에이전트를 위한 런타임 오류 해결 도구.** -Claude Code 및 Codex에 연결되어, 루프·위험한 작업·시크릿 유출을 -인시던트가 되기 전에 차단합니다. 지연 없음. 로컬 실행. +**코딩 에이전트를 위한 런타임 장애 해결 도구.** +Claude Code 및 Codex에 연동됩니다. 루프, 위험한 동작, 시크릿 유출을 +인시던트가 되기 전에 차단합니다. 지연 시간 없음. 로컬에서 실행. @@ -78,9 +78,18 @@ Claude Code 및 Codex에 연결되어, 루프·위험한 작업·시크릿 유 Gemini CLI +        + + + + Hermes + +

-> 하나 또는 여러 CLI에 훅을 설치하려면: `failproofai policies --install --cli opencode pi gemini` (또는 `--cli claude codex copilot cursor opencode pi gemini`). `--cli`를 생략하면 설치된 CLI를 자동 감지하고 선택을 안내합니다. +> 하나 또는 여러 CLI를 조합하여 훅을 설치할 수 있습니다: `failproofai policies --install --cli opencode pi gemini` (또는 `--cli claude codex copilot cursor opencode pi gemini hermes`). `--cli`를 생략하면 설치된 CLI를 자동으로 감지하고 선택을 안내합니다. +> +> **Hermes** (hermes-agent, Slack/Telegram 게이트웨이)는 **실시간 훅 적용** (`--cli hermes` — 한 번의 설치로 모든 플랫폼과 서브에이전트의 툴 호출을 가로챔)과 단일 `~/.hermes/state.db`의 게이트웨이 세션 오프라인 **감사** 재생을 모두 지원합니다. --- @@ -88,19 +97,19 @@ Claude Code 및 Codex에 연결되어, 루프·위험한 작업·시크릿 유 ```sh npm install -g failproofai -failproofai policies --install # 또는 `failproofai`를 실행하고 첫 실행 프롬프트에서 수락 +failproofai policies --install # 또는 `failproofai`를 실행하고 최초 실행 프롬프트에 동의 failproofai ``` -30개의 기본 제공 정책이 즉시 활성화됩니다. 대시보드는 `localhost:8020`에서 확인할 수 있습니다. `FAILPROOFAI_NO_FIRST_RUN=1`로 첫 실행 프롬프트를 비활성화할 수 있습니다. +30개의 기본 제공 정책이 즉시 활성화됩니다. 대시보드는 `localhost:8020`에서 확인할 수 있습니다. `FAILPROOFAI_NO_FIRST_RUN=1`로 최초 실행 프롬프트를 비활성화할 수 있습니다. --- -## 차단 항목 +## 차단하는 항목 | 정책 | 차단 내용 | |---|---| -| `block-push-master` | `main` / `master`에 대한 직접 푸시 | +| `block-push-master` | `main` / `master`에 직접 푸시 | | `block-force-push` | `git push --force` | | `block-work-on-main` | `main` / `master`에서의 커밋, 머지, 리베이스 | | `block-rm-rf` | 재귀적 파일 삭제 | @@ -110,10 +119,10 @@ failproofai --- -## 나만의 정책 만들기 +## 커스텀 정책 -`.failproofai/policies/` 디렉터리에 파일을 추가하면 별도 설정 없이 자동으로 로드됩니다. -커밋하면 팀 전체가 다음 풀 시 동일한 정책을 적용받습니다. +`.failproofai/policies/` 디렉토리에 파일을 추가하면 별도의 플래그 없이 자동으로 로드됩니다. +커밋해두면 다음 풀 시 팀 전체에 적용됩니다. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -134,8 +143,8 @@ customPolicies.add({ | 결정 | 효과 | |---|---| | `allow()` | 작업 허용 | -| `deny(message)` | 차단 — 메시지가 에이전트에게 반환됨 | -| `instruct(message)` | 통과시키되, 에이전트의 다음 프롬프트에 컨텍스트 추가 | +| `deny(message)` | 차단 — 메시지가 에이전트에 반환됨 | +| `instruct(message)` | 통과 허용, 단 에이전트의 다음 프롬프트에 컨텍스트 추가 | → [커스텀 정책 가이드](https://docs.befailproof.ai/custom-policies) @@ -143,9 +152,9 @@ customPolicies.add({ ## 세션 가시성 -에이전트가 수행하는 모든 도구 호출은 로컬에 기록됩니다. 대시보드에서 실행된 내용, -차단된 내용, 정책이 에이전트에게 전달한 내용을 확인할 수 있어 — 문제가 발생했을 때 -추측에 의존하지 않아도 됩니다. → [대시보드 가이드](https://docs.befailproof.ai/dashboard) +에이전트가 수행하는 모든 툴 호출은 로컬에 기록됩니다. 대시보드에서는 실행된 내용, +차단된 내용, 정책이 에이전트에 전달한 내용을 확인할 수 있어 — 문제가 발생했을 때 +추측할 필요가 없습니다. → [대시보드 가이드](https://docs.befailproof.ai/dashboard) --- @@ -153,30 +162,29 @@ customPolicies.add({ | | | |---|---| -| [시작하기](https://docs.befailproof.ai/getting-started) | 설치 및 첫 단계 | -| [기본 제공 정책](https://docs.befailproof.ai/built-in-policies) | 파라미터 포함 30개 정책 전체 | +| [시작하기](https://docs.befailproof.ai/getting-started) | 설치 및 첫 번째 단계 | +| [기본 제공 정책](https://docs.befailproof.ai/built-in-policies) | 파라미터 포함 30개 정책 전체 목록 | | [커스텀 정책](https://docs.befailproof.ai/custom-policies) | 직접 작성하기 | | [설정](https://docs.befailproof.ai/configuration) | 설정 범위 및 병합 규칙 | | [대시보드](https://docs.befailproof.ai/dashboard) | 세션 모니터 및 정책 활동 | -| [아키텍처](https://docs.befailproof.ai/architecture) | 훅 시스템 동작 원리 | +| [아키텍처](https://docs.befailproof.ai/architecture) | 훅 시스템 동작 방식 | --- ## 라이선스 -[Commons Clause](https://commonsclause.com/)가 포함된 MIT — 내부 및 개인 사용은 무료이며, failproofai 자체의 상업적 재판매는 별도 계약이 필요합니다. 전체 내용은 [LICENSE](./LICENSE)를 참조하세요. +[Commons Clause](https://commonsclause.com/)가 적용된 MIT 라이선스 — 내부 및 개인 사용은 무료이며, failproofai 자체의 상업적 재판매는 별도 계약이 필요합니다. 전문은 [LICENSE](./LICENSE)를 참조하세요. --- -## 기여하기 +## 기여 -[CONTRIBUTING.md](./CONTRIBUTING.md)를 참조하세요. 새로운 정책, 엣지 케이스, 번역 모두 환영합니다. +[CONTRIBUTING.md](./CONTRIBUTING.md)를 참고하세요. 새로운 정책, 엣지 케이스, 번역 모두 환영합니다. -> **시작 전에 빌드를 먼저 실행하세요.** `bun install && bun run build`를 먼저 실행하십시오. 이 저장소는 -> failproofai 자체 훅을 스스로에게 적용하며, `failproofai` 임포트를 -> 컴파일된 `dist/` 번들로 해석합니다 — 빌드 없이 시작하면 `Cannot find package 'failproofai'` -> 훅 오류가 발생합니다. `src/`를 변경한 후에는 다시 빌드하세요. -> [저장소 내 개발 훅 동작을 위한 빌드 방법](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)을 참조하세요. +> **시작 전에 빌드하세요.** 먼저 `bun install && bun run build`를 실행하세요. 이 저장소는 +> failproofai 자체 훅을 자기 자신에게 적용하며, 컴파일된 `dist/` 번들에서 `failproofai` 임포트를 해석합니다 — +> 빌드 없이는 `Cannot find package 'failproofai'` 훅 오류가 발생합니다. `src/` 변경 후에는 다시 빌드하세요. +> [빌드해야 저장소 내 개발 훅이 동작합니다](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)를 참고하세요. --- diff --git a/docs/i18n/README.pt-br.md b/docs/i18n/README.pt-br.md index ff99f4d9..967087e9 100644 --- a/docs/i18n/README.pt-br.md +++ b/docs/i18n/README.pt-br.md @@ -19,7 +19,7 @@ **Resolução de falhas em tempo de execução para agentes de codificação.** Integra-se ao Claude Code e ao Codex. Detecta loops, ações perigosas e vazamentos de segredos -antes que virem incidentes. Latência zero. Executa localmente. +antes que se tornem incidentes. Latência zero. Roda localmente. @@ -78,9 +78,18 @@ antes que virem incidentes. Latência zero. Executa localmente. Gemini CLI +        + + + + Hermes + +

-> Instale hooks para um ou qualquer combinação: `failproofai policies --install --cli opencode pi gemini` (ou `--cli claude codex copilot cursor opencode pi gemini`). Omita `--cli` para detectar automaticamente os CLIs instalados e exibir um prompt. +> Instale hooks para um ou qualquer combinação: `failproofai policies --install --cli opencode pi gemini` (ou `--cli claude codex copilot cursor opencode pi gemini hermes`). Omita `--cli` para detectar automaticamente os CLIs instalados e ser solicitado a escolher. +> +> **Hermes** (hermes-agent, um gateway para Slack/Telegram) é suportado tanto para **aplicação de hooks em tempo real** (`--cli hermes` — uma única instalação intercepta chamadas de ferramentas de todas as plataformas e subagentes) quanto para **auditoria** offline a partir de sessões do gateway gravadas no `~/.hermes/state.db`. --- @@ -88,11 +97,11 @@ antes que virem incidentes. Latência zero. Executa localmente. ```sh npm install -g failproofai -failproofai policies --install # ou simplesmente execute `failproofai` e aceite o prompt na primeira execução +failproofai policies --install # ou simplesmente execute `failproofai` e aceite o prompt da primeira execução failproofai ``` -30 políticas integradas são ativadas imediatamente. Dashboard disponível em `localhost:8020`. Desative o prompt de primeira execução com `FAILPROOFAI_NO_FIRST_RUN=1`. +30 políticas nativas são ativadas imediatamente. Dashboard disponível em `localhost:8020`. Desative o prompt da primeira execução com `FAILPROOFAI_NO_FIRST_RUN=1`. --- @@ -106,14 +115,14 @@ failproofai | `block-rm-rf` | Exclusão recursiva de arquivos | | `sanitize-api-keys` | Vazamento de chaves de API no contexto do agente | -→ [Todas as 30 políticas integradas](https://docs.befailproof.ai/built-in-policies) +→ [Todas as 30 políticas nativas](https://docs.befailproof.ai/built-in-policies) --- ## Suas próprias políticas -Coloque um arquivo em `.failproofai/policies/` — ele é carregado automaticamente, sem necessidade de flags. -Faça commit e toda a equipe receberá na próxima atualização. +Adicione um arquivo em `.failproofai/policies/` — ele é carregado automaticamente, sem nenhuma flag necessária. +Faça o commit e toda a equipe receberá a política no próximo pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -143,8 +152,8 @@ Três decisões disponíveis para cada política: ## Visibilidade da sessão -Cada chamada de ferramenta que seu agente realiza é registrada localmente. O dashboard mostra o que foi executado, -o que foi bloqueado e o que a política informou ao agente — para que você não fique no escuro +Cada chamada de ferramenta feita pelo seu agente é registrada localmente. O dashboard mostra o que foi executado, +o que foi bloqueado e o que a política comunicou ao agente — para que você não fique no escuro quando algo der errado. → [Guia do dashboard](https://docs.befailproof.ai/dashboard) --- @@ -153,8 +162,8 @@ quando algo der errado. → [Guia do dashboard](https://docs.befailproof.ai/dash | | | |---|---| -| [Primeiros Passos](https://docs.befailproof.ai/getting-started) | Instalação e primeiros passos | -| [Políticas Integradas](https://docs.befailproof.ai/built-in-policies) | Todas as 30 políticas com parâmetros | +| [Primeiros Passos](https://docs.befailproof.ai/getting-started) | Instalação e primeiras etapas | +| [Políticas Nativas](https://docs.befailproof.ai/built-in-policies) | Todas as 30 políticas com parâmetros | | [Políticas Personalizadas](https://docs.befailproof.ai/custom-policies) | Crie as suas próprias | | [Configuração](https://docs.befailproof.ai/configuration) | Escopos de configuração e regras de mesclagem | | [Dashboard](https://docs.befailproof.ai/dashboard) | Monitor de sessão e atividade de políticas | @@ -164,18 +173,18 @@ quando algo der errado. → [Guia do dashboard](https://docs.befailproof.ai/dash ## Licença -MIT com [Commons Clause](https://commonsclause.com/) — gratuito para uso interno e pessoal; a revenda comercial do próprio failproofai requer um acordo separado. Consulte [LICENSE](./LICENSE) para o texto completo. +MIT com [Commons Clause](https://commonsclause.com/) — gratuito para uso interno e pessoal; a revenda comercial do failproofai em si requer um acordo separado. Consulte [LICENSE](./LICENSE) para o texto completo. --- ## Contribuindo -Consulte [CONTRIBUTING.md](./CONTRIBUTING.md). Novas políticas, casos extremos e traduções são bem-vindos. +Consulte [CONTRIBUTING.md](./CONTRIBUTING.md). Novas políticas, casos extremos e traduções são sempre bem-vindos. > **Faça o build antes de começar.** Execute `bun install && bun run build` primeiro. Este repositório executa -> os próprios hooks do failproofai sobre si mesmo, e eles resolvem o import `failproofai` em relação ao +> os próprios hooks do failproofai sobre si mesmo, e eles resolvem o import `failproofai` a partir do > bundle compilado em `dist/` — sem um build você encontrará erros de hook `Cannot find package 'failproofai'`. -> Refaça o build após alterar `src/`. Consulte +> Recompile após alterar `src/`. Consulte > [Build before the in-repo dev hooks will work](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- diff --git a/docs/i18n/README.ru.md b/docs/i18n/README.ru.md index 6204b028..e84b9461 100644 --- a/docs/i18n/README.ru.md +++ b/docs/i18n/README.ru.md @@ -18,13 +18,13 @@ **Переводы:** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md) **Разрешение ошибок во время выполнения для кодирующих агентов.** -Интегрируется с Claude Code и Codex. Перехватывает бесконечные циклы, опасные действия и утечки секретов -до того, как они станут инцидентами. Нулевая латентность. Работает локально. +Подключается к Claude Code и Codex. Перехватывает циклы, опасные действия и утечки секретов +до того, как они станут инцидентами. Нулевая задержка. Работает локально.

- Failproof AI в действии + failproofai в действии

--- @@ -78,9 +78,18 @@ Gemini CLI +        + + + + Hermes + +

-> Установите хуки для одного или любой комбинации: `failproofai policies --install --cli opencode pi gemini` (или `--cli claude codex copilot cursor opencode pi gemini`). Опустите `--cli` для автоматического обнаружения установленных CLI и выбора. +> Установите hooks для одного или любой комбинации: `failproofai policies --install --cli opencode pi gemini` (или `--cli claude codex copilot cursor opencode pi gemini hermes`). Опустите `--cli` для автоматического обнаружения установленных CLI и подсказок. +> +> **Hermes** (hermes-agent, шлюз Slack/Telegram) поддерживается как для **live-hook принудительного исполнения** (`--cli hermes` — одна установка перехватывает вызовы инструментов с каждой платформы и субагента), так и для автономного **аудита** воспроизведения сессий шлюза из отдельного `~/.hermes/state.db`. --- @@ -88,11 +97,11 @@ ```sh npm install -g failproofai -failproofai policies --install # или просто запустите `failproofai` и примите предложение при первом запуске +failproofai policies --install # или просто запустите `failproofai` и примите первую подсказку failproofai ``` -30 встроенных политик активируются немедленно. Панель управления на `localhost:8020`. Отключите подсказку при первом запуске с `FAILPROOFAI_NO_FIRST_RUN=1`. +30 встроенных политик активируются немедленно. Панель управления на `localhost:8020`. Отключите первую подсказку с помощью `FAILPROOFAI_NO_FIRST_RUN=1`. --- @@ -100,11 +109,11 @@ failproofai | Политика | Что она блокирует | |---|---| -| `block-push-master` | Прямые пуши в `main` / `master` | +| `block-push-master` | Прямые push в `main` / `master` | | `block-force-push` | `git push --force` | -| `block-work-on-main` | Коммиты, слияния, перебазирования на `main` / `master` | +| `block-work-on-main` | Коммиты, merges, rebases в `main` / `master` | | `block-rm-rf` | Рекурсивное удаление файлов | -| `sanitize-api-keys` | Утечки API-ключей в контекст агента | +| `sanitize-api-keys` | Утечки API ключей в контекст агента | → [Все 30 встроенных политик](https://docs.befailproof.ai/built-in-policies) @@ -112,8 +121,8 @@ failproofai ## Ваши собственные политики -Просто скиньте файл в `.failproofai/policies/` — он загружается автоматически, никаких флагов не нужно. -Закоммитьте его, и вся команда получит его при следующем пуле. +Поместите файл в `.failproofai/policies/` — он загружается автоматически, флаги не требуются. +Закоммитьте его, и вся команда получит его при следующем pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -123,7 +132,7 @@ customPolicies.add({ match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolInput?.file_path?.includes("production")) - return deny("Writes to production paths are blocked."); + return deny("Записи в production пути заблокированы."); return allow(); }, }); @@ -134,8 +143,8 @@ customPolicies.add({ | Решение | Эффект | |---|---| | `allow()` | Разрешить операцию | -| `deny(message)` | Заблокировать её — сообщение вернётся агенту | -| `instruct(message)` | Пропустить, но добавить контекст в следующий запрос агента | +| `deny(message)` | Заблокировать её — сообщение возвращается агенту | +| `instruct(message)` | Пропустить её, но добавить контекст в следующую подсказку агента | → [Руководство по пользовательским политикам](https://docs.befailproof.ai/custom-policies) @@ -143,9 +152,9 @@ customPolicies.add({ ## Видимость сессии -Каждый вызов инструмента, который делает ваш агент, логируется локально. Панель управления показывает, что было запущено, -что было заблокировано и что политика сказала агенту — так что вы не будете гадать, -когда что-то пойдёт не так. → [Руководство по панели управления](https://docs.befailproof.ai/dashboard) +Каждый вызов инструмента, который делает ваш агент, записывается локально. Панель управления показывает, что запустилось, +что было заблокировано, и что политика сообщила агенту — поэтому вы не гадаете, +когда что-то идёт не так. → [Руководство панели управления](https://docs.befailproof.ai/dashboard) --- @@ -153,12 +162,12 @@ customPolicies.add({ | | | |---|---| -| [Getting Started](https://docs.befailproof.ai/getting-started) | Установка и первые шаги | -| [Built-in Policies](https://docs.befailproof.ai/built-in-policies) | Все 30 политик с параметрами | -| [Custom Policies](https://docs.befailproof.ai/custom-policies) | Напишите свои | -| [Configuration](https://docs.befailproof.ai/configuration) | Области конфигурации и правила слияния | -| [Dashboard](https://docs.befailproof.ai/dashboard) | Монитор сессий и активность политик | -| [Architecture](https://docs.befailproof.ai/architecture) | Как работает система хуков | +| [Начало работы](https://docs.befailproof.ai/getting-started) | Установка и первые шаги | +| [Встроенные политики](https://docs.befailproof.ai/built-in-policies) | Все 30 политик с параметрами | +| [Пользовательские политики](https://docs.befailproof.ai/custom-policies) | Напишите свои | +| [Конфигурация](https://docs.befailproof.ai/configuration) | Области конфигурации и правила слияния | +| [Панель управления](https://docs.befailproof.ai/dashboard) | Монитор сессии и активность политик | +| [Архитектура](https://docs.befailproof.ai/architecture) | Как работает система hooks | --- @@ -168,12 +177,11 @@ MIT с [Commons Clause](https://commonsclause.com/) — бесплатно дл --- -## Вклад +## Участие в разработке -См. [CONTRIBUTING.md](./CONTRIBUTING.md). Новые политики, граничные случаи и переводы всегда приветствуются. +See [CONTRIBUTING.md](./CONTRIBUTING.md). Новые политики, граничные случаи и переводы всегда приветствуются. -> **Сначала соберите проект.** Запустите `bun install && bun run build`. Этот репозиторий использует собственные хуки failproofai, и они разрешают импорт `failproofai` относительно скомпилированного бандла `dist/` — без сборки вы получите ошибки хуков `Cannot find package 'failproofai'`. Пересоберите после изменений в `src/`. См. -> [Build before the in-repo dev hooks will work](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Соберите проект перед началом.** Сначала запустите `bun install && bun run build`. Этот репозиторий запускает собственные hooks failproofai на себе, и они разрешают импорт `failproofai` относительно скомпилированного пакета `dist/` — без build вы получите ошибки hooks `Cannot find package 'failproofai'`. Пересоберите после изменения `src/`. See [Build before the in-repo dev hooks will work](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- diff --git a/docs/i18n/README.tr.md b/docs/i18n/README.tr.md index c8105080..579f34ba 100644 --- a/docs/i18n/README.tr.md +++ b/docs/i18n/README.tr.md @@ -17,14 +17,14 @@ **Çeviriler:** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md) -**Kodlama ajanları için çalışma zamanı hata çözümü.** -Claude Code ve Codex ile entegre olur. Döngüleri, tehlikeli işlemleri ve gizli sızıntıları -olay haline gelmeden yakalar. Sıfır gecikme. Yerel olarak çalışır. +**Kodlama ajanları için çalışma zamanı hatası çözümü.** +Claude Code ve Codex'e bağlanır. Döngüleri, tehlikeli işlemleri ve gizli diliş sızıntılarını +olaylar haline gelmeden önce yakalar. Sıfır gecikme. Yerel olarak çalışır.

- Failproof AI işlemde + Failproof AI çalışmada

--- @@ -78,9 +78,18 @@ olay haline gelmeden yakalar. Sıfır gecikme. Yerel olarak çalışır. Gemini CLI +        + + + + Hermes + +

-> Bir veya birkaç kombinasyon için hook'ları yükleyin: `failproofai policies --install --cli opencode pi gemini` (veya `--cli claude codex copilot cursor opencode pi gemini`). Kurulu CLI'ları otomatik olarak algılamak ve istemde görüntülemek için `--cli` parametresini atlayın. +> Bir veya herhangi bir kombinasyon için kanca yükleyin: `failproofai policies --install --cli opencode pi gemini` (veya `--cli claude codex copilot cursor opencode pi gemini hermes`). Yüklü CLI'ları otomatik olarak algılamak ve istemek için `--cli` öğesini atlayın. +> +> **Hermes** (hermes-agent, bir Slack/Telegram ağ geçidi) hem **canlı kanca uygulaması** (`--cli hermes` — bir kurulum her platformdan ve alt ajantan araç çağrılarını keser) hem de çevrimdışı **denetim** için desteklenir. tek `~/.hermes/state.db` dosyasından ağ geçidi oturumlarının tekrar oynatılması. --- @@ -88,22 +97,22 @@ olay haline gelmeden yakalar. Sıfır gecikme. Yerel olarak çalışır. ```sh npm install -g failproofai -failproofai policies --install # veya sadece `failproofai` çalıştırın ve ilk çalışmada istemi kabul edin +failproofai policies --install # veya sadece `failproofai` çalıştırın ve ilk çalıştırma istemini kabul edin failproofai ``` -30 yerleşik ilke hemen devreye girer. Gösterge paneli `localhost:8020` adresinde bulunur. İlk çalışma istemini `FAILPROOFAI_NO_FIRST_RUN=1` ile devre dışı bırakın. +30 yerleşik ilke hemen etkinleşir. Pano `localhost:8020` adresinde. İlk çalıştırma istemini `FAILPROOFAI_NO_FIRST_RUN=1` ile devre dışı bırakın. --- -## Ne engeller +## Neleri durdurur -| İlke | Ne engellediği | +| İlke | Neyi engeller | |---|---| -| `block-push-master` | `main` / `master` dalına doğrudan itme | +| `block-push-master` | `main` / `master` öğesine doğrudan itme işlemleri | | `block-force-push` | `git push --force` | -| `block-work-on-main` | `main` / `master` üzerinde değişiklikleri kaydetme, birleştirme, yeniden temellendirme | -| `block-rm-rf` | Tekrarlamalı dosya silme | +| `block-work-on-main` | `main` / `master` üzerine işlemeler, birleştirmeler, yeniden temeller | +| `block-rm-rf` | Özyinelemeli dosya silme | | `sanitize-api-keys` | API anahtarlarının ajan bağlamına sızması | → [Tüm 30 yerleşik ilke](https://docs.befailproof.ai/built-in-policies) @@ -112,8 +121,8 @@ failproofai ## Kendi ilkeleriniz -`.failproofai/policies/` klasörüne bir dosya bırakın — otomatik olarak yüklenir, hiçbir parametre gerekmez. -Bunu kaydedin ve tüm takım bir sonraki çekme sırasında alır. +`.failproofai/policies/` içine bir dosya bırakın — otomatik olarak yüklenir, bayrak gerekmez. +Taahhüt edin ve tüm takım bir sonraki çekişte alacaktır. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -123,19 +132,19 @@ customPolicies.add({ match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolInput?.file_path?.includes("production")) - return deny("Production yollarına yazma işlemleri engellenir."); + return deny("Üretim yollarına yazma işlemleri engellendi."); return allow(); }, }); ``` -Her ilke için kullanılabilir üç karar: +Her ilkeye sunulan üç karar: | Karar | Etki | |---|---| | `allow()` | İşleme izin ver | -| `deny(message)` | Engelle — mesaj ajana geri döner | -| `instruct(message)` | İzin ver, ancak ajanın bir sonraki isteme bağlam ekle | +| `deny(message)` | Engelle — ileti ajana geri gider | +| `instruct(message)` | İzin ver, ama ajana sonraki tavsiyeye bağlam ekle | → [Özel ilkeler rehberi](https://docs.befailproof.ai/custom-policies) @@ -143,8 +152,9 @@ Her ilke için kullanılabilir üç karar: ## Oturum görünürlüğü -Ajanınızın yaptığı her araç çağrısı yerel olarak günlüğe kaydedilir. Gösterge paneli neyin çalıştığını, -neyin engellendiğini ve ilkenin ajana söylediklerini gösterir — böylece bir şeyler yanlış gittiğinde tahmin yapmıyorsunuz. → [Gösterge paneli rehberi](https://docs.befailproof.ai/dashboard) +Ajanınızın yaptığı her araç çağrısı yerel olarak günlüğe kaydedilir. Pano neyin çalıştığını, +neyin engellediğini ve ilkenin ajana ne söylediğini gösterir — böylece bir şey +yanlış gittiğinde tahmin etmezsiniz. → [Pano rehberi](https://docs.befailproof.ai/dashboard) --- @@ -156,24 +166,24 @@ neyin engellendiğini ve ilkenin ajana söylediklerini gösterir — böylece bi | [Yerleşik İlkeler](https://docs.befailproof.ai/built-in-policies) | Tüm 30 ilke ve parametreleri | | [Özel İlkeler](https://docs.befailproof.ai/custom-policies) | Kendi ilkelerinizi yazın | | [Yapılandırma](https://docs.befailproof.ai/configuration) | Yapılandırma kapsamları ve birleştirme kuralları | -| [Gösterge Paneli](https://docs.befailproof.ai/dashboard) | Oturum monitörü ve ilke aktivitesi | -| [Mimari](https://docs.befailproof.ai/architecture) | Hook sistemi nasıl çalışır | +| [Pano](https://docs.befailproof.ai/dashboard) | Oturum monitörü ve ilke etkinliği | +| [Mimari](https://docs.befailproof.ai/architecture) | Kanca sistemi nasıl çalışır | --- ## Lisans -MIT ve [Commons Clause](https://commonsclause.com/) — dahili ve kişisel kullanım için ücretsiz; failproofai'nin ticari yeniden satışı ayrı bir anlaşma gerektirir. Tam metin için [LICENSE](./LICENSE) dosyasına bakın. +MIT ve [Commons Clause](https://commonsclause.com/) — dahili ve kişisel kullanım için ücretsiz; failproofai'nin ticari yeniden satışı ayrı bir anlaşma gerektirir. Tam metin için [LICENSE](./LICENSE) bölümüne bakın. --- -## Katkıda Bulunma +## Katkıda bulunmak -[CONTRIBUTING.md](./CONTRIBUTING.md) dosyasına bakın. Yeni ilkeler, kenar durumlar ve çeviriler hoş karşılanır. +[CONTRIBUTING.md](./CONTRIBUTING.md) bölümüne bakın. Yeni ilkeler, sınır durumları ve çeviriler hepsi hoş geldiniz. -> **Başlamadan önce derleyin.** Önce `bun install && bun run build` komutunu çalıştırın. Bu depo, failproofai'nin kendi hook'larını kendisi üzerinde çalıştırır ve `failproofai` ithalatını derlenmiş `dist/` paketine karşı çözer — derleme olmadan `Cannot find package 'failproofai'` hook hatalarına rastlarsınız. `src/` değişikliklerinden sonra yeniden derleyin. Bkz. [In-repo dev hook'larının çalışması için derleme gerekli](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Başlamadan önce derleyin.** Önce `bun install && bun run build` komutunu çalıştırın. Bu depo, failproofai'nin kendi kancalarını kendisinde çalıştırır ve `failproofai` ithalatını derlenmiş `dist/` paketi karşı çözer — bir derleme olmadan `Cannot find package 'failproofai'` kanca hatalarına çarparsınız. `src/` değişikliğinden sonra yeniden derleyin. [Depo içi geliştirme kanalarının çalışması için önce derleme](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) bölümüne bakın. --- -[Nivedit Jain](https://github.com/NiveditJain) ve [Nikita Agarwal](https://github.com/nk-ag) tarafından yapılmıştır. +[Nivedit Jain](https://github.com/NiveditJain) ve [Nikita Agarwal](https://github.com/nk-ag) tarafından oluşturulmuştur. [befailproof.ai](https://befailproof.ai) diff --git a/docs/i18n/README.vi.md b/docs/i18n/README.vi.md index 56060749..d0ff72b8 100644 --- a/docs/i18n/README.vi.md +++ b/docs/i18n/README.vi.md @@ -15,10 +15,10 @@ [![Docs](https://img.shields.io/badge/docs-befailproof.ai-002CA7?style=flat-square)](https://docs.befailproof.ai/introduction) [![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](./LICENSE) -**Bản dịch:** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md) +**Dịch:** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md) -**Giải pháp xử lý lỗi thời gian chạy cho các tác nhân lập trình.** -Kết nối với Claude Code và Codex. Phát hiện vòng lặp, hành động nguy hiểm và rò rỉ bí mật +**Giải quyết sự cố runtime cho các agents lập trình.** +Kết nối với Claude Code và Codex. Bắt các vòng lặp, hành động nguy hiểm và rò rỉ bí mật trước khi chúng trở thành sự cố. Độ trễ bằng không. Chạy cục bộ. @@ -29,7 +29,7 @@ trước khi chúng trở thành sự cố. Độ trễ bằng không. Chạy c --- -## Hỗ trợ các CLI tác nhân +## Các CLI agent được hỗ trợ

@@ -78,9 +78,18 @@ trước khi chúng trở thành sự cố. Độ trễ bằng không. Chạy c Gemini CLI +        + + + + Hermes + +

-> Cài đặt hook cho một hoặc nhiều kết hợp: `failproofai policies --install --cli opencode pi gemini` (hoặc `--cli claude codex copilot cursor opencode pi gemini`). Bỏ qua `--cli` để tự động phát hiện các CLI đã cài đặt và nhắc nhở. +> Cài đặt hooks cho một hoặc bất kỳ tổ hợp nào: `failproofai policies --install --cli opencode pi gemini` (hoặc `--cli claude codex copilot cursor opencode pi gemini hermes`). Bỏ qua `--cli` để tự động phát hiện các CLI được cài đặt và nhắc lựa chọn. +> +> **Hermes** (hermes-agent, một gateway Slack/Telegram) được hỗ trợ cho cả **thực thi live-hook** (`--cli hermes` — một cài đặt chặn các lệnh gọi công cụ từ mọi nền tảng và subagent) và **kiểm toán** ngoại tuyến của các phiên gateway của nó từ `~/.hermes/state.db` duy nhất. --- @@ -88,32 +97,32 @@ trước khi chúng trở thành sự cố. Độ trễ bằng không. Chạy c ```sh npm install -g failproofai -failproofai policies --install # hoặc chỉ cần chạy `failproofai` và chấp nhận lời nhắc lần đầu +failproofai policies --install # hoặc chỉ chạy `failproofai` và chấp nhận lời nhắc lần đầu failproofai ``` -30 chính sách tích hợp được kích hoạt ngay lập tức. Bảng điều khiển tại `localhost:8020`. Vô hiệu hóa lời nhắc lần đầu với `FAILPROOFAI_NO_FIRST_RUN=1`. +30 chính sách tích hợp kích hoạt ngay lập tức. Bảng điều khiển tại `localhost:8020`. Tắt lời nhắc lần đầu với `FAILPROOFAI_NO_FIRST_RUN=1`. --- -## Những gì nó ngăn chặn +## Những gì nó chặn | Chính sách | Những gì nó chặn | |---|---| | `block-push-master` | Đẩy trực tiếp đến `main` / `master` | | `block-force-push` | `git push --force` | -| `block-work-on-main` | Commit, hợp nhất, rebase trên `main` / `master` | +| `block-work-on-main` | Commits, merges, rebases trên `main` / `master` | | `block-rm-rf` | Xóa tệp đệ quy | -| `sanitize-api-keys` | Khóa API rò rỉ vào ngữ cảnh tác nhân | +| `sanitize-api-keys` | Các khóa API rò rỉ vào ngữ cảnh agent | → [Tất cả 30 chính sách tích hợp](https://docs.befailproof.ai/built-in-policies) --- -## Chính sách của riêng bạn +## Các chính sách của riêng bạn Thả một tệp vào `.failproofai/policies/` — nó tải tự động, không cần cờ nào. -Commit nó và toàn bộ nhóm sẽ nhận được nó vào lần pull tiếp theo. +Commit nó và toàn bộ nhóm sẽ nhận được nó trong pull tiếp theo. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -123,7 +132,7 @@ customPolicies.add({ match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolInput?.file_path?.includes("production")) - return deny("Ghi vào đường dẫn sản xuất bị chặn."); + return deny("Ghi vào các đường dẫn production bị chặn."); return allow(); }, }); @@ -133,9 +142,9 @@ Ba quyết định có sẵn cho mọi chính sách: | Quyết định | Hiệu ứng | |---|---| -| `allow()` | Cho phép thao tác | -| `deny(message)` | Chặn nó — thông báo quay lại tác nhân | -| `instruct(message)` | Cho phép nó thông qua, nhưng thêm ngữ cảnh vào lời nhắc tiếp theo của tác nhân | +| `allow()` | Cho phép hoạt động | +| `deny(message)` | Chặn nó — thông báo quay lại agent | +| `instruct(message)` | Cho phép thực hiện, nhưng thêm ngữ cảnh vào lời nhắc tiếp theo của agent | → [Hướng dẫn chính sách tùy chỉnh](https://docs.befailproof.ai/custom-policies) @@ -143,9 +152,9 @@ Ba quyết định có sẵn cho mọi chính sách: ## Khả năng hiển thị phiên -Mọi lệnh gọi công cụ mà tác nhân của bạn thực hiện đều được ghi lại cục bộ. Bảng điều khiển hiển thị những gì đã chạy, -những gì bị chặn và những gì chính sách cho tác nhân — vì vậy bạn không phải đoán -khi có điều gì đó không ổn. → [Hướng dẫn bảng điều khiển](https://docs.befailproof.ai/dashboard) +Mọi lệnh gọi công cụ mà agent của bạn thực hiện đều được ghi nhật ký cục bộ. Bảng điều khiển hiển thị những gì đã chạy, +những gì bị chặn và những gì chính sách đã nói với agent — để bạn không phải đoán +khi có sự cố. → [Hướng dẫn bảng điều khiển](https://docs.befailproof.ai/dashboard) --- @@ -164,19 +173,19 @@ khi có điều gì đó không ổn. → [Hướng dẫn bảng điều khiển ## Giấy phép -MIT với [Commons Clause](https://commonsclause.com/) — miễn phí để sử dụng nội bộ và cá nhân; bán lại thương mại của failproofai yêu cầu một thỏa thuận riêng. Xem [LICENSE](./LICENSE) để biết toàn bộ nội dung. +MIT với [Commons Clause](https://commonsclause.com/) — miễn phí cho việc sử dụng nội bộ và cá nhân; bán lại failproofai yêu cầu một thỏa thuận riêng. Xem [LICENSE](./LICENSE) để biết toàn bộ văn bản. --- ## Đóng góp -Xem [CONTRIBUTING.md](./CONTRIBUTING.md). Chính sách mới, trường hợp cạnh biên và bản dịch đều được hoan nghênh. +Xem [CONTRIBUTING.md](./CONTRIBUTING.md). Các chính sách mới, trường hợp đặc biệt và bản dịch đều được chào đón. -> **Xây dựng trước khi bắt đầu.** Chạy `bun install && bun run build` trước tiên. Kho này chạy -> hook của failproofai trên chính nó, và chúng giải quyết nhập `failproofai` so với -> gói `dist/` đã biên dịch — nếu không có bản dựng bạn sẽ gặp lỗi `Cannot find package 'failproofai'` -> hook. Xây dựng lại sau khi thay đổi `src/`. Xem -> [Xây dựng trước khi hook dev trong kho sẽ hoạt động](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Xây dựng trước khi bắt đầu.** Chạy `bun install && bun run build` trước. Repository này chạy +> các hook riêng của failproofai trên chính nó, và chúng giải quyết nhập `failproofai` dựa trên +> gói `dist/` được biên dịch — nếu không có bản dựng, bạn sẽ gặp lỗi hook `Cannot find package 'failproofai'`. +> Xây dựng lại sau khi thay đổi `src/`. Xem +> [Build before the in-repo dev hooks will work](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md index 1800b6c8..b6112fe9 100644 --- a/docs/i18n/README.zh.md +++ b/docs/i18n/README.zh.md @@ -17,8 +17,8 @@ **翻译版本：** [简体中文](./docs/i18n/README.zh.md) · [日本語](./docs/i18n/README.ja.md) · [한국어](./docs/i18n/README.ko.md) · [Español](./docs/i18n/README.es.md) · [Português](./docs/i18n/README.pt-br.md) · [Deutsch](./docs/i18n/README.de.md) · [Français](./docs/i18n/README.fr.md) · [Русский](./docs/i18n/README.ru.md) · [हिन्दी](./docs/i18n/README.hi.md) · [Türkçe](./docs/i18n/README.tr.md) · [Tiếng Việt](./docs/i18n/README.vi.md) · [Italiano](./docs/i18n/README.it.md) · [العربية](./docs/i18n/README.ar.md) · [עברית](./docs/i18n/README.he.md) -**为编码智能体提供运行时故障处理能力。** -集成 Claude Code 和 Codex，在循环、危险操作和密钥泄露酿成事故之前将其拦截。零延迟，本地运行。 +**面向编程智能体的运行时故障修复工具。** +接入 Claude Code 和 Codex，在循环、危险操作和密钥泄露演变成事故之前将其拦截。零延迟，本地运行。 @@ -77,9 +77,18 @@ Gemini CLI +        + + + + Hermes + +

-> 可为一个或多个 CLI 安装 hooks：`failproofai policies --install --cli opencode pi gemini`（或 `--cli claude codex copilot cursor opencode pi gemini`）。省略 `--cli` 则自动检测已安装的 CLI 并提示选择。 +> 可为一个或多个 CLI 安装 hooks：`failproofai policies --install --cli opencode pi gemini`（或 `--cli claude codex copilot cursor opencode pi gemini hermes`）。省略 `--cli` 参数将自动检测已安装的 CLI 并提示选择。 +> +> **Hermes**（hermes-agent，一个 Slack/Telegram 网关）同时支持**实时 hook 执行**（`--cli hermes` — 一次安装即可拦截所有平台和子智能体的工具调用）以及离线**审计**回放，可从单一的 `~/.hermes/state.db` 文件回放其网关会话。 --- @@ -87,11 +96,11 @@ ```sh npm install -g failproofai -failproofai policies --install # 或直接运行 `failproofai` 并在首次运行提示中确认 +failproofai policies --install # 或直接运行 `failproofai` 并接受首次运行提示 failproofai ``` -30 条内置策略立即生效。Dashboard 地址为 `localhost:8020`。设置 `FAILPROOFAI_NO_FIRST_RUN=1` 可禁用首次运行提示。 +30 条内置策略即时生效。访问 `localhost:8020` 查看控制台。使用 `FAILPROOFAI_NO_FIRST_RUN=1` 禁用首次运行提示。 --- @@ -111,7 +120,7 @@ failproofai ## 自定义策略 -将文件放入 `.failproofai/policies/` 目录即可自动加载，无需任何额外参数。提交到代码库后，团队成员在下次拉取时即可同步生效。 +将文件放入 `.failproofai/policies/` 目录即可自动加载，无需任何额外参数。提交到代码库后，团队所有成员在下次拉取时即可生效。 ```js import { customPolicies, deny, allow } from "failproofai"; @@ -132,16 +141,16 @@ customPolicies.add({ | 决策 | 效果 | |---|---| | `allow()` | 允许该操作 | -| `deny(message)` | 拦截操作——消息将返回给智能体 | -| `instruct(message)` | 放行，但在智能体的下一次提示中附加上下文 | +| `deny(message)` | 阻止该操作——消息将返回给智能体 | +| `instruct(message)` | 放行该操作，但向智能体的下一个提示词中追加上下文信息 | → [自定义策略指南](https://docs.befailproof.ai/custom-policies) --- -## 会话可视化 +## 会话可见性 -智能体的每一次工具调用都会在本地记录日志。Dashboard 展示了哪些操作已执行、哪些被拦截，以及策略向智能体返回了什么内容——让你在出现问题时不再两眼一抹黑。→ [Dashboard 指南](https://docs.befailproof.ai/dashboard) +智能体发起的每次工具调用都会在本地记录日志。控制台展示已执行的操作、被拦截的操作以及策略向智能体反馈的内容——让你在出现问题时不再茫然无措。→ [控制台指南](https://docs.befailproof.ai/dashboard) --- @@ -149,28 +158,28 @@ customPolicies.add({ | | | |---|---| -| [快速入门](https://docs.befailproof.ai/getting-started) | 安装与初始配置 | -| [内置策略](https://docs.befailproof.ai/built-in-policies) | 全部 30 条策略及其参数说明 | -| [自定义策略](https://docs.befailproof.ai/custom-policies) | 编写你自己的策略 | +| [快速上手](https://docs.befailproof.ai/getting-started) | 安装与入门步骤 | +| [内置策略](https://docs.befailproof.ai/built-in-policies) | 全部 30 条策略及参数说明 | +| [自定义策略](https://docs.befailproof.ai/custom-policies) | 编写自己的策略 | | [配置](https://docs.befailproof.ai/configuration) | 配置作用域与合并规则 | -| [Dashboard](https://docs.befailproof.ai/dashboard) | 会话监控与策略活动 | +| [控制台](https://docs.befailproof.ai/dashboard) | 会话监控与策略活动 | | [架构](https://docs.befailproof.ai/architecture) | Hook 系统的工作原理 | --- ## 许可证 -MIT 附加 [Commons Clause](https://commonsclause.com/)——个人及内部使用免费；将 failproofai 本身用于商业转售需另行签订协议。完整条款请参阅 [LICENSE](./LICENSE)。 +MIT 附加 [Commons Clause](https://commonsclause.com/) — 免费用于内部和个人用途；将 failproofai 本身作为商业产品转售需另行签订协议。完整条款请参阅 [LICENSE](./LICENSE)。 --- ## 贡献 -请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。欢迎贡献新策略、边界用例以及翻译。 +请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。欢迎贡献新策略、边界用例和翻译内容。 -> **开始前请先构建项目。** 首先运行 `bun install && bun run build`。本仓库使用 failproofai 自身的 hooks 对自身进行管控，这些 hooks 会将 `failproofai` 的导入解析到编译后的 `dist/` 包——若未构建，则会出现 `Cannot find package 'failproofai'` 的 hook 错误。修改 `src/` 后需重新构建。详见 [构建说明：让仓库内开发 hooks 正常工作](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)。 +> **开始前请先构建项目。** 首先运行 `bun install && bun run build`。本仓库会对自身运行 failproofai 的 hooks，这些 hooks 从编译后的 `dist/` 包中解析 `failproofai` 导入——如果未执行构建，将会遇到 `Cannot find package 'failproofai'` hook 错误。修改 `src/` 后需重新构建。详见 [构建后才能使用仓库内开发 hooks](./CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)。 --- -由 [Nivedit Jain](https://github.com/NiveditJain) 和 [Nikita Agarwal](https://github.com/nk-ag) 共同构建。 +由 [Nivedit Jain](https://github.com/NiveditJain) 和 [Nikita Agarwal](https://github.com/nk-ag) 共同打造。 [befailproof.ai](https://befailproof.ai) diff --git a/docs/it/architecture.mdx b/docs/it/architecture.mdx index 9f666bba..7ffc5fe1 100644 --- a/docs/it/architecture.mdx +++ b/docs/it/architecture.mdx @@ -1,10 +1,11 @@ --- +--- title: Architettura -description: "Come il gestore hook, il caricamento della configurazione e la valutazione delle policy funzionano internamente" +description: "Come funzionano internamente il gestore hook, il caricamento della configurazione e la valutazione delle policy" icon: sitemap --- -Questo documento spiega come failproofai funziona internamente: come il sistema hook intercetta le chiamate agli strumenti dell'agente, come viene caricata e unita la configurazione, come vengono valutate le policy e come il dashboard monitora l'attività dell'agente. +Questo documento spiega come failproofai funziona internamente: come il sistema di hook intercetta le chiamate agli strumenti dell'agente, come viene caricata e unita la configurazione, come vengono valutate le policy e come il dashboard monitora l'attività dell'agente. --- @@ -12,10 +13,10 @@ Questo documento spiega come failproofai funziona internamente: come il sistema failproofai ha due sottosistemi indipendenti: -1. **Gestore hook** - Un veloce sottoprocesso CLI che Claude Code invoca su ogni chiamata dello strumento dell'agente. Valuta le policy e restituisce una decisione. +1. **Gestore hook** - Un veloce sottoprocesso CLI che Claude Code richiama per ogni chiamata allo strumento dell'agente. Valuta le policy e restituisce una decisione. 2. **Agent Monitor (Dashboard)** - Un'applicazione web Next.js per monitorare le sessioni dell'agente e gestire le policy. -Entrambi i sottosistemi condividono file di configurazione in `~/.failproofai/` e nella directory `.failproofai/` del progetto, ma vengono eseguiti come processi separati e comunicano solo attraverso il filesystem. +Entrambi i sottosistemi condividono i file di configurazione in `~/.failproofai/` e nella directory `.failproofai/` del progetto, ma vengono eseguiti come processi separati e comunicano solo attraverso il filesystem. --- @@ -23,7 +24,7 @@ Entrambi i sottosistemi condividono file di configurazione in `~/.failproofai/` ### Integrazione con Claude Code -Quando esegui `failproofai policies --install`, scrive voci come questa in `~/.claude/settings.json`: +Quando esegui `failproofai policies --install`, vengono scritte voci come questa in `~/.claude/settings.json`: ```json { @@ -44,7 +45,7 @@ Quando esegui `failproofai policies --install`, scrive voci come questa in `~/.c } ``` -Claude Code quindi invoca `failproofai --hook PreToolUse` come sottoprocesso prima di ogni chiamata dello strumento, passando un payload JSON su stdin. +Claude Code quindi richiama `failproofai --hook PreToolUse` come sottoprocesso prima di ogni chiamata allo strumento, passando un payload JSON su stdin. ### Formato del payload @@ -62,7 +63,7 @@ Claude Code quindi invoca `failproofai --hook PreToolUse` come sottoprocesso pri Per gli eventi `PostToolUse`, il payload contiene anche `tool_result` con l'output dello strumento. -Il gestore impone un limite di stdin di 1 MB. I payload che superano questo limite vengono scartati e tutte le policy consentono implicitamente. +Il gestore applica un limite di 1 MB per stdin. I payload che superano questo limite vengono scartati e tutte le policy consentono implicitamente. ### Formato della risposta @@ -100,23 +101,23 @@ Il gestore impone un limite di stdin di 1 MB. I payload che superano questo limi **Consenti:** - Codice di uscita: `0` -- Stdout vuoto +- stdout vuoto **Consenti con messaggio:** -`allow(message)` consente a una policy di inviare un contesto informativo a Claude anche quando l'operazione è consentita. Il gestore hook scrive il seguente JSON su **stdout** (non su un file di configurazione — questa è la risposta del gestore a Claude Code, proprio come le risposte deny e instruct sopra): +`allow(message)` consente a una policy di inviare un contesto informativo a Claude anche quando l'operazione è consentita. Il gestore hook scrive il seguente JSON su **stdout** (non un file di configurazione — questa è la risposta del gestore a Claude Code, proprio come le risposte deny e instruct precedenti): ```json -// Scritto su stdout dal processo del gestore hook +// Written to stdout by the hook handler process { "hookSpecificOutput": { "additionalContext": "All CI checks passed on branch 'feat/my-feature'." } } ``` -- Codice di uscita: `0` (operazione consentita) -- Quando più policy restituiscono `allow` con un messaggio, i loro messaggi vengono uniti con newline in una singola stringa `additionalContext` -- Se nessuna policy fornisce un messaggio, stdout è vuoto (stesso di prima) +- Codice di uscita: `0` (l'operazione è consentita) +- Quando più policy restituiscono `allow` con un messaggio, i loro messaggi vengono uniti con interruzioni di riga in una singola stringa `additionalContext` +- Se nessuna policy fornisce un messaggio, stdout è vuoto (come prima) ### Pipeline di elaborazione @@ -145,7 +146,7 @@ L'intero processo viene eseguito in meno di 100ms per payload tipici senza chiam ## Caricamento della configurazione -`src/hooks/hooks-config.ts` implementa il caricamento della configurazione a tre livelli. +`src/hooks/hooks-config.ts` implementa il caricamento della configurazione in tre ambiti. ```text [1] {cwd}/.failproofai/policies-config.json ← project (highest priority) @@ -155,11 +156,11 @@ L'intero processo viene eseguito in meno di 100ms per payload tipici senza chiam Logica di unione: - `enabledPolicies` - unione deduplicate tra tutti e tre i file -- `policyParams` - per policy, il primo file che lo definisce vince completamente -- `customPoliciesPath` - il primo file che lo definisce vince -- `llm` - il primo file che lo definisce vince +- `policyParams` - per chiave di policy, il primo file che la definisce vince completamente +- `customPoliciesPath` - il primo file che la definisce vince +- `llm` - il primo file che la definisce vince -Il dashboard web utilizza `readHooksConfig()` (solo globale) per leggere e scrivere, poiché non viene invocato con un cwd di progetto. +Il dashboard web utilizza `readHooksConfig()` (solo globale) per la lettura e la scrittura, poiché non viene richiamato con un cwd di progetto. --- @@ -169,18 +170,18 @@ Il dashboard web utilizza `readHooksConfig()` (solo globale) per leggere e scriv Per ogni policy: -1. Cercare lo schema `params` della policy (se ne ha uno). -2. Leggere `policyParams[policy.name]` dalla configurazione unita. -3. Unire i valori forniti dall'utente sui default dello schema per produrre `ctx.params`. -4. Chiamare `policy.fn(ctx)` con il contesto risolto. -5. Se il risultato è `deny`, fermarsi immediatamente e restituire quella decisione. -6. Se il risultato è `instruct`, accumulare il messaggio e continuare. -7. Se il risultato è `allow`, continuare alla policy successiva. +1. Cerca lo schema `params` della policy (se ne ha uno). +2. Leggi `policyParams[policy.name]` dalla configurazione unita. +3. Unisci i valori forniti dall'utente sui valori predefiniti dello schema per produrre `ctx.params`. +4. Chiama `policy.fn(ctx)` con il contesto risolto. +5. Se il risultato è `deny`, fermarti immediatamente e restituisci quella decisione. +6. Se il risultato è `instruct`, accumula il messaggio e continua. +7. Se il risultato è `allow`, continua alla policy successiva. -Dopo che tutte le policy vengono eseguite: -- Se è stato restituito un `deny`, emettere la risposta deny. -- Se sono stati raccolti ritorni `instruct`, emettere una singola risposta instruct con tutti i messaggi uniti. -- Altrimenti, emettere una risposta allow (stdout vuoto, uscita 0). +Dopo l'esecuzione di tutte le policy: +- Se è stata restituita una qualsiasi `deny`, emetti la risposta deny. +- Se sono state raccolte risposte `instruct`, emetti una singola risposta instruct con tutti i messaggi uniti. +- Altrimenti, emetti una risposta allow (stdout vuoto, exit 0). --- @@ -204,9 +205,9 @@ interface BuiltinPolicyDefinition { } ``` -Le policy che accettano `params` dichiarano un `PolicyParamsSchema` con tipi e default per ogni parametro. Il valutatore di policy inietta i valori risolti in `ctx.params` prima di chiamare `fn`. Le funzioni di policy leggono `ctx.params` senza protezione null perché i default vengono sempre applicati per primo. +Le policy che accettano `params` dichiarano uno `PolicyParamsSchema` con tipi e valori predefiniti per ogni parametro. Il valutatore di policy inietta i valori risolti in `ctx.params` prima di chiamare `fn`. Le funzioni di policy leggono `ctx.params` senza protezioni null perché i valori predefiniti vengono sempre applicati prima. -La corrispondenza di pattern all'interno delle policy utilizza token di comando analizzati (argv), non corrispondenza di stringhe grezze. Questo previene il bypass tramite iniezione di operatori shell (ad es. un pattern per `sudo systemctl status *` non può essere bypassato aggiungendo `; rm -rf /` al comando). +La corrispondenza dei pattern all'interno delle policy utilizza token di comando analizzati (argv), non la corrispondenza di stringhe grezze. Questo previene il bypass tramite iniezione di operatori shell (ad es. un pattern per `sudo systemctl status *` non può essere bypassato aggiungendo `; rm -rf /` al comando). --- @@ -227,17 +228,17 @@ export function clearCustomHooks(): void { ... } // used in tests `src/hooks/custom-hooks-loader.ts` carica il file di policy dell'utente: -1. Leggere `customPoliciesPath` dalla configurazione; saltare se assente. -2. Risolvere al percorso assoluto; controllare che il file esista. -3. Riscrivere tutti gli import `from "failproofai"` al percorso dist effettivo in modo che `customPolicies` si risolva nello stesso registro `globalThis`. -4. Riscrivere ricorsivamente gli import locali transitivi per garantire la compatibilità ESM. -5. Scrivere file `.mjs` temporanei e `import()` il file di ingresso. -6. Chiamare `getCustomHooks()` per recuperare gli hook registrati. -7. Pulire tutti i file temporanei in un blocco `finally`. +1. Leggi `customPoliciesPath` dalla configurazione; salta se assente. +2. Risolvi al percorso assoluto; controlla che il file esista. +3. Riscrivi tutti gli import `from "failproofai"` al percorso dist effettivo in modo che `customPolicies` si risolva nello stesso registro `globalThis`. +4. Riscrivi ricorsivamente gli import locali transitivi per assicurare la compatibilità ESM. +5. Scrivi file `.mjs` temporanei e esegui l'import del file di entry. +6. Chiama `getCustomHooks()` per recuperare gli hook registrati. +7. Pulisci tutti i file temp in un blocco `finally`. -Su qualsiasi errore (file non trovato, errore di sintassi, errore di importazione), l'errore viene registrato in `~/.failproofai/hook.log` e il loader restituisce un array vuoto. Le policy integrate non sono interessate. +In caso di errore (file non trovato, errore di sintassi, fallimento dell'import), l'errore viene registrato in `~/.failproofai/hook.log` e il caricatore restituisce un array vuoto. Le policy integrate non sono interessate. -Le policy personalizzate vengono valutate dopo tutte le policy integrate. Un `deny` di una policy personalizzata ancora cortocircuita ulteriori policy personalizzate (ma tutte le politiche integrate sono già state eseguite a quel punto). +Le policy personalizzate vengono valutate dopo tutte le policy integrate. Una policy personalizzata `deny` interrompe ancora ulteriormente le policy personalizzate (ma a quel punto tutte le policy integrate sono già state eseguite). --- @@ -258,13 +259,13 @@ Dopo ogni evento hook, il gestore aggiunge una riga JSONL a `~/.failproofai/hook } ``` -Una riga per ogni policy che ha preso una decisione non-allow. Le decisioni allow non vengono registrate (per mantenere il file piccolo). +Una riga per ogni policy che ha preso una decisione non allow. Le decisioni allow non vengono registrate (per mantenere il file piccolo). --- ## Architettura del dashboard -Il dashboard è un'applicazione **Next.js 16** che utilizza l'App Router con React Server Components e Server Actions. +Il dashboard è un'applicazione **Next.js 16** che utilizza App Router con React Server Components e Server Actions. ```text app/ @@ -284,18 +285,18 @@ app/ download/[project]/[session]/route.ts ← Per-CLI session export (JSONL or JSON) ``` -**Flusso dei dati:** +**Flusso di dati:** -- I componenti della pagina chiamano `lib/projects.ts` e `lib/log-entries.ts` per leggere i dati del progetto/sessione direttamente dal filesystem (nessun livello API per le letture). -- La pagina Policies utilizza Server Actions per tutte le mutazioni (toggle, aggiornamento parametri, installazione/rimozione). -- Il visualizzatore della sessione analizza il formato di trascritto JSONL di Claude e visualizza una timeline di messaggi e chiamate ai strumenti. +- I componenti della pagina chiamano `lib/projects.ts` e `lib/log-entries.ts` per leggere i dati di progetto/sessione direttamente dal filesystem (nessun livello API per le letture). +- La pagina Policies utilizza Server Actions per tutte le mutazioni (attiva/disattiva, aggiornamento params, installa/rimuovi). +- Il visualizzatore di sessione analizza il formato di trascrizione JSONL di Claude e renderizza una timeline di messaggi e chiamate allo strumento. **Decisioni di progettazione chiave:** -- Nessun database - tutto lo stato persistente si trova in file semplici (`~/.failproofai/`, `~/.claude/projects/`). -- Server Actions per le mutazioni - nessuna API REST necessaria per le operazioni CRUD. -- React Server Components per le pagine di lettura - caricamento iniziale più veloce, nessun bundle client per il recupero dei dati. -- Componenti client solo dove è necessaria l'interattività (toggle policy, ricerca attività, visualizzatore log). +- Nessun database - tutto lo stato persistente è in file ordinari (`~/.failproofai/`, `~/.claude/projects/`). +- Server Actions per mutazioni - nessuna API REST necessaria per operazioni CRUD. +- React Server Components per pagine di lettura - caricamento iniziale più veloce, nessun bundle client per il recupero dati. +- Componenti client solo dove è necessaria l'interattività (attiva/disattiva policy, ricerca attività, visualizzatore log). --- diff --git a/docs/it/built-in-policies.mdx b/docs/it/built-in-policies.mdx index 3618d085..b13f76c4 100644 --- a/docs/it/built-in-policies.mdx +++ b/docs/it/built-in-policies.mdx @@ -1,22 +1,22 @@ --- -title: Politiche Built-in -description: "Tutte le 39 politiche built-in che rilevano i modalità di fallimento comuni degli agent" +title: Politiche integrate +description: "Tutte le 39 politiche integrate che catturano i comuni fallimenti degli agent" icon: shield --- -failproofai viene fornito con 39 politiche built-in che rilevano le modalità di fallimento comuni degli agent. Ogni politica si attiva su un tipo di evento hook specifico e su un nome di strumento. Diciannove politiche accettano parametri che ti permettono di regolarne il comportamento senza scrivere codice. Cinque politiche di workflow impongono una pipeline commit → push → PR → CI prima che Claude si fermi. +failproofai viene fornito con 39 politiche integrate che catturano i comuni fallimenti degli agent. Ogni politica si attiva su un tipo di hook event specifico e sul nome dello strumento. Diciannove politiche accettano parametri che ti permettono di regolarne il comportamento senza scrivere codice. Cinque politiche di workflow applicano una pipeline commit → push → PR → CI prima che Claude si fermi. --- ## Panoramica -Le politiche sono raggruppate in categorie: +Le politiche sono raggruppate per categorie: | Categoria | Politiche | Tipo di hook | |----------|----------|-----------| | [Comandi pericolosi](#comandi-pericolosi) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | | [Comandi infra](#comandi-infra) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [Secrets (sanitizer)](#secrets-sanitizer) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [Segreti (sanitizer)](#segreti-sanitizer) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | | [Ambiente](#ambiente) | block-env-files, protect-env-vars | PreToolUse | | [Accesso ai file](#accesso-ai-file) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | @@ -25,15 +25,15 @@ Le politiche sono raggruppate in categorie: | [Gestori di pacchetti](#gestori-di-pacchetti) | prefer-package-manager | PreToolUse | | [Workflow](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — ferma l'agent dal procedere. -- **`warn-`** — fornisce all'agent contesto aggiuntivo per l'auto-correzione. -- **`sanitize-`** — rimuove dati sensibili dall'output dello strumento prima che l'agent li veda. +- **`block-`** — ferma l'agent dall'andare avanti. +- **`warn-`** — fornisce all'agent un contesto aggiuntivo affinché possa correggersi automaticamente. +- **`sanitize-`** — ripulisce i dati sensibili dall'output dello strumento prima che l'agent li veda. -### Spazi dei nomi +### Namespace -Ogni politica risiede in uno slot `/`. Le politiche built-in appartengono allo spazio dei nomi **`failproofai/`** — ad esempio, `failproofai/sanitize-jwt`. Lo spazio dei nomi previene collisioni quando carichi anche politiche personalizzate o di terze parti con nomi brevi simili. +Ogni politica si trova in uno slot `/`. Le politiche integrate appartengono al namespace **`failproofai/`** — ad esempio, `failproofai/sanitize-jwt`. Lo namespace previene collisioni quando carichi anche politiche personalizzate o di terze parti con nomi brevi simili. -Nella tua configurazione puoi fare riferimento a una politica built-in utilizzando sia il suo nome breve che il suo nome qualificato; entrambi i moduli si risolvono nella stessa politica: +Nella tua configurazione puoi fare riferimento a una politica integrata con il suo nome breve o con il nome qualificato; entrambe le forme si risolvono nella stessa politica: ```json { @@ -44,33 +44,33 @@ Nella tua configurazione puoi fare riferimento a una politica built-in utilizzan } ``` -Se un nome non contiene `/`, failproofai lo tratta come appartenente allo spazio dei nomi predefinito `failproofai`. I nomi che già contengono un `/` (ad es. `myorg/foo`, `custom/my-hook`) vengono mantenuti così come sono. -- **`require-`** — blocca l'evento Stop finché le condizioni non sono soddisfatte. +Se un nome non contiene `/`, failproofai lo tratta come appartenente al namespace predefinito `failproofai`. I nomi che contengono già `/` (ad es. `myorg/foo`, `custom/my-hook`) vengono mantenuti così come sono. +- **`require-`** — blocca l'evento Stop fino a quando le condizioni non sono soddisfatte. --- -Ogni politica supporta un campo `hint` opzionale in `policyParams`. L'hint viene aggiunto al messaggio deny o instruct che Claude vede, fornendo una guida concreta senza modificare il codice della politica. Funziona con politiche built-in, personalizzate e di convenzione. Vedi [Configurazione → hint](/it/configuration#hint-cross-cutting) per i dettagli. +Ogni politica supporta un campo `hint` facoltativo in `policyParams`. L'hint viene aggiunto al messaggio di negazione o istruzione che Claude vede, fornendo una guida pratica senza modificare il codice della politica. Funziona con politiche integrate, personalizzate e di convenzione. Vedi [Configurazione → hint](/it/configuration#hint-cross-cutting) per i dettagli. --- ## Comandi pericolosi -Previeni che gli agent eseguano operazioni difficili da annullare o che potrebbero danneggiare il sistema host. +Impedisci agli agent di eseguire operazioni difficili da annullare o che potrebbero danneggiare il sistema host. ### `block-sudo` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi comando `sudo`. +**Event:** PreToolUse (Bash) +**Default:** Nega qualsiasi comando `sudo`. -Blocca le invocazioni che includono la parola chiave `sudo`. La ricerca di modelli viene eseguita sui token di comando analizzati, non sulla stringa grezza, per prevenire bypass tramite iniezione di operatori shell. +Blocca gli invocazioni che includono la parola chiave `sudo`. L'abbinamento del pattern viene eseguito su token di comando analizzati, non sulla stringa grezza, per prevenire bypass tramite iniezione di operatori shell. **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefissi di comando esatti consentiti. Ogni voce viene confrontata con i token argv analizzati. | +| `allowPatterns` | `string[]` | `[]` | Prefissi di comando esatti che sono consentiti. Ogni voce viene abbinata ai token argv analizzati. | **Esempio:** @@ -87,21 +87,21 @@ Blocca le invocazioni che includono la parola chiave `sudo`. La ricerca di model Con questa configurazione, `sudo systemctl status nginx` è consentito, ma `sudo rm /etc/hosts` è negato. -I modelli vengono confrontati con token analizzati, non con la stringa di comando grezza. Questo previene bypass tramite operatori shell aggiunti (ad es. `sudo systemctl status x; rm -rf /` non corrisponde a `sudo systemctl status *`). +I pattern vengono abbinati ai token analizzati, non alla stringa di comando grezza. Ciò previene il bypass tramite operatori shell aggiunti (ad es. `sudo systemctl status x; rm -rf /` non corrisponde a `sudo systemctl status *`). --- ### `block-rm-rf` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega `rm -rf`, `rm -fr` e forme di eliminazione ricorsiva simili. +**Event:** PreToolUse (Bash) +**Default:** Nega `rm -rf`, `rm -fr` e altre forme di eliminazione ricorsiva simili. **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Percorsi sicuri per l'eliminazione ricorsiva (ad es. `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Percorsi che è sicuro eliminare ricorsivamente (ad es. `/tmp`). | **Esempio:** @@ -119,8 +119,8 @@ I modelli vengono confrontati con token analizzati, non con la stringa di comand ### `block-curl-pipe-sh` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega `curl | bash`, `curl | sh`, `wget | bash` e modelli simili. +**Event:** PreToolUse (Bash) +**Default:** Nega `curl | bash`, `curl | sh`, `wget | bash` e pattern simili. Nessun parametro. @@ -128,8 +128,8 @@ Nessun parametro. ### `block-failproofai-commands` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega i comandi che disinstallerebbero o disabiliterebbero failproofai stesso (ad es. `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Event:** PreToolUse (Bash) +**Default:** Nega i comandi che disinstallerebbero o disabiliterebbero failproofai stesso (ad es. `npm uninstall failproofai`, `failproofai policies --uninstall`). Nessun parametro. @@ -137,18 +137,18 @@ Nessun parametro. ## Comandi infra -Interrompi gli agent di codifica dall'esecuzione di CLI infrastrutturali o dall'attivazione di pipeline CI/CD. Tutte le politiche in questa categoria sono **opt-in** (`defaultEnabled: false`) — gli agent che legittimamente necessitano di chiamare `kubectl`, `terraform`, ecc. non saranno disturbati a meno che tu non abiliti la politica. Quando abilitata, ogni invocazione della CLI corrispondente è negata a meno che il comando non corrisponda a una voce in `allowPatterns`. +Impedisci agli agent di codifica di eseguire CLI di infrastruttura o attivare pipeline CI/CD. Tutte le politiche di questa categoria sono **opt-in** (`defaultEnabled: false`) — gli agent che hanno legittimamente bisogno di chiamare `kubectl`, `terraform`, ecc. non saranno disturbati a meno che non abiliti la politica. Quando abilitata, ogni invocazione della CLI abbinata viene negata a meno che il comando non corrisponda a una voce in `allowPatterns`. -La grammatica del modello è la stessa di [`block-sudo`](#block-sudo): i token vengono confrontati con argv analizzato, `*` è un wildcard per un token e qualsiasi comando contenente un operatore shell autonomo (`&&`, `||`, `|`, `;`) o un token con metacaratteri shell incorporati viene rifiutato prima della ricerca di allowlist per prevenire bypass di iniezione. +La grammatica del pattern è la stessa di [`block-sudo`](#block-sudo): i token vengono abbinati ai argv analizzati, `*` è un carattere jolly per un token, e qualsiasi comando contenente un operatore shell standalone (`&&`, `||`, `|`, `;`) o un token con metacaratteri shell incorporati viene rifiutato prima dell'abbinamento della lista di consentiti per prevenire bypass di iniezione. ### `block-kubectl` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione `kubectl`. +**Event:** PreToolUse (Bash) +**Default:** Nega qualsiasi invocazione di `kubectl`. **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| | `allowPatterns` | `string[]` | `[]` | Prefissi di comando kubectl consentiti. | @@ -170,12 +170,12 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-terraform` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione `terraform` o `tofu` (OpenTofu). +**Event:** PreToolUse (Bash) +**Default:** Nega qualsiasi invocazione di `terraform` o `tofu` (OpenTofu). **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| | `allowPatterns` | `string[]` | `[]` | Prefissi di comando terraform/tofu consentiti. | @@ -195,14 +195,14 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-aws-cli` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione della CLI `aws`. +**Event:** PreToolUse (Bash) +**Default:** Nega qualsiasi invocazione della CLI `aws`. **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefissi di comando CLI aws consentiti. | +| `allowPatterns` | `string[]` | `[]` | Prefissi di comando della CLI aws consentiti. | **Esempio:** @@ -220,12 +220,12 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-gcloud` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione della CLI `gcloud` (Google Cloud). +**Event:** PreToolUse (Bash) +**Default:** Nega qualsiasi invocazione della CLI `gcloud` (Google Cloud). **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| | `allowPatterns` | `string[]` | `[]` | Prefissi di comando gcloud consentiti. | @@ -245,14 +245,14 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-az-cli` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione della CLI `az` (Azure). +**Event:** PreToolUse (Bash) +**Default:** Nega qualsiasi invocazione della CLI `az` (Azure). **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefissi di comando CLI az consentiti. | +| `allowPatterns` | `string[]` | `[]` | Prefissi di comando della CLI az consentiti. | **Esempio:** @@ -270,12 +270,12 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-helm` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione `helm`. +**Event:** PreToolUse (Bash) +**Default:** Nega qualsiasi invocazione di `helm`. **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| | `allowPatterns` | `string[]` | `[]` | Prefissi di comando helm consentiti. | @@ -295,8 +295,8 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-gh-pipeline` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega i seguenti sottocoman `gh` che mutano lo stato o attivano pipeline: +**Event:** PreToolUse (Bash) +**Default:** Nega i seguenti sottocomandi della CLI `gh` che mutano lo stato o attivano pipeline: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -305,13 +305,13 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f - `gh cache delete` - `gh secret set`, `gh secret delete` -I sottocomandi `gh` di sola lettura come `gh pr view`, `gh pr list`, `gh run list`, `gh release view` e `gh api repos/.../...` **non** vengono corrisposti da questa politica — sono regolarmente necessari per i controlli di workflow (incluso il `require-ci-green-before-stop` di failproofai). +I sottocomandi di sola lettura di `gh` come `gh pr view`, `gh pr list`, `gh run list`, `gh release view` e `gh api repos/.../...` **non** vengono abbinati da questa politica — sono regolarmente necessari per i controlli del workflow (incluso il proprio `require-ci-green-before-stop` di failproofai). **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Invocazioni scritte specifiche da consentire nonostante sarebbero altrimenti negate. | +| `allowPatterns` | `string[]` | `[]` | Invocazioni specifiche con script consentite anche se sarebbero altrimenti negate. | **Esempio:** @@ -327,14 +327,14 @@ I sottocomandi `gh` di sola lettura come `gh pr view`, `gh pr list`, `gh run lis --- -## Secrets (sanitizer) +## Segreti (sanitizer) -Interrompi gli agent dal leaking di credenziali nel loro contesto o output. Le politiche sanitizer si attivano su eventi **PostToolUse**. Quando Claude esegue un comando Bash, legge un file o chiama qualsiasi strumento, queste politiche ispezionano l'output prima che venga restituito a Claude. Se viene rilevato un modello di secret, la politica restituisce una decisione deny che impedisce all'output di essere passato indietro. +Impedisci agli agent di far trapelare credenziali nel loro contesto o output. Le politiche sanitizer si attivano su eventi **PostToolUse**. Quando Claude esegue un comando Bash, legge un file o chiama qualsiasi strumento, queste politiche ispezionano l'output prima che venga restituito a Claude. Se viene rilevato un pattern di segreto, la politica restituisce una decisione di negazione che impedisce al output di essere passato indietro. ### `sanitize-jwt` -**Evento:** PostToolUse (tutti gli strumenti) -**Predefinito:** Nasconde i token JWT (tre segmenti base64url separati da `.`). +**Event:** PostToolUse (tutti gli strumenti) +**Default:** Oscura i token JWT (tre segmenti base64url separati da `.`). Nessun parametro. @@ -342,14 +342,14 @@ Nessun parametro. ### `sanitize-api-keys` -**Evento:** PostToolUse (tutti gli strumenti) -**Predefinito:** Nasconde i formati comuni di chiavi API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), chiavi di accesso AWS (`AKIA`), chiavi Stripe (`sk_live_`, `sk_test_`) e chiavi API Google (`AIza`). +**Event:** PostToolUse (tutti gli strumenti) +**Default:** Oscura i formati comuni di chiave API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT (`ghp_`), chiavi di accesso AWS (`AKIA`), chiavi Stripe (`sk_live_`, `sk_test_`) e chiavi API Google (`AIza`). **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Modelli regex aggiuntivi da trattare come secret. | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Pattern regex aggiuntivi da trattare come segreti. | **Esempio:** @@ -358,8 +358,8 @@ Nessun parametro. "policyParams": { "sanitize-api-keys": { "additionalPatterns": [ - { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" }, - { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" } + { "regex": "myco_[A-Za-z0-9]{32}", "label": "Chiave API interna MyCo" }, + { "regex": "pat_[0-9a-f]{40}", "label": "PAT interno" } ] } } @@ -370,8 +370,8 @@ Nessun parametro. ### `sanitize-connection-strings` -**Evento:** PostToolUse (tutti gli strumenti) -**Predefinito:** Nasconde le stringhe di connessione al database che contengono credenziali incorporate (ad es. `postgresql://user:password@host/db`). +**Event:** PostToolUse (tutti gli strumenti) +**Default:** Oscura le stringhe di connessione al database che contengono credenziali incorporate (ad es. `postgresql://user:password@host/db`). Nessun parametro. @@ -379,8 +379,8 @@ Nessun parametro. ### `sanitize-private-key-content` -**Evento:** PostToolUse (tutti gli strumenti) -**Predefinito:** Nasconde i blocchi PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, ecc.). +**Event:** PostToolUse (tutti gli strumenti) +**Default:** Oscura i blocchi PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, ecc.). Nessun parametro. @@ -388,8 +388,8 @@ Nessun parametro. ### `sanitize-bearer-tokens` -**Evento:** PostToolUse (tutti gli strumenti) -**Predefinito:** Nasconde le intestazioni `Authorization: Bearer ` dove il token è di 20 o più caratteri. +**Event:** PostToolUse (tutti gli strumenti) +**Default:** Oscura gli header `Authorization: Bearer ` dove il token contiene 20 o più caratteri. Nessun parametro. @@ -397,14 +397,14 @@ Nessun parametro. ## Ambiente -Proteggi la configurazione dell'ambiente sensibile dalla lettura o dall'esposizione da parte degli agent. +Proteggi la configurazione dell'ambiente sensibile dall'essere letta o esposta da agent. ### `block-env-files` -**Evento:** PreToolUse (Bash, Read) -**Predefinito:** Nega la lettura di file `.env` tramite `cat .env`, chiamate dello strumento Read con `.env` come percorso del file, ecc. +**Event:** PreToolUse (Bash, Read) +**Default:** Nega la lettura di file `.env` tramite `cat .env`, chiamate dello strumento Read con `.env` come percorso del file, ecc. -Non blocca `.envrc` o altri file adiacenti all'ambiente — solo i file denominati esattamente `.env`. +Non blocca `.envrc` o altri file adiacenti all'ambiente — solo file denominati esattamente `.env`. Nessun parametro. @@ -412,8 +412,8 @@ Nessun parametro. ### `protect-env-vars` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega i comandi che stampano variabili di ambiente: `printenv`, `env`, `echo $VAR`. +**Event:** PreToolUse (Bash) +**Default:** Nega i comandi che stampano variabili d'ambiente: `printenv`, `env`, `echo $VAR`. Nessun parametro. @@ -421,16 +421,16 @@ Nessun parametro. ## Accesso ai file -Mantieni gli agent che lavorano all'interno dei confini del progetto e lontani da file sensibili. +Mantieni gli agent dentro i confini del progetto e lontani dai file sensibili. ### `block-read-outside-cwd` -**Evento:** PreToolUse (Read, Bash) -**Predefinito:** Nega la lettura di file al di fuori della radice del progetto. Il confine è `CLAUDE_PROJECT_DIR` (impostato una volta per sessione da Claude Code), con un fallback alla directory di lavoro corrente della sessione quando quella variabile non è impostata. L'utilizzo della radice del progetto piuttosto che il `cwd` live significa che il confine rimane stabile anche dopo che Claude si sposta in una sottodirectory. +**Event:** PreToolUse (Read, Bash) +**Default:** Nega la lettura di file al di fuori della radice del progetto. Il confine è `CLAUDE_PROJECT_DIR` (impostato una volta per sessione da Claude Code), con fallback alla directory di lavoro corrente della sessione quando quella variabile non è impostata. Utilizzare la radice del progetto piuttosto che il `cwd` in tempo reale significa che il confine rimane stabile anche dopo che Claude fa `cd` in una subdirectory. **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| | `allowPaths` | `string[]` | `[]` | Prefissi di percorso assoluto consentiti anche se al di fuori della radice del progetto. | @@ -450,14 +450,14 @@ Mantieni gli agent che lavorano all'interno dei confini del progetto e lontani d ### `block-secrets-write` -**Evento:** PreToolUse (Write, Edit) -**Predefinito:** Nega le scritture su file comunemente utilizzati per chiavi private e certificati: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Event:** PreToolUse (Write, Edit) +**Default:** Nega le scritture su file comunemente utilizzati per chiavi private e certificati: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | Modelli di nome file aggiuntivi (stile glob) da bloccare. | +| `additionalPatterns` | `string[]` | `[]` | Pattern di nome file aggiuntivi (stile glob) da bloccare. | **Esempio:** @@ -475,18 +475,18 @@ Mantieni gli agent che lavorano all'interno dei confini del progetto e lontani d ## Git -Previeni i push accidentali, force-push e errori di branch difficili da annullare. +Previeni push accidentali, force-push e errori di branch difficili da annullare. ### `block-push-master` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega `git push origin main` e `git push origin master`. +**Event:** PreToolUse (Bash) +**Default:** Nega `git push origin main` e `git push origin master`. **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Nomi di branch che non possono essere push direttamente. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Nomi di branch che non possono essere pushati direttamente. | **Esempio:** @@ -501,19 +501,19 @@ Previeni i push accidentali, force-push e errori di branch difficili da annullar ``` -Per consentire il push su tutti i branch (disabilitando effettivamente questa politica senza rimuoverla da `enabledPolicies`), imposta `protectedBranches: []`. +Per consentire il push a tutti i branch (disabilitando effettivamente questa politica senza rimuoverla da `enabledPolicies`), imposta `protectedBranches: []`. --- ### `block-work-on-main` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega `git commit`, `git merge`, `git rebase` e `git cherry-pick` mentre l'albero di lavoro è su `main` o `master`. La creazione e il cambio di branch (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) non sono interessati. +**Event:** PreToolUse (Bash) +**Default:** Nega `git commit`, `git merge`, `git rebase` e `git cherry-pick` mentre l'albero di lavoro è su `main` o `master`. La creazione e il cambio di branch (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) non sono interessati. **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| | `protectedBranches` | `string[]` | `["main", "master"]` | Nomi di branch su cui commit/merge/rebase/cherry-pick è negato. | @@ -521,16 +521,16 @@ Per consentire il push su tutti i branch (disabilitando effettivamente questa po ### `block-force-push` -**Evento:** PreToolUse (Bash) -**Predefinito:** Nega `git push --force` e `git push -f`. +**Event:** PreToolUse (Bash) +**Default:** Nega `git push --force` e `git push -f`. -Nessun parametro specifico della politica. Usa il [`hint`](/it/configuration#hint-cross-cutting) trasversale per suggerire alternative: +Nessun parametro specifico della politica. Usa il [`hint`](/it/configuration#hint-cross-cutting) cross-cutting per suggerire alternative: ```json { "policyParams": { "block-force-push": { - "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b `) and push that instead." + "hint": "Crea un nuovo branch dal tuo HEAD attuale (ad es. `git checkout -b `) e fai il push di quello." } } } @@ -540,8 +540,8 @@ Nessun parametro specifico della politica. Usa il [`hint`](/it/configuration#hin ### `warn-git-amend` -**Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a procedere con cautela quando esegue `git commit --amend`. Non blocca il comando. +**Event:** PreToolUse (Bash) +**Default:** Istruisce Claude a procedere con cautela quando esegue `git commit --amend`. Non blocca il comando. Nessun parametro. @@ -549,8 +549,8 @@ Nessun parametro. ### `warn-git-stash-drop` -**Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a confermare prima di eseguire `git stash drop`. Non blocca il comando. +**Event:** PreToolUse (Bash) +**Default:** Istruisce Claude a confermare prima di eseguire `git stash drop`. Non blocca il comando. Nessun parametro. @@ -558,8 +558,8 @@ Nessun parametro. ### `warn-all-files-staged` -**Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a revisionare quello che sta mettendo in stage quando esegue `git add -A` o `git add .`. Non blocca il comando. +**Event:** PreToolUse (Bash) +**Default:** Istruisce Claude a rivedere cosa sta staged quando esegue `git add -A` o `git add .`. Non blocca il comando. Nessun parametro. @@ -567,12 +567,12 @@ Nessun parametro. ## Database -Cattura le operazioni SQL distruttive prima che vengano eseguite sul tuo database. +Cattura le operazioni SQL distruttive prima che vengono eseguite sul tuo database. ### `warn-destructive-sql` -**Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a confermare prima di eseguire SQL contenente `DROP TABLE`, `DROP DATABASE` o `DELETE` senza una clausola `WHERE`. +**Event:** PreToolUse (Bash) +**Default:** Istruisce Claude a confermare prima di eseguire SQL contenente `DROP TABLE`, `DROP DATABASE` o `DELETE` senza una clausola `WHERE`. Nessun parametro. @@ -580,8 +580,8 @@ Nessun parametro. ### `warn-schema-alteration` -**Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a confermare prima di eseguire istruzioni `ALTER TABLE`. +**Event:** PreToolUse (Bash) +**Default:** Istruisce Claude a confermare prima di eseguire istruzioni `ALTER TABLE`. Nessun parametro. @@ -589,18 +589,18 @@ Nessun parametro. ## Avvisi -Fornisci agli agent contesto aggiuntivo prima di operazioni potenzialmente rischiose ma non distruttive. +Fornisci agli agent un contesto extra prima di operazioni potenzialmente rischiose ma non distruttive. ### `warn-large-file-write` -**Evento:** PreToolUse (Write) -**Predefinito:** Istruisce Claude a confermare prima di scrivere file più grandi di 1024 KB. +**Event:** PreToolUse (Write) +**Default:** Istruisce Claude a confermare prima di scrivere file più grandi di 1024 KB. **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | Soglia di dimensione del file in kilobyte al di sopra della quale viene emesso un avviso. | +| `thresholdKb` | `number` | `1024` | Soglia di dimensione file in kilobyte al di sopra della quale viene emesso un avviso. | **Esempio:** @@ -615,15 +615,15 @@ Fornisci agli agent contesto aggiuntivo prima di operazioni potenzialmente risch ``` -Il gestore hook applica un limite stdin di 1 MB sui payload. Per testare questa politica con contenuto piccolo, imposta `thresholdKb` su un valore ben al di sotto di 1024. +Il gestore dell'hook applica un limite stdin di 1 MB sui payload. Per testare questa politica con contenuto piccolo, imposta `thresholdKb` a un valore ben al di sotto di 1024. --- ### `warn-package-publish` -**Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a confermare prima di eseguire `npm publish`. +**Event:** PreToolUse (Bash) +**Default:** Istruisce Claude a confermare prima di eseguire `npm publish`. Nessun parametro. @@ -631,8 +631,8 @@ Nessun parametro. ### `warn-background-process` -**Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a stare attento quando avvia processi in background tramite `nohup`, `&`, `disown` o `screen`. +**Event:** PreToolUse (Bash) +**Default:** Istruisce Claude a fare attenzione quando avvia processi in background tramite `nohup`, `&`, `disown` o `screen`. Nessun parametro. @@ -640,8 +640,8 @@ Nessun parametro. ### `warn-global-package-install` -**Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a confermare prima di eseguire `npm install -g`, `yarn global add` o `pip install` senza un ambiente virtuale. +**Event:** PreToolUse (Bash) +**Default:** Istruisce Claude a confermare prima di eseguire `npm install -g`, `yarn global add` o `pip install` senza un ambiente virtuale. Nessun parametro. @@ -649,21 +649,21 @@ Nessun parametro. ## Gestori di pacchetti -Applica quali gestori di pacchetti l'agent è autorizzato a utilizzare. +Applica quale gestore di pacchetti l'agent è autorizzato a utilizzare. ### `prefer-package-manager` -**Evento:** PreToolUse (Bash) -**Predefinito:** Disabilitato. Quando abilitato, blocca qualsiasi comando del gestore di pacchetti non nell'elenco `allowed` e dice a Claude di riscrivere il comando utilizzando un gestore consentito. +**Event:** PreToolUse (Bash) +**Default:** Disabilitato. Quando abilitato, blocca qualsiasi comando del gestore di pacchetti non nell'elenco `allowed` e dice a Claude di riscrivere il comando usando un gestore autorizzato. Rileva: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | Nomi dei gestori di pacchetti consentiti. Qualsiasi gestore rilevato non in questo elenco viene bloccato. Quando vuoto, la politica è un no-op. | -| `blocked` | string[] | `[]` | Nomi di gestori aggiuntivi da bloccare al di là dell'elenco integrato (ad es. `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | Nomi dei gestori di pacchetti autorizzati. Qualsiasi gestore rilevato non in questo elenco è bloccato. Quando vuoto, la politica è una no-op. | +| `blocked` | string[] | `[]` | Nomi di gestori aggiuntivi da bloccare oltre l'elenco integrato (ad es. `['pdm', 'pipx']`). | -L'elenco dei blocchi integrato copre: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Usa `blocked` per aggiungere gestori non in questo elenco. +L'elenco di blocco integrato copre: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Usa `blocked` per aggiungere gestori non in questo elenco. **Configurazione di esempio:** @@ -679,18 +679,18 @@ L'elenco dei blocchi integrato copre: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun } ``` -Con questa configurazione, sia `pip install flask` che `pdm install flask` sono negati con un messaggio che dice a Claude di usare `uv` o `bun` invece. Comandi come `uv pip install flask` sono consentiti perché `uv` è nell'allowlist e viene verificato per primo. +Con questa configurazione, `pip install flask` e `pdm install flask` sono entrambi negati con un messaggio che dice a Claude di usare `uv` o `bun` invece. I comandi come `uv pip install flask` sono consentiti perché `uv` è nell'elenco di consentiti e viene controllato per primo. --- -## Comportamento dell'IA +## Comportamento AI Rileva quando gli agent rimangono bloccati o si comportano inaspettatamente. ### `warn-repeated-tool-calls` -**Evento:** PreToolUse (tutti gli strumenti) -**Predefinito:** Istruisce Claude a riconsiderare quando lo stesso strumento viene chiamato 3+ volte con parametri identici — un segno comune che l'agent è bloccato in un loop. +**Event:** PreToolUse (tutti gli strumenti) +**Default:** Istruisce Claude a riconsiderare quando lo stesso strumento viene chiamato 3+ volte con parametri identici — un segno comune che l'agent è bloccato in un loop. Nessun parametro. @@ -698,40 +698,40 @@ Nessun parametro. ## Workflow -Applica un workflow disciplinato di fine sessione. Queste politiche si attivano sull'evento **Stop** e negano all'agent di fermarsi finché ogni condizione non è soddisfatta. Seguono una catena di dipendenze naturale: commit → push → PR → CI. Se una politica nega, le politiche successive nella catena vengono saltate (deny short-circuits). +Applica un workflow di fine sessione disciplinato. Queste politiche si attivano sull'evento **Stop** e negano all'agent di fermarsi fino a quando ogni condizione non è soddisfatta. Seguono una catena di dipendenza naturale: commit → push → PR → CI. Se una politica nega, le politiche successive nella catena vengono saltate (negare shortcircuit). Tutte le politiche di workflow sono **fail-open**: se lo strumento richiesto non è disponibile (ad es. `gh` non installato, nessun remote git), la politica consente con un messaggio informativo che spiega perché il controllo è stato saltato. -### Semantica Stop per CLI +### Semantica di Stop per CLI -L'applicazione Stop sembra leggermente diversa tra i sette CLI supportati perché ognuno espone un contratto hook di fine agent diverso. Il **risultato** è lo stesso — l'agent non se la cava fermandosi mentre un gate di workflow sta fallendo — ma la **meccanica** differisce. La tabella seguente riassume; solo Pi ha una stranezza visibile all'utente che vale la pena capire prima di abilitare una politica `require-*-before-stop`. +L'applicazione di Stop varia leggermente tra i sette CLI supportati perché ognuno espone un contratto di hook diverso per il completamento dell'agent. Il **risultato** è lo stesso — l'agent non riuscirà a fermarsi mentre un gate di workflow sta fallendo — ma la **meccanica** differisce. La tabella sottostante riassume; solo Pi ha una peculiarità visibile all'utente che vale la pena comprendere prima di abilitare una politica `require-*-before-stop`. -| CLI | Quando il gate si attiva | Cosa vedi | +| CLI | Quando si attiva il gate | Cosa vedi | |---|---|---| -| Claude Code | Stesso loop dell'agent, immediatamente | Claude continua a lavorare — risolve il problema, quindi tenta di finire di nuovo. Nessuna interruzione visibile per te. | -| Codex | Stesso loop dell'agent, immediatamente | Uguale a Claude. | -| GitHub Copilot CLI | Stesso loop dell'agent, immediatamente | Uguale a Claude (usa il canale di riprovazione `{decision:"block", reason}` di Copilot — verificato empiricamente su Copilot CLI 1.0.41). | -| Cursor Agent | Stesso loop dell'agent, immediatamente | Uguale a Claude (usa il canale `{followup_message}` di Cursor — limitato a `loop_limit`, default 5 riprovazioni). | -| Gemini CLI | Stesso loop dell'agent, immediatamente | Uguale a Claude (usa il canale `{decision:"block", reason}` di Gemini su `AfterAgent`). | -| OpenCode | Stesso loop dell'agent, immediatamente | Uguale a Claude (usa la chiamata SDK `client.session.prompt(...)` di OpenCode instradata attraverso `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **Turno utente successivo** | **Pi si ferma visibilmente** quando il gate si attiva — il suo loop dell'agent esce e sei restituito al prompt. Il gate si attiva quindi la prossima volta che invii un prompt: failproofai antepone una direttiva `MANDATORY ACTION REQUIRED` al prompt di sistema di quel turno, istruendo l'LLM a completare il passo di workflow (commit, push, ecc.) prima di fare quello che hai chiesto. | +| Claude Code | Stesso loop dell'agent, immediatamente | Claude continua a lavorare — corregge il problema, quindi tenta di terminare di nuovo. Nessuna interruzione visibile. | +| Codex | Stesso loop dell'agent, immediatamente | Come Claude. | +| GitHub Copilot CLI | Stesso loop dell'agent, immediatamente | Come Claude (usa il canale di retry `{decision:"block", reason}` di Copilot — verificato empiricamente contro Copilot CLI 1.0.41). | +| Cursor Agent | Stesso loop dell'agent, immediatamente | Come Claude (usa il canale `{followup_message}` di Cursor — limitato a `loop_limit`, default 5 retry). | +| Gemini CLI | Stesso loop dell'agent, immediatamente | Come Claude (usa il canale `{decision:"block", reason}` di Gemini su `AfterAgent`). | +| OpenCode | Stesso loop dell'agent, immediatamente | Come Claude (usa la chiamata SDK `client.session.prompt(...)` di OpenCode instradato tramite `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **Turno utente successivo** | **Pi si ferma visibilmente** quando il gate si attiva — il suo loop di agent esce e sei riportato al prompt. Il gate si attiva quindi la prossima volta che invii un prompt: failproofai prepone una direttiva `MANDATORY ACTION REQUIRED` al prompt di sistema di quel turno, istruendo il LLM a completare il passo del workflow (commit, push, ecc.) prima di fare tutto quello che hai chiesto. | -**Limitazione di Pi.** L'evento `AgentEndEvent` di Pi (l'equivalente upstream dell'hook `Stop` di Claude) non ha un tipo Result — nel momento in cui si attiva, il loop dell'agent di Pi è già uscito. Pi non può essere forzato a riprovare lo stesso loop come Claude / Copilot / Cursor / Gemini / OpenCode possono. failproofai sposta il gate all'evento `before_agent_start` di Pi (che si attiva dopo il prossimo prompt utente) in modo che il controllo del workflow si applichi ancora, solo al turno successivo anziché a quello corrente. +**Limitazione di Pi.** L'evento `AgentEndEvent` di Pi (l'equivalente upstream dell'hook `Stop` di Claude) non ha un tipo Result — nel momento in cui si attiva, il loop di agent di Pi è già uscito. Pi non può essere forzato a riprovare lo stesso loop nel modo in cui Claude / Copilot / Cursor / Gemini / OpenCode possono. failproofai sposta il gate all'evento `before_agent_start` di Pi (che si attiva dopo il prossimo prompt dell'utente) in modo che il controllo del workflow ancora si applichi, solo al turno successivo piuttosto che al turno corrente. -**Cosa significa in pratica:** +**Cosa significa nella pratica:** -- Dopo che Pi si ferma, il motivo di negazione viene catturato in memoria con chiave id sessione Pi. Il prossimo prompt che invii nello stesso processo Pi lo scarica: l'LLM vede la direttiva `MANDATORY ACTION REQUIRED` in cima al suo prompt di sistema, esegue il commit (o push / apre il PR / attende CI), e solo allora continua con la tua richiesta. Il motivo di negazione catturato è una tantum — una volta scaricato, il gate è libero. -- Il gate è limitato dalla durata del processo Pi. Se fai `Ctrl+C` Pi o esci tra i turni, la voce in memoria viene eliminata insieme al processo e il gate viene saltato. Claude, Copilot, Cursor, Gemini e OpenCode hanno lo stesso limite (uccidi l'agent e il gate viene saltato) — Pi lo rende solo più visibile perché l'agent esce visibilmente prima che il gate si attivi. -- Un deny in sospeso viene anche cancellato su `session_shutdown` per qualsiasi motivo (`new` / `resume` / `fork` / `quit`), quindi un gate stantio da una sessione precedente non può trapelare in una sessione nuova avviata nello stesso processo Pi. +- Dopo che Pi si ferma, il motivo della negazione viene catturato in memoria keyed dall'ID sessione di Pi. Il prossimo prompt che invii nello stesso processo Pi lo scarica: l'LLM vede la direttiva `MANDATORY ACTION REQUIRED` in cima al suo prompt di sistema, fa il commit (o push / apre il PR / aspetta CI), e solo allora continua con la tua richiesta. Il motivo della negazione catturato è monouso — una volta scaricato, il gate è pulito. +- Il gate è limitato dalla durata del processo di Pi. Se fai `Ctrl+C` su Pi o esci tra i turni, la voce in memoria viene eliminata insieme al processo e il gate viene mancato. Claude, Copilot, Cursor, Gemini e OpenCode hanno lo stesso limite (uccidi l'agent e il gate viene mancato) — Pi lo rende solo più visibile perché l'agent si ferma visibilmente prima che il gate si attivi. +- Una negazione in sospeso viene anche cancellata su `session_shutdown` per qualsiasi motivo (`new` / `resume` / `fork` / `quit`), quindi un gate stantio da una sessione precedente non può fuoriuscire in una sessione fresca avviata nello stesso processo Pi. -Se hai bisogno di una riprovazione dello stesso loop in stile Claude, esegui le tue politiche `Stop` in uno qualsiasi degli altri sei CLI supportati. Stiamo tracciando Pi upstream per un futuro tipo Result su `AgentEndEvent` che ci permetterebbe di chiudere questa lacuna. +Se hai bisogno del retry dello stesso loop nello stile di Claude, esegui le tue politiche di `Stop` sotto uno dei sei altri CLI supportati. Stiamo monitorando Pi upstream per un tipo Result futuro su `AgentEndEvent` che ci permetterebbe di chiudere questo gap. ### `require-commit-before-stop` -**Evento:** Stop -**Predefinito:** Nega l'arresto quando ci sono modifiche non committate (file modificati, staged o non tracciati). Restituisce un messaggio informativo quando la directory di lavoro è pulita. +**Event:** Stop +**Default:** Nega il stop quando ci sono modifiche non committate (file modificati, staged o untracked). Restituisce un messaggio informativo quando la directory di lavoro è pulita. Nessun parametro. @@ -739,14 +739,14 @@ Nessun parametro. ### `require-push-before-stop` -**Evento:** Stop -**Predefinito:** Nega l'arresto quando ci sono commit non push o quando il branch corrente non ha un branch remoto di tracciamento. Suggerisce `git push -u` per creare un branch di tracciamento se necessario. Fallisce open se nessun remote è configurato. +**Event:** Stop +**Default:** Nega il stop quando ci sono commit non pushati o quando il branch corrente non ha un branch di tracking remoto. Suggerisce `git push -u` per creare un branch di tracking se necessario. Si apre se nessun remote è configurato. **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | Nome remoto su cui fare il push. | +| `remote` | `string` | `"origin"` | Nome del remote a cui fare push. | **Esempio:** @@ -764,39 +764,39 @@ Nessun parametro. ### `require-pr-before-stop` -**Evento:** Stop -**Predefinito:** Nega l'arresto quando nessuna pull request esiste per il branch corrente, o quando il PR esistente è chiuso senza essere fuso. Istruisce Claude a creare un PR con `gh pr create`. Quando il PR è **fuso**, la politica consente (il lavoro è stato spedito) e il messaggio suggerisce di uscire dal branch (`git checkout main && git pull`). +**Event:** Stop +**Default:** Nega il stop quando non esiste una pull request per il branch corrente, o quando la PR esistente è chiusa senza essere mergiata. Istruisce Claude a creare una PR con `gh pr create`. Quando la PR è **mergiata**, la politica consente (il lavoro è stato spedito) e il messaggio suggerisce di passare dal branch (`git checkout main && git pull`). Nessun parametro. -Questa politica richiede che [GitHub CLI](https://cli.github.com/) (`gh`) sia installato e autenticato. +Questa politica richiede che la [GitHub CLI](https://cli.github.com/) (`gh`) sia installata e autenticata. Esegui `gh auth login` con un token di accesso personale che ha scope `repo` per l'accesso in lettura alle -pull request. Se `gh` non è installato o non autenticato, la politica fallisce open e segnala il motivo a Claude. +pull request. Se `gh` non è installato o non autenticato, la politica si apre e riporta il motivo a Claude. --- ### `require-no-conflicts-before-stop` -**Evento:** Stop -**Predefinito:** Nega l'arresto quando il branch corrente non può fondersi pulitamente nel branch base. La politica prima conferma che esiste un PR `OPEN` su GitHub per il branch — senza uno, non c'è un target di fusione da applicare, quindi l'intera politica short-circuits per consentire. Una volta confermato un PR `OPEN`, due sonde indipendenti vengono eseguite: +**Event:** Stop +**Default:** Nega il stop quando il branch corrente non può essere cleanly mergiato nel branch base. La politica prima conferma che esiste una PR `OPEN` su GitHub per il branch — senza una, non c'è target di merge da applicare, quindi l'intera politica shortcircuit per consentire. Una volta confermata una PR `OPEN`, due probe indipendenti vengono eseguite: -1. **Locale** — `git merge-tree --write-tree --name-only origin/ HEAD`. Su conflitto, il messaggio deny nomina i file in conflitto in modo che Claude sappia esattamente cosa risolvere. -2. **GitHub** — riutilizza il risultato di `gh pr view --json mergeable,state` già recuperato nel precontrollo. Cattura conflitti che un `origin/` locale stantio perderebbe (ad es. qualcuno ha sbarcato un PR conflittuale su `main` da quando è stato fatto l'ultimo fetch). Un risultato `CONFLICTING` nega. Un risultato `UNKNOWN` nega anche e istruisce Claude ad aspettare ~10 secondi e ri-controllare prima di tentare di fermarsi di nuovo — questo previene falsi negativi mentre GitHub ricalcola. +1. **Locale** — `git merge-tree --write-tree --name-only origin/ HEAD`. Su conflitto, il messaggio di negazione nomina i file in conflitto in modo che Claude sappia esattamente cosa risolvere. +2. **GitHub** — riusa il risultato `gh pr view --json mergeable,state` già recuperato nel precheck. Cattura i conflitti che un `origin/` locale stantio perderebbe (ad es. qualcuno ha atterrato una PR in conflitto su `main` dall'ultimo fetch). Un risultato `CONFLICTING` nega. Un risultato `UNKNOWN` nega anche e istruisce Claude ad aspettare ~10 secondi e ri-controllare prima di tentare di fermarsi di nuovo — questo previene falsi negativi mentre GitHub ricalcola. -Salta interamente (consente) quando: `gh` non è installato, nessun PR esiste per il branch, lo stato del PR non è `OPEN` (ad es. `MERGED`, `CLOSED`), o `gh pr view` restituisce output non parsabile. Fallisce anche open quando `origin/` manca localmente o quando nessun commit è in anticipo di base — quei fall-through del Layer 1 consultano comunque la mergeability PR in cache prima di consentire. +Si salta interamente (consente) quando: `gh` non è installato, non esiste PR per il branch, lo stato della PR non è `OPEN` (ad es. `MERGED`, `CLOSED`), o `gh pr view` restituisce output non parseable. Si apre anche quando `origin/` manca localmente o quando non ci sono commit davanti a base — quei fallthrough del Layer 1 consultano ancora il mergeability della PR cachato prima di consentire. **Parametri:** -| Parametro | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Default | Descrizione | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Branch base da controllare per conflitti. | +| `baseBranch` | `string` | `"main"` | Branch base contro cui controllare i conflitti. | -GitHub CLI (`gh`) è richiesto per questa politica. La politica usa `gh pr view` per confermare -che esiste un PR `OPEN` prima di eseguire qualsiasi sonda di conflitto — senza `gh`, la politica -short-circuits per consentire. Esegui `gh auth login` con un token di accesso personale che ha +GitHub CLI (`gh`) è richiesta per questa politica. La politica usa `gh pr view` per confermare +che una PR `OPEN` esiste prima di eseguire qualsiasi probe di conflitto — senza `gh`, la politica +shortcircuit per consentire. Esegui `gh auth login` con un token di accesso personale che ha scope `repo` per l'accesso in lettura alle pull request. @@ -804,24 +804,24 @@ scope `repo` per l'accesso in lettura alle pull request. ### `require-ci-green-before-stop` -**Evento:** Stop -**Predefinito:** Nega l'arresto quando i controlli CI stanno fallendo o ancora in esecuzione sul branch corrente. Controlla sia le esecuzioni del workflow GitHub Actions che i controlli bot di terze parti (ad es. CodeRabbit, SonarCloud, Codecov). Tratta `skipped`, `cancelled` e `neutral` come non-fallenti (quest'ultimo copre ad es. avvisi di Socket Security su PR di contributori esterni, dove l'app intenzionalmente segnala neutral invece di success/failure). Restituisce un messaggio informativo quando tutti i controlli passano. +**Event:** Stop +**Default:** Nega il stop quando i controlli CI stanno fallendo o sono ancora in corso sul branch corrente. Controlla sia i workflow di GitHub Actions che i controlli di bot di terze parti (ad es. CodeRabbit, SonarCloud, Codecov). Tratta `skipped`, `cancelled` e `neutral` conclusioni come non-fallenti (quest'ultimo copre ad es. avvisi Socket Security su PR di collaboratori esterni, dove l'app intenzionalmente riporta neutral anziché success/failure). Restituisce un messaggio informativo quando tutti i controlli passano. Nessun parametro. -Questa politica richiede che [GitHub CLI](https://cli.github.com/) (`gh`) sia installato e autenticato. -Esegui `gh auth login` con un token di accesso personale che ha scope `repo` per l'accesso in lettura alle -esecuzioni del workflow Actions e all'API Checks. Se `gh` non è installato o non autenticato, la politica fallisce open e segnala il motivo a Claude. +Questa politica richiede che la [GitHub CLI](https://cli.github.com/) (`gh`) sia installata e autenticata. +Esegui `gh auth login` con un token di accesso personale che ha scope `repo` per l'accesso in lettura a +workflow run di Actions e all'API Checks. Se `gh` non è installato o non autenticato, la politica si apre e riporta il motivo a Claude. --- --- -## Disabilitare singole politiche +## Disabilitare politiche individuali -Rimuovi una politica specifica da `enabledPolicies` nella tua configurazione, o disabilitala nel tab Policies del dashboard. +Rimuovi una politica specifica da `enabledPolicies` nella tua configurazione, o disabilitala nella tab Politiche della dashboard. ```json { diff --git a/docs/it/cli/audit.mdx b/docs/it/cli/audit.mdx index 52e365ff..7e463043 100644 --- a/docs/it/cli/audit.mdx +++ b/docs/it/cli/audit.mdx @@ -1,19 +1,19 @@ --- -title: Audit delle sessioni passate (beta) -description: "Conta quante volte l'agente ha fatto cose inutili o rischiose nelle trascrizioni precedenti" +title: Controllare sessioni passate (beta) +description: "Conta quante volte l'agente ha fatto cose inefficienti o rischiose nei transcript passati" --- - **Funzionalità Beta.** L'audit è in versione beta mentre raccogliamo i feedback iniziali. - Il catalogo dei rilevatori e il formato del report potrebbero cambiare prima del prossimo rilascio stabile. - Per favore apri una segnalazione se qualcosa sembra non giusto. + **Funzione beta.** L'audit è fornito in beta mentre raccogliamo i primi feedback. + Il catalogo dei rilevatori e il formato del report potrebbero cambiare prima della prossima versione stabile. + Apri un issue se qualcosa non ti sembra giusto. -L'audit riproduce le tue trascrizioni passate dell'agent-CLI attraverso il motore delle policy di failproofai e genera un report visivo e condivisibile nella **pagina dashboard `/audit`** — l'archetipo del tuo agente, un punteggio 0–100, e esattamente quali policy avrebbero bloccato cosa. +L'audit riesegue i tuoi transcript passati da agent-CLI attraverso il motore di policy di failproofai e genera un report visivo e condivisibile sulla **pagina dashboard `/audit`** — l'archetipo dell'agente, un punteggio 0–100, e esattamente quali policy avrebbero catturato cosa. ## Eseguirlo -Tre modi di accesso — portano tutti allo stesso report `/audit`. +Tre modi per iniziare — tutti portano allo stesso report `/audit`. @@ -34,60 +34,60 @@ failproofai `npx -y failproofai audit` scarica failproofai, esegue la scansione e apre il - dashboard per te — nulla da installare in precedenza. + dashboard per te — niente da installare prima. - `failproofai audit` esegue la scansione nel tuo terminale, quindi apre - automaticamente `localhost:8020/audit` quando termina. + `failproofai audit` esegue la scansione nel tuo terminale, poi apre automaticamente + `localhost:8020/audit` quando termina. - Esegui `failproofai` e fai clic su **Audit** nella barra di navigazione (tra Policies e + Esegui `failproofai` e clicca **Audit** nella navbar (tra Policies e Projects), oppure apri `/audit` direttamente. - Esegui `failproofai audit -h` (o `--help`) per vedere l'utilizzo. L'audit viene eseguito **completamente - offline** — non è richiesto nessun account o connessione di rete — e il dashboard continua a essere fornito - fino a quando non lo interrompi con `Ctrl+C`. + Esegui `failproofai audit -h` (o `--help`) per vedere l'utilizzo. L'audit funziona **completamente + offline** — nessun account o connessione di rete richiesti — e il dashboard continua a servire + finché non lo arresti con `Ctrl+C`. -Il dashboard scansiona le trascrizioni passate dell'agent CLI su questa macchina (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) e segnala quante volte l'agente ha fatto cose che failproofai è costruito per bloccare — controlli di variabili d'ambiente, push forzati, prefissi `cd ` ridondanti, loop di polling con sleep, ricezione di file appena modificati, e altro. +Il dashboard scansiona i transcript passati da agent CLI su questa macchina (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) e segnala con che frequenza l'agente ha fatto cose che failproofai è costruito per bloccare — controlli di variabili d'ambiente, push forzati, prefissi `cd ` ridondanti, loop di polling con sleep, ri-letture di file appena modificati, e altro. -Per ogni trascrizione, ogni evento di tool-use viene riprodotto attraverso le 39 policy integrate **e** attraverso 8 rilevatori solo audit che catturano pattern non ancora coperti dalle policy di runtime. I conteggi vengono aggregati per policy / rilevatore in tutte le sessioni. +Per ogni transcript, ogni evento tool-use viene rieseguito attraverso le 39 policy integrate **e** attraverso 8 rilevatori solo audit che catturano pattern non ancora coperti da policy runtime. I conteggi vengono aggregati per policy / rilevatore in tutte le sessioni. -## Cosa otterrai +## Cosa ottieni -La pagina `/audit` è un **poster** a schermo singolo e condivisibile seguito da quattro sezioni sotto la piega: +La pagina `/audit` è un **poster** a schermo intero e condivisibile seguito da quattro sezioni sotto il fold: -1. **Poster** — l'identità del tuo agente a colpo d'occhio: il suo **archetipo** (uno di 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), le sue parole chiave di persona, quanto sia raro quell'archetipo, e un **punteggio 0–100** con una banda di livello (`S` fino a `bottom tier`). Costruito per condividere — pubblica su X o LinkedIn, oppure scaricalo come PNG. -2. **`// strengths`** — cosa il tuo agente già fa bene, come numeri reali dalla scansione (es. clean-tool-call %, `0` tentativi di push-to-main), mostrato solo dove la policy rilevante ha un record pulito. -3. **`// quirks`** — cosa è scivolato: una tabella classificata di comportamenti che failproofai avrebbe bloccato — *quando* è successo l'ultima volta, *cosa è scivolato* (e la policy integrate che l'avrebbe bloccato), la sua *gravità*, e quante volte è stato *osservato* (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — la lista di correzioni prescritte: una riga per policy con `failproofai policy add ` pronto da copiare e incollare, più un pulsante **installa tutto** che abilita ogni raccomandazione contemporaneamente e mostra il tuo **punteggio proiettato** se lo farai. -5. **`// come back better`** — sviluppa l'abitudine: imposta un **promemoria** di re-audit email (`3d` / `7d` / `14d` / `30d`) o esegui nuovamente l'audit ora, e **invita un amico** a eseguire il proprio audit (inviato da failproof.ai, Cc'd a te). I promemoria e gli inviti richiedono l'accesso — vedi [`failproofai auth`](/it/cli/auth). +1. **Poster** — l'identità del tuo agente a colpo d'occhio: il suo **archetipo** (uno tra 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), le sue parole chiave di persona, quanto raro è quell'archetipo, e un **punteggio 0–100** con una fascia di livello (`S` fino a `bottom tier`). Costruito per condividere — pubblica su X o LinkedIn, o scaricalo come PNG. +2. **`// strengths`** — cosa fa già bene il tuo agente, come numeri reali dalla scansione (es. clean-tool-call %, `0` tentativi push-to-main), mostrato solo dove la policy rilevante ha un record pulito. +3. **`// quirks`** — cosa è sfuggito: una tabella ordinata di comportamenti che failproofai avrebbe catturato — *quando* è successo per ultimo, *cosa è sfuggito* (e il builtin che l'avrebbe bloccato), la sua *severity*, e quante volte è stato *visto* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — la lista di correzioni prescritte: una riga per policy con un `failproofai policy add ` pronto da copiare-incollare, più un pulsante **install all** che abilita tutti i consigli contemporaneamente e mostra il tuo **punteggio previsto** se lo facessi. +5. **`// come back better`** — costruisci l'abitudine: imposta un **reminder** email di re-audit (`3d` / `7d` / `14d` / `30d`) o re-audit ora, e **invita un amico** a eseguire il loro audit (inviato da failproof.ai, Cc a te). I reminder e gli inviti richiedono login — vedi [`failproofai auth`](/it/cli/auth). ## Rilevatori solo audit -Questi rilevano pattern di "comportamento stupido" non (ancora) applicati in tempo reale. Vengono eseguiti solo durante l'audit e non bloccano mai una chiamata di tool live. +Questi rilevano pattern di "comportamento stupido" non (ancora) forzati in tempo reale. Funzionano solo durante l'audit e non bloccano mai una chiamata tool in diretta. | Rilevatore | Cosa conta | |---|---| -| `redundant-cd-cwd` | Comandi Bash che iniziano con `cd && …` anche se i comandi vengono già eseguiti in `cwd`. | +| `redundant-cd-cwd` | Comandi Bash che iniziano con `cd && …` anche se i comandi già funzionano in `cwd`. | | `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` su un singolo file sorgente — usa lo strumento `Read`. | -| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` modifiche in-place — usa lo strumento `Edit`. | -| `prefer-write-over-heredoc` | Heredoc / `echo > file` multi-line per scrivere file — usa lo strumento `Write`. | -| `sleep-polling-loop` | `sleep N` lungo (≥ 30s) o loop di polling `while …; sleep …; done`. | -| `find-from-root` | `find /`, `find /home`, `find /usr`, ecc. — limita l'ambito a `cwd`. | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, ignorando gli hook. | -| `reread-after-edit` | `Read` di un file che era appena stato `Edit`/`Write` nella stessa sessione. | +| `prefer-edit-over-sed-awk` | In-place edits `sed -i` / `awk … > file` — usa lo strumento `Edit`. | +| `prefer-write-over-heredoc` | Heredoc / `echo > file` multi-riga che scrivono file — usa lo strumento `Write`. | +| `sleep-polling-loop` | Long `sleep N` (≥ 30s) o loop di polling `while …; sleep …; done`. | +| `find-from-root` | `find /`, `find /home`, `find /usr`, ecc. — limita a `cwd` invece. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, saltando gli hook. | +| `reread-after-edit` | `Read` di un file che è stato appena `Edit`/`Write` nella stessa sessione. | ## Cache -- **Cache per trascrizione** su `~/.failproofai/cache/audit/.json` con chiave `(mtime, size, engineVersion, detectorVersion)` — si invalida automaticamente quando la trascrizione o il codice della policy/rilevatore cambia. Ogni voce memorizza anche un timestamp `cachedAt` come **metadati TTL** (non parte della chiave di cache); le voci più vecchie di **7 giorni** vengono rifiutate in lettura così i risultati di lunga durata non sopravvivono all'evoluzione dell'intento del rilevatore. -- **Cache del risultato intero** su `~/.failproofai/audit-dashboard.json` (modalità 0600). Consente al dashboard di eseguire il rendering istantaneamente durante la navigazione senza rieseguire. Anche rifiutato in lettura dopo il **TTL di 7 giorni** — `/audit` cade quindi nel suo stato vuoto e richiede una corsa fresca. Fai clic su `[ re-audit now ]` vicino al fondo del report per aggiornare — re-audit invia `noCache: true`, quindi bypassa la cache per trascrizione e ripete la scansione di ogni trascrizione invece di restituire il risultato memorizzato nella cache; la corsa trasmette il progresso tramite una striscia in alto appiccicosa e scambia il risultato al suo posto al successo (nessun ricaricamento della pagina; un re-audit fallito mantiene il report precedente). +- **Cache per-transcript** in `~/.failproofai/cache/audit/.json` indicizzata da `(mtime, size, engineVersion, detectorVersion)` — invalida automaticamente quando il transcript o il codice della policy/rilevatore cambia. Ogni voce memorizza anche un timestamp `cachedAt` come **metadati TTL** (non parte della chiave cache); le voci più vecchie di **7 giorni** vengono rifiutate alla lettura così i risultati di lunga durata non sopravvivono all'intento rilevatore in evoluzione. +- **Cache di risultato intero** in `~/.failproofai/audit-dashboard.json` (modalità 0600). Permette al dashboard di renderizzarsi istantaneamente sulla navigazione senza rieseguire. Anche rifiutato alla lettura passato il **TTL di 7 giorni** — `/audit` cade quindi nel suo stato vuoto e richiede un'esecuzione fresca. Clicca `[ re-audit now ]` vicino al fondo del report per aggiornare — re-audit invia `noCache: true`, quindi bypassa la cache per-transcript e riscansiona ogni transcript invece di restituire il risultato cache; l'esecuzione trasmette il progresso via una striscia appiccicosa in alto e scambia il risultato in posizione al successo (nessun reload della pagina; un re-audit fallito mantiene il report precedente). ## Note -- **Nessuna mutazione.** L'audit viene riprodotto in modalità sola lettura. `warn-repeated-tool-calls` viene ignorato perché il suo sidecar per sessione verrebbe altrimenti modificato. -- **Policy del flusso di lavoro saltate.** Le policy `require-*-before-stop` si attivano solo su eventi `Stop` e `execSync` rispetto allo stato git live — non hanno un'interpretazione significativa di "cosa sarebbe successo nel 2025", quindi non compaiono nei conteggi dell'audit. -- **Policy personalizzate saltate.** Gli hook personalizzati forniti dall'utente non vengono riprodotti (potrebbero essere cambiati dalla sessione originale). \ No newline at end of file +- **Nessuna mutazione.** L'audit riesegue in modalità sola lettura. `warn-repeated-tool-calls` viene saltato perché il suo sidecar per-sessione verrebbe altrimenti modificato. +- **Policy di workflow saltate.** Le policy `require-*-before-stop` si attivano solo su eventi `Stop` e `execSync` contro lo stato git in diretta — non hanno un'interpretazione significativa "cosa sarebbe successo nel 2025", quindi non compaiono nei conteggi audit. +- **Policy personalizzate saltate.** Gli hook personalizzati forniti dall'utente non vengono rieseguiti (potrebbero essere cambiati dalla sessione originale). \ No newline at end of file diff --git a/docs/it/cli/auth.mdx b/docs/it/cli/auth.mdx index 2cd172d5..52857b3d 100644 --- a/docs/it/cli/auth.mdx +++ b/docs/it/cli/auth.mdx @@ -1,17 +1,17 @@ --- title: Accedi -description: "Accedi a FailproofAI dalla CLI per abilitare promemoria e funzioni personalizzate" +description: "Accedi a FailproofAI dalla CLI per abilitare i promemoria e le funzioni personalizzate" --- ```bash failproofai auth login # email + codice monouso failproofai auth logout # revoca questa sessione -failproofai auth whoami # stampa l'identità dell'utente connesso +failproofai auth whoami # stampa l'identità con accesso effettuato ``` La forma legacy con flag `--login` / `--logout` / `--whoami` è ancora accettata come alias per compatibilità retroattiva. -L'autenticazione è facoltativa. Le policy, la dashboard, la pagina `/audit` e tutte le altre funzioni locali funzionano esattamente allo stesso modo che tu sia connesso o meno. La superficie di login esiste affinché le funzioni che **richiedono** un'identità stabile (promemoria di re-audit oggi, altre in futuro) abbiano un punto di ancoraggio. +L'autenticazione è facoltativa. Le politiche, la dashboard, la pagina `/audit` e tutte le altre funzioni locali funzionano esattamente allo stesso modo, che tu sia connesso o meno. La pagina di accesso esiste affinché le funzioni che **richiedono** un'identità stabile (promemoria per la re-audizione oggi, altre in futuro) abbiano un punto di ancoraggio. ## Flusso di accesso @@ -19,9 +19,9 @@ L'autenticazione è facoltativa. Le policy, la dashboard, la pagina `/audit` e t failproofai auth login ``` -Richiede la tua email, invia un codice monouso a 6 cifre a quell'indirizzo, richiede il codice e al termine scrive `~/.failproofai/auth.json` (permessi `0600`). La stessa sessione sarà quindi visibile nella dashboard in-app — cliccando su `[ imposta un promemoria ]` in `/audit` ti vedrà come connesso. +Richiede la tua email, invia un codice monouso di 6 cifre a quell'indirizzo, richiede il codice e, in caso di successo, scrive `~/.failproofai/auth.json` (modalità `0600`). La stessa sessione è quindi visibile nella dashboard dell'app — facendo clic su `[ set a reminder ]` su `/audit` ti vedrà come connesso. -La dashboard espone lo stesso flusso come finestra di dialogo modale su `/audit` per gli utenti che non usano mai la CLI. +La dashboard espone lo stesso flusso come finestra di dialogo modale su `/audit` per gli utenti che non toccano mai la CLI. ## Disconnessione @@ -29,19 +29,19 @@ La dashboard espone lo stesso flusso come finestra di dialogo modale su `/audit` failproofai auth logout ``` -Revoca la sessione corrente sul server ed elimina `~/.failproofai/auth.json`. Se l'api-server è irraggiungibile, il file locale viene rimosso comunque — l'intenzione locale di disconnessione ha sempre la priorità. +Revoca la sessione corrente sul server ed elimina `~/.failproofai/auth.json`. Se il server API non è raggiungibile, il file locale viene comunque rimosso — l'intenzione locale di disconnessione ha sempre priorità. -## Controllo identità +## Verifica identità ```bash failproofai auth whoami ``` -Stampa ` ()` e esce con codice 0 quando esiste una sessione valida, oppure stampa `not signed in` e esce con codice 1 altrimenti. Aggiorna silenziosamente il token di accesso in background se è entro un minuto dalla scadenza. +Stampa ` ()` ed esce con codice 0 quando esiste una sessione valida, oppure stampa `not signed in` ed esce con codice 1 in caso contrario. Aggiorna silenziosamente il token di accesso in background se è a meno di un minuto dalla scadenza. -## Promemoria persistente di re-audit +## Promemoria persistente per re-audizione -Quando clicchi su **`[ imposta un promemoria ]`** nella pagina `/audit` (o accedi tramite la finestra di dialogo modale a cui il pulsante è collegato), la dashboard scrive un piccolo file companion in `~/.failproofai/next-audit.json`: +Quando fai clic su **`[ set a reminder ]`** sulla pagina `/audit` (o accedi tramite la finestra modale che il pulsante attiva), la dashboard scrive un piccolo file companion in `~/.failproofai/next-audit.json`: ```json { @@ -51,9 +51,9 @@ Quando clicchi su **`[ imposta un promemoria ]`** nella pagina `/audit` (o acced } ``` -Questo file è associato all'email per cui è stato impostato — cambiando la sessione CLI su un account diverso nascondi qualsiasi promemoria che appartiene all'utente precedente. L'offset predefinito è **7 giorni**, configurabile in seguito quando arriverà lo scheduler. Creato con permessi `0600` come `auth.json`. +Questo file è limitato all'email per cui è stato impostato — cambiando la sessione CLI su un account diverso nascondi qualsiasi promemoria appartenente all'utente precedente. L'offset predefinito è **7 giorni**, configurabile in seguito quando lo scheduler sarà disponibile. Creato con permessi `0600` come `auth.json`. -L'endpoint `/api/auth/reminder` della dashboard espone `GET` (lettura), `POST` (impostazione / riprogrammazione) e `DELETE` (cancellazione) e richiede una sessione attiva. +L'endpoint `/api/auth/reminder` della dashboard espone `GET` (lettura), `POST` (imposta / riprogramma) e `DELETE` (cancella) e richiede una sessione attiva. ## Cosa contiene `~/.failproofai/auth.json` @@ -67,21 +67,21 @@ L'endpoint `/api/auth/reminder` della dashboard espone `GET` (lettura), `POST` ( } ``` -Creato con permessi `0600` (lettura/scrittura solo del proprietario). Il token di accesso è un JWT HS256 di 1 ora; il token di refresh è una stringa casuale opaca di 256 bit che il server archivia come `SHA-256(token)`. La riproduzione del token di refresh viene rilevata lato server e revoca ogni sessione dell'utente. +Creato con permessi `0600` (lettura/scrittura solo proprietario). Il token di accesso è un JWT HS256 di 1 ora; il token di refresh è una stringa casuale opaca di 256 bit che il server memorizza come `SHA-256(token)`. La riproduzione del token di refresh viene rilevata lato server e revoca tutte le sessioni per l'utente. ## Variabili di ambiente -| Variabile | Predefinita | Scopo | +| Variabile | Predefinito | Scopo | |---|---|---| -| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | Sovrascrivi l'URL base dell'api-server. Utile per lo sviluppo locale con un api-server self-hosted. | -| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | Sovrascrivi dove viene archiviato `auth.json`. Principalmente per i test. | +| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | Sovrascrive l'URL base del server API. Utile per sviluppo locale con un server API self-hosted. | +| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | Sovrascrive dove è archiviato `auth.json`. Principalmente per i test. | -Vedi [Variabili di ambiente](/it/cli/environment-variables) per l'elenco completo. +Consulta [Variabili di ambiente](/it/cli/environment-variables) per l'elenco completo. ## Risoluzione dei problemi -**"Could not reach the api-server"** — la CLI non riesce ad aprire una connessione TCP a `FAILPROOF_API_URL`. Controlla la tua rete, oppure imposta `FAILPROOF_API_URL` se stai eseguendo un api-server self-hosted. +**"Could not reach the api-server"** — la CLI non può aprire una connessione TCP a `FAILPROOF_API_URL`. Controlla la tua rete o imposta `FAILPROOF_API_URL` se stai utilizzando un server API self-hosted. -**"Rate limited"** — troppi tentativi di login in una finestra di 15 minuti per quell'email (5/email) o IP (20/IP), oppure un cooldown di resend di 30 secondi dopo la richiesta precedente per la stessa email. Il messaggio di errore include la finestra di retry-after in secondi. +**"Rate limited"** — troppi tentativi di accesso in una finestra di 15 minuti per quell'email (5/email) o IP (20/IP), oppure un cooldown di ripetizione di 30 secondi dopo la richiesta precedente per la stessa email. Il messaggio di errore include la finestra retry-after in secondi. -**Code rejected** — l'OTP era sbagliato, scaduto, o la riga ha raggiunto il suo blocco di 5 tentativi errati. Esegui di nuovo `failproofai auth login` per richiedere un codice nuovo. \ No newline at end of file +**Code rejected** — l'OTP era errato, scaduto, oppure la riga ha raggiunto il blocco di 5 tentativi sbagliati. Esegui nuovamente `failproofai auth login` per richiedere un codice nuovo. \ No newline at end of file diff --git a/docs/it/cli/dashboard.mdx b/docs/it/cli/dashboard.mdx index afc8eedf..7dea3a51 100644 --- a/docs/it/cli/dashboard.mdx +++ b/docs/it/cli/dashboard.mdx @@ -1,22 +1,22 @@ --- -title: Visualizzare sessioni -description: "Avvia il dashboard per consultare le sessioni degli agenti e gestire i criteri" +title: Visualizza sessioni +description: "Avvia la dashboard per sfogliare le sessioni degli agenti e gestire le policy" --- ```bash failproofai ``` -Avvia il dashboard web su `http://localhost:8020`. +Avvia la dashboard web su `http://localhost:8020`. ## Opzioni | Flag | Descrizione | |------|-------------| -| `--port ` | Porta su cui ascoltare (predefinito: `8020`) | -| `--allowed-origins ` | Host/indirizzi IP separati da virgola autorizzati ad accedere alle risorse di sviluppo | +| `--port ` | Porta su cui ascoltare (default: `8020`) | +| `--allowed-origins ` | Host/IP separati da virgola autorizzati ad accedere alle risorse di sviluppo | -Per puntare il dashboard a una cartella di progetto Claude non predefinita, imposta la variabile di ambiente `CLAUDE_PROJECTS_PATH` all'avvio. +Per puntare la dashboard a una cartella di progetto Claude non standard, impostare la variabile di ambiente `CLAUDE_PROJECTS_PATH` al momento dell'avvio. ## Esempi @@ -24,6 +24,6 @@ Per puntare il dashboard a una cartella di progetto Claude non predefinita, impo # Avvia su una porta diversa failproofai --port 9000 -# Usa un percorso personalizzato per i progetti Claude tramite variabile di ambiente +# Utilizza un percorso progetti Claude personalizzato tramite variabile d'ambiente CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/it/cli/environment-variables.mdx b/docs/it/cli/environment-variables.mdx index cbea160a..cbdb50c3 100644 --- a/docs/it/cli/environment-variables.mdx +++ b/docs/it/cli/environment-variables.mdx @@ -1,48 +1,47 @@ --- ---- title: Variabili d'ambiente -description: "Configura il comportamento di failproofai con le variabili d'ambiente" +description: "Configura il comportamento di failproofai con variabili d'ambiente" --- ## Dashboard | Variabile | Descrizione | |----------|-------------| -| `PORT` | Porta del dashboard (predefinito: `8020`) | -| `CLAUDE_PROJECTS_PATH` | Sostituisci il percorso dove si trovano le cartelle dei progetti Claude Code | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Pagine del dashboard da nascondere, separate da virgole | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Host/IP autorizzati ad accedere alle risorse di sviluppo. Stesso di `--allowed-origins`. | +| `PORT` | Porta del dashboard (predefinita: `8020`) | +| `CLAUDE_PROJECTS_PATH` | Sostituisce il percorso in cui si trovano le cartelle dei progetti Claude Code | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Pagine del dashboard separate da virgola da nascondere | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Host/IP autorizzati ad accedere alle risorse di sviluppo. Equivalente a `--allowed-origins`. | ## Logging | Variabile | Descrizione | |----------|-------------| | `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Livello di log del server (predefinito: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | Percorso del file di log personalizzato, oppure `true` per il predefinito (`~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | Percorso personalizzato del file di log degli hook, oppure `true` per il percorso predefinito (`~/.failproofai/logs/hooks.log`) | ## Telemetria | Variabile | Descrizione | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Disabilita la telemetria anonima sull'utilizzo | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Disabilita la telemetria anonima di utilizzo | ## Autenticazione | Variabile | Descrizione | |----------|-------------| -| `FAILPROOF_API_URL` | Sostituisci l'URL di base dell'api-server utilizzato da `failproofai auth` e dalla finestra di dialogo di autenticazione del dashboard. Predefinito: `https://api.befailproof.ai`; imposta `http://localhost:8080` (o altrove) quando esegui un api-server locale. | -| `FAILPROOFAI_AUTH_DIR` | Sostituisci dove viene archiviato `auth.json` (predefinito: `~/.failproofai`). Principalmente utile per test isolati. | +| `FAILPROOF_API_URL` | Sostituisce l'URL di base del server API utilizzato da `failproofai auth` e dalla finestra di dialogo di autenticazione del dashboard. Predefinito: `https://api.befailproof.ai`; impostare a `http://localhost:8080` (o altro percorso) quando si esegue un api-server locale. | +| `FAILPROOFAI_AUTH_DIR` | Sostituisce il percorso in cui è memorizzato `auth.json` (predefinito: `~/.failproofai`). Principalmente utile per test isolati. | ## Prompt al primo avvio | Variabile | Descrizione | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | Salta il prompt che offre di installare le policy al primo invio di `failproofai` | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Salta il prompt che offre di installare le policy al primo richiamo di `failproofai` senza argomenti | ## LLM (per la valutazione delle policy) | Variabile | Descrizione | |----------|-------------| -| `FAILPROOFAI_LLM_BASE_URL` | Endpoint API LLM (predefinito: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | Chiave API per le policy alimentate da LLM | +| `FAILPROOFAI_LLM_BASE_URL` | Endpoint dell'API LLM (predefinito: `https://api.openai.com/v1`) | +| `FAILPROOFAI_LLM_API_KEY` | Chiave API per le policy basate su LLM | | `FAILPROOFAI_LLM_MODEL` | Nome del modello (predefinito: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/it/cli/hook.mdx b/docs/it/cli/hook.mdx index f4c5c6ae..ffc69b1c 100644 --- a/docs/it/cli/hook.mdx +++ b/docs/it/cli/hook.mdx @@ -1,6 +1,6 @@ --- -title: Handler hook (interno) -description: "Il sottoprocesso che Claude Code chiama su ogni evento di strumento" +title: Gestore di hook (interno) +description: "Il sottoprocesso che Claude Code chiama su ogni evento dello strumento" --- ```bash @@ -9,13 +9,13 @@ failproofai --hook Questo è il comando registrato nel `settings.json` di Claude Code da `failproofai policies --install`. Normalmente non lo chiami direttamente. -Legge un payload JSON da stdin, valuta tutte le policy abilitate e esce con un codice che indica la decisione: +Legge un payload JSON da stdin, valuta tutte le politiche abilitate ed esce con un codice che indica la decisione: | Codice di uscita | Decisione | Effetto | |-----------|----------|--------| | `0` | `allow` | Consenti l'azione | -| `1` | `deny` | Blocca l'azione - Claude vede il motivo del blocco | -| `2` | `instruct` | Inietta indicazioni nel contesto di Claude | +| `1` | `deny` | Blocca l'azione - Claude vede il motivo del rifiuto | +| `2` | `instruct` | Inietta guida nel contesto di Claude | ### Tipi di evento supportati @@ -23,8 +23,8 @@ Legge un payload JSON da stdin, valuta tutte le policy abilitate e esce con un c |----------|--------| | **Esecuzione dello strumento** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | | **Ciclo di vita della sessione** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | -| **Interazione utente** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | -| **Subagenti e attività** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | +| **Interazione dell'utente** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | +| **Suagenti e attività** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | | **Configurazione** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | | **File system** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | | **Contesto** | `PreCompact`, `PostCompact` | \ No newline at end of file diff --git a/docs/it/cli/install-policies.mdx b/docs/it/cli/install-policies.mdx index 242d5867..f5777cb9 100644 --- a/docs/it/cli/install-policies.mdx +++ b/docs/it/cli/install-policies.mdx @@ -1,13 +1,13 @@ --- -title: Installa policy -description: "Abilita le policy in modo che vengano eseguite su ogni chiamata tool dell'agent" +title: Installare le policy +description: "Abilita le policy in modo che vengano eseguite su ogni chiamata di tool dell'agent" --- ```bash failproofai policies --install [policy-names...] [options] ``` -Scrive voci hook nel file di impostazioni della CLI dell'agent installata (Claude Code, OpenAI Codex o GitHub Copilot CLI _(beta)_) in modo che failproofai intercetti le chiamate tool. +Scrive voci di hook nel file settings dell'agent CLI installato (Claude Code, OpenAI Codex, o GitHub Copilot CLI _(beta)_) in modo che failproofai intercetti le chiamate di tool. Alias: `failproofai p -i` @@ -15,17 +15,17 @@ Alias: `failproofai p -i` | Flag | Descrizione | |------|-------------| -| `--cli claude\|codex\|copilot` | CLI(s) dell'agent per cui installare; separate da spazio (es. `--cli claude codex copilot`) o ripetute. Ometti per rilevare automaticamente le CLI installate e ricevere una richiesta. | -| `--scope user` | Installa nel file di impostazioni con scope utente (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Predefinito. | -| `--scope project` | Installa nel file di impostazioni con scope progetto (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | +| `--cli claude\|codex\|copilot` | CLI agent per cui installare; separati da spazio (es. `--cli claude codex copilot`) oppure ripetuti. Ometti per rilevare automaticamente i CLI installati e ricevere una richiesta. | +| `--scope user` | Installa nel file settings con scope utente (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Predefinito. | +| `--scope project` | Installa nel file settings con scope progetto (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | | `--scope local` | Solo Claude — installa in `/.claude/settings.local.json`. Codex e Copilot non hanno uno scope `local`. | -| `--custom ` / `-c` | Percorso a un file JS contenente policy hook personalizzate | +| `--custom ` / `-c` | Percorso di un file JS contenente policy di hook personalizzate | ## Comportamento -- **Nessun nome di policy** - apre un prompt interattivo per selezionare le policy +- **Nessun nome di policy** - apre una richiesta interattiva per selezionare le policy - **Nomi specifici** - abilita quelle policy (aggiunte a quelle già abilitate) -- **`all`** - abilita tutte le policy disponibili +- **`all`** - abilita ogni policy disponibile L'installazione è additiva: eseguire `--install` di nuovo aggiunge nuove policy senza rimuovere quelle esistenti. @@ -50,8 +50,8 @@ failproofai policies --install --cli codex --scope project # Installa per GitHub Copilot CLI (beta) per il progetto corrente failproofai policies --install --cli copilot --scope project -# Installa per tutte e tre le CLI in una volta +# Installa per tutti e tre i CLI in una volta failproofai policies --install --cli claude codex copilot ``` -Quando `--custom ` è fornito, il file viene convalidato immediatamente - deve chiamare `customPolicies.add()` almeno una volta. Il percorso risolto viene salvato in `policies-config.json` come `customPoliciesPath`. \ No newline at end of file +Quando viene fornito `--custom `, il file viene convalidato immediatamente - deve chiamare `customPolicies.add()` almeno una volta. Il percorso risolto viene salvato in `policies-config.json` come `customPoliciesPath`. \ No newline at end of file diff --git a/docs/it/cli/list-policies.mdx b/docs/it/cli/list-policies.mdx index 23faf0be..be64eebf 100644 --- a/docs/it/cli/list-policies.mdx +++ b/docs/it/cli/list-policies.mdx @@ -1,5 +1,5 @@ --- -title: Elenca le policy +title: Elencare le policy description: "Visualizza quali policy sono abilitate, i loro parametri e le policy personalizzate" --- @@ -7,7 +7,7 @@ description: "Visualizza quali policy sono abilitate, i loro parametri e le poli failproofai policies ``` -Mostra tutte le policy con il loro stato, i parametri configurati e le policy personalizzate. +Visualizza tutte le policy con il loro stato, i parametri configurati e le policy personalizzate. ## Esempio di output @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -Le chiavi sconosciute in `policyParams` vengono segnalate qui in modo da poter individuare i refusi in anticipo. \ No newline at end of file +Le chiavi sconosciute in `policyParams` vengono segnalate qui in modo da poter individuare gli errori di digitazione in anticipo. \ No newline at end of file diff --git a/docs/it/cli/remove-policies.mdx b/docs/it/cli/remove-policies.mdx index 3184df5d..350bf734 100644 --- a/docs/it/cli/remove-policies.mdx +++ b/docs/it/cli/remove-policies.mdx @@ -1,13 +1,13 @@ --- title: Disinstallare le policy -description: "Rimuovere le voci dei hook dalle impostazioni di Claude Code" +description: "Rimuovere le voci di hook dalle impostazioni di Claude Code" --- ```bash failproofai policies --uninstall [policy-names...] [options] ``` -Rimuove le voci dei hook di failproofai dal file `settings.json` di Claude Code. +Rimuove le voci di hook di failproofai da `settings.json` di Claude Code. Alias: `failproofai p -u` @@ -15,27 +15,27 @@ Alias: `failproofai p -u` | Flag | Descrizione | |------|-------------| -| `--scope user` | Rimuove dalle impostazioni globali (predefinito) | -| `--scope project` | Rimuove dalle impostazioni del progetto | -| `--scope local` | Rimuove dalle impostazioni locali | -| `--scope all` | Rimuove da tutti gli ambiti contemporaneamente | +| `--scope user` | Rimuovi dalle impostazioni globali (predefinito) | +| `--scope project` | Rimuovi dalle impostazioni del progetto | +| `--scope local` | Rimuovi dalle impostazioni locali | +| `--scope all` | Rimuovi da tutti gli ambiti contemporaneamente | | `--custom` / `-c` | Cancella il `customPoliciesPath` dalla configurazione | ## Comportamento -- **Nessun nome di policy** - rimuove tutte le voci dei hook di failproofai dal file delle impostazioni -- **Nomi specifici** - disabilita quelle policy ma mantiene i hook installati +- **Nessun nome di policy** - rimuove tutte le voci di hook di failproofai dal file di impostazioni +- **Nomi specifici** - disabilita quelle policy ma mantiene gli hook installati ## Esempi ```bash -# Rimuove tutti i hook globalmente +# Rimuovi tutti gli hook globalmente failproofai policies --uninstall -# Disabilita una policy specifica (mantiene i hook installati) +# Disabilita una policy specifica (mantiene gli hook installati) failproofai policies --uninstall block-sudo -# Rimuove i hook da ogni ambito +# Rimuovi gli hook da ogni ambito failproofai policies --uninstall --scope all # Cancella il percorso delle policy personalizzate diff --git a/docs/it/cli/version.mdx b/docs/it/cli/version.mdx index 8c528ca9..31f26acd 100644 --- a/docs/it/cli/version.mdx +++ b/docs/it/cli/version.mdx @@ -1,5 +1,5 @@ --- -title: Controlla la versione +title: Controlla versione description: "Stampa la versione installata di failproofai" --- diff --git a/docs/it/configuration.mdx b/docs/it/configuration.mdx index 98605280..ad260ca3 100644 --- a/docs/it/configuration.mdx +++ b/docs/it/configuration.mdx @@ -1,22 +1,22 @@ --- title: Configurazione -description: "Formato del file config, sistema a tre ambiti e regole di merge" +description: "Formato file di configurazione, sistema a tre livelli 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 - commitla nel tuo repository e ogni sviluppatore otterrà la stessa rete di sicurezza per gli agenti. +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. --- ## Ambiti di configurazione -Esistono tre ambiti di configurazione, valutati in ordine di priorità: +Ci sono tre ambiti di configurazione, valutati in ordine di priorità: | Ambito | Percorso file | Scopo | |--------|---------------|-------| -| **project** | `.failproofai/policies-config.json` | Impostazioni per-repo, commitmate nel controllo versione | -| **local** | `.failproofai/policies-config.local.json` | Override personali per-repo, gitignored | -| **global** | `~/.failproofai/policies-config.json` | Impostazioni predefinite a livello utente su tutti i progetti | +| **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 | Quando failproofai riceve un evento hook, carica e unisce tutti e tre i file che esistono per la directory di lavoro corrente. @@ -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"] ← unione deduplicated +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← unione deduplificata ``` -**`policyParams`** - il primo ambito che definisce i parametri per una determinata policy vince completamente. Non c'è merge profondo dei valori all'interno dei parametri di una policy. +**`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. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -46,7 +46,7 @@ project: (nessuna voce block-sudo) local: (nessuna voce block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← ricade su global +resolved: { allowPatterns: ["sudo systemctl status"] } ← fallback a global ``` **`customPoliciesPath`** - il primo ambito che lo definisce vince. @@ -55,7 +55,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← ricade su global --- -## Formato del file di configurazione +## Formato file di configurazione ```json { @@ -96,85 +96,85 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← ricade su global --- -## Riferimento dei campi +## Riferimento campi ### `enabledPolicies` -Tipo: `string[]` +Type: `string[]` -Elenco di nomi di policy da abilitare. I nomi devono corrispondere esattamente agli identificatori di policy mostrati da `failproofai policies`. Consulta [Built-in Policies](/it/built-in-policies) per l'elenco completo. +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. Le policy non in `enabledPolicies` sono inattive, anche se hanno voci in `policyParams`. ### `policyParams` -Tipo: `Record>` +Type: `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). -Se una policy ha parametri ma non li specifichi, vengono utilizzati i valori predefiniti della policy. Gli utenti che non configurano affatto `policyParams` ottengono un comportamento identico alle versioni precedenti. +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. -Le chiavi sconosciute all'interno del blocco dei parametri di una policy vengono silenziosamente ignorate al momento dell'esecuzione dell'hook, ma contrassegnate come avvisi quando esegui `failproofai policies`. +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`. -#### `hint` (multi-policy) +#### `hint` (cross-cutting) -Tipo: `string` (opzionale) +Type: `string` (optional) -Un messaggio aggiunto al motivo quando una policy restituisce `deny` o `instruct`. Usalo per dare a Claude una guida fruibile senza modificare la policy stessa. +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. -Funziona con qualsiasi tipo di policy — built-in, personalizzate (`custom/`), convenzione di progetto (`.failproofai-project/`), o convenzione utente (`.failproofai-user/`). +Funziona con qualsiasi tipo di policy — built-in, custom (`custom/`), project convention (`.failproofai-project/`), o user convention (`.failproofai-user/`). ```json { "policyParams": { "block-force-push": { - "hint": "Try creating a fresh branch instead." + "hint": "Prova a creare invece un nuovo branch." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], - "hint": "Use apt-get directly without sudo." + "hint": "Usa apt-get direttamente senza sudo." }, "custom/my-policy": { - "hint": "Ask the user for approval first." + "hint": "Chiedi l'approvazione all'utente prima." } } } ``` -Quando `block-force-push` nega, Claude vede: *"Force-pushing is blocked. Try creating a fresh branch instead."* +Quando `block-force-push` nega, Claude vede: *"Il force-push è bloccato. Prova a creare invece un nuovo branch."* -I valori non stringa e le stringhe vuote vengono silenziosamente ignorati. Se `hint` non è impostato, il comportamento è invariato (retrocompatibile). +I valori non-string e le stringhe vuote sono silenziosamente ignorati. Se `hint` non è impostato, il comportamento è invariato (backward-compatible). ### `customPoliciesPath` -Tipo: `string` (percorso assoluto) +Type: `string` (absolute path) -Percorso di un file JavaScript contenente policy di hook personalizzate. Viene impostato automaticamente da `failproofai policies --install --custom ` (il percorso viene risolto in assoluto prima di essere memorizzato). +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). -Il file viene caricato di nuovo su ogni evento hook - non c'è caching. Consulta [Custom Policies](/it/custom-policies) per i dettagli di authoring. +Il file viene caricato fresco ad ogni evento hook - non c'è caching. Vedi [Custom Policies](/it/custom-policies) per i dettagli di authoring. ### Policy basate su convenzione -Oltre al `customPoliciesPath` esplicito, failproofai scopre e carica automaticamente i file di policy dalle directory `.failproofai/policies/`: +In aggiunta a `customPoliciesPath` esplicito, failproofai scopre automaticamente e carica file di policy dalle directory `.failproofai/policies/`: | Livello | Directory | Ambito | |---------|-----------|--------| -| Project | `.failproofai/policies/` | Condiviso con il team tramite controllo versione | +| Project | `.failproofai/policies/` | Condiviso con il team tramite version control | | 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`). Altri file nella directory vengono ignorati. +**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. -**Nessuna configurazione necessaria:** Le policy di convenzione non richiedono voci in `policies-config.json`. Basta rilasciare i file nella directory e verranno raccolti al prossimo evento hook. +**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. -**Caricamento unificato:** Entrambe le directory di convenzione di progetto e utente vengono scansionate. Tutti i file corrispondenti da entrambi i livelli vengono caricati (a differenza di `customPoliciesPath` che utilizza il primo ambito vince). +**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). -Consulta [Custom Policies](/it/custom-policies) per ulteriori dettagli ed esempi. +Vedi [Custom Policies](/it/custom-policies) per più dettagli ed esempi. ### `llm` -Tipo: `object` (opzionale) +Type: `object` (optional) -Configurazione del client LLM per le policy che effettuano chiamate AI. Non richiesto per la maggior parte delle configurazioni. +Configurazione del client LLM per le policy che effettuano chiamate AI. Non richiesta per la maggior parte delle configurazioni. ```json { @@ -189,19 +189,20 @@ 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 delle impostazioni hook della tua CLI agente (i punti di ingresso 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 del tuo agent (i punti di ingresso dell'hook), mentre `policies-config.json` è il file che gestisci direttamente. I due sono separati: -- **Impostazioni CLI agente** — dice all'agente di chiamare `failproofai --hook ` su ogni tool use: +- **Impostazioni agent CLI** — dice all'agent di chiamare `failproofai --hook ` ad ogni uso di strumento: - **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 ambito `local`. Le voci di hook utilizzano i campi di comando `bash`/`powershell` con chiave OS di Copilot con `timeoutSec`; il file porta un marcatore di livello superiore `version: 1`. Il supporto di Copilot CLI è **beta** mentre verifichiamo lo schema di registrazione di `events.jsonl` (che i documenti pubblici non specificano) rispetto a più sessioni nel mondo reale. - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — Cursor non ha ambito `local`. Le voci di hook utilizzano il modulo a forma di Claude `{type, command, timeout}` (nessuna divisione `bash`/`powershell`), ma memorizzate sotto chiavi di evento camelCase (`preToolUse`, `beforeSubmitPrompt`, …) in un array piatto per lo schema di hook di Cursor](https://cursor.com/docs/hooks); il file porta un marcatore di livello superiore `version: 1`. Il gestore canonicalizza camelCase → PascalCase tramite `CURSOR_EVENT_MAP` in modo che le policy builtin esistenti si attivino invariate. Il supporto di Cursor Agent è **beta** mentre verifichiamo il formato di trascrizione 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 ambito `local`. A differenza degli altri sei CLI, OpenCode ha **nessun sistema di hook di comando esterno**: carica i 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 rilascia un piccolo plugin shim generato che esegue in subprocess il binario failproofai e traduce la risposta JSON a forma di Claude del binario nella semantica del plugin: `throw new Error()` per il deny di evento tool (annulla la chiamata dello strumento), `client.session.prompt(...)` per instruct E per `Stop` / `SubagentStop` deny (invia il motivo di deny come il prossimo messaggio utente — l'unico canale di retry forzato poiché `session.idle` è solo notifica e il lancio da esso è un no-op), e no-op per allow. Lo shim canonicalizza sia i nomi degli strumenti (minuscolo → PascalCase tramite `OPENCODE_TOOL_MAP`) che le chiavi degli argomenti di input degli strumenti (camelCase → snake_case tramite `OPENCODE_TOOL_INPUT_MAP` per `Read` / `Write` / `Edit`, ad es. `filePath` → `file_path`, `oldString` → `old_string`) prima di inoltrarli al binario, quindi i builtin di controllo del percorso come `block-read-outside-cwd`, `block-env-files`, e `block-secrets-write` si attivano invariati sulle chiamate di tool di OpenCode. Le sessioni vivono nel database SQLite di opencode a `~/.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 su 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 ambito `local`. Pi carica pacchetti di estensione 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 iscrive agli eventi `tool_call` / `user_bash` / `input` / `session_start` di Pi e esegue il shelling in `failproofai --hook --cli pi`; il gestore canonicalizza underscore_lower_snake_case → PascalCase tramite `PI_EVENT_MAP` in modo che le policy builtin esistenti si attivino invariate. Gli argomenti di input degli strumenti vengono anche canonicalizzati tramite `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit forniscono `path` piuttosto che `file_path`; il mapping della 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 l'API di estensione di Pi e il layout del log di sessione si stabilizzano. - - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (user), `/.gemini/settings.json` (project) — Gemini non ha ambito `local` (documenta un ambito `system` a `/etc/gemini-cli/settings.json` che failproofai non espone). Le voci di hook utilizzano il modulo `{type, command, timeout}` di Claude racchiuso nello schema matcher `{matcher, hooks: [...]}` di Gemini con `matcher: "*"` per impostazione predefinita. Gli eventi sono PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); il gestore mappa ai nomi canonici di Claude tramite `GEMINI_EVENT_MAP`. I nomi degli strumenti sono snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — il gestore canonicalizza tramite `GEMINI_TOOL_MAP` in modo che i policy builtin esistenti si attivino invariati. L'evaluator di policy emette la forma piatta `{decision: "deny", reason}` di Gemini (preferita per il contratto exit-0 della regola d'oro di Gemini), `{hookSpecificOutput: {hookEventName, additionalContext}}` per l'iniezione di contesto su BeforeAgent / AfterTool / SessionStart, e `{decision: "block", reason}` su AfterAgent per la semantica di retry forzato. Il supporto di Gemini CLI è **beta** mentre aumentiamo la copertura nel mondo reale. Consulta la [documentazione degli hook di Gemini CLI](https://geminicli.com/docs/hooks/). -- **`policies-config.json`** — dice a failproofai quali policy valutare e con quali parametri (condiviso su tutti i CLI agente) + - **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 sei 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. + - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (user), `/.gemini/settings.json` (project) — Gemini non ha un ambito `local` (documenta un ambito `system` presso `/etc/gemini-cli/settings.json` che failproofai non espone). Le voci hook usano la forma `{type, command, timeout}` di Claude avvolta nello schema matcher `{matcher, hooks: [...]}` di Gemini con `matcher: "*"` di default. Gli eventi sono PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); il gestore mappa ai nomi canonici Claude tramite `GEMINI_EVENT_MAP`. I nomi di strumento sono snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — il gestore canonicalizza tramite `GEMINI_TOOL_MAP` quindi le policy built-in esistenti si attivano invariate. L'evaluator di policy emette la forma piatta di Gemini `{decision: "deny", reason}` (preferita per il contratto Golden Rule di Gemini exit-0), `{hookSpecificOutput: {hookEventName, additionalContext}}` per l'iniezione di contesto su BeforeAgent / AfterTool / SessionStart, e `{decision: "block", reason}` su AfterAgent per la semantica force-retry. Il supporto di Gemini CLI è **beta** mentre allargheremo la copertura del mondo reale. Vedi la [documentazione degli hook di Gemini CLI](https://geminicli.com/docs/hooks/). + - **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|gemini` per target un agente specifico (spazio-separato o ripetuto per qualsiasi sottoinsieme): +Passa `--cli claude|codex|copilot|cursor|opencode|pi|gemini|hermes` per indirizzare un agent specifico (space-separated o ripetuto per qualsiasi subset): ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +211,24 @@ 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 gemini --scope project +failproofai policies --install --cli hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` -Quando `--cli` è omesso, `failproofai` rileva quali CLI agente sono installati (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): +Quando `--cli` è omesso, `failproofai` rileva quali agent CLI sono installati (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini` / `which hermes`): -- **Un CLI rilevato** — seleziona automaticamente quel CLI senza richiedere conferma. -- **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 singolarmente) e una sezione `Not installed (M) · install hooks ahead of time` che elenca ogni CLI supportato non rilevato come opzione di installazione anticipata (↑↓ 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 richiedere conferma. -- **Nessuno rilevato** — ricade su `claude`, con un avviso che nessun binario agente è stato trovato in PATH; il comando hook viene comunque scritto in modo che si attivi non appena ne installi uno. +- **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. -Puoi modificare `policies-config.json` direttamente in qualsiasi momento; le modifiche hanno effetto immediatamente sul prossimo evento hook senza necessità di riavvio. +Puoi modificare `policies-config.json` direttamente in qualsiasi momento; le modifiche hanno effetto immediatamente al prossimo evento hook senza necessità di restart. --- -## Esempio: configurazione a livello di progetto con impostazioni predefinite del team +## Esempio: configurazione a livello di project con default del team -Commita `.failproofai/policies-config.json` nel tuo repository: +Committa `.failproofai/policies-config.json` nel tuo repo: ```json { diff --git a/docs/it/custom-policies.mdx b/docs/it/custom-policies.mdx index ddf852ef..5d7a217b 100644 --- a/docs/it/custom-policies.mdx +++ b/docs/it/custom-policies.mdx @@ -1,10 +1,10 @@ --- -title: Policy Personalizzate -description: "Scrivi le tue policy in JavaScript - applica convenzioni, previeni deviazioni, rileva errori, integrati con sistemi esterni" +title: Politiche personalizzate +description: "Scrivi le tue regole in JavaScript - applica convenzioni, previeni derive, rileva fallimenti, integrati con sistemi esterni" icon: code --- -Le policy personalizzate ti permettono di scrivere regole per qualsiasi comportamento dell'agente: applicare convenzioni di progetto, prevenire deviazioni, bloccare operazioni distruttive, rilevare agenti bloccati, o integrarti con Slack, workflow di approvazione e altro ancora. Utilizzano lo stesso sistema di hook event e le stesse decisioni `allow`, `deny`, `instruct` delle policy integrate. +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. --- @@ -37,14 +37,14 @@ failproofai policies --install --custom ./my-policies.js --- -## Due modi per caricare policy personalizzate +## Due modi per caricare politiche personalizzate ### Opzione 1: Basata su convenzione (consigliato) -Inserisci file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e verranno caricati automaticamente — nessun flag o cambio di configurazione necessario. Funziona come i git hooks: inserisci un file e basta. +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. ``` -# Livello di progetto — committato su git, condiviso con il team +# Livello di progetto — committato a git, condiviso con il team .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs @@ -54,43 +54,43 @@ Inserisci file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e verranno ca **Come funziona:** - Entrambe le directory di progetto e utente vengono scansionate (unione — non first-scope-wins) -- I file vengono caricati alfabeticamente all'interno di ogni directory. Utilizza il prefisso `01-`, `02-` per controllare l'ordine -- Vengono caricati solo i file che corrispondono a `*policies.{js,mjs,ts}`; gli altri file vengono ignorati -- Ogni file viene caricato in modo indipendente (fail-open per file) -- Funziona insieme alle policy `--custom` esplicite e alle policy integrate +- 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 -Le policy di convenzione sono il modo più semplice per costruire uno standard di qualità per la tua organizzazione. Committi `.failproofai/policies/` su git e ogni membro del team otterrà automaticamente le stesse regole — nessuna configurazione per sviluppatore necessaria. Mentre il tuo team scopre nuovi modi di fallimento, aggiungi una policy e fai il push. Nel tempo questi diventano uno standard di qualità dinamico che continua a migliorare con ogni contributo. +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. ### Opzione 2: Percorso file esplicito ```bash -# Installa con un file di policy personalizzate +# Installa con un file di politiche personalizzate failproofai policies --install --custom ./my-policies.js -# Sostituisci il percorso del file di policy +# Sostituisci il percorso del file di politiche failproofai policies --install --custom ./new-policies.js -# Rimuovi il percorso delle policy personalizzate dalla configurazione +# Rimuovi il percorso delle politiche personalizzate dalla configurazione failproofai policies --uninstall --custom ``` -Il percorso assoluto risolto viene memorizzato in `policies-config.json` come `customPoliciesPath`. Il file viene caricato fresh su ogni hook event - non c'è caching tra gli eventi. +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. -### Utilizzare entrambi insieme +### Usare entrambi insieme -Le policy di convenzione e il file `--custom` esplicito possono coesistere. Ordine di caricamento: +Le politiche di convenzione e il file `--custom` esplicito possono coesistere. Ordine di caricamento: 1. File `customPoliciesPath` esplicito (se configurato) -2. File di convenzione di progetto (`{cwd}/.failproofai/policies/`, alfabetico) -3. File di convenzione utente (`~/.failproofai/policies/`, alfabetico) +2. File di convenzione di progetto (`{cwd}/.failproofai/policies/`, alfabetici) +3. File di convenzione utente (`~/.failproofai/policies/`, alfabetici) --- ## API -### Import +### Importazione ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -98,7 +98,7 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Registra una policy. Chiama questa funzione tutte le volte necessarie per più policy nello stesso file. +Registra una politica. Chiamala tutte le volte che è necessario per più politiche nello stesso file. ```ts customPolicies.add({ @@ -111,32 +111,32 @@ customPolicies.add({ ### Helper per decisioni -| Funzione | Effetto | Usare quando | +| Funzione | Effetto | Usa quando | |----------|--------|----------| -| `allow()` | Permetti l'operazione silenziosamente | L'azione è sicura, nessun messaggio necessario | -| `deny(message)` | Blocca l'operazione | L'agente non dovrebbe eseguire questa azione | -| `instruct(message)` | Aggiungi contesto senza bloccare | Dai all'agente contesto aggiuntivo per rimanere in traccia | +| `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 | -`deny(message)` - il messaggio appare a Claude con prefisso `"Blocked by failproofai:"`. Un singolo `deny` cortocircuita tutta la valutazione successiva. +`deny(message)` - il messaggio appare a Claude con il prefisso `"Blocked by failproofai:"`. Un singolo `deny` fa cortocircuito su 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 guidance extra a qualsiasi messaggio `deny` o `instruct` aggiungendo un campo `hint` in `policyParams` — nessun cambio di codice necessario. Questo funziona anche per le policy 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 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. ### Messaggi allow informativi -`allow(message)` permette l'operazione **e** invia un messaggio informativo indietro 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 avvertimento. +`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. -| Funzione | Effetto | Usare quando | +| Funzione | Effetto | Usa quando | |----------|--------|----------| -| `allow(message)` | Permetti e invia contesto a Claude | Conferma che un controllo è passato, o spiega perché un controllo è stato saltato | +| `allow(message)` | Consenti 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.")` — dice a Claude che tutto è verde -- **Spiegazioni fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — dice a Claude perché un controllo è stato saltato così ha il contesto completo -- **Più messaggi si accumulano:** se più policy restituiscono ciascuna `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 è 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 ```js customPolicies.add({ @@ -160,48 +160,48 @@ customPolicies.add({ | Campo | Tipo | Descrizione | |-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | Lo strumento in fase di chiamata (es. `"Bash"`, `"Write"`, `"Read"`) | +| `toolName` | `string \| undefined` | Lo strumento chiamato (ad es. `"Bash"`, `"Write"`, `"Read"`) | | `toolInput` | `Record \| undefined` | I parametri di input dello strumento | -| `payload` | `Record` | Payload evento grezzo completo da Claude Code | -| `session` | `SessionMetadata \| undefined` | Contesto sessione (vedi sotto) | +| `payload` | `Record` | Payload di evento completo grezzo da Claude Code | +| `session` | `SessionMetadata \| undefined` | Contesto di sessione (vedi sotto) | ### Campi `SessionMetadata` | Campo | Tipo | Descrizione | |-------|------|-------------| -| `sessionId` | `string` | Identificatore sessione Claude Code | +| `sessionId` | `string` | Identificatore di sessione Claude Code | | `cwd` | `string` | Directory di lavoro della sessione Claude Code | -| `transcriptPath` | `string` | Percorso del file transcript JSONL della sessione | +| `transcriptPath` | `string` | Percorso del file trascritto JSONL della sessione | ### Tipi di evento | Evento | Quando si attiva | Contenuti `toolInput` | |-------|--------------|----------------------| -| `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" \| ... }` - i hook devono sempre restituire `allow()`, non possono bloccare le notifiche | +| `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) | +| `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 | --- ## Ordine di valutazione -Le policy vengono valutate in questo ordine: +Le politiche vengono valutate in questo ordine: -1. Policy integrate (in ordine di definizione) -2. Policy personalizzate esplicite da `customPoliciesPath` (in ordine `.add()`) -3. Policy di convenzione da `.failproofai/policies/` di progetto (file alfabetici, ordine `.add()` all'interno) -4. Policy di convenzione da `~/.failproofai/policies/` utente (file alfabetici, ordine `.add()` all'interno) +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) -Il primo `deny` cortocircuita tutte le policy successive. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme. +Il primo `deny` fa cortocircuito su tutte le politiche successive. Tutti i messaggi `instruct` vengono accumulati e consegnati insieme. --- -## Import transitivi +## Importazioni transitive -I file di policy personalizzate possono importare moduli locali utilizzando percorsi relativi: +I file di politiche personalizzate possono importare moduli locali usando percorsi relativi: ```js // my-policies.js @@ -218,46 +218,46 @@ customPolicies.add({ }); ``` -Tutti gli import relativi raggiungibili dal file di ingresso vengono risolti. Questo viene implementato riscrivendo gli import `from "failproofai"` al percorso dist effettivo e creando file `.mjs` temporanei per garantire la compatibilità ESM. +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. --- -## Filtraggio per tipo di evento +## Filtraggio dei tipi di evento -Usa `match.events` per limitare quando una policy si attiva: +Usa `match.events` per limitare quando una politica si attiva: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Si attiva solo quando la sessione termina - // ctx.session.transcriptPath contiene il log di sessione completo + // Only fires when the session ends + // ctx.session.transcriptPath contains the full session log return allow(); }, }); ``` -Ometti `match` completamente per attivarsi su ogni tipo di evento. +Ometti completamente `match` per attivarsi su ogni tipo di evento. --- ## Gestione degli errori e modalità di fallimento -Le policy personalizzate sono **fail-open**: gli errori non bloccano mai le policy integrate o fanno crashare il gestore hook. +Le politiche personalizzate sono **fail-open**: gli errori non bloccano mai le politiche incorporate o fanno bloccare il gestore hook. -| Errore | Comportamento | -|--------|----------| -| `customPoliciesPath` non impostato | Nessuna policy personalizzata esplicita viene eseguita; le policy di convenzione e le policy integrate continuano normalmente | -| File non trovato | Avvertimento registrato in `~/.failproofai/hook.log`; le policy integrate continuano | -| Errore di sintassi/import (esplicito) | Errore registrato in `~/.failproofai/hook.log`; le policy personalizzate esplicite vengono saltate | -| Errore di sintassi/import (convenzione) | Errore registrato; quel file viene saltato, gli altri file di convenzione continuano comunque a caricarsi | -| `fn` lancia un'eccezione a runtime | Errore registrato; questo hook viene trattato come `allow`; gli altri hook continuano | -| `fn` impiega più di 10s | Timeout registrato; trattato come `allow` | -| Directory di convenzione mancante | Nessuna policy di convenzione viene eseguita; nessun errore | +| Fallimento | 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` | +| Directory di convenzione mancante | Nessuna politica di convenzione viene eseguita; nessun errore | -Per eseguire il debug degli errori di policy personalizzate, osserva il file di log: +Per eseguire il debug degli errori delle politiche personalizzate, osserva il file di registro: ```bash tail -f ~/.failproofai/hook.log @@ -266,7 +266,7 @@ tail -f ~/.failproofai/hook.log --- -## Esempio completo: multiple policy +## Esempio completo: più politiche ```js // my-policies.js @@ -323,31 +323,31 @@ export { customPolicies }; ## Esempi -La directory `examples/` contiene file di policy pronti per l'uso: +La directory `examples/` contiene file di politiche pronti all'uso: | File | Contenuti | |------|----------| -| `examples/policies-basic.js` | Cinque policy iniziali che coprono i comuni modi di fallimento dell'agente | -| `examples/policies-advanced/index.js` | Pattern avanzati: import transitivi, chiamate asincrone, scrubbing dell'output, e hook di fine sessione | -| `examples/convention-policies/security-policies.mjs` | Policy di convenzione sulla sicurezza (blocca scritture .env, previeni riscrittura della storia git) | -| `examples/convention-policies/workflow-policies.mjs` | Policy di convenzione sul workflow (reminder di test, audit delle scritture di file) | +| `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/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) | -### Utilizzare esempi di file espliciti +### Utilizzo di esempi di file espliciti ```bash failproofai policies --install --custom ./examples/policies-basic.js ``` -### Utilizzare esempi basati su convenzione +### Utilizzo di esempi basati su convenzione ```bash -# Copia a livello di progetto +# Copy to project level mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# O copia a livello di utente +# Or copy to user level mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -Nessun comando di installazione necessario — i file vengono racccolti automaticamente al prossimo hook event. \ No newline at end of file +Nessun comando di installazione necessario — i file vengono prelevati automaticamente al prossimo evento hook. \ No newline at end of file diff --git a/docs/it/dashboard.mdx b/docs/it/dashboard.mdx index 242ed0ec..a4dcc440 100644 --- a/docs/it/dashboard.mdx +++ b/docs/it/dashboard.mdx @@ -1,14 +1,14 @@ --- title: Dashboard -description: "Monitora le sessioni degli agenti, rivedi le chiamate ai tool e gestisci le policy" +description: "Monitora le sessioni degli agenti, rivedi le chiamate agli strumenti e gestisci i criteri" icon: chart-line --- -La dashboard 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. +Il dashboard failproofai è un'applicazione web locale per monitorare le sessioni dei tuoi agenti AI e gestire i criteri. Scopri cosa hanno fatto i tuoi agenti mentre eri via. --- -## Avviare la dashboard +## Avvio del dashboard ```bash failproofai @@ -16,7 +16,7 @@ failproofai Si apre su `http://localhost:8020`. -La dashboard legge direttamente dal filesystem - i tuoi progetti Claude Code e i file di configurazione failproofai. Nulla viene scritto su un servizio remoto. +Il dashboard legge direttamente dal filesystem - le tue cartelle di progetti Claude Code e i file di configurazione failproofai. Nulla viene scritto su un servizio remoto. --- @@ -24,81 +24,81 @@ La dashboard legge direttamente dal filesystem - i tuoi progetti Claude Code e i ### Progetti -Elenca tutti i progetti Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_ e Gemini CLI _(beta)_ 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 scansionando ogni trascrizione sotto `~/.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 sotto `~/.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 scansionando le trascrizioni JSONL per sessione sotto `~/.pi/agent/sessions//_.jsonl` (configurabile tramite `PI_SESSIONS_DIR`) ed estraendo il `cwd` dal primo record di ogni sessione; i progetti Gemini CLI vengono individuati scansionando `~/.gemini/tmp//chats/session--.jsonl` (configurabile tramite `GEMINI_SESSIONS_DIR`) e recuperando il cwd canonico dal marcatore di testo `.project_root` adiacente. Un progetto che è stato utilizzato da più CLI viene reso come una singola riga con tutti i badge corrispondenti. Usa il dropdown **CLI** sopra la tabella per filtrare per un agente CLI specifico; l'URL preserva la tua selezione come `?cli=claude|codex|copilot|cursor|opencode|pi|gemini`. +Elenca tutti i progetti Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Gemini CLI _(beta)_ e Hermes trovati sulla tua macchina. I progetti Claude vengono rilevati da `~/.claude/projects/` (o dal percorso impostato da `CLAUDE_PROJECTS_PATH`); i progetti Codex vengono rilevati scansionando ogni trascrizione in `~/.codex/sessions///
/*.jsonl` e raggruppando per il `cwd` registrato nel primo record di ogni sessione; i progetti Copilot CLI vengono rilevati scansionando ogni `~/.copilot/session-state//workspace.yaml` (configurabile tramite `COPILOT_HOME`) e raggruppando per il suo campo `cwd`; i progetti Cursor Agent vengono rilevati scansionando i metadati per sessione in `~/.cursor/agent-sessions//` (configurabile tramite `CURSOR_HOME`, con `conversations/` e `sessions/` testati come fallback) per uno scalare `cwd` in `meta.json` / `session.json` / `workspace.yaml`; i progetti OpenCode vengono rilevati 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 rilevati scansionando trascrizioni JSONL per sessione in `~/.pi/agent/sessions//_.jsonl` (configurabile tramite `PI_SESSIONS_DIR`) e estraendo il `cwd` dal primo record di ogni sessione; i progetti Gemini CLI vengono rilevati scansionando `~/.gemini/tmp//chats/session--.jsonl` (configurabile tramite `GEMINI_SESSIONS_DIR`) e recuperando il cwd canonico dal marcatore di testo `.project_root` adiacente; le sessioni del gateway Hermes vengono lette direttamente dal suo archivio SQLite in `~/.hermes/state.db` (configurabile tramite `HERMES_DB_PATH`) e raggruppate in progetti `hermes-` per `source` (Slack/Telegram/cli/cron — le sessioni del gateway non hanno cwd). Un progetto utilizzato da più CLI viene visualizzato come una singola riga con tutti i badge corrispondenti. Utilizza il dropdown **CLI** sopra la tabella per filtrare per uno specifico agente CLI; l'URL preserva la tua selezione come `?cli=claude|codex|copilot|cursor|opencode|pi|gemini|hermes`. 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 `Gemini CLI` (azzurro) +- Un badge CLI — `Claude Code` (arancione), `OpenAI Codex` (viola), `GitHub Copilot` (blu), `Cursor Agent` (smeraldo), `OpenCode` (ambra), `Pi` (rosa), `Gemini CLI` (cielo), e/o `Hermes` (indaco) - Data dell'attività di sessione più recente -Fai clic su un progetto per visualizzare le sue sessioni. +Fai clic 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 -- Numero di attività hook (policy che si sono attivate) +- Numero di chiamate agli strumenti +- Conteggio dell'attività hook (criteri che si sono attivati) -Usa il filtro intervallo di date e la ricerca per ID sessione per restringere l'elenco. Le sessioni sono impaginate. +Utilizza il filtro dell'intervallo di date e la ricerca dell'ID della sessione per restringere l'elenco. Le sessioni sono impaginate. Fai clic su una sessione per aprire il visualizzatore di sessione. ### Visualizzatore di sessione -Il visualizzatore di sessione risponde alla domanda fondamentale per gli agenti autonomi: cosa ha fatto l'agente e ha mantenuto la rotta? Un badge CLI accanto all'intestazione indica se la sessione è una trascrizione di Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi o Gemini CLI. Mostra una cronologia di tutto ciò che è accaduto in una sessione: +Il visualizzatore di sessione risponde alla domanda chiave per gli agenti autonomi: cosa ha fatto l'agente e ha mantenuto il percorso corretto? Un badge CLI accanto all'intestazione indica se la sessione è una trascrizione di Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Gemini CLI o Hermes. Mostra una cronologia di tutto ciò che è accaduto in una sessione: - **Messaggi** - Risposte di testo di Claude e prompt dell'utente -- **Chiamate ai tool** - Ogni tool invocato da Claude, con il suo input e output -- **Attività policy** - Per ogni chiamata ai tool, quali policy si sono attivate e quale decisione hanno restituito +- **Chiamate agli strumenti** - Ogni strumento invocato da Claude, con il suo input e output +- **Attività dei criteri** - Per ogni chiamata allo strumento, quali criteri si sono attivati 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 hook (count allow / deny / instruct). +La barra delle statistiche in alto mostra la durata della sessione, il totale delle chiamate agli strumenti 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, Pi e Gemini ottieni la trascrizione JSONL originale su disco byte-for-byte; per OpenCode (le cui sessioni risiedono in SQLite, non su disco) ottieni un documento JSON che rispecchia le tabelle sottostanti `session` / `messages` / `parts`. +Fai clic sul pulsante **Download Logs** per esportare la sessione. Per le sessioni Claude Code, Codex, Copilot, Cursor, Pi e Gemini ricevi la trascrizione JSONL originale su disco byte-per-byte; per OpenCode (le cui sessioni si trovano in SQLite, non su disco) ricevi un documento JSON che rispecchia le tabelle `session` / `messages` / `parts` sottostanti. ### Audit -Un report caratterizzato da una personalità su come il tuo agente si è effettivamente comportato nelle sessioni passate. Esegue la stessa scansione del CLI `failproofai audit` ma la renderizza come un poster condivisibile in una singola schermata + quattro sezioni sotto il fold: +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 lo visualizza come un poster condivisibile a schermo singolo + 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 rango 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 ha questo archetipo` riga di rarità · sigillo di riquadro pixel 8×8 · footer `audit yours → failproof.ai`. Tre pulsanti di condivisione si trovano appena fuori dalla casella di cattura: `post your archetype` (intento X), `share on linkedin`, `download poster`. La cattura viene eseguita tramite `html-to-image` quindi il PNG corrisponde al rendering sullo schermo pixel-for-pixel (bordi tratteggiati, maschera logo SVG, gradienti, metriche dei font — tutto preservato). -2. **Strengths** — elenco di righe tranquillo ✓ dei comportamenti che il tuo agente già fa bene, derivati dai dati di audit in tempo reale (velocità di chiamata tool pulita, nessun push diretto a main, zero perdite di credenziali, zero storm di ripetizione) — ognuno visualizzato solo quando la policy corrispondente ha un record pulito nella finestra di audit. -3. **Quirks** — tabella di quello che è sfuggito, classificato per gravità: `when · what slipped + the policy that would've caught it · severity pill · seen`, dove la ricorrenza recita `new` (una volta), `N× seen` (2–9 volte), o `recurring` (10+). -4. **How to improve** — elenco di righe tranquillo, uno per policy prescritta: nome della policy in bianco, descrizione di una riga, comando di installazione + pulsante copia sul lato destro. L'intestazione della sezione recita `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 card affiancate. Sinistra: imposta un promemoria (selezionatore di cadenza `3d` / `7d` / `14d` / `30d`; persiste tramite `/api/auth/reminder` una volta autenticato). Destra: sblocca i vantaggi failproof — `invite a friend` apre una modale che accetta un elenco di indirizzi email di amici separati da virgole/spazi/newline (max 10 per invio), li invia a `/api/audit/invite`, che viene inoltrato a `POST /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 ottiene una copia nella sua inbox. Gli utenti anonimi vengono instradati prima tramite `AuthDialog` in modo che l'email del mittente sia conosciuta prima che gli inviti vengano inviati. L'adempimento dei diritti / vantaggi è un follow-up. +1. **Poster** — riempie il primo viewport. Regione di cattura PNG autonoma con il wordmark failproof_ai + etichetta di audit · indice archetipi (`№ NN of 08`) + data di audit · punteggio numerico (0–100) + pillola di classificazione percentile (`top 15%`) · 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 · riga di rarità `// only N% of agents are this archetype` · sigillo a piastrella 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` (intento X), `share on linkedin`, `download poster`. La cattura viene eseguita tramite `html-to-image` in modo che il PNG corrisponda al rendering su schermo pixel per pixel (bordi tratteggiati, maschera logo SVG, gradienti, metriche dei caratteri — tutto preservato). +2. **Strengths** — elenco di righe calm ✓ dei comportamenti che il tuo agente fa già bene, derivati dai dati di audit dal vivo (tasso di chiamate agli strumenti pulito, nessun push diretto a main, zero fughe di credenziali, zero tempeste di retry) — ognuno visualizzato solo quando il criterio rilevante ha un record pulito nell'intervallo di audit. +3. **Quirks** — tabella di ciò che è sfuggito, classificato 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 calm, uno per criterio prescritto: nome del criterio 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 tutte le correzioni applicate), e il suo pulsante `[install all]` copia il comando combinato `failproofai policy add a b c …` per ogni criterio prescritto. +5. **Come back better** — due schede affiancate. Sinistra: imposta un promemoria (scelta 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 di email di amici separati da virgola/spazio/newline (massimo 10 per invio), li invia tramite POST a `/api/audit/invite`, che viene inoltrato al server API `POST /v0/invite`. Il server API invia un'email per destinatario da `invite@failproof.ai` con il mittente in Cc e `Reply-To` impostato, in modo che il destinatario veda chi lo ha invitato e il mittente riceva una copia nella sua inbox. Gli utenti anonimi vengono indirizzati attraverso `AuthDialog` per primo in modo che l'email del mittente sia nota prima che gli inviti vengano inviati. L'adempimento dei diritti / vantaggi è un follow-up. -Guidato dal runtime `failproofai audit` — vedi [Audit CLI](/it/cli/audit) per il motore di scansione sottostante, i flag supportati e gli invarianti di cache per trascrizione. La dashboard mette in cache il risultato più recente in `~/.failproofai/audit-dashboard.json` (modalità `0600`, slot singolo, le nuove esecuzioni sovrascrivono) quindi i revisiti sono istantanei; **sia le cache per trascrizione che il risultato complessivo vengono rifiutate in lettura una volta che hanno più di 7 giorni** in modo che la dashboard non serva mai silenziosamente un risultato di una settimana fa — dopo il TTL `/audit` cade nello stato vuoto e richiede un'esecuzione nuova. Fare clic su `[ re-audit now ]` vicino al fondo del report invia a `/api/audit/run` con `noCache: true` — la rivalutazione ignora la cache per trascrizione e ripete la scansione di ogni trascrizione da zero piuttosto che ritornare silenziosamente il risultato in cache — e la dashboard interroga `/api/audit/status` a 1Hz fino al completamento dell'esecuzione; una striscia di progresso rosa appiccicosa si appunta alla parte superiore del viewport durante l'esecuzione con un timer trascorso, e il risultato fresco viene scambiato in posizione al successo (nessun ricaricamento di pagina completo; una rivalutazione non riuscita lascia il report precedente intatto). Al fallimento 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 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 trascrizione. Il dashboard memorizza nella cache il risultato più recente in `~/.failproofai/audit-dashboard.json` (modalità `0600`, slot singolo, le nuove esecuzioni sovrascrivono) in modo che le revisioni siano istantanee; **sia le cache per trascrizione che di risultato completo vengono rifiutate alla lettura una volta che hanno più di 7 giorni** in modo che il dashboard non serva mai silenziosamente un risultato di una settimana fa — dopo il TTL `/audit` cade nello stato vuoto e chiede un'esecuzione nuova. Fare clic su `[ re-audit now ]` vicino al fondo del rapporto invia un POST a `/api/audit/run` con `noCache: true` — il re-audit ignora la cache per trascrizione e ripete la scansione di 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 termine dell'esecuzione; una striscia di progresso rosa appiccicatizia si fissa in cima al viewport durante l'esecuzione con un timer trascorso, e il risultato nuovo si scambia in posizione al successo (nessun ricaricamento della pagina completa; un re-audit non riuscito lascia il rapporto precedente intatto). 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 trascrizioni) sono visualizzati separatamente. -### Policies +### Criteri -Una pagina a due schede per gestire le policy e rivedere l'attività. +Una pagina con due schede per gestire i criteri e rivedere l'attività. - - - Selezione multipla di quali CLI agenti failproofai protegge da un singolo pannello — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi e Gemini CLI hanno tutti una riga con stato di installazione (`Active` / `Detected` / `Inactive`), il percorso delle impostazioni dell'ambito utente e un accento con colore del marchio. Seleziona o deseleziona i CLI che desideri e fai clic su `Apply changes` per installare/disinstallare il diff in un passaggio. I CLI il cui binario viene rilevato su PATH sono preselezionati. - - Attiva o disattiva le singole policy con un solo clic (scrive in `~/.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 + + - Seleziona quale agenti CLI failproofai protegge da un singolo pannello — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Gemini CLI e Hermes hanno tutti una riga con stato di installazione (`Active` / `Detected` / `Inactive`), il percorso delle impostazioni dell'ambito utente e un accento di colore del marchio. Seleziona o deseleziona i CLI che desideri e fai clic su `Apply changes` per installare/disinstallare il diff in un unico passaggio. I CLI il cui binario viene rilevato su PATH sono pre-selezionati. + - Attiva o disattiva i singoli criteri con un singolo clic (scrive su `~/.failproofai/policies-config.json` — condiviso tra ogni CLI installata) + - Espandi un criterio per configurare i suoi parametri (per i criteri che supportano `policyParams`) + - Imposta un percorso file criteri personalizzato - - - Storico completo impaginato di ogni evento hook che si è attivato 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)_ / Gemini CLI _(beta)_), nome della policy o ID 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, azzurro = Gemini CLI), nome del tool, ID sessione e il motivo per le decisioni deny/instruct - - Fai clic su un ID 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`) e renderizza il badge CLI corrispondente nell'intestazione + + - Cronologia completa impaginata di ogni evento hook che si è attivato 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)_ / Gemini CLI _(beta)_ / Hermes), nome del criterio o ID della sessione + - Ogni riga mostra: timestamp, nome del criterio, decisione, badge CLI (arancione = Claude Code, viola = OpenAI Codex, blu = GitHub Copilot, smeraldo = Cursor Agent, ambra = OpenCode, rosa = Pi, cielo = Gemini CLI, indaco = Hermes), nome dello strumento, ID della sessione e il motivo delle decisioni deny/instruct + - Fai clic su un ID della 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`, Hermes `~/.hermes/state.db`) e visualizza il badge CLI corrispondente nell'intestazione --- -## Aggiornamento automatico +## Auto-refresh -La dashboard ha un interruttore di aggiornamento automatico nella navigazione in alto. 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 a lunga esecuzione. +Il dashboard ha un toggle di auto-refresh nella navigazione in alto. Se abilitato, la pagina corrente si aggiorna periodicamente per mostrare nuove sessioni e attività dei criteri man mano che compaiono. Essenziale per monitorare le sessioni degli agenti autonomi di lunga durata. --- -## Disabilitare pagine +## Disabilitazione delle pagine -Se hai bisogno solo di alcune parti della dashboard, imposta `FAILPROOFAI_DISABLE_PAGES` su un elenco di nomi di pagine separati da virgole: +Se hai bisogno solo di alcune parti del dashboard, imposta `FAILPROOFAI_DISABLE_PAGES` su un elenco separato da virgole di nomi di pagine: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -108,9 +108,9 @@ Valori validi: `policies`, `projects`, `audit`. --- -## Configurare il percorso dei progetti +## Configurazione del percorso dei progetti -Per impostazione predefinita, la dashboard legge dalla directory standard dei progetti Claude Code. Sovrascrivilo per configurazioni personalizzate: +Per impostazione predefinita, il dashboard legge dalla directory dei progetti standard di Claude Code. Sostituiscilo per configurazioni personalizzate: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,13 +120,13 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## Accesso da un host non-localhost -Quando esegui la dashboard in **modalità dev** (`npm run dev`) e la accedi da un nome host diverso da `localhost` - ad esempio, un dominio personalizzato, un IP remoto o un URL tunnelato - potresti vedere un avviso come: +Quando esegui il dashboard in **modalità di sviluppo** (`npm run dev`) e lo accedi da un hostname diverso da `localhost` - ad esempio, un dominio personalizzato, un IP remoto o un URL tunnelato - 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 funzione solo per dev. 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 per lo sviluppo. Per consentire il tuo host, utilizza il flag `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -138,12 +138,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` invece: +Puoi anche impostare la variabile di ambiente `FAILPROOFAI_ALLOWED_DEV_ORIGINS`: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Questo si applica solo alla modalità dev. Quando esegui `failproofai` (modalità produzione), non c'è alcun websocket HMR e nessun problema di risorsa dev cross-origin. +Questo si applica solo alla modalità di sviluppo. Quando esegui `failproofai` (modalità di produzione), non c'è websocket HMR e nessun problema di risorsa di sviluppo cross-origin. \ No newline at end of file diff --git a/docs/it/examples.mdx b/docs/it/examples.mdx index 43fb4a64..45b1b876 100644 --- a/docs/it/examples.mdx +++ b/docs/it/examples.mdx @@ -1,6 +1,7 @@ --- +--- title: Esempi -description: "Come configurare i hook per Claude Code e Agents SDK" +description: "Come configurare gli hook per Claude Code e l'Agents SDK" icon: book-open --- @@ -8,9 +9,9 @@ Esempi pronti all'uso per scenari comuni. Ognuno mostra come installare e cosa a --- -## Configurare i hook per Claude Code +## Configurazione degli hook per Claude Code -Failproof AI si integra con Claude Code tramite il suo [sistema di hook](https://docs.anthropic.com/en/docs/claude-code/hooks). Quando esegui `failproofai policies --install`, registra i comandi hook nel file `settings.json` di Claude Code che si attivano ad ogni chiamata di strumento. +Failproof AI si integra con Claude Code tramite il suo [sistema di hook](https://docs.anthropic.com/en/docs/claude-code/hooks). Quando esegui `failproofai policies --install`, registra i comandi degli hook nel file `settings.json` di Claude Code che si attivano ad ogni chiamata di tool. @@ -18,7 +19,7 @@ Failproof AI si integra con Claude Code tramite il suo [sistema di hook](https:/ npm install -g failproofai ``` - + ```bash failproofai policies --install ``` @@ -28,22 +29,22 @@ Failproof AI si integra con Claude Code tramite il suo [sistema di hook](https:/ cat ~/.claude/settings.json | grep failproofai ``` - Dovresti vedere i record degli hook per gli eventi `PreToolUse`, `PostToolUse`, `Notification` e `Stop`. + Dovresti vedere voci di hook per gli eventi `PreToolUse`, `PostToolUse`, `Notification` e `Stop`. ```bash claude ``` - Le policy si eseguono automaticamente ad ogni chiamata di strumento. Prova a chiedere a Claude di eseguire `sudo rm -rf /` - sarà bloccato. + Le politiche ora si eseguono automaticamente ad ogni chiamata di tool. Prova a chiedere a Claude di eseguire `sudo rm -rf /` - verrà bloccato. --- -## Configurare i hook per Agents SDK +## Configurazione degli hook per l'Agents SDK -Se stai sviluppando con [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), puoi utilizzare lo stesso sistema di hook programmaticamente. +Se stai sviluppando con l'[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), puoi utilizzare lo stesso sistema di hook a livello programmativo. @@ -52,14 +53,14 @@ Se stai sviluppando con [Agents SDK](https://docs.anthropic.com/en/docs/agents-s ``` - Passa i comandi hook quando crei il tuo processo agente. Gli hook si attivano allo stesso modo che in Claude Code - tramite JSON su stdin/stdout: + Passa i comandi degli hook quando crei il tuo processo agente. Gli hook si attivano allo stesso modo che in Claude Code - via JSON su stdin/stdout: ```bash - failproofai --hook PreToolUse # chiamato prima di ogni strumento - failproofai --hook PostToolUse # chiamato dopo ogni strumento + failproofai --hook PreToolUse # called before each tool + failproofai --hook PostToolUse # called after each tool ``` - + ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -77,7 +78,7 @@ Se stai sviluppando con [Agents SDK](https://docs.anthropic.com/en/docs/agents-s }); ``` - + ```bash failproofai policies --install --custom ./my-agent-policies.js ``` @@ -88,35 +89,35 @@ Se stai sviluppando con [Agents SDK](https://docs.anthropic.com/en/docs/agents-s ## Blocca i comandi distruttivi -La configurazione più comune - evita che gli agenti causino danni irreversibili. +La configurazione più comune - impedisci agli agenti di causare danni irreversibili. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` -Cosa fa: +Quello che fa: - `block-sudo` - blocca tutti i comandi `sudo` - `block-rm-rf` - blocca l'eliminazione ricorsiva di file - `block-force-push` - blocca `git push --force` -- `block-curl-pipe-sh` - blocca il reindirizzamento di script remoti verso la shell +- `block-curl-pipe-sh` - blocca il piping di script remoti alla shell --- ## Previeni la fuga di segreti -Impedisci agli agenti di vedere o divulgare credenziali nell'output degli strumenti. +Impedisci agli agenti di vedere o divulgare credenziali nell'output dei tool. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -Questi si attivano su `PostToolUse` - dopo che uno strumento viene eseguito, ripuliscono l'output prima che l'agente lo veda. +Questi si attivano su `PostToolUse` - dopo che un tool è stato eseguito, scrubano l'output prima che l'agente lo veda. --- -## Ricevi avvisi su Slack quando gli agenti richiedono attenzione +## Ricevi avvisi Slack quando gli agenti hanno bisogno di attenzione -Utilizza l'hook di notifica per inoltrare gli avvisi di inattività a Slack. +Usa l'hook di notifica per inoltrare gli avvisi di inattività a Slack. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -150,7 +151,7 @@ customPolicies.add({ }); ``` -Installala: +Installalo: ```bash SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js @@ -158,9 +159,9 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c --- -## Mantieni gli agenti su un branch +## Tieni gli agenti su un ramo -Previeni che gli agenti cambino branch o facciano push su quelli protetti. +Impedisci agli agenti di cambiare ramo o fare push su rami protetti. ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -184,7 +185,7 @@ customPolicies.add({ ## Richiedi test prima dei commit -Ricorda agli agenti di eseguire i test prima di fare commit. +Ricorda agli agenti di eseguire i test prima di effettuare un commit. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -208,7 +209,7 @@ customPolicies.add({ ## Proteggi un repository di produzione -Effettua il commit di una config a livello di progetto in modo che ogni sviluppatore del tuo team ottenga le stesse policy. +Esegui il commit di una configurazione a livello di progetto in modo che ogni sviluppatore del tuo team ottenga le stesse politiche. Crea `.failproofai/policies-config.json` nel tuo repository: @@ -231,7 +232,7 @@ Crea `.failproofai/policies-config.json` nel tuo repository: } ``` -Quindi fai il commit: +Quindi esegui il commit: ```bash git add .failproofai/policies-config.json @@ -242,12 +243,12 @@ Ogni membro del team che ha failproofai installato raccoglierà automaticamente --- -## Costruisci uno standard di qualità a livello organizzativo con policy di convenzione +## Crea uno standard di qualità a livello organizzativo con politiche di convenzione -La configurazione più efficace: effettua il commit di `.failproofai/policies/` nel tuo repository con policy personalizzate per il tuo progetto. Ogni membro del team le ottiene automaticamente — nessun comando di installazione, nessun cambio di configurazione. +La configurazione più impattante: esegui il commit di `.failproofai/policies/` nel tuo repository con politiche personalizzate per il tuo progetto. Ogni membro del team le ottiene automaticamente — nessun comando di installazione, nessun cambio di configurazione. - + ```bash mkdir -p .failproofai/policies ``` @@ -283,14 +284,14 @@ La configurazione più efficace: effettua il commit di `.failproofai/policies/` }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - Man mano che il tuo team incontra nuovi problemi, aggiungi policy e fai push. Tutti ricevono l'aggiornamento al prossimo `git pull`. Queste policy diventano uno standard di qualità vivo che cresce con il tuo team. + Man mano che il tuo team incontra nuove modalità di errore, aggiungi politiche e fai push. Ognuno ottiene l'aggiornamento al prossimo `git pull`. Queste politiche diventano uno standard di qualità vivente che cresce con il tuo team. @@ -301,7 +302,7 @@ La configurazione più efficace: effettua il commit di `.failproofai/policies/` La directory [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) nel repository contiene: | File | Cosa mostra | -|------|-------------| -| `policies-basic.js` | Policy per iniziare - blocca scritture di produzione, force-push, script reindirizzati | -| `policies-notification.js` | Avvisi Slack per notifiche di inattività e fine sessione | -| `policies-advanced/index.js` | Import transitivi, hook asincroni, ripulitura dell'output PostToolUse, gestione dell'evento Stop | \ No newline at end of file +|------|---------------| +| `policies-basic.js` | Politiche di base - blocca scritture in produzione, force-push, script con pipe | +| `policies-notification.js` | Avvisi Slack per notifiche di inattività e fine della sessione | +| `policies-advanced/index.js` | Import transitivi, hook asincroni, scrubbing dell'output di PostToolUse, gestione degli eventi Stop | \ No newline at end of file diff --git a/docs/it/for-agents.mdx b/docs/it/for-agents.mdx index e8430bc7..7c771d13 100644 --- a/docs/it/for-agents.mdx +++ b/docs/it/for-agents.mdx @@ -1,5 +1,5 @@ --- -title: "Per gli agenti" +title: "Per agenti" description: "Aggiungi la conoscenza di Failproof AI al tuo agente di codifica in un comando. Funziona con Claude Code, Cursor, Windsurf e altri." --- @@ -9,28 +9,28 @@ Aggiungi il riferimento completo di Failproof AI al tuo agente di codifica in un npx skills add https://docs.befailproof.ai ``` -`npx skills` rileva quali agenti hai installato e aggiunge la skill nel formato corretto per ognuno automaticamente. +`npx skills` rileva quali agenti hai installato e aggiunge la skill nel formato corretto per ciascuno automaticamente. ## Cosa copre la skill | Area | Cosa è incluso | -|------|----------------| -| Policy | Nomi delle policy integrate, tipi di evento, parametri, abilitazione/disabilitazione | -| Policy personalizzate | `customPolicies.add()`, filtri di corrispondenza, API `allow`/`deny`/`instruct` | -| Oggetto Context | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | -| Configurazione | Struttura `policies-config.json`, fusione di scope, `policyParams` | +|------|---| +| Policies | Nomi delle policy integrate, tipi di evento, parametri, abilitazione/disabilitazione | +| Custom policies | `customPolicies.add()`, filtri di corrispondenza, API `allow`/`deny`/`instruct` | +| Context object | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | +| Configuration | struttura `policies-config.json`, fusione degli scope, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scope | -| Dashboard | Visualizzatore di sessioni, attività delle policy, variabili d'ambiente | -| Architettura | Flusso del gestore hook, codici di uscita, contratto stdin/stdout | +| Dashboard | visualizzatore di sessioni, attività delle policy, variabili di ambiente | +| Architecture | flusso del gestore hook, codici di uscita, contratto stdin/stdout | ## La skill è completa? -Mintlify genera `llms.txt` da tutte le pagine nella navigazione. La documentazione di Failproof AI copre l'API completa - ogni policy, opzione ed esempio è incluso. Se trovi qualcosa che manca, la fonte è su `https://docs.befailproof.ai/llms-full.txt`. +Mintlify genera `llms.txt` da tutte le pagine nella navigazione. La documentazione di Failproof AI copre l'API completa - ogni policy, opzione ed esempio è incluso. Se trovi qualcosa di mancante, la fonte è su `https://docs.befailproof.ai/llms-full.txt`. Per un contesto mirato, collega direttamente a una pagina specifica: ```bash -# Solo l'API per le policy personalizzate +# Solo l'API custom policies npx skills add https://docs.befailproof.ai/custom-policies # Solo le policy integrate diff --git a/docs/it/getting-started.mdx b/docs/it/getting-started.mdx index 4ffd7a19..fb583f43 100644 --- a/docs/it/getting-started.mdx +++ b/docs/it/getting-started.mdx @@ -1,13 +1,14 @@ --- -title: Per iniziare -description: "Installa failproofai, abilita le politiche e lascia che i tuoi agenti funzionino in modo affidabile" +--- +title: Guida introduttiva +description: "Installa failproofai, abilita le policy e lascia che i tuoi agent funzionino in modo affidabile" icon: rocket --- ## Requisiti - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (facoltativo - necessario solo per compilare dal codice sorgente) +- **Bun** >= 1.3.0 (opzionale - necessario solo per compilare dal codice sorgente) --- @@ -27,19 +28,19 @@ bun add -g failproofai --- -## Inizio rapido +## Avvio rapido - - Le politiche sono regole che vengono eseguite prima e dopo ogni chiamata a uno strumento dell'agente. Intercettano i comandi distruttivi, la fuga di segreti e altre modalità di guasto prima che causino danni. + + Le policy sono regole che vengono eseguite prima e dopo ogni chiamata di strumento dell'agent. Catturano comandi distruttivi, fughe di segreti e altri modi di fallimento prima che causino danni. ```bash failproofai policies --install ``` - Questo scrive voci di hook nelle CLI dell'agente installate (il file `~/.claude/settings.json` di Claude Code, il file `~/.codex/hooks.json` di OpenAI Codex, il file `~/.copilot/hooks/failproofai.json` di GitHub Copilot CLI, il file `~/.cursor/hooks.json` di Cursor Agent, lo shim del plugin generato di OpenCode in `~/.config/opencode/plugins/failproofai.mjs` più una voce di registrazione nell'array `plugin` di `~/.config/opencode/opencode.json`, il file `~/.pi/agent/settings.json` di Pi, oppure il file `~/.gemini/settings.json` di Gemini CLI). Quando è presente più di uno, ti verrà chiesto di scegliere; passa `--cli claude codex copilot cursor opencode pi gemini` (qualsiasi sottoinsieme) per saltare la richiesta. + Questo scrive voci di hook nei tuoi agent CLI installati (il file `~/.claude/settings.json` di Claude Code, il file `~/.codex/hooks.json` di OpenAI Codex, il file `~/.copilot/hooks/failproofai.json` di GitHub Copilot CLI, il file `~/.cursor/hooks.json` di Cursor Agent, lo shim del plugin generato di OpenCode in `~/.config/opencode/plugins/failproofai.mjs` più una voce di registrazione nell'array `plugin` di `~/.config/opencode/opencode.json`, il file `~/.pi/agent/settings.json` di Pi, il file `~/.gemini/settings.json` di Gemini CLI, o il file `~/.hermes/config.yaml` di Hermes). Quando è presente più di uno, ti verrà chiesto; passa `--cli claude codex copilot cursor opencode pi gemini hermes` (qualsiasi sottoinsieme) per saltare la richiesta. - Il supporto per GitHub Copilot CLI, Cursor Agent, OpenCode, Pi e Gemini CLI è in fase **beta** — installa con `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, oppure `--cli gemini`. + Il supporto per GitHub Copilot CLI, Cursor Agent, OpenCode, Pi e Gemini CLI è in **beta** — installa con `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi` o `--cli gemini`. Hermes (hermes-agent, un gateway Slack/Telegram) si installa con ambito utente con `--cli hermes` ed è **anche** una fonte di audit offline. ```bash failproofai policies --install --scope project @@ -49,6 +50,7 @@ bun add -g failproofai failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project + failproofai policies --install --cli hermes --scope user failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` @@ -57,56 +59,56 @@ bun add -g failproofai failproofai policies ``` - Mostra ogni politica, se è abilitata e tutti i parametri configurati. + Mostra ogni policy, se è abilitata e eventuali parametri configurati. - + ```bash failproofai ``` - Apre un dashboard locale all'indirizzo `http://localhost:8020` dove puoi sfogliare le sessioni, ispezionare le chiamate agli strumenti e gestire le politiche. + Apre una dashboard locale su `http://localhost:8020` dove puoi sfogliare le sessioni, ispezionare le chiamate di strumento e gestire le policy. - - Avvia Claude Code come di solito. Se l'agente prova a fare qualcosa di rischioso, failproofai lo intercetta automaticamente. Lascialo in esecuzione incustodito e rivedi quello che è successo nel dashboard. + + Avvia Claude Code come al solito. Se l'agent prova a fare qualcosa di rischioso, failproofai lo intercetta automaticamente. Lascialo in esecuzione incustodito e rivedi quello che è successo nella dashboard. --- -## Come funzionano le politiche +## Come funzionano le policy -Ogni volta che un agente esegue uno strumento, Claude Code chiama failproofai come sottoprocesso: +Ogni volta che un agent esegue uno strumento, Claude Code chiama failproofai come sottoprocesso: ```text Claude Code → failproofai --hook PreToolUse → legge JSON da stdin - valuta le politiche + valuta le policy scrive la decisione su stdout ``` -Ogni politica restituisce una di tre decisioni: +Ogni policy restituisce una di tre decisioni: -- **allow** - l'agente procede normalmente -- **deny** - l'azione viene bloccata, all'agente viene spiegato il motivo -- **instruct** - contesto aggiuntivo viene aggiunto al prompt dell'agente +- **allow** - l'agent procede normalmente +- **deny** - l'azione viene bloccata, all'agent viene spiegato il motivo +- **instruct** - contesto aggiuntivo viene aggiunto al prompt dell'agent -Le politiche vengono eseguite nel tuo processo locale. Nulla viene inviato a un servizio remoto. +Le policy vengono eseguite nel tuo processo locale. Nulla viene inviato a un servizio remoto. --- -## Configura politiche di team con politiche basate su convenzione +## Configura policy di team con policy basate su convenzione -Il modo più veloce per stabilire standard di qualità in tutto il team è la convenzione `.failproofai/policies/`. Inserisci i file delle politiche in questa directory e verranno caricati automaticamente — senza flag, senza modifiche di configurazione, senza comandi di installazione. +Il modo più veloce per stabilire standard di qualità in tutto il team è la convenzione `.failproofai/policies/`. Inserisci file di policy in questa directory e vengono caricati automaticamente — nessun flag, nessun cambio di configurazione, nessun comando di installazione. - + ```bash mkdir -p .failproofai/policies ``` - - Copia gli esempi di avvio o scrivi i tuoi: + + Copia gli esempi iniziali o scrivi i tuoi: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -131,33 +133,33 @@ Il modo più veloce per stabilire standard di qualità in tutto il team è la co }); ``` - + ```bash git add .failproofai/policies/ - git commit -m "Add team quality policies" + git commit -m "Aggiungi policy di qualità del team" ``` - Ogni membro del team che ha failproofai installato raccoglie automaticamente queste politiche. Nessuna configurazione per sviluppatore necessaria. + Ogni membro del team che ha failproofai installato raccoglie automaticamente queste policy. Nessuna configurazione per sviluppatore necessaria. -Fai il commit di `.failproofai/policies/` nel tuo repository in modo che tutto il team condivida gli stessi standard. Man mano che il tuo team scopre nuove modalità di guasto, aggiungi politiche e fai il push — tutti riceveranno l'aggiornamento al prossimo `git pull`. Nel tempo, queste politiche diventano uno standard di qualità che migliora continuamente. +Fai il commit di `.failproofai/policies/` nel tuo repository in modo che tutto il team condivida gli stessi standard. Man mano che il tuo team scopre nuovi modi di fallimento, aggiungi policy e fai il push — ognuno riceve l'aggiornamento al prossimo `git pull`. Nel tempo queste policy diventano uno standard di qualità vivente che continua a migliorare. --- ## Archiviazione dei dati -Tutti i file di configurazione e i log rimangono sulla tua macchina: +Tutta la configurazione e i log rimangono sulla tua macchina: -| Percorso | Cosa contiene | +| Percorso | Cosa archivia | |------|----------------| -| `~/.failproofai/policies-config.json` | Configurazione della politica globale | +| `~/.failproofai/policies-config.json` | Configurazione globale delle policy | | `~/.failproofai/hook-activity.jsonl` | Cronologia dell'esecuzione degli hook | -| `~/.failproofai/hook.log` | Log di debug per gli errori degli hook personalizzati | -| `.failproofai/policies-config.json` | Configurazione per progetto (sottoposta a commit) | -| `.failproofai/policies-config.local.json` | Override personali (ignorato da git) | +| `~/.failproofai/hook.log` | Log di debug per errori degli hook personalizzati | +| `.failproofai/policies-config.json` | Configurazione per progetto (committed) | +| `.failproofai/policies-config.local.json` | Personalizzazioni personali (gitignored) | --- @@ -167,7 +169,7 @@ Tutti i file di configurazione e i log rimangono sulla tua macchina: failproofai policies --uninstall ``` -Rimuove le voci di hook da `~/.claude/settings.json`. I file di configurazione in `~/.failproofai/` vengono mantenuti. +Rimuove le voci degli hook da `~/.claude/settings.json`. I file di configurazione in `~/.failproofai/` vengono conservati. --- @@ -179,16 +181,16 @@ Rimuove le voci di hook da `~/.claude/settings.json`. I file di configurazione i Ambiti e formato del file di configurazione - - Tutte le 26 politiche con parametri + + Tutte le 26 policy con parametri - - Scrivi le tue politiche in JavaScript + + Scrivi le tue policy in JavaScript - - Monitora le sessioni e rivedi l'attività delle politiche + + Monitora le sessioni e rivedi l'attività delle policy \ No newline at end of file diff --git a/docs/it/introduction.mdx b/docs/it/introduction.mdx index 1a3419e7..0a1d097f 100644 --- a/docs/it/introduction.mdx +++ b/docs/it/introduction.mdx @@ -1,36 +1,36 @@ --- title: "Failproof AI" -description: "FailproofAI fornisce agli agenti AI 39 politiche di fallimento integrate che intercettano loop, perdite di segreti, chiamate di strumenti distruttive e altro ancora in una singola installazione." +description: "FailproofAI fornisce agli agenti AI 39 politiche di fallimento integrate che rilevano loop, perdite di segreti, chiamate di strumenti distruttive e altro ancora in una singola installazione." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -Hook e politiche per **la gestione dei fallimenti nell'AI**, **il recupero dagli errori** e **l'affidabilità degli LLM**. Mantieni i tuoi agenti AI affidabili e in esecuzione autonoma su **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI** e **Agents SDK**. +Hook e politiche per **gestione dei fallimenti dell'AI**, **recupero degli errori** e **affidabilità dell'LLM**. Mantieni i tuoi agenti AI affidabili e in esecuzione autonoma su **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, **Hermes** e **Agents SDK**. -Gli agenti AI falliscono in modi prevedibili. Eseguono comandi distruttivi, perdono segreti, si allontanano dal compito assegnato, rimangono bloccati in loop o eseguono push direttamente al ramo principale. Senza supervisione, i piccoli fallimenti si trasformano in interruzioni di servizio, perdita di credenziali e lavoro perso. +Gli agenti AI falliscono in modi prevedibili. Eseguono comandi distruttivi, perdono segreti, si allontanano dall'obiettivo, rimangono bloccati in loop, o effettuano push direttamente al main. Se non controllati, piccoli fallimenti si trasformano in interruzioni, credenziali compromesse e lavoro perso. -FailproofAI risolve questo problema con le **politiche**. Queste regole si collegano a ogni chiamata di strumento dell'agente per **rilevare i fallimenti**, **mitigarli** (bloccare, istruire, sanitizzare) e **avvertirti** quando qualcosa richiede attenzione. Una dashboard locale ti consente di rivedere ogni chiamata di strumento, fallimento dell'agente e azione di recupero in seguito. +FailproofAI risolve questo con le **politiche**. Queste regole si intercettano in ogni chiamata di strumento dell'agente per **rilevare i fallimenti**, **mitigarli** (bloccare, istruire, pulire) e **avvisarti** quando qualcosa richiede attenzione. Un dashboard locale ti permette di esaminare ogni chiamata di strumento, fallimento dell'agente e azione di recupero in seguito. -Nessun dato lascia la tua macchina. +Nessun dato lascia il tuo computer. ## Inizia subito - Blocca comandi distruttivi, previeni perdite di segreti, mantieni gli agenti entro i confini del progetto e molto altro. Tutto disponibile subito. + Blocca comandi distruttivi, previeni perdite di segreti, mantieni gli agenti entro i confini del progetto e altro ancora. Tutto già pronto. Scrivi le tue regole in JavaScript con un semplice API allow / deny / instruct. - - Scopri cosa hanno fatto i tuoi agenti mentre eri assente. Sfoglia le sessioni, ispeziona le chiamate di strumenti, controlla dove le politiche sono state applicate. + + Scopri cosa hanno fatto i tuoi agenti mentre eri assente. Naviga le sessioni, ispeziona le chiamate di strumenti, rivedi dove le politiche hanno agito. - Regola qualsiasi politica senza codice. Imposta allowlist, rami protetti o soglie per progetto o globalmente. + Regola qualsiasi politica senza codice. Imposta liste di autorizzazione, rami protetti o soglie per progetto o globalmente. @@ -50,8 +50,8 @@ bun add -g failproofai ```bash -failproofai policies --install # abilita le politiche (oppure salta — `failproofai` ti offrirà di configurarle al primo avvio) -failproofai # avvia la dashboard +failproofai policies --install # abilita le politiche (o salta — `failproofai` ti offrirà di configurarle al primo avvio) +failproofai # avvia il dashboard ``` -Consulta la guida [Inizia subito](/it/getting-started) per la procedura dettagliata completa. \ No newline at end of file +Vedi la guida [Inizia subito](/it/getting-started) per la procedura dettagliata completa. \ No newline at end of file diff --git a/docs/it/package-aliases.mdx b/docs/it/package-aliases.mdx index fe1f087c..064e6499 100644 --- a/docs/it/package-aliases.mdx +++ b/docs/it/package-aliases.mdx @@ -16,17 +16,17 @@ bun add -g failproofai --- -## Perché possediamo i nomi degli alias +## Perché possediamo i nomi alias -Il typosquatting è un attacco comune alla supply chain in cui un attore malevolo registra un nome di pacchetto che dista una pressione di tasto da un pacchetto popolare. Gli utenti ignari che commettono errori di battitura durante l'installazione finiscono per eseguire codice controllato dall'attaccante con accesso completo al sistema - esattamente il tipo di minaccia che Failproof AI è progettato per difendere. +Il typosquatting è un attacco alla supply chain comune in cui un attore malevolo registra un nome di pacchetto che dista una pressione di tasto da un pacchetto popolare. Gli utenti ignari che commettono errori di battitura nel comando di installazione finiscono per eseguire codice controllato dall'attaccante con accesso completo al sistema - esattamente il tipo di minaccia che Failproof AI è progettato per difendere. -Per eliminare questa superficie di attacco, **possediamo preventivamente tutte le comuni varianti di ortografia e formattazione** di `failproofai` su npm. Nessuno di questi nomi può essere registrato da terze parti. Ognuno di essi è un thin proxy che installa e delega al vero pacchetto `failproofai`. +Per eliminare questa superficie di attacco, **possediamo preventivamente tutti gli errori di battitura comuni e le varianti di formattazione** di `failproofai` su npm. Nessuno di questi nomi può essere registrato da terze parti. Ognuno di essi è un proxy sottile che installa e delega al vero pacchetto `failproofai`. --- ## Alias registrati -**Varianti di formattazione** - diversi modi di scrivere "failproof ai": +**Varianti di formattazione** - modi diversi di scrivere "failproof ai": | Pacchetto | Stato | |---------|--------| @@ -47,7 +47,7 @@ Per eliminare questa superficie di attacco, **possediamo preventivamente tutte l | `fail-prof-ai` | ⏳ In attesa di supporto npm | | `failprof_ai` | ⏳ In attesa di supporto npm | -**Errori di battitura `faliproof*`** - `a` e `i` trasposte: +**Errori di battitura `faliproof*`** - `a` e `i` scambiate: | Pacchetto | Stato | |---------|--------| @@ -55,13 +55,13 @@ Per eliminare questa superficie di attacco, **possediamo preventivamente tutte l | `faliproof-ai` | ✅ Pubblicato | | `faliproofai` | ⏳ In attesa di supporto npm | -> **Perché in sospeso?** La politica anti-spam di npm blocca i nomi che si normalizzano alla stessa stringa di un pacchetto esistente dopo aver rimosso la punteggiatura ed eseguito controlli di somiglianza. Abbiamo contattato il supporto npm per riservare questi nomi a scopo anti-squatting. Verranno attivati una volta approvati. +> **Perché in attesa?** La politica di prevenzione dello spam di npm blocca i nomi che si normalizzano alla stessa stringa di un pacchetto esistente dopo aver rimosso la punteggiatura ed eseguito controlli di somiglianza. Abbiamo contattato il supporto npm per riservare questi nomi a scopo di protezione dal typosquatting. Verranno attivati una volta approvati. -Puoi verificare che qualsiasi alias pubblicato ci appartiene: +Puoi verificare che qualsiasi alias pubblicato sia di nostra proprietà: ```bash npm info failproof -# Cerca: "ExosphereHost Inc." nel campo maintainers +# Cerca: "ExosphereHost Inc." nel campo dei manutentori ``` --- @@ -70,13 +70,13 @@ npm info failproof Ogni pacchetto alias: -1. Elenca `failproofai` come dipendenza - così il vero pacchetto (inclusa la sua configurazione hook `postinstall`) viene eseguito durante l'installazione -2. Espone un binario che corrisponde al suo stesso nome (ad es. `failprof-ai`) che proxy tutti gli argomenti al binario `failproofai` +1. Elenca `failproofai` come dipendenza - così il vero pacchetto (inclusa la sua configurazione del hook `postinstall`) viene eseguito al momento dell'installazione +2. Espone un binario che corrisponde al proprio nome (ad es. `failprof-ai`) che proxy tutti gli argomenti al binario `failproofai` -Il proxy è uno script Node di due righe; non c'è logica, nessuna chiamata di rete e nessuna raccolta di dati oltre a quella che `failproofai` stesso esegue. +Il proxy è uno script Node di due righe; non c'è logica, nessuna chiamata di rete e nessuna raccolta di dati oltre a quella che fa `failproofai` stesso. --- -## Se trovi un nome che abbiamo tralasciato +## Se trovi un nome che abbiamo perso -Apri un issue su [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) e lo registreremo. \ No newline at end of file +Apri una segnalazione su [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) e lo registreremo. \ No newline at end of file diff --git a/docs/it/testing.mdx b/docs/it/testing.mdx index 2bcfe0ab..dbd88be2 100644 --- a/docs/it/testing.mdx +++ b/docs/it/testing.mdx @@ -4,7 +4,7 @@ description: "Test unitari, test end-to-end e helper per i test" icon: flask-vial --- -failproofai ha due suite di test: **test unitari** (veloci, con mock) e **test end-to-end** (invocazioni reali di subprocess). +failproofai ha due suite di test: **test unitari** (veloci, mockati) e **test end-to-end** (invocazioni reali di sottoproc --- @@ -17,10 +17,10 @@ bun run test:run # Esegui i test unitari in modalità watch bun run test -# Esegui i test E2E (richiede setup - vedi sotto) +# Esegui i test E2E (richiede configurazione - vedi sotto) bun run test:e2e -# Type-check senza compilare +# Verifica dei tipi senza compilare bunx tsc --noEmit # Lint @@ -36,15 +36,15 @@ I test unitari si trovano in `__tests__/` e utilizzano [Vitest](https://vitest.d ```text __tests__/ hooks/ - builtin-policies.test.ts # Policy logic per ogni builtin - hooks-config.test.ts # Caricamento config e scope merging - policy-evaluator.test.ts # Param injection e evaluation order - custom-hooks-registry.test.ts # globalThis registry add/get/clear - custom-hooks-loader.test.ts # ESM loader, transitive imports, error handling + builtin-policies.test.ts # Logica delle policy per ciascun builtin + hooks-config.test.ts # Caricamento della configurazione e merge degli scope + policy-evaluator.test.ts # Iniezione dei parametri e ordine di valutazione + custom-hooks-registry.test.ts # Registro globalThis add/get/clear + custom-hooks-loader.test.ts # Loader ESM, import transitivi, gestione errori manager.test.ts # Operazioni install/remove/list components/ - sessions-list.test.tsx # Componente sessions list - project-list.test.tsx # Componente project list + sessions-list.test.tsx # Componente elenco sessioni + project-list.test.tsx # Componente elenco progetti ... lib/ logger.test.ts @@ -61,7 +61,7 @@ __tests__/ AutoRefreshContext.test.tsx ``` -### Scrivere un test unitario per una policy +### Scrittura di un test unitario per una policy ```typescript import { describe, it, expect, beforeEach } from "vitest"; @@ -110,11 +110,11 @@ describe("block-sudo", () => { ## Test end-to-end -I test E2E invocano il vero binario `failproofai` come subprocess, inviano un payload JSON su stdin e verificano l'output su stdout e il codice di uscita. Questo testa il percorso di integrazione completo che Claude Code utilizza. +I test E2E invocano il binario `failproofai` reale come sottoproc, inviano un payload JSON a stdin, e fanno asserzioni sull'output stdout e il codice di uscita. Questo testa il percorso di integrazione completo che Claude Code utilizza. -### Setup +### Configurazione -I test E2E eseguono il binario direttamente dal codice sorgente del repository. Prima della prima esecuzione, compila il bundle CJS che i file di custom hook utilizzano quando importano da `'failproofai'`: +I test E2E eseguono il binario direttamente dalla fonte del repository. Prima della prima esecuzione, compila il bundle CJS che i file dei custom hook utilizzano quando importano da `'failproofai'`: ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -126,33 +126,33 @@ Quindi esegui i test: bun run test:e2e ``` -Ricompila `dist/` ogni volta che modifichi la public hook API (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, o `src/hooks/policy-types.ts`). +Ricompila `dist/` ogni volta che modifichi l'API pubblica dei hook (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts`, o `src/hooks/policy-types.ts`). ### Struttura del test E2E ```text __tests__/e2e/ helpers/ - hook-runner.ts # Spawn del binario, pipe del payload JSON, cattura exit code + stdout + stderr - fixture-env.ts # Directory temporanea isolata per test con file config - payloads.ts # Factory di payload accurati di Claude per ogni event type + hook-runner.ts # Esegui il binario, invia payload JSON, cattura codice di uscita + stdout + stderr + fixture-env.ts # Ambienti temp isolati per test con file di configurazione + payloads.ts # Factory di payload accurati secondo Claude per ogni tipo di evento hooks/ - builtin-policies.e2e.test.ts # Ogni builtin policy con vero subprocess - custom-hooks.e2e.test.ts # Caricamento e valutazione di custom hook - config-scopes.e2e.test.ts # Config merging tra project/local/global - policy-params.e2e.test.ts # Parameter injection per ogni policy parametrizzata + builtin-policies.e2e.test.ts # Ogni policy builtin con sottoproc reale + custom-hooks.e2e.test.ts # Caricamento e valutazione dei custom hook + config-scopes.e2e.test.ts # Merge della configurazione tra project/local/global + policy-params.e2e.test.ts # Iniezione di parametri per ogni policy parametrizzata ``` ### Utilizzo degli helper E2E -**`FixtureEnv`** - ambiente isolato per ogni test: +**`FixtureEnv`** - ambiente isolato per test: ```typescript import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - directory temp; passa come payload.cwd per leggere .failproofai/policies-config.json -// env.home - home dir isolata; nessuna leakage reale da ~/.failproofai +// env.cwd - dir temp; passa come payload.cwd per leggere .failproofai/policies-config.json +// env.home - home dir isolata; nessuna perdita reale di ~/.failproofai env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - factory di payload pronti all'uso: +**`Payloads`** - factory di payload predisposte: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -192,7 +192,7 @@ Payloads.notification(message, cwd) Payloads.stop(cwd) ``` -### Scrivere un test E2E +### Scrittura di un test E2E ```typescript import { describe, it, expect } from "vitest"; @@ -233,28 +233,28 @@ describe("block-rm-rf (E2E)", () => { ### Forme di risposta E2E -| Decisione | Exit code | stdout | -|----------|-----------|--------| +| Decisione | Codice di uscita | stdout | +|-----------|------------------|--------| | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | | Instruct (non-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop instruct | `2` | stdout vuoto; motivo in stderr | +| Stop instruct | `2` | stdout vuoto; ragione in stderr | | Allow | `0` | stringa vuota | -### Config Vitest +### Configurazione di Vitest I test E2E utilizzano `vitest.config.e2e.mts` con: -- `environment: "node"` - nessun browser global necessario -- `pool: "forks"` - vera isolazione dei processi (i test spawnnano subprocess) -- `testTimeout: 20_000` - 20s per test (avvio binario + hook eval) +- `environment: "node"` - nessun globale del browser necessario +- `pool: "forks"` - vera isolazione di processo (i test eseguono sottoproc) +- `testTimeout: 20_000` - 20s per test (avvio binario + valutazione hook) -Il pool `forks` è importante: i worker basati su thread condividono `globalThis`, il che può interferire con i test che spawnnano subprocess. I fork basati su processo evitano questo problema. +Il pool `forks` è importante: i worker basati su thread condividono `globalThis`, che può interferire con i test che invocano sottoproc. I fork basati su processo evitano questo. --- ## CI -L'esecuzione CI completa (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) è richiesta prima del merge. La suite E2E viene eseguita come job CI separato in parallelo. +L'esecuzione completa di CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) è obbligatoria per il merge. La suite E2E viene eseguita come job CI separato in parallelo. -Vedi [Contributing](../CONTRIBUTING.md) per la lista di controllo completa pre-merge. \ No newline at end of file +Vedi [Contributing](../CONTRIBUTING.md) per la checklist completa pre-merge. \ No newline at end of file diff --git a/docs/ja/architecture.mdx b/docs/ja/architecture.mdx index 08f9e352..66f0105c 100644 --- a/docs/ja/architecture.mdx +++ b/docs/ja/architecture.mdx @@ -12,18 +12,18 @@ icon: sitemap failproofai には独立した 2 つのサブシステムがあります。 -1. **フックハンドラー** - Claude Code がエージェントのツール呼び出しごとに起動する高速な CLI サブプロセス。ポリシーを評価して判断を返します。 -2. **エージェントモニター（ダッシュボード）** - エージェントセッションの監視とポリシー管理のための Next.js ウェブアプリケーション。 +1. **フックハンドラー** — エージェントのすべてのツール呼び出しに対して Claude Code が呼び出す高速な CLI サブプロセスです。ポリシーを評価して判定結果を返します。 +2. **エージェントモニター（ダッシュボード）** — エージェントセッションの監視とポリシー管理のための Next.js ウェブアプリケーションです。 -両サブシステムは `~/.failproofai/` とプロジェクトの `.failproofai/` ディレクトリにある設定ファイルを共有しますが、それぞれ独立したプロセスとして動作し、ファイルシステムを通じてのみ通信します。 +両サブシステムは `~/.failproofai/` およびプロジェクトの `.failproofai/` ディレクトリ内の設定ファイルを共有しますが、それぞれ独立したプロセスとして動作し、ファイルシステムを通じてのみ通信します。 --- ## フックハンドラー -### Claude Code との連携 +### Claude Code との統合 -`failproofai policies --install` を実行すると、`~/.claude/settings.json` に以下のようなエントリが書き込まれます。 +`failproofai policies --install` を実行すると、`~/.claude/settings.json` に次のようなエントリが書き込まれます。 ```json { @@ -44,7 +44,7 @@ failproofai には独立した 2 つのサブシステムがあります。 } ``` -Claude Code はツール呼び出しごとに `failproofai --hook PreToolUse` をサブプロセスとして起動し、JSON ペイロードを stdin で渡します。 +Claude Code は各ツール呼び出しの前に `failproofai --hook PreToolUse` をサブプロセスとして起動し、JSON ペイロードを stdin に渡します。 ### ペイロードの形式 @@ -62,11 +62,11 @@ Claude Code はツール呼び出しごとに `failproofai --hook PreToolUse` `PostToolUse` イベントの場合、ペイロードにはツールの出力を含む `tool_result` も含まれます。 -ハンドラーは stdin の上限を 1 MB に制限しています。この上限を超えるペイロードは破棄され、すべてのポリシーが暗黙的に allow となります。 +ハンドラーは stdin の上限を 1 MB に制限しています。これを超えるペイロードは破棄され、すべてのポリシーは暗黙的に allow となります。 ### レスポンスの形式 -**Deny（PreToolUse）：** +**Deny（PreToolUse）:** ```json { "hookSpecificOutput": { @@ -76,7 +76,7 @@ Claude Code はツール呼び出しごとに `failproofai --hook PreToolUse` } ``` -**Deny（PostToolUse）：** +**Deny（PostToolUse）:** ```json { "hookSpecificOutput": { @@ -85,7 +85,7 @@ Claude Code はツール呼び出しごとに `failproofai --hook PreToolUse` } ``` -**Instruct（Stop 以外のイベント）：** +**Instruct（Stop 以外のすべてのイベント）:** ```json { "hookSpecificOutput": { @@ -94,29 +94,29 @@ Claude Code はツール呼び出しごとに `failproofai --hook PreToolUse` } ``` -**Stop イベントの instruct：** -- 終了コード：`2` +**Stop イベントの instruct:** +- 終了コード: `2` - 理由は stdout ではなく stderr に書き込まれます -**Allow：** -- 終了コード：`0` +**Allow:** +- 終了コード: `0` - stdout は空 -**メッセージ付き Allow：** +**Allow（メッセージあり）:** -`allow(message)` を使うと、操作が許可された場合でもポリシーから Claude に情報コンテキストを返すことができます。フックハンドラーは以下の JSON を **stdout** に書き込みます（設定ファイルへの書き込みではなく、deny や instruct と同様に Claude Code へのハンドラーレスポンスです）。 +`allow(message)` を使うと、操作が許可されている場合でも、ポリシーが情報コンテキストを Claude に送り返すことができます。フックハンドラーは以下の JSON を **stdout** に書き込みます（設定ファイルではなく、上記の deny・instruct レスポンスと同様に、Claude Code へのハンドラーの応答です）。 ```json -// フックハンドラープロセスが stdout に書き込む内容 +// フックハンドラープロセスによって stdout に書き込まれます { "hookSpecificOutput": { "additionalContext": "All CI checks passed on branch 'feat/my-feature'." } } ``` -- 終了コード：`0`（操作は許可される） -- 複数のポリシーがメッセージ付きで `allow` を返した場合、それらのメッセージは改行で結合されて単一の `additionalContext` 文字列になります -- いずれのポリシーもメッセージを提供しない場合、stdout は空（従来と同じ動作） +- 終了コード: `0`（操作は許可されます） +- 複数のポリシーがメッセージ付きで `allow` を返した場合、各メッセージは改行で結合されて 1 つの `additionalContext` 文字列になります +- どのポリシーもメッセージを提供しない場合、stdout は空になります（従来と同じ動作） ### 処理パイプライン @@ -124,22 +124,22 @@ Claude Code はツール呼び出しごとに `failproofai --hook PreToolUse` ```text stdin JSON - → ペイロードのパース（最大 1 MB） - → セッションメタデータの抽出（session_id、cwd、tool_name、tool_input など） - → readMergedHooksConfig(cwd) ← プロジェクト + ローカル + グローバル設定をマージ - → 有効な組み込みポリシーをパラメーター解決後に登録 + → ペイロードをパース（最大 1 MB） + → セッションメタデータを抽出（session_id、cwd、tool_name、tool_input など） + → readMergedHooksConfig(cwd) ← プロジェクト・ローカル・グローバル設定をマージ + → 有効な組み込みポリシーを解決済みパラメーターで登録 → customPoliciesPath からカスタムポリシーを読み込み（設定されている場合） → カスタムポリシーをポリシーレジストリに登録 - → すべてのポリシーを評価（組み込みを先に、その後カスタムを） - → 最初の deny で短絡 - → instruct の判断は蓄積 - → allow メッセージは蓄積 - → JSON 判断を stdout に書き込み + → すべてのポリシーを評価（組み込みポリシーを先に、次にカスタムポリシー） + → 最初の deny で短絡評価 + → instruct の判定は蓄積される + → allow メッセージは蓄積される + → JSON の判定結果を stdout に書き込む → イベントを ~/.failproofai/hook-activity.jsonl に永続化 → 終了 ``` -LLM 呼び出しなしで、典型的なペイロードの処理は 100ms 以内に完了します。 +LLM 呼び出しなしで、典型的なペイロードに対して全処理が 100ms 未満で完了します。 --- @@ -153,40 +153,40 @@ LLM 呼び出しなしで、典型的なペイロードの処理は 100ms 以内 [3] ~/.failproofai/policies-config.json ← グローバル（最低優先度） ``` -マージのロジック： -- `enabledPolicies` - 3 つのファイルにわたって重複排除した和集合 -- `policyParams` - ポリシーキーごとに、最初に定義したファイルが完全に優先 -- `customPoliciesPath` - 最初に定義したファイルが優先 -- `llm` - 最初に定義したファイルが優先 +マージのロジック: +- `enabledPolicies` — 3 つのファイル全体にわたって重複を排除したユニオン +- `policyParams` — ポリシーごとのキーで、最初に定義したファイルが完全に優先されます +- `customPoliciesPath` — 最初に定義したファイルが優先されます +- `llm` — 最初に定義したファイルが優先されます -ウェブダッシュボードはプロジェクトの cwd を持たないため、読み取りと書き込みには `readHooksConfig()`（グローバルのみ）を使用します。 +ウェブダッシュボードはプロジェクトの cwd を指定せずに起動されるため、読み書きには `readHooksConfig()`（グローバルのみ）を使用します。 --- -## ポリシーの評価 +## ポリシー評価 `src/hooks/policy-evaluator.ts` がポリシーを順番に実行します。 -各ポリシーについて： +各ポリシーに対して: 1. ポリシーの `params` スキーマを参照します（存在する場合）。 2. マージ済み設定から `policyParams[policy.name]` を読み取ります。 3. ユーザー指定の値をスキーマのデフォルト値にマージして `ctx.params` を生成します。 -4. 解決されたコンテキストを使って `policy.fn(ctx)` を呼び出します。 -5. 結果が `deny` の場合、即座に停止してその判断を返します。 -6. 結果が `instruct` の場合、メッセージを蓄積して処理を続行します。 -7. 結果が `allow` の場合、次のポリシーへ進みます。 +4. 解決済みコンテキストで `policy.fn(ctx)` を呼び出します。 +5. 結果が `deny` の場合、直ちに処理を停止してその判定を返します。 +6. 結果が `instruct` の場合、メッセージを蓄積して次のポリシーに進みます。 +7. 結果が `allow` の場合、次のポリシーに進みます。 -すべてのポリシーの実行後： +すべてのポリシーの実行後: - `deny` が返された場合、deny レスポンスを出力します。 - `instruct` が収集された場合、すべてのメッセージを結合した単一の instruct レスポンスを出力します。 -- それ以外の場合、allow レスポンス（stdout 空、終了コード 0）を出力します。 +- それ以外の場合、allow レスポンスを出力します（stdout 空、終了コード 0）。 --- ## 組み込みポリシー -`src/hooks/builtin-policies.ts` が 39 個の組み込みポリシーを `BuiltinPolicyDefinition` オブジェクトとして定義しています。 +`src/hooks/builtin-policies.ts` が 39 個の組み込みポリシーをすべて `BuiltinPolicyDefinition` オブジェクトとして定義しています。 ```typescript interface BuiltinPolicyDefinition { @@ -204,15 +204,15 @@ interface BuiltinPolicyDefinition { } ``` -`params` を受け取るポリシーは、各パラメーターの型とデフォルト値を持つ `PolicyParamsSchema` を宣言します。ポリシー評価器は `fn` を呼び出す前に解決済みの値を `ctx.params` に注入します。デフォルト値は常に先に適用されるため、ポリシー関数は null チェックなしで `ctx.params` を読み取れます。 +`params` を受け取るポリシーは、各パラメーターの型とデフォルト値を含む `PolicyParamsSchema` を宣言します。ポリシーエバリュエーターは `fn` を呼び出す前に解決済みの値を `ctx.params` に注入します。デフォルト値は常に先に適用されるため、ポリシー関数は null チェックなしで `ctx.params` を読み取ることができます。 -ポリシー内のパターンマッチングは生の文字列マッチングではなく、解析済みのコマンドトークン（argv）を使用します。これにより、シェル演算子インジェクションによるバイパスを防ぎます（例：`sudo systemctl status *` というパターンは、コマンドに `; rm -rf /` を追加しても迂回できません）。 +ポリシー内のパターンマッチングは、生の文字列マッチングではなく、解析済みのコマンドトークン（argv）を使用します。これにより、シェル演算子のインジェクションによるバイパスを防止します（例: `sudo systemctl status *` というパターンは、コマンドに `; rm -rf /` を追加してもバイパスできません）。 --- ## カスタムポリシー -`src/hooks/custom-hooks-registry.ts` が `globalThis` を使ったレジストリを実装しています。 +`src/hooks/custom-hooks-registry.ts` が `globalThis` をバックエンドとしたレジストリを実装しています。 ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -222,28 +222,28 @@ export const customPolicies = { }; export function getCustomHooks(): CustomHook[] { ... } -export function clearCustomHooks(): void { ... } // テスト用 +export function clearCustomHooks(): void { ... } // テストで使用 ``` `src/hooks/custom-hooks-loader.ts` がユーザーのポリシーファイルを読み込みます。 -1. 設定から `customPoliciesPath` を読み取り、存在しない場合はスキップします。 -2. 絶対パスに解決してファイルの存在を確認します。 +1. 設定から `customPoliciesPath` を読み取り、未設定の場合はスキップします。 +2. 絶対パスに解決し、ファイルの存在を確認します。 3. すべての `from "failproofai"` インポートを実際の dist パスに書き換え、`customPolicies` が同じ `globalThis` レジストリに解決されるようにします。 -4. ESM 互換性を確保するため、推移的なローカルインポートを再帰的に書き換えます。 -5. 一時的な `.mjs` ファイルを書き出し、エントリファイルを `import()` します。 +4. ESM 互換性を確保するため、推移的なローカルインポートも再帰的に書き換えます。 +5. 一時的な `.mjs` ファイルを生成し、エントリファイルを `import()` します。 6. `getCustomHooks()` を呼び出して登録済みフックを取得します。 7. `finally` ブロックですべての一時ファイルを削除します。 -エラーが発生した場合（ファイルが見つからない、構文エラー、インポート失敗など）、エラーは `~/.failproofai/hook.log` に記録され、ローダーは空の配列を返します。組み込みポリシーへの影響はありません。 +エラー（ファイルが見つからない、構文エラー、インポート失敗など）が発生した場合、エラーは `~/.failproofai/hook.log` に記録され、ローダーは空の配列を返します。組み込みポリシーには影響しません。 -カスタムポリシーはすべての組み込みポリシーの後に評価されます。カスタムポリシーの `deny` はそれ以降のカスタムポリシーを短絡させますが（その時点ではすべての組み込みポリシーはすでに実行済みです）。 +カスタムポリシーはすべての組み込みポリシーの後に評価されます。カスタムポリシーの `deny` はそれ以降のカスタムポリシーの評価を短絡しますが、組み込みポリシーはすでに実行済みです。 --- -## アクティビティのログ記録 +## アクティビティログ -各フックイベントの後、ハンドラーは JSONL の 1 行を `~/.failproofai/hook-activity.jsonl` に追記します。 +各フックイベントの後、ハンドラーは `~/.failproofai/hook-activity.jsonl` に JSONL 行を追記します。 ```json { @@ -258,22 +258,22 @@ export function clearCustomHooks(): void { ... } // テスト用 } ``` -非 allow の判断をしたポリシーごとに 1 行記録されます。allow の判断はファイルサイズを抑えるため記録されません。 +allow 以外の判定を下したポリシーごとに 1 行記録されます。ファイルサイズを抑えるため、allow の判定はログに記録されません。 --- ## ダッシュボードのアーキテクチャ -ダッシュボードは App Router を使用した **Next.js 16** アプリケーションで、React Server Components と Server Actions を採用しています。 +ダッシュボードは、App Router・React Server Components・Server Actions を使用した **Next.js 16** アプリケーションです。 ```text app/ layout.tsx ← ルートレイアウト（テーマ、テレメトリー、ナビゲーション） - projects/page.tsx ← サーバーコンポーネント：Claude プロジェクトの一覧 - project/[name]/page.tsx ← サーバーコンポーネント：プロジェクト内のセッション一覧 + projects/page.tsx ← サーバーコンポーネント: すべての Claude プロジェクトを一覧表示 + project/[name]/page.tsx ← サーバーコンポーネント: プロジェクト内のセッションを一覧表示 project/[name]/session/ - [sessionId]/page.tsx ← サーバーコンポーネント：セッションビューアーの表示 - policies/page.tsx ← クライアントコンポーネント：ポリシー管理 + アクティビティログ + [sessionId]/page.tsx ← サーバーコンポーネント: セッションビューアーを表示 + policies/page.tsx ← クライアントコンポーネント: ポリシー管理 + アクティビティログ actions/ get-hooks-config.ts ← 設定とポリシー一覧の読み取り update-hooks-config.ts ← ポリシーの有効/無効の切り替え @@ -284,18 +284,18 @@ app/ download/[project]/[session]/route.ts ← CLI セッションごとのエクスポート（JSONL または JSON） ``` -**データフロー：** +**データフロー:** -- ページコンポーネントは `lib/projects.ts` と `lib/log-entries.ts` を呼び出して、ファイルシステムから直接プロジェクト/セッションデータを読み取ります（読み取りに API レイヤーなし）。 +- ページコンポーネントは `lib/projects.ts` と `lib/log-entries.ts` を呼び出し、ファイルシステムから直接プロジェクト/セッションデータを読み取ります（読み取りに API レイヤーは不要）。 - Policies ページはすべての変更操作（切り替え、パラメーター更新、インストール/削除）に Server Actions を使用します。 -- セッションビューアーは Claude の JSONL トランスクリプト形式をパースし、メッセージとツール呼び出しのタイムラインを描画します。 +- セッションビューアーは Claude の JSONL トランスクリプト形式をパースし、メッセージとツール呼び出しのタイムラインを表示します。 -**主要な設計方針：** +**主な設計上の判断:** -- データベースなし - すべての永続状態はプレーンファイル（`~/.failproofai/`、`~/.claude/projects/`）に保存 -- 変更操作に Server Actions を使用 - CRUD 操作に REST API が不要 -- 読み取りページに React Server Components を使用 - 初期表示が高速でデータフェッチのクライアントバンドルが不要 -- インタラクティビティが必要な箇所にのみクライアントコンポーネントを使用（ポリシーの切り替え、アクティビティ検索、ログビューアー） +- データベースなし — すべての永続状態はプレーンファイル（`~/.failproofai/`、`~/.claude/projects/`）に保存されます。 +- 変更操作には Server Actions を使用 — CRUD 操作に REST API は不要です。 +- 読み取りページには React Server Components を使用 — 初期ロードが高速で、データフェッチのクライアントバンドルが不要です。 +- クライアントコンポーネントはインタラクティブな操作が必要な箇所のみ使用（ポリシーの切り替え、アクティビティ検索、ログビューアー）。 --- @@ -304,22 +304,22 @@ app/ ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # CLI ルーター（フック / ダッシュボード / インストール など） +│ └── failproofai.mjs # CLI ルーター（hook / dashboard / install など） ├── src/hooks/ │ ├── handler.ts # フックイベントパイプライン │ ├── builtin-policies.ts # 39 個のポリシー定義 │ ├── policy-evaluator.ts # ポリシー実行エンジン -│ ├── policy-registry.ts # ポリシーの登録と参照 +│ ├── policy-registry.ts # ポリシーの登録と検索 │ ├── policy-types.ts # TypeScript インターフェース -│ ├── hooks-config.ts # マルチスコープ設定の読み込み -│ ├── custom-hooks-registry.ts # globalThis を使ったフックレジストリ +│ ├── hooks-config.ts # マルチスコープの設定読み込み +│ ├── custom-hooks-registry.ts # globalThis をバックエンドとしたフックレジストリ │ ├── custom-hooks-loader.ts # ユーザー JS フック用の ESM ローダー -│ ├── manager.ts # インストール / 削除 / 一覧操作 +│ ├── manager.ts # インストール / 削除 / 一覧表示操作 │ ├── install-prompt.ts # インタラクティブなポリシー選択プロンプト │ ├── hook-logger.ts # hook.log へのログ記録 │ ├── hook-activity-store.ts # hook-activity.jsonl へのアクティビティ永続化 │ └── llm-client.ts # LLM API クライアント（AI 駆動ポリシー用） -├── app/ # Next.js ダッシュボード（ページ + サーバーアクション） +├── app/ # Next.js ダッシュボード（ページ + Server Actions） ├── lib/ # 共有ユーティリティ │ ├── projects.ts # ファイルシステムから Claude プロジェクトを列挙 │ ├── log-entries.ts # Claude トランスクリプト JSONL 形式のパース @@ -328,5 +328,5 @@ failproofai/ ├── components/ # 共有 React UI コンポーネント ├── contexts/ # React コンテキストプロバイダー（テーマ、自動更新、テレメトリー） ├── examples/ # カスタムフックのサンプルファイル -└── __tests__/ # ユニットテストと E2E テスト +└── __tests__/ # ユニットテストおよび E2E テスト ``` \ No newline at end of file diff --git a/docs/ja/built-in-policies.mdx b/docs/ja/built-in-policies.mdx index 3017b25f..6467ffa8 100644 --- a/docs/ja/built-in-policies.mdx +++ b/docs/ja/built-in-policies.mdx @@ -1,16 +1,16 @@ --- title: 組み込みポリシー -description: "エージェントの一般的な失敗パターンを検出する39個の組み込みポリシー" +description: "エージェントの一般的な障害モードを検出する39の組み込みポリシー" icon: shield --- -failproofai には、エージェントの一般的な失敗パターンを検出する39個の組み込みポリシーが含まれています。各ポリシーは特定のフックイベントタイプとツール名に対して発火します。19個のポリシーはパラメーターを受け付け、コードを書かずに動作を調整できます。5つのワークフローポリシーは、Claude が停止する前にコミット → プッシュ → PR → CI のパイプラインを強制します。 +failproofai には、エージェントの一般的な障害モードを検出する39の組み込みポリシーが同梱されています。各ポリシーは特定のフックイベントタイプとツール名に対して発火します。19のポリシーはパラメーターを受け付けており、コードを書くことなく動作を調整できます。5つのワークフローポリシーは、Claude が停止する前にコミット → プッシュ → PR → CI のパイプラインを強制します。 --- ## 概要 -ポリシーはカテゴリごとにグループ化されています： +ポリシーはカテゴリ別にグループ化されています： | カテゴリ | ポリシー | フックタイプ | |----------|----------|-----------| @@ -25,15 +25,15 @@ failproofai には、エージェントの一般的な失敗パターンを検 | [パッケージマネージャー](#package-managers) | prefer-package-manager | PreToolUse | | [ワークフロー](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — エージェントの処理を停止します。 -- **`warn-`** — エージェントが自己修正できるよう追加のコンテキストを提供します。 -- **`sanitize-`** — エージェントが参照する前にツール出力から機密データを除去します。 +- **`block-`** — エージェントの処理を停止する。 +- **`warn-`** — エージェントが自己修正できるよう追加のコンテキストを提供する。 +- **`sanitize-`** — エージェントが確認する前にツール出力から機密データを除去する。 ### 名前空間 -すべてのポリシーは `/` のスロットに存在します。組み込みポリシーは **`failproofai/`** 名前空間に属します。例：`failproofai/sanitize-jwt`。名前空間により、短い名前が似ているカスタムポリシーやサードパーティポリシーを同時に読み込んでも衝突を防ぎます。 +すべてのポリシーは `<名前空間>/<名前>` というスロットに存在します。組み込みポリシーは **`failproofai/`** 名前空間に属しています（例：`failproofai/sanitize-jwt`）。名前空間により、類似した短い名前のカスタムポリシーやサードパーティポリシーを読み込む際の衝突を防ぎます。 -設定ファイルでは、短い名前または完全修飾名のどちらでも組み込みポリシーを参照できます。どちらの形式も同じポリシーに解決されます： +設定ファイルでは、組み込みポリシーを短縮名または完全修飾名のどちらでも参照でき、両方の形式が同じポリシーに解決されます： ```json { @@ -44,35 +44,35 @@ failproofai には、エージェントの一般的な失敗パターンを検 } ``` -名前に `/` が含まれない場合、failproofai はデフォルト名前空間 `failproofai` に属するものとして扱います。すでに `/` を含む名前（例：`myorg/foo`、`custom/my-hook`）はそのまま保持されます。 -- **`require-`** — 条件が満たされるまで Stop イベントをブロックします。 +名前に `/` が含まれない場合、failproofai はそれをデフォルト名前空間 `failproofai` に属するものとして扱います。すでに `/` を含む名前（例：`myorg/foo`、`custom/my-hook`）はそのまま保持されます。 +- **`require-`** — 条件が満たされるまで Stop イベントをブロックする。 --- -すべてのポリシーは `policyParams` でオプションの `hint` フィールドをサポートしています。hint は Claude が受け取る deny または instruct メッセージに追記され、ポリシーコードを変更せずに実行可能なガイダンスを提供します。組み込み、カスタム、コンベンションポリシーのいずれでも動作します。詳細は [設定 → hint](/ja/configuration#hint-cross-cutting) を参照してください。 +すべてのポリシーは `policyParams` にオプションの `hint` フィールドをサポートします。ヒントは Claude が受け取る deny または instruct メッセージに追加され、ポリシーコードを変更せずに実用的なガイダンスを提供します。組み込み・カスタム・規約ポリシーのすべてで機能します。詳細は[設定 → hint](/ja/configuration#hint-cross-cutting)を参照してください。 --- -## 危険なコマンド +## 危険なコマンド {#dangerous-commands} -元に戻しにくい操作やホストシステムに損害を与えかねない操作をエージェントが実行するのを防ぎます。 +取り消しが困難な操作や、ホストシステムに損害を与える可能性のある操作をエージェントが実行するのを防ぎます。 ### `block-sudo` -**イベント:** PreToolUse (Bash) -**デフォルト:** `sudo` コマンドを含むすべての実行を拒否します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `sudo` コマンドを含む任意のコマンドを拒否します。 -`sudo` キーワードを含む実行をブロックします。パターンマッチングは生の文字列ではなく、解析済みのコマンドトークンに対して行われるため、シェルオペレーターインジェクションによる回避を防ぎます。 +`sudo` キーワードを含む呼び出しをブロックします。パターンマッチングは生の文字列ではなく解析済みのコマンドトークンに対して行われるため、シェル演算子インジェクションによる回避を防ぎます。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 許可する正確なコマンドプレフィックス。各エントリは解析済みの argv トークンに対してマッチングされます。 | +| `allowPatterns` | `string[]` | `[]` | 許可されるコマンドの正確なプレフィックス。各エントリは解析済みの argv トークンと照合されます。 | -**例:** +**例：** ```json { @@ -84,26 +84,26 @@ failproofai には、エージェントの一般的な失敗パターンを検 } ``` -この設定では `sudo systemctl status nginx` は許可されますが、`sudo rm /etc/hosts` は拒否されます。 +この設定では、`sudo systemctl status nginx` は許可されますが、`sudo rm /etc/hosts` は拒否されます。 -パターンは生のコマンド文字列ではなく、解析済みトークンに対してマッチングされます。これにより、末尾に追加されたシェルオペレーターを使った回避を防ぎます（例：`sudo systemctl status x; rm -rf /` は `sudo systemctl status *` にマッチしません）。 +パターンは生のコマンド文字列ではなく解析済みトークンと照合されます。これにより、追加されたシェル演算子による回避を防ぎます（例：`sudo systemctl status x; rm -rf /` は `sudo systemctl status *` にマッチしません）。 --- ### `block-rm-rf` -**イベント:** PreToolUse (Bash) -**デフォルト:** `rm -rf`、`rm -fr`、および同様の再帰的削除の形式を拒否します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `rm -rf`、`rm -fr`、および類似の再帰的削除形式を拒否します。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| | `allowPaths` | `string[]` | `[]` | 再帰的削除が安全なパス（例：`/tmp`）。 | -**例:** +**例：** ```json { @@ -119,8 +119,8 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `block-curl-pipe-sh` -**イベント:** PreToolUse (Bash) -**デフォルト:** `curl | bash`、`curl | sh`、`wget | bash`、および同様のパターンを拒否します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `curl | bash`、`curl | sh`、`wget | bash`、および類似のパターンを拒否します。 パラメーターなし。 @@ -128,31 +128,31 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `block-failproofai-commands` -**イベント:** PreToolUse (Bash) -**デフォルト:** failproofai 自体をアンインストールまたは無効化するコマンドを拒否します（例：`npm uninstall failproofai`、`failproofai policies --uninstall`）。 +**イベント：** PreToolUse (Bash) +**デフォルト：** failproofai 自体をアンインストールまたは無効化するコマンド（例：`npm uninstall failproofai`、`failproofai policies --uninstall`）を拒否します。 パラメーターなし。 --- -## インフラコマンド +## インフラコマンド {#infra-commands} -コーディングエージェントがインフラ CLI を実行したり CI/CD パイプラインをトリガーしたりするのを防ぎます。このカテゴリのすべてのポリシーは **オプトイン**（`defaultEnabled: false`）です。`kubectl`、`terraform` などを正当に呼び出す必要があるエージェントは、ポリシーを有効化しない限り影響を受けません。有効化すると、`allowPatterns` のエントリとマッチしない限り、マッチした CLI のすべての呼び出しが拒否されます。 +コーディングエージェントがインフラ CLI を実行したり、CI/CD パイプラインをトリガーしたりするのを停止します。このカテゴリのすべてのポリシーは**オプトイン**（`defaultEnabled: false`）です。正当に `kubectl` や `terraform` などを呼び出す必要があるエージェントは、ポリシーを有効にしない限り影響を受けません。有効にすると、コマンドが `allowPatterns` のエントリにマッチしない限り、マッチした CLI のすべての呼び出しが拒否されます。 -パターン文法は [`block-sudo`](#block-sudo) と同じです：トークンは解析済みの argv に対してマッチングされ、`*` は1トークンのワイルドカードです。スタンドアロンのシェルオペレーター（`&&`、`||`、`|`、`;`）を含むコマンドや、シェルメタキャラクターが埋め込まれたトークンを含むコマンドは、インジェクション回避を防ぐためにアローリストマッチングの前に拒否されます。 +パターン文法は [`block-sudo`](#block-sudo) と同じです：トークンは解析済みの argv と照合され、`*` は1つのトークンのワイルドカードです。また、スタンドアロンのシェル演算子（`&&`、`||`、`|`、`;`）を含むコマンドや、埋め込まれたシェルメタ文字を含むトークンは、インジェクション回避を防ぐためにアローリストマッチングの前に拒否されます。 ### `block-kubectl` -**イベント:** PreToolUse (Bash) -**デフォルト:** すべての `kubectl` 呼び出しを拒否します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `kubectl` の任意の呼び出しを拒否します。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 許可する kubectl コマンドプレフィックス。 | +| `allowPatterns` | `string[]` | `[]` | 許可される kubectl コマンドプレフィックス。 | -**例:** +**例：** ```json { @@ -164,22 +164,22 @@ failproofai には、エージェントの一般的な失敗パターンを検 } ``` -この設定では `kubectl get pods` は許可されますが、`kubectl apply -f deploy.yaml` は拒否されます。 +この設定では、`kubectl get pods` は許可されますが、`kubectl apply -f deploy.yaml` は拒否されます。 --- ### `block-terraform` -**イベント:** PreToolUse (Bash) -**デフォルト:** すべての `terraform` または `tofu`（OpenTofu）呼び出しを拒否します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `terraform` または `tofu`（OpenTofu）の任意の呼び出しを拒否します。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 許可する terraform/tofu コマンドプレフィックス。 | +| `allowPatterns` | `string[]` | `[]` | 許可される terraform/tofu コマンドプレフィックス。 | -**例:** +**例：** ```json { @@ -195,16 +195,16 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `block-aws-cli` -**イベント:** PreToolUse (Bash) -**デフォルト:** すべての `aws` CLI 呼び出しを拒否します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `aws` CLI の任意の呼び出しを拒否します。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 許可する aws CLI コマンドプレフィックス。 | +| `allowPatterns` | `string[]` | `[]` | 許可される aws CLI コマンドプレフィックス。 | -**例:** +**例：** ```json { @@ -220,16 +220,16 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `block-gcloud` -**イベント:** PreToolUse (Bash) -**デフォルト:** すべての `gcloud`（Google Cloud）CLI 呼び出しを拒否します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `gcloud`（Google Cloud）CLI の任意の呼び出しを拒否します。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 許可する gcloud コマンドプレフィックス。 | +| `allowPatterns` | `string[]` | `[]` | 許可される gcloud コマンドプレフィックス。 | -**例:** +**例：** ```json { @@ -245,16 +245,16 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `block-az-cli` -**イベント:** PreToolUse (Bash) -**デフォルト:** すべての `az`（Azure）CLI 呼び出しを拒否します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `az`（Azure）CLI の任意の呼び出しを拒否します。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 許可する az CLI コマンドプレフィックス。 | +| `allowPatterns` | `string[]` | `[]` | 許可される az CLI コマンドプレフィックス。 | -**例:** +**例：** ```json { @@ -270,16 +270,16 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `block-helm` -**イベント:** PreToolUse (Bash) -**デフォルト:** すべての `helm` 呼び出しを拒否します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `helm` の任意の呼び出しを拒否します。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 許可する helm コマンドプレフィックス。 | +| `allowPatterns` | `string[]` | `[]` | 許可される helm コマンドプレフィックス。 | -**例:** +**例：** ```json { @@ -295,8 +295,8 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `block-gh-pipeline` -**イベント:** PreToolUse (Bash) -**デフォルト:** 状態を変更するかパイプラインをトリガーする以下の `gh` CLI サブコマンドを拒否します： +**イベント：** PreToolUse (Bash) +**デフォルト：** 状態を変更したりパイプラインをトリガーしたりする以下の `gh` CLI サブコマンドを拒否します： - `gh workflow run`、`gh workflow enable`、`gh workflow disable` - `gh run rerun`、`gh run cancel` @@ -305,15 +305,15 @@ failproofai には、エージェントの一般的な失敗パターンを検 - `gh cache delete` - `gh secret set`、`gh secret delete` -`gh pr view`、`gh pr list`、`gh run list`、`gh release view`、`gh api repos/.../...` などの読み取り専用 `gh` サブコマンドは、このポリシーにマッチ**しません**。これらは failproofai 自身の `require-ci-green-before-stop` を含むワークフローチェックで日常的に必要とされます。 +`gh pr view`、`gh pr list`、`gh run list`、`gh release view`、`gh api repos/.../...` などの読み取り専用の `gh` サブコマンドは、このポリシーの対象外です。これらはワークフローの確認（failproofai 自身の `require-ci-green-before-stop` を含む）に日常的に必要とされます。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| | `allowPatterns` | `string[]` | `[]` | 通常は拒否される場合でも許可する特定のスクリプト化された呼び出し。 | -**例:** +**例：** ```json { @@ -327,14 +327,14 @@ failproofai には、エージェントの一般的な失敗パターンを検 --- -## シークレット（サニタイザー） +## シークレット（サニタイザー） {#secrets-sanitizers} -エージェントが認証情報をコンテキストや出力に漏洩させるのを防ぎます。サニタイザーポリシーは **PostToolUse** イベントで発火します。Claude が Bash コマンドを実行したり、ファイルを読んだり、ツールを呼び出したりすると、これらのポリシーは Claude に返される前に出力を検査します。シークレットパターンが検出された場合、ポリシーは出力が返されるのを防ぐ deny 決定を返します。 +エージェントが認証情報をコンテキストや出力に漏洩させるのを防ぎます。サニタイザーポリシーは **PostToolUse** イベントで発火します。Claude が Bash コマンドを実行したり、ファイルを読み込んだり、ツールを呼び出したりすると、これらのポリシーは出力が Claude に返される前に検査します。シークレットパターンが検出された場合、ポリシーは出力が返されるのを防ぐ deny 決定を返します。 ### `sanitize-jwt` -**イベント:** PostToolUse（すべてのツール） -**デフォルト:** JWT トークン（`.` で区切られた3つの base64url セグメント）を削除します。 +**イベント：** PostToolUse（全ツール） +**デフォルト：** JWT トークン（`.` で区切られた3つの base64url セグメント）を削除します。 パラメーターなし。 @@ -342,16 +342,16 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `sanitize-api-keys` -**イベント:** PostToolUse（すべてのツール） -**デフォルト:** 一般的な API キー形式を削除します：Anthropic（`sk-ant-`）、OpenAI（`sk-`）、GitHub PAT（`ghp_`）、AWS アクセスキー（`AKIA`）、Stripe キー（`sk_live_`、`sk_test_`）、Google API キー（`AIza`）。 +**イベント：** PostToolUse（全ツール） +**デフォルト：** 一般的な API キー形式を削除します：Anthropic（`sk-ant-`）、OpenAI（`sk-`）、GitHub PAT（`ghp_`）、AWS アクセスキー（`AKIA`）、Stripe キー（`sk_live_`、`sk_test_`）、Google API キー（`AIza`）。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| | `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | シークレットとして扱う追加の正規表現パターン。 | -**例:** +**例：** ```json { @@ -370,8 +370,8 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `sanitize-connection-strings` -**イベント:** PostToolUse（すべてのツール） -**デフォルト:** 認証情報が埋め込まれたデータベース接続文字列を削除します（例：`postgresql://user:password@host/db`）。 +**イベント：** PostToolUse（全ツール） +**デフォルト：** 認証情報が埋め込まれたデータベース接続文字列（例：`postgresql://user:password@host/db`）を削除します。 パラメーターなし。 @@ -379,8 +379,8 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `sanitize-private-key-content` -**イベント:** PostToolUse（すべてのツール） -**デフォルト:** PEM ブロック（`-----BEGIN PRIVATE KEY-----`、`-----BEGIN RSA PRIVATE KEY-----` など）を削除します。 +**イベント：** PostToolUse（全ツール） +**デフォルト：** PEM ブロック（`-----BEGIN PRIVATE KEY-----`、`-----BEGIN RSA PRIVATE KEY-----` など）を削除します。 パラメーターなし。 @@ -388,23 +388,23 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `sanitize-bearer-tokens` -**イベント:** PostToolUse（すべてのツール） -**デフォルト:** トークンが20文字以上の `Authorization: Bearer ` ヘッダーを削除します。 +**イベント：** PostToolUse（全ツール） +**デフォルト：** トークンが20文字以上の `Authorization: Bearer ` ヘッダーを削除します。 パラメーターなし。 --- -## 環境 +## 環境 {#environment} -機密性の高い環境設定がエージェントによって読み取られたり公開されたりするのを防ぎます。 +エージェントによる機密環境設定の読み取りや露出を防ぎます。 ### `block-env-files` -**イベント:** PreToolUse (Bash, Read) -**デフォルト:** `cat .env` や、`.env` をファイルパスとして指定した `Read` ツール呼び出しなどによる `.env` ファイルの読み取りを拒否します。 +**イベント：** PreToolUse (Bash, Read) +**デフォルト：** `cat .env` や `.env` をファイルパスとして指定した `Read` ツール呼び出しなど、`.env` ファイルの読み取りを拒否します。 -`.envrc` やその他の環境関連ファイルはブロックしません。正確に `.env` という名前のファイルのみが対象です。 +`.envrc` やその他の環境関連ファイルはブロックせず、正確に `.env` という名前のファイルのみを対象とします。 パラメーターなし。 @@ -412,29 +412,29 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `protect-env-vars` -**イベント:** PreToolUse (Bash) -**デフォルト:** 環境変数を表示するコマンドを拒否します：`printenv`、`env`、`echo $VAR`。 +**イベント：** PreToolUse (Bash) +**デフォルト：** 環境変数を表示するコマンド（`printenv`、`env`、`echo $VAR`）を拒否します。 パラメーターなし。 --- -## ファイルアクセス +## ファイルアクセス {#file-access} -エージェントをプロジェクト境界内で作業させ、機密ファイルへのアクセスを防ぎます。 +エージェントをプロジェクトの境界内に留め、機密ファイルへのアクセスを防ぎます。 ### `block-read-outside-cwd` -**イベント:** PreToolUse (Read, Bash) -**デフォルト:** プロジェクトルート外のファイルの読み取りを拒否します。境界は `CLAUDE_PROJECT_DIR`（Claude Code がセッションごとに1回設定）で、この変数が未設定の場合はセッションの現在の作業ディレクトリにフォールバックします。ライブの `cwd` ではなくプロジェクトルートを使用することで、Claude がサブディレクトリに `cd` した後も境界が安定したままになります。 +**イベント：** PreToolUse (Read, Bash) +**デフォルト：** プロジェクトルート外のファイル読み取りを拒否します。境界は `CLAUDE_PROJECT_DIR`（Claude Code がセッションごとに1回設定）で、この変数が未設定の場合はセッションの現在の作業ディレクトリにフォールバックします。ライブの `cwd` ではなくプロジェクトルートを使用することで、Claude がサブディレクトリに `cd` した後も境界が安定したまま保たれます。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | プロジェクトルート外であっても許可する絶対パスプレフィックス。 | +| `allowPaths` | `string[]` | `[]` | プロジェクトルート外であっても許可される絶対パスプレフィックス。 | -**例:** +**例：** ```json { @@ -450,16 +450,16 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `block-secrets-write` -**イベント:** PreToolUse (Write, Edit) -**デフォルト:** 秘密鍵と証明書に一般的に使用されるファイルへの書き込みを拒否します：`id_rsa`、`id_ed25519`、`*.key`、`*.pem`、`*.p12`、`*.pfx`。 +**イベント：** PreToolUse (Write, Edit) +**デフォルト：** 秘密鍵や証明書によく使用されるファイルへの書き込みを拒否します：`id_rsa`、`id_ed25519`、`*.key`、`*.pem`、`*.p12`、`*.pfx`。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| | `additionalPatterns` | `string[]` | `[]` | ブロックする追加のファイル名パターン（グロブ形式）。 | -**例:** +**例：** ```json { @@ -473,22 +473,22 @@ failproofai には、エージェントの一般的な失敗パターンを検 --- -## Git +## Git {#git} -元に戻しにくい誤ったプッシュ、強制プッシュ、ブランチ操作ミスを防ぎます。 +取り消しが困難な誤ったプッシュ、強制プッシュ、ブランチミスを防ぎます。 ### `block-push-master` -**イベント:** PreToolUse (Bash) -**デフォルト:** `git push origin main` および `git push origin master` を拒否します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `git push origin main` および `git push origin master` を拒否します。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| | `protectedBranches` | `string[]` | `["main", "master"]` | 直接プッシュできないブランチ名。 | -**例:** +**例：** ```json { @@ -501,30 +501,30 @@ failproofai には、エージェントの一般的な失敗パターンを検 ``` -すべてのブランチへのプッシュを許可する場合（`enabledPolicies` からポリシーを削除せずに実質的に無効化する）、`protectedBranches: []` を設定してください。 +すべてのブランチへのプッシュを許可する（`enabledPolicies` からポリシーを削除せずに実質的に無効化する）には、`protectedBranches: []` を設定してください。 --- ### `block-work-on-main` -**イベント:** PreToolUse (Bash) -**デフォルト:** 作業ツリーが `main` または `master` にある状態での `git commit`、`git merge`、`git rebase`、`git cherry-pick` を拒否します。ブランチの作成と切り替え（`git checkout`、`git checkout -b`、`git switch`、`git switch -c`）は影響を受けません。 +**イベント：** PreToolUse (Bash) +**デフォルト：** ワーキングツリーが `main` または `master` 上にある場合、`git commit`、`git merge`、`git rebase`、`git cherry-pick` を拒否します。ブランチの作成と切り替え（`git checkout`、`git checkout -b`、`git switch`、`git switch -c`）は影響を受けません。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | commit/merge/rebase/cherry-pick を拒否するブランチ名。 | +| `protectedBranches` | `string[]` | `["main", "master"]` | commit/merge/rebase/cherry-pick が拒否されるブランチ名。 | --- ### `block-force-push` -**イベント:** PreToolUse (Bash) -**デフォルト:** `git push --force` および `git push -f` を拒否します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `git push --force` および `git push -f` を拒否します。 -ポリシー固有のパラメーターはありません。代替手段を提示するには、汎用の [`hint`](/ja/configuration#hint-cross-cutting) を使用してください： +ポリシー固有のパラメーターはありません。代替案を提案するには、共通の [`hint`](/ja/configuration#hint-cross-cutting) を使用してください： ```json { @@ -540,8 +540,8 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `warn-git-amend` -**イベント:** PreToolUse (Bash) -**デフォルト:** `git commit --amend` を実行する際に、慎重に進むよう Claude に指示します。コマンドはブロックしません。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `git commit --amend` を実行する際に慎重に進むよう Claude に指示します。コマンドをブロックしません。 パラメーターなし。 @@ -549,8 +549,8 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `warn-git-stash-drop` -**イベント:** PreToolUse (Bash) -**デフォルト:** `git stash drop` を実行する前に確認するよう Claude に指示します。コマンドはブロックしません。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `git stash drop` を実行する前に確認するよう Claude に指示します。コマンドをブロックしません。 パラメーターなし。 @@ -558,21 +558,21 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `warn-all-files-staged` -**イベント:** PreToolUse (Bash) -**デフォルト:** `git add -A` または `git add .` を実行する際に、ステージングする内容を確認するよう Claude に指示します。コマンドはブロックしません。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `git add -A` または `git add .` を実行する際に、ステージングする内容を確認するよう Claude に指示します。コマンドをブロックしません。 パラメーターなし。 --- -## データベース +## データベース {#database} -データベースに対して実行される前に、破壊的な SQL 操作を検出します。 +データベースに対して実行される前に破壊的な SQL 操作を検出します。 ### `warn-destructive-sql` -**イベント:** PreToolUse (Bash) -**デフォルト:** `DROP TABLE`、`DROP DATABASE`、または `WHERE` 句なしの `DELETE` を含む SQL を実行する前に確認するよう Claude に指示します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `DROP TABLE`、`DROP DATABASE`、または `WHERE` 句なしの `DELETE` を含む SQL を実行する前に確認するよう Claude に指示します。 パラメーターなし。 @@ -580,29 +580,29 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `warn-schema-alteration` -**イベント:** PreToolUse (Bash) -**デフォルト:** `ALTER TABLE` ステートメントを実行する前に確認するよう Claude に指示します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `ALTER TABLE` 文を実行する前に確認するよう Claude に指示します。 パラメーターなし。 --- -## 警告 +## 警告 {#warnings} -リスクはあるものの破壊的ではない操作の前に、エージェントに追加のコンテキストを提供します。 +潜在的にリスクはあるが破壊的ではない操作の前に、エージェントに追加のコンテキストを提供します。 ### `warn-large-file-write` -**イベント:** PreToolUse (Write) -**デフォルト:** 1024 KB を超えるファイルを書き込む前に確認するよう Claude に指示します。 +**イベント：** PreToolUse (Write) +**デフォルト：** 1024 KB を超えるファイルを書き込む前に確認するよう Claude に指示します。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | 警告が発生するファイルサイズのしきい値（キロバイト単位）。 | +| `thresholdKb` | `number` | `1024` | 警告が発行されるファイルサイズのしきい値（キロバイト）。 | -**例:** +**例：** ```json { @@ -615,15 +615,15 @@ failproofai には、エージェントの一般的な失敗パターンを検 ``` -フックハンドラーはペイロードに対して 1 MB の stdin 制限を適用します。小さなコンテンツでこのポリシーをテストするには、`thresholdKb` を 1024 より十分小さい値に設定してください。 +フックハンドラーはペイロードに対して 1 MB の stdin 制限を適用します。小さいコンテンツでこのポリシーをテストするには、`thresholdKb` を 1024 よりも十分に低い値に設定してください。 --- ### `warn-package-publish` -**イベント:** PreToolUse (Bash) -**デフォルト:** `npm publish` を実行する前に確認するよう Claude に指示します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `npm publish` を実行する前に確認するよう Claude に指示します。 パラメーターなし。 @@ -631,8 +631,8 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `warn-background-process` -**イベント:** PreToolUse (Bash) -**デフォルト:** `nohup`、`&`、`disown`、`screen` を使ってバックグラウンドプロセスを起動する際に注意するよう Claude に指示します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `nohup`、`&`、`disown`、または `screen` を使用してバックグラウンドプロセスを起動する際に注意するよう Claude に指示します。 パラメーターなし。 @@ -640,32 +640,32 @@ failproofai には、エージェントの一般的な失敗パターンを検 ### `warn-global-package-install` -**イベント:** PreToolUse (Bash) -**デフォルト:** `npm install -g`、`yarn global add`、または仮想環境なしの `pip install` を実行する前に確認するよう Claude に指示します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** `npm install -g`、`yarn global add`、または仮想環境なしの `pip install` を実行する前に確認するよう Claude に指示します。 パラメーターなし。 --- -## パッケージマネージャー +## パッケージマネージャー {#package-managers} -エージェントが使用できるパッケージマネージャーを制限します。 +エージェントが使用できるパッケージマネージャーを強制します。 ### `prefer-package-manager` -**イベント:** PreToolUse (Bash) -**デフォルト:** 無効。有効化すると、`allowed` リストにないパッケージマネージャーのコマンドをブロックし、許可されたマネージャーを使用してコマンドを書き直すよう Claude に指示します。 +**イベント：** PreToolUse (Bash) +**デフォルト：** 無効。有効にすると、`allowed` リストにないパッケージマネージャーコマンドをブロックし、許可されたマネージャーを使用してコマンドを書き直すよう Claude に指示します。 -検出対象：pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo。 +検出対象：pip、pip3、python -m pip、npm、npx、yarn、pnpm、pnpx、bun、bunx、uv、poetry、pipenv、conda、cargo。 | パラメーター | 型 | デフォルト | 説明 | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | 許可するパッケージマネージャー名。リストにない検出されたマネージャーはブロックされます。空の場合、ポリシーは何もしません。 | +| `allowed` | string[] | `[]` | 許可するパッケージマネージャー名。このリストにない検出済みのマネージャーはブロックされます。空の場合、ポリシーは何もしません。 | | `blocked` | string[] | `[]` | 組み込みリストに加えてブロックする追加のマネージャー名（例：`['pdm', 'pipx']`）。 | -組み込みのブロックリストには以下が含まれます：pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo。このリストにないマネージャーを追加するには `blocked` を使用してください。 +組み込みブロックリストは次を対象とします：pip、pip3、npm、npx、yarn、pnpm、pnpx、bun、bunx、uv、poetry、pipenv、conda、cargo。このリストにないマネージャーを追加するには `blocked` を使用してください。 -**設定例:** +**設定例：** ```json { @@ -679,59 +679,59 @@ failproofai には、エージェントの一般的な失敗パターンを検 } ``` -この設定では、`pip install flask` と `pdm install flask` はどちらも拒否され、`uv` または `bun` を使用するよう指示するメッセージが表示されます。`uv pip install flask` のようなコマンドは、`uv` がアローリストに含まれており最初にチェックされるため、許可されます。 +この設定では、`pip install flask` と `pdm install flask` はどちらも、`uv` または `bun` を使用するよう指示するメッセージとともに拒否されます。`uv pip install flask` のようなコマンドは、`uv` がアローリストに含まれており最初にチェックされるため許可されます。 --- -## AI の動作 +## AI の動作 {#ai-behavior} -エージェントが行き詰まったり予期しない動作をしたりするのを検出します。 +エージェントが行き詰まったり予期しない動作をしていないかを検出します。 ### `warn-repeated-tool-calls` -**イベント:** PreToolUse（すべてのツール） -**デフォルト:** 同じツールが同一パラメーターで3回以上呼び出された場合に、再考するよう Claude に指示します。これはエージェントがループに陥っている一般的なサインです。 +**イベント：** PreToolUse（全ツール） +**デフォルト：** 同じツールが同一のパラメーターで3回以上呼び出された場合に再考するよう Claude に指示します。これはエージェントがループにはまっている一般的なサインです。 パラメーターなし。 --- -## ワークフロー +## ワークフロー {#workflow} -セッション終了時に規律あるワークフローを強制します。これらのポリシーは **Stop** イベントで発火し、各条件が満たされるまでエージェントの停止を拒否します。自然な依存チェーン（コミット → プッシュ → PR → CI）に従います。ポリシーが拒否した場合、チェーン内の後続ポリシーはスキップされます（deny はショートサーキットします）。 +セッション終了時に規律あるワークフローを強制します。これらのポリシーは **Stop** イベントで発火し、各条件が満たされるまでエージェントの停止を拒否します。コミット → プッシュ → PR → CI という自然な依存チェーンに従います。ポリシーが拒否した場合、チェーン内のそれ以降のポリシーはスキップされます（deny はショートサーキット）。 -すべてのワークフローポリシーは **フェイルオープン**です：必要なツールが利用できない場合（例：`gh` がインストールされていない、git リモートがない）、ポリシーはチェックがスキップされた理由を説明する情報メッセージとともに許可します。 +すべてのワークフローポリシーは**フェイルオープン**です：必要なツールが利用できない場合（例：`gh` がインストールされていない、git リモートがない）、ポリシーはチェックがスキップされた理由を説明する情報メッセージとともに許可します。 ### CLI ごとの Stop セマンティクス -Stop の強制は、7つのサポートされている CLI によって若干異なります。各 CLI が異なる「エージェント終了」フックコントラクトを公開しているためです。**結果**は同じ（ワークフローゲートが失敗している状態でエージェントが停止することを防ぐ）ですが、**仕組み**は異なります。以下の表に要約します。`require-*-before-stop` ポリシーを有効化する前に理解しておく価値のあるユーザー向けの注意点があるのは Pi のみです。 +Stop の強制は、サポートされている7つの CLI によって若干異なります。各 CLI が異なる「エージェント終了」フックコントラクトを公開しているためです。**結果**は同じです（ワークフローゲートが失敗している間、エージェントは停止できません）が、**仕組み**は異なります。以下の表に要約します。`require-*-before-stop` ポリシーを有効にする前に理解しておく価値のある、ユーザーに見える挙動があるのは Pi のみです。 -| CLI | ゲートが発火するタイミング | ユーザーが見るもの | +| CLI | ゲートが発火するタイミング | 表示される内容 | |---|---|---| -| Claude Code | 同じエージェントループ、即座 | Claude は作業を継続し、問題を修正してから再度終了を試みます。ユーザーには中断は見えません。 | -| Codex | 同じエージェントループ、即座 | Claude と同じ。 | -| GitHub Copilot CLI | 同じエージェントループ、即座 | Claude と同じ（Copilot の `{decision:"block", reason}` リトライチャネルを使用 — Copilot CLI 1.0.41 に対して実証的に検証済み）。 | -| Cursor Agent | 同じエージェントループ、即座 | Claude と同じ（Cursor の `{followup_message}` チャネルを使用 — `loop_limit`、デフォルト5回のリトライまで）。 | -| Gemini CLI | 同じエージェントループ、即座 | Claude と同じ（`AfterAgent` の `{decision:"block", reason}` チャネルを使用）。 | -| OpenCode | 同じエージェントループ、即座 | Claude と同じ（`hookSpecificOutput.additionalContext` を通じてルーティングされた OpenCode の `client.session.prompt(...)` SDK 呼び出しを使用）。 | -| **Pi (pi-coding-agent)** | **次のユーザーターン** | **Pi はゲートが発火すると見えた形で停止します** — エージェントループが終了し、プロンプトに戻ります。次にプロンプトを送信したときにゲートが発火します：failproofai はそのターンのシステムプロンプトに `MANDATORY ACTION REQUIRED` ディレクティブを先頭に追加し、LLM にリクエストを実行する前にワークフローステップ（コミット、プッシュなど）を完了するよう指示します。 | +| Claude Code | 同じエージェントループ内で即座に | Claude が作業を継続し、問題を修正してから再び終了を試みます。ユーザーには中断が見えません。 | +| Codex | 同じエージェントループ内で即座に | Claude と同じです。 | +| GitHub Copilot CLI | 同じエージェントループ内で即座に | Claude と同じです（Copilot の `{decision:"block", reason}` リトライチャネルを使用 — Copilot CLI 1.0.41 で実証的に検証済み）。 | +| Cursor Agent | 同じエージェントループ内で即座に | Claude と同じです（Cursor の `{followup_message}` チャネルを使用 — デフォルト5回の `loop_limit` に上限あり）。 | +| Gemini CLI | 同じエージェントループ内で即座に | Claude と同じです（`AfterAgent` 上の Gemini の `{decision:"block", reason}` チャネルを使用）。 | +| OpenCode | 同じエージェントループ内で即座に | Claude と同じです（`hookSpecificOutput.additionalContext` を通じてルーティングされた OpenCode の `client.session.prompt(...)` SDK 呼び出しを使用）。 | +| **Pi (pi-coding-agent)** | **次のユーザーターン** | **Pi はゲートが発火すると目に見えて停止します** — エージェントループが終了し、プロンプトに戻ります。次にプロンプトを送信した際にゲートが発火します：failproofai はそのターンのシステムプロンプトの先頭に `MANDATORY ACTION REQUIRED` ディレクティブを付加し、あなたのリクエストを実行する前にワークフローステップ（コミット、プッシュなど）を完了するよう LLM に指示します。 | -**Pi の制限。** Pi の `AgentEndEvent`（Claude の `Stop` フックに相当するアップストリーム）には Result 型がありません。発火するときには Pi のエージェントループはすでに終了しています。Pi は Claude / Copilot / Cursor / Gemini / OpenCode のように同じループを強制的に再試行させることができません。failproofai はゲートを Pi の `before_agent_start` イベント（次のユーザープロンプト後に発火）にシフトすることで、現在のターンではなく次のターンでワークフローチェックを強制します。 +**Pi の制限事項。** Pi の `AgentEndEvent`（Claude の `Stop` フックに相当するアップストリーム）には Result タイプがありません。発火した時点で Pi のエージェントループはすでに終了しています。Claude / Copilot / Cursor / Gemini / OpenCode のように Pi を同じループで再試行させることはできません。failproofai はゲートを Pi の `before_agent_start` イベント（次のユーザープロンプトの後に発火）にシフトするため、ワークフローチェックは依然として強制されますが、現在のターンではなく次のターンで適用されます。 **実際の動作：** -- Pi が停止した後、deny の理由は Pi のセッション ID をキーとしてメモリ内にキャプチャされます。同じ Pi プロセスで次に送信するプロンプトがそれを消費します：LLM はシステムプロンプトの先頭に `MANDATORY ACTION REQUIRED` ディレクティブが表示され、コミット（またはプッシュ / PR 作成 / CI 待機）してからリクエストを続行します。キャプチャされた deny の理由はワンショットです — 一度消費されるとゲートはクリアされます。 -- ゲートは Pi のプロセスライフタイムに束縛されます。ターン間で Pi を `Ctrl+C` で終了したりキルしたりすると、メモリ内のエントリはプロセスとともにドロップされ、ゲートは見逃されます。Claude、Copilot、Cursor、Gemini、OpenCode も同じ制約があります（エージェントをキルするとゲートが見逃されます）— Pi はエージェントがゲートの前に見えた形で終了するため、より目立つだけです。 -- 保留中の deny は、何らかの理由（`new` / `resume` / `fork` / `quit`）による `session_shutdown` でもクリアされます。そのため、以前のセッションの古いゲートが同じ Pi プロセスで開始された新しいセッションに漏れることはありません。 +- Pi が停止した後、deny の理由は Pi のセッション ID をキーとしてメモリ内に保存されます。同じ Pi プロセスで次に送信したプロンプトがそれを消費します：LLM はシステムプロンプトの先頭で `MANDATORY ACTION REQUIRED` ディレクティブを確認し、コミット（またはプッシュ / PR 作成 / CI 待機）してから、あなたのリクエストを続行します。保存された deny の理由は一度消費されるとクリアされ、ゲートは解除されます。 +- ゲートは Pi のプロセスの存続期間に縛られます。ターンの間に Pi を `Ctrl+C` で終了するか終了した場合、メモリ内のエントリはプロセスとともに削除され、ゲートは失われます。Claude、Copilot、Cursor、Gemini、OpenCode も同じ制約があります（エージェントを強制終了するとゲートは失われます）。Pi はエージェントがゲートの発火前に目に見えて終了するため、これがより顕著に現れます。 +- 保留中の deny は、任意の理由（`new` / `resume` / `fork` / `quit`）による `session_shutdown` でもクリアされるため、前のセッションの古いゲートが同じ Pi プロセスで開始された新しいセッションに漏れることはありません。 -Claude スタイルの同一ループリトライが必要な場合は、他の6つのサポートされている CLI のいずれかで `Stop` ポリシーを実行してください。このギャップを埋めるための `AgentEndEvent` への将来の Result 型追加について、Pi のアップストリームを追跡しています。 +Claude スタイルの同ループ再試行が必要な場合は、他の6つのサポートされている CLI のいずれかで `Stop` ポリシーを実行してください。`AgentEndEvent` に Result タイプを追加するためのアップストリームの Pi の更新を追跡しており、これによりこのギャップを解消できる可能性があります。 ### `require-commit-before-stop` -**イベント:** Stop -**デフォルト:** コミットされていない変更（変更済み、ステージ済み、または追跡されていないファイル）がある場合に停止を拒否します。作業ディレクトリがクリーンな場合は情報メッセージを返します。 +**イベント：** Stop +**デフォルト：** コミットされていない変更（変更済み、ステージ済み、または未追跡ファイル）がある場合に停止を拒否します。作業ディレクトリがクリーンな場合は情報メッセージを返します。 パラメーターなし。 @@ -739,16 +739,16 @@ Claude スタイルの同一ループリトライが必要な場合は、他の6 ### `require-push-before-stop` -**イベント:** Stop -**デフォルト:** プッシュされていないコミットがある場合、または現在のブランチにリモートトラッキングブランチがない場合に停止を拒否します。必要に応じてトラッキングブランチを作成するために `git push -u` を提案します。リモートが設定されていない場合はフェイルオープンします。 +**イベント：** Stop +**デフォルト：** プッシュされていないコミットがある場合、または現在のブランチにリモートトラッキングブランチがない場合に停止を拒否します。必要に応じてトラッキングブランチを作成するために `git push -u` を提案します。リモートが設定されていない場合はフェイルオープンします。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| | `remote` | `string` | `"origin"` | プッシュ先のリモート名。 | -**例:** +**例：** ```json { @@ -764,13 +764,13 @@ Claude スタイルの同一ループリトライが必要な場合は、他の6 ### `require-pr-before-stop` -**イベント:** Stop -**デフォルト:** 現在のブランチに対してプルリクエストが存在しない場合、またはマージされずにクローズされた PR がある場合に停止を拒否します。`gh pr create` で PR を作成するよう Claude に指示します。PR が **マージ済み**の場合、ポリシーは許可します（作業が公開されています）。メッセージはブランチを切り替えるよう示唆します（`git checkout main && git pull`）。 +**イベント：** Stop +**デフォルト：** 現在のブランチにプルリクエストが存在しない場合、または既存の PR がマージされずにクローズされた場合に停止を拒否します。`gh pr create` を使用して PR を作成するよう Claude に指示します。PR が**マージ済み**の場合、ポリシーは許可し（作業がリリースされたため）、ブランチから切り替えるヒント（`git checkout main && git pull`）を提示します。 パラメーターなし。 -このポリシーには [GitHub CLI](https://cli.github.com/)（`gh`）がインストールされ認証されている必要があります。 +このポリシーには [GitHub CLI](https://cli.github.com/)（`gh`）のインストールと認証が必要です。 プルリクエストへの読み取りアクセスのために `repo` スコープを持つ個人アクセストークンで `gh auth login` を実行してください。`gh` がインストールされていないか認証されていない場合、ポリシーはフェイルオープンし、理由を Claude に報告します。 @@ -778,36 +778,36 @@ Claude スタイルの同一ループリトライが必要な場合は、他の6 ### `require-no-conflicts-before-stop` -**イベント:** Stop -**デフォルト:** 現在のブランチがベースブランチにクリーンにマージできない場合に停止を拒否します。ポリシーはまず GitHub 上のブランチに `OPEN` な PR があることを確認します — PR がない場合、強制するマージターゲットがないため、ポリシー全体がショートサーキットして許可します。`OPEN` な PR が確認されると、2つの独立したプローブが実行されます： +**イベント：** Stop +**デフォルト：** 現在のブランチがベースブランチにクリーンにマージできない場合に停止を拒否します。まず GitHub 上のブランチに `OPEN` 状態の PR があることを確認します。PR がなければ強制するマージターゲットがないため、ポリシー全体が allow にショートサーキットします。`OPEN` の PR が確認されると、2つの独立したプローブが実行されます： -1. **ローカル** — `git merge-tree --write-tree --name-only origin/ HEAD`。コンフリクトが発生した場合、deny メッセージは競合するファイルを名前で示し、Claude が何を解決すべきかを正確に把握できるようにします。 -2. **GitHub** — 事前チェックですでに取得した `gh pr view --json mergeable,state` の結果を再利用します。ローカルの `origin/` が古い場合に見逃してしまうコンフリクトを検出します（例：最後のフェッチ以降に誰かが `main` に競合する PR をマージした場合）。`CONFLICTING` の結果は拒否されます。`UNKNOWN` の結果も拒否され、Claude は再度停止を試みる前に約10秒待って再チェックするよう指示されます — これにより、GitHub が再計算中の偽陰性を防ぎます。 +1. **ローカル** — `git merge-tree --write-tree --name-only origin/ HEAD`。コンフリクトが発生した場合、Claude が何を解決すべきかを正確に把握できるよう、deny メッセージにコンフリクトしたファイル名が含まれます。 +2. **GitHub** — プレチェックですでに取得した `gh pr view --json mergeable,state` の結果を再利用します。古いローカルの `origin/` では見逃してしまうコンフリクトを検出します（例：最後のフェッチ以降に `main` に競合する PR がマージされた場合）。`CONFLICTING` の結果は拒否されます。`UNKNOWN` の結果も拒否され、再度停止を試みる前に約10秒待って再確認するよう Claude に指示します。これは GitHub が再計算する間の偽陰性を防ぎます。 -以下の場合はスキップします（許可します）：`gh` がインストールされていない、ブランチに PR が存在しない、PR の状態が `OPEN` でない（例：`MERGED`、`CLOSED`）、または `gh pr view` が解析不能な出力を返す。また、`origin/` がローカルに存在しない場合や、ベースより先のコミットがない場合もフェイルオープンします — これらのレイヤー1フォールスルーは、許可する前にキャッシュされた PR のマージ可能性を参照します。 +以下の場合は完全にスキップ（allow）します：`gh` がインストールされていない、ブランチに PR が存在しない、PR の状態が `OPEN` でない（例：`MERGED`、`CLOSED`）、または `gh pr view` が解析不能な出力を返す。ローカルに `origin/` がない場合や、ベースより先にコミットがない場合もフェイルオープンします。ただし、それらのレイヤー1フォールスルーは、許可する前にキャッシュされた PR のマージ可能性を確認します。 -**パラメーター:** +**パラメーター：** | パラメーター | 型 | デフォルト | 説明 | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | コンフリクトをチェックするベースブランチ。 | +| `baseBranch` | `string` | `"main"` | コンフリクトを確認するベースブランチ。 | -このポリシーには GitHub CLI（`gh`）が必要です。ポリシーは競合プローブを実行する前に `gh pr view` を使用して `OPEN` な PR が存在することを確認します — `gh` がない場合、ポリシーはショートサーキットして許可します。プルリクエストへの読み取りアクセスのために `repo` スコープを持つ個人アクセストークンで `gh auth login` を実行してください。 +このポリシーには GitHub CLI（`gh`）が必要です。ポリシーはコンフリクトプローブを実行する前に `gh pr view` を使用して `OPEN` の PR が存在することを確認します。`gh` がない場合、ポリシーは allow にショートサーキットします。プルリクエストへの読み取りアクセスのために `repo` スコープを持つ個人アクセストークンで `gh auth login` を実行してください。 --- ### `require-ci-green-before-stop` -**イベント:** Stop -**デフォルト:** 現在のブランチで CI チェックが失敗しているかまだ実行中の場合に停止を拒否します。GitHub Actions ワークフローの実行とサードパーティのボットチェック（例：CodeRabbit、SonarCloud、Codecov）の両方をチェックします。`skipped`、`cancelled`、`neutral` の結論は失敗として扱いません（後者は例えば、Socket Security が外部コントリビューターの PR に対して success/failure ではなく intentionally neutral を報告する場合をカバーします）。すべてのチェックが通過すると情報メッセージを返します。 +**イベント：** Stop +**デフォルト：** 現在のブランチで CI チェックが失敗しているか実行中の場合に停止を拒否します。GitHub Actions ワークフロー実行とサードパーティのボットチェック（例：CodeRabbit、SonarCloud、Codecov）の両方を確認します。`skipped`、`cancelled`、`neutral` の結論は失敗として扱いません（後者は例えば Socket Security が外部コントリビューターの PR に対して success/failure ではなく neutral を意図的に報告するケースをカバーします）。すべてのチェックが通過した場合は情報メッセージを返します。 パラメーターなし。 -このポリシーには [GitHub CLI](https://cli.github.com/)（`gh`）がインストールされ認証されている必要があります。 -Actions ワークフローの実行と Checks API への読み取りアクセスのために `repo` スコープを持つ個人アクセストークンで `gh auth login` を実行してください。`gh` がインストールされていないか認証されていない場合、ポリシーはフェイルオープンし、理由を Claude に報告します。 +このポリシーには [GitHub CLI](https://cli.github.com/)（`gh`）のインストールと認証が必要です。 +Actions ワークフロー実行と Checks API への読み取りアクセスのために `repo` スコープを持つ個人アクセストークンで `gh auth login` を実行してください。`gh` がインストールされていないか認証されていない場合、ポリシーはフェイルオープンし、理由を Claude に報告します。 --- @@ -816,7 +816,7 @@ Actions ワークフローの実行と Checks API への読み取りアクセス ## 個別ポリシーの無効化 -設定の `enabledPolicies` から特定のポリシーを削除するか、ダッシュボードの「ポリシー」タブでオフに切り替えてください。 +設定の `enabledPolicies` から特定のポリシーを削除するか、ダッシュボードの「ポリシー」タブでオフにしてください。 ```json { @@ -827,4 +827,4 @@ Actions ワークフローの実行と Checks API への読み取りアクセス } ``` -`enabledPolicies` にリストされていないポリシーは、`policyParams` にエントリが存在しても実行されません。 \ No newline at end of file +`enabledPolicies` にリストされていないポリシーは、`policyParams` のエントリが存在していても実行されません。 \ No newline at end of file diff --git a/docs/ja/cli/audit.mdx b/docs/ja/cli/audit.mdx index 62353c5c..4b218e71 100644 --- a/docs/ja/cli/audit.mdx +++ b/docs/ja/cli/audit.mdx @@ -1,19 +1,19 @@ --- -title: 過去のセッションを監査する（ベータ版） -description: "過去のトランスクリプト全体で、エージェントが無駄または危険な操作を行った頻度を集計します" +title: 過去セッションの監査（ベータ） +description: "過去のトランスクリプトで、エージェントが無駄または危険な操作を行った頻度を集計する" --- - **ベータ機能。** 初期フィードバックを収集している間、監査機能はベータ版として提供されます。 - 次の安定版リリース前に、検出器カタログとレポート形式が変更される可能性があります。 - 問題があればイシューを起票してください。 + **ベータ機能。** 監査機能は早期フィードバックを収集する段階でベータとして提供されています。 + 次の安定版リリース前に、検出器カタログやレポート形式が変更される可能性があります。 + 問題があれば Issue を開いてください。 -監査機能は、過去のエージェントCLIトランスクリプトを failproofai のポリシーエンジンで再生し、**`/audit` ダッシュボードページ**に共有可能なビジュアルレポートを生成します。レポートにはエージェントのアーキタイプ、0〜100のスコア、そして各ポリシーが何を検出できたかが表示されます。 +監査機能は、過去のエージェント CLI トランスクリプトを failproofai のポリシーエンジンで再実行し、**`/audit` ダッシュボードページ**に共有可能なビジュアルレポートを表示します。エージェントのアーキタイプ、0〜100 のスコア、そしてどのポリシーが何を検出したかを詳細に確認できます。 ## 実行方法 -3つの方法があり、いずれも同じ `/audit` レポートにアクセスできます。 +3 つの起動方法があり、いずれも同じ `/audit` レポートに遷移します。 @@ -33,13 +33,13 @@ failproofai - `npx -y failproofai audit` は failproofai を取得してスキャンを実行し、ダッシュボードを自動的に開きます。事前インストールは不要です。 + `npx -y failproofai audit` は failproofai を取得してスキャンを実行し、ダッシュボードを自動で開きます。事前インストールは不要です。 - - `failproofai audit` はターミナルでスキャンを実行し、完了後に `localhost:8020/audit` を自動的に開きます。 + + `failproofai audit` はターミナルでスキャンを実行し、完了後に自動で `localhost:8020/audit` を開きます。 - `failproofai` を実行してナビバーの **Audit**（PoliciesとProjectsの間）をクリックするか、`/audit` を直接開きます。 + `failproofai` を実行してナビゲーションバーの **Audit** をクリック（Policies と Projects の間）するか、`/audit` に直接アクセスします。 @@ -47,42 +47,42 @@ failproofai 使い方を確認するには `failproofai audit -h`（または `--help`）を実行してください。監査は**完全オフライン**で動作し、アカウントやネットワーク接続は不要です。`Ctrl+C` で停止するまでダッシュボードはサービスを継続します。 -ダッシュボードはこのマシン上の過去のエージェントCLIトランスクリプト（Claude Code、Codex、Copilot、Cursor、OpenCode、Pi、Gemini）をスキャンし、failproofai が防止するように設計された操作（環境変数チェック、フォースプッシュ、冗長な `cd ` プレフィックス、スリープポーリングループ、編集直後のファイル再読み込みなど）の発生頻度を報告します。 +ダッシュボードはこのマシン上の過去のエージェント CLI トランスクリプト（Claude Code、Codex、Copilot、Cursor、OpenCode、Pi、Gemini）をスキャンし、failproofai が防止するように設計された操作の発生頻度を報告します。対象は環境変数チェック、フォースプッシュ、冗長な `cd ` プレフィックス、スリープポーリングループ、編集直後のファイル再読み込みなどです。 -各トランスクリプトについて、すべてのツール使用イベントが39の組み込みポリシー**および**ランタイムポリシーではまだカバーされていないパターンを検出する8つの監査専用検出器で再生されます。カウントはすべてのセッションにわたってポリシー／検出器ごとに集計されます。 +各トランスクリプトについて、すべてのツール使用イベントが 39 のビルトインポリシー**および** 8 つの監査専用検出器で再実行されます（後者はランタイムポリシーでまだカバーされていないパターンを検出します）。カウントはポリシー・検出器ごとにすべてのセッションで集計されます。 -## 取得できる情報 +## レポートの内容 -`/audit` ページは1画面で共有可能な**ポスター**と、スクロール下部の4つのセクションで構成されています： +`/audit` ページは 1 画面の共有可能な**ポスター**と、スクロール下の 4 つのセクションで構成されています。 -1. **ポスター** — エージェントのプロファイルを一目で確認：**アーキタイプ**（8種類のうちの1つ — `optimist`、`cowboy`、`explorer`、`goldfish`、`paranoid architect`、`precision builder`、`hammer`、`ghost`）、ペルソナキーワード、そのアーキタイプの希少性、および階層バンド付きの**0〜100スコア**（`S` から `bottom tier` まで）。XやLinkedInへの投稿やPNGダウンロードに対応した共有向けデザインです。 -2. **`// strengths`** — エージェントがすでに得意とすること。スキャンの実際の数値として表示されます（例：クリーンなツールコール率、`0` 回のmainへのプッシュ試行）。関連ポリシーで問題が検出されなかった場合のみ表示されます。 -3. **`// quirks`** — 問題として検出されたもの：failproofai がキャッチできた可能性のある動作のランク付きテーブル。*いつ*最後に発生したか、*何が問題だったか*（およびブロックできた組み込みポリシー）、その*深刻度*、*確認頻度*（`new`／`recurring`／`N× seen`）が含まれます。 -4. **`// how to improve`** — 推奨される修正リスト：コピー貼り付け可能な `failproofai policy add ` を含むポリシーの行と、すべての推奨事項を一括で有効にする**すべてインストール**ボタン、および適用後の**予測スコア**が表示されます。 -5. **`// come back better`** — 習慣づくり：再監査の**リマインダー**メールを設定（`3d`／`7d`／`14d`／`30d`）するか、今すぐ再監査を実行し、**友人を招待**して自分自身の監査を実行してもらえます（failproof.ai から送信され、あなたにCCされます）。リマインダーと招待にはサインインが必要です。[`failproofai auth`](/ja/cli/auth) を参照してください。 +1. **ポスター** — エージェントのプロフィールが一目でわかる。**アーキタイプ**（8 種類のうちの 1 つ — `optimist`、`cowboy`、`explorer`、`goldfish`、`paranoid architect`、`precision builder`、`hammer`、`ghost`）、ペルソナキーワード、そのアーキタイプのレア度、**0〜100 スコア**とティアバンド（`S` から `bottom tier` まで）。X や LinkedIn への投稿や PNG ダウンロードにも対応した共有向けデザインです。 +2. **`// strengths`** — スキャン結果から得た実際の数値でエージェントが既によくできていることを表示（例：クリーンなツール呼び出しの割合、`main` へのプッシュ試行数 `0` 回）。関連ポリシーに問題がない場合のみ表示されます。 +3. **`// quirks`** — 見逃された動作：failproofai が検出できたはずの動作を優先度順に並べたテーブル。*最後に発生した日時*、*何が見逃されたか*（および対応するビルトイン）、*深刻度*、発生頻度（`new` / `recurring` / `N× seen`）が表示されます。 +4. **`// how to improve`** — 推奨修正リスト：コピー＆ペースト可能な `failproofai policy add ` コマンドをポリシーごとに 1 行表示。すべての推奨設定を一括で有効化する **install all** ボタンと、適用した場合の**予測スコア**も確認できます。 +5. **`// come back better`** — 習慣を作る：再監査メール**リマインダー**（`3d` / `7d` / `14d` / `30d`）の設定や今すぐ再監査の実行、そして**友人への招待**（failproof.ai から送信、自分に Cc）ができます。リマインダーと招待にはサインインが必要です。[`failproofai auth`](/ja/cli/auth) を参照してください。 ## 監査専用検出器 -これらはリアルタイムでは（まだ）強制されていない「非効率な動作」パターンを検出します。監査中のみ実行され、ライブのツールコールをブロックすることはありません。 +これらはリアルタイムで強制されていない（まだ）「非効率な動作」パターンを検出します。監査時のみ実行され、ライブのツール呼び出しをブロックすることはありません。 -| 検出器 | 検出内容 | +| 検出器 | カウント対象 | |---|---| -| `redundant-cd-cwd` | コマンドがすでに `cwd` で実行されているにもかかわらず、`cd && …` で始まる Bash コマンド。 | -| `prefer-edit-over-read-cat` | 単一のソースファイルに対する `cat`/`head`/`tail`/`less`/`more` — `Read` ツールを使用してください。 | -| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` によるインプレース編集 — `Edit` ツールを使用してください。 | -| `prefer-write-over-heredoc` | ヒアドキュメントや複数行の `echo > file` によるファイル書き込み — `Write` ツールを使用してください。 | -| `sleep-polling-loop` | 長い `sleep N`（30秒以上）または `while …; sleep …; done` ポーリングループ。 | -| `find-from-root` | `find /`、`find /home`、`find /usr` など — 代わりに `cwd` をスコープとして使用してください。 | +| `redundant-cd-cwd` | コマンドはすでに `cwd` で実行されているにもかかわらず、`cd && …` で始まる Bash コマンド。 | +| `prefer-edit-over-read-cat` | 単一のソースファイルへの `cat`/`head`/`tail`/`less`/`more` — `Read` ツールを使用すべき。 | +| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` によるインプレース編集 — `Edit` ツールを使用すべき。 | +| `prefer-write-over-heredoc` | ヒアドキュメント / 複数行の `echo > file` によるファイル書き込み — `Write` ツールを使用すべき。 | +| `sleep-polling-loop` | 長い `sleep N`（≥ 30 秒）や `while …; sleep …; done` のポーリングループ。 | +| `find-from-root` | `find /`、`find /home`、`find /usr` など — `cwd` にスコープを絞るべき。 | | `git-commit-no-verify` | `git commit … --no-verify` / `-n` によるフックのスキップ。 | -| `reread-after-edit` | 同じセッション内で `Edit`/`Write` した直後のファイルへの `Read`。 | +| `reread-after-edit` | 同一セッション内で `Edit`/`Write` した直後のファイルへの `Read`。 | ## キャッシュ -- **トランスクリプトごとのキャッシュ**：`~/.failproofai/cache/audit/.json` に `(mtime, size, engineVersion, detectorVersion)` をキーとして保存されます。トランスクリプトまたはポリシー／検出器のコードが変更された場合、自動的に無効化されます。各エントリには `cachedAt` タイムスタンプが **TTLメタデータ**として保存されます（キャッシュキーには含まれません）。**7日**以上経過したエントリは読み取り時に拒否されるため、検出器の意図が進化しても古い結果が残り続けることはありません。 -- **結果全体のキャッシュ**：`~/.failproofai/audit-dashboard.json`（モード 0600）。ダッシュボードのナビゲーション時に再実行なしで即座にレンダリングできます。**7日間のTTL**を超えると読み取り時に拒否されます。その場合、`/audit` は空の状態にフォールバックして新規実行を促します。レポート下部の `[ re-audit now ]` をクリックすると更新できます。再監査は `noCache: true` を送信するため、トランスクリプトごとのキャッシュをバイパスしてキャッシュ結果を返す代わりにすべてのトランスクリプトを再スキャンします。実行状況は上部の固定ストリップでストリーミング表示され、成功時は結果がその場で更新されます（ページのリロードなし。再監査に失敗した場合は以前のレポートが保持されます）。 +- **トランスクリプトごとのキャッシュ** は `~/.failproofai/cache/audit/.json` に保存され、`(mtime, size, engineVersion, detectorVersion)` をキーとしています。トランスクリプトやポリシー・検出器コードが変更されると自動的に無効化されます。各エントリには `cachedAt` タイムスタンプが **TTL メタデータ**として保存されます（キャッシュキーには含まれません）。**7 日**以上経過したエントリは読み込み時に拒否されるため、長期間のキャッシュが検出器の意図の変化に追いつけないという問題を防ぎます。 +- **結果全体のキャッシュ** は `~/.failproofai/audit-dashboard.json`（モード 0600）に保存されます。再実行なしでダッシュボードを即座に表示できます。こちらも **7 日 TTL** を超えると読み込み時に拒否されます。その場合 `/audit` は空の状態に戻り、新しい実行を促します。レポート下部の `[ re-audit now ]` をクリックすると更新できます。再監査は `noCache: true` を送信するため、トランスクリプトごとのキャッシュをバイパスしてすべてのトランスクリプトを再スキャンします（キャッシュ結果は返しません）。実行中はページ上部のスティッキーストリップに進捗が表示され、成功時にはページリロードなしで結果がその場で更新されます（再監査に失敗した場合は以前のレポートが維持されます）。 ## 注意事項 -- **変更なし。** 監査は読み取り専用モードで再生されます。`warn-repeated-tool-calls` は、セッションごとのサイドカーが変更されてしまうためスキップされます。 -- **ワークフローポリシーはスキップ。** `require-*-before-stop` ポリシーは `Stop` イベント時にのみ発火し、ライブのgit状態に対して `execSync` を実行します。これらは「2025年に何が起きたか」という意味のある解釈ができないため、監査カウントには含まれません。 -- **カスタムポリシーはスキップ。** ユーザーが定義したカスタムフックは再生されません（元のセッション以降に変更されている可能性があるため）。 \ No newline at end of file +- **変更なし。** 監査は読み取り専用モードで再実行されます。`warn-repeated-tool-calls` はセッションごとのサイドカーが変更されてしまうためスキップされます。 +- **ワークフローポリシーのスキップ。** `require-*-before-stop` ポリシーは `Stop` イベント時にのみ発火し、ライブの git 状態に対して `execSync` を実行します。「2025 年に何が起きたか」という文脈では意味のある解釈ができないため、監査カウントには含まれません。 +- **カスタムポリシーのスキップ。** ユーザーが定義したカスタムフックは再実行されません（元のセッション以降に変更された可能性があるため）。 \ No newline at end of file diff --git a/docs/ja/cli/auth.mdx b/docs/ja/cli/auth.mdx index dcc120af..841ae7d4 100644 --- a/docs/ja/cli/auth.mdx +++ b/docs/ja/cli/auth.mdx @@ -1,6 +1,6 @@ --- title: サインイン -description: "CLIからFailproofAIにサインインして、リマインダーやパーソナライズ機能を有効にする" +description: "CLIからFailproofAIにサインインして、リマインダーやパーソナライズされた機能を有効にする" --- ```bash @@ -11,7 +11,7 @@ failproofai auth whoami # サインイン中のアカウントを表示 後方互換性のため、従来の `--login` / `--logout` / `--whoami` フラグ形式も引き続きエイリアスとして使用できます。 -認証はオプトイン方式です。ポリシー、ダッシュボード、`/audit` ページ、その他すべてのローカル機能は、サインインの有無にかかわらず同じように動作します。ログイン機能が存在するのは、**安定したアカウント情報を必要とする**機能（現時点では再監査リマインダー、今後さらに追加予定）のためです。 +認証はオプトイン方式です。ポリシー、ダッシュボード、`/audit` ページ、その他すべてのローカル機能は、サインインの有無にかかわらず同じように動作します。ログイン機能は、**安定したアカウント情報を必要とする**機能（現時点では再監査リマインダー、今後追加予定のもの）の基盤として用意されています。 ## サインインフロー @@ -19,9 +19,9 @@ failproofai auth whoami # サインイン中のアカウントを表示 failproofai auth login ``` -メールアドレスの入力を求め、そのアドレスに6桁のワンタイムコードを送信し、コードの入力を求めます。成功すると `~/.failproofai/auth.json`（パーミッション `0600`）が作成されます。同じセッションがアプリ内ダッシュボードにも反映され、`/audit` ページで `[ set a reminder ]` をクリックするとサインイン済みとして認識されます。 +メールアドレスを入力するよう促され、そのアドレスに6桁のワンタイムコードが送信されます。コードを入力して認証に成功すると、`~/.failproofai/auth.json`（パーミッション `0600`）が作成されます。同じセッションがアプリ内ダッシュボードにも反映され、`/audit` の `[ set a reminder ]` をクリックした際にサインイン済みとして認識されます。 -CLIを使用しないユーザー向けに、ダッシュボードの `/audit` ページでも同じフローをモーダルダイアログとして提供しています。 +CLIを使用しないユーザー向けに、ダッシュボードの `/audit` ページでも同じフローをモーダルダイアログとして利用できます。 ## サインアウト @@ -29,7 +29,7 @@ CLIを使用しないユーザー向けに、ダッシュボードの `/audit` failproofai auth logout ``` -サーバー上の現在のセッションを無効化し、`~/.failproofai/auth.json` を削除します。APIサーバーに接続できない場合でも、ローカルファイルは削除されます。ローカルでのサインアウト操作が常に優先されます。 +サーバー上の現在のセッションを無効化し、`~/.failproofai/auth.json` を削除します。APIサーバーに接続できない場合でも、ローカルファイルは削除されます。ローカルでのログアウト操作が常に優先されます。 ## アカウント確認 @@ -37,11 +37,11 @@ failproofai auth logout failproofai auth whoami ``` -有効なセッションが存在する場合は ` ()` を表示して終了コード0で終了し、そうでない場合は `not signed in` を表示して終了コード1で終了します。アクセストークンの有効期限まで1分以内に近づいている場合は、バックグラウンドでサイレント更新を行います。 +有効なセッションが存在する場合は `<メールアドレス> (<ユーザーUUID>)` を表示してコード0で終了し、サインインしていない場合は `not signed in` を表示してコード1で終了します。アクセストークンの有効期限が1分以内に迫っている場合は、バックグラウンドで自動的に更新されます。 -## 定期的な再監査リマインダー +## 再監査リマインダーの設定 -`/audit` ページで **`[ set a reminder ]`** をクリックする（またはそのボタンが表示するモーダルからサインインする）と、ダッシュボードは `~/.failproofai/next-audit.json` に補助ファイルを書き込みます： +`/audit` ページで **`[ set a reminder ]`** をクリックする（またはボタンが表示するモーダルからサインインする）と、ダッシュボードが `~/.failproofai/next-audit.json` に小さなファイルを作成します。 ```json { @@ -51,9 +51,9 @@ failproofai auth whoami } ``` -このファイルは設定時のメールアドレスに紐付けられており、CLIセッションを別のアカウントに切り替えると、前のユーザーのリマインダーは非表示になります。デフォルトのオフセットは **7日間**で、スケジューラー機能のリリース後に変更可能になります。`auth.json` と同様に `0600` パーミッションで作成されます。 +このファイルは設定したメールアドレスにひもづいています。CLIセッションを別のアカウントに切り替えると、以前のユーザーのリマインダーは表示されなくなります。デフォルトの期間は**7日間**で、スケジューラーが実装された後に設定可能になる予定です。`auth.json` と同様に `0600` パーミッションで作成されます。 -ダッシュボードの `/api/auth/reminder` エンドポイントは `GET`（読み取り）、`POST`（設定・再スケジュール）、`DELETE`（削除）をサポートしており、有効なセッションが必要です。 +ダッシュボードの `/api/auth/reminder` エンドポイントは `GET`（読み取り）、`POST`（設定・再スケジュール）、`DELETE`（削除）をサポートし、有効なセッションが必要です。 ## `~/.failproofai/auth.json` の内容 @@ -67,21 +67,21 @@ failproofai auth whoami } ``` -`0600` パーミッション（オーナーのみ読み書き可能）で作成されます。アクセストークンは有効期限1時間のHS256 JWTです。リフレッシュトークンはサーバーが `SHA-256(token)` として保存する、不透明な256ビットのランダム文字列です。リフレッシュトークンの再利用はサーバー側で検出され、そのユーザーのすべてのセッションが無効化されます。 +`0600` パーミッション（オーナーのみ読み書き可能）で作成されます。アクセストークンは有効期限1時間のHS256 JWTで、リフレッシュトークンはサーバーが `SHA-256(token)` として保存する不透明な256ビットのランダム文字列です。リフレッシュトークンの使い回しはサーバー側で検出され、そのユーザーのすべてのセッションが無効化されます。 ## 環境変数 | 変数 | デフォルト値 | 用途 | |---|---|---| -| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | APIサーバーのベースURLを上書きします。セルフホスト型APIサーバーに対してローカル開発を行う際に便利です。 | -| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | `auth.json` の保存場所を上書きします。主にテスト用途です。 | +| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | APIサーバーのベースURLを上書きします。セルフホスト型APIサーバーを使ったローカル開発時に便利です。 | +| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | `auth.json` の保存場所を上書きします。主にテスト用途向けです。 | -全一覧については [環境変数](/ja/cli/environment-variables) を参照してください。 +完全な一覧については [環境変数](/ja/cli/environment-variables) を参照してください。 ## トラブルシューティング -**「APIサーバーに接続できませんでした」** — CLIが `FAILPROOF_API_URL` へのTCP接続を開けません。ネットワーク環境を確認するか、セルフホスト型APIサーバーを使用している場合は `FAILPROOF_API_URL` を設定してください。 +**「Could not reach the api-server」** — CLIが `FAILPROOF_API_URL` へのTCP接続を確立できません。ネットワーク接続を確認するか、セルフホスト型APIサーバーを使用している場合は `FAILPROOF_API_URL` を設定してください。 -**「レート制限」** — 15分以内に同じメールアドレス（5回/メール）またはIPアドレス（20回/IP）からのログイン試行が多すぎる場合、または同じメールアドレスへの前回のリクエストから30秒間の再送信クールダウン中です。エラーメッセージには再試行可能になるまでの時間が秒単位で含まれます。 +**「Rate limited」** — 15分間のウィンドウ内で、同一メールアドレスからのログイン試行が上限（メール5回、IP20回）を超えたか、同一メールアドレスへの再送信クールダウン（30秒）中です。エラーメッセージには、秒単位の再試行可能時間が含まれます。 -**コードが拒否された** — OTPが誤っているか、期限切れか、または5回の入力ミスによるロックアウトが発生しています。`failproofai auth login` を再実行して新しいコードをリクエストしてください。 \ No newline at end of file +**コードが拒否された** — OTPが誤っているか、有効期限が切れているか、5回の誤入力によるロックアウトが発生しています。`failproofai auth login` を再実行して、新しいコードを取得してください。 \ No newline at end of file diff --git a/docs/ja/cli/dashboard.mdx b/docs/ja/cli/dashboard.mdx index 49bc590f..9ae25151 100644 --- a/docs/ja/cli/dashboard.mdx +++ b/docs/ja/cli/dashboard.mdx @@ -1,29 +1,29 @@ --- -title: セッションの表示 -description: "ダッシュボードを起動してエージェントセッションの閲覧とポリシーの管理を行う" +title: セッションを表示する +description: "ダッシュボードを起動してエージェントセッションの確認とポリシーの管理を行う" --- ```bash failproofai ``` -`http://localhost:8020` でウェブダッシュボードを起動します。 +`http://localhost:8020` にウェブダッシュボードを起動します。 ## オプション | フラグ | 説明 | -|------|-------------| +|--------|------| | `--port ` | リッスンするポート番号（デフォルト: `8020`） | | `--allowed-origins ` | 開発リソースへのアクセスを許可するホスト/IPのカンマ区切りリスト | -ダッシュボードをデフォルト以外の Claude プロジェクトフォルダに向けるには、起動時に `CLAUDE_PROJECTS_PATH` 環境変数を設定してください。 +デフォルト以外の Claude プロジェクトフォルダーをダッシュボードに指定するには、起動時に `CLAUDE_PROJECTS_PATH` 環境変数を設定してください。 ## 使用例 ```bash -# Launch on a different port +# 別のポートで起動する failproofai --port 9000 -# Use a custom Claude projects path via environment variable +# 環境変数でカスタムの Claude プロジェクトパスを指定する CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/ja/cli/environment-variables.mdx b/docs/ja/cli/environment-variables.mdx index 904b5ab4..0dfdca7a 100644 --- a/docs/ja/cli/environment-variables.mdx +++ b/docs/ja/cli/environment-variables.mdx @@ -1,6 +1,6 @@ --- title: 環境変数 -description: "環境変数による failproofai の動作設定" +description: "環境変数で failproofai の動作を設定する" --- ## ダッシュボード @@ -8,40 +8,40 @@ description: "環境変数による failproofai の動作設定" | 変数 | 説明 | |----------|-------------| | `PORT` | ダッシュボードのポート番号（デフォルト: `8020`） | -| `CLAUDE_PROJECTS_PATH` | Claude Code のプロジェクトフォルダの検索場所を上書き | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | 非表示にするダッシュボードページをカンマ区切りで指定 | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | 開発リソースへのアクセスを許可するホスト/IP。`--allowed-origins` と同等。 | +| `CLAUDE_PROJECTS_PATH` | Claude Code のプロジェクトフォルダの検索場所を上書きする | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | 非表示にするダッシュボードページをカンマ区切りで指定する | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | 開発リソースへのアクセスを許可するホスト/IP。`--allowed-origins` と同じ。 | ## ログ | 変数 | 説明 | |----------|-------------| | `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | サーバーのログレベル（デフォルト: `warn`） | -| `FAILPROOFAI_HOOK_LOG_FILE` | フックログファイルのカスタムパス。`true` を指定するとデフォルトパス（`~/.failproofai/logs/hooks.log`）を使用。 | +| `FAILPROOFAI_HOOK_LOG_FILE` | フックログファイルのカスタムパス、または `true` を指定するとデフォルトパス（`~/.failproofai/logs/hooks.log`）を使用する | ## テレメトリー | 変数 | 説明 | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | 匿名利用テレメトリーを無効化 | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | 匿名使用状況テレメトリーを無効にする | ## 認証 | 変数 | 説明 | |----------|-------------| -| `FAILPROOF_API_URL` | `failproofai auth` およびダッシュボードの認証ダイアログが使用する API サーバーのベース URL を上書き。デフォルトは `https://api.befailproof.ai`。ローカルの API サーバーを使用する場合は `http://localhost:8080`（または任意のアドレス）に設定。 | -| `FAILPROOFAI_AUTH_DIR` | `auth.json` の保存場所を上書き（デフォルト: `~/.failproofai`）。主に独立したテスト環境で使用。 | +| `FAILPROOF_API_URL` | `failproofai auth` およびダッシュボードの認証ダイアログが使用する API サーバーのベース URL を上書きする。デフォルトは `https://api.befailproof.ai`。ローカルの API サーバーを使用する場合は `http://localhost:8080`（または該当するアドレス）に設定する。 | +| `FAILPROOFAI_AUTH_DIR` | `auth.json` の保存場所を上書きする（デフォルト: `~/.failproofai`）。主に独立したテスト環境で利用する。 | -## 初回実行プロンプト +## 初回起動時のプロンプト | 変数 | 説明 | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | `failproofai` を初めて単体で実行した際にポリシーのインストールを促すプロンプトをスキップ | +| `FAILPROOFAI_NO_FIRST_RUN=1` | `failproofai` を初めて引数なしで実行した際に表示されるポリシーインストールの案内をスキップする | ## LLM（ポリシー評価用） | 変数 | 説明 | |----------|-------------| -| `FAILPROOFAI_LLM_BASE_URL` | LLM API エンドポイント（デフォルト: `https://api.openai.com/v1`） | -| `FAILPROOFAI_LLM_API_KEY` | LLM 機能を使用するポリシーの API キー | +| `FAILPROOFAI_LLM_BASE_URL` | LLM API のエンドポイント（デフォルト: `https://api.openai.com/v1`） | +| `FAILPROOFAI_LLM_API_KEY` | LLM を使用したポリシー向けの API キー | | `FAILPROOFAI_LLM_MODEL` | モデル名（デフォルト: `gpt-4o-mini`） | \ No newline at end of file diff --git a/docs/ja/cli/hook.mdx b/docs/ja/cli/hook.mdx index fcecc7ce..14271ccc 100644 --- a/docs/ja/cli/hook.mdx +++ b/docs/ja/cli/hook.mdx @@ -1,6 +1,6 @@ --- title: フックハンドラー（内部） -description: "各ツールイベントでClaude Codeが呼び出すサブプロセス" +description: "各ツールイベントで Claude Code が呼び出すサブプロセス" --- ```bash @@ -9,10 +9,10 @@ failproofai --hook これは `failproofai policies --install` によって Claude Code の `settings.json` に登録されるコマンドです。通常、直接呼び出すことはありません。 -stdin からJSONペイロードを読み取り、有効なすべてのポリシーを評価し、判定結果を示す終了コードで終了します： +stdin から JSON ペイロードを読み取り、有効なすべてのポリシーを評価し、判定結果を示す終了コードで終了します。 | 終了コード | 判定 | 効果 | -|-----------|------|------| +|-----------|----------|--------| | `0` | `allow` | アクションを許可する | | `1` | `deny` | アクションをブロックする — Claude には拒否理由が通知される | | `2` | `instruct` | Claude のコンテキストにガイダンスを注入する | @@ -20,7 +20,7 @@ stdin からJSONペイロードを読み取り、有効なすべてのポリシ ### サポートされているイベントタイプ | カテゴリ | イベント | -|----------|---------| +|----------|--------| | **ツール実行** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | | **セッションライフサイクル** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | | **ユーザーインタラクション** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | diff --git a/docs/ja/cli/install-policies.mdx b/docs/ja/cli/install-policies.mdx index 7a39c558..53aba16b 100644 --- a/docs/ja/cli/install-policies.mdx +++ b/docs/ja/cli/install-policies.mdx @@ -7,7 +7,7 @@ description: "エージェントのツール呼び出しごとにポリシーが failproofai policies --install [policy-names...] [options] ``` -インストール済みのエージェント CLI（Claude Code、OpenAI Codex、または GitHub Copilot CLI _（ベータ）_）の設定ファイルにフックエントリを書き込み、failproofai がツール呼び出しをインターセプトできるようにします。 +インストール済みのエージェント CLI（Claude Code、OpenAI Codex、または GitHub Copilot CLI _(ベータ版)_）の設定ファイルにフックエントリを書き込み、failproofai がツール呼び出しをインターセプトできるようにします。 エイリアス: `failproofai p -i` @@ -15,43 +15,43 @@ failproofai policies --install [policy-names...] [options] | フラグ | 説明 | |------|-------------| -| `--cli claude\|codex\|copilot` | インストール対象のエージェント CLI。スペース区切り（例: `--cli claude codex copilot`）または繰り返し指定が可能。省略するとインストール済みの CLI を自動検出してプロンプトを表示。 | -| `--scope user` | ユーザースコープの設定ファイルにインストール（Claude: `~/.claude/settings.json`、Codex: `~/.codex/hooks.json`、Copilot: `~/.copilot/hooks/failproofai.json`）。デフォルト。 | -| `--scope project` | プロジェクトスコープの設定ファイルにインストール（Claude: `/.claude/settings.json`、Codex: `/.codex/hooks.json`、Copilot: `/.github/hooks/failproofai.json`）。 | -| `--scope local` | Claude のみ — `/.claude/settings.local.json` にインストール。Codex と Copilot には `local` スコープはありません。 | +| `--cli claude\|codex\|copilot` | インストール対象のエージェント CLI。スペース区切り（例: `--cli claude codex copilot`）または繰り返し指定が可能。省略するとインストール済みの CLI を自動検出し、プロンプトを表示する。 | +| `--scope user` | ユーザースコープの設定ファイルにインストールする（Claude: `~/.claude/settings.json`、Codex: `~/.codex/hooks.json`、Copilot: `~/.copilot/hooks/failproofai.json`）。デフォルト。 | +| `--scope project` | プロジェクトスコープの設定ファイルにインストールする（Claude: `/.claude/settings.json`、Codex: `/.codex/hooks.json`、Copilot: `/.github/hooks/failproofai.json`）。 | +| `--scope local` | Claude のみ — `/.claude/settings.local.json` にインストールする。Codex と Copilot には `local` スコープは存在しない。 | | `--custom ` / `-c` | カスタムフックポリシーを含む JS ファイルへのパス | ## 動作 -- **ポリシー名を指定しない場合** — ポリシーを選択するインタラクティブなプロンプトが開きます -- **特定の名前を指定した場合** — 指定したポリシーを有効化します（既に有効なポリシーに追加されます） -- **`all`** — 利用可能なすべてのポリシーを有効化します +- **ポリシー名を指定しない場合** — インタラクティブなプロンプトを開き、ポリシーを選択できる +- **特定の名前を指定した場合** — 指定したポリシーを有効化する（既に有効なポリシーに追加される） +- **`all`** — 利用可能なすべてのポリシーを有効化する -インストールは追加的に行われます。`--install` を再度実行すると、既存のポリシーを削除せずに新しいポリシーが追加されます。 +インストールは追加型です。`--install` を再度実行しても、既存のポリシーが削除されることなく新しいポリシーが追加されます。 -## 例 +## 使用例 ```bash -# すべてのデフォルトポリシーをグローバルにインストール（インタラクティブ） +# すべてのデフォルトポリシーをグローバルにインストールする（インタラクティブ） failproofai policies --install -# 現在のプロジェクトに特定のポリシーをインストール +# 現在のプロジェクトに特定のポリシーをインストールする failproofai policies --install block-sudo sanitize-api-keys --scope project -# すべてのポリシーを一括で有効化 +# すべてのポリシーを一括で有効化する failproofai policies --install all -# カスタムポリシーファイルとともにインストール +# カスタムポリシーファイルを指定してインストールする failproofai policies --install --custom ./my-policies.js -# OpenAI Codex 用にインストール（プロジェクトスコープ） +# OpenAI Codex 向けにインストールする（プロジェクトスコープ） failproofai policies --install --cli codex --scope project -# GitHub Copilot CLI（ベータ）用に現在のプロジェクトへインストール +# GitHub Copilot CLI（ベータ版）向けに現在のプロジェクトへインストールする failproofai policies --install --cli copilot --scope project -# 3つの CLI すべてに一括でインストール +# 3 つの CLI すべてに一括でインストールする failproofai policies --install --cli claude codex copilot ``` -`--custom ` が指定された場合、ファイルは即座に検証されます — `customPolicies.add()` を少なくとも1回呼び出している必要があります。解決されたパスは `policies-config.json` に `customPoliciesPath` として保存されます。 \ No newline at end of file +`--custom ` を指定した場合、ファイルは即座に検証されます。少なくとも 1 回 `customPolicies.add()` を呼び出している必要があります。解決されたパスは `customPoliciesPath` として `policies-config.json` に保存されます。 \ No newline at end of file diff --git a/docs/ja/cli/list-policies.mdx b/docs/ja/cli/list-policies.mdx index 9fb3dee0..0399e3b4 100644 --- a/docs/ja/cli/list-policies.mdx +++ b/docs/ja/cli/list-policies.mdx @@ -1,6 +1,6 @@ --- title: ポリシーの一覧表示 -description: "有効なポリシー、そのパラメータ、およびカスタムポリシーを確認する" +description: "有効なポリシー、そのパラメータ、カスタムポリシーを確認する" --- ```bash @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -`policyParams` 内の不明なキーはここにフラグが立てられるため、タイプミスを早期に発見できます。 \ No newline at end of file +`policyParams` 内の不明なキーはここでフラグが立てられるため、タイポを早期に発見できます。 \ No newline at end of file diff --git a/docs/ja/cli/remove-policies.mdx b/docs/ja/cli/remove-policies.mdx index 643e15ac..bdf8f228 100644 --- a/docs/ja/cli/remove-policies.mdx +++ b/docs/ja/cli/remove-policies.mdx @@ -7,7 +7,7 @@ description: "Claude Code の設定からフックエントリを削除する" failproofai policies --uninstall [policy-names...] [options] ``` -Claude Code の `settings.json` から failproofai フックエントリを削除します。 +Claude Code の `settings.json` から failproofai のフックエントリを削除します。 エイリアス: `failproofai p -u` @@ -15,29 +15,29 @@ Claude Code の `settings.json` から failproofai フックエントリを削 | フラグ | 説明 | |------|-------------| -| `--scope user` | グローバル設定から削除（デフォルト） | -| `--scope project` | プロジェクト設定から削除 | -| `--scope local` | ローカル設定から削除 | -| `--scope all` | すべてのスコープから一括削除 | +| `--scope user` | グローバル設定から削除する（デフォルト） | +| `--scope project` | プロジェクト設定から削除する | +| `--scope local` | ローカル設定から削除する | +| `--scope all` | すべてのスコープから一括削除する | | `--custom` / `-c` | 設定から `customPoliciesPath` をクリアする | ## 動作 -- **ポリシー名を指定しない場合** — 設定ファイルからすべての failproofai フックエントリを削除します -- **特定の名前を指定した場合** — 該当するポリシーを無効化しますが、フック自体はインストールされたまま維持されます +- **ポリシー名の指定なし** — 設定ファイルからすべての failproofai フックエントリを削除する +- **特定の名前を指定** — 対象ポリシーを無効化するが、フックはインストールされたまま維持する ## 使用例 ```bash -# すべてのフックをグローバルから削除 +# すべてのフックをグローバルから削除する failproofai policies --uninstall -# 特定のポリシーを無効化（フックはインストール済みのまま） +# 特定のポリシーを無効化する（フックはインストール済みのまま維持） failproofai policies --uninstall block-sudo -# すべてのスコープからフックを削除 +# すべてのスコープからフックを削除する failproofai policies --uninstall --scope all -# カスタムポリシーのパスをクリア +# カスタムポリシーのパスをクリアする failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/ja/cli/version.mdx b/docs/ja/cli/version.mdx index 86bdc4ee..4fe5371c 100644 --- a/docs/ja/cli/version.mdx +++ b/docs/ja/cli/version.mdx @@ -1,6 +1,6 @@ --- -title: バージョンを確認する -description: "インストールされている failproofai のバージョンを表示する" +title: バージョン確認 +description: "インストール済みの failproofai バージョンを表示する" --- ```bash @@ -9,4 +9,4 @@ failproofai --version failproofai -v ``` -インストールされているバージョン番号を表示します。 \ No newline at end of file +インストール済みのバージョン番号を表示します。 \ No newline at end of file diff --git a/docs/ja/configuration.mdx b/docs/ja/configuration.mdx index 46ca92f2..9c428489 100644 --- a/docs/ja/configuration.mdx +++ b/docs/ja/configuration.mdx @@ -1,38 +1,38 @@ --- 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つのファイルすべてをロードしてマージします。 ### マージルール -**`enabledPolicies`** — 3つのスコープすべての和集合。いずれかのレベルで有効になっているポリシーはアクティブになります。 +**`enabledPolicies`** — 3つのスコープの和集合。いずれかのレベルで有効になっているポリシーはアクティブになります。 ```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"] } @@ -55,7 +55,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global にフォー --- -## 設定ファイルの形式 +## 設定ファイルのフォーマット ```json { @@ -100,29 +100,29 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global にフォー ### `enabledPolicies` -型：`string[]` +型: `string[]` -有効にするポリシー名のリスト。名前は `failproofai policies` で表示されるポリシー識別子と完全に一致する必要があります。完全なリストは [Built-in Policies](/ja/built-in-policies) を参照してください。 +有効にするポリシー名のリスト。名前は `failproofai policies` で表示されるポリシー識別子と完全に一致する必要があります。完全なリストは[組み込みポリシー](/ja/built-in-policies)を参照してください。 -`enabledPolicies` に含まれていないポリシーは、`policyParams` にエントリがあっても無効になります。 +`enabledPolicies` に含まれていないポリシーは、`policyParams` にエントリがあっても無効です。 ### `policyParams` -型：`Record>` +型: `Record>` -ポリシーごとのパラメーターオーバーライド。外側のキーはポリシー名、内側のキーはポリシー固有のものです。各ポリシーで利用可能なパラメーターは [Built-in Policies](/ja/built-in-policies) に記載されています。 +ポリシーごとのパラメーター上書き設定。外側のキーはポリシー名、内側のキーはポリシー固有のものです。各ポリシーで使用可能なパラメーターは[組み込みポリシー](/ja/built-in-policies)に記載されています。 -ポリシーにパラメーターがあっても指定しない場合は、ポリシーの組み込みデフォルト値が使用されます。`policyParams` をまったく設定しないユーザーは、以前のバージョンと同じ動作になります。 +ポリシーにパラメーターがある場合でも指定しなければ、そのポリシーの組み込みデフォルト値が使用されます。`policyParams` を設定しないユーザーは、以前のバージョンと同じ動作になります。 -ポリシーのパラメーターブロック内の未知のキーは、フック実行時には無視されますが、`failproofai policies` を実行すると警告としてフラグが立てられます。 +ポリシーのパラメーターブロック内の未知のキーは、フック実行時には無視されますが、`failproofai policies` を実行すると警告として表示されます。 #### `hint`（横断的設定） -型：`string`（省略可能） +型: `string`（省略可能） -ポリシーが `deny` または `instruct` を返したときに、その理由に追加されるメッセージです。ポリシー自体を変更せずに Claude に実行可能なガイダンスを提供するために使用します。 +ポリシーが `deny` または `instruct` を返す際に、理由として追記されるメッセージです。ポリシー自体を変更せずに Claude へ具体的な指示を伝えるために使用します。 -組み込みポリシー、カスタムポリシー（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）など、あらゆるポリシータイプで使用できます。 +組み込み、カスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）など、あらゆるポリシータイプで使用できます。 ```json { @@ -141,40 +141,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 ` を実行すると自動的に設定されます（パスは保存前に絶対パスに解決されます）。 +カスタムフックポリシーを含む JavaScript ファイルへのパス。`failproofai policies --install --custom ` によって自動的に設定されます（パスは保存前に絶対パスに解決されます）。 -このファイルはフックイベントのたびに新たに読み込まれます。キャッシュは行われません。作成方法の詳細は [Custom Policies](/ja/custom-policies) を参照してください。 +ファイルはフックイベントのたびに再読み込みされます。キャッシュは行われません。作成方法の詳細は[カスタムポリシー](/ja/custom-policies)を参照してください。 ### 規約ベースのポリシー -明示的な `customPoliciesPath` に加え、failproofai は `.failproofai/policies/` ディレクトリからポリシーファイルを自動的に検出して読み込みます： +明示的な `customPoliciesPath` に加えて、failproofai は `.failproofai/policies/` ディレクトリからポリシーファイルを自動的に検出してロードします： | レベル | ディレクトリ | スコープ | -|-------|------------|---------| -| プロジェクト | `.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` が最初のスコープ優先なのとは異なります）。 -詳細と例については [Custom Policies](/ja/custom-policies) を参照してください。 +詳細と例は[カスタムポリシー](/ja/custom-policies)を参照してください。 ### `llm` -型：`object`（省略可能） +型: `object`（省略可能） -AI 呼び出しを行うポリシー向けの LLM クライアント設定。ほとんどの環境では不要です。 +AI 呼び出しを行うポリシーのための LLM クライアント設定。ほとんどの環境では不要です。 ```json { @@ -189,19 +189,20 @@ AI 呼び出しを行うポリシー向けの LLM クライアント設定。ほ ## CLI からの設定管理 -`policies --install` および `policies --uninstall` コマンドはエージェント CLI のフック設定ファイル（フックエントリーポイント）に書き込みますが、`policies-config.json` は直接管理するファイルです。この2つは別物です： +`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` マーカーが付きます。Copilot CLI サポートは、公開ドキュメントに仕様が記載されていない `events.jsonl` レコードスキーマを実際のセッションで検証中のため、**ベータ版**です。 - - **Cursor Agent _(beta)_**：`~/.cursor/hooks.json`（ユーザー）、`/.cursor/hooks.json`（プロジェクト） — Cursor には `local` スコープがありません。フックエントリーは Claude 形式の `{type, command, timeout}` を使用しますが、Cursor の [hooks スキーマ](https://cursor.com/docs/hooks) に従い、フラット配列内の camelCase イベントキー（`preToolUse`、`beforeSubmitPrompt` など）に保存され、ファイルにはトップレベルの `version: 1` マーカーが付きます。ハンドラーは `CURSOR_EVENT_MAP` を介して camelCase → PascalCase に正規化するため、既存の組み込みポリシーはそのまま動作します。Cursor Agent サポートは、公開ドキュメントに記載されていない Cursor のディスク上トランスクリプト形式を実際のインストールで検証中のため、**ベータ版**です。 - - **OpenCode _(beta)_**：`~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs`（ユーザー）、`/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs`（プロジェクト） — OpenCode には `local` スコープがありません。他の6つの 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` は通知専用でスローは no-op のため、強制リトライの唯一のチャンネル）、allow には no-op。シムはツール名（小文字 → 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 のツール呼び出しでもそのまま動作します。セッションは `~/.local/share/opencode/opencode.db` の OpenCode の SQLite DB に保存され、ダッシュボードのセッションビューアーは `opencode db --format json` と `opencode export ` を介して読み取ります。OpenCode サポートは、バージョン間の動作と実際のセッションの検証中のため、**ベータ版**です。[OpenCode plugins ドキュメント](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` を介して 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 とセッションログのレイアウトが安定するまで**ベータ版**です。 - - **Gemini CLI _(beta)_**：`~/.gemini/settings.json`（ユーザー）、`/.gemini/settings.json`（プロジェクト） — Gemini には `local` スコープがありません（failproofai が公開していない `/etc/gemini-cli/settings.json` の `system` スコープがドキュメントに記載されています）。フックエントリーは Claude の `{type, command, timeout}` 形式を Gemini の `{matcher, hooks: [...]}` マッチャースキーマでラップし、デフォルトで `matcher: "*"` を使用します。イベントは PascalCase（`SessionStart`、`BeforeAgent`、`AfterAgent`、`BeforeModel`、`AfterModel`、`BeforeToolSelection`、`BeforeTool`、`AfterTool`、`PreCompress`、`Notification`、`SessionEnd`）で、ハンドラーは `GEMINI_EVENT_MAP` を介して Claude の正規名にマッピングします。ツール名は snake_case（`run_shell_command`、`read_file`、`write_file`、`replace` など）で、ハンドラーは `GEMINI_TOOL_MAP` を介して正規化するため、既存の組み込みポリシーはそのまま動作します。ポリシーエバリュエーターは Gemini のフラットな `{decision: "deny", reason}` 形式（Gemini の「Golden Rule」exit-0 コントラクトに従い推奨）、BeforeAgent / AfterTool / SessionStart のコンテキスト注入には `{hookSpecificOutput: {hookEventName, additionalContext}}`、AfterAgent の強制リトライには `{decision: "block", reason}` を出力します。Gemini CLI サポートは、実世界のカバレッジを拡大しながら**ベータ版**です。[Gemini CLI hooks ドキュメント](https://geminicli.com/docs/hooks/)を参照してください。 -- **`policies-config.json`** — failproofai が評価するポリシーとそのパラメーターを指定します（すべてのエージェント CLI で共通） +- **エージェント 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` スコープがありません。他の6つの 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 のサポートは**ベータ版**です。 + - **Gemini CLI _(beta)_**: `~/.gemini/settings.json`（ユーザー）、`/.gemini/settings.json`（プロジェクト）— Gemini には `local` スコープがありません（failproofai が公開していない `/etc/gemini-cli/settings.json` の `system` スコープを文書化しています）。フックエントリは Claude の `{type, command, timeout}` 形式を Gemini の `{matcher, hooks: [...]}` マッチャースキーマでラップし、デフォルトで `matcher: "*"` を使用します。イベントは PascalCase（`SessionStart`、`BeforeAgent`、`AfterAgent`、`BeforeModel`、`AfterModel`、`BeforeToolSelection`、`BeforeTool`、`AfterTool`、`PreCompress`、`Notification`、`SessionEnd`）で、ハンドラーは `GEMINI_EVENT_MAP` を通じて Claude の標準名にマッピングします。ツール名はスネークケース（`run_shell_command`、`read_file`、`write_file`、`replace` など）で、ハンドラーは `GEMINI_TOOL_MAP` を通じて正規化するため、既存の組み込みポリシーはそのまま動作します。ポリシー評価器は Gemini のフラットな `{decision: "deny", reason}` 形式（Gemini の「ゴールデンルール」exit-0 契約に基づく推奨）、BeforeAgent / AfterTool / SessionStart でのコンテキスト注入用 `{hookSpecificOutput: {hookEventName, additionalContext}}`、AfterAgent での強制リトライセマンティクス用 `{decision: "block", reason}` を出力します。実際の使用環境でのカバレッジを拡大中のため、Gemini CLI のサポートは**ベータ版**です。[Gemini CLI フックドキュメント](https://geminicli.com/docs/hooks/)を参照してください。 + - **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|gemini` を渡します（スペース区切りまたは繰り返しで任意のサブセットを指定）： +特定のエージェントを対象にするには `--cli claude|codex|copilot|cursor|opencode|pi|gemini|hermes` を渡します（スペース区切りまたは繰り返しで複数指定可能）： ```bash failproofai policies --install --cli codex --scope project @@ -210,21 +211,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 gemini --scope project +failproofai policies --install --cli hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` -`--cli` を省略した場合、`failproofai` はインストール済みのエージェント CLI を自動検出します（`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`）： +`--cli` を省略すると、`failproofai` はインストール済みのエージェント CLI を自動検出します（`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini` / `which hermes`）： -- **1つの CLI を検出** — プロンプトなしでその CLI を自動選択します。 -- **インタラクティブなターミナルで複数の 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 にインストールします。 -- **検出なし** — `claude` にフォールバックし、PATH にエージェントバイナリが見つからなかったという警告を表示します。フックコマンドは引き続き書き込まれるため、CLI をインストールした時点で有効になります。 +- **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` にフォールバックします。フックコマンドは書き込まれるため、インストール後すぐに有効になります。 `policies-config.json` はいつでも直接編集できます。変更は次のフックイベント時に即座に反映され、再起動は不要です。 --- -## 例：チームのデフォルト設定を含むプロジェクトレベルの設定 +## 例：チームデフォルトを含むプロジェクトレベルの設定 `.failproofai/policies-config.json` をリポジトリにコミットします： @@ -245,4 +247,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi gem } ``` -各開発者はチームメンバーに影響を与えることなく、個人用のオーバーライドとして `.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 b0984533..44f1c94d 100644 --- a/docs/ja/custom-policies.mdx +++ b/docs/ja/custom-policies.mdx @@ -1,10 +1,10 @@ --- title: カスタムポリシー -description: "JavaScriptで独自のポリシーを作成 — 規約の強制、ドリフトの防止、障害の検出、外部システムとの連携" +description: "JavaScriptで独自のポリシーを記述する — 規約の適用、ドリフトの防止、障害の検出、外部システムとの連携" icon: code --- -カスタムポリシーを使うと、あらゆるエージェントの動作に対してルールを記述できます。プロジェクト規約の強制、ドリフトの防止、破壊的操作のゲート処理、スタックしたエージェントの検出、Slackや承認ワークフローとの連携など、さまざまな用途に対応しています。組み込みポリシーと同じフックイベントシステムと `allow`、`deny`、`instruct` の判定を使用します。 +カスタムポリシーを使うと、エージェントのあらゆる動作に対してルールを記述できます。プロジェクトの規約を強制する、ドリフトを防ぐ、破壊的な操作にゲートをかける、スタックしたエージェントを検出する、Slack・承認ワークフローなどと連携する、といった用途に活用できます。組み込みポリシーと同じフックイベントシステムおよび `allow`、`deny`、`instruct` の判定を使用します。 --- @@ -37,30 +37,30 @@ failproofai policies --install --custom ./my-policies.js --- -## カスタムポリシーの2つの読み込み方法 +## カスタムポリシーを読み込む2つの方法 ### オプション1: 規約ベース（推奨） -`*policies.{js,mjs,ts}` ファイルを `.failproofai/policies/` に配置するだけで自動的に読み込まれます。フラグや設定変更は不要です。gitフックと同じ仕組みで、ファイルを置くだけで動作します。 +`*policies.{js,mjs,ts}` ファイルを `.failproofai/policies/` に置くだけで自動的に読み込まれます — フラグや設定変更は不要です。gitフックと同じ感覚で、ファイルを置けばすぐに動きます。 ``` # プロジェクトレベル — gitにコミットしてチームで共有 .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# ユーザーレベル — 個人用、すべてのプロジェクトに適用 +# ユーザーレベル — 個人用、全プロジェクトに適用 ~/.failproofai/policies/my-policies.mjs ``` **動作の仕組み:** -- プロジェクトとユーザーの両ディレクトリがスキャンされます（和集合 — スコープ優先ではありません） -- ファイルは各ディレクトリ内でアルファベット順に読み込まれます。順序を制御するには `01-`、`02-` などのプレフィックスを付けてください +- プロジェクトとユーザー両方のディレクトリがスキャンされます（和集合 — スコープ優先ではありません） +- 各ディレクトリ内ではアルファベット順に読み込まれます。`01-`、`02-` のようなプレフィックスで順序を制御できます - `*policies.{js,mjs,ts}` にマッチするファイルのみ読み込まれ、それ以外は無視されます - 各ファイルは独立して読み込まれます（ファイル単位でフェイルオープン） -- 明示的な `--custom` や組み込みポリシーと共存できます +- 明示的な `--custom` フラグや組み込みポリシーと併用できます -規約ポリシーは、組織の品質基準を構築する最も簡単な方法です。`.failproofai/policies/` をgitにコミットすれば、開発者ごとのセットアップなしにすべてのチームメンバーが同じルールを自動的に適用できます。新しい障害パターンを発見したらポリシーを追加してプッシュするだけで、継続的に改善される生きた品質基準が積み上がっていきます。 +規約ポリシーは、組織の品質基準を構築する最も簡単な方法です。`.failproofai/policies/` をgitにコミットすれば、すべてのチームメンバーが自動的に同じルールを適用できます — 開発者ごとのセットアップは不要です。チームが新たな障害パターンを発見するたびにポリシーを追加してプッシュすれば、コントリビューションのたびに改善されていくリビングな品質基準になります。 ### オプション2: 明示的なファイルパス @@ -69,16 +69,16 @@ failproofai policies --install --custom ./my-policies.js # カスタムポリシーファイルを指定してインストール failproofai policies --install --custom ./my-policies.js -# ポリシーファイルのパスを変更 +# ポリシーファイルのパスを置き換え failproofai policies --install --custom ./new-policies.js -# 設定からカスタムポリシーのパスを削除 +# 設定からカスタムポリシーパスを削除 failproofai policies --uninstall --custom ``` -解決された絶対パスは `policies-config.json` の `customPoliciesPath` に保存されます。ファイルはフックイベントのたびに新たに読み込まれ、イベント間でのキャッシュはありません。 +解決された絶対パスは `policies-config.json` の `customPoliciesPath` として保存されます。ファイルはフックイベントのたびに新たに読み込まれ、イベント間でのキャッシュはありません。 -### 両方を組み合わせて使う +### 両方を併用する 規約ポリシーと明示的な `--custom` ファイルは共存できます。読み込み順序: @@ -98,45 +98,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -ポリシーを登録します。1つのファイルに複数のポリシーを定義する場合は、必要なだけ呼び出せます。 +ポリシーを登録します。同一ファイルに複数のポリシーを定義する場合は、必要な回数だけ呼び出せます。 ```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)` — メッセージは `"Blocked by failproofai:"` というプレフィックスを付けて Claude に表示されます。1つの `deny` が発生すると、それ以降の評価はすべて短絡します。 -`instruct(message)` — メッセージは現在のツール呼び出しに対する Claude のコンテキストに追記されます。すべての `instruct` メッセージは蓄積されてまとめて配信されます。 +`instruct(message)` — メッセージは現在のツール呼び出しに対する Claude のコンテキストに追記されます。すべての `instruct` メッセージは蓄積されて一括して配信されます。 -`deny` や `instruct` のメッセージに追加のガイダンスを付け加えるには、`policyParams` の `hint` フィールドを使います — コードの変更は不要です。カスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）ポリシーでも機能します。詳細は [設定 → hint](/ja/configuration#hint-cross-cutting) を参照してください。 +`deny` または `instruct` メッセージに追加のガイダンスを付け加えるには、`policyParams` の `hint` フィールドを使います — コード変更は不要です。カスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）ポリシーでも機能します。詳細は[設定 → hint](/ja/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 に伝える -- **フェイルオープンの説明:** `allow("GitHub CLI not installed, skipping CI check.")` — チェックがスキップされた理由を Claude に伝え、完全なコンテキストを提供する -- **複数メッセージの蓄積:** 複数のポリシーがそれぞれ `allow(message)` を返した場合、すべてのメッセージが改行で結合されてまとめて配信される +- **フェイルオープンの説明:** `allow("GitHub CLI not installed, skipping CI check.")` — チェックがスキップされた理由を Claude に伝えて完全なコンテキストを提供する +- **複数メッセージの蓄積:** 複数のポリシーがそれぞれ `allow(message)` を返した場合、すべてのメッセージは改行で結合されて一括配信されます ```js customPolicies.add({ @@ -146,7 +146,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."); } @@ -162,7 +162,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,7 +178,7 @@ customPolicies.add({ | イベント | 発火タイミング | `toolInput` の内容 | |-------|--------------|----------------------| | `PreToolUse` | Claude がツールを実行する前 | ツールの入力（例: Bash の場合 `{ command: "..." }`） | -| `PostToolUse` | ツールの実行完了後 | ツールの入力 + `tool_result`（出力） | +| `PostToolUse` | ツールが完了した後 | ツールの入力 + `tool_result`（出力） | | `Notification` | Claude が通知を送信するとき | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — フックは常に `allow()` を返す必要があり、通知をブロックすることはできません | | `Stop` | Claude セッションが終了するとき | 空 | @@ -189,19 +189,19 @@ 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` メッセージは蓄積されて一括配信されます。 --- -## 推移的なインポート +## 推移的インポート -カスタムポリシーファイルは相対パスを使ってローカルモジュールをインポートできます: +カスタムポリシーファイルは相対パスを使用してローカルモジュールをインポートできます: ```js // my-policies.js @@ -218,21 +218,21 @@ 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(); }, }); @@ -244,20 +244,20 @@ customPolicies.add({ ## エラー処理と障害モード -カスタムポリシーは**フェイルオープン**です。エラーが発生しても組み込みポリシーをブロックしたり、フックハンドラーをクラッシュさせたりすることはありません。 +カスタムポリシーは**フェイルオープン**です: エラーが発生しても組み込みポリシーをブロックしたり、フックハンドラーをクラッシュさせたりすることはありません。 | 障害 | 動作 | |---------|----------| -| `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 +266,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 +285,7 @@ customPolicies.add({ }, }); -// エージェントを正しい方向に維持: コミット前にテストを確認 +// エージェントをトラックに乗せる: コミット前にテストを確認 customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +300,7 @@ customPolicies.add({ }, }); -// フリーズ期間中の計画外の依存関係変更を防ぐ +// フリーズ期間中の予期しない依存関係の変更を防止 customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -321,24 +321,24 @@ export { customPolicies }; --- -## サンプル集 +## サンプル `examples/` ディレクトリにはすぐに使えるポリシーファイルが含まれています: | ファイル | 内容 | |------|----------| -| `examples/policies-basic.js` | 一般的なエージェント障害モードをカバーする5つのスターターポリシー | -| `examples/policies-advanced/index.js` | 高度なパターン: 推移的なインポート、非同期呼び出し、出力のスクラビング、セッション終了フック | -| `examples/convention-policies/security-policies.mjs` | 規約ベースのセキュリティポリシー（.env ファイルへの書き込みのブロック、git 履歴の書き換え防止） | +| `examples/policies-basic.js` | エージェントの一般的な障害モードをカバーする5つのスターターポリシー | +| `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 ``` -### 規約ベースのサンプルの使い方 +### 規約ベースのサンプルを使用する ```bash # プロジェクトレベルにコピー @@ -350,4 +350,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 051ebea6..5462eed4 100644 --- a/docs/ja/dashboard.mdx +++ b/docs/ja/dashboard.mdx @@ -1,10 +1,10 @@ --- title: ダッシュボード -description: "エージェントセッションの監視、ツール呼び出しの確認、ポリシーの管理" +description: "エージェントセッションの監視、ツールコールの確認、ポリシーの管理" icon: chart-line --- -failproofai ダッシュボードは、AIエージェントセッションの監視とポリシー管理を行うローカルWebアプリケーションです。あなたが離れている間にエージェントが何をしていたかを確認できます。 +failproofai ダッシュボードは、AIエージェントセッションの監視とポリシー管理のためのローカルWebアプリケーションです。作業中にエージェントが何を行ったかを確認できます。 --- @@ -16,7 +16,7 @@ failproofai `http://localhost:8020` で開きます。 -ダッシュボードはファイルシステムから直接読み取ります。Claude Code のプロジェクトフォルダーと failproofai の設定ファイルを参照しており、リモートサービスへの書き込みは一切行いません。 +ダッシュボードはファイルシステムから直接読み取ります — Claude Code のプロジェクトフォルダと failproofai の設定ファイルを参照します。リモートサービスへの書き込みは一切行われません。 --- @@ -24,67 +24,67 @@ failproofai ### プロジェクト -マシン上で見つかった Claude Code、OpenAI Codex、GitHub Copilot CLI _(ベータ)_、Cursor Agent _(ベータ)_、OpenCode _(ベータ)_、Pi _(ベータ)_、Gemini CLI _(ベータ)_ のすべてのプロジェクトを一覧表示します。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` を取得して検出されます。Gemini CLI プロジェクトは `~/.gemini/tmp//chats/session--.jsonl`（`GEMINI_SESSIONS_DIR` で設定可能）をスキャンし、隣接する `.project_root` テキストマーカーから正規の cwd を復元して検出されます。複数の CLI で使用されたプロジェクトは、すべての一致するバッジを持つ単一の行として表示されます。テーブル上部の **CLI** ドロップダウンで特定のエージェント CLI に絞り込めます。URLには選択内容が `?cli=claude|codex|copilot|cursor|opencode|pi|gemini` として保持されます。 +マシン上で見つかったすべての Claude Code、OpenAI Codex、GitHub Copilot CLI _(ベータ)_、Cursor Agent _(ベータ)_、OpenCode _(ベータ)_、Pi _(ベータ)_、Gemini CLI _(ベータ)_、および Hermes プロジェクトを一覧表示します。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` を取得することで検出されます。Gemini CLI プロジェクトは `~/.gemini/tmp//chats/session--.jsonl`（`GEMINI_SESSIONS_DIR` で設定可能）をスキャンし、隣接する `.project_root` テキストマーカーから正規の cwd を復元することで検出されます。Hermes ゲートウェイセッションは `~/.hermes/state.db`（`HERMES_DB_PATH` で設定可能）の SQLite ストアから直接読み取られ、`source`（Slack/Telegram/cli/cron — ゲートウェイセッションには cwd がありません）によって `hermes-` プロジェクトにグループ化されます。複数の CLI で使用されたプロジェクトは、該当するすべてのバッジを付けた1行として表示されます。テーブル上部の **CLI** ドロップダウンを使用して特定のエージェント CLI でフィルタリングできます。URLには選択内容が `?cli=claude|codex|copilot|cursor|opencode|pi|gemini|hermes` として保持されます。 各プロジェクトには以下が表示されます： -- プロジェクト名（フォルダーパスから導出） -- CLI バッジ — `Claude Code`（オレンジ）、`OpenAI Codex`（パープル）、`GitHub Copilot`（ブルー）、`Cursor Agent`（エメラルド）、`OpenCode`（アンバー）、`Pi`（ピンク）、`Gemini CLI`（スカイ） -- 最新セッションアクティビティの日付 +- プロジェクト名（フォルダパスから導出） +- CLI バッジ — `Claude Code`（オレンジ）、`OpenAI Codex`（パープル）、`GitHub Copilot`（ブルー）、`Cursor Agent`（エメラルド）、`OpenCode`（アンバー）、`Pi`（ピンク）、`Gemini CLI`（スカイ）、および/または `Hermes`（インディゴ） +- 最新のセッションアクティビティの日付 -プロジェクトをクリックするとそのセッション一覧が表示されます。 +プロジェクトをクリックするとそのセッションが表示されます。 ### セッション プロジェクト内のすべてのセッションを一覧表示します。各セッションには以下が表示されます： - セッション ID - 開始・終了タイムスタンプ -- ツール呼び出し回数 -- フックアクティビティ数（発火したポリシーの数） +- ツールコール数 +- フックアクティビティ数（発動したポリシー） -日付範囲フィルターとセッション ID 検索で絞り込みができます。セッションはページネーションされています。 +日付範囲フィルターとセッション ID 検索でリストを絞り込めます。セッションはページ分割されます。 セッションをクリックするとセッションビューアーが開きます。 ### セッションビューアー -セッションビューアーは、自律型エージェントにとって重要な問いに答えます：エージェントは何をしたのか、そして想定通りに動作していたのか？ヘッダーの横の CLI バッジが、セッションが Claude Code、OpenAI Codex、GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Gemini CLI のどのトランスクリプトかを示します。セッション内で起きたことのタイムラインが表示されます： +セッションビューアーは、自律エージェントにとっての核心的な問いに答えます：エージェントは何を行い、正しく動作していたか？ヘッダー横の CLI バッジは、セッションが Claude Code、OpenAI Codex、GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Gemini CLI、または Hermes のトランスクリプトであるかを示します。セッション内で起きたすべてのことのタイムラインが表示されます： -- **メッセージ** — Claudeのテキスト応答とユーザープロンプト -- **ツール呼び出し** — Claudeが呼び出したすべてのツールとその入力・出力 -- **ポリシーアクティビティ** — 各ツール呼び出しに対して、どのポリシーが発火しどの判断が返されたか +- **メッセージ** - Claude のテキスト応答とユーザープロンプト +- **ツールコール** - Claude が呼び出したすべてのツール（入力と出力を含む） +- **ポリシーアクティビティ** - 各ツールコールに対して発動したポリシーとその判定結果 -上部のスタッツバーにはセッション時間、合計ツール呼び出し数、フック判断のサマリー（allow / deny / instruct の件数）が表示されます。 +上部のステータスバーには、セッション時間、総ツールコール数、フック判定のサマリー（allow / deny / instruct の件数）が表示されます。 -**ログをダウンロード** ボタンをクリックするとセッションをエクスポートできます。Claude Code、Codex、Copilot、Cursor、Pi、Gemini のセッションはディスク上の元の JSONL トランスクリプトがバイト単位でそのまま取得されます。OpenCode（セッションがディスクではなく SQLite に保存される）では、`session` / `messages` / `parts` テーブルのデータを反映した JSON ドキュメントが取得されます。 +**ログをダウンロード** ボタンをクリックするとセッションをエクスポートできます。Claude Code、Codex、Copilot、Cursor、Pi、Gemini のセッションはディスク上の JSONL トランスクリプトをバイト単位でそのまま取得できます。OpenCode（セッションがディスク上ではなく SQLite に保存されている）の場合は、基礎となる `session` / `messages` / `parts` テーブルを反映した JSON ドキュメントが取得されます。 ### 監査 -過去のセッション全体にわたるエージェントの実際の挙動を個性的なレポートとして表示します。`failproofai audit` CLI と同じスキャンを実行しますが、単一画面の共有可能なポスターと折り畳み以降の4つのセクションとしてレンダリングされます： +過去のセッション全体でエージェントが実際にどのように行動していたかを個性的なレポートとして表示します。`failproofai audit` CLI と同じスキャンを実行し、1画面で共有可能なポスターと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行の説明、右側にインストールコマンド＋コピーボタン。セクションヘッダーには `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` に転送され、`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 インテント）、`share on linkedin`、`download poster`。キャプチャは `html-to-image` を通じて実行されるため、PNG は画面上のレンダリングとピクセル単位で一致します（破線の境界線、SVG ロゴマスク、グラデーション、フォントメトリクス — すべて保持）。 +2. **強み** — エージェントがすでに正しく行っている動作の穏やかな ✓ 行リスト。ライブ監査データから導出されます（クリーンなツールコール率、main への直接プッシュなし、認証情報の漏洩ゼロ、リトライストームなし）— 監査ウィンドウ全体でクリーンな記録を持つポリシーに関連するもののみ表示されます。 +3. **問題点** — 見逃された内容を深刻度順にランク付けしたテーブル：`いつ · 何が漏れたか + それを検出したはずのポリシー · 深刻度ピル · 発生回数`。再発回数は `new`（1回）、`N× seen`（2〜9回）、`recurring`（10回以上）と表示されます。 +4. **改善方法** — 推奨ポリシーごとの穏やかな行リスト：白いポリシー名、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` に誘導されます。権利付与 / 特典の履行は今後対応予定です。 -`failproofai audit` ランタイムで動作します。基盤となるスキャンエンジン、サポートされるフラグ、トランスクリプトごとのキャッシュの動作については [Audit CLI](/ja/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 audit` ランタイムによって駆動されます — 基礎となるスキャンエンジン、サポートされているフラグ、トランスクリプトごとのキャッシュの不変条件については [監査 CLI](/ja/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`）に基づいたコピーが表示されます。空の状態（キャッシュなしまたは期限切れ）とセッションゼロの状態（キャッシュは存在するがスキャンでトランスクリプトが見つからなかった）は別々に表示されます。 ### ポリシー -ポリシーの管理とアクティビティの確認を行う2タブのページです。 +ポリシーの管理とアクティビティの確認のための2タブページ。 - - 単一のパネルから failproofai が保護するエージェント CLI を複数選択できます — Claude Code、OpenAI Codex、GitHub Copilot、Cursor Agent、OpenCode、Pi、Gemini CLI それぞれの行にインストール状態（`Active` / `Detected` / `Inactive`）、ユーザースコープの設定パス、ブランドカラーのアクセントが表示されます。有効にしたい CLI にチェックを入れ、`Apply changes` をクリックすると差分が一括でインストール／アンインストールされます。PATH 上でバイナリが検出された CLI は事前にチェックされています。 - - 個々のポリシーをクリック一つでオン／オフに切り替えられます（`~/.failproofai/policies-config.json` に書き込まれ、インストール済みのすべての CLI で共有されます） - - ポリシーを展開してパラメーターを設定できます（`policyParams` をサポートするポリシーのみ） - - カスタムポリシーファイルのパスを設定できます + - 1つのパネルから failproofai が保護するエージェント CLI を複数選択できます — Claude Code、OpenAI Codex、GitHub Copilot、Cursor Agent、OpenCode、Pi、Gemini CLI、および Hermes にはそれぞれインストール状況（`Active` / `Detected` / `Inactive`）、ユーザースコープの設定パス、ブランドカラーのアクセントを持つ行があります。対象の CLI にチェックを入れるか外して `Apply changes` をクリックすると、差分を1ステップでインストール/アンインストールできます。PATH 上でバイナリが検出された CLI は事前にチェックされています。 + - 個別のポリシーをワンクリックで有効/無効に切り替えます（`~/.failproofai/policies-config.json` に書き込まれます — インストールされたすべての CLI で共有） + - パラメーターをサポートするポリシーの設定を展開して変更します（`policyParams` をサポートするポリシーの場合） + - カスタムポリシーファイルのパスを設定します - - すべてのセッションにわたって発火したすべてのフックイベントのフルページネーション履歴 - - 判断、イベントタイプ、CLI（Claude Code / OpenAI Codex / GitHub Copilot _(ベータ)_ / Cursor Agent _(ベータ)_ / OpenCode _(ベータ)_ / Pi _(ベータ)_ / Gemini CLI _(ベータ)_）、ポリシー名、セッション ID でフィルタリング可能 - - 各行には：タイムスタンプ、ポリシー名、判断、CLI バッジ（オレンジ = Claude Code、パープル = OpenAI Codex、ブルー = GitHub Copilot、エメラルド = Cursor Agent、アンバー = OpenCode、ピンク = Pi、スカイ = Gemini CLI）、ツール名、セッション 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`、Gemini CLI `~/.gemini/tmp//chats/.jsonl`）を自動検出し、ヘッダーに対応する CLI バッジを表示します + - すべてのセッションで発動したすべてのフックイベントの完全なページ分割履歴 + - 判定、イベントタイプ、CLI（Claude Code / OpenAI Codex / GitHub Copilot _(ベータ)_ / Cursor Agent _(ベータ)_ / OpenCode _(ベータ)_ / Pi _(ベータ)_ / Gemini CLI _(ベータ)_ / Hermes）、ポリシー名、またはセッション ID でフィルタリング + - 各行には：タイムスタンプ、ポリシー名、判定、CLI バッジ（オレンジ = Claude Code、パープル = OpenAI Codex、ブルー = GitHub Copilot、エメラルド = Cursor Agent、アンバー = OpenCode、ピンク = Pi、スカイ = Gemini CLI、インディゴ = Hermes）、ツール名、セッション 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`、Gemini CLI `~/.gemini/tmp//chats/.jsonl`、Hermes `~/.hermes/state.db`）、ヘッダーに対応する CLI バッジを表示します @@ -92,13 +92,13 @@ failproofai ## 自動更新 -ダッシュボードの上部ナビゲーションには自動更新トグルがあります。有効にすると、現在のページが定期的に更新され、新しいセッションやポリシーアクティビティが表示されます。長時間動作する自律型エージェントセッションの監視に不可欠です。 +ダッシュボードの上部ナビゲーションには自動更新トグルがあります。有効にすると、現在のページが定期的に更新され、新しいセッションとポリシーアクティビティがリアルタイムで表示されます。長時間実行される自律エージェントセッションの監視に不可欠です。 --- ## ページの無効化 -ダッシュボードの一部のみ必要な場合は、`FAILPROOFAI_DISABLE_PAGES` にカンマ区切りのページ名リストを設定します： +ダッシュボードの一部のみが必要な場合は、`FAILPROOFAI_DISABLE_PAGES` にページ名のカンマ区切りリストを設定します： ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -110,7 +110,7 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## プロジェクトパスの設定 -デフォルトでは、ダッシュボードは標準の Claude Code プロジェクトディレクトリから読み取ります。カスタム設定の場合は上書きできます： +デフォルトでは、ダッシュボードは標準の Claude Code プロジェクトディレクトリから読み取ります。カスタム設定の場合はオーバーライドしてください： ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,30 +120,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". ``` -これは、開発専用機能である HMR（ホットモジュールリロード）WebSocket へのクロスオリジンアクセスを Next.js がブロックしているためです。ホストを許可するには `--allowed-origins` フラグを使用します： +これは、Next.js が HMR（ホットモジュールリロード）WebSocket へのクロスオリジンアクセスをブロックしているためです。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 WebSocket もクロスオリジン開発リソースの問題も発生しません。 \ No newline at end of file diff --git a/docs/ja/examples.mdx b/docs/ja/examples.mdx index c92d0aec..32391816 100644 --- a/docs/ja/examples.mdx +++ b/docs/ja/examples.mdx @@ -1,16 +1,16 @@ --- title: 使用例 -description: "Claude CodeとAgents SDKにフックを設定する方法" +description: "Claude Code と Agents SDK にフックを設定する方法" icon: book-open --- -一般的なシナリオですぐに使えるサンプル集です。各例では、インストール方法と期待される動作を説明しています。 +よくあるシナリオに対応したすぐに使える使用例です。インストール方法と期待される動作を紹介します。 --- -## Claude Code にフックを設定する +## Claude Code へのフック設定 -Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.com/en/docs/claude-code/hooks)を通じて統合されます。`failproofai policies --install` を実行すると、ツール呼び出しのたびに発火するフックコマンドが Claude Code の `settings.json` に登録されます。 +Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.com/en/docs/claude-code/hooks)を通じて統合されます。`failproofai policies --install` を実行すると、すべてのツール呼び出し時に起動するフックコマンドが Claude Code の `settings.json` に登録されます。 @@ -35,13 +35,13 @@ Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.c claude ``` - これでポリシーがすべてのツール呼び出しに対して自動的に実行されます。Claude に `sudo rm -rf /` を実行するよう指示してみてください。ブロックされます。 + すべてのツール呼び出しでポリシーが自動的に実行されます。Claude に `sudo rm -rf /` を実行するよう指示してみてください — ブロックされます。 --- -## Agents SDK にフックを設定する +## Agents SDK へのフック設定 [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) を使って開発している場合、同じフックシステムをプログラムから利用できます。 @@ -52,14 +52,14 @@ Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.c ``` - エージェントプロセスの作成時にフックコマンドを渡します。フックは Claude Code と同様に stdin/stdout の JSON 経由で発火します： + エージェントプロセスの作成時にフックコマンドを渡します。フックは Claude Code と同じように stdin/stdout の JSON を介して起動します。 ```bash - failproofai --hook PreToolUse # ツール実行前に呼び出される - failproofai --hook PostToolUse # ツール実行後に呼び出される + failproofai --hook PreToolUse # 各ツールの呼び出し前に実行 + failproofai --hook PostToolUse # 各ツールの呼び出し後に実行 ``` - + ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -88,15 +88,15 @@ Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.c ## 破壊的なコマンドをブロックする -最も一般的な設定です。エージェントが取り消し不能な操作を行わないようにします。 +最も一般的なセットアップ — エージェントが取り返しのつかない操作を行うのを防ぎます。 ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` -各ポリシーの効果： +このコマンドの動作： - `block-sudo` — すべての `sudo` コマンドをブロック -- `block-rm-rf` — ファイルの再帰的削除をブロック +- `block-rm-rf` — 再帰的なファイル削除をブロック - `block-force-push` — `git push --force` をブロック - `block-curl-pipe-sh` — リモートスクリプトをシェルにパイプする操作をブロック @@ -104,19 +104,19 @@ failproofai policies --install block-sudo block-rm-rf block-force-push block-cur ## シークレットの漏洩を防ぐ -ツールの出力から認証情報が見えたり漏洩したりするのを防ぎます。 +エージェントがツールの出力からクレデンシャルを参照・漏洩するのを防ぎます。 ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -これらは `PostToolUse` で発火します。ツール実行後、エージェントが出力を受け取る前にスクラブ処理が行われます。 +これらは `PostToolUse` で起動します — ツール実行後、エージェントが出力を受け取る前にクレデンシャル情報を除去します。 --- -## エージェントが待機中のときに Slack 通知を送る +## エージェントが注意を要するときに Slack へ通知する -通知フックを使って、アイドル通知を Slack に転送します。 +通知フックを使って、アイドル状態のアラートを Slack に転送します。 ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -142,7 +142,7 @@ customPolicies.add({ signal: AbortSignal.timeout(5000), }); } catch { - // Slack に接続できなくてもエージェントをブロックしない + // Slack に接続できない場合でもエージェントをブロックしない } return allow(); @@ -150,7 +150,7 @@ customPolicies.add({ }); ``` -インストール： +インストールする： ```bash SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js @@ -160,7 +160,7 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c ## エージェントをブランチに固定する -エージェントが他のブランチに切り替えたり、保護されたブランチにプッシュしたりするのを防ぎます。 +エージェントが別のブランチに切り替えたり、保護されたブランチにプッシュしたりするのを防ぎます。 ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -206,9 +206,9 @@ customPolicies.add({ --- -## 本番リポジトリをロックする +## 本番リポジトリをロックダウンする -プロジェクトレベルの設定をコミットすることで、チームの全メンバーが同じポリシーを適用できます。 +プロジェクトレベルの設定をコミットして、チームの全員が同じポリシーを使えるようにします。 リポジトリに `.failproofai/policies-config.json` を作成します： @@ -238,13 +238,13 @@ git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -failproofai をインストール済みのチームメンバー全員が、これらのルールを自動的に適用できます。 +failproofai をインストールしているすべてのチームメンバーがこれらのルールを自動的に取得します。 --- -## コンベンションポリシーで組織全体の品質基準を構築する +## コンベンションポリシーでorg全体の品質標準を構築する -最も効果的な設定です。プロジェクトに合わせたポリシーを `.failproofai/policies/` にコミットすることで、チームメンバー全員が自動的に適用できます。インストールコマンドや設定変更は不要です。 +最も効果的なセットアップ：プロジェクトに合わせたポリシーを含む `.failproofai/policies/` をリポジトリにコミットします。インストールコマンドや設定変更なしに、すべてのチームメンバーが自動的にポリシーを取得できます。 @@ -256,8 +256,8 @@ failproofai をインストール済みのチームメンバー全員が、こ // .failproofai/policies/team-policies.mjs import { customPolicies, allow, deny, instruct } from "failproofai"; - // チームが推奨するパッケージマネージャーを強制する - // （代わりに組み込みの prefer-package-manager ポリシーを有効にする方法もあります） + // チームが使うパッケージマネージャーを強制する + // （代わりに組み込みの prefer-package-manager ポリシーを有効にすることもできます） customPolicies.add({ name: "enforce-bun", match: { events: ["PreToolUse"] }, @@ -290,7 +290,7 @@ failproofai をインストール済みのチームメンバー全員が、こ ``` - チームで新たな問題が発生したら、ポリシーを追加してプッシュしてください。次の `git pull` 時に全員がアップデートを受け取れます。これらのポリシーはチームとともに成長する生きた品質基準となります。 + チームが新たな問題に直面したら、ポリシーを追加してプッシュします。次回の `git pull` で全員がアップデートを取得できます。これらのポリシーはチームとともに成長する、生きた品質標準になります。 @@ -298,10 +298,10 @@ failproofai をインストール済みのチームメンバー全員が、こ ## その他の使用例 -リポジトリの [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) ディレクトリには以下のファイルが含まれています： +リポジトリの [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) ディレクトリには以下が含まれています： | ファイル | 内容 | |------|---------------| -| `policies-basic.js` | 基本ポリシー — 本番環境への書き込み、force push、パイプスクリプトのブロック | -| `policies-notification.js` | アイドル通知やセッション終了時の Slack アラート | -| `policies-advanced/index.js` | 推移的インポート、非同期フック、PostToolUse による出力スクラブ、Stop イベント処理 | \ No newline at end of file +| `policies-basic.js` | 基本的なポリシー — 本番環境への書き込み、force-push、パイプスクリプトのブロック | +| `policies-notification.js` | アイドル通知とセッション終了時の Slack アラート | +| `policies-advanced/index.js` | 推移的インポート、非同期フック、PostToolUse の出力スクラビング、Stop イベントの処理 | \ No newline at end of file diff --git a/docs/ja/for-agents.mdx b/docs/ja/for-agents.mdx index de6c5c25..dd86679d 100644 --- a/docs/ja/for-agents.mdx +++ b/docs/ja/for-agents.mdx @@ -1,33 +1,33 @@ --- title: "エージェント向け" -description: "コマンド一つで Failproof AI の知識をコーディングエージェントに追加できます。Claude Code、Cursor、Windsurf などに対応しています。" +description: "1つのコマンドでコーディングエージェントに Failproof AI の知識を追加できます。Claude Code、Cursor、Windsurf などに対応しています。" --- -コマンド一つで Failproof AI の完全なリファレンスをコーディングエージェントに追加できます。Claude Code、Cursor、Windsurf、その他スキルに対応したあらゆるエージェントで動作します。 +1つのコマンドで Failproof AI のリファレンス全体をコーディングエージェントに追加できます。Claude Code、Cursor、Windsurf、およびスキルをサポートするその他のエージェントに対応しています。 ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` はインストール済みのエージェントを自動検出し、それぞれに適したフォーマットでスキルを追加します。 +`npx skills` はインストール済みのエージェントを自動検出し、各エージェントに適したフォーマットでスキルを追加します。 -## スキルがカバーする範囲 +## スキルがカバーする内容 | 領域 | 含まれる内容 | -|------|----------------| +|------|-------------| | ポリシー | 組み込みポリシー名、イベントタイプ、パラメータ、有効化/無効化 | | カスタムポリシー | `customPolicies.add()`、マッチフィルター、`allow`/`deny`/`instruct` API | | コンテキストオブジェクト | `ctx.eventType`、`ctx.toolName`、`ctx.toolInput`、`ctx.session` | | 設定 | `policies-config.json` の構造、スコープのマージ、`policyParams` | | CLI | `failproofai policies --install`、`--uninstall`、`--custom`、スコープ | -| ダッシュボード | セッションビューアー、ポリシーアクティビティ、環境変数 | +| ダッシュボード | セッションビューア、ポリシーアクティビティ、環境変数 | | アーキテクチャ | フックハンドラーのフロー、終了コード、stdin/stdout コントラクト | ## スキルは完全ですか？ -Mintlify はナビゲーション内のすべてのページから `llms.txt` を生成します。Failproof AI のドキュメントは完全な API をカバーしており、すべてのポリシー・オプション・サンプルが含まれています。不足している内容を見つけた場合は、`https://docs.befailproof.ai/llms-full.txt` がソースです。 +Mintlify はナビゲーション内のすべてのページから `llms.txt` を生成します。Failproof AI のドキュメントはすべての API を網羅しており、すべてのポリシー、オプション、サンプルが含まれています。不足している内容が見つかった場合は、`https://docs.befailproof.ai/llms-full.txt` でソースを確認できます。 -特定のコンテキストが必要な場合は、特定のページに直接リンクしてください： +特定のコンテキストのみが必要な場合は、特定のページに直接リンクできます。 ```bash # カスタムポリシー API のみ diff --git a/docs/ja/getting-started.mdx b/docs/ja/getting-started.mdx index 6537f08e..59b11f83 100644 --- a/docs/ja/getting-started.mdx +++ b/docs/ja/getting-started.mdx @@ -1,10 +1,10 @@ --- title: はじめに -description: "failproofai をインストールし、ポリシーを有効にして、エージェントを安定稼働させる" +description: "failproofai をインストールし、ポリシーを有効化して、エージェントを安定稼働させましょう" icon: rocket --- -## 必要な環境 +## 動作要件 - **Node.js** >= 20.9.0 - **Bun** >= 1.3.0（任意 — ソースからビルドする場合のみ必要） @@ -30,16 +30,16 @@ bun add -g failproofai ## クイックスタート - - ポリシーとは、エージェントのツール呼び出しの前後に実行されるルールです。破壊的なコマンド、シークレットの漏洩、その他の障害モードを、実際に被害が出る前に検出します。 + + ポリシーは、エージェントのツール呼び出しの前後に実行されるルールです。破壊的なコマンド、シークレットの漏洩、その他の障害モードを、実害が出る前に検出します。 ```bash failproofai policies --install ``` - これにより、インストール済みのエージェント CLI にフックエントリが書き込まれます（Claude Code の `~/.claude/settings.json`、OpenAI Codex の `~/.codex/hooks.json`、GitHub Copilot CLI の `~/.copilot/hooks/failproofai.json`、Cursor Agent の `~/.cursor/hooks.json`、OpenCode の `~/.config/opencode/plugins/failproofai.mjs` に生成されるプラグインシムおよび `~/.config/opencode/opencode.json` の `plugin` 配列への登録エントリ、Pi の `~/.pi/agent/settings.json`、Gemini CLI の `~/.gemini/settings.json`）。複数が存在する場合はプロンプトが表示されます。`--cli claude codex copilot cursor opencode pi gemini`（任意のサブセット）を渡すとプロンプトをスキップできます。 + このコマンドは、インストール済みのエージェント CLI にフックエントリを書き込みます（Claude Code の `~/.claude/settings.json`、OpenAI Codex の `~/.codex/hooks.json`、GitHub Copilot CLI の `~/.copilot/hooks/failproofai.json`、Cursor Agent の `~/.cursor/hooks.json`、OpenCode の `~/.config/opencode/plugins/failproofai.mjs` と `~/.config/opencode/opencode.json` の `plugin` 配列へのエントリ、Pi の `~/.pi/agent/settings.json`、Gemini CLI の `~/.gemini/settings.json`、または Hermes の `~/.hermes/config.yaml`）。複数が存在する場合はプロンプトで選択を求められます。`--cli claude codex copilot cursor opencode pi gemini hermes`（任意のサブセット）を渡すとプロンプトをスキップできます。 - GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Gemini CLI のサポートは**ベータ版**です — それぞれ `--cli copilot`、`--cli cursor`、`--cli opencode`、`--cli pi`、または `--cli gemini` でインストールしてください。 + GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Gemini CLI のサポートは**ベータ版**です — それぞれ `--cli copilot`、`--cli cursor`、`--cli opencode`、`--cli pi`、`--cli gemini` でインストールしてください。Hermes（hermes-agent、Slack/Telegram ゲートウェイ）は `--cli hermes` でユーザースコープにインストールでき、オフライン監査ソースとしても機能します。 ```bash failproofai policies --install --scope project @@ -49,6 +49,7 @@ bun add -g failproofai failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project + failproofai policies --install --cli hermes --scope user failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` @@ -57,17 +58,17 @@ bun add -g failproofai failproofai policies ``` - すべてのポリシー、有効かどうか、設定済みのパラメータが表示されます。 + すべてのポリシー、その有効・無効の状態、および設定済みパラメータが表示されます。 ```bash failproofai ``` - `http://localhost:8020` にローカルダッシュボードが開き、セッションの閲覧、ツール呼び出しの確認、ポリシーの管理ができます。 + `http://localhost:8020` にローカルダッシュボードが開きます。セッションの閲覧、ツール呼び出しの確認、ポリシーの管理が行えます。 - Claude Code をいつも通り起動します。エージェントが危険な操作を試みると、failproofai が自動的に介入します。そのまま無人で実行し、後からダッシュボードで何が起きたかを確認できます。 + Claude Code を通常通り起動してください。エージェントがリスクのある操作を試みた場合、failproofai が自動的にインターセプトします。放置したまま実行し、あとでダッシュボードで何が起きたかを確認できます。 @@ -83,21 +84,21 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON writes decision to stdout ``` -各ポリシーは次の 3 つのいずれかを返します。 +各ポリシーは次の 3 つの判定のいずれかを返します。 -- **allow** — エージェントは通常どおり処理を続行する +- **allow** — エージェントは通常通り処理を続行する - **deny** — アクションがブロックされ、エージェントにその理由が通知される -- **instruct** — エージェントのプロンプトに追加のコンテキストが付加される +- **instruct** — エージェントのプロンプトに追加コンテキストが付加される -ポリシーはローカルプロセス内で実行されます。リモートサービスには何も送信されません。 +ポリシーはローカルプロセス内で実行されます。リモートサービスへのデータ送信は一切行われません。 --- ## 規約ベースのポリシーでチームポリシーを設定する -チーム全体で品質基準を素早く確立するには、`.failproofai/policies/` 規約を使う方法が最も手軽です。このディレクトリにポリシーファイルを置くだけで自動的に読み込まれます — フラグも設定変更もインストールコマンドも不要です。 +チーム全体に品質基準を確立する最も手軽な方法は、`.failproofai/policies/` の規約です。このディレクトリにポリシーファイルを置くだけで自動的に読み込まれます — フラグも、設定変更も、インストールコマンドも不要です。 @@ -106,13 +107,13 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON ``` - サンプルをコピーするか、独自のものを作成します。 + サンプルをコピーするか、独自のポリシーを作成してください。 ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ ``` - または新しく作成します。 + または新しいファイルを作成します。 ```js // .failproofai/policies/team-policies.mjs @@ -131,32 +132,32 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - failproofai をインストール済みのチームメンバー全員が、これらのポリシーを自動的に取得できます。開発者ごとのセットアップは不要です。 + failproofai をインストールしているすべてのチームメンバーが、これらのポリシーを自動的に取得します。開発者ごとの個別設定は不要です。 -`.failproofai/policies/` をリポジトリにコミットして、チーム全体で同じ基準を共有しましょう。新たな障害モードを発見したらポリシーを追加してプッシュするだけで、全員が次回の `git pull` 時にアップデートを受け取ります。時間をかけてこれらのポリシーを育てることで、継続的に改善される生きた品質基準になります。 +`.failproofai/policies/` をリポジトリにコミットすることで、チーム全員が同じ基準を共有できます。新たな障害モードが見つかったらポリシーを追加してプッシュするだけで、次の `git pull` 時に全員へ反映されます。こうして蓄積されたポリシーは、継続的に改善される生きた品質基準となります。 --- ## データの保存場所 -すべての設定とログはマシン上にのみ保存されます。 +すべての設定とログはお使いのマシン上に保存されます。 -| パス | 保存される内容 | -|------|----------------| +| パス | 保存内容 | +|------|----------| | `~/.failproofai/policies-config.json` | グローバルポリシー設定 | | `~/.failproofai/hook-activity.jsonl` | フック実行履歴 | | `~/.failproofai/hook.log` | カスタムフックエラーのデバッグログ | -| `.failproofai/policies-config.json` | プロジェクト単位の設定（コミット対象） | +| `.failproofai/policies-config.json` | プロジェクト別設定（コミット対象） | | `.failproofai/policies-config.local.json` | 個人用オーバーライド（gitignore 対象） | --- @@ -167,7 +168,7 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON failproofai policies --uninstall ``` -`~/.claude/settings.json` からフックエントリを削除します。`~/.failproofai/` 内の設定ファイルは保持されます。 +`~/.claude/settings.json` からフックエントリを削除します。`~/.failproofai/` 内の設定ファイルはそのまま保持されます。 --- @@ -180,7 +181,7 @@ failproofai policies --uninstall - パラメータ付きの全 26 ポリシー + パラメータを含む全 26 ポリシー diff --git a/docs/ja/introduction.mdx b/docs/ja/introduction.mdx index 1a8c0b41..aa59b0ff 100644 --- a/docs/ja/introduction.mdx +++ b/docs/ja/introduction.mdx @@ -1,36 +1,36 @@ --- title: "Failproof AI" -description: "FailproofAI は、ループ・シークレット漏洩・破壊的なツール呼び出しなどを検出する 39 個の組み込み失敗ポリシーを、1 回のインストールで提供します。" +description: "FailproofAI は AI エージェントに39種類の組み込み障害ポリシーを提供し、ループ・シークレット漏洩・破壊的なツール呼び出しなどをワンインストールで検出します。" --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -**AI 障害ハンドリング**・**エラーリカバリー**・**LLM の信頼性**のためのフックとポリシー。**Claude Code**、**OpenAI Codex**、**GitHub Copilot**、**Cursor Agent**、**OpenCode**、**Pi**、**Gemini CLI**、**Agents SDK** 上で、AI エージェントを安定して自律的に稼働させ続けます。 +**AI 障害ハンドリング**・**エラーリカバリー**・**LLM の信頼性**向上のためのフックとポリシー。**Claude Code**、**OpenAI Codex**、**GitHub Copilot**、**Cursor Agent**、**OpenCode**、**Pi**、**Gemini CLI**、**Hermes**、そして **Agents SDK** 上で、AI エージェントを安定かつ自律的に動作させ続けます。 -AI エージェントは、予測可能なパターンで失敗します。破壊的なコマンドを実行したり、シークレットを漏洩させたり、タスクから脱線したり、ループにはまったり、直接 main にプッシュしたりします。放置すると、小さな障害が連鎖してサービス停止・認証情報の漏洩・作業の消失につながります。 +AI エージェントの障害は、予測可能なパターンで発生します。破壊的なコマンドの実行、シークレットの漏洩、タスクからの逸脱、ループへの陥没、main ブランチへの直接プッシュ——放置すれば、小さな障害がサービス停止、認証情報の流出、作業の消失へと連鎖します。 -FailproofAI はこの問題を **ポリシー** で解決します。これらのルールはすべてのエージェントツール呼び出しにフックし、**障害を検出**・**軽減**（ブロック・指示・サニタイズ）し、対応が必要なときに**アラートを通知**します。ローカルダッシュボードで、すべてのツール呼び出し・エージェント障害・リカバリーアクションを事後に確認できます。 +FailproofAI はこれを**ポリシー**で解決します。これらのルールはエージェントのすべてのツール呼び出しにフックし、**障害を検出**し、**軽減**（ブロック・指示・サニタイズ）し、対応が必要な場合に**アラートを通知**します。ローカルダッシュボードで、あとからすべてのツール呼び出し・エージェント障害・リカバリーアクションを確認できます。 -データは一切、外部に送信されません。 +データはマシンの外に出ません。 ## はじめに - - 破壊的なコマンドのブロック、シークレット漏洩の防止、エージェントをプロジェクト境界内に制限など、すぐに使える機能が揃っています。 + + 破壊的なコマンドのブロック、シークレット漏洩の防止、エージェントをプロジェクト境界内に収める、など。すべてすぐに使えます。 - シンプルな allow / deny / instruct API を使って、JavaScript で独自ルールを作成できます。 + シンプルな allow / deny / instruct API を使い、JavaScript で独自のルールを記述できます。 - 離席中にエージェントが何をしていたかを確認できます。セッションの閲覧、ツール呼び出しの詳細確認、ポリシーが発火した箇所のレビューが可能です。 + 離席中にエージェントが何をしていたかを確認。セッションの閲覧、ツール呼び出しの詳細確認、ポリシーが発動した箇所のレビューが可能です。 - - コードを書かずにポリシーを調整できます。許可リスト・保護ブランチ・しきい値をプロジェクト単位またはグローバルに設定できます。 + + コード不要でポリシーを調整。許可リスト・保護ブランチ・しきい値をプロジェクト単位またはグローバルに設定できます。 @@ -54,4 +54,4 @@ failproofai policies --install # enable policies (or skip — `failproofai` wi failproofai # launch the dashboard ``` -詳細な手順については、[はじめかた](/ja/getting-started)ガイドをご覧ください。 \ No newline at end of file +詳細な手順については [Getting started](/ja/getting-started) ガイドをご覧ください。 \ No newline at end of file diff --git a/docs/ja/package-aliases.mdx b/docs/ja/package-aliases.mdx index 35f248b6..15fef477 100644 --- a/docs/ja/package-aliases.mdx +++ b/docs/ja/package-aliases.mdx @@ -1,12 +1,12 @@ --- title: パッケージエイリアス -description: "タイポスクワット防止用の登録済みエイリアスとその仕組み" +description: "登録済みタイポスクワット防止エイリアスとその仕組み" icon: copy --- ## 公式パッケージ -正式な npm パッケージは **`failproofai`** です： +npmの正式パッケージは **`failproofai`** です： ```bash npm install -g failproofai @@ -16,19 +16,19 @@ bun add -g failproofai --- -## エイリアス名を所有している理由 +## エイリアス名を保有している理由 -タイポスクワッティングとは、悪意のある攻撃者が人気パッケージ名からキー1つ違いのパッケージ名を登録するサプライチェーン攻撃の手口です。インストールコマンドを誤入力した気づかないユーザーは、フルのシステムアクセス権を持つ攻撃者制御のコードを実行してしまいます。これはまさに Failproof AI が防御するために設計された脅威です。 +タイポスクワッティングとは、人気パッケージの名前と1文字違いのパッケージ名を悪意ある攻撃者が登録するという、よく知られたサプライチェーン攻撃です。インストールコマンドを打ち間違えたユーザーが、攻撃者の管理するコードをフルシステムアクセス権限で実行してしまうことになります。これはまさに Failproof AI が防御を目的として設計している脅威の一つです。 -この攻撃面を排除するため、**npm 上の `failproofai` に関するよくある誤字・表記バリアントをすべて先回りで所有しています**。これらの名前はいずれも第三者が登録することはできません。各エイリアスは実際の `failproofai` パッケージにインストール・委譲する薄いプロキシです。 +この攻撃対象を排除するため、**`failproofai` のよくある誤字・表記バリエーションをすべて先制的に npm 上で取得しています**。これらの名前はいずれも第三者に登録されることはありません。各名前は、実際の `failproofai` パッケージにインストールと処理を委譲する薄いプロキシです。 --- ## 登録済みエイリアス -**表記バリアント** — 「failproof ai」のさまざまな書き方： +**表記バリエーション** — 「failproof ai」のさまざまな書き方： -| パッケージ | 状態 | +| パッケージ | ステータス | |---------|--------| | `failproof` | ✅ 公開済み | | `failproof-ai` | ⏳ npm サポート対応待ち | @@ -37,9 +37,9 @@ bun add -g failproofai | `fail_proof_ai` | ⏳ npm サポート対応待ち | | `fail-proofai` | ⏳ npm サポート対応待ち | -**`failprof*` 系タイポ** — "proof" の `o` が1つ抜けたもの： +**`failprof*` タイポ** — 「proof」から `o` が1つ欠けたもの： -| パッケージ | 状態 | +| パッケージ | ステータス | |---------|--------| | `failprof` | ✅ 公開済み | | `failprof-ai` | ✅ 公開済み | @@ -47,21 +47,21 @@ bun add -g failproofai | `fail-prof-ai` | ⏳ npm サポート対応待ち | | `failprof_ai` | ⏳ npm サポート対応待ち | -**`faliproof*` 系タイポ** — `a` と `i` が入れ替わったもの： +**`faliproof*` タイポ** — `a` と `i` が入れ替わったもの： -| パッケージ | 状態 | +| パッケージ | ステータス | |---------|--------| | `faliproof` | ✅ 公開済み | | `faliproof-ai` | ✅ 公開済み | | `faliproofai` | ⏳ npm サポート対応待ち | -> **対応待ちの理由：** npm のスパム防止ポリシーにより、記号を除去して類似度チェックを行った際に既存パッケージと同じ文字列に正規化される名前はブロックされます。アンチスクワッティングを目的としてこれらの名前を予約するよう npm サポートに連絡済みです。承認され次第、有効化される予定です。 +> **対応待ちの理由：** npm のスパム防止ポリシーにより、記号を除去して類似性チェックを行った後に既存パッケージと同じ文字列に正規化される名前の登録がブロックされています。アンチスクワッティング目的でこれらの名前を予約するよう npm サポートに連絡済みです。承認され次第、順次有効化されます。 -公開済みエイリアスが当社所有であることは以下のコマンドで確認できます： +公開済みのエイリアスが当社によって所有されていることは、以下のコマンドで確認できます： ```bash npm info failproof -# maintainers フィールドに "ExosphereHost Inc." が表示されることを確認してください +# maintainers フィールドに "ExosphereHost Inc." が表示されていることを確認してください ``` --- @@ -71,12 +71,12 @@ npm info failproof 各エイリアスパッケージは： 1. `failproofai` を依存関係として列挙しており、インストール時に実際のパッケージ（`postinstall` フックのセットアップを含む）が実行されます -2. 自身の名前（例：`failprof-ai`）と一致するバイナリを公開し、すべての引数を `failproofai` バイナリにプロキシします +2. 自身の名前（例：`failprof-ai`）に対応するバイナリを公開しており、すべての引数を `failproofai` バイナリにプロキシします -プロキシは2行の Node スクリプトで構成されており、ロジックもネットワーク呼び出しも、`failproofai` 自体が行う以上のデータ収集も一切ありません。 +プロキシは2行の Node スクリプトで、ロジックもネットワーク呼び出しも、`failproofai` 自体が行う以上のデータ収集も一切ありません。 --- -## 見落としている名前を見つけた場合 +## 見落とした名前を発見した場合 [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) にイシューを作成してください。登録対応いたします。 \ No newline at end of file diff --git a/docs/ja/testing.mdx b/docs/ja/testing.mdx index d8604d18..4f5fefaa 100644 --- a/docs/ja/testing.mdx +++ b/docs/ja/testing.mdx @@ -4,7 +4,7 @@ description: "ユニットテスト、E2Eテスト、テストヘルパー" icon: flask-vial --- -failproofai には2つのテストスイートがあります：**ユニットテスト**（高速、モック使用）と**エンドツーエンドテスト**（実際のサブプロセス呼び出し）。 +failproofai には2つのテストスイートがあります：**ユニットテスト**（高速・モック使用）と**エンドツーエンドテスト**（実際のサブプロセス呼び出し）。 --- @@ -31,7 +31,7 @@ bun run lint ## ユニットテスト -ユニットテストは `__tests__/` ディレクトリに配置されており、`jsdom` を使った [Vitest](https://vitest.dev) で動作します。 +ユニットテストは `__tests__/` に配置されており、`jsdom` を使った [Vitest](https://vitest.dev) で実行されます。 ```text __tests__/ @@ -40,7 +40,7 @@ __tests__/ hooks-config.test.ts # 設定の読み込みとスコープのマージ policy-evaluator.test.ts # パラメータ注入と評価順序 custom-hooks-registry.test.ts # globalThis レジストリの追加/取得/クリア - custom-hooks-loader.test.ts # ESM ローダー、推移的インポート、エラー処理 + custom-hooks-loader.test.ts # ESM ローダー、推移的インポート、エラーハンドリング manager.test.ts # インストール/削除/一覧操作 components/ sessions-list.test.tsx # セッションリストコンポーネント @@ -110,11 +110,11 @@ describe("block-sudo", () => { ## エンドツーエンドテスト -E2Eテストは実際の `failproofai` バイナリをサブプロセスとして起動し、JSON ペイロードを stdin にパイプして、stdout の出力と終了コードをアサートします。これにより、Claude Code が使用する完全な統合パスをテストできます。 +E2Eテストは実際の `failproofai` バイナリをサブプロセスとして呼び出し、JSON ペイロードを stdin にパイプして、stdout の出力と終了コードを検証します。これにより、Claude Code が使用する完全な統合パスをテストします。 ### セットアップ -E2Eテストはリポジトリのソースから直接バイナリを実行します。初回実行前に、カスタムフックファイルが `'failproofai'` からインポートする際に使用する CJS バンドルをビルドしてください： +E2Eテストはリポジトリのソースから直接バイナリを実行します。初回実行の前に、カスタムフックファイルが `'failproofai'` からインポートする際に使用する CJS バンドルをビルドしてください： ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -126,21 +126,21 @@ bun build src/index.ts --outdir dist --target node --format cjs bun run test:e2e ``` -パブリックフック API（`src/hooks/custom-hooks-registry.ts`、`src/hooks/policy-helpers.ts`、または `src/hooks/policy-types.ts`）を変更した場合は、`dist/` を再ビルドしてください。 +公開フック API（`src/hooks/custom-hooks-registry.ts`、`src/hooks/policy-helpers.ts`、または `src/hooks/policy-types.ts`）を変更した場合は、`dist/` を再ビルドしてください。 ### E2Eテストの構成 ```text __tests__/e2e/ helpers/ - hook-runner.ts # バイナリを起動し、ペイロード JSON をパイプして終了コード・stdout・stderr をキャプチャ - fixture-env.ts # テストごとに分離された設定ファイル付き一時ディレクトリ + hook-runner.ts # バイナリを起動し、ペイロード JSON をパイプして、終了コード・stdout・stderr をキャプチャ + fixture-env.ts # テストごとに分離された一時ディレクトリと設定ファイル payloads.ts # 各イベントタイプに対応した Claude 準拠のペイロードファクトリ hooks/ - builtin-policies.e2e.test.ts # 実際のサブプロセスを使った各ビルトインポリシー + builtin-policies.e2e.test.ts # 実際のサブプロセスで各ビルトインポリシーをテスト custom-hooks.e2e.test.ts # カスタムフックの読み込みと評価 - config-scopes.e2e.test.ts # プロジェクト/ローカル/グローバルをまたいだ設定マージ - policy-params.e2e.test.ts # パラメータ化されたポリシーごとのパラメータ注入 + config-scopes.e2e.test.ts # プロジェクト/ローカル/グローバルをまたいだ設定のマージ + policy-params.e2e.test.ts # パラメータ付きポリシーへのパラメータ注入 ``` ### E2Eヘルパーの使い方 @@ -162,7 +162,7 @@ env.writeConfig({ }); ``` -`createFixtureEnv()` は `afterEach` クリーンアップを自動で登録します。 +`createFixtureEnv()` はクリーンアップ用の `afterEach` を自動的に登録します。 **`runHook`** - バイナリを呼び出す： @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - 既製のペイロードファクトリ： +**`Payloads`** - 即座に使えるペイロードファクトリ： ```typescript Payloads.preToolUse.bash(command, cwd) @@ -226,7 +226,7 @@ describe("block-rm-rf (E2E)", () => { ); expect(result.exitCode).toBe(0); - expect(result.stdout).toBe(""); // allow → 空の stdout + expect(result.stdout).toBe(""); // allow → stdout は空 }); }); ``` @@ -238,23 +238,23 @@ describe("block-rm-rf (E2E)", () => { | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | | Instruct（Stop 以外） | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop instruct | `2` | 空の stdout；理由は stderr に出力 | +| Stop instruct | `2` | stdout は空；理由は stderr に出力 | | Allow | `0` | 空文字列 | ### Vitest の設定 E2Eテストは `vitest.config.e2e.mts` を使用し、以下の設定が適用されます： -- `environment: "node"` - ブラウザグローバルは不要 -- `pool: "forks"` - 真のプロセス分離（テストがサブプロセスを起動する） +- `environment: "node"` - ブラウザのグローバル変数は不要 +- `pool: "forks"` - 真のプロセス分離（テストがサブプロセスを起動） - `testTimeout: 20_000` - テストあたり20秒（バイナリ起動 + フック評価） -`forks` プールは重要です。スレッドベースのワーカーは `globalThis` を共有するため、サブプロセスを起動するテストに干渉する可能性があります。プロセスベースのフォークではこの問題が発生しません。 +`forks` プールは重要な設定です。スレッドベースのワーカーは `globalThis` を共有するため、サブプロセスを起動するテストに干渉する可能性があります。プロセスベースのフォークはこの問題を回避します。 --- ## CI -マージ前に、完全な CI 実行（`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`）がパスする必要があります。E2Eスイートは独立した CI ジョブとして並行実行されます。 +マージ前に、CI のフルラン（`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`）がすべてパスする必要があります。E2Eスイートは別の CI ジョブとして並列で実行されます。 -マージ前の完全なチェックリストについては、[Contributing](../CONTRIBUTING.md) を参照してください。 \ No newline at end of file +マージ前の完全なチェックリストは [Contributing](../CONTRIBUTING.md) を参照してください。 \ No newline at end of file diff --git a/docs/ko/architecture.mdx b/docs/ko/architecture.mdx index 4a0b9402..780844b5 100644 --- a/docs/ko/architecture.mdx +++ b/docs/ko/architecture.mdx @@ -1,10 +1,10 @@ --- title: 아키텍처 -description: "훅 핸들러, 설정 로딩, 정책 평가의 내부 동작 방식" +description: "훅 핸들러, 설정 로딩, 정책 평가가 내부적으로 동작하는 방식" icon: sitemap --- -이 문서는 failproofai의 내부 동작 방식을 설명합니다. 훅 시스템이 에이전트 도구 호출을 가로채는 방법, 설정이 로드되고 병합되는 방법, 정책이 평가되는 방법, 그리고 대시보드가 에이전트 활동을 모니터링하는 방법을 다룹니다. +이 문서는 failproofai의 내부 동작 방식을 설명합니다. 훅 시스템이 에이전트 도구 호출을 가로채는 방법, 설정이 로딩되고 병합되는 방식, 정책이 평가되는 과정, 그리고 대시보드가 에이전트 활동을 모니터링하는 방법을 다룹니다. --- @@ -12,10 +12,10 @@ icon: sitemap failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다: -1. **훅 핸들러** - Claude Code가 에이전트 도구 호출마다 실행하는 빠른 CLI 서브프로세스입니다. 정책을 평가하고 결정을 반환합니다. -2. **에이전트 모니터 (대시보드)** - 에이전트 세션을 모니터링하고 정책을 관리하기 위한 Next.js 웹 애플리케이션입니다. +1. **훅 핸들러** - 에이전트의 모든 도구 호출 시 Claude Code가 실행하는 빠른 CLI 서브프로세스입니다. 정책을 평가하고 결정을 반환합니다. +2. **에이전트 모니터 (대시보드)** - 에이전트 세션 모니터링 및 정책 관리를 위한 Next.js 웹 애플리케이션입니다. -두 서브시스템 모두 `~/.failproofai/`와 프로젝트의 `.failproofai/` 디렉토리에 있는 설정 파일을 공유하지만, 별도의 프로세스로 실행되며 파일 시스템을 통해서만 통신합니다. +두 서브시스템은 `~/.failproofai/`와 프로젝트의 `.failproofai/` 디렉터리에 있는 설정 파일을 공유하지만, 별도의 프로세스로 실행되며 파일 시스템을 통해서만 통신합니다. --- @@ -44,7 +44,7 @@ failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다: } ``` -이후 Claude Code는 각 도구 호출 전에 `failproofai --hook PreToolUse`를 서브프로세스로 실행하고, stdin으로 JSON 페이로드를 전달합니다. +그러면 Claude Code는 각 도구 호출 전에 `failproofai --hook PreToolUse`를 서브프로세스로 실행하고, stdin으로 JSON 페이로드를 전달합니다. ### 페이로드 형식 @@ -60,9 +60,9 @@ failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다: } ``` -`PostToolUse` 이벤트의 경우, 페이로드에 도구의 출력 결과가 담긴 `tool_result`도 포함됩니다. +`PostToolUse` 이벤트의 페이로드에는 도구의 출력이 담긴 `tool_result`도 포함됩니다. -핸들러는 stdin을 1 MB로 제한합니다. 이를 초과하는 페이로드는 무시되며, 모든 정책은 암묵적으로 허용됩니다. +핸들러는 stdin을 1MB로 제한합니다. 이 크기를 초과하는 페이로드는 무시되며, 모든 정책은 암묵적으로 허용됩니다. ### 응답 형식 @@ -85,7 +85,7 @@ failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다: } ``` -**지시 (Stop 이외의 모든 이벤트):** +**지시 (Stop 이벤트 제외):** ```json { "hookSpecificOutput": { @@ -96,27 +96,27 @@ failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다: **Stop 이벤트 지시:** - 종료 코드: `2` -- 이유는 stdout이 아닌 stderr에 기록됩니다 +- 이유는 stdout이 아닌 stderr에 기록됨 **허용:** - 종료 코드: `0` -- stdout은 비어 있습니다 +- stdout 비어 있음 **메시지와 함께 허용:** -`allow(message)`를 사용하면 작업이 허용된 경우에도 정책이 Claude에게 정보성 컨텍스트를 전달할 수 있습니다. 훅 핸들러는 다음 JSON을 **stdout**에 씁니다 (설정 파일이 아닌, 위의 거부 및 지시 응답과 동일하게 Claude Code에 대한 핸들러의 응답입니다): +`allow(message)`는 작업이 허용될 때도 정책이 Claude에게 정보성 컨텍스트를 전달할 수 있게 합니다. 훅 핸들러는 다음 JSON을 **stdout**에 작성합니다(설정 파일이 아니라 위의 거부/지시 응답과 마찬가지로 Claude Code에 대한 핸들러의 응답입니다): ```json -// 훅 핸들러 프로세스가 stdout에 씁니다 +// Written to stdout by the hook handler process { "hookSpecificOutput": { "additionalContext": "All CI checks passed on branch 'feat/my-feature'." } } ``` -- 종료 코드: `0` (작업이 허용됨) -- 여러 정책이 메시지와 함께 `allow`를 반환하는 경우, 해당 메시지들은 줄바꿈으로 연결되어 하나의 `additionalContext` 문자열이 됩니다 -- 어떤 정책도 메시지를 제공하지 않으면 stdout은 비어 있습니다 (기존 동작과 동일) +- 종료 코드: `0` (작업 허용됨) +- 여러 정책이 메시지와 함께 `allow`를 반환하면, 해당 메시지들이 줄바꿈으로 연결되어 하나의 `additionalContext` 문자열로 합쳐짐 +- 어떤 정책도 메시지를 제공하지 않으면 stdout은 비어 있음 (이전과 동일) ### 처리 파이프라인 @@ -126,20 +126,20 @@ failproofai는 두 개의 독립적인 서브시스템으로 구성됩니다: stdin JSON → 페이로드 파싱 (최대 1 MB) → 세션 메타데이터 추출 (session_id, cwd, tool_name, tool_input 등) - → readMergedHooksConfig(cwd) ← 프로젝트 + 로컬 + 글로벌 설정 병합 - → 활성화된 내장 정책을 해석된 파라미터와 함께 등록 + → readMergedHooksConfig(cwd) ← 프로젝트 + 로컬 + 전역 설정 병합 + → 활성화된 빌트인 정책을 확인된 파라미터로 등록 → customPoliciesPath에서 커스텀 정책 로드 (설정된 경우) → 커스텀 정책을 정책 레지스트리에 등록 - → 모든 정책 평가 (내장 정책 우선, 이후 커스텀) - → 첫 번째 deny에서 즉시 중단 - → instruct 결정은 누적 - → allow 메시지는 누적 - → JSON 결정을 stdout에 씁니다 - → ~/.failproofai/hook-activity.jsonl에 이벤트 저장 + → 모든 정책 평가 (빌트인 먼저, 그 다음 커스텀) + → 첫 번째 거부 시 즉시 중단 + → 지시 결정 누적 + → 허용 메시지 누적 + → stdout에 JSON 결정 작성 + → ~/.failproofai/hook-activity.jsonl에 이벤트 기록 → 종료 ``` -전체 프로세스는 LLM 호출 없이 일반적인 페이로드 기준 100ms 이내에 완료됩니다. +전체 프로세스는 LLM 호출 없이 일반적인 페이로드 기준으로 100ms 이내에 완료됩니다. --- @@ -148,45 +148,45 @@ stdin JSON `src/hooks/hooks-config.ts`가 세 가지 범위의 설정 로딩을 구현합니다. ```text -[1] {cwd}/.failproofai/policies-config.json ← 프로젝트 (가장 높은 우선순위) +[1] {cwd}/.failproofai/policies-config.json ← 프로젝트 (최고 우선순위) [2] {cwd}/.failproofai/policies-config.local.json ← 로컬 -[3] ~/.failproofai/policies-config.json ← 글로벌 (가장 낮은 우선순위) +[3] ~/.failproofai/policies-config.json ← 전역 (최저 우선순위) ``` 병합 로직: -- `enabledPolicies` - 세 파일 전체에서 중복을 제거한 합집합 -- `policyParams` - 정책별 키 기준, 먼저 정의한 파일이 전체를 결정 -- `customPoliciesPath` - 먼저 정의한 파일이 결정 -- `llm` - 먼저 정의한 파일이 결정 +- `enabledPolicies` - 세 파일 전체에서 중복 제거 후 합집합 +- `policyParams` - 정책별 키, 먼저 정의한 파일이 전적으로 우선 +- `customPoliciesPath` - 먼저 정의한 파일이 우선 +- `llm` - 먼저 정의한 파일이 우선 -웹 대시보드는 프로젝트 cwd 없이 실행되므로, 읽기와 쓰기 모두 `readHooksConfig()` (글로벌 전용)를 사용합니다. +웹 대시보드는 프로젝트 cwd 없이 실행되므로 읽기/쓰기에 `readHooksConfig()`(전역만)를 사용합니다. --- ## 정책 평가 -`src/hooks/policy-evaluator.ts`가 순서대로 정책을 실행합니다. +`src/hooks/policy-evaluator.ts`가 정책을 순서대로 실행합니다. 각 정책에 대해: -1. 정책의 `params` 스키마를 조회합니다 (있는 경우). +1. 정책의 `params` 스키마를 조회합니다(있는 경우). 2. 병합된 설정에서 `policyParams[policy.name]`을 읽습니다. -3. 사용자 제공 값을 스키마 기본값에 덮어써서 `ctx.params`를 생성합니다. -4. 해석된 컨텍스트와 함께 `policy.fn(ctx)`를 호출합니다. +3. 사용자가 제공한 값을 스키마 기본값에 덮어씌워 `ctx.params`를 생성합니다. +4. 확인된 컨텍스트로 `policy.fn(ctx)`를 호출합니다. 5. 결과가 `deny`이면 즉시 중단하고 해당 결정을 반환합니다. 6. 결과가 `instruct`이면 메시지를 누적하고 계속 진행합니다. -7. 결과가 `allow`이면 다음 정책으로 넘어갑니다. +7. 결과가 `allow`이면 다음 정책으로 계속 진행합니다. 모든 정책 실행 후: -- `deny`가 반환된 경우, 거부 응답을 출력합니다. -- `instruct` 반환이 수집된 경우, 모든 메시지를 합쳐 단일 지시 응답을 출력합니다. -- 그 외에는 허용 응답을 출력합니다 (stdout 비움, 종료 코드 0). +- `deny`가 반환된 경우 거부 응답을 내보냅니다. +- `instruct` 반환이 수집된 경우 모든 메시지를 합쳐 단일 지시 응답을 내보냅니다. +- 그 외의 경우 허용 응답을 내보냅니다(stdout 비어 있음, 종료 코드 0). --- -## 내장 정책 +## 빌트인 정책 -`src/hooks/builtin-policies.ts`는 39개의 내장 정책을 `BuiltinPolicyDefinition` 객체로 정의합니다: +`src/hooks/builtin-policies.ts`는 39개의 빌트인 정책을 `BuiltinPolicyDefinition` 객체로 정의합니다: ```typescript interface BuiltinPolicyDefinition { @@ -204,15 +204,15 @@ interface BuiltinPolicyDefinition { } ``` -`params`를 허용하는 정책은 각 파라미터의 타입과 기본값이 담긴 `PolicyParamsSchema`를 선언합니다. 정책 평가기는 `fn`을 호출하기 전에 해석된 값을 `ctx.params`에 주입합니다. 기본값이 항상 먼저 적용되므로, 정책 함수는 null 검사 없이 `ctx.params`를 읽을 수 있습니다. +`params`를 허용하는 정책은 각 파라미터의 타입과 기본값을 포함하는 `PolicyParamsSchema`를 선언합니다. 정책 평가기는 `fn` 호출 전에 확인된 값을 `ctx.params`에 주입합니다. 기본값이 항상 먼저 적용되므로 정책 함수는 null 검사 없이 `ctx.params`를 읽을 수 있습니다. -정책 내부의 패턴 매칭은 원시 문자열 매칭이 아닌 파싱된 명령어 토큰(argv)을 사용합니다. 이를 통해 셸 연산자 주입을 이용한 우회를 방지합니다 (예: `sudo systemctl status *` 패턴은 명령어에 `; rm -rf /`를 추가해도 우회할 수 없습니다). +정책 내부의 패턴 매칭은 원시 문자열 매칭이 아닌 파싱된 명령 토큰(argv)을 사용합니다. 이를 통해 셸 연산자 주입을 통한 우회를 방지합니다(예: `sudo systemctl status *` 패턴은 명령에 `; rm -rf /`를 덧붙여도 우회할 수 없습니다). --- ## 커스텀 정책 -`src/hooks/custom-hooks-registry.ts`는 `globalThis` 기반의 레지스트리를 구현합니다: +`src/hooks/custom-hooks-registry.ts`는 `globalThis` 기반 레지스트리를 구현합니다: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -222,28 +222,28 @@ export const customPolicies = { }; export function getCustomHooks(): CustomHook[] { ... } -export function clearCustomHooks(): void { ... } // 테스트에서 사용 +export function clearCustomHooks(): void { ... } // used in tests ``` `src/hooks/custom-hooks-loader.ts`는 사용자의 정책 파일을 로드합니다: -1. 설정에서 `customPoliciesPath`를 읽고, 없으면 건너뜁니다. +1. 설정에서 `customPoliciesPath`를 읽습니다. 없으면 건너뜁니다. 2. 절대 경로로 변환하고 파일 존재 여부를 확인합니다. -3. `customPolicies`가 동일한 `globalThis` 레지스트리로 해석될 수 있도록 모든 `from "failproofai"` 임포트를 실제 dist 경로로 재작성합니다. -4. ESM 호환성을 보장하기 위해 전이적인 로컬 임포트도 재귀적으로 재작성합니다. +3. `customPolicies`가 동일한 `globalThis` 레지스트리로 확인될 수 있도록 모든 `from "failproofai"` 임포트를 실제 dist 경로로 재작성합니다. +4. ESM 호환성을 위해 로컬 임포트의 전이적 의존성도 재귀적으로 재작성합니다. 5. 임시 `.mjs` 파일을 작성하고 엔트리 파일을 `import()`합니다. 6. `getCustomHooks()`를 호출하여 등록된 훅을 가져옵니다. 7. `finally` 블록에서 모든 임시 파일을 정리합니다. -오류 발생 시 (파일 없음, 문법 오류, 임포트 실패), 오류는 `~/.failproofai/hook.log`에 기록되고 로더는 빈 배열을 반환합니다. 내장 정책은 영향을 받지 않습니다. +파일 없음, 구문 오류, 임포트 실패 등의 오류가 발생하면 `~/.failproofai/hook.log`에 기록되고 로더는 빈 배열을 반환합니다. 빌트인 정책은 영향을 받지 않습니다. -커스텀 정책은 모든 내장 정책이 실행된 후에 평가됩니다. 커스텀 정책의 `deny`는 이후 커스텀 정책을 즉시 중단하지만, 이 시점에서 내장 정책은 이미 모두 실행된 상태입니다. +커스텀 정책은 모든 빌트인 정책 이후에 평가됩니다. 커스텀 정책의 `deny`는 이후 커스텀 정책의 실행을 중단시키지만, 모든 빌트인은 이미 실행된 상태입니다. --- ## 활동 로깅 -각 훅 이벤트 이후, 핸들러는 `~/.failproofai/hook-activity.jsonl`에 JSONL 한 줄을 추가합니다: +각 훅 이벤트 이후 핸들러는 `~/.failproofai/hook-activity.jsonl`에 JSONL 줄을 추가합니다: ```json { @@ -258,13 +258,13 @@ export function clearCustomHooks(): void { ... } // 테스트에서 사용 } ``` -허용이 아닌 결정을 내린 정책당 한 줄씩 기록됩니다. 허용 결정은 파일 크기를 줄이기 위해 기록하지 않습니다. +허용이 아닌 결정을 내린 정책마다 한 줄씩 기록됩니다. 허용 결정은 파일 크기를 줄이기 위해 기록하지 않습니다. --- ## 대시보드 아키텍처 -대시보드는 App Router를 사용하는 **Next.js 16** 애플리케이션으로, React Server Components와 Server Actions를 활용합니다. +대시보드는 App Router와 React 서버 컴포넌트 및 서버 액션을 사용하는 **Next.js 16** 애플리케이션입니다. ```text app/ @@ -276,7 +276,7 @@ app/ policies/page.tsx ← 클라이언트 컴포넌트: 정책 관리 + 활동 로그 actions/ get-hooks-config.ts ← 설정 + 정책 목록 읽기 - update-hooks-config.ts ← 정책 활성화/비활성화 토글 + update-hooks-config.ts ← 정책 활성화/비활성화 update-policy-params.ts ← 정책 파라미터 업데이트 get-hook-activity.ts ← 활동 로그 페이지네이션/검색 install-hooks-web.ts ← 브라우저에서 훅 설치/제거 @@ -286,16 +286,16 @@ app/ **데이터 흐름:** -- 페이지 컴포넌트는 `lib/projects.ts`와 `lib/log-entries.ts`를 호출하여 파일 시스템에서 직접 프로젝트/세션 데이터를 읽습니다 (읽기에는 API 레이어 없음). -- 정책 페이지는 모든 변경 작업(토글, 파라미터 업데이트, 설치/제거)에 Server Actions를 사용합니다. +- 페이지 컴포넌트는 `lib/projects.ts`와 `lib/log-entries.ts`를 호출하여 파일 시스템에서 직접 프로젝트/세션 데이터를 읽습니다(읽기에 별도 API 레이어 없음). +- Policies 페이지는 모든 변경(토글, 파라미터 업데이트, 설치/제거)에 서버 액션을 사용합니다. - 세션 뷰어는 Claude의 JSONL 트랜스크립트 형식을 파싱하고 메시지 및 도구 호출 타임라인을 렌더링합니다. -**주요 설계 결정:** +**핵심 설계 결정:** -- 데이터베이스 없음 - 모든 영속 상태는 일반 파일(`~/.failproofai/`, `~/.claude/projects/`)에 저장됩니다. -- 변경 작업에 Server Actions 사용 - CRUD 작업에 REST API가 필요 없습니다. -- 읽기 페이지에 React Server Components 사용 - 초기 로딩이 빠르고 데이터 페칭을 위한 클라이언트 번들이 없습니다. -- 상호작용이 필요한 경우에만 클라이언트 컴포넌트 사용 (정책 토글, 활동 검색, 로그 뷰어). +- 데이터베이스 없음 - 모든 영구 상태는 일반 파일(`~/.failproofai/`, `~/.claude/projects/`)에 저장됩니다. +- 변경에 서버 액션 사용 - CRUD 작업에 REST API가 필요하지 않습니다. +- 읽기 페이지에 React 서버 컴포넌트 사용 - 초기 로딩이 빠르고 데이터 페칭을 위한 클라이언트 번들이 필요 없습니다. +- 클라이언트 컴포넌트는 상호작용이 필요한 곳에만 사용(정책 토글, 활동 검색, 로그 뷰어). --- @@ -313,20 +313,20 @@ failproofai/ │ ├── policy-types.ts # TypeScript 인터페이스 │ ├── hooks-config.ts # 다중 범위 설정 로딩 │ ├── custom-hooks-registry.ts # globalThis 기반 훅 레지스트리 -│ ├── custom-hooks-loader.ts # 사용자 JS 훅을 위한 ESM 로더 -│ ├── manager.ts # 설치 / 제거 / 목록 작업 -│ ├── install-prompt.ts # 대화형 정책 선택 프롬프트 -│ ├── hook-logger.ts # hook.log에 로깅 -│ ├── hook-activity-store.ts # hook-activity.jsonl에 활동 저장 +│ ├── custom-hooks-loader.ts # 사용자 JS 훅용 ESM 로더 +│ ├── manager.ts # 설치 / 제거 / 목록 조회 작업 +│ ├── install-prompt.ts # 인터랙티브 정책 선택 프롬프트 +│ ├── hook-logger.ts # hook.log 로깅 +│ ├── hook-activity-store.ts # hook-activity.jsonl에 활동 기록 │ └── llm-client.ts # LLM API 클라이언트 (AI 기반 정책용) ├── app/ # Next.js 대시보드 (페이지 + 서버 액션) ├── lib/ # 공유 유틸리티 │ ├── projects.ts # 파일 시스템에서 Claude 프로젝트 열거 │ ├── log-entries.ts # Claude 트랜스크립트 JSONL 형식 파싱 -│ ├── paths.ts # 시스템 경로 해석 +│ ├── paths.ts # 시스템 경로 확인 │ └── ... ├── components/ # 공유 React UI 컴포넌트 ├── contexts/ # React 컨텍스트 프로바이더 (테마, 자동 새로고침, 텔레메트리) ├── examples/ # 커스텀 훅 파일 예시 -└── __tests__/ # 단위 테스트 및 E2E 테스트 +└── __tests__/ # 단위 및 E2E 테스트 ``` \ No newline at end of file diff --git a/docs/ko/built-in-policies.mdx b/docs/ko/built-in-policies.mdx index eee163c2..3ba3d9c5 100644 --- a/docs/ko/built-in-policies.mdx +++ b/docs/ko/built-in-policies.mdx @@ -1,22 +1,22 @@ --- title: 기본 제공 정책 -description: "에이전트의 일반적인 실패 패턴을 감지하는 39가지 기본 제공 정책" +description: "일반적인 에이전트 오류 패턴을 감지하는 39가지 기본 제공 정책" icon: shield --- -failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39가지 기본 제공 정책이 포함되어 있습니다. 각 정책은 특정 훅 이벤트 유형과 도구 이름에 따라 실행됩니다. 19개의 정책은 코드 작성 없이 동작을 조정할 수 있는 파라미터를 허용합니다. 5개의 워크플로 정책은 Claude가 중단하기 전에 커밋 → 푸시 → PR → CI 파이프라인을 강제합니다. +failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39가지 기본 제공 정책이 포함되어 있습니다. 각 정책은 특정 훅 이벤트 유형과 도구 이름에 대해 실행됩니다. 19개의 정책은 코드 작성 없이 동작을 조정할 수 있는 매개변수를 허용합니다. 5개의 워크플로 정책은 Claude가 중단되기 전에 커밋 → 푸시 → PR → CI 파이프라인을 강제합니다. --- ## 개요 -정책은 다음과 같은 카테고리로 분류됩니다: +정책은 다음 카테고리로 그룹화됩니다: | 카테고리 | 정책 | 훅 유형 | |----------|----------|-----------| | [위험한 명령어](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | | [인프라 명령어](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [시크릿(새니타이저)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [시크릿 (새니타이저)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | | [환경](#environment) | block-env-files, protect-env-vars | PreToolUse | | [파일 접근](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | @@ -25,15 +25,19 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 | [패키지 매니저](#package-managers) | prefer-package-manager | PreToolUse | | [워크플로](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — 에이전트가 진행하지 못하도록 차단합니다. +- **`block-`** — 에이전트가 계속 진행하지 못하도록 차단합니다. - **`warn-`** — 에이전트가 스스로 수정할 수 있도록 추가 컨텍스트를 제공합니다. -- **`sanitize-`** — 에이전트가 확인하기 전에 도구 출력에서 민감한 데이터를 제거합니다. +- **`sanitize-`** — 에이전트가 보기 전에 도구 출력에서 민감한 데이터를 제거합니다. ### 네임스페이스 -모든 정책은 `/` 슬롯에 위치합니다. 기본 제공 정책은 **`failproofai/`** 네임스페이스에 속하며, 예를 들어 `failproofai/sanitize-jwt`와 같습니다. 네임스페이스는 유사한 짧은 이름을 가진 커스텀 또는 서드파티 정책을 함께 로드할 때 충돌을 방지합니다. +모든 정책은 `/` 슬롯에 속합니다. 기본 제공 정책은 +**`failproofai/`** 네임스페이스에 속합니다 — 예를 들어 `failproofai/sanitize-jwt`. 이 +네임스페이스는 비슷한 짧은 이름을 가진 커스텀 또는 서드파티 정책을 함께 로드할 때 +충돌을 방지합니다. -설정에서 기본 제공 정책을 짧은 이름 또는 전체 한정 이름으로 참조할 수 있으며, 두 형식 모두 동일한 정책으로 해석됩니다: +설정 파일에서 기본 제공 정책을 짧은 이름 또는 전체 이름 중 하나로 참조할 수 있으며, +두 형식 모두 동일한 정책으로 해석됩니다: ```json { @@ -44,33 +48,35 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 } ``` -이름에 `/`가 없으면 failproofai는 기본 네임스페이스인 `failproofai`에 속하는 것으로 처리합니다. 이미 `/`가 포함된 이름(예: `myorg/foo`, `custom/my-hook`)은 그대로 유지됩니다. +이름에 `/`가 없으면 failproofai는 기본 네임스페이스인 `failproofai`에 속하는 것으로 +처리합니다. 이미 `/`를 포함한 이름(예: `myorg/foo`, `custom/my-hook`)은 그대로 +유지됩니다. - **`require-`** — 조건이 충족될 때까지 Stop 이벤트를 차단합니다. --- -모든 정책은 `policyParams`에서 선택적 `hint` 필드를 지원합니다. hint는 Claude가 확인하는 deny 또는 instruct 메시지에 추가되어, 정책 코드를 수정하지 않고도 실행 가능한 안내를 제공합니다. 기본 제공, 커스텀, 관례 정책 모두에서 사용할 수 있습니다. 자세한 내용은 [설정 → hint](/ko/configuration#hint-cross-cutting)를 참조하세요. +모든 정책은 `policyParams`에서 선택적 `hint` 필드를 지원합니다. hint는 Claude가 보는 deny 또는 instruct 메시지에 추가되어, 정책 코드를 수정하지 않고도 실행 가능한 안내를 제공합니다. 기본 제공, 커스텀, 컨벤션 정책 모두에서 동작합니다. 자세한 내용은 [구성 → hint](/ko/configuration#hint-cross-cutting)를 참조하세요. --- ## 위험한 명령어 -에이전트가 되돌리기 어렵거나 호스트 시스템을 손상시킬 수 있는 작업을 실행하지 못하도록 방지합니다. +에이전트가 되돌리기 어렵거나 호스트 시스템에 손상을 줄 수 있는 작업을 실행하지 못하도록 방지합니다. ### `block-sudo` **이벤트:** PreToolUse (Bash) -**기본값:** `sudo` 명령어가 포함된 모든 명령을 차단합니다. +**기본값:** `sudo` 명령어를 포함하는 모든 명령을 거부합니다. -`sudo` 키워드가 포함된 호출을 차단합니다. 패턴 매칭은 원시 문자열이 아닌 파싱된 명령 토큰에 대해 수행되어 셸 연산자 주입을 통한 우회를 방지합니다. +`sudo` 키워드를 포함하는 호출을 차단합니다. 패턴 매칭은 원시 문자열이 아닌 파싱된 명령 토큰에 대해 수행되어 셸 연산자 주입을 통한 우회를 방지합니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 허용된 정확한 명령 접두사. 각 항목은 파싱된 argv 토큰과 매칭됩니다. | +| `allowPatterns` | `string[]` | `[]` | 허용되는 정확한 명령 접두사. 각 항목은 파싱된 argv 토큰에 대해 매칭됩니다. | **예시:** @@ -84,10 +90,10 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 } ``` -이 설정으로 `sudo systemctl status nginx`는 허용되지만 `sudo rm /etc/hosts`는 차단됩니다. +이 설정에서 `sudo systemctl status nginx`는 허용되지만 `sudo rm /etc/hosts`는 거부됩니다. -패턴은 원시 명령 문자열이 아닌 파싱된 토큰과 매칭됩니다. 이를 통해 추가된 셸 연산자를 통한 우회를 방지합니다(예: `sudo systemctl status x; rm -rf /`는 `sudo systemctl status *`와 매칭되지 않습니다). +패턴은 원시 명령 문자열이 아닌 파싱된 토큰에 대해 매칭됩니다. 이는 추가된 셸 연산자를 통한 우회를 방지합니다 (예: `sudo systemctl status x; rm -rf /`는 `sudo systemctl status *`와 매칭되지 않습니다). --- @@ -95,13 +101,13 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `block-rm-rf` **이벤트:** PreToolUse (Bash) -**기본값:** `rm -rf`, `rm -fr` 및 유사한 재귀 삭제 형식을 차단합니다. +**기본값:** `rm -rf`, `rm -fr` 및 유사한 재귀 삭제 형식을 거부합니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | 재귀 삭제가 허용된 경로(예: `/tmp`). | +| `allowPaths` | `string[]` | `[]` | 재귀적으로 삭제해도 안전한 경로 (예: `/tmp`). | **예시:** @@ -120,37 +126,37 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `block-curl-pipe-sh` **이벤트:** PreToolUse (Bash) -**기본값:** `curl | bash`, `curl | sh`, `wget | bash` 및 유사한 패턴을 차단합니다. +**기본값:** `curl | bash`, `curl | sh`, `wget | bash` 및 유사한 패턴을 거부합니다. -파라미터 없음. +매개변수 없음. --- ### `block-failproofai-commands` **이벤트:** PreToolUse (Bash) -**기본값:** failproofai 자체를 제거하거나 비활성화하는 명령(예: `npm uninstall failproofai`, `failproofai policies --uninstall`)을 차단합니다. +**기본값:** failproofai 자체를 제거하거나 비활성화하는 명령을 거부합니다 (예: `npm uninstall failproofai`, `failproofai policies --uninstall`). -파라미터 없음. +매개변수 없음. --- ## 인프라 명령어 -코딩 에이전트가 인프라 CLI를 실행하거나 CI/CD 파이프라인을 트리거하지 못하도록 차단합니다. 이 카테고리의 모든 정책은 **옵트인**(`defaultEnabled: false`)입니다. `kubectl`, `terraform` 등을 합법적으로 호출해야 하는 에이전트는 정책을 활성화하지 않는 한 영향을 받지 않습니다. 활성화된 경우, 명령이 `allowPatterns`의 항목과 일치하지 않는 한 해당 CLI의 모든 호출이 차단됩니다. +코딩 에이전트가 인프라 CLI를 실행하거나 CI/CD 파이프라인을 트리거하지 못하도록 차단합니다. 이 카테고리의 모든 정책은 **옵트인** (`defaultEnabled: false`)입니다 — `kubectl`, `terraform` 등을 정상적으로 호출해야 하는 에이전트는 정책을 활성화하지 않는 한 영향을 받지 않습니다. 활성화되면 명령이 `allowPatterns`의 항목과 일치하지 않는 한 매칭된 CLI의 모든 호출이 거부됩니다. -패턴 문법은 [`block-sudo`](#block-sudo)와 동일합니다. 토큰은 파싱된 argv와 매칭되고, `*`는 하나의 토큰에 대한 와일드카드이며, 독립적인 셸 연산자(`&&`, `||`, `|`, `;`) 또는 셸 메타문자가 내장된 토큰을 포함하는 명령은 주입 우회를 방지하기 위해 허용 목록 매칭 전에 거부됩니다. +패턴 문법은 [`block-sudo`](#block-sudo)와 동일합니다: 토큰은 파싱된 argv에 대해 매칭되고, `*`는 한 토큰에 대한 와일드카드이며, 독립적인 셸 연산자(`&&`, `||`, `|`, `;`)를 포함하거나 임베디드 셸 메타문자가 있는 토큰을 포함하는 명령은 주입 우회를 방지하기 위해 허용 목록 매칭 전에 거부됩니다. ### `block-kubectl` **이벤트:** PreToolUse (Bash) -**기본값:** 모든 `kubectl` 호출을 차단합니다. +**기본값:** 모든 `kubectl` 호출을 거부합니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 허용된 kubectl 명령 접두사. | +| `allowPatterns` | `string[]` | `[]` | 허용되는 kubectl 명령 접두사. | **예시:** @@ -164,20 +170,20 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 } ``` -이 설정으로 `kubectl get pods`는 허용되지만 `kubectl apply -f deploy.yaml`은 차단됩니다. +이 설정에서 `kubectl get pods`는 허용되지만 `kubectl apply -f deploy.yaml`은 거부됩니다. --- ### `block-terraform` **이벤트:** PreToolUse (Bash) -**기본값:** 모든 `terraform` 또는 `tofu`(OpenTofu) 호출을 차단합니다. +**기본값:** 모든 `terraform` 또는 `tofu` (OpenTofu) 호출을 거부합니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 허용된 terraform/tofu 명령 접두사. | +| `allowPatterns` | `string[]` | `[]` | 허용되는 terraform/tofu 명령 접두사. | **예시:** @@ -196,13 +202,13 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `block-aws-cli` **이벤트:** PreToolUse (Bash) -**기본값:** 모든 `aws` CLI 호출을 차단합니다. +**기본값:** 모든 `aws` CLI 호출을 거부합니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 허용된 aws CLI 명령 접두사. | +| `allowPatterns` | `string[]` | `[]` | 허용되는 aws CLI 명령 접두사. | **예시:** @@ -221,13 +227,13 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `block-gcloud` **이벤트:** PreToolUse (Bash) -**기본값:** 모든 `gcloud`(Google Cloud) CLI 호출을 차단합니다. +**기본값:** 모든 `gcloud` (Google Cloud) CLI 호출을 거부합니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 허용된 gcloud 명령 접두사. | +| `allowPatterns` | `string[]` | `[]` | 허용되는 gcloud 명령 접두사. | **예시:** @@ -246,13 +252,13 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `block-az-cli` **이벤트:** PreToolUse (Bash) -**기본값:** 모든 `az`(Azure) CLI 호출을 차단합니다. +**기본값:** 모든 `az` (Azure) CLI 호출을 거부합니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 허용된 az CLI 명령 접두사. | +| `allowPatterns` | `string[]` | `[]` | 허용되는 az CLI 명령 접두사. | **예시:** @@ -271,13 +277,13 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `block-helm` **이벤트:** PreToolUse (Bash) -**기본값:** 모든 `helm` 호출을 차단합니다. +**기본값:** 모든 `helm` 호출을 거부합니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 허용된 helm 명령 접두사. | +| `allowPatterns` | `string[]` | `[]` | 허용되는 helm 명령 접두사. | **예시:** @@ -296,7 +302,7 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `block-gh-pipeline` **이벤트:** PreToolUse (Bash) -**기본값:** 상태를 변경하거나 파이프라인을 트리거하는 다음 `gh` CLI 서브커맨드를 차단합니다: +**기본값:** 상태를 변경하거나 파이프라인을 트리거하는 다음 `gh` CLI 서브커맨드를 거부합니다: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -305,13 +311,13 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 - `gh cache delete` - `gh secret set`, `gh secret delete` -`gh pr view`, `gh pr list`, `gh run list`, `gh release view`, `gh api repos/.../...`와 같은 읽기 전용 `gh` 서브커맨드는 이 정책에 **해당하지 않습니다**. 이러한 명령은 워크플로 확인(failproofai의 `require-ci-green-before-stop` 포함)에 일상적으로 필요합니다. +`gh pr view`, `gh pr list`, `gh run list`, `gh release view`, `gh api repos/.../...`와 같은 읽기 전용 `gh` 서브커맨드는 이 정책에서 매칭되지 **않습니다** — 이러한 명령은 워크플로 확인(failproofai의 `require-ci-green-before-stop` 포함)에 일상적으로 필요합니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 그렇지 않으면 차단될 특정 스크립트 호출을 허용합니다. | +| `allowPatterns` | `string[]` | `[]` | 그렇지 않으면 거부될 특정 스크립트 호출을 허용합니다. | **예시:** @@ -327,27 +333,27 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 --- -## 시크릿(새니타이저) +## 시크릿 (새니타이저) -에이전트가 컨텍스트나 출력에 자격 증명을 유출하지 못하도록 방지합니다. 새니타이저 정책은 **PostToolUse** 이벤트에서 실행됩니다. Claude가 Bash 명령을 실행하거나, 파일을 읽거나, 도구를 호출할 때 이러한 정책은 Claude에게 반환되기 전에 출력을 검사합니다. 시크릿 패턴이 감지되면 출력이 다시 전달되는 것을 방지하는 deny 결정을 반환합니다. +에이전트가 컨텍스트나 출력에 자격 증명을 노출하지 못하도록 방지합니다. 새니타이저 정책은 **PostToolUse** 이벤트에서 실행됩니다. Claude가 Bash 명령을 실행하거나, 파일을 읽거나, 도구를 호출할 때 이 정책들은 Claude에게 반환되기 전에 출력을 검사합니다. 시크릿 패턴이 감지되면 정책은 출력이 다시 전달되지 못하도록 거부 결정을 반환합니다. ### `sanitize-jwt` **이벤트:** PostToolUse (모든 도구) -**기본값:** JWT 토큰(`.`으로 구분된 세 개의 base64url 세그먼트)을 삭제합니다. +**기본값:** JWT 토큰(`.`으로 구분된 세 개의 base64url 세그먼트)을 난독화합니다. -파라미터 없음. +매개변수 없음. --- ### `sanitize-api-keys` **이벤트:** PostToolUse (모든 도구) -**기본값:** 일반적인 API 키 형식을 삭제합니다: Anthropic(`sk-ant-`), OpenAI(`sk-`), GitHub PAT(`ghp_`), AWS 액세스 키(`AKIA`), Stripe 키(`sk_live_`, `sk_test_`), Google API 키(`AIza`). +**기본값:** 일반적인 API 키 형식을 난독화합니다: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS 액세스 키 (`AKIA`), Stripe 키 (`sk_live_`, `sk_test_`), Google API 키 (`AIza`). -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| | `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | 시크릿으로 처리할 추가 정규식 패턴. | @@ -371,66 +377,66 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `sanitize-connection-strings` **이벤트:** PostToolUse (모든 도구) -**기본값:** 자격 증명이 내장된 데이터베이스 연결 문자열을 삭제합니다(예: `postgresql://user:password@host/db`). +**기본값:** 자격 증명이 포함된 데이터베이스 연결 문자열을 난독화합니다 (예: `postgresql://user:password@host/db`). -파라미터 없음. +매개변수 없음. --- ### `sanitize-private-key-content` **이벤트:** PostToolUse (모든 도구) -**기본값:** PEM 블록(`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` 등)을 삭제합니다. +**기본값:** PEM 블록(`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` 등)을 난독화합니다. -파라미터 없음. +매개변수 없음. --- ### `sanitize-bearer-tokens` **이벤트:** PostToolUse (모든 도구) -**기본값:** 토큰이 20자 이상인 `Authorization: Bearer ` 헤더를 삭제합니다. +**기본값:** 토큰이 20자 이상인 `Authorization: Bearer ` 헤더를 난독화합니다. -파라미터 없음. +매개변수 없음. --- ## 환경 -에이전트가 민감한 환경 구성을 읽거나 노출하지 못하도록 보호합니다. +에이전트가 민감한 환경 설정을 읽거나 노출하지 못하도록 보호합니다. ### `block-env-files` **이벤트:** PreToolUse (Bash, Read) -**기본값:** `cat .env`, `.env`를 파일 경로로 하는 `Read` 도구 호출 등을 통해 `.env` 파일을 읽는 것을 차단합니다. +**기본값:** `cat .env`, `.env`를 파일 경로로 하는 `Read` 도구 호출 등을 통한 `.env` 파일 읽기를 거부합니다. -`.envrc` 또는 다른 환경 관련 파일은 차단하지 않으며, 정확히 `.env`로 명명된 파일만 차단합니다. +`.envrc` 또는 기타 환경 관련 파일은 차단하지 않으며, 정확히 `.env`로 명명된 파일만 차단합니다. -파라미터 없음. +매개변수 없음. --- ### `protect-env-vars` **이벤트:** PreToolUse (Bash) -**기본값:** 환경 변수를 출력하는 명령(`printenv`, `env`, `echo $VAR`)을 차단합니다. +**기본값:** 환경 변수를 출력하는 명령을 거부합니다: `printenv`, `env`, `echo $VAR`. -파라미터 없음. +매개변수 없음. --- ## 파일 접근 -에이전트가 프로젝트 경계 내에서 작업하고 민감한 파일에 접근하지 못하도록 유지합니다. +에이전트가 프로젝트 경계 안에서만 작업하고 민감한 파일에 접근하지 못하도록 유지합니다. ### `block-read-outside-cwd` **이벤트:** PreToolUse (Read, Bash) -**기본값:** 프로젝트 루트 외부의 파일 읽기를 차단합니다. 경계는 `CLAUDE_PROJECT_DIR`(Claude Code가 세션당 한 번 설정)이며, 해당 변수가 설정되지 않은 경우 세션의 현재 작업 디렉토리로 폴백합니다. 라이브 `cwd` 대신 프로젝트 루트를 사용하면 Claude가 하위 디렉토리로 `cd`한 후에도 경계가 안정적으로 유지됩니다. +**기본값:** 프로젝트 루트 외부의 파일 읽기를 거부합니다. 경계는 `CLAUDE_PROJECT_DIR`(Claude Code가 세션당 한 번 설정)이며, 해당 변수가 설정되지 않은 경우 세션의 현재 작업 디렉토리로 폴백합니다. 라이브 `cwd` 대신 프로젝트 루트를 사용하면 Claude가 하위 디렉토리로 `cd`한 후에도 경계가 안정적으로 유지됩니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| | `allowPaths` | `string[]` | `[]` | 프로젝트 루트 외부에 있더라도 허용되는 절대 경로 접두사. | @@ -451,13 +457,13 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `block-secrets-write` **이벤트:** PreToolUse (Write, Edit) -**기본값:** 개인 키와 인증서에 일반적으로 사용되는 파일(`id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`)에 쓰기를 차단합니다. +**기본값:** 개인 키와 인증서에 일반적으로 사용되는 파일에 대한 쓰기를 거부합니다: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | 차단할 추가 파일 이름 패턴(글로브 스타일). | +| `additionalPatterns` | `string[]` | `[]` | 차단할 추가 파일명 패턴 (글로브 스타일). | **예시:** @@ -475,16 +481,16 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ## Git -실수로 인한 푸시, 강제 푸시, 되돌리기 어려운 브랜치 실수를 방지합니다. +되돌리기 어려운 실수로 인한 푸시, 강제 푸시, 브랜치 실수를 방지합니다. ### `block-push-master` **이벤트:** PreToolUse (Bash) -**기본값:** `git push origin main` 및 `git push origin master`를 차단합니다. +**기본값:** `git push origin main` 및 `git push origin master`를 거부합니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| | `protectedBranches` | `string[]` | `["main", "master"]` | 직접 푸시할 수 없는 브랜치 이름. | @@ -501,7 +507,7 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ``` -모든 브랜치로의 푸시를 허용하려면(사실상 `enabledPolicies`에서 제거하지 않고 이 정책을 비활성화), `protectedBranches: []`로 설정하세요. +모든 브랜치에 대한 푸시를 허용하려면(`enabledPolicies`에서 정책을 제거하지 않고 효과적으로 비활성화), `protectedBranches: []`로 설정하세요. --- @@ -509,22 +515,22 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `block-work-on-main` **이벤트:** PreToolUse (Bash) -**기본값:** 작업 트리가 `main` 또는 `master`에 있는 동안 `git commit`, `git merge`, `git rebase`, `git cherry-pick`을 차단합니다. 브랜치 생성 및 전환(`git checkout`, `git checkout -b`, `git switch`, `git switch -c`)은 영향을 받지 않습니다. +**기본값:** 작업 트리가 `main` 또는 `master`에 있는 동안 `git commit`, `git merge`, `git rebase`, `git cherry-pick`을 거부합니다. 브랜치 생성 및 전환(`git checkout`, `git checkout -b`, `git switch`, `git switch -c`)은 영향받지 않습니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | commit/merge/rebase/cherry-pick이 차단되는 브랜치 이름. | +| `protectedBranches` | `string[]` | `["main", "master"]` | commit/merge/rebase/cherry-pick이 거부되는 브랜치 이름. | --- ### `block-force-push` **이벤트:** PreToolUse (Bash) -**기본값:** `git push --force` 및 `git push -f`를 차단합니다. +**기본값:** `git push --force` 및 `git push -f`를 거부합니다. -정책별 파라미터 없음. 대안을 제안하려면 공통 [`hint`](/ko/configuration#hint-cross-cutting)를 사용하세요: +정책별 매개변수 없음. 크로스커팅 [`hint`](/ko/configuration#hint-cross-cutting)를 사용하여 대안을 제안할 수 있습니다: ```json { @@ -541,27 +547,27 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `warn-git-amend` **이벤트:** PreToolUse (Bash) -**기본값:** `git commit --amend` 실행 시 Claude에게 주의를 기울이도록 지시합니다. 명령을 차단하지 않습니다. +**기본값:** `git commit --amend` 실행 시 Claude에게 신중하게 진행하도록 안내합니다. 명령을 차단하지 않습니다. -파라미터 없음. +매개변수 없음. --- ### `warn-git-stash-drop` **이벤트:** PreToolUse (Bash) -**기본값:** `git stash drop` 실행 전 Claude에게 확인하도록 지시합니다. 명령을 차단하지 않습니다. +**기본값:** `git stash drop` 실행 전 Claude에게 확인하도록 안내합니다. 명령을 차단하지 않습니다. -파라미터 없음. +매개변수 없음. --- ### `warn-all-files-staged` **이벤트:** PreToolUse (Bash) -**기본값:** `git add -A` 또는 `git add .` 실행 시 Claude에게 스테이징 대상을 검토하도록 지시합니다. 명령을 차단하지 않습니다. +**기본값:** `git add -A` 또는 `git add .` 실행 시 Claude에게 스테이징 중인 내용을 검토하도록 안내합니다. 명령을 차단하지 않습니다. -파라미터 없음. +매개변수 없음. --- @@ -572,35 +578,35 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `warn-destructive-sql` **이벤트:** PreToolUse (Bash) -**기본값:** `DROP TABLE`, `DROP DATABASE`, 또는 `WHERE` 절 없는 `DELETE`가 포함된 SQL 실행 전 Claude에게 확인하도록 지시합니다. +**기본값:** `DROP TABLE`, `DROP DATABASE` 또는 `WHERE` 절 없는 `DELETE`가 포함된 SQL 실행 전 Claude에게 확인하도록 안내합니다. -파라미터 없음. +매개변수 없음. --- ### `warn-schema-alteration` **이벤트:** PreToolUse (Bash) -**기본값:** `ALTER TABLE` 구문 실행 전 Claude에게 확인하도록 지시합니다. +**기본값:** `ALTER TABLE` 구문 실행 전 Claude에게 확인하도록 안내합니다. -파라미터 없음. +매개변수 없음. --- ## 경고 -잠재적으로 위험하지만 파괴적이지 않은 작업 전에 에이전트에게 추가 컨텍스트를 제공합니다. +파괴적이지는 않지만 잠재적으로 위험한 작업 전에 에이전트에게 추가 컨텍스트를 제공합니다. ### `warn-large-file-write` **이벤트:** PreToolUse (Write) -**기본값:** 1024 KB보다 큰 파일을 쓰기 전에 Claude에게 확인하도록 지시합니다. +**기본값:** 1024 KB를 초과하는 파일 작성 전 Claude에게 확인하도록 안내합니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | 경고가 발생하는 파일 크기 임계값(킬로바이트). | +| `thresholdKb` | `number` | `1024` | 경고가 발생하는 파일 크기 임계값 (킬로바이트). | **예시:** @@ -615,7 +621,7 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ``` -훅 핸들러는 페이로드에 대해 1 MB stdin 제한을 적용합니다. 작은 콘텐츠로 이 정책을 테스트하려면 `thresholdKb`를 1024보다 훨씬 작은 값으로 설정하세요. +훅 핸들러는 페이로드에 대해 1 MB stdin 제한을 적용합니다. 작은 콘텐츠로 이 정책을 테스트하려면 `thresholdKb`를 1024보다 훨씬 낮은 값으로 설정하세요. --- @@ -623,27 +629,27 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `warn-package-publish` **이벤트:** PreToolUse (Bash) -**기본값:** `npm publish` 실행 전 Claude에게 확인하도록 지시합니다. +**기본값:** `npm publish` 실행 전 Claude에게 확인하도록 안내합니다. -파라미터 없음. +매개변수 없음. --- ### `warn-background-process` **이벤트:** PreToolUse (Bash) -**기본값:** `nohup`, `&`, `disown`, `screen`을 통해 백그라운드 프로세스를 시작할 때 Claude에게 주의를 기울이도록 지시합니다. +**기본값:** `nohup`, `&`, `disown`, `screen`을 통한 백그라운드 프로세스 실행 시 Claude에게 주의하도록 안내합니다. -파라미터 없음. +매개변수 없음. --- ### `warn-global-package-install` **이벤트:** PreToolUse (Bash) -**기본값:** 가상 환경 없이 `npm install -g`, `yarn global add`, `pip install` 실행 전 Claude에게 확인하도록 지시합니다. +**기본값:** `npm install -g`, `yarn global add`, 또는 가상 환경 없이 `pip install` 실행 전 Claude에게 확인하도록 안내합니다. -파라미터 없음. +매개변수 없음. --- @@ -654,18 +660,18 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `prefer-package-manager` **이벤트:** PreToolUse (Bash) -**기본값:** 비활성화. 활성화되면 `allowed` 목록에 없는 패키지 매니저 명령을 차단하고 Claude에게 허용된 매니저를 사용하도록 명령을 재작성하도록 지시합니다. +**기본값:** 비활성화됨. 활성화되면 `allowed` 목록에 없는 패키지 매니저 명령을 차단하고 허용된 매니저를 사용하여 명령을 재작성하도록 Claude에게 안내합니다. 감지 대상: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | 허용된 패키지 매니저 이름. 목록에 없는 감지된 매니저는 차단됩니다. 비어있으면 정책은 아무 작업도 하지 않습니다. | -| `blocked` | string[] | `[]` | 기본 제공 목록 외에 추가로 차단할 매니저 이름(예: `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | 허용되는 패키지 매니저 이름. 이 목록에 없는 감지된 매니저는 차단됩니다. 비어 있으면 정책은 아무 작업도 수행하지 않습니다. | +| `blocked` | string[] | `[]` | 기본 제공 목록 이외에 추가로 차단할 매니저 이름 (예: `['pdm', 'pipx']`). | -기본 제공 차단 목록: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. `blocked`를 사용하여 이 목록에 없는 매니저를 추가합니다. +기본 제공 차단 목록: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. 이 목록에 없는 매니저를 추가하려면 `blocked`를 사용하세요. -**예시 설정:** +**설정 예시:** ```json { @@ -679,7 +685,7 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 } ``` -이 설정으로 `pip install flask`와 `pdm install flask`는 모두 차단되며 Claude에게 `uv` 또는 `bun`을 사용하라는 메시지가 표시됩니다. `uv pip install flask`와 같은 명령은 `uv`가 허용 목록에 있고 먼저 확인되므로 허용됩니다. +이 설정에서 `pip install flask`와 `pdm install flask`는 모두 거부되며, Claude에게 대신 `uv` 또는 `bun`을 사용하도록 메시지가 표시됩니다. `uv pip install flask`와 같은 명령은 `uv`가 허용 목록에 있고 먼저 확인되므로 허용됩니다. --- @@ -690,63 +696,63 @@ failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39 ### `warn-repeated-tool-calls` **이벤트:** PreToolUse (모든 도구) -**기본값:** 동일한 도구가 동일한 파라미터로 3회 이상 호출될 때 Claude에게 재고하도록 지시합니다. 이는 에이전트가 루프에 빠진 일반적인 징후입니다. +**기본값:** 동일한 도구가 동일한 매개변수로 3회 이상 호출될 때 Claude에게 재고하도록 안내합니다 — 에이전트가 루프에 갇혀 있다는 일반적인 신호입니다. -파라미터 없음. +매개변수 없음. --- ## 워크플로 -체계적인 세션 종료 워크플로를 강제합니다. 이러한 정책은 **Stop** 이벤트에서 실행되며 각 조건이 충족될 때까지 에이전트의 중단을 차단합니다. 자연스러운 의존성 체인을 따릅니다: 커밋 → 푸시 → PR → CI. 정책이 차단하면 체인의 후속 정책은 건너뜁니다(deny 단락 평가). +세션 종료 시 체계적인 워크플로를 강제합니다. 이 정책들은 **Stop** 이벤트에서 실행되며 각 조건이 충족될 때까지 에이전트가 중단하지 못하도록 거부합니다. 자연스러운 의존성 체인을 따릅니다: 커밋 → 푸시 → PR → CI. 정책이 거부하면 체인의 이후 정책은 건너뜁니다 (거부 시 단락). -모든 워크플로 정책은 **fail-open**입니다: 필요한 도구를 사용할 수 없는 경우(예: `gh`가 설치되지 않음, git 원격 없음), 정책은 확인이 건너뛰어진 이유를 설명하는 안내 메시지와 함께 허용합니다. +모든 워크플로 정책은 **fail-open** 방식입니다: 필요한 도구를 사용할 수 없는 경우(예: `gh` 미설치, git 리모트 없음) 정책은 확인이 건너뛰어진 이유를 알리는 정보 메시지와 함께 허용합니다. -### CLI별 Stop 동작 방식 +### CLI별 Stop 시맨틱 -Stop 적용은 일곱 가지 지원 CLI에서 각각 다른 "에이전트 완료" 훅 계약을 노출하기 때문에 약간 다르게 보입니다. **결과**는 동일합니다 — 에이전트는 워크플로 게이트가 실패하는 동안 중단될 수 없습니다 — 하지만 **메커니즘**은 다릅니다. 아래 표는 요약을 제공합니다. Pi만 `require-*-before-stop` 정책을 활성화하기 전에 이해할 가치가 있는 사용자에게 보이는 동작 방식의 특이점이 있습니다. +Stop 적용은 지원되는 7개 CLI에서 각각 다른 "에이전트 완료" 훅 계약을 노출하기 때문에 약간씩 다르게 동작합니다. **결과**는 동일합니다 — 에이전트는 워크플로 게이트가 실패하는 동안 중단할 수 없습니다 — 하지만 **메커니즘**은 다릅니다. 아래 표에 요약되어 있습니다; `require-*-before-stop` 정책을 활성화하기 전에 이해할 가치가 있는 사용자에게 보이는 특이점은 Pi에만 있습니다. | CLI | 게이트 실행 시점 | 표시되는 내용 | |---|---|---| -| Claude Code | 동일한 에이전트 루프, 즉시 | Claude가 계속 작동합니다 — 문제를 수정한 다음 다시 완료를 시도합니다. 사용자에게 중단이 보이지 않습니다. | -| Codex | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다. | -| GitHub Copilot CLI | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다(Copilot의 `{decision:"block", reason}` 재시도 채널 사용 — Copilot CLI 1.0.41에 대해 경험적으로 검증됨). | -| Cursor Agent | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다(Cursor의 `{followup_message}` 채널 사용 — `loop_limit`에 의해 제한, 기본 5회 재시도). | -| Gemini CLI | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다(`AfterAgent`의 Gemini `{decision:"block", reason}` 채널 사용). | -| OpenCode | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다(`hookSpecificOutput.additionalContext`를 통해 라우팅된 OpenCode의 `client.session.prompt(...)` SDK 호출 사용). | -| **Pi (pi-coding-agent)** | **다음 사용자 턴** | **Pi는 게이트가 실행될 때 눈에 띄게 중단됩니다** — 에이전트 루프가 종료되고 프롬프트로 반환됩니다. 그런 다음 다음에 프롬프트를 제출할 때 게이트가 실행됩니다: failproofai는 해당 턴의 시스템 프롬프트에 `MANDATORY ACTION REQUIRED` 지시문을 앞에 추가하여 LLM에게 요청한 작업을 수행하기 전에 워크플로 단계(커밋, 푸시 등)를 완료하도록 지시합니다. | +| Claude Code | 동일한 에이전트 루프, 즉시 | Claude가 계속 작업합니다 — 문제를 수정한 후 다시 완료를 시도합니다. 사용자에게 보이는 중단 없음. | +| Codex | 동일한 에이전트 루프, 즉시 | Claude와 동일. | +| GitHub Copilot CLI | 동일한 에이전트 루프, 즉시 | Claude와 동일 (Copilot의 `{decision:"block", reason}` 재시도 채널 사용 — Copilot CLI 1.0.41에 대해 경험적으로 검증됨). | +| Cursor Agent | 동일한 에이전트 루프, 즉시 | Claude와 동일 (Cursor의 `{followup_message}` 채널 사용 — `loop_limit`으로 제한, 기본값 5회 재시도). | +| Gemini CLI | 동일한 에이전트 루프, 즉시 | Claude와 동일 (Gemini의 `{decision:"block", reason}` 채널을 `AfterAgent`에서 사용). | +| OpenCode | 동일한 에이전트 루프, 즉시 | Claude와 동일 (OpenCode의 `client.session.prompt(...)` SDK 호출을 `hookSpecificOutput.additionalContext`를 통해 라우팅). | +| **Pi (pi-coding-agent)** | **다음 사용자 턴** | **Pi는 게이트가 실행될 때 눈에 띄게 중단됩니다** — 에이전트 루프가 종료되고 프롬프트로 돌아옵니다. 그런 다음 다음에 프롬프트를 제출할 때 게이트가 실행됩니다: failproofai는 해당 턴의 시스템 프롬프트에 `MANDATORY ACTION REQUIRED` 지시문을 앞에 추가하여 LLM이 요청한 작업을 수행하기 전에 워크플로 단계(커밋, 푸시 등)를 완료하도록 안내합니다. | -**Pi의 제한 사항.** Pi의 `AgentEndEvent`(Claude의 `Stop` 훅에 해당하는 업스트림 이벤트)에는 Result 타입이 없습니다 — 실행될 때 Pi의 에이전트 루프가 이미 종료된 상태입니다. Pi는 Claude / Copilot / Cursor / Gemini / OpenCode처럼 동일한 루프를 강제로 재시도할 수 없습니다. failproofai는 게이트를 Pi의 `before_agent_start` 이벤트(다음 사용자 프롬프트 이후에 실행됨)로 이동하여 워크플로 확인이 여전히 적용되도록 합니다. 단, 현재 턴이 아닌 다음 턴에 적용됩니다. +**Pi 제한사항.** Pi의 `AgentEndEvent`(Claude의 `Stop` 훅에 해당하는 업스트림)에는 Result 타입이 없습니다 — 실행될 때쯤이면 Pi의 에이전트 루프가 이미 종료된 상태입니다. Pi는 Claude / Copilot / Cursor / Gemini / OpenCode처럼 동일한 루프를 강제로 재시도할 수 없습니다. failproofai는 게이트를 Pi의 `before_agent_start` 이벤트(다음 사용자 프롬프트 후에 실행됨)로 이동하므로 워크플로 확인은 현재 턴이 아닌 다음 턴에 적용됩니다. -**실제로 이것이 의미하는 바:** +**실제로 의미하는 것:** -- Pi가 중단된 후, deny 이유는 Pi 세션 id로 키잉된 인메모리에 캡처됩니다. 동일한 Pi 프로세스에서 제출하는 바로 다음 프롬프트가 이를 소비합니다: LLM은 시스템 프롬프트 상단에 `MANDATORY ACTION REQUIRED` 지시문을 보고, 커밋(또는 푸시 / PR 열기 / CI 대기)한 다음 요청을 계속합니다. 캡처된 deny 이유는 한 번만 소비됩니다 — 소비되면 게이트가 해제됩니다. -- 게이트는 Pi의 프로세스 수명에 의해 제한됩니다. 턴 사이에 Pi를 `Ctrl+C`하거나 종료하면 인메모리 항목이 프로세스와 함께 삭제되고 게이트를 놓치게 됩니다. Claude, Copilot, Cursor, Gemini, OpenCode도 동일한 제한이 있습니다(에이전트를 종료하면 게이트를 놓침) — Pi는 에이전트가 게이트 실행 전에 눈에 띄게 종료되기 때문에 이를 더 분명하게 만들 뿐입니다. -- 보류 중인 deny는 어떤 이유로든 `session_shutdown`(`new` / `resume` / `fork` / `quit`) 시 지워지므로, 이전 세션의 오래된 게이트가 동일한 Pi 프로세스에서 시작된 새 세션으로 누출될 수 없습니다. +- Pi가 중단된 후, 거부 이유는 Pi 세션 id로 키된 인메모리에 캡처됩니다. 동일한 Pi 프로세스에서 다음에 제출하는 프롬프트가 이를 소비합니다: LLM은 시스템 프롬프트 상단에 `MANDATORY ACTION REQUIRED` 지시문을 보고, 커밋(또는 푸시 / PR 열기 / CI 대기)을 수행한 후 요청을 계속합니다. 캡처된 거부 이유는 일회성입니다 — 소비되면 게이트가 해제됩니다. +- 게이트는 Pi의 프로세스 수명에 의해 제한됩니다. 턴 사이에 Pi를 `Ctrl+C`하거나 종료하면 인메모리 항목이 프로세스와 함께 삭제되고 게이트가 놓칩니다. Claude, Copilot, Cursor, Gemini, OpenCode도 동일한 제한이 있습니다(에이전트를 종료하면 게이트가 놓침) — Pi는 에이전트가 게이트가 실행되기 전에 눈에 띄게 종료되므로 더 명확하게 보입니다. +- 보류 중인 거부는 어떤 이유로든(`new` / `resume` / `fork` / `quit`) `session_shutdown` 시에도 지워지므로, 이전 세션의 오래된 게이트가 동일한 Pi 프로세스에서 시작된 새 세션으로 누출될 수 없습니다. -Claude 스타일의 동일 루프 재시도가 필요하다면, 다른 여섯 가지 지원 CLI 중 하나에서 `Stop` 정책을 실행하세요. Pi 업스트림에서 이 격차를 해소할 수 있는 `AgentEndEvent`의 향후 Result 타입을 추적하고 있습니다. +동일 루프 재시도가 필요하다면 다른 6개의 지원 CLI 중 하나에서 `Stop` 정책을 실행하세요. 이 격차를 해소할 수 있는 `AgentEndEvent`의 향후 Result 타입에 대해 Pi 업스트림을 추적 중입니다. ### `require-commit-before-stop` **이벤트:** Stop -**기본값:** 커밋되지 않은 변경 사항(수정, 스테이징, 추적되지 않은 파일)이 있을 때 중단을 차단합니다. 작업 디렉토리가 깨끗할 때 안내 메시지를 반환합니다. +**기본값:** 커밋되지 않은 변경 사항(수정됨, 스테이징됨, 또는 추적되지 않는 파일)이 있을 때 중단을 거부합니다. 작업 디렉토리가 깨끗하면 정보 메시지를 반환합니다. -파라미터 없음. +매개변수 없음. --- ### `require-push-before-stop` **이벤트:** Stop -**기본값:** 푸시되지 않은 커밋이 있거나 현재 브랜치에 원격 추적 브랜치가 없을 때 중단을 차단합니다. 필요한 경우 `git push -u`를 통해 추적 브랜치를 생성하도록 제안합니다. 원격이 구성되지 않은 경우 fail-open됩니다. +**기본값:** 푸시되지 않은 커밋이 있거나 현재 브랜치에 원격 추적 브랜치가 없을 때 중단을 거부합니다. 필요한 경우 추적 브랜치를 생성하기 위해 `git push -u`를 제안합니다. 리모트가 설정되지 않은 경우 fail-open 방식으로 동작합니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | 푸시할 원격 이름. | +| `remote` | `string` | `"origin"` | 푸시할 리모트 이름. | **예시:** @@ -765,13 +771,15 @@ Claude 스타일의 동일 루프 재시도가 필요하다면, 다른 여섯 ### `require-pr-before-stop` **이벤트:** Stop -**기본값:** 현재 브랜치에 풀 리퀘스트가 없거나 기존 PR이 병합 없이 닫힌 경우 중단을 차단합니다. Claude에게 `gh pr create`로 PR을 생성하도록 지시합니다. PR이 **병합**되면 정책은 허용하고(작업이 배포됨) 브랜치에서 전환하도록 힌트를 제공합니다(`git checkout main && git pull`). +**기본값:** 현재 브랜치에 대한 풀 리퀘스트가 없거나 기존 PR이 병합 없이 닫힌 경우 중단을 거부합니다. `gh pr create`로 PR을 생성하도록 Claude에게 안내합니다. PR이 **병합**되면 정책은 허용하고(작업이 배포됨) 브랜치에서 전환하도록 힌트를 제공합니다(`git checkout main && git pull`). -파라미터 없음. +매개변수 없음. -이 정책은 [GitHub CLI](https://cli.github.com/)(`gh`)가 설치되고 인증된 상태를 요구합니다. -풀 리퀘스트에 대한 읽기 접근을 위해 `repo` 스코프가 있는 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되지 않았거나 인증되지 않은 경우, 정책은 fail-open되고 Claude에게 이유를 보고합니다. +이 정책은 [GitHub CLI](https://cli.github.com/) (`gh`)가 설치되어 인증되어 있어야 합니다. +풀 리퀘스트에 대한 읽기 액세스를 위해 `repo` 스코프가 있는 개인 액세스 토큰으로 +`gh auth login`을 실행하세요. `gh`가 설치되지 않았거나 인증되지 않은 경우 정책은 +fail-open 방식으로 동작하고 이유를 Claude에게 보고합니다. --- @@ -779,21 +787,21 @@ Claude 스타일의 동일 루프 재시도가 필요하다면, 다른 여섯 ### `require-no-conflicts-before-stop` **이벤트:** Stop -**기본값:** 현재 브랜치가 베이스 브랜치에 깔끔하게 병합될 수 없을 때 중단을 차단합니다. 정책은 먼저 브랜치에 대한 GitHub의 `OPEN` PR이 있는지 확인합니다 — PR이 없으면 적용할 병합 대상이 없으므로 전체 정책이 단락 평가되어 허용됩니다. `OPEN` PR이 확인되면 두 가지 독립적인 검사가 실행됩니다: +**기본값:** 현재 브랜치가 베이스 브랜치에 깨끗하게 병합될 수 없을 때 중단을 거부합니다. 정책은 먼저 해당 브랜치에 대한 GitHub의 `OPEN` PR이 있는지 확인합니다 — PR이 없으면 강제할 병합 대상이 없으므로 전체 정책이 allow로 단락됩니다. `OPEN` PR이 확인되면 두 가지 독립적인 프로브가 실행됩니다: -1. **로컬** — `git merge-tree --write-tree --name-only origin/ HEAD`. 충돌 시, deny 메시지에 충돌 파일 이름을 표시하여 Claude가 무엇을 해결해야 하는지 정확히 알 수 있습니다. -2. **GitHub** — 사전 확인에서 이미 가져온 `gh pr view --json mergeable,state` 결과를 재사용합니다. 오래된 로컬 `origin/`가 놓칠 수 있는 충돌을 감지합니다(예: 마지막 fetch 이후 누군가가 충돌하는 PR을 `main`에 병합한 경우). `CONFLICTING` 결과는 차단됩니다. `UNKNOWN` 결과도 차단되며 Claude에게 다시 중단을 시도하기 전에 약 10초 대기하고 재확인하도록 지시합니다 — 이는 GitHub가 재계산하는 동안 거짓 음성을 방지합니다. +1. **로컬** — `git merge-tree --write-tree --name-only origin/ HEAD`. 충돌 시 거부 메시지에 충돌된 파일 이름이 포함되어 Claude가 정확히 무엇을 해결해야 하는지 알 수 있습니다. +2. **GitHub** — 사전 확인에서 이미 가져온 `gh pr view --json mergeable,state` 결과를 재사용합니다. 오래된 로컬 `origin/`가 놓칠 수 있는 충돌을 감지합니다 (예: 마지막 fetch 이후 누군가가 `main`에 충돌하는 PR을 병합한 경우). `CONFLICTING` 결과는 거부됩니다. `UNKNOWN` 결과도 거부되며 Claude에게 다시 중단을 시도하기 전에 약 10초 기다리고 재확인하도록 안내합니다 — 이는 GitHub가 재계산하는 동안의 false negative를 방지합니다. -다음의 경우 완전히 건너뜁니다(허용): `gh`가 설치되지 않음, 브랜치에 PR이 없음, PR 상태가 `OPEN`이 아님(예: `MERGED`, `CLOSED`), 또는 `gh pr view`가 파싱 불가능한 출력을 반환함. 로컬에 `origin/`가 없거나 베이스보다 앞선 커밋이 없는 경우에도 fail-open됩니다 — 이러한 레이어 1 폴스루는 허용하기 전에 캐시된 PR 병합 가능성을 여전히 참조합니다. +다음 경우에 전체 건너뜁니다(허용): `gh`가 설치되지 않음, 브랜치에 대한 PR이 없음, PR의 상태가 `OPEN`이 아님 (예: `MERGED`, `CLOSED`), 또는 `gh pr view`가 파싱 불가능한 출력을 반환. `origin/`가 로컬에 없거나 베이스보다 앞선 커밋이 없을 때도 fail-open 방식으로 동작합니다 — 이러한 Layer 1 폴스루는 허용하기 전에 캐시된 PR 병합 가능성을 계속 참조합니다. -**파라미터:** +**매개변수:** -| 파라미터 | 타입 | 기본값 | 설명 | +| 매개변수 | 타입 | 기본값 | 설명 | |-------|------|---------|-------------| | `baseBranch` | `string` | `"main"` | 충돌을 확인할 베이스 브랜치. | -이 정책에는 GitHub CLI(`gh`)가 필요합니다. 정책은 충돌 검사를 실행하기 전에 `gh pr view`를 사용하여 `OPEN` PR이 있는지 확인합니다 — `gh` 없이는 정책이 단락 평가되어 허용됩니다. 풀 리퀘스트에 대한 읽기 접근을 위해 `repo` 스코프가 있는 개인 액세스 토큰으로 `gh auth login`을 실행하세요. +이 정책에는 GitHub CLI (`gh`)가 필요합니다. 정책은 충돌 프로브를 실행하기 전에 `gh pr view`를 사용하여 `OPEN` PR이 존재하는지 확인합니다 — `gh` 없이는 정책이 allow로 단락됩니다. 풀 리퀘스트에 대한 읽기 액세스를 위해 `repo` 스코프가 있는 개인 액세스 토큰으로 `gh auth login`을 실행하세요. --- @@ -801,13 +809,15 @@ Claude 스타일의 동일 루프 재시도가 필요하다면, 다른 여섯 ### `require-ci-green-before-stop` **이벤트:** Stop -**기본값:** 현재 브랜치의 CI 검사가 실패하거나 실행 중일 때 중단을 차단합니다. GitHub Actions 워크플로 실행과 서드파티 봇 검사(예: CodeRabbit, SonarCloud, Codecov)를 모두 확인합니다. `skipped`, `cancelled`, `neutral` 결론은 실패로 처리하지 않습니다(후자는 예를 들어 외부 기여자 PR에서의 Socket Security 알림을 포함합니다. 여기서 앱은 의도적으로 성공/실패 대신 neutral을 보고합니다). 모든 검사가 통과되면 안내 메시지를 반환합니다. +**기본값:** 현재 브랜치에서 CI 확인이 실패하거나 아직 실행 중일 때 중단을 거부합니다. GitHub Actions 워크플로 실행과 서드파티 봇 확인(예: CodeRabbit, SonarCloud, Codecov)을 모두 확인합니다. `skipped`, `cancelled`, `neutral` 결론은 실패로 처리하지 않습니다 (후자는 예를 들어 앱이 의도적으로 성공/실패 대신 neutral을 보고하는 외부 기여자 PR의 Socket Security 알림을 포함). 모든 확인이 통과되면 정보 메시지를 반환합니다. -파라미터 없음. +매개변수 없음. -이 정책은 [GitHub CLI](https://cli.github.com/)(`gh`)가 설치되고 인증된 상태를 요구합니다. -Actions 워크플로 실행 및 Checks API에 대한 읽기 접근을 위해 `repo` 스코프가 있는 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되지 않았거나 인증되지 않은 경우, 정책은 fail-open되고 Claude에게 이유를 보고합니다. +이 정책은 [GitHub CLI](https://cli.github.com/) (`gh`)가 설치되어 인증되어 있어야 합니다. +Actions 워크플로 실행 및 Checks API에 대한 읽기 액세스를 위해 `repo` 스코프가 있는 +개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되지 않았거나 인증되지 않은 +경우 정책은 fail-open 방식으로 동작하고 이유를 Claude에게 보고합니다. --- @@ -816,7 +826,7 @@ Actions 워크플로 실행 및 Checks API에 대한 읽기 접근을 위해 `re ## 개별 정책 비활성화 -설정의 `enabledPolicies`에서 특정 정책을 제거하거나 대시보드의 Policies 탭에서 비활성화하세요. +설정 파일의 `enabledPolicies`에서 특정 정책을 제거하거나, 대시보드의 정책 탭에서 해제하세요. ```json { @@ -827,4 +837,4 @@ Actions 워크플로 실행 및 Checks API에 대한 읽기 접근을 위해 `re } ``` -`enabledPolicies`에 나열되지 않은 정책은 `policyParams` 항목이 있더라도 실행되지 않습니다. \ No newline at end of file +`enabledPolicies`에 나열되지 않은 정책은 `policyParams` 항목이 존재하더라도 실행되지 않습니다. \ No newline at end of file diff --git a/docs/ko/cli/audit.mdx b/docs/ko/cli/audit.mdx index 40bab927..2162ed39 100644 --- a/docs/ko/cli/audit.mdx +++ b/docs/ko/cli/audit.mdx @@ -1,25 +1,25 @@ --- title: 과거 세션 감사 (베타) -description: "과거 트랜스크립트에서 에이전트가 낭비적이거나 위험한 행동을 얼마나 자주 했는지 집계" +description: "과거 트랜스크립트에서 에이전트가 낭비적이거나 위험한 작업을 얼마나 자주 수행했는지 집계" --- **베타 기능.** 초기 피드백을 수집하는 동안 감사 기능은 베타로 제공됩니다. - 다음 안정 버전 출시 전까지 감지기 카탈로그와 리포트 형식이 변경될 수 있습니다. + 다음 안정 버전 전까지 감지기 카탈로그 및 보고서 형식이 변경될 수 있습니다. 이상한 점이 있으면 이슈를 열어 주세요. -감사 기능은 과거 에이전트 CLI 트랜스크립트를 failproofai의 정책 엔진으로 재실행하여, -**`/audit` 대시보드 페이지**에 공유 가능한 시각적 리포트를 렌더링합니다. -에이전트의 아키타입, 0~100점 점수, 그리고 어떤 정책이 무엇을 잡아냈을지 구체적으로 보여줍니다. +감사 기능은 과거 에이전트 CLI 트랜스크립트를 failproofai의 정책 엔진을 통해 재실행하고, +**`/audit` 대시보드 페이지**에 공유 가능한 시각적 보고서를 렌더링합니다 — +에이전트의 아키타입, 0~100점 점수, 그리고 어떤 정책이 무엇을 잡아냈을지 정확히 표시합니다. ## 실행 방법 -세 가지 방법이 있으며, 모두 동일한 `/audit` 리포트로 연결됩니다. +세 가지 방법 모두 동일한 `/audit` 보고서로 연결됩니다. -```bash npx (no install) +```bash npx (설치 불필요) npx -y failproofai audit ``` @@ -27,7 +27,7 @@ npx -y failproofai audit failproofai audit ``` -```bash failproofai (dashboard) +```bash failproofai (대시보드) failproofai ``` @@ -35,56 +35,61 @@ failproofai - `npx -y failproofai audit`는 failproofai를 가져와 스캔을 실행하고 대시보드를 열어줍니다 — 사전 설치가 필요 없습니다. + `npx -y failproofai audit`는 failproofai를 가져와 스캔을 실행하고 대시보드를 + 자동으로 열어줍니다 — 사전 설치가 필요 없습니다. - `failproofai audit`는 터미널에서 스캔을 실행한 뒤, 완료되면 자동으로 `localhost:8020/audit`를 엽니다. + `failproofai audit`는 터미널에서 스캔을 실행한 후 완료 시 자동으로 + `localhost:8020/audit`를 엽니다. - `failproofai`를 실행하고 내비게이션 바의 **Audit**을 클릭하거나(Policies와 Projects 사이), `/audit`을 직접 여세요. + `failproofai`를 실행하고 네비게이션 바(Policies와 Projects 사이)에서 + **Audit**을 클릭하거나, `/audit`를 직접 열어주세요. - `failproofai audit -h` (또는 `--help`)를 실행하면 사용법을 확인할 수 있습니다. 감사는 **완전히 오프라인**으로 실행되며 — 계정이나 네트워크가 필요 없습니다 — `Ctrl+C`로 중지할 때까지 대시보드가 계속 서비스됩니다. + 사용법을 확인하려면 `failproofai audit -h` (또는 `--help`)를 실행하세요. 감사는 + **완전 오프라인**으로 실행됩니다 — 계정이나 네트워크가 필요 없습니다 — 그리고 + 대시보드는 `Ctrl+C`로 중지할 때까지 계속 서비스됩니다. -대시보드는 이 머신에 있는 과거 에이전트 CLI 트랜스크립트(Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini)를 스캔하여, failproofai가 차단하도록 설계된 행동들 — 환경 변수 확인, 강제 푸시, 불필요한 `cd ` 접두사, sleep 폴링 루프, 방금 편집한 파일 재읽기 등 — 이 얼마나 자주 발생했는지 보고합니다. +대시보드는 이 머신의 과거 에이전트 CLI 트랜스크립트(Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini)를 스캔하고, failproofai가 막도록 설계된 작업들 — env-var 검사, 강제 푸시, 불필요한 `cd ` 접두사, sleep 폴링 루프, 방금 편집한 파일 재읽기 등 — 을 에이전트가 얼마나 자주 수행했는지 보고합니다. -각 트랜스크립트에서 모든 툴 사용 이벤트는 39개의 내장 정책과 런타임 정책으로 아직 다루지 않는 패턴을 잡아내는 8개의 감사 전용 감지기를 통해 재실행됩니다. 카운트는 모든 세션에 걸쳐 정책/감지기별로 집계됩니다. +각 트랜스크립트에 대해 모든 도구 사용 이벤트는 39개의 내장 정책 **및** 런타임 정책으로 아직 처리되지 않는 패턴을 잡아내는 8개의 감사 전용 감지기를 통해 재실행됩니다. 횟수는 모든 세션에 걸쳐 정책/감지기별로 집계됩니다. -## 결과물 +## 제공 내용 -`/audit` 페이지는 단일 화면의 공유 가능한 **포스터**와 그 아래 네 개의 섹션으로 구성됩니다. +`/audit` 페이지는 단일 화면의 공유 가능한 **포스터**와 그 아래 네 개의 섹션으로 구성됩니다: -1. **포스터** — 에이전트의 정체성을 한눈에: **아키타입**(8가지 중 하나 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), 페르소나 키워드, 해당 아키타입의 희귀도, 그리고 등급 밴드(`S`부터 `bottom tier`)가 포함된 **0~100점 점수**. 공유용으로 제작 — X나 LinkedIn에 게시하거나 PNG로 다운로드하세요. -2. **`// strengths`** — 에이전트가 이미 잘하는 것들을 스캔의 실제 수치로 표시 (예: 클린 툴 호출 %, `0`회의 main 푸시 시도). 해당 정책이 깨끗한 기록을 가진 경우에만 표시됩니다. -3. **`// quirks`** — 놓친 것들: failproofai가 잡아냈을 행동의 순위 테이블 — *마지막 발생 시점*, *놓친 내용*(및 차단했을 내장 정책), *심각도*, 그리고 발생 빈도(`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — 처방된 수정 목록: 복사-붙여넣기 가능한 `failproofai policy add `가 포함된 정책별 행, 모든 권장 사항을 한 번에 활성화하는 **install all** 버튼, 그리고 실행 시의 **예상 점수**. -5. **`// come back better`** — 습관 만들기: 재감사 이메일 **알림** 설정(`3d` / `7d` / `14d` / `30d`) 또는 즉시 재감사, **친구 초대**로 본인의 감사 실행 유도 (failproof.ai에서 발송, 수신자 참조로 귀하에게 전달). 알림 및 초대는 로그인이 필요합니다 — [`failproofai auth`](/ko/cli/auth)를 참조하세요. +1. **포스터** — 에이전트의 정체성을 한눈에: **아키타입** (8가지 중 하나 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), 페르소나 키워드, 해당 아키타입의 희귀도, 그리고 등급 밴드가 표시된 **0~100 점수** (`S`부터 `bottom tier`까지). 공유용으로 설계 — X나 LinkedIn에 게시하거나 PNG로 다운로드하세요. +2. **`// strengths`** — 에이전트가 이미 잘 하고 있는 것을 스캔의 실제 수치로 표시 (예: clean-tool-call %, `0`번의 push-to-main 시도) — 관련 정책에 깨끗한 기록이 있는 경우에만 표시됩니다. +3. **`// quirks`** — 빠져나간 것들: failproofai가 잡아냈을 동작의 순위 테이블 — *마지막으로 발생한 시점*, *무엇이 빠져나갔는지* (그리고 막았을 내장 정책), *심각도*, 그리고 얼마나 자주 *발견되었는지* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — 처방된 수정 목록: 복사하여 붙여넣을 수 있는 `failproofai policy add `가 포함된 정책당 한 행, 그리고 모든 권장 사항을 한 번에 활성화하고 **예상 점수**를 표시하는 **install all** 버튼. +5. **`// come back better`** — 습관 만들기: 재감사 이메일 **알림** 설정 (`3d` / `7d` / `14d` / `30d`) 또는 지금 바로 재감사, **친구 초대**로 자신의 감사를 실행하게 하기 (failproof.ai에서 발송, Cc를 나에게). 알림과 초대는 로그인이 필요합니다 — [`failproofai auth`](/ko/cli/auth)를 참고하세요. ## 감사 전용 감지기 -이는 실시간으로 (아직) 적용되지 않는 "비효율적 행동" 패턴을 감지합니다. 감사 중에만 실행되며 라이브 툴 호출을 절대 차단하지 않습니다. +이는 실시간으로 (아직) 적용되지 않는 "비효율적인 동작" 패턴을 감지합니다. 감사 중에만 실행되며 라이브 도구 호출을 절대 차단하지 않습니다. | 감지기 | 집계 내용 | |---|---| -| `redundant-cd-cwd` | 명령이 이미 `cwd`에서 실행되는데도 `cd && …`로 시작하는 Bash 명령. | -| `prefer-edit-over-read-cat` | 단일 소스 파일에 대한 `cat`/`head`/`tail`/`less`/`more` — `Read` 툴을 사용하세요. | -| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` 인플레이스 편집 — `Edit` 툴을 사용하세요. | -| `prefer-write-over-heredoc` | 파일을 작성하는 Heredoc / 멀티라인 `echo > file` — `Write` 툴을 사용하세요. | +| `redundant-cd-cwd` | 명령이 이미 `cwd`에서 실행됨에도 `cd && …`로 시작하는 Bash 명령. | +| `prefer-edit-over-read-cat` | 단일 소스 파일에 대한 `cat`/`head`/`tail`/`less`/`more` — `Read` 도구를 사용하세요. | +| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` 인플레이스 편집 — `Edit` 도구를 사용하세요. | +| `prefer-write-over-heredoc` | Heredoc / 멀티라인 `echo > file`로 파일 작성 — `Write` 도구를 사용하세요. | | `sleep-polling-loop` | 긴 `sleep N` (≥ 30초) 또는 `while …; sleep …; done` 폴링 루프. | -| `find-from-root` | `find /`, `find /home`, `find /usr` 등 — `cwd`로 범위를 좁히세요. | -| `git-commit-no-verify` | 훅을 건너뛰는 `git commit … --no-verify` / `-n`. | -| `reread-after-edit` | 같은 세션에서 `Edit`/`Write`된 직후 파일을 `Read`하는 경우. | +| `find-from-root` | `find /`, `find /home`, `find /usr` 등 — `cwd`로 범위를 제한하세요. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, 훅 건너뛰기. | +| `reread-after-edit` | 같은 세션에서 `Edit`/`Write`한 직후 해당 파일을 `Read`. | ## 캐시 -- `~/.failproofai/cache/audit/.json`의 **트랜스크립트별 캐시** — `(mtime, size, engineVersion, detectorVersion)`을 키로 하며, 트랜스크립트나 정책/감지기 코드가 변경되면 자동으로 무효화됩니다. 각 항목에는 **TTL 메타데이터**로 `cachedAt` 타임스탬프가 저장됩니다(캐시 키의 일부가 아님). **7일**이 지난 항목은 읽기 시 거부되어 오래된 결과가 진화하는 감지기 의도를 벗어나지 않도록 합니다. -- `~/.failproofai/audit-dashboard.json`의 **전체 결과 캐시** (모드 0600). 내비게이션 시 재실행 없이 대시보드를 즉시 렌더링할 수 있게 해줍니다. **7일 TTL**이 지나면 읽기 시 거부되며, `/audit`는 빈 상태로 돌아가 새 실행을 안내합니다. 리포트 하단의 `[ re-audit now ]`를 클릭하면 새로고침됩니다 — 재감사는 `noCache: true`를 전송하여 트랜스크립트별 캐시를 우회하고 캐시된 결과 대신 모든 트랜스크립트를 재스캔합니다. 실행은 상단 고정 스트립을 통해 진행 상황을 스트리밍하고, 성공 시 결과를 제자리에서 교체합니다(페이지 새로고침 없음; 재감사 실패 시 이전 리포트 유지). +- **트랜스크립트별 캐시** — `~/.failproofai/cache/audit/.json`에 `(mtime, size, engineVersion, detectorVersion)`를 키로 저장 — 트랜스크립트 또는 정책/감지기 코드가 변경되면 자동으로 무효화됩니다. 각 항목은 **TTL 메타데이터**로 `cachedAt` 타임스탬프도 저장합니다 (캐시 키의 일부가 아님); **7일**이 지난 항목은 읽기 시 거부되므로 오래된 결과가 진화하는 감지기 의도를 초과하지 않습니다. +- **전체 결과 캐시** — `~/.failproofai/audit-dashboard.json` (모드 0600). 재실행 없이 대시보드를 즉시 렌더링할 수 있게 해줍니다. **7일 TTL**을 초과하면 읽기 시 거부 — `/audit`는 빈 상태로 폴백하고 새로운 실행을 요청합니다. 보고서 하단의 `[ re-audit now ]`를 클릭하여 새로고침 — 재감사는 `noCache: true`를 전송하므로 트랜스크립트별 캐시를 우회하고 캐시된 결과 대신 모든 트랜스크립트를 재스캔합니다; 실행은 고정된 상단 스트립을 통해 진행 상황을 스트리밍하고 성공 시 결과를 현재 위치에서 교체합니다 (페이지 리로드 없음; 재감사 실패 시 이전 보고서 유지). ## 참고 사항 - **변경 없음.** 감사는 읽기 전용 모드로 재실행됩니다. `warn-repeated-tool-calls`는 세션별 사이드카가 수정될 수 있으므로 건너뜁니다. -- **워크플로 정책 건너뜀.** `require-*-before-stop` 정책은 `Stop` 이벤트에서만 실행되고 라이브 git 상태에 대해 `execSync`를 수행합니다 — "2025년에 어떤 일이 일어났을까"에 대한 의미 있는 해석이 없으므로 감사 카운트에 나타나지 않습니다. -- **커스텀 정책 건너뜀.** 사용자가 제공한 커스텀 훅은 재실행되지 않습니다(원래 세션 이후 변경되었을 수 있음). \ No newline at end of file +- **워크플로 정책 건너뜀.** `require-*-before-stop` 정책은 `Stop` 이벤트에서만 실행되고 라이브 git 상태에 대해 `execSync`를 수행합니다 — "2025년에 어떤 일이 일어났을까"에 대한 의미 있는 해석이 없으므로 감사 횟수에 나타나지 않습니다. +- **커스텀 정책 건너뜀.** 사용자 제공 커스텀 훅은 재실행되지 않습니다 (원래 세션 이후 변경되었을 수 있음). \ No newline at end of file diff --git a/docs/ko/cli/auth.mdx b/docs/ko/cli/auth.mdx index 9addb8b7..c6dbf4c6 100644 --- a/docs/ko/cli/auth.mdx +++ b/docs/ko/cli/auth.mdx @@ -1,6 +1,6 @@ --- title: 로그인 -description: "CLI에서 FailproofAI에 로그인하여 리마인더 및 개인화된 기능을 활성화합니다" +description: "알림 및 개인화 기능을 활성화하려면 CLI에서 FailproofAI에 로그인하세요" --- ```bash @@ -9,9 +9,9 @@ failproofai auth logout # 현재 세션 취소 failproofai auth whoami # 로그인된 계정 정보 출력 ``` -하위 호환성을 위해 기존의 `--login` / `--logout` / `--whoami` 플래그 형식도 별칭으로 계속 사용할 수 있습니다. +하위 호환성을 위해 기존 `--login` / `--logout` / `--whoami` 플래그 형식도 별칭으로 계속 사용할 수 있습니다. -인증은 선택 사항입니다. 정책, 대시보드, `/audit` 페이지를 비롯한 모든 로컬 기능은 로그인 여부와 관계없이 동일하게 작동합니다. 로그인 기능은 안정적인 신원이 **필요한** 기능(현재는 재감사 리마인더, 향후 더 많은 기능 예정)을 위한 기반을 제공하기 위해 존재합니다. +인증은 선택 사항입니다. 정책, 대시보드, `/audit` 페이지 및 기타 모든 로컬 기능은 로그인 여부와 관계없이 동일하게 작동합니다. 로그인 기능은 안정적인 신원이 **필요한** 기능(현재는 재감사 알림, 향후 더 많은 기능 예정)을 위해 존재합니다. ## 로그인 흐름 @@ -19,9 +19,9 @@ failproofai auth whoami # 로그인된 계정 정보 출력 failproofai auth login ``` -이메일 입력을 요청하고, 해당 주소로 6자리 일회용 코드를 발송하며, 코드 입력을 요청합니다. 성공 시 `~/.failproofai/auth.json` (모드 `0600`)이 저장됩니다. 동일한 세션은 인앱 대시보드에서도 확인할 수 있으며, `/audit`에서 `[ set a reminder ]`를 클릭하면 로그인된 상태로 인식됩니다. +이메일 주소를 입력하라는 프롬프트가 표시되고, 해당 주소로 6자리 일회용 코드가 전송되며, 코드를 입력하면 성공 시 `~/.failproofai/auth.json`(권한 `0600`)이 작성됩니다. 동일한 세션이 인앱 대시보드에서도 확인되며, `/audit`에서 `[ set a reminder ]`를 클릭하면 로그인 상태로 인식됩니다. -대시보드는 CLI를 사용하지 않는 사용자를 위해 `/audit`에서 모달 다이얼로그 형태로 동일한 흐름을 제공합니다. +대시보드는 CLI를 사용하지 않는 사용자를 위해 `/audit`에서 동일한 흐름을 모달 다이얼로그 형태로 제공합니다. ## 로그아웃 @@ -29,7 +29,7 @@ failproofai auth login failproofai auth logout ``` -서버에서 현재 세션을 취소하고 `~/.failproofai/auth.json`을 삭제합니다. API 서버에 연결할 수 없는 경우에도 로컬 파일은 삭제됩니다 — 로컬에서의 로그아웃 의도가 항상 우선합니다. +서버의 현재 세션을 취소하고 `~/.failproofai/auth.json`을 삭제합니다. API 서버에 접근할 수 없는 경우에도 로컬 파일은 삭제됩니다 — 로그아웃하려는 로컬 의도가 항상 우선합니다. ## 계정 확인 @@ -37,11 +37,11 @@ failproofai auth logout failproofai auth whoami ``` -유효한 세션이 있을 경우 ` ()`를 출력하고 종료 코드 0으로 종료하며, 로그인되지 않은 경우 `not signed in`을 출력하고 종료 코드 1로 종료합니다. 액세스 토큰이 만료 1분 이내인 경우 백그라운드에서 자동으로 갱신합니다. +유효한 세션이 존재하면 ` ()`를 출력하고 종료 코드 0으로 종료하며, 로그인되어 있지 않으면 `not signed in`을 출력하고 종료 코드 1로 종료합니다. 액세스 토큰이 만료 1분 이내인 경우 백그라운드에서 자동으로 갱신합니다. -## 지속적인 재감사 리마인더 +## 지속적인 재감사 알림 -`/audit` 페이지에서 **`[ set a reminder ]`** 를 클릭하거나 해당 버튼이 연결된 모달을 통해 로그인하면, 대시보드가 `~/.failproofai/next-audit.json`에 소형 보조 파일을 생성합니다: +`/audit` 페이지에서 **`[ set a reminder ]`**를 클릭하거나(또는 해당 버튼이 표시하는 모달을 통해 로그인하면), 대시보드가 `~/.failproofai/next-audit.json`에 소규모 보조 파일을 작성합니다: ```json { @@ -51,11 +51,11 @@ failproofai auth whoami } ``` -이 파일은 설정한 이메일 계정에 귀속됩니다 — CLI 세션을 다른 계정으로 전환하면 이전 사용자에게 속한 리마인더는 표시되지 않습니다. 기본 오프셋은 **7일**이며, 스케줄러가 도입되면 이후에 설정 가능합니다. `auth.json`과 동일하게 `0600` 권한으로 생성됩니다. +이 파일은 설정한 이메일에 종속됩니다 — CLI 세션을 다른 계정으로 전환하면 이전 사용자의 알림은 숨겨집니다. 기본 오프셋은 **7일**이며, 스케줄러가 도입되면 나중에 설정할 수 있습니다. `auth.json`과 마찬가지로 `0600` 권한으로 생성됩니다. -대시보드의 `/api/auth/reminder` 엔드포인트는 활성 세션이 필요하며 `GET`(조회), `POST`(설정/재예약), `DELETE`(삭제)를 지원합니다. +대시보드의 `/api/auth/reminder` 엔드포인트는 `GET`(읽기), `POST`(설정/재예약), `DELETE`(삭제)를 제공하며 활성 세션이 필요합니다. -## `~/.failproofai/auth.json` 내용 +## `~/.failproofai/auth.json`의 내용 ```json { @@ -67,21 +67,21 @@ failproofai auth whoami } ``` -`0600` 권한(소유자 전용 읽기/쓰기)으로 생성됩니다. 액세스 토큰은 유효 기간 1시간의 HS256 JWT이며, 리프레시 토큰은 서버가 `SHA-256(token)` 형태로 저장하는 불투명한 256비트 난수 문자열입니다. 리프레시 토큰 재사용이 서버 측에서 감지되면 해당 사용자의 모든 세션이 취소됩니다. +`0600` 권한(소유자 전용 읽기/쓰기)으로 생성됩니다. 액세스 토큰은 1시간 유효한 HS256 JWT이며, 리프레시 토큰은 서버가 `SHA-256(token)`으로 저장하는 불투명한 256비트 랜덤 문자열입니다. 리프레시 토큰 재사용이 서버 측에서 감지되면 해당 사용자의 모든 세션이 취소됩니다. ## 환경 변수 -| 변수 | 기본값 | 용도 | +| 변수 | 기본값 | 목적 | |---|---|---| -| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | API 서버 기본 URL을 재정의합니다. 자체 호스팅된 API 서버를 대상으로 로컬 개발 시 유용합니다. | -| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | `auth.json`이 저장되는 경로를 재정의합니다. 주로 테스트 용도로 사용합니다. | +| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | API 서버 기본 URL 재정의. 자체 호스팅 API 서버로 로컬 개발 시 유용합니다. | +| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | `auth.json` 저장 위치 재정의. 주로 테스트용입니다. | 전체 목록은 [환경 변수](/ko/cli/environment-variables)를 참조하세요. ## 문제 해결 -**"Could not reach the api-server"** — CLI가 `FAILPROOF_API_URL`로 TCP 연결을 열 수 없습니다. 네트워크를 확인하거나, 자체 호스팅 API 서버를 사용 중인 경우 `FAILPROOF_API_URL`을 설정하세요. +**"Could not reach the api-server"** — CLI가 `FAILPROOF_API_URL`로 TCP 연결을 열 수 없습니다. 네트워크를 확인하거나, 자체 호스팅 API 서버를 실행 중이라면 `FAILPROOF_API_URL`을 설정하세요. -**"Rate limited"** — 해당 이메일(이메일당 5회) 또는 IP(IP당 20회)에 대해 15분 이내에 로그인 시도가 너무 많거나, 동일 이메일에 대한 이전 요청 이후 30초 재발송 대기 시간이 적용된 경우입니다. 오류 메시지에 재시도 가능 시간(초)이 포함됩니다. +**"Rate limited"** — 해당 이메일(5회/이메일) 또는 IP(20회/IP)에 대해 15분 이내 로그인 시도가 너무 많거나, 같은 이메일로 이전 요청 후 30초 재전송 제한이 적용됩니다. 오류 메시지에 재시도 가능 시간(초)이 포함됩니다. -**코드 거부** — OTP가 잘못되었거나, 만료되었거나, 5회 오답 잠금에 도달한 경우입니다. `failproofai auth login`을 다시 실행하여 새 코드를 요청하세요. \ No newline at end of file +**코드 거부됨** — OTP가 잘못되었거나 만료되었거나, 5회 오답 잠금이 발생했습니다. `failproofai auth login`을 다시 실행하여 새 코드를 요청하세요. \ No newline at end of file diff --git a/docs/ko/cli/dashboard.mdx b/docs/ko/cli/dashboard.mdx index ea40f260..6db05f13 100644 --- a/docs/ko/cli/dashboard.mdx +++ b/docs/ko/cli/dashboard.mdx @@ -1,6 +1,6 @@ --- title: 세션 보기 -description: "대시보드를 실행하여 에이전트 세션을 탐색하고 정책을 관리합니다" +description: "대시보드를 실행하여 에이전트 세션을 탐색하고 정책을 관리하세요" --- ```bash @@ -12,9 +12,9 @@ failproofai ## 옵션 | 플래그 | 설명 | -|------|-------------| +|--------|------| | `--port ` | 수신 대기할 포트 (기본값: `8020`) | -| `--allowed-origins ` | 개발 리소스 접근을 허용할 호스트/IP 목록 (쉼표로 구분) | +| `--allowed-origins ` | 개발 리소스에 접근할 수 있는 호스트/IP 목록 (쉼표로 구분) | 기본값이 아닌 Claude 프로젝트 폴더를 대시보드에 지정하려면, 실행 시 `CLAUDE_PROJECTS_PATH` 환경 변수를 설정하세요. diff --git a/docs/ko/cli/environment-variables.mdx b/docs/ko/cli/environment-variables.mdx index 5619c9a0..5a4ee2c1 100644 --- a/docs/ko/cli/environment-variables.mdx +++ b/docs/ko/cli/environment-variables.mdx @@ -19,29 +19,29 @@ description: "환경 변수로 failproofai 동작 구성하기" | `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | 서버 로그 레벨 (기본값: `warn`) | | `FAILPROOFAI_HOOK_LOG_FILE` | 커스텀 훅 로그 파일 경로, 또는 기본 경로(`~/.failproofai/logs/hooks.log`)를 사용하려면 `true` | -## 텔레메트리 +## 원격 측정 | 변수 | 설명 | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | 익명 사용 통계 수집 비활성화 | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | 익명 사용 원격 측정 비활성화 | ## 인증 | 변수 | 설명 | |----------|-------------| -| `FAILPROOF_API_URL` | `failproofai auth` 및 대시보드 인증 대화상자에서 사용하는 API 서버 기본 URL 재정의. 기본값은 `https://api.befailproof.ai`이며, 로컬 api-server 실행 시 `http://localhost:8080` 등으로 설정. | -| `FAILPROOFAI_AUTH_DIR` | `auth.json`이 저장되는 경로 재정의 (기본값: `~/.failproofai`). 주로 격리된 테스트 환경에서 유용. | +| `FAILPROOF_API_URL` | `failproofai auth` 및 대시보드 인증 다이얼로그에서 사용하는 API 서버 기본 URL 재정의. 기본값은 `https://api.befailproof.ai`이며, 로컬 API 서버 실행 시 `http://localhost:8080`(또는 해당 주소)으로 설정. | +| `FAILPROOFAI_AUTH_DIR` | `auth.json` 저장 위치 재정의 (기본값: `~/.failproofai`). 주로 격리된 테스트 환경에서 유용함. | -## 첫 실행 프롬프트 +## 최초 실행 프롬프트 | 변수 | 설명 | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | 최초 `failproofai` 실행 시 정책 설치를 제안하는 프롬프트 건너뛰기 | +| `FAILPROOFAI_NO_FIRST_RUN=1` | 처음 `failproofai`를 실행할 때 정책 설치를 제안하는 프롬프트 건너뛰기 | ## LLM (정책 평가용) | 변수 | 설명 | |----------|-------------| | `FAILPROOFAI_LLM_BASE_URL` | LLM API 엔드포인트 (기본값: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | LLM 기반 정책에 사용할 API 키 | +| `FAILPROOFAI_LLM_API_KEY` | LLM 기반 정책용 API 키 | | `FAILPROOFAI_LLM_MODEL` | 모델 이름 (기본값: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/ko/cli/hook.mdx b/docs/ko/cli/hook.mdx index 2756f8f0..0ad5ddaf 100644 --- a/docs/ko/cli/hook.mdx +++ b/docs/ko/cli/hook.mdx @@ -7,24 +7,24 @@ description: "각 도구 이벤트마다 Claude Code가 호출하는 서브프 failproofai --hook ``` -이 명령어는 `failproofai policies --install`에 의해 Claude Code의 `settings.json`에 등록됩니다. 일반적으로 직접 호출할 필요는 없습니다. +이 명령은 `failproofai policies --install`이 Claude Code의 `settings.json`에 등록하는 명령입니다. 일반적으로 직접 호출할 필요가 없습니다. -stdin에서 JSON 페이로드를 읽고, 활성화된 모든 정책을 평가한 뒤, 결정 결과를 나타내는 종료 코드와 함께 종료합니다: +stdin에서 JSON 페이로드를 읽고 활성화된 모든 정책을 평가한 후, 결정 결과를 나타내는 종료 코드로 종료합니다: | 종료 코드 | 결정 | 효과 | |-----------|----------|--------| -| `0` | `allow` | 작업을 허용합니다 | -| `1` | `deny` | 작업을 차단합니다 - Claude가 거부 이유를 확인합니다 | -| `2` | `instruct` | Claude의 컨텍스트에 가이던스를 주입합니다 | +| `0` | `allow` | 작업 허용 | +| `1` | `deny` | 작업 차단 - Claude가 거부 이유를 확인함 | +| `2` | `instruct` | Claude의 컨텍스트에 가이던스 주입 | -### 지원되는 이벤트 유형 +### 지원하는 이벤트 유형 | 카테고리 | 이벤트 | |----------|--------| | **도구 실행** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | -| **세션 라이프사이클** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | -| **사용자 인터랙션** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | +| **세션 생명주기** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | +| **사용자 상호작용** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | | **서브에이전트 및 태스크** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | -| **구성** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | +| **설정** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | | **파일 시스템** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | | **컨텍스트** | `PreCompact`, `PostCompact` | \ No newline at end of file diff --git a/docs/ko/cli/install-policies.mdx b/docs/ko/cli/install-policies.mdx index a9bb18e5..de750e5c 100644 --- a/docs/ko/cli/install-policies.mdx +++ b/docs/ko/cli/install-policies.mdx @@ -1,13 +1,13 @@ --- title: 정책 설치 -description: "에이전트 도구 호출마다 정책이 실행되도록 활성화합니다" +description: "에이전트의 모든 도구 호출에 정책이 실행되도록 활성화합니다" --- ```bash failproofai policies --install [policy-names...] [options] ``` -설치된 에이전트 CLI의 설정 파일(Claude Code, OpenAI Codex, 또는 GitHub Copilot CLI _(베타)_)에 훅 항목을 작성하여 failproofai가 도구 호출을 가로챌 수 있도록 합니다. +설치된 에이전트 CLI(Claude Code, OpenAI Codex, 또는 GitHub Copilot CLI _(베타)_)의 설정 파일에 훅 항목을 작성하여 failproofai가 도구 호출을 가로챌 수 있도록 합니다. 별칭: `failproofai p -i` @@ -15,7 +15,7 @@ failproofai policies --install [policy-names...] [options] | 플래그 | 설명 | |------|-------------| -| `--cli claude\|codex\|copilot` | 설치할 에이전트 CLI. 공백으로 구분하거나(예: `--cli claude codex copilot`) 반복 지정 가능. 생략하면 설치된 CLI를 자동 감지하고 선택을 묻습니다. | +| `--cli claude\|codex\|copilot` | 설치할 에이전트 CLI; 공백으로 구분하거나(예: `--cli claude codex copilot`) 반복해서 지정할 수 있습니다. 생략하면 설치된 CLI를 자동으로 감지하여 선택을 요청합니다. | | `--scope user` | 사용자 범위 설정 파일에 설치합니다 (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). 기본값. | | `--scope project` | 프로젝트 범위 설정 파일에 설치합니다 (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | | `--scope local` | Claude 전용 — `/.claude/settings.local.json`에 설치합니다. Codex와 Copilot은 `local` 범위를 지원하지 않습니다. | @@ -23,16 +23,16 @@ failproofai policies --install [policy-names...] [options] ## 동작 방식 -- **정책 이름 미지정** - 정책을 선택할 수 있는 대화형 프롬프트를 엽니다 +- **정책 이름 미지정** - 정책을 선택할 수 있는 인터랙티브 프롬프트를 엽니다 - **특정 이름 지정** - 해당 정책을 활성화합니다 (이미 활성화된 정책에 추가됨) - **`all`** - 사용 가능한 모든 정책을 활성화합니다 -설치는 누적 방식으로 동작합니다. `--install`을 다시 실행해도 기존 정책이 제거되지 않고 새 정책만 추가됩니다. +설치는 추가 방식으로 동작합니다: `--install`을 다시 실행하면 기존 정책을 제거하지 않고 새 정책만 추가됩니다. ## 예시 ```bash -# 모든 기본 정책을 전역으로 설치 (대화형) +# 모든 기본 정책을 전역으로 설치 (인터랙티브) failproofai policies --install # 현재 프로젝트에 특정 정책 설치 @@ -44,14 +44,14 @@ failproofai policies --install all # 커스텀 정책 파일과 함께 설치 failproofai policies --install --custom ./my-policies.js -# OpenAI Codex에 설치 (프로젝트 범위) +# OpenAI Codex용 설치 (프로젝트 범위) failproofai policies --install --cli codex --scope project -# GitHub Copilot CLI (베타)에 현재 프로젝트용으로 설치 +# GitHub Copilot CLI(베타)용으로 현재 프로젝트에 설치 failproofai policies --install --cli copilot --scope project # 세 가지 CLI 모두에 한 번에 설치 failproofai policies --install --cli claude codex copilot ``` -`--custom `를 지정하면 파일이 즉시 유효성 검사를 받습니다. 해당 파일은 `customPolicies.add()`를 최소 한 번 이상 호출해야 합니다. 확인된 경로는 `customPoliciesPath`로 `policies-config.json`에 저장됩니다. \ No newline at end of file +`--custom `를 지정하면 파일이 즉시 유효성 검사를 거칩니다 — `customPolicies.add()`를 최소 한 번 이상 호출해야 합니다. 확인된 경로는 `customPoliciesPath`로 `policies-config.json`에 저장됩니다. \ No newline at end of file diff --git a/docs/ko/cli/list-policies.mdx b/docs/ko/cli/list-policies.mdx index a0729fc8..1c5bd0a9 100644 --- a/docs/ko/cli/list-policies.mdx +++ b/docs/ko/cli/list-policies.mdx @@ -1,13 +1,13 @@ --- title: 정책 목록 보기 -description: "활성화된 정책, 해당 파라미터, 그리고 커스텀 정책을 확인합니다" +description: "활성화된 정책, 매개변수, 커스텀 정책 확인하기" --- ```bash failproofai policies ``` -모든 정책의 상태, 설정된 파라미터, 그리고 커스텀 정책을 표시합니다. +모든 정책의 상태, 설정된 매개변수, 커스텀 정책을 표시합니다. ## 출력 예시 diff --git a/docs/ko/cli/remove-policies.mdx b/docs/ko/cli/remove-policies.mdx index 08422090..419ebc01 100644 --- a/docs/ko/cli/remove-policies.mdx +++ b/docs/ko/cli/remove-policies.mdx @@ -14,17 +14,17 @@ Claude Code의 `settings.json`에서 failproofai 훅 항목을 제거합니다. ## 옵션 | 플래그 | 설명 | -|--------|------| +|------|-------------| | `--scope user` | 전역 설정에서 제거 (기본값) | | `--scope project` | 프로젝트 설정에서 제거 | | `--scope local` | 로컬 설정에서 제거 | | `--scope all` | 모든 범위에서 한 번에 제거 | -| `--custom` / `-c` | 설정에서 `customPoliciesPath` 삭제 | +| `--custom` / `-c` | 설정에서 `customPoliciesPath` 초기화 | ## 동작 방식 -- **정책 이름 미지정** - 설정 파일에서 모든 failproofai 훅 항목을 제거합니다 -- **특정 이름 지정** - 해당 정책을 비활성화하되 훅은 설치된 상태로 유지합니다 +- **정책 이름 미지정** - 설정 파일에서 failproofai 훅 항목을 모두 제거 +- **특정 이름 지정** - 해당 정책을 비활성화하되 훅은 설치된 상태로 유지 ## 예시 @@ -38,6 +38,6 @@ failproofai policies --uninstall block-sudo # 모든 범위에서 훅 제거 failproofai policies --uninstall --scope all -# 커스텀 정책 경로 삭제 +# 커스텀 정책 경로 초기화 failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/ko/configuration.mdx b/docs/ko/configuration.mdx index 232b88e6..c90507f9 100644 --- a/docs/ko/configuration.mdx +++ b/docs/ko/configuration.mdx @@ -1,28 +1,28 @@ --- -title: 구성 -description: "설정 파일 형식, 세 가지 범위 시스템, 병합 규칙" +title: 설정 +description: "설정 파일 형식, 세 가지 범위 시스템, 그리고 병합 규칙" icon: gear --- -failproofai는 JSON 설정 파일을 사용하여 어떤 정책이 활성화되는지, 동작 방식, 그리고 커스텀 정책을 어디서 로드하는지를 제어합니다. 설정은 팀과 쉽게 공유할 수 있도록 설계되어 있습니다 — 저장소에 커밋하면 모든 개발자가 동일한 에이전트 안전망을 사용할 수 있습니다. +failproofai는 JSON 설정 파일을 사용하여 어떤 정책이 활성화되어 있는지, 정책이 어떻게 동작하는지, 그리고 커스텀 정책을 어디에서 불러올지를 제어합니다. 설정은 팀과 쉽게 공유할 수 있도록 설계되어 있습니다. 저장소에 커밋하면 모든 개발자가 동일한 에이전트 안전망을 갖게 됩니다. --- ## 설정 범위 -우선순위 순서대로 평가되는 세 가지 설정 범위가 있습니다: +설정 범위는 세 가지이며, 우선순위 순서대로 평가됩니다: | 범위 | 파일 경로 | 용도 | |------|-----------|------| -| **project** | `.failproofai/policies-config.json` | 버전 관리에 커밋되는 저장소별 설정 | -| **local** | `.failproofai/policies-config.local.json` | gitignore 처리되는 개인 저장소별 재정의 | +| **project** | `.failproofai/policies-config.json` | 저장소별 설정, 버전 관리에 커밋 | +| **local** | `.failproofai/policies-config.local.json` | 개인 저장소별 오버라이드, gitignore 처리 | | **global** | `~/.failproofai/policies-config.json` | 모든 프로젝트에 적용되는 사용자 수준 기본값 | -failproofai가 훅 이벤트를 받으면 현재 작업 디렉토리에 존재하는 세 파일을 모두 로드하고 병합합니다. +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,12 @@ 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`** — 처음 정의한 범위가 우선권을 가집니다. +**`customPoliciesPath`** - 이를 정의한 첫 번째 범위가 우선합니다. -**`llm`** — 처음 정의한 범위가 우선권을 가집니다. +**`llm`** - 이를 정의한 첫 번째 범위가 우선합니다. --- @@ -96,33 +96,33 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global까지 전달 --- -## 필드 참조 +## 필드 레퍼런스 ### `enabledPolicies` 타입: `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`를 전혀 설정하지 않은 사용자는 이전 버전과 동일하게 동작합니다. -정책 파라미터 블록 내의 알 수 없는 키는 훅 실행 시 조용히 무시되지만, `failproofai policies`를 실행하면 경고로 표시됩니다. +정책 파라미터 블록 내의 알 수 없는 키는 훅 실행 시 무시되지만, `failproofai policies` 실행 시 경고로 표시됩니다. -#### `hint` (공통 옵션) +#### `hint` (공통 설정) 타입: `string` (선택 사항) -정책이 `deny` 또는 `instruct`를 반환할 때 이유에 추가되는 메시지입니다. 정책 자체를 수정하지 않고도 Claude에게 실행 가능한 지침을 제공하는 데 사용합니다. +정책이 `deny` 또는 `instruct`를 반환할 때 reason에 추가되는 메시지입니다. 정책 자체를 수정하지 않고도 Claude에게 실행 가능한 안내를 제공할 때 사용합니다. -기본 제공, 커스텀(`custom/`), 프로젝트 규칙(`.failproofai-project/`), 사용자 규칙(`.failproofai-user/`) 등 모든 정책 유형에서 사용할 수 있습니다. +기본 제공, 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 등 모든 정책 유형에서 사용할 수 있습니다. ```json { @@ -141,32 +141,32 @@ 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)을 참고하세요. @@ -187,21 +187,22 @@ AI 호출을 수행하는 정책을 위한 LLM 클라이언트 설정입니다. --- -## CLI에서 설정 관리 +## 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` 마커가 있습니다. Copilot CLI 지원은 `events.jsonl` 레코드 스키마(공개 문서에 명시되지 않음)를 더 많은 실제 세션에서 검증하는 동안 **베타** 상태입니다. - - **Cursor Agent _(베타)_**: `~/.cursor/hooks.json` (사용자), `/.cursor/hooks.json` (프로젝트) — Cursor에는 `local` 범위가 없습니다. 훅 항목은 Claude 형식의 `{type, command, timeout}` 형태를 사용하지만, Cursor의 [hooks 스키마](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 응답을 플러그인 시맨틱으로 변환하는 소형 생성 플러그인 심(shim)을 생성합니다: 도구 이벤트 deny에는 `throw new Error()` (도구 호출 취소), instruct 및 `Stop`/`SubagentStop` deny에는 `client.session.prompt(...)` (deny 이유를 다음 사용자 메시지로 제출 — `session.idle`은 알림 전용이고 throw는 무작동이므로 이 채널이 유일한 강제 재시도 채널), allow에는 무작동. 심은 도구 이름(소문자 → `OPENCODE_TOOL_MAP`을 통한 PascalCase)과 도구 입력 인수 키(`Read`/`Write`/`Edit`에 대해 `OPENCODE_TOOL_INPUT_MAP`을 통한 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와 세션 로그 레이아웃이 안정화되는 동안 **베타** 상태입니다. - - **Gemini CLI _(베타)_**: `~/.gemini/settings.json` (사용자), `/.gemini/settings.json` (프로젝트) — Gemini에는 `local` 범위가 없습니다 (failproofai가 노출하지 않는 `/etc/gemini-cli/settings.json`의 `system` 범위를 문서화하고 있습니다). 훅 항목은 기본적으로 `matcher: "*"`를 사용하는 Gemini의 `{matcher, hooks: [...]}` 매처 스키마로 래핑된 Claude의 `{type, command, timeout}` 형태를 사용합니다. 이벤트는 PascalCase(`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`)이며, 핸들러는 `GEMINI_EVENT_MAP`을 통해 Claude 표준 이름으로 매핑합니다. 도구 이름은 snake_case(`run_shell_command`, `read_file`, `write_file`, `replace`, …)이며, 핸들러는 `GEMINI_TOOL_MAP`을 통해 정규화하므로 기존 기본 정책이 변경 없이 실행됩니다. 정책 평가기는 Gemini의 플랫 `{decision: "deny", reason}` 형태 (Gemini의 "Golden Rule" exit-0 계약에 따른 선호 형식), BeforeAgent/AfterTool/SessionStart에서의 컨텍스트 주입을 위한 `{hookSpecificOutput: {hookEventName, additionalContext}}`, 그리고 강제 재시도 시맨틱을 위한 AfterAgent의 `{decision: "block", reason}`을 반환합니다. Gemini CLI 지원은 실제 환경 커버리지를 넓히는 동안 **베타** 상태입니다. [Gemini CLI 훅 문서](https://geminicli.com/docs/hooks/)를 참고하세요. -- **`policies-config.json`** — failproofai에게 어떤 정책을 평가할지, 어떤 파라미터로 평가할지 알려줍니다 (모든 에이전트 CLI에서 공유) + - **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 지원은 **베타** 상태입니다. + - **Gemini CLI _(베타)_**: `~/.gemini/settings.json` (사용자), `/.gemini/settings.json` (프로젝트) — Gemini에는 `local` 범위가 없습니다(failproofai가 노출하지 않는 `/etc/gemini-cli/settings.json`의 `system` 범위가 문서에 있습니다). 훅 항목은 Claude의 `{type, command, timeout}` 형식을 Gemini의 `{matcher, hooks: [...]}` 매처 스키마로 감싸며 기본적으로 `matcher: "*"`를 사용합니다. 이벤트는 PascalCase입니다(`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`). 핸들러는 `GEMINI_EVENT_MAP`을 통해 Claude 표준 이름으로 매핑합니다. 도구 이름은 snake_case입니다(`run_shell_command`, `read_file`, `write_file`, `replace` 등) — 핸들러는 `GEMINI_TOOL_MAP`을 통해 정규화하므로 기존 기본 제공 정책이 변경 없이 동작합니다. 정책 평가기는 Gemini의 플랫 `{decision: "deny", reason}` 형식(Gemini의 "Golden Rule" exit-0 계약에 따른 선호 형식), BeforeAgent/AfterTool/SessionStart의 컨텍스트 주입을 위한 `{hookSpecificOutput: {hookEventName, additionalContext}}`, 그리고 강제 재시도 시맨틱을 위한 AfterAgent의 `{decision: "block", reason}`을 반환합니다. 실제 적용 범위를 넓히는 동안 Gemini CLI 지원은 **베타** 상태입니다. [Gemini CLI 훅 문서](https://geminicli.com/docs/hooks/)를 참고하세요. + - **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|gemini`를 전달하세요 (공백으로 구분하거나 반복 사용으로 부분 집합 선택): +특정 에이전트를 대상으로 하려면 `--cli claude|codex|copilot|cursor|opencode|pi|gemini|hermes`를 전달하세요(여러 개는 공백으로 구분하거나 반복 사용): ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +211,24 @@ 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 gemini --scope project +failproofai policies --install --cli hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` -`--cli`를 생략하면 failproofai는 설치된 에이전트 CLI를 자동 감지합니다 (`which claude`/`which codex`/`which copilot`/`which cursor-agent`/`which opencode`/`which pi`/`which gemini`): +`--cli`를 생략하면 `failproofai`가 설치된 에이전트 CLI를 자동으로 감지합니다(`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini` / `which hermes`): -- **하나의 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에 설치합니다. -- **감지된 CLI 없음** — PATH에서 에이전트 바이너리를 찾을 수 없다는 경고와 함께 `claude`로 폴백합니다. 훅 명령은 여전히 작성되므로 에이전트를 설치하는 즉시 활성화됩니다. +- **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에서 에이전트 바이너리를 찾을 수 없다는 경고를 표시합니다. 훅 명령은 그래도 기록되므로 설치 즉시 활성화됩니다. -`policies-config.json`은 언제든지 직접 편집할 수 있으며, 다음 훅 이벤트에서 즉시 적용됩니다 — 재시작이 필요 없습니다. +`policies-config.json`은 언제든지 직접 편집할 수 있으며, 변경 사항은 재시작 없이 다음 훅 이벤트부터 즉시 적용됩니다. --- ## 예시: 팀 기본값이 포함된 프로젝트 수준 설정 -저장소에 `.failproofai/policies-config.json`을 커밋하세요: +`.failproofai/policies-config.json`을 저장소에 커밋하세요: ```json { @@ -245,4 +247,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi gem } ``` -각 개발자는 팀원에게 영향을 주지 않고 개인 재정의를 위해 `.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 f556f973..f481abbe 100644 --- a/docs/ko/custom-policies.mdx +++ b/docs/ko/custom-policies.mdx @@ -1,10 +1,10 @@ --- title: 커스텀 정책 -description: "JavaScript로 직접 정책을 작성하세요 - 컨벤션 적용, 드리프트 방지, 실패 감지, 외부 시스템 연동 등" +description: "JavaScript로 직접 정책을 작성하세요 - 컨벤션 적용, 드리프트 방지, 실패 감지, 외부 시스템 연동" icon: code --- -커스텀 정책을 사용하면 에이전트의 모든 동작에 대한 규칙을 직접 작성할 수 있습니다. 프로젝트 컨벤션 적용, 드리프트 방지, 위험한 작업 차단, 응답 없는 에이전트 감지, Slack 연동, 승인 워크플로우 등을 구현할 수 있습니다. 내장 정책과 동일한 훅 이벤트 시스템과 `allow`, `deny`, `instruct` 결정 방식을 사용합니다. +커스텀 정책을 사용하면 에이전트 동작에 관한 규칙을 직접 작성할 수 있습니다. 프로젝트 컨벤션 적용, 드리프트 방지, 위험 작업 차단, 멈춘 에이전트 감지, Slack이나 승인 워크플로 연동 등 다양하게 활용할 수 있습니다. 내장 정책과 동일한 훅 이벤트 시스템과 `allow`, `deny`, `instruct` 결정 방식을 사용합니다. --- @@ -37,30 +37,30 @@ failproofai policies --install --custom ./my-policies.js --- -## 커스텀 정책을 로드하는 두 가지 방법 +## 커스텀 정책을 불러오는 두 가지 방법 ### 방법 1: 컨벤션 기반 (권장) -`*policies.{js,mjs,ts}` 파일을 `.failproofai/policies/` 디렉토리에 넣으면 별도의 플래그나 설정 변경 없이 자동으로 로드됩니다. git 훅처럼 파일만 넣으면 바로 동작합니다. +`.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: 명시적 파일 경로 @@ -76,11 +76,11 @@ failproofai policies --install --custom ./new-policies.js failproofai policies --uninstall --custom ``` -변환된 절대 경로는 `policies-config.json`의 `customPoliciesPath`에 저장됩니다. 파일은 매 훅 이벤트마다 새로 로드되며, 이벤트 간 캐싱은 없습니다. +변환된 절대 경로는 `policies-config.json`의 `customPoliciesPath`에 저장됩니다. 파일은 매 훅 이벤트마다 새로 불러오며 이벤트 간 캐싱은 없습니다. ### 두 방법을 함께 사용하기 -컨벤션 정책과 명시적 `--custom` 파일은 함께 사용할 수 있습니다. 로드 순서: +컨벤션 정책과 명시적 `--custom` 파일은 공존할 수 있습니다. 불러오는 순서: 1. 명시적 `customPoliciesPath` 파일 (설정된 경우) 2. 프로젝트 컨벤션 파일 (`{cwd}/.failproofai/policies/`, 알파벳 순) @@ -90,7 +90,7 @@ failproofai policies --uninstall --custom ## API -### 임포트 +### 가져오기 ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -98,13 +98,13 @@ 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; }); ``` @@ -112,31 +112,31 @@ customPolicies.add({ ### 결정 헬퍼 함수 | 함수 | 효과 | 사용 시점 | -|------|------|-----------| -| `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` 메시지는 누적되어 함께 전달됩니다. -`deny` 또는 `instruct` 메시지에 추가 가이던스를 덧붙이려면 `policyParams`의 `hint` 필드를 사용하세요 — 코드 변경이 필요 없습니다. 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 정책 모두에서 동작합니다. 자세한 내용은 [설정 → hint](/ko/configuration#hint-cross-cutting)를 참고하세요. +`policyParams`의 `hint` 필드를 추가하면 코드 변경 없이 `deny`나 `instruct` 메시지에 추가 안내를 붙일 수 있습니다. 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 정책 모두에서 동작합니다. 자세한 내용은 [설정 → 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 +146,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."); } @@ -158,28 +158,28 @@ 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로부터 받은 원시 이벤트 페이로드 전체 | +| `payload` | `Record` | Claude Code에서 전달된 전체 원시 이벤트 페이로드 | | `session` | `SessionMetadata \| undefined` | 세션 컨텍스트 (아래 참조) | ### `SessionMetadata` 필드 | 필드 | 타입 | 설명 | -|------|------|------| +|-------|------|-------------| | `sessionId` | `string` | Claude Code 세션 식별자 | -| `cwd` | `string` | Claude Code 세션의 작업 디렉토리 | +| `cwd` | `string` | Claude Code 세션의 작업 디렉터리 | | `transcriptPath` | `string` | 세션의 JSONL 트랜스크립트 파일 경로 | ### 이벤트 타입 | 이벤트 | 발생 시점 | `toolInput` 내용 | -|--------|-----------|-----------------| -| `PreToolUse` | Claude가 도구를 실행하기 전 | 도구의 입력값 (예: Bash의 경우 `{ command: "..." }`) | -| `PostToolUse` | 도구 실행 완료 후 | 도구의 입력값 + `tool_result` (출력값) | -| `Notification` | Claude가 알림을 보낼 때 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - 훅은 반드시 `allow()`를 반환해야 하며, 알림을 차단할 수 없음 | +|-------|--------------|----------------------| +| `PreToolUse` | Claude가 도구를 실행하기 전 | 도구의 입력 (예: Bash의 경우 `{ command: "..." }`) | +| `PostToolUse` | 도구 실행 완료 후 | 도구의 입력 + `tool_result` (출력) | +| `Notification` | Claude가 알림을 보낼 때 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - 훅은 항상 `allow()`를 반환해야 하며 알림을 차단할 수 없습니다 | | `Stop` | Claude 세션이 종료될 때 | 비어 있음 | --- @@ -190,11 +190,11 @@ 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` 메시지는 누적되어 함께 전달됩니다. --- @@ -218,43 +218,43 @@ customPolicies.add({ }); ``` -엔트리 파일에서 도달 가능한 모든 상대 임포트가 처리됩니다. `from "failproofai"` 임포트를 실제 dist 경로로 재작성하고 임시 `.mjs` 파일을 생성하여 ESM 호환성을 보장하는 방식으로 구현되어 있습니다. +엔트리 파일에서 도달 가능한 모든 상대 임포트가 처리됩니다. 내부적으로 `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** 방식입니다. 오류가 발생해도 내장 정책을 차단하거나 훅 핸들러를 중단시키지 않습니다. | 실패 상황 | 동작 | -|-----------|------| +|---------|----------| | `customPoliciesPath` 미설정 | 명시적 커스텀 정책이 실행되지 않음; 컨벤션 정책과 내장 정책은 정상 동작 | | 파일을 찾을 수 없음 | `~/.failproofai/hook.log`에 경고 기록; 내장 정책은 계속 실행 | | 문법/임포트 오류 (명시적) | `~/.failproofai/hook.log`에 오류 기록; 명시적 커스텀 정책 건너뜀 | -| 문법/임포트 오류 (컨벤션) | 오류 기록; 해당 파일 건너뜀, 다른 컨벤션 파일은 계속 로드 | -| `fn` 런타임 오류 | 오류 기록; 해당 훅은 `allow`로 처리; 다른 훅은 계속 실행 | -| `fn` 10초 초과 | 타임아웃 기록; `allow`로 처리 | -| 컨벤션 디렉토리 없음 | 컨벤션 정책이 실행되지 않음; 오류 없음 | +| 문법/임포트 오류 (컨벤션) | 오류 기록; 해당 파일 건너뜀, 다른 컨벤션 파일은 계속 불러옴 | +| 런타임에서 `fn` 예외 발생 | 오류 기록; 해당 훅은 `allow`로 처리; 다른 훅은 계속 실행 | +| `fn`이 10초 이상 소요 | 타임아웃 기록; `allow`로 처리 | +| 컨벤션 디렉터리 없음 | 컨벤션 정책 실행 없음; 오류 없음 | 커스텀 정책 오류를 디버깅하려면 로그 파일을 실시간으로 확인하세요: @@ -266,13 +266,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 +285,7 @@ customPolicies.add({ }, }); -// 에이전트가 올바른 방향 유지: 커밋 전 테스트 검증 +// 에이전트가 커밋 전에 테스트를 확인하도록 안내 customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +300,7 @@ customPolicies.add({ }, }); -// 프리즈 기간 중 계획되지 않은 의존성 변경 방지 +// 동결 기간 중 계획되지 않은 의존성 변경 방지 customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -323,14 +323,14 @@ export { customPolicies }; ## 예시 파일 -`examples/` 디렉토리에는 바로 실행 가능한 정책 파일이 포함되어 있습니다: +`examples/` 디렉터리에는 바로 실행 가능한 정책 파일들이 포함되어 있습니다: | 파일 | 내용 | -|------|------| +|------|----------| | `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/workflow-policies.mjs` | 컨벤션 기반 워크플로 정책 (테스트 알림, 파일 쓰기 감사) | ### 명시적 파일 예시 사용 @@ -350,4 +350,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/ko/dashboard.mdx b/docs/ko/dashboard.mdx index a7e0b319..eaa09fbc 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`에서 열립니다. -대시보드는 파일 시스템에서 직접 읽습니다 — Claude Code 프로젝트 폴더와 failproofai 설정 파일을 참조합니다. 원격 서비스에는 아무것도 기록되지 않습니다. +대시보드는 파일 시스템에서 직접 데이터를 읽습니다 — Claude Code 프로젝트 폴더와 failproofai 설정 파일에서 읽어오며, 원격 서비스에는 아무것도 기록되지 않습니다. --- @@ -24,22 +24,22 @@ failproofai ### 프로젝트 -머신에서 발견된 모든 Claude Code, OpenAI Codex, GitHub Copilot CLI _(베타)_, Cursor Agent _(베타)_, OpenCode _(베타)_, Pi _(베타)_, Gemini CLI _(베타)_ 프로젝트를 나열합니다. 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//`(폴백으로 `conversations/` 및 `sessions/`를 탐색하며 `CURSOR_HOME`으로 설정 가능) 아래의 세션별 메타데이터를 스캔하여 `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`를 가져와 검색됩니다. Gemini CLI 프로젝트는 `~/.gemini/tmp//chats/session--.jsonl`(`GEMINI_SESSIONS_DIR`로 설정 가능)을 스캔하고 인접한 `.project_root` 텍스트 마커에서 정규 cwd를 복원하여 검색됩니다. 여러 CLI에서 사용된 프로젝트는 일치하는 모든 배지와 함께 단일 행으로 표시됩니다. 테이블 위의 **CLI** 드롭다운을 사용하여 특정 에이전트 CLI로 필터링할 수 있으며, URL은 선택 항목을 `?cli=claude|codex|copilot|cursor|opencode|pi|gemini`로 보존합니다. +머신에서 발견된 모든 Claude Code, OpenAI Codex, GitHub Copilot CLI _(베타)_, Cursor Agent _(베타)_, OpenCode _(베타)_, Pi _(베타)_, Gemini CLI _(베타)_, Hermes 프로젝트를 나열합니다. 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`를 가져와 검색됩니다. Gemini CLI 프로젝트는 `~/.gemini/tmp//chats/session--.jsonl`(`GEMINI_SESSIONS_DIR`으로 구성 가능)을 스캔하고 인접한 `.project_root` 텍스트 마커에서 정규 cwd를 복원하여 검색됩니다. Hermes 게이트웨이 세션은 `~/.hermes/state.db`(`HERMES_DB_PATH`으로 구성 가능)의 SQLite 저장소에서 직접 읽어오며 `source`(Slack/Telegram/cli/cron — 게이트웨이 세션에는 cwd가 없음)로 `hermes-` 프로젝트로 그룹화됩니다. 여러 CLI에서 사용된 프로젝트는 일치하는 모든 배지가 있는 단일 행으로 표시됩니다. 테이블 위의 **CLI** 드롭다운을 사용하여 특정 에이전트 CLI로 필터링하세요. URL은 선택 내용을 `?cli=claude|codex|copilot|cursor|opencode|pi|gemini|hermes`로 보존합니다. 각 프로젝트에는 다음이 표시됩니다: - 프로젝트 이름 (폴더 경로에서 파생) -- CLI 배지 — `Claude Code` (주황색), `OpenAI Codex` (보라색), `GitHub Copilot` (파란색), `Cursor Agent` (에메랄드), `OpenCode` (황갈색), `Pi` (분홍색), 그리고/또는 `Gemini CLI` (하늘색) +- CLI 배지 — `Claude Code` (주황색), `OpenAI Codex` (보라색), `GitHub Copilot` (파란색), `Cursor Agent` (에메랄드), `OpenCode` (호박색), `Pi` (분홍색), `Gemini CLI` (하늘색), 및/또는 `Hermes` (남색) - 가장 최근 세션 활동 날짜 -프로젝트를 클릭하면 해당 세션을 확인할 수 있습니다. +프로젝트를 클릭하면 해당 세션이 표시됩니다. ### 세션 -프로젝트 내의 모든 세션을 나열합니다. 각 세션에는 다음이 표시됩니다: +프로젝트 내 모든 세션을 나열합니다. 각 세션에는 다음이 표시됩니다: - 세션 ID - 시작 및 종료 타임스탬프 -- 도구 호출 수 -- 훅 활동 횟수 (실행된 정책) +- 툴 호출 수 +- 훅 활동 수 (실행된 정책) 날짜 범위 필터와 세션 ID 검색을 사용하여 목록을 좁힐 수 있습니다. 세션은 페이지로 나뉩니다. @@ -47,44 +47,44 @@ failproofai ### 세션 뷰어 -세션 뷰어는 자율 에이전트에 대한 핵심 질문에 답합니다: 에이전트가 무엇을 했고, 올바른 방향을 유지했는가? 헤더 옆의 CLI 배지는 세션이 Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, 또는 Gemini CLI 트랜스크립트인지를 나타냅니다. 세션에서 발생한 모든 일의 타임라인이 표시됩니다: +세션 뷰어는 자율 에이전트에 대한 핵심 질문에 답합니다: 에이전트가 무엇을 했으며, 제대로 작동했는가? 헤더 옆의 CLI 배지는 세션이 Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Gemini CLI 또는 Hermes 트랜스크립트인지 나타냅니다. 세션에서 발생한 모든 일의 타임라인을 보여줍니다: -- **메시지** - Claude의 텍스트 응답 및 사용자 프롬프트 -- **도구 호출** - Claude가 호출한 모든 도구, 입력 및 출력 포함 -- **정책 활동** - 각 도구 호출에 대해 어떤 정책이 실행되었고 어떤 결정을 반환했는지 +- **메시지** - Claude의 텍스트 응답과 사용자 프롬프트 +- **툴 호출** - Claude가 호출한 모든 툴, 입력 및 출력 포함 +- **정책 활동** - 각 툴 호출에 대해 어떤 정책이 실행되었고 어떤 결정을 내렸는지 -상단의 통계 바는 세션 지속 시간, 총 도구 호출 수, 훅 결정 요약 (allow / deny / instruct 횟수)을 표시합니다. +상단의 통계 바에는 세션 지속 시간, 총 툴 호출 수, 훅 결정 요약(allow / deny / instruct 수)이 표시됩니다. -**로그 다운로드** 버튼을 클릭하면 세션을 내보낼 수 있습니다. Claude Code, Codex, Copilot, Cursor, Pi, Gemini 세션의 경우 디스크에 저장된 원본 JSONL 트랜스크립트를 바이트 단위로 그대로 받을 수 있으며, OpenCode(세션이 디스크가 아닌 SQLite에 저장됨)의 경우 기본 `session` / `messages` / `parts` 테이블을 반영하는 JSON 문서를 받게 됩니다. +**로그 다운로드** 버튼을 클릭하여 세션을 내보냅니다. Claude Code, Codex, Copilot, Cursor, Pi, Gemini 세션의 경우 디스크의 원본 JSONL 트랜스크립트를 바이트 단위로 그대로 받을 수 있으며, OpenCode(세션이 디스크가 아닌 SQLite에 저장됨)의 경우 기본 `session` / `messages` / `parts` 테이블을 미러링하는 JSON 문서를 받습니다. ### 감사 -과거 세션 전반에 걸쳐 에이전트가 실제로 어떻게 행동했는지에 대한 개성 있는 보고서입니다. `failproofai audit` CLI와 동일한 스캔을 실행하지만 단일 화면 공유 가능한 포스터 + 화면 아래의 네 섹션으로 렌더링됩니다: +과거 세션에서 에이전트가 실제로 어떻게 동작했는지에 대한 개성 있는 보고서입니다. `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 캡처 영역. 캡처 박스 바로 바깥에 세 개의 공유 버튼이 있습니다: `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-server의 `POST /v0/invite`로 전달됩니다. api-server는 수신자에게 `invite@failproof.ai`에서 발신자를 Cc에 포함하고 `Reply-To`를 설정하여 이메일을 전송하므로 수신자는 누가 초대했는지 알 수 있고 발신자는 받은 편지함에 사본을 받습니다. 익명 사용자는 초대가 발송되기 전에 발신자의 이메일을 알 수 있도록 먼저 `AuthDialog`로 라우팅됩니다. 권한/혜택 이행은 후속 작업입니다. +1. **포스터** — 첫 번째 뷰포트를 채웁니다. failproof_ai 워드마크 + 감사 레이블 · 아키타입 인덱스(`№ NN of 08`) + 감사 날짜 · 수치 점수(0–100) + 백분위 순위 pill(`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. **강점** — 에이전트가 이미 올바르게 수행하는 동작의 ✓ 행 목록으로, 라이브 감사 데이터(깔끔한 툴 호출 비율, main으로의 직접 푸시 없음, 자격 증명 누출 없음, 재시도 폭풍 없음)에서 도출됩니다 — 관련 정책이 감사 기간 동안 깨끗한 기록을 가진 경우에만 표시됩니다. +3. **문제점** — 심각도 순으로 정렬된 문제 테이블: `발생 시점 · 발생한 문제 + 이를 감지했을 정책 · 심각도 pill · 발생 횟수`, 재발 횟수는 `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`에서 수신자별로 이메일을 발송하며, 발신자가 참조(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` 런타임으로 구동됩니다 — 기본 스캔 엔진, 지원되는 플래그, 트랜스크립트별 캐시 불변성은 [감사 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가 보호하는 에이전트 CLI를 다중 선택합니다 — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Gemini CLI 모두 설치 상태 (`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, Gemini CLI, 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 _(베타)_ / Gemini CLI _(베타)_), 정책 이름 또는 세션 ID로 필터링 - - 각 행에는 타임스탬프, 정책 이름, 결정, CLI 배지 (주황색 = Claude Code, 보라색 = OpenAI Codex, 파란색 = GitHub Copilot, 에메랄드 = Cursor Agent, 황갈색 = OpenCode, 분홍색 = Pi, 하늘색 = Gemini CLI), 도구 이름, 세션 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`)하고 헤더에 일치하는 CLI 배지를 렌더링합니다 + - 모든 세션에서 실행된 모든 훅 이벤트의 전체 페이지네이션 기록 + - 결정, 이벤트 유형, CLI(Claude Code / OpenAI Codex / GitHub Copilot _(베타)_ / Cursor Agent _(베타)_ / OpenCode _(베타)_ / Pi _(베타)_ / Gemini CLI _(베타)_ / Hermes), 정책 이름 또는 세션 ID로 필터링 + - 각 행에는 타임스탬프, 정책 이름, 결정, CLI 배지(주황색 = Claude Code, 보라색 = OpenAI Codex, 파란색 = GitHub Copilot, 에메랄드 = Cursor Agent, 호박색 = OpenCode, 분홍색 = Pi, 하늘색 = Gemini CLI, 남색 = Hermes), 툴 이름, 세션 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`, Hermes `~/.hermes/state.db`)를 자동으로 감지하고 헤더에 일치하는 CLI 배지를 렌더링합니다 @@ -92,13 +92,13 @@ failproofai ## 자동 새로고침 -대시보드 상단 탐색에 자동 새로고침 토글이 있습니다. 활성화되면 현재 페이지가 주기적으로 새로고침되어 새 세션과 정책 활동이 나타나는 대로 표시됩니다. 장시간 실행되는 자율 에이전트 세션을 모니터링할 때 필수적입니다. +대시보드 상단 탐색에는 자동 새로고침 토글이 있습니다. 활성화하면 현재 페이지가 주기적으로 새로고침되어 새로운 세션과 정책 활동이 나타날 때 표시됩니다. 장시간 실행되는 자율 에이전트 세션을 모니터링하는 데 필수적입니다. --- ## 페이지 비활성화 -대시보드의 일부만 필요한 경우, `FAILPROOFAI_DISABLE_PAGES`를 쉼표로 구분된 페이지 이름 목록으로 설정하세요: +대시보드의 일부 기능만 필요한 경우 `FAILPROOFAI_DISABLE_PAGES`를 쉼표로 구분된 페이지 이름 목록으로 설정하세요: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -110,7 +110,7 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## 프로젝트 경로 구성 -기본적으로 대시보드는 표준 Claude Code 프로젝트 디렉터리에서 읽습니다. 사용자 정의 설정을 위해 재정의하세요: +기본적으로 대시보드는 표준 Claude Code 프로젝트 디렉토리에서 읽습니다. 사용자 정의 설정의 경우 재정의하세요: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,19 +120,19 @@ 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 @@ -145,5 +145,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/ko/examples.mdx b/docs/ko/examples.mdx index 76f0a368..1f48f1b9 100644 --- a/docs/ko/examples.mdx +++ b/docs/ko/examples.mdx @@ -1,16 +1,16 @@ --- -title: 예시 +title: 예제 description: "Claude Code 및 Agents SDK에 훅을 설정하는 방법" icon: book-open --- -일반적인 시나리오에 바로 사용할 수 있는 예시들입니다. 각 예시는 설치 방법과 기대 동작을 보여줍니다. +일반적인 시나리오에 바로 사용할 수 있는 예제들입니다. 각 예제는 설치 방법과 예상 동작을 보여줍니다. --- ## Claude Code에 훅 설정하기 -Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/docs/claude-code/hooks)을 통해 통합됩니다. `failproofai policies --install`을 실행하면 매 도구 호출 시 동작하는 훅 명령어가 Claude Code의 `settings.json`에 등록됩니다. +Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/docs/claude-code/hooks)을 통해 통합됩니다. `failproofai policies --install`을 실행하면 모든 도구 호출 시 실행되는 훅 명령어가 Claude Code의 `settings.json`에 등록됩니다. @@ -35,7 +35,7 @@ Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/doc claude ``` - 이제 모든 도구 호출 시 정책이 자동으로 실행됩니다. Claude에게 `sudo rm -rf /`를 실행해 보라고 요청해 보세요 — 차단됩니다. + 이제 모든 도구 호출 시 정책이 자동으로 실행됩니다. Claude에게 `sudo rm -rf /` 실행을 요청해 보세요 - 차단될 것입니다. @@ -43,7 +43,7 @@ Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/doc ## Agents SDK에 훅 설정하기 -[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk)로 개발하는 경우, 동일한 훅 시스템을 프로그래밍 방식으로 활용할 수 있습니다. +[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk)로 개발 중이라면 동일한 훅 시스템을 프로그래밍 방식으로 사용할 수 있습니다. @@ -52,7 +52,7 @@ Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/doc ``` - 에이전트 프로세스를 생성할 때 훅 명령어를 전달합니다. Claude Code와 동일한 방식으로 stdin/stdout JSON을 통해 훅이 실행됩니다: + 에이전트 프로세스 생성 시 훅 명령어를 전달합니다. 훅은 Claude Code와 동일하게 stdin/stdout JSON 방식으로 실행됩니다: ```bash failproofai --hook PreToolUse # called before each tool @@ -86,35 +86,35 @@ Failproof AI는 Claude Code의 [훅 시스템](https://docs.anthropic.com/en/doc --- -## 파괴적인 명령어 차단 +## 파괴적인 명령 차단 -가장 일반적인 설정 — 에이전트가 되돌릴 수 없는 작업을 수행하지 못하도록 방지합니다. +가장 일반적인 설정 - 에이전트가 되돌릴 수 없는 손상을 일으키는 것을 방지합니다. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` -각 정책의 역할: -- `block-sudo` - 모든 `sudo` 명령어 차단 +이 설정의 기능: +- `block-sudo` - 모든 `sudo` 명령 차단 - `block-rm-rf` - 재귀적 파일 삭제 차단 - `block-force-push` - `git push --force` 차단 -- `block-curl-pipe-sh` - 원격 스크립트를 셸로 파이프하는 것 차단 +- `block-curl-pipe-sh` - 원격 스크립트를 셸에 파이프하는 것 차단 --- ## 시크릿 유출 방지 -에이전트가 도구 출력에서 자격 증명을 보거나 유출하지 못하도록 차단합니다. +에이전트가 도구 출력에서 자격증명을 보거나 유출하는 것을 방지합니다. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -이 정책들은 `PostToolUse` 시점에 실행되며, 도구 실행 후 에이전트가 출력을 보기 전에 민감한 정보를 제거합니다. +이 정책들은 `PostToolUse` 시 실행됩니다 - 도구 실행 후 에이전트가 출력을 보기 전에 민감한 정보를 제거합니다. --- -## 에이전트 대기 시 Slack 알림 받기 +## 에이전트가 주의가 필요할 때 Slack 알림 받기 알림 훅을 사용하여 유휴 알림을 Slack으로 전달합니다. @@ -158,9 +158,9 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c --- -## 에이전트를 특정 브랜치에 고정 +## 에이전트를 특정 브랜치에 고정하기 -에이전트가 브랜치를 전환하거나 보호된 브랜치에 푸시하지 못하도록 방지합니다. +에이전트가 브랜치를 전환하거나 보호된 브랜치에 푸시하는 것을 방지합니다. ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -184,7 +184,7 @@ customPolicies.add({ ## 커밋 전 테스트 실행 요구 -에이전트가 커밋 전에 테스트를 실행하도록 상기시킵니다. +에이전트에게 커밋 전 테스트를 실행하도록 상기시킵니다. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -208,9 +208,9 @@ customPolicies.add({ ## 프로덕션 저장소 잠금 -팀의 모든 개발자가 동일한 정책을 적용받을 수 있도록 프로젝트 수준 설정을 저장소에 커밋합니다. +프로젝트 레벨 설정을 커밋하여 팀의 모든 개발자가 동일한 정책을 적용받도록 합니다. -저장소에 `.failproofai/policies-config.json`을 생성합니다: +저장소에 `.failproofai/policies-config.json`을 생성하세요: ```json { @@ -231,7 +231,7 @@ customPolicies.add({ } ``` -그런 다음 커밋합니다: +커밋: ```bash git add .failproofai/policies-config.json @@ -242,9 +242,9 @@ failproofai가 설치된 모든 팀원이 이 규칙을 자동으로 적용받 --- -## 컨벤션 정책으로 조직 전체 품질 기준 수립 +## 컨벤션 정책으로 조직 전체 품질 기준 구축 -가장 효과적인 설정: 프로젝트에 맞게 조정된 정책을 `.failproofai/policies/`에 저장소에 커밋합니다. 설치 명령어나 설정 변경 없이 모든 팀원이 자동으로 적용받습니다. +가장 효과적인 설정: 프로젝트에 맞춘 정책이 담긴 `.failproofai/policies/`를 저장소에 커밋하세요. 별도의 설치 명령이나 설정 변경 없이 모든 팀원이 자동으로 정책을 적용받습니다. @@ -289,19 +289,19 @@ failproofai가 설치된 모든 팀원이 이 규칙을 자동으로 적용받 git commit -m "Add team quality policies" ``` - - 팀에서 새로운 문제 사례가 발생할 때마다 정책을 추가하고 푸시하세요. 모든 팀원이 다음 `git pull` 시 업데이트를 받게 됩니다. 이 정책들은 팀과 함께 성장하는 살아있는 품질 기준이 됩니다. + + 팀이 새로운 문제를 발견할 때마다 정책을 추가하고 푸시하세요. 모든 팀원이 다음 `git pull` 시 업데이트를 받게 됩니다. 이 정책들은 팀과 함께 성장하는 살아있는 품질 기준이 됩니다. --- -## 더 많은 예시 +## 더 많은 예제 저장소의 [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) 디렉토리에는 다음이 포함되어 있습니다: | 파일 | 내용 | -|------|------| -| `policies-basic.js` | 기본 정책 — 프로덕션 쓰기, 강제 푸시, 파이프 스크립트 차단 | -| `policies-notification.js` | 유휴 알림 및 세션 종료 시 Slack 알림 | -| `policies-advanced/index.js` | 전이적 임포트, 비동기 훅, PostToolUse 출력 제거, Stop 이벤트 처리 | \ No newline at end of file +|------|---------------| +| `policies-basic.js` | 기본 정책 - 프로덕션 쓰기, 강제 푸시, 파이프된 스크립트 차단 | +| `policies-notification.js` | 유휴 알림 및 세션 종료에 대한 Slack 알림 | +| `policies-advanced/index.js` | 전이적 임포트, 비동기 훅, PostToolUse 출력 스크러빙, Stop 이벤트 처리 | \ No newline at end of file diff --git a/docs/ko/for-agents.mdx b/docs/ko/for-agents.mdx index ef394058..77680a29 100644 --- a/docs/ko/for-agents.mdx +++ b/docs/ko/for-agents.mdx @@ -1,9 +1,9 @@ --- -title: "에이전트를 위한 가이드" -description: "단 하나의 명령어로 코딩 에이전트에 Failproof AI 지식을 추가하세요. Claude Code, Cursor, Windsurf 등과 호환됩니다." +title: "에이전트를 위한 안내" +description: "단 하나의 명령으로 코딩 에이전트에 Failproof AI 지식을 추가하세요. Claude Code, Cursor, Windsurf 등과 함께 작동합니다." --- -단 하나의 명령어로 코딩 에이전트에 Failproof AI 전체 레퍼런스를 추가하세요. Claude Code, Cursor, Windsurf, 그리고 스킬을 지원하는 모든 에이전트와 호환됩니다. +단 하나의 명령으로 코딩 에이전트에 전체 Failproof AI 레퍼런스를 추가하세요. Claude Code, Cursor, Windsurf 및 스킬을 지원하는 모든 에이전트와 호환됩니다. ```bash npx skills add https://docs.befailproof.ai @@ -13,26 +13,26 @@ npx skills add https://docs.befailproof.ai ## 스킬이 다루는 내용 -| 영역 | 포함 내용 | +| 영역 | 포함된 내용 | |------|----------------| -| Policies | 내장 정책 이름, 이벤트 유형, 파라미터, 활성화/비활성화 | -| Custom policies | `customPolicies.add()`, 매칭 필터, `allow`/`deny`/`instruct` API | +| Policies | 내장 정책 이름, 이벤트 타입, 파라미터, 활성화/비활성화 | +| Custom policies | `customPolicies.add()`, 매치 필터, `allow`/`deny`/`instruct` API | | Context object | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | | Configuration | `policies-config.json` 구조, 스코프 병합, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, 스코프 | | Dashboard | 세션 뷰어, 정책 활동, 환경 변수 | | Architecture | 훅 핸들러 흐름, 종료 코드, stdin/stdout 계약 | -## 스킬은 완전한가요? +## 스킬이 완전한가요? -Mintlify는 내비게이션의 모든 페이지로부터 `llms.txt`를 생성합니다. Failproof AI 문서는 전체 API를 다루며, 모든 정책, 옵션, 예제가 포함되어 있습니다. 누락된 내용이 있다면 `https://docs.befailproof.ai/llms-full.txt`에서 원본을 확인할 수 있습니다. +Mintlify는 내비게이션의 모든 페이지에서 `llms.txt`를 생성합니다. Failproof AI 문서는 전체 API를 포함하고 있으며, 모든 정책, 옵션, 예제가 담겨 있습니다. 누락된 내용을 발견하면 원본 소스를 `https://docs.befailproof.ai/llms-full.txt`에서 확인하세요. -특정 컨텍스트만 필요하다면 해당 페이지에 직접 연결하세요: +특정 컨텍스트만 필요하다면 특정 페이지로 직접 링크하세요: ```bash -# 커스텀 정책 API만 추가 +# Just the custom policies API npx skills add https://docs.befailproof.ai/custom-policies -# 내장 정책만 추가 +# Just the built-in policies npx skills add https://docs.befailproof.ai/built-in-policies ``` \ No newline at end of file diff --git a/docs/ko/getting-started.mdx b/docs/ko/getting-started.mdx index 86a38a43..6b7ff502 100644 --- a/docs/ko/getting-started.mdx +++ b/docs/ko/getting-started.mdx @@ -4,7 +4,7 @@ description: "failproofai를 설치하고, 정책을 활성화하여 에이전 icon: rocket --- -## 요구사항 +## 요구 사항 - **Node.js** >= 20.9.0 - **Bun** >= 1.3.0 (선택 사항 - 소스에서 빌드할 때만 필요) @@ -31,15 +31,15 @@ bun add -g failproofai - 정책은 에이전트의 모든 도구 호출 전후에 실행되는 규칙입니다. 파괴적인 명령, 비밀 정보 유출, 기타 장애 유형을 피해가 발생하기 전에 차단합니다. + 정책은 에이전트의 모든 도구 호출 전후에 실행되는 규칙입니다. 파괴적인 명령, 시크릿 유출, 그 외 여러 장애 상황을 피해가 발생하기 전에 차단합니다. ```bash failproofai policies --install ``` - 이 명령은 설치된 에이전트 CLI의 훅 항목을 작성합니다 (Claude Code의 `~/.claude/settings.json`, OpenAI Codex의 `~/.codex/hooks.json`, GitHub Copilot CLI의 `~/.copilot/hooks/failproofai.json`, Cursor Agent의 `~/.cursor/hooks.json`, OpenCode의 `~/.config/opencode/plugins/failproofai.mjs` 플러그인 심 및 `~/.config/opencode/opencode.json`의 `plugin` 배열 등록 항목, Pi의 `~/.pi/agent/settings.json`, Gemini CLI의 `~/.gemini/settings.json`). 하나 이상 설치되어 있는 경우 선택 메시지가 표시됩니다. `--cli claude codex copilot cursor opencode pi gemini` (임의의 조합)를 전달하면 메시지를 건너뜁니다. + 이 명령은 설치된 에이전트 CLI에 훅 항목을 기록합니다 (Claude Code의 `~/.claude/settings.json`, OpenAI Codex의 `~/.codex/hooks.json`, GitHub Copilot CLI의 `~/.copilot/hooks/failproofai.json`, Cursor Agent의 `~/.cursor/hooks.json`, OpenCode의 `~/.config/opencode/plugins/failproofai.mjs` 생성 플러그인 심 및 `~/.config/opencode/opencode.json`의 `plugin` 배열 등록 항목, Pi의 `~/.pi/agent/settings.json`, Gemini CLI의 `~/.gemini/settings.json`, Hermes의 `~/.hermes/config.yaml`). 둘 이상의 CLI가 설치되어 있으면 선택 프롬프트가 표시됩니다. `--cli claude codex copilot cursor opencode pi gemini hermes` (원하는 조합)를 전달하면 프롬프트를 건너뜁니다. - GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Gemini CLI 지원은 **베타** 단계입니다 — `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, `--cli gemini`로 설치하세요. + GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Gemini CLI 지원은 **베타** 단계입니다 — `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, 또는 `--cli gemini`로 설치하세요. Hermes (hermes-agent, Slack/Telegram 게이트웨이)는 `--cli hermes`로 사용자 범위에 설치되며 오프라인 감사 소스이기도 합니다. ```bash failproofai policies --install --scope project @@ -49,6 +49,7 @@ bun add -g failproofai failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project + failproofai policies --install --cli hermes --scope user failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` @@ -57,17 +58,17 @@ bun add -g failproofai failproofai policies ``` - 모든 정책, 활성화 여부, 설정된 파라미터를 표시합니다. + 모든 정책과 활성화 여부, 설정된 파라미터를 표시합니다. ```bash failproofai ``` - `http://localhost:8020`에 로컬 대시보드를 열어 세션 조회, 도구 호출 검사, 정책 관리를 할 수 있습니다. + `http://localhost:8020`에 로컬 대시보드를 열어 세션을 탐색하고, 도구 호출을 검사하며, 정책을 관리할 수 있습니다. - 평소처럼 Claude Code를 시작하세요. 에이전트가 위험한 작업을 시도하면 failproofai가 자동으로 차단합니다. 자리를 비워도 대시보드에서 실행 내역을 확인할 수 있습니다. + 평소처럼 Claude Code를 시작하세요. 에이전트가 위험한 작업을 시도하면 failproofai가 자동으로 차단합니다. 에이전트를 무인으로 실행한 후 대시보드에서 결과를 확인하세요. @@ -75,7 +76,7 @@ bun add -g failproofai ## 정책 작동 방식 -에이전트가 도구를 실행할 때마다 Claude Code는 failproofai를 서브프로세스로 호출합니다: +에이전트가 도구를 실행할 때마다 Claude Code는 failproofai를 서브프로세스로 호출합니다. ```text Claude Code → failproofai --hook PreToolUse → reads stdin JSON @@ -83,36 +84,36 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON writes decision to stdout ``` -각 정책은 세 가지 결정 중 하나를 반환합니다: +각 정책은 다음 세 가지 결정 중 하나를 반환합니다. -- **allow** - 에이전트가 정상적으로 진행됨 -- **deny** - 작업이 차단되고, 에이전트에게 이유가 전달됨 -- **instruct** - 에이전트의 프롬프트에 추가 컨텍스트가 삽입됨 +- **allow** - 에이전트가 정상적으로 진행됩니다 +- **deny** - 작업이 차단되고 에이전트에게 이유가 전달됩니다 +- **instruct** - 에이전트의 프롬프트에 추가 컨텍스트가 삽입됩니다 -정책은 로컬 프로세스에서 실행됩니다. 외부 서비스로 어떤 데이터도 전송되지 않습니다. +정책은 로컬 프로세스에서 실행됩니다. 원격 서비스로는 아무것도 전송되지 않습니다. --- ## 컨벤션 기반 정책으로 팀 정책 설정하기 -팀 전체에 품질 기준을 빠르게 확립하는 방법은 `.failproofai/policies/` 컨벤션을 활용하는 것입니다. 이 디렉토리에 정책 파일을 추가하면 자동으로 로드됩니다 — 플래그, 설정 변경, 설치 명령이 필요 없습니다. +팀 전체에 품질 기준을 빠르게 적용하는 방법은 `.failproofai/policies/` 컨벤션을 활용하는 것입니다. 이 디렉터리에 정책 파일을 넣으면 자동으로 로드됩니다 — 별도의 플래그, 설정 변경, 설치 명령이 필요 없습니다. - + ```bash mkdir -p .failproofai/policies ``` - 예제 파일을 복사하거나 직접 작성하세요: + 스타터 예제를 복사하거나 직접 작성하세요. ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ ``` - 또는 새로 만들기: + 또는 새로 작성하세요. ```js // .failproofai/policies/team-policies.mjs @@ -137,24 +138,24 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON git commit -m "Add team quality policies" ``` - failproofai가 설치된 모든 팀원은 이 정책을 자동으로 적용받습니다. 개발자별 별도 설정이 필요 없습니다. + failproofai를 설치한 모든 팀원이 이 정책을 자동으로 적용받습니다. 개발자별 별도 설정이 필요 없습니다. -팀 전체가 동일한 기준을 공유할 수 있도록 `.failproofai/policies/`를 저장소에 커밋하세요. 팀이 새로운 장애 유형을 발견할 때마다 정책을 추가하고 푸시하면 — 모든 팀원이 다음 `git pull` 시 업데이트를 받게 됩니다. 시간이 지남에 따라 이 정책들은 지속적으로 발전하는 살아있는 품질 기준이 됩니다. +`.failproofai/policies/`를 저장소에 커밋하면 팀 전체가 동일한 기준을 공유할 수 있습니다. 팀이 새로운 장애 유형을 발견할 때마다 정책을 추가하고 푸시하세요 — 모든 팀원이 다음 `git pull` 시 업데이트를 받습니다. 시간이 지남에 따라 이 정책들은 지속적으로 발전하는 살아있는 품질 기준이 됩니다. --- ## 데이터 저장 -모든 설정과 로그는 로컬 머신에 저장됩니다: +모든 설정과 로그는 로컬 머신에 저장됩니다. | 경로 | 저장 내용 | |------|----------------| | `~/.failproofai/policies-config.json` | 전역 정책 설정 | -| `~/.failproofai/hook-activity.jsonl` | 훅 실행 기록 | +| `~/.failproofai/hook-activity.jsonl` | 훅 실행 이력 | | `~/.failproofai/hook.log` | 커스텀 훅 오류 디버그 로그 | | `.failproofai/policies-config.json` | 프로젝트별 설정 (커밋됨) | | `.failproofai/policies-config.local.json` | 개인 오버라이드 (gitignore 처리됨) | @@ -176,11 +177,11 @@ failproofai policies --uninstall - 스코프 및 설정 파일 형식 + 범위 및 설정 파일 형식 - - 파라미터가 포함된 26가지 정책 전체 목록 + + 파라미터가 있는 26가지 정책 전체 목록 diff --git a/docs/ko/introduction.mdx b/docs/ko/introduction.mdx index 080be9ae..b48424a0 100644 --- a/docs/ko/introduction.mdx +++ b/docs/ko/introduction.mdx @@ -5,32 +5,32 @@ description: "FailproofAI는 단 한 번의 설치로 루프, 시크릿 유출, [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -**AI 장애 처리**, **오류 복구**, **LLM 안정성**을 위한 훅과 정책. **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, 그리고 **Agents SDK**에서 AI 에이전트가 안정적으로 자율 실행될 수 있도록 지원합니다. +**AI 실패 처리**, **오류 복구**, **LLM 안정성**을 위한 훅과 정책 모음입니다. **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, **Hermes**, **Agents SDK** 전반에 걸쳐 AI 에이전트를 안정적으로 자율 실행할 수 있도록 지원합니다. -AI 에이전트는 예측 가능한 방식으로 실패합니다. 파괴적인 명령을 실행하거나, 시크릿을 유출하거나, 작업에서 벗어나거나, 루프에 빠지거나, main 브랜치에 직접 푸시하기도 합니다. 방치하면 사소한 실패가 서비스 장애, 자격 증명 유출, 작업 손실로 이어집니다. +AI 에이전트는 예측 가능한 방식으로 실패합니다. 파괴적인 명령을 실행하거나, 시크릿을 유출하거나, 작업 범위를 벗어나거나, 루프에 빠지거나, main 브랜치에 직접 푸시하기도 합니다. 방치하면 사소한 실패가 서비스 장애, 자격 증명 유출, 작업 손실로 이어질 수 있습니다. -FailproofAI는 **정책(policies)**으로 이 문제를 해결합니다. 이 규칙들은 모든 에이전트 도구 호출에 연결되어 **장애를 감지**하고, **완화 조치(차단, 지시, 정제)**를 취하며, 주의가 필요할 때 **알림을 전송**합니다. 로컬 대시보드에서 모든 도구 호출, 에이전트 장애, 복구 조치를 나중에 검토할 수 있습니다. +FailproofAI는 **정책**으로 이 문제를 해결합니다. 정책은 모든 에이전트 도구 호출에 연결되어 **실패를 감지**하고, **완화 조치**(차단, 지시, 정제)를 취하며, 주의가 필요할 때 **알림을 보냅니다**. 로컬 대시보드에서는 이후에 모든 도구 호출, 에이전트 실패, 복구 조치를 확인할 수 있습니다. -모든 데이터는 사용자의 머신을 벗어나지 않습니다. +데이터는 사용자의 머신 밖으로 나가지 않습니다. ## 시작하기 - 파괴적인 명령 차단, 시크릿 유출 방지, 에이전트를 프로젝트 범위 내로 제한하는 등 다양한 기능을 기본으로 제공합니다. + 파괴적인 명령 차단, 시크릿 유출 방지, 에이전트를 프로젝트 범위 내로 제한하는 기능 등을 기본 제공합니다. - 간단한 allow / deny / instruct API로 JavaScript 기반 규칙을 직접 작성하세요. + 간단한 allow / deny / instruct API로 JavaScript 기반의 자체 규칙을 작성하세요. - 자리를 비운 동안 에이전트가 무엇을 했는지 확인하세요. 세션을 탐색하고, 도구 호출을 검사하며, 정책이 실행된 위치를 검토할 수 있습니다. + 자리를 비운 동안 에이전트가 무엇을 했는지 확인하세요. 세션을 탐색하고, 도구 호출을 검사하며, 정책이 발동된 지점을 검토할 수 있습니다. - 코드 없이 모든 정책을 조정하세요. 허용 목록, 보호 브랜치, 임계값을 프로젝트별 또는 전역으로 설정할 수 있습니다. + 코드 없이 모든 정책을 조정하세요. 프로젝트별 또는 전역으로 허용 목록, 보호 브랜치, 임계값을 설정할 수 있습니다. @@ -54,4 +54,4 @@ failproofai policies --install # enable policies (or skip — `failproofai` wi failproofai # launch the dashboard ``` -전체 설명은 [시작하기](/ko/getting-started) 가이드를 참고하세요. \ No newline at end of file +전체 안내는 [시작하기](/ko/getting-started) 가이드를 참고하세요. \ No newline at end of file diff --git a/docs/ko/package-aliases.mdx b/docs/ko/package-aliases.mdx index ec4476e1..a5129fe7 100644 --- a/docs/ko/package-aliases.mdx +++ b/docs/ko/package-aliases.mdx @@ -1,12 +1,12 @@ --- title: 패키지 별칭 -description: "등록된 오타 방지 별칭과 그 동작 방식" +description: "등록된 오타 방지 별칭과 그 작동 방식" icon: copy --- ## 공식 패키지 -npm의 정식 패키지명은 **`failproofai`**입니다: +npm의 정식 패키지는 **`failproofai`**입니다: ```bash npm install -g failproofai @@ -16,17 +16,17 @@ bun add -g failproofai --- -## 별칭을 직접 소유하는 이유 +## 별칭 이름을 직접 소유하는 이유 -타이포스쿼팅(typosquatting)은 공급망 공격의 일반적인 수법으로, 악의적인 행위자가 인기 패키지 이름과 한 글자 차이나는 패키지명을 등록합니다. 설치 명령어를 잘못 입력한 사용자는 전체 시스템 접근 권한을 가진 공격자 제어 코드를 실행하게 됩니다 — 이것이 바로 Failproof AI가 방어하도록 설계된 위협의 전형적인 예입니다. +타이포스쿼팅(typosquatting)은 공급망 공격의 일종으로, 악의적인 공격자가 인기 패키지 이름에서 오타 한 글자 차이나는 패키지 이름을 등록합니다. 설치 명령어를 잘못 입력한 사용자는 자신도 모르는 사이에 공격자가 제어하는 코드를 전체 시스템 접근 권한으로 실행하게 됩니다 — 이것이 바로 Failproof AI가 방어하도록 설계된 위협 유형입니다. -이러한 공격 표면을 제거하기 위해, **저희는 npm에서 `failproofai`의 일반적인 오타 및 표기 변형을 모두 선제적으로 소유하고 있습니다**. 이 이름들 중 어느 것도 제3자가 등록할 수 없습니다. 각 이름은 실제 `failproofai` 패키지를 설치하고 위임하는 얇은 프록시입니다. +이러한 공격 표면을 없애기 위해, **npm에서 `failproofai`의 흔한 오타 및 표기 변형 이름을 선제적으로 모두 소유**하고 있습니다. 이 이름들은 제3자가 등록할 수 없으며, 각각은 실제 `failproofai` 패키지를 설치하고 위임하는 얇은 프록시입니다. --- ## 등록된 별칭 -**표기 변형** — "failproof ai"를 쓰는 다양한 방식: +**표기 변형** - "failproof ai"를 표현하는 다양한 방식: | 패키지 | 상태 | |---------|--------| @@ -37,7 +37,7 @@ bun add -g failproofai | `fail_proof_ai` | ⏳ npm 승인 대기 중 | | `fail-proofai` | ⏳ npm 승인 대기 중 | -**`failprof*` 오타** — "proof"에서 `o` 하나가 빠진 경우: +**`failprof*` 오타** - "proof"에서 `o` 하나가 빠진 경우: | 패키지 | 상태 | |---------|--------| @@ -47,7 +47,7 @@ bun add -g failproofai | `fail-prof-ai` | ⏳ npm 승인 대기 중 | | `failprof_ai` | ⏳ npm 승인 대기 중 | -**`faliproof*` 오타** — `a`와 `i`가 뒤바뀐 경우: +**`faliproof*` 오타** - `a`와 `i`가 뒤바뀐 경우: | 패키지 | 상태 | |---------|--------| @@ -55,9 +55,9 @@ bun add -g failproofai | `faliproof-ai` | ✅ 게시됨 | | `faliproofai` | ⏳ npm 승인 대기 중 | -> **승인 대기 중인 이유:** npm의 스팸 방지 정책은 구두점을 제거하고 유사도 검사를 실행했을 때 기존 패키지와 동일한 문자열로 정규화되는 이름을 차단합니다. 저희는 스쿼팅 방지 목적으로 이 이름들을 예약하기 위해 npm 지원팀에 연락했으며, 승인 후 활성화될 예정입니다. +> **승인 대기 중인 이유는?** npm의 스팸 방지 정책은 구두점을 제거하고 유사도 검사를 실행한 후 기존 패키지와 동일한 문자열로 정규화되는 이름을 차단합니다. 저희는 안티 스쿼팅 목적으로 이 이름들을 예약하기 위해 npm 지원팀에 문의한 상태이며, 승인되는 대로 활성화될 예정입니다. -다음 명령어로 게시된 별칭이 저희 소유인지 확인할 수 있습니다: +게시된 별칭이 저희 소유인지 다음과 같이 확인할 수 있습니다: ```bash npm info failproof @@ -66,17 +66,17 @@ npm info failproof --- -## 별칭의 동작 방식 +## 별칭의 작동 방식 각 별칭 패키지는: -1. `failproofai`를 의존성으로 등록하여 설치 시 실제 패키지(`postinstall` 훅 설정 포함)가 실행되도록 합니다 -2. 자신의 이름에 해당하는 바이너리(예: `failprof-ai`)를 노출하며, 모든 인수를 `failproofai` 바이너리로 프록시합니다 +1. `failproofai`를 의존성으로 등록합니다 — 설치 시 실제 패키지(및 해당 `postinstall` 훅 설정 포함)가 실행됩니다. +2. 자신의 이름에 해당하는 바이너리(예: `failprof-ai`)를 노출하여 모든 인자를 `failproofai` 바이너리로 전달합니다. -프록시는 두 줄짜리 Node 스크립트이며, 로직도 없고 네트워크 호출도 없고, `failproofai` 자체가 수행하는 것 이외의 데이터 수집도 없습니다. +프록시는 두 줄짜리 Node 스크립트이며, `failproofai` 자체가 수행하는 것 외에는 어떠한 로직, 네트워크 호출, 데이터 수집도 없습니다. --- ## 누락된 이름을 발견한 경우 -[failproofai/failproofai](https://github.com/failproofai/failproofai/issues)에 이슈를 열어주시면 등록하겠습니다. \ No newline at end of file +[failproofai/failproofai](https://github.com/failproofai/failproofai/issues)에 이슈를 등록해 주시면 해당 이름을 등록하겠습니다. \ No newline at end of file diff --git a/docs/ko/testing.mdx b/docs/ko/testing.mdx index 4b83200b..b841cade 100644 --- a/docs/ko/testing.mdx +++ b/docs/ko/testing.mdx @@ -1,23 +1,23 @@ --- title: 테스트 -description: "유닛 테스트, E2E 테스트, 테스트 헬퍼" +description: "단위 테스트, E2E 테스트, 테스트 헬퍼" icon: flask-vial --- -failproofai에는 두 가지 테스트 스위트가 있습니다: **유닛 테스트** (빠른 실행, 모킹 사용)와 **엔드-투-엔드 테스트** (실제 서브프로세스 호출). +failproofai에는 두 가지 테스트 스위트가 있습니다: **단위 테스트** (빠름, 목(mock) 사용)와 **엔드투엔드 테스트** (실제 서브프로세스 호출). --- ## 테스트 실행 ```bash -# 유닛 테스트 한 번 실행 +# 단위 테스트 한 번 실행 bun run test:run -# 유닛 테스트를 워치 모드로 실행 +# 단위 테스트를 감시 모드로 실행 bun run test -# E2E 테스트 실행 (사전 설정 필요 - 아래 참고) +# E2E 테스트 실행 (설정 필요 - 아래 참조) bun run test:e2e # 빌드 없이 타입 검사 @@ -29,19 +29,19 @@ bun run lint --- -## 유닛 테스트 +## 단위 테스트 -유닛 테스트는 `__tests__/` 디렉터리에 위치하며, `jsdom`과 함께 [Vitest](https://vitest.dev)를 사용합니다. +단위 테스트는 `__tests__/` 디렉터리에 위치하며 `jsdom`과 함께 [Vitest](https://vitest.dev)를 사용합니다. ```text __tests__/ hooks/ - builtin-policies.test.ts # 각 빌트인 정책 로직 + builtin-policies.test.ts # 각 내장 정책의 로직 hooks-config.test.ts # 설정 로딩 및 스코프 병합 policy-evaluator.test.ts # 파라미터 주입 및 평가 순서 custom-hooks-registry.test.ts # globalThis 레지스트리 추가/조회/초기화 - custom-hooks-loader.test.ts # ESM 로더, 전이적 임포트, 오류 처리 - manager.test.ts # 설치/제거/목록 조회 작업 + custom-hooks-loader.test.ts # ESM 로더, 전이적 임포트, 에러 처리 + manager.test.ts # install/remove/list 작업 components/ sessions-list.test.tsx # 세션 목록 컴포넌트 project-list.test.tsx # 프로젝트 목록 컴포넌트 @@ -61,7 +61,7 @@ __tests__/ AutoRefreshContext.test.tsx ``` -### 정책 유닛 테스트 작성하기 +### 정책 단위 테스트 작성하기 ```typescript import { describe, it, expect, beforeEach } from "vitest"; @@ -108,19 +108,19 @@ describe("block-sudo", () => { --- -## 엔드-투-엔드 테스트 +## 엔드투엔드 테스트 -E2E 테스트는 실제 `failproofai` 바이너리를 서브프로세스로 실행하고, JSON 페이로드를 stdin으로 전달한 뒤, stdout 출력과 종료 코드를 검증합니다. 이를 통해 Claude Code가 사용하는 전체 통합 경로를 테스트합니다. +E2E 테스트는 실제 `failproofai` 바이너리를 서브프로세스로 호출하고, JSON 페이로드를 stdin으로 전달한 뒤, stdout 출력과 종료 코드를 검증합니다. 이는 Claude Code가 사용하는 전체 통합 경로를 테스트합니다. ### 설정 -E2E 테스트는 레포지터리 소스에서 직접 바이너리를 실행합니다. 첫 실행 전에, 커스텀 훅 파일이 `'failproofai'`에서 임포트할 때 사용하는 CJS 번들을 빌드해야 합니다: +E2E 테스트는 저장소 소스에서 바이너리를 직접 실행합니다. 첫 실행 전에, 커스텀 훅 파일이 `'failproofai'`에서 임포트할 때 사용하는 CJS 번들을 빌드하세요: ```bash bun build src/index.ts --outdir dist --target node --format cjs ``` -그런 다음 테스트를 실행합니다: +이후 테스트를 실행합니다: ```bash bun run test:e2e @@ -133,26 +133,26 @@ bun run test:e2e ```text __tests__/e2e/ helpers/ - hook-runner.ts # 바이너리 실행, 페이로드 JSON 전달, 종료 코드 + stdout + stderr 캡처 - fixture-env.ts # 테스트별 격리된 임시 디렉터리와 설정 파일 - payloads.ts # 각 이벤트 타입에 대한 Claude 형식의 페이로드 팩토리 + hook-runner.ts # 바이너리 실행, 페이로드 JSON 파이핑, 종료 코드 + stdout + stderr 캡처 + fixture-env.ts # 테스트별 독립 임시 디렉터리 및 설정 파일 + payloads.ts # 각 이벤트 타입에 대한 Claude 호환 페이로드 팩토리 hooks/ - builtin-policies.e2e.test.ts # 실제 서브프로세스로 각 빌트인 정책 테스트 + builtin-policies.e2e.test.ts # 실제 서브프로세스로 각 내장 정책 테스트 custom-hooks.e2e.test.ts # 커스텀 훅 로딩 및 평가 - config-scopes.e2e.test.ts # 프로젝트/로컬/전역 설정 병합 - policy-params.e2e.test.ts # 각 파라미터화된 정책의 파라미터 주입 + config-scopes.e2e.test.ts # 프로젝트/로컬/글로벌 간 설정 병합 + policy-params.e2e.test.ts # 파라미터화된 정책의 파라미터 주입 ``` ### E2E 헬퍼 사용하기 -**`FixtureEnv`** - 테스트별 격리 환경: +**`FixtureEnv`** - 테스트별 독립 환경: ```typescript import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - 임시 디렉터리; .failproofai/policies-config.json을 불러오려면 payload.cwd로 전달 -// env.home - 격리된 홈 디렉터리; 실제 ~/.failproofai가 유입되지 않음 +// env.cwd - 임시 디렉터리; .failproofai/policies-config.json을 인식하도록 payload.cwd에 전달 +// env.home - 독립 홈 디렉터리; 실제 ~/.failproofai가 유입되지 않음 env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -162,9 +162,9 @@ env.writeConfig({ }); ``` -`createFixtureEnv()`는 `afterEach` 정리 작업을 자동으로 등록합니다. +`createFixtureEnv()`는 `afterEach` 정리를 자동으로 등록합니다. -**`runHook`** - 바이너리 실행: +**`runHook`** - 바이너리 호출: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - 미리 준비된 페이로드 팩토리: +**`Payloads`** - 미리 만들어진 페이로드 팩토리: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -238,7 +238,7 @@ describe("block-rm-rf (E2E)", () => { | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | | Instruct (Stop 제외) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop instruct | `2` | stdout 비어 있음; 이유는 stderr에 출력 | +| Stop instruct | `2` | 빈 stdout; 이유는 stderr에 출력 | | Allow | `0` | 빈 문자열 | ### Vitest 설정 @@ -247,9 +247,9 @@ E2E 테스트는 `vitest.config.e2e.mts`를 사용하며 다음과 같이 구성 - `environment: "node"` - 브라우저 전역 변수 불필요 - `pool: "forks"` - 진정한 프로세스 격리 (테스트가 서브프로세스를 생성) -- `testTimeout: 20_000` - 테스트당 20초 제한 (바이너리 시작 + 훅 평가) +- `testTimeout: 20_000` - 테스트당 20초 (바이너리 시작 + 훅 평가) -`forks` 풀이 중요한 이유는, 스레드 기반 워커는 `globalThis`를 공유하여 서브프로세스를 생성하는 테스트에 간섭할 수 있기 때문입니다. 프로세스 기반 포크는 이 문제를 방지합니다. +`forks` 풀이 중요한 이유: 스레드 기반 워커는 `globalThis`를 공유하므로 서브프로세스를 생성하는 테스트에 간섭이 발생할 수 있습니다. 프로세스 기반 포크는 이 문제를 방지합니다. --- @@ -257,4 +257,4 @@ E2E 테스트는 `vitest.config.e2e.mts`를 사용하며 다음과 같이 구성 병합 전에 전체 CI 실행(`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`)이 통과되어야 합니다. E2E 스위트는 별도의 CI 작업으로 병렬 실행됩니다. -전체 병합 전 체크리스트는 [Contributing](../CONTRIBUTING.md)을 참고하세요. \ No newline at end of file +전체 병합 전 체크리스트는 [Contributing](../CONTRIBUTING.md)를 참조하세요. \ No newline at end of file diff --git a/docs/pt-br/architecture.mdx b/docs/pt-br/architecture.mdx index 1e99e769..f6cf95e7 100644 --- a/docs/pt-br/architecture.mdx +++ b/docs/pt-br/architecture.mdx @@ -1,6 +1,6 @@ --- title: Arquitetura -description: "Como o handler de hooks, o carregamento de configuração e a avaliação de políticas funcionam internamente" +description: "Como o manipulador de hooks, o carregamento de configuração e a avaliação de políticas funcionam internamente" icon: sitemap --- @@ -12,14 +12,14 @@ Este documento explica como o failproofai funciona internamente: como o sistema O failproofai possui dois subsistemas independentes: -1. **Hook handler** - Um subprocesso CLI rápido que o Claude Code invoca a cada chamada de ferramenta do agente. Avalia as políticas e retorna uma decisão. -2. **Agent Monitor (Dashboard)** - Uma aplicação web Next.js para monitorar sessões de agentes e gerenciar políticas. +1. **Manipulador de hooks** - Um subprocesso de CLI rápido que o Claude Code invoca a cada chamada de ferramenta do agente. Avalia as políticas e retorna uma decisão. +2. **Monitor de Agentes (Dashboard)** - Uma aplicação web Next.js para monitorar sessões de agentes e gerenciar políticas. Ambos os subsistemas compartilham arquivos de configuração em `~/.failproofai/` e no diretório `.failproofai/` do projeto, mas são executados como processos separados e se comunicam apenas pelo sistema de arquivos. --- -## Hook handler +## Manipulador de hooks ### Integração com o Claude Code @@ -44,7 +44,7 @@ Quando você executa `failproofai policies --install`, ele grava entradas como e } ``` -O Claude Code então invoca `failproofai --hook PreToolUse` como subprocesso antes de cada chamada de ferramenta, passando um payload JSON via stdin. +O Claude Code então invoca `failproofai --hook PreToolUse` como um subprocesso antes de cada chamada de ferramenta, passando um payload JSON via stdin. ### Formato do payload @@ -62,7 +62,7 @@ O Claude Code então invoca `failproofai --hook PreToolUse` como subprocesso ant Para eventos `PostToolUse`, o payload também contém `tool_result` com a saída da ferramenta. -O handler impõe um limite de 1 MB para o stdin. Payloads que excedam esse limite são descartados e todas as políticas implicitamente permitem a operação. +O manipulador aplica um limite de 1 MB no stdin. Payloads que excedam esse limite são descartados e todas as políticas permitem implicitamente. ### Formato da resposta @@ -96,7 +96,7 @@ O handler impõe um limite de 1 MB para o stdin. Payloads que excedam esse limit **Instruir no evento Stop:** - Código de saída: `2` -- Motivo gravado em stderr (não stdout) +- Motivo gravado no stderr (não no stdout) **Permitir:** - Código de saída: `0` @@ -104,7 +104,7 @@ O handler impõe um limite de 1 MB para o stdin. Payloads que excedam esse limit **Permitir com mensagem:** -`allow(message)` permite que uma política envie contexto informacional de volta ao Claude mesmo quando a operação é permitida. O hook handler grava o seguinte JSON no **stdout** (não em um arquivo de configuração — esta é a resposta do handler ao Claude Code, assim como as respostas de deny e instruct acima): +`allow(message)` permite que uma política envie contexto informativo de volta ao Claude mesmo quando a operação é permitida. O manipulador de hooks grava o seguinte JSON no **stdout** (não em um arquivo de configuração — esta é a resposta do manipulador ao Claude Code, assim como as respostas de deny e instruct acima): ```json // Written to stdout by the hook handler process @@ -116,7 +116,7 @@ O handler impõe um limite de 1 MB para o stdin. Payloads que excedam esse limit ``` - Código de saída: `0` (a operação é permitida) - Quando múltiplas políticas retornam `allow` com uma mensagem, suas mensagens são concatenadas com quebras de linha em uma única string `additionalContext` -- Se nenhuma política fornecer uma mensagem, o stdout fica vazio (como antes) +- Se nenhuma política fornecer uma mensagem, o stdout fica vazio (igual ao comportamento anterior) ### Pipeline de processamento @@ -159,7 +159,7 @@ Lógica de mesclagem: - `customPoliciesPath` - o primeiro arquivo que o define prevalece - `llm` - o primeiro arquivo que o define prevalece -O dashboard web usa `readHooksConfig()` (somente global) para leitura e escrita, pois não é invocado com um cwd de projeto. +O dashboard web utiliza `readHooksConfig()` (somente global) para leitura e escrita, pois não é invocado com um cwd de projeto. --- @@ -169,15 +169,15 @@ O dashboard web usa `readHooksConfig()` (somente global) para leitura e escrita, Para cada política: -1. Busca o schema de `params` da política (se houver). +1. Busca o esquema `params` da política (se houver). 2. Lê `policyParams[policy.name]` da configuração mesclada. -3. Mescla os valores fornecidos pelo usuário sobre os padrões do schema para produzir `ctx.params`. +3. Mescla os valores fornecidos pelo usuário sobre os padrões do esquema para produzir `ctx.params`. 4. Chama `policy.fn(ctx)` com o contexto resolvido. 5. Se o resultado for `deny`, para imediatamente e retorna essa decisão. 6. Se o resultado for `instruct`, acumula a mensagem e continua. 7. Se o resultado for `allow`, continua para a próxima política. -Após a execução de todas as políticas: +Após todas as políticas serem executadas: - Se algum `deny` foi retornado, emite a resposta de negação. - Se algum retorno `instruct` foi coletado, emite uma única resposta de instrução com todas as mensagens concatenadas. - Caso contrário, emite uma resposta de permissão (stdout vazio, exit 0). @@ -204,9 +204,9 @@ interface BuiltinPolicyDefinition { } ``` -Políticas que aceitam `params` declaram um `PolicyParamsSchema` com tipos e valores padrão para cada parâmetro. O avaliador de políticas injeta os valores resolvidos em `ctx.params` antes de chamar `fn`. As funções de política leem `ctx.params` sem verificações de nulo, pois os padrões são sempre aplicados primeiro. +Políticas que aceitam `params` declaram um `PolicyParamsSchema` com tipos e valores padrão para cada parâmetro. O avaliador de políticas injeta os valores resolvidos em `ctx.params` antes de chamar `fn`. As funções de política leem `ctx.params` sem verificações de nulo porque os padrões são sempre aplicados primeiro. -A correspondência de padrões dentro das políticas usa tokens de comando analisados (argv), não correspondência de string bruta. Isso evita contornar via injeção de operadores shell (por exemplo, um padrão para `sudo systemctl status *` não pode ser contornado adicionando `; rm -rf /` ao comando). +A correspondência de padrões dentro das políticas usa tokens de comando analisados (argv), não correspondência de strings brutas. Isso impede bypass via injeção de operadores de shell (por exemplo, um padrão para `sudo systemctl status *` não pode ser contornado adicionando `; rm -rf /` ao comando). --- @@ -229,21 +229,21 @@ export function clearCustomHooks(): void { ... } // used in tests 1. Lê `customPoliciesPath` da configuração; ignora se ausente. 2. Resolve para caminho absoluto; verifica se o arquivo existe. -3. Reescreve todas as importações `from "failproofai"` para o caminho real de dist, de modo que `customPolicies` resolva para o mesmo registro `globalThis`. +3. Reescreve todas as importações `from "failproofai"` para o caminho real do dist, de modo que `customPolicies` resolva para o mesmo registro `globalThis`. 4. Reescreve recursivamente as importações locais transitivas para garantir compatibilidade com ESM. -5. Grava arquivos `.mjs` temporários e importa o arquivo de entrada com `import()`. +5. Grava arquivos `.mjs` temporários e faz `import()` do arquivo de entrada. 6. Chama `getCustomHooks()` para recuperar os hooks registrados. 7. Remove todos os arquivos temporários em um bloco `finally`. Em caso de qualquer erro (arquivo não encontrado, erro de sintaxe, falha de importação), o erro é registrado em `~/.failproofai/hook.log` e o carregador retorna um array vazio. As políticas integradas não são afetadas. -As políticas personalizadas são avaliadas após todas as políticas integradas. Um `deny` de uma política personalizada ainda interrompe o processamento das demais políticas personalizadas (mas todos os integrados já foram executados nesse ponto). +As políticas personalizadas são avaliadas após todas as políticas integradas. Um `deny` de uma política personalizada ainda interrompe as demais políticas personalizadas (mas todos os integrados já terão sido executados nesse ponto). --- -## Log de atividade +## Registro de atividades -Após cada evento de hook, o handler adiciona uma linha JSONL em `~/.failproofai/hook-activity.jsonl`: +Após cada evento de hook, o manipulador acrescenta uma linha JSONL ao `~/.failproofai/hook-activity.jsonl`: ```json { @@ -264,21 +264,21 @@ Uma linha por política que tomou uma decisão diferente de allow. Decisões de ## Arquitetura do dashboard -O dashboard é uma aplicação **Next.js 16** que usa o App Router com React Server Components e Server Actions. +O dashboard é uma aplicação **Next.js 16** que utiliza o App Router com React Server Components e Server Actions. ```text app/ - layout.tsx ← Layout raiz (tema, telemetria, navegação) + layout.tsx ← Layout raiz (tema, telemetria, nav) projects/page.tsx ← Server component: lista todos os projetos Claude project/[name]/page.tsx ← Server component: lista sessões de um projeto project/[name]/session/ [sessionId]/page.tsx ← Server component: renderiza o visualizador de sessão - policies/page.tsx ← Client component: gerenciamento de políticas + log de atividade + policies/page.tsx ← Client component: gerenciamento de políticas + log de atividades actions/ - get-hooks-config.ts ← Lê configuração + lista de políticas + get-hooks-config.ts ← Lê config + lista de políticas update-hooks-config.ts ← Ativa/desativa política - update-policy-params.ts ← Atualiza parâmetros de política - get-hook-activity.ts ← Pagina/pesquisa o log de atividade + update-policy-params.ts ← Atualiza parâmetros da política + get-hook-activity.ts ← Paginação/busca no log de atividades install-hooks-web.ts ← Instala/remove hooks pelo navegador api/ download/[project]/[session]/route.ts ← Exportação de sessão por CLI (JSONL ou JSON) @@ -286,16 +286,16 @@ app/ **Fluxo de dados:** -- Os componentes de página chamam `lib/projects.ts` e `lib/log-entries.ts` para ler dados de projetos/sessões diretamente do sistema de arquivos (sem camada de API para leituras). -- A página de Políticas usa Server Actions para todas as mutações (ativar/desativar, atualização de parâmetros, instalar/remover). +- Os componentes de página chamam `lib/projects.ts` e `lib/log-entries.ts` para ler dados de projeto/sessão diretamente do sistema de arquivos (sem camada de API para leituras). +- A página de Políticas usa Server Actions para todas as mutações (ativar/desativar, atualizar parâmetros, instalar/remover). - O visualizador de sessão analisa o formato de transcrição JSONL do Claude e renderiza uma linha do tempo de mensagens e chamadas de ferramentas. -**Principais decisões de design:** +**Decisões de design principais:** -- Sem banco de dados — todo o estado persistente está em arquivos simples (`~/.failproofai/`, `~/.claude/projects/`). +- Sem banco de dados — todo estado persistente está em arquivos simples (`~/.failproofai/`, `~/.claude/projects/`). - Server Actions para mutações — nenhuma API REST necessária para operações CRUD. -- React Server Components para páginas de leitura — carregamento inicial mais rápido, sem bundle de cliente para busca de dados. -- Client components apenas onde há necessidade de interatividade (toggles de políticas, pesquisa de atividade, visualizador de log). +- React Server Components para páginas de leitura — carregamento inicial mais rápido, sem bundle do cliente para busca de dados. +- Client components apenas onde há necessidade de interatividade (alternância de políticas, busca de atividades, visualizador de logs). --- @@ -304,17 +304,17 @@ app/ ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # Roteador CLI (hook / dashboard / install / etc.) +│ └── failproofai.mjs # Roteador de CLI (hook / dashboard / install / etc.) ├── src/hooks/ │ ├── handler.ts # Pipeline de eventos de hook │ ├── builtin-policies.ts # 39 definições de políticas │ ├── policy-evaluator.ts # Motor de execução de políticas │ ├── policy-registry.ts # Registro e busca de políticas │ ├── policy-types.ts # Interfaces TypeScript -│ ├── hooks-config.ts # Carregamento de configuração em múltiplos escopos +│ ├── hooks-config.ts # Carregamento de config em múltiplos escopos │ ├── custom-hooks-registry.ts # Registro de hooks baseado em globalThis │ ├── custom-hooks-loader.ts # Carregador ESM para hooks JS do usuário -│ ├── manager.ts # Operações de instalar / remover / listar +│ ├── manager.ts # Operações de install / remove / list │ ├── install-prompt.ts # Prompt interativo de seleção de políticas │ ├── hook-logger.ts # Logging para hook.log │ ├── hook-activity-store.ts # Persistência de atividade em hook-activity.jsonl @@ -322,11 +322,11 @@ failproofai/ ├── app/ # Dashboard Next.js (páginas + server actions) ├── lib/ # Utilitários compartilhados │ ├── projects.ts # Enumera projetos Claude do sistema de arquivos -│ ├── log-entries.ts # Analisa o formato de transcrição JSONL do Claude +│ ├── log-entries.ts # Analisa o formato JSONL de transcrição do Claude │ ├── paths.ts # Resolve caminhos do sistema │ └── ... -├── components/ # Componentes React de UI compartilhados +├── components/ # Componentes de UI React compartilhados ├── contexts/ # Provedores de contexto React (tema, auto-refresh, telemetria) -├── examples/ # Arquivos de hooks personalizados de exemplo +├── examples/ # Exemplos de arquivos de hooks personalizados └── __tests__/ # Testes unitários e E2E ``` \ No newline at end of file diff --git a/docs/pt-br/built-in-policies.mdx b/docs/pt-br/built-in-policies.mdx index 9170ee68..6d84b6c4 100644 --- a/docs/pt-br/built-in-policies.mdx +++ b/docs/pt-br/built-in-policies.mdx @@ -1,10 +1,10 @@ --- title: Políticas Integradas -description: "Todas as 39 políticas integradas que detectam modos comuns de falha em agentes" +description: "Todas as 39 políticas integradas que detectam falhas comuns de agentes" icon: shield --- -failproofai vem com 39 políticas integradas que detectam modos comuns de falha em agentes. Cada política é acionada em um tipo específico de evento de hook e nome de ferramenta. Dezenove políticas aceitam parâmetros que permitem ajustar seu comportamento sem escrever código. Cinco políticas de fluxo de trabalho impõem um pipeline de commit → push → PR → CI antes que Claude pare. +failproofai vem com 39 políticas integradas que detectam falhas comuns de agentes. Cada política é acionada em um tipo específico de evento de hook e nome de ferramenta. Dezenove políticas aceitam parâmetros que permitem ajustar seu comportamento sem escrever código. Cinco políticas de fluxo de trabalho impõem um pipeline de commit → push → PR → CI antes que o Claude pare. --- @@ -26,18 +26,14 @@ As políticas são agrupadas em categorias: | [Fluxo de trabalho](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | - **`block-`** — impede o agente de prosseguir. -- **`warn-`** — fornece contexto adicional ao agente para que ele possa se autocorrigir. -- **`sanitize-`** — remove dados sensíveis da saída de ferramentas antes que o agente os visualize. +- **`warn-`** — fornece ao agente contexto adicional para que ele possa se corrigir. +- **`sanitize-`** — remove dados sensíveis da saída da ferramenta antes que o agente os veja. ### Namespaces -Toda política reside em um slot `/`. As políticas integradas pertencem ao -namespace **`failproofai/`** — por exemplo, `failproofai/sanitize-jwt`. O -namespace evita colisões quando você também carrega políticas personalizadas ou de terceiros -com nomes curtos semelhantes. +Cada política vive em um slot `/`. As políticas integradas pertencem ao namespace **`failproofai/`** — por exemplo, `failproofai/sanitize-jwt`. O namespace previne colisões quando você também carrega políticas personalizadas ou de terceiros com nomes curtos similares. -Em sua configuração, você pode referenciar uma política integrada pelo nome curto ou pelo -nome qualificado; ambas as formas resolvem para a mesma política: +Na sua configuração, você pode referenciar uma política integrada pelo nome curto ou pelo nome qualificado; ambas as formas resolvem para a mesma política: ```json { @@ -48,22 +44,20 @@ nome qualificado; ambas as formas resolvem para a mesma política: } ``` -Se um nome não contiver `/`, o failproofai o trata como pertencente ao namespace padrão -`failproofai`. Nomes que já contêm `/` (ex.: `myorg/foo`, -`custom/my-hook`) são mantidos como estão. +Se um nome não contém `/`, o failproofai o trata como pertencente ao namespace padrão `failproofai`. Nomes que já contêm `/` (ex.: `myorg/foo`, `custom/my-hook`) são mantidos como estão. - **`require-`** — bloqueia o evento Stop até que as condições sejam atendidas. --- -Toda política suporta um campo opcional `hint` em `policyParams`. O hint é anexado à mensagem de deny ou instruct que Claude recebe, fornecendo orientações práticas sem modificar o código da política. Funciona com políticas integradas, personalizadas e de convenção. Veja [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para detalhes. +Toda política suporta um campo opcional `hint` em `policyParams`. O hint é anexado à mensagem de deny ou instruct que o Claude vê, fornecendo orientação prática sem modificar o código da política. Funciona com políticas integradas, personalizadas e de convenção. Veja [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para detalhes. --- ## Comandos perigosos -Impede agentes de executar operações difíceis de desfazer ou que possam danificar o sistema hospedeiro. +Impede agentes de executar operações difíceis de desfazer ou que possam danificar o sistema host. ### `block-sudo` @@ -93,7 +87,7 @@ Bloqueia invocações que incluem a palavra-chave `sudo`. A correspondência de Com esta configuração, `sudo systemctl status nginx` é permitido, mas `sudo rm /etc/hosts` é negado. -Os padrões são comparados com tokens analisados, não com a string de comando bruta. Isso evita bypass via operadores shell anexados (ex.: `sudo systemctl status x; rm -rf /` não corresponde a `sudo systemctl status *`). +Os padrões são comparados com tokens analisados, não com a string de comando bruta. Isso previne bypass via operadores shell anexados (ex.: `sudo systemctl status x; rm -rf /` não corresponde a `sudo systemctl status *`). --- @@ -101,13 +95,13 @@ Os padrões são comparados com tokens analisados, não com a string de comando ### `block-rm-rf` **Evento:** PreToolUse (Bash) -**Padrão:** Nega `rm -rf`, `rm -fr` e formas semelhantes de exclusão recursiva. +**Padrão:** Nega `rm -rf`, `rm -fr`, e formas similares de exclusão recursiva. **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Caminhos que são seguros para excluir recursivamente (ex.: `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Caminhos seguros para exclusão recursiva (ex.: `/tmp`). | **Exemplo:** @@ -126,7 +120,7 @@ Os padrões são comparados com tokens analisados, não com a string de comando ### `block-curl-pipe-sh` **Evento:** PreToolUse (Bash) -**Padrão:** Nega `curl | bash`, `curl | sh`, `wget | bash` e padrões semelhantes. +**Padrão:** Nega `curl | bash`, `curl | sh`, `wget | bash`, e padrões similares. Sem parâmetros. @@ -135,7 +129,7 @@ Sem parâmetros. ### `block-failproofai-commands` **Evento:** PreToolUse (Bash) -**Padrão:** Nega comandos que desinstalariam ou desativariam o próprio failproofai (ex.: `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Padrão:** Nega comandos que desinstalariam ou desabilitariam o próprio failproofai (ex.: `npm uninstall failproofai`, `failproofai policies --uninstall`). Sem parâmetros. @@ -143,9 +137,9 @@ Sem parâmetros. ## Comandos de infraestrutura -Impede agentes de codificação de executar CLIs de infraestrutura ou acionar pipelines de CI/CD. Todas as políticas nesta categoria são **opt-in** (`defaultEnabled: false`) — agentes que legitimamente precisam chamar `kubectl`, `terraform`, etc. não serão afetados, a menos que você habilite a política. Quando habilitada, cada invocação do CLI correspondente é negada, a menos que o comando corresponda a uma entrada em `allowPatterns`. +Impede agentes de codificação de executar CLIs de infraestrutura ou acionar pipelines de CI/CD. Todas as políticas nesta categoria são **opt-in** (`defaultEnabled: false`) — agentes que legitimamente precisam chamar `kubectl`, `terraform`, etc. não serão afetados a menos que você habilite a política. Quando habilitada, toda invocação da CLI correspondente é negada, a menos que o comando corresponda a uma entrada em `allowPatterns`. -A gramática de padrões é a mesma de [`block-sudo`](#block-sudo): os tokens são comparados com argv analisado, `*` é um caractere curinga para um token, e qualquer comando contendo um operador shell isolado (`&&`, `||`, `|`, `;`) ou um token com metacaracteres shell embutidos é rejeitado antes da verificação da lista de permissões para evitar bypasses por injeção. +A gramática de padrões é a mesma de [`block-sudo`](#block-sudo): os tokens são comparados com argv analisado, `*` é um curinga para um token, e qualquer comando contendo um operador shell autônomo (`&&`, `||`, `|`, `;`) ou um token com metacaracteres shell embutidos é rejeitado antes da correspondência da lista de permissões para evitar bypasses de injeção. ### `block-kubectl` @@ -202,13 +196,13 @@ Com esta configuração, `kubectl get pods` é permitido, mas `kubectl apply -f ### `block-aws-cli` **Evento:** PreToolUse (Bash) -**Padrão:** Nega qualquer invocação do CLI `aws`. +**Padrão:** Nega qualquer invocação da CLI `aws`. **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefixos de comandos do CLI aws que são permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefixos de comandos da CLI aws que são permitidos. | **Exemplo:** @@ -227,7 +221,7 @@ Com esta configuração, `kubectl get pods` é permitido, mas `kubectl apply -f ### `block-gcloud` **Evento:** PreToolUse (Bash) -**Padrão:** Nega qualquer invocação do CLI `gcloud` (Google Cloud). +**Padrão:** Nega qualquer invocação da CLI `gcloud` (Google Cloud). **Parâmetros:** @@ -252,13 +246,13 @@ Com esta configuração, `kubectl get pods` é permitido, mas `kubectl apply -f ### `block-az-cli` **Evento:** PreToolUse (Bash) -**Padrão:** Nega qualquer invocação do CLI `az` (Azure). +**Padrão:** Nega qualquer invocação da CLI `az` (Azure). **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefixos de comandos do CLI az que são permitidos. | +| `allowPatterns` | `string[]` | `[]` | Prefixos de comandos da CLI az que são permitidos. | **Exemplo:** @@ -302,7 +296,7 @@ Com esta configuração, `kubectl get pods` é permitido, mas `kubectl apply -f ### `block-gh-pipeline` **Evento:** PreToolUse (Bash) -**Padrão:** Nega os seguintes subcomandos do CLI `gh` que alteram estado ou acionam pipelines: +**Padrão:** Nega os seguintes subcomandos da CLI `gh` que mutam estado ou acionam pipelines: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -311,13 +305,13 @@ Com esta configuração, `kubectl get pods` é permitido, mas `kubectl apply -f - `gh cache delete` - `gh secret set`, `gh secret delete` -Subcomandos `gh` somente leitura, como `gh pr view`, `gh pr list`, `gh run list`, `gh release view` e `gh api repos/.../...`, **não** são abrangidos por esta política — eles são rotineiramente necessários para verificações de fluxo de trabalho (incluindo o próprio `require-ci-green-before-stop` do failproofai). +Subcomandos `gh` somente leitura, como `gh pr view`, `gh pr list`, `gh run list`, `gh release view`, e `gh api repos/.../...`, **não** são correspondidos por esta política — eles são rotineiramente necessários para verificações de fluxo de trabalho (incluindo o próprio `require-ci-green-before-stop` do failproofai). **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Invocações específicas com script para permitir mesmo que normalmente seriam negadas. | +| `allowPatterns` | `string[]` | `[]` | Invocações específicas com script a serem permitidas mesmo que normalmente seriam negadas. | **Exemplo:** @@ -335,7 +329,7 @@ Subcomandos `gh` somente leitura, como `gh pr view`, `gh pr list`, `gh run list` ## Segredos (sanitizadores) -Impede agentes de vazar credenciais em seu contexto ou saída. As políticas de sanitização são acionadas em eventos **PostToolUse**. Quando Claude executa um comando Bash, lê um arquivo ou chama qualquer ferramenta, essas políticas inspecionam a saída antes que ela seja retornada ao Claude. Se um padrão de segredo for detectado, a política retorna uma decisão de deny que impede que a saída seja repassada. +Impede agentes de vazar credenciais em seu contexto ou saída. As políticas de sanitização são acionadas em eventos **PostToolUse**. Quando o Claude executa um comando Bash, lê um arquivo ou chama qualquer ferramenta, essas políticas inspecionam a saída antes que ela seja retornada ao Claude. Se um padrão de segredo for detectado, a política retorna uma decisão de deny que impede a saída de ser repassada. ### `sanitize-jwt` @@ -349,7 +343,7 @@ Sem parâmetros. ### `sanitize-api-keys` **Evento:** PostToolUse (todas as ferramentas) -**Padrão:** Redige formatos comuns de chaves de API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), chaves de acesso AWS (`AKIA`), chaves Stripe (`sk_live_`, `sk_test_`) e chaves de API do Google (`AIza`). +**Padrão:** Redige formatos comuns de chaves de API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), chaves de acesso AWS (`AKIA`), chaves Stripe (`sk_live_`, `sk_test_`), e chaves de API do Google (`AIza`). **Parâmetros:** @@ -408,9 +402,9 @@ Protege configurações de ambiente sensíveis de serem lidas ou expostas por ag ### `block-env-files` **Evento:** PreToolUse (Bash, Read) -**Padrão:** Nega a leitura de arquivos `.env` via `cat .env`, chamadas da ferramenta `Read` com `.env` como caminho do arquivo, etc. +**Padrão:** Nega a leitura de arquivos `.env` via `cat .env`, chamadas da ferramenta `Read` com `.env` como caminho de arquivo, etc. -Não bloqueia `.envrc` ou outros arquivos relacionados ao ambiente — apenas arquivos nomeados exatamente `.env`. +Não bloqueia `.envrc` ou outros arquivos relacionados a ambiente — somente arquivos com o nome exato `.env`. Sem parâmetros. @@ -419,7 +413,7 @@ Sem parâmetros. ### `protect-env-vars` **Evento:** PreToolUse (Bash) -**Padrão:** Nega comandos que exibem variáveis de ambiente: `printenv`, `env`, `echo $VAR`. +**Padrão:** Nega comandos que imprimem variáveis de ambiente: `printenv`, `env`, `echo $VAR`. Sem parâmetros. @@ -432,13 +426,13 @@ Mantém os agentes trabalhando dentro dos limites do projeto e longe de arquivos ### `block-read-outside-cwd` **Evento:** PreToolUse (Read, Bash) -**Padrão:** Nega a leitura de arquivos fora do diretório raiz do projeto. O limite é definido por `CLAUDE_PROJECT_DIR` (definido uma vez por sessão pelo Claude Code), com fallback para o diretório de trabalho atual da sessão quando essa variável não está definida. Usar a raiz do projeto em vez do `cwd` ativo significa que o limite permanece estável mesmo depois que Claude entra em um subdiretório com `cd`. +**Padrão:** Nega a leitura de arquivos fora da raiz do projeto. O limite é `CLAUDE_PROJECT_DIR` (definido uma vez por sessão pelo Claude Code), com fallback para o diretório de trabalho atual da sessão quando essa variável não está definida. Usar a raiz do projeto em vez do `cwd` ativo significa que o limite permanece estável mesmo após o Claude fazer `cd` para um subdiretório. **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Prefixos de caminhos absolutos que são permitidos mesmo se estiverem fora da raiz do projeto. | +| `allowPaths` | `string[]` | `[]` | Prefixos de caminho absoluto que são permitidos mesmo que estejam fora da raiz do projeto. | **Exemplo:** @@ -457,13 +451,13 @@ Mantém os agentes trabalhando dentro dos limites do projeto e longe de arquivos ### `block-secrets-write` **Evento:** PreToolUse (Write, Edit) -**Padrão:** Nega gravações em arquivos comumente usados para chaves privadas e certificados: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Padrão:** Nega escritas em arquivos comumente usados para chaves privadas e certificados: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | Padrões de nome de arquivo adicionais (estilo glob) para bloquear. | +| `additionalPatterns` | `string[]` | `[]` | Padrões de nome de arquivo adicionais (estilo glob) a serem bloqueados. | **Exemplo:** @@ -481,7 +475,7 @@ Mantém os agentes trabalhando dentro dos limites do projeto e longe de arquivos ## Git -Previne pushes acidentais, force-pushes e erros de branch que são difíceis de desfazer. +Previne pushes acidentais, force-pushes e erros de branch difíceis de desfazer. ### `block-push-master` @@ -492,7 +486,7 @@ Previne pushes acidentais, force-pushes e erros de branch que são difíceis de | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Nomes de branches para os quais não é possível fazer push diretamente. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Nomes de branches que não podem receber push diretamente. | **Exemplo:** @@ -507,7 +501,7 @@ Previne pushes acidentais, force-pushes e erros de branch que são difíceis de ``` -Para permitir push em todas as branches (desabilitando efetivamente esta política sem removê-la de `enabledPolicies`), defina `protectedBranches: []`. +Para permitir push em todos os branches (desabilitando efetivamente esta política sem removê-la de `enabledPolicies`), defina `protectedBranches: []`. --- @@ -515,7 +509,7 @@ Para permitir push em todas as branches (desabilitando efetivamente esta políti ### `block-work-on-main` **Evento:** PreToolUse (Bash) -**Padrão:** Nega `git commit`, `git merge`, `git rebase` e `git cherry-pick` enquanto a árvore de trabalho está em `main` ou `master`. A criação e troca de branches (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) não são afetadas. +**Padrão:** Nega `git commit`, `git merge`, `git rebase`, e `git cherry-pick` enquanto a árvore de trabalho está em `main` ou `master`. Criação e troca de branches (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) não são afetados. **Parâmetros:** @@ -530,7 +524,7 @@ Para permitir push em todas as branches (desabilitando efetivamente esta políti **Evento:** PreToolUse (Bash) **Padrão:** Nega `git push --force` e `git push -f`. -Sem parâmetros específicos da política. Use o [`hint`](/pt-br/configuration#hint-cross-cutting) transversal para sugerir alternativas: +Sem parâmetros específicos de política. Use o [`hint`](/pt-br/configuration#hint-cross-cutting) transversal para sugerir alternativas: ```json { @@ -547,7 +541,7 @@ Sem parâmetros específicos da política. Use o [`hint`](/pt-br/configuration#h ### `warn-git-amend` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui Claude a proceder com cuidado ao executar `git commit --amend`. Não bloqueia o comando. +**Padrão:** Instrui o Claude a prosseguir com cuidado ao executar `git commit --amend`. Não bloqueia o comando. Sem parâmetros. @@ -556,7 +550,7 @@ Sem parâmetros. ### `warn-git-stash-drop` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui Claude a confirmar antes de executar `git stash drop`. Não bloqueia o comando. +**Padrão:** Instrui o Claude a confirmar antes de executar `git stash drop`. Não bloqueia o comando. Sem parâmetros. @@ -565,7 +559,7 @@ Sem parâmetros. ### `warn-all-files-staged` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui Claude a revisar o que está sendo preparado ao executar `git add -A` ou `git add .`. Não bloqueia o comando. +**Padrão:** Instrui o Claude a revisar o que está sendo adicionado ao stage quando executa `git add -A` ou `git add .`. Não bloqueia o comando. Sem parâmetros. @@ -573,12 +567,12 @@ Sem parâmetros. ## Banco de dados -Detecta operações SQL destrutivas antes que sejam executadas no seu banco de dados. +Detecta operações SQL destrutivas antes que sejam executadas no banco de dados. ### `warn-destructive-sql` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui Claude a confirmar antes de executar SQL contendo `DROP TABLE`, `DROP DATABASE` ou `DELETE` sem uma cláusula `WHERE`. +**Padrão:** Instrui o Claude a confirmar antes de executar SQL contendo `DROP TABLE`, `DROP DATABASE`, ou `DELETE` sem uma cláusula `WHERE`. Sem parâmetros. @@ -587,7 +581,7 @@ Sem parâmetros. ### `warn-schema-alteration` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui Claude a confirmar antes de executar instruções `ALTER TABLE`. +**Padrão:** Instrui o Claude a confirmar antes de executar instruções `ALTER TABLE`. Sem parâmetros. @@ -595,18 +589,18 @@ Sem parâmetros. ## Avisos -Fornece contexto adicional aos agentes antes de operações potencialmente arriscadas, mas não destrutivas. +Fornece contexto extra aos agentes antes de operações potencialmente arriscadas, mas não destrutivas. ### `warn-large-file-write` **Evento:** PreToolUse (Write) -**Padrão:** Instrui Claude a confirmar antes de gravar arquivos maiores que 1024 KB. +**Padrão:** Instrui o Claude a confirmar antes de escrever arquivos maiores que 1024 KB. **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | Limite de tamanho do arquivo em kilobytes acima do qual um aviso é emitido. | +| `thresholdKb` | `number` | `1024` | Limite de tamanho de arquivo em kilobytes acima do qual um aviso é emitido. | **Exemplo:** @@ -621,7 +615,7 @@ Fornece contexto adicional aos agentes antes de operações potencialmente arris ``` -O handler do hook impõe um limite de 1 MB no stdin para payloads. Para testar esta política com conteúdo pequeno, defina `thresholdKb` com um valor bem abaixo de 1024. +O handler do hook impõe um limite de 1 MB no stdin para payloads. Para testar esta política com conteúdo pequeno, defina `thresholdKb` para um valor bem abaixo de 1024. --- @@ -629,7 +623,7 @@ O handler do hook impõe um limite de 1 MB no stdin para payloads. Para testar e ### `warn-package-publish` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui Claude a confirmar antes de executar `npm publish`. +**Padrão:** Instrui o Claude a confirmar antes de executar `npm publish`. Sem parâmetros. @@ -638,7 +632,7 @@ Sem parâmetros. ### `warn-background-process` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui Claude a ter cuidado ao iniciar processos em segundo plano via `nohup`, `&`, `disown` ou `screen`. +**Padrão:** Instrui o Claude a ter cuidado ao iniciar processos em segundo plano via `nohup`, `&`, `disown`, ou `screen`. Sem parâmetros. @@ -647,7 +641,7 @@ Sem parâmetros. ### `warn-global-package-install` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui Claude a confirmar antes de executar `npm install -g`, `yarn global add` ou `pip install` sem um ambiente virtual. +**Padrão:** Instrui o Claude a confirmar antes de executar `npm install -g`, `yarn global add`, ou `pip install` sem um ambiente virtual. Sem parâmetros. @@ -655,21 +649,21 @@ Sem parâmetros. ## Gerenciadores de pacotes -Impõe quais gerenciadores de pacotes o agente tem permissão para usar. +Define quais gerenciadores de pacotes o agente está autorizado a usar. ### `prefer-package-manager` **Evento:** PreToolUse (Bash) -**Padrão:** Desabilitado. Quando habilitado, bloqueia qualquer comando de gerenciador de pacotes que não esteja na lista `allowed` e instrui Claude a reescrever o comando usando um gerenciador permitido. +**Padrão:** Desabilitado. Quando habilitado, bloqueia qualquer comando de gerenciador de pacotes que não esteja na lista `allowed` e instrui o Claude a reescrever o comando usando um gerenciador permitido. Detecta: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | Parâmetro | Tipo | Padrão | Descrição | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | Nomes de gerenciadores de pacotes permitidos. Qualquer gerenciador detectado que não esteja nesta lista é bloqueado. Quando vazio, a política não tem efeito. | -| `blocked` | string[] | `[]` | Nomes de gerenciadores adicionais para bloquear além da lista integrada (ex.: `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | Nomes de gerenciadores de pacotes permitidos. Qualquer gerenciador detectado que não esteja nesta lista é bloqueado. Quando vazia, a política é uma no-op. | +| `blocked` | string[] | `[]` | Nomes de gerenciadores adicionais a serem bloqueados além da lista integrada (ex.: `['pdm', 'pipx']`). | -A lista de bloqueio integrada inclui: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Use `blocked` para adicionar gerenciadores não presentes nesta lista. +A lista de bloqueio integrada cobre: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Use `blocked` para adicionar gerenciadores que não estão nesta lista. **Exemplo de configuração:** @@ -685,7 +679,7 @@ A lista de bloqueio integrada inclui: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun } ``` -Com esta configuração, `pip install flask` e `pdm install flask` são ambos negados com uma mensagem instruindo Claude a usar `uv` ou `bun`. Comandos como `uv pip install flask` são permitidos porque `uv` está na lista de permissões e é verificado primeiro. +Com esta configuração, `pip install flask` e `pdm install flask` são ambos negados com uma mensagem instruindo o Claude a usar `uv` ou `bun`. Comandos como `uv pip install flask` são permitidos porque `uv` está na lista de permissões e é verificado primeiro. --- @@ -696,7 +690,7 @@ Detecta quando agentes ficam presos ou se comportam de forma inesperada. ### `warn-repeated-tool-calls` **Evento:** PreToolUse (todas as ferramentas) -**Padrão:** Instrui Claude a reconsiderar quando a mesma ferramenta é chamada 3 ou mais vezes com parâmetros idênticos — um sinal comum de que o agente está preso em um loop. +**Padrão:** Instrui o Claude a reconsiderar quando a mesma ferramenta é chamada 3 ou mais vezes com parâmetros idênticos — um sinal comum de que o agente está preso em um loop. Sem parâmetros. @@ -704,40 +698,40 @@ Sem parâmetros. ## Fluxo de trabalho -Impõe um fluxo de trabalho disciplinado ao final da sessão. Essas políticas são acionadas no evento **Stop** e negam ao agente a possibilidade de parar até que cada condição seja atendida. Elas seguem uma cadeia de dependência natural: commit → push → PR → CI. Se uma política negar, as políticas posteriores na cadeia são ignoradas (negação causa curto-circuito). +Impõe um fluxo de trabalho disciplinado ao fim da sessão. Estas políticas são acionadas no evento **Stop** e negam ao agente a possibilidade de parar até que cada condição seja atendida. Elas seguem uma cadeia de dependência natural: commit → push → PR → CI. Se uma política negar, as políticas posteriores na cadeia são ignoradas (deny provoca curto-circuito). Todas as políticas de fluxo de trabalho são **fail-open**: se a ferramenta necessária não estiver disponível (ex.: `gh` não instalado, sem remote git), a política permite com uma mensagem informativa explicando por que a verificação foi ignorada. ### Semântica de Stop por CLI -A aplicação do Stop funciona de forma ligeiramente diferente entre os sete CLIs suportados, pois cada um expõe um contrato de hook de "agente finalizado" diferente. O **resultado** é o mesmo — o agente não consegue parar enquanto uma condição de fluxo de trabalho estiver falhando — mas a **mecânica** difere. A tabela abaixo resume; apenas o Pi tem uma peculiaridade visível ao usuário que vale entender antes de habilitar uma política `require-*-before-stop`. +A aplicação de Stop funciona de forma ligeiramente diferente entre os sete CLIs suportados, pois cada um expõe um contrato de hook diferente para "agente finalizado". O **resultado** é o mesmo — o agente não consegue parar enquanto um gate de fluxo de trabalho estiver falhando — mas a **mecânica** difere. A tabela abaixo resume; apenas o Pi tem uma peculiaridade visível ao usuário que vale entender antes de habilitar uma política `require-*-before-stop`. | CLI | Quando o gate é acionado | O que você vê | |---|---|---| -| Claude Code | No mesmo loop do agente, imediatamente | Claude continua trabalhando — corrige o problema e então tenta finalizar novamente. Nenhuma interrupção visível para você. | +| Claude Code | No mesmo loop do agente, imediatamente | O Claude continua trabalhando — corrige o problema e então tenta finalizar novamente. Nenhuma interrupção visível para você. | | Codex | No mesmo loop do agente, imediatamente | Igual ao Claude. | -| GitHub Copilot CLI | No mesmo loop do agente, imediatamente | Igual ao Claude (usa o canal de retry `{decision:"block", reason}` do Copilot — verificado empiricamente contra o Copilot CLI 1.0.41). | -| Cursor Agent | No mesmo loop do agente, imediatamente | Igual ao Claude (usa o canal `{followup_message}` do Cursor — limitado por `loop_limit`, padrão de 5 tentativas). | +| GitHub Copilot CLI | No mesmo loop do agente, imediatamente | Igual ao Claude (usa o canal de retry `{decision:"block", reason}` do Copilot — verificado empiricamente no Copilot CLI 1.0.41). | +| Cursor Agent | No mesmo loop do agente, imediatamente | Igual ao Claude (usa o canal `{followup_message}` do Cursor — limitado ao `loop_limit`, padrão 5 tentativas). | | Gemini CLI | No mesmo loop do agente, imediatamente | Igual ao Claude (usa o canal `{decision:"block", reason}` do Gemini em `AfterAgent`). | -| OpenCode | No mesmo loop do agente, imediatamente | Igual ao Claude (usa a chamada SDK `client.session.prompt(...)` do OpenCode roteada via `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **Próximo turno do usuário** | **Pi para visivelmente** quando o gate é acionado — seu loop de agente encerra e você retorna ao prompt. O gate então é acionado na próxima vez que você envia um prompt: o failproofai prefixa uma diretiva `MANDATORY ACTION REQUIRED` ao system prompt daquele turno, instruindo o LLM a concluir a etapa do fluxo de trabalho (commit, push, etc.) antes de fazer o que você pediu. | +| OpenCode | No mesmo loop do agente, imediatamente | Igual ao Claude (usa a chamada SDK `client.session.prompt(...)` do OpenCode roteada através de `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **Próximo turno do usuário** | **O Pi para visivelmente** quando o gate é acionado — seu loop de agente sai e você retorna ao prompt. O gate é então acionado na próxima vez que você enviar um prompt: o failproofai antepõe uma diretiva `MANDATORY ACTION REQUIRED` ao prompt do sistema daquele turno, instruindo o LLM a concluir a etapa do fluxo de trabalho (commit, push, etc.) antes de fazer o que você pediu. | -**Limitação do Pi.** O `AgentEndEvent` do Pi (equivalente ao hook `Stop` do Claude no upstream) não possui tipo Result — quando ele é acionado, o loop do agente do Pi já encerrou. O Pi não pode ser forçado a tentar novamente o mesmo loop como Claude / Copilot / Cursor / Gemini / OpenCode. O failproofai desloca o gate para o evento `before_agent_start` do Pi (que é acionado após o próximo prompt do usuário), de modo que a verificação do fluxo de trabalho ainda é aplicada, apenas no próximo turno em vez do atual. +**Limitação do Pi.** O `AgentEndEvent` do Pi (o equivalente upstream do hook `Stop` do Claude) não tem tipo Result — quando ele é acionado, o loop do agente do Pi já saiu. O Pi não pode ser forçado a repetir o mesmo loop da forma que Claude / Copilot / Cursor / Gemini / OpenCode podem. O failproofai desloca o gate para o evento `before_agent_start` do Pi (que é acionado após o próximo prompt do usuário), para que a verificação do fluxo de trabalho ainda seja aplicada, apenas no próximo turno em vez do atual. **O que isso significa na prática:** -- Após o Pi parar, o motivo da negação é capturado em memória, indexado pelo id de sessão do Pi. O próximo prompt que você enviar no mesmo processo Pi o consome: o LLM vê a diretiva `MANDATORY ACTION REQUIRED` no topo de seu system prompt, faz o commit (ou push / abre o PR / aguarda o CI) e só então continua com sua solicitação. O motivo da negação capturado é de uso único — após ser consumido, o gate é liberado. -- O gate é limitado ao tempo de vida do processo Pi. Se você pressionar `Ctrl+C` no Pi ou sair entre os turnos, a entrada em memória é descartada junto com o processo e o gate é perdido. Claude, Copilot, Cursor, Gemini e OpenCode têm o mesmo comportamento (encerrar o agente faz o gate ser perdido) — o Pi apenas o torna mais visível porque o agente encerra visivelmente antes de o gate ser acionado. -- Uma negação pendente também é apagada em `session_shutdown` por qualquer motivo (`new` / `resume` / `fork` / `quit`), então um gate obsoleto de uma sessão anterior não pode vazar para uma nova sessão iniciada no mesmo processo Pi. +- Após o Pi parar, o motivo da negação é capturado na memória, indexado pelo ID de sessão do Pi. O próximo prompt que você enviar no mesmo processo do Pi o consome: o LLM vê a diretiva `MANDATORY ACTION REQUIRED` no topo de seu prompt de sistema, faz o commit (ou push / abre o PR / aguarda o CI), e só então continua com sua solicitação. O motivo de negação capturado é de uso único — uma vez consumido, o gate é liberado. +- O gate é limitado ao tempo de vida do processo do Pi. Se você der `Ctrl+C` no Pi ou sair entre turnos, a entrada na memória é descartada junto com o processo e o gate é perdido. Claude, Copilot, Cursor, Gemini e OpenCode têm o mesmo limite (matar o agente faz o gate ser perdido) — o Pi apenas torna isso mais visível porque o agente sai visivelmente antes do gate ser acionado. +- Uma negação pendente também é limpa no `session_shutdown` por qualquer motivo (`new` / `resume` / `fork` / `quit`), então um gate obsoleto de uma sessão anterior não pode vazar para uma nova sessão iniciada no mesmo processo do Pi. -Se você precisar do retry no mesmo loop ao estilo Claude, execute suas políticas `Stop` em qualquer um dos outros seis CLIs suportados. Estamos acompanhando o Pi upstream em busca de um futuro tipo Result em `AgentEndEvent` que nos permita fechar essa lacuna. +Se você precisar do retry no mesmo loop no estilo Claude, execute suas políticas `Stop` em qualquer um dos outros seis CLIs suportados. Estamos acompanhando o upstream do Pi para um futuro tipo Result no `AgentEndEvent` que nos permitiria fechar essa lacuna. ### `require-commit-before-stop` **Evento:** Stop -**Padrão:** Nega a parada quando há alterações não commitadas (arquivos modificados, preparados ou não rastreados). Retorna uma mensagem informativa quando o diretório de trabalho está limpo. +**Padrão:** Nega a parada quando há alterações não commitadas (arquivos modificados, staged ou não rastreados). Retorna uma mensagem informativa quando o diretório de trabalho está limpo. Sem parâmetros. @@ -746,7 +740,7 @@ Sem parâmetros. ### `require-push-before-stop` **Evento:** Stop -**Padrão:** Nega a parada quando há commits não enviados ou quando a branch atual não possui branch de rastreamento remoto. Sugere `git push -u` para criar uma branch de rastreamento, se necessário. Falha abertamente se nenhum remote estiver configurado. +**Padrão:** Nega a parada quando há commits não enviados ou quando o branch atual não tem um branch de rastreamento remoto. Sugere `git push -u` para criar um branch de rastreamento, se necessário. Falha de forma aberta se nenhum remote estiver configurado. **Parâmetros:** @@ -771,14 +765,13 @@ Sem parâmetros. ### `require-pr-before-stop` **Evento:** Stop -**Padrão:** Nega a parada quando não existe pull request para a branch atual, ou quando o PR existente está fechado sem merge. Instrui Claude a criar um PR com `gh pr create`. Quando o PR é **mergeado**, a política permite (o trabalho foi entregue) e a mensagem sugere sair da branch (`git checkout main && git pull`). +**Padrão:** Nega a parada quando não existe pull request para o branch atual, ou quando o PR existente está fechado sem merge. Instrui o Claude a criar um PR com `gh pr create`. Quando o PR está **merged**, a política permite (o trabalho foi entregue) e a mensagem sugere sair do branch (`git checkout main && git pull`). Sem parâmetros. -Esta política requer a instalação e autenticação do [GitHub CLI](https://cli.github.com/) (`gh`). -Execute `gh auth login` com um personal access token que tenha escopo `repo` para acesso de leitura a -pull requests. Se `gh` não estiver instalado ou autenticado, a política falha abertamente e informa o motivo ao Claude. +Esta política requer que o [GitHub CLI](https://cli.github.com/) (`gh`) esteja instalado e autenticado. +Execute `gh auth login` com um token de acesso pessoal que tenha o escopo `repo` para acesso de leitura a pull requests. Se `gh` não estiver instalado ou não estiver autenticado, a política falha de forma aberta e reporta o motivo ao Claude. --- @@ -786,12 +779,12 @@ pull requests. Se `gh` não estiver instalado ou autenticado, a política falha ### `require-no-conflicts-before-stop` **Evento:** Stop -**Padrão:** Nega a parada quando a branch atual não pode ser mergeada de forma limpa na branch base. A política primeiro confirma que há um PR `OPEN` no GitHub para a branch — sem ele, não há destino de merge para impor, então toda a política causa curto-circuito para allow. Uma vez confirmado um PR `OPEN`, duas sondagens independentes são executadas: +**Padrão:** Nega a parada quando o branch atual não pode ser mesclado de forma limpa no branch base. A política primeiro confirma se há um PR `OPEN` no GitHub para o branch — sem um, não há alvo de merge a aplicar, então toda a política provoca curto-circuito para allow. Uma vez confirmado um PR `OPEN`, duas sondagens independentes são executadas: -1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`. Em caso de conflito, a mensagem de deny lista os arquivos conflitantes para que Claude saiba exatamente o que resolver. -2. **GitHub** — reutiliza o resultado de `gh pr view --json mergeable,state` já obtido na pré-verificação. Detecta conflitos que um `origin/` local desatualizado perderia (ex.: alguém fez merge de um PR conflitante em `main` desde o último fetch). Um resultado `CONFLICTING` nega. Um resultado `UNKNOWN` também nega e instrui Claude a aguardar ~10 segundos e verificar novamente antes de tentar parar — isso evita falsos negativos enquanto o GitHub recalcula. +1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`. Em caso de conflito, a mensagem de deny nomeia os arquivos em conflito para que o Claude saiba exatamente o que resolver. +2. **GitHub** — reutiliza o resultado de `gh pr view --json mergeable,state` já obtido na verificação prévia. Detecta conflitos que um `origin/` local desatualizado perderia (ex.: alguém lançou um PR conflitante em `main` desde o último fetch). Um resultado `CONFLICTING` nega. Um resultado `UNKNOWN` também nega e instrui o Claude a aguardar ~10 segundos e verificar novamente antes de tentar parar — isso previne falsos negativos enquanto o GitHub recomputa. -Ignora completamente (permite) quando: `gh` não está instalado, não existe PR para a branch, o estado do PR não é `OPEN` (ex.: `MERGED`, `CLOSED`), ou `gh pr view` retorna saída não parseável. Também falha abertamente quando `origin/` está ausente localmente ou quando não há commits à frente da base — esses fallbacks da Camada 1 ainda consultam a mergeabilidade do PR em cache antes de permitir. +Ignora completamente (permite) quando: `gh` não está instalado, nenhum PR existe para o branch, o estado do PR não é `OPEN` (ex.: `MERGED`, `CLOSED`), ou `gh pr view` retorna saída não analisável. Também falha de forma aberta quando `origin/` está faltando localmente ou quando não há commits à frente do base — esses fall-throughs da Camada 1 ainda consultam a mesclabilidade do PR em cache antes de permitir. **Parâmetros:** @@ -800,10 +793,7 @@ Ignora completamente (permite) quando: `gh` não está instalado, não existe PR | `baseBranch` | `string` | `"main"` | Branch base para verificar conflitos. | -O GitHub CLI (`gh`) é necessário para esta política. A política usa `gh pr view` para confirmar -que existe um PR `OPEN` antes de executar qualquer sondagem de conflito — sem `gh`, a política -causa curto-circuito para allow. Execute `gh auth login` com um personal access token que tenha -escopo `repo` para acesso de leitura a pull requests. +O GitHub CLI (`gh`) é necessário para esta política. A política usa `gh pr view` para confirmar que um PR `OPEN` existe antes de executar qualquer sondagem de conflito — sem `gh`, a política provoca curto-circuito para allow. Execute `gh auth login` com um token de acesso pessoal que tenha o escopo `repo` para acesso de leitura a pull requests. --- @@ -811,14 +801,13 @@ escopo `repo` para acesso de leitura a pull requests. ### `require-ci-green-before-stop` **Evento:** Stop -**Padrão:** Nega a parada quando as verificações de CI estão falhando ou ainda em execução na branch atual. Verifica tanto as execuções de workflow do GitHub Actions quanto verificações de bots de terceiros (ex.: CodeRabbit, SonarCloud, Codecov). Trata as conclusões `skipped`, `cancelled` e `neutral` como não-falhas (esta última cobre, por exemplo, alertas do Socket Security em PRs de contribuidores externos, onde o app intencionalmente reporta neutro em vez de sucesso/falha). Retorna uma mensagem informativa quando todas as verificações passam. +**Padrão:** Nega a parada quando as verificações de CI estão falhando ou ainda em execução no branch atual. Verifica tanto execuções de workflow do GitHub Actions quanto verificações de bots de terceiros (ex.: CodeRabbit, SonarCloud, Codecov). Trata conclusões `skipped`, `cancelled` e `neutral` como não-falhando (o último cobre, por exemplo, alertas do Socket Security em PRs de contribuidores externos, onde o aplicativo intencionalmente reporta neutro em vez de sucesso/falha). Retorna uma mensagem informativa quando todas as verificações passam. Sem parâmetros. -Esta política requer a instalação e autenticação do [GitHub CLI](https://cli.github.com/) (`gh`). -Execute `gh auth login` com um personal access token que tenha escopo `repo` para acesso de leitura a -execuções de workflow do Actions e à API de Verificações. Se `gh` não estiver instalado ou autenticado, a política falha abertamente e informa o motivo ao Claude. +Esta política requer que o [GitHub CLI](https://cli.github.com/) (`gh`) esteja instalado e autenticado. +Execute `gh auth login` com um token de acesso pessoal que tenha o escopo `repo` para acesso de leitura a execuções de workflow do Actions e à API de Checks. Se `gh` não estiver instalado ou não estiver autenticado, a política falha de forma aberta e reporta o motivo ao Claude. --- @@ -827,7 +816,7 @@ execuções de workflow do Actions e à API de Verificações. Se `gh` não esti ## Desabilitando políticas individuais -Remova uma política específica de `enabledPolicies` em sua configuração, ou desative-a na aba Policies do painel. +Remova uma política específica de `enabledPolicies` na sua configuração, ou desative-a na aba Políticas do painel. ```json { @@ -838,4 +827,4 @@ Remova uma política específica de `enabledPolicies` em sua configuração, ou } ``` -Políticas não listadas em `enabledPolicies` não são executadas, mesmo que existam entradas em `policyParams` para elas. \ No newline at end of file +Políticas não listadas em `enabledPolicies` não são executadas, mesmo que existam entradas de `policyParams` para elas. \ No newline at end of file diff --git a/docs/pt-br/cli/audit.mdx b/docs/pt-br/cli/audit.mdx index 4c5db193..0886e980 100644 --- a/docs/pt-br/cli/audit.mdx +++ b/docs/pt-br/cli/audit.mdx @@ -1,22 +1,22 @@ --- title: Auditar sessões anteriores (beta) -description: "Conte quantas vezes o agente fez coisas desnecessárias ou arriscadas em transcrições passadas" +description: "Conte quantas vezes o agente fez coisas desnecessárias ou arriscadas em transcrições anteriores" --- - **Recurso beta.** A auditoria é lançada como beta enquanto coletamos feedback - inicial. O catálogo de detectores e o formato do relatório podem mudar antes - do próximo corte estável. Abra uma issue se algo parecer errado. + **Recurso beta.** O audit é disponibilizado em beta enquanto coletamos feedback inicial. + O catálogo de detectores e o formato do relatório podem mudar antes do próximo corte estável. + Abra uma issue se algo parecer errado. -A auditoria reproduz suas transcrições passadas do agente-CLI pelo motor de -políticas do failproofai e gera um relatório visual e compartilhável na **página -do dashboard `/audit`** — o arquétipo do seu agente, uma pontuação de 0 a 100 e -exatamente quais políticas teriam detectado o quê. +O audit reproduz suas transcrições anteriores do agente-CLI pelo motor de políticas do failproofai +e gera um relatório visual e compartilhável na **página `/audit` do dashboard** +— o arquétipo do seu agente, uma pontuação de 0 a 100, e exatamente quais políticas +teriam capturado o quê. -## Execute +## Executar -Três formas de entrar — todas levam ao mesmo relatório `/audit`. +Três formas de iniciar — todas levam ao mesmo relatório `/audit`. @@ -37,60 +37,60 @@ failproofai `npx -y failproofai audit` baixa o failproofai, executa a varredura e abre o - dashboard para você — sem nada para instalar antes. + dashboard automaticamente — sem necessidade de instalação prévia. `failproofai audit` executa a varredura no seu terminal e abre `localhost:8020/audit` automaticamente ao terminar. - Execute `failproofai` e clique em **Audit** na barra de navegação (entre - Policies e Projects), ou abra `/audit` diretamente. + Execute `failproofai` e clique em **Audit** na barra de navegação (entre Policies e + Projects), ou acesse `/audit` diretamente. - Execute `failproofai audit -h` (ou `--help`) para ver o uso. A auditoria roda - **totalmente offline** — sem necessidade de conta ou rede — e o dashboard - continua servindo até você encerrá-lo com `Ctrl+C`. + Execute `failproofai audit -h` (ou `--help`) para ver o uso. O audit roda **completamente + offline** — sem conta ou conexão à internet necessária — e o dashboard continua servindo + até você encerrá-lo com `Ctrl+C`. -O dashboard varre transcrições passadas do agente CLI nesta máquina (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) e reporta com que frequência o agente fez coisas que o failproofai foi criado para impedir — verificações de variáveis de ambiente, force pushes, prefixos redundantes `cd `, loops de sleep-polling, releitura de arquivos recém-editados e mais. +O dashboard varre transcrições anteriores do agente CLI nesta máquina (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) e relata com que frequência o agente fez coisas que o failproofai foi criado para impedir — verificações de variáveis de ambiente, force pushes, prefixos redundantes `cd `, loops de polling com sleep, releitura de arquivos recém-editados, e mais. -Para cada transcrição, cada evento de uso de ferramenta é reproduzido pelas 39 políticas embutidas **e** por 8 detectores exclusivos de auditoria que capturam padrões ainda não cobertos pelas políticas em tempo de execução. As contagens são agregadas por política/detector em todas as sessões. +Para cada transcrição, cada evento de uso de ferramenta é reproduzido pelas 39 políticas integradas **e** pelos 8 detectores exclusivos do audit que capturam padrões ainda não cobertos pelas políticas em tempo real. As contagens são agregadas por política/detector em todas as sessões. -## O que você obtém +## O que você recebe -A página `/audit` é um **pôster** de tela única e compartilhável seguido de quatro seções abaixo da dobra: +A página `/audit` é um **pôster** de tela única e compartilhável seguido por quatro seções abaixo da dobra: -1. **Pôster** — a identidade do seu agente de relance: seu **arquétipo** (um de 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), suas palavras-chave de persona, quão raro é esse arquétipo e uma **pontuação de 0 a 100** com uma faixa de nível (de `S` até `bottom tier`). Feito para compartilhar — poste no X ou LinkedIn, ou baixe como PNG. -2. **`// strengths`** — o que seu agente já faz bem, com números reais da varredura (ex.: % de chamadas de ferramentas limpas, `0` tentativas de push-to-main), exibido apenas onde a política relevante tem um histórico limpo. -3. **`// quirks`** — o que escapou: uma tabela classificada de comportamentos que o failproofai teria detectado — *quando* ocorreu pela última vez, *o que escapou* (e o embutido que teria bloqueado), sua *gravidade* e com que frequência foi *visto* (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — a lista de correções prescritas: uma linha por política com um `failproofai policy add ` para copiar e colar, além de um botão **install all** que ativa todas as recomendações de uma vez e mostra sua **pontuação projetada** caso você o faça. -5. **`// come back better`** — crie o hábito: configure um **lembrete** de reauditoria por e-mail (`3d` / `7d` / `14d` / `30d`) ou faça uma reauditoria agora, e **convide um amigo** para executar sua própria auditoria (enviado pelo failproof.ai, com cópia para você). Lembretes e convites exigem login — veja [`failproofai auth`](/pt-br/cli/auth). +1. **Pôster** — a identidade do seu agente em um relance: seu **arquétipo** (um dos 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), suas palavras-chave de persona, o quão raro é esse arquétipo, e uma **pontuação de 0 a 100** com uma faixa de classificação (`S` até `bottom tier`). Criado para compartilhar — poste no X ou no LinkedIn, ou baixe como PNG. +2. **`// strengths`** — o que seu agente já faz bem, com números reais da varredura (ex.: % de chamadas de ferramenta limpas, `0` tentativas de push para main), exibido apenas onde a política relevante tem um histórico limpo. +3. **`// quirks`** — o que escapou: uma tabela classificada de comportamentos que o failproofai teria capturado — *quando* aconteceu pela última vez, *o que escapou* (e o integrado que teria bloqueado), sua *severidade*, e com que frequência foi *visto* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — a lista de correções prescrita: uma linha por política com um `failproofai policy add ` para copiar e colar, mais um botão **install all** que habilita todas as recomendações de uma vez e mostra sua **pontuação projetada** se você fizesse isso. +5. **`// come back better`** — crie o hábito: defina um **lembrete** de reauditoria por e-mail (`3d` / `7d` / `14d` / `30d`) ou reaudite agora, e **convide um amigo** para rodar a própria auditoria (enviado de failproof.ai, com Cc para você). Lembretes e convites exigem login — veja [`failproofai auth`](/pt-br/cli/auth). -## Detectores exclusivos de auditoria +## Detectores exclusivos do audit -Estes detectam padrões de "comportamento ineficiente" que ainda não são aplicados em tempo real. Eles rodam apenas durante a auditoria e nunca bloqueiam uma chamada de ferramenta ao vivo. +Esses detectores capturam padrões de "comportamento ineficiente" ainda não aplicados em tempo real. Rodam apenas durante o audit e nunca bloqueiam uma chamada de ferramenta ao vivo. | Detector | O que conta | |---|---| | `redundant-cd-cwd` | Comandos Bash começando com `cd && …` mesmo que os comandos já rodem em `cwd`. | -| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` em um único arquivo-fonte — use a ferramenta `Read`. | -| `prefer-edit-over-sed-awk` | Edições no lugar com `sed -i` / `awk … > file` — use a ferramenta `Edit`. | +| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` em um único arquivo fonte — use a ferramenta `Read`. | +| `prefer-edit-over-sed-awk` | Edições in-place com `sed -i` / `awk … > file` — use a ferramenta `Edit`. | | `prefer-write-over-heredoc` | Heredoc / `echo > file` multilinha para escrever arquivos — use a ferramenta `Write`. | | `sleep-polling-loop` | `sleep N` longo (≥ 30s) ou loops de polling `while …; sleep …; done`. | -| `find-from-root` | `find /`, `find /home`, `find /usr`, etc. — limite ao `cwd`. | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, ignorando hooks. | +| `find-from-root` | `find /`, `find /home`, `find /usr`, etc. — limite ao escopo de `cwd`. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, pulando hooks. | | `reread-after-edit` | `Read` de um arquivo que acabou de ser `Edit`/`Write` na mesma sessão. | ## Caches -- **Cache por transcrição** em `~/.failproofai/cache/audit/.json` com chave por `(mtime, size, engineVersion, detectorVersion)` — invalida automaticamente quando a transcrição ou o código de política/detector muda. Cada entrada também armazena um timestamp `cachedAt` como **metadado TTL** (não faz parte da chave de cache); entradas mais antigas que **7 dias** são rejeitadas na leitura para que resultados de longa data não sobrevivam à evolução da intenção dos detectores. -- **Cache de resultado completo** em `~/.failproofai/audit-dashboard.json` (modo 0600). Permite que o dashboard renderize instantaneamente na navegação sem re-executar. Também rejeitado na leitura após o **TTL de 7 dias** — `/audit` então cai em seu estado vazio e solicita uma nova execução. Clique em `[ re-audit now ]` perto do final do relatório para atualizar — a reauditoria envia `noCache: true`, ignorando o cache por transcrição e revarrendo todas as transcrições em vez de retornar o resultado em cache; a execução transmite o progresso via uma faixa fixa no topo e substitui o resultado no lugar ao terminar com sucesso (sem recarregamento de página; uma reauditoria com falha mantém o relatório anterior). +- **Cache por transcrição** em `~/.failproofai/cache/audit/.json`, indexado por `(mtime, size, engineVersion, detectorVersion)` — invalida automaticamente quando a transcrição ou o código de política/detector muda. Cada entrada também armazena um timestamp `cachedAt` como **metadado de TTL** (não faz parte da chave do cache); entradas com mais de **7 dias** são rejeitadas na leitura para que resultados de longa duração não sobrevivam à evolução da intenção dos detectores. +- **Cache do resultado completo** em `~/.failproofai/audit-dashboard.json` (modo 0600). Permite que o dashboard renderize instantaneamente na navegação sem precisar rodar novamente. Também rejeitado na leitura após o **TTL de 7 dias** — `/audit` então cai em seu estado vazio e solicita uma nova execução. Clique em `[ re-audit now ]` perto do final do relatório para atualizar — o re-audit envia `noCache: true`, então ignora o cache por transcrição e reavarre todas as transcrições em vez de retornar o resultado em cache; a execução transmite o progresso via uma faixa fixa no topo e substitui o resultado no lugar ao ser concluída com sucesso (sem recarregamento de página; um re-audit com falha mantém o relatório anterior). ## Observações -- **Sem mutação.** A auditoria é reproduzida em modo somente leitura. `warn-repeated-tool-calls` é ignorado porque seu sidecar por sessão seria modificado de outra forma. -- **Políticas de fluxo de trabalho ignoradas.** As políticas `require-*-before-stop` disparam apenas em eventos `Stop` e `execSync` contra o estado git ao vivo — elas não têm uma interpretação significativa de "o que teria acontecido em 2025", portanto não aparecem nas contagens de auditoria. -- **Políticas personalizadas ignoradas.** Hooks personalizados fornecidos pelo usuário não são reproduzidos (eles podem ter mudado desde a sessão original). \ No newline at end of file +- **Sem mutação.** O audit é reproduzido em modo somente leitura. `warn-repeated-tool-calls` é ignorado porque seu sidecar por sessão seria modificado de outra forma. +- **Políticas de fluxo de trabalho ignoradas.** As políticas `require-*-before-stop` são acionadas apenas em eventos `Stop` e `execSync` contra o estado git atual — elas não têm uma interpretação significativa de "o que teria acontecido em 2025", portanto não aparecem nas contagens do audit. +- **Políticas personalizadas ignoradas.** Hooks customizados fornecidos pelo usuário não são reproduzidos (eles podem ter mudado desde a sessão original). \ No newline at end of file diff --git a/docs/pt-br/cli/auth.mdx b/docs/pt-br/cli/auth.mdx index f24aa3f0..0fe4532d 100644 --- a/docs/pt-br/cli/auth.mdx +++ b/docs/pt-br/cli/auth.mdx @@ -1,17 +1,17 @@ --- title: Entrar -description: "Entre no FailproofAI pela CLI para ativar lembretes e recursos personalizados" +description: "Faça login no FailproofAI pela CLI para ativar lembretes e recursos personalizados" --- ```bash -failproofai auth login # e-mail + código de uso único +failproofai auth login # email + código de uso único failproofai auth logout # revogar esta sessão -failproofai auth whoami # exibir a identidade conectada +failproofai auth whoami # exibir a identidade do usuário conectado ``` -A forma legada com flags `--login` / `--logout` / `--whoami` ainda é aceita como alias para compatibilidade com versões anteriores. +A forma legada com flags `--login` / `--logout` / `--whoami` ainda é aceita como alias para compatibilidade retroativa. -A autenticação é opcional. Políticas, o dashboard, a página `/audit` e todos os outros recursos locais funcionam exatamente da mesma forma, independentemente de você estar conectado ou não. A tela de login existe para que recursos que **precisam** de uma identidade estável (lembretes de re-auditoria por enquanto, mais no futuro) tenham onde se ancorar. +A autenticação é opcional. Políticas, o painel, a página `/audit` e todos os outros recursos locais funcionam exatamente da mesma forma, esteja você conectado ou não. A funcionalidade de login existe para que recursos que **precisam** de uma identidade estável (lembretes de re-auditoria hoje, mais no futuro) tenham onde se ancorar. ## Fluxo de login @@ -19,9 +19,9 @@ A autenticação é opcional. Políticas, o dashboard, a página `/audit` e todo failproofai auth login ``` -Solicita seu e-mail, envia um código de 6 dígitos de uso único para esse endereço, pede o código e, em caso de sucesso, grava `~/.failproofai/auth.json` (modo `0600`). A mesma sessão fica visível no dashboard do aplicativo — ao clicar em `[ set a reminder ]` em `/audit`, você aparecerá como conectado. +Solicita seu e-mail, envia um código de uso único de 6 dígitos para esse endereço, pede o código e, em caso de sucesso, grava `~/.failproofai/auth.json` (modo `0600`). A mesma sessão fica visível no painel do aplicativo — ao clicar em `[ set a reminder ]` em `/audit`, você será reconhecido como conectado. -O dashboard expõe o mesmo fluxo como um diálogo modal em `/audit` para usuários que nunca usam a CLI. +O painel expõe o mesmo fluxo como um diálogo modal em `/audit` para usuários que nunca usam a CLI. ## Sair @@ -29,7 +29,7 @@ O dashboard expõe o mesmo fluxo como um diálogo modal em `/audit` para usuári failproofai auth logout ``` -Revoga a sessão atual no servidor e exclui `~/.failproofai/auth.json`. Se o servidor de API estiver inacessível, o arquivo local é removido de qualquer forma — a intenção local de sair sempre prevalece. +Revoga a sessão atual no servidor e exclui `~/.failproofai/auth.json`. Se o servidor de API estiver inacessível, o arquivo local é removido de qualquer forma — a intenção local de desconectar sempre prevalece. ## Verificação de identidade @@ -37,11 +37,11 @@ Revoga a sessão atual no servidor e exclui `~/.failproofai/auth.json`. Se o ser failproofai auth whoami ``` -Exibe ` ()` e encerra com código 0 quando existe uma sessão válida, ou `not signed in` e encerra com código 1 caso contrário. Atualiza silenciosamente o token de acesso em segundo plano se ele estiver a menos de um minuto de expirar. +Exibe ` ()` e encerra com código 0 quando há uma sessão válida, ou `not signed in` e encerra com código 1 caso contrário. Atualiza silenciosamente o token de acesso em segundo plano se ele estiver a menos de um minuto de expirar. ## Lembrete recorrente de re-auditoria -Quando você clica em **`[ set a reminder ]`** na página `/audit` (ou entra via o modal que o botão acessa), o dashboard grava um pequeno arquivo auxiliar em `~/.failproofai/next-audit.json`: +Ao clicar em **`[ set a reminder ]`** na página `/audit` (ou ao entrar via o modal que o botão exige), o painel grava um pequeno arquivo complementar em `~/.failproofai/next-audit.json`: ```json { @@ -51,9 +51,9 @@ Quando você clica em **`[ set a reminder ]`** na página `/audit` (ou entra via } ``` -Este arquivo está vinculado ao e-mail para o qual foi definido — trocar a sessão da CLI para uma conta diferente oculta qualquer lembrete pertencente ao usuário anterior. O intervalo padrão é de **7 dias**, configurável futuramente quando o agendador for implementado. Criado com permissões `0600` como `auth.json`. +Este arquivo está vinculado ao e-mail para o qual foi definido — trocar a sessão da CLI para uma conta diferente oculta qualquer lembrete pertencente ao usuário anterior. O intervalo padrão é de **7 dias**, configurável futuramente quando o agendador for implementado. Criado com permissões `0600`, assim como `auth.json`. -O endpoint `/api/auth/reminder` do dashboard expõe `GET` (ler), `POST` (definir / reagendar) e `DELETE` (limpar), e requer uma sessão ativa. +O endpoint `/api/auth/reminder` do painel expõe os métodos `GET` (ler), `POST` (definir / reagendar) e `DELETE` (limpar), e requer uma sessão ativa. ## O que há em `~/.failproofai/auth.json` @@ -67,7 +67,7 @@ O endpoint `/api/auth/reminder` do dashboard expõe `GET` (ler), `POST` (definir } ``` -Criado com permissões `0600` (leitura/escrita somente pelo proprietário). O token de acesso é um JWT HS256 com validade de 1 hora; o token de atualização é uma string aleatória opaca de 256 bits que o servidor armazena como `SHA-256(token)`. A reutilização do token de atualização é detectada no servidor e revoga todas as sessões do usuário. +Criado com permissões `0600` (leitura/escrita apenas pelo proprietário). O token de acesso é um JWT HS256 válido por 1 hora; o refresh token é uma string aleatória opaca de 256 bits que o servidor armazena como `SHA-256(token)`. A reutilização do refresh token é detectada no servidor e revoga todas as sessões do usuário. ## Variáveis de ambiente @@ -80,8 +80,8 @@ Consulte [Variáveis de ambiente](/pt-br/cli/environment-variables) para a lista ## Solução de problemas -**"Could not reach the api-server"** — a CLI não consegue abrir uma conexão TCP com `FAILPROOF_API_URL`. Verifique sua rede ou defina `FAILPROOF_API_URL` se você estiver executando um servidor de API auto-hospedado. +**"Could not reach the api-server"** — a CLI não consegue abrir uma conexão TCP com `FAILPROOF_API_URL`. Verifique sua rede ou defina `FAILPROOF_API_URL` se estiver executando um servidor de API auto-hospedado. -**"Rate limited"** — muitas tentativas de login em uma janela de 15 minutos para aquele e-mail (5/e-mail) ou IP (20/IP), ou um cooldown de 30 segundos após a solicitação anterior para o mesmo e-mail. A mensagem de erro inclui o tempo de espera em segundos. +**"Rate limited"** — muitas tentativas de login em uma janela de 15 minutos para aquele e-mail (5/e-mail) ou IP (20/IP), ou um intervalo de reenvio de 30 segundos após a solicitação anterior para o mesmo e-mail. A mensagem de erro inclui o tempo de espera em segundos. -**Código rejeitado** — o OTP estava incorreto, expirou ou a entrada atingiu o bloqueio de 5 tentativas erradas. Execute `failproofai auth login` novamente para solicitar um novo código. \ No newline at end of file +**Código rejeitado** — o OTP estava incorreto, expirado, ou a entrada atingiu o bloqueio após 5 tentativas erradas. Execute `failproofai auth login` novamente para solicitar um novo código. \ No newline at end of file diff --git a/docs/pt-br/cli/dashboard.mdx b/docs/pt-br/cli/dashboard.mdx index 50f80b17..cc09f98c 100644 --- a/docs/pt-br/cli/dashboard.mdx +++ b/docs/pt-br/cli/dashboard.mdx @@ -1,5 +1,5 @@ --- -title: Ver sessões +title: Visualizar sessões description: "Inicie o dashboard para navegar pelas sessões de agentes e gerenciar políticas" --- @@ -16,7 +16,7 @@ Inicia o dashboard web em `http://localhost:8020`. | `--port ` | Porta para escutar (padrão: `8020`) | | `--allowed-origins ` | Hosts/IPs separados por vírgula com permissão de acesso aos recursos de desenvolvimento | -Para apontar o dashboard para uma pasta de projetos Claude diferente da padrão, defina a variável de ambiente `CLAUDE_PROJECTS_PATH` ao iniciar. +Para apontar o dashboard para uma pasta de projeto Claude diferente da padrão, defina a variável de ambiente `CLAUDE_PROJECTS_PATH` ao iniciar. ## Exemplos diff --git a/docs/pt-br/cli/environment-variables.mdx b/docs/pt-br/cli/environment-variables.mdx index 7838e35e..175d9966 100644 --- a/docs/pt-br/cli/environment-variables.mdx +++ b/docs/pt-br/cli/environment-variables.mdx @@ -9,8 +9,8 @@ description: "Configure o comportamento do failproofai com variáveis de ambient |----------|-----------| | `PORT` | Porta do dashboard (padrão: `8020`) | | `CLAUDE_PROJECTS_PATH` | Substitui o local onde as pastas de projetos do Claude Code são encontradas | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Páginas do dashboard separadas por vírgula para ocultar | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hosts/IPs com permissão de acesso aos recursos de desenvolvimento. Equivalente a `--allowed-origins`. | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Páginas do dashboard a ocultar, separadas por vírgula | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hosts/IPs com permissão para acessar recursos de desenvolvimento. Equivalente a `--allowed-origins`. | ## Logging @@ -29,14 +29,14 @@ description: "Configure o comportamento do failproofai com variáveis de ambient | Variável | Descrição | |----------|-----------| -| `FAILPROOF_API_URL` | Substitui a URL base do servidor de API usada pelo `failproofai auth` e pelo diálogo de autenticação do dashboard. O padrão é `https://api.befailproof.ai`; defina como `http://localhost:8080` (ou outro endereço) ao executar um servidor de API local. | +| `FAILPROOF_API_URL` | Substitui a URL base do servidor de API usado pelo `failproofai auth` e pelo diálogo de autenticação do dashboard. O padrão é `https://api.befailproof.ai`; defina como `http://localhost:8080` (ou outro endereço) ao executar um servidor de API local. | | `FAILPROOFAI_AUTH_DIR` | Substitui o local onde o `auth.json` é armazenado (padrão: `~/.failproofai`). Útil principalmente para testes isolados. | -## Prompt de primeira execução +## Prompt de primeiro uso | Variável | Descrição | |----------|-----------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignora o prompt que oferece a instalação de políticas na primeira invocação simples do `failproofai` | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignora o prompt que oferece a instalação de políticas na primeira execução simples do `failproofai` | ## LLM (para avaliação de políticas) diff --git a/docs/pt-br/cli/hook.mdx b/docs/pt-br/cli/hook.mdx index 240b4bbe..5a94ea8b 100644 --- a/docs/pt-br/cli/hook.mdx +++ b/docs/pt-br/cli/hook.mdx @@ -23,7 +23,7 @@ Lê um payload JSON do stdin, avalia todas as políticas habilitadas e encerra c |-----------|---------| | **Execução de ferramentas** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | | **Ciclo de vida da sessão** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | -| **Interação com o usuário** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | +| **Interação do usuário** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | | **Subagentes e tarefas** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | | **Configuração** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | | **Sistema de arquivos** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | diff --git a/docs/pt-br/cli/install-policies.mdx b/docs/pt-br/cli/install-policies.mdx index 01d0f267..5c214766 100644 --- a/docs/pt-br/cli/install-policies.mdx +++ b/docs/pt-br/cli/install-policies.mdx @@ -1,13 +1,13 @@ --- title: Instalar políticas -description: "Ative as políticas para que sejam executadas em cada chamada de ferramenta do agente" +description: "Habilite políticas para que sejam executadas em cada chamada de ferramenta do agente" --- ```bash failproofai policies --install [policy-names...] [options] ``` -Grava entradas de hook no arquivo de configurações do CLI do agente instalado (Claude Code, OpenAI Codex ou GitHub Copilot CLI _(beta)_) para que o failproofai intercepte as chamadas de ferramentas. +Escreve entradas de hook no arquivo de configurações do CLI do agente instalado (Claude Code, OpenAI Codex ou GitHub Copilot CLI _(beta)_) para que o failproofai intercepte as chamadas de ferramentas. Aliases: `failproofai p -i` @@ -16,16 +16,16 @@ Aliases: `failproofai p -i` | Flag | Descrição | |------|-----------| | `--cli claude\|codex\|copilot` | CLI(s) do agente para instalar; separados por espaço (ex.: `--cli claude codex copilot`) ou repetidos. Omita para detectar os CLIs instalados e exibir um prompt. | -| `--scope user` | Instala no arquivo de configurações de escopo do usuário (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Padrão. | -| `--scope project` | Instala no arquivo de configurações de escopo do projeto (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | -| `--scope local` | Apenas Claude — instala em `/.claude/settings.local.json`. Codex e Copilot não possuem escopo `local`. | +| `--scope user` | Instala no arquivo de configurações com escopo de usuário (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Padrão. | +| `--scope project` | Instala no arquivo de configurações com escopo de projeto (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | +| `--scope local` | Somente Claude — instala em `/.claude/settings.local.json`. Codex e Copilot não possuem escopo `local`. | | `--custom ` / `-c` | Caminho para um arquivo JS contendo políticas de hook personalizadas | ## Comportamento -- **Sem nomes de política** — abre um prompt interativo para selecionar as políticas -- **Nomes específicos** — ativa as políticas indicadas (adicionadas às que já estiverem ativas) -- **`all`** — ativa todas as políticas disponíveis +- **Sem nomes de política** — abre um prompt interativo para selecionar políticas +- **Nomes específicos** — habilita essas políticas (adicionadas às que já estão habilitadas) +- **`all`** — habilita todas as políticas disponíveis A instalação é aditiva: executar `--install` novamente adiciona novas políticas sem remover as existentes. @@ -38,16 +38,16 @@ failproofai policies --install # Instalar políticas específicas para o projeto atual failproofai policies --install block-sudo sanitize-api-keys --scope project -# Ativar todas as políticas de uma vez +# Habilitar todas as políticas de uma vez failproofai policies --install all # Instalar com um arquivo de políticas personalizado failproofai policies --install --custom ./my-policies.js -# Instalar para OpenAI Codex (escopo de projeto) +# Instalar para o OpenAI Codex (escopo de projeto) failproofai policies --install --cli codex --scope project -# Instalar para GitHub Copilot CLI (beta) no projeto atual +# Instalar para o GitHub Copilot CLI (beta) no projeto atual failproofai policies --install --cli copilot --scope project # Instalar para os três CLIs de uma vez diff --git a/docs/pt-br/cli/list-policies.mdx b/docs/pt-br/cli/list-policies.mdx index f8134bfd..7c77feec 100644 --- a/docs/pt-br/cli/list-policies.mdx +++ b/docs/pt-br/cli/list-policies.mdx @@ -1,13 +1,13 @@ --- title: Listar políticas -description: "Veja quais políticas estão habilitadas, seus parâmetros e políticas customizadas" +description: "Veja quais políticas estão habilitadas, seus parâmetros e políticas personalizadas" --- ```bash failproofai policies ``` -Exibe todas as políticas com seu status, parâmetros configurados e políticas customizadas. +Exibe todas as políticas com seu status, parâmetros configurados e políticas personalizadas. ## Exemplo de saída @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -Chaves desconhecidas em `policyParams` são sinalizadas aqui para que você possa identificar erros de digitação com antecedência. \ No newline at end of file +Chaves desconhecidas em `policyParams` são sinalizadas aqui para que você possa detectar erros de digitação com antecedência. \ No newline at end of file diff --git a/docs/pt-br/cli/remove-policies.mdx b/docs/pt-br/cli/remove-policies.mdx index 512ec56d..4ea737d1 100644 --- a/docs/pt-br/cli/remove-policies.mdx +++ b/docs/pt-br/cli/remove-policies.mdx @@ -1,6 +1,6 @@ --- title: Desinstalar políticas -description: "Remove entradas de hook das configurações do Claude Code" +description: "Remover entradas de hook das configurações do Claude Code" --- ```bash @@ -15,11 +15,11 @@ Aliases: `failproofai p -u` | Flag | Descrição | |------|-----------| -| `--scope user` | Remove das configurações globais (padrão) | -| `--scope project` | Remove das configurações do projeto | -| `--scope local` | Remove das configurações locais | -| `--scope all` | Remove de todos os escopos de uma vez | -| `--custom` / `-c` | Limpa o `customPoliciesPath` da configuração | +| `--scope user` | Remover das configurações globais (padrão) | +| `--scope project` | Remover das configurações do projeto | +| `--scope local` | Remover das configurações locais | +| `--scope all` | Remover de todos os escopos de uma vez | +| `--custom` / `-c` | Limpar o `customPoliciesPath` da configuração | ## Comportamento @@ -29,15 +29,15 @@ Aliases: `failproofai p -u` ## Exemplos ```bash -# Remove todos os hooks globalmente +# Remover todos os hooks globalmente failproofai policies --uninstall -# Desativa uma política específica (mantém os hooks instalados) +# Desativar uma política específica (mantém os hooks instalados) failproofai policies --uninstall block-sudo -# Remove hooks de todos os escopos +# Remover hooks de todos os escopos failproofai policies --uninstall --scope all -# Limpa o caminho de políticas personalizadas +# Limpar o caminho de políticas personalizadas failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/pt-br/configuration.mdx b/docs/pt-br/configuration.mdx index 35c78a83..ba82f42c 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 --- -O failproofai utiliza arquivos de configuração JSON para controlar quais políticas estão ativas, como elas se comportam e de onde políticas personalizadas são carregadas. A configuração foi projetada para ser fácil de compartilhar com sua equipe — faça commit no 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 seu repositório e todos os desenvolvedores terão a mesma rede de segurança para agentes. --- @@ -13,12 +13,12 @@ O failproofai utiliza arquivos de configuração JSON para controlar quais polí 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, versionadas no controle de versão | -| **local** | `.failproofai/policies-config.local.json` | Substituições pessoais por repositório, ignoradas pelo git | -| **global** | `~/.failproofai/policies-config.json` | Padrões do usuário aplicados a todos os projetos | +|--------|--------------------|------------| +| **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 | -Quando o failproofai recebe um evento de hook, ele carrega e mescla os três arquivos existentes para o diretório de trabalho atual. +Quando failproofai recebe um evento de hook, ele carrega e mescla os três arquivos que existirem para o diretório de trabalho atual. ### Regras de mesclagem @@ -32,13 +32,13 @@ global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← união sem duplicatas ``` -**`policyParams`** — o primeiro escopo que define 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. +**`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. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← project vence, global é ignorado +resolved: { allowPatterns: ["sudo apt-get update"] } ← project vence, global ignorado ``` ```text @@ -102,9 +102,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 pelo `failproofai policies`. Consulte [Políticas Integradas](/pt-br/built-in-policies) para a lista completa. +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. -Políticas que não estão em `enabledPolicies` ficam inativas, mesmo que tenham entradas em `policyParams`. +Políticas que não estejam em `enabledPolicies` ficam inativas, mesmo que tenham entradas em `policyParams`. ### `policyParams` @@ -112,17 +112,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 possui parâmetros, mas você não os especifica, os padrões integrados da política são utilizados. Usuários que não configuram `policyParams` têm comportamento idêntico ao das versões anteriores. +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. -Chaves desconhecidas dentro do bloco de parâmetros de uma política são silenciosamente ignoradas no momento do disparo do hook, mas sinalizadas como avisos quando você executa `failproofai policies`. +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`. #### `hint` (transversal) Tipo: `string` (opcional) -Uma mensagem anexada ao motivo quando uma política retorna `deny` ou `instruct`. Use para fornecer ao Claude orientações práticas sem modificar a própria política. +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. -Funciona com qualquer tipo de política — integrada, personalizada (`custom/`), convenção de projeto (`.failproofai-project/`) ou convenção do usuário (`.failproofai-user/`). +Funciona com qualquer tipo de política — integradas, personalizadas (`custom/`), convenções de projeto (`.failproofai-project/`) ou convenções de usuário (`.failproofai-user/`). ```json { @@ -141,32 +141,32 @@ Funciona com qualquer tipo de política — integrada, personalizada (`custom/`) } ``` -Quando block-force-push nega, Claude vê: *"Force-pushing is blocked. Try creating a fresh branch instead."* +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 permanece inalterado (compatível com versões anteriores). ### `customPoliciesPath` Tipo: `string` (caminho absoluto) -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). +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). -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. +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. ### Políticas baseadas em convenção -Além do `customPoliciesPath` explícito, o failproofai descobre e carrega automaticamente arquivos de política dos diretórios `.failproofai/policies/`: +Além do `customPoliciesPath` explícito, failproofai descobre e carrega automaticamente arquivos de política dos diretórios `.failproofai/policies/`: | Nível | Diretório | Escopo | |-------|-----------|--------| | Projeto | `.failproofai/policies/` | Compartilhado com a equipe via controle de versão | -| Usuário | `~/.failproofai/policies/` | Pessoal, aplica-se a todos os projetos | +| Usuário | `~/.failproofai/policies/` | Pessoal, aplicado a todos os projetos | -**Correspondência de arquivos:** Apenas arquivos que correspondem 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:** 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. -**Sem configuração necessária:** Políticas por convenção não requerem 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 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. -**Carregamento por união:** Ambos os diretórios de convenção — de projeto e de usuário — são verificados. Todos os arquivos correspondentes de ambos os níveis são carregados (diferente do `customPoliciesPath`, que usa o primeiro escopo encontrado). +**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). Consulte [Políticas Personalizadas](/pt-br/custom-policies) para mais detalhes e exemplos. @@ -174,7 +174,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 dos cenários. +Configuração do cliente LLM para políticas que fazem chamadas de IA. Não é necessário para a maioria das configurações. ```json { @@ -189,19 +189,20 @@ 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 hooks da CLI do agente (os pontos de entrada dos hooks), enquanto o `policies-config.json` é o arquivo que você gerencia diretamente. Os dois são separados: +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: -- **Configurações da CLI do agente** — instrui o agente a chamar `failproofai --hook ` a cada uso de ferramenta: +- **Configurações do agente CLI** — instrui o agente a chamar `failproofai --hook ` a 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 tem escopo `local`. As entradas de hook usam os campos de comando `bash`/`powershell` com chave de SO do Copilot com `timeoutSec`; o arquivo contém um marcador `version: 1` no nível superior. O suporte ao Copilot CLI está em **beta** enquanto verificamos o esquema de registro `events.jsonl` (não especificado na documentação pública) contra mais sessões do mundo real. - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (usuário), `/.cursor/hooks.json` (projeto) — o Cursor não tem escopo `local`. As entradas de hook usam o formato no estilo Claude `{type, command, timeout}` (sem separação `bash`/`powershell`), mas armazenadas sob chaves de evento em camelCase (`preToolUse`, `beforeSubmitPrompt`, …) em um array plano seguindo o [esquema de hooks](https://cursor.com/docs/hooks) do Cursor; o arquivo contém um marcador `version: 1` no nível superior. O handler canonicaliza camelCase → PascalCase via `CURSOR_EVENT_MAP`, então as políticas integradas existentes disparam sem alterações. O suporte ao Cursor Agent está em **beta** enquanto verificamos o formato de transcrição em disco do Cursor (não especificado na documentação pública) contra mais instalações do mundo real. - - **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 tem escopo `local`. Diferente dos outros seis CLIs, o OpenCode **não possui sistema de hook por comando externo**: ele carrega plugins JS/TS em processo, explicitamente registrados via o array `plugin: []` em `opencode.json` (a descoberta automática 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 como subprocesso e traduz a resposta JSON no formato Claude de volta para semântica de plugin: `throw new Error()` para deny em eventos de ferramenta (cancela a chamada da ferramenta), `client.session.prompt(...)` para instruct E para deny de `Stop` / `SubagentStop` (envia o motivo da negação como próxima mensagem do usuário — o único canal de força de reenvio, já que `session.idle` é apenas notificação e lançar exceção a partir dele não tem efeito), e no-op para allow. O shim canonicaliza tanto os nomes das ferramentas (lowercase → PascalCase via `OPENCODE_TOOL_MAP`) quanto as chaves dos 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 repassar ao binário, de modo que as políticas integradas de verificação de caminho como `block-read-outside-cwd`, `block-env-files` e `block-secrets-write` disparam normalmente em 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 dashboard as lê via `opencode db --format json` e `opencode export `. O suporte ao OpenCode está em **beta** enquanto verificamos o comportamento em diferentes versões e contra mais sessões do mundo real. 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 tem escopo `local`. O Pi carrega pacotes de extensão TypeScript na inicialização; o arquivo de configurações é um array simples de strings `{"packages": ["./relative/path", …]}`. O failproofai escreve uma única entrada no array de pacotes 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`, então as políticas integradas existentes disparam sem alterações. Os argumentos de entrada das ferramentas também são canonicalizados via `PI_TOOL_INPUT_MAP` (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á possuía um fallback para `path`). O suporte ao Pi está em **beta** enquanto a API de extensão e o layout do log de sessão do Pi se estabilizam. - - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (usuário), `/.gemini/settings.json` (projeto) — o Gemini não tem escopo `local` (documenta um escopo `system` em `/etc/gemini-cli/settings.json`, que o failproofai não expõe). As entradas de hook usam o formato Claude `{type, command, timeout}` encapsulado no esquema de matcher do Gemini `{matcher, hooks: [...]}` com `matcher: "*"` por padrão. Os eventos são PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); o handler mapeia para nomes canônicos Claude via `GEMINI_EVENT_MAP`. Os nomes das ferramentas são snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — o handler canonicaliza via `GEMINI_TOOL_MAP`, então as políticas integradas existentes disparam sem alterações. O avaliador de políticas emite o formato plano `{decision: "deny", reason}` do Gemini (preferido pela "Regra de Ouro" do exit-0 do Gemini), `{hookSpecificOutput: {hookEventName, additionalContext}}` para injeção de contexto em BeforeAgent / AfterTool / SessionStart, e `{decision: "block", reason}` no AfterAgent para semântica de força de reenvio. O suporte ao Gemini CLI está em **beta** enquanto ampliamos a cobertura do mundo real. Consulte a [documentação de hooks do Gemini CLI](https://geminicli.com/docs/hooks/). -- **`policies-config.json`** — instrui o failproofai sobre quais políticas avaliar e com quais parâmetros (compartilhado entre todos os CLIs de agentes) + - **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 seis 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. + - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (usuário), `/.gemini/settings.json` (projeto) — o Gemini não possui escopo `local` (ele documenta um escopo `system` em `/etc/gemini-cli/settings.json`, que failproofai não expõe). As entradas de hook usam o formato Claude `{type, command, timeout}` encapsulado no esquema de matcher do Gemini `{matcher, hooks: [...]}` com `matcher: "*"` por padrão. Os eventos são PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); o handler mapeia para nomes canônicos do Claude via `GEMINI_EVENT_MAP`. Os nomes de ferramentas são snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — o handler os canonicaliza via `GEMINI_TOOL_MAP` para que as políticas integradas existentes disparem sem alteração. O avaliador de políticas emite o formato plano `{decision: "deny", reason}` do Gemini (preferido conforme o contrato exit-0 da "Regra de Ouro" do Gemini), `{hookSpecificOutput: {hookEventName, additionalContext}}` para injeção de contexto em BeforeAgent / AfterTool / SessionStart, e `{decision: "block", reason}` em AfterAgent para semântica de força de nova tentativa. O suporte ao Gemini CLI está em **beta** enquanto ampliamos a cobertura em situações reais. Consulte a [documentação de hooks do Gemini CLI](https://geminicli.com/docs/hooks/). + - **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|gemini` para direcionar um agente específico (separado por espaço ou repetido para qualquer subconjunto): +Passe `--cli claude|codex|copilot|cursor|opencode|pi|gemini|hermes` para direcionar um agente específico (separado por espaço ou repetido para qualquer subconjunto): ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +211,24 @@ 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 gemini --scope project +failproofai policies --install --cli hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` -Quando `--cli` é omitido, o `failproofai` detecta quais CLIs de agentes estão instalados (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): +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 gemini` / `which hermes`): - **Um CLI detectado** — seleciona automaticamente esse CLI sem solicitar confirmação. -- **Múltiplos 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ção de instalação antecipada (↑↓ para mover, Enter para selecionar, ^C para sair). O fluxo de desinstalação exibe apenas a seção Detected. -- **Múltiplos CLIs detectados** em uma execução não interativa (CI, sem TTY) — instala para todos os CLIs detectados sem solicitar confirmação. -- **Nenhum detectado** — 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. +- **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. -Você pode editar o `policies-config.json` diretamente a qualquer momento; as alterações têm efeito imediato no próximo evento de hook, sem necessidade de reinicialização. +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 do projeto com padrões da equipe +## Exemplo: configuração no nível de projeto com padrões da equipe -Faça commit de `.failproofai/policies-config.json` no seu repositório: +Faça o commit de `.failproofai/policies-config.json` no seu repositório: ```json { @@ -245,4 +247,4 @@ Faça commit de `.failproofai/policies-config.json` no seu repositório: } ``` -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 +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 diff --git a/docs/pt-br/custom-policies.mdx b/docs/pt-br/custom-policies.mdx index dc2c2930..2bb5a049 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, evite desvios, detecte falhas e integre com sistemas externos" icon: code --- -As políticas personalizadas permitem que você escreva regras para qualquer comportamento do agente: aplicar convenções do projeto, evitar desvios, bloquear 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 decisões `allow`, `deny`, `instruct` das políticas integradas. +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. --- @@ -29,7 +29,7 @@ customPolicies.add({ }); ``` -Instale com: +Instale: ```bash failproofai policies --install --custom ./my-policies.js @@ -39,9 +39,9 @@ failproofai policies --install --custom ./my-policies.js ## Duas formas de carregar políticas personalizadas -### Opção 1: Baseada em convenção (recomendada) +### Opção 1: Por convenção (recomendado) -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 pronto. +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. ``` # Nível do projeto — commitado no git, compartilhado com a equipe @@ -53,32 +53,32 @@ Coloque arquivos `*policies.{js,mjs,ts}` na pasta `.failproofai/policies/` e ele ``` **Como funciona:** -- Os diretórios do projeto e do usuário são verificados (união — não por primeiro escopo encontrado) -- Os arquivos são carregados em ordem alfabética dentro de cada diretório. Use prefixos como `01-`, `02-` para controlar a ordem -- Apenas arquivos que correspondam a `*policies.{js,mjs,ts}` são carregados; os demais são ignorados +- Os diretórios do projeto e do usuário são verificados (união — sem prioridade por 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 - 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 receberão as mesmas regras automaticamente — sem configuração individual. À 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. +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. ### Opção 2: Caminho de arquivo explícito ```bash -# Instala com um arquivo de políticas personalizado +# Instalar com um arquivo de políticas personalizado failproofai policies --install --custom ./my-policies.js -# Substitui o caminho do arquivo de políticas +# Substituir o caminho do arquivo de políticas failproofai policies --install --custom ./new-policies.js -# Remove o caminho de políticas personalizadas da configuração +# Remover o caminho de políticas personalizadas 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. -### Usando ambas juntas +### Usando as duas opções juntas As políticas por convenção e o arquivo `--custom` explícito podem coexistir. Ordem de carregamento: @@ -98,7 +98,7 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Registra uma política. Chame quantas vezes forem necessárias para múltiplas políticas no mesmo arquivo. +Registra uma política. Chame quantas vezes precisar para múltiplas políticas no mesmo arquivo. ```ts customPolicies.add({ @@ -109,34 +109,34 @@ customPolicies.add({ }); ``` -### Helpers de decisão +### Funções auxiliares 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 | Fornece contexto extra ao agente para mantê-lo no caminho certo | +| `instruct(message)` | Adiciona contexto sem bloquear | Forneça 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. +`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 é anexada 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 alteração no código. Isso também funciona para políticas personalizadas (`custom/`), de convenção do projeto (`.failproofai-project/`) e de convenção do usuário (`.failproofai-user/`). Consulte [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para mais detalhes. +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. -### Mensagens informativas de allow +### Mensagens allow informativas -`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. +`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. | Função | Efeito | Use quando | -|--------|--------|------------| -| `allow(message)` | Permite e envia contexto para Claude | Confirma que uma verificação passou ou explica por que foi ignorada | +|----------|--------|----------| +| `allow(message)` | Permite e envia contexto para Claude | Confirme que uma verificação passou, ou explique por que foi ignorada | Casos de uso: -- **Confirmações de status:** `allow("All CI checks passed.")` — informa Claude que tudo está em ordem -- **Explicações de fail-open:** `allow("GitHub CLI not installed, skipping CI check.")` — informa Claude por que uma verificação foi pulada, dando contexto completo -- **Múltiplas mensagens se acumulam:** se várias políticas retornarem `allow(message)`, todas as mensagens são unidas com quebras de linha e entregues juntas +- **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 +- **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 customPolicies.add({ @@ -146,7 +146,7 @@ customPolicies.add({ const cwd = ctx.session?.cwd; if (!cwd) return allow("No working directory, skipping branch check."); - // ... verifica o status do branch ... + // ... verificar status do branch ... if (allPushed) { return allow("Branch is up to date with remote."); } @@ -155,20 +155,20 @@ customPolicies.add({ }); ``` -### Campos do `PolicyContext` +### Campos de `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 completo do evento bruto do Claude Code | +| `payload` | `Record` | Payload bruto completo do evento do Claude Code | | `session` | `SessionMetadata \| undefined` | Contexto da sessão (veja abaixo) | -### Campos do `SessionMetadata` +### Campos de `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 | @@ -176,7 +176,7 @@ customPolicies.add({ ### Tipos de evento | 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 | @@ -188,10 +188,10 @@ customPolicies.add({ As políticas são avaliadas nesta ordem: -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 em `.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada arquivo) -4. Políticas de convenção do usuário em `~/.failproofai/policies/` (arquivos em ordem alfabética, ordem de `.add()` dentro de cada arquivo) +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) O primeiro `deny` interrompe todas as políticas subsequentes. Todas as mensagens `instruct` são acumuladas e entregues juntas. @@ -218,20 +218,20 @@ customPolicies.add({ }); ``` -Todas as importações relativas acessí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 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. --- ## Filtragem por tipo de evento -Use `match.events` para limitar quando uma política é acionada: +Use `match.events` para limitar quando uma política dispara: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Só dispara quando a sessão encerra + // Dispara apenas quando a sessão encerra // ctx.session.transcriptPath contém o log completo da sessão return allow(); }, @@ -244,17 +244,17 @@ Omita `match` completamente para disparar em todos os tipos 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 handler do hook. +As políticas personalizadas são **fail-open**: erros nunca bloqueiam as políticas integradas nem causam falha no hook handler. | Falha | Comportamento | -|-------|---------------| -| `customPoliciesPath` não definido | Nenhuma política personalizada explícita é executada; políticas de convenção e integradas continuam normalmente | +|---------|----------| +| `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 erro 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 de convenção é executada; sem erro | +| Diretório de convenção ausente | Nenhuma política por convenção é executada; sem erro | Para depurar erros de políticas personalizadas, monitore o arquivo de log: @@ -285,7 +285,7 @@ customPolicies.add({ }, }); -// Mantém o agente no caminho certo: verificar testes antes de commitar +// Mantém o agente no caminho certo: verifica os testes antes de commitar customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +300,7 @@ customPolicies.add({ }, }); -// Evita alterações não planejadas de dependências durante o período de congelamento +// Impede mudanças de dependências não planejadas durante o período de freeze customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -326,11 +326,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 comuns de falha do agente | -| `examples/policies-advanced/index.js` | Padrões avançados: importações transitivas, chamadas assíncronas, limpeza de saída e hooks de fim de sessão | -| `examples/convention-policies/security-policies.mjs` | Políticas de segurança baseadas em convenção (bloqueio de escrita em .env, prevenção de reescrita do histórico 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) | +|------|----------| +| `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) | ### Usando exemplos com arquivo explícito @@ -341,11 +341,11 @@ failproofai policies --install --custom ./examples/policies-basic.js ### Usando exemplos baseados em convenção ```bash -# Copia para o nível do projeto +# Copiar para o nível do projeto mkdir -p .failproofai/policies cp examples/convention-policies/*.mjs .failproofai/policies/ -# Ou copia para o nível do usuário +# Ou copiar para o nível do usuário mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` diff --git a/docs/pt-br/dashboard.mdx b/docs/pt-br/dashboard.mdx index 2c118ddb..7b2ed4d0 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ê diretamente do sistema de arquivos — suas pastas de projeto do Claude Code e os arquivos de configuração do failproofai. Nada é gravado em um serviço remoto. +O dashboard lê diretamente do sistema de arquivos — suas pastas de projetos do Claude Code e os arquivos de configuração do failproofai. Nada é gravado em um serviço remoto. --- @@ -24,11 +24,11 @@ O dashboard lê diretamente do sistema de arquivos — suas pastas de projeto do ### Projetos -Lista todos os projetos Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_ e Gemini CLI _(beta)_ encontrados na sua máquina. Os projetos Claude são descobertos a partir de `~/.claude/projects/` (ou do caminho definido por `CLAUDE_PROJECTS_PATH`); os projetos Codex são descobertos escaneando todos os transcritos em `~/.codex/sessions///
/*.jsonl` e agrupando pelo `cwd` registrado no primeiro registro de cada sessão; os projetos Copilot CLI são descobertos escaneando cada `~/.copilot/session-state//workspace.yaml` (configurável via `COPILOT_HOME`) e agrupando pelo campo `cwd`; os projetos Cursor Agent são descobertos escaneando os metadados por sessão em `~/.cursor/agent-sessions//` (configurável via `CURSOR_HOME`, com `conversations/` e `sessions/` verificados como fallbacks) para um escalar `cwd` em `meta.json` / `session.json` / `workspace.yaml`; os 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`); os projetos Pi são descobertos escaneando transcritos 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; os projetos Gemini CLI são descobertos escaneando `~/.gemini/tmp//chats/session--.jsonl` (configurável via `GEMINI_SESSIONS_DIR`) e recuperando o cwd canônico a partir do marcador de texto `.project_root` irmão. Um projeto que foi utilizado por múltiplos CLIs é exibido 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|gemini`. +Lista todos os projetos Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Gemini CLI _(beta)_ e Hermes encontrados na sua máquina. Os projetos Claude são descobertos em `~/.claude/projects/` (ou no caminho definido por `CLAUDE_PROJECTS_PATH`); os projetos Codex são descobertos varrendo todas as transcrições em `~/.codex/sessions///
/*.jsonl` e agrupando pelo `cwd` registrado no primeiro registro de cada sessão; os projetos Copilot CLI são descobertos varrendo cada `~/.copilot/session-state//workspace.yaml` (configurável via `COPILOT_HOME`) e agrupando pelo campo `cwd`; os projetos Cursor Agent são descobertos varrendo metadados por sessão em `~/.cursor/agent-sessions//` (configurável via `CURSOR_HOME`, com `conversations/` e `sessions/` como alternativas) em busca de um escalar `cwd` em `meta.json` / `session.json` / `workspace.yaml`; os 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`); os 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; os projetos Gemini CLI são descobertos varrendo `~/.gemini/tmp//chats/session--.jsonl` (configurável via `GEMINI_SESSIONS_DIR`) e recuperando o cwd canônico a partir do marcador de texto `.project_root` adjacente; as 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 do gateway não possuem cwd). Um projeto utilizado por múltiplos CLIs é exibido 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|gemini|hermes`. 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 `Gemini CLI` (azul-céu) +- Um badge de CLI — `Claude Code` (laranja), `OpenAI Codex` (roxo), `GitHub Copilot` (azul), `Cursor Agent` (esmeralda), `OpenCode` (âmbar), `Pi` (rosa), `Gemini CLI` (celeste) e/ou `Hermes` (índigo) - Data da atividade mais recente da sessão Clique em um projeto para ver suas sessões. @@ -37,7 +37,7 @@ Clique em um projeto para ver suas sessões. Lista todas as sessões dentro de um projeto. Cada sessão exibe: - ID da sessão -- Timestamps de início e fim +- Timestamps de início e término - Número de chamadas de ferramentas - Contagem de atividade de hooks (políticas que foram acionadas) @@ -47,44 +47,44 @@ Clique em uma sessão para abrir o visualizador de sessão. ### Visualizador de sessão -O visualizador de sessão responde à principal pergunta sobre 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 é um transcrito do Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi ou Gemini CLI. Ele exibe uma linha do tempo de tudo o que aconteceu em uma sessão: +O visualizador de sessão responde à pergunta central dos agentes autônomos: o que o agente fez, e ele se manteve no curso? Um badge de CLI ao lado do cabeçalho indica se a sessão é uma transcrição do Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Gemini CLI ou Hermes. Ele exibe uma linha do tempo de tudo 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 -- **Atividade de políticas** — Para cada chamada de ferramenta, quais políticas foram acionadas e qual decisão elas retornaram +- **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, o total de chamadas de ferramentas e um resumo das decisões de hook (contagens de allow / deny / instruct). +A barra de estatísticas no topo mostra 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 do Claude Code, Codex, Copilot, Cursor, Pi e Gemini, você recebe o transcrito JSONL original em disco byte a byte; para o 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 do Claude Code, Codex, Copilot, Cursor, Pi e Gemini, você recebe a transcrição JSONL original em disco byte a byte; para o 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 orientado por personalidade de como seu agente tem se comportado de fato ao longo de sessões passadas. Executa o mesmo escaneamento que o CLI `failproofai audit`, mas renderiza como um pôster de tela única compartilhável + quatro seções abaixo da dobra: +Um relatório com personalidade sobre como seu agente tem se comportado ao longo das sessões anteriores. Executa a mesma varredura que o CLI `failproofai audit`, mas renderiza como um pôster de tela única compartilhável + quatro seções abaixo da dobra: -1. **Pôster** — preenche o primeiro viewport. Região de captura PNG independente com o logotipo failproof_ai + rótulo de auditoria · índice de arquétipo (`№ NN of 08`) + data da auditoria · pontuação numérica (0–100) + pílula de percentil (`top 15%`) · o nome do arquétipo (um dentre `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` · bloco de símbolo pixel 8×8 · 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`, portanto o PNG corresponde pixel a pixel à renderização em tela (bordas tracejadas, máscara de logo SVG, gradientes, métricas de fonte — tudo preservado). -2. **Pontos fortes** — lista de linhas com ✓ destacando comportamentos que seu agente já faz corretamente, derivados dos dados de auditoria em tempo real (taxa limpa de chamadas de ferramentas, sem pushes diretos para main, zero vazamentos de credenciais, zero tempestades de retry) — cada item exibido apenas quando a política relevante tem um histórico limpo ao longo da janela de auditoria. -3. **Peculiaridades** — tabela do que passou despercebido, classificado por severidade: `quando · o que escapou + a política que teria detectado · pílula de severidade · visto`, onde a recorrência é exibida como `new` (uma vez), `N× seen` (2–9 vezes) ou `recurring` (10+). -4. **Como melhorar** — lista de linhas tranquilas, 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 cards 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 vantagens failproof — `invite a friend` abre um modal que aceita uma lista de e-mails de amigos separados por vírgula/espaço/nova 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 saiba quem o convidou e o remetente receba uma cópia em sua caixa de entrada. Usuários anônimos são direcionados pelo `AuthDialog` primeiro para que o e-mail do remetente seja conhecido antes dos convites serem enviados. Direitos e benefícios serão implementados em uma etapa futura. +1. **Pôster** — preenche o primeiro viewport. Região de captura PNG autocontida 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 sigilo 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 ao render na tela (bordas tracejadas, máscara de logo SVG, gradientes, métricas de fonte — tudo preservado). +2. **Pontos fortes** — lista de linhas com ✓ tranquilo dos comportamentos que seu agente já faz corretamente, derivada dos dados de auditoria ao vivo (taxa limpa de chamadas de ferramentas, sem pushes diretos para main, zero vazamentos de credenciais, zero tempestades de retry) — cada item exibido apenas quando a política relevante tem um histórico limpo dentro da janela de auditoria. +3. **Peculiaridades** — tabela do que passou despercebido, ordenada por severidade: `when · what slipped + the policy that would've caught it · severity pill · seen`, onde a recorrência lê `new` (uma vez), `N× seen` (2–9 vezes), ou `recurring` (10+). +4. **Como melhorar** — lista de linhas tranquila, 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 lê `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 cards lado a lado. Esquerdo: definir um lembrete (seletor de cadência `3d` / `7d` / `14d` / `30d`; persiste via `/api/auth/reminder` após autenticação). Direito: desbloquear benefícios 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áx. 10 por envio), faz POST para `/api/audit/invite`, que repassa 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, 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 redirecionados pelo `AuthDialog` primeiro, para que o e-mail do remetente seja conhecido antes de os convites serem enviados. Direitos / cumprimento de benefícios é uma etapa posterior. -Alimentado pelo runtime `failproofai audit` — veja [Audit CLI](/pt-br/cli/audit) para o motor de escaneamento subjacente, flags suportadas e invariantes de cache por transcrito. 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 transcrito quanto o cache do resultado completo são rejeitados na leitura quando têm mais de 7 dias**, portanto o dashboard nunca serve silenciosamente um resultado de uma semana atrás — após o TTL, `/audit` cai em seu estado vazio e solicita uma nova execução. Clicar em `[ re-audit now ]` perto da parte inferior do relatório faz POST em `/api/audit/run` com `noCache: true` — a re-auditoria ignora o cache por transcrito e reescanieia todos os transcritos do zero em vez de retornar silenciosamente o resultado em cache — e o dashboard verifica `/api/audit/status` a 1Hz até a execução terminar; uma faixa de progresso rosa fixa é fixada ao topo do viewport durante a execução com um timer de tempo decorrido, e o resultado atualizado substitui o anterior no lugar em caso de 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 o escaneamento não encontrou transcritos) são exibidos separadamente. +Alimentado pelo runtime `failproofai audit` — consulte [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 cache de resultado completo são rejeitados na leitura quando têm mais de 7 dias**, para que o dashboard nunca sirva silenciosamente um resultado de uma semana atrás — após o TTL, `/audit` cai no estado vazio e solicita uma nova execução. Clicar em `[ re-audit now ]` perto do final do relatório faz POST para `/api/audit/run` com `noCache: true` — a re-auditoria ignora o cache por transcrição e reanalisa todas as transcrições do zero em vez de retornar silenciosamente o resultado em cache — e o dashboard verifica `/api/audit/status` a 1Hz até a execução terminar; uma faixa de progresso rosa fixada no topo do viewport durante a execução exibe um timer decorrido, e o resultado atualizado substitui o anterior no lugar ao término 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`). O estado vazio (sem cache ou expirado) e o estado de zero sessões (cache existe, mas a varredura não encontrou transcrições) são exibidos separadamente. ### Políticas -Uma página com duas abas para gerenciar políticas e revisar atividades. +Uma página com duas abas para gerenciar políticas e revisar atividade. - - - Selecione múltiplos CLIs de agentes que o failproofai protege a partir de um único painel — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi e Gemini CLI têm uma linha com status de instalação (`Active` / `Detected` / `Inactive`), o caminho de configurações de escopo do usuário e um destaque colorido pela marca. Marque ou desmarque os CLIs desejados 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) + + - Selecione múltiplos CLIs de agentes que o failproofai protege em um único painel — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Gemini CLI e Hermes têm uma linha com status de instalação (`Active` / `Detected` / `Inactive`), o caminho de configurações de escopo do 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 alterações em uma etapa. CLIs cujo binário é detectado no PATH são pré-selecionados. + - 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 personalizado para o arquivo de políticas - - - Histórico paginado completo de todos os eventos de hook disparados 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)_ / Gemini CLI _(beta)_), 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, azul-céu = Gemini CLI), nome da ferramenta, ID de sessão e o motivo para decisões deny/instruct - - Clique em um ID de sessão para abrir seu transcrito — o visualizador detecta automaticamente qual CLI disparou 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`) e renderiza o badge de CLI correspondente no cabeçalho + + - 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)_ / Gemini CLI _(beta)_ / Hermes), 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, celeste = Gemini CLI, índigo = Hermes), nome da ferramenta, ID de sessão e o motivo das decisões 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`, Hermes `~/.hermes/state.db`) e renderiza o badge de CLI correspondente no cabeçalho @@ -92,13 +92,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 possui um toggle 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 à medida que 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` como uma lista separada por vírgulas de nomes de 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: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -110,7 +110,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-o para configurações personalizadas: +Por padrão, o dashboard lê do diretório padrão de projetos do Claude Code. Substitua para configurações personalizadas: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -118,7 +118,7 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Acessando de um host não-localhost +## Acessando a partir de um host diferente de 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 +126,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 websocket de HMR (hot module reload), que é um recurso exclusivo de desenvolvimento. 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 @@ -145,5 +145,5 @@ 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 produção), não há websocket HMR nem problema de recurso dev cross-origin. \ No newline at end of file diff --git a/docs/pt-br/examples.mdx b/docs/pt-br/examples.mdx index 1dd3804f..1e1e47fc 100644 --- a/docs/pt-br/examples.mdx +++ b/docs/pt-br/examples.mdx @@ -10,7 +10,7 @@ Exemplos prontos para uso em cenários comuns. Cada um mostra como instalar e o ## Configurando hooks para Claude Code -Failproof AI se integra ao Claude Code por meio do seu [sistema de hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Quando você executa `failproofai policies --install`, ele registra comandos de hook no `settings.json` do Claude Code que são disparados a cada chamada de ferramenta. +Failproof AI se integra com Claude Code por meio do seu [sistema de hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). Quando você executa `failproofai policies --install`, ele registra comandos de hook no `settings.json` do Claude Code que disparam a cada chamada de ferramenta. @@ -28,14 +28,14 @@ Failproof AI se integra ao Claude Code por meio do seu [sistema de hooks](https: cat ~/.claude/settings.json | grep failproofai ``` - Você deverá ver entradas de hook para os eventos `PreToolUse`, `PostToolUse`, `Notification` e `Stop`. + Você deve ver entradas de hook para os eventos `PreToolUse`, `PostToolUse`, `Notification` e `Stop`. ```bash claude ``` - As políticas agora são executadas automaticamente a cada chamada de ferramenta. Tente pedir ao Claude que execute `sudo rm -rf /` — o comando será bloqueado. + As políticas agora são executadas automaticamente a cada chamada de ferramenta. Tente pedir ao Claude para executar `sudo rm -rf /` — o comando será bloqueado. @@ -43,7 +43,7 @@ Failproof AI se integra ao Claude Code por meio do seu [sistema de hooks](https: ## Configurando hooks para o Agents SDK -Se você está desenvolvendo com o [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), pode usar o mesmo sistema de hooks de forma programática. +Se você está desenvolvendo com o [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), você pode usar o mesmo sistema de hooks de forma programática. @@ -52,7 +52,7 @@ Se você está desenvolvendo com o [Agents SDK](https://docs.anthropic.com/en/do ``` - Passe os comandos de hook ao criar o processo do seu agente. Os hooks disparam da mesma forma que no Claude Code — via stdin/stdout JSON: + Passe comandos de hook ao criar o processo do seu agente. Os hooks disparam da mesma forma que no Claude Code — via JSON pelo stdin/stdout: ```bash failproofai --hook PreToolUse # chamado antes de cada ferramenta @@ -65,7 +65,7 @@ Se você está desenvolvendo com o [Agents SDK](https://docs.anthropic.com/en/do customPolicies.add({ name: "limit-to-project-dir", - description: "Keep the agent inside the project directory", + description: "Mantém o agente dentro do diretório do projeto", match: { events: ["PreToolUse"] }, fn: async (ctx) => { const path = String(ctx.toolInput?.file_path ?? ""); @@ -88,7 +88,7 @@ Se você está desenvolvendo com o [Agents SDK](https://docs.anthropic.com/en/do ## Bloquear comandos destrutivos -A configuração mais comum — impedir que agentes causem danos irreversíveis. +A configuração mais comum — impede que agentes causem danos irreversíveis. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh @@ -102,28 +102,28 @@ O que isso faz: --- -## Prevenir vazamento de segredos +## Evitar vazamento de segredos -Impede que agentes visualizem ou vazem credenciais na saída de ferramentas. +Impede que agentes vejam ou vazem credenciais na saída das ferramentas. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -Essas políticas disparam no `PostToolUse` — após a execução de uma ferramenta, elas limpam a saída antes que o agente a veja. +Esses hooks disparam no `PostToolUse` — após a execução de uma ferramenta, eles limpam a saída antes que o agente a veja. --- ## Receber alertas no Slack quando agentes precisam de atenção -Use o hook de notificação para encaminhar alertas de inatividade ao Slack. +Use o hook de notificação para encaminhar alertas de ociosidade para o Slack. ```javascript import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "slack-on-idle", - description: "Alert Slack when the agent is waiting for input", + description: "Alerta o Slack quando o agente está aguardando input", match: { events: ["Notification"] }, fn: async (ctx) => { const webhookUrl = process.env.SLACK_WEBHOOK_URL; @@ -160,14 +160,14 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c ## Manter agentes em uma branch -Impede que agentes troquem de branch ou façam push em branches protegidas. +Impede que agentes troquem de branch ou façam push para branches protegidas. ```javascript import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "stay-on-branch", - description: "Prevent the agent from checking out other branches", + description: "Impede o agente de fazer checkout em outras branches", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); @@ -184,14 +184,14 @@ customPolicies.add({ ## Exigir testes antes de commits -Lembra os agentes de executar os testes antes de fazer commit. +Lembra os agentes de executar testes antes de fazer commit. ```javascript import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "test-before-commit", - description: "Remind the agent to run tests before committing", + description: "Lembra o agente de executar testes antes de fazer commit", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); @@ -206,9 +206,9 @@ customPolicies.add({ --- -## Proteger um repositório de produção +## Bloquear um repositório de produção -Faça commit de uma configuração no nível do projeto para que todos os desenvolvedores do time utilizem as mesmas políticas. +Faça commit de uma configuração em nível de projeto para que todos os desenvolvedores da sua equipe utilizem as mesmas políticas. Crie `.failproofai/policies-config.json` no seu repositório: @@ -238,13 +238,13 @@ git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -Todo membro do time que tiver o failproofai instalado receberá essas regras automaticamente. +Todo membro da equipe que tiver o failproofai instalado receberá essas regras automaticamente. --- ## Construir um padrão de qualidade para toda a organização com políticas de convenção -A configuração de maior impacto: faça commit da pasta `.failproofai/policies/` no seu repositório com políticas adaptadas ao seu projeto. Todos os membros do time as recebem automaticamente — sem comandos de instalação, sem alterações de configuração. +A configuração de maior impacto: faça commit de `.failproofai/policies/` no seu repositório com políticas adaptadas ao seu projeto. Todos os membros da equipe as recebem automaticamente — sem comandos de instalação, sem alterações de configuração. @@ -256,8 +256,8 @@ A configuração de maior impacto: faça commit da pasta `.failproofai/policies/ // .failproofai/policies/team-policies.mjs import { customPolicies, allow, deny, instruct } from "failproofai"; - // Enforce your team's preferred package manager - // (or enable the built-in prefer-package-manager policy instead) + // Aplica o gerenciador de pacotes preferido da equipe + // (ou ative a política integrada prefer-package-manager) customPolicies.add({ name: "enforce-bun", match: { events: ["PreToolUse"] }, @@ -269,7 +269,7 @@ A configuração de maior impacto: faça commit da pasta `.failproofai/policies/ }, }); - // Remind the agent to run tests before committing + // Lembra o agente de executar testes antes de fazer commit customPolicies.add({ name: "test-before-commit", match: { events: ["PreToolUse"] }, @@ -290,7 +290,7 @@ A configuração de maior impacto: faça commit da pasta `.failproofai/policies/ ``` - À medida que o time encontrar novos pontos de falha, adicione políticas e faça push. Todos recebem a atualização no próximo `git pull`. Essas políticas se tornam um padrão de qualidade vivo que cresce junto com o time. + À medida que a equipe encontrar novos modos de falha, adicione políticas e faça push. Todos recebem a atualização no próximo `git pull`. Essas políticas se tornam um padrão de qualidade vivo que cresce junto com a sua equipe. @@ -302,6 +302,6 @@ O diretório [`examples/`](https://github.com/failproofai/failproofai/tree/main/ | Arquivo | O que demonstra | |---------|-----------------| -| `policies-basic.js` | Políticas iniciais — bloquear escritas em produção, force-push e scripts redirecionados | -| `policies-notification.js` | Alertas no Slack para notificações de inatividade e encerramento de sessão | +| `policies-basic.js` | Políticas iniciais — bloqueia escritas em produção, force-push e scripts redirecionados | +| `policies-notification.js` | Alertas no Slack para notificações de ociosidade e encerramento de sessão | | `policies-advanced/index.js` | Importações transitivas, hooks assíncronos, limpeza de saída no PostToolUse e tratamento do evento Stop | \ No newline at end of file diff --git a/docs/pt-br/for-agents.mdx b/docs/pt-br/for-agents.mdx index d7ccbca6..b397ce51 100644 --- a/docs/pt-br/for-agents.mdx +++ b/docs/pt-br/for-agents.mdx @@ -1,9 +1,9 @@ --- title: "Para agentes" -description: "Adicione o conhecimento do Failproof AI ao seu agente de codificação em um único comando. Funciona com Claude Code, Cursor, Windsurf e muito mais." +description: "Adicione o conhecimento do Failproof AI ao seu agente de programação com um único comando. Compatível com Claude Code, Cursor, Windsurf e muito mais." --- -Adicione a referência completa do Failproof AI ao seu agente de codificação em um único comando. Funciona com Claude Code, Cursor, Windsurf e qualquer outro agente que suporte skills. +Adicione a referência completa do Failproof AI ao seu agente de programação com um único comando. Compatível com Claude Code, Cursor, Windsurf e qualquer outro agente que suporte skills. ```bash npx skills add https://docs.befailproof.ai @@ -15,24 +15,24 @@ O `npx skills` detecta quais agentes você tem instalados e adiciona a skill no | Área | O que está incluído | |------|----------------| -| Políticas | Nomes de políticas integradas, tipos de eventos, parâmetros, habilitar/desabilitar | -| Políticas personalizadas | `customPolicies.add()`, filtros de correspondência, API `allow`/`deny`/`instruct` | +| Policies | Nomes de policies nativas, tipos de eventos, parâmetros, habilitar/desabilitar | +| Custom policies | `customPolicies.add()`, filtros de correspondência, API `allow`/`deny`/`instruct` | | Objeto de contexto | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | | Configuração | Estrutura do `policies-config.json`, mesclagem de escopos, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, escopos | -| Dashboard | Visualizador de sessões, atividade de políticas, variáveis de ambiente | -| Arquitetura | Fluxo do handler de hooks, códigos de saída, contrato stdin/stdout | +| Dashboard | Visualizador de sessões, atividade de policies, variáveis de ambiente | +| Arquitetura | Fluxo do hook handler, códigos de saída, contrato stdin/stdout | ## A skill está completa? -O Mintlify gera o `llms.txt` a partir de todas as páginas da navegação. A documentação do Failproof AI cobre a API completa — cada política, opção e exemplo está incluído. Se você encontrar algo faltando, a fonte está em `https://docs.befailproof.ai/llms-full.txt`. +O Mintlify gera o `llms.txt` a partir de todas as páginas da navegação. A documentação do Failproof AI cobre a API completa — cada policy, opção e exemplo está incluído. Se você encontrar algo faltando, o conteúdo-fonte está em `https://docs.befailproof.ai/llms-full.txt`. Para contexto direcionado, aponte diretamente para uma página específica: ```bash -# Apenas a API de políticas personalizadas +# Apenas a API de custom policies npx skills add https://docs.befailproof.ai/custom-policies -# Apenas as políticas integradas +# Apenas as built-in policies npx skills add https://docs.befailproof.ai/built-in-policies ``` \ No newline at end of file diff --git a/docs/pt-br/getting-started.mdx b/docs/pt-br/getting-started.mdx index ca7fa09a..133c5565 100644 --- a/docs/pt-br/getting-started.mdx +++ b/docs/pt-br/getting-started.mdx @@ -1,6 +1,6 @@ --- title: Primeiros passos -description: "Instale o failproofai, ative as políticas e deixe seus agentes rodarem de forma confiável" +description: "Instale o failproofai, ative as políticas e deixe seus agentes rodando com confiabilidade" icon: rocket --- @@ -37,9 +37,9 @@ bun add -g failproofai failproofai policies --install ``` - Isso grava entradas de hook nos CLIs de agentes instalados (o `~/.claude/settings.json` do Claude Code, o `~/.codex/hooks.json` do OpenAI Codex, o `~/.copilot/hooks/failproofai.json` do GitHub Copilot CLI, o `~/.cursor/hooks.json` do Cursor Agent, o shim de plugin gerado pelo OpenCode em `~/.config/opencode/plugins/failproofai.mjs` mais uma entrada de registro no array `plugin` do `~/.config/opencode/opencode.json`, o `~/.pi/agent/settings.json` do Pi, ou o `~/.gemini/settings.json` do Gemini CLI). Quando mais de um estiver presente, você será solicitado a escolher; passe `--cli claude codex copilot cursor opencode pi gemini` (qualquer subconjunto) para pular a confirmação. + Isso registra entradas de hook nos CLIs de agente instalados (o `~/.claude/settings.json` do Claude Code, o `~/.codex/hooks.json` do OpenAI Codex, o `~/.copilot/hooks/failproofai.json` do GitHub Copilot CLI, o `~/.cursor/hooks.json` do Cursor Agent, o shim de plugin gerado pelo OpenCode em `~/.config/opencode/plugins/failproofai.mjs` mais uma entrada de registro no array `plugin` de `~/.config/opencode/opencode.json`, o `~/.pi/agent/settings.json` do Pi, o `~/.gemini/settings.json` do Gemini CLI ou o `~/.hermes/config.yaml` do Hermes). Se mais de um estiver presente, você será solicitado a escolher; passe `--cli claude codex copilot cursor opencode pi gemini hermes` (qualquer subconjunto) para pular a seleção. - O suporte ao GitHub Copilot CLI, Cursor Agent, OpenCode, Pi e Gemini CLI está em **beta** — instale com `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi` ou `--cli gemini`. + O suporte ao GitHub Copilot CLI, Cursor Agent, OpenCode, Pi e Gemini CLI está em **beta** — instale com `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi` ou `--cli gemini`. O Hermes (hermes-agent, um gateway Slack/Telegram) é instalado no escopo de usuário com `--cli hermes` e é **também** uma fonte de auditoria offline. ```bash failproofai policies --install --scope project @@ -49,6 +49,7 @@ bun add -g failproofai failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project + failproofai policies --install --cli hermes --scope user failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` @@ -57,7 +58,7 @@ bun add -g failproofai failproofai policies ``` - Exibe todas as políticas, se estão habilitadas e quaisquer parâmetros configurados. + Exibe todas as políticas, se estão ativadas e quaisquer parâmetros configurados. ```bash @@ -67,7 +68,7 @@ bun add -g failproofai Abre um painel local em `http://localhost:8020` onde você pode navegar pelas sessões, inspecionar chamadas de ferramentas e gerenciar políticas. - Inicie o Claude Code normalmente. Se o agente tentar algo arriscado, o failproofai o intercepta automaticamente. Deixe-o rodando sem supervisão e revise o que aconteceu no painel. + Inicie o Claude Code normalmente. Se o agente tentar algo arriscado, o failproofai intercepta automaticamente. Deixe-o rodando sem supervisão e revise o que aconteceu no painel. @@ -95,9 +96,9 @@ As políticas rodam no seu processo local. Nada é enviado para um serviço remo --- -## Configure políticas para a equipe com políticas baseadas em convenção +## Configurar políticas de equipe com políticas baseadas em convenção -A maneira mais rápida de estabelecer padrões de qualidade em toda a equipe é a convenção `.failproofai/policies/`. Coloque arquivos de política nesse diretório e eles são carregados automaticamente — sem flags, sem alterações de configuração, sem comandos de instalação. +A maneira mais rápida de estabelecer padrões de qualidade em toda a sua equipe é a convenção `.failproofai/policies/`. Coloque arquivos de política nesse diretório e eles são carregados automaticamente — sem flags, sem alterações de configuração, sem comandos de instalação. @@ -131,18 +132,18 @@ A maneira mais rápida de estabelecer padrões de qualidade em toda a equipe é }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - Todo membro da equipe que tiver o failproofai instalado receberá essas políticas automaticamente. Nenhuma configuração por desenvolvedor é necessária. + Todo membro da equipe que tiver o failproofai instalado receberá essas políticas automaticamente. Sem configuração por desenvolvedor. -Faça commit de `.failproofai/policies/` no seu repositório para que toda a equipe compartilhe os mesmos padrões. À medida que a equipe descobre novos modos de falha, adicione políticas e faça push — todos recebem a atualização no próximo `git pull`. Com o tempo, essas políticas se tornam um padrão de qualidade vivo que continua melhorando. +Faça commit de `.failproofai/policies/` no seu repositório para que toda a equipe compartilhe os mesmos padrões. À medida que a equipe descobrir novos modos de falha, adicione políticas e faça push — todos recebem a atualização no próximo `git pull`. Com o tempo, essas políticas se tornam um padrão de qualidade vivo que continua melhorando. --- @@ -187,7 +188,7 @@ Remove as entradas de hook do `~/.claude/settings.json`. Os arquivos de configur Escreva suas próprias políticas em JavaScript - + Monitore sessões e revise a atividade das políticas diff --git a/docs/pt-br/introduction.mdx b/docs/pt-br/introduction.mdx index 7121b58f..aaf26213 100644 --- a/docs/pt-br/introduction.mdx +++ b/docs/pt-br/introduction.mdx @@ -1,15 +1,15 @@ --- title: "Failproof AI" -description: "FailproofAI oferece aos agentes de IA 39 políticas de falha integradas que detectam loops, vazamentos de segredos, chamadas destrutivas de ferramentas e muito mais em uma única instalação." +description: "FailproofAI oferece 39 políticas de falha integradas para agentes de IA que detectam loops, vazamentos de segredos, chamadas de ferramentas destrutivas e muito mais em uma única instalação." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -Hooks e políticas para **tratamento de falhas de IA**, **recuperação de erros** e **confiabilidade de LLM**. Mantenha seus agentes de IA confiáveis e em execução autônoma no **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI** e no **Agents SDK**. +Hooks e políticas para **tratamento de falhas de IA**, **recuperação de erros** e **confiabilidade de LLMs**. Mantenha seus agentes de IA confiáveis e funcionando de forma autônoma no **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, **Hermes** e no **Agents SDK**. -Agentes de IA falham de maneiras previsíveis. Eles executam comandos destrutivos, vazam segredos, desviam das tarefas, ficam presos em loops ou fazem push direto para a main. Sem supervisão, pequenas falhas se transformam em interrupções, credenciais expostas e trabalho perdido. +Agentes de IA falham de maneiras previsíveis. Eles executam comandos destrutivos, vazam segredos, desviam da tarefa, ficam presos em loops ou fazem push direto para a branch principal. Sem supervisão, falhas pequenas evoluem para quedas de serviço, credenciais expostas e trabalho perdido. -FailproofAI resolve isso com **políticas**. Essas regras se conectam a cada chamada de ferramenta do agente para **detectar falhas**, **mitigá-las** (bloquear, instruir, sanitizar) e **alertar você** quando algo precisa de atenção. Um painel local permite revisar cada chamada de ferramenta, falha do agente e ação de recuperação após o fato. +O FailproofAI resolve isso com **políticas**. Essas regras se integram a cada chamada de ferramenta do agente para **detectar falhas**, **mitigá-las** (bloquear, instruir, sanitizar) e **alertar você** quando algo precisa de atenção. Um painel local permite revisar todas as chamadas de ferramenta, falhas do agente e ações de recuperação posteriormente. Nenhum dado sai da sua máquina. @@ -18,7 +18,7 @@ Nenhum dado sai da sua máquina. - Bloqueie comandos destrutivos, evite vazamento de segredos, mantenha os agentes dentro dos limites do projeto e muito mais. Tudo pronto para uso. + Bloqueie comandos destrutivos, evite vazamentos de segredos, mantenha os agentes dentro dos limites do projeto e muito mais. Tudo pronto para uso. @@ -26,11 +26,11 @@ Nenhum dado sai da sua máquina. - Veja o que seus agentes fizeram enquanto você estava ausente. Navegue pelas sessões, inspecione chamadas de ferramentas e revise onde as políticas foram acionadas. + Veja o que seus agentes fizeram enquanto você estava ausente. Navegue por sessões, inspecione chamadas de ferramentas e revise onde as políticas foram acionadas. - - Ajuste qualquer política sem escrever código. Defina listas de permissões, branches protegidos ou limites por projeto ou globalmente. + + Ajuste qualquer política sem escrever código. Defina listas de permissões, branches protegidas ou limites por projeto ou globalmente. @@ -54,4 +54,4 @@ failproofai policies --install # enable policies (or skip — `failproofai` wi failproofai # launch the dashboard ``` -Consulte o guia [Primeiros passos](/pt-br/getting-started) para um passo a passo completo. \ No newline at end of file +Consulte o guia de [Primeiros passos](/pt-br/getting-started) para o passo a passo completo. \ No newline at end of file diff --git a/docs/pt-br/package-aliases.mdx b/docs/pt-br/package-aliases.mdx index 90281f9e..7966f559 100644 --- a/docs/pt-br/package-aliases.mdx +++ b/docs/pt-br/package-aliases.mdx @@ -1,5 +1,5 @@ --- -title: Aliases de Pacote +title: Aliases de Pacotes description: "Aliases registrados para prevenção de typosquatting e como funcionam" icon: copy --- @@ -16,11 +16,11 @@ bun add -g failproofai --- -## Por que somos donos dos nomes de alias +## Por que possuímos os nomes de alias -Typosquatting é um ataque comum à cadeia de suprimentos de software, onde um agente malicioso registra um nome de pacote que difere por apenas um caractere de um pacote popular. Usuários desatentos que digitam errado o comando de instalação acabam executando código controlado pelo atacante com acesso total ao sistema — exatamente o tipo de ameaça que o Failproof AI foi projetado para combater. +Typosquatting é um ataque comum à cadeia de suprimentos de software, no qual um agente malicioso registra um nome de pacote que difere por apenas um caractere de um pacote popular. Usuários desatentos que digitam incorretamente o comando de instalação acabam executando código controlado pelo atacante com acesso total ao sistema — exatamente o tipo de ameaça que o Failproof AI foi projetado para combater. -Para eliminar essa superfície de ataque, **assumimos preventivamente todos os erros de digitação comuns e variantes de formatação** de `failproofai` no npm. Nenhum desses nomes pode ser registrado por terceiros. Cada um é um proxy simples que instala e delega ao pacote real `failproofai`. +Para eliminar essa superfície de ataque, **nós registramos preventivamente todas as variações ortográficas comuns e variantes de formatação** de `failproofai` no npm. Nenhum desses nomes pode ser registrado por terceiros. Cada um é um proxy leve que instala e delega para o pacote real `failproofai`. --- @@ -31,31 +31,31 @@ Para eliminar essa superfície de ataque, **assumimos preventivamente todos os e | Pacote | Status | |--------|--------| | `failproof` | ✅ Publicado | -| `failproof-ai` | ⏳ Aguardando suporte do npm | -| `fail-proof-ai` | ⏳ Aguardando suporte do npm | -| `failproof_ai` | ⏳ Aguardando suporte do npm | -| `fail_proof_ai` | ⏳ Aguardando suporte do npm | -| `fail-proofai` | ⏳ Aguardando suporte do npm | +| `failproof-ai` | ⏳ Aguardando aprovação do npm | +| `fail-proof-ai` | ⏳ Aguardando aprovação do npm | +| `failproof_ai` | ⏳ Aguardando aprovação do npm | +| `fail_proof_ai` | ⏳ Aguardando aprovação do npm | +| `fail-proofai` | ⏳ Aguardando aprovação do npm | -**Erros de digitação `failprof*`** — faltando um `o` em "proof": +**Erros de digitação `failprof*`** — sem um `o` em "proof": | Pacote | Status | |--------|--------| | `failprof` | ✅ Publicado | | `failprof-ai` | ✅ Publicado | -| `failprofai` | ⏳ Aguardando suporte do npm | -| `fail-prof-ai` | ⏳ Aguardando suporte do npm | -| `failprof_ai` | ⏳ Aguardando suporte do npm | +| `failprofai` | ⏳ Aguardando aprovação do npm | +| `fail-prof-ai` | ⏳ Aguardando aprovação do npm | +| `failprof_ai` | ⏳ Aguardando aprovação do npm | -**Erros de digitação `faliproof*`** — `a` e `i` trocados de posição: +**Erros de digitação `faliproof*`** — letras `a` e `i` invertidas: | Pacote | Status | |--------|--------| | `faliproof` | ✅ Publicado | | `faliproof-ai` | ✅ Publicado | -| `faliproofai` | ⏳ Aguardando suporte do npm | +| `faliproofai` | ⏳ Aguardando aprovação do npm | -> **Por que estão pendentes?** A política antisspam do npm bloqueia nomes que, após remoção de pontuação e verificações de similaridade, normalizam para a mesma string de um pacote já existente. Entramos em contato com o suporte do npm para reservar esses nomes com fins de proteção contra squatting. Eles serão ativados após aprovação. +> **Por que "aguardando aprovação"?** A política de prevenção de spam do npm bloqueia nomes que, após remoção de pontuação e verificações de similaridade, são normalizados para a mesma string de um pacote já existente. Entramos em contato com o suporte do npm para reservar esses nomes com fins anti-typosquatting. Eles serão ativados após aprovação. Você pode verificar que qualquer alias publicado pertence a nós: @@ -70,13 +70,13 @@ npm info failproof Cada pacote alias: -1. Lista `failproofai` como dependência — fazendo com que o pacote real (incluindo a configuração do hook `postinstall`) seja executado na instalação -2. Expõe um binário com seu próprio nome (ex.: `failprof-ai`) que repassa todos os argumentos para o binário `failproofai` +1. Lista `failproofai` como dependência — assim, o pacote real (incluindo a configuração do hook `postinstall`) é executado durante a instalação +2. Expõe um binário com o mesmo nome do alias (ex.: `failprof-ai`) que encaminha todos os argumentos para o binário `failproofai` -O proxy é um script Node de duas linhas; não há lógica adicional, chamadas de rede nem coleta de dados além do que o próprio `failproofai` realiza. +O proxy é um script Node de duas linhas; não há nenhuma lógica adicional, chamadas de rede ou coleta de dados além do que o próprio `failproofai` realiza. --- -## Se você encontrar um nome que não cobrimos +## Se você encontrar um nome que esquecemos Abra uma issue em [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) e nós o registraremos. \ No newline at end of file diff --git a/docs/pt-br/testing.mdx b/docs/pt-br/testing.mdx index e377877e..190f715b 100644 --- a/docs/pt-br/testing.mdx +++ b/docs/pt-br/testing.mdx @@ -1,26 +1,26 @@ --- title: Testes -description: "Testes unitários, testes E2E e utilitários de teste" +description: "Testes unitários, testes E2E e helpers de teste" icon: flask-vial --- -failproofai possui duas suítes de testes: **testes unitários** (rápidos, com mocks) e **testes end-to-end** (invocações reais de subprocessos). +failproofai possui dois conjuntos de testes: **testes unitários** (rápidos, com mocks) e **testes end-to-end** (invocações reais de subprocessos). --- ## Executando os testes ```bash -# Executar todos os testes unitários uma vez +# Executa todos os testes unitários uma vez bun run test:run -# Executar testes unitários em modo watch +# Executa os testes unitários em modo watch bun run test -# Executar testes E2E (requer configuração - veja abaixo) +# Executa os testes E2E (requer configuração - veja abaixo) bun run test:e2e -# Verificar tipos sem compilar +# Verifica tipos sem compilar bunx tsc --noEmit # Lint @@ -31,17 +31,17 @@ bun run lint ## Testes unitários -Os testes unitários ficam em `__tests__/` e usam [Vitest](https://vitest.dev) com `jsdom`. +Os testes unitários ficam em `__tests__/` e usam o [Vitest](https://vitest.dev) com `jsdom`. ```text __tests__/ hooks/ builtin-policies.test.ts # Lógica de políticas para cada builtin - hooks-config.test.ts # Carregamento de configuração e mesclagem de escopos + hooks-config.test.ts # Carregamento de config e mesclagem de escopos policy-evaluator.test.ts # Injeção de parâmetros e ordem de avaliação custom-hooks-registry.test.ts # Registro globalThis: add/get/clear custom-hooks-loader.test.ts # Loader ESM, imports transitivos, tratamento de erros - manager.test.ts # Operações install/remove/list + manager.test.ts # Operações de install/remove/list components/ sessions-list.test.tsx # Componente de lista de sessões project-list.test.tsx # Componente de lista de projetos @@ -110,7 +110,7 @@ describe("block-sudo", () => { ## Testes end-to-end -Os testes E2E invocam o binário real do `failproofai` como subprocesso, enviam um payload JSON via stdin e verificam a saída no stdout e o código de saída. Isso testa o caminho completo de integração que o Claude Code utiliza. +Os testes E2E invocam o binário real do `failproofai` como subprocesso, enviam um payload JSON via stdin e verificam a saída no stdout e o código de saída. Isso testa o caminho de integração completo que Claude Code utiliza. ### Configuração @@ -133,26 +133,26 @@ Recompile o `dist/` sempre que alterar a API pública de hooks (`src/hooks/custo ```text __tests__/e2e/ helpers/ - hook-runner.ts # Inicializa o binário, envia payload JSON, captura código de saída + stdout + stderr + hook-runner.ts # Inicia o binário, envia payload JSON, captura código de saída + stdout + stderr fixture-env.ts # Diretórios temporários isolados por teste com arquivos de configuração - payloads.ts # Fábricas de payload compatíveis com Claude para cada tipo de evento + payloads.ts # Fábricas de payloads fiéis ao Claude para cada tipo de evento hooks/ builtin-policies.e2e.test.ts # Cada política builtin com subprocesso real custom-hooks.e2e.test.ts # Carregamento e avaliação de hooks customizados - config-scopes.e2e.test.ts # Mesclagem de configuração entre escopos project/local/global + config-scopes.e2e.test.ts # Mesclagem de config entre escopos project/local/global policy-params.e2e.test.ts # Injeção de parâmetros para cada política parametrizada ``` -### Usando os utilitários E2E +### Usando os helpers E2E -**`FixtureEnv`** — ambiente isolado por teste: +**`FixtureEnv`** - ambiente isolado por teste: ```typescript import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - diretório temporário; passe como payload.cwd para carregar .failproofai/policies-config.json -// env.home - diretório home isolado; sem vazamentos do ~/.failproofai real +// env.cwd - diretório temporário; passe como payload.cwd para usar .failproofai/policies-config.json +// env.home - home dir isolada; sem vazamento do ~/.failproofai real env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -164,7 +164,7 @@ env.writeConfig({ `createFixtureEnv()` registra a limpeza via `afterEach` automaticamente. -**`runHook`** — invoca o binário: +**`runHook`** - invoca o binário: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** — fábricas de payload prontas para uso: +**`Payloads`** - fábricas de payload prontas para uso: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -245,16 +245,16 @@ describe("block-rm-rf (E2E)", () => { Os testes E2E usam `vitest.config.e2e.mts` com: -- `environment: "node"` — sem globals de navegador -- `pool: "forks"` — isolamento real de processos (os testes inicializam subprocessos) -- `testTimeout: 20_000` — 20s por teste (inicialização do binário + avaliação do hook) +- `environment: "node"` - sem necessidade de globals do navegador +- `pool: "forks"` - isolamento real de processos (os testes iniciam subprocessos) +- `testTimeout: 20_000` - 20s por teste (inicialização do binário + avaliação do hook) -O pool `forks` é importante: workers baseados em threads compartilham `globalThis`, o que pode interferir em testes que inicializam subprocessos. Forks baseados em processos evitam esse problema. +O pool `forks` é importante: workers baseados em threads compartilham o `globalThis`, o que pode interferir em testes que iniciam subprocessos. Forks baseados em processos evitam esse problema. --- ## CI -A execução completa de CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) deve passar antes do merge. A suíte E2E é executada como um job de CI separado, em paralelo. +A execução completa de CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) deve passar antes do merge. O conjunto de testes E2E é executado como um job de CI separado, em paralelo. -Consulte [Contributing](../CONTRIBUTING.md) para o checklist completo de pré-merge. \ No newline at end of file +Consulte [Contributing](../CONTRIBUTING.md) para o checklist completo pré-merge. \ No newline at end of file diff --git a/docs/ru/architecture.mdx b/docs/ru/architecture.mdx index 92a263c1..d2b01b77 100644 --- a/docs/ru/architecture.mdx +++ b/docs/ru/architecture.mdx @@ -1,11 +1,11 @@ --- --- title: Архитектура -description: "Как работают обработчик крючков, загрузка конфигурации и оценка политик" +description: "Как работают обработчик хука, загрузка конфигурации и оценка политик" icon: sitemap --- -Этот документ объясняет внутреннее устройство failproofai: как система крючков перехватывает вызовы инструментов агента, как загружается и объединяется конфигурация, как оцениваются политики и как панель мониторинга отслеживает активность агента. +Этот документ объясняет, как failproofai работает внутри: как система хуков перехватывает вызовы инструментов агента, как загружается и объединяется конфигурация, как оцениваются политики и как панель мониторинга отслеживает активность агента. --- @@ -13,18 +13,18 @@ icon: sitemap failproofai состоит из двух независимых подсистем: -1. **Обработчик крючков** — быстрый CLI подпроцесс, который Claude Code вызывает при каждом вызове инструмента агента. Оценивает политики и возвращает решение. -2. **Монитор агента (Панель)** — веб-приложение Next.js для мониторинга сеансов агента и управления политиками. +1. **Обработчик хука** — быстрый CLI подпроцесс, который Claude Code вызывает при каждом вызове инструмента агента. Оценивает политики и возвращает решение. +2. **Agent Monitor (Dashboard)** — веб-приложение Next.js для мониторинга сеансов агента и управления политиками. -Обе подсистемы используют файлы конфигурации в `~/.failproofai/` и в директории проекта `.failproofai/`, но работают как отдельные процессы и взаимодействуют только через файловую систему. +Обе подсистемы используют общие файлы конфигурации в `~/.failproofai/` и директории `.failproofai/` проекта, но запускаются как отдельные процессы и взаимодействуют только через файловую систему. --- -## Обработчик крючков +## Обработчик хука ### Интеграция с Claude Code -Когда вы выполняете `failproofai policies --install`, он записывает записи вроде этой в `~/.claude/settings.json`: +Когда вы запускаете `failproofai policies --install`, она записывает записи вроде этой в `~/.claude/settings.json`: ```json { @@ -45,7 +45,7 @@ failproofai состоит из двух независимых подсисте } ``` -Claude Code затем вызывает `failproofai --hook PreToolUse` как подпроцесс перед каждым вызовом инструмента, передавая JSON-полезную нагрузку на stdin. +Затем Claude Code вызывает `failproofai --hook PreToolUse` как подпроцесс перед каждым вызовом инструмента, передавая JSON-полезную нагрузку на stdin. ### Формат полезной нагрузки @@ -63,11 +63,11 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как Для событий `PostToolUse` полезная нагрузка также содержит `tool_result` с выводом инструмента. -Обработчик применяет лимит stdin в 1 МБ. Полезные нагрузки, превышающие это значение, отбрасываются и все политики неявно разрешают операцию. +Обработчик устанавливает лимит stdin в 1 МБ. Полезные нагрузки, превышающие это значение, отбрасываются и все политики неявно разрешают. ### Формат ответа -**Запретить (PreToolUse):** +**Deny (PreToolUse):** ```json { "hookSpecificOutput": { @@ -77,7 +77,7 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как } ``` -**Запретить (PostToolUse):** +**Deny (PostToolUse):** ```json { "hookSpecificOutput": { @@ -86,7 +86,7 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как } ``` -**Инструктировать (любое событие кроме Stop):** +**Instruct (любое событие кроме Stop):** ```json { "hookSpecificOutput": { @@ -95,20 +95,20 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как } ``` -**Событие Stop с инструкцией:** +**Событие Stop instruct:** - Код выхода: `2` -- Причина записывается в stderr (не в stdout) +- Причина записана в stderr (не stdout) -**Разрешить:** +**Allow:** - Код выхода: `0` - Пустой stdout -**Разрешить с сообщением:** +**Allow с сообщением:** -`allow(message)` позволяет политике отправить информационный контекст обратно Claude даже когда операция разрешена. Обработчик крючков записывает следующий JSON в **stdout** (не в файл конфигурации — это ответ обработчика на Claude Code, так же как запрет и инструкции выше): +`allow(message)` позволяет политике отправить информационный контекст обратно Claude, даже когда операция разрешена. Обработчик хука записывает следующий JSON в **stdout** (не в файл конфигурации — это ответ обработчика Claude Code, как и ответы deny и instruct выше): ```json -// Записано в stdout процессом обработчика крючков +// Записано в stdout процессом обработчика хука { "hookSpecificOutput": { "additionalContext": "All CI checks passed on branch 'feat/my-feature'." @@ -116,8 +116,8 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как } ``` - Код выхода: `0` (операция разрешена) -- Когда несколько политик возвращают `allow` с сообщением, их сообщения объединяются новыми строками в одну строку `additionalContext` -- Если ни одна политика не предоставляет сообщение, stdout пустой (как и раньше) +- Когда несколько политик возвращают `allow` с сообщением, их сообщения объединяются с переводами строк в одну строку `additionalContext` +- Если ни одна политика не предоставляет сообщение, stdout пустой (как раньше) ### Конвейер обработки @@ -125,19 +125,19 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как ```text stdin JSON - → parse payload (max 1 MB) - → extract session metadata (session_id, cwd, tool_name, tool_input, etc.) - → readMergedHooksConfig(cwd) ← merges project + local + global config - → register enabled builtin policies with resolved params - → load custom policies from customPoliciesPath (if set) - → register custom policies into policy registry - → evaluate all policies (builtins first, then custom) - → first deny short-circuits - → instruct decisions accumulate - → allow messages accumulate - → write JSON decision to stdout - → persist event to ~/.failproofai/hook-activity.jsonl - → exit + → парсинг полезной нагрузки (макс 1 МБ) + → извлечение метаданных сеанса (session_id, cwd, tool_name, tool_input, и т. д.) + → readMergedHooksConfig(cwd) ← объединяет конфигурацию проекта + локальную + глобальную + → регистрация включенных встроенных политик с разрешенными параметрами + → загрузка пользовательских политик из customPoliciesPath (если установлено) + → регистрация пользовательских политик в реестре политик + → оценка всех политик (встроенные первыми, затем пользовательские) + → первый deny вызывает короткое замыкание + → решения instruct накапливаются + → сообщения allow накапливаются + → запись решения JSON в stdout + → сохранение события в ~/.failproofai/hook-activity.jsonl + → выход ``` Весь процесс выполняется менее чем за 100 мс для типичных полезных нагрузок без вызовов LLM. @@ -146,7 +146,7 @@ stdin JSON ## Загрузка конфигурации -`src/hooks/hooks-config.ts` реализует загрузку конфигурации с тремя уровнями видимости. +`src/hooks/hooks-config.ts` реализует загрузку конфигурации с тремя областями. ```text [1] {cwd}/.failproofai/policies-config.json ← проект (наивысший приоритет) @@ -155,12 +155,12 @@ stdin JSON ``` Логика объединения: -- `enabledPolicies` — дедублицированное объединение всех трех файлов -- `policyParams` — ключ для каждой политики, первый файл, который его определяет, полностью побеждает +- `enabledPolicies` — дедуплицированное объединение всех трех файлов +- `policyParams` — по ключу политики, первый файл, который его определяет, побеждает полностью - `customPoliciesPath` — первый файл, который его определяет, побеждает - `llm` — первый файл, который его определяет, побеждает -Веб-панель использует `readHooksConfig()` (только глобальное) для чтения и записи, так как она не вызывается с cwd проекта. +Веб-панель использует `readHooksConfig()` (только глобальная) для чтения и записи, так как она не вызывается с cwd проекта. --- @@ -170,18 +170,18 @@ stdin JSON Для каждой политики: -1. Найти схему `params` политики (если она есть). -2. Прочитать `policyParams[policy.name]` из объединенной конфигурации. -3. Объединить предоставленные пользователем значения со значениями по умолчанию схемы для получения `ctx.params`. -4. Вызвать `policy.fn(ctx)` с разрешенным контекстом. -5. Если результат `deny`, остановиться немедленно и вернуть это решение. -6. Если результат `instruct`, накопить сообщение и продолжить. -7. Если результат `allow`, перейти к следующей политике. +1. Ищет схему `params` политики (если она есть). +2. Читает `policyParams[policy.name]` из объединенной конфигурации. +3. Объединяет предоставленные пользователем значения над значениями по умолчанию схемы для создания `ctx.params`. +4. Вызывает `policy.fn(ctx)` с разрешенным контекстом. +5. Если результат `deny`, останавливается немедленно и возвращает это решение. +6. Если результат `instruct`, накапливает сообщение и продолжает. +7. Если результат `allow`, продолжает к следующей политике. После выполнения всех политик: -- Если возвращен какой-либо `deny`, выдать ответ с запретом. -- Если собраны какие-либо `instruct`, выдать единый ответ с инструкцией со всеми сообщениями, объединенными вместе. -- В противном случае выдать ответ с разрешением (пустой stdout, выход 0). +- Если был возвращен какой-либо `deny`, выдает ответ deny. +- Если были собраны возвращаемые `instruct`, выдает один ответ instruct со всеми сообщениями объединены. +- В противном случае выдает ответ allow (пустой stdout, выход 0). --- @@ -205,15 +205,15 @@ interface BuiltinPolicyDefinition { } ``` -Политики, которые принимают `params`, объявляют `PolicyParamsSchema` с типами и значениями по умолчанию для каждого параметра. Оценщик политик внедряет разрешенные значения в `ctx.params` перед вызовом `fn`. Функции политик читают `ctx.params` без проверок на null, потому что значения по умолчанию всегда применяются первыми. +Политики, которые принимают `params`, объявляют `PolicyParamsSchema` с типами и значениями по умолчанию для каждого параметра. Оценщик политик внедряет разрешенные значения в `ctx.params` перед вызовом `fn`. Функции политик читают `ctx.params` без защиты от нулевых значений, потому что значения по умолчанию всегда применяются сначала. -Сопоставление шаблонов внутри политик использует разобранные токены команд (argv), а не прямое сопоставление строк. Это предотвращает обход через инъекции операторов оболочки (например, шаблон для `sudo systemctl status *` не может быть обойден путем добавления `; rm -rf /` к команде). +Сопоставление паттернов внутри политик использует проанализированные токены команды (argv), а не сопоставление по сырой строке. Это предотвращает обход с помощью инъекции оператора оболочки (например, паттерн для `sudo systemctl status *` не может быть обойден добавлением `; rm -rf /` к команде). --- ## Пользовательские политики -`src/hooks/custom-hooks-registry.ts` реализует реестр на основе `globalThis`: +`src/hooks/custom-hooks-registry.ts` реализует реестр, основанный на `globalThis`: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -223,28 +223,28 @@ export const customPolicies = { }; export function getCustomHooks(): CustomHook[] { ... } -export function clearCustomHooks(): void { ... } // used in tests +export function clearCustomHooks(): void { ... } // используется в тестах ``` -`src/hooks/custom-hooks-loader.ts` загружает файл политик пользователя: +`src/hooks/custom-hooks-loader.ts` загружает файл политики пользователя: -1. Прочитать `customPoliciesPath` из конфигурации; пропустить если отсутствует. -2. Разрешить абсолютный путь; проверить существование файла. -3. Переписать все импорты `from "failproofai"` на фактический путь dist, чтобы `customPolicies` разрешился на тот же реестр `globalThis`. -4. Рекурсивно переписать переходные локальные импорты для обеспечения совместимости ESM. -5. Записать временные файлы `.mjs` и `import()` файл точки входа. -6. Вызвать `getCustomHooks()` для получения зарегистрированных крючков. -7. Очистить все временные файлы в блоке `finally`. +1. Читает `customPoliciesPath` из конфигурации; пропускает, если отсутствует. +2. Разрешает абсолютный путь; проверяет, существует ли файл. +3. Переписывает все импорты `from "failproofai"` на фактический путь dist, чтобы `customPolicies` разрешился на один и тот же реестр `globalThis`. +4. Рекурсивно переписывает переходящие локальные импорты для обеспечения совместимости ESM. +5. Записывает временные файлы `.mjs` и `import()` файл записи. +6. Вызывает `getCustomHooks()` для получения зарегистрированных хуков. +7. Очищает все временные файлы в блоке `finally`. При любой ошибке (файл не найден, синтаксическая ошибка, ошибка импорта) ошибка регистрируется в `~/.failproofai/hook.log` и загрузчик возвращает пустой массив. Встроенные политики не затрагиваются. -Пользовательские политики оцениваются после всех встроенных политик. Пользовательская политика `deny` по-прежнему короткозамыкает дальнейшие пользовательские политики (но все встроенные уже были выполнены к этому моменту). +Пользовательские политики оцениваются после всех встроенных политик. `deny` пользовательской политики все еще вызывает короткое замыкание для дальнейших пользовательских политик (но все встроенные уже выполнены к этому моменту). --- ## Логирование активности -После каждого события крючка обработчик добавляет строку JSONL в `~/.failproofai/hook-activity.jsonl`: +После каждого события хука обработчик добавляет строку JSONL в `~/.failproofai/hook-activity.jsonl`: ```json { @@ -259,75 +259,75 @@ export function clearCustomHooks(): void { ... } // used in tests } ``` -Одна строка на политику, которая приняла решение не-разрешение. Решения о разрешении не регистрируются (чтобы файл был меньше). +По одной строке на политику, которая приняла решение, отличное от allow. Решения allow не регистрируются (чтобы сохранить размер файла маленьким). --- ## Архитектура панели -Панель — это приложение **Next.js 16**, использующее App Router с React Server Components и Server Actions. +Панель является приложением **Next.js 16** с использованием App Router с React Server Components и Server Actions. ```text app/ - layout.tsx ← Root layout (theme, telemetry, nav) - projects/page.tsx ← Server component: list all Claude projects - project/[name]/page.tsx ← Server component: list sessions in a project + layout.tsx ← Корневой макет (тема, телеметрия, навигация) + projects/page.tsx ← Server component: список всех проектов Claude + project/[name]/page.tsx ← Server component: список сеансов в проекте project/[name]/session/ - [sessionId]/page.tsx ← Server component: render session viewer - policies/page.tsx ← Client component: policy management + activity log + [sessionId]/page.tsx ← Server component: отображение просмотра сеанса + policies/page.tsx ← Client component: управление политиками + журнал активности actions/ - get-hooks-config.ts ← Read config + policy list - update-hooks-config.ts ← Toggle policy on/off - update-policy-params.ts ← Update policy parameters - get-hook-activity.ts ← Paginate/search activity log - install-hooks-web.ts ← Install/remove hooks from the browser + get-hooks-config.ts ← Чтение конфигурации + список политик + update-hooks-config.ts ← Включение/отключение политики + update-policy-params.ts ← Обновление параметров политики + get-hook-activity.ts ← Постраничный поиск журнала активности + install-hooks-web.ts ← Установка/удаление хуков из браузера api/ - download/[project]/[session]/route.ts ← Per-CLI session export (JSONL or JSON) + download/[project]/[session]/route.ts ← Экспорт сеанса по CLI (JSONL или JSON) ``` **Поток данных:** -- Компоненты страниц вызывают `lib/projects.ts` и `lib/log-entries.ts` для прямого чтения данных проекта/сеанса из файловой системы (нет API слоя для чтения). -- Страница Политик использует Server Actions для всех мутаций (переключение, обновление параметров, установка/удаление). -- Средство просмотра сеансов анализирует формат JSONL-транскрипта Claude и отображает временную шкалу сообщений и вызовов инструментов. +- Компоненты страниц вызывают `lib/projects.ts` и `lib/log-entries.ts` для чтения данных проекта/сеанса непосредственно из файловой системы (нет уровня API для чтения). +- Страница Policies использует Server Actions для всех изменений (переключение, обновление параметров, установка/удаление). +- Просмотрщик сеанса парсит формат стенограммы JSONL Claude и отображает хронологию сообщений и вызовов инструментов. -**Ключевые решения по проектированию:** +**Ключевые дизайн-решения:** -- Нет базы данных — все постоянное состояние находится в простых файлах (`~/.failproofai/`, `~/.claude/projects/`). -- Server Actions для мутаций — не требуется REST API для операций CRUD. -- React Server Components для страниц чтения — быстрая первоначальная загрузка, нет клиентского пакета для выборки данных. -- Клиентские компоненты только где нужна интерактивность (переключатели политик, поиск активности, средство просмотра логов). +- Нет базы данных — все постоянное состояние находится в обычных файлах (`~/.failproofai/`, `~/.claude/projects/`). +- Server Actions для изменений — REST API не требуется для операций CRUD. +- React Server Components для страниц чтения — более быстрая начальная загрузка, нет клиентского пакета для выборки данных. +- Клиентские компоненты только там, где требуется интерактивность (переключатели политик, поиск активности, просмотр журнала). --- -## Расположение файлов +## Структура файлов ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # CLI router (hook / dashboard / install / etc.) +│ └── failproofai.mjs # Маршрутизатор CLI (hook / dashboard / install / и т. д.) ├── src/hooks/ -│ ├── handler.ts # Hook event pipeline -│ ├── builtin-policies.ts # 39 policy definitions -│ ├── policy-evaluator.ts # Policy execution engine -│ ├── policy-registry.ts # Policy registration and lookup -│ ├── policy-types.ts # TypeScript interfaces -│ ├── hooks-config.ts # Multi-scope config loading -│ ├── custom-hooks-registry.ts # globalThis-backed hook registry -│ ├── custom-hooks-loader.ts # ESM loader for user JS hooks -│ ├── manager.ts # install / remove / list operations -│ ├── install-prompt.ts # Interactive policy selection prompt -│ ├── hook-logger.ts # Logging to hook.log -│ ├── hook-activity-store.ts # Persist activity to hook-activity.jsonl -│ └── llm-client.ts # LLM API client (for AI-powered policies) -├── app/ # Next.js dashboard (pages + server actions) -├── lib/ # Shared utilities -│ ├── projects.ts # Enumerate Claude projects from filesystem -│ ├── log-entries.ts # Parse Claude transcript JSONL format -│ ├── paths.ts # Resolve system paths +│ ├── handler.ts # Конвейер события хука +│ ├── builtin-policies.ts # 39 определений политик +│ ├── policy-evaluator.ts # Механизм выполнения политик +│ ├── policy-registry.ts # Регистрация и поиск политик +│ ├── policy-types.ts # Интерфейсы TypeScript +│ ├── hooks-config.ts # Загрузка конфигурации с несколькими областями +│ ├── custom-hooks-registry.ts # Реестр хуков, основанный на globalThis +│ ├── custom-hooks-loader.ts # Загрузчик ESM для пользовательских JS хуков +│ ├── manager.ts # Операции установки / удаления / списка +│ ├── install-prompt.ts # Интерактивное приглашение выбора политики +│ ├── hook-logger.ts # Логирование в hook.log +│ ├── hook-activity-store.ts # Сохранение активности в hook-activity.jsonl +│ └── llm-client.ts # Клиент LLM API (для политик с поддержкой AI) +├── app/ # Next.js панель (страницы + server actions) +├── lib/ # Общие утилиты +│ ├── projects.ts # Перечисление проектов Claude из файловой системы +│ ├── log-entries.ts # Парсинг формата стенограммы Claude JSONL +│ ├── paths.ts # Разрешение путей системы │ └── ... -├── components/ # Shared React UI components -├── contexts/ # React context providers (theme, auto-refresh, telemetry) -├── examples/ # Example custom hook files -└── __tests__/ # Unit and E2E tests +├── components/ # Общие компоненты React UI +├── contexts/ # Поставщики контекста React (тема, авто-обновление, телеметрия) +├── examples/ # Примеры файлов пользовательского хука +└── __tests__/ # Модульные и E2E тесты ``` \ No newline at end of file diff --git a/docs/ru/built-in-policies.mdx b/docs/ru/built-in-policies.mdx index 0d4274fc..4a02f746 100644 --- a/docs/ru/built-in-policies.mdx +++ b/docs/ru/built-in-policies.mdx @@ -1,40 +1,39 @@ --- ---- title: Встроенные политики -description: "Все 39 встроенных политик, которые ловят распространённые сбои агентов" +description: "39 встроенных политик для предотвращения типичных сбоев агентов" icon: shield --- -failproofai поставляется с 39 встроенными политиками, которые ловят распространённые сбои агентов. Каждая политика срабатывает на конкретный тип события hook и имя инструмента. Девятнадцать политик принимают параметры, позволяющие настраивать их поведение без написания кода. Пять политик workflow принудительно соблюдают конвейер commit → push → PR → CI перед остановкой Claude. +failproofai поставляется с 39 встроенными политиками, которые предотвращают типичные сбои агентов. Каждая политика срабатывает на определённый тип события хука и имя инструмента. Девятнадцать политик принимают параметры, позволяющие настраивать их поведение без написания кода. Пять рабочих политик обеспечивают соблюдение конвейера commit → push → PR → CI перед остановкой Claude. --- ## Обзор -Политики сгруппированы по категориям: +Политики разделены по категориям: -| Категория | Политики | Тип hook | +| Категория | Политики | Тип хука | |----------|----------|-----------| -| [Опасные команды](#опасные-команды) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | -| [Команды инфраструктуры](#команды-инфраструктуры) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [Секреты (санитайзеры)](#секреты-санитайзеры) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | -| [Переменные окружения](#переменные-окружения) | block-env-files, protect-env-vars | PreToolUse | -| [Доступ к файлам](#доступ-к-файлам) | block-read-outside-cwd, block-secrets-write | PreToolUse | +| [Опасные команды](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | +| [Инфраструктурные команды](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | +| [Секреты (санитайзеры)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [Окружение](#environment) | block-env-files, protect-env-vars | PreToolUse | +| [Доступ к файлам](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | -| [База данных](#база-данных) | warn-destructive-sql, warn-schema-alteration | PreToolUse | -| [Предупреждения](#предупреждения) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | -| [Менеджеры пакетов](#менеджеры-пакетов) | prefer-package-manager | PreToolUse | -| [Workflow](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | +| [База данных](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse | +| [Предупреждения](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | +| [Менеджеры пакетов](#package-managers) | prefer-package-manager | PreToolUse | +| [Рабочий процесс](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — остановить выполнение агентом операции. -- **`warn-`** — дать агенту дополнительный контекст, чтобы он мог самокорректироваться. -- **`sanitize-`** — удалить чувствительные данные из вывода инструмента перед тем, как агент их увидит. +- **`block-`** — остановить агента от продолжения. +- **`warn-`** — дать агенту дополнительный контекст для самокоррекции. +- **`sanitize-`** — удалить чувствительные данные из вывода инструмента перед отправкой агенту. ### Пространства имён -Каждая политика находится в слоте `/`. Встроенные политики принадлежат пространству имён **`failproofai/`** — например, `failproofai/sanitize-jwt`. Пространство имён предотвращает коллизии, когда вы также загружаете пользовательские или сторонние политики с похожими короткими именами. +Каждая политика находится в слоте `/`. Встроенные политики принадлежат пространству имён **`failproofai/`** — например, `failproofai/sanitize-jwt`. Пространство имён предотвращает коллизии при загрузке пользовательских или сторонних политик с похожими названиями. -В вашей конфигурации вы можете ссылаться на встроенную политику как по её короткому имени, так и по полному имени; обе формы разрешаются в одну и ту же политику: +В конфиге вы можете ссылаться на встроенную политику либо по краткому имени, либо по полному имени; обе формы разрешаются в одну политику: ```json { @@ -45,27 +44,27 @@ failproofai поставляется с 39 встроенными политик } ``` -Если имя не содержит `/`, failproofai обрабатывает его как принадлежащее пространству имён по умолчанию `failproofai`. Имена, которые уже содержат `/` (например `myorg/foo`, `custom/my-hook`), сохраняются как есть. -- **`require-`** — заблокировать событие Stop до выполнения условий. +Если имя не содержит `/`, failproofai считает его принадлежащим пространству имён по умолчанию `failproofai`. Имена, уже содержащие `/` (например, `myorg/foo`, `custom/my-hook`), сохраняются как есть. +- **`require-`** — блокировать событие Stop до выполнения условий. --- -Каждая политика поддерживает дополнительное поле `hint` в `policyParams`. Подсказка добавляется к сообщению deny или instruct, которое видит Claude, обеспечивая действенное руководство без изменения кода политики. Работает со встроенными, пользовательскими и convention политиками. Подробнее в [Configuration → hint](/ru/configuration#hint-cross-cutting). +Каждая политика поддерживает необязательное поле `hint` в `policyParams`. Подсказка добавляется к сообщению deny или instruct, которое видит Claude, предоставляя практичное руководство без изменения кода политики. Работает со встроенными, пользовательскими и условными политиками. Подробнее см. [Configuration → hint](/ru/configuration#hint-cross-cutting). --- ## Опасные команды -Предотвратить выполнение агентом операций, которые сложно отменить или которые могут повредить хост-систему. +Предотвратите выполнение агентами операций, которые сложно отменить или которые могут повредить хост-систему. ### `block-sudo` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует любую команду `sudo`. +**По умолчанию:** Запрещает любую команду `sudo`. -Блокирует вызовы, содержащие ключевое слово `sudo`. Сопоставление шаблонов выполняется на разобранных токенах команды, а не на исходной строке, чтобы предотвратить обход через инъекцию операторов shell. +Блокирует вызовы, содержащие ключевое слово `sudo`. Сопоставление осуществляется для разобранных токенов команды, а не для сырой строки, что предотвращает обход через инъекции операторов оболочки. **Параметры:** @@ -85,10 +84,10 @@ failproofai поставляется с 39 встроенными политик } ``` -С этой конфигурацией `sudo systemctl status nginx` разрешена, но `sudo rm /etc/hosts` заблокирована. +С такой конфигурацией `sudo systemctl status nginx` разрешена, но `sudo rm /etc/hosts` запрещена. -Шаблоны сопоставляются с разобранными токенами, а не с исходной командной строкой. Это предотвращает обход через приложенные операторы shell (например `sudo systemctl status x; rm -rf /` не соответствует `sudo systemctl status *`). +Шаблоны сопоставляются с разобранными токенами, а не с сырой командной строкой. Это предотвращает обход через добавленные операторы оболочки (например, `sudo systemctl status x; rm -rf /` не совпадает с `sudo systemctl status *`). --- @@ -96,13 +95,13 @@ failproofai поставляется с 39 встроенными политик ### `block-rm-rf` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует `rm -rf`, `rm -fr` и похожие формы рекурсивного удаления. +**По умолчанию:** Запрещает `rm -rf`, `rm -fr` и аналогичные формы рекурсивного удаления. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Пути, которые безопасно рекурсивно удалять (например `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Пути, которые безопасно удалять рекурсивно (например, `/tmp`). | **Пример:** @@ -121,7 +120,7 @@ failproofai поставляется с 39 встроенными политик ### `block-curl-pipe-sh` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует `curl | bash`, `curl | sh`, `wget | bash` и похожие шаблоны. +**По умолчанию:** Запрещает `curl | bash`, `curl | sh`, `wget | bash` и аналогичные шаблоны. Нет параметров. @@ -130,28 +129,28 @@ failproofai поставляется с 39 встроенными политик ### `block-failproofai-commands` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует команды, которые бы удалили или отключили сам failproofai (например `npm uninstall failproofai`, `failproofai policies --uninstall`). +**По умолчанию:** Запрещает команды, которые деинсталлировали бы или отключили бы сам failproofai (например, `npm uninstall failproofai`, `failproofai policies --uninstall`). Нет параметров. --- -## Команды инфраструктуры +## Инфраструктурные команды -Остановить agent-ы кодирования от запуска CLI инфраструктуры или срабатывания CI/CD pipeline-ов. Все политики в этой категории **opt-in** (`defaultEnabled: false`) — агенты, которым легитимно нужно вызывать `kubectl`, `terraform` и т.д., не будут нарушены, если вы не включите политику. При включении каждый вызов сопоставленного CLI блокируется, если только команда не совпадает с записью в `allowPatterns`. +Предотвратите выполнение агентами инфраструктурных CLI или запуск конвейеров CI/CD. Все политики в этой категории **опциональны** (`defaultEnabled: false`) — агенты, которым действительно требуется вызывать `kubectl`, `terraform` и т. д., не будут нарушены, если только вы не включите политику. Если политика включена, любое использование подходящего CLI запрещено, если команда не совпадает с записью в `allowPatterns`. -Грамматика шаблонов такая же, как в [`block-sudo`](#block-sudo): токены сопоставляются с разобранными argv, `*` является подстановочным символом для одного токена, и любая команда, содержащая отдельный оператор shell (`&&`, `||`, `|`, `;`) или токен с встроенными метасимволами shell, отклоняется до сопоставления списка разрешений, чтобы предотвратить обход через инъекцию. +Грамматика шаблонов совпадает с [`block-sudo`](#block-sudo): токены сопоставляются с разобранными argv, `*` — это подстановочный знак для одного токена, и любая команда, содержащая отдельный оператор оболочки (`&&`, `||`, `|`, `;`) или токен с внедрёнными метасимволами оболочки, отклоняется до проверки разрешённого списка, что предотвращает инъекции. ### `block-kubectl` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует любой вызов `kubectl`. +**По умолчанию:** Запрещает любое использование `kubectl`. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Префиксы команд kubectl, которые разрешены. | +| `allowPatterns` | `string[]` | `[]` | Префиксы kubectl-команд, которые разрешены. | **Пример:** @@ -165,20 +164,20 @@ failproofai поставляется с 39 встроенными политик } ``` -С этой конфигурацией `kubectl get pods` разрешена, но `kubectl apply -f deploy.yaml` заблокирована. +С такой конфигурацией `kubectl get pods` разрешена, но `kubectl apply -f deploy.yaml` запрещена. --- ### `block-terraform` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует любой вызов `terraform` или `tofu` (OpenTofu). +**По умолчанию:** Запрещает любое использование `terraform` или `tofu` (OpenTofu). **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Префиксы команд terraform/tofu, которые разрешены. | +| `allowPatterns` | `string[]` | `[]` | Префиксы terraform/tofu-команд, которые разрешены. | **Пример:** @@ -197,13 +196,13 @@ failproofai поставляется с 39 встроенными политик ### `block-aws-cli` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует любой вызов AWS CLI. +**По умолчанию:** Запрещает любое использование AWS CLI. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Префиксы команд AWS CLI, которые разрешены. | +| `allowPatterns` | `string[]` | `[]` | Префиксы aws-команд, которые разрешены. | **Пример:** @@ -222,13 +221,13 @@ failproofai поставляется с 39 встроенными политик ### `block-gcloud` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует любой вызов `gcloud` (Google Cloud) CLI. +**По умолчанию:** Запрещает любое использование `gcloud` (Google Cloud CLI). **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Префиксы команд gcloud, которые разрешены. | +| `allowPatterns` | `string[]` | `[]` | Префиксы gcloud-команд, которые разрешены. | **Пример:** @@ -247,13 +246,13 @@ failproofai поставляется с 39 встроенными политик ### `block-az-cli` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует любой вызов Azure CLI. +**По умолчанию:** Запрещает любое использование `az` (Azure CLI). **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Префиксы команд Azure CLI, которые разрешены. | +| `allowPatterns` | `string[]` | `[]` | Префиксы az-команд, которые разрешены. | **Пример:** @@ -272,13 +271,13 @@ failproofai поставляется с 39 встроенными политик ### `block-helm` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует любой вызов `helm`. +**По умолчанию:** Запрещает любое использование `helm`. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Префиксы команд helm, которые разрешены. | +| `allowPatterns` | `string[]` | `[]` | Префиксы helm-команд, которые разрешены. | **Пример:** @@ -297,7 +296,7 @@ failproofai поставляется с 39 встроенными политик ### `block-gh-pipeline` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует следующие подкоманды `gh` CLI, которые изменяют состояние или запускают pipeline-ы: +**По умолчанию:** Запрещает следующие подкоманды `gh` CLI, которые изменяют состояние или запускают конвейеры: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -306,13 +305,13 @@ failproofai поставляется с 39 встроенными политик - `gh cache delete` - `gh secret set`, `gh secret delete` -Только для чтения подкоманды `gh`, такие как `gh pr view`, `gh pr list`, `gh run list`, `gh release view` и `gh api repos/.../...` **не** соответствуют этой политике — они регулярно нужны для проверок workflow (включая собственный `require-ci-green-before-stop` failproofai). +Только для чтения подкоманды `gh`, такие как `gh pr view`, `gh pr list`, `gh run list`, `gh release view` и `gh api repos/.../...` **не** совпадают с этой политикой — они регулярно требуются для проверок рабочего процесса (включая собственный `require-ci-green-before-stop` failproofai). **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Конкретные сценариальные вызовы, которые нужно разрешить, несмотря на то что они иначе были бы заблокированы. | +| `allowPatterns` | `string[]` | `[]` | Определённые скриптовые вызовы для разрешения, хотя они иначе были бы запрещены. | **Пример:** @@ -330,12 +329,12 @@ failproofai поставляется с 39 встроенными политик ## Секреты (санитайзеры) -Остановить агентов от утечки учётных данных в их контекст или вывод. Политики-санитайзеры срабатывают на событиях **PostToolUse**. Когда Claude запускает команду Bash, читает файл или вызывает любой инструмент, эти политики проверяют вывод перед его возвратом Claude. Если обнаружен паттерн секрета, политика возвращает решение deny, которое предотвращает передачу вывода обратно. +Предотвратите утечку учётных данных в контекст или выход агента. Политики-санитайзеры срабатывают на событиях **PostToolUse**. Когда Claude выполняет bash-команду, читает файл или вызывает любой инструмент, эти политики проверяют вывод перед возвратом агенту. Если обнаружен шаблон секрета, политика возвращает решение deny, которое предотвращает передачу вывода обратно. ### `sanitize-jwt` **Событие:** PostToolUse (все инструменты) -**По умолчанию:** Скрывает JWT токены (три сегмента base64url, разделённые `.`). +**По умолчанию:** Скрывает JWT-токены (три сегмента base64url, разделённые `.`). Нет параметров. @@ -344,13 +343,13 @@ failproofai поставляется с 39 встроенными политик ### `sanitize-api-keys` **Событие:** PostToolUse (все инструменты) -**По умолчанию:** Скрывает распространённые форматы API ключей: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT (`ghp_`), AWS ключи доступа (`AKIA`), Stripe ключи (`sk_live_`, `sk_test_`) и Google API ключи (`AIza`). +**По умолчанию:** Скрывает распространённые форматы API-ключей: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS access keys (`AKIA`), Stripe keys (`sk_live_`, `sk_test_`) и Google API keys (`AIza`). **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Дополнительные regex паттерны, которые нужно обрабатывать как секреты. | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Дополнительные regex-шаблоны для обработки как секретов. | **Пример:** @@ -372,7 +371,7 @@ failproofai поставляется с 39 встроенными политик ### `sanitize-connection-strings` **Событие:** PostToolUse (все инструменты) -**По умолчанию:** Скрывает строки подключения к БД, содержащие встроенные учётные данные (например `postgresql://user:password@host/db`). +**По умолчанию:** Скрывает строки подключения к БД, содержащие внедрённые учётные данные (например, `postgresql://user:password@host/db`). Нет параметров. @@ -381,7 +380,7 @@ failproofai поставляется с 39 встроенными политик ### `sanitize-private-key-content` **Событие:** PostToolUse (все инструменты) -**По умолчанию:** Скрывает PEM блоки (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` и т.д.). +**По умолчанию:** Скрывает PEM-блоки (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` и т. д.). Нет параметров. @@ -390,22 +389,22 @@ failproofai поставляется с 39 встроенными политик ### `sanitize-bearer-tokens` **Событие:** PostToolUse (все инструменты) -**По умолчанию:** Скрывает `Authorization: Bearer ` заголовки, где токен составляет 20 или более символов. +**По умолчанию:** Скрывает заголовки `Authorization: Bearer `, где токен содержит 20 или более символов. Нет параметров. --- -## Переменные окружения +## Окружение -Защитить чувствительную конфигурацию окружения от чтения или раскрытия агентами. +Защитите чувствительную конфигурацию окружения от чтения или раскрытия агентами. ### `block-env-files` **Событие:** PreToolUse (Bash, Read) -**По умолчанию:** Блокирует чтение файлов `.env` через `cat .env`, вызовы инструмента Read с `.env` как путём файла и т.д. +**По умолчанию:** Запрещает чтение файлов `.env` через `cat .env`, вызовы инструмента Read с `.env` в качестве пути файла и т. д. -Не блокирует `.envrc` или другие файлы, связанные с окружением — только файлы названные ровно `.env`. +Не блокирует `.envrc` или другие файлы окружения — только файлы с точным именем `.env`. Нет параметров. @@ -414,7 +413,7 @@ failproofai поставляется с 39 встроенными политик ### `protect-env-vars` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует команды, которые выводят переменные окружения: `printenv`, `env`, `echo $VAR`. +**По умолчанию:** Запрещает команды, которые выводят переменные окружения: `printenv`, `env`, `echo $VAR`. Нет параметров. @@ -422,18 +421,18 @@ failproofai поставляется с 39 встроенными политик ## Доступ к файлам -Держать агентов в границах проекта и вдали от чувствительных файлов. +Держите агентов в границах проекта и подальше от чувствительных файлов. ### `block-read-outside-cwd` **Событие:** PreToolUse (Read, Bash) -**По умолчанию:** Блокирует чтение файлов вне корня проекта. Граница — `CLAUDE_PROJECT_DIR` (устанавливается один раз за сеанс Claude Code), с fallback на текущую рабочую директорию сеанса, если эта переменная не установлена. Использование корня проекта вместо live `cwd` означает, что граница остаётся стабильной даже после того, как Claude перейдёт в подпапку. +**По умолчанию:** Запрещает чтение файлов вне корня проекта. Границей является `CLAUDE_PROJECT_DIR` (устанавливается один раз за сессию Claude Code) с откатом на текущий рабочий каталог сессии, когда переменная не задана. Использование корня проекта вместо текущего `cwd` означает, что граница остаётся стабильной даже после `cd` Claude в подкаталог. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Абсолютные префиксы путей, которые разрешены даже если вне корня проекта. | +| `allowPaths` | `string[]` | `[]` | Префиксы абсолютных путей, которые разрешены даже если находятся вне корня проекта. | **Пример:** @@ -452,13 +451,13 @@ failproofai поставляется с 39 встроенными политик ### `block-secrets-write` **Событие:** PreToolUse (Write, Edit) -**По умолчанию:** Блокирует запись в файлы, обычно используемые для приватных ключей и сертификатов: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**По умолчанию:** Запрещает запись в файлы, обычно используемые для приватных ключей и сертификатов: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | Дополнительные паттерны имён файлов (glob-стиль) для блокировки. | +| `additionalPatterns` | `string[]` | `[]` | Дополнительные шаблоны имён файлов (glob-стиль) для блокировки. | **Пример:** @@ -476,18 +475,18 @@ failproofai поставляется с 39 встроенными политик ## Git -Предотвратить случайные push-и, force-push-и и ошибки веток, которые сложно отменить. +Предотвратите случайные push, force-push и ошибки в ветках, которые сложно отменить. ### `block-push-master` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует `git push origin main` и `git push origin master`. +**По умолчанию:** Запрещает `git push origin main` и `git push origin master`. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Имена веток, в которые нельзя напрямую push-ить. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Имена ветвей, в которые нельзя отправлять напрямую. | **Пример:** @@ -502,7 +501,7 @@ failproofai поставляется с 39 встроенными политик ``` -Чтобы разрешить push-ить во все ветки (эффективно отключить эту политику без удаления её из `enabledPolicies`), установите `protectedBranches: []`. +Чтобы разрешить отправку во все ветви (эффективно отключить эту политику без удаления из `enabledPolicies`), установите `protectedBranches: []`. --- @@ -510,22 +509,22 @@ failproofai поставляется с 39 встроенными политик ### `block-work-on-main` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует `git commit`, `git merge`, `git rebase` и `git cherry-pick` пока рабочее дерево находится на `main` или `master`. Создание и переключение веток (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) не затронуты. +**По умолчанию:** Запрещает `git commit`, `git merge`, `git rebase` и `git cherry-pick` при работе дерева на `main` или `master`. Создание и переключение ветвей (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) не затронуты. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Имена веток, на которых commit/merge/rebase/cherry-pick заблокированы. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Имена ветвей, на которых commit/merge/rebase/cherry-pick запрещены. | --- ### `block-force-push` **Событие:** PreToolUse (Bash) -**По умолчанию:** Блокирует `git push --force` и `git push -f`. +**По умолчанию:** Запрещает `git push --force` и `git push -f`. -Нет политико-специфичных параметров. Используйте cross-cutting [`hint`](/ru/configuration#hint-cross-cutting) для предложения альтернатив: +Нет специфичных для политики параметров. Используйте кросс-секционную [`hint`](/ru/configuration#hint-cross-cutting) для предложения альтернатив: ```json { @@ -542,7 +541,7 @@ failproofai поставляется с 39 встроенными политик ### `warn-git-amend` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude действовать осторожно при запуске `git commit --amend`. Команда не блокируется. +**По умолчанию:** Инструктирует Claude действовать осторожно при выполнении `git commit --amend`. Не блокирует команду. Нет параметров. @@ -551,7 +550,7 @@ failproofai поставляется с 39 встроенными политик ### `warn-git-stash-drop` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude подтвердить перед запуском `git stash drop`. Команда не блокируется. +**По умолчанию:** Инструктирует Claude подтвердить перед выполнением `git stash drop`. Не блокирует команду. Нет параметров. @@ -560,7 +559,7 @@ failproofai поставляется с 39 встроенными политик ### `warn-all-files-staged` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude просмотреть то, что оно ставит на сцену, при запуске `git add -A` или `git add .`. Команда не блокируется. +**По умолчанию:** Инструктирует Claude проверить, что он осуществляет индексирование при выполнении `git add -A` или `git add .`. Не блокирует команду. Нет параметров. @@ -568,12 +567,12 @@ failproofai поставляется с 39 встроенными политик ## База данных -Поймать деструктивные SQL операции перед их выполнением на вашей БД. +Перехватите деструктивные SQL-операции перед их выполнением против БД. ### `warn-destructive-sql` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude подтвердить перед запуском SQL, содержащего `DROP TABLE`, `DROP DATABASE` или `DELETE` без предложения `WHERE`. +**По умолчанию:** Инструктирует Claude подтвердить перед выполнением SQL, содержащего `DROP TABLE`, `DROP DATABASE` или `DELETE` без `WHERE`-предложения. Нет параметров. @@ -582,7 +581,7 @@ failproofai поставляется с 39 встроенными политик ### `warn-schema-alteration` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude подтвердить перед запуском `ALTER TABLE` операторов. +**По умолчанию:** Инструктирует Claude подтвердить перед выполнением `ALTER TABLE`-операций. Нет параметров. @@ -590,18 +589,18 @@ failproofai поставляется с 39 встроенными политик ## Предупреждения -Дать агентам дополнительный контекст перед потенциально рискованными, но не деструктивными операциями. +Дайте агентам дополнительный контекст перед потенциально рискованными, но не деструктивными операциями. ### `warn-large-file-write` **Событие:** PreToolUse (Write) -**По умолчанию:** Инструктирует Claude подтвердить перед записью файлов больше 1024 КБ. +**По умолчанию:** Инструктирует Claude подтвердить перед записью файлов больше 1024 KB. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | Пороговый размер файла в килобайтах, выше которого выводится предупреждение. | +| `thresholdKb` | `number` | `1024` | Порог размера файла в килобайтах, выше которого выдаётся предупреждение. | **Пример:** @@ -616,7 +615,7 @@ failproofai поставляется с 39 встроенными политик ``` -Обработчик hook применяет лимит 1 МБ stdin для payload-ов. Чтобы протестировать эту политику с малым содержимым, установите `thresholdKb` значительно ниже 1024. +Обработчик хука применяет ограничение stdin в 1 MB на полезные нагрузки. Для тестирования этой политики с малым содержимым установите `thresholdKb` на значение хорошо ниже 1024. --- @@ -624,7 +623,7 @@ failproofai поставляется с 39 встроенными политик ### `warn-package-publish` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude подтвердить перед запуском `npm publish`. +**По умолчанию:** Инструктирует Claude подтвердить перед выполнением `npm publish`. Нет параметров. @@ -642,7 +641,7 @@ failproofai поставляется с 39 встроенными политик ### `warn-global-package-install` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude подтвердить перед запуском `npm install -g`, `yarn global add` или `pip install` без виртуального окружения. +**По умолчанию:** Инструктирует Claude подтвердить перед выполнением `npm install -g`, `yarn global add` или `pip install` без виртуального окружения. Нет параметров. @@ -650,7 +649,7 @@ failproofai поставляется с 39 встроенными политик ## Менеджеры пакетов -Принудить агента использовать только разрешённые менеджеры пакетов. +Обеспечьте соблюдение правил о том, какие менеджеры пакетов разрешены агенту. ### `prefer-package-manager` @@ -661,10 +660,10 @@ failproofai поставляется с 39 встроенными политик | Параметр | Тип | По умолчанию | Описание | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | Разрешённые имена менеджеров пакетов. Любой обнаруженный менеджер не в этом списке блокируется. Когда пусто, политика не оказывает эффекта. | -| `blocked` | string[] | `[]` | Дополнительные имена менеджеров для блокировки помимо встроенного списка (например `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | Разрешённые имена менеджеров пакетов. Любой обнаруженный менеджер не в этом списке блокируется. Если пусто, политика неактивна. | +| `blocked` | string[] | `[]` | Дополнительные имена менеджеров для блокировки помимо встроенного списка (например, `['pdm', 'pipx']`). | -Встроенный список блокировки охватывает: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Используйте `blocked` для добавления менеджеров не в этом списке. +Встроенный список блокировки включает: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Используйте `blocked` для добавления менеджеров не в этом списке. **Пример конфигурации:** @@ -680,59 +679,59 @@ failproofai поставляется с 39 встроенными политик } ``` -С этой конфигурацией `pip install flask` и `pdm install flask` оба заблокированы с сообщением, говорящим Claude использовать `uv` или `bun` вместо этого. Команды типа `uv pip install flask` разрешены, потому что `uv` в списке разрешений и проверяется первым. +С этой конфигурацией как `pip install flask`, так и `pdm install flask` запрещены с сообщением, говорящим Claude использовать `uv` или `bun` вместо этого. Команды вроде `uv pip install flask` разрешены, потому что `uv` в разрешённом списке и проверяется первым. --- ## Поведение AI -Обнаружить когда агенты зависают или ведут себя неожиданно. +Обнаруживайте, когда агенты застревают или ведут себя неожиданно. ### `warn-repeated-tool-calls` **Событие:** PreToolUse (все инструменты) -**По умолчанию:** Инструктирует Claude пересмотреть когда один и тот же инструмент вызывается 3+ раза с идентичными параметрами — частый признак того, что агент застрял в loop. +**По умолчанию:** Инструктирует Claude пересмотреть, когда один и тот же инструмент вызывается 3+ раза с идентичными параметрами — распространённый признак того, что агент застрял в цикле. Нет параметров. --- -## Workflow +## Рабочий процесс -Принудить соблюдать дисциплинированный workflow конца сеанса. Эти политики срабатывают на событие **Stop** и блокируют агенту остановку до выполнения каждого условия. Они следуют естественной цепочке зависимостей: commit → push → PR → CI. Если политика блокирует, позднейшие политики в цепочке пропускаются (deny short-circuits). +Обеспечьте дисциплинированный рабочий процесс конца сессии. Эти политики срабатывают на событии **Stop** и запрещают агенту остановиться, пока не будут выполнены условия. Они следуют естественной цепочке зависимостей: commit → push → PR → CI. Если политика запрещает, последующие политики в цепи пропускаются (deny вызывает короткое замыкание). -Все политики workflow **fail-open**: если требуемый инструмент не доступен (например `gh` не установлен, нет git remote), политика разрешает с информационным сообщением, объясняющим, почему проверка была пропущена. +Все рабочие политики **fail-open**: если требуемый инструмент недоступен (например, `gh` не установлена, нет удалённого репозитория), политика разрешает с информационным сообщением, объясняющим, почему проверка была пропущена. -### Semantics Stop на CLI +### Семантика Stop для каждого CLI -Применение Stop немного отличается в семи поддерживаемых CLI, потому что каждый раскрывает разный contract хука «agent finished». **Результат** — одинаковый — агент не может остановиться пока gate workflow не пройден — но **механика** отличается. Таблица ниже резюмирует; только Pi имеет видимую для пользователя особенность, стоящую понимания перед включением политики `require-*-before-stop`. +Применение Stop выглядит немного по-разному в семи поддерживаемых CLI, потому что каждый предоставляет отличающийся контракт хука «агент завершил работу». **Результат** одинаков — агент не может остановиться, пока шлюз рабочего процесса не пройден — но **механика** отличается. Таблица ниже суммирует; только Pi имеет заметную для пользователя особенность, стоящую понимания перед включением политики `require-*-before-stop`. -| CLI | Когда gate срабатывает | Что вы видите | +| CLI | Когда срабатывает шлюз | Что вы видите | |---|---|---| -| Claude Code | Тот же loop агента, сразу же | Claude продолжает работу — исправляет проблему, затем снова пытается закончить. Без видимых перерывов для вас. | -| Codex | Тот же loop агента, сразу же | Как Claude. | -| GitHub Copilot CLI | Тот же loop агента, сразу же | Как Claude (использует `{decision:"block", reason}` retry канал Copilot — проверено эмпирически на Copilot CLI 1.0.41). | -| Cursor Agent | Тот же loop агента, сразу же | Как Claude (использует `{followup_message}` канал Cursor — capped на `loop_limit`, по умолчанию 5 retries). | -| Gemini CLI | Тот же loop агента, сразу же | Как Claude (использует `{decision:"block", reason}` канал Gemini на `AfterAgent`). | -| OpenCode | Тот же loop агента, сразу же | Как Claude (использует `client.session.prompt(...)` вызов SDK OpenCode маршрутизированный через `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **Следующий turn пользователя** | **Pi видимо останавливается** когда gate срабатывает — её loop агента выходит и вы возвращаетесь к prompt. Gate затем срабатывает в следующий раз, когда вы отправляете prompt: failproofai добавляет директиву `MANDATORY ACTION REQUIRED` к system prompt этого turn, инструктируя LLM завершить шаг workflow (commit, push и т.д.) перед тем как делать то, что вы просили. | +| Claude Code | Тот же цикл агента, сразу | Claude продолжает работать — исправляет проблему, затем пытается завершить снова. Нет видимого прерывания для вас. | +| Codex | Тот же цикл агента, сразу | То же самое, что Claude. | +| GitHub Copilot CLI | Тот же цикл агента, сразу | То же самое, что Claude (использует канал повтора `{decision:"block", reason}` Copilot — проверено эмпирически на Copilot CLI 1.0.41). | +| Cursor Agent | Тот же цикл агента, сразу | То же самое, что Claude (использует канал `{followup_message}` Cursor — ограничен `loop_limit`, по умолчанию 5 повторов). | +| Gemini CLI | Тот же цикл агента, сразу | То же самое, что Claude (использует канал `{decision:"block", reason}` Gemini на `AfterAgent`). | +| OpenCode | Тот же цикл агента, сразу | То же самое, что Claude (использует вызов SDK `client.session.prompt(...)` OpenCode, маршрутизированный через `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **Следующий ход пользователя** | **Pi видимо останавливается**, когда срабатывает шлюз — его цикл агента завершается и вы возвращаетесь к приглашению. Шлюз затем срабатывает при следующей отправке приглашения: failproofai добавляет директиву `MANDATORY ACTION REQUIRED` в системное приглашение того хода, инструктируя LLM завершить шаг рабочего процесса (commit, push и т. д.) перед выполнением запрашиваемого вами действия. | -**Ограничение Pi.** `AgentEndEvent` Pi (аналог upstream `Stop` hook Claude) не имеет типа Result — к моменту его срабатывания loop агента Pi уже выхода. Pi не может быть принуждена к retry того же loop как Claude / Copilot / Cursor / Gemini / OpenCode могут. failproofai сдвигает gate на `before_agent_start` event Pi (который срабатывает после следующего пользовательского prompt), чтобы проверка workflow всё ещё применялась, только на следующем turn вместо текущего. +**Ограничение Pi.** `AgentEndEvent` Pi (эквивалент `Stop` хука Claude) не имеет типа Result — по времени его срабатывания цикл агента Pi уже завершился. Pi не может быть принуждена повторить тот же цикл, как Claude / Copilot / Cursor / Gemini / OpenCode. failproofai смещает шлюз к событию `before_agent_start` Pi (которое срабатывает после следующего приглашения пользователя), чтобы проверка рабочего процесса всё ещё применялась, просто при следующем ходе вместо текущего. **Что это означает на практике:** -- После остановки Pi, причина deny захватывается в памяти, ключ по Pi session id. Очень следующий prompt, который вы отправляете в том же процессе Pi дренирует это: LLM видит директиву `MANDATORY ACTION REQUIRED` в верхней части своего system prompt, коммитит (или push-ит / открывает PR / ждёт CI), и только затем продолжает с вашим запросом. Захваченная причина deny — one-shot — один раз слита, gate очищен. -- Gate ограничена lifetime процесса Pi. Если вы `Ctrl+C` Pi или выходите между turn-ами, в памяти entry dropped вместе с процессом и gate пропущена. Claude, Copilot, Cursor, Gemini и OpenCode имеют ту же граничную (kill агента и gate пропущена) — Pi только делает это более видимым, потому что агент видимо выходит перед тем как gate срабатывает. -- Pending deny также очищена на `session_shutdown` по любой причине (`new` / `resume` / `fork` / `quit`), поэтому stale gate от приоров сеанса не может утечь в свежий сеанс, запущенный в том же процессе Pi. +- После остановки Pi причина deny захватывается в памяти с ключом по id сессии Pi. Самое следующее приглашение, которое вы отправляете в той же сессии Pi, его извлекает: LLM видит директиву `MANDATORY ACTION REQUIRED` в верхней части своего системного приглашения, commit-ит (или push-ит / открывает PR / ждёт CI) и только затем продолжает с вашим запросом. Захваченная причина deny — одноразовая — после извлечения шлюз свободен. +- Шлюз ограничен временем жизни процесса Pi. Если вы `Ctrl+C` Pi или выход между ходами, запись в памяти удаляется вместе с процессом и шлюз пропускается. Claude, Copilot, Cursor, Gemini и OpenCode имеют то же самое ограничение (kill агента и шлюз пропускается) — Pi просто делает это более видимым, потому что агент видимо завершает работу перед срабатыванием шлюза. +- Ожидающий deny также очищается на `session_shutdown` по любой причине (`new` / `resume` / `fork` / `quit`), поэтому устаревший шлюз из предыдущей сессии не может утечь в свежую сессию, начатую в том же процессе Pi. -Если вам нужен Claude-стиль same-loop retry, запустите ваши `Stop` политики под любым из шести других поддерживаемых CLI. Мы отслеживаем Pi upstream для будущего типа Result на `AgentEndEvent`, который позволил бы нам закрыть этот gap. +Если вам нужен повтор в том же цикле, как Claude, запустите ваши политики `Stop` в любом из шести других поддерживаемых CLI. Мы отслеживаем Pi upstream на предмет будущего типа Result на `AgentEndEvent`, который позволил бы нам закрыть этот пробел. ### `require-commit-before-stop` **Событие:** Stop -**По умолчанию:** Блокирует остановку когда есть неподтверждённые изменения (изменённые, staged или untracked файлы). Возвращает информационное сообщение когда рабочая директория чиста. +**По умолчанию:** Запрещает остановку при наличии незафиксированных изменений (изменённые, индексированные или неотслеживаемые файлы). Возвращает информационное сообщение, когда рабочий каталог чист. Нет параметров. @@ -741,13 +740,13 @@ failproofai поставляется с 39 встроенными политик ### `require-push-before-stop` **Событие:** Stop -**По умолчанию:** Блокирует остановку когда есть unpushed commits или когда текущая ветка не имеет удалённой tracking ветки. Предлагает `git push -u` создать tracking ветку если нужно. Fails open если нет настроенного remote. +**По умолчанию:** Запрещает остановку при наличии неотправленных коммитов или когда текущая ветвь не имеет удалённой отслеживаемой ветви. Предлагает `git push -u` для создания отслеживаемой ветви при необходимости. Fail open, если удалённый репозиторий не настроен. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | Имя remote для push-а. | +| `remote` | `string` | `"origin"` | Имя удалённого репозитория для отправки. | **Пример:** @@ -766,13 +765,14 @@ failproofai поставляется с 39 встроенными политик ### `require-pr-before-stop` **Событие:** Stop -**По умолчанию:** Блокирует остановку когда не существует pull request для текущей ветки, или когда существующий PR закрыт без merge. Инструктирует Claude создать PR с `gh pr create`. Когда PR **merged**, политика разрешает (работа доставлена) и сообщение намекает переключиться с ветки (`git checkout main && git pull`). +**По умолчанию:** Запрещает остановку при отсутствии pull request для текущей ветви или при закрытом существующем PR без мерджа. Инструктирует Claude создать PR с `gh pr create`. Когда PR **смёрджена**, политика разрешает (работа доставлена) и сообщение намекает переключиться с ветви (`git checkout main && git pull`). Нет параметров. -Эта политика требует [GitHub CLI](https://cli.github.com/) (`gh`) установленной и аутентифицированной. -Запустите `gh auth login` с personal access token, который имеет `repo` scope для чтения pull requests. Если `gh` не установлена или не аутентифицирована, политика fails open и сообщает причину Claude. +Эта политика требует установку и аутентификацию [GitHub CLI](https://cli.github.com/) (`gh`). +Выполните `gh auth login` с персональным токеном доступа, имеющим область `repo` для доступа на чтение к +pull request-ам. Если `gh` не установлена или не аутентифицирована, политика fail-open и сообщает причину Claude. --- @@ -780,24 +780,24 @@ failproofai поставляется с 39 встроенными политик ### `require-no-conflicts-before-stop` **Событие:** Stop -**По умолчанию:** Блокирует остановку когда текущая ветка не может cleanly merge в base ветку. Политика сначала подтверждает существует ли `OPEN` PR на GitHub для ветки — без одного, нет merge target для применения, поэтому вся политика short-circuits к allow. После подтверждения `OPEN` PR, два независимых probe запускаются: +**По умолчанию:** Запрещает остановку, когда текущая ветвь не может чисто мержиться в базовую ветвь. Политика сначала подтверждает наличие `OPEN` PR на GitHub для ветви — без него нет целевого мерджа для применения, поэтому вся политика short-circuit в разрешение. После подтверждения `OPEN` PR выполняются два независимых зонда: -1. **Локальный** — `git merge-tree --write-tree --name-only origin/ HEAD`. При конфликте сообщение deny называет конфликтующие файлы так Claude знает ровно что разрешать. -2. **GitHub** — переиспользует `gh pr view --json mergeable,state` результат уже загруженный в precheck. Ловит конфликты, которые stale локальный `origin/` пропустил бы (например кто-то landed конфликтующий PR на `main` с последнего fetch). Результат `CONFLICTING` блокирует. Результат `UNKNOWN` также блокирует и инструктирует Claude ждать ~10 секунд и повторно проверить перед тем как снова пытаться остановиться — это предотвращает false negatives пока GitHub переcomputes. +1. **Локальный** — `git merge-tree --write-tree --name-only origin/ HEAD`. При конфликте сообщение deny указывает конфликтные файлы, чтобы Claude знал ровно, что разрешить. +2. **GitHub** — повторно использует результат `gh pr view --json mergeable,state`, уже загруженный при предварительной проверке. Перехватывает конфликты, которые устаревший локальный `origin/` пропустил бы (например, кто-то посадил конфликтующий PR на `main` с последней fetch). Результат `CONFLICTING` запрещает. Результат `UNKNOWN` также запрещает и инструктирует Claude дождаться ~10 секунд и переповторить проверку перед попыткой остановки снова — это предотвращает ложные отрицания, пока GitHub пересчитывает. -Пропускает полностью (разрешает) когда: `gh` не установлена, нет PR для ветки, PR состояние не `OPEN` (например `MERGED`, `CLOSED`), или `gh pr view` возвращает распарсиваемый вывод. Также fails open когда `origin/` пропущена локально или когда нет commits вперёд от base — те Layer 1 fall-throughs всё ещё консультируют cached PR mergeability перед разрешением. +Пропускает полностью (разрешает) при: `gh` не установлена, нет PR для ветви, состояние PR не `OPEN` (например, `MERGED`, `CLOSED`), или `gh pr view` возвращает непарсируемый вывод. Также fail-open, когда `origin/` отсутствует локально или когда нет коммитов впереди базовой — те Layer 1 pass-through всё ещё консультируются с кэшированной слияемостью PR перед разрешением. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Base ветка для проверки конфликтов. | +| `baseBranch` | `string` | `"main"` | Базовая ветвь для проверки конфликтов. | GitHub CLI (`gh`) требуется для этой политики. Политика использует `gh pr view` для подтверждения -существует ли `OPEN` PR перед запуском любого probe конфликтов — без `gh`, политика -short-circuits к разрешению. Запустите `gh auth login` с personal access token, который имеет -`repo` scope для чтения pull requests. +наличия `OPEN` PR перед запуском любого зонда конфликта — без `gh` политика +short-circuit в разрешение. Выполните `gh auth login` с персональным токеном доступа, имеющим +область `repo` для доступа на чтение к pull request-ам. --- @@ -805,14 +805,14 @@ short-circuits к разрешению. Запустите `gh auth login` с pe ### `require-ci-green-before-stop` **Событие:** Stop -**По умолчанию:** Блокирует остановку когда CI checks падают или всё ещё запускаются на текущей ветке. Проверяет GitHub Actions workflow runs и сторонние bot checks (например CodeRabbit, SonarCloud, Codecov). Обрабатывает `skipped`, `cancelled` и `neutral` выводы как non-failing (последний охватывает например Socket Security alerts на outside contributor PR, где app намеренно сообщает neutral вместо success/failure). Возвращает информационное сообщение когда все checks проходят. +**По умолчанию:** Запрещает остановку, когда проверки CI не пройдены или всё ещё выполняются на текущей ветви. Проверяет как GitHub Actions workflow runs, так и сторонние bot checks (например, CodeRabbit, SonarCloud, Codecov). Обрабатывает `skipped`, `cancelled` и `neutral` результаты как не неудачные (последняя категория охватывает, например, Socket Security alerts на PR внешних контрибьюторов, где приложение намеренно сообщает neutral вместо success/failure). Возвращает информационное сообщение, когда все проверки пройдены. Нет параметров. -Эта политика требует [GitHub CLI](https://cli.github.com/) (`gh`) установленной и аутентифицированной. -Запустите `gh auth login` с personal access token, который имеет `repo` scope для чтения -Actions workflow runs и Checks API. Если `gh` не установлена или не аутентифицирована, политика fails open и сообщает причину Claude. +Эта политика требует установку и аутентификацию [GitHub CLI](https://cli.github.com/) (`gh`). +Выполните `gh auth login` с персональным токеном доступа, имеющим область `repo` для доступа на чтение к +Actions workflow runs и Checks API. Если `gh` не установлена или не аутентифицирована, политика fail-open и сообщает причину Claude. --- @@ -821,7 +821,7 @@ Actions workflow runs и Checks API. Если `gh` не установлена ## Отключение отдельных политик -Удалить конкретную политику из `enabledPolicies` в вашей конфигурации, или переключить её в dashboard Policies tab. +Удалите определённую политику из `enabledPolicies` в вашей конфигурации или переключите её в таб Policies на дашборде. ```json { @@ -832,4 +832,4 @@ Actions workflow runs и Checks API. Если `gh` не установлена } ``` -Политики не listed в `enabledPolicies` не запускаются, даже если `policyParams` записи для них существуют. \ No newline at end of file +Политики не перечисленные в `enabledPolicies` не запускаются, даже если существуют записи `policyParams` для них. \ No newline at end of file diff --git a/docs/ru/cli/audit.mdx b/docs/ru/cli/audit.mdx index a9e63e98..d3693eec 100644 --- a/docs/ru/cli/audit.mdx +++ b/docs/ru/cli/audit.mdx @@ -1,17 +1,17 @@ --- -title: Аудит прошлых сеансов (beta) -description: "Подсчитайте, как часто агент совершал неэффективные или рискованные действия в прошлых транскриптах" +title: Проверка прошлых сеансов (бета) +description: "Подсчитайте, как часто агент выполнял неэффективные или рискованные операции в прошлых транскриптах" --- - **Бета-функция.** Аудит поставляется в виде бета-версии, пока мы собираем первоначальные отзывы. - Каталог детекторов и формат отчета могут измениться перед следующим стабильным выпуском. - Пожалуйста, откройте issue, если что-то выглядит неправильно. + **Бета-функция.** Аудит выпущен в бета-версии для сбора первых отзывов. + Каталог детекторов и формат отчета могут измениться перед следующим стабильным + релизом. Пожалуйста, откройте проблему, если что-то выглядит неправильно. -Аудит повторно воспроизводит ваши прошлые транскрипты agent-CLI через механизм политик failproofai и создает удобный для совместного использования визуальный отчет на странице **`/audit` dashboard** — архетип вашего агента, оценка от 0 до 100 и точно то, какие политики могли бы поймать что-либо. +Аудит воспроизводит ваши прошлые транскрипты агента-CLI через механизм политик failproofai и рендеринге удобный для обмена визуальный отчет на **странице панели `/audit`** — архетип агента, оценка от 0 до 100 и ровно какие политики что бы перехватили. -## Запустите его +## Запустить Три способа — все ведут к одному отчету `/audit`. @@ -25,7 +25,7 @@ npx -y failproofai audit failproofai audit ``` -```bash failproofai (dashboard) +```bash failproofai (панель) failproofai ``` @@ -34,60 +34,60 @@ failproofai `npx -y failproofai audit` загружает failproofai, запускает сканирование и открывает - дашборд для вас — ничего не нужно устанавливать заранее. + панель для вас — ничего не нужно устанавливать заранее. - `failproofai audit` запускает сканирование в вашем терминале, затем - автоматически открывает `localhost:8020/audit` по завершении. + `failproofai audit` запускает сканирование в терминале, затем автоматически открывает + `localhost:8020/audit` по завершении. - + Запустите `failproofai` и нажмите **Audit** в навигационной панели (между Policies и - Projects) или откройте `/audit` напрямую. + Projects), или откройте `/audit` напрямую. - Запустите `failproofai audit -h` (или `--help`) чтобы увидеть справку по использованию. Аудит работает **полностью - офлайн** — не требуется аккаунт или сетевое соединение — и дашборд продолжает работать - до тех пор, пока вы не остановите его с помощью `Ctrl+C`. + Запустите `failproofai audit -h` (или `--help`) для просмотра справки. Аудит работает **полностью + оффлайн** — аккаунт или сеть не требуются — и панель продолжает работать + до тех пор, пока вы не остановите её с помощью `Ctrl+C`. -Дашборд сканирует прошлые транскрипты agent CLI на этой машине (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) и отчитывается о том, как часто агент совершал действия, которые failproofai предназначена остановить — проверки переменных окружения, force push, избыточные префиксы `cd `, sleep-polling циклы, повторное чтение файлов, только что отредактированных, и многое другое. +Панель сканирует прошлые транскрипты агента CLI на этой машине (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) и сообщает, как часто агент выполнял операции, которые failproofai создан, чтобы остановить — проверки переменных окружения, force push, повторяющиеся префиксы `cd `, sleep-polling циклы, повторное чтение только что отредактированных файлов и многое другое. -Для каждого транскрипта каждое событие tool-use повторно воспроизводится через 39 встроенных политик **и** через 8 детекторов только для аудита, которые ловят паттерны, еще не охватанные политиками времени выполнения. Подсчеты агрегируются по политикам / детекторам во всех сеансах. +Для каждого транскрипта каждое событие использования инструмента воспроизводится через 39 встроенных политик **и** через 8 аудит-специфичных детекторов, которые выявляют паттерны, еще не покрытые политиками реального времени. Подсчеты агрегируются для каждой политики/детектора по всем сеансам. ## Что вы получите -Страница `/audit` — это один экран, общедоступный **постер**, за которым следуют четыре раздела ниже складки: +Страница `/audit` — это односкринный, готовый для обмена **постер**, за которым следуют четыре скрытых раздела: -1. **Постер** — идентичность вашего агента с первого взгляда: его **архетип** (один из 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), ключевые слова его персоны, насколько редкий этот архетип и **оценка от 0 до 100** с полосой уровня (`S` вниз до `bottom tier`). Создано для совместного использования — публикуйте в X или LinkedIn или загружайте как PNG. -2. **`// strengths`** — то, что ваш агент уже делает хорошо, как реальные цифры из сканирования (например, чистый процент tool-call, `0` попыток push-to-main), показывается только там, где соответствующая политика имеет чистую запись. -3. **`// quirks`** — то, что прошло мимо: ранжированная таблица поведений, которые failproofai перехватила бы — *когда* это последний раз произошло, *что прошло* (и встроенная функция, которая это заблокировала бы), его *серьезность* и как часто это было *замечено* (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — рекомендуемый список исправлений: одна строка на политику с копируемой `failproofai policy add `, плюс кнопка **install all**, которая включает все рекомендации сразу и показывает вашу **прогнозируемую оценку**, если бы вы это сделали. -5. **`// come back better`** — выработайте привычку: установите напоминание по электронной почте о повторном аудите **reminder** (`3d` / `7d` / `14d` / `30d`) или проведите повторный аудит сейчас, и **пригласите друга** запустить свой собственный аудит (отправляется с failproof.ai, скопировано вам). Напоминания и приглашения требуют входа — см. [`failproofai auth`](/ru/cli/auth). +1. **Постер** — идентичность вашего агента с первого взгляда: его **архетип** (один из 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), ключевые слова персоны, насколько редок этот архетип, и **оценка от 0 до 100** с полосой уровня (`S` до `bottom tier`). Создан для обмена — опубликуйте на X или LinkedIn, или загрузите как PNG. +2. **`// strengths`** — что ваш агент уже делает хорошо, как реальные числа из сканирования (например, clean-tool-call %, `0` попыток push-to-main), показано только там, где соответствующая политика имеет чистую историю. +3. **`// quirks`** — что прошло: таблица с рейтингом поведения, которое failproofai бы перехватил — *когда* это последний раз произошло, *что прошло* (и встроенная политика, которая бы это заблокировала), его *серьезность* и как часто это было *видно* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — предписанный список исправлений: одна строка для каждой политики с copy-paste `failproofai policy add `, плюс кнопка **install all**, которая включает каждую рекомендацию сразу и показывает вашу **projected score**, если бы вы это сделали. +5. **`// come back better`** — выработайте привычку: установите напоминание **reminder** по электронной почте для повторного аудита (`3d` / `7d` / `14d` / `30d`) или повторите аудит сейчас, и **пригласите друга** запустить свой собственный аудит (отправлено с failproof.ai, копия вам). Напоминания и приглашения требуют входа — см. [`failproofai auth`](/ru/cli/auth). -## Детекторы только для аудита +## Аудит-специфичные детекторы -Они обнаруживают паттерны "глупого поведения", которые (еще) не применяются в реальном времени. Они работают только во время аудита и никогда не блокируют живой вызов tool. +Они выявляют паттерны "глупого поведения", не (еще) принудительно применяемые в реальном времени. Они запускаются только во время аудита и никогда не блокируют вызов инструмента в реальном времени. -| Детектор | Что считается | +| Детектор | Что он подсчитывает | |---|---| -| `redundant-cd-cwd` | Bash команды, начинающиеся с `cd && …`, даже если команды уже работают в `cwd`. | +| `redundant-cd-cwd` | Bash команды, начинающиеся с `cd && …` хотя команды уже выполняются в `cwd`. | | `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` на одном исходном файле — используйте инструмент `Read`. | -| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` встроенные редактирования — используйте инструмент `Edit`. | -| `prefer-write-over-heredoc` | Heredoc / многострочная `echo > file` запись файлов — используйте инструмент `Write`. | +| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` редактирование на месте — используйте инструмент `Edit`. | +| `prefer-write-over-heredoc` | Heredoc / многострочный `echo > file` запись файлов — используйте инструмент `Write`. | | `sleep-polling-loop` | Длинный `sleep N` (≥ 30s) или `while …; sleep …; done` polling циклы. | -| `find-from-root` | `find /`, `find /home`, `find /usr` и т.д. — ограничьте `cwd` вместо этого. | +| `find-from-root` | `find /`, `find /home`, `find /usr` и т.д. — ограничьте областью `cwd`. | | `git-commit-no-verify` | `git commit … --no-verify` / `-n`, пропуск хуков. | | `reread-after-edit` | `Read` файла, который был только что `Edit`/`Write` в том же сеансе. | ## Кэши -- **Кэш на транскрипт** по `~/.failproofai/cache/audit/.json`, индексируемый по `(mtime, size, engineVersion, detectorVersion)` — автоматически инвалидируется, когда транскрипт или код политики/детектора изменяются. Каждая запись также хранит временную метку `cachedAt` как **метаданные TTL** (не являющиеся частью ключа кэша); записи старше **7 дней** отклоняются при чтении, чтобы долгоживущие результаты не переживали развивающееся намерение детектора. -- **Кэш полного результата** по `~/.failproofai/audit-dashboard.json` (режим 0600). Позволяет дашборду отображаться мгновенно при навигации без переквапуска. Также отклоняется при чтении после **7-дневного TTL** — `/audit` затем переходит в пустое состояние и предлагает свежий запуск. Нажмите `[ re-audit now ]` рядом с нижней частью отчета, чтобы обновить — повторный аудит отправляет `noCache: true`, поэтому он обходит кэш на транскрипт и повторно сканирует каждый транскрипт вместо возврата кэшированного результата; запуск отправляет прогресс через липкую верхнюю полосу и заменяет результат на месте при успехе (без перезагрузки страницы; неудачный повторный аудит сохраняет предыдущий отчет). +- **Кэш на транскрипт** в `~/.failproofai/cache/audit/.json` с ключом по `(mtime, size, engineVersion, detectorVersion)` — автоматически инвалидируется при изменении транскрипта или кода политики/детектора. Каждая запись также хранит временную метку `cachedAt` как **TTL метаданные** (не часть ключа кэша); записи старше **7 дней** отклоняются при чтении, чтобы долгоживущие результаты не пережили эволюцию намерения детектора. +- **Кэш полного результата** в `~/.failproofai/audit-dashboard.json` (режим 0600). Позволяет панели рендериться мгновенно при навигации без повторного запуска. Также отклоняется при чтении после **7-дневного TTL** — `/audit` затем переходит в пустое состояние и предлагает запустить заново. Нажмите `[ re-audit now ]` в нижней части отчета для обновления — повторный аудит отправляет `noCache: true`, поэтому он обходит кэш на транскрипт и повторно сканирует каждый транскрипт вместо возврата кэшированного результата; запуск выводит прогресс через липкую верхнюю полосу и заменяет результат на месте при успехе (без перезагрузки страницы; неудачный повторный аудит сохраняет предыдущий отчет). -## Заметки +## Примечания -- **Без изменений.** Аудит повторно воспроизводится в режиме только для чтения. `warn-repeated-tool-calls` пропускается, потому что его боковой сопровождающий сеанс в противном случае был бы изменен. -- **Политики рабочего процесса пропущены.** Политики `require-*-before-stop` срабатывают только на событиях `Stop` и `execSync` в соответствии с живым состоянием git — они не имеют значимой интерпретации "что бы произошло в 2025", поэтому они не отображаются в подсчетах аудита. -- **Пользовательские политики пропущены.** Пользовательские хуки, предоставленные пользователем, не воспроизводятся (они могли измениться с момента исходного сеанса). \ No newline at end of file +- **Без изменений.** Аудит воспроизводится в режиме только чтения. `warn-repeated-tool-calls` пропускается, так как его сопровождающий файл на сеанс иначе был бы изменен. +- **Пропущены политики рабочего процесса.** Политики `require-*-before-stop` срабатывают только на события `Stop` и `execSync` в реальном состоянии git — они не имеют значимого толкования "что бы произошло в 2025", поэтому они не появляются в подсчетах аудита. +- **Пользовательские политики пропущены.** Предоставляемые пользователем пользовательские хуки не воспроизводятся (они могли измениться с исходного сеанса). \ No newline at end of file diff --git a/docs/ru/cli/auth.mdx b/docs/ru/cli/auth.mdx index 5cd486de..639be538 100644 --- a/docs/ru/cli/auth.mdx +++ b/docs/ru/cli/auth.mdx @@ -1,17 +1,17 @@ --- title: Вход в систему -description: "Войдите в FailproofAI из CLI, чтобы получить доступ к напоминаниям и персональным функциям" +description: "Войдите в FailproofAI из CLI, чтобы включить напоминания и персонализированные функции" --- ```bash failproofai auth login # email + одноразовый код -failproofai auth logout # отозвать текущий сеанс +failproofai auth logout # отозвать этот сеанс failproofai auth whoami # вывести идентификацию вошедшего пользователя ``` Устаревшая форма флагов `--login` / `--logout` / `--whoami` по-прежнему поддерживается как псевдоним для обратной совместимости. -Аутентификация — добровольная. Политики, панель управления, страница `/audit` и все остальные локальные функции работают одинаково независимо от того, вошли ли вы в систему или нет. Экран входа существует для функций, которые **требуют** стабильного идентификатора (напоминания о переаудите сегодня, в будущем и больше). +Аутентификация является опциональной. Политики, приборная панель, страница `/audit` и все остальные локальные функции работают одинаково независимо от того, вошли вы в систему или нет. Интерфейс входа существует для того, чтобы функции, которым **требуется** стабильная идентификация (напоминания о переаудите сегодня, более в будущем), имели якорь. ## Процесс входа @@ -19,29 +19,29 @@ failproofai auth whoami # вывести идентификацию вошед failproofai auth login ``` -Запросит ваш адрес электронной почты, отправит 6-значный одноразовый код на этот адрес, запросит код, а при успехе запишет `~/.failproofai/auth.json` (режим `0600`). Тот же сеанс станет видимым в панели приложения — при нажатии `[ set a reminder ]` на `/audit` вы будете отображаться как вошедший в систему. +Запрашивает ваш адрес электронной почты, отправляет на него 6-значный одноразовый код, запрашивает код и при успехе записывает `~/.failproofai/auth.json` (режим `0600`). Тот же сеанс затем видим на встроенной приборной панели — нажатие `[ set a reminder ]` на `/audit` покажет вас как вошедшего. -Панель управления предоставляет тот же процесс в виде модального диалога на `/audit` для пользователей, которые никогда не используют CLI. +Приборная панель предоставляет тот же процесс в виде модального диалога на `/audit` для пользователей, которые никогда не работают с CLI. -## Выход из системы +## Выход ```bash failproofai auth logout ``` -Отзывает текущий сеанс на сервере и удаляет `~/.failproofai/auth.json`. Если api-сервер недоступен, локальный файл удаляется в любом случае — локальное намерение выйти из системы всегда имеет приоритет. +Отзывает текущий сеанс на сервере и удаляет `~/.failproofai/auth.json`. Если api-сервер недоступен, локальный файл удаляется в любом случае — локальное намерение выйти всегда имеет приоритет. -## Проверка личности +## Проверка идентификации ```bash failproofai auth whoami ``` -Выводит ` ()` и завершает работу с кодом 0, если существует действительный сеанс, или `not signed in` и завершает работу с кодом 1 в противном случае. Незаметно обновляет маркер доступа в фоне, если до его истечения остаётся менее минуты. +Выводит ` ()` и выходит с кодом 0, когда существует действительный сеанс, или `not signed in` и выходит с кодом 1 в противном случае. Молча обновляет токен доступа в фоне, если он находится в пределе минуты до истечения. ## Постоянное напоминание о переаудите -Когда вы нажимаете **`[ set a reminder ]`** на странице `/audit` (или входите через модальное окно, которое вскрывает кнопка), панель управления создаёт небольшой вспомогательный файл в `~/.failproofai/next-audit.json`: +Когда вы нажимаете **`[ set a reminder ]`** на странице `/audit` (или входите через модальное окно, которое закрывает кнопка), приборная панель записывает небольшой сопутствующий файл в `~/.failproofai/next-audit.json`: ```json { @@ -51,11 +51,11 @@ failproofai auth whoami } ``` -Этот файл привязан к электронной почте, для которой он был установлен — переключение сеанса CLI на другую учётную запись скроет любое напоминание, относящееся к предыдущему пользователю. Смещение по умолчанию составляет **7 дней**, оно будет настраиваемым после добавления планировщика. Создаётся с разрешениями `0600`, как и `auth.json`. +Этот файл привязан к электронной почте, для которой он был установлен — переключение сеанса CLI на другой аккаунт скрывает любое напоминание, принадлежащее предыдущему пользователю. Смещение по умолчанию — **7 дней**, позже будет настраиваться при внедрении планировщика. Создан с разрешениями `0600` как `auth.json`. -Точка доступа `/api/auth/reminder` панели управления предоставляет `GET` (чтение), `POST` (установка / переназначение) и `DELETE` (очистка) и требует активный сеанс. +Конечная точка `/api/auth/reminder` приборной панели предоставляет `GET` (чтение), `POST` (установка / переплан) и `DELETE` (очистка) и требует активного сеанса. -## Содержимое `~/.failproofai/auth.json` +## Что находится в `~/.failproofai/auth.json` ```json { @@ -67,21 +67,21 @@ failproofai auth whoami } ``` -Создаётся с разрешениями `0600` (чтение/запись только для владельца). Маркер доступа — это JWT на основе HS256 с временем жизни 1 час; маркер обновления — это непрозрачная случайная строка на 256 бит, которую сервер хранит как `SHA-256(token)`. Повторное использование маркера обновления обнаруживается на стороне сервера и отзывает все сеансы пользователя. +Создан с разрешениями `0600` (чтение/запись только владельцем). Токен доступа — это 1-часовой HS256 JWT; токен обновления — это непрозрачная 256-битная случайная строка, которую сервер хранит как `SHA-256(token)`. Повторное использование токена обновления обнаруживается на стороне сервера и отзывает все сеансы пользователя. ## Переменные окружения | Переменная | По умолчанию | Назначение | |---|---|---| -| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | Переопределить базовый URL api-сервера. Полезно для локальной разработки с самостоятельно размещённым api-сервером. | +| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | Переопределить базовый URL api-сервера. Полезно для локальной разработки с самостоятельно размещенным api-сервером. | | `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | Переопределить, где хранится `auth.json`. В основном для тестов. | -Полный список см. в разделе [Переменные окружения](/ru/cli/environment-variables). +См. [Переменные окружения](/ru/cli/environment-variables) для полного списка. ## Устранение неполадок -**"Could not reach the api-server"** — CLI не может открыть TCP-соединение с `FAILPROOF_API_URL`. Проверьте сетевое соединение или установите `FAILPROOF_API_URL`, если вы используете самостоятельно размещённый api-сервер. +**"Could not reach the api-server"** — CLI не может открыть TCP-соединение с `FAILPROOF_API_URL`. Проверьте вашу сеть или установите `FAILPROOF_API_URL`, если вы запускаете самостоятельно размещенный api-сервер. -**"Rate limited"** — слишком много попыток входа в 15-минутном окне для этой электронной почты (5 на адрес) или IP (20 на IP), либо 30-секундный период ограничения повторной отправки после предыдущего запроса для той же электронной почты. Сообщение об ошибке включает интервал повтора в секундах. +**"Rate limited"** — слишком много попыток входа в течение 15-минутного окна для этого адреса электронной почты (5/email) или IP (20/IP), или 30-секундная задержка перед повторной отправкой после предыдущего запроса для того же адреса. Сообщение об ошибке содержит окно retry-after в секундах. -**Code rejected** — OTP неверен, истёк срок действия или достигнут лимит из 5 неправильных попыток. Запустите `failproofai auth login` снова, чтобы запросить новый код. \ No newline at end of file +**Code rejected** — OTP был неправильным, истек или строка достигла блокировки после 5 неправильных попыток. Запустите `failproofai auth login` снова, чтобы запросить новый код. \ No newline at end of file diff --git a/docs/ru/cli/dashboard.mdx b/docs/ru/cli/dashboard.mdx index 53f8fdf3..f4eae016 100644 --- a/docs/ru/cli/dashboard.mdx +++ b/docs/ru/cli/dashboard.mdx @@ -1,22 +1,22 @@ --- -title: Просмотр сессий -description: "Запустите приборную панель для просмотра сессий агентов и управления политиками" +title: Просмотр сеансов +description: "Запустите панель управления для просмотра сеансов агентов и управления политиками" --- ```bash failproofai ``` -Запускает веб-приборную панель по адресу `http://localhost:8020`. +Запускает веб-панель управления по адресу `http://localhost:8020`. ## Опции | Флаг | Описание | -|------|---------| +|------|-------------| | `--port ` | Порт для прослушивания (по умолчанию: `8020`) | | `--allowed-origins ` | Разделённые запятыми хосты/IP-адреса, разрешённые для доступа к ресурсам разработки | -Чтобы указать приборной панели нестандартную папку проекта Claude, установите переменную окружения `CLAUDE_PROJECTS_PATH` при запуске. +Чтобы указать папку проекта Claude, отличную от папки по умолчанию, установите переменную окружения `CLAUDE_PROJECTS_PATH` при запуске. ## Примеры @@ -24,6 +24,6 @@ failproofai # Запуск на другом порту failproofai --port 9000 -# Использование пользовательского пути к проектам Claude через переменную окружения +# Использование пользовательского пути проектов Claude через переменную окружения CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/ru/cli/environment-variables.mdx b/docs/ru/cli/environment-variables.mdx index e945fe55..ca06ddc1 100644 --- a/docs/ru/cli/environment-variables.mdx +++ b/docs/ru/cli/environment-variables.mdx @@ -3,21 +3,21 @@ title: Переменные окружения description: "Настройка поведения failproofai с помощью переменных окружения" --- -## Панель управления +## Dashboard | Переменная | Описание | |----------|-------------| -| `PORT` | Порт панели управления (по умолчанию: `8020`) | -| `CLAUDE_PROJECTS_PATH` | Переопределить путь, где находятся папки проектов Claude Code | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Страницы панели управления для скрытия (разделенные запятыми) | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Хосты/IP-адреса, разрешенные для доступа к ресурсам разработки. Аналогично `--allowed-origins`. | +| `PORT` | Порт Dashboard (по умолчанию: `8020`) | +| `CLAUDE_PROJECTS_PATH` | Переопределить расположение папок проектов Claude Code | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Список страниц Dashboard для скрытия (через запятую) | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Хосты/IP-адреса, которым разрешен доступ к ресурсам разработки. Аналогично `--allowed-origins`. | ## Логирование | Переменная | Описание | |----------|-------------| | `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Уровень логирования сервера (по умолчанию: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | Пользовательский путь к файлу логов hook, или `true` для пути по умолчанию (`~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | Пользовательский путь к файлу логов hook, или `true` для использования значения по умолчанию (`~/.failproofai/logs/hooks.log`) | ## Телеметрия @@ -29,8 +29,8 @@ description: "Настройка поведения failproofai с помощь | Переменная | Описание | |----------|-------------| -| `FAILPROOF_API_URL` | Переопределить базовый URL API, используемый `failproofai auth` и диалогом аутентификации панели управления. По умолчанию `https://api.befailproof.ai`; установите в `http://localhost:8080` (или другое место) при запуске локального api-server. | -| `FAILPROOFAI_AUTH_DIR` | Переопределить путь хранения `auth.json` (по умолчанию: `~/.failproofai`). Полезно в основном для изолированных тестов. | +| `FAILPROOF_API_URL` | Переопределить базовый URL API-сервера, используемый `failproofai auth` и диалогом аутентификации Dashboard. По умолчанию: `https://api.befailproof.ai`; установите значение `http://localhost:8080` (или другое) при запуске локального API-сервера. | +| `FAILPROOFAI_AUTH_DIR` | Переопределить расположение хранилища `auth.json` (по умолчанию: `~/.failproofai`). В основном полезно для изолированных тестов. | ## Приглашение при первом запуске @@ -42,6 +42,6 @@ description: "Настройка поведения failproofai с помощь | Переменная | Описание | |----------|-------------| -| `FAILPROOFAI_LLM_BASE_URL` | Конечная точка API LLM (по умолчанию: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | Ключ API для политик на основе LLM | -| `FAILPROOFAI_LLM_MODEL` | Имя модели (по умолчанию: `gpt-4o-mini`) | \ No newline at end of file +| `FAILPROOFAI_LLM_BASE_URL` | Endpoint LLM API (по умолчанию: `https://api.openai.com/v1`) | +| `FAILPROOFAI_LLM_API_KEY` | API-ключ для политик на основе LLM | +| `FAILPROOFAI_LLM_MODEL` | Название модели (по умолчанию: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/ru/cli/hook.mdx b/docs/ru/cli/hook.mdx index 20aaad33..fdfc0f47 100644 --- a/docs/ru/cli/hook.mdx +++ b/docs/ru/cli/hook.mdx @@ -1,28 +1,28 @@ --- -title: Обработчик hook (внутренний) -description: "Подпроцесс, который Claude Code вызывает при каждом событии инструмента" +title: Hook handler (внутренний) +description: "Подпроцесс, который Claude Code вызывает на каждом событии инструмента" --- ```bash failproofai --hook ``` -Это команда, зарегистрированная в `settings.json` Claude Code командой `failproofai policies --install`. Обычно вы не вызываете её напрямую. +Это команда, зарегистрированная в `settings.json` Claude Code командой `failproofai policies --install`. Обычно вы не вызываете эту команду напрямую. -Считывает JSON-полезную нагрузку из stdin, оценивает все включённые политики и выходит с кодом, указывающим решение: +Считывает JSON payload из stdin, вычисляет все включенные политики и завершается с кодом, указывающим на решение: | Код выхода | Решение | Эффект | |-----------|---------|--------| | `0` | `allow` | Разрешить действие | -| `1` | `deny` | Заблокировать действие — Claude видит причину отказа | -| `2` | `instruct` | Внести рекомендации в контекст Claude | +| `1` | `deny` | Заблокировать действие — Claude увидит причину отказа | +| `2` | `instruct` | Внести указания в контекст Claude | ### Поддерживаемые типы событий | Категория | События | |-----------|---------| -| **Выполнение инструментов** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | -| **Жизненный цикл сессии** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | +| **Выполнение инструмента** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | +| **Жизненный цикл сеанса** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | | **Взаимодействие пользователя** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | | **Подагенты и задачи** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | | **Конфигурация** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | diff --git a/docs/ru/cli/install-policies.mdx b/docs/ru/cli/install-policies.mdx index 77ac83f1..e46687de 100644 --- a/docs/ru/cli/install-policies.mdx +++ b/docs/ru/cli/install-policies.mdx @@ -7,27 +7,27 @@ description: "Включите политики, чтобы они выполн failproofai policies --install [policy-names...] [options] ``` -Записывает записи hook-а в файл настроек установленного CLI агента (Claude Code, OpenAI Codex или GitHub Copilot CLI _(beta)_), чтобы failproofai перехватывал вызовы инструментов. +Записывает записи hook в файл настроек установленного CLI агента (Claude Code, OpenAI Codex или GitHub Copilot CLI _(beta)_), чтобы failproofai перехватывал вызовы инструментов. -Псевдонимы: `failproofai p -i` +Альтернативные команды: `failproofai p -i` ## Опции | Флаг | Описание | |------|-------------| -| `--cli claude\|codex\|copilot` | CLI агента(ов) для установки; разделённые пробелами (например `--cli claude codex copilot`) или повторяющиеся. Опустите, чтобы обнаружить установленные CLI и получить запрос. | -| `--scope user` | Установить в файл настроек области пользователя (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). По умолчанию. | -| `--scope project` | Установить в файл настроек области проекта (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | -| `--scope local` | Только для Claude — устанавливает в `/.claude/settings.local.json`. Codex и Copilot не имеют локальной области. | -| `--custom ` / `-c` | Путь к файлу JS, содержащему пользовательские политики hook-а | +| `--cli claude\|codex\|copilot` | CLI агента(ов) для установки; разделённые пробелом (например `--cli claude codex copilot`) или повторённые. Если опущено, система автоматически обнаружит установленные CLI и запросит выбор. | +| `--scope user` | Установить в пользовательский файл настроек (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). По умолчанию. | +| `--scope project` | Установить в файл настроек проекта (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | +| `--scope local` | Только для Claude — установить в `/.claude/settings.local.json`. Codex и Copilot не поддерживают область `local`. | +| `--custom ` / `-c` | Путь к файлу JS, содержащему пользовательские политики hook | ## Поведение -- **Без названий политик** - открывает интерактивный запрос для выбора политик -- **Конкретные названия** - включает эти политики (добавляется к уже включённым) -- **`all`** - включает все доступные политики +- **Без названий политик** — открывает интерактивное окно для выбора политик +- **Конкретные названия** — включает эти политики (добавляет их к уже включённым) +- **`all`** — включает все доступные политики -Установка является аддитивной: повторный запуск `--install` добавляет новые политики без удаления существующих. +Установка носит аддитивный характер: повторный запуск `--install` добавляет новые политики без удаления существующих. ## Примеры @@ -38,10 +38,10 @@ failproofai policies --install # Установить конкретные политики для текущего проекта failproofai policies --install block-sudo sanitize-api-keys --scope project -# Включить все политики одновременно +# Включить все политики сразу failproofai policies --install all -# Установить с пользовательским файлом политик +# Установить с файлом пользовательских политик failproofai policies --install --custom ./my-policies.js # Установить для OpenAI Codex (область проекта) @@ -54,4 +54,4 @@ failproofai policies --install --cli copilot --scope project failproofai policies --install --cli claude codex copilot ``` -Когда указан `--custom `, файл сразу же проверяется — он должен вызвать `customPolicies.add()` минимум один раз. Разрешённый путь сохраняется в `policies-config.json` как `customPoliciesPath`. \ No newline at end of file +Если указан параметр `--custom `, файл немедленно проверяется — он должен хотя бы один раз вызвать `customPolicies.add()`. Разрешённый путь сохраняется в `policies-config.json` как `customPoliciesPath`. \ No newline at end of file diff --git a/docs/ru/cli/list-policies.mdx b/docs/ru/cli/list-policies.mdx index d279ca08..8f0197e4 100644 --- a/docs/ru/cli/list-policies.mdx +++ b/docs/ru/cli/list-policies.mdx @@ -1,4 +1,5 @@ --- +--- title: Список политик description: "Посмотрите, какие политики включены, их параметры и пользовательские политики" --- @@ -7,7 +8,7 @@ description: "Посмотрите, какие политики включены failproofai policies ``` -Отображает все политики с их статусом, настроенными параметрами и пользовательскими политиками. +Показывает все политики с их статусом, настроенными параметрами и пользовательскими политиками. ## Пример вывода @@ -28,4 +29,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -Неизвестные ключи в `policyParams` здесь отмечаются, чтобы вы могли рано выявить опечатки. \ No newline at end of file +Неизвестные ключи в `policyParams` отмечаются здесь, чтобы вы могли выявить опечатки на ранней стадии. \ No newline at end of file diff --git a/docs/ru/cli/remove-policies.mdx b/docs/ru/cli/remove-policies.mdx index 9b206379..920968d8 100644 --- a/docs/ru/cli/remove-policies.mdx +++ b/docs/ru/cli/remove-policies.mdx @@ -1,41 +1,41 @@ --- title: Удаление политик -description: "Удалите записи hook из settings Claude Code" +description: "Удаление записей hook из settings Claude Code" --- ```bash failproofai policies --uninstall [policy-names...] [options] ``` -Удаляет записи failproofai hook из `settings.json` Claude Code. +Удаляет записи hook failproofai из файла `settings.json` Claude Code. -Альтернативные команды: `failproofai p -u` +Alias: `failproofai p -u` -## Параметры +## Опции | Флаг | Описание | |------|-------------| | `--scope user` | Удалить из глобальных параметров (по умолчанию) | | `--scope project` | Удалить из параметров проекта | | `--scope local` | Удалить из локальных параметров | -| `--scope all` | Удалить из всех областей сразу | +| `--scope all` | Удалить из всех областей одновременно | | `--custom` / `-c` | Очистить `customPoliciesPath` из конфигурации | ## Поведение -- **Без названий политик** — удаляет все записи failproofai hook из файла параметров -- **Конкретные названия** — отключает эти политики, но сохраняет установленные hook +- **Без названий политик** — удаляет все записи hook failproofai из файла параметров +- **Конкретные названия** — отключает эти политики, но оставляет hooks установленными ## Примеры ```bash -# Удалить все hook глобально +# Удалить все hooks глобально failproofai policies --uninstall -# Отключить конкретную политику (hook остаются установленными) +# Отключить конкретную политику (hooks остаются установленными) failproofai policies --uninstall block-sudo -# Удалить hook из всех областей +# Удалить hooks из всех областей failproofai policies --uninstall --scope all # Очистить путь к пользовательским политикам diff --git a/docs/ru/configuration.mdx b/docs/ru/configuration.mdx index 3130ea3e..8a9c41e9 100644 --- a/docs/ru/configuration.mdx +++ b/docs/ru/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 | +| **project** | `.failproofai/policies-config.json` | Параметры репо, закоммичены в систему контроля версий | +| **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,7 +46,7 @@ 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`** — первая область, которая её определяет, побеждает. @@ -102,79 +102,79 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← переходит Тип: `string[]` -Список имён политик для включения. Имена должны точно совпадать с идентификаторами политик, показанными `failproofai policies`. См. [Built-in Policies](/ru/built-in-policies) для полного списка. +Список имён политик для активации. Имена должны точно совпадать с идентификаторами политик, показываемыми `failproofai policies`. Полный список см. в разделе [Built-in Policies](/ru/built-in-policies). -Политики, не указанные в `enabledPolicies`, неактивны, даже если у них есть записи в `policyParams`. +Политики, не входящие в `enabledPolicies`, неактивны, даже если у них есть записи в `policyParams`. ### `policyParams` Тип: `Record>` -Переопределения параметров для каждой политики. Внешний ключ — имя политики; внутренние ключи — специфичны для политики. Каждая политика документирует свои доступные параметры в [Built-in Policies](/ru/built-in-policies). +Переопределения параметров для каждой политики. Внешний ключ — имя политики; внутренние ключи — специфичны для политики. Каждая политика документирует свои доступные параметры в разделе [Built-in Policies](/ru/built-in-policies). -Если политика имеет параметры, но вы их не указываете, используются встроенные значения по умолчанию политики. Пользователи, которые вообще не настраивают `policyParams`, получают идентичное поведение предыдущим версиям. +Если у политики есть параметры, но вы их не указали, используются встроенные значения по умолчанию политики. Пользователи, которые вообще не настраивают `policyParams`, получают поведение, идентичное предыдущим версиям. Неизвестные ключи внутри блока параметров политики молча игнорируются при срабатывании хука, но помечаются как предупреждения при запуске `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": "Попробуйте создать новую ветку вместо этого." + "hint": "Try creating a fresh branch instead." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], - "hint": "Используйте apt-get непосредственно без sudo." + "hint": "Use apt-get directly without sudo." }, "custom/my-policy": { - "hint": "Сначала попросите одобрение у пользователя." + "hint": "Ask the user for approval first." } } } ``` -Когда `block-force-push` отклоняет, Claude видит: *"Force-pushing заблокирован. Попробуйте создать новую ветку вместо этого."* +Когда `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 ` (путь разрешается в абсолютный перед сохранением). -Файл загружается заново при каждом событии хука — кэширование отсутствует. Подробности разработки см. в [Custom Policies](/ru/custom-policies). +Файл загружается заново при каждом событии хука — кеширования нет. Подробности авторства см. в разделе [Custom Policies](/ru/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`, который использует правило первой побеждающей области). -Подробности и примеры см. в [Custom Policies](/ru/custom-policies). +Подробности и примеры см. в разделе [Custom Policies](/ru/custom-policies). ### `llm` Тип: `object` (опционально) -Конфигурация LLM клиента для политик, которые выполняют вызовы AI. Не требуется для большинства установок. +Конфигурация LLM-клиента для политик, которые делают AI-вызовы. Не требуется для большинства установок. ```json { @@ -189,19 +189,20 @@ 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 _(beta)_**: `~/.copilot/hooks/failproofai.json` (пользователь), `/.github/hooks/failproofai.json` (проект) — Copilot не имеет локальной области. Записи хука используют поля команды `bash`/`powershell` Copilot с ключом `timeoutSec`; файл содержит маркер уровня верхнего уровня `version: 1`. Поддержка Copilot CLI находится в **beta**, пока мы проверяем схему записи `events.jsonl` (которую не указывает официальная документация) против более реальных сессий. - - **Cursor Agent _(beta)_**: `~/.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 находится в **beta**, пока мы проверяем формат записи записей Cursor на диске (не указан в официальной документации) против более реальных установок. - - **OpenCode _(beta)_**: `~/.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 в подпроцессе и переводит ответ JSON двоичного файла в семантику плагина: `throw new Error()` для отклонения события инструмента (отменяет вызов инструмента), `client.session.prompt(...)` для instruct И для отклонения `Stop` / `SubagentStop` (отправляет причину отклонения в качестве следующего сообщения пользователя — единственный канал принудительного повторного попытки, так как `session.idle` доступна только для уведомлений и выброс из неё не работает), и 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 не имеет локальной области. 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` уже имел fallback `path`). Поддержка Pi находится в **beta**, пока стабилизируются API расширений Pi и макет журнала сессий. - - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (пользователь), `/.gemini/settings.json` (проект) — Gemini не имеет локальной области (документирует область `system` в `/etc/gemini-cli/settings.json`, которую failproofai не предоставляет). Записи хука используют форму Claude `{type, command, timeout}`, завёрнутую в схему сопоставителя Gemini `{matcher, hooks: [...]}` с `matcher: "*"` по умолчанию. События — PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); обработчик отображает на канонические имена Claude через `GEMINI_EVENT_MAP`. Имена инструментов — snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — обработчик канонизирует через `GEMINI_TOOL_MAP`, поэтому существующие встроенные политики срабатывают без изменений. Оценка политики выдаёт плоскую форму Gemini `{decision: "deny", reason}` (предпочтительно согласно "Golden Rule" Gemini контракт exit-0), `{hookSpecificOutput: {hookEventName, additionalContext}}` для внедрения контекста на BeforeAgent / AfterTool / SessionStart и `{decision: "block", reason}` на AfterAgent для семантики принудительного повторного попытки. Поддержка Gemini CLI находится в **beta**, пока мы расширяем реальное покрытие. См. [документацию хуков Gemini CLI](https://geminicli.com/docs/hooks/). + - **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 и макет журнала сессий стабилизируются. + - **Gemini CLI _(бета)_**: `~/.gemini/settings.json` (пользователь), `/.gemini/settings.json` (проект) — Gemini не имеет локальной области (она документирует область `system` в `/etc/gemini-cli/settings.json`, которую failproofai не предоставляет). Записи хуков используют форму Claude's `{type, command, timeout}`, обёрнутую в схему matcher Gemini's `{matcher, hooks: [...]}` с `matcher: "*"` по умолчанию. События — PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); обработчик картирует на имена Claude canonical через `GEMINI_EVENT_MAP`. Названия инструментов — snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — обработчик канонизирует через `GEMINI_TOOL_MAP`, поэтому существующие встроенные политики срабатывают без изменений. Оценщик политик выдаёт плоскую форму Gemini's `{decision: "deny", reason}` (предпочтено по Gemini's Golden Rule контракту exit-0), `{hookSpecificOutput: {hookEventName, additionalContext}}` для внедрения контекста в BeforeAgent / AfterTool / SessionStart, и `{decision: "block", reason}` на AfterAgent для семантики force-retry. Поддержка Gemini CLI находится в **бета-версии**, пока мы расширяем реальное покрытие. См. [документацию хуков Gemini CLI](https://geminicli.com/docs/hooks/). + - **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`. - **`policies-config.json`** — указывает failproofai, какие политики оценивать и с какими параметрами (общее для всех CLI агентов) -Передайте `--cli claude|codex|copilot|cursor|opencode|pi|gemini` для целевого агента (разделённые пробелом или повторяемые для любого подмножества): +Передайте `--cli claude|codex|copilot|cursor|opencode|pi|gemini|hermes` для выбора конкретного агента (разделённые пробелом или повторённые для подмножества): ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +211,24 @@ 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 gemini --scope project +failproofai policies --install --cli hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` -Когда `--cli` опущена, `failproofai` обнаруживает, какие CLI агентов установлены (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): +Когда `--cli` опущен, `failproofai` обнаруживает, какие CLI агентов установлены (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini` / `which hermes`): -- **Один 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; команда хука всё ещё записывается, поэтому она активируется, как только вы установите один. +- **Один 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; команда хука всё ещё записывается, поэтому она активируется, как только вы установите один. Вы можете редактировать `policies-config.json` напрямую в любой момент; изменения вступают в силу немедленно при следующем событии хука без необходимости перезагрузки. --- -## Пример: конфигурация уровня проекта с командными значениями по умолчанию +## Пример: конфиг уровня проекта с командными значениями по умолчанию -Закоммитьте `.failproofai/policies-config.json` в ваш репозиторий: +Закоммитьте `.failproofai/policies-config.json` в ваш репо: ```json { @@ -245,4 +247,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi gem } ``` -Затем каждый разработчик может создать `.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 4f81557c..80d086c2 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,52 @@ failproofai policies --install --custom ./my-policies.js ## Два способа загрузки пользовательских политик -### Вариант 1: На основе соглашения (рекомендуется) +### Способ 1: На основе соглашений (рекомендуется) -Поместите файлы `*policies.{js,mjs,ts}` в `.failproofai/policies/` и они будут загружены автоматически — не требуются флаги или изменения конфигурации. Это работает как git hooks: положите файл, и всё работает. +Поместите файлы `*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}`; другие файлы игнорируются -- Каждый файл загружается независимо (открытое поведение при ошибке для каждого файла) +- Сканируются оба каталога проекта и пользователя (объединение — не первое совпадение) +- Файлы загружаются в алфавитном порядке в каждом каталоге. Префиксуйте с `01-`, `02-` для управления порядком +- Загружаются только файлы, совпадающие с `*policies.{js,mjs,ts}`; остальные файлы игнорируются +- Каждый файл загружается независимо (отказоустойчивая загрузка для каждого файла) - Работает вместе с явным `--custom` и встроенными политиками -Политики на основе соглашения — это самый простой способ создать стандарт качества для вашей организации. Зафиксируйте `.failproofai/policies/` в git и каждый член команды автоматически получит одинаковые правила — никакой предварительной настройки для каждого разработчика не требуется. По мере того, как ваша команда обнаруживает новые сбои, добавляйте политику и выполняйте push. Со временем они станут живым стандартом качества, который постоянно улучшается с каждым вкладом. +Политики на основе соглашений — это самый простой способ установить стандарт качества для вашей организации. Зафиксируйте `.failproofai/policies/` в git, и каждый член команды автоматически получит одинаковые правила — никакой предварительной настройки для каждого разработчика не требуется. По мере того как ваша команда обнаруживает новые режимы отказа, добавляйте политику и отправляйте её. Со временем они становятся живым стандартом качества, который совершенствуется с каждым вкладом. -### Вариант 2: Явный путь к файлу +### Способ 2: Явный путь к файлу ```bash -# Установка с пользовательским файлом политик +# Установите с пользовательским файлом политик failproofai policies --install --custom ./my-policies.js -# Замена пути к файлу политик +# Замените путь файла политик failproofai policies --install --custom ./new-policies.js -# Удаление пути пользовательской политики из конфигурации +# Удалите путь пользовательских политик из конфигурации failproofai policies --uninstall --custom ``` -Разрешённый абсолютный путь сохраняется в `policies-config.json` как `customPoliciesPath`. Файл загружается заново при каждом событии хука — кэширования между событиями нет. +Разрешённый абсолютный путь сохраняется в `policies-config.json` как `customPoliciesPath`. Файл загружается заново при каждом событии перехвата — кеширование между событиями отсутствует. -### Использование обоих способов вместе +### Использование обоих вместе -Политики на основе соглашения и явный файл `--custom` могут сосуществовать. Порядок загрузки: +Политики на основе соглашений и явный файл `--custom` могут сосуществовать. Порядок загрузки: 1. Явный файл `customPoliciesPath` (если настроен) -2. Файлы соглашения проекта (`{cwd}/.failproofai/policies/`, по алфавиту) -3. Файлы соглашения пользователя (`~/.failproofai/policies/`, по алфавиту) +2. Файлы соглашений проекта (`{cwd}/.failproofai/policies/`, в алфавитном порядке) +3. Файлы соглашений пользователя (`~/.failproofai/policies/`, в алфавитном порядке) --- @@ -98,45 +98,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()` | Разрешить операцию беззвучно | Действие безопасно, сообщение не требуется | +| `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/`) политик тоже. See [Configuration → hint](/ru/configuration#hint-cross-cutting) для подробностей. +Вы можете добавить дополнительное руководство к любому сообщению `deny` или `instruct`, добавив поле `hint` в `policyParams` — без изменения кода. Это работает для пользовательских (`custom/`), проектных соглашений (`.failproofai-project/`) и пользовательских соглашений (`.failproofai-user/`) политик. См. [Конфигурация → 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("GitHub CLI not installed, skipping CI check.")` — сообщает Claude, почему проверка была пропущена, чтобы у него был полный контекст +- **Множественные сообщения накапливаются:** если несколько политик возвращают `allow(message)`, все сообщения объединяются с переводами строк и доставляются вместе ```js customPolicies.add({ @@ -146,7 +146,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."); } @@ -160,27 +160,27 @@ customPolicies.add({ | Поле | Тип | Описание | |------|-----|---------| | `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` | Инструмент, который вызывается (например, `"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 сеанса | +| `sessionId` | `string` | Идентификатор сессии Claude Code | +| `cwd` | `string` | Рабочий каталог сессии Claude Code | +| `transcriptPath` | `string` | Путь к файлу расшифровки JSONL сессии | ### Типы событий | Событие | Когда оно срабатывает | Содержимое `toolInput` | -|---------|----------------------|----------------------| +|--------|----------------------|----------------------| | `PreToolUse` | Перед запуском инструмента Claude | Входные данные инструмента (например, `{ command: "..." }` для Bash) | | `PostToolUse` | После завершения инструмента | Входные данные инструмента + `tool_result` (выходные данные) | -| `Notification` | Когда Claude отправляет уведомление | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - хуки должны всегда возвращать `allow()`, они не могут блокировать уведомления | -| `Stop` | Когда сеанс Claude заканчивается | Пусто | +| `Notification` | Когда Claude отправляет уведомление | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — перехваты всегда должны возвращать `allow()`, они не могут блокировать уведомления | +| `Stop` | Когда сессия Claude завершается | Пусто | --- @@ -190,16 +190,16 @@ 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` накапливаются и доставляются вместе. --- -## Транзитивные импорты +## Переходящие импорты Файлы пользовательских политик могут импортировать локальные модули, используя относительные пути: @@ -218,7 +218,7 @@ customPolicies.add({ }); ``` -Все относительные импорты, достижимые из файла входа, разрешаются. Это реализуется путём переписывания импортов `from "failproofai"` на фактический путь dist и создания временных файлов `.mjs` для обеспечения совместимости ESM. +Все относительные импорты, доступные из файла записи, разрешены. Это реализуется путём переписывания импортов `from "failproofai"` на фактический путь dist и создания временных файлов `.mjs` для обеспечения совместимости ESM. --- @@ -231,33 +231,33 @@ 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` полностью, чтобы срабатывать для каждого типа события. --- ## Обработка ошибок и режимы отказа -Пользовательские политики **открыты при ошибке**: ошибки никогда не блокируют встроенные политики и не приводят к сбою обработчика хука. +Пользовательские политики являются **отказоустойчивыми**: ошибки никогда не блокируют встроенные политики и не сбивают обработчик перехвата. | Отказ | Поведение | -|-------|-----------| -| `customPoliciesPath` не установлен | Явные пользовательские политики не выполняются; политики соглашения и встроенные политики продолжают работать нормально | -| Файл не найден | Предупреждение записано в `~/.failproofai/hook.log`; встроенные политики продолжают работать | -| Синтаксическая/ошибка импорта (явная) | Ошибка записана в `~/.failproofai/hook.log`; явные пользовательские политики пропущены | -| Синтаксическая/ошибка импорта (соглашение) | Ошибка записана; этот файл пропущен, другие файлы соглашения всё ещё загружаются | -| `fn` выбрасывает исключение во время выполнения | Ошибка записана; этот хук рассматривается как `allow`; другие хуки продолжают работать | -| `fn` занимает дольше 10s | Timeout записан; рассматривается как `allow` | -| Каталог соглашения отсутствует | Политики соглашения не выполняются; нет ошибки | +|-------|----------| +| `customPoliciesPath` не установлен | Явные пользовательские политики не запускаются; встроенные и соглашения продолжают нормально работать | +| Файл не найден | Предупреждение записывается в `~/.failproofai/hook.log`; встроенные продолжают работать | +| Ошибка синтаксиса/импорта (явная) | Ошибка записывается в `~/.failproofai/hook.log`; явные пользовательские политики пропускаются | +| Ошибка синтаксиса/импорта (соглашение) | Ошибка записывается; этот файл пропускается, остальные файлы соглашений всё ещё загружаются | +| `fn` выбрасывает во время выполнения | Ошибка записывается; этот перехват трактуется как `allow`; остальные перехваты продолжают работать | +| `fn` занимает больше 10 сек | Истечение времени записывается; трактуется как `allow` | +| Каталог соглашений отсутствует | Политики соглашений не запускаются; нет ошибки | -Для отладки ошибок пользовательской политики смотрите файл журнала: +Для отладки ошибок пользовательских политик наблюдайте за файлом журнала: ```bash tail -f ~/.failproofai/hook.log @@ -272,7 +272,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 +285,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 +300,7 @@ customPolicies.add({ }, }); -// Запретить незапланированные изменения зависимостей во время заморозки +// Prevent unplanned dependency changes during freeze customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -328,26 +328,26 @@ export { customPolicies }; | Файл | Содержимое | |------|-----------| | `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 ``` -### Использование примеров на основе соглашения +### Использование примеров на основе соглашений ```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 5b60a7b0..416ba866 100644 --- a/docs/ru/dashboard.mdx +++ b/docs/ru/dashboard.mdx @@ -1,11 +1,10 @@ --- ---- -title: Панель управления -description: "Мониторинг сеансов агентов, просмотр вызовов инструментов и управление политиками" +title: Dashboard +description: "Мониторьте сеансы агентов, проверяйте вызовы инструментов и управляйте политиками" icon: chart-line --- -Панель управления failproofai — это локальное веб-приложение для мониторинга сеансов вашего ИИ-агента и управления политиками. Узнайте, что делали ваши агенты, пока вас не было. +Панель управления failproofai — это локальное веб-приложение для мониторинга сеансов вашего AI-агента и управления политиками. Узнайте, что делал ваш агент, пока вас не было. --- @@ -17,7 +16,7 @@ failproofai Открывается на `http://localhost:8020`. -Панель управления читает данные непосредственно из файловой системы — из папок вашего проекта Claude Code и файлов конфигурации failproofai. Ничего не записывается в удалённый сервис. +Панель управления читает данные непосредственно из файловой системы — ваши папки проектов Claude Code и файлы конфигурации failproofai. Ничего не записывается в удалённый сервис. --- @@ -25,67 +24,67 @@ failproofai ### Projects -Отображает все проекты Claude Code, OpenAI Codex, GitHub Copilot CLI _(бета)_, Cursor Agent _(бета)_, OpenCode _(бета)_, Pi _(бета)_ и Gemini CLI _(бета)_, найденные на вашем компьютере. Проекты 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` из первой записи каждого сеанса; проекты Gemini CLI обнаруживаются путём сканирования `~/.gemini/tmp//chats/session--.jsonl` (настраивается через `GEMINI_SESSIONS_DIR`) и восстановления канонического cwd из соседнего текстового маркера `.project_root`. Проект, используемый несколькими CLI, отображается как одна строка со всеми соответствующими значками. Используйте раскрывающееся меню **CLI** над таблицей для фильтрации по определённому агенту CLI; URL сохраняет ваш выбор как `?cli=claude|codex|copilot|cursor|opencode|pi|gemini`. +Список всех найденных на вашем компьютере проектов Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Gemini CLI _(beta)_ и Hermes. Проекты 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` из первой записи каждого сеанса; проекты Gemini CLI обнаруживаются путём сканирования `~/.gemini/tmp//chats/session--.jsonl` (настраивается через `GEMINI_SESSIONS_DIR`) и восстановления канонического cwd из текстового маркера `.project_root`; сеансы шлюза Hermes читаются непосредственно из его хранилища SQLite на `~/.hermes/state.db` (настраивается через `HERMES_DB_PATH`) и группируются в проекты `hermes-` по `source` (Slack/Telegram/cli/cron — сеансы шлюза не имеют cwd). Проект, который использовался несколькими CLI, отображается как одна строка со всеми соответствующими значками. Используйте выпадающее меню **CLI** над таблицей для фильтрации по конкретному агенту; URL сохраняет ваш выбор как `?cli=claude|codex|copilot|cursor|opencode|pi|gemini|hermes`. Каждый проект показывает: -- Имя проекта (производная от пути папки) -- Значок CLI — `Claude Code` (оранжевый), `OpenAI Codex` (фиолетовый), `GitHub Copilot` (синий), `Cursor Agent` (изумрудный), `OpenCode` (янтарный), `Pi` (розовый) и/или `Gemini CLI` (светло-голубой) +- Имя проекта (производное от пути папки) +- Значок CLI — `Claude Code` (оранжевый), `OpenAI Codex` (фиолетовый), `GitHub Copilot` (синий), `Cursor Agent` (изумруд), `OpenCode` (янтарь), `Pi` (розовый), `Gemini CLI` (небесно-голубой) и/или `Hermes` (индиго) - Дата последней активности сеанса -Нажмите на проект, чтобы посмотреть его сеансы. +Щёлкните по проекту, чтобы просмотреть его сеансы. ### Sessions Список всех сеансов в проекте. Каждый сеанс показывает: - ID сеанса -- Временные метки начала и завершения +- Временные метки начала и конца - Количество вызовов инструментов -- Количество активностей хука (срабатывания политик) +- Счётчик активности хуков (срабатывания политик) -Используйте фильтр диапазона дат и поиск по ID сеанса, чтобы сузить список. Сеансы отображаются постранично. +Используйте фильтр диапазона дат и поиск по ID сеанса для уточнения списка. Сеансы постранично. -Нажмите на сеанс, чтобы открыть средство просмотра сеанса. +Щёлкните по сеансу, чтобы открыть средство просмотра сеанса. ### Session viewer -Средство просмотра сеанса отвечает на ключевой вопрос для автономных агентов: что делал агент и остался ли он на правильном пути? Значок CLI рядом с заголовком указывает, является ли сеанс транскрипцией Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi или Gemini CLI. Он показывает временную шкалу всех событий в сеансе: +Средство просмотра сеанса отвечает на ключевой вопрос для автономных агентов: что сделал агент и остался ли он на курсе? Значок CLI рядом с заголовком указывает, является ли сеанс транскрипцией Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Gemini CLI или Hermes. Он показывает временную шкалу всего, что произошло в сеансе: - **Messages** — текстовые ответы Claude и подсказки пользователя - **Tool calls** — каждый инструмент, который вызвал Claude, с его входными и выходными данными -- **Policy activity** — для каждого вызова инструмента, какие политики сработали и какое решение они вернули +- **Policy activity** — для каждого вызова инструмента, какие политики срабатывали и какое решение они вернули -Панель статистики в верхней части показывает продолжительность сеанса, общее количество вызовов инструментов и сводку решений хука (количество allow / deny / instruct). +Панель статистики вверху показывает длительность сеанса, общее количество вызовов инструментов и сводку решений хуков (счётчики allow / deny / instruct). -Нажмите кнопку **Download Logs**, чтобы экспортировать сеанс. Для сеансов Claude Code, Codex, Copilot, Cursor, Pi и Gemini вы получите исходную транскрипцию JSONL на диске побайтово; для OpenCode (чьи сеансы находятся в SQLite, а не на диске) вы получите JSON-документ, отражающий основные таблицы `session` / `messages` / `parts`. +Нажмите кнопку **Download Logs** для экспорта сеанса. Для сеансов Claude Code, Codex, Copilot, Cursor, Pi и Gemini вы получаете исходную транскрипцию JSONL на диске в исходном виде; для OpenCode (чьи сеансы хранятся в SQLite, а не на диске) вы получаете JSON-документ, отражающий основные таблицы `session` / `messages` / `parts`. ### Audit -Персонифицированный отчёт о том, как ваш агент фактически себя вёл во всех прошлых сеансах. Запускает то же сканирование, что и CLI `failproofai audit`, но отображает его как одноэкранный общий постер + четыре раздела ниже линии сгиба: +Доклад, выстроенный с учётом особенностей вашего агента, о том, как он на самом деле вёл себя в прошлых сеансах. Выполняет то же сканирование, что и CLI `failproofai audit`, но отображает это как одноэкранный проверяемый постер + четыре раздела ниже видимой области: -1. **Poster** — заполняет первый видимый элемент. Самодостаточный регион захвата 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. **Strengths** — спокойный список ✓ поведений, которые ваш агент уже выполняет правильно, полученные из данных живого аудита (чистая скорость вызовов инструментов, без прямых толчков в main, нулевые утечки учётных данных, нулевые штормы повторных попыток) — каждая поверхность отображается только при наличии чистого записи политики во всё время окна аудита. -3. **Quirks** — таблица того, что проскользнуло, ранжированная по серьёзности: `when · что проскользнуло + политика, которая бы это поймала · таблетка серьёзности · 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 за отправку), отправляет их на `/api/audit/invite`, который перенаправляет на `POST /v0/invite` сервера API. API-сервер отправляет по одному письму для каждого получателя с адреса `invite@failproof.ai` с копией отправителю и установкой `Reply-To`, чтобы получатель видел, кто его пригласил, и отправитель получал копию в своем почтовом ящике. Анонимные пользователи перенаправляются через `AuthDialog` первыми, чтобы электронная почта отправителя была известна до отправки приглашений. Выполнение прав и привилегий — это последующее действие. +1. **Poster** — заполняет первый видимый экран. Автономный регион захвата 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. **Strengths** — спокойный ✓ список поведения, которое ваш агент уже выполняет правильно, полученный из данных живого аудита (чистая скорость вызовов инструментов, без прямых push на 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 за отправку), публикует их на `/api/audit/invite`, которое пересылает на `POST /v0/invite` сервера API. Сервер API отправляет одно электронное письмо на одного получателя с адреса `invite@failproof.ai` с добавлением отправителя в Cc и установкой `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` с частотой 1 Гц до завершения запуска; во время запуска к верхней части окна приклеивается прилипчивая розовая полоса прогресса с прошедшим таймером, и свежий результат меняется местами на месте при успехе (без полной перезагрузки страницы; неудачный повторный аудит оставляет предыдущий отчёт неповреждённым). При ошибке полоса становится красной с текстом, зависящим от `RerunError.kind` (`timeout` / `network` / `post_failed`). Пустое состояние (нет кэша или истекло) и состояние нулевых сеансов (кэш существует, но сканирование не нашло транскрипции) отображаются отдельно. +Работает с помощью среды выполнения `failproofai audit` — см. [Audit CLI](/ru/cli/audit) для основного механизма сканирования, поддерживаемых флагов и инвариантов кэша для каждой транскрипции. Панель управления кэширует последний результат на `~/.failproofai/audit-dashboard.json` (режим `0600`, одиночный слот, новые запуски переписывают) поэтому повторные посещения мгновенны; **кэш для каждой транскрипции и весь кэш результатов отклоняются при чтении один раз они старше 7 дней**, поэтому панель управления никогда молча не обслуживает неделю старого результата — прошлый TTL `/audit` падает в пустое состояние и подсказывает свежий запуск. Нажатие `[ re-audit now ]` рядом с нижней частью отчёта публикует `/api/audit/run` с `noCache: true` — перепроверка обходит кэш для каждой транскрипции и повторно сканирует каждую транскрипцию с нуля вместо молчаливого возврата кэшированного результата — и панель управления опрашивает `/api/audit/status` на частоте 1 Гц до завершения запуска; липкая розовая полоса прогресса закрепляется в верхней части видимой области во время запуска с истёкшим таймером, и свежий результат переставляется на место при успехе (нет полной перезагрузки страницы; неудачная перепроверка оставляет предыдущий отчёт неповреждённым). При отказе полоса становится красной с копией, предусмотренной из `RerunError.kind` (`timeout` / `network` / `post_failed`). Пустое состояние (отсутствие кэша или истекший) и состояние нулевых сеансов (кэш существует, но сканирование не нашло транскрипции) отображаются отдельно. ### Policies -Двухвкладочная страница для управления политиками и просмотра активности. +Двухвкладочная страница для управления политиками и проверки активности. - - - Множественный выбор того, какие агенты CLI защищает failproofai, в одной панели — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi и Gemini CLI все имеют строку со статусом установки (`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, Gemini CLI и Hermes все имеют строку со статусом установки (`Active` / `Detected` / `Inactive`), путём пользовательской области видимости и фирменный цветной акцент. Отметьте или снимите отметку с CLI, которые вы хотите, и нажмите `Apply changes` для установки/удаления разницы за один шаг. CLI, чьи двоичные файлы обнаружены в PATH, предварительно отмечены. + - Переключайте отдельные политики вкл/выкл одним щелчком (записывает в `~/.failproofai/policies-config.json` — общее для каждого установленного CLI) + - Разверните политику для настройки её параметров (для политик, поддерживающих `policyParams`) + - Установите путь пользовательского файла политик - - - Полная постраничная история каждого события хука, которое срабатывало во всех сеансах - - Фильтруйте по решению, типу события, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(бета)_ / Cursor Agent _(бета)_ / OpenCode _(бета)_ / Pi _(бета)_ / Gemini CLI _(бета)_), имени политики или ID сеанса - - Каждая строка показывает: временную метку, имя политики, решение, значок CLI (оранжевый = Claude Code, фиолетовый = OpenAI Codex, синий = GitHub Copilot, изумрудный = Cursor Agent, янтарный = OpenCode, розовый = Pi, светло-голубой = Gemini CLI), имя инструмента, 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`) и отображает соответствующий значок CLI в заголовке + + - Полная постраничная история каждого события хука, срабатывающего во всех сеансах + - Фильтруйте по решению, типу события, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Gemini CLI _(beta)_ / Hermes), имени политики или ID сеанса + - Каждая строка показывает: временную метку, имя политики, решение, значок CLI (оранжевый = Claude Code, фиолетовый = OpenAI Codex, синий = GitHub Copilot, изумруд = Cursor Agent, янтарь = OpenCode, розовый = Pi, небесно-голубой = Gemini CLI, индиго = Hermes), имя инструмента, 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`, Hermes `~/.hermes/state.db`) и отображает соответствующий значок CLI в заголовке @@ -93,13 +92,13 @@ failproofai ## Auto-refresh -Панель управления имеет переключатель автоматического обновления в верхней навигации. При включении текущая страница периодически обновляется, чтобы показать новые сеансы и активность политик по мере их появления. Необходимо для мониторинга долгоживущих сеансов автономных агентов. +Панель управления имеет переключатель автоматического обновления в верхней навигации. Если он включен, текущая страница периодически обновляется, чтобы показывать новые сеансы и активность политик по мере их появления. Важно для мониторинга долгоживущих сеансов автономного агента. --- ## Отключение страниц -Если вам нужны только некоторые части панели управления, установите `FAILPROOFAI_DISABLE_PAGES` в список имён страниц, разделённый запятыми: +Если вам нужны только некоторые части панели управления, установите `FAILPROOFAI_DISABLE_PAGES` на список имён страниц, разделённых запятыми: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -109,9 +108,9 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai --- -## Настройка пути проектов +## Настройка пути к проектам -По умолчанию панель управления читает из стандартного каталога проектов Claude Code. Переопределите его для пользовательских конфигураций: +По умолчанию панель управления читает из стандартного каталога проектов Claude Code. Переопределите его для пользовательских установок: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -119,7 +118,7 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Доступ с не-localhost хоста +## Доступ с хоста, отличного от localhost При запуске панели управления в **режиме разработки** (`npm run dev`) и её доступе с имени хоста, отличного от `localhost` — например, пользовательского домена, удалённого IP или туннелированного URL — вы можете увидеть предупреждение вроде: @@ -127,7 +126,7 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ⚠ 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 @@ -146,5 +145,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/ru/examples.mdx b/docs/ru/examples.mdx index 034f4f9c..104ab782 100644 --- a/docs/ru/examples.mdx +++ b/docs/ru/examples.mdx @@ -1,16 +1,16 @@ --- title: Примеры -description: "Как настроить перехватчики для Claude Code и Agents SDK" +description: "Как настроить хуки для Claude Code и Agents SDK" icon: book-open --- -Готовые к использованию примеры для распространённых сценариев. Каждый показывает, как установить и чего ожидать. +Готовые к использованию примеры для типичных сценариев. Каждый показывает, как установить и чего ожидать. --- -## Настройка перехватчиков для Claude Code +## Настройка хуков для Claude Code -Failproof AI интегрируется с Claude Code через его [систему перехватчиков](https://docs.anthropic.com/en/docs/claude-code/hooks). Когда вы запускаете `failproofai policies --install`, он регистрирует команды перехватчиков в файле `settings.json` Claude Code, которые срабатывают при каждом вызове инструмента. +Failproof AI интегрируется с Claude Code через его [систему хуков](https://docs.anthropic.com/en/docs/claude-code/hooks). Когда вы запускаете `failproofai policies --install`, он регистрирует команды хуков в `settings.json` Claude Code, которые срабатывают при каждом вызове инструмента. @@ -23,27 +23,27 @@ Failproof AI интегрируется с Claude Code через его [сис failproofai policies --install ``` - + ```bash cat ~/.claude/settings.json | grep failproofai ``` - Вы должны увидеть записи перехватчиков для событий `PreToolUse`, `PostToolUse`, `Notification` и `Stop`. + Вы должны увидеть записи хуков для событий `PreToolUse`, `PostToolUse`, `Notification` и `Stop`. ```bash claude ``` - Политики теперь запускаются автоматически при каждом вызове инструмента. Попробуйте попросить Claude выполнить `sudo rm -rf /` — это будет заблокировано. + Политики теперь работают автоматически при каждом вызове инструмента. Попробуйте попросить Claude запустить `sudo rm -rf /` — это будет заблокировано. --- -## Настройка перехватчиков для Agents SDK +## Настройка хуков для Agents SDK -Если вы разрабатываете с помощью [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), вы можете использовать ту же систему перехватчиков программно. +Если вы разрабатываете с помощью [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), вы можете использовать ту же систему хуков программным способом. @@ -51,8 +51,8 @@ Failproof AI интегрируется с Claude Code через его [сис npm install failproofai ``` - - Передайте команды перехватчиков при создании процесса агента. Перехватчики срабатывают так же, как в Claude Code — через JSON в stdin/stdout: + + Передайте команды хуков при создании процесса агента. Хуки срабатывают так же, как в Claude Code — через stdin/stdout JSON: ```bash failproofai --hook PreToolUse # вызывается перед каждым инструментом @@ -65,12 +65,12 @@ Failproof AI интегрируется с Claude Code через его [сис customPolicies.add({ name: "limit-to-project-dir", - description: "Keep the agent inside the project directory", + description: "Держите агента внутри директории проекта", match: { events: ["PreToolUse"] }, fn: async (ctx) => { const path = String(ctx.toolInput?.file_path ?? ""); if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) { - return deny("Agent is restricted to the project directory"); + return deny("Агент ограничен директорией проекта"); } return allow(); }, @@ -86,9 +86,9 @@ Failproof AI интегрируется с Claude Code через его [сис --- -## Блокировка деструктивных команд +## Блокируйте деструктивные команды -Самая распространённая настройка — предотвращение необратимого ущерба от агентов. +Самая распространённая настройка — предотвратить агентам наносить необратимый ущерб. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh @@ -102,34 +102,34 @@ failproofai policies --install block-sudo block-rm-rf block-force-push block-cur --- -## Предотвращение утечки секретов +## Предотвратите утечку секретов -Помешайте агентам видеть или утечекать учётные данные в выводе инструментов. +Остановите агентов от просмотра или утечки учётных данных в выводе инструмента. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -Они срабатывают на `PostToolUse` — после выполнения инструмента они очищают вывод перед тем, как агент его увидит. +Они срабатывают на `PostToolUse` — после выполнения инструмента они очищают вывод до того, как агент его увидит. --- -## Получайте оповещения Slack, когда агентам нужно внимание +## Получайте оповещения в Slack, когда агентам нужно внимание -Используйте перехватчик уведомлений для отправки оповещений о ожидании в Slack. +Используйте хук уведомления для отправки оповещений о простое в Slack. ```javascript import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "slack-on-idle", - description: "Alert Slack when the agent is waiting for input", + description: "Оповестить Slack, когда агент ждёт ввода", match: { events: ["Notification"] }, fn: async (ctx) => { const webhookUrl = process.env.SLACK_WEBHOOK_URL; if (!webhookUrl) return allow(); - const message = String(ctx.payload?.message ?? "Agent is waiting"); + const message = String(ctx.payload?.message ?? "Агент ожидает"); const project = ctx.session?.cwd ?? "unknown"; try { @@ -142,7 +142,7 @@ customPolicies.add({ signal: AbortSignal.timeout(5000), }); } catch { - // never block the agent if Slack is unreachable + // никогда не блокируйте агента, если Slack недоступен } return allow(); @@ -150,7 +150,7 @@ customPolicies.add({ }); ``` -Установите её: +Установите это: ```bash SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js @@ -167,13 +167,13 @@ import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "stay-on-branch", - description: "Prevent the agent from checking out other branches", + description: "Предотвратить переключение агента на другие ветви", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); if (/git\s+checkout\s+(?!-b)/.test(cmd)) { - return deny("Stay on the current branch. Create a new branch with -b if needed."); + return deny("Оставайтесь на текущей ветви. Создайте новую ветвь с флагом -b при необходимости."); } return allow(); }, @@ -191,13 +191,13 @@ import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "test-before-commit", - description: "Remind the agent to run tests before committing", + description: "Напомнить агенту запустить тесты перед коммитом", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); if (/git\s+commit/.test(cmd)) { - return instruct("Run tests before committing. Use `npm test` or `bun test` first."); + return instruct("Запустите тесты перед коммитом. Сначала используйте `npm test` или `bun test`."); } return allow(); }, @@ -206,9 +206,9 @@ customPolicies.add({ --- -## Заблокируйте рабочий репозиторий +## Заблокируйте production репозиторий -Зафиксируйте конфигурацию на уровне проекта, чтобы все разработчики в вашей команде получили одинаковые политики. +Зафиксируйте конфиг на уровне проекта, чтобы все разработчики в вашей команде получили одинаковые политики. Создайте `.failproofai/policies-config.json` в вашем репозитории: @@ -231,7 +231,7 @@ customPolicies.add({ } ``` -Затем зафиксируйте её: +Затем зафиксируйте это: ```bash git add .failproofai/policies-config.json @@ -242,9 +242,9 @@ git commit -m "Add failproofai team policies" --- -## Создайте организационный стандарт качества с политиками соглашений +## Создайте стандарт качества на уровне организации с политиками соглашений -Самая эффективная настройка: зафиксируйте `.failproofai/policies/` в вашем репозитории с политиками, адаптированными к вашему проекту. Все члены команды получат их автоматически — никаких команд установки, никаких изменений конфигурации. +Наиболее эффективная настройка: зафиксируйте `.failproofai/policies/` в вашем репозитории с политиками, адаптированными к вашему проекту. Каждый член команды получит их автоматически — без команд установки, без изменения конфига. @@ -256,27 +256,27 @@ git commit -m "Add failproofai team policies" // .failproofai/policies/team-policies.mjs import { customPolicies, allow, deny, instruct } from "failproofai"; - // Enforce your team's preferred package manager - // (or enable the built-in prefer-package-manager policy instead) + // Обеспечьте использование предпочтительного менеджера пакетов вашей команды + // (или вместо этого включите встроенную политику prefer-package-manager) customPolicies.add({ name: "enforce-bun", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); - if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm."); + if (/\bnpm\b/.test(cmd)) return deny("Используйте bun вместо npm."); return allow(); }, }); - // Remind the agent to run tests before committing + // Напомните агенту запустить тесты перед коммитом customPolicies.add({ name: "test-before-commit", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) { - return instruct("Run tests before committing."); + return instruct("Запустите тесты перед коммитом."); } return allow(); }, @@ -289,19 +289,19 @@ git commit -m "Add failproofai team policies" git commit -m "Add team quality policies" ``` - - По мере того как ваша команда сталкивается с новыми типами отказов, добавляйте политики и отправляйте их. Все получат обновление при следующем `git pull`. Эти политики становятся живым стандартом качества, который растёт вместе с вашей командой. + + Когда ваша команда столкнётся с новыми режимами сбоя, добавляйте политики и отправляйте. Все получат обновление при следующем `git pull`. Эти политики становятся живым стандартом качества, который растёт вместе с вашей командой. --- -## Больше примеров +## Ещё примеры Директория [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) в репозитории содержит: -| Файл | Что он демонстрирует | +| Файл | Что он показывает | |------|---------------| -| `policies-basic.js` | Базовые политики — блокировка записи в production, force-push, передача скриптов в оболочку | -| `policies-notification.js` | Оповещения Slack для уведомлений о ожидании и окончании сеанса | -| `policies-advanced/index.js` | Транзитивные импорты, асинхронные перехватчики, очистка вывода PostToolUse, обработка события Stop | \ No newline at end of file +| `policies-basic.js` | Стартовые политики — блокируйте запись в production, force-push, передачу скриптов в оболочку | +| `policies-notification.js` | Оповещения Slack для уведомлений о простое и завершении сессии | +| `policies-advanced/index.js` | Транзитивные импорты, асинхронные хуки, очистка вывода PostToolUse, обработка события Stop | \ No newline at end of file diff --git a/docs/ru/for-agents.mdx b/docs/ru/for-agents.mdx index d7eebbcb..3c6cf828 100644 --- a/docs/ru/for-agents.mdx +++ b/docs/ru/for-agents.mdx @@ -1,33 +1,33 @@ --- title: "Для агентов" -description: "Добавьте всю базу знаний Failproof AI в свой кодирующий агент одной командой. Работает с Claude Code, Cursor, Windsurf и другими." +description: "Добавьте справочник Failproof AI в своего кодирующего агента одной командой. Работает с Claude Code, Cursor, Windsurf и другими." --- -Добавьте полный справочник Failproof AI в свой кодирующий агент одной командой. Работает с Claude Code, Cursor, Windsurf и любым другим агентом, поддерживающим навыки. +Добавьте полный справочник Failproof AI в своего кодирующего агента одной командой. Работает с Claude Code, Cursor, Windsurf и любым другим агентом, который поддерживает навыки. ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` автоматически определяет установленные агенты и добавляет навык в правильном формате для каждого. +`npx skills` автоматически определяет установленные у вас агенты и добавляет навык в нужном формате для каждого из них. -## Что включает навык +## Что входит в навык | Область | Содержимое | |---------|-----------| | Политики | Встроенные имена политик, типы событий, параметры, включение/отключение | -| Пользовательские политики | `customPolicies.add()`, фильтры соответствия, API `allow`/`deny`/`instruct` | +| Пользовательские политики | `customPolicies.add()`, фильтры совпадения, API `allow`/`deny`/`instruct` | | Объект контекста | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | -| Конфигурация | Структура `policies-config.json`, слияние областей видимости, `policyParams` | -| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, области видимости | -| Панель управления | Просмотр сессий, активность политик, переменные окружения | -| Архитектура | Поток обработчика хука, коды выхода, контракт stdin/stdout | +| Конфигурация | Структура `policies-config.json`, слияние областей, `policyParams` | +| CLI | `failproofai policies --install`, `--uninstall`, `--custom`, области действия | +| Панель управления | Просмотр сеанса, активность политик, переменные окружения | +| Архитектура | Поток обработчика hook'ов, коды выхода, контракт stdin/stdout | ## Полон ли навык? -Mintlify генерирует `llms.txt` из всех страниц в навигации. Документация Failproof AI охватывает полный API — каждая политика, опция и пример включены. Если вы найдёте что-то недостающее, источник находится на `https://docs.befailproof.ai/llms-full.txt`. +Mintlify генерирует `llms.txt` из всех страниц навигации. Документация Failproof AI охватывает полный API — каждая политика, опция и пример включены. Если вы обнаружите что-то пропущенное, источник находится в `https://docs.befailproof.ai/llms-full.txt`. -Для целевого контекста давайте прямую ссылку на конкретную страницу: +Для целевого контекста ссылайтесь прямо на конкретную страницу: ```bash # Только API пользовательских политик diff --git a/docs/ru/getting-started.mdx b/docs/ru/getting-started.mdx index b9f2a286..26e9d490 100644 --- a/docs/ru/getting-started.mdx +++ b/docs/ru/getting-started.mdx @@ -1,6 +1,6 @@ --- -title: Начало работы -description: "Установите failproofai, включите политики и позвольте вашим агентам работать надежно" +title: Быстрый старт +description: "Установите failproofai, включите политики и дайте своим агентам работать надёжно" icon: rocket --- @@ -31,15 +31,15 @@ bun add -g failproofai - Политики — это правила, которые выполняются до и после каждого вызова инструмента агента. Они перехватывают деструктивные команды, утечки секретов и другие сбои перед тем, как они причинят вред. + Политики — это правила, которые выполняются перед и после каждого вызова инструмента агентом. Они перехватывают деструктивные команды, утечки секретов и другие сбои до того, как они нанесут ущерб. ```bash failproofai policies --install ``` - Это добавляет записи крючков в установленные CLI агентов (Claude Code в `~/.claude/settings.json`, OpenAI Codex в `~/.codex/hooks.json`, GitHub Copilot CLI в `~/.copilot/hooks/failproofai.json`, Cursor Agent в `~/.cursor/hooks.json`, OpenCode с создаваемой заглушкой плагина в `~/.config/opencode/plugins/failproofai.mjs` плюс запись регистрации в массиве `plugin` файла `~/.config/opencode/opencode.json`, Pi в `~/.pi/agent/settings.json` или Gemini CLI в `~/.gemini/settings.json`). Если присутствует более одного варианта, вам будет предложено выбрать; передайте `--cli claude codex copilot cursor opencode pi gemini` (любое подмножество), чтобы пропустить запрос. + Эта команда записывает записи хуков в установленные CLI агентов (Claude Code's `~/.claude/settings.json`, OpenAI Codex's `~/.codex/hooks.json`, GitHub Copilot CLI's `~/.copilot/hooks/failproofai.json`, Cursor Agent's `~/.cursor/hooks.json`, OpenCode's generated plugin shim at `~/.config/opencode/plugins/failproofai.mjs` plus a registration entry in `~/.config/opencode/opencode.json`'s `plugin` array, Pi's `~/.pi/agent/settings.json`, Gemini CLI's `~/.gemini/settings.json`, или Hermes's `~/.hermes/config.yaml`). Если присутствует несколько, вам будет предложено выбрать; передайте `--cli claude codex copilot cursor opencode pi gemini hermes` (любое подмножество), чтобы пропустить запрос. - Поддержка GitHub Copilot CLI, Cursor Agent, OpenCode, Pi и Gemini CLI находится в статусе **beta** — устанавливайте с `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi` или `--cli gemini`. + GitHub Copilot CLI, Cursor Agent, OpenCode, Pi и Gemini CLI поддерживаются в режиме **бета** — установите с помощью `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi` или `--cli gemini`. Hermes (hermes-agent, шлюз Slack/Telegram) устанавливается в область пользователя с помощью `--cli hermes` и также является источником автономного аудита. ```bash failproofai policies --install --scope project @@ -49,25 +49,26 @@ bun add -g failproofai failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project + failproofai policies --install --cli hermes --scope user failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` - + ```bash failproofai policies ``` - Показывает все политики, включены ли они и любые настроенные параметры. + Показывает все политики, включены ли они и все настроенные параметры. ```bash failproofai ``` - Открывает локальную панель управления на `http://localhost:8020`, где вы можете просматривать сессии, проверять вызовы инструментов и управлять политиками. + Открывает локальную панель управления на `http://localhost:8020`, где вы можете просматривать сессии, инспектировать вызовы инструментов и управлять политиками. - - Запустите Claude Code обычным образом. Если агент попытается что-то рискованное, failproofai автоматически это перехватит. Оставьте его работать без присмотра и проверьте, что произошло, в панели управления. + + Запустите Claude Code как обычно. Если агент попытается что-то рискованное, failproofai автоматически это перехватит. Оставьте его работать без присмотра и просмотрите результаты на панели управления. @@ -83,30 +84,30 @@ Claude Code → failproofai --hook PreToolUse → читает JSON из std записывает решение в stdout ``` -Каждая политика возвращает одно из трех решений: +Каждая политика возвращает одно из трёх решений: -- **allow** — агент продолжает работу нормально -- **deny** — действие заблокировано, агенту объясняется почему -- **instruct** — дополнительный контекст добавляется в подсказку агента +- **allow** — агент работает нормально +- **deny** — действие блокируется, агенту сообщается причина +- **instruct** — в запрос агента добавляется дополнительный контекст -Политики выполняются в вашем локальном процессе. Ничего не отправляется на удаленный сервис. +Политики выполняются в вашем локальном процессе. Ничего не отправляется на удалённый сервис. --- -## Установите командные политики с использованием политик на основе соглашений +## Установите командные политики с использованием соглашения о политиках -Быстрейший способ установить стандарты качества во всей команде — это соглашение `.failproofai/policies/`. Поместите файлы политик в этот каталог, и они загружаются автоматически — без флагов, без изменения конфигурации, без команд установки. +Самый быстрый способ установить стандарты качества в вашей команде — это соглашение `.failproofai/policies/`. Просто добавьте файлы политик в эту директорию, и они будут загружены автоматически — без флагов, без изменения конфигурации, без команд установки. - + ```bash mkdir -p .failproofai/policies ``` - Скопируйте примеры для начинающих или напишите свои собственные: + Скопируйте примеры-шаблоны или напишите свои собственные: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -137,26 +138,26 @@ Claude Code → failproofai --hook PreToolUse → читает JSON из std git commit -m "Add team quality policies" ``` - Каждый член команды, у которого установлен failproofai, автоматически получает эти политики. Не требуется отдельная настройка для каждого разработчика. + Каждый член команды, у которого установлен failproofai, автоматически получит эти политики. Не требуется настройка для каждого разработчика. -Зафиксируйте `.failproofai/policies/` в репозитории, чтобы вся команда придерживалась одних и тех же стандартов. По мере того, как ваша команда обнаруживает новые способы сбоев, добавляйте политики и отправляйте их — каждый получит обновление при следующем `git pull`. Со временем эти политики становятся живым стандартом качества, который постоянно улучшается. +Зафиксируйте `.failproofai/policies/` в вашем репозитории, чтобы вся команда следовала одним и тем же стандартам. По мере того, как ваша команда обнаруживает новые способы сбоев, добавляйте политики и публикуйте их — все получат обновление при следующем `git pull`. Со временем эти политики становятся живым стандартом качества, который постоянно улучшается. --- ## Хранение данных -Все конфигурации и журналы остаются на вашей машине: +Вся конфигурация и логи остаются на вашем компьютере: -| Путь | Что хранится | -|------|----------------| +| Путь | Что здесь хранится | +|------|---| | `~/.failproofai/policies-config.json` | Глобальная конфигурация политик | -| `~/.failproofai/hook-activity.jsonl` | История выполнения крючков | -| `~/.failproofai/hook.log` | Журнал отладки для ошибок пользовательских крючков | -| `.failproofai/policies-config.json` | Конфигурация для проекта (зафиксирована) | +| `~/.failproofai/hook-activity.jsonl` | История выполнения хуков | +| `~/.failproofai/hook.log` | Лог отладки для ошибок пользовательских хуков | +| `.failproofai/policies-config.json` | Конфигурация для конкретного проекта (зафиксирована в git) | | `.failproofai/policies-config.local.json` | Личные переопределения (в .gitignore) | --- @@ -167,7 +168,7 @@ Claude Code → failproofai --hook PreToolUse → читает JSON из std failproofai policies --uninstall ``` -Удаляет записи крючков из `~/.claude/settings.json`. Файлы конфигурации в `~/.failproofai/` сохраняются. +Удаляет записи хуков из `~/.claude/settings.json`. Файлы конфигурации в `~/.failproofai/` сохраняются. --- @@ -176,7 +177,7 @@ failproofai policies --uninstall - Области и формат файла конфигурации + Области действия и формат файла конфигурации @@ -184,11 +185,11 @@ failproofai policies --uninstall - Напишите свои собственные политики на JavaScript + Напишите свои политики на JavaScript - Мониторьте сессии и проверьте активность политик + Мониторьте сессии и проверяйте активность политик \ No newline at end of file diff --git a/docs/ru/introduction.mdx b/docs/ru/introduction.mdx index c95320eb..4996d294 100644 --- a/docs/ru/introduction.mdx +++ b/docs/ru/introduction.mdx @@ -1,36 +1,36 @@ --- title: "Failproof AI" -description: "FailproofAI предоставляет AI-агентам 39 встроенных политик обработки ошибок, которые ловят циклы, утечки секретов, деструктивные вызовы инструментов и многое другое с одной установкой." +description: "FailproofAI предоставляет AI агентам 39 встроенных политик защиты, которые выявляют циклы, утечки секретов, деструктивные вызовы инструментов и многое другое в единой установке." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -Хуки и политики для **обработки ошибок AI**, **восстановления после сбоев** и **надежности LLM**. Делайте ваших AI-агентов надежными и работающими автономно в **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI** и **Agents SDK**. +Хуки и политики для **обработки сбоев AI**, **восстановления после ошибок** и **надёжности LLM**. Держите ваших AI агентов надёжными и работающими автономно на **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, **Hermes** и **Agents SDK**. -AI-агенты отказывают предсказуемым образом. Они запускают деструктивные команды, пропускают секреты, отклоняются от задач, застревают в циклах или отправляют изменения прямо в основную ветку. Без присмотра небольшие сбои превращаются в отключения сервиса, утечки учетных данных и потерю работы. +AI агенты падают предсказуемым образом. Они выполняют деструктивные команды, утекают секреты, отходят от задачи, застревают в циклах или пушат прямо в main. Без надзора, небольшие сбои каскадируют в отказы, утечки учётных данных и потерю работы. -FailproofAI решает эту проблему с помощью **политик**. Эти правила интегрируются в каждый вызов инструмента агента, чтобы **обнаруживать сбои**, **смягчать их** (блокировать, инструктировать, санитизировать) и **оповещать вас**, когда что-то требует внимания. Локальная панель управления позволяет просмотреть каждый вызов инструмента, сбой агента и действие по восстановлению впоследствии. +FailproofAI решает эту проблему с помощью **политик**. Эти правила перехватывают каждый вызов инструмента агента, чтобы **обнаружить сбои**, **смягчить их** (блокировать, инструктировать, санитизировать) и **оповестить вас**, когда требуется внимание. Локальная панель позволяет вам просмотреть каждый вызов инструмента, сбой агента и действие восстановления впоследствии. Никакие данные не покидают вашу машину. -## Начало работы +## Начните с этого - Блокируйте деструктивные команды, предотвращайте утечки секретов, держите агентов в границах проекта и многое другое. Все из коробки. + Блокируйте деструктивные команды, предотвращайте утечки секретов, держите агентов внутри границ проекта и многое другое. Всё готово к использованию. - Напишите собственные правила на JavaScript с простым API allow / deny / instruct. + Напишите свои правила на JavaScript с простым API allow / deny / instruct. - Посмотрите, что делали ваши агенты, пока вас не было. Обзор сеансов, проверка вызовов инструментов, просмотр срабатываний политик. + Смотрите, что делали ваши агенты, пока вас не было. Просматривайте сессии, проверяйте вызовы инструментов, смотрите, где срабатывали политики. - - Настраивайте любую политику без кода. Устанавливайте списки разрешенного, защищенные ветки или пороги для каждого проекта или глобально. + + Настраивайте любую политику без кода. Устанавливайте разрешённые списки, защищённые ветки или пороги для каждого проекта или глобально. @@ -50,8 +50,8 @@ bun add -g failproofai ```bash -failproofai policies --install # включить политики (или пропустить — `failproofai` предложит настроить их при первом запуске) -failproofai # запустить панель управления +failproofai policies --install # включить политики (или пропустить — `failproofai` предложит установить их при первом запуске) +failproofai # запустить панель ``` -Смотрите руководство [Начало работы](/ru/getting-started) для полного описания. \ No newline at end of file +Смотрите руководство [Начало работы](/ru/getting-started) для полного пошагового описания. \ No newline at end of file diff --git a/docs/ru/package-aliases.mdx b/docs/ru/package-aliases.mdx index bdad3af1..419f45ec 100644 --- a/docs/ru/package-aliases.mdx +++ b/docs/ru/package-aliases.mdx @@ -1,12 +1,12 @@ --- -title: Alias пакетов -description: "Зарегистрированные alias-ы для предотвращения опечаток и их работа" +title: Алиасы пакетов +description: "Зарегистрированные алиасы для предотвращения опечаток и принцип их работы" icon: copy --- ## Официальный пакет -Канонический npm пакет — **`failproofai`**: +Канонический пакет npm — это **`failproofai`**: ```bash npm install -g failproofai @@ -16,17 +16,17 @@ bun add -g failproofai --- -## Почему мы владеем альтернативными именами +## Почему мы владеем этими алиасами -Typosquatting — это распространённая атака на цепочку поставок, при которой злоумышленник регистрирует имя пакета, которое отличается на одно нажатие клавиши от популярного пакета. Невнимательные пользователи, которые опечатаются при вводе команды установки, запускают контролируемый злоумышленником код с полным доступом к системе — именно такую угрозу Failproof AI предназначен предотвращать. +Typosquatting — распространённая атака на цепь поставок, при которой злоумышленник регистрирует имя пакета, отличающееся на один символ от популярного пакета. Пользователи, случайно ошибившиеся при вводе команды установки, запускают контролируемый злоумышленником код с полным доступом к системе — это именно тот вид угроз, от которых Failproof AI призван защищать. -Чтобы исключить эту уязвимость, **мы упредительно владеем всеми распространёнными опечатками и вариантами форматирования** названия `failproofai` на npm. Ни одно из этих имён не может быть зарегистрировано третьей стороной. Каждое из них — это тонкий proxy, который устанавливает и делегирует работу реальному пакету `failproofai`. +Чтобы устранить эту уязвимость, **мы заранее регистрируем все распространённые опечатки и варианты написания** `failproofai` на npm. Никто из третьих лиц не может зарегистрировать эти имена. Каждое из них — это тонкий прокси, который устанавливает и делегирует выполнение реальному пакету `failproofai`. --- -## Зарегистрированные alias-ы +## Зарегистрированные алиасы -**Варианты форматирования** — разные способы написания «failproof ai»: +**Варианты написания** — разные способы написать "failproof ai": | Пакет | Статус | |---------|--------| @@ -37,7 +37,7 @@ Typosquatting — это распространённая атака на цеп | `fail_proof_ai` | ⏳ Ожидание поддержки npm | | `fail-proofai` | ⏳ Ожидание поддержки npm | -**Опечатки `failprof*`** — пропущена одна буква `o` в слове «proof»: +**Опечатки `failprof*`** — пропущена одна буква `o` в слове "proof": | Пакет | Статус | |---------|--------| @@ -47,7 +47,7 @@ Typosquatting — это распространённая атака на цеп | `fail-prof-ai` | ⏳ Ожидание поддержки npm | | `failprof_ai` | ⏳ Ожидание поддержки npm | -**Опечатки `faliproof*`** — перестановка букв `a` и `i`: +**Опечатки `faliproof*`** — буквы `a` и `i` переставлены местами: | Пакет | Статус | |---------|--------| @@ -55,28 +55,28 @@ Typosquatting — это распространённая атака на цеп | `faliproof-ai` | ✅ Опубликован | | `faliproofai` | ⏳ Ожидание поддержки npm | -> **Почему ожидание?** Политика npm по борьбе со спамом блокирует имена, которые нормализуются в то же самое имя, что и существующий пакет, после удаления пунктуации и проверки схожести. Мы связались с поддержкой npm, чтобы зарезервировать эти имена в целях противодействия typosquatting-у. Они будут активированы после одобрения. +> **Почему статус ожидания?** Политика npm по предотвращению спама блокирует имена, которые нормализуются в ту же строку, что и существующий пакет, после удаления пунктуации и проверки на сходство. Мы связались с поддержкой npm, чтобы зарезервировать эти имена в целях защиты от typosquatting. Они будут активированы после одобрения. -Вы можете проверить, что любой опубликованный alias принадлежит нам: +Вы можете проверить, что любой опубликованный алиас принадлежит нам: ```bash npm info failproof -# Ищите: "ExosphereHost Inc." в поле maintainers +# Найдите "ExosphereHost Inc." в поле maintainers ``` --- -## Как работают alias-ы +## Как работают алиасы -Каждый alias пакет: +Каждый пакет-алиас: -1. Указывает `failproofai` как зависимость — таким образом, реальный пакет (включая его hook `postinstall`) запускается при установке -2. Предоставляет бинарный файл с именем, совпадающим с его собственным (например `failprof-ai`), который проксирует все аргументы в бинарный файл `failproofai` +1. Указывает `failproofai` как зависимость — поэтому реальный пакет (включая его `postinstall` хук) запускается при установке +2. Предоставляет бинарный файл, соответствующий собственному имени (например, `failprof-ai`), который проксирует все аргументы в бинарный файл `failproofai` -Proxy — это двухстрочный Node скрипт; в нём нет логики, сетевых вызовов и сбора данных, выходящих за рамки того, что делает сам `failproofai`. +Прокси — это двухстрочный скрипт Node; здесь нет никакой логики, сетевых запросов и сбора данных, выходящих за рамки того, что делает сам `failproofai`. --- -## Если вы обнаружили пропущенное имя +## Если мы пропустили какое-то имя -Откройте issue на [failproofai/failproofai](https://github.com/failproofai/failproofai/issues), и мы зарегистрируем его. \ No newline at end of file +Откройте issue на [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) и мы его зарегистрируем. \ No newline at end of file diff --git a/docs/ru/testing.mdx b/docs/ru/testing.mdx index f3221112..22292588 100644 --- a/docs/ru/testing.mdx +++ b/docs/ru/testing.mdx @@ -1,11 +1,10 @@ --- ---- title: Тестирование -description: "Модульные тесты, сквозные тесты и вспомогательные инструменты тестирования" +description: "Модульные тесты, E2E тесты и вспомогательные инструменты для тестирования" icon: flask-vial --- -failproofai содержит два набора тестов: **модульные тесты** (быстрые, с мокированием) и **сквозные тесты** (реальные вызовы подпроцесса). +failproofai имеет два набора тестов: **модульные тесты** (быстрые, с моками) и **end-to-end тесты** (реальные вызовы подпроцессов). --- @@ -18,7 +17,7 @@ bun run test:run # Запустить модульные тесты в режиме наблюдения bun run test -# Запустить E2E тесты (требует настройки - см. ниже) +# Запустить E2E тесты (требует предварительной настройки - см. ниже) bun run test:e2e # Проверка типов без сборки @@ -38,13 +37,13 @@ bun run lint __tests__/ hooks/ builtin-policies.test.ts # Логика политик для каждой встроенной - hooks-config.test.ts # Загрузка конфига и слияние областей видимости + hooks-config.test.ts # Загрузка конфига и слияние областей policy-evaluator.test.ts # Инъекция параметров и порядок оценки - custom-hooks-registry.test.ts # Добавление/получение/очистка реестра globalThis - custom-hooks-loader.test.ts # ESM загрузчик, переходные импорты, обработка ошибок - manager.test.ts # Операции установки/удаления/списания + custom-hooks-registry.test.ts # globalThis реестр добавления/получения/очистки + custom-hooks-loader.test.ts # ESM загрузчик, транзитивные импорты, обработка ошибок + manager.test.ts # операции install/remove/list components/ - sessions-list.test.tsx # Компонент списка сеансов + sessions-list.test.tsx # Компонент списка сессий project-list.test.tsx # Компонент списка проектов ... lib/ @@ -109,13 +108,13 @@ describe("block-sudo", () => { --- -## Сквозные тесты +## End-to-end тесты -Сквозные тесты вызывают реальный бинарный файл `failproofai` как подпроцесс, передают JSON-полезную нагрузку в stdin и проверяют выходные данные stdout и код выхода. Это тестирует полный путь интеграции, который использует Claude Code. +E2E тесты вызывают реальный бинарный файл `failproofai` как подпроцесс, передают JSON-полезную нагрузку в stdin и проверяют выходные данные stdout и код выхода. Это тестирует полный путь интеграции, который использует Claude Code. ### Настройка -Сквозные тесты запускают бинарный файл прямо из исходного кода репозитория. Перед первым запуском соберите CJS-пакет, который файлы пользовательских хуков используют при импорте из `'failproofai'`: +E2E тесты запускают бинарный файл непосредственно из исходного кода репозитория. Перед первым запуском соберите CJS пакет, который используют файлы пользовательских хуков при импорте из `'failproofai'`: ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -127,33 +126,33 @@ bun build src/index.ts --outdir dist --target node --format cjs bun run test:e2e ``` -Пересоберите `dist/` всякий раз, когда вы изменяете публичный API хука (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` или `src/hooks/policy-types.ts`). +Пересобирайте `dist/` всякий раз, когда вы изменяете публичный API хука (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` или `src/hooks/policy-types.ts`). -### Структура сквозного теста +### Структура E2E теста ```text __tests__/e2e/ helpers/ - hook-runner.ts # Запуск бинарного файла, передача JSON-полезной нагрузки, перехват кода выхода + stdout + stderr - fixture-env.ts # Изолированные для каждого теста временные директории с файлами конфигурации - payloads.ts # Заводы полезных нагрузок, точные для Claude, для каждого типа события + hook-runner.ts # Запуск бинарного файла, передача JSON-полезной нагрузки, захват кода выхода + stdout + stderr + fixture-env.ts # Изолированные для каждого теста временные директории с файлами конфига + payloads.ts # Фабрики полезных нагрузок, соответствующие Claude, для каждого типа события hooks/ builtin-policies.e2e.test.ts # Каждая встроенная политика с реальным подпроцессом custom-hooks.e2e.test.ts # Загрузка и оценка пользовательских хуков - config-scopes.e2e.test.ts # Слияние конфигов между проектом/локальным/глобальным + config-scopes.e2e.test.ts # Слияние конфига между project/local/global policy-params.e2e.test.ts # Инъекция параметров для каждой параметризованной политики ``` -### Использование вспомогательных инструментов E2E +### Использование E2E помощников -**`FixtureEnv`** - изолированная среда для каждого теста: +**`FixtureEnv`** - изолированная для каждого теста среда: ```typescript import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - временная директория; передайте как payload.cwd чтобы подхватить .failproofai/policies-config.json -// env.home - изолированная домашняя директория; никаких утечек реального ~/.failproofai +// env.cwd - временная директория; передайте как payload.cwd для загрузки .failproofai/policies-config.json +// env.home - изолированная домашняя директория; в тестах не подгружается реальная ~/.failproofai env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -165,7 +164,7 @@ env.writeConfig({ `createFixtureEnv()` автоматически регистрирует очистку `afterEach`. -**`runHook`** - вызвать бинарный файл: +**`runHook`** - вызов бинарного файла: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -181,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - готовые заводы полезных нагрузок: +**`Payloads`** - готовые фабрики полезных нагрузок: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -193,7 +192,7 @@ Payloads.notification(message, cwd) Payloads.stop(cwd) ``` -### Написание сквозного теста +### Написание E2E теста ```typescript import { describe, it, expect } from "vitest"; @@ -227,35 +226,35 @@ describe("block-rm-rf (E2E)", () => { ); expect(result.exitCode).toBe(0); - expect(result.stdout).toBe(""); // allow → empty stdout + expect(result.stdout).toBe(""); // allow → пустой stdout }); }); ``` -### Форматы ответов E2E +### Формы E2E ответов | Решение | Код выхода | stdout | |----------|-----------|--------| | `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | | Instruct (не-Stop) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop instruct | `2` | пусто stdout; причина в stderr | +| Stop instruct | `2` | пустой stdout; причина в stderr | | Allow | `0` | пустая строка | -### Конфигурация Vitest +### Конфиг Vitest -Сквозные тесты используют `vitest.config.e2e.mts` с: +E2E тесты используют `vitest.config.e2e.mts` с: -- `environment: "node"` - браузерные глобальные переменные не требуются +- `environment: "node"` - глобальные переменные браузера не требуются - `pool: "forks"` - истинная изоляция процессов (тесты запускают подпроцессы) - `testTimeout: 20_000` - 20s на тест (запуск бинарного файла + оценка хука) -Пул `forks` важен: рабочие процессы на основе потоков делят `globalThis`, что может мешать тестам, запускающим подпроцессы. Форки на основе процессов избегают этого. +Пул `forks` важен: рабочие процессы на основе потоков совместно используют `globalThis`, что может помешать тестам, запускающим подпроцессы. Изолированные процессы этого избегают. --- ## CI -Полный запуск CI (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) должен пройти успешно перед объединением. Набор E2E тестов работает как отдельная задача CI параллельно. +Полный CI запуск (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) должен пройти перед слиянием. E2E набор выполняется как отдельное задание CI параллельно. -См. [Contributing](../CONTRIBUTING.md) для полного списка проверок перед объединением. \ No newline at end of file +См. [Contributing](../CONTRIBUTING.md) для полного предварительного списка проверок перед слиянием. \ No newline at end of file diff --git a/docs/tr/architecture.mdx b/docs/tr/architecture.mdx index f77bc2f5..74b5a388 100644 --- a/docs/tr/architecture.mdx +++ b/docs/tr/architecture.mdx @@ -1,12 +1,11 @@ --- - --- title: Mimari -description: "Hook işleyicisinin, config yüklemesinin ve politika değerlendirmesinin dahili olarak nasıl çalıştığı" +description: "Hook handler, config loading ve policy evaluation'ın dahili olarak nasıl çalıştığı" icon: sitemap --- -Bu belge failproofai'nin dahili olarak nasıl çalıştığını açıklar: hook sistemi aracı araç çağrılarını nasıl yakalar, yapılandırma nasıl yüklenir ve birleştirilir, politikalar nasıl değerlendirilir ve kontrol paneli aracı etkinliğini nasıl izler. +Bu belgede failproofai'nin dahili olarak nasıl çalıştığı açıklanmaktadır: hook sistemi agent tool çağrılarını nasıl kesiştirir, konfigürasyon nasıl yüklenir ve birleştirilir, politikalar nasıl değerlendirilir ve dashboard agent aktivitesini nasıl izler. --- @@ -14,14 +13,14 @@ Bu belge failproofai'nin dahili olarak nasıl çalıştığını açıklar: hook failproofai iki bağımsız alt sisteme sahiptir: -1. **Hook işleyicisi** - Claude Code'un her aracı araç çağrısında çağırdığı hızlı bir CLI alt süreci. Politikaları değerlendirir ve bir karar döndürür. -2. **Aracı İzleyicisi (Kontrol Paneli)** - Aracı oturumlarını izlemek ve politikaları yönetmek için Next.js web uygulaması. +1. **Hook handler** - Claude Code'un her agent tool çağrısında çağırdığı hızlı bir CLI alt işlemi. Politikaları değerlendirir ve bir karar döndürür. +2. **Agent Monitor (Dashboard)** - Agent oturumlarını izlemek ve politikaları yönetmek için bir Next.js web uygulaması. -Her iki alt sistem `~/.failproofai/` ve projenin `.failproofai/` dizinindeki yapılandırma dosyalarını paylaşır, ancak ayrı süreçler olarak çalışır ve yalnızca dosya sistemi aracılığıyla iletişim kurar. +Her iki alt sistem `~/.failproofai/` ve projenin `.failproofai/` dizinindeki konfigürasyon dosyalarını paylaşır, ancak ayrı işlemler olarak çalışırlar ve yalnızca dosya sistemi aracılığıyla iletişim kurarlar. --- -## Hook işleyicisi +## Hook handler ### Claude Code ile Entegrasyon @@ -46,9 +45,9 @@ Her iki alt sistem `~/.failproofai/` ve projenin `.failproofai/` dizinindeki yap } ``` -Claude Code daha sonra her araç çağrısından önce `failproofai --hook PreToolUse` komutunu bir alt süreç olarak çağırır ve stdin üzerinde bir JSON yükü iletir. +Claude Code daha sonra her tool çağrısından önce `failproofai --hook PreToolUse` komutunu alt işlem olarak çağırır ve stdin üzerinden bir JSON payload'u geçer. -### Yük biçimi +### Payload formatı ```json { @@ -62,11 +61,11 @@ Claude Code daha sonra her araç çağrısından önce `failproofai --hook PreTo } ``` -`PostToolUse` olayları için yük, araçın çıktısını içeren `tool_result` da içerir. +`PostToolUse` olayları için payload ayrıca `tool_result` içerir ve bu da tool'un çıktısını içerir. -İşleyici 1 MB stdin sınırını uygular. Bu sınırı aşan yükler atılır ve tüm politikalar örtük olarak izin verir. +Handler, 1 MB stdin limitini uygular. Bu limiti aşan payload'lar atılır ve tüm politikalar örtülü olarak izin verir. -### Yanıt biçimi +### Response formatı **Reddet (PreToolUse):** ```json @@ -97,98 +96,98 @@ Claude Code daha sonra her araç çağrısından önce `failproofai --hook PreTo ``` **Stop olay talimatı:** -- Çıkış kodu: `2` -- Sebep stderr'e yazılmıştır (stdout değil) +- Exit kodu: `2` +- Sebep stderr'e yazılır (stdout'a değil) -**İzin ver:** -- Çıkış kodu: `0` +**İzin Ver:** +- Exit kodu: `0` - Boş stdout -**İzin ver ve mesaj:** +**İleti ile izin ver:** -`allow(message)` bir politikanın, işlem izin verildiğinde bile Claude'a bilgilendirici bağlam göndermesine izin verir. Hook işleyicisi aşağıdaki JSON'u **stdout**'a yazar (yapılandırma dosyası değil — bu, deny ve instruct yanıtlarının üstünde olduğu gibi hook işleyici sürecinin Claude Code'a yanıtıdır): +`allow(message)` bir politikanın, işlem izin verildiği halde Claude'a bilgisel bağlam göndermesine olanak tanır. Hook handler, aşağıdaki JSON'u **stdout**'a yazar (bir config dosyasına değil — bu, deny ve instruct response'ları gibi hook handler'ın Claude Code'a cevabıdır): ```json -// Hook işleyici süreci tarafından stdout'a yazılmıştır +// Hook handler işlemi tarafından stdout'a yazıldı { "hookSpecificOutput": { "additionalContext": "All CI checks passed on branch 'feat/my-feature'." } } ``` -- Çıkış kodu: `0` (işleme izin verildi) -- Birden fazla politika ileti içeren `allow` döndürdüğünde, iletileri yeni satırlarla birleştirerek tek bir `additionalContext` dizesine katılırlar -- Hiçbir politika ileti sağlamazsa, stdout boştur (öncekiyle aynı) +- Exit kodu: `0` (işlem izin verildi) +- Birden fazla politika `allow` ve bir ileti döndürdüğünde, mesajları newline'larla birleştirerek tek bir `additionalContext` string'ine dönüştürülür +- Hiçbir politika mesaj sağlamıyorsa, stdout boştur (önceki gibi) ### İşlem hattı -`src/hooks/handler.ts` tam işlem hattını uygular: +`src/hooks/handler.ts` tam hattı uygular: ```text stdin JSON - → yükü ayrıştır (maks 1 MB) - → oturum metaverilerini çıkar (session_id, cwd, tool_name, tool_input, vb.) - → readMergedHooksConfig(cwd) ← proje + yerel + global yapılandırmayı birleştir - → etkin yerleşik politikaları çözümlenen parametrelerle kayıt et - → customPoliciesPath'ten özel politikaları yükle (ayarlandıysa) - → özel politikaları politika kaydına kayıt et - → tüm politikaları değerlendir (yerleşiklerin ardından özel olanlar) - → ilk reddet kısa devresi - → talimat kararları birikir - → mesajlara izin verilir ve birikir - → JSON kararını stdout'a yaz - → olayı ~/.failproofai/hook-activity.jsonl'ye kalıcı hale getir + → payload'ı ayrıştır (maksimum 1 MB) + → oturum metadata'sını çıkart (session_id, cwd, tool_name, tool_input, vb.) + → readMergedHooksConfig(cwd) ← proje + lokal + global config'i birleştirir + → etkin builtin politikaları çözülmüş parametrelerle kayıt et + → customPoliciesPath'ten custom politikaları yükle (ayarlanmışsa) + → custom politikaları politika kaydına kayıt et + → tüm politikaları değerlendir (builtin'ler önce, sonra custom'lar) + → ilk deny hemen durdurur + → instruct kararları birikir + → allow mesajları birikir + → karar JSON'unu stdout'a yaz + → olayı ~/.failproofai/hook-activity.jsonl'ye kaydet → çık ``` -Tüm işlem, LLM çağrıları olmayan tipik yükler için 100ms altında çalışır. +Tipik payload'lar için LLM çağrısı olmadığında tüm işlem 100ms altında çalışır. --- -## Yapılandırma Yükleme +## Konfigürasyon yükleme `src/hooks/hooks-config.ts` üç kapsamlı config yükleme uygular. ```text [1] {cwd}/.failproofai/policies-config.json ← proje (en yüksek öncelik) -[2] {cwd}/.failproofai/policies-config.local.json ← yerel -[3] ~/.failproofai/policies-config.json ← global (en düşük öncelik) +[2] {cwd}/.failproofai/policies-config.local.json ← lokal +[3] ~/.failproofai/policies-config.json ← global (en düşük öncelik) ``` Birleştirme mantığı: -- `enabledPolicies` - her üç dosya arasında tekilleştirilen birleşim -- `policyParams` - politika başına anahtar, ilk dosya tamamen kazanır -- `customPoliciesPath` - ilk dosya kazanır -- `llm` - ilk dosya kazanır +- `enabledPolicies` - üç dosya arasında çoğaltılmamış birleşim +- `policyParams` - politika başına anahtar, tanımlayan ilk dosya tamamen kazanır +- `customPoliciesPath` - tanımlayan ilk dosya kazanır +- `llm` - tanımlayan ilk dosya kazanır -Web kontrol paneli yalnızca global yapılandırma için `readHooksConfig()` kullanır çünkü bir proje cwd ile çağrılmaz. +Web dashboard okuma ve yazma için `readHooksConfig()` (yalnızca global) kullanır, çünkü proje cwd'si ile çağrılmaz. --- -## Politika Değerlendirmesi +## Politika değerlendirilmesi `src/hooks/policy-evaluator.ts` politikaları sırayla çalıştırır. Her politika için: -1. Politikanın `params` şemasını ara (varsa). -2. Birleştirilen yapılandırmadan `policyParams[policy.name]` oku. -3. Kullanıcı tarafından sağlanan değerleri şema varsayılanları üzerine birleştirerek `ctx.params` üret. -4. `policy.fn(ctx)` komutunu çözümlenen bağlamla çağır. -5. Sonuç `deny` ise, hemen durdur ve bu kararı döndür. -6. Sonuç `instruct` ise, mesajı biriktir ve devam et. -7. Sonuç `allow` ise, sonraki politikaya devam et. +1. Politikanın `params` şemasını bulun (eğer varsa). +2. `policyParams[policy.name]`'ı birleştirilmiş config'ten okuyun. +3. Kullanıcı tarafından sağlanan değerleri şema varsayılanları üzerinden birleştirerek `ctx.params`'ı üretin. +4. Çözülmüş bağlamla `policy.fn(ctx)` çağırın. +5. Sonuç `deny` ise, hemen durun ve bu kararı döndürün. +6. Sonuç `instruct` ise, mesajı biriktirin ve devam edin. +7. Sonuç `allow` ise, sonraki politikaya devam edin. Tüm politikalar çalıştıktan sonra: -- Herhangi bir `deny` döndürülürse, reddet yanıtını yayınla. -- Herhangi bir `instruct` dönüşü toplanırsa, tüm mesajlarla birleştirilerek tek bir instruct yanıtı yayınla. -- Aksi takdirde, izin yanıtını yayınla (boş stdout, çıkış 0). +- `deny` döndürüldüyse, deny response'unu yayınlayın. +- `instruct` dönüşleri toplandıysa, tüm mesajları birleştirerek tek bir instruct response'u yayınlayın. +- Aksi takdirde, allow response'unu yayınlayın (boş stdout, exit 0). --- -## Yerleşik Politikalar +## Builtin politikalar -`src/hooks/builtin-policies.ts` tüm 39 yerleşik politikayı `BuiltinPolicyDefinition` nesneleri olarak tanımlar: +`src/hooks/builtin-policies.ts` 39 builtin politikanın tümünü `BuiltinPolicyDefinition` nesneleri olarak tanımlar: ```typescript interface BuiltinPolicyDefinition { @@ -206,15 +205,15 @@ interface BuiltinPolicyDefinition { } ``` -`params` kabul eden politikalar her parametre için türler ve varsayılanlar içeren `PolicyParamsSchema` bildirir. Politika değerlendiricisi, `fn` çağrılmadan önce çözümlenen değerleri `ctx.params` öğesine enjekte eder. Politika işlevleri, varsayılanlar her zaman ilk olarak uygulandığı için `ctx.params` öğesini null kontrol yapmadan okur. +`params` kabul eden politikalar, her parametre için tür ve varsayılan değer içeren `PolicyParamsSchema` bildirirler. Politika değerlendiricisi `fn` çağrılmadan önce çözülmüş değerleri `ctx.params`'a enjekte eder. Politika işlevleri varsayılanlar önce her zaman uygulandığı için `ctx.params`'ı null kontrolü yapmadan okurlar. -Politikalar içindeki desen eşleştirmesi, ham dize eşleştirmesinden değil, ayrıştırılmış komut belirteçlerini (argv) kullanır. Bu, shell operatörü enjeksiyonu aracılığıyla bypass'ı önler (örneğin, `sudo systemctl status *` için bir desen, komuta `; rm -rf /` eklenerek bypass edilemez). +Politika içindeki desen eşleştirme, ham string eşleştirmesi değil, ayrıştırılmış komut token'larını (argv) kullanır. Bu, shell operatörü enjeksiyonu yoluyla bypass'ı önler (örneğin `sudo systemctl status *` deseni `; rm -rf /` ekleyerek bypass edilemez). --- -## Özel Politikalar +## Custom politikalar -`src/hooks/custom-hooks-registry.ts` bir `globalThis` tabanlı kayıt defteri uygular: +`src/hooks/custom-hooks-registry.ts` `globalThis` destekli bir kayıt defteri uygular: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -229,23 +228,23 @@ export function clearCustomHooks(): void { ... } // testlerde kullanılır `src/hooks/custom-hooks-loader.ts` kullanıcının politika dosyasını yükler: -1. Yapılandırmadan `customPoliciesPath` öğesini oku; yoksa atla. -2. Mutlak yola çöz; dosyanın var olduğunu kontrol et. -3. Tüm `from "failproofai"` içe aktarımlarını gerçek dist yoluna yeniden yaz, böylece `customPolicies` aynı `globalThis` kaydına çözülür. -4. ESM uyumluluğunu sağlamak için geçişli yerel içe aktarımları yinelemeli olarak yeniden yaz. -5. Geçici `.mjs` dosyaları yaz ve giriş dosyasını `import()` et. -6. Kayıtlı kancaları almak için `getCustomHooks()` çağır. -7. `finally` bloğunda tüm geçici dosyaları temizle. +1. Config'ten `customPoliciesPath`'i okuyun; yoksa atla. +2. Mutlak path'e çözün; dosyanın var olup olmadığını kontrol edin. +3. Tüm `from "failproofai"` import'larını gerçek dist path'ine yeniden yazın, böylece `customPolicies` aynı `globalThis` kaydına çözülür. +4. ESM uyumluluğunu sağlamak için geçişli lokal import'ları özyinelemeli olarak yeniden yazın. +5. Geçici `.mjs` dosyaları yazın ve giriş dosyasını `import()` edin. +6. Kayıtlı hook'ları almak için `getCustomHooks()`'u çağırın. +7. `finally` bloğunda tüm geçici dosyaları temizleyin. -Herhangi bir hata (dosya bulunamadı, söz dizimi hatası, içe aktarma hatası) üzerinde, hata `~/.failproofai/hook.log` dosyasına kaydedilir ve yükleyici boş bir dizi döndürür. Yerleşik politikalar etkilenmez. +Herhangi bir hata durumunda (dosya bulunamadı, syntax hatası, import hatası), hata `~/.failproofai/hook.log`'a kaydedilir ve loader boş dizi döndürür. Builtin politikalar etkilenmez. -Özel politikalar tüm yerleşik politikalardan sonra değerlendirilir. Özel bir politika `deny` yine de başka özel politikaları kısa devre yapar (ancak bu noktada tüm yerleşikler zaten çalıştırılmıştır). +Custom politikalar tüm builtin politikaların ardından değerlendirilir. Bir custom politika `deny`'si yine de başka custom politikaları kısa devre yapabilir (ancak tüm builtin'ler zaten bu noktada çalışmış olmuştur). --- -## Etkinlik Günlüğü +## Aktivite günlüğü -Her hook olayından sonra, işleyici `~/.failproofai/hook-activity.jsonl` dosyasına bir JSONL satırı ekler: +Her hook olayından sonra, handler `~/.failproofai/hook-activity.jsonl`'ye bir JSONL satırı ekler: ```json { @@ -260,75 +259,75 @@ Her hook olayından sonra, işleyici `~/.failproofai/hook-activity.jsonl` dosyas } ``` -İzin vermeyen bir karar alan her politika için bir satır. İzin kararları günlüğe kaydedilmez (dosyayı küçük tutmak için). +Allow olmayan karar veren her politika için bir satır. Allow kararları günlüğe kaydedilmez (dosyayı küçük tutmak için). --- -## Kontrol Paneli Mimarisi +## Dashboard mimarisi -Kontrol paneli, React Server Components ve Server Actions ile App Router kullanan bir **Next.js 16** uygulamasıdır. +Dashboard, App Router ile React Server Components ve Server Actions kullanan bir **Next.js 16** uygulamasıdır. ```text app/ - layout.tsx ← Kök düzen (tema, telemetri, gezinti) - projects/page.tsx ← Sunucu bileşeni: tüm Claude projelerini listele - project/[name]/page.tsx ← Sunucu bileşeni: bir projedeki oturumları listele + layout.tsx ← Root layout (tema, telemetri, nav) + projects/page.tsx ← Server component: tüm Claude projelerini listele + project/[name]/page.tsx ← Server component: bir projedeki oturumları listele project/[name]/session/ - [sessionId]/page.tsx ← Sunucu bileşeni: oturum görüntüleyiciyi oluştur - policies/page.tsx ← İstemci bileşeni: politika yönetimi + etkinlik günlüğü + [sessionId]/page.tsx ← Server component: oturum görüntüleyiciyi renderla + policies/page.tsx ← Client component: politika yönetimi + aktivite günlüğü actions/ - get-hooks-config.ts ← Yapılandırmayı ve politika listesini oku + get-hooks-config.ts ← Config + politika listesini oku update-hooks-config.ts ← Politikayı aç/kapat update-policy-params.ts ← Politika parametrelerini güncelle - get-hook-activity.ts ← Etkinlik günlüğünü sayfalandır/ara - install-hooks-web.ts ← Tarayıcıdan kancaları yükle/kaldır + get-hook-activity.ts ← Aktivite günlüğünü sayfalandır/ara + install-hooks-web.ts ← Hook'ları tarayıcıdan yükle/kaldır api/ - download/[project]/[session]/route.ts ← CLI başına oturum dışa aktarımı (JSONL veya JSON) + download/[project]/[session]/route.ts ← CLI başına oturum dışa aktar (JSONL veya JSON) ``` **Veri akışı:** -- Sayfa bileşenleri, proje/oturum verilerini dosya sisteminden doğrudan okumak için `lib/projects.ts` ve `lib/log-entries.ts` komutlarını çağırır (okumalar için API katmanı yok). -- Politikalar sayfası, tüm mutasyonlar (değiştir, parametreleri güncelle, yükle/kaldır) için Server Actions kullanır. -- Oturum görüntüleyicisi Claude'un JSONL transkript biçimini ayrıştırır ve iletilerin ve araç çağrılarının bir zaman çizelgesini oluşturur. +- Sayfa bileşenleri, dosya sisteminden doğrudan proje/oturum verilerini okumak için `lib/projects.ts` ve `lib/log-entries.ts` çağırırlar (okumalar için API katmanı yok). +- Policies sayfası tüm mutasyonlar (aç/kapat, params güncelleme, yükle/kaldır) için Server Actions kullanır. +- Oturum görüntüleyicisi Claude'un JSONL transkript formatını ayrıştırır ve mesaj ile tool çağrılarından oluşan bir zaman çizelgesi renderlar. -**Temel tasarım kararları:** +**Anahtar tasarım kararları:** -- Veritabanı yok - tüm kalıcı durum düz dosyalardadır (`~/.failproofai/`, `~/.claude/projects/`). -- Mutasyonlar için Server Actions - CRUD işlemleri için REST API gerekli değildir. -- Okuma sayfaları için React Server Components - daha hızlı ilk yükleme, veri getirme için istemci paketi yok. -- İstemci bileşenleri yalnızca etkileşimin gerekli olduğu yerlerde (politika açma/kapatma, etkinlik arama, günlük görüntüleyicisi). +- Veritabanı yok - tüm kalıcı durum düz dosyalarda (`~/.failproofai/`, `~/.claude/projects/`). +- Mutasyonlar için Server Actions - CRUD işlemleri için REST API'ye gerek yok. +- Okuma sayfaları için React Server Components - daha hızlı ilk yükleme, veri getirme için istemci demeti yok. +- Client bileşenleri yalnızca etkileşimin gerekli olduğu yerlerde (politika açma/kapama, aktivite arama, günlük görüntüleyici). --- -## Dosya Düzeni +## Dosya düzeni ```text failproofai/ ├── bin/ │ └── failproofai.mjs # CLI yönlendiricisi (hook / dashboard / install / vb.) ├── src/hooks/ -│ ├── handler.ts # Hook olay işlem hattı +│ ├── handler.ts # Hook olay hattı │ ├── builtin-policies.ts # 39 politika tanımı │ ├── policy-evaluator.ts # Politika yürütme motoru │ ├── policy-registry.ts # Politika kaydı ve araması │ ├── policy-types.ts # TypeScript arayüzleri -│ ├── hooks-config.ts # Çok kapsamlı yapılandırma yükleme -│ ├── custom-hooks-registry.ts # globalThis tabanlı kanca kaydı -│ ├── custom-hooks-loader.ts # Kullanıcı JS kancaları için ESM yükleyicisi +│ ├── hooks-config.ts # Çok kapsamlı config yükleme +│ ├── custom-hooks-registry.ts # globalThis destekli hook kaydı +│ ├── custom-hooks-loader.ts # Kullanıcı JS hook'ları için ESM yükleyicisi │ ├── manager.ts # yükle / kaldır / listele işlemleri -│ ├── install-prompt.ts # Etkileşimli politika seçim istemi -│ ├── hook-logger.ts # hook.log dosyasına günlüğe kaydetme -│ ├── hook-activity-store.ts # Etkinliği hook-activity.jsonl dosyasına kalıcı hale getir -│ └── llm-client.ts # LLM API istemcisi (AI güçlü politikalar için) -├── app/ # Next.js kontrol paneli (sayfalar + sunucu işlemleri) +│ ├── install-prompt.ts # Etkileşimli politika seçimi istemi +│ ├── hook-logger.ts # hook.log'a günlükleme +│ ├── hook-activity-store.ts # Aktiviteyi hook-activity.jsonl'ye kaydet +│ └── llm-client.ts # LLM API istemcisi (AI destekli politikalar için) +├── app/ # Next.js dashboard (sayfalar + server actions) ├── lib/ # Paylaşılan yardımcılar │ ├── projects.ts # Dosya sisteminden Claude projelerini numaralandır -│ ├── log-entries.ts # Claude transkript JSONL biçimini ayrıştır -│ ├── paths.ts # Sistem yollarını çöz +│ ├── log-entries.ts # Claude transkript JSONL formatını ayrıştır +│ ├── paths.ts # Sistem path'lerini çözümle │ └── ... ├── components/ # Paylaşılan React UI bileşenleri -├── contexts/ # React bağlam sağlayıcıları (tema, otomatik yenileme, telemetri) -├── examples/ # Örnek özel kanca dosyaları +├── contexts/ # React bağlam sağlayıcıları (tema, auto-refresh, telemetri) +├── examples/ # Örnek custom hook dosyaları └── __tests__/ # Birim ve E2E testleri ``` \ No newline at end of file diff --git a/docs/tr/built-in-policies.mdx b/docs/tr/built-in-policies.mdx index 9140dfb3..240ec79d 100644 --- a/docs/tr/built-in-policies.mdx +++ b/docs/tr/built-in-policies.mdx @@ -1,19 +1,18 @@ --- ---- title: Yerleşik İlkeler -description: "Yaygın aracı arıza modlarını yakalayan 39 yerleşik ilke" +description: "Ajent başarısızlık modlarını yakalayan 39 yerleşik ilke" icon: shield --- -failproofai, yaygın aracı arıza modlarını yakalayan 39 yerleşik ilke ile birlikte gelir. Her ilke belirli bir kanca olayı türü ve araç adında çalışır. On dokuz ilke, kod yazmadan davranışını ayarlamanıza olanak tanıyan parametreleri kabul eder. Beş iş akışı ilkesi, Claude'un durması öncesinde bir commit → push → PR → CI hattını uygular. +failproofai, ortak ajent başarısızlık modlarını yakalayan 39 yerleşik ilke ile birlikte gelir. Her ilke belirli bir hook olay türü ve araç adında devreye girer. On dokuz ilke, kod yazmanıza gerek kalmadan davranışlarını ayarlamanıza izin veren parametreleri kabul eder. Beş iş akışı ilkesi, Claude'un durmadan önce commit → push → PR → CI ardışık düzenini uygular. --- ## Genel Bakış -İlkeler kategorilere ayrılmıştır: +İlkeler kategorilere ayrılır: -| Kategori | İlkeler | Kanca türü | +| Kategori | İlkeler | Hook türü | |----------|---------|-----------| | [Tehlikeli komutlar](#tehlikeli-komutlar) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | | [Altyapı komutları](#altyapı-komutları) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | @@ -26,15 +25,15 @@ failproofai, yaygın aracı arıza modlarını yakalayan 39 yerleşik ilke ile b | [Paket yöneticileri](#paket-yöneticileri) | prefer-package-manager | PreToolUse | | [İş akışı](#iş-akışı) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — aracının devam etmesini engeller. -- **`warn-`** — aracıya kendi kendini düzeltebilmesi için ek bağlam sağlar. -- **`sanitize-`** — aracı görmesinden önce aracın çıktısından hassas verileri temizler. +- **`block-`** — ajanı devam etmekten durdur. +- **`warn-`** — ajenta ek bağlam sağla, böylece kendini düzeltebilsin. +- **`sanitize-`** — ajent görmeden önce araç çıktısından hassas verileri temizle. ### Ad Alanları -Her ilke bir `/` yuvasında yer alır. Yerleşik ilkeler **`failproofai/`** ad alanına aittir — örneğin, `failproofai/sanitize-jwt`. Ad alanı, benzer kısa adlara sahip özel veya üçüncü taraf ilkeleri yüklerken çakışmaları engeller. +Her ilke bir `/` slotunda bulunur. Yerleşik ilkeler **`failproofai/`** ad alanına aittir — örneğin, `failproofai/sanitize-jwt`. Ad alanı, benzer kısa adlara sahip özel veya üçüncü taraf ilkeleri yüklerken çakışmaları önler. -Yapılandırmanızda yerleşik bir ilkeye kısa adı veya tam adı ile başvurabilirsiniz; her iki form aynı ilkeye çözümlenir: +Yapılandırmanızda yerleşik bir ilkeye kısa adı veya tam adı ile başvurabilirsiniz; her iki form da aynı ilkeyi çözer: ```json { @@ -45,33 +44,33 @@ Yapılandırmanızda yerleşik bir ilkeye kısa adı veya tam adı ile başvurab } ``` -Bir adda `/` yoksa, failproofai onu varsayılan `failproofai` ad alanına ait olarak davranır. Zaten `/` içeren adlar (örn. `myorg/foo`, `custom/my-hook`) olduğu gibi kalır. -- **`require-`** — koşullar karşılanana kadar Stop olayını engeller. +Bir adda `/` yoksa, failproofai bunu varsayılan `failproofai` ad alanına ait olarak davranır. Zaten `/` içeren adlar (örneğin `myorg/foo`, `custom/my-hook`) olduğu gibi tutulur. +- **`require-`** — koşullar karşılanana kadar Stop olayını engelle. --- -Her ilke, `policyParams` içinde isteğe bağlı bir `hint` alanını destekler. İpucu, Claude'un gördüğü deny veya instruct mesajına eklenerek, ilke kodunu değiştirmeden işlem yapılabilir rehberlik sağlar. Yerleşik, özel ve kural ilkeleriyle çalışır. Ayrıntılar için [Yapılandırma → hint](/tr/configuration#hint-cross-cutting) bölümüne bakın. +Her ilke `policyParams` içinde isteğe bağlı bir `hint` alanını destekler. İpucu, Claude'un gördüğü deny veya instruct iletisine eklenir; ilke kodunu değiştirmeden işlem yapılabilir rehberlik sağlar. Yerleşik, özel ve kural ilkeleriyle çalışır. Ayrıntılar için [Yapılandırma → hint](/tr/configuration#hint-cross-cutting) bölümüne bakın. --- ## Tehlikeli komutlar -Aracıların geri almması zor olan veya ana sisteme zarar verebilecek işlemleri çalıştırmasını engeller. +Ajentlerin geri alınması zor olan veya ana bilgisayar sistemine zarar verebilecek işlemleri çalıştırmasını önleyin. ### `block-sudo` **Olay:** PreToolUse (Bash) **Varsayılan:** Herhangi bir `sudo` komutunu reddeder. -`sudo` anahtar sözcüğünü içeren çağrıları engeller. Model eşleştirmesi ham dize yerine ayrıştırılmış komut belirteçleri üzerinde yapılır; bu, shell operatörü enjeksiyonu yoluyla bypass'ı engeller. +`sudo` anahtar sözcüğünü içeren çağırışları engeller. Model eşleştirme ham dize yerine ayrıştırılmış komut jetonlarında yapılır; shell operatörü enjeksiyonu yoluyla atlatmayı önler. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `allowPatterns` | `string[]` | `[]` | İzin verilen tam komut önekleri. Her giriş ayrıştırılmış argv belirteçlerine karşı eşleştirilir. | +| `allowPatterns` | `string[]` | `[]` | İzin verilen tam komut önekleri. Her giriş ayrıştırılmış argv jetonlarına karşı eşleştirilir. | **Örnek:** @@ -85,10 +84,10 @@ Aracıların geri almması zor olan veya ana sisteme zarar verebilecek işlemler } ``` -Bu yapılandırmayla, `sudo systemctl status nginx` izin verilir, ancak `sudo rm /etc/hosts` reddedilir. +Bu yapılandırma ile `sudo systemctl status nginx` izin verilir, ancak `sudo rm /etc/hosts` reddedilir. -Desenler ham komut dizesi değil, ayrıştırılmış belirteçlere karşı eşleştirilir. Bu, eklenen shell operatörleri yoluyla bypass'ı engeller (örn. `sudo systemctl status x; rm -rf /` `sudo systemctl status *` ile eşleşmez). +Desenler ham komut dizesi değil, ayrıştırılmış jetonlara karşı eşleştirilir. Bu, shell operatörleri yoluyla atlatmayı önler (örneğin `sudo systemctl status x; rm -rf /` kodu `sudo systemctl status *` ile eşleşmez). --- @@ -96,13 +95,13 @@ Desenler ham komut dizesi değil, ayrıştırılmış belirteçlere karşı eşl ### `block-rm-rf` **Olay:** PreToolUse (Bash) -**Varsayılan:** `rm -rf`, `rm -fr` ve benzer özyinelemeli silme formlarını reddeder. +**Varsayılan:** `rm -rf`, `rm -fr` ve benzer yinelemeli silme formlarını reddeder. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `allowPaths` | `string[]` | `[]` | Özyinelemeli olarak silinmesi güvenli olan yollar (örn. `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Yinelemeli olarak silinmesi güvenli olan yollar (örneğin `/tmp`). | **Örnek:** @@ -123,29 +122,29 @@ Desenler ham komut dizesi değil, ayrıştırılmış belirteçlere karşı eşl **Olay:** PreToolUse (Bash) **Varsayılan:** `curl | bash`, `curl | sh`, `wget | bash` ve benzer desenleri reddeder. -Parametre yok. +Parametresi yok. --- ### `block-failproofai-commands` **Olay:** PreToolUse (Bash) -**Varsayılan:** failproofai'ın kaldırılmasını veya devre dışı bırakılmasını sağlayacak komutları reddeder (örn. `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Varsayılan:** failproofai'nin kendisini kaldıracak veya devre dışı bırakacak komutları reddeder (örneğin `npm uninstall failproofai`, `failproofai policies --uninstall`). -Parametre yok. +Parametresi yok. --- ## Altyapı komutları -Kodlama aracılarının altyapı CLI'lerini çalıştırmasını veya CI/CD hattını tetiklemesini engeller. Bu kategorideki tüm ilkeler **opt-in** (`defaultEnabled: false`) — `kubectl`, `terraform` vb. çağırması gereken aracılar ilkeyi etkinleştirmediğiniz sürece kesintiye uğramaz. Etkinleştirildiğinde, eşleşen CLI'nin her çağrısı komutu `allowPatterns` içindeki bir giriş ile eşleşmedikçe reddedilir. +Kodlama ajanlarının altyapı CLI'larını çalıştırmasını veya CI/CD ardışık düzenlerini tetiklemesini durdurun. Bu kategorideki tüm ilkeler **isteğe bağlı** (`defaultEnabled: false`) — `kubectl`, `terraform` vb. çağırması gereken ajanlar, ilkeyi etkinleştirmediğiniz sürece kesilmeyecektir. Etkinleştirildiğinde, eşleştirilen CLI'nın her çağırması `allowPatterns` içindeki bir giriş ile eşleşmediği sürece reddedilir. -Desen dilbilgisi, [`block-sudo`](#block-sudo) ile aynıdır: belirteçler ayrıştırılmış argv'ye karşı eşleştirilir, `*` bir belirteç için joker karttır ve herhangi bir çağrı içeren komut veya enjeksiyon bypass'ını engellemeyi tercih etmek için gömülü shell metakarakterlerine sahip belirteçler, izin listesi eşleştirmesi öncesinde reddedilir. +Desen dilbilgisi [`block-sudo`](#block-sudo) ile aynıdır: jetonlar ayrıştırılmış argv'ye karşı eşleştirilir, `*` bir jeton için joker karakterdir ve herhangi bir shell operatörü (`&&`, `||`, `|`, `;`) içeren veya gömülü shell metakarakterleri olan komutlar, enjeksiyon atlatmalarını önlemek için beyaz liste eşleştirmesinden önce reddedilir. ### `block-kubectl` **Olay:** PreToolUse (Bash) -**Varsayılan:** Herhangi bir `kubectl` çağrısını reddeder. +**Varsayılan:** Herhangi bir `kubectl` çağırışını reddeder. **Parametreler:** @@ -165,14 +164,14 @@ Desen dilbilgisi, [`block-sudo`](#block-sudo) ile aynıdır: belirteçler ayrı } ``` -Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f deploy.yaml` reddedilir. +Bu yapılandırma ile `kubectl get pods` izin verilir ancak `kubectl apply -f deploy.yaml` reddedilir. --- ### `block-terraform` **Olay:** PreToolUse (Bash) -**Varsayılan:** Herhangi bir `terraform` veya `tofu` (OpenTofu) çağrısını reddeder. +**Varsayılan:** Herhangi bir `terraform` veya `tofu` (OpenTofu) çağırışını reddeder. **Parametreler:** @@ -197,7 +196,7 @@ Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-aws-cli` **Olay:** PreToolUse (Bash) -**Varsayılan:** Herhangi bir `aws` CLI çağrısını reddeder. +**Varsayılan:** Herhangi bir `aws` CLI çağırışını reddeder. **Parametreler:** @@ -222,7 +221,7 @@ Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-gcloud` **Olay:** PreToolUse (Bash) -**Varsayılan:** Herhangi bir `gcloud` (Google Cloud) CLI çağrısını reddeder. +**Varsayılan:** Herhangi bir `gcloud` (Google Cloud) CLI çağırışını reddeder. **Parametreler:** @@ -247,7 +246,7 @@ Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-az-cli` **Olay:** PreToolUse (Bash) -**Varsayılan:** Herhangi bir `az` (Azure) CLI çağrısını reddeder. +**Varsayılan:** Herhangi bir `az` (Azure) CLI çağırışını reddeder. **Parametreler:** @@ -272,7 +271,7 @@ Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-helm` **Olay:** PreToolUse (Bash) -**Varsayılan:** Herhangi bir `helm` çağrısını reddeder. +**Varsayılan:** Herhangi bir `helm` çağırışını reddeder. **Parametreler:** @@ -297,7 +296,7 @@ Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-gh-pipeline` **Olay:** PreToolUse (Bash) -**Varsayılan:** Durumu mutasyona uğratan veya hattı tetikleyen aşağıdaki `gh` CLI alt komutlarını reddeder: +**Varsayılan:** Durumu değiştiren veya ardışık düzenler tetikleyen aşağıdaki `gh` CLI alt komutlarını reddeder: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -306,13 +305,13 @@ Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f de - `gh cache delete` - `gh secret set`, `gh secret delete` -`gh pr view`, `gh pr list`, `gh run list`, `gh release view` ve `gh api repos/.../...` gibi salt okunur `gh` alt komutları bu ilkeyle **eşleşmez** — iş akışı kontrolleri (failproofai'ın kendi `require-ci-green-before-stop` dahil) için rutin olarak gereklidir. +`gh pr view`, `gh pr list`, `gh run list`, `gh release view` ve `gh api repos/.../...` gibi salt okunur `gh` alt komutları bu ilke tarafından eşleştirilmez — iş akışı denetimleri için rutinlik olarak gereklidir (failproofai'nin kendi `require-ci-green-before-stop` dahil). **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `allowPatterns` | `string[]` | `[]` | Aksi takdirde reddedilecek belirli betikleştirilmiş çağrılara izin vermek için. | +| `allowPatterns` | `string[]` | `[]` | Aksi takdirde reddedilecek olmasına rağmen izin verilebilecek belirli komut dosyası çağırışları. | **Örnek:** @@ -330,27 +329,27 @@ Bu yapılandırmayla, `kubectl get pods` izin verilir ancak `kubectl apply -f de ## Sırlar (sanitizers) -Aracıların kimlik bilgilerini bağlamlarına veya çıktılarına sızmasını engeller. Sanitizer ilkeleri **PostToolUse** olaylarında çalışır. Claude bir Bash komutu çalıştırdığında, bir dosya okuduğunda veya herhangi bir aracı çağırdığında, bu ilkeler çıktı Claude'a döndürülmeden önce inceler. Bir gizli desen algılanırsa, ilke çıktının geri aktarılmasını engeller. +Ajentlerin kimlik bilgilerini kontekst veya çıktılarında sızmasını durdurun. Sanitizer ilkeleri **PostToolUse** olaylarında devreye girer. Claude bir Bash komutu çalıştırdığında, bir dosya okuduğunda veya herhangi bir aracı çağırdığında, bu ilkeler çıktı Claude'a döndürülmeden önce incelenir. Gizli bir desen algılanırsa, ilke çıktının geri dönmesini engelleyen bir reddetme kararı verir. ### `sanitize-jwt` **Olay:** PostToolUse (tüm araçlar) -**Varsayılan:** JWT belirteçlerini (`.` ile ayrılmış üç base64url segmenti) gizler. +**Varsayılan:** JWT jetonlarını (`.` ile ayrılmış üç base64url segmenti) gizler. -Parametre yok. +Parametresi yok. --- ### `sanitize-api-keys` **Olay:** PostToolUse (tüm araçlar) -**Varsayılan:** Yaygın API anahtar biçimlerini gizler: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT'ler (`ghp_`), AWS erişim anahtarları (`AKIA`), Stripe anahtarları (`sk_live_`, `sk_test_`) ve Google API anahtarları (`AIza`). +**Varsayılan:** Yaygın API anahtarı biçimlerini gizler: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT'ları (`ghp_`), AWS erişim anahtarları (`AKIA`), Stripe anahtarları (`sk_live_`, `sk_test_`) ve Google API anahtarları (`AIza`). **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Gizli olarak kabul edilecek ek regex desenleri. | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Sır olarak işlem görmesi gereken ek regex desenleri. | **Örnek:** @@ -372,42 +371,42 @@ Parametre yok. ### `sanitize-connection-strings` **Olay:** PostToolUse (tüm araçlar) -**Varsayılan:** Gömülü kimlik bilgileri içeren veritabanı bağlantı dizelerini gizler (örn. `postgresql://user:password@host/db`). +**Varsayılan:** Gömülü kimlik bilgileri içeren veritabanı bağlantı dizelerini gizler (örneğin `postgresql://user:password@host/db`). -Parametre yok. +Parametresi yok. --- ### `sanitize-private-key-content` **Olay:** PostToolUse (tüm araçlar) -**Varsayılan:** PEM bloklarını (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` vb.) gizler. +**Varsayılan:** PEM bloklarını gizler (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` vb.). -Parametre yok. +Parametresi yok. --- ### `sanitize-bearer-tokens` **Olay:** PostToolUse (tüm araçlar) -**Varsayılan:** `Authorization: Bearer ` başlıklarını gizler; belirteç 20 veya daha fazla karakterdir. +**Varsayılan:** `Authorization: Bearer ` başlıklarını gizler; burada jeton 20 veya daha fazla karakterdir. -Parametre yok. +Parametresi yok. --- ## Ortam -Aracılar tarafından okunan veya açığa çıkarılan hassas ortam yapılandırmasını korur. +Hassas ortam yapılandırmasını ajanlar tarafından okunmasından veya açığa çıkmasından koruyun. ### `block-env-files` **Olay:** PreToolUse (Bash, Read) -**Varsayılan:** `cat .env`, `Read` araç çağrıları (dosya yolu olarak `.env` ile) vb. aracılığıyla `.env` dosyalarını okumayı reddeder. +**Varsayılan:** `cat .env`, dosya yolu olarak `.env` ile Read araç çağrıları vb. aracılığıyla `.env` dosyalarını okumasını reddeder. -`.envrc` veya diğer ortam-ilgili dosyaları engellemiyor — yalnızca tam olarak `.env` adlandırılan dosyaları. +`.envrc` veya diğer ortam-komşu dosyaları engelleme — yalnızca tam olarak `.env` adındaki dosyaları engelle. -Parametre yok. +Parametresi yok. --- @@ -416,24 +415,24 @@ Parametre yok. **Olay:** PreToolUse (Bash) **Varsayılan:** Ortam değişkenlerini yazdıran komutları reddeder: `printenv`, `env`, `echo $VAR`. -Parametre yok. +Parametresi yok. --- ## Dosya erişimi -Aracıları proje sınırları içinde çalışmaya ve hassas dosyalardan uzak tutmaya devam eder. +Ajentleri proje sınırları içinde ve hassas dosyalardan uzak tutun. ### `block-read-outside-cwd` **Olay:** PreToolUse (Read, Bash) -**Varsayılan:** Proje kökünün dışında dosya okumayı reddeder. Sınır `CLAUDE_PROJECT_DIR` (Claude Code tarafından oturum başına bir kez belirlenir) olup, söz konusu değişken ayarlanmadığında oturum'ın geçerli çalışma dizinine geri dönüş yapılır. Canlı `cwd` yerine proje kökü kullanımı, Claude bir alt dizine `cd` yaptığında bile sınırın kararlı kalması demektir. +**Varsayılan:** Proje kökü dışındaki dosyaları okumasını reddeder. Sınır `CLAUDE_PROJECT_DIR` (Claude Code tarafından oturum başına bir kez ayarlanır) ve bu değişken ayarlanmadığında oturumun geçerli çalışma dizinine geri döner. Canlı `cwd` yerine proje kökünü kullanmak, Claude `cd` yaptıktan sonra bile sınırın kararlı kalmasını sağlar. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `allowPaths` | `string[]` | `[]` | Proje kökünün dışında olsa bile izin verilen kesinlik yol ön ekleri. | +| `allowPaths` | `string[]` | `[]` | Proje kökü dışında olsa bile izin verilen mutlak yol önekleri. | **Örnek:** @@ -452,13 +451,13 @@ Aracıları proje sınırları içinde çalışmaya ve hassas dosyalardan uzak t ### `block-secrets-write` **Olay:** PreToolUse (Write, Edit) -**Varsayılan:** Özel anahtarlar ve sertifikalar için yaygın olarak kullanılan dosyalara yazılmasını engeller: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Varsayılan:** Özel anahtarlar ve sertifikalar için yaygın olarak kullanılan dosyalara yazılışı reddeder: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `additionalPatterns` | `string[]` | `[]` | Engelleme yapılacak ek dosya adı desenleri (glob-stili). | +| `additionalPatterns` | `string[]` | `[]` | Engellenmesi gereken ek dosya adı desenleri (glob tarzı). | **Örnek:** @@ -476,7 +475,7 @@ Aracıları proje sınırları içinde çalışmaya ve hassas dosyalardan uzak t ## Git -Kazara itme, zorlamaya itme ve geri almesi zor olan dal hatalarını engeller. +Geri alınması zor olan kazara itişleri, zorla-itişleri ve dal hatalarını önleyin. ### `block-push-master` @@ -502,7 +501,7 @@ Kazara itme, zorlamaya itme ve geri almesi zor olan dal hatalarını engeller. ``` -Tüm dallara itmeye izin vermek için (bu ilkeyi `enabledPolicies` öğesinden kaldırmadan devre dışı bırakmak için), `protectedBranches: []` ayarlayın. +Tüm dallara itişe izin vermek için (bu ilkeyi `enabledPolicies` öğesinden kaldırmadan etkili bir şekilde devre dışı bırakmak), `protectedBranches: []` ayarını yapın. --- @@ -510,13 +509,13 @@ Tüm dallara itmeye izin vermek için (bu ilkeyi `enabledPolicies` öğesinden k ### `block-work-on-main` **Olay:** PreToolUse (Bash) -**Varsayılan:** Çalışma ağacı `main` veya `master` üzerindeyken `git commit`, `git merge`, `git rebase` ve `git cherry-pick` komutlarını reddeder. Dal oluşturma ve geçiş (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) etkilenmemiş. +**Varsayılan:** Çalışma ağacı `main` veya `master` üzerindeyken `git commit`, `git merge`, `git rebase` ve `git cherry-pick` komutlarını reddeder. Dal oluşturma ve geçiş (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) etkilenmez. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `protectedBranches` | `string[]` | `["main", "master"]` | commit/merge/rebase/cherry-pick'inin reddedildiği dal adları. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Commit/merge/rebase/cherry-pick'in reddedildiği dal adları. | --- @@ -525,13 +524,13 @@ Tüm dallara itmeye izin vermek için (bu ilkeyi `enabledPolicies` öğesinden k **Olay:** PreToolUse (Bash) **Varsayılan:** `git push --force` ve `git push -f` komutlarını reddeder. -İlkeye özgü parametre yok. Alternatif önerileri sunmak için çapraz kesit [`hint`](/tr/configuration#hint-cross-cutting) özelliğini kullanın: +İlke spesifik parametresi yok. Alternatifleri önermek için çapraz kesme [`hint`](/tr/configuration#hint-cross-cutting) kullanın: ```json { "policyParams": { "block-force-push": { - "hint": "Geçerli HEAD'inizden yeni bir dal oluşturun (örn. `git checkout -b `) ve bunun yerine bunu itin." + "hint": "Geçerli HEAD'inizden yeni bir dal oluşturun (örneğin `git checkout -b `) ve bunun yerine o dalı itin." } } } @@ -542,66 +541,66 @@ Tüm dallara itmeye izin vermek için (bu ilkeyi `enabledPolicies` öğesinden k ### `warn-git-amend` **Olay:** PreToolUse (Bash) -**Varsayılan:** `git commit --amend` çalıştırırken Claude'u dikkatli ilerlemeye talimat verir. Komutu engellemiyor. +**Varsayılan:** Claude'u `git commit --amend` çalıştırırken dikkatli ilerlemeye bilgilendirir. Komut engellenmez. -Parametre yok. +Parametresi yok. --- ### `warn-git-stash-drop` **Olay:** PreToolUse (Bash) -**Varsayılan:** `git stash drop` çalıştırmadan önce Claude'u onay vermeye talimat verir. Komutu engellemiyor. +**Varsayılan:** Claude'u `git stash drop` çalıştırmadan önce onaylamaya bilgilendirir. Komut engellenmez. -Parametre yok. +Parametresi yok. --- ### `warn-all-files-staged` **Olay:** PreToolUse (Bash) -**Varsayılan:** `git add -A` veya `git add .` çalıştırırken Claude'u sahnelediklerini gözden geçirmeye talimat verir. Komutu engellemiyor. +**Varsayılan:** Claude'u `git add -A` veya `git add .` çalıştırdığında sahneye koydukları şeyleri gözden geçirmeye bilgilendirir. Komut engellenmez. -Parametre yok. +Parametresi yok. --- ## Veritabanı -Yıkıcı SQL işlemlerini veritabanınıza karşı yürütülmesinden önce yakalar. +Yıkıcı SQL işlemlerini veritabanınıza yürütülmeden önce yakalayın. ### `warn-destructive-sql` **Olay:** PreToolUse (Bash) -**Varsayılan:** `DROP TABLE`, `DROP DATABASE` veya `WHERE` cümlesi olmayan `DELETE` içeren SQL çalıştırmadan önce Claude'u onay vermeye talimat verir. +**Varsayılan:** Claude'u `DROP TABLE`, `DROP DATABASE` veya `WHERE` şartı olmayan `DELETE` içeren SQL çalıştırmadan önce onaylamaya bilgilendirir. -Parametre yok. +Parametresi yok. --- ### `warn-schema-alteration` **Olay:** PreToolUse (Bash) -**Varsayılan:** `ALTER TABLE` deyimleri çalıştırmadan önce Claude'u onay vermeye talimat verir. +**Varsayılan:** Claude'u `ALTER TABLE` ifadeleri çalıştırmadan önce onaylamaya bilgilendirir. -Parametre yok. +Parametresi yok. --- ## Uyarılar -Aracılara potansiyel olarak riskli ancak yıkıcı olmayan işlemlerden önce ek bağlam verir. +Ajentlere potansiyel olarak riskli ancak yıkıcı olmayan işlemlerden önce ekstra bağlam sağlayın. ### `warn-large-file-write` **Olay:** PreToolUse (Write) -**Varsayılan:** 1024 KB'den daha büyük dosyalar yazılmadan önce Claude'u onay vermeye talimat verir. +**Varsayılan:** Claude'u 1024 KB'den büyük dosyaları yazmadan önce onaylamaya bilgilendirir. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `thresholdKb` | `number` | `1024` | Uyarı verilen dosya boyutu eşiği kilobayt cinsinden. | +| `thresholdKb` | `number` | `1024` | Uyarı verildiği dosya boyutu eşiği (kilobayt). | **Örnek:** @@ -616,7 +615,7 @@ Aracılara potansiyel olarak riskli ancak yıkıcı olmayan işlemlerden önce e ``` -Kanca işleyicisi yüklerde 1 MB stdin sınırı uygular. Bu ilkeyi küçük içerikle test etmek için `thresholdKb` öğesini 1024'ün çok altında bir değere ayarlayın. +Hook işleyicisi yükler üzerinde 1 MB stdin sınırı uygular. Bu ilkeyi küçük içerikle test etmek için `thresholdKb` değerini 1024'in altında bir değere ayarlayın. --- @@ -624,47 +623,47 @@ Kanca işleyicisi yüklerde 1 MB stdin sınırı uygular. Bu ilkeyi küçük iç ### `warn-package-publish` **Olay:** PreToolUse (Bash) -**Varsayılan:** `npm publish` çalıştırmadan önce Claude'u onay vermeye talimat verir. +**Varsayılan:** Claude'u `npm publish` çalıştırmadan önce onaylamaya bilgilendirir. -Parametre yok. +Parametresi yok. --- ### `warn-background-process` **Olay:** PreToolUse (Bash) -**Varsayılan:** `nohup`, `&`, `disown` veya `screen` aracılığıyla arka plan işlemleri başlatırken Claude'u dikkatli olmaya talimat verir. +**Varsayılan:** Claude'u `nohup`, `&`, `disown` veya `screen` aracılığıyla arka plan işlemleri başlatırken dikkatli olmaya bilgilendirir. -Parametre yok. +Parametresi yok. --- ### `warn-global-package-install` **Olay:** PreToolUse (Bash) -**Varsayılan:** Sanal ortam olmadan `npm install -g`, `yarn global add` veya `pip install` çalıştırmadan önce Claude'u onay vermeye talimat verir. +**Varsayılan:** Claude'u `npm install -g`, `yarn global add` veya sanal ortam olmadan `pip install` çalıştırmadan önce onaylamaya bilgilendirir. -Parametre yok. +Parametresi yok. --- ## Paket yöneticileri -Aracının kullanmasına izin verilen paket yöneticisini zorunlu kılar. +Ajanın hangi paket yöneticilerini kullanmasına izin verildiğini zorunlu kılın. ### `prefer-package-manager` **Olay:** PreToolUse (Bash) -**Varsayılan:** Devre dışı. Etkinleştirildiğinde, `allowed` listesinde olmayan herhangi bir paket yöneticisi komutunu engeller ve Claude'u komutu izin verilen bir yöneticisi kullanarak yeniden yazması için söyler. +**Varsayılan:** Devre dışı. Etkinleştirildiğinde, `allowed` listesinde olmayan paket yöneticisi komutlarını engeller ve Claude'u komut yöneticisi kullanarak komutu yazmaya söyler. Algılar: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | Parametre | Tür | Varsayılan | Açıklama | |-----------|-----|-----------|---------| -| `allowed` | string[] | `[]` | İzin verilen paket yöneticisi adları. Bu listeye girmeyen algılanan yöneticiler engellenir. Boş olduğunda, ilke boştadır. | -| `blocked` | string[] | `[]` | Yerleşik listeyi aşan engelleme yapılacak ek yönetici adları (örn. `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | İzin verilen paket yöneticisi adları. Bu listede olmayan herhangi bir algılanan yönetici engellenir. Boş olduğunda ilke işlemsiz kalır. | +| `blocked` | string[] | `[]` | Yerleşik listesinin ötesinde engellenmesi gereken ek yönetici adları (örneğin `['pdm', 'pipx']`). | -Yerleşik blok listesi şunları kapsar: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Bu listeye girmeyen yöneticileri eklemek için `blocked` özelliğini kullanın. +Yerleşik engel listesi şunları kapsar: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Bu listede olmayan yöneticileri eklemek için `blocked` kullanın. **Örnek yapılandırma:** @@ -680,74 +679,74 @@ Yerleşik blok listesi şunları kapsar: pip, pip3, npm, npx, yarn, pnpm, pnpx, } ``` -Bu yapılandırmayla, `pip install flask` ve `pdm install flask` ikisi de reddedilir ve Claude'a bunun yerine `uv` veya `bun` kullanması söylenir. `uv install flask` gibi komutlar izin verilir çünkü `uv` izin listesindedir ve ilk olarak kontrol edilir. +Bu yapılandırma ile `pip install flask` ve `pdm install flask` her ikisi de reddedilir; Claude'a bunun yerine `uv` veya `bun` kullanması söylenir. `uv` beyaz listede olduğu ve önce kontrol edildiği için `uv pip install flask` gibi komutlar izin verilir. --- ## AI davranışı -Aracıların takılı kalması veya beklenmedik şekilde davranması durumunda algılar. +Ajanların sıkışıp kalması veya beklenmeyen davranması durumlarını algılayın. ### `warn-repeated-tool-calls` **Olay:** PreToolUse (tüm araçlar) -**Varsayılan:** Aynı araç 3 veya daha fazla kez özdeş parametrelerle çağrıldığında Claude'u yeniden düşünmeye talimat verir — bu sık sık aracının döngüde takılı kaldığının bir işaretidir. +**Varsayılan:** Aynı araç aynı parametrelerle 3+ kez çağrılırsa Claude'u yeniden düşünmeye bilgilendirir — ajanın bir döngüde sıkışmasının yaygın bir işaretidir. -Parametre yok. +Parametresi yok. --- ## İş akışı -Disiplinli bir oturum sonu iş akışını zorunlu kılar. Bu ilkeler **Stop** olayında çalışır ve aracının her koşul karşılanana kadar durmasını engeller. Doğal bir bağımlılık zincirini takip ederler: commit → push → PR → CI. Bir ilke reddederse, zincirdeki sonraki ilkeler atlanır (deny kısa devre yapar). +Disiplinli bir oturum sonu iş akışı uygulayın. Bu ilkeler **Stop** olayında devreye girer ve aynı ajan, her koşul karşılanana kadar durmaktan yoksun bırakılır. Doğal bir bağımlılık zinciri izlerler: commit → push → PR → CI. Bir ilke reddederse, zincirdeki sonraki ilkeler atlanır (reddetme kısa devre). -Tüm iş akışı ilkeleri **fail-open** özelliğine sahiptir: gerekli araç kullanılamıyorsa (örn. `gh` yüklü değil, git uzak yok), ilke neden kontrol atlandığını açıklayan bilgilendirici bir mesajla izin verir. +Tüm iş akışı ilkeleri **başarısız-açık** dur: gerekli araç kullanılamıyorsa (örneğin `gh` kurulu değil, git uzaktan yoktur), ilke bir bilgi iletisi ile izin verir; kontrol neden atlanmadığını açıklar. ### CLI başına Stop semantiği -Stop uygulaması, yedi desteklenen CLI arasında biraz farklı görünür çünkü her biri farklı bir aracı bitti kanca sözleşmesi sunar. **Sonuç** aynıdır — aracı bir iş akışı kapısı başarısız olurken durma yolundan çekilemez — ama **mekanikler** farklıdır. Aşağıdaki tablo özeti verir; yalnızca Pi, bir `require-*-before-stop` ilkesini etkinleştirmeden önce anlaşılmaya değer kullanıcı tarafından görülen bir anlama sahiptir. +Stop uygulaması yedi desteklenen CLI arasında biraz farklı görünür; çünkü her biri farklı bir "ajan bitişi" hook sözleşmesi ortaya koyar. **Sonuç** aynıdır — ajan bir iş akışı kapısı başarısız iken durmaktan kurtulmaz — ancak **mekanikler** farklıdır. Aşağıdaki tablo özetler; bir `require-*-before-stop` ilkesini etkinleştirmeden önce anlamanın değerine sahip Pi'de yalnızca kullanıcı tarafından görülebilir bir garip durum vardır. -| CLI | Kapı ne zaman çalışır | Ne görürsünüz | +| CLI | Kapı ne zaman devreye girer | Ne görürsünüz | |---|---|---| -| Claude Code | Aynı aracı döngüsü, hemen | Claude çalışmaya devam eder — sorunu düzeltir, sonra yeniden bitirmeyi dener. Sizin için görünen kesinti yok. | -| Codex | Aynı aracı döngüsü, hemen | Claude ile aynı. | -| GitHub Copilot CLI | Aynı aracı döngüsü, hemen | Claude ile aynı (Copilot'un `{decision:"block", reason}` yeniden deneme kanalını kullanır — Copilot CLI 1.0.41'e karşı ampirik olarak doğrulanmıştır). | -| Cursor Agent | Aynı aracı döngüsü, hemen | Claude ile aynı (Cursor'ın `{followup_message}` kanalını kullanır — `loop_limit` kadar sınırlı, varsayılan 5 yeniden deneme). | -| Gemini CLI | Aynı aracı döngüsü, hemen | Claude ile aynı (Gemini'nin `AfterAgent` üzerinde `{decision:"block", reason}` kanalını kullanır). | -| OpenCode | Aynı aracı döngüsü, hemen | Claude ile aynı (OpenCode'un `client.session.prompt(...)` SDK çağrısını `hookSpecificOutput.additionalContext` aracılığıyla yönlendirilmiş şekilde kullanır). | -| **Pi (pi-coding-agent)** | **Sonraki kullanıcı sırası** | **Pi görünür şekilde durur** kapı çalışırken — aracı döngüsü çıkar ve istemle dönersiniz. Kapı daha sonra bir sonraki istem gönderdiğinizde çalışır: failproofai bir `MANDATORY ACTION REQUIRED` yönergesi bu dönüşün sistem istemine hazırlar, LLM'ye iş akışı adımını (commit, push, vb.) istediğiniz şeyden önce tamamlamayı talimat verir. | +| Claude Code | Aynı ajan döngüsü, hemen | Claude çalışmaya devam eder — sorunu düzeltir, sonra tekrar bitirmeye çalışır. Size görünen kesinti yok. | +| Codex | Aynı ajan döngüsü, hemen | Claude ile aynı. | +| GitHub Copilot CLI | Aynı ajan döngüsü, hemen | Claude ile aynı (Copilot'un `{decision:"block", reason}` yeniden deneme kanalını kullanır — ampirik olarak Copilot CLI 1.0.41'e karşı doğrulanmıştır). | +| Cursor Agent | Aynı ajan döngüsü, hemen | Claude ile aynı (Cursor'un `{followup_message}` kanalını kullanır — `loop_limit`, varsayılan 5 yeniden denemeler ile sınırlandırılmış). | +| Gemini CLI | Aynı ajan döngüsü, hemen | Claude ile aynı (Gemini'nin `{decision:"block", reason}` kanalını kullanır; `AfterAgent` üzerinde). | +| OpenCode | Aynı ajan döngüsü, hemen | Claude ile aynı (OpenCode'un `client.session.prompt(...)` SDK çağrısını kullanır; `hookSpecificOutput.additionalContext` aracılığıyla yönlendirilmiş). | +| **Pi (pi-coding-agent)** | **Sonraki kullanıcı sırası** | **Kapı devreye girdiğinde Pi görünen şekilde durur** — ajan döngüsü çıkar ve komut isteminin başına dönersiniz. Kapı daha sonra bir sonraki iletişim gönderdiğinizde devreye girer: failproofai iş akışı adımını tamamlamadan önce (commit, push vb.) bir `MANDATORY ACTION REQUIRED` yönergesini o sıraya ait sistem komutunun başına ekler; ne istedinizi yapmadan önce. -**Pi sınırlaması.** Pi'nin `AgentEndEvent` (Claude'un `Stop` kancasının eşdeğeri), bir Sonuç türü yok — Pi'nin aracı döngüsü çıktığında bu çalışır. Pi, Claude / Copilot / Cursor / Gemini / OpenCode'un yapabildiği şekilde aynı döngüyü yeniden denemek için zorlanamaz. failproofai kapıyı Pi'nin `before_agent_start` olayına kaydırır (sonraki kullanıcı istemi sonra çalışır) böylece iş akışı kontrolü yine uygulanır, sadece geçerli değil sonraki dönüş üzerinde. +**Pi sınırlaması.** Pi'nin `AgentEndEvent` (Claude'un `Stop` hook'unun yukarı akış eşdeğeri) hiçbir Result türü yoktur — Pi'nin ajan döngüsü zaten çıkmış olduğu süredir. Pi, Claude / Copilot / Cursor / Gemini / OpenCode'un yapabildiği şekilde aynı döngüyü yeniden denemeye zorlanamazı. failproofai kapıyı Pi'nin `before_agent_start` olayına kaydırır (sonraki kullanıcı iletişim sonrasında devreye girer) — iş akışı kontrolü hala uygulanır, yalnızca mevcut sıra yerine sonraki sıra üzerinde. -**Pratik olarak bunun anlamı:** +**Bunu pratikte ne anlama gelir:** -- Pi durduğunda, ret nedeni Pi oturum kimliğine göre bellek içinde yakalanır. Aynı Pi sürecinde gönderdiğiniz çok sonraki istem bunu boşaltır: LLM sistem isteminin üstünde `MANDATORY ACTION REQUIRED` yönergesi görür, taahhüt eder (veya iter / PR açar / CI'nin bitmesini bekler) ve sonra istediğiniz şeyler ile devam eder. Yakalanan ret nedeni tek çekişli — boşaltıldıktan sonra kapı temizlenir. -- Kapı Pi'nin süreç yaşam döngüsüne bağlıdır. Pi'yi `Ctrl+C` yaparsanız veya sırasında çıkarsanız, bellek içi giriş süreçle birlikte bırakılır ve kapı kaçırılır. Claude, Copilot, Cursor, Gemini ve OpenCode'un aynı bağlı durumu vardır (aracıyı öldür ve kapı kaçırıldı) — Pi sadece onu daha görünür kılar çünkü aracı kapı çalışmadan önce görünür şekilde çıkar. -- Bekleyen bir ret de herhangi bir nedenden `session_shutdown` üzerinde temizlenir (`new` / `resume` / `fork` / `quit`), bu nedenle aynı Pi sürecinde başlatılan yeni bir oturuma adli bir oturumdan kalmış bir kapı sızmaması. +- Pi durundan sonra, reddetme nedeni oturum kimliği tarafından bellek içinde anahtarlanmış şekilde yakalanır. Aynı Pi işlemi içinde gönderdiğiniz çok sonraki istişare bunu boşaltır: LLM sistem komutunun üstünde `MANDATORY ACTION REQUIRED` yönergesini görür, commits (veya pushes / açıklık PR / CI'yi bekler) ve ancak o zaman istediğiniz şeye devam eder. Yakalanan reddetme nedeni tek atış — bir kez boşaltıldıktan sonra kapı açıktır. +- Kapı Pi'nin işlem ömrü tarafından sınırlandırılır. Turlar arasında Pi'yi `Ctrl+C` yaparsanız veya çıkarsanız, bellek içi giriş işlemle birlikte bırakılır ve kapı kaçırılır. Claude, Copilot, Cursor, Gemini ve OpenCode'un aynı sınırı vardır (ajanı öldürün ve kapı kaçırılır) — Pi sadece bunu daha görünür hale getirir; çünkü ajan kapı devreye girmeden önce görünen şekilde çıkar. +- Beklemede olan bir reddetme herhangi bir nedenle `session_shutdown` üzerine de temizlenir (`new` / `resume` / `fork` / `quit`), bu nedenle önceki oturumdan eski bir kapı, aynı Pi işlemi içinde başlatılan yeni bir oturuma sızamaz. -Claude-stili aynı döngü yeniden denemesine gerek duyarsanız, `Stop` ilkelerinizi diğer altı desteklenen CLI'sinin herhangi biri altında çalıştırın. Pi upstream'ini gelecekteki bir Sonuç türü için `AgentEndEvent` izleyen bir şekilde takip ediyoruz; bu boşluğu kapatmamıza izin verirdi. +Claude tarzı aynı döngü yeniden denemesine ihtiyacınız varsa, `Stop` ilkelerinizi desteklenen diğer altı CLI'den birinin altında çalıştırın. Pi yukarı akışını gelecek bir Result türü ile izliyoruz; `AgentEndEvent` üzerinde bu boşluğu kapatmamıza izin verecektir. ### `require-commit-before-stop` **Olay:** Stop -**Varsayılan:** İşlenmemiş değişiklikler (değiştirilmiş, hazırlanmış veya izlenmeyen dosyalar) olduğunda durmasını reddeder. Çalışma dizini temiz olduğunda bilgilendirici bir mesaj döndürür. +**Varsayılan:** Commit edilmemiş değişiklikler (değiştirilmiş, sahnelenmiş veya izlenmeyen dosyalar) olduğunda durmasını reddeder. Çalışma dizini temiz olduğunda bilgi iletisi döndürür. -Parametre yok. +Parametresi yok. --- ### `require-push-before-stop` **Olay:** Stop -**Varsayılan:** İtilmemiş commits olduğunda veya geçerli dal hiçbir uzak izleme dalına sahip olmadığında durmasını reddeder. Gerektiğinde bir izleme dalı oluşturmak için `git push -u` önerir. Hiçbir uzak yapılandırılmadığında açık olarak başarısız olur. +**Varsayılan:** Push edilmemiş commits olduğunda veya mevcut dal uzaktan izleme dalı olmadığında durmasını reddeder. Gerekirse izleme dalı oluşturmak için `git push -u` önerir. Yapılandırılmış uzaktan yoksa başarısız-açık. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `remote` | `string` | `"origin"` | İtilecek uzak ad. | +| `remote` | `string` | `"origin"` | İtiş yapılacak uzaktan adı. | **Örnek:** @@ -766,13 +765,13 @@ Parametre yok. ### `require-pr-before-stop` **Olay:** Stop -**Varsayılan:** Geçerli dal için hiçbir pull isteği yok olduğunda veya varolan PR birleştirilmeden kapatıldığında durmasını reddeder. Claude'u `gh pr create` ile bir PR oluşturması talimat verir. PR **birleştirildiğinde**, ilke izin verir (çalışma sevk edilmiştir) ve mesaj dal (`git checkout main && git pull`) kapatması için ipucu verir. +**Varsayılan:** Geçerli dal için çekme isteği yoksa veya mevcut PR birleştirilmeden kapatılmışsa durmasını reddeder. Claude'u `gh pr create` ile bir PR oluşturmaya bilgilendirir. PR **birleştirildiğinde**, ilke izin verir (çalışma gönderildi) ve ileti daldan geçmeye ipuç verir (`git checkout main && git pull`). -Parametre yok. +Parametresi yok. -Bu ilke [GitHub CLI](https://cli.github.com/) (`gh`) yüklü ve doğrulanmış olmasını gerektirir. -Pull isteklerine okuma erişimi için `repo` kapsamına sahip bir kişisel erişim belirteci ile `gh auth login` çalıştırın. `gh` yüklü değilse veya doğrulanmazsa, ilke açık olarak başarısız olur ve nedeni Claude'a raporlar. +Bu ilke [GitHub CLI](https://cli.github.com/) (`gh`) kurulu ve doğrulanmış olmasını gerektirir. +Çekme isteklerine okuma erişimi için `repo` kapsamına sahip kişisel erişim belirteci ile `gh auth login` çalıştırın. `gh` kurulu değilse veya doğrulanmamışsa, ilke başarısız-açık ve nedeni Claude'a raporlar. --- @@ -780,21 +779,21 @@ Pull isteklerine okuma erişimi için `repo` kapsamına sahip bir kişisel eriş ### `require-no-conflicts-before-stop` **Olay:** Stop -**Varsayılan:** Geçerli dal temel dala temiz şekilde birleşemediğinde durmasını reddeder. İlke ilk olarak dal için GitHub'da bir `OPEN` PR olduğunu onaylar — bir tane olmadan, birleştirme hedefi olmadığından tüm ilke kısa devre ile izin verir. `OPEN` PR doğrulandıktan sonra, iki bağımsız sonda çalışır: +**Varsayılan:** Geçerli dal temel dala temiz şekilde birleştirilemezse durmasını reddeder. İlke önce dal için GitHub'da `OPEN` bir PR'ın olduğunu onaylar — biri olmadan, birleştirme hedefi yoktur; bu nedenle tüm ilke kısa devre ve izin verir. `OPEN` PR onaylandıktan sonra iki bağımsız sonda çalışır: -1. **Yerel** — `git merge-tree --write-tree --name-only origin/ HEAD`. Çatışmada, ret mesajı çatışan dosyaları adlandırır; bu nedenle Claude tam olarak hangi dosyaları çözeceğini bilir. -2. **GitHub** — `gh pr view --json mergeable,state` sonucunu zaten önceden belirlenmiş şekilde yeniden kullanır. Eski bir yerel `origin/` kaçıracağı çatışmaları yakalar (örn. birisi son alma işlemi `main` üzerinde çatışan bir PR açtığından beri). Bir `CONFLICTING` sonuç reddeder. Bir `UNKNOWN` sonuç da reddeder ve Claude'u ~10 saniye bekletmeye ve durma denemesinden önce yeniden kontrol etmeye talimat verir — bu yanlış negatifleri engeller; GitHub yeniden hesaplarken. +1. **Yerel** — `git merge-tree --write-tree --name-only origin/ HEAD`. Çatışmada, reddetme iletişi çatışmalı dosyaları adlandırır; böylece Claude tam olarak ne çözeceğini bilir. +2. **GitHub** — zaten ön kontrol içinde alınan `gh pr view --json mergeable,state` sonucunu yeniden kullanır. Eski yerel `origin/` kaçıracağı çatışmaları yakalar (örneğin, birisi son getirmeden bu yana `main` üzerinde çatışan bir PR indirdi). `CONFLICTING` sonuç reddeder. `UNKNOWN` sonuç da reddeder ve Claude'u tekrar kontrol etmeden ~10 saniye beklemesini bilgilendirir — durmaya tekrar denemeden önce bu yanlış negatifleri önler. -Atlar tamamen (izin verir): `gh` yüklü değil, dal için PR yok, PR'ın durumu `OPEN` değil (örn. `MERGED`, `CLOSED`) veya `gh pr view` ayrıştırılamaz çıktı döndürdü. Ayrıca açık olarak başarısız olur; `origin/` eksik olduğunda veya temel dışında ileriye gidiş yok — bu Katman 1 geri dönüşleri yine de yeniden konumlandırılan PR birleşebilirliği danışmak önce izin verir. +Şu durumlarda tamamen atlanır (izin verir): `gh` kurulu değil, dal için PR yoktur, PR'ın durumu `OPEN` değildir (örneğin `MERGED`, `CLOSED`) veya `gh pr view` ayrıştırılamayan çıktı döndürür. Ayrıca `origin/` yerel olarak eksik olduğunda veya hiçbir komit tabanın ilerisinde olmadığında da başarısız-açık — bu Katman 1 açılışları yine de izin vermeden önce önbelleğe alınan PR birleştirilebilirliğini danışır. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `baseBranch` | `string` | `"main"` | Çatışmaları kontrol etmek için temel dal. | +| `baseBranch` | `string` | `"main"` | Çatışmalar için kontrol edilmesi gereken temel dal. | -Bu ilke GitHub CLI (`gh`) gerektirir. İlke bir `OPEN` PR olduğunu onaylamak için `gh pr view` kulllanır — `gh` olmadan, ilke kısa devre ile izin verir. `gh auth login` öğesini pull isteklerine okuma erişimi için `repo` kapsamına sahip bir kişisel erişim belirteci ile çalıştırın. +Bu ilke için GitHub CLI (`gh`) gereklidir. İlke bir `OPEN` PR'ın var olduğunu doğrulamak için `gh pr view` kullanır — `gh` olmadan, ilke kısa devre ve izin verir. Çekme isteklerine okuma erişimi için `repo` kapsamına sahip kişisel erişim belirteci ile `gh auth login` çalıştırın. --- @@ -802,13 +801,13 @@ Bu ilke GitHub CLI (`gh`) gerektirir. İlke bir `OPEN` PR olduğunu onaylamak i ### `require-ci-green-before-stop` **Olay:** Stop -**Varsayılan:** CI kontrolleri geçerli dal üzerinde başarısız olduğunda veya çalışırken durmasını reddeder. Hem GitHub Actions iş akışı çalıştırmaları hem de üçüncü taraf bot kontrolleri (örn. CodeRabbit, SonarCloud, Codecov) kontrol eder. `skipped`, `cancelled` ve `neutral` sonuçları başarısız olarak değerlendirir (ikinci işlem örn. Socket Güvenliği dış katkı PR'leri hakkında uyarılar, uygulama kasıtlı olarak başarısız yerine nötr raporları) İzin verdiğinde tüm kontrolleri geçerse bilgilendirici bir mesaj döndürür. +**Varsayılan:** Geçerli daldaki CI kontrolleri başarısız veya hala çalışıyor olduğunda durmasını reddeder. GitHub Actions iş akışı çalıştırmalarını ve üçüncü taraf bot kontrollerini kontrol eder (örneğin CodeRabbit, SonarCloud, Codecov). `skipped`, `cancelled` ve `neutral` sonuçlarını başarısız olmayan olarak işler (sonuncusu örneğin dış katkıda bulunan PR'larında Socket Security uyarılarını kapsar; uygulama kasıtlı olarak başarı/başarısız yerine neutral raporlar). Tüm kontroller geçtiğinde bilgi iletişi döndürür. -Parametre yok. +Parametresi yok. -Bu ilke [GitHub CLI](https://cli.github.com/) (`gh`) yüklü ve doğrulanmış olmasını gerektirir. -`gh auth login` öğesini Actions iş akışı çalıştırmaları ve Kontroller API'sine okuma erişimi için `repo` kapsamına sahip bir kişisel erişim belirteci ile çalıştırın. `gh` yüklü değilse veya doğrulanmazsa, ilke açık olarak başarısız olur ve nedeni Claude'a raporlar. +Bu ilke için [GitHub CLI](https://cli.github.com/) (`gh`) kurulu ve doğrulanmış olması gerekir. +Actions iş akışı çalıştırmalarına ve Kontroller API'sine okuma erişimi için `repo` kapsamına sahip kişisel erişim belirteci ile `gh auth login` çalıştırın. `gh` kurulu değilse veya doğrulanmamışsa, ilke başarısız-açık ve nedeni Claude'a raporlar. --- @@ -817,7 +816,7 @@ Bu ilke [GitHub CLI](https://cli.github.com/) (`gh`) yüklü ve doğrulanmış o ## Bireysel ilkeleri devre dışı bırakma -Yapılandırmanızdaki `enabledPolicies` öğesinden belirli bir ilkeyi kaldırın veya pano'nun İlkeler sekmesinde kapatın. +Yapılandırmanızda `enabledPolicies` öğesinden belirli bir ilkeyi kaldırın veya panonun Politikalar sekmesinde kapatın. ```json { @@ -828,4 +827,4 @@ Yapılandırmanızdaki `enabledPolicies` öğesinden belirli bir ilkeyi kaldır } ``` -`enabledPolicies` öğesinde listelenmemiş ilkeler, `policyParams` girdileri bulunsa bile çalışmaz. \ No newline at end of file +`enabledPolicies` içinde listelenmemiş ilkeler, `policyParams` girdileri var olsa bile çalışmaz. \ No newline at end of file diff --git a/docs/tr/cli/audit.mdx b/docs/tr/cli/audit.mdx index 0fc902b3..3615d41a 100644 --- a/docs/tr/cli/audit.mdx +++ b/docs/tr/cli/audit.mdx @@ -1,19 +1,19 @@ --- -title: Geçmiş oturumları denetleme (beta) -description: "Aracının geçmiş transkriptlerde ne sıklıkta israf edici veya riskli şeyler yaptığını say" +title: Geçmiş oturumları denetle (beta) +description: "Ajanın geçmiş transkriptlerde ne sıklıkla israf veya riskli şeyler yaptığını say" --- **Beta özelliği.** Denetim, erken geri bildirim toplarken beta olarak sunulmaktadır. - Dedektör kataloğu ve rapor biçimi sonraki kararlı sürümden önce değişebilir. - Herhangi bir sorun görürseniz lütfen bir sorun açın. + Dedektör kataloğu ve rapor formatı, bir sonraki kararlı sürümden önce değişebilir. + Herhangi bir şey yanlış görünürse lütfen bir sorun açınız. -Denetim, geçmiş agent-CLI transkriptlerinizi failproofai'nin politika motorundan geçirerek paylaşılabilir bir görsel rapor oluşturur — aracının arketipi, 0–100 puanı ve hangi politikaların tam olarak neyi yakalayacağını **`/audit` dashboard sayfasında** gösterir. +Denetim, geçmiş ajan-CLI transkriptlerinizi failproofai'nin politika motoru üzerinden yeniden oynatır ve **`/audit` kontrol paneli sayfasında** paylaşılabilir, görsel bir rapor oluşturur — ajanınızın arketipi, 0–100 puanı ve tam olarak hangi politikaların neleri yakalayacağını gösterir. ## Çalıştırın -Üç yol — hepsi aynı `/audit` raporuna gider. +Üç giriş yolu — tümü aynı `/audit` raporuna ulaşır. @@ -25,7 +25,7 @@ npx -y failproofai audit failproofai audit ``` -```bash failproofai (dashboard) +```bash failproofai (kontrol paneli) failproofai ``` @@ -33,56 +33,56 @@ failproofai - `npx -y failproofai audit` failproofai'yi getirir, taramayı çalıştırır ve önce hiçbir şey kurmanıza gerek kalmadan dashboard'u açar. + `npx -y failproofai audit` failproofai'yi getirir, taramayı çalıştırır ve kontrol panelini açar — önce herhangi bir şey kurmanıza gerek yok. - - `failproofai audit` taramayı terminalinizde çalıştırır, ardından bittiğinde `localhost:8020/audit` adresini otomatik olarak açar. + + `failproofai audit` taramayı terminalinizde çalıştırır, ardından bittikten sonra otomatik olarak `localhost:8020/audit` sayfasını açar. - - `failproofai` çalıştırın ve navbar'da **Audit** düğmesine tıklayın (Policies ve Projects arasında), veya `/audit` adresini doğrudan açın. + + `failproofai` komutunu çalıştırın ve gezinti çubuğunda (Politikalar ve Projeler arasında) **Audit** seçeneğine tıklayın veya doğrudan `/audit` sayfasını açın. - Kullanımı görmek için `failproofai audit -h` (veya `--help`) komutunu çalıştırın. Denetim **tamamen çevrimdışı** çalışır — hesap veya ağ gerekmez — ve dashboard `Ctrl+C` ile durduruncaya kadar hizmet vermeye devam eder. + Kullanımı görmek için `failproofai audit -h` (veya `--help`) komutunu çalıştırın. Denetim **tamamen çevrimdışı** çalışır — hesap veya ağ gerekmez — ve kontrol paneli `Ctrl+C` ile durdurana kadar sunulmaya devam eder. -Dashboard, bu makinedeki geçmiş agent CLI transkriptlerini tarar (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) ve aracının failproofai'nin durdurması için inşa edilen şeyleri ne sıklıkta yaptığını raporlar — ortam değişkeni kontrolleri, kuvvet itişleri, gereksiz `cd ` önekleri, sleep-polling döngüleri, yeni düzenlenen dosyaları yeniden okuma ve daha fazlası. +Kontrol paneli bu makinedeki geçmiş ajan CLI transkriptlerini tarar (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) ve ajanın failproofai'nin durdurmak için tasarlandığı şeyleri ne sıklıkla yaptığını bildirir — ortam değişkeni kontrolleri, zorla göndermeler, gereksiz `cd ` önekleri, uyku-yoklama döngüleri, yeni düzenlenen dosyaları yeniden okuma ve daha fazlası. -Her transkript için, her araç kullanım olayı 39 yerleşik politika **ve** zaman çalışma politikalarında henüz kapsanmayan desenleri yakalayan 8 salt denetim dedektöründen geçirilir. Sayımlar tüm oturumlar arasında politika / dedektör başına toplanır. +Her transkript için, her araç-kullanım olayı 39 yerleşik politika **ve** henüz çalışma zamanı politikaları tarafından kapsanmayan desenleri yakalayan 8 denetim-yalnızca dedektörü aracılığıyla yeniden oynatılır. Sayılar tüm oturumlar arasında politika / dedektör başına toplanır. -## Ne elde edersiniz +## Neleri elde edersiniz -`/audit` sayfası, tek ekranlı, paylaşılabilir bir **poster** ve ardından katlanmış dört bölümü içerir: +`/audit` sayfası, tek ekranlı, paylaşılabilir bir **poster** ve ardından aşağıya katlanmış dört bölümden oluşur: -1. **Poster** — aracının kimliği bir bakışta: **arketipi** (8'den biri — `iyimser`, `kovboy`, `kaşif`, `balık hafızası`, `paranoid mimar`, `hassas inşaatçı`, `çekiç`, `hayalet`), kişiliği anahtar kelimeler, bu arketipin ne kadar nadir olduğu ve bir kademe grubu (`S` ile `alt kademeye`) bir **0–100 puanı**. Paylaşım için tasarlanmış — X veya LinkedIn'e gönderin veya PNG olarak indirin. -2. **`// strengths`** — aracınızın zaten iyi yaptığı şeyler, taramadan gerçek numaralar olarak (örn. temiz araç çağrısı %, `0` ana dalına itme denemeleri), yalnızca ilgili politika temiz bir kayda sahipse gösterilir. -3. **`// quirks`** — sızan şeyler: failproofai'nin yakalayacağı davranışların sıralanmış tablosu — *son ne zaman* oldu, *ne sızdı* (ve bunu engellemiş olacak yerleşik), *ciddiyeti* ve ne sıklıkta *görüldüğü* (`yeni` / `tekrarlayan` / `N× görüldü`). -4. **`// nasıl geliştirilir`** — önerilen düzeltme listesi: politika başına bir satır kopyala-yapıştır `failproofai policy add ` ile, artı **tümünü kur** düğmesi her öneriyi aynı anda etkinleştiriyor ve yaparsanız **öngörülen puanınızı** gösteriyor. -5. **`// daha iyi geri dön`** — alışkanlığı oluştur: bir denetim yenileme **hatırlatıcısı** (`3d` / `7d` / `14d` / `30d`) ayarla veya şimdi yeniden denetle, ve **bir arkadaşı davet et** kendi denetimini çalıştırmak için (failproof.ai'den gönderilir, Cc siz). Hatırlatıcılar ve davetler oturum açmayı gerektirir — bkz. [`failproofai auth`](/tr/cli/auth). +1. **Poster** — ajanınızın kimliğini bir bakışta: **arketipi** (8'den biri — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), kişi anahtar kelimeleri, o arketipin ne kadar nadir olduğu ve **0–100 puanı** bir kademe bandı (`S`'den `bottom tier`'a kadar). Paylaşılmak için tasarlanmış — X veya LinkedIn'e gönderin veya PNG olarak indirin. +2. **`// strengths`** — ajanınızın zaten iyi yaptıkları, taramadan gerçek sayılar olarak (örn. temiz araç çağrısı %, `0` ana şubaya itme denemesi), yalnızca ilgili politikanın temiz bir kaydı olduğu yerlerde gösterilir. +3. **`// quirks`** — sızan şeyler: failproofai'nin yakalayacağı davranışların sıralı tablosu — *son ne zaman* olduğu, *ne sızdı* (ve onu engelleyecek yerleşik), *ciddiyet* düzeyi ve *ne sıklıkla* görüldüğü (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — önerilen düzeltme listesi: her politika için bir satır, kopyala-yapıştır `failproofai policy add ` ile birlikte, artı tüm önerileri aynı anda etkinleştirip **tahmini puanı** gösteren bir **tümünü yükle** düğmesi. +5. **`// come back better`** — alışkanlığı oluşturun: yeniden denetim e-posta **hatırlatıcısı** ayarlayın (`3d` / `7d` / `14d` / `30d`) veya şimdi yeniden denetim yapın ve kendi denetimini çalıştırması için **bir arkadaşını davet edin** (failproof.ai'den gönderilir, size kcc yapılır). Hatırlatıcılar ve davetler oturum açma gerektirir — [`failproofai auth`](/tr/cli/auth) bölümüne bakınız. -## Salt denetim dedektörleri +## Denetim-yalnızca dedektörler -Bunlar gerçek zamanlı olarak (henüz) uygulanmayan "aptal davranış" desenleri algılar. Bunlar sadece denetim sırasında çalışır ve canlı bir araç çağrısını asla engelleme. +Bunlar gerçek zamanlı olarak (henüz) uygulanmayan "aptal davranış" desenleri algılarlar. Yalnızca denetim sırasında çalışırlar ve canlı bir araç çağrısını hiçbir zaman bloklamaz. -| Dedektör | Neyi sayar | +| Dedektör | Ne saydığı | |---|---| -| `redundant-cd-cwd` | `cd && …` ile başlayan Bash komutları komutlar zaten `cwd` içinde çalışmakta olsa bile. | -| `prefer-edit-over-read-cat` | Tek bir kaynak dosyasında `cat`/`head`/`tail`/`less`/`more` — Read aracını kullanın. | -| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > dosya` yerinde düzenlemeler — Edit aracını kullanın. | -| `prefer-write-over-heredoc` | Heredoc / çok satırlı `echo > dosya` dosyaları yazma — Write aracını kullanın. | -| `sleep-polling-loop` | Uzun `sleep N` (≥ 30s) veya `while …; sleep …; done` polling döngüleri. | -| `find-from-root` | `find /`, `find /home`, `find /usr`, vb. — bunun yerine `cwd` kapsamını belirleyin. | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, kancaları atlayarak. | -| `reread-after-edit` | Aynı oturumda yeni `Edit`/`Write` olan dosyanın `Read`'i. | +| `redundant-cd-cwd` | `cd && …` ile başlayan Bash komutları, komutlar zaten `cwd`'de çalışmakta iken. | +| `prefer-edit-over-read-cat` | Tek bir kaynak dosyada `cat`/`head`/`tail`/`less`/`more` — `Read` aracını kullanın. | +| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` yerinde düzenlemeler — `Edit` aracını kullanın. | +| `prefer-write-over-heredoc` | Heredoc / çok satırlı `echo > file` dosya yazmaları — `Write` aracını kullanın. | +| `sleep-polling-loop` | Uzun `sleep N` (≥ 30s) veya `while …; sleep …; done` yoklama döngüleri. | +| `find-from-root` | `find /`, `find /home`, `find /usr`, vb. — bunun yerine `cwd` kapsamında yapın. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, kancaları atlama. | +| `reread-after-edit` | Aynı oturumda yeni düzenlenen veya yazılan bir dosyanın `Read` işlemi. | ## Önbellekler -- **Transkript başına önbellek** `~/.failproofai/cache/audit/.json` adresinde `(mtime, size, engineVersion, detectorVersion)` ile anahtarlanmış — transkript veya politika/dedektör kodu değiştiğinde otomatik olarak geçersiz kılınır. Her giriş ayrıca **TTL meta verileri** olarak bir `cachedAt` zaman damgası depolar (önbellek anahtarının parçası değil); **7 günden** daha eski girdiler okunurken reddedilir, böylece uzun ömürlü sonuçlar gelişen dedektör niyetinin ötesine geçmez. -- **Tüm sonuç önbelleği** `~/.failproofai/audit-dashboard.json` adresinde (mod 0600). Dashboard'un gezinme sırasında anında oluşturulmasını sağlar, yeniden çalıştırmaya gerek kalmaz. Ayrıca **7 günlük TTL** geçtikten sonra okunurken reddedilir — `/audit` daha sonra boş durumuna geri döner ve taze bir çalıştırmayı ister. Raporu öğelerinin yanında `[ şimdi yeniden denetle ]` düğmesine tıklayarak yenilemek için — yeniden denetim `noCache: true` gönderir, böylece transkript başına önbelleği atlar ve önbelleğe alınan sonucu dönüştürmek yerine her transkripti yeniden tarar; çalıştırma ilerlemek için yapışkan üst şerit aracılığıyla akıntı gösterir ve başarı sırasında sonucu yerinde değiştirir (sayfa yükleme yok; başarısız yeniden denetim önceki raporu tutar). +- **Transkript başına önbellek** `~/.failproofai/cache/audit/.json` dosyasında `(mtime, size, engineVersion, detectorVersion)` anahtarı ile — transkript veya politika/dedektör kodu değiştiğinde otomatik olarak geçersiz kılınır. Her giriş ayrıca **TTL meta verisi** olarak bir `cachedAt` zaman damgası depolar (önbellek anahtarının bir parçası değil); **7 günden** eski olan girişler okunurken reddedilir, böylece uzun ömürlü sonuçlar değişen dedektör niyetinden daha uzun ömürlü olmaz. +- **Tam sonuç önbelleği** `~/.failproofai/audit-dashboard.json` dosyasında (mod 0600). Kontrol panelinin yeniden çalıştırmadan gezintide anında işlenmesini sağlar. **7 günlük TTL**'den sonra da okunurken reddedilir — `/audit` boş durumuna düşer ve yeni bir çalışma istenir. Raporu sonuna yakın yeniden denetlemek için `[ re-audit now ]` öğesine tıklayın — yeniden denetim `noCache: true` gönderir, böylece transkript başına önbelleği atlar ve önbelleğe alınan sonucu döndürmek yerine her transkripti yeniden tarar; çalışma ilerlemeyi yapışkan bir üst şerit aracılığıyla akışa sokar ve başarılı durumda sonucu yerinde değiştirir (sayfa yeniden yüklenmesi yok; başarısız yeniden denetim önceki raporu tutar). ## Notlar -- **Mutation yok.** Denetim salt okunur modda oynatılır. `warn-repeated-tool-calls` atlanır, çünkü oturum başına yan arabası aksi takdirde değiştirilir. -- **İş akışı politikaları atlanmış.** `require-*-before-stop` politikaları sadece `Stop` olaylarında ve canlı git durumuna karşı `execSync` ateşlenir — "2025'te ne olurdu" gibi anlamlı bir yorumu yoktur, bu nedenle denetim sayımlarında görünmezler. -- **Özel politikalar atlanmış.** Kullanıcı tarafından sağlanan özel kancalar yeniden oynatılmaz (orijinal oturum bu yana değişmiş olabilirler). \ No newline at end of file +- **Mutasyon yok.** Denetim salt okunur modda yeniden oynatılır. `warn-repeated-tool-calls`, oturum başına yan taraf arabası aksi halde değiştirileceği için atlanır. +- **İş akışı politikaları atlanır.** `require-*-before-stop` politikaları yalnızca `Stop` olaylarında ve canlı git durumuna karşı `execSync`'te devreye girer — "2025'te ne olurdu" yorumunun anlamı yoktur, bu nedenle denetim sayılarında görünmezler. +- **Özel politikalar atlanır.** Kullanıcı tarafından sağlanan özel kancalar yeniden oynatılmaz (bunlar orijinal oturumdan bu yana değişmiş olabilir). \ No newline at end of file diff --git a/docs/tr/cli/auth.mdx b/docs/tr/cli/auth.mdx index 830c2ec5..a8dd2de8 100644 --- a/docs/tr/cli/auth.mdx +++ b/docs/tr/cli/auth.mdx @@ -1,6 +1,7 @@ --- +--- title: Oturum aç -description: "FailproofAI'ye CLI'dan oturum açarak anımsatıcıları ve kişiselleştirilmiş özellikleri etkinleştirin" +description: "FailproofAI'da CLI üzerinden oturum açarak hatırlatıcıları ve kişiselleştirilmiş özellikleri etkinleştirin" --- ```bash @@ -9,9 +10,9 @@ failproofai auth logout # revoke this session failproofai auth whoami # print the signed-in identity ``` -Eski `--login` / `--logout` / `--whoami` bayrak biçimi hâlâ geriye uyumluluk için takma ad olarak kabul edilmektedir. +Eski `--login` / `--logout` / `--whoami` bayrak formu hala geriye dönük uyumluluk için takma ad olarak kabul edilmektedir. -Kimlik doğrulama isteğe bağlıdır. İlkeler, gösterge paneli, `/audit` sayfası ve diğer tüm yerel özellikler oturum açmış olsanız da olmasanız da tamamen aynı şekilde çalışır. Oturum açma sayfası, **gerektiğinde** sabit bir kimlik gerektiren özelliklerin (bugün yeniden denetim anımsatıcıları, gelecekte daha fazlası) bir tutturacak noktasına sahip olması için mevcuttur. +Kimlik doğrulama isteğe bağlıdır. İlkeler, gösterge paneli, `/audit` sayfası ve diğer tüm yerel özellikler, oturum açmış olmanız veya olmamanız fark etmeksizin tamamen aynı şekilde çalışır. Oturum açma yüzeyi, **sabit bir kimliğe ihtiyaç duyan** özellikler (bugün yeniden denetim hatırlatıcıları, gelecekte daha fazlası) için bir bağlantı noktası sağlamak amacıyla mevcuttur. ## Oturum açma akışı @@ -19,17 +20,17 @@ Kimlik doğrulama isteğe bağlıdır. İlkeler, gösterge paneli, `/audit` sayf failproofai auth login ``` -E-posta adresinizi istenir, bu adrese 6 haneli tek kullanımlık bir kod gönderilir, kod için istenir ve başarı durumunda `~/.failproofai/auth.json` dosyasını yazar (`0600` modu). Aynı oturum daha sonra uygulama içi gösterge panelinde görünür — `/audit` sayfasında `[ set a reminder ]` düğmesine tıklamak sizi oturum açmış olarak gösterir. +E-posta adresinizi sorar, o adrese 6 haneli bir kerelik kod gönderir, kodu ister ve başarılı olduğunda `~/.failproofai/auth.json` dosyasını yazar (`0600` modu). Aynı oturum daha sonra uygulama içi gösterge panelinde görülebilir — `/audit` sayfasında `[ set a reminder ]` öğesine tıklamak sizi oturum açmış olarak görecektir. -Gösterge paneli, CLI'ya hiç dokunmayan kullanıcılar için `/audit` sayfasında bu akışı modal diyalog olarak sunar. +Gösterge paneli, CLI'ye hiç dokunmayan kullanıcılar için `/audit` sayfasında modal bir diyalog olarak aynı akışı gösterir. -## Oturum kapatma +## Oturumu kapatma ```bash failproofai auth logout ``` -Geçerli oturumu sunucuda iptal eder ve `~/.failproofai/auth.json` dosyasını siler. API sunucusuna ulaşılamazsa, yerel dosya yine de kaldırılır — yerel olarak oturum kapatma niyeti her zaman öncelik alır. +Sunucudaki mevcut oturumu iptal eder ve `~/.failproofai/auth.json` dosyasını siler. API sunucusuna ulaşılamıyorsa, yerel dosya yine de kaldırılır — yerel oturum kapatma niyeti her zaman öncelik alır. ## Kimlik kontrolü @@ -37,11 +38,11 @@ Geçerli oturumu sunucuda iptal eder ve `~/.failproofai/auth.json` dosyasını s failproofai auth whoami ``` -Geçerli bir oturum olduğunda ` ()` yazdırır ve 0 ile çıkar, aksi takdirde `not signed in` yazdırır ve 1 ile çıkar. Erişim belirteci sona ermeye 1 dakika kalmışsa arka planda sessizce yeniler. +Geçerli bir oturum varsa ` ()` öğesini yazdırır ve çıkış kodu 0 ile sonlandırır veya aksi takdirde `not signed in` öğesini yazdırır ve çıkış kodu 1 ile sonlandırır. Süresi dolmaya bir dakika kala arka planda erişim belirtecini sessizce yeniler. -## Kalıcı yeniden denetim anımsatıcısı +## Kalıcı yeniden denetim hatırlatıcısı -`/audit` sayfasında **`[ set a reminder ]`** düğmesine tıkladığınızda (veya düğmenin kapılarından geçerek modal aracılığıyla oturum açtığınızda), gösterge paneli `~/.failproofai/next-audit.json` konumunda küçük bir yardımcı dosya yazar: +`/audit` sayfasında **`[ set a reminder ]`** öğesine tıkladığınızda (veya düğmenin kapısı açan modal aracılığıyla oturum açtığınızda), gösterge paneli `~/.failproofai/next-audit.json` konumunda küçük bir yardımcı dosya yazar: ```json { @@ -51,11 +52,11 @@ Geçerli bir oturum olduğunda ` ()` yazdırır ve 0 ile çık } ``` -Bu dosya, ayarlandığı e-posta adresine kapsamlıdır — CLI oturumunu farklı bir hesaba değiştirmek, önceki kullanıcıya ait herhangi bir anımsatıcıyı gizler. Varsayılan fark **7 gündür**, zamanlayıcı geldiğinde daha sonra yapılandırılabilir. `auth.json` gibi `0600` izinleriyle oluşturulur. +Bu dosya, kendisinin ayarlandığı e-posta adresiyle sınırlandırılmıştır — CLI oturumunu farklı bir hesaba değiştirmek, önceki kullanıcıya ait olan herhangi bir hatırlatıcıyı gizler. Varsayılan offset **7 gündür** ve zamanlayıcı kullanıma sunulduğunda yapılandırılabilir. `auth.json` gibi `0600` izinleriyle oluşturulur. -Gösterge panelinin `/api/auth/reminder` uç noktası `GET` (oku), `POST` (ayarla / yeniden zamanla) ve `DELETE` (temizle) işlemlerini sunar ve etkin bir oturum gerektirir. +Gösterge panelinin `/api/auth/reminder` uç noktası `GET` (oku), `POST` (ayarla / yeniden zamanla) ve `DELETE` (temizle) işlemlerini açığa çıkarır ve etkin bir oturum gerektirir. -## `~/.failproofai/auth.json` dosyasında neler var +## `~/.failproofai/auth.json` içinde neler var ```json { @@ -67,21 +68,21 @@ Gösterge panelinin `/api/auth/reminder` uç noktası `GET` (oku), `POST` (ayarl } ``` -`0600` izinleriyle oluşturulur (yalnızca sahibi okuma/yazma). Erişim belirteci 1 saatlik HS256 JWT'sidir; yenileme belirteci, sunucunun `SHA-256(token)` olarak depoladığı opak 256 bit rastgele bir dizedir. Yenileme belirteci tekrarı sunucu tarafında algılanır ve kullanıcı için tüm oturumları iptal eder. +`0600` izinleriyle oluşturulur (yalnızca sahibin okuma/yazma erişimi). Erişim belirteci 1 saatlik bir HS256 JWT'dir; yenileme belirteci, sunucunun `SHA-256(token)` olarak depoladığı opak bir 256 bitlik rastgele dizedir. Yenileme belirteci yeniden oynatması sunucu tarafında algılanır ve kullanıcı için her oturumu iptal eder. ## Ortam değişkenleri | Değişken | Varsayılan | Amaç | |---|---|---| -| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | API sunucusu temel URL'sini geçersiz kılın. Kendi barındırılan API sunucusuna karşı yerel geliştirme için yararlıdır. | -| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | `auth.json` dosyasının saklandığı konumu geçersiz kılın. Çoğunlukla testler için. | +| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | API sunucusu temel URL'sini geçersiz kılın. Kendi kendini barındıran bir API sunucusu üzerinde yerel geliştirme için kullanışlıdır. | +| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | `auth.json` dosyasının depolandığı yeri geçersiz kılın. Çoğunlukla testler için. | -Tam listeyi [Ortam değişkenleri](/tr/cli/environment-variables) bölümünde görmek için. +Tam liste için [Ortam değişkenleri](/tr/cli/environment-variables) bölümüne bakın. ## Sorun giderme -**"Could not reach the api-server"** — CLI, `FAILPROOF_API_URL` adresine TCP bağlantısı açamıyor. Ağ bağlantınızı kontrol edin veya kendi barındırılan API sunucusu çalıştırıyorsanız `FAILPROOF_API_URL` ayarlayın. +**"Could not reach the api-server"** — CLI, `FAILPROOF_API_URL` adresine TCP bağlantısı açamıyor. Ağınızı kontrol edin veya kendi kendini barındıran bir API sunucusu çalıştırıyorsanız `FAILPROOF_API_URL` değerini ayarlayın. -**"Rate limited"** — o e-posta adresi için 15 dakikalık bir pencere içinde çok fazla oturum açma denemesi (5/e-posta) veya IP (20/IP), ya da önceki istek sonrasında aynı e-posta için 30 saniyelik yeniden gönderme bekleme süresi. Hata iletisi, yeniden deneme süresini saniye cinsinden içerir. +**"Rate limited"** — o e-posta için 15 dakikalık bir pencerede çok fazla oturum açma denemesi (5/e-posta) veya IP (20/IP) veya aynı e-posta için önceki istekten sonra 30 saniyelik yeniden gönderme bekleme süresi. Hata mesajı, yeniden deneme-sonrası penceresini saniye cinsinden içerir. -**Code rejected** — OTP yanlış, süresi dolmuş veya satır 5 yanlış tahminde kilitlenmiş. Yeni bir kod istemek için `failproofai auth login` komutunu çalıştırın. \ No newline at end of file +**Code rejected** — OTP yanlış, süresi dolmuş veya satır 5 yanlış tahminin kilitlenmesine ulaştı. Yeni bir kod talep etmek için `failproofai auth login` öğesini tekrar çalıştırın. \ No newline at end of file diff --git a/docs/tr/cli/dashboard.mdx b/docs/tr/cli/dashboard.mdx index 82b40468..428c1215 100644 --- a/docs/tr/cli/dashboard.mdx +++ b/docs/tr/cli/dashboard.mdx @@ -1,6 +1,6 @@ --- title: Oturumları görüntüle -description: "Aracı oturumlarını taramak ve politikaları yönetmek için panoyu başlatın" +description: "Aracı oturumlarına göz atmak ve politikaları yönetmek için panoyu başlatın" --- ```bash @@ -14,16 +14,16 @@ Web panosunu `http://localhost:8020` adresinde başlatır. | Bayrak | Açıklama | |------|-------------| | `--port ` | Dinlenecek port (varsayılan: `8020`) | -| `--allowed-origins ` | Dev kaynaklarına erişim izni verilen virgülle ayrılmış hostlar/IP'ler | +| `--allowed-origins ` | Dev kaynaklarına erişime izin verilen virgülle ayrılmış ana bilgisayarlar/IP'ler | Panoyu varsayılan olmayan bir Claude proje klasörüne yönlendirmek için başlatırken `CLAUDE_PROJECTS_PATH` ortam değişkenini ayarlayın. ## Örnekler ```bash -# Farklı bir portta başlatın +# Farklı bir portta başlat failproofai --port 9000 -# Ortam değişkeni aracılığıyla özel bir Claude projeleri yolunu kullanın +# Ortam değişkeni aracılığıyla özel bir Claude projeleri yolunu kullan CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/tr/cli/environment-variables.mdx b/docs/tr/cli/environment-variables.mdx index 82aec946..c8a59fb8 100644 --- a/docs/tr/cli/environment-variables.mdx +++ b/docs/tr/cli/environment-variables.mdx @@ -6,42 +6,42 @@ description: "failproofai davranışını ortam değişkenleriyle yapılandırı ## Dashboard | Değişken | Açıklama | -|----------|---------| +|----------|----------| | `PORT` | Dashboard portu (varsayılan: `8020`) | -| `CLAUDE_PROJECTS_PATH` | Claude Code proje klasörlerinin bulunduğu konumu geçersiz kılın | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Gizlenecek dashboard sayfaları (virgülle ayrılmış) | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Geliştirme kaynaklarına erişim izni verilen hostlar/IP'ler. `--allowed-origins` ile aynı. | +| `CLAUDE_PROJECTS_PATH` | Claude Code proje klasörlerinin bulunduğu konumu geçersiz kıl | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Gizlenecek dashboard sayfalarının virgülle ayrılmış listesi | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Dev kaynaklara erişim izni verilen hostlar/IP'ler. `--allowed-origins` ile aynı. | ## Logging | Değişken | Açıklama | -|----------|---------| -| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Sunucu günlük seviyesi (varsayılan: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | Özel hook günlük dosyası yolu veya varsayılan için `true` (`~/.failproofai/logs/hooks.log`) | +|----------|----------| +| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Sunucu log seviyesi (varsayılan: `warn`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | Özel hook log dosyası yolu veya varsayılan için `true` (`~/.failproofai/logs/hooks.log`) | -## Telemetri +## Telemetry | Değişken | Açıklama | -|----------|---------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Anonim kullanım telemetrisini devre dışı bırakın | +|----------|----------| +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Anonim kullanım telemetrisini devre dışı bırak | -## Kimlik Doğrulama +## Authentication | Değişken | Açıklama | -|----------|---------| -| `FAILPROOF_API_URL` | `failproofai auth` ve dashboard kimlik doğrulama iletişim kutusu tarafından kullanılan api-server temel URL'sini geçersiz kılın. Varsayılan olarak `https://api.befailproof.ai` değerine ayarlanır; yerel api-server çalıştırırken `http://localhost:8080` (veya başka bir adres) olarak ayarlayın. | -| `FAILPROOFAI_AUTH_DIR` | `auth.json` dosyasının depolandığı konumu geçersiz kılın (varsayılan: `~/.failproofai`). Çoğunlukla izole testler için kullanışlıdır. | +|----------|----------| +| `FAILPROOF_API_URL` | `failproofai auth` ve dashboard auth iletişim kutusu tarafından kullanılan api-server temel URL'sini geçersiz kıl. Varsayılan `https://api.befailproof.ai`; yerel api-server çalıştırırken `http://localhost:8080` (veya başka bir adres) olarak ayarla. | +| `FAILPROOFAI_AUTH_DIR` | `auth.json` dosyasının depolandığı konumu geçersiz kıl (varsayılan: `~/.failproofai`). Çoğunlukla izole testler için yararlı. | ## İlk çalıştırma istemi | Değişken | Açıklama | -|----------|---------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | İlk bare `failproofai` çağrısında politikaları yüklemeyi teklif eden istemi atlayın | +|----------|----------| +| `FAILPROOFAI_NO_FIRST_RUN=1` | İlk bare `failproofai` çağrısında politikaları yüklemeyi teklif eden istemi atla | ## LLM (politika değerlendirmesi için) | Değişken | Açıklama | -|----------|---------| +|----------|----------| | `FAILPROOFAI_LLM_BASE_URL` | LLM API uç noktası (varsayılan: `https://api.openai.com/v1`) | | `FAILPROOFAI_LLM_API_KEY` | LLM destekli politikalar için API anahtarı | | `FAILPROOFAI_LLM_MODEL` | Model adı (varsayılan: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/tr/cli/hook.mdx b/docs/tr/cli/hook.mdx index 91934450..7e31789c 100644 --- a/docs/tr/cli/hook.mdx +++ b/docs/tr/cli/hook.mdx @@ -1,20 +1,15 @@ ---- -title: Hook işleyicisi (iç) -description: "Claude Code'un her araç etkinliğinde çağırdığı alt işlem" ---- - ```bash failproofai --hook ``` Bu, `failproofai policies --install` tarafından Claude Code'un `settings.json` dosyasına kaydedilen komuttur. Normalde bunu doğrudan çağırmazsınız. -stdin'den bir JSON yükü okur, tüm etkinleştirilmiş ilkeleri değerlendirir ve kararı gösteren bir çıkış kodu ile çıkar: +stdin'den bir JSON yükü okur, tüm etkin ilkeleri değerlendirir ve kararı gösteren bir çıkış kodu ile çıkar: | Çıkış kodu | Karar | Etki | |-----------|--------|--------| -| `0` | `allow` | Eyleme izin ver | -| `1` | `deny` | Eylemi engelle - Claude reddetme nedenini görür | +| `0` | `allow` | İşleme izin ver | +| `1` | `deny` | İşlemi engelle - Claude reddetme nedenini görür | | `2` | `instruct` | Claude'un bağlamına rehberlik ekle | ### Desteklenen olay türleri diff --git a/docs/tr/cli/install-policies.mdx b/docs/tr/cli/install-policies.mdx index d0d69aca..58a276e8 100644 --- a/docs/tr/cli/install-policies.mdx +++ b/docs/tr/cli/install-policies.mdx @@ -1,13 +1,13 @@ --- -title: Politikaları Yükle -description: "Politikaları etkinleştirerek her agent araç çağrısında çalışmasını sağlayın" +title: Politikaları yükle +description: "Politikaları etkinleştirerek her agent araç çağrısında çalışmasını sağla" --- ```bash failproofai policies --install [policy-names...] [options] ``` -failproofai'nin araç çağrılarını kesintiye uğratabilmesi için yüklü agent CLI'nizin (Claude Code, OpenAI Codex veya GitHub Copilot CLI _(beta)_) ayarlar dosyasına hook girişleri yazar. +Yüklü agent CLI'nizin (Claude Code, OpenAI Codex veya GitHub Copilot CLI _(beta)_) ayar dosyasına hook girdileri yazarak failproofai'ın araç çağrılarını engellenmesini sağlar. Takma adlar: `failproofai p -i` @@ -15,43 +15,43 @@ Takma adlar: `failproofai p -i` | Bayrak | Açıklama | |------|-------------| -| `--cli claude\|codex\|copilot` | Yüklenecek Agent CLI'ler; boşlukla ayrılmış (örn. `--cli claude codex copilot`) veya tekrarlı. Yüklü CLI'leri algılamak ve sorulup seçim yapmak için atlayın. | -| `--scope user` | Kullanıcı kapsamı ayarlar dosyasına yükleyin (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Varsayılan. | -| `--scope project` | Proje kapsamı ayarlar dosyasına yükleyin (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | -| `--scope local` | Yalnızca Claude — `/.claude/settings.local.json` dosyasına yükleyin. Codex ve Copilot'un `local` kapsamı yoktur. | +| `--cli claude\|codex\|copilot` | Yüklenecek Agent CLI'ler; boşlukla ayrılmış (örn. `--cli claude codex copilot`) veya tekrarlı. Yüklü CLI'leri otomatik olarak algılamak ve istemek için atlayın. | +| `--scope user` | Kullanıcı kapsamlı ayar dosyasına yükle (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Varsayılan. | +| `--scope project` | Proje kapsamlı ayar dosyasına yükle (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | +| `--scope local` | Yalnızca Claude — `/.claude/settings.local.json` dosyasına yükle. Codex ve Copilot'un `local` kapsamı yoktur. | | `--custom ` / `-c` | Özel hook politikaları içeren JS dosyasının yolu | ## Davranış -- **Politik adı yok** - politika seçimi için etkileşimli bir istem açar -- **Belirli adlar** - bu politikaları etkinleştirir (zaten etkin olan politikalara eklenir) -- **`all`** - tüm kullanılabilir politikaları etkinleştirir +- **Politika adı yok** - politika seçmek için etkileşimli istem açar +- **Belirli adlar** - bu politikaları etkinleştirir (zaten etkinleştirilenler korunur) +- **`all`** - mevcut tüm politikaları etkinleştirir -Yükleme katkı sağlayıcıdır: `--install` komutunu tekrar çalıştırmak yeni politikaları ekler, mevcut olanları kaldırmaz. +Yükleme toplamalıdır: `--install` komutunu yeniden çalıştırmak yeni politikaları ekler, mevcut olanları kaldırmaz. ## Örnekler ```bash -# Tüm varsayılan politikaları global olarak yükleyin (etkileşimli) +# Tüm varsayılan politikaları genel olarak yükle (etkileşimli) failproofai policies --install -# Geçerli proje için belirli politikaları yükleyin +# Geçerli proje için belirli politikaları yükle failproofai policies --install block-sudo sanitize-api-keys --scope project -# Tüm politikaları bir kerede etkinleştirin +# Tüm politikaları aynı anda etkinleştir failproofai policies --install all -# Özel politika dosyasıyla yükleyin +# Özel politika dosyası ile yükle failproofai policies --install --custom ./my-policies.js -# OpenAI Codex için yükleyin (proje kapsamı) +# OpenAI Codex için yükle (proje kapsamı) failproofai policies --install --cli codex --scope project -# GitHub Copilot CLI (beta) için geçerli proje için yükleyin +# GitHub Copilot CLI (beta) için geçerli proje kapsamında yükle failproofai policies --install --cli copilot --scope project -# Üç CLI için de aynı anda yükleyin +# Üç CLI için aynı anda yükle failproofai policies --install --cli claude codex copilot ``` -`--custom ` sağlandığında, dosya hemen doğrulanır - en az bir kez `customPolicies.add()` çağrısı yapmalıdır. Çözümlenmiş yol, `policies-config.json` dosyasında `customPoliciesPath` olarak kaydedilir. \ No newline at end of file +`--custom ` sağlandığında, dosya hemen doğrulanır - en az bir kez `customPolicies.add()` çağrısı yapmalıdır. Çözümlenen yol, `customPoliciesPath` olarak `policies-config.json` dosyasına kaydedilir. \ No newline at end of file diff --git a/docs/tr/cli/list-policies.mdx b/docs/tr/cli/list-policies.mdx index 1bb56e21..b9b2d6d9 100644 --- a/docs/tr/cli/list-policies.mdx +++ b/docs/tr/cli/list-policies.mdx @@ -1,13 +1,13 @@ --- -title: İlkeleri Listele -description: "Hangi ilkelerin etkin olduğunu, parametrelerini ve özel ilkeleri görün" +title: Politikaları listele +description: "Hangi politikaların etkin olduğunu, parametrelerini ve özel politikaları görün" --- ```bash failproofai policies ``` -Tüm ilkeleri, durumlarını, yapılandırılmış parametrelerini ve özel ilkeleri gösterir. +Tüm politikaları durumları, yapılandırılmış parametreleri ve özel politikaları ile gösterir. ## Örnek çıktı @@ -16,16 +16,16 @@ Failproof AI Hook Policies (user) Status Name Description ────── ────────────────────────────────────────────────────────────── - ✓ block-sudo Block sudo commands + ✓ block-sudo Sudo komutlarını engelle allowPatterns: ["sudo systemctl status"] - ✓ block-rm-rf Block recursive deletions - ✗ block-curl-pipe-sh Block curl|bash patterns - ✓ sanitize-api-keys Redact API keys from output + ✓ block-rm-rf Özyinelemeli silmeleri engelle + ✗ block-curl-pipe-sh curl|bash düzenini engelle + ✓ sanitize-api-keys API anahtarlarını çıktıdan kaldır additionalPatterns: [{ regex: "MY_TOKEN_...", label: "..." }] ── Custom Policies (/home/alice/myproject/my-policies.js) ────────────── - ✓ require-jira-ticket Block commits without ticket - ✓ approval-gate Approval gate for destructive ops + ✓ require-jira-ticket Bilet olmayan commit'leri engelle + ✓ approval-gate Yıkıcı işlemler için onay kapısı ``` -`policyParams` içindeki bilinmeyen anahtarlar burada işaretlenir, böylece yazım hatalarını erkenden yakalayabilirsiniz. \ No newline at end of file +`policyParams` içindeki bilinmeyen anahtarlar burada işaretlenir, böylece yazım hatalarını erken yakalayabilirsiniz. \ No newline at end of file diff --git a/docs/tr/cli/remove-policies.mdx b/docs/tr/cli/remove-policies.mdx index c7685055..a3035319 100644 --- a/docs/tr/cli/remove-policies.mdx +++ b/docs/tr/cli/remove-policies.mdx @@ -1,6 +1,6 @@ --- -title: İlkeleri kaldır -description: "Claude Code'un ayarlarından hook girişlerini kaldırın" +title: İlkeleri Kaldır +description: "Claude Code ayarlarından hook girişlerini kaldırın" --- ```bash @@ -15,29 +15,29 @@ Takma adlar: `failproofai p -u` | Bayrak | Açıklama | |------|-------------| -| `--scope user` | Global ayarlardan kaldırır (varsayılan) | -| `--scope project` | Proje ayarlarından kaldırır | -| `--scope local` | Yerel ayarlardan kaldırır | -| `--scope all` | Tüm kapsamlardan aynı anda kaldırır | -| `--custom` / `-c` | Yapılandırmadan `customPoliciesPath` öğesini temizler | +| `--scope user` | Genel ayarlardan kaldırın (varsayılan) | +| `--scope project` | Proje ayarlarından kaldırın | +| `--scope local` | Yerel ayarlardan kaldırın | +| `--scope all` | Tüm kapsamlardan aynı anda kaldırın | +| `--custom` / `-c` | Yapılandırmadan `customPoliciesPath` değerini temizleyin | ## Davranış -- **İlke adı yok** - ayar dosyasından tüm failproofai hook girişlerini kaldırır +- **İlke adı yok** - ayarlar dosyasından tüm failproofai hook girişlerini kaldırır - **Belirli adlar** - bu ilkeleri devre dışı bırakır ancak hook'ları yüklü tutar ## Örnekler ```bash -# Tüm hook'ları global olarak kaldırın +# Tüm hook'ları genel olarak kaldırın failproofai policies --uninstall # Belirli bir ilkeyi devre dışı bırakın (hook'ları yüklü tutar) failproofai policies --uninstall block-sudo -# Hook'ları her kapsamdan kaldırın +# Her kapsamdan hook'ları kaldırın failproofai policies --uninstall --scope all -# Özel ilkeler yolunu temizle +# Özel ilkeler yolunu temizleyin failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/tr/cli/version.mdx b/docs/tr/cli/version.mdx index 28724094..526de10d 100644 --- a/docs/tr/cli/version.mdx +++ b/docs/tr/cli/version.mdx @@ -1,6 +1,6 @@ --- title: Sürümü kontrol et -description: "Kurulu failproofai sürümünü yazdır" +description: "Yüklü failproofai sürümünü yazdır" --- ```bash @@ -9,4 +9,4 @@ failproofai --version failproofai -v ``` -Kurulu sürüm numarasını yazdırır. \ No newline at end of file +Yüklü sürüm numarasını yazdırır. \ No newline at end of file diff --git a/docs/tr/configuration.mdx b/docs/tr/configuration.mdx index 567437b0..245b7f07 100644 --- a/docs/tr/configuration.mdx +++ b/docs/tr/configuration.mdx @@ -1,10 +1,10 @@ --- title: Yapılandırma -description: "Config dosya formatı, üç kapsam sistemi ve birleştirme kuralları" +description: "Yapılandırma dosyası formatı, üç kapsamlı sistem ve birleştirme kuralları" icon: gear --- -failproofai, hangi politikaların aktif olduğunu, davranışları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 - repo'nuzda commit edin ve her geliştirici aynı agent 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, ekibinizle paylaşmak için tasarlanmıştır - bunu repo'nuza kaydedin ve her geliştirici aynı ajan güvenlik ağını alır. --- @@ -13,40 +13,40 @@ failproofai, hangi politikaların aktif olduğunu, davranışlarını ve özel p Üç yapılandırma kapsamı vardır ve öncelik sırasına göre değerlendirilir: | Kapsam | Dosya yolu | Amaç | -|-------|-----------|---------| -| **project** | `.failproofai/policies-config.json` | Repo başına ayarlar, sürüm kontrolüne commit edilir | -| **local** | `.failproofai/policies-config.local.json` | Kişisel repo başına geçersiz kılmalar, gitignore'da | -| **global** | `~/.failproofai/policies-config.json` | Tüm projeler genelinde kullanıcı düzeyinde varsayılanlar | +|--------|-----------|------| +| **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 | -failproofai bir hook olayı aldığında, geçerli çalışma dizini için var olan üç dosyayı da yükler ve birleştirir. +failproofai bir hook olayı aldığında, mevcut çalışma dizini için mevcut olan üç dosyanın tümünü yükler ve birleştirir. ### Birleştirme kuralları -**`enabledPolicies`** - tüm üç kapsamın birleşimi. Herhangi bir seviyede etkinleştirilen bir politika etkindir. +**`enabledPolicies`** - üç kapsamın tümünün birleşimi. Herhangi bir seviyede etkinleştirilen bir politika etkindir. ```text -project: ["block-sudo"] -local: ["block-rm-rf"] -global: ["block-sudo", "sanitize-api-keys"] +proje: ["block-sudo"] +yerel: ["block-rm-rf"] +genel: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← çıkartılmış birleşim +çözüm: ["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. ```text -project: block-sudo → { allowPatterns: ["sudo apt-get update"] } -global: block-sudo → { allowPatterns: ["sudo systemctl status"] } +proje: block-sudo → { allowPatterns: ["sudo apt-get update"] } +genel: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← project kazanır, global yoksayılır +çözüm: { allowPatterns: ["sudo apt-get update"] } ← proje kazanır, genel yok sayılır ``` ```text -project: (block-sudo girişi yok) -local: (block-sudo girişi yok) -global: block-sudo → { allowPatterns: ["sudo systemctl status"] } +proje: (block-sudo girişi yok) +yerel: (block-sudo girişi yok) +genel: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← global'e düşer +çözüm: { allowPatterns: ["sudo systemctl status"] } ← genel'e düşer ``` **`customPoliciesPath`** - bunu tanımlayan ilk kapsam kazanır. @@ -55,7 +55,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global'e düşer --- -## Config dosya formatı +## Yapılandırma dosyası formatı ```json { @@ -102,25 +102,25 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global'e düşer Tür: `string[]` -Etkinleştirilecek politika adlarının listesi. Adlar, `failproofai policies` tarafından gösterilen politika tanımlayıcılarıyla tamamen 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) bölümüne bakın. -`enabledPolicies`'de olmayan politikalar, `policyParams`'da girişleri olsa bile inaktiftir. +`enabledPolicies` içinde olmayan politikalar, `policyParams` içinde girdileri olsa bile etkindir değildir. ### `policyParams` Tür: `Record>` -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) bölümünde mevcut parametrelerini belgeler. +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. -Bir politikanın parametreleri varsa ancak 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 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 bloğu içindeki bilinmeyen anahtarlar hook tetiklendiğinde sessizce yoksayılır ancak `failproofai policies` çalıştırdığınızda uyarı olarak işaretlenir. +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. -#### `hint` (enlemesine) +#### `hint` (çapraz kesme) Tür: `string` (isteğe bağlı) -Bir politika `deny` veya `instruct` döndürdüğünde nedene eklenen bir ileti. Claude'u politikanın kendisini değiştirmeden işlem yapılabilir rehberlik sağlamak için kullanın. +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. Herhangi bir politika türüyle çalışır — yerleşik, özel (`custom/`), proje kuralı (`.failproofai-project/`) veya kullanıcı kuralı (`.failproofai-user/`). @@ -132,7 +132,7 @@ Herhangi bir politika türüyle çalışır — yerleşik, özel (`custom/`), pr }, "block-sudo": { "allowPatterns": ["sudo apt-get"], - "hint": "sudo olmadan apt-get'i doğrudan kullanın." + "hint": "sudo olmadan doğrudan apt-get kullanın." }, "custom/my-policy": { "hint": "Önce kullanıcıdan onay isteyin." @@ -141,34 +141,34 @@ Herhangi bir politika türüyle çalışır — yerleşik, özel (`custom/`), pr } ``` -`block-force-push` reddettiğinde, Claude görür: *"Force-push bloke edilmiş. Bunun yerine yeni bir dal oluşturmayı deneyin."* +`block-force-push` reddettiğinde, Claude şunu görür: *"Zorla itme engellendi. Bunun yerine yeni bir dal oluşturmayı deneyin."* -String olmayan değerler ve boş dizeler sessizce yoksayılır. `hint` ayarlanmamışsa, davranış değişmez (geriye dönük uyumlu). +Dize olmayan değerler ve boş dizeler sessizce yok sayılır. `hint` ayarlanmadıysa, davranış değişmez (geriye dönük 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 depolanmadan önce mutlak olarak çözümlenir). +Ö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). -Dosya her hook olayında yeni yüklenir - önbellekleme yoktur. Yazar ayrıntıları için [Özel Politikalar](/tr/custom-policies) bölümüne bakın. +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. ### Kural tabanlı politikalar -Açık `customPoliciesPath`'a ek olarak, failproofai `.failproofai/policies/` dizinlerinden politika dosyalarını otomatik olarak bulur ve yükler: +Açık `customPoliciesPath`'e ek olarak, failproofai `.failproofai/policies/` dizinlerinden politika dosyalarını otomatik olarak keşfeder ve yükler: -| Seviye | Dizin | Kapsam | -|-------|-----------|-------| +| 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 | -**Dosya eşleştirmesi:** Yalnızca `*policies.{js,mjs,ts}` ile eşleşen dosyalar yüklenir (ör. `security-policies.mjs`, `workflow-policies.js`). Dizindeki diğer dosyalar yoksayılır. +**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. -**Config gerekmez:** Kural politikaları, `policies-config.json`'de girişler gerektirmez. Dosyaları dizine bırakın ve sonraki hook olayında alınırlar. +**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. -**Birleştirme yüklemesi:** Hem proje hem de kullanıcı kural dizinleri taranır. Her iki seviyedeki tüm eşleşen dosyalar yüklenir (`customPoliciesPath`'dan farklı olarak ilk kapsam kazanır). +**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). -Daha fazla ayrıntı ve örnek için [Özel Politikalar](/tr/custom-policies) bölümüne bakın. +Daha fazla ayrıntı ve örnekler için [Özel Politikalar](/tr/custom-policies) bölümüne bakın. ### `llm` @@ -187,21 +187,22 @@ AI çağrıları yapan politikalar için LLM istemci yapılandırması. Çoğu k --- -## CLI'den yapılandırma yönetimi +## CLI'dan yapılandırma yönetimi -`policies --install` ve `policies --uninstall` komutları, agent 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 (hook giriş noktaları) yazarken `policies-config.json`, doğrudan yönettiğiniz dosyadır. İkisi ayrıdır: -- **Agent CLI ayarları** — agent'e her tool kullanımında `failproofai --hook ` çağırmasını söyler: - - **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'in `local` kapsamı yok - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (user), `/.github/hooks/failproofai.json` (project) — Copilot'un `local` kapsamı yok. Hook girişleri Copilot'un OS anahtarlı `bash`/`powershell` komut alanlarını `timeoutSec` ile kullanır; dosya üst düzey `version: 1` işaretiyle taşınır. Copilot CLI desteği **beta**'dır çünkü `events.jsonl` kayıt şemasını (halk dokümanları belirtmiyor) daha fazla gerçek dünya oturumuna karşı doğrulanıyoruz. - - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — Cursor'un `local` kapsamı yok. Hook girişleri Claude biçimli `{type, command, timeout}` formunu kullanır (no `bash`/`powershell` split), ancak Cursor'un [hooks şeması](https://cursor.com/docs/hooks) başına düz bir dizide camelCase olay anahtarları (`preToolUse`, `beforeSubmitPrompt`, …) altında depolanır; dosya üst düzey `version: 1` işaretiyle taşınır. İşleyici `CURSOR_EVENT_MAP` aracılığıyla camelCase → PascalCase'yi normalizedir, böylece mevcut yerleşik politikalar değişmeden ateşlenir. Cursor Agent desteği **beta**'dır çünkü Cursor'un disk üzerindeki transkriptini (genel doklarda belirtilmemiş) daha fazla gerçek kuruluma karşı doğrulanıyoruz. - - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (user), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (project) — OpenCode'un `local` kapsamı yok. Diğer altı CLI'den farklı olarak, OpenCode'un **dış komut hook sistemi yok**: `opencode.json`'daki `plugin: []` dizisi aracılığıyla açıkça kayıtlı işlem içi JS/TS eklentilerini yükler (`.opencode/plugins/` otomatik keşfi, opencode v1.14.33'te eklentilerin **nasıl** yüklediği değildir). Yükleme, failproofai ikilisini subprocess çağıran ve ikilinin Claude biçimli JSON yanıtını eklenti semantiğine çeviren küçük bir oluşturulan eklenti başlığını bırakır: tool olayı deny için `throw new Error()` (tool çağrısını iptal eder), instruct VE `Stop` / `SubagentStop` deny için `client.session.prompt(...)` (deny nedenini sonraki kullanıcı mesajı olarak gönderir — `session.idle` bildirim yalnız olduğu ve bundan atmanın no-op olması nedeniyle tek force-retry kanalı), ve allow için no-op. Başlık, ikili iletişime iletmeden önce hem tool adlarını (lowercase → PascalCase via `OPENCODE_TOOL_MAP`) hem de tool giriş arg anahtarlarını (camelCase → snake_case via `OPENCODE_TOOL_INPUT_MAP` for `Read` / `Write` / `Edit`, ör. `filePath` → `file_path`, `oldString` → `old_string`) normalleştirir, bu nedenle `block-read-outside-cwd`, `block-env-files` ve `block-secrets-write` gibi yol kontrol yerleşikleri OpenCode tool çağrılarında değişmeden ateşlenir. Oturumlar opencode'un `~/.local/share/opencode/opencode.db` adresindeki SQLite DB'sinde yaşar; panonun oturum görüntüleyicisi `opencode db --format json` ve `opencode export ` aracılığıyla okur. OpenCode desteği **beta**'dır çünkü sürümler arasında ve daha fazla gerçek dünya oturumuna karşı davranış doğrulanıyoruz. [OpenCode eklentileri doklara](https://opencode.ai/docs/plugins/) bakın. - - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `/.pi/settings.json` (project) — Pi'nin `local` kapsamı yok. Pi, başlangıçta TypeScript uzantı paketlerini yükler; ayarlar dosyası düz bir dize dizini `{"packages": ["./relative/path", …]}`. failproofai, bundled `pi-extension/` dizinine işaret eden tek packages-array girişini yazar. Uzantı dahili olarak Pi'nin `tool_call` / `user_bash` / `input` / `session_start` olaylarına abone olur ve `failproofai --hook --cli pi` adresine shells; işleyici `PI_EVENT_MAP` aracılığıyla underscore_lower_snake_case → PascalCase'yi normalleştirir, böylece mevcut yerleşik politikalar değişmeden ateşlenir. Tool giriş args de `PI_TOOL_INPUT_MAP` aracılığıyla normalleştirilir (Pi'nin Read / Write / Edit, `file_path` yerine `path` teslim eder; üst düzey anahtarı eşleştirmek `block-env-files` ve `block-secrets-write` ateşine izin verir — `block-read-outside-cwd` zaten `path` geri dönüşüne sahipti). Pi desteği **beta**'dır çünkü Pi'nin uzantı API'si ve oturum günlüğü düzeni kararlı hale gelirken. - - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (user), `/.gemini/settings.json` (project) — Gemini'nin `local` kapsamı yok (failproofai'nin açığa çıkarmadığı `/etc/gemini-cli/settings.json` adresinde bir `system` kapsamını belgeler). Hook girişleri, Claude'un `{type, command, timeout}` formunu, Gemini'nin `{matcher, hooks: [...]}` eşleştirici şemasında `matcher: "*"` ile varsayılan olarak sarmalanmış şekilde kullanır. Olaylar PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); işleyici `GEMINI_EVENT_MAP` aracılığıyla Claude kanonik adlarına eşler. Tool adları snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — işleyici `GEMINI_TOOL_MAP` aracılığıyla normalleştirir, böylece mevcut yerleşik politikalar değişmeden ateşlenir. Politika değerlendiricisi, Gemini'nin düz `{decision: "deny", reason}` şeklini (Gemini'nin "Golden Rule" exit-0 sözleşmesine göre tercih edilen), BeforeAgent / AfterTool / SessionStart üzerinde bağlam enjeksiyonu için `{hookSpecificOutput: {hookEventName, additionalContext}}` ve force-retry semantiği için AfterAgent'de `{decision: "block", reason}` yayar. Gemini CLI desteği **beta**'dır çünkü gerçek dünya kapsamını genişletiyoruz. [Gemini CLI hooks doklarına](https://geminicli.com/docs/hooks/) bakın. -- **`policies-config.json`** — failproofai'ye hangi politikaları değerlendireceğini ve hangi parametrelerle değerlendireceğini söyler (tüm agent CLI'leri arasında paylaşılı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 altı 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. + - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (kullanıcı), `/.gemini/settings.json` (proje) — Gemini yerel kapsamı yok (`/etc/gemini-cli/settings.json` içinde belgelenen bir `system` kapsamı vardır, failproofai bunu göstermez). Hook girdileri Claude'un `{type, command, timeout}` formunu Gemini'nin `{matcher, hooks: [...]}` eşleşme şemasında, varsayılan olarak `matcher: "*"` ile sarılı halde kullanır. Olaylar PascalCase'tir (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); işleyici `GEMINI_EVENT_MAP` aracılığıyla Claude kanonik adlarına eşlenir. Araç adları snake_case'tir (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — işleyici `GEMINI_TOOL_MAP` aracılığıyla kanonikleştirir, böylece mevcut yerleşik politikalar değişmeden çalışır. Politika değerlendirici Gemini'nin düz `{decision: "deny", reason}` şeklini yayar (Gemini'nin "Altın Kural" exit-0 sözleşmesine göre tercih edilen), `{hookSpecificOutput: {hookEventName, additionalContext}}` BeforeAgent / AfterTool / SessionStart'ta bağlam enjeksiyonu için ve AfterAgent'ta `{decision: "block", reason}` zorla yeniden deneme semantiği için. Gemini CLI desteği **beta** durumundadır ve gerçek dünya kapsamsını genişletirken. [Gemini CLI hooks belgeleri](https://geminicli.com/docs/hooks/) başlıklı sayfaya bakın. + - **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 -Belirli bir agent'i hedeflemek için `--cli claude|codex|copilot|cursor|opencode|pi|gemini` geçirin (boşlukla ayrılmış veya herhangi bir alt kümesi için tekrarlanır): +Belirli bir ajanı hedeflemek için `--cli claude|codex|copilot|cursor|opencode|pi|gemini|hermes` geçin (boşlukla ayrılmış veya herhangi bir altküme için tekrarlanan): ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +211,24 @@ 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 gemini --scope project +failproofai policies --install --cli hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` -`--cli` atıldığında, `failproofai` hangi agent CLI'lerinin kurulu olduğunu algılar (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): +`--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 gemini` / `which hermes`): -- **Bir CLI algılandı** — söylemeden bu CLI'yi otomatik seçer. -- **Etkileşimli terminalde birden çok CLI algılandı** — `Detected (N)` bölümüne gruplandırılmış ok tuşu tek seçim istemi gösterir (`Detected (N) aggregate aggregate row + algılanan her CLI) ve `Not installed (M) · install hooks ahead of time` bölümünde her algılanmayan desteklenen CLI'yi ileri yükleme seçeneği olarak listeler (↑↓ taşı, Enter seç, ^C çık). Kaldırma akışı yalnızca Algılanan bölümü gösterir. -- **Etkileşimli olmayan çalıştırmada birden çok CLI algılandı** (CI, TTY yok) — sorulmadan tüm algılanan CLI'ler için kurar. -- **Hiç algılanmadı** — `claude`'a geri döner ve PATH'da agent ikilisinin bulunmadığına dair bir uyarıyla; hook komutu yine de yazılır, böylece bir tane kurduğunuz anda etkinleşir. +- **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. -`policies-config.json`'i istediğiniz zaman doğrudan düzenleyebilirsiniz; değişiklikler yeniden başlatma gerekmeksizin sonraki hook olayında hemen geçerli olur. +`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. --- -## Örnek: takım varsayılanlarıyla proje düzeyinde yapılandırma +## Örnek: takım varsayılanları ile proje düzeyinde yapılandırma -`.failproofai/policies-config.json`'i repo'nuzda commit edin: +`.failproofai/policies-config.json`'u repo'nuza kaydedin: ```json { diff --git a/docs/tr/custom-policies.mdx b/docs/tr/custom-policies.mdx index 3e9aa8f6..e09c69e8 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, sapmaları önleyin, başarısızlıkları algılayın, dış sistemlerle entegre olun" +description: "JavaScript'te kendi ilkelerinizi yazın - kuralları uygulayın, kaymaları engelleyin, arızaları tespit edin, dış sistemlerle entegre olun" icon: code --- -Özel ilkeler, herhangi bir ajan davranışı için kurallar yazmanızı sağlar: proje kurallarını uygulayın, sapmaları önleyin, yıkıcı işlemleri engelleyin, takılı kalan ajanları algılayın 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 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. --- @@ -29,7 +29,7 @@ customPolicies.add({ }); ``` -Kurun: +Yükleyin: ```bash failproofai policies --install --custom ./my-policies.js @@ -39,34 +39,34 @@ failproofai policies --install --custom ./my-policies.js ## Özel ilkeleri yüklemenin iki yolu -### Seçenek 1: Kural tabanlı (önerilen) +### Seçenek 1: Kurala Dayalı (önerilen) -`*policies.{js,mjs,ts}` dosyalarını `.failproofai/policies/` dizinine koyun ve otomatik olarak yüklenir — herhangi bir bayrak veya yapılandırma değişikliğine gerek yoktur. Bu git hook'lar gibi çalışır: dosya koyun, işte olur. +`*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. ``` -# Proje seviyesi — git'e gönderilen, ekip ile paylaşılan +# Proje seviyesi — git'e kaydedilir, takım tarafından paylaşılır .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# Kullanıcı seviyesi — kişisel, tüm projeler için geçerli +# Kullanıcı seviyesi — kişisel, tüm projelere uygulanır ~/.failproofai/policies/my-policies.mjs ``` **Nasıl çalışır:** -- Hem proje hem de kullanıcı dizinleri taranır (birleşim — ilk-başarı-kazanır değil) -- Dosyalar her dizin içinde alfabetik sırayla yüklenir. Sırayı kontrol etmek için `01-`, `02-` ön ekini kullanın +- 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) +- 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 -Kural tabanlı ilkeler, kuruluşunuz için bir kalite standardı oluşturmanın en kolay yoludur. `.failproofai/policies/` dizinini git'e gönderün ve her ekip üyesi otomatik olarak aynı kurallara sahip olur — geliştirici başına kurulum gerekmez. Ekibiniz yeni hata modlarını keşfettikçe, bir ilke ekleyin ve gönderin. Zamanla bunlar, her katkıyla iyileşmeye devam eden canlı bir kalite standardı haline gelir. +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. ### Seçenek 2: Açık dosya yolu ```bash -# Özel ilkeler dosyasıyla kurun +# Özel ilkeler dosyası ile yükleyin failproofai policies --install --custom ./my-policies.js # İlkeler dosyası yolunu değiştirin @@ -76,21 +76,21 @@ failproofai policies --install --custom ./new-policies.js failproofai policies --uninstall --custom ``` -Çözülmüş mutlak yol, `customPoliciesPath` olarak `policies-config.json` içinde depolanır. Dosya her hook olayında yeni yüklenir - olaylar arasında önbellekleme yoktur. +Çö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. ### Her ikisini birlikte kullanma -Kural tabanlı ilkeler ve açık `--custom` dosyası birlikte bulunabilir. Yükleme sırası: +Kurala dayalı ilkeler ve açık `--custom` dosyası bir arada bulunabilir. Yükleme sırası: 1. Açık `customPoliciesPath` dosyası (yapılandırılmışsa) -2. Proje kural tabanlı dosyaları (`{cwd}/.failproofai/policies/`, alfabetik) -3. Kullanıcı kural tabanlı dosyaları (`~/.failproofai/policies/`, alfabetik) +2. Proje kurala dayalı dosyalar (`{cwd}/.failproofai/policies/`, alfabetik) +3. Kullanıcı kurala dayalı dosyalar (`~/.failproofai/policies/`, alfabetik) --- ## API -### İçeri Aktarma +### İçe Aktar ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -103,40 +103,40 @@ Bir ilkeyi kaydeder. Aynı dosyada birden fazla ilke için gerektiği kadar ça ```ts customPolicies.add({ name: string; // gerekli - benzersiz tanımlayıcı - description?: string; // `failproofai policies` çıkışında gösterilir - match?: { events?: HookEventType[] }; // olay türüne göre filtrele; hepsini eşleştirmek için çıkar + 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 fn: (ctx: PolicyContext) => PolicyResult | Promise; }); ``` -### Karar yardımcıları +### Karar Yardımcıları -| İşlev | Etki | Kullanım zamanı | +| İşlev | Efekt | Kullanım zamanı | |----------|--------|----------| -| `allow()` | İşleme sessizce izin ver | İşlem güvenli, mesaj gerekli değil | -| `deny(message)` | İşlemi engelle | Ajan bu işlemi yapmamalı | -| `instruct(message)` | Engellemeden bağlam ekle | Ajana takılı kalmamak için ekstra bağlam ver | +| `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 | -`deny(message)` - mesaj Claude'a `"Blocked by failproofai:"` önekiyle gösterilir. Tek bir `deny`, tüm daha sonraki değerlendirmeleri kısa devre yapar. +`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. -`instruct(message)` - mesaj, geçerli araç çağrısı için Claude'un bağlamına eklenir. Tüm `instruct` mesajları biriktirilir ve birlikte teslim edilir. +`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. -Kod değişikliği yapılmadan herhangi bir `deny` veya `instruct` mesajına `policyParams` içinde bir `hint` alanı ekleyerek ek rehberlik ekleyebilirsiniz — bu özel (`custom/`), proje kural tabanlı (`.failproofai-project/`), ve kullanıcı kural tabanlı (`.failproofai-user/`) ilkeler 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. +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. ### Bilgilendirici izin mesajları -`allow(message)` işleme izin verir **ve** Claude'a bir bilgilendirici mesaj geri gönderir. Mesaj, hook işleyicisinin stdout yanıtında `additionalContext` olarak teslim edilir — `instruct` ile aynı mekanizma kullanılır, ancak anlamsal olarak farklıdır: uyarı değil, bir durum güncellemesidir. +`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. -| İşlev | Etki | Kullanım zamanı | +| İşlev | Efekt | Kullanım zamanı | |----------|--------|----------| -| `allow(message)` | İzin ver ve Claude'a bağlam gönder | Kontrolün geçtiğini onaylayın veya kontrolün neden atlandığını açıklayın | +| `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 | -Kullanım örnekleri: +Kullanım durumları: - **Durum onayları:** `allow("All CI checks passed.")` — Claude'a her şeyin yeşil olduğunu söyler -- **Açık başarısızlık açıklamaları:** `allow("GitHub CLI not installed, skipping CI check.")` — Claude'a kontrolün neden atlandığını söyler böylece tam bağlama sahip olur -- **Birden fazla mesaj birikiyor:** birkaç ilke her biri `allow(message)` döndürürse, tüm mesajlar yeni satırlarla birleştirilir ve birlikte teslim edilir +- **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 ```js customPolicies.add({ @@ -146,7 +146,7 @@ customPolicies.add({ const cwd = ctx.session?.cwd; if (!cwd) return allow("No working directory, skipping branch check."); - // ... şube durumunu kontrol et ... + // ... dal durumunu kontrol et ... if (allPushed) { return allow("Branch is up to date with remote."); } @@ -160,9 +160,9 @@ customPolicies.add({ | Alan | Tür | Açıklama | |-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string \| undefined` | Çağrılan araç (örneğin `"Bash"`, `"Write"`, `"Read"`) | -| `toolInput` | `Record \| undefined` | Aracın giriş parametreleri | -| `payload` | `Record` | Claude Code'dan gelen tam ham olay yükü | +| `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ü | | `session` | `SessionMetadata \| undefined` | Oturum bağlamı (aşağıya bakın) | ### `SessionMetadata` alanları @@ -175,33 +175,33 @@ customPolicies.add({ ### Olay türleri -| Olay | Ne zaman çalışır | `toolInput` içeriği | +| Olay | Ne zaman başlatılır | `toolInput` içerikleri | |------|--------------|----------------------| -| `PreToolUse` | Claude bir araç çalıştırmadan önce | Aracın girişi (örneğin Bash için `{ command: "..." }`) | -| `PostToolUse` | Bir araç tamamlandıktan sonra | Aracın girişi + `tool_result` (çıkış) | -| `Notification` | Claude bir bildirim gönderdiğinde | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hook'lar her zaman `allow()` döndürmelidir, bildirim'leri engelleyemezler | +| `PreToolUse` | Claude bir aracı çalıştırmadan önce | Aracın girdisi (ör. Bash için `{ command: "..." }`) | +| `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ş | --- ## Değerlendirme sırası -İlkeler bu sırayla değerlendirilir: +İlkeler şu sırayla değerlendirilir: 1. Yerleşik ilkeler (tanım sırasında) -2. `customPoliciesPath` dan gelen açık özel ilkeler (`.add()` sırasında) -3. Proje `.failproofai/policies/` den gelen kural tabanlı ilkeler (dosyalar alfabetik, içinde `.add()` sırasında) -4. Kullanıcı `~/.failproofai/policies/` den gelen kural tabanlı ilkeler (dosyalar alfabetik, içinde `.add()` 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ı) -İlk `deny` tüm sonraki ilkeleri kısa devre yapar. Tüm `instruct` mesajları biriktirilir ve birlikte teslim edilir. +İlk `deny` tüm sonraki ilkeleri kısaltır. Tüm `instruct` mesajları birikimlenir ve birlikte teslim edilir. --- -## Geçişli içeri aktarmalar +## Geçişken içe aktarmalar -Özel ilke dosyaları bağıl yollar kullanarak yerel modülleri içeri aktarabilir: +Özel ilke dosyaları göreceli yollar kullanarak yerel modülleri içe aktarabilir: ```js // my-policies.js @@ -218,43 +218,43 @@ customPolicies.add({ }); ``` -Giriş dosyasından ulaşılabilen tüm bağıl içeri aktarmalar çözülür. Bu, `from "failproofai"` içeri 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 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. --- ## Olay türü filtrelemesi -Bir ilkenin ne zaman çalışacağını sınırlamak için `match.events` kullanın: +Bir ilkenin ne zaman başlatılacağını sınırlamak için `match.events` kullanın: ```js customPolicies.add({ name: "require-summary-on-stop", match: { events: ["Stop"] }, fn: async (ctx) => { - // Yalnızca oturum sona erdiğinde çalışır + // Sadece oturum sona erdiğinde başlatılır // ctx.session.transcriptPath tam oturum günlüğünü içerir return allow(); }, }); ``` -Her olay türünde çalışması için `match` tamamen çıkarın. +`match` öğesini tamamen atlayarak her olay türünde başlatılmasını sağlayın. --- -## Hata işleme ve başarısızlık modları +## Hata yönetimi ve arıza modları -Özel ilkeler **açık başarısızlık**: hatalar asla yerleşik ilkeleri engellemeyen veya hook işleyiciyi kıramaz. +Özel ilkeler **açık başarısız olur**: hatalar hiçbir zaman yerleşik ilkeleri engelleme veya hook işleyiciyi çökmez. -| Başarısızlık | Davranış | +| Arıza | Davranış | |---------|----------| -| `customPoliciesPath` ayarlanmamış | Açık özel ilkeler çalışmaz; kural tabanlı ilkeler ve yerleşik olanlar normal devam eder | -| Dosya bulunamadı | Uyarı `~/.failproofai/hook.log` dosyasına kaydedilir; yerleşik olanlar devam eder | -| Söz dizimi/içeri aktarma hatası (açık) | Hata `~/.failproofai/hook.log` dosyasına kaydedilir; açık özel ilkeler atlanır | -| Söz dizimi/içeri aktarma hatası (kural tabanlı) | Hata kaydedilir; bu dosya atlanır, diğer kural tabanlı dosyalar yüklenir | -| `fn` çalışma zamanında hata atarsa | Hata kaydedilir; bu hook `allow` olarak işlenir; diğer hook'lar devam eder | -| `fn` 10 saniyeden daha uzun sürerse | Zaman aşımı kaydedilir; `allow` olarak işlenir | -| Kural tabanlı dizin eksikse | Kural tabanlı ilkeler çalışmaz; hata yok | +| `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 | Özel ilke hatalarını hata ayıklamak için günlük dosyasını izleyin: @@ -272,7 +272,7 @@ tail -f ~/.failproofai/hook.log // my-policies.js import { customPolicies, allow, deny, instruct } from "failproofai"; -// Ajanın secrets/ dizinine yazmasını engelle +// Aracının secrets/ dizinine yazmasını engelleyin customPolicies.add({ name: "block-secrets-dir", description: "Prevent agent from writing to secrets/ directory", @@ -285,7 +285,7 @@ customPolicies.add({ }, }); -// Ajanı takılı tutun: göndermeden önce testleri doğrula +// Aracıyı doğru yolda tutun: taahhüt etmeden önce testleri doğrulayın customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -300,7 +300,7 @@ customPolicies.add({ }, }); -// Dondurma döneminde planlanmamış bağımlılık değişikliklerini önle +// Dondurma döneminde planlanmamış bağımlılık değişikliklerini engelleyin customPolicies.add({ name: "dependency-freeze", description: "Prevent unplanned dependency changes during freeze period", @@ -323,14 +323,14 @@ export { customPolicies }; ## Örnekler -`examples/` dizini hemen çalıştırılabilir ilke dosyaları içerir: +`examples/` dizini çalışmaya hazır ilke dosyalarını içerir: | Dosya | İçerik | |------|----------| -| `examples/policies-basic.js` | Yaygın ajan başarısızlık modlarını kapsayan beş başlangıç ilkesi | -| `examples/policies-advanced/index.js` | Gelişmiş desenler: geçişli içeri aktarmalar, zaman uyumsuz çağrılar, çıkış temizleme, ve oturum sonu hook'ları | -| `examples/convention-policies/security-policies.mjs` | Kural tabanlı güvenlik ilkeleri (.env yazma bloğu, git geçmişi yeniden yazma engelle) | -| `examples/convention-policies/workflow-policies.mjs` | Kural tabanlı iş akışı ilkeleri (test hatırlatıcıları, denetim dosyası yazmaları) | +| `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ı) | ### Açık dosya örneklerini kullanma @@ -338,7 +338,7 @@ export { customPolicies }; failproofai policies --install --custom ./examples/policies-basic.js ``` -### Kural tabanlı örnekleri kullanma +### Kurala dayalı örnekleri kullanma ```bash # Proje seviyesine kopyala @@ -350,4 +350,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -Kurulum komutu gerekmez — dosyalar sonraki hook olayında otomatik olarak alınır. \ No newline at end of file +Yükleme komutu gerekmez — dosyalar bir sonraki hook olayında otomatik olarak alınır. \ No newline at end of file diff --git a/docs/tr/dashboard.mdx b/docs/tr/dashboard.mdx index b0ffe411..6b865387 100644 --- a/docs/tr/dashboard.mdx +++ b/docs/tr/dashboard.mdx @@ -1,14 +1,14 @@ --- -title: Dashboard -description: "Ajan oturumlarını izleyin, araç çağrılarını gözden geçirin ve politikaları yönetin" +title: Pano +description: "Agent oturumlarını izleyin, araç çağrılarını gözden geçirin ve politikaları yönetin" icon: chart-line --- -failproofai dashboard, AI ajan oturumlarınızı izlemek ve politikaları yönetmek için tasarlanmış yerel bir web uygulamasıdır. Ajanlarınız yokken neler yaptığını öğrenin. +failproofai panosu, yapay zeka aracı oturumlarınızı izlemek ve politikaları yönetmek için yerel bir web uygulamasıdır. Aracılarınız sizi yokken neler yaptığını görün. --- -## Dashboard'u başlatma +## Panoyu başlatma ```bash failproofai @@ -16,7 +16,7 @@ failproofai `http://localhost:8020` adresinde açılır. -Dashboard, dosya sisteminden doğrudan okuma yapıyor - Claude Code proje klasörleriniz ve failproofai yapılandırma dosyaları. Hiçbir veri uzak bir servise yazılmıyor. +Pano, dosya sisteminden doğrudan okur — Claude Code proje klasörlerinizi ve failproofai yapılandırma dosyalarınızı. Uzak bir hizmete hiçbir şey yazılmaz. --- @@ -24,11 +24,11 @@ Dashboard, dosya sisteminden doğrudan okuma yapıyor - Claude Code proje klasö ### Projeler -Makinenizde bulunan tüm Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_ ve Gemini CLI _(beta)_ projelerini listeler. Claude projeleri `~/.claude/projects/` adresinden (veya `CLAUDE_PROJECTS_PATH` tarafından belirtilen yoldan) keşfedilir; Codex projeleri `~/.codex/sessions///
/*.jsonl` altındaki her transkripton taranarak ve her oturumun ilk kaydında kaydedilen `cwd` ile gruplandırılarak keşfedilir; Copilot CLI projeleri her `~/.copilot/session-state//workspace.yaml` taranarak keşfedilir (`COPILOT_HOME` aracılığıyla yapılandırılabilir) ve `cwd` alanına göre gruplandırılır; Cursor Agent projeleri `~/.cursor/agent-sessions//` altındaki oturum başına metaveri taranarak keşfedilir (`CURSOR_HOME` aracılığıyla yapılandırılabilir, `conversations/` ve `sessions/` fallback olarak araştırılır) ve `meta.json` / `session.json` / `workspace.yaml` içindeki `cwd` skaları için; OpenCode projeleri `opencode db --format json` aracılığıyla `~/.local/share/opencode/opencode.db` adresindeki SQLite veritabanı sorgulanarak keşfedilir (`session` ve `project` tablolarını okuruz ve `project_id` ile gruplandırırız); Pi projeleri `~/.pi/agent/sessions//_.jsonl` altındaki oturum başına JSONL transkriptleri taranarak keşfedilir (`PI_SESSIONS_DIR` aracılığıyla yapılandırılabilir) ve her oturumun ilk kaydından `cwd` çekilir; Gemini CLI projeleri `~/.gemini/tmp//chats/session--.jsonl` taranarak keşfedilir (`GEMINI_SESSIONS_DIR` aracılığıyla yapılandırılabilir) ve komşu `.project_root` metin işaretçisinden kurallı cwd kurtarılır. Birden fazla CLI tarafından kullanılan bir proje, eşleşen tüm rozetlerle tek bir satır olarak görüntülenir. Belirli bir ajan CLI'ye göre filtrelemek için tablonun üzerindeki **CLI** açılır menüsünü kullanın; URL seçiminizi `?cli=claude|codex|copilot|cursor|opencode|pi|gemini` olarak saklar. +Makinenizde bulunan tüm Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Gemini CLI _(beta)_ ve Hermes projelerini listeler. Claude projeleri `~/.claude/projects/` adresinden keşfedilir (veya `CLAUDE_PROJECTS_PATH` tarafından ayarlanan yol); Codex projeleri `~/.codex/sessions///
/*.jsonl` altındaki her transkripti tarayarak ve her oturumun ilk kaydında kaydedilen `cwd` ye göre gruplandırılarak keşfedilir; Copilot CLI projeleri her `~/.copilot/session-state//workspace.yaml` tarayarak keşfedilir (`COPILOT_HOME` üzerinden yapılandırılabilir) ve `cwd` alanına göre gruplandırılır; Cursor Agent projeleri `~/.cursor/agent-sessions//` altındaki oturum başına meta verileri tarayarak keşfedilir (`CURSOR_HOME` üzerinden yapılandırılabilir, `conversations/` ve `sessions/` geri dönüş olarak problanır) `meta.json` / `session.json` / `workspace.yaml` içindeki `cwd` skaler değeri için; OpenCode projeleri `~/.local/share/opencode/opencode.db` adresindeki SQLite DB'sini `opencode db --format json` üzerinden sorgulayarak keşfedilir (`session` ve `project` tablolarını okuyuz ve `project_id` ye göre gruplandırırız); Pi projeleri `~/.pi/agent/sessions//_.jsonl` altındaki oturum başına JSONL transkriptlerini tarayarak keşfedilir (`PI_SESSIONS_DIR` üzerinden yapılandırılabilir) ve her oturumun ilk kaydından `cwd` yi çekeriz; Gemini CLI projeleri `~/.gemini/tmp//chats/session--.jsonl` tarayarak keşfedilir (`GEMINI_SESSIONS_DIR` üzerinden yapılandırılabilir) ve `.project_root` metin işaretçisinden kanonik cwd'yi kurtarırız; Hermes ağ geçidi oturumları doğrudan `~/.hermes/state.db` (`HERMES_DB_PATH` üzerinden yapılandırılabilir) adresindeki SQLite deposundan okunur ve `source` (Slack/Telegram/cli/cron — ağ geçidi oturumlarının cwd'si yoktur) tarafından `hermes-` projelerine gruplandırılır. Birden çok CLI tarafından kullanılan bir proje, tüm eşleşen rozetleriyle tek bir satır olarak işlenir. Belirli bir aracı CLI'ye 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|gemini|hermes` olarak korur. Her proje şunları gösterir: - Proje adı (klasör yolundan türetilmiş) -- CLI rozetleri — `Claude Code` (turuncu), `OpenAI Codex` (mor), `GitHub Copilot` (mavi), `Cursor Agent` (zümrüt), `OpenCode` (kehribar), `Pi` (pembe) ve/veya `Gemini CLI` (gökyüzü) +- CLI rozeti — `Claude Code` (turuncu), `OpenAI Codex` (mor), `GitHub Copilot` (mavi), `Cursor Agent` (zümrüt), `OpenCode` (kehribar), `Pi` (pembe), `Gemini CLI` (gökyüzü), ve/veya `Hermes` (çivit) - En son oturum etkinliğinin tarihi Oturumlarını görmek için bir projeyi tıklayın. @@ -36,38 +36,38 @@ Oturumlarını görmek için bir projeyi tıklayın. ### Oturumlar Bir proje içindeki tüm oturumları listeler. Her oturum şunları gösterir: -- Oturum kimliği +- Oturum ID'si - Başlangıç ve bitiş zaman damgaları - Araç çağrılarının sayısı -- Hook etkinlik sayısı (harekete geçen politikalar) +- Kancı etkinliği sayısı (tetiklenen politikalar) -Listeyi daraltmak için tarih aralığı filtresini ve oturum kimliği aramasını kullanın. Oturumlar sayfalandırılmıştır. +Listeyi daraltmak için tarih aralığı filtresini ve oturum ID aramasını kullanın. Oturumlar sayfalanır. -Oturum görüntüleyicisini açmak için bir oturumu tıklayın. +Oturum görüntüleyiciyi açmak için bir oturumu tıklayın. ### Oturum görüntüleyici -Oturum görüntüleyici, özerk ajanlar için kilit soruyu yanıtlar: ajan ne yaptı ve doğru yolda kaldı mı? Başlık yanındaki CLI rozeti, oturumun Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi veya Gemini CLI transkripi olup olmadığını gösterir. Oturumda meydana gelen her şeyin bir zaman çizelgesini gösterir: +Oturum görüntüleyici, otonom aracılar için temel soruyu yanıtlar: aracı ne yaptı ve hız tuttu mu? Başlığın yanındaki CLI rozeti, oturumun Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Gemini CLI veya Hermes transkripti olup olmadığını gösterir. Bir oturumda gerçekleşen her şeyin bir zaman çizelgesini gösterir: -- **Mesajlar** - Claude'ın metin yanıtları ve kullanıcı istemleri -- **Araç çağrıları** - Claude'ın çağırdığı her araç, giriş ve çıkışı ile birlikte -- **Politika etkinliği** - Her araç çağrısı için hangi politikaların harekete geçtiği ve hangi kararı döndürdüğü +- **İletiler** - Claude'un metin yanıtları ve kullanıcı istemleri +- **Araç çağrıları** - Claude'un çağırdığı her araç, girişi ve çıktısıyla +- **Politika etkinliği** - Her araç çağrısı için, hangi politikalar tetiklendi ve ne kararı döndürdü -Üstteki istatistik çubuğu, oturum süresi, toplam araç çağrıları ve kanca kararlarının bir özetini (izin ver / reddet / talimat say) gösterir. +Üstteki istatistik çubuğu oturum süresini, toplam araç çağrılarını ve kanca kararlarının bir özetini gösterir (allow / deny / instruct sayıları). -Oturumu dışa aktarmak için **İndirme Günlükleri** düğmesini tıklayın. Claude Code, Codex, Copilot, Cursor, Pi ve Gemini oturumları için orijinal disk üzerindeki JSONL transkripi byte-for-byte alırsınız; OpenCode (oturumları diskte değil SQLite'de yaşayan) için altta yatan `session` / `messages` / `parts` tablolarını yansıtan bir JSON belgesini alırsınız. +Oturumu dışa aktarmak için **İndirme Günlükleri** düğmesini tıklayın. Claude Code, Codex, Copilot, Cursor, Pi ve Gemini oturumları için orijinal disk üzerindeki JSONL transkriptini bayt-bayt alırsınız; OpenCode (oturumları diskte değil SQLite'de yaşayan) için temel `session` / `messages` / `parts` tablolarını yansıtan bir JSON belgesi alırsınız. ### Denetim -Ajan'ın geçmiş oturumlar boyunca gerçekten nasıl davrandığına dair kişilik taşıyan bir rapor. `failproofai audit` CLI ile aynı taramayı çalıştırır ancak bunu tek ekranlı paylaşılabilir bir poster + dört geri planda bölüm olarak gösterir: +Aracınızın geçmiş oturumlar arasında gerçekten nasıl davrandığına dair kişilik odaklı bir rapor. `failproofai audit` CLI ile aynı taramasını çalıştırır ancak bunu tek ekran paylaşılabilir poster + aşağıya katlanmış dört bölüm olarak işler: -1. **Poster** — ilk görünüm alanını doldurur. failproof_ai sözcüğü işareti + denetim etiketi içeren kendi içinde 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` adlarından biri) + 3 anahtar kelime şeridi · `// only N% of agents are this archetype` nadir olma satırı · 8×8 piksel sigil döşeme · `audit yours → failproof.ai` altbilgisi. Yakalama kutusunun hemen dışında üç paylaşma düğmesi bulunur: `post your archetype` (X niyeti), `share on linkedin`, `download poster`. Yakalama `html-to-image` aracılığıyla çalışır, böylece PNG ekran üzerindeki render ile piksel-to-piksel eşleşir (kesikli kenarlıklar, SVG logo maskesi, degradeler, yazı tipi metrikleri — tümü korunur). -2. **Güçlü Yönler** — sakin ✓ satır listeleme, ajanınızın zaten doğru yaptığı davranışlar, canlı denetim verilerinden türetilmiş (temiz araç çağrı oranı, ana dalına doğrudan itme yok, sıfır kimlik bilgisi sızıntısı, sıfır yeniden deneme fırtınası) — her biri yalnızca ilgili politika denetim penceresinde temiz bir kayda sahip olduğunda sunulur. -3. **Tuhaflıklar** — sıkışıp kalıp tablosu, ciddiyete göre sıralandı: `when · what slipped + the policy that would've caught it · severity pill · seen`, yinelenme `new` (bir kez), `N× seen` (2–9 kez) veya `recurring` (10+) olarak okunur. -4. **Nasıl iyileştirilir** — sakin satır listeleme, önerilen her politika için bir tane: politika adı beyaz, tek satırda açıklama, sağ tarafında yükleme komutu + kopyala düğmesi. Bölüm başlığı `enable all N → projected · ` (her bir onarımın uygulanması ile ulaşacağınız puan) olarak okunur ve `[install all]` düğmesi her önerilen politika için birleştirilmiş `failproofai policy add a b c …` komutunu kopyalar. -5. **Daha iyi dön** — yan yana iki kart. Sol: hatırlatıcı ayarla (`3d` / `7d` / `14d` / `30d` kadans seçici; `/api/auth/reminder` aracılığıyla kimlik doğrulandıktan sonra 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-posta listesini (gönderi başına maks. 10) alan ve `POST /v0/invite` adresine POSTlayan bir modal açar. API sunucusu `invite@failproof.ai` adresinden her alıcı için bir e-posta gönderir, gönderici Cc'ye alınır ve `Reply-To` ayarlanır, böylece alıcı onları kimin davet ettiğini ve gönderici gelen kutusunda bir kopya alır. Anonim kullanıcılar, davetler çıkmazdan önce gönderenin e-postası bilinecek şekilde `AuthDialog` aracılığıyla yönlendirilir. Yetkilendirme / avantajlar yerine getirilmesi sonraki adım. +1. **Poster** — ilk görünüm penceresini doldurur. failproof_ai sözcüğü işareti + denetim etiketi ile kendi içinde PNG yakalama bölgesi · arketip indeksi (`№ NN of 08`) + denetim tarihi · sayısal puan (0–100) + yüzdelik sıra hapı (`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` nadir bulunma satırı · 8×8 piksel sigil döşemesi · `audit yours → failproof.ai` alt bilgisi. Üç paylaş düğmesi yakalama kutusunun hemen dışında yer alır: `post your archetype` (X niyeti), `share on linkedin`, `download poster`. Yakalama `html-to-image` üzerinden çalışır, bu nedenle PNG ekranda işlenen görüntüyle piksel-piksel eşleşir (kesik çizgili sınırlar, SVG logo maskesi, degradeler, yazı tipi ölçümleri — hepsi korunur). +2. **Güçlü Yönler** — sakin ✓ satır listeniz, aracınızın zaten doğru yaptığı davranışlardan, canlı denetim verilerinden türetilmiş (temiz araç çağrısı oranı, ana hala doğrudan itilme yok, kimlik bilgisi sızıntısı yok, yeniden deneme fırtınaları yok) — her biri yalnızca ilgili politika denetim penceresi arasında temiz bir kayda sahip olduğunda ortaya çıkar. +3. **Tuhaflıklar** — sızdı, ciddiyet ve sıralanmışlık tablosu: `when · what slipped + the policy that would've caught it · severity pill · seen`, burada yineleme `new` (bir kez), `N× seen` (2–9 kez) veya `recurring` (10+) olarak okunur. +4. **Nasıl iyileştirilir** — sakin satır listesi, önerilen her politika için bir tane: politika adı beyazda, tek satırlı açıklama, yükleme komutu + sağ tarafta kopyala düğmesi. Bölüm başlığı `enable all N → projected · ` (her onarım uygulandıktan sonra ulaşacağınız puan) olarak okunur ve `[install all]` düğmesi önerilen tüm politikalar için birleştirilmiş `failproofai policy add a b c …` komutunu kopyalar. +5. **Daha iyi dön** — yan yana iki kart. Sol: bir anımsatıcı ayarla (`3d` / `7d` / `14d` / `30d` cadence seçici; `/api/auth/reminder` üzerinden kimlik doğrulaması yapıldıktan sonra kalıcıdır). Sağ: failproof avantajlarının kilidini aç — `invite a friend` virgül/boşluk/satır sonu ile ayrılmış bir arkadaş e-posta listesini (gönderme başına maksimum 10) alan ve `/api/audit/invite` adresine POSTlayan bir modal açar, bu da api-sunucusunun `POST /v0/invite` adresine iletir. API sunucusu her alıcıya `invite@failproof.ai` adresinden bir e-posta gönderir, gönderici Cc'd ve `Reply-To` ayarlanmıştır, bu nedenle alıcı kimin kendilerini davet ettiğini görür ve gönderici gelen kutusuna bir kopya alır. Anonim kullanıcılar gönderenin e-postası bilinmeden önce davetler gönderilmeyecek şekilde `AuthDialog` üzerinden yönlendirilir. Hak/avantajlar karşılanması bir takip görevidir. -`failproofai audit` çalışma zamanı tarafından yönlendirilir — altta yatan tarama motoru, desteklenen bayraklar ve transkripsyon başına önbellek değişmezleri için [Denetim CLI](/tr/cli/audit) bölümüne bakın. Dashboard en son sonucu `~/.failproofai/audit-dashboard.json` adresinde önbelleğe alır (`0600` modu, tek yuva, yeni çalıştırmalar üzerine yazar), böylece yeniden ziyaretler anında gerçekleşir; **hem transkripsiyon başına hem de tüm sonuç önbellekleri okunduğunda 7 günden eski olunca reddedilir**, böylece dashboard asla sessizce bir hafta eski sonuç sunmaz — TTL'den sonra `/audit` boş durumuna girer ve taze çalıştırmayı ister. Raporun alt kısmında `[ re-audit now ]` seçeneğini tıklamak `/api/audit/run` adresine `noCache: true` ile POSTler — yeniden denetim transkripsyon başına önbelleği atlar ve sessizce önbelleğe alınan sonucu döndürmek yerine her transkripsyonu baştan yeniden tarar — ve dashboard `/api/audit/status` adresini 1Hz'de yoklar; çalıştırma sırasında görünüm alanının üstüne yapışan pembe bir ilerleme şeridi geçen zamanlayıcı ile sabitlenir ve yeni sonuç başarı üzerine yerinde değiştirilir (tam sayfa yeniden yükleme yok; başarısız yeniden denetim önceki raporu sintact bırakır). Başarısız olduğunda şerit `RerunError.kind` (`timeout` / `network` / `post_failed`) anahtarlanmış kopya ile kırmızıya döner. Boş durum (önbellek yok veya süresi dolmuş) ve sıfır oturum durumu (önbellek var ancak tarama transkripsyon bulamadı) ayrı ayrı sunulur. +`failproofai audit` çalışma zamanı tarafından yönlendirilir — temel tarama motorunu, desteklenen bayrakları ve transkript başına önbellek değişmezlerini [Denetim CLI](/tr/cli/audit) adresinde görün. Pano en son sonucu `~/.failproofai/audit-dashboard.json` adresinde önbelleğe alır (mod `0600`, tek yuva, yeni çalıştırmalar üzerine yazar) böylece yeniden ziyaretler anlıktır; **hem transkript başına hem de bütün sonuç önbellekleri okuma sırasında 7 günden daha eski olduğunda reddedilir**, bu nedenle pano hiçbir zaman sessizce bir hafta eski sonuç sunmaz — TTL geçtikten sonra `/audit` boş durumuna düşer ve taze bir çalıştırma istenir. Raporun alt kısmına yakınında `[ re-audit now ]` öğesini tıklatmak `/api/audit/run` öğesine `noCache: true` ile POSTlar — yeniden denetim transkript başına önbelleği atlar ve her transkripti sessizce yapılan sonucu döndürmek yerine sıfırdan yeniden tarar — ve pano çalıştırma bitene kadar `/api/audit/status` adresini 1Hz'de yoklar; çalıştırma sırasında yapışkan pembe ilerleme şeridi görünüm penceresinin en üstüne sabitlenir ve geçen zamanlı sayaçla birlikte taze sonuç başarıda yerinde değişir (tam sayfa yeniden yüklemesi yok; başarısız yeniden denetim önceki raporu bozulmamış bırakır). Arızada şerit kırmızıya döner ve `RerunError.kind` kapalı kopya (`timeout` / `network` / `post_failed`). Boş durum (önbellek yok veya süresi dolmuş) ve sıfır oturum durumu (önbellek var ama tarama hiçbir transkript bulmadı) ayrı ayrı ortaya çıkarılır. ### Politikalar @@ -75,16 +75,16 @@ Politikaları yönetmek ve etkinliği gözden geçirmek için iki sekmeli bir sa - - Tek bir panelinden failproofai'nin hangi ajan CLI'lerini koruduğunu çoklu seçim yapın — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi ve Gemini CLI'nin her birinin yükleme durumu (`Active` / `Detected` / `Inactive`) satırı, kullanıcı kapsamı ayarları yolu ve marka renginde vurgu vardır. İstediğiniz CLI'leri işaretleyin veya işareti kaldırın ve `Apply changes` düğmesini tıklayarak bir adımda farkı yükleyin/kaldırın. Dosya yolunda ikili tespit edilen CLI'ler önceden işaretlenmiştir. - - Bireysel politikaları tek tıkla açıp kapatın (`~/.failproofai/policies-config.json` adresine yazılır — yüklü her CLI'de paylaşılır) - - Politika parametrelerini yapılandırmak için bir politikayı genişletin (`policyParams` destekleyen politikalar için) - - Özel politikalar dosyası yolunu ayarlayın + - Tek bir panelden hangi aracı CLI'lerin failproofai tarafından korunacağını çoklu seçim yapın — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Gemini CLI ve Hermes'in hepsinin yükleme durumu (`Active` / `Detected` / `Inactive`) olan bir satırı, kullanıcı kapsamı ayarları yolu ve marka renkli vurguyu vardır. İstediğiniz CLI'leri işaretleyin veya işareti kaldırın ve farkı bir adımda yüklemek/kaldırmak için `Apply changes` öğesine tıklayın. İkili PATH'de algılanan CLI'ler önceden işaretlenmiş. + - Tek tıklamayla bireysel politikaları açıp kapatın (`~/.failproofai/policies-config.json` adresine yazar — tüm yüklü CLI'ler arasında paylaşılır) + - Parametrelerini yapılandırmak için bir politikayı genişletin (`policyParams` destekleyen politikalar için) + - Özel politika dosyası yolunu ayarla - - Tüm oturumlar arasında harekete geçen her hook 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)_ / Gemini CLI _(beta)_), 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, gökyüzü = Gemini CLI), araç adı, oturum kimliği ve reddet/talimat kararlarının nedeni - - Oturum kimliğini tıklatarak transkripsyonu açı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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`) ve başlık içinde eşleşen CLI rozetini gösterir + - Tüm oturumlar arasında tetiklenen her kanca olayının tam sayfalı geçmişi + - Karar, olay türü, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Gemini CLI _(beta)_ / Hermes), politika adı veya oturum ID'ye göre filtrele + - 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, gökyüzü = Gemini CLI, çivit = Hermes), araç adı, oturum ID ve deny/instruct kararları için neden + - Transkripti açmak için bir oturum ID'sine tıklayın — görüntüleyici hangi CLI'nin kancayı tetiklediğini otomatik 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`, Hermes `~/.hermes/state.db`) ve başlıkta eşleşen CLI rozetini işler @@ -92,13 +92,13 @@ Politikaları yönetmek ve etkinliği gözden geçirmek için iki sekmeli bir sa ## Otomatik yenileme -Dashboard, üst gezintide otomatik yenileme tuşuna sahiptir. Etkinleştirildiğinde, geçerli sayfa, yeni oturumlar ve politika etkinlikleri göründükçe periyodik olarak yenilenir. Uzun süre çalışan özerk ajan oturumlarını izlemek için gereklidir. +Panonun üst gezinmesinde otomatik yenileme değiştirici vardır. Etkinleştirildiğinde, geçerli sayfa yeni oturumları ve politika etkinliğini göstermek için periyodik olarak yenilenir. Uzun süren otonom aracı oturumlarını izlemek için gereklidir. --- ## Sayfaları devre dışı bırakma -Dashboard'un yalnızca bazı bölümlerine ihtiyacınız varsa, `FAILPROOFAI_DISABLE_PAGES` öğesini virgülle ayrılmış sayfa adları listesine ayarlayın: +Panonun yalnızca bazı parçalarına ihtiyacınız varsa, `FAILPROOFAI_DISABLE_PAGES` öğesini virgülle ayrılmış sayfa adları listesine ayarlayın: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -108,9 +108,9 @@ Geçerli değerler: `policies`, `projects`, `audit`. --- -## Projeler yolunu yapılandırma +## Projeler yolunun yapılandırılması -Varsayılan olarak, dashboard 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,21 +118,21 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Yerel olmayan bir konaktan erişim +## Localhost olmayan bir konaktan erişim -Dashboard'u **geliştirme modu** (`npm run dev`) içinde çalıştırırken ve `localhost` dışında bir ana bilgisayar adından erişirken — örneğin, özel bir etki alanı, uzak IP veya tünel URL — aşağıdaki gibi bir uyarı görebilirsiniz: +Panoyu **geliştirme modunda** (`npm run dev`) çalıştırırken ve `localhost` dışında bir ana bilgisayar adından erişirken — örneğin, özel bir etki alanı, uzak bir IP veya tünel oluşturulmuş bir URL — şö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) websocket'ine yalnızca geliştirme için olan çapraz kaynaklı erişimi engelmesidir. Ana bilgisayarınıza izin vermek için `--allowed-origins` bayrağını kullanın: +Bu, Next.js'nin HMR (sıcak modül yeniden yüklemesi) websocketine çapraz kökenli erişimi engeller, bu da sadece geliştirme özelliğidir. Konağınıza izin vermek için `--allowed-origins` bayrağını kullanın: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -Birden fazla ana bilgisayar veya IP için virgülle ayrılmış bir liste iletin: +Birden çok 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 @@ -145,5 +145,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Bu yalnızca geliştirme modunda uygulanır. `failproofai` çalıştırıldığında (üretim modu), HMR websocket'i ve çapraz kaynaklı geliştirme kaynağı sorunu yoktur. +Bu yalnızca geliştirme modunda geçerlidir. `failproofai` (üretim modu) çalıştırılırken HMR websocket'i ve çapraz kökenli geliştirme kaynağı sorunu yoktur. \ No newline at end of file diff --git a/docs/tr/examples.mdx b/docs/tr/examples.mdx index f4728c9f..a728d94a 100644 --- a/docs/tr/examples.mdx +++ b/docs/tr/examples.mdx @@ -1,71 +1,71 @@ --- title: Örnekler -description: "Claude Code ve Agents SDK için hook'lar nasıl kurulur" +description: "Claude Code ve Agents SDK için kancaları nasıl ayarlanır" icon: book-open --- -Yaygın senaryolar için hazır kullanılabilir örnekler. Her biri kurulumu ve neyi bekleyeceğinizi gösterir. +Yaygın senaryolar için hazır kullanım örnekleri. Her biri nasıl yükleneceğini ve neleri bekleyeceğinizi gösterir. --- -## Claude Code için hook'ları ayarlama +## Claude Code için kancaları ayarlama -Failproof AI, Claude Code ile [hook'lar sistemi](https://docs.anthropic.com/en/docs/claude-code/hooks) aracılığıyla entegre olur. `failproofai policies --install` çalıştırdığınızda, Claude Code'un `settings.json` dosyasında her araç çağrısında tetiklenen hook komutlarını kaydeder. +Failproof AI, Claude Code ile [kanca sistemi](https://docs.anthropic.com/en/docs/claude-code/hooks) üzerinden entegre olur. `failproofai policies --install` komutunu çalıştırdığınızda, Claude Code'un `settings.json` dosyasında her araç çağrısında tetiklenen kanca komutlarını kaydeder. - + ```bash npm install -g failproofai ``` - + ```bash failproofai policies --install ``` - + ```bash cat ~/.claude/settings.json | grep failproofai ``` - `PreToolUse`, `PostToolUse`, `Notification` ve `Stop` etkinlikleri için hook girdilerini görmelisiniz. + `PreToolUse`, `PostToolUse`, `Notification` ve `Stop` olayları için kanca girdilerini görmelisiniz. - + ```bash claude ``` - Politikalar artık her araç çağrısında otomatik olarak çalışır. Claude'dan `sudo rm -rf /` çalıştırmasını istemeyi deneyin - engellenir. + Politikalar artık her araç çağrısında otomatik olarak çalışır. Claude'dan `sudo rm -rf /` çalıştırmasını istemeyi deneyin - engellenecektir. --- -## Agents SDK için hook'ları ayarlama +## Agents SDK için kancaları ayarlama -[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) ile geliştiriyorsanız, aynı hook sistemini programlı bir şekilde kullanabilirsiniz. +[Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) ile geliştiriyorsanız, aynı kanca sistemini programlı olarak kullanabilirsiniz. - + ```bash npm install failproofai ``` - - Aracı işleminizi oluştururken hook komutlarını geçin. Hook'lar Claude Code'daki gibi aynı şekilde çalışır - stdin/stdout JSON aracılığıyla: + + Aracı işlemi oluştururken kanca komutlarını iletin. Kancalar Claude Code'dakiyle aynı şekilde tetiklenir - stdin/stdout JSON aracılığıyla: ```bash failproofai --hook PreToolUse # her araçtan önce çağrılır failproofai --hook PostToolUse # her araçtan sonra çağrılır ``` - + ```javascript import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "limit-to-project-dir", - description: "Aracı proje dizini içinde tutar", + description: "Aracı proje dizini içinde tutun", match: { events: ["PreToolUse"] }, fn: async (ctx) => { const path = String(ctx.toolInput?.file_path ?? ""); @@ -77,7 +77,7 @@ Failproof AI, Claude Code ile [hook'lar sistemi](https://docs.anthropic.com/en/d }); ``` - + ```bash failproofai policies --install --custom ./my-agent-policies.js ``` @@ -88,7 +88,7 @@ Failproof AI, Claude Code ile [hook'lar sistemi](https://docs.anthropic.com/en/d ## Yıkıcı komutları engelle -En yaygın kurulum - aracıların geri döndürülemez hasara neden olmasını önle. +En yaygın kurulum - ajanların geri döndürülemez hasara yol açmasını önle. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh @@ -97,39 +97,39 @@ failproofai policies --install block-sudo block-rm-rf block-force-push block-cur Bunu ne yapar: - `block-sudo` - tüm `sudo` komutlarını engeller - `block-rm-rf` - özyinelemeli dosya silmeyi engeller -- `block-force-push` - `git push --force`'u engeller -- `block-curl-pipe-sh` - uzak komutları shell'e yönlendirmeyi engeller +- `block-force-push` - `git push --force` öğesini engeller +- `block-curl-pipe-sh` - uzaktan betiklerin kabuğa aktarılmasını engeller --- ## Sır sızıntısını önle -Aracıların kimlik bilgilerini görmesini veya araç çıktısında sızdırmasını engelle. +Ajanların araç çıktısında kimlik bilgilerini görmesini veya sızıtmasını engelleyin. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -Bunlar `PostToolUse`'de çalışır - bir araç çalıştıktan sonra, araç çıktısını ajan görmeden temizlerler. +Bunlar `PostToolUse` üzerinde tetiklenir - bir araç çalıştırıldıktan sonra, ajan görmeden önce çıktıyı temizlerler. --- -## Aracılar dikkat gerektirdiğinde Slack uyarıları al +## Ajanlar dikkat gerektirdiğinde Slack uyarıları alın -Bildirimi hook'unu kullanarak boşta bekleme uyarılarını Slack'e yönlendir. +Boş bekleme uyarılarını Slack'e iletmek için bildirim kancasını kullanın. ```javascript import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "slack-on-idle", - description: "Araç girdi için beklerken Slack'e uyarı gönder", + description: "Ajan giriş beklerken Slack'e uyarı gönderin", match: { events: ["Notification"] }, fn: async (ctx) => { const webhookUrl = process.env.SLACK_WEBHOOK_URL; if (!webhookUrl) return allow(); - const message = String(ctx.payload?.message ?? "Araç beklemede"); + const message = String(ctx.payload?.message ?? "Ajan bekliyor"); const project = ctx.session?.cwd ?? "bilinmiyor"; try { @@ -142,7 +142,7 @@ customPolicies.add({ signal: AbortSignal.timeout(5000), }); } catch { - // Slack ulaşılamazsa aracı hiçbir zaman engelleme + // Slack ulaşılamıyorsa ajanı hiçbir zaman bloke etme } return allow(); @@ -150,7 +150,7 @@ customPolicies.add({ }); ``` -Yükle: +Yükleyin: ```bash SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js @@ -158,22 +158,22 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c --- -## Aracıları bir dalda tut +## Ajanları bir dalda tut -Aracıların dal değiştirmesini veya korumalı dallara göndermesini önle. +Ajanların dalları değiştirmesini veya korumalı dallara gitmesini önleyin. ```javascript import { customPolicies, allow, deny } from "failproofai"; customPolicies.add({ name: "stay-on-branch", - description: "Aracının diğer dallara geçmesini önle", + description: "Ajanın başka dallara geçmesini önle", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); if (/git\s+checkout\s+(?!-b)/.test(cmd)) { - return deny("Geçerli dalda kal. Gerekirse -b ile yeni dal oluştur."); + return deny("Mevcut dalda kal. Gerekirse -b ile yeni dal oluştur."); } return allow(); }, @@ -182,22 +182,22 @@ customPolicies.add({ --- -## Commit'ten önce testler gerekli kıl +## Taahhüt etmeden önce testler gerekli kıl -Aracılara commit'lemeden önce testleri çalıştırmalarını hatırlat. +Ajanları taahhüt etmeden önce test çalıştırması konusunda uyarın. ```javascript import { customPolicies, allow, instruct } from "failproofai"; customPolicies.add({ name: "test-before-commit", - description: "Aracıya commit'lemeden önce testleri çalıştırmasını hatırlat", + description: "Ajanı taahhüt etmeden önce test çalıştırmaya hatırlatın", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); if (/git\s+commit/.test(cmd)) { - return instruct("Commit'lemeden önce testleri çalıştır. Önce `npm test` veya `bun test`'i kullan."); + return instruct("Taahhüt etmeden önce testleri çalıştırın. Önce `npm test` veya `bun test` kullanın."); } return allow(); }, @@ -206,11 +206,11 @@ customPolicies.add({ --- -## Production deposunu kilitlenmiş hale getir +## Prodüksiyon deposunu kilitle -Proje seviyesinde bir config commit'le, böylece ekibinizdeki her geliştirici aynı politikaları alır. +Proje düzeyinde yapılandırmayı taahhüt edin, böylece ekibinizdeki her geliştirici aynı politikaları alır. -Deponuzda `.failproofai/policies-config.json` dosyası oluştur: +Deponuzda `.failproofai/policies-config.json` oluşturun: ```json { @@ -231,23 +231,23 @@ Deponuzda `.failproofai/policies-config.json` dosyası oluştur: } ``` -Sonra commit'le: +Sonra taahhüt edin: ```bash git add .failproofai/policies-config.json -git commit -m "Add failproofai team policies" +git commit -m "failproofai ekip politikalarını ekle" ``` -failproofai yüklü olan her takım üyesi otomatik olarak bu kuralları alacaktır. +failproofai yüklü olan her takım üyesi bu kuralları otomatik olarak alacaktır. --- -## Konvansiyonel politikalarla kuruluş çapında kalite standardı oluştur +## Konvansiyon politikaları ile kuruluş çapında bir kalite standardı oluştur -En etkili kurulum: `.failproofai/policies/`'ni projenize commit'le ve politikaları projenize göre özelleştir. Her takım üyesi otomatik olarak alır — kurulum komutu yok, yapılandırma değişikliği yok. +En etkili kurulum: `.failproofai/policies/` deponuza projenize göre uyarlanmış politikalarla taahhüt edin. Her takım üyesi bunları otomatik olarak alır — hiçbir yükleme komutu yok, hiçbir yapılandırma değişikliği yok. - + ```bash mkdir -p .failproofai/policies ``` @@ -256,41 +256,41 @@ En etkili kurulum: `.failproofai/policies/`'ni projenize commit'le ve politikala // .failproofai/policies/team-policies.mjs import { customPolicies, allow, deny, instruct } from "failproofai"; - // Takımının tercih ettiği paket yöneticisini zorunlu kıl - // (veya bunun yerine yerleşik prefer-package-manager politikasını etkinleştir) + // Ekibinizin tercih ettiği paket yöneticisini uygulayın + // (veya bunun yerine yerleşik prefer-package-manager politikasını etkinleştirin) customPolicies.add({ name: "enforce-bun", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); const cmd = String(ctx.toolInput?.command ?? ""); - if (/\bnpm\b/.test(cmd)) return deny("npm yerine bun'ı kullan."); + if (/\bnpm\b/.test(cmd)) return deny("npm yerine bun kullanın."); return allow(); }, }); - // Aracıya commit'lemeden önce testleri çalıştırmasını hatırlat + // Ajanı taahhüt etmeden önce test çalıştırmaya hatırlatın customPolicies.add({ name: "test-before-commit", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) { - return instruct("Commit'lemeden önce testleri çalıştır."); + return instruct("Taahhüt etmeden önce testleri çalıştırın."); } return allow(); }, }); ``` - + ```bash git add .failproofai/policies/ - git commit -m "Add team quality policies" + git commit -m "Takım kalite politikaları ekle" ``` - - Takımınız yeni hata modlarına ulaştıkça, politikalar ekle ve gönder. Herkes bir sonraki `git pull`'da güncellemeyi alır. Bu politikalar, takımınızla birlikte büyüyen bir yaşayan kalite standardı haline gelir. + + Ekibiniz yeni hata modları yaşadıkça, politika ekleyin ve itin. Herkes sonraki `git pull`da güncellemeyi alır. Bu politikalar, ekibinizle birlikte büyüyen canlı bir kalite standardı haline gelir. @@ -298,10 +298,10 @@ En etkili kurulum: `.failproofai/policies/`'ni projenize commit'le ve politikala ## Daha fazla örnek -Repodaki [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) dizini şunları içerir: +Depo içindeki [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) dizini şunları içerir: -| Dosya | Ne gösterir | +| Dosya | Neyi gösterir | |------|---------------| -| `policies-basic.js` | Başlangıç politikaları - production yazılarını, force-push'u, yönlendirilmiş komutları engelle | -| `policies-notification.js` | Boşta bekleme bildirimleri ve oturum sonu için Slack uyarıları | -| `policies-advanced/index.js` | Geçişli içe aktarımlar, async hook'lar, PostToolUse çıktısı temizliği, Stop olayı işleme | \ No newline at end of file +| `policies-basic.js` | Başlangıç politikaları - prodüksiyon yazılarını engelle, force-push, borulanan betikleri engelle | +| `policies-notification.js` | Boş bildirimler ve oturum sonu için Slack uyarıları | +| `policies-advanced/index.js` | Geçişli içe aktarmalar, eşzamansız kancalar, PostToolUse çıktı temizleme, Stop olay işleme | \ No newline at end of file diff --git a/docs/tr/for-agents.mdx b/docs/tr/for-agents.mdx index d4887649..e03be0f9 100644 --- a/docs/tr/for-agents.mdx +++ b/docs/tr/for-agents.mdx @@ -1,31 +1,31 @@ --- -title: "Agenler için" -description: "Kodlama agentnize Failproof AI bilgisini tek komutla ekleyin. Claude Code, Cursor, Windsurf ve daha fazlasıyla uyumludur." +title: "Ajanlar için" +description: "Failproof AI bilgisini bir komutla kodlama ajanınıza ekleyin. Claude Code, Cursor, Windsurf ve diğer birçok araçla çalışır." --- -Failproof AI referansının tamamını kodlama agentnize tek komutla ekleyin. Claude Code, Cursor, Windsurf ve beceri destekleyen diğer tüm agenlerle uyumludur. +Failproof AI referansının tamamını kodlama ajanınıza bir komutla ekleyin. Claude Code, Cursor, Windsurf ve beceri desteği olan diğer ajanlarla çalışır. ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` hangi agentlerin yüklü olduğunu tespit eder ve beceriyi her biri için doğru formatta otomatik olarak ekler. +`npx skills`, yüklü olduğunuz ajanları tespit eder ve beceriyi her biri için otomatik olarak doğru formatta ekler. -## Beceri neleri kapsar +## Beceri neyi kapsar -| Alan | İçerik | -|------|--------| -| İlkeler | Yerleşik ilke adları, olay türleri, parametreler, etkinleştir/devre dışı bırak | -| Özel ilkeler | `customPolicies.add()`, eşleşme filtreleri, `allow`/`deny`/`instruct` API'si | -| Bağlam nesnesi | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | +| Alan | Neler dahil | +|------|-------------| +| İlkeler | Yerleşik ilke adları, olay türleri, parametreler, etkinleştirme/devre dışı bırakma | +| Özel ilkeler | `customPolicies.add()`, eşleşme filtreleri, `allow`/`deny`/`instruct` API | +| Context nesnesi | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | | Yapılandırma | `policies-config.json` yapısı, kapsam birleştirme, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, kapsamlar | -| Pano | Oturum görüntüleyici, ilke aktivitesi, ortam değişkenleri | +| Kontrol paneli | Oturum görüntüleyici, ilke aktivitesi, ortam değişkenleri | | Mimari | Hook işleyici akışı, çıkış kodları, stdin/stdout sözleşmesi | ## Beceri tam mı? -Mintlify, `llms.txt` dosyasını navigasyondaki tüm sayfalardan oluşturur. Failproof AI belgeleri tam API'yi kapsar - her ilke, seçenek ve örnek dahil edilmiştir. Bir şey eksikse, kaynak `https://docs.befailproof.ai/llms-full.txt` adresindedir. +Mintlify, `llms.txt` dosyasını navigasyondaki tüm sayfalardan oluşturur. Failproof AI dokümentasyonu tam API'yi kapsar - her ilke, seçenek ve örnek dahil edilmiştir. Eğer bir şey eksik bulursanız, kaynak `https://docs.befailproof.ai/llms-full.txt` adresindedir. Hedeflenmiş bağlam için doğrudan belirli bir sayfaya bağlantı verin: diff --git a/docs/tr/getting-started.mdx b/docs/tr/getting-started.mdx index f93a7ba7..16429282 100644 --- a/docs/tr/getting-started.mdx +++ b/docs/tr/getting-started.mdx @@ -1,13 +1,13 @@ --- -title: Başlangıç -description: "failproofai'yi yükleyin, politikaları etkinleştirin ve ajanlarınızı güvenilir şekilde çalıştırın" +title: Başlarken +description: "failproofai'ı kurun, politikaları etkinleştirin ve ajanlarınızın güvenilir şekilde çalışmasını sağlayın" icon: rocket --- ## Gereksinimler - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (isteğe bağlı - yalnızca kaynaktan derleme için gerekli) +- **Bun** >= 1.3.0 (isteğe bağlı - yalnızca kaynaktan derlemek için gerekli) --- @@ -31,15 +31,15 @@ bun add -g failproofai - Politikalar, her ajan araç çağrısından önce ve sonra çalışan kurallardır. Yıkıcı komutları, gizli bilgi sızıntılarını ve hasar vermeden önce diğer hata modlarını yakalarlar. + Politikalar, ajanın her araç çağrısından önce ve sonra çalışan kurallardır. Yıkıcı komutları, gizli bilgi sızıntılarını ve hasara neden olmadan diğer başarısızlık modlarını yakalar. ```bash failproofai policies --install ``` - Bu, yüklü ajan CLI'lerinize kanca girdileri yazar (Claude Code'un `~/.claude/settings.json`, OpenAI Codex'in `~/.codex/hooks.json`, GitHub Copilot CLI'nin `~/.copilot/hooks/failproofai.json`, Cursor Agent'ın `~/.cursor/hooks.json`, OpenCode'un `~/.config/opencode/plugins/failproofai.mjs` konumundaki oluşturulan eklenti shim'i ve `~/.config/opencode/opencode.json` dosyasının `plugin` dizisinde bir kayıt girdisi, Pi'nin `~/.pi/agent/settings.json` veya Gemini CLI'nin `~/.gemini/settings.json`). Birden fazlası mevcut olduğunda size sorulacaktır; istem atlamak için `--cli claude codex copilot cursor opencode pi gemini` (herhangi bir alt küme) parametresini geçin. + Bu, yüklü ajan CLI'lerinize hook girişleri yazar (Claude Code'un `~/.claude/settings.json`, OpenAI Codex'in `~/.codex/hooks.json`, GitHub Copilot CLI'nin `~/.copilot/hooks/failproofai.json`, Cursor Agent'ın `~/.cursor/hooks.json`, OpenCode'un `~/.config/opencode/plugins/failproofai.mjs` konumundaki oluşturulmuş plugin shim'i ve `~/.config/opencode/opencode.json` dosyasındaki `plugin` dizisinde bir kayıt girişi, Pi'nin `~/.pi/agent/settings.json`, Gemini CLI'nin `~/.gemini/settings.json` veya Hermes'in `~/.hermes/config.yaml` dosyası). Birden fazla varsa size sorulacak; `--cli claude codex copilot cursor opencode pi gemini hermes` (herhangi bir alt küme) geçerek sorguyu atlayabilirsiniz. - GitHub Copilot CLI, Cursor Agent, OpenCode, Pi ve Gemini CLI desteği **beta** aşamasındadır — `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi` veya `--cli gemini` ile yükleyin. + GitHub Copilot CLI, Cursor Agent, OpenCode, Pi ve Gemini CLI desteği **beta** aşamasındadır — `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi` veya `--cli gemini` ile kurun. Hermes (hermes-agent, bir Slack/Telegram ağ geçidi) `--cli hermes` ile kullanıcı kapsamında yüklenir ve **ayrıca** çevrimdışı bir denetim kaynağıdır. ```bash failproofai policies --install --scope project @@ -49,6 +49,7 @@ bun add -g failproofai failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project + failproofai policies --install --cli hermes --scope user failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` @@ -57,47 +58,47 @@ bun add -g failproofai failproofai policies ``` - Her politikayı, etkin olup olmadığını ve yapılandırılmış parametreleri gösterir. + Her politikayı, etkinleştirilip etkinleştirilmediğini ve yapılandırılmış parametreleri gösterir. ```bash failproofai ``` - `http://localhost:8020` konumunda oturumları tarayabileceğiniz, araç çağrılarını inceleyebileceğiniz ve politikaları yönetebileceğiniz yerel bir panoyu açar. + Oturumları göz atabilir, araç çağrılarını inceleyebilir ve politikaları yönetebileceğiniz `http://localhost:8020` konumundaki yerel bir panoyu açar. - Claude Code'u her zamanki gibi başlatın. Ajan riskli bir şey denerse, failproofai otomatik olarak bunu engeller. Bunu arka planda çalışır bırakın ve panoda ne olduğunu gözden geçirin. + Claude Code'u her zamanki gibi başlatın. Ajan riskli bir şey denerse, failproofai bunu otomatik olarak durdurur. Bunu çalıştırılır durumda bırakın ve panoda ne olduğunu gözden geçirin. --- -## Politikalar nasıl çalışır? +## Politikalar nasıl çalışır -Bir ajan bir araç çalıştırdığında, Claude Code failproofai'yi bir alt işlem olarak çağırır: +Ajan bir araç her çalıştırdığında, Claude Code failproofai'ı bir alt işlem olarak çağırır: ```text -Claude Code → failproofai --hook PreToolUse → stdin JSON'u okur +Claude Code → failproofai --hook PreToolUse → stdin JSON'ı okur politikaları değerlendirir kararı stdout'a yazar ``` Her politika üç karardan birini döndürür: -- **allow** - ajan normal şekilde ilerlenir -- **deny** - işlem engellenir, ajana neden olduğu söylenir -- **instruct** - ajanın istemesine ekstra bağlam eklenir +- **allow** - ajan normal şekilde devam eder +- **deny** - eylem engellenir, ajanına neden engelleneceği söylenir +- **instruct** - ajanın isteminine ek bağlam eklenir -Politikalar yerel işleminizde çalışır. Uzak bir hizmete hiçbir şey gönderilmez. +Politikalar yerel işleminizde çalışır. Hiçbir şey uzak bir hizmete gönderilmez. --- -## Kural tabanlı politikalarla takım politikaları kurun +## Kural tabanlı politikalarla ekip politikaları ayarlayın -Takım genelinde kalite standartları oluşturmanın en hızlı yolu `.failproofai/policies/` kuralıdır. Bu dizine politika dosyalarını bırakın ve otomatik olarak yüklenir — hiçbir bayrak, yapılandırma değişikliği veya kurulum komutu gerekmez. +Ekibiniz genelinde kalite standartları oluşturmanın en hızlı yolu `.failproofai/policies/` kuralıdır. Bu dizine politika dosyalarını bırakın ve otomatik olarak yüklenir — bayrak yok, yapılandırma değişikliği yok, kurulum komutu yok. @@ -106,7 +107,7 @@ Takım genelinde kalite standartları oluşturmanın en hızlı yolu `.failproof ``` - Başlangıç örneklerini kopyalayın veya kendi örneklerinizi yazın: + Başlangıç örneklerini kopyalayın veya kendi dosyalarınızı yazın: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -124,7 +125,7 @@ Takım genelinde kalite standartları oluşturmanın en hızlı yolu `.failproof fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) { - return instruct("Commit yapmadan önce testleri çalıştırın."); + return instruct("Run tests before committing."); } return allow(); }, @@ -134,15 +135,15 @@ Takım genelinde kalite standartları oluşturmanın en hızlı yolu `.failproof ```bash git add .failproofai/policies/ - git commit -m "Takım kalite politikaları ekle" + git commit -m "Add team quality policies" ``` - failproofai yüklü olan her takım üyesi bu politikaları otomatik olarak alır. Geliştirici başına kurulum gerekmez. + failproofai yüklü olan her ekip üyesi bu politikaları otomatik olarak alır. Geliştirici başına kurulum gerekmez. -`.failproofai/policies/` dosyasını deponuza işleyin, böylece tüm takım aynı standartları paylaşır. Takımınız yeni hata modları keşfettikçe, politikalar ekleyin ve gönderin — herkes bir sonraki `git pull` konusunda güncelleme alır. Zaman içinde bu politikalar, gelişmeye devam eden yaşayan bir kalite standardı haline gelir. +Tüm ekibin aynı standartları paylaşması için `.failproofai/policies/` dizinini deponuza işleyin. Ekibiniz yeni başarısızlık modları keşfettikçe politika ekleyin ve gönderin — herkes bir sonraki `git pull` işleminde güncellemeyi alır. Zamanla bu politikalar, sürekli iyileşen ve ekibi güvende tutan canlı bir kalite standardı haline gelir. --- @@ -151,13 +152,13 @@ Takım genelinde kalite standartları oluşturmanın en hızlı yolu `.failproof Tüm yapılandırma ve günlükler makinenizde kalır: -| Yol | Depoladığı şey | -|------|----------------| +| Yol | Ne depolar | +|------|------------| | `~/.failproofai/policies-config.json` | Genel politika yapılandırması | -| `~/.failproofai/hook-activity.jsonl` | Kanca yürütme geçmişi | -| `~/.failproofai/hook.log` | Özel kanca hatalarına ilişkin hata ayıklama günlüğü | +| `~/.failproofai/hook-activity.jsonl` | Hook yürütme geçmişi | +| `~/.failproofai/hook.log` | Özel hook hataları için hata ayıklama günlüğü | | `.failproofai/policies-config.json` | Proje başına yapılandırma (işlenmiş) | -| `.failproofai/policies-config.local.json` | Kişisel geçersiz kılmalar (gitignored) | +| `.failproofai/policies-config.local.json` | Kişisel geçersiz kılmalar (gitignore) | --- @@ -167,7 +168,7 @@ Tüm yapılandırma ve günlükler makinenizde kalır: failproofai policies --uninstall ``` -`~/.claude/settings.json` dosyasından kanca girdilerini kaldırır. `~/.failproofai/` konumundaki yapılandırma dosyaları tutulur. +`~/.claude/settings.json` dosyasından hook girişlerini kaldırır. `~/.failproofai/` içindeki yapılandırma dosyaları korunur. --- @@ -180,15 +181,15 @@ failproofai policies --uninstall - Parametreleri olan 26 politikanın tümü + Parameterlerle 26 politikanın tümü JavaScript'te kendi politikalarınızı yazın - - Oturumları izleyin ve politika faaliyetini gözden geçirin + + Oturumları izleyin ve politika etkinliğini gözden geçirin \ No newline at end of file diff --git a/docs/tr/introduction.mdx b/docs/tr/introduction.mdx index 69a8181c..526ec330 100644 --- a/docs/tr/introduction.mdx +++ b/docs/tr/introduction.mdx @@ -1,36 +1,36 @@ --- title: "Failproof AI" -description: "FailproofAI, AI ajanlarına 39 yerleşik hata politikası sunarak döngüleri, gizli sızıntılarını, yıkıcı araç çağrılarını ve daha fazlasını tek bir kurulumda yakalar." +description: "FailproofAI, AI ajanlarına döngüleri, gizli dizi sızıntılarını, yıkıcı araç çağrılarını ve daha fazlasını tek bir kurulumda yakalaması için 39 yerleşik başarısızlık politikası sağlar." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -**AI hata yönetimi**, **hata kurtarması** ve **LLM güvenilirliği** için kancalar ve politikalar. AI ajanlarınızı güvenilir ve **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI** ve **Agents SDK** üzerinde otonom olarak çalışan durumda tutun. +**AI başarısızlık işleme**, **hata kurtarma** ve **LLM güvenilirliği** için hook'lar ve politikalar. AI ajanlarınızı **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, **Hermes** ve **Agents SDK** arasında güvenilir ve otonom halde tutun. -AI ajanları öngörülebilir şekillerde başarısız olur. Yıkıcı komutları çalıştırırlar, gizli bilgileri sızıtırlar, görevden saparlar, döngüye girip kalırlar veya doğrudan ana dal'a gönderirler. İhmal edilirse, küçük arızalar kesintilere, sızdırılan kimlik bilgilerine ve kayıp işlere dönüşür. +AI ajanları tahmin edilebilir şekillerde başarısız olur. Yıkıcı komutlar çalıştırırlar, sırları sızıntıya uğratırlar, görevlerinden saparlar, döngülere takılırlar ya da doğrudan ana dala push yaparlar. Gözetimsiz bırakıldığında, küçük başarısızlıklar kesintilere, sızıntıya uğramış kimlik bilgilerine ve kayıp işlere dönüşür. -FailproofAI bunu **politikalar** ile çözer. Bu kurallar, her ajan araç çağrısına bağlanarak **hataları algılar**, **bunları hafifletir** (engelle, talimat ver, temizle) ve **dikkat gerektiğinde sizi uyarır**. Yerel bir pano, her araç çağrısını, ajan arızasını ve kurtarma eylemini sonradan incelemenize olanak tanır. +FailproofAI bunu **politikalar** ile çözer. Bu kurallar, her ajan araç çağrısına hook olarak **başarısızlıkları algılamak**, **onları hafifletmek** (engelle, talimat ver, temizle) ve **dikkat gereken bir şey olduğunda sizi uyarmak** için bağlanır. Yerel bir pano, daha sonra her araç çağrısını, ajan başarısızlığını ve kurtarma eylemini incelemenizi sağlar. -Hiçbir veri makinenizden ayrılmaz. +Hiçbir veri makinenizi terk etmez. -## Başlarken +## Başlayın - Yıkıcı komutları engelleyin, gizli bilgi sızıntısını önleyin, ajanları proje sınırları içinde tutun ve daha fazlası. Hepsi hazır olarak gelir. + Yıkıcı komutları engelle, gizli dizi sızıntılarını önle, ajanları proje sınırları içinde tut ve daha fazlasını yap. Hepsi hazır olarak. - Basit allow / deny / instruct API'si ile JavaScript'te kendi kurallarınızı yazın. + Basit allow / deny / instruct API'si ile JavaScript'te kendi kurallarını yaz. - Ajanlarınız yokken ne yaptığını görün. Oturumlara göz atın, araç çağrılarını inceleyin, politikaların nerede devreye girdiğini gözden geçirin. + Ajanlarınız yokken neler yaptığını gör. Oturumları gözat, araç çağrılarını incele, politikaların nereden tetiklendiğini incele. - - Herhangi bir politikayı kod olmadan ayarlayın. İzin listeleri, korumalı dallar veya eşikleri proje başına veya genel olarak ayarlayın. + + Herhangi bir politikayı kod yazmadan ayarla. İzin listelerini, korunan dalları ya da eşikleri proje başına veya genel olarak ayarla. @@ -50,8 +50,8 @@ bun add -g failproofai ```bash -failproofai policies --install # politikaları etkinleştirin (veya atlayın — `failproofai` ilk çalışmada bunları ayarlamayı teklif edecektir) -failproofai # panoyu başlatın +failproofai policies --install # politikaları etkinleştir (ya da atla — failproofai ilk çalıştırmada kurulumu teklif edecektir) +failproofai # panoyu başlat ``` -Tam anlatım için [Başlarken](/tr/getting-started) kılavuzuna bakın. \ No newline at end of file +Tüm kılavuz için [Başlarken](/tr/getting-started) rehberine bakın. \ No newline at end of file diff --git a/docs/tr/package-aliases.mdx b/docs/tr/package-aliases.mdx index af80952c..4a7b8cca 100644 --- a/docs/tr/package-aliases.mdx +++ b/docs/tr/package-aliases.mdx @@ -1,6 +1,6 @@ --- title: Paket Takma Adları -description: "Tescilli typosquat-önleme takma adları ve bunların nasıl çalıştığı" +description: "Kayıtlı yazım hatası önleme takma adları ve bunların nasıl çalıştığı" icon: copy --- @@ -16,52 +16,52 @@ bun add -g failproofai --- -## Neden takma ad adlarına sahibiz +## Neden takma ad adlarını sahibi oluyoruz -Typosquatting, kötü amaçlı bir aktörün popüler bir paketin adından bir tuş kadar uzak olan bir paket adını tescil ettiği yaygın bir tedarik zinciri saldırısıdır. Kurulum komutunu yanlış yazan şüphesiz kullanıcılar, saldırganın kontrol ettiği kodu tam sistem erişimi ile çalıştırırlar - Failproof AI'nin savunması için tasarlandığı tam olarak bu tür bir tehdit. +Yazım hatası saldırısı (typosquatting), kötü niyetli bir aktörün popüler bir pakete bir tuş uzaklıkta olan bir paket adını kaydettiği yaygın bir tedarik zinciri saldırısıdır. Yükleme komutunu yanlış yazan kullanıcılar, tam sistem erişimi ile saldırgan tarafından kontrol edilen kodu çalıştırmakta bulunur - tam olarak Failproof AI'nin savunması için tasarlandığı tehdit türü. -Bu yüzey alanını ortadan kaldırmak için **`failproofai`'nin tüm yaygın yazım hataları ve biçim varyantlarına npm'de önceden sahip oluyuz**. Bu adlardan hiçbiri üçüncü bir taraf tarafından tescil edilemez. Her biri, gerçek `failproofai` paketine kuran ve devreden ince bir vekil olarak işlev görmektedir. +Bu riski ortadan kaldırmak için, **npm'de `failproofai`'nin tüm yaygın yazım hatalarını ve biçimlendirme varyantlarını önceden sahibi oluyoruz**. Bu adların hiçbiri üçüncü bir taraf tarafından kaydedilemez. Her biri, gerçek `failproofai` paketine yüklemeyi ve delegasyonu sağlayan ince bir vekil (proxy) olarak işlev görmektedir. --- -## Tescilli takma adları +## Kayıtlı takma adlar -**Biçim varyantları** - "failproof ai" yazmanın farklı yolları: +**Biçimlendirme varyantları** - "failproof ai"i yazmanın farklı yolları: | Paket | Durum | |---------|--------| | `failproof` | ✅ Yayımlandı | -| `failproof-ai` | ⏳ npm desteği beklemede | -| `fail-proof-ai` | ⏳ npm desteği beklemede | -| `failproof_ai` | ⏳ npm desteği beklemede | -| `fail_proof_ai` | ⏳ npm desteği beklemede | -| `fail-proofai` | ⏳ npm desteği beklemede | +| `failproof-ai` | ⏳ npm desteği bekleniyor | +| `fail-proof-ai` | ⏳ npm desteği bekleniyor | +| `failproof_ai` | ⏳ npm desteği bekleniyor | +| `fail_proof_ai` | ⏳ npm desteği bekleniyor | +| `fail-proofai` | ⏳ npm desteği bekleniyor | -**`failprof*` yazım hataları** - "proof" adından bir `o` eksik: +**`failprof*` yazım hatası** - "proof"tan bir `o` eksik: | Paket | Durum | |---------|--------| | `failprof` | ✅ Yayımlandı | | `failprof-ai` | ✅ Yayımlandı | -| `failprofai` | ⏳ npm desteği beklemede | -| `fail-prof-ai` | ⏳ npm desteği beklemede | -| `failprof_ai` | ⏳ npm desteği beklemede | +| `failprofai` | ⏳ npm desteği bekleniyor | +| `fail-prof-ai` | ⏳ npm desteği bekleniyor | +| `failprof_ai` | ⏳ npm desteği bekleniyor | -**`faliproof*` yazım hataları** - `a` ve `i` yer değiştirmiş: +**`faliproof*` yazım hatası** - `a` ve `i` yer değiştirmiş: | Paket | Durum | |---------|--------| | `faliproof` | ✅ Yayımlandı | | `faliproof-ai` | ✅ Yayımlandı | -| `faliproofai` | ⏳ npm desteği beklemede | +| `faliproofai` | ⏳ npm desteği bekleniyor | -> **Neden beklemede?** npm'nin spam-önleme politikası, noktalama işaretleri kaldırıldıktan ve benzerlik kontrolleri yapıldıktan sonra mevcut bir paketle aynı dizeye normalleşen adları engeller. npm desteğine bu adları anti-squatting amaçları için ayırması için başvurduk. Onay verildikten sonra etkinleştirileceklerdir. +> **Neden beklemede?** npm'nin spam önleme politikası, noktalama işaretleri çıkarıldıktan sonra ve benzerlik kontrolleri yapıldıktan sonra mevcut bir paketle aynı dizeye normalleşen adları engeller. npm desteği ile iletişime geçerek bu adları saldırı önleme amaçları için ayırttırmaya çalışıyoruz. Onay aldıktan sonra aktifleştirileceklerdir. -Yayımlanmış herhangi bir takma adın bizim tarafımızdan sahiplenildiğini doğrulayabilirsiniz: +Yayımlanmış herhangi bir takma adın bizim tarafımızdan sahibi olunduğunu doğrulayabilirsiniz: ```bash npm info failproof -# Şunu arayın: maintainers alanında "ExosphereHost Inc." +# Bak: "ExosphereHost Inc." bakımcılar alanında ``` --- @@ -70,13 +70,13 @@ npm info failproof Her takma ad paketi: -1. `failproofai`'yi bir bağımlılık olarak listeler - böylece gerçek paket (kurulum kancasının `postinstall` kurulumu dahil) kurulumda çalışır -2. Tüm argümanları `failproofai` ikilisine aktaran kendi adıyla eşleşen bir ikili sunar (ör. `failprof-ai`) +1. `failproofai`'yi bir bağımlılık olarak listeler - böylece gerçek paket (yükleme sonrası kancası kurulumu dahil) yükleme sırasında çalışır +2. Tüm argümanları `failproofai` ikili dosyasına vekil olarak gönderen kendi adıyla eşleşen bir ikili dosya sunar (örn. `failprof-ai`) -Vekil iki satırlık bir Node betiğidir; hiçbir mantık, ağ çağrısı yoktur ve `failproofai`'nin kendisinin yaptığının ötesinde veri toplama yoktur. +Vekil iki satırlık bir Node betiğidir; hiçbir mantık, ağ çağrısı ve `failproofai`'nin kendisinin yaptığı ötesinde veri toplama yoktur. --- ## Kaçırdığımız bir ad bulursanız -[failproofai/failproofai](https://github.com/failproofai/failproofai/issues) adresinde bir issue açın ve biz bunu tescil edeceğiz. \ No newline at end of file +[failproofai/failproofai](https://github.com/failproofai/failproofai/issues) adresinde bir konu açın ve biz adını kaydetmiş olacağız. \ No newline at end of file diff --git a/docs/tr/testing.mdx b/docs/tr/testing.mdx index b39d8e2c..9d94e0f9 100644 --- a/docs/tr/testing.mdx +++ b/docs/tr/testing.mdx @@ -4,11 +4,11 @@ description: "Birim testleri, uçtan uca testler ve test yardımcıları" icon: flask-vial --- -failproofai iki test paketi içerir: **birim testleri** (hızlı, mock'lanmış) ve **uçtan uca testler** (gerçek alt işlem çağrıları). +failproofai iki test paketine sahiptir: **birim testleri** (hızlı, mock'lanmış) ve **uçtan uca testler** (gerçek alt işlem çağrıları). --- -## Testleri çalıştırma +## Test Çalıştırma ```bash # Tüm birim testlerini bir kez çalıştır @@ -17,31 +17,31 @@ bun run test:run # Birim testlerini izleme modunda çalıştır bun run test -# E2E testlerini çalıştır (kurulum gerekli - aşağıya bakınız) +# E2E testlerini çalıştır (kurulum gerektirir - aşağıya bakın) bun run test:e2e -# Derlenmeden tip kontrolü yap +# Derleme yapmadan tip kontrolü yap bunx tsc --noEmit -# Lint'i çalıştır +# Lint bun run lint ``` --- -## Birim testleri +## Birim Testleri -Birim testleri `__tests__/` dizininde bulunur ve `jsdom` ile birlikte [Vitest](https://vitest.dev) kullanır. +Birim testleri `__tests__/` dizininde bulunur ve [Vitest](https://vitest.dev) ile `jsdom` kullanır. ```text __tests__/ hooks/ - builtin-policies.test.ts # Her yerleşik politika için politika mantığı + builtin-policies.test.ts # Her yerleşik için politika mantığı hooks-config.test.ts # Config yükleme ve kapsam birleştirme - policy-evaluator.test.ts # Parametre enjeksiyonu ve değerlendirme sırası - custom-hooks-registry.test.ts # globalThis kayıt defteri ekleme/alma/temizleme - custom-hooks-loader.test.ts # ESM yükleyici, geçişli içe aktarımlar, hata işleme - manager.test.ts # yükleme/kaldırma/listeleme işlemleri + policy-evaluator.test.ts # Param enjeksiyonu ve değerlendirme sırası + custom-hooks-registry.test.ts # globalThis kayıt defteri ekle/al/temizle + custom-hooks-loader.test.ts # ESM yükleyicisi, geçişli içe aktarımlar, hata işleme + manager.test.ts # kurulum/kaldırma/listeleme işlemleri components/ sessions-list.test.tsx # Oturum listesi bileşeni project-list.test.tsx # Proje listesi bileşeni @@ -71,7 +71,7 @@ import { allow, deny } from "../../src/hooks/policy-types"; describe("block-sudo", () => { const policy = getBuiltinPolicies().find((p) => p.name === "block-sudo")!; - it("sudo komutlarını reddeder", () => { + it("denies sudo commands", () => { const ctx = { eventType: "PreToolUse" as const, payload: {}, @@ -82,7 +82,7 @@ describe("block-sudo", () => { expect(policy.fn(ctx)).toEqual(deny("sudo command blocked by failproofai")); }); - it("sudo olmayan komutlara izin verir", () => { + it("allows non-sudo commands", () => { const ctx = { eventType: "PreToolUse" as const, payload: {}, @@ -93,7 +93,7 @@ describe("block-sudo", () => { expect(policy.fn(ctx)).toEqual(allow()); }); - it("allowPatterns içindeki desenlere izin verir", () => { + it("allows patterns in allowPatterns", () => { const ctx = { eventType: "PreToolUse" as const, payload: {}, @@ -108,13 +108,13 @@ describe("block-sudo", () => { --- -## Uçtan uca testler +## Uçtan Uca Testler -E2E testleri gerçek `failproofai` ikili dosyasını alt işlem olarak çağırır, stdin'e JSON yükü aktarır ve stdout çıktısı ile çıkış kodunu doğrular. Bu, Claude Code tarafından kullanılan tam entegrasyon yolunu test eder. +E2E testleri gerçek `failproofai` ikili dosyasını bir alt işlem olarak çağırır, stdin'e JSON yükü aktarır ve stdout çıkışı ile çıkış kodunu doğrular. Bu, Claude Code'un kullandığı tam entegrasyon yolunu test eder. ### Kurulum -E2E testleri, ikili dosyayı doğrudan repo kaynağından çalıştırır. İlk çalıştırmadan önce, özel kanca dosyalarının `'failproofai'`'den içe aktarırken kullandığı CJS paketini oluşturun: +E2E testleri ikili dosyayı doğrudan depo kaynak kodundan çalıştırır. İlk çalıştırmadan önce, özel hook dosyalarının `'failproofai'`'den içe aktarırken kullandığı CJS paketini derleyin: ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -126,21 +126,21 @@ Ardından testleri çalıştırın: bun run test:e2e ``` -Genel kanca API'sini değiştirdiğinizde (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` veya `src/hooks/policy-types.ts`) `dist/` dizinini yeniden derleyin. +Genel hook API'sini değiştirdiğinizde (`src/hooks/custom-hooks-registry.ts`, `src/hooks/policy-helpers.ts` veya `src/hooks/policy-types.ts`) `dist/` dizinini yeniden derleyin. ### E2E test yapısı ```text __tests__/e2e/ helpers/ - hook-runner.ts # İkili dosyayı başlat, yükü JSON olarak aktar, çıkış kodu + stdout + stderr'ı yakala - fixture-env.ts # Config dosyaları ile test başına izole edilmiş temp dizinler - payloads.ts # Her olay türü için Claude'a uygun yükü üreten fabrikalar + hook-runner.ts # İkiliyi çağır, payload JSON'ı aktarıl, çıkış kodu + stdout + stderr yakala + fixture-env.ts # Config dosyaları olan test başına izole geçici dizinler + payloads.ts # Her olay türü için Claude-doğru payload fabrikaları hooks/ - builtin-policies.e2e.test.ts # Her yerleşik politika gerçek alt işlem ile - custom-hooks.e2e.test.ts # Özel kanca yükleme ve değerlendirmesi - config-scopes.e2e.test.ts # Proje/yerel/küresel arasında config birleştirme - policy-params.e2e.test.ts # Parametreli her politika için parametre enjeksiyonu + builtin-policies.e2e.test.ts # Her yerleşik politika gerçek alt işlemle + custom-hooks.e2e.test.ts # Özel hook yükleme ve değerlendirme + config-scopes.e2e.test.ts # Proje/yerel/genel arasında config birleştirme + policy-params.e2e.test.ts # Her parametreli politika için parametre enjeksiyonu ``` ### E2E yardımcılarını kullanma @@ -151,8 +151,8 @@ __tests__/e2e/ import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - temp dizin; .failproofai/policies-config.json almak için payload.cwd olarak geçir -// env.home - izole ev dizini; gerçek ~/.failproofai sızıntısı olmaz +// env.cwd - geçici dir; .failproofai/policies-config.json'u almak için payload.cwd olarak geçir +// env.home - izole ev dizini; gerçek ~/.failproofai sızıntısı yoktur env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -164,7 +164,7 @@ env.writeConfig({ `createFixtureEnv()` `afterEach` temizliğini otomatik olarak kaydeder. -**`runHook`** - ikili dosyayı çağır: +**`runHook`** - ikiliyi çağır: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** - hazır yükü üreten fabrikalar: +**`Payloads`** - hazır payload fabrikaları: ```typescript Payloads.preToolUse.bash(command, cwd) @@ -192,7 +192,7 @@ Payloads.notification(message, cwd) Payloads.stop(cwd) ``` -### E2E test yazma +### E2E testi yazma ```typescript import { describe, it, expect } from "vitest"; @@ -201,7 +201,7 @@ import { runHook } from "../helpers/hook-runner"; import { Payloads } from "../helpers/payloads"; describe("block-rm-rf (E2E)", () => { - it("rm -rf komutunu reddeder", async () => { + it("denies rm -rf", async () => { const env = createFixtureEnv(); env.writeConfig({ enabledPolicies: ["block-rm-rf"] }); @@ -215,7 +215,7 @@ describe("block-rm-rf (E2E)", () => { expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); }); - it("tekrarsız rm'ye izin verir", async () => { + it("allows non-recursive rm", async () => { const env = createFixtureEnv(); env.writeConfig({ enabledPolicies: ["block-rm-rf"] }); @@ -237,24 +237,24 @@ describe("block-rm-rf (E2E)", () => { |----------|-----------|--------| | `PreToolUse` reddet | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | | `PostToolUse` reddet | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | -| Talimat (Stop dışı) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop talimatı | `2` | boş stdout; sebep stderr'de | +| Talimat (Stop değil) | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | +| Stop talimatı | `2` | boş stdout; stderr'de neden | | İzin ver | `0` | boş dize | -### Vitest config +### Vitest yapılandırması -E2E testleri `vitest.config.e2e.mts` dosyasını şu ayarlarla kullanır: +E2E testleri `vitest.config.e2e.mts` kullanır: -- `environment: "node"` - tarayıcı küresellerine gerek yok -- `pool: "forks"` - gerçek işlem izolasyonu (testler alt işlemleri başlatır) -- `testTimeout: 20_000` - test başına 20sn (ikili başlatma + kanca değerlendirmesi) +- `environment: "node"` - tarayıcı globals'ı gerekli değil +- `pool: "forks"` - gerçek işlem izolasyonu (testler alt işlemleri çağırır) +- `testTimeout: 20_000` - test başına 20s (ikili başlatma + hook değerlendirmesi) -`forks` havuzu önemlidir: thread tabanlı çalışanlar `globalThis` paylaşır ve bu alt işlemleri başlatan testlerde müdahale edebilir. İşlem tabanlı fork'lar bunu önler. +`forks` havuzu önemlidir: iş parçacığı tabanlı çalışanlar `globalThis`'i paylaşır, bu da alt işlem çağıran testleri etkileyebilir. İşlem tabanlı forks bunu önler. --- ## CI -Birleştirmeden önce tam CI çalıştırması (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) geçmesi gerekir. E2E paketi paralel olarak ayrı bir CI işi olarak çalışır. +Tam CI çalıştırması (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) birleştirmeden önce başarılı olması gerekir. E2E paketi paralel olarak ayrı bir CI işi olarak çalışır. -Tam ön birleştirme kontrol listesi için [Katkıda Bulunma](../CONTRIBUTING.md) bölümüne bakınız. \ No newline at end of file +Tam ön birleştirme kontrol listesi için [Contributing](../CONTRIBUTING.md) bölümüne bakın. \ No newline at end of file diff --git a/docs/vi/architecture.mdx b/docs/vi/architecture.mdx index 7b6af150..95e6fd1f 100644 --- a/docs/vi/architecture.mdx +++ b/docs/vi/architecture.mdx @@ -1,12 +1,11 @@ --- - --- title: Kiến trúc description: "Cách hook handler, config loading, và policy evaluation hoạt động nội bộ" icon: sitemap --- -Tài liệu này giải thích cách failproofai hoạt động nội bộ: cách hệ thống hook chặn các lệnh gọi công cụ của agent, cách cấu hình được tải và hợp nhất, cách các chính sách được đánh giá, và cách dashboard theo dõi hoạt động của agent. +Tài liệu này giải thích cách failproofai hoạt động nội bộ: cách hệ thống hook chặn các lệnh gọi công cụ của agent, cách cấu hình được tải và hợp nhất, cách các chính sách được đánh giá, và cách dashboard giám sát hoạt động của agent. --- @@ -14,10 +13,10 @@ Tài liệu này giải thích cách failproofai hoạt động nội bộ: các failproofai có hai hệ thống con độc lập: -1. **Hook handler** - Một CLI subprocess nhanh mà Claude Code gọi trên mỗi lệnh gọi công cụ agent. Đánh giá các chính sách và trả về một quyết định. -2. **Agent Monitor (Dashboard)** - Một ứng dụng web Next.js để theo dõi các phiên làm việc của agent và quản lý các chính sách. +1. **Hook handler** - Một quy trình CLI nhanh mà Claude Code gọi trên mỗi lệnh gọi công cụ của agent. Đánh giá các chính sách và trả về một quyết định. +2. **Agent Monitor (Dashboard)** - Một ứng dụng web Next.js để giám sát các phiên làm việc của agent và quản lý các chính sách. -Cả hai hệ thống con chia sẻ các tệp cấu hình trong `~/.failproofai/` và thư mục `.failproofai/` của dự án, nhưng chúng chạy dưới dạng các quy trình riêng biệt và chỉ giao tiếp thông qua hệ thống tệp. +Cả hai hệ thống con đều chia sẻ các tệp cấu hình trong `~/.failproofai/` và thư mục `.failproofai/` của dự án, nhưng chúng chạy dưới dạng các quy trình riêng biệt và chỉ giao tiếp qua hệ thống tệp. --- @@ -25,7 +24,7 @@ Cả hai hệ thống con chia sẻ các tệp cấu hình trong `~/.failproofai ### Tích hợp với Claude Code -Khi bạn chạy `failproofai policies --install`, nó ghi các mục như thế này vào `~/.claude/settings.json`: +Khi bạn chạy `failproofai policies --install`, nó sẽ ghi các mục như thế này vào `~/.claude/settings.json`: ```json { @@ -46,7 +45,7 @@ Khi bạn chạy `failproofai policies --install`, nó ghi các mục như thế } ``` -Claude Code sau đó gọi `failproofai --hook PreToolUse` như một subprocess trước mỗi lệnh gọi công cụ, truyền một payload JSON trên stdin. +Claude Code sau đó gọi `failproofai --hook PreToolUse` như một quy trình con trước mỗi lệnh gọi công cụ, truyền một payload JSON vào stdin. ### Định dạng payload @@ -62,13 +61,13 @@ Claude Code sau đó gọi `failproofai --hook PreToolUse` như một subprocess } ``` -Đối với các sự kiện `PostToolUse`, payload cũng chứa `tool_result` với kết quả của công cụ. +Đối với các sự kiện `PostToolUse`, payload cũng chứa `tool_result` với đầu ra của công cụ. -Handler thực thi giới hạn 1 MB cho stdin. Các payload vượt quá giới hạn này sẽ bị loại bỏ và tất cả các chính sách ngầm cho phép. +Handler áp dụng giới hạn stdin 1 MB. Các payload vượt quá giới hạn này bị loại bỏ và tất cả các chính sách ngầm cho phép. ### Định dạng phản hồi -**Deny (PreToolUse):** +**Từ chối (PreToolUse):** ```json { "hookSpecificOutput": { @@ -78,7 +77,7 @@ Handler thực thi giới hạn 1 MB cho stdin. Các payload vượt quá giới } ``` -**Deny (PostToolUse):** +**Từ chối (PostToolUse):** ```json { "hookSpecificOutput": { @@ -87,7 +86,7 @@ Handler thực thi giới hạn 1 MB cho stdin. Các payload vượt quá giới } ``` -**Instruct (bất kỳ sự kiện nào ngoại trừ Stop):** +**Hướng dẫn (bất kỳ sự kiện nào trừ Stop):** ```json { "hookSpecificOutput": { @@ -96,17 +95,17 @@ Handler thực thi giới hạn 1 MB cho stdin. Các payload vượt quá giới } ``` -**Instruct sự kiện Stop:** -- Exit code: `2` +**Hướng dẫn sự kiện Stop:** +- Mã thoát: `2` - Lý do được ghi vào stderr (không phải stdout) -**Allow:** -- Exit code: `0` -- stdout trống +**Cho phép:** +- Mã thoát: `0` +- stdout rỗng -**Allow với thông báo:** +**Cho phép với tin nhắn:** -`allow(message)` cho phép một chính sách gửi ngữ cảnh thông tin trở lại Claude ngay cả khi hoạt động được phép. Hook handler ghi JSON sau đây vào **stdout** (không phải một tệp cấu hình — đây là phản hồi của handler đối với Claude Code, giống như các phản hồi deny và instruct ở trên): +`allow(message)` cho phép một chính sách gửi bối cảnh thông tin quay lại Claude ngay cả khi hoạt động được phép. Hook handler ghi JSON sau đây vào **stdout** (không phải tệp cấu hình — đây là phản hồi của handler đối với Claude Code, giống như các phản hồi từ chối và hướng dẫn ở trên): ```json // Written to stdout by the hook handler process @@ -116,13 +115,13 @@ Handler thực thi giới hạn 1 MB cho stdin. Các payload vượt quá giới } } ``` -- Exit code: `0` (hoạt động được phép) -- Khi nhiều chính sách trả về `allow` với một thông báo, các thông báo của chúng được nối với dòng mới thành một chuỗi `additionalContext` duy nhất -- Nếu không có chính sách nào cung cấp một thông báo, stdout sẽ trống (giống như trước đây) +- Mã thoát: `0` (hoạt động được phép) +- Khi nhiều chính sách trả về `allow` với một tin nhắn, các tin nhắn của chúng được nối với các dòng mới thành một chuỗi `additionalContext` duy nhất +- Nếu không có chính sách nào cung cấp tin nhắn, stdout trống (giống như trước đây) -### Pipeline xử lý +### Đường ống xử lý -`src/hooks/handler.ts` thực hiện toàn bộ pipeline: +`src/hooks/handler.ts` triển khai đầy đủ đường ống: ```text stdin JSON @@ -141,13 +140,13 @@ stdin JSON → exit ``` -Toàn bộ quy trình chạy dưới 100ms cho các payload điển hình mà không có các lệnh gọi LLM. +Toàn bộ quá trình chạy dưới 100ms cho các payload điển hình không có lệnh gọi LLM. --- -## Config loading +## Tải cấu hình -`src/hooks/hooks-config.ts` thực hiện config loading ba phạm vi. +`src/hooks/hooks-config.ts` triển khai tải cấu hình ba phạm vi. ```text [1] {cwd}/.failproofai/policies-config.json ← project (highest priority) @@ -156,39 +155,39 @@ Toàn bộ quy trình chạy dưới 100ms cho các payload điển hình mà kh ``` Logic hợp nhất: -- `enabledPolicies` - hợp nhất được khử trùng lặp trên cả ba tệp -- `policyParams` - mỗi chính sách, tệp đầu tiên xác định nó sẽ thắng toàn bộ +- `enabledPolicies` - liên kết không trùng lặp trên cả ba tệp +- `policyParams` - mỗi khóa chính sách, tệp đầu tiên xác định nó sẽ thắng hoàn toàn - `customPoliciesPath` - tệp đầu tiên xác định nó sẽ thắng - `llm` - tệp đầu tiên xác định nó sẽ thắng -Dashboard web sử dụng `readHooksConfig()` (chỉ toàn cầu) để đọc và ghi, vì nó không được gọi với một project cwd. +Dashboard web sử dụng `readHooksConfig()` (toàn cầu duy nhất) để đọc và ghi, vì nó không được gọi với cwd của dự án. --- -## Policy evaluation +## Đánh giá chính sách `src/hooks/policy-evaluator.ts` chạy các chính sách theo thứ tự. Đối với mỗi chính sách: -1. Tra cứu lược đồ `params` của chính sách (nếu có). -2. Đọc `policyParams[policy.name]` từ config đã hợp nhất. -3. Hợp nhất các giá trị do người dùng cung cấp vào các giá trị mặc định của lược đồ để tạo `ctx.params`. -4. Gọi `policy.fn(ctx)` với ngữ cảnh đã được giải quyết. -5. Nếu kết quả là `deny`, dừng lại ngay lập tức và trả về quyết định đó. +1. Tra cứu lược đồ `params` của chính sách (nếu nó có). +2. Đọc `policyParams[policy.name]` từ cấu hình đã hợp nhất. +3. Hợp nhất các giá trị do người dùng cung cấp trên các giá trị mặc định của lược đồ để tạo ra `ctx.params`. +4. Gọi `policy.fn(ctx)` với bối cảnh đã được giải quyết. +5. Nếu kết quả là `deny`, dừng ngay lập tức và trả về quyết định đó. 6. Nếu kết quả là `instruct`, tích lũy thông báo và tiếp tục. -7. Nếu kết quả là `allow`, tiếp tục với chính sách tiếp theo. +7. Nếu kết quả là `allow`, tiếp tục đến chính sách tiếp theo. Sau khi tất cả các chính sách chạy: -- Nếu bất kỳ `deny` nào được trả về, phát hành phản hồi deny. -- Nếu bất kỳ kết quả `instruct` nào được thu thập, phát hành một phản hồi instruct duy nhất với tất cả các thông báo được nối. -- Ngoài ra, phát hành phản hồi allow (stdout trống, exit 0). +- Nếu bất kỳ `deny` nào được trả về, phát ra phản hồi từ chối. +- Nếu có bất kỳ phản hồi `instruct` nào được thu thập, phát ra một phản hồi hướng dẫn duy nhất với tất cả các thông báo được nối lại. +- Nếu không, phát ra phản hồi cho phép (stdout trống, thoát 0). --- -## Builtin policies +## Chính sách tích hợp sẵn -`src/hooks/builtin-policies.ts` định nghĩa tất cả 39 chính sách tích hợp sẵn như các đối tượng `BuiltinPolicyDefinition`: +`src/hooks/builtin-policies.ts` định nghĩa tất cả 39 chính sách tích hợp sẵn dưới dạng các đối tượng `BuiltinPolicyDefinition`: ```typescript interface BuiltinPolicyDefinition { @@ -206,15 +205,15 @@ interface BuiltinPolicyDefinition { } ``` -Các chính sách chấp nhận `params` khai báo `PolicyParamsSchema` với các loại và giá trị mặc định cho mỗi tham số. Policy evaluator tiêm các giá trị đã được giải quyết vào `ctx.params` trước khi gọi `fn`. Các hàm chính sách đọc `ctx.params` mà không cần null-guarding vì các giá trị mặc định luôn được áp dụng trước. +Các chính sách chấp nhận `params` khai báo một `PolicyParamsSchema` với các kiểu và giá trị mặc định cho mỗi tham số. Người đánh giá chính sách tiêm các giá trị được giải quyết vào `ctx.params` trước khi gọi `fn`. Các hàm chính sách đọc `ctx.params` mà không cần bảo vệ null vì các giá trị mặc định luôn được áp dụng trước. -Pattern matching bên trong các chính sách sử dụng các token lệnh được phân tích (argv), không phải so khớp chuỗi thô. Điều này ngăn chặn bypass thông qua shell operator injection (ví dụ: một mẫu cho `sudo systemctl status *` không thể bị bypass bằng cách thêm `; rm -rf /` vào lệnh). +So khớp mẫu bên trong các chính sách sử dụng các token lệnh được phân tích cú pháp (argv), không phải so khớp chuỗi thô. Điều này ngăn chặn việc vượt qua thông qua tiêm toán tử shell (ví dụ: một mẫu cho `sudo systemctl status *` không thể bị vượt qua bằng cách nối thêm `; rm -rf /` vào lệnh). --- -## Custom policies +## Chính sách tùy chỉnh -`src/hooks/custom-hooks-registry.ts` thực hiện một registry được hỗ trợ bởi `globalThis`: +`src/hooks/custom-hooks-registry.ts` triển khai một sổ đăng ký được hỗ trợ bởi `globalThis`: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -229,23 +228,23 @@ export function clearCustomHooks(): void { ... } // used in tests `src/hooks/custom-hooks-loader.ts` tải tệp chính sách của người dùng: -1. Đọc `customPoliciesPath` từ config; bỏ qua nếu không có. +1. Đọc `customPoliciesPath` từ cấu hình; bỏ qua nếu không có. 2. Giải quyết đến đường dẫn tuyệt đối; kiểm tra tệp tồn tại. -3. Viết lại tất cả `from "failproofai"` imports đến đường dẫn dist thực tế để `customPolicies` giải quyết đến cùng một registry `globalThis`. -4. Viết lại một cách đệ quy các import local chuyên cần để đảm bảo tương thích ESM. -5. Ghi các tệp `.mjs` tạm thời và `import()` tệp mục nhập. -6. Gọi `getCustomHooks()` để truy xuất các hook đã đăng ký. -7. Dọn dẹp tất cả các tệp tạm thời trong một khối `finally`. +3. Viết lại tất cả các mục nhập `from "failproofai"` thành đường dẫn dist thực tế để `customPolicies` phân giải thành cùng một sổ đăng ký `globalThis`. +4. Viết lại một cách đệ quy các mục nhập cục bộ chuyên qua để đảm bảo khả năng tương thích ESM. +5. Ghi các tệp `.mjs` tạm thời và `import()` tệp entry. +6. Gọi `getCustomHooks()` để lấy các hook đã đăng ký. +7. Dọn sạch tất cả các tệp tạm thời trong khối `finally`. -Nếu xảy ra bất kỳ lỗi nào (tệp không tìm thấy, lỗi cú pháp, lỗi import), lỗi sẽ được ghi vào `~/.failproofai/hook.log` và loader sẽ trả về một mảng trống. Các chính sách tích hợp sẵn không bị ảnh hưởng. +Trong trường hợp có lỗi (tệp không tìm thấy, lỗi cú pháp, lỗi nhập), lỗi được ghi vào `~/.failproofai/hook.log` và loader trả về một mảng trống. Các chính sách tích hợp sẵn không bị ảnh hưởng. -Các chính sách tùy chỉnh được đánh giá sau tất cả các chính sách tích hợp sẵn. Một chính sách tùy chỉnh `deny` vẫn ngắn mạch các chính sách tùy chỉnh tiếp theo (nhưng tất cả các builtins đã chạy ở thời điểm này). +Các chính sách tùy chỉnh được đánh giá sau tất cả các chính sách tích hợp sẵn. Một chính sách tùy chỉnh `deny` vẫn làm ngắn mạch các chính sách tùy chỉnh tiếp theo (nhưng tất cả các chính sách tích hợp sẵn đã chạy tại thời điểm đó). --- -## Activity logging +## Ghi nhật ký hoạt động -Sau mỗi sự kiện hook, handler thêm một dòng JSONL vào `~/.failproofai/hook-activity.jsonl`: +Sau mỗi sự kiện hook, handler nối thêm một dòng JSONL vào `~/.failproofai/hook-activity.jsonl`: ```json { @@ -260,11 +259,11 @@ Sau mỗi sự kiện hook, handler thêm một dòng JSONL vào `~/.failproofai } ``` -Một dòng cho mỗi chính sách đưa ra quyết định không phải allow. Các quyết định Allow không được ghi vào nhật ký (để giữ tệp nhỏ). +Một dòng cho mỗi chính sách đã đưa ra quyết định không cho phép. Các quyết định cho phép không được ghi nhật ký (để giữ tệp nhỏ). --- -## Kiến trúc Dashboard +## Kiến trúc dashboard Dashboard là một ứng dụng **Next.js 16** sử dụng App Router với React Server Components và Server Actions. @@ -288,16 +287,16 @@ app/ **Luồng dữ liệu:** -- Các thành phần trang gọi `lib/projects.ts` và `lib/log-entries.ts` để đọc dữ liệu dự án/phiên trực tiếp từ hệ thống tệp (không có lớp API để đọc). -- Trang Policies sử dụng Server Actions cho tất cả các thay đổi (toggle, cập nhật params, install/remove). -- Trình xem phiên phân tích định dạng transcript JSONL của Claude và hiển thị một dòng thời gian của các tin nhắn và lệnh gọi công cụ. +- Các thành phần trang gọi `lib/projects.ts` và `lib/log-entries.ts` để đọc dữ liệu dự án/phiên làm việc trực tiếp từ hệ thống tệp (không có lớp API cho các lần đọc). +- Trang Policies sử dụng Server Actions cho tất cả các thay đổi (bật/tắt, cập nhật tham số, cài đặt/xóa). +- Trình xem phiên làm việc phân tích định dạng bảng điểm JSONL của Claude và hiển thị dòng thời gian của các thông báo và lệnh gọi công cụ. **Các quyết định thiết kế chính:** -- Không có cơ sở dữ liệu - tất cả trạng thái liên tục nằm trong các tệp thuần (`~/.failproofai/`, `~/.claude/projects/`). +- Không có cơ sở dữ liệu - tất cả trạng thái liên tục là trong các tệp thô (`~/.failproofai/`, `~/.claude/projects/`). - Server Actions cho các thay đổi - không cần REST API cho các hoạt động CRUD. -- React Server Components cho các trang đọc - tải ban đầu nhanh hơn, không có client bundle cho việc tìm nạp dữ liệu. -- Các thành phần client chỉ khi cần tương tác (toggles chính sách, tìm kiếm hoạt động, trình xem nhật ký). +- React Server Components cho các trang đọc - tải ban đầu nhanh hơn, không có gói máy khách cho tìm nạp dữ liệu. +- Các thành phần máy khách chỉ khi cần tương tác (bật/tắt chính sách, tìm kiếm hoạt động, trình xem nhật ký). --- diff --git a/docs/vi/built-in-policies.mdx b/docs/vi/built-in-policies.mdx index ecf47b97..b7eb5873 100644 --- a/docs/vi/built-in-policies.mdx +++ b/docs/vi/built-in-policies.mdx @@ -1,19 +1,19 @@ --- -title: Chính sách Tích hợp -description: "Tất cả 39 chính sách tích hợp giúp phát hiện các chế độ lỗi phổ biến của agent" +title: Các chính sách tích hợp sẵn +description: "Tất cả 39 chính sách tích hợp sẵn bắt được các chế độ lỗi thông thường của agent" icon: shield --- -failproofai đi kèm với 39 chính sách tích hợp giúp phát hiện các chế độ lỗi phổ biến của agent. Mỗi chính sách được kích hoạt trên một loại sự kiện hook cụ thể và tên công cụ. Mười chín chính sách chấp nhận các tham số cho phép bạn điều chỉnh hành vi của chúng mà không cần viết mã. Năm chính sách quy trình làm việc thực thi một đường ống commit → push → PR → CI trước khi Claude dừng. +failproofai được trang bị 39 chính sách tích hợp sẵn bắt được các chế độ lỗi thông thường của agent. Mỗi chính sách được kích hoạt trên một loại sự kiện hook cụ thể và tên công cụ. Mười chín chính sách chấp nhận các tham số cho phép bạn tinh chỉnh hành vi của chúng mà không cần viết mã. Năm chính sách quy trình làm việc thực thi đường dẫn commit → push → PR → CI trước khi Claude dừng lại. --- ## Tổng quan -Các chính sách được nhóm theo danh mục: +Các chính sách được nhóm vào các danh mục: -| Danh mục | Chính sách | Loại Hook | -|----------|----------|-----------| +| Danh mục | Chính sách | Loại hook | +|----------|-----------|-----------| | [Lệnh nguy hiểm](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | | [Lệnh cơ sở hạ tầng](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | | [Bí mật (sanitizers)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | @@ -25,15 +25,19 @@ Các chính sách được nhóm theo danh mục: | [Trình quản lý gói](#package-managers) | prefer-package-manager | PreToolUse | | [Quy trình làm việc](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — dừng agent từ việc tiếp tục. -- **`warn-`** — cung cấp cho agent ngữ cảnh bổ sung để nó có thể tự sửa chữa. -- **`sanitize-`** — xóa dữ liệu nhạy cảm từ đầu ra công cụ trước khi agent nhìn thấy nó. +- **`block-`** — dừng agent không được tiếp tục. +- **`warn-`** — cung cấp ngữ cảnh bổ sung để agent có thể tự sửa chữa. +- **`sanitize-`** — loại bỏ dữ liệu nhạy cảm từ kết quả công cụ trước khi agent nhìn thấy. ### Không gian tên -Mỗi chính sách tồn tại trong một khe `/`. Các chính sách tích hợp thuộc về không gian tên **`failproofai/`** — ví dụ: `failproofai/sanitize-jwt`. Không gian tên ngăn chặn xung đột khi bạn cũng tải các chính sách tùy chỉnh hoặc của bên thứ ba có tên ngắn tương tự. +Mỗi chính sách sống trong một vị trí `/`. Các chính sách tích hợp sẵn thuộc về +không gian tên **`failproofai/`** — ví dụ: `failproofai/sanitize-jwt`. Không gian tên +ngăn chặn va chạm khi bạn cũng tải các chính sách tùy chỉnh hoặc của bên thứ ba +có tên ngắn tương tự. -Trong cấu hình của bạn, bạn có thể tham chiếu một chính sách tích hợp bằng tên ngắn hoặc tên đủ điều kiện của nó; cả hai dạng đều giải quyết chính sách tương tự: +Trong cấu hình của bạn, bạn có thể tham chiếu đến một chính sách tích hợp sẵn bằng tên ngắn hoặc tên +đủ điều kiện; cả hai dạng đều giải quyết thành cùng một chính sách: ```json { @@ -44,33 +48,35 @@ Trong cấu hình của bạn, bạn có thể tham chiếu một chính sách t } ``` -Nếu tên không có `/`, failproofai sẽ coi nó thuộc về không gian tên mặc định `failproofai`. Các tên đã chứa `/` (ví dụ: `myorg/foo`, `custom/my-hook`) được giữ nguyên. +Nếu một tên không có `/`, failproofai coi nó thuộc về không gian tên mặc định +`failproofai`. Các tên đã chứa `/` (ví dụ: `myorg/foo`, +`custom/my-hook`) được giữ nguyên. - **`require-`** — chặn sự kiện Stop cho đến khi các điều kiện được đáp ứng. --- -Mỗi chính sách hỗ trợ một trường `hint` tùy chọn trong `policyParams`. Hint được thêm vào thông báo deny hoặc instruct mà Claude nhìn thấy, cung cấp hướng dẫn có thể thực hiện được mà không cần sửa đổi mã chính sách. Hoạt động với các chính sách tích hợp, tùy chỉnh và quy ước. Xem [Cấu hình → hint](/vi/configuration#hint-cross-cutting) để biết chi tiết. +Mỗi chính sách hỗ trợ một trường `hint` tùy chọn trong `policyParams`. Hint được nối vào tin nhắn deny hoặc instruct mà Claude nhìn thấy, cung cấp hướng dẫn có thể hành động mà không sửa đổi mã chính sách. Hoạt động với các chính sách tích hợp sẵn, tùy chỉnh và theo quy ước. Xem [Configuration → hint](/vi/configuration#hint-cross-cutting) để biết chi tiết. --- ## Lệnh nguy hiểm -Ngăn chặn agent chạy các hoạt động khó hoàn tác hoặc có thể làm hỏng hệ thống chủ. +Ngăn chặn agent chạy các thao tác khó hoàn tác hoặc có thể làm hỏng hệ thống chủ nhà. ### `block-sudo` **Sự kiện:** PreToolUse (Bash) **Mặc định:** Từ chối bất kỳ lệnh `sudo` nào. -Chặn các lệnh gọi chứa từ khóa `sudo`. Khớp mẫu được thực hiện trên các token lệnh được phân tích cú pháp, không phải chuỗi thô, để ngăn chặn vượt qua qua injection operator shell. +Chặn các lần gọi bao gồm từ khóa `sudo`. Phối hợp mẫu được thực hiện trên các token lệnh được phân tích cú pháp, không phải chuỗi thô, để ngăn chặn bypass qua tiêm toán tử shell. **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh chính xác được phép. Mỗi mục được so khớp với các token argv được phân tích. | +|--------|------|---------|-------| +| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh chính xác được phép. Mỗi mục được so khớp với các token argv được phân tích cú pháp. | **Ví dụ:** @@ -87,7 +93,7 @@ Chặn các lệnh gọi chứa từ khóa `sudo`. Khớp mẫu được thực Với cấu hình này, `sudo systemctl status nginx` được phép, nhưng `sudo rm /etc/hosts` bị từ chối. -Các mẫu được so khớp với các token được phân tích, không phải chuỗi lệnh thô. Điều này ngăn chặn vượt qua qua các operator shell được thêm vào (ví dụ: `sudo systemctl status x; rm -rf /` không khớp với `sudo systemctl status *`). +Các mẫu được so khớp với các token được phân tích cú pháp, không phải chuỗi lệnh thô. Điều này ngăn chặn bypass qua các toán tử shell được thêm vào (ví dụ: `sudo systemctl status x; rm -rf /` không khớp với `sudo systemctl status *`). --- @@ -100,8 +106,8 @@ Các mẫu được so khớp với các token được phân tích, không ph **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Các đường dẫn an toàn để xóa đệ quy (ví dụ: `/tmp`). | +|--------|------|---------|-------| +| `allowPaths` | `string[]` | `[]` | Đường dẫn an toàn để xóa đệ quy (ví dụ: `/tmp`). | **Ví dụ:** @@ -137,9 +143,9 @@ Không có tham số. ## Lệnh cơ sở hạ tầng -Ngăn chặn agent viết mã chạy CLI cơ sở hạ tầng hoặc kích hoạt đường dẫn CI/CD. Tất cả các chính sách trong danh mục này là **tùy chọn** (`defaultEnabled: false`) — agent cần gọi `kubectl`, `terraform`, v.v. sẽ không bị gián đoạn trừ khi bạn bật chính sách. Khi được bật, mỗi lần gọi CLI phù hợp bị từ chối trừ khi lệnh khớp với một mục trong `allowPatterns`. +Dừng các agent mã hóa chạy CLI cơ sở hạ tầng hoặc kích hoạt đường ống CI/CD. Tất cả các chính sách trong danh mục này là **opt-in** (`defaultEnabled: false`) — các agent hợp pháp cần gọi `kubectl`, `terraform`, v.v. sẽ không bị gián đoạn trừ khi bạn bật chính sách. Khi được bật, mỗi lần gọi CLI phù hợp bị từ chối trừ khi lệnh khớp với một mục trong `allowPatterns`. -Ngữ pháp mẫu giống như [`block-sudo`](#block-sudo): các token được so khớp với argv được phân tích, `*` là ký tự đại diện cho một token, và bất kỳ lệnh nào chứa một operator shell độc lập (`&&`, `||`, `|`, `;`) hoặc token có ký tự siêu shell nhúng bị từ chối trước khi khớp danh sách cho phép để ngăn chặn injection. +Ngữ pháp mẫu giống như [`block-sudo`](#block-sudo): các token được so khớp với argv được phân tích cú pháp, `*` là ký tự đại diện cho một token, và bất kỳ lệnh nào chứa toán tử shell độc lập (`&&`, `||`, `|`, `;`) hoặc token có ký tự siêu dữ liệu shell nhúng bị từ chối trước khi so khớp danh sách cho phép để ngăn chặn bypass tiêm. ### `block-kubectl` @@ -149,7 +155,7 @@ Ngữ pháp mẫu giống như [`block-sudo`](#block-sudo): các token được **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| +|--------|------|---------|-------| | `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh kubectl được phép. | **Ví dụ:** @@ -176,7 +182,7 @@ Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| +|--------|------|---------|-------| | `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh terraform/tofu được phép. | **Ví dụ:** @@ -201,8 +207,8 @@ Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh CLI aws được phép. | +|--------|------|---------|-------| +| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh aws CLI được phép. | **Ví dụ:** @@ -226,7 +232,7 @@ Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| +|--------|------|---------|-------| | `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh gcloud được phép. | **Ví dụ:** @@ -251,8 +257,8 @@ Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh CLI az được phép. | +|--------|------|---------|-------| +| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh az CLI được phép. | **Ví dụ:** @@ -276,7 +282,7 @@ Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| +|--------|------|---------|-------| | `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh helm được phép. | **Ví dụ:** @@ -296,7 +302,7 @@ Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply ### `block-gh-pipeline` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối các lệnh phụ sau của CLI `gh` thay đổi trạng thái hoặc kích hoạt đường dẫn: +**Mặc định:** Từ chối các lệnh phụ CLI `gh` sau đây gây ra thay đổi trạng thái hoặc kích hoạt đường ống: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -305,13 +311,13 @@ Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply - `gh cache delete` - `gh secret set`, `gh secret delete` -Các lệnh phụ `gh` chỉ đọc như `gh pr view`, `gh pr list`, `gh run list`, `gh release view` và `gh api repos/.../...` **không** được khớp bởi chính sách này — chúng thường cần thiết cho các kiểm tra quy trình làm việc (bao gồm cả `require-ci-green-before-stop` của failproofai). +Các lệnh phụ `gh` chỉ đọc như `gh pr view`, `gh pr list`, `gh run list`, `gh release view` và `gh api repos/.../...` **không** được khớp bởi chính sách này — chúng thường cần thiết cho các kiểm tra quy trình làm việc (bao gồm cả chính sách `require-ci-green-before-stop` của failproofai). **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Các lệnh gọi kịch bản cụ thể để cho phép mặc dù chúng sẽ bị từ chối. | +|--------|------|---------|-------| +| `allowPatterns` | `string[]` | `[]` | Các lệnh gọi được viết kịch bản cụ thể để cho phép ngay cả khi chúng sẽ bị từ chối. | **Ví dụ:** @@ -329,12 +335,12 @@ Các lệnh phụ `gh` chỉ đọc như `gh pr view`, `gh pr list`, `gh run lis ## Bí mật (sanitizers) -Ngăn chặn agent rò rỉ thông tin xác thực vào ngữ cảnh hoặc đầu ra của chúng. Các chính sách sanitizer được kích hoạt trên các sự kiện **PostToolUse**. Khi Claude chạy một lệnh Bash, đọc một tệp hoặc gọi bất kỳ công cụ nào, các chính sách này kiểm tra đầu ra trước khi nó được trả về cho Claude. Nếu phát hiện mẫu bí mật, chính sách sẽ trả về quyết định deny ngăn chặn đầu ra được truyền lại. +Dừng agent rò rỉ thông tin đăng nhập vào ngữ cảnh hoặc kết quả của chúng. Các chính sách sanitizer được kích hoạt trên các sự kiện **PostToolUse**. Khi Claude chạy lệnh Bash, đọc tệp hoặc gọi bất kỳ công cụ nào, các chính sách này kiểm tra kết quả trước khi nó được trả về Claude. Nếu phát hiện mẫu bí mật, chính sách trả về quyết định deny ngăn chặn kết quả được truyền lại. ### `sanitize-jwt` **Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Loại bỏ các token JWT (ba đoạn base64url cách nhau bằng `.`). +**Mặc định:** Che khuất các token JWT (ba đoạn base64url được phân cách bằng `.`). Không có tham số. @@ -343,12 +349,12 @@ Không có tham số. ### `sanitize-api-keys` **Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Loại bỏ các định dạng khóa API phổ biến: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), khóa truy cập AWS (`AKIA`), khóa Stripe (`sk_live_`, `sk_test_`) và khóa API Google (`AIza`). +**Mặc định:** Che khuất các định dạng khóa API phổ biến: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS access keys (`AKIA`), Stripe keys (`sk_live_`, `sk_test_`) và Google API keys (`AIza`). **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| +|--------|------|---------|-------| | `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Các mẫu regex bổ sung để coi là bí mật. | **Ví dụ:** @@ -371,7 +377,7 @@ Không có tham số. ### `sanitize-connection-strings` **Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Loại bỏ chuỗi kết nối cơ sở dữ liệu chứa thông tin xác thực nhúng (ví dụ: `postgresql://user:password@host/db`). +**Mặc định:** Che khuất chuỗi kết nối cơ sở dữ liệu chứa thông tin đăng nhập nhúng (ví dụ: `postgresql://user:password@host/db`). Không có tham số. @@ -380,7 +386,7 @@ Không có tham số. ### `sanitize-private-key-content` **Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Loại bỏ các khối PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, v.v.). +**Mặc định:** Che khuất các khối PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, v.v.). Không có tham số. @@ -389,7 +395,7 @@ Không có tham số. ### `sanitize-bearer-tokens` **Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Loại bỏ các tiêu đề `Authorization: Bearer ` nơi token có 20 ký tự trở lên. +**Mặc định:** Che khuất các tiêu đề `Authorization: Bearer ` nơi token là 20 hoặc nhiều ký tự hơn. Không có tham số. @@ -397,14 +403,14 @@ Không có tham số. ## Môi trường -Bảo vệ cấu hình môi trường nhạy cảm khỏi việc bị agent đọc hoặc tiếp xúc. +Bảo vệ cấu hình môi trường nhạy cảm khỏi việc agent đọc hoặc tiếp xúc. ### `block-env-files` **Sự kiện:** PreToolUse (Bash, Read) -**Mặc định:** Từ chối đọc các tệp `.env` qua `cat .env`, các lệnh gọi công cụ Read có `.env` làm đường dẫn tệp, v.v. +**Mặc định:** Từ chối đọc tệp `.env` qua `cat .env`, gọi công cụ `Read` với `.env` là đường dẫn tệp, v.v. -Không chặn `.envrc` hoặc các tệp liên quan môi trường khác - chỉ các tệp được đặt tên chính xác là `.env`. +Không chặn `.envrc` hoặc các tệp liên quan môi trường khác - chỉ những tệp được đặt tên chính xác là `.env`. Không có tham số. @@ -421,18 +427,18 @@ Không có tham số. ## Truy cập tệp -Giữ agent hoạt động bên trong ranh giới dự án và xa khỏi các tệp nhạy cảm. +Giữ agent làm việc trong ranh giới dự án và tránh xa những tệp nhạy cảm. ### `block-read-outside-cwd` **Sự kiện:** PreToolUse (Read, Bash) -**Mặc định:** Từ chối đọc các tệp ngoài thư mục gốc dự án. Ranh giới là `CLAUDE_PROJECT_DIR` (được đặt một lần mỗi phiên bởi Claude Code), với sự hỗ trợ dự phòng cho thư mục làm việc hiện tại của phiên khi biến đó không được đặt. Sử dụng thư mục gốc dự án thay vì `cwd` trực tiếp có nghĩa là ranh giới vẫn ổn định ngay cả sau khi Claude `cd` vào một thư mục con. +**Mặc định:** Từ chối đọc tệp bên ngoài gốc dự án. Ranh giới là `CLAUDE_PROJECT_DIR` (được đặt một lần mỗi phiên bởi Claude Code), với dự phòng là thư mục làm việc hiện tại của phiên khi biến đó chưa được đặt. Sử dụng gốc dự án thay vì `cwd` trực tiếp có nghĩa là ranh giới vẫn ổn định ngay cả sau khi Claude `cd` vào thư mục con. **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Tiền tố đường dẫn tuyệt đối được phép ngay cả khi nằm ngoài thư mục gốc dự án. | +|--------|------|---------|-------| +| `allowPaths` | `string[]` | `[]` | Tiền tố đường dẫn tuyệt đối được phép ngay cả khi bên ngoài gốc dự án. | **Ví dụ:** @@ -451,12 +457,12 @@ Giữ agent hoạt động bên trong ranh giới dự án và xa khỏi các t ### `block-secrets-write` **Sự kiện:** PreToolUse (Write, Edit) -**Mặc định:** Từ chối ghi vào các tệp thường được sử dụng cho khóa riêng tư và chứng chỉ: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Mặc định:** Từ chối ghi vào các tệp thường được sử dụng cho các khóa riêng tư và chứng chỉ: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| +|--------|------|---------|-------| | `additionalPatterns` | `string[]` | `[]` | Các mẫu tên tệp bổ sung (kiểu glob) để chặn. | **Ví dụ:** @@ -475,7 +481,7 @@ Giữ agent hoạt động bên trong ranh giới dự án và xa khỏi các t ## Git -Ngăn chặn các lần push, force-push và lỗi nhánh ngẫu nhiên khó hoàn tác. +Ngăn chặn các lần push tình cờ, force-push và các lỗi nhánh khó hoàn tác. ### `block-push-master` @@ -485,7 +491,7 @@ Ngăn chặn các lần push, force-push và lỗi nhánh ngẫu nhiên khó ho **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| +|--------|------|---------|-------| | `protectedBranches` | `string[]` | `["main", "master"]` | Tên nhánh không thể được push trực tiếp. | **Ví dụ:** @@ -501,7 +507,7 @@ Ngăn chặn các lần push, force-push và lỗi nhánh ngẫu nhiên khó ho ``` -Để cho phép push đến tất cả các nhánh (tệp vô hiệu hóa chính sách này mà không cần xóa nó khỏi `enabledPolicies`), hãy đặt `protectedBranches: []`. +Để cho phép push đến tất cả các nhánh (có hiệu lực là vô hiệu hóa chính sách này mà không xóa nó khỏi `enabledPolicies`), đặt `protectedBranches: []`. --- @@ -509,13 +515,13 @@ Ngăn chặn các lần push, force-push và lỗi nhánh ngẫu nhiên khó ho ### `block-work-on-main` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối `git commit`, `git merge`, `git rebase` và `git cherry-pick` khi cây làm việc trên `main` hoặc `master`. Tạo nhánh và chuyển đổi (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) không bị ảnh hưởng. +**Mặc định:** Từ chối `git commit`, `git merge`, `git rebase` và `git cherry-pick` khi cây làm việc nằm trên `main` hoặc `master`. Tạo nhánh và chuyển đổi (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) không bị ảnh hưởng. **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Tên nhánh trên đó commit/merge/rebase/cherry-pick bị từ chối. | +|--------|------|---------|-------| +| `protectedBranches` | `string[]` | `["main", "master"]` | Tên nhánh trong đó commit/merge/rebase/cherry-pick bị từ chối. | --- @@ -524,13 +530,13 @@ Ngăn chặn các lần push, force-push và lỗi nhánh ngẫu nhiên khó ho **Sự kiện:** PreToolUse (Bash) **Mặc định:** Từ chối `git push --force` và `git push -f`. -Không có tham số cụ thể chính sách. Sử dụng [`hint`](/vi/configuration#hint-cross-cutting) xuyên suốt để đề xuất các giải pháp thay thế: +Không có tham số cụ thể chính sách. Sử dụng [`hint`](/vi/configuration#hint-cross-cutting) cắt ngang để gợi ý các giải pháp thay thế: ```json { "policyParams": { "block-force-push": { - "hint": "Tạo một nhánh mới từ HEAD hiện tại của bạn (ví dụ: `git checkout -b `) và push nhánh đó thay thế." + "hint": "Tạo một nhánh mới từ HEAD hiện tại của bạn (ví dụ: `git checkout -b `) và push nhánh đó thay vì." } } } @@ -559,7 +565,7 @@ Không có tham số. ### `warn-all-files-staged` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Hướng dẫn Claude xem xét những gì nó đang tổ chức khi chạy `git add -A` hoặc `git add .`. Không chặn lệnh. +**Mặc định:** Hướng dẫn Claude xem lại những gì nó sắp sàng lọc khi chạy `git add -A` hoặc `git add .`. Không chặn lệnh. Không có tham số. @@ -567,7 +573,7 @@ Không có tham số. ## Cơ sở dữ liệu -Phát hiện các thao tác SQL tàn phá trước khi chúng thực thi với cơ sở dữ liệu của bạn. +Bắt các thao tác SQL phá hủy trước khi chúng thực thi đối với cơ sở dữ liệu của bạn. ### `warn-destructive-sql` @@ -589,7 +595,7 @@ Không có tham số. ## Cảnh báo -Cung cấp cho agent ngữ cảnh bổ sung trước các thao tác có rủi ro nhưng không tàn phá. +Cung cấp agent ngữ cảnh bổ sung trước các hoạt động tiềm ẩn rủi ro nhưng không phá hủy. ### `warn-large-file-write` @@ -599,8 +605,8 @@ Cung cấp cho agent ngữ cảnh bổ sung trước các thao tác có rủi ro **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | Ngưỡng kích thước tệp tính bằng kilobyte trên đó cảnh báo được phát hành. | +|--------|------|---------|-------| +| `thresholdKb` | `number` | `1024` | Ngưỡng kích thước tệp tính bằng kilobyte mà cảnh báo được phát hành. | **Ví dụ:** @@ -615,7 +621,7 @@ Cung cấp cho agent ngữ cảnh bổ sung trước các thao tác có rủi ro ``` -Trình xử lý hook thực thi giới hạn stdin 1 MB trên tải trọng. Để kiểm tra chính sách này với nội dung nhỏ, hãy đặt `thresholdKb` thành giá trị ít hơn 1024. +Xử lý hook thực thi giới hạn stdin 1 MB trên tải trọng. Để kiểm tra chính sách này với nội dung nhỏ, đặt `thresholdKb` thành giá trị tốt dưới 1024. --- @@ -649,21 +655,21 @@ Không có tham số. ## Trình quản lý gói -Thực thi trình quản lý gói nào được agent phép sử dụng. +Thực thi trình quản lý gói nào agent được phép sử dụng. ### `prefer-package-manager` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Tắt. Khi bật, chặn bất kỳ lệnh trình quản lý gói nào không có trong danh sách `allowed` và yêu cầu Claude viết lại lệnh bằng trình quản lý được phép. +**Mặc định:** Bị vô hiệu hóa. Khi được bật, chặn bất kỳ lệnh trình quản lý gói nào không trong danh sách `allowed` và yêu cầu Claude viết lại lệnh bằng trình quản lý được phép. Phát hiện: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. | Tham số | Loại | Mặc định | Mô tả | -|-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | Tên trình quản lý gói được phép. Bất kỳ trình quản lý được phát hiện nào không có trong danh sách này đều bị chặn. Khi để trống, chính sách là không hoạt động. | -| `blocked` | string[] | `[]` | Tên trình quản lý bổ sung để chặn ngoài danh sách tích hợp (ví dụ: `['pdm', 'pipx']`). | +|--------|------|---------|-------| +| `allowed` | string[] | `[]` | Các tên trình quản lý gói được phép. Bất kỳ trình quản lý được phát hiện nào không có trong danh sách này bị chặn. Khi trống, chính sách là no-op. | +| `blocked` | string[] | `[]` | Các tên trình quản lý bổ sung để chặn ngoài danh sách tích hợp sẵn (ví dụ: `['pdm', 'pipx']`). | -Danh sách chặn tích hợp bao gồm: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Sử dụng `blocked` để thêm các trình quản lý không có trong danh sách này. +Danh sách chặn tích hợp sẵn bao gồm: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Sử dụng `blocked` để thêm các trình quản lý không có trong danh sách này. **Cấu hình ví dụ:** @@ -679,18 +685,18 @@ Danh sách chặn tích hợp bao gồm: pip, pip3, npm, npx, yarn, pnpm, pnpx, } ``` -Với cấu hình này, `pip install flask` và `pdm install flask` đều bị từ chối với thông báo yêu cầu Claude sử dụng `uv` hoặc `bun` thay thế. Các lệnh như `uv pip install flask` được phép vì `uv` có trong danh sách cho phép và được kiểm tra trước tiên. +Với cấu hình này, `pip install flask` và `pdm install flask` đều bị từ chối với thông báo yêu cầu Claude sử dụng `uv` hoặc `bun` thay vì. Các lệnh như `uv pip install flask` được phép vì `uv` nằm trong danh sách cho phép và được kiểm tra trước tiên. --- ## Hành vi AI -Phát hiện khi agent bị kẹt hoặc hoạt động không như mong đợi. +Phát hiện khi agent bị mắc kẹt hoặc có hành vi bất thường. ### `warn-repeated-tool-calls` **Sự kiện:** PreToolUse (tất cả công cụ) -**Mặc định:** Hướng dẫn Claude suy nghĩ lại khi cùng một công cụ được gọi 3 lần hoặc nhiều hơn với các tham số giống nhau - dấu hiệu phổ biến của agent bị kẹt trong vòng lặp. +**Mặc định:** Hướng dẫn Claude xem xét lại khi cùng một công cụ được gọi 3 lần trở lên với các tham số giống hệt nhau - dấu hiệu phổ biến của agent bị mắc vòng lặp. Không có tham số. @@ -698,40 +704,40 @@ Không có tham số. ## Quy trình làm việc -Thực thi quy trình làm việc kỷ luật ở cuối phiên. Các chính sách này được kích hoạt trên sự kiện **Stop** và từ chối agent dừng lại cho đến khi mỗi điều kiện được đáp ứng. Chúng tuân theo chuỗi phụ thuộc tự nhiên: commit → push → PR → CI. Nếu chính sách từ chối, các chính sách sau đó trong chuỗi sẽ bị bỏ qua (deny ngắn mạch). +Thực thi quy trình làm việc cuối phiên kỷ luật. Các chính sách này được kích hoạt trên sự kiện **Stop** và từ chối agent dừng lại cho đến khi mỗi điều kiện được đáp ứng. Chúng tuân theo chuỗi phụ thuộc tự nhiên: commit → push → PR → CI. Nếu chính sách từ chối, các chính sách sau trong chuỗi bị bỏ qua (deny short-circuits). -Tất cả các chính sách quy trình làm việc **fail-open**: nếu công cụ yêu cầu không có sẵn (ví dụ: `gh` chưa cài đặt, không có git remote), chính sách cho phép với thông báo thông tin giải thích lý do kiểm tra bị bỏ qua. +Tất cả các chính sách quy trình làm việc là **fail-open**: nếu công cụ được yêu cầu không có sẵn (ví dụ: `gh` không cài đặt, không có git remote), chính sách cho phép với thông báo thông tin giải thích lý do kiểm tra bị bỏ qua. ### Ngữ nghĩa Stop theo CLI -Thực thi Stop trông hơi khác nhau trên bảy CLI được hỗ trợ vì mỗi CLI tiếp xúc với hợp đồng hook "agent finished" khác nhau. **Kết quả** là giống nhau — agent không thoát khỏi việc dừng lại khi một cổng quy trình làm việc đang thất bại — nhưng **cơ học** khác nhau. Bảng dưới đây tóm tắt; chỉ có Pi có một đặc điểm nhạy cảm đáng hiểu trước khi bạn bật chính sách `require-*-before-stop`. +Thực thi Stop trông hơi khác nhau trên bảy CLI được hỗ trợ vì mỗi CLI tiếp xúc với hợp đồng hook "agent kết thúc" khác nhau. **Kết quả** là như nhau — agent không thoát khỏi việc dừng lại trong khi cổng quy trình làm việc đang thất bại — nhưng **cơ chế** khác nhau. Bảng dưới đây tóm tắt; chỉ Pi có một điểm kỳ lạ hiển thị cho người dùng đáng hiểu trước khi bạn bật chính sách `require-*-before-stop`. -| CLI | Khi cổng kích hoạt | Bạn thấy gì | +| CLI | Khi cổng kích hoạt | Những gì bạn thấy | |---|---|---| -| Claude Code | Cùng một vòng lặp agent, ngay lập tức | Claude tiếp tục làm việc — sửa chữa vấn đề, sau đó cố gắng kết thúc lại. Không gián đoạn hiển thị cho bạn. | -| Codex | Cùng một vòng lặp agent, ngay lập tức | Giống như Claude. | -| GitHub Copilot CLI | Cùng một vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng kênh `{decision:"block", reason}` của Copilot — xác minh theo kinh nghiệm so với Copilot CLI 1.0.41). | -| Cursor Agent | Cùng một vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng kênh `{followup_message}` của Cursor — bị giới hạn bởi `loop_limit`, mặc định 5 lần thử lại). | -| Gemini CLI | Cùng một vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng kênh `{decision:"block", reason}` của Gemini trên `AfterAgent`). | -| OpenCode | Cùng một vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng lệnh gọi SDK `client.session.prompt(...)` của OpenCode được định tuyến qua `hookSpecificOutput.additionalContext`). | -| **Pi (pi-coding-agent)** | **Lần tiếp theo người dùng** | **Pi dừng rõ ràng** khi cổng kích hoạt — vòng lặp agent của nó thoát và bạn được trả về lời nhắc. Cổng sau đó kích hoạt lần tiếp theo bạn gửi lời nhắc: failproofai thêm một chỉ thị `MANDATORY ACTION REQUIRED` vào lời nhắc hệ thống của lần đó, hướng dẫn LLM hoàn thành bước quy trình làm việc (commit, push, v.v.) trước khi làm những gì bạn yêu cầu. | +| Claude Code | Cùng vòng lặp agent, ngay lập tức | Claude tiếp tục làm việc — sửa vấn đề, sau đó cố gắng hoàn thành lại. Không có sự gián đoạn hiển thị cho bạn. | +| Codex | Cùng vòng lặp agent, ngay lập tức | Giống như Claude. | +| GitHub Copilot CLI | Cùng vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng kênh `{decision:"block", reason}` retry của Copilot — đã xác minh theo kinh nghiệm đối với Copilot CLI 1.0.41). | +| Cursor Agent | Cùng vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng kênh `{followup_message}` của Cursor — bị giới hạn ở `loop_limit`, mặc định 5 lần thử lại). | +| Gemini CLI | Cùng vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng kênh `{decision:"block", reason}` của Gemini trên `AfterAgent`). | +| OpenCode | Cùng vòng lặp agent, ngay lập tức | Giống như Claude (sử dụng lệnh gọi SDK `client.session.prompt(...)` của OpenCode được định tuyến qua `hookSpecificOutput.additionalContext`). | +| **Pi (pi-coding-agent)** | **Lần tới người dùng** | **Pi dừng lại rõ ràng** khi cổng kích hoạt — vòng lặp agent của nó thoát và bạn quay lại dấu nhắc. Cổng sau đó kích hoạt lần tiếp theo bạn gửi dấu nhắc: failproofai thêm tiền tố `MANDATORY ACTION REQUIRED` vào lời nhắc hệ thống của lần đó, hướng dẫn LLM hoàn thành bước quy trình làm việc (commit, push, v.v.) trước khi làm bất cứ điều gì bạn yêu cầu. | -**Giới hạn Pi.** `AgentEndEvent` của Pi (tương đương thượng nguồn của hook `Stop` của Claude) không có loại Result — khi nó kích hoạt, vòng lặp agent của Pi đã thoát. Pi không thể bị buộc phải thử lại cùng một vòng lặp như Claude / Copilot / Cursor / Gemini / OpenCode có thể. failproofai chuyển cổng sang sự kiện `before_agent_start` của Pi (được kích hoạt sau lời nhắc người dùng tiếp theo) để kiểm tra quy trình làm việc vẫn thực thi, chỉ là ở lần tiếp theo thay vì hiện tại. +**Giới hạn Pi.** `AgentEndEvent` của Pi (tương đương thượng nguồn của hook `Stop` của Claude) không có loại Result — khi nó kích hoạt, vòng lặp agent của Pi đã thoát. Pi không thể bị buộc thử lại cùng một vòng lặp theo cách Claude / Copilot / Cursor / Gemini / OpenCode. failproofai thay đổi cổng sang sự kiện `before_agent_start` của Pi (được kích hoạt sau dấu nhắc người dùng tiếp theo) để kiểm tra quy trình làm việc vẫn thực thi, chỉ trên lần tới thay vì lần hiện tại. -**Điều này có nghĩa là gì trong thực tế:** +**Điều này có nghĩa gì trong thực tế:** -- Sau khi Pi dừng, lý do deny được lưu trong bộ nhớ được khóa theo id phiên Pi. Lời nhắc rất tiếp theo bạn gửi trong cùng một quy trình Pi xả nó: LLM thấy chỉ thị `MANDATORY ACTION REQUIRED` ở đầu lời nhắc hệ thống của nó, commit (hoặc push / mở PR / chờ CI) và chỉ sau đó tiếp tục với yêu cầu của bạn. Lý do deny được lưu lại là một lần — sau khi xả, cổng sạch. -- Cổng được giới hạn bởi thời gian sống của quy trình Pi. Nếu bạn `Ctrl+C` Pi hoặc thoát giữa các lần, mục trong bộ nhớ bị xóa cùng với quy trình và cổng bị bỏ lỡ. Claude, Copilot, Cursor, Gemini và OpenCode có cách ràng buộc tương tự (giết agent và cổng bị bỏ lỡ) — Pi chỉ làm nó rõ ràng hơn vì agent rõ ràng thoát trước khi cổng kích hoạt. -- Một deny đang chờ cũng bị xóa trên `session_shutdown` vì bất kỳ lý do gì (`new` / `resume` / `fork` / `quit`), vì vậy cổng cũ từ một phiên trước không thể rò rỉ vào một phiên mới được bắt đầu trong cùng một quy trình Pi. +- Sau khi Pi dừng lại, lý do từ chối được ghi vào bộ nhớ trong bằng id phiên Pi. Dấu nhắc rất tiếp theo bạn gửi trong cùng quy trình Pi lấy ra nó: LLM nhìn thấy chỉ thị `MANDATORY ACTION REQUIRED` ở đầu lời nhắc hệ thống của nó, commit (hoặc push / mở PR / chờ CI) và chỉ khi đó tiếp tục với yêu cầu của bạn. Lý do từ chối được ghi lại là một lần — sau khi lấy ra, cổng rõ ràng. +- Cổng bị ràng buộc bởi vòng đời quá trình Pi. Nếu bạn `Ctrl+C` Pi hoặc thoát giữa các lần, mục bộ nhớ trong được loại bỏ cùng với quá trình và cổng bị bỏ lỡ. Claude, Copilot, Cursor, Gemini và OpenCode có cùng ranh giới (giết agent và cổng bị bỏ lỡ) — Pi chỉ làm cho nó rõ ràng hơn vì agent rõ ràng thoát trước khi cổng kích hoạt. +- Một từ chối đang chờ cũng bị xóa trên `session_shutdown` vì lý do gì đó (`new` / `resume` / `fork` / `quit`), vì vậy cổng cũ từ phiên trước không thể bị rò rỉ vào phiên mới được khởi động trong cùng quy trình Pi. -Nếu bạn cần thử lại cùng một vòng lặp như Claude, chạy các chính sách `Stop` của bạn dưới bất kỳ trong sáu CLI được hỗ trợ khác. Chúng tôi đang theo dõi Pi thượng nguồn cho loại Result trong tương lai trên `AgentEndEvent` sẽ cho phép chúng tôi đóng khoảng trống này. +Nếu bạn cần thử lại cùng vòng lặp kiểu Claude, hãy chạy các chính sách `Stop` của bạn dưới bất kỳ sáu CLI được hỗ trợ khác. Chúng tôi đang theo dõi Pi thượng nguồn để có loại Result trong tương lai trên `AgentEndEvent` sẽ cho phép chúng tôi đóng khoảng cách này. ### `require-commit-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng khi có các thay đổi chưa commit (tệp được sửa đổi, tổ chức hoặc chưa theo dõi). Trả lại thông báo thông tin khi thư mục làm việc sạch. +**Mặc định:** Từ chối dừng lại khi có thay đổi chưa được xác nhận (tệp đã sửa đổi, được sắp xếp hoặc chưa theo dõi). Trả về thông báo thông tin khi thư mục làm việc sạch sẽ. Không có tham số. @@ -740,12 +746,12 @@ Không có tham số. ### `require-push-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng khi có các commit chưa push hoặc khi nhánh hiện tại không có nhánh remote theo dõi. Đề xuất `git push -u` để tạo nhánh theo dõi nếu cần. Thất bại mở nếu không có remote được cấu hình. +**Mặc định:** Từ chối dừng lại khi có các lần commit chưa được push hoặc khi nhánh hiện tại không có nhánh theo dõi từ xa. Gợi ý `git push -u` để tạo nhánh theo dõi nếu cần. Thất bại mở nếu không có remote được cấu hình. **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| +|--------|------|---------|-------| | `remote` | `string` | `"origin"` | Tên remote để push đến. | **Ví dụ:** @@ -765,13 +771,14 @@ Không có tham số. ### `require-pr-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng khi không có pull request nào tồn tại cho nhánh hiện tại, hoặc khi PR hiện có bị đóng mà không merge. Hướng dẫn Claude tạo PR bằng `gh pr create`. Khi PR được **merge**, chính sách cho phép (công việc đã được gửi) và thông báo gợi ý chuyển đổi ra khỏi nhánh (`git checkout main && git pull`). +**Mặc định:** Từ chối dừng lại khi không có yêu cầu pull tồn tại cho nhánh hiện tại hoặc khi PR hiện có bị đóng mà không merge. Hướng dẫn Claude tạo PR với `gh pr create`. Khi PR được **merge**, chính sách cho phép (công việc đã được gửi) và thông báo gợi ý chuyển ra khỏi nhánh (`git checkout main && git pull`). Không có tham số. Chính sách này yêu cầu [GitHub CLI](https://cli.github.com/) (`gh`) được cài đặt và xác thực. -Chạy `gh auth login` với token truy cập cá nhân có phạm vi `repo` để truy cập đọc pull request. Nếu `gh` không được cài đặt hoặc chưa được xác thực, chính sách thất bại mở và báo cáo lý do cho Claude. +Chạy `gh auth login` với token truy cập cá nhân có phạm vi `repo` để đọc +yêu cầu pull. Nếu `gh` không được cài đặt hoặc không xác thực, chính sách thất bại mở và báo cáo lý do cho Claude. --- @@ -779,24 +786,24 @@ Chạy `gh auth login` với token truy cập cá nhân có phạm vi `repo` đ ### `require-no-conflicts-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng khi nhánh hiện tại không thể sạch sẽ merge vào nhánh cơ sở. Chính sách trước tiên xác nhận có một PR `OPEN` trên GitHub cho nhánh — nếu không có, không có mục tiêu merge để thực thi, vì vậy toàn bộ chính sách rút ngắn để cho phép. Một khi PR `OPEN` được xác nhận, hai bộ thăm dò độc lập chạy: +**Mặc định:** Từ chối dừng lại khi nhánh hiện tại không thể merge sạch vào nhánh cơ sở. Chính sách trước tiên xác nhận có PR `OPEN` trên GitHub cho nhánh — nếu không có, không có mục tiêu merge để thực thi, vì vậy toàn bộ chính sách short-circuit cho phép. Khi PR `OPEN` được xác nhận, hai điều tra độc lập chạy: -1. **Cục bộ** — `git merge-tree --write-tree --name-only origin/ HEAD`. Về xung đột, thông báo deny đặt tên các tệp xung đột để Claude biết chính xác những gì cần giải quyết. -2. **GitHub** — sử dụng lại kết quả `gh pr view --json mergeable,state` đã được lấy trong kiểm tra trước. Nắm bắt các xung đột mà `origin/` cũ cục bộ sẽ bỏ lỡ (ví dụ: ai đó đã đưa PR xung đột trên `main` kể từ lần fetch cuối cùng). Kết quả `CONFLICTING` từ chối. Kết quả `UNKNOWN` cũng từ chối và hướng dẫn Claude chờ ~ 10 giây và kiểm tra lại trước khi cố gắng dừng lại — điều này ngăn chặn âm tính giả trong khi GitHub tính toán lại. +1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`. Xung đột, thông báo từ chối đặt tên các tệp xung đột để Claude biết chính xác phải giải quyết cái gì. +2. **GitHub** — tái sử dụng kết quả `gh pr view --json mergeable,state` đã được tìm nạp trong kiểm tra trước. Bắt những xung đột mà `origin/` cũ cục bộ sẽ bỏ lỡ (ví dụ: ai đó đã hạ cánh PR xung đột trên `main` kể từ lần tìm nạp cuối cùng). Kết quả `CONFLICTING` từ chối. Kết quả `UNKNOWN` cũng từ chối và hướng dẫn Claude chờ ~10 giây và kiểm tra lại trước khi cố gắng dừng lại lại — điều này ngăn chặn dương tính giả trong khi GitHub tính toán lại. -Bỏ qua hoàn toàn (cho phép) khi: `gh` không được cài đặt, không có PR cho nhánh, trạng thái PR không phải `OPEN` (ví dụ: `MERGED`, `CLOSED`), hoặc `gh pr view` trả về đầu ra không thể phân tích. Cũng thất bại mở khi `origin/` bị thiếu cục bộ hoặc khi không có commit trước cơ sở — những lỗi rơi qua Lớp 1 đó vẫn tham khảo khả năng merge PR được lưu trước khi cho phép. +Bỏ qua hoàn toàn (cho phép) khi: `gh` không được cài đặt, không có PR nào cho nhánh, trạng thái PR không phải `OPEN` (ví dụ: `MERGED`, `CLOSED`), hoặc `gh pr view` trả về kết quả không thể phân tích. Cũng thất bại mở khi `origin/` bị thiếu cục bộ hoặc khi không có commit trước cơ sở — những lần rơi qua Layer 1 đó vẫn tham khảo kết quả PR mergeability được lưu trong bộ nhớ cache trước khi cho phép. **Tham số:** | Tham số | Loại | Mặc định | Mô tả | -|-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Nhánh cơ sở để kiểm tra xung đột. | +|--------|------|---------|-------| +| `baseBranch` | `string` | `"main"` | Nhánh cơ sở để kiểm tra xung đột đối với. | -GitHub CLI (`gh`) được yêu cầu cho chính sách này. Chính sách sử dụng `gh pr view` để xác nhận -một PR `OPEN` tồn tại trước khi chạy bất kỳ bộ thăm dò xung đột nào — nếu không có `gh`, chính sách -rút ngắn để cho phép. Chạy `gh auth login` với token truy cập cá nhân có phạm vi -`repo` để truy cập đọc pull request. +GitHub CLI (`gh`) là bắt buộc cho chính sách này. Chính sách sử dụng `gh pr view` để xác nhận +một PR `OPEN` tồn tại trước khi chạy bất kỳ điều tra xung đột nào — nếu không có `gh`, chính sách +short-circuit cho phép. Chạy `gh auth login` với token truy cập cá nhân có +phạm vi `repo` để đọc yêu cầu pull. --- @@ -804,14 +811,14 @@ rút ngắn để cho phép. Chạy `gh auth login` với token truy cập cá n ### `require-ci-green-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng khi các kiểm tra CI đang thất bại hoặc vẫn đang chạy trên nhánh hiện tại. Kiểm tra cả chạy quy trình GitHub Actions và kiểm tra bot của bên thứ ba (ví dụ: CodeRabbit, SonarCloud, Codecov). Coi `skipped`, `cancelled` và `neutral` kết luận là không thất bại (điều sau bao gồm ví dụ: cảnh báo Socket Security trên PR của người đóng góp bên ngoài, nơi ứng dụng cố ý báo cáo neutral thay vì success/failure). Trả lại thông báo thông tin khi tất cả các kiểm tra vượt qua. +**Mặc định:** Từ chối dừng lại khi các kiểm tra CI đang thất bại hoặc vẫn chạy trên nhánh hiện tại. Kiểm tra cả công việc GitHub Actions workflow và các kiểm tra bot của bên thứ ba (ví dụ: CodeRabbit, SonarCloud, Codecov). Coi `skipped`, `cancelled` và `neutral` kết luận là không thất bại (cái sau bao gồm ví dụ: Socket Security alerts trên PR của người đóng góp bên ngoài, nơi ứng dụng cố tình báo cáo neutral thay vì success/failure). Trả về thông báo thông tin khi tất cả các kiểm tra vượt qua. Không có tham số. Chính sách này yêu cầu [GitHub CLI](https://cli.github.com/) (`gh`) được cài đặt và xác thực. -Chạy `gh auth login` với token truy cập cá nhân có phạm vi `repo` để truy cập đọc -chạy quy trình Actions và API Checks. Nếu `gh` không được cài đặt hoặc chưa được xác thực, chính sách thất bại mở và báo cáo lý do cho Claude. +Chạy `gh auth login` với token truy cập cá nhân có phạm vi `repo` để đọc +quy trình làm việc Actions và Checks API. Nếu `gh` không được cài đặt hoặc không xác thực, chính sách thất bại mở và báo cáo lý do cho Claude. --- @@ -820,7 +827,7 @@ chạy quy trình Actions và API Checks. Nếu `gh` không được cài đặt ## Vô hiệu hóa các chính sách riêng lẻ -Xóa một chính sách cụ thể khỏi `enabledPolicies` trong cấu hình của bạn, hoặc tắt nó trên tab Chính sách của bảng điều khiển. +Xóa một chính sách cụ thể khỏi `enabledPolicies` trong cấu hình của bạn hoặc bật tắt nó trên tab Policies của bảng điều khiển. ```json { diff --git a/docs/vi/cli/audit.mdx b/docs/vi/cli/audit.mdx index 060e5608..e7fcf00a 100644 --- a/docs/vi/cli/audit.mdx +++ b/docs/vi/cli/audit.mdx @@ -1,19 +1,19 @@ --- -title: Kiểm tra các phiên làm việc trước đó (beta) -description: "Đếm xem agent đã làm những việc lãng phí hoặc rủi ro bao nhiêu lần trong các bản ghi lịch sử trước đó" +title: Kiểm toán các phiên trước (beta) +description: "Đếm xem agent đã làm những việc lãng phí hoặc rủi ro bao nhiêu lần trên các bản ghi quá khứ" --- - **Tính năng beta.** Tính năng kiểm tra được phát hành dưới dạng beta trong khi chúng tôi thu thập phản hồi ban đầu. - Danh mục phát hiện và định dạng báo cáo có thể thay đổi trước bản phát hành ổn định tiếp theo. - Vui lòng mở một issue nếu có gì không ổn. + **Tính năng beta.** Công cụ kiểm toán được phát hành dưới dạng beta trong khi chúng tôi thu thập phản hồi ban đầu. + Danh mục detector và định dạng báo cáo có thể thay đổi trước bản ổn định tiếp theo. + Vui lòng tạo issue nếu bạn thấy bất cứ điều gì sai sót. -Tính năng kiểm tra sẽ phát lại các bản ghi lịch sử agent-CLI trước đó của bạn thông qua engine chính sách của failproofai và tạo ra một báo cáo hình ảnh có thể chia sẻ trên **trang `/audit` của bảng điều khiển** — kiểu mẫu agent của bạn, điểm từ 0–100 và chính xác những chính sách nào sẽ bắt được cái gì. +Công cụ kiểm toán sẽ phát lại các bản ghi quá khứ của agent-CLI qua engine chính sách của failproofai và tạo ra một báo cáo trực quan có thể chia sẻ trên **trang dashboard `/audit`** — kiểu mẫu của agent, điểm từ 0–100, và chính xác những chính sách nào sẽ phát hiện được điều gì. ## Chạy nó -Ba cách để bắt đầu — tất cả đều dẫn tới cùng một báo cáo `/audit`. +Ba cách để bắt đầu — tất cả đều dẫn đến cùng một báo cáo `/audit`. @@ -25,7 +25,7 @@ npx -y failproofai audit failproofai audit ``` -```bash failproofai (bảng điều khiển) +```bash failproofai (dashboard) failproofai ``` @@ -33,56 +33,56 @@ failproofai - `npx -y failproofai audit` tải failproofai, chạy quét, và mở bảng điều khiển cho bạn — không cần cài đặt gì trước. + `npx -y failproofai audit` tải failproofai, chạy quét, và mở dashboard cho bạn — không cần cài đặt trước. - `failproofai audit` chạy quét trong terminal của bạn, rồi tự động mở `localhost:8020/audit` khi hoàn thành. + `failproofai audit` chạy quét trong terminal của bạn, sau đó tự động mở `localhost:8020/audit` khi hoàn tất. - - Chạy `failproofai` và nhấp vào **Audit** trong thanh điều hướng (giữa Policies và Projects), hoặc mở `/audit` trực tiếp. + + Chạy `failproofai` và nhấp **Audit** trong navbar (giữa Policies và Projects), hoặc mở `/audit` trực tiếp. - Chạy `failproofai audit -h` (hoặc `--help`) để xem cách sử dụng. Tính năng kiểm tra chạy **hoàn toàn ngoại tuyến** — không cần tài khoản hoặc mạng — và bảng điều khiển tiếp tục phục vụ cho đến khi bạn dừng nó bằng `Ctrl+C`. + Chạy `failproofai audit -h` (hoặc `--help`) để xem cách sử dụng. Công cụ kiểm toán chạy **hoàn toàn ngoại tuyến** — không cần tài khoản hay mạng — và dashboard tiếp tục hoạt động cho đến khi bạn dừng nó bằng `Ctrl+C`. -Bảng điều khiển quét các bản ghi lịch sử agent CLI trước đó trên máy này (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) và báo cáo xem agent đã làm những việc mà failproofai được xây dựng để dừng bao nhiêu lần — kiểm tra biến môi trường, force push, tiền tố `cd ` dư thừa, vòng lặp sleep-polling, đọc lại tệp vừa sửa, và nhiều hơn nữa. +Dashboard quét các bản ghi agent CLI quá khứ trên máy này (Claude Code, Codex, Copilot, Cursor, OpenCode, Pi, Gemini) và báo cáo tần suất agent làm những việc mà failproofai được xây dựng để ngăn chặn — kiểm tra biến môi trường, force push, tiền tố `cd ` dư thừa, vòng lặp sleep-polling, đọc lại tệp vừa chỉnh sửa, và nhiều hơn nữa. -Đối với mỗi bản ghi lịch sử, mọi sự kiện sử dụng công cụ được phát lại thông qua 39 chính sách tích hợp **và** 8 bộ phát hiện chỉ dùng để kiểm tra bắt các mẫu chưa được bao phủ bởi các chính sách thời gian chạy. Số lượng được tổng hợp cho mỗi chính sách / bộ phát hiện trên tất cả các phiên. +Đối với mỗi bản ghi, mỗi sự kiện tool-use được phát lại thông qua 39 chính sách tích hợp **và** thông qua 8 detector chỉ dùng cho kiểm toán để phát hiện các mẫu chưa được bao phủ bởi các chính sách thời gian chạy. Các số được tổng hợp theo chính sách/detector trên tất cả các phiên. ## Những gì bạn nhận được -Trang `/audit` là một **áp phích** trên toàn màn hình, có thể chia sẻ được, theo sau là bốn phần phía dưới: +Trang `/audit` là một **áp phích** toàn màn hình có thể chia sẻ, theo sau bởi bốn phần dưới nền trang: -1. **Áp phích** — danh tính của agent của bạn một cách sơ lược: **kiểu mẫu** của nó (một trong 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), các từ khóa tính cách, mức độ hiếm có của kiểu mẫu đó, và **điểm từ 0–100** với một dải cấp bậc (`S` xuống `bottom tier`). Được xây dựng để chia sẻ — đăng trên X hoặc LinkedIn, hoặc tải xuống dưới dạng PNG. -2. **`// strengths`** — những gì agent của bạn đã làm tốt, dưới dạng các số thực từ quét (ví dụ: clean-tool-call %, `0` push-to-main attempts), chỉ được hiển thị khi chính sách liên quan có một hồ sơ sạch sẽ. -3. **`// quirks`** — những gì lọt qua: một bảng xếp hạng các hành vi mà failproofai sẽ bắt được — *khi nào* nó lần cuối xảy ra, *cái gì lọt qua* (và chính sách tích hợp sẽ chặn nó), **mức độ nghiêm trọng** của nó, và nó được **nhìn thấy** bao nhiêu lần (`new` / `recurring` / `N× seen`). -4. **`// how to improve`** — danh sách sửa chữa được quy định: một hàng cho mỗi chính sách với `failproofai policy add ` sao chép dán, cộng với nút **install all** cho phép mọi khuyến nghị cùng một lúc và hiển thị **projected score** của bạn nếu bạn làm. -5. **`// come back better`** — xây dựng thói quen: đặt **reminder** tái kiểm tra qua email (`3d` / `7d` / `14d` / `30d`) hoặc tái kiểm tra ngay bây giờ, và **mời một bạn** chạy kiểm tra của riêng họ (gửi từ failproof.ai, Cc cho bạn). Reminders và invites yêu cầu đăng nhập — xem [`failproofai auth`](/vi/cli/auth). +1. **Áp phích** — danh tính của agent một cách nhanh chóng: **kiểu mẫu** của nó (một trong 8 — `optimist`, `cowboy`, `explorer`, `goldfish`, `paranoid architect`, `precision builder`, `hammer`, `ghost`), các từ khóa tính cách của nó, mức độ hiếm của kiểu mẫu đó, và **điểm 0–100** với dải hạng (`S` cho đến `bottom tier`). Được xây dựng để chia sẻ — đăng lên X hoặc LinkedIn, hoặc tải xuống dưới dạng PNG. +2. **`// strengths`** — những gì agent của bạn đã làm tốt, dưới dạng các số thực từ quét (ví dụ: clean-tool-call %, `0` lần push-to-main), chỉ hiển thị nơi chính sách liên quan có hồ sơ sạch sẽ. +3. **`// quirks`** — những gì đã trượt qua: một bảng xếp hạng các hành vi mà failproofai sẽ phát hiện — *khi* nó lần cuối cùng xảy ra, *những gì đã trượt* (và built-in sẽ chặn nó), *mức độ nghiêm trọng* của nó, và *tần suất* nó *được nhìn thấy* (`new` / `recurring` / `N× seen`). +4. **`// how to improve`** — danh sách sửa chữa được quy định: một hàng trên mỗi chính sách với `failproofai policy add ` sao chép-dán, cộng với nút **install all** cho phép mọi đề xuất cùng một lúc và hiển thị **projected score** của bạn nếu bạn làm vậy. +5. **`// come back better`** — hình thành thói quen: đặt **reminder** kiểm toán lại qua email (`3d` / `7d` / `14d` / `30d`) hoặc kiểm toán lại ngay bây giờ, và **invite a friend** để chạy kiểm toán của riêng họ (được gửi từ failproof.ai, được Cc cho bạn). Reminder và lời mời cần đăng nhập — xem [`failproofai auth`](/vi/cli/auth). -## Bộ phát hiện chỉ dùng để kiểm tra +## Detector chỉ dùng cho kiểm toán -Những bộ này phát hiện các mẫu hành vi "ngu ngốc" không (chưa) được thực thi thời gian thực. Chúng chạy chỉ trong quá trình kiểm tra và không bao giờ chặn một lệnh gọi công cụ trực tiếp. +Những cái này phát hiện các mẫu hành vi "ngớ ngẩn" chưa được (thực thi) trong thời gian thực. Chúng chỉ chạy trong quá trình kiểm toán và không bao giờ chặn một lệnh tool gọi trực tiếp. -| Bộ phát hiện | Những gì nó đếm | +| Detector | Những gì nó đếm | |---|---| -| `redundant-cd-cwd` | Các lệnh Bash bắt đầu bằng `cd && …` mặc dù các lệnh đã chạy trong `cwd`. | -| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` trên một tệp nguồn duy nhất — sử dụng công cụ `Read`. | -| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` các chỉnh sửa tại chỗ — sử dụng công cụ `Edit`. | -| `prefer-write-over-heredoc` | Heredoc / multi-line `echo > file` ghi tệp — sử dụng công cụ `Write`. | -| `sleep-polling-loop` | `sleep N` dài (≥ 30s) hoặc `while …; sleep …; done` vòng lặp polling. | -| `find-from-root` | `find /`, `find /home`, `find /usr`, vv — giới hạn trong `cwd`. | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, bỏ qua hooks. | -| `reread-after-edit` | `Read` của tệp vừa được `Edit`/`Write` trong cùng một phiên. | +| `redundant-cd-cwd` | Lệnh Bash bắt đầu với `cd && …` mặc dù các lệnh đã chạy trong `cwd`. | +| `prefer-edit-over-read-cat` | `cat`/`head`/`tail`/`less`/`more` trên một tệp nguồn duy nhất — hãy sử dụng công cụ `Read`. | +| `prefer-edit-over-sed-awk` | `sed -i` / `awk … > file` chỉnh sửa tại chỗ — hãy sử dụng công cụ `Edit`. | +| `prefer-write-over-heredoc` | Heredoc / `echo > file` đa dòng ghi tệp — hãy sử dụng công cụ `Write`. | +| `sleep-polling-loop` | Long `sleep N` (≥ 30s) hoặc `while …; sleep …; done` vòng lặp polling. | +| `find-from-root` | `find /`, `find /home`, `find /usr`, v.v. — phạm vi đến `cwd` thay thế. | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`, bỏ qua hook. | +| `reread-after-edit` | `Read` của một tệp vừa được `Edit`/`Write` trong cùng một phiên. | ## Bộ nhớ đệm -- **Bộ nhớ đệm mỗi bản ghi lịch sử** tại `~/.failproofai/cache/audit/.json` được khóa bằng `(mtime, size, engineVersion, detectorVersion)` — tự động vô hiệu hóa khi bản ghi lịch sử hoặc mã chính sách/phát hiện thay đổi. Mỗi mục cũng lưu trữ dấu thời gian `cachedAt` làm **siêu dữ liệu TTL** (không phải một phần của khóa bộ nhớ đệm); các mục cũ hơn **7 ngày** bị từ chối khi đọc để các kết quả dài hạn không vượt quá ý định phát hiện khác nhau. -- **Bộ nhớ đệm toàn bộ kết quả** tại `~/.failproofai/audit-dashboard.json` (chế độ 0600). Cho phép bảng điều khiển hiển thị ngay lập tức khi điều hướng mà không cần chạy lại. Cũng bị từ chối khi đọc quá **TTL 7 ngày** — `/audit` sau đó rơi vào trạng thái trống của nó và nhắc nhở chạy làm mới. Nhấp vào `[ re-audit now ]` gần dưới cùng của báo cáo để làm mới — re-audit gửi `noCache: true`, vì vậy nó bỏ qua bộ nhớ đệm mỗi bản ghi lịch sử và quét lại mọi bản ghi lịch sử thay vì trả lại kết quả được lưu trong bộ nhớ đệm; lần chạy phát trực tiếp tiến độ thông qua một dải dính ở đầu và hoán đổi kết quả tại chỗ khi thành công (không tải lại trang; một re-audit không thành công sẽ giữ lại báo cáo trước đó). +- **Bộ nhớ đệm trên mỗi bản ghi** tại `~/.failproofai/cache/audit/.json` được khóa bởi `(mtime, size, engineVersion, detectorVersion)` — tự động vô hiệu hóa khi bản ghi hoặc mã chính sách/detector thay đổi. Mỗi mục nhập cũng lưu trữ dấu thời gian `cachedAt` như **siêu dữ liệu TTL** (không phải là một phần của khóa bộ nhớ đệm); các mục nhập cũ hơn **7 ngày** bị từ chối khi đọc để các kết quả lâu dài không vượt quá ý định detector phát triển. +- **Bộ nhớ đệm toàn bộ kết quả** tại `~/.failproofai/audit-dashboard.json` (chế độ 0600). Cho phép dashboard hiển thị ngay lập tức khi điều hướng mà không cần chạy lại. Cũng bị từ chối khi đọc quá **7 ngày TTL** — `/audit` sau đó rơi vào trạng thái trống và nhắc chạy lại. Nhấp `[ re-audit now ]` gần phía dưới của báo cáo để làm mới — kiểm toán lại gửi `noCache: true`, vì vậy nó bỏ qua bộ nhớ đệm trên mỗi bản ghi và quét lại mỗi bản ghi thay vì trả về kết quả được lưu trong bộ nhớ đệm; chạy phát trực tuyến tiến trình qua một dải trên cùng dính và hoán đổi kết quả tại chỗ khi thành công (không tải lại trang; một lần kiểm toán lại không thành công sẽ giữ báo cáo trước đó). ## Ghi chú -- **Không có đột biến.** Tính năng kiểm tra phát lại ở chế độ chỉ đọc. `warn-repeated-tool-calls` bị bỏ qua vì sidecar mỗi phiên của nó sẽ bị sửa đổi. -- **Chính sách quy trình bị bỏ qua.** `require-*-before-stop` chính sách chỉ kích hoạt trên `Stop` sự kiện và `execSync` so với trạng thái git trực tiếp — chúng không có ý nghĩa "điều gì sẽ xảy ra vào năm 2025" giải thích, vì vậy chúng không xuất hiện trong số đếm kiểm tra. -- **Chính sách tùy chỉnh bị bỏ qua.** Các hook tùy chỉnh được cung cấp bởi người dùng không được phát lại (chúng có thể đã thay đổi kể từ phiên gốc). \ No newline at end of file +- **Không có đột biến.** Kiểm toán phát lại ở chế độ chỉ đọc. `warn-repeated-tool-calls` bị bỏ qua vì sidecar trên mỗi phiên của nó sẽ bị sửa đổi nếu không. +- **Chính sách workflow bị bỏ qua.** Các chính sách `require-*-before-stop` chỉ kích hoạt trên các sự kiện `Stop` và `execSync` đối với trạng thái git trực tiếp — chúng không có cách diễn giải có ý nghĩa "những gì sẽ xảy ra vào năm 2025", vì vậy chúng không xuất hiện trong số kiểm toán. +- **Chính sách tùy chỉnh bị bỏ qua.** Hook tùy chỉnh do người dùng cung cấp không được phát lại (chúng có thể đã thay đổi kể từ phiên gốc). \ No newline at end of file diff --git a/docs/vi/cli/auth.mdx b/docs/vi/cli/auth.mdx index 04cf5955..5ad6ac01 100644 --- a/docs/vi/cli/auth.mdx +++ b/docs/vi/cli/auth.mdx @@ -1,17 +1,17 @@ --- title: Đăng nhập -description: "Đăng nhập vào FailproofAI từ CLI để bật nhắc nhở và các tính năng được cá nhân hóa" +description: "Đăng nhập vào FailproofAI từ CLI để bật các lời nhắc và tính năng cá nhân hóa" --- ```bash -failproofai auth login # email + mã một lần -failproofai auth logout # thu hồi phiên này -failproofai auth whoami # in danh tính đã đăng nhập +failproofai auth login # email + one-time code +failproofai auth logout # revoke this session +failproofai auth whoami # print the signed-in identity ``` -Dạng cờ cũ `--login` / `--logout` / `--whoami` vẫn được chấp nhận như một bí danh để tương thích ngược. +Dạng cờ legacy `--login` / `--logout` / `--whoami` vẫn được chấp nhận như một bí danh để tương thích ngược. -Xác thực là tùy chọn. Các chính sách, bảng điều khiển, trang `/audit`, và mọi tính năng cục bộ khác hoạt động hoàn toàn giống nhau cho dù bạn đã đăng nhập hay chưa. Giao diện đăng nhập tồn tại để các tính năng **cần** một danh tính ổn định (nhắc nhở tái kiểm toán ngày hôm nay, nhiều tính năng hơn trong tương lai) có nơi để neo. +Xác thực là tùy chọn. Policies, dashboard, trang `/audit`, và mọi tính năng cục bộ khác hoạt động giống nhau dù bạn đã đăng nhập hay chưa. Giao diện đăng nhập tồn tại để các tính năng **cần** một danh tính ổn định (những lời nhắc kiểm toán lại ngay hôm nay, nhiều hơn trong tương lai) có chỗ để neo. ## Luồng đăng nhập @@ -19,9 +19,9 @@ Xác thực là tùy chọn. Các chính sách, bảng điều khiển, trang `/ failproofai auth login ``` -Yêu cầu nhập email của bạn, gửi mã một lần 6 chữ số đến địa chỉ đó, yêu cầu nhập mã, và khi thành công sẽ ghi `~/.failproofai/auth.json` (chế độ `0600`). Cùng phiên đó sẽ hiển thị trong bảng điều khiển trong ứng dụng — nhấp vào `[ set a reminder ]` trên `/audit` sẽ thấy bạn đã đăng nhập. +Yêu cầu email của bạn, gửi mã một lần 6 chữ số đến địa chỉ đó, yêu cầu mã, và khi thành công sẽ ghi `~/.failproofai/auth.json` (chế độ `0600`). Phiên làm việc tương tự sau đó sẽ hiển thị trên dashboard trong ứng dụng — nhấp vào `[ set a reminder ]` trên `/audit` sẽ thấy bạn đã đăng nhập. -Bảng điều khiển hiển thị cùng một luồng như một hộp thoại phương thức trên `/audit` cho những người dùng không bao giờ sử dụng CLI. +Dashboard hiển thị cùng luồng dưới dạng hộp thoại phương thức trên `/audit` cho những người dùng không bao giờ sử dụng CLI. ## Đăng xuất @@ -29,7 +29,7 @@ Bảng điều khiển hiển thị cùng một luồng như một hộp thoại failproofai auth logout ``` -Thu hồi phiên hiện tại trên máy chủ và xóa `~/.failproofai/auth.json`. Nếu máy chủ api không thể truy cập được, tệp cục bộ sẽ bị xóa bất kể — ý định cục bộ để đăng xuất luôn thắng. +Thu hồi phiên làm việc hiện tại trên máy chủ và xóa `~/.failproofai/auth.json`. Nếu máy chủ API không thể truy cập được, tệp cục bộ sẽ bị xóa dù sao — ý định cục bộ để đăng xuất luôn thắng. ## Kiểm tra danh tính @@ -37,11 +37,11 @@ Thu hồi phiên hiện tại trên máy chủ và xóa `~/.failproofai/auth.jso failproofai auth whoami ``` -In ` ()` và thoát 0 khi một phiên hợp lệ tồn tại, hoặc `not signed in` và thoát 1 trong trường hợp khác. Yên tĩnh làm mới mã truy cập trong nền nếu nó trong vòng một phút sắp hết hạn. +In ra ` ()` và thoát với mã 0 khi tồn tại phiên làm việc hợp lệ, hoặc in ra `not signed in` và thoát với mã 1 nếu không. Im lặng làm mới token truy cập ở nền tảng nếu nó cách hết hạn dưới một phút. -## Nhắc nhở tái kiểm toán dai dẳng +## Lời nhắc kiểm toán lại liên tục -Khi bạn nhấp vào **`[ set a reminder ]`** trên trang `/audit` (hoặc đăng nhập thông qua phương thức mà nút đó kiểm soát truy cập), bảng điều khiển sẽ ghi một tệp đồng hành nhỏ tại `~/.failproofai/next-audit.json`: +Khi bạn nhấp vào **`[ set a reminder ]`** trên trang `/audit` (hoặc đăng nhập qua hộp thoại phương thức mà nút gating), dashboard sẽ ghi một tệp đi kèm nhỏ tại `~/.failproofai/next-audit.json`: ```json { @@ -51,11 +51,11 @@ Khi bạn nhấp vào **`[ set a reminder ]`** trên trang `/audit` (hoặc đă } ``` -Tệp này được giới hạn trong phạm vi email mà nó được đặt cho — chuyển phiên CLI sang một tài khoản khác sẽ ẩn bất kỳ nhắc nhở nào thuộc về người dùng trước đó. Độ lệch mặc định là **7 ngày**, có thể cấu hình sau khi trình lập lịch được triển khai. Được tạo với quyền `0600` như `auth.json`. +Tệp này được xác định phạm vi cho email nó được đặt — chuyển phiên CLI sang tài khoản khác sẽ ẩn bất kỳ lời nhắc nào thuộc về người dùng trước đó. Độ lệch mặc định là **7 ngày**, có thể cấu hình sau khi trình lập lịch được phát hành. Được tạo với quyền `0600` giống như `auth.json`. -Điểm cuối `/api/auth/reminder` của bảng điều khiển hiển thị `GET` (đọc), `POST` (đặt / sắp xếp lại), và `DELETE` (xóa) và yêu cầu một phiên hoạt động. +Điểm cuối `/api/auth/reminder` của dashboard hiển thị `GET` (đọc), `POST` (đặt / lên lịch lại), và `DELETE` (xóa) và yêu cầu một phiên làm việc hoạt động. -## Cái gì nằm trong `~/.failproofai/auth.json` +## Nội dung của `~/.failproofai/auth.json` ```json { @@ -67,21 +67,21 @@ Tệp này được giới hạn trong phạm vi email mà nó được đặt c } ``` -Được tạo với quyền `0600` (chỉ chủ sở hữu có thể đọc/ghi). Mã truy cập là JWT HS256 1 giờ; mã làm mới là một chuỗi ngẫu nhiên 256-bit không rõ ràng mà máy chủ lưu trữ dưới dạng `SHA-256(token)`. Phát lại mã làm mới được phát hiện phía máy chủ và thu hồi mọi phiên cho người dùng. +Được tạo với quyền `0600` (đọc/ghi chỉ dành cho chủ sở hữu). Token truy cập là JWT HS256 1 giờ; token làm mới là một chuỗi ngẫu nhiên không rõ ràng 256 bit mà máy chủ lưu trữ dưới dạng `SHA-256(token)`. Phát lại token làm mới được phát hiện ở phía máy chủ và thu hồi mọi phiên làm việc cho người dùng. -## Các biến môi trường +## Biến môi trường | Biến | Mặc định | Mục đích | |---|---|---| -| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | Ghi đè URL cơ sở máy chủ api. Hữu ích cho phát triển cục bộ dựa trên máy chủ api tự lưu trữ. | -| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | Ghi đè vị trí lưu trữ `auth.json`. Chủ yếu cho các bài kiểm tra. | +| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | Ghi đè URL cơ sở máy chủ API. Hữu ích cho phát triển cục bộ so với máy chủ API tự lưu trữ. | +| `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | Ghi đè nơi `auth.json` được lưu trữ. Chủ yếu dành cho các bài kiểm tra. | -Xem [Các biến môi trường](/vi/cli/environment-variables) để có danh sách đầy đủ. +Xem [Environment variables](/vi/cli/environment-variables) để xem danh sách đầy đủ. ## Khắc phục sự cố -**"Could not reach the api-server"** — CLI không thể mở kết nối TCP đến `FAILPROOF_API_URL`. Kiểm tra mạng của bạn, hoặc đặt `FAILPROOF_API_URL` nếu bạn đang chạy máy chủ api tự lưu trữ. +**"Could not reach the api-server"** — CLI không thể mở kết nối TCP đến `FAILPROOF_API_URL`. Kiểm tra mạng của bạn, hoặc đặt `FAILPROOF_API_URL` nếu bạn đang chạy máy chủ API tự lưu trữ. -**"Rate limited"** — quá nhiều lần thử đăng nhập trong cửa sổ 15 phút cho email đó (5/email) hoặc IP (20/IP), hoặc thời gian chờ gửi lại 30 giây sau yêu cầu trước đó cho cùng email. Thông báo lỗi bao gồm cửa sổ retry-after tính bằng giây. +**"Rate limited"** — quá nhiều nỗ lực đăng nhập trong cửa sổ 15 phút cho email đó (5/email) hoặc IP (20/IP), hoặc hết thời gian gửi lại 30 giây sau yêu cầu trước đó cho cùng email. Thông báo lỗi bao gồm cửa sổ thử lại trong vài giây. -**Code rejected** — OTP sai, hết hạn, hoặc hàng đó chạm vào khóa 5 lần đoán sai. Chạy `failproofai auth login` lại để yêu cầu mã mới. \ No newline at end of file +**Code rejected** — OTP sai, hết hạn, hoặc hàng đó đạt khóa 5 lần đoán sai. Chạy `failproofai auth login` lại để yêu cầu mã mới. \ No newline at end of file diff --git a/docs/vi/cli/dashboard.mdx b/docs/vi/cli/dashboard.mdx index 54f8bea3..c384451f 100644 --- a/docs/vi/cli/dashboard.mdx +++ b/docs/vi/cli/dashboard.mdx @@ -1,29 +1,29 @@ --- title: Xem các phiên làm việc -description: "Khởi động bảng điều khiển để duyệt các phiên của agent và quản lý chính sách" +description: "Khởi chạy bảng điều khiển để duyệt các phiên hoạt động của agent và quản lý chính sách" --- ```bash failproofai ``` -Khởi động bảng điều khiển web tại `http://localhost:8020`. +Khởi chạy bảng điều khiển web tại `http://localhost:8020`. ## Tùy chọn -| Cờ | Mô tả | +| Flag | Mô tả | |------|-------------| | `--port ` | Cổng để lắng nghe (mặc định: `8020`) | -| `--allowed-origins ` | Các host/IP được phép truy cập tài nguyên dev, ngăn cách bằng dấu phẩy | +| `--allowed-origins ` | Các host/IP được phân tách bằng dấu phẩy được phép truy cập tài nguyên dev | -Để trỏ bảng điều khiển đến thư mục dự án Claude không phải mặc định, hãy đặt biến môi trường `CLAUDE_PROJECTS_PATH` khi khởi động. +Để trỏ bảng điều khiển đến thư mục dự án Claude không phải mặc định, hãy đặt biến môi trường `CLAUDE_PROJECTS_PATH` khi khởi chạy. ## Ví dụ ```bash -# Khởi động trên một cổng khác +# Launch on a different port failproofai --port 9000 -# Sử dụng đường dẫn dự án Claude tùy chỉnh thông qua biến môi trường +# Use a custom Claude projects path via environment variable CLAUDE_PROJECTS_PATH=~/my-claude-projects failproofai ``` \ No newline at end of file diff --git a/docs/vi/cli/environment-variables.mdx b/docs/vi/cli/environment-variables.mdx index d0e4fab7..9574aff1 100644 --- a/docs/vi/cli/environment-variables.mdx +++ b/docs/vi/cli/environment-variables.mdx @@ -1,47 +1,47 @@ --- title: Biến môi trường -description: "Cấu hình hành vi failproofai bằng biến môi trường" +description: "Cấu hình hành vi failproofai bằng các biến môi trường" --- ## Dashboard | Biến | Mô tả | |----------|-------------| -| `PORT` | Cổng Dashboard (mặc định: `8020`) | -| `CLAUDE_PROJECTS_PATH` | Ghi đè vị trí tìm kiếm thư mục dự án Claude Code | -| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Các trang dashboard được ẩn, cách nhau bằng dấu phẩy | -| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Các máy chủ/IP được phép truy cập tài nguyên phát triển. Tương tự như `--allowed-origins`. | +| `PORT` | Cổng dashboard (mặc định: `8020`) | +| `CLAUDE_PROJECTS_PATH` | Ghi đè vị trí tìm thấy thư mục dự án Claude Code | +| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Các trang dashboard cách nhau bằng dấu phẩy để ẩn | +| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Host/IP được phép truy cập tài nguyên dev. Tương tự như `--allowed-origins`. | ## Logging | Biến | Mô tả | |----------|-------------| -| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Mức độ nhật ký máy chủ (mặc định: `warn`) | -| `FAILPROOFAI_HOOK_LOG_FILE` | Đường dẫn tệp nhật ký hook tùy chỉnh, hoặc `true` cho mặc định (`~/.failproofai/logs/hooks.log`) | +| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Cấp độ log của server (mặc định: `warn`) | +| `FAILPROOFAI_HOOK_LOG_FILE` | Đường dẫn tập tin log hook tùy chỉnh, hoặc `true` cho mặc định (`~/.failproofai/logs/hooks.log`) | ## Telemetry | Biến | Mô tả | |----------|-------------| -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Vô hiệu hóa telemetry sử dụng nặc danh | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Tắt telemetry sử dụng ẩn danh | ## Authentication | Biến | Mô tả | |----------|-------------| -| `FAILPROOF_API_URL` | Ghi đè URL cơ sở api-server được sử dụng bởi `failproofai auth` và hộp thoại xác thực dashboard. Mặc định là `https://api.befailproof.ai`; đặt thành `http://localhost:8080` (hoặc nơi khác) khi chạy api-server cục bộ. | -| `FAILPROOFAI_AUTH_DIR` | Ghi đè vị trí lưu trữ `auth.json` (mặc định: `~/.failproofai`). Chủ yếu hữu ích cho các bài kiểm tra cô lập. | +| `FAILPROOF_API_URL` | Ghi đè URL cơ sở api-server được sử dụng bởi `failproofai auth` và hộp thoại xác thực dashboard. Mặc định là `https://api.befailproof.ai`; đặt thành `http://localhost:8080` (hoặc bất kỳ đâu) khi chạy api-server cục bộ. | +| `FAILPROOFAI_AUTH_DIR` | Ghi đè nơi lưu trữ `auth.json` (mặc định: `~/.failproofai`). Hầu hết hữu ích cho các bài kiểm tra cách ly. | -## First-run prompt +## Lời nhắc lần đầu chạy | Biến | Mô tả | |----------|-------------| -| `FAILPROOFAI_NO_FIRST_RUN=1` | Bỏ qua lời nhắc cài đặt chính sách lần đầu tiên khi gọi `failproofai` | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Bỏ qua lời nhắc cung cấp cài đặt chính sách lần đầu gọi `failproofai` trống | -## LLM (cho đánh giá chính sách) +## LLM (để đánh giá chính sách) | Biến | Mô tả | |----------|-------------| -| `FAILPROOFAI_LLM_BASE_URL` | Điểm cuối LLM API (mặc định: `https://api.openai.com/v1`) | -| `FAILPROOFAI_LLM_API_KEY` | Khóa API cho các chính sách được hỗ trợ bởi LLM | +| `FAILPROOFAI_LLM_BASE_URL` | Điểm cuối API LLM (mặc định: `https://api.openai.com/v1`) | +| `FAILPROOFAI_LLM_API_KEY` | Khóa API cho các chính sách hỗ trợ LLM | | `FAILPROOFAI_LLM_MODEL` | Tên mô hình (mặc định: `gpt-4o-mini`) | \ No newline at end of file diff --git a/docs/vi/cli/hook.mdx b/docs/vi/cli/hook.mdx index 975be338..04b30e9e 100644 --- a/docs/vi/cli/hook.mdx +++ b/docs/vi/cli/hook.mdx @@ -1,30 +1,30 @@ --- title: Hook handler (internal) -description: "Tiến trình con mà Claude Code gọi tại mỗi sự kiện công cụ" +description: "Subprocess mà Claude Code gọi trên mỗi sự kiện công cụ" --- ```bash failproofai --hook ``` -Đây là lệnh được đăng ký trong `settings.json` của Claude Code bởi `failproofai policies --install`. Bình thường bạn không gọi lệnh này trực tiếp. +Đây là lệnh được đăng ký trong `settings.json` của Claude Code bởi `failproofai policies --install`. Bình thường bạn không gọi trực tiếp lệnh này. -Đọc một payload JSON từ stdin, đánh giá tất cả các chính sách được bật, và thoát với một mã chỉ thị quyết định: +Đọc một payload JSON từ stdin, đánh giá tất cả các chính sách được bật, và thoát với một mã chỉ định quyết định: | Mã thoát | Quyết định | Hiệu ứng | -|-----------|-----------|---------| -| `0` | `allow` | Cho phép thực hiện hành động | -| `1` | `deny` | Chặn hành động - Claude nhìn thấy lý do từ chối | -| `2` | `instruct` | Tiêm hướng dẫn vào ngữ cảnh của Claude | +|-----------|------------|---------| +| `0` | `allow` | Cho phép hành động | +| `1` | `deny` | Chặn hành động - Claude sẽ thấy lý do từ chối | +| `2` | `instruct` | Đưa hướng dẫn vào ngữ cảnh của Claude | ### Các loại sự kiện được hỗ trợ | Danh mục | Sự kiện | -|----------|--------| +|----------|---------| | **Thực thi công cụ** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` | | **Vòng đời phiên** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` | | **Tương tác người dùng** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` | -| **Đại lý phụ & nhiệm vụ** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | +| **Subagents & nhiệm vụ** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` | | **Cấu hình** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` | | **Hệ thống tệp** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` | | **Ngữ cảnh** | `PreCompact`, `PostCompact` | \ No newline at end of file diff --git a/docs/vi/cli/install-policies.mdx b/docs/vi/cli/install-policies.mdx index 9f2bb467..cb856894 100644 --- a/docs/vi/cli/install-policies.mdx +++ b/docs/vi/cli/install-policies.mdx @@ -1,47 +1,47 @@ --- -title: Cài đặt policies -description: "Bật policies để chúng chạy trên mọi lệnh gọi công cụ của agent" +title: Cài đặt chính sách +description: "Kích hoạt các chính sách để chúng chạy trên mọi lệnh gọi công cụ của agent" --- ```bash failproofai policies --install [policy-names...] [options] ``` -Ghi các mục hook vào tệp cài đặt của agent CLI đã cài đặt (Claude Code, OpenAI Codex, hoặc GitHub Copilot CLI _(beta)_) để failproofai có thể chặn các lệnh gọi công cụ. +Ghi các mục hook vào tệp cài đặt của CLI agent được cài đặt (Claude Code, OpenAI Codex, hoặc GitHub Copilot CLI _(beta)_) để failproofai chặn các lệnh gọi công cụ. Bí danh: `failproofai p -i` -## Các tùy chọn +## Tùy chọn | Cờ | Mô tả | |------|-------------| -| `--cli claude\|codex\|copilot` | Agent CLI(s) để cài đặt; cách nhau bằng dấu cách (ví dụ: `--cli claude codex copilot`) hoặc lặp lại. Bỏ qua để phát hiện các CLI đã cài đặt và nhắc nhở. | +| `--cli claude\|codex\|copilot` | CLI agent được cài đặt cho; cách nhau bằng dấu cách (ví dụ: `--cli claude codex copilot`) hoặc lặp lại. Bỏ qua để tự động phát hiện CLI được cài đặt và nhắc. | | `--scope user` | Cài đặt vào tệp cài đặt phạm vi người dùng (Claude: `~/.claude/settings.json`; Codex: `~/.codex/hooks.json`; Copilot: `~/.copilot/hooks/failproofai.json`). Mặc định. | | `--scope project` | Cài đặt vào tệp cài đặt phạm vi dự án (Claude: `/.claude/settings.json`; Codex: `/.codex/hooks.json`; Copilot: `/.github/hooks/failproofai.json`). | | `--scope local` | Chỉ Claude — cài đặt vào `/.claude/settings.local.json`. Codex và Copilot không có phạm vi `local`. | -| `--custom ` / `-c` | Đường dẫn đến tệp JS chứa các policies hook tùy chỉnh | +| `--custom ` / `-c` | Đường dẫn đến tệp JS chứa các chính sách hook tùy chỉnh | ## Hành vi -- **Không có tên policy** - mở một lời nhắc tương tác để chọn policies -- **Tên cụ thể** - bật các policies đó (được thêm vào bất kỳ policies nào đã được bật) -- **`all`** - bật tất cả các policies có sẵn +- **Không có tên chính sách** - mở lời nhắc tương tác để chọn chính sách +- **Tên cụ thể** - kích hoạt những chính sách đó (thêm vào bất kỳ chính sách nào đã được kích hoạt) +- **`all`** - kích hoạt mọi chính sách có sẵn -Cài đặt là cộng dồn: chạy `--install` lại sẽ thêm các policies mới mà không xóa các policies hiện có. +Cài đặt là phụ gia: chạy `--install` lại sẽ thêm các chính sách mới mà không xóa các chính sách hiện có. ## Ví dụ ```bash -# Cài đặt tất cả default policies toàn cục (tương tác) +# Cài đặt tất cả các chính sách mặc định toàn cầu (tương tác) failproofai policies --install -# Cài đặt policies cụ thể cho dự án hiện tại +# Cài đặt các chính sách cụ thể cho dự án hiện tại failproofai policies --install block-sudo sanitize-api-keys --scope project -# Bật tất cả policies cùng một lúc +# Kích hoạt tất cả các chính sách cùng một lúc failproofai policies --install all -# Cài đặt với tệp policies tùy chỉnh +# Cài đặt với tệp chính sách tùy chỉnh failproofai policies --install --custom ./my-policies.js # Cài đặt cho OpenAI Codex (phạm vi dự án) @@ -54,4 +54,4 @@ failproofai policies --install --cli copilot --scope project failproofai policies --install --cli claude codex copilot ``` -Khi `--custom ` được cung cấp, tệp sẽ được xác thực ngay lập tức - nó phải gọi `customPolicies.add()` ít nhất một lần. Đường dẫn được phân giải sẽ được lưu vào `policies-config.json` dưới dạng `customPoliciesPath`. \ No newline at end of file +Khi cung cấp `--custom `, tệp được xác thực ngay lập tức - nó phải gọi `customPolicies.add()` ít nhất một lần. Đường dẫn được giải quyết được lưu vào `policies-config.json` với tên `customPoliciesPath`. \ No newline at end of file diff --git a/docs/vi/cli/list-policies.mdx b/docs/vi/cli/list-policies.mdx index 3103f5a4..134ebf66 100644 --- a/docs/vi/cli/list-policies.mdx +++ b/docs/vi/cli/list-policies.mdx @@ -1,13 +1,13 @@ --- title: Liệt kê các chính sách -description: "Xem các chính sách nào được bật, các tham số của chúng và các chính sách tùy chỉnh" +description: "Xem những chính sách nào được bật, các tham số của chúng và các chính sách tùy chỉnh" --- ```bash failproofai policies ``` -Hiển thị tất cả các chính sách cùng với trạng thái, các tham số đã cấu hình và các chính sách tùy chỉnh. +Hiển thị tất cả các chính sách cùng với trạng thái, các tham số đã cấu hình và các chính sách tùy chỉnh của chúng. ## Ví dụ về kết quả đầu ra @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -Các khóa không xác định trong `policyParams` sẽ được đánh dấu ở đây để bạn có thể bắt các lỗi đánh máy sớm. \ No newline at end of file +Các khóa không xác định trong `policyParams` sẽ được đánh dấu ở đây để bạn có thể phát hiện những lỗi đánh máy sớm. \ No newline at end of file diff --git a/docs/vi/cli/remove-policies.mdx b/docs/vi/cli/remove-policies.mdx index 4a119712..68218b0b 100644 --- a/docs/vi/cli/remove-policies.mdx +++ b/docs/vi/cli/remove-policies.mdx @@ -1,43 +1,43 @@ --- -title: Gỡ cài đặt policies -description: "Xóa hook entries từ settings của Claude Code" +title: Gỡ cài đặt chính sách +description: "Xoá các mục hook từ cài đặt Claude Code" --- ```bash failproofai policies --uninstall [policy-names...] [options] ``` -Xóa các hook entries của failproofai từ `settings.json` của Claude Code. +Xoá các mục hook của failproofai từ `settings.json` của Claude Code. -Alias: `failproofai p -u` +Bí danh: `failproofai p -u` -## Options +## Các tùy chọn -| Flag | Description | +| Cờ | Mô tả | |------|-------------| -| `--scope user` | Xóa từ global settings (mặc định) | -| `--scope project` | Xóa từ project settings | -| `--scope local` | Xóa từ local settings | -| `--scope all` | Xóa từ tất cả scopes cùng một lúc | -| `--custom` / `-c` | Xóa `customPoliciesPath` khỏi config | +| `--scope user` | Xoá từ cài đặt toàn cục (mặc định) | +| `--scope project` | Xoá từ cài đặt dự án | +| `--scope local` | Xoá từ cài đặt cục bộ | +| `--scope all` | Xoá từ tất cả các phạm vi cùng một lúc | +| `--custom` / `-c` | Xoá `customPoliciesPath` khỏi cấu hình | -## Behavior +## Hành vi -- **Không có tên policy** - xóa tất cả failproofai hook entries từ settings file -- **Tên cụ thể** - vô hiệu hóa những policies đó nhưng giữ lại hooks đã cài đặt +- **Không có tên chính sách** - xoá tất cả các mục hook của failproofai khỏi tệp cài đặt +- **Tên cụ thể** - vô hiệu hoá những chính sách đó nhưng giữ lại các hook đã cài đặt -## Examples +## Ví dụ ```bash -# Xóa tất cả hooks toàn cục +# Remove all hooks globally failproofai policies --uninstall -# Vô hiệu hóa một policy cụ thể (giữ lại hooks đã cài đặt) +# Disable a specific policy (keeps hooks installed) failproofai policies --uninstall block-sudo -# Xóa hooks từ mọi scope +# Remove hooks from every scope failproofai policies --uninstall --scope all -# Xóa đường dẫn custom policies +# Clear custom policies path failproofai policies --uninstall --custom ``` \ No newline at end of file diff --git a/docs/vi/cli/version.mdx b/docs/vi/cli/version.mdx index e4c02bce..8430c3c6 100644 --- a/docs/vi/cli/version.mdx +++ b/docs/vi/cli/version.mdx @@ -1,6 +1,6 @@ --- title: Kiểm tra phiên bản -description: "In ra phiên bản failproofai đã cài đặt" +description: "In phiên bản failproofai đã cài đặt" --- ```bash diff --git a/docs/vi/configuration.mdx b/docs/vi/configuration.mdx index e5db1851..d94dff4c 100644 --- a/docs/vi/configuration.mdx +++ b/docs/vi/configuration.mdx @@ -4,54 +4,54 @@ 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 các chính sách nào đang hoạt động, 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 - cam kết nó vào kho lưu trữ của bạn và mọi nhà phát triển sẽ 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 đ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. --- -## Các phạm vi cấu hình +## Phạm vi cấu hình 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 cho mỗi kho, được cam kết vào kiểm soát phiên bản | -| **local** | `.failproofai/policies-config.local.json` | Ghi đè cục bộ cho mỗi kho, được gitignore | -| **global** | `~/.failproofai/policies-config.json` | Giá trị mặc định cấp người dùng trên tất cả các dự án | +| **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 | +| **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 một 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ó 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. ### Quy tắc hợp nhất -**`enabledPolicies`** - hợp của cả ba phạm vi. Một chính sách được bật ở bất kỳ cấp nào đều hoạt động. +**`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. ```text project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← hợp đã khử trùng +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← loại bỏ trùng lặp ``` -**`policyParams`** - phạm vi đầu tiên xác định tham số cho một chính sách nhất định sẽ chiến thắng hoàn toàn. Không có hợp nhất sâu của các giá trị trong 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 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. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← project chiến thắng, global bị bỏ qua +resolved: { allowPatterns: ["sudo apt-get update"] } ← project thắng, global bị bỏ qua ``` ```text -project: (không có mục block-sudo) -local: (không có mục block-sudo) +project: (no block-sudo entry) +local: (no block-sudo entry) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← rơi vào global +resolved: { allowPatterns: ["sudo systemctl status"] } ← rơi xuống global ``` -**`customPoliciesPath`** - phạm vi đầu tiên xác định nó sẽ chiến thắng. +**`customPoliciesPath`** - phạm vi đầu tiên xác định nó sẽ thắng. -**`llm`** - phạm vi đầu tiên xác định nó sẽ chiến thắng. +**`llm`** - phạm vi đầu tiên xác định nó sẽ thắng. --- @@ -100,81 +100,81 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← rơi vào global ### `enabledPolicies` -Kiểu: `string[]` +Loại: `string[]` -Danh sách tên chính sách cần bậ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 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 đủ. -Các chính sách không có trong `enabledPolicies` không hoạt động, ngay cả khi chúng có các mục trong `policyParams`. +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`. ### `policyParams` -Kiểu: `Record>` +Loại: `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à dành riêng cho từng 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ố 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). -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 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` hoàn toàn sẽ nhận được hành vi giống hệt như 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 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 đó. -Các khóa không xác định bên trong khối tham số của chính sách bị 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`. +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`. #### `hint` (cross-cutting) -Kiểu: `string` (tùy chọn) +Loại: `string` (tùy chọn) -Một thông điệp được nối 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 hướng dẫn có thể hành động cho Claude 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 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. -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/`). +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/`). ```json { "policyParams": { "block-force-push": { - "hint": "Hãy thử tạo một nhánh mới." + "hint": "Try creating a fresh branch instead." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], - "hint": "Sử dụng apt-get trực tiếp mà không cần sudo." + "hint": "Use apt-get directly without sudo." }, "custom/my-policy": { - "hint": "Yêu cầu sự phê duyệt của người dùng trước." + "hint": "Ask the user for approval first." } } } ``` -Khi `block-force-push` từ chối, Claude sẽ thấy: *"Force-pushing bị chặn. Hãy thử tạo một nhánh mới."* +Khi `block-force-push` từ chối, Claude sẽ 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 rỗ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). +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). ### `customPoliciesPath` -Kiểu: `string` (đường dẫn tuyệt đối) +Loại: `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ữ). -Tệp được tải lại trên mỗi sự kiện hook - không có bộ đệm. Xem [Custom Policies](/vi/custom-policies) để biết chi tiết tác giả. +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ả. ### Cá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 | +| Cấp độ | Thư mục | Phạm vi | |-------|-----------|-------| -| Dự án | `.failproofai/policies/` | Chia sẻ với nhóm 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 | +| 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 | -**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ớ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ông cần cấu hình:** Các chính sách quy ước không yêu cầu các mục trong `policies-config.json`. Chỉ cần thả các tệp vào thư mục và chúng sẽ được chọn khi sự kiện hook tiếp theo xảy ra. +**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. -**Tải hợp:** Cả hai thư mục quy ước dự án và người dùng được quét. Tất cả các tệp khớp từ cả hai cấp đều được tải (không giống `customPoliciesPath` sử dụng first-scope-wins). +**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). Xem [Custom Policies](/vi/custom-policies) để biết thêm chi tiết và ví dụ. ### `llm` -Kiểu: `object` (tùy chọn) +Loại: `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 lệnh gọi AI. Không cần thiết cho hầu hết các thiết lập. +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. ```json { @@ -189,19 +189,20 @@ 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ọ ## 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 vào hook), trong khi `policies-config.json` là tệp bạn quản lý trực tiếp. Hai tệp 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 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ài đặt Agent CLI** — yêu cầu agent gọi `failproofai --hook ` trên mỗi 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 hook sử dụng các trường lệnh `bash`/`powershell` được xác định theo hệ điều hành của Copilot 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. - - **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 hook sử dụng hình thức `{type, command, timeout}` dạng Claude (không 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 [hooks schema](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ý chính tắc hóa camelCase → PascalCase thông qua `CURSOR_EVENT_MAP` để các chính sách tích hợp sẵn hiện có kích hoạt không thay đổi. Hỗ trợ Cursor Agent là **beta** trong khi chúng tôi xác minh định dạng bảng điểm của Cursor trên đĩa (không được chỉ định trong tài liệu công khai) so với nhiều 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ông giống như sáu 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 trong quy 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 các plugin được tải trên opencode v1.14.33). Install thả một shim plugin nhỏ được tạo ra gọi lệnh phụ vào nhị phân failproofai và dịch phản hồi JSON dạng Claude của nhị phân trở lại ngữ semantics plugin: `throw new Error()` để từ chối sự kiện công cụ (hủy lệnh gọi công cụ), `client.session.prompt(...)` để instruct VÀ để từ chối `Stop` / `SubagentStop` (gửi lý do từ chối làm thông điệp người dùng tiếp theo — kênh retry-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 phép. Shim chính tắc hóa cả tên công cụ (chữ thường → PascalCase qua `OPENCODE_TOOL_MAP`) và các 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 chính sách 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 sống trong cơ sở dữ liệu SQLite của opencode tại `~/.local/share/opencode/opencode.db`; trình 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 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 nhiều 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 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ỏ vào thư mục `pi-extension/` được đóng gói của nó. Phần mở rộng trội theo dõi các sự kiện `tool_call` / `user_bash` / `input` / `session_start` của Pi và lệnh shell tới `failproofai --hook --cli pi`; trình xử lý chính tắc hóa underscore_lower_snake_case → PascalCase thông qua `PI_EVENT_MAP` để các chính sách tích hợp sẵn hiện có kích hoạt không thay đổi. Các đối số đầu vào công cụ cũng được chính tắc hóa qua `PI_TOOL_INPUT_MAP` (Pi's Read / Write / Edit giao `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ó một dự phòng `path`). Hỗ trợ Pi là **beta** trong khi API mở rộng Pi và bố cục nhật ký phiên ổn định. - - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (người dùng), `/.gemini/settings.json` (dự án) — Gemini không có phạm vi `local` (nó ghi lại một phạm vi `system` tại `/etc/gemini-cli/settings.json` mà failproofai không hiển thị). Các mục hook sử dụng hình thức `{type, command, timeout}` của Claude được bao bọc trong lược đồ bộ khớp `{matcher, hooks: [...]}` của Gemini với `matcher: "*"` theo mặc định. Các sự kiện là PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); trình xử lý ánh xạ tới các tên canonical Claude qua `GEMINI_EVENT_MAP`. Tên công cụ là snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — trình xử lý chính tắc hóa qua `GEMINI_TOOL_MAP` để các chính sách tích hợp sẵn hiện có kích hoạt không thay đổi. Đánh giá chính sách phát ra hình dạng phẳng `{decision: "deny", reason}` của Gemini (ưa thích theo "Golden Rule" hợp đồng exit-0 của Gemini), `{hookSpecificOutput: {hookEventName, additionalContext}}` để tiêm bối cảnh trên BeforeAgent / AfterTool / SessionStart, và `{decision: "block", reason}` trên AfterAgent để sử dụng ngữ semantics retry-buộc. Hỗ trợ Gemini CLI là **beta** trong khi chúng tôi mở rộng độ bao phủ thực tế. Xem [tài liệu hooks Gemini CLI](https://geminicli.com/docs/hooks/). -- **`policies-config.json`** — yêu cầu failproofai đánh giá chính sách nào và với những tham số nào (dùng chung trên tất cả các CLI agent) +- **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ư sáu 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. + - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (user), `/.gemini/settings.json` (project) — Gemini không có phạm vi `local` (nó ghi lại phạm vi `system` tại `/etc/gemini-cli/settings.json` mà failproofai không tiếp xúc). Các mục nhập hook sử dụng dạng `{type, command, timeout}` của Claude được bao bọc trong lược đồ matcher `{matcher, hooks: [...]}` của Gemini với `matcher: "*"` theo mặc định. Các sự kiện là PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); trình xử lý ánh xạ đến tên Claude canonical qua `GEMINI_EVENT_MAP`. Tên công cụ là snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — trình xử lý chuẩn hóa qua `GEMINI_TOOL_MAP` vì vậy các chính sách built-in hiện có kích hoạt không thay đổi. Trình đánh giá chính sách phát hành hình dạng phẳng `{decision: "deny", reason}` của Gemini (ưu tiên theo Golden Rule exit-0 contract của Gemini), `{hookSpecificOutput: {hookEventName, additionalContext}}` cho tiêm ngữ cảnh trên BeforeAgent / AfterTool / SessionStart, và `{decision: "block", reason}` trên AfterTool cho ngữ nghĩa thử lại buộc. Hỗ trợ Gemini CLI đang ở **beta** khi chúng tôi mở rộng phạm vi thế giới thực. Xem [tài liệu hooks Gemini CLI](https://geminicli.com/docs/hooks/). + - **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) -Chuyển `--cli claude|codex|copilot|cursor|opencode|pi|gemini` để nhắm mục tiêu 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 hợp con nào): +Chuyển `--cli claude|codex|copilot|cursor|opencode|pi|gemini|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): ```bash failproofai policies --install --cli codex --scope project @@ -210,21 +211,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 gemini --scope project +failproofai policies --install --cli hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` -Khi `--cli` bị bỏ qua, `failproofai` phát hiện CLI agent nào được cài đặt (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): +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 gemini` / `which hermes`): - **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 chọn đơn với phím mũi tên được nhóm thành một phần `Detected (N)` (với một hàng tổng hợp `Install for all N detected` + từng CLI được phát hiện riêng lẻ) và một phần `Not installed (M) · install hooks ahead of time` liệt kê mọi CLI được hỗ trợ chưa được phát hiện như một 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 Detected. -- **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ó cái nào được phát hiện** — quay trở lại `claude`, với 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 ghi để nó kích hoạt ngay khi bạn cài đặt một lệnh. +- **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. -Bạn có thể chỉnh sửa `policies-config.json` trực tiếp bất cứ 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. +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. --- -## Ví dụ: cấu hình cấp dự án có giá trị mặc định nhóm +## Ví dụ: cấu hình cấp dự án với mặc định nhóm Cam kết `.failproofai/policies-config.json` vào kho lưu trữ của bạn: @@ -245,4 +247,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 các đồ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) để ghi đè cá nhân mà không ảnh hưởng đến đồng đội. \ No newline at end of file diff --git a/docs/vi/custom-policies.mdx b/docs/vi/custom-policies.mdx index 90af6c47..ffb18d56 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 của riêng bạn bằng JavaScript - thực thi quy ước, ngăn chặn sự trôi dạt, phát hiện các lỗi, tích hợp với các hệ thống bên ngoài" +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" 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 sự trôi dạt, kiểm soát các hoạt động phá hủy, phát hiện các agent bị mắc kẹt, hoặc tích hợp với Slack, quy trình phê duyệt, v.v. 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 có sẵn. +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. --- @@ -41,46 +41,46 @@ failproofai policies --install --custom ./my-policies.js ### Tùy chọn 1: Dựa trên quy ước (được khuyến nghị) -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ác cờ hoặc thay đổi cấu hình. Điều này hoạt động như git hooks: thả một tệp, nó chỉ hoạt động. +Đặ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. ``` -# Mức dự án — được cam kết vào git, chia sẻ với nhóm +# Project level — committed to git, shared with the team .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# Mức người dùng — cá nhân, áp dụng cho tất cả các dự án +# User level — personal, applies to all projects ~/.failproofai/policies/my-policies.mjs ``` **Cách nó hoạt động:** -- Cả hai thư mục dự án và người dùng được quét (hợp nhất — không phải chiến thắng phạm vi đầu tiên) +- 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 (mở lỗi cho mỗi tệp) -- Hoạt động cùng với các chính sách `--custom` rõ ràng và có sẵn +- 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ác chính sách quy ước là cách dễ nhất để xây dựng tiêu chuẩn chất lượng cho tổ chức của bạn. Cam kết `.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 mỗi 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. Theo thời gian, những điều này 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. +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. ### Tùy chọn 2: Đường dẫn tệp rõ ràng ```bash -# Cài đặt với một tệp chính sách tùy chỉnh +# Install with a custom policies file failproofai policies --install --custom ./my-policies.js -# Thay thế đường dẫn tệp chính sách +# Replace the policies file path failproofai policies --install --custom ./new-policies.js -# Xóa đường dẫn chính sách tùy chỉnh khỏi cấu hình +# Remove the custom policies path from config failproofai policies --uninstall --custom ``` -Đường dẫn tuyệt đối được giải quyết được lưu trữ trong `policies-config.json` dưới dạng `customPoliciesPath`. 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. +Đườ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. ### Sử dụng cả hai cùng nhau -Các chính sách quy ước và tệp `--custom` rõ ràng có thể coexist. Thứ tự tải: +Các chính sách theo quy ước và 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) @@ -90,7 +90,7 @@ Các chính sách quy ước và tệp `--custom` rõ ràng có thể coexist. T ## API -### Nhập khẩu +### Import ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -98,7 +98,7 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -Đăng ký một chính sách. Gọi điều này bao nhiêu lần cần thiết 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 bao nhiêu lần tùy ý cho nhiều chính sách trong cùng một tệp. ```ts customPolicies.add({ @@ -109,34 +109,34 @@ customPolicies.add({ }); ``` -### Các trợ giúp quyết định +### Trợ giúp quyết định | 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 | | `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 cho agent ngữ cảnh bổ sung để duy trì theo dõi | +| `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 | -`deny(message)` - thông báo xuất hiện trước Claude với tiền tố `"Blocked by failproofai:"`. Một `deny` duy nhất sẽ ngắn mạch tất cả các đánh giá tiếp theo. +`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. -`instruct(message)` - thông báo được thêm 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à được gửi cùng nhau. +`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. -Bạn có thể thêm hướng dẫn bổ sung 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 [Cấu hình → 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ỳ 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. -### Các thông báo allow có thông tin +### Thông báo allow thông tin -`allow(message)` cho phép hoạt động **và** gửi lại một thông báo thông tin cho Claude. Thông báo được gửi dưới dạng `additionalContext` trong phản hồi stdout của trình xử lý hook — cơ chế giống như được sử dụng bởi `instruct`, nhưng có nghĩa khác: nó là một cập nhật trạng thái, không phải cảnh báo. +`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. | 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 lý do 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 tại sao kiểm tra bị bỏ qua | -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ở lỗi:** `allow("GitHub CLI not installed, skipping CI check.")` — cho Claude biết lý do tại sao kiểm tra bị bỏ qua để nó có đầy đủ ngữ cảnh -- **Nhiều thông báo tích lũy:** nếu nhiều chính sách mỗi cái trả về `allow(message)`, tất cả các thông báo được nối với dòng mới và gửi cùng nhau +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 ```js customPolicies.add({ @@ -162,24 +162,24 @@ customPolicies.add({ | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | | `toolName` | `string \| undefined` | Công cụ đang đượ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` | Toàn bộ payload sự kiện thô từ Claude Code | +| `payload` | `Record` | Payload sự kiện thô đầy đủ từ Claude Code | | `session` | `SessionMetadata \| undefined` | Ngữ cảnh phiên (xem bên dưới) | ### Các trường `SessionMetadata` | Trường | Loại | Mô tả | |-------|------|-------------| -| `sessionId` | `string` | Mã định danh phiên Claude Code | +| `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 | ### Các loại sự kiện -| Sự kiện | Khi nó xảy ra | Nội dung `toolInput` | +| 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) | -| `Notification` | Khi Claude gửi thông báo | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - các hook phải luôn trả về `allow()`, chúng không thể chặn thông báo | +| `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 +188,20 @@ customPolicies.add({ Các chính sách được đánh giá theo thứ tự này: -1. Các chính sách có sẵn (theo thứ tự định nghĩa) +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ừ dự án `.failproofai/policies/` (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ừ người dùng `~/.failproofai/policies/` (tệp theo thứ tự bảng chữ cái, thứ tự `.add()` bên trong) +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) -`deny` đầu tiên sẽ ngắn mạch tất cả các chính sách tiếp theo. Tất cả các thông báo `instruct` được tích lũy và được gửi cùng nhau. +`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. --- -## Nhập bắc cầu +## Các import chuyển tiếp -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á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ể import các mô-đun cục bộ bằng cách sử dụng các đường dẫn tương đối: ```js // my-policies.js @@ -218,13 +218,13 @@ customPolicies.add({ }); ``` -Tất cả các nhập bắc cầu có thể truy cập được từ tệp mục nhập được giải quyết. Điều này được triển khai bằng cách viết lại các nhập `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 tương thích ESM. +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. --- ## Lọc loại sự kiện -Sử dụng `match.events` để giới hạn khi chính sách xảy ra: +Sử dụng `match.events` để giới hạn khi một chính sách kích hoạt: ```js customPolicies.add({ @@ -238,22 +238,22 @@ customPolicies.add({ }); ``` -Bỏ qua `match` hoàn toàn để xảy ra trên mỗi loại sự kiện. +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 **mở lỗi**: các lỗi không bao giờ chặn các chính sách có sẵn hoặc làm hỏng trình xử lý hook. +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. | 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à có 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`; các chính sách có sẵn tiếp tục | -| Lỗi cú pháp/nhập (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/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 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 hơn 10 giây | Hết giờ đượ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 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` | | Thư mục quy ước bị thiếu | Không có chính sách quy ước chạy; không có lỗi | @@ -323,14 +323,14 @@ export { customPolicies }; ## Ví dụ -Thư mục `examples/` chứa các tệp chính sách sẵn sàng để chạy: +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 đầu bao gồm các chế độ lỗi agent phổ biến | -| `examples/policies-advanced/index.js` | Các mô hình nâng cao: nhập bắc cầu, lệnh gọi không đồng bộ, xóa đầu ra, và các 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 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 ghi kiểm toán) | +| `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ữ) | ### Sử dụng các ví dụ tệp rõ ràng @@ -350,4 +350,4 @@ mkdir -p ~/.failproofai/policies cp examples/convention-policies/*.mjs ~/.failproofai/policies/ ``` -Không cần lệnh cài đặt — các tệp được nhặt lên tự động trên sự kiện hook tiếp theo. \ No newline at end of file +Không cần lệnh cài đặt — các tệp được chọn tự động trên sự kiện hook tiếp theo. \ No newline at end of file diff --git a/docs/vi/dashboard.mdx b/docs/vi/dashboard.mdx index f3c9f813..219cbd9b 100644 --- a/docs/vi/dashboard.mdx +++ b/docs/vi/dashboard.mdx @@ -1,6 +1,7 @@ --- -title: Dashboard -description: "Giám sát các phiên làm việc của agent, xem lại các lệnh gọi công cụ và quản lý chính sách" +--- +title: Bảng điều khiển +description: "Giám sát các phiên làm việc của agent, xem xét các lệnh gọi công cụ và quản lý chính sách" icon: chart-line --- @@ -16,7 +17,7 @@ failproofai Mở tại `http://localhost:8020`. -Bảng điều khiển đọc trực tiếp từ hệ thống tệp tin - các thư mục dự án Claude Code và các tệp cấu hình failproofai của bạn. Không có gì được ghi vào dịch vụ từ xa. +Bảng điều khiển đọc trực tiếp từ hệ thống tệp - các thư mục dự án Claude Code và các tệp cấu hình failproofai. Không có gì được ghi vào dịch vụ từ xa. --- @@ -24,67 +25,67 @@ Bảng điều khiển đọc trực tiếp từ hệ thống tệp tin - các t ### Dự án -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)_ và Gemini CLI _(beta)_ đượ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 chép 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 từng `~/.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ư phương án dự phòng) để tìm giá trị `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 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 chép 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 dự án Gemini CLI được khám phá bằng cách quét `~/.gemini/tmp//chats/session--.jsonl` (có thể cấu hình thông qua `GEMINI_SESSIONS_DIR`) và khôi phục cwd chính thức từ dấu đánh dấu văn bản `.project_root` kế bên. Một dự án đã được sử dụng bởi nhiều CLI sẽ hiển thị dưới dạng một hàng có 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 một agent CLI 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|gemini`. +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)_, Gemini CLI _(beta)_ và Hermes được tìm thấy trên máy của bạn. Các dự án Claude được phát hiện từ `~/.claude/projects/` (hoặc đường dẫn được đặt bởi `CLAUDE_PROJECTS_PATH`); các dự án Codex được phát hiện bằng cách quét mỗi bản ghi tạm 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 phát hiện bằng cách quét từng `~/.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 phát hiện 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 qua `CURSOR_HOME`, với `conversations/` và `sessions/` được thử như giải pháp thay thế) cho một vô hướng `cwd` trong `meta.json` / `session.json` / `workspace.yaml`; các dự án OpenCode được phát hiện bằng cách truy vấn cơ sở dữ liệu SQLite của nó tại `~/.local/share/opencode/opencode.db` 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 phát hiện bằng cách quét bản ghi tạm JSONL cho 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 dự án Gemini CLI được phát hiện bằng cách quét `~/.gemini/tmp//chats/session--.jsonl` (có thể cấu hình qua `GEMINI_SESSIONS_DIR`) và khôi phục cwd chính tắc từ dấu `.project_root` phía bên cạnh; các phiên cổng Hermes được đọc trực tiếp từ kho lưu trữ SQLite của nó tại `~/.hermes/state.db` (có thể cấu hình qua `HERMES_DB_PATH`) và được nhóm thành các dự án `hermes-` theo `source` (Slack/Telegram/cli/cron — các phiên cổng không có cwd). Một dự án đã được sử dụng bởi nhiều CLI được 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 một agent CLI cụ thể; URL lưu lựa chọn của bạn dưới dạng `?cli=claude|codex|copilot|cursor|opencode|pi|gemini|hermes`. Mỗi dự án hiển thị: - Tên dự án (được lấy từ đường dẫn thư mục) -- Một huy hiệu CLI — `Claude Code` (cam), `OpenAI Codex` (tím), `GitHub Copilot` (xanh), `Cursor Agent` (ngọc bích), `OpenCode` (hổ phách), `Pi` (hồng) và/hoặc `Gemini CLI` (bầu trời) -- Ngày hoạt động phiên làm việc gần đây nhất +- Một huy hiệu CLI — `Claude Code` (cam), `OpenAI Codex` (tím), `GitHub Copilot` (xanh), `Cursor Agent` (lục bảo), `OpenCode` (hổ phách), `Pi` (hồng), `Gemini CLI` (xanh da trời) và/hoặc `Hermes` (chàm) +- Ngày của 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 +### Phiên -Liệt kê tất cả các phiên làm việc trong một dự án. Mỗi phiên làm việc hiển thị: -- ID phiên làm việc +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ụ -- Số lượng hoạt động móc (chính sách được kích hoạt) +- Số lượng cuộc gọi công cụ +- Số lượng hoạt động hook (chính sách được kích hoạt) -Sử dụng bộ lọc khoảng thời gian và tìm kiếm ID phiên làm việc để thu hẹp danh sách. Các phiên làm việc được chia trang. +Sử dụng bộ lọc phạm vi ngày và tìm kiếm ID phiên để thu hẹp danh sách. Các phiên được phân trang. -Nhấp vào một phiên làm việc để mở trình xem phiên làm việc. +Nhấp vào một phiên để mở trình xem phiên. -### Trình xem phiên làm việc +### Trình xem phiên -Trình xem phiên làm việc trả lời câu hỏi chính cho các agent tự trị: agent đã làm gì và liệu nó có ở đúng con đường không? Một huy hiệu CLI bên cạnh tiêu đề cho biết phiên làm việc có phải là Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi hay Gemini CLI. Nó hiển thị một dòng thời gian của tất cả những gì đã xảy ra trong một phiên làm việc: +Trình xem phiên trả lời câu hỏi quan trọng cho các agent tự động: agent đã làm gì, và nó có duy trì được theo dõi không? Một huy hiệu CLI bên cạnh tiêu đề cho biết phiên là bản ghi Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Gemini CLI hay Hermes. 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** - Các phản hồi văn bản của Claude và các 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 input và output 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 được kích hoạt và quyết định nào mà chúng trả về +- **Tin nhắn** - Các phản hồi văn bản và lời nhắc của người dùng từ Claude +- **Cuộc gọi công cụ** - Mọi công cụ mà Claude gọi, cùng với đầu vào và đầu ra +- **Hoạt động chính sách** - Đối với mỗi lệnh gọi công cụ, các chính sách nào được kích hoạt và quyết định nào họ trả về -Thanh thống kê ở trên cùng hiển thị thời lượng phiên làm việc, tổng số lệnh gọi công cụ và một tóm tắt các quyết định móc (số lượng cho phép / từ chối / hướng dẫn). +Thanh thống kê ở phía 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 nút **Tải xuống Nhật ký** để xuất phiên làm việc. Đối với các phiên làm việc Claude Code, Codex, Copilot, Cursor, Pi và Gemini, bạn nhận được bảng ghi chép JSONL trên đĩa gốc byte-for-byte; đối với OpenCode (các phiên làm việc của nó nằm trong SQLite, không phải trên đĩa), bạn nhận được 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, Pi và Gemini, bạn sẽ nhận được bản ghi JSONL trên đĩa nguyên gốc byte-for-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 một 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 được điều khiển bởi tính cách về cách agent của bạn thực sự hoạt động trên các phiên làm việc trong quá khứ. Chạy lần quét giống như CLI `failproofai audit` nhưng hiển thị nó dưới dạng một trang duy nhất có thể chia sẻ + bốn phần ẩn bên dưới: +Một báo cáo được chạy bằng tính cách của cách agent của bạn thực sự hoạt động trên các phiên trong quá khứ. Chạy cùng một quá trình quét như CLI `failproofai audit` nhưng hiển thị nó dưới dạng một tấm poster có thể chia sẻ trên một màn hình duy nhất + bốn phần dưới ngữ cảnh: -1. **Áp phích** — lấp đầy viewport đầu tiên. Vùng chụp PNG độc lập với logo failproof_ai + nhãn kiểm toán · chỉ số mẫu vốn (`№ NN of 08`) + ngày kiểm toán · điểm số số (0–100) + viên xếp hạng phần trăm (`top 15%`) · tên mẫu vốn (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 · dòng `// only N% of agents are this archetype` · ô sigil tile 8×8 pixel · `audit yours → failproof.ai` chân trang. Ba nút chia sẻ nằm ngoài hộp chụp: `post your archetype` (ý định X), `share on linkedin`, `download poster`. Chụp chạy qua `html-to-image` để PNG khớp với bản render trên màn hình từng pixel (viền nét đứt, mặt nạ logo SVG, gradients, 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 ✓ của các hành vi mà agent của bạn đã làm đúng, được lấy từ dữ liệu kiểm toán trực tiếp (tỷ lệ lệnh gọi công cụ sạch sẽ, 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 retry) — mỗi cái chỉ được hiển thị khi chính sách liên quan có hồ sơ sạch sẽ trên toàn bộ cửa sổ kiểm toán. -3. **Những tính kỳ lạ** — bảng những gì trượt qua, được 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 đó lần xuất hiện đọc là `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, một cho mỗi chính sách được quy định: tên chính sách bằng trắng, mô tả một dòng, lệnh cài đặt + nút sao chép ở bên phải. Tiêu đề phần đọc `enable all N → projected · ` (điểm bạn sẽ đạt được với mọi bản sửa lỗi đượ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ẻ cạnh nhau. Trái: đặt một lời nhắc nhở (`3d` / `7d` / `14d` / `30d` chọn nhịp độ; duy trì 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 chấp nhận danh sách email của bạn được phân tách bằng dấu phẩy/khoảng trắng/xuống dòng (tối đa 10 lần gửi), POSTS chúng đến `/api/audit/invite`, chuyển tiếp đến `/api/audit/invite` của máy chủ api `POST /v0/invite`. 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 được Cc'd 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 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` đầu tiên để email của người gửi được biết trước khi lời mời được gửi đi. Thực hiện quyền lợi / perks là một công việc tiếp theo. +1. **Poster** — lấp đầy khung nhìn đầu tiên. Vùng chụp PNG độc lập với biểu tượng failproof_ai + nhãn kiểm toán · chỉ số kiến trúc (`№ NN of 08`) + ngày kiểm toán · điểm số (0–100) + xếp hạng phần trăm (`top 15%`) · tên kiến trúc (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 · ô sigil pixel 8×8 · chân trang `audit yours → failproof.ai`. Ba nút chia sẻ nằm ngay bên 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 bản kết xuất trên màn hình pixel-for-pixel (đường viền đứt nét, mặt nạ logo SVG, gradient, số liệu phông chữ — tất cả đều được bảo toàn). +2. **Điểm mạnh** — dòng danh sách yên tĩnh ✓ các hành vi 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ệ gọi công cụ sạch, không có đẩy trực tiếp vào chính, không rò rỉ thông tin xác thực, không có cơn bão thử lại) — mỗi cái chỉ được hiển thị khi chính sách liên quan có bản ghi sạch trên cửa sổ kiểm toán. +3. **Những điều lạ lùng** — bảng những gì bị bỏ qua, được xếp hạng theo mức độ nghiêm trọng: `when · what slipped + the policy that would've caught it · severity pill · seen`, nơi sự tái diễn đọc `new` (một lần), `N× seen` (2–9 lần), hoặc `recurring` (10+). +4. **Cách cải thiện** — dòng danh sách yên tĩnh, một cho mỗi chính sách được quy định: tên chính sách bằng 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 bạn sẽ đạt được với mọi sửa chữa được áp dụng), và nó `[install all]` nút 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ẻ cạnh nhau. Bên trái: đặt nhắc nhở (`3d` / `7d` / `14d` / `30d` bộ chọn tần suất; được giữ qua `/api/auth/reminder` sau khi xác thực). Bên phải: mở khóa các đặc quyền failproof — `invite a friend` mở một modal nhận một danh sách các 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 lần gửi), POSTs chúng đến `/api/audit/invite`, được chuyển tiếp đến `/v0/invite` `POST` 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 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. Người dùng ẩn danh được định tuyến qua `AuthDialog` trước tiên để email của người gửi được biết trước khi lời mời được gửi. Quyền lợi / thực hiện đặc quyền là một bước tiếp theo. -Được thúc đẩy 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ộ đệm cho mỗi bảng ghi chép. Bảng điều khiển lưu vào bộ đệm kết quả mới nhất tại `~/.failproofai/audit-dashboard.json` (chế độ `0600`, slot đơn, các lần chạy mới sẽ ghi đè) để các lần revisit nhanh tức thì; **cả bộ đệm cho mỗi bảng ghi chép và bộ đệm kết quả toàn bộ đều bị từ chối khi đọc khi chúng cũ hơn 7 ngày** để bảng điều khiển không bao giờ im lặng phục vụ kết quả cũ một tuần — quá TTL `/audit` giảm xuống trạng thái trống của nó và nhắc chạy lại. Nhấp `[ re-audit now ]` gần dưới cùng của báo cáo POSTs `/api/audit/run` với `noCache: true` — re-audit bỏ qua bộ đệm cho mỗi bảng ghi chép và quét lại mọi bảng ghi chép từ đầu thay vì im lặng trả về kết quả được lưu vào bộ đệm — và bảng điều khiển thăm dò `/api/audit/status` ở tần số 1Hz cho đến khi lần chạy hoàn thành; một dải tiến trình hồng dính pins ở trên cùng của viewport trong quá trình chạy với bộ đếm thời gian trôi qua, và kết quả mới được hoán đổi vào vị trí khi thành công (không tải lại trang đầy đủ; một re-audit 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 sang đỏ với sao chép được khóa từ `RerunError.kind` (`timeout` / `network` / `post_failed`). Trạng thái trống (không có bộ đệm hoặc hết hạn) và trạng thái không có phiên (bộ đệm tồn tại nhưng lần quét không tìm thấy bảng ghi chép) được hiển thị riêng biệt. +Được điều khiển bởi thời gian chạy `failproofai audit` — xem [Audit CLI](/vi/cli/audit) cho công cụ quét cơ bản, các cờ được hỗ trợ và các bất biến bộ nhớ đệm trên mỗi bản ghi. Bảng điều khiển lưu vào bộ nhớ đệm kết quả mới nhất tại `~/.failproofai/audit-dashboard.json` (chế độ `0600`, một khe 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ớ đệm trên mỗi bản ghi và toàn bộ kết quả sẽ 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ờ âm thầm phục vụ kết quả một tuần tuổi — quá TTL `/audit` rơi vào trạng thái trống rỗng của nó và nhắc chạy lại. Nhấp `[ re-audit now ]` gần phía dưới của báo cáo POSTs `/api/audit/run` với `noCache: true` — kiểm toán lại bỏ qua bộ nhớ đệm trên mỗi bản ghi và quét lại mỗi bản ghi từ đầu thay vì âm thầm trả về kết quả được lưu vào bộ nhớ đệm — và bảng điều khiển bỏ phiếu `/api/audit/status` ở 1Hz cho đến khi chạy xong; một dải tiến trình hồng dính ghìm vào đầu trang khung nhìn trong lần chạy với bộ hẹn giờ đã trôi qua, và kết quả mới nhất hoán đổi vị trí khi thành công (không tải lại trang đầy đủ; một lần kiểm toán lại không thành công để báo cáo trước đó nguyên vẹn). Khi thất bại, dải chuyển sang màu đỏ với bản sao được khóa theo `RerunError.kind` (`timeout` / `network` / `post_failed`). Trạng thái trống (không có bộ nhớ đệm hoặc hết hạn) và trạng thái không có phiên (bộ nhớ đệm tồn tại nhưng quá trình quét không tìm thấy bản ghi) được hiển thị riêng biệt. ### Chính sách -Một trang hai tab để quản lý chính sách và xem lại hoạt động. +Một trang hai tab để quản lý chính sách và xem xét hoạt động. - - Chọn nhiều CLI agent mà failproofai bảo vệ từ một bảng duy nhất — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi và Gemini CLI đề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 điểm nhấn có thương hiệu. Kiểm tra hoặc bỏ kiểm tra các CLI bạn muốn và nhấp `Apply changes` để cài đặt/gỡ cài đặt chênh lệch trong một bước. Các CLI có tệp 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 (ghi vào `~/.failproofai/policies-config.json` — chia sẻ trên mọi CLI được cài đặt) + - Chọn nhiều agent CLI nào mà failproofai bảo vệ từ một bảng điều khiển duy nhất — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, Gemini CLI 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 điểm nhấn có thương hiệu. Chọn hoặc bỏ chọn các CLI bạn muốn và nhấp `Apply changes` để cài đặt/gỡ cài đặt chênh lệch trong một bước. Các CLI có tệp nhị phân được phát hiện trên PATH được tính sẵn. + - Bật hoặc tắt các chính sách riêng lẻ 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 để 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ử được phân trang đầy đủ của mọi sự kiện móc đã được kích hoạt trên tất cả các phiên làm việc - - 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)_ / Gemini CLI _(beta)_), tên chính sách hoặc ID phiên làm việc - - 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 bích = Cursor Agent, hổ phách = OpenCode, hồng = Pi, bầu trời = Gemini CLI), tên công cụ, ID phiên làm việc và lý do cho các quyết định từ chối/hướng dẫn - - Nhấp vào ID phiên làm việc để mở bảng ghi chép của nó — trình xem tự động phát hiện CLI nào kích hoạt móc (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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`) và hiển thị huy hiệu CLI phù hợp trong tiêu đề + - Lịch sử được phân trang đầy đủ của mọi sự kiện hook đã được 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)_ / Gemini CLI _(beta)_ / Hermes), 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, lục bảo = Cursor Agent, hổ phách = OpenCode, hồng = Pi, xanh da trời = Gemini CLI, chàm = Hermes), 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ản ghi của nó — trình xem tự động phát hiện CLI nào được 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`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`, Hermes `~/.hermes/state.db`) và hiển thị huy hiệu CLI phù hợp trong tiêu đề @@ -92,7 +93,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 bộ chuyển đổi 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 làm việc và hoạt động chính sách mới khi chúng xuất hiện. Thiết yếu để giám sát các phiên làm việc agent tự trị chạy lâu dài. +Bảng điều khiển có công tắc làm mới tự động trong điều hướng hàng trên cùng. Khi được bật, trang hiện tại sẽ được 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. Cần thiết để giám sát các phiên agent tự động chạy lâu dài. --- @@ -120,30 +121,30 @@ 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ế độ dev** (`npm run dev`) và truy cập nó từ tên máy chủ không phải `localhost` - chẳng hạn như tên miền tùy chỉnh, IP từ xa hoặc URL được đường hầm — bạn có thể thấy 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 `localhost` - ví dụ, một 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ư: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Đây là Next.js chặn truy cập xuyên nguồn gốc đến websocket HMR (tải lại mô-đun nóng) của nó, đây là tính năng chỉ dev. Để cho phép máy chủ của bạn, hãy sử dụng cờ `--allowed-origins`: +Đây là Next.js chặn quyền truy cập gốc chéo vào websocket HMR (làm mới mô-đun nóng) của nó, đây là một tính năng chỉ dev. Để 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 ``` -Đối với nhiều máy chủ hoặc IP, hãy chuyển danh sách được phân tách bằng dấu phẩy: +Để có nhiều máy chủ hoặc IP, hãy chuyển một danh sách được phân tách bằng dấu phẩy: ```bash 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` thay thế: +Bạn cũng có thể đặt biến môi trường `FAILPROOFAI_ALLOWED_DEV_ORIGINS`: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Đ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ó vấn đề tài nguyên dev xuyên nguồn gốc. +Điều này chỉ áp dụng cho chế độ dev. Khi chạy `failproofai` (chế độ sản xuất), không có websocket HMR và không có vấn đề tài nguyên dev gốc chéo. \ No newline at end of file diff --git a/docs/vi/examples.mdx b/docs/vi/examples.mdx index 612edfb1..27b43c46 100644 --- a/docs/vi/examples.mdx +++ b/docs/vi/examples.mdx @@ -1,16 +1,17 @@ --- -title: Ví dụ +--- +title: Các ví dụ description: "Cách thiết lập hooks cho Claude Code và Agents SDK" icon: book-open --- -Các ví dụ sẵn sàng sử dụng cho các tình huống phổ biến. Mỗi ví dụ cho thấy cách cài đặt và những gì bạn có thể mong đợi. +Các ví dụ sẵn sàng sử dụng cho những kịch bản phổ biến. Mỗi ví dụ cho thấy cách cài đặt và những gì bạn nên mong đợi. --- ## Thiết lập hooks cho Claude Code -Failproof AI tích hợp với Claude Code thông qua [hệ thống hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) của nó. Khi bạn chạy `failproofai policies --install`, nó sẽ đăng ký các lệnh hook trong `settings.json` của Claude Code sẽ chạy trên mỗi lần gọi công cụ. +Failproof AI tích hợp với Claude Code thông qua [hệ thống hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) của nó. Khi bạn chạy `failproofai policies --install`, nó sẽ đăng ký các lệnh hook trong `settings.json` của Claude Code và chúng sẽ được kích hoạt trên mỗi lệnh gọi công cụ. @@ -23,19 +24,19 @@ Failproof AI tích hợp với Claude Code thông qua [hệ thống hooks](https failproofai policies --install ``` - + ```bash cat ~/.claude/settings.json | grep failproofai ``` - Bạn sẽ thấy các mục hook cho các sự kiện `PreToolUse`, `PostToolUse`, `Notification`, và `Stop`. + Bạn sẽ thấy các mục hook cho các sự kiện `PreToolUse`, `PostToolUse`, `Notification` và `Stop`. ```bash claude ``` - Các chính sách giờ đã chạy tự động trên mỗi lần gọi công cụ. Hãy thử yêu cầu Claude chạy `sudo rm -rf /` - nó sẽ bị chặn. + Các chính sách sẽ chạy tự động trên mỗi lệnh gọi công cụ. Hãy thử yêu cầu Claude chạy `sudo rm -rf /` - nó sẽ bị chặn. @@ -43,7 +44,7 @@ Failproof AI tích hợp với Claude Code thông qua [hệ thống hooks](https ## Thiết lập hooks cho Agents SDK -Nếu bạn đang xây dựng với [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), bạn có thể sử dụng cùng hệ thống hook một cách lập trình. +Nếu bạn đang xây dựng với [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), bạn có thể sử dụng cùng một hệ thống hook theo cách lập trình. @@ -52,7 +53,7 @@ Nếu bạn đang xây dựng với [Agents SDK](https://docs.anthropic.com/en/d ``` - Truyền các lệnh hook khi tạo quy trình agent của bạn. Các hooks sẽ chạy giống như trong Claude Code - thông qua stdin/stdout JSON: + Truyền các lệnh hook khi tạo quá trình agent của bạn. Các hooks được kích hoạt giống như trong Claude Code - thông qua JSON stdin/stdout: ```bash failproofai --hook PreToolUse # được gọi trước mỗi công cụ @@ -86,17 +87,17 @@ Nếu bạn đang xây dựng với [Agents SDK](https://docs.anthropic.com/en/d --- -## Chặn các lệnh tàn phá +## Chặn các lệnh phá hoại -Cài đặt phổ biến nhất - ngăn agents thực hiện các thiệt hại không thể khôi phục được. +Thiết lập phổ biến nhất - ngăn agent gây ra các thiệt hại không thể hoàn tác. ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` -Điều này làm gì: +Điều này thực hiện những gì sau: - `block-sudo` - chặn tất cả các lệnh `sudo` -- `block-rm-rf` - chặn xóa file đệ quy +- `block-rm-rf` - chặn xóa tệp đệ quy - `block-force-push` - chặn `git push --force` - `block-curl-pipe-sh` - chặn piping các script từ xa đến shell @@ -104,19 +105,19 @@ failproofai policies --install block-sudo block-rm-rf block-force-push block-cur ## Ngăn chặn rò rỉ bí mật -Dừng agents nhìn thấy hoặc rò rỉ thông tin xác thực trong đầu ra công cụ. +Dừng agent khỏi việc nhìn thấy hoặc rò rỉ thông tin đăng nhập trong đầu ra công cụ. ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -Những cái này chạy trên `PostToolUse` - sau khi một công cụ chạy, chúng sẽ xóa đầu ra trước khi agent nhìn thấy nó. +Những chính sách này được kích hoạt trên `PostToolUse` - sau khi một công cụ chạy, chúng sẽ làm sạch đầu ra trước khi agent nhìn thấy nó. --- -## Nhận cảnh báo Slack khi agents cần chú ý +## Nhận cảnh báo Slack khi agent cần sự chú ý -Sử dụng hook thông báo để chuyển tiếp cảnh báo idle đến Slack. +Sử dụng notification hook để chuyển tiếp các cảnh báo chờ đợi đến Slack. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -158,9 +159,9 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c --- -## Giữ agents trên một nhánh +## Giữ agent trên một nhánh -Ngăn agents chuyển đổi nhánh hoặc đẩy đến các nhánh được bảo vệ. +Ngăn agent chuyển đổi nhánh hoặc push đến các nhánh được bảo vệ. ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -182,9 +183,9 @@ customPolicies.add({ --- -## Yêu cầu kiểm thử trước khi commit +## Yêu cầu kiểm tra trước khi commit -Nhắc nhở agents chạy kiểm thử trước khi commit. +Nhắc nhở agent chạy các bài kiểm tra trước khi commit. ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -206,11 +207,11 @@ customPolicies.add({ --- -## Khóa chặt một repo sản xuất +## Khóa một kho lưu trữ production -Commit một cấu hình mức dự án để mỗi nhà phát triển trong nhóm của bạn nhận được các chính sách giống nhau. +Commit cấu hình cấp dự án để mọi nhà phát triển trong nhóm của bạn đều nhận được các chính sách giống nhau. -Tạo `.failproofai/policies-config.json` trong repo của bạn: +Tạo `.failproofai/policies-config.json` trong kho lưu trữ của bạn: ```json { @@ -238,13 +239,13 @@ git add .failproofai/policies-config.json git commit -m "Add failproofai team policies" ``` -Mỗi thành viên nhóm có failproofai được cài đặt sẽ tự động nhận những quy tắc này. +Mỗi thành viên trong nhóm có cài đặt failproofai sẽ tự động chọn những quy tắc này. --- -## Xây dựng tiêu chuẩn chất lượng toàn tổ chức với chính sách quy ước +## Xây dựng một tiêu chuẩn chất lượng toàn tổ chức với các chính sách quy ước -Cài đặt có tác động lớn nhất: commit `.failproofai/policies/` vào repo của bạn với các chính sách được điều chỉnh cho dự án của bạn. Mỗi thành viên nhóm sẽ nhận được chúng tự động — không có lệnh cài đặt, không có thay đổi cấu hình. +Thiết lập có tác động lớn nhất: commit `.failproofai/policies/` đến kho lưu trữ của bạn với các chính sách được điều chỉnh cho dự án của bạn. Mỗi thành viên trong nhóm sẽ nhận được chúng tự động — không có lệnh cài đặt, không có thay đổi cấu hình. @@ -283,25 +284,25 @@ Cài đặt có tác động lớn nhất: commit `.failproofai/policies/` vào }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - Khi nhóm của bạn gặp các chế độ lỗi mới, hãy thêm chính sách và đẩy lên. Mọi người sẽ nhận được cập nhật vào `git pull` tiếp theo của họ. Những chính sách này trở thành một tiêu chuẩn chất lượng sống động phát triển cùng với nhóm của bạn. + Khi nhóm của bạn gặp phải những chế độ lỗi mới, hãy thêm chính sách và push. Mọi người sẽ nhận được bản cập nhật trên `git pull` tiếp theo của họ. Những chính sách này trở thành một tiêu chuẩn chất lượng sống động phát triển cùng với nhóm của bạn. --- -## Các ví dụ khác +## Thêm nhiều ví dụ -Thư mục [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) trong repo chứa: +Thư mục [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) trong kho lưu trữ chứa: -| Tệp | Điều nó thể hiện | +| Tệp | Những gì nó cho thấy | |------|---------------| -| `policies-basic.js` | Các chính sách khởi đầu - chặn ghi sản xuất, force-push, piped scripts | -| `policies-notification.js` | Cảnh báo Slack cho thông báo idle và kết thúc phiên | -| `policies-advanced/index.js` | Nhập transitional, async hooks, PostToolUse output scrubbing, Stop event handling | \ No newline at end of file +| `policies-basic.js` | Chính sách khởi động - chặn ghi production, force-push, piped scripts | +| `policies-notification.js` | Cảnh báo Slack cho các thông báo chờ đợi và kết thúc phiên | +| `policies-advanced/index.js` | Nhập quá độc lập, async hooks, PostToolUse output scrubbing, Stop event handling | \ No newline at end of file diff --git a/docs/vi/for-agents.mdx b/docs/vi/for-agents.mdx index e4e5967e..a129c88d 100644 --- a/docs/vi/for-agents.mdx +++ b/docs/vi/for-agents.mdx @@ -1,36 +1,36 @@ --- -title: "Cho các agents" -description: "Thêm kiến thức Failproof AI vào agent lập trình của bạn chỉ bằng một lệnh. Hoạt động với Claude Code, Cursor, Windsurf và nhiều hơn nữa." +title: "Cho các agent" +description: "Thêm kiến thức Failproof AI vào coding agent của bạn chỉ bằng một lệnh. Hoạt động với Claude Code, Cursor, Windsurf và nhiều hơn nữa." --- -Thêm toàn bộ tài liệu tham khảo Failproof AI vào agent lập trình của bạn chỉ bằng một lệnh. Hoạt động với Claude Code, Cursor, Windsurf và bất kỳ agent nào khác hỗ trợ skills. +Thêm toàn bộ tài liệu tham khảo Failproof AI vào coding agent của bạn chỉ bằng một lệnh. Hoạt động với Claude Code, Cursor, Windsurf và bất kỳ agent nào hỗ trợ skills. ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` phát hiện những agents bạn đã cài đặt và tự động thêm skill ở định dạng phù hợp cho từng agent. +`npx skills` phát hiện những agent nào bạn đã cài đặt và tự động thêm skill theo định dạng phù hợp cho từng agent. ## Skill bao gồm những gì | Lĩnh vực | Nội dung bao gồm | |------|----------------| -| Policies | Tên policy tích hợp, loại sự kiện, tham số, bật/tắt | -| Custom policies | `customPolicies.add()`, bộ lọc phù hợp, API `allow`/`deny`/`instruct` | +| Policies | Tên policies được xây dựng sẵn, các loại event, tham số, bật/tắt | +| Custom policies | `customPolicies.add()`, bộ lọc khớp, API `allow`/`deny`/`instruct` | | Context object | `ctx.eventType`, `ctx.toolName`, `ctx.toolInput`, `ctx.session` | -| Configuration | Cấu trúc `policies-config.json`, scope merging, `policyParams` | +| Configuration | Cấu trúc `policies-config.json`, hợp nhất scope, `policyParams` | | CLI | `failproofai policies --install`, `--uninstall`, `--custom`, scopes | -| Dashboard | Session viewer, policy activity, biến môi trường | -| Architecture | Hook handler flow, exit codes, stdin/stdout contract | +| Dashboard | Trình xem session, hoạt động policy, biến môi trường | +| Architecture | Luồng xử lý hook, exit codes, hợp đồng stdin/stdout | ## Skill có đầy đủ không? -Mintlify tạo `llms.txt` từ tất cả các trang trong navigation. Tài liệu Failproof AI bao gồm toàn bộ API - mọi policy, tùy chọn và ví dụ đều được đưa vào. Nếu bạn thấy thiếu điều gì, nguồn nằm tại `https://docs.befailproof.ai/llms-full.txt`. +Mintlify tạo `llms.txt` từ tất cả các trang trong điều hướng. Tài liệu Failproof AI bao gồm toàn bộ API - mọi policy, tùy chọn và ví dụ đều được đưa vào. Nếu bạn thấy thiếu gì, nguồn gốc nằm tại `https://docs.befailproof.ai/llms-full.txt`. -Để có ngữ cảnh cụ thể, liên kết trực tiếp đến một trang cụ thể: +Để có bối cảnh cụ thể, liên kết trực tiếp đến một trang cụ thể: ```bash -# Chỉ custom policies API +# Chỉ API custom policies npx skills add https://docs.befailproof.ai/custom-policies # Chỉ built-in policies diff --git a/docs/vi/getting-started.mdx b/docs/vi/getting-started.mdx index 8eadb7b9..f81b0633 100644 --- a/docs/vi/getting-started.mdx +++ b/docs/vi/getting-started.mdx @@ -1,13 +1,13 @@ --- title: Bắt đầu -description: "Cài đặt failproofai, kích hoạt policies, và để agents của bạn chạy một cách đáng tin cậy" +description: "Cài đặt failproofai, bật các chính sách, và để agents của bạn chạy một cách đáng tin cậy" icon: rocket --- ## Yêu cầu - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (tùy chọn - chỉ cần thiết khi build từ source) +- **Bun** >= 1.3.0 (tùy chọn - chỉ cần thiết để build từ nguồn) --- @@ -30,16 +30,16 @@ bun add -g failproofai ## Bắt đầu nhanh - - Policies là những quy tắc chạy trước và sau mỗi lần agent gọi công cụ. Chúng bắt các lệnh có khả năng gây hủy hoại, rò rỉ bí mật, và các tình huống thất bại khác trước khi chúng gây ra thiệt hại. + + Chính sách là những quy tắc chạy trước và sau mỗi lần agent gọi tool. Chúng bắt các lệnh phá hủy, rò rỉ bí mật, và những chế độ lỗi khác trước khi chúng gây thiệt hại. ```bash failproofai policies --install ``` - Điều này ghi hook entries vào các agent CLIs đã cài đặt của bạn (tệp `~/.claude/settings.json` của Claude Code, `~/.codex/hooks.json` của OpenAI Codex, `~/.copilot/hooks/failproofai.json` của GitHub Copilot CLI, `~/.cursor/hooks.json` của Cursor Agent, plugin shim được tạo tại `~/.config/opencode/plugins/failproofai.mjs` của OpenCode cộng với entry đăng ký trong mảng `plugin` của `~/.config/opencode/opencode.json`, `~/.pi/agent/settings.json` của Pi, hoặc `~/.gemini/settings.json` của Gemini CLI). Khi có nhiều hơn một được cài đặt, bạn sẽ được hỏi; truyền `--cli claude codex copilot cursor opencode pi gemini` (bất kỳ subset nào) để bỏ qua lời nhắc. + Lệnh này ghi các hook entries vào CLI agents đã cài đặt của bạn (Claude Code's `~/.claude/settings.json`, OpenAI Codex's `~/.codex/hooks.json`, GitHub Copilot CLI's `~/.copilot/hooks/failproofai.json`, Cursor Agent's `~/.cursor/hooks.json`, OpenCode's generated plugin shim at `~/.config/opencode/plugins/failproofai.mjs` plus a registration entry in `~/.config/opencode/opencode.json`'s `plugin` array, Pi's `~/.pi/agent/settings.json`, Gemini CLI's `~/.gemini/settings.json`, or Hermes's `~/.hermes/config.yaml`). Khi có nhiều hơn một cái có mặt, bạn sẽ được nhắc; truyền `--cli claude codex copilot cursor opencode pi gemini hermes` (bất kỳ tập hợp con nào) để bỏ qua lời nhắc. - Hỗ trợ cho GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, và Gemini CLI là **beta** — cài đặt với `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, hoặc `--cli gemini`. + GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, và Gemini CLI support là **beta** — cài đặt với `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, hoặc `--cli gemini`. Hermes (hermes-agent, một gateway Slack/Telegram) cài đặt user-scope với `--cli hermes` và là **cũng** một nguồn audit offline. ```bash failproofai policies --install --scope project @@ -49,6 +49,7 @@ bun add -g failproofai failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project + failproofai policies --install --cli hermes --scope user failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` @@ -57,62 +58,62 @@ bun add -g failproofai failproofai policies ``` - Hiển thị mỗi policy, cho dù nó được kích hoạt hay không, và bất kỳ tham số nào được cấu hình. + Hiển thị mỗi chính sách, xem nó có được bật hay không, và bất kỳ tham số nào được cấu hình. - + ```bash failproofai ``` - Mở một bảng điều khiển cục bộ tại `http://localhost:8020` nơi bạn có thể duyệt phiên, kiểm tra các lệnh gọi công cụ, và quản lý policies. + Mở dashboard cục bộ tại `http://localhost:8020` nơi bạn có thể duyệt các phiên, kiểm tra các tool calls, và quản lý chính sách. - Khởi chạy Claude Code như bình thường. Nếu agent cố gắng làm điều gì đó rủi ro, failproofai sẽ chặn nó tự động. Để nó chạy không tham dự và xem xét những gì đã xảy ra trên bảng điều khiển. + Khởi động Claude Code như bình thường. Nếu agent thử một điều gì đó rủi ro, failproofai sẽ chặn nó tự động. Để nó chạy không cần giám sát và xem xét những gì đã xảy ra trong dashboard. --- -## Policies hoạt động như thế nào +## Cách các chính sách hoạt động -Mỗi khi một agent chạy một công cụ, Claude Code gọi failproofai như một subprocess: +Mỗi khi một agent chạy một tool, Claude Code gọi failproofai như một subprocess: ```text -Claude Code → failproofai --hook PreToolUse → đọc JSON từ stdin - đánh giá policies - ghi quyết định vào stdout +Claude Code → failproofai --hook PreToolUse → reads stdin JSON + evaluates policies + writes decision to stdout ``` -Mỗi policy trả về một trong ba quyết định: +Mỗi chính sách trả về một trong ba quyết định: - **allow** - agent tiếp tục bình thường - **deny** - hành động bị chặn, agent được thông báo lý do - **instruct** - ngữ cảnh bổ sung được thêm vào prompt của agent -Policies chạy trong quá trình cục bộ của bạn. Không có gì được gửi tới dịch vụ từ xa. +Các chính sách chạy trong quy trình cục bộ của bạn. Không có gì được gửi đến dịch vụ từ xa. --- -## Thiết lập team policies với convention-based policies +## Thiết lập chính sách nhóm với chính sách dựa trên quy ước -Cách nhanh nhất để thiết lập các tiêu chuẩn chất lượng trên toàn team là convention `.failproofai/policies/`. Thả các tệp policy vào thư mục này và chúng sẽ được tải tự động — không có flags, không có thay đổi config, không có lệnh cài đặt. +Cách nhanh nhất để thiết lập tiêu chuẩn chất lượng trên toàn nhóm của bạn là quy ước `.failproofai/policies/`. Thả các tệp chính sách vào thư mục này và chúng sẽ được tải tự động — không có flag, không có thay đổi config, không có lệnh cài đặt. - + ```bash mkdir -p .failproofai/policies ``` - - Sao chép các ví dụ khởi đầu hoặc viết của riêng bạn: + + Sao chép các ví dụ khởi động hoặc viết chính sách của riêng bạn: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ ``` - Hoặc tạo một tệp mới: + Hoặc tạo một cái mới: ```js // .failproofai/policies/team-policies.mjs @@ -124,7 +125,7 @@ Cách nhanh nhất để thiết lập các tiêu chuẩn chất lượng trên fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) { - return instruct("Chạy tests trước khi commit."); + return instruct("Run tests before committing."); } return allow(); }, @@ -134,30 +135,30 @@ Cách nhanh nhất để thiết lập các tiêu chuẩn chất lượng trên ```bash git add .failproofai/policies/ - git commit -m "Thêm team quality policies" + git commit -m "Add team quality policies" ``` - Mỗi thành viên trong team có failproofai được cài đặt sẽ tự động nhận các policies này. Không cần thiết lập cho từng developer. + Mỗi thành viên nhóm có failproofai được cài đặt sẽ nhận các chính sách này tự động. Không cần thiết lập cho từng nhà phát triển. -Commit `.failproofai/policies/` vào repo của bạn để toàn bộ team chia sẻ các tiêu chuẩn giống nhau. Khi team của bạn phát hiện ra các tình huống thất bại mới, thêm policies và push — mọi người sẽ nhận được cập nhật trên lần `git pull` tiếp theo của họ. Theo thời gian, những policies này trở thành một tiêu chuẩn chất lượng sống động luôn được cải thiện. +Commit `.failproofai/policies/` vào repo của bạn để toàn bộ nhóm chia sẻ các tiêu chuẩn giống nhau. Khi nhóm của bạn phát hiện ra các chế độ lỗi mới, hãy thêm chính sách và push — mọi người sẽ nhận được cập nhật trên lần `git pull` tiếp theo của họ. 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, liên tục cải thiện. --- ## Lưu trữ dữ liệu -Tất cả các cấu hình và logs vẫn ở trên máy của bạn: +Tất cả cấu hình và log vẫn ở trên máy tính của bạn: -| Đường dẫn | Nội dung lưu trữ | +| Đường dẫn | Lưu trữ những gì | |------|----------------| -| `~/.failproofai/policies-config.json` | Cấu hình policy toàn cầu | +| `~/.failproofai/policies-config.json` | Cấu hình chính sách toàn cầu | | `~/.failproofai/hook-activity.jsonl` | Lịch sử thực thi hook | -| `~/.failproofai/hook.log` | Debug log cho các lỗi hook tùy chỉnh | -| `.failproofai/policies-config.json` | Cấu hình cho mỗi dự án (committed) | -| `.failproofai/policies-config.local.json` | Overrides cá nhân (gitignored) | +| `~/.failproofai/hook.log` | Log gỡ lỗi cho lỗi hook tùy chỉnh | +| `.failproofai/policies-config.json` | Cấu hình trên mỗi dự án (được commit) | +| `.failproofai/policies-config.local.json` | Ghi đè cá nhân (gitignored) | --- @@ -176,19 +177,19 @@ Xóa hook entries từ `~/.claude/settings.json`. Các tệp config trong `~/.fa - Scopes và định dạng tệp config + Phạm vi và định dạng tệp config - Tất cả 26 policies với tham số + Tất cả 26 chính sách với tham số - Viết policies của riêng bạn trong JavaScript + Viết các chính sách riêng của bạn trong JavaScript - Giám sát phiên và xem xét hoạt động policy + Giám sát các phiên và xem xét hoạt động chính sách \ No newline at end of file diff --git a/docs/vi/introduction.mdx b/docs/vi/introduction.mdx index 1d9986e7..daaf6270 100644 --- a/docs/vi/introduction.mdx +++ b/docs/vi/introduction.mdx @@ -1,15 +1,15 @@ --- title: "Failproof AI" -description: "FailproofAI cung cấp 39 chính sách xử lý lỗi tích hợp sẵn giúp bắt các vòng lặp, rò rỉ bí mật, các lệnh gọi công cụ phá hủy và nhiều hơn nữa trong một lần cài đặt." +description: "FailproofAI cung cấp 39 chính sách xử lý lỗi tích hợp sẵn giúp phát hiện vòng lặp, rò rỉ bí mật, lệnh gọi công cụ tàn phá, và nhiều hơn nữa chỉ với một lần cài đặt." --- [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -Các hook và chính sách cho **xử lý lỗi AI**, **phục hồi lỗi**, và **độ tin cậy LLM**. Giữ cho các agent AI của bạn hoạt động đáng tin cậy và tự động trên **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, và **Agents SDK**. +Hooks và chính sách cho **xử lý lỗi AI**, **phục hồi lỗi**, và **độ tin cậy LLM**. Giữ cho các AI agents của bạn luôn đáng tin cậy và hoạt động tự trị trên **Claude Code**, **OpenAI Codex**, **GitHub Copilot**, **Cursor Agent**, **OpenCode**, **Pi**, **Gemini CLI**, **Hermes**, và **Agents SDK**. -Các agent AI gặp sự cố theo những cách có thể dự đoán được. Chúng chạy các lệnh phá hủy, rò rỉ bí mật, lạc khỏi nhiệm vụ, bị kẹt trong các vòng lặp, hoặc đẩy trực tiếp vào nhánh main. Nếu không được kiểm soát, những sự cố nhỏ có thể dẫn đến ngừng hoạt động, rò rỉ thông tin đăng nhập, và mất dữ liệu. +Các AI agents thất bại theo những cách có thể dự đoán được. Chúng chạy các lệnh tàn phá, rò rỉ bí mật, lạc khỏi nhiệm vụ, mắc kẹt trong các vòng lặp, hoặc push trực tiếp lên main. Nếu không được giám sát, những lỗi nhỏ sẽ dẫn đến sự cố toàn hệ thống, rò rỉ thông tin xác thực, và mất công việc. -FailproofAI giải quyết vấn đề này bằng **chính sách**. Những quy tắc này can thiệp vào mọi lệnh gọi công cụ của agent để **phát hiện lỗi**, **giảm thiểu chúng** (chặn, hướng dẫn, vệ sinh), và **cảnh báo bạn** khi có điều cần chú ý. Một bảng điều khiển cục bộ cho phép bạn xem xét mọi lệnh gọi công cụ, lỗi agent và hành động phục hồi sau đó. +FailproofAI giải quyết vấn đề này bằng **policies** (chính sách). Những quy tắc này kết nối vào mọi lệnh gọi công cụ của agent để **phát hiện lỗi**, **giảm nhẹ chúng** (chặn, hướng dẫn, làm sạch), và **cảnh báo cho bạn** khi có điều gì cần chú ý. Một bảng điều khiển cục bộ cho phép bạn xem lại mọi lệnh gọi công cụ, lỗi agent, và hành động phục hồi sau này. Không có dữ liệu nào rời khỏi máy của bạn. @@ -18,24 +18,24 @@ Không có dữ liệu nào rời khỏi máy của bạn. - Chặn các lệnh phá hủy, ngăn chặn rò rỉ bí mật, giữ các agent trong ranh giới dự án và nhiều hơn nữa. Tất cả đã sẵn sàng. + Chặn các lệnh tàn phá, ngăn chặn rò rỉ bí mật, giữ agents trong ranh giới dự án, và nhiều hơn nữa. Tất cả đã sẵn sàng. - Viết các quy tắc riêng của bạn bằng JavaScript với API allow / deny / instruct đơn giản. + Viết các quy tắc của riêng bạn bằng JavaScript với API allow / deny / instruct đơn giản. - - Xem các agent của bạn đã làm gì khi bạn vắng mặt. Duyệt qua các phiên làm việc, kiểm tra các lệnh gọi công cụ, xem xét các chỗ chính sách được kích hoạt. + + Xem những gì các agents của bạn đã làm trong khi bạn vắng mặt. Duyệt qua các phiên, kiểm tra các lệnh gọi công cụ, xem xét nơi các chính sách được kích hoạt. - Điều chỉnh bất kỳ chính sách nào mà không cần mã. Đặt danh sách cho phép, các nhánh được bảo vệ, hoặc ngưỡng theo dự án hoặc toàn cầu. + Điều chỉnh bất kỳ chính sách nào mà không cần code. Đặt danh sách cho phép, nhánh được bảo vệ, hoặc ngưỡng cho từng dự án hoặc toàn cục. -## Bắt đầu nhanh +## Khởi động nhanh @@ -50,8 +50,8 @@ bun add -g failproofai ```bash -failproofai policies --install # bật các chính sách (hoặc bỏ qua — `failproofai` sẽ đề xuất thiết lập chúng trong lần chạy đầu tiên) -failproofai # khởi chạy bảng điều khiển +failproofai policies --install # bật chính sách (hoặc bỏ qua — `failproofai` sẽ đề xuất thiết lập chúng khi chạy lần đầu tiên) +failproofai # khởi động bảng điều khiển ``` -Xem hướng dẫn [Bắt đầu](/vi/getting-started) để có hướng dẫn đầy đủ. \ No newline at end of file +Xem hướng dẫn [Bắt đầu](/vi/getting-started) để tìm hiểu chi tiết đầy đủ. \ No newline at end of file diff --git a/docs/vi/package-aliases.mdx b/docs/vi/package-aliases.mdx index 8e38a924..9124d79a 100644 --- a/docs/vi/package-aliases.mdx +++ b/docs/vi/package-aliases.mdx @@ -1,12 +1,12 @@ --- -title: Bí danh Gói -description: "Các bí danh ngăn chặn typosquat đã đăng ký và cách chúng hoạt động" +title: Package Aliases +description: "Những alias phòng chống lỗi đánh máy được đăng ký và cách chúng hoạt động" icon: copy --- ## Gói chính thức -Gói npm chính là **`failproofai`**: +Gói npm chính thức là **`failproofai`**: ```bash npm install -g failproofai @@ -16,17 +16,17 @@ bun add -g failproofai --- -## Tại sao chúng tôi sở hữu các tên bí danh +## Tại sao chúng tôi sở hữu các tên alias -Typosquatting là một cuộc tấn công chuỗi cung ứng phổ biến, trong đó một tác nhân độc hại đăng ký tên gói chỉ cách một phím bàn phím so với gói phổ biến. Những người dùng vô tình gõ sai lệnh cài đặt sẽ chạy mã do kẻ tấn công kiểm soát với quyền truy cập toàn hệ thống - đó chính là loại mối đe dọa mà Failproof AI được thiết kế để bảo vệ. +Typosquatting là một cuộc tấn công chuỗi cung ứng phổ biến trong đó một diễn viên độc hại đăng ký tên gói chỉ cách một phím bàn phím so với gói phổ biến. Những người dùng vô tình gõ sai lệnh cài đặt sẽ chạy mã được kiểm soát bởi kẻ tấn công với quyền truy cập đầy đủ hệ thống - chính xác là loại mối đe dọa mà Failproof AI được thiết kế để bảo vệ. -Để loại bỏ rủi ro này, **chúng tôi chủ động sở hữu tất cả các lỗi chính tả phổ biến và các biến thể định dạng** của `failproofai` trên npm. Không tên nào trong số này có thể được đăng ký bởi bên thứ ba. Mỗi tên đều là một proxy đơn giản giúp cài đặt và ủy quyền cho gói `failproofai` thực tế. +Để loại bỏ bề mặt tấn công này, **chúng tôi chủ động sở hữu tất cả các lỗi đánh máy phổ biến và các biến thể định dạng** của `failproofai` trên npm. Không có tên nào trong số này có thể được đăng ký bởi bên thứ ba. Mỗi tên là một proxy mỏng cài đặt và ủy quyền cho gói `failproofai` thực tế. --- -## Bí danh đã đăng ký +## Các alias được đăng ký -**Biến thể định dạng** - các cách khác nhau để viết "failproof ai": +**Các biến thể định dạng** - những cách khác nhau để viết "failproof ai": | Gói | Trạng thái | |---------|--------| @@ -37,7 +37,7 @@ Typosquatting là một cuộc tấn công chuỗi cung ứng phổ biến, tron | `fail_proof_ai` | ⏳ Chờ hỗ trợ npm | | `fail-proofai` | ⏳ Chờ hỗ trợ npm | -**`failprof*` typos** - thiếu một `o` từ "proof": +**Lỗi đánh máy `failprof*`** - thiếu một chữ `o` từ "proof": | Gói | Trạng thái | |---------|--------| @@ -47,7 +47,7 @@ Typosquatting là một cuộc tấn công chuỗi cung ứng phổ biến, tron | `fail-prof-ai` | ⏳ Chờ hỗ trợ npm | | `failprof_ai` | ⏳ Chờ hỗ trợ npm | -**`faliproof*` typos** - hoán đổi `a` và `i`: +**Lỗi đánh máy `faliproof*`** - hoán đổi `a` và `i`: | Gói | Trạng thái | |---------|--------| @@ -55,9 +55,9 @@ Typosquatting là một cuộc tấn công chuỗi cung ứng phổ biến, tron | `faliproof-ai` | ✅ Đã xuất bản | | `faliproofai` | ⏳ Chờ hỗ trợ npm | -> **Tại sao chờ?** Chính sách ngăn chặn thư rác của npm chặn các tên được chuẩn hóa thành chuỗi giống như gói hiện có sau khi loại bỏ dấu chấm câu và chạy kiểm tra tương tự. Chúng tôi đã liên hệ với hỗ trợ npm để đặt trước những tên này nhằm mục đích chống typosquatting. Chúng sẽ được kích hoạt sau khi được phê duyệt. +> **Tại sao đang chờ?** Chính sách phòng chống spam của npm chặn các tên được chuẩn hóa thành chuỗi giống nhau như gói hiện có sau khi loại bỏ dấu câu và chạy kiểm tra tương tự. Chúng tôi đã liên hệ với hỗ trợ npm để dự trữ các tên này cho mục đích phòng chống typosquatting. Chúng sẽ được kích hoạt sau khi được phê duyệt. -Bạn có thể xác minh bất kỳ bí danh đã xuất bản nào do chúng tôi sở hữu: +Bạn có thể xác minh bất kỳ alias được xuất bản nào đều được chúng tôi sở hữu: ```bash npm info failproof @@ -66,17 +66,17 @@ npm info failproof --- -## Cách các bí danh hoạt động +## Cách các alias hoạt động -Mỗi gói bí danh: +Mỗi gói alias: -1. Liệt kê `failproofai` làm phụ thuộc - vì vậy gói thực tế (bao gồm thiết lập móc `postinstall` của nó) được chạy khi cài đặt -2. Hiển thị một lệnh binary phù hợp với tên riêng của nó (ví dụ `failproof-ai`) ủy quyền tất cả các đối số cho lệnh binary `failproofai` +1. Liệt kê `failproofai` làm một phụ thuộc - vì vậy gói thực tế (bao gồm thiết lập hook `postinstall` của nó) chạy khi cài đặt +2. Phơi bày nhị phân khớp với tên của chính nó (ví dụ: `failprof-ai`) phục vụ như proxy cho tất cả các đối số đến nhị phân `failproofai` -Proxy là một tập lệnh Node hai dòng; không có logic, không có lệnh gọi mạng và không có thu thập dữ liệu ngoài những gì `failproofai` tự thực hiện. +Proxy là một kịch bản Node hai dòng; không có logic, không có lệnh gọi mạng và không có thu thập dữ liệu ngoài những gì `failproofai` tự làm. --- -## Nếu bạn tìm thấy một tên chúng tôi bỏ sót +## Nếu bạn tìm thấy một tên mà chúng tôi bỏ lỡ Mở một issue tại [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) và chúng tôi sẽ đăng ký nó. \ No newline at end of file diff --git a/docs/vi/testing.mdx b/docs/vi/testing.mdx index 802eb1f5..451d0bf8 100644 --- a/docs/vi/testing.mdx +++ b/docs/vi/testing.mdx @@ -1,14 +1,14 @@ --- -title: Kiểm thử +title: Thử nghiệm description: "Unit tests, E2E tests, và test helpers" icon: flask-vial --- -failproofai có hai bộ kiểm thử: **unit tests** (nhanh, mocked) và **end-to-end tests** (subprocess thực). +failproofai có hai bộ test: **unit tests** (nhanh, mocked) và **end-to-end tests** (gọi subprocess thực tế). --- -## Chạy kiểm thử +## Chạy tests ```bash # Chạy tất cả unit tests một lần @@ -17,10 +17,10 @@ bun run test:run # Chạy unit tests ở chế độ watch bun run test -# Chạy E2E tests (cần setup - xem bên dưới) +# Chạy E2E tests (yêu cầu thiết lập - xem bên dưới) bun run test:e2e -# Kiểm tra kiểu mà không cần build +# Type-check mà không build bunx tsc --noEmit # Lint @@ -36,7 +36,7 @@ Unit tests nằm trong `__tests__/` và sử dụng [Vitest](https://vitest.dev) ```text __tests__/ hooks/ - builtin-policies.test.ts # Logic policy cho mỗi builtin + builtin-policies.test.ts # Logic policy cho từng builtin hooks-config.test.ts # Config loading và scope merging policy-evaluator.test.ts # Param injection và evaluation order custom-hooks-registry.test.ts # globalThis registry add/get/clear @@ -110,17 +110,17 @@ describe("block-sudo", () => { ## End-to-end tests -E2E tests gọi nhị phân `failproofai` thực làm subprocess, pipe payload JSON tới stdin, và assert stdout output cũng như exit code. Điều này kiểm thử đường dẫn tích hợp hoàn chỉnh mà Claude Code sử dụng. +E2E tests gọi binary `failproofai` thực tế dưới dạng subprocess, pipe payload JSON vào stdin, và kiểm tra stdout output cùng exit code. Điều này test đường dẫn tích hợp hoàn chỉnh mà Claude Code sử dụng. -### Setup +### Thiết lập -E2E tests chạy nhị phân trực tiếp từ nguồn repo. Trước lần chạy đầu tiên, build bundle CJS mà các file custom hook sử dụng khi import từ `'failproofai'`: +E2E tests chạy binary trực tiếp từ repo source. Trước lần chạy đầu tiên, build CJS bundle mà các tệp custom hook sử dụng khi import từ `'failproofai'`: ```bash bun build src/index.ts --outdir dist --target node --format cjs ``` -Sau đó chạy các kiểm thử: +Sau đó chạy tests: ```bash bun run test:e2e @@ -133,14 +133,14 @@ Rebuild `dist/` bất cứ khi nào bạn thay đổi public hook API (`src/hook ```text __tests__/e2e/ helpers/ - hook-runner.ts # Spawn the binary, pipe payload JSON, capture exit code + stdout + stderr - fixture-env.ts # Per-test isolated temp directories with config files - payloads.ts # Claude-accurate payload factories for each event type + hook-runner.ts # Spawn binary, pipe payload JSON, capture exit code + stdout + stderr + fixture-env.ts # Per-test isolated temp directories với config files + payloads.ts # Claude-accurate payload factories cho mỗi event type hooks/ - builtin-policies.e2e.test.ts # Each builtin policy with real subprocess - custom-hooks.e2e.test.ts # Custom hook loading and evaluation - config-scopes.e2e.test.ts # Config merging across project/local/global - policy-params.e2e.test.ts # Parameter injection for each parameterized policy + builtin-policies.e2e.test.ts # Mỗi builtin policy với real subprocess + custom-hooks.e2e.test.ts # Custom hook loading và evaluation + config-scopes.e2e.test.ts # Config merging qua project/local/global + policy-params.e2e.test.ts # Parameter injection cho mỗi parameterized policy ``` ### Sử dụng E2E helpers @@ -151,7 +151,7 @@ __tests__/e2e/ import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - temp dir; pass as payload.cwd to pick up .failproofai/policies-config.json +// env.cwd - temp dir; pass as payload.cwd để pick up .failproofai/policies-config.json // env.home - isolated home dir; no real ~/.failproofai leaks in env.writeConfig({ @@ -162,9 +162,9 @@ env.writeConfig({ }); ``` -`createFixtureEnv()` đăng ký cleanup `afterEach` tự động. +`createFixtureEnv()` tự động đăng ký `afterEach` cleanup. -**`runHook`** - gọi nhị phân: +**`runHook`** - gọi binary: ```typescript import { runHook } from "../helpers/hook-runner"; @@ -249,12 +249,12 @@ E2E tests sử dụng `vitest.config.e2e.mts` với: - `pool: "forks"` - true process isolation (tests spawn subprocesses) - `testTimeout: 20_000` - 20s per test (binary startup + hook eval) -Pool `forks` rất quan trọng: thread-based workers chia sẻ `globalThis`, điều này có thể gây ảnh hưởng tới các tests spawning subprocess. Process-based forks tránh điều này. +`forks` pool rất quan trọng: thread-based workers chia sẻ `globalThis`, điều này có thể can thiệp vào subprocess-spawning tests. Process-based forks tránh điều này. --- ## CI -Full CI run (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) được yêu cầu pass trước khi merge. E2E suite chạy như một separate CI job song song. +Full CI run (`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`) phải pass trước khi merge. E2E suite chạy như một separate CI job song song. -Xem [Contributing](../CONTRIBUTING.md) để biết complete pre-merge checklist. \ No newline at end of file +Xem [Contributing](../CONTRIBUTING.md) để có danh sách pre-merge hoàn chỉnh. \ No newline at end of file diff --git a/docs/zh/architecture.mdx b/docs/zh/architecture.mdx index d510203c..aa5e17bb 100644 --- a/docs/zh/architecture.mdx +++ b/docs/zh/architecture.mdx @@ -4,7 +4,7 @@ description: "钩子处理器、配置加载和策略评估的内部工作原理 icon: sitemap --- -本文档介绍 failproofai 的内部工作原理：钩子系统如何拦截 Agent 工具调用、配置如何加载与合并、策略如何评估，以及控制台如何监控 Agent 活动。 +本文档介绍 failproofai 的内部工作原理：钩子系统如何拦截 Agent 工具调用、配置如何加载与合并、策略如何评估，以及仪表板如何监控 Agent 活动。 --- @@ -12,10 +12,10 @@ icon: sitemap failproofai 包含两个独立子系统： -1. **钩子处理器** - 一个高速 CLI 子进程，Claude Code 在每次 Agent 工具调用时都会调用它。负责评估策略并返回决策。 -2. **Agent 监控器（控制台）** - 一个用于监控 Agent 会话和管理策略的 Next.js Web 应用。 +1. **钩子处理器** - 一个快速的 CLI 子进程，Claude Code 在每次 Agent 工具调用时都会调用它。负责评估策略并返回决策结果。 +2. **Agent 监控器（仪表板）** - 一个用于监控 Agent 会话和管理策略的 Next.js Web 应用。 -两个子系统共享 `~/.failproofai/` 和项目 `.failproofai/` 目录中的配置文件，但它们以独立进程运行，仅通过文件系统进行通信。 +两个子系统共享 `~/.failproofai/` 和项目 `.failproofai/` 目录中的配置文件，但各自作为独立进程运行，仅通过文件系统进行通信。 --- @@ -23,7 +23,7 @@ failproofai 包含两个独立子系统： ### 与 Claude Code 的集成 -运行 `failproofai policies --install` 后，它会将如下条目写入 `~/.claude/settings.json`： +当你运行 `failproofai policies --install` 时，它会将如下条目写入 `~/.claude/settings.json`： ```json { @@ -60,9 +60,9 @@ Claude Code 随后会在每次工具调用前将 `failproofai --hook PreToolUse` } ``` -对于 `PostToolUse` 事件，载荷还会包含 `tool_result` 字段，其中包含工具的输出内容。 +对于 `PostToolUse` 事件，载荷还会包含 `tool_result` 字段，其中记录了工具的输出。 -处理器对 stdin 强制执行 1 MB 的限制。超出此限制的载荷将被丢弃，所有策略隐式允许通过。 +处理器对 stdin 强制限制为 1 MB。超出此限制的载荷将被丢弃，所有策略默认隐式放行。 ### 响应格式 @@ -85,7 +85,7 @@ Claude Code 随后会在每次工具调用前将 `failproofai --hook PreToolUse` } ``` -**指令（除 Stop 外的任何事件）：** +**指令（除 Stop 以外的任意事件）：** ```json { "hookSpecificOutput": { @@ -98,13 +98,13 @@ Claude Code 随后会在每次工具调用前将 `failproofai --hook PreToolUse` - 退出码：`2` - 原因写入 stderr（而非 stdout） -**允许：** +**放行：** - 退出码：`0` - stdout 为空 -**带消息的允许：** +**附带消息的放行：** -`allow(message)` 允许策略在操作被允许时向 Claude 回传信息性上下文。钩子处理器将以下 JSON 写入 **stdout**（这不是配置文件——这是处理器向 Claude Code 的响应，与 deny 和 instruct 响应方式相同）： +`allow(message)` 允许策略在操作被放行的同时，向 Claude 发送信息性上下文。钩子处理器会将以下 JSON 写入 **stdout**（这不是配置文件——这是处理器对 Claude Code 的响应，与拒绝和指令响应的方式相同）： ```json // 由钩子处理器进程写入 stdout @@ -114,9 +114,9 @@ Claude Code 随后会在每次工具调用前将 `failproofai --hook PreToolUse` } } ``` -- 退出码：`0`（操作被允许） -- 当多个策略返回带消息的 `allow` 时，消息将以换行符拼接为单个 `additionalContext` 字符串 -- 若没有策略提供消息，stdout 为空（与之前相同） +- 退出码：`0`（操作被放行） +- 若多个策略均返回附带消息的 `allow`，其消息将以换行符连接，合并为单个 `additionalContext` 字符串 +- 若没有策略提供消息，则 stdout 为空（与之前的行为一致） ### 处理流水线 @@ -127,25 +127,25 @@ stdin JSON → 解析载荷（最大 1 MB） → 提取会话元数据（session_id、cwd、tool_name、tool_input 等） → readMergedHooksConfig(cwd) ← 合并项目 + 本地 + 全局配置 - → 注册已启用的内置策略并解析参数 + → 注册已启用的内置策略（含已解析的参数） → 从 customPoliciesPath 加载自定义策略（如已设置） → 将自定义策略注册到策略注册表 - → 评估所有策略（先评估内置策略，再评估自定义策略） - → 首个 deny 立即短路退出 - → instruct 决策持续累积 - → allow 消息持续累积 + → 评估所有策略（先执行内置策略，再执行自定义策略） + → 首个 deny 立即短路 + → instruct 决策累积 + → allow 消息累积 → 将 JSON 决策写入 stdout → 将事件持久化到 ~/.failproofai/hook-activity.jsonl → 退出 ``` -对于典型载荷，整个过程在 100ms 内完成，无需调用任何 LLM。 +对于典型载荷，整个处理过程无需调用 LLM，在 100ms 以内完成。 --- ## 配置加载 -`src/hooks/hooks-config.ts` 实现了三层配置加载。 +`src/hooks/hooks-config.ts` 实现了三级作用域的配置加载。 ```text [1] {cwd}/.failproofai/policies-config.json ← 项目级（最高优先级） @@ -154,33 +154,33 @@ stdin JSON ``` 合并逻辑： -- `enabledPolicies` - 对三个文件的并集去重 -- `policyParams` - 按策略键名，第一个定义该键的文件完全优先 -- `customPoliciesPath` - 第一个定义该值的文件优先 -- `llm` - 第一个定义该值的文件优先 +- `enabledPolicies` - 对三个文件取去重并集 +- `policyParams` - 按策略名称为键，首个定义该键的文件整体优先 +- `customPoliciesPath` - 首个定义该字段的文件优先 +- `llm` - 首个定义该字段的文件优先 -Web 控制台使用 `readHooksConfig()`（仅全局配置）进行读写，因为它不以项目 cwd 调用。 +Web 仪表板使用 `readHooksConfig()`（仅读取全局配置）进行读写，因为它不以项目的 cwd 调用。 --- ## 策略评估 -`src/hooks/policy-evaluator.ts` 按顺序依次运行策略。 +`src/hooks/policy-evaluator.ts` 按顺序运行各策略。 对于每条策略： -1. 查找策略的 `params` 模式（如有）。 -2. 从合并配置中读取 `policyParams[policy.name]`。 -3. 将用户提供的值覆盖到模式默认值之上，生成 `ctx.params`。 -4. 以解析后的上下文调用 `policy.fn(ctx)`。 +1. 查找该策略的 `params` 模式（如有）。 +2. 从合并后的配置中读取 `policyParams[policy.name]`。 +3. 将用户提供的值覆盖模式默认值，生成 `ctx.params`。 +4. 使用解析后的上下文调用 `policy.fn(ctx)`。 5. 若结果为 `deny`，立即停止并返回该决策。 -6. 若结果为 `instruct`，累积消息并继续。 -7. 若结果为 `allow`，继续到下一条策略。 +6. 若结果为 `instruct`，累积消息并继续执行。 +7. 若结果为 `allow`，继续执行下一条策略。 所有策略运行完毕后： -- 若有任何 `deny` 返回，输出 deny 响应。 -- 若收集到任何 `instruct` 返回，输出单个 instruct 响应，所有消息拼接在一起。 -- 否则，输出 allow 响应（stdout 为空，退出码 0）。 +- 若存在任意 `deny` 结果，则输出拒绝响应。 +- 若收集到任意 `instruct` 结果，则输出单条指令响应，所有消息以换行符连接。 +- 否则，输出放行响应（stdout 为空，退出码为 0）。 --- @@ -204,15 +204,15 @@ interface BuiltinPolicyDefinition { } ``` -接受 `params` 的策略会声明一个 `PolicyParamsSchema`，其中包含每个参数的类型和默认值。策略评估器在调用 `fn` 之前将解析后的值注入 `ctx.params`。策略函数读取 `ctx.params` 时无需空值保护，因为默认值始终优先应用。 +接受 `params` 的策略会声明一个 `PolicyParamsSchema`，其中包含各参数的类型和默认值。策略评估器在调用 `fn` 之前，会将解析后的值注入 `ctx.params`。策略函数读取 `ctx.params` 时无需进行空值判断，因为默认值始终会被预先填充。 -策略内部的模式匹配使用解析后的命令 token（argv），而非原始字符串匹配。这可以防止通过 Shell 操作符注入绕过（例如，针对 `sudo systemctl status *` 的模式不会因在命令后追加 `; rm -rf /` 而被绕过）。 +策略内部的模式匹配使用解析后的命令令牌（argv），而非原始字符串匹配。这可防止通过 Shell 操作符注入绕过规则（例如，针对 `sudo systemctl status *` 的模式，无法通过在命令末尾追加 `; rm -rf /` 来绕过）。 --- ## 自定义策略 -`src/hooks/custom-hooks-registry.ts` 实现了一个基于 `globalThis` 的注册表： +`src/hooks/custom-hooks-registry.ts` 实现了基于 `globalThis` 的注册表： ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -225,25 +225,25 @@ export function getCustomHooks(): CustomHook[] { ... } export function clearCustomHooks(): void { ... } // 用于测试 ``` -`src/hooks/custom-hooks-loader.ts` 加载用户的策略文件： +`src/hooks/custom-hooks-loader.ts` 负责加载用户的策略文件： 1. 从配置中读取 `customPoliciesPath`；若不存在则跳过。 2. 解析为绝对路径；检查文件是否存在。 -3. 将所有 `from "failproofai"` 的导入重写为实际的 dist 路径，使 `customPolicies` 解析到同一个 `globalThis` 注册表。 -4. 递归重写传递性本地导入以确保 ESM 兼容性。 -5. 写入临时 `.mjs` 文件并 `import()` 入口文件。 +3. 将所有 `from "failproofai"` 的导入重写为实际的 dist 路径，使 `customPolicies` 能解析到同一个 `globalThis` 注册表。 +4. 递归重写传递性本地导入，以确保 ESM 兼容性。 +5. 写入临时 `.mjs` 文件，并通过 `import()` 加载入口文件。 6. 调用 `getCustomHooks()` 获取已注册的钩子。 7. 在 `finally` 块中清理所有临时文件。 -发生任何错误（文件未找到、语法错误、导入失败）时，错误将记录到 `~/.failproofai/hook.log`，加载器返回空数组。内置策略不受影响。 +发生任何错误时（文件未找到、语法错误、导入失败），错误会被记录到 `~/.failproofai/hook.log`，加载器返回空数组。内置策略不受影响。 -自定义策略在所有内置策略之后评估。自定义策略的 `deny` 仍会短路后续自定义策略（但所有内置策略此时已完成评估）。 +自定义策略在所有内置策略执行完毕后才会被评估。自定义策略的 `deny` 仍会短路后续自定义策略（但此时所有内置策略已经执行完毕）。 --- ## 活动日志 -每次钩子事件后，处理器会向 `~/.failproofai/hook-activity.jsonl` 追加一行 JSONL： +每次钩子事件发生后，处理器会向 `~/.failproofai/hook-activity.jsonl` 追加一行 JSONL 记录： ```json { @@ -258,44 +258,44 @@ export function clearCustomHooks(): void { ... } // 用于测试 } ``` -每条记录对应一条做出非 allow 决策的策略。Allow 决策不记录日志（以保持文件精简）。 +每条记录对应一个做出非放行决策的策略。放行决策不会被记录（以保持文件精简）。 --- -## 控制台架构 +## 仪表板架构 -控制台是一个 **Next.js 16** 应用，使用 App Router，结合 React Server Components 和 Server Actions。 +仪表板是一个 **Next.js 16** 应用，使用 App Router，搭配 React Server Components 和 Server Actions。 ```text app/ layout.tsx ← 根布局（主题、遥测、导航） - projects/page.tsx ← Server 组件：列出所有 Claude 项目 - project/[name]/page.tsx ← Server 组件：列出项目中的会话 + projects/page.tsx ← 服务端组件：列出所有 Claude 项目 + project/[name]/page.tsx ← 服务端组件：列出项目中的会话 project/[name]/session/ - [sessionId]/page.tsx ← Server 组件：渲染会话查看器 - policies/page.tsx ← Client 组件：策略管理 + 活动日志 + [sessionId]/page.tsx ← 服务端组件：渲染会话查看器 + policies/page.tsx ← 客户端组件：策略管理 + 活动日志 actions/ - get-hooks-config.ts ← 读取配置 + 策略列表 - update-hooks-config.ts ← 切换策略开关 + get-hooks-config.ts ← 读取配置和策略列表 + update-hooks-config.ts ← 启用/禁用策略 update-policy-params.ts ← 更新策略参数 get-hook-activity.ts ← 分页/搜索活动日志 - install-hooks-web.ts ← 从浏览器安装/移除钩子 + install-hooks-web.ts ← 通过浏览器安装/移除钩子 api/ download/[project]/[session]/route.ts ← 按 CLI 会话导出（JSONL 或 JSON） ``` **数据流：** -- 页面组件调用 `lib/projects.ts` 和 `lib/log-entries.ts` 直接从文件系统读取项目/会话数据（读取操作无 API 层）。 -- 策略页面使用 Server Actions 处理所有变更操作（切换、参数更新、安装/移除）。 +- 页面组件调用 `lib/projects.ts` 和 `lib/log-entries.ts`，直接从文件系统读取项目/会话数据（读取操作无 API 层）。 +- 策略页面的所有变更操作（切换、参数更新、安装/移除）均使用 Server Actions。 - 会话查看器解析 Claude 的 JSONL 转录格式，并渲染消息和工具调用的时间线。 **关键设计决策：** -- 无数据库——所有持久化状态存储在纯文本文件中（`~/.failproofai/`、`~/.claude/projects/`）。 -- 变更操作使用 Server Actions——无需为 CRUD 操作构建 REST API。 -- 读取页面使用 React Server Components——更快的首屏加载，无需客户端数据获取 bundle。 -- 仅在需要交互性时使用 Client 组件（策略切换、活动搜索、日志查看器）。 +- 无数据库——所有持久化状态均存储于普通文件（`~/.failproofai/`、`~/.claude/projects/`）中。 +- 使用 Server Actions 进行变更操作——CRUD 操作无需 REST API。 +- 读取页面使用 React Server Components——首次加载更快，无需为数据获取打包客户端代码。 +- 仅在需要交互性的地方使用客户端组件（策略切换、活动搜索、日志查看器）。 --- @@ -304,29 +304,29 @@ app/ ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # CLI 路由（hook / dashboard / install 等） +│ └── failproofai.mjs # CLI 路由器（hook / dashboard / install 等） ├── src/hooks/ │ ├── handler.ts # 钩子事件流水线 │ ├── builtin-policies.ts # 39 条策略定义 │ ├── policy-evaluator.ts # 策略执行引擎 │ ├── policy-registry.ts # 策略注册与查找 │ ├── policy-types.ts # TypeScript 接口定义 -│ ├── hooks-config.ts # 多层配置加载 +│ ├── hooks-config.ts # 多级作用域配置加载 │ ├── custom-hooks-registry.ts # 基于 globalThis 的钩子注册表 -│ ├── custom-hooks-loader.ts # 用户 JS 钩子的 ESM 加载器 -│ ├── manager.ts # 安装/移除/列出操作 +│ ├── custom-hooks-loader.ts # 用于用户 JS 钩子的 ESM 加载器 +│ ├── manager.ts # 安装 / 移除 / 列出操作 │ ├── install-prompt.ts # 交互式策略选择提示 -│ ├── hook-logger.ts # 记录日志到 hook.log +│ ├── hook-logger.ts # 写入 hook.log 的日志记录 │ ├── hook-activity-store.ts # 将活动持久化到 hook-activity.jsonl │ └── llm-client.ts # LLM API 客户端（用于 AI 驱动的策略） -├── app/ # Next.js 控制台（页面 + Server Actions） -├── lib/ # 共享工具函数 +├── app/ # Next.js 仪表板（页面 + Server Actions） +├── lib/ # 共享工具库 │ ├── projects.ts # 从文件系统枚举 Claude 项目 │ ├── log-entries.ts # 解析 Claude 转录 JSONL 格式 │ ├── paths.ts # 解析系统路径 │ └── ... ├── components/ # 共享 React UI 组件 -├── contexts/ # React context 提供者（主题、自动刷新、遥测） +├── contexts/ # React Context Provider（主题、自动刷新、遥测） ├── examples/ # 自定义钩子示例文件 └── __tests__/ # 单元测试与端到端测试 ``` \ No newline at end of file diff --git a/docs/zh/built-in-policies.mdx b/docs/zh/built-in-policies.mdx index 0419fa10..8e2bd6da 100644 --- a/docs/zh/built-in-policies.mdx +++ b/docs/zh/built-in-policies.mdx @@ -1,10 +1,10 @@ --- title: 内置策略 -description: "所有 39 条内置策略，用于捕获常见的代理失败模式" +description: "39 个内置策略，用于捕获常见的 Agent 故障模式" icon: shield --- -failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。每条策略会在特定的钩子事件类型和工具名称上触发。十九条策略支持参数配置，让你无需编写代码即可调整其行为。五条工作流策略会在 Claude 停止之前强制执行提交 → 推送 → PR → CI 的流水线。 +failproofai 内置了 39 个策略，用于捕获常见的 Agent 故障模式。每个策略针对特定的 Hook 事件类型和工具名称触发。其中 19 个策略支持参数配置，让您无需编写代码即可调整其行为。5 个工作流策略会在 Claude 停止前强制执行提交 → 推送 → PR → CI 的流水线。 --- @@ -12,11 +12,11 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 策略按类别分组： -| 类别 | 策略 | 钩子类型 | +| 类别 | 策略 | Hook 类型 | |----------|----------|-----------| | [危险命令](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | | [基础设施命令](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [密钥（清理器）](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [密钥（清洗器）](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | | [环境](#environment) | block-env-files, protect-env-vars | PreToolUse | | [文件访问](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse | @@ -25,15 +25,15 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 | [包管理器](#package-managers) | prefer-package-manager | PreToolUse | | [工作流](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop | -- **`block-`** — 阻止代理继续执行。 -- **`warn-`** — 向代理提供额外上下文，使其能够自我纠正。 -- **`sanitize-`** — 在代理看到工具输出之前清除其中的敏感数据。 +- **`block-`** — 阻止 Agent 继续执行。 +- **`warn-`** — 为 Agent 提供额外上下文，使其能够自我纠正。 +- **`sanitize-`** — 在 Agent 看到工具输出之前清除其中的敏感数据。 ### 命名空间 -每条策略都位于 `/` 插槽中。内置策略属于 **`failproofai/`** 命名空间——例如 `failproofai/sanitize-jwt`。当你同时加载具有相似短名称的自定义或第三方策略时，命名空间可防止命名冲突。 +每个策略都位于 `/` 槽中。内置策略属于 **`failproofai/`** 命名空间，例如 `failproofai/sanitize-jwt`。命名空间可防止您同时加载具有相似短名称的自定义或第三方策略时发生冲突。 -在配置中，你可以通过短名称或完整限定名称来引用内置策略；两种形式解析到同一条策略： +在配置文件中，您可以使用短名称或完整限定名称来引用内置策略，两种形式解析到同一个策略： ```json { @@ -44,33 +44,33 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 } ``` -如果名称中不含 `/`，failproofai 会将其视为属于默认命名空间 `failproofai`。已包含 `/` 的名称（如 `myorg/foo`、`custom/my-hook`）将保持原样。 +如果名称中不含 `/`，failproofai 会将其视为属于默认命名空间 `failproofai`。已包含 `/` 的名称（如 `myorg/foo`、`custom/my-hook`）则保持原样。 - **`require-`** — 阻止 Stop 事件，直到满足条件为止。 --- -每条策略在 `policyParams` 中都支持可选的 `hint` 字段。该提示会附加到 Claude 看到的 deny 或 instruct 消息中，在不修改策略代码的情况下提供可操作的指导。适用于内置策略、自定义策略和约定策略。详见[配置 → hint](/zh/configuration#hint-cross-cutting)。 +每个策略在 `policyParams` 中都支持可选的 `hint` 字段。该提示会附加到 Claude 收到的 deny 或 instruct 消息中，提供可操作的指导，无需修改策略代码。适用于内置策略、自定义策略和约定策略。详见[配置 → hint](/zh/configuration#hint-cross-cutting)。 --- ## 危险命令 -防止代理运行难以撤销或可能损害宿主系统的操作。 +防止 Agent 运行难以撤销或可能损害宿主系统的操作。 ### `block-sudo` **事件：** PreToolUse (Bash) **默认行为：** 拒绝任何包含 `sudo` 的命令。 -阻止包含 `sudo` 关键字的调用。模式匹配基于解析后的命令令牌，而非原始字符串，以防止通过 Shell 运算符注入绕过。 +阻止包含 `sudo` 关键字的调用。模式匹配基于已解析的命令 token，而非原始字符串，以防止通过 Shell 运算符注入绕过。 **参数：** | 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 允许的精确命令前缀。每个条目与解析后的 argv 令牌进行匹配。 | +| `allowPatterns` | `string[]` | `[]` | 允许的命令前缀。每个条目与已解析的 argv token 进行匹配。 | **示例：** @@ -84,10 +84,10 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 } ``` -使用此配置，`sudo systemctl status nginx` 会被允许，但 `sudo rm /etc/hosts` 会被拒绝。 +使用此配置，`sudo systemctl status nginx` 将被允许，但 `sudo rm /etc/hosts` 将被拒绝。 -模式匹配基于解析后的令牌，而非原始命令字符串。这可防止通过附加 Shell 运算符进行绕过（例如，`sudo systemctl status x; rm -rf /` 不会匹配 `sudo systemctl status *`）。 +模式匹配基于已解析的 token，而非原始命令字符串。这可防止通过附加 Shell 运算符绕过（例如 `sudo systemctl status x; rm -rf /` 不会匹配 `sudo systemctl status *`）。 --- @@ -101,7 +101,7 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 | 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | 允许递归删除的安全路径（例如 `/tmp`）。 | +| `allowPaths` | `string[]` | `[]` | 允许递归删除的路径（如 `/tmp`）。 | **示例：** @@ -129,7 +129,7 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `block-failproofai-commands` **事件：** PreToolUse (Bash) -**默认行为：** 拒绝会卸载或禁用 failproofai 本身的命令（例如 `npm uninstall failproofai`、`failproofai policies --uninstall`）。 +**默认行为：** 拒绝会卸载或禁用 failproofai 自身的命令（如 `npm uninstall failproofai`、`failproofai policies --uninstall`）。 无参数。 @@ -137,9 +137,9 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ## 基础设施命令 -防止编码代理运行基础设施 CLI 或触发 CI/CD 流水线。此类别中的所有策略均为**按需启用**（`defaultEnabled: false`）——合法需要调用 `kubectl`、`terraform` 等工具的代理不会受到干扰，除非你主动启用该策略。启用后，匹配 CLI 的每次调用都会被拒绝，除非命令与 `allowPatterns` 中的某个条目匹配。 +防止编码 Agent 运行基础设施 CLI 或触发 CI/CD 流水线。此类别中的所有策略均为**按需启用**（`defaultEnabled: false`）——合法需要调用 `kubectl`、`terraform` 等工具的 Agent 不会受到干扰，除非您主动启用相应策略。启用后，除非命令匹配 `allowPatterns` 中的条目，否则所有匹配 CLI 的调用均会被拒绝。 -模式语法与 [`block-sudo`](#block-sudo) 相同：令牌与解析后的 argv 进行匹配，`*` 是单个令牌的通配符，任何包含独立 Shell 运算符（`&&`、`||`、`|`、`;`）或嵌入 Shell 元字符令牌的命令，在白名单匹配之前都会被拒绝，以防止注入绕过。 +模式语法与 [`block-sudo`](#block-sudo) 相同：token 与已解析的 argv 进行匹配，`*` 为单个 token 的通配符，任何包含独立 Shell 运算符（`&&`、`||`、`|`、`;`）或内嵌 Shell 元字符的 token 都会在允许列表匹配之前被拒绝，以防注入绕过。 ### `block-kubectl` @@ -164,7 +164,7 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 } ``` -使用此配置，`kubectl get pods` 会被允许，但 `kubectl apply -f deploy.yaml` 会被拒绝。 +使用此配置，`kubectl get pods` 将被允许，但 `kubectl apply -f deploy.yaml` 将被拒绝。 --- @@ -296,7 +296,7 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `block-gh-pipeline` **事件：** PreToolUse (Bash) -**默认行为：** 拒绝以下会修改状态或触发流水线的 `gh` CLI 子命令： +**默认行为：** 拒绝以下会改变状态或触发流水线的 `gh` CLI 子命令： - `gh workflow run`、`gh workflow enable`、`gh workflow disable` - `gh run rerun`、`gh run cancel` @@ -305,13 +305,13 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 - `gh cache delete` - `gh secret set`、`gh secret delete` -只读的 `gh` 子命令（如 `gh pr view`、`gh pr list`、`gh run list`、`gh release view` 和 `gh api repos/.../...`）**不**在此策略的匹配范围内——这些命令通常用于工作流检查（包括 failproofai 自身的 `require-ci-green-before-stop`）。 +只读的 `gh` 子命令（如 `gh pr view`、`gh pr list`、`gh run list`、`gh release view` 和 `gh api repos/.../...`）**不**在此策略的拦截范围内——这些命令在工作流检查中经常用到（包括 failproofai 自身的 `require-ci-green-before-stop`）。 **参数：** | 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | 即使会被拒绝，也允许的特定脚本调用。 | +| `allowPatterns` | `string[]` | `[]` | 允许的特定脚本调用，即使它们本应被拒绝。 | **示例：** @@ -327,14 +327,14 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 --- -## 密钥（清理器） +## 密钥（清洗器） -防止代理将凭据泄露到其上下文或输出中。清理器策略在 **PostToolUse** 事件上触发。当 Claude 运行 Bash 命令、读取文件或调用任何工具时，这些策略会在输出返回给 Claude 之前对其进行检查。如果检测到密钥模式，策略会返回拒绝决策，阻止输出被传回。 +防止 Agent 将凭据泄露到其上下文或输出中。清洗器策略在 **PostToolUse** 事件上触发。当 Claude 运行 Bash 命令、读取文件或调用任何工具时，这些策略会在输出返回给 Claude 之前对其进行检查。若检测到密钥模式，策略将返回拒绝决定，阻止输出被传回。 ### `sanitize-jwt` **事件：** PostToolUse（所有工具） -**默认行为：** 脱敏 JWT 令牌（由 `.` 分隔的三段 base64url 内容）。 +**默认行为：** 清除 JWT token（由 `.` 分隔的三段 base64url 字符串）。 无参数。 @@ -343,13 +343,13 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `sanitize-api-keys` **事件：** PostToolUse（所有工具） -**默认行为：** 脱敏常见的 API 密钥格式：Anthropic（`sk-ant-`）、OpenAI（`sk-`）、GitHub PAT（`ghp_`）、AWS 访问密钥（`AKIA`）、Stripe 密钥（`sk_live_`、`sk_test_`）以及 Google API 密钥（`AIza`）。 +**默认行为：** 清除常见的 API 密钥格式：Anthropic（`sk-ant-`）、OpenAI（`sk-`）、GitHub PAT（`ghp_`）、AWS 访问密钥（`AKIA`）、Stripe 密钥（`sk_live_`、`sk_test_`）以及 Google API 密钥（`AIza`）。 **参数：** | 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | 额外需要视为密钥的正则表达式模式。 | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | 额外的正则表达式模式，用于识别自定义密钥。 | **示例：** @@ -371,7 +371,7 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `sanitize-connection-strings` **事件：** PostToolUse（所有工具） -**默认行为：** 脱敏包含嵌入凭据的数据库连接字符串（例如 `postgresql://user:password@host/db`）。 +**默认行为：** 清除包含内嵌凭据的数据库连接字符串（如 `postgresql://user:password@host/db`）。 无参数。 @@ -380,7 +380,7 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `sanitize-private-key-content` **事件：** PostToolUse（所有工具） -**默认行为：** 脱敏 PEM 块（`-----BEGIN PRIVATE KEY-----`、`-----BEGIN RSA PRIVATE KEY-----` 等）。 +**默认行为：** 清除 PEM 块（`-----BEGIN PRIVATE KEY-----`、`-----BEGIN RSA PRIVATE KEY-----` 等）。 无参数。 @@ -389,7 +389,7 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `sanitize-bearer-tokens` **事件：** PostToolUse（所有工具） -**默认行为：** 脱敏 `Authorization: Bearer ` 请求头中令牌长度达到 20 个字符或以上的内容。 +**默认行为：** 清除 `Authorization: Bearer ` 请求头中 token 长度为 20 个或更多字符的内容。 无参数。 @@ -397,14 +397,14 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ## 环境 -防止代理读取或暴露敏感的环境配置。 +保护敏感的环境配置，防止 Agent 读取或暴露它们。 ### `block-env-files` -**事件：** PreToolUse (Bash, Read) +**事件：** PreToolUse（Bash、Read） **默认行为：** 拒绝通过 `cat .env`、以 `.env` 为文件路径的 `Read` 工具调用等方式读取 `.env` 文件。 -不会阻止 `.envrc` 或其他与环境相关的文件——仅阻止名称恰好为 `.env` 的文件。 +不会阻止读取 `.envrc` 或其他与环境相关的文件——仅阻止名称恰好为 `.env` 的文件。 无参数。 @@ -412,7 +412,7 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `protect-env-vars` -**事件：** PreToolUse (Bash) +**事件：** PreToolUse（Bash） **默认行为：** 拒绝打印环境变量的命令：`printenv`、`env`、`echo $VAR`。 无参数。 @@ -421,18 +421,18 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ## 文件访问 -将代理限制在项目边界内，并使其远离敏感文件。 +将 Agent 的工作范围限制在项目目录内，并使其远离敏感文件。 ### `block-read-outside-cwd` -**事件：** PreToolUse (Read, Bash) -**默认行为：** 拒绝读取项目根目录之外的文件。边界由 `CLAUDE_PROJECT_DIR`（由 Claude Code 在每次会话开始时设置）确定，当该变量未设置时，回退到会话的当前工作目录。使用项目根目录而非实时的 `cwd`，意味着即使 Claude `cd` 进入子目录后，边界仍然保持稳定。 +**事件：** PreToolUse（Read、Bash） +**默认行为：** 拒绝读取项目根目录以外的文件。边界为 `CLAUDE_PROJECT_DIR`（由 Claude Code 在每个会话开始时设置一次），当该变量未设置时回退到会话的当前工作目录。使用项目根目录而非实时的 `cwd`，意味着即使 Claude `cd` 进入子目录后，边界依然保持稳定。 **参数：** | 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | 即使位于项目根目录之外，也允许访问的绝对路径前缀。 | +| `allowPaths` | `string[]` | `[]` | 即使在项目根目录之外也允许访问的绝对路径前缀。 | **示例：** @@ -450,14 +450,14 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `block-secrets-write` -**事件：** PreToolUse (Write, Edit) -**默认行为：** 拒绝写入常用于私钥和证书的文件：`id_rsa`、`id_ed25519`、`*.key`、`*.pem`、`*.p12`、`*.pfx`。 +**事件：** PreToolUse（Write、Edit） +**默认行为：** 拒绝写入通常用于私钥和证书的文件：`id_rsa`、`id_ed25519`、`*.key`、`*.pem`、`*.p12`、`*.pfx`。 **参数：** | 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | 额外需要阻止的文件名模式（glob 风格）。 | +| `additionalPatterns` | `string[]` | `[]` | 额外的文件名模式（glob 风格）以阻止写入。 | **示例：** @@ -475,18 +475,18 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ## Git -防止意外推送、强制推送以及难以撤销的分支操作失误。 +防止意外推送、强制推送以及难以撤销的分支错误操作。 ### `block-push-master` -**事件：** PreToolUse (Bash) +**事件：** PreToolUse（Bash） **默认行为：** 拒绝 `git push origin main` 和 `git push origin master`。 **参数：** | 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | 不能直接推送的分支名称。 | +| `protectedBranches` | `string[]` | `["main", "master"]` | 不允许直接推送的分支名称。 | **示例：** @@ -501,15 +501,15 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ``` -若要允许推送到所有分支（即在不从 `enabledPolicies` 中移除此策略的情况下将其实际禁用），请设置 `protectedBranches: []`。 +如需允许推送到所有分支（即在不将此策略从 `enabledPolicies` 中移除的情况下将其实际禁用），可设置 `protectedBranches: []`。 --- ### `block-work-on-main` -**事件：** PreToolUse (Bash) -**默认行为：** 当工作树处于 `main` 或 `master` 分支时，拒绝 `git commit`、`git merge`、`git rebase` 和 `git cherry-pick`。分支创建和切换（`git checkout`、`git checkout -b`、`git switch`、`git switch -c`）不受影响。 +**事件：** PreToolUse（Bash） +**默认行为：** 当工作树位于 `main` 或 `master` 分支时，拒绝 `git commit`、`git merge`、`git rebase` 和 `git cherry-pick`。分支创建和切换（`git checkout`、`git checkout -b`、`git switch`、`git switch -c`）不受影响。 **参数：** @@ -521,10 +521,10 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `block-force-push` -**事件：** PreToolUse (Bash) +**事件：** PreToolUse（Bash） **默认行为：** 拒绝 `git push --force` 和 `git push -f`。 -无特定策略参数。使用通用 [`hint`](/zh/configuration#hint-cross-cutting) 建议替代方案： +无策略专属参数。可使用通用的 [`hint`](/zh/configuration#hint-cross-cutting) 来建议替代方案： ```json { @@ -540,8 +540,8 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `warn-git-amend` -**事件：** PreToolUse (Bash) -**默认行为：** 在运行 `git commit --amend` 时指示 Claude 谨慎操作。不会阻止该命令。 +**事件：** PreToolUse（Bash） +**默认行为：** 当运行 `git commit --amend` 时，指示 Claude 谨慎操作。不会阻止该命令。 无参数。 @@ -549,8 +549,8 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `warn-git-stash-drop` -**事件：** PreToolUse (Bash) -**默认行为：** 在运行 `git stash drop` 前指示 Claude 进行确认。不会阻止该命令。 +**事件：** PreToolUse（Bash） +**默认行为：** 在运行 `git stash drop` 之前，指示 Claude 进行确认。不会阻止该命令。 无参数。 @@ -558,8 +558,8 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `warn-all-files-staged` -**事件：** PreToolUse (Bash) -**默认行为：** 在运行 `git add -A` 或 `git add .` 时指示 Claude 检查所暂存的内容。不会阻止该命令。 +**事件：** PreToolUse（Bash） +**默认行为：** 当运行 `git add -A` 或 `git add .` 时，指示 Claude 审查所暂存的内容。不会阻止该命令。 无参数。 @@ -567,12 +567,12 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ## 数据库 -在破坏性 SQL 操作对数据库执行前将其拦截。 +在破坏性 SQL 操作执行之前将其拦截。 ### `warn-destructive-sql` -**事件：** PreToolUse (Bash) -**默认行为：** 在运行包含 `DROP TABLE`、`DROP DATABASE` 或不带 `WHERE` 子句的 `DELETE` 的 SQL 前，指示 Claude 进行确认。 +**事件：** PreToolUse（Bash） +**默认行为：** 在运行包含 `DROP TABLE`、`DROP DATABASE` 或不带 `WHERE` 子句的 `DELETE` 的 SQL 之前，指示 Claude 进行确认。 无参数。 @@ -580,8 +580,8 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `warn-schema-alteration` -**事件：** PreToolUse (Bash) -**默认行为：** 在运行 `ALTER TABLE` 语句前，指示 Claude 进行确认。 +**事件：** PreToolUse（Bash） +**默认行为：** 在运行 `ALTER TABLE` 语句之前，指示 Claude 进行确认。 无参数。 @@ -589,18 +589,18 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ## 警告 -在执行可能存在风险但非破坏性的操作前，为代理提供额外上下文。 +在潜在有风险但非破坏性的操作前，为 Agent 提供额外上下文。 ### `warn-large-file-write` -**事件：** PreToolUse (Write) -**默认行为：** 在写入大于 1024 KB 的文件前，指示 Claude 进行确认。 +**事件：** PreToolUse（Write） +**默认行为：** 在写入大于 1024 KB 的文件之前，指示 Claude 进行确认。 **参数：** | 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | 触发警告的文件大小阈值（以千字节为单位）。 | +| `thresholdKb` | `number` | `1024` | 触发警告的文件大小阈值（单位：KB）。 | **示例：** @@ -615,15 +615,15 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ``` -钩子处理程序对 stdin 载荷强制执行 1 MB 的限制。若要使用较小内容测试此策略，请将 `thresholdKb` 设置为远低于 1024 的值。 +Hook 处理程序对 stdin 的载荷大小有 1 MB 的限制。若要使用较小的内容测试此策略，请将 `thresholdKb` 设置为远低于 1024 的值。 --- ### `warn-package-publish` -**事件：** PreToolUse (Bash) -**默认行为：** 在运行 `npm publish` 前，指示 Claude 进行确认。 +**事件：** PreToolUse（Bash） +**默认行为：** 在运行 `npm publish` 之前，指示 Claude 进行确认。 无参数。 @@ -631,8 +631,8 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `warn-background-process` -**事件：** PreToolUse (Bash) -**默认行为：** 在通过 `nohup`、`&`、`disown` 或 `screen` 启动后台进程时，指示 Claude 保持谨慎。 +**事件：** PreToolUse（Bash） +**默认行为：** 当通过 `nohup`、`&`、`disown` 或 `screen` 启动后台进程时，指示 Claude 谨慎操作。 无参数。 @@ -640,8 +640,8 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `warn-global-package-install` -**事件：** PreToolUse (Bash) -**默认行为：** 在运行 `npm install -g`、`yarn global add` 或在没有虚拟环境的情况下运行 `pip install` 前，指示 Claude 进行确认。 +**事件：** PreToolUse（Bash） +**默认行为：** 在运行 `npm install -g`、`yarn global add` 或在没有虚拟环境的情况下运行 `pip install` 之前，指示 Claude 进行确认。 无参数。 @@ -649,21 +649,21 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ## 包管理器 -强制代理只能使用被允许的包管理器。 +强制规定 Agent 允许使用的包管理器。 ### `prefer-package-manager` -**事件：** PreToolUse (Bash) -**默认行为：** 禁用。启用后，阻止任何不在 `allowed` 列表中的包管理器命令，并告知 Claude 使用允许的管理器重写该命令。 +**事件：** PreToolUse（Bash） +**默认行为：** 禁用。启用后，阻止任何不在 `allowed` 列表中的包管理器命令，并告知 Claude 使用允许的包管理器重写该命令。 可检测：pip、pip3、python -m pip、npm、npx、yarn、pnpm、pnpx、bun、bunx、uv、poetry、pipenv、conda、cargo。 | 参数 | 类型 | 默认值 | 描述 | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | 允许的包管理器名称。任何未在此列表中的已检测管理器都会被阻止。为空时，该策略不执行任何操作。 | -| `blocked` | string[] | `[]` | 除内置列表之外额外需要阻止的管理器名称（例如 `['pdm', 'pipx']`）。 | +| `allowed` | string[] | `[]` | 允许的包管理器名称。任何检测到的且不在此列表中的包管理器都将被阻止。为空时，策略不执行任何操作。 | +| `blocked` | string[] | `[]` | 除内置列表外额外需要阻止的包管理器名称（如 `['pdm', 'pipx']`）。 | -内置阻止列表包括：pip、pip3、npm、npx、yarn、pnpm、pnpx、bun、bunx、uv、poetry、pipenv、conda、cargo。使用 `blocked` 追加不在此列表中的管理器。 +内置阻止列表包含：pip、pip3、npm、npx、yarn、pnpm、pnpx、bun、bunx、uv、poetry、pipenv、conda、cargo。使用 `blocked` 可追加不在此列表中的包管理器。 **示例配置：** @@ -679,18 +679,18 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 } ``` -使用此配置，`pip install flask` 和 `pdm install flask` 都会被拒绝，并提示 Claude 改用 `uv` 或 `bun`。而 `uv pip install flask` 则会被允许，因为 `uv` 在白名单中且会被优先检查。 +使用此配置，`pip install flask` 和 `pdm install flask` 都会被拒绝，并提示 Claude 改用 `uv` 或 `bun`。而 `uv pip install flask` 则会被允许，因为 `uv` 在允许列表中且优先被检测。 --- ## AI 行为 -检测代理陷入循环或行为异常的情况。 +检测 Agent 卡住或行为异常的情况。 ### `warn-repeated-tool-calls` **事件：** PreToolUse（所有工具） -**默认行为：** 当同一工具以相同参数被调用 3 次或以上时，指示 Claude 重新考虑——这通常是代理陷入循环的标志。 +**默认行为：** 当同一工具以相同参数被调用 3 次及以上时，指示 Claude 重新考虑——这是 Agent 陷入循环的常见信号。 无参数。 @@ -698,40 +698,40 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ## 工作流 -强制执行规范的会话结束工作流。这些策略在 **Stop** 事件上触发，并阻止代理停止，直到每个条件都满足为止。它们遵循自然的依赖链：提交 → 推送 → PR → CI。如果某条策略拒绝，链中后续的策略将被跳过（拒绝会短路）。 +强制执行规范的会话结束工作流。这些策略在 **Stop** 事件上触发，阻止 Agent 停止，直到每个条件都得到满足。它们遵循自然的依赖链：提交 → 推送 → PR → CI。如果某个策略拒绝，链中后续策略将被跳过（拒绝会短路）。 -所有工作流策略均为**开放失败**模式：如果所需工具不可用（例如未安装 `gh`，或没有 git 远程仓库），策略会允许通过，并附上说明跳过检查原因的信息提示。 +所有工作流策略均为**失败开放**模式：如果所需工具不可用（如未安装 `gh`、无 git 远端），策略将允许通过并提供信息性消息，说明检查被跳过的原因。 ### 各 CLI 的 Stop 语义 -由于七种支持的 CLI 各自暴露不同的"代理完成"钩子契约，Stop 强制执行的方式略有不同。**结果**是相同的——代理无法在工作流关卡未通过的情况下停止——但**机制**有所不同。下表作出了说明；在启用 `require-*-before-stop` 策略之前，只有 Pi 存在一个值得了解的用户可见差异。 +由于七种受支持的 CLI 各自暴露不同的"Agent 完成"Hook 合约，Stop 强制执行在各 CLI 上的表现略有不同。**结果**是相同的——Agent 在工作流门控未通过时无法停止——但**机制**有所差异。下表作出了总结；只有 Pi 存在一个值得您在启用 `require-*-before-stop` 策略前了解的用户可见差异。 -| CLI | 关卡触发时机 | 你看到的现象 | +| CLI | 门控触发时机 | 您看到的效果 | |---|---|---| -| Claude Code | 同一代理循环，立即触发 | Claude 继续工作——修复问题后再次尝试完成。对你不可见。 | -| Codex | 同一代理循环，立即触发 | 与 Claude 相同。 | -| GitHub Copilot CLI | 同一代理循环，立即触发 | 与 Claude 相同（使用 Copilot 的 `{decision:"block", reason}` 重试通道——经 Copilot CLI 1.0.41 实测验证）。 | -| Cursor Agent | 同一代理循环，立即触发 | 与 Claude 相同（使用 Cursor 的 `{followup_message}` 通道——上限为 `loop_limit`，默认 5 次重试）。 | -| Gemini CLI | 同一代理循环，立即触发 | 与 Claude 相同（在 `AfterAgent` 上使用 Gemini 的 `{decision:"block", reason}` 通道）。 | -| OpenCode | 同一代理循环，立即触发 | 与 Claude 相同（使用 OpenCode 的 `client.session.prompt(...)` SDK 调用，通过 `hookSpecificOutput.additionalContext` 路由）。 | -| **Pi (pi-coding-agent)** | **下一个用户轮次** | **Pi 会明显停止**——当关卡触发时，其代理循环退出并返回到提示符。该关卡将在你下次提交提示时触发：failproofai 会在该轮次的系统提示前添加一条 `MANDATORY ACTION REQUIRED` 指令，要求 LLM 在执行你的请求之前完成工作流步骤（提交、推送等）。 | +| Claude Code | 同一 Agent 循环，立即触发 | Claude 继续工作——修复问题后再次尝试结束。对您无可见中断。 | +| Codex | 同一 Agent 循环，立即触发 | 与 Claude 相同。 | +| GitHub Copilot CLI | 同一 Agent 循环，立即触发 | 与 Claude 相同（使用 Copilot 的 `{decision:"block", reason}` 重试通道——已针对 Copilot CLI 1.0.41 实证验证）。 | +| Cursor Agent | 同一 Agent 循环，立即触发 | 与 Claude 相同（使用 Cursor 的 `{followup_message}` 通道——上限为 `loop_limit`，默认 5 次重试）。 | +| Gemini CLI | 同一 Agent 循环，立即触发 | 与 Claude 相同（使用 Gemini 的 `{decision:"block", reason}` 通道，位于 `AfterAgent`）。 | +| OpenCode | 同一 Agent 循环，立即触发 | 与 Claude 相同（使用 OpenCode 的 `client.session.prompt(...)` SDK 调用，通过 `hookSpecificOutput.additionalContext` 路由）。 | +| **Pi (pi-coding-agent)** | **下一个用户轮次** | **Pi 会明显停止**——当门控触发时，其 Agent 循环退出，控制权回到提示符。下次您提交提示时门控才会触发：failproofai 会在该轮次的系统提示开头附加一条 `MANDATORY ACTION REQUIRED` 指令，要求 LLM 在执行您请求的操作之前先完成工作流步骤（提交、推送等）。 | -**Pi 的限制。** Pi 的 `AgentEndEvent`（相当于 Claude 的 `Stop` 钩子的上游等价物）没有 Result 类型——当其触发时，Pi 的代理循环已经退出。Pi 无法像 Claude / Copilot / Cursor / Gemini / OpenCode 那样被强制重试同一循环。failproofai 将关卡转移到 Pi 的 `before_agent_start` 事件（在下一个用户提示后触发），从而确保工作流检查仍然有效，只是在下一轮而非当前轮次执行。 +**Pi 的限制。** Pi 的 `AgentEndEvent`（上游等效于 Claude 的 `Stop` Hook）没有 Result 类型——当它触发时，Pi 的 Agent 循环已经退出。Pi 无法像 Claude / Copilot / Cursor / Gemini / OpenCode 那样被强制重试同一循环。failproofai 将门控转移到 Pi 的 `before_agent_start` 事件（在下一个用户提示后触发），这样工作流检查依然会被执行，只是在下一轮而非当前轮次。 **实际影响：** -- Pi 停止后，拒绝原因会以 Pi session id 为键存储在内存中。在同一 Pi 进程中，你提交的下一个提示会消耗它：LLM 会在系统提示顶部看到 `MANDATORY ACTION REQUIRED` 指令，先提交（或推送/创建 PR/等待 CI），然后再继续处理你的请求。该拒绝原因是一次性的——消耗后关卡即清除。 -- 关卡的生命周期与 Pi 进程绑定。如果你在两次轮次之间 `Ctrl+C` 终止 Pi 或退出，内存中的条目会随进程一同销毁，关卡会被跳过。Claude、Copilot、Cursor、Gemini 和 OpenCode 也有同样的限制（终止代理则跳过关卡）——Pi 只是让这一点更加明显，因为代理在关卡触发前就已经可见地退出了。 -- 待处理的拒绝也会在任何原因的 `session_shutdown` 时清除（`new` / `resume` / `fork` / `quit`），因此先前会话的陈旧关卡不会泄漏到同一 Pi 进程中启动的新会话。 +- Pi 停止后，拒绝原因会以 Pi 会话 ID 为键存储在内存中。您在同一 Pi 进程中提交的下一个提示会消费它：LLM 在系统提示顶部看到 `MANDATORY ACTION REQUIRED` 指令，先完成提交（或推送/开 PR/等待 CI），然后才继续您的请求。该拒绝原因是一次性的——消费后门控即清除。 +- 门控的生命周期受 Pi 进程生命周期限制。如果您在两次轮次之间 `Ctrl+C` 或退出 Pi，内存中的条目会随进程一起丢失，门控也就错过了。Claude、Copilot、Cursor、Gemini 和 OpenCode 有相同的限制（杀掉 Agent 则门控错过）——只是 Pi 更为明显，因为 Agent 在门控触发之前就已可见地退出了。 +- 待处理的拒绝在任何原因导致的 `session_shutdown` 时也会被清除（`new` / `resume` / `fork` / `quit`），因此来自之前会话的过期门控不会泄漏到在同一 Pi 进程中启动的新会话中。 -如果你需要 Claude 风格的同循环重试，请在其他六种支持的 CLI 下运行你的 `Stop` 策略。我们正在跟踪 Pi 上游，等待 `AgentEndEvent` 未来支持 Result 类型，届时我们将能弥合这一差距。 +如果您需要类似 Claude 的同循环重试，请在其他六种受支持的 CLI 下运行您的 `Stop` 策略。我们正在跟踪 Pi 上游，等待 `AgentEndEvent` 上未来的 Result 类型以弥补这一差距。 ### `require-commit-before-stop` **事件：** Stop -**默认行为：** 当存在未提交的更改（已修改、已暂存或未跟踪的文件）时，拒绝停止。工作目录干净时返回提示信息。 +**默认行为：** 当存在未提交的更改（已修改、已暂存或未跟踪的文件）时，拒绝停止。工作目录干净时返回信息性消息。 无参数。 @@ -740,13 +740,13 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `require-push-before-stop` **事件：** Stop -**默认行为：** 当存在未推送的提交，或当前分支没有远程跟踪分支时，拒绝停止。必要时建议使用 `git push -u` 创建跟踪分支。如果未配置远程仓库，则开放失败。 +**默认行为：** 当存在未推送的提交或当前分支没有远端跟踪分支时，拒绝停止。如需创建跟踪分支，建议使用 `git push -u`。若未配置远端，则失败开放。 **参数：** | 参数 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | 推送目标的远程名称。 | +| `remote` | `string` | `"origin"` | 要推送到的远端名称。 | **示例：** @@ -765,13 +765,13 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `require-pr-before-stop` **事件：** Stop -**默认行为：** 当当前分支不存在拉取请求，或现有 PR 已关闭且未合并时，拒绝停止。指示 Claude 使用 `gh pr create` 创建 PR。当 PR 已**合并**时，策略允许通过（工作已发布），并提示切换回分支（`git checkout main && git pull`）。 +**默认行为：** 当当前分支不存在 Pull Request，或现有 PR 已关闭且未合并时，拒绝停止。指示 Claude 使用 `gh pr create` 创建 PR。当 PR 被**合并**后，策略允许通过（工作已交付），并提示切换离开该分支（`git checkout main && git pull`）。 无参数。 -此策略需要安装并通过身份验证的 [GitHub CLI](https://cli.github.com/)（`gh`）。 -运行 `gh auth login`，使用具有 `repo` 权限（用于读取拉取请求）的个人访问令牌。如果未安装 `gh` 或未通过身份验证，策略会开放失败，并将原因报告给 Claude。 +此策略需要安装并完成身份验证的 [GitHub CLI](https://cli.github.com/)（`gh`）。 +运行 `gh auth login`，使用具有 `repo` 作用域的个人访问令牌以获得对 Pull Request 的读取权限。如果未安装 `gh` 或未完成身份验证，策略将失败开放并向 Claude 报告原因。 --- @@ -779,12 +779,12 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `require-no-conflicts-before-stop` **事件：** Stop -**默认行为：** 当当前分支无法干净地合并到基础分支时，拒绝停止。该策略首先确认 GitHub 上是否存在该分支的 `OPEN` PR——如果没有，则没有可强制执行的合并目标，整个策略短路为允许。确认存在 `OPEN` PR 后，会运行两个独立探测： +**默认行为：** 当当前分支无法与基础分支干净合并时，拒绝停止。策略首先确认 GitHub 上该分支存在 `OPEN` 状态的 PR——没有 PR 则无合并目标可强制执行，整个策略短路为允许。确认存在 `OPEN` PR 后，将运行两个独立探测： -1. **本地** — `git merge-tree --write-tree --name-only origin/ HEAD`。发生冲突时，拒绝消息会列出冲突文件，让 Claude 明确知道需要解决哪些问题。 -2. **GitHub** — 复用预检时已获取的 `gh pr view --json mergeable,state` 结果。可捕获本地陈旧的 `origin/` 会遗漏的冲突（例如，自上次 fetch 以来，有人将一个冲突的 PR 合并到了 `main`）。`CONFLICTING` 结果会触发拒绝。`UNKNOWN` 结果也会触发拒绝，并指示 Claude 等待约 10 秒后重新检查再尝试停止——这可防止 GitHub 重新计算期间出现假阴性。 +1. **本地检测** — `git merge-tree --write-tree --name-only origin/ HEAD`。发生冲突时，拒绝消息会列出冲突文件，使 Claude 知道确切需要解决的内容。 +2. **GitHub 检测** — 复用在预检中已获取的 `gh pr view --json mergeable,state` 结果。可捕获本地过期的 `origin/` 可能遗漏的冲突（例如自上次 fetch 以来，有人在 `main` 上合并了冲突 PR）。`CONFLICTING` 结果导致拒绝。`UNKNOWN` 结果也会拒绝，并指示 Claude 等待约 10 秒后重新检查，再尝试停止——这可防止 GitHub 重新计算期间出现误放。 -在以下情况下完全跳过（允许通过）：未安装 `gh`、该分支不存在 PR、PR 状态不为 `OPEN`（如 `MERGED`、`CLOSED`），或 `gh pr view` 返回无法解析的输出。当本地缺少 `origin/` 或没有超前于基础的提交时也会开放失败——这些第一层回退仍会在允许前参考缓存的 PR 可合并性。 +以下情况策略将完全跳过（允许通过）：未安装 `gh`、该分支无 PR、PR 状态非 `OPEN`（如 `MERGED`、`CLOSED`），或 `gh pr view` 返回无法解析的输出。当本地缺少 `origin/` 或 HEAD 相对于基础没有新提交时也失败开放——这些第一层回退在允许之前仍会查询缓存的 PR 可合并性。 **参数：** @@ -793,7 +793,7 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 | `baseBranch` | `string` | `"main"` | 用于检查冲突的基础分支。 | -此策略需要 GitHub CLI（`gh`）。策略会使用 `gh pr view` 确认存在 `OPEN` PR，然后再运行任何冲突探测——没有 `gh` 则策略短路为允许。运行 `gh auth login`，使用具有 `repo` 权限（用于读取拉取请求）的个人访问令牌。 +此策略需要 GitHub CLI（`gh`）。策略使用 `gh pr view` 在运行任何冲突探测之前确认存在 `OPEN` PR——没有 `gh` 则策略短路为允许。运行 `gh auth login`，使用具有 `repo` 作用域的个人访问令牌以获得对 Pull Request 的读取权限。 --- @@ -801,22 +801,22 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 ### `require-ci-green-before-stop` **事件：** Stop -**默认行为：** 当当前分支的 CI 检查失败或仍在运行时，拒绝停止。同时检查 GitHub Actions 工作流运行和第三方机器人检查（如 CodeRabbit、SonarCloud、Codecov）。将 `skipped`、`cancelled` 和 `neutral` 结论视为非失败（后者涵盖了例如外部贡献者 PR 上的 Socket Security 告警，此时应用程序有意报告 neutral 而非 success/failure）。所有检查通过时返回提示信息。 +**默认行为：** 当 CI 检查在当前分支上失败或仍在运行时，拒绝停止。同时检查 GitHub Actions 工作流运行和第三方 Bot 检查（如 CodeRabbit、SonarCloud、Codecov）。将 `skipped`、`cancelled` 和 `neutral` 结论视为非失败（后者涵盖例如 Socket Security 对外部贡献者 PR 的警报，其中应用程序有意报告 neutral 而非 success/failure）。所有检查通过时返回信息性消息。 无参数。 -此策略需要安装并通过身份验证的 [GitHub CLI](https://cli.github.com/)（`gh`）。 -运行 `gh auth login`，使用具有 `repo` 权限（用于读取 Actions 工作流运行和 Checks API）的个人访问令牌。如果未安装 `gh` 或未通过身份验证，策略会开放失败，并将原因报告给 Claude。 +此策略需要安装并完成身份验证的 [GitHub CLI](https://cli.github.com/)（`gh`）。 +运行 `gh auth login`，使用具有 `repo` 作用域的个人访问令牌以获得对 Actions 工作流运行和 Checks API 的读取权限。如果未安装 `gh` 或未完成身份验证，策略将失败开放并向 Claude 报告原因。 --- --- -## 禁用单条策略 +## 禁用单个策略 -从配置的 `enabledPolicies` 中移除特定策略，或在控制台的策略选项卡中将其关闭。 +在配置文件的 `enabledPolicies` 中移除特定策略，或在控制台的策略标签页中将其关闭。 ```json { @@ -827,4 +827,4 @@ failproofai 内置了 39 条策略，用于捕获常见的代理失败模式。 } ``` -未列在 `enabledPolicies` 中的策略不会运行，即使存在对应的 `policyParams` 条目也是如此。 \ No newline at end of file +未列在 `enabledPolicies` 中的策略不会运行，即使 `policyParams` 中存在对应条目。 \ No newline at end of file diff --git a/docs/zh/cli/audit.mdx b/docs/zh/cli/audit.mdx index 9af54169..d6d90c87 100644 --- a/docs/zh/cli/audit.mdx +++ b/docs/zh/cli/audit.mdx @@ -1,19 +1,19 @@ --- title: 审计历史会话（测试版） -description: "统计代理在历史记录中执行浪费性或高风险操作的频率" +description: "统计智能体在历史记录中执行浪费性或高风险操作的频率" --- - **测试版功能。** 审计功能作为测试版发布，目的是收集早期反馈。 - 探测器目录和报告格式可能在下一个稳定版本发布前有所变化。 + **测试版功能。** 审计功能目前以测试版形式发布，我们正在收集早期反馈。 + 检测器目录和报告格式可能在下一个稳定版本发布前有所变动。 如发现任何异常，请提交 issue。 -审计功能将过去的代理 CLI 记录重新通过 failproofai 的策略引擎进行回放，并在 **`/audit` 仪表板页面**上生成一份可共享的可视化报告——包括代理的原型分类、0 至 100 的评分，以及哪些策略能够捕获哪些问题的详细说明。 +审计功能会将您过去的智能体 CLI 记录通过 failproofai 的策略引擎进行回放，并在 **`/audit` 仪表板页面**生成一份可分享的可视化报告——包括您的智能体原型、0 到 100 的评分，以及哪些策略会捕获哪些问题。 ## 运行方式 -有三种入口——均指向同一份 `/audit` 报告。 +有三种入口，最终都会进入同一份 `/audit` 报告。 @@ -33,56 +33,57 @@ failproofai - `npx -y failproofai audit` 会自动获取 failproofai、执行扫描，并为你打开仪表板——无需提前安装任何内容。 + `npx -y failproofai audit` 会自动获取 failproofai、执行扫描并为您打开仪表板——无需提前安装任何东西。 - - `failproofai audit` 在终端中执行扫描，完成后自动打开 `localhost:8020/audit`。 + + `failproofai audit` 在终端中运行扫描，完成后自动打开 + `localhost:8020/audit`。 - - 运行 `failproofai` 后点击导航栏中的 **Audit**（位于 Policies 和 Projects 之间），或直接访问 `/audit`。 + + 运行 `failproofai`，点击导航栏中的 **Audit**（位于 Policies 和 Projects 之间），或直接打开 `/audit`。 - 运行 `failproofai audit -h`（或 `--help`）可查看用法说明。审计**完全离线**运行——无需账户或网络——仪表板会持续提供服务，直到你按下 `Ctrl+C` 停止。 + 运行 `failproofai audit -h`（或 `--help`）查看使用说明。审计**完全离线**运行——无需账号或网络——仪表板会持续运行，直到您按 `Ctrl+C` 停止。 -仪表板会扫描本机上过去的代理 CLI 记录（Claude Code、Codex、Copilot、Cursor、OpenCode、Pi、Gemini），并报告代理执行 failproofai 旨在阻止的操作的频率——包括环境变量检查、强制推送、冗余的 `cd ` 前缀、轮询睡眠循环、重复读取刚编辑过的文件等。 +仪表板会扫描本机上过去的智能体 CLI 记录（Claude Code、Codex、Copilot、Cursor、OpenCode、Pi、Gemini），并报告智能体执行了哪些 failproofai 旨在阻止的操作——环境变量检查、强制推送、冗余的 `cd ` 前缀、轮询 sleep 循环、重复读取刚编辑的文件等。 -针对每条记录，所有工具使用事件都会通过 39 个内置策略以及 8 个仅用于审计的探测器进行重放，后者可捕获运行时策略尚未覆盖的模式。计数会按策略/探测器维度跨所有会话进行聚合。 +对于每条记录，每个工具调用事件都会通过 39 条内置策略以及 8 个仅限审计的检测器进行回放——这些检测器可识别运行时策略尚未覆盖的模式。计数按策略/检测器维度在所有会话中汇总。 ## 报告内容 -`/audit` 页面是一个单屏可共享的**海报**，下方附有四个区块： +`/audit` 页面是一张单屏可分享的**海报**，后跟四个折叠下方的区块： -1. **海报** — 代理身份一览：其**原型**（共 8 种：`optimist`、`cowboy`、`explorer`、`goldfish`、`paranoid architect`、`precision builder`、`hammer`、`ghost`）、角色关键词、该原型的稀有程度，以及带有等级区间（`S` 至 `bottom tier`）的 **0–100 评分**。专为分享设计——可发布到 X 或 LinkedIn，或下载为 PNG。 -2. **`// strengths`** — 代理已做得很好的方面，以扫描得出的真实数据呈现（如 clean-tool-call 百分比、`0` 次推送主干尝试），仅在相关策略记录清白时显示。 -3. **`// quirks`** — 漏网之鱼：一份按优先级排序的行为表格，列出 failproofai 本可捕获的行为——*最后发生时间*、*漏过的内容*（以及应对的内置策略）、*严重程度*，以及出现频率（`new` / `recurring` / `N× seen`）。 -4. **`// how to improve`** — 建议修复清单：每条策略对应一行可直接复制粘贴的 `failproofai policy add ` 命令，另有一个**全部安装**按钮，可一次性启用所有建议，并显示执行后的**预计评分**。 -5. **`// come back better`** — 养成习惯：设置重新审计的邮件**提醒**（`3d` / `7d` / `14d` / `30d`）或立即重新审计，并**邀请朋友**进行他们自己的审计（由 failproof.ai 发送，抄送给你）。提醒和邀请功能需要登录——请参阅 [`failproofai auth`](/zh/cli/auth)。 +1. **海报** — 一目了然地展示您的智能体身份：其**原型**（共 8 种——`optimist`、`cowboy`、`explorer`、`goldfish`、`paranoid architect`、`precision builder`、`hammer`、`ghost`）、人物关键词、该原型的稀有程度，以及带有层级标识的 **0 到 100 评分**（从 `S` 到 `bottom tier`）。专为分享而设计——可发布到 X 或 LinkedIn，也可下载为 PNG。 +2. **`// strengths`** — 您的智能体已经表现良好的方面，来自扫描的真实数据（例如干净工具调用率、`0` 次推送到主分支的尝试），仅在相关策略记录完全干净时显示。 +3. **`// quirks`** — 漏掉了什么：按优先级排列的行为表格，列出 failproofai 本可捕获的操作——*最近发生时间*、*泄漏内容*（以及会阻止它的内置规则）、*严重程度*，以及出现频率（`new` / `recurring` / `N× seen`）。 +4. **`// how to improve`** — 建议修复列表：每条策略对应一行可复制粘贴的 `failproofai policy add ` 命令，以及一个**一键安装全部**按钮，可同时启用所有建议，并显示执行后的**预期评分**。 +5. **`// come back better`** — 培养习惯：设置重新审计的邮件**提醒**（`3d` / `7d` / `14d` / `30d`）或立即重新审计，并**邀请好友**进行自己的审计（由 failproof.ai 发送，抄送给您）。提醒和邀请需要登录——请参阅 [`failproofai auth`](/zh/cli/auth)。 -## 仅用于审计的探测器 +## 仅限审计的检测器 -这些探测器用于检测尚未（在运行时）强制执行的"低效行为"模式。它们仅在审计期间运行，不会阻止实时工具调用。 +这些检测器用于识别尚未在实时环境中强制执行的"低效行为"模式。它们仅在审计期间运行，不会阻止实时工具调用。 -| 探测器 | 统计内容 | +| 检测器 | 统计内容 | |---|---| | `redundant-cd-cwd` | 以 `cd && …` 开头的 Bash 命令，尽管命令已在 `cwd` 中运行。 | | `prefer-edit-over-read-cat` | 对单个源文件使用 `cat`/`head`/`tail`/`less`/`more`——应使用 `Read` 工具。 | | `prefer-edit-over-sed-awk` | 使用 `sed -i` / `awk … > file` 进行原地编辑——应使用 `Edit` 工具。 | -| `prefer-write-over-heredoc` | 使用 heredoc / 多行 `echo > file` 写入文件——应使用 `Write` 工具。 | +| `prefer-write-over-heredoc` | 使用 Heredoc / 多行 `echo > file` 写入文件——应使用 `Write` 工具。 | | `sleep-polling-loop` | 长时间 `sleep N`（≥ 30 秒）或 `while …; sleep …; done` 轮询循环。 | -| `find-from-root` | `find /`、`find /home`、`find /usr` 等——应限定在 `cwd` 范围内。 | -| `git-commit-no-verify` | `git commit … --no-verify` / `-n`，跳过 hooks。 | -| `reread-after-edit` | 在同一会话中对刚刚 `Edit`/`Write` 过的文件执行 `Read`。 | +| `find-from-root` | `find /`、`find /home`、`find /usr` 等——应将范围限定在 `cwd`。 | +| `git-commit-no-verify` | `git commit … --no-verify` / `-n`，跳过钩子。 | +| `reread-after-edit` | 在同一会话中对刚刚 `Edit`/`Write` 的文件执行 `Read`。 | ## 缓存机制 -- **按记录缓存**，路径为 `~/.failproofai/cache/audit/.json`，以 `(mtime, size, engineVersion, detectorVersion)` 为键——当记录或策略/探测器代码发生变化时自动失效。每条缓存项还存储 `cachedAt` 时间戳作为 **TTL 元数据**（不作为缓存键的一部分）；超过 **7 天**的条目在读取时会被拒绝，避免长期缓存的结果与不断演进的探测器意图脱节。 -- **整体结果缓存**，路径为 `~/.failproofai/audit-dashboard.json`（权限 0600）。允许仪表板在导航时即时渲染，无需重新运行。同样在超过 **7 天 TTL** 后读取时被拒绝——`/audit` 随后会回退至空状态并提示重新运行。点击报告底部附近的 `[ re-audit now ]` 可刷新——重新审计会发送 `noCache: true`，从而绕过按记录缓存，重新扫描所有记录而非返回缓存结果；运行过程通过顶部固定条带流式显示进度，成功后原地替换结果（无需刷新页面；重新审计失败时保留上次报告）。 +- **逐记录缓存**位于 `~/.failproofai/cache/audit/.json`，以 `(mtime, size, engineVersion, detectorVersion)` 为键——当记录或策略/检测器代码发生变化时自动失效。每个条目还存储 `cachedAt` 时间戳作为 **TTL 元数据**（不作为缓存键的一部分）；超过 **7 天**的条目在读取时会被拒绝，以防止长期存在的结果与不断演进的检测器意图产生偏差。 +- **整体结果缓存**位于 `~/.failproofai/audit-dashboard.json`（权限 0600）。允许仪表板在导航时即时渲染，无需重新运行。同样超过 **7 天 TTL** 后在读取时被拒绝——`/audit` 随后进入空状态并提示重新运行。点击报告底部的 `[ re-audit now ]` 刷新——重新审计会发送 `noCache: true`，绕过逐记录缓存并重新扫描所有记录，而非返回缓存结果；运行进度通过顶部固定条目流式显示，成功后在原位替换结果（无需重载页面；若重新审计失败，则保留上一份报告）。 ## 注意事项 -- **不修改任何数据。** 审计以只读模式回放。`warn-repeated-tool-calls` 会被跳过，因为其按会话存储的附属文件否则会被修改。 -- **工作流策略被跳过。** `require-*-before-stop` 策略仅在 `Stop` 事件时触发，并通过 `execSync` 对实时 git 状态进行检查——它们对"2025 年的历史会话中会发生什么"没有实质性的解读意义，因此不会出现在审计计数中。 -- **自定义策略被跳过。** 用户提供的自定义 hooks 不会被重放（它们可能在原始会话之后已发生变化）。 \ No newline at end of file +- **不做任何修改。** 审计以只读模式回放。`warn-repeated-tool-calls` 会被跳过，因为其每个会话的附属文件否则会被修改。 +- **跳过工作流策略。** `require-*-before-stop` 策略仅在 `Stop` 事件时触发，并对实时 git 状态执行 `execSync`——它们在审计场景中没有有意义的"2025 年会发生什么"解读，因此不出现在审计计数中。 +- **跳过自定义策略。** 用户提供的自定义钩子不会被回放（它们可能在原始会话之后发生了变化）。 \ No newline at end of file diff --git a/docs/zh/cli/auth.mdx b/docs/zh/cli/auth.mdx index c67b2317..cccfd035 100644 --- a/docs/zh/cli/auth.mdx +++ b/docs/zh/cli/auth.mdx @@ -5,13 +5,13 @@ description: "通过 CLI 登录 FailproofAI，以启用提醒和个性化功能" ```bash failproofai auth login # 邮箱 + 一次性验证码 -failproofai auth logout # 吊销当前会话 -failproofai auth whoami # 打印已登录的身份信息 +failproofai auth logout # 撤销当前会话 +failproofai auth whoami # 打印当前登录身份 ``` -旧版 `--login` / `--logout` / `--whoami` 标志形式仍作为别名受支持，以保持向后兼容性。 +旧版 `--login` / `--logout` / `--whoami` 标志形式仍可作为别名使用，以保持向后兼容性。 -身份验证为可选功能。无论您是否登录，策略、仪表板、`/audit` 页面及所有其他本地功能的运行方式完全相同。登录功能的存在是为了让**需要**稳定身份的功能（目前是重新审计提醒，未来还会有更多）有所依托。 +身份认证为可选功能。无论您是否登录，策略、仪表板、`/audit` 页面及所有其他本地功能的工作方式完全相同。登录功能的存在是为了让**需要**稳定身份的特性（目前是重新审计提醒，未来还会有更多）有所依托。 ## 登录流程 @@ -19,29 +19,29 @@ failproofai auth whoami # 打印已登录的身份信息 failproofai auth login ``` -提示输入您的邮箱，向该地址发送一个 6 位一次性验证码，然后提示输入验证码。成功后，将在 `~/.failproofai/auth.json`（权限为 `0600`）中写入会话信息。此后该会话将在应用内仪表板中可见——在 `/audit` 页面点击 `[ set a reminder ]` 时，系统将识别您为已登录状态。 +提示输入您的邮箱，向该地址发送 6 位一次性验证码，提示输入验证码，成功后将写入 `~/.failproofai/auth.json`（权限模式 `0600`）。同一会话随后在应用内仪表板中可见——在 `/audit` 页面点击 `[ set a reminder ]` 时将识别您为已登录状态。 -仪表板还在 `/audit` 页面以模态对话框的形式提供相同的登录流程，供从未使用过 CLI 的用户使用。 +对于从未使用 CLI 的用户，仪表板在 `/audit` 页面以模态对话框的形式提供相同的登录流程。 -## 登出 +## 退出登录 ```bash failproofai auth logout ``` -在服务器端吊销当前会话，并删除 `~/.failproofai/auth.json`。如果无法连接到 API 服务器，无论如何都会删除本地文件——本地的登出意图始终优先。 +撤销服务器上的当前会话并删除 `~/.failproofai/auth.json`。若 API 服务器不可达，无论如何都会删除本地文件——本地的退出登录意图始终优先。 -## 身份验证 +## 身份确认 ```bash failproofai auth whoami ``` -当有效会话存在时，打印 ` ()` 并以退出码 0 退出；否则打印 `not signed in` 并以退出码 1 退出。如果访问令牌距离过期不足一分钟，将在后台静默刷新。 +当有效会话存在时，打印 ` ()` 并以退出码 0 退出；否则打印 `not signed in` 并以退出码 1 退出。若访问令牌距过期不足一分钟，则在后台静默刷新。 ## 持久化重新审计提醒 -当您在 `/audit` 页面点击 **`[ set a reminder ]`**（或通过该按钮触发的模态框登录）时，仪表板会在 `~/.failproofai/next-audit.json` 写入一个小型配套文件： +当您在 `/audit` 页面点击 **`[ set a reminder ]`**（或通过该按钮触发的模态框登录）时，仪表板会在 `~/.failproofai/next-audit.json` 写入一个小型辅助文件： ```json { @@ -51,9 +51,9 @@ failproofai auth whoami } ``` -该文件与设置它时所用的邮箱绑定——将 CLI 会话切换到不同账号后，属于前一用户的提醒将被隐藏。默认偏移量为 **7 天**，调度器上线后可进行配置。与 `auth.json` 一样，以 `0600` 权限创建。 +该文件与设置时所用的邮箱绑定——将 CLI 会话切换到其他账户后，属于上一用户的提醒将被隐藏。默认间隔为 **7 天**，调度器上线后可进行配置。与 `auth.json` 一样，文件以 `0600` 权限创建。 -仪表板的 `/api/auth/reminder` 接口提供 `GET`（读取）、`POST`（设置/重新调度）和 `DELETE`（清除）方法，并需要有效会话。 +仪表板的 `/api/auth/reminder` 端点提供 `GET`（读取）、`POST`（设置/重新调度）和 `DELETE`（清除）操作，需要有效会话。 ## `~/.failproofai/auth.json` 的内容 @@ -67,21 +67,21 @@ failproofai auth whoami } ``` -以 `0600` 权限创建（仅所有者可读写）。访问令牌为有效期 1 小时的 HS256 JWT；刷新令牌为不透明的 256 位随机字符串，服务器以 `SHA-256(token)` 的形式存储。服务器端会检测刷新令牌的重放攻击，一旦检测到将吊销该用户的所有会话。 +以 `0600` 权限创建（仅所有者可读写）。访问令牌是有效期为 1 小时的 HS256 JWT；刷新令牌是不透明的 256 位随机字符串，服务器以 `SHA-256(token)` 的形式存储。服务器端会检测刷新令牌的重放攻击，并撤销该用户的所有会话。 ## 环境变量 | 变量 | 默认值 | 用途 | |---|---|---| -| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | 覆盖 API 服务器的基础 URL。适用于针对自托管 API 服务器进行本地开发。 | +| `FAILPROOF_API_URL` | `https://api.befailproof.ai` | 覆盖 API 服务器的基础 URL。适用于本地针对自托管 API 服务器进行开发。 | | `FAILPROOFAI_AUTH_DIR` | `~/.failproofai` | 覆盖 `auth.json` 的存储位置。主要用于测试。 | -请参阅[环境变量](/zh/cli/environment-variables)以获取完整列表。 +完整列表请参见[环境变量](/zh/cli/environment-variables)。 ## 故障排查 -**"Could not reach the api-server"** — CLI 无法与 `FAILPROOF_API_URL` 建立 TCP 连接。请检查您的网络连接，或在运行自托管 API 服务器时设置 `FAILPROOF_API_URL`。 +**"Could not reach the api-server"** — CLI 无法与 `FAILPROOF_API_URL` 建立 TCP 连接。请检查您的网络，或在运行自托管 API 服务器时设置 `FAILPROOF_API_URL`。 -**"Rate limited"** — 在 15 分钟窗口内，该邮箱（5 次/邮箱）或 IP（20 次/IP）的登录尝试次数过多，或在同一邮箱上次请求后 30 秒内重新发送。错误消息中包含以秒为单位的重试等待时间。 +**"Rate limited"** — 该邮箱（5次/邮箱）或 IP（20次/IP）在 15 分钟内登录尝试次数过多，或同一邮箱上次请求后的 30 秒重发冷却未结束。错误消息中包含以秒为单位的重试等待时间。 -**验证码被拒绝** — OTP 错误、已过期，或该记录达到 5 次错误猜测的锁定上限。请重新运行 `failproofai auth login` 以请求新的验证码。 \ No newline at end of file +**验证码被拒绝** — OTP 错误、已过期，或该行达到了 5 次错误猜测锁定上限。请重新运行 `failproofai auth login` 以获取新的验证码。 \ No newline at end of file diff --git a/docs/zh/cli/dashboard.mdx b/docs/zh/cli/dashboard.mdx index c280a9c3..c9fa1fb8 100644 --- a/docs/zh/cli/dashboard.mdx +++ b/docs/zh/cli/dashboard.mdx @@ -1,22 +1,22 @@ --- title: 查看会话 -description: "启动控制面板以浏览代理会话并管理策略" +description: "启动仪表板以浏览代理会话并管理策略" --- ```bash failproofai ``` -在 `http://localhost:8020` 启动 Web 控制面板。 +在 `http://localhost:8020` 启动 Web 仪表板。 ## 选项 | 标志 | 描述 | -|------|-------------| +|------|------| | `--port ` | 监听端口（默认：`8020`） | | `--allowed-origins ` | 允许访问开发资源的主机/IP，以逗号分隔 | -若要将控制面板指向非默认的 Claude 项目文件夹，请在启动时设置 `CLAUDE_PROJECTS_PATH` 环境变量。 +如需将仪表板指向非默认的 Claude 项目文件夹，请在启动时设置 `CLAUDE_PROJECTS_PATH` 环境变量。 ## 示例 diff --git a/docs/zh/cli/environment-variables.mdx b/docs/zh/cli/environment-variables.mdx index 3831baa2..22086a71 100644 --- a/docs/zh/cli/environment-variables.mdx +++ b/docs/zh/cli/environment-variables.mdx @@ -29,8 +29,8 @@ description: "通过环境变量配置 failproofai 的行为" | 变量 | 描述 | |----------|-------------| -| `FAILPROOF_API_URL` | 覆盖 `failproofai auth` 及控制台认证对话框所使用的 API 服务器基础 URL。默认为 `https://api.befailproof.ai`；在本地运行 api-server 时，可设为 `http://localhost:8080`（或其他地址）。 | -| `FAILPROOFAI_AUTH_DIR` | 覆盖 `auth.json` 的存储位置（默认：`~/.failproofai`），主要用于隔离测试。 | +| `FAILPROOF_API_URL` | 覆盖 `failproofai auth` 及控制台认证对话框所使用的 API 服务器基础 URL，默认为 `https://api.befailproof.ai`；在本地运行 API 服务器时可设置为 `http://localhost:8080`（或其他地址） | +| `FAILPROOFAI_AUTH_DIR` | 覆盖 `auth.json` 的存储位置（默认：`~/.failproofai`），主要用于隔离测试 | ## 首次运行提示 diff --git a/docs/zh/cli/hook.mdx b/docs/zh/cli/hook.mdx index f8b6311d..e2292b68 100644 --- a/docs/zh/cli/hook.mdx +++ b/docs/zh/cli/hook.mdx @@ -1,5 +1,5 @@ --- -title: Hook 处理程序（内部） +title: Hook 处理器（内部） description: "Claude Code 在每个工具事件上调用的子进程" --- @@ -7,19 +7,19 @@ description: "Claude Code 在每个工具事件上调用的子进程" failproofai --hook ``` -这是由 `failproofai policies --install` 注册到 Claude Code 的 `settings.json` 中的命令。通常情况下，你不需要直接调用它。 +这是由 `failproofai policies --install` 在 Claude Code 的 `settings.json` 中注册的命令。通常情况下，你不需要直接调用它。 -该命令从 stdin 读取 JSON 负载，评估所有已启用的策略，并以退出码的形式返回决策结果： +该命令从 stdin 读取 JSON 数据，评估所有已启用的策略，并以表示决策结果的退出码退出： | 退出码 | 决策 | 效果 | |--------|------|------| | `0` | `allow` | 允许该操作 | -| `1` | `deny` | 阻止该操作——Claude 会看到拒绝原因 | +| `1` | `deny` | 阻止该操作 - Claude 将看到拒绝原因 | | `2` | `instruct` | 向 Claude 的上下文中注入指导信息 | ### 支持的事件类型 -| 分类 | 事件 | +| 类别 | 事件 | |------|------| | **工具执行** | `PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`、`PermissionDenied` | | **会话生命周期** | `SessionStart`、`SessionEnd`、`Stop`、`StopFailure` | diff --git a/docs/zh/cli/install-policies.mdx b/docs/zh/cli/install-policies.mdx index 67f14421..4070f70d 100644 --- a/docs/zh/cli/install-policies.mdx +++ b/docs/zh/cli/install-policies.mdx @@ -1,38 +1,38 @@ --- title: 安装策略 -description: "启用策略，使其在每次 agent 工具调用时运行" +description: "启用策略，使其在每次 Agent 工具调用时运行" --- ```bash failproofai policies --install [policy-names...] [options] ``` -将 hook 条目写入已安装的 agent CLI 的配置文件（Claude Code、OpenAI Codex 或 GitHub Copilot CLI _(beta)_），以便 failproofai 拦截工具调用。 +将 hook 条目写入已安装的 Agent CLI 的配置文件（Claude Code、OpenAI Codex 或 GitHub Copilot CLI _(beta)_），使 failproofai 能够拦截工具调用。 别名：`failproofai p -i` ## 选项 -| 标志 | 描述 | -|------|------| -| `--cli claude\|codex\|copilot` | 要安装的 Agent CLI，用空格分隔（例如 `--cli claude codex copilot`）或重复指定。省略则自动检测已安装的 CLI 并提示选择。 | -| `--scope user` | 安装到用户级别的配置文件（Claude：`~/.claude/settings.json`；Codex：`~/.codex/hooks.json`；Copilot：`~/.copilot/hooks/failproofai.json`）。默认值。 | -| `--scope project` | 安装到项目级别的配置文件（Claude：`/.claude/settings.json`；Codex：`/.codex/hooks.json`；Copilot：`/.github/hooks/failproofai.json`）。 | -| `--scope local` | 仅限 Claude — 安装到 `/.claude/settings.local.json`。Codex 和 Copilot 没有 `local` 作用域。 | +| 参数 | 说明 | +|------|-------------| +| `--cli claude\|codex\|copilot` | 要安装的 Agent CLI，空格分隔（例如 `--cli claude codex copilot`）或重复指定。省略则自动检测已安装的 CLI 并提示选择。 | +| `--scope user` | 安装到用户级配置文件（Claude：`~/.claude/settings.json`；Codex：`~/.codex/hooks.json`；Copilot：`~/.copilot/hooks/failproofai.json`）。默认值。 | +| `--scope project` | 安装到项目级配置文件（Claude：`/.claude/settings.json`；Codex：`/.codex/hooks.json`；Copilot：`/.github/hooks/failproofai.json`）。 | +| `--scope local` | 仅限 Claude — 安装到 `/.claude/settings.local.json`。Codex 和 Copilot 不支持 `local` 作用域。 | | `--custom ` / `-c` | 包含自定义 hook 策略的 JS 文件路径 | -## 行为说明 +## 行为 - **不指定策略名称** — 打开交互式提示以选择策略 -- **指定具体名称** — 启用对应策略（追加到已启用的策略中） +- **指定具体名称** — 启用这些策略（追加到已启用的策略中） - **`all`** — 启用所有可用策略 -安装操作是累加的：再次运行 `--install` 会添加新策略，而不会移除已有策略。 +安装是增量式的：再次运行 `--install` 只会添加新策略，不会移除已有策略。 ## 示例 ```bash -# 以交互方式全局安装所有默认策略 +# 全局安装所有默认策略（交互式） failproofai policies --install # 为当前项目安装特定策略 @@ -41,10 +41,10 @@ failproofai policies --install block-sudo sanitize-api-keys --scope project # 一次性启用所有策略 failproofai policies --install all -# 使用自定义策略文件进行安装 +# 使用自定义策略文件安装 failproofai policies --install --custom ./my-policies.js -# 为 OpenAI Codex 安装（项目作用域） +# 为 OpenAI Codex 安装（项目级作用域） failproofai policies --install --cli codex --scope project # 为 GitHub Copilot CLI (beta) 安装到当前项目 @@ -54,4 +54,4 @@ failproofai policies --install --cli copilot --scope project failproofai policies --install --cli claude codex copilot ``` -提供 `--custom ` 时，文件会立即经过验证 — 它必须至少调用一次 `customPolicies.add()`。解析后的路径将作为 `customPoliciesPath` 保存到 `policies-config.json` 中。 \ No newline at end of file +提供 `--custom ` 时，文件将立即被验证 — 它必须至少调用一次 `customPolicies.add()`。解析后的路径将作为 `customPoliciesPath` 保存到 `policies-config.json` 中。 \ No newline at end of file diff --git a/docs/zh/cli/list-policies.mdx b/docs/zh/cli/list-policies.mdx index 3fbc4ba7..a5bb0b7b 100644 --- a/docs/zh/cli/list-policies.mdx +++ b/docs/zh/cli/list-policies.mdx @@ -1,13 +1,13 @@ --- title: 列出策略 -description: "查看已启用的策略、其参数以及自定义策略" +description: "查看已启用的策略、其参数及自定义策略" --- ```bash failproofai policies ``` -显示所有策略及其状态、已配置的参数和自定义策略。 +显示所有策略的状态、已配置的参数以及自定义策略。 ## 示例输出 @@ -28,4 +28,4 @@ Failproof AI Hook Policies (user) ✓ approval-gate Approval gate for destructive ops ``` -`policyParams` 中未知的键会在此处被标记出来，帮助你尽早发现拼写错误。 \ No newline at end of file +`policyParams` 中的未知键会在此处标记出来，以便您及早发现拼写错误。 \ No newline at end of file diff --git a/docs/zh/cli/remove-policies.mdx b/docs/zh/cli/remove-policies.mdx index 1fddfeac..ffc93e5c 100644 --- a/docs/zh/cli/remove-policies.mdx +++ b/docs/zh/cli/remove-policies.mdx @@ -1,13 +1,13 @@ --- title: 卸载策略 -description: "从 Claude Code 的设置中移除钩子条目" +description: "从 Claude Code 的设置中移除 hook 条目" --- ```bash failproofai policies --uninstall [policy-names...] [options] ``` -从 Claude Code 的 `settings.json` 中移除 failproofai 钩子条目。 +从 Claude Code 的 `settings.json` 中移除 failproofai hook 条目。 别名：`failproofai p -u` @@ -23,19 +23,19 @@ failproofai policies --uninstall [policy-names...] [options] ## 行为说明 -- **不指定策略名称** — 从设置文件中移除所有 failproofai 钩子条目 -- **指定名称** — 禁用对应策略，但保留已安装的钩子 +- **未指定策略名称** - 从设置文件中移除所有 failproofai hook 条目 +- **指定具体名称** - 禁用相应策略，但保留已安装的 hook ## 示例 ```bash -# 全局移除所有钩子 +# 全局移除所有 hook failproofai policies --uninstall -# 禁用特定策略（保留已安装的钩子） +# 禁用特定策略（保留已安装的 hook） failproofai policies --uninstall block-sudo -# 从所有作用域中移除钩子 +# 从所有作用域中移除 hook failproofai policies --uninstall --scope all # 清除自定义策略路径 diff --git a/docs/zh/cli/version.mdx b/docs/zh/cli/version.mdx index 190b457e..4aac04f4 100644 --- a/docs/zh/cli/version.mdx +++ b/docs/zh/cli/version.mdx @@ -1,5 +1,5 @@ --- -title: 检查版本 +title: 查看版本 description: "打印已安装的 failproofai 版本" --- diff --git a/docs/zh/configuration.mdx b/docs/zh/configuration.mdx index 214270d3..21fbaf5f 100644 --- a/docs/zh/configuration.mdx +++ b/docs/zh/configuration.mdx @@ -1,16 +1,16 @@ --- title: 配置 -description: "配置文件格式、三层作用域系统及合并规则" +description: "配置文件格式、三级作用域系统与合并规则" icon: gear --- -failproofai 使用 JSON 配置文件来控制哪些策略处于激活状态、它们的行为方式以及从何处加载自定义策略。配置设计上便于与团队共享——将其提交到代码仓库，每位开发者都能获得相同的 Agent 安全防护。 +failproofai 使用 JSON 配置文件来控制哪些策略处于启用状态、策略的行为方式，以及自定义策略的加载路径。配置设计上便于团队共享——将其提交到仓库，每位开发者都能获得相同的 AI 代理安全防护。 --- ## 配置作用域 -共有三个配置作用域，按优先级顺序依次评估： +共有三个配置作用域，按优先级顺序评估： | 作用域 | 文件路径 | 用途 | |-------|-----------|---------| @@ -18,11 +18,11 @@ failproofai 使用 JSON 配置文件来控制哪些策略处于激活状态、 | **local** | `.failproofai/policies-config.local.json` | 个人的仓库级覆盖配置，已加入 gitignore | | **global** | `~/.failproofai/policies-config.json` | 适用于所有项目的用户级默认配置 | -当 failproofai 收到 hook 事件时，它会加载并合并当前工作目录下所有存在的三个文件。 +当 failproofai 收到 hook 事件时，会加载并合并当前工作目录下所有已存在的三个文件。 ### 合并规则 -**`enabledPolicies`** — 取三个作用域的并集。任意级别启用的策略均处于激活状态。 +**`enabledPolicies`** — 取三个作用域的并集。任意级别启用的策略都会生效。 ```text project: ["block-sudo"] @@ -32,26 +32,26 @@ 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 -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 +resolved: { allowPatterns: ["sudo systemctl status"] } ← 回退到 global ``` -**`customPoliciesPath`** — 最先定义的作用域优先。 +**`customPoliciesPath`** — 最先定义该字段的作用域胜出。 -**`llm`** — 最先定义的作用域优先。 +**`llm`** — 最先定义该字段的作用域胜出。 --- @@ -102,25 +102,25 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← 向下回退至 glob 类型：`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` 时会以警告形式标出。 +策略参数块中未知的键在 hook 触发时会被静默忽略，但在运行 `failproofai policies` 时会作为警告标记出来。 -#### `hint`（通用参数） +#### `hint`（通用配置项） 类型：`string`（可选） -当策略返回 deny 或 instruct 时，附加到原因说明中的消息。使用它可以在不修改策略本身的情况下，为 Claude 提供可操作的指导。 +当策略返回 `deny` 或 `instruct` 时，附加到原因后面的消息。可用于在不修改策略本身的情况下，向 Claude 提供可操作的指引。 适用于任何类型的策略——内置策略、自定义策略（`custom/`）、项目约定策略（`.failproofai-project/`）或用户约定策略（`.failproofai-user/`）。 @@ -143,38 +143,38 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← 向下回退至 glob 当 block-force-push 拒绝操作时，Claude 会看到：*"Force-pushing is blocked. Try creating a fresh branch instead."* -非字符串值和空字符串会被静默忽略。如果未设置 `hint`，行为保持不变（向后兼容）。 +非字符串值和空字符串会被静默忽略。若未设置 `hint`，行为保持不变（向后兼容）。 ### `customPoliciesPath` 类型：`string`（绝对路径） -包含自定义 hook 策略的 JavaScript 文件路径。此路径由 `failproofai policies --install --custom ` 自动设置（路径在存储前会被解析为绝对路径）。 +包含自定义 hook 策略的 JavaScript 文件路径。该值由 `failproofai policies --install --custom ` 自动设置（路径在存储前会被解析为绝对路径）。 -每次 hook 事件触发时都会重新加载该文件，不使用缓存。自定义策略的编写详情请参阅[自定义策略](/zh/custom-policies)。 +每次 hook 事件触发时都会重新加载该文件，不进行缓存。有关编写自定义策略的详情，请参见[自定义策略](/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` 中添加任何条目，只需将文件放入对应目录，下次 hook 事件触发时即可自动生效。 -**联合加载：** 项目级和用户级约定目录都会被扫描。两个级别的所有匹配文件都会被加载（与 `customPoliciesPath` 遵循先定义者优先的规则不同）。 +**联合加载：** 项目和用户约定目录都会被扫描，两个级别中所有匹配的文件都会被加载（与 `customPoliciesPath` 采用首个作用域胜出的方式不同）。 -更多详情和示例请参阅[自定义策略](/zh/custom-policies)。 +更多详情和示例请参见[自定义策略](/zh/custom-policies)。 ### `llm` 类型：`object`（可选） -供需要进行 AI 调用的策略使用的 LLM 客户端配置。大多数场景下无需配置。 +供策略进行 AI 调用的 LLM 客户端配置，大多数场景下无需配置。 ```json { @@ -189,19 +189,20 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← 向下回退至 glob ## 通过 CLI 管理配置 -`policies --install` 和 `policies --uninstall` 命令会写入 Agent CLI 的 hook 设置文件（hook 入口点），而 `policies-config.json` 是你直接管理的文件。两者是相互独立的： +`policies --install` 和 `policies --uninstall` 命令会写入代理 CLI 的 hook 设置文件（hook 入口点），而 `policies-config.json` 是由你直接管理的文件，两者相互独立： -- **Agent CLI 设置** — 指示 Agent 在每次工具调用时执行 `failproofai --hook `： +- **代理 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` 作用域。Hook 条目使用 Copilot 的操作系统键化 `bash`/`powershell` 命令字段（含 `timeoutSec`）；文件顶层包含 `version: 1` 标记。Copilot CLI 支持目前处于 **beta** 阶段，我们正在对照更多真实场景验证 `events.jsonl` 记录的 schema（公开文档中未予说明）。 - - **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` 将驼峰式名称规范化为 PascalCase，因此现有内置策略无需改动即可正常触发。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 在转发给二进制文件之前，会将工具名称（小写 → PascalCase，通过 `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 会写入一个 packages 数组条目，指向其捆绑的 `pi-extension/` 目录。扩展内部订阅 Pi 的 `tool_call` / `user_bash` / `input` / `session_start` 事件，并调用 `failproofai --hook --cli pi`；处理程序通过 `PI_EVENT_MAP` 将下划线小写命名规范化为 PascalCase，因此现有内置策略无需改动即可正常触发。工具输入参数也通过 `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 和会话日志格式趋于稳定。 - - **Gemini CLI _(beta)_**：`~/.gemini/settings.json`（用户级）、`/.gemini/settings.json`（项目级）—— Gemini 没有 `local` 作用域（其文档中有位于 `/etc/gemini-cli/settings.json` 的 `system` 作用域，failproofai 不对外暴露该作用域）。Hook 条目使用 Claude 的 `{type, command, timeout}` 格式，包裹在 Gemini 的 `{matcher, hooks: [...]}` matcher schema 中，默认 `matcher: "*"`。事件名称为 PascalCase（`SessionStart`、`BeforeAgent`、`AfterAgent`、`BeforeModel`、`AfterModel`、`BeforeToolSelection`、`BeforeTool`、`AfterTool`、`PreCompress`、`Notification`、`SessionEnd`）；处理程序通过 `GEMINI_EVENT_MAP` 映射到 Claude 规范名称。工具名称为 snake_case（`run_shell_command`、`read_file`、`write_file`、`replace` 等）——处理程序通过 `GEMINI_TOOL_MAP` 规范化，使现有内置策略无需改动即可正常触发。策略评估器输出 Gemini 的平铺 `{decision: "deny", reason}` 格式（符合 Gemini 的"黄金规则"退出码 0 约定），在 BeforeAgent / AfterTool / SessionStart 时输出 `{hookSpecificOutput: {hookEventName, additionalContext}}` 进行上下文注入，在 AfterAgent 时输出 `{decision: "block", reason}` 以实现强制重试语义。Gemini CLI 支持目前处于 **beta** 阶段，我们正在扩大真实场景的覆盖范围。详见 [Gemini CLI hooks 文档](https://geminicli.com/docs/hooks/)。 -- **`policies-config.json`** — 告知 failproofai 要评估哪些策略及其参数（在所有 Agent CLI 之间共享） + - **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 和会话日志格式稳定。 + - **Gemini CLI _(beta)_**：`~/.gemini/settings.json`（用户级）、`/.gemini/settings.json`（项目级）——Gemini 没有 `local` 作用域（其文档记录了 `/etc/gemini-cli/settings.json` 的 `system` 作用域，failproofai 未对外暴露该作用域）。Hook 条目使用 Claude 的 `{type, command, timeout}` 格式，包裹在 Gemini 的 `{matcher, hooks: [...]}` 匹配器模式中，默认 `matcher: "*"`。事件采用帕斯卡式（`SessionStart`、`BeforeAgent`、`AfterAgent`、`BeforeModel`、`AfterModel`、`BeforeToolSelection`、`BeforeTool`、`AfterTool`、`PreCompress`、`Notification`、`SessionEnd`）；处理器通过 `GEMINI_EVENT_MAP` 映射到 Claude 规范名称。工具名称采用蛇形命名（`run_shell_command`、`read_file`、`write_file`、`replace` 等）——处理器通过 `GEMINI_TOOL_MAP` 规范化，使现有内置策略正常触发。策略评估器输出 Gemini 的扁平 `{decision: "deny", reason}` 格式（符合 Gemini 的"黄金规则"exit-0 约定），在 BeforeAgent / AfterTool / SessionStart 时输出 `{hookSpecificOutput: {hookEventName, additionalContext}}` 进行上下文注入，在 AfterAgent 时输出 `{decision: "block", reason}` 实现强制重试语义。Gemini CLI 支持目前为 **beta** 版本，我们正在扩大实际场景覆盖范围。详见 [Gemini CLI hooks 文档](https://geminicli.com/docs/hooks/)。 + - **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|gemini` 指定目标 Agent（空格分隔或重复指定，可选任意组合）： +通过 `--cli claude|codex|copilot|cursor|opencode|pi|gemini|hermes` 指定目标代理（可用空格分隔或重复指定多个）： ```bash failproofai policies --install --cli codex --scope project @@ -210,23 +211,24 @@ 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 gemini --scope project +failproofai policies --install --cli hermes --scope user failproofai policies --install --cli claude codex copilot cursor opencode pi gemini ``` -省略 `--cli` 时，`failproofai` 会自动检测已安装的 Agent CLI（`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`）： +省略 `--cli` 时，`failproofai` 会自动检测已安装的代理 CLI（`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini` / `which hermes`）： - **检测到一个 CLI** — 自动选择该 CLI，无需提示。 -- **检测到多个 CLI**（交互式终端）— 显示方向键单选提示，分组展示：`已检测 (N)` 部分（包含一个"为所有 N 个已检测 CLI 安装"的聚合选项，以及各已检测 CLI 的单独选项）和`未安装 (M) · 提前安装 hooks` 部分（列出每个未检测到的受支持 CLI 作为预安装选项；↑↓ 移动，Enter 选择，^C 退出）。卸载流程只显示已检测部分。 -- **检测到多个 CLI**（非交互式运行，如 CI 或无 TTY）— 为所有已检测 CLI 安装，无需提示。 -- **未检测到任何 CLI** — 回退至 `claude`，并警告 PATH 中未找到 Agent 二进制文件；hook 命令仍会写入，待安装后即可激活。 +- **在交互式终端中检测到多个 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 命令仍会被写入，一旦安装代理即可生效。 -你可以随时直接编辑 `policies-config.json`，更改在下次 hook 事件触发时立即生效，无需重启。 +你可以随时直接编辑 `policies-config.json`，修改将在下一次 hook 事件触发时立即生效，无需重启。 --- -## 示例：包含团队默认配置的项目级配置 +## 示例：带团队默认配置的项目级配置 -将 `.failproofai/policies-config.json` 提交到代码仓库： +将 `.failproofai/policies-config.json` 提交到你的仓库： ```json { @@ -245,4 +247,4 @@ failproofai policies --install --cli claude codex copilot cursor opencode pi gem } ``` -每位开发者可以在本地创建 `.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 f58eeb94..cb4dd136 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、审批工作流等系统集成。它们使用与内置策略相同的钩子事件系统和 `allow`、`deny`、`instruct` 决策机制。 +自定义策略让你可以为任何 Agent 行为编写规则：强制执行项目规范、防止配置漂移、拦截破坏性操作、检测卡死的 Agent，或与 Slack、审批工作流等外部系统集成。它们使用与内置策略相同的 Hook 事件系统以及 `allow`、`deny`、`instruct` 决策。 --- @@ -37,33 +37,33 @@ failproofai policies --install --custom ./my-policies.js --- -## 加载自定义策略的两种方式 +## 两种加载自定义策略的方式 ### 方式一：基于约定（推荐） -将 `*policies.{js,mjs,ts}` 文件放入 `.failproofai/policies/` 目录，它们会被自动加载——无需任何命令行参数或配置更改。这与 git hooks 的工作方式类似：放入文件，直接生效。 +将 `*policies.{js,mjs,ts}` 文件放入 `.failproofai/policies/` 目录，它们会被自动加载——无需任何命令行参数或配置变更。这和 git hooks 的用法一样：放入文件即生效。 ``` -# 项目级——提交到 git，与团队共享 +# 项目级别——提交到 git，与团队共享 .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# 用户级——个人使用，适用于所有项目 +# 用户级别——个人配置，适用于所有项目 ~/.failproofai/policies/my-policies.mjs ``` **工作原理：** -- 项目目录和用户目录均会被扫描（取并集，而非先匹配者优先） -- 每个目录内的文件按字母顺序加载；可用 `01-`、`02-` 前缀控制顺序 +- 项目目录和用户目录均会被扫描（取并集，而非"第一个作用域优先"） +- 文件在各自目录内按字母顺序加载；可使用 `01-`、`02-` 前缀控制顺序 - 仅加载匹配 `*policies.{js,mjs,ts}` 的文件，其他文件会被忽略 -- 每个文件独立加载（单个文件失败时采用宽松策略） -- 可与显式 `--custom` 参数及内置策略共存 +- 每个文件独立加载（单文件失败不影响其他文件） +- 可与显式 `--custom` 及内置策略共存 -基于约定的策略是为团队建立质量标准的最便捷方式。将 `.failproofai/policies/` 提交到 git，每位团队成员就能自动获得相同的规则——无需逐个开发者配置。随着团队发现新的故障模式，只需添加一个策略并推送。随着时间推移，这些策略将成为一套随每次贡献不断完善的活质量标准。 +基于约定的策略是为团队建立质量标准的最简便方式。将 `.failproofai/policies/` 提交到 git，每位团队成员都会自动获得相同的规则，无需任何个人配置。随着团队不断发现新的故障模式，添加策略并推送即可。久而久之，这些策略将成为随着每次贡献持续完善的质量标准。 -### 方式二：显式文件路径 +### 方式二：显式指定文件路径 ```bash # 安装时指定自定义策略文件 @@ -76,7 +76,7 @@ failproofai policies --install --custom ./new-policies.js failproofai policies --uninstall --custom ``` -解析后的绝对路径会以 `customPoliciesPath` 字段存储在 `policies-config.json` 中。每次钩子事件触发时都会重新加载该文件，事件之间不存在缓存。 +解析后的绝对路径会作为 `customPoliciesPath` 存储在 `policies-config.json` 中。每次 Hook 事件触发时都会重新加载该文件，事件之间不存在缓存。 ### 两种方式同时使用 @@ -98,7 +98,7 @@ import { customPolicies, allow, deny, instruct } from "failproofai"; ### `customPolicies.add(hook)` -注册一个策略。同一文件中可多次调用以注册多个策略。 +注册一条策略。可在同一文件中多次调用以注册多条策略。 ```ts customPolicies.add({ @@ -111,32 +111,32 @@ 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(message)` 允许操作**并**向 Claude 发送一条信息性消息。该消息以 `additionalContext` 的形式通过钩子处理器的 stdout 响应传递——与 `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,7 +158,7 @@ customPolicies.add({ ### `PolicyContext` 字段 | 字段 | 类型 | 描述 | -|-------|------|-------------| +|------|------|------| | `eventType` | `string` | `"PreToolUse"`、`"PostToolUse"`、`"Notification"`、`"Stop"` | | `toolName` | `string \| undefined` | 被调用的工具（例如 `"Bash"`、`"Write"`、`"Read"`） | | `toolInput` | `Record \| undefined` | 工具的输入参数 | @@ -168,19 +168,19 @@ 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" \| ... }` ——钩子必须始终返回 `allow()`，不能阻止通知 | -| `Stop` | Claude 会话结束时 | 为空 | +| `PostToolUse` | 工具执行完成之后 | 工具的输入 + `tool_result`（输出内容） | +| `Notification` | Claude 发送通知时 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` —— Hook 必须始终返回 `allow()`，不能阻止通知 | +| `Stop` | Claude 会话结束时 | 空 | --- @@ -190,11 +190,11 @@ 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` 消息会被累积并一并发送。 --- @@ -218,7 +218,7 @@ customPolicies.add({ }); ``` -所有从入口文件可达的相对导入均会被解析。实现方式是将 `from "failproofai"` 的导入重写为实际的 dist 路径，并创建临时 `.mjs` 文件以确保 ESM 兼容性。 +所有从入口文件可达的相对导入均会被解析。其实现方式是将 `from "failproofai"` 的导入重写为实际的 dist 路径，并创建临时 `.mjs` 文件以确保 ESM 兼容性。 --- @@ -238,26 +238,26 @@ customPolicies.add({ }); ``` -完全省略 `match` 则在每种事件类型上都触发。 +完全省略 `match` 则对所有事件类型触发。 --- -## 错误处理与失败模式 +## 错误处理与故障模式 -自定义策略采用**宽松失败**策略：错误不会阻止内置策略运行，也不会导致钩子处理器崩溃。 +自定义策略采用**失败开放**原则：错误不会阻止内置策略运行，也不会导致 Hook 处理器崩溃。 | 故障情况 | 行为 | -|---------|----------| +|----------|------| | 未设置 `customPoliciesPath` | 不运行显式自定义策略；约定策略和内置策略正常继续 | | 文件未找到 | 警告记录到 `~/.failproofai/hook.log`；内置策略继续运行 | | 语法/导入错误（显式） | 错误记录到 `~/.failproofai/hook.log`；跳过显式自定义策略 | -| 语法/导入错误（约定） | 错误记录；跳过该文件，其他约定文件仍正常加载 | -| `fn` 运行时抛出异常 | 错误记录；该钩子视为 `allow`；其他钩子继续运行 | +| 语法/导入错误（约定） | 错误记录；跳过该文件，其他约定文件继续加载 | +| `fn` 运行时抛出异常 | 错误记录；该 Hook 视为 `allow`；其他 Hook 继续运行 | | `fn` 执行超过 10 秒 | 超时记录；视为 `allow` | | 约定目录不存在 | 不运行约定策略；不报错 | -要调试自定义策略错误，可监听日志文件： +要调试自定义策略错误，可以实时查看日志文件： ```bash tail -f ~/.failproofai/hook.log @@ -266,13 +266,13 @@ tail -f ~/.failproofai/hook.log --- -## 完整示例：多个策略 +## 完整示例：多条策略 ```js // 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 +285,7 @@ customPolicies.add({ }, }); -// 保持 Agent 方向正确：提交前验证测试 +// 引导 Agent 保持正轨：提交前验证测试 customPolicies.add({ name: "remind-test-before-commit", description: "Keep the agent on track: verify tests pass before committing", @@ -321,15 +321,15 @@ export { customPolicies }; --- -## 示例 +## 示例文件 `examples/` 目录包含可直接运行的策略文件： | 文件 | 内容 | -|------|----------| -| `examples/policies-basic.js` | 涵盖常见 Agent 故障模式的五个入门策略 | -| `examples/policies-advanced/index.js` | 高级模式：传递性导入、异步调用、输出脱敏和会话结束钩子 | -| `examples/convention-policies/security-policies.mjs` | 基于约定的安全策略（阻止 .env 写入、防止 git 历史改写） | +|------|------| +| `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` | 基于约定的工作流策略（测试提醒、审计文件写入） | ### 使用显式文件示例 @@ -341,13 +341,13 @@ 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 +无需安装命令——文件在下次 Hook 事件触发时会被自动加载。 \ No newline at end of file diff --git a/docs/zh/dashboard.mdx b/docs/zh/dashboard.mdx index dc58ca9b..721b39e2 100644 --- a/docs/zh/dashboard.mdx +++ b/docs/zh/dashboard.mdx @@ -1,14 +1,14 @@ --- -title: 仪表板 +title: 控制台 description: "监控 Agent 会话、查看工具调用并管理策略" icon: chart-line --- -failproofai 仪表板是一个用于监控 AI Agent 会话和管理策略的本地 Web 应用程序。查看 Agent 在你离开时做了什么。 +failproofai 控制台是一个本地 Web 应用，用于监控 AI Agent 会话和管理策略。查看 Agent 在你离开期间的所有操作。 --- -## 启动仪表板 +## 启动控制台 ```bash failproofai @@ -16,58 +16,58 @@ failproofai 在 `http://localhost:8020` 打开。 -仪表板直接从文件系统读取数据——包括你的 Claude Code 项目文件夹和 failproofai 配置文件。不会向任何远程服务写入数据。 +控制台直接从文件系统读取数据——包括你的 Claude Code 项目文件夹和 failproofai 配置文件。不会向任何远程服务写入数据。 --- -## 页面 +## 页面说明 ### 项目 -列出在你机器上发现的所有 Claude Code、OpenAI Codex、GitHub Copilot CLI _(测试版)_、Cursor Agent _(测试版)_、OpenCode _(测试版)_、Pi _(测试版)_ 和 Gemini CLI _(测试版)_ 项目。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` 来发现；Gemini CLI 项目通过扫描 `~/.gemini/tmp//chats/session--.jsonl`（可通过 `GEMINI_SESSIONS_DIR` 配置），并从同级 `.project_root` 文本标记中恢复规范 cwd 来发现。被多个 CLI 使用的项目会渲染为单行并显示所有匹配的标记。使用表格上方的 **CLI** 下拉菜单按特定 Agent CLI 筛选；URL 会将你的选择保存为 `?cli=claude|codex|copilot|cursor|opencode|pi|gemini`。 +列出在你的机器上发现的所有 Claude Code、OpenAI Codex、GitHub Copilot CLI _(beta)_、Cursor Agent _(beta)_、OpenCode _(beta)_、Pi _(beta)_、Gemini CLI _(beta)_ 和 Hermes 项目。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` 发现；Gemini CLI 项目通过扫描 `~/.gemini/tmp//chats/session--.jsonl`（可通过 `GEMINI_SESSIONS_DIR` 配置），并从同级 `.project_root` 文本标记中恢复规范化 cwd 发现；Hermes 网关会话直接从 `~/.hermes/state.db`（可通过 `HERMES_DB_PATH` 配置）的 SQLite 存储中读取，并按 `source`（Slack/Telegram/cli/cron——网关会话没有 cwd）分组为 `hermes-` 项目。被多个 CLI 使用的项目在同一行显示，并附上所有匹配的徽章。使用表格上方的 **CLI** 下拉菜单按特定 Agent CLI 筛选；URL 会将你的选择保存为 `?cli=claude|codex|copilot|cursor|opencode|pi|gemini|hermes`。 每个项目显示： - 项目名称（从文件夹路径派生） -- CLI 标记——`Claude Code`（橙色）、`OpenAI Codex`（紫色）、`GitHub Copilot`（蓝色）、`Cursor Agent`（翠绿色）、`OpenCode`（琥珀色）、`Pi`（粉色）和/或 `Gemini CLI`（天蓝色） -- 最近会话活动的日期 +- CLI 徽章——`Claude Code`（橙色）、`OpenAI Codex`（紫色）、`GitHub Copilot`（蓝色）、`Cursor Agent`（翠绿色）、`OpenCode`（琥珀色）、`Pi`（粉色）、`Gemini CLI`（天蓝色）和/或 `Hermes`（靛蓝色） +- 最近一次会话活动的日期 -点击项目可查看其会话。 +点击项目可查看其会话列表。 ### 会话 -列出某个项目中的所有会话。每个会话显示： +列出项目内的所有会话。每个会话显示： - 会话 ID - 开始和结束时间戳 - 工具调用次数 -- Hook 活动次数（触发的策略数） +- Hook 活动计数（触发的策略数量） -使用日期范围筛选器和会话 ID 搜索来缩小列表范围。会话支持分页。 +使用日期范围筛选和会话 ID 搜索来缩小列表范围。会话以分页形式显示。 点击会话可打开会话查看器。 ### 会话查看器 -会话查看器回答了自主 Agent 的核心问题：Agent 做了什么，是否保持在正轨上？标题旁的 CLI 标记表明该会话是 Claude Code、OpenAI Codex、GitHub Copilot CLI、Cursor Agent、OpenCode、Pi 还是 Gemini CLI 的记录。它显示会话中发生的所有事情的时间线： +会话查看器回答了自主 Agent 的核心问题：Agent 做了什么，是否保持在正轨上？页眉旁的 CLI 徽章指示该会话是 Claude Code、OpenAI Codex、GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Gemini CLI 还是 Hermes 的记录。它以时间线形式展示会话中发生的所有事件： - **消息** - Claude 的文本回复和用户提示 -- **工具调用** - Claude 调用的每个工具，包括其输入和输出 -- **策略活动** - 针对每个工具调用，显示哪些策略触发了以及返回了什么决策 +- **工具调用** - Claude 调用的每个工具，包含其输入和输出 +- **策略活动** - 每次工具调用触发了哪些策略及其返回的决策 -顶部的统计栏显示会话时长、工具调用总数以及 hook 决策摘要（allow / deny / instruct 计数）。 +顶部的统计栏显示会话时长、工具调用总数，以及 Hook 决策摘要（allow / deny / instruct 计数）。 -点击 **Download Logs** 按钮可导出会话。对于 Claude Code、Codex、Copilot、Cursor、Pi 和 Gemini 会话，你将获得磁盘上原始的 JSONL 记录（逐字节）；对于 OpenCode（其会话存储在 SQLite 中而非磁盘文件）,你将获得一个镜像底层 `session` / `messages` / `parts` 表的 JSON 文档。 +点击**下载日志**按钮可导出会话。对于 Claude Code、Codex、Copilot、Cursor、Pi 和 Gemini 会话，你将获得原始的磁盘 JSONL 记录文件（逐字节原样）；对于 OpenCode（其会话存储在 SQLite 而非磁盘上），你将获得一个 JSON 文档，镜像底层的 `session` / `messages` / `parts` 表。 ### 审计 -一份对 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 logo 遮罩、渐变、字体度量——全部保留）。 -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 intent）、`share on linkedin`、`download poster`。捕获通过 `html-to-image` 实现，PNG 与屏幕渲染像素级一致（虚线边框、SVG logo 遮罩、渐变、字体度量——全部保留）。 +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` 运行时驱动——关于底层扫描引擎、支持的标志和每条记录的缓存不变性，请参阅 [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 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`）显示相应的提示文案。空白状态（无缓存或已过期）和零会话状态（缓存存在但扫描未找到记录）分别独立显示。 ### 策略 @@ -75,16 +75,16 @@ failproofai - - 从单个面板多选 failproofai 保护哪些 Agent CLI——Claude Code、OpenAI Codex、GitHub Copilot、Cursor Agent、OpenCode、Pi 和 Gemini CLI 均有一行显示安装状态（`Active` / `Detected` / `Inactive`）、用户范围的设置路径和品牌色调。勾选或取消勾选所需的 CLI，然后点击 `Apply changes` 一步完成安装/卸载差异。PATH 上检测到二进制文件的 CLI 会被预先勾选。 - - 单击即可开启或关闭单个策略（写入 `~/.failproofai/policies-config.json`——所有已安装 CLI 共享） + - 在单一面板中多选 failproofai 保护哪些 Agent CLI——Claude Code、OpenAI Codex、GitHub Copilot、Cursor Agent、OpenCode、Pi、Gemini CLI 和 Hermes 各有一行，显示安装状态（`Active` / `Detected` / `Inactive`）、用户范围设置路径，以及品牌色强调。勾选或取消勾选你想要的 CLI，点击 `Apply changes` 一步完成安装/卸载差异。已在 PATH 中检测到二进制文件的 CLI 会被预先勾选。 + - 一键开启或关闭单个策略（写入 `~/.failproofai/policies-config.json`——所有已安装的 CLI 共享） - 展开策略以配置其参数（适用于支持 `policyParams` 的策略） - 设置自定义策略文件路径 - - 所有会话中触发的每个 hook 事件的完整分页历史记录 - - 按决策、事件类型、CLI（Claude Code / OpenAI Codex / GitHub Copilot _(测试版)_ / Cursor Agent _(测试版)_ / OpenCode _(测试版)_ / Pi _(测试版)_ / Gemini CLI _(测试版)_）、策略名称或会话 ID 筛选 - - 每行显示：时间戳、策略名称、决策、CLI 标记（橙色 = Claude Code，紫色 = OpenAI Codex，蓝色 = GitHub Copilot，翠绿色 = Cursor Agent，琥珀色 = OpenCode，粉色 = Pi，天蓝色 = Gemini CLI）、工具名称、会话 ID 以及 deny/instruct 决策的原因 - - 点击会话 ID 可打开其记录——查看器会自动检测是哪个 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`、Gemini CLI `~/.gemini/tmp//chats/.jsonl`），并在标题中渲染匹配的 CLI 标记 + - 所有会话中触发的每个 Hook 事件的完整分页历史记录 + - 按决策、事件类型、CLI（Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Gemini CLI _(beta)_ / Hermes）、策略名称或会话 ID 筛选 + - 每行显示：时间戳、策略名称、决策、CLI 徽章（橙色 = Claude Code，紫色 = OpenAI Codex，蓝色 = GitHub Copilot，翠绿色 = Cursor Agent，琥珀色 = OpenCode，粉色 = Pi，天蓝色 = Gemini CLI，靛蓝色 = Hermes）、工具名称、会话 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`、Gemini CLI `~/.gemini/tmp//chats/.jsonl`、Hermes `~/.hermes/state.db`），并在页眉中渲染对应的 CLI 徽章 @@ -92,13 +92,13 @@ failproofai ## 自动刷新 -仪表板在顶部导航中提供自动刷新开关。启用后，当前页面会定期刷新，以实时显示新会话和策略活动。这对于监控长时间运行的自主 Agent 会话至关重要。 +控制台顶部导航栏有一个自动刷新开关。启用后，当前页面会定期刷新，以显示新出现的会话和策略活动。这对于监控长时间运行的自主 Agent 会话至关重要。 --- ## 禁用页面 -如果只需要仪表板的某些部分，可将 `FAILPROOFAI_DISABLE_PAGES` 设置为以逗号分隔的页面名称列表： +如果你只需要控制台的部分功能，可以将 `FAILPROOFAI_DISABLE_PAGES` 设置为逗号分隔的页面名称列表： ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -110,7 +110,7 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## 配置项目路径 -默认情况下，仪表板从标准 Claude Code 项目目录读取。对于自定义设置，可以覆盖此路径： +默认情况下，控制台从标准 Claude Code 项目目录读取。可以为自定义设置覆盖路径： ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -120,30 +120,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 diff --git a/docs/zh/examples.mdx b/docs/zh/examples.mdx index 37c114cf..e4d65fb3 100644 --- a/docs/zh/examples.mdx +++ b/docs/zh/examples.mdx @@ -4,13 +4,13 @@ description: "如何为 Claude Code 和 Agents SDK 配置 hooks" icon: book-open --- -开箱即用的常见场景示例，每个示例都说明了如何安装及预期效果。 +开箱即用的常见场景示例，每个示例均说明如何安装及预期效果。 --- ## 为 Claude Code 配置 hooks -Failproof AI 通过 [hooks 系统](https://docs.anthropic.com/en/docs/claude-code/hooks)与 Claude Code 集成。运行 `failproofai policies --install` 时，它会在 Claude Code 的 `settings.json` 中注册 hook 命令，这些命令会在每次工具调用时触发。 +Failproof AI 通过 [hooks 系统](https://docs.anthropic.com/en/docs/claude-code/hooks)与 Claude Code 集成。运行 `failproofai policies --install` 后，它会在 Claude Code 的 `settings.json` 中注册 hook 命令，并在每次工具调用时触发。 @@ -23,19 +23,19 @@ Failproof AI 通过 [hooks 系统](https://docs.anthropic.com/en/docs/claude-cod failproofai policies --install ``` - + ```bash cat ~/.claude/settings.json | grep failproofai ``` - 你应该能看到 `PreToolUse`、`PostToolUse`、`Notification` 和 `Stop` 事件的 hook 条目。 + 你应该能看到 `PreToolUse`、`PostToolUse`、`Notification` 和 `Stop` 事件对应的 hook 条目。 ```bash claude ``` - 策略现在会在每次工具调用时自动运行。尝试让 Claude 执行 `sudo rm -rf /`——该命令将被拦截。 + 策略现在会在每次工具调用时自动执行。尝试让 Claude 运行 `sudo rm -rf /`，该命令将被拦截。 @@ -43,7 +43,7 @@ Failproof AI 通过 [hooks 系统](https://docs.anthropic.com/en/docs/claude-cod ## 为 Agents SDK 配置 hooks -如果你正在使用 [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) 进行开发，可以以编程方式使用相同的 hook 系统。 +如果你正在使用 [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk) 进行开发，可以通过编程方式使用相同的 hook 系统。 @@ -52,11 +52,11 @@ Failproof AI 通过 [hooks 系统](https://docs.anthropic.com/en/docs/claude-cod ``` - 创建 agent 进程时传入 hook 命令。hooks 的触发方式与 Claude Code 中相同——通过 stdin/stdout JSON 传递： + 在创建 agent 进程时传入 hook 命令。hooks 的触发方式与 Claude Code 中相同——通过 stdin/stdout JSON 传递： ```bash - failproofai --hook PreToolUse # 在每个工具调用前触发 - failproofai --hook PostToolUse # 在每个工具调用后触发 + failproofai --hook PreToolUse # called before each tool + failproofai --hook PostToolUse # called after each tool ``` @@ -88,35 +88,35 @@ Failproof AI 通过 [hooks 系统](https://docs.anthropic.com/en/docs/claude-cod ## 拦截破坏性命令 -最常见的配置——防止 agent 造成不可逆的破坏。 +最常见的配置——防止 agent 执行不可逆的破坏性操作。 ```bash failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh ``` 各策略说明： -- `block-sudo` - 拦截所有 `sudo` 命令 -- `block-rm-rf` - 拦截递归删除文件操作 -- `block-force-push` - 拦截 `git push --force` -- `block-curl-pipe-sh` - 拦截将远程脚本通过管道传入 shell 的操作 +- `block-sudo` — 拦截所有 `sudo` 命令 +- `block-rm-rf` — 拦截递归文件删除 +- `block-force-push` — 拦截 `git push --force` +- `block-curl-pipe-sh` — 拦截将远程脚本通过管道传递给 shell 的操作 --- ## 防止密钥泄露 -阻止 agent 在工具输出中查看或泄露凭据。 +阻止 agent 在工具输出中看到或泄露凭据。 ```bash failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens ``` -这些策略在 `PostToolUse` 时触发——工具运行后，在 agent 看到输出之前对其进行脱敏处理。 +这些策略在 `PostToolUse` 阶段触发——工具执行完成后，在 agent 看到输出之前对其进行脱敏处理。 --- -## 通过 Slack 接收 agent 待处理提醒 +## 在 agent 需要关注时发送 Slack 提醒 -使用通知 hook 将空闲提醒转发到 Slack。 +使用 notification hook 将空闲告警转发至 Slack。 ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -142,7 +142,7 @@ customPolicies.add({ signal: AbortSignal.timeout(5000), }); } catch { - // 如果 Slack 不可达，绝不阻塞 agent + // never block the agent if Slack is unreachable } return allow(); @@ -158,9 +158,9 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c --- -## 将 agent 限定在指定分支 +## 将 agent 限制在指定分支 -防止 agent 切换分支或推送到受保护的分支。 +防止 agent 切换分支或向受保护分支推送代码。 ```javascript import { customPolicies, allow, deny } from "failproofai"; @@ -184,7 +184,7 @@ customPolicies.add({ ## 提交前要求运行测试 -提醒 agent 在提交前先运行测试。 +提醒 agent 在提交代码前先运行测试。 ```javascript import { customPolicies, allow, instruct } from "failproofai"; @@ -206,9 +206,9 @@ customPolicies.add({ --- -## 锁定生产环境仓库 +## 锁定生产仓库 -在项目中提交一份项目级配置，让团队所有成员自动获得相同的策略。 +在项目中提交一份团队级配置，使所有开发者自动应用相同的策略。 在仓库中创建 `.failproofai/policies-config.json`： @@ -242,9 +242,9 @@ git commit -m "Add failproofai team policies" --- -## 通过约定策略构建团队级质量标准 +## 通过约定策略构建组织级质量标准 -效果最显著的配置：将针对项目定制的策略提交到仓库的 `.failproofai/policies/` 目录。每位团队成员都会自动获取——无需执行安装命令，无需修改配置。 +最具价值的配置方式：将 `.failproofai/policies/` 提交到仓库，其中包含针对项目定制的策略。所有团队成员将自动获取这些策略，无需执行任何安装命令，也无需修改配置。 @@ -256,8 +256,8 @@ git commit -m "Add failproofai team policies" // .failproofai/policies/team-policies.mjs import { customPolicies, allow, deny, instruct } from "failproofai"; - // 强制使用团队首选的包管理器 - // （也可以启用内置的 prefer-package-manager 策略） + // Enforce your team's preferred package manager + // (or enable the built-in prefer-package-manager policy instead) customPolicies.add({ name: "enforce-bun", match: { events: ["PreToolUse"] }, @@ -269,7 +269,7 @@ git commit -m "Add failproofai team policies" }, }); - // 提醒 agent 在提交前运行测试 + // Remind the agent to run tests before committing customPolicies.add({ name: "test-before-commit", match: { events: ["PreToolUse"] }, @@ -289,8 +289,8 @@ git commit -m "Add failproofai team policies" git commit -m "Add team quality policies" ``` - - 每当团队遇到新的问题模式时，添加相应策略并推送。每位成员在下次 `git pull` 时即可获得更新。这些策略将成为随团队成长而不断演进的活质量标准。 + + 每当团队遇到新的问题模式时，添加相应策略并推送。每位成员在下次 `git pull` 后即可获取更新。这些策略将成为随团队成长而不断演进的质量标准。 @@ -298,10 +298,10 @@ git commit -m "Add failproofai team policies" ## 更多示例 -仓库中的 [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) 目录包含： +仓库中的 [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) 目录包含以下内容： | 文件 | 内容说明 | -|------|---------| -| `policies-basic.js` | 入门策略——拦截生产环境写入、强制推送、管道脚本 | -| `policies-notification.js` | 空闲通知和会话结束时的 Slack 提醒 | -| `policies-advanced/index.js` | 传递式导入、异步 hooks、PostToolUse 输出脱敏、Stop 事件处理 | \ No newline at end of file +|------|----------| +| `policies-basic.js` | 入门策略——拦截生产环境写入、force push 及管道脚本 | +| `policies-notification.js` | 针对空闲通知和会话结束的 Slack 告警 | +| `policies-advanced/index.js` | 传递导入、异步 hooks、PostToolUse 输出脱敏及 Stop 事件处理 | \ No newline at end of file diff --git a/docs/zh/for-agents.mdx b/docs/zh/for-agents.mdx index a4f2c23f..e322b5d3 100644 --- a/docs/zh/for-agents.mdx +++ b/docs/zh/for-agents.mdx @@ -1,36 +1,36 @@ --- -title: "适用于 AI 助手" -description: "一条命令即可将 Failproof AI 知识添加到你的编程 AI 助手中。支持 Claude Code、Cursor、Windsurf 等。" +title: "适用于 Agent" +description: "一条命令即可将 Failproof AI 知识添加到你的编程 Agent 中。支持 Claude Code、Cursor、Windsurf 等。" --- -一条命令即可将完整的 Failproof AI 参考文档添加到你的编程 AI 助手中。支持 Claude Code、Cursor、Windsurf 以及任何其他支持技能（skills）的 AI 助手。 +一条命令即可将完整的 Failproof AI 参考文档添加到你的编程 Agent 中。支持 Claude Code、Cursor、Windsurf 以及任何支持 skills 的 Agent。 ```bash npx skills add https://docs.befailproof.ai ``` -`npx skills` 会自动检测你已安装的 AI 助手，并以适合各自的格式添加该技能。 +`npx skills` 会自动检测你已安装的 Agent，并以适合各 Agent 的格式添加该 skill。 -## 技能涵盖的内容 +## Skill 涵盖的内容 | 领域 | 包含内容 | |------|----------------| -| 策略 | 内置策略名称、事件类型、参数、启用/禁用 | -| 自定义策略 | `customPolicies.add()`、匹配过滤器、`allow`/`deny`/`instruct` API | -| 上下文对象 | `ctx.eventType`、`ctx.toolName`、`ctx.toolInput`、`ctx.session` | -| 配置 | `policies-config.json` 结构、作用域合并、`policyParams` | +| Policies | 内置策略名称、事件类型、参数、启用/禁用 | +| Custom policies | `customPolicies.add()`、匹配过滤器、`allow`/`deny`/`instruct` API | +| Context object | `ctx.eventType`、`ctx.toolName`、`ctx.toolInput`、`ctx.session` | +| Configuration | `policies-config.json` 结构、作用域合并、`policyParams` | | CLI | `failproofai policies --install`、`--uninstall`、`--custom`、作用域 | -| 控制台 | 会话查看器、策略活动、环境变量 | -| 架构 | Hook 处理程序流程、退出码、stdin/stdout 协议 | +| Dashboard | 会话查看器、策略活动、环境变量 | +| Architecture | Hook 处理流程、退出码、stdin/stdout 协议 | -## 技能内容完整吗？ +## Skill 是否完整？ -Mintlify 会从导航中的所有页面生成 `llms.txt`。Failproof AI 文档覆盖了完整的 API——每条策略、每个选项和每个示例都包含在内。如果你发现有遗漏，原始内容请访问 `https://docs.befailproof.ai/llms-full.txt`。 +Mintlify 会从导航中的所有页面生成 `llms.txt`。Failproof AI 文档覆盖了完整的 API——每个策略、选项和示例都包含在内。如果你发现有遗漏，源文件位于 `https://docs.befailproof.ai/llms-full.txt`。 -如需针对性的上下文，可直接链接到特定页面： +如需定向获取特定内容，可直接链接到具体页面： ```bash -# 仅获取自定义策略 API +# 仅获取 custom policies API npx skills add https://docs.befailproof.ai/custom-policies # 仅获取内置策略 diff --git a/docs/zh/getting-started.mdx b/docs/zh/getting-started.mdx index 5954aa1d..92ed9c45 100644 --- a/docs/zh/getting-started.mdx +++ b/docs/zh/getting-started.mdx @@ -1,13 +1,13 @@ --- title: 快速开始 -description: "安装 failproofai，启用策略，让你的智能体稳定运行" +description: "安装 failproofai，启用策略，让你的 Agent 稳定可靠地运行" icon: rocket --- -## 系统要求 +## 环境要求 - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0（可选，仅在从源码构建时需要） +- **Bun** >= 1.3.0（可选 - 仅在从源码构建时需要） --- @@ -31,15 +31,15 @@ bun add -g failproofai - 策略是在每次智能体工具调用前后执行的规则。它们能在破坏性命令、密钥泄露及其他故障发生之前将其拦截。 + 策略是在每次 Agent 工具调用前后执行的规则。它们能在破坏性命令、密钥泄露及其他故障模式造成损害之前将其拦截。 ```bash failproofai policies --install ``` - 该命令会将 hook 条目写入已安装的智能体 CLI 中（Claude Code 的 `~/.claude/settings.json`、OpenAI Codex 的 `~/.codex/hooks.json`、GitHub Copilot CLI 的 `~/.copilot/hooks/failproofai.json`、Cursor Agent 的 `~/.cursor/hooks.json`、OpenCode 在 `~/.config/opencode/plugins/failproofai.mjs` 生成的插件 shim 以及 `~/.config/opencode/opencode.json` 的 `plugin` 数组中的注册条目、Pi 的 `~/.pi/agent/settings.json`，或 Gemini CLI 的 `~/.gemini/settings.json`）。如果检测到多个已安装的 CLI，系统会提示你选择；也可以通过 `--cli claude codex copilot cursor opencode pi gemini`（任意子集）跳过提示。 + 此命令会将 hook 条目写入已安装的 Agent CLI 配置文件中（Claude Code 的 `~/.claude/settings.json`、OpenAI Codex 的 `~/.codex/hooks.json`、GitHub Copilot CLI 的 `~/.copilot/hooks/failproofai.json`、Cursor Agent 的 `~/.cursor/hooks.json`、OpenCode 在 `~/.config/opencode/plugins/failproofai.mjs` 生成的插件 shim 及 `~/.config/opencode/opencode.json` 的 `plugin` 数组注册项、Pi 的 `~/.pi/agent/settings.json`、Gemini CLI 的 `~/.gemini/settings.json`，或 Hermes 的 `~/.hermes/config.yaml`）。若检测到多个 CLI，系统会提示你选择；也可以通过 `--cli claude codex copilot cursor opencode pi gemini hermes`（任意子集）跳过提示。 - GitHub Copilot CLI、Cursor Agent、OpenCode、Pi 和 Gemini CLI 的支持目前处于 **测试阶段** — 分别使用 `--cli copilot`、`--cli cursor`、`--cli opencode`、`--cli pi` 或 `--cli gemini` 进行安装。 + GitHub Copilot CLI、Cursor Agent、OpenCode、Pi 和 Gemini CLI 的支持目前处于 **beta** 阶段 — 请分别使用 `--cli copilot`、`--cli cursor`、`--cli opencode`、`--cli pi` 或 `--cli gemini` 进行安装。Hermes（hermes-agent，一个 Slack/Telegram 网关）使用 `--cli hermes` 安装用户级作用域，同时也是一个**离线**审计数据源。 ```bash failproofai policies --install --scope project @@ -49,6 +49,7 @@ bun add -g failproofai failproofai policies --install --cli opencode --scope project failproofai policies --install --cli pi --scope project failproofai policies --install --cli gemini --scope project + failproofai policies --install --cli hermes --scope user failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` @@ -57,17 +58,17 @@ bun add -g failproofai failproofai policies ``` - 显示所有策略、是否已启用，以及已配置的参数。 + 显示所有策略、各策略的启用状态及已配置的参数。 ```bash failproofai ``` - 在 `http://localhost:8020` 打开本地控制台，你可以在此浏览会话记录、查看工具调用详情并管理策略。 + 在 `http://localhost:8020` 打开本地控制台，你可以在此浏览会话记录、检查工具调用详情并管理策略。 - - 像往常一样启动 Claude Code。如果智能体尝试执行危险操作，failproofai 会自动拦截。你可以让它在无人值守的情况下运行，事后在控制台中查看发生了什么。 + + 像往常一样启动 Claude Code。如果 Agent 尝试执行危险操作，failproofai 会自动拦截。可以让它在无人值守的情况下运行，之后在控制台中查看执行情况。 @@ -75,7 +76,7 @@ bun add -g failproofai ## 策略的工作原理 -每次智能体执行工具时，Claude Code 会将 failproofai 作为子进程调用： +每当 Agent 执行一个工具时，Claude Code 会将 failproofai 作为子进程调用： ```text Claude Code → failproofai --hook PreToolUse → reads stdin JSON @@ -85,19 +86,19 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON 每条策略会返回以下三种决策之一： -- **allow** — 智能体正常继续执行 -- **deny** — 操作被阻止，智能体会收到阻止原因说明 -- **instruct** — 在智能体的提示中追加额外上下文 +- **allow** - Agent 正常继续执行 +- **deny** - 操作被拦截，Agent 会收到拦截原因说明 +- **instruct** - 向 Agent 的提示词中添加额外的上下文信息 -策略在本地进程中运行，不会向远程服务发送任何数据。 +策略在你的本地进程中运行，不会向任何远程服务发送数据。 --- -## 使用约定式策略建立团队规范 +## 通过约定式策略建立团队规范 -在团队中快速建立质量标准的最便捷方式是使用 `.failproofai/policies/` 约定目录。只需将策略文件放入该目录，它们就会自动加载——无需任何标志、配置变更或安装命令。 +在团队中快速统一质量标准的最佳方式是使用 `.failproofai/policies/` 约定。只需将策略文件放入该目录，它们便会自动加载 — 无需任何额外参数、配置修改或安装命令。 @@ -106,13 +107,13 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON ``` - 复制示例文件或自行编写： + 复制内置的示例文件，或自己编写： ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ ``` - 或者创建一个新文件： + 或者创建一个新的策略文件： ```js // .failproofai/policies/team-policies.mjs @@ -131,33 +132,33 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - 所有已安装 failproofai 的团队成员都会自动获取这些策略，无需额外的个人配置。 + 所有已安装 failproofai 的团队成员都会自动获取这些策略，无需每人单独配置。 -将 `.failproofai/policies/` 提交到代码仓库，让整个团队共享相同的标准。随着团队发现新的故障模式，只需添加策略并推送——所有人在下次 `git pull` 时即可获得更新。随着时间推移，这些策略将成为持续演进的质量标准。 +将 `.failproofai/policies/` 提交到代码仓库，让整个团队共享同一套标准。随着团队不断发现新的故障模式，持续添加策略并推送 — 所有人在下次 `git pull` 时便能自动获取更新。随着时间推移，这些策略将成为一套持续演进的活跃质量标准。 --- ## 数据存储 -所有配置和日志均保存在本地机器上： +所有配置和日志均保存在本地： | 路径 | 存储内容 | |------|----------------| | `~/.failproofai/policies-config.json` | 全局策略配置 | -| `~/.failproofai/hook-activity.jsonl` | Hook 执行历史 | -| `~/.failproofai/hook.log` | 自定义 hook 错误的调试日志 | -| `.failproofai/policies-config.json` | 项目级配置（可提交到仓库） | -| `.failproofai/policies-config.local.json` | 个人覆盖配置（已加入 gitignore） | +| `~/.failproofai/hook-activity.jsonl` | Hook 执行历史记录 | +| `~/.failproofai/hook.log` | 自定义 hook 错误调试日志 | +| `.failproofai/policies-config.json` | 项目级配置（可提交至版本库） | +| `.failproofai/policies-config.local.json` | 个人本地覆盖配置（已加入 .gitignore） | --- @@ -171,7 +172,7 @@ failproofai policies --uninstall --- -## 后续步骤 +## 下一步 @@ -184,10 +185,10 @@ failproofai policies --uninstall - 使用 JavaScript 编写自己的策略 + 使用 JavaScript 编写你自己的策略 - + 监控会话并查看策略活动记录 diff --git a/docs/zh/introduction.mdx b/docs/zh/introduction.mdx index 86413b53..b741ec58 100644 --- a/docs/zh/introduction.mdx +++ b/docs/zh/introduction.mdx @@ -5,32 +5,32 @@ description: "FailproofAI 为 AI 智能体提供 39 条内置故障策略，一 [![npm weekly downloads](https://img.shields.io/npm/dw/failproofai?style=flat-square&color=2ea44f)](https://www.npmjs.com/package/failproofai) -用于 **AI 故障处理**、**错误恢复**和 **LLM 可靠性**的 Hooks 与策略。让你的 AI 智能体在 **Claude Code**、**OpenAI Codex**、**GitHub Copilot**、**Cursor Agent**、**OpenCode**、**Pi**、**Gemini CLI** 以及 **Agents SDK** 上稳定运行、自主执行任务。 +专为 **AI 故障处理**、**错误恢复**和 **LLM 可靠性**设计的 Hooks 与策略系统。让你的 AI 智能体在 **Claude Code**、**OpenAI Codex**、**GitHub Copilot**、**Cursor Agent**、**OpenCode**、**Pi**、**Gemini CLI**、**Hermes** 以及 **Agents SDK** 上稳定运行、持续自主工作。 -AI 智能体的失败方式往往是可预测的：执行破坏性命令、泄露密钥、偏离任务、陷入循环，或直接推送到主分支。如果不加干预，小故障会逐步演变成服务中断、凭证泄露和数据丢失。 +AI 智能体的失败往往有迹可循：执行破坏性命令、泄露密钥、偏离任务、陷入死循环，或直接推送到主分支。一旦无人看管，小故障就会滚雪球般演变成服务中断、凭据泄露和数据丢失。 -FailproofAI 通过**策略**来解决这些问题。这些规则会介入智能体的每一次工具调用，**检测故障**、**进行缓解**（阻止、指令纠正、信息脱敏），并在需要关注时**及时提醒你**。本地仪表板让你可以事后回溯每一次工具调用、智能体故障和恢复操作。 +FailproofAI 通过**策略**来解决这些问题。这些规则挂载到每一次智能体工具调用中，负责**检测故障**、**采取应对措施**（阻止、指示、脱敏）并在需要人工介入时**及时告警**。本地仪表板让你事后可以回顾每一次工具调用、智能体故障及恢复操作的完整记录。 -所有数据均不离开你的本机。 +所有数据均不离开你的本地机器。 -## 快速上手 +## 快速开始 - 开箱即用：阻止破坏性命令、防止密钥泄露、将智能体限制在项目边界内，以及更多功能。 + 开箱即用：拦截破坏性命令、防止密钥泄露、将智能体限制在项目边界内，以及更多功能。 - 使用 JavaScript 编写自己的规则，支持简洁的 allow / deny / instruct API。 + 使用 JavaScript 编写你自己的规则，配合简洁的 allow / deny / instruct API 轻松实现。 - 查看智能体在你离开期间做了什么。浏览会话记录、检查工具调用、回顾策略触发情况。 + 查看智能体在你离开期间的所有操作。浏览会话记录、检查工具调用、回顾策略触发详情。 - - 无需编写代码即可调整任何策略。按项目或全局设置白名单、受保护分支或触发阈值。 + + 无需编写代码即可调整任意策略。可按项目或全局设置允许列表、受保护分支或触发阈值。 @@ -54,4 +54,4 @@ failproofai policies --install # enable policies (or skip — `failproofai` wi failproofai # launch the dashboard ``` -完整操作流程请参阅[快速入门](/zh/getting-started)指南。 \ No newline at end of file +完整操作流程请参阅[入门指南](/zh/getting-started)。 \ No newline at end of file diff --git a/docs/zh/package-aliases.mdx b/docs/zh/package-aliases.mdx index 83ed4413..d47a7552 100644 --- a/docs/zh/package-aliases.mdx +++ b/docs/zh/package-aliases.mdx @@ -1,6 +1,6 @@ --- title: 包别名 -description: "已注册的防错字抢注别名及其工作原理" +description: "已注册的防域名抢注别名及其工作原理" icon: copy --- @@ -16,17 +16,17 @@ bun add -g failproofai --- -## 为什么我们持有这些别名 +## 为何我们持有这些别名 -错字抢注（Typosquatting）是一种常见的供应链攻击手段——恶意攻击者注册一个与热门包名仅差一个按键的包名，毫无防备的用户在安装时输错命令，最终以完整系统权限运行了攻击者控制的代码。这正是 Failproof AI 旨在防御的威胁类型。 +域名抢注（typosquatting）是一种常见的供应链攻击手段——恶意者注册一个与热门包名相差仅一个按键的包名。不知情的用户在拼错安装命令时，就会以完整的系统权限运行攻击者控制的代码，而这正是 Failproof AI 旨在防御的威胁类型。 -为了消除这一攻击面，**我们在 npm 上抢先注册了 `failproofai` 所有常见的拼写错误和格式变体**。任何第三方都无法注册这些名称。每个别名都是一个轻量代理，安装后会委托给真正的 `failproofai` 包。 +为消除这一攻击面，**我们在 npm 上抢先注册了 `failproofai` 所有常见的拼写错误及格式变体**。这些名称均无法被第三方注册。每个别名都是一个轻量级代理包，安装时会委托给真正的 `failproofai` 包。 --- ## 已注册的别名 -**格式变体** — "failproof ai" 的不同书写方式： +**格式变体** - "failproof ai" 的不同书写方式： | 包名 | 状态 | |---------|--------| @@ -37,7 +37,7 @@ bun add -g failproofai | `fail_proof_ai` | ⏳ 等待 npm 支持 | | `fail-proofai` | ⏳ 等待 npm 支持 | -**`failprof*` 错字** — "proof" 中少了一个 `o`： +**`failprof*` 拼写错误** - "proof" 中少了一个 `o`： | 包名 | 状态 | |---------|--------| @@ -47,7 +47,7 @@ bun add -g failproofai | `fail-prof-ai` | ⏳ 等待 npm 支持 | | `failprof_ai` | ⏳ 等待 npm 支持 | -**`faliproof*` 错字** — `a` 和 `i` 互换： +**`faliproof*` 拼写错误** - `a` 和 `i` 位置互换： | 包名 | 状态 | |---------|--------| @@ -55,9 +55,9 @@ bun add -g failproofai | `faliproof-ai` | ✅ 已发布 | | `faliproofai` | ⏳ 等待 npm 支持 | -> **为什么是"等待支持"？** npm 的垃圾包防护策略会拦截那些在去除标点符号并进行相似度检查后，与已有包名规范化结果相同的包名。我们已联系 npm 支持团队，申请以防抢注为由保留这些名称，待审批通过后即可激活。 +> **为何处于等待状态？** npm 的防垃圾包策略会屏蔽在去除标点符号并进行相似性检查后，与已有包名规范化结果相同的新包名。我们已联系 npm 支持团队，申请以防抢注为目的保留这些名称，待审核通过后即可启用。 -您可以通过以下命令验证任意已发布的别名均归我们所有： +您可以验证任意已发布别名均由我们持有： ```bash npm info failproof @@ -70,13 +70,13 @@ npm info failproof 每个别名包： -1. 将 `failproofai` 列为依赖项——因此安装时会运行真正的包（包括其 `postinstall` 钩子设置） -2. 暴露一个与自身同名的二进制文件（例如 `failprof-ai`），将所有参数代理转发给 `failproofai` 二进制文件 +1. 将 `failproofai` 列为依赖项——安装时会运行真正的包（包括其 `postinstall` 钩子设置） +2. 暴露一个与自身同名的可执行文件（例如 `failprof-ai`），将所有参数代理转发给 `failproofai` 二进制文件 -代理是一个两行的 Node 脚本，没有任何逻辑处理、网络请求，也不会收集 `failproofai` 本身之外的任何数据。 +该代理仅为两行 Node 脚本，不含任何逻辑、网络请求，也不会收集 `failproofai` 本身以外的任何数据。 --- -## 如果您发现我们遗漏了某个名称 +## 如果您发现我们遗漏的包名 -请在 [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) 提交 Issue，我们会及时注册该名称。 \ No newline at end of file +请在 [failproofai/failproofai](https://github.com/failproofai/failproofai/issues) 提交 issue，我们将及时注册。 \ No newline at end of file diff --git a/docs/zh/testing.mdx b/docs/zh/testing.mdx index 3792eb42..041797ce 100644 --- a/docs/zh/testing.mdx +++ b/docs/zh/testing.mdx @@ -1,10 +1,10 @@ --- title: 测试 -description: "单元测试、E2E 测试与测试辅助工具" +description: "单元测试、端到端测试及测试辅助工具" icon: flask-vial --- -failproofai 包含两套测试套件：**单元测试**（快速、使用 mock）和**端到端测试**（真实子进程调用）。 +failproofai 包含两套测试套件：**单元测试**（快速、模拟）和**端到端测试**（真实子进程调用）。 --- @@ -14,13 +14,13 @@ failproofai 包含两套测试套件：**单元测试**（快速、使用 mock # 单次运行所有单元测试 bun run test:run -# 以监听模式运行单元测试 +# 以监视模式运行单元测试 bun run test -# 运行 E2E 测试（需要提前配置——见下文） +# 运行 E2E 测试（需要配置环境，详见下文） bun run test:e2e -# 仅进行类型检查，不编译 +# 类型检查（不构建） bunx tsc --noEmit # 代码检查 @@ -31,19 +31,19 @@ bun run lint ## 单元测试 -单元测试位于 `__tests__/` 目录下，使用 [Vitest](https://vitest.dev) 并配合 `jsdom` 运行。 +单元测试位于 `__tests__/` 目录，使用 [Vitest](https://vitest.dev) 和 `jsdom`。 ```text __tests__/ hooks/ - builtin-policies.test.ts # 各内置策略的逻辑测试 + builtin-policies.test.ts # 每个内置策略的逻辑测试 hooks-config.test.ts # 配置加载与作用域合并 - policy-evaluator.test.ts # 参数注入与求值顺序 - custom-hooks-registry.test.ts # globalThis 注册表的 add/get/clear 操作 - custom-hooks-loader.test.ts # ESM 加载器、传递依赖导入及错误处理 - manager.test.ts # install/remove/list 操作 + policy-evaluator.test.ts # 参数注入与评估顺序 + custom-hooks-registry.test.ts # globalThis 注册表的增删查 + custom-hooks-loader.test.ts # ESM 加载器、传递导入、错误处理 + manager.test.ts # 安装/移除/列举操作 components/ - sessions-list.test.tsx # Session 列表组件 + sessions-list.test.tsx # 会话列表组件 project-list.test.tsx # 项目列表组件 ... lib/ @@ -110,11 +110,11 @@ describe("block-sudo", () => { ## 端到端测试 -E2E 测试将真实的 `failproofai` 二进制文件作为子进程调用，将 JSON 载荷通过 stdin 传入，并对 stdout 输出和退出码进行断言。这覆盖了 Claude Code 使用的完整集成路径。 +E2E 测试将真实的 `failproofai` 二进制文件作为子进程调用，向 stdin 传入 JSON 载荷，并对 stdout 输出和退出码进行断言。这覆盖了 Claude Code 所使用的完整集成路径。 -### 配置 +### 环境配置 -E2E 测试直接从仓库源码运行二进制文件。在首次运行前，需要构建自定义 hook 文件在导入 `'failproofai'` 时所使用的 CJS 包： +E2E 测试直接从仓库源码运行二进制文件。在首次运行前，请构建自定义 hook 文件在导入 `'failproofai'` 时所依赖的 CJS 包： ```bash bun build src/index.ts --outdir dist --target node --format cjs @@ -126,33 +126,33 @@ bun build src/index.ts --outdir dist --target node --format cjs bun run test:e2e ``` -每当修改公共 hook API（`src/hooks/custom-hooks-registry.ts`、`src/hooks/policy-helpers.ts` 或 `src/hooks/policy-types.ts`）时，需要重新构建 `dist/`。 +每当你修改公共 hook API（`src/hooks/custom-hooks-registry.ts`、`src/hooks/policy-helpers.ts` 或 `src/hooks/policy-types.ts`）后，请重新构建 `dist/`。 ### E2E 测试结构 ```text __tests__/e2e/ helpers/ - hook-runner.ts # 启动二进制进程，传入载荷 JSON，捕获退出码、stdout 和 stderr + hook-runner.ts # 启动二进制进程、传入载荷 JSON、捕获退出码 + stdout + stderr fixture-env.ts # 每个测试独立的临时目录与配置文件 - payloads.ts # 针对各事件类型的 Claude 标准载荷工厂函数 + payloads.ts # 符合 Claude 格式的各事件类型载荷工厂函数 hooks/ - builtin-policies.e2e.test.ts # 使用真实子进程测试每个内置策略 - custom-hooks.e2e.test.ts # 自定义 hook 的加载与求值 - config-scopes.e2e.test.ts # 跨项目/本地/全局作用域的配置合并 - policy-params.e2e.test.ts # 各参数化策略的参数注入 + builtin-policies.e2e.test.ts # 每个内置策略的真实子进程测试 + custom-hooks.e2e.test.ts # 自定义 hook 的加载与评估 + config-scopes.e2e.test.ts # 跨项目/本地/全局的配置合并 + policy-params.e2e.test.ts # 参数化策略的参数注入 ``` ### 使用 E2E 辅助工具 -**`FixtureEnv`** —— 每个测试的隔离环境： +**`FixtureEnv`** — 每个测试独立的隔离环境： ```typescript import { createFixtureEnv } from "../helpers/fixture-env"; const env = createFixtureEnv(); -// env.cwd - 临时目录；作为 payload.cwd 传入以读取 .failproofai/policies-config.json -// env.home - 隔离的 home 目录；不会泄漏真实的 ~/.failproofai 配置 +// env.cwd - 临时目录；作为 payload.cwd 传入以加载 .failproofai/policies-config.json +// env.home - 隔离的主目录；不会泄露真实的 ~/.failproofai env.writeConfig({ enabledPolicies: ["block-sudo"], @@ -164,7 +164,7 @@ env.writeConfig({ `createFixtureEnv()` 会自动注册 `afterEach` 清理逻辑。 -**`runHook`** —— 调用二进制文件： +**`runHook`** — 调用二进制文件： ```typescript import { runHook } from "../helpers/hook-runner"; @@ -180,7 +180,7 @@ expect(result.exitCode).toBe(0); expect(result.parsed?.hookSpecificOutput?.permissionDecision).toBe("deny"); ``` -**`Payloads`** —— 预置载荷工厂函数： +**`Payloads`** — 内置载荷工厂函数： ```typescript Payloads.preToolUse.bash(command, cwd) @@ -231,30 +231,30 @@ describe("block-rm-rf (E2E)", () => { }); ``` -### E2E 响应结构 +### E2E 响应格式 | 决策 | 退出码 | stdout | |----------|-----------|--------| -| `PreToolUse` deny | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | -| `PostToolUse` deny | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | -| Instruct（非 Stop） | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | -| Stop instruct | `2` | stdout 为空；原因输出至 stderr | -| Allow | `0` | 空字符串 | +| `PreToolUse` 拒绝 | `0` | `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"..."}}` | +| `PostToolUse` 拒绝 | `0` | `{"hookSpecificOutput":{"additionalContext":"Blocked ... because: ..."}}` | +| 指令（非 Stop） | `0` | `{"hookSpecificOutput":{"additionalContext":"Instruction from failproofai: ..."}}` | +| Stop 指令 | `2` | stdout 为空；原因输出至 stderr | +| 允许 | `0` | 空字符串 | ### Vitest 配置 E2E 测试使用 `vitest.config.e2e.mts`，配置如下： -- `environment: "node"` —— 不需要浏览器全局变量 -- `pool: "forks"` —— 真正的进程隔离（测试会启动子进程） -- `testTimeout: 20_000` —— 每个测试超时 20 秒（含二进制启动 + hook 求值时间） +- `environment: "node"` — 无需浏览器全局变量 +- `pool: "forks"` — 真正的进程隔离（测试会启动子进程） +- `testTimeout: 20_000` — 每个测试超时 20 秒（包含二进制启动 + hook 评估） -使用 `forks` 池非常重要：基于线程的 worker 会共享 `globalThis`，可能干扰启动子进程的测试。基于进程的 forks 可避免此问题。 +`forks` 池至关重要：基于线程的 worker 共享 `globalThis`，可能干扰需要启动子进程的测试，而基于进程的 forks 可以避免这一问题。 --- -## CI +## 持续集成 -在合并代码前，必须通过完整的 CI 流程（`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`）。E2E 测试套件作为独立的 CI 任务并行运行。 +合并前必须通过完整的 CI 流程（`bun run lint && bunx tsc --noEmit && bun run test:run && bun run build`）。E2E 套件作为独立的 CI 任务并行运行。 -完整的合并前检查清单请参阅 [Contributing](../CONTRIBUTING.md)。 \ No newline at end of file +完整的合并前检查清单请参见 [Contributing](../CONTRIBUTING.md)。 \ No newline at end of file From 18ca38c7024b000317020d93e51e57033a0912f8 Mon Sep 17 00:00:00 2001 From: NiveditJain Date: Sat, 11 Jul 2026 00:30:57 -0700 Subject: [PATCH 2/2] fix(docs): resolve translation regressions from #486 docs sync MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes the failing `docs` CI job (MDX parse) and the Hermes review on #487: - ja/built-in-policies.mdx: strip 11 hallucinated `{#id}` heading-ID suffixes that @mdx-js/mdx (the Mintlify deploy parser) rejects with "Could not parse expression with acorn". English + all 13 sibling languages use plain headings; this restores parity and fixes CI. - tr/cli/hook.mdx: restore the YAML frontmatter (title + description) dropped in re-translation — every other language kept it. - he/configuration.mdx: restore the dropped `--cli claude|codex|copilot|cursor|opencode|pi|gemini|hermes` inline code span (the #486 change should have extended the list, not removed it). - de/cli/auth.mdx: un-translate the inline-code placeholder ` ()` back to ` ()` per the never-translate-inline-code rule. Verified: `bun run validate:mdx` now passes 300/300 pages. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_013k21Co2w2vLyKPhevz8HtM --- CHANGELOG.md | 5 +++++ docs/de/cli/auth.mdx | 2 +- docs/he/configuration.mdx | 2 +- docs/ja/built-in-policies.mdx | 22 +++++++++++----------- docs/tr/cli/hook.mdx | 5 +++++ 5 files changed, 23 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c7d0524b..32422230 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## 0.0.13-beta.2 — 2026-07-11 + +### Docs +- Fix translation regressions from the #486 docs sync: strip hallucinated `{#…}` heading-ID syntax that broke MDX parsing (`ja/built-in-policies`), restore dropped YAML frontmatter (`tr/cli/hook`) and the `--cli …|hermes` inline code span (`he/configuration`), and un-translate an inline-code placeholder (`de/cli/auth`). (#487) + ## 0.0.13-beta.1 — 2026-07-10 ### Features diff --git a/docs/de/cli/auth.mdx b/docs/de/cli/auth.mdx index a438538b..c0e2d2ea 100644 --- a/docs/de/cli/auth.mdx +++ b/docs/de/cli/auth.mdx @@ -37,7 +37,7 @@ Widerruft die aktuelle Sitzung auf dem Server und löscht `~/.failproofai/auth.j failproofai auth whoami ``` -Gibt ` ()` aus und beendet sich mit Code 0, wenn eine gültige Sitzung vorhanden ist, oder gibt `not signed in` aus und beendet sich mit Code 1. Erneuert das Zugriffstoken im Hintergrund automatisch, wenn es weniger als eine Minute bis zum Ablauf hat. +Gibt ` ()` aus und beendet sich mit Code 0, wenn eine gültige Sitzung vorhanden ist, oder gibt `not signed in` aus und beendet sich mit Code 1. Erneuert das Zugriffstoken im Hintergrund automatisch, wenn es weniger als eine Minute bis zum Ablauf hat. ## Wiederkehrende Audit-Erinnerung diff --git a/docs/he/configuration.mdx b/docs/he/configuration.mdx index 594357c2..24e3cda4 100644 --- a/docs/he/configuration.mdx +++ b/docs/he/configuration.mdx @@ -202,7 +202,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← יורד לכלל ה - **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) -עבור מטרה לחלק agent מסוים העבור space-separated או חוזר על כל תת-קבוצה: +עבור `--cli claude|codex|copilot|cursor|opencode|pi|gemini|hermes` למטרה סוכן ספציפי (space-separated או חוזר לכל תת-קבוצה): ```bash failproofai policies --install --cli codex --scope project diff --git a/docs/ja/built-in-policies.mdx b/docs/ja/built-in-policies.mdx index 6467ffa8..f36abfd2 100644 --- a/docs/ja/built-in-policies.mdx +++ b/docs/ja/built-in-policies.mdx @@ -55,7 +55,7 @@ failproofai には、エージェントの一般的な障害モードを検出 --- -## 危険なコマンド {#dangerous-commands} +## 危険なコマンド 取り消しが困難な操作や、ホストシステムに損害を与える可能性のある操作をエージェントが実行するのを防ぎます。 @@ -135,7 +135,7 @@ failproofai には、エージェントの一般的な障害モードを検出 --- -## インフラコマンド {#infra-commands} +## インフラコマンド コーディングエージェントがインフラ CLI を実行したり、CI/CD パイプラインをトリガーしたりするのを停止します。このカテゴリのすべてのポリシーは**オプトイン**（`defaultEnabled: false`）です。正当に `kubectl` や `terraform` などを呼び出す必要があるエージェントは、ポリシーを有効にしない限り影響を受けません。有効にすると、コマンドが `allowPatterns` のエントリにマッチしない限り、マッチした CLI のすべての呼び出しが拒否されます。 @@ -327,7 +327,7 @@ failproofai には、エージェントの一般的な障害モードを検出 --- -## シークレット（サニタイザー） {#secrets-sanitizers} +## シークレット（サニタイザー） エージェントが認証情報をコンテキストや出力に漏洩させるのを防ぎます。サニタイザーポリシーは **PostToolUse** イベントで発火します。Claude が Bash コマンドを実行したり、ファイルを読み込んだり、ツールを呼び出したりすると、これらのポリシーは出力が Claude に返される前に検査します。シークレットパターンが検出された場合、ポリシーは出力が返されるのを防ぐ deny 決定を返します。 @@ -395,7 +395,7 @@ failproofai には、エージェントの一般的な障害モードを検出 --- -## 環境 {#environment} +## 環境 エージェントによる機密環境設定の読み取りや露出を防ぎます。 @@ -419,7 +419,7 @@ failproofai には、エージェントの一般的な障害モードを検出 --- -## ファイルアクセス {#file-access} +## ファイルアクセス エージェントをプロジェクトの境界内に留め、機密ファイルへのアクセスを防ぎます。 @@ -473,7 +473,7 @@ failproofai には、エージェントの一般的な障害モードを検出 --- -## Git {#git} +## Git 取り消しが困難な誤ったプッシュ、強制プッシュ、ブランチミスを防ぎます。 @@ -565,7 +565,7 @@ failproofai には、エージェントの一般的な障害モードを検出 --- -## データベース {#database} +## データベース データベースに対して実行される前に破壊的な SQL 操作を検出します。 @@ -587,7 +587,7 @@ failproofai には、エージェントの一般的な障害モードを検出 --- -## 警告 {#warnings} +## 警告 潜在的にリスクはあるが破壊的ではない操作の前に、エージェントに追加のコンテキストを提供します。 @@ -647,7 +647,7 @@ failproofai には、エージェントの一般的な障害モードを検出 --- -## パッケージマネージャー {#package-managers} +## パッケージマネージャー エージェントが使用できるパッケージマネージャーを強制します。 @@ -683,7 +683,7 @@ failproofai には、エージェントの一般的な障害モードを検出 --- -## AI の動作 {#ai-behavior} +## AI の動作 エージェントが行き詰まったり予期しない動作をしていないかを検出します。 @@ -696,7 +696,7 @@ failproofai には、エージェントの一般的な障害モードを検出 --- -## ワークフロー {#workflow} +## ワークフロー セッション終了時に規律あるワークフローを強制します。これらのポリシーは **Stop** イベントで発火し、各条件が満たされるまでエージェントの停止を拒否します。コミット → プッシュ → PR → CI という自然な依存チェーンに従います。ポリシーが拒否した場合、チェーン内のそれ以降のポリシーはスキップされます（deny はショートサーキット）。 diff --git a/docs/tr/cli/hook.mdx b/docs/tr/cli/hook.mdx index 7e31789c..b69121c5 100644 --- a/docs/tr/cli/hook.mdx +++ b/docs/tr/cli/hook.mdx @@ -1,3 +1,8 @@ +--- +title: Hook işleyicisi (iç) +description: "Claude Code'un her araç etkinliğinde çağırdığı alt işlem" +--- + ```bash failproofai --hook ```