From 0e4089576ae19c003a15f14baf90725c04018b87 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 8 May 2026 07:37:29 +0000 Subject: [PATCH] docs: update translations for changed English sources --- docs/ar/architecture.mdx | 115 +++++------ docs/ar/built-in-policies.mdx | 268 ++++++++++++------------ docs/ar/configuration.mdx | 133 ++++++------ docs/ar/dashboard.mdx | 79 ++++--- docs/ar/getting-started.mdx | 73 +++---- docs/de/architecture.mdx | 134 ++++++------ docs/de/built-in-policies.mdx | 137 ++++++------ docs/de/configuration.mdx | 96 +++++---- docs/de/dashboard.mdx | 66 +++--- docs/de/getting-started.mdx | 54 ++--- docs/es/architecture.mdx | 148 ++++++------- docs/es/built-in-policies.mdx | 251 +++++++++++----------- docs/es/configuration.mdx | 78 +++---- docs/es/dashboard.mdx | 54 ++--- docs/es/getting-started.mdx | 38 ++-- docs/fr/architecture.mdx | 74 +++---- docs/fr/built-in-policies.mdx | 176 ++++++++-------- docs/fr/configuration.mdx | 76 ++++--- docs/fr/dashboard.mdx | 66 +++--- docs/fr/getting-started.mdx | 44 ++-- docs/he/architecture.mdx | 136 ++++++------ docs/he/built-in-policies.mdx | 316 ++++++++++++++-------------- docs/he/configuration.mdx | 145 ++++++------- docs/he/dashboard.mdx | 97 +++++---- docs/he/getting-started.mdx | 71 ++++--- docs/hi/architecture.mdx | 119 ++++++----- docs/hi/built-in-policies.mdx | 344 +++++++++++++++---------------- docs/hi/configuration.mdx | 122 ++++++----- docs/hi/dashboard.mdx | 72 +++---- docs/hi/getting-started.mdx | 64 +++--- docs/i18n/README.ar.md | 169 ++++++++------- docs/i18n/README.de.md | 121 ++++++----- docs/i18n/README.es.md | 119 ++++++----- docs/i18n/README.fr.md | 111 ++++++---- docs/i18n/README.he.md | 186 ++++++++++------- docs/i18n/README.hi.md | 179 +++++++++------- docs/i18n/README.it.md | 185 ++++++++++------- docs/i18n/README.pt-br.md | 103 +++++---- docs/i18n/README.ru.md | 175 +++++++++------- docs/i18n/README.tr.md | 192 +++++++++-------- docs/i18n/README.vi.md | 161 +++++++++------ docs/it/architecture.mdx | 105 +++++----- docs/it/built-in-policies.mdx | 248 +++++++++++----------- docs/it/configuration.mdx | 109 +++++----- docs/it/dashboard.mdx | 54 ++--- docs/it/getting-started.mdx | 86 ++++---- docs/pt-br/architecture.mdx | 94 ++++----- docs/pt-br/built-in-policies.mdx | 154 +++++++------- docs/pt-br/configuration.mdx | 76 ++++--- docs/pt-br/dashboard.mdx | 42 ++-- docs/pt-br/getting-started.mdx | 38 ++-- docs/ru/architecture.mdx | 224 ++++++++++---------- docs/ru/built-in-policies.mdx | 247 +++++++++++----------- docs/ru/configuration.mdx | 132 ++++++------ docs/ru/dashboard.mdx | 90 ++++---- docs/ru/getting-started.mdx | 76 +++---- docs/tr/architecture.mdx | 224 ++++++++++---------- docs/tr/built-in-policies.mdx | 270 ++++++++++++------------ docs/tr/configuration.mdx | 109 +++++----- docs/tr/dashboard.mdx | 66 +++--- docs/tr/getting-started.mdx | 94 +++++---- docs/vi/architecture.mdx | 101 +++++---- docs/vi/built-in-policies.mdx | 186 ++++++++--------- docs/vi/configuration.mdx | 119 ++++++----- docs/vi/dashboard.mdx | 62 +++--- docs/vi/getting-started.mdx | 67 +++--- 66 files changed, 4408 insertions(+), 4012 deletions(-) diff --git a/docs/ar/architecture.mdx b/docs/ar/architecture.mdx index caa9330a..f185e5f5 100644 --- a/docs/ar/architecture.mdx +++ b/docs/ar/architecture.mdx @@ -1,23 +1,22 @@ --- - --- -title: المعمارية -description: "كيفية عمل معالج الخطاف وتحميل الإعدادات وتقييم السياسات داخلياً" +title: العمارة +description: "كيفية عمل معالج الخطاف وتحميل الإعدادات وتقييم السياسات داخليًا" icon: sitemap --- -توضح هذه الوثيقة كيفية عمل failproofai داخلياً: كيف يعترض نظام الخطاف استدعاءات أداة الوكيل، وكيف يتم تحميل ودمج الإعدادات، وكيف يتم تقييم السياسات، وكيف تراقب لوحة التحكم نشاط الوكيل. +تشرح هذه الوثيقة كيفية عمل failproofai داخليًا: كيف يعترض نظام الخطاف استدعاءات أدوات الوكيل، وكيفية تحميل ودمج الإعدادات، وكيفية تقييم السياسات، وكيفية مراقبة لوحة التحكم لنشاط الوكيل. --- ## نظرة عامة -يتكون failproofai من نظامين فرعيين مستقلين: +يحتوي failproofai على نظامين فرعيين مستقلين: -1. **معالج الخطاف** - عملية CLI سريعة يستدعيها Claude Code على كل استدعاء أداة وكيل. يقيّم السياسات ويرجع قراراً. +1. **معالج الخطاف** - عملية سطر أوامر سريعة يستدعيها Claude Code في كل استدعاء أداة وكيل. يقيم السياسات ويعيد قرارًا. 2. **مراقب الوكيل (لوحة التحكم)** - تطبيق ويب Next.js لمراقبة جلسات الوكيل وإدارة السياسات. -يشترك كلا النظامين الفرعيين في ملفات الإعدادات في `~/.failproofai/` ومجلد المشروع `.failproofai/`، لكنهما يعملان كعمليات منفصلة ويتواصلان فقط عبر نظام الملفات. +يشترك كلا النظامين في ملفات الإعدادات في `~/.failproofai/` وفي مجلد المشروع `.failproofai/`، لكنهما يعملان كعمليات منفصلة ولا يتواصلان إلا من خلال نظام الملفات. --- @@ -25,7 +24,7 @@ icon: sitemap ### التكامل مع Claude Code -عند تشغيل `failproofai policies --install`، فإنه يكتب إدخالات مثل هذه في `~/.claude/settings.json`: +عند تشغيل `failproofai policies --install`، يكتب إدخالات مثل هذه في `~/.claude/settings.json`: ```json { @@ -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` مع مخرجات الأداة. -يفرض المعالج حد أقصى بحجم 1 ميجابايت لـ stdin. يتم تجاهل الحمولات التي تتجاوز هذا الحد وجميع السياسات تسمح بشكل ضمني. +يفرض المعالج حد أقصى للملفات المدخلة بحجم 1 ميجابايت. يتم التخلص من الحمولات التي تتجاوز هذا الحد وتسمح جميع السياسات ضمنيًا. ### صيغة الاستجابة @@ -87,7 +86,7 @@ icon: sitemap } ``` -**التعليمات (أي حدث باستثناء Stop):** +**التعليمات (أي حدث ما عدا Stop):** ```json { "hookSpecificOutput": { @@ -96,7 +95,7 @@ icon: sitemap } ``` -**حدث التعليمات Stop:** +**تعليمات حدث التوقف:** - رمز الخروج: `2` - السبب مكتوب على stderr (وليس stdout) @@ -104,9 +103,9 @@ icon: sitemap - رمز الخروج: `0` - stdout فارغ -**السماح مع رسالة:** +**السماح برسالة:** -`allow(message)` تسمح لسياسة ما بإرسال سياق معلوماتي مرة أخرى إلى Claude حتى عندما تكون العملية مسموحة. يكتب معالج الخطاف JSON التالي إلى **stdout** (وليس ملف إعدادات — هذه استجابة المعالج لـ Claude Code، تماماً مثل استجابات الرفض والتعليمات أعلاه): +يسمح `allow(message)` لسياسة بإرسال سياق معلومات للخلف إلى Claude حتى عندما تكون العملية مسموحة. يكتب معالج الخطاف JSON التالي إلى **stdout** (وليس ملف إعدادات — هذه استجابة المعالج لـ Claude Code، تمامًا مثل ردود الرفض والتعليمات أعلاه): ```json // Written to stdout by the hook handler process @@ -117,10 +116,10 @@ icon: sitemap } ``` - رمز الخروج: `0` (العملية مسموحة) -- عندما تعيد عدة سياسات `allow` مع رسالة، يتم دمج رسائلها بفواصل أسطر في سلسلة واحدة `additionalContext` -- إذا لم تقدم أي سياسة رسالة، فإن stdout فارغ (كما كان من قبل) +- عندما تعيد عدة سياسات `allow` برسالة، يتم دمج رسائلها بفواصل أسطر في سلسلة `additionalContext` واحدة +- إذا لم تقدم أي سياسة رسالة، يكون stdout فارغًا (نفسه كما هو الحال) -### خط معالجة الأنابيب +### خط أنابيب المعالجة يطبق `src/hooks/handler.ts` خط الأنابيب الكامل: @@ -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,12 +155,12 @@ stdin JSON ``` منطق الدمج: -- `enabledPolicies` - اتحاد مخصص عبر جميع الملفات الثلاثة -- `policyParams` - لكل سياسة، الملف الأول الذي يحددها يفوز تماماً -- `customPoliciesPath` - الملف الأول الذي يحددها يفوز -- `llm` - الملف الأول الذي يحددها يفوز +- `enabledPolicies` - اتحاد غير مكرر عبر جميع الملفات الثلاثة +- `policyParams` - مفتاح لكل سياسة، الملف الأول الذي يعرّفه يفوز بالكامل +- `customPoliciesPath` - الملف الأول الذي يعرّفه يفوز +- `llm` - الملف الأول الذي يعرّفه يفوز -تستخدم لوحة تحكم الويب `readHooksConfig()` (عام فقط) للقراءة والكتابة، لأنها لا تُستدعى مع cwd مشروع. +تستخدم لوحة التحكم على الويب `readHooksConfig()` (بشكل عام فقط) للقراءة والكتابة، لأنها لا تُستدعى مع cwd المشروع. --- @@ -171,24 +170,24 @@ stdin JSON لكل سياسة: -1. ابحث عن مخطط `params` الخاص بالسياسة (إن كان لديها واحدة). +1. ابحث عن مخطط `params` للسياسة (إن كان لديها واحدة). 2. اقرأ `policyParams[policy.name]` من الإعدادات المدمجة. -3. دمج القيم المعطاة من قبل المستخدم على القيم الافتراضية للمخطط لإنتاج `ctx.params`. -4. استدع `policy.fn(ctx)` مع السياق المحل. -5. إذا كانت النتيجة `deny`، توقف فوراً وأرجع هذا القرار. -6. إذا كانت النتيجة `instruct`، اجمع الرسالة وتابع. -7. إذا كانت النتيجة `allow`، انتقل إلى السياسة التالية. +3. دمج القيم المقدمة من المستخدم فوق قيم المخطط الافتراضية لإنتاج `ctx.params`. +4. استدعِ `policy.fn(ctx)` مع السياق المحل. +5. إذا كانت النتيجة `deny`، توقف على الفور وأعد هذا القرار. +6. إذا كانت النتيجة `instruct`، تراكم الرسالة والمتابعة. +7. إذا كانت النتيجة `allow`، المتابعة إلى السياسة التالية. بعد تشغيل جميع السياسات: - إذا تم إرجاع أي `deny`، أصدر استجابة الرفض. -- إذا تم جمع أي إرجاعات `instruct`، أصدر استجابة تعليمات واحدة مع جميع الرسائل المدمجة. -- وإلا، أصدر استجابة السماح (stdout فارغ، خروج 0). +- إذا تم جمع أي عودات `instruct`، أصدر استجابة تعليمات واحدة مع دمج جميع الرسائل. +- وإلا، أصدر استجابة سماح (stdout فارغ، خروج 0). --- ## السياسات المدمجة -يحدد `src/hooks/builtin-policies.ts` جميع السياسات المدمجة الـ 26 ك `BuiltinPolicyDefinition` كائنات: +يعرّف `src/hooks/builtin-policies.ts` جميع السياسات المدمجة الـ 26 كأجسام `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__"; @@ -227,25 +226,25 @@ export function getCustomHooks(): CustomHook[] { ... } 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` مؤقتة و `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` ويرجع المحمل مصفوفة فارغة. السياسات المدمجة لم تتأثر. +في أي خطأ (ملف غير موجود، خطأ بناء جملة، فشل الاستيراد)، يتم تسجيل الخطأ في `~/.failproofai/hook.log` ويعيد المحمل مصفوفة فارغة. السياسات المدمجة غير متأثرة. -يتم تقييم السياسات المخصصة بعد جميع السياسات المدمجة. الرفض من سياسة مخصصة لا يزال يختصر السياسات المخصصة الأخرى (لكن جميع السياسات المدمجة قد تم تشغيلها بالفعل في تلك النقطة). +يتم تقييم السياسات المخصصة بعد جميع السياسات المدمجة. رفض السياسة المخصصة لا يزال يختصر السياسات المخصصة الإضافية (لكن جميع المدمجات قد تم تشغيلها بالفعل في تلك النقطة). --- ## تسجيل النشاط -بعد كل حدث خطاف، يلحق المعالج سطر JSONL بـ `~/.failproofai/hook-activity.jsonl`: +بعد كل حدث خطاف، يضيف المعالج سطر JSONL إلى `~/.failproofai/hook-activity.jsonl`: ```json { @@ -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/ @@ -283,25 +282,25 @@ app/ get-hook-activity.ts ← Paginate/search activity log install-hooks-web.ts ← Install/remove hooks from the browser api/ - download/[project]/[session]/route.ts ← Export session as ZIP/JSONL + download/[project]/[session]/route.ts ← Per-CLI session export (JSONL or JSON) ``` **تدفق البيانات:** -- مكونات الصفحة تستدعي `lib/projects.ts` و `lib/log-entries.ts` لقراءة بيانات المشروع/الجلسة مباشرة من نظام الملفات (لا توجد طبقة API للقراءات). -- تستخدم صفحة السياسات Server Actions لجميع التغييرات (تبديل، تحديث المعاملات، التثبيت/الإزالة). -- يحلل عارض الجلسة صيغة نسخ Claude JSONL وينقل جدول زمني للرسائل واستدعاءات الأداة. +- تستدعي مكونات الصفحة `lib/projects.ts` و`lib/log-entries.ts` لقراءة بيانات المشروع/الجلسة مباشرة من نظام الملفات (لا توجد طبقة API للقراءة). +- تستخدم صفحة السياسات Server Actions لجميع الطفرات (تبديل، تحديث params، تثبيت/إزالة). +- يحلل عارض الجلسة صيغة نسخ JSONL من Claude ويعرض خط زمني للرسائل واستدعاءات الأدوات. **قرارات التصميم الرئيسية:** -- لا توجد قاعدة بيانات - جميع الحالة الدائمة موجودة في ملفات عادية (`~/.failproofai/`, `~/.claude/projects/`). -- Server Actions للتغييرات - لا توجد حاجة لـ REST API لعمليات CRUD. +- لا توجد قاعدة بيانات - جميع الحالات الدائمة في ملفات عادية (`~/.failproofai/`، `~/.claude/projects/`). +- Server Actions للطفرات - لا توجد حاجة لـ REST API لعمليات CRUD. - React Server Components لصفحات القراءة - تحميل أولي أسرع، لا حزمة عميل لجلب البيانات. -- مكونات العميل فقط حيث تكون التفاعل مطلوباً (تبديل السياسة، بحث النشاط، عارض السجل). +- مكونات العميل فقط حيث تكون التفاعلية مطلوبة (تبديلات السياسة، بحث النشاط، عارض السجل). --- -## تخطيط الملف +## تخطيط الملفات ```text failproofai/ diff --git a/docs/ar/built-in-policies.mdx b/docs/ar/built-in-policies.mdx index f06e1b01..19322ddb 100644 --- a/docs/ar/built-in-policies.mdx +++ b/docs/ar/built-in-policies.mdx @@ -1,11 +1,11 @@ --- --- title: السياسات المدمجة -description: "جميع 39 سياسة مدمجة تقبض على أنماط فشل العامل الشائعة" +description: "جميع 39 سياسة مدمجة تمنع حالات فشل الوكيل الشائعة" icon: shield --- -يأتي failproofai مع 39 سياسة مدمجة تقبض على أنماط فشل العامل الشائعة. تعمل كل سياسة على حدث خطاف معين واسم أداة معينة. تقبل تسع عشرة سياسة معاملات تتيح لك ضبط سلوكها دون كتابة أكواد. تفرض خمس سياسات سير عمل خط أنابيب commit → push → PR → CI قبل توقف Claude. +يأتي failproofai مع 39 سياسة مدمجة تمنع حالات فشل الوكيل الشائعة. تعمل كل سياسة على نوع حدث hook محدد واسم أداة محددة. تقبل تسع عشرة سياسة معاملات تتيح لك ضبط سلوكها دون كتابة أكواد. خمس سياسات سير عمل تفرض خط أنابيب commit → push → PR → CI قبل توقف Claude. --- @@ -13,32 +13,30 @@ 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 | +| [أوامر البنية الأساسية](#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 | | [قاعدة البيانات](#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 | +| [تحذيرات](#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-`** — مسح البيانات الحساسة من مخرجات الأداة قبل أن يراها الوكيل. ### مساحات الأسماء -تعيش كل سياسة في فتحة `/`. تنتمي السياسات المدمجة إلى -مساحة الأسماء **`exospherehost/`** — على سبيل المثال، `exospherehost/sanitize-jwt`. تمنع -مساحة الأسماء التصادمات عند تحميل السياسات المخصصة أو من طرف ثالث -بأسماء قصيرة مماثلة. +تقع كل سياسة في فتحة `/`. تنتمي السياسات المدمجة إلى مساحة الأسماء +**`exospherehost/`** — على سبيل المثال، `exospherehost/sanitize-jwt`. تمنع مساحة الأسماء +التصادمات عند تحميل سياسات مخصصة أو من جهات خارجية بأسماء قصيرة متشابهة. -في تكوينك يمكنك الإشارة إلى سياسة مدمجة باسمها القصير أو -اسمها المؤهل؛ كلا الشكلين يحلان نفس السياسة: +في إعدادك، يمكنك الإشارة إلى سياسة مدمجة بواسطة اسمها القصير أو اسمها المؤهل؛ كلا النموذجين يؤديان إلى نفس السياسة: ```json { @@ -49,29 +47,29 @@ icon: shield } ``` -إذا لم يكن لاسم `/`، يتعامل failproofai معه كمنتمٍ إلى مساحة الأسماء الافتراضية -`exospherehost`. الأسماء التي تحتوي بالفعل على `/` (مثل `myorg/foo`، +إذا كان الاسم لا يحتوي على `/`، يتعامل failproofai معه على أنه ينتمي إلى مساحة الأسماء الافتراضية +`exospherehost`. الأسماء التي تحتوي بالفعل على `/` (مثل `myorg/foo`, `custom/my-hook`) يتم الاحتفاظ بها كما هي. -- **`require-`** — حظر حدث الإيقاف حتى يتم استيفاء الشروط. +- **`require-`** — حجب حدث التوقف حتى تتحقق الشروط. --- -تدعم كل سياسة حقل `hint` اختياري في `policyParams`. يتم إلحاق التلميح برسالة الحظر أو التعليمات التي يراها Claude، مما يوفر توجيهات قابلة للتنفيذ دون تعديل أكواد السياسة. يعمل مع السياسات المدمجة والمخصصة والاتفاقية. انظر [التكوين → hint](/ar/configuration#hint-cross-cutting) للتفاصيل. +تدعم كل سياسة حقل `hint` اختياري في `policyParams`. يتم إضافة التلميح إلى رسالة الرفض أو الإرشادات التي يراها Claude، مما يوفر توجيهات قابلة للتنفيذ دون تعديل كود السياسة. يعمل مع السياسات المدمجة والمخصصة وسياسات الاتفاقية. انظر [الإعدادات → hint](/ar/configuration#hint-cross-cutting) للحصول على التفاصيل. --- ## الأوامر الخطرة -منع العوامل من تشغيل العمليات التي يصعب الرجوع عنها أو التي قد تضر نظام المضيف. +منع الوكلاء من تشغيل العمليات التي يصعب التراجع عنها أو التي قد تلحق الضرر بنظام المضيف. ### `block-sudo` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر أي أمر `sudo`. +**الإعداد الافتراضي:** يرفض أي أمر `sudo`. -يحظر الاستدعاءات التي تتضمن كلمة المفتاح `sudo`. يتم مطابقة النمط على رموز الأمر المحللة، وليس السلسلة الخام، لمنع تجاوز عن طريق حقن عامل shell. +يحجب الاستدعاءات التي تتضمن كلمة `sudo`. يتم مطابقة النمط على رموز الأمر المحللة، وليس السلسلة الخام، لمنع التجاوز عبر حقن عامل shell. **المعاملات:** @@ -91,10 +89,10 @@ icon: shield } ``` -مع هذا التكوين، يُسمح `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 *`). --- @@ -102,13 +100,13 @@ icon: shield ### `block-rm-rf` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر `rm -rf`، `rm -fr`، وأشكال الحذف التكراري المماثلة. +**الإعداد الافتراضي:** يرفض `rm -rf` و`rm -fr` وأشكال الحذف العودي المماثلة. **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | المسارات الآمنة للحذف التكراري (مثل `/tmp`). | +| `allowPaths` | `string[]` | `[]` | المسارات الآمنة للحذف العودي (مثل `/tmp`). | **مثال:** @@ -127,31 +125,31 @@ icon: shield ### `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`). -لا توجد معاملات. +بدون معاملات. --- -## أوامر البنية التحتية +## أوامر البنية الأساسية -منع عوامل الترميز من تشغيل واجهات سطر الأوامر للبنية التحتية أو تشغيل خطوط أنابيب CI/CD. جميع السياسات في هذه الفئة **اختيارية** (`defaultEnabled: false`) — لن يتم تعطيل العوامل التي تحتاج بشكل شرعي إلى استدعاء `kubectl`، `terraform`، إلخ ما لم تقم بتفعيل السياسة. عند التفعيل، يتم حظر كل استدعاء للواجهة المطابقة ما لم يطابق الأمر إدخالاً في `allowPatterns`. +إيقاف وكلاء البرمجة عن تشغيل واجهات سطر أوامر البنية الأساسية أو تشغيل خطوط أنابيب CI/CD. جميع السياسات في هذه الفئة **اختيارية** (`defaultEnabled: false`) — الوكلاء الذين يحتاجون بشكل حقيقي لاستدعاء `kubectl` أو `terraform` وما إلى ذلك لن يتعرضوا للانقطاع ما لم تفعل السياسة. عند التفعيل، يتم رفض كل استدعاء لواجهة سطر الأوامر المطابقة ما لم يطابق الأمر إدخالاً في `allowPatterns`. -نحو النمط هو نفسه [`block-sudo`](#block-sudo): يتم مطابقة الرموز مقابل argv المحلل، `*` هو بطاقة برية لرمز واحد، وأي أمر يحتوي على عامل shell منفصل (`&&`، `||`، `|`، `;`) أو رمز يحتوي على أحرف metacharacters shell مدمجة يُرفض قبل مطابقة القائمة البيضاء لمنع تجاوزات الحقن. +نحو النمط هو نفسه [`block-sudo`](#block-sudo): يتم مطابقة الرموز مقابل argv المحللة، و`*` هو بطاقة البدل لرمز واحد، وأي أمر يحتوي على عامل shell مستقل (`&&`, `||`, `|`, `;`) أو رمز يحتوي على أحرف shell ميتاتا مضمنة يتم رفضه قبل مطابقة قائمة البيض لمنع التجاوزات عبر الحقن. ### `block-kubectl` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر أي استدعاء `kubectl`. +**الإعداد الافتراضي:** يرفض أي استدعاء `kubectl`. **المعاملات:** @@ -171,14 +169,14 @@ icon: shield } ``` -مع هذا التكوين، يُسمح `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). **المعاملات:** @@ -203,7 +201,7 @@ icon: shield ### `block-aws-cli` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر أي استدعاء `aws` CLI. +**الإعداد الافتراضي:** يرفض أي استدعاء واجهة سطر أوامر `aws`. **المعاملات:** @@ -228,7 +226,7 @@ icon: shield ### `block-gcloud` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر أي استدعاء `gcloud` (Google Cloud) CLI. +**الإعداد الافتراضي:** يرفض أي استدعاء واجهة سطر أوامر `gcloud` (Google Cloud). **المعاملات:** @@ -253,7 +251,7 @@ icon: shield ### `block-az-cli` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر أي استدعاء `az` (Azure) CLI. +**الإعداد الافتراضي:** يرفض أي استدعاء واجهة سطر أوامر `az` (Azure). **المعاملات:** @@ -278,7 +276,7 @@ icon: shield ### `block-helm` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر أي استدعاء `helm`. +**الإعداد الافتراضي:** يرفض أي استدعاء `helm`. **المعاملات:** @@ -303,7 +301,7 @@ icon: shield ### `block-gh-pipeline` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر أوامر فرعية `gh` CLI التالية التي تغير الحالة أو تشغل خطوط الأنابيب: +**الإعداد الافتراضي:** يرفض أوامر فرعية `gh` CLI التالية التي تغير الحالة أو تشغل خطوط أنابيب: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -312,13 +310,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). **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | استدعاءات مكتوبة محددة للسماح بها حتى لو كانت ستُنكر بخلاف ذلك. | +| `allowPatterns` | `string[]` | `[]` | استدعاءات نصية محددة يجب السماح بها حتى لو تم رفضها. | **مثال:** @@ -334,29 +332,29 @@ icon: shield --- -## الأسرار (المنظفات) +## الأسرار (معقمات) -منع العوامل من تسرب بيانات الاعتماد إلى سياقهم أو مخرجاتهم. تعمل سياسات المُنظف على أحداث **PostToolUse**. عندما يقوم Claude بتشغيل أمر Bash، أو قراءة ملف، أو استدعاء أي أداة، تفحص هذه السياسات المخرجات قبل إرجاعها إلى Claude. إذا تم اكتشاف نمط سري، ترجع السياسة قرار حظر يمنع إرجاع المخرجات. +منع الوكلاء من تسرب بيانات الاعتماد إلى سياقهم أو مخرجاتهم. تعمل سياسات المعقم على أحداث **PostToolUse**. عندما يقوم Claude بتشغيل أمر Bash أو قراءة ملف أو استدعاء أي أداة، تفحص هذه السياسات المخرجات قبل إرجاعها إلى Claude. إذا تم اكتشاف نمط سري، تعيد السياسة قرار الرفض الذي يمنع تمرير المخرجات للخلف. ### `sanitize-jwt` **الحدث:** PostToolUse (جميع الأدوات) -**الافتراضي:** يحجب رموز JWT (ثلاث قطاعات base64url مفصولة بـ `.`). +**الإعداد الافتراضي:** يخفي رموز JWT (ثلاث مقاطع base64url مفصولة بـ `.`). -لا توجد معاملات. +بدون معاملات. --- ### `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 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 إضافية يجب التعامل معها كأسرار. | **مثال:** @@ -378,68 +376,68 @@ icon: shield ### `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 (جميع الأدوات) -**الافتراضي:** يحجب رؤوس `Authorization: Bearer ` حيث يكون الرمز 20 حرفاً أو أكثر. +**الإعداد الافتراضي:** يخفي رؤوس `Authorization: Bearer ` حيث يكون الرمز 20 حرفاً أو أكثر. -لا توجد معاملات. +بدون معاملات. --- ## البيئة -حماية تكوين البيئة الحساس من القراءة أو الكشف من قبل العوامل. +حماية إعدادات البيئة الحساسة من قراءتها أو الكشف عنها من قبل الوكلاء. ### `block-env-files` -**الحدث:** PreToolUse (Bash، Read) -**الافتراضي:** ينكر قراءة ملفات `.env` عبر `cat .env`، استدعاءات أداة Read مع `.env` كمسار الملف، إلخ. +**الحدث:** PreToolUse (Bash, Read) +**الإعداد الافتراضي:** يرفض قراءة ملفات `.env` عبر `cat .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` إلى دليل فرعي. +**الحدث:** PreToolUse (Read, Bash) +**الإعداد الافتراضي:** يرفض قراءة الملفات خارج جذر المشروع. الحد هو `CLAUDE_PROJECT_DIR` (مجموعة مرة واحدة في كل جلسة بواسطة Claude Code)، مع الرجوع إلى دليل العمل الحالي للجلسة عند عدم تعيين هذا المتغير. يعني استخدام جذر المشروع بدلاً من `cwd` المباشر أن الحد يبقى مستقراً حتى بعد قيام Claude بـ `cd` في مجلد فرعي. **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | بادئات المسارات المطلقة المسموح بها حتى لو كانت خارج جذر المشروع. | +| `allowPaths` | `string[]` | `[]` | بادئات المسار المطلق المسموح بها حتى لو كانت خارج جذر المشروع. | **مثال:** @@ -457,14 +455,14 @@ icon: shield ### `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) يجب حجبها. | **مثال:** @@ -482,12 +480,12 @@ icon: shield ## Git -منع الدفع العرضي والدفع القسري وأخطاء الفرع التي يصعب الرجوع عنها. +منع الدفعات العرضية والدفعات القسرية وأخطاء الفروع التي يصعب التراجع عنها. ### `block-push-master` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر `git push origin main` و `git push origin master`. +**الإعداد الافتراضي:** يرفض `git push origin main` و`git push origin master`. **المعاملات:** @@ -508,7 +506,7 @@ icon: shield ``` -للسماح بالدفع إلى جميع الفروع (تعطيل هذه السياسة بشكل فعال دون إزالتها من `enabledPolicies`)، اضبط `protectedBranches: []`. +للسماح بالدفع إلى جميع الفروع (بشكل فعال تعطيل هذه السياسة دون إزالتها من `enabledPolicies`)، اضبط `protectedBranches: []`. --- @@ -516,28 +514,28 @@ icon: shield ### `block-work-on-main` **الحدث:** PreToolUse (Bash) -**الافتراضي:** ينكر الخروج من فروع `main` أو `master` مباشرة. +**الإعداد الافتراضي:** يرفض `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"]` | أسماء الفروع التي لا يمكن الخروج منها مباشرة. | +| `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`](/ar/configuration#hint-cross-cutting) الشامل لاقتراح بدائل: +بدون معاملات خاصة بالسياسة. استخدم [`hint`](/ar/configuration#hint-cross-cutting) عابر الحدود لاقتراح بدائل: ```json { "policyParams": { "block-force-push": { - "hint": "إنشاء فرع جديد من HEAD الحالي (مثل `git checkout -b `) ودفعه بدلاً من ذلك." + "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b `) and push that instead." } } } @@ -548,66 +546,66 @@ icon: shield ### `warn-git-amend` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يعلم Claude بالمتابعة بحذر عند تشغيل `git commit --amend`. لا يحظر الأمر. +**الإعداد الافتراضي:** يرشد Claude للمتابعة بحذر عند تشغيل `git commit --amend`. لا يحجب الأمر. -لا توجد معاملات. +بدون معاملات. --- ### `warn-git-stash-drop` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يعلم Claude بالتأكيد قبل تشغيل `git stash drop`. لا يحظر الأمر. +**الإعداد الافتراضي:** يرشد Claude للتأكيد قبل تشغيل `git stash drop`. لا يحجب الأمر. -لا توجد معاملات. +بدون معاملات. --- ### `warn-all-files-staged` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يعلم Claude بمراجعة ما يقوم بمرحلته عند تشغيل `git add -A` أو `git add .`. لا يحظر الأمر. +**الإعداد الافتراضي:** يرشد Claude لمراجعة ما يقوم بتجهيزه عند تشغيل `git add -A` أو `git add .`. لا يحجب الأمر. -لا توجد معاملات. +بدون معاملات. --- ## قاعدة البيانات -اقبض على عمليات SQL المدمرة قبل تنفيذها ضد قاعدة البيانات الخاصة بك. +اكتشف العمليات SQL المدمرة قبل أن تُنفذ ضد قاعدة البيانات الخاصة بك. ### `warn-destructive-sql` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يعلم Claude بالتأكيد قبل تشغيل SQL يحتوي على `DROP TABLE`, `DROP DATABASE`, أو `DELETE` بدون جملة `WHERE`. +**الإعداد الافتراضي:** يرشد Claude للتأكيد قبل تشغيل SQL يحتوي على `DROP TABLE` أو `DROP DATABASE` أو `DELETE` بدون بند `WHERE`. -لا توجد معاملات. +بدون معاملات. --- ### `warn-schema-alteration` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يعلم Claude بالتأكيد قبل تشغيل بيانات `ALTER TABLE`. +**الإعداد الافتراضي:** يرشد Claude للتأكيد قبل تشغيل بيانات `ALTER TABLE`. -لا توجد معاملات. +بدون معاملات. --- ## التحذيرات -إعطاء العوامل سياق إضافي قبل العمليات المحتملة المحفوفة بالمخاطر ولكن غير المدمرة. +أعط الوكلاء سياقاً إضافياً قبل العمليات المحتملة الخطورة لكن غير المدمرة. ### `warn-large-file-write` **الحدث:** PreToolUse (Write) -**الافتراضي:** يعلم Claude بالتأكيد قبل كتابة ملفات أكبر من 1024 كيلوبايت. +**الإعداد الافتراضي:** يرشد Claude للتأكيد قبل كتابة الملفات الأكبر من 1024 كيلوبايت. **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | عتبة حجم الملف بالكيلوبايت التي يتم فوقها إصدار تحذير. | +| `thresholdKb` | `number` | `1024` | حد حجم الملف بالكيلوبايت أعلاه يتم إصدار تحذير. | **مثال:** @@ -622,7 +620,7 @@ icon: shield ``` -يفرض معالج الخطاف حد stdin بحجم 1 ميجابايت على الحمولات. لاختبار هذه السياسة بمحتوى صغير، اضبط `thresholdKb` على قيمة أقل بكثير من 1024. +يفرض معالج hook حداً بـ 1 MB لـ stdin على الحمولات. لاختبار هذه السياسة بمحتوى صغير، اضبط `thresholdKb` على قيمة أقل بكثير من 1024. --- @@ -630,49 +628,49 @@ icon: shield ### `warn-package-publish` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يعلم Claude بالتأكيد قبل تشغيل `npm publish`. +**الإعداد الافتراضي:** يرشد Claude للتأكيد قبل تشغيل `npm publish`. -لا توجد معاملات. +بدون معاملات. --- ### `warn-background-process` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يعلم Claude بالحذر عند تشغيل العمليات الخلفية عبر `nohup`, `&`, `disown`, أو `screen`. +**الإعداد الافتراضي:** يرشد Claude لأن يكون حذراً عند بدء العمليات الخلفية عبر `nohup` أو `&` أو `disown` أو `screen`. -لا توجد معاملات. +بدون معاملات. --- ### `warn-global-package-install` **الحدث:** PreToolUse (Bash) -**الافتراضي:** يعلم Claude بالتأكيد قبل تشغيل `npm install -g`, `yarn global add`, أو `pip install` بدون بيئة افتراضية. +**الإعداد الافتراضي:** يرشد Claude للتأكيد قبل تشغيل `npm install -g` أو `yarn global add` أو `pip install` بدون بيئة افتراضية. -لا توجد معاملات. +بدون معاملات. --- -## مديري الحزم +## مديرو الحزم -فرض مديري الحزم المسموح للعامل باستخدامهم. +فرض مديري الحزم المسموح للوكيل باستخدامهم. ### `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 { @@ -686,42 +684,42 @@ 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` موجود في قائمة المسموحات ويتم التحقق منها أولاً. --- ## سلوك الذكاء الاصطناعي -اكتشف عندما تعلق العوامل أو تتصرف بشكل غير متوقع. +اكتشف عندما يتعطل الوكلاء أو يتصرفون بشكل غير متوقع. ### `warn-repeated-tool-calls` **الحدث:** PreToolUse (جميع الأدوات) -**الافتراضي:** يعلم Claude بإعادة النظر عندما يتم استدعاء نفس الأداة 3 مرات أو أكثر بمعاملات متطابقة — علامة شائعة على أن العامل عالق في حلقة. +**الإعداد الافتراضي:** يرشد Claude لإعادة التفكير عندما تُستدعى نفس الأداة 3+ مرات بمعاملات متطابقة — وهي علامة شائعة على أن الوكيل عالق في حلقة. -لا توجد معاملات. +بدون معاملات. --- ## سير العمل -فرض سير عمل منضبط بنهاية الجلسة. تعمل هذه السياسات على حدث **Stop** وتحظر Claude من الإيقاف حتى يتم استيفاء كل شرط. تتبع سلسلة اعتماد طبيعية: commit → push → PR → CI. إذا حظرت سياسة ما، يتم تخطي السياسات اللاحقة في السلسلة (حظر يقطع الدائرة). +فرض سير عمل منضبط لنهاية الجلسة. تعمل هذه السياسات على حدث **Stop** وترفض قيام Claude من التوقف حتى يتحقق كل شرط. تتبع سلسلة تبعية طبيعية: commit → push → PR → CI. إذا رفضت سياسة، يتم تخطي السياسات اللاحقة في السلسلة (الرفض يقصر الدائرة). -جميع سياسات سير العمل **fail-open**: إذا لم تكن الأداة المطلوبة متاحة (مثل `gh` غير مثبت، لا يوجد git remote)، تسمح السياسة برسالة معلوماتية توضح سبب تخطي الفحص. +جميع سياسات سير العمل **تفشل بشكل مفتوح**: إذا كانت الأداة المطلوبة غير متاحة (مثل `gh` غير مثبت، لا يوجد remote git)، تسمح السياسة برسالة إعلامية توضح سبب تخطي الفحص. ### `require-commit-before-stop` **الحدث:** Stop -**الافتراضي:** ينكر الإيقاف عند وجود تغييرات غير محفوظة (ملفات معدلة أو محرحلة أو غير محتفظ بها). يرجع رسالة معلوماتية عند نظافة دليل العمل. +**الإعداد الافتراضي:** يرفض التوقف عندما تكون هناك تغييرات غير محفوظة (ملفات معدلة أو مرحلة أو غير مراقبة). يعيد رسالة إعلامية عندما تكون دليل العمل نظيفاً. -لا توجد معاملات. +بدون معاملات. --- ### `require-push-before-stop` **الحدث:** Stop -**الافتراضي:** ينكر الإيقاف عند وجود commits غير مدفوعة أو عندما لا يكون الفرع الحالي يحتوي على فرع tracking بعيد. يقترح `git push -u` لإنشاء فرع tracking إذا لزم الأمر. يفشل open إذا لم يكن هناك remote مكون. +**الإعداد الافتراضي:** يرفض التوقف عندما تكون هناك commits غير مدفوعة أو عندما لا يكون لديك الفرع الحالي فرع تتبع بعيد. يقترح `git push -u` لإنشاء فرع تتبع إذا لزم الأمر. يفشل بشكل مفتوح إذا لم يتم تكوين remote. **المعاملات:** @@ -746,14 +744,14 @@ icon: shield ### `require-pr-before-stop` **الحدث:** Stop -**الافتراضي:** ينكر الإيقاف عندما لا يكون هناك pull request للفرع الحالي، أو عندما يكون PR الموجود مغلقاً بدون دمج. يعلم Claude بإنشاء PR مع `gh pr create`. عندما يتم **دمج** PR، تسمح السياسة (تم شحن العمل) والرسالة توحي بالخروج من الفرع (`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` برمز وصول شخصي يحتوي على نطاق `repo` للوصول للقراءة -إلى pull requests. إذا لم يتم تثبيت `gh` أو لم يتم مصادقته، تفشل السياسة open وتقرر السبب إلى Claude. +تتطلب هذه السياسة [GitHub CLI](https://cli.github.com/) (`gh`) أن تكون مثبتة ومصرحاً بها. +قم بتشغيل `gh auth login` برمز وصول شخصي يحتوي على نطاق `repo` لقراءة الوصول إلى +pull requests. إذا لم يتم تثبيت `gh` أو عدم المصادقة عليه، تفشل السياسة بشكل مفتوح وتبلغ السبب إلى Claude. --- @@ -761,23 +759,23 @@ icon: shield ### `require-no-conflicts-before-stop` **الحدث:** Stop -**الافتراضي:** ينكر الإيقاف عندما لا يمكن دمج الفرع الحالي بنظافة في فرع الأساس. تؤكد السياسة أولاً وجود PR `OPEN` على GitHub للفرع — بدونها، لا يوجد هدف دمج لفرضه، لذا تقصير السياسة بالكامل للسماح. بمجرد تأكيد PR `OPEN`، يعمل مسحان مستقلان: +**الإعداد الافتراضي:** يرفض التوقف عندما لا يمكن دمج الفرع الحالي بنظافة في الفرع الأساسي. تؤكد السياسة أولاً وجود `OPEN` PR على GitHub للفرع — بدون واحدة، لا يوجد هدف دمج للفرض، لذلك تقصر السياسة بأكملها إلى السماح. بمجرد تأكيد `OPEN` PR، يتم تشغيل فحصين مستقلين: -1. **محلي** — `git merge-tree --write-tree --name-only origin/ HEAD`. عند تضارب، تسمي رسالة الحظر الملفات المتضاربة حتى يعرف Claude بالضبط ما يجب حله. -2. **GitHub** — يعيد استخدام نتيجة `gh pr view --json mergeable,state` التي تم جلبها بالفعل في precheck. يقبض على التضاربات التي قد يفتقدها `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` يرجع مخرجات غير قابلة للتحليل. تفشل أيضاً open عند فقدان `origin/` محلياً أو عند عدم وجود commits في المقدمة من base — تلك تخفيضات الطبقة 1 لا تزال تستشير PR mergeability المخزن مؤقتاً قبل السماح. +يتخطى بالكامل (يسمح) عند: `gh` غير مثبت، لا توجد PR للفرع، حالة PR ليست `OPEN` (مثل `MERGED`, `CLOSED`)، أو `gh pr view` يعيد مخرجات غير قابلة للتحليل. يفشل أيضاً بشكل مفتوح عندما يكون `origin/` مفقوداً محلياً أو عندما لا توجد commits في المقدمة من القاعدة — تلك الحالات من الطبقة 1 لا تزال تستشير قابلية الدمج المخزنة PR قبل السماح. **المعاملات:** | المعامل | النوع | الافتراضي | الوصف | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | فرع الأساس للتحقق من التضاربات ضده. | +| `baseBranch` | `string` | `"main"` | الفرع الأساسي للتحقق من التضاربات ضده. | -يُطلب GitHub CLI (`gh`) لهذه السياسة. تستخدم السياسة `gh pr view` لتأكيد وجود PR `OPEN` -قبل تشغيل أي مسح تضارب — بدون `gh`، تقصير السياسة للسماح. قم بتشغيل `gh auth login` برمز وصول شخصي يحتوي على -نطاق `repo` للوصول للقراءة إلى pull requests. +GitHub CLI (`gh`) مطلوب لهذه السياسة. تستخدم السياسة `gh pr view` للتأكيد من وجود +PR `OPEN` قبل تشغيل أي فحص تضارب — بدون `gh`، تقصر السياسة إلى السماح. قم بتشغيل `gh auth login` برمز وصول شخصي يحتوي على +نطاق `repo` لقراءة الوصول إلى pull requests. --- @@ -785,23 +783,23 @@ icon: shield ### `require-ci-green-before-stop` **الحدث:** Stop -**الافتراضي:** ينكر الإيقاف عندما تفشل فحوصات CI أو لا تزال تعمل على الفرع الحالي. يتحقق من كل من GitHub Actions workflow runs وفحوصات البوت من طرف ثالث (مثل CodeRabbit، SonarCloud، Codecov). يعامل `skipped` و `cancelled` كنتيجة نجاح. يرجع رسالة معلوماتية عند مرور جميع الفحوصات. +**الإعداد الافتراضي:** يرفض التوقف عندما تكون فحوصات CI في الفشل أو لا تزال قيد التشغيل على الفرع الحالي. يفحص كلاً من تشغيلات سير عمل GitHub Actions وفحوصات الروبوتات من جهات خارجية (مثل CodeRabbit, SonarCloud, Codecov). يتعامل مع الخلاصات `skipped` و`cancelled` كنجاح. يعيد رسالة إعلامية عندما تمر جميع الفحوصات. -لا توجد معاملات. +بدون معاملات. -تتطلب هذه السياسة [GitHub CLI](https://cli.github.com/) (`gh`) ليتم تثبيتها ومصادقة عليها. +تتطلب هذه السياسة [GitHub CLI](https://cli.github.com/) (`gh`) أن تكون مثبتة ومصرحاً بها. قم بتشغيل `gh auth login` برمز وصول شخصي يحتوي على نطاق `repo` للوصول للقراءة إلى -Actions workflow runs و Checks API. إذا لم يتم تثبيت `gh` أو لم يتم مصادقته، تفشل السياسة open وتقرر السبب إلى Claude. +تشغيلات سير عمل Actions وAPI الفحوصات. إذا لم يتم تثبيت `gh` أو عدم المصادقة عليه، تفشل السياسة بشكل مفتوح وتبلغ السبب إلى Claude. --- --- -## تعطيل السياسات الفردية +## تعطيل سياسات فردية -أزل سياسة معينة من `enabledPolicies` في تكوينك، أو بطلها في علامة تبويب السياسات بلوحة المعلومات. +أزل سياسة محددة من `enabledPolicies` في إعدادك، أو قم بتبديلها في لسان سياسات لوحة التحكم. ```json { @@ -812,4 +810,4 @@ Actions workflow runs و Checks API. إذا لم يتم تثبيت `gh` أو ل } ``` -لا تعمل السياسات غير المدرجة في `enabledPolicies`، حتى لو كانت إدخالات `policyParams` موجودة لها. \ No newline at end of file +السياسات غير المدرجة في `enabledPolicies` لا تعمل، حتى لو كانت هناك إدخالات `policyParams` موجودة لها. \ No newline at end of file diff --git a/docs/ar/configuration.mdx b/docs/ar/configuration.mdx index c2600134..65481be1 100644 --- a/docs/ar/configuration.mdx +++ b/docs/ar/configuration.mdx @@ -1,63 +1,62 @@ --- - --- -title: الإعدادات -description: "صيغة ملف الإعدادات ونظام النطاقات الثلاثة وقواعد الدمج" +title: التكوين +description: "تنسيق ملف الإعدادات، نظام النطاقات الثلاثة، وقواعد الدمج" icon: gear --- -يستخدم failproofai ملفات إعدادات JSON للتحكم في السياسات النشطة وكيفية سلوكها وموقع تحميل السياسات المخصصة. تم تصميم الإعدادات لتكون سهلة المشاركة مع فريقك - قم بالتزامها بمستودعك وسيحصل كل مطور على نفس الشبكة الأمنية للوكيل. +يستخدم failproofai ملفات إعدادات JSON للتحكم في السياسات النشطة وكيفية عملها ومن أين يتم تحميل السياسات المخصصة. تم تصميم التكوين ليكون من السهل مشاركته مع فريقك - قم بإيداعه في مستودع الكود وسيحصل كل مطور على نفس شبكة الأمان للـ agent. --- -## نطاقات الإعدادات +## نطاقات التكوين -هناك ثلاثة نطاقات للإعدادات، يتم تقييمها بترتيب الأولوية: +هناك ثلاثة نطاقات للتكوين، يتم تقييمها بترتيب الأولوية: | النطاق | مسار الملف | الغرض | |-------|-----------|---------| -| **المشروع** | `.failproofai/policies-config.json` | إعدادات كل مستودع، مُلتزم بالتحكم بالإصدارات | -| **محلي** | `.failproofai/policies-config.local.json` | تجاوزات شخصية لكل مستودع، مُستثناة من Git | -| **عام** | `~/.failproofai/policies-config.json` | إعدادات افتراضية على مستوى المستخدم عبر جميع المشاريع | +| **project** | `.failproofai/policies-config.json` | إعدادات خاصة بكل مستودع، مرتكزة في التحكم بالإصدارات | +| **local** | `.failproofai/policies-config.local.json` | تجاوزات شخصية لكل مستودع، مضافة إلى gitignore | +| **global** | `~/.failproofai/policies-config.json` | الإعدادات الافتراضية على مستوى المستخدم عبر جميع المشاريع | -عندما يتلقى failproofai حدث خطاف، يقوم بتحميل ودمج جميع الملفات الثلاثة الموجودة للمجلد الحالي. +عندما يتلقى 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"] ← union مُزال التكرار +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← اتحاد مُزال التكرار ``` -**`policyParams`** - أول نطاق يحدد المعاملات لسياسة معينة يفوز بالكامل. لا يوجد دمج عميق للقيم داخل معاملات السياسة. +**`policyParams`** - النطاق الأول الذي يحدد المعاملات لسياسة معينة يفوز بالكامل. لا يوجد دمج عميق للقيم داخل معاملات السياسة. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← المشروع يفوز، يتم تجاهل العام +resolved: { allowPatterns: ["sudo apt-get update"] } ← project يفوز، global مُتجاهل ``` ```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"] } ← ينزلق إلى العام +resolved: { allowPatterns: ["sudo systemctl status"] } ← تنحدر إلى global ``` -**`customPoliciesPath`** - أول نطاق يحددها يفوز. +**`customPoliciesPath`** - النطاق الأول الذي يحدده يفوز. -**`llm`** - أول نطاق يحددها يفوز. +**`llm`** - النطاق الأول الذي يحدده يفوز. --- -## صيغة ملف الإعدادات +## تنسيق ملف الإعدادات ```json { @@ -104,79 +103,79 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← ينزلق إلى ا النوع: `string[]` -قائمة بأسماء السياسات المراد تفعيلها. يجب أن تطابق الأسماء بالضبط معرّفات السياسات الموضحة في `failproofai policies`. انظر [السياسات المدمجة](/ar/built-in-policies) للاطلاع على القائمة الكاملة. +قائمة بأسماء السياسات المراد تفعيلها. يجب أن تطابق الأسماء بالضبط معرّفات السياسة الموضحة بواسطة `failproofai policies`. انظر [Built-in Policies](/ar/built-in-policies) للحصول على القائمة الكاملة. -السياسات التي ليست في `enabledPolicies` غير نشطة، حتى لو كان لديها إدخالات في `policyParams`. +السياسات التي لا تكون في `enabledPolicies` غير نشطة، حتى لو كانت لديها إدخالات في `policyParams`. ### `policyParams` النوع: `Record>` -تجاوزات المعاملات لكل سياسة. المفتاح الخارجي هو اسم السياسة؛ والمفاتيح الداخلية خاصة بكل سياسة. توثق كل سياسة المعاملات المتاحة لها في [السياسات المدمجة](/ar/built-in-policies). +تجاوزات المعاملات لكل سياسة. المفتاح الخارجي هو اسم السياسة؛ والمفاتيح الداخلية خاصة بكل سياسة. تقثّق كل سياسة معاملات متاحة في [Built-in Policies](/ar/built-in-policies). -إذا كانت لدى السياسة معاملات ولم تحددها، يتم استخدام الإعدادات المدمجة للسياسة. المستخدمون الذين لا يقومون بإعداد `policyParams` على الإطلاق سيحصلون على سلوك متطابق مع الإصدارات السابقة. +إذا كانت لدى السياسة معاملات لكنك لم تحددها، يتم استخدام الإعدادات الافتراضية المدمجة للسياسة. المستخدمون الذين لم يقوموا بتكوين `policyParams` على الإطلاق يحصلون على سلوك مطابق للإصدارات السابقة. -المفاتيح غير المعروفة داخل كتلة معاملات السياسة يتم تجاهلها بصمت في وقت تشغيل الخطاف ولكن يتم وضع علامة عليها كتحذيرات عند تشغيل `failproofai policies`. +المفاتيح غير المعروفة داخل كتلة معاملات السياسة يتم تجاهلها بصمت وقت تشغيل hook لكن يتم تجاهلها كتحذيرات عند تشغيل `failproofai policies`. -#### `hint` (عام) +#### `hint` (cross-cutting) النوع: `string` (اختياري) -رسالة مُلحقة بالسبب عندما تُرجع السياسة `deny` أو `instruct`. استخدمها لتزويد Claude بإرشادات قابلة للتنفيذ دون تعديل السياسة نفسها. +رسالة يتم إضافتها إلى السبب عندما تُرجع السياسة `deny` أو `instruct`. استخدمه لإعطاء Claude توجيهات قابلة للتنفيذ دون تعديل السياسة نفسها. -يعمل مع أي نوع سياسة - مدمجة أو مخصصة (`custom/`) أو اتفاقية المشروع (`.failproofai-project/`) أو اتفاقية المستخدم (`.failproofai-user/`). +يعمل مع أي نوع من السياسات — مدمجة أو مخصصة (`custom/`) أو اتفاقية المشروع (`.failproofai-project/`) أو اتفاقية المستخدم (`.failproofai-user/`). ```json { "policyParams": { "block-force-push": { - "hint": "Try creating a fresh branch instead." + "hint": "حاول إنشاء فرع جديد بدلاً من ذلك." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], - "hint": "Use apt-get directly without sudo." + "hint": "استخدم apt-get مباشرة بدون sudo." }, "custom/my-policy": { - "hint": "Ask the user for approval first." + "hint": "اطلب موافقة المستخدم أولاً." } } } ``` -عندما يرفض `block-force-push`، يرى Claude: *"Force-pushing is blocked. Try creating a fresh branch instead."* +عندما يرفض `block-force-push`، يرى Claude: *"Push بالقوة محظور. حاول إنشاء فرع جديد بدلاً من ذلك."* -القيم غير النصية والسلاسل الفارغة يتم تجاهلها بصمت. إذا لم يتم تعيين `hint`، لا يتغير السلوك (متوافق للخلف). +القيم غير النصية والسلاسل الفارغة يتم تجاهلها بصمت. إذا لم يتم تعيين `hint`، يبقى السلوك دون تغيير (متوافق للخلف). ### `customPoliciesPath` النوع: `string` (مسار مطلق) -مسار إلى ملف JavaScript يحتوي على سياسات خطاف مخصصة. يتم تعيينه تلقائياً بواسطة `failproofai policies --install --custom ` (يتم حل المسار إلى مطلق قبل تخزينه). +المسار إلى ملف JavaScript يحتوي على سياسات hook مخصصة. يتم تعيين هذا تلقائياً بواسطة `failproofai policies --install --custom ` (يتم تحويل المسار إلى مطلق قبل تخزينه). -يتم تحميل الملف من جديد في كل حدث خطاف - لا يوجد تخزين مؤقت. انظر [السياسات المخصصة](/ar/custom-policies) للتفاصيل المتعلقة بالإنشاء. +يتم تحميل الملف بشكل جديد في كل حدث hook - لا يوجد تخزين مؤقت. انظر [Custom Policies](/ar/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`. ما عليك سوى إسقاط الملفات في المجلد وسيتم انتقاؤها في حدث hook التالي. -**تحميل Union:** يتم مسح مجلدات الاتفاقية بالمشروع والمستخدم. يتم تحميل جميع الملفات المطابقة من كلا المستويين (على عكس `customPoliciesPath` الذي يستخدم نظام أول نطاق يفوز). +**تحميل الاتحاد:** يتم مسح مجلدات اتفاقية المشروع والمستخدم. يتم تحميل جميع الملفات المطابقة من كلا المستويين (بخلاف `customPoliciesPath` الذي يستخدم first-scope-wins). -انظر [السياسات المخصصة](/ar/custom-policies) للمزيد من التفاصيل والأمثلة. +انظر [Custom Policies](/ar/custom-policies) للحصول على المزيد من التفاصيل والأمثلة. ### `llm` النوع: `object` (اختياري) -إعدادات عميل LLM للسياسات التي تُجري استدعاءات AI. غير مطلوب لمعظم الإعدادات. +تكوين عميل LLM للسياسات التي تقوم بنداءات AI. غير مطلوب بالنسبة لمعظم الإعدادات. ```json { @@ -189,38 +188,46 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← ينزلق إلى ا --- -## إدارة الإعدادات من واجهة سطر الأوامر +## إدارة التكوين من CLI -تكتب أوامر `policies --install` و `policies --uninstall` إلى ملف إعدادات الخطاف الخاص بـ CLI الوكيل (نقاط إدخال الخطاف)، بينما `policies-config.json` هو الملف الذي تديره مباشرة. الاثنان منفصلان: +تكتب الأوامر `policies --install` و `policies --uninstall` إلى ملف إعدادات hook لـ agent CLI الخاص بك (نقاط الدخول للـ hook)، بينما `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 _(بيتا)_**: `~/.copilot/hooks/failproofai.json` (مستخدم), `/.github/hooks/failproofai.json` (مشروع) — لا يحتوي Copilot على نطاق `local`. إدخالات الخطاف تستخدم حقول الأوامر `bash`/`powershell` مفتاحة OS من Copilot مع `timeoutSec`؛ الملف يحمل علامة `version: 1` على المستوى الأعلى. دعم Copilot CLI موجود في **بيتا** بينما نتحقق من مخطط سجل `events.jsonl` (الذي لا تحدده المستندات العامة) مقابل المزيد من الجلسات الحقيقية. -- **`policies-config.json`** — يخبر failproofai بأي سياسات يتم تقييمها وبأي معاملات (مشتركة عبر جميع CLIs الوكيل) +- **إعدادات 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 مع `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`، …) في صفيف مسطح لكل [schema hooks](https://cursor.com/docs/hooks) الخاص بـ Cursor؛ يحمل الملف علامة `version: 1` على المستوى الأعلى. يقوم معالج الأحداث بتشريع camelCase → PascalCase عبر `CURSOR_EVENT_MAP` بحيث تعمل السياسات المدمجة الموجودة دون تغيير. دعم Cursor Agent في **beta** بينما نتحقق من نسخة Cursor على القرص (غير محددة في المستندات العامة) مقابل المزيد من عمليات التثبيت الحقيقية. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (مستخدم)، `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (مشروع) — OpenCode ليس له نطاق `local`. بخلاف الأربعة CLIs الأخرى، OpenCode ليس له **نظام hook أوامر خارجية**: يحمل في العملية JS/TS plugins مسجل صراحة عبر صفيف `plugin: []` في `opencode.json` (الاكتشاف التلقائي من `.opencode/plugins/` **ليس** كيفية تحميل plugins على opencode v1.14.33). يسقط التثبيت مصراع صغير plugin توليدي يستدعي ثنائي failproofai كعملية فرعية ويترجم استجابة JSON على شكل Claude الثنائية إلى دلالات plugin (`throw new Error()` للـ deny، `client.session.prompt(...)` للـ instruct، no-op للـ allow). تعيش الجلسات في قاعدة بيانات SQLite الخاصة بـ OpenCode في `~/.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 عند بدء التشغيل؛ ملف الإعدادات هو صفيف سلاسل مسطح `{"packages": ["./relative/path", …]}`. يكتب failproofai إدخال صفيف حزم واحد يشير إلى مجلد `pi-extension/` المجمع الخاص به. تشترك الإضافة داخلياً في أحداث `tool_call` / `user_bash` / `input` / `session_start` الخاصة بـ Pi وتنفيذ `failproofai --hook --cli pi`؛ يقوم المعالج بتشريع snake_case lower_snake_case → PascalCase عبر `PI_EVENT_MAP` بحيث تعمل السياسات المدمجة الموجودة دون تغيير. دعم 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}` ملفوف في مخطط Gemini's `{matcher, hooks: [...]}` matcher مع `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's المسطح `{decision: "deny", reason}` (المفضل لكل القاعدة الذهبية لـ Gemini exit-0 contract)، `{hookSpecificOutput: {hookEventName, additionalContext}}` لحقن السياق على BeforeAgent / AfterTool / SessionStart، و `{decision: "block", reason}` على AfterAgent لدلالات إعادة المحاولة القسري. دعم Gemini CLI في **beta** بينما نوسع التغطية الحقيقية. انظر [Gemini CLI hooks docs](https://geminicli.com/docs/hooks/). +- **`policies-config.json`** — يخبر failproofai بالسياسات التي يجب تقييمها وبأي معاملات (مشترك عبر جميع agent CLIs) -مرّر `--cli claude|codex|copilot` للاستهداف الوكيل محدد (مفصول بمسافات أو متكرر لأي مجموعة فرعية): +مرر `--cli claude|codex|copilot|cursor|opencode|pi|gemini` للاستهداف agent محدد (مفصول بمسافة أو مكرر لأي مجموعة فرعية): ```bash failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project -failproofai policies --install --cli claude codex copilot +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 claude codex copilot cursor opencode pi gemini ``` -عند حذف `--cli`، يكتشف `failproofai` أي CLIs للوكيل مُثبتة (`which claude` / `which codex` / `which copilot`): +عندما يتم حذف `--cli`، يكتشف failproofai أي agent CLIs مثبتة (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): -- **تم اكتشاف CLI واحد** — يختار هذا CLI تلقائياً دون موجه. -- **تم اكتشاف عدة CLIs** في محطة طرفية تفاعلية — يعرض موجه اختيار وحيد بأسهم: عند وجود اثنين من CLIs الخيارات هي `Both` و ` only` و ` only`؛ مع ثلاثة CLIs الخيار الأول يصبح `All` (↑↓ للتحرك, Enter للاختيار, ^C للخروج). -- **تم اكتشاف عدة CLIs** في تشغيل غير تفاعلي (CI, بدون TTY) — التثبيت لجميع CLIs المكتشفة دون موجه. -- **لم يتم اكتشاف أي منها** — الرجوع إلى `claude`، مع تحذير بعدم وجود ملف تنفيذي للوكيل في PATH؛ أمر الخطاف لا يزال مكتوباً لذا يتم تنشيطه بمجرد تثبيت واحد. +- **CLI واحد مكتشف** — يختار تلقائياً هذا CLI دون السؤال. +- **CLIs متعددة مكتشفة** في محطة تفاعلية — يعرض موجه اختيار واحد مفتاح السهم مجمعة في قسم `Detected (N)` (مع صف إجمالي `Install for all N detected` + كل CLI مكتشفة بشكل فردي) وقسم `Not installed (M) · install hooks ahead of time` يسرد كل CLI غير مكتشفة مدعومة كخيار تثبيت آجل (↑↓ للتحرك، Enter للاختيار، ^C للخروج). يعرض تدفق الإزالة قسم Detected فقط. +- **CLIs متعددة مكتشفة** في تشغيل غير تفاعلي (CI، بدون TTY) — تثبيت لجميع CLIs المكتشفة دون السؤال. +- **لا يتم اكتشاف أي منها** — يرجع إلى `claude`، مع تحذير بأنه لم يتم العثور على ثنائي agent في PATH؛ أمر hook لا يزال مكتوبا حتى ينشط بمجرد تثبيت واحد. -يمكنك تعديل `policies-config.json` مباشرة في أي وقت؛ التغييرات تدخل حيز التنفيذ فوراً في حدث الخطاف التالي دون الحاجة إلى إعادة تشغيل. +يمكنك تحرير `policies-config.json` مباشرة في أي وقت؛ يتم تفعيل التغييرات فوراً في حدث hook التالي دون الحاجة إلى إعادة تشغيل. --- -## مثال: إعدادات على مستوى المشروع مع إعدادات افتراضية للفريق +## مثال: تكوين على مستوى المشروع مع إعدادات الفريق الافتراضية -التزم `.failproofai/policies-config.json` بمستودعك: +قم بإيداع `.failproofai/policies-config.json` في مستودع الكود الخاص بك: ```json { @@ -239,4 +246,4 @@ failproofai policies --install --cli claude codex copilot } ``` -يمكن لكل مطور بعد ذلك إنشاء `.failproofai/policies-config.local.json` (مستثناة من Git) للتجاوزات الشخصية دون التأثير على زملائهم. \ No newline at end of file +يمكن لكل مطور بعد ذلك إنشاء `.failproofai/policies-config.local.json` (مضافة إلى gitignore) للحصول على تجاوزات شخصية دون التأثير على زملاء الفريق. \ No newline at end of file diff --git a/docs/ar/dashboard.mdx b/docs/ar/dashboard.mdx index 524d5e28..ac941b3b 100644 --- a/docs/ar/dashboard.mdx +++ b/docs/ar/dashboard.mdx @@ -1,23 +1,22 @@ --- ---- -title: لوحة التحكم +title: لوحة المعلومات description: "مراقبة جلسات الوكيل، ومراجعة استدعاءات الأدوات، وإدارة السياسات" icon: chart-line --- -لوحة تحكم failproofai هي تطبيق ويب محلي لمراقبة جلسات وكيل الذكاء الاصطناعي الخاص بك وإدارة السياسات. انظر إلى ما فعله وكلاؤك أثناء غيابك. +لوحة معلومات failproofai هي تطبيق ويب محلي لمراقبة جلسات وكيل الذكاء الاصطناعي الخاص بك وإدارة السياسات. اطلع على ما فعله وكلاؤك أثناء غيابك. --- -## بدء لوحة التحكم +## بدء لوحة المعلومات ```bash failproofai ``` -يتم الفتح على `http://localhost:8020`. +يفتح على `http://localhost:8020`. -تقرأ لوحة التحكم مباشرة من نظام الملفات - مجلدات مشاريع Claude Code وملفات إعدادات failproofai. لا يتم كتابة أي شيء إلى خدمة بعيدة. +تقرأ لوحة المعلومات مباشرة من نظام الملفات - مجلدات مشاريع Claude Code وملفات تكوين failproofai. لا يتم كتابة أي شيء إلى خدمة بعيدة. --- @@ -25,55 +24,55 @@ failproofai ### المشاريع -تسرد جميع مشاريع Claude Code و OpenAI Codex و GitHub Copilot CLI _(beta)_ الموجودة على جهازك. يتم اكتشاف مشاريع Claude من `~/.claude/projects/` (أو المسار المحدد بواسطة `CLAUDE_PROJECTS_PATH`؛ يتم اكتشاف مشاريع Codex بمسح كل النصوص الموجودة تحت `~/.codex/sessions///
/*.jsonl` والتجميع حسب `cwd` المسجل في السجل الأول لكل جلسة؛ يتم اكتشاف مشاريع Copilot CLI بمسح كل `~/.copilot/session-state//workspace.yaml` (قابل للتكوين عبر `COPILOT_HOME`) والتجميع حسب حقل `cwd` الخاص به. يتم عرض المشروع الذي تم استخدامه بواسطة عدة واجهات سطر أوامر كصف واحد مع جميع الشارات المطابقة. استخدم القائمة المنسدلة **CLI** فوق الجدول للتصفية حسب واجهة سطر أوامر محددة؛ يحافظ عنوان URL على اختيارك كـ `?cli=claude|codex|copilot`. +تسرد جميع مشاريع 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** أعلاه الجدول للتصفية حسب واجهة سطر أوامر وكيل معينة؛ يحتفظ عنوان URL بتحديدك كـ `?cli=claude|codex|copilot|cursor|opencode|pi|gemini`. يعرض كل مشروع: - اسم المشروع (مشتق من مسار المجلد) -- شارة CLI — `Claude Code` (برتقالي)، `OpenAI Codex` (بنفسجي)، و/أو `GitHub Copilot` (أزرق) -- تاريخ أحدث نشاط جلسة +- شارة CLI — `Claude Code` (برتقالي)، `OpenAI Codex` (بنفسجي)، `GitHub Copilot` (أزرق)، `Cursor Agent` (زمردي)، `OpenCode` (عنبري)، `Pi` (وردي)، و/أو `Gemini CLI` (سماوي) +- تاريخ آخر نشاط جلسة -انقر على مشروع لمشاهدة جلساته. +انقر على مشروع لرؤية جلساته. ### الجلسات تسرد جميع الجلسات داخل مشروع. تعرض كل جلسة: - معرّف الجلسة -- طوابع زمنية البداية والنهاية +- الطوابع الزمنية للبدء والنهاية - عدد استدعاءات الأدوات -- عدد أنشطة الخطاف (السياسات التي تم تشغيلها) +- عدد أنشطة الخطاف (السياسات التي تم تفعيلها) استخدم مرشح نطاق التاريخ وبحث معرّف الجلسة لتضييق القائمة. يتم ترقيم الجلسات. -انقر على جلسة لفتح مشاهد الجلسة. +انقر على جلسة لفتح عارض الجلسة. -### مشاهد الجلسة +### عارض الجلسة -يجيب مشاهد الجلسة على السؤال الأساسي للوكلاء المستقلين: ماذا فعل الوكيل، وهل ظل على المسار الصحيح؟ تشير شارة CLI بجانب الرأس إلى ما إذا كانت الجلسة نسخة Claude Code أو OpenAI Codex. يعرض جدول زمني لكل شيء حدث في جلسة: +يجيب عارض الجلسة على السؤال الرئيسي للوكلاء المستقلين: ماذا فعل الوكيل، وهل ظل على المسار الصحيح؟ تشير شارة CLI بجانب الرأس إلى ما إذا كانت الجلسة نسخة Claude Code أو OpenAI Codex أو GitHub Copilot CLI أو Cursor Agent أو OpenCode أو Pi أو Gemini CLI. يعرض خطًا زمنيًا لكل ما حدث في جلسة: -- **الرسائل** - استجابات Claude النصية والتعليمات من المستخدم -- **استدعاءات الأدوات** - كل أداة استدعاها Claude، مع المدخلات والمخرجات الخاصة بها -- **نشاط السياسة** - لكل استدعاء أداة، السياسات التي تم تشغيلها والقرار الذي أرجعته +- **الرسائل** - ردود النصوص من Claude والمطالبات من المستخدم +- **استدعاءات الأدوات** - كل أداة استدعاها Claude، مع المدخلات والمخرجات +- **نشاط السياسة** - لكل استدعاء أداة، السياسات التي تم تفعيلها والقرار الذي أرجعته -تعرض شريط الإحصائيات في الأعلى مدة الجلسة وإجمالي استدعاءات الأدوات وملخص قرارات الخطاف (عدد السماح / الرفض / التعليمات). +تعرض شريط الإحصائيات في الأعلى مدة الجلسة وإجمالي استدعاءات الأدوات وملخصًا لقرارات الخطاف (عدد السماح / الرفض / إرشاد). -يمكنك تصدير الجلسة كملف ZIP أو JSONL باستخدام زر التحميل. +انقر على زر **تنزيل السجلات** لتصدير الجلسة. بالنسبة لجلسات Claude Code و Codex و Copilot و Cursor و Pi و Gemini، تحصل على نص JSONL الأصلي على القرص كما هو؛ بالنسبة لـ OpenCode (التي تعيش جلساتها في SQLite وليس على القرص)، تحصل على مستند JSON يعكس جداول `session` / `messages` / `parts` الأساسية. ### السياسات -صفحة بلسانين لإدارة السياسات ومراجعة النشاط. +صفحة بتبويبين لإدارة السياسات ومراجعة النشاط. - - - بدّل السياسات الفردية تشغيل أو إيقاف بنقرة واحدة (يكتب إلى `~/.failproofai/policies-config.json`) - - وسّع سياسة لتكوين معاملات الخاص بها (للسياسات التي تدعم `policyParams`) + + - تبديل السياسات الفردية على أو إيقافها بنقرة واحدة (كتابة إلى `~/.failproofai/policies-config.json`) + - توسيع سياسة لتكوين معاملات الخاصة بها (بالنسبة للسياسات التي تدعم `policyParams`) - تثبيت أو إزالة الخطافات لنطاق معين - - تعيين مسار ملف سياسات مخصص + - تعيين مسار ملف السياسات المخصصة - - - السجل الكامل المرقّم لكل حدث خطاف تم تشغيله عبر جميع الجلسات - - التصفية حسب القرار أو نوع الحدث أو CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_) أو اسم السياسة أو معرّف الجلسة - - يعرض كل صف: الطابع الزمني واسم السياسة والقرار وشارة CLI (برتقالي = Claude Code، بنفسجي = OpenAI Codex، أزرق = GitHub Copilot) واسم الأداة ومعرّف الجلسة وسبب قرارات الرفض/التعليمات - - انقر على معرّف جلسة لفتح نسختها - يكتشف المشاهد تلقائياً أي CLI أطلق الخطاف (Claude `~/.claude/projects/…`، Codex `~/.codex/sessions/…`، Copilot CLI `~/.copilot/session-state//events.jsonl`) ويعرض شارة 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) واسم الأداة ومعرّف الجلسة والسبب لقرارات الرفض/الإرشاد + - انقر على معرّف الجلسة لفتح النسخة الخاصة به — يكتشف العارض تلقائيًا واجهة سطر الأوامر التي فعلت الخطاف (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 المطابقة في الرأس @@ -81,31 +80,31 @@ failproofai ## التحديث التلقائي -تحتوي لوحة التحكم على تبديل للتحديث التلقائي في التنقل العلوي. عند تفعيله، يتم تحديث الصفحة الحالية بشكل دوري لعرض الجلسات الجديدة ونشاط السياسة عند ظهورها. ضروري لمراقبة جلسات الوكيل المستقل ذات التشغيل الطويل. +تحتوي لوحة المعلومات على تبديل تحديث تلقائي في الملاحة العلوية. عند تفعيله، تنعش الصفحة الحالية بشكل دوري لإظهار جلسات جديدة ونشاط السياسة وهي تظهر. ضروري لمراقبة جلسات وكيل مستقل طويلة الأمد. --- ## تعطيل الصفحات -إذا كنت تحتاج فقط إلى بعض أجزاء لوحة التحكم، فاضبط `FAILPROOFAI_DISABLE_PAGES` على قائمة مفصولة بفواصل من أسماء الصفحات: +إذا كنت تحتاج فقط إلى بعض أجزاء لوحة المعلومات، فاضبط `FAILPROOFAI_DISABLE_PAGES` على قائمة مفصولة بفواصل من أسماء الصفحات: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai ``` -القيم الصحيحة: `policies`، `projects`. +القيم الصحيحة: `policies` و `projects`. --- ## المظهر -تدعم لوحة التحكم وضع الإضاءة والظلام. بدّل عبر الزر في شريط التنقل. يتم تخزين التفضيل في ذاكرة التخزين المحلي بمتصفحك. +تدعم لوحة المعلومات الوضع الفاتح والداكن. بدل عبر الزر في شريط الملاحة. يتم تخزين التفضيل في وحدة تخزين محلية المتصفح. --- ## تكوين مسار المشاريع -بشكل افتراضي، تقرأ لوحة التحكم من دليل مشاريع Claude Code القياسي. تجاوزها لأنظمة مخصصة: +بشكل افتراضي، تقرأ لوحة المعلومات من دليل مشاريع Claude Code القياسي. تجاوزها في الإعدادات المخصصة: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -115,30 +114,30 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## الوصول من مضيف غير localhost -عند تشغيل لوحة التحكم في **وضع dev** (`npm run dev`) والوصول إليها من اسم مضيف بخلاف `localhost` - على سبيل المثال، مجال مخصص أو عنوان IP بعيد أو عنوان URL بنفق - قد تشاهد تحذيراً مثل: +عند تشغيل لوحة المعلومات في **وضع التطوير** (`npm run dev`) والوصول إليها من اسم مضيف آخر غير `localhost` - على سبيل المثال، مجال مخصص أو IP بعيد أو عنوان URL متسلسل - قد تظهر تحذير مثل: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -هذا Next.js يمنع الوصول عبر الأصول إلى websocket HMR (إعادة تحميل الوحدة الساخنة) الخاص به، وهي ميزة خاصة بـ dev فقط. للسماح بمضيفك، استخدم علم `--allowed-origins`: +هذا هو Next.js يحظر الوصول عبر الأصول إلى websocket HMR (إعادة تحميل وحدة ساخن)، وهي ميزة خاصة بالتطوير فقط. للسماح بمضيفك، استخدم العلم `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -لعدة مضيفات أو عناوين IP، مرر قائمة مفصولة بفواصل: +لعدة مضيفات أو IPs، مرر قائمة مفصولة بفواصل: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -يمكنك أيضاً ضبط متغير البيئة `FAILPROOFAI_ALLOWED_DEV_ORIGINS` بدلاً من ذلك: +يمكنك أيضًا تعيين متغير البيئة `FAILPROOFAI_ALLOWED_DEV_ORIGINS` بدلاً من ذلك: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -ينطبق هذا فقط على وضع dev. عند تشغيل `failproofai` (وضع الإنتاج)، لا توجد websocket HMR ولا توجد مشكلة مورد dev عبر الأصول. +هذا ينطبق فقط على وضع التطوير. عند تشغيل `failproofai` (وضع الإنتاج)، لا يوجد websocket HMR ولا مشكلة مورد تطوير عبر الأصول. \ No newline at end of file diff --git a/docs/ar/getting-started.mdx b/docs/ar/getting-started.mdx index 28acdc2c..8b4a239f 100644 --- a/docs/ar/getting-started.mdx +++ b/docs/ar/getting-started.mdx @@ -1,7 +1,6 @@ --- ---- title: البدء السريع -description: "ثبّت failproofai، وفعّل السياسات، واترك وكلاءك يعملون بموثوقية" +description: "ثبّت failproofai وفعّل السياسات واترك وكلاءك يعملون بموثوقية" icon: rocket --- @@ -31,48 +30,52 @@ bun add -g failproofai ## البدء السريع - - السياسات هي قواعد تعمل قبل وبعد كل استدعاء أداة وكيل. تقبض على الأوامر المدمرة، وتسرب الأسرار، وأنماط الفشل الأخرى قبل أن تسبب ضررًا. + + السياسات هي قواعد تعمل قبل وبعد كل استدعاء أداة من الوكيل. وهي تمسك بالأوامر المدمرة وتسرب الأسرار وأنماط الفشل الأخرى قبل أن تسبب الضرر. ```bash failproofai policies --install ``` - هذا يكتب إدخالات hook في واجهات سطر الأوامر المثبتة للوكيل (ملف `~/.claude/settings.json` الخاص بـ Claude Code، أو `~/.codex/hooks.json` الخاص بـ OpenAI Codex، أو `~/.copilot/hooks/failproofai.json` الخاص بـ GitHub Copilot CLI). عندما يكون أكثر من واحد موجودًا، سيتم الطلب منك؛ مرر `--cli claude codex copilot` (أي مجموعة فرعية) لتخطي الطلب. + يكتب هذا مدخلات hook في واجهات سطر الأوامر المثبتة للوكلاء (Claude Code في `~/.claude/settings.json`، OpenAI Codex في `~/.codex/hooks.json`، GitHub Copilot CLI في `~/.copilot/hooks/failproofai.json`، Cursor Agent في `~/.cursor/hooks.json`، OpenCode في shim المكون مسبقاً في `~/.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` (أي مجموعة جزئية) لتخطي الموجه. - دعم GitHub Copilot CLI في مرحلة **beta** — ثبّت باستخدام `--cli copilot`. + دعم GitHub Copilot CLI و Cursor Agent و OpenCode و Pi و Gemini CLI هو **إصدار تجريبي** — ثبّت باستخدام `--cli copilot` أو `--cli cursor` أو `--cli opencode` أو `--cli pi` أو `--cli gemini`. ```bash failproofai policies --install --scope project failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project + 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 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 → reads stdin JSON @@ -80,36 +83,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 @@ -128,18 +131,18 @@ 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` التالي. بمرور الوقت، تصبح هذه السياسات معياراً جودة حياً يستمر في التحسن. --- @@ -149,22 +152,22 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON تبقى جميع الإعدادات والسجلات على جهازك: | المسار | ما يخزنه | -|------|----------------| +|------|---------| | `~/.failproofai/policies-config.json` | إعدادات السياسة العامة | | `~/.failproofai/hook-activity.jsonl` | سجل تنفيذ Hook | | `~/.failproofai/hook.log` | سجل التصحيح لأخطاء hook المخصصة | -| `.failproofai/policies-config.json` | إعدادات المشروع (محفوظة) | -| `.failproofai/policies-config.local.json` | التجاوزات الشخصية (معفاة من gitignore) | +| `.failproofai/policies-config.json` | إعدادات خاصة بالمشروع (مرتكبة) | +| `.failproofai/policies-config.local.json` | تجاوزات شخصية (معزولة عن git) | --- -## الإلغاء +## إلغاء التثبيت ```bash failproofai policies --uninstall ``` -يزيل إدخالات hook من `~/.claude/settings.json`. يتم الاحتفاظ بملفات الإعدادات في `~/.failproofai/`. +يزيل مدخلات hook من `~/.claude/settings.json`. ملفات الإعدادات في `~/.failproofai/` يتم الاحتفاظ بها. --- @@ -177,10 +180,10 @@ failproofai policies --uninstall - جميع السياسات الـ 26 مع المعاملات + جميع 26 سياسة مع المعاملات - + اكتب سياساتك الخاصة في JavaScript diff --git a/docs/de/architecture.mdx b/docs/de/architecture.mdx index fc69273b..59b7d539 100644 --- a/docs/de/architecture.mdx +++ b/docs/de/architecture.mdx @@ -4,7 +4,7 @@ description: "Wie der Hook-Handler, das Laden der Konfiguration und die Richtlin icon: sitemap --- -Dieses Dokument erläutert, wie failproofai intern funktioniert: 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 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. --- @@ -12,8 +12,8 @@ Dieses Dokument erläutert, wie failproofai intern funktioniert: wie das Hook-Sy failproofai besteht aus zwei unabhängigen Teilsystemen: -1. **Hook-Handler** – Ein schneller CLI-Subprozess, den Claude Code bei jedem Agent-Tool-Aufruf startet. 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. +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. Beide Teilsysteme teilen sich Konfigurationsdateien in `~/.failproofai/` und im `.failproofai/`-Verzeichnis des Projekts, laufen aber als separate Prozesse und kommunizieren ausschließlich über das Dateisystem. @@ -23,7 +23,7 @@ Beide Teilsysteme teilen sich Konfigurationsdateien in `~/.failproofai/` und im ### Integration mit Claude Code -Wenn Sie `failproofai policies --install` ausführen, werden Einträge wie diese in `~/.claude/settings.json` geschrieben: +Beim Ausführen von `failproofai policies --install` werden Einträge wie folgt in `~/.claude/settings.json` geschrieben: ```json { @@ -44,9 +44,9 @@ Wenn Sie `failproofai policies --install` ausführen, werden Einträge wie diese } ``` -Claude Code startet dann `failproofai --hook PreToolUse` als Subprozess vor jedem Tool-Aufruf und übergibt dabei ein JSON-Payload über stdin. +Claude Code ruft `failproofai --hook PreToolUse` dann als Subprozess vor jedem Tool-Aufruf auf und übergibt eine JSON-Nutzlast über stdin. -### Payload-Format +### Nutzlastformat ```json { @@ -60,9 +60,9 @@ Claude Code startet dann `failproofai --hook PreToolUse` als Subprozess vor jede } ``` -Bei `PostToolUse`-Ereignissen enthält das Payload zusätzlich `tool_result` mit der Ausgabe des Tools. +Bei `PostToolUse`-Ereignissen enthält die Nutzlast zusätzlich `tool_result` mit der Ausgabe des Tools. -Der Handler erzwingt ein stdin-Limit von 1 MB. Payloads, die dieses Limit überschreiten, werden verworfen und alle Richtlinien erlauben implizit. +Der Handler erzwingt ein stdin-Limit von 1 MB. Nutzlasten, die diesen Wert überschreiten, werden verworfen, und alle Richtlinien erlauben implizit. ### Antwortformat @@ -85,7 +85,7 @@ Der Handler erzwingt ein stdin-Limit von 1 MB. Payloads, die dieses Limit übers } ``` -**Anweisung (beliebiges Ereignis außer Stop):** +**Anweisen (beliebiges Ereignis außer Stop):** ```json { "hookSpecificOutput": { @@ -94,9 +94,9 @@ Der Handler erzwingt ein stdin-Limit von 1 MB. Payloads, die dieses Limit übers } ``` -**Stop-Ereignis mit Anweisung:** +**Stop-Ereignis instruct:** - Exit-Code: `2` -- Begründung wird in stderr geschrieben (nicht stdout) +- Grund wird in stderr geschrieben (nicht stdout) **Erlauben:** - Exit-Code: `0` @@ -104,7 +104,7 @@ Der Handler erzwingt ein stdin-Limit von 1 MB. Payloads, die dieses Limit übers **Erlauben mit Nachricht:** -`allow(message)` erlaubt es einer Richtlinie, informationellen Kontext an Claude zurückzusenden, auch wenn die Operation erlaubt ist. Der Hook-Handler schreibt folgenden JSON-Inhalt in **stdout** (nicht in eine Konfigurationsdatei – dies ist die Antwort des Handlers an Claude Code, genau wie Ablehnen- und Anweisungsantworten oben): +`allow(message)` ermöglicht es einer Richtlinie, informativen Kontext an Claude zurückzusenden, auch 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 Ablehnen- und Anweisen-Antworten oben): ```json // Written to stdout by the hook handler process @@ -115,31 +115,31 @@ Der Handler erzwingt ein stdin-Limit von 1 MB. Payloads, die dieses Limit übers } ``` - Exit-Code: `0` (Operation ist erlaubt) -- Wenn mehrere Richtlinien `allow` mit einer Nachricht zurückgeben, werden ihre Nachrichten mit Zeilenumbrüchen zu einem einzelnen `additionalContext`-String zusammengefügt +- Wenn mehrere Richtlinien `allow` mit einer Nachricht zurückgeben, werden deren Nachrichten mit Zeilenumbrüchen zu einem einzigen `additionalContext`-String zusammengefügt - Wenn keine Richtlinie eine Nachricht liefert, ist stdout leer (wie zuvor) -### Verarbeitungspipeline +### Verarbeitungs-Pipeline `src/hooks/handler.ts` implementiert die vollständige Pipeline: ```text stdin JSON - → Payload parsen (max. 1 MB) - → Sitzungsmetadaten extrahieren (session_id, cwd, tool_name, tool_input, etc.) - → readMergedHooksConfig(cwd) ← führt Projekt-, lokale und globale Konfiguration zusammen - → aktivierte eingebaute Richtlinien mit aufgelösten Parametern registrieren - → benutzerdefinierte Richtlinien aus customPoliciesPath laden (falls gesetzt) - → benutzerdefinierte Richtlinien in die Policy-Registry registrieren - → alle Richtlinien auswerten (zuerst eingebaute, dann benutzerdefinierte) - → erstes deny unterbricht sofort die Auswertung - → instruct-Entscheidungen werden gesammelt - → allow-Nachrichten werden gesammelt - → JSON-Entscheidung in stdout schreiben - → Ereignis in ~/.failproofai/hook-activity.jsonl speichern - → beenden + → 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 ``` -Der gesamte Prozess läuft bei typischen Payloads ohne LLM-Aufrufe in unter 100 ms ab. +Der gesamte Prozess läuft bei typischen Nutzlasten in unter 100 ms ohne LLM-Aufrufe. --- @@ -149,17 +149,17 @@ Der gesamte Prozess läuft bei typischen Payloads ohne LLM-Aufrufe in unter 100 ```text [1] {cwd}/.failproofai/policies-config.json ← Projekt (höchste Priorität) -[2] {cwd}/.failproofai/policies-config.local.json ← lokal -[3] ~/.failproofai/policies-config.json ← global (niedrigste Priorität) +[2] {cwd}/.failproofai/policies-config.local.json ← Lokal +[3] ~/.failproofai/policies-config.json ← Global (niedrigste Priorität) ``` Zusammenführungslogik: -- `enabledPolicies` – deduplizierte Vereinigung aus allen drei Dateien +- `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 +- `customPoliciesPath` – die erste Datei, die ihn definiert, gewinnt +- `llm` – die erste Datei, die ihn definiert, gewinnt -Das Web-Dashboard verwendet `readHooksConfig()` (nur global) zum Lesen und Schreiben, da es ohne Projekt-cwd aufgerufen wird. +Das Web-Dashboard verwendet `readHooksConfig()` (nur global) zum Lesen und Schreiben, da es nicht mit einem Projekt-cwd aufgerufen wird. --- @@ -169,18 +169,18 @@ Das Web-Dashboard verwendet `readHooksConfig()` (nur global) zum Lesen und Schre Für jede Richtlinie: -1. Das `params`-Schema der Richtlinie nachschlagen (falls vorhanden). -2. `policyParams[policy.name]` aus der zusammengeführten Konfiguration lesen. -3. Vom Benutzer angegebene Werte über 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, mit der nächsten Richtlinie fortfahren. +1. Das `params`-Schema der Richtlinie wird nachgeschlagen (sofern vorhanden). +2. `policyParams[policy.name]` wird aus der zusammengeführten Konfiguration gelesen. +3. Vom Benutzer angegebene Werte werden über die Schema-Standards gelegt, um `ctx.params` zu erstellen. +4. `policy.fn(ctx)` wird mit dem aufgelösten Kontext aufgerufen. +5. Ist das Ergebnis `deny`, wird sofort abgebrochen und diese Entscheidung zurückgegeben. +6. Ist das Ergebnis `instruct`, wird die Nachricht angesammelt und die Auswertung fortgesetzt. +7. Ist das Ergebnis `allow`, wird mit der nächsten Richtlinie fortgefahren. -Nach dem Durchlauf aller Richtlinien: -- Falls ein `deny` zurückgegeben wurde, die Ablehnungsantwort ausgeben. -- Falls `instruct`-Rückgaben gesammelt wurden, eine einzelne instruct-Antwort mit allen zusammengefügten Nachrichten ausgeben. -- Andernfalls eine allow-Antwort ausgeben (leerer stdout, Exit 0). +Nach Ausführung aller Richtlinien: +- Wurde ein `deny` zurückgegeben, wird die Ablehnungsantwort ausgegeben. +- Wurden `instruct`-Rückgaben gesammelt, wird eine einzelne Anweisungsantwort mit allen zusammengefügten Nachrichten ausgegeben. +- Andernfalls wird eine Erlaubnisantwort ausgegeben (leerer stdout, Exit 0). --- @@ -204,15 +204,15 @@ interface BuiltinPolicyDefinition { } ``` -Richtlinien, die `params` akzeptieren, deklarieren ein `PolicyParamsSchema` mit Typen und Standardwerten für jeden Parameter. Der Richtlinienauswerter injiziert aufgelöste Werte in `ctx.params`, bevor `fn` aufgerufen wird. 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 Richtlinien-Evaluator injiziert aufgelöste Werte in `ctx.params`, bevor `fn` aufgerufen wird. Richtlinienfunktionen lesen `ctx.params` ohne Null-Prüfung, da Standardwerte immer zuerst angewendet werden. -Das Muster-Matching in Richtlinien verwendet geparste Befehls-Token (argv), keine rohe Zeichenkettenübereinstimmung. Dies verhindert Umgehungsversuche durch Shell-Operator-Injection (z. B. kann ein Muster für `sudo systemctl status *` nicht durch Anhängen von `; rm -rf /` an den Befehl umgangen werden). +Das Muster-Matching innerhalb von Richtlinien verwendet geparste Befehlstokens (argv) statt rohem String-Matching. Dadurch werden Umgehungsversuche 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). --- ## Benutzerdefinierte Richtlinien -`src/hooks/custom-hooks-registry.ts` implementiert eine auf `globalThis` basierende Registry: +`src/hooks/custom-hooks-registry.ts` implementiert eine `globalThis`-basierte Registry: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -227,23 +227,23 @@ export function clearCustomHooks(): void { ... } // used in tests `src/hooks/custom-hooks-loader.ts` lädt die Richtliniendatei des Benutzers: -1. `customPoliciesPath` aus der Konfiguration lesen; überspringen, falls nicht vorhanden. -2. Zum absoluten Pfad auflösen; prüfen, ob die Datei existiert. -3. Alle `from "failproofai"`-Importe in den tatsächlichen dist-Pfad umschreiben, damit `customPolicies` zur gleichen `globalThis`-Registry aufgelöst wird. +1. `customPoliciesPath` aus der Konfiguration lesen; überspringen, wenn nicht vorhanden. +2. Auf absoluten Pfad auflösen; prüfen, ob die Datei existiert. +3. Alle `from "failproofai"`-Importe zum tatsächlichen dist-Pfad umschreiben, damit `customPolicies` in dieselbe `globalThis`-Registry aufgelöst wird. 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. +7. Alle temporären Dateien in einem `finally`-Block aufräumen. 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. Eingebaute Richtlinien sind davon nicht betroffen. -Benutzerdefinierte Richtlinien werden nach allen eingebauten Richtlinien ausgewertet. Ein `deny` einer benutzerdefinierten Richtlinie unterbricht weiterhin die Auswertung weiterer benutzerdefinierter Richtlinien (aber alle eingebauten wurden zu diesem Zeitpunkt bereits ausgeführt). +Benutzerdefinierte Richtlinien werden nach allen eingebauten Richtlinien ausgewertet. Ein `deny` einer benutzerdefinierten Richtlinie unterbricht zwar weitere benutzerdefinierte Richtlinien (alle eingebauten wurden zu diesem Zeitpunkt jedoch 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 } ``` -Eine Zeile pro Richtlinie, die eine Nicht-allow-Entscheidung getroffen hat. Allow-Entscheidungen werden nicht protokolliert (um die Dateigröße gering zu halten). +Eine Zeile pro Richtlinie, die eine Nicht-Erlauben-Entscheidung getroffen hat. Erlauben-Entscheidungen werden nicht protokolliert (um die Datei klein zu halten). --- @@ -281,21 +281,21 @@ app/ get-hook-activity.ts ← Aktivitätsprotokoll paginieren/durchsuchen install-hooks-web.ts ← Hooks über den Browser installieren/entfernen api/ - download/[project]/[session]/route.ts ← Sitzung als ZIP/JSONL exportieren + download/[project]/[session]/route.ts ← Sitzungsexport pro CLI (JSONL oder JSON) ``` **Datenfluss:** -- Seitenkomponenten rufen `lib/projects.ts` und `lib/log-entries.ts` auf, um Projekt- und 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 Zeitachse 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 Lesevorgänge). +- Die Richtlinienseite verwendet Server Actions für alle Mutationen (Umschalten, Parameteraktualisierung, Installieren/Entfernen). +- Der Sitzungs-Viewer parst Claudes JSONL-Transkriptformat und rendert eine Zeitleiste mit Nachrichten und Tool-Aufrufen. **Wesentliche Designentscheidungen:** - Keine Datenbank – der gesamte persistente Zustand liegt 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-Schalter, Aktivitätssuche, Log-Viewer). +- React Server Components für Leseseiten – schnelleres initiales Laden, kein Client-Bundle für Datenabruf. +- Client-Komponenten nur dort, wo Interaktivität benötigt wird (Richtlinien-Umschalter, Aktivitätssuche, Log-Viewer). --- @@ -304,29 +304,29 @@ app/ ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # CLI-Router (Hook / Dashboard / Install / etc.) +│ └── failproofai.mjs # CLI-Router (hook / dashboard / install / etc.) ├── src/hooks/ │ ├── handler.ts # Hook-Ereignis-Pipeline │ ├── builtin-policies.ts # 26 Richtliniendefinitionen -│ ├── policy-evaluator.ts # Richtlinienausführungs-Engine +│ ├── policy-evaluator.ts # Richtlinien-Ausführungsengine │ ├── policy-registry.ts # Richtlinienregistrierung und -suche │ ├── policy-types.ts # TypeScript-Interfaces │ ├── hooks-config.ts # Konfigurationsladen mit mehreren Geltungsbereichen │ ├── custom-hooks-registry.ts # globalThis-basierte Hook-Registry │ ├── custom-hooks-loader.ts # ESM-Loader für benutzerdefinierte JS-Hooks -│ ├── manager.ts # Install-, Entfernen- und Listen-Operationen +│ ├── manager.ts # Installieren / Entfernen / Auflisten │ ├── install-prompt.ts # Interaktive Richtlinienauswahl-Eingabeaufforderung │ ├── hook-logger.ts # Protokollierung in hook.log -│ ├── hook-activity-store.ts # Aktivitäten in hook-activity.jsonl speichern +│ ├── hook-activity-store.ts # Aktivität in hook-activity.jsonl persistieren │ └── llm-client.ts # LLM-API-Client (für KI-gestützte Richtlinien) ├── app/ # Next.js-Dashboard (Seiten + Server Actions) -├── lib/ # Gemeinsam genutzte Hilfsfunktionen +├── 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/ # Gemeinsam genutzte React-UI-Komponenten -├── contexts/ # React-Kontext-Provider (Theme, Auto-Refresh, Telemetrie) +├── contexts/ # React-Context-Provider (Theme, Auto-Refresh, Telemetrie) ├── examples/ # Beispieldateien 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 3337078a..9afc0f69 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 Agenten-Fehler abfangen" +description: "Alle 39 integrierten Richtlinien, die häufige Agent-Fehlermuster abfangen" icon: shield --- -failproofai wird mit 39 integrierten Richtlinien ausgeliefert, die häufige Agenten-Fehler 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 stoppt. +failproofai wird mit 39 integrierten Richtlinien ausgeliefert, die häufige Agent-Fehlermuster 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. --- @@ -15,25 +15,25 @@ 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 | -| [Infra-Befehle](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | 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 | | [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 | | [Datenbank](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse | | [Warnungen](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | -| [Paketverwaltung](#package-managers) | prefer-package-manager | PreToolUse | +| [Paketmanager](#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 | -- **`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 diese sieht. +- **`block-`** — verhindert, dass der Agent weiter fortfährt. +- **`warn-`** — gibt dem Agenten zusätzlichen Kontext zur Selbstkorrektur. +- **`sanitize-`** — bereinigt sensible Daten aus der Tool-Ausgabe, bevor der Agent sie sieht. -### Namespaces +### Namensräume -Jede Richtlinie befindet sich in einem `/`-Slot. Integrierte Richtlinien gehören zum Namespace **`exospherehost/`** — zum Beispiel `exospherehost/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 Namensraum **`exospherehost/`** — zum Beispiel `exospherehost/sanitize-jwt`. Der Namensraum verhindert Kollisionen, wenn Sie zusätzlich benutzerdefinierte oder Drittanbieter-Richtlinien mit ähnlichen Kurznamen laden. -In Ihrer Konfiguration können Sie eine integrierte Richtlinie entweder über ihren Kurznamen oder ihren qualifizierten Namen referenzieren; beide Formen verweisen auf dieselbe Richtlinie: +In Ihrer Konfiguration können Sie eine integrierte Richtlinie entweder über ihren Kurznamen oder ihren vollqualifizierten Namen referenzieren; beide Formen verweisen auf dieselbe Richtlinie: ```json { @@ -44,33 +44,33 @@ In Ihrer Konfiguration können Sie eine integrierte Richtlinie entweder über ih } ``` -Wenn ein Name kein `/` enthält, behandelt failproofai ihn als zum Standard-Namespace `exospherehost` gehörend. Namen, die bereits ein `/` enthalten (z.B. `myorg/foo`, `custom/my-hook`), werden unverändert übernommen. -- **`require-`** — blockiert das Stop-Ereignis, bis Bedingungen erfüllt sind. +Wenn ein Name kein `/` enthält, behandelt failproofai ihn als zum Standard-Namensraum `exospherehost` 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 umsetzbare Hinweise, ohne den Richtliniencode zu ändern. Funktioniert mit integrierten, benutzerdefinierten und konventionellen 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 bietet umsetzbare Anleitung, ohne den Richtliniencode zu ändern. Funktioniert mit integrierten, benutzerdefinierten und konventionsbasierten Richtlinien. Weitere Details unter [Konfiguration → hint](/de/configuration#hint-cross-cutting). --- ## Gefährliche Befehle -Verhindert, dass Agenten Operationen ausführen, die schwer rückgängig zu machen sind oder das Host-System beschädigen könnten. +Verhindert, dass Agenten Operationen ausführen, die schwer rückgängig zu machen sind oder das Hostsystem beschädigen könnten. ### `block-sudo` **Ereignis:** PreToolUse (Bash) **Standard:** Verweigert jeden `sudo`-Befehl. -Blockiert Aufrufe, die das Schlüsselwort `sudo` enthalten. Der Pattern-Abgleich erfolgt auf geparsten Befehls-Tokens, nicht auf dem rohen String, um Umgehungsversuche über Shell-Operator-Injection zu verhindern. +Blockiert Aufrufe, die das Schlüsselwort `sudo` enthalten. Der Musterabgleich erfolgt auf geparsten Befehls-Tokens, nicht auf dem Rohstring, um Umgehungsversuche durch Shell-Operator-Injection zu verhindern. **Parameter:** | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Exakte Befehlspräfixe, die erlaubt sind. Jeder Eintrag wird gegen die geparsten argv-Tokens abgeglichen. | +| `allowPatterns` | `string[]` | `[]` | Genaue Befehlspräfixe, die erlaubt sind. Jeder Eintrag wird gegen die geparsten argv-Tokens abgeglichen. | **Beispiel:** @@ -87,7 +87,7 @@ Blockiert Aufrufe, die das Schlüsselwort `sudo` enthalten. Der Pattern-Abgleich 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 rohen Befehls-String. Dies verhindert Umgehungsversuche über angehängte Shell-Operatoren (z.B. stimmt `sudo systemctl status x; rm -rf /` nicht mit `sudo systemctl status *` überein). +Muster werden gegen geparste Tokens abgeglichen, nicht gegen den Rohbefehlsstring. Dies verhindert Umgehungsversuche durch angehängte Shell-Operatoren (z. B. passt `sudo systemctl status x; rm -rf /` nicht auf `sudo systemctl status *`). --- @@ -101,7 +101,7 @@ Muster werden gegen geparste Tokens abgeglichen, nicht gegen den rohen Befehls-S | 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. --- -## Infra-Befehle +## Infrastrukturbefehle -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 gestört, es sei denn, Sie aktivieren die Richtlinie. Wenn aktiviert, wird jeder Aufruf der übereinstimmenden CLI verweigert, es sei denn, der Befehl stimmt mit einem Eintrag in `allowPatterns` überein. +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, sofern die Richtlinie nicht aktiviert ist. Wenn aktiviert, wird jeder Aufruf der entsprechenden CLI verweigert, es sei denn, der Befehl entspricht einem Eintrag in `allowPatterns`. -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 abgewiesen, um Injection-Umgehungen zu verhindern. +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-Umgehungen 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`-(OpenTofu)-Aufruf. +**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`-(Google Cloud)-CLI-Aufruf. +**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`-(Azure)-CLI-Aufruf. +**Standard:** Verweigert jeden `az`- (Azure) CLI-Aufruf. **Parameter:** @@ -305,7 +305,7 @@ 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 failproofai's eigenem `require-ci-green-before-stop`). +Nur-Lese-`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`). **Parameter:** @@ -329,7 +329,7 @@ Schreibgeschützte `gh`-Unterbefehle wie `gh pr view`, `gh pr list`, `gh run lis ## Geheimnisse (Sanitizer) -Verhindert, dass Agenten Anmeldedaten in ihren Kontext oder ihre Ausgabe lecken. Sanitizer-Richtlinien werden bei **PostToolUse**-Ereignissen ausgelöst. Wenn Claude einen Bash-Befehl ausführt, eine Datei liest oder ein beliebiges 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 zurückgegeben wird. +Verhindert, dass Agenten Zugangsdaten 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 beliebiges 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 deny-Entscheidung zurück, die verhindert, dass die Ausgabe zurückgegeben wird. ### `sanitize-jwt` @@ -343,7 +343,7 @@ Keine Parameter. ### `sanitize-api-keys` **Ereignis:** PostToolUse (alle Tools) -**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`). +**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:** @@ -371,7 +371,7 @@ Keine Parameter. ### `sanitize-connection-strings` **Ereignis:** PostToolUse (alle Tools) -**Standard:** Schwärzt Datenbankverbindungsstrings mit eingebetteten Anmeldedaten (z.B. `postgresql://user:password@host/db`). +**Standard:** Schwärzt Datenbankverbindungsstrings mit eingebetteten Zugangsdaten (z. B. `postgresql://user:password@host/db`). Keine Parameter. @@ -421,18 +421,18 @@ Keine Parameter. ## Dateizugriff -Hält Agenten innerhalb der Projektgrenzen und fern von sensiblen Dateien. +Hält Agenten innerhalb der Projektgrenzen und weg von sensiblen 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` (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 wenn Claude per `cd` in ein Unterverzeichnis wechselt. +**Standard:** Verweigert das Lesen von Dateien außerhalb des Projektstammverzeichnisses. 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 Projektstammverzeichnisses anstelle des aktuellen `cwd` bedeutet, dass die Grenze stabil bleibt, auch wenn Claude in ein Unterverzeichnis wechselt. **Parameter:** | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Absolute Pfadpräfixe, die erlaubt sind, auch wenn sie außerhalb des Projektstamms liegen. | +| `allowPaths` | `string[]` | `[]` | Absolute Pfadpräfixe, die auch außerhalb des Projektstammverzeichnisses erlaubt sind. | **Beispiel:** @@ -451,13 +451,13 @@ Hält Agenten innerhalb der Projektgrenzen und fern 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:** | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | Zusätzliche Dateinamen-Muster (Glob-Stil) zum Blockieren. | +| `additionalPatterns` | `string[]` | `[]` | Zusätzliche Dateinamensmuster (Glob-Stil), die blockiert werden sollen. | **Beispiel:** @@ -486,7 +486,7 @@ Verhindert versehentliche Pushes, Force-Pushes und Branch-Fehler, die schwer rü | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Branch-Namen, auf die nicht direkt gepusht werden darf. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Branch-Namen, in die nicht direkt gepusht werden darf. | **Beispiel:** @@ -501,7 +501,7 @@ Verhindert versehentliche Pushes, Force-Pushes und Branch-Fehler, die schwer rü ``` -Um das Pushen auf alle Branches zu erlauben (wodurch diese Richtlinie effektiv deaktiviert wird, ohne sie aus `enabledPolicies` zu entfernen), setzen Sie `protectedBranches: []`. +Um das Pushen in alle Branches zu erlauben (diese Richtlinie effektiv zu deaktivieren, ohne sie aus `enabledPolicies` zu entfernen), setzen Sie `protectedBranches: []`. --- @@ -509,13 +509,13 @@ Um das Pushen auf alle Branches zu erlauben (wodurch diese Richtlinie effektiv d ### `block-work-on-main` **Ereignis:** PreToolUse (Bash) -**Standard:** Verweigert das direkte Auschecken von `main`- oder `master`-Branches. +**Standard:** Verweigert `git commit`, `git merge`, `git rebase` und `git cherry-pick`, wenn der Working Tree auf `main` oder `master` liegt. Branch-Erstellung und -Wechsel (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) sind nicht betroffen. **Parameter:** | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Branch-Namen, die nicht direkt ausgecheckt werden dürfen. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Branch-Namen, auf denen commit/merge/rebase/cherry-pick verweigert wird. | --- @@ -541,7 +541,7 @@ Keine richtlinienspezifischen Parameter. Verwenden Sie das übergreifende [`hint ### `warn-git-amend` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, beim Ausführen von `git commit --amend` vorsichtig vorzugehen. Blockiert den Befehl nicht. +**Standard:** Weist Claude an, vorsichtig vorzugehen, wenn `git commit --amend` ausgeführt wird. Blockiert den Befehl nicht. Keine Parameter. @@ -559,7 +559,7 @@ Keine Parameter. ### `warn-all-files-staged` **Ereignis:** PreToolUse (Bash) -**Standard:** Weist Claude an, zu überprüfen, was es staged, wenn es `git add -A` oder `git add .` ausführt. Blockiert den Befehl nicht. +**Standard:** Weist Claude an, zu überprüfen, was es staged, wenn `git add -A` oder `git add .` ausgeführt wird. Blockiert den Befehl nicht. Keine Parameter. @@ -572,7 +572,7 @@ Fängt destruktive SQL-Operationen ab, bevor sie gegen Ihre Datenbank ausgeführ ### `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 eine `WHERE`-Klausel enthält. +**Standard:** Weist Claude an, zu bestätigen, bevor SQL mit `DROP TABLE`, `DROP DATABASE` oder `DELETE` ohne `WHERE`-Klausel ausgeführt wird. Keine Parameter. @@ -594,7 +594,7 @@ 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 geschrieben werden, die größer als 1024 KB sind. +**Standard:** Weist Claude an, zu bestätigen, bevor Dateien größer als 1024 KB geschrieben werden. **Parameter:** @@ -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 unter 1024. +Der Hook-Handler erzwingt ein 1-MB-stdin-Limit für Payloads. Um diese Richtlinie mit kleinen Inhalten zu testen, setzen Sie `thresholdKb` auf einen Wert deutlich unter 1024. --- @@ -647,7 +647,7 @@ Keine Parameter. --- -## Paketverwaltung +## Paketmanager Legt fest, welche Paketmanager der Agent verwenden darf. @@ -660,10 +660,10 @@ Erkennt: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, po | 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']`). | +| `allowed` | string[] | `[]` | Erlaubte Paketmanager-Namen. Jeder erkannte Manager, der nicht in dieser Liste steht, wird blockiert. Bei leerer Liste ist die Richtlinie wirkungslos. | +| `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 anzufügen, die nicht in dieser Liste enthalten sind. +Die integrierte Blockierliste 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. **Beispielkonfiguration:** @@ -679,7 +679,7 @@ Die integrierte Blockliste umfasst: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, } ``` -Mit dieser Konfiguration werden sowohl `pip install flask` als auch `pdm install flask` mit einer Meldung verweigert, 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 sowohl `pip install flask` als auch `pdm install flask` 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. --- @@ -690,7 +690,7 @@ Erkennt, wenn Agenten feststecken oder sich unerwartet verhalten. ### `warn-repeated-tool-calls` **Ereignis:** PreToolUse (alle Tools) -**Standard:** Weist Claude an, zu überdenken, wenn dasselbe Tool 3+ Mal mit identischen Parametern aufgerufen wird — ein häufiges Anzeichen dafür, dass der Agent in einer Schleife feststeckt. +**Standard:** Weist Claude an, zu überdenken, wenn dasselbe Tool 3 oder mehr Male mit identischen Parametern aufgerufen wird — ein häufiges Zeichen dafür, dass der Agent in einer Schleife feststeckt. Keine Parameter. @@ -698,14 +698,14 @@ Keine Parameter. ## Workflow -Erzwingt einen disziplinierten End-of-Session-Workflow. Diese Richtlinien werden beim **Stop**-Ereignis ausgelöst und verhindern, dass Claude stoppt, 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 schließt kurz). +Erzwingt einen disziplinierten End-of-Session-Workflow. Diese Richtlinien werden beim **Stop**-Ereignis ausgelöst und verhindern, dass Claude 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 short-circuits). -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 Informationsmeldung, 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. ### `require-commit-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Stoppen, wenn es nicht committete Änderungen gibt (geänderte, gestagte oder nicht verfolgte Dateien). Gibt eine Informationsmeldung zurück, wenn das Arbeitsverzeichnis sauber ist. +**Standard:** Verweigert das Anhalten, wenn es nicht committete Änderungen gibt (geänderte, gestagete oder nicht verfolgte Dateien). Gibt eine informative Nachricht zurück, wenn das Arbeitsverzeichnis sauber ist. Keine Parameter. @@ -714,7 +714,7 @@ Keine Parameter. ### `require-push-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Stoppen, wenn es nicht gepushte 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. Schlägt fehl-offen, wenn kein Remote konfiguriert ist. +**Standard:** Verweigert das Anhalten, wenn es nicht gepushte 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. Fail-open, wenn kein Remote konfiguriert ist. **Parameter:** @@ -739,14 +739,13 @@ Keine Parameter. ### `require-pr-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Stoppen, 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 (die Arbeit wurde ausgeliefert) und die Meldung 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 wurde ausgeliefert) und die Nachricht weist darauf hin, 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. -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 fail-open und berichtet den Grund an Claude. +Diese Richtlinie erfordert die Installation und Authentifizierung von [GitHub CLI](https://cli.github.com/) (`gh`). +Führen Sie `gh auth login` mit einem Personal Access Token aus, das den `repo`-Scope für Lesezugriff auf Pull Requests hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, ist die Richtlinie fail-open und meldet den Grund an Claude. --- @@ -754,24 +753,21 @@ Pull Requests hat. Wenn `gh` nicht installiert oder nicht authentifiziert ist, s ### `require-no-conflicts-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Stoppen, wenn der aktuelle Branch nicht sauber in den Basis-Branch gemergt werden kann. Die Richtlinie bestätigt zunächst, dass ein `OPEN`-PR auf GitHub für den Branch existiert — ohne einen gibt es kein Merge-Ziel zum Erzwingen, sodass die gesamte Richtlinie auf allow kurz schließt. Sobald ein `OPEN`-PR bestätigt ist, laufen zwei unabhängige Prüfungen: +**Standard:** Verweigert das Anhalten, wenn der aktuelle Branch nicht sauber in den Basis-Branch gemergt werden kann. Die Richtlinie bestätigt zunächst, dass es einen `OPEN`-PR auf GitHub für den Branch gibt — ohne einen solchen gibt es kein Merge-Ziel zum Durchsetzen, sodass die gesamte Richtlinie zu allow short-circuits. Sobald ein `OPEN`-PR bestätigt ist, werden zwei unabhängige Prüfungen durchgeführt: -1. **Lokal** — `git merge-tree --write-tree --name-only origin/ HEAD`. Bei Konflikt nennt die Verweigerungsmeldung die konfliktierenden Dateien, sodass Claude genau weiß, was aufgelöst werden muss. -2. **GitHub** — verwendet das bereits in der Vorprüfung abgerufene `gh pr view --json mergeable,state`-Ergebnis erneut. Fängt Konflikte ab, die ein veraltetes lokales `origin/` verpassen würde (z.B. wenn jemand seit dem letzten Fetch einen konfliktierenden PR auf `main` gemergt hat). Ein `CONFLICTING`-Ergebnis verweigert. Ein `UNKNOWN`-Ergebnis verweigert ebenfalls und weist Claude an, ~10 Sekunden zu warten und erneut zu prüfen, bevor erneut versucht wird zu stoppen — dies verhindert falsche Negative, während GitHub neu berechnet. +1. **Lokal** — `git merge-tree --write-tree --name-only origin/ HEAD`. Bei einem Konflikt nennt die deny-Nachricht die betroffenen Dateien, sodass Claude genau weiß, was zu beheben ist. +2. **GitHub** — verwendet das bereits in der Vorprüfung abgerufene Ergebnis von `gh pr view --json mergeable,state`. Erfasst Konflikte, die ein veralteter lokaler `origin/` verpassen würde (z. B. wenn jemand einen konfliktierenden PR auf `main` gelandet hat seit dem letzten Fetch). Ein `CONFLICTING`-Ergebnis verweigert. Ein `UNKNOWN`-Ergebnis verweigert ebenfalls und weist Claude an, ~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. -Überspringt vollständig (erlaubt), wenn: `gh` nicht installiert ist, kein PR für den Branch existiert, der Status des PR nicht `OPEN` ist (z.B. `MERGED`, `CLOSED`), oder `gh pr view` nicht parsbare Ausgabe zurückgibt. Schlägt auch fail-open, wenn `origin/` lokal fehlt oder wenn keine Commits vor der Basis vorhanden sind — diese Layer-1-Durchfälle konsultieren dennoch die gecachte PR-Mergefähigkeit, bevor sie erlauben. +Wird vollständig übersprungen (erlaubt), wenn: `gh` nicht installiert ist, kein PR für den Branch existiert, der Status des PR nicht `OPEN` ist (z. B. `MERGED`, `CLOSED`) oder `gh pr view` nicht parsierbare Ausgabe zurückgibt. Fail-open auch wenn `origin/` lokal fehlt oder wenn keine Commits vor der Basis vorhanden sind — diese Layer-1-Fallbacks konsultieren noch die gecachte PR-Mergierbarkeit, bevor sie erlauben. **Parameter:** | Parameter | Typ | Standard | Beschreibung | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Basis-Branch, gegen den auf Konflikte geprüft werden soll. | +| `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 irgendeine Konfliktprüfung ausgeführt wird — ohne `gh` schließt die Richtlinie -auf 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 existiert, bevor eine Konfliktprüfung durchgeführt wird — ohne `gh` short-circuits die Richtlinie zu allow. Führen Sie `gh auth login` mit einem Personal Access Token aus, das den `repo`-Scope für Lesezugriff auf Pull Requests hat. --- @@ -779,14 +775,13 @@ Lesezugriff auf Pull Requests hat. ### `require-ci-green-before-stop` **Ereignis:** Stop -**Standard:** Verweigert das Stoppen, wenn CI-Prüfungen auf dem aktuellen Branch fehlschlagen oder noch laufen. Prüft sowohl GitHub Actions-Workflow-Runs als auch Drittanbieter-Bot-Prüfungen (z.B. CodeRabbit, SonarCloud, Codecov). Behandelt `skipped`- und `cancelled`-Ergebnisse als Erfolg. Gibt eine Informationsmeldung zurück, wenn alle Prüfungen bestehen. +**Standard:** Verweigert das Anhalten, wenn CI-Prüfungen auf dem aktuellen Branch fehlschlagen oder noch laufen. Prüft sowohl GitHub Actions-Workflow-Runs als auch Drittanbieter-Bot-Prüfungen (z. B. CodeRabbit, SonarCloud, Codecov). Behandelt `skipped`- und `cancelled`-Ergebnisse als Erfolg. 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. -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 fail-open und berichtet den Grund an Claude. +Diese Richtlinie erfordert die Installation und Authentifizierung von [GitHub CLI](https://cli.github.com/) (`gh`). +Führen Sie `gh auth login` mit einem Personal Access Token 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, ist die Richtlinie fail-open und meldet den Grund an Claude. --- @@ -795,7 +790,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 schalten Sie sie im Dashboard-Tab „Policies" aus. +Entfernen Sie eine bestimmte Richtlinie aus `enabledPolicies` in Ihrer Konfiguration, oder deaktivieren Sie sie im Dashboard-Tab „Policies". ```json { diff --git a/docs/de/configuration.mdx b/docs/de/configuration.mdx index 3d30db77..bdc721e9 100644 --- a/docs/de/configuration.mdx +++ b/docs/de/configuration.mdx @@ -4,25 +4,25 @@ description: "Konfigurationsdateiformat, Drei-Scope-System und Zusammenführungs icon: gear --- -failproofai verwendet JSON-Konfigurationsdateien, um zu steuern, welche Richtlinien aktiv sind, wie sie sich verhalten und von wo benutzerdefinierte Richtlinien geladen werden. Die Konfiguration ist so gestaltet, dass sie einfach mit dem 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 von wo benutzerdefinierte Richtlinien geladen werden. Die Konfiguration ist so gestaltet, dass sie einfach mit dem Team geteilt werden kann – 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 der Versionsverwaltung eingecheckt | -| **local** | `.failproofai/policies-config.local.json` | Persönliche, repository-spezifische Überschreibungen, per gitignore ausgeschlossen | -| **global** | `~/.failproofai/policies-config.json` | Benutzerweite Standardeinstellungen für alle Projekte | +| Scope | Dateipfad | Zweck | +|-------|-----------|-------| +| **project** | `.failproofai/policies-config.json` | Repository-spezifische Einstellungen, in die Versionskontrolle eingecheckt | +| **local** | `.failproofai/policies-config.local.json` | Persönliche repository-spezifische Überschreibungen, per .gitignore ausgeschlossen | +| **global** | `~/.failproofai/policies-config.json` | Benutzerweite Standardwerte für alle Projekte | Wenn failproofai ein Hook-Ereignis empfängt, lädt und führt es alle drei Dateien zusammen, die für das aktuelle Arbeitsverzeichnis vorhanden sind. ### 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 einer beliebigen 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 Zusammenführen von Werten innerhalb der Parameter einer Richtlinie. +**`policyParams`** – der erste Scope, der Parameter für eine bestimmte Richtlinie definiert, gewinnt vollständig. Es gibt keine tiefe Zusammenführung von Werten innerhalb der Parameter einer Richtlinie. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -46,12 +46,12 @@ project: (kein block-sudo-Eintrag) local: (kein block-sudo-Eintrag) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← Fallback auf global +resolved: { allowPatterns: ["sudo systemctl status"] } ← greift auf global zurück ``` -**`customPoliciesPath`** – der erste Bereich, der ihn definiert, gewinnt. +**`customPoliciesPath`** – der erste Scope, der ihn definiert, gewinnt. -**`llm`** – der erste Bereich, der ihn definiert, gewinnt. +**`llm`** – der erste Scope, der ihn definiert, gewinnt. --- @@ -102,27 +102,27 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← Fallback auf global Typ: `string[]` -Liste der zu aktivierenden Richtliniennamen. Die Namen müssen exakt mit den von `failproofai policies` angezeigten Richtlinienbezeichnern übereinstimmen. Die vollständige Liste finden Sie unter [Integrierte Richtlinien](/de/built-in-policies). +Liste der zu aktivierenden Richtliniennamen. Die Namen müssen exakt mit den Richtlinien-Identifikatoren übereinstimmen, die von `failproofai policies` angezeigt werden. Die vollständige Liste finden Sie unter [Integrierte Richtlinien](/de/built-in-policies). -Richtlinien, die nicht in `enabledPolicies` aufgeführt sind, sind inaktiv, auch wenn sie Einträge in `policyParams` haben. +Richtlinien, die nicht in `enabledPolicies` aufgeführt sind, sind inaktiv – auch wenn sie Einträge in `policyParams` haben. ### `policyParams` Typ: `Record>` -Richtlinienspezifische Parameterüberschreibungen. Der äußere Schlüssel ist der Richtlinienname; die inneren Schlüssel sind richtlinienspezifisch. Jede Richtlinie dokumentiert ihre verfügbaren Parameter unter [Integrierte Richtlinien](/de/built-in-policies). +Parameterschreibungen pro Richtlinie. Der äußere Schlüssel ist der Richtlinienname; die inneren Schlüssel sind richtlinienspezifisch. Jede Richtlinie dokumentiert ihre verfügbaren Parameter unter [Integrierte Richtlinien](/de/built-in-policies). -Wenn eine Richtlinie Parameter hat, Sie diese aber nicht angeben, werden die eingebauten Standardwerte der Richtlinie verwendet. Benutzer, die `policyParams` überhaupt nicht konfigurieren, erhalten 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 im Parameterblock einer Richtlinie werden zur Zeit des Hook-Auslösens stillschweigend ignoriert, aber als Warnungen markiert, wenn Sie `failproofai policies` ausführen. +Unbekannte Schlüssel innerhalb des Parameterblocks einer Richtlinie werden zum Zeitpunkt des Hook-Aufrufs stillschweigend ignoriert, aber als Warnungen angezeigt, wenn Sie `failproofai policies` ausführen. #### `hint` (übergreifend) Typ: `string` (optional) -Eine Nachricht, die an den Grund angehängt wird, wenn eine Richtlinie `deny` oder `instruct` zurückgibt. Verwenden Sie ihn, um Claude handlungsrelevante Hinweise zu geben, ohne die Richtlinie selbst zu ändern. +Eine Nachricht, die dem Grund angefügt wird, wenn eine Richtlinie `deny` oder `instruct` zurückgibt. Verwenden Sie sie, um Claude handlungsrelevante Hinweise zu geben, ohne die Richtlinie selbst zu ändern. -Funktioniert mit jedem Richtlinientyp – eingebaut, benutzerdefiniert (`custom/`), Projektkonvention (`.failproofai-project/`) oder Benutzerkonvention (`.failproofai-user/`). +Funktioniert mit jedem Richtlinientyp – integriert, benutzerdefiniert (`custom/`), Projektkonvention (`.failproofai-project/`) oder Benutzerkonvention (`.failproofai-user/`). ```json { @@ -141,7 +141,7 @@ Funktioniert mit jedem Richtlinientyp – eingebaut, benutzerdefiniert (`custom/ } ``` -Wenn `block-force-push` ablehnt, sieht Claude: *„Force-pushing is blocked. Try creating a fresh branch instead."* +Wenn `block-force-push` ablehnt, sieht Claude: *„Force-Pushing ist blockiert. Try creating a fresh branch instead."* Nicht-String-Werte und leere Zeichenketten werden stillschweigend ignoriert. Wenn `hint` nicht gesetzt ist, bleibt das Verhalten unverändert (abwärtskompatibel). @@ -149,24 +149,24 @@ Nicht-String-Werte und leere Zeichenketten werden stillschweigend ignoriert. Wen 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). +Pfad zu einer JavaScript-Datei mit benutzerdefinierten Hook-Richtlinien. Dieser wird automatisch durch `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. Einzelheiten zur Erstellung finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies). +Die Datei wird bei jedem Hook-Ereignis neu geladen – es gibt kein Caching. Details zum Erstellen benutzerdefinierter Richtlinien 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/` | Mit dem Team über Versionskontrolle 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 auf `*policies.{js,mjs,ts}` passen (z. B. `security-policies.mjs`, `workflow-policies.js`). Andere Dateien im Verzeichnis werden ignoriert. -**Keine Konfiguration erforderlich:** Konventionsrichtlinien benötigen keine Einträge in `policies-config.json`. Legen Sie einfach Dateien in das Verzeichnis und sie werden beim nächsten Hook-Ereignis aufgegriffen. +**Keine Konfiguration erforderlich:** Konventionsrichtlinien erfordern keine Einträge in `policies-config.json`. Legen Sie einfach Dateien in das Verzeichnis, und sie werden beim nächsten Hook-Ereignis berücksichtigt. -**Gemeinsames Laden:** Sowohl das Projekt- als auch das Benutzer-Konventionsverzeichnis werden durchsucht. Alle passenden Dateien aus beiden Ebenen werden geladen (im Gegensatz zu `customPoliciesPath`, das das Prinzip „erster Bereich gewinnt" verwendet). +**Gemeinsames Laden:** Sowohl das Projekt- als auch das Benutzer-Konventionsverzeichnis werden durchsucht. Alle übereinstimmenden Dateien aus beiden Ebenen werden geladen (im Gegensatz zu `customPoliciesPath`, das nach dem Prinzip „erster Scope gewinnt" arbeitet). Weitere Details und Beispiele finden Sie unter [Benutzerdefinierte Richtlinien](/de/custom-policies). @@ -189,34 +189,42 @@ LLM-Client-Konfiguration für Richtlinien, die KI-Aufrufe durchführen. Für die ## Konfiguration über die CLI verwalten -Die Befehle `policies --install` und `policies --uninstall` schreiben in die Hook-Einstellungsdatei Ihrer Agenten-CLI (die Hook-Einstiegspunkte), während `policies-config.json` die Datei ist, die Sie direkt verwalten. Beides ist 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. Beides ist voneinander getrennt: -- **Agenten-CLI-Einstellungen** – weist den Agenten an, `failproofai --hook ` bei jeder Werkzeugnutzung aufzurufen: +- **Agenten-CLI-Einstellungen** — weist den Agenten an, bei jeder Werkzeugnutzung `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 Copilots OS-schlüsselbasierte `bash`/`powershell`-Befehlsfelder mit `timeoutSec`; die Datei enthält einen `version: 1`-Marker auf oberster Ebene. Die Unterstützung der Copilot CLI ist **Beta**, während wir das `events.jsonl`-Datensatzschema (das in der öffentlichen Dokumentation nicht spezifiziert ist) anhand weiterer realer Sitzungen überprüfen. -- **`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 für Copilot CLI ist **Beta**, während wir das `events.jsonl`-Eintragsschema (das die öffentliche Dokumentation nicht spezifiziert) anhand weiterer realer Sitzungen verifizieren. + - **Cursor Agent _(Beta)_**: `~/.cursor/hooks.json` (Benutzer), `/.cursor/hooks.json` (Projekt) — Cursor hat keinen `local`-Scope. Hook-Einträge verwenden die Claude-ähnliche Form `{type, command, timeout}` (ohne `bash`/`powershell`-Trennung), 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 normalisiert camelCase → PascalCase über `CURSOR_EVENT_MAP`, sodass vorhandene integrierte Richtlinien unverändert ausgelöst werden. Die Unterstützung für Cursor Agent ist **Beta**, während wir Cursors Transkript-On-Disk-Format (in der öffentlichen Dokumentation 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`-Scope. Anders als die anderen vier CLIs hat OpenCode **kein externes Hook-System für Befehle**: Es lädt In-Process-JS/TS-Plugins, die explizit über das `plugin: []`-Array in `opencode.json` registriert werden (Auto-Erkennung aus `.opencode/plugins/` ist **nicht** die Art, wie Plugins in opencode v1.14.33 geladen werden). Die Installation legt einen kleinen generierten Plugin-Shim ab, der das failproofai-Binary als Subprozess aufruft und die Claude-ähnliche JSON-Antwort des Binaries zurück in Plugin-Semantik übersetzt (`throw new Error()` für deny, `client.session.prompt(...)` für instruct, No-Op für allow). 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 versionsübergreifend und anhand weiterer realer Sitzungen verifizieren. Weitere Informationen finden Sie in der [OpenCode-Plugins-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 beim Start TypeScript-Erweiterungspakete; 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 normalisiert underscore_lower_snake_case → PascalCase über `PI_EVENT_MAP`, sodass vorhandene integrierte Richtlinien unverändert ausgelöst werden. Die Unterstützung für Pi ist **Beta**, während Pis Erweiterungs-API und das Sitzungsprotokoll-Layout sich 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 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 normalisiert über `GEMINI_TOOL_MAP`, sodass vorhandene integrierte Richtlinien unverändert ausgelöst werden. Der Richtlinien-Evaluator gibt Geminis flache `{decision: "deny", reason}`-Form aus (bevorzugt gemäß Geminis „Golden Rule" Exit-0-Vertrag), `{hookSpecificOutput: {hookEventName, additionalContext}}` für die Kontextinjektion 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 erweitern. Weitere Informationen finden Sie in der [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) -Übergeben Sie `--cli claude|codex|copilot`, um eine bestimmte Agenten-CLI anzusprechen (leerzeichen- oder wiederholungsgetrennt für eine beliebige Teilmenge): +Übergeben Sie `--cli claude|codex|copilot|cursor|opencode|pi|gemini`, um eine bestimmte Agenten-CLI anzusprechen (leerzeichen- oder wiederholungsgetrennt für eine beliebige Teilmenge): ```bash failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project -failproofai policies --install --cli claude codex copilot +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 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`): +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`): -- **Eine CLI erkannt** – wählt diese CLI automatisch ohne Rückfrage aus. -- **Mehrere CLIs erkannt** in einem interaktiven Terminal – zeigt eine Pfeiltasten-Einzelauswahl-Eingabeaufforderung: Wenn zwei CLIs vorhanden sind, lauten die Auswahlmöglichkeiten `Both`, ` only`, ` only`; bei drei CLIs wird die erste Option zu `All` (↑↓ zum Bewegen, Enter zum Auswählen, ^C zum Beenden). -- **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 keine Agenten-Binärdatei im PATH gefunden wurde; der Hook-Befehl wird trotzdem geschrieben und aktiviert sich, 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 Auswahlabfrage mit Pfeiltasten an, gruppiert in einen Abschnitt `Erkannt (N)` (mit einer zusammenfassenden Zeile `Für alle N erkannten installieren` und jeder erkannten CLI einzeln) sowie einen Abschnitt `Nicht installiert (M) · Hooks bereits einrichten` mit allen nicht erkannten unterstützten CLIs als Vorinstallationsoption (↑↓ zum Bewegen, Enter zur Auswahl, ^C zum Beenden). Der Deinstallationsablauf zeigt nur den Abschnitt „Erkannt". +- **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 dennoch geschrieben, sodass er aktiviert wird, sobald Sie eine CLI 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. +Sie können `policies-config.json` jederzeit direkt bearbeiten; Änderungen treten beim nächsten Hook-Ereignis sofort in Kraft – ein Neustart ist nicht erforderlich. --- -## Beispiel: Projektkonfiguration mit Team-Standardwerten +## Beispiel: Konfiguration auf Projektebene mit Team-Standardwerten Committen Sie `.failproofai/policies-config.json` in Ihr Repository: @@ -237,4 +245,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 Überschreibungen erstellen, ohne die Teamkollegen zu beeinflussen. \ No newline at end of file diff --git a/docs/de/dashboard.mdx b/docs/de/dashboard.mdx index acf8e188..e740fd3e 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 einsehen 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 Agents in Ihrer Abwesenheit getan haben. +Das failproofai-Dashboard ist eine lokale Webanwendung zur Überwachung deiner KI-Agentensitzungen und zur Verwaltung von Richtlinien. Sieh nach, was deine Agenten in deiner 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 aus dem Dateisystem – aus deinen Claude Code-Projektordnern und den failproofai-Konfigurationsdateien. Es werden keine Daten an einen Remote-Dienst geschrieben. --- @@ -24,14 +24,14 @@ Das Dashboard liest direkt aus dem Dateisystem – aus Ihren Claude Code Projekt ### Projekte -Listet alle Claude Code-, OpenAI Codex- und GitHub Copilot CLI _(Beta)_-Projekte auf, die auf Ihrem Rechner gefunden wurden. Claude-Projekte werden aus `~/.claude/projects/` ermittelt (oder dem über `CLAUDE_PROJECTS_PATH` festgelegten Pfad); Codex-Projekte werden durch das Durchsuchen aller Transkripte unter `~/.codex/sessions///
/*.jsonl` ermittelt und nach dem `cwd`-Feld des ersten Eintrags jeder Sitzung gruppiert; Copilot CLI-Projekte werden durch das Durchsuchen der jeweiligen `~/.copilot/session-state//workspace.yaml` ermittelt (konfigurierbar über `COPILOT_HOME`) und nach dem `cwd`-Feld gruppiert. Ein Projekt, das von mehreren CLIs verwendet wurde, erscheint als einzelne Zeile mit allen zugehörigen Badges. 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`. +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 deinem Rechner gefunden wurden. Claude-Projekte werden aus `~/.claude/projects/` ermittelt (oder dem Pfad, der über `CLAUDE_PROJECTS_PATH` gesetzt wurde); Codex-Projekte werden durch das Durchsuchen aller Transkripte unter `~/.codex/sessions///
/*.jsonl` und das Gruppieren anhand des `cwd`-Eintrags im ersten Datensatz jeder Sitzung gefunden; Copilot CLI-Projekte werden durch das Auslesen jeder `~/.copilot/session-state//workspace.yaml`-Datei (konfigurierbar über `COPILOT_HOME`) und das Gruppieren nach dem `cwd`-Feld ermittelt; Cursor Agent-Projekte werden durch das Durchsuchen sitzungsbezogener Metadaten unter `~/.cursor/agent-sessions//` (konfigurierbar über `CURSOR_HOME`, mit `conversations/` und `sessions/` als Fallback-Pfade) nach einem `cwd`-Skalar in `meta.json` / `session.json` / `workspace.yaml` gefunden; OpenCode-Projekte werden durch Abfragen der SQLite-Datenbank unter `~/.local/share/opencode/opencode.db` via `opencode db --format json` ermittelt (wir lesen die Tabellen `session` und `project` und gruppieren nach `project_id`); Pi-Projekte werden durch das Durchsuchen sitzungsbezogener JSONL-Transkripte unter `~/.pi/agent/sessions//_.jsonl` (konfigurierbar über `PI_SESSIONS_DIR`) und das Auslesen des `cwd`-Eintrags aus dem ersten Datensatz jeder Sitzung gefunden; Gemini CLI-Projekte werden durch das Durchsuchen von `~/.gemini/tmp//chats/session--.jsonl` (konfigurierbar über `GEMINI_SESSIONS_DIR`) und das Rekonstruieren des kanonischen cwd aus dem benachbarten `.project_root`-Textmarker ermittelt. Ein Projekt, das von mehreren CLIs genutzt wurde, erscheint als einzelne Zeile mit allen zugehörigen Badges. Verwende das **CLI**-Dropdown oberhalb der Tabelle, um nach einer bestimmten Agenten-CLI zu filtern; die URL speichert deine Auswahl als `?cli=claude|codex|copilot|cursor|opencode|pi|gemini`. Jedes Projekt zeigt: -- Projektname (abgeleitet vom Ordnerpfad) -- Ein CLI-Badge — `Claude Code` (orange), `OpenAI Codex` (lila) und/oder `GitHub Copilot` (blau) +- Projektname (abgeleitet aus dem Ordnerpfad) +- Ein CLI-Badge — `Claude Code` (orange), `OpenAI Codex` (lila), `GitHub Copilot` (blau), `Cursor Agent` (smaragd), `OpenCode` (bernstein), `Pi` (pink) und/oder `Gemini CLI` (himmelblau) - Datum der letzten Sitzungsaktivität -Klicken Sie auf ein Projekt, um seine Sitzungen anzuzeigen. +Klicke auf ein Projekt, um dessen Sitzungen anzuzeigen. ### Sitzungen @@ -41,38 +41,38 @@ 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 einzugrenzen. Sitzungen werden seitenweise angezeigt. +Verwende den Datumsbereichsfilter und die Sitzungs-ID-Suche, um die Liste einzugrenzen. Sitzungen werden seitenweise dargestellt. -Klicken Sie auf eine Sitzung, um den Sitzungs-Viewer zu öffnen. +Klicke auf eine Sitzung, um den Sitzungsbetrachter zu öffnen. -### Sitzungs-Viewer +### Sitzungsbetrachter -Der Sitzungs-Viewer beantwortet die zentrale Frage bei autonomen Agents: Was hat der Agent getan, und ist er auf Kurs geblieben? Ein CLI-Badge neben der Überschrift zeigt an, ob es sich bei der Sitzung um ein Claude Code- oder OpenAI Codex-Transkript handelt. Er zeigt eine Zeitleiste aller Ereignisse einer Sitzung: +Der Sitzungsbetrachter beantwortet die zentrale Frage bei autonomen Agenten: Was hat der Agent getan, und hat er sich an die Vorgaben 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 einen Zeitverlauf aller Ereignisse einer Sitzung: -- **Nachrichten** – Claudes Textantworten und Benutzer-Prompts -- **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 Nutzereingaben +- **Tool-Aufrufe** – Jedes Tool, das Claude aufgerufen hat, mit Eingabe und Ausgabe +- **Richtlinienaktivität** – Für jeden Tool-Aufruf: welche Richtlinien ausgelöst wurden und welche Entscheidung sie zurückgegeben haben Die Statistikleiste oben zeigt Sitzungsdauer, Gesamtanzahl der Tool-Aufrufe und eine Zusammenfassung der Hook-Entscheidungen (Anzahl von allow / deny / instruct). -Sie können die Sitzung als ZIP- oder JSONL-Datei über die Download-Schaltfläche exportieren. +Klicke auf die Schaltfläche **Logs herunterladen**, um die Sitzung zu exportieren. Bei Claude Code-, Codex-, Copilot-, Cursor-, Pi- und Gemini-Sitzungen erhältst du das originale JSONL-Transkript vom Datenträger byte-für-byte; bei OpenCode (dessen Sitzungen in SQLite statt auf der Festplatte gespeichert sind) erhältst du ein JSON-Dokument, das die zugrunde liegenden Tabellen `session` / `messages` / `parts` widerspiegelt. ### Richtlinien -Eine Seite mit zwei Tabs zur Verwaltung von Richtlinien und Einsicht der Aktivitäten. +Eine Seite mit zwei Tabs zur Verwaltung von Richtlinien und zur Einsicht in Aktivitäten. - - Einzelne Richtlinien mit einem Klick aktivieren oder deaktivieren (schreibt in `~/.failproofai/policies-config.json`) - - Eine Richtlinie aufklappen, um ihre Parameter zu konfigurieren (für Richtlinien, die `policyParams` unterstützen) - - Hooks für einen bestimmten Scope installieren oder entfernen - - Einen benutzerdefinierten Pfad für die Richtliniendatei festlegen + - Einzelne Richtlinien per Klick aktivieren oder deaktivieren (schreibt in `~/.failproofai/policies-config.json`) + - Eine Richtlinie erweitern, um ihre Parameter zu konfigurieren (für Richtlinien, die `policyParams` unterstützen) + - Hooks für einen bestimmten Geltungsbereich installieren oder entfernen + - Einen benutzerdefinierten Dateipfad für Richtlinien festlegen - - Vollständige, seitenweise Übersicht aller Hook-Ereignisse, die über alle Sitzungen hinweg ausgelöst wurden - - Filtern nach Entscheidung, Ereignistyp, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(Beta)_), Richtlinienname oder Sitzungs-ID - - Jede Zeile zeigt: Zeitstempel, Richtlinienname, Entscheidung, CLI-Badge (orange = Claude Code, lila = OpenAI Codex, blau = GitHub Copilot), Tool-Name, Sitzungs-ID und den Grund für deny/instruct-Entscheidungen - - Klicken Sie auf eine Sitzungs-ID, um ihr Transkript zu öffnen – der Viewer erkennt automatisch, welche CLI den Hook ausgelöst hat (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`), und zeigt das passende CLI-Badge in der Überschrift an + - Vollständiger, seitenweise dargestellter Verlauf aller Hook-Ereignisse, die sitzungsübergreifend ausgelöst wurden + - Filterung 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, smaragd = Cursor Agent, bernstein = OpenCode, pink = Pi, himmelblau = Gemini CLI), Tool-Name, Sitzungs-ID und den Grund für deny/instruct-Entscheidungen + - Klicke auf eine Sitzungs-ID, um ihr Transkript zu öffnen – der Betrachter 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 @@ -80,13 +80,13 @@ Eine Seite mit zwei Tabs zur Verwaltung von Richtlinien und Einsicht der Aktivit ## Automatische Aktualisierung -Das Dashboard verfügt über einen Schalter für die automatische Aktualisierung in der oberen Navigation. Wenn aktiviert, wird die aktuelle Seite periodisch aktualisiert, um neue Sitzungen und Richtlinienaktivitäten anzuzeigen, sobald sie auftreten. Unverzichtbar für die Überwachung lang laufender autonomer Agent-Sitzungen. +Das Dashboard verfügt über einen Schalter für die automatische Aktualisierung in der oberen Navigation. Wenn aktiviert, aktualisiert sich die aktuelle Seite regelmäßig, um neue Sitzungen und Richtlinienaktivitäten anzuzeigen, sobald sie auftreten. Unverzichtbar für die Überwachung lang laufender autonomer Agentensitzungen. --- ## Seiten deaktivieren -Wenn Sie nur bestimmte Teile des Dashboards benötigen, setzen Sie `FAILPROOFAI_DISABLE_PAGES` auf eine kommagetrennte Liste von Seitennamen: +Wenn du nur bestimmte Teile des Dashboards benötigst, setze `FAILPROOFAI_DISABLE_PAGES` auf eine kommagetrennte Liste von Seitennamen: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -98,13 +98,13 @@ Gültige Werte: `policies`, `projects`. ## Design -Das Dashboard unterstützt helles und dunkles Design. Wechseln Sie über die Schaltfläche in der Navigationsleiste. Die Einstellung wird im lokalen Speicher Ihres Browsers gespeichert. +Das Dashboard unterstützt hellen und dunklen Modus. Umschalten über die Schaltfläche in der Navigationsleiste. Die Einstellung wird im lokalen Speicher deines Browsers gespeichert. --- ## Projektpfad konfigurieren -Standardmäßig liest das Dashboard aus dem Standardverzeichnis für Claude Code-Projekte. Überschreiben Sie es für benutzerdefinierte Setups: +Standardmäßig liest das Dashboard aus dem regulären Claude Code-Projektverzeichnis. Überschreibe es für benutzerdefinierte Setups: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -114,30 +114,30 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## Zugriff von einem Nicht-localhost-Host -Wenn Sie das Dashboard im **Entwicklungsmodus** (`npm run dev`) ausführen und von einem anderen Hostnamen als localhost darauf zugreifen – zum Beispiel einer benutzerdefinierten Domain, einer Remote-IP oder einer getunnelten URL – sehen Sie möglicherweise eine Warnung wie: +Wenn du das Dashboard im **Entwicklungsmodus** (`npm run dev`) ausführst und von einem anderen Hostnamen als localhost darauf zugreifst – zum Beispiel einer benutzerdefinierten Domain, einer Remote-IP oder einer getunnelten URL – siehst du möglicherweise eine Warnung wie: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Dies ist Next.js, das den Cross-Origin-Zugriff auf seinen HMR-WebSocket (Hot Module Reload) blockiert – ein Feature, das nur im Entwicklungsmodus existiert. Um Ihren Host zuzulassen, verwenden Sie das Flag `--allowed-origins`: +Next.js blockiert dabei den ursprungsübergreifenden Zugriff auf seinen HMR-Websocket (Hot Module Reload), der ausschließlich im Entwicklungsmodus verwendet wird. Um deinen Host zuzulassen, verwende das Flag `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -Für mehrere Hosts oder IPs übergeben Sie eine kommagetrennte Liste: +Für mehrere Hosts oder IPs übergib eine kommagetrennte Liste: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -Sie können stattdessen auch die Umgebungsvariable `FAILPROOFAI_ALLOWED_DEV_ORIGINS` setzen: +Du kannst alternativ 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 Entwicklungsmodus. Beim Ausführen von `failproofai` (Produktionsmodus) gibt es keinen HMR-WebSocket und kein Cross-Origin-Problem mit Entwicklungsressourcen. +Dies gilt nur für den Entwicklungsmodus. Beim Ausführen von `failproofai` (Produktionsmodus) gibt es keinen HMR-Websocket und kein ursprungsübergreifendes Entwicklungsressourcenproblem. \ No newline at end of file diff --git a/docs/de/getting-started.mdx b/docs/de/getting-started.mdx index 0da10098..5b237138 100644 --- a/docs/de/getting-started.mdx +++ b/docs/de/getting-started.mdx @@ -1,13 +1,13 @@ --- title: Erste Schritte -description: "Installiere failproofai, aktiviere Richtlinien und lass deine Agenten zuverlässig laufen" +description: "failproofai installieren, Richtlinien aktivieren und Agenten zuverlässig ausführen" icon: rocket --- ## Voraussetzungen - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (optional – nur zum Kompilieren aus dem Quellcode erforderlich) +- **Bun** >= 1.3.0 (optional – nur zum Bauen aus dem Quellcode erforderlich) --- @@ -31,20 +31,24 @@ bun add -g failproofai - Richtlinien sind Regeln, die vor und nach jedem Werkzeugaufruf eines Agenten ausgeführt werden. Sie fangen destruktive Befehle, das Abfließen von Geheimnissen und andere Fehlerquellen ab, bevor sie Schaden anrichten können. + Richtlinien sind Regeln, die vor und nach jedem Tool-Aufruf eines Agenten ausgeführt werden. Sie erkennen destruktive Befehle, den Verlust von Geheimnissen und andere Fehlerquellen, bevor Schaden entsteht. ```bash failproofai policies --install ``` - Dabei werden Hook-Einträge in die installierten Agent-CLIs geschrieben (Claude Codes `~/.claude/settings.json`, OpenAI Codex' `~/.codex/hooks.json` oder GitHub Copilot CLIs `~/.copilot/hooks/failproofai.json`). Sind mehrere vorhanden, wird eine Auswahl angezeigt; mit `--cli claude codex copilot` (oder einer beliebigen Teilmenge) kannst du die Auswahl überspringen. + Dies schreibt Hook-Einträge in die installierten Agent-CLIs (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 generiertes Plugin-Shim unter `~/.config/opencode/plugins/failproofai.mjs` sowie einen Registrierungseintrag im `plugin`-Array von `~/.config/opencode/opencode.json`, Pi's `~/.pi/agent/settings.json` oder Gemini CLI's `~/.gemini/settings.json`). Wenn mehrere vorhanden sind, wird eine Auswahl angeboten; mit `--cli claude codex copilot cursor opencode pi gemini` (beliebige Teilmenge) kann die Abfrage übersprungen werden. - Die GitHub Copilot CLI-Unterstützung ist **Beta** – installiere sie mit `--cli copilot`. + 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`. ```bash failproofai policies --install --scope project failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project + 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 block-sudo block-rm-rf sanitize-api-keys ``` @@ -60,18 +64,18 @@ bun add -g failproofai failproofai ``` - Öffnet ein lokales Dashboard unter `http://localhost:8020`, in dem du Sitzungen durchsuchen, Werkzeugaufrufe untersuchen und Richtlinien verwalten kannst. + Öffnet ein lokales Dashboard unter `http://localhost:8020`, in dem Sitzungen durchsucht, Tool-Aufrufe inspiziert und Richtlinien verwaltet werden können. - Starte Claude Code wie gewohnt. Versucht der Agent etwas Riskantes, greift failproofai automatisch ein. Lass ihn unbeaufsichtigt laufen und überprüfe anschließend im Dashboard, was passiert ist. + Starte Claude Code wie gewohnt. Wenn der Agent etwas Riskantes versucht, greift failproofai automatisch ein. Lass ihn unbeaufsichtigt laufen und prüfe später im Dashboard, was passiert ist. --- -## Wie Richtlinien funktionieren +## Funktionsweise von Richtlinien -Jedes Mal, wenn ein Agent ein Werkzeug ausführt, ruft Claude Code failproofai als Unterprozess auf: +Jedes Mal, wenn ein Agent ein Tool ausführt, ruft Claude Code failproofai als Unterprozess auf: ```text Claude Code → failproofai --hook PreToolUse → reads stdin JSON @@ -82,18 +86,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 wird über den Grund informiert +- **deny** – die Aktion wird blockiert und der Agent erhält eine Begründung - **instruct** – dem Prompt des Agenten wird zusätzlicher Kontext hinzugefügt -Richtlinien laufen in deinem lokalen Prozess. Es werden keine Daten an einen externen Dienst übertragen. +Richtlinien laufen im lokalen Prozess. Es werden keine Daten an einen externen Dienst gesendet. --- -## Teamrichtlinien mit konventionsbasierten Richtlinien einrichten +## Team-Richtlinien mit konventionsbasierten Richtlinien einrichten -Der schnellste Weg, Qualitätsstandards im gesamten Team zu etablieren, ist die `.failproofai/policies/`-Konvention. Lege Richtliniendateien in dieses Verzeichnis und sie werden automatisch geladen – ohne Flags, Konfigurationsänderungen oder Installationsbefehle. +Der schnellste Weg, Qualitätsstandards im Team durchzusetzen, ist die `.failproofai/policies/`-Konvention. Lege Richtliniendateien in dieses Verzeichnis und sie werden automatisch geladen – ohne Flags, Konfigurationsänderungen oder Installationsbefehle. @@ -102,13 +106,13 @@ Der schnellste Weg, Qualitätsstandards im gesamten Team zu etablieren, ist die ``` - Kopiere die Starter-Beispiele oder schreibe eigene: + Kopiere die Starterbeispiele oder schreibe eigene: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ ``` - Oder erstelle eine neue: + Oder erstelle eine neue Datei: ```js // .failproofai/policies/team-policies.mjs @@ -133,27 +137,27 @@ Der schnellste Weg, Qualitätsstandards im gesamten Team zu etablieren, ist die git commit -m "Add team quality policies" ``` - Jedes Teammitglied, das failproofai installiert hat, übernimmt diese Richtlinien automatisch. Kein individuelles Setup pro Entwickler erforderlich. + Jedes Teammitglied, das failproofai installiert hat, erhält diese Richtlinien automatisch. Kein individuelles Setup erforderlich. -Checke `.failproofai/policies/` in dein Repository ein, damit das gesamte Team dieselben Standards teilt. Wenn dein Team neue Fehlerquellen entdeckt, füge Richtlinien hinzu und pushe 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 teilt. Wenn das Team neue Fehlerquellen entdeckt, füge Richtlinien hinzu und pushe 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. --- ## Datenspeicherung -Alle Konfigurationen und Protokolle verbleiben auf deinem Rechner: +Alle Konfigurationsdaten und Protokolle verbleiben auf deinem Rechner: -| Pfad | Gespeicherte Daten | -|------|----------------| +| Pfad | Inhalt | +|------|--------| | `~/.failproofai/policies-config.json` | Globale Richtlinienkonfiguration | | `~/.failproofai/hook-activity.jsonl` | Hook-Ausführungsverlauf | -| `~/.failproofai/hook.log` | Debug-Protokoll für Fehler in eigenen Hooks | +| `~/.failproofai/hook.log` | Debug-Protokoll für benutzerdefinierte Hook-Fehler | | `.failproofai/policies-config.json` | Projektbezogene Konfiguration (eingecheckt) | -| `.failproofai/policies-config.local.json` | Persönliche Überschreibungen (gitignored) | +| `.failproofai/policies-config.local.json` | Persönliche Überschreibungen (per gitignore ausgeschlossen) | --- @@ -179,12 +183,12 @@ Entfernt Hook-Einträge aus `~/.claude/settings.json`. Konfigurationsdateien in Alle 26 Richtlinien mit Parametern - - Schreibe eigene Richtlinien in JavaScript + + Eigene Richtlinien in JavaScript schreiben - Sitzungen überwachen und Richtlinienaktivität überprüfen + Sitzungen überwachen und Richtlinienaktivitäten einsehen \ No newline at end of file diff --git a/docs/es/architecture.mdx b/docs/es/architecture.mdx index 0bc07892..ff8d465f 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 panel de control monitoriza 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. --- @@ -12,10 +12,10 @@ 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 (Panel de control)** — Una aplicación web Next.js para monitorizar sesiones de agentes y gestionar políticas. +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 (Panel de control)** - Una aplicación web Next.js para monitorear sesiones de agentes 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 invoca entonces `failproofai --hook PreToolUse` como subproceso antes de cada llamada a herramienta, pasando un payload JSON por 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 @@ -62,7 +62,7 @@ Claude Code invoca entonces `failproofai --hook PreToolUse` como subproceso ante 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 tamaño se descartan y todas las políticas permiten implícitamente. +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 @@ -96,7 +96,7 @@ El manejador impone un límite de 1 MB en stdin. Los payloads que superen este t **Instruir en evento Stop:** - Código de salida: `2` -- El motivo se escribe en stderr (no en stdout) +- Motivo escrito en stderr (no en stdout) **Permitir:** - Código de salida: `0` @@ -115,8 +115,8 @@ El manejador impone un límite de 1 MB en stdin. Los payloads que superen este t } ``` - Código de salida: `0` (la operación está permitida) -- Cuando varias políticas devuelven `allow` con un mensaje, sus mensajes se unen con saltos de línea en una sola cadena `additionalContext` -- Si ninguna política proporciona un mensaje, stdout queda vacío (igual que antes) +- Cuando múltiples 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,42 +124,42 @@ El manejador impone un límite de 1 MB en stdin. Los payloads que superen este t ```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 + → parsear payload (máx. 1 MB) + → extraer metadatos de sesión (session_id, cwd, tool_name, tool_input, etc.) + → readMergedHooksConfig(cwd) ← fusiona config 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 + → evaluar todas las políticas (primero las integradas, luego las personalizadas) + → el primer deny cortocircuita la evaluación + → las decisiones instruct se acumulan + → los mensajes allow se acumulan + → escribir decisión JSON en stdout + → persistir evento en ~/.failproofai/hook-activity.jsonl + → salir ``` -Todo el proceso se ejecuta en menos de 100 ms para payloads típicos sin ninguna llamada 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 niveles. ```text -[1] {cwd}/.failproofai/policies-config.json ← proyecto (máxima prioridad) +[1] {cwd}/.failproofai/policies-config.json ← proyecto (mayor prioridad) [2] {cwd}/.failproofai/policies-config.local.json ← local -[3] ~/.failproofai/policies-config.json ← global (mínima prioridad) +[3] ~/.failproofai/policies-config.json ← global (menor prioridad) ``` -Lógica de combinación: -- `enabledPolicies` — unión sin duplicados de los tres archivos -- `policyParams` — clave por política; gana íntegramente el primer archivo que la defina -- `customPoliciesPath` — gana el primer archivo que lo defina -- `llm` — gana el primer archivo que lo defina +Lógica de fusión: +- `enabledPolicies` - unión deduplicada de los tres archivos +- `policyParams` - por clave de política, el primer archivo que lo defina tiene prioridad completa +- `customPoliciesPath` - el primer archivo que lo defina tiene prioridad +- `llm` - el primer archivo que lo defina tiene prioridad -El panel de control web utiliza `readHooksConfig()` (solo global) para lectura y escritura, ya que no se invoca con un cwd de proyecto. +El panel de control web usa `readHooksConfig()` (solo global) para lectura y escritura, ya que no se invoca con un cwd de proyecto. --- @@ -169,18 +169,18 @@ El panel de control web utiliza `readHooksConfig()` (solo global) para lectura y Para cada política: -1. Busca el esquema `params` de la política (si tiene uno). -2. Lee `policyParams[policy.name]` de la configuración combinada. -3. Combina los valores proporcionados por el usuario sobre los valores predeterminados del esquema para producir `ctx.params`. -4. Llama a `policy.fn(ctx)` con el contexto resuelto. -5. Si el resultado es `deny`, se detiene inmediatamente y devuelve esa decisión. -6. Si el resultado es `instruct`, acumula el mensaje y continúa. -7. Si el resultado es `allow`, continúa con la siguiente política. +1. Buscar el esquema `params` de la política (si tiene uno). +2. Leer `policyParams[policy.name]` de la configuración fusionada. +3. Fusionar los valores proporcionados por el usuario sobre los valores predeterminados 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. -Tras ejecutar todas las políticas: -- Si se devolvió algún `deny`, emite la respuesta de deny. -- Si se recopilaron respuestas `instruct`, emite una única respuesta instruct con todos los mensajes unidos. -- En caso contrario, emite una respuesta allow (stdout vacío, exit 0). +Después de que se ejecuten todas las políticas: +- Si se devolvió algún `deny`, emitir la respuesta de deny. +- Si se recopilaron respuestas `instruct`, emitir una única respuesta instruct con todos los mensajes unidos. +- De lo contrario, emitir una respuesta allow (stdout vacío, exit 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 comprobaciones de nulo porque los valores predeterminados siempre se aplican primero. +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 comprobación de nulos porque los valores predeterminados siempre se aplican primero. -La coincidencia de patrones dentro de las políticas utiliza tokens de comando analizados (argv), no coincidencia de cadenas sin procesar. Esto evita la elusión mediante inyección de operadores de shell (p. ej., un patrón para `sudo systemctl status *` no puede eludirse añadiendo `; rm -rf /` al comando). +La coincidencia de patrones dentro de las políticas usa tokens de comando analizados (argv), no coincidencia de cadenas sin procesar. Esto evita la omisión mediante inyección de operadores de shell (por ejemplo, un patrón para `sudo systemctl status *` no puede omitirse añadiendo `; rm -rf /` al comando). --- @@ -227,23 +227,23 @@ export function clearCustomHooks(): void { ... } // used in tests `src/hooks/custom-hooks-loader.ts` carga el archivo de políticas del usuario: -1. Lee `customPoliciesPath` de la configuración; omite si no existe. -2. Resuelve a ruta absoluta; comprueba que el archivo existe. -3. Reescribe todas las importaciones `from "failproofai"` a la ruta dist real para que `customPolicies` resuelva al mismo registro `globalThis`. -4. Reescribe recursivamente las importaciones locales transitivas para garantizar la compatibilidad con ESM. -5. Escribe archivos `.mjs` temporales e importa el archivo de entrada con `import()`. -6. Llama a `getCustomHooks()` para recuperar los hooks registrados. -7. Limpia todos los archivos temporales en un bloque `finally`. +1. Leer `customPoliciesPath` de la configuración; omitir si no está presente. +2. Resolver a ruta absoluta; verificar 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 `import()` el archivo de entrada. +6. Llamar a `getCustomHooks()` para recuperar los hooks registrados. +7. Limpiar todos los archivos temporales en un bloque `finally`. 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 demás políticas personalizadas (pero en ese punto todas las integradas ya han sido ejecutadas). +Las políticas personalizadas se evalúan después de todas las políticas integradas. Un `deny` de una política personalizada aún cortocircuita las demás políticas personalizadas (pero todas las integradas ya se habrán ejecutado en ese punto). --- ## Registro de actividad -Tras cada evento de hook, el manejador añade 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 { @@ -258,44 +258,44 @@ Tras cada evento de hook, el manejador añade una línea JSONL a `~/.failproofai } ``` -Una línea por política que tomó una decisión distinta de allow. Las decisiones allow no se registran (para mantener el archivo pequeño). +Una línea por política que tomó una decisión que no fue allow. Las decisiones allow no se registran (para mantener el archivo pequeño). --- ## Arquitectura del panel de control -El panel de control es una aplicación **Next.js 16** que utiliza el App Router con React Server Components y Server Actions. +El panel de control es una aplicación **Next.js 16** que usa el App Router con React Server Components y Server Actions. ```text app/ - layout.tsx ← Diseño raíz (tema, telemetría, nav) - projects/page.tsx ← Componente servidor: lista todos los proyectos Claude - project/[name]/page.tsx ← Componente servidor: lista sesiones de un proyecto + layout.tsx ← Layout raíz (tema, telemetría, nav) + projects/page.tsx ← Componente servidor: listar todos los proyectos Claude + project/[name]/page.tsx ← Componente servidor: listar sesiones en un proyecto project/[name]/session/ - [sessionId]/page.tsx ← Componente servidor: renderiza el visor de sesión + [sessionId]/page.tsx ← Componente servidor: renderizar visor de sesión policies/page.tsx ← Componente cliente: gestión de políticas + registro de actividad actions/ - get-hooks-config.ts ← Leer configuración + lista de políticas + get-hooks-config.ts ← Leer config + lista de políticas update-hooks-config.ts ← Activar/desactivar política update-policy-params.ts ← Actualizar parámetros de política - get-hook-activity.ts ← Paginar/buscar en el registro de actividad + get-hook-activity.ts ← Paginar/buscar registro de actividad install-hooks-web.ts ← Instalar/eliminar hooks desde el navegador api/ - download/[project]/[session]/route.ts ← Exportar sesión como ZIP/JSONL + 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 y sesiones directamente desde el sistema de archivos (sin capa de API para lecturas). +- 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 sesiones analiza el formato de transcripción JSONL de Claude y renderiza una línea de tiempo de mensajes y llamadas a herramientas. +- 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. **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 una 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 (activación de políticas, búsqueda de actividad, visor de registros). +- 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 cliente para obtención de datos. +- Componentes cliente solo donde se necesita interactividad (activadores de políticas, búsqueda de actividad, visor de registros). --- @@ -311,9 +311,9 @@ 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-nivel │ ├── custom-hooks-registry.ts # Registro de hooks respaldado por globalThis -│ ├── custom-hooks-loader.ts # Cargador ESM para hooks JS de usuario +│ ├── custom-hooks-loader.ts # Cargador ESM para hooks JS del usuario │ ├── 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 @@ -322,11 +322,11 @@ failproofai/ ├── 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 el formato JSONL de transcripción de Claude +│ ├── log-entries.ts # Analizar formato JSONL de transcripción Claude │ ├── paths.ts # Resolver rutas del sistema │ └── ... -├── components/ # Componentes React UI compartidos +├── components/ # Componentes UI React compartidos ├── contexts/ # Proveedores de contexto React (tema, auto-refresco, telemetría) -├── examples/ # Archivos de hooks personalizados de ejemplo +├── examples/ # Archivos de hook personalizados de ejemplo └── __tests__/ # Pruebas unitarias 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 384c2464..1545a7a1 100644 --- a/docs/es/built-in-policies.mdx +++ b/docs/es/built-in-policies.mdx @@ -4,13 +4,13 @@ description: "Las 39 políticas integradas que detectan los modos de fallo más icon: shield --- -failproofai incluye 39 políticas integradas que detectan los modos de fallo más comunes de los agentes. Cada política se activa ante un tipo de evento de hook y un nombre de herramienta específicos. Diecinueve políticas aceptan parámetros que permiten ajustar su comportamiento sin escribir código. Cinco políticas de flujo de trabajo aplican un pipeline de commit → push → PR → CI antes de que Claude se detenga. +failproofai incluye 39 políticas integradas que detectan los modos de fallo 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 un pipeline de commit → push → PR → CI antes de que Claude se detenga. --- ## Descripción general -Las políticas están agrupadas por categorías: +Las políticas están agrupadas en categorías: | Categoría | Políticas | Tipo de hook | |-----------|-----------|--------------| @@ -27,13 +27,13 @@ Las políticas están agrupadas por categorías: - **`block-`** — impide que el agente continúe. - **`warn-`** — proporciona al agente contexto adicional para que pueda corregirse por sí mismo. -- **`sanitize-`** — elimina datos sensibles de la salida de las herramientas antes de que el agente los vea. +- **`sanitize-`** — elimina datos sensibles de la salida de la herramienta antes de que el agente la vea. ### Espacios de nombres -Cada política ocupa un slot con la forma `/`. Las políticas integradas pertenecen al espacio de nombres **`exospherehost/`** — por ejemplo, `exospherehost/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 ocupa un espacio `/`. Las políticas integradas pertenecen al espacio de nombres **`exospherehost/`** — por ejemplo, `exospherehost/sanitize-jwt`. El espacio de nombres evita colisiones cuando también se cargan políticas personalizadas o de terceros con nombres cortos similares. -En tu configuración puedes referirte a una política integrada por su nombre corto o por su nombre cualificado; ambas formas apuntan a la misma política: +En la configuración puedes hacer referencia a una política integrada tanto por su nombre corto como por su nombre completo; ambas formas resuelven a la misma política: ```json { @@ -44,7 +44,7 @@ En tu configuración puedes referirte a una política integrada por su nombre co } ``` -Si un nombre no contiene `/`, failproofai lo considera perteneciente al espacio de nombres predeterminado `exospherehost`. Los nombres que ya contienen un `/` (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 `exospherehost`. Los nombres que ya contienen una `/` (por ejemplo, `myorg/foo`, `custom/my-hook`) se mantienen tal cual. - **`require-`** — bloquea el evento Stop hasta que se cumplan las condiciones. --- @@ -57,20 +57,20 @@ Todas las políticas admiten un campo opcional `hint` en `policyParams`. El hint ## Comandos peligrosos -Evitan que los agentes ejecuten operaciones difíciles de deshacer o que puedan dañar el sistema anfitrión. +Evita que los agentes ejecuten operaciones difíciles de deshacer o que podrían dañar el sistema anfitrión. ### `block-sudo` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega cualquier comando `sudo`. +**Comportamiento por defecto:** Deniega cualquier comando `sudo`. -Bloquea invocaciones que incluyan la palabra clave `sudo`. La coincidencia de patrones se realiza sobre los tokens del comando ya parseado, no sobre la cadena de texto en bruto, para evitar bypasses mediante inyección de operadores de shell. +Bloquea las invocaciones que incluyen la palabra clave `sudo`. La coincidencia de patrones se realiza sobre los tokens del comando ya parseado, no sobre la cadena sin procesar, para evitar omisiones mediante inyección de operadores de shell. **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos exactos de comandos que están permitidos. Cada entrada se compara con los tokens de argv parseados. | +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| +| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos exactos que están permitidos. Cada entrada se compara contra los tokens argv parseados. | **Ejemplo:** @@ -87,7 +87,7 @@ 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. -Los patrones se comparan con los tokens parseados, no con la cadena de comando en bruto. Esto previene bypasses 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 los tokens parseados, no contra la cadena del comando sin procesar. Esto evita omisiones mediante operadores de shell añadidos (por ejemplo, `sudo systemctl status x; rm -rf /` no coincide con `sudo systemctl status *`). --- @@ -95,13 +95,13 @@ Los patrones se comparan con los tokens parseados, no con la cadena de comando e ### `block-rm-rf` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega `rm -rf`, `rm -fr` y formas similares de eliminación recursiva. +**Comportamiento por defecto:** Deniega `rm -rf`, `rm -fr` y formas similares de eliminación recursiva. **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| -| `allowPaths` | `string[]` | `[]` | Rutas en las que es seguro realizar eliminaciones recursivas (p. ej. `/tmp`). | +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| +| `allowPaths` | `string[]` | `[]` | Rutas en las que se permite la eliminación recursiva (por ejemplo, `/tmp`). | **Ejemplo:** @@ -120,7 +120,7 @@ Los patrones se comparan con los tokens parseados, no con la cadena de comando e ### `block-curl-pipe-sh` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega `curl | bash`, `curl | sh`, `wget | bash` y patrones similares. +**Comportamiento por defecto:** Deniega `curl | bash`, `curl | sh`, `wget | bash` y patrones similares. Sin parámetros. @@ -129,7 +129,7 @@ Sin parámetros. ### `block-failproofai-commands` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega comandos que desinstalen o deshabiliten failproofai (p. ej. `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Comportamiento por defecto:** Deniega los comandos que desinstalarían o deshabilitarían failproofai (por ejemplo, `npm uninstall failproofai`, `failproofai policies --uninstall`). Sin parámetros. @@ -137,19 +137,19 @@ Sin parámetros. ## Comandos de infraestructura -Impiden que los agentes de código 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 afectados a menos que habilites la política. Una vez habilitada, cualquier invocación de la CLI correspondiente es denegada salvo que el comando coincida con alguna entrada en `allowPatterns`. +Impide que los agentes de codificació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 afectados a menos que habilites la política. Una vez habilitada, cada invocación de la CLI correspondiente es denegada, salvo 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 parseado, `*` 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 bypasses por inyección. +La gramática de patrones es la misma que en [`block-sudo`](#block-sudo): los tokens se comparan contra argv parseado, `*` 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 permisos, para evitar omisiones por inyección. ### `block-kubectl` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega cualquier invocación de `kubectl`. +**Comportamiento por defecto:** Deniega cualquier invocación de `kubectl`. **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| | `allowPatterns` | `string[]` | `[]` | Prefijos de comandos kubectl que están permitidos. | **Ejemplo:** @@ -164,19 +164,19 @@ 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` es denegado. --- ### `block-terraform` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega cualquier invocación de `terraform` o `tofu` (OpenTofu). +**Comportamiento por defecto:** Deniega cualquier invocación de `terraform` o `tofu` (OpenTofu). **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| | `allowPatterns` | `string[]` | `[]` | Prefijos de comandos terraform/tofu que están permitidos. | **Ejemplo:** @@ -196,13 +196,13 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply ### `block-aws-cli` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega cualquier invocación de la CLI de `aws`. +**Comportamiento por defecto:** Deniega cualquier invocación del CLI `aws`. **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos de la CLI de aws que están permitidos. | +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| +| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos del CLI aws que están permitidos. | **Ejemplo:** @@ -221,13 +221,13 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply ### `block-gcloud` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega cualquier invocación de la CLI de `gcloud` (Google Cloud). +**Comportamiento por defecto:** Deniega cualquier invocación del CLI `gcloud` (Google Cloud). **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos de gcloud que están permitidos. | +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| +| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos gcloud que están permitidos. | **Ejemplo:** @@ -246,13 +246,13 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply ### `block-az-cli` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega cualquier invocación de la CLI de `az` (Azure). +**Comportamiento por defecto:** Deniega cualquier invocación del CLI `az` (Azure). **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos de la CLI de az que están permitidos. | +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| +| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos del CLI az que están permitidos. | **Ejemplo:** @@ -271,13 +271,13 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply ### `block-helm` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega cualquier invocación de `helm`. +**Comportamiento por defecto:** Deniega cualquier invocación de `helm`. **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos de helm que están permitidos. | +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| +| `allowPatterns` | `string[]` | `[]` | Prefijos de comandos helm que están permitidos. | **Ejemplo:** @@ -296,7 +296,7 @@ Con esta configuración, `kubectl get pods` está permitido pero `kubectl apply ### `block-gh-pipeline` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega los siguientes subcomandos de la CLI `gh` que modifican el 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 +305,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 capturados por esta política — son necesarios habitualmente para comprobaciones de flujo de trabajo (incluidas las propias de failproofai como `require-ci-green-before-stop`). +Los subcomandos `gh` de solo lectura, como `gh pr view`, `gh pr list`, `gh run list`, `gh release view` y `gh api repos/.../...`, **no** son detectados por esta política — se necesitan habitualmente para comprobaciones de flujo de trabajo (incluida la propia `require-ci-green-before-stop` de failproofai). **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| -| `allowPatterns` | `string[]` | `[]` | Invocaciones específicas mediante script que se permiten aunque normalmente serían denegadas. | +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| +| `allowPatterns` | `string[]` | `[]` | Invocaciones específicas programadas que se permiten aunque normalmente serían denegadas. | **Ejemplo:** @@ -329,12 +329,12 @@ Los subcomandos de `gh` de solo lectura como `gh pr view`, `gh pr list`, `gh run ## Secretos (sanitizadores) -Evitan que los agentes filtren credenciales en su contexto o salida. Las políticas de sanitización 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 devolverla 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 enviada de vuelta. +Impide que los agentes filtren credenciales en su contexto o salida. Las políticas de sanitización 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 deny que impide que la salida sea enviada de vuelta. ### `sanitize-jwt` **Evento:** PostToolUse (todas las herramientas) -**Por defecto:** Redacta tokens JWT (tres segmentos base64url separados por `.`). +**Comportamiento por defecto:** Redacta tokens JWT (tres segmentos base64url separados por `.`). Sin parámetros. @@ -343,13 +343,13 @@ Sin parámetros. ### `sanitize-api-keys` **Evento:** PostToolUse (todas las herramientas) -**Por defecto:** Redacta formatos comunes de claves de API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), claves de acceso de AWS (`AKIA`), claves de Stripe (`sk_live_`, `sk_test_`) y claves de la API de Google (`AIza`). +**Comportamiento por defecto:** Redacta los formatos de API key más comunes: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), claves de acceso AWS (`AKIA`), claves Stripe (`sk_live_`, `sk_test_`) y claves de API de Google (`AIza`). **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Patrones regex adicionales a tratar como secretos. | +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Patrones regex adicionales que se tratarán como secretos. | **Ejemplo:** @@ -371,7 +371,7 @@ Sin parámetros. ### `sanitize-connection-strings` **Evento:** PostToolUse (todas las herramientas) -**Por defecto:** Redacta cadenas de conexión a bases de datos que contengan credenciales embebidas (p. ej. `postgresql://user:password@host/db`). +**Comportamiento por defecto:** Redacta las cadenas de conexión a bases de datos que contienen credenciales embebidas (por ejemplo, `postgresql://user:password@host/db`). Sin parámetros. @@ -380,7 +380,7 @@ Sin parámetros. ### `sanitize-private-key-content` **Evento:** PostToolUse (todas las herramientas) -**Por defecto:** Redacta bloques PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, etc.). +**Comportamiento por defecto:** Redacta bloques PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, etc.). Sin parámetros. @@ -389,7 +389,7 @@ Sin parámetros. ### `sanitize-bearer-tokens` **Evento:** PostToolUse (todas las herramientas) -**Por defecto:** Redacta cabeceras `Authorization: Bearer ` donde el token tiene 20 o más caracteres. +**Comportamiento por defecto:** Redacta cabeceras `Authorization: Bearer ` donde el token tiene 20 o más caracteres. Sin parámetros. @@ -397,14 +397,14 @@ Sin parámetros. ## Entorno -Protege la configuración sensible del entorno para que los agentes no puedan leerla ni exponerla. +Protege la configuración de entorno sensible para que los agentes no puedan leerla ni exponerla. ### `block-env-files` **Evento:** PreToolUse (Bash, Read) -**Por defecto:** Deniega la lectura de archivos `.env` mediante `cat .env`, llamadas a la herramienta `Read` con `.env` como ruta de archivo, etc. +**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 — únicamente archivos llamados exactamente `.env`. +No bloquea `.envrc` ni otros archivos relacionados con el entorno — solo archivos llamados exactamente `.env`. Sin parámetros. @@ -413,7 +413,7 @@ Sin parámetros. ### `protect-env-vars` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega comandos que impriman variables de entorno: `printenv`, `env`, `echo $VAR`. +**Comportamiento por defecto:** Deniega los comandos que imprimen variables de entorno: `printenv`, `env`, `echo $VAR`. Sin parámetros. @@ -421,18 +421,18 @@ Sin parámetros. ## Acceso a archivos -Mantiene a los agentes dentro de los límites del proyecto y alejados de archivos sensibles. +Mantiene a los agentes trabajando dentro de los límites del proyecto y alejados de archivos sensibles. ### `block-read-outside-cwd` **Evento:** PreToolUse (Read, Bash) -**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` en tiempo real garantiza que el límite se mantenga estable incluso cuando Claude hace `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 permanece estable incluso después de que Claude cambie a un subdirectorio con `cd`. **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| -| `allowPaths` | `string[]` | `[]` | Prefijos de rutas absolutas que están permitidas aunque estén fuera de la raíz del proyecto. | +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| +| `allowPaths` | `string[]` | `[]` | Prefijos de rutas absolutas que están permitidos aunque estén fuera de la raíz del proyecto. | **Ejemplo:** @@ -451,13 +451,13 @@ Mantiene a los agentes dentro de los límites del proyecto y alejados de archivo ### `block-secrets-write` **Evento:** PreToolUse (Write, Edit) -**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 usados para claves privadas y certificados: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| -| `additionalPatterns` | `string[]` | `[]` | Patrones de nombre de archivo adicionales (estilo glob) a bloquear. | +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| +| `additionalPatterns` | `string[]` | `[]` | Patrones de nombre de archivo adicionales (estilo glob) que se bloquearán. | **Ejemplo:** @@ -480,12 +480,12 @@ Previene pushes accidentales, force-pushes y errores de rama que son difíciles ### `block-push-master` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega `git push origin main` y `git push origin master`. +**Comportamiento por defecto:** Deniega `git push origin main` y `git push origin master`. **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| | `protectedBranches` | `string[]` | `["main", "master"]` | Nombres de ramas a las que no se puede hacer push directamente. | **Ejemplo:** @@ -501,7 +501,7 @@ Previene pushes accidentales, force-pushes y errores de rama que son difíciles ``` -Para permitir push a todas las ramas (deshabilitando efectivamente esta política sin eliminarla de `enabledPolicies`), establece `protectedBranches: []`. +Para permitir el push a todas las ramas (deshabilitando efectivamente esta política sin eliminarla de `enabledPolicies`), establece `protectedBranches: []`. --- @@ -509,22 +509,22 @@ Para permitir push a todas las ramas (deshabilitando efectivamente esta polític ### `block-work-on-main` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega hacer checkout directamente a las ramas `main` o `master`. +**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 rama (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) no se ven afectados. **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Nombres de ramas a las que no se puede hacer checkout directamente. | +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| +| `protectedBranches` | `string[]` | `["main", "master"]` | Nombres de ramas en las que se deniega commit/merge/rebase/cherry-pick. | --- ### `block-force-push` **Evento:** PreToolUse (Bash) -**Por defecto:** Deniega `git push --force` y `git push -f`. +**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 la política. Usa el campo transversal [`hint`](/es/configuration#hint-cross-cutting) para sugerir alternativas: ```json { @@ -541,7 +541,7 @@ Sin parámetros específicos de política. Usa el [`hint`](/es/configuration#hin ### `warn-git-amend` **Evento:** PreToolUse (Bash) -**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 para que proceda con cuidado al ejecutar `git commit --amend`. No bloquea el comando. Sin parámetros. @@ -550,7 +550,7 @@ Sin parámetros. ### `warn-git-stash-drop` **Evento:** PreToolUse (Bash) -**Por defecto:** Instruye a Claude para que confirme antes de ejecutar `git stash drop`. No bloquea el comando. +**Comportamiento por defecto:** Instruye a Claude para que confirme antes de ejecutar `git stash drop`. No bloquea el comando. Sin parámetros. @@ -559,7 +559,7 @@ Sin parámetros. ### `warn-all-files-staged` **Evento:** PreToolUse (Bash) -**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 para que revise lo que está añadiendo al stage cuando ejecuta `git add -A` o `git add .`. No bloquea el comando. Sin parámetros. @@ -572,7 +572,7 @@ Detecta operaciones SQL destructivas antes de que se ejecuten contra tu base de ### `warn-destructive-sql` **Evento:** PreToolUse (Bash) -**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 para que confirme antes de ejecutar SQL que contenga `DROP TABLE`, `DROP DATABASE` o `DELETE` sin cláusula `WHERE`. Sin parámetros. @@ -581,7 +581,7 @@ Sin parámetros. ### `warn-schema-alteration` **Evento:** PreToolUse (Bash) -**Por defecto:** Instruye a Claude para que confirme antes de ejecutar sentencias `ALTER TABLE`. +**Comportamiento por defecto:** Instruye a Claude para que confirme antes de ejecutar sentencias `ALTER TABLE`. Sin parámetros. @@ -589,18 +589,18 @@ Sin parámetros. ## Advertencias -Proporcionan a los agentes contexto adicional 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) -**Por defecto:** Instruye a Claude para que confirme antes de escribir archivos de más de 1024 KB. +**Comportamiento por defecto:** Instruye a Claude para que confirme antes de escribir archivos mayores de 1024 KB. **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| -| `thresholdKb` | `number` | `1024` | Umbral de tamaño de archivo en kilobytes por encima del cual se emite una advertencia. | +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| +| `thresholdKb` | `number` | `1024` | Umbral de tamaño de archivo en kilobytes a partir del cual se emite una advertencia. | **Ejemplo:** @@ -615,7 +615,7 @@ Proporcionan a los agentes contexto adicional antes de operaciones potencialment ``` -El manejador de hooks aplica 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. +El manejador del hook impone un límite de 1 MB en stdin para los payloads. Para probar esta política con contenido pequeño, establece `thresholdKb` en un valor muy por debajo de 1024. --- @@ -623,7 +623,7 @@ El manejador de hooks aplica un límite de 1 MB en stdin para los payloads. Para ### `warn-package-publish` **Evento:** PreToolUse (Bash) -**Por defecto:** Instruye a Claude para que confirme antes de ejecutar `npm publish`. +**Comportamiento por defecto:** Instruye a Claude para que confirme antes de ejecutar `npm publish`. Sin parámetros. @@ -632,7 +632,7 @@ Sin parámetros. ### `warn-background-process` **Evento:** PreToolUse (Bash) -**Por defecto:** Instruye a Claude para que tenga cuidado al lanzar procesos en segundo plano mediante `nohup`, `&`, `disown` o `screen`. +**Comportamiento por defecto:** Instruye a Claude para que tenga precaución al lanzar procesos en segundo plano mediante `nohup`, `&`, `disown` o `screen`. Sin parámetros. @@ -641,7 +641,7 @@ Sin parámetros. ### `warn-global-package-install` **Evento:** PreToolUse (Bash) -**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 para que confirme antes de ejecutar `npm install -g`, `yarn global add` o `pip install` sin un entorno virtual. Sin parámetros. @@ -649,21 +649,21 @@ Sin parámetros. ## Gestores de paquetes -Establece qué gestores de paquetes puede utilizar el agente. +Controla qué gestores de paquetes puede usar el agente. ### `prefer-package-manager` **Evento:** PreToolUse (Bash) -**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:** 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. Detecta: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. -| Parámetro | Tipo | 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 tiene efecto. | -| `blocked` | string[] | `[]` | Nombres adicionales de gestores a bloquear más allá de la lista integrada (p. ej. `['pdm', 'pipx']`). | +| 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 será bloqueado. Si está vacío, la política no tiene efecto. | +| `blocked` | string[] | `[]` | Nombres de gestores adicionales a bloquear más allá de la lista integrada (por ejemplo, `['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 +679,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 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. +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. --- ## Comportamiento de la IA -Detecta cuando los agentes se quedan bloqueados o se comportan de forma inesperada. +Detecta cuándo los agentes se quedan bloqueados o se comportan de forma inesperada. ### `warn-repeated-tool-calls` **Evento:** PreToolUse (todas las herramientas) -**Por defecto:** Instruye a Claude para que reconsidere cuando la misma herramienta se llama 3 o más veces con parámetros idénticos — una señal habitual de que el agente está atascado en un bucle. +**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 — un síntoma habitual de que el agente está atrapado en un bucle. Sin parámetros. @@ -698,14 +698,14 @@ 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 deniegan a Claude detenerse hasta que cada condición se cumpla. Siguen una cadena de dependencias natural: commit → push → PR → CI. Si una política deniega, las políticas posteriores de la cadena se omiten (cortocircuito en deny). +Impone un flujo de trabajo disciplinado al final de la sesión. Estas políticas se activan en el evento **Stop** y evitan que Claude 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 (el deny hace un cortocircuito). -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 la acción con un mensaje informativo que explica 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 (por ejemplo, `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. ### `require-commit-before-stop` **Evento:** Stop -**Por defecto:** Deniega detenerse cuando hay cambios sin confirmar (archivos modificados, en stage o sin seguimiento). Devuelve un mensaje informativo cuando el directorio de trabajo está limpio. +**Comportamiento por defecto:** Deniega la detención cuando hay cambios sin confirmar (archivos modificados, en stage o sin seguimiento). Devuelve un mensaje informativo cuando el directorio de trabajo está limpio. Sin parámetros. @@ -714,12 +714,12 @@ Sin parámetros. ### `require-push-before-stop` **Evento:** Stop -**Por defecto:** Deniega detenerse cuando hay commits sin publicar 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 ningún remote configurado. +**Comportamiento por defecto:** Deniega la detención cuando hay commits sin publicar 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 de forma abierta si no hay ningún remote configurado. **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| | `remote` | `string` | `"origin"` | Nombre del remote al que hacer push. | **Ejemplo:** @@ -739,13 +739,13 @@ Sin parámetros. ### `require-pr-before-stop` **Evento:** Stop -**Por defecto:** Deniega detenerse cuando no existe ningún pull request para la rama actual, o cuando el PR existente está cerrado sin haberse fusionado. Instruye a Claude para que cree un PR con `gh pr create`. Cuando el PR está **fusionado**, la política lo permite (el trabajo ha sido entregado) y el mensaje sugiere cambiar de rama (`git checkout main && git pull`). +**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 haberse fusionado. Instruye a Claude para que cree una PR con `gh pr create`. Cuando la PR está **fusionada**, la política lo permite (el trabajo ha sido publicado) y el mensaje sugiere cambiar de rama (`git checkout main && git pull`). Sin parámetros. Esta política requiere que [GitHub CLI](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 los pull requests. Si `gh` no está instalado o no está autenticado, la política falla de forma abierta e informa a Claude del motivo. +Ejecuta `gh auth login` con un token de acceso personal que tenga el alcance `repo` para acceso de lectura a las pull requests. Si `gh` no está instalado o no está autenticado, la política falla de forma abierta e informa del motivo a Claude. --- @@ -753,24 +753,24 @@ Ejecuta `gh auth login` con un token de acceso personal que tenga el scope `repo ### `require-no-conflicts-before-stop` **Evento:** Stop -**Por defecto:** Deniega detenerse cuando la rama actual no puede fusionarse limpiamente en la rama base. La política primero confirma que existe un PR con estado `OPEN` en GitHub para la rama — sin uno, no hay objetivo de fusión que aplicar, por lo que toda la política cortocircuita hacia allow. Una vez confirmado el PR con estado `OPEN`, se ejecutan dos sondeos independientes: +**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 destino de fusión que aplicar, por lo que toda la política hace un cortocircuito hacia allow. Una vez confirmada la PR `OPEN`, se ejecutan dos sondeos independientes: 1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`. En caso de conflicto, el mensaje de deny 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 podría pasar por alto (p. ej. si alguien entregó un PR conflictivo en `main` desde el último fetch). Un resultado `CONFLICTING` genera un deny. Un resultado `UNKNOWN` también genera un deny 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. +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 podría pasar por alto (por ejemplo, si alguien publicó una PR conflictiva en `main` desde la última sincronizació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 evita falsos negativos mientras GitHub recalcula. -Se omite completamente (permite) cuando: `gh` no está instalado, no existe ningún 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/` no existe localmente o cuando no hay commits por delante de la base — esos casos de fallthrough en Layer 1 igualmente consultan la fusionabilidad del PR en caché antes de permitir. +Se omite por completo (permite) cuando: `gh` no está instalado, no existe PR para la rama, el estado de la PR no es `OPEN` (por ejemplo, `MERGED`, `CLOSED`), o `gh pr view` devuelve una salida no parseable. También falla de forma abierta cuando `origin/` no existe localmente o cuando no hay commits por delante de la base — esas excepciones de la capa 1 aún consultan la fusionabilidad de la PR en caché antes de permitir. **Parámetros:** -| Parámetro | Tipo | Por defecto | Descripción | -|-----------|------|-------------|-------------| +| Parámetro | Tipo | Valor por defecto | Descripción | +|-----------|------|-------------------|-------------| | `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 un PR con estado `OPEN` antes de ejecutar cualquier sondeo de conflictos — sin `gh`, la política -cortocircuita hacia allow. Ejecuta `gh auth login` con un token de acceso personal que tenga -el scope `repo` para acceso de lectura a los pull requests. +que existe una PR `OPEN` antes de ejecutar cualquier sondeo de conflictos — sin `gh`, la política +hace un cortocircuito hacia allow. Ejecuta `gh auth login` con un token de acceso personal que tenga +el alcance `repo` para acceso de lectura a las pull requests. --- @@ -778,14 +778,13 @@ el scope `repo` para acceso de lectura a los pull requests. ### `require-ci-green-before-stop` **Evento:** Stop -**Por defecto:** Deniega detenerse 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` y `cancelled` como éxito. 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 las ejecuciones de flujo de trabajo de GitHub Actions como las comprobaciones de bots de terceros (por ejemplo, CodeRabbit, SonarCloud, Codecov). Trata las conclusiones `skipped` y `cancelled` como éxito. Devuelve un mensaje informativo cuando todas las comprobaciones pasan. Sin parámetros. Esta política requiere que [GitHub CLI](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 las -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 de forma abierta e informa a Claude del motivo. +Ejecuta `gh auth login` con un token de acceso personal que tenga el alcance `repo` para acceso de lectura a las ejecuciones de flujo de trabajo de Actions y a 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. --- @@ -794,7 +793,7 @@ ejecuciones de flujo de trabajo de Actions y la API de Checks. Si `gh` no está ## Deshabilitar políticas individuales -Elimina una política específica de `enabledPolicies` en tu configuración, o desactívala en la pestaña Políticas del panel de control. +Elimina una política concreta de `enabledPolicies` en tu configuración, o desactívala desde la pestaña Políticas del panel de control. ```json { @@ -805,4 +804,4 @@ Elimina una política específica de `enabledPolicies` en tu configuración, o d } ``` -Las políticas que no están listadas 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 en `policyParams` para ellas. \ No newline at end of file diff --git a/docs/es/configuration.mdx b/docs/es/configuration.mdx index c43fa763..613053e7 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 combinación" +description: "Formato del archivo de configuración, sistema de tres ámbitos y reglas de fusión" icon: gear --- -failproofai utiliza archivos de configuración JSON para controlar qué políticas están activas, cómo se comportan y desde dónde se cargan las políticas personalizadas. La configuración está diseñada para compartirse fácilmente con tu equipo: confírmala en tu repositorio y cada desarrollador obtendrá la misma red de seguridad para el agente. +failproofai utiliza archivos de configuración JSON para controlar qué políticas están activas, cómo se comportan y desde dónde se cargan las políticas personalizadas. La configuración está diseñada para compartirse fácilmente con tu equipo: confírmala en tu repositorio y todos los desarrolladores obtendrán la misma red de seguridad para el agente. --- @@ -15,14 +15,14 @@ Existen tres ámbitos de configuración, evaluados en orden de prioridad: | Ámbito | Ruta del archivo | Propósito | |--------|-----------------|-----------| | **project** | `.failproofai/policies-config.json` | Configuración por repositorio, confirmada en el control de versiones | -| **local** | `.failproofai/policies-config.local.json` | Anulaciones personales por repositorio, ignoradas por git | +| **local** | `.failproofai/policies-config.local.json` | Anulaciones personales por repositorio, excluidas con gitignore | | **global** | `~/.failproofai/policies-config.json` | Valores predeterminados a nivel de usuario para todos los proyectos | -Cuando failproofai recibe un evento de hook, carga y combina los tres archivos que existen para el directorio de trabajo actual. +Cuando failproofai recibe un evento de hook, carga y fusiona los tres archivos que existen para el directorio de trabajo actual. -### Reglas de combinación +### Reglas de fusión -**`enabledPolicies`** - la unión de los tres ámbitos. Una política habilitada en cualquier nivel está activa. +**`enabledPolicies`** — la unión de los tres ámbitos. Una política habilitada en cualquier nivel está activa. ```text project: ["block-sudo"] @@ -32,13 +32,13 @@ global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← unión sin duplicados ``` -**`policyParams`** - el primer ámbito que define los parámetros para una política determinada tiene prioridad completa. No hay combinació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 completamente. No se realiza una fusión profunda de los 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 tiene prioridad, global se ignora +resolved: { allowPatterns: ["sudo apt-get update"] } ← project gana, global se ignora ``` ```text @@ -46,12 +46,12 @@ project: (sin entrada block-sudo) local: (sin entrada block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← cae hasta global +resolved: { allowPatterns: ["sudo systemctl status"] } ← se aplica el valor de global ``` -**`customPoliciesPath`** - el primer ámbito que lo define tiene prioridad. +**`customPoliciesPath`** — gana el primer ámbito que lo define. -**`llm`** - el primer ámbito que lo define tiene prioridad. +**`llm`** — gana el primer ámbito que lo define. --- @@ -104,7 +104,7 @@ Tipo: `string[]` Lista de nombres de políticas a habilitar. Los nombres deben coincidir exactamente con los identificadores de política que muestra `failproofai policies`. Consulta [Políticas integradas](/es/built-in-policies) para ver la lista completa. -Las políticas que no están en `enabledPolicies` están inactivas, aunque tengan entradas en `policyParams`. +Las políticas que no estén en `enabledPolicies` estarán inactivas, incluso si tienen entradas en `policyParams`. ### `policyParams` @@ -112,17 +112,17 @@ 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). -Si una política tiene parámetros pero no los especificas, se utilizan los valores predeterminados integrados de la política. Los usuarios que no configuran `policyParams` en absoluto obtienen un comportamiento idéntico al de versiones anteriores. +Si una política tiene parámetros pero no los especificas, se usarán los valores predeterminados integrados de la política. Los usuarios que no configuren `policyParams` en absoluto obtendrán un comportamiento idéntico al de versiones anteriores. -Las claves desconocidas dentro del bloque de parámetros de una política se ignoran silenciosamente en el momento de dispararse 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 al ejecutar el hook, pero se marcan como advertencias cuando ejecutas `failproofai policies`. #### `hint` (transversal) Tipo: `string` (opcional) -Un mensaje que se añade al motivo cuando una política devuelve `deny` o `instruct`. Úsalo para 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 práctica sin modificar la política en sí. -Funciona con cualquier tipo de política: integrada, personalizada (`custom/`), convención de proyecto (`.failproofai-project/`) o convención de usuario (`.failproofai-user/`). +Funciona con cualquier tipo de política: integradas, personalizadas (`custom/`), convenciones de proyecto (`.failproofai-project/`) o convenciones de usuario (`.failproofai-user/`). ```json { @@ -143,15 +143,15 @@ 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."* -Los valores que no son cadenas de texto y las cadenas vacías se ignoran silenciosamente. Si `hint` no está configurado, el comportamiento no cambia (compatible con versiones anteriores). +Los valores que no sean cadenas de texto y las cadenas vacías se ignoran silenciosamente. Si `hint` no está definido, el comportamiento no cambia (compatible con versiones anteriores). ### `customPoliciesPath` Tipo: `string` (ruta absoluta) -Ruta a un archivo JavaScript que contiene políticas de hook personalizadas. Este campo lo establece automáticamente `failproofai policies --install --custom ` (la ruta se resuelve a absoluta antes de almacenarse). +Ruta a un archivo JavaScript que contiene políticas de hook personalizadas. Se establece automáticamente mediante `failproofai policies --install --custom ` (la ruta se resuelve a absoluta antes de almacenarse). -El archivo se carga de nuevo en cada evento de hook; no hay caché. Consulta [Políticas personalizadas](/es/custom-policies) para más detalles sobre su creación. +El archivo se carga de nuevo en cada evento de hook; no hay caché. Consulta [Políticas personalizadas](/es/custom-policies) para más detalles sobre cómo crearlas. ### Políticas basadas en convención @@ -162,11 +162,11 @@ Además del `customPoliciesPath` explícito, failproofai descubre y carga autom | 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. +**Coincidencia de archivos:** Solo se cargan los archivos que coincidan con `*policies.{js,mjs,ts}` (por ejemplo, `security-policies.mjs`, `workflow-policies.js`). Los demás archivos 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. +**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 siguiente evento de hook. -**Carga por unión:** Se analizan tanto el directorio de convención del proyecto como el del usuario. Se cargan todos los archivos coincidentes de ambos niveles (a diferencia de `customPoliciesPath`, que usa el primero en ganar por ámbito). +**Carga por unión:** Se analizan tanto el directorio de convención del proyecto como el del usuario. Se cargan todos los archivos coincidentes de ambos niveles (a diferencia de `customPoliciesPath`, que usa el primer ámbito que gana). Consulta [Políticas personalizadas](/es/custom-policies) para más detalles y ejemplos. @@ -174,7 +174,7 @@ Consulta [Políticas personalizadas](/es/custom-policies) para más detalles y e Tipo: `object` (opcional) -Configuración del cliente LLM para políticas que realizan llamadas a IA. No es necesario para la mayoría de las configuraciones. +Configuración del cliente LLM para políticas que realizan llamadas a IA. No es necesaria para la mayoría de las configuraciones. ```json { @@ -189,30 +189,38 @@ 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 independientes: +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 de los hooks), mientras que `policies-config.json` es el archivo que gestionas directamente. Ambos son independientes: -- **Configuración de la CLI del agente** — indica al agente que llame a `failproofai --hook ` en cada uso de herramienta: +- **Configuración de la CLI del agente** — le indica al agente que llame a `failproofai --hook ` en cada uso de herramienta: - **Claude Code**: `~/.claude/settings.json` (usuario), `/.claude/settings.json` (proyecto), `/.claude/settings.local.json` (local) - **OpenAI Codex**: `~/.codex/hooks.json` (usuario), `/.codex/hooks.json` (proyecto) — Codex no tiene ámbito `local` - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (usuario), `/.github/hooks/failproofai.json` (proyecto) — Copilot no tiene ámbito `local`. Las entradas de hook utilizan los campos de comando `bash`/`powershell` con clave de SO de Copilot con `timeoutSec`; el archivo lleva un marcador de nivel superior `version: 1`. El soporte de Copilot CLI está en **beta** mientras verificamos el esquema de registros `events.jsonl` (que la documentación pública no especifica) con más sesiones reales. -- **`policies-config.json`** — indica a failproofai qué políticas evaluar y con qué parámetros (compartido entre todas las CLIs de agente) + - **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 de SO de Copilot junto con `timeoutSec`; el archivo incluye un marcador `version: 1` en el nivel superior. El soporte de Copilot CLI está en **beta** mientras verificamos el esquema de registros de `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}` de Claude (sin división `bash`/`powershell`), pero se almacenan bajo claves de evento en camelCase (`preToolUse`, `beforeSubmitPrompt`, …) en un array plano según el [esquema de hooks](https://cursor.com/docs/hooks) de Cursor; el archivo incluye un marcador `version: 1` en el nivel superior. El manejador canonicaliza camelCase → PascalCase mediante `CURSOR_EVENT_MAP` para que las políticas integradas existentes funcionen sin cambios. El soporte de Cursor Agent está en **beta** mientras verificamos el formato en disco del transcript 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 cuatro 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 crea un pequeño shim de plugin generado que llama al binario de failproofai como subproceso y traduce la respuesta JSON de forma Claude del binario a la semántica del plugin (`throw new Error()` para deny, `client.session.prompt(...)` para instruct, sin operación para allow). Las sesiones se almacenan en la base de datos SQLite de opencode en `~/.local/share/opencode/opencode.db`; el visor de sesiones del dashboard 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 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 extensiones TypeScript al iniciar; el archivo de configuración es un array de cadenas plano `{"packages": ["./relative/path", …]}`. failproofai escribe una única entrada en el array de paquetes que apunta a su directorio `pi-extension/` incluido. La extensión internamente se suscribe a los eventos `tool_call` / `user_bash` / `input` / `session_start` de Pi y ejecuta `failproofai --hook --cli pi`; el manejador canonicaliza underscore_lower_snake_case → PascalCase mediante `PI_EVENT_MAP` para que las políticas integradas existentes funcionen sin cambios. El soporte de Pi está en **beta** mientras la API de extensiones y el formato de los registros de sesión de Pi 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 los 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 funcionen sin cambios. El evaluador de políticas emite la forma plana `{decision: "deny", reason}` de Gemini (preferida según el contrato exit-0 de la Regla de Oro de Gemini), `{hookSpecificOutput: {hookEventName, additionalContext}}` para la 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 del mundo real. Consulta la [documentación de hooks de Gemini CLI](https://geminicli.com/docs/hooks/). +- **`policies-config.json`** — le indica a failproofai qué políticas evaluar y con qué parámetros (compartido entre todas las CLIs de agentes) -Pasa `--cli claude|codex|copilot` para apuntar a un agente específico (separados por espacios o repetidos para cualquier subconjunto): +Pasa `--cli claude|codex|copilot|cursor|opencode|pi|gemini` para apuntar a un agente específico (separados por espacios o repetidos para cualquier subconjunto): ```bash failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project -failproofai policies --install --cli claude codex copilot +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 claude codex copilot cursor opencode pi gemini ``` -Cuando se omite `--cli`, `failproofai` detecta qué CLIs de agente están instaladas (`which claude` / `which codex` / `which copilot`): +Cuando se omite `--cli`, `failproofai` detecta qué CLIs de agente están instaladas (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): - **Una CLI detectada** — la selecciona automáticamente sin preguntar. -- **Múltiples CLIs detectadas** en una terminal interactiva — muestra un prompt de selección única con teclas de flecha: cuando hay dos CLIs presentes, las opciones son `Both`, ` only`, ` only`; con tres CLIs, la primera opción pasa a ser `All` (↑↓ para mover, Enter para seleccionar, ^C para salir). -- **Múltiples CLIs detectadas** en una ejecución no interactiva (CI, sin TTY) — instala para todas las CLIs detectadas sin preguntar. -- **Ninguna detectada** — usa `claude` como alternativa, con una advertencia de que no se encontró ningún binario de agente en PATH; el comando del hook se escribe igualmente para que se active en cuanto instales uno. +- **Varias CLIs detectadas** en una terminal interactiva — muestra un prompt de selección única con teclas de flecha, agrupado en una sección `Detected (N)` (con una fila agregada `Install for all N detected` + cada CLI detectada individualmente) y una sección `Not installed (M) · install hooks ahead of time` que lista 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. +- **Varias 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. -Puedes editar `policies-config.json` directamente en cualquier momento; los cambios tienen efecto inmediato en el próximo evento de hook sin necesidad de reiniciar. +Puedes editar `policies-config.json` directamente en cualquier momento; los cambios tienen efecto inmediato en el siguiente evento de hook sin necesidad de reiniciar. --- @@ -237,4 +245,4 @@ Confirma `.failproofai/policies-config.json` en tu repositorio: } ``` -Cada desarrollador puede entonces 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` (excluido con gitignore) para sus anulaciones personales sin afectar a sus compañeros de equipo. \ No newline at end of file diff --git a/docs/es/dashboard.mdx b/docs/es/dashboard.mdx index c20813b4..2f5e1ab4 100644 --- a/docs/es/dashboard.mdx +++ b/docs/es/dashboard.mdx @@ -1,14 +1,14 @@ --- -title: Panel de control -description: "Supervisa sesiones de agentes, revisa llamadas a herramientas y gestiona políticas" +title: Dashboard +description: "Monitorea sesiones de agentes, revisa llamadas a herramientas y gestiona políticas" icon: chart-line --- -El panel de control de failproofai es una aplicación web local para supervisar tus sesiones de agentes de IA y gestionar políticas. Consulta 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. --- -## Iniciar el panel de control +## Iniciar el dashboard ```bash failproofai @@ -16,7 +16,7 @@ failproofai Se abre en `http://localhost:8020`. -El panel de control lee directamente del 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. +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. --- @@ -24,11 +24,11 @@ El panel de control lee directamente del sistema de archivos: las carpetas de pr ### Proyectos -Lista todos los proyectos de Claude Code, OpenAI Codex y GitHub Copilot CLI _(beta)_ encontrados en tu máquina. Los proyectos de Claude se detectan desde `~/.claude/projects/` (o la ruta definida por `CLAUDE_PROJECTS_PATH`); los proyectos de Codex se detectan escaneando cada transcripción en `~/.codex/sessions///
/*.jsonl` y agrupándolos por el campo `cwd` registrado en el primer registro de cada sesión; los proyectos de Copilot CLI se detectan escaneando cada `~/.copilot/session-state//workspace.yaml` (configurable mediante `COPILOT_HOME`) y agrupándolos por su campo `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`. +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 todas las transcripciones en `~/.codex/sessions///
/*.jsonl` y agrupando por el `cwd` registrado en el primer registro de cada sesión; los proyectos de Copilot CLI se descubren escaneando cada `~/.copilot/session-state//workspace.yaml` (configurable mediante `COPILOT_HOME`) y agrupando por su campo `cwd`; los proyectos de Cursor Agent se descubren escaneando los metadatos por sesión en `~/.cursor/agent-sessions//` (configurable mediante `CURSOR_HOME`, con `conversations/` y `sessions/` como alternativas) buscando un escalar `cwd` en `meta.json` / `session.json` / `workspace.yaml`; los proyectos de OpenCode se descubren consultando su base de datos SQLite en `~/.local/share/opencode/opencode.db` mediante `opencode db --format json` (leemos las tablas `session` y `project` y agrupamos por `project_id`); los proyectos de Pi se descubren escaneando transcripciones JSONL por sesión en `~/.pi/agent/sessions//_.jsonl` (configurable mediante `PI_SESSIONS_DIR`) y extrayendo el `cwd` del primer registro de cada sesión; 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. Un proyecto que haya sido utilizado por múltiples CLIs se muestra como una sola fila con todos los badges correspondientes. Usa el 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`. Cada proyecto muestra: - Nombre del proyecto (derivado de la ruta de la carpeta) -- Una insignia de CLI — `Claude Code` (naranja), `OpenAI Codex` (morado) y/o `GitHub Copilot` (azul) +- 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) - Fecha de la actividad de sesión más reciente Haz clic en un proyecto para ver sus sesiones. @@ -39,23 +39,23 @@ Lista todas las sesiones dentro de un proyecto. Cada sesión muestra: - ID de sesión - Marcas de tiempo de inicio y fin - Número de llamadas a herramientas -- Recuento de actividad de hooks (políticas que se activaron) +- Conteo de actividad de hooks (políticas que se activaron) Usa el filtro de rango de fechas y la búsqueda por ID de sesión para reducir la lista. Las sesiones están paginadas. -Haz clic en una sesión para abrir el visor de sesiones. +Haz clic en una sesión para abrir el visor de sesión. -### Visor de sesiones +### Visor de sesión -El visor de sesiones responde la pregunta clave para los agentes autónomos: ¿qué hizo el agente y se mantuvo en el camino correcto? Una insignia de CLI junto al encabezado indica si la sesión es una transcripción de Claude Code o de OpenAI Codex. Muestra una línea de tiempo de todo lo que ocurrió en una sesión: +El visor de sesión responde la pregunta clave para los agentes autónomos: ¿qué hizo el agente y se mantuvo en el camino correcto? Un badge de CLI junto al encabezado indica si la sesión es una transcripción de Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi o Gemini CLI. 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 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 +- **Actividad de políticas** - Para cada llamada a herramienta, qué políticas se activaron y qué decisión retornaron -La barra de estadísticas en la parte superior muestra la duración de la sesión, el total de llamadas a herramientas y un resumen de las decisiones de los hooks (recuentos de allow / deny / instruct). +La barra de estadísticas en la parte superior muestra la duración de la sesión, el total de llamadas a herramientas y un resumen de las decisiones de los hooks (conteos de allow / deny / instruct). -Puedes exportar la sesión como un archivo ZIP o JSONL usando el botón de descarga. +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 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`. ### Políticas @@ -65,14 +65,14 @@ Una página con dos pestañas para gestionar políticas y revisar la actividad. - Activa o desactiva políticas individuales con un solo clic (escribe en `~/.failproofai/policies-config.json`) - Expande una política para configurar sus parámetros (para políticas que admiten `policyParams`) - - Instala o elimina hooks para un alcance determinado - - Establece una ruta de archivo de políticas personalizada + - Instala o elimina hooks para un ámbito determinado + - Define una ruta personalizada para el archivo de políticas - - Historial paginado completo de todos los eventos de hooks que se han activado en todas las sesiones - - Filtra por decisión, tipo de evento, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_), 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), 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`) y muestra la insignia de CLI correspondiente en el encabezado + - Historial completo y paginado de cada evento de hook que se ha activado en todas las sesiones + - Filtra por decisión, tipo de evento, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / 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 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`) y muestra el badge de CLI correspondiente en el encabezado @@ -80,13 +80,13 @@ Una página con dos pestañas para gestionar políticas y revisar la actividad. ## Actualización automática -El panel de control tiene un interruptor de actualización automática en la navegación superior. Cuando está activado, la página actual se actualiza periódicamente para mostrar nuevas sesiones y actividad de políticas a medida que aparecen. Es esencial para supervisar sesiones de agentes autónomos de larga duración. +El dashboard tiene un interruptor de actualización automática en la navegación superior. Cuando está habilitado, la página actual se actualiza periódicamente para mostrar nuevas sesiones y actividad de políticas a medida que aparecen. Es fundamental para monitorear sesiones de agentes autónomos de larga duración. --- ## Deshabilitar páginas -Si solo necesitas algunas partes del panel de control, establece `FAILPROOFAI_DISABLE_PAGES` con una lista separada por comas de nombres de páginas: +Si solo necesitas algunas partes del dashboard, establece `FAILPROOFAI_DISABLE_PAGES` con una lista de nombres de páginas separados por comas: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -98,13 +98,13 @@ Valores válidos: `policies`, `projects`. ## Tema -El panel de control admite modo claro y oscuro. Cámbialo con el botón en la barra de navegación. La preferencia se almacena en el almacenamiento local de tu navegador. +El dashboard admite modo claro y oscuro. Cámbialo con el botón en la barra de navegación. La preferencia se almacena en el almacenamiento local de tu navegador. --- ## Configurar la ruta de proyectos -De forma predeterminada, el panel de control lee desde el directorio estándar de proyectos de Claude Code. Puedes sobreescribirlo para configuraciones personalizadas: +Por defecto, el dashboard lee desde el directorio estándar de proyectos de Claude Code. Reemplázalo para configuraciones personalizadas: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -114,13 +114,13 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## Acceder desde un host que no sea localhost -Cuando ejecutas el panel de control en **modo desarrollo** (`npm run dev`) y accedes desde un nombre de host distinto a `localhost` — por ejemplo, un dominio personalizado, una IP remota o una URL tuneada — es posible que veas una advertencia como esta: +Al ejecutar el dashboard en **modo dev** (`npm run dev`) y acceder a él desde un nombre de host 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 desarrollo. Para permitir tu host, usa la flag `--allowed-origins`: +Esto es Next.js bloqueando el acceso de origen cruzado a su websocket de 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`: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -139,5 +139,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Esto solo aplica al modo desarrollo. Cuando ejecutas `failproofai` (modo producción), no existe websocket HMR ni problema de recurso de desarrollo de origen cruzado. +Esto solo aplica en modo dev. Al ejecutar `failproofai` (modo producción), no hay websocket de HMR ni problema de recursos dev de origen cruzado. \ No newline at end of file diff --git a/docs/es/getting-started.mdx b/docs/es/getting-started.mdx index e5d85d0a..d6f78780 100644 --- a/docs/es/getting-started.mdx +++ b/docs/es/getting-started.mdx @@ -30,21 +30,25 @@ 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 fallos antes de que causen daño. + + Las políticas son reglas que se ejecutan antes y después de cada llamada a herramientas 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 instalados (el `~/.claude/settings.json` de Claude Code, el `~/.codex/hooks.json` de OpenAI Codex o el `~/.copilot/hooks/failproofai.json` de GitHub Copilot CLI). Si hay más de uno presente, se te pedirá que elijas; usa `--cli claude codex copilot` (cualquier subconjunto) para omitir el prompt. + Esto escribe entradas de hook en los CLI 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 plugin generado de OpenCode en `~/.config/opencode/plugins/failproofai.mjs` más una entrada de registro en el array `plugin` de `~/.config/opencode/opencode.json`, el `~/.pi/agent/settings.json` de Pi, o el `~/.gemini/settings.json` de Gemini CLI). Si hay más de uno presente, se te pedirá que elijas; usa `--cli claude codex copilot cursor opencode pi gemini` (cualquier subconjunto) para omitir el mensaje. - El soporte de GitHub Copilot CLI está en **beta** — instala con `--cli copilot`. + El soporte para 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`. ```bash failproofai policies --install --scope project failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project + 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 block-sudo block-rm-rf sanitize-api-keys ``` @@ -63,7 +67,7 @@ bun add -g 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 ocurrido en el panel de control. + Inicia Claude Code como de costumbre. Si el agente intenta algo arriesgado, failproofai lo intercepta automáticamente. Déjalo en ejecución sin supervisión y revisa lo que ocurrió en el panel de control. @@ -82,16 +86,16 @@ 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 es bloqueada y el agente recibe una explicación -- **instruct** - se agrega contexto adicional al prompt del agente +- **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. +Las políticas se ejecutan en tu proceso local. No se envía nada a ningún servicio remoto. --- -## Configura políticas de equipo con políticas basadas en convención +## Configurar políticas de equipo mediante 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. @@ -102,7 +106,7 @@ La forma más rápida de establecer estándares de calidad en tu equipo es la co ``` - Copia los ejemplos de inicio o escribe los tuyos: + Copia los ejemplos de inicio o escribe los tuyos propios: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -133,19 +137,19 @@ La forma más rápida de establecer estándares de calidad en tu equipo es la co git commit -m "Add team quality policies" ``` - Cada miembro del equipo que tenga failproofai instalado recibirá estas políticas automáticamente. Sin configuración por desarrollador. + Cada miembro del equipo que tenga failproofai instalado adoptará estas políticas automáticamente. No se necesita configuración por desarrollador. -Confirma `.failproofai/policies/` en tu repositorio para que todo el equipo comparta los mismos estándares. A medida que el equipo descubra nuevos modos de fallo, agrega 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. +Confirma `.failproofai/policies/` en tu repositorio para que todo el equipo comparta los mismos estándares. A medida que el equipo descubra nuevos modos de fallo, agrega 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. --- ## Almacenamiento de datos -Toda la configuración y los registros permanecen en tu máquina: +Toda la configuración y los registros se guardan en tu máquina: | Ruta | Qué almacena | |------|--------------| @@ -153,7 +157,7 @@ Toda la configuración y los registros permanecen en tu máquina: | `~/.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 git) | -| `.failproofai/policies-config.local.json` | Ajustes personales (ignorado por git) | +| `.failproofai/policies-config.local.json` | Anulaciones personales (en gitignore) | --- @@ -163,7 +167,7 @@ Toda la configuración y los registros permanecen en tu máquina: failproofai policies --uninstall ``` -Elimina las entradas de hooks de `~/.claude/settings.json`. Los archivos de configuración en `~/.failproofai/` se conservan. +Elimina las entradas de hook de `~/.claude/settings.json`. Los archivos de configuración en `~/.failproofai/` se conservan. --- @@ -172,7 +176,7 @@ Elimina las entradas de hooks de `~/.claude/settings.json`. Los archivos de conf - Ámbitos y formato de archivos de configuración + Ámbitos y formato de los archivos de configuración @@ -184,7 +188,7 @@ Elimina las entradas de hooks de `~/.claude/settings.json`. Los archivos de conf - Monitorea sesiones y revisa la actividad de políticas + Supervisa sesiones y revisa la actividad de las políticas \ No newline at end of file diff --git a/docs/fr/architecture.mdx b/docs/fr/architecture.mdx index da5fc0a2..c42d8ab7 100644 --- a/docs/fr/architecture.mdx +++ b/docs/fr/architecture.mdx @@ -10,12 +10,12 @@ Ce document explique le fonctionnement interne de failproofai : comment le syst ## Vue d'ensemble -failproofai comporte deux sous-systèmes indépendants : +failproofai comprend deux sous-systèmes indépendants : 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'agent (Tableau de bord)** - Une application web Next.js pour surveiller les sessions d'agent 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 en tant que processus séparés et ne communiquent que via le système de fichiers. +Les deux sous-systèmes partagent les 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 qu'à travers 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 écrit 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,7 +44,7 @@ Lorsque vous exécutez `failproofai policies --install`, il écrit 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 un payload JSON sur stdin. ### Format du payload @@ -64,7 +64,7 @@ Pour les événements `PostToolUse`, le payload contient également `tool_result Le gestionnaire impose une limite de 1 Mo sur stdin. Les payloads dépassant cette taille sont ignorés et toutes les politiques autorisent implicitement. -### Format de la réponse +### Format de réponse **Refus (PreToolUse) :** ```json @@ -104,7 +104,7 @@ Le gestionnaire impose une limite de 1 Mo sur stdin. Les payloads dépassant cet **Autorisation avec message :** -`allow(message)` permet à une politique d'envoyer un 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 — il s'agit de la réponse du gestionnaire à Claude Code, tout comme les réponses de refus et d'instruction ci-dessus) : +`allow(message)` permet à une politique d'envoyer un 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, exactement 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 impose une limite de 1 Mo sur stdin. Les payloads dépassant cet } ``` - Code de sortie : `0` (l'opération est autorisée) -- 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 précédemment) +- Lorsque plusieurs politiques retournent `allow` avec un message, leurs messages sont joints par des sauts de ligne dans une seule chaîne `additionalContext` +- Si aucune politique ne fournit de message, stdout est vide (comportement inchangé) ### Pipeline de traitement @@ -139,13 +139,13 @@ stdin JSON → exit ``` -L'ensemble du processus s'exécute en moins de 100 ms pour les payloads typiques, sans aucun appel LLM. +L'ensemble du processus s'exécute en moins de 100 ms pour des payloads typiques, sans aucun appel LLM. --- ## Chargement de la configuration -`src/hooks/hooks-config.ts` implémente le chargement de la configuration sur trois niveaux. +`src/hooks/hooks-config.ts` implémente le chargement de configuration à trois niveaux. ```text [1] {cwd}/.failproofai/policies-config.json ← projet (priorité la plus haute) @@ -154,12 +154,12 @@ L'ensemble du processus s'exécute en moins de 100 ms pour les payloads typiques ``` Logique de fusion : -- `enabledPolicies` - union dédupliquée sur les trois fichiers +- `enabledPolicies` - union dédupliquée des 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 +- `customPoliciesPath` - le premier fichier qui le définit l'emporte +- `llm` - le premier fichier qui le définit l'emporte -Le tableau de bord web utilise `readHooksConfig()` (global uniquement) pour la lecture et l'écriture, car il n'est pas invoqué avec un répertoire de travail de projet. +Le tableau de bord web utilise `readHooksConfig()` (global uniquement) pour la lecture et l'écriture, car il n'est pas invoqué avec un cwd de projet. --- @@ -171,7 +171,7 @@ Pour chaque politique : 1. Rechercher le schéma `params` de la politique (si elle en possède un). 2. Lire `policyParams[policy.name]` depuis la configuration fusionnée. -3. Fusionner les valeurs fournies par l'utilisateur avec les valeurs par défaut du schéma pour produire `ctx.params`. +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. 6. Si le résultat est `instruct`, accumuler le message et continuer. @@ -180,7 +180,7 @@ Pour chaque politique : 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, exit 0). +- Sinon, émettre une réponse d'autorisation (stdout vide, code de sortie 0). --- @@ -204,15 +204,15 @@ interface BuiltinPolicyDefinition { } ``` -Les politiques qui acceptent des `params` déclarent un `PolicyParamsSchema` avec des types et des valeurs par défaut pour 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 protection contre les valeurs nulles, 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 null car les valeurs par défaut sont toujours appliquées en premier. -La correspondance de motifs à l'intérieur des politiques utilise des tokens de commande analysés (argv), et non une correspondance de chaînes brutes. Cela empêche les contournements 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). +La correspondance de motifs à l'intérieur des politiques utilise des tokens de commande analysés (argv), et non une correspondance brute sur les chaînes. Cela empêche les contournements 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 adossé à `globalThis` : +`src/hooks/custom-hooks-registry.ts` implémente un registre basé sur `globalThis` : ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -228,14 +228,14 @@ export function clearCustomHooks(): void { ... } // used in tests `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 vers un 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` se résolve vers le même registre `globalThis`. -4. Réécrire récursivement les imports locaux transitifs pour assurer la compatibilité ESM. +2. Résoudre en 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` 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 non trouvé, 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 journalisé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 quand même les politiques personnalisées suivantes (mais toutes les politiques intégrées ont déjà été exécutées à ce stade). @@ -258,7 +258,7 @@ Après chaque événement de hook, le gestionnaire ajoute une ligne JSONL à `~/ } ``` -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 léger). +Une ligne par politique ayant rendu une décision différente de allow. Les décisions d'autorisation ne sont pas journalisées (pour limiter la taille du fichier). --- @@ -275,31 +275,31 @@ app/ [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 ← Lire la configuration + liste des politiques + get-hooks-config.ts ← Lecture de la config + liste des politiques update-hooks-config.ts ← Activer/désactiver une politique update-policy-params.ts ← Mettre à jour les paramètres d'une politique - get-hook-activity.ts ← Paginer/rechercher dans le journal d'activité + get-hook-activity.ts ← Pagination/recherche dans le journal d'activité install-hooks-web.ts ← Installer/supprimer les hooks depuis le navigateur api/ - download/[project]/[session]/route.ts ← Exporter une session en ZIP/JSONL + download/[project]/[session]/route.ts ← Export de session CLI (JSONL ou JSON) ``` **Flux de données :** - 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 les Server Actions pour toutes les mutations (activation/désactivation, mise à jour des paramètres, installation/suppression). +- La page Politiques utilise des Server Actions pour toutes les mutations (activation/désactivation, mise à jour des paramètres, installation/suppression). - Le visualiseur de session analyse le format de transcription JSONL de Claude et affiche une chronologie des messages et des appels d'outils. **Décisions de conception clés :** -- Pas de base de données - tout l'état persistant est dans des fichiers plats (`~/.failproofai/`, `~/.claude/projects/`). -- Server Actions pour les mutations - pas d'API REST nécessaire pour les opérations CRUD. +- Pas de base de données - tout l'état persistant est dans des fichiers simples (`~/.failproofai/`, `~/.claude/projects/`). +- Server Actions pour les mutations - aucune 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 (activation des politiques, recherche dans l'activité, visualiseur de journaux). +- Composants client uniquement là où l'interactivité est nécessaire (bascules de politiques, recherche dans l'activité, visualiseur de logs). --- -## Structure des fichiers +## Organisation des fichiers ```text failproofai/ @@ -311,21 +311,21 @@ failproofai/ │ ├── policy-evaluator.ts # Moteur d'exécution des politiques │ ├── policy-registry.ts # Enregistrement et recherche des politiques │ ├── policy-types.ts # Interfaces TypeScript -│ ├── hooks-config.ts # Chargement de la configuration multi-niveaux -│ ├── custom-hooks-registry.ts # Registre de hooks adossé à globalThis +│ ├── hooks-config.ts # Chargement de configuration multi-niveaux +│ ├── custom-hooks-registry.ts # Registre de hooks basé sur globalThis │ ├── custom-hooks-loader.ts # Chargeur ESM pour les hooks JS utilisateur -│ ├── manager.ts # Opérations d'installation / suppression / liste +│ ├── manager.ts # Opérations install / remove / list │ ├── install-prompt.ts # Invite interactive de sélection des politiques │ ├── 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 basées sur l'IA) +│ └── 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 │ ├── paths.ts # Résolution des chemins système │ └── ... -├── components/ # Composants UI React partagés +├── components/ # Composants React UI partagés ├── 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 diff --git a/docs/fr/built-in-policies.mdx b/docs/fr/built-in-policies.mdx index 0a6f2870..848103ca 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 de hook et un nom d'outil spécifiques. Dix-neuf politiques acceptent des paramètres qui vous permettent d'ajuster 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 de hook spécifique et un nom d'outil. Dix-neuf politiques acceptent des paramètres qui permettent d'ajuster leur comportement sans écrire de code. Cinq politiques de workflow imposent un pipeline commit → push → PR → CI avant que Claude ne s'arrête. --- @@ -13,7 +13,7 @@ failproofai est livré avec 39 politiques intégrées qui interceptent les modes 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 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 | @@ -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 continuer. -- **`warn-`** — fournit à l'agent un contexte supplémentaire pour lui permettre de se corriger. -- **`sanitize-`** — supprime les données sensibles de la sortie d'un outil avant que l'agent ne les voie. +- **`warn-`** — fournit à l'agent un contexte supplémentaire pour qu'il puisse se corriger. +- **`sanitize-`** — expurge les données sensibles de la sortie d'outil avant que l'agent ne la voie. ### Espaces de noms -Chaque politique occupe un emplacement `/`. Les politiques intégrées appartiennent à l'espace de noms **`exospherehost/`** — par exemple, `exospherehost/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 **`exospherehost/`** — par exemple, `exospherehost/sanitize-jwt`. L'espace de noms évite les collisions lorsque vous chargez également des politiques personnalisées ou tierces ayant des noms courts similaires. -Dans votre configuration, vous pouvez référencer une politique intégrée par son nom court ou son nom qualifié ; les deux formes désignent 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 résolvent vers la même politique : ```json { @@ -44,13 +44,13 @@ Dans votre configuration, vous pouvez référencer une politique intégrée par } ``` -Si un nom ne contient pas de `/`, failproofai considère qu'il appartient à l'espace de noms par défaut `exospherehost`. 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 le considère comme appartenant à l'espace de noms par défaut `exospherehost`. Les noms contenant déjà un `/` (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 hint est ajouté au message deny ou instruct que voit Claude, fournissant 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 plus de détails. +Toutes les politiques supportent un champ optionnel `hint` dans `policyParams`. Ce hint est ajouté au message deny ou instruct que Claude voit, apportant des conseils concrets 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. --- @@ -62,15 +62,15 @@ Empêche les agents d'exécuter des opérations difficiles à annuler ou suscept ### `block-sudo` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse toute commande `sudo`. +**Défaut :** Bloque toute commande `sudo`. -Bloque les invocations qui incluent le mot-clé `sudo`. La correspondance de motif 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 est effectuée 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 :** | Paramètre | Type | Défaut | Description | |-----------|------|--------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commande exacts autorisés. Chaque entrée est comparée aux tokens argv analysés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes autorisés. Chaque entrée est comparée aux tokens argv analysés. | **Exemple :** @@ -84,7 +84,7 @@ 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 *`). @@ -95,7 +95,7 @@ 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. +**Défaut :** Bloque `rm -rf`, `rm -fr` et les formes similaires de suppression récursive. **Paramètres :** @@ -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. +**Défaut :** Bloque `curl | bash`, `curl | sh`, `wget | bash` et les motifs similaires. Aucun paramètre. @@ -129,7 +129,7 @@ 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`). +**Défaut :** Bloque les commandes qui désinstalleraient ou désactiveraient failproofai lui-même (ex. `npm uninstall failproofai`, `failproofai policies --uninstall`). Aucun paramètre. @@ -137,20 +137,20 @@ Aucun paramètre. ## 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 qui ont légitimement besoin d'appeler `kubectl`, `terraform`, etc. ne seront pas perturbés à moins que vous n'activiez la politique. Une fois activée, chaque invocation de la CLI concernée 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 la politique. Une fois activée, toute invocation du CLI correspondant est bloquée, à moins que la commande ne corresponde à une entrée dans `allowPatterns`. -La grammaire des motifs est la même que pour [`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. +La grammaire des motifs est identique à celle de [`block-sudo`](#block-sudo) : les tokens sont comparés à 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 pour prévenir les contournements par injection. ### `block-kubectl` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse toute invocation de `kubectl`. +**Défaut :** Bloque toute invocation `kubectl`. **Paramètres :** | Paramètre | Type | Défaut | Description | |-----------|------|--------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commande kubectl autorisés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes kubectl autorisés. | **Exemple :** @@ -164,20 +164,20 @@ 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). +**Défaut :** Bloque toute invocation `terraform` ou `tofu` (OpenTofu). **Paramètres :** | Paramètre | Type | Défaut | Description | |-----------|------|--------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commande terraform/tofu autorisés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes terraform/tofu autorisés. | **Exemple :** @@ -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 de la CLI `aws`. +**Défaut :** Bloque toute invocation du CLI `aws`. **Paramètres :** | Paramètre | Type | Défaut | Description | |-----------|------|--------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commande CLI aws autorisés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes du CLI aws autorisés. | **Exemple :** @@ -221,13 +221,13 @@ Avec cette configuration, `kubectl get pods` est autorisé mais `kubectl apply - ### `block-gcloud` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse toute invocation de la CLI `gcloud` (Google Cloud). +**Défaut :** Bloque toute invocation du CLI `gcloud` (Google Cloud). **Paramètres :** | Paramètre | Type | Défaut | Description | |-----------|------|--------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commande gcloud autorisés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes gcloud autorisés. | **Exemple :** @@ -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 de la CLI `az` (Azure). +**Défaut :** Bloque toute invocation du CLI `az` (Azure). **Paramètres :** | Paramètre | Type | Défaut | Description | |-----------|------|--------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commande CLI az autorisés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes du CLI az autorisés. | **Exemple :** @@ -271,13 +271,13 @@ 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`. +**Défaut :** Bloque toute invocation `helm`. **Paramètres :** | Paramètre | Type | Défaut | Description | |-----------|------|--------|-------------| -| `allowPatterns` | `string[]` | `[]` | Préfixes de commande helm autorisés. | +| `allowPatterns` | `string[]` | `[]` | Préfixes de commandes helm autorisés. | **Exemple :** @@ -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 de la CLI `gh` suivantes, qui modifient l'état ou déclenchent des pipelines : +**Défaut :** Bloque les sous-commandes du CLI `gh` 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 comme `gh pr view`, `gh pr list`, `gh run list`, `gh release view` et `gh api repos/.../...` ne sont **pas** concernées 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** interceptées par cette politique — elles sont couramment nécessaires pour les vérifications de workflow (y compris le `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 :** @@ -329,12 +329,12 @@ Les sous-commandes `gh` en lecture seule comme `gh pr view`, `gh pr list`, `gh r ## Secrets (sanitizers) -Empêche les agents de faire fuiter des identifiants dans leur contexte ou leur sortie. Les politiques de type sanitizer 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 renvoyée à Claude. Si un motif de secret est détecté, la politique retourne une décision de refus qui empêche le renvoi de la sortie. +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, ces politiques inspectent la sortie avant qu'elle ne soit renvoyée à Claude. Si un motif de secret est détecté, la politique retourne une décision deny qui empêche la sortie d'être transmise. ### `sanitize-jwt` **Événement :** PostToolUse (tous les outils) -**Par défaut :** Masque les tokens JWT (trois segments base64url séparés par des `.`). +**Défaut :** Expurge les tokens JWT (trois segments base64url séparés par `.`). Aucun paramètre. @@ -343,7 +343,7 @@ Aucun paramètre. ### `sanitize-api-keys` **Événement :** PostToolUse (tous les outils) -**Par défaut :** Masque les formats courants de clés API : Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), clés d'accès AWS (`AKIA`), clés Stripe (`sk_live_`, `sk_test_`) et clés API Google (`AIza`). +**Défaut :** Expurge les formats de clés API courants : Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), clés d'accès AWS (`AKIA`), clés Stripe (`sk_live_`, `sk_test_`) et clés API Google (`AIza`). **Paramètres :** @@ -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 base de données contenant des identifiants intégrés (ex. `postgresql://user:password@host/db`). +**Défaut :** Expurge les chaînes de connexion de base de données contenant des identifiants intégrés (ex. `postgresql://user:password@host/db`). Aucun paramètre. @@ -380,7 +380,7 @@ Aucun paramètre. ### `sanitize-private-key-content` **Événement :** PostToolUse (tous les outils) -**Par défaut :** Masque les blocs PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, etc.). +**Défaut :** Expurge les blocs PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, etc.). 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. +**Défaut :** Expurge les en-têtes `Authorization: Bearer ` dont le token fait 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. +**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`. +**Défaut :** Bloque les commandes qui affichent les variables d'environnement : `printenv`, `env`, `echo $VAR`. Aucun paramètre. @@ -426,13 +426,13 @@ 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 définie par `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 que Claude se soit déplacé dans un sous-répertoire avec `cd`. +**Défaut :** Bloque la lecture de fichiers 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 direct garantit que la limite reste stable même après que Claude se déplace dans un sous-répertoire avec `cd`. **Paramètres :** | Paramètre | Type | Défaut | Description | |-----------|------|--------|-------------| -| `allowPaths` | `string[]` | `[]` | Préfixes de chemin absolu autorisés même s'ils sont en dehors de la racine du projet. | +| `allowPaths` | `string[]` | `[]` | Préfixes de chemins absolus autorisés même en dehors de la racine du projet. | **Exemple :** @@ -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`. +**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 :** @@ -480,13 +480,13 @@ Prévient les pushs accidentels, les force-pushs et les erreurs de branches diff ### `block-push-master` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse `git push origin main` et `git push origin master`. +**Défaut :** Bloque `git push origin main` et `git push origin master`. **Paramètres :** | Paramètre | Type | Défaut | Description | |-----------|------|--------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Noms de branches vers lesquelles le push direct est interdit. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Noms de branches sur lesquelles le push direct est interdit. | **Exemple :** @@ -501,7 +501,7 @@ Prévient les pushs accidentels, les force-pushs et les erreurs de branches diff ``` -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 vers toutes les branches (désactivant effectivement cette politique sans la retirer de `enabledPolicies`), définissez `protectedBranches: []`. --- @@ -509,20 +509,20 @@ 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 le checkout direct des branches `main` ou `master`. +**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 branches (`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 dont le checkout direct est interdit. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Noms de branches sur lesquelles commit/merge/rebase/cherry-pick est interdit. | --- ### `block-force-push` **Événement :** PreToolUse (Bash) -**Par défaut :** Refuse `git push --force` et `git push -f`. +**Défaut :** Bloque `git push --force` et `git push -f`. Aucun paramètre spécifique à la politique. Utilisez le [`hint`](/fr/configuration#hint-cross-cutting) transversal pour suggérer des alternatives : @@ -541,7 +541,7 @@ Aucun paramètre spécifique à la politique. Utilisez le [`hint`](/fr/configura ### `warn-git-amend` **Événement :** PreToolUse (Bash) -**Par défaut :** Demande à Claude de procéder avec précaution lors de l'exécution de `git commit --amend`. Ne bloque pas la commande. +**Défaut :** Demande à Claude de procéder avec précaution lors de l'exécution de `git commit --amend`. Ne bloque pas la commande. Aucun paramètre. @@ -550,7 +550,7 @@ Aucun paramètre. ### `warn-git-stash-drop` **Événement :** PreToolUse (Bash) -**Par défaut :** Demande à Claude de confirmer avant d'exécuter `git stash drop`. Ne bloque pas la commande. +**Défaut :** Demande à Claude de confirmer avant d'exécuter `git stash drop`. Ne bloque pas la commande. Aucun paramètre. @@ -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. +**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. @@ -572,7 +572,7 @@ Intercepte les opérations SQL destructives avant qu'elles ne s'exécutent sur v ### `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`. +**Défaut :** Demande à Claude de confirmer avant d'exécuter du SQL contenant `DROP TABLE`, `DROP DATABASE` ou `DELETE` sans clause `WHERE`. Aucun paramètre. @@ -581,7 +581,7 @@ Aucun paramètre. ### `warn-schema-alteration` **Événement :** PreToolUse (Bash) -**Par défaut :** Demande à Claude de confirmer avant d'exécuter des instructions `ALTER TABLE`. +**Défaut :** Demande à Claude de confirmer avant d'exécuter des instructions `ALTER TABLE`. Aucun paramètre. @@ -594,7 +594,7 @@ Fournit aux agents un contexte supplémentaire avant des opérations potentielle ### `warn-large-file-write` **Événement :** PreToolUse (Write) -**Par défaut :** Demande à Claude de confirmer avant d'écrire des fichiers de plus de 1024 Ko. +**Défaut :** Demande à Claude de confirmer avant d'écrire des fichiers de plus de 1024 Ko. **Paramètres :** @@ -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 payloads en stdin. Pour tester cette politique avec du contenu de petite taille, définissez `thresholdKb` à une valeur bien inférieure à 1024. +Le gestionnaire de hook impose une limite de 1 Mo sur stdin pour les charges utiles. Pour tester cette politique avec du contenu de petite taille, définissez `thresholdKb` à une valeur bien inférieure à 1024. --- @@ -623,7 +623,7 @@ Le gestionnaire de hook impose une limite de 1 Mo sur les payloads en stdin. Pou ### `warn-package-publish` **Événement :** PreToolUse (Bash) -**Par défaut :** Demande à Claude de confirmer avant d'exécuter `npm publish`. +**Défaut :** Demande à Claude de confirmer avant d'exécuter `npm publish`. Aucun paramètre. @@ -632,7 +632,7 @@ Aucun paramètre. ### `warn-background-process` **Événement :** PreToolUse (Bash) -**Par défaut :** Demande à Claude d'être prudent lors du lancement de processus en arrière-plan via `nohup`, `&`, `disown` ou `screen`. +**Défaut :** Demande à Claude d'être prudent lors du lancement de processus en arrière-plan via `nohup`, `&`, `disown` ou `screen`. Aucun paramètre. @@ -641,7 +641,7 @@ Aucun paramètre. ### `warn-global-package-install` **Événement :** PreToolUse (Bash) -**Par défaut :** Demande à Claude de confirmer avant d'exécuter `npm install -g`, `yarn global add` ou `pip install` sans environnement virtuel. +**Défaut :** Demande à Claude de confirmer avant d'exécuter `npm install -g`, `yarn global add` ou `pip install` sans environnement virtuel. Aucun paramètre. @@ -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é. Une fois activé, bloque toute commande de gestionnaire de paquets non présente dans la liste `allowed` et demande à Claude de réécrire la commande en utilisant un gestionnaire autorisé. +**Défaut :** Désactivé. Lorsqu'il est activé, bloque toute commande de gestionnaire de paquets ne figurant pas dans 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 des gestionnaires de paquets autorisés. Tout gestionnaire détecté absent de cette liste est bloqué. Quand la liste est 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 des gestionnaires de paquets autorisés. Tout gestionnaire détecté absent de cette liste est bloqué. Lorsqu'elle est vide, la politique est sans effet. | +| `blocked` | string[] | `[]` | Noms de gestionnaires supplémentaires à bloquer au-delà de la liste intégrée (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,18 +679,18 @@ 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` figure 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 telles que `uv pip install flask` sont autorisées car `uv` figure dans la liste d'autorisation et est vérifié en premier. --- -## Comportement des agents IA +## Comportement de l'IA -Détecte quand les agents sont bloqués ou se comportent de manière inattendue. +Détecte quand les agents sont bloqués ou se comportent de façon inattendue. ### `warn-repeated-tool-calls` **Événement :** PreToolUse (tous les outils) -**Par défaut :** Demande à Claude de reconsidérer lorsque le même outil est appelé 3 fois ou plus avec des paramètres identiques — signe courant que l'agent est bloqué dans une boucle. +**Défaut :** Demande à Claude de reconsidérer lorsque le même outil est appelé 3 fois ou plus avec des paramètres identiques — signe courant que l'agent est coincé dans une boucle. Aucun paramètre. @@ -698,14 +698,14 @@ Aucun paramètre. ## Workflow -Impose un workflow de fin de session rigoureux. Ces politiques se déclenchent sur l'événement **Stop** et empêchent Claude de s'arrêter tant que chaque condition n'est pas 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 (le refus court-circuite). +Impose un workflow de fin de session discipliné. Ces politiques se déclenchent sur l'événement **Stop** et empêchent Claude de s'arrêter tant que chaque condition n'est pas remplie. Elles suivent une chaîne de dépendances naturelle : commit → push → PR → CI. Si une politique bloque, 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. ### `require-commit-before-stop` **Événement :** Stop -**Par défaut :** Refuse l'arrêt lorsqu'il y a des modifications non committées (fichiers modifiés, indexés ou non suivis). Retourne un message informatif lorsque le répertoire de travail est propre. +**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. @@ -714,7 +714,7 @@ Aucun paramètre. ### `require-push-before-stop` **Événement :** Stop -**Par défaut :** Refuse l'arrêt lorsqu'il y a des commits non poussé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. Passe en mode ouvert si aucun remote n'est configuré. +**Défaut :** Bloque l'arrêt lorsqu'il y a des commits non poussé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 :** @@ -739,14 +739,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`). +**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 fusion. 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`). Aucun paramètre. -Cette politique nécessite que [GitHub CLI](https://cli.github.com/) (`gh`) soit installé et authentifié. -Exécutez `gh auth login` avec un token d'accès personnel ayant le scope `repo` pour un accès en lecture aux -pull requests. Si `gh` n'est pas installé ou non authentifié, la politique passe en mode ouvert et signale la raison à Claude. +Cette politique nécessite que le [GitHub CLI](https://cli.github.com/) (`gh`) soit installé et authentifié. +Exécutez `gh auth login` avec un token d'accès personnel ayant le scope `repo` pour l'accès en lecture aux +pull requests. Si `gh` n'est pas installé ou non authentifié, la politique est fail-open et en rapporte la raison à Claude. --- @@ -754,24 +754,24 @@ pull requests. Si `gh` n'est pas installé ou non authentifié, la politique pas ### `require-no-conflicts-before-stop` **Événement :** Stop -**Par défaut :** Refuse l'arrêt lorsque la branche courante ne peut pas être fusionnée proprement dans la branche de base. La politique vérifie d'abord qu'il existe une PR `OPEN` sur GitHub pour la branche — sans PR, il n'y a pas de cible de fusion à contrôler, donc toute la politique court-circuite vers l'autorisation. Une fois qu'une PR `OPEN` est confirmée, deux sondes indépendantes s'exécutent : +**Défaut :** Bloque 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 à imposer, donc toute la politique court-circuite vers allow. Une fois une PR `OPEN` confirmée, deux sondes indépendantes s'exécutent : -1. **Local** — `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 pré-vérification. Détecte les conflits qu'un `origin/` local obsolète manquerait (ex. quelqu'un a mergé une PR en conflit 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 ~10 secondes et de revérifier avant de tenter de s'arrêter à nouveau — 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 nomme les fichiers en conflit afin 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 obsolète manquerait (ex. quelqu'un a fusionné 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 environ 10 secondes et de revérifier avant de tenter de s'arrêter à nouveau — cela évite les faux négatifs pendant que GitHub recalcule. -Court-circuite entièrement (autorise) dans les cas suivants : `gh` non installé, aucune PR n'existe pour la branche, l'état de la PR n'est pas `OPEN` (ex. `MERGED`, `CLOSED`), ou `gh pr view` retourne une sortie non analysable. Passe également en mode ouvert lorsque `origin/` est absent localement ou lorsqu'aucun commit n'est en avance sur la base — ces court-circuits de niveau 1 consultent tout de même la fusionnabilité PR mise en cache avant d'autoriser. +Ignore entièrement (autorise) dans les cas suivants : `gh` non installé, aucune PR n'existe 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 couche 1 consultent tout de même la fusion de PR en cache avant d'autoriser. **Paramètres :** | Paramètre | Type | Défaut | Description | |-----------|------|--------|-------------| -| `baseBranch` | `string` | `"main"` | Branche de base à vérifier pour les conflits. | +| `baseBranch` | `string` | `"main"` | Branche de base contre laquelle vérifier les conflits. | -GitHub CLI (`gh`) est requis pour cette politique. La politique utilise `gh pr view` pour confirmer +Le GitHub CLI (`gh`) est requis pour cette politique. La politique utilise `gh pr view` pour confirmer qu'une PR `OPEN` existe avant d'exécuter toute sonde de conflit — sans `gh`, la politique -court-circuite vers l'autorisation. Exécutez `gh auth login` avec un token d'accès personnel ayant le scope -`repo` pour un accès en lecture aux pull requests. +court-circuite vers allow. Exécutez `gh auth login` avec un token d'accès personnel ayant le +scope `repo` pour l'accès en lecture aux pull requests. --- @@ -779,14 +779,14 @@ court-circuite vers l'autorisation. Exécutez `gh auth login` avec un token d'ac ### `require-ci-green-before-stop` **Événement :** Stop -**Par défaut :** Refuse l'arrêt lorsque les vérifications CI échouent ou sont toujours en cours sur la branche courante. Vérifie à la fois les exécutions de workflows GitHub Actions et les vérifications de bots tiers (ex. CodeRabbit, SonarCloud, Codecov). Traite les conclusions `skipped` et `cancelled` comme un succès. Retourne un message informatif lorsque toutes les vérifications sont passées. +**Défaut :** Bloque l'arrêt lorsque les vérifications CI échouent ou sont toujours en cours sur la branche courante. Vérifie à la fois les exécutions de workflow GitHub Actions et les vérifications de bots tiers (ex. CodeRabbit, SonarCloud, Codecov). Traite les conclusions `skipped` et `cancelled` comme des succès. Retourne un message informatif lorsque toutes les vérifications passent. Aucun paramètre. -Cette politique nécessite que [GitHub CLI](https://cli.github.com/) (`gh`) soit installé et authentifié. -Exécutez `gh auth login` avec un token d'accès personnel ayant le scope `repo` pour un accès en lecture aux -exécutions de workflows Actions et à l'API Checks. Si `gh` n'est pas installé ou non authentifié, la politique passe en mode ouvert et signale la raison à Claude. +Cette politique nécessite que le [GitHub CLI](https://cli.github.com/) (`gh`) soit installé et authentifié. +Exécutez `gh auth login` avec un token d'accès personnel ayant le scope `repo` pour l'accès en lecture aux +exécutions de workflow Actions et à l'API Checks. Si `gh` n'est pas installé ou non authentifié, la politique est fail-open et en rapporte la raison à Claude. --- @@ -795,7 +795,7 @@ exécutions de workflows Actions et à l'API Checks. Si `gh` n'est pas installé ## 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/configuration.mdx b/docs/fr/configuration.mdx index 550138b6..5fc6a17c 100644 --- a/docs/fr/configuration.mdx +++ b/docs/fr/configuration.mdx @@ -1,10 +1,10 @@ --- title: Configuration -description: "Format du fichier de configuration, système à trois portées et règles de fusion" +description: "Format du fichier de config, système à trois portées 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 depuis où les politiques personnalisées sont chargé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éficiera 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 d'où les politiques personnalisées sont chargé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. --- @@ -13,12 +13,12 @@ failproofai utilise des fichiers de configuration JSON pour contrôler quelles p Il existe trois portées de configuration, évaluées 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 | +| **local** | `.failproofai/policies-config.local.json` | Remplacements personnels par dépôt, ignorés 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 existants pour le répertoire de travail courant. +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 @@ -42,11 +42,11 @@ resolved: { allowPatterns: ["sudo apt-get update"] } ← project l'emporte, gl ``` ```text -project: (pas d'entrée block-sudo) -local: (pas d'entrée block-sudo) +project: (aucune entrée block-sudo) +local: (aucune entrée block-sudo) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← repli sur global +resolved: { allowPatterns: ["sudo systemctl status"] } ← transmission au global ``` **`customPoliciesPath`** — la première portée qui le définit l'emporte. @@ -110,17 +110,17 @@ 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). +Remplacements 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). -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 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 lors du déclenchement du hook, mais signalées comme avertissements lors de l'exécution de `failproofai policies`. +Les clés inconnues dans le bloc de paramètres d'une politique sont silencieusement ignorées au moment du déclenchement du hook, mais signalées comme avertissements 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 retourne `deny` ou `instruct`. Utilisez-le pour donner à Claude des conseils concrets sans modifier la politique elle-même. Fonctionne avec n'importe quel type de politique — intégrée, personnalisée (`custom/`), convention de projet (`.failproofai-project/`) ou convention utilisateur (`.failproofai-user/`). @@ -141,34 +141,34 @@ Fonctionne avec n'importe quel type de politique — intégrée, personnalisée } ``` -Lorsque `block-force-push` refuse, Claude voit : *"Force-pushing is blocked. Try creating a fresh branch instead."* +Lorsque `block-force-push` refuse, Claude voit : *« Force-pushing is blocked. Try creating a fresh branch instead. »* -Les valeurs non-chaînes et les chaînes vides sont silencieusement ignorées. Si `hint` n'est pas défini, le comportement reste inchangé (rétrocompatible). +Les valeurs non-chaînes et les chaînes vides sont silencieusement ignorées. Si `hint` n'est pas défini, le comportement est inchangé (compatible avec les versions antérieures). ### `customPoliciesPath` Type : `string` (chemin absolu) -Chemin vers un fichier JavaScript contenant des politiques de hook personnalisées. Ce champ est défini automatiquement par `failproofai policies --install --custom ` (le chemin est résolu en absolu avant d'être enregistré). +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é). -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 [Politiques personnalisées](/fr/custom-policies) pour les détails de création. -### Politiques basées sur les conventions +### Politiques basées sur des 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. -**Aucune configuration nécessaire :** 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`. Il suffit de déposer des fichiers dans le répertoire et ils sont 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 les deux analysés. Tous les fichiers correspondants des deux niveaux sont chargés (contrairement à `customPoliciesPath` qui utilise la règle premier-arrivé-premier-servi). +**Chargement par union :** Les répertoires de convention de projet et d'utilisateur sont tous deux analysés. Tous les fichiers correspondants des deux niveaux sont chargés (contrairement à `customPoliciesPath` qui utilise la règle premier-arrivé-premier-servi). -Consultez [Politiques personnalisées](/fr/custom-policies) pour plus de détails et d'exemples. +Consultez [Politiques personnalisées](/fr/custom-policies) pour plus de détails et des exemples. ### `llm` @@ -194,29 +194,37 @@ Les commandes `policies --install` et `policies --uninstall` écrivent dans le f - **Paramètres de la CLI d'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` à clé OS de Copilot avec `timeoutSec` ; le fichier porte un marqueur de niveau supérieur `version: 1`. 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. -- **`policies-config.json`** — indique à failproofai quelles politiques évaluer et avec quels paramètres (partagé entre toutes les CLI d'agent) + - **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` propres à l'OS de Copilot avec `timeoutSec` ; le fichier porte un marqueur de niveau supérieur `version: 1`. La prise en charge de Copilot CLI est en **bêta** pendant que nous vérifions le schéma des enregistrements `events.jsonl` (non spécifié dans la documentation publique) sur davantage de sessions réelles. + - **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 `{type, command, timeout}` 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 de Cursor](https://cursor.com/docs/hooks) ; le fichier porte un marqueur de niveau supérieur `version: 1`. Le handler 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 du transcript sur disque de Cursor (non spécifié dans la documentation publique) sur davantage d'installations réelles. + - **OpenCode _(bêta)_** : `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (utilisateur), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (projet) — OpenCode n'a pas de portée `local`. Contrairement aux quatre autres CLIs, OpenCode **n'a pas de système de hooks 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** le mode de chargement des plugins sous 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 deny, `client.session.prompt(...)` pour instruct, no-op pour allow). Les sessions résident dans la base de données 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 sur davantage de sessions réelles. Consultez la [documentation des plugins OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(bêta)_** : `~/.pi/agent/settings.json` (utilisateur), `/.pi/settings.json` (projet) — Pi n'a pas de 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/` inclus. 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-shell ; le handler canonicalise underscore_lower_snake_case → PascalCase via `PI_EVENT_MAP` afin que les politiques intégrées existantes se déclenchent sans modification. 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 `{type, command, timeout}` de Claude enveloppée dans le schéma de matcher `{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 handler les mappe aux noms canoniques de Claude via `GEMINI_EVENT_MAP`. Les noms d'outils sont en snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — le handler les 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 (préférée selon le contrat exit-0 de la règle d'or 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) -Passez `--cli claude|codex|copilot` pour cibler un agent spécifique (séparé par des espaces ou répété pour un sous-ensemble quelconque) : +Passez `--cli claude|codex|copilot|cursor|opencode|pi|gemini` pour cibler un agent spécifique (séparés par des espaces ou répétés pour n'importe quel sous-ensemble) : ```bash failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project -failproofai policies --install --cli claude codex copilot +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 claude codex copilot cursor opencode pi gemini ``` -Lorsque `--cli` est omis, `failproofai` détecte les CLI d'agent installées (`which claude` / `which codex` / `which copilot`) : +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`) : -- **Une CLI détectée** — sélectionne automatiquement cette CLI sans demande de confirmation. -- **Plusieurs CLI détectées** dans un terminal interactif — affiche une invite de sélection unique par touches directionnelles : lorsque deux CLI sont présentes, les choix sont `Both`, ` only`, ` only` ; avec trois CLI, la première option devient `All` (↑↓ pour naviguer, Entrée pour sélectionner, ^C pour quitter). -- **Plusieurs CLI détectées** lors d'une exécution non-interactive (CI, pas de TTY) — installe pour toutes les CLI détectées sans demande de confirmation. -- **Aucune détectée** — repli sur `claude`, avec un avertissement qu'aucun binaire d'agent n'a été trouvé dans PATH ; la commande de hook est quand même écrite et s'activera dès que vous en installerez un. +- **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 directionnelles regroupée en une section `Detected (N)` (avec une ligne agrégée `Install for all N detected` + chaque CLI détectée individuellement) et une section `Not installed (M) · install hooks ahead of time` listant toutes les CLIs supportées non détectées comme option d'installation anticipée (↑↓ pour naviguer, 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, sans TTY) — installe pour toutes les CLIs détectées sans invite. +- **Aucune détectée** — revient à `claude`, avec un avertissement qu'aucun binaire d'agent n'a été trouvé dans le PATH ; la commande de hook est tout de même écrite afin de s'activer dès que vous en installez un. -Vous pouvez modifier `policies-config.json` directement à tout moment ; les modifications prennent effet immédiatement au prochain événement de hook, sans redémarrage nécessaire. +Vous pouvez modifier `policies-config.json` directement à tout moment ; les modifications prennent effet immédiatement au prochain événement de hook sans redémarrage. --- -## Exemple : configuration au niveau projet avec les paramètres par défaut de l'é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 : @@ -237,4 +245,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 ses remplacements personnels sans affecter ses coéquipiers. \ No newline at end of file diff --git a/docs/fr/dashboard.mdx b/docs/fr/dashboard.mdx index 4f3135e6..1e98baf5 100644 --- a/docs/fr/dashboard.mdx +++ b/docs/fr/dashboard.mdx @@ -1,14 +1,14 @@ --- -title: Tableau de bord -description: "Surveillez les sessions d'agents, examinez les appels d'outils et gérez les politiques" +title: Dashboard +description: "Surveillez les sessions des agents, examinez les appels d'outils et gérez les politiques" icon: chart-line --- -Le tableau de bord failproofai est une application web locale permettant de surveiller vos sessions d'agents IA et de gérer les politiques. Voyez ce que vos agents ont fait pendant votre absence. +Le dashboard failproofai est une application web locale pour surveiller vos sessions d'agents IA et gérer les politiques. Voyez ce que vos agents ont fait pendant votre absence. --- -## Démarrer le tableau de bord +## Démarrer le dashboard ```bash failproofai @@ -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. Rien n'est écrit vers un service distant. +Le dashboard 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,12 +24,12 @@ Le tableau de bord lit directement depuis le système de fichiers — vos dossie ### Projets -Liste tous les projets Claude Code, OpenAI Codex et GitHub Copilot 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 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 son champ `cwd`. Un projet utilisé par plusieurs CLI s'affiche sur une seule ligne avec tous les badges correspondants. Utilisez le menu déroulant **CLI** au-dessus du tableau pour filtrer par un agent CLI spécifique ; l'URL conserve votre sélection sous la forme `?cli=claude|codex|copilot`. +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 regroupés par le `cwd` enregistré dans le premier enregistrement de chaque session ; les projets Copilot CLI sont découverts en analysant chaque `~/.copilot/session-state//workspace.yaml` (configurable via `COPILOT_HOME`) et regroupés par son champ `cwd` ; les projets Cursor Agent sont découverts en analysant les métadonnées par session sous `~/.cursor/agent-sessions//` (configurable via `CURSOR_HOME`, avec `conversations/` et `sessions/` sondés comme alternatives) pour un scalaire `cwd` dans `meta.json` / `session.json` / `workspace.yaml` ; les projets OpenCode sont découverts en interrogeant sa base de données SQLite à `~/.local/share/opencode/opencode.db` via `opencode db --format json` (nous lisons les tables `session` et `project` et regroupons par `project_id`) ; les projets Pi sont découverts en analysant les transcripts JSONL par session sous `~/.pi/agent/sessions//_.jsonl` (configurable via `PI_SESSIONS_DIR`) et en extrayant le `cwd` du premier enregistrement de chaque session ; les 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 à partir du marqueur de texte `.project_root` adjacent. Un projet utilisé par plusieurs CLI s'affiche sur une seule ligne avec tous les badges correspondants. Utilisez le menu déroulant **CLI** au-dessus du tableau pour filtrer par un agent CLI spécifique ; l'URL conserve votre sélection sous la forme `?cli=claude|codex|copilot|cursor|opencode|pi|gemini`. Chaque projet affiche : - Le nom du projet (dérivé du chemin du dossier) -- Un badge CLI — `Claude Code` (orange), `OpenAI Codex` (violet) et/ou `GitHub Copilot` (bleu) -- La date de l'activité de session la plus récente +- Un badge CLI — `Claude Code` (orange), `OpenAI Codex` (violet), `GitHub Copilot` (bleu), `Cursor Agent` (émeraude), `OpenCode` (ambre), `Pi` (rose) et/ou `Gemini CLI` (bleu ciel) +- La date de la dernière activité de session Cliquez sur un projet pour voir ses 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,15 +47,15 @@ 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é dans les rails ? Un badge CLI à côté de l'en-tête indique si la session est une transcription Claude Code ou OpenAI Codex. Il affiche une chronologie de tout ce qui s'est passé dans une session : +Le visualiseur de session répond à la question clé 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é dans une session : -- **Messages** — Les réponses textuelles de Claude et les invites utilisateur -- **Appels d'outils** — Chaque outil invoqué par Claude, avec son entrée et sa sortie -- **Activité des politiques** — Pour chaque appel d'outil, quelles politiques ont été déclenchées et quelle décision elles ont rendue +- **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 se sont déclenchées et quelle décision elles ont rendue -La barre de statistiques en haut affiche la durée de la session, le nombre total d'appels d'outils et un résumé des décisions de hook (nombre de 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 des hooks (comptage allow / deny / instruct). -Vous pouvez exporter la session sous forme de fichier ZIP ou JSONL via le bouton de téléchargement. +Cliquez sur le bouton **Download Logs** 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, pas sur disque) vous obtenez un document JSON reflétant les tables sous-jacentes `session` / `messages` / `parts`. ### Politiques @@ -63,30 +63,30 @@ Une page à deux onglets pour gérer les politiques et examiner l'activité. - - Activez ou désactivez des politiques individuelles d'un seul clic (écrit dans `~/.failproofai/policies-config.json`) - - Développez une politique pour configurer ses paramètres (pour les politiques prenant en charge `policyParams`) - - Installez ou supprimez des hooks pour un scope donné - - Définissez un chemin de fichier de politiques personnalisé + - Activez ou désactivez des politiques individuelles en un seul clic (écrit dans `~/.failproofai/policies-config.json`) + - Développez une politique pour configurer ses paramètres (pour les politiques qui prennent en charge `policyParams`) + - Installez ou supprimez des hooks pour une portée donnée + - Définissez un chemin personnalisé pour le fichier de politiques - - Historique complet et paginé 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)_), 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), 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`) et affiche le badge CLI correspondant dans l'en-tête + - Historique complet paginé 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, bleu 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 --- -## Rafraîchissement automatique +## Actualisation automatique -Le tableau de bord dispose d'un bouton de rafraîchissement automatique dans la navigation supérieure. Lorsqu'il est activé, la page courante se rafraîchit périodiquement pour afficher les nouvelles sessions et l'activité des politiques au fur et à mesure. Indispensable pour surveiller des sessions d'agents autonomes de longue durée. +Le dashboard 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. --- ## Désactiver des pages -Si vous n'avez besoin que de certaines parties du tableau de bord, définissez `FAILPROOFAI_DISABLE_PAGES` avec une liste de noms de pages séparés par des virgules : +Si vous n'avez besoin que de certaines parties du dashboard, définissez `FAILPROOFAI_DISABLE_PAGES` avec une liste de noms de pages séparés par des virgules : ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -98,13 +98,13 @@ Valeurs valides : `policies`, `projects`. ## Thème -Le tableau de bord prend en charge les modes clair et sombre. Basculez entre les deux via le bouton dans la barre de navigation. La préférence est enregistrée dans le stockage local de votre navigateur. +Le dashboard prend en charge les modes clair et sombre. Basculez via le bouton dans la barre de navigation. La préférence est enregistrée dans le stockage local de votre navigateur. --- ## Configurer le chemin des projets -Par défaut, le tableau de bord lit depuis le répertoire de projets Claude Code standard. Remplacez-le pour des configurations personnalisées : +Par défaut, le dashboard lit depuis le répertoire de projets Claude Code standard. Remplacez-le pour des configurations personnalisées : ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -112,21 +112,21 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Accéder depuis un hôte autre que localhost +## Accès depuis un hôte non-localhost -Lorsque vous exécutez le tableau de bord en **mode développement** (`npm run dev`) et que vous y accédez depuis un nom d'hôte autre que `localhost` — par exemple, un domaine personnalisé, une IP distante ou une URL tunnelisée — vous pouvez voir un avertissement du type : +Lorsque vous exécutez le dashboard en **mode dev** (`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 : ```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 (hot module reload), une fonctionnalité réservée au développement. Pour autoriser votre hôte, utilisez l'option `--allowed-origins` : +Il s'agit de Next.js qui bloque l'accès cross-origin à son websocket HMR (rechargement à chaud des modules), qui est une fonctionnalité réservée au mode dev. Pour autoriser votre hôte, utilisez le flag `--allowed-origins` : ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -Pour plusieurs hôtes ou adresses IP, passez une liste séparée par des virgules : +Pour plusieurs hôtes ou IPs, passez une liste séparée par des virgules : ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 @@ -139,5 +139,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 cross-origin en développement. +Ceci s'applique uniquement au mode dev. Lors de l'exécution de `failproofai` (mode production), il n'y a pas de websocket HMR ni de problème de ressource dev cross-origin. \ No newline at end of file diff --git a/docs/fr/getting-started.mdx b/docs/fr/getting-started.mdx index 058181ee..2c852509 100644 --- a/docs/fr/getting-started.mdx +++ b/docs/fr/getting-started.mdx @@ -1,5 +1,5 @@ --- -title: Premiers pas +title: Démarrage rapide description: "Installez failproofai, activez les politiques et laissez vos agents s'exécuter de manière fiable" icon: rocket --- @@ -7,7 +7,7 @@ icon: rocket ## Prérequis - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (optionnel - uniquement nécessaire pour la compilation depuis les sources) +- **Bun** >= 1.3.0 (optionnel - uniquement nécessaire pour compiler depuis les sources) --- @@ -31,24 +31,28 @@ 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 destructives, les fuites de secrets et d'autres modes d'échec 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'un agent. Elles interceptent les commandes destructrices, les fuites de secrets et d'autres modes de défaillance avant qu'ils ne causent des dommages. ```bash failproofai policies --install ``` - Ceci écrit des entrées de hook dans vos interfaces en ligne de commande d'agents installées (`~/.claude/settings.json` pour Claude Code, `~/.codex/hooks.json` pour OpenAI Codex, ou `~/.copilot/hooks/failproofai.json` pour GitHub Copilot CLI). Si plusieurs sont présentes, vous serez invité à choisir ; passez `--cli claude codex copilot` (tout sous-ensemble) pour ignorer l'invite. + Cette commande écrit 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, ou le `~/.gemini/settings.json` de Gemini CLI). Si plusieurs CLIs sont présents, vous serez invité à choisir ; passez `--cli claude codex copilot cursor opencode pi gemini` (ou n'importe quel sous-ensemble) pour ignorer l'invite. - La prise en charge de GitHub Copilot CLI est en **bêta** — installez avec `--cli copilot`. + La prise en charge de GitHub Copilot CLI, Cursor Agent, OpenCode, Pi et Gemini CLI est en **version bêta** — installez avec `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi` ou `--cli gemini`. ```bash failproofai policies --install --scope project failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project + 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 block-sudo block-rm-rf sanitize-api-keys ``` - + ```bash failproofai policies ``` @@ -60,10 +64,10 @@ bun add -g failproofai 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. + Ouvre un tableau de bord local à `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. @@ -82,7 +86,7 @@ Claude Code → failproofai --hook PreToolUse → reads stdin JSON 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 +- **deny** - l'action est bloquée, l'agent est informé du motif - **instruct** - du contexte supplémentaire est ajouté à l'invite de l'agent @@ -91,9 +95,9 @@ Les politiques s'exécutent dans votre processus local. Rien n'est envoyé à un --- -## Configurer des politiques d'équipe avec les politiques basées sur les conventions +## Mettre en place des 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 politique dans ce répertoire et ils sont chargés automatiquement — sans indicateurs, sans modifications de configuration, sans commandes d'installation. +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 de flags, pas de changements de configuration, pas de commandes d'installation. @@ -101,8 +105,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 créez les vôtres : + + Copiez les exemples de démarrage ou écrivez les vôtres : ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -133,12 +137,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 automatiquement ces politiques. Aucune configuration par développeur 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. -Validez `.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 d'échec, 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. +Committez `.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 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. --- @@ -147,12 +151,12 @@ Validez `.failproofai/policies/` dans votre dépôt pour que toute l'équipe par Toute la configuration et les journaux restent sur votre machine : -| Chemin | Ce qu'il stocke | -|--------|-----------------| +| Chemin | Contenu | +|--------|---------| | `~/.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 (validée) | +| `.failproofai/policies-config.json` | Configuration par projet (committée) | | `.failproofai/policies-config.local.json` | Substitutions personnelles (ignorées par git) | --- @@ -167,7 +171,7 @@ Supprime les entrées de hook de `~/.claude/settings.json`. Les fichiers de conf --- -## Prochaines étapes +## Étapes suivantes @@ -184,7 +188,7 @@ Supprime les entrées de hook de `~/.claude/settings.json`. Les fichiers de conf - Surveillez les sessions et examinez l'activité des politiques + Surveillez les sessions et consultez l'activité des politiques \ No newline at end of file diff --git a/docs/he/architecture.mdx b/docs/he/architecture.mdx index 37d68854..1ef66f80 100644 --- a/docs/he/architecture.mdx +++ b/docs/he/architecture.mdx @@ -1,30 +1,30 @@ --- --- title: ארכיטקטורה -description: "כיצד מטפל ה-hook, טעינת התצורה והערכת המדיניות עובדים באופן פנימי" +description: "כיצד מטפל ה-hook, טעינת הקונפיגורציה והערכת המדיניות פועלים באופן פנימי" icon: sitemap --- -מסמך זה מסביר כיצד failproofai עובד באופן פנימי: כיצד מערכת ה-hook חוצצת קריאות כלי סוכן, כיצד התצורה נטענת ומוזגת, כיצד מדיניות מוערכת, וכיצד לוח המחוונים מנטר פעילות סוכן. +מסמך זה מסביר כיצד failproofai עובד באופן פנימי: כיצד מערכת ה-hook מיירטת קריאות כלים של סוכנים, כיצד הקונפיגורציה נטענת ומוזגת, כיצד מדיניויות מוערכות, וכיצד לוח הבקרה מנטר את פעילות הסוכן. --- ## סקירה כללית -ל-failproofai יש שתי תת-מערכות עצמאיות: +ל-failproofai שתי תת-מערכות בלתי תלויות: -1. **מטפל ה-Hook** - תהליך CLI מהיר שהוא Claude Code משדר בכל קריאת כלי סוכן. מעריך מדיניות והחזר החלטה. -2. **Agent Monitor (Dashboard)** - אפליקציית Next.js לניטור מושבי סוכן וניהול מדיניות. +1. **Hook handler** - תהליך CLI מהיר שClaude Code מפעיל בכל קריאת כלי סוכן. מעריך מדיניויות והחזר החלטה. +2. **Agent Monitor (Dashboard)** - יישום Next.js לניטור סדרות סוכנים וניהול מדיניויות. -שתי התת-מערכות חולקות קבצי תצורה ב-`~/.failproofai/` ובתיקייה `~/.failproofai/` של הפרויקט, אך הם פועלים כתהליכים נפרדים ותקשורתם היא רק דרך מערכת הקבצים. +שתי התת-מערכות חולקות קבצי קונפיגורציה ב-`~/.failproofai/` ובספרייה `.failproofai/` של הפרויקט, אך הן פועלות כתהליכים נפרדים ותקשרות רק דרך מערכת הקבצים. --- -## מטפל ה-Hook +## Hook handler -### אינטגרציה עם Claude Code +### שילוב עם Claude Code -כאשר אתה מריץ `failproofai policies --install`, הוא כותב ערכים כמו זה ב-`~/.claude/settings.json`: +כאשר אתה מריץ `failproofai policies --install`, הוא כותב ערכים כמו זה לתוך `~/.claude/settings.json`: ```json { @@ -45,9 +45,9 @@ icon: sitemap } ``` -Claude Code לאחר מכן משדר `failproofai --hook PreToolUse` כתת-תהליך לפני כל קריאת כלי, והעברת עומס JSON על stdin. +Claude Code לאחר מכן מפעיל את `failproofai --hook PreToolUse` כתהליך משנה לפני כל קריאת כלי, עוביר עומס JSON ב-stdin. -### פורמט עומס +### פורמט העומס ```json { @@ -61,11 +61,11 @@ Claude Code לאחר מכן משדר `failproofai --hook PreToolUse` כתת-תה } ``` -עבור אירועי `PostToolUse`, העומס מכיל גם `tool_result` עם הפלט של הכלי. +עבור אירועי `PostToolUse`, העומס מכיל גם `tool_result` עם פלט הכלי. -המטפל כופה גבול של 1 MB ל-stdin. עומסים החוצים זאת מושלכים וכל המדיניות משתמעת להרשות. +המטפל אוכף גבול stdin של 1 MB. עומסים החוצים זאת מושלכים וכל המדיניויות מאפשרות באופן מובהק. -### פורמט תגובה +### פורמט התשובה **Deny (PreToolUse):** ```json @@ -86,7 +86,7 @@ Claude Code לאחר מכן משדר `failproofai --hook PreToolUse` כתת-תה } ``` -**Instruct (any event except Stop):** +**Instruct (כל אירוע למעט Stop):** ```json { "hookSpecificOutput": { @@ -97,7 +97,7 @@ Claude Code לאחר מכן משדר `failproofai --hook PreToolUse` כתת-תה **Stop event instruct:** - קוד יציאה: `2` -- הנמקה כתובה ל-stderr (לא stdout) +- סיבה כתובה ל-stderr (לא stdout) **Allow:** - קוד יציאה: `0` @@ -105,7 +105,7 @@ Claude Code לאחר מכן משדר `failproofai --hook PreToolUse` כתת-תה **Allow עם הודעה:** -`allow(message)` מאפשר למדיניות לשלוח הקשר מידע חזרה ל-Claude גם כאשר הפעולה מורשית. מטפל ה-Hook כותב את ה-JSON הבא ל-**stdout** (לא קובץ תצורה — זו התגובה של המטפל ל-Claude Code, בדיוק כמו תגובות deny ו-instruct למעלה): +`allow(message)` מאפשר למדיניות לשלוח הקשר מידע חזרה ל-Claude גם כאשר הפעולה מותרת. מטפל ה-hook כותב את ה-JSON הבא ל-**stdout** (לא קובץ קונפיגורציה — זו התשובה של המטפל ל-Claude Code, בדיוק כמו תשובות deny ו-instruct למעלה): ```json // Written to stdout by the hook handler process @@ -115,13 +115,13 @@ Claude Code לאחר מכן משדר `failproofai --hook PreToolUse` כתת-תה } } ``` -- קוד יציאה: `0` (הפעולה מורשית) -- כאשר מדיניות מרובות החוזרות `allow` עם הודעה, ההודעות שלהן מחוברות עם שורות חדשות למחרוזת `additionalContext` יחידה -- אם אין מדיניות המספקת הודעה, stdout הוא ריק (כמו קודם) +- קוד יציאה: `0` (הפעולה מותרת) +- כאשר מספר מדיניויות מחזירות `allow` עם הודעה, ההודעות שלהן מצורפות עם שורות חדשות לתוך מחרוזת `additionalContext` יחידה +- אם אף מדיניות לא מספקת הודעה, stdout ריק (זהה לפני כן) -### צינור עיבוד +### צנרת עיבוד -`src/hooks/handler.ts` מיישם את המסלול המלא: +`src/hooks/handler.ts` מיישם את הצנרת המלאה: ```text stdin JSON @@ -140,13 +140,13 @@ stdin JSON → exit ``` -התהליך כולו פועל בפחות מ-100ms עבור עומסים טיפוסיים ללא קריאות LLM. +כל התהליך פועל תחת 100ms עבור עומסים אופייניים ללא קריאות LLM. --- -## טעינת תצורה +## טעינת קונפיגורציה -`src/hooks/hooks-config.ts` מיישם טעינת תצורה בתחום שלוש. +`src/hooks/hooks-config.ts` מיישם טעינת קונפיגורציה תלת-הטווח. ```text [1] {cwd}/.failproofai/policies-config.json ← project (highest priority) @@ -154,40 +154,40 @@ stdin JSON [3] ~/.failproofai/policies-config.json ← global (lowest priority) ``` -ההיגיון של המיזוג: -- `enabledPolicies` - איחוד לא משוכפל בכל שלוש הקבצים -- `policyParams` - per-policy key, הקובץ הראשון שמגדיר את זה מנצח לחלוטין -- `customPoliciesPath` - הקובץ הראשון שמגדיר את זה מנצח -- `llm` - הקובץ הראשון שמגדיר את זה מנצח +לוגיקת מיזוג: +- `enabledPolicies` - איחוד מנוקה בכל שלושת הקבצים +- `policyParams` - מפתח לכל מדיניות, הקובץ הראשון שמגדיר אותו מנצח כליל +- `customPoliciesPath` - הקובץ הראשון שמגדיר אותו מנצח +- `llm` - הקובץ הראשון שמגדיר אותו מנצח -לוח המחוונים ברשת משתמש ב-`readHooksConfig()` (global only) לקריאה וכתיבה, מכיוון שהוא לא משדר עם 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`, השדר את תשובת ה-deny. +- אם נאספו החזרות `instruct`, השדר תשובת instruct יחידה עם כל ההודעות המצורפות. +- אחרת, השדר תשובת allow (stdout ריק, יציאה 0). --- -## מדיניות בנויה +## מדיניויות מובנות -`src/hooks/builtin-policies.ts` מגדיר את כל 26 המדיניות המובנות כ-`BuiltinPolicyDefinition` אובייקטים: +`src/hooks/builtin-policies.ts` מגדיר את כל 26 המדיניויות המובנות כאובייקטי `BuiltinPolicyDefinition`: ```typescript interface BuiltinPolicyDefinition { @@ -205,15 +205,15 @@ interface BuiltinPolicyDefinition { } ``` -מדיניות המקבלת `params` מצהירה `PolicyParamsSchema` עם סוגים וברירות ברירת מחדל עבור כל פרמטר. מעריך המדיניות מזריק ערכים מסולקים ל-`ctx.params` לפני קריאה ל-`fn`. פונקציות מדיניות קוראות ל-`ctx.params` ללא guard null מכיוון שברירות ברירת מחדל תמיד מיושמות תחילה. +מדיניויות המקבלות `params` מכריזות על `PolicyParamsSchema` עם סוגים וברירות מחדל לכל פרמטר. מעריך המדיניות מזריק ערכים שנפתרו לתוך `ctx.params` לפני קריאה ל-`fn`. פונקציות מדיניות קוראות `ctx.params` ללא null-guarding כי ברירות מחדל תמיד יישמו תחילה. -התאמת דפוסים בתוך מדיניות משתמשת בקלקולי פקודה מנותחים (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`-backed: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -228,23 +228,23 @@ export function clearCustomHooks(): void { ... } // used in tests `src/hooks/custom-hooks-loader.ts` טוען את קובץ המדיניות של המשתמש: -1. קרא את `customPoliciesPath` מהתצורה; דלג אם חסר. -2. פתור לנתיב מוחלט; בדוק קובץ קיים. -3. כתוב מחדש את כל `from "failproofai"` ייבוא לנתיב ה-dist בפועל כדי `customPolicies` יתבררו לרישום `globalThis` זהה. -4. כתוב מחדש ייבוא מקומי חולף רקורסיבי כדי להבטיח התאימות ESM. -5. כתוב קבצי `.mjs` זמניים ו-`import()` קובץ הכניסה. -6. התקשר ל-`getCustomHooks()` כדי לשלוח קטגוריות מחדש. +1. קרא את `customPoliciesPath` מהקונפיגורציה; דלג אם לא נמצא. +2. פתור לנתיב מוחלט; בדוק שהקובץ קיים. +3. כתוב מחדש את כל הייבוא `from "failproofai"` לנתיב dist בפועל כדי ש-`customPolicies` יתקרר לרישום `globalThis` זהה. +4. כתוב מחדש באופן רקורסיבי ייבוא מקומי עברי כדי להבטיח תאימות ESM. +5. כתוב קובצי `.mjs` זמניים ו-`import()` את קובץ הערך. +6. קרא ל-`getCustomHooks()` כדי לאחזר קריאות רשומות. 7. נקה את כל הקבצים הזמניים בבלוק `finally`. -בכל שגיאה (קובץ לא נמצא, שגיאת תחביר, כישלון ייבוא), השגיאה מתועדת ב-`~/.failproofai/hook.log` והטוען מחזיר מערך ריק. מדיניות מובנית לא מושפעת. +בכל שגיאה (קובץ לא נמצא, שגיאת תחביר, כישלון ייבוא), השגיאה נרשמת ל-`~/.failproofai/hook.log` והטוען מחזיר מערך ריק. מדיניויות מובנות לא מושפעות. -מדיניות מותאמת מוערכת לאחר כל המדיניות המובנות. `deny` מדיניות מותאמת עדיין מעיל קצר מדיניות מותאמת נוספת (אך כל הבנוי כבר רץ בנקודה זו). +מדיניויות מותאמות אישית מוערכות לאחר כל המדיניויות המובנות. `deny` של מדיניות מותאמת אישית עדיין מקצר זרימת מדיניויות מותאמות אישית נוספות (אך כל הביטויים כבר פעלו בנקודה זו). --- ## רישום פעילות -לאחר כל אירוע hook, המטפל מוסיף שורת JSONL ל-`~/.failproofai/hook-activity.jsonl`: +לאחר כל אירוע hook, המטפל מצרף שורת JSONL ל-`~/.failproofai/hook-activity.jsonl`: ```json { @@ -259,13 +259,13 @@ export function clearCustomHooks(): void { ... } // used in tests } ``` -שורה אחת לכל מדיניות שנתנה החלטה שאינה מאפשרת. החלטות Allow לא מתועדות (כדי לשמור את הקובץ קטן). +שורה אחת לכל מדיניות שעשתה החלטה שאינה allow. החלטות Allow לא נרשמות (כדי להשאיר את הקובץ קטן). --- -## ארכיטקטורת לוח המחוונים +## ארכיטקטורת לוח בקרה -לוח המחוונים הוא אפליקציית **Next.js 16** באמצעות App Router עם React Server Components ו-Server Actions. +לוח הבקרה הוא יישום **Next.js 16** המשתמש ב-App Router עם React Server Components ו-Server Actions. ```text app/ @@ -282,21 +282,21 @@ app/ get-hook-activity.ts ← Paginate/search activity log install-hooks-web.ts ← Install/remove hooks from the browser api/ - download/[project]/[session]/route.ts ← Export session as ZIP/JSONL + download/[project]/[session]/route.ts ← Per-CLI session export (JSONL or JSON) ``` **זרימת נתונים:** -- רכיבי עמוד קוראים ל-`lib/projects.ts` ו-`lib/log-entries.ts` כדי לקרוא נתוני פרויקט/מושב ישירות מ-filesystem (ללא שכבת API לקריאות). -- עמוד המדיניות משתמש בשרת Actions עבור כל מוטציות (החלפה, עדכון params, התקנה/הסרה). -- צופה המושב מנתח פורמט תוליד JSONL של Claude ומרחיב ציר זמן של הודעות וקריאות כלים. +- רכיבי דף קוראים ל-`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/he/built-in-policies.mdx b/docs/he/built-in-policies.mdx index 676b7acc..0377b52d 100644 --- a/docs/he/built-in-policies.mdx +++ b/docs/he/built-in-policies.mdx @@ -1,42 +1,39 @@ --- ---- -title: מדיניויות מובנות -description: "כל 39 המדיניויות המובנות התופסות אופני כשל נפוצים של סוכנים" +title: מדיניות מובנות +description: "כל 39 המדיניות המובנות שתופסות מצבי כשל נפוצים של סוכנים" icon: shield --- -failproofai מגיע עם 39 מדיניויות מובנות התופסות אופני כשל נפוצים של סוכנים. כל מדיניות מופעלת על סוג אירוע hook ושם כלי ספציפי. תשע עשרה מדיניויות מקבלות פרמטרים המאפשרים לכם לכוונן את התנהגותן ללא כתיבת קוד. חמש מדיניויות workflow אוכפות צנרת commit → push → PR → CI לפני שClaude עוצר. +failproofai מגיע עם 39 מדיניות מובנות שתופסות מצבי כשל נפוצים של סוכנים. כל מדיניות פועלת על סוג אירוע hook ושם כלי ספציפי. תשע עשרה מדיניות מקבלות פרמטרים המאפשרים לך לכוונן את התנהגותן ללא כתיבת קוד. חמש מדיניות זרימת עבודה אוכפות צינור commit → push → PR → CI בטרם Claude עוצר. --- ## סקירה כללית -המדיניויות מקובצות לקטגוריות: +מדיניויות מקובצות לקטגוריות: | קטגוריה | מדיניויות | סוג Hook | |----------|----------|-----------| | [פקודות מסוכנות](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | -| [פקודות Infrastructure](#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 | +| [פקודות תשתית](#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 | | [מנהלי חבילות](#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 | +| [זרימת עבודה](#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-`** — נקה נתונים רגישים מפלט הכלי לפני שהסוכן רואה זאת. -### Namespaces +### מרחבי שמות -כל מדיניות גרה בחריץ `/`. מדיניויות מובנות שייכות ל -namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-namespace -מונע התנגשויות כשאתה גם טוען מדיניויות מותאמות או של צד שלישי עם שמות קצרים דומים. +כל מדיניות נמצאת בחריץ `/`. מדיניות מובנות שייכות ל-namespace **`exospherehost/`** — לדוגמה, `exospherehost/sanitize-jwt`. מרחב השמות מונע התנגשויות כאשר אתה טוען גם מדיניות מותאמות או של צד שלישי עם שמות קצרים דומים. -בתצורה שלך תוכל להתייחס למדיניות מובנית על ידי השם הקצר שלה או שם מוסמך; שתי הצורות מתרוצות לאותה מדיניות: +בתצורה שלך אתה יכול להתייחס למדיניות מובנית על ידי השם הקצר שלה או שמה המורשה; שתי הצורות מפתרות לאותה מדיניות: ```json { @@ -47,33 +44,33 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na } ``` -אם לשם אין `/`, failproofai מתייחס אליו כשייך ל-namespace ברירת המחדל `exospherehost`. שמות שכבר מכילים `/` (למשל `myorg/foo`, `custom/my-hook`) נשמרים כפי שהם. +אם לשם אין `/`, failproofai מתייחס אליו כשייך ל-namespace ברירת המחדל `exospherehost`. שמות שכבר מכילים `/` (למשל `myorg/foo`, `custom/my-hook`) נשמרים כמו שהם. - **`require-`** — חסום את אירוע Stop עד שתנאים מתקיימים. --- -כל מדיניות תומכת בשדה `hint` אופציוני ב-`policyParams`. ה-hint מחובר להודעת deny או instruct שClaude רואה, ומספק הנחיות פעולה ללא שינוי קוד מדיניות. עובד עם מדיניויות מובנות, מותאמות ושל convention. ראה [Configuration → hint](/he/configuration#hint-cross-cutting) לפרטים. +כל מדיניות תומכת בשדה `hint` אופציוני ב-`policyParams`. ההערה מתווספת להודעת deny או instruct ש-Claude רואה, תוך מתן הנחיות מעשיות ללא שינוי קוד מדיניות. עובד עם מדיניויות מובנות, מותאמות וביחס התנהגות. ראה [Configuration → hint](/he/configuration#hint-cross-cutting) לפרטים. --- ## פקודות מסוכנות -מנע סוכנים מהפעלת פעולות שקשה לבטל או שיכולות להזיק למערכת המארחת. +מנע מסוכנים הפעלת פעולות שקשה לבטל או שעלולות לפגוע במערכת המארח. ### `block-sudo` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** שוללת כל פקודת `sudo`. +**ברירת מחדל:** מסרב לכל פקודת `sudo`. -חוסמת הפעלות המכילות את המילה השמורה `sudo`. התאמת דפוס נעשית על tokenים של פקודה מנותחת, לא על המחרוזת הגולמית, כדי למנוע עקיפה דרך injection של operator shell. +חוסם הזעקות שכוללות את המילה השמורה `sudo`. התאמת דפוסים מתבצעת על אסימוני פקודה שנתוח, לא על המחרוזת הגולמית, כדי למנוע עקיפה דרך הזרקת אופרטור shell. **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודה מדויקות שמותרות. כל ערך מתואם מול tokenים של argv שנתוחו. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודה מדויקות המותרות. כל ערך מתואם כנגד אסימוני argv שנתוח. | **דוגמה:** @@ -87,10 +84,10 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na } ``` -עם תצורה זו, `sudo systemctl status nginx` מותר, אך `sudo rm /etc/hosts` שלול. +עם תצורה זו, `sudo systemctl status nginx` מותרת, אך `sudo rm /etc/hosts` נדחית. -דפוסים מתואמים מול tokenים שנתוחו, לא מול מחרוזת הפקודה הגולמית. זה מונע עקיפה דרך operators של shell מחובר (למשל `sudo systemctl status x; rm -rf /` לא תואם `sudo systemctl status *`). +דפוסים מתואמים כנגד אסימוני שנתוח, לא מחרוזת הפקודה הגולמית. זה מונע עקיפה דרך אופרטורים shell מוספים (למשל `sudo systemctl status x; rm -rf /` לא תואם `sudo systemctl status *`). --- @@ -98,13 +95,13 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ### `block-rm-rf` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** שוללת `rm -rf`, `rm -fr` וצורות מחיקה רקורסיביות דומות. +**ברירת מחדל:** מסרב `rm -rf`, `rm -fr`, וצורות מחיקה רקורסיביות דומות. **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | נתיבים שבטוח למחוק בצורה רקורסיבית (למשל `/tmp`). | +| `allowPaths` | `string[]` | `[]` | נתיבים בטוחים למחיקה רקורסיבית (למשל `/tmp`). | **דוגמה:** @@ -123,37 +120,37 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ### `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`). -ללא פרמטרים. +אין פרמטרים. --- -## פקודות Infrastructure +## פקודות תשתית -עצור סוכני קידוד מהפעלת CLIs של infrastructure או טריגור צנרות CI/CD. כל המדיניויות בקטגוריה זו הן **opt-in** (`defaultEnabled: false`) — סוכנים שצריכים בעצם להקרין `kubectl`, `terraform`, וכו' לא יופרעו אלא אם תאפשר את המדיניות. כשמאופשרת, כל הפעלה של ה-CLI המתאימה שלולה אלא אם הפקודה תואמת לערך ב-`allowPatterns`. +עצור סוכני קידוד מהפעלת CLIs של תשתית או הדלקת צינורות CI/CD. כל המדיניויות בקטגוריה זו הן **הסכמה מראש** (`defaultEnabled: false`) — סוכנים שבאמת צריכים לקרוא ל-`kubectl`, `terraform`, וכו' לא יופרעו אלא אם תפעיל את המדיניות. כאשר מופעלת, כל הזעקה של ה-CLI המתאים נדחית אלא אם הפקודה תואמת ערך ב-`allowPatterns`. -דקדוק הדפוס זהה ל-[`block-sudo`](#block-sudo): tokenים מתואמים מול argv שנתוח, `*` הוא wildcard עבור token אחד, וכל פקודה המכילה standalone shell operator (`&&`, `||`, `|`, `;`) או token עם shell metacharacters משובצים שלול לפני התאמה allowlist כדי למנוע injection bypasses. +דקדוק הדפוס זהה ל-[`block-sudo`](#block-sudo): אסימוני התאמה כנגד argv שנתוח, `*` הוא כל דבר עם אסימון אחד, וכל פקודה המכילה אופרטור shell עצמאי (`&&`, `||`, `|`, `;`) או אסימון עם תווי מטא-shell משובצים נדחית לפני התאמת רשימה מותרת למניעת עקיפה הזרקה. ### `block-kubectl` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** שוללת כל הפעלה של `kubectl`. +**ברירת מחדל:** מסרב כל הזעקת `kubectl`. **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודה של kubectl שמותרות. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודת kubectl המותרות. | **דוגמה:** @@ -167,20 +164,20 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na } ``` -עם תצורה זו, `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). **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודה של terraform/tofu שמותרות. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודת terraform/tofu המותרות. | **דוגמה:** @@ -199,13 +196,13 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ### `block-aws-cli` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** שוללת כל הפעלה של CLI `aws`. +**ברירת מחדל:** מסרב כל הזעקת `aws` CLI. **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודה של aws CLI שמותרות. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודת aws CLI המותרות. | **דוגמה:** @@ -224,13 +221,13 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ### `block-gcloud` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** שוללת כל הפעלה של CLI `gcloud` (Google Cloud). +**ברירת מחדל:** מסרב כל הזעקת `gcloud` (Google Cloud) CLI. **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודה של gcloud שמותרות. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודת gcloud המותרות. | **דוגמה:** @@ -249,13 +246,13 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ### `block-az-cli` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** שוללת כל הפעלה של CLI `az` (Azure). +**ברירת מחדל:** מסרב כל הזעקת `az` (Azure) CLI. **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודה של az CLI שמותרות. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודת az CLI המותרות. | **דוגמה:** @@ -274,13 +271,13 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ### `block-helm` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** שוללת כל הפעלה של `helm`. +**ברירת מחדל:** מסרב כל הזעקת `helm`. **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | קידומות פקודה של helm שמותרות. | +| `allowPatterns` | `string[]` | `[]` | קידומות פקודת helm המותרות. | **דוגמה:** @@ -299,7 +296,7 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ### `block-gh-pipeline` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** שוללת תת-פקודות `gh` CLI הבאות שמטרפדות state או טריגרות צנרות: +**ברירת מחדל:** מסרב את תת-הפקודות הבאות של `gh` CLI שמשנות מצב או מעלות צינורות: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -308,13 +305,13 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na - `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` שלfaiproofai). +תת-פקודות `gh` קריאה-בלבד כמו `gh pr view`, `gh pr list`, `gh run list`, `gh release view`, ו-`gh api repos/.../...` **אינן** תואמות על ידי מדיניות זו — הן נחוצות באופן קבוע לבדיקות זרימת עבודה (כולל ה-`require-ci-green-before-stop` שלו failproofai). **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | הפעלות scripted ספציפיות להרשאה אפילו אם היו שלולות אחרת. | +| `allowPatterns` | `string[]` | `[]` | הזעקות מסוימות לתסריט לאישור למרות שהן אחרת היו נדחות. | **דוגמה:** @@ -330,29 +327,29 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na --- -## סודות (מנקי) +## סודות (מנקה) -עצור סוכנים מ-leaking credentials לתוך ההקשר או הפלט שלהם. מדיניויות Sanitizer מופעלות על אירועי **PostToolUse**. כשClaude מפעיל פקודת Bash, קורא קובץ, או קורא לכל כלי, מדיניויות אלה בוחנות את הפלט לפני החזרתו לClaude. אם דפוס סודי מזוהה, המדיניות מחזירה החלטת deny התוקעת את הפלט מעברת חזרה. +עצור סוכנים מדלוף אישורים להקשר או פלט שלהם. מדיניויות מנקה פועלות על אירועי **PostToolUse**. כאשר Claude מפעיל פקודת Bash, קורא קובץ, או קורא לכל כלי, מדיניויות אלה בוחנות את הפלט לפני שהוא מוחזר ל-Claude. אם דפוס סוד זוהה, המדיניות מחזירה החלטת deny המונעת מהפלט להיות מועבר חזרה. ### `sanitize-jwt` **אירוע:** PostToolUse (כל הכלים) -**ברירת מחדל:** מחליקה JWT tokens (שלוש segments base64url מופרדות על ידי `.`). +**ברירת מחדל:** מסיר טוקנים JWT (שלוש קטעי base64url מופרדים ב-`.`). -ללא פרמטרים. +אין פרמטרים. --- ### `sanitize-api-keys` **אירוע:** PostToolUse (כל הכלים) -**ברירת מחדל:** מחליקה פורמטי מפתח API נפוצים: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS access keys (`AKIA`), Stripe keys (`sk_live_`, `sk_test_`) וGoogle API keys (`AIza`). +**ברירת מחדל:** מסיר פורמטי מפתח API נפוצים: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), מפתחות גישה AWS (`AKIA`), מפתחות Stripe (`sk_live_`, `sk_test_`), ומפתחות Google API (`AIza`). **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | דפוסי regex נוספים להתייחסות כסודות. | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | דפוסי regex נוספים להיחשב כסודות. | **דוגמה:** @@ -374,68 +371,68 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ### `sanitize-connection-strings` **אירוע:** PostToolUse (כל הכלים) -**ברירת מחדל:** מחליקה מחרוזות חיבור של מסד נתונים המכילות credentials משובצים (למשל `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 (כל הכלים) -**ברירת מחדל:** מחליקה `Authorization: Bearer ` headers כאשר ה-token הוא 20 או יותר תווים. +**ברירת מחדל:** מסיר כותרות `Authorization: Bearer ` כאשר האסימון הוא 20 תווים או יותר. -ללא פרמטרים. +אין פרמטרים. --- ## סביבה -הגן על תצורת סביבה רגישה מקריאה או חשיפה על ידי סוכנים. +הגן על תצורת סביבה רגישה מהיווצרות קריאה או חשיפה על ידי סוכנים. ### `block-env-files` **אירוע:** PreToolUse (Bash, Read) -**ברירת מחדל:** שוללת קריאת קבצי `.env` דרך `cat .env`, קריאות כלי Read עם `.env` כנתיב הקובץ, וכו'. +**ברירת מחדל:** מסרב קריאת קבצי `.env` דרך `cat .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), עם fallback לספריית העבודה הנוכחית של הסשן כשהמשתנה ההוא אינו מוגדר. שימוש בשורש הפרויקט ולא ב-`cwd` החי אומר שהגבול נשאר יציב גם אחרי שClaude `cd`-ים לתת-ספריה. +**ברירת מחדל:** מסרב קריאת קבצים מחוץ לשורש הפרויקט. הגבול הוא `CLAUDE_PROJECT_DIR` (מוגדר פעם אחת לכל הפעלה על ידי Claude Code), עם חזרה ל-cwd הנוכחי של ההפעלה כאשר משתנה זה לא מוגדר. שימוש בשורש הפרויקט ולא ב-`cwd` החי משמעות שהגבול נשאר יציב גם אחרי Claude `cd` לתתי-ספרייה. **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | קידומות נתיב מוחלט שמותרות אפילו אם מחוץ לשורש הפרויקט. | +| `allowPaths` | `string[]` | `[]` | קידומות נתיב מוחלט המותרות גם אם מחוץ לשורש הפרויקט. | **דוגמה:** @@ -454,13 +451,13 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ### `block-secrets-write` **אירוע:** PreToolUse (Write, Edit) -**ברירת מחדל:** שוללת כתיבה לקבצים שמשמשים בדרך כלל לפרטי מפתחות וקרטיפיקטים: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**ברירת מחדל:** מסרב כתיבות לקבצים המשמשים בדרך כלל למפתחות פרטיים ותעודות: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `additionalPatterns` | `string[]` | `[]` | דפוסי שם קובץ נוספים (סגנון glob) לחסימה. | +| `additionalPatterns` | `string[]` | `[]` | דפוסי שם קובץ נוספים (בסגנון glob) לחסימה. | **דוגמה:** @@ -478,18 +475,18 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ## Git -מנע pushes בלתי מכוונים, force-pushes והטעויות של branch שקשה לבטל. +מנע דחיפות מקרית, דחיפות כפויות, וטעויות ענף שקשה לבטל. ### `block-push-master` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** שוללת `git push origin main` ו-`git push origin master`. +**ברירת מחדל:** מסרב `git push origin main` ו-`git push origin master`. **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | שמות branch שלא ניתן לpush אליהם ישירות. | +| `protectedBranches` | `string[]` | `["main", "master"]` | שמות ענפים שלא ניתן לדחוף אליהם ישירות. | **דוגמה:** @@ -504,7 +501,7 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ``` -כדי לאפשר push לכל branches (בעצם השבתה של מדיניות זו ללא הסרתה מ-`enabledPolicies`), קבע `protectedBranches: []`. +כדי לאפשר דחיפה לכל הענפים (למעשה השבתת מדיניות זו ללא הסרה מ-`enabledPolicies`), הגדר `protectedBranches: []`. --- @@ -512,22 +509,22 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ### `block-work-on-main` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** שוללת checkout של `main` או `master` branches ישירות. +**ברירת מחדל:** מסרב `git commit`, `git merge`, `git rebase`, ו-`git cherry-pick` בזמן שעץ העבודה נמצא על `main` או `master`. יצירת ענפים והחלפתם (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) אינם מושפעים. **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | שמות branch שלא ניתן לcheckout אליהם ישירות. | +| `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) של cross-cutting כדי להציע חלופות: +אין פרמטרים ספציפיים למדיניות. השתמש ב-cross-cutting [`hint`](/he/configuration#hint-cross-cutting) כדי להציע חלופות: ```json { @@ -544,66 +541,66 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ### `warn-git-amend` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מורה ל-Claude להמשיך בזהירות בעת הפעלת `git commit --amend`. לא חוסמת הפקודה. +**ברירת מחדל:** מורה ל-Claude להתקדם בזהירות בעת הפעלת `git commit --amend`. אינו חוסם את הפקודה. -ללא פרמטרים. +אין פרמטרים. --- ### `warn-git-stash-drop` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מורה ל-Claude להאשר לפני הפעלת `git stash drop`. לא חוסמת הפקודה. +**ברירת מחדל:** מורה ל-Claude לאשר לפני הפעלת `git stash drop`. אינו חוסם את הפקודה. -ללא פרמטרים. +אין פרמטרים. --- ### `warn-all-files-staged` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מורה ל-Claude לבחון מה זה staging כאשר זה מפעיל `git add -A` או `git add .`. לא חוסמת הפקודה. +**ברירת מחדל:** מורה ל-Claude לבדוק את מה שהוא מעיד בעת הפעלת `git add -A` או `git add .`. אינו חוסם את הפקודה. -ללא פרמטרים. +אין פרמטרים. --- ## מסד נתונים -תפוס פעולות SQL destructive לפני שהן מבוצעות כנגד מסד הנתונים שלך. +תפוס פעולות SQL הרסניות לפני שהן מבוצעות כנגד בסיס הנתונים שלך. ### `warn-destructive-sql` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מורה ל-Claude להאשר לפני הפעלת SQL המכיל `DROP TABLE`, `DROP DATABASE`, או `DELETE` ללא `WHERE` clause. +**ברירת מחדל:** מורה ל-Claude לאשר לפני הפעלת SQL המכיל `DROP TABLE`, `DROP DATABASE`, או `DELETE` ללא סעיף `WHERE`. -ללא פרמטרים. +אין פרמטרים. --- ### `warn-schema-alteration` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מורה ל-Claude להאשר לפני הפעלת הצהרות `ALTER TABLE`. +**ברירת מחדל:** מורה ל-Claude לאשר לפני הפעלת הצהרות `ALTER TABLE`. -ללא פרמטרים. +אין פרמטרים. --- ## אזהרות -תן לסוכנים הקשר נוסף לפני פעולות בפוטנציאל סיכון אך non-destructive. +תן סוכנים הקשר נוסף לפני פעולות פוטנציאליות מסוכנות אך לא הרסניות. ### `warn-large-file-write` **אירוע:** PreToolUse (Write) -**ברירת מחדל:** מורה ל-Claude להאשר לפני כתיבת קבצים גדולים מ-1024 KB. +**ברירת מחדל:** מורה ל-Claude לאשר לפני כתיבת קבצים גדולים מ-1024 KB. **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | סף גודל קובץ בקילובייטים מעליו הוצاה אזהרה. | +| `thresholdKb` | `number` | `1024` | סף גודל קובץ בקילובייטים שמעליו אזהרה מונפקת. | **דוגמה:** @@ -618,7 +615,7 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ``` -מטפל ה-hook אוכף מגבלת stdin של 1 MB על payloads. כדי לבדוק מדיניות זו עם תוכן קטן, קבע `thresholdKb` לערך הרבה מתחת ל-1024. +ידית hook אוכפת מגבלת stdin של 1 MB על עומסים. כדי לבדוק מדיניות זו עם תוכן קטן, הגדר `thresholdKb` לערך הרבה מתחת ל-1024. --- @@ -626,49 +623,49 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ### `warn-package-publish` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מורה ל-Claude להאשר לפני הפעלת `npm publish`. +**ברירת מחדל:** מורה ל-Claude לאשר לפני הפעלת `npm publish`. -ללא פרמטרים. +אין פרמטרים. --- ### `warn-background-process` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מורה ל-Claude להיות זהיר בעת השקת תהליכי background דרך `nohup`, `&`, `disown` או `screen`. +**ברירת מחדל:** מורה ל-Claude להיות זהיר בעת הפעלת תהליכים ברקע דרך `nohup`, `&`, `disown`, או `screen`. -ללא פרמטרים. +אין פרמטרים. --- ### `warn-global-package-install` **אירוע:** PreToolUse (Bash) -**ברירת מחדל:** מורה ל-Claude להאשר לפני הפעלת `npm install -g`, `yarn global add` או `pip install` ללא virtual environment. +**ברירת מחדל:** מורה ל-Claude לאשר לפני הפעלת `npm install -g`, `yarn global add`, או `pip install` ללא סביבה וירטואלית. -ללא פרמטרים. +אין פרמטרים. --- ## מנהלי חבילות -אכוף איזה מנהלי חבילות הסוכן מותר להשתמש. +אכוף אילו מנהלי חבילות מותר לסוכן להשתמש. ### `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. -| Parameter | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-----------|------|---------|-------------| -| `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 { @@ -682,48 +679,48 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na } ``` -עם תצורה זו, `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+ פעמים עם פרמטרים זהים — סימן נפוץ שהסוכן תקוע בלולאה. +**ברירת מחדל:** מורה ל-Claude לשקול מחדש כאשר אותו כלי קרוא 3 פעמים או יותר עם פרמטרים זהים — סימן נפוץ לכך שהסוכן תקוע בלולאה. -ללא פרמטרים. +אין פרמטרים. --- -## Workflow +## זרימת עבודה -אכוף workflow של סוף-סשן מתורגל. מדיניויות אלה מופעלות על אירוע **Stop** ושוללות את Claude מהעצירה עד שכל תנאי מתקיימים. הם עוקבים אחר שרשרת תלות טבעית: commit → push → PR → CI. אם מדיניות שוללת, מדיניויות מאוחרות יותר בשרשרת מדולגות (deny מקצר). +אכוף זרימת עבודה משמעת בסוף ההפעלה. מדיניויות אלה פועלות על אירוע **Stop** וסירבות ל-Claude מעצירה עד שכל תנאי מתקיים. הם עוקבים אחר שרשרת תלות טבעית: commit → push → PR → CI. אם מדיניות סירבה, מדיניויות מאוחרות יותר בשרשרת דלילות (deny קצר-מעגלים). -כל מדיניויות workflow הן **fail-open**: אם הכלי הנדרש אינו זמין (למשל `gh` לא מותקן, אין remote git), המדיניות מאפשרת עם הודעה תובנה המסבירה מדוע הבדיקה הדולגה. +כל מדיניויות זרימת העבודה הן **fail-open**: אם הכלי הנדרש אינו זמין (למשל `gh` לא מותקן, אין git remote), המדיניות מאפשרת עם הודעה אינפורמטיבית המסבירה מדוע הבדיקה דלילה. ### `require-commit-before-stop` **אירוע:** Stop -**ברירת מחדל:** שוללת עצירה כשיש שינויים uncommitted (modified, staged או untracked files). מחזירה הודעה תובנה כאשר ספריית העבודה נקייה. +**ברירת מחדל:** מסרב עצירה כאשר יש שינויים לא מחויבים (קבצים שונויים, בתאימה, או לא מעקובים). מחזיר הודעה אינפורמטיבית כאשר ספריית העבודה נקייה. -ללא פרמטרים. +אין פרמטרים. --- ### `require-push-before-stop` **אירוע:** Stop -**ברירת מחדל:** שוללת עצירה כשיש commits unpushed או כאשר ה-branch הנוכחי אין לו remote tracking branch. מציע `git push -u` ליצירת tracking branch אם נדרש. Fails open אם אין remote מוגדרת. +**ברירת מחדל:** מסרב עצירה כאשר יש commits לא דחופים או כאשר לענף הנוכחי אין ענף remote שנקבע. מציע `git push -u` ליצור ענף מעקובים אם נדרש. Fails open אם אין remote מוגדר. **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | שם Remote לpush אליו. | +| `remote` | `string` | `"origin"` | שם ה-remote לדחיפה אליו. | **דוגמה:** @@ -742,14 +739,14 @@ namespace **`exospherehost/`** — למשל, `exospherehost/sanitize-jwt`. ה-na ### `require-pr-before-stop` **אירוע:** Stop -**ברירת מחדל:** שוללת עצירה כאשר אין pull request עבור ה-branch הנוכחי, או כאשר ה-PR הקיים סגור ללא merge. מורה ל-Claude ליצור PR עם `gh pr create`. כאשר ה-PR הוא **merged**, המדיניות מאפשרת (העבודה נשלחה) והודעה מציעה להחליף off ה-branch (`git checkout main && git pull`). +**ברירת מחדל:** מסרב עצירה כאשר אין בקשת pull קיימת עבור הענף הנוכחי, או כאשר ה-PR הקיים סגור ללא מיזוג. מורה ל-Claude ליצור PR עם `gh pr create`. כאשר ה-PR הוא **merged**, המדיניות מאפשרת (העבודה נשלחה) וההודעה רומזת להחליף את הענף (`git checkout main && git pull`). -ללא פרמטרים. +אין פרמטרים. -מדיניות זו דורשת [GitHub CLI](https://cli.github.com/) (`gh`) להיות מותקן והעתקי. -הפעל `gh auth login` עם personal access token שיש לו `repo` scope עבור read access ל -pull requests. אם `gh` אינו מותקן או לא העתקי, המדיניות fails open ודוחה את הסיבה ל-Claude. +מדיניות זו דורשת [GitHub CLI](https://cli.github.com/) (`gh`) להתקיים ולהתאמת. +הפעל `gh auth login` עם personal access token שיש לו `repo` scope לגישת קריאה ל- +pull requests. אם `gh` לא מותקן או לא מוצא, המדיניות fails open ודיווח הסיבה ל-Claude. --- @@ -757,24 +754,23 @@ pull requests. אם `gh` אינו מותקן או לא העתקי, המדיני ### `require-no-conflicts-before-stop` **אירוע:** Stop -**ברירת מחדל:** שוללת עצירה כאשר ה-branch הנוכחי לא יכול להתמזג בנקיון לתוך ה-base branch. המדיניות קודם מאשרת שיש `OPEN` PR על GitHub עבור ה-branch — ללא אחת, אין merge target לאכוף, כל המדיניות מתקצרת להרשאה. ברגע שקיום `OPEN` PR מאושרת, שתי בדיקות עצמאיות מופעלות: +**ברירת מחדל:** מסרב עצירה כאשר הענף הנוכחי לא יכול להתמזג בנקיון לענף הבסיס. המדיניות תחילה מאשרת שיש PR `OPEN` ב-GitHub עבור הענף — ללא אחד, אין מטרה מיזוג לאכיפה, כך שכל המדיניות קטע קצר לאישור. פעם PR `OPEN` מאושר, שני בדיקות עצמאיות פועלות: -1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`. בהתנגשות, הודעת הדחייה מייעדת את קבצי ההתנגשות כדי Claude יודע בדיוק מה לפתור. -2. **GitHub** — משתמשת שוב בתוצאה של `gh pr view --json mergeable,state` שכבר הועלתה ב-precheck. תופסת conflicts שה-`origin/` stale local היה מיפסיד (למשל מישהו ירד PR מתנגשה על `main` מאז ה-fetch האחרון). `CONFLICTING` result דוחה. `UNKNOWN` result גם דוחה ומורה ל-Claude לחכות ~10 שניות ו-re-check לפני ניסיון עצירה שוב — זה מונע false negatives בעוד GitHub מחשבת מחדש. +1. **Local** — `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 שניות ובדיקה חוזרת לפני ניסיון להפסיק שוב — זה מונע false negatives בזמן GitHub מחשב מחדש. -Skips כליל (מאפשרת) כאשר: `gh` אינו מותקן, אין PR עבור ה-branch, state ה-PR אינו `OPEN` (למשל `MERGED`, `CLOSED`), או `gh pr view` מחזיר פלט לא parseable. גם fails open כאשר `origin/` חסר locally או כאשר אין commits ahead של base — אלה Layer 1 fall-throughs עדיין ייעוץ בcached PR mergeability לפני הרשאה. +Skips לחלוטין (מאפשרת) כאשר: `gh` לא מותקן, אין PR קיים עבור הענף, מצב ה-PR אינו `OPEN` (למשל `MERGED`, `CLOSED`), או `gh pr view` מחזיר פלט בלתי ניתן לניתוח. גם fails open כאשר `origin/` חסר מקומית או כאשר אין commits לפני בסיס — אלה Layer 1 fall-throughs עדיין יוועדו ל-cached PR mergeability לפני אישור. **פרמטרים:** -| Param | Type | Default | Description | +| פרמטר | סוג | ברירת מחדל | תיאור | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Base branch לבדיקת conflicts נגד. | +| `baseBranch` | `string` | `"main"` | ענף בסיס לבדיקה לעימות כנגד. | -GitHub CLI (`gh`) נדרש עבור מדיניות זו. המדיניות משתמשת ב-`gh pr view` להאשרת -קיום `OPEN` PR לפני הפעלת כל בדיקת conflicts — ללא `gh`, המדיניות מתקצרת -להרשאה. הפעל `gh auth login` עם personal access token שיש לו `repo` scope עבור -read access לpull requests. +GitHub CLI (`gh`) נדרש למדיניות זו. המדיניות משתמשת ב-`gh pr view` לאישור PR `OPEN` +קיים לפני הפעלת כל בדיקת עימות — ללא `gh`, המדיניות קטע קצר לאישור. הפעל `gh auth login` עם +personal access token שיש לו `repo` scope לגישת קריאה ל-pull requests. --- @@ -782,14 +778,14 @@ read access לpull requests. ### `require-ci-green-before-stop` **אירוע:** Stop -**ברירת מחדל:** שוללת עצירה כאשר בדיקות CI נכשלות או עדיין מופעלות על ה-branch הנוכחי. בודקת גם GitHub Actions workflow runs וגם בדיקות bot של צד שלישי (למשל CodeRabbit, SonarCloud, Codecov). מטפלת `skipped` ו-`cancelled` conclusions כהצלחה. מחזירה הודעה תובנה כאשר כל הבדיקות עוברות. +**ברירת מחדל:** מסרב עצירה כאשר בדיקות CI נכשלות או עדיין רצות על הענף הנוכחי. בדיקות גם GitHub Actions workflow runs וגם third-party bot checks (למשל CodeRabbit, SonarCloud, Codecov). מתייחס `skipped` ו-`cancelled` מסקנות כהצלחה. מחזיר הודעה אינפורמטיבית כאשר כל הבדיקות עוברות. -ללא פרמטרים. +אין פרמטרים. -מדיניות זו דורשת [GitHub CLI](https://cli.github.com/) (`gh`) להיות מותקנת והעתקית. -הפעל `gh auth login` עם personal access token שיש לו `repo` scope עבור read access ל -Actions workflow runs וה-Checks API. אם `gh` אינו מותקן או לא העתקי, המדיניות fails open ודוחה את הסיבה ל-Claude. +מדיניות זו דורשת [GitHub CLI](https://cli.github.com/) (`gh`) להתקיים ולהתאמת. +הפעל `gh auth login` עם personal access token שיש לו `repo` scope לגישת קריאה ל- +Actions workflow runs וה-Checks API. אם `gh` לא מותקן או לא מוצא, המדיניות fails open ודיווח הסיבה ל-Claude. --- @@ -798,7 +794,7 @@ Actions workflow runs וה-Checks API. אם `gh` אינו מותקן או לא ## השבתת מדיניויות בודדות -הסר מדיניות ספציפית מ-`enabledPolicies` בתצורה שלך, או החליף אותה בטאב Policies של ה-dashboard. +הסר מדיניות ספציפית מ-`enabledPolicies` בתצורה שלך, או החלף אותה ב-Policies tab של הלוח. ```json { @@ -809,4 +805,4 @@ Actions workflow runs וה-Checks API. אם `gh` אינו מותקן או לא } ``` -מדיניויות שלא מופיעות ב-`enabledPolicies` לא מופעלות, גם אם קיימות לה ערכי `policyParams`. \ No newline at end of file +מדיניויות שלא ברשימה ב-`enabledPolicies` לא רצות, גם אם ערכי `policyParams` קיימים עבורם. \ No newline at end of file diff --git a/docs/he/configuration.mdx b/docs/he/configuration.mdx index b578d609..92a446c1 100644 --- a/docs/he/configuration.mdx +++ b/docs/he/configuration.mdx @@ -1,29 +1,28 @@ --- ---- -title: תצורה -description: "פורמט קובץ הקונפיגורציה, מערכת שלוש-ההיקפים, וכללי המיזוג" +title: הגדרה +description: "פורמט קובץ הגדרה, מערכת שלוש-ההיקפים וכללי מיזוג" icon: gear --- -failproofai משתמש בקבצי תצורה JSON כדי לשלוט אילו מדיניויות פעילות, כיצד הן מתנהגות, ומאיפה מדיניויות מותאמות אישית נטענות. התצורה מעוצבת כדי להיות קלה לשיתוף עם הצוות שלך - בצע commit אותה אל הריפוזיטורי שלך וכל מפתח יקבל את אותו רשת ביטחון של סוכנים. +failproofai משתמש בקובצי הגדרה JSON כדי לשלוט אילו מדיניות פעילות, כיצד הן מתנהגות, ומהיכן מדיניות מותאמת אישית נטענת. ההגדרה מעוצבת כך שקל לשתף עם הצוות שלך - בצע commit לריפו שלך וכל מפתח יקבל את אותו רשת בטיחות לsagent. --- -## היקפי התצורה +## היקפי הגדרה -יש שלושה היקפי תצורה, המוערכים לפי סדר עדיפויות: +יש שלוש היקפי הגדרה, המוערכים לפי סדר עדיפויות: -| היקף | נתיב הקובץ | תכלית | +| היקף | נתיב קובץ | מטרה | |-------|-----------|---------| -| **פרויקט** | `.failproofai/policies-config.json` | הגדרות לכל ריפוזיטורי, משותפות ב-version control | -| **מקומי** | `.failproofai/policies-config.local.json` | דריסות אישיות לכל ריפוזיטורי, מנוצלות ב-gitignore | -| **גלובלי** | `~/.failproofai/policies-config.json` | ברירות מחדל ברמת המשתמש בכל הפרויקטים | +| **project** | `.failproofai/policies-config.json` | הגדרות לכל ריפו, committed לגרסה | +| **local** | `.failproofai/policies-config.local.json` | עקיפות אישיות לכל ריפו, gitignored | +| **global** | `~/.failproofai/policies-config.json` | ברירות מחדל ברמת המשתמש בכל הפרויקטים | -כאשר failproofai מקבל אירוע hook, הוא טוען ומזוג את כל שלושת הקבצים הקיימים עבור ספריית העבודה הנוכחית. +כאשר failproofai מקבל イベנט hook, היא טוענת ממזגת את כל שלושת הקובצים שקיימים עבור ספריית העבודה הנוכחית. -### כללי המיזוג +### כללי מיזוג -**`enabledPolicies`** - האיחוד של כל שלושת ההיקפים. מדיניות שמופעלת בכל רמה היא פעילה. +**`enabledPolicies`** - האיחוד של כל שלוש ההיקפים. מדיניות שפעילה בכל רמה היא פעילה. ```text project: ["block-sudo"] @@ -33,30 +32,30 @@ 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"] } ← פרויקט מנצח, global מתעלם +resolved: { allowPatterns: ["sudo apt-get update"] } ← project מנצח, global מתעלם ``` ```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"] } ← נופל דרך לגלובלי +resolved: { allowPatterns: ["sudo systemctl status"] } ← נופל דרך להיקף global ``` -**`customPoliciesPath`** - ההיקף הראשון שמגדיר אותו מנצח. +**`customPoliciesPath`** - ההיקף הראשון המגדיר אותו מנצח. -**`llm`** - ההיקף הראשון שמגדיר אותו מנצח. +**`llm`** - ההיקף הראשון המגדיר אותו מנצח. --- -## פורמט קובץ התצורה +## פורמט קובץ הגדרה ```json { @@ -97,85 +96,85 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← נופל דרך לג --- -## הפניית שדות +## התייחסות לשדות ### `enabledPolicies` -סוג: `string[]` +Type: `string[]` -רשימת שמות המדיניויות להפעלה. השמות חייבים להתאים בדיוק למזהי המדיניויות המוצגים על ידי `failproofai policies`. ראה [Built-in Policies](/he/built-in-policies) לקבלת הרשימה המלאה. +רשימת שמות מדיניות להפעלה. השמות חייבים להתאים בדיוק לזהויות המדיניות המוצגות על ידי `failproofai policies`. ראה [Built-in Policies](/he/built-in-policies) לקבלת הרשימה המלאה. -מדיניויות שלא ב-`enabledPolicies` אינן פעילות, גם אם יש להן ערכים ב-`policyParams`. +מדיניות שלא ב-`enabledPolicies` אינן פעילות, גם אם יש להן ערכים ב-`policyParams`. ### `policyParams` -סוג: `Record>` +Type: `Record>` -דריסות פרמטרים לכל מדיניות. המפתח החיצוני הוא שם המדיניות; המפתחות הפנימיים הם ספציפיים למדיניות. כל מדיניות תוקדם פרמטרים זמינים שלה ב-[Built-in Policies](/he/built-in-policies). +עקיפות פרמטרים לכל מדיניות. המפתח החיצוני הוא שם המדיניות; המפתחות הפנימיים הם ספציפיים למדיניות. כל מדיניות תיעד את הפרמטרים הזמינים שלה ב-[Built-in Policies](/he/built-in-policies). -אם למדיניות יש פרמטרים אך אתה לא מציין אותם, משמשות ברירות המחדל המובנות של המדיניות. משתמשים שלא מגדירים כלל `policyParams` מקבלים התנהגות זהה לגרסאות קודמות. +אם למדיניות יש פרמטרים אך אתה לא מציין אותם, משתמשים בברירות המחדל המובנות של המדיניות. משתמשים שלא מגדירים `policyParams` כלל מקבלים התנהגות זהה לגרסאות קודמות. -מפתחות לא ידועים בתוך בלוק הפרמטרים של מדיניות מתעלמים בשקט בעת ירי hook אך מסומנים כאזהרות כאשר אתה מריץ `failproofai policies`. +מפתחות לא ידועים בתוך בלוק הפרמטרים של מדיניות מתעלמים בשקט בעת הדלקת hook אך מסומנים כהזהרות כאשר אתה מריץ `failproofai policies`. -#### `hint` (חוצה-פעילויות) +#### `hint` (חוצה-תחום) -סוג: `string` (אופציונלי) +Type: `string` (optional) -הודעה הנוספת לסיבה כאשר מדיניות חוזרת `deny` או `instruct`. השתמש בה כדי לתן Claude הדרכה פעלנית ללא שינוי המדיניות עצמה. +הודעה המצורפת לסיבה כאשר מדיניות מחזירה `deny` או `instruct`. השתמש בה כדי להעניק Claude הנחיה ניתנת לביצוע מבלי לשנות את המדיניות עצמה. -עובד עם כל סוג מדיניות - מובנה, מותאמת אישית (`custom/`), קונוונציה של פרויקט (`.failproofai-project/`), או קונוונציה של משתמש (`.failproofai-user/`). +עובד עם כל סוג מדיניות — מובנה, מותאם אישית (`custom/`), קונוונציה פרויקט (`.failproofai-project/`), או קונוונציה משתמש (`.failproofai-user/`). ```json { "policyParams": { "block-force-push": { - "hint": "Try creating a fresh branch instead." + "hint": "נסה ליצור ענף טרי במקום." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], - "hint": "Use apt-get directly without sudo." + "hint": "השתמש ב-apt-get ישירות ללא sudo." }, "custom/my-policy": { - "hint": "Ask the user for approval first." + "hint": "בקש אישור מהמשתמש תחילה." } } } ``` -כאשר `block-force-push` שולל, Claude רואה: *"Force-pushing is blocked. Try creating a fresh branch instead."* +כאשר `block-force-push` מכחיש, Claude רואה: *Force-pushing is blocked. Try creating a fresh branch instead.* -ערכים שאינם מחרוזת ומחרוזות ריקות מתעלמים בשקט. אם `hint` לא מוגדר, ההתנהגות לא משתנה (תואם לאחור). +ערכים שאינם מחרוזת ומחרוזות ריקות מתעלמים בשקט. אם `hint` לא מוגדר, ההתנהגות אינה משתנה (תאימות לאחור). ### `customPoliciesPath` -סוג: `string` (נתיב מוחלט) +Type: `string` (absolute path) -נתיב לקובץ JavaScript המכיל מדיניויות hook מותאמות אישית. זה מוגדר באופן אוטומטי על ידי `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/`: | רמה | ספרייה | היקף | |-------|-----------|-------| -| פרויקט | `.failproofai/policies/` | משותף עם צוות דרך version control | -| משתמש | `~/.failproofai/policies/` | אישי, חל על כל הפרויקטים | +| Project | `.failproofai/policies/` | משותף לצוות דרך version control | +| 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` -סוג: `object` (אופציונלי) +Type: `object` (optional) -תצורת לקוח LLM עבור מדיניויות שמבצעות קריאות AI. לא נדרש עבור רוב ההגדרות. +הגדרת לקוח LLM למדיניות שעושות שיחות AI. לא נדרש לרוב התקנות. ```json { @@ -188,38 +187,46 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← נופל דרך לג --- -## ניהול תצורה מה-CLI +## ניהול הגדרה מ-CLI -הפקודות `policies --install` ו-`policies --uninstall` כותבות לקובץ הגדרות hook של CLI הסוכן שלך (נקודות כניסה hook), בעוד `policies-config.json` הוא הקובץ שאתה מנהל ישירות. השניים נפרדים: +הפקודות `policies --install` ו-`policies --uninstall` כותבות לקובץ הגדרות hook של agent CLI שלך (נקודות הכניסה של hook), בעוד `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 משתמשים בשדות פקודה `bash`/`powershell` שמוקדש ל-OS של Copilot עם `timeoutSec`; הקובץ נושא סימן `version: 1` ברמה העליונה. תמיכת Copilot CLI היא **beta** בזמן שאנו מאמתים את סכמת רשומות `events.jsonl` (שהדוקים הציבוריים לא מציינים) מול יותר סשנים בעולם אמיתי. -- **`policies-config.json`** — אומר ל-failproofai אילו מדיניויות להערך ועם אילו פרמטרים (משותף בכל Agent CLIs) +- **הגדרות Agent CLI** — אומר לsagent להקרא `failproofai --hook ` על כל 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 אינו בעל היקף `local` + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (user), `/.github/hooks/failproofai.json` (project) — Copilot אינו בעל היקף `local`. ערכי Hook משתמשים בשדות הפקודה של Copilot `bash`/`powershell` הממפתחים את מערכת ההפעלה עם `timeoutSec`; הקובץ משאיר סימן `version: 1` ברמה עליונה. תמיכת Copilot CLI היא **beta** בזמן שאנו מאמתים את סכמת הרישום `events.jsonl` (שהמסמכים הציבוריים לא מציינים) מול יותר סשנים בעולם האמיתי. + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — Cursor אינו בעל היקף `local`. ערכי Hook משתמשים בצורה Claude-shaped `{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` (user), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (project) — OpenCode אינו בעל היקף `local`. בניגוד לארבעת ה-CLIs האחרים, OpenCode **אינו בעל מערכת hook פקודה חיצונית**: היא טוענת בתוך-תהליך JS/TS plugins רשומים באופן מפורש דרך מערך `plugin: []` ב-`opencode.json` (גילוי אוטומטי מ-`.opencode/plugins/` **אינו** איך plugins נטענים ב-opencode v1.14.33). Install משחרר shim plugin קטן שנוצר שקורא subprocess לbinary failproofai ותורגם את התגובה JSON Claude-shape של binary חזרה לסמנטיקה של plugin (`throw new Error()` ל-deny, `client.session.prompt(...)` ל-instruct, no-op ל-allow). סשנים חיים ב-SQLite DB של 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 בעת ההתחלה; קובץ ההגדרות הוא מערך מחרוזת שטוח `{"packages": ["./relative/path", …]}`. failproofai כותב ערך אחד של מערך-packages המצביע על ספריית `pi-extension/` המקובצת שלה. ההרחבה באופן פנימי מנויה ל-Pi's `tool_call` / `user_bash` / `input` / `session_start` events ו-shells החוצה ל-`failproofai --hook --cli pi`; המטפל קנוני underscore_lower_snake_case → PascalCase דרך `PI_EVENT_MAP` כך שמדיניות מובנות קיימות יוצאות ללא שינוי. תמיכת Pi היא **beta** בזמן שבית-הנתונים API של Pi וסכמת session-log מתייצבות. + - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (user), `/.gemini/settings.json` (project) — 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 canonical דרך `GEMINI_EVENT_MAP`. שמות כלים הם snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — המטפל קנוני דרך `GEMINI_TOOL_MAP` כך שמדיניות מובנות קיימות יוצאות ללא שינוי. מעריך המדיניות פולט צורה שטוחה של Gemini `{decision: "deny", reason}` (מועדף לפי Gemini's "Golden Rule" exit-0 contract), `{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 איזו מדיניות להעריך ועם איזה params (משותף בכל agent CLIs) -עבור `--cli claude|codex|copilot` כדי לכוון סוכן ספציפי (מופרד בחללים או חזרה על תת-קבוצה): +עבור `--cli claude|codex|copilot|cursor|opencode|pi|gemini` כדי להשתמע ב-agent ספציפי (space-separated או חוזר על כל תת-קבוצה): ```bash failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project -failproofai policies --install --cli claude codex copilot +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 claude codex copilot cursor opencode pi gemini ``` -כאשר `--cli` הושמט, `failproofai` מגלה אילו Agent CLIs מותקנים (`which claude` / `which codex` / `which copilot`): +כאשר `--cli` מושמט, `failproofai` זוקפת איזה agent CLIs מותקנים (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): -- **CLI אחד מגולה** — בוחר אוטומטי את ה-CLI הזה ללא הנחמת. -- **CLIs מרובים מגלויים** בטרמינל אינטראקטיבי — מציג בחירת חד-נבחרת בחצים: כאשר שניים CLIs נוכחים הבחירות הן `Both`, ` only`, ` only`; עם שלושה CLIs האפשרות הראשונה הופכת ל-`All` (↑↓ להזוזה, Enter לבחירה, ^C לצאת). -- **CLIs מרובים מגלויים** בריצה לא-אינטראקטיבית (CI, ללא TTY) — מתקין עבור כל CLIs מגלויים ללא הנחמת. -- **אף אחד לא מגולה** — חוזר ל-`claude`, עם אזהרה שלא נמצא בינארי סוכן ב-PATH; פקודת ה-hook עדיין כתובה כך שהיא מופעלת ברגע שתתקין אחד. +- **CLI אחד זוקף** — auto-selects אותו CLI ללא שאלה. +- **CLIs מרובים זוקפים** בטרמינל אינטראקטיבי — מציג בחירת חץ-מקלדת יחידה במערכת אישור מחולקת לתוך חלק `Detected (N)` (עם שורת `Install for all N detected` aggregated + כל CLI זוקף בנפרדות) ו-`Not installed (M) · install hooks ahead of time` חלק המפרט כל CLI שלא זוקף שנתמך כאפשרות forward-install (↑↓ להזיז, Enter לבחור, ^C לצאת). זרימת ההסרה מציגה רק את החלק של Detected. +- **CLIs מרובים זוקפים** בריצה לא-אינטראקטיבית (CI, no TTY) — מתקנים עבור כל CLI זוקף ללא שאלה. +- **אף אחד לא זוקף** — חוזר ל-`claude`, עם אזהרה שלא agentinary binary נמצא ב-PATH; פקודת hook עדיין כתובה כך היא מופעלת ברגע שאתה מתקן אחד. -אתה יכול לערוך `policies-config.json` ישירות בכל עת; השינויים נכנסים לתוקף מיד בפני אירוע hook הבא ללא צורך בהפעלה מחדש. +אתה יכול לערוך `policies-config.json` ישירות בכל עת; שינויים נכנסים לתוקף מיד באירוע hook הבא ללא צורך בהפעלה מחדש. --- -## דוגמה: תצורת ברמת פרויקט עם ברירות מחדל של צוות +## דוגמה: תצורה ברמת פרויקט עם ברירות מחדל לצוות -Commit `.failproofai/policies-config.json` לריפוזיטורי שלך: +Commit `.failproofai/policies-config.json` לריפו שלך: ```json { @@ -238,4 +245,4 @@ Commit `.failproofai/policies-config.json` לריפוזיטורי שלך: } ``` -כל מפתח יכול ליצור `.failproofai/policies-config.local.json` (מנוצל ב-gitignore) לדריסות אישיות ללא השפעה על חברי הצוות. \ No newline at end of file +כל מפתח יכול לאחר מכן ליצור `.failproofai/policies-config.local.json` (gitignored) לעקיפות אישיות ללא השפעה על חברי צוות. \ No newline at end of file diff --git a/docs/he/dashboard.mdx b/docs/he/dashboard.mdx index 11cf47f5..f57bbbc7 100644 --- a/docs/he/dashboard.mdx +++ b/docs/he/dashboard.mdx @@ -1,11 +1,10 @@ --- ---- -title: לוח בקרה -description: "עקוב אחרי סשנים של סוכנים, בדוק קריאות כלים וניהל מדיניויות" +title: לוח הבקרה +description: "עקוב אחר הפעלות של סוכנים, בדוק קריאות כלים וניהל מדיניויות" icon: chart-line --- -לוח הבקרה של failproofai היא אפליקציית אינטרנט מקומית לניטור סשנים של סוכני AI וניהול מדיניויות. ראה מה עשו הסוכנים שלך בזמן שהיית רחוק. +לוח הבקרה של failproofai היא אפליקציית אינטרנט מקומית לעקיבה אחרי הפעלות סוכנים בינה מלאכותית וניהול מדיניויות. ראה מה עשו הסוכנים שלך בזמן שלא היית. --- @@ -15,65 +14,65 @@ 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)_ שנמצאים במכונה שלך. פרויקטי Claude מגוכלשו מ`~/.claude/projects/` (או הנתיב שהוגדר על ידי `CLAUDE_PROJECTS_PATH`); פרויקטי Codex מגוכלשו על ידי סריקת כל תמלול תחת `~/.codex/sessions///
/*.jsonl` וקיבוץ לפי ה`cwd` שנרשם בתיעוד הראשון של כל סשן; פרויקטי Copilot CLI מגוכלשו על ידי סריקת כל `~/.copilot/session-state//workspace.yaml` (ניתן להגדיר דרך `COPILOT_HOME`) וקיבוץ לפי שדה ה`cwd` שלו. פרויקט ששימש בו משתמשים במספר CLIs יוצג בשורה אחת עם כל התגיות המתאימות. השתמש בתפריט הנפתח **CLI** מעל הטבלה לסינון לפי סוכן CLI ספציפי; ה-URL שמר על הבחירה שלך כ`?cli=claude|codex|copilot`. +מפרט את כל פרויקטי 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 סוכן ספציפי; כתובת ה־URL שומרת את הבחירה שלך כ־`?cli=claude|codex|copilot|cursor|opencode|pi|gemini`. כל פרויקט מציג: -- שם הפרויקט (מתוך נתיב התיקייה) -- תגית CLI — `Claude Code` (כתום), `OpenAI Codex` (סגול), ו/או `GitHub Copilot` (כחול) -- תאריך פעילות הסשן האחרון +- שם הפרויקט (נגזר מנתיב התיקייה) +- תג CLI — `Claude Code` (כתום), `OpenAI Codex` (סגול), `GitHub Copilot` (כחול), `Cursor Agent` (ירוק תכלת), `OpenCode` (ענבר), `Pi` (ורוד), ו/או `Gemini CLI` (שמיים) +- תאריך של פעילות ההפעלה האחרונה -לחץ על פרויקט כדי לראות את הסשנים שלו. +לחץ על פרויקט כדי לראות את ההפעלות שלו. -### Sessions +### הפעלות -מפרטת את כל הסשנים בתוך פרויקט. כל סשן מציג: -- מזהה הסשן -- חותמות זמן התחלה וסיום +מפרט את כל ההפעלות בפרויקט. כל הפעלה מציגה: +- מזהה הפעלה +- חותמות זמן של התחלה וסיום - מספר קריאות כלים -- ספירת פעילות Hook (מדיניויות שיורו) +- ספירת פעילות hook (מדיניויות שהופעלו) -השתמש בסינון טווח התאריכים וחיפוש ID סשן כדי לצמצם את הרשימה. סשנים מחולקים לעמודים. +השתמש בסינון טווח התאריכים וחיפוש מזהה ההפעלה כדי לצמצם את הרשימה. הפעלות מדורגות. -לחץ על סשן כדי לפתוח את מציג הסשן. +לחץ על הפעלה כדי לפתוח את תצוגת ההפעלה. -### מציג סשן +### תצוגת ההפעלה -מציג הסשן עונה על השאלה העיקרית לסוכנים אוטונומיים: מה עשה הסוכן, והאם הוא נשאר בנתיב? תגית CLI ליד כותרת ההתחלה מציינת אם הסשן הוא תמלול Claude Code או OpenAI Codex. הוא מציג ציר זמן של כל מה שקרה בסשן: +תצוגת ההפעלה עונה על השאלה העיקרית עבור סוכנים אוטונומיים: מה עשה הסוכן, והאם הוא נשאר במסלול? תג CLI ליד הכותרת מציין האם ההפעלה היא תמלול Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, או Gemini CLI. היא מציגה ציר זמן של כל מה שקרה בהפעלה: -- **הודעות** - תגובות טקסט של Claude והנחיות המשתמש -- **קריאות כלים** - כל כלי שהשתמש בו Claude, עם הקלט והפלט שלו -- **פעילות מדיניות** - לכל קריאת כלי, איזה מדיניויות יורו ואיזו החלטה הן החזירו +- **הודעות** - תגובות טקסט של Claude והנחיות משתמש +- **קריאות כלים** - כל כלי שהשתמש Claude בו, עם הקלט והפלט שלו +- **פעילות מדיניות** - עבור כל קריאת כלי, אילו מדיניויות הופעלו והחלטה שהן החזירו -סרגל הסטטיסטיקה בחלק העליון מציג משך הסשן, סך הכל קריאות כלים, וסיכום של החלטות hook (ספירות allow / deny / instruct). +סרגל הסטטיסטיקה בחלק העליון מציג משך ההפעלה, סך הקריאות של כלים וסיכום של החלטות hook (ספירות allow / deny / instruct). -אתה יכול לייצא את הסשן כקובץ ZIP או JSONL באמצעות כפתור ההורדה. +לחץ על כפתור **Download Logs** כדי לייצא את ההפעלה. עבור Claude Code, Codex, Copilot, Cursor, Pi, וניסיונות Gemini תקבל את תמלול JSONL המקורי על הדיסק בתבנית זהה לבית; עבור OpenCode (שההפעלות שלה חיות ב־SQLite, לא על הדיסק) תקבל מסמך JSON המשקף את הטבלאות `session` / `messages` / `parts` הבסיסיות. -### Policies +### מדיניויות -עמוד בשתי כרטיסיות לניהול מדיניויות ובדיקת פעילות. +דף בן שני טבים לניהול מדיניויות ובדיקת פעילות. - - - החלף את המדיניויות הפרטניות פעם אחת בלחיצה (כותב ל`~/.failproofai/policies-config.json`) - - הרחב מדיניות כדי להגדיר את הפרמטרים שלה (למדיניויות התומכות `policyParams`) - - התקן או הסר hooks לטווח נתון - - הגדר נתיב קובץ מדיניויות מותאם אישית + + - הפעל או כבה מדיניויות בודדות בלחיצה אחת (כותב ל־`~/.failproofai/policies-config.json`) + - הרחב מדיניות כדי להגדיר את הפרמטרים שלה (עבור מדיניויות התומכות ב־`policyParams`) + - התקן או הסר hook עבור טווח נתון + - הגדר נתיב קובץ מדיניויות מותאם - - - היסטוריה מלאה המחולקת לעמודים של כל אירוע hook שיורה בכל הסשנים - - סנן לפי החלטה, סוג אירוע, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_), שם מדיניות, או ID סשן - - כל שורה מציגה: חותמת זמן, שם מדיניות, החלטה, תגית CLI (כתום = Claude Code, סגול = OpenAI Codex, כחול = GitHub Copilot), שם כלי, ID סשן, והסיבה להחלטות deny/instruct - - לחץ על ID סשן כדי לפתוח את התמלול שלו — הקורא גוכלש אוטומטית באיזה CLI יורה את ה-hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`) ויוצג את תגית CLI התואמת בכותרת + + - היסטוריה מדורגת מלאה של כל אירוע 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), שם כלי, מזהה הפעלה, והסיבה להחלטות deny/instruct + - לחץ על מזהה הפעלה כדי לפתוח את התמלול שלה — התצוגה זוהה אוטומטית איזה CLI הפעיל את ה־hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`) ומציגה את תג ה־CLI המתאים בכותרת @@ -81,31 +80,31 @@ failproofai ## רענון אוטומטי -לוח הבקרה כולל מתג רענון אוטומטי בניווט העליון. כאשר הוא מופעל, העמוד הנוכחי מתרענן מעת לעת כדי להציג סשנים חדשים ופעילות מדיניות כשהם מופיעים. חיוני לניטור סשנים של סוכנים אוטונומיים ארוכי טווח. +לוח הבקרה כולל בחירה לרענון אוטומטי בניווט העליון. כאשר מופעל, העמוד הנוכחי מרעננן מעת לעת כדי להציג הפעלות וטעינות מדיניות חדשות כשהן מופיעות. חיוני לעקיבה אחר הפעלות סוכנים אוטונומיים בתוקף. --- ## השבתת עמודים -אם אתה צריך רק חלקים מסוימים של לוח הבקרה, הגדר את `FAILPROOFAI_DISABLE_PAGES` לרשימה המופרדת בפסיקים של שמות עמודים: +אם אתה צריך רק חלקים מסוימים מלוח הבקרה, הגדר את `FAILPROOFAI_DISABLE_PAGES` לרשימה מופרדת בפסיקים של שמות עמודים: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai ``` -ערכים תקפים: `policies`, `projects`. +ערכים חוקיים: `policies`, `projects`. --- -## עיצוב +## ערכת נושא -לוח הבקרה תומך במצב בהיר וחשוך. החלף דרך הכפתור בסרגל הניווט. ההעדפה מאוחסנת בשמירת המקום המקומית של הדפדפן שלך. +לוח הבקרה תומך במצב בהיר וחשוך. הפעל דרך הכפתור בסרגל הניווט. ההעדפה מאוחסנת באחסון מקומי של הדפדפן שלך. --- ## הגדרת נתיב הפרויקטים -כברירת מחדל, לוח הבקרה קורא מספריית הפרויקטים הסטנדרטית של Claude Code. עקוף אותה לעבור משנה: +כברירת מחדל, לוח הבקרה קורא מתיקיית פרויקטי Claude Code הסטנדרטית. בטל אם כן להגדרות מותאמות: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -113,21 +112,21 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## גישה משם שאינו localhost +## גישה מכונה שאינה localhost -כאשר מריצים את לוח הבקרה ב**מצב פיתוח** (`npm run dev`) וגישה אליו משם הוא שאינו `localhost` - לדוגמה, דומיין מותאם אישית, IP מרחוק, או כתובת URL אוניברסלית - ייתכן שתראה אזהרה כמו: +כאשר הפעלת את לוח הבקרה במצב **dev** (`npm run dev`) וגישה אליו מ־hostname שאינו `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) שלו, שהוא תכונה רק לפיתוח. כדי לאפשר את השם שלך, השתמש בדגל `--allowed-origins`: +זה Next.js חוסם גישה חוצת־מקור ל־HMR (hot module reload) websocket שלו, שזה תכונה לפי פיתוח בלבד. כדי לאפשר את הכונן שלך, השתמש בדגל `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -עבור מספר שמות או IP-ים, העבר רשימה המופרדת בפסיקים: +עבור מחשבים או כתובות IP מרובים, pass רשימה מופרדת בפסיקים: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 @@ -140,5 +139,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -זה חל רק על מצב פיתוח. כאשר מריצים את `failproofai` (מצב ייצור), אין תרמיל HMR ואין בעיית משאב פיתוח חוצת מקור. +זה חל רק על מצב פיתוח. כאשר הפעלת `failproofai` (מצב ייצור), אין HMR websocket וללא בעיות של משאב פיתוח חוצה־מקור. \ No newline at end of file diff --git a/docs/he/getting-started.mdx b/docs/he/getting-started.mdx index e6180921..22f4088f 100644 --- a/docs/he/getting-started.mdx +++ b/docs/he/getting-started.mdx @@ -1,14 +1,13 @@ --- ---- -title: קבלת התחלה -description: "התקן את failproofai, הפעל מדיניות, והרשה לסוכנים שלך לפעול בצורה אמינה" +title: תחילת העבודה +description: "התקן את failproofai, הפעל מדיניות, והנח לסוכנים שלך לפעול בצורה אמינה" icon: rocket --- ## דרישות - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (אופציונלי - נדרש רק לבניה מקוד מקור) +- **Bun** >= 1.3.0 (אופציונלי - נדרש רק לבנייה מהקוד המקור) --- @@ -32,20 +31,24 @@ 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). כאשר יותר מאחד קיים, תתבקע להציע בחירה; העבור `--cli claude codex copilot` (כל תת-קבוצה) כדי לדלג על ההנחיה. + זה כותב ערכי 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 plugin שנוצר של 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` (כל תת-קבוצה) כדי לדלג על ההנמקה. - תמיכה ב-GitHub Copilot CLI היא **בטא** — התקן עם `--cli copilot`. + תמיכה ב-GitHub Copilot CLI, Cursor Agent, OpenCode, Pi ו-Gemini CLI הם **בטא** — התקן עם `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, או `--cli gemini`. ```bash failproofai policies --install --scope project failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project + 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 block-sudo block-rm-rf sanitize-api-keys ``` @@ -54,17 +57,17 @@ bun add -g failproofai failproofai policies ``` - מציג כל מדיניות, האם היא מופעלת, וכל פרמטר מוגדר. + מציג כל מדיניות, האם היא מופעלת, וכל פרמטרים מעוצבים. ```bash failproofai ``` - פותח לוח בקרה מקומי ב-`http://localhost:8020` שבו אתה יכול לעיין בהפעלות, לבחון קריאות כלים, ולנהל מדיניות. + פותח לוח בקרה מקומי ב-`http://localhost:8020` שבו אתה יכול לעיין בהפעלות, לבדוק קריאות כלים ולנהל מדיניות. - הפעל את Claude Code כרגיל. אם הסוכן מנסה משהו מסוכן, failproofai יתעכב עליו באופן אוטומטי. השאר אותו פועל ללא השגחה וסקור מה קרה בלוח הבקרה. + התחל את Claude Code כרגיל. אם הסוכן מנסה משהו מסוכן, failproofai יחצה אותו אוטומטית. השאר אותו פועל ללא השגחה וסקור את מה שקרה בלוח הבקרה. @@ -72,7 +75,7 @@ bun add -g failproofai ## איך מדיניות עובדת -בכל פעם שסוכן מריץ כלי, Claude Code קורא ל-failproofai כתהליך משנה: +בכל פעם שסוכן מפעיל כלי, Claude Code קוראה ל-failproofai כתהליך משנה: ```text Claude Code → failproofai --hook PreToolUse → קורא JSON מ-stdin @@ -83,18 +86,18 @@ Claude Code → failproofai --hook PreToolUse → קורא JSON מ-stdin כל מדיניות מחזירה אחת משלוש החלטות: - **allow** - הסוכן ממשיך בדרך רגילה -- **deny** - הפעולה חסומה, הסוכן מוסבר למה -- **instruct** - הקשר נוסף מתווסף להנחיית הסוכן +- **deny** - הפעולה חסומה, הסוכן מקבל הסבר למה +- **instruct** - הקשר נוסף מתווסף להנמקה של הסוכן -מדיניות רצה בתהליך המקומי שלך. שום דבר לא נשלח לשירות מרחוק. +מדיניות רצות בתהליך המקומי שלך. שום דבר לא נשלח לשירות מרוחק. --- -## הגדר מדיניות צוות עם מדיניות מבוססות כנס +## הגדר מדיניות לצוות עם מדיניות מבוססות כנס -הדרך המהירה ביותר לחוקים בעלי איכות בכל הצוות שלך היא ההנוהג `.failproofai/policies/`. זרוק קבצי מדיניות לתוך ספרייה זו והם טעונים באופן אוטומטי — ללא דגלים, ללא שינויי תצורה, ללא פקודות התקנה. +הדרך המהירה ביותר לקבוע תקנים איכות בכל הצוות שלך היא הכנס `.failproofai/policies/`. זרוק קבצי מדיניות לתוך הספריה הזו והם נטענים אוטומטית — ללא דגלים, ללא שינויי תצורה, ללא פקודות התקנה. @@ -103,7 +106,7 @@ Claude Code → failproofai --hook PreToolUse → קורא JSON מ-stdin ``` - העתק את דוגמאות ההתחלה או כתוב בעצמך: + העתק את דוגמאות ההתחלה או כתוב שלך: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -121,40 +124,40 @@ 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("Run tests before committing."); + return instruct("הרץ בדיקות לפני commit."); } return allow(); }, }); ``` - + ```bash git add .failproofai/policies/ - git commit -m "Add team quality policies" + git commit -m "הוסף מדיניות איכות לצוות" ``` - כל חבר בצוות שיש לו failproofai מותקן בוחר את המדיניות הללו באופן אוטומטי. ללא התקנה לכל מפתח. + כל חבר בצוות שיש לו failproofai מותקן יקטוף את המדיניות הללו אוטומטית. אין צורך בהגדרה לכל מפתח. -בצע עבודה של `.failproofai/policies/` לכל המאגר שלך כך שכל הצוות שלך חולק את אותם התקנים. כאשר הצוות שלך מגלה מצבי כשל חדשים, הוסף מדיניות ודחוף — כולם מקבלים את העדכון ב-`git pull` הבא שלהם. עם הזמן, המדיניות הללו הופכות לתקן איכות חי שממשיך להשתפר. +בצע commit ל-`.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` | דריסות אישיות (gitignored) | +| `.failproofai/policies-config.json` | תצורה לפי פרויקט (מובהקת) | +| `.failproofai/policies-config.local.json` | עדכונים אישיים (gitignored) | --- @@ -168,24 +171,24 @@ failproofai policies --uninstall --- -## הצעדים הבאים +## שלבים הבאים - טווח וקביעת קובץ תצורה + היקפים וקובץ תצורה - - כל 26 מדיניות עם פרמטרים + + כל 26 המדיניות עם פרמטרים - - כתוב את המדיניות שלך בJavaScript + + כתוב את המדיניות שלך ב-JavaScript - - מוניטור הפעלות וסקור פעילות מדיניות + + עקוב אחר הפעלות וסקור פעילות מדיניות \ No newline at end of file diff --git a/docs/hi/architecture.mdx b/docs/hi/architecture.mdx index b73c91e5..d75a3a56 100644 --- a/docs/hi/architecture.mdx +++ b/docs/hi/architecture.mdx @@ -1,23 +1,22 @@ --- - --- title: आर्किटेक्चर -description: "हुक हैंडलर, कॉन्फ़िगरेशन लोडिंग और पॉलिसी मूल्यांकन आंतरिक रूप से कैसे काम करते हैं" +description: "हुक हैंडलर, कॉन्फ़िग लोडिंग और पॉलिसी मूल्यांकन कैसे आंतरिक रूप से काम करते हैं" icon: sitemap --- -यह दस्तावेज़ बताता है कि failproofai आंतरिक रूप से कैसे काम करता है: हुक सिस्टम एजेंट टूल कॉल को कैसे इंटरसेप्ट करता है, कॉन्फ़िगरेशन कैसे लोड और मर्ज होता है, पॉलिसीज़ का मूल्यांकन कैसे होता है, और डैशबोर्ड एजेंट गतिविधि को कैसे मॉनिटर करता है। +यह दस्तावेज़ समझाता है कि failproofai आंतरिक रूप से कैसे काम करता है: हुक सिस्टम एजेंट टूल कॉल को कैसे अवरोधित करता है, कॉन्फ़िग कैसे लोड और मर्ज किया जाता है, पॉलिसीज़ का मूल्यांकन कैसे किया जाता है, और डैशबोर्ड एजेंट गतिविधि की निगरानी कैसे करता है। --- -## सारांश +## अवलोकन -failproofai के दो स्वतंत्र उपप्रणालियां हैं: +failproofai के दो स्वतंत्र सबसिस्टम हैं: -1. **हुक हैंडलर** - एक तेज़ CLI उपप्रक्रिया जो Claude Code हर एजेंट टूल कॉल पर आमंत्रित करती है। पॉलिसीज़ का मूल्यांकन करता है और एक निर्णय देता है। -2. **एजेंट मॉनिटर (डैशबोर्ड)** - एजेंट सत्रों की निगरानी और पॉलिसीज़ को प्रबंधित करने के लिए एक Next.js वेब एप्लिकेशन। +1. **हुक हैंडलर** - एक तेजी वाली CLI सबप्रोसेस जो Claude Code हर एजेंट टूल कॉल पर आमंत्रित करता है। पॉलिसीज़ का मूल्यांकन करता है और निर्णय लौटाता है। +2. **एजेंट मॉनिटर (डैशबोर्ड)** - एजेंट सेशन की निगरानी और पॉलिसीज़ को प्रबंधित करने के लिए एक Next.js वेब एप्लिकेशन। -दोनों उपप्रणालियां `~/.failproofai/` और प्रोजेक्ट की `.failproofai/` डायरेक्टरी में कॉन्फ़िगरेशन फ़ाइलें साझा करती हैं, लेकिन वे अलग-अलग प्रक्रियाओं के रूप में चलती हैं और केवल फ़ाइलसिस्टम के माध्यम से संचार करती हैं। +दोनों सबसिस्टम `~/.failproofai/` और प्रोजेक्ट की `.failproofai/` डायरेक्टरी में कॉन्फ़िग फाइलें साझा करते हैं, लेकिन वे अलग प्रक्रियाओं के रूप में चलते हैं और केवल फाइलसिस्टम के माध्यम से संचार करते हैं। --- @@ -46,7 +45,7 @@ failproofai के दो स्वतंत्र उपप्रणालि } ``` -Claude Code फिर प्रत्येक टूल कॉल से पहले `failproofai --hook PreToolUse` को एक उपप्रक्रिया के रूप में आमंत्रित करता है, stdin पर एक JSON पेलोड पास करता है। +Claude Code फिर हर टूल कॉल से पहले `failproofai --hook PreToolUse` को सबप्रोसेस के रूप में आमंत्रित करता है, stdin पर एक JSON पेलोड पास करता है। ### पेलोड प्रारूप @@ -62,9 +61,9 @@ Claude Code फिर प्रत्येक टूल कॉल से पह } ``` -`PostToolUse` इवेंट्स के लिए, पेलोड में टूल के आउटपुट के साथ `tool_result` भी शामिल है। +PostToolUse इवेंट के लिए, पेलोड में टूल के आउटपुट के साथ `tool_result` भी शामिल होता है। -हैंडलर 1 MB stdin सीमा लागू करता है। इस सीमा से अधिक पेलोड को छोड़ दिया जाता है और सभी पॉलिसीज़ अर्थपूर्ण रूप से अनुमति देती हैं। +हैंडलर 1 MB stdin सीमा लागू करता है। इस सीमा से अधिक पेलोड को छोड़ दिया जाता है और सभी पॉलिसीज़ निहित रूप से अनुमति देते हैं। ### प्रतिक्रिया प्रारूप @@ -87,7 +86,7 @@ Claude Code फिर प्रत्येक टूल कॉल से पह } ``` -**निर्देशन (Stop को छोड़कर किसी भी इवेंट):** +**निर्देश (कोई भी इवेंट Stop को छोड़कर):** ```json { "hookSpecificOutput": { @@ -96,9 +95,9 @@ Claude Code फिर प्रत्येक टूल कॉल से पह } ``` -**Stop इवेंट निर्देशन:** +**Stop इवेंट निर्देश:** - Exit code: `2` -- कारण stderr को लिखा गया (stdout को नहीं) +- stderr में लिखा गया कारण (stdout नहीं) **अनुमति दें:** - Exit code: `0` @@ -106,7 +105,7 @@ Claude Code फिर प्रत्येक टूल कॉल से पह **संदेश के साथ अनुमति दें:** -`allow(message)` एक पॉलिसी को Claude को सूचनात्मक संदर्भ भेजने देता है भले ही ऑपरेशन की अनुमति हो। हुक हैंडलर निम्नलिखित JSON को **stdout** में लिखता है (कॉन्फ़िगरेशन फ़ाइल में नहीं — यह हैंडलर की Claude Code को प्रतिक्रिया है, जैसे अस्वीकार और निर्देश प्रतिक्रियाएं ऊपर दी गई हैं): +`allow(message)` एक पॉलिसी को Claude के लिए सूचनात्मक संदर्भ वापस भेजने देता है यहां तक कि जब ऑपरेशन की अनुमति दी जाती है। हुक हैंडलर निम्नलिखित JSON को **stdout** में लिखता है (एक कॉन्फ़िग फाइल नहीं — यह हैंडलर की Claude Code के लिए प्रतिक्रिया है, जैसे deny और instruct प्रतिक्रिया ऊपर): ```json // हुक हैंडलर प्रक्रिया द्वारा stdout में लिखा गया @@ -117,10 +116,10 @@ Claude Code फिर प्रत्येक टूल कॉल से पह } ``` - Exit code: `0` (ऑपरेशन की अनुमति है) -- जब कई पॉलिसीज़ एक संदेश के साथ `allow` देती हैं, तो उनके संदेश नई पंक्तियों के साथ एक एकल `additionalContext` स्ट्रिंग में जुड़ जाते हैं -- यदि कोई पॉलिसी संदेश प्रदान नहीं करती है, तो stdout खाली है (पहले की तरह) +- जब कई पॉलिसीज़ संदेश के साथ `allow` लौटाती हैं, तो उनके संदेश नई लाइन के साथ एकल `additionalContext` स्ट्रिंग में जुड़ जाते हैं +- यदि कोई पॉलिसी संदेश प्रदान नहीं करती है, तो stdout खाली है (पहले जैसा ही) -### प्रोसेसिंग पाइपलाइन +### प्रसंस्करण पाइपलाइन `src/hooks/handler.ts` पूरी पाइपलाइन को लागू करता है: @@ -141,13 +140,13 @@ stdin JSON → exit ``` -बिना LLM कॉल्स के सामान्य पेलोड्स के लिए पूरी प्रक्रिया 100ms से कम में चलती है। +LLM कॉल के बिना विशिष्ट पेलोड के लिए पूरी प्रक्रिया 100ms में चलती है। --- -## कॉन्फ़िगरेशन लोडिंग +## कॉन्फ़िग लोडिंग -`src/hooks/hooks-config.ts` तीन-स्कोप कॉन्फ़िगरेशन लोडिंग को लागू करता है। +`src/hooks/hooks-config.ts` तीन-स्कोप कॉन्फ़िग लोडिंग को लागू करता है। ```text [1] {cwd}/.failproofai/policies-config.json ← project (highest priority) @@ -155,13 +154,13 @@ stdin JSON [3] ~/.failproofai/policies-config.json ← global (lowest priority) ``` -मर्ज तर्क: -- `enabledPolicies` - सभी तीन फ़ाइलों में डीडुप्लिकेटेड यूनियन -- `policyParams` - प्रति-पॉलिसी कुंजी, पहली फ़ाइल जो इसे परिभाषित करती है पूरी तरह जीतती है -- `customPoliciesPath` - पहली फ़ाइल जो इसे परिभाषित करती है जीतती है -- `llm` - पहली फ़ाइल जो इसे परिभाषित करती है जीतती है +मर्ज लॉजिक: +- `enabledPolicies` - तीनों फाइलों में डुप्लिकेट-मुक्त यूनियन +- `policyParams` - प्रति-पॉलिसी कुंजी, पहली फाइल जो इसे परिभाषित करती है पूरी तरह जीत जाती है +- `customPoliciesPath` - पहली फाइल जो इसे परिभाषित करती है जीत जाती है +- `llm` - पहली फाइल जो इसे परिभाषित करती है जीत जाती है -वेब डैशबोर्ड पढ़ने और लिखने के लिए `readHooksConfig()` (केवल वैश्विक) का उपयोग करता है, क्योंकि इसे प्रोजेक्ट cwd के साथ आमंत्रित नहीं किया जाता है। +वेब डैशबोर्ड `readHooksConfig()` (केवल global) का उपयोग पढ़ने और लिखने के लिए करता है, क्योंकि इसे प्रोजेक्ट cwd के साथ आमंत्रित नहीं किया जाता है। --- @@ -172,23 +171,23 @@ stdin JSON प्रत्येक पॉलिसी के लिए: 1. पॉलिसी के `params` स्कीमा को देखें (यदि इसके पास है)। -2. मर्ज किए गए कॉन्फ़िगरेशन से `policyParams[policy.name]` पढ़ें। -3. `ctx.params` बनाने के लिए स्कीमा डिफ़ॉल्ट्स पर उपयोगकर्ता-प्रदान किए गए मानों को मर्ज करें। -4. हल किए गए संदर्भ के साथ `policy.fn(ctx)` को कॉल करें। -5. यदि परिणाम `deny` है, तो तुरंत रुकें और उस निर्णय को वापस करें। -6. यदि परिणाम `instruct` है, तो संदेश को जमा करें और जारी रखें। +2. मर्ज किए गए कॉन्फ़िग से `policyParams[policy.name]` पढ़ें। +3. `ctx.params` का निर्माण करने के लिए स्कीमा डिफ़ॉल्ट पर उपयोगकर्ता-प्रदान किए गए मान को मर्ज करें। +4. समाधान किए गए कॉन्टेक्स्ट के साथ `policy.fn(ctx)` को कॉल करें। +5. यदि परिणाम `deny` है, तो तुरंत रुकें और उस निर्णय को लौटाएं। +6. यदि परिणाम `instruct` है, तो संदेश जमा करें और जारी रखें। 7. यदि परिणाम `allow` है, तो अगली पॉलिसी पर जाएं। सभी पॉलिसीज़ चलने के बाद: -- यदि कोई `deny` वापस किया गया था, तो अस्वीकार प्रतिक्रिया दें। -- यदि कोई `instruct` वापसी एकत्र किए गए थे, तो सभी संदेशों को जोड़ने के साथ एक एकल निर्देश प्रतिक्रिया दें। +- यदि कोई `deny` लौटाया गया था, तो deny प्रतिक्रिया दें। +- यदि कोई `instruct` लौटा हुआ संचित हुआ था, तो सभी संदेश जुड़े हुए एकल instruct प्रतिक्रिया दें। - अन्यथा, अनुमति प्रतिक्रिया दें (खाली stdout, exit 0)। --- -## अंतर्निहित पॉलिसीज़ +## बिल्ट-इन पॉलिसीज़ -`src/hooks/builtin-policies.ts` सभी 26 अंतर्निहित पॉलिसीज़ को `BuiltinPolicyDefinition` ऑब्जेक्ट्स के रूप में परिभाषित करता है: +`src/hooks/builtin-policies.ts` सभी 26 बिल्ट-इन पॉलिसीज़ को `BuiltinPolicyDefinition` ऑब्जेक्ट के रूप में परिभाषित करता है: ```typescript interface BuiltinPolicyDefinition { @@ -206,9 +205,9 @@ interface BuiltinPolicyDefinition { } ``` -जो पॉलिसीज़ `params` स्वीकार करती हैं वे प्रत्येक पैरामीटर के लिए प्रकार और डिफ़ॉल्ट्स के साथ `PolicyParamsSchema` घोषित करती हैं। पॉलिसी मूल्यांकन `fn` को कॉल करने से पहले `ctx.params` में हल किए गए मानों को इंजेक्ट करता है। पॉलिसी फ़ंक्शन्स `ctx.params` को पढ़ते हैं बिना null-गार्डिंग के क्योंकि डिफ़ॉल्ट्स हमेशा पहले लागू होते हैं। +जो पॉलिसीज़ `params` स्वीकार करती हैं वे प्रत्येक पैरामीटर के लिए प्रकार और डिफ़ॉल्ट के साथ `PolicyParamsSchema` की घोषणा करती हैं। पॉलिसी मूल्यांकनकर्ता `fn` को कॉल करने से पहले समाधान किए गए मानों को `ctx.params` में इंजेक्ट करता है। पॉलिसी फंक्शन null-गार्डिंग के बिना `ctx.params` को पढ़ते हैं क्योंकि डिफ़ॉल्ट हमेशा पहले लागू होते हैं। -पॉलिसीज़ के अंदर पैटर्न मिलान पार्स किए गए कमांड टोकन्स (argv) का उपयोग करता है, कच्ची स्ट्रिंग मिलान नहीं। यह shell ऑपरेटर इंजेक्शन के माध्यम से बाईपास को रोकता है (उदाहरण के लिए `sudo systemctl status *` के लिए एक पैटर्न को `; rm -rf /` को जोड़कर बाईपास नहीं किया जा सकता)। +पॉलिसीज़ के अंदर पैटर्न मिलान कच्ची स्ट्रिंग मिलान के बजाय पार्स किए गए कमांड टोकन (argv) का उपयोग करता है। यह shell ऑपरेटर इंजेक्शन के माध्यम से बाईपास को रोकता है (जैसे `sudo systemctl status *` के लिए एक पैटर्न को `; rm -rf /` जोड़कर बाईपास नहीं किया जा सकता)। --- @@ -227,25 +226,25 @@ export function getCustomHooks(): CustomHook[] { ... } 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` फ़ाइलें लिखें और प्रविष्टि फ़ाइल को `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` में लॉग किया जाता है और लोडर एक खाली सरणी देता है। अंतर्निहित पॉलिसीज़ प्रभावित नहीं होती हैं। +किसी भी त्रुटि पर (फाइल नहीं मिली, सिंटैक्स त्रुटि, आयात विफलता), त्रुटि को `~/.failproofai/hook.log` में लॉग किया जाता है और लोडर एक खाली सरणी लौटाता है। बिल्ट-इन पॉलिसीज़ प्रभावित नहीं होती हैं। -कस्टम पॉलिसीज़ का मूल्यांकन सभी अंतर्निहित पॉलिसीज़ के बाद किया जाता है। एक कस्टम पॉलिसी `deny` अभी भी आगे की कस्टम पॉलिसीज़ को छोटा करता है (लेकिन सभी अंतर्निहित पॉलिसीज़ पहले ही चल चुकी हैं)। +कस्टम पॉलिसीज़ का मूल्यांकन सभी बिल्ट-इन पॉलिसीज़ के बाद किया जाता है। एक कस्टम पॉलिसी `deny` अभी भी आगे कस्टम पॉलिसीज़ को शॉर्ट-सर्किट करता है (लेकिन सभी बिल्ट-इन्स पहले ही चल चुकी हैं)। --- ## गतिविधि लॉगिंग -प्रत्येक हुक इवेंट के बाद, हैंडलर `~/.failproofai/hook-activity.jsonl` में एक JSONL पंक्ति जोड़ता है: +प्रत्येक हुक इवेंट के बाद, हैंडलर `~/.failproofai/hook-activity.jsonl` में एक JSONL लाइन जोड़ता है: ```json { @@ -260,13 +259,13 @@ 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/ @@ -283,25 +282,25 @@ app/ get-hook-activity.ts ← Paginate/search activity log install-hooks-web.ts ← Install/remove hooks from the browser api/ - download/[project]/[session]/route.ts ← Export session as ZIP/JSONL + download/[project]/[session]/route.ts ← Per-CLI session export (JSONL or JSON) ``` **डेटा प्रवाह:** -- पेज कंपोनेंट्स प्रोजेक्ट/सेशन डेटा को सीधे फ़ाइलसिस्टम से पढ़ने के लिए `lib/projects.ts` और `lib/log-entries.ts` को कॉल करते हैं (पढ़ने के लिए कोई API परत नहीं)। -- पॉलिसीज़ पेज सभी म्यूटेशन्स के लिए Server Actions का उपयोग करता है (टॉगल, पैरामीटर अपडेट, इंस्टॉल/निकालना)। -- सेशन दर्शक Claude की JSONL ट्रांसक्रिप्ट प्रारूप को पार्स करता है और संदेशों और टूल कॉल्स की एक समयरेखा प्रस्तुत करता है। +- पेज कंपोनेंट `lib/projects.ts` और `lib/log-entries.ts` को कॉल करते हैं ताकि फाइलसिस्टम से सीधे प्रोजेक्ट/सेशन डेटा पढ़ा जा सके (रीड्स के लिए कोई API लेयर नहीं)। +- पॉलिसीज़ पेज सभी म्यूटेशन (टॉगल, पैरामीटर अपडेट, इंस्टॉल/हटाना) के लिए Server Actions का उपयोग करता है। +- सेशन व्यूअर Claude के JSONL ट्रांसक्रिप्ट प्रारूप को पार्स करता है और संदेश और टूल कॉल की एक टाइमलाइन प्रस्तुत करता है। **मुख्य डिज़ाइन निर्णय:** -- कोई डेटाबेस नहीं - सभी स्थायी स्थिति सादी फ़ाइलों में है (`~/.failproofai/`, `~/.claude/projects/`)। -- म्यूटेशन्स के लिए Server Actions - CRUD ऑपरेशन्स के लिए कोई REST API आवश्यक नहीं है। -- पढ़ने पन्नों के लिए React Server Components - तेज़ प्रारंभिक लोड, डेटा फेचिंग के लिए कोई क्लाइंट बंडल नहीं। -- क्लाइंट कंपोनेंट्स केवल जहां इंटरैक्टिविटी आवश्यक है (पॉलिसी टॉगल, गतिविधि खोज, लॉग दर्शक)। +- कोई डेटाबेस नहीं - सभी स्थायी स्थिति सादा फाइलों में है (`~/.failproofai/`, `~/.claude/projects/`)। +- म्यूटेशन के लिए Server Actions - CRUD ऑपरेशन के लिए कोई REST API की आवश्यकता नहीं है। +- रीड पेज के लिए React Server Components - तेजी से प्रारंभिक लोड, डेटा फेचिंग के लिए कोई क्लाइंट बंडल नहीं। +- क्लाइंट कंपोनेंट केवल जहां इंटरएक्टिविटी आवश्यक है (पॉलिसी टॉगल, गतिविधि खोज, लॉग व्यूअर)। --- -## फ़ाइल लेआउट +## फाइल लेआउट ```text failproofai/ diff --git a/docs/hi/built-in-policies.mdx b/docs/hi/built-in-policies.mdx index 535ababa..ab17c8ce 100644 --- a/docs/hi/built-in-policies.mdx +++ b/docs/hi/built-in-policies.mdx @@ -1,40 +1,39 @@ --- ---- -title: बिल्ट-इन पॉलिसीज़ -description: "सभी 39 बिल्ट-इन पॉलिसीज़ जो एजेंट की आम विफलताओं को रोकती हैं" +title: निर्मित नीतियाँ +description: "सभी 39 निर्मित नीतियाँ जो एजेंट की सामान्य विफलता मोड को पकड़ती हैं" icon: shield --- -failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ आता है जो एजेंट की आम विफलताओं को रोकती हैं। प्रत्येक पॉलिसी एक विशिष्ट हुक इवेंट टाइप और टूल नाम पर सक्रिय होती है। उन्नीस पॉलिसीज़ पैरामीटर स्वीकार करती हैं जो आपको कोड लिखे बिना उनके व्यवहार को ट्यून करने देते हैं। पाँच वर्कफ़्लो पॉलिसीज़ Claude को रोकने से पहले एक कमिट → पुश → PR → CI पाइपलाइन लागू करती हैं। +failproofai 39 निर्मित नीतियों के साथ आता है जो एजेंट की सामान्य विफलता मोड को पकड़ते हैं। प्रत्येक नीति एक विशिष्ट हुक ईवेंट प्रकार और टूल नाम पर काम करती है। उन्नीस नीतियाँ पैरामीटर स्वीकार करती हैं जो आपको कोड लिखे बिना उनके व्यवहार को समायोजित करने देती हैं। पाँच वर्कफ़्लो नीतियाँ कमिट → पुश → PR → CI पाइपलाइन को लागू करती हैं इससे पहले कि Claude रुक जाए। --- ## अवलोकन -पॉलिसीज़ को श्रेणियों में विभाजित किया गया है: +नीतियों को श्रेणियों में विभाजित किया गया है: -| श्रेणी | पॉलिसीज़ | हुक टाइप | +| श्रेणी | नीतियाँ | हुक प्रकार | |----------|----------|-----------| -| [खतरनाक कमांड](#खतरनाक-कमांड) | 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 | -| [वर्कफ़्लो](#वर्कफ़्लो) | 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-`** — एजेंट इसे देखने से पहले टूल आउटपुट से संवेदनशील डेटा को साफ़ करता है। +- **`warn-`** — एजेंट को अतिरिक्त संदर्भ देता है ताकि वह स्वयं को ठीक कर सके। +- **`sanitize-`** — एजेंट इसे देखने से पहले टूल आउटपुट से संवेदनशील डेटा हटाता है। ### नेमस्पेस -प्रत्येक पॉलिसी एक `/` स्लॉट में रहती है। बिल्ट-इन पॉलिसीज़ **`exospherehost/`** नेमस्पेस से संबंधित हैं — उदाहरण के लिए, `exospherehost/sanitize-jwt`। नेमस्पेस यह सुनिश्चित करता है कि जब आप समान नामों की कस्टम या तीसरे पक्ष की पॉलिसीज़ भी लोड करते हैं तो कोई टकराव न हो। +प्रत्येक नीति एक `/` स्लॉट में रहती है। निर्मित नीतियाँ **`exospherehost/`** नेमस्पेस से संबंधित हैं — उदाहरण के लिए, `exospherehost/sanitize-jwt`। नेमस्पेस उन टकरावों को रोकता है जब आप समान छोटे नामों वाली कस्टम या तीसरे पक्ष की नीतियाँ भी लोड करते हैं। -अपनी कॉन्फ़िगरेशन में आप एक बिल्ट-इन को इसके छोटे नाम या योग्य नाम दोनों से संदर्भित कर सकते हैं; दोनों रूप एक ही पॉलिसी को हल करते हैं: +अपने कॉन्फ़िग में, आप एक निर्मित नीति को इसके छोटे नाम या योग्य नाम दोनों से संदर्भित कर सकते हैं; दोनों रूप एक ही नीति को हल करते हैं: ```json { @@ -45,33 +44,33 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ } ``` -यदि किसी नाम में कोई `/` नहीं है, तो failproofai इसे डिफ़ॉल्ट नेमस्पेस `exospherehost` से संबंधित मानता है। जिन नामों में पहले से `/` है (जैसे `myorg/foo`, `custom/my-hook`), उन्हें जैसे हैं वैसे ही रखा जाता है। -- **`require-`** — Stop इवेंट को तब तक ब्लॉक करता है जब तक शर्तें पूरी न हो जाएँ। +यदि एक नाम में कोई `/` नहीं है, तो failproofai इसे डिफ़ॉल्ट नेमस्पेस `exospherehost` से संबंधित मानता है। जो नाम पहले से ही `/` युक्त हैं (जैसे `myorg/foo`, `custom/my-hook`) को जैसे हैं वैसे ही रखा जाता है। +- **`require-`** — Stop ईवेंट को तब तक ब्लॉक करता है जब तक शर्तें पूरी न हो जाएँ। --- -हर पॉलिसी `policyParams` में एक वैकल्पिक `hint` फ़ील्ड सपोर्ट करती है। हिंट को deny या instruct संदेश में जोड़ा जाता है जो Claude देखता है, जिससे बिना पॉलिसी कोड को संशोधित किए कार्रवाई योग्य मार्गदर्शन मिलता है। बिल्ट-इन, कस्टम और कन्वेंशन पॉलिसीज़ के साथ काम करता है। विवरण के लिए [Configuration → hint](/hi/configuration#hint-cross-cutting) देखें। +प्रत्येक नीति `policyParams` में एक वैकल्पिक `hint` फ़ील्ड का समर्थन करती है। हिंट को deny या instruct संदेश में जोड़ा जाता है जो Claude देखता है, नीति कोड को संशोधित किए बिना कार्रवाई योग्य मार्गदर्शन प्रदान करता है। निर्मित, कस्टम, और सम्मेलन नीतियों के साथ काम करता है। विवरण के लिए [कॉन्फ़िगरेशन → hint](/hi/configuration#hint-cross-cutting) देखें। --- ## खतरनाक कमांड -एजेंट्स को ऐसी ऑपरेशन्स चलाने से रोकें जो कम करने में मुश्किल हों या होस्ट सिस्टम को नुकसान पहुँचा सकें। +एजेंटों को उन ऑपरेशन चलाने से रोकें जो कम करना मुश्किल हैं या होस्ट सिस्टम को नुकसान पहुंचा सकते हैं। ### `block-sudo` -**इवेंट:** PreToolUse (Bash) +**ईवेंट:** PreToolUse (Bash) **डिफ़ॉल्ट:** किसी भी `sudo` कमांड को अस्वीकार करता है। -किसी भी `sudo` कीवर्ड वाली इनवोकेशन को ब्लॉक करता है। पैटर्न मिलान कच्ची स्ट्रिंग के बजाय पार्स किए गए कमांड टोकन पर किया जाता है, जिससे शेल ऑपरेटर इंजेक्शन के माध्यम से बायपास रोका जा सके। +`sudo` कीवर्ड युक्त आह्वानों को ब्लॉक करता है। पैटर्न मिलान raw स्ट्रिंग पर नहीं बल्कि पार्स किए गए कमांड टोकन पर किया जाता है, ताकि शेल ऑपरेटर इंजेक्शन के माध्यम से बाईपास को रोका जा सके। **पैरामीटर:** -| पैरामीटर | टाइप | डिफ़ॉल्ट | विवरण | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | सटीक कमांड प्रीफ़िक्स जो अनुमति दिए गए हैं। प्रत्येक एंट्री को पार्स किए गए argv टोकन के विरुद्ध मिलाया जाता है। | +| `allowPatterns` | `string[]` | `[]` | सटीक कमांड उपसर्ग जो अनुमति हैं। प्रत्येक प्रविष्टि को पार्स किए गए argv टोकन के विरुद्ध मिलाया जाता है। | **उदाहरण:** @@ -85,24 +84,24 @@ 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 *` से मेल नहीं खाता। +पैटर्न को raw कमांड स्ट्रिंग के बजाय पार्स किए गए टोकन के विरुद्ध मिलाया जाता है। यह परिशिष्ट शेल ऑपरेटर के माध्यम से बाईपास को रोकता है (उदाहरण के लिए `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`)। | +| `allowPaths` | `string[]` | `[]` | पथ जो पुनरावर्ती रूप से हटाने के लिए सुरक्षित हैं (उदाहरण के लिए `/tmp`)। | **उदाहरण:** @@ -120,8 +119,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-curl-pipe-sh` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** `curl | bash`, `curl | sh`, `wget | bash` और समान पैटर्न को अस्वीकार करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `curl | bash`, `curl | sh`, `wget | bash`, और समान पैटर्न को अस्वीकार करता है। कोई पैरामीटर नहीं। @@ -129,8 +128,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-failproofai-commands` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** उन कमांड्स को अस्वीकार करता है जो failproofai को अनइंस्टॉल या अक्षम करेंगे (जैसे `npm uninstall failproofai`, `failproofai policies --uninstall`)। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** ऐसी कमांडों को अस्वीकार करता है जो failproofai को स्वयं अनइंस्टॉल या अक्षम करेंगी (उदाहरण के लिए `npm uninstall failproofai`, `failproofai policies --uninstall`)। कोई पैरामीटर नहीं। @@ -138,20 +137,20 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ## इंफ्रा कमांड -कोडिंग एजेंट्स को इंफ्रास्ट्रक्चर CLIs चलाने या CI/CD पाइपलाइन को ट्रिगर करने से रोकें। इस श्रेणी की सभी पॉलिसीज़ **ऑप्ट-इन** हैं (`defaultEnabled: false`) — एजेंट जिन्हें वास्तव में `kubectl`, `terraform` आदि को कॉल करने की आवश्यकता है, वे पॉलिसी को सक्षम किए जाने तक बाधित नहीं होंगे। जब सक्षम किया जाता है, तो मिलान किए गए CLI की प्रत्येक इनवोकेशन को अस्वीकार कर दिया जाता है जब तक कि कमांड `allowPatterns` में एक एंट्री से मेल न खाए। +कोडिंग एजेंटों को इंफ्रास्ट्रक्चर CLIs चलाने या CI/CD पाइपलाइन ट्रिगर करने से रोकता है। इस श्रेणी में सभी नीतियाँ **opt-in** (`defaultEnabled: false`) हैं — ऐसे एजेंट जिन्हें वास्तव में `kubectl`, `terraform`, आदि को कॉल करने की आवश्यकता है, वे तब तक परेशान नहीं होंगे जब तक आप नीति को सक्षम न करें। जब सक्षम हो, तो मिलान की गई CLI के प्रत्येक आह्वान को अस्वीकार किया जाता है जब तक कि कमांड `allowPatterns` में किसी प्रविष्टि से मेल न खाए। -पैटर्न व्याकरण [`block-sudo`](#block-sudo) के समान है: टोकन को पार्स किए गए argv के विरुद्ध मिलाया जाता है, `*` एक टोकन के लिए वाइल्डकार्ड है, और किसी भी कमांड में एक अलग शेल ऑपरेटर (`&&`, `||`, `|`, `;`) या एम्बेडेड शेल मेटाकैरेक्टर के साथ एक टोकन इंजेक्शन बायपास रोकने के लिए allowlist मिलान से पहले अस्वीकार किया जाता है। +पैटर्न ग्रामर [`block-sudo`](#block-sudo) के समान है: टोकन को पार्स किए गए argv के विरुद्ध मिलाया जाता है, `*` एक टोकन के लिए वाइल्डकार्ड है, और कोई भी कमांड जिसमें एक स्टैंडअलोन शेल ऑपरेटर (`&&`, `||`, `|`, `;`) या एम्बेड किए गए शेल मेटाकैरेक्टर वाला टोकन है, इंजेक्शन बाईपास को रोकने के लिए allowlist मिलान से पहले अस्वीकार किया जाता है। ### `block-kubectl` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** किसी भी `kubectl` इनवोकेशन को अस्वीकार करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** किसी भी `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) इनवोकेशन को अस्वीकार करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** किसी भी `terraform` या `tofu` (OpenTofu) आह्वान को अस्वीकार करता है। **पैरामीटर:** -| पैरामीटर | टाइप | डिफ़ॉल्ट | विवरण | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | terraform/tofu कमांड प्रीफ़िक्स जो अनुमति दिए गए हैं। | +| `allowPatterns` | `string[]` | `[]` | terraform/tofu कमांड उपसर्ग जो अनुमति हैं। | **उदाहरण:** @@ -196,14 +195,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-aws-cli` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** किसी भी `aws` CLI इनवोकेशन को अस्वीकार करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** किसी भी `aws` CLI आह्वान को अस्वीकार करता है। **पैरामीटर:** -| पैरामीटर | टाइप | डिफ़ॉल्ट | विवरण | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | aws CLI कमांड प्रीफ़िक्स जो अनुमति दिए गए हैं। | +| `allowPatterns` | `string[]` | `[]` | aws CLI कमांड उपसर्ग जो अनुमति हैं। | **उदाहरण:** @@ -221,14 +220,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-gcloud` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** किसी भी `gcloud` (Google Cloud) CLI इनवोकेशन को अस्वीकार करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** किसी भी `gcloud` (Google Cloud) CLI आह्वान को अस्वीकार करता है। **पैरामीटर:** -| पैरामीटर | टाइप | डिफ़ॉल्ट | विवरण | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | gcloud कमांड प्रीफ़िक्स जो अनुमति दिए गए हैं। | +| `allowPatterns` | `string[]` | `[]` | gcloud कमांड उपसर्ग जो अनुमति हैं। | **उदाहरण:** @@ -246,14 +245,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-az-cli` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** किसी भी `az` (Azure) CLI इनवोकेशन को अस्वीकार करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** किसी भी `az` (Azure) CLI आह्वान को अस्वीकार करता है। **पैरामीटर:** -| पैरामीटर | टाइप | डिफ़ॉल्ट | विवरण | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | az CLI कमांड प्रीफ़िक्स जो अनुमति दिए गए हैं। | +| `allowPatterns` | `string[]` | `[]` | az CLI कमांड उपसर्ग जो अनुमति हैं। | **उदाहरण:** @@ -271,14 +270,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `block-helm` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** किसी भी `helm` इनवोकेशन को अस्वीकार करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** किसी भी `helm` आह्वान को अस्वीकार करता है। **पैरामीटर:** -| पैरामीटर | टाइप | डिफ़ॉल्ट | विवरण | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | helm कमांड प्रीफ़िक्स जो अनुमति दिए गए हैं। | +| `allowPatterns` | `string[]` | `[]` | helm कमांड उपसर्ग जो अनुमति हैं। | **उदाहरण:** @@ -296,8 +295,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `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` @@ -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/.../...` इस पॉलिसी द्वारा मेल नहीं खाते — ये वर्कफ़्लो चेक के लिए नियमित रूप से आवश्यक होते हैं (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[]` | `[]` | विशिष्ट लिपिबद्ध आह्वान जिन्हें अनुमति देनी है भले ही वे अन्यथा अस्वीकार हो जाएँ। | **उदाहरण:** @@ -328,14 +327,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ --- -## सीक्रेट्स (सैनिटाइज़र) +## सीक्रेट (सैनिटाइज़र) -एजेंट्स को अपने संदर्भ या आउटपुट में क्रेडेंशियल्स लीक करने से रोकें। सैनिटाइज़र पॉलिसीज़ **PostToolUse** इवेंट्स पर फायर करती हैं। जब Claude एक Bash कमांड चलाता है, एक फ़ाइल पढ़ता है, या कोई भी टूल कॉल करता है, ये पॉलिसीज़ इसे Claude को वापस किए जाने से पहले आउटपुट को निरीक्षण करती हैं। यदि कोई सीक्रेट पैटर्न पाया जाता है, तो पॉलिसी एक deny निर्णय लौटाती है जो आउटपुट को वापस किए जाने से रोकता है। +एजेंटों को अपने संदर्भ या आउटपुट में क्रेडेंशियल लीक करने से रोकता है। सैनिटाइज़र नीतियाँ **PostToolUse** ईवेंट पर काम करती हैं। जब Claude एक Bash कमांड चलाता है, एक फ़ाइल पढ़ता है, या कोई भी टूल कॉल करता है, तो ये नीतियाँ आउटपुट का निरीक्षण करती हैं इससे पहले कि यह Claude को वापस किया जाए। यदि एक सीक्रेट पैटर्न का पता चला है, तो नीति एक अस्वीकार निर्णय देती है जो आउटपुट को पास होने से रोकता है। ### `sanitize-jwt` -**इवेंट:** PostToolUse (सभी टूल्स) -**डिफ़ॉल्ट:** JWT टोकन्स को रिडैक्ट करता है (तीन base64url सेगमेंट `.` से अलग)। +**ईवेंट:** PostToolUse (सभी टूल) +**डिफ़ॉल्ट:** JWT टोकन को (`.` से अलग तीन base64url सेगमेंट) को सेंसर करता है। कोई पैरामीटर नहीं। @@ -343,14 +342,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `sanitize-api-keys` -**इवेंट:** PostToolUse (सभी टूल्स) -**डिफ़ॉल्ट:** सामान्य API की फॉर्मेट्स को रिडैक्ट करता है: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS एक्सेस की (`AKIA`), Stripe की (`sk_live_`, `sk_test_`), और Google API की (`AIza`)। +**ईवेंट:** PostToolUse (सभी टूल) +**डिफ़ॉल्ट:** सामान्य 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 पैटर्न। | **उदाहरण:** @@ -371,8 +370,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `sanitize-connection-strings` -**इवेंट:** PostToolUse (सभी टूल्स) -**डिफ़ॉल्ट:** डेटाबेस कनेक्शन स्ट्रिंग्स को रिडैक्ट करता है जिनमें एम्बेडेड क्रेडेंशियल्स होते हैं (जैसे `postgresql://user:password@host/db`)। +**ईवेंट:** PostToolUse (सभी टूल) +**डिफ़ॉल्ट:** एम्बेड किए गए क्रेडेंशियल युक्त डेटाबेस कनेक्शन स्ट्रिंग को सेंसर करता है (उदाहरण के लिए `postgresql://user:password@host/db`)। कोई पैरामीटर नहीं। @@ -380,8 +379,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `sanitize-private-key-content` -**इवेंट:** PostToolUse (सभी टूल्स) -**डिफ़ॉल्ट:** PEM ब्लॉक्स को रिडैक्ट करता है (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, आदि)। +**ईवेंट:** PostToolUse (सभी टूल) +**डिफ़ॉल्ट:** PEM ब्लॉक को सेंसर करता है (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, आदि)। कोई पैरामीटर नहीं। @@ -389,8 +388,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `sanitize-bearer-tokens` -**इवेंट:** PostToolUse (सभी टूल्स) -**डिफ़ॉल्ट:** `Authorization: Bearer ` हेडर्स को रिडैक्ट करता है जहाँ टोकन 20 या अधिक कैरेक्टर है। +**ईवेंट:** PostToolUse (सभी टूल) +**डिफ़ॉल्ट:** `Authorization: Bearer ` हेडर को सेंसर करता है जहाँ टोकन 20 या अधिक वर्णों का हो। कोई पैरामीटर नहीं। @@ -398,14 +397,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ## पर्यावरण -संवेदनशील पर्यावरण कॉन्फ़िगरेशन को एजेंट्स द्वारा पढ़े जाने या उजागर किए जाने से रक्षा करें। +संवेदनशील पर्यावरण कॉन्फ़िगरेशन को एजेंटों द्वारा पढ़े या उजागर होने से सुरक्षित रखता है। ### `block-env-files` -**इवेंट:** PreToolUse (Bash, Read) -**डिफ़ॉल्ट:** `.env` फ़ाइलों को `cat .env`, फ़ाइल पथ के रूप में `.env` के साथ Read टूल कॉल्स आदि के माध्यम से पढ़ने से अस्वीकार करता है। +**ईवेंट:** PreToolUse (Bash, Read) +**डिफ़ॉल्ट:** `cat .env`, Read टूल कॉल के साथ `.env` को फ़ाइल पथ के रूप में, आदि के माध्यम से `.env` फ़ाइलें पढ़ने को अस्वीकार करता है। -`.envrc` या अन्य पर्यावरण-संबंधित फ़ाइलों को ब्लॉक नहीं करता — केवल `.env` नाम की फ़ाइलों को। +`.envrc` या अन्य पर्यावरण-आसन्न फ़ाइलों को ब्लॉक नहीं करता है - केवल ठीक नाम वाली फ़ाइलें `.env` ब्लॉक करता है। कोई पैरामीटर नहीं। @@ -413,8 +412,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `protect-env-vars` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** पर्यावरण वेरिएबल्स को प्रिंट करने वाली कमांड्स को अस्वीकार करता है: `printenv`, `env`, `echo $VAR`। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** पर्यावरण चर प्रिंट करने वाली कमांडों को अस्वीकार करता है: `printenv`, `env`, `echo $VAR`। कोई पैरामीटर नहीं। @@ -422,18 +421,18 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ## फ़ाइल एक्सेस -एजेंट्स को प्रोजेक्ट सीमाओं के अंदर काम करने और संवेदनशील फ़ाइलों से दूर रखें। +एजेंटों को प्रोजेक्ट सीमाओं के भीतर काम करने और संवेदनशील फ़ाइलों से दूर रखता है। ### `block-read-outside-cwd` -**इवेंट:** PreToolUse (Read, Bash) -**डिफ़ॉल्ट:** प्रोजेक्ट रूट के बाहर फ़ाइलों को पढ़ने से अस्वीकार करता है। सीमा `CLAUDE_PROJECT_DIR` है (Claude Code द्वारा सेशन में एक बार सेट किया जाता है), जिसमें उस वेरिएबल सेट न होने पर सेशन के करंट वर्किंग डायरेक्टरी का फॉलबैक है। प्रोजेक्ट रूट का उपयोग करने से लाइव `cwd` की जगह सीमा स्थिर रहती है भले ही Claude `cd` करके किसी सबडायरेक्टरी में चला जाए। +**ईवेंट:** PreToolUse (Read, Bash) +**डिफ़ॉल्ट:** प्रोजेक्ट रूट के बाहर फ़ाइलें पढ़ने को अस्वीकार करता है। सीमा `CLAUDE_PROJECT_DIR` है (Claude Code द्वारा प्रति सत्र एक बार सेट), जब वह चर सेट न हो तो सत्र की वर्तमान कार्य निर्देशिका में फॉलबैक के साथ। live `cwd` के बजाय प्रोजेक्ट रूट का उपयोग करने का अर्थ है कि सीमा स्थिर रहती है भले ही Claude एक सबडायरेक्टरी में `cd` हो। **पैरामीटर:** -| पैरामीटर | टाइप | डिफ़ॉल्ट | विवरण | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | पूर्ण पथ प्रीफ़िक्स जो अनुमति दिए गए हैं यहाँ तक कि प्रोजेक्ट रूट के बाहर भी। | +| `allowPaths` | `string[]` | `[]` | पूर्ण पथ उपसर्ग जो अनुमत हैं भले ही प्रोजेक्ट रूट के बाहर हों। | **उदाहरण:** @@ -451,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-शैली)। | **उदाहरण:** @@ -476,18 +475,18 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ## Git -आकस्मिक पुश, फोर्स-पुश और ब्रांच गलतियों को रोकें जो कम करने में मुश्किल हों। +आकस्मिक पुश, force-push, और ब्रांच गलतियों को रोकता है जो कम करना मुश्किल हैं। ### `block-push-master` -**इवेंट:** PreToolUse (Bash) +**ईवेंट:** PreToolUse (Bash) **डिफ़ॉल्ट:** `git push origin main` और `git push origin master` को अस्वीकार करता है। **पैरामीटर:** -| पैरामीटर | टाइप | डिफ़ॉल्ट | विवरण | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | ब्रांच नाम जो सीधे पुश नहीं किए जा सकते। | +| `protectedBranches` | `string[]` | `["main", "master"]` | ब्रांच नाम जिन्हें सीधे push नहीं किया जा सकता। | **उदाहरण:** @@ -502,36 +501,36 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ``` -सभी ब्रांचेस में पुश करने की अनुमति देने के लिए (प्रभावी रूप से `enabledPolicies` से हटाए बिना इस पॉलिसी को अक्षम करने के लिए), `protectedBranches: []` सेट करें। +सभी ब्रांचों को push करने की अनुमति देने के लिए (इस नीति को `enabledPolicies` से हटाए बिना प्रभावी रूप से अक्षम करने के लिए), `protectedBranches: []` सेट करें। --- ### `block-work-on-main` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** `main` या `master` ब्रांचेस को सीधे चेक आउट करने से अस्वीकार करता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `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"]` | ब्रांच नाम जो सीधे चेक आउट नहीं किए जा सकते। | +| `protectedBranches` | `string[]` | `["main", "master"]` | ब्रांच नाम जिन पर commit/merge/rebase/cherry-pick अस्वीकार किया जाता है। | --- ### `block-force-push` -**इवेंट:** PreToolUse (Bash) +**ईवेंट:** PreToolUse (Bash) **डिफ़ॉल्ट:** `git push --force` और `git push -f` को अस्वीकार करता है। -कोई पॉलिसी-विशिष्ट पैरामीटर नहीं। विकल्पों का सुझाव देने के लिए क्रॉस-कटिंग [`hint`](/hi/configuration#hint-cross-cutting) का उपयोग करें: +कोई नीति-विशिष्ट पैरामीटर नहीं। विकल्पों का सुझाव देने के लिए क्रॉस-कटिंग [`hint`](/hi/configuration#hint-cross-cutting) का उपयोग करें: ```json { "policyParams": { "block-force-push": { - "hint": "अपने वर्तमान HEAD से एक नई ब्रांच बनाएँ (जैसे `git checkout -b `) और इसके बजाय उसे पुश करें।" + "hint": "अपने वर्तमान HEAD से एक नई ब्रांच बनाएँ (उदाहरण के लिए `git checkout -b `) और इसके बजाय उसे push करें।" } } } @@ -541,8 +540,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `warn-git-amend` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** Claude को `git commit --amend` चलाते समय सावधानी से आगे बढ़ने का निर्देश देता है। कमांड को ब्लॉक नहीं करता। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `git commit --amend` चलाते समय Claude को सावधानी से आगे बढ़ने का निर्देश देता है। कमांड को ब्लॉक नहीं करता है। कोई पैरामीटर नहीं। @@ -550,8 +549,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `warn-git-stash-drop` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** Claude को `git stash drop` चलाने से पहले पुष्टि करने का निर्देश देता है। कमांड को ब्लॉक नहीं करता। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `git stash drop` चलाने से पहले Claude को पुष्टि करने का निर्देश देता है। कमांड को ब्लॉक नहीं करता है। कोई पैरामीटर नहीं। @@ -559,8 +558,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `warn-all-files-staged` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** Claude को `git add -A` या `git add .` चलाते समय जांचने का निर्देश देता है कि वह क्या स्टेज कर रहा है। कमांड को ब्लॉक नहीं करता। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `git add -A` या `git add .` चलाते समय Claude को समीक्षा करने का निर्देश देता है कि वह क्या स्टेज कर रहा है। कमांड को ब्लॉक नहीं करता है। कोई पैरामीटर नहीं। @@ -568,12 +567,12 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ## डेटाबेस -विनाशकारी SQL ऑपरेशन्स को डेटाबेस के विरुद्ध निष्पादित होने से पहले पकड़ें। +विनाशकारी SQL ऑपरेशनों को आपके डेटाबेस के विरुद्ध निष्पादित होने से पहले पकड़ता है। ### `warn-destructive-sql` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** Claude को `DROP TABLE`, `DROP DATABASE` या `WHERE` क्लॉज़ के बिना `DELETE` युक्त SQL चलाने से पहले पुष्टि करने का निर्देश देता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `DROP TABLE`, `DROP DATABASE`, या `WHERE` क्लॉज के बिना `DELETE` युक्त SQL चलाने से पहले Claude को पुष्टि करने का निर्देश देता है। कोई पैरामीटर नहीं। @@ -581,8 +580,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `warn-schema-alteration` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** Claude को `ALTER TABLE` स्टेटमेंट्स चलाने से पहले पुष्टि करने का निर्देश देता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `ALTER TABLE` स्टेटमेंट चलाने से पहले Claude को पुष्टि करने का निर्देश देता है। कोई पैरामीटर नहीं। @@ -590,18 +589,18 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ## चेतावनियाँ -संभावित रूप से जोखिम भरी लेकिन गैर-विनाशकारी ऑपरेशन्स से पहले एजेंट्स को अतिरिक्त संदर्भ दें। +एजेंटों को संभावित रूप से जोखिम भरे लेकिन गैर-विनाशकारी ऑपरेशनों से पहले अतिरिक्त संदर्भ देता है। ### `warn-large-file-write` -**इवेंट:** PreToolUse (Write) -**डिफ़ॉल्ट:** Claude को 1024 KB से बड़ी फ़ाइलों को लिखने से पहले पुष्टि करने का निर्देश देता है। +**ईवेंट:** PreToolUse (Write) +**डिफ़ॉल्ट:** 1024 KB से बड़ी फ़ाइलें लिखने से पहले Claude को पुष्टि करने का निर्देश देता है। **पैरामीटर:** -| पैरामीटर | टाइप | डिफ़ॉल्ट | विवरण | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | किलोबाइट्स में फ़ाइल आकार थ्रेशहोल्ड जिसके ऊपर चेतावनी जारी की जाती है। | +| `thresholdKb` | `number` | `1024` | फ़ाइल आकार थ्रेशोल्ड किलोबाइट में जिसके ऊपर चेतावनी जारी की जाती है। | **उदाहरण:** @@ -616,15 +615,15 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ``` -हुक हैंडलर पेलोड्स पर 1 MB stdin सीमा लागू करता है। इस पॉलिसी को छोटे कंटेंट के साथ टेस्ट करने के लिए, `thresholdKb` को 1024 से अच्छी तरह कम वैल्यू पर सेट करें। +हुक हैंडलर पेलोड पर 1 MB stdin सीमा लागू करता है। छोटी सामग्री के साथ इस नीति का परीक्षण करने के लिए, `thresholdKb` को 1024 के नीचे एक मान पर सेट करें। --- ### `warn-package-publish` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** Claude को `npm publish` चलाने से पहले पुष्टि करने का निर्देश देता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `npm publish` चलाने से पहले Claude को पुष्टि करने का निर्देश देता है। कोई पैरामीटर नहीं। @@ -632,8 +631,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `warn-background-process` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** Claude को `nohup`, `&`, `disown` या `screen` के माध्यम से बैकग्राउंड प्रोसेस लॉन्च करते समय सावधान रहने का निर्देश देता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `nohup`, `&`, `disown`, या `screen` के माध्यम से पृष्ठभूमि प्रक्रियाएं लॉन्च करते समय Claude को सावधान रहने का निर्देश देता है। कोई पैरामीटर नहीं। @@ -641,8 +640,8 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `warn-global-package-install` -**इवेंट:** PreToolUse (Bash) -**डिफ़ॉल्ट:** Claude को `npm install -g`, `yarn global add` या वर्चुअल एनवायरनमेंट के बिना `pip install` चलाने से पहले पुष्टि करने का निर्देश देता है। +**ईवेंट:** PreToolUse (Bash) +**डिफ़ॉल्ट:** `npm install -g`, `yarn global add`, या `pip install` को वर्चुअल वातावरण के बिना चलाने से पहले Claude को पुष्टि करने का निर्देश देता है। कोई पैरामीटर नहीं। @@ -650,21 +649,21 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ## पैकेज मैनेजर -एजेंट को उपयोग करने की अनुमति दी जाने वाली पैकेज मैनेजर्स को लागू करें। +यह लागू करता है कि एजेंट को किस पैकेज मैनेजर का उपयोग करने की अनुमति है। ### `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` का उपयोग करें। **उदाहरण कॉन्फ़िगरेशन:** @@ -680,18 +679,18 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ } ``` -इस कॉन्फ़िग के साथ, `pip install flask` और `pdm install flask` दोनों अस्वीकार किए जाते हैं एक संदेश के साथ जो Claude को `uv` या `bun` का उपयोग करने के लिए कहता है। `uv pip install flask` जैसी कमांड्स अनुमति दी जाती हैं क्योंकि `uv` allowlist में है और पहले चेक किया जाता है। +इस कॉन्फ़िग के साथ, `pip install flask` और `pdm install flask` दोनों को अस्वीकार किया जाता है जिसमें एक संदेश है जो Claude को `uv` या `bun` का उपयोग करने के लिए कहता है। `uv pip install flask` जैसी कमांडें अनुमत हैं क्योंकि `uv` अनुमति सूची में है और पहले जांचा जाता है। --- ## AI व्यवहार -जब एजेंट्स फँस जाएँ या अप्रत्याशित तरीके से व्यवहार करें तो पहचानें। +पहचानता है कि जब एजेंट फंस जाते हैं या अप्रत्याशित व्यवहार करते हैं। ### `warn-repeated-tool-calls` -**इवेंट:** PreToolUse (सभी टूल्स) -**डिफ़ॉल्ट:** Claude को पुनर्विचार करने का निर्देश देता है जब एक ही टूल को 3+ बार समान पैरामीटर्स के साथ कॉल किया जाता है — एक सामान्य संकेत कि एजेंट एक लूप में फँसा है। +**ईवेंट:** PreToolUse (सभी टूल) +**डिफ़ॉल्ट:** जब एक ही टूल को समान पैरामीटर के साथ 3+ बार कॉल किया जाता है तो Claude को पुनर्विचार करने का निर्देश देता है - एजेंट के एक लूप में फंसने का एक सामान्य संकेत। कोई पैरामीटर नहीं। @@ -699,14 +698,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ## वर्कफ़्लो -एक अनुशासित सेशन के अंत वर्कफ़्लो को लागू करें। ये पॉलिसीज़ **Stop** इवेंट पर फायर करती हैं और Claude को तब तक रोकती हैं जब तक प्रत्येक शर्त पूरी न हो जाए। वे एक प्राकृतिक निर्भरता श्रृंखला का पालन करती हैं: commit → push → PR → CI। यदि कोई पॉलिसी अस्वीकार करती है, तो श्रृंखला में बाद की पॉलिसीज़ छोड़ दी जाती हैं (deny शॉर्ट-सर्किट्स)। +एक अनुशासित सत्र-अंत वर्कफ़्लो लागू करता है। ये नीतियाँ **Stop** ईवेंट पर काम करती हैं और Claude को तब तक रोकती हैं जब तक प्रत्येक शर्त पूरी न हो जाए। वे एक प्राकृतिक निर्भरता श्रृंखला का पालन करती हैं: कमिट → पुश → PR → CI। यदि एक नीति अस्वीकार करती है, तो श्रृंखला में बाद की नीतियों को छोड़ दिया जाता है (अस्वीकार शॉर्ट-सर्किट करता है)। -सभी वर्कफ़्लो पॉलिसीज़ **फेल-ओपन** हैं: यदि आवश्यक टूल उपलब्ध नहीं है (जैसे `gh` इंस्टॉल नहीं है, कोई git रिमोट नहीं), तो पॉलिसी एक सूचनात्मक संदेश के साथ अनुमति देती है कि चेक को क्यों छोड़ा गया था। +सभी वर्कफ़्लो नीतियाँ **fail-open** हैं: यदि आवश्यक टूल उपलब्ध नहीं है (उदाहरण के लिए `gh` स्थापित नहीं है, कोई git रिमोट नहीं), तो नीति एक सूचनात्मक संदेश के साथ अनुमति देती है जो समझाता है कि जांच को क्यों छोड़ दिया गया। ### `require-commit-before-stop` -**इवेंट:** Stop -**डिफ़ॉल्ट:** रुकने को अस्वीकार करता है जब अनकमिट्टेड परिवर्तन होते हैं (संशोधित, स्टेज किए गए, या अनट्रैक किए गए फ़ाइलें)। वर्किंग डायरेक्टरी स्वच्छ होने पर एक सूचनात्मक संदेश लौटाता है। +**ईवेंट:** Stop +**डिफ़ॉल्ट:** जब अप्रतिबद्ध परिवर्तन हों (संशोधित, स्टेज किए गए, या अट्रैक न किए गए फ़ाइलें) तो रुकने को अस्वीकार करता है। कार्यशील निर्देशिका स्वच्छ होने पर एक सूचनात्मक संदेश देता है। कोई पैरामीटर नहीं। @@ -714,14 +713,14 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `require-push-before-stop` -**इवेंट:** Stop -**डिफ़ॉल्ट:** रुकने को अस्वीकार करता है जब अनपुश किए गए कमिट होते हैं या जब करंट ब्रांच का कोई रिमोट ट्रैकिंग ब्रांच नहीं है। यदि आवश्यक हो तो ट्रैकिंग ब्रांच बनाने के लिए `git push -u` का सुझाव देता है। यदि कोई रिमोट कॉन्फ़िगर नहीं है तो फेल ओपन। +**ईवेंट:** Stop +**डिफ़ॉल्ट:** जब अपुष्ट कमिट हों या वर्तमान ब्रांच के पास कोई रिमोट ट्रैकिंग ब्रांच न हो तो रुकने को अस्वीकार करता है। यदि आवश्यक हो तो ट्रैकिंग ब्रांच बनाने के लिए `git push -u` का सुझाव देता है। यदि कोई रिमोट कॉन्फ़िगर न हो तो fail open होता है। **पैरामीटर:** -| पैरामीटर | टाइप | डिफ़ॉल्ट | विवरण | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | पुश करने के लिए रिमोट नाम। | +| `remote` | `string` | `"origin"` | push करने के लिए रिमोट नाम। | **उदाहरण:** @@ -739,60 +738,61 @@ failproofai 39 बिल्ट-इन पॉलिसीज़ के साथ ### `require-pr-before-stop` -**इवेंट:** Stop -**डिफ़ॉल्ट:** रुकने को अस्वीकार करता है जब करंट ब्रांच के लिए कोई पुल रिक्वेस्ट मौजूद नहीं है, या जब मौजूदा PR बिना मर्ज किए बंद है। Claude को `gh pr create` के साथ एक PR बनाने का निर्देश देता है। जब PR **मर्ज** होता है, तो पॉलिसी अनुमति देती है (काम शिप हो गया) और संदेश ब्रांच से स्विच करने का संकेत देता है (`git checkout main && git pull`)। +**ईवेंट:** Stop +**डिफ़ॉल्ट:** जब वर्तमान ब्रांच के लिए कोई pull request न हो, या जब मौजूदा PR बिना मर्ज किए बंद हो तो रुकने को अस्वीकार करता है। `gh pr create` के साथ PR बनाने का निर्देश देता है। जब PR **मर्ज** हो जाता है, तो नीति अनुमति देती है (काम भेज दिया गया है) और संदेश ब्रांच को स्विच करने का संकेत देता है (`git checkout main && git pull`)। कोई पैरामीटर नहीं। -यह पॉलिसी [GitHub CLI](https://cli.github.com/) (`gh`) को इंस्टॉल और प्रमाणित किए जाने की आवश्यकता है। -पुल रिक्वेस्ट के पढ़ने के लिए `repo` स्कोप के साथ एक व्यक्तिगत एक्सेस टोकन का उपयोग करके `gh auth login` चलाएँ। -यदि `gh` इंस्टॉल नहीं है या प्रमाणित नहीं है, तो पॉलिसी फेल ओपन करती है और कारण को Claude को रिपोर्ट करती है। +यह नीति [GitHub CLI](https://cli.github.com/) (`gh`) को स्थापित और प्रमाणित होने की आवश्यकता है। +व्यक्तिगत एक्सेस टोकन के साथ `gh auth login` चलाएँ जिसमें pull requests को पढ़ने के लिए `repo` scope हो। +यदि `gh` स्थापित नहीं है या प्रमाणित नहीं है, तो नीति fail open होती है और Claude को कारण की रिपोर्ट करती है। --- ### `require-no-conflicts-before-stop` -**इवेंट:** Stop -**डिफ़ॉल्ट:** रुकने को अस्वीकार करता है जब करंट ब्रांच बेस ब्रांच में स्वच्छ रूप से मर्ज नहीं हो सकता। पॉलिसी पहले पुष्टि करती है कि ब्रांच के लिए GitHub पर एक `OPEN` PR है — बिना इसके, कोई मर्ज लक्ष्य नहीं है जो लागू किया जाए, तो संपूर्ण पॉलिसी शॉर्ट-सर्किट करती है अनुमति देने के लिए। एक बार `OPEN` PR की पुष्टि होने के बाद, दो स्वतंत्र जांचें चलती हैं: +**ईवेंट:** Stop +**डिफ़ॉल्ट:** जब वर्तमान ब्रांच बेस ब्रांच में स्वच्छता से मर्ज न हो सके तो रुकने को अस्वीकार करता है। नीति पहले पुष्टि करती है कि ब्रांच के लिए GitHub पर एक `OPEN` PR मौजूद है — इसके बिना, मर्ज करने के लिए कोई लक्ष्य नहीं है, इसलिए पूरी नीति अनुमति देने के लिए शॉर्ट-सर्किट करती है। एक `OPEN` PR की पुष्टि होने के बाद, दो स्वतंत्र जांचें चलती हैं: -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`। conflict पर, deny संदेश conflicted फ़ाइलों का नाम देता है ताकि Claude जान सके कि क्या हल करना है। +2. **GitHub** — `gh pr view --json mergeable,state` परिणाम को पुनः उपयोग करता है जो पहले से ही precondition में लाया गया है। ऐसे conflict को पकड़ता है जिन्हें stale स्थानीय `origin/` मिस करेगा (उदाहरण के लिए किसी ने पिछली fetch के बाद `main` पर एक conflicting PR लाया)। `CONFLICTING` परिणाम अस्वीकार करता है। `UNKNOWN` परिणाम भी अस्वीकार करता है और Claude को ~10 सेकंड प्रतीक्षा करने और फिर से जांचने का निर्देश देता है इससे पहले कि वह दोबारा रुकने का प्रयास करे — यह GitHub के पुनः computation के दौरान false negatives को रोकता है। -पूरी तरह छोड़ देता है (अनुमति देता है) जब: `gh` इंस्टॉल नहीं है, ब्रांच के लिए कोई PR मौजूद नहीं है, PR की स्थिति `OPEN` नहीं है (जैसे `MERGED`, `CLOSED`), या `gh pr view` अपार्सेबल आउटपुट लौटाता है। साथ ही फेल ओपन करता है जब `origin/` स्थानीय रूप से नहीं है या जब कोई कमिट बेस से आगे नहीं हैं — वे Layer 1 फॉलथ्रू अभी भी अनुमति देने से पहले कैश्ड PR मर्जेबिलिटी से परामर्श लेते हैं। +पूरी तरह छोड़ देता है (अनुमत करता है) जब: `gh` स्थापित नहीं है, ब्रांच के लिए कोई PR नहीं है, PR की स्थिति `OPEN` नहीं है (उदाहरण के लिए `MERGED`, `CLOSED`), या `gh pr view` परिणाम parse न किए जा सकते हों। जब स्थानीय रूप से `origin/` missing हो या जब base से आगे कोई commits नहीं हों तो भी fail open होता है — वे Layer 1 fall-throughs अनुमति देने से पहले cached PR mergeability को सलाह देते हैं। **पैरामीटर:** -| पैरामीटर | टाइप | डिफ़ॉल्ट | विवरण | +| पैरामीटर | प्रकार | डिफ़ॉल्ट | विवरण | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | टकराव की जाँच के लिए बेस ब्रांच। | +| `baseBranch` | `string` | `"main"` | conflict जांचने के लिए बेस ब्रांच। | -यह पॉलिसी [GitHub CLI](https://cli.github.com/) (`gh`) को इंस्टॉल और प्रमाणित किए जाने की आवश्यकता है। पॉलिसी टकराव की जाँच चलाने से पहले ब्रांच के लिए `gh pr view` का उपयोग करके एक `OPEN` PR को पुष्टि करने के लिए करती है — `gh` के बिना, पॉलिसी अनुमति देने के लिए शॉर्ट-सर्किट करती है। पुल रिक्वेस्ट के पढ़ने के लिए `repo` स्कोप के साथ एक व्यक्तिगत एक्सेस टोकन का उपयोग करके `gh auth login` चलाएँ। +यह नीति [GitHub CLI](https://cli.github.com/) (`gh`) की आवश्यकता है। नीति किसी भी conflict जांच से चलाने से पहले एक `OPEN` PR मौजूद है यह पुष्टि करने के लिए `gh pr view` का उपयोग करता है — `gh` के बिना, नीति fail open होती है। pull requests को पढ़ने के लिए `repo` scope के साथ व्यक्तिगत एक्सेस टोकन के साथ `gh auth login` चलाएँ। --- ### `require-ci-green-before-stop` -**इवेंट:** Stop -**डिफ़ॉल्ट:** रुकने को अस्वीकार करता है जब करंट ब्रांच पर CI चेक विफल हो रहे हैं या अभी भी चल रहे हैं। GitHub Actions वर्कफ़्लो रन और तीसरे पक्ष की बॉट चेक्स दोनों को चेक करता है (जैसे CodeRabbit, SonarCloud, Codecov)। `skipped` और `cancelled` सिद्धांतों को सफलता के रूप में मानता है। सभी चेक पास होने पर एक सूचनात्मक संदेश लौटाता है। +**ईवेंट:** Stop +**डिफ़ॉल्ट:** जब CI जांच वर्तमान ब्रांच पर विफल हो रही हों या अभी भी चल रहे हों तो रुकने को अस्वीकार करता है। GitHub Actions वर्कफ़्लो रन और तीसरे पक्ष की बॉट जांचें (उदाहरण के लिए CodeRabbit, SonarCloud, Codecov) दोनों को जांचता है। `skipped` और `cancelled` निष्कर्षों को सफलता के रूप में मानता है। सभी जांचें पास होने पर एक सूचनात्मक संदेश देता है। कोई पैरामीटर नहीं। -यह पॉलिसी [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` scope के साथ व्यक्तिगत एक्सेस टोकन के साथ `gh auth login` चलाएँ। +यदि `gh` स्थापित नहीं है या प्रमाणित नहीं है, तो नीति fail open होती है और Claude को कारण की रिपोर्ट करती है। --- --- -## व्यक्तिगत पॉलिसीज़ को अक्षम करना +## व्यक्तिगत नीतियों को अक्षम करना -अपनी कॉन्फ़िगरेशन में `enabledPolicies` से एक विशिष्ट पॉलिसी को हटाएँ, या डैशबोर्ड के पॉलिसीज़ टैब में इसे बंद करें। +अपने कॉन्फ़िग में `enabledPolicies` से एक विशिष्ट नीति को हटाएँ, या इसे dashboard के Policies टैब में बंद करें। ```json { @@ -803,4 +803,4 @@ Actions वर्कफ़्लो रन और Checks API के लिए } ``` -`enabledPolicies` में सूचीबद्ध नहीं की गई पॉलिसीज़ नहीं चलती हैं, भले ही उनके लिए `policyParams` एंट्रीज़ मौजूद हों। \ No newline at end of file +`enabledPolicies` में सूचीबद्ध नहीं की गई नीतियाँ चलती नहीं हैं, भले ही उनके लिए `policyParams` प्रविष्टियाँ मौजूद हों। \ No newline at end of file diff --git a/docs/hi/configuration.mdx b/docs/hi/configuration.mdx index 16ecb805..11ec9ba4 100644 --- a/docs/hi/configuration.mdx +++ b/docs/hi/configuration.mdx @@ -1,61 +1,61 @@ --- title: कॉन्फ़िगरेशन -description: "कॉन्फ़िग फ़ाइल प्रारूप, तीन-स्कोप सिस्टम, और मर्ज नियम" +description: "कॉन्फ़िग फाइल फॉर्मेट, तीन-स्कोप सिस्टम, और मर्ज नियम" icon: gear --- -failproofai JSON कॉन्फ़िगरेशन फ़ाइलों का उपयोग करके यह नियंत्रित करता है कि कौन सी नीतियां सक्रिय हैं, वे कैसे व्यवहार करती हैं, और कस्टम नीतियां कहां से लोड की जाती हैं। कॉन्फ़िगरेशन आपकी टीम के साथ साझा करना आसान बनाने के लिए डिज़ाइन किया गया है - इसे अपने रिपॉजिटरी में कमिट करें और हर डेवलपर को एक जैसा एजेंट सेफ्टी नेट मिल जाएगा। +failproofai JSON कॉन्फ़िगरेशन फाइलों का उपयोग करता है यह नियंत्रित करने के लिए कि कौन सी नीतियां सक्रिय हैं, वे कैसे काम करती हैं, और कस्टम नीतियां कहां से लोड की जाती हैं। कॉन्फ़िगरेशन आपकी टीम के साथ साझा करना आसान बनाने के लिए डिज़ाइन किया गया है - इसे अपने रिपो में कमिट करें और हर डेवलपर को एक ही एजेंट सेफ्टी नेट मिलता है। --- ## कॉन्फ़िगरेशन स्कोप -तीन कॉन्फ़िगरेशन स्कोप हैं, जिनका मूल्यांकन प्राथमिकता क्रम में होता है: +तीन कॉन्फ़िगरेशन स्कोप हैं, प्राथमिकता के क्रम में मूल्यांकित: -| स्कोप | फ़ाइल पथ | उद्देश्य | +| स्कोप | फाइल पाथ | उद्देश्य | |-------|-----------|---------| -| **project** | `.failproofai/policies-config.json` | प्रति-रिपॉजिटरी सेटिंग्स, संस्करण नियंत्रण में कमिट की गई | -| **local** | `.failproofai/policies-config.local.json` | व्यक्तिगत प्रति-रिपॉजिटरी ओवरराइड, gitignored | -| **global** | `~/.failproofai/policies-config.json` | सभी प्रोजेक्ट्स में उपयोगकर्ता-स्तरीय डिफ़ॉल्ट | +| **project** | `.failproofai/policies-config.json` | प्रति-रिपो सेटिंग्स, संस्करण नियंत्रण में कमिट किए गए | +| **local** | `.failproofai/policies-config.local.json` | व्यक्तिगत प्रति-रिपो ओवरराइड, gitignored | +| **global** | `~/.failproofai/policies-config.json` | सभी प्रोजेक्ट्स में उपयोगकर्ता-स्तर की डिफ़ॉल्ट सेटिंग्स | -जब failproofai को हुक इवेंट मिलता है, तो यह वर्तमान कार्यशील निर्देशिका के लिए सभी तीन फ़ाइलों को लोड और मर्ज करता है। +जब failproofai को एक हुक ईवेंट प्राप्त होता है, तो यह वर्तमान कार्य निर्देशिका के लिए सभी तीन फाइलों को लोड और मर्ज करता है। ### मर्ज नियम -**`enabledPolicies`** - सभी तीन स्कोप का संघ। किसी भी स्तर पर सक्षम की गई नीति सक्रिय है। +**`enabledPolicies`** - सभी तीन स्कोप का संघ। किसी भी स्तर पर सक्षम कोई भी नीति सक्रिय है। ```text project: ["block-sudo"] 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"] } ← project जीतता है, global अनदेखा किया जाता है +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"] } ← global तक गिरता है +resolved: { allowPatterns: ["sudo systemctl status"] } ← falls through to global ``` -**`customPoliciesPath`** - इसे परिभाषित करने वाला पहला स्कोप जीत जाता है। +**`customPoliciesPath`** - पहला स्कोप जो इसे परिभाषित करता है जीता है। -**`llm`** - इसे परिभाषित करने वाला पहला स्कोप जीत जाता है। +**`llm`** - पहला स्कोप जो इसे परिभाषित करता है जीता है। --- -## कॉन्फ़िग फ़ाइल प्रारूप +## कॉन्फ़िग फाइल फॉर्मेट ```json { @@ -96,43 +96,43 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global तक गि --- -## फ़ील्ड संदर्भ +## फील्ड संदर्भ ### `enabledPolicies` प्रकार: `string[]` -सक्षम करने के लिए नीति नामों की सूची। नाम `failproofai policies` द्वारा दिखाए गए नीति पहचानकर्ताओं से बिल्कुल मेल खाने चाहिए। पूरी सूची के लिए [Built-in Policies](/hi/built-in-policies) देखें। +सक्षम करने के लिए नीति नामों की सूची। नामों को `failproofai policies` द्वारा दिखाए गए नीति पहचानकर्ताओं के साथ बिल्कुल मेल खाना चाहिए। पूरी सूची के लिए [Built-in Policies](/hi/built-in-policies) देखें। -`enabledPolicies` में न होने वाली नीतियां निष्क्रिय हैं, भले ही उनके पास `policyParams` में प्रविष्टियां हों। +`enabledPolicies` में नहीं होने वाली नीतियां निष्क्रिय हैं, भले ही उनके पास `policyParams` में प्रविष्टियां हों। ### `policyParams` प्रकार: `Record>` -प्रति-नीति पैरामीटर ओवरराइड। बाहरी कुंजी नीति का नाम है; आंतरिक कुंजियां नीति-विशिष्ट हैं। प्रत्येक नीति अपने उपलब्ध पैरामीटर को [Built-in Policies](/hi/built-in-policies) में दस्तावेज करती है। +प्रति-नीति पैरामीटर ओवरराइड। बाहरी कुंजी नीति का नाम है; आंतरिक कुंजियां नीति-विशिष्ट हैं। प्रत्येक नीति [Built-in Policies](/hi/built-in-policies) में अपने उपलब्ध पैरामीटर दस्तावेज़ित करती है। -यदि किसी नीति के पैरामीटर हैं लेकिन आप उन्हें निर्दिष्ट नहीं करते, तो नीति के निर्मित डिफ़ॉल्ट का उपयोग किया जाता है। जो उपयोगकर्ता बिल्कुल भी `policyParams` कॉन्फ़िगर नहीं करते हैं, वे पिछले संस्करणों के समान व्यवहार प्राप्त करते हैं। +यदि किसी नीति के पैरामीटर हैं लेकिन आप उन्हें निर्दिष्ट नहीं करते हैं, तो नीति की निर्मित-में डिफ़ॉल्ट का उपयोग किया जाता है। जो उपयोगकर्ता `policyParams` को बिल्कुल कॉन्फ़िगर नहीं करते हैं उन्हें पिछले संस्करणों के समान व्यवहार मिलता है। -नीति के पैरामीटर ब्लॉक के अंदर अज्ञात कुंजियां हुक-फायर समय पर चुप्पी से अनदेखी की जाती हैं लेकिन जब आप `failproofai policies` चलाते हैं तो चेतावनी के रूप में फ्लैग किए जाते हैं। +नीति के पैरामीटर ब्लॉक के अंदर अज्ञात कुंजियों को हुक-फायर समय पर चुप्पी से अनदेखा किया जाता है लेकिन जब आप `failproofai policies` चलाते हैं तो चेतावनी के रूप में झंडी लगाई जाती है। -#### `hint` (क्रॉस-कटिंग) +#### `hint` (cross-cutting) प्रकार: `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"], - "hint": "Sudo के बिना सीधे apt-get का उपयोग करें।" + "hint": "sudo के बिना सीधे apt-get का उपयोग करें।" }, "custom/my-policy": { "hint": "पहले उपयोगकर्ता से अनुमति मांगें।" @@ -141,32 +141,32 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global तक गि } ``` -जब `block-force-push` अस्वीकार करता है, तो Claude देखता है: *"Force-pushing अवरुद्ध है। इसके बजाय एक ताजी शाखा बनाने का प्रयास करें।"* +जब `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](/hi/custom-policies) देखें। +फाइल को हर हुक ईवेंट पर ताज़ा लोड किया जाता है - कोई कैशिंग नहीं है। [Custom Policies](/hi/custom-policies) लेखन विवरण के लिए देखें। -### सम्मेलन-आधारित नीतियां +### कन्वेंशन-आधारित नीतियां -स्पष्ट `customPoliciesPath` के अलावा, failproofai `.failproofai/policies/` निर्देशिकाओं से नीति फ़ाइलों को स्वचालित रूप से खोजता है और लोड करता है: +स्पष्ट `customPoliciesPath` के अतिरिक्त, failproofai स्वचालित रूप से `.failproofai/policies/` निर्देशिकाओं से नीति फाइलें खोजता है और लोड करता है: | स्तर | निर्देशिका | स्कोप | |-------|-----------|-------| | Project | `.failproofai/policies/` | संस्करण नियंत्रण के माध्यम से टीम के साथ साझा किया गया | -| User | `~/.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](/hi/custom-policies) देखें। @@ -174,7 +174,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global तक गि प्रकार: `object` (वैकल्पिक) -AI कॉल करने वाली नीतियों के लिए LLM क्लाइंट कॉन्फ़िगरेशन। अधिकांश सेटअप के लिए आवश्यक नहीं है। +AI कॉल करने वाली नीतियों के लिए LLM क्लाइंट कॉन्फ़िगरेशन। अधिकांश सेटअप्स के लिए आवश्यक नहीं है। ```json { @@ -189,36 +189,44 @@ AI कॉल करने वाली नीतियों के लिए LL ## CLI से कॉन्फ़िगरेशन प्रबंधित करना -`policies --install` और `policies --uninstall` कमांड आपके एजेंट CLI की हुक सेटिंग्स फ़ाइल (हुक एंट्री पॉइंट) में लिखते हैं, जबकि `policies-config.json` वह फ़ाइल है जिसे आप सीधे प्रबंधित करते हैं। दोनों अलग हैं: +`policies --install` और `policies --uninstall` कमांड आपके एजेंट CLI की हुक सेटिंग्स फाइल (हुक एंट्री पॉइंट) में लिखते हैं, जबकि `policies-config.json` वह फाइल है जिसे आप सीधे प्रबंधित करते हैं। दोनों अलग हैं: -- **Agent CLI सेटिंग्स** — एजेंट को प्रत्येक टूल उपयोग पर `failproofai --hook ` को कॉल करने के लिए कहता है: +- **एजेंट 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` स्कोप नहीं है। हुक प्रविष्टियां `timeoutSec` के साथ Copilot के OS-कुंजीयुक्त `bash`/`powershell` कमांड फ़ील्ड का उपयोग करती हैं; फ़ाइल शीर्ष-स्तरीय `version: 1` मार्कर रखती है। Copilot CLI समर्थन **beta** में है जब हम `events.jsonl` रिकॉर्ड स्कीमा (जो सार्वजनिक डॉक्स निर्दिष्ट नहीं करते) को अधिक वास्तविक-दुनिया सत्रों के विरुद्ध सत्यापित करते हैं। -- **`policies-config.json`** — failproofai को बताता है कि कौन सी नीतियों का मूल्यांकन करना है और किन पैरामीटर के साथ (सभी एजेंट CLI में साझा किया गया) + - **OpenAI Codex**: `~/.codex/hooks.json` (user), `/.codex/hooks.json` (project) — Codex के पास `local` स्कोप नहीं है + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (user), `/.github/hooks/failproofai.json` (project) — Copilot के पास `local` स्कोप नहीं है। हुक एंट्रीज Copilot के OS-keyed `bash`/`powershell` कमांड फील्ड्स `timeoutSec` के साथ उपयोग करती हैं; फाइल एक शीर्ष-स्तर `version: 1` मार्कर रखती है। Copilot CLI सपोर्ट **beta** है जबकि हम `events.jsonl` रिकॉर्ड स्कीमा (जिसे सार्वजनिक दस्तावेज़ निर्दिष्ट नहीं करते) को अधिक वास्तविक-दुनिया सत्रों के विरुद्ध सत्यापित करते हैं। + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — 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` (user), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (project) — OpenCode के पास `local` स्कोप नहीं है। अन्य चार CLIs के विपरीत, OpenCode के पास **कोई बाहरी-कमांड हुक सिस्टम नहीं है**: यह `opencode.json` में `plugin: []` ऐरे के माध्यम से स्पष्ट रूप से पंजीकृत in-process JS/TS प्लगइन लोड करता है (`.opencode/plugins/` से स्वचालित-खोज **नहीं** है कि opencode v1.14.33 पर प्लगइन कैसे लोड होते हैं)। इंस्टॉल एक छोटी जेनरेट की गई प्लगइन shim देता है जो failproofai बाइनरी को subprocess-कॉल करता है और बाइनरी के Claude-shape JSON प्रतिक्रिया को प्लगइन सिमेंटिक्स (`throw new Error()` for deny, `client.session.prompt(...)` for instruct, no-op for allow) में वापस अनुवाद करता है। सत्र `~/.local/share/opencode/opencode.db` में opencode के SQLite DB में रहते हैं; डैशबोर्ड का सत्र दर्शक `opencode db --format json` और `opencode export ` के माध्यम से उन्हें पढ़ता है। OpenCode सपोर्ट **beta** है जबकि हम संस्करणों में और अधिक वास्तविक-दुनिया सत्रों के विरुद्ध व्यवहार सत्यापित करते हैं। [OpenCode plugins docs](https://opencode.ai/docs/plugins/) देखें। + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `/.pi/settings.json` (project) — Pi के पास `local` स्कोप नहीं है। Pi स्टार्टअप पर TypeScript एक्सटेंशन पैकेज लोड करता है; सेटिंग्स फाइल एक फ्लैट स्ट्रिंग ऐरे `{"packages": ["./relative/path", …]}` है। failproofai एक एकल packages-array एंट्री लिखता है जो अपनी बंडल की गई `pi-extension/` निर्देशिका की ओर इशारा करता है। एक्सटेंशन आंतरिक रूप से Pi के `tool_call` / `user_bash` / `input` / `session_start` ईवेंट्स को सबस्क्राइब करता है और `failproofai --hook --cli pi` के लिए shell करता है; हैंडलर underscore_lower_snake_case → PascalCase को `PI_EVENT_MAP` के माध्यम से कैनोनिकलाइज़ करता है इसलिए मौजूदा निर्मित-में नीतियां अपरिवर्तित रहती हैं। Pi सपोर्ट **beta** है जबकि Pi का एक्सटेंशन API और सत्र-लॉग लेआउट स्थिर होते हैं। + - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (user), `/.gemini/settings.json` (project) — Gemini के पास `local` स्कोप नहीं है (यह `/etc/gemini-cli/settings.json` पर एक `system` स्कोप दस्तावेज़ित करता है जिसे failproofai expose नहीं करता है)। हुक एंट्रीज 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}` force-retry सिमेंटिक्स के लिए उत्सर्जित करता है। Gemini CLI सपोर्ट **beta** है जबकि हम वास्तविक-दुनिया कवरेज चौड़ा करते हैं। [Gemini CLI hooks docs](https://geminicli.com/docs/hooks/) देखें। +- **`policies-config.json`** — failproofai को बताता है कि कौन सी नीतियों का मूल्यांकन करना है और किस पैरामीटर के साथ (सभी एजेंट CLIs में साझा किया गया) -एक विशिष्ट एजेंट को लक्ष्य करने के लिए `--cli claude|codex|copilot` पास करें (स्पेस-अलग या किसी भी उपसमुच्चय के लिए दोहराया): +`--cli claude|codex|copilot|cursor|opencode|pi|gemini` को किसी विशिष्ट एजेंट को लक्ष्य करने के लिए पास करें (स्पेस-सेपरेटेड या किसी सबसेट के लिए दोहराए गए): ```bash failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project -failproofai policies --install --cli claude codex copilot +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 claude codex copilot cursor opencode pi gemini ``` -जब `--cli` छोड़ा जाता है, तो `failproofai` यह पता लगाता है कि कौन से एजेंट CLI स्थापित हैं (`which claude` / `which codex` / `which copilot`): +जब `--cli` छोड़ा जाता है, `failproofai` पता लगाता है कि कौन से एजेंट CLIs इंस्टॉल किए गए हैं (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): -- **एक CLI का पता चला** — बिना प्रॉम्प्ट के उस CLI को स्वचालित रूप से चुनता है। -- **एक इंटरेक्टिव टर्मिनल में कई CLI का पता चला** — एक तीर-कुंजी एकल-चयन प्रॉम्प्ट दिखाता है: जब दो CLI मौजूद हैं तो विकल्प `Both`, ` only`, ` only` हैं; तीन CLI के साथ पहला विकल्प `All` बन जाता है (↑↓ चलने के लिए, Enter चुनने के लिए, ^C छोड़ने के लिए)। -- **एक गैर-इंटरेक्टिव रन में कई CLI का पता चला** (CI, no TTY) — बिना प्रॉम्प्ट के सभी पता चले CLI के लिए स्थापित करता है। -- **कोई नहीं पता चला** — `claude` में वापस गिरता है, एक चेतावनी के साथ कि PATH में कोई एजेंट बाइनरी नहीं मिली; हुक कमांड अभी भी लिखा जाता है इसलिए यह सक्रिय हो जाता है जैसे ही आप एक स्थापित करते हैं। +- **एक CLI पता चला** — बिना प्रॉम्प्ट के उस CLI को स्वचालित रूप से चुनता है। +- **इंटरैक्टिव टर्मिनल में कई CLIs पता चले** — एक तीर-कुंजी सिंगल-चयन प्रॉम्प्ट दिखाता है जो एक `Detected (N)` सेक्शन में समूहबद्ध है (एक `Install for all N detected` एकत्रित पंक्ति + प्रत्येक पता चला CLI व्यक्तिगत रूप से) और एक `Not installed (M) · install hooks ahead of time` सेक्शन सभी अपता चले समर्थित CLIs को एक फॉर्वर्ड-इंस्टॉल विकल्प के रूप में सूचीबद्ध करता है (↑↓ को स्थानांतरित करने के लिए, Enter चयन के लिए, ^C छोड़ने के लिए)। अनइंस्टॉल फ्लो केवल Detected सेक्शन दिखाता है। +- **कई CLIs पता चले** एक गैर-इंटरैक्टिव रन में (CI, कोई TTY नहीं) — बिना प्रॉम्प्ट के सभी पता चले CLIs के लिए इंस्टॉल करता है। +- **कोई भी नहीं पता चला** — `claude` में वापस गिर जाता है, एक चेतावनी के साथ कि PATH में कोई एजेंट बाइनरी नहीं मिला; हुक कमांड अभी भी लिखा जाता है इसलिए यह सक्रिय होता है जैसे ही आप एक इंस्टॉल करते हैं। -आप कभी भी `policies-config.json` को सीधे संपादित कर सकते हैं; परिवर्तन तुरंत अगले हुक इवेंट पर प्रभावी हो जाते हैं, पुनरारंभ की आवश्यकता नहीं। +आप किसी भी समय `policies-config.json` को सीधे संपादित कर सकते हैं; परिवर्तन अगली हुक ईवेंट पर बिना पुनः प्रारंभ किए तुरंत प्रभावी होते हैं। --- -## उदाहरण: टीम डिफ़ॉल्ट के साथ प्रोजेक्ट-स्तरीय कॉन्फ़िगरेशन +## उदाहरण: टीम डिफ़ॉल्ट के साथ प्रोजेक्ट-स्तर कॉन्फ़िगरेशन -`.failproofai/policies-config.json` को अपने रिपॉजिटरी में कमिट करें: +`.failproofai/policies-config.json` को अपने रिपो में कमिट करें: ```json { @@ -237,4 +245,4 @@ failproofai policies --install --cli claude codex copilot } ``` -प्रत्येक डेवलपर फिर व्यक्तिगत ओवरराइड के लिए `.failproofai/policies-config.local.json` (gitignored) बना सकता है, साथियों को प्रभावित किए बिना। \ No newline at end of file +प्रत्येक डेवलपर तब `.failproofai/policies-config.local.json` (gitignored) बना सकता है व्यक्तिगत ओवरराइड के लिए बिना सहकर्मियों को प्रभावित किए। \ No newline at end of file diff --git a/docs/hi/dashboard.mdx b/docs/hi/dashboard.mdx index f804be07..cdb0997e 100644 --- a/docs/hi/dashboard.mdx +++ b/docs/hi/dashboard.mdx @@ -1,10 +1,10 @@ --- -title: डैशबोर्ड +title: Dashboard description: "एजेंट सेशन की निगरानी करें, टूल कॉल की समीक्षा करें, और नीतियों का प्रबंधन करें" icon: chart-line --- -failproofai डैशबोर्ड आपके AI एजेंट सेशन की निगरानी और नीतियों के प्रबंधन के लिए एक स्थानीय वेब एप्लिकेशन है। देखें कि आपके एजेंट आपके दूर रहने के दौरान क्या करते थे। +failproofai डैशबोर्ड आपके AI एजेंट सेशन की निगरानी और नीतियों के प्रबंधन के लिए एक स्थानीय वेब एप्लिकेशन है। देखें कि आपके एजेंट आपकी अनुपस्थिति में क्या करते थे। --- @@ -16,7 +16,7 @@ failproofai `http://localhost:8020` पर खुलता है। -डैशबोर्ड सीधे फाइल सिस्टम से पढ़ता है - आपके Claude Code प्रोजेक्ट फ़ोल्डर और failproofai कॉन्फ़िग फाइलें। कुछ भी किसी रिमोट सेवा में नहीं लिखा जाता है। +डैशबोर्ड फाइलसिस्टम से सीधे पढ़ता है - आपकी Claude Code प्रोजेक्ट फोल्डर और failproofai कॉन्फ़िग फाइलें। किसी दूरस्थ सेवा में कुछ भी नहीं लिखा जाता है। --- @@ -24,38 +24,38 @@ failproofai ### प्रोजेक्ट्स -आपकी मशीन पर मिले सभी Claude Code, OpenAI Codex, और GitHub Copilot CLI _(beta)_ प्रोजेक्ट्स को सूचीबद्ध करता है। Claude प्रोजेक्ट्स `~/.claude/projects/` से खोजे जाते हैं (या `CLAUDE_PROJECTS_PATH` द्वारा सेट पाथ); Codex प्रोजेक्ट्स `~/.codex/sessions///
/*.jsonl` के तहत प्रत्येक ट्रांसक्रिप्ट स्कैन करके और प्रत्येक सेशन के पहले रिकॉर्ड में दर्ज `cwd` द्वारा समूहीकृत करके खोजे जाते हैं; Copilot CLI प्रोजेक्ट्स प्रत्येक `~/.copilot/session-state//workspace.yaml` स्कैन करके खोजे जाते हैं (`COPILOT_HOME` के माध्यम से कॉन्फ़िगर योग्य) और इसके `cwd` फील्ड द्वारा समूहीकृत होते हैं। एक प्रोजेक्ट जो कई CLIs द्वारा उपयोग किया गया है, सभी मेल खाने वाले बैज के साथ एक पंक्ति के रूप में प्रदर्शित होता है। तालिका के ऊपर **CLI** ड्रॉपडाउन का उपयोग करके किसी विशिष्ट एजेंट CLI द्वारा फ़िल्टर करें; URL आपके चयन को `?cli=claude|codex|copilot` के रूप में संरक्षित करता है। +आपकी मशीन पर पाई गई सभी 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/` फॉलबैक के रूप में जांचे जाते हैं) `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` टेक्स्ट मार्कर से canonical cwd को पुनः प्राप्त करके खोजे जाते हैं। एक प्रोजेक्ट जो कई CLIs द्वारा उपयोग किया गया है, सभी मेलिंग बैज के साथ एक पंक्ति के रूप में प्रदर्शित होता है। एक विशिष्ट एजेंट CLI द्वारा फ़िल्टर करने के लिए टेबल के ऊपर **CLI** ड्रॉपडाउन का उपयोग करें; URL आपकी चयन को `?cli=claude|codex|copilot|cursor|opencode|pi|gemini` के रूप में संरक्षित करता है। प्रत्येक प्रोजेक्ट दिखाता है: -- प्रोजेक्ट का नाम (फ़ोल्डर पाथ से निकाला गया) -- एक CLI बैज — `Claude Code` (नारंगी), `OpenAI Codex` (बैंगनी), और/या `GitHub Copilot` (नीला) +- प्रोजेक्ट का नाम (फोल्डर पाथ से प्राप्त) +- एक CLI बैज — `Claude Code` (नारंगी), `OpenAI Codex` (बैंगनी), `GitHub Copilot` (नीला), `Cursor Agent` (पन्ना), `OpenCode` (एम्बर), `Pi` (गुलाबी), और/या `Gemini CLI` (आकाश) - सबसे हाल की सेशन गतिविधि की तारीख -किसी प्रोजेक्ट को देखने के लिए क्लिक करें और इसके सेशन देखें। +इसकी सेशन देखने के लिए एक प्रोजेक्ट पर क्लिक करें। ### सेशन्स -किसी प्रोजेक्ट के भीतर सभी सेशन को सूचीबद्ध करता है। प्रत्येक सेशन दिखाता है: +एक प्रोजेक्ट के भीतर सभी सेशन की सूची बनाता है। प्रत्येक सेशन दिखाता है: - सेशन ID -- शुरुआत और समाप्त समय +- शुरुआत और अंत समय - टूल कॉल की संख्या - हुक गतिविधि गणना (नीतियां जो सक्रिय हुईं) -सूची को संकीर्ण करने के लिए दिनांश श्रेणी फ़िल्टर और सेशन ID खोज का उपयोग करें। सेशन पृष्ठांकित हैं। +सूची को संकुचित करने के लिए दिनांक श्रेणी फ़िल्टर और सेशन ID खोज का उपयोग करें। सेशन पेजीनेटेड हैं। -सेशन दर्शक को खोलने के लिए किसी सेशन को क्लिक करें। +सेशन दर्शक खोलने के लिए एक सेशन पर क्लिक करें। ### सेशन दर्शक -सेशन दर्शक स्वायत्त एजेंट के लिए महत्वपूर्ण प्रश्न का उत्तर देता है: एजेंट ने क्या किया, और क्या यह ट्रैक पर रहा? हेडर के बगल में एक CLI बैज यह संकेत देता है कि सेशन Claude Code या OpenAI Codex ट्रांसक्रिप्ट है या नहीं। यह सेशन में हुई हर चीज की एक समयरेखा दिखाता है: +सेशन दर्शक स्वायत्त एजेंटों के लिए मुख्य प्रश्न का उत्तर देता है: एजेंट ने क्या किया, और क्या यह ट्रैक पर रहा? हेडर के बगल में एक CLI बैज यह इंगित करता है कि सेशन Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, या Gemini CLI ट्रांसक्रिप्ट है। यह सेशन में होने वाली सभी चीजों की एक समयरेखा दिखाता है: -- **संदेश** - Claude के पाठ प्रतिक्रियाएं और उपयोगकर्ता संकेत -- **टूल कॉल्स** - हर टूल जो Claude ने आमंत्रित किया, इसके इनपुट और आउटपुट के साथ -- **नीति गतिविधि** - प्रत्येक टूल कॉल के लिए, कौन सी नीतियां सक्रिय हुईं और उन्होंने क्या निर्णय लौटाया +- **संदेश** - Claude के पाठ प्रतिक्रियाएं और उपयोगकर्ता प्रॉम्प्ट +- **टूल कॉल्स** - Claude द्वारा आमंत्रित प्रत्येक टूल, इसके इनपुट और आउटपुट के साथ +- **नीति गतिविधि** - प्रत्येक टूल कॉल के लिए, कौन सी नीतियां सक्रिय हुईं और वे किस निर्णय पर पहुंचीं -शीर्ष पर आंकड़े बार सेशन की अवधि, कुल टूल कॉल, और हुक निर्णयों का सारांश (allow / deny / instruct गणना) दिखाता है। +शीर्ष पर सांख्यिकी पट्टी सेशन अवधि, कुल टूल कॉल, और हुक निर्णयों (allow / deny / instruct गणना) का सारांश दिखाता है। -आप डाउनलोड बटन का उपयोग करके सेशन को ZIP या JSONL फाइल के रूप में निर्यात कर सकते हैं। +सेशन निर्यात करने के लिए **Download Logs** बटन पर क्लिक करें। Claude Code, Codex, Copilot, Cursor, Pi, और Gemini सेशन के लिए आप मूल ऑन-डिस्क JSONL ट्रांसक्रिप्ट बाइट-फॉर-बाइट प्राप्त करते हैं; OpenCode (जिसके सेशन डिस्क पर नहीं बल्कि SQLite में रहते हैं) के लिए आप एक JSON दस्तावेज़ प्राप्त करते हैं जो अंतर्निहित `session` / `messages` / `parts` टेबल को प्रतिबिंबित करता है। ### नीतियां @@ -63,30 +63,30 @@ failproofai - - एक क्लिक के साथ अलग-अलग नीतियों को चालू या बंद करें (`~/.failproofai/policies-config.json` में लिखता है) - - किसी नीति को उसके मापदंडों को कॉन्फ़िगर करने के लिए विस्तारित करें (उन नीतियों के लिए जो `policyParams` का समर्थन करती हैं) - - किसी दिए गए स्कोप के लिए हुक स्थापित या निकालें - - एक कस्टम नीति फाइल पाथ सेट करें + - एक क्लिक से अलग-अलग नीतियों को चालू या बंद करें (`~/.failproofai/policies-config.json` में लिखता है) + - किसी नीति को उसके पैरामीटर को कॉन्फ़िगर करने के लिए विस्तारित करें (जो नीतियां `policyParams` का समर्थन करती हैं) + - किसी दिए गए स्कोप के लिए हुक स्थापित या हटाएं + - एक कस्टम नीतियों फाइल पाथ सेट करें - - सभी सेशन में सभी हुक ईवेंट का पूर्ण पृष्ठांकित इतिहास जो सक्रिय हुए हैं - - निर्णय, ईवेंट प्रकार, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_), नीति का नाम, या सेशन ID द्वारा फ़िल्टर करें - - प्रत्येक पंक्ति दिखाती है: समय, नीति का नाम, निर्णय, CLI बैज (नारंगी = Claude Code, बैंगनी = OpenAI Codex, नीला = GitHub Copilot), टूल का नाम, सेशन ID, और deny/instruct निर्णयों का कारण - - सेशन ID पर क्लिक करके इसके ट्रांसक्रिप्ट को खोलें — दर्शक स्वचालित रूप से पता लगाता है कि कौन सा CLI हुक को सक्रिय करता है (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`) और हेडर में मेल खाने वाले CLI बैज को प्रदर्शित करता है + - सभी सेशन में फायर हुए प्रत्येक हुक ईवेंट का पूर्ण पेजीनेटेड इतिहास + - निर्णय, ईवेंट प्रकार, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Gemini CLI _(beta)_), नीति नाम, या सेशन 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 बैज प्रदर्शित करता है --- -## स्वचालित रीफ्रेश +## स्वतः-रीफ्रेश -डैशबोर्ड के शीर्ष नेविगेशन में एक स्वचालित रीफ्रेश टॉगल है। सक्षम होने पर, वर्तमान पृष्ठ नए सेशन और नीति गतिविधि दिखाने के लिए नियमित रूप से ताज़ा होता है क्योंकि वे दिखाई देते हैं। लंबे समय तक चलने वाले स्वायत्त एजेंट सेशन की निगरानी के लिए आवश्यक है। +डैशबोर्ड में शीर्ष नेविगेशन में एक स्वतः-रीफ्रेश टॉगल है। जब सक्षम होता है, तो वर्तमान पृष्ठ समय-समय पर नई सेशन और नीति गतिविधि दिखाने के लिए रीफ्रेश होता है क्योंकि वे दिखाई देते हैं। लंबे समय तक चलने वाली स्वायत्त एजेंट सेशन की निगरानी के लिए आवश्यक। --- ## पृष्ठों को अक्षम करना -यदि आपको डैशबोर्ड के केवल कुछ भाग की आवश्यकता है, तो `FAILPROOFAI_DISABLE_PAGES` को पृष्ठ नामों की अल्पविराम से अलग की गई सूची पर सेट करें: +यदि आपको केवल डैशबोर्ड के कुछ हिस्सों की आवश्यकता है, तो `FAILPROOFAI_DISABLE_PAGES` को पृष्ठ नामों की एक अल्पविरामित सूची में सेट करें: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -98,11 +98,11 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## थीम -डैशबोर्ड हल्के और गहरे मोड का समर्थन करता है। नेविगेशन बार में बटन के माध्यम से टॉगल करें। वरीयता आपके ब्राउज़र के स्थानीय संग्रहण में संग्रहीत है। +डैशबोर्ड हल्के और गहरे मोड का समर्थन करता है। नेविगेशन बार में बटन के माध्यम से टॉगल करें। प्राथमिकता आपके ब्राउज़र के स्थानीय स्टोरेज में संग्रहीत है। --- -## प्रोजेक्ट्स पाथ कॉन्फ़िगर करना +## प्रोजेक्ट्स पाथ को कॉन्फ़िगर करना डिफ़ॉल्ट रूप से, डैशबोर्ड मानक Claude Code प्रोजेक्ट्स निर्देशिका से पढ़ता है। कस्टम सेटअप के लिए इसे ओवरराइड करें: @@ -114,30 +114,30 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## गैर-localhost होस्ट से एक्सेस करना -जब डैशबोर्ड को **dev मोड** (`npm run dev`) में चलाते हैं और इसे `localhost` के अलावा किसी होस्टनाम से एक्सेस करते हैं - उदाहरण के लिए, एक कस्टम डोमेन, एक रिमोट IP, या एक टनल किया गया URL - आप यह चेतावनी देख सकते हैं: +जब डैशबोर्ड को **dev मोड** में चलाते हैं (`npm run dev`) और `localhost` के अलावा किसी होस्टनाम से एक्सेस करते हैं - उदाहरण के लिए, एक कस्टम डोमेन, एक दूरस्थ IP, या एक tunneled URL - आप एक चेतावनी देख सकते हैं: ```text -⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". +⚠ "dashboard.example.com" से Next.js dev संसाधन /_next/webpack-hmr के लिए अवरोधित क्रॉस-ऑरिजिन अनुरोध। ``` -यह Next.js अपने HMR (हॉट मॉड्यूल रीलोड) वेबसॉकेट तक cross-origin एक्सेस को ब्लॉक कर रहा है, जो कि एक dev-only सुविधा है। अपने होस्ट को अनुमति देने के लिए `--allowed-origins` फ़्लैग का उपयोग करें: +यह Next.js अपने HMR (hot module reload) websocket को क्रॉस-ऑरिजिन एक्सेस से अवरोधित कर रहा है, जो एक dev-only फीचर है। अपने होस्ट को अनुमति देने के लिए, `--allowed-origins` फ्लैग का उपयोग करें: ```bash npm run dev -- --allowed-origins dashboard.example.com ``` -कई होस्ट या 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 मोड पर लागू होता है। जब `failproofai` (production मोड) चलाते हैं, तो कोई HMR वेबसॉकेट नहीं होता है और कोई cross-origin dev संसाधन समस्या नहीं होती है। +यह केवल dev मोड पर लागू होता है। जब `failproofai` (production मोड) चलाते हैं, तो कोई HMR websocket और कोई क्रॉस-ऑरिजिन dev संसाधन समस्या नहीं होती है। \ No newline at end of file diff --git a/docs/hi/getting-started.mdx b/docs/hi/getting-started.mdx index 78f46815..fa270265 100644 --- a/docs/hi/getting-started.mdx +++ b/docs/hi/getting-started.mdx @@ -1,13 +1,13 @@ --- -title: शुरुआत करें -description: "failproofai को इंस्टॉल करें, policies को सक्षम करें, और अपने agents को विश्वसनीय तरीके से चलाएं" +title: शुरुआत करना +description: "failproofai इंस्टॉल करें, policies को सक्षम करें, और अपने agents को विश्वसनीय रूप से चलाएं" icon: rocket --- ## आवश्यकताएं - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (वैकल्पिक - केवल source से build करने के लिए आवश्यक) +- **Bun** >= 1.3.0 (वैकल्पिक - केवल स्रोत से बनाने के लिए आवश्यक) --- @@ -31,20 +31,24 @@ bun add -g failproofai - Policies ऐसे नियम हैं जो हर agent tool call से पहले और बाद में चलते हैं। ये विनाशकारी commands, secret leakage, और अन्य विफलता के तरीकों को नुकसान पहुंचाने से पहले पकड़ते हैं। + Policies नियम हैं जो हर agent tool call से पहले और बाद में चलते हैं। वे विनाशकारी commands, secret leakage, और अन्य विफलता के तरीकों को नुकसान पहुंचाने से पहले पकड़ते हैं। ```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`)। जब एक से अधिक मौजूद हों तो आपको prompt दिया जाएगा; prompt को छोड़ने के लिए `--cli claude codex copilot` (किसी भी subset) को pass करें। + यह आपके स्थापित 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 के `~/.config/opencode/plugins/failproofai.mjs` पर generated plugin shim और `~/.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) पास करें। - GitHub Copilot CLI support **beta** में है — `--cli copilot` के साथ इंस्टॉल करें। + GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, और Gemini CLI समर्थन **beta** है — `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, या `--cli gemini` के साथ इंस्टॉल करें। ```bash failproofai policies --install --scope project failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project + 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 block-sudo block-rm-rf sanitize-api-keys ``` @@ -53,30 +57,30 @@ bun add -g failproofai failproofai policies ``` - हर policy को दिखाता है, कि वह enabled है या नहीं, और कोई भी configured parameters। + हर policy को दिखाता है, चाहे वह सक्षम है या नहीं, और कोई भी कॉन्फ़िगर किए गए parameters। ```bash failproofai ``` - `http://localhost:8020` पर एक local dashboard खोलता है जहां आप sessions browse कर सकते हैं, tool calls inspect कर सकते हैं, और policies manage कर सकते हैं। + `http://localhost:8020` पर एक स्थानीय dashboard खोलता है जहां आप sessions को browse कर सकते हैं, tool calls का निरीक्षण कर सकते हैं, और policies को प्रबंधित कर सकते हैं। - - Claude Code को सामान्य रूप से शुरू करें। अगर agent कुछ जोखिम भरा करने का प्रयास करे तो failproofai स्वचालित रूप से इसे रोक देता है। इसे unattended चलाएं और dashboard में देखें कि क्या हुआ। + + Claude Code को सामान्य रूप से शुरू करें। यदि agent कुछ जोखिम भरा करने की कोशिश करता है, तो failproofai इसे स्वचालित रूप से रोक देता है। इसे unattended चलने दें और dashboard में देखें कि क्या हुआ। --- -## Policies कैसे काम करती हैं +## Policies कैसे काम करते हैं -हर बार जब एक agent एक tool चलाता है, Claude Code failproofai को एक subprocess के रूप में कॉल करता है: +हर बार जब कोई agent tool चलाता है, Claude Code failproofai को एक subprocess के रूप में कॉल करता है: ```text -Claude Code → failproofai --hook PreToolUse → stdin JSON को पढ़ता है +Claude Code → failproofai --hook PreToolUse → stdin JSON पढ़ता है policies का मूल्यांकन करता है - निर्णय को stdout में लिखता है + stdout को निर्णय लिखता है ``` प्रत्येक policy तीन निर्णयों में से एक देता है: @@ -86,14 +90,14 @@ Claude Code → failproofai --hook PreToolUse → stdin JSON को पढ - **instruct** - agent के prompt में अतिरिक्त context जोड़ा जाता है -Policies आपकी local process में चलती हैं। कुछ भी किसी remote service को नहीं भेजा जाता है। +Policies आपकी स्थानीय process में चलते हैं। कुछ भी दूरस्थ service को नहीं भेजा जाता है। --- -## Convention-based policies के साथ team policies सेट अप करें +## Convention-based policies के साथ team policies सेट करें -आपकी team में quality standards स्थापित करने का सबसे तेज़ तरीका `.failproofai/policies/` convention है। इस directory में policy files को drop करें और वे स्वचालित रूप से load हो जाते हैं — कोई flags, config changes, या install commands नहीं। +अपनी team में गुणवत्ता मानकों को स्थापित करने का सबसे तेज़ तरीका `.failproofai/policies/` convention है। इस directory में policy files को drop करें और वे स्वचालित रूप से load हो जाते हैं — कोई flags नहीं, कोई config changes नहीं, कोई install commands नहीं। @@ -102,13 +106,13 @@ Policies आपकी local process में चलती हैं। कु ``` - Starter examples को copy करें या अपना खुद का लिखें: + Starter examples की प्रतिलिपि बनाएं या अपने स्वयं के लिखें: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ ``` - या एक नया बनाएं: + या एक नई बनाएं: ```js // .failproofai/policies/team-policies.mjs @@ -120,7 +124,7 @@ Policies आपकी local process में चलती हैं। कु 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("Commit करने से पहले tests चलाएं।"); } return allow(); }, @@ -130,24 +134,24 @@ Policies आपकी local process में चलती हैं। कु ```bash git add .failproofai/policies/ - git commit -m "Add team quality policies" + git commit -m "Team की गुणवत्ता policies जोड़ें" ``` - हर team member जिसके पास failproofai installed है ये policies automatically pick up करता है। कोई per-developer setup की आवश्यकता नहीं है। + हर team member जिसके पास failproofai इंस्टॉल है, ये policies स्वचालित रूप से प्राप्त करता है। कोई per-developer setup की आवश्यकता नहीं है। -अपनी repo में `.failproofai/policies/` को commit करें ताकि पूरी team एक जैसे standards share करे। जब आपकी team को नए failure modes खोजें, policies जोड़ें और push करें — सभी को अपने अगले `git pull` पर update मिलेगा। समय के साथ ये policies एक living quality standard बन जाती हैं जो लगातार improve होते रहते हैं। +`.failproofai/policies/` को अपने repo में commit करें ताकि पूरी team समान मानकों को साझा करे। जब आपकी team नए failure modes की खोज करे, policies को जोड़ें और push करें — सभी को अपने अगले `git pull` पर update मिल जाता है। समय के साथ ये policies एक जीवंत गुणवत्ता मानक बन जाते हैं जो लगातार सुधरता है। --- -## डेटा स्टोरेज +## डेटा storage -सभी configuration और logs आपकी machine पर रहते हैं: +सभी कॉन्फ़िगरेशन और logs आपकी machine पर रहते हैं: -| Path | यह क्या store करता है | +| Path | यह क्या stores करता है | |------|----------------| | `~/.failproofai/policies-config.json` | Global policy config | | `~/.failproofai/hook-activity.jsonl` | Hook execution history | @@ -163,7 +167,7 @@ Policies आपकी local process में चलती हैं। कु failproofai policies --uninstall ``` -`~/.claude/settings.json` से hook entries को remove करता है। `~/.failproofai/` में config files को रखा जाता है। +`~/.claude/settings.json` से hook entries को हटाता है। `~/.failproofai/` में config files को रखा जाता है। --- @@ -176,15 +180,15 @@ failproofai policies --uninstall - सभी 26 policies parameters के साथ + सभी 26 policies और parameters - JavaScript में अपनी खुद की policies लिखें + JavaScript में अपनी स्वयं की policies लिखें - Sessions को monitor करें और policy activity की review करें + Sessions की निगरानी करें और policy activity की समीक्षा करें \ No newline at end of file diff --git a/docs/i18n/README.ar.md b/docs/i18n/README.ar.md index 31b00b0b..442bf0e3 100644 --- a/docs/i18n/README.ar.md +++ b/docs/i18n/README.ar.md @@ -25,13 +25,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**، **OpenAI Codex**، **GitHub Copilot CLI** _(beta)_ و **Agents SDK**. +الطريقة الأسهل لإدارة السياسات التي تحافظ على موثوقية وكلاء الذكاء الاصطناعي والبقاء على المسار الصحيح والتشغيل المستقل - لـ **Claude Code**، **OpenAI Codex**، **GitHub Copilot CLI** _(بيتا)_، **Cursor Agent** _(بيتا)_، **OpenCode** _(بيتا)_، **Pi** _(بيتا)_، **Gemini CLI** _(بيتا)_ و **Agents SDK**.

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

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

@@ -52,17 +52,44 @@        - + المزيد قريباً + + + + Cursor Agent + + +

+

+ + + + OpenCode + + +        + + + + Pi + + +        + + + + Gemini CLI + +

-> قم بتثبيت الـ hooks لأحد أو اثنين أو جميعهم: `failproofai policies --install --cli copilot` (أو `--cli claude codex copilot`). تجاهل `--cli` للكشف التلقائي عن واجهات سطر الأوامر المثبتة والفحص. **دعم GitHub Copilot CLI قيد الإصدار التجريبي.** +> تثبيت الخطافات لواحد أو أي مزيج: `failproofai policies --install --cli opencode pi gemini` (أو `--cli claude codex copilot cursor opencode pi gemini`). احذف `--cli` للكشف التلقائي عن واجهات سطر الأوامر المثبتة والمطالبة. **دعم GitHub Copilot CLI و Cursor Agent و OpenCode و Pi و Gemini CLI في مرحلة بيتا — الاختبار جارٍ.** -- **39 سياسة مدمجة** - تجنب حالات الفشل الشائعة للوكلاء خارج الصندوق. احجب الأوامر المدمرة، منع تسريب الأسرار، احتفظ بالوكلاء داخل حدود المشروع، اكتشف الحلقات، والمزيد. -- **سياسات مخصصة** - اكتب قواعد موثوقيتك الخاصة في JavaScript. استخدم `allow`/`deny`/`instruct` API لفرض المعايير، منع الانجراف، تقييد العمليات، أو الدمج مع الأنظمة الخارجية. -- **تكوين سهل** - اضبط أي سياسة بدون كتابة الأكواد. قم بتعيين قوائم السماح والفروع المحمية والحدود لكل مشروع أو عام. يتم دمج تكوين ثلاث نطاقات تلقائياً. -- **شاشة عرض الوكيل** - اطلع على ما فعله وكلاؤك أثناء غيابك. استعرض الجلسات، افحص كل استدعاء أداة، واستعرض بالضبط المكان الذي تم فيه تفعيل السياسات. +- **39 سياسة مدمجة** - اكتشف أنماط فشل الوكيل الشائعة خارج الصندوق. احجب الأوامر المدمرة، منع تسرب الأسرار، احتفظ بالوكلاء داخل حدود المشروع، اكتشف الحلقات، والمزيد. +- **سياسات مخصصة** - اكتب قواعد الموثوقية الخاصة بك في JavaScript. استخدم واجهة برمجية `allow`/`deny`/`instruct` لفرض الاتفاقيات، منع الانجراف، تقييد العمليات، أو التكامل مع الأنظمة الخارجية. +- **إعدادات سهلة** - اضبط أي سياسة دون كتابة أكواد. عيّن قوائم السماح والفروع المحمية والحدود القصوى لكل مشروع أو عالمياً. يتم دمج إعدادات ثلاث نطاقات تلقائياً. +- **مراقب الوكيل** - اطلع على ما فعله وكلاؤك أثناء غيابك. تصفح الجلسات، فتش كل استدعاء أداة، وراجع بالضبط حيث تم تشغيل السياسات. -كل شيء يعمل محلياً - لا تترك البيانات جهازك. +كل شيء يعمل محلياً - لا تترك أي بيانات آلتك. --- @@ -91,15 +118,15 @@ bun add -g failproofai failproofai policies --install ``` -يكتب إدخالات hook في `~/.claude/settings.json`. سيستدعي Claude Code الآن failproofai قبل وبعد كل استدعاء أداة. +يكتب إدخالات الخطاف في `~/.claude/settings.json`. الآن سيستدعي Claude Code failproofai قبل وبعد كل استدعاء أداة. -### 2. قم بتشغيل لوحة التحكم +### 2. تشغيل لوحة التحكم ```bash failproofai ``` -يفتح `http://localhost:8020` - استعرض الجلسات، افحص السجلات، أدر السياسات. +يفتح `http://localhost:8020` - تصفح الجلسات، فتش السجلات، أدِر السياسات. ### 3. تحقق مما هو نشط @@ -114,7 +141,7 @@ failproofai policies ### النطاقات | النطاق | الأمر | حيث يكتب | -|-------|-------|---------| +|-------|---------|---------| | عام (افتراضي) | `failproofai policies --install` | `~/.claude/settings.json` | | المشروع | `failproofai policies --install --scope project` | `.claude/settings.json` | | محلي | `failproofai policies --install --scope local` | `.claude/settings.local.json` | @@ -135,9 +162,9 @@ failproofai policies --uninstall --scope project --- -## التكوين +## الإعدادات -يتم حفظ تكوين السياسة في `~/.failproofai/policies-config.json` (عام) أو `.failproofai/policies-config.json` في مشروعك (لكل مشروع). +تعيش إعدادات السياسة في `~/.failproofai/policies-config.json` (عام) أو `.failproofai/policies-config.json` في مشروعك (لكل مشروع). ```json { @@ -152,15 +179,15 @@ failproofai policies --uninstall --scope project "policyParams": { "block-sudo": { "allowPatterns": ["sudo systemctl status", "sudo journalctl"], - "hint": "Use apt-get directly without sudo." + "hint": "استخدم apt-get مباشرة بدون sudo." }, "block-push-master": { "protectedBranches": ["main", "release", "prod"], - "hint": "Try creating a fresh branch instead." + "hint": "حاول إنشاء فرع جديد بدلاً من ذلك." }, "sanitize-api-keys": { "additionalPatterns": [ - { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" } + { "regex": "myco_[A-Za-z0-9]{32}", "label": "مفتاح API لـ MyCo" } ] }, "warn-large-file-write": { @@ -170,39 +197,39 @@ failproofai policies --uninstall --scope project } ``` -**يتم دمج نطاقات التكوين الثلاثة** تلقائياً (المشروع → المحلي → العام). انظر [docs/configuration.mdx](docs/configuration.mdx) للحصول على قواعد الدمج الكاملة. +**ثلاثة نطاقات إعدادات** يتم دمجها تلقائياً (المشروع → محلي → عام). انظر [docs/configuration.mdx](docs/configuration.mdx) للحصول على قواعد الدمج الكاملة. --- ## السياسات المدمجة -| السياسة | الوصف | قابل للتخصيص | -|--------|--------|:---:| -| `block-sudo` | منع الوكلاء من تشغيل الأوامر النظامية الممتازة | `allowPatterns` | -| `block-rm-rf` | منع حذف الملفات العودية العرضية | `allowPaths` | -| `block-curl-pipe-sh` | منع الوكلاء من أنابيب البرامج النصية غير الموثوقة إلى shell | | +| السياسة | الوصف | قابل للتكوين | +|---------|----------|:---:| +| `block-sudo` | منع الوكلاء من تشغيل أوامر النظام المميزة | `allowPatterns` | +| `block-rm-rf` | منع حذف الملفات المتكرر العرضي | `allowPaths` | +| `block-curl-pipe-sh` | منع الوكلاء من نقل البرامج النصية غير الموثوقة إلى shell | | | `block-failproofai-commands` | منع إلغاء التثبيت الذاتي | | -| `sanitize-jwt` | إيقاف تسريب رموز JWT إلى سياق الوكيل | | -| `sanitize-api-keys` | إيقاف تسريب مفاتيح API إلى سياق الوكيل | `additionalPatterns` | -| `sanitize-connection-strings` | إيقاف تسريب بيانات اعتماد قاعدة البيانات إلى سياق الوكيل | | +| `sanitize-jwt` | وقف تسرب رموز JWT إلى سياق الوكيل | | +| `sanitize-api-keys` | وقف تسرب مفاتيح API إلى سياق الوكيل | `additionalPatterns` | +| `sanitize-connection-strings` | وقف تسرب بيانات اعتماد قاعدة البيانات إلى سياق الوكيل | | | `sanitize-private-key-content` | تحرير كتل مفاتيح PEM الخاصة من الإخراج | | -| `sanitize-bearer-tokens` | تحرير رموز Bearer للترخيص من الإخراج | | +| `sanitize-bearer-tokens` | تحرير رموز Bearer للتفويض من الإخراج | | | `block-env-files` | منع الوكلاء من قراءة ملفات .env | | | `protect-env-vars` | منع الوكلاء من طباعة متغيرات البيئة | | | `block-read-outside-cwd` | احتفظ بالوكلاء داخل حدود المشروع | `allowPaths` | -| `block-secrets-write` | منع الكتابة إلى ملفات المفاتيح والشهادات الخاصة | `additionalPatterns` | +| `block-secrets-write` | منع الكتابة إلى ملفات المفاتيح الخاصة والشهادات | `additionalPatterns` | | `block-push-master` | منع الدفع العرضي إلى main/master | `protectedBranches` | | `block-work-on-main` | احتفظ بالوكلاء بعيداً عن الفروع المحمية | `protectedBranches` | | `block-force-push` | منع `git push --force` | | | `warn-git-amend` | ذكّر الوكلاء قبل تعديل الالتزامات | | -| `warn-git-stash-drop` | ذكّر الوكلاء قبل إسقاط المخزن المؤقت | | -| `warn-all-files-staged` | احصر `git add -A` العرضية | | -| `warn-destructive-sql` | احصر DROP/DELETE SQL قبل التنفيذ | | -| `warn-schema-alteration` | احصر ALTER TABLE قبل التنفيذ | | -| `warn-large-file-write` | احصر كتابات الملفات الكبيرة غير المتوقعة | `thresholdKb` | -| `warn-package-publish` | احصر `npm publish` العرضية | | -| `warn-background-process` | احصر عمليات الخلفية غير المقصودة | | -| `warn-global-package-install` | احصر تثبيتات الحزم العام غير المقصودة | | +| `warn-git-stash-drop` | ذكّر الوكلاء قبل حذف stashes | | +| `warn-all-files-staged` | اكتشف `git add -A` العرضية | | +| `warn-destructive-sql` | اكتشف DROP/DELETE SQL قبل التنفيذ | | +| `warn-schema-alteration` | اكتشف ALTER TABLE قبل التنفيذ | | +| `warn-large-file-write` | اكتشف عمليات كتابة الملفات الكبيرة غير المتوقعة | `thresholdKb` | +| `warn-package-publish` | اكتشف `npm publish` العرضية | | +| `warn-background-process` | اكتشف عمليات الخلفية غير المقصودة | | +| `warn-global-package-install` | اكتشف تثبيت الحزم العامة غير المقصودة | | | …والمزيد | | | تفاصيل السياسة الكاملة ومرجع المعاملات: [docs/built-in-policies.mdx](docs/built-in-policies.mdx) @@ -211,25 +238,25 @@ failproofai policies --uninstall --scope project ## السياسات المخصصة -اكتب سياساتك الخاصة للحفاظ على موثوقية الوكلاء وتركيزهم على المهام: +اكتب سياساتك الخاصة للحفاظ على موثوقية الوكلاء والبقاء على المسار الصحيح: ```js import { customPolicies, allow, deny, instruct } from "failproofai"; customPolicies.add({ name: "no-production-writes", - description: "Block writes to paths containing 'production'", + description: "حجب الكتابة إلى المسارات التي تحتوي على 'production'", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow(); const path = ctx.toolInput?.file_path ?? ""; - if (path.includes("production")) return deny("Writes to production paths are blocked"); + if (path.includes("production")) return deny("الكتابة إلى مسارات الإنتاج محظورة"); return allow(); }, }); ``` -تثبيت مع: +التثبيت مع: ```bash failproofai policies --install --custom ./my-policies.js @@ -238,32 +265,32 @@ failproofai policies --install --custom ./my-policies.js ### مساعدات القرار | الدالة | التأثير | -|--------|--------| +|--------|---------| | `allow()` | السماح بالعملية | -| `allow(message)` | السماح وإرسال سياق معلوماتي إلى Claude | -| `deny(message)` | حجب العملية؛ يتم عرض الرسالة لـ Claude | -| `instruct(message)` | إضافة سياق إلى سلب Claude؛ لا تحجب | +| `allow(message)` | السماح بإرسال السياق المعلوماتي إلى Claude | +| `deny(message)` | حجب العملية؛ الرسالة تظهر لـ Claude | +| `instruct(message)` | إضافة سياق إلى موجه Claude؛ لا تحجب | ### كائن السياق (`ctx`) | الحقل | النوع | الوصف | -|-------|-------|--------| -| `eventType` | `string` | `"PreToolUse"`، `"PostToolUse"`، `"Notification"`، `"Stop"` | -| `toolName` | `string` | الأداة التي يتم استدعاؤها (`"Bash"`، `"Write"`، `"Read"`، …) | +|-------|-------|----------| +| `eventType` | `string` | `PreToolUse`, `PostToolUse`, `Notification`, `Stop` | +| `toolName` | `string` | الأداة المستدعاة (`Bash`, `Write`, `Read`, …) | | `toolInput` | `object` | معاملات إدخال الأداة | -| `payload` | `object` | حمل الحدث الخام الكامل | +| `payload` | `object` | حمولة الحدث الخام الكاملة | | `session.cwd` | `string` | دليل العمل لجلسة Claude Code | -| `session.sessionId` | `string` | معرف الجلسة | -| `session.transcriptPath` | `string` | المسار إلى ملف نسخة الجلسة | +| `session.sessionId` | `string` | معرّف الجلسة | +| `session.transcriptPath` | `string` | المسار إلى ملف نسخ جلسة الجلسة | -تدعم الـ hooks المخصصة الاستيراد المحلي الانتقالي والـ async/await والوصول إلى `process.env`. الأخطاء قابلة للفتح (مسجلة في `~/.failproofai/hook.log`، السياسات المدمجة تستمر). انظر [docs/custom-hooks.mdx](docs/custom-hooks.mdx) للحصول على الدليل الكامل. +الخطافات المخصصة تدعم الواردات المحلية الانتقالية، async/await، والوصول إلى `process.env`. الأخطاء آمنة مفتوحة (مسجلة في `~/.failproofai/hook.log`، تستمر السياسات المدمجة). انظر [docs/custom-hooks.mdx](docs/custom-hooks.mdx) للحصول على الدليل الكامل. -### السياسات المستندة إلى الاتفاقية +### السياسات القائمة على الاتفاقية -أسقط ملفات `*policies.{js,mjs,ts}` في `.failproofai/policies/` وتحمل تلقائياً - لا توجد أعلام أو تغييرات تكوين مطلوبة. احفظ الدليل في git وكل عضو فريق يحصل على نفس معايير الجودة تلقائياً. +قم بإسقاط ملفات `*policies.{js,mjs,ts}` في `.failproofai/policies/` ويتم تحميلها تلقائياً — بدون أعلام أو تغييرات إعدادات. التزم الدليل بـ git وكل عضو في الفريق يحصل على معايير الجودة نفسها تلقائياً. ```text -# مستوى المشروع — ملتزم بـ git، مشترك مع الفريق +# مستوى المشروع — مُلتزم بـ git، مشترك مع الفريق .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs @@ -271,13 +298,13 @@ failproofai policies --install --custom ./my-policies.js ~/.failproofai/policies/my-policies.mjs ``` -كلا المستويين محملان (اتحاد). يتم تحميل الملفات أبجدياً داخل كل دليل. البادئة مع `01-`، `02-`، إلخ للتحكم في الترتيب. مع اكتشاف فريقك لحالات فشل جديدة، أضف سياسة ودفع — يحصل الجميع على التحديث في السحب التالي. انظر [examples/convention-policies/](examples/convention-policies/) للأمثلة الجاهزة للاستخدام. +كلا المستويين يحملان (اتحاد). يتم تحميل الملفات أبجدياً داخل كل دليل. البادئة مع `01-`, `02-`, إلخ. للتحكم في الترتيب. عندما يكتشف فريقك أنماط فشل جديدة، أضف سياسة وادفع — يحصل الجميع على التحديث في سحب الطلب التالي. انظر [examples/convention-policies/](examples/convention-policies/) للحصول على أمثلة جاهزة للاستخدام. --- -## القياس عن بعد +## قياس الاستخدام -يجمع Failproof AI قياس الاستخدام المجهول عبر PostHog لفهم استخدام الميزات. لم يتم أبداً إرسال محتوى الجلسة أو أسماء الملفات أو إدخالات الأدوات أو المعلومات الشخصية. +يجمع Failproof AI بيانات قياس الاستخدام المجهولة عبر PostHog لفهم استخدام الميزات. لا يتم أبداً إرسال محتوى الجلسة أو أسماء الملفات أو مدخلات الأداة أو المعلومات الشخصية. تعطيله: @@ -290,14 +317,14 @@ FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai ## التوثيق | الدليل | الوصف | -|--------|--------| -| [البدء](docs/getting-started.mdx) | التثبيت والخطوات الأولى | -| [السياسات المدمجة](docs/built-in-policies.mdx) | جميع 39 سياسة مدمجة مع المعاملات | -| [السياسات المخصصة](docs/custom-policies.mdx) | اكتب سياساتك الخاصة | -| [التكوين](docs/configuration.mdx) | تنسيق ملف التكوين ودمج النطاق | -| [لوحة التحكم](docs/dashboard.mdx) | راقب الجلسات واستعرض نشاط السياسة | -| [العمارة](docs/architecture.mdx) | كيف يعمل نظام hook | -| [الاختبار](docs/testing.mdx) | تشغيل الاختبارات وكتابة اختبارات جديدة | +|--------|----------| +| [Getting Started](docs/getting-started.mdx) | التثبيت والخطوات الأولى | +| [Built-in Policies](docs/built-in-policies.mdx) | جميع السياسات المدمجة الـ 39 مع المعاملات | +| [Custom Policies](docs/custom-policies.mdx) | اكتب سياساتك الخاصة | +| [Configuration](docs/configuration.mdx) | صيغة ملف الإعدادات ودمج النطاقات | +| [Dashboard](docs/dashboard.mdx) | مراقبة الجلسات ومراجعة نشاط السياسة | +| [Architecture](docs/architecture.mdx) | كيف يعمل نظام الخطافات | +| [Testing](docs/testing.mdx) | تشغيل الاختبارات وكتابة اختبارات جديدة | ### تشغيل التوثيق محلياً @@ -306,7 +333,7 @@ docker build -f Dockerfile.docs -t failproofai-docs . docker run --rm -p 3000:3000 failproofai-docs ``` -يفتح موقع Mintlify documentation على `http://localhost:3000`. الحاوية تراقب التغييرات إذا قمت بتحميل دليل التوثيق: +يفتح موقع Mintlify للتوثيق في `http://localhost:3000`. ستراقب الحاوية التغييرات إذا قمت بتركيب دليل التوثيق: ```bash docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs @@ -316,9 +343,9 @@ docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs ## ملاحظة لمساهمي failproofai -يستخدم ملف `.claude/settings.json` الخاص بهذا المستودع `bun ./bin/failproofai.mjs --hook ` بدلاً من أمر `npx -y failproofai` القياسي. هذا لأن تشغيل `npx -y failproofai` داخل مشروع failproofai نفسه يخلق تضاربة يشير إلى نفسه. +يستخدم `.claude/settings.json` في هذا الريبو `bun ./bin/failproofai.mjs --hook ` بدلاً من أمر `npx -y failproofai` القياسي. وذلك لأن تشغيل `npx -y failproofai` داخل مشروع failproofai نفسه ينشئ تضاربة الإحالة الذاتية. -بالنسبة لجميع المستودعات الأخرى، النهج الموصى به هو `npx -y failproofai`، المثبت عبر: +بالنسبة لجميع المستودعات الأخرى، الطريقة الموصى بها هي `npx -y failproofai`، المثبتة عبر: ```bash failproofai policies --install --scope project @@ -336,7 +363,7 @@ failproofai policies --install --scope project --- -تم الإنشاء والصيانة بواسطة **ExosphereHost: مختبر أبحاث الموثوقية لوكلاءك**. نساعد المؤسسات والشركات الناشئة على تحسين موثوقية وكلاءهم بالذكاء الاصطناعي من خلال وكلائنا الخاصين والبرامج والخبرة. تعرف على المزيد على [exosphere.host](https://exosphere.host). +مبني وتم الحفاظ عليه بواسطة **ExosphereHost: Reliability Research Lab for Your Agents**. نساعد المؤسسات والشركات الناشئة على تحسين موثوقية وكلاء الذكاء الاصطناعي لديهم من خلال وكلائنا والبرامج والخبرات الخاصة بنا. تعرف على المزيد في [exosphere.host](https://exosphere.host). \ No newline at end of file diff --git a/docs/i18n/README.de.md b/docs/i18n/README.de.md index 7fc5e147..b091a92d 100644 --- a/docs/i18n/README.de.md +++ b/docs/i18n/README.de.md @@ -23,13 +23,13 @@ **Ü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) -Der einfachste Weg, Richtlinien zu verwalten, die Ihre KI-Agenten zuverlässig, fokussiert und autonom am Laufen halten – für **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(Beta)_ und das **Agents SDK**. +Die einfachste Möglichkeit, Richtlinien zu verwalten, die Ihre KI-Agenten zuverlässig, fokussiert und autonom am Laufen halten – für **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(Beta)_, **Cursor Agent** _(Beta)_, **OpenCode** _(Beta)_, **Pi** _(Beta)_, **Gemini CLI** _(Beta)_ und das **Agents SDK**.

Failproof AI in Aktion

-## Unterstützte Agenten-CLIs +## Unterstützte Agent-CLIs

@@ -50,15 +50,42 @@ Der einfachste Weg, Richtlinien zu verwalten, die Ihre KI-Agenten zuverlässig,        - + weitere folgen in Kürze + + + + Cursor Agent + + +

+

+ + + + OpenCode + + +        + + + + Pi + + +        + + + + Gemini CLI + +

-> Hooks für eine, zwei oder alle drei installieren: `failproofai policies --install --cli copilot` (oder `--cli claude codex copilot`). `--cli` weglassen, um installierte CLIs automatisch zu erkennen und eine Auswahl anzuzeigen. **Die GitHub Copilot CLI-Unterstützung befindet sich in der Beta-Phase.** +> Hooks für eine oder mehrere Kombinationen 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 anzuzeigen. **Die Unterstützung für GitHub Copilot CLI, Cursor Agent, OpenCode, Pi und Gemini CLI befindet sich in der Beta – Tests laufen noch.** -- **39 integrierte Richtlinien** – Häufige Fehlerquellen von Agenten werden sofort abgefangen. Destruktive Befehle blockieren, das Durchsickern von Geheimnissen verhindern, Agenten innerhalb der Projektgrenzen halten, Schleifen erkennen und vieles mehr. -- **Benutzerdefinierte Richtlinien** – Schreiben Sie eigene Zuverlässigkeitsregeln in JavaScript. Nutzen Sie die `allow`/`deny`/`instruct`-API, um Konventionen durchzusetzen, Abweichungen zu verhindern, Operationen zu kontrollieren oder externe Systeme einzubinden. -- **Einfache Konfiguration** – Jede Richtlinie lässt sich ohne Code anpassen. Erlaubnislisten, geschützte Branches und Schwellenwerte können pro Projekt oder global festgelegt werden. Drei Konfigurationsbereiche werden automatisch zusammengeführt. -- **Agent Monitor** – Sehen Sie, was Ihre Agenten in Ihrer Abwesenheit getan haben. Sitzungen durchsuchen, jeden Tool-Aufruf prüfen und genau nachvollziehen, wo Richtlinien ausgelöst wurden. +- **39 integrierte Richtlinien** – Häufige Fehlermuster von Agenten werden sofort erkannt. Destruktive Befehle werden blockiert, das Durchsickern von Geheimnissen verhindert, Agenten innerhalb der Projektgrenzen gehalten, Schleifen erkannt und vieles mehr. +- **Benutzerdefinierte Richtlinien** – Schreiben Sie eigene Zuverlässigkeitsregeln in JavaScript. Nutzen Sie die `allow`/`deny`/`instruct`-API, um Konventionen durchzusetzen, Abweichungen zu verhindern, Operationen zu genehmigen oder externe Systeme einzubinden. +- **Einfache Konfiguration** – Jede Richtlinie lässt sich ohne Code anpassen. Allowlists, geschützte Branches und Schwellenwerte können pro Projekt oder global festgelegt werden. Drei Konfigurationsbereiche werden automatisch zusammengeführt. +- **Agent-Monitor** – Sehen Sie, was Ihre Agenten in Ihrer Abwesenheit getan haben. Sessions durchsuchen, jeden Tool-Aufruf prüfen und genau nachvollziehen, wo Richtlinien ausgelöst wurden. Alles läuft lokal – keine Daten verlassen Ihren Rechner. @@ -67,7 +94,7 @@ Alles läuft lokal – keine Daten verlassen Ihren Rechner. ## Voraussetzungen - Node.js >= 20.9.0 -- Bun >= 1.3.0 (optional – nur für die Entwicklung / das Bauen aus dem Quellcode erforderlich) +- Bun >= 1.3.0 (optional – nur für Entwicklung / Build aus dem Quellcode erforderlich) --- @@ -97,7 +124,7 @@ Schreibt Hook-Einträge in `~/.claude/settings.json`. Claude Code ruft failproof failproofai ``` -Öffnet `http://localhost:8020` – Sitzungen durchsuchen, Logs einsehen, Richtlinien verwalten. +Öffnet `http://localhost:8020` – Sessions durchsuchen, Logs einsehen, Richtlinien verwalten. ### 3. Aktive Richtlinien prüfen @@ -111,8 +138,8 @@ failproofai policies ### Bereiche -| Bereich | Befehl | Schreibort | -|---------|--------|------------| +| Bereich | Befehl | Schreibziel | +|---------|--------|-------------| | Global (Standard) | `failproofai policies --install` | `~/.claude/settings.json` | | Projekt | `failproofai policies --install --scope project` | `.claude/settings.json` | | Lokal | `failproofai policies --install --scope local` | `.claude/settings.local.json` | @@ -135,7 +162,7 @@ failproofai policies --uninstall --scope project ## Konfiguration -Die Richtlinienkonfiguration liegt in `~/.failproofai/policies-config.json` (global) oder `.failproofai/policies-config.json` in Ihrem Projekt (projektspezifisch). +Die Richtlinienkonfiguration befindet sich in `~/.failproofai/policies-config.json` (global) oder `.failproofai/policies-config.json` in Ihrem Projekt (projektspezifisch). ```json { @@ -168,32 +195,32 @@ Die Richtlinienkonfiguration liegt in `~/.failproofai/policies-config.json` (glo } ``` -**Drei Konfigurationsbereiche** werden automatisch zusammengeführt (Projekt → Lokal → Global). Die vollständigen Zusammenführungsregeln finden Sie in [docs/configuration.mdx](docs/configuration.mdx). +**Drei Konfigurationsbereiche** werden automatisch zusammengeführt (Projekt → Lokal → Global). Vollständige Zusammenführungsregeln finden Sie unter [docs/configuration.mdx](docs/configuration.mdx). --- ## Integrierte Richtlinien | Richtlinie | Beschreibung | Konfigurierbar | -|------------|--------------|:--------------:| +|------------|-------------|:---:| | `block-sudo` | Verhindert, dass Agenten privilegierte Systembefehle ausführen | `allowPatterns` | | `block-rm-rf` | Verhindert versehentliches rekursives Löschen von Dateien | `allowPaths` | -| `block-curl-pipe-sh` | Verhindert, dass Agenten nicht vertrauenswürdige Skripte in die Shell leiten | | +| `block-curl-pipe-sh` | Verhindert, dass Agenten nicht vertrauenswürdige Skripte per Pipe an die Shell übergeben | | | `block-failproofai-commands` | Verhindert die Selbstdeinstallation | | -| `sanitize-jwt` | Verhindert, dass JWT-Token in den Agentenkontext gelangen | | -| `sanitize-api-keys` | Verhindert, dass API-Schlüssel in den Agentenkontext gelangen | `additionalPatterns` | -| `sanitize-connection-strings` | Verhindert, dass Datenbank-Anmeldedaten in den Agentenkontext gelangen | | -| `sanitize-private-key-content` | Entfernt PEM-Private-Key-Blöcke aus der Ausgabe | | -| `sanitize-bearer-tokens` | Entfernt Authorization-Bearer-Token aus der Ausgabe | | +| `sanitize-jwt` | Verhindert, dass JWT-Token in den Agenten-Kontext gelangen | | +| `sanitize-api-keys` | Verhindert, dass API-Schlüssel in den Agenten-Kontext gelangen | `additionalPatterns` | +| `sanitize-connection-strings` | Verhindert, dass Datenbank-Zugangsdaten in den Agenten-Kontext gelangen | | +| `sanitize-private-key-content` | Schwärzt PEM-Private-Key-Blöcke aus der Ausgabe | | +| `sanitize-bearer-tokens` | Schwärzt Authorization-Bearer-Token aus der Ausgabe | | | `block-env-files` | Verhindert, dass Agenten .env-Dateien lesen | | | `protect-env-vars` | Verhindert, dass Agenten Umgebungsvariablen ausgeben | | | `block-read-outside-cwd` | Hält Agenten innerhalb der Projektgrenzen | `allowPaths` | -| `block-secrets-write` | Verhindert das Schreiben in Private-Key- und Zertifikatsdateien | `additionalPatterns` | -| `block-push-master` | Verhindert versehentliche Pushes nach main/master | `protectedBranches` | +| `block-secrets-write` | Verhindert das Schreiben in Private-Key- und Zertifikatdateien | `additionalPatterns` | +| `block-push-master` | Verhindert versehentliche Pushes auf main/master | `protectedBranches` | | `block-work-on-main` | Hält Agenten von geschützten Branches fern | `protectedBranches` | | `block-force-push` | Verhindert `git push --force` | | | `warn-git-amend` | Erinnert Agenten vor dem Ändern von Commits | | -| `warn-git-stash-drop` | Erinnert Agenten vor dem Verwerfen von Stashes | | +| `warn-git-stash-drop` | Erinnert Agenten vor dem Löschen von Stashes | | | `warn-all-files-staged` | Erkennt versehentliches `git add -A` | | | `warn-destructive-sql` | Erkennt DROP/DELETE-SQL vor der Ausführung | | | `warn-schema-alteration` | Erkennt ALTER TABLE vor der Ausführung | | @@ -201,7 +228,7 @@ Die Richtlinienkonfiguration liegt in `~/.failproofai/policies-config.json` (glo | `warn-package-publish` | Erkennt versehentliches `npm publish` | | | `warn-background-process` | Erkennt unbeabsichtigte Hintergrundprozess-Starts | | | `warn-global-package-install` | Erkennt unbeabsichtigte globale Paketinstallationen | | -| …und weitere | | | +| …und mehr | | | Vollständige Richtliniendetails und Parameterreferenz: [docs/built-in-policies.mdx](docs/built-in-policies.mdx) @@ -209,7 +236,7 @@ Vollständige Richtliniendetails und Parameterreferenz: [docs/built-in-policies. ## Benutzerdefinierte Richtlinien -Schreiben Sie eigene Richtlinien, um Agenten zuverlässig und fokussiert zu halten: +Schreiben Sie eigene Richtlinien, um Agenten zuverlässig und auf Kurs zu halten: ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -227,7 +254,7 @@ customPolicies.add({ }); ``` -Installation mit: +Installieren mit: ```bash failproofai policies --install --custom ./my-policies.js @@ -237,45 +264,45 @@ failproofai policies --install --custom ./my-policies.js | Funktion | Wirkung | |----------|---------| -| `allow()` | Operation erlauben | -| `allow(message)` | Operation erlauben und informativen Kontext an Claude senden | -| `deny(message)` | Operation blockieren; Nachricht wird Claude angezeigt | +| `allow()` | Aktion erlauben | +| `allow(message)` | Erlauben und informativen Kontext an Claude senden | +| `deny(message)` | Aktion blockieren; Nachricht wird Claude angezeigt | | `instruct(message)` | Kontext zum Prompt von Claude hinzufügen; blockiert nicht | ### Kontextobjekt (`ctx`) | Feld | Typ | Beschreibung | -|------|-----|--------------| +|------|-----|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | | `toolName` | `string` | Aufgerufenes Tool (`"Bash"`, `"Write"`, `"Read"`, …) | | `toolInput` | `object` | Eingabeparameter des Tools | -| `payload` | `object` | Vollständiger roher Event-Payload | -| `session.cwd` | `string` | Arbeitsverzeichnis der Claude Code-Sitzung | -| `session.sessionId` | `string` | Sitzungskennung | +| `payload` | `object` | Vollständige rohe Event-Nutzlast | +| `session.cwd` | `string` | Arbeitsverzeichnis der Claude Code-Session | +| `session.sessionId` | `string` | Session-Bezeichner | | `session.transcriptPath` | `string` | Pfad zur Sitzungstranskript-Datei | -Benutzerdefinierte Hooks unterstützen transitive lokale Importe, async/await und Zugriff auf `process.env`. Fehler verhalten sich fail-open (werden in `~/.failproofai/hook.log` protokolliert, integrierte Richtlinien laufen weiter). Die vollständige Anleitung finden Sie in [docs/custom-hooks.mdx](docs/custom-hooks.mdx). +Benutzerdefinierte Hooks unterstützen transitive lokale Importe, async/await und Zugriff auf `process.env`. Fehler verhalten sich fail-open (werden in `~/.failproofai/hook.log` protokolliert, integrierte Richtlinien laufen weiter). Vollständige Anleitung: [docs/custom-hooks.mdx](docs/custom-hooks.mdx). ### Konventionsbasierte Richtlinien -Legen Sie `*policies.{js,mjs,ts}`-Dateien in `.failproofai/policies/` ab und sie werden automatisch geladen – ohne zusätzliche Flags oder Konfigurationsänderungen. Committen Sie das Verzeichnis in Git und jedes Teammitglied erhält automatisch dieselben Qualitätsstandards. +Legen Sie `*policies.{js,mjs,ts}`-Dateien in `.failproofai/policies/` ab – sie werden automatisch geladen, ohne Flags oder Konfigurationsänderungen. Committen Sie das Verzeichnis in Git, und alle Teammitglieder erhalten automatisch dieselben Qualitätsstandards. ```text -# Projektebene — in Git eingecheckt, mit dem Team geteilt +# Projektebene – in Git eingecheckt, mit dem Team geteilt .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# Benutzerebene — persönlich, gilt für alle Projekte +# Benutzerebene – persönlich, gilt für alle Projekte ~/.failproofai/policies/my-policies.mjs ``` -Beide Ebenen werden geladen (Vereinigung). Dateien werden innerhalb jedes Verzeichnisses alphabetisch geladen. Präfixe wie `01-`, `02-` usw. steuern die Reihenfolge. Sobald Ihr Team neue Fehlerquellen entdeckt, fügen Sie eine Richtlinie hinzu und pushen – alle erhalten die Aktualisierung beim nächsten Pull. Einsatzbereite Beispiele finden Sie unter [examples/convention-policies/](examples/convention-policies/). +Beide Ebenen werden geladen (Vereinigung). Dateien werden innerhalb jedes Verzeichnisses alphabetisch geladen. Mit `01-`, `02-` usw. als Präfix lässt sich die Reihenfolge steuern. Sobald Ihr Team neue Fehlermuster entdeckt, fügen Sie eine Richtlinie hinzu und pushen – alle erhalten das Update beim nächsten Pull. Fertige Beispiele finden Sie unter [examples/convention-policies/](examples/convention-policies/). --- ## Telemetrie -Failproof AI erfasst anonyme Nutzungstelemetrie über PostHog, um die Nutzung von Funktionen zu verstehen. Es werden niemals Sitzungsinhalte, Dateinamen, Tool-Eingaben oder persönliche Informationen übermittelt. +Failproof AI erfasst anonyme Nutzungstelemetrie über PostHog, um die Nutzung von Funktionen zu verstehen. Es werden niemals Session-Inhalte, Dateinamen, Tool-Eingaben oder persönliche Informationen übermittelt. Deaktivieren: @@ -288,14 +315,14 @@ FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai ## Dokumentation | Leitfaden | Beschreibung | -|-----------|--------------| +|-----------|-------------| | [Erste Schritte](docs/getting-started.mdx) | Installation und erste Schritte | | [Integrierte Richtlinien](docs/built-in-policies.mdx) | Alle 39 integrierten Richtlinien mit Parametern | | [Benutzerdefinierte Richtlinien](docs/custom-policies.mdx) | Eigene Richtlinien schreiben | | [Konfiguration](docs/configuration.mdx) | Konfigurationsdateiformat und Bereichszusammenführung | -| [Dashboard](docs/dashboard.mdx) | Sitzungen überwachen und Richtlinienaktivität einsehen | +| [Dashboard](docs/dashboard.mdx) | Sessions überwachen und Richtlinienaktivität prüfen | | [Architektur](docs/architecture.mdx) | Funktionsweise des Hook-Systems | -| [Tests](docs/testing.mdx) | Tests ausführen und neue Tests schreiben | +| [Tests](docs/testing.mdx) | Tests ausführen und neue schreiben | ### Dokumentation lokal ausführen @@ -304,7 +331,7 @@ docker build -f Dockerfile.docs -t failproofai-docs . docker run --rm -p 3000:3000 failproofai-docs ``` -Öffnet die Mintlify-Dokumentationsseite unter `http://localhost:3000`. Der Container erkennt Änderungen, wenn Sie das Docs-Verzeichnis einbinden: +Öffnet die Mintlify-Dokumentationsseite unter `http://localhost:3000`. Der Container erkennt Änderungen, wenn Sie das docs-Verzeichnis einbinden: ```bash docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs @@ -314,9 +341,9 @@ docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs ## Hinweis für failproofai-Mitwirkende -Die `.claude/settings.json` dieses Repos verwendet `bun ./bin/failproofai.mjs --hook ` anstelle des standardmäßigen `npx -y failproofai`-Befehls. Dies liegt daran, dass die Ausführung von `npx -y failproofai` innerhalb des failproofai-Projekts selbst einen selbstreferenzierenden Konflikt erzeugt. +Die `.claude/settings.json` dieses Repos verwendet `bun ./bin/failproofai.mjs --hook ` anstelle des Standardbefehls `npx -y failproofai`. Das liegt daran, dass die Ausführung von `npx -y failproofai` innerhalb des failproofai-Projekts selbst einen selbstreferenzierenden Konflikt erzeugt. -Für alle anderen Repos ist die empfohlene Vorgehensweise `npx -y failproofai`, installiert über: +Für alle anderen Repos ist der empfohlene Ansatz `npx -y failproofai`, installiert über: ```bash failproofai policies --install --scope project @@ -334,4 +361,4 @@ Siehe [LICENSE](LICENSE). --- -Entwickelt und gepflegt von **ExosphereHost: Reliability Research Lab for Your Agents**. Wir helfen Unternehmen und Startups dabei, die Zuverlässigkeit ihrer KI-Agenten durch eigene Agenten, Software und Expertise zu verbessern. Mehr erfahren unter [exosphere.host](https://exosphere.host). +Entwickelt und gepflegt von **ExosphereHost: Reliability Research Lab for Your Agents**. Wir helfen Unternehmen und Start-ups dabei, die Zuverlässigkeit ihrer KI-Agenten durch eigene Agenten, Software und Expertise zu verbessern. Mehr erfahren unter [exosphere.host](https://exosphere.host). diff --git a/docs/i18n/README.es.md b/docs/i18n/README.es.md index 2b366a0f..925cbc11 100644 --- a/docs/i18n/README.es.md +++ b/docs/i18n/README.es.md @@ -23,7 +23,7 @@ **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) -La forma más sencilla de gestionar políticas que mantienen a tus agentes de IA fiables, centrados en la tarea y ejecutándose de forma autónoma — para **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(beta)_ y el **Agents SDK**. +La forma más sencilla de gestionar políticas que mantienen a tus agentes de IA fiables, centrados en su tarea y funcionando de forma autónoma — para **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(beta)_, **Cursor Agent** _(beta)_, **OpenCode** _(beta)_, **Pi** _(beta)_, **Gemini CLI** _(beta)_ y el **Agents SDK**.

Failproof AI en acción @@ -50,15 +50,42 @@ La forma más sencilla de gestionar políticas que mantienen a tus agentes de IA        - + más próximamente + + + + Cursor Agent + + +

+

+ + + + OpenCode + + +        + + + + Pi + + +        + + + + Gemini CLI + +

-> Instala hooks para uno, dos o los tres: `failproofai policies --install --cli copilot` (o `--cli claude codex copilot`). Omite `--cli` para detectar automáticamente los CLIs instalados y mostrar un menú de selección. **La compatibilidad con GitHub Copilot CLI está en beta.** +> 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. **El soporte para GitHub Copilot CLI, Cursor Agent, OpenCode, Pi y Gemini CLI está en beta — las pruebas están en curso.** -- **39 políticas integradas** - Detecta los modos de fallo más comunes de los agentes sin configuración adicional. Bloquea comandos destructivos, previene la filtración de secretos, mantiene a los agentes dentro de los límites del proyecto, detecta bucles y mucho más. -- **Políticas personalizadas** - Escribe tus propias reglas de fiabilidad en JavaScript. Usa la API `allow`/`deny`/`instruct` para aplicar convenciones, prevenir la desviación de comportamiento, controlar operaciones o integrarte con sistemas externos. -- **Configuración sencilla** - Ajusta cualquier política sin escribir código. Define listas de permitidos, ramas protegidas y umbrales por proyecto o de forma global. Los tres niveles de configuración se combinan automáticamente. -- **Monitor de agentes** - Revisa qué hicieron tus agentes mientras no estabas. Navega por las sesiones, inspecciona cada llamada a herramienta y analiza exactamente dónde se activaron las políticas. +- **39 políticas integradas** — Detecta los fallos más comunes de los agentes de serie. Bloquea comandos destructivos, evita la filtración de secretos, mantiene a los agentes dentro de los límites del proyecto, detecta bucles y mucho más. +- **Políticas personalizadas** — Escribe tus propias reglas de fiabilidad en JavaScript. Usa la API `allow`/`deny`/`instruct` para aplicar convenciones, evitar desvíos, controlar operaciones o integrarte con sistemas externos. +- **Configuración sencilla** — Ajusta cualquier política sin escribir código. Define listas de permitidos, ramas protegidas y umbrales por proyecto o de forma global. La configuración de tres ámbitos se fusiona automáticamente. +- **Monitor de agentes** — Consulta lo que hicieron tus agentes mientras no estabas. Navega por las sesiones, inspecciona cada llamada a herramienta y revisa exactamente dónde se activaron las políticas. Todo se ejecuta localmente — ningún dato sale de tu máquina. @@ -67,7 +94,7 @@ Todo se ejecuta localmente — ningún dato sale de tu máquina. ## Requisitos - Node.js >= 20.9.0 -- Bun >= 1.3.0 (opcional — solo necesario para desarrollo o compilación desde el código fuente) +- Bun >= 1.3.0 (opcional — solo necesario para desarrollo / compilación desde el código fuente) --- @@ -83,7 +110,7 @@ bun add -g failproofai ## Inicio rápido -### 1. Activa las políticas globalmente +### 1. Activar las políticas globalmente ```bash failproofai policies --install @@ -91,7 +118,7 @@ failproofai policies --install Escribe las entradas de hook en `~/.claude/settings.json`. Claude Code invocará failproofai antes y después de cada llamada a herramienta. -### 2. Abre el panel de control +### 2. Abrir el panel de control ```bash failproofai @@ -99,7 +126,7 @@ failproofai Abre `http://localhost:8020` — navega por las sesiones, inspecciona los registros y gestiona las políticas. -### 3. Comprueba qué está activo +### 3. Comprobar qué está activo ```bash failproofai policies @@ -109,11 +136,11 @@ failproofai policies ## Instalación de políticas -### Niveles de alcance +### Ámbitos -| Alcance | Comando | Dónde escribe | -|---------|---------|---------------| -| Global (por defecto) | `failproofai policies --install` | `~/.claude/settings.json` | +| Ámbito | Comando | Dónde escribe | +|--------|---------|---------------| +| Global (predeterminado) | `failproofai policies --install` | `~/.claude/settings.json` | | Proyecto | `failproofai policies --install --scope project` | `.claude/settings.json` | | Local | `failproofai policies --install --scope local` | `.claude/settings.local.json` | @@ -127,7 +154,7 @@ failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ```bash failproofai policies --uninstall -# o para un alcance específico: +# o para un ámbito específico: failproofai policies --uninstall --scope project ``` @@ -135,7 +162,7 @@ failproofai policies --uninstall --scope project ## Configuración -La configuración de políticas se encuentra en `~/.failproofai/policies-config.json` (global) o en `.failproofai/policies-config.json` dentro de tu proyecto (por proyecto). +La configuración de políticas reside en `~/.failproofai/policies-config.json` (global) o en `.failproofai/policies-config.json` dentro de tu proyecto (por proyecto). ```json { @@ -168,7 +195,7 @@ La configuración de políticas se encuentra en `~/.failproofai/policies-config. } ``` -**Los tres niveles de configuración** se combinan automáticamente (proyecto → local → global). Consulta [docs/configuration.mdx](docs/configuration.mdx) para ver las reglas completas de combinación. +**Los tres ámbitos de configuración** se fusionan automáticamente (proyecto → local → global). Consulta [docs/configuration.mdx](docs/configuration.mdx) para ver las reglas completas de fusión. --- @@ -176,31 +203,31 @@ La configuración de políticas se encuentra en `~/.failproofai/policies-config. | Política | Descripción | Configurable | |----------|-------------|:---:| -| `block-sudo` | Evita que los agentes ejecuten comandos del sistema con privilegios elevados | `allowPatterns` | +| `block-sudo` | Evita que los agentes ejecuten comandos de sistema con privilegios | `allowPatterns` | | `block-rm-rf` | Previene la eliminación recursiva accidental de archivos | `allowPaths` | -| `block-curl-pipe-sh` | Evita que los agentes ejecuten scripts no confiables a través de la shell | | -| `block-failproofai-commands` | Previene la autodesinstalación | | -| `sanitize-jwt` | Evita que los tokens JWT se filtren al contexto del agente | | -| `sanitize-api-keys` | Evita que las claves de API se filtren al contexto del agente | `additionalPatterns` | -| `sanitize-connection-strings` | Evita que las credenciales de base de datos se filtren al contexto del agente | | -| `sanitize-private-key-content` | Oculta los bloques de clave privada PEM en la salida | | -| `sanitize-bearer-tokens` | Oculta los tokens Bearer de Authorization en la salida | | +| `block-curl-pipe-sh` | Evita que los agentes canalicen scripts no confiables al shell | | +| `block-failproofai-commands` | Previene la auto-desinstalación | | +| `sanitize-jwt` | Impide que los tokens JWT se filtren al contexto del agente | | +| `sanitize-api-keys` | Impide que las claves API se filtren al contexto del agente | `additionalPatterns` | +| `sanitize-connection-strings` | Impide que las credenciales de base de datos se filtren al contexto del agente | | +| `sanitize-private-key-content` | Oculta los bloques de clave privada PEM de la salida | | +| `sanitize-bearer-tokens` | Oculta los tokens Bearer de Authorization de la salida | | | `block-env-files` | Impide que los agentes lean archivos .env | | | `protect-env-vars` | Evita que los agentes impriman variables de entorno | | | `block-read-outside-cwd` | Mantiene a los agentes dentro de los límites del proyecto | `allowPaths` | -| `block-secrets-write` | Previene escrituras en archivos de clave privada y certificados | `additionalPatterns` | +| `block-secrets-write` | Previene escrituras en archivos de claves privadas y certificados | `additionalPatterns` | | `block-push-master` | Previene envíos accidentales a main/master | `protectedBranches` | | `block-work-on-main` | Mantiene a los agentes fuera de las ramas protegidas | `protectedBranches` | | `block-force-push` | Previene `git push --force` | | | `warn-git-amend` | Avisa a los agentes antes de modificar commits | | | `warn-git-stash-drop` | Avisa a los agentes antes de eliminar stashes | | | `warn-all-files-staged` | Detecta un `git add -A` accidental | | -| `warn-destructive-sql` | Detecta instrucciones DROP/DELETE SQL antes de ejecutarlas | | -| `warn-schema-alteration` | Detecta ALTER TABLE antes de ejecutarlo | | +| `warn-destructive-sql` | Detecta sentencias DROP/DELETE SQL antes de ejecutarlas | | +| `warn-schema-alteration` | Detecta ALTER TABLE antes de ejecutarlas | | | `warn-large-file-write` | Detecta escrituras de archivos inesperadamente grandes | `thresholdKb` | | `warn-package-publish` | Detecta un `npm publish` accidental | | | `warn-background-process` | Detecta lanzamientos no intencionados de procesos en segundo plano | | -| `warn-global-package-install` | Detecta instalaciones de paquetes globales no intencionadas | | +| `warn-global-package-install` | Detecta instalaciones globales de paquetes no intencionadas | | | …y más | | | Detalles completos de políticas y referencia de parámetros: [docs/built-in-policies.mdx](docs/built-in-policies.mdx) @@ -209,7 +236,7 @@ Detalles completos de políticas y referencia de parámetros: [docs/built-in-pol ## Políticas personalizadas -Escribe tus propias políticas para mantener a los agentes fiables y centrados en la tarea: +Escribe tus propias políticas para mantener a los agentes fiables y centrados en su tarea: ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -247,35 +274,35 @@ failproofai policies --install --custom ./my-policies.js | Campo | Tipo | Descripción | |-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string` | Herramienta que se está llamando (`"Bash"`, `"Write"`, `"Read"`, …) | +| `toolName` | `string` | Herramienta invocada (`"Bash"`, `"Write"`, `"Read"`, …) | | `toolInput` | `object` | Parámetros de entrada de la herramienta | -| `payload` | `object` | Payload completo del evento en crudo | +| `payload` | `object` | Payload completo del evento en bruto | | `session.cwd` | `string` | Directorio de trabajo de la sesión de Claude Code | | `session.sessionId` | `string` | Identificador de sesión | | `session.transcriptPath` | `string` | Ruta al archivo de transcripción de la sesión | -Los hooks personalizados admiten importaciones locales transitivas, async/await y acceso a `process.env`. Los errores son fail-open (se registran en `~/.failproofai/hook.log` y las políticas integradas continúan ejecutándose). Consulta [docs/custom-hooks.mdx](docs/custom-hooks.mdx) para la guía completa. +Los hooks personalizados admiten importaciones locales transitivas, async/await y acceso a `process.env`. Los errores son fail-open (se registran en `~/.failproofai/hook.log` y las políticas integradas continúan). Consulta [docs/custom-hooks.mdx](docs/custom-hooks.mdx) para la guía completa. -### Políticas basadas en convención +### Políticas basadas en convenciones -Coloca archivos `*policies.{js,mjs,ts}` en `.failproofai/policies/` y se cargarán automáticamente — sin necesidad de flags ni cambios de configuración. Confirma el directorio en git y todos los miembros del equipo obtendrán automáticamente los mismos estándares de calidad. +Coloca archivos `*policies.{js,mjs,ts}` en `.failproofai/policies/` y se cargarán automáticamente — sin necesidad de flags ni cambios de configuración. Haz commit del directorio en git y cada miembro del equipo obtendrá los mismos estándares de calidad automáticamente. ```text -# Nivel de proyecto — confirmado 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 -# Nivel de usuario — personal, se aplica a todos los proyectos +# Nivel de usuario — personal, aplica a todos los proyectos ~/.failproofai/policies/my-policies.mjs ``` -Ambos niveles se cargan (unión). Los archivos se cargan alfabéticamente dentro de cada directorio. Usa prefijos como `01-`, `02-`, etc. para controlar el orden. A medida que el equipo descubre nuevos modos de fallo, añade una política y haz push — todos recibirán la actualización en su próximo pull. Consulta [examples/convention-policies/](examples/convention-policies/) para ver ejemplos listos para usar. +Ambos niveles se cargan (unión). Los archivos se cargan alfabéticamente dentro de cada directorio. Usa prefijos `01-`, `02-`, etc. para controlar el orden. A medida que tu equipo descubra nuevos modos de fallo, añade una política y haz push — todos recibirán la actualización en su próximo pull. Consulta [examples/convention-policies/](examples/convention-policies/) para ver ejemplos listos para usar. --- ## Telemetría -Failproof AI recopila telemetría de uso anónima a través de PostHog para entender el uso de las funcionalidades. Nunca se envía contenido de sesiones, nombres de archivos, entradas de herramientas ni información personal. +Failproof AI recopila telemetría de uso anónima a través de PostHog para comprender el uso de las funcionalidades. Nunca se envía el contenido de las sesiones, nombres de archivos, entradas de herramientas ni información personal. Para desactivarla: @@ -292,10 +319,10 @@ FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai | [Primeros pasos](docs/getting-started.mdx) | Instalación y primeros pasos | | [Políticas integradas](docs/built-in-policies.mdx) | Las 39 políticas integradas con sus parámetros | | [Políticas personalizadas](docs/custom-policies.mdx) | Escribe tus propias políticas | -| [Configuración](docs/configuration.mdx) | Formato del archivo de configuración y combinación de niveles | -| [Panel de control](docs/dashboard.mdx) | Monitorea sesiones y revisa la actividad de las políticas | +| [Configuración](docs/configuration.mdx) | Formato del archivo de configuración y fusión de ámbitos | +| [Panel de control](docs/dashboard.mdx) | Monitoriza sesiones y revisa la actividad de las políticas | | [Arquitectura](docs/architecture.mdx) | Cómo funciona el sistema de hooks | -| [Testing](docs/testing.mdx) | Ejecución de pruebas y creación de nuevas | +| [Testing](docs/testing.mdx) | Ejecución de pruebas y escritura de nuevas | ### Ejecutar la documentación localmente @@ -304,7 +331,7 @@ docker build -f Dockerfile.docs -t failproofai-docs . docker run --rm -p 3000:3000 failproofai-docs ``` -Abre el sitio de documentación Mintlify en `http://localhost:3000`. El contenedor detecta cambios si montas el directorio de documentación: +Abre el sitio de documentación de Mintlify en `http://localhost:3000`. El contenedor detecta cambios si montas el directorio de documentación: ```bash docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs @@ -314,7 +341,7 @@ docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs ## Nota para colaboradores de failproofai -El archivo `.claude/settings.json` de este repositorio usa `bun ./bin/failproofai.mjs --hook ` en lugar del comando estándar `npx -y failproofai`. Esto se debe a que ejecutar `npx -y failproofai` dentro del propio proyecto failproofai genera un conflicto de autoreferencia. +El archivo `.claude/settings.json` de este repositorio usa `bun ./bin/failproofai.mjs --hook ` en lugar del comando estándar `npx -y failproofai`. Esto se debe a que ejecutar `npx -y failproofai` dentro del propio proyecto failproofai genera un conflicto de auto-referencia. Para todos los demás repositorios, el enfoque recomendado es `npx -y failproofai`, instalado mediante: @@ -322,7 +349,7 @@ Para todos los demás repositorios, el enfoque recomendado es `npx -y failproofa failproofai policies --install --scope project ``` -## Contribuir +## Cómo contribuir Consulta [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/docs/i18n/README.fr.md b/docs/i18n/README.fr.md index 5ce129d2..c69dfe50 100644 --- a/docs/i18n/README.fr.md +++ b/docs/i18n/README.fr.md @@ -23,7 +23,7 @@ **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) -La manière la plus simple de gérer les politiques qui maintiennent vos agents IA fiables, concentrés sur leurs tâches et autonomes — pour **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(bêta)_ et l'**Agents SDK**. +La façon la plus simple de gérer des politiques qui maintiennent vos agents IA fiables, concentrés sur leurs tâches et autonomes — pour **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(bêta)_, **Cursor Agent** _(bêta)_, **OpenCode** _(bêta)_, **Pi** _(bêta)_, **Gemini CLI** _(bêta)_ et le **Agents SDK**.

Failproof AI en action @@ -50,15 +50,42 @@ La manière la plus simple de gérer les politiques qui maintiennent vos agents        - + d'autres à venir + + + + Cursor Agent + + +

+

+ + + + OpenCode + + +        + + + + Pi + + +        + + + + Gemini CLI + +

-> Installez les hooks pour un, deux ou les trois CLIs : `failproofai policies --install --cli copilot` (ou `--cli claude codex copilot`). Omettez `--cli` pour détecter automatiquement les CLIs installés et être invité à choisir. **La prise en charge de GitHub Copilot CLI est en bêta.** +> Installez les hooks pour l'un ou une combinaison quelconque : `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. **La prise en charge de GitHub Copilot CLI, Cursor Agent, OpenCode, Pi et Gemini CLI est en bêta — les tests sont en cours.** -- **39 politiques intégrées** - Détectez les modes de défaillance courants des agents dès le départ. Bloquez les commandes destructrices, empêchez les fuites de secrets, maintenez les agents dans les limites du projet, détectez les boucles, et bien plus encore. -- **Politiques personnalisées** - Écrivez vos propres règles de fiabilité en JavaScript. Utilisez l'API `allow`/`deny`/`instruct` pour imposer des conventions, prévenir la dérive, contrôler les opérations ou vous intégrer à des systèmes externes. -- **Configuration simplifiée** - Ajustez n'importe quelle politique sans écrire de code. Définissez des listes d'autorisation, des branches protégées et des seuils par projet ou globalement. La configuration à trois niveaux est fusionnée automatiquement. -- **Agent Monitor** - Voyez ce que vos agents ont fait en votre absence. Parcourez les sessions, inspectez chaque appel d'outil et examinez précisément où les politiques se sont déclenchées. +- **39 politiques intégrées** - Détectez les modes d'échec courants des agents dès l'installation. Bloquez les commandes destructives, prévenez les fuites de secrets, maintenez les agents dans les limites du projet, détectez les boucles, et bien plus encore. +- **Politiques personnalisées** - Rédigez vos propres règles de fiabilité en JavaScript. Utilisez l'API `allow`/`deny`/`instruct` pour appliquer des conventions, prévenir les dérives, contrôler les opérations ou vous intégrer à des systèmes externes. +- **Configuration simplifiée** - Ajustez n'importe quelle politique sans écrire de code. Définissez des listes d'autorisation, des branches protégées et des seuils par projet ou globalement. Les trois niveaux de configuration sont fusionnés automatiquement. +- **Moniteur d'agents** - Voyez ce que vos agents ont fait pendant votre absence. Parcourez les sessions, inspectez chaque appel d'outil et examinez exactement où les politiques se sont déclenchées. Tout s'exécute localement — aucune donnée ne quitte votre machine. @@ -67,7 +94,7 @@ Tout s'exécute localement — aucune donnée ne quitte votre machine. ## Prérequis - Node.js >= 20.9.0 -- Bun >= 1.3.0 (facultatif — nécessaire uniquement pour le développement ou la compilation depuis les sources) +- Bun >= 1.3.0 (optionnel — uniquement nécessaire pour le développement / la compilation depuis les sources) --- @@ -89,7 +116,7 @@ bun add -g failproofai failproofai policies --install ``` -Écrit les entrées de hook dans `~/.claude/settings.json`. Claude Code invoquera désormais failproofai avant et après chaque appel d'outil. +Écrit les entrées de hooks dans `~/.claude/settings.json`. Claude Code invoquera désormais failproofai avant et après chaque appel d'outil. ### 2. Lancer le tableau de bord @@ -111,11 +138,11 @@ failproofai policies ### Niveaux de portée -| Portée | Commande | Fichier modifié | -|-------|---------|-----------------| -| Global (par défaut) | `failproofai policies --install` | `~/.claude/settings.json` | +| Portée | Commande | Emplacement d'écriture | +|--------|---------|-----------------| +| Globale (par défaut) | `failproofai policies --install` | `~/.claude/settings.json` | | Projet | `failproofai policies --install --scope project` | `.claude/settings.json` | -| Local | `failproofai policies --install --scope local` | `.claude/settings.local.json` | +| Locale | `failproofai policies --install --scope local` | `.claude/settings.local.json` | ### Installer des politiques spécifiques @@ -135,7 +162,7 @@ failproofai policies --uninstall --scope project ## Configuration -La configuration des politiques se trouve dans `~/.failproofai/policies-config.json` (global) ou `.failproofai/policies-config.json` dans votre projet (par projet). +La configuration des politiques se trouve dans `~/.failproofai/policies-config.json` (globale) ou `.failproofai/policies-config.json` dans votre projet (par projet). ```json { @@ -168,7 +195,7 @@ La configuration des politiques se trouve dans `~/.failproofai/policies-config.j } ``` -**Trois niveaux de configuration** sont fusionnés automatiquement (projet → local → global). Consultez [docs/configuration.mdx](docs/configuration.mdx) pour les règles de fusion complètes. +**Les trois niveaux de configuration** sont fusionnés automatiquement (projet → local → global). Consultez [docs/configuration.mdx](docs/configuration.mdx) pour les règles de fusion complètes. --- @@ -178,29 +205,29 @@ La configuration des politiques se trouve dans `~/.failproofai/policies-config.j |--------|-------------|:---:| | `block-sudo` | Empêche les agents d'exécuter des commandes système privilégiées | `allowPatterns` | | `block-rm-rf` | Empêche la suppression récursive accidentelle de fichiers | `allowPaths` | -| `block-curl-pipe-sh` | Empêche les agents de diriger des scripts non fiables vers le shell | | +| `block-curl-pipe-sh` | Empêche les agents de rediriger des scripts non fiables vers le shell | | | `block-failproofai-commands` | Empêche la désinstallation automatique | | -| `sanitize-jwt` | Empêche les jetons JWT de fuir dans le contexte de l'agent | | -| `sanitize-api-keys` | Empêche les clés API de fuir dans le contexte de l'agent | `additionalPatterns` | -| `sanitize-connection-strings` | Empêche les identifiants de base de données de fuir dans le contexte de l'agent | | +| `sanitize-jwt` | Empêche les jetons JWT de fuiter dans le contexte de l'agent | | +| `sanitize-api-keys` | Empêche les clés API de fuiter dans le contexte de l'agent | `additionalPatterns` | +| `sanitize-connection-strings` | Empêche les identifiants de base de données de fuiter dans le contexte de l'agent | | | `sanitize-private-key-content` | Masque les blocs de clés privées PEM dans la sortie | | | `sanitize-bearer-tokens` | Masque les jetons Authorization Bearer dans la sortie | | | `block-env-files` | Empêche les agents de lire les fichiers .env | | | `protect-env-vars` | Empêche les agents d'afficher les variables d'environnement | | | `block-read-outside-cwd` | Maintient les agents dans les limites du projet | `allowPaths` | | `block-secrets-write` | Empêche les écritures dans les fichiers de clés privées et de certificats | `additionalPatterns` | -| `block-push-master` | Empêche les pushs accidentels vers main/master | `protectedBranches` | -| `block-work-on-main` | Maintient les agents hors des branches protégées | `protectedBranches` | +| `block-push-master` | Empêche les poussées accidentelles vers main/master | `protectedBranches` | +| `block-work-on-main` | Empêche les agents de travailler sur les branches protégées | `protectedBranches` | | `block-force-push` | Empêche `git push --force` | | -| `warn-git-amend` | Avertit les agents avant de modifier des commits | | -| `warn-git-stash-drop` | Avertit les agents avant de supprimer des stashes | | +| `warn-git-amend` | Rappelle aux agents avant de modifier des commits | | +| `warn-git-stash-drop` | Rappelle aux agents avant de supprimer des stashs | | | `warn-all-files-staged` | Détecte les `git add -A` accidentels | | -| `warn-destructive-sql` | Détecte les instructions DROP/DELETE SQL avant leur exécution | | -| `warn-schema-alteration` | Détecte les ALTER TABLE avant leur exécution | | +| `warn-destructive-sql` | Détecte les instructions SQL DROP/DELETE avant exécution | | +| `warn-schema-alteration` | Détecte les ALTER TABLE avant exécution | | | `warn-large-file-write` | Détecte les écritures de fichiers anormalement volumineuses | `thresholdKb` | | `warn-package-publish` | Détecte les `npm publish` accidentels | | -| `warn-background-process` | Détecte les lancements de processus en arrière-plan non intentionnels | | -| `warn-global-package-install` | Détecte les installations de paquets globaux non intentionnelles | | +| `warn-background-process` | Détecte les lancements involontaires de processus en arrière-plan | | +| `warn-global-package-install` | Détecte les installations involontaires de paquets globaux | | | …et plus encore | | | Détails complets des politiques et référence des paramètres : [docs/built-in-policies.mdx](docs/built-in-policies.mdx) @@ -209,7 +236,7 @@ Détails complets des politiques et référence des paramètres : [docs/built-in ## Politiques personnalisées -Écrivez vos propres politiques pour maintenir les agents fiables et concentrés sur leurs tâches : +Rédigez vos propres politiques pour maintenir les agents fiables et concentrés sur leurs tâches : ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -240,7 +267,7 @@ failproofai policies --install --custom ./my-policies.js | `allow()` | Autorise l'opération | | `allow(message)` | Autorise et envoie un contexte informatif à Claude | | `deny(message)` | Bloque l'opération ; le message est affiché à Claude | -| `instruct(message)` | Ajoute du contexte au prompt de Claude ; ne bloque pas | +| `instruct(message)` | Ajoute du contexte à l'invite de Claude ; ne bloque pas | ### Objet de contexte (`ctx`) @@ -254,11 +281,11 @@ failproofai policies --install --custom ./my-policies.js | `session.sessionId` | `string` | Identifiant de session | | `session.transcriptPath` | `string` | Chemin vers le fichier de transcription de la session | -Les hooks personnalisés prennent en charge les imports locaux transitifs, async/await et l'accès à `process.env`. Les erreurs sont non bloquantes (consignées dans `~/.failproofai/hook.log`, les politiques intégrées continuent de s'exécuter). Consultez [docs/custom-hooks.mdx](docs/custom-hooks.mdx) pour le guide complet. +Les hooks personnalisés prennent en charge les imports locaux transitifs, async/await et l'accès à `process.env`. Les erreurs sont en mode fail-open (consignées dans `~/.failproofai/hook.log`, les politiques intégrées continuent). Consultez [docs/custom-hooks.mdx](docs/custom-hooks.mdx) pour le guide complet. -### Politiques basées sur des conventions +### Politiques basées sur les conventions -Déposez des fichiers `*policies.{js,mjs,ts}` dans `.failproofai/policies/` et ils sont automatiquement chargés — aucun indicateur ni modification de configuration n'est nécessaire. Committez le répertoire dans git et chaque membre de l'équipe bénéficie automatiquement des mêmes standards de qualité. +Déposez des fichiers `*policies.{js,mjs,ts}` dans `.failproofai/policies/` et ils sont automatiquement chargés — aucun indicateur ni modification de configuration n'est nécessaire. Commitez le répertoire dans git et chaque membre de l'équipe bénéficie automatiquement des mêmes standards de qualité. ```text # Niveau projet — commité dans git, partagé avec l'équipe @@ -269,13 +296,13 @@ Déposez des fichiers `*policies.{js,mjs,ts}` dans `.failproofai/policies/` et i ~/.failproofai/policies/my-policies.mjs ``` -Les deux niveaux sont chargés (union). Les fichiers sont chargés par ordre alphabétique dans chaque répertoire. Préfixez avec `01-`, `02-`, etc. pour contrôler l'ordre. À mesure que votre équipe découvre de nouveaux modes de défaillance, ajoutez une politique et poussez — tout le monde reçoit la mise à jour au prochain pull. Consultez [examples/convention-policies/](examples/convention-policies/) pour des exemples prêts à l'emploi. +Les deux niveaux sont chargés (union). Les fichiers sont chargés par ordre alphabétique dans chaque répertoire. Préfixez avec `01-`, `02-`, etc. pour contrôler l'ordre. Au fur et à mesure que votre équipe découvre de nouveaux modes d'échec, ajoutez une politique et poussez — tout le monde reçoit la mise à jour au prochain pull. Consultez [examples/convention-policies/](examples/convention-policies/) pour des exemples prêts à l'emploi. --- ## Télémétrie -Failproof AI collecte des données de télémétrie d'utilisation anonymes via PostHog afin de comprendre l'utilisation des fonctionnalités. Aucun contenu de session, nom de fichier, entrée d'outil ou information personnelle n'est jamais envoyé. +Failproof AI collecte des données de télémétrie d'utilisation anonymes via PostHog afin de comprendre l'utilisation des fonctionnalités. Aucun contenu de session, nom de fichier, entrée d'outil ni information personnelle n'est jamais envoyé. Pour la désactiver : @@ -289,10 +316,10 @@ FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai | Guide | Description | |-------|-------------| -| [Démarrage](docs/getting-started.mdx) | Installation et premiers pas | +| [Démarrage](docs/getting-started.mdx) | Installation et premières étapes | | [Politiques intégrées](docs/built-in-policies.mdx) | Les 39 politiques intégrées avec leurs paramètres | -| [Politiques personnalisées](docs/custom-policies.mdx) | Écrire vos propres politiques | -| [Configuration](docs/configuration.mdx) | Format des fichiers de configuration et fusion des portées | +| [Politiques personnalisées](docs/custom-policies.mdx) | Rédigez vos propres politiques | +| [Configuration](docs/configuration.mdx) | Format du fichier de configuration et fusion des niveaux | | [Tableau de bord](docs/dashboard.mdx) | Surveiller les sessions et examiner l'activité des politiques | | [Architecture](docs/architecture.mdx) | Fonctionnement du système de hooks | | [Tests](docs/testing.mdx) | Exécuter les tests et en écrire de nouveaux | @@ -304,7 +331,7 @@ docker build -f Dockerfile.docs -t failproofai-docs . docker run --rm -p 3000:3000 failproofai-docs ``` -Ouvre le site de documentation Mintlify à l'adresse `http://localhost:3000`. Le conteneur surveille les modifications si vous montez le répertoire de documentation : +Ouvre le site de documentation Mintlify sur `http://localhost:3000`. Le conteneur surveille les modifications si vous montez le répertoire de documentation : ```bash docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs @@ -312,17 +339,17 @@ docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs --- -## Note pour les contributeurs de failproofai +## Note pour les contributeurs failproofai Le fichier `.claude/settings.json` de ce dépôt utilise `bun ./bin/failproofai.mjs --hook ` au lieu de la commande standard `npx -y failproofai`. En effet, exécuter `npx -y failproofai` à l'intérieur du projet failproofai lui-même crée un conflit d'auto-référence. -Pour tous les autres dépôts, l'approche recommandée est `npx -y failproofai`, installé via : +Pour tous les autres dépôts, l'approche recommandée est `npx -y failproofai`, installée via : ```bash failproofai policies --install --scope project ``` -## Contribuer +## Contribution Consultez [CONTRIBUTING.md](CONTRIBUTING.md). @@ -334,4 +361,4 @@ Consultez [LICENSE](LICENSE). --- -Conçu et maintenu par **ExosphereHost : Reliability Research Lab for Your Agents**. Nous aidons les entreprises et les startups à améliorer la fiabilité de leurs agents IA grâce à nos propres agents, logiciels et expertise. Pour en savoir plus, visitez [exosphere.host](https://exosphere.host). +Développé et maintenu par **ExosphereHost : Reliability Research Lab for Your Agents**. Nous aidons les entreprises et les startups à améliorer la fiabilité de leurs agents IA grâce à nos propres agents, logiciels et expertises. En savoir plus sur [exosphere.host](https://exosphere.host). diff --git a/docs/i18n/README.he.md b/docs/i18n/README.he.md index 8183c2b3..72ededd7 100644 --- a/docs/i18n/README.he.md +++ b/docs/i18n/README.he.md @@ -25,13 +25,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) -הדרך הקלה ביותר לנהל מדיניות שמשמרות את סוכני ה-AI שלך אמינים, ממוקדים והפועלים באופן עצמאי - עבור **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(בטא)_ והמערך **Agents SDK**. +הדרך הקלה ביותר לנהל מדיניות שמשמרת את סוכניך בינות מהימנים, ממוקדים וריצים באופן אוטונומי - עבור **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(beta)_, **Cursor Agent** _(beta)_, **OpenCode** _(beta)_, **Pi** _(beta)_, **Gemini CLI** _(beta)_ וה-**Agents SDK**.

Failproof AI בפעולה

-## CLIs של סוכנים תומכים +## סוכני CLI נתמכים

@@ -52,28 +52,55 @@        - + עוד בקרוב + + + + Cursor Agent + + +

+

+ + + + OpenCode + + +        + + + + Pi + + +        + + + + Gemini CLI + +

-> התקן hookים לאחד, שניים או שלושתם: `failproofai policies --install --cli copilot` (או `--cli claude codex copilot`). השמט את `--cli` לגילוי אוטומטי של CLIs מותקנים והודעה לאישור. **תמיכת GitHub Copilot CLI נמצאת בבטא.** +> התקן hooks לאחד או לשילוב כלשהו: `failproofai policies --install --cli opencode pi gemini` (או `--cli claude codex copilot cursor opencode pi gemini`). השמט `--cli` לגילוי אוטומטי של CLI מותקנים וקבלת הנחיות. **תמיכת GitHub Copilot CLI, Cursor Agent, OpenCode, Pi ו-Gemini CLI נמצאת בגרסת בטא — בדיקות מתמשכות.** -- **39 מדיניות מובנות** - תפס מצבי כשל נפוצים של סוכנים מחוץ לקופסה. חסום פקודות הרסניות, מנע דליפת סודות, שמור סוכנים בתוך גבולות פרויקט, גלה לולאות ועוד. -- **מדיניות מותאמת אישית** - כתוב את כללי האמינות שלך ב-JavaScript. השתמש ב-API `allow`/`deny`/`instruct` כדי לאכוף קונוונציות, למנוע סטייה, להגביל פעולות או להשתלב עם מערכות חיצוניות. -- **תצורה קלה** - כוונן כל מדיניות ללא כתיבת קוד. הגדר רשימות מאושרות, ענפים מוגנים, סף לפי פרויקט או בעולם. תצורה תלת-היקף מתמזגת באופן אוטומטי. -- **צג סוכן** - ראה מה סוכניך עשו בזמן שהיית בחוץ. עיין בהפעלות, בדוק כל קריאת כלי, וסקור בדיוק היכן מדיניות הופעלו. +- **39 מדיניות מובנית** - תפס מצבי כשל נפוצים של סוכן תיכף. חסום פקודות הרסניות, מנע דליפת סודות, שמור סוכנים בתוך גבולות הפרוייקט, גלה לולאות ועוד. +- **מדיניות מותאמת אישית** - כתוב חוקי אמינות משלך ב-JavaScript. השתמש ב-API `allow`/`deny`/`instruct` לכפיית קונוונציות, מניעת סטייה, שערי פעולות או אינטגרציה עם מערכות חיצוניות. +- **תצורה קלה** - כוונן כל מדיניות ללא כתיבת קוד. קבע allowlists, ענפים מוגנים, סף לכל פרוייקט או באופן גלובלי. שלוש היקפי תצורה מתמזגים באופן אוטומטי. +- **Agent Monitor** - ראה מה עשו סוכניך בזמן שהיית בחוץ. עיין בהפעלות, בדוק כל קריאת כלי, ובדוק בדיוק איפה מדיניות הופעלה. -הכל פועל מקומית - אף נתון לא משאיר את המכונה שלך. +הכל יעבוד באופן מקומי - שום מידע לא משאיר את המכונה שלך. --- ## דרישות - Node.js >= 20.9.0 -- Bun >= 1.3.0 (אופציונלי - נדרש רק לפיתוח / בנייה מהמקור) +- Bun >= 1.3.0 (אופציונלי - נדרש רק לפיתוח / בנייה מקוד מקור) --- -## התקנה +## התקן ```bash npm install -g failproofai @@ -85,15 +112,15 @@ bun add -g failproofai ## התחלה מהירה -### 1. הפעל מדיניות בעולם +### 1. הפעל מדיניות באופן גלובלי ```bash failproofai policies --install ``` -כותב ערכי hook לתוך `~/.claude/settings.json`. Claude Code יהפוך failproofai לפני ואחרי כל קריאת כלי. +כותב ערכי hook ל-`~/.claude/settings.json`. Claude Code כעת יגיד ל-failproofai להפעיל לפני ואחרי כל קריאת כלי. -### 2. הפעל את לוח הבקרה +### 2. הפעל את לוח השליטה ```bash failproofai @@ -113,10 +140,10 @@ failproofai policies ### היקפים -| היקף | פקודה | איתם הוא כותב | +| היקף | פקודה | איפה זה כותב | |-------|---------|-----------------| -| עולמי (ברירת מחדל) | `failproofai policies --install` | `~/.claude/settings.json` | -| פרויקט | `failproofai policies --install --scope project` | `.claude/settings.json` | +| גלובלי (ברירת מחדל) | `failproofai policies --install` | `~/.claude/settings.json` | +| פרוייקט | `failproofai policies --install --scope project` | `.claude/settings.json` | | מקומי | `failproofai policies --install --scope local` | `.claude/settings.local.json` | ### התקן מדיניות ספציפיות @@ -129,7 +156,7 @@ failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ```bash failproofai policies --uninstall -# או לגבי היקף ספציפי: +# או עבור היקף ספציפי: failproofai policies --uninstall --scope project ``` @@ -137,7 +164,7 @@ failproofai policies --uninstall --scope project ## תצורה -תצורת המדיניות נמצאת ב-`~/.failproofai/policies-config.json` (עולמי) או `.failproofai/policies-config.json` בפרויקט שלך (לכל פרויקט). +תצורת מדיניות חיה ב-`~/.failproofai/policies-config.json` (גלובלי) או ב-`.failproofai/policies-config.json` בפרוייקט שלך (לכל פרוייקט). ```json { @@ -160,7 +187,7 @@ failproofai policies --uninstall --scope project }, "sanitize-api-keys": { "additionalPatterns": [ - { "regex": "myco_[A-Za-z0-9]{32}", "label": "מפתח API של MyCo" } + { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" } ] }, "warn-large-file-write": { @@ -170,60 +197,60 @@ failproofai policies --uninstall --scope project } ``` -**שלוש היקפי תצורה** מתמזגות באופן אוטומטי (פרויקט → מקומי → עולמי). ראה [docs/configuration.mdx](docs/configuration.mdx) לכללי מיזוג מלאים. +**שלוש היקפי תצורה** מתמזגים באופן אוטומטי (פרוייקט → מקומי → גלובלי). ראה [docs/configuration.mdx](docs/configuration.mdx) לכללי מיזוג מלאים. --- -## מדיניות מובנות +## מדיניות מובנית -| מדיניות | תיאור | ניתן להגדיר | +| מדיניות | תיאור | ניתן להתאמה אישית | |--------|-------------|:---:| -| `block-sudo` | מנע מסוכנים הפעלת פקודות מערכת מיוחסות | `allowPatterns` | +| `block-sudo` | מנע סוכנים מהפעלת פקודות מערכת מובחרות | `allowPatterns` | | `block-rm-rf` | מנע מחיקת קבצים רקורסיבית בשוגג | `allowPaths` | -| `block-curl-pipe-sh` | מנע מסוכנים צנרור סקריפטים לא אמינים לשל | | +| `block-curl-pipe-sh` | מנע סוכנים מהעברת סקריפטים לא מהימנים לשל | | | `block-failproofai-commands` | מנע הסרה עצמית | | -| `sanitize-jwt` | עצור JWT tokens מלהדיף לתוך הקשר סוכן | | -| `sanitize-api-keys` | עצור API keys מלהדיף לתוך הקשר סוכן | `additionalPatterns` | -| `sanitize-connection-strings` | עצור credentials של בסיס נתונים מלהדיף לתוך הקשר סוכן | | -| `sanitize-private-key-content` | הסתר בלוקים של מפתח פרטי PEM מהפלט | | -| `sanitize-bearer-tokens` | הסתר Bearer tokens של Authorization מהפלט | | -| `block-env-files` | שמור סוכנים מקריאת קובצי .env | | -| `protect-env-vars` | מנע מסוכנים הדפסת משתני סביבה | | -| `block-read-outside-cwd` | שמור סוכנים בתוך גבולות פרויקט | `allowPaths` | -| `block-secrets-write` | מנע כתיבות לקבצי מפתח פרטי ותעודות | `additionalPatterns` | -| `block-push-master` | מנע דחיפות בשוגג לעיקר/master | `protectedBranches` | -| `block-work-on-main` | שמור סוכנים מעל ענפים מוגנים | `protectedBranches` | +| `sanitize-jwt` | עצור אסימוני JWT מדליפים להקשר הסוכן | | +| `sanitize-api-keys` | עצור מפתחות API מדליפים להקשר הסוכן | `additionalPatterns` | +| `sanitize-connection-strings` | עצור אישורי מסד נתונים מדליפים להקשר הסוכן | | +| `sanitize-private-key-content` | הסתר בלוקים פרטיים PEM מהפלט | | +| `sanitize-bearer-tokens` | הסתר אסימוני Authorization Bearer מהפלט | | +| `block-env-files` | שמור סוכנים מקריאת קבצי .env | | +| `protect-env-vars` | מנע סוכנים מהדפסת משתני סביבה | | +| `block-read-outside-cwd` | שמור סוכנים בתוך גבולות הפרוייקט | `allowPaths` | +| `block-secrets-write` | מנע כתיבות לקבצי מפתח פרטיים ותעודות | `additionalPatterns` | +| `block-push-master` | מנע דחיפות בשוגג ל-main/master | `protectedBranches` | +| `block-work-on-main` | שמור סוכנים מענפים מוגנים | `protectedBranches` | | `block-force-push` | מנע `git push --force` | | -| `warn-git-amend` | הזכר סוכנים לפני שינוי commits | | -| `warn-git-stash-drop` | הזכר סוכנים לפני הורדת stashes | | -| `warn-all-files-staged` | תפס `git add -A` בשוגג | | -| `warn-destructive-sql` | תפס DROP/DELETE SQL לפני ביצוע | | -| `warn-schema-alteration` | תפס ALTER TABLE לפני ביצוע | | -| `warn-large-file-write` | תפס כתיבות קובץ גדולות באופן בלתי צפוי | `thresholdKb` | -| `warn-package-publish` | תפס `npm publish` בשוגג | | -| `warn-background-process` | תפס הפעלות תהליך בתוך כדור בלא כוונה | | -| `warn-global-package-install` | תפס התקנות חבילה גלובליות בלא כוונה | | +| `warn-git-amend` | הזכר סוכנים לפני תיקון commits | | +| `warn-git-stash-drop` | הזכר סוכנים לפני זריקת stashes | | +| `warn-all-files-staged` | תופס `git add -A` בשוגג | | +| `warn-destructive-sql` | תופס DROP/DELETE SQL לפני ביצוע | | +| `warn-schema-alteration` | תופס ALTER TABLE לפני ביצוע | | +| `warn-large-file-write` | תופס כתיבות קבצים גדולות בהפתעה | `thresholdKb` | +| `warn-package-publish` | תופס `npm publish` בשוגג | | +| `warn-background-process` | תופס השקות תהליכים רקע לא מכוונות | | +| `warn-global-package-install` | תופס התקנות חבילה גלובליות לא מכוונות | | | …ועוד | | | -פרטי מדיניות מלאים והפניה של פרמטרים: [docs/built-in-policies.mdx](docs/built-in-policies.mdx) +פרטי מדיניות מלאים והפניית פרמטרים: [docs/built-in-policies.mdx](docs/built-in-policies.mdx) --- ## מדיניות מותאמת אישית -כתוב את המדיניות שלך כדי לשמור סוכנים אמינים וממוקדים: +כתוב מדיניות משלך לשמירה על סוכנים אמינים וממוקדים: ```js import { customPolicies, allow, deny, instruct } from "failproofai"; customPolicies.add({ name: "no-production-writes", - description: "חסום כתיבות לנתיבים המכילים 'production'", + description: "חסום כתיבות לנתיבים המכילים production", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow(); const path = ctx.toolInput?.file_path ?? ""; - if (path.includes("production")) return deny("כתיבות לנתיבים production חסומות"); + if (path.includes("production")) return deny("כתיבות לנתיבי production חסומות"); return allow(); }, }); @@ -239,47 +266,47 @@ failproofai policies --install --custom ./my-policies.js | פונקציה | השפעה | |----------|--------| -| `allow()` | אישור הפעולה | -| `allow(message)` | אישור והשלח הקשר מידע ל-Claude | +| `allow()` | אפשר את הפעולה | +| `allow(message)` | אפשר וישלח הקשר מידע ל-Claude | | `deny(message)` | חסום את הפעולה; הודעה מוצגת ל-Claude | -| `instruct(message)` | הוסף הקשר לפרומפט של Claude; אל תחסום | +| `instruct(message)` | הוסף הקשר לפרומפט של Claude; לא חוסם | ### אובייקט הקשר (`ctx`) | שדה | סוג | תיאור | |-------|------|-------------| -| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string` | כלי שמקראים (`"Bash"`, `"Write"`, `"Read"`, …) | -| `toolInput` | `object` | פרמטרי קלט של כלי | +| `eventType` | `string` | `PreToolUse`, `PostToolUse`, `Notification`, `Stop` | +| `toolName` | `string` | כלי בקריאה (`Bash`, `Write`, `Read`, …) | +| `toolInput` | `object` | פרמטרי קלט של הכלי | | `payload` | `object` | מטען אירוע גולמי מלא | -| `session.cwd` | `string` | ספרית עבודה של הפעלת Claude Code | +| `session.cwd` | `string` | ספריית עבודה של הפעלת Claude Code | | `session.sessionId` | `string` | מזהה הפעלה | -| `session.transcriptPath` | `string` | נתיב לקובץ תמלול של הפעלה | +| `session.transcriptPath` | `string` | נתיב לקובץ תמלול ההפעלה | -hookים מותאמים אישית תומכים בייבואים מקומיים טרנזיטיביים, async/await, וגישה ל-`process.env`. שגיאות פועלות בפתיחה בכשל (רשומות ב-`~/.failproofai/hook.log`, מדיניות מובנות ממשיכות). ראה [docs/custom-hooks.mdx](docs/custom-hooks.mdx) למדריך מלא. +hook מותאמים תומכים ייבוא מקומי טרנזיטיבי, async/await וגישה ל-`process.env`. שגיאות נפתחות בנדיבות (רשומות ל-`~/.failproofai/hook.log`, מדיניויות מובנית ממשיכות). ראה [docs/custom-hooks.mdx](docs/custom-hooks.mdx) לגיד המלא. -### מדיניות מבוססות קונוונציה +### מדיניויות מבוססות קונוונציה -הוסף קבצי `*policies.{js,mjs,ts}` לתוך `.failproofai/policies/` והם טוענים באופן אוטומטי — אף דגלים או שינויי תצורה לא נדרשים. בצע commit של הספרייה ל-git וכל חברי הצוות מקבלים את אותם סטנדרטים איכות באופן אוטומטי. +זרוק קבצי `*policies.{js,mjs,ts}` ל-`.failproofai/policies/` והם נטענים באופן אוטומטי — אין צורך בדגלים או שינויי תצורה. בצור את הספרייה ל-git וכל חברה בצוות מקבלת את אותם תקנים איכות באופן אוטומטי. ```text -# רמת פרויקט — committed ל-git, משותף עם הצוות +# רמת פרוייקט — מובהקת ל-git, משותפת עם הצוות .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# רמת משתמש — אישי, חל על כל הפרויקטים +# רמת משתמש — אישית, חלה על כל הפרוייקטים ~/.failproofai/policies/my-policies.mjs ``` -שתי הרמות טוענות (union). קבצים טוענים בסדר אלפביתי בתוך כל ספרייה. הוסף קידומת עם `01-`, `02-`, וכו' כדי לשלוט בסדר. כאשר הצוות שלך מגלה מצבי כשל חדשים, הוסף מדיניות ודחוף — כולם מקבלים את העדכון ב-pull הבא שלהם. ראה [examples/convention-policies/](examples/convention-policies/) לדוגמאות מוכנות לשימוש. +שתי הרמות נטענות (איחוד). קבצים נטענים בסדר אלפביתי בכל ספרייה. התחל עם `01-`, `02-` וכו' כדי לשלוט בסדר. כאשר הצוות שלך גילה מצבי כשל חדשים, הוסף מדיניות ודחוף — כולם מקבלים את העדכון ב-pull הבא שלהם. ראה [examples/convention-policies/](examples/convention-policies/) לדוגמאות מוכנות לשימוש. --- -## טלמטריה +## טלימטריה -Failproof AI אוסף טלמטריה שימוש אנונימית דרך PostHog כדי להבין שימוש בתכונות. תוכן הפעלה, שמות קבצים, קלטי כלים או מידע אישי לעולם לא נשלחים. +Failproof AI אוספת טלימטריה שימוש אנונימית דרך PostHog כדי להבין שימוש בתכונות. שום תוכן הפעלה, שמות קבצים, קלטי כלים או מידע אישי לא נשלחים אי פעם. -השבת זאת: +השבית זאת: ```bash FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai @@ -287,26 +314,26 @@ FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai --- -## תיעוד +## דוקומנטציה | מדריך | תיאור | |-------|-------------| -| [Getting Started](docs/getting-started.mdx) | התקנה ורגעים ראשונים | -| [Built-in Policies](docs/built-in-policies.mdx) | כל 39 מדיניות מובנות עם פרמטרים | -| [Custom Policies](docs/custom-policies.mdx) | כתוב את המדיניות שלך | +| [Getting Started](docs/getting-started.mdx) | התקנה וצעדים ראשונים | +| [Built-in Policies](docs/built-in-policies.mdx) | כל 39 מדיניויות מובנית עם פרמטרים | +| [Custom Policies](docs/custom-policies.mdx) | כתוב את המדיניויות שלך | | [Configuration](docs/configuration.mdx) | פורמט קובץ תצורה ומיזוג היקף | -| [Dashboard](docs/dashboard.mdx) | עקוב אחר הפעלות וסקור פעילות מדיניות | -| [Architecture](docs/architecture.mdx) | כיצד מערכת hook פועלת | -| [Testing](docs/testing.mdx) | הרץ בדיקות וכתוב חדשות | +| [Dashboard](docs/dashboard.mdx) | מנטור הפעלות וסקור פעילות מדיניות | +| [Architecture](docs/architecture.mdx) | איך מערכת ה-hook עובדת | +| [Testing](docs/testing.mdx) | הפעל בדיקות וכתוב חדשות | -### הרץ תיעוד מקומי +### הפעל docs באופן מקומי ```bash docker build -f Dockerfile.docs -t failproofai-docs . docker run --rm -p 3000:3000 failproofai-docs ``` -פותח את אתר Mintlify docs ב-`http://localhost:3000`. המיכל עוקב אחר שינויים אם אתה מעגן את ספרית ה-docs: +פותח את אתר ה-Mintlify docs ב-`http://localhost:3000`. הקונטיינר מתראה לשינויים אם אתה מעמיד את ספריית ה-docs: ```bash docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs @@ -316,9 +343,9 @@ docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs ## הערה לתורמי failproofai -ה-`.claude/settings.json` של repot זה משתמש ב-`bun ./bin/failproofai.mjs --hook ` במקום הפקודה `npx -y failproofai` הסטנדרטית. זה בגלל שהרצה של `npx -y failproofai` בתוך פרויקט failproofai עצמו יוצרת קונפליקט הסתמכות עצמית. +ה-`.claude/settings.json` של המאגר הזה משתמש ב-`bun ./bin/failproofai.mjs --hook ` במקום בפקודה `npx -y failproofai` הסטנדרטית. זה מכיוון שהפעלת `npx -y failproofai` בתוך פרוייקט failproofai עצמו יוצרת קונפליקט עצמי-הפניה. -עבור כל ה-repos האחרים, הגישה המומלצת היא `npx -y failproofai`, המותקנת דרך: +לכל המאגרים האחרים, הגישה המומלצת היא `npx -y failproofai`, המותקנת דרך: ```bash failproofai policies --install --scope project @@ -330,13 +357,14 @@ failproofai policies --install --scope project --- -## רישיון +## ראשון ראה [LICENSE](LICENSE). --- -בנוי ותוחזק על ידי **ExosphereHost: Reliability Research Lab for Your Agents**. אנחנו עוזרים לחברות ולסטארטאפים לשפר את אמינות סוכני ה-AI שלהם דרך הסוכנים, התוכנה והמומחיות שלנו. למד עוד ב-[exosphere.host](https://exosphere.host). +בנוי ותחזוקה על ידי **ExosphereHost: Reliability Research Lab for Your Agents**. אנחנו עוזרים לארגונים וסטארטאפים לשפר את האמינות של סוכניהם בינות דרך סוכנים, תוכנה ומומחיות משלנו. למד עוד ב-[exosphere.host](https://exosphere.host). +``` \ No newline at end of file diff --git a/docs/i18n/README.hi.md b/docs/i18n/README.hi.md index 8145abd2..501bccbb 100644 --- a/docs/i18n/README.hi.md +++ b/docs/i18n/README.hi.md @@ -23,10 +23,10 @@ **अनुवाद**: [简体中文](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) -अपने AI एजेंट्स को विश्वसनीय, केंद्रित और स्वायत्त रूप से चलाने के लिए नीतियों को प्रबंधित करने का सबसे आसान तरीका - **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(बीटा)_ & **Agents SDK** के लिए। +अपने AI एजेंट को विश्वसनीय, कार्य-केंद्रित और स्वायत्त रूप से चलाने वाली नीतियों को प्रबंधित करने का सबसे आसान तरीका - **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(बीटा)_, **Cursor Agent** _(बीटा)_, **OpenCode** _(बीटा)_, **Pi** _(बीटा)_, **Gemini CLI** _(बीटा)_ और **Agents SDK** के लिए।

- Failproof AI कार्यरत + Failproof AI कार्य में

## समर्थित एजेंट CLIs @@ -50,28 +50,55 @@        - + अन्य जल्द आने वाले हैं + + + + Cursor Agent + + +

+

+ + + + OpenCode + + +        + + + + Pi + + +        + + + + Gemini CLI + +

-> एक, दो, या तीनों के लिए हुक इंस्टॉल करें: `failproofai policies --install --cli copilot` (या `--cli claude codex copilot`)। `--cli` को छोड़ दें ताकि स्वचालित रूप से इंस्टॉल किए गए CLIs का पता लगाया जा सके और प्रेरित किया जा सके। **GitHub Copilot CLI समर्थन बीटा में है।** +> एक या कई संयोजन के लिए हुक इंस्टॉल करें: `failproofai policies --install --cli opencode pi gemini` (या `--cli claude codex copilot cursor opencode pi gemini`)। `--cli` छोड़ें तो स्वचालित रूप से इंस्टॉल किए गए CLIs का पता लगेगा और संकेत दिया जाएगा। **GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, और Gemini CLI समर्थन बीटा में है — परीक्षण जारी है।** -- **39 अंतर्निहित नीतियां** - सामान्य एजेंट विफलता मोड को बॉक्स से बाहर निकालें। विनाशकारी कमांड को ब्लॉक करें, गुप्त रिसाव को रोकें, एजेंट्स को प्रोजेक्ट सीमाओं के अंदर रखें, लूप का पता लगाएं, और बहुत कुछ। -- **कस्टम नीतियां** - JavaScript में अपने स्वयं की विश्वसनीयता नियम लिखें। `allow`/`deny`/`instruct` API का उपयोग करके सम्मेलन लागू करें, बहाव को रोकें, संचालन को गेट करें, या बाहरी सिस्टम के साथ एकीकृत करें। -- **आसान कॉन्फ़िगरेशन** - कोड लिखे बिना किसी भी नीति को ट्यून करें। allowlist, सुरक्षित शाखाएं, प्रति-प्रोजेक्ट या विश्व स्तर पर सीमा सेट करें। तीन-स्कोप कॉन्फ़िगरेशन स्वचालित रूप से मर्ज हो जाता है। -- **एजेंट मॉनिटर** - देखें कि आपके एजेंट्स आपके दूर रहते हुए क्या करते थे। सत्रों को ब्राउज़ करें, हर टूल कॉल का निरीक्षण करें, और बिल्कुल देखें कि नीतियां कहां कार्य करती हैं। +- **39 बिल्ट-इन नीतियां** - सामान्य एजेंट विफलता मोड को तुरंत पकड़ें। विनाशकारी आदेशों को ब्लॉक करें, गुप्त लीक को रोकें, एजेंट को प्रोजेक्ट सीमाओं के अंदर रखें, लूप का पता लगाएं और बहुत कुछ। +- **कस्टम नीतियां** - JavaScript में अपने स्वयं की विश्वसनीयता नियम लिखें। सम्मेलन लागू करने, बहाव रोकने, संचालन को गेट करने या बाहरी सिस्टम के साथ एकीकृत करने के लिए `allow`/`deny`/`instruct` API का उपयोग करें। +- **आसान कॉन्फ़िगरेशन** - कोड लिखे बिना किसी भी नीति को ट्यून करें। सफेदलिस्ट, संरक्षित शाखाएं, प्रति-प्रोजेक्ट या विश्व स्तर पर थ्रेशहोल्ड सेट करें। तीन-स्कोप कॉन्फ़िग स्वचालित रूप से मर्ज होता है। +- **एजेंट मॉनिटर** - देखें कि आपके एजेंट क्या करते थे जब आप दूर थे। सत्रों को ब्राउज़ करें, हर टूल कॉल का निरीक्षण करें, और देखें कि नीतियां कहां चलीं। -सब कुछ स्थानीय रूप से चलता है - कोई डेटा आपकी मशीन से बाहर नहीं जाता है। +सब कुछ स्थानीय रूप से चलता है - कोई डेटा आपकी मशीन से बाहर नहीं जाता। --- ## आवश्यकताएं - Node.js >= 20.9.0 -- Bun >= 1.3.0 (वैकल्पिक - केवल विकास / स्रोत से बनाने के लिए आवश्यक) +- Bun >= 1.3.0 (वैकल्पिक - केवल विकास / स्रोत से निर्माण के लिए आवश्यक) --- -## स्थापित करें +## इंस्टॉल करें ```bash npm install -g failproofai @@ -81,15 +108,15 @@ bun add -g failproofai --- -## त्वरित शुरुआत +## त्वरित प्रारंभ -### 1. नीतियों को विश्व स्तर पर सक्षम करें +### 1. वैश्विक रूप से नीतियों को सक्षम करें ```bash failproofai policies --install ``` -`~/.claude/settings.json` में हुक प्रविष्टियां लिखता है। Claude Code अब प्रत्येक टूल कॉल से पहले और बाद में failproofai को लागू करेगा। +`~/.claude/settings.json` में हुक प्रविष्टियां लिखता है। Claude Code अब प्रत्येक टूल कॉल से पहले और बाद में failproofai को आमंत्रित करेगा। ### 2. डैशबोर्ड लॉन्च करें @@ -97,9 +124,9 @@ failproofai policies --install failproofai ``` -`http://localhost:8020` खोलता है - सत्रों को ब्राउज़ करें, लॉग का निरीक्षण करें, नीतियों को प्रबंधित करें। +`http://localhost:8020` खोलता है - सत्रों को ब्राउज़ करें, लॉग का निरीक्षण करें, नीतियों का प्रबंधन करें। -### 3. जांचें कि क्या सक्रिय है +### 3. देखें कि क्या सक्रिय है ```bash failproofai policies @@ -107,17 +134,17 @@ failproofai policies --- -## नीति स्थापन +## नीति स्थापना ### स्कोप -| स्कोप | कमांड | कहाँ यह लिखता है | +| स्कोप | कमांड | जहां यह लिखता है | |-------|---------|-----------------| -| विश्व स्तर (डिफ़ॉल्ट) | `failproofai policies --install` | `~/.claude/settings.json` | +| वैश्विक (डिफ़ॉल्ट) | `failproofai policies --install` | `~/.claude/settings.json` | | प्रोजेक्ट | `failproofai policies --install --scope project` | `.claude/settings.json` | | स्थानीय | `failproofai policies --install --scope local` | `.claude/settings.local.json` | -### विशिष्ट नीतियां स्थापित करें +### विशिष्ट नीतियों को इंस्टॉल करें ```bash failproofai policies --install block-sudo block-rm-rf sanitize-api-keys @@ -133,9 +160,9 @@ failproofai policies --uninstall --scope project --- -## विन्यास +## कॉन्फ़िगरेशन -नीति विन्यास `~/.failproofai/policies-config.json` (विश्व स्तर) या आपके प्रोजेक्ट में `.failproofai/policies-config.json` (प्रति-प्रोजेक्ट) में रहता है। +नीति कॉन्फ़िगरेशन `~/.failproofai/policies-config.json` (वैश्विक) या आपके प्रोजेक्ट में `.failproofai/policies-config.json` (प्रति-प्रोजेक्ट) में रहती है। ```json { @@ -150,15 +177,15 @@ failproofai policies --uninstall --scope project "policyParams": { "block-sudo": { "allowPatterns": ["sudo systemctl status", "sudo journalctl"], - "hint": "sudo के बिना apt-get का उपयोग सीधे करें।" + "hint": "sudo के बिना सीधे apt-get का उपयोग करें।" }, "block-push-master": { "protectedBranches": ["main", "release", "prod"], - "hint": "इसके बजाय एक ताजा शाखा बनाने का प्रयास करें।" + "hint": "इसके बजाय एक नई शाखा बनाने का प्रयास करें।" }, "sanitize-api-keys": { "additionalPatterns": [ - { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API कुंजी" } + { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" } ] }, "warn-large-file-write": { @@ -168,39 +195,39 @@ failproofai policies --uninstall --scope project } ``` -**तीन विन्यास स्कोप** स्वचालित रूप से मर्ज हो जाते हैं (प्रोजेक्ट → स्थानीय → विश्व स्तर)। पूर्ण मर्ज नियमों के लिए [docs/configuration.mdx](docs/configuration.mdx) देखें। +**तीन कॉन्फ़िग स्कोप** स्वचालित रूप से मर्ज होते हैं (प्रोजेक्ट → स्थानीय → वैश्विक)। पूर्ण मर्ज नियमों के लिए [docs/configuration.mdx](docs/configuration.mdx) देखें। --- -## अंतर्निहित नीतियां +## बिल्ट-इन नीतियां -| नीति | विवरण | कॉन्फ़िगरेबल | +| नीति | विवरण | कॉन्फ़िगर योग्य | |--------|-------------|:---:| -| `block-sudo` | एजेंट्स को विशेषाधिकार प्राप्त सिस्टम कमांड चलाने से रोकें | `allowPatterns` | -| `block-rm-rf` | आकस्मिक पुनरावर्ती फ़ाइल विलोपन को रोकें | `allowPaths` | -| `block-curl-pipe-sh` | एजेंट्स को अविश्वसनीय स्क्रिप्ट को शेल में पाइप करने से रोकें | | -| `block-failproofai-commands` | स्व-स्थापना को रोकें | | -| `sanitize-jwt` | JWT टोकन को एजेंट संदर्भ में रिसाव से रोकें | | -| `sanitize-api-keys` | API कुंजी को एजेंट संदर्भ में रिसाव से रोकें | `additionalPatterns` | -| `sanitize-connection-strings` | डेटाबेस क्रेडेंशियल को एजेंट संदर्भ में रिसाव से रोकें | | +| `block-sudo` | एजेंट को विशेषाधिकार प्राप्त सिस्टम आदेश चलाने से रोकें | `allowPatterns` | +| `block-rm-rf` | आकस्मिक पुनरावर्ती फाइल विलोपन को रोकें | `allowPaths` | +| `block-curl-pipe-sh` | एजेंट को अविश्वस्त स्क्रिप्ट को शेल में पाइप करने से रोकें | | +| `block-failproofai-commands` | आत्म-स्थापना को रोकें | | +| `sanitize-jwt` | JWT टोकन को एजेंट संदर्भ में लीक होने से रोकें | | +| `sanitize-api-keys` | API कुंजियों को एजेंट संदर्भ में लीक होने से रोकें | `additionalPatterns` | +| `sanitize-connection-strings` | डेटाबेस क्रेडेंशियल को एजेंट संदर्भ में लीक होने से रोकें | | | `sanitize-private-key-content` | आउटपुट से PEM निजी कुंजी ब्लॉक को संपादित करें | | -| `sanitize-bearer-tokens` | आउटपुट से प्राधिकरण Bearer टोकन को संपादित करें | | -| `block-env-files` | एजेंट्स को .env फ़ाइलें पढ़ने से रखें | | -| `protect-env-vars` | एजेंट्स को पर्यावरण चर प्रिंट करने से रोकें | | -| `block-read-outside-cwd` | एजेंट्स को प्रोजेक्ट सीमाओं के अंदर रखें | `allowPaths` | -| `block-secrets-write` | निजी कुंजी और प्रमाणपत्र फ़ाइलों में लिखने को रोकें | `additionalPatterns` | -| `block-push-master` | मुख्य/मास्टर में आकस्मिक पुश को रोकें | `protectedBranches` | -| `block-work-on-main` | एजेंट्स को सुरक्षित शाखाओं से दूर रखें | `protectedBranches` | +| `sanitize-bearer-tokens` | आउटपुट से प्राधिकरण वाहक टोकन को संपादित करें | | +| `block-env-files` | एजेंट को .env फाइलों को पढ़ने से रोकें | | +| `protect-env-vars` | एजेंट को पर्यावरण चर प्रिंट करने से रोकें | | +| `block-read-outside-cwd` | एजेंट को प्रोजेक्ट सीमाओं के अंदर रखें | `allowPaths` | +| `block-secrets-write` | निजी कुंजी और प्रमाणपत्र फाइलों में लिखने से रोकें | `additionalPatterns` | +| `block-push-master` | मुख्य/मास्टर को आकस्मिक धकेलने से रोकें | `protectedBranches` | +| `block-work-on-main` | एजेंट को संरक्षित शाखाओं से दूर रखें | `protectedBranches` | | `block-force-push` | `git push --force` को रोकें | | -| `warn-git-amend` | कमिट संशोधित करने से पहले एजेंट्स को याद दिलाएं | | -| `warn-git-stash-drop` | स्टैश को छोड़ने से पहले एजेंट्स को याद दिलाएं | | +| `warn-git-amend` | एजेंट को कमिट संशोधित करने से पहले याद दिलाएं | | +| `warn-git-stash-drop` | एजेंट को स्टैश ड्रॉप करने से पहले याद दिलाएं | | | `warn-all-files-staged` | आकस्मिक `git add -A` को पकड़ें | | | `warn-destructive-sql` | DROP/DELETE SQL को निष्पादन से पहले पकड़ें | | -| `warn-schema-alteration` | ALTER TABLE को निष्पादन से पहले पकड़ें | | -| `warn-large-file-write` | अप्रत्याशित रूप से बड़ी फ़ाइल लिखने को पकड़ें | `thresholdKb` | +| `warn-schema-alteration` | निष्पादन से पहले ALTER TABLE को पकड़ें | | +| `warn-large-file-write` | अप्रत्याशित बड़ी फाइल लिखने को पकड़ें | `thresholdKb` | | `warn-package-publish` | आकस्मिक `npm publish` को पकड़ें | | -| `warn-background-process` | अनपेक्षित बैकग्राउंड प्रक्रिया लॉन्च को पकड़ें | | -| `warn-global-package-install` | अनपेक्षित वैश्विक पैकेज इंस्टॉल को पकड़ें | | +| `warn-background-process` | अनिच्छुक पृष्ठभूमि प्रक्रिया लॉन्च को पकड़ें | | +| `warn-global-package-install` | अनिच्छुक वैश्विक पैकेज इंस्टॉल को पकड़ें | | | …और अधिक | | | पूर्ण नीति विवरण और पैरामीटर संदर्भ: [docs/built-in-policies.mdx](docs/built-in-policies.mdx) @@ -209,14 +236,14 @@ failproofai policies --uninstall --scope project ## कस्टम नीतियां -एजेंट्स को विश्वसनीय और केंद्रित रखने के लिए अपनी स्वयं की नीतियां लिखें: +एजेंट को विश्वसनीय और कार्य-केंद्रित रखने के लिए अपनी स्वयं की नीतियां लिखें: ```js import { customPolicies, allow, deny, instruct } from "failproofai"; customPolicies.add({ name: "no-production-writes", - description: "'production' युक्त पथों में लिखने को ब्लॉक करें", + description: "उत्पादन युक्त पथों में लिखने को ब्लॉक करें", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow(); @@ -227,7 +254,7 @@ customPolicies.add({ }); ``` -इसके साथ स्थापित करें: +निम्नलिखित के साथ इंस्टॉल करें: ```bash failproofai policies --install --custom ./my-policies.js @@ -235,47 +262,47 @@ failproofai policies --install --custom ./my-policies.js ### निर्णय सहायक -| कार्य | प्रभाव | +| फंक्शन | प्रभाव | |----------|--------| | `allow()` | संचालन की अनुमति दें | | `allow(message)` | अनुमति दें और Claude को सूचनात्मक संदर्भ भेजें | -| `deny(message)` | संचालन को ब्लॉक करें; संदेश Claude को दिखाया गया | -| `instruct(message)` | Claude के प्रॉम्प्ट को संदर्भ जोड़ें; ब्लॉक नहीं करता है | +| `deny(message)` | संचालन को ब्लॉक करें; संदेश Claude को दिखाया जाता है | +| `instruct(message)` | Claude के संकेत में संदर्भ जोड़ें; ब्लॉक नहीं करता है | ### संदर्भ ऑब्जेक्ट (`ctx`) | फील्ड | प्रकार | विवरण | |-------|------|-------------| -| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string` | कॉल किया जा रहा टूल (`"Bash"`, `"Write"`, `"Read"`, …) | +| `eventType` | `string` | `PreToolUse`, `PostToolUse`, `Notification`, `Stop` | +| `toolName` | `string` | कहा जा रहा टूल (`Bash`, `Write`, `Read`, …) | | `toolInput` | `object` | टूल के इनपुट पैरामीटर | -| `payload` | `object` | पूर्ण कच्ची इवेंट पेलोड | +| `payload` | `object` | पूर्ण कच्ची घटना पेलोड | | `session.cwd` | `string` | Claude Code सत्र की कार्य निर्देशिका | | `session.sessionId` | `string` | सत्र पहचानकर्ता | -| `session.transcriptPath` | `string` | सत्र प्रतिलेख फ़ाइल का पथ | +| `session.transcriptPath` | `string` | सत्र प्रतिलेख फाइल का पथ | -कस्टम हुक transitive स्थानीय आयात, async/await, और `process.env` तक पहुंच का समर्थन करते हैं। त्रुटियां fail-open हैं (लॉग किए गए `~/.failproofai/hook.log`, अंतर्निहित नीतियां जारी रहती हैं)। पूर्ण मार्गदर्शन के लिए [docs/custom-hooks.mdx](docs/custom-hooks.mdx) देखें। +कस्टम हुक सकर्मक स्थानीय आयातों, async/await, और `process.env` तक पहुंच का समर्थन करते हैं। त्रुटियां खुली विफलता हैं (लॉग किया गया `~/.failproofai/hook.log`, बिल्ट-इन नीतियां जारी रहती हैं)। पूर्ण गाइड के लिए [docs/custom-hooks.mdx](docs/custom-hooks.mdx) देखें। ### सम्मेलन-आधारित नीतियां -`.failproofai/policies/` में `*policies.{js,mjs,ts}` फ़ाइलें छोड़ें और वे स्वचालित रूप से लोड होती हैं - कोई फ्लैग या कॉन्फ़िगरेशन परिवर्तन की आवश्यकता नहीं है। निर्देशिका को git में कमिट करें और हर टीम सदस्य को स्वचालित रूप से समान गुणवत्ता मानक मिलते हैं। +`.failproofai/policies/` में `*policies.{js,mjs,ts}` फाइलें डालें और वे स्वचालित रूप से लोड हो जाती हैं — कोई फ्लैग या कॉन्फ़िग परिवर्तन की आवश्यकता नहीं। निर्देशिका को git में कमिट करें और हर टीम सदस्य को स्वचालित रूप से समान गुणवत्ता मानदंड मिलते हैं। ```text # प्रोजेक्ट स्तर — git में कमिट किया गया, टीम के साथ साझा किया गया .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# उपयोगकर्ता स्तर — व्यक्तिगत, सभी प्रोजेक्ट्स पर लागू होता है +# उपयोगकर्ता स्तर — व्यक्तिगत, सभी प्रोजेक्ट पर लागू होता है ~/.failproofai/policies/my-policies.mjs ``` -दोनों स्तर लोड होते हैं (union)। फ़ाइलें प्रत्येक निर्देशिका के अंदर वर्णक्रम के आधार पर लोड होती हैं। आदेश को नियंत्रित करने के लिए `01-`, `02-`, आदि से उपसर्ग करें। जब आपकी टीम नई विफलता मोड को खोजती है, तो एक नीति जोड़ें और पुश करें — सभी को अपने अगले पुल पर अपडेट मिलता है। [examples/convention-policies/](examples/convention-policies/) में उपयोग के लिए तैयार उदाहरण देखें। +दोनों स्तर लोड होते हैं (यूनियन)। फाइलें प्रत्येक निर्देशिका के भीतर वर्णक्रम में लोड की जाती हैं। क्रम को नियंत्रित करने के लिए `01-`, `02-` आदि के साथ उपसर्ग करें। जब आपकी टीम नई विफलता मोड की खोज करती है, एक नीति जोड़ें और पुश करें — सभी को अगली पुल पर अपडेट मिल जाता है। तैयार-से-उपयोग के उदाहरणों के लिए [examples/convention-policies/](examples/convention-policies/) देखें। --- ## टेलीमेट्री -Failproof AI PostHog के माध्यम से गुमनाम उपयोग टेलीमेट्री एकत्र करता है ताकि सुविधा उपयोग को समझा जा सके। कोई सत्र सामग्री, फ़ाइल के नाम, टूल इनपुट, या व्यक्तिगत जानकारी कभी नहीं भेजी जाती है। +Failproof AI सुविधा उपयोग को समझने के लिए PostHog के माध्यम से गुमनाम उपयोग टेलीमेट्री एकत्र करता है। कोई सत्र सामग्री, फाइल नाम, टूल इनपुट, या व्यक्तिगत जानकारी कभी नहीं भेजी जाती है। इसे अक्षम करें: @@ -289,22 +316,22 @@ FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai | गाइड | विवरण | |-------|-------------| -| [शुरुआत करना](docs/getting-started.mdx) | स्थापन और पहले कदम | -| [अंतर्निहित नीतियां](docs/built-in-policies.mdx) | सभी 39 अंतर्निहित नीतियां पैरामीटर के साथ | -| [कस्टम नीतियां](docs/custom-policies.mdx) | अपनी स्वयं की नीतियां लिखें | -| [विन्यास](docs/configuration.mdx) | कॉन्फ़िगरेशन फ़ाइल प्रारूप और स्कोप मर्जिंग | -| [डैशबोर्ड](docs/dashboard.mdx) | सत्रों की निगरानी करें और नीति गतिविधि की समीक्षा करें | -| [आर्किटेक्चर](docs/architecture.mdx) | हुक सिस्टम कैसे काम करता है | -| [परीक्षण](docs/testing.mdx) | परीक्षण चलाना और नए लिखना | +| [Getting Started](docs/getting-started.mdx) | स्थापना और पहले कदम | +| [Built-in Policies](docs/built-in-policies.mdx) | सभी 39 बिल्ट-इन नीतियां पैरामीटर के साथ | +| [Custom Policies](docs/custom-policies.mdx) | अपनी स्वयं की नीतियां लिखें | +| [Configuration](docs/configuration.mdx) | कॉन्फ़िग फाइल प्रारूप और स्कोप मर्जिंग | +| [Dashboard](docs/dashboard.mdx) | सत्रों की निगरानी करें और नीति गतिविधि की समीक्षा करें | +| [Architecture](docs/architecture.mdx) | हुक सिस्टम कैसे काम करता है | +| [Testing](docs/testing.mdx) | परीक्षण चलाना और नए लिखना | -### स्थानीय रूप से दस्तावेज़ चलाएं +### स्थानीय रूप से प्रलेखन चलाएं ```bash docker build -f Dockerfile.docs -t failproofai-docs . docker run --rm -p 3000:3000 failproofai-docs ``` -`http://localhost:3000` पर Mintlify दस्तावेज़ साइट खोलता है। कंटेनर दस्तावेज़ निर्देशिका को माउंट करने पर परिवर्तनों के लिए देखता है: +`http://localhost:3000` पर Mintlify प्रलेखन साइट खोलता है। कंटेनर परिवर्तनों के लिए देखता है यदि आप प्रलेखन निर्देशिका माउंट करते हैं: ```bash docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs @@ -314,15 +341,15 @@ docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs ## failproofai योगदानकर्ताओं के लिए नोट -इस रिपो का `.claude/settings.json` मानक `npx -y failproofai` कमांड के बजाय `bun ./bin/failproofai.mjs --hook ` का उपयोग करता है। यह इसलिए है क्योंकि failproofai प्रोजेक्ट के अंदर `npx -y failproofai` चलाने से स्व-संदर्भित विरोध पैदा होता है। +इस रिपो का `.claude/settings.json` मानक `npx -y failproofai` कमांड की बजाय `bun ./bin/failproofai.mjs --hook ` का उपयोग करता है। ऐसा इसलिए है क्योंकि failproofai परियोजना के अंदर `npx -y failproofai` चलाने से एक आत्म-संदर्भित संघर्ष पैदा होता है। -अन्य सभी रिपो के लिए, अनुशंसित दृष्टिकोण `npx -y failproofai` है, जो इसके द्वारा स्थापित है: +सभी अन्य रिपो के लिए, अनुशंसित दृष्टिकोण `npx -y failproofai` है, जो निम्न के माध्यम से स्थापित है: ```bash failproofai policies --install --scope project ``` -## योगदान देना +## योगदान [CONTRIBUTING.md](CONTRIBUTING.md) देखें। @@ -334,4 +361,4 @@ failproofai policies --install --scope project --- -**ExosphereHost: आपके एजेंट्स के लिए विश्वसनीयता अनुसंधान प्रयोगशाला** द्वारा निर्मित और रखरखाव किया गया। हम अपने स्वयं के एजेंट्स, सॉफ्टवेयर, और विशेषज्ञता के माध्यम से उद्यम और स्टार्टअप को अपने AI एजेंट्स की विश्वसनीयता में सुधार करने में मदद करते हैं। [exosphere.host](https://exosphere.host) पर और जानें। +**ExosphereHost द्वारा निर्मित और संचालित: आपके एजेंटों के लिए विश्वसनीयता अनुसंधान प्रयोगशाला**। हम एंटरप्राइज और स्टार्टअप को अपने स्वयं के एजेंट, सॉफ्टवेयर और विशेषज्ञता के माध्यम से अपने AI एजेंटों की विश्वसनीयता में सुधार करने में मदद करते हैं। [exosphere.host](https://exosphere.host) पर अधिक जानें। diff --git a/docs/i18n/README.it.md b/docs/i18n/README.it.md index 98cff8e5..05fc2b92 100644 --- a/docs/i18n/README.it.md +++ b/docs/i18n/README.it.md @@ -23,13 +23,13 @@ **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) -Il modo più semplice per gestire le policy che mantengono i tuoi agenti AI affidabili, focalizzati e in esecuzione autonoma - per **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(beta)_ e l'**Agents SDK**. +Il modo più facile per gestire le politiche che mantengono i tuoi agenti AI affidabili, concentrati e in esecuzione autonoma - per **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(beta)_, **Cursor Agent** _(beta)_, **OpenCode** _(beta)_, **Pi** _(beta)_, **Gemini CLI** _(beta)_ e l'**Agents SDK**.

Failproof AI in action

-## CLI agenti supportati +## CLI degli agenti supportati

@@ -50,24 +50,51 @@ Il modo più semplice per gestire le policy che mantengono i tuoi agenti AI affi        - + altri in arrivo a breve + + + + Cursor Agent + + +

+

+ + + + OpenCode + + +        + + + + Pi + + +        + + + + Gemini CLI + +

-> Installa gli hook per uno, due o tutti e tre: `failproofai policies --install --cli copilot` (oppure `--cli claude codex copilot`). Ometti `--cli` per il rilevamento automatico dei CLI installati e un prompt. **Il supporto per GitHub Copilot CLI è in beta.** +> 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. **Il supporto per GitHub Copilot CLI, Cursor Agent, OpenCode, Pi e Gemini CLI è in beta — i test sono in corso.** -- **39 Policy Integrate** - Cattura i comuni modi di fallimento degli agenti già pronti all'uso. Blocca i comandi distruttivi, previene le fughe di segreti, mantiene gli agenti entro i confini del progetto, rileva i loop e altro ancora. -- **Policy Personalizzate** - Scrivi le tue regole di affidabilità in JavaScript. Usa l'API `allow`/`deny`/`instruct` per applicare convenzioni, prevenire derive, controllare le operazioni o integrarsi con sistemi esterni. -- **Configurazione Facile** - Sintonizza qualsiasi policy senza scrivere codice. Imposta liste di permessi, branch protetti, soglie per progetto o globalmente. Tre scope di configurazione si uniscono automaticamente. -- **Monitor Agenti** - Guarda cosa hanno fatto i tuoi agenti mentre eri via. Consulta le sessioni, ispeziona ogni chiamata di tool e rivedi esattamente dove le policy sono state attivate. +- **39 politiche incorporate** - Cattura le modalità di errore comuni degli agenti fin da subito. Blocca i comandi distruttivi, previeni le fughe di segreti, mantieni gli agenti entro i confini del progetto, rileva i loop e molto altro. +- **Politiche personalizzate** - Scrivi le tue regole di affidabilità in JavaScript. Usa l'API `allow`/`deny`/`instruct` per applicare convenzioni, prevenire deviazioni, controllare operazioni o integrarti con sistemi esterni. +- **Configurazione facile** - Regola qualsiasi politica senza scrivere codice. Imposta whitelist, rami protetti, soglie per progetto o globalmente. Le tre configurazioni di ambito si uniscono automaticamente. +- **Monitor agenti** - Vedi cosa hanno fatto i tuoi agenti mentre eri lontano. Sfoglia le sessioni, ispeziona ogni chiamata di strumento e verifica esattamente dove sono state attivate le politiche. -Tutto viene eseguito localmente - nessun dato lascia la tua macchina. +Tutto viene eseguito localmente - nessun dato esce dalla tua macchina. --- ## Requisiti - Node.js >= 20.9.0 -- Bun >= 1.3.0 (opzionale - necessario solo per lo sviluppo / compilazione da fonte) +- Bun >= 1.3.0 (facoltativo - necessario solo per lo sviluppo / compilazione dal sorgente) --- @@ -83,13 +110,13 @@ bun add -g failproofai ## Avvio rapido -### 1. Abilita le policy globalmente +### 1. Abilita le politiche globalmente ```bash failproofai policies --install ``` -Scrive i dati hook in `~/.claude/settings.json`. Claude Code ora invocherà failproofai prima e dopo ogni chiamata di tool. +Scrive le voci dei hook in `~/.claude/settings.json`. Claude Code ora invocherà failproofai prima e dopo ogni chiamata di strumento. ### 2. Avvia il dashboard @@ -97,9 +124,9 @@ Scrive i dati hook in `~/.claude/settings.json`. Claude Code ora invocherà fail failproofai ``` -Apre `http://localhost:8020` - consulta le sessioni, ispeziona i log, gestisci le policy. +Apre `http://localhost:8020` - sfoglia le sessioni, ispeziona i log, gestisci le politiche. -### 3. Controlla cosa è attivo +### 3. Verifica cosa è attivo ```bash failproofai policies @@ -107,27 +134,27 @@ failproofai policies --- -## Installazione della policy +## Installazione delle politiche -### Scope +### Ambiti -| Scope | Comando | Dove scrive | -|-------|---------|-------------| +| Ambito | Comando | Dove scrive | +|--------|---------|-------------| | Globale (predefinito) | `failproofai policies --install` | `~/.claude/settings.json` | | Progetto | `failproofai policies --install --scope project` | `.claude/settings.json` | | Locale | `failproofai policies --install --scope local` | `.claude/settings.local.json` | -### Installa policy specifiche +### Installa politiche specifiche ```bash failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` -### Rimuovi le policy +### Rimuovi politiche ```bash failproofai policies --uninstall -# oppure per uno scope specifico: +# oppure per un ambito specifico: failproofai policies --uninstall --scope project ``` @@ -135,7 +162,7 @@ failproofai policies --uninstall --scope project ## Configurazione -La configurazione della policy si trova in `~/.failproofai/policies-config.json` (globale) o `.failproofai/policies-config.json` nel tuo progetto (per-progetto). +La configurazione della politica si trova in `~/.failproofai/policies-config.json` (globale) o `.failproofai/policies-config.json` nel tuo progetto (per progetto). ```json { @@ -168,48 +195,48 @@ La configurazione della policy si trova in `~/.failproofai/policies-config.json` } ``` -**Tre scope di configurazione** vengono uniti automaticamente (progetto → locale → globale). Vedi [docs/configuration.mdx](docs/configuration.mdx) per le regole di unione complete. +**Tre ambiti di configurazione** vengono uniti automaticamente (progetto → locale → globale). Vedi [docs/configuration.mdx](docs/configuration.mdx) per le regole complete di unione. --- -## Policy integrate - -| Policy | Descrizione | Configurabile | -|--------|-------------|:---:| -| `block-sudo` | Impedisce agli agenti di eseguire comandi di sistema privilegiati | `allowPatterns` | -| `block-rm-rf` | Impedisce l'eliminazione ricorsiva accidentale di file | `allowPaths` | -| `block-curl-pipe-sh` | Impedisce agli agenti di convogliare script non attendibili alla shell | | -| `block-failproofai-commands` | Impedisce l'auto-disinstallazione | | -| `sanitize-jwt` | Ferma la perdita di token JWT nel contesto dell'agente | | -| `sanitize-api-keys` | Ferma la perdita di chiavi API nel contesto dell'agente | `additionalPatterns` | -| `sanitize-connection-strings` | Ferma la perdita delle credenziali del database nel contesto dell'agente | | -| `sanitize-private-key-content` | Redige i blocchi di chiave privata PEM dall'output | | -| `sanitize-bearer-tokens` | Redige i token Bearer di Authorization dall'output | | -| `block-env-files` | Impedisce agli agenti di leggere file .env | | -| `protect-env-vars` | Impedisce agli agenti di stampare le variabili d'ambiente | | -| `block-read-outside-cwd` | Mantiene gli agenti entro i confini del progetto | `allowPaths` | -| `block-secrets-write` | Impedisce le scritture su file di chiave privata e certificato | `additionalPatterns` | -| `block-push-master` | Impedisce i push accidentali su main/master | `protectedBranches` | -| `block-work-on-main` | Mantiene gli agenti lontani dai branch protetti | `protectedBranches` | -| `block-force-push` | Impedisce `git push --force` | | -| `warn-git-amend` | Ricorda agli agenti prima di modificare i commit | | +## Politiche incorporate + +| Politica | Descrizione | Configurabile | +|----------|-------------|:---:| +| `block-sudo` | Impedisci agli agenti di eseguire comandi di sistema privilegiati | `allowPatterns` | +| `block-rm-rf` | Previeni l'eliminazione accidentale di file ricorsiva | `allowPaths` | +| `block-curl-pipe-sh` | Impedisci agli agenti di trasmettere script non attendibili alla shell | | +| `block-failproofai-commands` | Previeni l'auto-disinstallazione | | +| `sanitize-jwt` | Impedisci ai token JWT di fuggire nel contesto dell'agente | | +| `sanitize-api-keys` | Impedisci alle chiavi API di fuggire nel contesto dell'agente | `additionalPatterns` | +| `sanitize-connection-strings` | Impedisci alle credenziali del database di fuggire nel contesto dell'agente | | +| `sanitize-private-key-content` | Redigi i blocchi di chiave privata PEM dall'output | | +| `sanitize-bearer-tokens` | Redigi i token Bearer di autorizzazione dall'output | | +| `block-env-files` | Impedisci agli agenti di leggere i file .env | | +| `protect-env-vars` | Impedisci agli agenti di stampare le variabili di ambiente | | +| `block-read-outside-cwd` | Mantieni gli agenti dentro i confini del progetto | `allowPaths` | +| `block-secrets-write` | Impedisci le scritture nei file di chiave privata e certificati | `additionalPatterns` | +| `block-push-master` | Previeni i push accidentali a main/master | `protectedBranches` | +| `block-work-on-main` | Impedisci agli agenti di lavorare su rami protetti | `protectedBranches` | +| `block-force-push` | Previeni `git push --force` | | +| `warn-git-amend` | Ricorda agli agenti prima di emendare i commit | | | `warn-git-stash-drop` | Ricorda agli agenti prima di eliminare gli stash | | -| `warn-all-files-staged` | Cattura `git add -A` accidentale | | -| `warn-destructive-sql` | Cattura DROP/DELETE SQL prima dell'esecuzione | | -| `warn-schema-alteration` | Cattura ALTER TABLE prima dell'esecuzione | | -| `warn-large-file-write` | Cattura le scritture di file inaspettatamente grandi | `thresholdKb` | -| `warn-package-publish` | Cattura `npm publish` accidentale | | -| `warn-background-process` | Cattura l'avvio di processi di background involontario | | -| `warn-global-package-install` | Cattura gli install di pacchetti globali involontari | | +| `warn-all-files-staged` | Rileva l'accidentale `git add -A` | | +| `warn-destructive-sql` | Rileva DROP/DELETE SQL prima dell'esecuzione | | +| `warn-schema-alteration` | Rileva ALTER TABLE prima dell'esecuzione | | +| `warn-large-file-write` | Rileva scritture di file inaspettatamente grandi | `thresholdKb` | +| `warn-package-publish` | Rileva l'accidentale `npm publish` | | +| `warn-background-process` | Rileva i lanci di processi in background non intenzionali | | +| `warn-global-package-install` | Rileva i lanci di installazione di pacchetti globali non intenzionali | | | …e altri | | | -Dettagli completi sulla policy e riferimento dei parametri: [docs/built-in-policies.mdx](docs/built-in-policies.mdx) +Dettagli completi della politica e riferimento dei parametri: [docs/built-in-policies.mdx](docs/built-in-policies.mdx) --- -## Policy personalizzate +## Politiche personalizzate -Scrivi le tue policy per mantenere gli agenti affidabili e focalizzati: +Scrivi le tue politiche per mantenere gli agenti affidabili e concentrati: ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -233,35 +260,35 @@ Installa con: failproofai policies --install --custom ./my-policies.js ``` -### Helper di decisione +### Funzioni di supporto decisionale | Funzione | Effetto | -|----------|--------| +|----------|---------| | `allow()` | Consenti l'operazione | | `allow(message)` | Consenti e invia contesto informativo a Claude | | `deny(message)` | Blocca l'operazione; il messaggio viene mostrato a Claude | | `instruct(message)` | Aggiungi contesto al prompt di Claude; non blocca | -### Oggetto di contesto (`ctx`) +### Oggetto contesto (`ctx`) | Campo | Tipo | Descrizione | |-------|------|-------------| -| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string` | Tool in fase di chiamata (`"Bash"`, `"Write"`, `"Read"`, …) | -| `toolInput` | `object` | Parametri di input del tool | -| `payload` | `object` | Payload di evento grezzo completo | +| `eventType` | `string` | `PreToolUse`, `PostToolUse`, `Notification`, `Stop` | +| `toolName` | `string` | Strumento in fase di richiesta (`Bash`, `Write`, `Read`, …) | +| `toolInput` | `object` | Parametri di input dello strumento | +| `payload` | `object` | Payload completo dell'evento grezzo | | `session.cwd` | `string` | Directory di lavoro della sessione Claude Code | | `session.sessionId` | `string` | Identificatore della sessione | -| `session.transcriptPath` | `string` | Percorso al file di trascrizione della sessione | +| `session.transcriptPath` | `string` | Percorso del file trascrizione della sessione | -I hook personalizzati supportano import locali transitivi, async/await e accesso a `process.env`. Gli errori sono fail-open (registrati in `~/.failproofai/hook.log`, le policy integrate continuano). Vedi [docs/custom-hooks.mdx](docs/custom-hooks.mdx) per la guida completa. +I hook personalizzati supportano importazioni locali transitive, async/await e accesso a `process.env`. Gli errori sono fail-open (registrati in `~/.failproofai/hook.log`, le politiche incorporate continuano). Vedi [docs/custom-hooks.mdx](docs/custom-hooks.mdx) per la guida completa. -### Policy basate su convenzione +### Politiche basate su convenzioni -Scarica i file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e vengono caricati automaticamente - nessun flag o cambiamento di configurazione necessario. Esegui il commit della directory in git e ogni membro del team ottiene automaticamente gli stessi standard di qualità. +Posiziona i file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e vengono caricati automaticamente — nessun flag o cambio di configurazione necessari. Committa la directory su git e ogni membro del team ottiene automaticamente gli stessi standard di qualità. ```text -# Livello progetto — committed a git, condiviso con il team +# Livello progetto — committato su git, condiviso con il team .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs @@ -269,15 +296,15 @@ Scarica i file `*policies.{js,mjs,ts}` in `.failproofai/policies/` e vengono car ~/.failproofai/policies/my-policies.mjs ``` -Entrambi i livelli vengono caricati (union). I file vengono caricati alfabeticamente all'interno di ogni directory. Prefisso con `01-`, `02-`, ecc. per controllare l'ordine. Man mano che il tuo team scopre nuovi modi di fallimento, aggiungi una policy e fai il push - tutti ottengono l'aggiornamento al loro prossimo pull. Vedi [examples/convention-policies/](examples/convention-policies/) per esempi pronti all'uso. +Entrambi i livelli vengono caricati (unione). I file vengono caricati alfabeticamente all'interno di ogni directory. Aggiungi il prefisso `01-`, `02-`, ecc. per controllare l'ordine. Mentre il tuo team scopre nuove modalità di errore, aggiungi una politica e fai il push — tutti ricevono l'aggiornamento al prossimo pull. Vedi [examples/convention-policies/](examples/convention-policies/) per esempi pronti all'uso. --- ## Telemetria -Failproof AI raccoglie telemetria d'uso anonima tramite PostHog per comprendere l'utilizzo delle funzionalità. Il contenuto della sessione, i nomi dei file, gli input dei tool o le informazioni personali non vengono mai inviati. +Failproof AI raccoglie telemetria di utilizzo anonima tramite PostHog per comprendere l'utilizzo delle funzionalità. Il contenuto della sessione, i nomi dei file, gli input degli strumenti o le informazioni personali non vengono mai inviati. -Disabilitalo: +Disabilitala: ```bash FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai @@ -290,12 +317,12 @@ FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai | Guida | Descrizione | |-------|-------------| | [Getting Started](docs/getting-started.mdx) | Installazione e primi passi | -| [Built-in Policies](docs/built-in-policies.mdx) | Tutte le 39 policy integrate con parametri | -| [Custom Policies](docs/custom-policies.mdx) | Scrivi le tue policy | -| [Configuration](docs/configuration.mdx) | Formato del file di configurazione e unione degli scope | -| [Dashboard](docs/dashboard.mdx) | Monitora le sessioni e rivedi l'attività delle policy | +| [Built-in Policies](docs/built-in-policies.mdx) | Tutte le 39 politiche incorporate con parametri | +| [Custom Policies](docs/custom-policies.mdx) | Scrivi le tue politiche | +| [Configuration](docs/configuration.mdx) | Formato del file di configurazione e unione degli ambiti | +| [Dashboard](docs/dashboard.mdx) | Monitora le sessioni e verifica l'attività delle politiche | | [Architecture](docs/architecture.mdx) | Come funziona il sistema di hook | -| [Testing](docs/testing.mdx) | Esecuzione dei test e scrittura di nuovi | +| [Testing](docs/testing.mdx) | Esegui i test e scrivi i nuovi | ### Esegui la documentazione localmente @@ -304,7 +331,7 @@ docker build -f Dockerfile.docs -t failproofai-docs . docker run --rm -p 3000:3000 failproofai-docs ``` -Apre il sito di documentazione Mintlify su `http://localhost:3000`. Il contenitore guarda i cambiamenti se monti la directory della documentazione: +Apre il sito della documentazione Mintlify su `http://localhost:3000`. Il container osserva i cambiamenti se monti la directory dei documenti: ```bash docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs @@ -312,11 +339,11 @@ docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs --- -## Nota per i contributori di failproofai +## Nota per i collaboratori di failproofai -Il `.claude/settings.json` di questo repo utilizza `bun ./bin/failproofai.mjs --hook ` invece del comando standard `npx -y failproofai`. Questo è perché eseguire `npx -y failproofai` all'interno del progetto failproofai stesso crea un conflitto di auto-riferimento. +Il `.claude/settings.json` di questo repository utilizza `bun ./bin/failproofai.mjs --hook ` invece del comando standard `npx -y failproofai`. Questo perché l'esecuzione di `npx -y failproofai` dentro il progetto failproofai stesso crea un conflitto di auto-riferimento. -Per tutti gli altri repo, l'approccio consigliato è `npx -y failproofai`, installato tramite: +Per tutti gli altri repository, l'approccio consigliato è `npx -y failproofai`, installato tramite: ```bash failproofai policies --install --scope project @@ -334,4 +361,4 @@ Vedi [LICENSE](LICENSE). --- -Creato e Mantenuto da **ExosphereHost: Reliability Research Lab for Your Agents**. Aiutiamo aziende e startup a migliorare l'affidabilità dei loro agenti AI attraverso i nostri agenti, software e competenze. Scopri di più su [exosphere.host](https://exosphere.host). +Creato e mantenuto da **ExosphereHost: Reliability Research Lab for Your Agents**. Aiutiamo le aziende e le startup a migliorare l'affidabilità dei loro agenti AI attraverso i nostri agenti, software e competenze. Scopri di più su [exosphere.host](https://exosphere.host). diff --git a/docs/i18n/README.pt-br.md b/docs/i18n/README.pt-br.md index 80d0cf70..d76ac9af 100644 --- a/docs/i18n/README.pt-br.md +++ b/docs/i18n/README.pt-br.md @@ -23,7 +23,7 @@ **Traduções**: [简体中文](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) -A maneira mais fácil de gerenciar políticas que mantêm seus agentes de IA confiáveis, focados na tarefa e rodando de forma autônoma — para **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(beta)_ e o **Agents SDK**. +A maneira mais fácil de gerenciar políticas que mantêm seus agentes de IA confiáveis, focados nas tarefas e operando de forma autônoma - para **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(beta)_, **Cursor Agent** _(beta)_, **OpenCode** _(beta)_, **Pi** _(beta)_, **Gemini CLI** _(beta)_ e o **Agents SDK**.

Failproof AI em ação @@ -50,24 +50,51 @@ A maneira mais fácil de gerenciar políticas que mantêm seus agentes de IA con        - + mais em breve + + + + Cursor Agent + + +

+

+ + + + OpenCode + + +        + + + + Pi + + +        + + + + Gemini CLI + +

-> Instale hooks para um, dois ou todos os três: `failproofai policies --install --cli copilot` (ou `--cli claude codex copilot`). Omita `--cli` para detectar automaticamente os CLIs instalados e receber uma confirmação. **O suporte ao GitHub Copilot CLI está em beta.** +> 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. **O suporte a GitHub Copilot CLI, Cursor Agent, OpenCode, Pi e Gemini CLI está em beta — os testes estão em andamento.** -- **39 Políticas Integradas** - Detecte os modos de falha mais comuns de agentes logo de início. Bloqueie comandos destrutivos, evite vazamento de segredos, mantenha os agentes dentro dos limites do projeto, detecte loops e muito mais. +- **39 Políticas Integradas** - Detecte os modos de falha mais comuns dos agentes logo de cara. Bloqueie comandos destrutivos, evite vazamento de segredos, mantenha os agentes dentro dos limites do projeto, detecte loops e muito mais. - **Políticas Personalizadas** - Escreva suas próprias regras de confiabilidade em JavaScript. Use a API `allow`/`deny`/`instruct` para aplicar convenções, prevenir desvios, controlar operações ou integrar com sistemas externos. -- **Configuração Simples** - Ajuste qualquer política sem escrever código. Defina listas de permissão, branches protegidas e limites por projeto ou globalmente. Três escopos de configuração mesclados automaticamente. +- **Configuração Simples** - Ajuste qualquer política sem escrever código. Defina listas de permissão, branches protegidas e limites por projeto ou globalmente. Três escopos de configuração são mesclados automaticamente. - **Monitor de Agentes** - Veja o que seus agentes fizeram enquanto você estava ausente. Navegue pelas sessões, inspecione cada chamada de ferramenta e revise exatamente onde as políticas foram acionadas. -Tudo roda localmente — nenhum dado sai da sua máquina. +Tudo é executado localmente — nenhum dado sai da sua máquina. --- ## Requisitos - Node.js >= 20.9.0 -- Bun >= 1.3.0 (opcional — necessário apenas para desenvolvimento / build a partir do código-fonte) +- Bun >= 1.3.0 (opcional - necessário apenas para desenvolvimento / compilação a partir do código-fonte) --- @@ -83,23 +110,23 @@ bun add -g failproofai ## Início rápido -### 1. Ative as políticas globalmente +### 1. Habilitar políticas globalmente ```bash failproofai policies --install ``` -Insere entradas de hook em `~/.claude/settings.json`. Claude Code passará a invocar o failproofai antes e depois de cada chamada de ferramenta. +Escreve entradas de hook em `~/.claude/settings.json`. Claude Code passará a invocar failproofai antes e depois de cada chamada de ferramenta. -### 2. Abra o painel +### 2. Abrir o painel ```bash failproofai ``` -Abre `http://localhost:8020` — navegue pelas sessões, inspecione logs e gerencie políticas. +Abre `http://localhost:8020` - navegue pelas sessões, inspecione logs, gerencie políticas. -### 3. Verifique o que está ativo +### 3. Verificar o que está ativo ```bash failproofai policies @@ -176,24 +203,24 @@ A configuração de políticas fica em `~/.failproofai/policies-config.json` (gl | Política | Descrição | Configurável | |----------|-----------|:---:| -| `block-sudo` | Impede agentes de executar comandos privilegiados do sistema | `allowPatterns` | +| `block-sudo` | Impede que agentes executem comandos privilegiados do sistema | `allowPatterns` | | `block-rm-rf` | Previne exclusão recursiva acidental de arquivos | `allowPaths` | -| `block-curl-pipe-sh` | Impede agentes de redirecionar scripts não confiáveis para o shell | | -| `block-failproofai-commands` | Previne a auto-desinstalação | | -| `sanitize-jwt` | Impede que tokens JWT vazem no contexto do agente | | -| `sanitize-api-keys` | Impede que chaves de API vazem no contexto do agente | `additionalPatterns` | -| `sanitize-connection-strings` | Impede que credenciais de banco de dados vazem no contexto do agente | | -| `sanitize-private-key-content` | Oculta blocos de chave privada PEM da saída | | -| `sanitize-bearer-tokens` | Oculta tokens Bearer de Authorization da saída | | -| `block-env-files` | Impede agentes de ler arquivos .env | | -| `protect-env-vars` | Impede agentes de imprimir variáveis de ambiente | | -| `block-read-outside-cwd` | Mantém agentes dentro dos limites do projeto | `allowPaths` | +| `block-curl-pipe-sh` | Impede que agentes redirecionem scripts não confiáveis para o shell | | +| `block-failproofai-commands` | Previne a desinstalação automática | | +| `sanitize-jwt` | Evita que tokens JWT vazem para o contexto do agente | | +| `sanitize-api-keys` | Evita que chaves de API vazem para o contexto do agente | `additionalPatterns` | +| `sanitize-connection-strings` | Evita que credenciais de banco de dados vazem para o contexto do agente | | +| `sanitize-private-key-content` | Remove blocos de chave privada PEM da saída | | +| `sanitize-bearer-tokens` | Remove tokens Bearer de Authorization da saída | | +| `block-env-files` | Impede que agentes leiam arquivos .env | | +| `protect-env-vars` | Impede que agentes imprimam variáveis de ambiente | | +| `block-read-outside-cwd` | Mantém os agentes dentro dos limites do projeto | `allowPaths` | | `block-secrets-write` | Previne gravações em arquivos de chave privada e certificado | `additionalPatterns` | | `block-push-master` | Previne pushes acidentais para main/master | `protectedBranches` | -| `block-work-on-main` | Mantém agentes fora de branches protegidas | `protectedBranches` | +| `block-work-on-main` | Mantém os agentes fora de branches protegidas | `protectedBranches` | | `block-force-push` | Previne `git push --force` | | -| `warn-git-amend` | Lembra agentes antes de alterar commits | | -| `warn-git-stash-drop` | Lembra agentes antes de descartar stashes | | +| `warn-git-amend` | Lembra os agentes antes de emendar commits | | +| `warn-git-stash-drop` | Lembra os agentes antes de descartar stashes | | | `warn-all-files-staged` | Detecta `git add -A` acidental | | | `warn-destructive-sql` | Detecta DROP/DELETE SQL antes da execução | | | `warn-schema-alteration` | Detecta ALTER TABLE antes da execução | | @@ -209,7 +236,7 @@ Detalhes completos das políticas e referência de parâmetros: [docs/built-in-p ## Políticas personalizadas -Escreva suas próprias políticas para manter os agentes confiáveis e focados na tarefa: +Escreva suas próprias políticas para manter os agentes confiáveis e focados nas tarefas: ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -233,7 +260,7 @@ Instale com: failproofai policies --install --custom ./my-policies.js ``` -### Funções de decisão +### Funções auxiliares de decisão | Função | Efeito | |--------|--------| @@ -254,11 +281,11 @@ failproofai policies --install --custom ./my-policies.js | `session.sessionId` | `string` | Identificador da sessão | | `session.transcriptPath` | `string` | Caminho para o arquivo de transcrição da sessão | -Hooks personalizados suportam importações locais transitivas, async/await e acesso a `process.env`. Erros são fail-open (registrados em `~/.failproofai/hook.log`, as políticas integradas continuam). Consulte [docs/custom-hooks.mdx](docs/custom-hooks.mdx) para o guia completo. +Hooks personalizados suportam importações locais transitivas, async/await e acesso a `process.env`. Erros são fail-open (registrados em `~/.failproofai/hook.log`, as políticas integradas continuam funcionando). Consulte [docs/custom-hooks.mdx](docs/custom-hooks.mdx) para o guia completo. ### Políticas baseadas em convenção -Coloque arquivos `*policies.{js,mjs,ts}` em `.failproofai/policies/` e eles serão carregados automaticamente — sem flags ou alterações de configuração necessárias. Faça commit do diretório no git e todos os membros da equipe receberão automaticamente os mesmos padrões de qualidade. +Coloque arquivos `*policies.{js,mjs,ts}` em `.failproofai/policies/` e eles serão carregados automaticamente — sem flags ou alterações de configuração necessárias. Faça o commit do diretório no git e todos os membros da equipe receberão os mesmos padrões de qualidade automaticamente. ```text # Nível de projeto — commitado no git, compartilhado com a equipe @@ -269,15 +296,15 @@ Coloque arquivos `*policies.{js,mjs,ts}` em `.failproofai/policies/` e eles ser ~/.failproofai/policies/my-policies.mjs ``` -Ambos os níveis são carregados (união). Os arquivos são carregados em ordem alfabética dentro de cada diretório. Prefixe com `01-`, `02-`, etc. para controlar a ordem. Conforme sua equipe descobre novos modos de falha, adicione uma política e faça push — todos recebem a atualização no próximo pull. Veja [examples/convention-policies/](examples/convention-policies/) para exemplos prontos para uso. +Ambos os níveis são carregados (união). Os arquivos são carregados em ordem alfabética dentro de cada diretório. Use o prefixo `01-`, `02-`, etc. para controlar a ordem. À medida que sua equipe descobre novos modos de falha, adicione uma política e faça o push — todos recebem a atualização no próximo pull. Veja [examples/convention-policies/](examples/convention-policies/) para exemplos prontos para uso. --- ## Telemetria -O Failproof AI coleta telemetria de uso anônima via PostHog para entender o uso de funcionalidades. Nenhum conteúdo de sessão, nome de arquivo, entrada de ferramenta ou informação pessoal é enviado. +Failproof AI coleta telemetria de uso anônima via PostHog para entender o uso das funcionalidades. Nenhum conteúdo de sessão, nome de arquivo, entrada de ferramenta ou informação pessoal é enviado. -Para desabilitar: +Para desativar: ```bash FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai @@ -293,18 +320,18 @@ FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai | [Políticas Integradas](docs/built-in-policies.mdx) | Todas as 39 políticas integradas com parâmetros | | [Políticas Personalizadas](docs/custom-policies.mdx) | Escreva suas próprias políticas | | [Configuração](docs/configuration.mdx) | Formato do arquivo de configuração e mesclagem de escopos | -| [Painel](docs/dashboard.mdx) | Monitore sessões e revise a atividade de políticas | +| [Painel](docs/dashboard.mdx) | Monitore sessões e revise a atividade das políticas | | [Arquitetura](docs/architecture.mdx) | Como o sistema de hooks funciona | | [Testes](docs/testing.mdx) | Executando testes e escrevendo novos | -### Execute a documentação localmente +### Executar a documentação localmente ```bash docker build -f Dockerfile.docs -t failproofai-docs . docker run --rm -p 3000:3000 failproofai-docs ``` -Abre o site de documentação Mintlify em `http://localhost:3000`. O container detecta alterações se você montar o diretório de docs: +Abre o site de documentação Mintlify em `http://localhost:3000`. O container observa alterações se você montar o diretório de documentação: ```bash docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs @@ -314,7 +341,7 @@ docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs ## Nota para contribuidores do failproofai -O `.claude/settings.json` deste repositório usa `bun ./bin/failproofai.mjs --hook ` em vez do comando padrão `npx -y failproofai`. Isso ocorre porque executar `npx -y failproofai` dentro do próprio projeto failproofai cria um conflito de auto-referência. +O arquivo `.claude/settings.json` deste repositório usa `bun ./bin/failproofai.mjs --hook ` em vez do comando padrão `npx -y failproofai`. Isso ocorre porque executar `npx -y failproofai` dentro do próprio projeto failproofai cria um conflito de auto-referência. Para todos os outros repositórios, a abordagem recomendada é `npx -y failproofai`, instalado via: @@ -334,4 +361,4 @@ Consulte [LICENSE](LICENSE). --- -Desenvolvido e mantido pela **ExosphereHost: Reliability Research Lab for Your Agents**. Ajudamos empresas e startups a melhorar a confiabilidade de seus agentes de IA por meio de nossos próprios agentes, software e expertise. Saiba mais em [exosphere.host](https://exosphere.host). +Criado e mantido pela **ExosphereHost: Reliability Research Lab for Your Agents**. Ajudamos empresas e startups a melhorar a confiabilidade de seus agentes de IA por meio de nossos próprios agentes, software e expertise. Saiba mais em [exosphere.host](https://exosphere.host). diff --git a/docs/i18n/README.ru.md b/docs/i18n/README.ru.md index dc30a2a9..627a4822 100644 --- a/docs/i18n/README.ru.md +++ b/docs/i18n/README.ru.md @@ -23,7 +23,7 @@ **Переводы**: [简体中文](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) -Самый простой способ управления политиками, которые делают ваших AI-агентов надёжными, сосредоточенными на задачах и работающими автономно — для **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(бета)_ и **Agents SDK**. +Самый простой способ управлять политиками, которые поддерживают ваши AI-агентов надёжными, сосредоточенными на задачах и работающими автономно — для **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(бета)_, **Cursor Agent** _(бета)_, **OpenCode** _(бета)_, **Pi** _(бета)_, **Gemini CLI** _(бета)_ и **Agents SDK**.

Failproof AI в действии @@ -50,24 +50,51 @@        - + ещё скоро + + + + Cursor Agent + + +

+

+ + + + OpenCode + + +        + + + + Pi + + +        + + + + Gemini CLI + +

-> Установите перехватчики для одного, двух или всех трёх: `failproofai policies --install --cli copilot` (или `--cli claude codex copilot`). Опустите `--cli`, чтобы автоматически обнаружить установленные CLI и выбрать. **Поддержка GitHub Copilot CLI находится в бета-версии.** +> Установите хуки для одного или нескольких из них: `failproofai policies --install --cli opencode pi gemini` (или `--cli claude codex copilot cursor opencode pi gemini`). Опустите `--cli` для автоматического обнаружения установленных CLI и подсказок. **Поддержка GitHub Copilot CLI, Cursor Agent, OpenCode, Pi и Gemini CLI находится в бета-версии — тестирование продолжается.** -- **39 встроенных политик** — перехватывайте распространённые режимы отказа агентов из коробки. Блокируйте деструктивные команды, предотвращайте утечки секретов, держите агентов в границах проекта, обнаруживайте циклы и многое другое. -- **Пользовательские политики** — напишите свои собственные правила надёжности на JavaScript. Используйте API `allow`/`deny`/`instruct` для обеспечения соглашений, предотвращения дрейфа, управления операциями или интеграции с внешними системами. -- **Простая конфигурация** — настраивайте любую политику без написания кода. Установите белые списки, защищённые ветви, пороги для каждого проекта или глобально. Три области конфигурации объединяются автоматически. -- **Монитор агентов** — смотрите, что делали ваши агенты, пока вас не было. Просматривайте сессии, проверяйте каждый вызов инструмента и смотрите, где именно срабатывали политики. +- **39 встроенных политик** — ловите типичные режимы отказа агентов из коробки. Блокируйте деструктивные команды, предотвращайте утечку секретов, держите агентов внутри границ проекта, обнаруживайте циклы и многое другое. +- **Пользовательские политики** — напишите свои собственные правила надёжности на JavaScript. Используйте API `allow`/`deny`/`instruct` для принятия соглашений, предотвращения дрейфа, контроля операций или интеграции с внешними системами. +- **Простая конфигурация** — настройте любую политику без написания кода. Установите белые списки, защищённые ветви, пороги для отдельных проектов или глобально. Конфигурация с тремя областями объединяется автоматически. +- **Монитор агентов** — смотрите, что делали ваши агенты, пока вас не было. Просматривайте сессии, инспектируйте каждый вызов инструмента и проверяйте ровно то, где срабатывали политики. -Всё выполняется локально — никакие данные не покидают вашу машину. +Всё работает локально — никакие данные не покидают вашу машину. --- ## Требования - Node.js >= 20.9.0 -- Bun >= 1.3.0 (опционально — требуется только для разработки / построения из исходного кода) +- Bun >= 1.3.0 (опционально — требуется только для разработки / сборки из исходного кода) --- @@ -89,9 +116,9 @@ bun add -g failproofai failproofai policies --install ``` -Записывает записи перехватчиков в `~/.claude/settings.json`. Claude Code будет вызывать failproofai до и после каждого вызова инструмента. +Записывает записи хуков в `~/.claude/settings.json`. Claude Code теперь будет вызывать failproofai до и после каждого вызова инструмента. -### 2. Запустите панель мониторинга +### 2. Запустите панель управления ```bash failproofai @@ -109,10 +136,10 @@ failproofai policies ## Установка политик -### Области +### Области видимости -| Область | Команда | Где записывается | -|---------|---------|-----------------| +| Область видимости | Команда | Где записывается | +|-------|---------|-----------------| | Глобальная (по умолчанию) | `failproofai policies --install` | `~/.claude/settings.json` | | Проект | `failproofai policies --install --scope project` | `.claude/settings.json` | | Локальная | `failproofai policies --install --scope local` | `.claude/settings.local.json` | @@ -127,7 +154,7 @@ failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ```bash failproofai policies --uninstall -# или для конкретной области: +# или для конкретной области видимости: failproofai policies --uninstall --scope project ``` @@ -154,7 +181,7 @@ failproofai policies --uninstall --scope project }, "block-push-master": { "protectedBranches": ["main", "release", "prod"], - "hint": "Попробуйте создать новую ветвь." + "hint": "Попробуйте создать свежую ветку вместо этого." }, "sanitize-api-keys": { "additionalPatterns": [ @@ -168,60 +195,60 @@ failproofai policies --uninstall --scope project } ``` -**Три области конфигурации** объединяются автоматически (проект → локальная → глобальная). Смотрите [docs/configuration.mdx](docs/configuration.mdx) для полных правил объединения. +**Три области конфигурации** объединяются автоматически (проект → локальная → глобальная). Полные правила объединения см. в [docs/configuration.mdx](docs/configuration.mdx). --- ## Встроенные политики | Политика | Описание | Настраивается | -|----------|---------|:---:| -| `block-sudo` | Предотвратите запуск привилегированных системных команд агентами | `allowPatterns` | -| `block-rm-rf` | Предотвратите случайное рекурсивное удаление файлов | `allowPaths` | -| `block-curl-pipe-sh` | Предотвратите передачу агентами ненадёжных скриптов в shell | | -| `block-failproofai-commands` | Предотвратите самоудаление | | -| `sanitize-jwt` | Остановите утечку JWT-токенов в контекст агента | | -| `sanitize-api-keys` | Остановите утечку ключей API в контекст агента | `additionalPatterns` | -| `sanitize-connection-strings` | Остановите утечку учётных данных БД в контекст агента | | -| `sanitize-private-key-content` | Отредактируйте блоки приватных ключей PEM из вывода | | -| `sanitize-bearer-tokens` | Отредактируйте токены Authorization Bearer из вывода | | -| `block-env-files` | Держите агентов подальше от чтения файлов .env | | -| `protect-env-vars` | Предотвратите вывод переменных окружения агентами | | -| `block-read-outside-cwd` | Держите агентов в границах проекта | `allowPaths` | -| `block-secrets-write` | Предотвратите запись в файлы приватных ключей и сертификатов | `additionalPatterns` | -| `block-push-master` | Предотвратите случайные push в main/master | `protectedBranches` | -| `block-work-on-main` | Держите агентов вдали от защищённых ветвей | `protectedBranches` | -| `block-force-push` | Предотвратите `git push --force` | | -| `warn-git-amend` | Напомните агентам перед изменением коммитов | | -| `warn-git-stash-drop` | Напомните агентам перед удалением stash | | -| `warn-all-files-staged` | Поймайте случайный `git add -A` | | -| `warn-destructive-sql` | Поймайте DROP/DELETE SQL перед выполнением | | -| `warn-schema-alteration` | Поймайте ALTER TABLE перед выполнением | | -| `warn-large-file-write` | Поймайте неожиданно большие записи файлов | `thresholdKb` | -| `warn-package-publish` | Поймайте случайный `npm publish` | | -| `warn-background-process` | Поймайте непреднамеренные запуски фоновых процессов | | -| `warn-global-package-install` | Поймайте непреднамеренные глобальные установки пакетов | | -| …и ещё | | | - -Полные детали политик и справочник параметров: [docs/built-in-policies.mdx](docs/built-in-policies.mdx) +|--------|-------------|:---:| +| `block-sudo` | Предотвратить выполнение привилегированных системных команд агентами | `allowPatterns` | +| `block-rm-rf` | Предотвратить случайное рекурсивное удаление файлов | `allowPaths` | +| `block-curl-pipe-sh` | Предотвратить перенаправление ненадёжных скриптов в shell | | +| `block-failproofai-commands` | Предотвратить самоудаление | | +| `sanitize-jwt` | Остановить утечку JWT-токенов в контекст агента | | +| `sanitize-api-keys` | Остановить утечку API-ключей в контекст агента | `additionalPatterns` | +| `sanitize-connection-strings` | Остановить утечку учётных данных БД в контекст агента | | +| `sanitize-private-key-content` | Скрыть блоки приватных ключей PEM из вывода | | +| `sanitize-bearer-tokens` | Скрыть токены Authorization Bearer из вывода | | +| `block-env-files` | Удерживать агентов от чтения .env-файлов | | +| `protect-env-vars` | Предотвратить печать переменных окружения агентами | | +| `block-read-outside-cwd` | Держать агентов внутри границ проекта | `allowPaths` | +| `block-secrets-write` | Предотвратить запись в файлы приватных ключей и сертификатов | `additionalPatterns` | +| `block-push-master` | Предотвратить случайные отправки в main/master | `protectedBranches` | +| `block-work-on-main` | Удерживать агентов от защищённых ветвей | `protectedBranches` | +| `block-force-push` | Предотвратить `git push --force` | | +| `warn-git-amend` | Напомнить агентам перед переписанием коммитов | | +| `warn-git-stash-drop` | Напомнить агентам перед удалением stash | | +| `warn-all-files-staged` | Перехватить случайный `git add -A` | | +| `warn-destructive-sql` | Перехватить DROP/DELETE SQL перед выполнением | | +| `warn-schema-alteration` | Перехватить ALTER TABLE перед выполнением | | +| `warn-large-file-write` | Перехватить неожиданно большие записи файлов | `thresholdKb` | +| `warn-package-publish` | Перехватить случайный `npm publish` | | +| `warn-background-process` | Перехватить непредвиденные запуски фоновых процессов | | +| `warn-global-package-install` | Перехватить непредвиденные глобальные установки пакетов | | +| …и ещё больше | | | + +Полные детали политик и справка параметров: [docs/built-in-policies.mdx](docs/built-in-policies.mdx) --- ## Пользовательские политики -Напишите собственные политики, чтобы держать агентов надёжными и сосредоточенными: +Напишите свои собственные политики для поддержания надёжности и сосредоточенности агентов на задачах: ```js import { customPolicies, allow, deny, instruct } from "failproofai"; customPolicies.add({ name: "no-production-writes", - description: "Блокируйте запись в пути, содержащие 'production'", + description: "Блокировать записи в пути, содержащие слово 'production'", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow(); const path = ctx.toolInput?.file_path ?? ""; - if (path.includes("production")) return deny("Записи в production пути заблокированы"); + if (path.includes("production")) return deny("Записи в production-пути заблокированы"); return allow(); }, }); @@ -236,48 +263,48 @@ failproofai policies --install --custom ./my-policies.js ### Вспомогательные функции решений | Функция | Эффект | -|---------|--------| +|----------|--------| | `allow()` | Разрешить операцию | | `allow(message)` | Разрешить и отправить информационный контекст Claude | -| `deny(message)` | Заблокировать операцию; сообщение показано Claude | +| `deny(message)` | Блокировать операцию; сообщение показано Claude | | `instruct(message)` | Добавить контекст в подсказку Claude; не блокирует | ### Объект контекста (`ctx`) | Поле | Тип | Описание | -|------|-----|---------| -| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string` | Вызываемый инструмент (`"Bash"`, `"Write"`, `"Read"`, …) | -| `toolInput` | `object` | Входные параметры инструмента | +|-------|------|-------------| +| `eventType` | `string` | `PreToolUse`, `PostToolUse`, `Notification`, `Stop` | +| `toolName` | `string` | Вызываемый инструмент (`Bash`, `Write`, `Read`, …) | +| `toolInput` | `object` | Параметры ввода инструмента | | `payload` | `object` | Полная исходная полезная нагрузка события | | `session.cwd` | `string` | Рабочий каталог сессии Claude Code | | `session.sessionId` | `string` | Идентификатор сессии | -| `session.transcriptPath` | `string` | Путь к файлу транскрипта сессии | +| `session.transcriptPath` | `string` | Путь к файлу стенограммы сессии | -Пользовательские перехватчики поддерживают транзитивные локальные импорты, async/await и доступ к `process.env`. Ошибки работают в открытом режиме (регистрируются в `~/.failproofai/hook.log`, встроенные политики продолжаются). Смотрите [docs/custom-hooks.mdx](docs/custom-hooks.mdx) для полного руководства. +Пользовательские хуки поддерживают транзитивные локальные импорты, async/await и доступ к `process.env`. Ошибки работают в режиме открытого отказа (логируются в `~/.failproofai/hook.log`, встроенные политики продолжают работу). Полное руководство см. в [docs/custom-hooks.mdx](docs/custom-hooks.mdx). ### Политики на основе соглашений -Поместите файлы `*policies.{js,mjs,ts}` в `.failproofai/policies/` и они автоматически загружаются — без флагов или изменений конфигурации. Зафиксируйте каталог в git и каждый участник команды автоматически получит одинаковые стандарты качества. +Поместите файлы `*policies.{js,mjs,ts}` в `.failproofai/policies/` и они автоматически загружаются — без флагов или изменений конфигурации. Зафиксируйте директорию в git и каждый член команды получит одни и те же стандарты качества автоматически. ```text -# Уровень проекта — зафиксирован в git, поделен с командой +# Уровень проекта — зафиксировано в git, поделено с командой .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# Уровень пользователя — личный, применяется ко всем проектам +# Уровень пользователя — личные, применяются ко всем проектам ~/.failproofai/policies/my-policies.mjs ``` -Обе уровни загружаются (объединение). Файлы загружаются в алфавитном порядке в каждом каталоге. Добавьте префикс `01-`, `02-` и т. д., чтобы управлять порядком. По мере того, как ваша команда обнаруживает новые режимы отказа, добавляйте политику и выполняйте push — все получат обновление при следующем pull. Смотрите [examples/convention-policies/](examples/convention-policies/) для готовых к использованию примеров. +Оба уровня загружаются (объединение). Файлы загружаются в алфавитном порядке в каждом каталоге. Для управления порядком используйте префиксы `01-`, `02-` и т. д. По мере того как ваша команда обнаруживает новые режимы отказа, добавляйте политику и отправляйте — все получат обновление при следующем pull. Примеры готовых к использованию примеров см. в [examples/convention-policies/](examples/convention-policies/). --- ## Телеметрия -Failproof AI собирает анонимную телеметрию использования через PostHog для понимания использования функций. Содержание сессии, имена файлов, входные данные инструментов или личная информация никогда не отправляются. +Failproof AI собирает анонимную телеметрию использования через PostHog для понимания использования функций. Содержимое сессии, имена файлов, вводы инструментов или личная информация никогда не отправляются. -Отключите это: +Отключить: ```bash FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai @@ -288,13 +315,13 @@ FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai ## Документация | Руководство | Описание | -|-------------|---------| -| [Начало работы](docs/getting-started.mdx) | Установка и первые шаги | +|-------|-------------| +| [Быстрый старт](docs/getting-started.mdx) | Установка и первые шаги | | [Встроенные политики](docs/built-in-policies.mdx) | Все 39 встроенных политик с параметрами | | [Пользовательские политики](docs/custom-policies.mdx) | Напишите свои политики | -| [Конфигурация](docs/configuration.mdx) | Формат файла конфигурации и объединение областей | -| [Панель мониторинга](docs/dashboard.mdx) | Мониторьте сессии и просматривайте активность политик | -| [Архитектура](docs/architecture.mdx) | Как работает система перехватчиков | +| [Конфигурация](docs/configuration.mdx) | Формат конфигурационного файла и объединение областей | +| [Панель управления](docs/dashboard.mdx) | Мониторинг сессий и анализ активности политик | +| [Архитектура](docs/architecture.mdx) | Как работает система хуков | | [Тестирование](docs/testing.mdx) | Запуск тестов и написание новых | ### Запустите документацию локально @@ -312,9 +339,9 @@ docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs --- -## Примечание для участников failproofai +## Примечание для соавторов failproofai -Файл `.claude/settings.json` этого репозитория использует `bun ./bin/failproofai.mjs --hook ` вместо стандартной команды `npx -y failproofai`. Это потому, что запуск `npx -y failproofai` внутри самого проекта failproofai создаёт конфликт самоссылки. +`.claude/settings.json` этого репозитория использует `bun ./bin/failproofai.mjs --hook ` вместо стандартной команды `npx -y failproofai`. Это потому, что запуск `npx -y failproofai` внутри самого проекта failproofai создаёт конфликт саморефернции. Для всех остальных репозиториев рекомендуемый подход — `npx -y failproofai`, установленный через: @@ -322,16 +349,16 @@ docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs failproofai policies --install --scope project ``` -## Вклад +## Участие в разработке -Смотрите [CONTRIBUTING.md](CONTRIBUTING.md). +См. [CONTRIBUTING.md](CONTRIBUTING.md). --- ## Лицензия -Смотрите [LICENSE](LICENSE). +См. [LICENSE](LICENSE). --- -Создано и поддерживается **ExosphereHost: Reliability Research Lab for Your Agents**. Мы помогаем предприятиям и стартапам улучшить надёжность своих AI-агентов через собственных агентов, программное обеспечение и опыт. Узнайте больше на [exosphere.host](https://exosphere.host). +Построено и поддерживается **ExosphereHost: Reliability Research Lab for Your Agents**. Мы помогаем предприятиям и стартапам повысить надёжность своих AI-агентов через собственных агентов, программное обеспечение и экспертизу. Узнайте больше на [exosphere.host](https://exosphere.host). diff --git a/docs/i18n/README.tr.md b/docs/i18n/README.tr.md index b2a348b9..fe609b8a 100644 --- a/docs/i18n/README.tr.md +++ b/docs/i18n/README.tr.md @@ -23,13 +23,13 @@ **Ç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) -AI aracılarınızı güvenilir, odaklanmış ve otonom olarak çalıştıran politikaları yönetmenin en kolay yolu - **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(beta)_ ve **Agents SDK** için. +AI ajanlarınızı güvenilir, odaklı ve otonom olarak çalışan halde tutmak için politikaları yönetmenin en kolay yolu - **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(beta)_, **Cursor Agent** _(beta)_, **OpenCode** _(beta)_, **Pi** _(beta)_, **Gemini CLI** _(beta)_ & **Agents SDK** için.

- Failproof AI çalışırken + Failproof AI in action

-## Desteklenen ajan CLI'ları +## Desteklenen ajans CLI'ları

@@ -50,28 +50,55 @@ AI aracılarınızı güvenilir, odaklanmış ve otonom olarak çalıştıran po        - + yakında daha fazlası + + + + Cursor Agent + + +

+

+ + + + OpenCode + + +        + + + + Pi + + +        + + + + Gemini CLI + +

-> Bir, iki veya üçünün tümüne kancalar yükleyin: `failproofai policies --install --cli copilot` (veya `--cli claude codex copilot`). Yüklü CLI'ları otomatik olarak algılamak ve sorulmak için `--cli` kullanmayın. **GitHub Copilot CLI desteği beta aşamasındadır.** +> Hook'ları tek bir veya herhangi bir kombinasyon için yükleyin: `failproofai policies --install --cli opencode pi gemini` (veya `--cli claude codex copilot cursor opencode pi gemini`). `--cli` parametresini atlayarak yüklü CLI'ları otomatik olarak algılatıp seçim yapmak isteyebilirsiniz. **GitHub Copilot CLI, Cursor Agent, OpenCode, Pi ve Gemini CLI desteği beta aşamasındadır — testler devam etmektedir.** -- **39 Yerleşik Politika** - Kutudan çıkar çıkmaz yaygın ajan başarısızlık modlarını yakala. Yıkıcı komutları engelle, gizli kaçışını önle, ajanları proje sınırları içinde tut, döngüleri tespit et ve daha fazlasını yap. -- **Özel Politikalar** - JavaScript'te kendi güvenilirlik kurallarını yaz. Kuralları uygula, sürüklemeyi önle, işlemleri kapat veya harici sistemlerle entegre olmak için `allow`/`deny`/`instruct` API'sini kullan. -- **Kolay Yapılandırma** - Kod yazmadan herhangi bir politikayı ayarla. İzin listeleri, korumalı dallar, eşik değerlerini proje başına veya genel olarak ayarla. Üç kapsamlı yapılandırma otomatik olarak birleşir. -- **Ajan İzleme** - Ajanlarının seni yokken ne yaptığını gör. Oturumları gözat, her araç çağrısını incele ve politikaların tam olarak nerede çalıştığını gözden geçir. +- **39 Yerleşik Politika** - Yaygın ajans hatasını hemen tespit edin. Yıkıcı komutları engelleyin, gizli diziler sızmasını önleyin, ajanları proje sınırları içinde tutun, döngüleri algılayın ve daha fazlası. +- **Özel Politikalar** - JavaScript'te kendi güvenilirlik kurallarınızı yazın. Kuralları uygulamak, kaymaları önlemek, işlemleri kapılaştırmak veya dış sistemlerle entegre olmak için `allow`/`deny`/`instruct` API'sini kullanın. +- **Kolay Yapılandırma** - Kod yazmadan herhangi bir politikayı ayarlayın. İzin listelerini ayarlayın, korunan dalları seçin, eşikleri proje başına veya global olarak belirleyin. Üç kapsam yapılandırması otomatik olarak birleştirilir. +- **Ajans Monitörü** - Ajanlarınız yokken neler yaptığını görün. Oturumları inceleyin, her araç çağrısını denetleyin ve politikaların tam olarak nerede etkinleştiğini gözden geçirin. -Her şey yerel olarak çalışır - verileriniz makinenizi terk etmez. +Her şey yerel olarak çalışır - hiçbir veri makinenizi terk etmez. --- ## Gereksinimler - Node.js >= 20.9.0 -- Bun >= 1.3.0 (isteğe bağlı - yalnızca geliştirme / kaynaktan derleme için gerekli) +- Bun >= 1.3.0 (isteğe bağlı - sadece geliştirme / kaynaktan derlemek için gerekli) --- -## Yükle +## Yükleme ```bash npm install -g failproofai @@ -83,23 +110,23 @@ bun add -g failproofai ## Hızlı başlangıç -### 1. Politikaları genel olarak etkinleştir +### 1. Politikaları global olarak etkinleştirin ```bash failproofai policies --install ``` -`~/.claude/settings.json` içine kanca girdileri yazar. Claude Code artık her araç çağrısından önce ve sonra failproofai'yi çağıracak. +`~/.claude/settings.json` dosyasına hook girişlerini yazar. Claude Code artık her araç çağrısından önce ve sonra failproofai'yi çağıracaktır. -### 2. Paneli başlat +### 2. Panoyu açın ```bash failproofai ``` -`http://localhost:8020` açar - oturumları gözat, günlükleri incele, politikaları yönet. +`http://localhost:8020` açılır - oturumları inceleyin, günlükleri görüntüleyin, politikaları yönetin. -### 3. Nelerin etkin olduğunu kontrol et +### 3. Aktif olanları kontrol edin ```bash failproofai policies @@ -111,19 +138,19 @@ failproofai policies ### Kapsamlar -| Kapsam | Komut | Nereye yazar | -|-------|-------|-------------| -| Genel (varsayılan) | `failproofai policies --install` | `~/.claude/settings.json` | +| Kapsam | Komut | Nereye yazılır | +|--------|---------|-----------------| +| Global (varsayılan) | `failproofai policies --install` | `~/.claude/settings.json` | | Proje | `failproofai policies --install --scope project` | `.claude/settings.json` | | Yerel | `failproofai policies --install --scope local` | `.claude/settings.local.json` | -### Belirli politikaları yükle +### Belirli politikaları yükleyin ```bash failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ``` -### Politikaları kaldır +### Politikaları kaldırın ```bash failproofai policies --uninstall @@ -135,7 +162,7 @@ failproofai policies --uninstall --scope project ## Yapılandırma -Politika yapılandırması `~/.failproofai/policies-config.json` (genel) veya proje içi `.failproofai/policies-config.json` adresinde bulunur. +Politika yapılandırması `~/.failproofai/policies-config.json` (global) veya projenizde `.failproofai/policies-config.json` dosyasında bulunur. ```json { @@ -150,15 +177,15 @@ Politika yapılandırması `~/.failproofai/policies-config.json` (genel) veya pr "policyParams": { "block-sudo": { "allowPatterns": ["sudo systemctl status", "sudo journalctl"], - "hint": "sudo olmadan apt-get'i doğrudan kullan." + "hint": "sudo kullanmadan apt-get'i doğrudan kullanın." }, "block-push-master": { "protectedBranches": ["main", "release", "prod"], - "hint": "Bunun yerine yeni bir dal oluşturmayı dene." + "hint": "Bunun yerine yeni bir dal oluşturmayı deneyin." }, "sanitize-api-keys": { "additionalPatterns": [ - { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" } + { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API anahtarı" } ] }, "warn-large-file-write": { @@ -168,39 +195,39 @@ Politika yapılandırması `~/.failproofai/policies-config.json` (genel) veya pr } ``` -**Üç yapılandırma kapsamı** otomatik olarak birleştirilir (proje → yerel → genel). Tam birleştirme kuralları için [docs/configuration.mdx](docs/configuration.mdx) bkz. +**Üç yapılandırma kapsamı** otomatik olarak birleştirilir (proje → yerel → global). Tam birleştirme kuralları için [docs/configuration.mdx](docs/configuration.mdx) dosyasını inceleyebilirsiniz. --- ## Yerleşik politikalar | Politika | Açıklama | Yapılandırılabilir | -|---------|---------|:---:| +|--------|-------------|:---:| | `block-sudo` | Ajanları ayrıcalıklı sistem komutlarını çalıştırmaktan engelle | `allowPatterns` | -| `block-rm-rf` | Yanlışlıkla yapılan özyinelemeli dosya silmeyi engelle | `allowPaths` | -| `block-curl-pipe-sh` | Ajanları güvenilmeyen betikleri kabuğa yönlendirmekten engelle | | +| `block-rm-rf` | Tesadüfi özyineli dosya silmesini engelle | `allowPaths` | +| `block-curl-pipe-sh` | Ajanları güvenilmez komut dosyalarını shell'e yönlendirmekten engelle | | | `block-failproofai-commands` | Kendi kaldırılmasını engelle | | -| `sanitize-jwt` | JWT belirteçlerinin ajan bağlamına sızmasını durdur | | -| `sanitize-api-keys` | API anahtarlarının ajan bağlamına sızmasını durdur | `additionalPatterns` | -| `sanitize-connection-strings` | Veritabanı kimlik bilgilerinin ajan bağlamına sızmasını durdur | | -| `sanitize-private-key-content` | Çıktıdan PEM özel anahtar bloklarını gizle | | -| `sanitize-bearer-tokens` | Çıktıdan Authorization Bearer belirteçlerini gizle | | +| `sanitize-jwt` | JWT belirteçlerinin ajans bağlamına sızmasını durdur | | +| `sanitize-api-keys` | API anahtarlarının ajans bağlamına sızmasını durdur | `additionalPatterns` | +| `sanitize-connection-strings` | Veritabanı kimlik bilgilerinin ajans bağlamına sızmasını durdur | | +| `sanitize-private-key-content` | PEM özel anahtar bloklarını çıktıdan redakte et | | +| `sanitize-bearer-tokens` | Authorization Bearer belirteçlerini çıktıdan redakte et | | | `block-env-files` | Ajanları .env dosyalarını okumaktan engelle | | | `protect-env-vars` | Ajanları ortam değişkenlerini yazdırmaktan engelle | | | `block-read-outside-cwd` | Ajanları proje sınırları içinde tut | `allowPaths` | -| `block-secrets-write` | Özel anahtar ve sertifika dosyalarına yazılışları engelle | `additionalPatterns` | -| `block-push-master` | Ana/master dalına yanlışlıkla yapılan gönderimleri engelle | `protectedBranches` | -| `block-work-on-main` | Ajanları korumalı dallardan uzak tut | `protectedBranches` | -| `block-force-push` | `git push --force` komutunu engelle | | -| `warn-git-amend` | Ajanları taahhütleri değiştirmeden önce uyar | | +| `block-secrets-write` | Özel anahtar ve sertifika dosyalarına yazmaları engelle | `additionalPatterns` | +| `block-push-master` | Tesadüfi ana/master dalına göndermeyi engelle | `protectedBranches` | +| `block-work-on-main` | Ajanları korunan dallardan uzak tut | `protectedBranches` | +| `block-force-push` | `git push --force`'u engelle | | +| `warn-git-amend` | Ajanları commit'i değiştirmeden önce uyar | | | `warn-git-stash-drop` | Ajanları stash'i bırakmadan önce uyar | | -| `warn-all-files-staged` | Yanlışlıkla yapılan `git add -A` komutunu yakala | | -| `warn-destructive-sql` | DROP/DELETE SQL komutlarını yürütülmeden önce yakala | | -| `warn-schema-alteration` | ALTER TABLE komutlarını yürütülmeden önce yakala | | +| `warn-all-files-staged` | Tesadüfi `git add -A`'yı yakala | | +| `warn-destructive-sql` | DROP/DELETE SQL'ini yürütmeden önce yakala | | +| `warn-schema-alteration` | ALTER TABLE'ı yürütmeden önce yakala | | | `warn-large-file-write` | Beklenmedik şekilde büyük dosya yazışlarını yakala | `thresholdKb` | -| `warn-package-publish` | Yanlışlıkla yapılan `npm publish` komutunu yakala | | -| `warn-background-process` | Amaçlanan olmayan arka plan işlem başlatmalarını yakala | | -| `warn-global-package-install` | Amaçlanan olmayan genel paket kurulumlarını yakala | | +| `warn-package-publish` | Tesadüfi `npm publish`'i yakala | | +| `warn-background-process` | Istenmeyen arka plan işlemini başlatmayı yakala | | +| `warn-global-package-install` | Istenmeyen global paket kurulumunu yakala | | | …ve daha fazlası | | | Tam politika detayları ve parametre referansı: [docs/built-in-policies.mdx](docs/built-in-policies.mdx) @@ -209,25 +236,25 @@ Tam politika detayları ve parametre referansı: [docs/built-in-policies.mdx](do ## Özel politikalar -Ajanları güvenilir ve odaklanmış tutmak için kendi politikalarını yaz: +Ajanları güvenilir ve odaklı tutmak için kendi politikalarınızı yazın: ```js import { customPolicies, allow, deny, instruct } from "failproofai"; customPolicies.add({ name: "no-production-writes", - description: "'production' içeren yollara yazışları engelle", + description: "Üretim yolunu içeren yollara yazmaları engelle", match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow(); const path = ctx.toolInput?.file_path ?? ""; - if (path.includes("production")) return deny("Production yollarına yazışlar engellendi"); + if (path.includes("production")) return deny("Üretim yollarına yazma işlemleri engellenmektedir"); return allow(); }, }); ``` -Yükle: +Aşağıdaki komutla yükleyin: ```bash failproofai policies --install --custom ./my-policies.js @@ -235,41 +262,41 @@ failproofai policies --install --custom ./my-policies.js ### Karar yardımcıları -| Fonksiyon | Etki | -|-----------|------| +| İşlev | Etki | +|----------|--------| | `allow()` | İşleme izin ver | -| `allow(message)` | İşleme izin ver ve Claude'a bilgilendirici bağlam gönder | +| `allow(message)` | İzin ver ve Claude'a bilgilendirici bağlam gönder | | `deny(message)` | İşlemi engelle; ileti Claude'a gösterilir | -| `instruct(message)` | Claude'un istemi için bağlam ekle; engelleme yapma | +| `instruct(message)` | Claude'un isteme bağlam ekle; engelleme yapma | ### Bağlam nesnesi (`ctx`) | Alan | Tür | Açıklama | -|------|-----|---------| +|-------|------|-------------| | `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | | `toolName` | `string` | Çağrılan araç (`"Bash"`, `"Write"`, `"Read"`, …) | | `toolInput` | `object` | Aracın giriş parametreleri | -| `payload` | `object` | Tam ham olay verisi | +| `payload` | `object` | Tam ham olay yükü | | `session.cwd` | `string` | Claude Code oturumunun çalışma dizini | | `session.sessionId` | `string` | Oturum tanımlayıcısı | | `session.transcriptPath` | `string` | Oturum transkripti dosyasının yolu | -Özel kancalar geçişli yerel içeri aktarmaları, async/await'i ve `process.env` erişimini destekler. Hatalar açık başarısız olur (günlüğe `~/.failproofai/hook.log` dosyasına kaydedilir, yerleşik politikalar devam eder). Tam rehber için [docs/custom-hooks.mdx](docs/custom-hooks.mdx) bkz. +Özel hook'lar geçişli yerel içe aktarımları, async/await'i ve `process.env` erişimini destekler. Hatalar açık başarısız olur (günlükleri `~/.failproofai/hook.log` dosyasına yazılır, yerleşik politikalar devam eder). Tam kılavuz için [docs/custom-hooks.mdx](docs/custom-hooks.mdx) dosyasını inceleyebilirsiniz. ### Kural tabanlı politikalar -`.failproofai/policies/` dizinine `*policies.{js,mjs,ts}` dosyaları bırak ve otomatik olarak yüklenir — bayrak veya yapılandırma değişikliği gerekmez. Dizini git'e kaydet ve her ekip üyesi otomatik olarak aynı kalite standartlarını alır. +`*policies.{js,mjs,ts}` dosyalarını `.failproofai/policies/` klasörüne bırakın ve otomatik olarak yüklenir — bayrak veya yapılandırma değişikliğine gerek yok. Klasörü git'e commit edin ve her takım üyesi aynı kalite standartlarını otomatik olarak alır. ```text -# Proje seviyesi — git'e kaydedildi, ekiple paylaşıldı +# Proje seviyesi — git'e commit edilmiş, takımla paylaşılmış .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# Kullanıcı seviyesi — kişisel, tüm projelere uygulandı +# Kullanıcı seviyesi — kişisel, tüm projeler için geçerli ~/.failproofai/policies/my-policies.mjs ``` -Her iki seviye de yüklenir (birleştirme). Dosyalar her dizinde alfabetik olarak yüklenir. Sırayı kontrol etmek için `01-`, `02-`, vb. ile başla. Ekibiniz yeni başarısızlık modları keşfettikçe, bir politika ekle ve gönder — herkes sonraki çekişinde güncelleştirir. Hazır kullanılır örnekler için [examples/convention-policies/](examples/convention-policies/) bkz. +Her iki seviye de yüklenir (birleşim). Dosyalar her dizin içinde alfabetik olarak yüklenir. Sırayı kontrol etmek için `01-`, `02-` vb. ile önek ekleyin. Takımınız yeni hata modlarını keşfettikçe, bir politika ekleyin ve gönderin — herkes bir sonraki pull işleminde güncellemeyi alır. Hazır örnekler için [examples/convention-policies/](examples/convention-policies/) dosyasını inceleyebilirsiniz. --- @@ -277,7 +304,7 @@ Her iki seviye de yüklenir (birleştirme). Dosyalar her dizinde alfabetik olara Failproof AI, özellik kullanımını anlamak için PostHog aracılığıyla anonim kullanım telemetrisi toplar. Oturum içeriği, dosya adları, araç girdileri veya kişisel bilgiler asla gönderilmez. -Devre dışı bırak: +Devre dışı bırakmak için: ```bash FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai @@ -285,26 +312,26 @@ FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai --- -## Belgelendirme +## Dokümantasyon -| Rehber | Açıklama | -|--------|----------| -| [Başlangıç](docs/getting-started.mdx) | Kurulum ve ilk adımlar | -| [Yerleşik Politikalar](docs/built-in-policies.mdx) | 39 yerleşik politika ve parametreler | -| [Özel Politikalar](docs/custom-policies.mdx) | Kendi politikalarını yaz | -| [Yapılandırma](docs/configuration.mdx) | Yapılandırma dosyası biçimi ve kapsam birleştirmesi | -| [Pano](docs/dashboard.mdx) | Oturumları izle ve politika etkinliğini gözden geçir | -| [Mimari](docs/architecture.mdx) | Kanca sistemi nasıl çalışır | -| [Test Etme](docs/testing.mdx) | Testleri çalıştır ve yenilerini yaz | +| Kılavuz | Açıklama | +|-------|-------------| +| [Başlarken](docs/getting-started.mdx) | Kurulum ve ilk adımlar | +| [Yerleşik Politikalar](docs/built-in-policies.mdx) | Parametreli tüm 39 yerleşik politika | +| [Özel Politikalar](docs/custom-policies.mdx) | Kendi politikalarınızı yazın | +| [Yapılandırma](docs/configuration.mdx) | Yapılandırma dosyası biçimi ve kapsam birleştirme | +| [Pano](docs/dashboard.mdx) | Oturumları izleyin ve politika etkinliğini gözden geçirin | +| [Mimari](docs/architecture.mdx) | Hook sistemi nasıl çalışır | +| [Test Etme](docs/testing.mdx) | Testleri çalıştırın ve yenilerini yazın | -### Belgeleri yerel olarak çalıştır +### Dokümanları yerel olarak çalıştırın ```bash docker build -f Dockerfile.docs -t failproofai-docs . docker run --rm -p 3000:3000 failproofai-docs ``` -Mintlify belgelendirme sitesini `http://localhost:3000` adresinde açar. Belgelendirme dizinini bağlarsan, kapsayıcı değişiklikleri izler: +`http://localhost:3000` adresinde Mintlify doküman sitesini açar. Konteyner doküman dizinini bağlarsanız değişiklikleri izler: ```bash docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs @@ -312,28 +339,27 @@ docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs --- -## failproofai katkıda bulunanları için not +## failproofai katkıda bulunanlar için not -Bu repoyu `.claude/settings.json`, standart `npx -y failproofai` komutu yerine `bun ./bin/failproofai.mjs --hook ` kullanır. Bunun nedeni, failproofai projesi içinde `npx -y failproofai` çalıştırmanın kendi kendine referans çatışması oluşturmasıdır. +Bu deponun `.claude/settings.json` dosyası standart `npx -y failproofai` komutu yerine `bun ./bin/failproofai.mjs --hook ` komutunu kullanır. Bunun nedeni, failproofai projesi içinde `npx -y failproofai` komutunu çalıştırmanın kendi kendine referans veren bir çatışma oluşturmasıdır. -Tüm diğer repolar için, önerilen yaklaşım `npx -y failproofai` olup: +Diğer tüm depolar için önerilen yaklaşım `npx -y failproofai` komutudur ve aşağıdaki komutla yüklenir: ```bash failproofai policies --install --scope project ``` -ile kurulur. +## Katkıda bulunma -## Katkıda Bulunma - -[CONTRIBUTING.md](CONTRIBUTING.md) bkz. +[CONTRIBUTING.md](CONTRIBUTING.md) dosyasını inceleyebilirsiniz. --- ## Lisans -[LICENSE](LICENSE) bkz. +[LICENSE](LICENSE) dosyasını inceleyebilirsiniz. --- -**ExosphereHost: Ajanlarınızın Güvenilirlik Araştırması Laboratuvarı** tarafından oluşturulmuş ve bakımlanmaktadır. Kurumsal ve başlangıç şirketlerinin AI ajanlarının güvenilirliğini kendi ajanları, yazılımı ve uzmanlığı aracılığıyla geliştirmemize yardımcı oluyoruz. [exosphere.host](https://exosphere.host) adresinden daha fazla bilgi edinin. +**ExosphereHost: Ajanlarınız için Güvenilirlik Araştırması Laboratuvarı** tarafından oluşturulmuş ve yönetilmektedir. Kuruluşlar ve yeni başlayanların AI ajanlarının güvenilirliğini kendi ajanları, yazılımı ve uzmanlığı aracılığıyla artırmasına yardımcı oluyoruz. Daha fazla bilgi için [exosphere.host](https://exosphere.host) adresini ziyaret edin. +``` diff --git a/docs/i18n/README.vi.md b/docs/i18n/README.vi.md index dac49fc9..3796a76e 100644 --- a/docs/i18n/README.vi.md +++ b/docs/i18n/README.vi.md @@ -23,13 +23,13 @@ **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) -Cách dễ nhất để quản lý các chính sách giúp tác nhân AI của bạn đáng tin cậy, tập trung vào nhiệm vụ và chạy độc lập - cho **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(phiên bản beta)_ & **Agents SDK**. +Cách dễ nhất để quản lý các chính sách giữ cho các AI agent của bạn đáng tin cậy, tập trung vào công việc và chạy tự động - cho **Claude Code**, **OpenAI Codex**, **GitHub Copilot CLI** _(beta)_, **Cursor Agent** _(beta)_, **OpenCode** _(beta)_, **Pi** _(beta)_, **Gemini CLI** _(beta)_ & **Agents SDK**.

Failproof AI in action

-## Các CLI tác nhân được hỗ trợ +## Agent CLIs được hỗ trợ

@@ -50,24 +50,51 @@ Cách dễ nhất để quản lý các chính sách giúp tác nhân AI của b        - + nhiều thứ khác sắp ra mắt + + + + Cursor Agent + + +

+

+ + + + OpenCode + + +        + + + + Pi + + +        + + + + Gemini CLI + +

-> Cài đặt hooks cho một, hai hoặc cả ba: `failproofai policies --install --cli copilot` (hoặc `--cli claude codex copilot`). Bỏ qua `--cli` để tự động phát hiện các CLI đã cài đặt và nhắc. **Hỗ trợ GitHub Copilot CLI đang ở phiên bản beta.** +> Cài đặt hooks cho một hoặc bất kỳ kết hợp nào: `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 cài đặt và nhắc nhở. **Hỗ trợ GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, và Gemini CLI đang ở giai đoạn beta — kiểm tra đang tiếp tục.** -- **39 Chính sách Tích hợp** - Bắt các chế độ lỗi tác nhân phổ biến ngay từ đầu. Chặn các lệnh phá hoại, ngăn chặn rò rỉ bí mật, giữ tác nhân trong ranh giới dự án, phát hiện vòng lặp, và nhiều hơn nữa. -- **Chính sách Tùy chỉnh** - Viết các quy tắc độ tin cậy của riêng bạn bằng JavaScript. Sử dụng API `allow`/`deny`/`instruct` để thực thi quy ước, ngăn chặn sự thay đổi, kiểm soát hoạt động, hoặc tích hợp với các hệ thống bên ngoài. -- **Cấu hình Dễ dàng** - Điều chỉnh bất kỳ chính sách nào mà không viết mã. Đặt danh sách cho phép, nhánh được bảo vệ, ngưỡng cho mỗi dự án hoặc trên toàn cầu. Cấu hình ba phạm vi hợp nhất tự động. -- **Giám sát Tác nhân** - Xem những gì tác nhân của bạn đã làm trong khi bạn vắng mặt. Duyệt các phiên, kiểm tra mọi lệnh gọi công cụ, và xem xét chính xác nơi các chính sách được kích hoạt. +- **39 Chính sách tích hợp** - Bắt các chế độ lỗi agent phổ biến ngay từ đầu. 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, phát hiện vòng lặp và nhiều hơn nữa. +- **Chính sách tùy chỉnh** - Viết các quy tắc độ tin cậy của riêng bạn bằng JavaScript. Sử dụng API `allow`/`deny`/`instruct` để thực thi các quy ước, ngăn chặn sai lệch, kiểm soát các hoạt động hoặc tích hợp với các hệ thống bên ngoài. +- **Cấu hình dễ dàng** - Điều chỉnh bất kỳ chính sách nào mà không cần viết mã. Đặt danh sách cho phép, nhánh được bảo vệ, ngưỡng theo dự án hoặc trên toàn cầu. Hợp nhất cấu hình ba phạm vi tự động. +- **Agent Monitor** - Xem những gì các agent của bạn đã làm khi bạn đã đi. Duyệt qua các phiên, kiểm tra từng lệnh công cụ và xem chính xác nơi các chính sách được kích hoạt. -Mọi thứ chạy cục bộ - không có dữ liệu nào rời khỏi máy của bạn. +Mọi thứ chạy cục bộ - không có dữ liệu nào rời khỏi máy tính của bạn. --- ## Yêu cầu - Node.js >= 20.9.0 -- Bun >= 1.3.0 (tùy chọn - chỉ cần thiết để phát triển / xây dựng từ nguồn) +- Bun >= 1.3.0 (tùy chọn - chỉ cần cho phát triển / xây dựng từ nguồn) --- @@ -75,7 +102,7 @@ Mọi thứ chạy cục bộ - không có dữ liệu nào rời khỏi máy c ```bash npm install -g failproofai -# hoặc +# or bun add -g failproofai ``` @@ -83,21 +110,21 @@ bun add -g failproofai ## Bắt đầu nhanh -### 1. Kích hoạt chính sách trên toàn cầu +### 1. Bật chính sách toàn cầu ```bash failproofai policies --install ``` -Ghi mục hook vào `~/.claude/settings.json`. Claude Code hiện sẽ gọi failproofai trước và sau mỗi lệnh gọi công cụ. +Ghi các mục hook vào `~/.claude/settings.json`. Claude Code sẽ gọi failproofai trước và sau mỗi lệnh công cụ. -### 2. Khởi chạy bảng điều khiển +### 2. Khởi động bảng điều khiển ```bash failproofai ``` -Mở `http://localhost:8020` - duyệt các phiên, kiểm tra nhật ký, quản lý chính sách. +Mở `http://localhost:8020` - duyệt qua các phiên, kiểm tra nhật ký, quản lý chính sách. ### 3. Kiểm tra những gì đang hoạt động @@ -112,7 +139,7 @@ failproofai policies ### Phạm vi | Phạm vi | Lệnh | Nơi nó ghi | -|--------|------|------------| +|-------|---------|-----------------| | Toàn cầu (mặc định) | `failproofai policies --install` | `~/.claude/settings.json` | | Dự án | `failproofai policies --install --scope project` | `.claude/settings.json` | | Cục bộ | `failproofai policies --install --scope local` | `.claude/settings.local.json` | @@ -127,7 +154,7 @@ failproofai policies --install block-sudo block-rm-rf sanitize-api-keys ```bash failproofai policies --uninstall -# hoặc cho một phạm vi cụ thể: +# or for a specific scope: failproofai policies --uninstall --scope project ``` @@ -172,35 +199,35 @@ Cấu hình chính sách nằm trong `~/.failproofai/policies-config.json` (toà --- -## Chính sách tích hợp sẵn +## Chính sách tích hợp | Chính sách | Mô tả | Có thể cấu hình | -|-----------|-------|:---:| -| `block-sudo` | Ngăn tác nhân chạy các lệnh hệ thống có quyền cao | `allowPatterns` | +|--------|-------------|:---:| +| `block-sudo` | Ngăn agent chạy các lệnh hệ thống có quyền | `allowPatterns` | | `block-rm-rf` | Ngăn xóa tệp đệ quy vô tình | `allowPaths` | -| `block-curl-pipe-sh` | Ngăn tác nhân piping các tập lệnh không đáng tin cậy vào shell | | +| `block-curl-pipe-sh` | Ngăn agent từ piping các tập lệnh không đáng tin cậy vào shell | | | `block-failproofai-commands` | Ngăn tự gỡ cài đặt | | -| `sanitize-jwt` | Dừng rò rỉ JWT token vào bối cảnh tác nhân | | -| `sanitize-api-keys` | Dừng rò rỉ khóa API vào bối cảnh tác nhân | `additionalPatterns` | -| `sanitize-connection-strings` | Dừng rò rỉ thông tin xác thực cơ sở dữ liệu vào bối cảnh tác nhân | | -| `sanitize-private-key-content` | Che phủ các khối khóa riêng PEM khỏi đầu ra | | -| `sanitize-bearer-tokens` | Che phủ các token Authorization Bearer khỏi đầu ra | | -| `block-env-files` | Giữ tác nhân tránh khỏi việc đọc tệp .env | | -| `protect-env-vars` | Ngăn tác nhân in các biến môi trường | | -| `block-read-outside-cwd` | Giữ tác nhân trong ranh giới dự án | `allowPaths` | -| `block-secrets-write` | Ngăn ghi vào các tệp khóa riêng và chứng chỉ | `additionalPatterns` | -| `block-push-master` | Ngăn đẩy vô tình đến main/master | `protectedBranches` | -| `block-work-on-main` | Giữ tác nhân tránh khỏi các nhánh được bảo vệ | `protectedBranches` | +| `sanitize-jwt` | Dừng JWT token rò rỉ vào ngữ cảnh agent | | +| `sanitize-api-keys` | Dừng API key rò rỉ vào ngữ cảnh agent | `additionalPatterns` | +| `sanitize-connection-strings` | Dừng thông tin xác thực cơ sở dữ liệu rò rỉ vào ngữ cảnh agent | | +| `sanitize-private-key-content` | Làm mờ các khối khóa riêng PEM khỏi đầu ra | | +| `sanitize-bearer-tokens` | Làm mờ các Authorization Bearer token khỏi đầu ra | | +| `block-env-files` | Giữ agent khỏi đọc tệp .env | | +| `protect-env-vars` | Ngăn agent in biến môi trường | | +| `block-read-outside-cwd` | Giữ agent trong ranh giới dự án | `allowPaths` | +| `block-secrets-write` | Ngăn ghi vào tệp khóa riêng và chứng chỉ | `additionalPatterns` | +| `block-push-master` | Ngăn đẩy vô tình lên main/master | `protectedBranches` | +| `block-work-on-main` | Giữ agent khỏi các nhánh được bảo vệ | `protectedBranches` | | `block-force-push` | Ngăn `git push --force` | | -| `warn-git-amend` | Nhắc tác nhân trước khi sửa đổi commit | | -| `warn-git-stash-drop` | Nhắc tác nhân trước khi bỏ stashes | | +| `warn-git-amend` | Nhắc nhở agent trước khi sửa đổi commit | | +| `warn-git-stash-drop` | Nhắc nhở agent trước khi thả stash | | | `warn-all-files-staged` | Bắt `git add -A` vô tình | | -| `warn-destructive-sql` | Bắt DROP/DELETE SQL trước khi thực thi | | +| `warn-destructive-sql` | Bắt SQL DROP/DELETE trước khi thực thi | | | `warn-schema-alteration` | Bắt ALTER TABLE trước khi thực thi | | -| `warn-large-file-write` | Bắt các ghi tệp lớn bất ngờ | `thresholdKb` | +| `warn-large-file-write` | Bắt ghi tệp lớn bất ngờ | `thresholdKb` | | `warn-package-publish` | Bắt `npm publish` vô tình | | -| `warn-background-process` | Bắt các lần khởi chạy quá trình nền không có ý định | | -| `warn-global-package-install` | Bắt cài đặt gói toàn cầu không có ý định | | +| `warn-background-process` | Bắt khởi động quy trình nền không mong muốn | | +| `warn-global-package-install` | Bắt cài đặt gói toàn cầu không mong muốn | | | …và nhiều hơn nữa | | | Chi tiết chính sách đầy đủ và tham chiếu tham số: [docs/built-in-policies.mdx](docs/built-in-policies.mdx) @@ -209,7 +236,7 @@ Chi tiết chính sách đầy đủ và tham chiếu tham số: [docs/built-in- ## Chính sách tùy chỉnh -Viết các chính sách của riêng bạn để giữ tác nhân đáng tin cậy và tập trung vào nhiệm vụ: +Viết chính sách của riêng bạn để giữ cho agent đáng tin cậy và tập trung vào công việc: ```js import { customPolicies, allow, deny, instruct } from "failproofai"; @@ -236,44 +263,44 @@ failproofai policies --install --custom ./my-policies.js ### Trợ giúp quyết định | Hàm | Hiệu ứng | -|-----|---------| +|----------|--------| | `allow()` | Cho phép hoạt động | -| `allow(message)` | Cho phép và gửi bối cảnh thông tin đến Claude | -| `deny(message)` | Chặn hoạt động; thông báo được hiển thị cho Claude | -| `instruct(message)` | Thêm bối cảnh vào lời nhắc của Claude; không chặn | +| `allow(message)` | Cho phép và gửi ngữ cảnh thông tin tới Claude | +| `deny(message)` | Chặn hoạt động; thông báo hiển thị cho Claude | +| `instruct(message)` | Thêm ngữ cảnh vào lời nhắc của Claude; không chặn | -### Đối tượng bối cảnh (`ctx`) +### Đối tượng ngữ cảnh (`ctx`) | Trường | Loại | Mô tả | -|-------|------|-------| -| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` | -| `toolName` | `string` | Công cụ được gọi (`"Bash"`, `"Write"`, `"Read"`, …) | -| `toolInput` | `object` | Tham số đầu vào của công cụ | -| `payload` | `object` | Toàn bộ mupayload sự kiện thô | +|-------|------|-------------| +| `eventType` | `string` | `PreToolUse`, `PostToolUse`, `Notification`, `Stop` | +| `toolName` | `string` | Công cụ được gọi (`Bash`, `Write`, `Read`, …) | +| `toolInput` | `object` | Các tham số đầu vào của công cụ | +| `payload` | `object` | Toàn bộ sự kiện payload thô | | `session.cwd` | `string` | Thư mục làm việc của phiên Claude Code | | `session.sessionId` | `string` | Định danh phiên | -| `session.transcriptPath` | `string` | Đường dẫn đến tệp bản ghi phiên | +| `session.transcriptPath` | `string` | Đường dẫn đến tệp bảng điểm phiên | -Các hook tùy chỉnh hỗ trợ nhập cục bộ chuyên sâu, async/await, và truy cập vào `process.env`. Các lỗi được mở lại (được ghi nhật ký vào `~/.failproofai/hook.log`, các chính sách tích hợp sẵn tiếp tục). Xem [docs/custom-hooks.mdx](docs/custom-hooks.mdx) để biết hướng dẫn đầy đủ. +Hook tùy chỉnh hỗ trợ nhập cục bộ chuyển tiếp, async/await, và truy cập `process.env`. Các lỗi là fail-open (được ghi vào `~/.failproofai/hook.log`, các chính sách tích hợp tiếp tục). Xem [docs/custom-hooks.mdx](docs/custom-hooks.mdx) để biết hướng dẫn đầy đủ. ### Chính sách dựa trên quy ước -Thả các tệp `*policies.{js,mjs,ts}` vào `.failproofai/policies/` và chúng sẽ được tải tự động — không cần cờ hoặc thay đổi cấu hình. Cam kết thư mục vào git và mỗi thành viên nhóm sẽ tự động nhận được các tiêu chuẩn chất lượng giống nhau. +Thả các tệp `*policies.{js,mjs,ts}` vào `.failproofai/policies/` và chúng sẽ được tải tự động — không cần cờ hoặc thay đổi cấu hình. Commit thư mục vào git và mỗi thành viên trong nhóm sẽ tự động nhận được các tiêu chuẩn chất lượng giống nhau. ```text -# Cấp dự án — cam kết vào git, chia sẻ với nhóm +# Cấp dự án — được commit vào git, chia sẻ với nhóm .failproofai/policies/security-policies.mjs .failproofai/policies/workflow-policies.mjs -# Cấp người dùng — cá nhân, áp dụng cho tất cả dự án +# Cấp độ người dùng — cá nhân, áp dụng cho tất cả dự án ~/.failproofai/policies/my-policies.mjs ``` -Cả hai cấp độ được tải (hợp nhất). Các tệp được tải theo bảng chữ cái trong mỗi thư mục. Tiền tố với `01-`, `02-`, v.v. để kiểm soát thứ tự. Khi nhóm của bạn phát hiện các chế độ lỗi mới, hãy thêm một chính sách và đẩy — mọi người sẽ nhận được bản cập nhật khi họ kéo tiếp theo. Xem [examples/convention-policies/](examples/convention-policies/) để biết các ví dụ sẵn sàng sử dụng. +Cả hai cấp tải (liên hợp). Các tệp được tải theo thứ tự bảng chữ cái trong mỗi thư mục. Tiền tố với `01-`, `02-`, v.v. để kiểm soát thứ tự. Khi nhóm của bạn khám phá các chế độ lỗi mới, hãy thêm một chính sách và đẩy — mọi người sẽ nhận được bản cập nhật vào lần pull tiếp theo của họ. Xem [examples/convention-policies/](examples/convention-policies/) để xem các ví dụ sẵn sàng sử dụng. --- -## Telemetry +## Đo lường từ xa Failproof AI thu thập telemetry sử dụng ẩn danh thông qua PostHog để hiểu cách sử dụng tính năng. Không bao giờ gửi nội dung phiên, tên tệp, đầu vào công cụ hoặc thông tin cá nhân. @@ -288,14 +315,14 @@ FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai ## Tài liệu | Hướng dẫn | Mô tả | -|---------|-------| -| [Bắt đầu](docs/getting-started.mdx) | Cài đặt và các bước đầu tiên | -| [Chính sách Tích hợp](docs/built-in-policies.mdx) | Tất cả 39 chính sách tích hợp sẵn với tham số | -| [Chính sách Tùy chỉnh](docs/custom-policies.mdx) | Viết các chính sách của riêng bạn | -| [Cấu hình](docs/configuration.mdx) | Định dạng tệp cấu hình và hợp nhất phạm vi | -| [Bảng điều khiển](docs/dashboard.mdx) | Giám sát phiên và xem xét hoạt động chính sách | -| [Kiến trúc](docs/architecture.mdx) | Cách hệ thống hook hoạt động | -| [Thử nghiệm](docs/testing.mdx) | Chạy các bài kiểm tra và viết những bài mới | +|-------|-------------| +| [Getting Started](docs/getting-started.mdx) | Cài đặt và các bước đầu tiên | +| [Built-in Policies](docs/built-in-policies.mdx) | Tất cả 39 chính sách tích hợp sẵn có các tham số | +| [Custom Policies](docs/custom-policies.mdx) | Viết chính sách của riêng bạn | +| [Configuration](docs/configuration.mdx) | Định dạng tệp cấu hình và hợp nhất phạm vi | +| [Dashboard](docs/dashboard.mdx) | Giám sát phiên và xem lại hoạt động chính sách | +| [Architecture](docs/architecture.mdx) | Cách hệ thống hook hoạt động | +| [Testing](docs/testing.mdx) | Chạy kiểm tra và viết kiểm tra mới | ### Chạy tài liệu cục bộ @@ -312,9 +339,9 @@ docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs --- -## Lưu ý cho những người đóng góp failproofai +## Ghi chú cho những người đóng góp failproofai -`.claude/settings.json` của repo này sử dụng `bun ./bin/failproofai.mjs --hook ` thay vì lệnh `npx -y failproofai` tiêu chuẩn. Điều này là vì chạy `npx -y failproofai` bên trong chính dự án failproofai tạo ra một xung đột tự tham chiếu. +`.claude/settings.json` của repo này sử dụng `bun ./bin/failproofai.mjs --hook ` thay vì lệnh tiêu chuẩn `npx -y failproofai`. Điều này là vì chạy `npx -y failproofai` bên trong chính dự án failproofai tạo ra xung đột tự tham chiếu. Đối với tất cả các repo khác, cách tiếp cận được khuyến nghị là `npx -y failproofai`, được cài đặt thông qua: @@ -334,4 +361,4 @@ Xem [LICENSE](LICENSE). --- -Được xây dựng và duy trì bởi **ExosphereHost: Phòng thí nghiệm nghiên cứu độ tin cậy cho các tác nhân AI của bạn**. Chúng tôi giúp các doanh nghiệp và công ty khởi nghiệp cải thiện độ tin cậy của các tác nhân AI của họ thông qua các tác nhân, phần mềm và chuyên môn của riêng chúng tôi. Tìm hiểu thêm tại [exosphere.host](https://exosphere.host). +Được xây dựng và duy trì bởi **ExosphereHost: Phòng thí nghiệm nghiên cứu độ tin cậy cho Agent của bạn**. Chúng tôi giúp các doanh nghiệp và startups cải thiện độ tin cậy của các AI agent của họ thông qua các agent, phần mềm và chuyên môn của riêng chúng tôi. Tìm hiểu thêm tại [exosphere.host](https://exosphere.host). diff --git a/docs/it/architecture.mdx b/docs/it/architecture.mdx index 29ecf2d6..6add3f94 100644 --- a/docs/it/architecture.mdx +++ b/docs/it/architecture.mdx @@ -1,12 +1,11 @@ --- - --- title: Architettura -description: "Come funzionano internamente il gestore hook, il caricamento della config e la valutazione delle policy" +description: "Come il gestore dei hook, il caricamento della configurazione e la valutazione delle policy funzionano internamente" icon: sitemap --- -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. +Questo documento spiega come failproofai funziona internamente: come il sistema di hook intercetta le chiamate degli strumenti dell'agente, come viene caricata e unita la configurazione, come vengono valutate le policy e come il dashboard monitora l'attività dell'agente. --- @@ -14,14 +13,14 @@ Questo documento spiega come failproofai funziona internamente: come il sistema failproofai ha due sottosistemi indipendenti: -1. **Hook handler** - Un veloce subprocess CLI che Claude Code invoca a ogni chiamata di strumento dell'agente. Valuta le policy e restituisce una decisione. +1. **Gestore dei hook** - Un rapido sottoprocesso CLI che Claude Code richiama ad ogni chiamata dello 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 i 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 tramite il filesystem. --- -## Hook handler +## Gestore dei hook ### Integrazione con Claude Code @@ -46,7 +45,7 @@ Quando esegui `failproofai policies --install`, scrive voci come questa in `~/.c } ``` -Claude Code invoca quindi `failproofai --hook PreToolUse` come subprocess prima di ogni chiamata di strumento, passando un payload JSON su stdin. +Claude Code quindi richiama `failproofai --hook PreToolUse` come sottoprocesso prima di ogni chiamata dello strumento, passando un payload JSON su stdin. ### Formato del payload @@ -64,11 +63,11 @@ Claude Code invoca quindi `failproofai --hook PreToolUse` come subprocess prima Per gli eventi `PostToolUse`, il payload contiene anche `tool_result` con l'output dello strumento. -L'handler applica un limite di stdin di 1 MB. I payload che superano questo limite vengono scartati e tutte le policy permettono implicitamente. +Il gestore applica un limite stdin di 1 MB. I payload che superano questo limite vengono scartati e tutte le policy consentono implicitamente. ### Formato della risposta -**Deny (PreToolUse):** +**Nega (PreToolUse):** ```json { "hookSpecificOutput": { @@ -78,7 +77,7 @@ L'handler applica un limite di stdin di 1 MB. I payload che superano questo limi } ``` -**Deny (PostToolUse):** +**Nega (PostToolUse):** ```json { "hookSpecificOutput": { @@ -96,17 +95,17 @@ L'handler applica un limite di stdin di 1 MB. I payload che superano questo limi } ``` -**Instruct per evento Stop:** +**Instruct evento Stop:** - Exit code: `2` - Motivo scritto su stderr (non stdout) -**Allow:** +**Consenti:** - Exit code: `0` - stdout vuoto -**Allow con messaggio:** +**Consenti con messaggio:** -`allow(message)` consente a una policy di inviare contesto informativo a Claude anche quando l'operazione è consentita. L'hook handler scrive il seguente JSON su **stdout** (non su un file di config — questa è la risposta dell'handler a Claude Code, proprio come le risposte deny e instruct sopra): +`allow(message)` consente a una policy di inviare il contesto informativo indietro a Claude anche quando l'operazione è consentita. Il gestore dei 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 sopra): ```json // Written to stdout by the hook handler process @@ -116,8 +115,8 @@ L'handler applica un limite di stdin di 1 MB. I payload che superano questo limi } } ``` -- Exit code: `0` (operazione consentita) -- Quando più policy restituiscono `allow` con un messaggio, i loro messaggi vengono uniti con newline in un'unica stringa `additionalContext` +- Exit code: `0` (l'operazione è consentita) +- Quando più policy restituiscono `allow` con un messaggio, i loro messaggi vengono uniti con nuove righe in una singola stringa `additionalContext` - Se nessuna policy fornisce un messaggio, stdout è vuoto (come prima) ### Pipeline di elaborazione @@ -141,13 +140,13 @@ stdin JSON → exit ``` -L'intero processo viene eseguito in meno di 100ms per payload tipici senza chiamate LLM. +L'intero processo viene eseguito in meno di 100ms per i payload tipici senza chiamate LLM. --- ## Caricamento della configurazione -`src/hooks/hooks-config.ts` implementa il caricamento della config a tre ambiti. +`src/hooks/hooks-config.ts` implementa il caricamento della configurazione con tre ambiti. ```text [1] {cwd}/.failproofai/policies-config.json ← project (highest priority) @@ -156,39 +155,39 @@ L'intero processo viene eseguito in meno di 100ms per payload tipici senza chiam ``` Logica di unione: -- `enabledPolicies` - unione deduplicated in 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 +- `enabledPolicies` - unione deduplica tra tutti e tre i file +- `policyParams` - per 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 del progetto. +Il dashboard web utilizza `readHooksConfig()` (solo globale) per la lettura e la scrittura, poiché non viene richiamato con un cwd di progetto. --- -## Valutazione delle policy +## Valutazione della policy `src/hooks/policy-evaluator.ts` esegue le policy in ordine. Per ogni policy: -1. Cerca lo schema `params` della policy (se ne ha uno). -2. Leggi `policyParams[policy.name]` dalla config unita. -3. Unisci i valori forniti dall'utente sui default dello schema per produrre `ctx.params`. +1. Ricerca 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`, fermati immediatamente e restituisci quella decisione. +5. Se il risultato è `deny`, interrompi immediatamente e restituisci quella decisione. 6. Se il risultato è `instruct`, accumula il messaggio e continua. -7. Se il risultato è `allow`, continua con la policy successiva. +7. Se il risultato è `allow`, continua alla policy successiva. -Dopo che tutte le policy vengono eseguite: -- Se è stato restituito un qualsiasi `deny`, emetti la risposta deny. -- Se sono stati raccolti dei ritorni `instruct`, emetti un'unica risposta instruct con tutti i messaggi uniti. +Dopo che tutte le policy sono state eseguite: +- Se è stato restituito un `deny`, emetti la risposta deny. +- Se sono stati raccolti resi di `instruct`, emetti una singola risposta instruct con tutti i messaggi uniti. - Altrimenti, emetti una risposta allow (stdout vuoto, exit 0). --- -## Policy built-in +## Policy integrate -`src/hooks/builtin-policies.ts` definisce tutte le 26 policy built-in come oggetti `BuiltinPolicyDefinition`: +`src/hooks/builtin-policies.ts` definisce tutte le 26 policy integrate come oggetti `BuiltinPolicyDefinition`: ```typescript interface BuiltinPolicyDefinition { @@ -206,9 +205,9 @@ interface BuiltinPolicyDefinition { } ``` -Le policy che accettano `params` dichiarano uno `PolicyParamsSchema` con tipi e default per ogni parametro. L'evaluator delle policy inietta i valori risolti in `ctx.params` prima di chiamare `fn`. Le funzioni delle policy leggono `ctx.params` senza null-guarding perché i default vengono sempre applicati per primi. +Le policy che accettano `params` dichiarano un `PolicyParamsSchema` con i tipi e i valori predefiniti per ogni parametro. Il valutatore di policy inietta i valori risolti in `ctx.params` prima di chiamare `fn`. Le funzioni della policy leggono `ctx.params` senza null-guard perché i valori predefiniti vengono sempre applicati per primi. -Il pattern matching all'interno delle policy utilizza token di comando analizzati (argv), non corrispondenza di stringhe grezze. Questo previene il bypass via iniezione di operatori shell (ad es. un pattern per `sudo systemctl status *` non può essere bypassato aggiungendo `; rm -rf /` al comando). +L'abbinamento di pattern all'interno delle policy utilizza token di comando parsati (argv), non abbinamento di stringhe non elaborate. 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,25 +226,25 @@ export function getCustomHooks(): CustomHook[] { ... } export function clearCustomHooks(): void { ... } // used in tests ``` -`src/hooks/custom-hooks-loader.ts` carica il file di policy dell'utente: +`src/hooks/custom-hooks-loader.ts` carica il file della policy dell'utente: -1. Leggi `customPoliciesPath` dalla config; salta se assente. +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 garantire la compatibilità ESM. 5. Scrivi file `.mjs` temporanei e `import()` il file di entry. 6. Chiama `getCustomHooks()` per recuperare gli hook registrati. -7. Pulisci tutti i file temp in un blocco `finally`. +7. Pulisci tutti i file temporanei in un blocco `finally`. -In caso di errore (file non trovato, errore di sintassi, errore di import), l'errore viene registrato in `~/.failproofai/hook.log` e il loader restituisce un array vuoto. Le policy built-in non ne sono interessate. +In caso di errore (file non trovato, errore di sintassi, errore di import), l'errore viene registrato in `~/.failproofai/hook.log` e il loader restituisce un array vuoto. Le policy integrate non sono interessate. -Le policy personalizzate vengono valutate dopo tutte le policy built-in. Un `deny` di policy personalizzata continua a fare short-circuit delle ulteriori policy personalizzate (ma tutte le built-in sono già state eseguite a questo punto). +Le policy personalizzate vengono valutate dopo tutte le policy integrate. Un `deny` di una policy personalizzata comunque cortocircuita ulteriori policy personalizzate (ma a quel punto tutte le policy integrate sono già state eseguite). --- ## Registrazione dell'attività -Dopo ogni evento hook, l'handler aggiunge una riga JSONL a `~/.failproofai/hook-activity.jsonl`: +Dopo ogni evento hook, il gestore aggiunge una riga JSONL a `~/.failproofai/hook-activity.jsonl`: ```json { @@ -260,7 +259,7 @@ Dopo ogni evento hook, l'handler aggiunge una riga JSONL a `~/.failproofai/hook- } ``` -Una riga per 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). --- @@ -283,21 +282,21 @@ app/ get-hook-activity.ts ← Paginate/search activity log install-hooks-web.ts ← Install/remove hooks from the browser api/ - download/[project]/[session]/route.ts ← Export session as ZIP/JSONL + download/[project]/[session]/route.ts ← Per-CLI session export (JSONL or JSON) ``` -**Flusso di dati:** +**Flusso dei dati:** -- I componenti 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 params, install/remove). -- Il visualizzatore di sessione analizza il formato di trascritto JSONL di Claude e renderizza una timeline di messaggi e chiamate di strumento. +- 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 (attivazione/disattivazione, aggiornamento dei parametri, installazione/rimozione). +- Il visualizzatore di sessioni analizza il formato della trascrizione JSONL di Claude e visualizza una timeline di messaggi e chiamate di strumenti. -**Decisioni di progettazione chiave:** +**Decisioni di design chiave:** -- Nessun database - tutto lo stato persistente è in file semplici (`~/.failproofai/`, `~/.claude/projects/`). -- Server Actions per 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 fetch dei dati. -- Componenti client solo dove è necessaria l'interattività (toggle policy, ricerca attività, visualizzatore log). +- 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 dati. +- Componenti client solo dove è necessaria l'interattività (attivazioni di policy, ricerca di attività, visualizzatore di log). --- diff --git a/docs/it/built-in-policies.mdx b/docs/it/built-in-policies.mdx index 05950a42..69b9d9c0 100644 --- a/docs/it/built-in-policies.mdx +++ b/docs/it/built-in-policies.mdx @@ -1,43 +1,39 @@ --- -title: Politiche integrate -description: "Tutte le 39 politiche integrate che rilevano i comuni modi di fallimento degli agenti" +title: Criteri integrati +description: "Tutti i 39 criteri integrati che intercettano le modalità di errore comuni degli agenti" icon: shield --- -failproofai fornisce 39 politiche integrate che rilevano i comuni modi di fallimento degli agenti. Ogni politica si attiva su un tipo di evento hook specifico e un nome di tool specifico. Diciannove politiche accettano parametri che ti permettono di sintonizzare il loro comportamento senza scrivere codice. Cinque politiche di workflow applicano una pipeline commit → push → PR → CI prima che Claude si fermi. +failproofai viene fornito con 39 criteri integrati che intercettano le modalità di errore comuni degli agenti. Ogni criterio si attiva su un tipo di evento hook specifico e sul nome dello strumento. Diciannove criteri accettano parametri che ti permettono di regolarne il comportamento senza scrivere codice. Cinque criteri di flusso di lavoro applicano una pipeline commit → push → PR → CI prima che Claude si fermi. --- ## Panoramica -Le politiche sono raggruppate in categorie: +I criteri sono raggruppati per categorie: -| Categoria | Politiche | Tipo di hook | -|----------|----------|-----------| +| Categoria | Criteri | 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 | -| [Segreti (sanitizer)](#segreti-sanitizer) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [Secrets (sanitizzatori)](#secrets-sanitizzatori) | 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 | | [Database](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse | | [Avvisi](#avvisi) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | -| [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 | +| [Gestori pacchetti](#gestori-pacchetti) | prefer-package-manager | PreToolUse | +| [Flusso di lavoro](#flusso-di-lavoro) | 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'agente dal procedere. -- **`warn-`** — fornisci all'agente un contesto aggiuntivo in modo da potersi autocorregere. -- **`sanitize-`** — rimuovi i dati sensibili dall'output del tool prima che l'agente li veda. +- **`block-`** — impedisce all'agente di procedere. +- **`warn-`** — fornisce all'agente contesto aggiuntivo in modo che possa autocorreggersi. +- **`sanitize-`** — rimuove dati sensibili dall'output dello strumento prima che l'agente li veda. -### Namespace +### Spazi dei nomi -Ogni politica risiede in uno slot `/`. Le politiche integrate appartengono al namespace -**`exospherehost/`** — ad esempio, `exospherehost/sanitize-jwt`. Il -namespace previene collisioni quando carichi anche politiche personalizzate o di terze parti -con nomi brevi simili. +Ogni criterio si trova in uno slot `/`. I criteri integrati appartengono allo spazio dei nomi **`exospherehost/`** — ad esempio, `exospherehost/sanitize-jwt`. Lo spazio dei nomi evita collisioni quando carichi anche criteri personalizzati o di terze parti con nomi brevi simili. -Nella tua configurazione puoi fare riferimento a una politica integrata usando 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 un criterio integrato utilizzando sia il nome breve che il nome qualificato; entrambe le forme si risolvono nello stesso criterio: ```json { @@ -48,15 +44,13 @@ nome qualificato; entrambi i moduli si risolvono nella stessa politica: } ``` -Se un nome non contiene `/`, failproofai lo tratta come appartenente al namespace predefinito -`exospherehost`. I nomi che già contengono `/` (ad es. `myorg/foo`, -`custom/my-hook`) vengono mantenuti così come sono. +Se un nome non contiene `/`, failproofai lo tratta come appartenente allo spazio dei nomi predefinito `exospherehost`. I nomi che contengono già un `/` (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 di deny o instruct che Claude vede, fornendo indicazioni praticabili senza modificare il codice della politica. Funziona con politiche integrate, personalizzate e di convenzione. Vedi [Configuration → hint](/it/configuration#hint-cross-cutting) per i dettagli. +Ogni criterio supporta un campo `hint` opzionale in `policyParams`. L'hint viene aggiunto al messaggio di negazione o istruzione che Claude vede, fornendo indicazioni praticabili senza modificare il codice del criterio. Funziona con i criteri integrati, personalizzati e di convenzione. Consulta [Configurazione → hint](/it/configuration#hint-cross-cutting) per i dettagli. --- @@ -70,13 +64,13 @@ Impedisci agli agenti di eseguire operazioni difficili da annullare o che potreb **Evento:** PreToolUse (Bash) **Predefinito:** Nega qualsiasi comando `sudo`. -Blocca le invocazioni che includono la parola chiave `sudo`. La corrispondenza dei pattern viene eseguita sui token di comando analizzati, non sulla stringa grezza, per prevenire il bypass tramite l'iniezione dell'operatore shell. +Blocca le 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:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefissi di comando esatti che sono consentiti. Ogni voce viene confrontata con i token argv analizzati. | +| `allowPatterns` | `string[]` | `[]` | Prefissi di comando esatti consentiti. Ogni voce viene confrontata con i token argv analizzati. | **Esempio:** @@ -93,7 +87,7 @@ Blocca le invocazioni che includono la parola chiave `sudo`. La corrispondenza d Con questa configurazione, `sudo systemctl status nginx` è consentito, ma `sudo rm /etc/hosts` è negato. -I pattern vengono confrontati con i token analizzati, non con la stringa di comando grezza. Questo previene il bypass tramite operatori shell aggiunti (ad es. `sudo systemctl status x; rm -rf /` non corrisponde a `sudo systemctl status *`). +I pattern vengono confrontati con i token analizzati, non con la stringa di comando grezza. Questo previene bypass tramite operatori shell accodati (ad es. `sudo systemctl status x; rm -rf /` non corrisponde a `sudo systemctl status *`). --- @@ -105,9 +99,9 @@ I pattern vengono confrontati con i token analizzati, non con la stringa di coma **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Percorsi che sono sicuri per eliminare ricorsivamente (ad es. `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Percorsi che è sicuro eliminare ricorsivamente (ad es. `/tmp`). | **Esempio:** @@ -135,7 +129,7 @@ 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`). +**Predefinito:** Nega comandi che disinstallerebbero o disabiliterebbero failproofai stesso (ad es. `npm uninstall failproofai`, `failproofai policies --uninstall`). Nessun parametro. @@ -143,20 +137,20 @@ Nessun parametro. ## Comandi infra -Ferma gli agenti di codifica dall'eseguire CLI di infrastruttura o dall'attivare pipeline CI/CD. Tutte le politiche in questa categoria sono **opt-in** (`defaultEnabled: false`) — gli agenti che legittimamente hanno bisogno di chiamare `kubectl`, `terraform`, ecc. non verranno disturbati a meno che tu non abiliti la politica. Quando abilitate, ogni invocazione della CLI corrispondente è negata a meno che il comando non corrisponda a una voce in `allowPatterns`. +Impedisci agli agenti di codifica di eseguire CLI infrastrutturali o attivare pipeline CI/CD. Tutti i criteri in questa categoria sono **opt-in** (`defaultEnabled: false`) — gli agenti che hanno legittimamente bisogno di chiamare `kubectl`, `terraform`, ecc. non saranno interrotti a meno che non abiliti il criterio. Quando è abilitato, ogni invocazione della CLI abbinata viene negata a meno che il comando non corrisponda a una voce in `allowPatterns`. -La grammatica del pattern è la stessa di [`block-sudo`](#block-sudo): i token vengono confrontati con argv analizzato, `*` è un wildcard per un token, e qualsiasi comando che contiene un operatore shell standalone (`&&`, `||`, `|`, `;`) o un token con metacaratteri shell incorporati viene rifiutato prima della corrispondenza della lista di autorizzazione per prevenire bypass di iniezione. +La grammatica del pattern è la stessa di [`block-sudo`](#block-sudo): i token vengono confrontati rispetto all'argv analizzato, `*` è un carattere jolly per un token, e qualsiasi comando contenente un operatore shell autonomo (`&&`, `||`, `|`, `;`) 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 di `kubectl`. +**Predefinito:** Nega qualsiasi invocazione `kubectl`. **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefissi di comando kubectl che sono consentiti. | +| `allowPatterns` | `string[]` | `[]` | Prefissi di comando kubectl consentiti. | **Esempio:** @@ -177,13 +171,13 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-terraform` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione di `terraform` o `tofu` (OpenTofu). +**Predefinito:** Nega qualsiasi invocazione `terraform` o `tofu` (OpenTofu). **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefissi di comando terraform/tofu che sono consentiti. | +| `allowPatterns` | `string[]` | `[]` | Prefissi di comando terraform/tofu consentiti. | **Esempio:** @@ -202,13 +196,13 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-aws-cli` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione di CLI `aws`. +**Predefinito:** Nega qualsiasi invocazione `aws` CLI. **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefissi di comando AWS CLI che sono consentiti. | +| `allowPatterns` | `string[]` | `[]` | Prefissi di comando aws CLI consentiti. | **Esempio:** @@ -227,13 +221,13 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-gcloud` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione di CLI `gcloud` (Google Cloud). +**Predefinito:** Nega qualsiasi invocazione `gcloud` (Google Cloud) CLI. **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefissi di comando gcloud che sono consentiti. | +| `allowPatterns` | `string[]` | `[]` | Prefissi di comando gcloud consentiti. | **Esempio:** @@ -252,13 +246,13 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-az-cli` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione di CLI `az` (Azure). +**Predefinito:** Nega qualsiasi invocazione `az` (Azure) CLI. **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefissi di comando az CLI che sono consentiti. | +| `allowPatterns` | `string[]` | `[]` | Prefissi di comando az CLI consentiti. | **Esempio:** @@ -277,13 +271,13 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-helm` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega qualsiasi invocazione di `helm`. +**Predefinito:** Nega qualsiasi invocazione `helm`. **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefissi di comando helm che sono consentiti. | +| `allowPatterns` | `string[]` | `[]` | Prefissi di comando helm consentiti. | **Esempio:** @@ -302,7 +296,7 @@ Con questa configurazione, `kubectl get pods` è consentito ma `kubectl apply -f ### `block-gh-pipeline` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega i seguenti sottocomandi di CLI `gh` che mutano lo stato o attivano pipeline: +**Predefinito:** Nega i seguenti sottocomandi `gh` CLI che mutano lo stato o attivano pipeline: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -311,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** sono corrisposti da questa politica — sono comunemente necessari per i controlli di workflow (incluso il proprio `require-ci-green-before-stop` di failproofai). +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 abbinati da questo criterio — sono regolarmente necessari per i controlli del flusso di lavoro (incluso il `require-ci-green-before-stop` di failproofai). **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Invocazioni script specifiche da consentire anche se sarebbero altrimenti negate. | +| `allowPatterns` | `string[]` | `[]` | Invocazioni specifiche scritte per consentire anche se verrebbero negate. | **Esempio:** @@ -333,14 +327,14 @@ I sottocomandi `gh` di sola lettura come `gh pr view`, `gh pr list`, `gh run lis --- -## Segreti (sanitizer) +## Secrets (sanitizzatori) -Ferma gli agenti dal trapelare le 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 tool, queste politiche ispezionano l'output prima che venga restituito a Claude. Se viene rilevato un pattern segreto, la politica restituisce una decisione di deny che impedisce all'output di essere passato indietro. +Impedisci agli agenti di esporre credenziali nel loro contesto o output. I criteri sanitizzatori si attivano su eventi **PostToolUse**. Quando Claude esegue un comando Bash, legge un file o chiama qualsiasi strumento, questi criteri ispezionano l'output prima che venga restituito a Claude. Se viene rilevato un pattern di secret, il criterio restituisce una decisione di negazione che impedisce il passaggio dell'output. ### `sanitize-jwt` -**Evento:** PostToolUse (tutti i tool) -**Predefinito:** Oscura i token JWT (tre segmenti base64url separati da `.`). +**Evento:** PostToolUse (tutti gli strumenti) +**Predefinito:** Redige i token JWT (tre segmenti base64url separati da `.`). Nessun parametro. @@ -348,14 +342,14 @@ Nessun parametro. ### `sanitize-api-keys` -**Evento:** PostToolUse (tutti i tool) -**Predefinito:** Oscura i formati di chiave API comuni: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), chiavi di accesso AWS (`AKIA`), chiavi Stripe (`sk_live_`, `sk_test_`), e chiavi API Google (`AIza`). +**Evento:** PostToolUse (tutti gli strumenti) +**Predefinito:** Redige i formati comuni di API key: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), chiavi di accesso AWS (`AKIA`), chiavi Stripe (`sk_live_`, `sk_test_`), e chiavi Google API (`AIza`). **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Pattern regex aggiuntivi da trattare come segreti. | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Pattern regex aggiuntivi da trattare come secret. | **Esempio:** @@ -376,8 +370,8 @@ Nessun parametro. ### `sanitize-connection-strings` -**Evento:** PostToolUse (tutti i tool) -**Predefinito:** Oscura le stringhe di connessione del database che contengono credenziali incorporate (ad es. `postgresql://user:password@host/db`). +**Evento:** PostToolUse (tutti gli strumenti) +**Predefinito:** Redige le stringhe di connessione al database che contengono credenziali incorporate (ad es. `postgresql://user:password@host/db`). Nessun parametro. @@ -385,8 +379,8 @@ Nessun parametro. ### `sanitize-private-key-content` -**Evento:** PostToolUse (tutti i tool) -**Predefinito:** Oscura i blocchi PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, ecc.). +**Evento:** PostToolUse (tutti gli strumenti) +**Predefinito:** Redige i blocchi PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, ecc.). Nessun parametro. @@ -394,8 +388,8 @@ Nessun parametro. ### `sanitize-bearer-tokens` -**Evento:** PostToolUse (tutti i tool) -**Predefinito:** Oscura gli header `Authorization: Bearer ` dove il token è composto da 20 o più caratteri. +**Evento:** PostToolUse (tutti gli strumenti) +**Predefinito:** Redige gli header `Authorization: Bearer ` dove il token è di 20 o più caratteri. Nessun parametro. @@ -403,14 +397,14 @@ Nessun parametro. ## Ambiente -Proteggi la configurazione dell'ambiente sensibile dal essere letta o esposta dagli agenti. +Proteggi la configurazione dell'ambiente sensibile dalla lettura o dall'esposizione da parte degli agenti. ### `block-env-files` **Evento:** PreToolUse (Bash, Read) -**Predefinito:** Nega la lettura di file `.env` tramite `cat .env`, chiamate di tool Read con `.env` come percorso file, ecc. +**Predefinito:** 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 correlati all'ambiente — solo file denominati esattamente `.env`. +Non blocca `.envrc` o altri file adiacenti all'ambiente — solo file denominati esattamente `.env`. Nessun parametro. @@ -419,7 +413,7 @@ Nessun parametro. ### `protect-env-vars` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega i comandi che stampano le variabili d'ambiente: `printenv`, `env`, `echo $VAR`. +**Predefinito:** Nega comandi che stampano variabili d'ambiente: `printenv`, `env`, `echo $VAR`. Nessun parametro. @@ -427,18 +421,18 @@ Nessun parametro. ## Accesso ai file -Mantieni gli agenti all'interno dei confini del progetto e lontano dai file sensibili. +Mantieni gli agenti che lavorano all'interno dei 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. Usare la radice del progetto piuttosto che il `cwd` live significa che il confine rimane stabile anche dopo che Claude fa `cd` in una sottodirectory. +**Predefinito:** Nega la lettura di file al di fuori della root del progetto. Il limite è `CLAUDE_PROJECT_DIR` (impostato una volta per sessione da Claude Code), con un fallback alla directory di lavoro corrente della sessione quando tale variabile non è impostata. L'utilizzo della root del progetto piuttosto della `cwd` live significa che il limite rimane stabile anche dopo che Claude fa `cd` in una sottodirectory. **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Prefissi di percorso assoluti che sono consentiti anche se al di fuori della radice del progetto. | +| `allowPaths` | `string[]` | `[]` | Prefissi di percorso assoluto consentiti anche se al di fuori della root del progetto. | **Esempio:** @@ -457,11 +451,11 @@ Mantieni gli agenti all'interno dei confini del progetto e lontano dai file sens ### `block-secrets-write` **Evento:** PreToolUse (Write, Edit) -**Predefinito:** Nega le scritture su file comunemente usati per chiavi private e certificati: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Predefinito:** Nega le scritture su file comunemente utilizzati per chiavi private e certificati: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| | `additionalPatterns` | `string[]` | `[]` | Pattern di nome file aggiuntivi (stile glob) da bloccare. | @@ -490,9 +484,9 @@ Previeni push accidentali, force-push e errori di branch difficili da annullare. **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Nomi di branch che non possono essere spinti direttamente. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Nomi dei branch che non possono essere sottoposti a push direttamente. | **Esempio:** @@ -507,7 +501,7 @@ Previeni push accidentali, force-push e errori di branch difficili da annullare. ``` -Per consentire di spingere a tutti i branch (disabilitando efficacemente questa politica senza rimuoverla da `enabledPolicies`), imposta `protectedBranches: []`. +Per consentire il push su tutti i branch (disabilitando effettivamente questo criterio senza rimuoverlo da `enabledPolicies`), imposta `protectedBranches: []`. --- @@ -515,13 +509,13 @@ Per consentire di spingere a tutti i branch (disabilitando efficacemente questa ### `block-work-on-main` **Evento:** PreToolUse (Bash) -**Predefinito:** Nega il checkout diretto dei branch `main` o `master`. +**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. **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Nomi di branch che non possono essere estratti direttamente. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Nomi dei branch su cui commit/merge/rebase/cherry-pick è negato. | --- @@ -530,13 +524,13 @@ Per consentire di spingere a tutti i branch (disabilitando efficacemente questa **Evento:** PreToolUse (Bash) **Predefinito:** Nega `git push --force` e `git push -f`. -Nessun parametro specifico della politica. Usa l'[`hint`](/it/configuration#hint-cross-cutting) cross-cutting per suggerire alternative: +Nessun parametro specifico del criterio. Usa l'[`hint`](/it/configuration#hint-cross-cutting) cross-cutting per suggerire alternative: ```json { "policyParams": { "block-force-push": { - "hint": "Crea un nuovo branch dal tuo HEAD attuale (ad es. `git checkout -b `) e spingi quello invece." + "hint": "Crea un nuovo branch dal tuo HEAD corrente (ad es. `git checkout -b `) e fai il push di quello invece." } } } @@ -565,7 +559,7 @@ Nessun parametro. ### `warn-all-files-staged` **Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a rivedere ciò che sta stadiando quando esegue `git add -A` o `git add .`. Non blocca il comando. +**Predefinito:** Istruisce Claude a rivedere quello che sta staging quando esegue `git add -A` o `git add .`. Non blocca il comando. Nessun parametro. @@ -573,7 +567,7 @@ Nessun parametro. ## Database -Rileva le operazioni SQL distruttive prima che vengano eseguite sul tuo database. +Intercetta le operazioni SQL distruttive prima che vengano eseguite sul tuo database. ### `warn-destructive-sql` @@ -595,7 +589,7 @@ Nessun parametro. ## Avvisi -Fornisci agli agenti un contesto extra prima di operazioni potenzialmente rischiose ma non distruttive. +Fornisci agli agenti contesto aggiuntivo prima di operazioni potenzialmente rischiose ma non distruttive. ### `warn-large-file-write` @@ -604,7 +598,7 @@ Fornisci agli agenti un contesto extra prima di operazioni potenzialmente rischi **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| | `thresholdKb` | `number` | `1024` | Soglia di dimensione del file in kilobyte al di sopra della quale viene emesso un avviso. | @@ -621,7 +615,7 @@ Fornisci agli agenti un contesto extra prima di operazioni potenzialmente rischi ``` -Il gestore dell'hook applica un limite di 1 MB stdin sui payload. Per testare questa politica con contenuto piccolo, imposta `thresholdKb` a un valore ben al di sotto di 1024. +Il gestore hook applica un limite stdin di 1 MB sui payload. Per testare questo criterio con contenuto piccolo, imposta `thresholdKb` su un valore ben al di sotto di 1024. --- @@ -638,7 +632,7 @@ Nessun parametro. ### `warn-background-process` **Evento:** PreToolUse (Bash) -**Predefinito:** Istruisce Claude a fare attenzione quando avvia processi in background tramite `nohup`, `&`, `disown`, o `screen`. +**Predefinito:** Istruisce Claude a fare attenzione quando lancia processi in background tramite `nohup`, `&`, `disown`, o `screen`. Nessun parametro. @@ -653,9 +647,9 @@ Nessun parametro. --- -## Gestori di pacchetti +## Gestori pacchetti -Applica quale gestore di pacchetti l'agente è autorizzato a usare. +Applica quale gestore di pacchetti l'agente può utilizzare. ### `prefer-package-manager` @@ -666,7 +660,7 @@ Rileva: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poe | Parametro | Tipo | Predefinito | Descrizione | |-----------|------|---------|-------------| -| `allowed` | string[] | `[]` | Nomi dei gestori di pacchetti consentiti. Qualsiasi gestore rilevato non in questa lista viene bloccato. Quando vuoto, la politica è un no-op. | +| `allowed` | string[] | `[]` | Nomi dei gestori di pacchetti consentiti. Qualsiasi gestore rilevato non in questa lista è bloccato. Quando vuoto, il criterio è un no-op. | | `blocked` | string[] | `[]` | Nomi di gestori aggiuntivi da bloccare oltre la lista integrata (ad es. `['pdm', 'pipx']`). | La lista di blocco integrata copre: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. Usa `blocked` per aggiungere gestori non in questa lista. @@ -685,33 +679,33 @@ La lista di blocco integrata 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` è nella lista di autorizzazione ed è controllato 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. Comandi come `uv pip install flask` sono consentiti perché `uv` è nella lista di consentiti e viene controllato per primo. --- ## Comportamento AI -Rileva quando gli agenti rimangono bloccati o si comportano inaspettatamente. +Rileva quando gli agenti rimangono bloccati o si comportano in modo inaspettato. ### `warn-repeated-tool-calls` -**Evento:** PreToolUse (tutti i tool) -**Predefinito:** Istruisce Claude a riconsiderare quando lo stesso tool viene chiamato 3 o più volte con parametri identici — un segno comune che l'agente è bloccato in un loop. +**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'agente è bloccato in un loop. Nessun parametro. --- -## Workflow +## Flusso di lavoro -Applica un workflow disciplinato di fine sessione. Queste politiche si attivano sull'evento **Stop** e negano a Claude 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 (il deny cortocircuita). +Applica un flusso di lavoro disciplinato di fine sessione. Questi criteri si attivano sull'evento **Stop** e negano a Claude di fermarsi fino a quando ogni condizione non è soddisfatta. Seguono una catena di dipendenze naturale: commit → push → PR → CI. Se un criterio nega, i criteri successivi nella catena vengono saltati (la negazione interrompe il percorso). -Tutte le politiche di workflow sono **fail-open**: se il tool richiesto non è disponibile (ad es. `gh` non installato, nessun git remote), la politica consente con un messaggio informativo spiegando perché il controllo è stato saltato. +Tutti i criteri di flusso di lavoro sono **fail-open**: se lo strumento richiesto non è disponibile (ad es. `gh` non installato, nessun git remote), il criterio consente con un messaggio informativo che spiega perché il controllo è stato saltato. ### `require-commit-before-stop` **Evento:** Stop -**Predefinito:** Nega lo stop quando ci sono modifiche non committate (file modificati, staged o non tracciati). Restituisce un messaggio informativo quando la working directory è pulita. +**Predefinito:** Nega l'arresto quando ci sono cambiamenti non committati (file modificati, staged o non tracciati). Restituisce un messaggio informativo quando la directory di lavoro è pulita. Nessun parametro. @@ -720,13 +714,13 @@ Nessun parametro. ### `require-push-before-stop` **Evento:** Stop -**Predefinito:** Nega lo stop quando ci sono commit non spinti o quando il branch corrente non ha un branch di tracciamento remoto. Suggerisce `git push -u` per creare un branch di tracciamento se necessario. Fallisce open se nessun remote è configurato. +**Predefinito:** Nega l'arresto quando ci sono commit non sottoposti a push o quando il branch corrente non ha nessun branch di tracciamento remoto. Suggerisce `git push -u` per creare un branch di tracciamento se necessario. Fallisce in modo aperto se nessun remote è configurato. **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | Nome del remote su cui spingere. | +| `remote` | `string` | `"origin"` | Nome del remote su cui fare il push. | **Esempio:** @@ -745,14 +739,14 @@ Nessun parametro. ### `require-pr-before-stop` **Evento:** Stop -**Predefinito:** Nega lo stop quando nessuna pull request esiste per il branch corrente, o quando la PR esistente è chiusa senza essere unita. Istruisce Claude a creare una PR con `gh pr create`. Quando la PR è **unita**, la politica consente (il lavoro è stato spedito) e il messaggio suggerisce di passare dal branch (`git checkout main && git pull`). +**Predefinito:** Nega l'arresto quando non esiste una pull request per il branch corrente, o quando la PR esistente è chiusa senza essere unita. Istruisce Claude a creare una PR con `gh pr create`. Quando la PR è **unita**, il criterio consente (il lavoro è stato spedito) e il messaggio suggerisce di passare da un altro branch (`git checkout main && git pull`). 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 -pull request. Se `gh` non è installato o non autenticato, la politica fallisce open e riporta il motivo a Claude. +Questo criterio richiede che [GitHub CLI](https://cli.github.com/) (`gh`) sia installato e autenticato. +Esegui `gh auth login` con un personal access token che ha lo scope `repo` per l'accesso in lettura alle +pull request. Se `gh` non è installato o non autenticato, il criterio fallisce in modo aperto e segnala il motivo a Claude. --- @@ -760,24 +754,24 @@ pull request. Se `gh` non è installato o non autenticato, la politica fallisce ### `require-no-conflicts-before-stop` **Evento:** Stop -**Predefinito:** Nega lo stop quando il branch corrente non può unirsi pulitamente 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 cortocircuita per consentire. Una volta confermato una PR `OPEN`, due sonde indipendenti vengono eseguite: +**Predefinito:** Nega l'arresto quando il branch corrente non può essere unito in modo pulito nel branch base. Il criterio prima conferma che esiste una PR `OPEN` su GitHub per il branch — senza una, non c'è un target di merge da applicare, quindi l'intero criterio interrompe il percorso per consentire. Una volta confermata una PR `OPEN`, due sonde indipendenti vengono eseguite: -1. **Locale** — `git merge-tree --write-tree --name-only origin/ HEAD`. In caso di conflitto, il messaggio di 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 nella precheck. Rileva i conflitti che un `origin/` locale stantio potrebbe mancare (ad es. qualcuno ha fatto un commit di una PR in conflitto su `main` da quando è stato fatto l'ultimo fetch). Un risultato `CONFLICTING` nega. Un risultato `UNKNOWN` nega anche e istruisce Claude di aspettare ~10 secondi e ri-controllare prima di provare a fermarsi di nuovo — questo previene falsi negativi mentre GitHub ricalcola. +1. **Locale** — `git merge-tree --write-tree --name-only origin/ HEAD`. In caso di conflitto, il messaggio di negazione 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 precheck. Intercetta i conflitti che uno `origin/` locale stantio avrebbe perso (ad es. qualcuno ha fatto il landing di una PR in conflitto su `main` dall'ultimo fetch). Un risultato `CONFLICTING` nega. Un risultato `UNKNOWN` nega anche e istruisce Claude di aspettare ~10 secondi e ri-controllare prima di tentare di fermasi di nuovo — questo previene falsi negativi mentre GitHub ricalcola. -Salta interamente (consente) quando: `gh` non è installato, nessuna PR esiste per il branch, lo stato della PR non è `OPEN` (ad es. `MERGED`, `CLOSED`), o `gh pr view` restituisce output non parsificabile. Fallisce anche open quando `origin/` manca localmente o quando nessun commit è avanti di base — questi fallthrough di Layer 1 consultano ancora il mergeability memorizzato della PR prima di consentire. +Salta completamente (consente) quando: `gh` non è installato, nessuna PR esiste per il branch, lo stato della PR non è `OPEN` (ad es. `MERGED`, `CLOSED`), o `gh pr view` restituisce output non parseabile. Fallisce anche in modo aperto quando `origin/` manca localmente o quando nessun commit è ahead di base — quei fallthrough di Layer 1 consultano comunque la mergeability della PR in cache prima di consentire. **Parametri:** -| Param | Tipo | Predefinito | Descrizione | +| Parametro | Tipo | Predefinito | Descrizione | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Branch base da controllare per i 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 una PR `OPEN` prima di eseguire qualsiasi sonda di conflitto — senza `gh`, la politica -cortocircuita per consentire. Esegui `gh auth login` con un token di accesso personale che ha -scope `repo` per l'accesso in lettura alle pull request. +GitHub CLI (`gh`) è richiesto per questo criterio. Il criterio usa `gh pr view` per confermare +che esiste una PR `OPEN` prima di eseguire qualsiasi sonda di conflitto — senza `gh`, il criterio +interrompe il percorso per consentire. Esegui `gh auth login` con un personal access token che ha +lo scope `repo` per l'accesso in lettura alle pull request. --- @@ -785,23 +779,23 @@ scope `repo` per l'accesso in lettura alle pull request. ### `require-ci-green-before-stop` **Evento:** Stop -**Predefinito:** Nega lo stop quando i controlli CI stanno fallendo o sono ancora in esecuzione sul branch corrente. Controlla sia i run del workflow GitHub Actions che i controlli di bot di terze parti (ad es. CodeRabbit, SonarCloud, Codecov). Tratta conclusioni `skipped` e `cancelled` come success. Restituisce un messaggio informativo quando tutti i controlli passano. +**Predefinito:** Nega l'arresto quando i controlli CI stanno fallendo o sono ancora in esecuzione sul branch corrente. Controlla sia i run dei workflow GitHub Actions che i controlli di bot di terze parti (ad es. CodeRabbit, SonarCloud, Codecov). Tratta le conclusioni `skipped` e `cancelled` come successo. 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 ai -run del workflow Actions e l'API Checks. Se `gh` non è installato o non autenticato, la politica fallisce open e riporta il motivo a Claude. +Questo criterio richiede che [GitHub CLI](https://cli.github.com/) (`gh`) sia installato e autenticato. +Esegui `gh auth login` con un personal access token che ha lo scope `repo` per l'accesso in lettura ai +run dei workflow Actions e all'API Checks. Se `gh` non è installato o non autenticato, il criterio fallisce in modo aperto e segnala il motivo a Claude. --- --- -## Disabilitare politiche individuali +## Disabilitazione di criteri individuali -Rimuovi una politica specifica da `enabledPolicies` nella tua configurazione, o disattivala nella scheda Politiche della dashboard. +Rimuovi uno specifico criterio da `enabledPolicies` nella tua configurazione, o disabilitalo nel tab Policies del dashboard. ```json { @@ -812,4 +806,4 @@ Rimuovi una politica specifica da `enabledPolicies` nella tua configurazione, o } ``` -Le politiche non elencate in `enabledPolicies` non vengono eseguite, anche se esistono voci `policyParams` per loro. \ No newline at end of file +I criteri non elencati in `enabledPolicies` non vengono eseguiti, anche se esistono voci `policyParams` per loro. \ No newline at end of file diff --git a/docs/it/configuration.mdx b/docs/it/configuration.mdx index 41fc7c4a..da2ebbcf 100644 --- a/docs/it/configuration.mdx +++ b/docs/it/configuration.mdx @@ -1,29 +1,30 @@ --- + --- title: Configurazione -description: "Formato del file di configurazione, sistema a tre livelli e regole di merge" +description: "Formato file di configurazione, sistema a tre scope e regole di merge" icon: gear --- -failproofai utilizza file di configurazione JSON per controllare quali policy sono attive, come si comportano e da dove vengono caricate le policy personalizzate. La configurazione è progettata per essere facilmente condivisibile con il tuo team - esegui il commit nel tuo repository e ogni sviluppatore otterrà la stessa rete di sicurezza dell'agente. +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 - esegui il commit nel tuo repository e ogni sviluppatore avrà la stessa rete di sicurezza per gli agent. --- -## Ambiti di configurazione +## Scope di configurazione -Esistono tre ambiti di configurazione, valutati in ordine di priorità: +Esistono tre scope di configurazione, valutati in ordine di priorità: -| Ambito | Percorso file | Scopo | -|--------|---------------|-------| -| **progetto** | `.failproofai/policies-config.json` | Impostazioni per repository, eseguito il commit nel controllo versione | -| **locale** | `.failproofai/policies-config.local.json` | Override personali per repository, ignorati da git | -| **globale** | `~/.failproofai/policies-config.json` | Impostazioni predefinite a livello utente su tutti i progetti | +| Scope | Percorso file | Scopo | +|-------|-----------|---------| +| **project** | `.failproofai/policies-config.json` | Impostazioni per-repo, committate nel controllo versioni | +| **local** | `.failproofai/policies-config.local.json` | Override personali per-repo, nel gitignore | +| **global** | `~/.failproofai/policies-config.json` | Impostazioni predefinite a livello utente per tutti i progetti | Quando failproofai riceve un evento hook, carica e unisce tutti e tre i file che esistono per la directory di lavoro corrente. ### Regole di merge -**`enabledPolicies`** - l'unione di tutti e tre gli ambiti. Una policy abilitata a qualsiasi livello è attiva. +**`enabledPolicies`** - l'unione di tutti e tre gli scope. Una policy abilitata a qualsiasi livello è attiva. ```text project: ["block-sudo"] @@ -33,7 +34,7 @@ global: ["block-sudo", "sanitize-api-keys"] resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← unione senza duplicati ``` -**`policyParams`** - il primo ambito che definisce i parametri per una data policy vince completamente. Non esiste un merge profondo dei valori all'interno dei parametri di una policy. +**`policyParams`** - il primo scope che definisce i parametri per una determinata policy vince completamente. Non esiste un merge profondo dei valori all'interno dei parametri di una policy. ```text project: block-sudo → { allowPatterns: ["sudo apt-get update"] } @@ -47,12 +48,12 @@ project: (no block-sudo entry) local: (no block-sudo entry) global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo systemctl status"] } ← ricade al global +resolved: { allowPatterns: ["sudo systemctl status"] } ← cade a global ``` -**`customPoliciesPath`** - il primo ambito che la definisce vince. +**`customPoliciesPath`** - il primo scope che la definisce vince. -**`llm`** - il primo ambito che lo definisce vince. +**`llm`** - il primo scope che la definisce vince. --- @@ -103,7 +104,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← ricade al global Tipo: `string[]` -Elenco di 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. +Lista dei nomi delle policy da abilitare. I nomi devono corrispondere esattamente agli identificativi delle 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`. @@ -111,63 +112,63 @@ Le policy non in `enabledPolicies` sono inattive, anche se hanno voci in `policy Tipo: `Record>` -Override di parametri per ogni policy. La chiave esterna è il nome della policy; le chiavi interne sono specifiche della policy. Ogni policy documenta i suoi parametri disponibili in [Built-in Policies](/it/built-in-policies). +Override dei parametri per-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 incorporati della policy. Gli utenti che non configurano affatto `policyParams` ottengono 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 del hook, ma segnalate come avvisi quando esegui `failproofai policies`. +Le chiavi sconosciute all'interno del blocco dei parametri di una policy vengono silenziosamente ignorate al momento dell'attivazione dell'hook, ma segnalate come avvisi quando esegui `failproofai policies`. #### `hint` (trasversale) Tipo: `string` (opzionale) -Un messaggio aggiunto al motivo quando una policy restituisce `deny` o `instruct`. Usalo per dare a Claude una guida attuabile senza modificare la policy stessa. +Un messaggio aggiunto alla ragione quando una policy restituisce `deny` o `instruct`. Usalo per dare a Claude una guida pratica senza modificare la policy stessa. -Funziona con qualsiasi tipo di policy — built-in, personalizzato (`custom/`), convenzione del progetto (`.failproofai-project/`) o convenzione dell'utente (`.failproofai-user/`). +Funziona con qualsiasi tipo di policy — incorporata, personalizzata (`custom/`), convenzione di progetto (`.failproofai-project/`), o convenzione utente (`.failproofai-user/`). ```json { "policyParams": { "block-force-push": { - "hint": "Try creating a fresh branch instead." + "hint": "Prova a creare 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 prima l'approvazione all'utente." } } } ``` -Quando `block-force-push` nega, Claude vede: *"Force-pushing is blocked. Try creating a fresh branch instead."* +Quando `block-force-push` nega, Claude vede: *"Force-pushing è bloccato. Prova a creare un nuovo branch."* -I valori non stringa e le stringhe vuote vengono silenziosamente ignorati. Se `hint` non è impostato, il comportamento rimane invariato (retrocompatibile). +I valori non-stringa e le stringhe vuote vengono silenziosamente ignorate. Se `hint` non è impostato, il comportamento rimane invariato (retrocompatibile). ### `customPoliciesPath` Tipo: `string` (percorso assoluto) -Percorso a un file JavaScript contenente policy hook personalizzate. Viene impostato automaticamente da `failproofai policies --install --custom ` (il percorso viene risolto in assoluto prima di essere archiviato). +Percorso di un file JavaScript contenente policy hook personalizzate. Questo viene impostato automaticamente da `failproofai policies --install --custom ` (il percorso viene risolto in assoluto prima di essere memorizzato). -Il file viene caricato di nuovo ad ogni evento hook - non c'è caching. Vedi [Custom Policies](/it/custom-policies) per i dettagli di authoring. +Il file viene caricato di nuovo su 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 al `customPoliciesPath` esplicito, failproofai scopre automaticamente e carica i file di policy dalle directory `.failproofai/policies/`: -| Livello | Directory | Ambito | -|---------|-----------|--------| -| Progetto | `.failproofai/policies/` | Condiviso con il team tramite controllo versione | -| Utente | `~/.failproofai/policies/` | Personale, si applica a tutti i progetti | +| Livello | Directory | Scope | +|-------|-----------|-------| +| Project | `.failproofai/policies/` | Condiviso con il team tramite controllo versioni | +| User | `~/.failproofai/policies/` | Personale, si applica a tutti i progetti | -**Corrispondenza file:** Solo i file che corrispondono a `*policies.{js,mjs,ts}` vengono caricati (ad es. `security-policies.mjs`, `workflow-policies.js`). Gli altri file nella directory vengono ignorati. +**Corrispondenza file:** Solo i file corrispondenti a `*policies.{js,mjs,ts}` vengono caricati (ad es. `security-policies.mjs`, `workflow-policies.js`). Gli altri file nella directory vengono ignorati. -**Nessuna configurazione necessaria:** Le policy di convenzione non richiedono voci in `policies-config.json`. Basta rilasciare i file nella directory e vengono rilevati al prossimo evento hook. +**Nessuna configurazione necessaria:** Le policy di convenzione non richiedono voci in `policies-config.json`. Basta eliminare i file nella directory e verranno prelevati al prossimo evento hook. -**Caricamento unione:** Entrambe le directory di convenzione del progetto e dell'utente vengono scansionate. Tutti i file corrispondenti da entrambi i livelli vengono caricati (a differenza di `customPoliciesPath` che utilizza first-scope-wins). +**Caricamento unione:** 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 usa first-scope-wins). Vedi [Custom Policies](/it/custom-policies) per ulteriori dettagli ed esempi. @@ -190,36 +191,44 @@ Configurazione del client LLM per le policy che effettuano chiamate AI. Non rich ## Gestione della configurazione dalla CLI -I comandi `policies --install` e `policies --uninstall` scrivono nel file di impostazioni hook della CLI del tuo 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 dell'agent CLI (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: - - **Claude Code**: `~/.claude/settings.json` (utente), `/.claude/settings.json` (progetto), `/.claude/settings.local.json` (locale) - - **OpenAI Codex**: `~/.codex/hooks.json` (utente), `/.codex/hooks.json` (progetto) — Codex non ha un ambito `locale` - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (utente), `/.github/hooks/failproofai.json` (progetto) — Copilot non ha ambito locale. Le voci hook utilizzano i campi di comando `bash`/`powershell` con chiave OS di Copilot con `timeoutSec`; il file contiene un marcatore `version: 1` di livello superiore. Il supporto Copilot CLI è **beta** mentre verifichiamo lo schema del record `events.jsonl` (che la documentazione pubblica non specifica) rispetto a più sessioni nel mondo reale. -- **`policies-config.json`** — dice a failproofai quali policy valutare e con quali parametri (condiviso su tutte le CLI agente) +- **Impostazioni Agent CLI** — dice all'agent di chiamare `failproofai --hook ` su ogni tool use: + - **Claude Code**: `~/.claude/settings.json` (user), `/.claude/settings.json` (project), `/.claude/settings.local.json` (local) + - **OpenAI Codex**: `~/.codex/hooks.json` (user), `/.codex/hooks.json` (project) — Codex non ha uno scope `local` + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (user), `/.github/hooks/failproofai.json` (project) — Copilot non ha uno scope `local`. Gli entry degli hook utilizzano i campi comando `bash`/`powershell` di Copilot con chiave OS con `timeoutSec`; il file contiene un marcatore `version: 1` di primo livello. Il supporto Copilot CLI è **beta** mentre verifichiamo lo schema del record `events.jsonl` (che la documentazione pubblica non specifica) rispetto a più sessioni reali. + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `/.cursor/hooks.json` (project) — Cursor non ha uno scope `local`. Gli entry degli hook utilizzano la forma `{type, command, timeout}` a forma Claude (nessuna divisione `bash`/`powershell`), ma memorizzati sotto chiavi evento in camelCase (`preToolUse`, `beforeSubmitPrompt`, …) in un array flat secondo lo [schema hooks](https://cursor.com/docs/hooks) di Cursor; il file contiene un marcatore `version: 1` di primo livello. Il gestore canonicalizza camelCase → PascalCase tramite `CURSOR_EVENT_MAP` in modo che le policy incorporate esistenti si attivino senza modifiche. Il supporto Cursor Agent è **beta** mentre verifichiamo il formato di trascrizione di Cursor su disco (non specificato nella documentazione pubblica) rispetto a più installazioni reali. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (user), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (project) — OpenCode non ha uno scope `local`. A differenza degli altri quattro CLI, OpenCode **non ha un sistema hook di comando esterno**: carica plugin JS/TS in-process esplicitamente registrati tramite l'array `plugin: []` in `opencode.json` (l'auto-discovery da `.opencode/plugins/` **non** è il modo in cui i plugin si caricano su opencode v1.14.33). L'installazione rilascia un piccolo shim plugin generato che effettua una subprocess-call al binario failproofai e traduce la risposta JSON a forma Claude del binario di nuovo in semantica plugin (`throw new Error()` per deny, `client.session.prompt(...)` per instruct, no-op per allow). Le sessioni vivono nel DB SQLite di opencode a `~/.local/share/opencode/opencode.db`; il visualizzatore di sessioni della dashboard le legge tramite `opencode db --format json` e `opencode export `. Il supporto OpenCode è **beta** mentre verifichiamo il comportamento tra versioni e rispetto a più sessioni reali. Vedi la [documentazione plugin OpenCode](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `/.pi/settings.json` (project) — Pi non ha uno scope `local`. Pi carica pacchetti di estensione TypeScript all'avvio; il file di impostazioni è un array di stringhe flat `{"packages": ["./relative/path", …]}`. failproofai scrive una singola voce di array packages che punta alla directory `pi-extension/` raggruppata. L'estensione internamente si iscrive agli eventi `tool_call` / `user_bash` / `input` / `session_start` di Pi e shell out a `failproofai --hook --cli pi`; il gestore canonicalizza underscore_lower_snake_case → PascalCase tramite `PI_EVENT_MAP` in modo che le policy incorporate esistenti si attivino senza modifiche. Il supporto 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 uno scope `local` (documenta uno scope `system` a `/etc/gemini-cli/settings.json` che failproofai non espone). Gli entry degli hook utilizzano la forma Claude `{type, command, timeout}` avvolta nello schema matcher di Gemini `{matcher, hooks: [...]}` con `matcher: "*"` per impostazione predefinita. Gli eventi sono PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); il gestore esegue il mapping a nomi canonici Claude tramite `GEMINI_EVENT_MAP`. I nomi dei tool sono snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — il gestore canonicalizza tramite `GEMINI_TOOL_MAP` in modo che le policy incorporate esistenti si attivino senza modifiche. L'evaluator della policy emette la forma flat di Gemini `{decision: "deny", reason}` (preferita secondo la Golden Rule di Gemini con contratto 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 Gemini CLI è **beta** mentre ampliamo la copertura nel mondo reale. Vedi la [documentazione hook Gemini CLI](https://geminicli.com/docs/hooks/). +- **`policies-config.json`** — dice a failproofai quali policy valutare e con quali parametri (condiviso tra tutti gli agent CLI) -Passa `--cli claude|codex|copilot` per targetizzare uno specifico agente (separati da spazio o ripetuti per qualsiasi sottoinsieme): +Passa `--cli claude|codex|copilot|cursor|opencode|pi|gemini` per scegliere un agent specifico (separati da spazi o ripetuti per qualsiasi sottoinsieme): ```bash failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project -failproofai policies --install --cli claude codex copilot +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 claude codex copilot cursor opencode pi gemini ``` -Quando `--cli` viene omesso, `failproofai` rileva quali CLI agente sono installate (`which claude` / `which codex` / `which copilot`): +Quando `--cli` viene omesso, `failproofai` rileva quali agent CLI sono installati (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): -- **Una CLI rilevata** — auto-seleziona quella CLI senza chiedere. -- **Più CLI rilevate** in un terminale interattivo — mostra un prompt di selezione singola con frecce: quando due CLI sono presenti le scelte sono `Both`, ` only`, ` only`; con tre CLI la prima opzione diventa `All` (↑↓ per muoversi, Invio per selezionare, ^C per uscire). -- **Più CLI rilevate** in un'esecuzione non interattiva (CI, no TTY) — installa per tutte le CLI rilevate senza chiedere. -- **Nessuna rilevata** — ricade a `claude`, con un avviso che nessun binario agente è stato trovato in PATH; il comando hook viene comunque scritto quindi si attiva non appena installi uno. +- **Un CLI rilevato** — seleziona automaticamente quel CLI senza chiedere. +- **Più CLI rilevati** in un terminal interattivo — mostra un prompt single-select a freccia raggruppato in una sezione `Detected (N)` (con una riga aggregata `Install for all N detected` + ogni CLI rilevato individualmente) e una sezione `Not installed (M) · install hooks ahead of time` elencando ogni CLI non rilevato supportato come opzione di forward-install (↑↓ per muoversi, Enter per selezionare, ^C per uscire). Il flusso di disinstallazione mostra solo la sezione Detected. +- **Più CLI rilevati** in un'esecuzione non-interattiva (CI, nessun TTY) — installa per tutti i CLI rilevati senza chiedere. +- **Nessuno rilevato** — ricade su `claude`, con un avviso che nessun binario agent è stato trovato in PATH; il comando hook è comunque scritto in modo che si attivi non appena ne installi uno. -Puoi modificare `policies-config.json` direttamente in qualsiasi momento; i cambiamenti hanno effetto immediato al 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 riavvio. --- ## Esempio: configurazione a livello di progetto con impostazioni predefinite del team -Esegui il commit di `.failproofai/policies-config.json` nel tuo repository: +Esegui il commit di `.failproofai/policies-config.json` nel tuo repo: ```json { @@ -238,4 +247,4 @@ Esegui il commit di `.failproofai/policies-config.json` nel tuo repository: } ``` -Ogni sviluppatore può quindi creare `.failproofai/policies-config.local.json` (ignorato da git) per override personali senza influenzare i compagni di team. \ No newline at end of file +Ogni sviluppatore può quindi creare `.failproofai/policies-config.local.json` (nel gitignore) per override personali senza influenzare i compagni di squadra. \ No newline at end of file diff --git a/docs/it/dashboard.mdx b/docs/it/dashboard.mdx index 52b6c553..8606b373 100644 --- a/docs/it/dashboard.mdx +++ b/docs/it/dashboard.mdx @@ -1,6 +1,6 @@ --- title: Dashboard -description: "Monitora le sessioni degli agenti, esamina le chiamate agli strumenti e gestisci le policy" +description: "Monitora le sessioni degli agenti, rivedi le chiamate ai tool e gestisci le policy" icon: chart-line --- @@ -16,7 +16,7 @@ failproofai Si apre su `http://localhost:8020`. -Il dashboard legge direttamente dal filesystem - le tue cartelle di progetto Claude Code e i file di configurazione failproofai. Niente viene scritto su un servizio remoto. +Il dashboard legge direttamente dal filesystem - le cartelle del tuo progetto Claude Code e i file di configurazione di failproofai. Nulla viene scritto su un servizio remoto. --- @@ -24,55 +24,55 @@ Il dashboard legge direttamente dal filesystem - le tue cartelle di progetto Cla ### Progetti -Elenca tutti i progetti Claude Code, OpenAI Codex e GitHub Copilot 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 transcript 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`. Un progetto che è stato utilizzato da più CLI viene visualizzato come una singola riga con tutti i badge corrispondenti. Usa il dropdown **CLI** sopra la tabella per filtrare per uno specifico agent CLI; l'URL conserva la tua selezione come `?cli=claude|codex|copilot`. +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 scoperto da `~/.claude/projects/` (o dal percorso impostato da `CLAUDE_PROJECTS_PATH`); i progetti Codex vengono scoperti scansionando ogni transcript sotto `~/.codex/sessions///
/*.jsonl` e raggruppati per il `cwd` registrato nel primo record di ogni sessione; i progetti Copilot CLI vengono scoperti scansionando ogni `~/.copilot/session-state//workspace.yaml` (configurabile tramite `COPILOT_HOME`) e raggruppati per il campo `cwd`; i progetti Cursor Agent vengono scoperti scansionando i metadati per sessione sotto `~/.cursor/agent-sessions//` (configurabile tramite `CURSOR_HOME`, con `conversations/` e `sessions/` provati come fallback) per uno scalare `cwd` in `meta.json` / `session.json` / `workspace.yaml`; i progetti OpenCode vengono scoperti interrogando il suo DB SQLite su `~/.local/share/opencode/opencode.db` tramite `opencode db --format json` (leggiamo le tabelle `session` e `project` e raggruppiamo per `project_id`); i progetti Pi vengono scoperti scansionando i transcript 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 scoperti scansionando `~/.gemini/tmp//chats/session--.jsonl` (configurabile tramite `GEMINI_SESSIONS_DIR`) e recuperando il cwd canonico dal marcatore di testo sibling `.project_root`. Un progetto che è stato utilizzato da più CLI viene visualizzato 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`. Ogni progetto mostra: - Nome del progetto (derivato dal percorso della cartella) -- Un badge CLI — `Claude Code` (arancione), `OpenAI Codex` (viola) e/o `GitHub Copilot` (blu) +- Un badge CLI — `Claude Code` (arancione), `OpenAI Codex` (viola), `GitHub Copilot` (blu), `Cursor Agent` (verde smeraldo), `OpenCode` (ambra), `Pi` (rosa) e/o `Gemini CLI` (azzurro) - 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 della sessione - Timestamp di inizio e fine -- Numero di chiamate agli strumenti -- Numero di attività hook (policy che si sono attivate) +- Numero di chiamate ai tool +- Conteggio dell'attività degli hook (policy che si sono attivate) -Usa il filtro intervallo date e la ricerca per ID sessione per restringere l'elenco. Le sessioni sono impaginate. +Usa il filtro dell'intervallo di date e la ricerca per ID di 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 chiave per gli agenti autonomi: cosa ha fatto l'agente e è rimasto in traccia? Un badge CLI accanto all'intestazione indica se la sessione è un transcript Claude Code o OpenAI Codex. 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 la giusta direzione? 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 timeline di tutto ciò che è accaduto in una sessione: -- **Messaggi** - Risposte di testo di Claude e prompt degli utenti -- **Chiamate agli strumenti** - Ogni strumento che Claude ha invocato, con il suo input e output -- **Attività policy** - Per ogni chiamata agli strumenti, quali policy si sono attivate e quale decisione hanno restituito +- **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à delle policy** - Per ogni chiamata ai tool, quali policy si sono attivate e quale decisione hanno restituito -La barra delle statistiche in alto mostra la durata della sessione, il numero totale di chiamate agli strumenti e un riepilogo delle decisioni hook (conteggi allow / deny / instruct). +La barra delle statistiche in alto mostra la durata della sessione, il numero totale di chiamate ai tool e un riepilogo delle decisioni degli hook (conteggi di allow / deny / instruct). -Puoi esportare la sessione come file ZIP o JSONL usando il pulsante di download. +Fai clic sul pulsante **Download Logs** per esportare la sessione. Per le sessioni Claude Code, Codex, Copilot, Cursor, Pi e Gemini ottieni il transcript JSONL originale su disco byte-per-byte; per OpenCode (le cui sessioni risiedono in SQLite, non su disco) ottieni un documento JSON che rispecchia le tabelle `session` / `messages` / `parts` sottostanti. ### Policy -Una pagina a due schede per gestire le policy e esaminare l'attività. +Una pagina a due schede per gestire le policy e rivedere l'attività. - - Attiva o disattiva singole policy con un solo clic (scrive su `~/.failproofai/policies-config.json`) + - Attiva o disattiva le singole policy con un solo clic (scrive su `~/.failproofai/policies-config.json`) - Espandi una policy per configurare i suoi parametri (per le policy che supportano `policyParams`) - - Installa o rimuovi hook per un determinato ambito + - Installa o rimuovi gli hook per un determinato scope - Imposta un percorso file di policy personalizzato - - Cronologia impaginata completa 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)_), nome della policy o ID della sessione - - Ogni riga mostra: timestamp, nome della policy, decisione, badge CLI (arancione = Claude Code, viola = OpenAI Codex, blu = GitHub Copilot), nome dello strumento, ID della sessione e il motivo delle decisioni deny/instruct - - Fai clic su un ID sessione per aprire il suo transcript — il visualizzatore rileva automaticamente quale CLI ha attivato l'hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`) e visualizza 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)_), nome della policy o ID della sessione + - Ogni riga mostra: timestamp, nome della policy, decisione, badge CLI (arancione = Claude Code, viola = OpenAI Codex, blu = GitHub Copilot, verde smeraldo = Cursor Agent, ambra = OpenCode, rosa = Pi, azzurro = Gemini CLI), nome del tool, ID della sessione e il motivo delle decisioni deny/instruct + - Fai clic su un ID di sessione per aprire la sua trascrizione — il visualizzatore rileva automaticamente quale CLI ha attivato l'hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`) e visualizza il badge CLI corrispondente nell'intestazione @@ -80,13 +80,13 @@ Una pagina a due schede per gestire le policy e esaminare l'attività. ## Aggiornamento automatico -Il 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 sessioni di agenti autonomi a lunga durata. +Il 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à delle policy man mano che appaiono. Essenziale per monitorare le sessioni degli agenti autonomi di lunga durata. --- ## Disabilitazione delle pagine -Se hai bisogno solo di alcune parti del dashboard, imposta `FAILPROOFAI_DISABLE_PAGES` su un elenco separato da virgole di nomi di pagina: +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 @@ -104,7 +104,7 @@ Il dashboard supporta la modalità chiara e scura. Attiva/disattiva tramite il p ## Configurazione del percorso dei progetti -Per impostazione predefinita, il dashboard legge dalla directory dei progetti Claude Code standard. Sostituiscilo per configurazioni personalizzate: +Per impostazione predefinita, il dashboard legge dalla directory dei progetti Claude Code standard. Esegui l'override per configurazioni personalizzate: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -114,13 +114,13 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai ## Accesso da un host non-localhost -Quando esegui il dashboard in **modalità dev** (`npm run dev`) e lo accedi da un nome host diverso da `localhost` - ad esempio, un dominio personalizzato, un IP remoto o un URL tunnelato - potresti visualizzare un avviso come: +Quando esegui il dashboard in **modalità dev** (`npm run dev`) e vi accedi da un hostname diverso da `localhost` - ad esempio, un dominio personalizzato, un IP remoto o un URL tunneled - potresti visualizzare 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 di sola modalità 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 funzione solo per lo sviluppo. Per consentire il tuo host, usa il flag `--allowed-origins`: ```bash npm run dev -- --allowed-origins dashboard.example.com @@ -139,5 +139,5 @@ FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Questo si applica solo alla modalità dev. Quando esegui `failproofai` (modalità di produzione), non c'è un websocket HMR e nessun problema di risorsa dev cross-origin. +Questo si applica solo alla modalità dev. Quando esegui `failproofai` (modalità di produzione), non c'è websocket HMR e nessun problema di risorsa dev cross-origin. \ No newline at end of file diff --git a/docs/it/getting-started.mdx b/docs/it/getting-started.mdx index ebd9891c..91901096 100644 --- a/docs/it/getting-started.mdx +++ b/docs/it/getting-started.mdx @@ -1,13 +1,13 @@ --- -title: Introduzione -description: "Installa failproofai, abilita le politiche e lascia che i tuoi agenti funzionino in modo affidabile" +title: Iniziare +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 (opzionale - necessario solo per compilare dal sorgente) +- **Bun** >= 1.3.0 (opzionale - necessario solo per compilare da sorgente) --- @@ -30,21 +30,25 @@ bun add -g failproofai ## Avvio rapido - - Le politiche sono regole che vengono eseguite prima e dopo ogni chiamata a uno strumento dell'agente. Catturano comandi distruttivi, fughe di segreti e altri modi di fallimento prima che causino danni. + + Le policy sono regole che vengono eseguite prima e dopo ogni chiamata a uno strumento dell'agent. Intercettano comandi distruttivi, fughe di segreti e altri problemi prima che causino danni. ```bash failproofai policies --install ``` - Questo scrive voci di hook nelle tue CLI di agenti installate (`~/.claude/settings.json` di Claude Code, `~/.codex/hooks.json` di OpenAI Codex, o `~/.copilot/hooks/failproofai.json` di GitHub Copilot CLI). Quando è presente più di una, ti verrà richiesto di sceglierne una; passa `--cli claude codex copilot` (qualsiasi sottoinsieme) per saltare la richiesta. + Questo aggiunge voci di hook ai tuoi CLI agent 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, o il file `~/.gemini/settings.json` di Gemini CLI). Se ne è presente più di uno, ti verrà chiesto di scegliere; passa `--cli claude codex copilot cursor opencode pi gemini` (qualsiasi sottoinsieme) per saltare la richiesta. - Il supporto per GitHub Copilot CLI è **beta** — installa con `--cli copilot`. + 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`. ```bash failproofai policies --install --scope project failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project + 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 block-sudo block-rm-rf sanitize-api-keys ``` @@ -53,56 +57,56 @@ bun add -g failproofai failproofai policies ``` - Mostra ogni politica, se è abilitata e eventuali parametri configurati. + Mostra ogni policy, se è abilitata e tutti i parametri configurati. ```bash failproofai ``` - Apre una 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 a strumenti e gestire le policy. - - Avvia Claude Code come al solito. Se l'agente tenta qualcosa di rischioso, failproofai lo intercetta automaticamente. Lascialo in esecuzione senza sorveglianza e rivedi quello che è accaduto nella dashboard. + + Avvia Claude Code come al solito. Se l'agent prova a fare qualcosa di rischioso, failproofai lo intercetta automaticamente. Lascialo in esecuzione senza supervisione e rivedi cosa è accaduto nella dashboard. --- -## Come funzionano le politiche +## Come funzionano le policy -Ogni volta che un agente esegue uno strumento, Claude Code chiama failproofai come un 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 extra viene aggiunto al prompt dell'agente +- **allow** - l'agent procede normalmente +- **deny** - l'azione viene bloccata, all'agent viene spiegato il motivo +- **instruct** - viene aggiunto contesto aggiuntivo 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 le politiche del team con politiche basate su convenzioni +## Configura policy di team con le policy basate su convenzione -Il modo più veloce per stabilire standard di qualità in tutto il team è la convenzione `.failproofai/policies/`. Inserisci i file di politica in questa directory e vengono 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/`. Copia i file delle policy in questa directory e verranno caricati automaticamente — nessun flag, nessuna modifica di configurazione, nessun comando di installazione. - + ```bash mkdir -p .failproofai/policies ``` - - Copia gli esempi di avvio o scrivi i tuoi: + + Copia gli esempi di partenza o scrivi i tuoi: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -120,40 +124,40 @@ Il modo più veloce per stabilire standard di qualità in tutto il team è la co fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) { - return instruct("Esegui i test prima di eseguire il commit."); + return instruct("Esegui i test prima di fare il commit."); } return allow(); }, }); ``` - + ```bash git add .failproofai/policies/ git commit -m "Add team quality policies" ``` - Ogni membro del team che ha failproofai installato raccoglie automaticamente queste politiche. Non è necessaria alcuna configurazione per sviluppatore. + Ogni membro del team che ha failproofai installato raccoglie automaticamente queste policy. Nessuna configurazione per sviluppatore necessaria. -Esegui il commit di `.failproofai/policies/` al tuo repository in modo che tutto il team condivida gli stessi standard. Man mano che il tuo team scopre nuovi modi di fallimento, aggiungi politiche e esegui il push — tutti ricevono l'aggiornamento al loro prossimo `git pull`. Nel tempo, queste politiche diventano uno standard di qualità vivo che continua a migliorare. +Effettua il commit di `.failproofai/policies/` nel tuo repository in modo che l'intero team condivida gli stessi standard. Man mano che il tuo team scopre nuovi problemi, aggiungi policy e fai il push — tutti riceveranno l'aggiornamento al loro prossimo `git pull`. Nel tempo, queste policy diventano uno standard di qualità in continua evoluzione che migliora costantemente. --- ## Archiviazione dei dati -Tutta la configurazione e i log rimangono sul tuo computer: +Tutte le configurazioni e i log rimangono sul tuo computer: -| Percorso | Cosa archivia | -|------|----------------| -| `~/.failproofai/policies-config.json` | Configurazione globale delle politiche | +| Percorso | Cosa contiene | +|----------|---------------| +| `~/.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/hook.log` | Log di debug per errori di hook personalizzati | | `.failproofai/policies-config.json` | Configurazione per progetto (sottoposta a commit) | -| `.failproofai/policies-config.local.json` | Override personali (gitignored) | +| `.failproofai/policies-config.local.json` | Override personali (esclusi da git) | --- @@ -163,7 +167,7 @@ Tutta la configurazione e i log rimangono sul tuo computer: failproofai policies --uninstall ``` -Rimuove le voci di hook da `~/.claude/settings.json`. I file di configurazione in `~/.failproofai/` vengono conservati. +Rimuove le voci di hook da `~/.claude/settings.json`. I file di configurazione in `~/.failproofai/` vengono mantenuti. --- @@ -175,16 +179,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/pt-br/architecture.mdx b/docs/pt-br/architecture.mdx index 175e217b..f87da985 100644 --- a/docs/pt-br/architecture.mdx +++ b/docs/pt-br/architecture.mdx @@ -8,22 +8,22 @@ Este documento explica como o failproofai funciona internamente: como o sistema --- -## Visão geral +## Visão Geral O failproofai possui dois subsistemas independentes: -1. **Handler de hooks** - Um subprocesso CLI rápido que o Claude Code invoca em 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. +1. **Hook handler** - Um subprocesso CLI rápido que o Claude Code invoca a cada chamada de ferramenta do agente. Avalia 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. -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. +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 através do sistema de arquivos. --- -## Handler de hooks +## Hook handler ### Integração com o Claude Code -Quando você executa `failproofai policies --install`, ele escreve entradas como esta no `~/.claude/settings.json`: +Ao executar `failproofai policies --install`, ele grava entradas como estas no `~/.claude/settings.json`: ```json { @@ -44,7 +44,7 @@ Quando você executa `failproofai policies --install`, ele escreve entradas como } ``` -O Claude Code então invoca `failproofai --hook PreToolUse` como um subprocesso antes de cada chamada de ferramenta, passando um payload JSON via stdin. +O Claude Code então invoca `failproofai --hook PreToolUse` como subprocesso antes de cada chamada de ferramenta, passando um payload JSON via stdin. ### Formato do payload @@ -62,11 +62,11 @@ O Claude Code então invoca `failproofai --hook PreToolUse` como um subprocesso Para eventos `PostToolUse`, o payload também contém `tool_result` com a saída da ferramenta. -O handler aplica 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 handler impõe um limite de 1 MB para o stdin. Payloads que excedem esse limite são descartados e todas as políticas implicitamente permitem a operação. ### Formato da resposta -**Negar (PreToolUse):** +**Deny (PreToolUse):** ```json { "hookSpecificOutput": { @@ -76,7 +76,7 @@ O handler aplica um limite de 1 MB para o stdin. Payloads que excedam esse limit } ``` -**Negar (PostToolUse):** +**Deny (PostToolUse):** ```json { "hookSpecificOutput": { @@ -85,7 +85,7 @@ O handler aplica um limite de 1 MB para o stdin. Payloads que excedam esse limit } ``` -**Instruir (qualquer evento exceto Stop):** +**Instruct (qualquer evento exceto Stop):** ```json { "hookSpecificOutput": { @@ -94,17 +94,17 @@ O handler aplica um limite de 1 MB para o stdin. Payloads que excedam esse limit } ``` -**Instruir em evento Stop:** +**Instruct no evento Stop:** - Código de saída: `2` - Motivo escrito no stderr (não no stdout) -**Permitir:** +**Allow:** - Código de saída: `0` - stdout vazio -**Permitir com mensagem:** +**Allow com mensagem:** -`allow(message)` permite que uma política envie contexto informativo de volta ao Claude mesmo quando a operação é permitida. O handler de hooks escreve 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 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): ```json // Written to stdout by the hook handler process @@ -115,7 +115,7 @@ O handler aplica 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, as mensagens são unidas com quebras de linha em uma única string `additionalContext` +- Quando múltiplas políticas retornam `allow` com uma mensagem, suas mensagens são unidas com quebras de linha em uma única string `additionalContext` - Se nenhuma política fornecer uma mensagem, o stdout fica vazio (como antes) ### Pipeline de processamento @@ -139,7 +139,7 @@ stdin JSON → exit ``` -Todo o processo é executado em menos de 100ms para payloads típicos, sem nenhuma chamada a LLM. +Todo o processo é executado em menos de 100ms para payloads típicos, sem chamadas a LLMs. --- @@ -154,12 +154,12 @@ Todo o processo é executado em menos de 100ms para payloads típicos, sem nenhu ``` Lógica de mesclagem: -- `enabledPolicies` - união deduplicada entre os três arquivos -- `policyParams` - por chave de política, o primeiro arquivo que a define prevalece inteiramente -- `customPoliciesPath` - o primeiro arquivo que o define prevalece -- `llm` - o primeiro arquivo que o define prevalece +- `enabledPolicies` - união sem duplicatas entre os três arquivos +- `policyParams` - por chave de política, o primeiro arquivo que a define vence inteiramente +- `customPoliciesPath` - o primeiro arquivo que o define vence +- `llm` - o primeiro arquivo que o define vence -O dashboard web usa `readHooksConfig()` (somente global) para leitura e escrita, pois não é invocado com um cwd de projeto. +O dashboard web usa `readHooksConfig()` (apenas global) para leitura e escrita, pois não é invocado com um cwd de projeto. --- @@ -173,13 +173,13 @@ Para cada política: 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`. 4. Chama `policy.fn(ctx)` com o contexto resolvido. -5. Se o resultado for `deny`, para imediatamente e retorna essa decisão. +5. Se o resultado for `deny`, interrompe 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 todas as políticas serem executadas: - Se algum `deny` foi retornado, emite a resposta de deny. -- Se algum retorno `instruct` foi coletado, emite uma única resposta de instruct com todas as mensagens unidas. +- Se algum retorno `instruct` foi coletado, emite uma única resposta instruct com todas as mensagens unidas. - Caso contrário, emite uma resposta de allow (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 porque 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, pois 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 strings brutas. Isso evita bypass por 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). +A correspondência de padrões dentro das políticas utiliza tokens de comando analisados (argv), não correspondência de string bruta. Isso evita bypass por injeção de operadores shell (por exemplo, um padrão para `sudo systemctl status *` não pode ser contornado anexando `; 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`. -4. Reescreve recursivamente as importações locais transitivas para garantir compatibilidade com ESM. -5. Escreve arquivos `.mjs` temporários e faz `import()` do arquivo de entrada. +3. Reescreve todos os imports `from "failproofai"` para o caminho real do dist, de modo que `customPolicies` resolva para o mesmo registro `globalThis`. +4. Reescreve recursivamente imports locais transitivos para garantir compatibilidade com ESM. +5. Grava arquivos `.mjs` temporários e executa `import()` no 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 loader retorna um array vazio. As políticas integradas não são afetadas. -As políticas customizadas são avaliadas após todas as políticas integradas. Um `deny` de uma política customizada ainda interrompe as demais políticas customizadas (mas todas as políticas integradas já terão sido executadas nesse ponto). +As políticas customizadas são avaliadas após todas as políticas integradas. Um `deny` de uma política customizada ainda interrompe as demais políticas customizadas subsequentes (mas todos os integrados já terão sido executados nesse ponto). --- -## Registro de atividade +## Log de atividades -Após cada evento de hook, o handler anexa uma linha JSONL ao `~/.failproofai/hook-activity.jsonl`: +Após cada evento de hook, o handler anexa uma linha JSONL em `~/.failproofai/hook-activity.jsonl`: ```json { @@ -270,32 +270,32 @@ O dashboard é uma aplicação **Next.js 16** que utiliza o App Router com React app/ 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 em um projeto + 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 update-hooks-config.ts ← Ativa/desativa política update-policy-params.ts ← Atualiza parâmetros de política - get-hook-activity.ts ← Pagina/pesquisa log de atividade + get-hook-activity.ts ← Pagina/pesquisa o log de atividades install-hooks-web.ts ← Instala/remove hooks pelo navegador api/ - download/[project]/[session]/route.ts ← Exporta sessão como ZIP/JSONL + download/[project]/[session]/route.ts ← Exportação de sessão por CLI (JSONL ou JSON) ``` **Fluxo de dados:** -- 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 (toggle, atualização de parâmetros, instalação/remoção). +- 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). - 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 do cliente para busca de dados. -- Client components apenas onde a interatividade é necessária (toggles de política, pesquisa de atividade, visualizador de log). +- React Server Components para páginas de leitura - carregamento inicial mais rápido, sem bundle cliente para busca de dados. +- Client components apenas onde há interatividade (toggles de política, busca de atividades, visualizador de log). --- @@ -314,18 +314,18 @@ failproofai/ │ ├── hooks-config.ts # Carregamento de configuração multi-escopo │ ├── custom-hooks-registry.ts # Registro de hooks baseado em globalThis │ ├── custom-hooks-loader.ts # Loader ESM para hooks JS do usuário -│ ├── manager.ts # Operações de instalação / remoção / listagem +│ ├── manager.ts # Operações de install / remove / list │ ├── install-prompt.ts # Prompt interativo de seleção de políticas -│ ├── hook-logger.ts # Registro em hook.log -│ ├── hook-activity-store.ts # Persistência de atividade em hook-activity.jsonl -│ └── llm-client.ts # Cliente de API LLM (para políticas baseadas em IA) +│ ├── hook-logger.ts # Logging para hook.log +│ ├── hook-activity-store.ts # Persiste atividade em hook-activity.jsonl +│ └── llm-client.ts # Cliente de API LLM (para políticas com IA) ├── 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 JSONL de transcrição do Claude │ ├── paths.ts # Resolve caminhos do sistema │ └── ... -├── components/ # Componentes React UI compartilhados +├── components/ # Componentes React de UI compartilhados ├── contexts/ # Provedores de contexto React (tema, auto-refresh, telemetria) ├── examples/ # Exemplos de arquivos de hooks customizados └── __tests__/ # Testes unitários e E2E diff --git a/docs/pt-br/built-in-policies.mdx b/docs/pt-br/built-in-policies.mdx index a2aa0609..b470b42b 100644 --- a/docs/pt-br/built-in-policies.mdx +++ b/docs/pt-br/built-in-policies.mdx @@ -1,39 +1,39 @@ --- title: Políticas Integradas -description: "Todas as 39 políticas integradas que detectam modos comuns de falha de agentes" +description: "Todas as 39 políticas integradas que detectam falhas comuns de agentes" icon: shield --- -failproofai é distribuído com 39 políticas integradas que detectam modos comuns de falha 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 workflow impõem um pipeline de commit → push → PR → CI antes que o 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 aplicam um pipeline de commit → push → PR → CI antes que Claude pare. --- -## Visão geral +## Visão Geral As políticas são agrupadas em categorias: | Categoria | Políticas | Tipo de hook | |----------|----------|-----------| -| [Comandos perigosos](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | -| [Comandos de infraestrutura](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | -| [Segredos (sanitizadores)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | -| [Ambiente](#environment) | block-env-files, protect-env-vars | PreToolUse | -| [Acesso a arquivos](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse | +| [Comandos perigosos](#comandos-perigosos) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands | PreToolUse | +| [Comandos de infraestrutura](#comandos-de-infraestrutura) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse | +| [Segredos (sanitizadores)](#segredos-sanitizadores) | 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 | +| [Acesso a arquivos](#acesso-a-arquivos) | 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 | -| [Banco de dados](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse | -| [Avisos](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | -| [Gerenciadores de pacotes](#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 | +| [Banco de dados](#banco-de-dados) | warn-destructive-sql, warn-schema-alteration | PreToolUse | +| [Avisos](#avisos) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | +| [Gerenciadores de pacotes](#gerenciadores-de-pacotes) | prefer-package-manager | PreToolUse | +| [Fluxo de trabalho](#fluxo-de-trabalho) | 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 da ferramenta antes que o agente os veja. +- **`sanitize-`** — remove dados sensíveis da saída da ferramenta antes que o agente a veja. ### Namespaces -Cada política ocupa um slot `/`. As políticas integradas pertencem ao namespace **`exospherehost/`** — por exemplo, `exospherehost/sanitize-jwt`. O namespace evita colisões quando você também carrega políticas personalizadas ou de terceiros com nomes curtos similares. +Cada política ocupa um slot `/`. As políticas integradas pertencem ao namespace **`exospherehost/`** — por exemplo, `exospherehost/sanitize-jwt`. O namespace evita colisões quando você também carrega políticas personalizadas ou de terceiros com nomes abreviados similares. -Na sua configuração, você pode se referir a 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 seu nome abreviado ou pelo nome qualificado; ambas as formas resolvem para a mesma política: ```json { @@ -44,33 +44,33 @@ Na sua configuração, você pode se referir a uma política integrada pelo nome } ``` -Se um nome não contém `/`, failproofai o trata como pertencente ao namespace padrão `exospherehost`. Nomes que já contêm `/` (ex.: `myorg/foo`, `custom/my-hook`) são mantidos como estão. +Se um nome não contiver `/`, o failproofai o trata como pertencente ao namespace padrão `exospherehost`. 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 o 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. Consulte [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para mais detalhes. +Toda política suporta um campo opcional `hint` em `policyParams`. O hint é adicionado à mensagem de deny ou instruct que Claude vê, fornecendo orientações práticas sem modificar o código da política. Funciona com políticas integradas, personalizadas e de convenção. Consulte [Configuração → hint](/pt-br/configuration#hint-cross-cutting) para mais detalhes. --- ## Comandos perigosos -Impede agentes de executar operações difíceis de desfazer ou que possam danificar o sistema hospedeiro. +Impede que agentes executem operações difíceis de desfazer ou que possam danificar o sistema host. ### `block-sudo` **Evento:** PreToolUse (Bash) **Padrão:** Nega qualquer comando `sudo`. -Bloqueia invocações que incluem a palavra-chave `sudo`. A correspondência de padrões é feita nos tokens de comando analisados, não na string bruta, para evitar bypass via injeção de operadores de shell. +Bloqueia invocações que incluem a palavra-chave `sudo`. A correspondência de padrão é feita nos tokens de comando analisados, não na string bruta, para evitar bypass por injeção de operador shell. **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Prefixos exatos de comando que são permitidos. Cada entrada é verificada contra os tokens argv analisados. | +| `allowPatterns` | `string[]` | `[]` | Prefixos de comando exatos que são permitidos. Cada entrada é comparada com os tokens argv analisados. | **Exemplo:** @@ -87,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 verificados contra os tokens analisados, não a string de comando bruta. Isso evita bypass via operadores de 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 impede bypass por meio de operadores shell adicionados (ex.: `sudo systemctl status x; rm -rf /` não corresponde a `sudo systemctl status *`). --- @@ -137,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, toda invocação da CLI correspondente é negada, a menos que o comando corresponda a uma entrada em `allowPatterns`. +Impede que agentes de codificação executem CLIs de infraestrutura ou acionem 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 interrompidos 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 do [`block-sudo`](#block-sudo): os tokens são verificados contra o argv analisado, `*` é um curinga para um token, e qualquer comando contendo um operador de shell isolado (`&&`, `||`, `|`, `;`) ou um token com metacaracteres de 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 o argv analisado, `*` é um curinga para um token, e qualquer comando contendo um operador shell independente (`&&`, `||`, `|`, `;`) ou um token com metacaracteres shell embutidos é rejeitado antes da verificação da lista de permissões para evitar bypasses por injeção. ### `block-kubectl` @@ -296,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 da CLI `gh` que modificam 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` @@ -305,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 correspondidos por esta política — eles são rotineiramente necessários para verificações de workflow (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 bloqueados por esta política — eles são frequentemente 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 em script para permitir mesmo que normalmente seriam negadas. | +| `allowPatterns` | `string[]` | `[]` | Invocações específicas com script a permitir, mesmo que normalmente fossem negadas. | **Exemplo:** @@ -329,12 +329,12 @@ 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. Políticas sanitizadoras 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 negação que impede a saída de ser repassada. +Impede que agentes vazem 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. ### `sanitize-jwt` **Evento:** PostToolUse (todas as ferramentas) -**Padrão:** Oculta tokens JWT (três segmentos base64url separados por `.`). +**Padrão:** Redige tokens JWT (três segmentos base64url separados por `.`). Sem parâmetros. @@ -343,13 +343,13 @@ Sem parâmetros. ### `sanitize-api-keys` **Evento:** PostToolUse (todas as ferramentas) -**Padrão:** Oculta 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:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Padrões regex adicionais para tratar como segredos. | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Padrões regex adicionais a serem tratados como segredos. | **Exemplo:** @@ -371,7 +371,7 @@ Sem parâmetros. ### `sanitize-connection-strings` **Evento:** PostToolUse (todas as ferramentas) -**Padrão:** Oculta strings de conexão de banco de dados que contêm credenciais embutidas (ex.: `postgresql://user:password@host/db`). +**Padrão:** Redige strings de conexão de banco de dados que contêm credenciais embutidas (ex.: `postgresql://user:password@host/db`). Sem parâmetros. @@ -380,7 +380,7 @@ Sem parâmetros. ### `sanitize-private-key-content` **Evento:** PostToolUse (todas as ferramentas) -**Padrão:** Oculta blocos PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, etc.). +**Padrão:** Redige blocos PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, etc.). Sem parâmetros. @@ -389,7 +389,7 @@ Sem parâmetros. ### `sanitize-bearer-tokens` **Evento:** PostToolUse (todas as ferramentas) -**Padrão:** Oculta cabeçalhos `Authorization: Bearer ` onde o token tem 20 ou mais caracteres. +**Padrão:** Redige cabeçalhos `Authorization: Bearer ` onde o token tem 20 ou mais caracteres. Sem parâmetros. @@ -402,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 — apenas arquivos nomeados exatamente como `.env`. Sem parâmetros. @@ -426,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 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` atual garante que o limite permaneça estável mesmo após o Claude entrar em um subdiretório via `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` atual significa que o limite permanece estável mesmo após o Claude executar `cd` em um subdiretório. **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `allowPaths` | `string[]` | `[]` | Prefixos de caminho absoluto que são permitidos mesmo estando fora da raiz do projeto. | +| `allowPaths` | `string[]` | `[]` | Prefixos de caminho absoluto que são permitidos mesmo que estejam fora da raiz do projeto. | **Exemplo:** @@ -451,7 +451,7 @@ Mantém os agentes trabalhando dentro dos limites do projeto e longe de arquivos ### `block-secrets-write` **Evento:** PreToolUse (Write, Edit) -**Padrão:** Nega escritas em arquivos comumente usados para chaves privadas e certificados: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Padrão:** Nega gravações em arquivos comumente usados para chaves privadas e certificados: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Parâmetros:** @@ -501,7 +501,7 @@ Previne pushes acidentais, force-pushes e erros de branch difíceis de desfazer. ``` -Para permitir push em todos os branches (efetivamente desabilitando 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: []`. --- @@ -509,13 +509,13 @@ Para permitir push em todos os branches (efetivamente desabilitando esta políti ### `block-work-on-main` **Evento:** PreToolUse (Bash) -**Padrão:** Nega o checkout direto dos branches `main` ou `master`. +**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. **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Nomes de branches que não podem ser checados diretamente. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Nomes de branches nos quais commit/merge/rebase/cherry-pick é negado. | --- @@ -524,7 +524,7 @@ Para permitir push em todos os branches (efetivamente desabilitando 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 { @@ -541,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 o Claude a prosseguir com cuidado ao executar `git commit --amend`. Não bloqueia o comando. +**Padrão:** Instrui Claude a prosseguir com cuidado ao executar `git commit --amend`. Não bloqueia o comando. Sem parâmetros. @@ -550,7 +550,7 @@ Sem parâmetros. ### `warn-git-stash-drop` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui o Claude a confirmar antes de executar `git stash drop`. Não bloqueia o comando. +**Padrão:** Instrui Claude a confirmar antes de executar `git stash drop`. Não bloqueia o comando. Sem parâmetros. @@ -559,7 +559,7 @@ Sem parâmetros. ### `warn-all-files-staged` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui o Claude a revisar o que está sendo adicionado ao stage ao executar `git add -A` ou `git add .`. Não bloqueia o comando. +**Padrão:** Instrui Claude a revisar o que está sendo staged ao executar `git add -A` ou `git add .`. Não bloqueia o comando. Sem parâmetros. @@ -572,7 +572,7 @@ Detecta operações SQL destrutivas antes que sejam executadas no banco de dados ### `warn-destructive-sql` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui o Claude a confirmar antes de executar SQL contendo `DROP TABLE`, `DROP DATABASE` ou `DELETE` sem cláusula `WHERE`. +**Padrão:** Instrui Claude a confirmar antes de executar SQL contendo `DROP TABLE`, `DROP DATABASE` ou `DELETE` sem uma cláusula `WHERE`. Sem parâmetros. @@ -581,7 +581,7 @@ Sem parâmetros. ### `warn-schema-alteration` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui o Claude a confirmar antes de executar instruções `ALTER TABLE`. +**Padrão:** Instrui Claude a confirmar antes de executar instruções `ALTER TABLE`. Sem parâmetros. @@ -594,7 +594,7 @@ Fornece contexto extra aos agentes antes de operações potencialmente arriscada ### `warn-large-file-write` **Evento:** PreToolUse (Write) -**Padrão:** Instrui o Claude a confirmar antes de escrever arquivos maiores que 1024 KB. +**Padrão:** Instrui Claude a confirmar antes de gravar arquivos maiores que 1024 KB. **Parâmetros:** @@ -615,7 +615,7 @@ Fornece contexto extra aos agentes antes de operações potencialmente arriscada ``` -O handler de hook impõe um limite de 1 MB de stdin em payloads. Para testar esta política com conteúdo pequeno, defina `thresholdKb` com um valor bem abaixo de 1024. +O manipulador de hook impõe um limite de 1 MB de stdin nos payloads. Para testar esta política com conteúdo pequeno, defina `thresholdKb` com um valor bem abaixo de 1024. --- @@ -623,7 +623,7 @@ O handler de hook impõe um limite de 1 MB de stdin em payloads. Para testar est ### `warn-package-publish` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui o Claude a confirmar antes de executar `npm publish`. +**Padrão:** Instrui Claude a confirmar antes de executar `npm publish`. Sem parâmetros. @@ -632,7 +632,7 @@ Sem parâmetros. ### `warn-background-process` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui o Claude a ter cuidado ao iniciar processos em segundo plano via `nohup`, `&`, `disown` ou `screen`. +**Padrão:** Instrui Claude a ter cuidado ao iniciar processos em segundo plano via `nohup`, `&`, `disown` ou `screen`. Sem parâmetros. @@ -641,7 +641,7 @@ Sem parâmetros. ### `warn-global-package-install` **Evento:** PreToolUse (Bash) -**Padrão:** Instrui o Claude a confirmar antes de executar `npm install -g`, `yarn global add` ou `pip install` sem um ambiente virtual. +**Padrão:** Instrui Claude a confirmar antes de executar `npm install -g`, `yarn global add` ou `pip install` sem um ambiente virtual. Sem parâmetros. @@ -649,19 +649,19 @@ Sem parâmetros. ## Gerenciadores de pacotes -Define quais gerenciadores de pacotes o agente tem permissão de usar. +Define quais gerenciadores de pacotes o agente pode 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 o 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 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 vazia, 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 vazio, a política não faz nada. | +| `blocked` | string[] | `[]` | Nomes adicionais de gerenciadores a bloquear 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 que não estão nesta lista. @@ -679,33 +679,33 @@ 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 o Claude a usar `uv` ou `bun`. Comandos como `uv pip install flask` são permitidos porque `uv` está na lista de permitidos e é verificado primeiro. +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. --- ## Comportamento de IA -Detecta quando agentes travam ou se comportam de forma inesperada. +Detecta quando os agentes ficam presos ou se comportam de forma inesperada. ### `warn-repeated-tool-calls` **Evento:** PreToolUse (todas as ferramentas) -**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. +**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. Sem parâmetros. --- -## Workflow +## Fluxo de trabalho -Impõe um workflow disciplinado de fim de sessão. Essas políticas são acionadas no evento **Stop** e negam ao Claude 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 (a negação causa curto-circuito). +Aplica um fluxo de trabalho disciplinado ao final da sessão. Essas políticas são acionadas no evento **Stop** e impedem Claude de parar até que cada condição seja atendida. Elas seguem uma cadeia de dependências natural: commit → push → PR → CI. Se uma política negar, as políticas posteriores na cadeia são ignoradas (deny causa curto-circuito). -Todas as políticas de workflow 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. +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. ### `require-commit-before-stop` **Evento:** Stop -**Padrão:** Nega a parada quando há alterações não commitadas (arquivos modificados, em stage 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. @@ -714,7 +714,7 @@ Sem parâmetros. ### `require-push-before-stop` **Evento:** Stop -**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 aberta se nenhum remote estiver configurado. +**Padrão:** Nega a parada quando há commits não enviados por push 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 abertamente se nenhum remote estiver configurado. **Parâmetros:** @@ -739,14 +739,14 @@ Sem parâmetros. ### `require-pr-before-stop` **Evento:** Stop -**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`). +**Padrão:** Nega a parada quando não existe nenhum pull request para o branch atual, ou quando o PR existente está fechado sem merge. Instrui 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 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 escopo `repo` para acesso de leitura a -pull requests. Se `gh` não estiver instalado ou autenticado, a política falha aberta e informa o motivo ao Claude. +pull requests. Se `gh` não estiver instalado ou autenticado, a política falha abertamente e reporta o motivo ao Claude. --- @@ -754,23 +754,23 @@ 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 o branch atual não pode ser mesclado de forma limpa no branch base. A política primeiro confirma que existe um PR `OPEN` no GitHub para o branch — sem um, não há destino de merge a impor, então toda a política faz curto-circuito para permitir. 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 limpo no branch base. A política primeiro confirma se há um PR `OPEN` no GitHub para o branch — sem um, não há destino de merge a verificar, então toda a política causa 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 negação lista os arquivos com conflito para que o Claude saiba exatamente o que resolver. -2. **GitHub** — reutiliza o resultado de `gh pr view --json mergeable,state` já buscado na pré-verificação. Detecta conflitos que um `origin/` local desatualizado poderia perder (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 o 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 lista os arquivos em conflito 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 enviou um PR conflitante para `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 previne falsos negativos enquanto o GitHub recalcula. -Ignora completamente (permite) quando: `gh` não está instalado, não existe PR 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 aberta quando `origin/` está ausente localmente ou quando não há commits à frente da base — essas situações de fallback da Camada 1 ainda consultam a mesclabilidade do PR em cache antes de permitir. +Ignora completamente (permite) quando: `gh` não está instalado, não existe PR 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 abertamente quando `origin/` está ausente localmente ou quando não há commits à frente da base — esses fallbacks da Camada 1 ainda consultam a mesclabilidade do PR em cache antes de permitir. **Parâmetros:** | Parâmetro | Tipo | Padrão | Descrição | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Branch base para verificar conflitos. | +| `baseBranch` | `string` | `"main"` | Branch base contra o qual 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 -faz curto-circuito para permitir. Execute `gh auth login` com um token de acesso pessoal que tenha +causa curto-circuito para allow. Execute `gh auth login` com um token de acesso pessoal que tenha escopo `repo` para acesso de leitura a pull requests. @@ -779,14 +779,14 @@ 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 no branch atual. Verifica tanto as execuções de workflow do GitHub Actions quanto as verificações de bots de terceiros (ex.: CodeRabbit, SonarCloud, Codecov). Trata conclusões `skipped` e `cancelled` como sucesso. Retorna uma mensagem informativa quando todas as verificações passam. +**Padrão:** Nega a parada quando verificações de CI estão falhando ou ainda em execução no branch atual. Verifica tanto as execuções de workflow do GitHub Actions quanto as verificações de bots de terceiros (ex.: CodeRabbit, SonarCloud, Codecov). Trata conclusões `skipped` e `cancelled` como sucesso. Retorna uma mensagem informativa quando todas as verificações passam. Sem parâmetros. 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 escopo `repo` para acesso de leitura às -execuções de workflow do Actions e à API de Checks. Se `gh` não estiver instalado ou autenticado, a política falha aberta e informa o motivo ao Claude. +Execute `gh auth login` com um token de acesso pessoal 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 reporta o motivo ao Claude. --- @@ -795,7 +795,7 @@ execuções de workflow do Actions e à API de Checks. Se `gh` não estiver inst ## Desabilitando políticas individuais -Remova uma política específica de `enabledPolicies` na sua configuração, ou desative-a na aba Políticas do dashboard. +Remova uma política específica de `enabledPolicies` na sua configuração, ou desative-a na aba Políticas do painel. ```json { @@ -806,4 +806,4 @@ Remova uma política específica de `enabledPolicies` na sua configuração, ou } ``` -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 +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 diff --git a/docs/pt-br/configuration.mdx b/docs/pt-br/configuration.mdx index d5a99075..9a5bd1a0 100644 --- a/docs/pt-br/configuration.mdx +++ b/docs/pt-br/configuration.mdx @@ -4,7 +4,7 @@ description: "Formato do arquivo de configuração, sistema de três escopos e r icon: gear --- -failproofai usa arquivos de configuração JSON para controlar quais políticas estão ativas, como elas se comportam e de onde as políticas personalizadas são carregadas. A configuração foi projetada para ser fácil de compartilhar com sua equipe — faça commit no repositório e todos os desenvolvedores terão a mesma rede de segurança para agentes. +O failproofai utiliza 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 facilmente compartilhada com seu time — faça commit no seu repositório e todos os desenvolvedores terão a mesma rede de segurança para o agente. --- @@ -12,17 +12,17 @@ failproofai usa arquivos de configuração JSON para controlar quais políticas Existem três escopos de configuração, avaliados em ordem de prioridade: -| Escopo | Caminho do arquivo | Propósito | -|--------|-------------------|-----------| -| **project** | `.failproofai/policies-config.json` | Configurações por repositório, versionadas no controle de versão | +| Escopo | Caminho do arquivo | Finalidade | +|--------|-------------------|------------| +| **project** | `.failproofai/policies-config.json` | Configurações por repositório, commitadas no controle de versão | | **local** | `.failproofai/policies-config.local.json` | Substituições pessoais por repositório, ignoradas pelo git | -| **global** | `~/.failproofai/policies-config.json` | Padrões do usuário para todos os projetos | +| **global** | `~/.failproofai/policies-config.json` | Padrões do usuário aplicados a todos os projetos | -Quando failproofai recebe um evento de hook, ele carrega e mescla os três arquivos que existem para o diretório de trabalho atual. +Quando o failproofai recebe um evento de hook, ele carrega e mescla os três arquivos que existem para o diretório de trabalho atual. ### Regras de mesclagem -**`enabledPolicies`** — a união dos três escopos. Uma política habilitada em qualquer nível fica ativa. +**`enabledPolicies`** — união dos três escopos. Uma política habilitada em qualquer nível fica ativa. ```text project: ["block-sudo"] @@ -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 os parâmetros para uma determinada política ganha por completo. Não há mesclagem profunda dos valores dentro dos parâmetros de uma política. +**`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. ```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 @@ -49,9 +49,9 @@ global: block-sudo → { allowPatterns: ["sudo systemctl status"] } resolved: { allowPatterns: ["sudo systemctl status"] } ← cai para o global ``` -**`customPoliciesPath`** — o primeiro escopo que o define vence. +**`customPoliciesPath`** — o primeiro escopo que o definir vence. -**`llm`** — o primeiro escopo que o define vence. +**`llm`** — o primeiro escopo que o definir vence. --- @@ -104,7 +104,7 @@ Tipo: `string[]` Lista de nomes de políticas a habilitar. Os nomes devem corresponder exatamente aos identificadores de política exibidos por `failproofai policies`. Consulte [Políticas Integradas](/pt-br/built-in-policies) para a lista completa. -Políticas que não estão em `enabledPolicies` ficam inativas, mesmo que tenham entradas em `policyParams`. +Políticas que não estão em `enabledPolicies` ficam inativas, mesmo que possuam entradas em `policyParams`. ### `policyParams` @@ -112,15 +112,15 @@ 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 tem parâmetros, mas você não os especifica, os valores padrão 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 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. -Chaves desconhecidas dentro do bloco de parâmetros de uma política são silenciosamente ignoradas no momento da execução do hook, mas sinalizadas como avisos ao executar `failproofai policies`. +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 ao executar `failproofai policies`. #### `hint` (transversal) Tipo: `string` (opcional) -Uma mensagem adicionada ao motivo quando uma política retorna `deny` ou `instruct`. Use-a para fornecer orientações acionáveis ao Claude sem modificar a política em si. +Uma mensagem adicionada ao motivo quando uma política retorna `deny` ou `instruct`. Use para fornecer orientações acionáveis ao Claude sem modificar a política em si. Funciona com qualquer tipo de política — integrada, personalizada (`custom/`), convenção de projeto (`.failproofai-project/`) ou convenção de usuário (`.failproofai-user/`). @@ -143,30 +143,30 @@ 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."* -Valores que não são string e strings vazias são silenciosamente ignorados. Se `hint` não estiver definido, o comportamento não é alterado (compatível com versões anteriores). +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. Isso é 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. Este valor é definido 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. ### Políticas baseadas em convenção -Além do `customPoliciesPath` explícito, failproofai descobre e carrega automaticamente arquivos de política dos diretórios `.failproofai/policies/`: +Além do `customPoliciesPath` explícito, o 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, aplicado a todos os projetos | +| Projeto | `.failproofai/policies/` | Compartilhado com o time via controle de versão | +| Usuário | `~/.failproofai/policies/` | Pessoal, aplica-se a todos os projetos | **Correspondência de arquivos:** Apenas arquivos que correspondem a `*policies.{js,mjs,ts}` são carregados (ex.: `security-policies.mjs`, `workflow-policies.js`). Outros arquivos no diretório são ignorados. -**Sem configuração necessária:** Políticas por convenção não requerem entradas em `policies-config.json`. Basta adicionar os arquivos ao diretório e eles serão detectados no próximo evento de hook. +**Sem configuração necessária:** As políticas de 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. -**Carregamento por união:** Tanto os diretórios de convenção do projeto quanto os do usuário são verificados. Todos os arquivos correspondentes de ambos os níveis são carregados (ao contrário de `customPoliciesPath`, que usa o critério de primeiro escopo que vence). +**Carregamento por união:** Tanto o diretório de convenção do projeto quanto o do usuário são verificados. Todos os arquivos correspondentes de ambos os níveis são carregados (diferente de `customPoliciesPath`, que usa o princípio do primeiro escopo que vencer). Consulte [Políticas Personalizadas](/pt-br/custom-policies) para mais detalhes e exemplos. @@ -189,34 +189,42 @@ 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 sua CLI de agente (os pontos de entrada do hook), enquanto `policies-config.json` é o arquivo que você gerencia diretamente. Os dois são separados: +Os comandos `policies --install` e `policies --uninstall` escrevem no arquivo de configurações de hook da sua CLI de agente (os pontos de entrada do hook), enquanto `policies-config.json` é o arquivo que você gerencia diretamente. Os dois são separados: - **Configurações da CLI do agente** — 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 tem 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 e `timeoutSec`; o arquivo possui um marcador de nível superior `version: 1`. O suporte ao Copilot CLI está em **beta** enquanto verificamos o esquema de registro `events.jsonl` (que a documentação pública não especifica) em mais sessões reais. -- **`policies-config.json`** — instrui failproofai sobre quais políticas avaliar e com quais parâmetros (compartilhado entre todas as CLIs de agente) + - **OpenAI Codex**: `~/.codex/hooks.json` (usuário), `/.codex/hooks.json` (projeto) — o Codex não possui escopo `local` + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (usuário), `/.github/hooks/failproofai.json` (projeto) — o Copilot não possui escopo `local`. As entradas de hook utilizam os campos de comando `bash`/`powershell` com chave de SO do Copilot e `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` (que a documentação pública não especifica) em mais sessões do mundo real. + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (usuário), `/.cursor/hooks.json` (projeto) — o Cursor não possui escopo `local`. As entradas de hook utilizam o formato `{type, command, timeout}` no estilo do Claude (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 contém 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çõ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) em 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 possui escopo `local`. Diferente das outras quatro CLIs, o OpenCode **não possui sistema de hook por comando externo**: ele carrega plugins JS/TS em processo, explicitamente registrados via array `plugin: []` no `opencode.json` (a descoberta automática de `.opencode/plugins/` **não** é como os plugins são carregados no opencode v1.14.33). A instalação coloca um pequeno shim de plugin gerado que chama o binário do failproofai como subprocesso e traduz a resposta JSON no formato Claude do binário de volta para a semântica de plugin (`throw new Error()` para deny, `client.session.prompt(...)` para instruct, sem operação para allow). 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 em diferentes versões e em 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 possui 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 se inscreve nos eventos `tool_call` / `user_bash` / `input` / `session_start` do Pi e executa `failproofai --hook --cli pi` como subprocesso; o handler canonicaliza underscore_lower_snake_case → PascalCase via `PI_EVENT_MAP`, de modo que as políticas integradas existentes disparam sem alterações. 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 possui escopo `local` (ele documenta um escopo `system` em `/etc/gemini-cli/settings.json` que o failproofai não expõe). As entradas de hook utilizam o formato `{type, command, timeout}` do Claude encapsulado no esquema de matcher `{matcher, hooks: [...]}` do Gemini, com `matcher: "*"` por padrão. Os eventos estão em PascalCase (`SessionStart`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `BeforeToolSelection`, `BeforeTool`, `AfterTool`, `PreCompress`, `Notification`, `SessionEnd`); o handler mapeia para os nomes canônicos do Claude via `GEMINI_EVENT_MAP`. Os nomes de ferramentas estão em snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — o handler canonicaliza via `GEMINI_TOOL_MAP`, de modo que as políticas integradas existentes disparam sem alterações. 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 force-retry. O suporte ao Gemini CLI está em **beta** enquanto ampliamos a cobertura no 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 todas as CLIs de agente) -Passe `--cli claude|codex|copilot` para selecionar um agente específico (separado por espaço ou repetido para qualquer subconjunto): +Passe `--cli claude|codex|copilot|cursor|opencode|pi|gemini` para selecionar um agente específico (separados por espaço ou repetidos para qualquer subconjunto): ```bash failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project -failproofai policies --install --cli claude codex copilot +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 claude codex copilot cursor opencode pi gemini ``` -Quando `--cli` é omitido, `failproofai` detecta quais CLIs de agente estão instaladas (`which claude` / `which codex` / `which copilot`): +Quando `--cli` é omitido, o `failproofai` detecta quais CLIs de agente estão instaladas (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): - **Uma CLI detectada** — seleciona automaticamente essa CLI sem solicitar confirmação. -- **Múltiplas CLIs detectadas** em um terminal interativo — exibe um prompt de seleção única com teclas de seta: quando duas CLIs estão presentes, as opções são `Both`, ` only`, ` only`; com três CLIs, a primeira opção se torna `All` (↑↓ para mover, Enter para selecionar, ^C para sair). -- **Múltiplas CLIs detectadas** em uma execução não interativa (CI, sem TTY) — instala para todas as CLIs detectadas sem solicitar confirmação. -- **Nenhuma detectada** — usa `claude` como fallback, com um aviso de que nenhum binário de agente foi encontrado no PATH; o comando de hook ainda é escrito e ativará assim que você instalar um. +- **Múltiplas CLIs detectadas** em um terminal interativo — exibe um prompt de seleção por teclas de seta, agrupado em uma seção `Detected (N)` (com uma linha agregada `Install for all N detected` + cada CLI detectada individualmente) e uma seção `Not installed (M) · install hooks ahead of time` listando cada CLI suportada não detectada como opção de instalação antecipada (↑↓ para mover, Enter para selecionar, ^C para sair). O fluxo de desinstalação exibe apenas a seção de detectadas. +- **Múltiplas CLIs detectadas** em execução não interativa (CI, sem TTY) — instala para todas as CLIs detectadas sem solicitar confirmação. +- **Nenhuma detectada** — usa `claude` como padrão, com um aviso de que nenhum binário de agente foi encontrado no PATH; o comando de hook ainda é escrito e será ativado assim que você instalar um. Você pode editar `policies-config.json` diretamente a qualquer momento; as alterações entram em vigor imediatamente no próximo evento de hook, sem necessidade de reinicialização. --- -## Exemplo: configuração no nível do projeto com padrões da equipe +## Exemplo: configuração em nível de projeto com padrões do time Faça commit de `.failproofai/policies-config.json` no seu repositório: @@ -237,4 +245,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` (ignorado pelo git) para substituições pessoais sem afetar os colegas de time. \ No newline at end of file diff --git a/docs/pt-br/dashboard.mdx b/docs/pt-br/dashboard.mdx index d340e464..1e4ad296 100644 --- a/docs/pt-br/dashboard.mdx +++ b/docs/pt-br/dashboard.mdx @@ -24,11 +24,11 @@ O dashboard lê diretamente do sistema de arquivos — suas pastas de projetos d ### Projetos -Lista todos os projetos Claude Code, OpenAI Codex e GitHub Copilot 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 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`. Um projeto que foi usado por múltiplos CLIs é renderizado como uma única linha com todos os badges correspondentes. Use o menu suspenso **CLI** acima da tabela para filtrar por um agente CLI específico; a URL preserva sua seleção como `?cli=claude|codex|copilot`. +Lista todos os projetos do 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 do Claude são descobertos a partir de `~/.claude/projects/` (ou do caminho definido por `CLAUDE_PROJECTS_PATH`); os projetos do Codex são descobertos escaneando todas as transcrições em `~/.codex/sessions///
/*.jsonl` e agrupando pelo `cwd` registrado no primeiro registro de cada sessão; os projetos do Copilot CLI são descobertos escaneando cada `~/.copilot/session-state//workspace.yaml` (configurável via `COPILOT_HOME`) e agrupando pelo campo `cwd`; os projetos do Cursor Agent são descobertos escaneando metadados por sessão em `~/.cursor/agent-sessions//` (configurável via `CURSOR_HOME`, com `conversations/` e `sessions/` verificados como alternativas) para um escalar `cwd` em `meta.json` / `session.json` / `workspace.yaml`; os projetos do OpenCode são descobertos consultando seu banco de dados 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 do Pi são descobertos escaneando transcrições JSONL por sessão em `~/.pi/agent/sessions//_.jsonl` (configurável via `PI_SESSIONS_DIR`) e extraindo o `cwd` do primeiro registro de cada sessão; os projetos do 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` adjacente. Um projeto que foi usado por vários 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`. Cada projeto exibe: - Nome do projeto (derivado do caminho da pasta) -- Um badge de CLI — `Claude Code` (laranja), `OpenAI Codex` (roxo) e/ou `GitHub Copilot` (azul) +- Um badge de CLI — `Claude Code` (laranja), `OpenAI Codex` (roxo), `GitHub Copilot` (azul), `Cursor Agent` (esmeralda), `OpenCode` (âmbar), `Pi` (rosa) e/ou `Gemini CLI` (celeste) - Data da atividade mais recente da sessão Clique em um projeto para ver suas sessões. @@ -47,32 +47,32 @@ Clique em uma sessão para abrir o visualizador de sessão. ### Visualizador de sessão -O visualizador de sessão responde à pergunta fundamental para agentes autônomos: o que o agente fez e ele se manteve no caminho certo? Um badge de CLI ao lado do cabeçalho indica se a sessão é uma transcrição do Claude Code ou do OpenAI Codex. Ele exibe uma linha do tempo de tudo o que aconteceu em uma sessão: +O visualizador de sessão responde à pergunta principal sobre agentes autônomos: o que o agente fez e ele se manteve no caminho certo? Um badge de CLI ao lado do cabeçalho indica se a sessão é uma transcrição do Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi ou Gemini CLI. 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 mostra a duração da sessão, total de chamadas de ferramentas e um resumo das decisões de hooks (contagens de allow / deny / instruct). +A barra de estatísticas no topo exibe a duração da sessão, o total de chamadas de ferramentas e um resumo das decisões de hooks (contagens de allow / deny / instruct). -Você pode exportar a sessão como um arquivo ZIP ou JSONL usando o botão de download. +Clique no botão **Download Logs** para exportar a sessão. Para sessões do Claude Code, Codex, Copilot, Cursor, Pi e Gemini, você obtém a transcrição JSONL original em disco byte a byte; para o OpenCode (cujas sessões ficam no SQLite, não em disco), você obtém um documento JSON espelhando as tabelas subjacentes `session` / `messages` / `parts`. ### Políticas Uma página com duas abas para gerenciar políticas e revisar atividades. - - - Ative ou desative políticas individualmente com um único clique (grava em `~/.failproofai/policies-config.json`) + + - Ative ou desative políticas individuais com um único clique (grava em `~/.failproofai/policies-config.json`) - Expanda uma política para configurar seus parâmetros (para políticas que suportam `policyParams`) - Instale ou remova hooks para um determinado escopo - Defina um caminho personalizado para o arquivo de políticas - - - Histórico completo paginado 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)_), 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), 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`) e renderiza o badge de CLI correspondente no cabeçalho + + - Histórico paginado completo de todos os eventos de hook que foram acionados 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, celeste = Gemini CLI), nome da ferramenta, ID de sessão e o motivo das decisões de deny/instruct + - Clique em um ID de sessão para abrir sua transcrição — o visualizador detecta automaticamente qual CLI acionou o hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`) e renderiza o badge do CLI correspondente no cabeçalho @@ -80,13 +80,13 @@ Uma página com duas abas para gerenciar políticas e revisar atividades. ## Atualização automática -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 surgem. Essencial para monitorar sessões de agentes autônomos de longa duração. +O dashboard possui um botão de alternância de atualização automática na navegação superior. Quando ativado, a página atual é atualizada periodicamente para exibir novas sessões e atividades de políticas à 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` como uma lista separada por vírgulas com os nomes das páginas: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -112,15 +112,15 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Acessando a partir de um host diferente de localhost +## Acessando de um host que não seja localhost -Ao executar o dashboard em **modo de desenvolvimento** (`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: +Ao executar o dashboard no **modo dev** (`npm run dev`) e acessá-lo de um hostname diferente de `localhost` — por exemplo, um domínio personalizado, um IP remoto ou uma URL com túnel — você pode ver um aviso como: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Isso é o Next.js bloqueando o acesso cross-origin ao seu websocket HMR (hot module reload), que é uma funcionalidade exclusiva do modo de desenvolvimento. Para permitir seu host, use a flag `--allowed-origins`: +Isso ocorre porque o Next.js está bloqueando o acesso de origem cruzada ao seu websocket de 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 @@ -132,12 +132,12 @@ Para múltiplos hosts ou IPs, passe uma lista separada por vírgulas: npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -Você também pode definir a variável de ambiente `FAILPROOFAI_ALLOWED_DEV_ORIGINS` como alternativa: +Você também pode definir a variável de ambiente `FAILPROOFAI_ALLOWED_DEV_ORIGINS`: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Isso se aplica apenas ao modo de desenvolvimento. Ao executar `failproofai` (modo de produção), não há websocket HMR nem problema de recurso de desenvolvimento cross-origin. +Isso se aplica apenas ao modo dev. Ao executar `failproofai` (modo de produção), não há websocket de HMR nem problema de recursos dev de origem cruzada. \ No newline at end of file diff --git a/docs/pt-br/getting-started.mdx b/docs/pt-br/getting-started.mdx index 3221c200..f6ecc138 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 com confiabilidade" +description: "Instale o failproofai, ative as políticas e deixe seus agentes rodando com confiabilidade" icon: rocket --- @@ -37,14 +37,18 @@ bun add -g failproofai failproofai policies --install ``` - Isso grava entradas de hook nos CLIs de agente instalados (o `~/.claude/settings.json` do Claude Code, o `~/.codex/hooks.json` do OpenAI Codex ou o `~/.copilot/hooks/failproofai.json` do GitHub Copilot CLI). Quando mais de um estiver presente, você será solicitado a escolher; use `--cli claude codex copilot` (qualquer subconjunto) para pular a seleção. + Isso insere 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` de `~/.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 essa etapa. - O suporte ao GitHub Copilot CLI está em **beta** — instale com `--cli copilot`. + 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`. ```bash failproofai policies --install --scope project failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project + 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 block-sudo block-rm-rf sanitize-api-keys ``` @@ -53,14 +57,14 @@ bun add -g failproofai failproofai policies ``` - Exibe todas as políticas, se estão ativas e quaisquer parâmetros configurados. + Exibe todas as políticas, se estão ativas e quais parâmetros foram configurados. ```bash failproofai ``` - Abre um painel local em `http://localhost:8020` onde você pode navegar por sessões, inspecionar chamadas de ferramentas e gerenciar políticas. + 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. @@ -71,7 +75,7 @@ bun add -g failproofai ## Como as políticas funcionam -Toda vez que um agente executa uma ferramenta, o Claude Code chama o failproofai como subprocesso: +Toda vez que um agente executa uma ferramenta, o Claude Code chama o failproofai como um subprocesso: ```text Claude Code → failproofai --hook PreToolUse → reads stdin JSON @@ -86,14 +90,14 @@ Cada política retorna uma de três decisões: - **instruct** - contexto adicional é inserido no prompt do agente -As políticas são executadas no seu processo local. Nenhum dado é enviado a um serviço remoto. +As políticas são executadas no seu processo local. Nada é enviado para um serviço remoto. --- -## Configurar políticas de equipe com políticas baseadas em convenção +## Configure 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 serão carregados automaticamente — sem flags, sem alterações de configuração, sem comandos de instalação. +A forma 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 serão carregados automaticamente — sem flags, sem mudanças de configuração, sem comandos de instalação. @@ -127,31 +131,31 @@ 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 recebe 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. Nenhuma configuração por desenvolvedor é necessária. -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 sua 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. --- ## Armazenamento de dados -Toda a configuração e os logs ficam na sua máquina: +Todas as configurações e logs ficam na sua máquina: | Caminho | O que armazena | |---------|----------------| | `~/.failproofai/policies-config.json` | Configuração global de políticas | | `~/.failproofai/hook-activity.jsonl` | Histórico de execução de hooks | -| `~/.failproofai/hook.log` | Log de depuração para erros de hooks personalizados | +| `~/.failproofai/hook.log` | Log de depuração para erros em hooks personalizados | | `.failproofai/policies-config.json` | Configuração por projeto (commitada) | | `.failproofai/policies-config.local.json` | Substituições pessoais (ignoradas pelo git) | @@ -172,18 +176,18 @@ Remove as entradas de hook do `~/.claude/settings.json`. Os arquivos de configur - Escopos e formato do arquivo de configuração + Escopos e formato dos arquivos de configuração - Todas as 26 políticas com parâmetros + Todas as 26 políticas com seus parâmetros Escreva suas próprias políticas em JavaScript - + Monitore sessões e revise a atividade das políticas diff --git a/docs/ru/architecture.mdx b/docs/ru/architecture.mdx index 71d3cd16..ded1bd7e 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. **Hook handler** — быстрый CLI подпроцесс, который Claude Code вызывает при каждом вызове инструмента агента. Оценивает политики и возвращает решение. -2. **Agent Monitor (Dashboard)** — веб-приложение Next.js для мониторинга сессий агента и управления политиками. +1. **Обработчик хука** — быстрый подпроцесс CLI, который Claude Code вызывает при каждом вызове инструмента агента. Оценивает политики и возвращает решение. +2. **Монитор агента (Панель управления)** — веб-приложение Next.js для отслеживания сеансов агента и управления политиками. -Обе подсистемы совместно используют файлы конфигурации в `~/.failproofai/` и в директории проекта `.failproofai/`, но работают как отдельные процессы и взаимодействуют только через файловую систему. +Обе подсистемы используют общие файлы конфигурации в `~/.failproofai/` и директории `.failproofai/` проекта, но работают как отдельные процессы и взаимодействуют только через файловую систему. --- -## Hook handler +## Обработчик хука ### Интеграция с Claude Code -Когда вы запускаете `failproofai policies --install`, он записывает записи подобно этой в `~/.claude/settings.json`: +Когда вы запускаете `failproofai policies --install`, он добавляет записи вроде этой в `~/.claude/settings.json`: ```json { @@ -61,13 +61,13 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как } ``` -Для событий `PostToolUse` полезная нагрузка также содержит `tool_result` с результатом работы инструмента. +Для событий `PostToolUse` полезная нагрузка также содержит `tool_result` с выходом инструмента. -Обработчик устанавливает лимит stdin в 1 МБ. Полезные нагрузки, превышающие этот лимит, отбрасываются и все политики неявно разрешают операцию. +Обработчик предусматривает ограничение stdin в 1 МБ. Полезные нагрузки, превышающие этот лимит, отбрасываются и все политики неявно разрешают операцию. ### Формат ответа -**Deny (PreToolUse):** +**Запрет (PreToolUse):** ```json { "hookSpecificOutput": { @@ -77,7 +77,7 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как } ``` -**Deny (PostToolUse):** +**Запрет (PostToolUse):** ```json { "hookSpecificOutput": { @@ -86,7 +86,7 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как } ``` -**Instruct (любое событие, кроме Stop):** +**Инструкция (любое событие кроме Stop):** ```json { "hookSpecificOutput": { @@ -95,20 +95,20 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как } ``` -**Instruct для события Stop:** +**Инструкция события Stop:** - Код выхода: `2` -- Причина выводится в stderr (не в stdout) +- Причина записывается в stderr (не stdout) -**Allow:** +**Разрешение:** - Код выхода: `0` - Пустой stdout -**Allow с сообщением:** +**Разрешение с сообщением:** -`allow(message)` позволяет политике отправлять информационный контекст обратно в Claude даже когда операция разрешена. Обработчик хуков записывает следующий JSON в **stdout** (не в файл конфига — это ответ обработчика для Claude Code, как и ответы deny и instruct выше): +`allow(message)` позволяет политике отправить информационный контекст обратно Claude даже если операция разрешена. Обработчик хука записывает следующий JSON в **stdout** (не в файл конфигурации — это ответ обработчика на Claude Code, как и ответы deny и instruct выше): ```json -// Написано в stdout процессом обработчика хуков +// Записывается в stdout процессом обработчика хука { "hookSpecificOutput": { "additionalContext": "All CI checks passed on branch 'feat/my-feature'." @@ -116,28 +116,28 @@ Claude Code затем вызывает `failproofai --hook PreToolUse` как } ``` - Код выхода: `0` (операция разрешена) -- Когда несколько политик возвращают `allow` с сообщением, их сообщения объединяются с переводами строк в один string `additionalContext` -- Если ни одна политика не предоставляет сообщение, stdout пуст (как и раньше) +- Когда несколько политик возвращают `allow` с сообщением, их сообщения объединяются с переводами строк в единую строку `additionalContext` +- Если ни одна политика не предоставляет сообщение, stdout пуст (как раньше) ### Конвейер обработки `src/hooks/handler.ts` реализует полный конвейер: ```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 +JSON на stdin + → разбор полезной нагрузки (макс. 1 МБ) + → извлечение метаданных сеанса (session_id, cwd, tool_name, tool_input и т.д.) + → readMergedHooksConfig(cwd) ← объединяет конфигурацию проекта + локальную + глобальную + → регистрация включённых встроенных политик с разрешёнными параметрами + → загрузка пользовательских политик из customPoliciesPath (если установлено) + → регистрация пользовательских политик в реестр политик + → оценка всех политик (встроенные сначала, затем пользовательские) + → первый запрет прерывает процесс + → решения instruct накапливаются + → сообщения allow накапливаются + → запись JSON-решения в stdout + → сохранение события в ~/.failproofai/hook-activity.jsonl + → выход ``` Весь процесс выполняется менее чем за 100 мс для типичных полезных нагрузок без вызовов LLM. @@ -146,21 +146,21 @@ stdin JSON ## Загрузка конфигурации -`src/hooks/hooks-config.ts` реализует загрузку конфигурации в трёх областях. +`src/hooks/hooks-config.ts` реализует трёхуровневую загрузку конфигурации. ```text -[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) +[1] {cwd}/.failproofai/policies-config.json ← проект (наивысший приоритет) +[2] {cwd}/.failproofai/policies-config.local.json ← локальная +[3] ~/.failproofai/policies-config.json ← глобальная (наименьший приоритет) ``` Логика объединения: - `enabledPolicies` — дедублицированное объединение всех трёх файлов -- `policyParams` — по ключу политики, первый файл, который его определяет, получает полный приоритет -- `customPoliciesPath` — первый файл, который его определяет, получает приоритет -- `llm` — первый файл, который его определяет, получает приоритет +- `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`, вывести ответ deny. -- Если были собраны какие-либо `instruct`, вывести один ответ instruct со всеми объединёнными сообщениями. -- В противном случае вывести ответ allow (пустой 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` без проверки на 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__"; @@ -223,22 +223,22 @@ 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` и загрузчик возвращает пустой массив. Встроенные политики не затрагиваются. +При любой ошибке (файл не найден, синтаксическая ошибка, ошибка импорта) ошибка логируется в `~/.failproofai/hook.log` и загрузчик возвращает пустой массив. Встроенные политики не затрагиваются. -Пользовательские политики оцениваются после всех встроенных политик. Пользовательская политика `deny` по-прежнему прерывает дальнейшие пользовательские политики (но к тому моменту все встроенные уже выполнены). +Пользовательские политики оцениваются после всех встроенных политик. `deny` пользовательской политики всё ещё прерывает дальнейшие пользовательские политики (но все встроенные к этому моменту уже выполнены). --- @@ -259,44 +259,44 @@ export function clearCustomHooks(): void { ... } // used in tests } ``` -По одной строке на каждую политику, которая приняла решение, отличное от allow. Решения allow не регистрируются (чтобы держать файл в разумном размере). +По одной строке на политику, которая приняла решение не-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 ← Export session as ZIP/JSONL + download/[project]/[session]/route.ts ← Экспорт сеанса (JSONL или JSON) ``` **Поток данных:** -- Компоненты страниц вызывают `lib/projects.ts` и `lib/log-entries.ts` для чтения данных проекта/сессии непосредственно из файловой системы (без слоя API для чтения). -- Страница Policies использует Server Actions для всех изменений (переключение, обновление параметров, установка/удаление). -- Просмотрщик сессии анализирует формат JSONL транскрипта Claude и отображает временную шкалу сообщений и вызовов инструментов. +- Компоненты страниц вызывают `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 для страниц чтения — быстрее начальная загрузка, нет клиентского бандла для получения данных. +- Client components только где нужна интерактивность (переключение политик, поиск по активности, просмотр журнала). --- @@ -305,29 +305,29 @@ app/ ```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 # 26 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 # 26 определений политик +│ ├── 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 / 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 # разбор формата JSONL-транскрипта Claude +│ ├── 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 context (тема, авто-обновление, телеметрия) +├── 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 af3142d2..b4520b80 100644 --- a/docs/ru/built-in-policies.mdx +++ b/docs/ru/built-in-policies.mdx @@ -1,10 +1,10 @@ --- title: Встроенные политики -description: "Все 39 встроенных политик, которые перехватывают распространенные режимы отказа агентов" +description: "Все 39 встроенных политик, которые ловят распространённые режимы отказа агента" icon: shield --- -failproofai поставляется с 39 встроенными политиками, которые перехватывают распространенные режимы отказа агентов. Каждая политика срабатывает на определенный тип события hook и имя инструмента. Девятнадцать политик принимают параметры, которые позволяют вам настраивать их поведение без написания кода. Пять политик рабочего процесса обеспечивают выполнение конвейера commit → push → PR → CI перед тем, как Claude остановится. +failproofai поставляется с 39 встроенными политиками, которые ловят распространённые режимы отказа агента. Каждая политика срабатывает на определённый тип события хука и имя инструмента. Девятнадцать политик принимают параметры, позволяющие настроить их поведение без написания кода. Пять политик рабочего процесса обеспечивают выполнение конвейера commit → push → PR → CI до остановки Claude. --- @@ -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-`** — остановить агента от продолжения. +- **`warn-`** — дать агенту дополнительный контекст, чтобы он мог самокорректироваться. +- **`sanitize-`** — удалить чувствительные данные из вывода инструмента до того, как агент их увидит. -### Пространства имен +### Пространства имён -Каждая политика находится в слоте `/`. Встроенные политики принадлежат пространству имен **`exospherehost/`** — например, `exospherehost/sanitize-jwt`. Пространство имен предотвращает конфликты при загрузке пользовательских или сторонних политик с похожими короткими названиями. +Каждая политика находится в слоте `/`. Встроенные политики принадлежат пространству имён **`exospherehost/`** — например, `exospherehost/sanitize-jwt`. Пространство имён предотвращает коллизии при загрузке пользовательских или сторонних политик с похожими короткими названиями. -В вашей конфигурации вы можете ссылаться на встроенную политику либо по ее короткому названию, либо по его полному названию; обе формы разрешаются в одну и ту же политику: +В вашей конфигурации вы можете ссылаться на встроенную политику либо по её короткому названию, либо по полному названию; обе формы разрешаются в одну и ту же политику: ```json { @@ -44,34 +44,33 @@ failproofai поставляется с 39 встроенными политик } ``` -Если имя не содержит `/`, failproofai рассматривает его как принадлежащее пространству имен по умолчанию `exospherehost`. Имена, которые уже содержат `/` (например, `myorg/foo`, `custom/my-hook`), остаются без изменений. - +Если имя не содержит `/`, failproofai рассматривает его как принадлежащее пространству имён по умолчанию `exospherehost`. Имена, которые уже содержат `/` (например `myorg/foo`, `custom/my-hook`), сохраняются как есть. - **`require-`** — заблокировать событие Stop до выполнения условий. --- -Каждая политика поддерживает дополнительное поле `hint` в `policyParams`. Подсказка добавляется к сообщению deny или instruct, которое видит Claude, предоставляя практические рекомендации без изменения кода политики. Работает со встроенными, пользовательскими и условными политиками. Подробности см. в разделе [Конфигурация → hint](/ru/configuration#hint-cross-cutting). +Каждая политика поддерживает необязательное поле `hint` в `policyParams`. Подсказка добавляется к сообщению deny или instruct, которое видит Claude, предоставляя действенное руководство без изменения кода политики. Работает со встроенными, пользовательскими и конвенционными политиками. Подробнее см. [Конфигурация → hint](/ru/configuration#hint-cross-cutting). --- ## Опасные команды -Предотвратите выполнение операций, которые сложно отменить или которые могут повредить хост-систему. +Помешать агентам запускать операции, которые сложно отменить или которые могут повредить хост-систему. ### `block-sudo` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет любую команду `sudo`. +**По умолчанию:** Запрещает любую команду `sudo`. -Блокирует вызовы, содержащие ключевое слово `sudo`. Сопоставление паттернов выполняется на проанализированных токенах команды, а не на исходной строке, чтобы предотвратить обход путем инъекции операторов оболочки. +Блокирует вызовы, содержащие ключевое слово `sudo`. Сопоставление шаблонов производится на разобранных токенах команды, а не на сырой строке, чтобы предотвратить обход через инъекцию оператора оболочки. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Точные префиксы команд, которые разрешены. Каждая запись сопоставляется с проанализированными токенами argv. | +| `allowPatterns` | `string[]` | `[]` | Точные префиксы команд, которые разрешены. Каждая запись сопоставляется с разобранными токенами argv. | **Пример:** @@ -85,10 +84,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 *`). --- @@ -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,31 +120,31 @@ 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` и т. д., не будут нарушены, если вы не включите политику. При включении каждый вызов соответствующего CLI запрещен, если только команда не соответствует записи в `allowPatterns`. +Остановить кодирующие агенты от запуска CLI инфраструктуры или триггеров CI/CD конвейеров. Все политики в этой категории **opt-in** (`defaultEnabled: false`) — агенты, которым законно нужно вызывать `kubectl`, `terraform`, и т.д., не будут прерваны, если вы не включите политику. Когда включена, каждое вызывание совпадающего CLI запрещено, если команда не совпадает с записью в `allowPatterns`. -Грамматика паттерна такая же, как у [`block-sudo`](#block-sudo): токены сопоставляются с проанализированными argv, `*` является подстановочным символом для одного токена, и любая команда, содержащая отдельный оператор оболочки (`&&`, `||`, `|`, `;`) или токен с встроенными метасимволами оболочки, отклоняется перед сопоставлением с белым списком, чтобы предотвратить обход путем инъекции. +Грамматика шаблонов та же, что и в [`block-sudo`](#block-sudo): токены сопоставляются с разобранным argv, `*` — это подстановочный знак для одного токена, и любая команда, содержащая автономный оператор оболочки (`&&`, `||`, `|`, `;`) или токен с встроенными метасимволами оболочки, отклоняется перед сопоставлением с разрешающим списком, чтобы предотвратить обходы инъекции. ### `block-kubectl` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет любой вызов `kubectl`. +**По умолчанию:** Запрещает любой вызов `kubectl`. **Параметры:** @@ -165,14 +164,14 @@ 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). **Параметры:** @@ -197,13 +196,13 @@ failproofai поставляется с 39 встроенными политик ### `block-aws-cli` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет любой вызов CLI `aws`. +**По умолчанию:** Запрещает любой вызов `aws` CLI. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `allowPatterns` | `string[]` | `[]` | Префиксы команд CLI aws, которые разрешены. | +| `allowPatterns` | `string[]` | `[]` | Префиксы команд aws CLI, которые разрешены. | **Пример:** @@ -222,7 +221,7 @@ failproofai поставляется с 39 встроенными политик ### `block-gcloud` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет любой вызов CLI `gcloud` (Google Cloud). +**По умолчанию:** Запрещает любой вызов `gcloud` (Google Cloud) CLI. **Параметры:** @@ -247,7 +246,7 @@ failproofai поставляется с 39 встроенными политик ### `block-az-cli` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет любой вызов CLI `az` (Azure). +**По умолчанию:** Запрещает любой вызов `az` (Azure) CLI. **Параметры:** @@ -272,7 +271,7 @@ failproofai поставляется с 39 встроенными политик ### `block-helm` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет любой вызов `helm`. +**По умолчанию:** Запрещает любой вызов `helm`. **Параметры:** @@ -297,7 +296,7 @@ failproofai поставляется с 39 встроенными политик ### `block-gh-pipeline` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет следующие подкоманды CLI `gh`, которые изменяют состояние или запускают конвейеры: +**По умолчанию:** Запрещает следующие подкоманды `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/.../...` **не** соответствуют этой политике — они обычно требуются для проверок рабочего процесса (включая собственную `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[]` | `[]` | Специфические автоматизированные вызовы для разрешения, хотя они иначе были бы запрещены. | **Пример:** @@ -328,23 +327,23 @@ failproofai поставляется с 39 встроенными политик --- -## Секреты (санитайзеры) +## Секреты (дезинфицирующие средства) -Остановите утечку учетных данных агентов в их контекст или вывод. Политики санитайзеров срабатывают на событиях **PostToolUse**. Когда Claude запускает команду Bash, читает файл или вызывает любой инструмент, эти политики проверяют выходные данные перед их возвратом Claude. Если обнаружен паттерн секрета, политика возвращает решение deny, которое предотвращает передачу выходных данных. +Помешать агентам утечке учётных данных в их контекст или вывод. Политики дезинфицирования срабатывают на события **PostToolUse**. Когда Claude запускает команду Bash, читает файл или вызывает любой инструмент, эти политики проверяют вывод до его возврата Claude. Если обнаружен паттерн секрета, политика возвращает решение deny, которое предотвращает возврат вывода. ### `sanitize-jwt` **Событие:** PostToolUse (все инструменты) -**По умолчанию:** Редактирует JWT токены (три сегмента base64url, разделенные `.`). +**По умолчанию:** Удаляет JWT токены (три сегмента base64url, разделённые `.`). -Параметры отсутствуют. +Нет параметров. --- ### `sanitize-api-keys` **Событие:** PostToolUse (все инструменты) -**По умолчанию:** Редактирует распространенные форматы API ключей: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS access keys (`AKIA`), Stripe keys (`sk_live_`, `sk_test_`) и Google API keys (`AIza`). +**По умолчанию:** Удаляет распространённые форматы ключей API: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`ghp_`), AWS access keys (`AKIA`), Stripe keys (`sk_live_`, `sk_test_`), и Google API keys (`AIza`). **Параметры:** @@ -372,68 +371,68 @@ 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 (все инструменты) -**По умолчанию:** Редактирует заголовки `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`. -Параметры отсутствуют. +Нет параметров. --- ### `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 переходит в подкаталог. +**По умолчанию:** Запрещает чтение файлов вне корня проекта. Граница — это `CLAUDE_PROJECT_DIR` (устанавливается один раз за сеанс Claude Code), с откатом к текущей рабочей директории сеанса, когда переменная не установлена. Использование корня проекта вместо живого `cwd` означает, что граница остаётся стабильной даже после того, как Claude делает `cd` в подпапку. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `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 и ошибки ветвей, которые сложно отменить. +Предотвратить случайные pushes, force-pushes и ошибки в ветвях, которые сложно отменить. ### `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"]` | Названия ветвей, в которые нельзя push напрямую. | **Пример:** @@ -502,7 +501,7 @@ failproofai поставляется с 39 встроенными политик ``` -Чтобы разрешить push во все ветви (фактически отключение этой политики без удаления из `enabledPolicies`), установите `protectedBranches: []`. +Чтобы разрешить push во все ветви (фактически отключить эту политику без её удаления из `enabledPolicies`), установите `protectedBranches: []`. --- @@ -510,22 +509,22 @@ failproofai поставляется с 39 встроенными политик ### `block-work-on-main` **Событие:** PreToolUse (Bash) -**По умолчанию:** Отклоняет переход на ветви `main` или `master` напрямую. +**По умолчанию:** Запрещает `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"]` | Имена ветвей, на которые нельзя переходить напрямую. | +| `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`](/ru/configuration#hint-cross-cutting) для предложения альтернатив: +Нет специфических для политики параметров. Используйте сквозной [`hint`](/ru/configuration#hint-cross-cutting) для предложения альтернатив: ```json { @@ -542,66 +541,66 @@ failproofai поставляется с 39 встроенными политик ### `warn-git-amend` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude действовать осторожно при выполнении `git commit --amend`. Не блокирует команду. +**По умолчанию:** Инструктирует Claude быть осторожным при запуске `git commit --amend`. Не блокирует команду. -Параметры отсутствуют. +Нет параметров. --- ### `warn-git-stash-drop` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude подтвердить перед выполнением `git stash drop`. Не блокирует команду. +**По умолчанию:** Инструктирует Claude подтвердить перед запуском `git stash drop`. Не блокирует команду. -Параметры отсутствуют. +Нет параметров. --- ### `warn-all-files-staged` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude просмотреть то, что оно ставит на сцену при выполнении `git add -A` или `git add .`. Не блокирует команду. +**По умолчанию:** Инструктирует Claude проверить, что он stageing, при запуске `git add -A` или `git add .`. Не блокирует команду. -Параметры отсутствуют. +Нет параметров. --- ## База данных -Перехватите деструктивные SQL операции перед их выполнением на вашей базе данных. +Уловить деструктивные SQL операции до их выполнения против вашей базы данных. ### `warn-destructive-sql` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude подтвердить перед выполнением SQL, содержащего `DROP TABLE`, `DROP DATABASE` или `DELETE` без предложения `WHERE`. +**По умолчанию:** Инструктирует Claude подтвердить перед запуском SQL, содержащего `DROP TABLE`, `DROP DATABASE` или `DELETE` без `WHERE` предложения. -Параметры отсутствуют. +Нет параметров. --- ### `warn-schema-alteration` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude подтвердить перед выполнением инструкций `ALTER TABLE`. +**По умолчанию:** Инструктирует Claude подтвердить перед запуском заявлений `ALTER TABLE`. -Параметры отсутствуют. +Нет параметров. --- ## Предупреждения -Дайте агентам дополнительный контекст перед потенциально рискованными, но неразрушающими операциями. +Дать агентам дополнительный контекст перед потенциально рискованными, но неразрушающими операциями. ### `warn-large-file-write` **Событие:** PreToolUse (Write) -**По умолчанию:** Инструктирует Claude подтвердить перед записью файлов больше 1024 КБ. +**По умолчанию:** Инструктирует Claude подтвердить перед записью файлов больше, чем 1024 KB. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `thresholdKb` | `number` | `1024` | Пороговое значение размера файла в килобайтах, выше которого выдается предупреждение. | +| `thresholdKb` | `number` | `1024` | Пороговое значение размера файла в килобайтах, выше которого выдаётся предупреждение. | **Пример:** @@ -616,7 +615,7 @@ failproofai поставляется с 39 встроенными политик ``` -Обработчик hook обеспечивает ограничение stdin в 1 МБ на полезные данные. Чтобы протестировать эту политику с малым содержимым, установите `thresholdKb` на значение намного ниже 1024. +Обработчик хука обеспечивает ограничение stdin в 1 MB для полезных нагрузок. Для тестирования этой политики с небольшим содержимым установите `thresholdKb` на значение намного ниже 1024. --- @@ -624,9 +623,9 @@ failproofai поставляется с 39 встроенными политик ### `warn-package-publish` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude подтвердить перед выполнением `npm publish`. +**По умолчанию:** Инструктирует Claude подтвердить перед запуском `npm publish`. -Параметры отсутствуют. +Нет параметров. --- @@ -635,36 +634,36 @@ failproofai поставляется с 39 встроенными политик **Событие:** PreToolUse (Bash) **По умолчанию:** Инструктирует Claude быть осторожным при запуске фоновых процессов через `nohup`, `&`, `disown` или `screen`. -Параметры отсутствуют. +Нет параметров. --- ### `warn-global-package-install` **Событие:** PreToolUse (Bash) -**По умолчанию:** Инструктирует Claude подтвердить перед выполнением `npm install -g`, `yarn global add` или `pip install` без виртуального окружения. +**По умолчанию:** Инструктирует Claude подтвердить перед запуском `npm install -g`, `yarn global add` или `pip install` без виртуального окружения. -Параметры отсутствуют. +Нет параметров. --- ## Менеджеры пакетов -Принудите агента использовать только разрешенные менеджеры пакетов. +Принудить агента использовать только разрешённые менеджеры пакетов. ### `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[] | `[]` | Разрешённые имена менеджеров пакетов. Любой обнаруженный менеджер, отсутствующий в этом списке, блокируется. Когда пусто, политика не работает. | +| `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,48 +679,48 @@ 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+ раза с идентичными параметрами — обычный признак того, что агент застрял в цикле. +**По умолчанию:** Инструктирует Claude пересмотреть, когда один и тот же инструмент вызывается 3+ раза с идентичными параметрами — частый знак того, что агент застрял в цикле. -Параметры отсутствуют. +Нет параметров. --- ## Рабочий процесс -Обеспечьте дисциплинированный рабочий процесс завершения сеанса. Эти политики срабатывают на событие **Stop** и запрещают Claude остановиться до выполнения каждого условия. Они следуют естественной цепочке зависимостей: commit → push → PR → CI. Если политика запрещает, последующие политики в цепочке пропускаются (deny ускоряет). +Обеспечить дисциплинированный рабочий процесс конца сеанса. Эти политики срабатывают на событие **Stop** и запрещают Claude останавливаться, пока не будут выполнены все условия. Они следуют естественной цепочке зависимостей: commit → push → PR → CI. Если политика запрещает, более поздние политики в цепи пропускаются (deny short-circuits). -Все политики рабочего процесса **fail-open**: если требуемый инструмент недоступен (например, `gh` не установлен, нет удаленного репо), политика разрешает с информационным сообщением, объясняющим, почему проверка была пропущена. +Все политики рабочего процесса **fail-open**: если требуемый инструмент недоступен (например `gh` не установлена, нет git удалённого), политика разрешает с информационным сообщением, объясняющим, почему проверка была пропущена. ### `require-commit-before-stop` **Событие:** Stop -**По умолчанию:** Запрещает остановку при наличии несохраненных изменений (измененные, поставленные на сцену или неотслеживаемые файлы). Возвращает информационное сообщение, когда рабочий каталог чист. +**По умолчанию:** Запрещает остановку, когда есть некоммитные изменения (модифицированные, staged или untracked файлы). Возвращает информационное сообщение, когда рабочая директория чистая. -Параметры отсутствуют. +Нет параметров. --- ### `require-push-before-stop` **Событие:** Stop -**По умолчанию:** Запрещает остановку, когда есть неправленные коммиты или когда текущая ветвь не имеет удаленной ветви отслеживания. Предлагает `git push -u` для создания ветви отслеживания при необходимости. Открывается при отсутствии настроенного удаленного репо. +**По умолчанию:** Запрещает остановку, когда есть непushнутые коммиты или когда текущая ветвь не имеет удалённой tracking ветви. Предлагает `git push -u` для создания tracking ветви, если это необходимо. Fail open, если нет configured удалённого. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `remote` | `string` | `"origin"` | Имя удаленного репо для push. | +| `remote` | `string` | `"origin"` | Имя удалённого для push. | **Пример:** @@ -740,14 +739,14 @@ failproofai поставляется с 39 встроенными политик ### `require-pr-before-stop` **Событие:** Stop -**По умолчанию:** Запрещает остановку, когда для текущей ветви не существует pull request или когда существующий PR закрыт без слияния. Инструктирует Claude создать PR с `gh pr create`. Когда PR **объединен**, политика разрешает (работа доставлена) и сообщение намекает переключиться с ветви (`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` с личным токеном доступа, имеющим область `repo` для чтения доступа к -pull requests. Если `gh` не установлен или не аутентифицирован, политика открывается и сообщает причину Claude. +Эта политика требует установки и аутентификации [GitHub CLI](https://cli.github.com/) (`gh`). +Запустите `gh auth login` с personal access token, который имеет `repo` scope для read access к +pull requests. Если `gh` не установлена или не аутентифицирована, политика fail open и сообщает причину Claude. --- @@ -755,24 +754,24 @@ pull requests. Если `gh` не установлен или не аутент ### `require-no-conflicts-before-stop` **Событие:** Stop -**По умолчанию:** Запрещает остановку, когда текущая ветвь не может чистоклслиться в базовую ветвь. Политика сначала подтверждает наличие `OPEN` PR на GitHub для ветви — без одного, нет цели слияния для принудительного исполнения, поэтому вся политика сокращает allow. После подтверждения `OPEN` PR выполняются два независимых зонда: +**По умолчанию:** Запрещает остановку, когда текущая ветвь не может чистоклиено смержиться в base ветвь. Политика сначала подтверждает, что есть `OPEN` PR на GitHub для ветви — без одного, нет merge target для принудительного, поэтому вся политика short-circuits для разрешения. Когда `OPEN` PR подтверждён, два независимых зонда запускаются: -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 секунд и переосмотреть перед повторной попыткой остановки — это предотвращает ложные отрицания, пока GitHub пересчитывает. +1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`. При конфликте, сообщение deny называет конфликтующие файлы, так что Claude знает точно, что разрешить. +2. **GitHub** — переиспользует `gh pr view --json mergeable,state` результат, уже поднятый в precheck. Ловит конфликты, которые stale local `origin/` бы пропустил (например someone landed конфликтующий PR на `main` с последней fetch). `CONFLICTING` результат запрещает. `UNKNOWN` результат также запрещает и инструктирует Claude ждать ~10 секунд и re-check перед попыткой остановки снова — это предотвращает false negatives, пока GitHub переочищает. -Полностью пропускает (разрешает) когда: `gh` не установлен, для ветви нет PR, состояние PR не `OPEN` (например, `MERGED`, `CLOSED`), или `gh pr view` возвращает нераспознаваемый вывод. Также открывается когда `origin/` отсутствует локально или когда нет коммитов впереди базы — те fallthrough слоя 1 все еще консультируются с кэшированной слиточностью PR перед разрешением. +Skips entirely (разрешает), когда: `gh` не установлена, нет PR для ветви, состояние PR не `OPEN` (например `MERGED`, `CLOSED`), или `gh pr view` возвращает непарсируемый вывод. Также fail open, когда `origin/` отсутствует локально или когда нет коммитов впереди base — те Layer 1 fall-throughs ещё консультируют cached PR mergeability перед разрешением. **Параметры:** | Параметр | Тип | По умолчанию | Описание | |-------|------|---------|-------------| -| `baseBranch` | `string` | `"main"` | Базовая ветвь для проверки конфликтов против. | +| `baseBranch` | `string` | `"main"` | Base ветвь для проверки конфликтов против. | GitHub CLI (`gh`) требуется для этой политики. Политика использует `gh pr view` для подтверждения -существования `OPEN` PR перед выполнением любого зонда конфликта — без `gh`, политика -сокращается к allow. Выполните `gh auth login` с личным токеном доступа, имеющим -область `repo` для чтения доступа к pull requests. +`OPEN` PR существует перед запуском любого конфликтного зонда — без `gh`, политика +short-circuits для разрешения. Запустите `gh auth login` с personal access token, который имеет +`repo` scope для read access к pull requests. --- @@ -780,14 +779,14 @@ GitHub CLI (`gh`) требуется для этой политики. Поли ### `require-ci-green-before-stop` **Событие:** Stop -**По умолчанию:** Запрещает остановку, когда проверки CI не пройдены или все еще выполняются на текущей ветви. Проверяет как запуски рабочих процессов GitHub Actions, так и проверки третьих сторон (например, CodeRabbit, SonarCloud, Codecov). Рассматривает заключения `skipped` и `cancelled` как успех. Возвращает информационное сообщение, когда все проверки проходят. +**По умолчанию:** Запрещает остановку, когда CI проверки неудачны или всё ещё запускаются на текущей ветви. Проверяет оба GitHub Actions workflow runs и третьих парти bot checks (например CodeRabbit, SonarCloud, Codecov). Рассматривает `skipped` и `cancelled` conclusions как успех. Возвращает информационное сообщение, когда все проверки проходят. -Параметры отсутствуют. +Нет параметров. -Эта политика требует установленный и аутентифицированный [GitHub CLI](https://cli.github.com/) (`gh`). -Выполните `gh auth login` с личным токеном доступа, имеющим область `repo` для чтения доступа к -запускам рабочих процессов Actions и API Checks. Если `gh` не установлен или не аутентифицирован, политика открывается и сообщает причину Claude. +Эта политика требует установки и аутентификации [GitHub CLI](https://cli.github.com/) (`gh`). +Запустите `gh auth login` с personal access token, который имеет `repo` scope для read access к +Actions workflow runs и Checks API. Если `gh` не установлена или не аутентифицирована, политика fail open и сообщает причину Claude. --- @@ -796,7 +795,7 @@ GitHub CLI (`gh`) требуется для этой политики. Поли ## Отключение отдельных политик -Удалите конкретную политику из `enabledPolicies` в вашей конфигурации или отключите ее на вкладке Policies в панели управления. +Удалить специфическую политику из `enabledPolicies` в вашей конфигурации, или отключить её в закладке Policies панели управления. ```json { @@ -807,4 +806,4 @@ GitHub CLI (`gh`) требуется для этой политики. Поли } ``` -Политики, не указанные в `enabledPolicies`, не запускаются, даже если для них существуют записи `policyParams`. \ No newline at end of file +Политики, не указанные в `enabledPolicies`, не запускаются, даже если существуют записи `policyParams` для них. \ No newline at end of file diff --git a/docs/ru/configuration.mdx b/docs/ru/configuration.mdx index 276edb9e..5d5afea9 100644 --- a/docs/ru/configuration.mdx +++ b/docs/ru/configuration.mdx @@ -1,63 +1,61 @@ ---- - --- title: Конфигурация -description: "Формат файла конфигурации, трёхуровневая система и правила слияния" +description: "Формат конфиг-файла, система трёх областей видимости и правила слияния" icon: gear --- -failproofai использует JSON-файлы конфигурации для управления активными политиками, их поведением и местом загрузки пользовательских политик. Конфигурация разработана так, чтобы её легко было делиться с командой — коммитьте её в репозиторий, и каждый разработчик получит одинаковую защиту агента. +failproofai использует JSON-файлы конфигурации для управления активными политиками, их поведением и путями загрузки пользовательских политик. Конфигурация разработана так, чтобы её было легко делиться с командой — закоммитьте её в репозиторий, и каждый разработчик получит одинаковую защиту агента. --- -## Уровни конфигурации +## Области видимости конфигурации -Существует три уровня конфигурации, оцениваемые в порядке приоритета: +Существует три области видимости конфигурации, оцениваемые в порядке приоритета: -| Уровень | Путь файла | Назначение | -|---------|-----------|-----------| -| **project** | `.failproofai/policies-config.json` | Настройки для конкретного репозитория, коммитятся в систему контроля версий | -| **local** | `.failproofai/policies-config.local.json` | Личные переопределения для конкретного репозитория, добавлены в gitignore | -| **global** | `~/.failproofai/policies-config.json` | Значения по умолчанию на уровне пользователя для всех проектов | +| Область | Путь файла | Назначение | +|-------|-----------|---------| +| **project** | `.failproofai/policies-config.json` | Параметры репозитория, закоммичены в систему контроля версий | +| **local** | `.failproofai/policies-config.local.json` | Личные переопределения в репозитории, в .gitignore | +| **global** | `~/.failproofai/policies-config.json` | Пользовательские значения по умолчанию для всех проектов | -Когда failproofai получает событие hook, он загружает и объединяет все три файла, которые существуют для текущего рабочего каталога. +Когда failproofai получает событие хука, он загружает и объединяет все три файла, которые существуют для текущей директории. ### Правила слияния -**`enabledPolicies`** — объединение всех трёх уровней. Политика, активированная на любом уровне, является активной. +**`enabledPolicies`** — объединение всех трёх областей видимости. Политика, активированная на любом уровне, работает. ```text project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← дедублицированное объединение +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: (нет entry block-sudo) -local: (нет entry 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`** — первая область видимости, определяющая это, побеждает. --- -## Формат файла конфигурации +## Формат конфиг-файла ```json { @@ -104,27 +102,27 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← переход к gl Тип: `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`, получают поведение, идентичное предыдущим версиям. -Неизвестные ключи внутри блока параметров политики молча игнорируются во время срабатывания 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 { @@ -134,49 +132,49 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← переход к gl }, "block-sudo": { "allowPatterns": ["sudo apt-get"], - "hint": "Используйте apt-get напрямую без sudo." + "hint": "Используйте apt-get непосредственно без sudo." }, "custom/my-policy": { - "hint": "Сначала запросите одобрение у пользователя." + "hint": "Сначала попросите одобрение у пользователя." } } } ``` -Когда `block-force-push` отклоняет запрос, Claude видит: *«Force-push заблокирован. Попробуйте создать свежую ветку вместо этого.»* +Когда `block-force-push` отклоняет, Claude видит: *"Force-pushing заблокирован. Попробуйте создать свежую ветку вместо этого."* -Не-строковые значения и пустые строки молча игнорируются. Если `hint` не установлен, поведение не меняется (обратно совместимо). +Не-строковые значения и пустые строки молча игнорируются. Если `hint` не установлен, поведение не меняется (обратная совместимость). ### `customPoliciesPath` Тип: `string` (абсолютный путь) -Путь к файлу JavaScript, содержащему пользовательские hook-политики. Устанавливается автоматически с помощью `failproofai policies --install --custom ` (путь разрешается в абсолютный перед сохранением). +Путь к JavaScript-файлу, содержащему пользовательские политики хуков. Устанавливается автоматически командой `failproofai policies --install --custom ` (путь преобразуется в абсолютный перед сохранением). -Файл загружается заново для каждого события hook — кэширования нет. Подробности разработки см. в разделе [Custom Policies](/ru/custom-policies). +Файл загружается заново при каждом событии хука — кеширования нет. Подробности в [Custom Policies](/ru/custom-policies). -### Политики на основе соглашений +### Политики, основанные на конвенциях -В дополнение к явному `customPoliciesPath`, failproofai автоматически обнаруживает и загружает файлы политик из директорий `.failproofai/policies/`: +В дополнение к явному `customPoliciesPath` failproofai автоматически обнаруживает и загружает файлы политик из директорий `.failproofai/policies/`: -| Уровень | Директория | Уровень | -|---------|-----------|--------| -| Project | `.failproofai/policies/` | Делится с командой через систему контроля версий | -| User | `~/.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`. Просто поместите файлы в директорию, и они будут подхвачены при следующем событии хука. -**Объединённая загрузка:** Обе директории соглашений (project и user) сканируются. Все соответствующие файлы из обоих уровней загружаются (в отличие от `customPoliciesPath`, который использует правило «первый уровень побеждает»). +**Загрузка объединением:** Сканируются обе директории конвенций — проектная и пользовательская. Все совпадающие файлы из обоих уровней загружаются (в отличие от `customPoliciesPath`, который использует правило первой области видимости). -Дополнительные сведения и примеры см. в разделе [Custom Policies](/ru/custom-policies). +Подробнее и примеры см. в [Custom Policies](/ru/custom-policies). ### `llm` Тип: `object` (опционально) -Конфигурация LLM-клиента для политик, которые выполняют вызовы AI. Не требуется для большинства конфигураций. +Конфигурация LLM-клиента для политик, которые делают вызовы ИИ. Не требуется для большинства установок. ```json { @@ -191,36 +189,44 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← переход к gl ## Управление конфигурацией из CLI -Команды `policies --install` и `policies --uninstall` записывают в файл hook-настроек вашего агентского CLI (точки входа hook), в то время как `policies-config.json` — файл, который вы управляете напрямую. Это два отдельных понятия: +Команды `policies --install` и `policies --uninstall` записывают в файл настроек хуков агента CLI (точки входа хуков), а `policies-config.json` — это файл, который вы управляете напрямую. Это два отдельных компонента: -- **Настройки агентского CLI** — указывает агенту вызывать `failproofai --hook ` при каждом использовании инструмента: - - **Claude Code**: `~/.claude/settings.json` (user), `/.claude/settings.json` (project), `/.claude/settings.local.json` (local) - - **OpenAI Codex**: `~/.codex/hooks.json` (user), `/.codex/hooks.json` (project) — у Codex нет локального уровня - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (user), `/.github/hooks/failproofai.json` (project) — у Copilot нет локального уровня. Hook-записи используют поля команд Copilot с привязкой к ОС `bash`/`powershell` с `timeoutSec`; файл содержит маркер версии верхнего уровня `version: 1`. Поддержка Copilot CLI находится в **бета**-версии, пока мы проверяем схему записи `events.jsonl` (которую публичная документация не указывает) против большего количества реальных сеансов. -- **`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 нет локальной области видимости + - **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 нет локальной области видимости. Записи хуков используют форму `{type, command, timeout}`, как у Claude (без разделения `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). Установка создаёт небольшой сгенерированный shim плагина, который вызывает бинарный файл failproofai в подпроцессе и переводит Claude-образный JSON-ответ бинарного файла обратно в семантику плагина (`throw new Error()` для deny, `client.session.prompt(...)` для instruct, no-op для allow). Сессии живут в 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 нет локальной области видимости. 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 находится в **beta**, пока стабилизируются API расширений Pi и формат журнала сессий. + - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (пользователь), `/.gemini/settings.json` (проект) — у Gemini нет локальной области видимости (в документации указана область `system` в `/etc/gemini-cli/settings.json`, которую failproofai не предоставляет). Записи хуков используют форму `{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 Gemini exit-0), `{hookSpecificOutput: {hookEventName, additionalContext}}` для впрыска контекста на BeforeAgent / AfterTool / SessionStart и `{decision: "block", reason}` на AfterAgent для семантики force-retry. Поддержка Gemini CLI находится в **beta**, пока мы расширяем реальное покрытие. См. [документацию хуков Gemini CLI](https://geminicli.com/docs/hooks/). +- **`policies-config.json`** — говорит failproofai, какие политики оценивать и с какими параметрами (доступно всем агентам CLI) -Передайте `--cli claude|codex|copilot` для выбора конкретного агента (разделённые пробелами или повторённые для любого подмножества): +Передайте `--cli claude|codex|copilot|cursor|opencode|pi|gemini`, чтобы ориентироваться на конкретного агента (разделённые пробелами или повторённые для любого подмножества): ```bash failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project -failproofai policies --install --cli claude codex copilot +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 claude codex copilot cursor opencode pi gemini ``` -Когда `--cli` опущен, `failproofai` обнаруживает, какие агентские CLI установлены (`which claude` / `which codex` / `which copilot`): +Когда `--cli` опущен, `failproofai` обнаруживает, какие агенты CLI установлены (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): - **Обнаружен один CLI** — автоматически выбирает этот CLI без подтверждения. -- **Обнаружены несколько CLI** в интерактивном терминале — показывает подсказку одноместного выбора со стрелками: при наличии двух CLI опции — `Both`, ` only`, ` only`; с тремя CLI первая опция становится `All` (↑↓ для перемещения, Enter для выбора, ^C для выхода). -- **Обнаружены несколько CLI** в неинтерактивном запуске (CI, нет TTY) — устанавливает для всех обнаруженных CLI без подтверждения. -- **Ничего не обнаружено** — возвращается к `claude` с предупреждением, что агентский бинарный файл не найден в PATH; команда hook всё равно записывается, поэтому активируется сразу же при установке. +- **Обнаружено несколько CLI** в интерактивном терминале — показывает быструю навигацию стрелками однократного выбора, сгруппированную в раздел `Detected (N)` (со строкой-агрегатором Установить для всех N обнаруженных + каждый обнаруженный CLI отдельно) и раздел `Not installed (M) · install hooks ahead of time`, перечисляющий каждый необнаруженный поддерживаемый CLI как опцию предварительной установки (↑↓ для перемещения, Enter для выбора, ^C для выхода). Поток удаления показывает только раздел Detected. +- **Обнаружено несколько CLI** в неинтерактивном запуске (CI, нет TTY) — устанавливает для всех обнаруженных CLI без подтверждения. +- **Ничего не обнаружено** — возвращается к `claude`, с предупреждением, что в PATH не найдена никакая версия агента; команда хука всё ещё записывается, так что она активируется, как только вы установите одну. -Вы можете редактировать `policies-config.json` напрямую в любое время; изменения вступают в силу немедленно при следующем событии hook без необходимости перезагрузки. +Вы можете редактировать `policies-config.json` напрямую в любое время; изменения вступают в силу немедленно при следующем событии хука без необходимости перезагрузки. --- -## Пример: конфигурация на уровне проекта с командными значениями по умолчанию +## Пример: конфиг на уровне проекта с командными значениями по умолчанию -Коммитьте `.failproofai/policies-config.json` в ваш репозиторий: +Закоммитьте `.failproofai/policies-config.json` в ваш репозиторий: ```json { @@ -239,4 +245,4 @@ failproofai policies --install --cli claude codex copilot } ``` -Каждый разработчик может затем создать `.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/dashboard.mdx b/docs/ru/dashboard.mdx index e07d7986..23ba9bed 100644 --- a/docs/ru/dashboard.mdx +++ b/docs/ru/dashboard.mdx @@ -1,10 +1,10 @@ --- title: Панель управления -description: "Мониторьте сеансы агентов, просматривайте вызовы инструментов и управляйте политиками" +description: "Отслеживайте сессии агентов, просматривайте вызовы инструментов и управляйте политиками" icon: chart-line --- -Панель управления failproofai — это локальное веб-приложение для мониторинга сеансов ваших AI-агентов и управления политиками. Узнайте, что делали ваши агенты, пока вас не было рядом. +Панель управления failproofai — это локальное веб-приложение для мониторинга сессий вашего AI-агента и управления политиками. Узнайте, что делали ваши агенты, пока вас не было. --- @@ -16,63 +16,63 @@ failproofai Открывается на `http://localhost:8020`. -Панель управления читает данные прямо из файловой системы — из папок проектов Claude Code и файлов конфигурации failproofai. Ничего не отправляется на удалённые сервисы. +Панель управления считывает данные непосредственно из файловой системы — ваши папки проектов Claude Code и файлы конфигурации failproofai. Никакие данные не отправляются на удалённый сервис. --- ## Страницы -### Projects +### Проекты -Перечисляет все найденные на вашей машине проекты Claude Code, OpenAI Codex и GitHub Copilot CLI _(бета)_. Проекты Claude обнаруживаются из `~/.claude/projects/` (или пути, установленного через `CLAUDE_PROJECTS_PATH`); проекты Codex обнаруживаются путём сканирования всех транскриптов в `~/.codex/sessions///
/*.jsonl` и группировкой по `cwd`, записанному в первой записи каждого сеанса; проекты Copilot CLI обнаруживаются путём сканирования каждого `~/.copilot/session-state//workspace.yaml` (настраивается через `COPILOT_HOME`) и группировкой по его полю `cwd`. Проект, используемый несколькими CLI, выводится в виде одной строки со всеми соответствующими значками. Используйте выпадающий список **CLI** над таблицей для фильтрации по конкретному агенту CLI; URL сохраняет ваш выбор как `?cli=claude|codex|copilot`. +Отображает все найденные на вашем компьютере проекты 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`. Проект, использованный несколькими интерфейсами CLI, отображается как одна строка со всеми соответствующими значками. Используйте раскрывающееся меню **CLI** над таблицей для фильтрации по конкретному агенту; URL сохраняет ваш выбор как `?cli=claude|codex|copilot|cursor|opencode|pi|gemini`. -Каждый проект показывает: -- Имя проекта (производное от пути папки) -- Значок CLI — `Claude Code` (оранжевый), `OpenAI Codex` (фиолетовый) и/или `GitHub Copilot` (синий) -- Дату последней активности сеанса +Каждый проект отображает: +- Имя проекта (получено из пути папки) +- Значок CLI — `Claude Code` (оранжевый), `OpenAI Codex` (фиолетовый), `GitHub Copilot` (синий), `Cursor Agent` (изумрудный), `OpenCode` (янтарный), `Pi` (розовый) и/или `Gemini CLI` (небесный) +- Дата самой последней активности сессии -Нажмите на проект, чтобы увидеть его сеансы. +Нажмите на проект, чтобы увидеть его сессии. -### Sessions +### Сессии -Перечисляет все сеансы в рамках проекта. Каждый сеанс показывает: -- ID сеанса -- Временные метки начала и окончания +Отображает все сессии в проекте. Каждая сессия показывает: +- Идентификатор сессии +- Временные метки начала и конца - Количество вызовов инструментов -- Количество активностей хуков (сработавшие политики) +- Количество действий перехватчиков (сработавших политик) -Используйте фильтр по диапазону дат и поиск по ID сеанса для сужения списка. Сеансы разделены на страницы. +Используйте фильтр по диапазону дат и поиск по ID сессии для сужения списка. Сессии отображаются с постраничной разбивкой. -Нажмите на сеанс, чтобы открыть просмотр сеанса. +Нажмите на сессию, чтобы открыть средство просмотра сессии. -### Session viewer +### Средство просмотра сессии -Просмотр сеанса отвечает на ключевой вопрос для автономных агентов: что делал агент и остался ли он сосредоточен? Значок CLI рядом с заголовком указывает, является ли сеанс транскриптом Claude Code или OpenAI Codex. Он отображает временную шкалу всех событий, произошедших в сеансе: +Средство просмотра сессии ответит на ключевой вопрос для автономных агентов: что сделал агент и остался ли он в курсе? Значок CLI рядом с заголовком показывает, является ли сессия транскриптом Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi или Gemini CLI. Это отображает временную шкалу всего, что произошло в сессии: -- **Messages** - текстовые ответы Claude и подсказки пользователя -- **Tool calls** - каждый инструмент, вызванный Claude, с его входными и выходными данными -- **Policy activity** - для каждого вызова инструмента показаны, какие политики срабатывали и какое решение они вернули +- **Сообщения** — текстовые ответы Claude и подсказки пользователя +- **Вызовы инструментов** — каждый инструмент, который вызвал Claude, с его входными и выходными данными +- **Активность политик** — для каждого вызова инструмента, какие политики сработали и какое решение они вернули -Строка статистики в верхней части показывает длительность сеанса, общее количество вызовов инструментов и сводку решений хуков (количество решений allow / deny / instruct). +Полоса статистики в верхней части показывает длительность сессии, общее количество вызовов инструментов и сводку решений перехватчиков (количество allow / deny / instruct). -Вы можете экспортировать сеанс в виде файла ZIP или JSONL, используя кнопку скачивания. +Нажмите кнопку **Download Logs** для экспорта сессии. Для сессий Claude Code, Codex, Copilot, Cursor, Pi и Gemini вы получаете исходный JSONL-транскрипт на диске байт в байт; для OpenCode (чьи сессии живут в SQLite, а не на диске) вы получаете документ JSON, отражающий базовые таблицы `session` / `messages` / `parts`. -### Policies +### Политики -Двухвкладышевая страница для управления политиками и просмотра активности. +Двухвкладочная страница для управления политиками и просмотра активности. - - - Включайте или отключайте отдельные политики одним щелчком (записывается в `~/.failproofai/policies-config.json`) - - Разверните политику для настройки её параметров (для политик, поддерживающих `policyParams`) - - Установите или удалите хуки для заданной области + + - Включайте или отключайте отдельные политики одним щелчком (записывает в `~/.failproofai/policies-config.json`) + - Разверните политику, чтобы настроить её параметры (для политик, поддерживающих `policyParams`) + - Установите или удалите перехватчики для заданной области - Установите пользовательский путь к файлу политик - - - Полная постраничная история всех событий хуков, которые срабатывали во всех сеансах - - Фильтруйте по решению, типу события, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(бета)_), названию политики или ID сеанса - - Каждая строка показывает: временную метку, имя политики, решение, значок CLI (оранжевый = Claude Code, фиолетовый = OpenAI Codex, синий = GitHub Copilot), имя инструмента, ID сеанса и причину решений deny/instruct - - Нажмите на ID сеанса, чтобы открыть его транскрипт — просмотр автоматически обнаруживает, какой CLI срабатил хук (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`) и отображает соответствующий значок CLI в заголовке + + - Полная постраничная история каждого события перехватчика, которое срабатывало во всех сессиях + - Фильтруйте по решению, типу события, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Gemini CLI _(beta)_), имени политики или 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 в заголовке @@ -80,13 +80,13 @@ failproofai ## Автоматическое обновление -Панель управления имеет переключатель автоматического обновления в верхней навигации. Если он включен, текущая страница периодически обновляется, чтобы показывать новые сеансы и активность политик по мере их появления. Существенно для мониторинга длительных сеансов автономных агентов. +Панель управления содержит переключатель автоматического обновления в верхней навигации. Когда он включен, текущая страница периодически обновляется, чтобы показать новые сессии и активность политик при их появлении. Необходимо для мониторинга долгоживущих сессий автономных агентов. --- ## Отключение страниц -Если вам нужны только некоторые части панели управления, установите `FAILPROOFAI_DISABLE_PAGES` в список названий страниц, разделённый запятыми: +Если вам нужны только некоторые части панели управления, установите `FAILPROOFAI_DISABLE_PAGES` на список имён страниц, разделённый запятыми: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -98,13 +98,13 @@ FAILPROOFAI_DISABLE_PAGES=policies failproofai ## Тема -Панель управления поддерживает светлый и тёмный режимы. Переключайте с помощью кнопки на панели навигации. Ваше предпочтение сохраняется в локальном хранилище браузера. +Панель управления поддерживает светлый и тёмный режимы. Переключайте через кнопку в строке навигации. Предпочтение сохраняется в локальном хранилище вашего браузера. --- -## Настройка пути к проектам +## Настройка пути проектов -По умолчанию панель управления читает из стандартного каталога проектов Claude Code. Переопределите его для пользовательских установок: +По умолчанию панель управления читает из стандартного каталога проектов Claude Code. Переопределите для пользовательских установок: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -112,15 +112,15 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## Доступ с хоста, отличного от localhost +## Доступ с немейнстрима 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 @@ -132,12 +132,12 @@ npm run dev -- --allowed-origins dashboard.example.com npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -Вы также можете установить переменную окружения `FAILPROOFAI_ALLOWED_DEV_ORIGINS`: +Вы также можете вместо этого установить переменную окружения `FAILPROOFAI_ALLOWED_DEV_ORIGINS`: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Это применяется только к режиму разработки. При запуске `failproofai` (режим производства) нет вебсокета HMR и проблем с кросс-доменными ресурсами разработки. +Это применяется только в режиме разработки. Когда вы запускаете `failproofai` (режим продакшена), нет HMR вебсокета и нет проблем с кросс-доменным доступом к ресурсам разработки. \ No newline at end of file diff --git a/docs/ru/getting-started.mdx b/docs/ru/getting-started.mdx index bec7a25f..8a339e28 100644 --- a/docs/ru/getting-started.mdx +++ b/docs/ru/getting-started.mdx @@ -1,13 +1,13 @@ --- title: Начало работы -description: "Установите failproofai, активируйте политики и позвольте вашим агентам работать надежно" +description: "Установите failproofai, включите политики и позвольте вашим агентам работать надёжно" icon: rocket --- ## Требования - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (опционально - требуется только для сборки из исходного кода) +- **Bun** >= 1.3.0 (опционально — требуется только для сборки из исходного кода) --- @@ -30,40 +30,44 @@ 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`). Если присутствует более одного, вам будет предложен выбор; передайте `--cli claude codex copilot` (любое подмножество) чтобы пропустить запрос. + Это записывает записи хуков в установленные 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` (любое подмножество) для пропуска запроса. - Поддержка GitHub Copilot CLI находится в статусе **beta** — установите с `--cli copilot`. + Поддержка GitHub Copilot CLI, Cursor Agent, OpenCode, Pi и Gemini CLI находится в **бета-версии** — устанавливайте с `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi` или `--cli gemini`. ```bash failproofai policies --install --scope project failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project + 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 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 автоматически перехватит это. Оставьте его запущённым и просмотрите результаты на панели управления. @@ -75,40 +79,40 @@ bun add -g 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 @@ -120,40 +124,40 @@ Claude Code → failproofai --hook PreToolUse → читает JSON из std 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" ``` - Каждый член команды, у которого установлен 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.local.json` | Личные переопределения (в .gitignore) | +| `~/.failproofai/hook.log` | Журнал отладки ошибок пользовательских хуков | +| `.failproofai/policies-config.json` | Конфигурация для каждого проекта (в репозитории) | +| `.failproofai/policies-config.local.json` | Личные переопределения (игнорируется git) | --- @@ -167,7 +171,7 @@ failproofai policies --uninstall --- -## Дальнейшие шаги +## Следующие шаги @@ -180,11 +184,11 @@ failproofai policies --uninstall - Напишите свои собственные политики на JavaScript + Напишите свои политики на JavaScript - Мониторьте сеансы и просматривайте активность политик + Отслеживайте сессии и просматривайте активность политик \ No newline at end of file diff --git a/docs/tr/architecture.mdx b/docs/tr/architecture.mdx index 1ffa6589..8a623b9b 100644 --- a/docs/tr/architecture.mdx +++ b/docs/tr/architecture.mdx @@ -1,11 +1,11 @@ --- --- title: Mimari -description: "Hook yöneticisinin, config yüklemesinin ve politika değerlendirmesinin dahili olarak nasıl çalıştığı" +description: "Hook işleyicisinin, yapılandırma yüklemesinin ve politika değerlendirmesinin dahili olarak nasıl çalıştığı" icon: sitemap --- -Bu belge failproofai'nin dahili olarak nasıl çalıştığını açıklar: hook sistemi agent araç çağrılarını nasıl yakaladığı, konfigürasyon nasıl yüklenip birleştirildiği, politikalar nasıl değerlendirildiği ve panelin agent aktivitesini nasıl izlediği. +Bu belge failproofai'nin dahili olarak nasıl çalıştığını açıklar: hook sistemi aracı araç çağrılarını nasıl kesintiye uğratır, yapılandırma nasıl yüklenir ve birleştirilir, politikalar nasıl değerlendirilir ve gösterge paneli aracı aktivitesini nasıl izler. --- @@ -13,18 +13,18 @@ Bu belge failproofai'nin dahili olarak nasıl çalıştığını açıklar: hook failproofai iki bağımsız alt sisteme sahiptir: -1. **Hook yöneticisi** - Claude Code'un her agent araç ç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 (Panel)** - Agent oturumlarını izlemek ve politikaları yönetmek için bir Next.js web uygulaması. +1. **Hook işleyicisi** - Claude Code'un her aracı araç çağrısında çağırdığı hızlı bir CLI alt işlemi. Politikaları değerlendirir ve bir karar döndürür. +2. **Aracı İzleyici (Gösterge Paneli)** - Aracı oturumlarını izlemek ve politikaları yönetmek için bir Next.js web uygulaması. -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. +Her iki alt sistem da `~/.failproofai/` ve projenin `.failproofai/` dizininde yapılandırma dosyalarını paylaşır, ancak ayrı işlemler olarak çalışırlar ve yalnızca dosya sistemi aracılığıyla iletişim kurabilirler. --- -## Hook yöneticisi +## Hook işleyicisi ### Claude Code ile Entegrasyon -`failproofai policies --install` komutunu çalıştırdığınızda, `~/.claude/settings.json` dosyasına şu gibi girişler yazar: +`failproofai policies --install` komutunu çalıştırdığınızda, `~/.claude/settings.json` içine şu gibi girişleri yazar: ```json { @@ -45,9 +45,9 @@ Her iki alt sistem `~/.failproofai/` ve projenin `.failproofai/` dizinindeki kon } ``` -Claude Code daha sonra her araç çağrısından önce `failproofai --hook PreToolUse` komutunu bir alt işlem olarak çağırır ve stdin'de JSON yükü iletir. +Claude Code daha sonra her araç çağrısından önce `failproofai --hook PreToolUse` komutunu bir alt işlem olarak çağırır ve stdin üzerinden bir JSON yükü geçirir. -### Yük biçimi +### Yük Formatı ```json { @@ -63,9 +63,9 @@ Claude Code daha sonra her araç çağrısından önce `failproofai --hook PreTo `PostToolUse` olayları için, yük ayrıca aracın çıktısını içeren `tool_result` içerir. -Yönetici 1 MB stdin sınırı uygular. Bu sınırı aşan yükler atılır ve tüm politikalar örtük olarak izin verir. +İşleyici 1 MB stdin sınırını zorlar. Bu limiti aşan yükler atılır ve tüm politikalar örtülü olarak izin verir. -### Yanıt biçimi +### Yanıt Formatı **Reddet (PreToolUse):** ```json @@ -95,97 +95,97 @@ Yönetici 1 MB stdin sınırı uygular. Bu sınırı aşan yükler atılır ve t } ``` -**Stop olay talimatı:** +**Stop olayı talimatı:** - Çıkış kodu: `2` -- Sebep stderr'ye yazılır (stdout değil) +- Nedeni stderr'e yazılır (stdout'a değil) **İzin Ver:** - Çıkış kodu: `0` - Boş stdout -**İletili mesaj ile İzin Ver:** +**İleti ile İzin Ver:** -`allow(message)` bir politikanın işlem izin verildiğinde bile Claude'a bilgilendirici bağlam göndermesini sağlar. Hook yöneticisi aşağıdaki JSON'u **stdout**'a yazar (config dosyası değil — bu, yukarıdaki reddet ve talimat yanıtları gibi hook yöneticisinin Claude Code'a verdiği yanıt): +`allow(message)`, bir politikanın işlem izin verilirken bile Claude'a bilgilendirici bağlam gönderebilmesini sağlar. Hook işleyicisi aşağıdaki JSON'u **stdout'a** yazar (bir yapılandırma dosyasına değil — bu, deny ve instruct yanıtları gibi hook işleyicisinin Claude Code'a verdiği yanıttır): ```json -// Hook yönetici işlemi tarafından stdout'a yazılır +// Hook işleyici süreci tarafından stdout'a yazılır { "hookSpecificOutput": { "additionalContext": "All CI checks passed on branch 'feat/my-feature'." } } ``` -- Çıkış kodu: `0` (işleme izin verildi) -- Birden fazla politika mesaj içeren `allow` döndürdüğünde, mesajları yeni satırlarla birleştirilerek tek `additionalContext` dizesine katılır -- Hiçbir politika mesaj sağlamadığında, stdout boştur (daha öncekinin aynısı) +- Çıkış kodu: `0` (işlem izin verilir) +- Birden çok politika `allow` ile bir ileti döndürdüğünde, mesajları yeni satırlarla birleştirilmiş bir tek `additionalContext` dizesine katılırlar +- Hiçbir politika bir ileti sağlamıyorsa, stdout boştur (önceki gibi) -### İşleme ardışık düzeni +### İşleme Ardışık Düzeni `src/hooks/handler.ts` tam ardışık düzeni uygular: ```text stdin JSON - → yük ayrıştırma (maks 1 MB) - → oturum meta verisi çıkarma (session_id, cwd, tool_name, tool_input, vb.) - → readMergedHooksConfig(cwd) ← proje + yerel + genel config birleştirir - → etkinleştirilen yerleşik politikaları çözülmüş parametrelerle kaydettir - → customPoliciesPath'tan özel politikaları yükle (ayarlanmışsa) - → özel politikaları politika kaydına kaydettir - → tüm politikaları değerlendir (yerleşikleri önce, sonra özel) - → ilk reddet kısa devre yapar - → talimat kararları birikir - → mesajlara izin verir birikiyor - → JSON kararını stdout'a yaz - → olayı ~/.failproofai/hook-activity.jsonl'ye kaydet - → çık + → 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 ``` -Tüm işlem, LLM çağrıları olmayan tipik yükler için 100 ms altında çalışır. +Tüm işlem, LLM çağrısı olmayan tipik yükler için 100ms altında çalışır. --- -## Konfigürasyon yükleme +## Yapılandırma Yükleme -`src/hooks/hooks-config.ts` üç kapsamlı config yüklemeyi uygular. +`src/hooks/hooks-config.ts` üç kapsamlı yapılandırma yüklemesini 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 ← genel (en düşük öncelik) +[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) ``` Birleştirme mantığı: -- `enabledPolicies` - üç dosya arasında tekilleştirilmiş birleşim -- `policyParams` - politika başına anahtar, onu tanımlayan ilk dosya tamamen kazanır -- `customPoliciesPath` - onu tanımlayan ilk dosya kazanır -- `llm` - onu tanımlayan ilk dosya kazanır +- `enabledPolicies` - üç dosya arasında çoğaltılmış birleşim +- `policyParams` - politika başına anahtar, ilk dosya tam olarak tanımlanan kazanır +- `customPoliciesPath` - ilk dosya tanımlayan kazanır +- `llm` - ilk dosya tanımlayan kazanır -Web paneli, proje cwd'si olmadığı için okuma ve yazma için `readHooksConfig()` (yalnızca genel) kullanır. +Web gösterge paneli, bir proje cwd'si ile çağrılmadığından, okuma ve yazma için `readHooksConfig()` (yalnızca global) kullanır. --- -## Politika değerlendirmesi +## Politika Değerlendirmesi `src/hooks/policy-evaluator.ts` politikaları sırayla çalıştırır. Her politika için: 1. Politikanın `params` şemasını arayın (eğer varsa). -2. Birleştirilmiş config'den `policyParams[policy.name]` okuyun. -3. `ctx.params` üretmek için kullanıcı tarafından sağlanan değerleri şema varsayılanlarının üzerine birleştirin. -4. `policy.fn(ctx)` komutunu çözülmüş bağlamla çağırın. -5. Sonuç `deny` ise, hemen durdurun ve o kararı döndürün. -6. Sonuç `instruct` ise, mesajı biriktirebilir ve devam edin. +2. Birleştirilmiş yapılandırmadan `policyParams[policy.name]` okuyun. +3. Kullanıcı tarafından sağlanan değerleri şema varsayılanları üzerine birleştirerek `ctx.params` oluşturun. +4. Çözümlenmiş bağlam ile `policy.fn(ctx)` çağırın. +5. Sonuç `deny` ise, hemen durarak bu kararı döndürün. +6. Sonuç `instruct` ise, mesajı biriktirir ve devam edin. 7. Sonuç `allow` ise, sonraki politikaya devam edin. Tüm politikalar çalıştıktan sonra: -- Herhangi bir `deny` döndürüldüyse, reddet yanıtını gönderin. -- Herhangi bir `instruct` dönüşü toplanmışsa, tüm mesajları birleştirilmiş olarak tek bir talimat yanıtı gönderin. -- Aksi takdirde, izin yanıtı gönderin (boş stdout, çıkış 0). +- Herhangi bir `deny` döndürülmüşse, deny yanıtını yayınlayın. +- Herhangi bir `instruct` dönüşü toplanmışsa, tüm mesajlar birleştirilmiş tek bir instruct yanıtını yayınlayın. +- Aksi takdirde, bir allow yanıtını yayınlayın (boş stdout, çıkış 0). --- -## Yerleşik politikalar +## Yerleşik Politikalar `src/hooks/builtin-policies.ts` tüm 26 yerleşik politikayı `BuiltinPolicyDefinition` nesneleri olarak tanımlar: @@ -205,13 +205,13 @@ interface BuiltinPolicyDefinition { } ``` -`params`'ı kabul eden politikalar, her parametre için türler ve varsayılanları içeren bir `PolicyParamsSchema` bildirir. Politika değerlendiricisi `fn` çağrılmadan önce çözülmüş değerleri `ctx.params`'a enjekte eder. Politika işlevleri varsayılanlar her zaman önce uygulandığından `ctx.params`'ı null-koruması olmadan okurlar. +`params` kabul eden politikalar, her parametre için türler ve varsayılanlarla birlikte bir `PolicyParamsSchema` tanımlarlar. Politika değerlendiricisi, `fn` çağrısından önce çözümlenmiş değerleri `ctx.params` öğesine enjekte eder. Politika işlevleri, varsayılanlar her zaman ilk uygulandığından `ctx.params` öğesini null koruması olmadan okur. -Politikalar içindeki desen eşleştirmesi, ham dize eşleştirmesi değil, ayrıştırılmış komut belirteçlerini (argv) kullanır. Bu, shell operatörü enjeksiyonu yoluyla bypass'ı önler (örneğin `sudo systemctl status *` için bir desen `;`rm -rf /` ekleyerek bypass yapılamaz). +Politikaların içindeki desen eşleştirmesi, ham dize eşleştirmesi yerine ayrıştırılmış komut belirteçlerini (argv) kullanır. Bu, shell operatörü enjeksiyonu yoluyla bypass'ı engeller (örn. `sudo systemctl status *` için bir desen `; rm -rf /` ekleyerek bypass edilemez). --- -## Özel politikalar +## Özel Politikalar `src/hooks/custom-hooks-registry.ts` bir `globalThis`-destekli kayıt defteri uygular: @@ -223,28 +223,28 @@ export const customPolicies = { }; export function getCustomHooks(): CustomHook[] { ... } -export function clearCustomHooks(): void { ... } // testlerde kullanılır +export function clearCustomHooks(): void { ... } // used in tests ``` `src/hooks/custom-hooks-loader.ts` kullanıcının politika dosyasını yükler: -1. Config'den `customPoliciesPath` okuyun; yoksa atla. -2. Mutlak yola çözümlendirin; dosya varlığını kontrol edin. -3. Tüm `from "failproofai"` ithalatlarını gerçek dağıtım yoluna yazarak `customPolicies`'in aynı `globalThis` kaydına çözümlenmesini sağla. -4. ESM uyumluluğunu sağlamak için geçişli yerel ithalatları özyinelemeli olarak yazın. -5. Geçici `.mjs` dosyaları yazın ve giriş dosyasını `import()` yapın. +1. Yapılandırmadan `customPoliciesPath` okuyun; yoksa atla. +2. Mutlak yola çözümleme; dosya var mı diye kontrol edin. +3. Tüm `from "failproofai"` içe aktarmalarını gerçek dist yoluna yeniden yazın; böylece `customPolicies` aynı `globalThis` kaydına çözümlensin. +4. ESM uyumluluğunu sağlamak için geçişli yerel içe aktarmaları özyinelemeli olarak yeniden yazın. +5. Geçici `.mjs` dosyaları yazın ve giriş dosyasını `import()` işleyin. 6. Kayıtlı kancaları almak için `getCustomHooks()` çağırın. -7. Tüm geçici dosyaları bir `finally` bloğunda temizleyin. +7. `finally` bloğunda tüm geçici dosyaları temizleyin. -Herhangi bir hata durumunda (dosya bulunamadı, sözdizim hatası, ithalatçı hatası), hata `~/.failproofai/hook.log`'a günlüğe kaydedilir ve yükleyici boş bir dizi döndürür. Yerleşik politikalar etkilenmez. +Herhangi bir hatada (dosya bulunamadı, söz dizimi hatası, içe aktarma başarısızlığı), hata `~/.failproofai/hook.log` öğesine kaydedilir ve yükleyici boş bir dizi döndürür. Yerleşik politikalar etkilenmez. -Özel politikalar tüm yerleşik politikalardan sonra değerlendirilir. Özel bir politika `deny` yine sonraki özel politikaları kısa devre yapar (ancak o noktada tüm yerleşikler zaten çalıştırılmışlardır). +Özel politikalar tüm yerleşik politikaların ardından değerlendirilir. Özel bir politika `deny` yine de daha fazla özel politikayı kısa devre eder (ancak tüm yerleşik olanlar zaten o noktada çalışmıştır). --- -## Aktivite günlüğü kaydı +## Aktivite Günlüğü -Her hook olayından sonra, yönetici `~/.failproofai/hook-activity.jsonl`'ye bir JSONL satırı ekler: +Her hook olayından sonra, işleyici `~/.failproofai/hook-activity.jsonl` öğesine bir JSONL satırı ekler: ```json { @@ -259,75 +259,75 @@ Her hook olayından sonra, yönetici `~/.failproofai/hook-activity.jsonl`'ye bir } ``` -İzin vermeyen kararı alan her politika için bir satır. İzin verme kararları günlüğe kaydedilmez (dosyayı küçük tutmak için). +İzin vermeyen bir karar alan her politika için bir satır. Allow kararları günlüğe kaydedilmez (dosyayı küçük tutmak için). --- -## Panel mimarisi +## Gösterge Paneli Mimarisi -Panel, React Server Components ve Server Actions kullanan App Router'ı içeren bir **Next.js 16** uygulamasıdır. +Gösterge paneli, React Server Components ve Server Actions ile App Router'ı kullanan bir **Next.js 16** uygulamasıdır. ```text app/ - layout.tsx ← Kök düzeni (tema, telemetri, nav) - 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 (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 ← Sunucu bileşeni: oturum görüntüleyici oluştur - policies/page.tsx ← İstemci bileşeni: politika yönetimi + aktivite günlüğü + [sessionId]/page.tsx ← Server component: render session viewer + policies/page.tsx ← Client component: policy management + activity log actions/ - 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 ← Aktivite günlüğünü sayfalara ayır/ara - install-hooks-web.ts ← Tarayıcıdan kancaları kur/kaldır + 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 ← Oturumu ZIP/JSONL olarak dışa aktar + download/[project]/[session]/route.ts ← Per-CLI session export (JSONL or JSON) ``` **Veri akışı:** -- Sayfa bileşenleri, proje/oturum verilerini doğrudan dosya sisteminden okumak için `lib/projects.ts` ve `lib/log-entries.ts`'ı çağırır (okumalar için API katmanı yoktur). -- Politikalar sayfası tüm mutasyonlar için Server Actions kullanır (aç/kapat, parametreler güncellemesi, kur/kaldır). -- Oturum görüntüleyeni Claude'un JSONL transkript biçimini ayrıştırır ve mesajlar ile araç çağrılarının bir zaman çizelgesini oluşturur. +- Sayfa bileşenleri, proje/oturum verilerini doğrudan dosya sisteminden okumak için `lib/projects.ts` ve `lib/log-entries.ts` çağırır (okumalar için API katmanı yoktur). +- Politikalar sayfası tüm mutasyonlar (geçiş, parametreler güncellemesi, yükleme/kaldırma) için Server Actions kullanır. +- Oturum görüntüleyicisi, Claude'un JSONL transkript formatını ayrıştırır ve mesaj ve araç çağrılarının bir zaman çizelgesini gösterir. **Temel 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'ye gerek yok. +- Veritabanı yok - tüm kalıcı durum düz dosyalarda bulunur (`~/.failproofai/`, `~/.claude/projects/`). +- Mutasyonlar için Server Actions - CRUD işlemleri için REST API gerekmez. - 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ç/kapanır, aktivite araması, günlük görüntüleyici). +- İstemci bileşenleri yalnızca etkileşim gerektiğinde (politika değiştiricileri, etkinlik araması, günlük görüntüleyici). --- -## Dosya düzeni +## Dosya Düzeni ```text failproofai/ ├── bin/ -│ └── failproofai.mjs # CLI yönlendiricisi (hook / panel / kurulum / vb.) +│ └── failproofai.mjs # CLI router (hook / dashboard / install / etc.) ├── src/hooks/ -│ ├── handler.ts # Hook olay ardışık düzeni -│ ├── builtin-policies.ts # 26 politika tanımı -│ ├── policy-evaluator.ts # Politika yürütme motoru -│ ├── policy-registry.ts # Politika kaydı ve arama -│ ├── policy-types.ts # TypeScript arayüzleri -│ ├── hooks-config.ts # Çok kapsamlı config yükleme -│ ├── custom-hooks-registry.ts # globalThis-destekli kanca kaydı -│ ├── custom-hooks-loader.ts # Kullanıcı JS kankaları için ESM yükleyici -│ ├── manager.ts # kurulum / kaldırma / listeleme işlemleri -│ ├── install-prompt.ts # Etkileşimli politika seçim istemi -│ ├── hook-logger.ts # hook.log'a günlük kaydı -│ ├── hook-activity-store.ts # Aktiviteyi hook-activity.jsonl'ye kaydet -│ └── llm-client.ts # LLM API istemcisi (AI güçlendirilmiş politikalar için) -├── app/ # Next.js paneli (sayfalar + sunucu eylemleri) -├── lib/ # Paylaşılan yardımcılar -│ ├── projects.ts # Dosya sisteminden Claude projelerini listelendirme -│ ├── log-entries.ts # Claude transkript JSONL biçimini ayrıştırma -│ ├── paths.ts # Sistem yollarını çözümlendirme +│ ├── handler.ts # Hook event pipeline +│ ├── builtin-policies.ts # 26 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/ # Paylaşılan React UI bileşenleri -├── contexts/ # React bağlam sağlayıcıları (tema, otomatik yenileme, telemetri) -├── examples/ # Örnek özel kanca dosyaları -└── __tests__/ # Birim ve E2E testleri +├── 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/tr/built-in-policies.mdx b/docs/tr/built-in-policies.mdx index 8aed753b..8a2efbd1 100644 --- a/docs/tr/built-in-policies.mdx +++ b/docs/tr/built-in-policies.mdx @@ -1,22 +1,22 @@ --- title: Yerleşik İlkeler -description: "Ajan başarısızlığının yaygın nedenlerini yakalayan 39 yerleşik ilke" +description: "Ajent hatasının yaygın nedenlerini yakalayan 39 yerleşik ilke" icon: shield --- -failproofai, ajan başarısızlığının yaygın nedenlerini yakalayan 39 yerleşik ilke ile birlikte gelir. Her ilke, belirli bir hook etkinliği türü ve araç adında tetiklenir. On dokuz ilke, kodlama yapmadan davranışlarını ayarlamanızı sağlayan parametreleri kabul eder. Beş iş akışı ilkesi, Claude'un durduğundan önce commit → push → PR → CI ardışık düzenini zorunlu kılar. +failproofai, ajent hatasının yaygın nedenlerini yakalayan 39 yerleşik ilke ile birlikte gelir. Her ilke belirli bir hook olay türü ve araç adı üzerinde etkinleşir. On dokuz ilke, kodu yazmadan davranışlarını ayarlamanıza olanak sağlayan parametreleri kabul eder. Beş iş akışı ilkesi, Claude durmadan önce commit → push → PR → CI ardışık düzenini zorunlu kılar. --- ## Genel Bakış -İlkeler kategoriler halinde gruplandırılır: +İlkeler kategorilere ayrılmış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 | -| [Sırlar (temizleyiciler)](#sırlar-temizleyiciler) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | +| [Sırlar (sanitizler)](#sırlar-sanitizler) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse | | [Ortam](#ortam) | block-env-files, protect-env-vars | PreToolUse | | [Dosya erişimi](#dosya-erişimi) | 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, ajan başarısızlığının yaygın nedenlerini yakalayan 39 yerle | [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-`** — ajanın devam etmesini engeller. -- **`warn-`** — ajanın kendi kendini düzeltmesi için ek bağlam sağlar. -- **`sanitize-`** — ajan görmeden önce araç çıktısından hassas verileri temizler. +- **`block-`** — ajenti devam etmesini engeller. +- **`warn-`** — ajente kendi kendini düzeltmesi için ek bağlam sağlar. +- **`sanitize-`** — ajent tarafından görülmeden önce araç çıktısından hassas verileri temizler. ### Ad Alanları -Her ilke bir `/` alanında yer alır. Yerleşik ilkeler **`exospherehost/`** ad alanına aittir — örneğin, `exospherehost/sanitize-jwt`. Ad alanı, benzer kısa adlara sahip özel veya üçüncü taraf ilkeler yüklediğinizde çakışmaları engeller. +Her ilke bir `/` yuvasında bulunur. Yerleşik ilkeler **`exospherehost/`** ad alanına aittir — örneğin, `exospherehost/sanitize-jwt`. Ad alanı, benzer kısa adlara sahip özel veya üçüncü taraf ilkeler yüklemek için çakışmaları önler. -Yapılandırmanızda yerleşik bir ilkeye kısa adı veya tam nitelikli adı ile başvurabilirsiniz; her iki form aynı ilkeyi çözer: +Yapılandırmanızda yerleşik bir ilkeye kısa adı veya tam adı ile başvurabilirsiniz; her iki form de aynı ilkeye çözümlenir: ```json { @@ -44,33 +44,33 @@ Yapılandırmanızda yerleşik bir ilkeye kısa adı veya tam nitelikli adı ile } ``` -Bir ad `/` içermiyorsa, failproofai bunu varsayılan `exospherehost` ad alanına ait olarak işler. Zaten `/` içeren adlar (örneğin `myorg/foo`, `custom/my-hook`) olduğu gibi kalır. -- **`require-`** — koşullar karşılanana kadar Stop etkinliğini engeller. +Bir adın `/` içermemesi durumunda, failproofai bunu varsayılan ad alanı `exospherehost`e ait olarak işler. Zaten `/` içeren adlar (örn. `myorg/foo`, `custom/my-hook`) olduğu gibi kalır. +- **`require-`** — koşullar karşılanana kadar Durdur olayını engeller. --- -Her ilke `policyParams` içinde isteğe bağlı bir `hint` alanını destekler. İpucu, deny veya instruct mesajına eklenir ve Claude bunu görür, ilke kodunu değiştirmeden işlem yapabilir 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üğü inkar veya talimat mesajına eklenir ve ilke kodunu değiştirmeden işlem yapabilecek 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) konusuna bakın. --- ## Tehlikeli komutlar -Ajanları geri alması zor olan veya ana sisteme zarar verebilecek işlemleri çalıştırmaktan koruyun. +Ajanları geri almayı zor olan veya ana sistem hasar verebilecek işlemleri çalıştırmaktan koruyu. ### `block-sudo` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Herhangi bir `sudo` komutunu reddeder. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `sudo` komutunu reddeder. -`sudo` anahtar sözcüğünü içeren çağrıları engeller. Desen eşleştirmesi, ham dizeyi değil, ayrıştırılmış komut belirteçleri üzerinde yapılır ve bu da kabuk operatörü enjeksiyonu yoluyla atlama girişimlerini engeller. +`sudo` anahtar sözcüğünü içeren çağırmaları engeller. Desen eşleştirmesi, shell operatörü enjeksiyonu yoluyla bypass'ı önlemek için ham dize değil, ayrıştırılmış komut belirteçleri üzerinde yapılır. **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 belirteçleri ile eşleştirilir. | **Örnek:** @@ -87,21 +87,21 @@ Ajanları geri alması zor olan veya ana sisteme zarar verebilecek işlemleri ç 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, ek kabuk operatörleri yoluyla atlama girişimlerini engeller (örneğin `sudo systemctl status x; rm -rf /`, `sudo systemctl status *` ile eşleşmez). +Desenler ham komut dizesi değil, ayrıştırılmış belirteçler ile eşleştirilir. Bu, eklenen shell operatörleri yoluyla bypass'ı önler (örn. `sudo systemctl status x; rm -rf /`, `sudo systemctl status *` ile eşleşmez). --- ### `block-rm-rf` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** `rm -rf`, `rm -fr` ve benzer özyinelemeli silme biçimlerini reddeder. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `rm -rf`, `rm -fr` ve benzeri özyinelemeli silme türlerini reddeder. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `allowPaths` | `string[]` | `[]` | Özyinelemeli olarak silinmek için güvenli olan yollar (örneğin `/tmp`). | +| `allowPaths` | `string[]` | `[]` | Özyinelemeli olarak silinmesi güvenli olan yollar (örn. `/tmp`). | **Örnek:** @@ -119,7 +119,7 @@ Desenler ham komut dizesi değil, ayrıştırılmış belirteçlere karşı eşl ### `block-curl-pipe-sh` -**Etkinlik:** PreToolUse (Bash) +**Olay:** PreToolUse (Bash) **Varsayılan:** `curl | bash`, `curl | sh`, `wget | bash` ve benzer desenleri reddeder. Parametre yok. @@ -128,8 +128,8 @@ Parametre yok. ### `block-failproofai-commands` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** failproofai'yi kaldıracak veya devre dışı bırakacak komutları reddeder (örneğin `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Olay:** PreToolUse (Bash) +**Varsayılan:** failproofai'yı kaldıracak veya devre dışı bırakacak komutları reddeder (örn. `npm uninstall failproofai`, `failproofai policies --uninstall`). Parametre yok. @@ -137,14 +137,14 @@ Parametre yok. ## Altyapı komutları -Kodlama ajanlarını altyapı CLI'lerini çalıştırmaktan veya CI/CD ardışık düzenlerini tetiklemekten uzak tutun. Bu kategorideki tüm ilkeler **opt-in** (`defaultEnabled: false`) — `kubectl`, `terraform` vb. çağrısına meşru ihtiyaçları olan ajanlar, ilke etkinleştirilmediğinde engellenmez. Etkinleştirildiğinde, eşleştirilmiş CLI'nin her çağrısı `allowPatterns` içindeki bir girdiye uymadıkça reddedilir. +Kodlama ajanlarını altyapı CLI'lerini çalıştırmaktan veya CI/CD ardışık düzenlerini tetiklemekten durdurun. Bu kategorideki tüm ilkeler **opt-in** (`defaultEnabled: false`) — `kubectl`, `terraform` vb. çağırmaya hakkı olan ajanlar, ilkeyi etkinleştirmedikçe engellenmez. Etkinleştirildiğinde, eşleştirilen CLI'nin her çağrısı, komut `allowPatterns` içindeki bir girişle eşleşmediğince reddedilir. -Desen dilbilgisi [`block-sudo`](#block-sudo) ile aynıdır: belirteçler ayrıştırılmış argv'ye karşı eşleştirilir, `*` tek bir belirteç için joker kartır ve enjeksiyondan korunmak için bağımsız kabuk operatörü (`&&`, `||`, `|`, `;`) içeren veya gömülü kabuk metakarakterlerine sahip bir belirteç içeren komutlar, izin listesi eşleştirmesinden önce reddedilir. +Desen dilbilgisi [`block-sudo`](#block-sudo) ile aynıdır: belirteçler ayrıştırılmış argv ile eşleştirilir, `*` bir belirteç için joker karakterdir ve enjeksiyon bypass'ını önlemek için whitelist eşleştirmesinden önce bağımsız shell operatörü (`&&`, `||`, `|`, `;`) veya katıştırılmış shell metakarakterine sahip belirteç içeren komutlar reddedilir. ### `block-kubectl` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Herhangi bir `kubectl` çağrısını reddeder. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `kubectl` çağrılarını reddeder. **Parametreler:** @@ -170,8 +170,8 @@ Bu yapılandırma ile `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-terraform` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Herhangi bir `terraform` veya `tofu` (OpenTofu) çağrısını reddeder. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `terraform` veya `tofu` (OpenTofu) çağrılarını reddeder. **Parametreler:** @@ -195,8 +195,8 @@ Bu yapılandırma ile `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-aws-cli` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Herhangi bir `aws` CLI çağrısını reddeder. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `aws` CLI çağrılarını reddeder. **Parametreler:** @@ -220,8 +220,8 @@ Bu yapılandırma ile `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-gcloud` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Herhangi bir `gcloud` (Google Cloud) CLI çağrısını reddeder. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `gcloud` (Google Cloud) CLI çağrılarını reddeder. **Parametreler:** @@ -245,8 +245,8 @@ Bu yapılandırma ile `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-az-cli` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Herhangi bir `az` (Azure) CLI çağrısını reddeder. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `az` (Azure) CLI çağrılarını reddeder. **Parametreler:** @@ -270,8 +270,8 @@ Bu yapılandırma ile `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-helm` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Herhangi bir `helm` çağrısını reddeder. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `helm` çağrılarını reddeder. **Parametreler:** @@ -295,8 +295,8 @@ Bu yapılandırma ile `kubectl get pods` izin verilir ancak `kubectl apply -f de ### `block-gh-pipeline` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Durumu değiştirecek veya ardışık düzenleri tetikleyecek aşağıdaki `gh` CLI alt komutlarını reddeder: +**Olay:** PreToolUse (Bash) +**Varsayılan:** Durumu değiştiren veya ardışık düzenleri 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` @@ -305,13 +305,13 @@ Bu yapılandırma ile `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 ilke tarafından eşleştirilmez — iş akışı kontrolleri için rutin olarak gereklidir (failproofai'nin kendi `require-ci-green-before-stop` dahil). +`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ışı kontrolleri için düzenli olarak gereklidir (failproofai'ın kendi `require-ci-green-before-stop` dahil). **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `allowPatterns` | `string[]` | `[]` | Aksi takdirde reddedilecek olsa da izin verilecek belirli komut dosyası çağrıları. | +| `allowPatterns` | `string[]` | `[]` | Aksi takdirde reddedilecek olsa da izin verilecek belirli script çağrıları. | **Örnek:** @@ -327,14 +327,14 @@ Bu yapılandırma ile `kubectl get pods` izin verilir ancak `kubectl apply -f de --- -## Sırlar (temizleyiciler) +## Sırlar (sanitizler) -Ajanları kimlik bilgilerini bağlamlarına veya çıktılarına sızlatmaktan koruyun. Temizleyici ilkeleri **PostToolUse** etkinliklerinde tetiklenir. Claude bir Bash komutu çalıştırdığında, bir dosya okuduğunda veya herhangi bir aracı çağırdığında, bu ilkeler Claude'a döndürülmeden önce çıktıyı inceler. Gizli bir desen algılanırsa, ilke çıktının geri dönüşünü engelleyen deny kararını verir. +Ajanları kimlik bilgilerini içeriğe veya çıktıya sızdırmaktan durdurun. Sanitizer ilkeleri **PostToolUse** olaylarında etkinleşir. Claude bir Bash komutu çalıştırdığında, bir dosya okuduğunda veya herhangi bir araç çağırdığında, bu ilkeler Claude'a döndürülmeden önce çıktıyı inceler. Bir sır deseni algılanırsa, ilke çıktının geri dönmesini önleyen bir reddet kararı döndürür. ### `sanitize-jwt` -**Etkinlik:** PostToolUse (tüm araçlar) -**Varsayılan:** JWT belirteçlerini (`.` ile ayrılmış üç base64url parçası) redakte eder. +**Olay:** PostToolUse (tüm araçlar) +**Varsayılan:** JWT belirteçlerini (`.` ile ayrılmış üç base64url segmenti) gizler. Parametre yok. @@ -342,14 +342,14 @@ Parametre yok. ### `sanitize-api-keys` -**Etkinlik:** PostToolUse (tüm araçlar) -**Varsayılan:** Yaygın API anahtar biçimlerini redakte eder: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT'leri (`ghp_`), AWS erişim anahtarları (`AKIA`), Stripe anahtarları (`sk_live_`, `sk_test_`) ve Google API anahtarları (`AIza`). +**Olay:** PostToolUse (tüm araçlar) +**Varsayılan:** Yaygın API anahtarı biçimlerini gizler: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`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 işlenecek ek regex desenleri. | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Sır olarak işlenecek ek regex desenleri. | **Örnek:** @@ -358,8 +358,8 @@ Parametre yok. "policyParams": { "sanitize-api-keys": { "additionalPatterns": [ - { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo iç API anahtarı" }, - { "regex": "pat_[0-9a-f]{40}", "label": "İç PAT" } + { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo dahili API anahtarı" }, + { "regex": "pat_[0-9a-f]{40}", "label": "Dahili PAT" } ] } } @@ -370,8 +370,8 @@ Parametre yok. ### `sanitize-connection-strings` -**Etkinlik:** PostToolUse (tüm araçlar) -**Varsayılan:** Gömülü kimlik bilgileri içeren veritabanı bağlantı dizelerini redakte eder (örneğin `postgresql://user:password@host/db`). +**Olay:** PostToolUse (tüm araçlar) +**Varsayılan:** Katıştırılmış kimlik bilgileri içeren veritabanı bağlantı dizelerini gizler (örn. `postgresql://user:password@host/db`). Parametre yok. @@ -379,8 +379,8 @@ Parametre yok. ### `sanitize-private-key-content` -**Etkinlik:** PostToolUse (tüm araçlar) -**Varsayılan:** PEM bloklarını redakte eder (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` vb.). +**Olay:** PostToolUse (tüm araçlar) +**Varsayılan:** PEM bloklarını gizler (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, vb.). Parametre yok. @@ -388,8 +388,8 @@ Parametre yok. ### `sanitize-bearer-tokens` -**Etkinlik:** PostToolUse (tüm araçlar) -**Varsayılan:** `Authorization: Bearer ` başlıklarını redakte eder; burada belirteç 20 veya daha fazla karakterdir. +**Olay:** PostToolUse (tüm araçlar) +**Varsayılan:** `Authorization: Bearer ` başlıklarını gizler (belirteç 20 veya daha fazla karakterdir). Parametre yok. @@ -401,10 +401,10 @@ Hassas ortam yapılandırmasını ajanlar tarafından okunmaktan veya açığa ### `block-env-files` -**Etkinlik:** PreToolUse (Bash, Read) -**Varsayılan:** `.env` dosyalarını `cat .env` aracılığıyla, `.env` dosya yolu ile Read araç çağrıları vb. okumayı reddeder. +**Olay:** PreToolUse (Bash, Read) +**Varsayılan:** `.env` dosyalarının `cat .env`, `.env` dosya yolu ile Read araç çağrıları vb. aracılığıyla okunmasını reddeder. -`.envrc` veya diğer ortam-bitişik dosyaları engellemez — yalnızca tam olarak `.env` adlı dosyaları engeller. +`.envrc` veya diğer ortam ile ilgili dosyaları engellememez — yalnızca tam olarak `.env` adlı dosyaları. Parametre yok. @@ -412,8 +412,8 @@ Parametre yok. ### `protect-env-vars` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Ortam değişkenlerini yazan komutları reddeder: `printenv`, `env`, `echo $VAR`. +**Olay:** PreToolUse (Bash) +**Varsayılan:** Ortam değişkenlerini yazdıracak komutları reddeder: `printenv`, `env`, `echo $VAR`. Parametre yok. @@ -421,18 +421,18 @@ Parametre yok. ## Dosya erişimi -Ajanları proje sınırları içinde çalışmaya ve hassas dosyalarından uzak tutun. +Ajanları proje sınırları içinde çalışmak ve hassas dosyalardan uzak tutun. ### `block-read-outside-cwd` -**Etkinlik:** PreToolUse (Read, Bash) -**Varsayılan:** Proje kökünün dışındaki dosyaları okumayı reddeder. Sınır `CLAUDE_PROJECT_DIR` (Claude Code tarafından oturum başına bir kez ayarlanır) ve söz konusu değişken ayarlanmadığında oturum mevcut çalışma dizinine geri döner. Live `cwd` yerine proje kökünü kullanmak, Claude `cd` olsa bile sınırın istikrarlı kalmasını sağlar. +**Olay:** PreToolUse (Read, Bash) +**Varsayılan:** Proje kökü dışındaki dosyaları okumayı reddeder. Sınır `CLAUDE_PROJECT_DIR` (Claude Code tarafından oturum başına bir kez ayarlanır), bu değişken ayarlanmadığında oturumun geçerli çalışma dizinine geri döner. Canlı `cwd` yerine proje kökü kullanmak, Claude `cd` ile bir alt dizine gittikten sonra bile sınırın sabit kalması anlamına gelir. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `allowPaths` | `string[]` | `[]` | Proje kökünün dışında olsa da izin verilen mutlak yol önekleri. | +| `allowPaths` | `string[]` | `[]` | Proje kökü dışında olsa bile izin verilen mutlak yol önekleri. | **Örnek:** @@ -450,14 +450,14 @@ Ajanları proje sınırları içinde çalışmaya ve hassas dosyalarından uzak ### `block-secrets-write` -**Etkinlik:** PreToolUse (Write, Edit) -**Varsayılan:** Özel anahtarlar ve sertifikalar için yaygın olarak kullanılan dosyalara yazmayı reddeder: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. +**Olay:** PreToolUse (Write, Edit) +**Varsayılan:** Özel anahtarlar ve sertifikalar için yaygın olarak kullanılan dosyalara yazmaları reddeder: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `additionalPatterns` | `string[]` | `[]` | Engellenecek ek dosya adı desenleri (glob tarzı). | +| `additionalPatterns` | `string[]` | `[]` | Engellenecek ek dosya adı desenleri (glob stili). | **Örnek:** @@ -475,18 +475,18 @@ Ajanları proje sınırları içinde çalışmaya ve hassas dosyalarından uzak ## Git -Beklenmedik itişleri, kuvvetli itişleri ve geri alması zor olan dal hatalarını engelle. +Kazara push'ları, force-push'ları ve geri almayı zor kılan branch hatalarını önleyin. ### `block-push-master` -**Etkinlik:** PreToolUse (Bash) +**Olay:** PreToolUse (Bash) **Varsayılan:** `git push origin main` ve `git push origin master` komutlarını reddeder. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Doğrudan itilemiyen dal adları. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Doğrudan push yapılamayan branch adları. | **Örnek:** @@ -501,36 +501,36 @@ Beklenmedik itişleri, kuvvetli itişleri ve geri alması zor olan dal hataları ``` -Tüm dallara itişe izin vermek için (bu ilkeyi `enabledPolicies` öğesinden kaldırmadan etkili bir şekilde devre dışı bırakmak için), `protectedBranches: []` ayarlayın. +Tüm branchlara push yapılmasına izin vermek için (bu ilkeyi `enabledPolicies` komutundan kaldırmadan etkili bir şekilde devre dışı bırakmak), `protectedBranches: []` ayarlayın. --- ### `block-work-on-main` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** `main` veya `master` dallarına doğrudan geçmeyi reddeder. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `main` veya `master` üzerindeyken `git commit`, `git merge`, `git rebase` ve `git cherry-pick` komutlarını reddeder. Branch oluşturma ve değiştirme (`git checkout`, `git checkout -b`, `git switch`, `git switch -c`) etkilenmez. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `protectedBranches` | `string[]` | `["main", "master"]` | Doğrudan geçilemiyen dal adları. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Commit/merge/rebase/cherry-pick'in reddedildiği branch adları. | --- ### `block-force-push` -**Etkinlik:** PreToolUse (Bash) +**Olay:** PreToolUse (Bash) **Varsayılan:** `git push --force` ve `git push -f` komutlarını reddeder. -İlkeye özgü parametre yok. Alternatifleri önermek için çapraz kesme [`hint`](/tr/configuration#hint-cross-cutting) kullanın: +İlkeye özgü parametreler yok. Alternatifleri önerme için çapraz kesiş [`hint`](/tr/configuration#hint-cross-cutting) kullanın: ```json { "policyParams": { "block-force-push": { - "hint": "Geçerli HEAD'nizden yeni bir dal oluşturun (örneğin `git checkout -b `) ve bunun yerine onu itin." + "hint": "Geçerli HEAD'iniz ile yeni bir branch oluşturun (örn. `git checkout -b `) ve bunun yerine onu push edin." } } } @@ -540,8 +540,8 @@ Tüm dallara itişe izin vermek için (bu ilkeyi `enabledPolicies` öğesinden k ### `warn-git-amend` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Claude'u `git commit --amend` çalıştırırken dikkatli olması konusunda talimatlandırır. Komutu engelleme. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `git commit --amend` çalıştırırken Claude'u dikkatli olmaya yönlendirir. Komutu engellememez. Parametre yok. @@ -549,8 +549,8 @@ Parametre yok. ### `warn-git-stash-drop` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Claude'u `git stash drop` çalıştırmadan önce onay alması konusunda talimatlandırır. Komutu engelleme. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `git stash drop` çalıştırmadan önce Claude'u onay vermeye yönlendirir. Komutu engellememez. Parametre yok. @@ -558,8 +558,8 @@ Parametre yok. ### `warn-all-files-staged` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Claude'u `git add -A` veya `git add .` çalıştırdığında ne hazırlayıp hazırlamadığını incelemesi konusunda talimatlandırır. Komutu engelleme. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `git add -A` veya `git add .` çalıştırırken stage'lediğini gözden geçirmeye yönlendirir. Komutu engellememez. Parametre yok. @@ -567,12 +567,12 @@ Parametre yok. ## Veritabanı -Veritabanınıza karşı yürütülmeden önce yıkıcı SQL işlemlerini yakala. +Yıkıcı SQL işlemleri veritabanınızda çalıştırılmadan önce yakalayın. ### `warn-destructive-sql` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Claude'u `DROP TABLE`, `DROP DATABASE` veya `WHERE` yan tümcesi olmayan `DELETE` içeren SQL çalıştırmadan önce onay alması konusunda talimatlandırır. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `DROP TABLE`, `DROP DATABASE` veya `WHERE` yan tümcesi olmayan `DELETE` içeren SQL çalıştırmadan önce Claude'u onay vermeye yönlendirir. Parametre yok. @@ -580,8 +580,8 @@ Parametre yok. ### `warn-schema-alteration` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Claude'u `ALTER TABLE` deyimleri çalıştırmadan önce onay alması konusunda talimatlandırır. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `ALTER TABLE` deyimleri çalıştırmadan önce Claude'u onay vermeye yönlendirir. Parametre yok. @@ -589,18 +589,18 @@ Parametre yok. ## Uyarılar -Potansiyel olarak riskli ancak yıkıcı olmayan işlemler yapılmadan önce ajanları ekstra bağlam ile sağlayın. +Ajanları potansiyel olarak riskli ancak yıkıcı olmayan işlemlerden önce ek bağlam verin. ### `warn-large-file-write` -**Etkinlik:** PreToolUse (Write) -**Varsayılan:** Claude'u 1024 KB'tan büyük dosyalar yazmadan önce onay alması konusunda talimatlandırır. +**Olay:** PreToolUse (Write) +**Varsayılan:** 1024 KB'den büyük dosyalar yazmadan önce Claude'u onay vermeye yönlendirir. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `thresholdKb` | `number` | `1024` | Uyarı verilecek kilobytes cinsinden dosya boyutu eşiği. | +| `thresholdKb` | `number` | `1024` | Bir uyarının verildiği dosya boyutu eşiği (kilobayt). | **Örnek:** @@ -615,15 +615,15 @@ Potansiyel olarak riskli ancak yıkıcı olmayan işlemler yapılmadan önce aja ``` -Hook işleyicisi yüklerde 1 MB stdin sınırı uygular. Bu ilkeyi küçük içerikle test etmek için `thresholdKb` öğesini 1024'ten çok daha düşük bir değere ayarlayın. +Hook işleyici, yüklerde 1 MB stdin sınırını zorunlu kılar. Bu ilkeyi küçük içerikle test etmek için `thresholdKb` öğesini 1024'ün çok altında bir değere ayarlayın. --- ### `warn-package-publish` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Claude'u `npm publish` çalıştırmadan önce onay alması konusunda talimatlandırır. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `npm publish` çalıştırmadan önce Claude'u onay vermeye yönlendirir. Parametre yok. @@ -631,8 +631,8 @@ Parametre yok. ### `warn-background-process` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Claude'u `nohup`, `&`, `disown` veya `screen` aracılığıyla arka plan işlemleri başlatırken dikkatli olması konusunda talimatlandırır. +**Olay:** PreToolUse (Bash) +**Varsayılan:** `nohup`, `&`, `disown` veya `screen` aracılığıyla arka plan işlemleri başlatırken Claude'u dikkatli olmaya yönlendirir. Parametre yok. @@ -640,8 +640,8 @@ Parametre yok. ### `warn-global-package-install` -**Etkinlik:** PreToolUse (Bash) -**Varsayılan:** Claude'u `npm install -g`, `yarn global add` veya sanal ortam olmadan `pip install` çalıştırmadan önce onay alması konusunda talimatlandırır. +**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 yönlendirir. Parametre yok. @@ -653,15 +653,15 @@ Ajanın kullanmasına izin verilen paket yöneticisini zorunlu kılın. ### `prefer-package-manager` -**Etkinlik:** 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öneticiye yeniden yazması konusunda talimatlandırır. +**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 kullanacak şekilde 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 listede olmayan algılanan yöneticiler engellenir. Boş olduğunda, ilke hiçbir şey yapmaz. | -| `blocked` | string[] | `[]` | Yerleşik listenin ötesinde engellenen ek yönetici adları (örneğin `['pdm', 'pipx']`). | +| `allowed` | string[] | `[]` | İzin verilen paket yöneticisi adları. Bu listede olmayan algılanan yöneticiler engellenir. Boş olduğunda ilke bir no-op'tur. | +| `blocked` | string[] | `[]` | Yerleşik listeyi aşan engellencek ek yönetici adları (örn. `['pdm', 'pipx']`). | 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. @@ -679,33 +679,33 @@ Yerleşik engel listesi şunları kapsar: pip, pip3, npm, npx, yarn, pnpm, pnpx, } ``` -Bu yapılandırma ile `pip install flask` ve `pdm install flask` ikisi de reddedilir ve Claude'u bunun yerine `uv` veya `bun` kullanması konusunda talimatlandıran bir mesaj gönderilir. `uv pip install flask` gibi komutlar izin verilir çünkü `uv` izin listesindedir ve ilk olarak denetlenir. +Bu yapılandırma ile `pip install flask` ve `pdm install flask` her ikisi de Claude'a `uv` veya `bun` kullanmasını söyleyen bir iletiyle reddedilir. `uv` allowlist'te olduğu ve önce kontrol edildiği için `uv pip install flask` gibi komutlar izin verilir. --- ## AI davranışı -Ajanlar takılıp kaldığında veya beklenmedik şekilde davrandığında algılayın. +Ajanlar takıldığında veya beklenmedik davrandığında algıla. ### `warn-repeated-tool-calls` -**Etkinlik:** PreToolUse (tüm araçlar) -**Varsayılan:** Aynı araç aynı parametrelerle 3 veya daha fazla kez çağrıldığında Claude'u yeniden düşünmesi konusunda talimatlandırır — bu yaygın olarak ajanın bir döngüde sıkışmış olmasının işaretidir. +**Olay:** PreToolUse (tüm araçlar) +**Varsayılan:** Aynı araç, aynı parametrelerle 3 veya daha fazla kez çağrıldığında Claude'u yeniden düşünmeye yönlendirir — ajanın bir döngüye takıldığının yaygın bir işareti. Parametre yok. --- -## İş akışı +## İş Akışı -Disiplinli bir oturum sonu iş akışı uygula. Bu ilkeler **Stop** etkinliğinde tetiklenir ve her koşul karşılanana kadar Claude'un durdurmayı reddedeceğini reddeder. Bunlar doğal bir bağımlılık zinciri izler: commit → push → PR → CI. Bir ilke redde ettiyse, zincirdeki sonraki ilkeler atlanır (reddetme kısa devreler). +Disiplinli bir oturum sonlandırma iş akışını zorunlu kılın. Bu ilkeler **Stop** olayında etkinleşir ve her koşul karşılanana kadar Claude'un durmasını engeller. Doğal bir bağımlılık zincirine uyarlar: commit → push → PR → CI. Bir ilke inkar ederse, zincirdeki sonraki ilkeler atlanır (inkar kısa devreler). -Tüm iş akışı ilkeleri **başarısız açıkça**: gerekli araç mevcut değilse (örneğin `gh` yüklü değilse, git uzaklaması yoksa), ilke denetin neden atlandığını açıklayan bilgilendirici bir mesajla izin verir. +Tüm iş akışı ilkeleri **fail-open** (başarısız açık): gerekli araç kullanılamıyorsa (örn. `gh` kurulu değil, git remote yok), ilke, kontrol neden atlanıyor olduğunu açıklayan bilgilendirici bir iletiyle izin verir. ### `require-commit-before-stop` -**Etkinlik:** Stop -**Varsayılan:** İşlenmemiş değişiklikler (değiştirilmiş, hazırlanmış veya izlenmeyen dosyalar) olduğunda durdurmayı reddeder. Çalışma dizini temiz olduğunda bilgilendirici bir mesaj döndürür. +**Olay:** Stop +**Varsayılan:** İşlenmemiş değişiklikler olduğunda durmasını reddeder (değiştirilmiş, hazırlanan veya izlenmeyen dosyalar). Çalışma dizini temiz olduğunda bilgilendirici bir ileti döndürür. Parametre yok. @@ -713,14 +713,14 @@ Parametre yok. ### `require-push-before-stop` -**Etkinlik:** Stop -**Varsayılan:** İtilmemiş işlemler olduğunda veya geçerli dal uzaktan izleme dalına sahip olmadığında durdurmayı reddeder. Gerekirse izleme dalı oluşturmak için `git push -u` önerir. Yapılandırılmış uzak yoksa başarısız açıkça. +**Olay:** Stop +**Varsayılan:** Push edilmemiş taahhütler olduğunda veya geçerli branch'in uzak izleme branch'i olmadığında durmasını reddeder. Gerekirse `git push -u` kullanarak izleme branch'i oluşturmayı önerir. Remote yapılandırılmamışsa fail-open'ı. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `remote` | `string` | `"origin"` | İtileceği uzak ad. | +| `remote` | `string` | `"origin"` | Push yapılacak remote adı. | **Örnek:** @@ -738,50 +738,52 @@ Parametre yok. ### `require-pr-before-stop` -**Etkinlik:** Stop -**Varsayılan:** Geçerli dal için hiç pull request olmadığında veya mevcut PR birleştirilmeden kapatıldığında durdurmayı reddeder. Claude'u `gh pr create` ile PR oluşturması konusunda talimatlandırır. PR **birleştirildiğinde**, ilke izin verir (iş yayımlanmıştır) ve mesaj daldan çıkmayı önerir (`git checkout main && git pull`). +**Olay:** Stop +**Varsayılan:** Geçerli branch için bir pull request olmadığında veya mevcut PR birleştirilmeden kapatıldığında durmasını reddeder. `gh pr create` kullanarak PR oluşturmaya talimat verir. PR **birleştirildiğinde**, ilke izin verir (çalışma sevk edildi) ve ileti branch'ten uzak durma tavsiyesi verir (`git checkout main && git pull`). Parametre yok. -Bu ilke [GitHub CLI](https://cli.github.com/) (`gh`) yüklü ve kimlik doğrulaması yapılmış şekilde gereklidir. -Pull request'lere okuma erişimi için `repo` kapsamına sahip kişisel erişim belirteci ile `gh auth login` çalıştırın. `gh` yüklü değilse veya kimlik doğrulaması yapılmamışsa, ilke başarısız açıkça ve nedenini Claude'a bildirir. +Bu ilke [GitHub CLI](https://cli.github.com/) (`gh`) kurulu ve kimliği doğrulanmış olmasını gerektirir. +Pull requests'e 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 kimliği doğrulanmamışsa, ilke fail-open'ı ve nedeni Claude'a rapor eder. --- ### `require-no-conflicts-before-stop` -**Etkinlik:** Stop -**Varsayılan:** Geçerli dal taban dala temiz bir şekilde birleştirilemediğinde durdurmayı reddeder. İlke ilk olarak dal için GitHub'da açık bir PR olduğunu onaylar — yoksa, birleştirme hedefi yoktur, bu nedenle tüm ilke kısa devreler izin verir. Açık PR onaylandıktan sonra, iki bağımsız araştırma çalışır: +**Olay:** Stop +**Varsayılan:** Geçerli branch'in taban branch'e temiz bir şekilde birleştirilememesi durumunda durmasını reddeder. İlke ilk olarak branch için GitHub'da `OPEN` PR olduğunu doğrular — birleşme hedefi olmadığında, tüm ilke short-circuit'a sahip olur. Bir `OPEN` PR doğrulandıktan sonra, iki bağımsız araştırma çalışır: -1. **Yerel** — `git merge-tree --write-tree --name-only origin/ HEAD`. Çatışmada, reddetme mesajı çakışan dosyaları adlandırır, böylece Claude tam olarak neyi çözeceğini bilir. -2. **GitHub** — ön kontrol sırasında zaten alınan `gh pr view --json mergeable,state` sonucunu yeniden kullanır. Eski yerel `origin/` kaçıracağı çatışmaları yakalar (örneğin birisi son getirme'den bu yana `main` hakkında çakışan PR'yi yağmıştır). `CONFLICTING` sonucu reddeder. `UNKNOWN` sonuç da reddeder ve Claude'u durdurmayı yeniden deneme girişiminden önce ~10 saniye beklemesi ve yeniden kontrol etmesi konusunda talimatlandırır — bu, GitHub yeniden hesaplarken yanlış negatifi engeller. +1. **Yerel** — `git merge-tree --write-tree --name-only origin/ HEAD`. Çakışmada, inkar iletisi Claude'un tam olarak neyi çözeceğini bilmesi için çakışan dosyaları adlandırır. +2. **GitHub** — önceden ön denetimde alınan `gh pr view --json mergeable,state` sonucunu yeniden kullanır. Son yerel `origin/` kaçırabilecek çakışmaları yakalar (örn. biri son getirişten sonra `main` üzerine çakışan bir PR indi). `CONFLICTING` bir sonuç reddeder. `UNKNOWN` sonuç da reddeder ve Claude'u ~10 saniye bekleyip durmaya çalışmadan önce yeniden kontrol etmeye yönlendirir — bu GitHub yeniden hesaplarken yanlış negatifleri önler. -Şu durumlarda tamamen atlanır (izin verir): `gh` yüklü değildir, dal için PR yoktur, PR'nin 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 tabandan ileri hiç işlem olmadığında da başarısız açıkça — bu Katman 1 geçişleri izin vermeden önce yine de önbelleğe alınan PR birleştirilebilirliğini danışır. +Atlanır (izin verir): `gh` kurulu değil, branch için PR yok, PR'ın durumu `OPEN` değil (örn. `MERGED`, `CLOSED`), veya `gh pr view` ayrıştırılamayan çıktı döndürür. Ayrıca `origin/` yerel olarak eksikse veya tabandan daha ileride commit yoksa fail-open'ı — bu Katman 1 fall-through'ları izin vermeden önce önbelleğe alınan PR birleştirilebilirliğine danışır. **Parametreler:** | Param | Tür | Varsayılan | Açıklama | |-------|-----|-----------|---------| -| `baseBranch` | `string` | `"main"` | Çatışmalar için kontrol edilecek taban dal. | +| `baseBranch` | `string` | `"main"` | Çakışmaları kontrol etmek için taban branch. | -Bu ilke GitHub CLI (`gh`) gerektirir. İlke, herhangi bir çatışma araştırması çalıştırmadan önce açık bir PR'nin var olduğunu onaylamak için `gh pr view` kullanır — `gh` olmadan, ilke kısa devreler izin verir. Pull request'lere okuma erişimi için `repo` kapsamına sahip kişisel erişim belirteci ile `gh auth login` çalıştırın. +Bu ilke GitHub CLI (`gh`) gerektirir. İlke, herhangi bir çakışma araştırması çalıştırmadan önce `gh pr view` kullanarak bir `OPEN` PR'ın mevcut olduğunu doğrular — `gh` olmadan ilke short-circuit'a sahip olur ve izin verir. Pull requests'e okuma erişimi için `repo` kapsamına sahip kişisel erişim belirteci ile `gh auth login` çalıştırın. --- ### `require-ci-green-before-stop` -**Etkinlik:** Stop -**Varsayılan:** Geçerli dal üzerinde CI kontrolleri başarısız oluyorsa veya hala çalışıyorsa durdurmayı reddeder. GitHub Actions iş akışı çalıştırmaları ve üçüncü taraf bot kontrolleri (örneğin CodeRabbit, SonarCloud, Codecov) kontrol eder. `skipped` ve `cancelled` sonuçlarını başarı olarak değerlendirir. Tüm kontroller geçtiğinde bilgilendirici bir mesaj döndürür. +**Olay:** Stop +**Varsayılan:** Geçerli branch'de CI kontrolleri başarısız olduğunda veya çalıştığında durmasını reddeder. GitHub Actions iş akışı çalıştırmalarını ve üçüncü taraf bot kontrolleri (örn. CodeRabbit, SonarCloud, Codecov) kontrol eder. `skipped` ve `cancelled` sonuçlarını başarı olarak değerlendirir. Tüm kontroller başarılı olduğunda bilgilendirici bir ileti döndürür. Parametre yok. -Bu ilke [GitHub CLI](https://cli.github.com/) (`gh`) yüklü ve kimlik doğrulaması yapılmış şekilde gereklidir. -Actions iş akışı çalıştırmalarına ve Checks 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` yüklü değilse veya kimlik doğrulaması yapılmamışsa, ilke başarısız açıkça ve nedenini Claude'a bildirir. +Bu ilke [GitHub CLI](https://cli.github.com/) (`gh`) kurulu ve kimliği doğrulanmış olmasını gerektirir. +Actions iş akışı çalıştırmalarına ve Checks API'ye 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 kimliği doğrulanmamışsa, ilke fail-open'ı ve nedeni Claude'a rapor eder. --- @@ -790,7 +792,7 @@ Actions iş akışı çalıştırmalarına ve Checks API'sine okuma erişimi iç ## Bireysel ilkeleri devre dışı bırakma -Yapılandırmanızda `enabledPolicies` öğesinden belirli bir ilkeyi kaldırın veya pano Politikalar sekmesinde kapatın. +Yapılandırmadaki `enabledPolicies` komutundan belirli bir ilkeyi kaldırın veya panonun İlkeler sekmesinde kapatın. ```json { @@ -801,4 +803,4 @@ Yapılandırmanızda `enabledPolicies` öğesinden belirli bir ilkeyi kaldırın } ``` -`enabledPolicies` içinde listelenmemiş ilkeler, `policyParams` girdileri olsa bile çalışmaz. \ No newline at end of file +`enabledPolicies` içinde listelenmemiş ilkeler çalışmaz, `policyParams` girdileri olsa bile. \ No newline at end of file diff --git a/docs/tr/configuration.mdx b/docs/tr/configuration.mdx index ffea7b46..d090985e 100644 --- a/docs/tr/configuration.mdx +++ b/docs/tr/configuration.mdx @@ -1,36 +1,35 @@ --- ---- -title: Konfigürasyon -description: "Yapılandırma dosyası biçimi, üç kapsam sistemi ve birleştirme kuralları" +title: Yapılandırma +description: "Yapılandırma dosyası biçimi, üç kapsamlı sistem ve birleştirme kuralları" icon: gear --- -failproofai, hangi ilkelerin aktif olduğunu, nasıl davrandığını ve özel ilkelerin nereden yüklendiğini kontrol etmek için JSON yapılandırma dosyalarını kullanır. Konfigürasyon, takımınızla paylaşımı kolaylaştıracak şekilde tasarlanmıştır - bunu repo'nuza yükleyin ve her geliştirici aynı aracı güvenlik ağını alır. +failproofai, hangi ilkelerin etkin olduğunu, nasıl davrandıklarını ve özel ilkelerin nereden yükleneceğini kontrol etmek için JSON yapılandırma dosyalarını kullanır. Yapılandırma, takımınızla paylaşmaya uygun şekilde tasarlanmıştır - bunu repoya kaydedin ve her geliştirici aynı aracı güvenlik ağını alır. --- -## Konfigürasyon kapsamları +## Yapılandırma kapsamları -Üç yapılandırma kapsamı vardır ve öncelik sırasıyla değerlendirilir: +Üç 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 kaydedilir | -| **local** | `.failproofai/policies-config.local.json` | Kişisel repo başına geçersiz kılmalar, gitignored | +| **proje** | `.failproofai/policies-config.json` | Repoya özel ayarlar, sürüm kontrol altında | +| **yerel** | `.failproofai/policies-config.local.json` | Kişisel repoya özel geçersiz kılmalar, gitignored | | **global** | `~/.failproofai/policies-config.json` | Tüm projeler arasında kullanıcı düzeyinde varsayılanlar | -failproofai bir hook olayı aldığında, geçerli çalışma dizini için mevcut olan üç dosyayı da yükler ve birleştirir. +failproofai bir hook olayı aldığında, geçerli çalışma dizini için var olan üç dosyayı da yükler ve birleştirir. ### Birleştirme kuralları -**`enabledPolicies`** - üç kapsamın birleşimi. Herhangi bir düzeyde etkinleştirilen bir ilke etkindir. +**`enabledPolicies`** - üç kapsamın tümünün birleşimi. Herhangi bir düzeyde etkinleştirilen ilke aktiftir. ```text project: ["block-sudo"] local: ["block-rm-rf"] global: ["block-sudo", "sanitize-api-keys"] -resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← tekrar olmayan birleşim +resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← yinelenenden arındırılmış birleşim ``` **`policyParams`** - belirli bir ilke için parametreleri tanımlayan ilk kapsam tamamen kazanır. Bir ilkenin parametreleri içinde derin birleştirme yoktur. @@ -39,7 +38,7 @@ resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"] ← tekrar olmayan project: block-sudo → { allowPatterns: ["sudo apt-get update"] } global: block-sudo → { allowPatterns: ["sudo systemctl status"] } -resolved: { allowPatterns: ["sudo apt-get update"] } ← project kazanır, global yoksayılır +resolved: { allowPatterns: ["sudo apt-get update"] } ← proje kazanır, global yoksayılır ``` ```text @@ -97,31 +96,31 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← global'e düşer --- -## Alan referansı +## Alan başvurusu ### `enabledPolicies` Tür: `string[]` -Etkinleştirilecek ilke adlarının listesi. Adlar `failproofai policies` tarafından gösterilen ilke tanımlayıcılarıyla tam olarak eşleşmelidir. Tam liste için bkz. [Built-in Policies](/tr/built-in-policies). +Etkinleştirilecek ilke adlarının listesi. Adlar, `failproofai policies` tarafından gösterilen ilke tanımlayıcılarıyla tam olarak eşleşmelidir. Tam liste için bkz. [Yerleşik İlkeler](/tr/built-in-policies). -`enabledPolicies` içinde olmayan ilkeler, `policyParams`'de girdileri olsa bile etkin değildir. +`enabledPolicies` listesinde olmayan ilkeler inaktiftir; `policyParams` içinde girdileri olsa bile. ### `policyParams` Tür: `Record>` -İlke başına parametre geçersiz kılmaları. Dış anahtar ilke adıdır; iç anahtarlar ilkeye özgüdür. Her ilke, [Built-in Policies](/tr/built-in-policies) bölümünde kullanılabilir parametrelerini belgelendirir. +İlkeye özel parametre geçersiz kılmaları. Dış anahtar ilke adıdır; iç anahtarlar ilkeye özgüdür. Her ilke, [Yerleşik İlkeler](/tr/built-in-policies) kısmında mevcut parametrelerini belgelemeleri. -Bir ilkenin parametreleri varsa ancak bunları belirtmezseniz, ilkenin yerleşik varsayılanları kullanılır. `policyParams`'i hiç yapılandırmayan kullanıcılar önceki sürümlerle aynı davranışı alır. +Bir ilkenin parametreleri varsa ancak bunları belirtmezseniz, ilkenin yerleşik varsayılanları kullanılır. `policyParams` yapılandırmayan kullanıcılar önceki sürümlerle aynı davranışı alırlar. -Bir ilkenin params bloğunun içindeki bilinmeyen anahtarlar, hook tetiklenme sırasında sessizce yoksayılır ancak `failproofai policies` çalıştırdığınızda uyarılar olarak işaretlenir. +Bir ilkenin parametre bloğu içindeki bilinmeyen anahtarlar, hook ateşlenme zamanında sessizce yoksayılır ancak `failproofai policies` çalıştırdığınızda uyarı olarak işaretlenir. -#### `hint` (cross-cutting) +#### `hint` (çapraz kesme) Tür: `string` (isteğe bağlı) -Bir ilke `deny` veya `instruct` döndürdüğünde nedene eklenen bir mesaj. İlkenin kendisini değiştirmeden Claude'a eyleme geçirilebilir rehberlik vermek için bunu kullanın. +Bir ilke `deny` veya `instruct` döndürdüğünde nedene eklenen bir ileti. Claude'a ilkeyi değiştirmeden uygulanabilir rehberlik sağlamak için kullanın. Herhangi bir ilke türüyle çalışır — yerleşik, özel (`custom/`), proje kuralı (`.failproofai-project/`) veya kullanıcı kuralı (`.failproofai-user/`). @@ -129,53 +128,53 @@ Herhangi bir ilke türüyle çalışır — yerleşik, özel (`custom/`), proje { "policyParams": { "block-force-push": { - "hint": "Bunun yerine yeni bir branch oluşturmayı deneyin." + "hint": "Bunun yerine yeni bir dal oluşturmayı deneyin." }, "block-sudo": { "allowPatterns": ["sudo apt-get"], - "hint": "Sudo olmadan doğrudan apt-get kullanın." + "hint": "sudo olmadan doğrudan apt-get kullanın." }, "custom/my-policy": { - "hint": "Önce kullanıcıdan onay isteyin." + "hint": "Önce kullanıcıdan onay isteyiniz." } } } ``` -`block-force-push` reddettiğinde, Claude şunu görür: *"Force-pushing bloklandı. Bunun yerine yeni bir branch oluşturmayı deneyin."* +`block-force-push` reddettiğinde Claude şunu görür: *"Force-push engellendi. Bunun yerine yeni bir dal oluşturmayı deneyin."* -String olmayan değerler ve boş stringler sessizce yoksayılır. `hint` ayarlanmadıysa davranış değişmez (geriye dönük uyumlu). +Dize olmayan değerler ve boş dizeler sessizce yoksayılır. `hint` ayarlanmamışsa, davranış değişmez (geriye dönük uyumlu). ### `customPoliciesPath` Tür: `string` (mutlak yol) -Özel hook ilkeleri 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 ilkelerini içeren JavaScript dosyasının yolu. Bu, `failproofai policies --install --custom ` tarafından otomatik olarak ayarlanır (yol depolanmadan önce mutlak olarak çözümlenir). -Dosya her hook olayında yeniden yüklenir - önbellekleme yoktur. Yazım ayrıntıları için bkz. [Custom Policies](/tr/custom-policies). +Dosya her hook olayında yeniden yüklenir - önbelleğe alma yoktur. Yazarlık ayrıntıları için bkz. [Özel İlkeler](/tr/custom-policies). ### Kurala dayalı ilkeler -Açık `customPoliciesPath`'in yanı sıra, failproofai `.failproofai/policies/` dizinlerinden ilke dosyalarını otomatik olarak keşfeder ve yükler: +Açık `customPoliciesPath`'e ek olarak, failproofai `.failproofai/policies/` dizinlerinden ilke dosyalarını otomatik olarak bulur ve yükler: | Düzey | Dizin | Kapsam | |-------|-----------|-------| -| Project | `.failproofai/policies/` | Sürüm kontrolü aracılığıyla takımla paylaşılır | -| User | `~/.failproofai/policies/` | Kişisel, tüm projelere uygulanır | +| Proje | `.failproofai/policies/` | Sürüm kontrolü aracılığıyla takımla paylaşıldı | +| Kullanıcı | `~/.failproofai/policies/` | Kişisel, tüm projeler için geçerlidir | -**Dosya eşleştirmesi:** Yalnızca `*policies.{js,mjs,ts}` eşleşen dosyalar yüklenir (örn. `security-policies.mjs`, `workflow-policies.js`). Dizindeki diğer dosyalar yoksayılır. +**Dosya eşleştirmesi:** Yalnızca `*policies.{js,mjs,ts}` ile eşleşen dosyalar yüklenir (örneğin `security-policies.mjs`, `workflow-policies.js`). Dizindeki diğer dosyalar yoksayılır. -**Yapılandırma gerekli değil:** Kural ilkeleri `policies-config.json`'de giriş gerektirmez. Dosyaları dizine bırakın ve sonraki hook olayında alınırlar. +**Yapılandırma gerekmez:** Kurala dayalı ilkeler `policies-config.json` içinde giriş gerektirmez. Dosyaları dizine bırakın ve bunlar sonraki hook olayında alınır. -**Birleşim yükleme:** Hem proje hem de kullanıcı kural dizinleri taranır. Her iki düzeydeki tüm eşleşen dosyalar yüklenir (`customPoliciesPath`'in ilk kapsam kazanır kuralından farklı olarak). +**Birleşim yüklemesi:** Hem proje hem de kullanıcı kurala dayalı dizinler taranır. Her iki düzeydeki tüm eşleşen dosyalar yüklenir (`customPoliciesPath` ilk kapsamı kazananı kullandığından farklı). -Daha fazla ayrıntı ve örnekler için bkz. [Custom Policies](/tr/custom-policies). +Daha fazla bilgi ve örnekler için bkz. [Özel İlkeler](/tr/custom-policies). ### `llm` Tür: `object` (isteğe bağlı) -AI çağrıları yapan ilkeler için LLM istemci konfigürasyonu. Çoğu kurulum için gerekli değildir. +AI çağrıları yapan ilkeler için LLM istemci yapılandırması. Çoğu kurulum için gerekli değildir. ```json { @@ -188,38 +187,46 @@ AI çağrıları yapan ilkeler için LLM istemci konfigürasyonu. Çoğu kurulum --- -## CLI'dan konfigürasyonu yönetme +## CLI'den yapılandırmayı yönetme -`policies --install` ve `policies --uninstall` komutları aracı CLI'nizin hook ayarları dosyasına yazarken (hook giriş noktaları), `policies-config.json` doğrudan yönettiğiniz dosyadır. İkisi ayrıdır: +`policies --install` ve `policies --uninstall` komutları aracının CLI'sinin hook ayarları dosyasına (hook giriş noktaları) yazarken, `policies-config.json` doğrudan yönettiğiniz dosyadır. İkisi ayrıdır: -- **Aracı CLI ayarları** — aracıya her tool kullanımında `failproofai --hook ` çağrısını söyler: +- **Aracı CLI ayarları** — aracıya her araç kullanımında `failproofai --hook ` çağırmasını söyler: - **Claude Code**: `~/.claude/settings.json` (kullanıcı), `/.claude/settings.json` (proje), `/.claude/settings.local.json` (yerel) - - **OpenAI Codex**: `~/.codex/hooks.json` (kullanıcı), `/.codex/hooks.json` (proje) — Codex'in `local` kapsamı yoktur - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (kullanıcı), `/.github/hooks/failproofai.json` (proje) — Copilot'un `local` kapsamı yoktur. Hook girdileri Copilot'un işletim sistemi anahtarlı `bash`/`powershell` komut alanlarını `timeoutSec` ile kullanır; dosya üst düzey `version: 1` işaretleyicisini taşır. Copilot CLI desteği, `events.jsonl` kayıt şemasını (genel doklar belirtmez) daha fazla gerçek dünya oturumuna karşı doğruladığımız için **beta**'dır. -- **`policies-config.json`** — failproofai'ye hangi ilkeleri değerlendireceğini ve hangi parametrelerle kullanacağını söyler (tüm aracı CLI'leri arasında paylaşılır) + - **OpenAI Codex**: `~/.codex/hooks.json` (kullanıcı), `/.codex/hooks.json` (proje) — Codex'in yerel kapsamı yoktur + - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (kullanıcı), `/.github/hooks/failproofai.json` (proje) — Copilot'un yerel kapsamı yoktur. Hook girdileri Copilot'un işletim sistemi anahtarlı `bash`/`powershell` komut alanlarını `timeoutSec` ile kullanır; dosya üst düzey `version: 1` işaretçisi taşır. Copilot CLI desteği **beta** olup `events.jsonl` kayıt şemasını (halka açık belgeler belirtmez) daha fazla gerçek oturuma karşı doğrulamaktadır. + - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (kullanıcı), `/.cursor/hooks.json` (proje) — Cursor'un yerel kapsamı yoktur. Hook girdileri Claude şeklinde `{type, command, timeout}` formunu kullanır (`bash`/`powershell` bölümü yoktur), ancak Cursor'un [hooks şeması](https://cursor.com/docs/hooks) başına camelCase olay anahtarları (`preToolUse`, `beforeSubmitPrompt`, …) altında düz bir diz içinde depolanır; dosya üst düzey `version: 1` işaretçisi taşır. İşleyici `CURSOR_EVENT_MAP` aracılığıyla camelCase → PascalCase'i kurallılaştırır; böylece mevcut yerleşik ilkeler değişmeden ateşlenir. Cursor Agent desteği **beta** olup Cursor'un diskete yazma transkriptini (halka açık belgelerde belirtilmez) daha fazla gerçek kuruluma karşı doğrulamaktadır. + - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (kullanıcı), `/.opencode/opencode.json` + `/.opencode/plugins/failproofai.mjs` (proje) — OpenCode'un yerel kapsamı yoktur. Diğer dört CLI'den farklı olarak, OpenCode **harici komut hook sistemine sahip değildir**: `opencode.json` içindeki `plugin: []` dizisi aracılığıyla açıkça kaydedilen işlem içi JS/TS eklentilerini yükler (`.opencode/plugins/` uyumdan otomatik bulma **OpenCode v1.14.33'te eklentilerin nasıl yükleneceği değildir**). Kurulum, failproofai ikili dosyasını alt işlem çağıran ve ikili dosyanın Claude şeklinde JSON yanıtını eklenti semantiğine geri çeviren küçük bir oluşturulan eklenti dolgusu bırakır (`deny` için `throw new Error()`, `instruct` için `client.session.prompt(...)`, `allow` için no-op). Oturumlar OpenCode'un SQLite VT'de `~/.local/share/opencode/opencode.db` bulunur; pano oturum görüntüleyeni bunları `opencode db --format json` ve `opencode export ` aracılığıyla okur. OpenCode desteği **beta** olup davranışı sürümler arasında ve daha fazla gerçek oturuma karşı doğrulamaktadır. Bkz. [OpenCode eklentileri belgelemeleri](https://opencode.ai/docs/plugins/). + - **Pi _(beta)_**: `~/.pi/agent/settings.json` (kullanıcı), `/.pi/settings.json` (proje) — Pi'nin yerel kapsamı yoktur. Pi başlangıçta TypeScript uzantı paketlerini yükler; ayarlar dosyası düz bir dize dizisidir `{"packages": ["./relative/path", …]}`. failproofai bundled `pi-extension/` dizinini işaret eden tek bir packages-array girdisi yazar. Uzantı dahili olarak Pi'nin `tool_call` / `user_bash` / `input` / `session_start` etkinliklerine abone olur ve `failproofai --hook --cli pi` çalıştırır; işleyici `PI_EVENT_MAP` aracılığıyla underscore_lower_snake_case → PascalCase'i kurallılaştırır; böylece mevcut yerleşik ilkeler değişmeden ateşlenir. Pi desteği **beta** olup Pi'nin uzantı API'si ve oturum günlüğü düzeni stabilize olunca. + - **Gemini CLI _(beta)_**: `~/.gemini/settings.json` (kullanıcı), `/.gemini/settings.json` (proje) — Gemini'nin yerel kapsamı yoktur (varsayılan olarak `matcher: "*"` ile Gemini'nin `{matcher, hooks: [...]}` eşleştirici şeması içine sarmalanmış Claude'ün `{type, command, timeout}` formunu kullanır). Etkinlikler 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şler. Araç adları snake_case'tir (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — işleyici `GEMINI_TOOL_MAP` aracılığıyla kurallılaştırır; böylece mevcut yerleşik ilkeler değişmeden ateşlenir. İlke değerlendiricisi Gemini'nin düz `{decision: "deny", reason}` şeklini (Gemini'nin "Golden Rule" exit-0 sözleşmesine göre tercih edilir), BeforeAgent / AfterTool / SessionStart üzerinde bağlam enjeksiyonu için `{hookSpecificOutput: {hookEventName, additionalContext}}` ve AfterAgent üzerinde `{decision: "block", reason}` yayınlar (force-retry semantiği için). Gemini CLI desteği **beta** olup gerçek dünya kapsamını genişletirken. Bkz. [Gemini CLI hooks belgelemeleri](https://geminicli.com/docs/hooks/). +- **`policies-config.json`** — failproofai'ye hangi ilkeleri değerlendireceğini ve hangi parametrelerle yapacağını söyler (tüm aracı CLI'ları arasında paylaşılır) -Belirli bir aracıyı hedeflemek için `--cli claude|codex|copilot` geçin (boşlukla ayrılmış veya herhangi bir alt küme için tekrarlanır): +Belirli bir aracıyı hedeflemek için `--cli claude|codex|copilot|cursor|opencode|pi|gemini` geçirin (boşlukla ayrılmış veya herhangi bir alt küme için tekrarlanan): ```bash failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project -failproofai policies --install --cli claude codex copilot +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 claude codex copilot cursor opencode pi gemini ``` -`--cli` atlandığında, `failproofai` hangi aracı CLI'lerinin kurulu olduğunu tespit eder (`which claude` / `which codex` / `which copilot`): +`--cli` atlanırsa, `failproofai` hangi aracı CLI'larının yüklü olduğunu algılar (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): -- **Bir CLI tespit edildi** — onay istenmeden otomatik olarak o CLI'yi seçer. -- **Birden fazla CLI tespit edildi** etkileşimli bir terminalde — ok tuşu tek seçimli istemini gösterir: iki CLI mevcut olduğunda seçenekler `Both`, ` only`, ` only` şeklindedir; üç CLI ile ilk seçenek `All` olur (↑↓ hareket etmek için, seçmek için Enter, çıkmak için ^C). -- **Birden fazla CLI tespit edildi** etkileşimsiz bir çalıştırmada (CI, TTY yok) — onay istenmeden tespit edilen tüm CLI'ler için yükler. -- **Hiçbiri tespit edilmedi** — uyarı ile `claude`'a döner; aracı ikili PATH'de bulunamadı; hook komutu yine de yazılır, böylece biri kurulur kurulmaz etkinleşir. +- **Bir CLI algılandı** — sormadan o CLI'yı otomatik seçer. +- **Etkileşimli terminalde birden fazla CLI algılandı** — gruplandırılmış bir `Detected (N)` bölümü (bir `Install for all N detected` toplam satırı + algılanan her CLI ayrı ayrı) ve desteklenen tüm algılanmamış CLI'yı ileriye dönük kurulum seçeneği olarak listeleyen bir `Not installed (M) · install hooks ahead of time` bölümü gösteren ok tuşu tek seçim istemini gösterir (↑↓ hareket, Enter seç, ^C çık). Kaldır akışı yalnızca Algılanan bölümü gösterir. +- **Etkileşimli olmayan çalıştırmada birden fazla CLI algılandı** (CI, TTY yok) — sormadan algılanan tüm CLI'lar için kurar. +- **Hiçbiri algılanmadı** — `claude`'a geri düşer, PATH'te aracı ikili dosyasının bulunamadığı uyarısı; hook komutu yine de yazılır; böylece bir tane kurduğunuz anda etkinleşir. -`policies-config.json`'yi herhangi bir zamanda doğrudan düzenleyebilirsiniz; değişiklikler yeniden başlatma gerekmeksizin sonraki hook olayında etkinleşir. +İstediğiniz zaman `policies-config.json` doğrudan düzenleyebilirsiniz; değişiklikler yeniden başlatmaya gerek kalmadan sonraki hook olayında hemen etkinleşir. --- ## Örnek: takım varsayılanlarıyla proje düzeyinde yapılandırma -`.failproofai/policies-config.json`'i repo'nuza yükleyin: +Repoya `.failproofai/policies-config.json` kaydedin: ```json { @@ -238,4 +245,4 @@ failproofai policies --install --cli claude codex copilot } ``` -Her geliştirici daha sonra `.failproofai/policies-config.local.json` (gitignored) oluşturabilir ve takım arkadaşlarını etkilemeden kişisel geçersiz kılmalar yapabilir. \ No newline at end of file +Her geliştirici daha sonra `.failproofai/policies-config.local.json` (gitignored) oluşturabilir; takım arkadaşlarını etkilemeden kişisel geçersiz kılmalar için. \ No newline at end of file diff --git a/docs/tr/dashboard.mdx b/docs/tr/dashboard.mdx index 62c37993..19767f4e 100644 --- a/docs/tr/dashboard.mdx +++ b/docs/tr/dashboard.mdx @@ -1,10 +1,10 @@ --- title: Dashboard -description: "Aracı oturumlarını izleyin, araç çağrılarını gözden geçirin ve politikaları yönetin" +description: "Agent oturumlarını izleyin, araç çağrılarını gözden geçirin ve politikaları yönetin" icon: chart-line --- -failproofai dashboard, AI aracı oturumlarınızı izlemek ve politikaları yönetmek için yerel bir web uygulamasıdır. Aracılarınız siz uzaktayken neler yaptığını görün. +failproofai dashboard, AI agent oturumlarınızı izlemek ve politikaları yönetmek için yerel bir web uygulamasıdır. Agenlerinizin uzakta iken neler yaptığını görün. --- @@ -16,7 +16,7 @@ failproofai `http://localhost:8020` adresinde açılır. -Dashboard doğrudan dosya sisteminden okur - Claude Code proje klasörleriniz ve failproofai yapılandırma dosyalarınız. Hiçbir şey uzak bir servise yazılmaz. +Dashboard dosya sisteminden doğrudan okur - Claude Code proje klasörleriniz ve failproofai yapılandırma dosyalarınız. Hiçbir şey uzak bir hizmete yazılmaz. --- @@ -24,11 +24,11 @@ Dashboard doğrudan dosya sisteminden okur - Claude Code proje klasörleriniz ve ### Projeler -Makinenizde bulunan tüm Claude Code, OpenAI Codex ve GitHub Copilot CLI _(beta)_ projelerini listeler. Claude projeleri `~/.claude/projects/` konumundan keşfedilir (veya `CLAUDE_PROJECTS_PATH` tarafından ayarlanan yol); Codex projeleri `~/.codex/sessions///
/*.jsonl` altındaki tüm transkriptleri tarayarak ve her oturumun ilk kaydında kayıtlı `cwd` ile gruplayarak keşfedilir; Copilot CLI projeleri her `~/.copilot/session-state//workspace.yaml` dosyasını tarayarak (`COPILOT_HOME` aracılığıyla yapılandırılabilir) ve `cwd` alanına göre gruplayarak keşfedilir. Birden fazla CLI tarafından kullanılan bir proje, tüm eşleşen rozetlerle tek bir satır olarak görüntülenir. Tablo üzerindeki **CLI** açılır menüsünü kullanarak belirli bir aracı CLI'ye göre filtreleyin; URL seçiminizi `?cli=claude|codex|copilot` olarak korur. +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/` (veya `CLAUDE_PROJECTS_PATH` tarafından ayarlanan yol) içinden keşfedilir; Codex projeleri `~/.codex/sessions///
/*.jsonl` altındaki her transkrip 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 (`COPILOT_HOME` aracılığıyla yapılandırılabilir) ve `cwd` alanına göre gruplandırılarak keşfedilir; Cursor Agent projeleri `~/.cursor/agent-sessions//` altındaki oturum başına metaveri taranarak (`CURSOR_HOME` aracılığıyla yapılandırılabilir, `conversations/` ve `sessions/` yedek olarak taranır) `meta.json` / `session.json` / `workspace.yaml` içinde `cwd` skaleri aranarak keşfedilir; OpenCode projeleri `~/.local/share/opencode/opencode.db` konumundaki SQLite DB'si sorgulayarak (`opencode db --format json` aracılığıyla) keşfedilir (`session` ve `project` tablolarını okur ve `project_id` ile gruplandırırız); Pi projeleri `~/.pi/agent/sessions//_.jsonl` altındaki oturum başına JSONL transkriptleri taranarak (`PI_SESSIONS_DIR` aracılığıyla yapılandırılabilir) ve her oturumun ilk kaydından `cwd` çekilerek keşfedilir; Gemini CLI projeleri `~/.gemini/tmp//chats/session--.jsonl` taranarak (`GEMINI_SESSIONS_DIR` aracılığıyla yapılandırılabilir) ve komşu `.project_root` metin işaretçisinden kanonik cwd kurtarılarak keşfedilir. Birden fazla CLI tarafından kullanılan bir proje, tüm eşleşen rozetlerle tek bir satır olarak görünür. Belirli bir agent CLI'ye göre filtrelemek için tablo üzerindeki **CLI** açılır menüsünü kullanın; URL seçiminizi `?cli=claude|codex|copilot|cursor|opencode|pi|gemini` olarak korumalıdır. Her proje şunları gösterir: - Proje adı (klasör yolundan türetilmiş) -- CLI rozeti — `Claude Code` (turuncu), `OpenAI Codex` (mor) ve/veya `GitHub Copilot` (mavi) +- Bir CLI rozeti — `Claude Code` (turuncu), `OpenAI Codex` (mor), `GitHub Copilot` (mavi), `Cursor Agent` (zümrüt), `OpenCode` (kehribar), `Pi` (pembe) ve/veya `Gemini CLI` (açık mavi) - En son oturum aktivitesinin tarihi Oturumlarını görmek için bir projeye tıklayın. @@ -36,26 +36,26 @@ Oturumlarını görmek için bir projeye tıklayın. ### Oturumlar Bir proje içindeki tüm oturumları listeler. Her oturum şunları gösterir: -- Oturum kimliği +- Oturum ID'si - Başlangıç ve bitiş zaman damgaları -- Araç çağrısı sayısı -- Hook aktivite sayısı (tetiklenen politikalar) +- Araç çağrılarının sayısı +- Hook aktivitesi sayısı (tetiklenen politikalar) -Listeyi daraltmak için tarih aralığı filtresini ve oturum kimliği aramasını kullanın. Oturumlar sayfalanmıştır. +Listeyi daraltmak için tarih aralığı filtresini ve oturum ID'si aramasını kullanın. Oturumlar sayfalandırılmıştır. Oturum görüntüleyicisini açmak için bir oturuma tıklayın. ### Oturum görüntüleyici -Oturum görüntüleyici, otonom aracılar için temel soruyu cevaplar: aracı ne yaptı ve yolu takip etti mi? Başlık yanındaki CLI rozeti oturumun Claude Code veya OpenAI Codex transkripti olup olmadığını gösterir. Bir oturumda meydana gelen her şeyin bir zaman çizelgesini gösterir: +Oturum görüntüleyici, otonom agenler için temel soruyu yanıtlar: agent ne yaptı ve yolunda mı kaldı? Başlık yanındaki bir CLI rozeti, oturumun Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi veya Gemini CLI transkripti olup olmadığını gösterir. Oturumda meydana gelen her şeyin bir zaman çizelgesini gösterir: -- **Mesajlar** - Claude'un metin yanıtları ve kullanıcı istemleri -- **Araç çağrıları** - Claude'un çağırdığı her araç, girdisi ve çıktısı ile -- **Politika aktivitesi** - Her araç çağrısı için hangi politikaların tetiklendiği ve hangi kararı döndürdüğü +- **Mesajlar** - Claude'un metin yanıtları ve kullanıcı komutları +- **Araç çağrıları** - Claude'un çağırdığı her araç, girdisi ve çıktısı ile birlikte +- **Politika aktivitesi** - Her araç çağrısı için hangi politikaların tetiklendiği ve hangi kararı döndürdükleri -Üstteki istatistik çubuğu oturum süresini, toplam araç çağrısını ve kanca kararlarının (izin ver / reddet / talimatlı sayıları) özetini gösterir. +Üstteki istatistik çubuğu oturum süresini, toplam araç çağrılarını ve kanca kararlarının bir özetini (izin ver / reddet / instruct sayıları) gösterir. -İndirme düğmesini kullanarak oturumu ZIP veya JSONL dosyası olarak dışa aktarabilirsiniz. +Oturumu dışa aktarmak için **Download Logs** düğmesine tıklayın. Claude Code, Codex, Copilot, Cursor, Pi ve Gemini oturumları için byte-for-byte orijinal disk üstü JSONL transkriptini alırsınız; OpenCode oturumları için (oturumları diskte değil SQLite'de yaşayan) alttaki `session` / `messages` / `parts` tablolarını yansıtan bir JSON belgesi alırsınız. ### Politikalar @@ -63,16 +63,16 @@ Politikaları yönetmek ve aktiviteyi gözden geçirmek için iki sekmeli bir sa - - Tek bir tıklamayla bireysel politikaları açıp kapatın (`~/.failproofai/policies-config.json` dosyasına yazılır) - - Bir politikanın parametrelerini yapılandırmak için genişletin (`policyParams` destekleyen politikalar için) + - Tek tıklamayla bireysel politikaları açın veya kapatın (`~/.failproofai/policies-config.json` dosyasına yazılır) + - Parametrelerini yapılandırmak için bir politikayı genişletin (`policyParams` destekleyen politikalar için) - Belirli bir kapsam için kancaları kurun veya kaldırın - - Özel politikalar dosyası yolu ayarlayın + - Özel bir politika dosyası yolu ayarlayın - - Tüm oturumlar genelinde tetiklenen her kanca olayının tam sayfalanmış geçmişi - - Kararına, olay türüne, CLI'ye (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_), politika adına 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), araç adı, oturum kimliği ve reddet/talimatlı kararlarının nedeni - - Transkriptini açmak için bir oturum kimliğine tıklayın — görüntüleyici kancayı tetikleyen CLI'yi otomatik olarak algılar (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`) ve başlıkta eşleşen CLI rozetini görüntüler + - Tüm oturumlar arasında tetiklenen her hook etkinliğinin 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 ID'si ile 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, açık mavi = Gemini CLI), araç adı, oturum ID'si ve reddet/instruct kararlarının nedeni + - Transkripi açmak için bir oturum ID'sine tıklayın — görüntüleyici hangi CLI'nin kancayı tetiklediğini otomatik olarak algılar (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.jsonl`, Cursor Agent `~/.cursor/agent-sessions//events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions//.jsonl`, Gemini CLI `~/.gemini/tmp//chats/.jsonl`) ve başlıkta eşleşen CLI rozetini gösterir @@ -80,13 +80,13 @@ Politikaları yönetmek ve aktiviteyi gözden geçirmek için iki sekmeli bir sa ## Otomatik yenileme -Dashboard üst gezintide otomatik yenileme değiştiricisine sahiptir. Etkinleştirildiğinde, geçerli sayfa yeni oturumlar ve politika aktiviteleri göründüğünde periyodik olarak yenilenir. Uzun süren otonom aracı oturumlarını izlemek için gereklidir. +Dashboard üst gezintide bir otomatik yenileme açılır/kapanır düğmesine sahiptir. Etkinleştirildiğinde, mevcut sayfa yeni oturumları ve politika aktivitelerini göstermek için periyodik olarak yenilenir. Uzun süreli otonom agent 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` değerini virgülle ayrılmış bir sayfa adları listesine ayarlayın: +Yalnızca dashboard'un bazı bölümlerine ihtiyacınız varsa, `FAILPROOFAI_DISABLE_PAGES` değerini virgülle ayrılmış bir sayfa adları listesine ayarlayın: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai @@ -98,13 +98,13 @@ Geçerli değerler: `policies`, `projects`. ## Tema -Dashboard açık ve koyu modu destekler. Gezinti çubuğundaki düğmeyle geçiş yapın. Tercih, tarayıcınızın yerel depolama alanında saklanır. +Dashboard açık ve koyu modu destekler. Gezinti çubuğundaki düğme ile değiştirin. Tercih tarayıcınızın yerel depolamasında saklanır. --- -## Projeler yolunu yapılandırma +## Proje yolunu yapılandırma -Varsayılan olarak, dashboard standart Claude Code projeleri dizininden okur. Özel kurulumlar için bunu geçersiz kılın: +Varsayılan olarak, dashboard standart Claude Code projeler dizininden okur. Özel kurulumlar için geçersiz kılın: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -112,32 +112,32 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai --- -## localhost olmayan bir konaktan erişim +## Localhost olmayan bir ana bilgisayardan erişme -Dashboard'u **dev modunda** (`npm run dev`) çalıştırırken ve `localhost` dışında bir ana bilgisayar adından (örneğin özel bir alan, uzak bir IP veya tünel harita URL'si) erişirken şöyle bir uyarı görebilirsiniz: +Dashboard'u **dev modunda** (`npm run dev`) çalıştırırken ve `localhost` dışında bir ana bilgisayar adından erişirken - örneğin, özel bir alan adı, uzak bir IP veya tünellenmiş bir URL - şu gibi 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 (hot module reload) websocket'ine çapraz kaynaklı erişimi engellemesidir; bu yalnızca geliştirme özelliğidir. Konağınıza izin vermek için `--allowed-origins` bayrağını kullanın: +Bu, Next.js'nin HMR (sıcak modül yeniden yükleme) WebSocket'ine çapraz kaynaklı erişimi engellemesidir ve bu bir dev-only özelliğidir. Ana bilgisayarı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 geçirin: +Birden fazla ana bilgisayar veya IP için, virgülle ayrılmış bir liste iletin: ```bash npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5 ``` -Bunun yerine `FAILPROOFAI_ALLOWED_DEV_ORIGINS` ortam değişkenini de ayarlayabilirsiniz: +Bunun yerine `FAILPROOFAI_ALLOWED_DEV_ORIGINS` ortam değişkenini ayarlayabilirsiniz: ```bash FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev ``` -Bu yalnızca dev modu için geçerlidir. `failproofai` (üretim modu) çalıştırırken HMR websocket'i ve çapraz kaynaklı dev kaynağı sorunu yoktur. +Bu yalnızca dev moduna uygulanır. `failproofai` (üretim modu) çalıştırılırken, HMR WebSocket'i yoktur ve çapraz kaynaklı dev kaynağı sorunu yoktur. \ No newline at end of file diff --git a/docs/tr/getting-started.mdx b/docs/tr/getting-started.mdx index 28f7e2c6..0db3bb32 100644 --- a/docs/tr/getting-started.mdx +++ b/docs/tr/getting-started.mdx @@ -1,13 +1,13 @@ --- -title: Başlangıç -description: "failproofai'ı kurun, politikaları etkinleştirin ve agenplerinizin güvenilir şekilde çalışmasını sağlayın" +title: Başlarken +description: "failproofai'ı kurun, ilkeleri etkinleştirin ve ajanlarınızın güvenilir bir şekilde çalışmasını sağlayın" icon: rocket --- ## Gereksinimler - **Node.js** >= 20.9.0 -- **Bun** >= 1.3.0 (isteğe bağlı - sadece kaynaktan derleme için gerekli) +- **Bun** >= 1.3.0 (isteğe bağlı - yalnızca kaynaktan derlemek için gereklidir) --- @@ -30,21 +30,25 @@ bun add -g failproofai ## Hızlı başlangıç - - Politikalar, her agent araç çağrısından önce ve sonra çalışan kurallardır. Hasar vermeden önce yıkıcı komutları, gizli dağılımı ve diğer hata modlarını yakalarlar. + + İlkeler, her ajan araç çağrısından önce ve sonra çalışan kurallardır. Bunlar, yıkıcı komutları, gizli dizi sızıntılarını ve diğer hata modlarını hasar vermeden önce yakalarlar. ```bash failproofai policies --install ``` - Bu, yüklü agent CLI'lerinize hook girişleri yazar (Claude Code'un `~/.claude/settings.json`, OpenAI Codex'in `~/.codex/hooks.json` veya GitHub Copilot CLI'nin `~/.copilot/hooks/failproofai.json` dosyasına). Birden fazlası mevcut olduğunda size istenir; istemi atlamak için `--cli claude codex copilot` (herhangi bir alt küme) geçirin. + Bu, yüklü ajan CLI'lerinize kanca 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'in `~/.cursor/hooks.json`, OpenCode'un `~/.config/opencode/plugins/failproofai.mjs` adresindeki oluşturulan eklenti dolgusunu artı `~/.config/opencode/opencode.json` içindeki `plugin` dizisine bir kayıt girişini, Pi'nin `~/.pi/agent/settings.json` veya Gemini CLI'nin `~/.gemini/settings.json`). Birden fazla olması durumunda sorunuza soracaktır; istemi atlamak için `--cli claude codex copilot cursor opencode pi gemini` (herhangi bir alt küme) geçirin. - GitHub Copilot CLI desteği **beta** sürümündedir — `--cli copilot` ile kurun. + 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. ```bash failproofai policies --install --scope project failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project + 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 block-sudo block-rm-rf sanitize-api-keys ``` @@ -53,56 +57,56 @@ bun add -g failproofai failproofai policies ``` - Her politikayi, etkin olup olmadığını ve yapılandırılan parametreleri gösterir. + Her ilkeyi, etkin olup olmadığını ve yapılandırılan parametreleri gösterir. - + ```bash failproofai ``` - `http://localhost:8020` adresinde yerel bir kontrol paneli açar; burada oturumları tarayabilir, araç çağrılarını inceleyebilir ve politikaları yönetebilirsiniz. + `http://localhost:8020` adresinde yerel bir pano açar; burada oturumları göz atabilir, araç çağrılarını inceleyebilir ve ilkeleri yönetebilirsiniz. - - Claude Code'u her zamanki gibi başlatın. Agent riskli birşey yapmaya çalışırsa, failproofai bunu otomatik olarak engeller. Bunu çalışır halde bırakın ve kontrol panelinde ne olduğunu gözden geçirin. + + Claude Code'u her zamanki gibi başlatın. Ajan riskli bir şey yapmaya çalışırsa, failproofai bunu otomatik olarak engeller. Bunu çalışır halde bırakın ve panoda ne olduğunu gözden geçirin. --- -## Politikalar nasıl çalışır +## İlkeler nasıl çalışır? -Agent her bir araçı çalıştırdığında, Claude Code failproofai'ı bir alt işlem olarak çağırır: +Her ajan bir araç ç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 - politikaları değerlendirir - stdout'a karar yazar + ilkeleri değerlendirir + kararı stdout'a yazar ``` -Her politika üç karardan birini döndürür: +Her ilke üç karardan birini döndürür: -- **allow** - agent normal şekilde devam eder -- **deny** - işlem engellenir, agente neden olduğu söylenir -- **instruct** - agent'ın isteme ek bağlam eklenir +- **allow** - ajan normal olarak devam eder +- **deny** - işlem engellenir, ajan nedenini söylenir +- **instruct** - ajanın komutuna ek bağlam eklenir -Politikalar yerel işleminizde çalışır. Hiçbir şey uzak bir hizmete gönderilmez. +İlkeler yerel işleminizde çalışır. Uzak bir hizmete hiçbir şey gönderilmez. --- -## Kural tabanlı politikalarla takım politikaları kurun +## Kural tabanlı ilkelerle takım ilkelerini ayarlayın -Takımınız genelinde kalite standartlarını belirlemenin en hızlı yolu `.failproofai/policies/` kuralıdır. Politika dosyalarını bu dizine bırakın ve otomatik olarak yüklenir — hiç bayrak, hiç yapılandırma değişikliği, hiç kurulum komutu yok. +Takımınız genelinde kalite standartları oluşturmanın en hızlı yolu `.failproofai/policies/` kuralıdır. İlke dosyalarını bu dizine bırakın ve bunlar otomatik olarak yüklenir — hiçbir bayrak, hiçbir yapılandırma değişikliği, hiçbir kurulum komutu yok. - + ```bash mkdir -p .failproofai/policies ``` - - Başlangıç örneklerini kopyalayın veya kendi olanlarınızı yazın: + + Başlangıç örneklerini kopyalayın veya kendi örneğinizi yazın: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -120,39 +124,39 @@ Takımınız genelinde kalite standartlarını belirlemenin en hızlı yolu `.fa fn: async (ctx) => { if (ctx.toolName !== "Bash") return allow(); if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) { - return instruct("Commit etmeden önce testleri çalıştırın."); + return instruct("Yapılandırmadan önce testleri çalıştırın."); } return allow(); }, }); ``` - + ```bash git add .failproofai/policies/ - git commit -m "Takım kalite politikaları ekle" + git commit -m "Takım kalite ilkeleri ekle" ``` - failproofai yüklü olan her takım üyesi bu politikaları otomatik olarak alır. Geliştirici başına kurulum gerekli değildir. + failproofai yüklenmiş olan her takım üyesi bu ilkeleri otomatik olarak alır. Geliştirici başına kurulum gerekmez. -`.failproofai/policies/` dosyasını repunuza commit edin, 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` sırasında güncellemeleri alır. Zaman içinde bu politikalar, sürekli geliştirilen yaşayan bir kalite standardı haline gelir. +`.failproofai/policies/` dosyasını repo'nuzda yapılandırın, böylece tüm takım aynı standartları paylaşır. Takımınız yeni hata modlarını keşfettikçe, ilkeler ekleyin ve yükleyin — herkes bir sonraki `git pull` ile güncellemeleri alır. Zamanla bu ilkeler, gelişmeye devam eden ve iyileşen bir yaşayan kalite standardı haline gelir. --- ## Veri depolama -Tüm yapılandırma ve loglar makinenizde kalır: +Tüm yapılandırma ve günlükler makinenizde kalır: -| Yol | Depolanan şey | +| Yol | Ne depolandığı | |------|----------------| -| `~/.failproofai/policies-config.json` | Global politika yapılandırması | -| `~/.failproofai/hook-activity.jsonl` | Hook yürütme geçmişi | -| `~/.failproofai/hook.log` | Özel hook hataları için hata ayıklama logu | -| `.failproofai/policies-config.json` | Proje başına yapılandırma (commit edilmiş) | +| `~/.failproofai/policies-config.json` | Genel ilke yapılandırması | +| `~/.failproofai/hook-activity.jsonl` | Kanca yürütme geçmişi | +| `~/.failproofai/hook.log` | Özel kanca hataları için hata ayıklama günlüğü | +| `.failproofai/policies-config.json` | Proje başına yapılandırma (yapılandırılmış) | | `.failproofai/policies-config.local.json` | Kişisel geçersiz kılmalar (gitignored) | --- @@ -163,7 +167,7 @@ Tüm yapılandırma ve loglar makinenizde kalır: failproofai policies --uninstall ``` -`~/.claude/settings.json` dosyasından hook girişlerini kaldırır. `~/.failproofai/` içindeki yapılandırma dosyaları tutulur. +`~/.claude/settings.json` dosyasından kanca girişlerini kaldırır. `~/.failproofai/` içindeki yapılandırma dosyaları tutulur. --- @@ -172,19 +176,19 @@ failproofai policies --uninstall - Kapsamlar ve yapılandırma dosyası biçimi + Kapsamlar ve yapılandırma dosyası formatı - - Tüm 26 politika ve parametreleri + + 26 ilkenin tümü parametrelerle - - JavaScript'te kendi politikalarınızı yazın + + JavaScript'te kendi ilkelerinizi yazın - - Oturumları izleyin ve politika aktivitesini gözden geçirin + + Oturumları izleyin ve ilke etkinliğini gözden geçirin \ No newline at end of file diff --git a/docs/vi/architecture.mdx b/docs/vi/architecture.mdx index d0e6b1ad..a2384954 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ộ" +description: "Cách hook handler, config loading và policy evaluation hoạt động bên trong" icon: sitemap --- -Tài liệu này giải thích cách failproofai hoạt động nội bộ: cách hook system chặn các tool call của agent, cách configuration được load và merge, cách policies được đánh giá, và cách dashboard giám sát hoạt động của agent. +Tài liệu này giải thích cách failproofai hoạt động bên trong: cách hệ thống hook chặn các tool call của agent, cách configuration được tải và merge, cách policies đượ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 subsystem độc lập: -1. **Hook handler** - Một subprocess CLI nhanh mà Claude Code gọi trên mỗi agent tool call. Đánh giá policies và trả về quyết định. -2. **Agent Monitor (Dashboard)** - Một ứng dụng web Next.js để giám sát các agent session và quản lý policies. +1. **Hook handler** - Một CLI subprocess nhanh mà Claude Code gọi trên mỗi agent tool call. Đánh giá policies và trả lại một quyết định. +2. **Agent Monitor (Dashboard)** - Một Next.js web application để giám sát agent sessions và quản lý policies. -Cả hai subsystem chia sẻ các file cấu hình trong `~/.failproofai/` và thư mục `.failproofai/` của project, nhưng chúng chạy như các process riêng biệt và chỉ giao tiếp thông qua filesystem. +Cả hai subsystem đều chia sẻ các tệp cấu hình trong `~/.failproofai/` và thư mục `.failproofai/` của project, nhưng chúng chạy dưới dạng các process riêng biệt và chỉ giao tiếp qua filesystem. --- @@ -25,7 +24,7 @@ Cả hai subsystem chia sẻ các file cấu hình trong `~/.failproofai/` và t ### Tích hợp với Claude Code -Khi bạn chạy `failproofai policies --install`, nó sẽ ghi các entry như sau vào `~/.claude/settings.json`: +Khi bạn chạy `failproofai policies --install`, nó sẽ ghi các entry như thế này vào `~/.claude/settings.json`: ```json { @@ -46,9 +45,9 @@ Khi bạn chạy `failproofai policies --install`, nó sẽ ghi các entry như } ``` -Claude Code sau đó gọi `failproofai --hook PreToolUse` như một subprocess trước mỗi tool call, truyền một JSON payload trên stdin. +Claude Code sau đó gọi `failproofai --hook PreToolUse` như một subprocess trước mỗi tool call, chuyển một JSON payload qua stdin. -### Định dạng payload +### Định dạng Payload ```json { @@ -64,9 +63,9 @@ Claude Code sau đó gọi `failproofai --hook PreToolUse` như một subprocess Đối với `PostToolUse` events, payload cũng chứa `tool_result` với output của tool. -Handler enforces giới hạn stdin 1 MB. Các payload vượt quá giới hạn này được loại bỏ và tất cả policies implicit cho phép. +Handler thực thi giới hạn 1 MB cho stdin. Những payload vượt quá giới hạn này sẽ bị loại bỏ và tất cả policies sẽ ngầm cho phép. -### Định dạng response +### Định dạng Response **Deny (PreToolUse):** ```json @@ -98,15 +97,15 @@ Handler enforces giới hạn stdin 1 MB. Các payload vượt quá giới hạn **Stop event instruct:** - Exit code: `2` -- Lý do được ghi vào stderr (không phải stdout) +- Reason được ghi vào stderr (không phải stdout) **Allow:** - Exit code: `0` -- Stdout trống +- Stdout trống rỗng -**Allow với message:** +**Allow with message:** -`allow(message)` cho phép một policy gửi informational context trở lại Claude ngay cả khi operation được phép. Hook handler ghi JSON sau vào **stdout** (không phải config file — đây là handler's response tới Claude Code, giống như deny và instruct responses ở trên): +`allow(message)` cho phép một policy gửi contextual information trở lại Claude ngay cả khi operation được cho phép. Hook handler ghi JSON sau đây vào **stdout** (không phải một file cấu hình — đây là response của handler tới Claude Code, giống như deny và instruct responses ở trên): ```json // Written to stdout by the hook handler process @@ -116,13 +115,13 @@ Handler enforces giới hạn stdin 1 MB. Các payload vượt quá giới hạn } } ``` -- Exit code: `0` (operation được phép) -- Khi nhiều policies trả về `allow` với một message, các messages của chúng được join với newlines thành một single `additionalContext` string -- Nếu không có policy nào cung cấp message, stdout trống (giống như trước) +- Exit code: `0` (operation được cho phép) +- Khi nhiều policies trả về `allow` với một message, các messages của chúng được join lại bằng newlines thành một chuỗi `additionalContext` duy nhất +- Nếu không có policy nào cung cấp message, stdout trống rỗng (giống như trước) ### Processing pipeline -`src/hooks/handler.ts` implements toàn bộ pipeline: +`src/hooks/handler.ts` thực hiện toàn bộ pipeline: ```text stdin JSON @@ -141,13 +140,13 @@ stdin JSON → exit ``` -Toàn bộ process chạy dưới 100ms cho các typical payloads mà không có LLM calls. +Toàn bộ process chạy dưới 100ms cho typical payloads mà không có LLM calls. --- ## Configuration loading -`src/hooks/hooks-config.ts` implements three-scope config loading. +`src/hooks/hooks-config.ts` thực hiện three-scope config loading. ```text [1] {cwd}/.failproofai/policies-config.json ← project (highest priority) @@ -156,10 +155,10 @@ Toàn bộ process chạy dưới 100ms cho các typical payloads mà không có ``` Merge logic: -- `enabledPolicies` - deduplicated union across all three files -- `policyParams` - per-policy key, first file that defines it wins entirely -- `customPoliciesPath` - first file that defines it wins -- `llm` - first file that defines it wins +- `enabledPolicies` - deduplicated union trên cả ba files +- `policyParams` - per-policy key, file đầu tiên định nghĩa nó sẽ thắng hoàn toàn +- `customPoliciesPath` - file đầu tiên định nghĩa nó sẽ thắng +- `llm` - file đầu tiên định nghĩa nó sẽ thắng Web dashboard sử dụng `readHooksConfig()` (global only) để đọc và ghi, vì nó không được gọi với project cwd. @@ -169,26 +168,26 @@ Web dashboard sử dụng `readHooksConfig()` (global only) để đọc và ghi `src/hooks/policy-evaluator.ts` chạy policies theo thứ tự. -Với mỗi policy: +Cho mỗi policy: -1. Look up policy's `params` schema (nếu nó có). +1. Tra cứu schema `params` của policy (nếu nó có). 2. Đọc `policyParams[policy.name]` từ merged config. -3. Merge user-provided values over schema defaults để tạo `ctx.params`. +3. Merge user-provided values trên schema defaults để tạo ra `ctx.params`. 4. Gọi `policy.fn(ctx)` với resolved context. -5. Nếu result là `deny`, dừng ngay lập tức và trả về quyết định đó. -6. Nếu result là `instruct`, accumulate message và tiếp tục. -7. Nếu result là `allow`, tiếp tục tới policy tiếp theo. +5. Nếu kết quả là `deny`, dừng ngay lập tức và trả lại quyết định đó. +6. Nếu kết quả là `instruct`, tích lũy message và tiếp tục. +7. Nếu kết quả là `allow`, tiếp tục tới policy tiếp theo. Sau khi tất cả policies chạy: -- Nếu bất kỳ `deny` nào được trả về, emit deny response. -- Nếu bất kỳ `instruct` returns nào được collected, emit một single instruct response với tất cả messages được join. -- Ngoài ra, emit một allow response (empty stdout, exit 0). +- Nếu bất kỳ `deny` nào được trả về, phát emit deny response. +- Nếu bất kỳ `instruct` returns nào được thu thập, phát emit một single instruct response với tất cả messages được join lại. +- Ngược lại, phát emit một allow response (empty stdout, exit 0). --- ## Builtin policies -`src/hooks/builtin-policies.ts` định nghĩa tất cả 26 built-in policies như `BuiltinPolicyDefinition` objects: +`src/hooks/builtin-policies.ts` định nghĩa tất cả 26 built-in policies như các `BuiltinPolicyDefinition` objects: ```typescript interface BuiltinPolicyDefinition { @@ -206,15 +205,15 @@ interface BuiltinPolicyDefinition { } ``` -Các policies chấp nhận `params` khai báo một `PolicyParamsSchema` với types và defaults cho mỗi parameter. Policy evaluator injects resolved values vào `ctx.params` trước khi gọi `fn`. Policy functions đọc `ctx.params` mà không cần null-guarding vì defaults luôn được applied trước. +Policies chấp nhận `params` khai báo một `PolicyParamsSchema` với types và defaults cho mỗi parameter. Policy evaluator inject resolved values vào `ctx.params` trước khi gọi `fn`. Policy functions đọc `ctx.params` mà không cần null-guarding vì defaults luôn được áp dụng trước. -Pattern matching bên trong policies sử dụng parsed command tokens (argv), không phải raw string matching. Điều này ngăn chặn bypass thông qua shell operator injection (ví dụ: một pattern cho `sudo systemctl status *` không thể bypass bằng cách append `; rm -rf /` vào command). +Pattern matching bên trong policies sử dụng parsed command tokens (argv), không phải raw string matching. Điều này ngăn chặn bypass qua shell operator injection (ví dụ: pattern cho `sudo systemctl status *` không thể bị bypass bằng cách thêm `; rm -rf /` vào command). --- ## Custom policies -`src/hooks/custom-hooks-registry.ts` implements một `globalThis`-backed registry: +`src/hooks/custom-hooks-registry.ts` thực hiện một `globalThis`-backed registry: ```typescript const REGISTRY_KEY = "__failproofai_custom_hooks__"; @@ -227,25 +226,25 @@ export function getCustomHooks(): CustomHook[] { ... } export function clearCustomHooks(): void { ... } // used in tests ``` -`src/hooks/custom-hooks-loader.ts` load user's policy file: +`src/hooks/custom-hooks-loader.ts` tải file policy của user: -1. Đọc `customPoliciesPath` từ config; skip nếu absent. -2. Resolve tới absolute path; check file exists. -3. Rewrite tất cả `from "failproofai"` imports tới actual dist path để `customPolicies` resolve tới cùng `globalThis` registry. -4. Recursively rewrite transitive local imports để ensure ESM compatibility. -5. Write temporary `.mjs` files và `import()` entry file. +1. Đọc `customPoliciesPath` từ config; bỏ qua nếu không có. +2. Resolve thành absolute path; check file tồn tại. +3. Rewrite tất cả `from "failproofai"` imports sang actual dist path để `customPolicies` resolve tới cùng `globalThis` registry. +4. Recursively rewrite transitive local imports để đảm bảo ESM compatibility. +5. Ghi temporary `.mjs` files và `import()` entry file. 6. Gọi `getCustomHooks()` để retrieve registered hooks. 7. Clean up tất cả temp files trong một `finally` block. Trên bất kỳ error nào (file not found, syntax error, import failure), error được logged tới `~/.failproofai/hook.log` và loader trả về một empty array. Built-in policies không bị ảnh hưởng. -Custom policies được đánh giá sau tất cả built-in policies. Một custom policy `deny` vẫn short-circuits further custom policies (nhưng tất cả built-ins đã chạy rồi ở điểm đó). +Custom policies được đánh giá sau tất cả built-in policies. Một custom policy `deny` vẫn short-circuits các custom policies khác (nhưng tất cả built-ins đã chạy rồi ở điểm này). --- ## Activity logging -Sau mỗi hook event, handler appends một JSONL line tới `~/.failproofai/hook-activity.jsonl`: +Sau mỗi hook event, handler append một JSONL line tới `~/.failproofai/hook-activity.jsonl`: ```json { @@ -260,7 +259,7 @@ Sau mỗi hook event, handler appends một JSONL line tới `~/.failproofai/hoo } ``` -Một line cho mỗi policy mà có một non-allow decision. Allow decisions không được logged (để giữ file nhỏ). +Một line cho mỗi policy mà đưa ra quyết định non-allow. Allow decisions không được logged (để giữ file nhỏ gọn). --- @@ -283,21 +282,21 @@ app/ get-hook-activity.ts ← Paginate/search activity log install-hooks-web.ts ← Install/remove hooks from the browser api/ - download/[project]/[session]/route.ts ← Export session as ZIP/JSONL + download/[project]/[session]/route.ts ← Per-CLI session export (JSONL or JSON) ``` **Data flow:** -- Page components gọi `lib/projects.ts` và `lib/log-entries.ts` để đọc project/session data trực tiếp từ filesystem (không API layer cho reads). +- Page components gọi `lib/projects.ts` và `lib/log-entries.ts` để đọc project/session data trực tiếp từ filesystem (không có API layer cho reads). - Policies page sử dụng Server Actions cho tất cả mutations (toggle, params update, install/remove). - Session viewer parse Claude's JSONL transcript format và render một timeline của messages và tool calls. **Key design decisions:** -- Không database - tất cả persistent state nằm trong plain files (`~/.failproofai/`, `~/.claude/projects/`). +- Không có database - tất cả persistent state nằm trong plain files (`~/.failproofai/`, `~/.claude/projects/`). - Server Actions cho mutations - không cần REST API cho CRUD operations. - React Server Components cho read pages - faster initial load, không client bundle cho data fetching. -- Client components chỉ ở nơi cần interactivity (policy toggles, activity search, log viewer). +- Client components chỉ khi cần interactivity (policy toggles, activity search, log viewer). --- diff --git a/docs/vi/built-in-policies.mdx b/docs/vi/built-in-policies.mdx index a5a39dfb..5a67f2ad 100644 --- a/docs/vi/built-in-policies.mdx +++ b/docs/vi/built-in-policies.mdx @@ -1,10 +1,10 @@ --- -title: Chính sách Built-in -description: "Tất cả 39 chính sách built-in có thể bắt được các lỗi agent phổ biến" +title: 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 chế độ lỗi phổ biến của agent" icon: shield --- -failproofai được cung cấp với 39 chính sách built-in có thể bắt được các lỗi agent phổ biến. Mỗi chính sách kích hoạt trên một loại sự kiện hook và tên công cụ cụ thể. 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 code. Năm chính sách workflow thực thi quy trình commit → push → PR → CI trước khi Claude dừng lại. +failproofai được cung cấp với 39 chính sách tích hợp sẵn để bắt các chế độ lỗi phổ biến của agent. Mỗi chính sách 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 code. Năm chính sách quy trình làm việc thực thi một pipeline commit → push → PR → CI trước khi Claude dừng. --- @@ -23,21 +23,17 @@ Các chính sách được nhóm thành các danh mục: | [Cơ sở dữ liệu](#cơ-sở-dữ-liệu) | warn-destructive-sql, warn-schema-alteration | PreToolUse | | [Cảnh báo](#cảnh-báo) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse | | [Trình quản lý gói](#trình-quản-lý-gói) | 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 | +| [Quy trình làm việc](#quy-trình-làm-việc) | 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 tiếp tục. -- **`warn-`** — cung cấp ngữ cảnh bổ sung để agent có thể tự sửa chữa. -- **`sanitize-`** — làm sạch 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 từ tiếp tục thực hiện. +- **`warn-`** — cung cấp cho agent bối cảnh bổ sung để nó có thể tự điều chỉnh. +- **`sanitize-`** — xóa sạch dữ liệu nhạy cảm từ output công cụ trước khi agent nhìn thấy. ### Không gian tên -Mỗi chính sách nằm trong một slot `/`. Các chính sách built-in thuộc về -không gian tên **`exospherehost/`** — ví dụ: `exospherehost/sanitize-jwt`. Không gian tên -ngăn chặn các 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 -với các tên ngắn tương tự. +Mỗi chính sách nằm trong một slot `/`. Các chính sách tích hợp sẵn thuộc về không gian tên **`exospherehost/`** — ví dụ: `exospherehost/sanitize-jwt`. Không gian tên này 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 với các tên ngắn tương tự. -Trong cấu hình của bạn, bạn có thể tham chiếu đến một built-in bằng tên ngắn hoặc tên -đủ điều kiện; cả hai dạng giải quyết cùng một chính sách: +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 đủ; cả hai dạng đều phân giải thành cùng một chính sách: ```json { @@ -48,35 +44,33 @@ Trong cấu hình của bạn, bạn có thể tham chiếu đến một built-i } ``` -Nếu một tên không có `/`, failproofai coi nó thuộc về không gian tên mặc định -`exospherehost`. 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. +Nếu một tên không có `/`, failproofai coi nó thuộc không gian tên mặc định `exospherehost`. 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 đ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 code chính sách. Hoạt động với chính sách built-in, tùy chỉnh và convention. Xem [Configuration → hint](/vi/configuration#hint-cross-cutting) để biết chi tiết. +Mọi chính sách đều hỗ trợ 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 hành động mà không cần sửa đổi code chính sách. Hoạt động với chính sách tích hợp sẵn, tùy chỉnh và quy ước. Xem [Cấu hình → hint](/vi/configuration#hint-cross-cutting) để biết chi tiết. --- ## Lệnh nguy hiểm -Ngăn chặn các agent chạy các thao tác khó được hoàn tác hoặc có thể làm hỏng hệ thống chủ. +Ngăn chặn các 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ủ. ### `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 bao gồm từ khóa `sudo`. Việc so 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òng qua bằng cách tiêm toán tử shell. +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 bỏ qua qua lỗi nhúng 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 cú pháp. | +| `allowPatterns` | `string[]` | `[]` | Các tiền tố lệnh chính xác được cho 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ụ:** @@ -90,10 +84,10 @@ Chặn các lệnh gọi bao gồm từ khóa `sudo`. Việc so khớp mẫu đ } ``` -Với cấu hình này, `sudo systemctl status nginx` được cho phép, nhưng `sudo rm /etc/hosts` bị từ chối. +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 cú pháp, không phải chuỗi lệnh thô. Điều này ngăn chặn vòng qua bằng cách thêm toán tử shell (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 bỏ qua qua các toán tử shell được nối thêm (ví dụ: `sudo systemctl status x; rm -rf /` không khớp với `sudo systemctl status *`). --- @@ -101,7 +95,7 @@ Các mẫu được so khớp với các token được phân tích cú pháp, k ### `block-rm-rf` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối `rm -rf`, `rm -fr` và các hình thức xóa đệ quy tương tự. +**Mặc định:** Từ chối `rm -rf`, `rm -fr` và các dạng xóa đệ quy tương tự. **Tham số:** @@ -135,7 +129,7 @@ Không có tham số. ### `block-failproofai-commands` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối các lệnh sẽ gỡ cài đặt hoặc vô hiệu hóa chính failproofai (ví dụ: `npm uninstall failproofai`, `failproofai policies --uninstall`). +**Mặc định:** Từ chối các lệnh sẽ gỡ cài đặt hoặc tắt failproofai (ví dụ: `npm uninstall failproofai`, `failproofai policies --uninstall`). Không có tham số. @@ -143,9 +137,9 @@ Không có tham số. ## Lệnh Infra -Dừng các agent mã hóa chạy CLIs cơ sở hạ tầng hoặc kích hoạt các đườ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ệnh gọi của 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 các pipeline 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 cần hợp pháp để 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ệnh gọi của 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 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ự đặc biệt shell nhúng bị từ chối trước khi so khớp danh sách cho phép để ngăn chặn các bypass tiêm. +Ngữ pháp mẫu giống với [`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ó các ký tự siêu dữ liệu shell được nhúng đều bị từ chối trước khi so khớp danh sách cho phép để ngăn chặn bỏ qua lỗi. ### `block-kubectl` @@ -156,7 +150,7 @@ Ngữ pháp mẫu giống như [`block-sudo`](#block-sudo): các token được | Tham số | Loại | Mặc định | Mô tả | |--------|------|---------|-------| -| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh kubectl được phép. | +| `allowPatterns` | `string[]` | `[]` | Các tiền tố lệnh kubectl được cho phép. | **Ví dụ:** @@ -170,7 +164,7 @@ Ngữ pháp mẫu giống như [`block-sudo`](#block-sudo): các token được } ``` -Với cấu hình này, `kubectl get pods` được cho phép nhưng `kubectl apply -f deploy.yaml` bị từ chối. +Với cấu hình này, `kubectl get pods` được phép nhưng `kubectl apply -f deploy.yaml` bị từ chối. --- @@ -183,7 +177,7 @@ Với cấu hình này, `kubectl get pods` được cho phép nhưng `kubectl ap | Tham số | Loại | Mặc định | Mô tả | |--------|------|---------|-------| -| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh terraform/tofu được phép. | +| `allowPatterns` | `string[]` | `[]` | Các tiền tố lệnh terraform/tofu được cho phép. | **Ví dụ:** @@ -208,7 +202,7 @@ Với cấu hình này, `kubectl get pods` được cho phép nhưng `kubectl ap | Tham số | Loại | Mặc định | Mô tả | |--------|------|---------|-------| -| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh aws CLI được phép. | +| `allowPatterns` | `string[]` | `[]` | Các tiền tố lệnh CLI aws được cho phép. | **Ví dụ:** @@ -233,7 +227,7 @@ Với cấu hình này, `kubectl get pods` được cho phép nhưng `kubectl ap | Tham số | Loại | Mặc định | Mô tả | |--------|------|---------|-------| -| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh gcloud được phép. | +| `allowPatterns` | `string[]` | `[]` | Các tiền tố lệnh gcloud được cho phép. | **Ví dụ:** @@ -258,7 +252,7 @@ Với cấu hình này, `kubectl get pods` được cho phép nhưng `kubectl ap | Tham số | Loại | Mặc định | Mô tả | |--------|------|---------|-------| -| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh az CLI được phép. | +| `allowPatterns` | `string[]` | `[]` | Các tiền tố lệnh CLI az được cho phép. | **Ví dụ:** @@ -283,7 +277,7 @@ Với cấu hình này, `kubectl get pods` được cho phép nhưng `kubectl ap | Tham số | Loại | Mặc định | Mô tả | |--------|------|---------|-------| -| `allowPatterns` | `string[]` | `[]` | Tiền tố lệnh helm được phép. | +| `allowPatterns` | `string[]` | `[]` | Các tiền tố lệnh helm được cho phép. | **Ví dụ:** @@ -302,7 +296,7 @@ Với cấu hình này, `kubectl get pods` được cho phép nhưng `kubectl ap ### `block-gh-pipeline` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối các lệnh con `gh` CLI sau đây làm thay đổi trạng thái hoặc kích hoạt các đường ống: +**Mặc định:** Từ chối các lệnh con `gh` CLI sau đây làm thay đổi trạng thái hoặc kích hoạt các pipeline: - `gh workflow run`, `gh workflow enable`, `gh workflow disable` - `gh run rerun`, `gh run cancel` @@ -311,13 +305,13 @@ Với cấu hình này, `kubectl get pods` được cho phép nhưng `kubectl ap - `gh cache delete` - `gh secret set`, `gh secret delete` -Các lệnh con `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 workflow (bao gồm cả `require-ci-green-before-stop` của chính failproofai). +Các lệnh con `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 được cần thường xuyên 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). **Tham số:** | Tham số | Loại | Mặc định | Mô tả | |--------|------|---------|-------| -| `allowPatterns` | `string[]` | `[]` | Các lệnh gọi được viết kịch bản cụ thể để cho phép mặc dù nếu không sẽ bị từ chối. | +| `allowPatterns` | `string[]` | `[]` | Các lệnh gọi kịch bản cụ thể được cho phép mặc dù chúng sẽ bị từ chối. | **Ví dụ:** @@ -335,12 +329,12 @@ Các lệnh con `gh` chỉ đọc như `gh pr view`, `gh pr list`, `gh run list` ## Bí mật (sanitizers) -Dừng các 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 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 đầu ra trước khi nó được trả lại cho Claude. Nếu phát hiện một 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 trở lại. +Dừng agent từ rò rỉ thông tin xác thực vào ngữ cảnh hoặc output của chúng. Các chính sách sanitizer 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 output 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 output được chuyển tiếp lại. ### `sanitize-jwt` **Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Redact các token JWT (ba đoạn base64url được tách bằng `.`). +**Mặc định:** Loại bỏ các token JWT (ba đoạn base64url được phân tách bằng `.`). Không có tham số. @@ -349,13 +343,13 @@ Không có tham số. ### `sanitize-api-keys` **Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Redact 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 Google API (`AIza`). +**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`). **Tham số:** | Tham số | Loại | Mặc định | Mô tả | |--------|------|---------|-------| -| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Các mẫu regex bổ sung được coi là bí mật. | +| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | Các mẫu regex bổ sung để coi là bí mật. | **Ví dụ:** @@ -364,8 +358,8 @@ Không có tham số. "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": "Khóa API nội bộ MyCo" }, + { "regex": "pat_[0-9a-f]{40}", "label": "PAT nội bộ" } ] } } @@ -377,7 +371,7 @@ Không có tham số. ### `sanitize-connection-strings` **Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Redact các 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:** Loại bỏ các 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`). Không có tham số. @@ -386,7 +380,7 @@ Không có tham số. ### `sanitize-private-key-content` **Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Redact các khối PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, v.v.). +**Mặc định:** Loại bỏ các khối PEM (`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----`, v.v.). Không có tham số. @@ -395,7 +389,7 @@ Không có tham số. ### `sanitize-bearer-tokens` **Sự kiện:** PostToolUse (tất cả công cụ) -**Mặc định:** Redact `Authorization: Bearer ` headers nơi token có 20 hoặc nhiều ký tự hơn. +**Mặc định:** Loại bỏ các tiêu đề `Authorization: Bearer ` nơi token là 20 ký tự trở lên. Không có tham số. @@ -403,14 +397,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 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 bị 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` thông 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 các tệp `.env` qua `cat .env`, lệnh 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 `.env`. +Không chặn `.envrc` hoặc các tệp liền kề môi trường khác — chỉ các tệp có tên chính xác là `.env`. Không có tham số. @@ -419,7 +413,7 @@ Không có tham số. ### `protect-env-vars` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối các lệnh in các biến môi trường: `printenv`, `env`, `echo $VAR`. +**Mặc định:** Từ chối các lệnh in ra các biến môi trường: `printenv`, `env`, `echo $VAR`. Không có tham số. @@ -432,13 +426,13 @@ Giữ các agent làm việc bên trong ranh giới dự án và tránh xa các ### `block-read-outside-cwd` **Sự kiện:** PreToolUse (Read, Bash) -**Mặc định:** Từ chối đọc các tệp bên 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 dự phòng là 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 các tệp bên ngoài thư mụ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 fallback đến 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 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 bên ngoài thư mục gốc dự án. | +| `allowPaths` | `string[]` | `[]` | Các tiền tố đường dẫn tuyệt đối được phép ngay cả khi bên ngoài thư mục dự án. | **Ví dụ:** @@ -457,7 +451,7 @@ Giữ các agent làm việc bên trong ranh giới dự án và tránh xa các ### `block-secrets-write` **Sự kiện:** PreToolUse (Write, Edit) -**Mặc định:** Từ chối ghi vào các tệp thường dùng cho khóa riêng 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 khóa riêng và chứng chỉ: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`. **Tham số:** @@ -481,7 +475,7 @@ Giữ các agent làm việc bên trong ranh giới dự án và tránh xa các ## Git -Ngăn chặn các lần push tình cờ, force-push và lỗi nhánh khó được hoàn tác. +Ngăn chặn các lần đẩy ngẫu nhiên, lực đẩy và lỗi nhánh khó hoàn tác. ### `block-push-master` @@ -492,7 +486,7 @@ Ngăn chặn các lần push tình cờ, force-push và lỗi nhánh khó đư | 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. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Các tên nhánh không thể được đẩy trực tiếp. | **Ví dụ:** @@ -507,7 +501,7 @@ Ngăn chặn các lần push tình cờ, force-push và lỗi nhánh khó đư ``` -Để cho phép push tới tất cả các nhánh (có hiệu lực vô hiệu hóa chính sách này mà không cần loại bỏ nó khỏi `enabledPolicies`), hãy đặt `protectedBranches: []`. +Để cho phép đẩy đến tất cả các nhánh (thực tế là vô hiệu hóa chính sách này mà không xóa nó khỏi `enabledPolicies`), hãy đặt `protectedBranches: []`. --- @@ -515,13 +509,13 @@ Ngăn chặn các lần push tình cờ, force-push và lỗi nhánh khó đư ### `block-work-on-main` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Từ chối kiểm tra trực tiếp các nhánh `main` hoặc `master`. +**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 và chuyển nhánh (`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 không thể được kiểm tra trực tiếp. | +| `protectedBranches` | `string[]` | `["main", "master"]` | Các tên nhánh mà commit/merge/rebase/cherry-pick bị từ chối. | --- @@ -530,13 +524,13 @@ Ngăn chặn các lần push tình cờ, force-push và lỗi nhánh khó đư **Sự kiện:** PreToolUse (Bash) **Mặc định:** Từ chối `git push --force` và `git push -f`. -Không có tham số chính sách cụ thể. Sử dụng [`hint`](/vi/configuration#hint-cross-cutting) cắt ngang để gợi ý các lựa chọn thay thế: +Không có tham số cụ thể cho chính sách. Sử dụng [`hint`](/vi/configuration#hint-cross-cutting) xuyên suốt để gợi ý các giải pháp thay thế: ```json { "policyParams": { "block-force-push": { - "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b `) and push that instead." + "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à đẩy nhánh đó thay thế." } } } @@ -565,7 +559,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 staging khi nó chạy `git add -A` hoặc `git add .`. Không chặn lệnh. +**Mặc định:** Hướng dẫn Claude xem xét những gì nó đang staging khi chạy `git add -A` hoặc `git add .`. Không chặn lệnh. Không có tham số. @@ -573,7 +567,7 @@ Không có tham số. ## Cơ sở dữ liệu -Bắt các thao tác SQL phá hủy trước khi chúng thực thi với cơ sở dữ liệu của bạn. +Bắt các hoạt động SQL phá hủy trước khi chúng thực thi vào cơ sở dữ liệu của bạn. ### `warn-destructive-sql` @@ -587,7 +581,7 @@ Không có tham số. ### `warn-schema-alteration` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy các câu lệnh `ALTER TABLE`. +**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy các lệnh `ALTER TABLE`. Không có tham số. @@ -595,7 +589,7 @@ Không có tham số. ## Cảnh báo -Cung cấp cho các agent ngữ cảnh bổ sung trước các thao tác có khả năng rủi ro nhưng không phá hủy. +Cung cấp cho agent bối 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` @@ -606,7 +600,7 @@ Cung cấp cho các agent ngữ cảnh bổ sung trước các thao tác có kh | 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 mà trên đó sẽ có cảnh báo. | +| `thresholdKb` | `number` | `1024` | Ngưỡng kích thước tệp tính bằng kilobyte mà trên đó cảnh báo được đưa ra. | **Ví dụ:** @@ -621,7 +615,7 @@ Cung cấp cho các agent ngữ cảnh bổ sung trước các thao tác có kh ``` -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 một giá trị well below 1024. +Trình xử lý hook thực thi giới hạn stdin 1 MB trên các 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 một giá trị tốt bên dưới 1024. --- @@ -638,7 +632,7 @@ Không có tham số. ### `warn-background-process` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Hướng dẫn Claude cẩn thận khi khởi chạy các quy trình nền thông qua `nohup`, `&`, `disown` hoặc `screen`. +**Mặc định:** Hướng dẫn Claude cẩn thận khi khởi động các quy trình nền qua `nohup`, `&`, `disown` hoặc `screen`. Không có tham số. @@ -647,7 +641,7 @@ Không có tham số. ### `warn-global-package-install` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy `npm install -g`, `yarn global add` hoặc `pip install` mà không có một môi trường ảo. +**Mặc định:** Hướng dẫn Claude xác nhận trước khi chạy `npm install -g`, `yarn global add` hoặc `pip install` mà không có môi trường ảo. Không có tham số. @@ -660,16 +654,16 @@ Thực thi trình quản lý gói nào mà agent được phép sử dụng. ### `prefer-package-manager` **Sự kiện:** PreToolUse (Bash) -**Mặc định:** 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 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:** Tắt. Khi được 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. 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à no-op. | -| `blocked` | string[] | `[]` | Tên trình quản lý bổ sung để chặn ngoài danh sách built-in (ví dụ: `['pdm', 'pipx']`). | +| `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 built-in 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ụ:** @@ -685,33 +679,33 @@ Danh sách chặn built-in bao gồm: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun } ``` -Với cấu hình này, `pip install flask` và `pdm install flask` đều bị từ chối với một 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 cho phép vì `uv` ở trong danh sách cho phép và được kiểm tra trước. +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` 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 các agent bị mắc kẹt hoặc có hành vi bất thường. +Phát hiện khi agent bị kẹt hoặc hành xử không như mong đợi. ### `warn-repeated-tool-calls` **Sự kiện:** PreToolUse (tất cả công cụ) -**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 — một dấu hiệu phổ biến rằng agent bị mắc kẹt trong một 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 với các tham số giống hệt nhau — một dấu hiệu phổ biến của agent bị kẹt trong vòng lặp. Không có tham số. --- -## Workflow +## Quy trình làm việc -Thực thi một quy trình kết thúc phiên được kỷ luật. Các chính sách này kích hoạt trên sự kiện **Stop** và từ chối Claude dừng lại cho đến khi từng điều kiện được đáp ứng. Chúng theo một chuỗi phụ thuộc tự nhiên: commit → push → PR → CI. Nếu một chính sách từ chối, các chính sách sau trong chuỗi được bỏ qua (deny short-circuits). +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 kích hoạt trên sự kiện **Stop** và từ chối Claude dừng lại cho đến khi mỗi điều kiện được đáp ứng. Chúng tuân theo một 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 làm ngắn mạch). -Tất cả các chính sách workflow là **fail-open**: nếu công cụ cần thiết không khả dụng (ví dụ: `gh` không được cài đặt, không có git remote), chính sách cho phép với một 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 **fail-open**: nếu công cụ bắt buộc 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. ### `require-commit-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng lại khi có những thay đổi chưa commit (tệp được sửa đổi, staged hoặc untracked). Trả về một 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 khi có thay đổi chưa được commit (tệp đã sửa đổi, staged 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ố. @@ -720,13 +714,13 @@ Không có tham số. ### `require-push-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng lại khi có các commit chưa 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. Fails open nếu không có remote được cấu hình. +**Mặc định:** Từ chối dừng khi có các commit chưa được đẩy 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. Fail open 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. | +| `remote` | `string` | `"origin"` | Tên remote để đẩy đến. | **Ví dụ:** @@ -745,14 +739,14 @@ Không có tham số. ### `require-pr-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng lại khi không có yêu cầu pull 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 với `gh pr create`. Khi PR **merged**, 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`). +**Mặc định:** Từ chối dừng khi không có pull request cho nhánh hiện tại hoặc 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 đã ship) và thông báo gợi ý chuyển 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 một token truy cập cá nhân có phạm vi `repo` để truy cập đọc -các yêu cầu pull. Nếu `gh` không được cài đặt hoặc không được xác thực, chính sách fails open và báo cáo lý do cho Claude. +Chạy `gh auth login` với personal access token có `repo` scope để đọc pull request. +Nếu `gh` không được cài đặt hoặc không xác thực, chính sách fail open và báo cáo lý do cho Claude. --- @@ -760,24 +754,24 @@ các yêu cầu pull. Nếu `gh` không được cài đặt hoặc không đư ### `require-no-conflicts-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng lại khi nhánh hiện tại không thể cleanly 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ó một, không có mục tiêu merge để thực thi, vì vậy toàn bộ chính sách short-circuits để cho phép. Khi một 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 khi nhánh hiện tại không thể merge sạch sẽ 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 nên toàn bộ chính sách short-circuit để cho phép. Sau khi PR `OPEN` được xác nhận, hai cuộc kiểm tra độc lập chạy: -1. **Local** — `git merge-tree --write-tree --name-only origin/ HEAD`. Khi 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** — 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 các xung đột mà một `origin/` cũ cục bộ sẽ bỏ lỡ (ví dụ: người nào đó đã hạ cánh một 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à re-check trước khi cố gắng dừng lại lại — điều này ngăn chặn false negatives trong khi GitHub tính toán lại. +1. **Cục bộ** — `git merge-tree --write-tree --name-only origin/ HEAD`. Khi xung đột, thông báo deny đặt tên các tệp xung đột để Claude biết chính xác phải giải quyết gì. +2. **GitHub** — sử dụng lại kết quả `gh pr view --json mergeable,state` đã được tìm nạp trong precheck. Bắt các 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 — điều này ngăn chặn các kết quả âm 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 tồn tại 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. Cũng fails open khi `origin/` bị mất cục bộ hoặc khi không có commits phía trước cơ sở — những lần fall-through Layer 1 đó vẫn tham khảo PR mergeability được lưu trong bộ nhớ đệm 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 cho nhánh, trạng thái PR không phải `OPEN` (ví dụ: `MERGED`, `CLOSED`), hoặc `gh pr view` trả về output không thể phân tích cú pháp. Cũng fail open khi `origin/` bị thiếu cục bộ hoặc không có commit nào phía trước cơ sở — những lỗi Layer 1 đó vẫn tham khảo mergeable PR được lưu trữ 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 chống lại. | +| `baseBranch` | `string` | `"main"` | Nhánh cơ sở để kiểm tra xung đột. | 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 -short-circuits để cho phép. Chạy `gh auth login` với một token truy cập cá nhân có -phạm vi `repo` để truy cập đọc các yêu cầu pull. +PR `OPEN` tồn tại trước khi chạy bất kỳ cuộc kiểm 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 personal access token có +`repo` scope để đọc pull request. --- @@ -785,14 +779,14 @@ phạm vi `repo` để truy cập đọc các yêu cầu pull. ### `require-ci-green-before-stop` **Sự kiện:** Stop -**Mặc định:** Từ chối dừng lại khi 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ả GitHub Actions workflow chạy và kiểm tra bot của bên thứ ba (ví dụ: CodeRabbit, SonarCloud, Codecov). Coi `skipped` và `cancelled` kết luận là thành công. Trả về một thông báo thông tin khi tất cả các kiểm tra đều vượt qua. +**Mặc định:** Từ chối dừng 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ả 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` và `cancelled` kết luận là thành công. Trả về thông báo thông tin khi tất 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 một token truy cập cá nhân có phạm vi `repo` để truy cập đọc -các chạy workflow Actions và Checks API. Nếu `gh` không được cài đặt hoặc không được xác thực, chính sách fails open và báo cáo lý do cho Claude. +Chạy `gh auth login` với personal access token có `repo` scope để đọc +chạy quy trình 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 fail open và báo cáo lý do cho Claude. --- @@ -801,7 +795,7 @@ các chạy workflow Actions và Checks API. Nếu `gh` không được cài đ ## Vô hiệu hóa các chính sách riêng lẻ -Loại bỏ một chính sách cụ thể khỏi `enabledPolicies` trong cấu hình của bạn hoặc chuyển đổi nó tắt trong tab Chính sách của bảng điều khiển. +Xóa chính sách cụ thể khỏi `enabledPolicies` trong cấu hình của bạn hoặc tắt nó trong tab Chính sách của bảng điều khiển. ```json { @@ -812,4 +806,4 @@ Loại bỏ một chính sách cụ thể khỏi `enabledPolicies` trong cấu h } ``` -Các chính sách không được liệt kê trong `enabledPolicies` không chạy, ngay cả khi các mục `policyParams` tồn tại cho chúng. \ No newline at end of file +Các chính sách không được liệt kê trong `enabledPolicies` không chạy, ngay cả khi tồn tại các mục `policyParams` cho chúng. \ No newline at end of file diff --git a/docs/vi/configuration.mdx b/docs/vi/configuration.mdx index 388fea2b..833ff743 100644 --- a/docs/vi/configuration.mdx +++ b/docs/vi/configuration.mdx @@ -1,11 +1,12 @@ --- + --- title: Cấu hình description: "Định dạng tệp cấu hình, hệ thống ba phạm vi, và quy tắc hợp nhất" icon: gear --- -failproofai sử dụng các tệp cấu hình JSON để kiểm soát những chính sách nào 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 - hãy cam kết nó vào kho lưu trữ của bạn và mọi nhà phát triển đều nhận được cùng một lưới bảo vệ cho agent. +failproofai sử dụng 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, 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 team của bạn - cam kết nó vào repo và mỗi developer sẽ có cùng một lưới bảo vệ cho agent. --- @@ -15,15 +16,15 @@ 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 per-repo, cam kết vào kiểm soát phiên bản | -| **local** | `.failproofai/policies-config.local.json` | Ghi đè cá nhân per-repo, được gitignore | -| **global** | `~/.failproofai/policies-config.json` | Giá trị mặc định cấp người dùng cho tất cả các dự án | +| **project** | `.failproofai/policies-config.json` | Cài đặt mỗi repo, cam kết vào kiểm soát phiên bản | +| **local** | `.failproofai/policies-config.local.json` | Ghi đè cá nhân mỗi repo, được gitignore | +| **global** | `~/.failproofai/policies-config.json` | Mặc định cấp người dùng trên tất cả các dự án | Khi failproofai nhận một sự kiện hook, nó tải và hợp nhất cả ba tệp tồn tại cho thư mục làm việc hiện tại. ### Quy tắc hợp nhất -**`enabledPolicies`** - liên hợp của cả ba phạm vi. Một chính sách được kích hoạt ở bất kỳ cấp nào đều hoạt động. +**`enabledPolicies`** - hợp của tất cả ba phạm vi. Một chính sách được bật ở bất kỳ mức nào đều hoạt động. ```text project: ["block-sudo"] @@ -33,26 +34,26 @@ global: ["block-sudo", "sanitize-api-keys"] 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 params cho một chính sách nhất định chiến thắng hoàn toàn. Không có sự hợp nhất sâu của các giá trị trong params của chính sách. +**`policyParams`** - phạm vi đầu tiên định nghĩa các tham số cho một chính sách nhất định sẽ thắng toàn bộ. 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ó chiến thắng. +**`customPoliciesPath`** - phạm vi đầu tiên định nghĩa nó sẽ thắng. -**`llm`** - phạm vi đầu tiên xác định nó chiến thắng. +**`llm`** - phạm vi đầu tiên định nghĩa nó sẽ thắng. --- @@ -97,31 +98,31 @@ resolved: { allowPatterns: ["sudo systemctl status"] } ← rơi vào global --- -## Tham khảo trường +## Tham chiếu trường ### `enabledPolicies` -Loại: `string[]` +Kiểu: `string[]` -Danh sách tên chính sách để 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) để biết danh sách đầy đủ. +Danh sách tên chính sách để bật. Tên phải khớp chính xác với các mã định danh chính sách được hiển thị bởi `failproofai policies`. Xem [Chính sách tích hợp](/vi/built-in-policies) để xem danh sách đầy đủ. -Các chính sách không có trong `enabledPolicies` không hoạt động, ngay cả khi chúng có mục trong `policyParams`. +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 nhập trong `policyParams`. ### `policyParams` -Loại: `Record>` +Kiểu: `Record>` -Ghi đè tham số per-policy. Khóa bên ngoài là tên chính sách; các khóa bên trong là cụ thể từng chính sách. Mỗi chính sách ghi chép các tham số có sẵn của nó trong [Built-in Policies](/vi/built-in-policies). +Ghi đè tham số mỗi chính sách. Khóa bên ngoài là tên chính sách; các khóa bên trong là khóa dành riêng cho chính sách. Mỗi chính sách có tài liệu các tham số có sẵn trong [Chính sách tích hợp](/vi/built-in-policies). -Nếu một chính sách 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. Những người dùng không cấu hình `policyParams` 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, mặc định tích hợp của chính sách sẽ được sử dụng. Người dùng không định 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. -Các khóa không xác định bên trong khối params của chính sách bị bỏ qua im lặng tại thời gian kích hoạt hook nhưng được gắn cờ là cảnh báo khi bạn chạy `failproofai policies`. +Các khóa không xác định bên trong khối tham số của chính sách sẽ bị im lặng khi hook bắn nhưng được đánh dấu là cảnh báo khi bạn chạy `failproofai policies`. -#### `hint` (cross-cutting) +#### `hint` (xuyên suốt) -Loại: `string` (tùy chọn) +Kiểu: `string` (tùy chọn) -Một tin nhắn đượ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 cho Claude hướng dẫn có thể thực hiện được mà không sửa đổi chính sách. +Một thông báo được thêm vào lý do khi chính sách trả về `deny` hoặc `instruct`. Sử dụng nó để cung cấp hướng dẫn hành động cho Claude mà không 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, tùy chỉnh (`custom/`), quy ước dự án (`.failproofai-project/`), hoặc quy ước người dùng (`.failproofai-user/`). @@ -129,53 +130,53 @@ Hoạt động với bất kỳ loại chính sách nào — tích hợp, tùy c { "policyParams": { "block-force-push": { - "hint": "Hãy thử tạo một nhánh mới thay vào đó." + "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": "Hãy yêu cầu người dùng phê duyệt trước." + "hint": "Ask the user for approval first." } } } ``` -Khi `block-force-push` từ chối, Claude thấy: *"Force-pushing bị chặn. Hãy thử tạo một nhánh mới thay vào đó."* +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 trống bị bỏ qua im lặng. Nếu `hint` không được đặt, hành vi không thay đổi (tương thích ngược). +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). ### `customPoliciesPath` -Loại: `string` (đường dẫn tuyệt đối) +Kiểu: `string` (đường dẫn tuyệt đối) Đường dẫn đến tệp JavaScript chứa các chính sách hook tùy chỉnh. Điều này được đặt tự động bởi `failproofai policies --install --custom ` (đường dẫn được phân giải thành tuyệt đối trước khi được lưu trữ). -Tệp được tải mới trên mỗi sự kiện hook - không có lưu trữ. Xem [Custom Policies](/vi/custom-policies) để biết chi tiết viết. +Tệp được tải lại trên mỗi sự kiện hook - không có bộ nhớ cache. Xem [Chính sách tùy chỉnh](/vi/custom-policies) để biết chi tiết về tác giả. ### 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/`: +Ngoài `customPoliciesPath` rõ ràng, failproofai tự động khám phá và tải các tệp chính sách từ các thư mục `.failproofai/policies/`: -| Cấp | Thư mục | Phạm vi | +| Mức | Thư mục | Phạm vi | |-------|-----------|-------| -| 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 team 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ỉ các tệp khớp `*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:** Chính sách quy ước không yêu cầu mục nào trong `policies-config.json`. Chỉ cần thả các tệp vào thư mục và chúng sẽ được chọn vào sự kiện hook tiếp theo. +**Không cần cấu hình:** Chính sách quy ước không 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 nhặt lên khi hook tiếp theo được kích hoạt. -**Tải hợp nhất:** Cả hai thư mục quy ước dự án và người dùng đượ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 phạm vi đầu tiên thắng). +**Tải hợp:** Cả hai thư mục quy ước dự án và người dùng đều được quét. Tất cả các tệp khớp từ cả hai mức được tải (không giống `customPoliciesPath` sử dụng first-scope-wins). -Xem [Custom Policies](/vi/custom-policies) để biết thêm chi tiết và ví dụ. +Xem [Chính sách tùy chỉnh](/vi/custom-policies) để biết thêm chi tiết và ví dụ. ### `llm` -Loại: `object` (tùy chọn) +Kiểu: `object` (tùy chọn) -Cấu hình máy khách LLM cho các chính sách thực hiện các cuộc gọi AI. Không bắt buộc cho hầu hết các thiết lập. +Cấu hình client 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 thiết lập. ```json { @@ -190,36 +191,44 @@ Cấu hình máy khách LLM cho các chính sách thực hiện các cuộc gọ ## Quản lý cấu hình từ CLI -Các lệnh `policies --install` và `policies --uninstall` ghi vào tệp cài đặt hook của CLI agent của bạn (các điểm 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 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ác điểm vào hook), trong khi `policies-config.json` là tệp bạn quản lý trực tiếp. Hai cái này là riêng biệt: -- **Cài đặt CLI Agent** — yêu cầu agent gọi `failproofai --hook ` trên mỗi lần sử dụng công cụ: - - **Claude Code**: `~/.claude/settings.json` (người dùng), `/.claude/settings.json` (dự án), `/.claude/settings.local.json` (cục bộ) - - **OpenAI Codex**: `~/.codex/hooks.json` (người dùng), `/.codex/hooks.json` (dự án) — Codex không có phạm vi `local` - - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (người dùng), `/.github/hooks/failproofai.json` (dự án) — Copilot không có phạm vi `local`. Các mục hook sử dụng các trường lệnh `bash`/`powershell` có khóa OS của Copilot với `timeoutSec`; tệp mang một dấu hiệ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à tài liệu công khai không chỉ định) so với nhiều phiên thực tế hơn. -- **`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 (chia sẻ 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 sử dụng công cụ: + - **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 OS 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à tài liệu công cộng không chỉ định) so với nhiều phiên bản 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}` của Claude (không phân chia `bash`/`powershell`), nhưng được lưu trữ theo khóa sự kiện camelCase (`preToolUse`, `beforeSubmitPrompt`, …) trong một mảng phẳng theo [lược đồ hook](https://cursor.com/docs/hooks) của Cursor; tệp mang một đánh dấu `version: 1` cấp cao nhất. Trình xử lý chuyển chính tắc camelCase → PascalCase thông qua `CURSOR_EVENT_MAP` để các chính sách tích hợp hiện có hoạt động không thay đổi. Hỗ trợ Cursor Agent là **beta** trong khi chúng tôi xác minh định dạng phiên bản Cursor trên đĩa (không được chỉ định trong tài liệu công cộng) so với nhiều 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ư bốn CLI khác, OpenCode có **không hệ thống hook lệnh bên ngoài**: nó tải các plugin JS/TS trong quá trình xử lý được đăng ký rõ ràng thông qua mảng `plugin: []` trong `opencode.json` (tự động phát hiện từ `.opencode/plugins/` là **không** 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 subprocess cho nhị phân failproofai và dịch phản ứng JSON hình dạng Claude của nhị phân trở lại ngữ nghĩa plugin (`throw new Error()` cho deny, `client.session.prompt(...)` cho instruct, không-op cho allow). Các phiên làm việc sống trong DB 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 thông qua `opencode db --format json` và `opencode export `. Hỗ trợ OpenCode là **beta** trong khi chúng tôi xác minh hành vi trên các phiên bản và so với các phiên bản thực tế hơn. Xem [tài liệu plugin 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 tiện ích mở rộng TypeScript khi khởi động; tệp cài đặt là một mảng chuỗi `{"packages": ["./relative/path", …]}`. failproofai ghi một mục nhập packages-array duy nhất trỏ đến thư mục `pi-extension/` được đóng gói của nó. Tiện ích mở rộng nội bộ đă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ý chuyển chính tắc underscore_lower_snake_case → PascalCase thông qua `PI_EVENT_MAP` để các chính sách tích hợp hiện có hoạt động không thay đổi. Hỗ trợ Pi là **beta** trong khi API tiện ích mở rộng Pi và bố cục 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ạ tới tên claude chính tắc thông qua `GEMINI_EVENT_MAP`. Tên công cụ là snake_case (`run_shell_command`, `read_file`, `write_file`, `replace`, …) — trình xử lý chuyển chính tắc thông qua `GEMINI_TOOL_MAP` để các chính sách tích hợp hiện có hoạt động không thay đổi. Công cụ đánh giá chính sách phát ra hình dạng `{decision: "deny", reason}` phẳng của Gemini (ưu tiên mỗi quy tắc vàng của Gemini exit-0), `{hookSpecificOutput: {hookEventName, additionalContext}}` cho tiêm ngữ cảnh trên BeforeAgent / AfterTool / SessionStart, và `{decision: "block", reason}` trên AfterAgent cho ngữ nghĩa thử lại lự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 hook Gemini CLI](https://geminicli.com/docs/hooks/). +- **`policies-config.json`** — cho failproofai biết những chính sách nào để đá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` để nhắm mục tiêu một agent cụ thể (cách nhau bằng khoảng trắng hoặc lặp lại cho bất kỳ tập con nào): +Chuyển `--cli claude|codex|copilot|cursor|opencode|pi|gemini` để nhắm mục tiêu 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): ```bash failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project -failproofai policies --install --cli claude codex copilot +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 claude codex copilot cursor opencode pi gemini ``` -Khi `--cli` bị bỏ qua, `failproofai` phát hiện các CLI agent nào được cài đặt (`which claude` / `which codex` / `which copilot`): +Khi `--cli` bị bỏ qua, `failproofai` phát hiện các CLI agent nào được cài đặt (`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which gemini`): - **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 một thiết bị đầu cuối tương tác — hiển thị dấu mũi tên lựa chọn một lựa chọn: khi có hai CLI, các lựa chọn là `Both`, ` only`, ` only`; với ba CLI, tùy chọn đầu tiên trở thành `All` (↑↓ để di chuyển, Enter để chọn, ^C để thoát). +- **Nhiều CLI được phát hiện** trong một thiết bị đầu cuối tương tác — hiển thị lời nhắc lựa chọn đơn khóa mũi tên được nhóm thành phần `Detected (N)` (với hàng tổng hợp `Install for all N detected` + mỗi 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 hỗ trợ không được phát hiện như một tùy chọn cài đặt 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 một 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 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 viết để nó kích hoạt ngay khi bạn cài đặt một lệnh. +- **Không 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. -Bạn có thể chỉnh sửa `policies-config.json` trực tiếp bất kỳ lúc nào; các thay đổi có hiệu lực ngay lập tức trên sự kiện hook tiếp theo mà không cần khởi động lại. +Bạn có thể chỉnh sửa `policies-config.json` trực tiếp bất kỳ lúc nào; các thay đổi có hiệu lực ngay trên 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 với giá trị mặc định nhóm +## Ví dụ: cấu hình cấp dự án với mặc định team -Cam kết `.failproofai/policies-config.json` vào kho lưu trữ của bạn: +Cam kết `.failproofai/policies-config.json` vào repo của bạn: ```json { @@ -238,4 +247,4 @@ Cam kết `.failproofai/policies-config.json` vào kho lưu trữ của bạn: } ``` -Sau đó, mỗi nhà phát triển có thể tạo `.failproofai/policies-config.local.json` (được gitignore) cho các ghi đè cá nhân mà không ảnh hưởng đến các đồng nghiệp. \ No newline at end of file +Mỗi developer sau đó có thể tạo `.failproofai/policies-config.local.json` (gitignored) cho các ghi đè cá nhân mà không ảnh hưởng đến các đồng đội. \ No newline at end of file diff --git a/docs/vi/dashboard.mdx b/docs/vi/dashboard.mdx index 46918e6d..8e6bc4ab 100644 --- a/docs/vi/dashboard.mdx +++ b/docs/vi/dashboard.mdx @@ -1,10 +1,10 @@ --- title: Bảng điều khiển -description: "Giám sát các phiên tác nhân, xem xét các lệnh gọi công cụ và quản lý chính sách" +description: "Theo dõi các phiên làm việc của agent, xem lại các lệnh gọi tool, và quản lý chính sách" icon: chart-line --- -Bảng điều khiển failproofai là một ứng dụng web cục bộ để giám sát các phiên tác nhân AI của bạn và quản lý chính sách. Xem những gì các tác nhân của bạn đã làm trong khi bạn vắng mặt. +Bảng điều khiển failproofai là một ứng dụng web cục bộ để theo dõi các phiên làm việc của agent AI của bạn và quản lý chính sách. Xem những gì các agent của bạn đã làm trong khi bạn vắng mặt. --- @@ -24,12 +24,12 @@ Bảng điều khiển đọc trực tiếp từ hệ thống tệp - các thư ### Dự án -Liệt kê tất cả các dự án Claude Code, OpenAI Codex và GitHub Copilot CLI _(beta)_ đượ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 trong `~/.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 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ó. 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 với tất cả các huy hiệu phù hợp. Sử dụng menu thả xuống **CLI** ở trên bảng để lọc theo một CLI tác nhân cụ thể; URL giữ lựa chọn của bạn dưới dạng `?cli=claude|codex|copilot`. +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 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 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 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 từng phiên dưới `~/.cursor/agent-sessions//` (có thể cấu hình qua `CURSOR_HOME`, với `conversations/` và `sessions/` được thử làm dự phòng) để tìm 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 các bản ghi JSONL từng 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ừ điểm đánh dấu `.project_root` liền kề. 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** ở 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`. 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), và/hoặc `GitHub Copilot` (xanh) -- Ngày hoạt động phiên gần nhất +- Tên dự án (được suy ra 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 lục bảo), `OpenCode` (hổ phách), `Pi` (hồng), và/hoặc `Gemini CLI` (xanh nhạt) +- Ngày hoạt động phiên gần đây nhất Nhấp vào một dự án để xem các phiên của nó. @@ -38,8 +38,8 @@ Nhấp vào một dự án để xem các phiên của nó. 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 hook (chính sách được kích hoạt) +- Số lượng lệnh gọi tool +- Số lượng hoạt động hook (chính sách đã kích hoạt) 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. @@ -47,64 +47,64 @@ Nhấp vào một phiên để mở trình xem phiên. ### Trình xem phiên -Trình xem phiên trả lời câu hỏi chính cho các tác nhân tự chủ động: tác nhân đã làm gì, và nó có ở đúng hướng 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 hay OpenAI Codex. Nó hiển thị một dòng thời gian của mọi thứ xảy ra trong một phiên: +Trình xem phiên trả lời câu hỏi chính cho các agent tự chủ: agent đã làm gì và liệu nó có duy trì hiệu suất không? Một huy hiệu CLI bên cạnh tiêu đề cho biết phiên là một bản ghi 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 mọi thứ đã xảy ra trong một phiên: -- **Tin nhắn** - Phản hồi văn bản của Claude và lời nhắc của người dùng -- **Lệnh gọi công cụ** - Mọi công cụ mà Claude gọi, cùng với đầu vào và đầu ra của nó -- **Hoạt động chính sách** - Đối với mỗi lệnh gọi công cụ, các chính sách nào được kích hoạt và quyết định nào chúng trả về +- **Tin nhắn** - Các phản hồi văn bản của Claude và lời nhắc của người dùng +- **Lệnh gọi tool** - Mọi tool mà Claude gọi, với đầu vào và đầu ra của nó +- **Hoạt động chính sách** - Đối với mỗi lệnh gọi tool, chính sách nào đã kích hoạt và quyết định nào mà chúng trả về -Thanh thống kê ở trên cùng hiển thị thời lượng phiên, tổng số lệnh gọi công cụ và tóm tắt các quyết định hook (số lượng allow / deny / instruct). +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 tool, và tóm tắt các quyết định hook (số lượng allow / deny / instruct). -Bạn có thể xuất phiên dưới dạng tệp ZIP hoặc JSONL bằng cách sử dụng nút tải xuống. +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 nhận được bản ghi JSONL trên đĩa ban đầu từng byte; đối với OpenCode (các phiên của nó nằm trong SQLite, không phải trên đĩa) bạn nhận được một tài liệu JSON phản ánh các bảng `session` / `messages` / `parts` cơ bản. ### Chính sách -Một trang hai tab để quản lý chính sách và xem xét hoạt động. +Một trang có hai tab để quản lý chính sách và xem lại hoạt động. - - 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`) + - Bật hoặc tắt các chính sách riêng lẻ chỉ bằng một clic (ghi vào `~/.failproofai/policies-config.json`) - 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`) - - Cài đặt hoặc xóa hook cho một phạm vi nhất định + - Cài đặt hoặc xóa các hook cho một phạm vi nhất định - Đặt đường dẫn tệp chính sách tùy chỉnh - - Lịch sử đầy đủ được phân trang của mọi sự kiện hook đượ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)_), 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), 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 kích hoạt hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state//events.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 đã 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)_), tên chính sách, hoặc ID phiên + - Mỗi hàng hiển thị: dấu thời gian, tên chính sách, quyết định, huy hiệu CLI (cam = Claude Code, tím = OpenAI Codex, xanh = GitHub Copilot, ngọc lục bảo = Cursor Agent, hổ phách = OpenCode, hồng = Pi, xanh nhạt = Gemini CLI), tên tool, 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 đã 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`) và hiển thị huy hiệu CLI phù hợp trong tiêu đề --- -## Tự động làm tươi +## Làm mới tự động -Bảng điều khiển có một nút bật tắt tự động làm tươi trong thanh điều hướng trên cùng. Khi bật, trang hiện tại sẽ làm tươ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. Điều cần thiết để giám sát các phiên tác nhân tự chủ động chạy lâu dài. +Bảng điều khiển có một công tắc làm mới tự động trong thanh điều hướng trên cùng. Khi được bật, trang hiện tại 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 để theo dõi các phiên agent tự chủ chạy dài. --- ## Vô hiệu hóa các trang -Nếu bạn chỉ cần một số phần của bảng điều khiển, hãy đặt `FAILPROOFAI_DISABLE_PAGES` thành danh sách tên trang được phân tách bằng dấu phẩy: +Nếu bạn chỉ cần một số phần của bảng điều khiển, hãy đặt `FAILPROOFAI_DISABLE_PAGES` thành một danh sách các tên trang được phân tách bằng dấu phẩy: ```bash FAILPROOFAI_DISABLE_PAGES=policies failproofai ``` -Giá trị hợp lệ: `policies`, `projects`. +Các giá trị hợp lệ: `policies`, `projects`. --- ## Chủ đề -Bảng điều khiển hỗ trợ chế độ sáng và tối. Bật tắt qua nút trong thanh điều hướng. Tùy chọn được lưu trữ trong lưu trữ cục bộ của trình duyệt của bạn. +Bảng điều khiển hỗ trợ chế độ sáng và tối. Chuyển đổi qua nút trong thanh điều hướng. Tùy chọn được lưu trong bộ nhớ cục bộ của trình duyệt. --- ## Cấu hình đường dẫn dự án -Theo mặc định, bảng điều khiển đọc từ thư mục dự án Claude Code tiêu chuẩn. Ghi đè cho các thiết lập tùy chỉnh: +Theo mặc định, bảng điều khiển đọc từ thư mục dự án Claude Code tiêu chuẩn. Ghi đè nó cho các thiết lập tùy chỉnh: ```bash CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai @@ -114,19 +114,19 @@ 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ừ một tên máy chủ khác với `localhost` - chẳng hạn như miền tùy chỉnh, IP từ xa hoặc URL được kết nối - 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 với `localhost` - ví dụ, một tên miền tùy chỉnh, IP từ xa, hoặc URL được tạo đường hầm - bạn có thể thấy cảnh báo như: ```text ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com". ``` -Đây là Next.js chặn quyền truy cập cross-origin vào websocket HMR (hot module reload) của nó, đây là tính năng chỉ dành cho 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 truy cập xuyên nguồn gốc vào websocket HMR (hot module reload) của nó, đây là tính năng chỉ dành cho dev. Để cho phép máy chủ của bạn, 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 truyền danh sách được phân tách bằng dấu phẩy: +Đối với 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 @@ -139,5 +139,5 @@ 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ế độ sản xuất), không có websocket HMR và không có vấn đề về tài nguyên dev cross-origin. +Đ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. \ No newline at end of file diff --git a/docs/vi/getting-started.mdx b/docs/vi/getting-started.mdx index ff6cb8e9..07b19358 100644 --- a/docs/vi/getting-started.mdx +++ b/docs/vi/getting-started.mdx @@ -1,13 +1,14 @@ --- +--- title: Bắt đầu -description: "Cài đặt failproofai, bật các chính sách, và để các agent của bạn chạy một cách đáng tin cậy" +description: "Cài đặt failproofai, kích hoạt các chính sách và để các agent 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 xây dựng từ mã nguồn) +- **Bun** >= 1.3.0 (tùy chọn - chỉ cần thiết khi xây dựng từ nguồn) --- @@ -30,21 +31,25 @@ bun add -g failproofai ## Bắt đầu nhanh - - Chính sách là những quy tắc chạy trước và sau mỗi lệnh gọi công cụ của agent. Chúng bắt các lệnh xóa dữ liệu, rò rỉ bí mật, và các chế độ lỗi khác trước khi gây thiệt hại. + + Các chính sách là những quy tắc chạy trước và sau mỗi lần gọi tool của agent. Chúng bắt các lệnh phá hoại, rò rỉ bí mật và các chế độ hỏng hóc khác trước khi gây thiệt hại. ```bash failproofai policies --install ``` - Lệnh này ghi các mục hook vào các CLI agent được cài đặt của bạn (tệp `~/.claude/settings.json` của Claude Code, tệp `~/.codex/hooks.json` của OpenAI Codex, hoặc tệp `~/.copilot/hooks/failproofai.json` của GitHub Copilot CLI). Khi có nhiều hơn một tệp, bạn sẽ được nhắc; truyền `--cli claude codex copilot` (bất kỳ tập hợp con nào) để bỏ qua lời nhắc. + Lệnh này ghi các hook entries vào các CLI agent đã 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 plugin shim được tạo tại `~/.config/opencode/plugins/failproofai.mjs` cộng với một mục đăng ký trong mảng `plugin` của `~/.config/opencode/opencode.json`, Pi's `~/.pi/agent/settings.json`, hoặc Gemini CLI's `~/.gemini/settings.json`). Khi có nhiều hơn một được hiện diện, bạn sẽ được nhắc; hãy truyền `--cli claude codex copilot cursor opencode pi gemini` (bất kỳ tập hợp con nào) để bỏ qua lời nhắc. - Hỗ trợ GitHub Copilot CLI đang ở **giai đoạn thử nghiệm** — cài đặt với `--cli copilot`. + GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, và Gemini CLI support hiện đang ở **beta** — cài đặt bằng `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, hoặc `--cli gemini`. ```bash failproofai policies --install --scope project failproofai policies --install --cli codex --scope project failproofai policies --install --cli copilot --scope project + 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 block-sudo block-rm-rf sanitize-api-keys ``` @@ -53,25 +58,25 @@ bun add -g failproofai failproofai policies ``` - Hiển thị mọi chính sách, trạng thái bật/tắt của chú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 kích hoạt hay không, và bất kỳ tham số nào được cấu hình. ```bash failproofai ``` - Mở 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ý các chính sách. + 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 qua các phiên, kiểm tra các lệnh gọi tool và quản lý các 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 mà không được theo dõi và xem xét những gì đã xảy ra trong bảng điều khiển. + 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ẽ can thiệp tự động. Để nó chạy không được quan sát và xem xét những gì đã xảy ra trong bảng điều khiển. --- -## Chính sách hoạt động như thế nào +## Cách hoạt động của các chính sách -Mỗi khi agent chạy một công cụ, Claude Code gọi failproofai dưới dạng một tiến trình con: +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 @@ -83,17 +88,17 @@ 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 cho biết lý do -- **instruct** - ngữ cảnh bổ sung được thêm vào lời nhắc của agent +- **instruct** - thêm ngữ cảnh vào prompt của agent -Chính sách chạy trong quá trình cục bộ của bạn. Không có gì được gửi đến một 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 một dịch vụ từ xa. --- -## Thiết lập chính sách nhóm với chính sách dựa trên quy ước +## Thiết lập các chính sách nhóm với các chính sách dựa trên quy ước -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/`. Đưa 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ó cờ, không có thay đổi cấu hình, không có lệnh cài đặt. +Cách nhanh nhất để thiết lập các tiêu chuẩn chất lượng trên toàn nhóm của bạn là sử dụng 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ần cờ, không cần thay đổi cấu hình, không cần lệnh cài đặt. @@ -101,8 +106,8 @@ Cách nhanh nhất để thiết lập tiêu chuẩn chất lượng trên toàn mkdir -p .failproofai/policies ``` - - Sao chép các ví dụ khởi động hoặc viết của riêng bạn: + + Sao chép các ví dụ khởi đầu hoặc viết của riêng bạn: ```bash cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/ @@ -120,39 +125,39 @@ Cách nhanh nhất để thiết lập tiêu chuẩn chất lượng trên toàn 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("Chạy kiểm thử trước khi commit."); } return allow(); }, }); ``` - + ```bash git add .failproofai/policies/ - git commit -m "Add team quality policies" + git commit -m "Thêm các chính sách chất lượng của nhóm" ``` - Mỗi thành viên nhóm đã cài đặt failproofai 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. + Mỗi thành viên nhóm đã cài đặt failproofai sẽ tự động sử dụng các chính sách này. Không cần thiết lập riêng cho từng nhà phát triển. -Cam kết `.failproofai/policies/` vào kho lưu trữ 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 những 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 bản cập nhật vào 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 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ùng các tiêu chuẩn. Khi nhóm của bạn phát hiện ra các chế độ hỏng hóc mới, hãy thêm các chính sách và push — mọi người sẽ nhận được bản cập nhật vào lần `git pull` tiếp theo của họ. Theo thời gian, các chính sách này trở thành một tiêu chuẩn chất lượng sống động mà tiếp tục cải thiện. --- ## Lưu trữ dữ liệu -Tất cả cấu hình và nhật ký đều nằm trên máy của bạn: +Tất cả cấu hình và nhật ký được lưu trên máy tính của bạn: -| Đường dẫn | Những gì nó lưu trữ | +| Đường dẫn | Nó lưu trữ | |------|----------------| -| `~/.failproofai/policies-config.json` | Cấu hình chính sách toàn cầu | +| `~/.failproofai/policies-config.json` | Cấu hình chính sách toàn cục | | `~/.failproofai/hook-activity.jsonl` | Lịch sử thực thi hook | | `~/.failproofai/hook.log` | Nhật ký gỡ lỗi cho các lỗi hook tùy chỉnh | -| `.failproofai/policies-config.json` | Cấu hình cho mỗi dự án (được cam kết) | +| `.failproofai/policies-config.json` | Cấu hình cho mỗi dự án (được commit) | | `.failproofai/policies-config.local.json` | Ghi đè cá nhân (được gitignore) | --- @@ -163,16 +168,16 @@ Tất cả cấu hình và nhật ký đều nằm trên máy của bạn: failproofai policies --uninstall ``` -Xóa các mục hook khỏi `~/.claude/settings.json`. Các tệp cấu hình trong `~/.failproofai/` được giữ lại. +Xóa các hook entries từ `~/.claude/settings.json`. Các tệp cấu hình trong `~/.failproofai/` được giữ lại. --- -## Bước tiếp theo +## Các bước tiếp theo - Phạm vi và định dạng tệp cấu hình + Các phạm vi và định dạng tệp cấu hình @@ -180,11 +185,11 @@ Xóa các mục hook khỏi `~/.claude/settings.json`. Các tệp cấu hình tr - Viết các chính sách của riêng bạn trong JavaScript + Viết chính sách của riêng bạn bằng JavaScript - Giám sát phiên và xem xét hoạt động chính sách + 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