diff --git a/docs/ar/policies/builtin-catalog.mdx b/docs/ar/policies/builtin-catalog.mdx index d8405531..afda0631 100644 --- a/docs/ar/policies/builtin-catalog.mdx +++ b/docs/ar/policies/builtin-catalog.mdx @@ -1,112 +1,112 @@ --- -title: "Builtin policy catalog" -description: "Review every builtin Failproof AI policy, its trigger, recommended state, and configurable parameters." +title: "كتالوج السياسات المدمجة" +description: "اطّلع على كل سياسة مدمجة من سياسات Failproof AI، وحافزها، والحالة الموصى بها، والمعاملات القابلة للتكوين." icon: "list-checks" --- -الحزمة المثبتة هي مصدر الحقيقة لتوفر السياسات. قم بتشغيل `failproofai policies` بعد كل ترقية لأن إدخالات الكتالوج والسلوك قد يتغيران مع إصدار الحزمة. +الحزمة المثبتة هي مصدر الحقيقة لتوفر السياسات. قم بتشغيل `failproofai policies` بعد كل تحديث لأن إدخالات الكتالوج والسلوك قد يتغيران مع إصدار الحزمة. -## الأساس الموصى به +## خط الأساس الموصى به -يفعّل التحديد الموصى به من الإعداد الموجه حاليًا معقمات الأسرار وحماية البيئة والحماية الذاتية وحماية الأوامر الكارثية وسلامة الفروع المحمية: +يعمل الإعداد الموجه حالياً على تفعيل معقمات الأسرار، وحماية البيئة، الحماية الذاتية، حراس الأوامر الكارثية، وسلامة الفروع المحمية: ```text sanitize-jwt sanitize-api-keys sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars block-env-files block-secrets-write -block-self-pause block-failproofai-commands -block-sudo block-curl-pipe-sh -block-rm-rf block-push-master -block-force-push +block-failproofai-commands block-sudo +block-curl-pipe-sh block-rm-rf +block-push-master block-force-push ``` -الموصى به أضيق بقصد من **Everything**. يمكن لسياسات البنية التحتية وسير العمل أن تقاطع العمل الصحيح وينبغي تفعيلها للمستودعات والآلات التي تحتاجها. +`block-failproofai-commands` **مفعل دائماً**. تم إدراجه أعلاه لتوضيح المعلومات، لكنه يتسجل عند كل تقييم سواء ظهر في مجموعة السياسات المفعلة لديك أم لا، ولا يمكن تعطيله أو إيقافه مؤقتاً — فالحارس الذي يمكن للعامل إيقاف الإنفاذ عنه ليس حارساً. + +الموصى به مقصود أن يكون أضيق من **الكل**. سياسات البنية التحتية وسير العمل يمكن أن تقاطع العمل الصحيح وينبغي تفعيلها للمستودعات والأجهزة التي تحتاجها. ## الأسرار والبيئة -| السياسة | المُحَفِّز | النتيجة | +| السياسة | الحافز | النتيجة | | --- | --- | --- | -| `sanitize-jwt` | `PostToolUse` | تحرير JWTs من مخرجات الأداة قبل أن يراها النموذج. | -| `sanitize-api-keys` | `PostToolUse` | تحرير مفاتيح OpenAI و Anthropic و GitHub و AWS و Stripe و Google الشائعة. | -| `sanitize-connection-strings` | `PostToolUse` | تحرير سلاسل اتصال قواعد البيانات التي تحتوي على بيانات الاعتماد. | -| `sanitize-private-key-content` | `PostToolUse` | تحرير أجسام مفاتيح PEM الخاصة. | -| `sanitize-bearer-tokens` | `PostToolUse` | تحرير رموز التفويض من نوع bearer. | -| `protect-env-vars` | `PreToolUse` على أدوات shell | حظر الأوامر التي تفرغ متغيرات البيئة. | -| `block-env-files` | `PreToolUse` | حظر قراءة وكتابة ملفات `.env`. | -| `block-read-outside-cwd` | `PreToolUse` على قراءة أو glob أو grep أو أدوات shell | إبقاء القراءات داخل دليل عمل الجلسة. | -| `block-secrets-write` | `PreToolUse` على أدوات الكتابة | حظر الكتابة إلى أسماء ملفات مفاتيح الأسرار وبيانات الاعتماد الشائعة. | - -## الأوامر الخطرة والبنية التحتية - -| السياسة | المُحَفِّز | النتيجة | +| `sanitize-jwt` | `PostToolUse` | إخفاء JWTs من مخرجات الأدوات قبل أن يراها النموذج. | +| `sanitize-api-keys` | `PostToolUse` | إخفاء مفاتيح OpenAI و Anthropic و GitHub و AWS و Stripe و Google الشائعة. | +| `sanitize-connection-strings` | `PostToolUse` | إخفاء سلاسل اتصال قواعد البيانات التي تحتوي على بيانات اعتماد. | +| `sanitize-private-key-content` | `PostToolUse` | إخفاء أجسام مفاتيح PEM الخاصة. | +| `sanitize-bearer-tokens` | `PostToolUse` | إخفاء رموز الترخيص. | +| `protect-env-vars` | `PreToolUse` على أدوات الغلاف | منع الأوامر التي تفرغ متغيرات البيئة. | +| `block-env-files` | `PreToolUse` | منع قراءة وكتابة ملفات `.env`. | +| `block-read-outside-cwd` | `PreToolUse` على أدوات القراءة أو glob أو grep أو shell | إبقاء القراءة داخل دليل العمل للجلسة. | +| `block-secrets-write` | `PreToolUse` على أدوات الكتابة | منع الكتابة إلى أسماء ملفات المفاتيح السرية والبيانات الاعتمادية الشائعة. | + +## الأوامر الخطيرة والبنية التحتية + +| السياسة | الحافز | النتيجة | | --- | --- | --- | -| `block-self-pause` | `PreToolUse`, `PermissionRequest` | منع الوكيل من إيقاف إنفاذه الخاص. | -| `block-sudo` | `PreToolUse`, `PermissionRequest` | حظر `sudo` إلا إذا طابق نمط السماح. | -| `block-curl-pipe-sh` | `PreToolUse` | حظر البرامج النصية المُحملة الموجهة مباشرة إلى shell. | -| `block-rm-rf` | `PreToolUse` | حظر أنماط الحذف العودية الكارثية. | -| `block-failproofai-commands` | `PreToolUse` | منع الوكلاء من تغيير أو إلغاء تثبيت Failproof AI. | -| `block-kubectl` | `PreToolUse` | التحكم في أوامر Kubernetes. | -| `block-terraform` | `PreToolUse` | التحكم في أوامر Terraform و OpenTofu. | -| `block-aws-cli` | `PreToolUse` | التحكم في أوامر AWS CLI. | -| `block-gcloud` | `PreToolUse` | التحكم في أوامر Google Cloud CLI. | -| `block-az-cli` | `PreToolUse` | التحكم في أوامر Azure CLI. | -| `block-helm` | `PreToolUse` | التحكم في أوامر Helm. | -| `block-gh-pipeline` | `PreToolUse` | التحكم في عمليات GitHub CLI الطفيفة في سير العمل والتشغيل والدمج والإصدار والذاكرة والسر. | +| `block-sudo` | `PreToolUse`, `PermissionRequest` | منع `sudo` إلا إذا تطابق نمط السماح. | +| `block-curl-pipe-sh` | `PreToolUse` | منع النصوص البرمجية المحملة الموجهة مباشرة إلى الغلاف. | +| `block-rm-rf` | `PreToolUse` | منع أنماط الحذف العودية الكارثية. | +| `block-failproofai-commands` | `PreToolUse`, `PermissionRequest` | **مفعل دائماً، لا يمكن تعطيله.** منع كل استدعاء CLI من Failproof AI، والإيقاف الذاتي، وإلغاء تثبيت مدير الحزم. | +| `block-kubectl` | `PreToolUse` | حماية أوامر Kubernetes. | +| `block-terraform` | `PreToolUse` | حماية أوامر Terraform و OpenTofu. | +| `block-aws-cli` | `PreToolUse` | حماية أوامر AWS CLI. | +| `block-gcloud` | `PreToolUse` | حماية أوامر Google Cloud CLI. | +| `block-az-cli` | `PreToolUse` | حماية أوامر Azure CLI. | +| `block-helm` | `PreToolUse` | حماية أوامر Helm. | +| `block-gh-pipeline` | `PreToolUse` | حماية عمليات GitHub CLI الطافرة لسير العمل والتشغيل والدمج والإصدار والذاكرة والعمليات السرية. | ## سلامة Git وقاعدة البيانات -| السياسة | المُحَفِّز | النتيجة | +| السياسة | الحافز | النتيجة | | --- | --- | --- | -| `block-push-master` | `PreToolUse` | حظر الدفع المباشر إلى الفروع المحمية المُعَدَّة. | -| `block-force-push` | `PreToolUse` | حظر الدفع القسري؛ يبقى `--force-with-lease` مسموحًا بالتنفيذ الحالي. | -| `block-work-on-main` | `PreToolUse` | حظر الالتزامات والدمجات على الفروع المحمية. | -| `warn-git-amend` | `PreToolUse` | تحذير قبل إعادة كتابة التزام مع `--amend`. | -| `warn-git-stash-drop` | `PreToolUse` | تحذير قبل حذف أو مسح المخزن المؤقت بشكل دائم. | +| `block-push-master` | `PreToolUse` | منع الدفع المباشر إلى الفروع المحمية المُعدَّلة. | +| `block-force-push` | `PreToolUse` | منع الدفع القسري؛ يبقى `--force-with-lease` مسموحاً بالتطبيق الحالي. | +| `block-work-on-main` | `PreToolUse` | منع الالتزامات والدمج على الفروع المحمية. | +| `warn-git-amend` | `PreToolUse` | تحذير قبل إعادة كتابة التزام باستخدام `--amend`. | +| `warn-git-stash-drop` | `PreToolUse` | تحذير قبل حذف أو مسح المخزن المؤقت نهائياً. | | `warn-all-files-staged` | `PreToolUse` | تحذير على `git add -A` أو `git add .` أو `git add --all` الواسع. | -| `warn-destructive-sql` | `PreToolUse` | تحذير على `DROP` و `TRUNCATE` و `DELETE` بدون `WHERE` عبر عملاء قاعدة البيانات المعروفة. | -| `warn-schema-alteration` | `PreToolUse` | تحذير على عمليات `ALTER TABLE` للعمود وإعادة التسمية المعروفة. | +| `warn-destructive-sql` | `PreToolUse` | تحذير على `DROP` و `TRUNCATE` و `DELETE` بدون `WHERE` من خلال عملاء قواعد البيانات المعروفة. | +| `warn-schema-alteration` | `PreToolUse` | تحذير على عمليات `ALTER TABLE` المعروفة لأعمدة وإعادة تسمية. | -## الحزم وسلوك النظام وحلقات الوكيل +## الحزم وسلوك النظام وحلقات العامل -| السياسة | المُحَفِّز | النتيجة | +| السياسة | الحافز | النتيجة | | --- | --- | --- | -| `warn-package-publish` | `PreToolUse` | تحذير قبل النشر إلى سجلات الحزم. | -| `warn-global-package-install` | `PreToolUse` | تحذير قبل التثبيت العام للحزم. | -| `prefer-package-manager` | `PreToolUse` | إرشاد الوكيل لاستخدام مدير حزم مسموح. | -| `warn-large-file-write` | `PreToolUse` على أدوات الكتابة | تحذير فوق حد حجم الملف المُعَدَّ. | -| `warn-background-process` | `PreToolUse` | تحذير على أنماط العمليات الخلفية المنفصلة أو طويلة الأمد. | -| `warn-repeated-tool-calls` | `PreToolUse` | تحذير بعد ثلاث مكالمات أداة متطابقة أو أكثر. | +| `warn-package-publish` | `PreToolUse` | تحذير قبل النشر إلى السجلات. | +| `warn-global-package-install` | `PreToolUse` | تحذير قبل التثبيت العام للحزمة. | +| `prefer-package-manager` | `PreToolUse` | إرشاد العامل لاستخدام مدير حزم مسموح. | +| `warn-large-file-write` | `PreToolUse` على أدوات الكتابة | تحذير فوق حد حجم الملف المُعدَّل. | +| `warn-background-process` | `PreToolUse` | تحذير على أنماط العمليات الخلفية المنفصلة أو طويلة العمر. | +| `warn-repeated-tool-calls` | `PreToolUse` | تحذير بعد ثلاث مكالمات أدوات متطابقة أو أكثر. | ## سير عمل نهاية المهمة -تتطلب هذه السياسات جهازًا يصدر حدث `Stop` متوافقًا. +تتطلب هذه السياسات حزام يصدر حدث `Stop` متوافق. | السياسة | النتيجة | | --- | --- | -| `require-commit-before-stop` | رفض الإكمال بينما يبقى العمل المتتبع غير مرتكب. | -| `require-push-before-stop` | رفض الإكمال بينما تبقى الالتزامات محلية فقط. | -| `require-pr-before-stop` | مطلوب طلب دمج للفرع الحالي. | -| `require-no-conflicts-before-stop` | مطلوب دمج نظيف ضد فرع القاعدة المُعَدَّ. | -| `require-ci-green-before-stop` | مطلوب إكمال فحوصات CI للرأس الحالي بنجاح. | +| `require-commit-before-stop` | رفض الإنجاز بينما يبقى العمل المتتبع غير ملتزم. | +| `require-push-before-stop` | رفض الإنجاز بينما تبقى الالتزامات محلية فقط. | +| `require-pr-before-stop` | طلب طلب دمج للفرع الحالي. | +| `require-no-conflicts-before-stop` | طلب دمج نظيف مقابل فرع القاعدة المُعدَّل. | +| `require-ci-green-before-stop` | طلب اكتمال فحوصات CI في HEAD الحالي بنجاح. | ## مرجع المعاملات -قم بتكوين المعاملات ضمن كائن `policyParams` للنطاق المحدد. يتم التحقق من الأنواع بواسطة كل سياسة. +قم بتكوين المعاملات تحت كائن `policyParams` للنطاق المحدد. يتم التحقق من الأنواع من قبل كل سياسة. | السياسة | المعامل | النوع والافتراضي | | --- | --- | --- | -| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; تحتوي الإدخالات على `regex` و `label` | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`؛ الإدخالات تحتوي على `regex` و `label` | | `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | | `block-sudo` | `allowPatterns` | `string[]`, `[]` | | `block-rm-rf` | `allowPaths` | `string[]`, `[]` | -| Infrastructure blockers | `allowPatterns` | `string[]`, `[]` | +| حاجبات البنية التحتية | `allowPatterns` | `string[]`, `[]` | | `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | | `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | | `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | | `prefer-package-manager` | `allowed`, `blocked` | `string[]`, `[]` | | `warn-large-file-write` | `thresholdKb` | `number`, `1024` | -| `require-push-before-stop` | `remote`, `baseBranch` | `string`, `"origin"`; `string`, `"main"` | +| `require-push-before-stop` | `remote`, `baseBranch` | `string`, `"origin"`؛ `string`, `"main"` | | `require-pr-before-stop` | `baseBranch` | `string`, `"main"` | | `require-no-conflicts-before-stop` | `baseBranch` | `string`, `"main"` | @@ -125,5 +125,5 @@ block-force-push ``` - نمط السماح يوسع ما قد يفعله الوكيل. اختبر الترميز الدقيق وأشكال الأوامر على جهاز الهدف قبل نشره عبر الأسطول. + نمط السماح يوسّع ما قد يفعله العامل. اختبر الرمزنة الدقيقة وأنماط الأوامر على الحزام المستهدف قبل نشره عبر الأسطول. \ No newline at end of file diff --git a/docs/ar/policies/failure-behavior.mdx b/docs/ar/policies/failure-behavior.mdx index 4386f396..a75a67cb 100644 --- a/docs/ar/policies/failure-behavior.mdx +++ b/docs/ar/policies/failure-behavior.mdx @@ -1,19 +1,20 @@ --- +--- title: "سلوك الفشل" -description: "افهم ما يحدث عندما يكون تقييم السياسة أو مستودع الملفات المحلي غير متاح." +description: "افهم ما يحدث عند عدم توفر تقييم السياسة أو daemon المحلي." icon: "shield-alert" --- -تم تصميم Failproof AI بحيث يكون فشل الإنفاذ مرئياً بدلاً من السماح بصمت بعمل محفوف بالمخاطر. +تم تصميم Failproof AI بحيث يكون فشل الإنفاذ مرئياً بدلاً من السماح الصامت بعمل محفوف بالمخاطر. -## تشخيص كتلة الفشل المغلقة +## تشخيص كتلة مغلقة الفشل - 1. انتقل إلى **Admin → enforcement** وافتح الجهاز. - 2. تحقق من آخر تسجيل دخول له والنشر المعين والنشر المبلغ عنه. + 1. انتقل إلى **Admin → enforcement** وافتح الآلة. + 2. تحقق من آخر تسجيل دخول، والنشر المعين، والنشر المبلغ عنه. 3. انتقل إلى **Observe → policy** وافتح جلسة القرار المرفوض. - 4. تأكد مما إذا كان السبب يبلغ عن إمكانية الوصول إلى مستودع الملفات أو عدم تطابق الإصدار أو السياسة نفسها. + 4. تأكد مما إذا كان السبب يشير إلى إمكانية الوصول إلى daemon أم عدم التطابق في الإصدار أم السياسة نفسها. @@ -23,21 +24,45 @@ icon: "shield-alert" failproofai config ``` - إعادة تشغيل `failproofai config` تحدّث وتعيد تشغيل مستودع الملفات بعد ترقية الحزمة. + إعادة تشغيل `failproofai config` يحدّث ويعيد تشغيل daemon بعد ترقية الحزمة. -على جهاز تم تكوينه للاستخدام مع `failproofaid`، مستودع الملفات هو المقيّم الوحيد. إذا كان غير قابل للوصول أو كان إصدار البروتوكول الخاص به غير متطابق مع CLI، يفشل تقييم الخطاف بشكل مغلق. يتم رفض الإجراء مع سبب يوجه المشغل للتحقق من مستودع الملفات أو تحديثه. +على آلة تم تكوينها لاستخدام `failproofaid`، يكون daemon هو المقيّم الوحيد. إذا كان غير قابل للوصول أو كان إصدار البروتوكول الخاص به لا يطابق CLI، يفشل تقييم hook بشكل مغلق. يتم رفض الإجراء مع سبب يوجه المشغل إلى التحقق من daemon أو تحديثه. -قبل تكوين مستودع الملفات، تقيّم الخطاطيف السياسات في العملية. بمجرد تسجيل تكوين مستودع الملفات، لا يعود Failproof AI إلى مقيّم ثانٍ بصمت عند فشل مستودع الملفات. +قبل تكوين daemon، تقيّم hooks السياسات أثناء المعالجة. بمجرد تسجيل تكوين daemon، لا يعود Failproof AI إلى تقييم ثاني بصمت عند فشل daemon. -## الرد على قرار الفشل المغلق +## الاستجابة لقرار مغلق الفشل 1. قم بتشغيل `failproofai config --status`. 2. إذا اختلفت الإصدارات، أعد تشغيل `failproofai config` بعد تحديث الحزمة. -3. إذا كان مستودع الملفات غير قابل للوصول، افحص حالة خدمته والسجلات المحلية. -4. استأنف عمل الوكيل فقط بعد التحقق من صحة مسار تقييم السياسة المعروف. +3. إذا كان daemon غير قابل للوصول، افحص حالة الخدمة وسجلات الملف الشخصي المحلي. +4. استأنف عمل agent فقط بعد التأكد من أن مسار تقييم السياسة المعروف سليم. - لا تعيد محاولة الإجراء المحظور بشكل متكرر. رد الفشل المغلق يعني أن النظام لم يتمكن من التأكد من أن الإجراء كان آمناً. - \ No newline at end of file + لا تحاول تكرار الإجراء المحظور بشكل متكرر. استجابة مغلقة الفشل تعني أن النظام لم يتمكن من إثبات أن الإجراء كان آمناً. + + +## لن يتم تحميل الحزمة + +آلة تم إخبارها بفرض حزمة، ولا يمكنها تشغيلها، ترفض بدلاً من المتابعة بصمت. المحفز هو **توقع مسجل**، وليس توقع فارغ: آلة بدون حزم مثبتة تكون صامتة، بينما حزمة تم إعلانها ولن تُحل — أو تسجل أقل من ما يعلنه البيان الخاص بها — ترفض. + +الرفض **ضيق**، على عكس daemon غير قابل للوصول. daemon الذي لا يمكن الوصول إليه يعني أنه لم يحدث أي تقييم على الإطلاق، لذلك لا يمكن معرفة شيء آمن. حزمة لن تتحمل لديها مجموعة قابلة للعد من الحراس المفقودين، لأن كل سياسة معلنة تحمل `match` خاصة بها — لذلك ترفض فقط الأحداث والأدوات التي غطتها تلك السياسات، وكل شيء آخر يمضي قدماً. + +لا تنطلق بسبب: + +- حزمة `observe`، التي تقيّم وتتجاهل بالبناء +- سياسات لم تأخذها، أو أوقفتها بشكل صريح +- حزمة لم يتلقاها المحمّل، حيث لا يمكن التمييز بين «لا تسجيلات» و تخطي متعمد +- توقف جلسة نشطة +- مهلة زمنية للتحميل، وهي عابرة — لحظة قرص واحدة بطيئة يجب ألا ترفض حتى يتدخل إنسان + +`UserPromptSubmit` **توجه** بدلاً من الرفض، مهما أعلنت السياسة المفقودة. رفض شامل سيأخذ معه ويغلقك خارج agent الذي يمكنه إصلاح المشكلة. + +### ماذا تفعل + +```bash +failproofai pack list +``` + +يسمي أي حزمة مثبتة لن يتم تحميلها، ويقول السبب، ويخرج برمز غير صفر. ثم إما أعد تثبيتها (`failproofai pack add `) أو أزلها (`failproofai pack remove `) — إزالتها تسحب التوقع، والرفض يتوقف معها. \ No newline at end of file diff --git a/docs/ar/policies/packs.mdx b/docs/ar/policies/packs.mdx new file mode 100644 index 00000000..ed48e435 --- /dev/null +++ b/docs/ar/policies/packs.mdx @@ -0,0 +1,110 @@ +--- +title: "حزم السياسات" +description: "قم بتثبيت مجموعة من السياسات المنشورة كإصدار GitHub، وأدر ما تفرضه." +icon: "package" +--- + +الحزمة عبارة عن مجموعة من السياسات المنشورة كإصدار GitHub. أمر واحد يثبتها، ويتم التحقق من قيم تجزئة الإصدار قبل تشغيل أي شيء، ويتم تسجيل البصمة بحيث لا يمكن للحزمة أن تتغير على جهازك بعد ذلك. + +## قم بتثبيت سياسات Failproof AI + +```bash +failproofai pack add core +``` + +هذا يثبت المجموعة التي ننشرها، من النسخة داخل الحزمة — لذلك لا تحتاج إلى شبكة ولا يمكن أن تفشل خلف وكيل. خذ جزءًا منها: + +```bash +failproofai pack add core --policy block-rm-rf # واحدة، أو عدة مفصولة بفواصل +failproofai pack add core --category dangerous-commands # فئة كاملة +failproofai pack add core --all # كل شيء فيها +``` + +يسمي `failproofai pack list` كل فئة تقدمها الحزمة. + +## اطلع على محتويات الحزمة، قبل تثبيتها + +```bash +failproofai pack list acme/support-agent +``` + +يسرد كل سياسة تحملها الحزمة، مجمعة حسب الفئة، مع تحديد أيها يفعّلها مؤلفها افتراضيًا وأيها اختيارية. يقرأ **البيان فقط** — لا يتم أبدًا تنزيل القطعة الرئيسية ولا استيرادها، لذا فإن النظر إلى حزمة غريب لا يمكن أن يشغل كود غريب. البيان لا يزال يتحقق منه مقابل `SHA256SUMS` الخاص بالإصدار، لذا ما تقرأه هو ما سيتم تثبيته. + +يسرد `failproofai pack list` بدون مصدر الحزم المثبتة بالفعل هنا. + +## قم بتثبيت حزمة شخص آخر + +```bash +failproofai pack add acme/support-agent +``` + +أي من هذه تعمل — الصق أيًا منها لديك: + +| المصدر | النتيجة | +| --- | --- | +| `acme/support-agent` | أحدث إصدار، **محدد** بالعلامة الدقيقة التي تم حلها | +| `acme/support-agent@v2.1.0` | هذا الإصدار | +| `github:acme/support-agent@v2.1.0` | نفس الشيء، مكتوب بوضوح | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | نفس الشيء، تم نسخه من متصفح | + +عدم تسمية علامة يثبت أحدث إصدار **ويحددها**، ثم يخبرك بالعلامة التي اختارها. ما يتم تسجيله دائمًا يسمي بالضبط إصدارًا واحدًا، لذا لا يمكن لإعادة التثبيت أن تنجرف. + +## خذ جزءًا من الحزمة + +بشكل افتراضي تحصل على **الافتراضيات الخاصة** بالحزمة — السياسات التي وضع مؤلفها علامة عليها آمنة للتشغيل دون مراقبة — وليس كل ما تحتويه. + +```bash +failproofai pack add acme/support-agent --category billing,git +failproofai pack add acme/support-agent --policy block-refunds +failproofai pack add acme/support-agent --all +``` + +يتم دمج `--category` و `--policy` كاتحاد (`--only` مقبول كمرادف لـ `--policy`). إضافة مجددًا بإصدار أحدث تحتفظ بما اخترته بدلاً من إعادة تشغيل الباقي. + +## أدر ما هو قيد التشغيل + +```bash +failproofai policies # كل مصدر في قائمة واحدة، الحزم مضمنة +failproofai pack list # الحزم فقط، مجمعة حسب الفئة +failproofai policies --uninstall block-refunds # أوقف سياسة حزمة واحدة +failproofai policies --install block-refunds # وإعادة تشغيلها +failproofai pack remove acme/support-agent +``` + +الاسم العادي يعني **المدمج** عندما يكون موجودًا بهذا الاسم. اذكر نسخة الحزمة بوضوح عندما تحتاج إلى: + +```bash +failproofai policies --uninstall acme/support-agent:block-refunds +``` + + +إذا كانت الحزمة تشحن سياسة اسمها هو أيضًا **مدمج مفعّل**، يتم تشغيل المدمج وتخطي نسخة الحزمة — سيتم تقييم نفس الحماية مرتين وإلا. أوقف المدمج لاستخدام نسخة الحزمة بدلاً من ذلك. + + +## من أين تأتي سياسات Failproof AI + +يقرأ `core` النسخة المدرجة في حزمة npm. نفس المجموعة منشورة كإصدار GitHub، وهو ما تثبته إذا كنت تريد إصدارًا محددًا: + +```bash +failproofai pack add core # من هذه الحزمة، بدون شبكة +failproofai pack add FailproofAI/policies # نفس المجموعة، من إصدار GitHub الخاص بها +``` + +## ما الذي توفره السلامة الكاملة وما الذي لا توفره + +`SHA256SUMS` مرسلة في نفس الإصدار مثل القطعة، لذا فهي **ليست** توقيعًا ولا تثبت شيئًا عن هوية ناشرها. ما تثبته هو أن البايتات هي الموجودة في ذلك الإصدار — وبسبب تسجيل البصمة عند إضافة الحزمة وإعادة التحقق منها قبل كل استيراد، لا يمكن للحزمة أن تتغير على جهازك بعد ذلك. يتوقف المستودع الذي يُعيد وسم أو يستبدل أحد الأصول عن التحميل بدلاً من تشغيل شيء آخر بهدوء. + +في وقت التثبيت، يتم أيضًا **استيراد الحزمة مرة واحدة** والتحقق منها مقابل بيانها الخاص. يتم رفض الحزمة التي لا يمكن تحليل قطعتها أو التي تسجل شيئًا مختلفًا عما تعلنه قبل تفعيل أي شيء — بدلاً من التثبيت بنجاح والفشل في استدعاء الأداة التالية. + +## عندما لن تحميل الحزمة + +الحزمة التي تم إخبار هذا الجهاز بفرضها ولا يمكنه تشغيلها **ترفض** الأحداث التي غطتها سياساته المفقودة، بدلاً من السماح بها صمتًا. انظر [سلوك الفشل](/ar/policies/failure-behavior). `failproofai pack list` يسمي أي حزمة في تلك الحالة ويخرج بقيمة غير صفرية. + +## بلا اتصال والمرايا + +| المتغير | التأثير | +| --- | --- | +| `FAILPROOFAI_NO_DOWNLOAD=1` | يرفض الجلب؛ الحزم المثبتة بالفعل تستمر في الفرض | +| `FAILPROOFAI_PACK_BASE_URL` | يوجه جلب الحزم إلى مرآة بدلاً من `github.com` | + +نشر حزمتك الخاصة: انظر [نشر حزمة](/ar/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/ar/policies/publish-a-pack.mdx b/docs/ar/policies/publish-a-pack.mdx new file mode 100644 index 00000000..df91a432 --- /dev/null +++ b/docs/ar/policies/publish-a-pack.mdx @@ -0,0 +1,92 @@ +--- +--- +title: "نشر حزمة" +description: "شحن سياساتك الخاصة كإصدار GitHub يمكن لأي شخص تثبيته." +icon: "upload" +--- + +الحزمة عبارة عن ثلاثة ملفات مرفقة بإصدار GitHub. يكتب `failproofai pack build` جميع الثلاثة من ملف سياسة لديك بالفعل. + +## 1. اكتب السياسات + +ملف واحد، يستخدم نفس الواجهة البرمجية لأي سياسة مخصصة. يهمان حقلان إضافيان للحزمة: + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-refunds", + description: "Refunds above the approved limit need a human", + category: "Billing", // groups it, and is what --category selects on + defaultEnabled: true, // switched on by a plain `pack add` + match: { events: ["PreToolUse"], tools: ["Bash"] }, + fn: async (ctx) => + String(ctx.toolInput?.command ?? "").includes("refund") + ? deny("Refunds need a human. Ask before running this.") + : allow(), +}); +``` + +يتم تعيين `defaultEnabled` افتراضيًا إلى **false** عند حذفه. `failproofai pack add` البسيط يقوم بتشغيل فقط ما حددته — تثبيت كل سياسة من سياسات الغريب دون مراقبة ليست قرارًا يجب على المثبت أن يتخذه للمستخدم. + + +يجب أن يكون الإدخال **ملف واحد مكتفٍ بذاته**. فقط الإدخال هو ما يتم تثبيت الخلاصة عليه، لذا فإن حزمة تستورد ملفات محلية لا يمكنها بصراحة المطالبة بأن الخلاصة تغطي ما يعمل. قم بالدمج أولاً (`esbuild` أو `bun build` أو `rollup`) وأنشئ الحزمة من الحزمة المدمجة — يرفض `pack build` الاستيراد المحلي بدلاً من شحن وعد لا يمكنه الوفاء به. + + +## 2. بناء أصول الإصدار + +```bash +failproofai pack build ./policies.mjs \ + --id acme/support-agent \ + --version 1.0.0 \ + --out ./dist-pack +``` + +يكتب ثلاثة ملفات ويتحقق من صحة كل سياسة باستخدام **قواعد المُحمِّل الخاصة** أولاً — لذا فإن الحزمة التي لن تتمكن من التثبيت تفشل هنا، حيث يمكنك إصلاحها: + +| الملف | ما هو | +| --- | --- | +| `failproofai-pack.json` | البيان: المعرّف والإصدار والتأثير وإدخال واحد لكل سياسة | +| `failproofai-pack.mjs` | إدخالك، كما هو حرفيًا | +| `SHA256SUMS` | ` ` للملفين الآخرين | + +تم الرفض عند وقت البناء: معرف ليس `publisher/name`، اسم سياسة يحتوي على `/`، سياسة تعلن `alwaysOn`، وصف مفقود أو `category` أو `match`، إدخال لا يسجل أي شيء، وإدخال يستورد ملفات محلية. + +## 3. أرفقها بإصدار + +ضع علامة على الإصدار بنفس الإصدار الذي أنشأته، وأرفق جميع الملفات الثلاثة كأصول الإصدار: + +```bash +gh release create 1.0.0 \ + ./dist-pack/failproofai-pack.json \ + ./dist-pack/failproofai-pack.mjs \ + ./dist-pack/SHA256SUMS +``` + +يمكن لأي شخص الآن تثبيته: + +```bash +failproofai pack add acme/support-agent +``` + +أسماء الأصول ثابتة — وهي ما ينشئها CLI الخاص بالمستهلك من عناوين URL الخاصة به، بدون استدعاء API وبدون اكتشاف. + +## شحن إصدار جديد + +قم بالبناء باستخدام `--version` الجديد، وضع علامة على إصدار جديد، وأرفق الأصول الثلاثة مرة أخرى. يقوم المستهلكون بتشغيل نفس `pack add` والاحتفاظ بأي مجموعة اختاروها؛ تبقى السياسة التي أطفأوها مطفأة عبر الترقية. + +تغيير **اسم** السياسة هو تغيير كسر: جهاز قام بإيقاف تشغيله يقوم بإيقاف تشغيل اسم لم يعد موجودًا، والاسم الجديد يصل إلى أيًا كان `defaultEnabled` يقول. + +## ما يثق به المستخدمون + +`SHA256SUMS` يعيش في نفس الإصدار مثل الأصل، لذا فإنه يثبت أن البايتات هي تلك التي نشرتها — وليس من أنت. أي شخص يمكنه الكتابة إلى المستودع يمكنه كتابة كلا الملفين. حماية المستخدمين هي أن الخلاصة يتم تثبيتها عند التثبيت، بحيث لا يمكن لما شحنته أن يتغير تحتهم بعد ذلك. + +قم بالنشر من مستودع يمكنك التحكم في الوصول الكتابي إليه، وتعامل مع إصدار حزمة مثل نشر حزمة. + +## راقب قبل أن تفرض + +قد يعلن البيان عن `"effect": "observe"`. تعمل تلك السياسات وتُسجل أحكامها **وتُرفض** — لا شيء محجوب. إنها الطريقة لقياس قاعدة جديدة مقابل حركة المرور الحقيقية قبل أن تتمكن من مقاطعة عمل أي شخص. + +```json +{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +``` \ No newline at end of file diff --git a/docs/ar/reference/failproof-cli.mdx b/docs/ar/reference/failproof-cli.mdx index ea5391a4..190f1349 100644 --- a/docs/ar/reference/failproof-cli.mdx +++ b/docs/ar/reference/failproof-cli.mdx @@ -1,14 +1,14 @@ --- -title: "واجهة سطر الأوامر Failproof AI" -description: "تثبيت الخطافات، إدارة السياسات المحلية، الاتصال بالسحابة، وتشغيل خادم الويب المحلي." +title: "واجهة سطر أوامر Failproof AI" +description: "تثبيت الخطافات وإدارة السياسات المحلية والاتصال بالسحابة وتشغيل خادم محلي." icon: "terminal" --- -قم بتثبيت واجهة سطر الأوامر المحلية باستخدام `npm install -g failproofai`. قم بتشغيلها بدون وسائط لفتح لوحة التحكم للسياسات المحلية. +قم بتثبيت واجهة سطر الأوامر المحلية باستخدام `npm install -g failproofai`. قم بتشغيلها بدون وسيطات لفتح لوحة معلومات السياسات المحلية. -تتطلب الحزمة Node.js 20.9 أو الإصدار الأحدث. Bun 1.3 أو الإصدار الأحدث مدعوم للتطوير والتثبيتات من المصدر. `failproofai configure` و`failproofai setup` هي بدائل لـ `failproofai config`؛ `failproofai p` هي بديل لـ `failproofai policies`. +تتطلب الحزمة Node.js 20.9 أو أحدث. يتم دعم Bun 1.3 أو أحدث للتطوير والتثبيت من المصدر. `failproofai configure` و `failproofai setup` هما أسماء مستعارة لـ `failproofai config`؛ `failproofai p` اسم مستعار لـ `failproofai policies`. -## إعداد الجهاز +## إعداد جهاز ```bash npm install -g failproofai @@ -20,64 +20,69 @@ failproofai policies --install failproofai config --status ``` -قم بتشغيل `failproofai` بدون وسائط لفتح لوحة التحكم للسياسات المحلية. +قم بتشغيل `failproofai` بدون وسيطات لفتح لوحة معلومات السياسات المحلية. | الأمر | النتيجة | | --- | --- | | `failproofai config` | تشغيل إعداد الجهاز التفاعلي | -| `failproofai config --connect --token ` | الاتصال بسحابة استقبال البيانات وتسليم السياسات | +| `failproofai config --connect --token ` | الاتصال بالسحابة وتسليم السياسات | | `failproofai config --status` | عرض حالة الاتصال والخادم والتسليم والإيقاف المؤقت | -| `failproofai policies` | قائمة السياسات المدمجة والمخصصة | +| `failproofai policies` | قائمة السياسات المدمجة والمخصصة والمتفق عليها والحزم والمدارة من السحابة | | `failproofai policies --install` | تثبيت الخطافات وتفعيل السياسات | -| `failproofai policy add ` | تفعيل سياسة مدمجة واحدة | -| `failproofai policy remove ` | تعطيل سياسة مدمجة واحدة | +| `failproofai policy add ` | تفعيل سياسة واحدة — مدمجة أو `:` من حزمة مثبتة | +| `failproofai policy remove ` | تعطيل سياسة واحدة بنفس التسمية | | `failproofai policies --uninstall` | تعطيل السياسات أو إزالة خطافات الهيكل | -| `failproofai audit` | مسح سجل الوكيل المحلي وفتح عرض التدقيق المحلي | -| `failproofai audit --schedule [days] --email
` | جدولة عمليات مسح محلية متكررة وإرسال النتائج عبر البريد الإلكتروني | +| `failproofai pack list` | قائمة حزم السياسات المثبتة وكل سياسة في كل واحدة | +| `failproofai pack add ` | تثبيت حزمة سياسة من إصدار GitHub؛ بدون علامة يأخذ الأحدث ويثبتها | +| `failproofai pack add --bundled` | تثبيت السياسات المدمجة كحزمة من هذه الحزمة بدون شبكة | +| `failproofai pack build ` | بناء ثلاثة موارد إصدار لحزمة خاصة بك | +| `failproofai pack remove ` | إلغاء تفعيل حزمة مثبتة | +| `failproofai audit` | فحص السجل المحلي للوكيل وفتح عرض التدقيق المحلي | +| `failproofai audit --schedule [days] --email
` | جدولة عمليات مسح محلية متكررة وإرسال نتائجها بالبريد الإلكتروني | | `failproofai audit --status` | عرض عنوان التقرير والفاصل الزمني والمسح المجدول التالي | -| `failproofai audit --no-schedule` | إيقاف عمليات المسح المتكررة دون حذف سجل التدقيق | -| `failproofai harness list` | قائمة المسارات الإضافية للالتقاط | +| `failproofai audit --no-schedule` | إيقاف المسح المتكرر بدون حذف سجل التدقيق | +| `failproofai harness list` | قائمة مسارات المقارنة الإضافية | | `failproofai flush --wait` | تسليم ملف الأحداث الحالي | -| `failproofai backfill --since 30d` | إعادة قراءة السجل السابق الذي تم تمريره | -| `failproofai config --pause [duration]` | إيقاف جلسة محلية واحدة مؤقتاً لمدة 30 دقيقة افتراضياً، حتى 8 ساعات | -| `failproofai config --resume` | استئناف جلسة محلية معلقة واحدة؛ أضف `--all` لإزالة جميع الإيقافات المؤقتة | +| `failproofai backfill --since 30d` | إعادة قراءة السجل السابق المنقول | +| `failproofai config --pause [duration]` | إيقاف جلسة محلية واحدة لمدة 30 دقيقة افتراضياً، حتى 8 ساعات | +| `failproofai config --resume` | استئناف جلسة محلية مؤقوفة؛ أضف `--all` لمسح جميع الإيقافات | | `failproofai update` | إنهاء ترحيلات الحزمة وتحديث الخادم | -| `failproofai migrate --dry-run` | معاينة أو تشغيل ترحيلات تخطيط المنزل المعلقة | +| `failproofai migrate --dry-run` | معاينة أو تشغيل ترحيلات التخطيط المنزلي المعلقة | | `failproofai uninstall` | إزالة الخطافات والخادم قبل إزالة الحزمة | | `failproofai --version` | طباعة إصدار الحزمة المثبتة | | `failproofai --help` | عرض الأوامر والاستخدام العام | -## علامات التكوين +## أعلام التكوين | العلم | الاستخدام | | --- | --- | | `--connect --token ` | الاتصال بشكل غير تفاعلي | | `--machine-id ` | تعيين معرف الجهاز المستقر | -| `--machine-label ` | تعيين أو تغيير تسمية لوحة التحكم | -| `--no-transcripts` | إرسال القرارات بدون محتوى النص | -| `--disconnect` | إيقاف سحب سياسات السحابة وتسليم الأحداث | +| `--machine-label ` | تعيين أو تغيير تسمية لوحة المعلومات | +| `--no-transcripts` | إرسال القرارات بدون محتوى النصوص | +| `--disconnect` | إيقاف سحب سياسة السحابة وتسليم الأحداث | | `--status` | عرض حالة الجهاز الحالية | -| `--pause [duration]` | إيقاف أحدث جلسة في المجلد الحالي مؤقتاً؛ تقبل الثواني أو الدقائق أو الساعات وتفترض 30 دقيقة | -| `--resume` | إنهاء إيقاف مطابق مبكراً | +| `--pause [duration]` | إيقاف الجلسة الأحدث في المجلد الحالي؛ يقبل ثوان أو دقائق أو ساعات ويفترض 30 دقيقة | +| `--resume` | إنهاء الإيقاف المطابق مبكراً | | `--session ` | استهداف جلسة صريحة للإيقاف المؤقت أو الاستئناف | | `--all` | مع `--resume`، أنهِ كل إيقاف نشط | -تعليق الإيقافات المحلية السياسات المدمجة والمخصصة وسياسات الاتفاقية لجلسة واحدة. تنتهي دائماً ولا تعطل سياسات السحابة المدارة. `block-self-pause` يمنع وكيل مزود من استخدام هذا الثغر بنفسه. +تعليق الإيقافات المحلية السياسات المدمجة والمخصصة والمتفق عليها والحزمة لجلسة واحدة. تنتهي دائماً ولا تعطل سياسات السحابة المدارة. `block-failproofai-commands` — وهي تكون مفعلة دائماً ولا يمكن تعطيلها أو إيقافها — تمنع وكيل مدعوم من استخدام هذا الهروب بنفسه. -## علامات السياسة +## أعلام السياسات | العلم | الاستخدام | | --- | --- | | `--install`, `-i` | تفعيل السياسات وتثبيت خطافات الهيكل | | `--uninstall`, `-u` | تعطيل السياسات أو إزالة الخطافات | -| `--cli ` | استهدف هيكل واحد أو أكثر مدعوم | -| `--scope user\|project\|local\|all` | اختر نطاق التكوين؛ `all` للإزالة | -| `--beta` | تضمين سياسات بيتا | +| `--cli ` | استهداف أحد أو أكثر من الهياكل المدعومة | +| `--scope user\|project\|local\|all` | اختيار نطاق التكوين؛ `all` لإلغاء التثبيت | +| `--beta` | تضمين سياسات تجريبية | | `--custom`, `-c ` | التحقق من صحة وتحميل ملف سياسة مخصص؛ قابل للتكرار | -## علامات التسليم والصيانة +## أعلام التسليم والصيانة -| الأمر | العلامات | +| الأمر | الأعلام | | --- | --- | | `backfill` | `--since <30d\|6m\|YYYY-MM-DD>`, `--dry-run` | | `flush` | `--wait`, `--timeout ` | @@ -85,7 +90,7 @@ failproofai config --status | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -يجب تشغيل `failproofai update` بعد `npm install -g failproofai@latest`؛ يقوم بإجراء ترحيلات تخطيط المنزل وتثبيت ملف الخادم المطابق وإعادة تشغيل الخدمة. `--no-daemon` يقوم بترحيل التخطيط فقط. +يجب تشغيل `failproofai update` بعد `npm install -g failproofai@latest`؛ فهو يقوم بترحيلات التخطيط المنزلي وتثبيت ثنائي الخادم المطابق وإعادة تشغيل الخدمة. `--no-daemon` يقوم فقط بترحيل التخطيط. ## مسارات الهيكل @@ -95,36 +100,38 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -أسماء الهياكل المدعومة هي `claude` و`codex` و`copilot` و`cursor` و`opencode` و`pi` و`hermes` و`openclaw` و`factory` و`devin` و`antigravity` و`goose`. +أسماء الهياكل المدعومة هي `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, و `goose`. -تسميات الأسماء معرّفات الوكيل المشتقة عندما يحتوي جذران على نسخ من نفس المشروع. يتم رفض الجذور المتداخلة والتسميات المكررة لمنع الجمع المكرر أو تلف المؤشر. إعادة تحميل تكوين المسار الإضافي بدون إعادة تشغيل الخادم. +تقوم التسميات بتجميع معرفات الوكيل المشتقة عندما يحتوي جذران على نسخ من نفس المشروع. يتم رفض الجذور المتداخلة والتسميات المكررة لمنع المجموعة المكررة أو تلف المؤشر. إعادة تحميل تكوين المسار الإضافي بدون إعادة تشغيل الخادم. -يمكن لبيئات الحاوية استبدال المسارات الإضافية المكونة بالملف بمتغير مفصول بفواصل يسمى `FAILPROOFAI__EXTRA_PATHS`، على سبيل المثال: +يمكن لبيئات الحاويات استبدال المسارات الإضافية المكونة بملف بمتغير مفصول بفواصل يسمى `FAILPROOFAI__EXTRA_PATHS`، على سبيل المثال: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" ``` -## المتغيرات البيئية +## متغيرات البيئة -استخدم ملفات التكوين لسلوك الجهاز الدائم. المتغيرات البيئية مفيدة جداً للحاويات والاختبارات وعملية واحدة. +استخدم ملفات التكوين للسلوك المستمر للجهاز. متغيرات البيئة الأكثر فائدة للحاويات والاختبارات والعملية الواحدة. | المتغير | الاستخدام | | --- | --- | | `FAILPROOFAI_HOME` | نقل تخطيط `~/.failproofai` الكامل | -| `FAILPROOFAI_LOG_LEVEL` | ضبط مستوى التفاصيل للتسجيل المحلي | +| `FAILPROOFAI_LOG_LEVEL` | تعيين طول الكلام المحلي | | `FAILPROOFAI_HOOK_LOG_FILE` | كتابة تشخيصات الخطاف إلى ملف محدد | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | تعطيل التلمترا المجهولة لهذه العملية | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | تعطيل القياس عن بعد المجهول لهذه العملية | | `FAILPROOFAI_NO_FIRST_RUN=1` | تخطي إعداد التشغيل الأول التفاعلي | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | تخطي تدقيق ما بعد الإعداد المحلي | -| `FAILPROOFAI_LLM_BASE_URL` | تجاوز نقطة نهاية متوافقة مع OpenAI التي تستخدمها سياسات LLM | -| `FAILPROOFAI_LLM_API_KEY` | توفير مفتاح API الذي تستخدمه سياسات LLM | -| `FAILPROOFAI_LLM_MODEL` | تحديد النموذج الذي تستخدمه سياسات LLM | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | تخطي التدقيق المحلي بعد الإعداد | +| `FAILPROOFAI_LLM_BASE_URL` | تجاوز نقطة نهاية OpenAI المتوافقة المستخدمة في سياسات LLM | +| `FAILPROOFAI_LLM_API_KEY` | توفير مفتاح API المستخدم في سياسات LLM | +| `FAILPROOFAI_LLM_MODEL` | اختيار النموذج المستخدم في سياسات LLM | | `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | ربط تحميل وحدة السياسة المخصصة | -| `FAILPROOFAI__EXTRA_PATHS` | استبدال مسارات الالتقاط الإضافية المكونة لهيكل واحد | -| `NO_COLOR` | تعطيل إخراج الطرفية الملون | +| `FAILPROOFAI_NO_DOWNLOAD=1` | رفض جلب الحزم وثنائيات الخادم؛ ما هو مثبت يبقى قائماً | +| `FAILPROOFAI_PACK_BASE_URL` | جلب الحزم من مرآة بدلاً من `github.com` | +| `FAILPROOFAI__EXTRA_PATHS` | استبدال مسارات المقارنة الإضافية المكونة لهيكل واحد | +| `NO_COLOR` | تعطيل إخراج المحطة الملونة | -متغيرات المنزل الخاصة بالوكيل مثل `CLAUDE_PROJECTS_PATH` و`CURSOR_HOME` و`HERMES_HOME` و`OPENCLAW_HOME` تتجاوز المكان الذي يكتشف فيه Failproof AI جلسات محلية لهذا الهيكل. +متغيرات المنزل الخاصة بالوكيل مثل `CLAUDE_PROJECTS_PATH` و `CURSOR_HOME` و `HERMES_HOME` و `OPENCLAW_HOME` تجاوز حيث يكتشف Failproof AI الجلسات المحلية لهذا الهيكل. ## إيقاف أو إزالة جهاز بأمان @@ -134,7 +141,7 @@ failproofai config --status failproofai config --resume ``` -إيقاف جلسة محلية مؤقتاً لا يعطل سياسات السحابة المدارة. استعد نشرات السحابة من خلال سير عمل إنفاذ السحابة عندما تكون الطرح نفسه هو المشكلة. +إيقاف جلسة محلية لا يعطل سياسات السحابة المدارة. استرجع نشر السحابة من خلال سير عمل إنفاذ السحابة عندما تكون الطرح نفسه هو المشكلة. قبل إزالة حزمة npm، أزل الخطافات المثبتة والخادم: @@ -144,7 +151,7 @@ failproofai uninstall --yes npm rm -g failproofai ``` -قم بتشغيل `failproofai --help` للحصول على تفاصيل محددة للإصدار. +قم بتشغيل `failproofai --help` للحصول على تفاصيل خاصة بالإصدار. قم بتشغيل `failproofai uninstall` قبل `npm rm -g failproofai`؛ npm لا يزيل خطافات الوكيل المثبتة أو خدمة الخادم. diff --git a/docs/ar/start/quickstart.mdx b/docs/ar/start/quickstart.mdx index 0932384e..cedf7608 100644 --- a/docs/ar/start/quickstart.mdx +++ b/docs/ar/start/quickstart.mdx @@ -1,13 +1,12 @@ --- ---- title: "البدء السريع" -description: "التقط جلسة وكيل، ابحث عن عطل، وابدأ بمنع حدوثه." +description: "التقط جلسة وكيل، ابحث عن عطل، وابدأ في منعه." icon: "zap" --- -يوفر هذا البدء السريع تقريراً من جهاز واحد عن الجلسات، وتشغيل عملية تدقيق، ونشر سياسة. استخدم المهارة لإعداد Failproof AI، أو اتبع الخطوات اليدوية. +يوضح هذا البدء السريع كيفية جعل جهاز واحد يرسل الجلسات، وتشغيل تدقيق، ونشر سياسة. استخدم المهارة لإعداد Failproof AI، أو اتبع الخطوات اليدوية. -**أي المسار يناسبك؟** إذا كان وكيلك يعمل في أحد الأدوات 12 المدعومة [harnesses](/ar/reference/harnesses) — واجهة أوامر للبرمجة أو بوابة مثل Hermes أو OpenClaw — اتبع الخطوات أدناه؛ تحتاج إلى Node.js 20.9 أو أحدث. إذا كان وكيلك لا يملك أداة، قم بتجهيزه باستخدام [Python SDK](/ar/reference/custom-agents) للتتبع والتدقيق، ثم عد إلى [تشغيل فحص الفشل الأول](/ar/start/first-audit)؛ يتطلب التنفيذ في هذا المسار خطاف في وقت التشغيل الخاص بك. +**أي مسار هو مسارك؟** إذا كان وكيلك يعمل في أحد [الأطر](/ar/reference/harnesses) الـ 12 المدعومة — واجهة سطر أوامر لكتابة الأكواد، أو بوابة مثل Hermes أو OpenClaw — اتبع الخطوات أدناه؛ تحتاج Node.js 20.9 أو إصدار أحدث. إذا كان وكيلك لا يحتوي على إطار، فقم بتجهيزه باستخدام [Python SDK](/ar/reference/custom-agents) للتتبع والتدقيقات، ثم عد إلى [تشغيل فحص الفشل الأول الخاص بك](/ar/start/first-audit)؛ الإنفاذ في هذا المسار يتطلب خطاف في وقت التشغيل الخاص بك. @@ -22,16 +21,16 @@ icon: "zap" Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - يفحص وكيلك المشروع، ويختار التكامل ذا الصلة، ويقوم بالإعداد، والتحقق منه. انظر إلى [مستودع مهارات FailproofAI](https://github.com/FailproofAI/skills) للمهارات الفردية وخيارات التثبيت المتقدمة. + يقوم وكيلك بفحص المشروع، واختيار التكامل ذي الصلة، وتنفيذ الإعداد، والتحقق منه. راجع [مستودع مهارات FailproofAI](https://github.com/FailproofAI/skills) للحصول على المهارات الفردية وخيارات التثبيت المتقدمة. - ## قبل البدء + ## قبل أن تبدأ -1. افتح [لوحة تحكم Failproof AI](https://app.befailproof.ai) وأنشئ حساباً أو سجل الدخول ببريدك الإلكتروني للعمل. -2. انتقل إلى **Administration → Keys** وأنشئ مفتاحاً باستخدام `events:add` و `policies:pull`. -3. انسخ السر لمرة واحدة واحفظه على الجهاز المستهدف: +1. افتح [لوحة تحكم Failproof AI](https://app.befailproof.ai) وأنشئ حسابًا أو سجل الدخول باستخدام بريدك الإلكتروني للعمل. +2. انتقل إلى **Administration → Keys** وأنشئ مفتاحًا باستخدام `events:add` و `policies:pull`. +3. انسخ السر لمرة واحدة وخزنه على الجهاز الهدف: ```bash export FAILPROOFAI_KEY="" @@ -40,15 +39,15 @@ export FAILPROOFAI_KEY="" ## التثبيت - + ```bash npm install -g failproofai failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - يتم إرسال نصوص الجلسة بشكل افتراضي. أضف `--no-transcripts` للإبلاغ عن نشاط الخطاف وقرارات السياسة دون محتوى النصوص. + يتم إرسال نسخ جلسات العمل بشكل افتراضي. أضف `--no-transcripts` للإبلاغ عن نشاط الخطاف وقرارات السياسة دون محتوى النسخة. - إذا كان هذا الجهاز يحتوي بالفعل على سجل وكيل، معاينة واستيراد آخر سبعة أيام، ثم انتظر انتهاء التسليم. تخطى هذه الخطوة على جهاز جديد. + إذا كان لديك هذا الجهاز بالفعل سجل وكيل، فقم بمعاينة واستيراد آخر سبعة أيام، ثم انتظر انتهاء التسليم. تخطَّ هذه الخطوة على جهاز جديد. ```bash failproofai backfill --since 7d --dry-run @@ -56,30 +55,30 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - افتح **Sessions** في Failproof AI وحدد جلسة مستوردة. + افتح **Sessions** في Failproof AI واختر جلسة تم استيرادها. - يقوم هذا بربط Failproof AI بأداتك وتثبيت 40 سياسة مدمجة. استخدمها لرؤية قرارات السياسة المحلية وتجربة التنفيذ قبل أن يقوم Failproof AI بتدقيق جلساتك وكتابة السياسات لوكلائك. + يرفق هذا Failproof AI بإطارك ويثبت السياسات المدمجة الـ 39. استخدمها لمشاهدة قرارات السياسة المحلية وتجربة الإنفاذ قبل أن يدقق Failproof AI جلساتك وينشئ سياسات لوكلائك. - دع برنامج التثبيت يكتشف أداتك، أو قم بتسمية واحدة صراحة. كل واحد من الـ 12 هو قيمة `--cli` صحيحة — `claude`و`codex`و`copilot`و`cursor`و`opencode`و`pi`و`hermes`و`openclaw`و`factory`و`devin`و`antigravity`و`goose`. + دع المثبت يكتشف إطارك، أو سمِّ واحدًا بشكل صريح. كل واحد من الـ 12 هو قيمة `--cli` صحيحة — `claude`، `codex`، `copilot`، `cursor`، `opencode`، `pi`، `hermes`، `openclaw`، `factory`، `devin`، `antigravity`، `goose`. ```bash failproofai policies --install --cli claude --scope user # a coding CLI failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - يتم التحقق من حجب استدعاء أداة قبل تشغيله على الأدوات الـ 12 جميعها. يتم التحقق من بوابات نهاية الدور على 8 — انظر [القدرة على التنفيذ](/ar/reference/harnesses#enforcement-capability) للمصفوفة لكل أداة. + يتم التحقق من حجب استدعاء أداة قبل تشغيله على الـ 12 جميعًا. يتم التحقق من بوابات نهاية الدور على 8 — راجع [إمكانية الإنفاذ](/ar/reference/harnesses#enforcement-capability) للحصول على مصفوفة كل إطار. - اتبع [تشغيل فحص الفشل الأول](/ar/start/first-audit). استخدم هدفاً محدداً مثل "ابحث عن الجلسات حيث أعاد الوكيل محاولة أداة فاشلة دون تغيير نهجه." + اتبع [تشغيل فحص الفشل الأول الخاص بك](/ar/start/first-audit). استخدم هدفًا محددًا مثل البحث عن الجلسات التي أعاد فيها الوكيل محاولة أداة فاشلة دون تغيير نهجه. - اتبع [منع الفشل الأول باستخدام سياسة](/ar/start/first-policy). ابدأ في وضع المراقبة، افحص المطابقات، ثم نفذ الإصدار المراجع. + اتبع [منع الفشل الأول الخاص بك باستخدام سياسة](/ar/start/first-policy). ابدأ في وضع المراقبة، افحص المطابقات، ثم أنفذ النسخة المراجعة. - شغّل `failproofai config --status`. يقدم الإعداد الصحي تقرير الاتصال بالسحابة وحالة الخادم والقوى العاملة وما إذا كان التنفيذ موقوفاً. + شغّل `failproofai config --status`. يرسل الإعداد السليم الاتصال بالسحابة وحالة المراقب وما إذا كان الإنفاذ موقوفًا. \ No newline at end of file diff --git a/docs/de/policies/builtin-catalog.mdx b/docs/de/policies/builtin-catalog.mdx index e80f57d7..f2cea5ed 100644 --- a/docs/de/policies/builtin-catalog.mdx +++ b/docs/de/policies/builtin-catalog.mdx @@ -1,100 +1,100 @@ --- -title: "Integrierter Policy-Katalog" -description: "Übersicht aller integrierten Failproof AI Policies mit Auslöser, empfohlenem Zustand und konfigurierbaren Parametern." +title: "Integrierter Richtlinienkatalog" +description: "Übersicht aller integrierten Failproof AI-Richtlinien mit Auslöser, empfohlenem Status und konfigurierbaren Parametern." icon: "list-checks" --- -Das installierte Paket ist die maßgebliche Quelle für die verfügbaren Policies. Führen Sie nach jedem Upgrade `failproofai policies` aus, da sich Katalogeinträge und Verhalten mit der Paketversion ändern können. +Das installierte Paket ist die maßgebliche Quelle für die Verfügbarkeit von Richtlinien. Führen Sie `failproofai policies` nach jedem Upgrade aus, da sich Katalogeinträge und Verhalten mit der Paketversion ändern können. -## Empfohlene Basiskonfiguration +## Empfohlene Grundkonfiguration -Die empfohlene Auswahl des geführten Setups aktiviert derzeit Secret-Sanitizer, Umgebungsschutz, Selbstschutz, Schutz vor katastrophalen Befehlen sowie Sicherheit für geschützte Branches: +Die empfohlene Auswahl des geführten Setups aktiviert derzeit Secret-Sanitizer, Umgebungsschutzmaßnahmen, Selbstschutz, Absicherungen gegen katastrophale Befehle sowie Schutz für geschützte Branches: ```text sanitize-jwt sanitize-api-keys sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars block-env-files block-secrets-write -block-self-pause block-failproofai-commands -block-sudo block-curl-pipe-sh -block-rm-rf block-push-master -block-force-push +block-failproofai-commands block-sudo +block-curl-pipe-sh block-rm-rf +block-push-master block-force-push ``` -Die empfohlene Auswahl ist bewusst schmaler als **Alles**. Infrastruktur- und Workflow-Policies können legitime Arbeit unterbrechen und sollten nur für die Repositories und Maschinen aktiviert werden, die sie tatsächlich benötigen. +`block-failproofai-commands` ist **immer aktiv**. Es wird oben der Vollständigkeit halber aufgeführt, registriert sich jedoch bei jeder Auswertung unabhängig davon, ob es in Ihrem aktivierten Set erscheint – und es kann weder deaktiviert noch pausiert werden. Eine Absicherung gegen das Abschalten der Durchsetzung durch den Agenten ist keine Absicherung, wenn der Agent sie selbst abschalten kann. + +„Empfohlen" ist bewusst enger gefasst als **Alles**. Infrastruktur- und Workflow-Richtlinien können gültige Arbeitsabläufe unterbrechen und sollten nur für die Repositories und Systeme aktiviert werden, die sie benötigen. ## Secrets und Umgebung -| Policy | Auslöser | Ergebnis | +| Richtlinie | Auslöser | Ergebnis | | --- | --- | --- | | `sanitize-jwt` | `PostToolUse` | JWTs aus der Tool-Ausgabe entfernen, bevor das Modell sie sieht. | | `sanitize-api-keys` | `PostToolUse` | Gängige OpenAI-, Anthropic-, GitHub-, AWS-, Stripe- und Google-Schlüssel entfernen. | -| `sanitize-connection-strings` | `PostToolUse` | Datenbankverbindungszeichenfolgen mit Zugangsdaten entfernen. | +| `sanitize-connection-strings` | `PostToolUse` | Datenbankverbindungszeichenfolgen mit Anmeldedaten entfernen. | | `sanitize-private-key-content` | `PostToolUse` | PEM-Private-Key-Inhalte entfernen. | -| `sanitize-bearer-tokens` | `PostToolUse` | Authorization-Bearer-Token entfernen. | -| `protect-env-vars` | `PreToolUse` auf Shell-Tools | Befehle blockieren, die Umgebungsvariablen ausgeben. | +| `sanitize-bearer-tokens` | `PostToolUse` | Authorization-Bearer-Tokens entfernen. | +| `protect-env-vars` | `PreToolUse` bei Shell-Tools | Befehle blockieren, die Umgebungsvariablen ausgeben. | | `block-env-files` | `PreToolUse` | Lese- und Schreibzugriffe auf `.env`-Dateien blockieren. | -| `block-read-outside-cwd` | `PreToolUse` auf Lese-, Glob-, Grep- oder Shell-Tools | Lesezugriffe auf das Arbeitsverzeichnis der Sitzung beschränken. | -| `block-secrets-write` | `PreToolUse` auf Schreib-Tools | Schreibzugriffe auf bekannte Secret-Key- und Credential-Dateinamen blockieren. | +| `block-read-outside-cwd` | `PreToolUse` bei Lese-, Glob-, Grep- oder Shell-Tools | Lesezugriffe auf das Arbeitsverzeichnis der Sitzung beschränken. | +| `block-secrets-write` | `PreToolUse` bei Schreib-Tools | Schreibzugriffe auf bekannte Secret-Key- und Credential-Dateinamen blockieren. | ## Gefährliche Befehle und Infrastruktur -| Policy | Auslöser | Ergebnis | +| Richtlinie | Auslöser | Ergebnis | | --- | --- | --- | -| `block-self-pause` | `PreToolUse`, `PermissionRequest` | Verhindert, dass ein Agent seine eigene Durchsetzung pausiert. | | `block-sudo` | `PreToolUse`, `PermissionRequest` | `sudo` blockieren, sofern kein Allow-Muster übereinstimmt. | -| `block-curl-pipe-sh` | `PreToolUse` | Heruntergeladene Skripte blockieren, die direkt an eine Shell weitergeleitet werden. | +| `block-curl-pipe-sh` | `PreToolUse` | Heruntergeladene Skripte, die direkt an eine Shell geleitet werden, blockieren. | | `block-rm-rf` | `PreToolUse` | Katastrophale rekursive Löschmuster blockieren. | -| `block-failproofai-commands` | `PreToolUse` | Verhindert, dass Agents Failproof AI ändern oder deinstallieren. | +| `block-failproofai-commands` | `PreToolUse`, `PermissionRequest` | **Immer aktiv, kann nicht deaktiviert werden.** Jeden Failproof AI CLI-Aufruf, Self-Pause und Paketmanager-Deinstallation blockieren. | | `block-kubectl` | `PreToolUse` | Kubernetes-Befehle absichern. | | `block-terraform` | `PreToolUse` | Terraform- und OpenTofu-Befehle absichern. | -| `block-aws-cli` | `PreToolUse` | AWS-CLI-Befehle absichern. | -| `block-gcloud` | `PreToolUse` | Google-Cloud-CLI-Befehle absichern. | -| `block-az-cli` | `PreToolUse` | Azure-CLI-Befehle absichern. | +| `block-aws-cli` | `PreToolUse` | AWS CLI-Befehle absichern. | +| `block-gcloud` | `PreToolUse` | Google Cloud CLI-Befehle absichern. | +| `block-az-cli` | `PreToolUse` | Azure CLI-Befehle absichern. | | `block-helm` | `PreToolUse` | Helm-Befehle absichern. | -| `block-gh-pipeline` | `PreToolUse` | Mutierende GitHub-CLI-Operationen für Workflow, Run, Merge, Release, Cache und Secrets absichern. | +| `block-gh-pipeline` | `PreToolUse` | Verändernde GitHub CLI-Operationen für Workflows, Runs, Merges, Releases, Caches und Secrets absichern. | ## Git- und Datenbanksicherheit -| Policy | Auslöser | Ergebnis | +| Richtlinie | Auslöser | Ergebnis | | --- | --- | --- | | `block-push-master` | `PreToolUse` | Direkte Pushes auf konfigurierte geschützte Branches blockieren. | | `block-force-push` | `PreToolUse` | Force-Pushes blockieren; `--force-with-lease` bleibt in der aktuellen Implementierung erlaubt. | | `block-work-on-main` | `PreToolUse` | Commits und Merges auf geschützten Branches blockieren. | -| `warn-git-amend` | `PreToolUse` | Warnung vor dem Überschreiben eines Commits mit `--amend`. | -| `warn-git-stash-drop` | `PreToolUse` | Warnung vor dem dauerhaften Löschen oder Leeren von Stashes. | -| `warn-all-files-staged` | `PreToolUse` | Warnung bei umfassendem `git add -A`, `git add .` oder `git add --all`. | -| `warn-destructive-sql` | `PreToolUse` | Warnung bei `DROP`, `TRUNCATE` und `DELETE` ohne `WHERE` über bekannte Datenbankclients. | -| `warn-schema-alteration` | `PreToolUse` | Warnung bei erkannten `ALTER TABLE`-Spalten- und Umbenennungsoperationen. | +| `warn-git-amend` | `PreToolUse` | Warnen, bevor ein Commit mit `--amend` überschrieben wird. | +| `warn-git-stash-drop` | `PreToolUse` | Warnen, bevor Stashes dauerhaft gelöscht oder geleert werden. | +| `warn-all-files-staged` | `PreToolUse` | Bei umfangreichen `git add -A`-, `git add .`- oder `git add --all`-Befehlen warnen. | +| `warn-destructive-sql` | `PreToolUse` | Bei `DROP`, `TRUNCATE` und `DELETE` ohne `WHERE` über bekannte Datenbankclients warnen. | +| `warn-schema-alteration` | `PreToolUse` | Bei erkannten `ALTER TABLE`-Spalten- und Umbenennungsoperationen warnen. | -## Pakete, Systemverhalten und Agent-Schleifen +## Pakete, Systemverhalten und Agentenschleifen -| Policy | Auslöser | Ergebnis | +| Richtlinie | Auslöser | Ergebnis | | --- | --- | --- | -| `warn-package-publish` | `PreToolUse` | Warnung vor dem Veröffentlichen in Paket-Registries. | -| `warn-global-package-install` | `PreToolUse` | Warnung vor der globalen Paketinstallation. | -| `prefer-package-manager` | `PreToolUse` | Den Agent anweisen, einen erlaubten Paketmanager zu verwenden. | -| `warn-large-file-write` | `PreToolUse` auf Schreib-Tools | Warnung bei Überschreiten des konfigurierten Dateigrößen-Schwellenwerts. | -| `warn-background-process` | `PreToolUse` | Warnung bei abgetrennten oder langlebigen Hintergrundprozess-Mustern. | -| `warn-repeated-tool-calls` | `PreToolUse` | Warnung nach drei oder mehr identischen Tool-Aufrufen. | +| `warn-package-publish` | `PreToolUse` | Warnen, bevor in Paketregistries veröffentlicht wird. | +| `warn-global-package-install` | `PreToolUse` | Warnen, bevor Pakete global installiert werden. | +| `prefer-package-manager` | `PreToolUse` | Den Agenten anweisen, einen erlaubten Paketmanager zu verwenden. | +| `warn-large-file-write` | `PreToolUse` bei Schreib-Tools | Bei Überschreitung des konfigurierten Dateigrößenschwellenwerts warnen. | +| `warn-background-process` | `PreToolUse` | Bei abgetrennten oder langlebigen Hintergrundprozessmustern warnen. | +| `warn-repeated-tool-calls` | `PreToolUse` | Nach drei oder mehr identischen Tool-Aufrufen warnen. | ## Aufgabenabschluss-Workflow -Diese Policies erfordern ein Harness, das ein kompatibles `Stop`-Ereignis ausgibt. +Diese Richtlinien erfordern ein Harness, das ein kompatibles `Stop`-Event ausgibt. -| Policy | Ergebnis | +| Richtlinie | Ergebnis | | --- | --- | -| `require-commit-before-stop` | Abschluss verweigern, solange nachverfolgbare Arbeit nicht committed wurde. | +| `require-commit-before-stop` | Abschluss verweigern, solange verfolgte Änderungen nicht committet sind. | | `require-push-before-stop` | Abschluss verweigern, solange Commits nur lokal vorhanden sind. | | `require-pr-before-stop` | Einen Pull Request für den aktuellen Branch erfordern. | -| `require-no-conflicts-before-stop` | Einen sauberen Merge gegen den konfigurierten Basis-Branch erfordern. | -| `require-ci-green-before-stop` | Erfordern, dass CI-Checks für den aktuellen HEAD erfolgreich abgeschlossen werden. | +| `require-no-conflicts-before-stop` | Einen konfliktfreien Merge gegen den konfigurierten Basis-Branch erfordern. | +| `require-ci-green-before-stop` | Erfordern, dass die CI-Prüfungen für den aktuellen HEAD erfolgreich abgeschlossen werden. | -## Parameter-Referenz +## Parameterreferenz -Parameter werden im `policyParams`-Objekt des gewählten Scopes konfiguriert. Typen werden von jeder Policy validiert. +Parameter werden unter dem `policyParams`-Objekt des ausgewählten Scopes konfiguriert. Typen werden von jeder Richtlinie validiert. -| Policy | Parameter | Typ und Standard | +| Richtlinie | Parameter | Typ und Standard | | --- | --- | --- | | `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; Einträge enthalten `regex` und `label` | | `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | @@ -125,5 +125,5 @@ Parameter werden im `policyParams`-Objekt des gewählten Scopes konfiguriert. Ty ``` - Ein Allow-Muster erweitert den Handlungsspielraum eines Agents. Testen Sie die genaue Tokenisierung und Befehlsvarianten auf dem Ziel-Harness, bevor Sie es flächendeckend einsetzen. + Ein Allow-Muster erweitert den Handlungsspielraum eines Agenten. Testen Sie die genaue Tokenisierung und Befehlsvarianten auf dem Ziel-Harness, bevor Sie es flächendeckend einsetzen. \ No newline at end of file diff --git a/docs/de/policies/failure-behavior.mdx b/docs/de/policies/failure-behavior.mdx index e3e22714..57067efa 100644 --- a/docs/de/policies/failure-behavior.mdx +++ b/docs/de/policies/failure-behavior.mdx @@ -1,19 +1,19 @@ --- title: "Fehlerverhalten" -description: "Verstehen Sie, was passiert, wenn die Richtlinienauswertung oder der lokale Daemon nicht verfügbar ist." +description: "Verstehen, was passiert, wenn die Richtlinienauswertung oder der lokale Daemon nicht verfügbar ist." icon: "shield-alert" --- -Failproof AI ist so konzipiert, dass ein Durchsetzungsfehler sichtbar wird, anstatt riskante Aktionen stillschweigend zuzulassen. +Failproof AI ist so konzipiert, dass ein Durchsetzungsfehler sichtbar wird, anstatt riskante Aktionen stillschweigend zu erlauben. -## Einen failure-closed-Block diagnostizieren +## Einen „failure-closed"-Block diagnostizieren - 1. Gehen Sie zu **Admin → Durchsetzung** und öffnen Sie die Maschine. - 2. Überprüfen Sie das letzte Check-in, die zugewiesene Bereitstellung und die gemeldete Bereitstellung. - 3. Gehen Sie zu **Beobachten → Richtlinie** und öffnen Sie die Sitzung der abgelehnten Entscheidung. - 4. Bestätigen Sie, ob der Grund auf die Erreichbarkeit des Daemons, einen Versionsunterschied oder die Richtlinie selbst hindeutet. + 1. Gehen Sie zu **Admin → Durchsetzung** und öffnen Sie den Computer. + 2. Prüfen Sie seinen letzten Check-in, das zugewiesene Deployment und das gemeldete Deployment. + 3. Gehen Sie zu **Observe → Richtlinie** und öffnen Sie die Sitzung der abgelehnten Entscheidung. + 4. Stellen Sie fest, ob der Grund auf Daemon-Erreichbarkeit, Versionsunterschiede oder die Richtlinie selbst hinweist. @@ -27,17 +27,41 @@ Failproof AI ist so konzipiert, dass ein Durchsetzungsfehler sichtbar wird, anst -Auf einer Maschine, die zur Verwendung von `failproofaid` konfiguriert ist, ist der Daemon der einzige Auswertungsdienst. Ist er nicht erreichbar oder stimmt seine Protokollversion nicht mit der CLI überein, schlägt die Hook-Auswertung failure-closed fehl. Die Aktion wird mit einer Begründung abgelehnt, die den Operator anweist, den Daemon zu überprüfen oder zu aktualisieren. +Auf einem Computer, der zur Verwendung von `failproofaid` konfiguriert ist, ist der Daemon der einzige Auswertungsinstanz. Ist er nicht erreichbar oder stimmt seine Protokollversion nicht mit der CLI überein, schlägt die Hook-Auswertung geschlossen fehl. Die Aktion wird mit einer Begründung abgelehnt, die den Betreiber anweist, den Daemon zu prüfen oder zu aktualisieren. -Vor der Daemon-Konfiguration wertet Failproof AI Richtlinien direkt im Prozess aus. Sobald die Daemon-Konfiguration gespeichert ist, fällt Failproof AI bei einem Daemon-Ausfall nicht stillschweigend auf einen zweiten Auswertungsdienst zurück. +Vor der Daemon-Konfiguration werten Hooks Richtlinien im Prozess aus. Sobald die Daemon-Konfiguration gespeichert ist, fällt Failproof AI bei einem Daemon-Fehler nicht stillschweigend auf eine zweite Auswertungsinstanz zurück. -## Auf eine failure-closed-Entscheidung reagieren +## Auf eine „failure-closed"-Entscheidung reagieren 1. Führen Sie `failproofai config --status` aus. -2. Wenn sich die Versionen unterscheiden, führen Sie nach dem Aktualisieren des Pakets erneut `failproofai config` aus. -3. Wenn der Daemon nicht erreichbar ist, prüfen Sie seinen Dienststatus und die lokalen Protokolle. -4. Setzen Sie die Agent-Arbeit erst fort, wenn ein bekannter Richtlinienauswertungspfad fehlerfrei funktioniert. +2. Wenn sich die Versionen unterscheiden, führen Sie `failproofai config` nach dem Aktualisieren des Pakets erneut aus. +3. Ist der Daemon nicht erreichbar, prüfen Sie seinen Servicestatus und die lokalen Logs. +4. Nehmen Sie die Agenten-Arbeit erst wieder auf, wenn ein bekannter Richtlinienauswertungspfad funktionsfähig ist. - Versuchen Sie nicht wiederholt, die blockierte Aktion erneut auszuführen. Eine failure-closed-Antwort bedeutet, dass das System nicht feststellen konnte, ob die Aktion sicher war. - \ No newline at end of file + Versuchen Sie nicht wiederholt, die blockierte Aktion zu wiederholen. Eine „failure-closed"-Antwort bedeutet, dass das System nicht feststellen konnte, dass die Aktion sicher war. + + +## Ein Pack lässt sich nicht laden + +Ein Computer, der angewiesen wurde, ein Pack durchzusetzen, und es nicht ausführen kann, lehnt ab, anstatt stillschweigend fortzufahren. Auslöser ist eine **aufgezeichnete Erwartung**, niemals eine leere: Ein Computer ohne installierte Packs ist still, während ein Pack, das deklariert ist und sich nicht auflösen lässt – oder das weniger registriert als sein Manifest angibt – ablehnt. + +Die Ablehnung ist **eng gefasst**, anders als bei einem nicht erreichbaren Daemon. Ein Daemon, der nicht erreichbar ist, bedeutet, dass überhaupt keine Auswertung stattgefunden hat, sodass nichts als sicher bekannt sein kann. Ein Pack, das sich nicht lädt, hat eine aufzählbare Menge fehlender Wächter, da jede deklarierte Richtlinie ihr eigenes `match` mitbringt – daher lehnt es nur die Ereignisse und Tools ab, die von diesen Richtlinien abgedeckt werden, und alles andere läuft weiter. + +Es greift nicht bei: + +- einem `observe`-Pack, das konstruktionsbedingt auswertet und verwirft +- Richtlinien, die Sie nie übernommen oder explizit deaktiviert haben +- einem Pack, das der Loader nie empfangen hat, wo sich „keine Registrierungen" nicht von einem bewussten Überspringen unterscheiden lässt +- einer aktiven Sitzungspause +- einem Lade-Timeout, das vorübergehend ist – ein einzelner langsamer Festplattenmoment darf nicht ablehnen, bis ein Mensch eingreift + +`UserPromptSubmit` **instruiert** anstatt abzulehnen, unabhängig davon, was die fehlende Richtlinie deklariert hat. Eine pauschale Ablehnung würde es ebenfalls erfassen und Sie aus dem Agenten aussperren, der das Problem beheben könnte. + +### Vorgehensweise + +```bash +failproofai pack list +``` + +Dieser Befehl nennt alle installierten Packs, die sich nicht laden lassen, gibt den Grund an und beendet sich mit einem Fehlercode. Installieren Sie das Pack anschließend neu (`failproofai pack add `) oder entfernen Sie es (`failproofai pack remove `) – durch das Entfernen wird die Erwartung zurückgezogen, und die Ablehnung hört damit auf. \ No newline at end of file diff --git a/docs/de/policies/packs.mdx b/docs/de/policies/packs.mdx new file mode 100644 index 00000000..03252fdb --- /dev/null +++ b/docs/de/policies/packs.mdx @@ -0,0 +1,110 @@ +--- +title: "Policy Packs" +description: "Installiere einen Satz von Policies, der als GitHub-Release veröffentlicht wurde, und verwalte, was er durchsetzt." +icon: "package" +--- + +Ein Pack ist ein Satz von Policies, der als GitHub-Release veröffentlicht wurde. Ein einziger Befehl installiert ihn, die eigenen Prüfsummen des Releases werden vor der Ausführung verifiziert, und der Digest wird gespeichert, damit sich der Pack auf deinem Rechner anschließend nicht mehr verändern kann. + +## Die Failproof AI Policies installieren + +```bash +failproofai pack add core +``` + +Damit wird der von uns veröffentlichte Satz aus der im Paket enthaltenen Kopie installiert — es ist also keine Netzwerkverbindung erforderlich, und hinter einem Proxy kann es nicht fehlschlagen. Nur einen Teil davon übernehmen: + +```bash +failproofai pack add core --policy block-rm-rf # eine oder mehrere kommagetrennte Policies +failproofai pack add core --category dangerous-commands # eine gesamte Kategorie +failproofai pack add core --all # alles darin +``` + +`failproofai pack list` listet alle Kategorien auf, die der Pack enthält. + +## Den Inhalt eines Packs vor der Installation prüfen + +```bash +failproofai pack list acme/support-agent +``` + +Listet alle Policies des Packs gruppiert nach Kategorie auf und zeigt an, welche der Autor standardmäßig aktiviert hat und welche optional sind. Es wird **ausschließlich das Manifest** gelesen — das eigentliche Artefakt wird weder heruntergeladen noch importiert. Das Anzeigen eines fremden Packs führt also keinen fremden Code aus. Das Manifest wird dennoch gegen die `SHA256SUMS` des Releases geprüft, sodass das, was du siehst, auch das ist, was installiert würde. + +`failproofai pack list` ohne Angabe einer Quelle listet die bereits hier installierten Packs auf. + +## Einen fremden Pack installieren + +```bash +failproofai pack add acme/support-agent +``` + +Alle folgenden Formate funktionieren — füge einfach das ein, was du hast: + +| Quelle | Ergebnis | +| --- | --- | +| `acme/support-agent` | Neuestes Release, **fixiert** auf den exakt aufgelösten Tag | +| `acme/support-agent@v2.1.0` | Dieses Release | +| `github:acme/support-agent@v2.1.0` | Dasselbe, explizit geschrieben | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | Dasselbe, aus dem Browser kopiert | + +Wird kein Tag angegeben, wird das neueste Release installiert **und fixiert**, und anschließend wird angezeigt, welcher Tag gewählt wurde. Was gespeichert wird, benennt immer genau ein Release, sodass eine Neuinstallation nicht abweichen kann. + +## Nur einen Teil eines Packs verwenden + +Standardmäßig erhältst du die **eigenen** Standardwerte des Packs — die Policies, die der Autor als sicher für die unbeaufsichtigte Aktivierung markiert hat — nicht alles, was er enthält. + +```bash +failproofai pack add acme/support-agent --category billing,git +failproofai pack add acme/support-agent --policy block-refunds +failproofai pack add acme/support-agent --all +``` + +`--category` und `--policy` werden als Vereinigung kombiniert (`--only` wird als Synonym für `--policy` akzeptiert). Wird ein Pack in einer neueren Version erneut hinzugefügt, bleiben die gewählten Einstellungen erhalten, anstatt alles andere wieder einzuschalten. + +## Verwaltung der aktiven Policies + +```bash +failproofai policies # alle Quellen in einer Liste, einschließlich Packs +failproofai pack list # nur Packs, gruppiert nach Kategorie +failproofai policies --uninstall block-refunds # eine Pack-Policy deaktivieren +failproofai policies --install block-refunds # und wieder aktivieren +failproofai pack remove acme/support-agent +``` + +Ein einfacher Name bezieht sich auf die **eingebaute** Policy, sofern eine mit diesem Namen existiert. Den Namen einer Pack-Kopie explizit angeben, wenn nötig: + +```bash +failproofai policies --uninstall acme/support-agent:block-refunds +``` + + +Wenn ein Pack eine Policy mitbringt, deren Name auch ein **aktiviertes Builtin** ist, wird das Builtin ausgeführt und die Pack-Kopie übersprungen — andernfalls würde dieselbe Prüfung zweimal ausgewertet. Das Builtin deaktivieren, um stattdessen die Pack-Kopie zu verwenden. + + +## Woher die Failproof AI Policies stammen + +`core` liest die im npm-Paket mitgelieferte Kopie. Derselbe Satz wird auch als GitHub-Release veröffentlicht, was du installierst, wenn du eine bestimmte Version möchtest: + +```bash +failproofai pack add core # aus diesem Paket, ohne Netzwerkverbindung +failproofai pack add FailproofAI/policies # derselbe Satz, aus dem GitHub-Release +``` + +## Was Integritätsprüfung leistet und was nicht + +`SHA256SUMS` wird im selben Release wie das Artefakt ausgeliefert und ist daher **keine** Signatur und beweist nichts darüber, wer es veröffentlicht hat. Was sie beweist, ist, dass die Bytes genau die des veröffentlichten Releases sind — und da der Digest beim Hinzufügen des Packs gespeichert und vor jedem Import erneut geprüft wird, kann sich ein Pack auf deinem Rechner anschließend nicht mehr verändern. Ein Repository, das einen Asset-Tag neu setzt oder ersetzt, wird nicht mehr geladen, anstatt still etwas anderes auszuführen. + +Bei der Installation wird der Pack auch **einmalig importiert** und gegen sein eigenes Manifest geprüft. Ein Pack, dessen Artefakt nicht geparst werden kann oder der etwas anderes als deklariert registriert, wird abgelehnt, bevor etwas aktiviert wird — anstatt sauber zu installieren und beim nächsten Tool-Aufruf zu versagen. + +## Wenn ein Pack nicht geladen werden kann + +Ein Pack, der auf diesem Rechner durchgesetzt werden soll, aber nicht ausgeführt werden kann, **verweigert** die Ereignisse, die von den fehlenden Policies abgedeckt wurden, anstatt sie stillschweigend zuzulassen. Siehe [Fehlerverhalten](/de/policies/failure-behavior). `failproofai pack list` benennt jeden Pack in diesem Zustand und beendet sich mit einem Fehlercode ungleich null. + +## Offline-Betrieb und Mirrors + +| Variable | Auswirkung | +| --- | --- | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Verhindert jeden Abruf; bereits installierte Packs erzwingen weiterhin ihre Policies | +| `FAILPROOFAI_PACK_BASE_URL` | Leitet den Pack-Abruf an einen Mirror statt an `github.com` weiter | + +Eigene Packs veröffentlichen: siehe [Pack veröffentlichen](/de/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/de/policies/publish-a-pack.mdx b/docs/de/policies/publish-a-pack.mdx new file mode 100644 index 00000000..e4963529 --- /dev/null +++ b/docs/de/policies/publish-a-pack.mdx @@ -0,0 +1,91 @@ +--- +title: "Ein Pack veröffentlichen" +description: "Eigene Policies als GitHub-Release bereitstellen, das jeder installieren kann." +icon: "upload" +--- + +Ein Pack besteht aus drei Dateien, die einem GitHub-Release beigefügt werden. `failproofai pack build` erzeugt alle drei aus einer Policy-Datei, die bereits vorhanden ist. + +## 1. Die Policies schreiben + +Eine einzelne Datei, die dieselbe API wie jede benutzerdefinierte Policy verwendet. Zwei zusätzliche Felder sind für ein Pack relevant: + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-refunds", + description: "Refunds above the approved limit need a human", + category: "Billing", // groups it, and is what --category selects on + defaultEnabled: true, // switched on by a plain `pack add` + match: { events: ["PreToolUse"], tools: ["Bash"] }, + fn: async (ctx) => + String(ctx.toolInput?.command ?? "").includes("refund") + ? deny("Refunds need a human. Ask before running this.") + : allow(), +}); +``` + +`defaultEnabled` ist standardmäßig **false**, wenn es weggelassen wird. Ein einfaches `failproofai pack add` aktiviert nur das, was explizit markiert wurde — ob alle Policies eines Fremden unbeaufsichtigt installiert werden, sollte nicht stillschweigend für den Nutzer entschieden werden. + + +Der Eintrag muss eine **in sich geschlossene Datei** sein. Nur der Eintrag wird mit einem Digest verknüpft. Ein Pack, das lokale Dateien importiert, kann nicht ernsthaft behaupten, der Digest decke ab, was tatsächlich ausgeführt wird. Daher zunächst bündeln (`esbuild`, `bun build`, `rollup`) und das Pack aus dem Bundle erstellen — `pack build` lehnt einen lokalen Import ab, anstatt ein Versprechen zu machen, das es nicht halten kann. + + +## 2. Die Release-Assets erstellen + +```bash +failproofai pack build ./policies.mjs \ + --id acme/support-agent \ + --version 1.0.0 \ + --out ./dist-pack +``` + +Es werden drei Dateien geschrieben, und jede Policy wird zuerst mit den **eigenen Regeln des Loaders** validiert — so schlägt ein Pack, das niemals installiert werden könnte, bereits hier fehl, wo es noch behoben werden kann: + +| Datei | Beschreibung | +| --- | --- | +| `failproofai-pack.json` | Das Manifest: ID, Version, Effekt und ein Eintrag pro Policy | +| `failproofai-pack.mjs` | Der Eintrag, unverändert | +| `SHA256SUMS` | ` ` für die anderen beiden Dateien | + +Zur Build-Zeit abgelehnt werden: eine ID, die nicht dem Format `publisher/name` entspricht; ein Policy-Name, der `/` enthält; eine Policy, die `alwaysOn` deklariert; eine fehlende `description`, `category` oder `match`; ein Eintrag, der nichts registriert; sowie ein Eintrag, der lokale Dateien importiert. + +## 3. Dem Release beifügen + +Das Release mit derselben Version taggen, die beim Build angegeben wurde, und alle drei Dateien als Release-Assets anhängen: + +```bash +gh release create 1.0.0 \ + ./dist-pack/failproofai-pack.json \ + ./dist-pack/failproofai-pack.mjs \ + ./dist-pack/SHA256SUMS +``` + +Nun kann es jeder installieren: + +```bash +failproofai pack add acme/support-agent +``` + +Die Asset-Namen sind festgelegt — sie sind das, woraus die CLI des Consumers ihre URLs konstruiert, ohne API-Aufruf und ohne Erkennung. + +## Eine neue Version veröffentlichen + +Mit dem neuen `--version` bauen, ein neues Release taggen und die drei Assets erneut anhängen. Consumer führen dasselbe `pack add` aus und behalten die Teilmenge, die sie ausgewählt hatten; eine deaktivierte Policy bleibt auch nach dem Upgrade deaktiviert. + +Das **Umbenennen** einer Policy ist eine breaking change: Ein System, das sie deaktiviert hatte, deaktiviert jetzt einen Namen, der nicht mehr existiert, und der neue Name wird mit dem Standardwert von `defaultEnabled` aktiviert. + +## Was Nutzer vertrauen + +`SHA256SUMS` liegt im selben Release wie das Artefakt und beweist daher, dass die Bytes mit dem übereinstimmen, was veröffentlicht wurde — nicht jedoch, wer der Urheber ist. Wer Schreibzugriff auf das Repository hat, kann beide Dateien schreiben. Der Schutz für die Nutzer besteht darin, dass der Digest bei der Installation eingefroren wird — was veröffentlicht wurde, kann nachträglich nicht mehr verändert werden. + +Aus einem Repository veröffentlichen, dessen Schreibzugriff kontrolliert wird, und ein Pack-Release wie die Veröffentlichung eines Packages behandeln. + +## Beobachten vor dem Durchsetzen + +Ein Manifest kann `"effect": "observe"` deklarieren. Diese Policies werden ausgeführt und ihre Urteile werden **aufgezeichnet und verworfen** — nichts wird blockiert. So lässt sich eine neue Regel gegen echten Traffic messen, bevor sie die Arbeit von jemandem unterbrechen kann. + +```json +{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +``` \ No newline at end of file diff --git a/docs/de/reference/failproof-cli.mdx b/docs/de/reference/failproof-cli.mdx index 786ce7e7..4802d176 100644 --- a/docs/de/reference/failproof-cli.mdx +++ b/docs/de/reference/failproof-cli.mdx @@ -4,11 +4,11 @@ description: "Hooks installieren, lokale Richtlinien verwalten, Cloud verbinden icon: "terminal" --- -Installiere die lokale CLI mit `npm install -g failproofai`. Ohne Argumente aufgerufen öffnet sie das lokale Richtlinien-Dashboard. +Installiere die lokale CLI mit `npm install -g failproofai`. Starte sie ohne Argumente, um das lokale Richtlinien-Dashboard zu öffnen. -Das Paket benötigt Node.js 20.9 oder neuer. Bun 1.3 oder neuer wird für Entwicklungs- und Quellinstallationen unterstützt. `failproofai configure` und `failproofai setup` sind Aliase für `failproofai config`; `failproofai p` ist ein Alias für `failproofai policies`. +Das Paket erfordert Node.js 20.9 oder neuer. Bun 1.3 oder neuer wird für Entwicklung und Quell-Installationen unterstützt. `failproofai configure` und `failproofai setup` sind Aliase für `failproofai config`; `failproofai p` ist ein Alias für `failproofai policies`. -## Maschine einrichten +## Eine Maschine einrichten ```bash npm install -g failproofai @@ -20,31 +20,36 @@ failproofai policies --install failproofai config --status ``` -Führe `failproofai` ohne Argumente aus, um das lokale Richtlinien-Dashboard zu öffnen. +Starte `failproofai` ohne Argumente, um das lokale Richtlinien-Dashboard zu öffnen. | Befehl | Ergebnis | | --- | --- | -| `failproofai config` | Interaktives Maschinensetup starten | -| `failproofai config --connect --token ` | Cloud-Ingestion und Richtlinienlieferung verbinden | -| `failproofai config --status` | Verbindungs-, Daemon-, Liefer- und Pausenstatus anzeigen | -| `failproofai policies` | Eingebaute und benutzerdefinierte Richtlinien auflisten | +| `failproofai config` | Interaktive Maschineneinrichtung starten | +| `failproofai config --connect --token ` | Cloud-Ingest und Richtlinienbereitstellung verbinden | +| `failproofai config --status` | Verbindungs-, Daemon-, Bereitstellungs- und Pausenstatus anzeigen | +| `failproofai policies` | Eingebaute, benutzerdefinierte, konventionsbasierte, Pack- und Cloud-verwaltete Richtlinien auflisten | | `failproofai policies --install` | Hooks installieren und Richtlinien aktivieren | -| `failproofai policy add ` | Eine eingebaute Richtlinie aktivieren | -| `failproofai policy remove ` | Eine eingebaute Richtlinie deaktivieren | +| `failproofai policy add ` | Eine Richtlinie aktivieren – eine eingebaute oder `:` aus einem installierten Pack | +| `failproofai policy remove ` | Eine Richtlinie deaktivieren, gleiche Benennung | | `failproofai policies --uninstall` | Richtlinien deaktivieren oder Harness-Hooks entfernen | -| `failproofai audit` | Lokalen Agentenverlauf scannen und lokale Audit-Ansicht öffnen | -| `failproofai audit --schedule [days] --email
` | Wiederkehrende lokale Scans planen und deren Ergebnisse per E-Mail senden | +| `failproofai pack list` | Installierte Richtlinien-Packs und alle enthaltenen Richtlinien auflisten | +| `failproofai pack add ` | Ein Richtlinien-Pack von einem GitHub-Release installieren; ohne Tag wird das neueste genommen und angeheftet | +| `failproofai pack add --bundled` | Die eingebauten Richtlinien als Pack installieren, aus diesem Paket, ohne Netzwerkzugriff | +| `failproofai pack build ` | Die drei Release-Assets für ein eigenes Pack erstellen | +| `failproofai pack remove ` | Ein installiertes Pack deaktivieren | +| `failproofai audit` | Lokale Agent-History durchsuchen und die lokale Audit-Ansicht öffnen | +| `failproofai audit --schedule [days] --email
` | Wiederkehrende lokale Scans planen und Ergebnisse per E-Mail senden | | `failproofai audit --status` | Berichtsadresse, Intervall und nächsten geplanten Scan anzeigen | -| `failproofai audit --no-schedule` | Wiederkehrende Scans stoppen, ohne den Audit-Verlauf zu löschen | +| `failproofai audit --no-schedule` | Wiederkehrende Scans stoppen, ohne die Audit-History zu löschen | | `failproofai harness list` | Zusätzliche Erfassungspfade auflisten | -| `failproofai flush --wait` | Aktuellen Ereignis-Spool ausliefern | -| `failproofai backfill --since 30d` | Zuvor verarbeiteten Verlauf erneut einlesen | -| `failproofai config --pause [duration]` | Eine lokale Sitzung standardmäßig 30 Minuten pausieren, maximal 8 Stunden | -| `failproofai config --resume` | Eine pausierte lokale Sitzung fortsetzen; `--all` beendet alle Pausen | -| `failproofai update` | Paketmigrationen abschließen und den Daemon aktualisieren | +| `failproofai flush --wait` | Den aktuellen Ereignis-Spool übermitteln | +| `failproofai backfill --since 30d` | Zuvor verarbeitete History erneut einlesen | +| `failproofai config --pause [duration]` | Eine lokale Sitzung standardmäßig 30 Minuten pausieren, bis zu 8 Stunden | +| `failproofai config --resume` | Eine pausierte lokale Sitzung fortsetzen; `--all` hinzufügen, um alle Pausen aufzuheben | +| `failproofai update` | Paket-Migrationen abschließen und den Daemon aktualisieren | | `failproofai migrate --dry-run` | Ausstehende Home-Layout-Migrationen vorab anzeigen oder ausführen | -| `failproofai uninstall` | Hooks und Daemon entfernen, bevor das Paket deinstalliert wird | -| `failproofai --version` | Installierte Paketversion ausgeben | +| `failproofai uninstall` | Hooks und den Daemon entfernen, bevor das Paket deinstalliert wird | +| `failproofai --version` | Die installierte Paketversion ausgeben | | `failproofai --help` | Befehle und allgemeine Nutzungshinweise anzeigen | ## Konfigurationsflags @@ -52,17 +57,17 @@ Führe `failproofai` ohne Argumente aus, um das lokale Richtlinien-Dashboard zu | Flag | Verwendung | | --- | --- | | `--connect --token ` | Nicht-interaktiv verbinden | -| `--machine-id ` | Stabile Maschinen-ID festlegen | -| `--machine-label ` | Dashboard-Bezeichnung festlegen oder ändern | +| `--machine-id ` | Die stabile Maschinen-ID setzen | +| `--machine-label ` | Das Dashboard-Label setzen oder ändern | | `--no-transcripts` | Entscheidungen ohne Transkriptinhalt senden | -| `--disconnect` | Cloud-Richtlinienabfragen und Ereignislieferung stoppen | +| `--disconnect` | Cloud-Richtlinienabfragen und Ereignisübermittlung stoppen | | `--status` | Aktuellen Maschinenstatus anzeigen | -| `--pause [duration]` | Die neueste Sitzung im aktuellen Verzeichnis pausieren; akzeptiert Sekunden, Minuten oder Stunden, Standard 30 Minuten | +| `--pause [duration]` | Die neueste Sitzung im aktuellen Verzeichnis pausieren; akzeptiert Sekunden, Minuten oder Stunden, Standard ist 30 Minuten | | `--resume` | Eine passende Pause vorzeitig beenden | | `--session ` | Eine explizite Sitzung für Pause oder Fortsetzen auswählen | -| `--all` | Zusammen mit `--resume` alle aktiven Pausen beenden | +| `--all` | Mit `--resume` alle aktiven Pausen beenden | -Lokale Pausen setzen eingebaute, benutzerdefinierte und konventionelle Richtlinien für eine Sitzung aus. Sie laufen stets ab und deaktivieren keine Cloud-verwalteten Richtlinien. `block-self-pause` verhindert, dass ein instrumentierter Agent diesen Ausweg selbst nutzt. +Lokale Pausen setzen eingebaute, benutzerdefinierte, konventionsbasierte und Pack-Richtlinien für eine Sitzung aus. Sie laufen immer ab und deaktivieren keine Cloud-verwalteten Richtlinien. `block-failproofai-commands` – das immer aktiv ist und selbst weder deaktiviert noch pausiert werden kann – verhindert, dass ein instrumentierter Agent diesen Ausweg selbst nutzt. ## Richtlinienflags @@ -71,11 +76,11 @@ Lokale Pausen setzen eingebaute, benutzerdefinierte und konventionelle Richtlini | `--install`, `-i` | Richtlinien aktivieren und Harness-Hooks installieren | | `--uninstall`, `-u` | Richtlinien deaktivieren oder Hooks entfernen | | `--cli ` | Einen oder mehrere unterstützte Harnesses auswählen | -| `--scope user\|project\|local\|all` | Konfigurationsbereich wählen; `all` gilt für die Deinstallation | +| `--scope user\|project\|local\|all` | Den Konfigurationsbereich auswählen; `all` ist für die Deinstallation | | `--beta` | Beta-Richtlinien einschließen | -| `--custom`, `-c ` | Benutzerdefinierte Richtliniendatei validieren und laden; wiederholbar | +| `--custom`, `-c ` | Eine benutzerdefinierte Richtliniendatei validieren und laden; wiederholbar | -## Liefer- und Wartungsflags +## Übermittlungs- und Wartungsflags | Befehl | Flags | | --- | --- | @@ -97,9 +102,9 @@ failproofai harness remove-path Unterstützte Harness-Namen sind `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` und `goose`. -Labels versehen abgeleitete Agenten-IDs mit einem Namensraum, wenn zwei Wurzelverzeichnisse Kopien desselben Projekts enthalten. Überlappende Wurzeln und doppelte Labels werden abgelehnt, um doppelte Erfassung oder Cursor-Korruption zu verhindern. Die Konfiguration zusätzlicher Pfade wird ohne Daemon-Neustart neu geladen. +Labels versehen abgeleitete Agent-IDs mit einem Namensraum, wenn zwei Stammverzeichnisse Kopien desselben Projekts enthalten. Überlappende Stammverzeichnisse und doppelte Labels werden abgelehnt, um doppelte Erfassung oder Cursor-Korruption zu verhindern. Die Konfiguration zusätzlicher Pfade wird ohne Daemon-Neustart neu geladen. -Container-Umgebungen können dateibasiert konfigurierte zusätzliche Pfade durch eine kommagetrennte Variable namens `FAILPROOFAI__EXTRA_PATHS` ersetzen, zum Beispiel: +Container-Umgebungen können dateibasierte Zusatzpfade durch eine kommagetrennte Variable namens `FAILPROOFAI__EXTRA_PATHS` ersetzen, zum Beispiel: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -112,21 +117,23 @@ Verwende Konfigurationsdateien für dauerhaftes Maschinenverhalten. Umgebungsvar | Variable | Verwendung | | --- | --- | | `FAILPROOFAI_HOME` | Das vollständige `~/.failproofai`-Layout verschieben | -| `FAILPROOFAI_LOG_LEVEL` | Lokale Protokollierungsdetails festlegen | -| `FAILPROOFAI_HOOK_LOG_FILE` | Hook-Diagnosen in eine ausgewählte Datei schreiben | +| `FAILPROOFAI_LOG_LEVEL` | Lokale Protokollierungsausführlichkeit einstellen | +| `FAILPROOFAI_HOOK_LOG_FILE` | Hook-Diagnosedaten in eine ausgewählte Datei schreiben | | `FAILPROOFAI_TELEMETRY_DISABLED=1` | Anonyme Telemetrie für diesen Prozess deaktivieren | -| `FAILPROOFAI_NO_FIRST_RUN=1` | Interaktives Ersteinrichtungs-Setup überspringen | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Lokalen Audit nach dem Setup überspringen | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Interaktive Ersteinrichtung überspringen | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Lokalen Audit nach der Einrichtung überspringen | | `FAILPROOFAI_LLM_BASE_URL` | Den von LLM-Richtlinien verwendeten OpenAI-kompatiblen Endpunkt überschreiben | -| `FAILPROOFAI_LLM_API_KEY` | Den von LLM-Richtlinien verwendeten API-Schlüssel bereitstellen | +| `FAILPROOFAI_LLM_API_KEY` | Den von LLM-Richtlinien verwendeten API-Schlüssel angeben | | `FAILPROOFAI_LLM_MODEL` | Das von LLM-Richtlinien verwendete Modell auswählen | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Ladezeit benutzerdefinierter Richtlinienmodule begrenzen | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Das Laden benutzerdefinierter Richtlinienmodule zeitlich begrenzen | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Das Abrufen von Packs und Daemon-Binaries ablehnen; bereits Installiertes wird weiter durchgesetzt | +| `FAILPROOFAI_PACK_BASE_URL` | Packs von einem Spiegel statt von `github.com` abrufen | | `FAILPROOFAI__EXTRA_PATHS` | Konfigurierte zusätzliche Erfassungspfade für einen Harness ersetzen | -| `NO_COLOR` | Farbige Terminal-Ausgabe deaktivieren | +| `NO_COLOR` | Farbige Terminalausgabe deaktivieren | -Agentenspezifische Home-Variablen wie `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` und `OPENCLAW_HOME` überschreiben, wo Failproof AI lokale Sitzungen für diesen Harness erkennt. +Agenten-spezifische Home-Variablen wie `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` und `OPENCLAW_HOME` überschreiben, wo Failproof AI lokale Sitzungen für diesen Harness erkennt. -## Maschine sicher pausieren oder entfernen +## Eine Maschine sicher pausieren oder entfernen ```bash failproofai config --pause @@ -136,7 +143,7 @@ failproofai config --resume Eine lokale Sitzungspause deaktiviert keine Cloud-verwalteten Richtlinien. Stelle Cloud-Deployments über den Cloud-Enforcement-Workflow wieder her, wenn das Rollout selbst das Problem ist. -Bevor du das npm-Paket entfernst, entferne die installierten Hooks und den Daemon: +Bevor das npm-Paket entfernt wird, installierte Hooks und den Daemon entfernen: ```bash failproofai uninstall --dry-run @@ -144,8 +151,8 @@ failproofai uninstall --yes npm rm -g failproofai ``` -Führe `failproofai --help` für versionsspezifische Details aus. +Führe `failproofai --help` aus, um versionsspezifische Details zu erhalten. - Führe `failproofai uninstall` vor `npm rm -g failproofai` aus; npm entfernt keine installierten Agenten-Hooks oder den Daemon-Dienst. + Führe `failproofai uninstall` vor `npm rm -g failproofai` aus; npm entfernt weder installierte Agent-Hooks noch den Daemon-Dienst. \ No newline at end of file diff --git a/docs/de/start/quickstart.mdx b/docs/de/start/quickstart.mdx index 515080a8..37dacf98 100644 --- a/docs/de/start/quickstart.mdx +++ b/docs/de/start/quickstart.mdx @@ -1,12 +1,12 @@ --- title: "Quickstart" -description: "Erfasse eine Agent-Session, finde einen Fehler und verhindere ihn." +description: "Zeichne eine Agentensitzung auf, finde einen Fehler und verhindere ihn künftig." icon: "zap" --- -Dieser Quickstart richtet eine Maschine zum Melden von Sessions ein, führt ein Audit durch und stellt eine Policy bereit. Nutze die Skill-Option oder folge den manuellen Schritten. +Dieser Quickstart richtet eine Maschine für das Melden von Sitzungen ein, führt ein Audit durch und stellt eine Policy bereit. Nutze den Skill, um Failproof einzurichten, oder folge den manuellen Schritten. -**Welcher Weg ist deiner?** Wenn dein Agent in einem der 12 unterstützten [Harnesses](/de/reference/harnesses) läuft — einer Coding-CLI oder einem Gateway wie Hermes oder OpenClaw — folge den Schritten unten; du benötigst Node.js 20.9 oder neuer. Wenn dein Agent kein Harness hat, instrumentiere ihn mit dem [Python SDK](/de/reference/custom-agents) für Tracing und Audits und steig dann bei [Ersten Fehlercheck ausführen](/de/start/first-audit) wieder ein; für Durchsetzung auf diesem Weg ist ein Hook in deiner Runtime erforderlich. +**Welcher Weg passt zu dir?** Wenn dein Agent in einem der 12 unterstützten [Harnesses](/de/reference/harnesses) läuft — einem Coding-CLI oder einem Gateway wie Hermes oder OpenClaw — folge den nachstehenden Schritten; du benötigst Node.js 20.9 oder neuer. Wenn dein Agent kein Harness hat, instrumentiere ihn mit dem [Python SDK](/de/reference/custom-agents) für Tracing und Audits und steige dann bei [Führe deine erste Fehlerprüfung durch](/de/start/first-audit) wieder ein; Enforcement auf diesem Weg erfordert einen Hook in deiner Runtime. @@ -16,27 +16,27 @@ Dieser Quickstart richtet eine Maschine zum Melden von Sessions ein, führt ein npx skills add FailproofAI/skills ``` - + ```text Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Dein Agent analysiert das Projekt, wählt die passende Integration, führt das Setup durch und überprüft es. Siehe das [FailproofAI Skills-Repository](https://github.com/FailproofAI/skills) für einzelne Skills und erweiterte Installationsoptionen. + Dein Agent analysiert das Projekt, wählt die passende Integration, führt die Einrichtung durch und überprüft sie. Einzelne Skills und erweiterte Installationsoptionen findest du im [FailproofAI Skills-Repository](https://github.com/FailproofAI/skills). - - ## Bevor du beginnst + + ## Voraussetzungen -1. Öffne das [Failproof AI Dashboard](https://app.befailproof.ai) und erstelle ein Konto oder melde dich mit deiner Arbeits-E-Mail an. -2. Gehe zu **Administration → Keys** und erstelle einen Key mit `events:add` und `policies:pull`. -3. Kopiere das Einmal-Secret und speichere es auf der Zielmaschine: +1. Öffne das [Failproof AI Dashboard](https://app.befailproof.ai) und erstelle ein Konto oder melde dich mit deiner geschäftlichen E-Mail-Adresse an. +2. Gehe zu **Administration → Keys** und erstelle einen Schlüssel mit `events:add` und `policies:pull`. +3. Kopiere das einmalige Secret und speichere es auf der Zielmaschine: ```bash export FAILPROOFAI_KEY="" ``` - ## Installieren + ## Installation @@ -45,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - Session-Transkripte werden standardmäßig übertragen. Füge `--no-transcripts` hinzu, um Hook-Aktivitäten und Policy-Entscheidungen ohne Transkriptinhalte zu melden. + Sitzungstranskripte werden standardmäßig übertragen. Füge `--no-transcripts` hinzu, um Hook-Aktivitäten und Policy-Entscheidungen ohne Transkriptinhalt zu melden. - Falls diese Maschine bereits Agent-Verlaufsdaten hat, zeige die letzten sieben Tage in der Vorschau an und importiere sie, dann warte bis die Übertragung abgeschlossen ist. Überspringe diesen Schritt auf einer neuen Maschine. + Wenn auf dieser Maschine bereits Agentenhistorie vorhanden ist, kannst du die letzten sieben Tage vorab anzeigen und importieren — warte anschließend, bis die Übertragung abgeschlossen ist. Überspringe diesen Schritt auf einer neuen Maschine. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +55,30 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Öffne **Sessions** in Failproof AI und wähle eine importierte Session aus. + Öffne **Sessions** in Failproof AI und wähle eine importierte Sitzung aus. - - Dadurch wird Failproof AI mit deinem Harness verbunden und die 40 integrierten Policies werden installiert. Nutze sie, um lokale Policy-Entscheidungen zu sehen und Durchsetzung auszuprobieren, bevor Failproof AI deine Sessions auditiert und Policies für deine Agents schreibt. + + Damit wird Failproof AI an dein Harness angebunden und die 39 integrierten Policies werden installiert. Nutze sie, um lokale Policy-Entscheidungen zu beobachten und Enforcement auszuprobieren, bevor Failproof AI deine Sitzungen prüft und Policies für deine Agenten erstellt. - Lass den Installer dein Harness erkennen oder gib eines explizit an. Jedes der 12 ist ein gültiger `--cli`-Wert — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + Lass den Installer dein Harness automatisch erkennen oder gib eines explizit an. Alle 12 sind gültige `--cli`-Werte — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash - failproofai policies --install --cli claude --scope user # eine Coding-CLI + failproofai policies --install --cli claude --scope user # ein Coding-CLI failproofai policies --install --cli hermes --scope user # ein Slack/Telegram-Gateway ``` - Das Blockieren eines Tool-Calls vor der Ausführung wird auf allen 12 unterstützt. Turn-End-Gates werden auf 8 unterstützt — siehe [Durchsetzungsfähigkeit](/de/reference/harnesses#enforcement-capability) für die Harness-spezifische Matrix. + Das Blockieren eines Tool-Calls vor seiner Ausführung ist für alle 12 verifiziert. Turn-End-Gates sind für 8 verifiziert — die harnessspezifische Matrix findest du unter [Enforcement-Fähigkeit](/de/reference/harnesses#enforcement-capability). - Folge [Ersten Fehlercheck ausführen](/de/start/first-audit). Nutze ein konkretes Ziel, zum Beispiel: „Sessions finden, in denen der Agent einen fehlschlagenden Tool-Call erneut versucht hat, ohne seinen Ansatz zu ändern." + Folge [Führe deine erste Fehlerprüfung durch](/de/start/first-audit). Verwende ein konkretes Ziel, z. B. „Sitzungen finden, in denen der Agent ein fehlgeschlagenes Tool ohne Änderung des Ansatzes erneut aufgerufen hat." - Folge [Ersten Fehler mit einer Policy verhindern](/de/start/first-policy). Starte im Beobachtungsmodus, prüfe Treffer und setze dann die überprüfte Version durch. + Folge [Verhindere deinen ersten Fehler mit einer Policy](/de/start/first-policy). Beginne im Beobachtungsmodus, prüfe Treffer und setze die überarbeitete Version dann durch. - Führe `failproofai config --status` aus. Ein gesundes Setup meldet die Cloud-Verbindung, den Daemon-Status und ob die Durchsetzung pausiert ist. + Führe `failproofai config --status` aus. Eine gesunde Einrichtung meldet die Cloud-Verbindung, den Daemon-Status und ob Enforcement pausiert ist. \ No newline at end of file diff --git a/docs/docs.json b/docs/docs.json index 81034e0a..cda19dd2 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -323,6 +323,8 @@ "zh/policies/builtin", "zh/policies/builtin-catalog", "zh/policies/custom", + "zh/policies/packs", + "zh/policies/publish-a-pack", "zh/policies/local-configuration", "zh/policies/editor", "zh/policies/deploy", @@ -477,6 +479,8 @@ "ja/policies/builtin", "ja/policies/builtin-catalog", "ja/policies/custom", + "ja/policies/packs", + "ja/policies/publish-a-pack", "ja/policies/local-configuration", "ja/policies/editor", "ja/policies/deploy", @@ -631,6 +635,8 @@ "ko/policies/builtin", "ko/policies/builtin-catalog", "ko/policies/custom", + "ko/policies/packs", + "ko/policies/publish-a-pack", "ko/policies/local-configuration", "ko/policies/editor", "ko/policies/deploy", @@ -785,6 +791,8 @@ "es/policies/builtin", "es/policies/builtin-catalog", "es/policies/custom", + "es/policies/packs", + "es/policies/publish-a-pack", "es/policies/local-configuration", "es/policies/editor", "es/policies/deploy", @@ -939,6 +947,8 @@ "pt-br/policies/builtin", "pt-br/policies/builtin-catalog", "pt-br/policies/custom", + "pt-br/policies/packs", + "pt-br/policies/publish-a-pack", "pt-br/policies/local-configuration", "pt-br/policies/editor", "pt-br/policies/deploy", @@ -1093,6 +1103,8 @@ "de/policies/builtin", "de/policies/builtin-catalog", "de/policies/custom", + "de/policies/packs", + "de/policies/publish-a-pack", "de/policies/local-configuration", "de/policies/editor", "de/policies/deploy", @@ -1247,6 +1259,8 @@ "fr/policies/builtin", "fr/policies/builtin-catalog", "fr/policies/custom", + "fr/policies/packs", + "fr/policies/publish-a-pack", "fr/policies/local-configuration", "fr/policies/editor", "fr/policies/deploy", @@ -1401,6 +1415,8 @@ "ru/policies/builtin", "ru/policies/builtin-catalog", "ru/policies/custom", + "ru/policies/packs", + "ru/policies/publish-a-pack", "ru/policies/local-configuration", "ru/policies/editor", "ru/policies/deploy", @@ -1555,6 +1571,8 @@ "hi/policies/builtin", "hi/policies/builtin-catalog", "hi/policies/custom", + "hi/policies/packs", + "hi/policies/publish-a-pack", "hi/policies/local-configuration", "hi/policies/editor", "hi/policies/deploy", @@ -1709,6 +1727,8 @@ "tr/policies/builtin", "tr/policies/builtin-catalog", "tr/policies/custom", + "tr/policies/packs", + "tr/policies/publish-a-pack", "tr/policies/local-configuration", "tr/policies/editor", "tr/policies/deploy", @@ -1863,6 +1883,8 @@ "vi/policies/builtin", "vi/policies/builtin-catalog", "vi/policies/custom", + "vi/policies/packs", + "vi/policies/publish-a-pack", "vi/policies/local-configuration", "vi/policies/editor", "vi/policies/deploy", @@ -2017,6 +2039,8 @@ "it/policies/builtin", "it/policies/builtin-catalog", "it/policies/custom", + "it/policies/packs", + "it/policies/publish-a-pack", "it/policies/local-configuration", "it/policies/editor", "it/policies/deploy", @@ -2171,6 +2195,8 @@ "ar/policies/builtin", "ar/policies/builtin-catalog", "ar/policies/custom", + "ar/policies/packs", + "ar/policies/publish-a-pack", "ar/policies/local-configuration", "ar/policies/editor", "ar/policies/deploy", @@ -2325,6 +2351,8 @@ "he/policies/builtin", "he/policies/builtin-catalog", "he/policies/custom", + "he/policies/packs", + "he/policies/publish-a-pack", "he/policies/local-configuration", "he/policies/editor", "he/policies/deploy", diff --git a/docs/es/policies/builtin-catalog.mdx b/docs/es/policies/builtin-catalog.mdx index bf487d57..64178e91 100644 --- a/docs/es/policies/builtin-catalog.mdx +++ b/docs/es/policies/builtin-catalog.mdx @@ -1,37 +1,41 @@ --- title: "Catálogo de políticas integradas" -description: "Consulta cada política integrada de Failproof AI, su activador, estado recomendado y parámetros configurables." +description: "Revisa todas las políticas integradas de Failproof AI, su disparador, estado recomendado y parámetros configurables." icon: "list-checks" --- -El paquete instalado es la fuente de verdad para la disponibilidad de políticas. Ejecuta `failproofai policies` después de cada actualización, ya que las entradas del catálogo y el comportamiento pueden cambiar con la versión del paquete. +El paquete instalado es la fuente de verdad para la disponibilidad de políticas. Ejecuta `failproofai policies` tras cada actualización, ya que las entradas del catálogo y el comportamiento pueden cambiar con la versión del paquete. ## Línea base recomendada -La selección recomendada del asistente de configuración guiada activa actualmente los sanitizadores de secretos, las protecciones de entorno, la autoprotección, las salvaguardas de comandos catastróficos y la seguridad de ramas protegidas: +La selección recomendada por la configuración guiada activa actualmente los sanitizadores de secretos, las protecciones de entorno, la autoprotección, las defensas contra comandos catastróficos y la seguridad de ramas protegidas: ```text sanitize-jwt sanitize-api-keys sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars block-env-files block-secrets-write -block-self-pause block-failproofai-commands -block-sudo block-curl-pipe-sh -block-rm-rf block-push-master -block-force-push +block-failproofai-commands block-sudo +block-curl-pipe-sh block-rm-rf +block-push-master block-force-push ``` -La configuración recomendada es deliberadamente más restrictiva que **Todo**. Las políticas de infraestructura y flujo de trabajo pueden interrumpir trabajo válido, por lo que deben habilitarse únicamente en los repositorios y máquinas que las necesiten. +`block-failproofai-commands` está **siempre activo**. Se incluye arriba por +completitud, pero se registra en cada evaluación independientemente de si aparece en +tu conjunto habilitado, y no puede desactivarse ni pausarse — una protección contra +que el agente desactive la aplicación que el propio agente puede desactivar no es una protección. + +La selección recomendada es deliberadamente más acotada que **Todo**. Las políticas de infraestructura y flujo de trabajo pueden interrumpir trabajo válido, y deben habilitarse únicamente en los repositorios y máquinas que las necesiten. ## Secretos y entorno -| Política | Activador | Resultado | +| Política | Disparador | Resultado | | --- | --- | --- | -| `sanitize-jwt` | `PostToolUse` | Redacta los JWT de la salida de la herramienta antes de que el modelo los procese. | +| `sanitize-jwt` | `PostToolUse` | Redacta JWTs de la salida de las herramientas antes de que el modelo los vea. | | `sanitize-api-keys` | `PostToolUse` | Redacta claves comunes de OpenAI, Anthropic, GitHub, AWS, Stripe y Google. | | `sanitize-connection-strings` | `PostToolUse` | Redacta cadenas de conexión a bases de datos que contengan credenciales. | | `sanitize-private-key-content` | `PostToolUse` | Redacta cuerpos de claves privadas PEM. | -| `sanitize-bearer-tokens` | `PostToolUse` | Redacta tokens bearer de autorización. | +| `sanitize-bearer-tokens` | `PostToolUse` | Redacta tokens de autorización de tipo bearer. | | `protect-env-vars` | `PreToolUse` en herramientas de shell | Bloquea comandos que vuelcan variables de entorno. | | `block-env-files` | `PreToolUse` | Bloquea lecturas y escrituras de archivos `.env`. | | `block-read-outside-cwd` | `PreToolUse` en herramientas de lectura, glob, grep o shell | Restringe las lecturas al directorio de trabajo de la sesión. | @@ -39,60 +43,59 @@ La configuración recomendada es deliberadamente más restrictiva que **Todo**. ## Comandos peligrosos e infraestructura -| Política | Activador | Resultado | +| Política | Disparador | Resultado | | --- | --- | --- | -| `block-self-pause` | `PreToolUse`, `PermissionRequest` | Impide que un agente pause su propia aplicación de políticas. | -| `block-sudo` | `PreToolUse`, `PermissionRequest` | Bloquea `sudo` salvo que coincida un patrón de lista de permitidos. | -| `block-curl-pipe-sh` | `PreToolUse` | Bloquea scripts descargados que se redirigen directamente a un shell. | -| `block-rm-rf` | `PreToolUse` | Bloquea patrones de eliminación recursiva catastrófica. | -| `block-failproofai-commands` | `PreToolUse` | Impide que los agentes modifiquen o desinstalen Failproof AI. | -| `block-kubectl` | `PreToolUse` | Controla los comandos de Kubernetes. | -| `block-terraform` | `PreToolUse` | Controla los comandos de Terraform y OpenTofu. | -| `block-aws-cli` | `PreToolUse` | Controla los comandos de la CLI de AWS. | -| `block-gcloud` | `PreToolUse` | Controla los comandos de la CLI de Google Cloud. | -| `block-az-cli` | `PreToolUse` | Controla los comandos de la CLI de Azure. | -| `block-helm` | `PreToolUse` | Controla los comandos de Helm. | -| `block-gh-pipeline` | `PreToolUse` | Controla las operaciones mutantes de workflow, run, merge, release, cache y secret de la CLI de GitHub. | +| `block-sudo` | `PreToolUse`, `PermissionRequest` | Bloquea `sudo` salvo que coincida un patrón de permiso. | +| `block-curl-pipe-sh` | `PreToolUse` | Bloquea scripts descargados y canalizados directamente a un shell. | +| `block-rm-rf` | `PreToolUse` | Bloquea patrones de eliminación recursiva catastróficos. | +| `block-failproofai-commands` | `PreToolUse`, `PermissionRequest` | **Siempre activo, no puede desactivarse.** Bloquea toda invocación del CLI de Failproof AI, autopausas y desinstalaciones mediante gestores de paquetes. | +| `block-kubectl` | `PreToolUse` | Controla comandos de Kubernetes. | +| `block-terraform` | `PreToolUse` | Controla comandos de Terraform y OpenTofu. | +| `block-aws-cli` | `PreToolUse` | Controla comandos del CLI de AWS. | +| `block-gcloud` | `PreToolUse` | Controla comandos del CLI de Google Cloud. | +| `block-az-cli` | `PreToolUse` | Controla comandos del CLI de Azure. | +| `block-helm` | `PreToolUse` | Controla comandos de Helm. | +| `block-gh-pipeline` | `PreToolUse` | Controla operaciones mutantes del CLI de GitHub: workflow, run, merge, release, cache y secret. | ## Seguridad en Git y bases de datos -| Política | Activador | Resultado | +| Política | Disparador | Resultado | | --- | --- | --- | -| `block-push-master` | `PreToolUse` | Bloquea los push directos a las ramas protegidas configuradas. | -| `block-force-push` | `PreToolUse` | Bloquea los force-push; `--force-with-lease` sigue estando permitido por la implementación actual. | +| `block-push-master` | `PreToolUse` | Bloquea pushes directos a las ramas protegidas configuradas. | +| `block-force-push` | `PreToolUse` | Bloquea los force-pushes; `--force-with-lease` sigue siendo permitido por la implementación actual. | | `block-work-on-main` | `PreToolUse` | Bloquea commits y merges en ramas protegidas. | | `warn-git-amend` | `PreToolUse` | Advierte antes de reescribir un commit con `--amend`. | | `warn-git-stash-drop` | `PreToolUse` | Advierte antes de eliminar o limpiar stashes de forma permanente. | -| `warn-all-files-staged` | `PreToolUse` | Advierte sobre `git add -A`, `git add .` o `git add --all` de amplio alcance. | -| `warn-destructive-sql` | `PreToolUse` | Advierte sobre `DROP`, `TRUNCATE` y `DELETE` sin `WHERE` a través de clientes de base de datos reconocidos. | -| `warn-schema-alteration` | `PreToolUse` | Advierte sobre operaciones reconocidas de `ALTER TABLE` en columnas y renombrados. | +| `warn-all-files-staged` | `PreToolUse` | Advierte ante el uso amplio de `git add -A`, `git add .` o `git add --all`. | +| `warn-destructive-sql` | `PreToolUse` | Advierte ante `DROP`, `TRUNCATE` y `DELETE` sin `WHERE` en clientes de base de datos reconocidos. | +| `warn-schema-alteration` | `PreToolUse` | Advierte ante operaciones reconocidas de `ALTER TABLE` para columnas y renombrados. | ## Paquetes, comportamiento del sistema y bucles de agente -| Política | Activador | Resultado | +| Política | Disparador | Resultado | | --- | --- | --- | | `warn-package-publish` | `PreToolUse` | Advierte antes de publicar en registros de paquetes. | | `warn-global-package-install` | `PreToolUse` | Advierte antes de instalar paquetes de forma global. | | `prefer-package-manager` | `PreToolUse` | Instruye al agente para que use un gestor de paquetes permitido. | | `warn-large-file-write` | `PreToolUse` en herramientas de escritura | Advierte cuando se supera el umbral de tamaño de archivo configurado. | -| `warn-background-process` | `PreToolUse` | Advierte sobre patrones de procesos en segundo plano desvinculados o de larga duración. | +| `warn-background-process` | `PreToolUse` | Advierte ante patrones de procesos en segundo plano desacoplados o de larga duración. | | `warn-repeated-tool-calls` | `PreToolUse` | Advierte tras tres o más llamadas idénticas a una herramienta. | -## Flujo de trabajo al finalizar la tarea +## Flujo de trabajo al final de la tarea Estas políticas requieren un harness que emita un evento `Stop` compatible. | Política | Resultado | | --- | --- | | `require-commit-before-stop` | Rechaza la finalización mientras haya trabajo rastreado sin confirmar. | -| `require-push-before-stop` | Rechaza la finalización mientras haya commits que solo existen en local. | -| `require-pr-before-stop` | Requiere una pull request para la rama actual. | +| `require-push-before-stop` | Rechaza la finalización mientras haya commits solo en local. | +| `require-pr-before-stop` | Requiere un pull request para la rama actual. | | `require-no-conflicts-before-stop` | Requiere un merge limpio contra la rama base configurada. | -| `require-ci-green-before-stop` | Requiere que las comprobaciones de CI del HEAD actual se completen satisfactoriamente. | +| `require-ci-green-before-stop` | Requiere que las comprobaciones de CI del HEAD actual finalicen con éxito. | ## Referencia de parámetros -Configura los parámetros en el objeto `policyParams` del ámbito seleccionado. Los tipos son validados por cada política. +Configura los parámetros en el objeto `policyParams` del scope seleccionado. Los tipos son validados por cada política. | Política | Parámetro | Tipo y valor por defecto | | --- | --- | --- | @@ -125,5 +128,5 @@ Configura los parámetros en el objeto `policyParams` del ámbito seleccionado. ``` - Un patrón de lista de permitidos amplía lo que un agente puede hacer. Prueba la tokenización exacta y las variantes de comando en el harness de destino antes de desplegarlo en toda una flota. + Un patrón de permiso amplía lo que un agente puede hacer. Prueba la tokenización exacta y las variantes de comandos en el harness de destino antes de desplegarlo en una flota. \ No newline at end of file diff --git a/docs/es/policies/failure-behavior.mdx b/docs/es/policies/failure-behavior.mdx index 71f66620..50344625 100644 --- a/docs/es/policies/failure-behavior.mdx +++ b/docs/es/policies/failure-behavior.mdx @@ -1,19 +1,19 @@ --- title: "Comportamiento ante fallos" -description: "Entiende qué ocurre cuando la evaluación de políticas o el daemon local no están disponibles." +description: "Entiende qué sucede cuando la evaluación de políticas o el daemon local no están disponibles." icon: "shield-alert" --- -Failproof AI está diseñado para que un fallo de aplicación sea visible en lugar de permitir silenciosamente trabajo riesgoso. +Failproof AI está diseñado para que un fallo de aplicación sea visible, en lugar de permitir silenciosamente trabajo riesgoso. ## Diagnosticar un bloqueo por fallo cerrado - + 1. Ve a **Admin → enforcement** y abre la máquina. - 2. Verifica su último registro de actividad, el despliegue asignado y el despliegue reportado. + 2. Revisa su último registro de entrada, el despliegue asignado y el despliegue reportado. 3. Ve a **Observe → policy** y abre la sesión de la decisión denegada. - 4. Confirma si el motivo indica problemas de alcanzabilidad del daemon, diferencia de versiones o la propia política. + 4. Confirma si el motivo reporta inaccesibilidad del daemon, desajuste de versión o la política en sí. @@ -23,21 +23,45 @@ Failproof AI está diseñado para que un fallo de aplicación sea visible en lug failproofai config ``` - Volver a ejecutar `failproofai config` actualiza y reinicia el daemon tras actualizar el paquete. + Volver a ejecutar `failproofai config` actualiza y reinicia el daemon tras una actualización del paquete. -En una máquina configurada para usar `failproofaid`, el daemon es el único evaluador. Si no es alcanzable o su versión de protocolo no coincide con la del CLI, la evaluación de hooks falla de forma cerrada. La acción se deniega con un motivo que indica al operador que verifique o actualice el daemon. +En una máquina configurada para usar `failproofaid`, el daemon es el único evaluador. Si no es accesible o su versión de protocolo no coincide con la CLI, la evaluación del hook falla en modo cerrado. La acción se deniega con un motivo que indica al operador que verifique o actualice el daemon. -Antes de la configuración del daemon, los hooks evalúan las políticas en proceso. Una vez que la configuración del daemon queda registrada, Failproof AI no recurre silenciosamente a un segundo evaluador cuando el daemon falla. +Antes de configurar el daemon, los hooks evalúan las políticas en proceso. Una vez que la configuración del daemon queda registrada, Failproof AI no recurre silenciosamente a un segundo evaluador cuando el daemon falla. -## Responder ante una decisión de fallo cerrado +## Responder a una decisión de fallo cerrado 1. Ejecuta `failproofai config --status`. 2. Si las versiones difieren, vuelve a ejecutar `failproofai config` después de actualizar el paquete. -3. Si el daemon no es alcanzable, inspecciona el estado de su servicio y los registros locales. -4. Reanuda el trabajo del agente solo después de confirmar que la ruta de evaluación de políticas está funcionando correctamente. +3. Si el daemon no es accesible, inspecciona el estado de su servicio y los logs locales. +4. Reanuda el trabajo del agente solo después de confirmar que la ruta de evaluación de políticas conocida está en buen estado. - No reintentes repetidamente la acción bloqueada. Una respuesta de fallo cerrado significa que el sistema no pudo determinar que la acción era segura. - \ No newline at end of file + No reintentes repetidamente la acción bloqueada. Una respuesta de fallo cerrado significa que el sistema no pudo establecer que la acción era segura. + + +## Un pack no carga + +Una máquina a la que se le indicó aplicar un pack, y no puede ejecutarlo, deniega en lugar de continuar silenciosamente. El disparador es una **expectativa registrada**, nunca una vacía: una máquina sin packs instalados permanece en silencio, mientras que un pack que está declarado y no se puede resolver — o que registra menos de lo que declara su manifiesto — deniega. + +La denegación es **acotada**, a diferencia de un daemon inaccesible. Un daemon que no puede alcanzarse significa que no se realizó ninguna evaluación, por lo que nada puede considerarse seguro. Un pack que no carga tiene un conjunto enumerable de guardas faltantes, ya que cada política declarada lleva su propio `match` — por lo tanto, deniega solo los eventos y herramientas que esas políticas cubrían, y todo lo demás continúa. + +No se activa para: + +- un pack de `observe`, que evalúa y descarta por construcción +- políticas que nunca tomaste, o que desactivaste explícitamente +- un pack que el cargador nunca recibió, donde "sin registros" no se puede distinguir de una omisión deliberada +- una pausa de sesión activa +- un tiempo de espera de carga, que es transitorio — un momento de disco lento no debe denegar hasta que intervenga un humano + +`UserPromptSubmit` **instructs** en lugar de denegar, independientemente de lo que declarara la política faltante. Una denegación general lo incluiría y te dejaría sin acceso al agente que podría solucionar el problema. + +### Qué hacer + +```bash +failproofai pack list +``` + +Nombra cualquier pack instalado que no cargue, indica el motivo y termina con código distinto de cero. Luego reinstálalo (`failproofai pack add `) o elimínalo (`failproofai pack remove `) — eliminarlo retira la expectativa, y la denegación cesa con ella. \ No newline at end of file diff --git a/docs/es/policies/packs.mdx b/docs/es/policies/packs.mdx new file mode 100644 index 00000000..5e862d13 --- /dev/null +++ b/docs/es/policies/packs.mdx @@ -0,0 +1,110 @@ +--- +title: "Paquetes de políticas" +description: "Instala un conjunto de políticas publicadas como una versión de GitHub y gestiona lo que se aplica." +icon: "package" +--- + +Un paquete es un conjunto de políticas publicadas como una versión de GitHub. Un solo comando lo instala, los checksums propios de la versión se verifican antes de ejecutar nada, y el digest queda registrado para que el paquete no pueda cambiar en tu máquina posteriormente. + +## Instalar las políticas de Failproof AI + +```bash +failproofai pack add core +``` + +Esto instala el conjunto que publicamos, desde la copia incluida en el paquete npm, por lo que no necesita red y no puede fallar detrás de un proxy. Puedes instalar solo una parte: + +```bash +failproofai pack add core --policy block-rm-rf # una, o varias separadas por comas +failproofai pack add core --category dangerous-commands # una categoría completa +failproofai pack add core --all # todo lo que contiene +``` + +`failproofai pack list` muestra todas las categorías que ofrece el paquete. + +## Ver qué contiene un paquete antes de instalarlo + +```bash +failproofai pack list acme/support-agent +``` + +Lista todas las políticas del paquete, agrupadas por categoría, indicando cuáles activa su autor por defecto y cuáles son opcionales. Solo lee el **manifiesto** — el artefacto principal nunca se descarga ni se importa, así que consultar el paquete de un desconocido no puede ejecutar código ajeno. El manifiesto se verifica igualmente contra el archivo `SHA256SUMS` de la versión, de modo que lo que estás leyendo es exactamente lo que se instalaría. + +`failproofai pack list` sin ningún argumento lista los paquetes ya instalados en esta máquina. + +## Instalar el paquete de otra persona + +```bash +failproofai pack add acme/support-agent +``` + +Cualquiera de estas formas funciona — pega la que tengas a mano: + +| Origen | Resultado | +| --- | --- | +| `acme/support-agent` | Versión más reciente, **fijada** al tag exacto que se resolvió | +| `acme/support-agent@v2.1.0` | Esa versión concreta | +| `github:acme/support-agent@v2.1.0` | Lo mismo, escrito de forma explícita | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | Lo mismo, copiado desde el navegador | + +Si no se especifica ningún tag, se instala la versión más reciente **y se fija**, informándote del tag elegido. Lo que queda registrado siempre nombra exactamente una versión, así que una reinstalación no puede derivar. + +## Instalar solo una parte de un paquete + +Por defecto obtienes los **propios** valores predeterminados del paquete — las políticas que su autor marcó como seguras para activar sin supervisión — no todo lo que contiene. + +```bash +failproofai pack add acme/support-agent --category billing,git +failproofai pack add acme/support-agent --policy block-refunds +failproofai pack add acme/support-agent --all +``` + +`--category` y `--policy` se combinan como unión (`--only` se acepta como sinónimo de `--policy`). Al volver a añadir el paquete en una versión más reciente se conserva lo que elegiste en lugar de reactivar el resto. + +## Gestionar lo que está activo + +```bash +failproofai policies # todas las fuentes en una lista, paquetes incluidos +failproofai pack list # solo paquetes, agrupados por categoría +failproofai policies --uninstall block-refunds # desactivar una política de paquete +failproofai policies --install block-refunds # volver a activarla +failproofai pack remove acme/support-agent +``` + +Un nombre sin prefijo hace referencia a la política **incorporada** si existe una con ese nombre. Especifica la copia de un paquete de forma explícita cuando lo necesites: + +```bash +failproofai policies --uninstall acme/support-agent:block-refunds +``` + + +Si un paquete incluye una política cuyo nombre coincide con un **incorporado habilitado**, el incorporado se ejecuta y la copia del paquete se omite — de lo contrario, la misma protección se evaluaría dos veces. Desactiva el incorporado para usar la copia del paquete en su lugar. + + +## De dónde vienen las políticas de Failproof AI + +`core` lee la copia incluida en el paquete npm. El mismo conjunto se publica como una versión de GitHub, que es lo que se instala si quieres una versión específica: + +```bash +failproofai pack add core # desde este paquete, sin red +failproofai pack add FailproofAI/policies # el mismo conjunto, desde su versión de GitHub +``` + +## Qué garantiza la integridad y qué no + +`SHA256SUMS` se distribuye en la misma versión que el artefacto, por lo que **no** es una firma y no prueba nada sobre quién lo publicó. Lo que sí prueba es que los bytes son los que esa versión publicó — y como el digest se registra al añadir el paquete y se vuelve a verificar antes de cada importación, un paquete no puede cambiar en tu máquina posteriormente. Un repositorio que reetiquetar o reemplaza un asset deja de cargarse en lugar de ejecutar silenciosamente algo diferente. + +En el momento de la instalación, el paquete también se **importa una vez** y se verifica contra su propio manifiesto. Un paquete cuyo artefacto no se puede analizar, o que registra algo distinto a lo que declara, se rechaza antes de activar nada — en lugar de instalarse correctamente y fallar en tu siguiente llamada a una herramienta. + +## Cuándo un paquete no carga + +Un paquete que esta máquina tiene orden de aplicar y no puede ejecutar **deniega** los eventos cubiertos por sus políticas ausentes, en lugar de permitirlos silenciosamente. Consulta [Comportamiento ante fallos](/es/policies/failure-behavior). `failproofai pack list` identifica cualquier paquete en ese estado y termina con código de salida distinto de cero. + +## Sin conexión y mirrors + +| Variable | Efecto | +| --- | --- | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Rechaza cualquier descarga; los paquetes ya instalados siguen aplicándose | +| `FAILPROOFAI_PACK_BASE_URL` | Redirige la descarga de paquetes a un mirror en lugar de `github.com` | + +Para publicar tu propio paquete, consulta [Publicar un paquete](/es/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/es/policies/publish-a-pack.mdx b/docs/es/policies/publish-a-pack.mdx new file mode 100644 index 00000000..915b02eb --- /dev/null +++ b/docs/es/policies/publish-a-pack.mdx @@ -0,0 +1,91 @@ +--- +title: "Publicar un pack" +description: "Distribuye tus propias políticas como una release de GitHub que cualquiera puede instalar." +icon: "upload" +--- + +Un pack son tres archivos adjuntos a una release de GitHub. `failproofai pack build` genera los tres a partir de un archivo de políticas que ya tienes. + +## 1. Escribe las políticas + +Un solo archivo, usando la misma API que cualquier política personalizada. Dos campos adicionales son importantes para un pack: + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-refunds", + description: "Refunds above the approved limit need a human", + category: "Billing", // groups it, and is what --category selects on + defaultEnabled: true, // switched on by a plain `pack add` + match: { events: ["PreToolUse"], tools: ["Bash"] }, + fn: async (ctx) => + String(ctx.toolInput?.command ?? "").includes("refund") + ? deny("Refunds need a human. Ask before running this.") + : allow(), +}); +``` + +`defaultEnabled` es **false** por defecto cuando se omite. Un `failproofai pack add` simple solo activa lo que hayas marcado — instalar automáticamente todas las políticas de un desconocido no es una decisión que el instalador deba tomar por su usuario. + + +La entrada debe ser **un único archivo autocontenido**. Solo la entrada tiene el digest fijado, por lo que un pack que importe archivos locales no podría garantizar honestamente que el digest cubre lo que se ejecuta. Primero empaqueta con (`esbuild`, `bun build`, `rollup`) y construye el pack desde el bundle — `pack build` rechaza una importación local en lugar de hacer una promesa que no puede cumplir. + + +## 2. Construye los archivos de la release + +```bash +failproofai pack build ./policies.mjs \ + --id acme/support-agent \ + --version 1.0.0 \ + --out ./dist-pack +``` + +Genera tres archivos y valida cada política con las **reglas propias del loader** antes — así un pack que nunca podría instalarse falla aquí, donde puedes corregirlo: + +| Archivo | Descripción | +| --- | --- | +| `failproofai-pack.json` | El manifiesto: id, versión, efecto y una entrada por política | +| `failproofai-pack.mjs` | Tu entrada, tal cual | +| `SHA256SUMS` | ` ` para los otros dos | + +Se rechaza en tiempo de construcción: un id que no sea `publisher/name`, un nombre de política que contenga `/`, una política que declare `alwaysOn`, una `description`, `category` o `match` ausente, una entrada que no registra nada, y una entrada que importa archivos locales. + +## 3. Adjúntalos a una release + +Etiqueta la release con la misma versión que construiste y adjunta los tres archivos como assets de la release: + +```bash +gh release create 1.0.0 \ + ./dist-pack/failproofai-pack.json \ + ./dist-pack/failproofai-pack.mjs \ + ./dist-pack/SHA256SUMS +``` + +Ahora cualquiera puede instalarlo: + +```bash +failproofai pack add acme/support-agent +``` + +Los nombres de los assets son fijos — son los que la CLI del consumidor usa para construir sus URLs, sin llamadas a la API ni descubrimiento automático. + +## Publicar una nueva versión + +Construye con el nuevo `--version`, crea una nueva release, adjunta los tres assets nuevamente. Los consumidores ejecutan el mismo `pack add` y conservan el subconjunto que habían elegido; una política que desactivaron permanece desactivada tras la actualización. + +Cambiar el **nombre** de una política es un cambio incompatible: una máquina que la había desactivado está desactivando un nombre que ya no existe, y el nuevo nombre llega con lo que `defaultEnabled` indique. + +## En qué confían tus usuarios + +`SHA256SUMS` vive en la misma release que el artefacto, por lo que prueba que los bytes son los que publicaste — no quién eres. Cualquiera que pueda escribir en el repositorio puede escribir ambos archivos. La protección de tus usuarios es que el digest queda fijado al instalar, de modo que lo que publicaste no puede cambiar posteriormente. + +Publica desde un repositorio cuyo acceso de escritura controles, y trata una release de pack como si fuera la publicación de un paquete. + +## Observar antes de aplicar + +Un manifiesto puede declarar `"effect": "observe"`. Esas políticas se ejecutan y sus veredictos se **registran y descartan** — nada queda bloqueado. Es la forma de medir una nueva regla frente al tráfico real antes de que pueda interrumpir el trabajo de alguien. + +```json +{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +``` \ No newline at end of file diff --git a/docs/es/reference/failproof-cli.mdx b/docs/es/reference/failproof-cli.mdx index 545f38cd..f481903a 100644 --- a/docs/es/reference/failproof-cli.mdx +++ b/docs/es/reference/failproof-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof AI CLI" -description: "Instala hooks, gestiona políticas locales, conecta a Cloud y opera el demonio local." +description: "Instala hooks, gestiona políticas locales, conecta con Cloud y opera el daemon local." icon: "terminal" --- -Instala la CLI local con `npm install -g failproofai`. Ejecútala sin argumentos para abrir el panel de políticas local. +Instala el CLI local con `npm install -g failproofai`. Ejecútalo sin argumentos para abrir el panel de políticas local. -El paquete requiere Node.js 20.9 o superior. Bun 1.3 o superior es compatible para desarrollo e instalaciones desde fuente. `failproofai configure` y `failproofai setup` son alias de `failproofai config`; `failproofai p` es un alias de `failproofai policies`. +El paquete requiere Node.js 20.9 o superior. Bun 1.3 o superior es compatible para desarrollo e instalaciones desde el código fuente. `failproofai configure` y `failproofai setup` son alias de `failproofai config`; `failproofai p` es un alias de `failproofai policies`. ## Configurar una máquina @@ -25,59 +25,64 @@ Ejecuta `failproofai` sin argumentos para abrir el panel de políticas local. | Comando | Resultado | | --- | --- | | `failproofai config` | Ejecuta la configuración interactiva de la máquina | -| `failproofai config --connect --token ` | Conecta la ingesta Cloud y la entrega de políticas | -| `failproofai config --status` | Muestra el estado de la conexión, el demonio, la entrega y la pausa | -| `failproofai policies` | Lista las políticas integradas y personalizadas | -| `failproofai policies --install` | Instala hooks y habilita políticas | -| `failproofai policy add ` | Habilita una política integrada | -| `failproofai policy remove ` | Deshabilita una política integrada | -| `failproofai policies --uninstall` | Deshabilita políticas o elimina los hooks del harness | -| `failproofai audit` | Analiza el historial local del agente y abre la vista de auditoría local | -| `failproofai audit --schedule [days] --email
` | Programa análisis locales recurrentes y envía sus resultados por correo | -| `failproofai audit --status` | Muestra la dirección del informe, el intervalo y el próximo análisis programado | -| `failproofai audit --no-schedule` | Detiene los análisis recurrentes sin eliminar el historial de auditoría | +| `failproofai config --connect --token ` | Conecta la ingesta de Cloud y la entrega de políticas | +| `failproofai config --status` | Muestra el estado de conexión, daemon, entrega y pausa | +| `failproofai policies` | Lista las políticas integradas, personalizadas, de convención, de pack y gestionadas por Cloud | +| `failproofai policies --install` | Instala hooks y activa las políticas | +| `failproofai policy add ` | Activa una política: una integrada o `:` de un pack instalado | +| `failproofai policy remove ` | Desactiva una política con la misma nomenclatura | +| `failproofai policies --uninstall` | Desactiva políticas o elimina los hooks del harness | +| `failproofai pack list` | Lista los packs de políticas instalados y todas las políticas que incluye cada uno | +| `failproofai pack add ` | Instala un pack de políticas desde una release de GitHub; sin etiqueta toma la más reciente y la fija | +| `failproofai pack add --bundled` | Instala las políticas integradas como un pack, desde este paquete, sin red | +| `failproofai pack build ` | Construye los tres archivos de release para un pack propio | +| `failproofai pack remove ` | Desactiva un pack instalado | +| `failproofai audit` | Escanea el historial del agente local y abre la vista de auditoría local | +| `failproofai audit --schedule [days] --email
` | Programa escaneos locales periódicos y envía los hallazgos por correo | +| `failproofai audit --status` | Muestra la dirección de informes, el intervalo y el próximo escaneo programado | +| `failproofai audit --no-schedule` | Detiene los escaneos periódicos sin eliminar el historial de auditoría | | `failproofai harness list` | Lista las rutas de captura adicionales | -| `failproofai flush --wait` | Entrega el spool de eventos actual | -| `failproofai backfill --since 30d` | Vuelve a leer el historial previamente procesado | -| `failproofai config --pause [duration]` | Pausa una sesión local durante 30 minutos por defecto, hasta 8 horas | +| `failproofai flush --wait` | Entrega la cola de eventos actual | +| `failproofai backfill --since 30d` | Relee el historial previamente procesado | +| `failproofai config --pause [duration]` | Pausa una sesión local durante 30 minutos por defecto, hasta un máximo de 8 horas | | `failproofai config --resume` | Reanuda una sesión local pausada; añade `--all` para limpiar todas las pausas | -| `failproofai update` | Completa las migraciones del paquete y actualiza el demonio | +| `failproofai update` | Completa las migraciones del paquete y actualiza el daemon | | `failproofai migrate --dry-run` | Previsualiza o ejecuta las migraciones de diseño del directorio home pendientes | -| `failproofai uninstall` | Elimina los hooks y el demonio antes de desinstalar el paquete | +| `failproofai uninstall` | Elimina los hooks y el daemon antes de desinstalar el paquete | | `failproofai --version` | Muestra la versión del paquete instalado | | `failproofai --help` | Muestra los comandos y el uso global | -## Flags de configuración +## Opciones de configuración -| Flag | Uso | +| Opción | Uso | | --- | --- | | `--connect --token ` | Conecta de forma no interactiva | | `--machine-id ` | Establece el ID estable de la máquina | | `--machine-label ` | Establece o cambia la etiqueta del panel | | `--no-transcripts` | Envía decisiones sin el contenido de la transcripción | -| `--disconnect` | Detiene las extracciones de políticas Cloud y la entrega de eventos | +| `--disconnect` | Detiene las descargas de políticas de Cloud y la entrega de eventos | | `--status` | Muestra el estado actual de la máquina | | `--pause [duration]` | Pausa la sesión más reciente en el directorio actual; acepta segundos, minutos u horas y tiene un valor por defecto de 30 minutos | -| `--resume` | Finaliza una pausa coincidente antes de tiempo | +| `--resume` | Finaliza anticipadamente una pausa coincidente | | `--session ` | Apunta a una sesión explícita para pausar o reanudar | -| `--all` | Junto con `--resume`, finaliza todas las pausas activas | +| `--all` | Con `--resume`, finaliza todas las pausas activas | -Las pausas locales suspenden las políticas integradas, personalizadas y de convención para una sesión. Siempre expiran y no deshabilitan las políticas gestionadas por Cloud. `block-self-pause` impide que un agente instrumentado use este mecanismo de escape por sí mismo. +Las pausas locales suspenden las políticas integradas, personalizadas, de convención y de pack para una sesión. Siempre expiran y no desactivan las políticas gestionadas por Cloud. `block-failproofai-commands` —que siempre está activo y no puede desactivarse ni pausarse— impide que un agente instrumentado use esta vía de escape. -## Flags de políticas +## Opciones de políticas -| Flag | Uso | +| Opción | Uso | | --- | --- | -| `--install`, `-i` | Habilita políticas e instala hooks del harness | -| `--uninstall`, `-u` | Deshabilita políticas o elimina hooks | +| `--install`, `-i` | Activa las políticas e instala los hooks del harness | +| `--uninstall`, `-u` | Desactiva las políticas o elimina los hooks | | `--cli ` | Apunta a uno o más harnesses compatibles | | `--scope user\|project\|local\|all` | Elige el ámbito de configuración; `all` es para desinstalar | -| `--beta` | Incluye políticas en versión beta | -| `--custom`, `-c ` | Valida y carga un archivo de política personalizada; repetible | +| `--beta` | Incluye políticas en fase beta | +| `--custom`, `-c ` | Valida y carga un archivo de política personalizado; se puede repetir | -## Flags de entrega y mantenimiento +## Opciones de entrega y mantenimiento -| Comando | Flags | +| Comando | Opciones | | --- | --- | | `backfill` | `--since <30d\|6m\|YYYY-MM-DD>`, `--dry-run` | | `flush` | `--wait`, `--timeout ` | @@ -85,9 +90,9 @@ Las pausas locales suspenden las políticas integradas, personalizadas y de conv | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` debe ejecutarse después de `npm install -g failproofai@latest`; realiza las migraciones del diseño del directorio home, instala el binario del demonio correspondiente y reinicia el servicio. `--no-daemon` solo realiza la migración del diseño. +`failproofai update` debe ejecutarse después de `npm install -g failproofai@latest`; realiza las migraciones del diseño del directorio home, instala el binario del daemon correspondiente y reinicia el servicio. `--no-daemon` realiza únicamente la migración del diseño. -## Rutas de harness +## Rutas del harness ```text failproofai harness list [harness] @@ -97,9 +102,9 @@ failproofai harness remove-path Los nombres de harness compatibles son `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` y `goose`. -Las etiquetas dan espacio de nombres a los IDs de agente derivados cuando dos raíces contienen copias del mismo proyecto. Las raíces superpuestas y las etiquetas duplicadas se rechazan para evitar recolección duplicada o corrupción del cursor. La configuración de rutas adicionales se recarga sin necesidad de reiniciar el demonio. +Las etiquetas delimitan los IDs de agente derivados cuando dos raíces contienen copias del mismo proyecto. Las raíces solapadas y las etiquetas duplicadas son rechazadas para evitar la recolección duplicada o la corrupción del cursor. La configuración de rutas adicionales se recarga sin necesidad de reiniciar el daemon. -Los entornos de contenedor pueden reemplazar las rutas adicionales configuradas en archivos con una variable separada por comas llamada `FAILPROOFAI__EXTRA_PATHS`, por ejemplo: +Los entornos de contenedor pueden reemplazar las rutas adicionales configuradas en archivos mediante una variable separada por comas con el nombre `FAILPROOFAI__EXTRA_PATHS`, por ejemplo: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -113,18 +118,20 @@ Usa archivos de configuración para el comportamiento persistente de la máquina | --- | --- | | `FAILPROOFAI_HOME` | Reubica el diseño completo de `~/.failproofai` | | `FAILPROOFAI_LOG_LEVEL` | Establece la verbosidad del registro local | -| `FAILPROOFAI_HOOK_LOG_FILE` | Escribe diagnósticos de hooks en un archivo seleccionado | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Deshabilita la telemetría anónima para este proceso | -| `FAILPROOFAI_NO_FIRST_RUN=1` | Omite la configuración interactiva del primer arranque | +| `FAILPROOFAI_HOOK_LOG_FILE` | Escribe los diagnósticos del hook en un archivo seleccionado | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Desactiva la telemetría anónima para este proceso | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Omite la configuración interactiva del primer inicio | | `FAILPROOFAI_NO_AUTO_AUDIT=1` | Omite la auditoría local posterior a la configuración | -| `FAILPROOFAI_LLM_BASE_URL` | Reemplaza el endpoint compatible con OpenAI usado por las políticas LLM | -| `FAILPROOFAI_LLM_API_KEY` | Proporciona la clave API usada por las políticas LLM | -| `FAILPROOFAI_LLM_MODEL` | Selecciona el modelo usado por las políticas LLM | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limita la carga del módulo de políticas personalizadas | +| `FAILPROOFAI_LLM_BASE_URL` | Reemplaza el endpoint compatible con OpenAI utilizado por las políticas LLM | +| `FAILPROOFAI_LLM_API_KEY` | Proporciona la clave de API utilizada por las políticas LLM | +| `FAILPROOFAI_LLM_MODEL` | Selecciona el modelo utilizado por las políticas LLM | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limita el tiempo de carga del módulo de política personalizada | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Impide la descarga de packs y binarios del daemon; lo que esté instalado continúa aplicándose | +| `FAILPROOFAI_PACK_BASE_URL` | Descarga packs desde un espejo en lugar de `github.com` | | `FAILPROOFAI__EXTRA_PATHS` | Reemplaza las rutas de captura adicionales configuradas para un harness | -| `NO_COLOR` | Deshabilita la salida de terminal con colores | +| `NO_COLOR` | Desactiva la salida de terminal con color | -Las variables de directorio home específicas del agente, como `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` y `OPENCLAW_HOME`, anulan la ubicación donde Failproof AI descubre las sesiones locales para ese harness. +Las variables de directorio home específicas del agente, como `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` y `OPENCLAW_HOME`, reemplazan la ubicación donde Failproof AI descubre las sesiones locales para ese harness. ## Pausar o eliminar una máquina de forma segura @@ -134,9 +141,9 @@ failproofai config --status failproofai config --resume ``` -Una pausa de sesión local no deshabilita las políticas gestionadas por Cloud. Restaura los despliegues de Cloud a través del flujo de trabajo de aplicación de Cloud cuando el propio despliegue es el problema. +Una pausa de sesión local no desactiva las políticas gestionadas por Cloud. Restaura los despliegues de Cloud a través del flujo de trabajo de aplicación de Cloud cuando el propio despliegue es el problema. -Antes de eliminar el paquete npm, elimina los hooks instalados y el demonio: +Antes de eliminar el paquete npm, elimina los hooks instalados y el daemon: ```bash failproofai uninstall --dry-run @@ -147,5 +154,5 @@ npm rm -g failproofai Ejecuta `failproofai --help` para obtener detalles específicos de la versión. - Ejecuta `failproofai uninstall` antes de `npm rm -g failproofai`; npm no elimina los hooks del agente instalados ni el servicio del demonio. + Ejecuta `failproofai uninstall` antes de `npm rm -g failproofai`; npm no elimina los hooks del agente instalados ni el servicio del daemon. \ No newline at end of file diff --git a/docs/es/start/quickstart.mdx b/docs/es/start/quickstart.mdx index 9c330db2..5ecd4886 100644 --- a/docs/es/start/quickstart.mdx +++ b/docs/es/start/quickstart.mdx @@ -1,12 +1,12 @@ --- title: "Inicio rápido" -description: "Captura una sesión de agente, detecta un fallo y empieza a prevenirlo." +description: "Captura una sesión del agente, encuentra un fallo y empieza a prevenirlo." icon: "zap" --- -Este inicio rápido configura una máquina para que reporte sesiones, ejecuta una auditoría y despliega una política. Usa la skill para configurar Failproof o sigue los pasos manuales. +Este inicio rápido conecta una máquina para que reporte sesiones, ejecuta una auditoría y despliega una política. Usa la skill para configurar Failproof AI, o sigue los pasos manuales. -**¿Cuál es tu camino?** Si tu agente se ejecuta en uno de los 12 [harnesses](/es/reference/harnesses) compatibles — una CLI de codificación, o una gateway como Hermes u OpenClaw — sigue los pasos a continuación; necesitas Node.js 20.9 o posterior. Si tu agente no tiene harness, instrumértalo con el [SDK de Python](/es/reference/custom-agents) para trazado y auditorías, y luego continúa en [Ejecuta tu primera verificación de fallos](/es/start/first-audit); el control de acceso en esa ruta requiere un hook en tu runtime. +**¿Cuál es tu camino?** Si tu agente se ejecuta en uno de los 12 [harnesses](/es/reference/harnesses) compatibles — una CLI de programación, o un gateway como Hermes u OpenClaw — sigue los pasos a continuación; necesitas Node.js 20.9 o posterior. Si tu agente no tiene harness, instrumétalo con el [SDK de Python](/es/reference/custom-agents) para trazas y auditorías, y luego continúa en [Ejecuta tu primera verificación de fallos](/es/start/first-audit); la aplicación de políticas en ese camino requiere un hook en tu runtime. @@ -21,7 +21,7 @@ Este inicio rápido configura una máquina para que reporte sesiones, ejecuta un Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Tu agente inspecciona el proyecto, elige la integración correspondiente, realiza la configuración y la verifica. Consulta el [repositorio de skills de FailproofAI](https://github.com/FailproofAI/skills) para ver skills individuales y opciones de instalación avanzadas. + Tu agente inspecciona el proyecto, elige la integración relevante, realiza la configuración y la verifica. Consulta el [repositorio de skills de FailproofAI](https://github.com/FailproofAI/skills) para ver skills individuales y opciones de instalación avanzadas. @@ -45,7 +45,7 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - Las transcripciones de sesiones se envían por defecto. Añade `--no-transcripts` para reportar la actividad de hooks y las decisiones de políticas sin el contenido de la transcripción. + Los transcritos de sesión se envían de forma predeterminada. Añade `--no-transcripts` para reportar la actividad de hooks y las decisiones de políticas sin el contenido del transcrito. Si esta máquina ya tiene historial de agente, previsualiza e importa los últimos siete días, luego espera a que finalice la entrega. Omite este paso en una máquina nueva. @@ -58,27 +58,27 @@ export FAILPROOFAI_KEY="" Abre **Sessions** en Failproof AI y selecciona una sesión importada. - Esto conecta Failproof AI a tu harness e instala las 40 políticas integradas. Úsalas para ver las decisiones de políticas locales y probar el control de acceso antes de que Failproof AI audite tus sesiones y escriba políticas para tus agentes. + Esto conecta Failproof AI a tu harness e instala las 39 políticas integradas. Úsalas para ver las decisiones de políticas locales y probar la aplicación antes de que Failproof AI audite tus sesiones y escriba políticas para tus agentes. Deja que el instalador detecte tu harness, o indícalo explícitamente. Cualquiera de los 12 es un valor válido para `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash - failproofai policies --install --cli claude --scope user # una CLI de codificación - failproofai policies --install --cli hermes --scope user # una gateway de Slack/Telegram + failproofai policies --install --cli claude --scope user # una CLI de programación + failproofai policies --install --cli hermes --scope user # un gateway de Slack/Telegram ``` - El bloqueo de una llamada a herramienta antes de que se ejecute está verificado en los 12. Las compuertas de fin de turno están verificadas en 8 — consulta la [capacidad de control de acceso](/es/reference/harnesses#enforcement-capability) para ver la matriz por harness. + El bloqueo de una llamada a herramienta antes de que se ejecute está verificado en los 12. Las compuertas de fin de turno están verificadas en 8 — consulta la [capacidad de aplicación](/es/reference/harnesses#enforcement-capability) para ver la matriz por harness. - Sigue [Ejecuta tu primera verificación de fallos](/es/start/first-audit). Usa un objetivo concreto como «encontrar sesiones donde el agente reintentó una herramienta fallida sin cambiar su enfoque». + Sigue [Ejecuta tu primera verificación de fallos](/es/start/first-audit). Usa un objetivo concreto como "encontrar sesiones donde el agente reintentó una herramienta fallida sin cambiar su enfoque". - Sigue [Previene tu primer fallo con una política](/es/start/first-policy). Empieza en modo de observación, inspecciona las coincidencias y luego aplica la versión revisada. + Sigue [Previene tu primer fallo con una política](/es/start/first-policy). Empieza en modo observación, inspecciona las coincidencias y luego aplica la versión revisada. - Ejecuta `failproofai config --status`. Una configuración correcta reporta la conexión en la nube, el estado del daemon y si el control de acceso está pausado. + Ejecuta `failproofai config --status`. Una configuración saludable reporta la conexión a la nube, el estado del daemon y si la aplicación de políticas está pausada. \ No newline at end of file diff --git a/docs/fr/policies/builtin-catalog.mdx b/docs/fr/policies/builtin-catalog.mdx index 3ad4b839..4305632e 100644 --- a/docs/fr/policies/builtin-catalog.mdx +++ b/docs/fr/policies/builtin-catalog.mdx @@ -1,94 +1,98 @@ --- title: "Catalogue des politiques intégrées" -description: "Découvrez chaque politique intégrée de Failproof AI, son déclencheur, l'état recommandé et ses paramètres configurables." +description: "Consultez chaque politique intégrée de Failproof AI, son déclencheur, l'état recommandé et les paramètres configurables." icon: "list-checks" --- -Le package installé fait autorité quant à la disponibilité des politiques. Exécutez `failproofai policies` après chaque mise à jour, car les entrées du catalogue et leur comportement peuvent évoluer avec la version du package. +Le package installé fait foi pour la disponibilité des politiques. Exécutez `failproofai policies` après chaque mise à jour, car les entrées du catalogue et leur comportement peuvent évoluer avec la version du package. -## Configuration de référence recommandée +## Base recommandée -La sélection recommandée par l'assistant de configuration active actuellement les assainisseurs de secrets, les protections d'environnement, la protection du service lui-même, les gardes contre les commandes catastrophiques et la sécurité des branches protégées : +La sélection recommandée par l'assistant de configuration active actuellement les assainisseurs de secrets, les protections d'environnement, l'auto-protection, les gardes contre les commandes catastrophiques et la sécurité des branches protégées : ```text sanitize-jwt sanitize-api-keys sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars block-env-files block-secrets-write -block-self-pause block-failproofai-commands -block-sudo block-curl-pipe-sh -block-rm-rf block-push-master -block-force-push +block-failproofai-commands block-sudo +block-curl-pipe-sh block-rm-rf +block-push-master block-force-push ``` -La sélection recommandée est délibérément plus restreinte que **Tout activer**. Les politiques d'infrastructure et de workflow peuvent interrompre un travail légitime ; elles doivent être activées uniquement pour les dépôts et les machines qui en ont besoin. +`block-failproofai-commands` est **toujours actif**. Il figure ci-dessus pour +être exhaustif, mais il s'enregistre à chaque évaluation, qu'il apparaisse ou non +dans votre ensemble activé, et il ne peut pas être désactivé ni mis en pause — une +garde contre la désactivation de l'application par l'agent ne saurait être +désactivable par l'agent lui-même. + +La base recommandée est délibérément plus restreinte que **Tout**. Les politiques d'infrastructure et de workflow peuvent interrompre un travail valide et ne devraient être activées que pour les dépôts et les machines qui en ont besoin. ## Secrets et environnement | Politique | Déclencheur | Résultat | | --- | --- | --- | -| `sanitize-jwt` | `PostToolUse` | Masque les JWT dans la sortie des outils avant que le modèle ne les voie. | -| `sanitize-api-keys` | `PostToolUse` | Masque les clés OpenAI, Anthropic, GitHub, AWS, Stripe et Google courantes. | -| `sanitize-connection-strings` | `PostToolUse` | Masque les chaînes de connexion à des bases de données contenant des identifiants. | +| `sanitize-jwt` | `PostToolUse` | Masque les JWTs dans la sortie des outils avant que le modèle ne les voie. | +| `sanitize-api-keys` | `PostToolUse` | Masque les clés courantes OpenAI, Anthropic, GitHub, AWS, Stripe et Google. | +| `sanitize-connection-strings` | `PostToolUse` | Masque les chaînes de connexion aux bases de données contenant des identifiants. | | `sanitize-private-key-content` | `PostToolUse` | Masque les corps de clés privées PEM. | -| `sanitize-bearer-tokens` | `PostToolUse` | Masque les jetons bearer d'autorisation. | +| `sanitize-bearer-tokens` | `PostToolUse` | Masque les jetons d'autorisation bearer. | | `protect-env-vars` | `PreToolUse` sur les outils shell | Bloque les commandes qui exposent les variables d'environnement. | | `block-env-files` | `PreToolUse` | Bloque les lectures et écritures des fichiers `.env`. | -| `block-read-outside-cwd` | `PreToolUse` sur les outils read, glob, grep ou shell | Limite les lectures au répertoire de travail de la session. | +| `block-read-outside-cwd` | `PreToolUse` sur les outils de lecture, glob, grep ou shell | Restreint les lectures au répertoire de travail de la session. | | `block-secrets-write` | `PreToolUse` sur les outils d'écriture | Bloque les écritures vers les noms de fichiers courants de clés secrètes et d'identifiants. | ## Commandes dangereuses et infrastructure | Politique | Déclencheur | Résultat | | --- | --- | --- | -| `block-self-pause` | `PreToolUse`, `PermissionRequest` | Empêche un agent de suspendre sa propre application des règles. | -| `block-sudo` | `PreToolUse`, `PermissionRequest` | Bloque `sudo` sauf si un modèle d'autorisation correspond. | -| `block-curl-pipe-sh` | `PreToolUse` | Bloque les scripts téléchargés et directement transmis à un shell via un pipe. | -| `block-rm-rf` | `PreToolUse` | Bloque les patterns de suppression récursive catastrophiques. | -| `block-failproofai-commands` | `PreToolUse` | Empêche les agents de modifier ou de désinstaller Failproof AI. | +| `block-sudo` | `PreToolUse`, `PermissionRequest` | Bloque `sudo` sauf si un motif d'autorisation correspond. | +| `block-curl-pipe-sh` | `PreToolUse` | Bloque les scripts téléchargés redirigés directement vers un shell. | +| `block-rm-rf` | `PreToolUse` | Bloque les motifs de suppression récursive catastrophiques. | +| `block-failproofai-commands` | `PreToolUse`, `PermissionRequest` | **Toujours actif, ne peut pas être désactivé.** Bloque toute invocation de la CLI Failproof AI, toute mise en pause automatique et toute désinstallation via le gestionnaire de packages. | | `block-kubectl` | `PreToolUse` | Contrôle les commandes Kubernetes. | | `block-terraform` | `PreToolUse` | Contrôle les commandes Terraform et OpenTofu. | | `block-aws-cli` | `PreToolUse` | Contrôle les commandes AWS CLI. | | `block-gcloud` | `PreToolUse` | Contrôle les commandes Google Cloud CLI. | | `block-az-cli` | `PreToolUse` | Contrôle les commandes Azure CLI. | | `block-helm` | `PreToolUse` | Contrôle les commandes Helm. | -| `block-gh-pipeline` | `PreToolUse` | Contrôle les opérations GitHub CLI mutantes : workflow, run, merge, release, cache et secret. | +| `block-gh-pipeline` | `PreToolUse` | Contrôle les opérations mutantes de workflow, run, merge, release, cache et secret de la CLI GitHub. | -## Sécurité Git et bases de données +## Sécurité Git et base de données | Politique | Déclencheur | Résultat | | --- | --- | --- | -| `block-push-master` | `PreToolUse` | Bloque les push directs vers les branches protégées configurées. | -| `block-force-push` | `PreToolUse` | Bloque les force-push ; `--force-with-lease` reste autorisé par l'implémentation actuelle. | -| `block-work-on-main` | `PreToolUse` | Bloque les commits et merges sur les branches protégées. | +| `block-push-master` | `PreToolUse` | Bloque les pousses directes vers les branches protégées configurées. | +| `block-force-push` | `PreToolUse` | Bloque les pousses forcées ; `--force-with-lease` reste autorisé par l'implémentation actuelle. | +| `block-work-on-main` | `PreToolUse` | Bloque les commits et fusions sur les branches protégées. | | `warn-git-amend` | `PreToolUse` | Avertit avant de réécrire un commit avec `--amend`. | -| `warn-git-stash-drop` | `PreToolUse` | Avertit avant de supprimer ou vider définitivement des stashes. | -| `warn-all-files-staged` | `PreToolUse` | Avertit en cas d'ajout global via `git add -A`, `git add .` ou `git add --all`. | -| `warn-destructive-sql` | `PreToolUse` | Avertit en cas de `DROP`, `TRUNCATE` ou `DELETE` sans `WHERE` via des clients de base de données reconnus. | -| `warn-schema-alteration` | `PreToolUse` | Avertit lors d'opérations reconnues `ALTER TABLE` sur des colonnes ou des renommages. | +| `warn-git-stash-drop` | `PreToolUse` | Avertit avant de supprimer ou vider définitivement des remises. | +| `warn-all-files-staged` | `PreToolUse` | Avertit en cas d'indexation large avec `git add -A`, `git add .` ou `git add --all`. | +| `warn-destructive-sql` | `PreToolUse` | Avertit en cas de `DROP`, `TRUNCATE` et `DELETE` sans `WHERE` via les clients de base de données reconnus. | +| `warn-schema-alteration` | `PreToolUse` | Avertit lors d'opérations reconnues de `ALTER TABLE` sur des colonnes et de renommage. | ## Packages, comportement système et boucles d'agent | Politique | Déclencheur | Résultat | | --- | --- | --- | -| `warn-package-publish` | `PreToolUse` | Avertit avant de publier sur des registres de packages. | +| `warn-package-publish` | `PreToolUse` | Avertit avant la publication vers des registres de packages. | | `warn-global-package-install` | `PreToolUse` | Avertit avant l'installation globale d'un package. | -| `prefer-package-manager` | `PreToolUse` | Indique à l'agent d'utiliser un gestionnaire de packages autorisé. | +| `prefer-package-manager` | `PreToolUse` | Demande à l'agent d'utiliser un gestionnaire de packages autorisé. | | `warn-large-file-write` | `PreToolUse` sur les outils d'écriture | Avertit au-delà du seuil de taille de fichier configuré. | -| `warn-background-process` | `PreToolUse` | Avertit en cas de patterns de processus en arrière-plan détachés ou de longue durée. | +| `warn-background-process` | `PreToolUse` | Avertit en cas de motifs de processus détachés ou de longue durée en arrière-plan. | | `warn-repeated-tool-calls` | `PreToolUse` | Avertit après trois appels d'outil identiques ou plus. | ## Workflow de fin de tâche -Ces politiques nécessitent un harnais émettant un événement `Stop` compatible. +Ces politiques requièrent un harnais qui émet un événement `Stop` compatible. | Politique | Résultat | | --- | --- | -| `require-commit-before-stop` | Refuse la complétion tant que des modifications suivies ne sont pas commitées. | +| `require-commit-before-stop` | Refuse la complétion tant que du travail suivi reste non validé. | | `require-push-before-stop` | Refuse la complétion tant que des commits restent uniquement en local. | | `require-pr-before-stop` | Exige une pull request pour la branche courante. | -| `require-no-conflicts-before-stop` | Exige un merge propre par rapport à la branche de base configurée. | -| `require-ci-green-before-stop` | Exige que les vérifications CI du HEAD actuel se terminent avec succès. | +| `require-no-conflicts-before-stop` | Exige une fusion propre avec la branche de base configurée. | +| `require-ci-green-before-stop` | Exige que les vérifications CI du HEAD courant se terminent avec succès. | ## Référence des paramètres @@ -125,5 +129,5 @@ Configurez les paramètres dans l'objet `policyParams` du scope sélectionné. L ``` - Un modèle d'autorisation élargit ce qu'un agent peut faire. Testez la tokenisation exacte et les variantes de commandes sur le harnais cible avant de le déployer sur une flotte de machines. + Un motif d'autorisation élargit ce qu'un agent peut faire. Testez la tokenisation exacte et les variantes de commandes sur le harnais cible avant de le déployer sur un parc de machines. \ No newline at end of file diff --git a/docs/fr/policies/failure-behavior.mdx b/docs/fr/policies/failure-behavior.mdx index 621acd2d..3f81f042 100644 --- a/docs/fr/policies/failure-behavior.mdx +++ b/docs/fr/policies/failure-behavior.mdx @@ -1,19 +1,19 @@ --- title: "Comportement en cas d'échec" -description: "Comprenez ce qui se passe lorsque l'évaluation des politiques ou le daemon local est indisponible." +description: "Comprendre ce qui se passe lorsque l'évaluation des politiques ou le démon local est indisponible." icon: "shield-alert" --- -Failproof AI est conçu de sorte qu'un échec d'application soit visible plutôt que de permettre silencieusement des actions risquées. +Failproof AI est conçu de sorte qu'un échec d'application soit visible plutôt que de laisser silencieusement passer des actions risquées. -## Diagnostiquer un blocage en mode échec fermé +## Diagnostiquer un blocage en mode fermé sur échec - 1. Accédez à **Admin → enforcement** et ouvrez la machine. + 1. Allez dans **Admin → enforcement** et ouvrez la machine. 2. Vérifiez sa dernière connexion, le déploiement assigné et le déploiement rapporté. - 3. Accédez à **Observe → policy** et ouvrez la session de la décision refusée. - 4. Confirmez si la raison indique l'accessibilité du daemon, un écart de version ou la politique elle-même. + 3. Allez dans **Observe → policy** et ouvrez la session de la décision refusée. + 4. Confirmez si la raison indique une inaccessibilité du démon, un décalage de version ou la politique elle-même. @@ -23,21 +23,45 @@ Failproof AI est conçu de sorte qu'un échec d'application soit visible plutôt failproofai config ``` - Relancer `failproofai config` met à jour et redémarre le daemon après une mise à jour du package. + Relancer `failproofai config` met à jour et redémarre le démon après une mise à jour du package. -Sur une machine configurée pour utiliser `failproofaid`, le daemon est le seul évaluateur. S'il est inaccessible ou si sa version de protocole ne correspond pas à celle du CLI, l'évaluation des hooks échoue en mode fermé. L'action est refusée avec un message indiquant à l'opérateur de vérifier ou mettre à jour le daemon. +Sur une machine configurée pour utiliser `failproofaid`, le démon est le seul évaluateur. S'il est inaccessible ou si sa version de protocole ne correspond pas à celle du CLI, l'évaluation des hooks échoue en mode fermé. L'action est refusée avec une raison qui invite l'opérateur à vérifier ou mettre à jour le démon. -Avant la configuration du daemon, les hooks évaluent les politiques en cours de processus. Une fois la configuration du daemon enregistrée, Failproof AI ne bascule pas silencieusement vers un second évaluateur en cas d'échec du daemon. +Avant la configuration du démon, les hooks évaluent les politiques en cours de processus. Une fois la configuration du démon enregistrée, Failproof AI ne bascule pas silencieusement vers un second évaluateur en cas d'échec du démon. -## Répondre à une décision en mode échec fermé +## Réagir à une décision de blocage en mode fermé sur échec 1. Exécutez `failproofai config --status`. 2. Si les versions diffèrent, relancez `failproofai config` après avoir mis à jour le package. -3. Si le daemon est inaccessible, inspectez son état de service et ses journaux locaux. -4. Ne reprenez le travail de l'agent qu'après avoir confirmé qu'un chemin d'évaluation des politiques connu est opérationnel. +3. Si le démon est inaccessible, inspectez l'état de son service et les journaux locaux. +4. Ne reprenez le travail de l'agent qu'une fois qu'un chemin d'évaluation de politique connu est sain. - Ne réessayez pas l'action bloquée de manière répétée. Une réponse en mode échec fermé signifie que le système n'a pas pu établir que l'action était sûre. - \ No newline at end of file + Ne réessayez pas répétitivement l'action bloquée. Une réponse en mode fermé sur échec signifie que le système n'a pas pu établir que l'action était sûre. + + +## Un pack ne se charge pas + +Une machine à qui l'on a demandé d'appliquer un pack, et qui ne peut pas l'exécuter, refuse plutôt que de continuer silencieusement. Le déclencheur est une **attente enregistrée**, jamais une attente vide : une machine sans pack installé reste silencieuse, tandis qu'un pack déclaré qui ne peut pas se résoudre — ou qui enregistre moins que ce que son manifeste déclare — provoque un refus. + +Le refus est **ciblé**, contrairement à un démon inaccessible. Un démon inaccessible signifie qu'aucune évaluation n'a eu lieu, donc rien ne peut être considéré comme sûr. Un pack qui ne se charge pas dispose d'un ensemble dénombrable de gardes manquantes, car chaque politique déclarée porte son propre `match` — il ne refuse donc que les événements et outils couverts par ces politiques, et tout le reste continue. + +Il ne se déclenche pas pour : + +- un pack `observe`, qui évalue et ignore par construction +- des politiques que vous n'avez jamais adoptées, ou explicitement désactivées +- un pack que le chargeur n'a jamais reçu, où « aucune inscription » ne peut être distinguée d'un saut délibéré +- une pause de session active +- un délai d'expiration du chargement, qui est transitoire — un instant de disque lent ne doit pas provoquer un refus jusqu'à ce qu'un humain intervienne + +`UserPromptSubmit` **instruit** plutôt que de refuser, quelle que soit la politique manquante déclarée. Un refus général l'emporterait avec lui et vous bloquerait hors de l'agent qui pourrait résoudre le problème. + +### Que faire + +```bash +failproofai pack list +``` + +Cette commande identifie tout pack installé qui ne se charge pas, indique pourquoi, et se termine avec un code non-zéro. Ensuite, soit réinstallez-le (`failproofai pack add `), soit supprimez-le (`failproofai pack remove `) — le supprimer retire l'attente, et le refus cesse avec elle. \ No newline at end of file diff --git a/docs/fr/policies/packs.mdx b/docs/fr/policies/packs.mdx new file mode 100644 index 00000000..9b9497bc --- /dev/null +++ b/docs/fr/policies/packs.mdx @@ -0,0 +1,110 @@ +--- +title: "Packs de politiques" +description: "Installez un ensemble de politiques publiées sous forme de release GitHub et gérez ce qu'elles appliquent." +icon: "package" +--- + +Un pack est un ensemble de politiques publiées sous forme de release GitHub. Une seule commande suffit à l'installer, les checksums de la release sont vérifiés avant toute exécution, et le digest est enregistré pour que le pack ne puisse pas être modifié sur votre machine par la suite. + +## Installer les politiques Failproof AI + +```bash +failproofai pack add core +``` + +Cette commande installe l'ensemble que nous publions, depuis la copie incluse dans le package — aucune connexion réseau n'est nécessaire et elle ne peut pas échouer derrière un proxy. Vous pouvez n'en prendre qu'une partie : + +```bash +failproofai pack add core --policy block-rm-rf # une seule, ou quelques-unes séparées par des virgules +failproofai pack add core --category dangerous-commands # toute une catégorie +failproofai pack add core --all # tout son contenu +``` + +`failproofai pack list` liste toutes les catégories proposées par le pack. + +## Consulter le contenu d'un pack avant de l'installer + +```bash +failproofai pack list acme/support-agent +``` + +Liste toutes les politiques du pack, regroupées par catégorie, en indiquant celles que l'auteur active par défaut et celles qui sont optionnelles. Seul le **manifeste** est lu — l'artefact principal n'est jamais téléchargé ni importé, ce qui fait que consulter le pack d'un inconnu n'exécute aucun code étranger. Le manifeste est tout de même vérifié par rapport au `SHA256SUMS` de la release, de sorte que ce que vous lisez correspond exactement à ce qui serait installé. + +`failproofai pack list` sans argument liste les packs déjà installés sur cette machine. + +## Installer le pack de quelqu'un d'autre + +```bash +failproofai pack add acme/support-agent +``` + +Chacune de ces formes est acceptée — collez celle que vous avez sous la main : + +| Source | Résultat | +| --- | --- | +| `acme/support-agent` | Dernière release, **épinglée** au tag exact résolu | +| `acme/support-agent@v2.1.0` | Cette release précise | +| `github:acme/support-agent@v2.1.0` | La même, écrite explicitement | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | La même, copiée depuis un navigateur | + +Ne pas spécifier de tag installe la dernière release **et l'épingle**, puis vous indique le tag choisi. Ce qui est enregistré désigne toujours exactement une release, de sorte qu'une réinstallation ne peut pas dériver. + +## Ne prendre qu'une partie d'un pack + +Par défaut, vous obtenez les **propres** valeurs par défaut du pack — les politiques que son auteur a jugées sûres à activer sans surveillance — et non son contenu intégral. + +```bash +failproofai pack add acme/support-agent --category billing,git +failproofai pack add acme/support-agent --policy block-refunds +failproofai pack add acme/support-agent --all +``` + +`--category` et `--policy` se combinent en union (`--only` est accepté comme synonyme de `--policy`). Réinstaller à une version plus récente conserve vos sélections plutôt que de tout réactiver. + +## Gérer ce qui est activé + +```bash +failproofai policies # toutes les sources en une seule liste, packs inclus +failproofai pack list # les packs uniquement, regroupés par catégorie +failproofai policies --uninstall block-refunds # désactiver une politique de pack +failproofai policies --install block-refunds # la réactiver +failproofai pack remove acme/support-agent +``` + +Un nom seul désigne la politique **intégrée** si elle existe sous ce nom. Désignez explicitement la copie d'un pack lorsque nécessaire : + +```bash +failproofai policies --uninstall acme/support-agent:block-refunds +``` + + +Si un pack fournit une politique dont le nom correspond à une **politique intégrée activée**, c'est la version intégrée qui s'exécute et la copie du pack est ignorée — la même protection serait sinon évaluée deux fois. Désactivez la politique intégrée pour utiliser la copie du pack à la place. + + +## Origine des politiques Failproof AI + +`core` lit la copie fournie dans le package npm. Ce même ensemble est publié sous forme de release GitHub, que vous installez si vous souhaitez une version spécifique : + +```bash +failproofai pack add core # depuis ce package, sans réseau +failproofai pack add FailproofAI/policies # le même ensemble, depuis sa release GitHub +``` + +## Ce que l'intégrité garantit et ce qu'elle ne garantit pas + +`SHA256SUMS` est livré dans la même release que l'artefact, ce qui signifie que ce **n'est pas** une signature et ne prouve rien sur l'identité de l'éditeur. Ce que cela prouve, c'est que les octets sont bien ceux publiés dans cette release — et comme le digest est enregistré lors de l'ajout du pack et re-vérifié avant chaque import, un pack ne peut pas être modifié sur votre machine par la suite. Un dépôt qui retague ou remplace un artefact cesse de se charger au lieu d'exécuter silencieusement autre chose. + +Au moment de l'installation, le pack est également **importé une fois** et vérifié par rapport à son propre manifeste. Un pack dont l'artefact ne se parse pas, ou qui enregistre autre chose que ce qu'il déclare, est refusé avant toute activation — plutôt que de s'installer proprement et d'échouer lors de votre prochain appel d'outil. + +## Quand un pack ne se charge pas + +Un pack que cette machine a reçu l'ordre d'appliquer et qu'elle ne peut pas exécuter **refuse** les événements couverts par ses politiques manquantes, plutôt que de les autoriser silencieusement. Voir [Comportement en cas d'échec](/fr/policies/failure-behavior). `failproofai pack list` indique tout pack dans cet état et retourne un code de sortie non nul. + +## Hors ligne et miroirs + +| Variable | Effet | +| --- | --- | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Refuse tout téléchargement ; les packs déjà installés continuent d'être appliqués | +| `FAILPROOFAI_PACK_BASE_URL` | Redirige le téléchargement des packs vers un miroir plutôt que `github.com` | + +Pour publier votre propre pack, consultez [Publier un pack](/fr/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/fr/policies/publish-a-pack.mdx b/docs/fr/policies/publish-a-pack.mdx new file mode 100644 index 00000000..46164851 --- /dev/null +++ b/docs/fr/policies/publish-a-pack.mdx @@ -0,0 +1,91 @@ +--- +title: "Publier un pack" +description: "Distribuez vos propres politiques sous forme de release GitHub que tout le monde peut installer." +icon: "upload" +--- + +Un pack est composé de trois fichiers attachés à une release GitHub. `failproofai pack build` génère les trois à partir d'un fichier de politiques que vous possédez déjà. + +## 1. Écrire les politiques + +Un seul fichier, utilisant la même API que n'importe quelle politique personnalisée. Deux champs supplémentaires sont importants pour un pack : + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-refunds", + description: "Refunds above the approved limit need a human", + category: "Billing", // groups it, and is what --category selects on + defaultEnabled: true, // switched on by a plain `pack add` + match: { events: ["PreToolUse"], tools: ["Bash"] }, + fn: async (ctx) => + String(ctx.toolInput?.command ?? "").includes("refund") + ? deny("Refunds need a human. Ask before running this.") + : allow(), +}); +``` + +`defaultEnabled` vaut **false** par défaut si vous l'omettez. Un simple `failproofai pack add` n'active que ce que vous avez marqué — activer en bloc toutes les politiques d'un inconnu sans supervision n'est pas une décision que l'installeur devrait prendre à la place de son utilisateur. + + +L'entrée doit être **un fichier unique et autonome**. Seule l'entrée est épinglée par son condensat, donc un pack qui importe des fichiers locaux ne pourrait pas honnêtement prétendre que le condensat couvre ce qui s'exécute. Bundlez d'abord (`esbuild`, `bun build`, `rollup`) et construisez le pack à partir du bundle — `pack build` refuse une importation locale plutôt que de livrer une promesse qu'il ne peut pas tenir. + + +## 2. Construire les assets de la release + +```bash +failproofai pack build ./policies.mjs \ + --id acme/support-agent \ + --version 1.0.0 \ + --out ./dist-pack +``` + +Cette commande génère trois fichiers et valide chaque politique avec **les propres règles du chargeur** — ainsi, un pack qui ne pourrait jamais s'installer échoue ici, là où vous pouvez corriger le problème : + +| Fichier | Description | +| --- | --- | +| `failproofai-pack.json` | Le manifeste : id, version, effet, et une entrée par politique | +| `failproofai-pack.mjs` | Votre entrée, verbatim | +| `SHA256SUMS` | ` ` pour les deux autres fichiers | + +Refusés à la construction : un id qui n'est pas `publisher/name`, un nom de politique contenant `/`, une politique déclarant `alwaysOn`, une `description`, une `category` ou un `match` manquants, une entrée qui n'enregistre rien, et une entrée qui importe des fichiers locaux. + +## 3. Attacher les fichiers à une release + +Taguez la release avec la même version que celle utilisée lors de la construction, et attachez les trois fichiers comme assets de la release : + +```bash +gh release create 1.0.0 \ + ./dist-pack/failproofai-pack.json \ + ./dist-pack/failproofai-pack.mjs \ + ./dist-pack/SHA256SUMS +``` + +N'importe qui peut désormais l'installer : + +```bash +failproofai pack add acme/support-agent +``` + +Les noms des assets sont fixes — c'est à partir d'eux que le CLI du consommateur construit ses URLs, sans appel API ni mécanisme de découverte. + +## Publier une nouvelle version + +Construisez avec le nouveau `--version`, taguez une nouvelle release, attachez à nouveau les trois assets. Les consommateurs exécutent le même `pack add` et conservent le sous-ensemble qu'ils avaient choisi ; une politique qu'ils ont désactivée reste désactivée après la mise à jour. + +Changer le **nom** d'une politique est un changement cassant : une machine qui l'avait désactivée désactive un nom qui n'existe plus, et le nouveau nom arrive avec ce que `defaultEnabled` indique. + +## Ce que vos utilisateurs vous font confiance + +`SHA256SUMS` se trouve dans la même release que l'artefact, ce qui prouve que les octets sont bien ceux que vous avez publiés — mais pas qui vous êtes. Quiconque peut écrire dans le dépôt peut écrire les deux fichiers. La protection de vos utilisateurs réside dans le fait que le condensat est épinglé au moment de l'installation, ce qui empêche ce que vous avez publié de changer à leur insu par la suite. + +Publiez depuis un dépôt dont vous contrôlez les accès en écriture, et traitez une release de pack comme la publication d'un package. + +## Observer avant d'appliquer + +Un manifeste peut déclarer `"effect": "observe"`. Ces politiques s'exécutent et leurs verdicts sont **enregistrés puis ignorés** — rien n'est bloqué. C'est la façon de mesurer une nouvelle règle face au trafic réel avant qu'elle ne puisse interrompre le travail de quiconque. + +```json +{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +``` \ No newline at end of file diff --git a/docs/fr/reference/failproof-cli.mdx b/docs/fr/reference/failproof-cli.mdx index c75970c3..67481731 100644 --- a/docs/fr/reference/failproof-cli.mdx +++ b/docs/fr/reference/failproof-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof AI CLI" -description: "Installer les hooks, gérer les politiques locales, connecter le Cloud et opérer le daemon local." +description: "Installez les hooks, gérez les politiques locales, connectez le Cloud et pilotez le démon local." icon: "terminal" --- -Installez le CLI local avec `npm install -g failproofai`. Exécutez-le sans arguments pour ouvrir le tableau de bord des politiques locales. +Installez le CLI local avec `npm install -g failproofai`. Lancez-le sans argument pour ouvrir le tableau de bord des politiques locales. -Le package nécessite Node.js 20.9 ou une version plus récente. Bun 1.3 ou une version plus récente est pris en charge pour le développement et les installations depuis les sources. `failproofai configure` et `failproofai setup` sont des alias de `failproofai config` ; `failproofai p` est un alias de `failproofai policies`. +Le package requiert Node.js 20.9 ou une version plus récente. Bun 1.3 ou une version plus récente est pris en charge pour le développement et les installations depuis les sources. `failproofai configure` et `failproofai setup` sont des alias de `failproofai config` ; `failproofai p` est un alias de `failproofai policies`. ## Configurer une machine @@ -20,62 +20,67 @@ failproofai policies --install failproofai config --status ``` -Exécutez `failproofai` sans arguments pour ouvrir le tableau de bord des politiques locales. +Lancez `failproofai` sans argument pour ouvrir le tableau de bord des politiques locales. | Commande | Résultat | | --- | --- | -| `failproofai config` | Lancer la configuration interactive de la machine | -| `failproofai config --connect --token ` | Connecter l'ingestion Cloud et la distribution des politiques | -| `failproofai config --status` | Afficher l'état de connexion, du daemon, de la distribution et de la pause | -| `failproofai policies` | Lister les politiques intégrées et personnalisées | -| `failproofai policies --install` | Installer les hooks et activer les politiques | -| `failproofai policy add ` | Activer une politique intégrée | -| `failproofai policy remove ` | Désactiver une politique intégrée | -| `failproofai policies --uninstall` | Désactiver les politiques ou supprimer les hooks du harness | -| `failproofai audit` | Analyser l'historique local de l'agent et ouvrir la vue d'audit locale | -| `failproofai audit --schedule [days] --email
` | Planifier des analyses locales récurrentes et envoyer leurs résultats par e-mail | -| `failproofai audit --status` | Afficher l'adresse du rapport, l'intervalle et la prochaine analyse planifiée | -| `failproofai audit --no-schedule` | Arrêter les analyses récurrentes sans supprimer l'historique d'audit | -| `failproofai harness list` | Lister les chemins de capture supplémentaires | -| `failproofai flush --wait` | Livrer le spool d'événements actuel | -| `failproofai backfill --since 30d` | Relire l'historique précédemment traité | -| `failproofai config --pause [duration]` | Mettre en pause une session locale pendant 30 minutes par défaut, jusqu'à 8 heures | -| `failproofai config --resume` | Reprendre une session locale en pause ; ajouter `--all` pour lever toutes les pauses | -| `failproofai update` | Terminer les migrations du package et mettre à jour le daemon | -| `failproofai migrate --dry-run` | Prévisualiser ou exécuter les migrations de disposition du répertoire personnel en attente | -| `failproofai uninstall` | Supprimer les hooks et le daemon avant de désinstaller le package | -| `failproofai --version` | Afficher la version du package installé | -| `failproofai --help` | Afficher les commandes et l'utilisation globale | +| `failproofai config` | Lance la configuration interactive de la machine | +| `failproofai config --connect --token ` | Connecte l'ingestion Cloud et la distribution des politiques | +| `failproofai config --status` | Affiche la connexion, le démon, la distribution et l'état de pause | +| `failproofai policies` | Liste les politiques intégrées, personnalisées, de convention, de pack et gérées par le Cloud | +| `failproofai policies --install` | Installe les hooks et active les politiques | +| `failproofai policy add ` | Active une politique — intégrée, ou `:` depuis un pack installé | +| `failproofai policy remove ` | Désactive une politique, même convention de nommage | +| `failproofai policies --uninstall` | Désactive les politiques ou supprime les hooks du harnais | +| `failproofai pack list` | Liste les packs de politiques installés et chaque politique qu'ils contiennent | +| `failproofai pack add ` | Installe un pack de politiques depuis une release GitHub ; sans tag, prend la dernière version et la fixe | +| `failproofai pack add --bundled` | Installe les politiques intégrées sous forme de pack, depuis ce package, sans réseau | +| `failproofai pack build ` | Construit les trois fichiers de release pour un pack personnalisé | +| `failproofai pack remove ` | Désactive un pack installé | +| `failproofai audit` | Analyse l'historique local de l'agent et ouvre la vue d'audit locale | +| `failproofai audit --schedule [days] --email
` | Planifie des analyses locales récurrentes et envoie leurs résultats par e-mail | +| `failproofai audit --status` | Affiche l'adresse du rapport, l'intervalle et la prochaine analyse planifiée | +| `failproofai audit --no-schedule` | Arrête les analyses récurrentes sans supprimer l'historique d'audit | +| `failproofai harness list` | Liste les chemins de capture supplémentaires | +| `failproofai flush --wait` | Livre le spool d'événements actuel | +| `failproofai backfill --since 30d` | Relit l'historique précédemment traité | +| `failproofai config --pause [duration]` | Met en pause une session locale pendant 30 minutes par défaut, jusqu'à 8 heures | +| `failproofai config --resume` | Reprend une session locale en pause ; ajoutez `--all` pour lever toutes les pauses | +| `failproofai update` | Finalise les migrations du package et met à jour le démon | +| `failproofai migrate --dry-run` | Prévisualise ou exécute les migrations de disposition du répertoire personnel en attente | +| `failproofai uninstall` | Supprime les hooks et le démon avant de désinstaller le package | +| `failproofai --version` | Affiche la version du package installé | +| `failproofai --help` | Affiche les commandes et l'utilisation globale | ## Options de configuration | Option | Utilisation | | --- | --- | -| `--connect --token ` | Se connecter de manière non interactive | -| `--machine-id ` | Définir l'identifiant stable de la machine | -| `--machine-label ` | Définir ou modifier le libellé du tableau de bord | -| `--no-transcripts` | Envoyer les décisions sans le contenu des transcriptions | -| `--disconnect` | Arrêter les récupérations de politiques Cloud et la livraison d'événements | -| `--status` | Afficher l'état actuel de la machine | -| `--pause [duration]` | Mettre en pause la session la plus récente dans le répertoire courant ; accepte des secondes, minutes ou heures, avec une valeur par défaut de 30 minutes | -| `--resume` | Terminer une pause correspondante avant son expiration | -| `--session ` | Cibler une session explicite pour la mise en pause ou la reprise | -| `--all` | Avec `--resume`, terminer toutes les pauses actives | +| `--connect --token ` | Connexion non interactive | +| `--machine-id ` | Définit l'identifiant stable de la machine | +| `--machine-label ` | Définit ou modifie le libellé du tableau de bord | +| `--no-transcripts` | Envoie les décisions sans le contenu des transcripts | +| `--disconnect` | Arrête les téléchargements de politiques Cloud et la distribution d'événements | +| `--status` | Affiche l'état actuel de la machine | +| `--pause [duration]` | Met en pause la session la plus récente dans le répertoire courant ; accepte des secondes, minutes ou heures, avec une valeur par défaut de 30 minutes | +| `--resume` | Met fin à une pause correspondante avant son expiration | +| `--session ` | Cible une session explicite pour la pause ou la reprise | +| `--all` | Avec `--resume`, met fin à toutes les pauses actives | -Les pauses locales suspendent les politiques intégrées, personnalisées et de convention pour une session. Elles expirent toujours et ne désactivent pas les politiques gérées par le Cloud. `block-self-pause` empêche un agent instrumenté d'utiliser cette échappatoire lui-même. +Les pauses locales suspendent les politiques intégrées, personnalisées, de convention et de pack pour une session. Elles expirent toujours et ne désactivent pas les politiques gérées par le Cloud. `block-failproofai-commands` — qui est toujours actif et ne peut lui-même être ni désactivé ni mis en pause — empêche un agent instrumenté d'utiliser cette échappatoire. -## Options de politiques +## Options des politiques | Option | Utilisation | | --- | --- | -| `--install`, `-i` | Activer les politiques et installer les hooks du harness | -| `--uninstall`, `-u` | Désactiver les politiques ou supprimer les hooks | -| `--cli ` | Cibler un ou plusieurs harnesses pris en charge | -| `--scope user\|project\|local\|all` | Choisir la portée de configuration ; `all` est réservé à la désinstallation | -| `--beta` | Inclure les politiques bêta | -| `--custom`, `-c ` | Valider et charger un fichier de politique personnalisé ; répétable | +| `--install`, `-i` | Active les politiques et installe les hooks du harnais | +| `--uninstall`, `-u` | Désactive les politiques ou supprime les hooks | +| `--cli ` | Cible un ou plusieurs harnais pris en charge | +| `--scope user\|project\|local\|all` | Choisit la portée de la configuration ; `all` est réservé à la désinstallation | +| `--beta` | Inclut les politiques en version bêta | +| `--custom`, `-c ` | Valide et charge un fichier de politique personnalisé ; répétable | -## Options de livraison et de maintenance +## Options de distribution et de maintenance | Commande | Options | | --- | --- | @@ -85,9 +90,9 @@ Les pauses locales suspendent les politiques intégrées, personnalisées et de | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` doit être exécuté après `npm install -g failproofai@latest` ; il effectue les migrations de disposition du répertoire personnel, installe le binaire daemon correspondant et redémarre le service. `--no-daemon` effectue uniquement la migration de disposition. +`failproofai update` doit être exécuté après `npm install -g failproofai@latest` ; il effectue les migrations de disposition du répertoire personnel, installe le binaire du démon correspondant et redémarre le service. `--no-daemon` effectue uniquement la migration de disposition. -## Chemins du harness +## Chemins du harnais ```text failproofai harness list [harness] @@ -95,11 +100,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -Les noms de harness pris en charge sont `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` et `goose`. +Les noms de harnais pris en charge sont `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` et `goose`. -Les libellés permettent de distinguer les identifiants d'agents dérivés lorsque deux racines contiennent des copies du même projet. Les racines qui se chevauchent et les libellés en double sont rejetés pour éviter les collectes dupliquées ou la corruption du curseur. La configuration des chemins supplémentaires se recharge sans redémarrage du daemon. +Les libellés permettent de distinguer les identifiants d'agents dérivés lorsque deux racines contiennent des copies du même projet. Les racines qui se chevauchent et les libellés en double sont rejetés pour éviter les collectes en double ou la corruption du curseur. La configuration des chemins supplémentaires se recharge sans redémarrage du démon. -Les environnements conteneurisés peuvent remplacer les chemins supplémentaires configurés par fichier par une variable séparée par des virgules nommée `FAILPROOFAI__EXTRA_PATHS`, par exemple : +Les environnements conteneurisés peuvent remplacer les chemins supplémentaires configurés par fichier avec une variable séparée par des virgules nommée `FAILPROOFAI__EXTRA_PATHS`, par exemple : ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -107,26 +112,28 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## Variables d'environnement -Utilisez les fichiers de configuration pour le comportement persistant de la machine. Les variables d'environnement sont particulièrement utiles pour les conteneurs, les tests et les processus uniques. +Utilisez des fichiers de configuration pour le comportement persistant de la machine. Les variables d'environnement sont plus utiles pour les conteneurs, les tests et un seul processus. | Variable | Utilisation | | --- | --- | -| `FAILPROOFAI_HOME` | Déplacer l'ensemble de la disposition `~/.failproofai` | -| `FAILPROOFAI_LOG_LEVEL` | Définir le niveau de verbosité des journaux locaux | -| `FAILPROOFAI_HOOK_LOG_FILE` | Écrire les diagnostics des hooks dans un fichier sélectionné | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Désactiver la télémétrie anonyme pour ce processus | -| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignorer la configuration interactive au premier lancement | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Ignorer l'audit local après la configuration | -| `FAILPROOFAI_LLM_BASE_URL` | Remplacer le point de terminaison compatible OpenAI utilisé par les politiques LLM | -| `FAILPROOFAI_LLM_API_KEY` | Fournir la clé API utilisée par les politiques LLM | -| `FAILPROOFAI_LLM_MODEL` | Sélectionner le modèle utilisé par les politiques LLM | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limiter le temps de chargement des modules de politiques personnalisés | -| `FAILPROOFAI__EXTRA_PATHS` | Remplacer les chemins de capture supplémentaires configurés pour un harness | -| `NO_COLOR` | Désactiver la sortie terminal colorée | - -Les variables de répertoire personnel propres à chaque agent, telles que `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` et `OPENCLAW_HOME`, remplacent l'emplacement où Failproof AI découvre les sessions locales pour ce harness. - -## Mettre en pause ou supprimer une machine en toute sécurité +| `FAILPROOFAI_HOME` | Déplace la disposition complète de `~/.failproofai` | +| `FAILPROOFAI_LOG_LEVEL` | Définit le niveau de verbosité des journaux locaux | +| `FAILPROOFAI_HOOK_LOG_FILE` | Écrit les diagnostics des hooks dans un fichier sélectionné | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Désactive la télémétrie anonyme pour ce processus | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignore la configuration interactive au premier lancement | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Ignore l'audit local après la configuration | +| `FAILPROOFAI_LLM_BASE_URL` | Remplace le point de terminaison compatible OpenAI utilisé par les politiques LLM | +| `FAILPROOFAI_LLM_API_KEY` | Fournit la clé API utilisée par les politiques LLM | +| `FAILPROOFAI_LLM_MODEL` | Sélectionne le modèle utilisé par les politiques LLM | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limite le temps de chargement des modules de politiques personnalisées | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Refuse de télécharger les packs et les binaires du démon ; ce qui est installé continue d'être appliqué | +| `FAILPROOFAI_PACK_BASE_URL` | Récupère les packs depuis un miroir au lieu de `github.com` | +| `FAILPROOFAI__EXTRA_PATHS` | Remplace les chemins de capture supplémentaires configurés pour un harnais | +| `NO_COLOR` | Désactive la colorisation de la sortie terminal | + +Les variables de répertoire personnel spécifiques aux agents, telles que `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` et `OPENCLAW_HOME`, remplacent l'emplacement où Failproof AI découvre les sessions locales pour ce harnais. + +## Mettre en pause ou retirer une machine en toute sécurité ```bash failproofai config --pause @@ -134,9 +141,9 @@ failproofai config --status failproofai config --resume ``` -La mise en pause d'une session locale ne désactive pas les politiques gérées par le Cloud. Restaurez les déploiements Cloud via le workflow d'application Cloud lorsque le déploiement lui-même est à l'origine du problème. +La mise en pause d'une session locale ne désactive pas les politiques gérées par le Cloud. Restaurez les déploiements Cloud via le workflow d'application Cloud lorsque le déploiement lui-même pose problème. -Avant de supprimer le package npm, supprimez les hooks installés et le daemon : +Avant de supprimer le package npm, supprimez les hooks installés et le démon : ```bash failproofai uninstall --dry-run @@ -147,5 +154,5 @@ npm rm -g failproofai Exécutez `failproofai --help` pour obtenir des détails spécifiques à la version. - Exécutez `failproofai uninstall` avant `npm rm -g failproofai` ; npm ne supprime pas les hooks d'agent installés ni le service daemon. + Exécutez `failproofai uninstall` avant `npm rm -g failproofai` ; npm ne supprime pas les hooks d'agent installés ni le service du démon. \ No newline at end of file diff --git a/docs/fr/start/quickstart.mdx b/docs/fr/start/quickstart.mdx index b3ea096f..c2b6240c 100644 --- a/docs/fr/start/quickstart.mdx +++ b/docs/fr/start/quickstart.mdx @@ -1,17 +1,17 @@ --- title: "Démarrage rapide" -description: "Capturez une session d'agent, identifiez un échec et commencez à le prévenir." +description: "Capturez une session d'agent, identifiez une défaillance et commencez à la prévenir." icon: "zap" --- -Ce guide de démarrage rapide vous permet de configurer une machine pour qu'elle transmette des sessions, d'effectuer un audit et de déployer une politique. Utilisez la compétence pour configurer Failproof AI, ou suivez les étapes manuelles. +Ce guide de démarrage rapide vous permet de configurer une machine pour qu'elle rapporte des sessions, d'exécuter un audit et de déployer une politique. Utilisez le skill pour configurer Failproof AI, ou suivez les étapes manuelles. -**Quelle est votre situation ?** Si votre agent s'exécute dans l'un des 12 [harnais](/fr/reference/harnesses) pris en charge — une CLI de développement, ou une passerelle comme Hermes ou OpenClaw — suivez les étapes ci-dessous ; vous avez besoin de Node.js 20.9 ou version ultérieure. Si votre agent ne possède pas de harnais, instrumentez-le avec le [SDK Python](/fr/reference/custom-agents) pour le traçage et les audits, puis rejoignez la section [Exécutez votre premier contrôle d'échec](/fr/start/first-audit) ; l'application des politiques sur cette voie nécessite un hook dans votre environnement d'exécution. +**Quelle est votre situation ?** Si votre agent s'exécute dans l'un des 12 [harnais](/fr/reference/harnesses) pris en charge — un CLI de codage, ou une passerelle comme Hermes ou OpenClaw — suivez les étapes ci-dessous ; vous aurez besoin de Node.js 20.9 ou version ultérieure. Si votre agent n'a pas de harnais, instrumentez-le avec le [SDK Python](/fr/reference/custom-agents) pour le traçage et les audits, puis rejoignez la section [Exécuter votre premier contrôle de défaillance](/fr/start/first-audit) ; l'application des politiques sur ce chemin nécessite un hook dans votre runtime. - + - + ```bash npx skills add FailproofAI/skills ``` @@ -21,7 +21,7 @@ Ce guide de démarrage rapide vous permet de configurer une machine pour qu'elle Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Votre agent inspecte le projet, choisit l'intégration appropriée, effectue la configuration et vérifie son bon fonctionnement. Consultez le [dépôt de compétences FailproofAI](https://github.com/FailproofAI/skills) pour les compétences individuelles et les options d'installation avancées. + Votre agent inspecte le projet, choisit l'intégration pertinente, effectue la configuration et la vérifie. Consultez le [dépôt de skills FailproofAI](https://github.com/FailproofAI/skills) pour les skills individuels et les options d'installation avancées. @@ -29,7 +29,7 @@ Ce guide de démarrage rapide vous permet de configurer une machine pour qu'elle ## Avant de commencer 1. Ouvrez le [tableau de bord Failproof AI](https://app.befailproof.ai) et créez un compte ou connectez-vous avec votre adresse e-mail professionnelle. -2. Accédez à **Administration → Keys** et créez une clé avec `events:add` et `policies:pull`. +2. Accédez à **Administration → Clés** et créez une clé avec `events:add` et `policies:pull`. 3. Copiez le secret à usage unique et stockez-le sur la machine cible : ```bash @@ -45,7 +45,7 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - Les transcriptions de sessions sont envoyées par défaut. Ajoutez `--no-transcripts` pour transmettre l'activité des hooks et les décisions de politique sans le contenu des transcriptions. + Les transcriptions de sessions sont envoyées par défaut. Ajoutez `--no-transcripts` pour rapporter l'activité des hooks et les décisions de politique sans le contenu des transcriptions. Si cette machine possède déjà un historique d'agent, prévisualisez et importez les sept derniers jours, puis attendez la fin de la livraison. Ignorez cette étape sur une nouvelle machine. @@ -57,28 +57,28 @@ export FAILPROOFAI_KEY="" Ouvrez **Sessions** dans Failproof AI et sélectionnez une session importée. - - Cette étape attache Failproof AI à votre harnais et installe les 40 politiques intégrées. Utilisez-les pour observer les décisions de politique locales et tester l'application avant que Failproof AI n'audite vos sessions et n'écrive des politiques pour vos agents. + + Cette étape connecte Failproof AI à votre harnais et installe les 39 politiques intégrées. Utilisez-les pour visualiser les décisions de politique locales et tester l'application avant que Failproof AI n'audite vos sessions et n'écrive des politiques pour vos agents. - Laissez l'installateur détecter votre harnais automatiquement, ou nommez-en un explicitement. Chacun des 12 est une valeur `--cli` valide — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + Laissez l'installateur détecter votre harnais, ou nommez-en un explicitement. Chacun des 12 est une valeur `--cli` valide — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash - failproofai policies --install --cli claude --scope user # une CLI de développement + failproofai policies --install --cli claude --scope user # un CLI de codage failproofai policies --install --cli hermes --scope user # une passerelle Slack/Telegram ``` - Le blocage d'un appel d'outil avant son exécution est vérifié sur les 12 harnais. Les contrôles en fin de tour sont vérifiés sur 8 — consultez la [capacité d'application](/fr/reference/harnesses#enforcement-capability) pour la matrice par harnais. + Le blocage d'un appel d'outil avant son exécution est vérifié sur les 12. Les verrous de fin de tour sont vérifiés sur 8 — consultez les [capacités d'application](/fr/reference/harnesses#enforcement-capability) pour la matrice par harnais. - Suivez [Exécutez votre premier contrôle d'échec](/fr/start/first-audit). Utilisez un objectif concret tel que « trouver les sessions où l'agent a réessayé un outil défaillant sans modifier son approche ». + Suivez [Exécuter votre premier contrôle de défaillance](/fr/start/first-audit). Utilisez un objectif concret, par exemple « trouver les sessions où l'agent a réessayé un outil défaillant sans modifier son approche ». - - Suivez [Prévenez votre premier échec avec une politique](/fr/start/first-policy). Commencez en mode observation, inspectez les correspondances, puis appliquez la version révisée. + + Suivez [Prévenir votre première défaillance avec une politique](/fr/start/first-policy). Commencez en mode observation, inspectez les correspondances, puis appliquez la version révisée. - Exécutez `failproofai config --status`. Une configuration saine indique la connexion au cloud, l'état du démon et si l'application des politiques est en pause. + Exécutez `failproofai config --status`. Une configuration saine signale la connexion au cloud, l'état du daemon et si l'application des politiques est en pause. \ No newline at end of file diff --git a/docs/he/policies/builtin-catalog.mdx b/docs/he/policies/builtin-catalog.mdx index 0d67ef8d..1e418ffc 100644 --- a/docs/he/policies/builtin-catalog.mdx +++ b/docs/he/policies/builtin-catalog.mdx @@ -1,106 +1,106 @@ --- -title: "קטלוג מדיניויות מובנה" -description: "בדוק כל מדיניות Failproof AI מובנית, את הטריגר שלה, המצב המומלץ, והפרמטרים הניתנים להגדרה." +title: "קטלוג המדיניויות המובנות" +description: "סקור כל מדיניות Failproof AI מובנית, את הטריגר שלה, המצב המומלץ והפרמטרים הניתנים להגדרה." icon: "list-checks" --- -החבילה המותקנת היא מקור האמת לזמינות המדיניויות. הרץ `failproofai policies` אחרי כל שדרוג כי ערכי הקטלוג וההתנהגות עשויים להשתנות עם גרסת החבילה. +החבילה המותקנת היא מקור האמת לזמינות המדיניויות. הרץ את `failproofai policies` אחרי כל שדרוג כי ערכי הקטלוג וההתנהגות עלולים להשתנות עם גרסת החבילה. -## בסיס מומלץ +## קו בסיס מומלץ -הבחירה המומלצת של ההגדרה המודרכת כרגע מאפשרת מחטאי סודות, הגנות סביבה, הגנה עצמית, שומרי פקודות קטסטרופליים והגנת ענפים מוגנים: +הבחירה המומלצת של ההתקנה המודרכת מאפשרת כרגע מטהרי סודות, הגנות סביבה, הגנה עצמית, שומרי פקודות קטסטרופליות והגנת ענפים מוגנים: ```text sanitize-jwt sanitize-api-keys sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars block-env-files block-secrets-write -block-self-pause block-failproofai-commands -block-sudo block-curl-pipe-sh -block-rm-rf block-push-master -block-force-push +block-failproofai-commands block-sudo +block-curl-pipe-sh block-rm-rf +block-push-master block-force-push ``` -המומלץ הוא בכוונה צר יותר מ**הכל**. מדיניויות תשתית וזרימת עבודה עשויות להפריע לעבודה תקפה ויש להפעיל אותן במאגרים ובמכונות שצריכים אותן. +`block-failproofai-commands` **תמיד פעילה**. היא רשומה למעלה לצורך שלמות, אך היא נרשמת בכל הערכה בין אם היא מופיעה בסט המופעל שלך ובין אם לא, ולא ניתן להשבית או להשהות אותה — זוהי הגנה נגד הסוכן שמסיר את האכיפה שהסוכן יכול להסיר אינה הגנה. + +המומלץ הוא בכוונה צר יותר מ**הכל**. מדיניויות תשתית וזרימת עבודה יכולות להפריע לעבודה תקינה וצריך להיות מופעלות עבור המאגרים והמכונות הזקוקות להן. ## סודות וסביבה | מדיניות | טריגר | תוצאה | | --- | --- | --- | -| `sanitize-jwt` | `PostToolUse` | הסתר JWTs מפלט כלים לפני שהמודל רואה אותם. | -| `sanitize-api-keys` | `PostToolUse` | הסתר OpenAI, Anthropic, GitHub, AWS, Stripe, ומפתחות Google נפוצים. | -| `sanitize-connection-strings` | `PostToolUse` | הסתר מחרוזות חיבור מסד נתונים המכילות כמויות. | -| `sanitize-private-key-content` | `PostToolUse` | הסתר גופי PEM של מפתח פרטי. | -| `sanitize-bearer-tokens` | `PostToolUse` | הסתר אסימוני ההרשאה. | -| `protect-env-vars` | `PreToolUse` בכלים של shell | חסום פקודות שמעדכנות משתני סביבה. | +| `sanitize-jwt` | `PostToolUse` | הסר JWTs מפלט הכלי לפני שהמודל רואה אותם. | +| `sanitize-api-keys` | `PostToolUse` | הסר מפתחות נפוצים של OpenAI, Anthropic, GitHub, AWS, Stripe ו-Google. | +| `sanitize-connection-strings` | `PostToolUse` | הסר מחרוזות חיבור לבסיס נתונים המכילות אישורים. | +| `sanitize-private-key-content` | `PostToolUse` | הסר גופי מפתח פרטי PEM. | +| `sanitize-bearer-tokens` | `PostToolUse` | הסר אסימוני הרשאה. | +| `protect-env-vars` | `PreToolUse` בכלים של shell | חסום פקודות שמזלזלות משתנות סביבה. | | `block-env-files` | `PreToolUse` | חסום קריאה וכתיבה של קבצי `.env`. | -| `block-read-outside-cwd` | `PreToolUse` בכלים read, glob, grep, או shell | שמור קריאות בתוך ספריית העבודה של הסשן. | -| `block-secrets-write` | `PreToolUse` בכלים של write | חסום כתיבה לשמות קבצים נפוצים של מפתחות סוד והעמדות בתוקף. | +| `block-read-outside-cwd` | `PreToolUse` בכלים של read, glob, grep או shell | השאר קריאות בתוך תיקיית העבודה של ההפעלה. | +| `block-secrets-write` | `PreToolUse` בכלים של write | חסום כתיבה לשמות קבצים של מפתח סודי ואישורים נפוצים. | ## פקודות מסוכנות ותשתית | מדיניות | טריגר | תוצאה | | --- | --- | --- | -| `block-self-pause` | `PreToolUse`, `PermissionRequest` | מנע סוכן מהשהיית אכיפתו שלו. | -| `block-sudo` | `PreToolUse`, `PermissionRequest` | חסום `sudo` אלא אם קיים שיוך לדפוס allow. | -| `block-curl-pipe-sh` | `PreToolUse` | חסום סקריפטים שהורדו מופנים ישירות ל-shell. | +| `block-sudo` | `PreToolUse`, `PermissionRequest` | חסום `sudo` אלא אם דפוס allow תואם. | +| `block-curl-pipe-sh` | `PreToolUse` | חסום סקריפטים מורידים המועברים ישירות לשל. | | `block-rm-rf` | `PreToolUse` | חסום דפוסי מחיקה רקורסיבית קטסטרופליים. | -| `block-failproofai-commands` | `PreToolUse` | מנע סוכנים משינוי או הסרת Failproof AI. | +| `block-failproofai-commands` | `PreToolUse`, `PermissionRequest` | **תמיד פעילה, לא ניתן להשבית.** חסום כל הפעלה של Failproof AI CLI, השהיית עצמית וביטול התקנת מנהל חבילות. | | `block-kubectl` | `PreToolUse` | שער פקודות Kubernetes. | -| `block-terraform` | `PreToolUse` | שער פקודות Terraform וOpenTofu. | +| `block-terraform` | `PreToolUse` | שער פקודות Terraform ו-OpenTofu. | | `block-aws-cli` | `PreToolUse` | שער פקודות AWS CLI. | | `block-gcloud` | `PreToolUse` | שער פקודות Google Cloud CLI. | | `block-az-cli` | `PreToolUse` | שער פקודות Azure CLI. | | `block-helm` | `PreToolUse` | שער פקודות Helm. | -| `block-gh-pipeline` | `PreToolUse` | שער פקודות GitHub CLI שמשנות זרימת עבודה, הפעלה, מיזוג, שחרור, cache, וחלקי סוד. | +| `block-gh-pipeline` | `PreToolUse` | שער פעולות GitHub CLI המשנות של זרימת עבודה, הפעלה, מיזוג, שחרור, מטמון וסודות. | -## בטיחות Git ומסד נתונים +## בטיחות Git ובסיס נתונים | מדיניות | טריגר | תוצאה | | --- | --- | --- | | `block-push-master` | `PreToolUse` | חסום דחיפות ישירות לענפים מוגנים שהוגדרו. | -| `block-force-push` | `PreToolUse` | חסום דחיפות כפויות; `--force-with-lease` נשאר מורשה בהטמעה הנוכחית. | -| `block-work-on-main` | `PreToolUse` | חסום commits ומיזוגים בענפים מוגנים. | -| `warn-git-amend` | `PreToolUse` | התרא לפני שכתוב מחדש של commit עם `--amend`. | -| `warn-git-stash-drop` | `PreToolUse` | התרא לפני הפלת או ניקוי סטאשים קבוע. | -| `warn-all-files-staged` | `PreToolUse` | התרא על `git add -A`, `git add .`, או `git add --all` רחב. | -| `warn-destructive-sql` | `PreToolUse` | התרא על `DROP`, `TRUNCATE`, ו`DELETE` ללא `WHERE` דרך לקוחות מסד נתונים מוכרים. | -| `warn-schema-alteration` | `PreToolUse` | התרא על פעולות `ALTER TABLE` עמודות וביטול שם מוכרות. | +| `block-force-push` | `PreToolUse` | חסום כפיית דחיפות; `--force-with-lease` נשאר מותר בהטמעה הנוכחית. | +| `block-work-on-main` | `PreToolUse` | חסום commits וmergים בענפים מוגנים. | +| `warn-git-amend` | `PreToolUse` | הזהר לפני שכתוב מחדש commit עם `--amend`. | +| `warn-git-stash-drop` | `PreToolUse` | הזהר לפני הטלה קבועה או ניקוי של stashes. | +| `warn-all-files-staged` | `PreToolUse` | הזהר על `git add -A`, `git add .` או `git add --all` רחבים. | +| `warn-destructive-sql` | `PreToolUse` | הזהר על `DROP`, `TRUNCATE` ו-`DELETE` ללא `WHERE` דרך לקוחות בסיס נתונים מוכרים. | +| `warn-schema-alteration` | `PreToolUse` | הזהר על פעולות `ALTER TABLE` של עמודות ושינוי שמות מוכרים. | -## חבילות, התנהגות מערכת, וזוגות סוכנים +## חבילות, התנהגות מערכת וحلقות סוכן | מדיניות | טריגר | תוצאה | | --- | --- | --- | -| `warn-package-publish` | `PreToolUse` | התרא לפני פרסום לרישומי חבילות. | -| `warn-global-package-install` | `PreToolUse` | התרא לפני התקנה גלובלית של חבילה. | -| `prefer-package-manager` | `PreToolUse` | הנחה הסוכן להשתמש במנהל חבילות מותר. | -| `warn-large-file-write` | `PreToolUse` בכלים של write | התרא מעל סף גודל קובץ שהוגדר. | -| `warn-background-process` | `PreToolUse` | התרא על דפוסי תהליך רקע מנותקים או ארוכי טווח. | -| `warn-repeated-tool-calls` | `PreToolUse` | התרא אחרי שלוש או יותר קריאות כלים זהות. | +| `warn-package-publish` | `PreToolUse` | הזהר לפני פרסום למאגרי חבילות. | +| `warn-global-package-install` | `PreToolUse` | הזהר לפני התקנה גלובלית של חבילות. | +| `prefer-package-manager` | `PreToolUse` | הנחה את הסוכן להשתמש במנהל חבילות מותר. | +| `warn-large-file-write` | `PreToolUse` בכלים של write | הזהר מעל סף גודל קובץ שהוגדר. | +| `warn-background-process` | `PreToolUse` | הזהר על דפוסי תהליכים רקע מנותקים או בעלי חיים ארוכים. | +| `warn-repeated-tool-calls` | `PreToolUse` | הזהר אחרי שלוש או יותר קריאות כלי זהות. | -## זרימת עבודה של סיום משימה +## זרימת עבודה סוף משימה -מדיניויות אלה דורשות מנוף שפולט אירוע `Stop` תואם. +מדיניויות אלו דורשות הרתעה הפולטת אירוע `Stop` תואם. | מדיניות | תוצאה | | --- | --- | -| `require-commit-before-stop` | סרב להשלמה בזמן שעבודה מעקב נותרה לא מובילה. | -| `require-push-before-stop` | סרב להשלמה בזמן שהתחייבויות נשארות מקומיות בלבד. | -| `require-pr-before-stop` | דרוש בקשת משיכה לענף הנוכחי. | -| `require-no-conflicts-before-stop` | דרוש מיזוג נקי כנגד ענף הבסיס שהוגדר. | -| `require-ci-green-before-stop` | דרוש שבדיקות CI של HEAD הנוכחי יושלמו בהצלחה. | +| `require-commit-before-stop` | דחה השלמה בזמן שעבודה מעקב נשארת לא committed. | +| `require-push-before-stop` | דחה השלמה בזמן שcommits נשאר ברמה מקומית בלבד. | +| `require-pr-before-stop` | דרוש pull request לענף הנוכחי. | +| `require-no-conflicts-before-stop` | דרוש merge נקי מול ענף הבסיס שהוגדר. | +| `require-ci-green-before-stop` | דרוש בדיקות CI של current-HEAD להשלים בהצלחה. | -## הפניה פרמטרים +## ייחוס פרמטרים הגדר פרמטרים תחת אובייקט `policyParams` של ההיקף שנבחר. סוגים מאומתים על ידי כל מדיניות. | מדיניות | פרמטר | סוג וברירת מחדל | | --- | --- | --- | -| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; רשומות מכילות `regex` ו`label` | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; ערכים מכילים `regex` ו-`label` | | `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | | `block-sudo` | `allowPatterns` | `string[]`, `[]` | | `block-rm-rf` | `allowPaths` | `string[]`, `[]` | -| Infrastructure blockers | `allowPatterns` | `string[]`, `[]` | +| חוסמי תשתית | `allowPatterns` | `string[]`, `[]` | | `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | | `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | | `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | @@ -125,5 +125,5 @@ block-force-push ``` - דפוס allow מרחיב את מה שסוכן עשוי לעשות. בדוק את הטוקניזציה המדויקת וגרסאות פקודה בתוך המנוף המטרה לפני פריסה בחברה. + דפוס allow מרחיב את מה שסוכן עשוי לעשות. בדוק את הטוקניזציה המדויקת וגרסאות הפקודה בהרתעה היעד לפני פריסה בכל הצי. \ No newline at end of file diff --git a/docs/he/policies/failure-behavior.mdx b/docs/he/policies/failure-behavior.mdx index 34a33202..0d11f875 100644 --- a/docs/he/policies/failure-behavior.mdx +++ b/docs/he/policies/failure-behavior.mdx @@ -1,19 +1,20 @@ --- -title: "התנהגות בעת כשל" -description: "הבנת מה קורה כאשר הערכת המדיניות או ה-daemon המקומי אינו זמין." +--- +title: "התנהגות כשלון" +description: "הבן מה קורה כשהערכת המדיניות או הדימון המקומי אינו זמין." icon: "shield-alert" --- -Failproof AI תוכנן כך שכשל אכיפה יהיה גלוי במקום להתיר בשקט עבודה מסוכנת. +Failproof AI מעוצב כך שכשל בהטמעה יהיה נראה במקום להתיר בשקט עבודה מסוכנת. -## אבחון בלוק סגור כשל +## אבחן בלוק סגור כשלון - 1. עברו ל-**Admin → enforcement** ופתחו את המכונה. - 2. בדקו את ה-check-in האחרון שלה, את ה-deployment המוקצה, וה-deployment המדווח. - 3. עברו ל-**Observe → policy** ופתחו את הסשן של ההחלטה המדחויה. - 4. אשרו האם הסיבה מדווחת בנוגע לנגישות daemon, חוסר התאמה בגרסה, או המדיניות עצמה. + 1. עבור ל **Admin → enforcement** ופתח את המכונה. + 2. בדוק את ה-check-in האחרון שלה, את ההטמעה שהוקצתה, ואת ההטמעה שדווחה. + 3. עבור ל **Observe → policy** ופתח את הסשן של החלטת הכשל. + 4. אשר האם הסיבה מדווחת על נגישות דימון, חוסר התאמה של גרסה, או המדיניות עצמה. @@ -23,21 +24,45 @@ Failproof AI תוכנן כך שכשל אכיפה יהיה גלוי במקום ל failproofai config ``` - הרצה חוזרת של `failproofai config` מעדכנת ומפעילה מחדש את ה-daemon לאחר שדרוג חבילה. + הפעלה מחדש של `failproofai config` מעדכנת ומפעילה מחדש את הדימון לאחר שדרוג חבילה. -על מכונה שהוגדרה להשתמש ב-`failproofaid`, ה-daemon הוא המעריך היחיד. אם הוא לא נגיש או גרסת הפרוטוקול שלו אינה תואמת ל-CLI, הערכת ה-hook נכשלת בצורה סגורה. הפעולה מדוחית עם סיבה המכוונת את המפעיל לבדיקה או עדכון ה-daemon. +על מכונה המוגדרת להשתמש ב-`failproofaid`, הדימון הוא המעריך היחיד. אם הוא אינו נגיש או גרסת הפרוטוקול שלו אינה תואמת ל-CLI, הערכת ה-hook נכשלת בצורה סגורה. הפעולה נשללת עם סיבה המכוונת את המפעיל לבדוק או לעדכן את הדימון. -לפני קביעת daemon, ה-hooks מעריכים מדיניות בתוך התהליך. לאחר ש-daemon configuration מוקלט, Failproof AI לא חוזר בשקט למעריך שני כאשר ה-daemon נכשל. +לפני תצורת הדימון, ה-hooks מעריכים מדיניויות בתהליך. לאחר שהתצורה של הדימון נרשמה, Failproof AI לא חוזר בשקט למעריך שני כאשר הדימון נכשל. -## תגובה להחלטה סגורה כשל +## הגב להחלטה סגורה כשלון -1. הריצו `failproofai config --status`. -2. אם הגרסאות שונות, הריצו מחדש את `failproofai config` לאחר עדכון החבילה. -3. אם ה-daemon אינו נגיש, בדקו את מצב השירות שלו ואת יומני המקום. -4. המשיכו בעבודת agent רק לאחר שנתיב הערכת מדיניות ידוע הוא בריא. +1. הרץ `failproofai config --status`. +2. אם הגרסאות שונות, הרץ מחדש `failproofai config` לאחר עדכון החבילה. +3. אם הדימון אינו נגיש, בדוק את מצב השירות שלו ואת היומנים המקומיים. +4. חזור לעבודת סוכן רק לאחר שנתיב הערכת מדיניות ידוע הוא בריא. - אל תנסו שוב וחוזר על הפעולה המחוסמת. תגובה סגורה כשל פירושה שהמערכת לא הצליחה לקבוע שהפעולה הייתה בטוחה. - \ No newline at end of file + אל תנסה שוב וחוזר פעמים רבות את הפעולה החסומה. תגובה סגורה כשלון פירושה שהמערכת לא יכלה לקבוע שהפעולה הייתה בטוחה. + + +## חבילה לא תעלה + +מכונה שנאמר לה להטיל ממשלה חבילה, ולא יכולה להפעיל אותה, משללת במקום להמשיך בשקט. הטריגר הוא **ציפיה מתועדת**, לעולם לא ריקה: מכונה ללא חבילות מותקנות שקטה, בעוד שחבילה שנהנת וכמויות לא יתפרו - או שמגיעה פחות מאשר המניפסט שלה מהנה - משללת. + +ה-deny הוא **צר**, בניגוד לדימון אי-נגיש. דימון שלא ניתן להגיע אליו פירושו שלא התרחשה הערכה כלל, כך ששום דבר לא יכול להיות ידוע כבטוח. חבילה שלא תעלה יש לה קבוצה ספירה של שומרים חסרים, כי כל מדיניות המוצהרת נושאת את שלה `match` - כך שהיא משללת רק את האירועים והכלים שהמדיניויות הללו כיסו, והכל אחר ממשיך. + +הוא לא יורה עבור: + +- חבילה `observe`, המעריכה ויוצרת על ידי בנייה +- מדיניויות שלעולם לא לקחת, או הדלקת מפורשת +- חבילה שהטוען לעולם לא קיבל, כאשר "אין הרשמות" לא יכול להיות מובחן מדילוג מכוון +- השהיית סשן פעילה +- זמן הקצאה טעון, שהוא חולף - רגע אחד של דיסק איטי חייב לא שלל עד שאדם אנושי מתערב + +`UserPromptSubmit` **מנחה** במקום משלול, כל מה שהמדיניות החסרה הצהירה. משלול כללי היה לוקח את זה ויינעול אותך מהסוכן שיכול לתקן את הבעיה. + +### מה לעשות + +```bash +failproofai pack list +``` + +זה שם כל חבילה מותקנת שלא תעלה, אומר למה, ויוצא לא אפס. לאחר מכן או התקן אותה מחדש (`failproofai pack add `) או הסר אותה (`failproofai pack remove `) - הסרתה משוללת את הציפיה, והשלול מפסיק איתו. \ No newline at end of file diff --git a/docs/he/policies/packs.mdx b/docs/he/policies/packs.mdx new file mode 100644 index 00000000..ff53046b --- /dev/null +++ b/docs/he/policies/packs.mdx @@ -0,0 +1,110 @@ +--- +title: "חבילות מדיניויות" +description: "התקן מערכת מדיניויות שפורסמה כהוצאת GitHub, וניהל את מה שהיא אוכפת." +icon: "package" +--- + +חבילה היא מערכת מדיניויות שפורסמה כהוצאת GitHub. פקודה אחת מתקינה אותה, סכומי הביקורת של ההוצאה מאומתים לפני כל פעולה, והתמצות מתועדת כדי שהחבילה לא תוכל להשתנות במכונה שלך בעתיד. + +## התקן את מדיניויות Failproof AI + +```bash +failproofai pack add core +``` + +זה מתקין את המערכה שאנו מפרסמים, מהעותק בתוך החבילה — לכן הוא לא צריך רשת ולא יכול להיכשל מאחורי proxy. קח חלק ממנה: + +```bash +failproofai pack add core --policy block-rm-rf # אחת, או כמה מופרדות בפסיק +failproofai pack add core --category dangerous-commands # קטגוריה שלמה +failproofai pack add core --all # הכל בה +``` + +`failproofai pack list` מפרט כל קטגוריה שהחבילה מציעה. + +## ראה מה חבילה מכילה, לפני התקנה + +```bash +failproofai pack list acme/support-agent +``` + +מפרט כל מדיניות שהחבילה מחזיקה, מקובצת לפי קטגוריה, וסימון איזו מהן הכותב שלה מפעיל כברירת מחדל ואילו הן הצמדות. זה קורא **רק את המניפסט** — הקובץ העיקרי לעולם לא מוּרד ולעולם לא יובא, כך שהסתכלות בחבילה של זר לא יכול להריץ קוד של זר. המניפסט עדיין בדוק נגד `SHA256SUMS` של ההוצאה עצמה, לכן מה שאתה קורא זה מה שיתקין. + +`failproofai pack list` ללא מקור מפרט את החבילות שכבר מותקנות כאן. + +## התקן חבילה של מישהו אחר + +```bash +failproofai pack add acme/support-agent +``` + +כל אלה עובדים — הדבק איזה שיש לך: + +| מקור | תוצאה | +| --- | --- | +| `acme/support-agent` | הוצאה החדשה ביותר, **מוצמדת** לתג המדויק שלה | +| `acme/support-agent@v2.1.0` | הוצאה זו | +| `github:acme/support-agent@v2.1.0` | אותו הדבר, כתוב במפורש | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | אותו הדבר, מועתק מדפדפן | + +ללא שם תג מתקין את ההוצאה החדשה ביותר **ומצמיד אותה**, ואז מגיד לך איזה תג הוא בחר. מה שנרשם תמיד קובע בדיוק הוצאה אחת, כך שהתקנה חוזרת לא יכולה להסחף. + +## קח חלק מחבילה + +כברירת מחדל אתה מקבל את **שלה** של החבילה עצמה — המדיניויות שהכותב שלה סימן כבטוחות להפעלה ללא השגחה — לא הכל שהיא מכילה. + +```bash +failproofai pack add acme/support-agent --category billing,git +failproofai pack add acme/support-agent --policy block-refunds +failproofai pack add acme/support-agent --all +``` + +`--category` ו-`--policy` משתלבים כאיחוד (`--only` מקובל כנרדף ל-`--policy`). הוספה חוזרת בגרסה חדשה יותר שומרת על מה שבחרת במקום להחזיר את השאר בהפעלה. + +## נהל מה פועל + +```bash +failproofai policies # כל מקור ברשימה אחת, חבילות כלולות +failproofai pack list # רק חבילות, מקובצות לפי קטגוריה +failproofai policies --uninstall block-refunds # כבה מדיניות חבילה אחת +failproofai policies --install block-refunds # ובחזרה הפעל +failproofai pack remove acme/support-agent +``` + +שם חשוף פירושו ה-**builtin** כאשר קיים אחד בשם זה. שם את עותק החבילה בבירור כשאתה צריך ל: + +```bash +failproofai policies --uninstall acme/support-agent:block-refunds +``` + + +אם חבילה משלחת מדיניות שגם שם שלה הוא **builtin מופעל**, ה-builtin רץ והעותק של החבילה דלוק — אותו הגן היה מוערך פעמיים אחרת. כבה את ה-builtin כדי להשתמש בעותק של החבילה במקום. + + +## מהיכן מדיניויות Failproof AI מגיעות + +`core` קורא את העותק שנשלח בחבילת npm. אותה מערכה פורסמת כהוצאת GitHub, שמה שאתה מתקין אם אתה רוצה גרסה ספציפית: + +```bash +failproofai pack add core # מחבילה זו, ללא רשת +failproofai pack add FailproofAI/policies # אותה מערכה, מהוצאת GitHub שלה +``` + +## מה שלמות עושה ולא עושה + +`SHA256SUMS` משלח בהוצאה זהה לקובץ, כך שהוא **לא** חתימה ולא מוכיח כלום על מי פרסם אותה. מה שהוא כן מוכיח זה שה-bytes הם שהוצאה פרסמה — וכי תמצות מתועדת כאשר אתה מוסיף את החבילה וחדש־אומתת לפני כל יבוא, חבילה לא יכולה להשתנות תחת מכונתך. מאגר שמסדר מחדש תגים או מחליף קובץ מפסיק לטעון במקום להריץ בשקט משהו אחר. + +בזמן התקנה החבילה גם **מיובאת פעם אחת** ובדוקה נגד המניפסט שלה. חבילה שקובץ שלה לא משתתח, או שרושמת משהו שלא הוא הצהיר, מסורבת לפני שום הפעלה — במקום התקנה ניקיה וכשל בקריאת כלי הבאה שלך. + +## כאשר חבילה לא תטען + +חבילה שמכונה זו נאמרה לאכוף ולא יכולה להריץ **דוחה** את האירועים שהמדיניויות החסרות שלה כיסו, במקום להתיר אותם בשקט. ראה [Failure behavior](/he/policies/failure-behavior). `failproofai pack list` מפרט כל חבילה במצב זה וצוא לא אפס. + +## אופלין וראי + +| משתנה | השפעה | +| --- | --- | +| `FAILPROOFAI_NO_DOWNLOAD=1` | מסרב להביא; חבילות שכבר מותקנות ממשיכות אוכיפות | +| `FAILPROOFAI_PACK_BASE_URL` | מצביע הבאה חבילות על ראי במקום `github.com` | + +פרסום החבילה שלך: ראה [Publish a pack](/he/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/he/policies/publish-a-pack.mdx b/docs/he/policies/publish-a-pack.mdx new file mode 100644 index 00000000..24e12786 --- /dev/null +++ b/docs/he/policies/publish-a-pack.mdx @@ -0,0 +1,91 @@ +--- +title: "פרסום חבילה" +description: "שלח את המדיניויות שלך כהוצאת GitHub שכל אחד יוכל להתקין." +icon: "upload" +--- + +חבילה היא שלושה קבצים המצורפים להוצאת GitHub. `failproofai pack build` כותב את שלושתם מקובץ מדיניות שכבר יש לך. + +## 1. כתוב את המדיניויות + +קובץ אחד, תוך שימוש באותה API כמו כל מדיניות מותאמת אישית. שני שדות נוספים משנים: + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-refunds", + description: "Refunds above the approved limit need a human", + category: "Billing", // groups it, and is what --category selects on + defaultEnabled: true, // switched on by a plain `pack add` + match: { events: ["PreToolUse"], tools: ["Bash"] }, + fn: async (ctx) => + String(ctx.toolInput?.command ?? "").includes("refund") + ? deny("Refunds need a human. Ask before running this.") + : allow(), +}); +``` + +`defaultEnabled` מוגדר כברירת מחדל ל־**false** כשאתה משמיט אותו. `failproofai pack add` פשוטה מדליקה רק את מה שסימנת — התקנת כל מדיניות של זר ללא감독מאינה החלטה שהמתקין צריך להחליט עבור המשתמש שלו. + + +הקובץ חייב להיות **קובץ עצמאי אחד**. רק הקובץ מוצמד ל־digest, כך שחבילה שמייבאת קבצים מקומיים לא יכולה להצהיר בכנות שה־digest מכסה מה שפועל. צרור קודם (`esbuild`, `bun build`, `rollup`) ובנה את החבילה מה־bundle — `pack build` דוחה ייבוא מקומי ולא משלח הבטחה שהיא לא יכולה לשמור. + + +## 2. בנה את נכסי ההוצאה + +```bash +failproofai pack build ./policies.mjs \ + --id acme/support-agent \ + --version 1.0.0 \ + --out ./dist-pack +``` + +הוא כותב שלושה קבצים, ומאמת כל מדיניות עם **כללי הטוען שלו** קודם — כך שחבילה שלא הייתה יכולה להתקין אף פעם נכשלת כאן, שם אתה יכול לתקן אותה: + +| קובץ | מה זה | +| --- | --- | +| `failproofai-pack.json` | המניפסט: id, גרסה, אפקט, וערך אחד לכל מדיניות | +| `failproofai-pack.mjs` | הקובץ שלך, כפי שהוא | +| `SHA256SUMS` | ` ` לשני האחרים | + +דחוי בזמן בנייה: id שאינו `publisher/name`, שם מדיניות המכיל `/`, מדיניות שמצהירה `alwaysOn`, `description`, `category` או `match` חסר, קובץ שלא רושם כלום, וקובץ שמייבא קבצים מקומיים. + +## 3. צרף אותם להוצאה + +תג את ההוצאה עם אותה גרסה שבנית, וצרף את שלושת הקבצים כנכסי הוצאה: + +```bash +gh release create 1.0.0 \ + ./dist-pack/failproofai-pack.json \ + ./dist-pack/failproofai-pack.mjs \ + ./dist-pack/SHA256SUMS +``` + +כל אחד יכול כעת להתקין אותה: + +```bash +failproofai pack add acme/support-agent +``` + +שמות הנכסים קבועים — אלה מה שה־CLI של הצרכן בונה את כתובות ה־URL שלהם, ללא קריאת API וללא גילוי. + +## משלוח גרסה חדשה + +בנה עם ה־`--version` החדש, תג הוצאה חדשה, צרף את שלושת הנכסים שוב. הצרכנים מריצים את אותו `pack add` ושומרים על כל תת־קבוצה שבחרו; מדיניות שהם כיבו נשארת כבויה בעלייה. + +שינוי **השם** של מדיניות הוא שינוי משברי: מכונה שכיבתה אותה מדליקה הגדרה שלא קיימת עוד, והשם החדש מגיע בכל מה ש־`defaultEnabled` אומר. + +## מה המשתמשים שלך סומכים + +`SHA256SUMS` חיה באותה הוצאה כמו הקובץ, כך שהוא מוכיח שהבייטים הם אלה שפרסמת — לא מי אתה. כל מי שיכול לכתוב למאגר יכול לכתוב לשני הקבצים. ההגנה של המשתמשים שלך היא שה־digest מוצמד כשהם מתקינים, כך שמה שחדשת לא יכול להשתנות אחריהם. + +פרסום מממאגר שגישת הכתיבה שלו אתה שולט, וטפל בהוצאת חבילה כמו פרסום חבילה. + +## התבונן לפני שאתה אוכף + +מניפסט עשוי להצהיר `"effect": "observe"`. מדיניויות אלה פועלות והפסקותיהן **מתועדות ומושלכות** — כלום לא חסום. זו הדרך למדוד כלל חדש מול תנועה אמיתית לפני שהוא יכול להפריע לעבודה של מישהו. + +```json +{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +``` \ No newline at end of file diff --git a/docs/he/reference/failproof-cli.mdx b/docs/he/reference/failproof-cli.mdx index b4b52530..ec755a3b 100644 --- a/docs/he/reference/failproof-cli.mdx +++ b/docs/he/reference/failproof-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof AI CLI" -description: "התקן hooks, נהל מדיניות מקומית, התחבר לענן והפעל את daemon המקומי." +description: "התקן hooks, נהל מדיניות מקומית, התחבר ל-Cloud, והפעל את ה-daemon המקומי." icon: "terminal" --- התקן את ה-CLI המקומי עם `npm install -g failproofai`. הרץ אותו ללא ארגומנטים כדי לפתוח את לוח הבקרה של המדיניות המקומית. -החבילה דורשת Node.js 20.9 ואילך. Bun 1.3 ואילך נתמך לפיתוח והתקנות מקוד מקור. `failproofai configure` ו-`failproofai setup` הם כינויים ל-`failproofai config`; `failproofai p` הוא כינוי ל-`failproofai policies`. +החבילה דורשת Node.js גרסה 20.9 ומעלה. Bun גרסה 1.3 ומעלה נתמך לפיתוח והתקנות מקוד מקור. `failproofai configure` ו-`failproofai setup` הם כינויים ל-`failproofai config`; `failproofai p` הוא כינוי ל-`failproofai policies`. ## הגדר מכונה @@ -25,57 +25,62 @@ failproofai config --status | פקודה | תוצאה | | --- | --- | | `failproofai config` | הרץ הגדרת מכונה אינטראקטיבית | -| `failproofai config --connect --token ` | התחבר לספיגת ענן וביצוע מדיניות | -| `failproofai config --status` | הצג מצב חיבור, daemon, ביצוע והשהיה | -| `failproofai policies` | רשום מדיניות מובנות ומותאמות | +| `failproofai config --connect --token ` | התחבר ל-Cloud ingestion והעברת מדיניות | +| `failproofai config --status` | הצג חיבור, daemon, משלוח, ומצב השהיה | +| `failproofai policies` | רשום מדיניות מובנית, מותאמת אישית, קונבנציה, pack, וניהול ב-Cloud | | `failproofai policies --install` | התקן hooks והפעל מדיניות | -| `failproofai policy add ` | הפעל מדיניות מובנית אחת | -| `failproofai policy remove ` | כבה מדיניות מובנית אחת | -| `failproofai policies --uninstall` | כבה מדיניות או הסר hooks של ציוד | -| `failproofai audit` | סרוק היסטוריית סוכן מקומית ופתח את תצוגת הביקורת המקומית | -| `failproofai audit --schedule [days] --email
` | תזמן סריקות מקומיות חוזרות ושלח את הממצאים לאימייל | -| `failproofai audit --status` | הצג את כתובת הדוח, המרווח והסריקה המתוזמנת הבאה | -| `failproofai audit --no-schedule` | עצור סריקות חוזרות ללא מחיקת היסטוריית הביקורת | +| `failproofai policy add ` | הפעל מדיניות אחת — מובנית, או `:` מ-pack מותקן | +| `failproofai policy remove ` | השבת מדיניות אחת, אותה שמות | +| `failproofai policies --uninstall` | השבת מדיניות או הסר hooks בחרוז | +| `failproofai pack list` | רשום policy packs מותקנים וכל מדיניות שכל אחד מהם מכיל | +| `failproofai pack add ` | התקן policy pack משחרור GitHub; ללא tag מייצר הכי חדש והצמוד | +| `failproofai pack add --bundled` | התקן את המדיניות המובנית כ-pack, מהחבילה הזו, ללא רשת | +| `failproofai pack build ` | בנה את שלושת נכסי ההפצה ל-pack שלך | +| `failproofai pack remove ` | השבת pack מותקן | +| `failproofai audit` | סרוק את היסטוריית agent מקומית ופתח את תצוגת הביקורת המקומית | +| `failproofai audit --schedule [days] --email
` | תזמן סריקות מקומיות חוזרות ושלח את ממצאיהן בדוא״ל | +| `failproofai audit --status` | הצג כתובת דו״ח, מרווח, וסריקה מתוזמנת הבאה | +| `failproofai audit --no-schedule` | עצור סריקות חוזרות ללא מחיקת היסטוריית ביקורת | | `failproofai harness list` | רשום נתיבי לכידה נוספים | -| `failproofai flush --wait` | הספק את ספול האירוע הנוכחי | -| `failproofai backfill --since 30d` | קרא מחדש היסטוריה שעברה בעבר | -| `failproofai config --pause [duration]` | השהה הפעלה מקומית אחת למשך 30 דקות כברירת מחדל, עד 8 שעות | -| `failproofai config --resume` | שחזר הפעלה מקומית מושהית אחת; הוסף `--all` כדי לנקות את כל ההשהיות | -| `failproofai update` | סיים הגרות חבילות ועדכן את ה-daemon | -| `failproofai migrate --dry-run` | תצוג קדימה או הרץ הגרות פריסת בית שלא בוצעו | -| `failproofai uninstall` | הסר hooks ו-daemon לפני הסרת החבילה | +| `failproofai flush --wait` | השלח את ספול האירועים הנוכחי | +| `failproofai backfill --since 30d` | קרא מחדש היסטוריה שעברה קודם לכן | +| `failproofai config --pause [duration]` | השהה הפעלה מקומית אחת ל-30 דקות כברירת מחדל, עד 8 שעות | +| `failproofai config --resume` | חזור הפעלה מקומית מושהית; הוסף `--all` כדי לנקות את כל ההשהיות | +| `failproofai update` | סיים הגדרות חבילה והדוק את ה-daemon | +| `failproofai migrate --dry-run` | תצפית או הרץ הגדרות בקיץ-בבית מסיימות | +| `failproofai uninstall` | הסר hooks וה-daemon לפני הסרת החבילה | | `failproofai --version` | הדפס את גרסת החבילה המותקנת | -| `failproofai --help` | הצג פקודות וגבול שימוש | +| `failproofai --help` | הצג פקודות ושימוש גלובלי | ## דגלי תצורה | דגל | שימוש | | --- | --- | -| `--connect --token ` | התחבר ללא אינטראקטיביות | -| `--machine-id ` | הגדר את מזהה המכונה היציב | -| `--machine-label ` | הגדר או שנה את תווית לוח הבקרה | -| `--no-transcripts` | שלח החלטות ללא תוכן תמליל | -| `--disconnect` | עצור משיכות מדיניות ענן והעברת אירוע | +| `--connect --token ` | התחבר ללא אינטראקציה | +| `--machine-id ` | קבע את זהות המכונה היציבה | +| `--machine-label ` | קבע או שנה את תווית לוח הבקרה | +| `--no-transcripts` | שלח החלטות ללא תוכן תמלול | +| `--disconnect` | עצור משיכות מדיניות ב-Cloud ושילוח אירועים | | `--status` | הצג את מצב המכונה הנוכחי | -| `--pause [duration]` | השהה את ההפעלה החדשה ביותר בספריה הנוכחית; קבל שניות, דקות או שעות וברירת מחדל של 30 דקות | -| `--resume` | סיים השהיה תואמת מוקדם | -| `--session ` | כוון להפעלה מפורשת להשהיה או חידוש | +| `--pause [duration]` | השהה את ההפעלה החדשה ביותר בספרייה הנוכחית; קבל שניות, דקות או שעות וברירת מחדל ל-30 דקות | +| `--resume` | סיים השהיה משחקת מוקדם | +| `--session ` | יעד הפעלה מפורשת להשהיה או חזרה | | `--all` | עם `--resume`, סיים כל השהיה פעילה | -השהיות מקומיות מושהות מדיניות מובנית, מותאמת וכנס למספר הפעלה אחת. הן תמיד פוקעות ואינן משבתות מדיניות מנוהלת בענן. `block-self-pause` מונע מסוכן מוכשר להשתמש בפתח בריחה זה בעצמו. +השהיות מקומיות משעות מדיניות מובנית, מותאמת אישית, קונבנציה, ו-pack עבור הפעלה אחת. הם תמיד פוקעים ואינם משביתים מדיניות ניהול ב-Cloud. `block-failproofai-commands` — שהוא תמיד פועל ולא יכול להיות משביתה בעצמו — מונע מ-agent מלוכד להשתמש בדלת מילוט זו בעצמו. ## דגלי מדיניות | דגל | שימוש | | --- | --- | -| `--install`, `-i` | הפעל מדיניות והתקן hooks ציוד | -| `--uninstall`, `-u` | כבה מדיניות או הסר hooks | -| `--cli ` | כוון לאחד או יותר ציודים נתמכים | -| `--scope user\|project\|local\|all` | בחר את ניתוק ההגדרה; `all` הוא להסרה | +| `--install`, `-i` | הפעל מדיניות והתקן hooks בחרוז | +| `--uninstall`, `-u` | השבת מדיניות או הסר hooks | +| `--cli ` | יעד חרוז אחד או יותר נתמך | +| `--scope user\|project\|local\|all` | בחר טווח תצורה; `all` עבור uninstall | | `--beta` | כלול מדיניות בטא | -| `--custom`, `-c ` | אמת וטען קובץ מדיניות מותאם; חוזר | +| `--custom`, `-c ` | אמת וטען קובץ מדיניות מותאם אישית; חוזר | -## דגלי ביצוע ותחזוקה +## דגלי משלוח ותחזוקה | פקודה | דגלים | | --- | --- | @@ -85,9 +90,9 @@ failproofai config --status | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` צריך להיות מורץ אחרי `npm install -g failproofai@latest`; הוא מבצע הגרות פריסת בית, מתקין את ה-daemon בינארי התואם ומפעיל מחדש את השירות. `--no-daemon` מבצע רק הגרת פריסה. +`failproofai update` צריך להיות מופעל אחרי `npm install -g failproofai@latest`; זה מבצע הגדרות פריסה, מתקין את בינארי ה-daemon תואם, ומפעיל מחדש את השירות. `--no-daemon` מבצע רק הגדרות פריסה. -## נתיבי ציוד +## נתיבי חרוז ```text failproofai harness list [harness] @@ -95,11 +100,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -שמות ציוד נתמכים הם `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` ו-`goose`. +שמות חרוז נתמך הם `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, ו-`goose`. -תוויות משמרות מזהי סוכן נגזרים כאשר שני שורשים מכילים עותקים של אותו פרויקט. שורשים חופפים וכינויים כפולים נדחים כדי למנוע אוסף כפול או קטע. תצורת נתיב נוסף טוענת מחדש ללא הפעלה מחדש של daemon. +תוויות מרחב זהות agent נגזרות כאשר שני שורשים מכילים עותקים של אותו פרויקט. שורשים חופפים ותוויות כפולות נדחו כדי למנוע אוסף כפול או חרב corruption. תצורת נתיב נוסף מטענת מחדש ללא הפעלה מחדש של daemon. -סביבות מכולה יכולות להחליף נתיבים נוספים שנוצרו בקובץ בעזרת משתנה המופרד בפסיקים בשם `FAILPROOFAI__EXTRA_PATHS`, למשל: +סביבות קונטיינר יכולות להחליף נתיבים קבוצים בקובץ עם משתנה מופרד בפסיקים בשם `FAILPROOFAI__EXTRA_PATHS`, לדוגמה: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -107,24 +112,26 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## משתני סביבה -השתמש בקובצי תצורה לתנהגות מכונה קבועה. משתני סביבה שימושיים ביותר למכולות, בדיקות והפעלה יחידה. +השתמש בקובצי תצורה להתנהגות מכונה קבועה. משתני סביבה הם שימושיים ביותר לקונטיינרים, בדיקות, ותהליך אחד. | משתנה | שימוש | | --- | --- | -| `FAILPROOFAI_HOME` | העבר את פריסת `~/.failproofai` המוחלטת | -| `FAILPROOFAI_LOG_LEVEL` | הגדר את מילולות הרישום המקומי | +| `FAILPROOFAI_HOME` | העבר את הפריסה המלאה `~/.failproofai` | +| `FAILPROOFAI_LOG_LEVEL` | קבע רמת רבונות רישום מקומית | | `FAILPROOFAI_HOOK_LOG_FILE` | כתוב אבחון hook לקובץ נבחר | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | כבה טלמטריה אנונימית לתהליך זה | -| `FAILPROOFAI_NO_FIRST_RUN=1` | דלג על הגדרת הפעלה ראשונה אינטראקטיבית | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | דלג על ביקורת מקומית לאחר הגדרה | -| `FAILPROOFAI_LLM_BASE_URL` | עקוף את נקודת הקצה התואמת OpenAI המשמשת למדיניות LLM | -| `FAILPROOFAI_LLM_API_KEY` | ספק את מפתח ה-API המשמש למדיניות LLM | -| `FAILPROOFAI_LLM_MODEL` | בחר את המודל המשמש למדיניות LLM | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | חוסם טעינת מודול מדיניות מותאמת | -| `FAILPROOFAI__EXTRA_PATHS` | החלף נתיבי לכידה נוספים מוגדרים לציוד אחד | -| `NO_COLOR` | כבה פלט טרמינל צבוע | - -משתני בית ספציפיים לסוכן כגון `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` ו-`OPENCLAW_HOME` עוקפים היכן Failproof AI גילה הפעלות מקומיות לציוד זה. +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | השבת טלמטריה אנונימית להפעלה זו | +| `FAILPROOFAI_NO_FIRST_RUN=1` | דלג על הגדרת הרצה ראשונה אינטראקטיבית | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | דלג על ביקורת מקומית אחרי הגדרה | +| `FAILPROOFAI_LLM_BASE_URL` | דרוס את נקודת הקצה תואמת OpenAI בשימוש במדיניות LLM | +| `FAILPROOFAI_LLM_API_KEY` | ספק את מפתח ה-API בשימוש במדיניות LLM | +| `FAILPROOFAI_LLM_MODEL` | בחר את המודל בשימוש במדיניות LLM | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | חוק טעינת מודול מדיניות מותאמת אישית | +| `FAILPROOFAI_NO_DOWNLOAD=1` | דחה להביא packs ובינאריים daemon; מה שמותקן שומר על אכיפה | +| `FAILPROOFAI_PACK_BASE_URL` | הביא packs ממראה במקום `github.com` | +| `FAILPROOFAI__EXTRA_PATHS` | החלף נתיבי לכידה נוספים מוגדרים לחרוז אחד | +| `NO_COLOR` | השבת פלט טרמינל צבעוני | + +משתני בית ספציפיים ל-agent כגון `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME`, ו-`OPENCLAW_HOME` דורסים היכן Failproof AI גוגל הפעלות מקומיות לחרוז זה. ## השהה או הסר מכונה בבטחה @@ -134,9 +141,9 @@ failproofai config --status failproofai config --resume ``` -השהיה של הפעלה מקומית אינה משבתת מדיניות מנוהלת בענן. שחזר פריסות ענן דרך זרימת האכיפה של ענן כאשר התצוג עצמו הוא הבעיה. +השהיית הפעלה מקומית אינה משביתה מדיניות ניהול ב-Cloud. שחזר פריסות Cloud דרך זרימת עבודת אכיפה ב-Cloud כאשר ההטלה עצמה היא הבעיה. -לפני הסרת חבילת npm, הסר hooks והוקינים daemon: +לפני הסרת החבילה npm, הסר hooks מותקנים וה-daemon: ```bash failproofai uninstall --dry-run @@ -147,5 +154,5 @@ npm rm -g failproofai הרץ `failproofai --help` לפרטים ספציפיים לגרסה. - הרץ `failproofai uninstall` לפני `npm rm -g failproofai`; npm אינו מסיר hooks סוכן מותקנים או שירות daemon. + הרץ `failproofai uninstall` לפני `npm rm -g failproofai`; npm לא מסיר hooks agent מותקנים או שירות daemon. \ No newline at end of file diff --git a/docs/he/start/quickstart.mdx b/docs/he/start/quickstart.mdx index 2e27d13e..cd8dc171 100644 --- a/docs/he/start/quickstart.mdx +++ b/docs/he/start/quickstart.mdx @@ -1,15 +1,16 @@ --- +--- title: "התחלה מהירה" -description: "תופס סשן של סוכן, מוצא כשל, והתחל למנוע אותו." +description: "תפוס הפעלת סוכן, מצא כשל והתחל למנוע אותו." icon: "zap" --- -התחלה מהירה זו מגבילה מכונה אחת לדיווח סשנים, מפעילה ביקורת, וממשנת מדיניות. השתמש בכישרון כדי להגדיר את Failproof AI, או עקוב אחר השלבים הידניים. +התחלה מהירה זו מעלה מכונה אחת לדיווח הפעלות, מריצה ביקורת ופורסת מדיניות. השתמש בכישור כדי להגדיר את Failproof AI, או בצע את השלבים ידנית. -**איזה נתיב הוא שלך?** אם הסוכן שלך פועל באחד מ-12 [מנשקים](/he/reference/harnesses) שנתמכים — CLI לקידוד, או שער כמו Hermes או OpenClaw — עקוב אחר השלבים למטה; אתה צריך Node.js 20.9 או מאוחר יותר. אם לסוכן שלך אין מנשק, תרגם אותו עם [Python SDK](/he/reference/custom-agents) לעקיבה וביקורות, ואז חזור ל-[הפעל את בדיקת הכשל הראשונה שלך](/he/start/first-audit); אוכיפוי בנתיב זה דורש hook בסביבת הריצה שלך. +**איזו דרך היא שלך?** אם הסוכן שלך פועל באחד מ-12 [הרתקים](/he/reference/harnesses) הנתמכים — CLI קידוד, או שער כמו Hermes או OpenClaw — בצע את השלבים להלן; אתה זקוק Node.js 20.9 ואילך. אם לסוכן שלך אין הרתק, צור אותו בעזרת [Python SDK](/he/reference/custom-agents) לעקיבה וביקורות, ואז חזור אל [הרץ את בדיקת הכשל הראשונה שלך](/he/start/first-audit); אכיפה בנתיב זה דורשת hook בזמן ריצה שלך. - + ```bash @@ -21,22 +22,22 @@ icon: "zap" Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - הסוכן שלך בוחן את הפרויקט, בוחר את האינטגרציה הרלוונטית, מבצע את ההגדרה, ומאמת אותה. ראה את [מאגר הכישורים של FailproofAI](https://github.com/FailproofAI/skills) לכישורים בודדים ואפשרויות התקנה מתקדמות. + הסוכן שלך בוחן את הפרויקט, בוחר את האינטגרציה הרלוונטית, מבצע את ההגדרה ומאמת אותה. ראה את [מאגר כישורי FailproofAI](https://github.com/FailproofAI/skills) לקבלת כישורים בודדים ואפשרויות התקנה מתקדמות. ## לפני שתתחיל -1. פתח את [לוח הבקרה של Failproof AI](https://app.befailproof.ai) וצור חשבון או התחבר עם אימייל עבודה. -2. עבור ל-**Administration → Keys** וצור מפתח עם `events:add` ו-`policies:pull`. -3. העתק את הסוד החד-פעמי ושמור אותו במכונת היעד: +1. פתח את [לוח הבקרה של Failproof AI](https://app.befailproof.ai) וצור חשבון או היכנס עם כתובת הדוא"ל שלך בעבודה. +2. עבור אל **Administration → Keys** וצור מפתח עם `events:add` ו-`policies:pull`. +3. העתק את הסוד לשימוש חד-פעמי והנח אותו במכונת היעד: ```bash export FAILPROOFAI_KEY="" ``` - ## התקן + ## התקנה @@ -45,9 +46,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - תמלילי סשן נשלחים כברירת מחדל. הוסף `--no-transcripts` כדי לדווח על פעילות hook והחלטות מדיניות ללא תוכן תמלילים. + תמלילי הפעלות נשלחים כברירת מחדל. הוסף `--no-transcripts` כדי לדווח על פעילות hook והחלטות מדיניות ללא תוכן תמליל. - אם למכונה זו יש כבר היסטוריה של סוכן, תצפה וייבא את שבעת הימים האחרונים, ואז חכה שההסגרה תסתיים. דלג על שלב זה במכונה חדשה. + אם למכונה זו כבר יש היסטוריה סוכן, הצג תצוגה מקדימה וייבא את שבעת הימים האחרונים, ואז חכה שהמסירה תסתיים. דלג על שלב זה במכונה חדשה. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +56,30 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - פתח את **Sessions** ב-Failproof AI ובחר סשן שיובא. + פתח **Sessions** ב-Failproof AI ובחר הפעלה מיובאת. - - זה מחבר את Failproof AI למנשק שלך ומתקין את 40 המדיניויות המובנות. השתמש בהם כדי לראות החלטות מדיניות מקומיות ולנסות אוכיפוי לפני שFailproof AI מבקר בסשנים שלך וכותב מדיניויות לסוכנים שלך. + + פעולה זו מחברת את Failproof AI להרתק שלך ומתקנת את 39 המדיניות הבנויות. השתמש בהם כדי לראות החלטות מדיניות מקומיות וכדי לנסות אכיפה לפני שFailproof AI מבקר בהפעלות שלך וכותב מדיניות לסוכנים שלך. - תן למתקין לגלות את המנשק שלך, או תן שם למשהו באופן מפורש. כל אחד מ-12 הוא ערך `--cli` תקף — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + אפשר לגלאי להעלות את ההרתק שלך, או ציין אחד במפורש. כל אחד מ-12 הוא ערך `--cli` תקף — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash failproofai policies --install --cli claude --scope user # a coding CLI failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - חסימת קריאת כלי לפני שהיא פועלת מתאומתת בכל 12. שערי סוף תור מתאומתים ב-8 — ראה [יכולת אוכיפוי](/he/reference/harnesses#enforcement-capability) למטריצת ההפעלה לכל מנשק. + חסימת קריאת כלי לפני שהיא רצה מאומתת על כל 12. שערים בסוף פנייה מאומתים ב-8 — ראה [יכולת אכיפה](/he/reference/harnesses#enforcement-capability) למטריצה לפי הרתק. - - עקוב אחר [הפעל את בדיקת הכשל הראשונה שלך](/he/start/first-audit). השתמש במטרה קונקרטית כגון "מצא סשנים שבהם הסוכן ניסה שוב כלי שנכשל ללא שינוי בגישתו." + + עקוב אחר [הרץ את בדיקת הכשל הראשונה שלך](/he/start/first-audit). השתמש במטרה קונקרטית כמו "מצא הפעלות שבהן הסוכן ניסה שוב כלי שכישל ללא שינוי בגישתו." - עקוב אחר [מנע את הכשל הראשון שלך עם מדיניות](/he/start/first-policy). התחל במצב צפייה, בדוק התאמות, ואז אוכף את הגרסה שנבדקה. + עקוב אחר [מנע את הכשל הראשון שלך עם מדיניות](/he/start/first-policy). התחל במצב תצפית, בדוק התאמות, ואז אכוף את הגרסה שבדוקה. - הפעל `failproofai config --status`. הגדרה בריאה מדווחת על חיבור הענן, מצב daemon, ואם אוכיפוי מושהה. + הרץ `failproofai config --status`. הגדרה בריאה מדווחת על חיבור ענן, מצב daemon, ויומא האכיפה מושהה. \ No newline at end of file diff --git a/docs/hi/policies/builtin-catalog.mdx b/docs/hi/policies/builtin-catalog.mdx index 40c17c83..d6613857 100644 --- a/docs/hi/policies/builtin-catalog.mdx +++ b/docs/hi/policies/builtin-catalog.mdx @@ -1,98 +1,98 @@ --- title: "बिल्ट-इन पॉलिसी कैटलॉग" -description: "प्रत्येक बिल्ट-इन Failproof AI पॉलिसी, इसके ट्रिगर, अनुशंसित स्थिति और कॉन्फ़िगरेबल पैरामीटर की समीक्षा करें।" +description: "प्रत्येक बिल्ट-इन Failproof AI पॉलिसी, इसके ट्रिगर, अनुशंसित स्थिति और कॉन्फ़िगर करने योग्य पैरामीटर की समीक्षा करें।" icon: "list-checks" --- -इंस्टॉल किया गया पैकेज पॉलिसी उपलब्धता का स्रोत है। हर अपग्रेड के बाद `failproofai policies` चलाएं क्योंकि कैटलॉग प्रविष्टियां और व्यवहार पैकेज संस्करण के साथ बदल सकते हैं। +स्थापित पैकेज पॉलिसी उपलब्धता का सत्य स्रोत है। हर अपग्रेड के बाद `failproofai policies` चलाएं क्योंकि कैटलॉग प्रविष्टियां और व्यवहार पैकेज संस्करण के साथ बदल सकते हैं। ## अनुशंसित बेसलाइन -गाइडेड सेटअप की अनुशंसित चयन वर्तमान में सीक्रेट सैनिटाइज़र, पर्यावरण संरक्षण, स्व-सुरक्षा, विनाशकारी-कमांड गार्ड और संरक्षित-शाखा सुरक्षा को सक्षम करता है: +निर्देशित सेटअप की अनुशंसित चयन वर्तमान में सीक्रेट सैनिटाइजर, पर्यावरण सुरक्षा, आत्म-सुरक्षा, विनाशकारी-कमांड गार्ड और संरक्षित-ब्रांच सुरक्षा सक्षम करता है: ```text sanitize-jwt sanitize-api-keys sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars block-env-files block-secrets-write -block-self-pause block-failproofai-commands -block-sudo block-curl-pipe-sh -block-rm-rf block-push-master -block-force-push +block-failproofai-commands block-sudo +block-curl-pipe-sh block-rm-rf +block-push-master block-force-push ``` -अनुशंसित जानबूझकर **Everything** से संकीर्ण है। इंफ्रास्ट्रक्चर और वर्कफ़्लो पॉलिसियां वैध कार्य को बाधित कर सकती हैं और उन्हें उन रिपॉजिटरीज़ और मशीनों के लिए सक्षम किया जाना चाहिए जिन्हें उनकी आवश्यकता है। +`block-failproofai-commands` **हमेशा चालू** रहता है। यह पूर्णता के लिए ऊपर सूचीबद्ध है, लेकिन यह हर मूल्यांकन पर पंजीकृत होता है, चाहे यह आपके सक्षम समुच्चय में दिखाई दे या नहीं, और इसे अक्षम या रोका नहीं जा सकता — यह एजेंट द्वारा बंद किए जा सकने वाले प्रवर्तन को बंद करने के खिलाफ एक सुरक्षा है। -## सीक्रेट्स और पर्यावरण +अनुशंसित जानबूझकर **Everything** से अधिक संकीर्ण है। बुनियादी ढांचा और वर्कफ़्लो पॉलिसियां वैध कार्य को बाधित कर सकती हैं और उन्हें उन रिपॉजिटरी और मशीनों के लिए सक्षम किया जाना चाहिए जिन्हें उनकी आवश्यकता है। + +## सीक्रेट और पर्यावरण | पॉलिसी | ट्रिगर | परिणाम | | --- | --- | --- | -| `sanitize-jwt` | `PostToolUse` | मॉडल देखने से पहले टूल आउटपुट से JWTs को संपादित करें। | -| `sanitize-api-keys` | `PostToolUse` | सामान्य OpenAI, Anthropic, GitHub, AWS, Stripe और Google कुंजियों को संपादित करें। | -| `sanitize-connection-strings` | `PostToolUse` | क्रेडेंशियल्स युक्त डेटाबेस कनेक्शन स्ट्रिंग्स को संपादित करें। | -| `sanitize-private-key-content` | `PostToolUse` | PEM प्राइवेट-की बॉडीज़ को संपादित करें। | -| `sanitize-bearer-tokens` | `PostToolUse` | अधिकरण वाहक टोकन को संपादित करें। | -| `protect-env-vars` | शेल टूल्स पर `PreToolUse` | पर्यावरण चर डंप करने वाली कमांड्स को ब्लॉक करें। | -| `block-env-files` | `PreToolUse` | `.env` फ़ाइलों के पढ़ने और लिखने को ब्लॉक करें। | -| `block-read-outside-cwd` | रीड, ग्लोब, ग्रेप या शेल टूल्स पर `PreToolUse` | रीड को सेशन कार्य निर्देशिका के भीतर रखें। | -| `block-secrets-write` | राइट टूल्स पर `PreToolUse` | सामान्य सीक्रेट-की और क्रेडेंशियल फ़ाइलनामों में राइट को ब्लॉक करें। | - -## खतरनाक कमांड्स और इंफ्रास्ट्रक्चर +| `sanitize-jwt` | `PostToolUse` | मॉडल के द्वारा देखे जाने से पहले टूल आउटपुट से JWT को हटाएं। | +| `sanitize-api-keys` | `PostToolUse` | सामान्य OpenAI, Anthropic, GitHub, AWS, Stripe और Google कुंजियों को हटाएं। | +| `sanitize-connection-strings` | `PostToolUse` | क्रेडेंशियल वाली डेटाबेस कनेक्शन स्ट्रिंग को हटाएं। | +| `sanitize-private-key-content` | `PostToolUse` | PEM प्राइवेट-की बॉडी को हटाएं। | +| `sanitize-bearer-tokens` | `PostToolUse` | प्राधिकरण बीयरर टोकन को हटाएं। | +| `protect-env-vars` | शेल टूल्स पर `PreToolUse` | पर्यावरण चर डंप करने वाली कमांड को ब्लॉक करें। | +| `block-env-files` | `PreToolUse` | `.env` फाइलों को पढ़ना और लिखना ब्लॉक करें। | +| `block-read-outside-cwd` | पढ़ने, ग्लोब, ग्रेप या शेल टूल्स पर `PreToolUse` | सेशन कार्य निर्देशिका के अंदर पढ़ना रखें। | +| `block-secrets-write` | लेखन टूल्स पर `PreToolUse` | सामान्य सीक्रेट-की और क्रेडेंशियल फाइलनामों में लिखना ब्लॉक करें। | + +## खतरनाक कमांड और बुनियादी ढांचा | पॉलिसी | ट्रिगर | परिणाम | | --- | --- | --- | -| `block-self-pause` | `PreToolUse`, `PermissionRequest` | एजेंट को अपने स्वयं के प्रवर्तन को रोकने से रोकें। | -| `block-sudo` | `PreToolUse`, `PermissionRequest` | `sudo` को ब्लॉक करें जब तक कि अनुमति पैटर्न मेल न खाए। | -| `block-curl-pipe-sh` | `PreToolUse` | डाउनलोड की गई स्क्रिप्ट्स को सीधे शेल में पाइप करने से ब्लॉक करें। | +| `block-sudo` | `PreToolUse`, `PermissionRequest` | `sudo` को ब्लॉक करें जब तक कि कोई allow पैटर्न मेल न खाए। | +| `block-curl-pipe-sh` | `PreToolUse` | डाउनलोड की गई स्क्रिप्ट को सीधे शेल में पाइप किए जाने को ब्लॉक करें। | | `block-rm-rf` | `PreToolUse` | विनाशकारी रिकर्सिव डिलीशन पैटर्न को ब्लॉक करें। | -| `block-failproofai-commands` | `PreToolUse` | एजेंट्स को Failproof AI बदलने या अनइंस्टॉल करने से रोकें। | -| `block-kubectl` | `PreToolUse` | Kubernetes कमांड्स को गेट करें। | -| `block-terraform` | `PreToolUse` | Terraform और OpenTofu कमांड्स को गेट करें। | -| `block-aws-cli` | `PreToolUse` | AWS CLI कमांड्स को गेट करें। | -| `block-gcloud` | `PreToolUse` | Google Cloud CLI कमांड्स को गेट करें। | -| `block-az-cli` | `PreToolUse` | Azure CLI कमांड्स को गेट करें। | -| `block-helm` | `PreToolUse` | Helm कमांड्स को गेट करें। | -| `block-gh-pipeline` | `PreToolUse` | म्यूटेटिंग GitHub CLI वर्कफ़्लो, रन, मर्ज, रिलीज़, कैश और सीक्रेट ऑपरेशन्स को गेट करें। | +| `block-failproofai-commands` | `PreToolUse`, `PermissionRequest` | **हमेशा चालू, अक्षम नहीं किया जा सकता।** हर Failproof AI CLI आह्वान, आत्म-रोक और पैकेज-प्रबंधक अनइंस्टॉल को ब्लॉक करें। | +| `block-kubectl` | `PreToolUse` | Kubernetes कमांड गेट करें। | +| `block-terraform` | `PreToolUse` | Terraform और OpenTofu कमांड गेट करें। | +| `block-aws-cli` | `PreToolUse` | AWS CLI कमांड गेट करें। | +| `block-gcloud` | `PreToolUse` | Google Cloud CLI कमांड गेट करें। | +| `block-az-cli` | `PreToolUse` | Azure CLI कमांड गेट करें। | +| `block-helm` | `PreToolUse` | Helm कमांड गेट करें। | +| `block-gh-pipeline` | `PreToolUse` | म्यूटेटिंग GitHub CLI वर्कफ़्लो, रन, मर्ज, रिलीज, कैश और सीक्रेट ऑपरेशन गेट करें। | -## गिट और डेटाबेस सुरक्षा +## Git और डेटाबेस सुरक्षा | पॉलिसी | ट्रिगर | परिणाम | | --- | --- | --- | -| `block-push-master` | `PreToolUse` | कॉन्फ़िगर की गई संरक्षित शाखाओं में सीधे पुश को ब्लॉक करें। | +| `block-push-master` | `PreToolUse` | कॉन्फ़िगर किए गए संरक्षित ब्रांचों में सीधे पुश को ब्लॉक करें। | | `block-force-push` | `PreToolUse` | फोर्स-पुश को ब्लॉक करें; `--force-with-lease` वर्तमान कार्यान्वयन द्वारा अनुमत रहता है। | -| `block-work-on-main` | `PreToolUse` | संरक्षित शाखाओं पर कमिट्स और मर्जेस को ब्लॉक करें। | +| `block-work-on-main` | `PreToolUse` | संरक्षित ब्रांचों पर कमिट और मर्ज को ब्लॉक करें। | | `warn-git-amend` | `PreToolUse` | `--amend` के साथ कमिट को फिर से लिखने से पहले चेतावनी दें। | -| `warn-git-stash-drop` | `PreToolUse` | स्टेशेस को स्थायी रूप से ड्रॉप या क्लीयर करने से पहले चेतावनी दें। | +| `warn-git-stash-drop` | `PreToolUse` | स्टैश को स्थायी रूप से हटाने या साफ करने से पहले चेतावनी दें। | | `warn-all-files-staged` | `PreToolUse` | व्यापक `git add -A`, `git add .` या `git add --all` पर चेतावनी दें। | -| `warn-destructive-sql` | `PreToolUse` | मान्यता प्राप्त डेटाबेस क्लाइंट्स के माध्यम से `WHERE` के बिना `DROP`, `TRUNCATE` और `DELETE` पर चेतावनी दें। | -| `warn-schema-alteration` | `PreToolUse` | मान्यता प्राप्त `ALTER TABLE` कॉलम और नाम बदलने के ऑपरेशन्स पर चेतावनी दें। | +| `warn-destructive-sql` | `PreToolUse` | मान्यता प्राप्त डेटाबेस क्लाइंट के माध्यम से `WHERE` के बिना `DROP`, `TRUNCATE` और `DELETE` पर चेतावनी दें। | +| `warn-schema-alteration` | `PreToolUse` | मान्यता प्राप्त `ALTER TABLE` कॉलम और पुनः नाम संचालन पर चेतावनी दें। | -## पैकेजेस, सिस्टम व्यवहार और एजेंट लूप्स +## पैकेज, सिस्टम व्यवहार और एजेंट लूप | पॉलिसी | ट्रिगर | परिणाम | | --- | --- | --- | -| `warn-package-publish` | `PreToolUse` | पैकेज रजिस्ट्रीज़ में प्रकाशित करने से पहले चेतावनी दें। | -| `warn-global-package-install` | `PreToolUse` | ग्लोबल पैकेज इंस्टॉलेशन से पहले चेतावनी दें। | -| `prefer-package-manager` | `PreToolUse` | एजेंट को अनुमत पैकेज मैनेजर का उपयोग करने का निर्देश दें। | -| `warn-large-file-write` | राइट टूल्स पर `PreToolUse` | कॉन्फ़िगर की गई फ़ाइल-साइज़ थ्रेशोल्ड के ऊपर चेतावनी दें। | -| `warn-background-process` | `PreToolUse` | डिटेच्ड या लॉन्ग-लिव्ड बैकग्राउंड-प्रोसेस पैटर्न पर चेतावनी दें। | -| `warn-repeated-tool-calls` | `PreToolUse` | तीन या अधिक समान टूल कॉल्स के बाद चेतावनी दें। | +| `warn-package-publish` | `PreToolUse` | पैकेज रजिस्ट्री में प्रकाशित करने से पहले चेतावनी दें। | +| `warn-global-package-install` | `PreToolUse` | वैश्विक पैकेज स्थापना से पहले चेतावनी दें। | +| `prefer-package-manager` | `PreToolUse` | एजेंट को अनुमत पैकेज प्रबंधक का उपयोग करने के लिए निर्देश दें। | +| `warn-large-file-write` | लेखन टूल्स पर `PreToolUse` | कॉन्फ़िगर की गई फाइल-आकार थ्रेसहोल्ड से ऊपर चेतावनी दें। | +| `warn-background-process` | `PreToolUse` | डिटेच्ड या दीर्घकालीन बैकग्राउंड-प्रोसेस पैटर्न पर चेतावनी दें। | +| `warn-repeated-tool-calls` | `PreToolUse` | तीन या अधिक समान टूल कॉल के बाद चेतावनी दें। | -## कार्य के अंत का वर्कफ़्लो +## कार्य-समाप्ति वर्कफ़्लो -ये पॉलिसियां एक हार्नेस की आवश्यकता करती हैं जो संगत `Stop` इवेंट उत्सर्जित करे। +ये पॉलिसियों को एक हार्नेस की आवश्यकता है जो संगत `Stop` इवेंट उत्सर्जित करता है। | पॉलिसी | परिणाम | | --- | --- | -| `require-commit-before-stop` | ट्रैक किया गया कार्य अपरिवर्तित रहते हुए समापन से इनकार करें। | -| `require-push-before-stop` | कमिट्स लोकल-ओनली रहते हुए समापन से इनकार करें। | -| `require-pr-before-stop` | वर्तमान शाखा के लिए पुल रिक्वेस्ट की आवश्यकता है। | -| `require-no-conflicts-before-stop` | कॉन्फ़िगर की गई बेस शाखा के खिलाफ क्लीन मर्ज की आवश्यकता है। | -| `require-ci-green-before-stop` | वर्तमान-HEAD CI चेक्स के सफलतापूर्वक पूर्ण होने की आवश्यकता है। | +| `require-commit-before-stop` | ट्रैक किए गए कार्य के साथ पूर्ण होने से इनकार करें जो अनकमिटेड रहते हैं। | +| `require-push-before-stop` | कमिट के साथ पूर्ण होने से इनकार करें जो केवल स्थानीय रहते हैं। | +| `require-pr-before-stop` | वर्तमान ब्रांच के लिए एक पुल अनुरोध की आवश्यकता है। | +| `require-no-conflicts-before-stop` | कॉन्फ़िगर की गई बेस ब्रांच के विरुद्ध स्वच्छ मर्ज की आवश्यकता है। | +| `require-ci-green-before-stop` | वर्तमान-HEAD CI चेक को सफलतापूर्वक पूर्ण करने की आवश्यकता है। | ## पैरामीटर संदर्भ -चयनित स्कोप के `policyParams` ऑब्जेक्ट के तहत पैरामीटर कॉन्फ़िगर करें। प्रकार प्रत्येक पॉलिसी द्वारा मान्य किए जाते हैं। +चयनित स्कोप के `policyParams` ऑब्जेक्ट के तहत पैरामीटर कॉन्फ़िगर करें। प्रकारों को प्रत्येक पॉलिसी द्वारा मान्य किया जाता है। | पॉलिसी | पैरामीटर | प्रकार और डिफ़ॉल्ट | | --- | --- | --- | @@ -100,7 +100,7 @@ block-force-push | `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | | `block-sudo` | `allowPatterns` | `string[]`, `[]` | | `block-rm-rf` | `allowPaths` | `string[]`, `[]` | -| इंफ्रास्ट्रक्चर ब्लॉकर्स | `allowPatterns` | `string[]`, `[]` | +| बुनियादी ढांचा ब्लॉकर | `allowPatterns` | `string[]`, `[]` | | `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | | `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | | `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | @@ -125,5 +125,5 @@ block-force-push ``` - एक अनुमति पैटर्न एजेंट को जो कर सकता है उसे व्यापक करता है। फ्लीट में तैनात करने से पहले लक्ष्य हार्नेस पर सटीक टोकनाइजेशन और कमांड वेरिएंट्स का परीक्षण करें। + एक allow पैटर्न एजेंट को अधिक क्या कर सकता है यह चौड़ा करता है। लक्ष्य हार्नेस पर पूरे फ्लीट में तैनात करने से पहले सटीक टोकनाइजेशन और कमांड वेरिएंट का परीक्षण करें। \ No newline at end of file diff --git a/docs/hi/policies/failure-behavior.mdx b/docs/hi/policies/failure-behavior.mdx index 0af5f8a4..cd829497 100644 --- a/docs/hi/policies/failure-behavior.mdx +++ b/docs/hi/policies/failure-behavior.mdx @@ -1,19 +1,20 @@ --- -title: "विफलता का व्यवहार" -description: "समझें कि जब नीति मूल्यांकन या स्थानीय daemon अनुपलब्ध हो तो क्या होता है।" +--- +title: "विफलता व्यवहार" +description: "समझें कि नीति मूल्यांकन या स्थानीय डेमॉन अनुपलब्ध होने पर क्या होता है।" icon: "shield-alert" --- -Failproof AI को इस तरह डिज़ाइन किया गया है कि प्रवर्तन विफलता दृश्यमान हो, न कि जोखिम भरे काम को चुप्पी से अनुमति दी जाए। +Failproof AI इस तरह डिज़ाइन किया गया है कि प्रवर्तन विफलता दृश्यमान हो, न कि जोखिम भरे काम को मौन रूप से अनुमति देने दे। ## विफलता-बंद ब्लॉक का निदान करें - 1. **Admin → enforcement** पर जाएं और मशीन को खोलें। - 2. इसकी अंतिम जांच-इन, असाइन किया गया डिप्लॉयमेंट, और रिपोर्ट किया गया डिप्लॉयमेंट जांचें। - 3. **Observe → policy** पर जाएं और अस्वीकृत निर्णय का सेशन खोलें। - 4. पुष्टि करें कि क्या कारण daemon पहुंच, संस्करण विसंगति, या नीति को रिपोर्ट करता है। + 1. **Admin → enforcement** पर जाएं और मशीन खोलें। + 2. इसकी अंतिम चेक-इन, असाइन की गई तैनाती, और रिपोर्ट की गई तैनाती की जांच करें। + 3. **Observe → policy** पर जाएं और अस्वीकृत निर्णय का सत्र खोलें। + 4. पुष्टि करें कि क्या कारण डेमॉन पहुंचने की क्षमता, संस्करण विसंगति, या नीति स्वयं की रिपोर्ट करता है। @@ -23,21 +24,45 @@ Failproof AI को इस तरह डिज़ाइन किया गय failproofai config ``` - `failproofai config` को फिर से चलाने से पैकेज अपग्रेड के बाद daemon को अपडेट और पुनः शुरू किया जाता है। + `failproofai config` को फिर से चलाना पैकेज अपग्रेड के बाद डेमॉन को अपडेट और पुनः शुरू करता है। -`failproofaid` का उपयोग करने के लिए कॉन्फ़िगर की गई मशीन पर, daemon एकमात्र मूल्यांकनकर्ता है। यदि यह अनुपलब्ध है या इसका प्रोटोकॉल संस्करण CLI से मेल नहीं खाता है, तो हुक मूल्यांकन विफल हो जाता है। क्रिया को एक कारण के साथ अस्वीकार कर दिया जाता है जो ऑपरेटर को daemon की जांच या अपडेट करने के लिए निर्देशित करता है। +`failproofaid` का उपयोग करने के लिए कॉन्फ़िगर की गई मशीन पर, डेमॉन एकमात्र मूल्यांकनकर्ता है। यदि यह अनुपलब्ध है या इसका प्रोटोकॉल संस्करण CLI से मेल नहीं खाता है, तो हुक मूल्यांकन बंद हो जाता है। कार्रवाई को एक कारण के साथ अस्वीकार कर दिया जाता है जो ऑपरेटर को डेमॉन की जांच या अपडेट करने के लिए निर्देशित करता है। -Daemon कॉन्फ़िगरेशन से पहले, हुक नीतियों का प्रक्रिया में मूल्यांकन करते हैं। एक बार daemon कॉन्फ़िगरेशन रिकॉर्ड किए जाने के बाद, Failproof AI daemon विफल होने पर दूसरे मूल्यांकनकर्ता को चुप्पी से वापस नहीं लौटाता है। +डेमॉन कॉन्फ़िगरेशन से पहले, हुक नीतियों का प्रक्रिया में मूल्यांकन करते हैं। एक बार डेमॉन कॉन्फ़िगरेशन दर्ज हो जाने के बाद, Failproof AI जब डेमॉन विफल हो तो मौन रूप से दूसरे मूल्यांकनकर्ता को वापस नहीं करता है। ## विफलता-बंद निर्णय का जवाब दें 1. `failproofai config --status` चलाएं। -2. यदि संस्करण भिन्न हैं, तो पैकेज अपडेट करने के बाद `failproofai config` को फिर से चलाएं। -3. यदि daemon अनुपलब्ध है, तो इसकी सेवा स्थिति और स्थानीय लॉग का निरीक्षण करें। -4. केवल तभी एजेंट कार्य फिर से शुरू करें जब एक ज्ञात नीति मूल्यांकन पथ स्वस्थ हो। +2. यदि संस्करण अलग हैं, पैकेज अपडेट करने के बाद `failproofai config` को फिर से चलाएं। +3. यदि डेमॉन अनुपलब्ध है, तो इसकी सेवा स्थिति और स्थानीय लॉग का निरीक्षण करें। +4. एक ज्ञात नीति मूल्यांकन पथ स्वस्थ होने के बाद ही एजेंट कार्य फिर से शुरू करें। - अवरुद्ध क्रिया को बार-बार पुनः प्रयास न करें। विफलता-बंद प्रतिक्रिया का मतलब है कि सिस्टम यह स्थापित नहीं कर सका कि क्रिया सुरक्षित थी। - \ No newline at end of file + अवरुद्ध कार्रवाई को बार-बार फिर से प्रयास न करें। विफलता-बंद प्रतिक्रिया का मतलब है कि सिस्टम यह स्थापित नहीं कर सका कि कार्रवाई सुरक्षित थी। + + +## एक पैक लोड नहीं होगा + +एक मशीन जिसे पैक को लागू करने के लिए कहा गया था, और इसे चलाने में असमर्थ है, चुप रहने के बजाय अस्वीकार कर देती है। ट्रिगर एक **दर्ज अपेक्षा** है, कभी खाली नहीं: कोई पैक स्थापित नहीं होने वाली मशीन चुप रहती है, जबकि एक पैक जो घोषित है और समाधान नहीं होगा — या जो अपने मैनिफेस्ट से कम पंजीकृत करता है — अस्वीकार कर देता है। + +यह अस्वीकार **संकीर्ण** है, अनुपलब्ध डेमॉन के विपरीत। एक डेमॉन जो नहीं पहुंचा जा सकता वह कोई मूल्यांकन नहीं हुआ, इसलिए कुछ भी सुरक्षित ज्ञात नहीं है। एक पैक जो लोड नहीं होगा में गायब सुरक्षा की एक गणनीय सेट है, क्योंकि हर घोषित नीति अपना स्वयं का `match` रखती है — इसलिए यह केवल उन नीतियों द्वारा कवर की गई घटनाओं और उपकरणों को अस्वीकार करता है, और बाकी सब कुछ आगे बढ़ता है। + +यह निम्नलिखित के लिए नहीं चलता: + +- एक `observe` पैक, जो निर्माण द्वारा मूल्यांकन और त्याग करता है +- नीतियां जो आपने कभी नहीं लीं, या स्पष्ट रूप से बंद कीं +- एक पैक जो लोडर को कभी नहीं मिला, जहां "कोई पंजीकरण नहीं" एक जानबूझकर छोड़ से अलग नहीं किया जा सकता +- एक सक्रिय सत्र विराम +- एक लोड टाइमआउट, जो क्षणिक है — एक धीमी डिस्क का क्षण तब तक अस्वीकार नहीं करना चाहिए जब तक कोई मानव हस्तक्षेप न करे + +`UserPromptSubmit` अस्वीकार करने के बजाय **निर्देश** देता है, चाहे लापता नीति ने क्या घोषित किया हो। एक व्यापक अस्वीकार इसे साथ ले जाएगा और आपको उस एजेंट से बाहर कर देगा जो समस्या को ठीक कर सकता था। + +### क्या करना है + +```bash +failproofai pack list +``` + +यह किसी भी स्थापित पैक का नाम रखता है जो लोड नहीं होगा, कहता है कि क्यों, और गैर-शून्य के साथ निकलता है। फिर इसे फिर से स्थापित करें (`failproofai pack add `) या हटा दें (`failproofai pack remove `) — इसे हटाने से अपेक्षा वापस ली जाती है, और अस्वीकार इसके साथ रुक जाता है। \ No newline at end of file diff --git a/docs/hi/policies/packs.mdx b/docs/hi/policies/packs.mdx new file mode 100644 index 00000000..1aac1420 --- /dev/null +++ b/docs/hi/policies/packs.mdx @@ -0,0 +1,110 @@ +--- +title: "Policy packs" +description: "GitHub रिलीज़ के रूप में प्रकाशित नीतियों का एक सेट इंस्टॉल करें, और यह क्या लागू करता है इसे प्रबंधित करें।" +icon: "package" +--- + +एक pack GitHub रिलीज़ के रूप में प्रकाशित नीतियों का एक सेट है। एक कमांड इसे इंस्टॉल करता है, रिलीज़ के अपने चेकसम को कुछ भी चलाने से पहले सत्यापित किया जाता है, और डाइजेस्ट रिकॉर्ड किया जाता है ताकि pack आपकी मशीन के बाद बदल न सके। + +## Failproof AI नीतियों को इंस्टॉल करें + +```bash +failproofai pack add core +``` + +यह पैकेज के अंदर की कॉपी से प्रकाशित सेट को इंस्टॉल करता है — इसलिए इसे नेटवर्क की आवश्यकता नहीं है और यह प्रॉक्सी के पीछे विफल नहीं हो सकता। इसका एक हिस्सा लें: + +```bash +failproofai pack add core --policy block-rm-rf # एक, या अल्पविराम से अलग कुछ +failproofai pack add core --category dangerous-commands # एक पूरी श्रेणी +failproofai pack add core --all # इसमें सब कुछ +``` + +`failproofai pack list` pack द्वारा प्रदान की गई हर श्रेणी का नाम देता है। + +## इंस्टॉल करने से पहले एक pack में क्या है यह देखें + +```bash +failproofai pack list acme/support-agent +``` + +pack द्वारा की जाने वाली हर नीति को सूचीबद्ध करता है, श्रेणी द्वारा समूहीकृत, यह चिह्नित करता है कि इसके लेखक डिफ़ॉल्ट रूप से कौन से को चालू करते हैं और कौन से opt-in हैं। यह **केवल manifest को** पढ़ता है — entry artifact कभी डाउनलोड नहीं किया जाता और कभी imported नहीं किया जाता, इसलिए एक अपरिचित pack को देखना अपरिचित कोड को नहीं चला सकता। manifest को अभी भी रिलीज़ के अपने `SHA256SUMS` के विरुद्ध जांचा जाता है, इसलिए आप जो पढ़ रहे हैं वह वही है जो इंस्टॉल होगा। + +`failproofai pack list` कोई स्रोत के बिना यहां पहले से इंस्टॉल किए गए packs को सूचीबद्ध करता है। + +## किसी और के pack को इंस्टॉल करें + +```bash +failproofai pack add acme/support-agent +``` + +इनमें से कोई भी काम करता है — जो भी आपके पास है वह पेस्ट करें: + +| स्रोत | परिणाम | +| --- | --- | +| `acme/support-agent` | नवीनतम रिलीज़, **pinned** सटीक टैग के लिए जो इसे हल किया | +| `acme/support-agent@v2.1.0` | वह रिलीज़ | +| `github:acme/support-agent@v2.1.0` | वही, स्पष्ट रूप से लिखा | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | वही, ब्राउज़र से कॉपी किया | + +कोई टैग नाम नहीं देने से नवीनतम रिलीज़ इंस्टॉल होता है **और इसे pin किया जाता है**, फिर आपको यह बताता है कि किस टैग को चुना। जो कुछ भी रिकॉर्ड किया जाता है वह हमेशा ठीक एक रिलीज़ का नाम देता है, इसलिए एक reinstall drift नहीं हो सकता। + +## एक pack का हिस्सा लें + +डिफ़ॉल्ट रूप से आप pack के **अपने** defaults प्राप्त करते हैं — जिन नीतियों को इसके लेखक ने निरीक्षण के साथ चालू करने के लिए सुरक्षित चिह्नित किया है — इसमें सब कुछ नहीं। + +```bash +failproofai pack add acme/support-agent --category billing,git +failproofai pack add acme/support-agent --policy block-refunds +failproofai pack add acme/support-agent --all +``` + +`--category` और `--policy` एक union के रूप में संयोजित होते हैं (`--only` को `--policy` का पर्यायवाची माना जाता है)। एक नए संस्करण में फिर से जोड़ने से आपने जो चुना है वह रहता है न कि बाकी को वापस चालू करना। + +## प्रबंधित करें कि क्या चालू है + +```bash +failproofai policies # एक सूची में हर स्रोत, packs सहित +failproofai pack list # केवल packs, श्रेणी द्वारा समूहीकृत +failproofai policies --uninstall block-refunds # एक pack policy को बंद करें +failproofai policies --install block-refunds # और वापस चालू करें +failproofai pack remove acme/support-agent +``` + +एक bare name का अर्थ है **builtin** जब उस नाम द्वारा एक मौजूद हो। जब आपको चाहिए तो एक pack की कॉपी को स्पष्ट रूप से नाम दें: + +```bash +failproofai policies --uninstall acme/support-agent:block-refunds +``` + + +यदि एक pack एक नीति भेजता है जिसका नाम भी एक **enabled builtin** है, तो builtin चलता है और pack की कॉपी को छोड़ दिया जाता है — अन्यथा एक ही guard का दो बार मूल्यांकन किया जाएगा। इसके बजाय pack की कॉपी का उपयोग करने के लिए builtin को बंद करें। + + +## Failproof AI नीतियां कहां से आती हैं + +`core` npm पैकेज में vendored कॉपी को पढ़ता है। एक ही सेट GitHub रिलीज़ के रूप में प्रकाशित होता है, जो आप इंस्टॉल करते हैं यदि आप एक विशिष्ट संस्करण चाहते हैं: + +```bash +failproofai pack add core # इस पैकेज से, कोई नेटवर्क नहीं +failproofai pack add FailproofAI/policies # एक ही सेट, इसकी GitHub रिलीज़ से +``` + +## अखंडता क्या करती है और नहीं करती है + +`SHA256SUMS` artifact के समान रिलीज़ में शिप होता है, इसलिए यह **एक हस्ताक्षर नहीं है** और प्रकाशक के बारे में कुछ भी साबित नहीं करता। जो यह साबित करता है वह यह है कि bytes वही हैं जो उस रिलीज़ ने प्रकाशित किए — और क्योंकि डाइजेस्ट को pack जोड़ते समय रिकॉर्ड किया जाता है और हर import से पहले फिर से सत्यापित किया जाता है, एक pack आपकी मशीन के बाद नहीं बदल सकता। एक repository जो retags करता है या एक asset को बदलता है वह चुप से कुछ और चलाने के बजाय लोड करना बंद कर देता है। + +इंस्टॉल समय पर pack को भी **एक बार imported** किया जाता है और अपने manifest के विरुद्ध जांचा जाता है। एक pack जिसके artifact को parse नहीं किया जा सकता, या जो अपनी घोषणा के अलावा कुछ और register करता है, को activate होने के बजाय इंस्टॉल होने से पहले reject किया जाता है — अपने अगले tool call पर विफल होने के बजाय। + +## जब एक pack load नहीं होगा + +एक pack जिसे यह मशीन लागू करने के लिए कहा गया था और नहीं चला सकता **उन events को deny करता है** जिनकी इसकी missing नीतियों ने coverage दी, बजाय इसके कि उन्हें चुप से allow किया जाए। [Failure behavior](/hi/policies/failure-behavior) देखें। `failproofai pack list` उस state में किसी भी pack का नाम देता है और non-zero के साथ exit करता है। + +## Offline और mirrors + +| Variable | प्रभाव | +| --- | --- | +| `FAILPROOFAI_NO_DOWNLOAD=1` | fetch करने से इनकार करता है; पहले से इंस्टॉल किए गए packs लागू रहते हैं | +| `FAILPROOFAI_PACK_BASE_URL` | pack fetching को `github.com` के बजाय एक mirror की ओर इंगित करता है | + +अपना खुद का pack प्रकाशित करना: [Publish a pack](/hi/policies/publish-a-pack) देखें। \ No newline at end of file diff --git a/docs/hi/policies/publish-a-pack.mdx b/docs/hi/policies/publish-a-pack.mdx new file mode 100644 index 00000000..02f62f44 --- /dev/null +++ b/docs/hi/policies/publish-a-pack.mdx @@ -0,0 +1,92 @@ +--- +--- +title: "एक पैक प्रकाशित करें" +description: "GitHub रिलीज़ के रूप में अपनी नीतियों को शिप करें जिन्हें कोई भी इंस्टॉल कर सके।" +icon: "upload" +--- + +एक पैक GitHub रिलीज़ से जुड़ी तीन फाइलें हैं। `failproofai pack build` एक नीति फाइल से सभी तीन को लिखता है जो आपके पास पहले से है। + +## 1. नीतियां लिखें + +एक फाइल, किसी भी कस्टम नीति के समान API का उपयोग करते हुए। एक पैक के लिए दो अतिरिक्त फील्ड महत्वपूर्ण हैं: + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-refunds", + description: "Refunds above the approved limit need a human", + category: "Billing", // groups it, and is what --category selects on + defaultEnabled: true, // switched on by a plain `pack add` + match: { events: ["PreToolUse"], tools: ["Bash"] }, + fn: async (ctx) => + String(ctx.toolInput?.command ?? "").includes("refund") + ? deny("Refunds need a human. Ask before running this.") + : allow(), +}); +``` + +जब आप इसे छोड़ते हैं तो `defaultEnabled` डिफ़ॉल्ट रूप से **false** होता है। एक सादा `failproofai pack add` केवल वह सक्षम करता है जिसे आपने चिह्नित किया है — किसी अजनबी की हर नीति को निरीक्षित तरीके से इंस्टॉल करना एक ऐसा निर्णय नहीं है जो इंस्टॉलर अपने उपयोगकर्ता के लिए ले सकता है। + + +प्रविष्टि **एक आत्मनिर्भर फाइल** होनी चाहिए। केवल प्रविष्टि ही डाइजेस्ट-पिन की गई है, इसलिए एक पैक जो स्थानीय फाइलों को आयात करता है वह ईमानदारी से यह दावा नहीं कर सकता कि डाइजेस्ट उस सब को कवर करता है जो चलता है। पहले बंडल करें (`esbuild`, `bun build`, `rollup`) और बंडल से पैक बनाएं — `pack build` स्थानीय आयात को अस्वीकार करता है बजाय उस प्रतिश्रुति को शिप करने के जिसे वह रख नहीं सकता। + + +## 2. रिलीज़ संपत्ति बनाएं + +```bash +failproofai pack build ./policies.mjs \ + --id acme/support-agent \ + --version 1.0.0 \ + --out ./dist-pack +``` + +यह तीन फाइलें लिखता है, और पहले **लोडर के अपने नियमों** के साथ हर नीति को मान्य करता है — तो एक पैक जो कभी इंस्टॉल नहीं हो सकता वह यहां विफल होता है, जहां आप इसे ठीक कर सकते हैं: + +| फाइल | यह क्या है | +| --- | --- | +| `failproofai-pack.json` | मेनिफेस्ट: id, version, effect, और प्रति नीति एक प्रविष्टि | +| `failproofai-pack.mjs` | आपकी प्रविष्टि, ज्यों की त्यों | +| `SHA256SUMS` | ` ` अन्य दोनों के लिए | + +बिल्ड समय पर अस्वीकृत: एक id जो `publisher/name` नहीं है, `/` युक्त नीति का नाम, `alwaysOn` की घोषणा करने वाली नीति, गायब `description`, `category` या `match`, एक प्रविष्टि जो कुछ भी रजिस्टर नहीं करती, और एक प्रविष्टि जो स्थानीय फाइलों को आयात करती है। + +## 3. उन्हें एक रिलीज़ से जोड़ें + +रिलीज़ को उसी संस्करण के साथ टैग करें जو आपने बनाया था, और तीनों फाइलों को रिलीज़ संपत्ति के रूप में जोड़ें: + +```bash +gh release create 1.0.0 \ + ./dist-pack/failproofai-pack.json \ + ./dist-pack/failproofai-pack.mjs \ + ./dist-pack/SHA256SUMS +``` + +अब कोई भी इसे इंस्टॉल कर सकता है: + +```bash +failproofai pack add acme/support-agent +``` + +संपत्ति के नाम निश्चित हैं — वे वह हैं जो एक उपभोक्ता की CLI अपने URLs से बनाती है, कोई API कॉल नहीं और कोई खोज नहीं। + +## एक नया संस्करण शिप करना + +नए `--version` के साथ बनाएं, एक नई रिलीज़ टैग करें, तीनों संपत्ति को फिर से जोड़ें। उपभोक्ता एक ही `pack add` चलाते हैं और जो भी सबसेट उन्होंने चुना था उसे रखते हैं; एक नीति जिसे वे बंद कर गए थे वह अपग्रेड में बंद रहती है। + +एक नीति के **name** को बदलना एक विघ्नकारी परिवर्तन है: एक मशीन जिसने इसे बंद कर दिया था वह एक नाम बंद कर रही है जो अब मौजूद नहीं है, और नया नाम जो कुछ भी `defaultEnabled` कहता है उस पर आता है। + +## आपके उपयोगकर्ता क्या विश्वास कर रहे हैं + +`SHA256SUMS` उसी रिलीज़ में है जो कलाकृति है, इसलिए यह साबित करता है कि बाइट्स वे हैं जो आपने प्रकाशित किए — न कि आप कौन हैं। जो कोई भी रिपॉजिटरी में लिख सकता है वह दोनों फाइलें लिख सकता है। आपके उपयोगकर्ताओं की सुरक्षा यह है कि डाइजेस्ट तब पिन किया जाता है जब वे इंस्टॉल करते हैं, इसलिए जो आपने शिप किया वह उनके बाद नहीं बदल सकता। + +एक रिपॉजिटरी से प्रकाशित करें जिसके लिखने की पहुंच आप नियंत्रित करते हैं, और एक पैक रिलीज़ को एक पैकेज प्रकाशित करने जैसे मानें। + +## लागू करने से पहले अवलोकन करें + +एक मेनिफेस्ट `"effect": "observe"` घोषित कर सकता है। वे नीतियां चलती हैं और उनके निर्णय **रिकॉर्ड किए जाते हैं और त्याग दिए जाते हैं** — कुछ भी ब्लॉक नहीं है। यह एक नए नियम को वास्तविक ट्रैफिक के खिलाफ मापने का तरीका है इससे पहले कि यह किसी के काम को बाधित कर सके। + +```json +{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +``` \ No newline at end of file diff --git a/docs/hi/reference/failproof-cli.mdx b/docs/hi/reference/failproof-cli.mdx index 7b480892..3a085b1a 100644 --- a/docs/hi/reference/failproof-cli.mdx +++ b/docs/hi/reference/failproof-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof AI CLI" -description: "हुक इंस्टॉल करें, स्थानीय नीतियों का प्रबंधन करें, क्लाउड से कनेक्ट करें, और स्थानीय डेमन को चलाएं।" +description: "हुक इंस्टॉल करें, स्थानीय नीतियों को प्रबंधित करें, क्लाउड कनेक्ट करें, और स्थानीय डेमॉन संचालित करें।" icon: "terminal" --- -`npm install -g failproofai` के साथ स्थानीय CLI इंस्टॉल करें। इसे बिना किसी तर्क के चलाएं ताकि स्थानीय नीति डैशबोर्ड खुल जाए। +`npm install -g failproofai` के साथ स्थानीय CLI इंस्टॉल करें। इसे बिना किसी आर्गुमेंट के चलाएं ताकि स्थानीय नीति डैशबोर्ड खुले। -पैकेज के लिए Node.js 20.9 या नए संस्करण की आवश्यकता है। Bun 1.3 या नए संस्करण विकास और स्रोत इंस्टॉल के लिए समर्थित हैं। `failproofai configure` और `failproofai setup`, `failproofai config` के लिए उपनाम हैं; `failproofai p`, `failproofai policies` के लिए एक उपनाम है। +पैकेज को Node.js 20.9 या नए संस्करण की आवश्यकता है। Bun 1.3 या नए संस्करण विकास और स्रोत इंस्टॉल के लिए समर्थित हैं। `failproofai configure` और `failproofai setup` के लिए `failproofai config` के उपनाम हैं; `failproofai p` के लिए `failproofai policies` का उपनाम है। ## एक मशीन सेट अप करें @@ -20,64 +20,69 @@ failproofai policies --install failproofai config --status ``` -बिना किसी तर्क के `failproofai` चलाएं ताकि स्थानीय नीति डैशबोर्ड खुल जाए। +स्थानीय नीति डैशबोर्ड खोलने के लिए बिना किसी आर्गुमेंट के `failproofai` चलाएं। | कमांड | परिणाम | | --- | --- | -| `failproofai config` | इंटरैक्टिव मशीन सेटअप चलाएं | -| `failproofai config --connect --token ` | क्लाउड इंजेशन और नीति डिलीवरी से कनेक्ट करें | -| `failproofai config --status` | कनेक्शन, डेमन, डिलीवरी और पॉज़ स्थिति दिखाएं | -| `failproofai policies` | बिल्ट-इन और कस्टम नीतियों की सूची बनाएं | +| `failproofai config` | इंटरएक्टिव मशीन सेटअप चलाएं | +| `failproofai config --connect --token ` | क्लाउड इनजेशन और नीति डिलीवरी को कनेक्ट करें | +| `failproofai config --status` | कनेक्शन, डेमॉन, डिलीवरी और पॉज स्थिति दिखाएं | +| `failproofai policies` | बिल्ट-इन, कस्टम, कन्वेंशन, पैक और क्लाउड-प्रबंधित नीतियां सूचीबद्ध करें | | `failproofai policies --install` | हुक इंस्टॉल करें और नीतियों को सक्षम करें | -| `failproofai policy add ` | एक बिल्ट-इन नीति सक्षम करें | -| `failproofai policy remove ` | एक बिल्ट-इन नीति अक्षम करें | -| `failproofai policies --uninstall` | नीतियों को अक्षम करें या हार्नेस हुक हटाएं | +| `failproofai policy add ` | एक नीति सक्षम करें — एक बिल्ट-इन या इंस्टॉल किए गए पैक से `:` | +| `failproofai policy remove ` | एक नीति को अक्षम करें, समान नामकरण | +| `failproofai policies --uninstall` | नीतियों को अक्षम करें या हार्नेस हुक निकालें | +| `failproofai pack list` | इंस्टॉल किए गए नीति पैक और प्रत्येक एक द्वारा वहन की गई प्रत्येक नीति सूचीबद्ध करें | +| `failproofai pack add ` | GitHub रिलीज़ से एक नीति पैक इंस्टॉल करें; कोई टैग नहीं सबसे नया लेता है और इसे पिन करता है | +| `failproofai pack add --bundled` | बिल्ट-इन नीतियों को एक पैक के रूप में इंस्टॉल करें, इस पैकेज से, कोई नेटवर्क नहीं | +| `failproofai pack build ` | अपने स्वयं के पैक के लिए तीन रिलीज़ एसेट बनाएं | +| `failproofai pack remove ` | एक इंस्टॉल किए गए पैक को निष्क्रिय करें | | `failproofai audit` | स्थानीय एजेंट इतिहास स्कैन करें और स्थानीय ऑडिट दृश्य खोलें | -| `failproofai audit --schedule [days] --email
` | आवर्ती स्थानीय स्कैन शेड्यूल करें और उनके निष्कर्षों को ईमेल करें | -| `failproofai audit --status` | रिपोर्ट पता, अंतराल और अगला निर्धारित स्कैन दिखाएं | -| `failproofai audit --no-schedule` | आवर्ती स्कैन रोकें ऑडिट इतिहास हटाए बिना | -| `failproofai harness list` | अतिरिक्त कैप्चर पाथ की सूची बनाएं | -| `failproofai flush --wait` | वर्तमान इवेंट स्पूल डिलीवर करें | -| `failproofai backfill --since 30d` | पहले से पास किए गए इतिहास को फिर से पढ़ें | -| `failproofai config --pause [duration]` | एक स्थानीय सत्र को डिफॉल्ट रूप से 30 मिनट के लिए पॉज़ करें, 8 घंटे तक | -| `failproofai config --resume` | एक पॉज़ किए गए स्थानीय सत्र को फिर से शुरू करें; सभी पॉज़ को स्पष्ट करने के लिए `--all` जोड़ें | -| `failproofai update` | पैकेज माइग्रेशन पूरा करें और डेमन को अपडेट करें | -| `failproofai migrate --dry-run` | लंबित होम-लेआउट माइग्रेशन का पूर्वावलोकन या चलाएं | -| `failproofai uninstall` | हुक और डेमन को हटाएं पैकेज को हटाने से पहले | +| `failproofai audit --schedule [days] --email
` | आवर्ती स्थानीय स्कैन शेड्यूल करें और उनके निष्कर्ष ईमेल करें | +| `failproofai audit --status` | रिपोर्ट पता, अंतराल और अगली अनुसूचित स्कैन दिखाएं | +| `failproofai audit --no-schedule` | आवर्ती स्कैन को बंद करें ऑडिट इतिहास को हटाए बिना | +| `failproofai harness list` | अतिरिक्त कैप्चर पाथ सूचीबद्ध करें | +| `failproofai flush --wait` | वर्तमान ईवेंट स्पूल डिलीवर करें | +| `failproofai backfill --since 30d` | पहले पास किए गए इतिहास को फिर से पढ़ें | +| `failproofai config --pause [duration]` | एक स्थानीय सेशन को 30 मिनट के लिए डिफ़ॉल्ट रूप से पॉज करें, 8 घंटे तक | +| `failproofai config --resume` | एक पॉज किए गए स्थानीय सेशन को फिर से शुरू करें; सभी पॉज को साफ़ करने के लिए `--all` जोड़ें | +| `failproofai update` | पैकेज माइग्रेशन समाप्त करें और डेमॉन अपडेट करें | +| `failproofai migrate --dry-run` | लंबित होम-लेआउट माइग्रेशन को प्रिव्यू या चलाएं | +| `failproofai uninstall` | पैकेज हटाने से पहले हुक और डेमॉन निकालें | | `failproofai --version` | इंस्टॉल किए गए पैकेज संस्करण को प्रिंट करें | | `failproofai --help` | कमांड और वैश्विक उपयोग दिखाएं | -## कॉन्फ़िगरेशन फ़्लैग +## कॉन्फ़िगरेशन फ्लैग -| फ़्लैग | उपयोग | +| फ्लैग | उपयोग | | --- | --- | -| `--connect --token ` | गैर-इंटरैक्टिव रूप से कनेक्ट करें | +| `--connect --token ` | गैर-इंटरएक्टिव रूप से कनेक्ट करें | | `--machine-id ` | स्थिर मशीन ID सेट करें | | `--machine-label ` | डैशबोर्ड लेबल सेट या बदलें | | `--no-transcripts` | ट्रांसक्रिप्ट सामग्री के बिना निर्णय भेजें | -| `--disconnect` | क्लाउड नीति पुल और इवेंट डिलीवरी रोकें | +| `--disconnect` | क्लाउड नीति पुल और ईवेंट डिलीवरी बंद करें | | `--status` | वर्तमान मशीन स्थिति दिखाएं | -| `--pause [duration]` | वर्तमान निर्देशिका में नवीनतम सत्र को पॉज़ करें; सेकंड, मिनट, या घंटे स्वीकार करता है और डिफॉल्ट रूप से 30 मिनट है | -| `--resume` | मिलान करने वाले पॉज़ को जल्दी समाप्त करें | -| `--session ` | पॉज़ या रिज़्यूम के लिए एक स्पष्ट सत्र लक्ष्य करें | -| `--all` | `--resume` के साथ, हर सक्रिय पॉज़ को समाप्त करें | +| `--pause [duration]` | वर्तमान निर्देशिका में सबसे नए सेशन को पॉज करें; सेकंड, मिनट या घंटे स्वीकार करता है और 30 मिनट के लिए डिफ़ॉल्ट | +| `--resume` | एक मेल खाते वाले पॉज को जल्दी समाप्त करें | +| `--session ` | पॉज या रिज्यूम के लिए एक स्पष्ट सेशन को लक्ष्य करें | +| `--all` | `--resume` के साथ, हर सक्रिय पॉज को समाप्त करें | -स्थानीय पॉज़ बिल्ट-इन, कस्टम और सम्मेलन नीतियों को एक सत्र के लिए निलंबित करते हैं। वे हमेशा समाप्त होते हैं और क्लाउड-प्रबंधित नीतियों को अक्षम नहीं करते हैं। `block-self-pause` एक साधन एजेंट को इस एस्केप हैच का स्वयं उपयोग करने से रोकता है। +स्थानीय पॉज एक सेशन के लिए बिल्ट-इन, कस्टम, कन्वेंशन और पैक नीतियों को निलंबित करते हैं। वे हमेशा समाप्त हो जाते हैं और क्लाउड-प्रबंधित नीतियों को अक्षम नहीं करते। `block-failproofai-commands` — जो हमेशा चालू है और स्वयं को अक्षम या पॉज नहीं किया जा सकता — एक इंस्ट्रूमेंटेड एजेंट को इस एस्केप हैच का उपयोग करने से रोकता है। -## नीति फ़्लैग +## नीति फ्लैग -| फ़्लैग | उपयोग | +| फ्लैग | उपयोग | | --- | --- | | `--install`, `-i` | नीतियों को सक्षम करें और हार्नेस हुक इंस्टॉल करें | -| `--uninstall`, `-u` | नीतियों को अक्षम करें या हुक हटाएं | +| `--uninstall`, `-u` | नीतियों को अक्षम करें या हुक निकालें | | `--cli ` | एक या अधिक समर्थित हार्नेस को लक्ष्य करें | | `--scope user\|project\|local\|all` | कॉन्फ़िगरेशन स्कोप चुनें; `all` अनइंस्टॉल के लिए है | | `--beta` | बीटा नीतियों को शामिल करें | -| `--custom`, `-c ` | एक कस्टम नीति फ़ाइल को मान्य करें और लोड करें; दोहराए जा सकते हैं | +| `--custom`, `-c ` | कस्टम नीति फ़ाइल को मान्य करें और लोड करें; दोहराया जा सकता है | -## डिलीवरी और रखरखाव फ़्लैग +## डिलीवरी और रखरखाव फ्लैग -| कमांड | फ़्लैग | +| कमांड | फ्लैग | | --- | --- | | `backfill` | `--since <30d\|6m\|YYYY-MM-DD>`, `--dry-run` | | `flush` | `--wait`, `--timeout ` | @@ -85,7 +90,7 @@ failproofai config --status | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` को `npm install -g failproofai@latest` के बाद चलाया जाना चाहिए; यह होम-लेआउट माइग्रेशन करता है, मिलान करने वाले डेमन बाइनरी को इंस्टॉल करता है, और सेवा को पुनः शुरू करता है। `--no-daemon` केवल लेआउट माइग्रेशन करता है। +`npm install -g failproofai@latest` के बाद `failproofai update` चलाया जाना चाहिए; यह होम-लेआउट माइग्रेशन करता है, मेल खाते वाले डेमॉन बाइनरी को इंस्टॉल करता है, और सेवा को पुनः शुरू करता है। `--no-daemon` केवल लेआउट माइग्रेशन करता है। ## हार्नेस पाथ @@ -95,11 +100,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -समर्थित हार्नेस नाम `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, और `goose` हैं। +समर्थित हार्नेस नाम `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` और `goose` हैं। -लेबल व्युत्पन्न एजेंट ID को नेमस्पेस करते हैं जब दो रूट एक ही प्रोजेक्ट की प्रतियां रखते हैं। ओवरलैपिंग रूट और डुप्लिकेट लेबल को अस्वीकार किया जाता है ताकि डुप्लिकेट संग्रह या कर्सर भ्रष्टाचार को रोका जा सके। अतिरिक्त-पाथ कॉन्फ़िगरेशन डेमन पुनरारंभ के बिना पुनः लोड होता है। +लेबल व्युत्पन्न एजेंट आईडी को नामस्थान करते हैं जब दो रूट एक ही प्रोजेक्ट की प्रतियां रखते हैं। डुप्लिकेट संग्रह या कर्सर भ्रष्टाचार को रोकने के लिए ओवरलैपिंग रूट और डुप्लिकेट लेबल को अस्वीकार किया जाता है। अतिरिक्त-पाथ कॉन्फ़िगरेशन डेमॉन रीस्टार्ट के बिना पुनः लोड होता है। -कंटेनर पर्यावरण फ़ाइल-कॉन्फ़िगर किए गए अतिरिक्त पाथों को `FAILPROOFAI__EXTRA_PATHS` नामक अल्पविराम-अलग किए गए चर से बदल सकते हैं, उदाहरण के लिए: +कंटेनर वातावरण फ़ाइल-कॉन्फ़िगर किए गए अतिरिक्त पाथ को एक अल्पविराम-अलग किए गए वेरिएबल से बदल सकते हैं जिसे `FAILPROOFAI__EXTRA_PATHS` कहा जाता है, उदाहरण के लिए: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -109,24 +114,26 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl स्थायी मशीन व्यवहार के लिए कॉन्फ़िगरेशन फ़ाइलों का उपयोग करें। पर्यावरण चर कंटेनर, परीक्षण और एक प्रक्रिया के लिए सबसे उपयोगी हैं। -| चर | उपयोग | +| वेरिएबल | उपयोग | | --- | --- | | `FAILPROOFAI_HOME` | संपूर्ण `~/.failproofai` लेआउट को स्थानांतरित करें | -| `FAILPROOFAI_LOG_LEVEL` | स्थानीय लॉगिंग वर्बोसिटी सेट करें | -| `FAILPROOFAI_HOOK_LOG_FILE` | हुक डायग्नोस्टिक्स को चयनित फ़ाइल में लिखें | +| `FAILPROOFAI_LOG_LEVEL` | स्थानीय लॉगिंग विस्तार सेट करें | +| `FAILPROOFAI_HOOK_LOG_FILE` | हुक डायग्नोस्टिक्स को एक चयनित फ़ाइल में लिखें | | `FAILPROOFAI_TELEMETRY_DISABLED=1` | इस प्रक्रिया के लिए अनाम टेलीमेट्री अक्षम करें | -| `FAILPROOFAI_NO_FIRST_RUN=1` | इंटरैक्टिव पहली बार सेटअप छोड़ें | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | पोस्ट-सेटअप स्थानीय ऑडिट छोड़ें | -| `FAILPROOFAI_LLM_BASE_URL` | LLM नीतियों द्वारा उपयोग किए गए OpenAI-संगत एंडपॉइंट को ओवरराइड करें | -| `FAILPROOFAI_LLM_API_KEY` | LLM नीतियों द्वारा उपयोग किए गए API कुंजी की आपूर्ति करें | -| `FAILPROOFAI_LLM_MODEL` | LLM नीतियों द्वारा उपयोग किए गए मॉडल का चयन करें | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | कस्टम नीति मॉड्यूल लोडिंग को बाउंड करें | +| `FAILPROOFAI_NO_FIRST_RUN=1` | इंटरएक्टिव पहली बार चलाएं सेटअप छोड़ें | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | सेटअप के बाद स्थानीय ऑडिट छोड़ें | +| `FAILPROOFAI_LLM_BASE_URL` | LLM नीतियों द्वारा उपयोग किए जाने वाले OpenAI-संगत एंडपॉइंट को ओवरराइड करें | +| `FAILPROOFAI_LLM_API_KEY` | LLM नीतियों द्वारा उपयोग किया जाने वाला API कुंजी प्रदान करें | +| `FAILPROOFAI_LLM_MODEL` | LLM नीतियों द्वारा उपयोग किए गए मॉडल को चुनें | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | कस्टम नीति मॉड्यूल लोडिंग को बाध्य करें | +| `FAILPROOFAI_NO_DOWNLOAD=1` | पैक और डेमॉन बाइनरी लाने से इनकार करें; जो इंस्टॉल है वह लागू रहता है | +| `FAILPROOFAI_PACK_BASE_URL` | `github.com` के बजाय मिरर से पैक लाएं | | `FAILPROOFAI__EXTRA_PATHS` | एक हार्नेस के लिए कॉन्फ़िगर किए गए अतिरिक्त कैप्चर पाथ को बदलें | | `NO_COLOR` | रंगीन टर्मिनल आउटपुट अक्षम करें | -एजेंट-विशिष्ट होम चर जैसे `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME`, और `OPENCLAW_HOME` ओवरराइड करते हैं कि Failproof AI उस हार्नेस के लिए स्थानीय सत्र खोज करता है। +एजेंट-विशिष्ट होम वेरिएबल जैसे `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` और `OPENCLAW_HOME` ओवरराइड करते हैं कि Failproof AI उस हार्नेस के लिए स्थानीय सेशन कहां खोजता है। -## एक मशीन को सुरक्षित रूप से पॉज़ या निकालें +## एक मशीन को सुरक्षित रूप से पॉज या निकालें ```bash failproofai config --pause @@ -134,9 +141,9 @@ failproofai config --status failproofai config --resume ``` -स्थानीय सत्र पॉज़ क्लाउड-प्रबंधित नीतियों को अक्षम नहीं करता है। जब रोलआउट ही समस्या है तो क्लाउड प्रवर्तन वर्कफ़्लो के माध्यम से क्लाउड परिनियोजन को पुनः स्थापित करें। +एक स्थानीय सेशन पॉज क्लाउड-प्रबंधित नीतियों को अक्षम नहीं करता। जब रोलआउट स्वयं समस्या है तो क्लाउड एन्फोर्समेंट वर्कफ़्लो के माध्यम से क्लाउड तैनाती को पुनः स्थापित करें। -npm पैकेज को हटाने से पहले, इंस्टॉल किए गए हुक और डेमन को हटाएं: +npm पैकेज को हटाने से पहले, इंस्टॉल किए गए हुक और डेमॉन को निकालें: ```bash failproofai uninstall --dry-run @@ -147,5 +154,5 @@ npm rm -g failproofai संस्करण-विशिष्ट विवरण के लिए `failproofai --help` चलाएं। - `npm rm -g failproofai` से पहले `failproofai uninstall` चलाएं; npm इंस्टॉल किए गए एजेंट हुक या डेमन सेवा को नहीं हटाता है। + `npm rm -g failproofai` से पहले `failproofai uninstall` चलाएं; npm इंस्टॉल किए गए एजेंट हुक या डेमॉन सेवा को नहीं हटाता। \ No newline at end of file diff --git a/docs/hi/start/quickstart.mdx b/docs/hi/start/quickstart.mdx index 16a83d5a..d281365f 100644 --- a/docs/hi/start/quickstart.mdx +++ b/docs/hi/start/quickstart.mdx @@ -1,37 +1,36 @@ --- ---- -title: "त्वरित शुरुआत" -description: "एक एजेंट सेशन कैप्चर करें, एक विफलता खोजें, और इसे रोकना शुरू करें।" +title: "क्विकस्टार्ट" +description: "एक एजेंट सेशन कैप्चर करें, विफलता खोजें, और इसे रोकना शुरू करें।" icon: "zap" --- -यह त्वरित शुरुआत एक मशीन को सेशन रिपोर्ट करने, एक ऑडिट चलाने और एक नीति तैनात करने के लिए सेट अप करती है। Failproof AI को सेट करने के लिए कौशल का उपयोग करें, या मैनुअल चरणों का पालन करें। +यह क्विकस्टार्ट एक मशीन को सेशन रिपोर्ट करने के लिए सेट करता है, एक ऑडिट चलाता है, और एक नीति तैनात करता है। Failproof AI को सेट अप करने के लिए स्किल का उपयोग करें, या मैनुअल स्टेप्स का पालन करें। -**आपका पथ कौन सा है?** यदि आपका एजेंट 12 समर्थित [हार्नेस](/hi/reference/harnesses) में से एक में चलता है — एक कोडिंग CLI, या Hermes या OpenClaw जैसा गेटवे — नीचे दिए गए चरणों का पालन करें; आपको Node.js 20.9 या बाद का संस्करण चाहिए। यदि आपके एजेंट के पास कोई हार्नेस नहीं है, तो ट्रेसिंग और ऑडिट के लिए इसे [Python SDK](/hi/reference/custom-agents) से इंस्ट्रूमेंट करें, फिर [अपनी पहली विफलता जांच चलाएं](/hi/start/first-audit) पर फिर से शामिल हों; उस पथ पर enforcement के लिए आपके runtime में एक hook की आवश्यकता है। +**आपका पाथ कौन सा है?** यदि आपका एजेंट 12 समर्थित [harnesses](/hi/reference/harnesses) में से एक में चलता है — एक कोडिंग CLI, या Hermes या OpenClaw जैसा गेटवे — नीचे दिए गए स्टेप्स का पालन करें; आपको Node.js 20.9 या बाद का संस्करण चाहिए। यदि आपके एजेंट के पास कोई harness नहीं है, तो ट्रेसिंग और ऑडिट के लिए इसे [Python SDK](/hi/reference/custom-agents) से इंस्ट्रूमेंट करें, फिर [Run your first failure check](/hi/start/first-audit) पर वापस आएं; उस पाथ पर एनफोर्समेंट के लिए आपके रनटाइम में एक हुक की आवश्यकता होती है। - + - + ```bash npx skills add FailproofAI/skills ``` - + ```text Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - आपका एजेंट प्रोजेक्ट का निरीक्षण करता है, प्रासंगिक एकीकरण चुनता है, सेटअप करता है, और इसे सत्यापित करता है। व्यक्तिगत कौशल और उन्नत इंस्टॉलेशन विकल्पों के लिए [FailproofAI कौशल रिपोजिटरी](https://github.com/FailproofAI/skills) देखें। + आपका एजेंट प्रोजेक्ट की जांच करता है, प्रासंगिक इंटीग्रेशन चुनता है, सेटअप करता है, और इसे सत्यापित करता है। व्यक्तिगत स्किल्स और उन्नत इंस्टॉलेशन विकल्प के लिए [FailproofAI skills repository](https://github.com/FailproofAI/skills) देखें। - ## शुरू करने से पहले + ## शुरुआत करने से पहले 1. [Failproof AI डैशबोर्ड](https://app.befailproof.ai) खोलें और एक खाता बनाएं या अपने कार्य ईमेल से साइन इन करें। 2. **Administration → Keys** पर जाएं और `events:add` और `policies:pull` के साथ एक कुंजी बनाएं। -3. एकबारी गुप्त को कॉपी करें और इसे लक्ष्य मशीन पर संग्रहीत करें: +3. एकबारगी गुप्त को कॉपी करें और इसे लक्ष्य मशीन पर स्टोर करें: ```bash export FAILPROOFAI_KEY="" @@ -46,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - सेशन ट्रांसक्रिप्ट डिफ़ॉल्ट रूप से भेजी जाती हैं। `--no-transcripts` जोड़ें ताकि ट्रांसक्रिप्ट सामग्री के बिना hook activity और नीति निर्णय रिपोर्ट किए जाएं। + सेशन ट्रांसक्रिप्ट्स डिफ़ॉल्ट रूप से भेजे जाते हैं। ट्रांसक्रिप्ट सामग्री के बिना हुक गतिविधि और नीति निर्णयों की रिपोर्ट करने के लिए `--no-transcripts` जोड़ें। - यदि इस मशीन के पास पहले से एजेंट history है, तो पिछले सात दिनों का पूर्वावलोकन करें और आयात करें, फिर delivery समाप्त होने का इंतजार करें। नई मशीन पर इस चरण को छोड़ें। + यदि इस मशीन पर पहले से एजेंट इतिहास है, तो अंतिम सात दिनों का पूर्वावलोकन करें और आयात करें, फिर डिलीवरी समाप्त होने की प्रतीक्षा करें। नई मशीन पर इस स्टेप को छोड़ दें। ```bash failproofai backfill --since 7d --dry-run @@ -58,28 +57,28 @@ export FAILPROOFAI_KEY="" Failproof AI में **Sessions** खोलें और एक आयातित सेशन चुनें। - - यह Failproof AI को आपके हार्नेस से जोड़ता है और 40 built-in नीतियां इंस्टॉल करता है। उन्हें स्थानीय नीति निर्णय देखने और Failproof AI आपके सेशन ऑडिट करने और आपके एजेंट के लिए नीतियां लिखने से पहले enforcement आजमाने के लिए उपयोग करें। + + यह Failproof AI को आपके harness से जोड़ता है और 39 बिल्ट-इन नीतियां इंस्टॉल करता है। स्थानीय नीति निर्णय देखने के लिए और Failproof AI आपके सेशन ऑडिट करने और आपके एजेंट्स के लिए नीतियां लिखने से पहले एनफोर्समेंट आजमाने के लिए इनका उपयोग करें। - इंस्टॉलर को अपने हार्नेस को detect करने दें, या एक को explicitly नाम दें। 12 में से प्रत्येक एक वैध `--cli` मान है — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`। + इंस्टॉलर को अपना harness डिटेक्ट करने दें, या एक स्पष्ट रूप से नाम दें। 12 में से प्रत्येक एक वैध `--cli` मान है — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`। ```bash failproofai policies --install --cli claude --scope user # a coding CLI failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - एक tool call को चलने से पहले block करना सभी 12 पर verified है। Turn-end gates 8 पर verified हैं — per-harness matrix के लिए [enforcement capability](/hi/reference/harnesses#enforcement-capability) देखें। + सभी 12 पर चलने से पहले एक टूल कॉल को ब्लॉक करना सत्यापित है। टर्न-एंड गेट्स 8 पर सत्यापित हैं — प्रति-harness मैट्रिक्स के लिए [enforcement capability](/hi/reference/harnesses#enforcement-capability) देखें। - - [अपनी पहली विफलता जांच चलाएं](/hi/start/first-audit) का पालन करें। एक ठोस लक्ष्य का उपयोग करें जैसे कि "ऐसे सेशन खोजें जहां एजेंट ने अपने दृष्टिकोण को बदले बिना एक विफल tool को फिर से try किया।" + + [Run your first failure check](/hi/start/first-audit) का पालन करें। एक ठोस लक्ष्य का उपयोग करें जैसे "सेशन खोजें जहां एजेंट ने अपने दृष्टिकोण को बदले बिना विफल टूल को फिर से आजमाया।" - [एक नीति के साथ अपनी पहली विफलता को रोकें](/hi/start/first-policy) का पालन करें। observe mode में शुरू करें, matches को inspect करें, फिर reviewed संस्करण को enforce करें। + [Prevent your first failure with a policy](/hi/start/first-policy) का पालन करें। अवलोकन मोड में शुरू करें, मिलान का निरीक्षण करें, फिर समीक्षा किए गए संस्करण को लागू करें। - `failproofai config --status` चलाएं। एक स्वस्थ सेटअप क्लाउड कनेक्शन, daemon state, और क्या enforcement को paused किया गया है यह रिपोर्ट करता है। + `failproofai config --status` चलाएं। एक स्वस्थ सेटअप क्लाउड कनेक्शन, डेमॉन स्थिति, और क्या एनफोर्समेंट को रोका गया है इसकी रिपोर्ट करता है। \ No newline at end of file diff --git a/docs/i18n/README.ar.md b/docs/i18n/README.ar.md index 408fc74e..094c30c2 100644 --- a/docs/i18n/README.ar.md +++ b/docs/i18n/README.ar.md @@ -22,29 +22,29 @@ **الترجمات:** [简体中文](../../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) -**قابلية الملاحظة والفرض لكل بيئة تقنية يعمل فيها وكيلك الذكي.** أينما يعمل وكيلك -الذكي، نحن نراه — ويمكننا الرفض. يتصل failproofai بـ 12 بيئة تقنية — واجهات سطر -أوامر البرمجة مثل Claude Code و Codex، بوابات الدردشة مثل Hermes، المساعدات ذاتية -الاستضافة مثل OpenClaw — لالتقاط كل عملية وحجب استدعاءات الأدوات الخطيرة قبل تنفيذها. -40 سياسة مدمجة. بدون تأخير. يعمل محليًا. +**قابلية الملاحظة والإنفاذ لكل محرك يشغّل وكلاءك.** +حيثما يعمل وكلاؤك، نحن نراهم — ويمكننا الاعتراض. يدعم failproofai 12 محرك وكيل +— واجهات سطر أوامر الترميز مثل Claude Code و Codex، وبوابات الدردشة مثل Hermes، +والمساعدات ذاتية الاستضافة مثل OpenClaw — حيث يعكس كل عملية تشغيل ويحجب استدعاءات الأدوات الخطرة +قبل تنفيذها. 39 سياسة مدمجة. لا توجد تأخيرات زمنية. يعمل محلياً.

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

--- -## البيئات التقنية المدعومة +## المحركات المدعومة -اثنتا عشرة بيئة تقنية في فئتين — عشر واجهات سطر أوامر برمجة، وبوابتا دردشة ومساعد -(Hermes، OpenClaw). نفس الأحداث، نفس السياسات، نفس سجل الجلسة، أيًا كانت البيئة التي -يعمل فيها وكيلك الذكي. +اثنا عشر محركاً في فئتين — عشر واجهات سطر أوامر للترميز، وبوابتان للدردشة والمساعدات +(Hermes، OpenClaw). نفس الأحداث، نفس السياسات، نفس سجل الجلسات، +أياً كان المحرك الذي يعمل فيه وكيلك. -الوكلاء الذين لا يعملون في أي منها يقدمون التقارير من خلال [Python SDK](https://docs.befailproof.ai/reference/custom-agents)، -والذي يوفر لك التتبع والجلسات والتدقيق. يحتاج الفرض هناك إلى خطاف في وقت التشغيل الخاص بك -— [تحدث معنا](mailto:support@befailproof.ai) وسنقوم بتعيينه. +تقدم الوكلاء الذين لا يعملون في أي منهم تقاريرهم عبر [Python SDK](https://docs.befailproof.ai/reference/custom-agents)، +والذي يوفر لك التتبع والجلسات والمراجعات. يتطلب الإنفاذ هناك ربط في +وقت تشغيلك الخاص — [تحدث إلينا](mailto:support@befailproof.ai) وسنقوم بتعيينه. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -144,38 +144,38 @@ ```sh npm install -g failproofai -failproofai policies --install # أو قم بتشغيل `failproofai` فقط واقبل رسالة التشغيل الأول +failproofai policies --install # أو فقط قم بتشغيل `failproofai` واقبل موجه التشغيل الأول failproofai ``` -40 سياسة مدمجة تتفعل فورًا. لوحة التحكم في `localhost:8020`. عطّل رسالة التشغيل الأول باستخدام `FAILPROOFAI_NO_FIRST_RUN=1`. +39 سياسة مدمجة تُفعَّل فوراً. لوحة المعلومات على `localhost:8020`. عطّل موجه التشغيل الأول باستخدام `FAILPROOFAI_NO_FIRST_RUN=1`. --- -## ما يمنعه +## ما الذي يوقفه -| السياسة | ما يحجبه | +| السياسة | ما الذي يحجبه | |---|---| -| `sanitize-api-keys` | تسرب مفاتيح API إلى سياق الوكيل | +| `sanitize-api-keys` | مفاتيح API تتسرب إلى سياق الوكيل | | `block-env-files` | قراءة ملفات `.env` والملفات السرية الأخرى | -| `warn-repeated-tool-calls` | حلقة الوكيل على نفس الاستدعاء | +| `warn-repeated-tool-calls` | الوكيل يكرر نفس الاستدعاء | | `block-sudo` | تصعيد الامتيازات | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` غير المحدود | -| `block-terraform` / `block-kubectl` | التغييرات غير المراجعة للبنية الأساسية الحية | +| `warn-destructive-sql` | `DROP`، `TRUNCATE`، `DELETE` غير المحدود | +| `block-terraform` / `block-kubectl` | تغييرات غير مراجعة على البنية التحتية الحية | | `block-rm-rf` | حذف الملفات بشكل متكرر | | `block-force-push` / `block-push-master` | `git push --force`، الدفع المباشر إلى `main` | -تنطبق أول خمسة على أي وكيل يمكنه استدعاء أداة. الثلاثة الأخيرة هي المفضلة لدى المطورين — -واجهات سطر أوامر البرمجة هي الفئة من البيئات التقنية التي نغطيها بعمق أكثر. +الخمس الأولى تنطبق على أي وكيل يمكنه استدعاء أداة. الثلاث الأخيرة مفضلة المطورين — +واجهات سطر أوامر الترميز هي فئة المحرك التي نغطيها بعمق أكبر. -→ [جميع السياسات المدمجة البالغ عددها 40](https://docs.befailproof.ai/policies/builtin) +→ [جميع السياسات المدمجة الـ 39](https://docs.befailproof.ai/policies/builtin) --- ## سياساتك الخاصة -ضع ملفًا في `.failproofai/policies/` — يتم تحميله تلقائيًا، لا توجد حاجة لعلامات. -قم بارتكابه وستحصل الفريق بأكمله عليه في الجلب التالي. +ضع ملفاً في `.failproofai/policies/` — يحمّل تلقائياً، لا توجد أعلام مطلوبة. +التزمه وستحصل الفريق بالكامل عليه في السحب التالي. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -185,19 +185,19 @@ customPolicies.add({ match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolInput?.file_path?.includes("production")) - return deny("Writes to production paths are blocked."); + return deny("الكتابة إلى مسارات الإنتاج محجوبة."); return allow(); }, }); ``` -هناك ثلاثة قرارات متاحة لكل سياسة: +ثلاثة قرارات متاحة لكل سياسة: | القرار | التأثير | |---|---| | `allow()` | السماح بالعملية | -| `deny(message)` | حجبها — يعود الرسالة إلى الوكيل | -| `instruct(message)` | السماح بها، لكن أضف سياقًا إلى المحفز التالي للوكيل | +| `deny(message)` | حجبها — الرسالة تعود إلى الوكيل | +| `instruct(message)` | السماح بها، لكن أضف سياق إلى موجه الوكيل التالي | → [دليل السياسات المخصصة](https://docs.befailproof.ai/policies/custom) @@ -205,29 +205,31 @@ customPolicies.add({ ## قابلية الملاحظة -الفرض نصف واحد. النصف الآخر هو رؤية ما فعله الوكيل فعلاً. +الإنفاذ هو نصف واحد. النصف الآخر هو رؤية ما فعله الوكيل فعلاً. -قم بتشغيل `failproofai` بدون مُعاملات وسيخدم لوحة تحكم على `localhost:8020` -تقرأ سجل التشغيل الموجود بالفعل على جهازك — لا حساب، لا تسجيل، لا شيء يترك الصندوق. -تحصل على قائمة الجلسة، وتسلسل استدعاءات النموذج، واستدعاءات الأدوات وقرارات الخطاف داخل كل تشغيل، -وما تم حجبه وما قالته السياسة للوكيل، وتدقيق غير متصل (`failproofai audit`) الذي يمسح سجلك -بحثًا عن أنماط محفوفة بالمخاطر ويقترح السياسات لإيقافها. +شغّل `failproofai` بدون وسائط وسيخدم لوحة معلومات على `localhost:8020` +قارئاً سجل التشغيل الموجود بالفعل على جهازك — لا حساب، لا اشتراك، لا شيء +يترك الصندوق. تحصل على قائمة الجلسات، وتسلسل استدعاءات النموذج، واستدعاءات الأدوات +وقرارات الربط داخل كل تشغيل، ما تم حجبه وما قالته السياسة للوكيل، +وتدقيق غير متصل (`failproofai audit`) الذي يفحص سجلك بحثاً عن أنماط محفوفة بالمخاطر +ويقترح سياسات لإيقافها. -→ [لوحة التحكم المحلية](https://docs.befailproof.ai/reference/local-dashboard) · -[اقرأ تتبعًا](https://docs.befailproof.ai/sessions/read-a-trace) · +→ [لوحة المعلومات المحلية](https://docs.befailproof.ai/reference/local-dashboard) · +[قراءة التتبع](https://docs.befailproof.ai/sessions/read-a-trace) · [التدقيق المحلي](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** هو الجانب المستضاف من نفس نموذج البيانات، للفرق التي -تدير الوكلاء عبر أسطول: كل تشغيل من كل بيئة تقنية في مكان واحد، رسم بياني للتنفيذ مع -وكلاء فرعيين متوازيين على ممراتهم الخاصة، كمون p50/p95/p99 للنماذج والأدوات والخطافات، -التكلفة لكل نموذج وتتبع نافذة السياق، تتبع الأخطاء، SQL فوق آثارك مع لوحات تحكم قابلة -للمشاركة، التقييمات التي تسجلها خدمتك الخاصة، المراجعات المجدولة التي تحول الأعطال المتكررة -إلى نتائج مدعومة بالأدلة، والتنبيهات الموجهة إلى Slack أو البريد الإلكتروني أو webhook موقّع. -الاستضافة الذاتية في مجموعتك الخاصة متاحة في خطة Enterprise. +**قابلية ملاحظة Failproof AI** هي الجانب المستضاف من نفس نموذج البيانات، للفرق +التي تشغّل الوكلاء عبر مجموعة: كل تشغيل من كل محرك في مكان واحد، رسم بياني للتنفيذ +مع وكلاء فرعيين متوازيين على مساراتهم الخاصة، زمن الاستجابة p50/p95/p99 +للنماذج والأدوات والربط، التكلفة لكل نموذج وتتبع نافذة السياق، تتبع الأخطاء، SQL +على تتبعاتك الخاصة مع لوحات معلومات قابلة للمشاركة، التقييمات المسجلة من قبل خدمتك الخاصة، +التدقيقات المجدولة التي تحول الفشل المتكرر إلى نتائج مدعومة بالأدلة، والتنبيهات +الموجهة إلى Slack أو البريد الإلكتروني أو webhook موقع. الاستضافة الذاتية في مجموعتك الخاصة +متاحة في خطة Enterprise. → [الجلسات](https://docs.befailproof.ai/sessions/overview) · [التدقيقات](https://docs.befailproof.ai/audits/overview) · -[احجز عرضًا توضيحيًا](https://befailproof.ai/get-a-demo) +[احجز عرضاً توضيحياً](https://befailproof.ai/get-a-demo) --- @@ -235,50 +237,49 @@ customPolicies.add({ | ابدأ | | |---|---| -| [البدء السريع](https://docs.befailproof.ai/start/quickstart) | التثبيت، والاتصال بالبيئة التقنية، وشاهد التشغيل الأول | -| [المفاهيم](https://docs.befailproof.ai/start/concepts) | كيف يعمل نظام الخطاف | -| [البيئات التقنية المدعومة](https://docs.befailproof.ai/reference/harnesses) | الكل 12، وما يمكن لكل منها فرضه | +| [البدء السريع](https://docs.befailproof.ai/start/quickstart) | التثبيت وربط محرك وشاهد التشغيل الأول | +| [المفاهيم](https://docs.befailproof.ai/start/concepts) | كيفية عمل نظام الربط | +| [المحركات المدعومة](https://docs.befailproof.ai/reference/harnesses) | جميع الـ 12 وما يمكن لكل واحد منها إنفاذه | | لاحظ | | |---|---| -| [الجلسات](https://docs.befailproof.ai/sessions/overview) | تابع التشغيل: النماذج والأدوات والأخطاء والكمون | -| [اقرأ تتبعًا](https://docs.befailproof.ai/sessions/read-a-trace) | ما يخبرك به الرسم البياني للتنفيذ | -| [التدقيقات](https://docs.befailproof.ai/audits/overview) | ابحث عن أنماط الفشل عبر جلسات كثيرة | -| [لوحة التحكم المحلية](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`، لا حاجة للحساب | +| [الجلسات](https://docs.befailproof.ai/sessions/overview) | اتبع تشغيلاً: النماذج والأدوات والأخطاء وزمن الاستجابة | +| [قراءة التتبع](https://docs.befailproof.ai/sessions/read-a-trace) | ما الذي يخبرك به رسم البياني للتنفيذ | +| [التدقيقات](https://docs.befailproof.ai/audits/overview) | ابحث عن أنماط الفشل عبر عدد من الجلسات | +| [لوحة المعلومات المحلية](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`، لا يوجد حساب مطلوب | -| فرض | | +| أنفذ | | |---|---| -| [السياسات المدمجة](https://docs.befailproof.ai/policies/builtin) | جميع السياسات الـ 40 مع المعاملات | -| [السياسات المخصصة](https://docs.befailproof.ai/policies/custom) | اكتب الخاصة بك | +| [السياسات المدمجة](https://docs.befailproof.ai/policies/builtin) | جميع السياسات الـ 39 مع المعاملات | +| [السياسات المخصصة](https://docs.befailproof.ai/policies/custom) | اكتب سياساتك الخاصة | | [التكوين](https://docs.befailproof.ai/policies/local-configuration) | نطاقات التكوين وقواعد الدمج | -| أداة وكيلك الخاص | | +| أدوات وكيلك الخاص | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | الإبلاغ عن التشغيلات من وكيل بدون بيئة تقنية | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | ابلغ عن التشغيلات من وكيل بدون محرك | | [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | مرجع `allow` / `deny` / `instruct` | --- ## الترخيص -MIT مع [Commons Clause](https://commonsclause.com/) — مجاني للاستخدام الداخلي والشخصي؛ -يتطلب إعادة بيع تجارية لـ failproofai نفسه اتفاقية منفصلة. انظر [LICENSE](../../LICENSE) للنص الكامل. +MIT مع [Commons Clause](https://commonsclause.com/) — مجاني للاستخدام الداخلي والشخصي؛ إعادة بيع تجارية من failproofai نفسه يتطلب اتفاقية منفصلة. انظر [LICENSE](../../LICENSE) للنص الكامل. --- ## المساهمة -انظر [CONTRIBUTING.md](../../CONTRIBUTING.md). السياسات الجديدة والحالات الحدية والترجمات كلها مرحب بها. +انظر [CONTRIBUTING.md](../../CONTRIBUTING.md). السياسات الجديدة والحالات الحدية والترجمات جميعها مرحب بها. -> **ابنِ قبل أن تبدأ.** قم بتشغيل `bun install && bun run build` أولاً. يعمل هذا المستودع -> خطافات failproofai الخاصة به على نفسه، وهي تحل استيراد `failproofai` مقابل حزمة `dist/` -> المترجمة — بدون بناء ستواجه أخطاء خطاف `Cannot find package 'failproofai'`. أعد البناء -> بعد تغيير `src/`. انظر -> [ابنِ قبل أن تعمل خطافات dev داخل المستودع](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **بناء قبل أن تبدأ.** شغّل `bun install && bun run build` أولاً. يشغّل هذا الريبو +> ربطات failproofai الخاصة به على نفسه، ويحل استيراد `failproofai` مقابل +> حزمة `dist/` المترجمة — بدون بناء ستصطدم بأخطاء ربط `Cannot find package 'failproofai'`. +> أعد البناء بعد تغيير `src/`. انظر +> [بناء قبل أن تعمل ربطات dev في المريبو](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -تم البناء بـ ❤️ بواسطة [befailproof.ai](https://befailproof.ai) في SF وBengaluru. +بُني بـ ❤️ من قِبل [befailproof.ai](https://befailproof.ai) في SF و Bengaluru. \ No newline at end of file diff --git a/docs/i18n/README.de.md b/docs/i18n/README.de.md index 1707c9d2..497c215f 100644 --- a/docs/i18n/README.de.md +++ b/docs/i18n/README.de.md @@ -20,8 +20,8 @@ **Ü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) -**Observability und Durchsetzung für jeden Harness, in dem deine Agenten laufen.** -Egal wo deine Agenten ausgeführt werden – wir sehen es und können eingreifen. Failproof bindet sich in 12 Agent-Harnesses ein – Coding-CLIs wie Claude Code und Codex, Chat-Gateways wie Hermes, selbst gehostete Assistenten wie OpenClaw – erfasst jeden Durchlauf und blockiert gefährliche Tool-Aufrufe, bevor sie ausgeführt werden. 40 eingebaute Richtlinien. Keine Latenz. Läuft lokal. +**Observability und Durchsetzung für jede Umgebung, in der Ihre Agents laufen.** +Egal wo Ihre Agents laufen – wir sehen es und können eingreifen. Failproof unterstützt 12 Agent-Umgebungen (Harnesses) — Coding-CLIs wie Claude Code und Codex, Chat-Gateways wie Hermes, selbst gehostete Assistenten wie OpenClaw — erfasst jeden Lauf und blockiert gefährliche Tool-Aufrufe, bevor sie ausgeführt werden. 39 eingebaute Richtlinien. Null Latenz. Läuft lokal. @@ -33,9 +33,9 @@ Egal wo deine Agenten ausgeführt werden – wir sehen es und können eingreifen ## Unterstützte Harnesses -Zwölf Harnesses in zwei Klassen – zehn Coding-CLIs und zwei Chat- und Assistenz-Gateways (Hermes, OpenClaw). Dieselben Events, dieselben Richtlinien, dieselbe Sitzungshistorie – unabhängig davon, welchen Harness dein Agent verwendet. +Zwölf Harnesses in zwei Klassen — zehn Coding-CLIs und zwei Chat- und Assistenten-Gateways (Hermes, OpenClaw). Gleiche Events, gleiche Richtlinien, gleiche Sitzungshistorie — unabhängig davon, in welcher Umgebung Ihr Agent läuft. -Agenten, die in keinem davon laufen, können über das [Python SDK](https://docs.befailproof.ai/reference/custom-agents) berichten – es bietet Tracing, Sessions und Audits. Durchsetzung erfordert dort einen Hook in deiner eigenen Laufzeitumgebung – [sprich uns an](mailto:support@befailproof.ai) und wir erarbeiten eine Lösung. +Agents, die in keiner dieser Umgebungen laufen, berichten über das [Python SDK](https://docs.befailproof.ai/reference/custom-agents), das Tracing, Sitzungen und Audits bietet. Für die Durchsetzung dort benötigen Sie einen Hook in Ihrer eigenen Laufzeitumgebung — [sprechen Sie uns an](mailto:support@befailproof.ai) und wir helfen Ihnen dabei. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,36 +135,36 @@ Agenten, die in keinem davon laufen, können über das [Python SDK](https://docs ```sh npm install -g failproofai -failproofai policies --install # oder einfach `failproofai` ausführen und den Erststart-Dialog bestätigen +failproofai policies --install # oder einfach `failproofai` ausführen und die Erststart-Eingabeaufforderung bestätigen failproofai ``` -40 eingebaute Richtlinien werden sofort aktiviert. Dashboard unter `localhost:8020`. Den Erststart-Dialog deaktivieren mit `FAILPROOFAI_NO_FIRST_RUN=1`. +39 eingebaute Richtlinien werden sofort aktiviert. Dashboard unter `localhost:8020`. Den Erststart-Dialog deaktivieren Sie mit `FAILPROOFAI_NO_FIRST_RUN=1`. --- ## Was es verhindert -| Richtlinie | Was sie blockiert | +| Richtlinie | Was wird blockiert | |---|---| -| `sanitize-api-keys` | API-Schlüssel, die in den Kontext des Agenten gelangen | +| `sanitize-api-keys` | API-Schlüssel, die in den Kontext des Agents gelangen | | `block-env-files` | Lesezugriffe auf `.env` und andere Secret-Dateien | -| `warn-repeated-tool-calls` | Den Agenten, der denselben Aufruf in einer Schleife wiederholt | -| `block-sudo` | Privilege-Escalation | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, unbegrenzte `DELETE`-Abfragen | -| `block-terraform` / `block-kubectl` | Nicht geprüfte Änderungen an Live-Infrastruktur | +| `warn-repeated-tool-calls` | Agent-Schleifen beim selben Aufruf | +| `block-sudo` | Privilege Escalation | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, unbegrenzte `DELETE`-Anweisungen | +| `block-terraform` / `block-kubectl` | Nicht geprüfte Änderungen an produktiver Infrastruktur | | `block-rm-rf` | Rekursives Löschen von Dateien | | `block-force-push` / `block-push-master` | `git push --force`, direkte Pushes auf `main` | -Die ersten fünf gelten für jeden Agenten, der Tools aufrufen kann. Die letzten drei sind die Favoriten unter Entwicklern – Coding-CLIs sind die Harness-Klasse, die wir am umfassendsten abdecken. +Die ersten fünf gelten für jeden Agent, der Tools aufrufen kann. Die letzten drei sind die Favoriten unter Entwicklern — Coding-CLIs sind die Harness-Klasse, die wir am tiefsten abdecken. -→ [Alle 40 eingebauten Richtlinien](https://docs.befailproof.ai/policies/builtin) +→ [Alle 39 eingebauten Richtlinien](https://docs.befailproof.ai/policies/builtin) --- ## Eigene Richtlinien -Lege eine Datei in `.failproofai/policies/` ab – sie wird automatisch geladen, ohne zusätzliche Flags. Committe sie und das gesamte Team erhält sie beim nächsten Pull. +Legen Sie eine Datei in `.failproofai/policies/` ab — sie wird automatisch geladen, ohne Flags. Committen Sie sie, und das gesamte Team erhält sie beim nächsten Pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -180,13 +180,13 @@ customPolicies.add({ }); ``` -Drei Entscheidungen stehen jeder Richtlinie zur Verfügung: +Jede Richtlinie kann eine von drei Entscheidungen treffen: | Entscheidung | Wirkung | |---|---| | `allow()` | Operation erlauben | -| `deny(message)` | Blockieren – die Nachricht wird an den Agenten zurückgegeben | -| `instruct(message)` | Durchlassen, aber dem nächsten Prompt des Agenten Kontext hinzufügen | +| `deny(message)` | Blockieren — die Nachricht wird an den Agent zurückgegeben | +| `instruct(message)` | Durchlassen, aber dem nächsten Prompt des Agents Kontext hinzufügen | → [Leitfaden für eigene Richtlinien](https://docs.befailproof.ai/policies/custom) @@ -196,15 +196,15 @@ Drei Entscheidungen stehen jeder Richtlinie zur Verfügung: Durchsetzung ist die eine Hälfte. Die andere Hälfte ist zu sehen, was der Agent tatsächlich getan hat. -Starte `failproofai` ohne Argumente, und es stellt ein Dashboard unter `localhost:8020` bereit, das die bereits auf deinem Rechner vorhandene Ausführungshistorie liest – kein Konto, keine Registrierung, nichts verlässt das Gerät. Du erhältst die Sitzungsliste, die Abfolge von Modellaufrufen, Tool-Aufrufen und Hook-Entscheidungen innerhalb jedes Durchlaufs, was blockiert wurde und was die Richtlinie dem Agenten mitgeteilt hat, sowie ein Offline-Audit (`failproofai audit`), das deine Historie nach riskanten Mustern durchsucht und Richtlinien vorschlägt, um sie zu unterbinden. +Führen Sie `failproofai` ohne Argumente aus, und es startet ein Dashboard auf `localhost:8020`, das die bereits auf Ihrem Rechner vorhandene Verlaufshistorie ausliest — kein Konto, keine Registrierung, nichts verlässt Ihren Rechner. Sie erhalten die Sitzungsliste, die Abfolge von Modell-Aufrufen, Tool-Aufrufen und Hook-Entscheidungen innerhalb jedes Laufs, was blockiert wurde und was die Richtlinie dem Agent mitgeteilt hat, sowie ein Offline-Audit (`failproofai audit`), das Ihre Historie nach riskanten Mustern durchsucht und Richtlinien vorschlägt, um diese zu unterbinden. → [Lokales Dashboard](https://docs.befailproof.ai/reference/local-dashboard) · -[Einen Trace lesen](https://docs.befailproof.ai/sessions/read-a-trace) · +[Eine Ablaufverfolgung lesen](https://docs.befailproof.ai/sessions/read-a-trace) · [Lokales Audit](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** ist die gehostete Seite desselben Datenmodells – für Teams, die Agenten über eine gesamte Flotte hinweg betreiben: alle Durchläufe aus allen Harnesses an einem Ort, ein Ausführungsgraph mit parallelen Sub-Agenten auf eigenen Spuren, p50/p95/p99-Latenz für Modelle, Tools und Hooks, modellbezogene Kosten- und Kontextfensterverfolgung, Fehlerverfolgung, SQL über eigene Traces mit teilbaren Dashboards, Evaluierungen bewertet durch deinen eigenen Dienst, geplante Audits, die wiederkehrende Fehler in evidenzgestützte Befunde umwandeln, sowie Benachrichtigungen über Slack, E-Mail oder einen signierten Webhook. Self-Hosting im eigenen Cluster ist im Enterprise-Plan verfügbar. +**Failproof AI Observability** ist die gehostete Seite desselben Datenmodells, für Teams, die Agents in einer ganzen Flotte betreiben: jeder Lauf aus jeder Harness an einem Ort, ein Ausführungsgraph mit parallelen Sub-Agents auf eigenen Spuren, p50/p95/p99-Latenz für Modelle, Tools und Hooks, modellbezogenes Kosten- und Kontextfenster-Tracking, Fehlerverfolgung, SQL über Ihre eigenen Traces mit teilbaren Dashboards, Evaluierungen bewertet durch Ihren eigenen Dienst, geplante Audits, die wiederkehrende Fehler in evidenzbasierte Befunde umwandeln, sowie Benachrichtigungen an Slack, E-Mail oder einen signierten Webhook. Self-Hosting im eigenen Cluster ist im Enterprise-Plan verfügbar. -→ [Sessions](https://docs.befailproof.ai/sessions/overview) · +→ [Sitzungen](https://docs.befailproof.ai/sessions/overview) · [Audits](https://docs.befailproof.ai/audits/overview) · [Demo buchen](https://befailproof.ai/get-a-demo) @@ -214,43 +214,43 @@ Starte `failproofai` ohne Argumente, und es stellt ein Dashboard unter `localhos | Einstieg | | |---|---| -| [Schnellstart](https://docs.befailproof.ai/start/quickstart) | Installieren, einen Harness verbinden, den ersten Durchlauf ansehen | +| [Schnellstart](https://docs.befailproof.ai/start/quickstart) | Installieren, eine Harness verbinden, den ersten Lauf ansehen | | [Konzepte](https://docs.befailproof.ai/start/concepts) | Wie das Hook-System funktioniert | -| [Unterstützte Harnesses](https://docs.befailproof.ai/reference/harnesses) | Alle 12 und was jeder davon durchsetzen kann | +| [Unterstützte Harnesses](https://docs.befailproof.ai/reference/harnesses) | Alle 12 und was jede davon durchsetzen kann | | Beobachten | | |---|---| -| [Sessions](https://docs.befailproof.ai/sessions/overview) | Einen Durchlauf verfolgen: Modelle, Tools, Fehler, Latenz | -| [Einen Trace lesen](https://docs.befailproof.ai/sessions/read-a-trace) | Was der Ausführungsgraph aussagt | -| [Audits](https://docs.befailproof.ai/audits/overview) | Fehlermuster über viele Sessions hinweg erkennen | +| [Sitzungen](https://docs.befailproof.ai/sessions/overview) | Einem Lauf folgen: Modelle, Tools, Fehler, Latenz | +| [Eine Ablaufverfolgung lesen](https://docs.befailproof.ai/sessions/read-a-trace) | Was der Ausführungsgraph Ihnen mitteilt | +| [Audits](https://docs.befailproof.ai/audits/overview) | Fehlermuster über viele Sitzungen hinweg finden | | [Lokales Dashboard](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, kein Konto erforderlich | | Durchsetzen | | |---|---| -| [Eingebaute Richtlinien](https://docs.befailproof.ai/policies/builtin) | Alle 40 Richtlinien mit Parametern | -| [Eigene Richtlinien](https://docs.befailproof.ai/policies/custom) | Eigene schreiben | +| [Eingebaute Richtlinien](https://docs.befailproof.ai/policies/builtin) | Alle 39 Richtlinien mit Parametern | +| [Eigene Richtlinien](https://docs.befailproof.ai/policies/custom) | Schreiben Sie Ihre eigenen | | [Konfiguration](https://docs.befailproof.ai/policies/local-configuration) | Konfigurations-Scopes und Zusammenführungsregeln | -| Eigenen Agenten instrumentieren | | +| Eigenen Agent instrumentieren | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Durchläufe von einem Agenten ohne Harness melden | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Läufe von einem Agent ohne Harness melden | | [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` Referenz | --- ## Lizenz -MIT mit [Commons Clause](https://commonsclause.com/) – kostenlos für den internen und persönlichen Gebrauch; der kommerzielle Weiterverkauf von failproofai selbst erfordert eine separate Vereinbarung. Den vollständigen Text findest du unter [LICENSE](../../LICENSE). +MIT mit [Commons Clause](https://commonsclause.com/) — kostenlos für den internen und privaten Einsatz; der kommerzielle Weiterverkauf von failproofai selbst erfordert eine gesonderte Vereinbarung. Den vollständigen Text finden Sie unter [LICENSE](../../LICENSE). --- ## Mitwirken -Siehe [CONTRIBUTING.md](../../CONTRIBUTING.md). Neue Richtlinien, Grenzfälle und Übersetzungen sind herzlich willkommen. +Siehe [CONTRIBUTING.md](../../CONTRIBUTING.md). Neue Richtlinien, Randfälle und Übersetzungen sind herzlich willkommen. -> **Vor dem Start bauen.** Führe zuerst `bun install && bun run build` aus. Dieses Repository führt failproofais eigene Hooks auf sich selbst aus, und diese lösen den `failproofai`-Import gegen das kompilierte `dist/`-Bundle auf – ohne einen Build erhältst du `Cannot find package 'failproofai'`-Hook-Fehler. Nach Änderungen an `src/` neu bauen. Siehe +> **Vor dem Start bauen.** Führen Sie zuerst `bun install && bun run build` aus. Dieses Repository verwendet failproofai's eigene Hooks auf sich selbst, und diese lösen den `failproofai`-Import gegen das kompilierte `dist/`-Bundle auf — ohne einen Build erhalten Sie `Cannot find package 'failproofai'`-Hook-Fehler. Nach Änderungen in `src/` neu bauen. Siehe > [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Mit ❤️ gebaut von [befailproof.ai](https://befailproof.ai) in SF und Bengaluru. +Gebaut mit ❤️ von [befailproof.ai](https://befailproof.ai) in SF und Bengaluru. diff --git a/docs/i18n/README.es.md b/docs/i18n/README.es.md index 746a8887..2e77c6ed 100644 --- a/docs/i18n/README.es.md +++ b/docs/i18n/README.es.md @@ -20,8 +20,8 @@ **Traducciones:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Observabilidad y control para cada entorno en el que corren tus agentes.** -Donde sea que corran tus agentes, nosotros lo vemos — y podemos decir que no. Failproof intercepta 12 entornos de agentes — CLIs de programación como Claude Code y Codex, pasarelas de chat como Hermes, asistentes autoalojados como OpenClaw — capturando cada ejecución y bloqueando llamadas peligrosas a herramientas antes de que se ejecuten. 40 políticas integradas. Cero latencia. Se ejecuta localmente. +**Observabilidad y control para todos los entornos en los que corren tus agentes.** +Dondequiera que se ejecuten tus agentes, nosotros lo vemos — y podemos decir que no. Failproof engancha 12 entornos de ejecución de agentes — CLIs de programación como Claude Code y Codex, pasarelas de chat como Hermes, asistentes autoalojados como OpenClaw — capturando cada ejecución y bloqueando llamadas a herramientas peligrosas antes de que se ejecuten. 39 políticas integradas. Cero latencia. Se ejecuta localmente. @@ -33,9 +33,9 @@ Donde sea que corran tus agentes, nosotros lo vemos — y podemos decir que no. ## Entornos compatibles -Doce entornos en dos categorías — diez CLIs de programación, y dos pasarelas de chat y asistentes (Hermes, OpenClaw). Los mismos eventos, las mismas políticas, el mismo historial de sesiones, sin importar en cuál de ellos corra tu agente. +Doce entornos en dos categorías — diez CLIs de programación y dos pasarelas de chat y asistentes (Hermes, OpenClaw). Los mismos eventos, las mismas políticas, el mismo historial de sesiones, independientemente del entorno en que se ejecute tu agente. -Los agentes que no se ejecuten en ninguno de estos entornos pueden reportar a través del [SDK de Python](https://docs.befailproof.ai/reference/custom-agents), que ofrece trazas, sesiones y auditorías. Para aplicar controles en esos casos se necesita un hook en tu propio runtime — [contáctanos](mailto:support@befailproof.ai) y lo diseñamos juntos. +Los agentes que no corran en ninguno de ellos pueden informar a través del [SDK de Python](https://docs.befailproof.ai/reference/custom-agents), que ofrece trazado, sesiones y auditorías. El control en esos entornos requiere un hook en tu propio runtime — [contáctanos](mailto:support@befailproof.ai) y lo mapearemos juntos. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,11 +135,11 @@ Los agentes que no se ejecuten en ninguno de estos entornos pueden reportar a tr ```sh npm install -g failproofai -failproofai policies --install # o simplemente ejecuta `failproofai` y acepta el aviso del primer inicio +failproofai policies --install # o simplemente ejecuta `failproofai` y acepta el aviso de primera ejecución failproofai ``` -40 políticas integradas se activan de inmediato. Panel de control en `localhost:8020`. Desactiva el aviso del primer inicio con `FAILPROOFAI_NO_FIRST_RUN=1`. +39 políticas integradas se activan de inmediato. Panel de control en `localhost:8020`. Desactiva el aviso de primera ejecución con `FAILPROOFAI_NO_FIRST_RUN=1`. --- @@ -148,24 +148,24 @@ failproofai | Política | Qué bloquea | |---|---| | `sanitize-api-keys` | Claves de API que se filtran al contexto del agente | -| `block-env-files` | Lecturas de `.env` y otros archivos con secretos | -| `warn-repeated-tool-calls` | El agente haciendo un bucle con la misma llamada | +| `block-env-files` | Lecturas de `.env` y otros archivos de secretos | +| `warn-repeated-tool-calls` | El agente en bucle sobre la misma llamada | | `block-sudo` | Escalada de privilegios | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` sin condiciones | -| `block-terraform` / `block-kubectl` | Cambios sin revisión en infraestructura en producción | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` sin restricciones | +| `block-terraform` / `block-kubectl` | Cambios no revisados en infraestructura en producción | | `block-rm-rf` | Eliminación recursiva de archivos | | `block-force-push` / `block-push-master` | `git push --force`, pushes directos a `main` | -Las primeras cinco se aplican a cualquier agente que pueda llamar a una herramienta. Las últimas tres son las favoritas de los desarrolladores — las CLIs de programación son la categoría de entorno que cubrimos con mayor profundidad. +Las primeras cinco se aplican a cualquier agente que pueda llamar a una herramienta. Las últimas tres son las favoritas de los desarrolladores — las CLIs de programación son la categoría de entornos que cubrimos con mayor profundidad. -→ [Las 40 políticas integradas](https://docs.befailproof.ai/policies/builtin) +→ [Las 39 políticas integradas](https://docs.befailproof.ai/policies/builtin) --- ## Tus propias políticas Coloca un archivo en `.failproofai/policies/` — se carga automáticamente, sin necesidad de flags. -Confírmalo en el repositorio y todo el equipo lo recibirá en el próximo pull. +Haz commit y todo el equipo lo tendrá en el próximo pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -198,51 +198,51 @@ Tres decisiones disponibles para cada política: El control es una mitad. La otra mitad es ver qué hizo realmente el agente. Ejecuta `failproofai` sin argumentos y sirve un panel de control en `localhost:8020` -que lee el historial de ejecuciones ya almacenado en tu máquina — sin cuenta, sin registro, sin que nada salga del equipo. Obtienes la lista de sesiones, la secuencia de llamadas al modelo, llamadas a herramientas y decisiones del hook dentro de cada ejecución, qué fue bloqueado y qué le dijo la política al agente, y una auditoría offline (`failproofai audit`) que analiza tu historial en busca de patrones arriesgados y sugiere políticas para detenerlos. +que lee el historial de ejecuciones ya almacenado en tu máquina — sin cuenta, sin registro, sin que nada salga del equipo. Obtienes la lista de sesiones, la secuencia de llamadas al modelo, llamadas a herramientas y decisiones de hooks dentro de cada ejecución, qué fue bloqueado y qué le indicó la política al agente, y una auditoría sin conexión (`failproofai audit`) que analiza tu historial en busca de patrones de riesgo y sugiere políticas para detenerlos. → [Panel local](https://docs.befailproof.ai/reference/local-dashboard) · -[Leer una traza](https://docs.befailproof.ai/sessions/read-a-trace) · +[Leer un trazado](https://docs.befailproof.ai/sessions/read-a-trace) · [Auditoría local](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** es la versión alojada del mismo modelo de datos, para equipos que ejecutan agentes en una flota: cada ejecución de cada entorno en un solo lugar, un grafo de ejecución con subagentes paralelos en sus propios carriles, latencia p50/p95/p99 para modelos, herramientas y hooks, seguimiento de costos y ventana de contexto por modelo, seguimiento de errores, SQL sobre tus propias trazas con paneles compartibles, evaluaciones puntuadas por tu propio servicio, auditorías programadas que convierten fallos recurrentes en hallazgos respaldados por evidencia, y alertas enrutadas a Slack, email o un webhook firmado. El autoalojamiento en tu propio clúster está disponible en el plan Enterprise. +**Failproof AI Observability** es la parte alojada del mismo modelo de datos, para equipos que ejecutan agentes en una flota: todas las ejecuciones de todos los entornos en un solo lugar, un grafo de ejecución con subagentes paralelos en sus propios canales, latencia p50/p95/p99 para modelos, herramientas y hooks, seguimiento de costes y ventana de contexto por modelo, seguimiento de errores, SQL sobre tus propios trazados con paneles compartibles, evaluaciones puntuadas por tu propio servicio, auditorías programadas que convierten fallos recurrentes en hallazgos respaldados por evidencias, y alertas enrutadas a Slack, correo electrónico o un webhook firmado. El autoalojamiento en tu propio clúster está disponible en el plan Enterprise. → [Sesiones](https://docs.befailproof.ai/sessions/overview) · [Auditorías](https://docs.befailproof.ai/audits/overview) · -[Solicitar una demo](https://befailproof.ai/get-a-demo) +[Reservar una demo](https://befailproof.ai/get-a-demo) --- ## Documentación -| Empezar | | +| Comenzar | | |---|---| -| [Inicio rápido](https://docs.befailproof.ai/start/quickstart) | Instalar, conectar un entorno, ver la primera ejecución | +| [Inicio rápido](https://docs.befailproof.ai/start/quickstart) | Instala, conecta un entorno, ve la primera ejecución | | [Conceptos](https://docs.befailproof.ai/start/concepts) | Cómo funciona el sistema de hooks | -| [Entornos compatibles](https://docs.befailproof.ai/reference/harnesses) | Los 12, y qué puede controlar cada uno | +| [Entornos compatibles](https://docs.befailproof.ai/reference/harnesses) | Los 12 entornos y qué puede controlar cada uno | | Observar | | |---|---| -| [Sesiones](https://docs.befailproof.ai/sessions/overview) | Seguir una ejecución: modelos, herramientas, errores, latencia | -| [Leer una traza](https://docs.befailproof.ai/sessions/read-a-trace) | Qué te está diciendo el grafo de ejecución | -| [Auditorías](https://docs.befailproof.ai/audits/overview) | Encontrar patrones de fallo en muchas sesiones | +| [Sesiones](https://docs.befailproof.ai/sessions/overview) | Sigue una ejecución: modelos, herramientas, errores, latencia | +| [Leer un trazado](https://docs.befailproof.ai/sessions/read-a-trace) | Qué te indica el grafo de ejecución | +| [Auditorías](https://docs.befailproof.ai/audits/overview) | Encuentra patrones de fallo en múltiples sesiones | | [Panel local](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, sin cuenta necesaria | | Controlar | | |---|---| -| [Políticas integradas](https://docs.befailproof.ai/policies/builtin) | Las 40 políticas con sus parámetros | -| [Políticas personalizadas](https://docs.befailproof.ai/policies/custom) | Escribe las tuyas | -| [Configuración](https://docs.befailproof.ai/policies/local-configuration) | Ámbitos de configuración y reglas de fusión | +| [Políticas integradas](https://docs.befailproof.ai/policies/builtin) | Las 39 políticas con sus parámetros | +| [Políticas personalizadas](https://docs.befailproof.ai/policies/custom) | Escribe las tuyas propias | +| [Configuración](https://docs.befailproof.ai/policies/local-configuration) | Ámbitos de configuración y reglas de combinación | | Instrumentar tu propio agente | | |---|---| -| [SDK de Python](https://docs.befailproof.ai/reference/custom-agents) | Reportar ejecuciones desde un agente sin entorno propio | +| [SDK de Python](https://docs.befailproof.ai/reference/custom-agents) | Reporta ejecuciones desde un agente sin entorno | | [SDK de políticas](https://docs.befailproof.ai/reference/policy-sdk) | Referencia de `allow` / `deny` / `instruct` | --- ## Licencia -MIT con [Commons Clause](https://commonsclause.com/) — gratuito para uso interno y personal; la reventa comercial de failproofai en sí misma requiere un acuerdo separado. Consulta [LICENSE](../../LICENSE) para el texto completo. +MIT con [Commons Clause](https://commonsclause.com/) — libre para uso interno y personal; la reventa comercial de failproofai en sí requiere un acuerdo independiente. Consulta [LICENSE](../../LICENSE) para el texto completo. --- @@ -250,8 +250,9 @@ MIT con [Commons Clause](https://commonsclause.com/) — gratuito para uso inter Consulta [CONTRIBUTING.md](../../CONTRIBUTING.md). Se aceptan con gusto nuevas políticas, casos límite y traducciones. -> **Compila antes de empezar.** Ejecuta primero `bun install && bun run build`. Este repositorio ejecuta sus propios hooks de failproofai sobre sí mismo, y resuelven la importación de `failproofai` contra el bundle compilado en `dist/` — sin una compilación previa obtendrás errores de hook `Cannot find package 'failproofai'`. Recompila tras modificar `src/`. Consulta [Compila antes de que funcionen los hooks de desarrollo del repositorio](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Compila antes de empezar.** Ejecuta primero `bun install && bun run build`. Este repositorio ejecuta los propios hooks de failproofai sobre sí mismo, y resuelven la importación de `failproofai` contra el bundle compilado en `dist/` — sin una compilación previa obtendrás errores de hook `Cannot find package 'failproofai'`. Vuelve a compilar tras modificar `src/`. Consulta +> [Compila antes de que funcionen los hooks de desarrollo del repositorio](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Construido con ❤️ por [befailproof.ai](https://befailproof.ai) en SF y Bengaluru. +Hecho con ❤️ por [befailproof.ai](https://befailproof.ai) en SF y Bengaluru. diff --git a/docs/i18n/README.fr.md b/docs/i18n/README.fr.md index 5e1aa467..cc963faa 100644 --- a/docs/i18n/README.fr.md +++ b/docs/i18n/README.fr.md @@ -21,7 +21,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) **Observabilité et contrôle pour chaque environnement d'exécution de vos agents.** -Où que vos agents s'exécutent, nous le voyons — et nous pouvons dire non. Failproof s'intègre à 12 environnements d'exécution d'agents — des CLI de développement comme Claude Code et Codex, des passerelles de chat comme Hermes, des assistants auto-hébergés comme OpenClaw — en capturant chaque exécution et en bloquant les appels d'outils dangereux avant qu'ils ne s'exécutent. 40 politiques intégrées. Zéro latence. Fonctionne en local. +Où que vos agents s'exécutent, nous le voyons — et nous pouvons dire non. Failproof s'intègre à 12 environnements d'agents — des CLI de codage comme Claude Code et Codex, des passerelles de chat comme Hermes, des assistants auto-hébergés comme OpenClaw — capturant chaque exécution et bloquant les appels d'outils dangereux avant qu'ils ne s'exécutent. 39 politiques intégrées. Zéro latence. Fonctionne en local. @@ -31,11 +31,11 @@ Où que vos agents s'exécutent, nous le voyons — et nous pouvons dire non. Fa --- -## Environnements d'exécution pris en charge +## Environnements pris en charge -Douze environnements d'exécution en deux catégories — dix CLI de développement, et deux passerelles de chat et d'assistant (Hermes, OpenClaw). Mêmes événements, mêmes politiques, même historique de session, quel que soit l'environnement dans lequel votre agent s'exécute. +Douze environnements en deux catégories — dix CLI de codage, et deux passerelles de chat et d'assistant (Hermes, OpenClaw). Mêmes événements, mêmes politiques, même historique de session, quel que soit l'environnement dans lequel votre agent s'exécute. -Les agents qui ne s'exécutent dans aucun d'eux envoient leurs données via le [SDK Python](https://docs.befailproof.ai/reference/custom-agents), qui vous offre le traçage, la gestion des sessions et les audits. L'application des politiques dans ce cas nécessite un hook dans votre propre runtime — [contactez-nous](mailto:support@befailproof.ai) et nous l'adapterons. +Les agents qui ne s'exécutent dans aucun d'entre eux remontent leurs données via le [SDK Python](https://docs.befailproof.ai/reference/custom-agents), qui vous offre le traçage, les sessions et les audits. L'application des politiques y nécessite un hook dans votre propre runtime — [contactez-nous](mailto:support@befailproof.ai) et nous le configurerons ensemble. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,11 +135,11 @@ Les agents qui ne s'exécutent dans aucun d'eux envoient leurs données via le [ ```sh npm install -g failproofai -failproofai policies --install # ou lancez simplement `failproofai` et acceptez l'invite au premier démarrage +failproofai policies --install # or just run `failproofai` and accept the first-run prompt failproofai ``` -40 politiques intégrées s'activent immédiatement. Tableau de bord disponible sur `localhost:8020`. Désactivez l'invite au premier démarrage avec `FAILPROOFAI_NO_FIRST_RUN=1`. +39 politiques intégrées s'activent immédiatement. Tableau de bord sur `localhost:8020`. Désactivez l'invite de premier démarrage avec `FAILPROOFAI_NO_FIRST_RUN=1`. --- @@ -151,21 +151,20 @@ failproofai | `block-env-files` | La lecture des fichiers `.env` et autres fichiers secrets | | `warn-repeated-tool-calls` | L'agent qui boucle sur le même appel | | `block-sudo` | L'élévation de privilèges | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` sans condition | -| `block-terraform` / `block-kubectl` | Les modifications non examinées sur l'infrastructure en production | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` non borné | +| `block-terraform` / `block-kubectl` | Les modifications non révisées de l'infrastructure en production | | `block-rm-rf` | La suppression récursive de fichiers | | `block-force-push` / `block-push-master` | `git push --force`, les pushs directs vers `main` | -Les cinq premières s'appliquent à tout agent capable d'appeler un outil. Les trois dernières sont les préférées des développeurs — les CLI de développement sont la catégorie d'environnements que nous couvrons le plus en profondeur. +Les cinq premières s'appliquent à tout agent capable d'appeler un outil. Les trois dernières sont les préférées des développeurs — les CLI de codage sont la catégorie d'environnements que nous couvrons le plus en profondeur. -→ [Les 40 politiques intégrées](https://docs.befailproof.ai/policies/builtin) +→ [Les 39 politiques intégrées](https://docs.befailproof.ai/policies/builtin) --- ## Vos propres politiques -Déposez un fichier dans `.failproofai/policies/` — il se charge automatiquement, sans aucun flag. -Commitez-le et toute l'équipe en bénéficie dès le prochain pull. +Déposez un fichier dans `.failproofai/policies/` — il se charge automatiquement, sans aucun flag nécessaire. Committez-le et toute l'équipe l'obtient au prochain pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -185,9 +184,9 @@ Trois décisions disponibles pour chaque politique : | Décision | Effet | |---|---| -| `allow()` | Autoriser l'opération | -| `deny(message)` | La bloquer — le message est renvoyé à l'agent | -| `instruct(message)` | La laisser passer, mais ajouter du contexte à la prochaine invite de l'agent | +| `allow()` | Autorise l'opération | +| `deny(message)` | La bloque — le message est renvoyé à l'agent | +| `instruct(message)` | La laisse passer, mais ajoute du contexte au prochain prompt de l'agent | → [Guide des politiques personnalisées](https://docs.befailproof.ai/policies/custom) @@ -195,15 +194,15 @@ Trois décisions disponibles pour chaque politique : ## Observabilité -L'application des politiques n'est qu'une moitié. L'autre moitié consiste à voir ce que l'agent a réellement fait. +L'application des politiques n'est qu'une moitié. L'autre moitié, c'est voir ce que l'agent a réellement fait. -Lancez `failproofai` sans argument et il sert un tableau de bord sur `localhost:8020` en lisant l'historique d'exécution déjà présent sur votre machine — sans compte, sans inscription, sans rien quitter votre poste. Vous obtenez la liste des sessions, la séquence des appels de modèles, les appels d'outils et les décisions de hook à l'intérieur de chaque exécution, ce qui a été bloqué et ce que la politique a dit à l'agent, ainsi qu'un audit hors ligne (`failproofai audit`) qui analyse votre historique à la recherche de patterns risqués et suggère des politiques pour les arrêter. +Lancez `failproofai` sans argument et il sert un tableau de bord sur `localhost:8020` en lisant l'historique d'exécution déjà présent sur votre machine — sans compte, sans inscription, sans rien qui quitte la machine. Vous obtenez la liste des sessions, la séquence des appels de modèles, les appels d'outils et les décisions des hooks à l'intérieur de chaque exécution, ce qui a été bloqué et ce que la politique a indiqué à l'agent, ainsi qu'un audit hors ligne (`failproofai audit`) qui analyse votre historique à la recherche de patterns risqués et suggère des politiques pour y remédier. → [Tableau de bord local](https://docs.befailproof.ai/reference/local-dashboard) · [Lire une trace](https://docs.befailproof.ai/sessions/read-a-trace) · [Audit local](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** est la version hébergée du même modèle de données, pour les équipes qui exécutent des agents sur une flotte : chaque exécution de chaque environnement en un seul endroit, un graphe d'exécution avec des sous-agents parallèles sur leurs propres voies, la latence p50/p95/p99 pour les modèles, les outils et les hooks, le suivi du coût et de la fenêtre de contexte par modèle, le suivi des erreurs, du SQL sur vos propres traces avec des tableaux de bord partageables, des évaluations notées par votre propre service, des audits planifiés qui transforment les échecs récurrents en conclusions étayées par des preuves, et des alertes routées vers Slack, par e-mail ou via un webhook signé. L'auto-hébergement dans votre propre cluster est disponible avec le plan Enterprise. +**Failproof AI Observability** est le volet hébergé du même modèle de données, pour les équipes qui font tourner des agents sur une flotte de machines : chaque exécution de chaque environnement au même endroit, un graphe d'exécution avec des sous-agents parallèles sur leurs propres lignes, la latence p50/p95/p99 pour les modèles, les outils et les hooks, le suivi des coûts et de la fenêtre de contexte par modèle, le suivi des erreurs, du SQL sur vos propres traces avec des tableaux de bord partageables, des évaluations scorées par votre propre service, des audits planifiés qui transforment les échecs récurrents en constats étayés par des preuves, et des alertes acheminées vers Slack, par e-mail ou via un webhook signé. L'auto-hébergement dans votre propre cluster est disponible sur le plan Entreprise. → [Sessions](https://docs.befailproof.ai/sessions/overview) · [Audits](https://docs.befailproof.ai/audits/overview) · @@ -213,28 +212,28 @@ Lancez `failproofai` sans argument et il sert un tableau de bord sur `localhost: ## Documentation -| Démarrage | | +| Démarrer | | |---|---| | [Démarrage rapide](https://docs.befailproof.ai/start/quickstart) | Installer, connecter un environnement, voir la première exécution | -| [Concepts](https://docs.befailproof.ai/start/concepts) | Comment fonctionne le système de hooks | -| [Environnements pris en charge](https://docs.befailproof.ai/reference/harnesses) | Les 12 environnements et ce que chacun peut appliquer | +| [Concepts](https://docs.befailproof.ai/start/concepts) | Comment le système de hooks fonctionne | +| [Environnements pris en charge](https://docs.befailproof.ai/reference/harnesses) | Les 12 environnements, et ce que chacun peut appliquer | | Observer | | |---|---| | [Sessions](https://docs.befailproof.ai/sessions/overview) | Suivre une exécution : modèles, outils, erreurs, latence | | [Lire une trace](https://docs.befailproof.ai/sessions/read-a-trace) | Ce que le graphe d'exécution vous indique | -| [Audits](https://docs.befailproof.ai/audits/overview) | Identifier les patterns d'échec sur de nombreuses sessions | -| [Tableau de bord local](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, sans compte nécessaire | +| [Audits](https://docs.befailproof.ai/audits/overview) | Identifier des patterns d'échec sur de nombreuses sessions | +| [Tableau de bord local](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, aucun compte requis | -| Appliquer | | +| Appliquer des politiques | | |---|---| -| [Politiques intégrées](https://docs.befailproof.ai/policies/builtin) | Les 40 politiques avec leurs paramètres | +| [Politiques intégrées](https://docs.befailproof.ai/policies/builtin) | Les 39 politiques avec leurs paramètres | | [Politiques personnalisées](https://docs.befailproof.ai/policies/custom) | Écrire les vôtres | | [Configuration](https://docs.befailproof.ai/policies/local-configuration) | Portées de configuration et règles de fusion | | Instrumenter votre propre agent | | |---|---| -| [SDK Python](https://docs.befailproof.ai/reference/custom-agents) | Rapporter les exécutions d'un agent sans environnement d'exécution | +| [SDK Python](https://docs.befailproof.ai/reference/custom-agents) | Remonter les exécutions depuis un agent sans environnement | | [SDK de politiques](https://docs.befailproof.ai/reference/policy-sdk) | Référence `allow` / `deny` / `instruct` | --- @@ -249,9 +248,8 @@ MIT avec [Commons Clause](https://commonsclause.com/) — gratuit pour un usage Voir [CONTRIBUTING.md](../../CONTRIBUTING.md). Nouvelles politiques, cas limites et traductions sont les bienvenus. -> **Compilez avant de commencer.** Exécutez d'abord `bun install && bun run build`. Ce dépôt fait tourner les propres hooks de failproofai sur lui-même, et ils résolvent l'import `failproofai` par rapport au bundle `dist/` compilé — sans compilation, vous obtiendrez des erreurs de hook `Cannot find package 'failproofai'`. Recompilez après avoir modifié `src/`. Voir -> [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Compilez avant de commencer.** Exécutez `bun install && bun run build` en premier. Ce dépôt fait tourner les propres hooks de failproofai sur lui-même, et ils résolvent l'import `failproofai` par rapport au bundle compilé `dist/` — sans compilation, vous obtiendrez des erreurs de hook `Cannot find package 'failproofai'`. Recompilez après avoir modifié `src/`. Voir [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Fait avec ❤️ par [befailproof.ai](https://befailproof.ai) à San Francisco et Bengaluru. +Construit avec ❤️ par [befailproof.ai](https://befailproof.ai) à SF et Bengaluru. diff --git a/docs/i18n/README.he.md b/docs/i18n/README.he.md index d19bb49c..7f0ca936 100644 --- a/docs/i18n/README.he.md +++ b/docs/i18n/README.he.md @@ -22,8 +22,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) -**ניטור והטלת אכיפה לכל קוסם שהסוכנים שלך רצים בו.** -איפה שהסוכנים שלך רצים, אנחנו רואים את זה — ואנחנו יכולים להגיד לא. Failproof מתחבר ל-12 קוסמים של סוכנים — ממשקי שורת פקודה לקידוד כמו Claude Code ו-Codex, שערי צ'אט כמו Hermes, עוזרים ממוחזקים עצמאיים כמו OpenClaw — תופסים כל הרצה וחוסמים קריאות כלים מסוכנות לפני שהן מתבצעות. 40 מדיניות מובנות. זמן אפס. רץ בעמדה מקומית. +**תצפיתיות ואכיפה לכל מנוע שבו רצים הסוכנים שלך.** בכל מקום בו רצים הסוכנים שלך, אנו רואים זאת — ואנו יכולים לסרב. Failproof מתחבר ל-12 מנועי סוכנים — CLIs קידוד כמו Claude Code ו-Codex, שערי צ'אט כמו Hermes, עוזרים מאורחנים עצמיים כמו OpenClaw — תופסים כל הפעלה וחוסמים קריאות כלים מסוכנות לפני ביצוע. 39 מדיניות מובנות. זמן חיתוך אפס. רץ ברמה מקומית. @@ -33,12 +32,11 @@ --- -## קוסמים נתמכים +## מנועים נתמכים -שנים עשר קוסמים בשתי מחלקות — עשרה ממשקי שורת פקודה לקידוד, ושני שערי צ'אט ועוזרים (Hermes, OpenClaw). אותם האירועים, אותן המדיניויות, אותו ההיסטוריה של הפגישה, בכל אחד מהקוסמים שהסוכן שלך רץ בו. +שנים עשר מנועים בשתי מחלקות — עשרה CLIs קידוד, ושני שערי צ'אט ועוזרים (Hermes, OpenClaw). אירועים זהים, מדיניות זהה, היסטוריית סדרה זהה, בכל מנוע בו רץ הסוכן שלך. -סוכנים שרצים בשום אחד מהם מדווחים דרך [Python SDK](https://docs.befailproof.ai/reference/custom-agents), -שנותן לך עקבוב, פגישות וביקורות. אכיפה שם דורשת קרס בזמן ריצה שלך — [שדברו אלינו](mailto:support@befailproof.ai) והנו נמפה את זה. +סוכנים הרצים בשום אחד מהם מדווחים דרך [Python SDK](https://docs.befailproof.ai/reference/custom-agents), שמעניק לך עקיבה, סדרות וביקורות. אכיפה שם דורשת hook בקרנטיים שלך — [דברו איתנו](mailto:support@befailproof.ai) ותחול אותה. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -138,11 +136,11 @@ ```sh npm install -g failproofai -failproofai policies --install +failproofai policies --install # או פשוט הרץ `failproofai` וקבל את ההנחיה של ההפעלה הראשונה failproofai ``` -40 מדיניויות מובנות מופעלות מיידית. לוח בקרה ב-`localhost:8020`. השבת את הנושא בהרצה ראשונה עם `FAILPROOFAI_NO_FIRST_RUN=1`. +39 מדיניות מובנות מופעלות מיד. לוח בקרה ב-`localhost:8020`. השבת את הנחיית ההפעלה הראשונה עם `FAILPROOFAI_NO_FIRST_RUN=1`. --- @@ -150,25 +148,24 @@ failproofai | מדיניות | מה היא חוסמת | |---|---| -| `sanitize-api-keys` | מפתחות API שדולפים להקשר של הסוכן | -| `block-env-files` | קריאות של קבצי `.env` וקבצי סודות אחרים | -| `warn-repeated-tool-calls` | הסוכן עוקף את אותה הקריאה | +| `sanitize-api-keys` | מפתחות API דולפים להקשר של הסוכן | +| `block-env-files` | קריאות של `.env` וקבצי סודות אחרים | +| `warn-repeated-tool-calls` | הסוכן נתקע בקרא אותה | | `block-sudo` | הסלמת הרשאות | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` ללא גבול | -| `block-terraform` / `block-kubectl` | שינויים ללא ביקורת לתשתית חיה | -| `block-rm-rf` | מחיקה רקורסיבית של קבצים | -| `block-force-push` / `block-push-master` | `git push --force`, דחיפה ישירה ל-`main` | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, unbounded `DELETE` | +| `block-terraform` / `block-kubectl` | שינויים שלא נבדקו לתשתית חיה | +| `block-rm-rf` | מחיקת קבצים רקורסיבית | +| `block-force-push` / `block-push-master` | `git push --force`, push ישיר ל-`main` | -חמשת הראשונים חלים על כל סוכן שיכול לקרוא לכלי. השלוש אחרונות הן אהובות על המפתחים — ממשקי שורת פקודה לקידוד הם מחלקת הקוסם שאנחנו מכסים את העומק ביותר. +חמשת הראשונים חלים על כל סוכן שיכול להתקשר לכלי. שלוש האחרונות הן המועדפות של מפתחים — CLIs קידוד הם מחלקת ה-harness בה אנו מכסים בעומק הרבה ביותר. -→ [כל 40 המדיניויות המובנות](https://docs.befailproof.ai/policies/builtin) +→ [כל 39 המדיניות המובנות](https://docs.befailproof.ai/policies/builtin) --- -## המדיניויות שלך +## המדיניות שלך -שחרר קובץ ל-`.failproofai/policies/` — הוא טוען באופן אוטומטי, אין צורך בדגלים. -העלו את זה והצוות כולו מקבל את זה בשלימת הבא. +הנח קובץ ל-`.failproofai/policies/` — הוא נטען באופן אוטומטי, ללא דגלים נדרשים. בצע commit אותו והצוות כולו יקבל אותו ב-pull הבא. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -186,43 +183,31 @@ customPolicies.add({ שלוש החלטות זמינות לכל מדיניות: -| החלטה | השפעה | +| החלטה | אפקט | |---|---| | `allow()` | אפשר את הפעולה | -| `deny(message)` | חסום את זה — ההודעה חוזרת לסוכן | -| `instruct(message)` | תן את זה דרך, אבל הוסף הקשר להנמקה הבאה של הסוכן | +| `deny(message)` | חסום זאת — ההודעה חוזרת לסוכן | +| `instruct(message)` | תן לזה עבור, אך הוסף הקשר לנושא הבא של הסוכן | -→ [מדריך מדיניויות מותאמות](https://docs.befailproof.ai/policies/custom) +→ [מדריך המדיניות המותאמת](https://docs.befailproof.ai/policies/custom) --- -## ניטור +## תצפיתיות -אכיפה היא חצי אחד. החצי השני הוא לראות מה הסוכן בעצם עשה. +אכיפה היא חצי אחד. החצי השני הוא ראיית מה הסוכן בעצם עשה. -הרץ `failproofai` ללא ארגומנטים והוא משרת לוח בקרה ב-`localhost:8020` -קורא את היסטוריית הריצה כבר במכונה שלך — אין חשבון, אין הרשמה, שום דבר -עוזב את הקופסה. אתה מקבל את רשימת הפגישות, את הרצף של קריאות דגם, קריאות כלים -והחלטות קרס בתוך כל הרצה, מה חוסם ומה המדיניות אמרה לסוכן, -וביקורת בעבודה קשה (`failproofai audit`) שסורקת את ההיסטוריה שלך לדפוסים מסוכנים -ומציעה מדיניויות לעצירתם. +הרץ את `failproofai` ללא ארגומנטים ויש לו לשרת לוח בקרה ב-`localhost:8020` קורא את היסטוריית הריצה שכבר קיימת במכונה שלך — אין חשבון, אין הרשמה, כלום לא עוזב את הקופסה. אתה מקבל את רשימת הסדרה, את הרצף של קריאות דגם, קריאות כלים וקבלת החלטות hook בתוך כל ריצה, מה שנחסם ומה המדיניות אמרה לסוכן, וביקורת לא מקוונת (`failproofai audit`) שסורקת את היסטוריה שלך לדפוסים מסוכנים וממליצה על מדיניות לעצור אותם. → [לוח בקרה מקומי](https://docs.befailproof.ai/reference/local-dashboard) · -[קראו עקבוב](https://docs.befailproof.ai/sessions/read-a-trace) · +[קרא עקבות](https://docs.befailproof.ai/sessions/read-a-trace) · [ביקורת מקומית](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** היא הצד המארח של אותו מודל נתונים, לצוותים -המריצים סוכנים על פני צי: כל ריצה מכל קוסם במקום אחד, גרף ביצוע עם תת-סוכנים מקבילים -בנתיבים שלהם, זמן פעולה p50/p95/p99 לדגמים, כלים וקרסים, -עלות לכל דגם ועקבוב חלון הקשר, עקבוב שגיאות, SQL על העקבות שלך -עם לוחות בקרה ניתנים לשיתוף, הערכות המדורגות על ידי השירות שלך, -ביקורות מתוזמנות המהפכות כשלים חוזרים לממצאים המבוססים על עדויות, -והתנעות המנותבות ל-Slack, דוא"ל או webhook חתום. אירוח עצמי בקבוצה שלך -זמין בתוכנית Enterprise. +**Failproof AI Observability** היא הצד המעונן של אותו מודל נתונים, לצוותים שמפעילים סוכנים על פני צי: כל ריצה מכל harness במקום אחד, גרף הביצוע עם תת-סוכנים מקבילים בנתיביהם שלהם, p50/p95/p99 חביון לדגמים, כלים והוקים, עלות לפי דגם ועקיבת חלון הקשר, עקיבת שגיאות, SQL על עקבותיך שלך עם לוחות בקרה שניתן לשתף, הערכות שדורגו על ידי השירות שלך, ביקורות מתוזמנות שהופכות כשלים חוזרים להוכחות, והתריעות שמקובלות ל-Slack, דוא"ל או webhook חתום. Self-hosting בקלאסטר שלך זמין בתוכנית Enterprise. -→ [פגישות](https://docs.befailproof.ai/sessions/overview) · +→ [סדרות](https://docs.befailproof.ai/sessions/overview) · [ביקורות](https://docs.befailproof.ai/audits/overview) · -[הזמנת הדגמה](https://befailproof.ai/get-a-demo) +[הזמן הדגמה](https://befailproof.ai/get-a-demo) --- @@ -230,49 +215,45 @@ customPolicies.add({ | התחל | | |---|---| -| [התחלה מהירה](https://docs.befailproof.ai/start/quickstart) | התקנה, חיבור קוסם, ראה את ההרצה הראשונה | -| [קונספטים](https://docs.befailproof.ai/start/concepts) | איך מערכת הקרס עובדת | -| [קוסמים נתמכים](https://docs.befailproof.ai/reference/harnesses) | כל 12, ומה כל אחד יכול להטיל | +| [התחלה מהירה](https://docs.befailproof.ai/start/quickstart) | התקנה, חיבור harness, ראה את הריצה הראשונה | +| [קונספטים](https://docs.befailproof.ai/start/concepts) | כיצד מערכת ה-hook עובדת | +| [Harnesses נתמכים](https://docs.befailproof.ai/reference/harnesses) | כל 12, ומה כל אחד יכול לאכוף | -| לראות | | +| תצפיתיות | | |---|---| -| [פגישות](https://docs.befailproof.ai/sessions/overview) | עקוב אחר הרצה: דגמים, כלים, שגיאות, זמן פעולה | -| [קראו עקבוב](https://docs.befailproof.ai/sessions/read-a-trace) | מה גרף הביצוע אומר לך | -| [ביקורות](https://docs.befailproof.ai/audits/overview) | מצא דפוסי כשל על פני הרבה פגישות | +| [סדרות](https://docs.befailproof.ai/sessions/overview) | עקוב אחרי ריצה: דגמים, כלים, שגיאות, זמן חביון | +| [קרא עקבות](https://docs.befailproof.ai/sessions/read-a-trace) | מה גרף ההביצוע אומר לך | +| [ביקורות](https://docs.befailproof.ai/audits/overview) | מצא דפוסי כשל על פני הרבה סדרות | | [לוח בקרה מקומי](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, אין צורך בחשבון | -| הטל | | +| אכיפה | | |---|---| -| [מדיניויות מובנות](https://docs.befailproof.ai/policies/builtin) | כל 40 המדיניויות עם פרמטרים | -| [מדיניויות מותאמות](https://docs.befailproof.ai/policies/custom) | כתוב שלך | -| [תצורה](https://docs.befailproof.ai/policies/local-configuration) | טווחי תצורה וכללי מיזוג | +| [מדיניות מובנות](https://docs.befailproof.ai/policies/builtin) | כל 39 המדיניות עם פרמטרים | +| [מדיניות מותאמת](https://docs.befailproof.ai/policies/custom) | כתוב שלך שלך | +| [תצורה](https://docs.befailproof.ai/policies/local-configuration) | היקפי תצורה וכללי מיזוג | -| הנתק את הסוכן שלך | | +| כלים את הסוכן שלך | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | דוח הריצות מסוכן ללא קוסם | -| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | התייחסות `allow` / `deny` / `instruct` | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | דווח על הרצות מסוכן ללא harness | +| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` reference | --- ## רישיון -MIT עם [Commons Clause](https://commonsclause.com/) — חופשי לשימוש פנימי והשימוש אישי; מכירה מסחרית של failproofai עצמו דורשת הסכם נפרד. ראה [LICENSE](../../LICENSE) לטקסט המלא. +MIT עם [Commons Clause](https://commonsclause.com/) — חינם לשימוש פנימי ואישי; מכירה מסחרית של failproofai עצמו דורשת הסכם נפרד. ראה [LICENSE](../../LICENSE) לטקסט המלא. --- ## תרומה -ראה [CONTRIBUTING.md](../../CONTRIBUTING.md). מדיניויות חדשות, מקרי קצה, ותרגומים כולם מרוחקים. +ראה [CONTRIBUTING.md](../../CONTRIBUTING.md). מדיניות חדשות, קצוות קיצון, ותרגומים כולם ברוכים הבאים. -> **בנה לפני שתתחיל.** הרץ `bun install && bun run build` תחילה. ריפו זה מריץ -> את הקרסים שלו על עצמו, והם פותרים את ה-`failproofai` import מול -> ה-`dist/` bundle המורכב — ללא בנייה תפגע בשגיאות קרס `Cannot find package 'failproofai'`. -> בנה מחדש לאחר שינוי `src/`. ראה -> [בנה לפני שקרסי dev בתוך הריפו יעבדו](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **בנה לפני שתתחיל.** הרץ `bun install && bun run build` תחילה. ריפו זה מריץ את ה-hooks של failproofai שלו בעצמו, והם פותרים את ה-import של `failproofai` לעומת ה-bundle של `dist/` שהורכב — ללא build אתה תפגע בשגיאות hook של `Cannot find package 'failproofai'`. בנה מחדש לאחר שינוי ב-`src/`. ראה [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -בנוי עם ❤️ על ידי [befailproof.ai](https://befailproof.ai) ב-SF ו-Bengaluru. +בנויה עם ❤️ על ידי [befailproof.ai](https://befailproof.ai) ב-SF וב-Bengaluru. \ No newline at end of file diff --git a/docs/i18n/README.hi.md b/docs/i18n/README.hi.md index c99c9126..f3202bf3 100644 --- a/docs/i18n/README.hi.md +++ b/docs/i18n/README.hi.md @@ -20,11 +20,8 @@ **अनुवाद:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**हर harness के लिए निरीक्षण और प्रवर्तन जहाँ आपके agents चलते हैं।** -जहाँ भी आपके agents चलते हैं, हम देख सकते हैं — और हम मना कर सकते हैं। Failproof 12 agent -harnesses को hook करता है — Claude Code और Codex जैसे coding CLIs, Hermes जैसे chat -gateways, OpenClaw जैसे self-hosted assistants — हर run को capture करता है और -खतरनाक tool calls को execute होने से पहले रोकता है। 40 built-in policies। Zero latency। Locally चलता है। +**आपके एजेंट्स द्वारा चलाए जाने वाले हर हार्नेस के लिए अवलोकन और प्रवर्तन।** +जहाँ भी आपके एजेंट्स चलते हैं, हम उन्हें देखते हैं — और हम ना कह सकते हैं। Failproof 12 एजेंट हार्नेस को हुक करता है — कोडिंग CLIs जैसे Claude Code और Codex, चैट गेटवे जैसे Hermes, सेल्फ-होस्टेड असिस्टेंट्स जैसे OpenClaw — हर चलाव को कैप्चर करता है और खतरनाक टूल कॉल्स को निष्पादन से पहले ब्लॉक करता है। 39 बिल्ट-इन पॉलिसीज़। शून्य लेटेंसी। स्थानीय रूप से चलता है। @@ -34,15 +31,11 @@ gateways, OpenClaw जैसे self-hosted assistants — हर run को cap --- -## समर्थित harnesses +## समर्थित हार्नेस -दो classes में बारह harnesses — दस coding CLIs, और दो chat और assistant -gateways (Hermes, OpenClaw)। एक जैसी events, एक जैसी policies, एक जैसी session history, -चाहे आपका agent उनमें से कोई भी हो। +दो वर्गों में बारह हार्नेस — दस कोडिंग CLIs, और दो चैट और असिस्टेंट गेटवे (Hermes, OpenClaw)। समान इवेंट्स, समान पॉलिसीज़, समान सेशन हिस्ट्री, भले ही आपका एजेंट किसी में भी चले। -Agents जो इनमें से किसी में भी नहीं चलते वे [Python SDK](https://docs.befailproof.ai/reference/custom-agents) के -माध्यम से report करते हैं, जो आपको tracing, sessions और audits देता है। वहाँ प्रवर्तन के लिए आपके -own runtime में एक hook की जरूरत है — [हमसे बात करें](mailto:support@befailproof.ai) और हम इसे map कर देंगे। +जो एजेंट्स इनमें से किसी में भी नहीं चलते, वे [Python SDK](https://docs.befailproof.ai/reference/custom-agents) के माध्यम से रिपोर्ट करते हैं, जो आपको ट्रेसिंग, सेशन्स और ऑडिट्स देता है। वहाँ प्रवर्तन के लिए आपके स्वयं के रनटाइम में एक हुक की आवश्यकता है — [हमसे बात करें](mailto:support@befailproof.ai) और हम इसे मैप करेंगे। {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -138,42 +131,40 @@ own runtime में एक hook की जरूरत है — [हमस -## स्थापना +## इंस्टॉल करें ```sh npm install -g failproofai -failproofai policies --install # या बस `failproofai` चलाएँ और पहली बार के प्रॉम्प्ट को स्वीकार करें +failproofai policies --install # या बस `failproofai` चलाएं और पहली बार के प्रॉम्प्ट को स्वीकार करें failproofai ``` -40 built-in policies तुरंत सक्रिय हो जाती हैं। Dashboard `localhost:8020` पर है। पहली बार के प्रॉम्प्ट को `FAILPROOFAI_NO_FIRST_RUN=1` से अक्षम करें। +39 बिल्ट-इन पॉलिसीज़ तुरंत सक्रिय हो जाती हैं। डैशबोर्ड `localhost:8020` पर। पहली बार के प्रॉम्प्ट को `FAILPROOFAI_NO_FIRST_RUN=1` के साथ अक्षम करें। --- ## यह क्या रोकता है -| Policy | क्या यह ब्लॉक करता है | +| पॉलिसी | यह क्या ब्लॉक करता है | |---|---| -| `sanitize-api-keys` | API keys का agent के context में leak होना | -| `block-env-files` | `.env` और अन्य secret files का read होना | -| `warn-repeated-tool-calls` | Agent का एक ही call पर loop करना | -| `block-sudo` | Privilege escalation | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, unbounded `DELETE` | -| `block-terraform` / `block-kubectl` | Live infrastructure में unreviewed changes | -| `block-rm-rf` | Recursive file deletion | -| `block-force-push` / `block-push-master` | `git push --force`, `main` को direct pushes | +| `sanitize-api-keys` | एजेंट के कॉन्टेक्स्ट में एपीआई कीज़ का लीक होना | +| `block-env-files` | `.env` और अन्य गुप्त फ़ाइलों को पढ़ना | +| `warn-repeated-tool-calls` | एजेंट का एक ही कॉल पर लूप करना | +| `block-sudo` | प्रिविलेज एस्केलेशन | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, अनबाउंडेड `DELETE` | +| `block-terraform` / `block-kubectl` | लाइव इंफ्रास्ट्रक्चर में अनरिव्यूड परिवर्तन | +| `block-rm-rf` | रिकर्सिव फ़ाइल डिलीशन | +| `block-force-push` / `block-push-master` | `git push --force`, `main` को सीधे पुश | -पहली पाँच किसी भी agent पर लागू होती हैं जो एक tool को call कर सकता है। अंतिम तीन -developer पसंदीदा हैं — coding CLIs वह harness class हैं जिसे हम सबसे गहराई से cover करते हैं। +पहली पाँच किसी भी एजेंट पर लागू होती हैं जो टूल कॉल कर सकता है। अंतिम तीन डेवलपर के पसंदीदा हैं — कोडिंग CLIs वह हार्नेस क्लास है जिसे हम सबसे गहराई से कवर करते हैं। -→ [सभी 40 built-in policies](https://docs.befailproof.ai/policies/builtin) +→ [सभी 39 बिल्ट-इन पॉलिसीज़](https://docs.befailproof.ai/policies/builtin) --- -## आपकी अपनी policies +## आपकी अपनी पॉलिसीज़ -`.failproofai/policies/` में एक फाइल डालें — यह automatically load हो जाती है, कोई flags की जरूरत नहीं। -इसे commit करें और पूरी team को अगले pull पर यह मिल जाएगी। +`.failproofai/policies/` में एक फ़ाइल ड्रॉप करें — यह स्वचालित रूप से लोड होती है, कोई फ्लैग की आवश्यकता नहीं है। इसे कमिट करें और पूरी टीम को अगले पुल पर यह मिलेगा। ```js import { customPolicies, deny, allow } from "failproofai"; @@ -189,90 +180,72 @@ customPolicies.add({ }); ``` -हर policy के लिए तीन निर्णय उपलब्ध हैं: +हर पॉलिसी के लिए तीन निर्णय उपलब्ध हैं: | निर्णय | प्रभाव | |---|---| -| `allow()` | Operation को permit करें | -| `deny(message)` | इसे ब्लॉक करें — message agent को वापस जाता है | -| `instruct(message)` | इसे through होने दें, लेकिन agent के अगले prompt में context जोड़ें | +| `allow()` | ऑपरेशन को अनुमति दें | +| `deny(message)` | इसे ब्लॉक करें — संदेश एजेंट को वापस जाता है | +| `instruct(message)` | इसे अनुमति दें, लेकिन एजेंट के अगले प्रॉम्प्ट में कॉन्टेक्स्ट जोड़ें | -→ [Custom policies guide](https://docs.befailproof.ai/policies/custom) +→ [कस्टम पॉलिसीज़ गाइड](https://docs.befailproof.ai/policies/custom) --- -## निरीक्षण +## अवलोकन -प्रवर्तन एक आधा है। दूसरा आधा यह देखना है कि agent ने वास्तव में क्या किया। +प्रवर्तन एक आधा है। दूसरा आधा यह देखना है कि एजेंट ने वास्तव में क्या किया। -बिना किसी argument के `failproofai` चलाएँ और यह `localhost:8020` पर एक dashboard serve करता है -जो आपकी machine पर पहले से मौजूद run history को read करता है — कोई account नहीं, कोई signup नहीं, कुछ भी -बाहर नहीं जाता। आपको session list, हर run के अंदर model calls, tool calls और hook decisions का sequence, -क्या block किया गया और policy ने agent को क्या बताया, और एक offline audit (`failproofai audit`) जो -आपके history को risky patterns के लिए scan करता है और policies सुझाता है उन्हें रोकने के लिए। +बिना किसी तर्क के `failproofai` चलाएं और यह `localhost:8020` पर एक डैशबोर्ड परोसता है जो आपकी मशीन पर पहले से मौजूद रन हिस्ट्री को पढ़ता है — कोई अकाउंट, कोई साइनअप, कुछ भी बॉक्स से बाहर नहीं जाता। आप सेशन लिस्ट, हर रन के अंदर मॉडल कॉल्स, टूल कॉल्स और हुक डिसिजन्स का अनुक्रम, क्या ब्लॉक किया गया और पॉलिसी ने एजेंट को क्या बताया, और एक ऑफलाइन ऑडिट (`failproofai audit`) देखते हैं जो आपकी हिस्ट्री को जोखिम भरे पैटर्न के लिए स्कैन करता है और पॉलिसीज़ सुझाता है उन्हें रोकने के लिए। -→ [Local dashboard](https://docs.befailproof.ai/reference/local-dashboard) · -[एक trace पढ़ें](https://docs.befailproof.ai/sessions/read-a-trace) · -[Local audit](https://docs.befailproof.ai/audits/local-audit) +→ [लोकल डैशबोर्ड](https://docs.befailproof.ai/reference/local-dashboard) · [ट्रेस पढ़ें](https://docs.befailproof.ai/sessions/read-a-trace) · [लोकल ऑडिट](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** एक team के लिए hosted side है जो एक fleet में agents चला रहे हैं: -हर harness से हर run एक ही जगह, parallel sub-agents के अपने lanes के साथ एक execution graph, -models, tools और hooks के लिए p50/p95/p99 latency, per-model cost और context-window tracking, error -tracking, आपके own traces पर SQL shareable dashboards के साथ, आपकी own service द्वारा scored -evaluations, scheduled audits जो recurring failures को evidence-backed findings में turn करते हैं, -और alerts जो Slack, email या एक signed webhook को route करते हैं। आपके own cluster में self-hosting -Enterprise plan पर उपलब्ध है। +**Failproof AI अवलोकन** एक ही डेटा मॉडल का होस्टेड हिस्सा है, एजेंट्स को एक फ्लीट में चलाने वाली टीमों के लिए: हर हार्नेस से हर रन एक जगह में, समानांतर सब-एजेंट्स के साथ एक निष्पादन ग्राफ उनकी अपनी लेन में, मॉडल्स, टूल्स और हुक्स के लिए p50/p95/p99 लेटेंसी, प्रति-मॉडल लागत और कॉन्टेक्स्ट-विंडो ट्रैकिंग, एरर ट्रैकिंग, आपके स्वयं के ट्रेस्स पर SQL शेयरेबल डैशबोर्ड के साथ, आपकी स्वयं की सेवा द्वारा स्कोर किए गए इवैल्यूएशन्स, शेड्यूल किए गए ऑडिट्स जो आवर्ती विफलताओं को साक्ष्य-समर्थित निष्कर्षों में बदलते हैं, और Slack, ईमेल या एक हस्ताक्षरित वेबहुक को रूट किए गए अलर्ट। आपके अपने क्लस्टर में सेल्फ-होस्टिंग एंटरप्राइज प्लान पर उपलब्ध है। -→ [Sessions](https://docs.befailproof.ai/sessions/overview) · -[Audits](https://docs.befailproof.ai/audits/overview) · -[एक demo बुक करें](https://befailproof.ai/get-a-demo) +→ [सेशन्स](https://docs.befailproof.ai/sessions/overview) · [ऑडिट्स](https://docs.befailproof.ai/audits/overview) · [डेमो बुक करें](https://befailproof.ai/get-a-demo) --- -## Documentation +## प्रलेखन | शुरुआत करें | | |---|---| -| [Quickstart](https://docs.befailproof.ai/start/quickstart) | Install करें, एक harness को connect करें, पहला run देखें | -| [Concepts](https://docs.befailproof.ai/start/concepts) | Hook system कैसे काम करता है | -| [समर्थित harnesses](https://docs.befailproof.ai/reference/harnesses) | सभी 12, और हर एक क्या enforce कर सकता है | +| [क्विकस्टार्ट](https://docs.befailproof.ai/start/quickstart) | इंस्टॉल करें, एक हार्नेस कनेक्ट करें, पहला रन देखें | +| [अवधारणाएं](https://docs.befailproof.ai/start/concepts) | हुक सिस्टम कैसे काम करता है | +| [समर्थित हार्नेस](https://docs.befailproof.ai/reference/harnesses) | सभी 12, और हर एक क्या प्रवर्तन कर सकता है | -| निरीक्षण करें | | +| अवलोकन करें | | |---|---| -| [Sessions](https://docs.befailproof.ai/sessions/overview) | एक run को follow करें: models, tools, errors, latency | -| [एक trace पढ़ें](https://docs.befailproof.ai/sessions/read-a-trace) | Execution graph आपको क्या बता रहा है | -| [Audits](https://docs.befailproof.ai/audits/overview) | कई sessions में failure patterns खोजें | -| [Local dashboard](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, कोई account की जरूरत नहीं | +| [सेशन्स](https://docs.befailproof.ai/sessions/overview) | एक रन को फॉलो करें: मॉडल्स, टूल्स, एरर्स, लेटेंसी | +| [ट्रेस पढ़ें](https://docs.befailproof.ai/sessions/read-a-trace) | निष्पादन ग्राफ आपको क्या बता रहा है | +| [ऑडिट्स](https://docs.befailproof.ai/audits/overview) | कई सेशन्स में विफलता पैटर्न खोजें | +| [लोकल डैशबोर्ड](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, कोई अकाउंट की आवश्यकता नहीं | | प्रवर्तन करें | | |---|---| -| [Built-in policies](https://docs.befailproof.ai/policies/builtin) | सभी 40 policies parameters के साथ | -| [Custom policies](https://docs.befailproof.ai/policies/custom) | अपनी खुद की policies लिखें | -| [Configuration](https://docs.befailproof.ai/policies/local-configuration) | Config scopes और merge rules | +| [बिल्ट-इन पॉलिसीज़](https://docs.befailproof.ai/policies/builtin) | सभी 39 पॉलिसीज़ पैरामीटर्स के साथ | +| [कस्टम पॉलिसीज़](https://docs.befailproof.ai/policies/custom) | अपनी अपनी पॉलिसीज़ लिखें | +| [कॉन्फ़िगरेशन](https://docs.befailproof.ai/policies/local-configuration) | कॉन्फ़िग स्कोप्स और मर्ज नियम | -| अपने agent को instrument करें | | +| अपने स्वयं के एजेंट को इंस्ट्रूमेंट करें | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | कोई harness वाले agent से runs report करें | -| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` reference | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | कोई हार्नेस न होने वाले एजेंट से रन रिपोर्ट करें | +| [पॉलिसी SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` संदर्भ | --- ## लाइसेंस -MIT with [Commons Clause](https://commonsclause.com/) — internal और personal use के लिए free; failproofai -के commercial resale के लिए एक separate agreement की जरूरत है। पूरे text के लिए [LICENSE](../../LICENSE) देखें। +MIT with [Commons Clause](https://commonsclause.com/) — आंतरिक और व्यक्तिगत उपयोग के लिए निःशुल्क; failproofai स्वयं के वाणिज्यिक पुनर्विक्रय के लिए एक अलग समझौते की आवश्यकता है। पूर्ण पाठ के लिए [LICENSE](../../LICENSE) देखें। --- -## योगदान +## योगदान देना -[CONTRIBUTING.md](../../CONTRIBUTING.md) देखें। नई policies, edge cases, और translations सभी स्वागत हैं। +[CONTRIBUTING.md](../../CONTRIBUTING.md) देखें। नई पॉलिसीज़, एज केसेस, और अनुवाद सभी स्वागत हैं। -> **शुरू करने से पहले build करें।** पहले `bun install && bun run build` चलाएँ। यह repo failproofai की अपनी -> hooks को अपने पर चलाता है, और वे `failproofai` import को compiled `dist/` bundle के विरुद्ध resolve करते हैं — -> build के बिना आपको `Cannot find package 'failproofai'` hook errors का सामना करना पड़ेगा। `src/` को -> बदलने के बाद rebuild करें। [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) देखें। +> **शुरुआत करने से पहले बिल्ड करें।** पहले `bun install && bun run build` चलाएं। यह रेपो failproofai की अपनी हुक्स को स्वयं पर चलाता है, और वे कंपाइल किए गए `dist/` बंडल के विरुद्ध `failproofai` आयात को हल करते हैं — बिल्ड के बिना आप `Cannot find package 'failproofai'` हुक एरर्स से टकराएंगे। `src/` बदलने के बाद रीबिल्ड करें। [इन-रेपो डेव हुक्स काम करने के लिए पहले बिल्ड करें](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) देखें। --- -SF और Bengaluru में [befailproof.ai](https://befailproof.ai) द्वारा ❤️ के साथ built। +SF और बेंगलुरु में [befailproof.ai](https://befailproof.ai) द्वारा ❤️ के साथ बनाया गया। diff --git a/docs/i18n/README.it.md b/docs/i18n/README.it.md index 249498bd..bfa6973a 100644 --- a/docs/i18n/README.it.md +++ b/docs/i18n/README.it.md @@ -20,22 +20,22 @@ **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) -**Osservabilità e applicazione per ogni esecuzione dei tuoi agenti.** -Ovunque gli agenti vengono eseguiti, noi li vediamo — e possiamo dire di no. Failproof si aggancia a 12 ambienti di esecuzione per agenti — CLI di codifica come Claude Code e Codex, gateway di chat come Hermes, assistenti self-hosted come OpenClaw — catturando ogni esecuzione e bloccando le chiamate di strumenti pericolose prima che vengano eseguite. 40 politiche integrate. Latenza zero. Esecuzione locale. +**Osservabilità e controllo per ogni harness in cui i tuoi agenti vengono eseguiti.** +Ovunque i tuoi agenti vengono eseguiti, li vediamo — e possiamo dire no. Failproof aggancia 12 harness per agenti — CLI di coding come Claude Code e Codex, gateway di chat come Hermes, assistenti self-hosted come OpenClaw — catturando ogni esecuzione e bloccando le chiamate di strumento pericolose prima che vengano eseguite. 39 policy built-in. Zero latenza. Viene eseguito localmente.

- Failproof AI in action + Failproof AI in azione

--- -## Ambienti di esecuzione supportati +## Harness supportati -Dodici ambienti in due categorie — dieci CLI di codifica e due gateway di chat e assistenti (Hermes, OpenClaw). Gli stessi eventi, le stesse politiche, la stessa cronologia delle sessioni, indipendentemente da quale ambiente il tuo agente utilizza. +Dodici harness in due classi — dieci CLI di coding e due gateway di chat e assistente (Hermes, OpenClaw). Gli stessi eventi, le stesse policy, lo stesso cronologia delle sessioni, indipendentemente da quale harness il tuo agente utilizza. -Gli agenti che non vengono eseguiti in nessuno di questi si collegano tramite l'[SDK Python](https://docs.befailproof.ai/reference/custom-agents), che ti offre tracciamento, sessioni e audit. L'applicazione lì richiede un hook nel tuo runtime — [contattaci](mailto:support@befailproof.ai) e lo mapperemo. +Gli agenti che non vengono eseguiti in nessuno di questi riferiscono attraverso [Python SDK](https://docs.befailproof.ai/reference/custom-agents), che ti offre tracciamento, sessioni e audit. L'enforcement lì richiede un hook nel tuo runtime — [contattaci](mailto:support@befailproof.ai) e lo mapperemo. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,37 +135,37 @@ Gli agenti che non vengono eseguiti in nessuno di questi si collegano tramite l' ```sh npm install -g failproofai -failproofai policies --install # oppure esegui `failproofai` e accetta il prompt al primo avvio +failproofai policies --install # oppure esegui solo `failproofai` e accetta il prompt al primo utilizzo failproofai ``` -40 politiche integrate si attivano immediatamente. Dashboard su `localhost:8020`. Disabilita il prompt al primo avvio con `FAILPROOFAI_NO_FIRST_RUN=1`. +39 policy built-in si attivano immediatamente. Dashboard su `localhost:8020`. Disabilita il prompt al primo utilizzo con `FAILPROOFAI_NO_FIRST_RUN=1`. --- ## Cosa blocca -| Politica | Cosa blocca | +| Policy | Cosa blocca | |---|---| -| `sanitize-api-keys` | Perdite di chiavi API nel contesto dell'agente | -| `block-env-files` | Letture di `.env` e altri file segreti | -| `warn-repeated-tool-calls` | L'agente che si blocca sulla stessa chiamata | +| `sanitize-api-keys` | Chiavi API che trapelano nel contesto dell'agente | +| `block-env-files` | Letture di `.env` e altri file di segreti | +| `warn-repeated-tool-calls` | L'agente in loop sulla stessa chiamata | | `block-sudo` | Escalation dei privilegi | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` illimitati | -| `block-terraform` / `block-kubectl` | Modifiche non riviste all'infrastruttura in produzione | -| `block-rm-rf` | Cancellazione ricorsiva di file | -| `block-force-push` / `block-push-master` | `git push --force`, push diretti a `main` | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` senza limiti | +| `block-terraform` / `block-kubectl` | Modifiche non revisionate all'infrastruttura live | +| `block-rm-rf` | Eliminazione ricorsiva di file | +| `block-force-push` / `block-push-master` | `git push --force`, spinte dirette a `main` | -I primi cinque si applicano a qualsiasi agente che possa chiamare uno strumento. Gli ultimi tre sono i preferiti dagli sviluppatori — le CLI di codifica sono la categoria di ambienti che copriamo più a fondo. +I primi cinque si applicano a qualsiasi agente che possa chiamare uno strumento. Gli ultimi tre sono i preferiti degli sviluppatori — i CLI di coding sono la classe di harness che copriamo più in profondità. -→ [Tutte e 40 le politiche integrate](https://docs.befailproof.ai/policies/builtin) +→ [Tutte le 39 policy built-in](https://docs.befailproof.ai/policies/builtin) --- -## Le tue politiche personali +## Le tue policy -Rilascia un file in `.failproofai/policies/` — si carica automaticamente, non servono flag. -Eseguine il commit e l'intero team lo riceverà al prossimo pull. +Copia un file in `.failproofai/policies/` — viene caricato automaticamente, non sono necessari flag. +Eseguine il commit e il team intero lo otterrà al prossimo pull. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -175,35 +175,36 @@ customPolicies.add({ match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolInput?.file_path?.includes("production")) - return deny("Writes to production paths are blocked."); + return deny("Le scritture nei percorsi di produzione sono bloccate."); return allow(); }, }); ``` -Tre decisioni disponibili per ogni politica: +Tre decisioni disponibili per ogni policy: | Decisione | Effetto | |---|---| | `allow()` | Consenti l'operazione | | `deny(message)` | Bloccala — il messaggio torna all'agente | -| `instruct(message)` | Lasciala passare, ma aggiungi contesto al prossimo prompt dell'agente | +| `instruct(message)` | Lasciarla passare, ma aggiungi contesto al prossimo prompt dell'agente | -→ [Guida alle politiche personalizzate](https://docs.befailproof.ai/policies/custom) +→ [Guida alle policy personalizzate](https://docs.befailproof.ai/policies/custom) --- ## Osservabilità -L'applicazione è una metà. L'altra metà è vedere cosa ha veramente fatto l'agente. +L'enforcement è una metà. L'altra metà è vedere quello che l'agente ha effettivamente fatto. -Esegui `failproofai` senza argomenti e servirà un dashboard su `localhost:8020` leggendo la cronologia delle esecuzioni già presente sulla tua macchina — nessun account, nessuna registrazione, nulla che esce dal sistema. Ottieni l'elenco delle sessioni, la sequenza di chiamate di modello, chiamate di strumenti e decisioni di hook all'interno di ogni esecuzione, cosa è stato bloccato e cosa la politica ha detto all'agente, e un audit offline (`failproofai audit`) che scansiona la tua cronologia per modelli rischiosi e suggerisce politiche per bloccarli. +Esegui `failproofai` senza argomenti e serve un dashboard su `localhost:8020` +leggendo la cronologia delle esecuzioni già presente sulla tua macchina — nessun account, nessuna iscrizione, nulla che lascia il box. Ottieni l'elenco delle sessioni, la sequenza di chiamate del modello, chiamate di strumenti e decisioni di hook all'interno di ogni esecuzione, cosa è stato bloccato e cosa la policy ha detto all'agente, e un audit offline (`failproofai audit`) che scansiona la tua cronologia per pattern rischiosi e suggerisce policy per fermarli. → [Dashboard locale](https://docs.befailproof.ai/reference/local-dashboard) · [Leggi una traccia](https://docs.befailproof.ai/sessions/read-a-trace) · [Audit locale](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** è il lato ospitato dello stesso modello di dati, per team che eseguono agenti su una flotta: ogni esecuzione da ogni ambiente in un unico posto, un grafo di esecuzione con sub-agenti paralleli sui propri percorsi, latenza p50/p95/p99 per modelli, strumenti e hook, costo per modello e tracciamento della finestra di contesto, tracciamento degli errori, SQL sulle tue tracce con dashboard condivisibili, valutazioni puntate dal tuo servizio, audit pianificati che trasformano i fallimenti ricorrenti in risultati basati su prove, e avvisi instradati a Slack, email o un webhook firmato. L'auto-hosting nel tuo cluster è disponibile nel piano Enterprise. +**Failproof AI Observability** è il lato ospitato dello stesso modello di dati, per i team che eseguono agenti su una flotta: ogni esecuzione da ogni harness in un unico posto, un grafico di esecuzione con sotto-agenti paralleli su loro corsie, latenza p50/p95/p99 per modelli, strumenti e hook, costo per modello e tracciamento della finestra di contesto, tracciamento degli errori, SQL sulle tue tracce con dashboard condivisibili, valutazioni puntate dal tuo servizio, audit programmati che trasformano i fallimenti ricorrenti in risultati supportati da prove, e avvisi indirizzati a Slack, email o webhook firmato. L'auto-hosting nel tuo cluster è disponibile nel piano Enterprise. → [Sessioni](https://docs.befailproof.ai/sessions/overview) · [Audit](https://docs.befailproof.ai/audits/overview) · @@ -213,44 +214,45 @@ Esegui `failproofai` senza argomenti e servirà un dashboard su `localhost:8020` ## Documentazione -| Inizio | | +| Inizia | | |---|---| -| [Quickstart](https://docs.befailproof.ai/start/quickstart) | Installa, connetti un ambiente, vedi la prima esecuzione | +| [Guida rapida](https://docs.befailproof.ai/start/quickstart) | Installa, connetti un harness, vedi la prima esecuzione | | [Concetti](https://docs.befailproof.ai/start/concepts) | Come funziona il sistema di hook | -| [Ambienti di esecuzione supportati](https://docs.befailproof.ai/reference/harnesses) | Tutti e 12, e cosa ciascuno può applicare | +| [Harness supportati](https://docs.befailproof.ai/reference/harnesses) | Tutti i 12, e cosa ciascuno può enforce | | Osserva | | |---|---| | [Sessioni](https://docs.befailproof.ai/sessions/overview) | Segui un'esecuzione: modelli, strumenti, errori, latenza | -| [Leggi una traccia](https://docs.befailproof.ai/sessions/read-a-trace) | Cosa il grafo di esecuzione ti sta dicendo | -| [Audit](https://docs.befailproof.ai/audits/overview) | Trova modelli di fallimento su molte sessioni | +| [Leggi una traccia](https://docs.befailproof.ai/sessions/read-a-trace) | Cosa ti sta dicendo il grafico di esecuzione | +| [Audit](https://docs.befailproof.ai/audits/overview) | Trova pattern di fallimento su molte sessioni | | [Dashboard locale](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, nessun account necessario | | Applica | | |---|---| -| [Politiche integrate](https://docs.befailproof.ai/policies/builtin) | Tutte le 40 politiche con parametri | -| [Politiche personalizzate](https://docs.befailproof.ai/policies/custom) | Scrivi le tue | +| [Policy built-in](https://docs.befailproof.ai/policies/builtin) | Tutte le 39 policy con parametri | +| [Policy personalizzate](https://docs.befailproof.ai/policies/custom) | Scrivi le tue | | [Configurazione](https://docs.befailproof.ai/policies/local-configuration) | Ambiti di configurazione e regole di merge | | Strumenta il tuo agente | | |---|---| -| [SDK Python](https://docs.befailproof.ai/reference/custom-agents) | Segnala esecuzioni da un agente senza ambiente | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Riporta esecuzioni da un agente senza harness | | [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Riferimento `allow` / `deny` / `instruct` | --- ## Licenza -MIT con [Commons Clause](https://commonsclause.com/) — libera per uso interno e personale; la rivendita commerciale di failproofai stesso richiede un accordo separato. Vedi [LICENSE](../../LICENSE) per il testo completo. +MIT con [Commons Clause](https://commonsclause.com/) — gratuito per uso interno e personale; la rivendita commerciale di failproofai stesso richiede un accordo separato. Vedi [LICENSE](../../LICENSE) per il testo completo. --- ## Contribuire -Vedi [CONTRIBUTING.md](../../CONTRIBUTING.md). Nuove politiche, casi limite e traduzioni sono tutti benvenuti. +Vedi [CONTRIBUTING.md](../../CONTRIBUTING.md). Nuove policy, casi limite e traduzioni sono tutti benvenuti. -> **Compila prima di iniziare.** Esegui prima `bun install && bun run build`. Questo repository esegue i propri hook di failproofai su se stesso, e risolvono l'importazione di `failproofai` contro il bundle compilato `dist/` — senza una build avrai errori di hook `Cannot find package 'failproofai'`. Ricompila dopo aver modificato `src/`. Vedi [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Costruisci prima di iniziare.** Esegui `bun install && bun run build` per primo. Questo repo esegue i propri hook di failproofai su se stesso, e risolvono l'import di `failproofai` rispetto al bundle compilato `dist/` — senza una compilazione ti troverai con errori di hook `Cannot find package 'failproofai'`. Ricompila dopo aver modificato `src/`. Vedi +> [Costruisci prima che i dev hook in-repo funzionino](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Realizzato con ❤️ da [befailproof.ai](https://befailproof.ai) a San Francisco e Bengaluru. +Realizzato con ❤️ da [befailproof.ai](https://befailproof.ai) a SF e Bengaluru. diff --git a/docs/i18n/README.ja.md b/docs/i18n/README.ja.md index f079f001..8b9ccf67 100644 --- a/docs/i18n/README.ja.md +++ b/docs/i18n/README.ja.md @@ -18,10 +18,10 @@ [![Docs](https://img.shields.io/badge/docs-befailproof.ai-002CA7?style=flat-square)](https://docs.befailproof.ai/) [![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](../../LICENSE) -**翻訳版:** [简体中文](../../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) +**翻訳:** [简体中文](../../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) -**あらゆるハーネスで動くエージェントに、オブザーバビリティと制御を。** -エージェントがどこで動いていても、Failproofはすべてを把握し、必要なときに「ノー」と言えます。Failproofは12のエージェントハーネスにフックし — Claude Code や Codex などのコーディングCLI、Hermes などのチャットゲートウェイ、OpenClaw などのセルフホスト型アシスタント — すべての実行を記録し、危険なツール呼び出しを実行前にブロックします。40の組み込みポリシー。レイテンシゼロ。ローカル動作。 +**あらゆるハーネスで動くエージェントに、可観測性と制御を。** +エージェントがどこで動いていても、私たちはそれを見ています——そして「No」と言えます。Failproof は 12 種類のエージェントハーネスにフックします。Claude Code や Codex のようなコーディング CLI、Hermes のようなチャットゲートウェイ、OpenClaw のようなセルフホスト型アシスタントに対応し、すべての実行をキャプチャして危険なツール呼び出しを実行前にブロックします。39 のビルトインポリシー。レイテンシーゼロ。ローカルで動作。 @@ -33,9 +33,9 @@ ## 対応ハーネス -2つのクラスに分かれた12のハーネス — 10のコーディングCLIと、2つのチャット・アシスタントゲートウェイ（Hermes、OpenClaw）。どのハーネスを使っても、同じイベント、同じポリシー、同じセッション履歴が利用できます。 +12 種類のハーネスを 2 つのクラスに分類しています——コーディング CLI が 10 種類、チャット・アシスタントゲートウェイ（Hermes、OpenClaw）が 2 種類です。どのハーネスで動かしても、同じイベント、同じポリシー、同じセッション履歴が使えます。 -いずれのハーネスにも属さないエージェントは [Python SDK](https://docs.befailproof.ai/reference/custom-agents) を通じてレポートできます。トレース、セッション、監査機能が利用可能です。その環境でのエンフォースメントにはご自身のランタイムへのフック実装が必要です — [お問い合わせください](mailto:support@befailproof.ai)。対応方法をご案内します。 +いずれのハーネスでも動作しないエージェントは [Python SDK](https://docs.befailproof.ai/reference/custom-agents) を通じてレポートできます。トレーシング、セッション管理、監査が利用可能です。そこでのエンフォースメントには自前のランタイムへのフックが必要です——[お問い合わせ](mailto:support@befailproof.ai)いただければ対応方法をご案内します。 {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,36 +135,37 @@ ```sh npm install -g failproofai -failproofai policies --install # または `failproofai` を実行して初回プロンプトに従うだけでもOK +failproofai policies --install # または `failproofai` を実行して初回起動のプロンプトに従う failproofai ``` -40の組み込みポリシーが即座に有効化されます。ダッシュボードは `localhost:8020` で確認できます。初回プロンプトを無効にするには `FAILPROOFAI_NO_FIRST_RUN=1` を設定してください。 +39 のビルトインポリシーが即座に有効になります。ダッシュボードは `localhost:8020` で確認できます。`FAILPROOFAI_NO_FIRST_RUN=1` を設定すると初回起動プロンプトを無効化できます。 --- -## ブロックできる操作 +## 防げること -| ポリシー | ブロック対象 | +| ポリシー | ブロックする内容 | |---|---| -| `sanitize-api-keys` | エージェントのコンテキストへのAPIキー漏洩 | -| `block-env-files` | `.env` などのシークレットファイルの読み取り | -| `warn-repeated-tool-calls` | 同じ呼び出しをループし続けるエージェント | +| `sanitize-api-keys` | エージェントのコンテキストへの API キー漏洩 | +| `block-env-files` | `.env` やその他のシークレットファイルの読み取り | +| `warn-repeated-tool-calls` | 同じ呼び出しでループするエージェント | | `block-sudo` | 権限昇格 | | `warn-destructive-sql` | `DROP`、`TRUNCATE`、条件なし `DELETE` | -| `block-terraform` / `block-kubectl` | 本番インフラへの未レビュー変更 | +| `block-terraform` / `block-kubectl` | レビューなしの本番インフラへの変更 | | `block-rm-rf` | 再帰的なファイル削除 | | `block-force-push` / `block-push-master` | `git push --force`、`main` への直接プッシュ | -最初の5つはツールを呼び出せるあらゆるエージェントに適用されます。残りの3つは開発者に特に人気のポリシーで、コーディングCLIはもっとも深くカバーしているハーネスクラスです。 +最初の 5 つはツールを呼び出せるすべてのエージェントに適用されます。残りの 3 つは開発者に特に人気で——コーディング CLI は私たちが最も深くカバーしているハーネスクラスです。 -→ [組み込みポリシー一覧（40件）](https://docs.befailproof.ai/policies/builtin) +→ [39 のビルトインポリシー一覧](https://docs.befailproof.ai/policies/builtin) --- -## カスタムポリシー +## 独自ポリシー -`.failproofai/policies/` にファイルを置くだけで自動的に読み込まれます。フラグ不要。コミットすればチーム全員が次のプルで使えます。 +`.failproofai/policies/` にファイルを置くだけで自動的に読み込まれます——フラグ不要です。 +コミットすれば、次回プル時にチーム全員に適用されます。 ```js import { customPolicies, deny, allow } from "failproofai"; @@ -180,29 +181,29 @@ customPolicies.add({ }); ``` -各ポリシーで使用できる3つの判断： +すべてのポリシーで使用できる 3 つの判定: -| 判断 | 効果 | +| 判定 | 効果 | |---|---| | `allow()` | 操作を許可する | -| `deny(message)` | ブロックする — メッセージはエージェントに返される | +| `deny(message)` | ブロックする——メッセージはエージェントに返される | | `instruct(message)` | 通過させるが、エージェントの次のプロンプトにコンテキストを追加する | → [カスタムポリシーガイド](https://docs.befailproof.ai/policies/custom) --- -## オブザーバビリティ +## 可観測性 -エンフォースメントは半分にすぎません。もう半分は、エージェントが実際に何をしたかを把握することです。 +エンフォースメントは機能の半分です。もう半分は、エージェントが実際に何をしたかを把握することです。 -`failproofai` を引数なしで実行すると、`localhost:8020` にダッシュボードが起動し、マシン上の実行履歴を読み込みます — アカウント不要、サインアップ不要、データは外部に出ません。セッション一覧、モデル呼び出しのシーケンス、各実行内のツール呼び出しとフック判断、ブロックされた内容とポリシーがエージェントに伝えた内容、そしてオフライン監査（`failproofai audit`）で履歴からリスクのあるパターンを検出してポリシーの提案を行います。 +引数なしで `failproofai` を実行すると、`localhost:8020` でダッシュボードが起動し、マシン上の実行履歴を読み取ります——アカウント不要、サインアップ不要、データは外部に送信されません。セッション一覧、モデル呼び出しのシーケンス、各実行内のツール呼び出しとフック判定、ブロックされた内容とポリシーがエージェントに伝えた内容、そしてオフライン監査（`failproofai audit`）による履歴スキャンでリスクのあるパターンを検出し、対策ポリシーを提案します。 → [ローカルダッシュボード](https://docs.befailproof.ai/reference/local-dashboard) · [トレースの読み方](https://docs.befailproof.ai/sessions/read-a-trace) · [ローカル監査](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** は同じデータモデルのホスト型サービスで、フリートでエージェントを運用するチーム向けです。全ハーネスのすべての実行を一か所に集約し、並列サブエージェントを独立レーンで表示する実行グラフ、モデル・ツール・フックのp50/p95/p99レイテンシ、モデルごとのコストとコンテキストウィンドウのトラッキング、エラートラッキング、共有可能なダッシュボード付きSQLクエリ、独自サービスによるスコアリング評価、繰り返す失敗をエビデンスに基づく知見に変える定期監査、そしてSlack・メール・署名付きWebhookへのアラートルーティングを提供します。自社クラスターへのセルフホスティングはEnterpriseプランで利用可能です。 +**Failproof AI Observability** は同じデータモデルのホスト版で、フリートでエージェントを運用するチーム向けです。全ハーネスからのすべての実行を一か所に集約し、並列サブエージェントを独立レーンで表示する実行グラフ、モデル・ツール・フックの p50/p95/p99 レイテンシー、モデルごとのコストとコンテキストウィンドウのトラッキング、エラートラッキング、共有可能なダッシュボード付きの自前トレースへの SQL クエリ、自社サービスによるスコアリング付き評価、繰り返す障害をエビデンスベースの知見に変えるスケジュール監査、そして Slack・メール・署名付き Webhook へのアラートルーティングを提供します。Enterprise プランでは自社クラスターへのセルフホスティングも利用可能です。 → [セッション](https://docs.befailproof.ai/sessions/overview) · [監査](https://docs.befailproof.ai/audits/overview) · @@ -216,40 +217,40 @@ customPolicies.add({ |---|---| | [クイックスタート](https://docs.befailproof.ai/start/quickstart) | インストール、ハーネスの接続、最初の実行を確認する | | [コンセプト](https://docs.befailproof.ai/start/concepts) | フックシステムの仕組み | -| [対応ハーネス](https://docs.befailproof.ai/reference/harnesses) | 全12件と各ハーネスで適用できるポリシー | +| [対応ハーネス](https://docs.befailproof.ai/reference/harnesses) | 全 12 種類と各ハーネスで適用できるエンフォースメント | -| 観測する | | +| 観察する | | |---|---| -| [セッション](https://docs.befailproof.ai/sessions/overview) | 実行を追う：モデル、ツール、エラー、レイテンシ | +| [セッション](https://docs.befailproof.ai/sessions/overview) | 実行を追跡する: モデル、ツール、エラー、レイテンシー | | [トレースの読み方](https://docs.befailproof.ai/sessions/read-a-trace) | 実行グラフが示していること | -| [監査](https://docs.befailproof.ai/audits/overview) | 多数のセッションにまたがる失敗パターンを発見する | +| [監査](https://docs.befailproof.ai/audits/overview) | 複数セッションにまたがる障害パターンを見つける | | [ローカルダッシュボード](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`、アカウント不要 | | 制御する | | |---|---| -| [組み込みポリシー](https://docs.befailproof.ai/policies/builtin) | パラメータ付き全40ポリシー | -| [カスタムポリシー](https://docs.befailproof.ai/policies/custom) | 独自ポリシーを作成する | +| [ビルトインポリシー](https://docs.befailproof.ai/policies/builtin) | パラメーター付き全 39 ポリシー | +| [カスタムポリシー](https://docs.befailproof.ai/policies/custom) | 独自のポリシーを作成する | | [設定](https://docs.befailproof.ai/policies/local-configuration) | 設定スコープとマージルール | -| 独自エージェントを計測する | | +| 独自エージェントを計装する | | |---|---| | [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | ハーネスなしのエージェントから実行をレポートする | -| [ポリシーSDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` リファレンス | +| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` リファレンス | --- ## ライセンス -MIT with [Commons Clause](https://commonsclause.com/) — 社内利用・個人利用は無料。failproofai 自体の商業的な再販には別途契約が必要です。全文は [LICENSE](../../LICENSE) をご覧ください。 +MIT with [Commons Clause](https://commonsclause.com/) ——社内利用および個人利用は無料です。failproofai 自体の商用再販には別途契約が必要です。全文は [LICENSE](../../LICENSE) をご覧ください。 --- ## コントリビューション -[CONTRIBUTING.md](../../CONTRIBUTING.md) をご参照ください。新しいポリシー、エッジケースの対応、翻訳の追加はいずれも歓迎します。 +[CONTRIBUTING.md](../../CONTRIBUTING.md) をご参照ください。新しいポリシー、エッジケースの対応、翻訳はいずれも歓迎します。 -> **作業前にビルドしてください。** まず `bun install && bun run build` を実行してください。このリポジトリはfailproofai自身のフックを自分自身に適用しており、フックはコンパイル済みの `dist/` バンドルに対して `failproofai` インポートを解決します。ビルドなしで実行すると `Cannot find package 'failproofai'` というフックエラーが発生します。`src/` を変更した後は再ビルドしてください。詳細は [リポジトリ内の開発用フックを動作させるためのビルド手順](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) をご覧ください。 +> **作業を始める前にビルドしてください。** まず `bun install && bun run build` を実行してください。このリポジトリは failproofai 自身のフックを自分自身に適用しており、`failproofai` のインポートはコンパイル済みの `dist/` バンドルに対して解決されます——ビルドなしで実行すると `Cannot find package 'failproofai'` というフックエラーが発生します。`src/` を変更した後は再ビルドしてください。詳細は [リポジトリ内の開発フックが動作するようにビルドする](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work) をご覧ください。 --- -SFとベンガルールのチームが ❤️ を込めて開発。[befailproof.ai](https://befailproof.ai) +❤️ を込めて [befailproof.ai](https://befailproof.ai) が SF とベンガルールで開発。 diff --git a/docs/i18n/README.ko.md b/docs/i18n/README.ko.md index c154bc49..da95d71e 100644 --- a/docs/i18n/README.ko.md +++ b/docs/i18n/README.ko.md @@ -20,10 +20,11 @@ **번역:** [简体中文](../../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) -**에이전트가 실행되는 모든 하네스에 대한 관찰 가능성과 정책 적용.** -에이전트가 어디서 실행되든 우리는 확인하고 — 필요하다면 차단합니다. Failproof는 12개의 에이전트 +**에이전트가 실행되는 모든 하네스에 대한 가시성과 정책 적용.** +에이전트가 어디서 실행되든 우리는 모두 감지하고 — 차단할 수 있습니다. Failproof는 12개의 에이전트 하네스에 훅을 연결합니다 — Claude Code, Codex 같은 코딩 CLI, Hermes 같은 채팅 게이트웨이, -OpenClaw 같은 자체 호스팅 어시스턴트 — 모든 실행을 캡처하고 위험한 도구 호출을 실행 전에 차단합니다. 기본 제공 정책 40개. 레이턴시 제로. 로컬 실행. +OpenClaw 같은 자체 호스팅 어시스턴트 — 모든 실행을 캡처하고 위험한 도구 호출을 +실행 전에 차단합니다. 39개의 내장 정책. 지연 시간 제로. 로컬에서 실행. @@ -35,9 +36,11 @@ OpenClaw 같은 자체 호스팅 어시스턴트 — 모든 실행을 캡처하 ## 지원 하네스 -두 가지 유형의 하네스 12개 — 코딩 CLI 10개, 채팅 및 어시스턴트 게이트웨이(Hermes, OpenClaw) 2개. 에이전트가 어느 하네스에서 실행되든 동일한 이벤트, 동일한 정책, 동일한 세션 히스토리가 적용됩니다. +두 가지 유형의 12개 하네스 — 10개의 코딩 CLI와 2개의 채팅 및 어시스턴트 +게이트웨이(Hermes, OpenClaw). 에이전트가 어느 하네스에서 실행되든 동일한 이벤트, 동일한 정책, 동일한 세션 기록을 제공합니다. -위에 해당하는 하네스를 사용하지 않는 에이전트는 [Python SDK](https://docs.befailproof.ai/reference/custom-agents)를 통해 리포트할 수 있으며, 트레이싱·세션·감사 기능을 제공합니다. 해당 환경에서의 정책 적용은 런타임에 직접 훅을 추가해야 합니다 — [문의하기](mailto:support@befailproof.ai)로 연락 주시면 방법을 안내해 드립니다. +이 중 어느 하네스에서도 실행되지 않는 에이전트는 [Python SDK](https://docs.befailproof.ai/reference/custom-agents)를 통해 보고할 수 있으며, +트레이싱, 세션 및 감사 기능을 제공합니다. 해당 환경에서의 정책 적용은 자체 런타임에 훅이 필요합니다 — [문의하시면](mailto:support@befailproof.ai) 함께 방법을 찾아드립니다. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -137,37 +140,38 @@ OpenClaw 같은 자체 호스팅 어시스턴트 — 모든 실행을 캡처하 ```sh npm install -g failproofai -failproofai policies --install # 또는 `failproofai`를 실행하고 최초 실행 프롬프트에서 수락 +failproofai policies --install # or just run `failproofai` and accept the first-run prompt failproofai ``` -기본 제공 정책 40개가 즉시 활성화됩니다. 대시보드는 `localhost:8020`에서 확인할 수 있습니다. `FAILPROOFAI_NO_FIRST_RUN=1`로 최초 실행 프롬프트를 비활성화할 수 있습니다. +39개의 내장 정책이 즉시 활성화됩니다. 대시보드는 `localhost:8020`에서 확인하세요. 최초 실행 프롬프트는 `FAILPROOFAI_NO_FIRST_RUN=1`로 비활성화할 수 있습니다. --- -## 차단 항목 +## 차단 대상 | 정책 | 차단 내용 | |---|---| | `sanitize-api-keys` | 에이전트 컨텍스트로 유출되는 API 키 | | `block-env-files` | `.env` 및 기타 시크릿 파일 읽기 | | `warn-repeated-tool-calls` | 동일한 호출을 반복하는 에이전트 루프 | -| `block-sudo` | 권한 상승 | +| `block-sudo` | 권한 상승 시도 | | `warn-destructive-sql` | `DROP`, `TRUNCATE`, 조건 없는 `DELETE` | -| `block-terraform` / `block-kubectl` | 검토 없는 라이브 인프라 변경 | +| `block-terraform` / `block-kubectl` | 검토되지 않은 운영 인프라 변경 | | `block-rm-rf` | 재귀적 파일 삭제 | | `block-force-push` / `block-push-master` | `git push --force`, `main` 브랜치 직접 푸시 | -처음 다섯 가지는 도구를 호출할 수 있는 모든 에이전트에 적용됩니다. 나머지 세 가지는 개발자들이 가장 선호하는 정책으로 — 코딩 CLI는 우리가 가장 깊이 지원하는 하네스 유형입니다. +처음 다섯 가지는 도구를 호출할 수 있는 모든 에이전트에 적용됩니다. 나머지 세 가지는 +개발자들이 가장 선호하는 정책입니다 — 코딩 CLI는 우리가 가장 깊이 지원하는 하네스 유형입니다. -→ [기본 제공 정책 40개 전체 보기](https://docs.befailproof.ai/policies/builtin) +→ [39개 내장 정책 전체 목록](https://docs.befailproof.ai/policies/builtin) --- ## 커스텀 정책 -`.failproofai/policies/` 디렉토리에 파일을 추가하면 자동으로 로드됩니다 — 별도 플래그 불필요. -커밋하면 팀 전체가 다음 풀 시 적용받습니다. +`.failproofai/policies/` 폴더에 파일을 추가하기만 하면 — 별도 플래그 없이 자동으로 로드됩니다. +커밋하면 팀 전체가 다음 pull 때 적용받습니다. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -188,24 +192,27 @@ customPolicies.add({ | 결정 | 효과 | |---|---| | `allow()` | 작업 허용 | -| `deny(message)` | 차단 — 메시지가 에이전트로 반환됨 | +| `deny(message)` | 차단 — 메시지가 에이전트에게 반환됨 | | `instruct(message)` | 통과시키되, 에이전트의 다음 프롬프트에 컨텍스트 추가 | → [커스텀 정책 가이드](https://docs.befailproof.ai/policies/custom) --- -## 관찰 가능성 +## 가시성 -정책 적용은 절반입니다. 나머지 절반은 에이전트가 실제로 무엇을 했는지 파악하는 것입니다. +정책 적용은 절반에 불과합니다. 나머지 절반은 에이전트가 실제로 무엇을 했는지 파악하는 것입니다. -`failproofai`를 인수 없이 실행하면 `localhost:8020`에서 대시보드가 시작되며, 이미 로컬에 저장된 실행 히스토리를 읽습니다 — 계정 불필요, 회원가입 불필요, 데이터가 외부로 나가지 않습니다. 세션 목록, 각 실행 내의 모델 호출 순서·도구 호출·훅 결정, 차단된 항목과 정책이 에이전트에 전달한 내용, 그리고 오프라인 감사(`failproofai audit`) 기능으로 히스토리에서 위험 패턴을 스캔하고 이를 방지할 정책을 제안받을 수 있습니다. +`failproofai`를 인수 없이 실행하면 `localhost:8020`에서 대시보드를 제공합니다. +이미 로컬 머신에 저장된 실행 기록을 읽어오며 — 계정도, 회원가입도, 데이터 외부 전송도 필요 없습니다. +세션 목록, 모델 호출 순서, 각 실행 내의 도구 호출 및 훅 결정 사항, 차단된 내용과 정책이 에이전트에게 전달한 내용, +그리고 기록에서 위험한 패턴을 스캔하고 이를 방지할 정책을 제안하는 오프라인 감사(`failproofai audit`)까지 제공합니다. → [로컬 대시보드](https://docs.befailproof.ai/reference/local-dashboard) · [트레이스 읽기](https://docs.befailproof.ai/sessions/read-a-trace) · [로컬 감사](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability**는 동일한 데이터 모델의 호스팅 버전으로, 여러 머신에서 에이전트를 운영하는 팀을 위한 서비스입니다: 모든 하네스에서 실행된 전체 기록을 한 곳에서 확인, 독립 레인에서 병렬 서브에이전트가 표시되는 실행 그래프, 모델·도구·훅의 p50/p95/p99 레이턴시, 모델별 비용 및 컨텍스트 윈도우 추적, 에러 추적, 공유 가능한 대시보드가 포함된 자체 트레이스 SQL 쿼리, 자체 서비스로 채점하는 평가, 반복 실패를 근거 있는 발견으로 전환하는 정기 감사, Slack·이메일·서명된 웹훅으로 알림 라우팅. 자체 클러스터 셀프호스팅은 Enterprise 플랜에서 제공됩니다. +**Failproof AI Observability**는 동일한 데이터 모델의 호스팅 버전으로, 여러 머신에서 에이전트를 운영하는 팀을 위해 설계되었습니다: 모든 하네스의 모든 실행을 한 곳에서, 독립 레인에서 병렬 실행되는 서브 에이전트를 포함한 실행 그래프, 모델·도구·훅의 p50/p95/p99 지연 시간, 모델별 비용 및 컨텍스트 윈도우 추적, 오류 추적, 공유 가능한 대시보드와 함께 자체 트레이스에 대한 SQL 쿼리, 자체 서비스로 평가 점수 산정, 반복되는 장애를 근거 기반 분석 결과로 전환하는 정기 감사, 그리고 Slack·이메일·서명된 웹훅으로 라우팅되는 알림까지 제공합니다. 자체 클러스터 셀프 호스팅은 Enterprise 플랜에서 이용 가능합니다. → [세션](https://docs.befailproof.ai/sessions/overview) · [감사](https://docs.befailproof.ai/audits/overview) · @@ -217,33 +224,33 @@ customPolicies.add({ | 시작하기 | | |---|---| -| [퀵스타트](https://docs.befailproof.ai/start/quickstart) | 설치, 하네스 연결, 첫 번째 실행 확인 | -| [개념](https://docs.befailproof.ai/start/concepts) | 훅 시스템 작동 원리 | -| [지원 하네스](https://docs.befailproof.ai/reference/harnesses) | 12개 전체 및 각 하네스의 적용 가능한 정책 | +| [빠른 시작](https://docs.befailproof.ai/start/quickstart) | 설치, 하네스 연결, 첫 번째 실행 확인 | +| [개념](https://docs.befailproof.ai/start/concepts) | 훅 시스템 동작 방식 | +| [지원 하네스](https://docs.befailproof.ai/reference/harnesses) | 12개 전체 및 각각의 정책 적용 범위 | -| 관찰 | | +| 관찰하기 | | |---|---| -| [세션](https://docs.befailproof.ai/sessions/overview) | 실행 추적: 모델, 도구, 에러, 레이턴시 | -| [트레이스 읽기](https://docs.befailproof.ai/sessions/read-a-trace) | 실행 그래프가 말해주는 것 | -| [감사](https://docs.befailproof.ai/audits/overview) | 여러 세션에 걸친 실패 패턴 탐색 | +| [세션](https://docs.befailproof.ai/sessions/overview) | 실행 추적: 모델, 도구, 오류, 지연 시간 | +| [트레이스 읽기](https://docs.befailproof.ai/sessions/read-a-trace) | 실행 그래프가 알려주는 정보 | +| [감사](https://docs.befailproof.ai/audits/overview) | 여러 세션에 걸친 장애 패턴 파악 | | [로컬 대시보드](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, 계정 불필요 | | 정책 적용 | | |---|---| -| [기본 제공 정책](https://docs.befailproof.ai/policies/builtin) | 파라미터가 포함된 40개 정책 전체 | +| [내장 정책](https://docs.befailproof.ai/policies/builtin) | 파라미터 포함 39개 정책 전체 | | [커스텀 정책](https://docs.befailproof.ai/policies/custom) | 직접 작성하기 | | [설정](https://docs.befailproof.ai/policies/local-configuration) | 설정 스코프 및 병합 규칙 | -| 에이전트 직접 계측 | | +| 자체 에이전트 계측 | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | 하네스 없는 에이전트에서 실행 리포트 | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | 하네스 없는 에이전트에서 실행 보고 | | [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` 레퍼런스 | --- ## 라이선스 -[Commons Clause](https://commonsclause.com/)가 포함된 MIT 라이선스 — 내부 및 개인 사용은 무료이며, failproofai 자체의 상업적 재판매는 별도 계약이 필요합니다. 전문은 [LICENSE](../../LICENSE)를 참고하세요. +[Commons Clause](https://commonsclause.com/)가 포함된 MIT 라이선스 — 내부 및 개인 사용은 무료이며, failproofai 자체의 상업적 재판매에는 별도 계약이 필요합니다. 전문은 [LICENSE](../../LICENSE)를 참고하세요. --- @@ -251,11 +258,11 @@ customPolicies.add({ [CONTRIBUTING.md](../../CONTRIBUTING.md)를 참고하세요. 새로운 정책, 엣지 케이스, 번역 모두 환영합니다. -> **시작 전에 먼저 빌드하세요.** `bun install && bun run build`를 먼저 실행해야 합니다. 이 저장소는 -> failproofai 자체 훅을 스스로에 적용하며, 훅은 `failproofai` 임포트를 컴파일된 `dist/` 번들에서 -> 해석합니다 — 빌드 없이 실행하면 `Cannot find package 'failproofai'` 훅 오류가 발생합니다. -> `src/` 변경 후에는 다시 빌드하세요. 자세한 내용은 -> [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)를 참고하세요. +> **시작 전에 빌드하세요.** 먼저 `bun install && bun run build`를 실행하세요. 이 저장소는 +> failproofai 자체 훅을 직접 적용하며, `failproofai` 임포트를 컴파일된 `dist/` 번들에서 +> 찾습니다 — 빌드 없이는 `Cannot find package 'failproofai'` 훅 오류가 발생합니다. +> `src/`를 변경한 후에는 다시 빌드하세요. 자세한 내용은 +> [저장소 내 개발 훅이 작동하려면 빌드가 먼저입니다](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)를 참고하세요. --- diff --git a/docs/i18n/README.pt-br.md b/docs/i18n/README.pt-br.md index fd57fd73..6754370c 100644 --- a/docs/i18n/README.pt-br.md +++ b/docs/i18n/README.pt-br.md @@ -20,8 +20,8 @@ **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) -**Observabilidade e controle para cada ambiente em que seus agentes rodam.** -Onde quer que seus agentes estejam, a gente enxerga — e pode dizer não. O Failproof se integra a 12 ambientes de agentes — CLIs de codificação como Claude Code e Codex, gateways de chat como Hermes, assistentes auto-hospedados como OpenClaw — capturando cada execução e bloqueando chamadas de ferramenta perigosas antes que aconteçam. 40 políticas embutidas. Zero latência. Roda localmente. +**Observabilidade e controle para todos os ambientes em que seus agentes rodam.** +Onde quer que seus agentes executem, nós enxergamos — e podemos dizer não. O Failproof se conecta a 12 harnesses de agentes — CLIs de codificação como Claude Code e Codex, gateways de chat como Hermes, assistentes auto-hospedados como OpenClaw — capturando cada execução e bloqueando chamadas de ferramentas perigosas antes que elas aconteçam. 39 políticas integradas. Zero latência. Roda localmente. @@ -31,11 +31,11 @@ Onde quer que seus agentes estejam, a gente enxerga — e pode dizer não. O Fai --- -## Ambientes suportados +## Harnesses suportados -Doze ambientes em duas categorias — dez CLIs de codificação e dois gateways de chat e assistentes (Hermes, OpenClaw). Mesmos eventos, mesmas políticas, mesmo histórico de sessão, independentemente de qual o seu agente utiliza. +Doze harnesses em duas categorias — dez CLIs de codificação e dois gateways de chat e assistentes (Hermes, OpenClaw). Mesmos eventos, mesmas políticas, mesmo histórico de sessão, independentemente de qual seu agente utilize. -Agentes que não rodam em nenhum deles reportam por meio do [Python SDK](https://docs.befailproof.ai/reference/custom-agents), que oferece rastreamento, sessões e auditorias. Para aplicar controles nesses casos, é necessário um hook no seu próprio runtime — [fale conosco](mailto:support@befailproof.ai) e mapeamos juntos. +Agentes que não rodam em nenhum deles reportam através do [Python SDK](https://docs.befailproof.ai/reference/custom-agents), que oferece rastreamento, sessões e auditorias. A aplicação de políticas nesses casos requer um hook no seu próprio runtime — [fale conosco](mailto:support@befailproof.ai) e mapeamos juntos. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,11 +135,11 @@ Agentes que não rodam em nenhum deles reportam por meio do [Python SDK](https:/ ```sh npm install -g failproofai -failproofai policies --install # ou apenas execute `failproofai` e aceite o prompt da primeira execução +failproofai policies --install # ou simplesmente rode `failproofai` e aceite o prompt da primeira execução failproofai ``` -40 políticas embutidas são ativadas imediatamente. Dashboard em `localhost:8020`. Desative o prompt da primeira execução com `FAILPROOFAI_NO_FIRST_RUN=1`. +39 políticas integradas são ativadas imediatamente. Dashboard em `localhost:8020`. Desative o prompt da primeira execução com `FAILPROOFAI_NO_FIRST_RUN=1`. --- @@ -147,25 +147,25 @@ failproofai | Política | O que bloqueia | |---|---| -| `sanitize-api-keys` | Vazamento de chaves de API para o contexto do agente | -| `block-env-files` | Leitura de `.env` e outros arquivos com segredos | -| `warn-repeated-tool-calls` | O agente entrando em loop na mesma chamada | -| `block-sudo` | Escalada de privilégios | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` sem cláusula WHERE | +| `sanitize-api-keys` | Vazamento de chaves de API no contexto do agente | +| `block-env-files` | Leitura de arquivos `.env` e outros arquivos com segredos | +| `warn-repeated-tool-calls` | O agente em loop na mesma chamada | +| `block-sudo` | Escalação de privilégios | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` sem cláusula `WHERE` | | `block-terraform` / `block-kubectl` | Alterações não revisadas em infraestrutura em produção | | `block-rm-rf` | Exclusão recursiva de arquivos | | `block-force-push` / `block-push-master` | `git push --force`, pushes diretos para `main` | -As cinco primeiras se aplicam a qualquer agente que possa chamar uma ferramenta. As três últimas são as favoritas dos desenvolvedores — CLIs de codificação são a categoria de ambiente em que temos a cobertura mais profunda. +As primeiras cinco se aplicam a qualquer agente que possa chamar uma ferramenta. As três últimas são as favoritas dos desenvolvedores — CLIs de codificação são a categoria de harness que cobrimos com mais profundidade. -→ [Todas as 40 políticas embutidas](https://docs.befailproof.ai/policies/builtin) +→ [Todas as 39 políticas integradas](https://docs.befailproof.ai/policies/builtin) --- ## Suas próprias políticas -Coloque um arquivo em `.failproofai/policies/` — ele é carregado automaticamente, sem necessidade de flags. -Faça commit e toda a equipe recebe na próxima atualização. +Coloque um arquivo em `.failproofai/policies/` — ele é carregado automaticamente, sem flags adicionais. +Faça commit e toda a equipe receberá na próxima atualização. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -186,7 +186,7 @@ Três decisões disponíveis para cada política: | Decisão | Efeito | |---|---| | `allow()` | Permite a operação | -| `deny(message)` | Bloqueia — a mensagem é devolvida ao agente | +| `deny(message)` | Bloqueia — a mensagem é enviada de volta ao agente | | `instruct(message)` | Deixa passar, mas adiciona contexto ao próximo prompt do agente | → [Guia de políticas personalizadas](https://docs.befailproof.ai/policies/custom) @@ -195,19 +195,19 @@ Três decisões disponíveis para cada política: ## Observabilidade -Controle é uma metade. A outra é enxergar o que o agente realmente fez. +A aplicação de políticas é uma metade. A outra metade é enxergar o que o agente realmente fez. -Execute `failproofai` sem argumentos e ele serve um dashboard em `localhost:8020` lendo o histórico de execuções já disponível na sua máquina — sem conta, sem cadastro, nada sai do seu ambiente. Você tem a lista de sessões, a sequência de chamadas ao modelo, chamadas de ferramenta e decisões de hook dentro de cada execução, o que foi bloqueado e o que a política disse ao agente, além de uma auditoria offline (`failproofai audit`) que varre seu histórico em busca de padrões arriscados e sugere políticas para contê-los. +Execute `failproofai` sem argumentos e ele servirá um dashboard em `localhost:8020` lendo o histórico de execuções já presente na sua máquina — sem conta, sem cadastro, sem nada sair do ambiente. Você tem a lista de sessões, a sequência de chamadas de modelo, chamadas de ferramentas e decisões de hook em cada execução, o que foi bloqueado e o que a política comunicou ao agente, além de uma auditoria offline (`failproofai audit`) que analisa seu histórico em busca de padrões de risco e sugere políticas para contê-los. → [Dashboard local](https://docs.befailproof.ai/reference/local-dashboard) · [Lendo um trace](https://docs.befailproof.ai/sessions/read-a-trace) · [Auditoria local](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** é o lado hospedado do mesmo modelo de dados, para equipes que rodam agentes em múltiplas máquinas: todas as execuções de todos os ambientes em um só lugar, um grafo de execução com sub-agentes paralelos em suas próprias raias, latência p50/p95/p99 para modelos, ferramentas e hooks, rastreamento de custo e janela de contexto por modelo, rastreamento de erros, SQL sobre seus próprios traces com dashboards compartilháveis, avaliações pontuadas pelo seu próprio serviço, auditorias agendadas que transformam falhas recorrentes em descobertas com evidências, e alertas roteados para Slack, e-mail ou um webhook assinado. Auto-hospedagem no seu próprio cluster está disponível no plano Enterprise. +**Failproof AI Observability** é a versão hospedada do mesmo modelo de dados, para equipes que rodam agentes em uma frota: todas as execuções de todos os harnesses em um só lugar, um grafo de execução com sub-agentes paralelos em suas próprias faixas, latência p50/p95/p99 para modelos, ferramentas e hooks, rastreamento de custo e janela de contexto por modelo, rastreamento de erros, SQL sobre seus próprios traces com dashboards compartilháveis, avaliações pontuadas pelo seu próprio serviço, auditorias agendadas que transformam falhas recorrentes em achados embasados em evidências, e alertas roteados para Slack, e-mail ou um webhook assinado. Auto-hospedagem no seu próprio cluster está disponível no plano Enterprise. → [Sessões](https://docs.befailproof.ai/sessions/overview) · [Auditorias](https://docs.befailproof.ai/audits/overview) · -[Agende uma demo](https://befailproof.ai/get-a-demo) +[Agendar uma demo](https://befailproof.ai/get-a-demo) --- @@ -215,33 +215,33 @@ Execute `failproofai` sem argumentos e ele serve um dashboard em `localhost:8020 | Início | | |---|---| -| [Quickstart](https://docs.befailproof.ai/start/quickstart) | Instale, conecte um ambiente e veja a primeira execução | +| [Quickstart](https://docs.befailproof.ai/start/quickstart) | Instale, conecte um harness, veja a primeira execução | | [Conceitos](https://docs.befailproof.ai/start/concepts) | Como o sistema de hooks funciona | -| [Ambientes suportados](https://docs.befailproof.ai/reference/harnesses) | Todos os 12 e o que cada um pode controlar | +| [Harnesses suportados](https://docs.befailproof.ai/reference/harnesses) | Todos os 12 e o que cada um pode aplicar | | Observar | | |---|---| | [Sessões](https://docs.befailproof.ai/sessions/overview) | Acompanhe uma execução: modelos, ferramentas, erros, latência | -| [Lendo um trace](https://docs.befailproof.ai/sessions/read-a-trace) | O que o grafo de execução está te dizendo | -| [Auditorias](https://docs.befailproof.ai/audits/overview) | Encontre padrões de falha em múltiplas sessões | +| [Lendo um trace](https://docs.befailproof.ai/sessions/read-a-trace) | O que o grafo de execução está mostrando | +| [Auditorias](https://docs.befailproof.ai/audits/overview) | Encontre padrões de falha em várias sessões | | [Dashboard local](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, sem conta necessária | -| Controlar | | +| Aplicar políticas | | |---|---| -| [Políticas embutidas](https://docs.befailproof.ai/policies/builtin) | Todas as 40 políticas com parâmetros | +| [Políticas integradas](https://docs.befailproof.ai/policies/builtin) | Todas as 39 políticas com parâmetros | | [Políticas personalizadas](https://docs.befailproof.ai/policies/custom) | Escreva as suas próprias | | [Configuração](https://docs.befailproof.ai/policies/local-configuration) | Escopos de configuração e regras de mesclagem | -| Instrumente seu próprio agente | | +| Instrumentar seu próprio agente | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Reporte execuções de um agente sem ambiente | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Reporte execuções de um agente sem harness | | [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Referência de `allow` / `deny` / `instruct` | --- ## Licença -MIT com [Commons Clause](https://commonsclause.com/) — gratuito para uso interno e pessoal; a revenda comercial do failproofai em si requer um acordo separado. Veja [LICENSE](../../LICENSE) para o texto completo. +MIT com [Commons Clause](https://commonsclause.com/) — gratuito para uso interno e pessoal; a revenda comercial do próprio failproofai requer um acordo separado. Veja [LICENSE](../../LICENSE) para o texto completo. --- @@ -249,7 +249,7 @@ MIT com [Commons Clause](https://commonsclause.com/) — gratuito para uso inter Veja [CONTRIBUTING.md](../../CONTRIBUTING.md). Novas políticas, casos extremos e traduções são bem-vindos. -> **Faça o build antes de começar.** Execute `bun install && bun run build` primeiro. Este repositório roda os próprios hooks do failproofai sobre si mesmo, e eles resolvem o import `failproofai` contra o bundle compilado em `dist/` — sem um build, você vai encontrar erros de hook com `Cannot find package 'failproofai'`. Refaça o build após alterar `src/`. Veja +> **Faça o build antes de começar.** Execute `bun install && bun run build` primeiro. Este repositório roda os próprios hooks do failproofai sobre si mesmo, e eles resolvem o import `failproofai` contra o bundle compilado em `dist/` — sem um build você encontrará erros de hook `Cannot find package 'failproofai'`. Reconstrua após alterar `src/`. Veja > [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- diff --git a/docs/i18n/README.ru.md b/docs/i18n/README.ru.md index e3e98882..bd7213f8 100644 --- a/docs/i18n/README.ru.md +++ b/docs/i18n/README.ru.md @@ -20,8 +20,8 @@ **Переводы:** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**Видимость и контроль для каждого окружения, в котором работают ваши агенты.** -Где бы ни работали ваши агенты, мы это видим — и можем сказать нет. failproofai подключается к 12 окружениям агентов — coding CLI, таким как Claude Code и Codex, шлюзам чата, таким как Hermes, самостоятельным помощникам, таким как OpenClaw — перехватывая каждый запуск и блокируя опасные вызовы инструментов перед их выполнением. 40 встроенных политик. Нулевая задержка. Работает локально. +**Наблюдаемость и контроль для каждой платформы, на которой работают ваши агенты.** +Где бы ни работали ваши агенты, мы видим это — и мы можем остановить опасные действия. Failproof интегрируется с 12 платформами для запуска агентов — от кодовых CLI, таких как Claude Code и Codex, до шлюзов чатов, таких как Hermes, и самостоятельных ассистентов, таких как OpenClaw — перехватывая каждый запуск и блокируя опасные вызовы инструментов до их выполнения. 39 встроенных политик. Нулевая задержка. Работает локально. @@ -31,11 +31,12 @@ --- -## Поддерживаемые окружения +## Поддерживаемые платформы -Двенадцать окружений в двух категориях — десять coding CLI и два шлюза для чата и ассистентов (Hermes, OpenClaw). Одни и те же события, одни и те же политики, одна и та же история сессий, независимо от того, в каком из них работает ваш агент. +Двенадцать платформ в двух классах — десять кодовых CLI и два шлюза для чатов и ассистентов (Hermes, OpenClaw). Одни и те же события, одни и те же политики, одна и та же история сеансов, независимо от платформы, на которой работает ваш агент. -Агенты, работающие ни в одном из них, отправляют отчеты через [Python SDK](https://docs.befailproof.ai/reference/custom-agents), который дает вам трассировку, сессии и аудит. Контроль там требует подключения в вашем собственном рантайме — [свяжитесь с нами](mailto:support@befailproof.ai) и мы его настроим. +Агенты, работающие ни на одной из них, отправляют отчёты через [Python SDK](https://docs.befailproof.ai/reference/custom-agents), +который предоставляет вам трассировку, сеансы и аудиты. Контроль там требует подключения в вашей собственной среде выполнения — [свяжитесь с нами](mailto:support@befailproof.ai) и мы поможем. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,36 +136,36 @@ ```sh npm install -g failproofai -failproofai policies --install # или просто запустите `failproofai` и примите запрос при первом запуске +failproofai policies --install # или просто запустите `failproofai` и примите подсказку при первом запуске failproofai ``` -40 встроенных политик активируются сразу же. Панель управления на `localhost:8020`. Отключите запрос при первом запуске с помощью `FAILPROOFAI_NO_FIRST_RUN=1`. +39 встроенных политик активируются немедленно. Панель управления доступна на `localhost:8020`. Отключите подсказку при первом запуске с помощью `FAILPROOFAI_NO_FIRST_RUN=1`. --- -## Что это блокирует +## Что блокируется -| Политика | Что она блокирует | +| Политика | Что блокируется | |---|---| -| `sanitize-api-keys` | Утечку API-ключей в контекст агента | -| `block-env-files` | Чтение файлов `.env` и других секретных файлов | -| `warn-repeated-tool-calls` | Зацикливание агента на одном и том же вызове | +| `sanitize-api-keys` | Утечка ключей API в контекст агента | +| `block-env-files` | Чтение файлов `.env` и других файлов с секретами | +| `warn-repeated-tool-calls` | Агент зацикливается на одном и том же вызове | | `block-sudo` | Повышение привилегий | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, неограниченный `DELETE` | -| `block-terraform` / `block-kubectl` | Непроверенные изменения работающей инфраструктуры | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, неограниченные `DELETE` | +| `block-terraform` / `block-kubectl` | Непроверенные изменения активной инфраструктуры | | `block-rm-rf` | Рекурсивное удаление файлов | -| `block-force-push` / `block-push-master` | `git push --force`, прямые push в `main` | +| `block-force-push` / `block-push-master` | `git push --force`, прямые толчки в `main` | -Первые пять применяются к любому агенту, который может вызывать инструмент. Последние три — фавориты разработчиков — coding CLI — это класс окружения, который мы поддерживаем наиболее глубоко. +Первые пять применяются к любому агенту, который может вызвать инструмент. Последние три — фавориты разработчиков — кодовые CLI — это класс платформ, который мы охватываем наиболее глубоко. -→ [Все 40 встроенных политик](https://docs.befailproof.ai/policies/builtin) +→ [Все 39 встроенных политик](https://docs.befailproof.ai/policies/builtin) --- ## Ваши собственные политики -Просто разместите файл в `.failproofai/policies/` — он загружается автоматически, флаги не требуются. +Добавьте файл в `.failproofai/policies/` — он загружается автоматически без дополнительных флагов. Закоммитьте его и вся команда получит его при следующем pull. ```js @@ -186,26 +187,28 @@ customPolicies.add({ | Решение | Эффект | |---|---| | `allow()` | Разрешить операцию | -| `deny(message)` | Заблокировать её — сообщение вернется агенту | +| `deny(message)` | Заблокировать — сообщение вернётся агенту | | `instruct(message)` | Пропустить, но добавить контекст в следующий запрос агента | → [Руководство по пользовательским политикам](https://docs.befailproof.ai/policies/custom) --- -## Видимость +## Наблюдаемость -Контроль — это одна половина. Другая половина — это видение того, что на самом деле сделал агент. +Контроль — это одна половина. Другая половина — видеть, что на самом деле сделал агент. -Запустите `failproofai` без аргументов и она откроет панель управления на `localhost:8020`, читая историю запусков, уже находящуюся на вашей машине — никакого аккаунта, никакой регистрации, ничего не выходит за границы. Вы получаете список сессий, последовательность вызовов модели, вызовов инструментов и решений подключения в каждом запуске, что было заблокировано и что политика сказала агенту, а также автономный аудит (`failproofai audit`), который сканирует вашу историю на предмет рискованных паттернов и предлагает политики для их остановки. +Запустите `failproofai` без аргументов и он будет служить панель управления на `localhost:8020`, +читая историю запусков уже находящуюся на вашей машине — никаких учётных записей, никаких регистраций, ничего не покидает периметр. Вы получаете список сеансов, последовательность вызовов моделей, вызовов инструментов и решений подключений в каждом запуске, что было заблокировано и что политика сообщила агенту, а также автономный аудит (`failproofai audit`), который сканирует вашу историю на предмет рискованных паттернов и предлагает политики для их остановки. → [Локальная панель управления](https://docs.befailproof.ai/reference/local-dashboard) · [Чтение трассировки](https://docs.befailproof.ai/sessions/read-a-trace) · [Локальный аудит](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** — это хостированная часть той же модели данных для команд, работающих с агентами на флоте: каждый запуск от каждого окружения в одном месте, граф выполнения с параллельными под-агентами на своих полосах, латентность p50/p95/p99 для моделей, инструментов и подключений, стоимость на модель и отслеживание окна контекста, отслеживание ошибок, SQL над вашими собственными трассировками с общими панелями управления, оценки, оцениваемые вашим сервисом, запланированные аудиты, которые превращают повторяющиеся сбои в подтвержденные выводы, и оповещения, направляемые в Slack, электронную почту или подписанный вебхук. Самостоятельный хостинг в вашем собственном кластере доступен в плане Enterprise. +**Failproof AI Observability** — это размещённая сторона той же модели данных, для команд, +запускающих агентов по всему флоту: каждый запуск от каждой платформы в одном месте, граф выполнения с параллельными под-агентами на их собственных линиях, p50/p95/p99 задержка для моделей, инструментов и подключений, стоимость и отслеживание окна контекста для каждой модели, отслеживание ошибок, SQL по вашим собственным трассам с общими панелями управления, оценки, оценённые вашей собственной службой, запланированные аудиты, которые превращают повторяющиеся сбои в подтверждённые выводы, и оповещения, направленные в Slack, электронную почту или подписанный webhook. Собственное хостирование в вашем собственном кластере доступно в плане Enterprise. -→ [Сессии](https://docs.befailproof.ai/sessions/overview) · +→ [Сеансы](https://docs.befailproof.ai/sessions/overview) · [Аудиты](https://docs.befailproof.ai/audits/overview) · [Запросить демонстрацию](https://befailproof.ai/get-a-demo) @@ -215,42 +218,42 @@ customPolicies.add({ | Начало | | |---|---| -| [Быстрый старт](https://docs.befailproof.ai/start/quickstart) | Установка, подключение окружения, просмотр первого запуска | -| [Концепции](https://docs.befailproof.ai/start/concepts) | Как работает система подключения | -| [Поддерживаемые окружения](https://docs.befailproof.ai/reference/harnesses) | Все 12, и что каждое может контролировать | +| [Быстрый старт](https://docs.befailproof.ai/start/quickstart) | Установка, подключение платформы, первый запуск | +| [Концепции](https://docs.befailproof.ai/start/concepts) | Как работает система подключений | +| [Поддерживаемые платформы](https://docs.befailproof.ai/reference/harnesses) | Все 12 и что может контролировать каждая | | Наблюдение | | |---|---| -| [Сессии](https://docs.befailproof.ai/sessions/overview) | Следите за запуском: модели, инструменты, ошибки, задержка | +| [Сеансы](https://docs.befailproof.ai/sessions/overview) | Отследите запуск: модели, инструменты, ошибки, задержка | | [Чтение трассировки](https://docs.befailproof.ai/sessions/read-a-trace) | Что вам говорит граф выполнения | -| [Аудиты](https://docs.befailproof.ai/audits/overview) | Найдите паттерны сбоев в разных сессиях | -| [Локальная панель управления](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, аккаунт не требуется | +| [Аудиты](https://docs.befailproof.ai/audits/overview) | Найдите паттерны сбоев в нескольких сеансах | +| [Локальная панель управления](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, никакой учётной записи не требуется | | Контроль | | |---|---| -| [Встроенные политики](https://docs.befailproof.ai/policies/builtin) | Все 40 политик с параметрами | -| [Пользовательские политики](https://docs.befailproof.ai/policies/custom) | Напишите свои собственные | +| [Встроенные политики](https://docs.befailproof.ai/policies/builtin) | Все 39 политик с параметрами | +| [Пользовательские политики](https://docs.befailproof.ai/policies/custom) | Напишите свои | | [Конфигурация](https://docs.befailproof.ai/policies/local-configuration) | Области конфигурации и правила слияния | -| Подключите свой собственный агент | | +| Инструмент вашего собственного агента | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Отправляйте запуски от агента без окружения | -| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Справочник `allow` / `deny` / `instruct` | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Отправляйте отчёты от агента без платформы | +| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Справка `allow` / `deny` / `instruct` | --- ## Лицензия -MIT с [Commons Clause](https://commonsclause.com/) — бесплатно для внутреннего и личного использования; коммерческая перепродажа самого failproofai требует отдельного соглашения. Полный текст см. в [LICENSE](../../LICENSE). +MIT с [Commons Clause](https://commonsclause.com/) — свободна для внутреннего и личного использования; коммерческая перепродажа самого failproofai требует отдельного соглашения. См. [LICENSE](../../LICENSE) для полного текста. --- ## Вклад -См. [CONTRIBUTING.md](../../CONTRIBUTING.md). Новые политики, граничные случаи и переводы всегда приветствуются. +Смотрите [CONTRIBUTING.md](../../CONTRIBUTING.md). Новые политики, граничные случаи и переводы приветствуются. -> **Постройте перед началом работы.** Сначала запустите `bun install && bun run build`. Этот репозиторий запускает собственные подключения failproofai для себя, и они разрешают импорт `failproofai` к скомпилированному пакету `dist/` — без сборки вы получите ошибки подключения `Cannot find package 'failproofai'`. Перестройте после изменения `src/`. См. раздел -> [Постройте перед тем, как будут работать in-repo dev подключения](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Постройте перед началом.** Запустите `bun install && bun run build` в первый раз. Этот репозиторий запускает собственные подключения failproofai на себе, и они разрешают импорт `failproofai` для скомпилированного пакета `dist/` — без сборки вы получите ошибки подключения `Cannot find package 'failproofai'`. Перестройте после изменения `src/`. Смотрите +> [Постройте перед тем, как в-репо девелопер подключения будут работать](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- diff --git a/docs/i18n/README.tr.md b/docs/i18n/README.tr.md index 7e7cd39f..7558d1b3 100644 --- a/docs/i18n/README.tr.md +++ b/docs/i18n/README.tr.md @@ -20,8 +20,8 @@ **Ç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) -**Ajanların çalıştığı her ortamda gözlemlenebilirlik ve uygulama.** -Ajanların nerede çalıştığını görebiliriz — ve hayır diyebiliriz. Failproof, Claude Code ve Codex gibi kodlama CLI'ları, Hermes gibi sohbet ağ geçitleri, OpenClaw gibi kendi kendine barındırılan asistanlar olmak üzere 12 ajan ortamını kancalamakta, her çalışmayı yakalamakta ve tehlikeli araç çağrılarını yürütülmeden önce engellemektedir. 40 yerleşik politika. Sıfır gecikme. Yerel olarak çalışır. +**Aracılarınızın çalıştığı her ortam için gözlemlenebilirlik ve zorlama.** +Aracılarınız nereye koşarsa koşsun, biz bunu görüyoruz — ve hayır diyebiliriz. Failproof, 12 aracı ortamına bağlanıyor — Claude Code ve Codex gibi kodlama CLIleri, Hermes gibi sohbet ağ geçitleri, OpenClaw gibi kendi kendine barındırılan asistanlar — her çalıştırmayı yakalayarak ve tehlikeli araç çağrılarını yürütülmeden önce engellemeyi sağlıyor. 39 yerleşik politika. Sıfır gecikme. Yerel olarak çalışıyor. @@ -33,9 +33,9 @@ Ajanların nerede çalıştığını görebiliriz — ve hayır diyebiliriz. Fai ## Desteklenen ortamlar -İki sınıfta on iki ortam — on kodlama CLI'sı ve iki sohbet ve asistan ağ geçidi (Hermes, OpenClaw). Aynı olaylar, aynı politikalar, aynı oturum geçmişi, ajan hangi ortamda çalışırsa çalışsın. +İki sınıfta on iki ortam — on kodlama CLIsi ve iki sohbet ile asistan ağ geçidi (Hermes, OpenClaw). Aynı olaylar, aynı politikalar, aynı oturum geçmişi, aracınız nerede çalışırsa çalışsın. -Bunların hiçbirinde çalışmayan Ajanlar [Python SDK](https://docs.befailproof.ai/reference/custom-agents) aracılığıyla rapor verir; bu size izleme, oturumlar ve denetim yeteneği sağlar. Orada uygulama, kendi çalışma ortamınızda bir kanca gerektirir — [bize yazın](mailto:support@befailproof.ai) ve biz bunu eşleştireceğiz. +Bunlardan hiçbirinde çalışmayan aracılar, [Python SDK](https://docs.befailproof.ai/reference/custom-agents) aracılığıyla rapor verir. Burada izleme, oturumlar ve denetimler alabilirsiniz. Zorlama burada kendi çalışma zamanınızda bir kanca gerektirir — [bizimle iletişime geçin](mailto:support@befailproof.ai) ve onu harita çizeriz. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -131,41 +131,41 @@ Bunların hiçbirinde çalışmayan Ajanlar [Python SDK](https://docs.befailproo -## Kurulum +## Yükleme ```sh npm install -g failproofai -failproofai policies --install # veya sadece `failproofai` çalıştırın ve ilk çalıştırma istemini kabul edin +failproofai policies --install # veya sadece `failproofai` çalıştırın ve ilk çalışma istemine katılın failproofai ``` -40 yerleşik politika hemen etkinleştirilir. Pano şu adreste bulunur: `localhost:8020`. İlk çalıştırma istemini `FAILPROOFAI_NO_FIRST_RUN=1` ile devre dışı bırakın. +39 yerleşik politika hemen etkinleştirilir. Kontrol paneli `localhost:8020` adresinde mevcuttur. İlk çalışma istemini `FAILPROOFAI_NO_FIRST_RUN=1` ile devre dışı bırakın. --- -## Neleri engeller +## Engellediği neler -| Politika | Neyi engeller | +| Politika | Engellediği | |---|---| -| `sanitize-api-keys` | API anahtarlarının ajanın bağlamına sızması | +| `sanitize-api-keys` | API anahtarlarının aracının bağlamına sızması | | `block-env-files` | `.env` ve diğer gizli dosyaların okunması | -| `warn-repeated-tool-calls` | Ajanın aynı çağrıda döngüye girmesi | +| `warn-repeated-tool-calls` | Aracının aynı çağrıda döngüye girmesi | | `block-sudo` | Ayrıcalık yükseltme | -| `warn-destructive-sql` | `DROP`, `TRUNCATE`, sınırsız `DELETE` | -| `block-terraform` / `block-kubectl` | Canlı altyapıya incelenmemiş değişiklikler | -| `block-rm-rf` | Yinelemeli dosya silme | -| `block-force-push` / `block-push-master` | `git push --force`, `main` öğesine doğrudan push işlemleri | +| `warn-destructive-sql` | `DROP`, `TRUNCATE`, sınırlandırılmamış `DELETE` | +| `block-terraform` / `block-kubectl` | İncelenmemiş canlı altyapı değişiklikleri | +| `block-rm-rf` | Özyinelemeli dosya silme | +| `block-force-push` / `block-push-master` | `git push --force`, `main` adresine doğrudan itme | -İlk beş tanesinin herhangi bir araç çağırabilen ajan için geçerlidir. Son üçü geliştirici favori notları — kodlama CLI'ları, en derinlemesine kapsadığımız ortam sınıfıdır. +İlk beşi bir araç çağırabilen herhangi bir aracıya uygulanır. Son üçü geliştirici favorileridir — kodlama CLIleri, en derin kapsadığımız ortam sınıfıdır. -→ [40 yerleşik politikanın tümü](https://docs.befailproof.ai/policies/builtin) +→ [Tüm 39 yerleşik politika](https://docs.befailproof.ai/policies/builtin) --- ## Kendi politikalarınız -`.failproofai/policies/` klasörüne bir dosya bırakın — bayrak gerekli olmaksızın otomatik olarak yüklenir. -İşleyin ve tüm takım bunu sonraki pull'da alır. +`.failproofai/policies/` klasörüne bir dosya bırakın — otomatik olarak yüklenir, hiçbir bayrak gerekmez. +Bunu commitleyin ve tüm takım sonraki pull'da alır. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -175,19 +175,19 @@ customPolicies.add({ match: { events: ["PreToolUse"] }, fn: async (ctx) => { if (ctx.toolInput?.file_path?.includes("production")) - return deny("Production yollarına yazma işlemleri engellenir."); + return deny("Writings to production paths are blocked."); return allow(); }, }); ``` -Her politika için kullanılabilir üç karar: +Her politikaya açık üç karar: | Karar | Etki | |---|---| | `allow()` | İşleme izin ver | -| `deny(message)` | Engelle — ileti ajana geri gider | -| `instruct(message)` | Bunu geçir, ancak ajanın sonraki istemine bağlam ekle | +| `deny(message)` | Engelle — mesaj aracıya geri gider | +| `instruct(message)` | İzin ver, ancak aracının sonraki istemine bağlam ekle | → [Özel politikalar rehberi](https://docs.befailproof.ai/policies/custom) @@ -195,15 +195,15 @@ Her politika için kullanılabilir üç karar: ## Gözlemlenebilirlik -Uygulama bir yarısı. Diğer yarısı ise ajanın gerçekte ne yaptığını görmektir. +Zorlama yarısı. Diğer yarısı aracının gerçekten ne yaptığını görmektir. -`failproofai` parametresiz çalıştırın ve makinenizde zaten bulunan çalışma geçmişini okuyan `localhost:8020` adresinde bir pano sunar — hesap yok, kayıt yok, hiçbir şey kutudan dışarı çıkmaz. Oturum listesini, model çağrılarının sırasını, her çalışma içindeki araç çağrılarını ve kanca kararlarını, neyin engellendiğini ve politikanın ajana söylediklerini, ve risky desenleri için çalışma geçmişinizi taraması yapan ve onları durdurmak için politikalar önerenin çevrimdışı denetimini (`failproofai audit`) alırsınız. +`failproofai`'yi hiçbir argüman olmadan çalıştırın ve `localhost:8020` adresinde zaten makinenizde bulunan çalışma geçmişini okuyan bir kontrol paneli sunar — hesap yok, kaydolma yok, kutunun dışına çıkan hiçbir şey yok. Oturum listesini, her çalıştırma içindeki model çağrılarının, araç çağrılarının ve kanca kararlarının sırasını, bloke edilen şeyi ve politikanın aracıya söylediğini alırsınız ve geçmişinizi taraması ve önlemek için politikalar önermesi gereken çevrimdışı bir denetim (`failproofai audit`) alırsınız. -→ [Yerel pano](https://docs.befailproof.ai/reference/local-dashboard) · -[İz oku](https://docs.befailproof.ai/sessions/read-a-trace) · +→ [Yerel kontrol paneli](https://docs.befailproof.ai/reference/local-dashboard) · +[İzleme okuyun](https://docs.befailproof.ai/sessions/read-a-trace) · [Yerel denetim](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Gözlemlenebilirliği**, bir filo arasında ajanlar çalıştıran takımlar için aynı veri modelinin barındırılan tarafıdır: her ortamdan her çalışma tek bir yerde, kendi şeritlerinde paralel alt-ajanlar içeren bir yürütme grafiği, modeller, araçlar ve kancalar için p50/p95/p99 gecikmesi, model başına maliyet ve bağlam penceresi izlemesi, hata izlemesi, kendi izlemeleri üzerinden SQL paylaşılabilir panolarla, kendi hizmetiniz tarafından puanlandırılan değerlendirmeler, yinelenen hataları kanıta dayalı bulgulara dönüştüren planlanan denetimler ve Slack, e-posta veya imzalı webhooks'a yönlendirilen uyarılar. Kendi kümenizde kendi kendine barındırma, Enterprise planında kullanılabilir. +**Failproof AI Gözlemlenebilirlik**, aynı veri modelinin barındırılan tarafıdır, bir filo genelinde aracılar çalıştıran ekipler için: her ortamdan her çalıştırma tek bir yerde, kendi şeritlerinde paralel alt aracıları olan bir yürütme grafiği, modeller, araçlar ve kancalar için p50/p95/p99 gecikme süresi, model başına maliyet ve bağlam penceresi izlemesi, hata izlemesi, kendi izlemeleriniz üzerinde SQL ve paylaşılabilir kontrol panelleri, kendi hizmetiniz tarafından puanlanan değerlendirmeler, tekrarlayan hataları kanıta dayalı bulgulara dönüştüren planlanan denetimler ve Slack, e-posta veya imzalı bir webhook'a yönlendirilen uyarılar. Kendi kümenizde kendi kendine barındırma, Kurumsal planda mevcuttur. → [Oturumlar](https://docs.befailproof.ai/sessions/overview) · [Denetimler](https://docs.befailproof.ai/audits/overview) · @@ -211,46 +211,47 @@ Uygulama bir yarısı. Diğer yarısı ise ajanın gerçekte ne yaptığını g --- -## Belgeleme +## Dokümantasyon -| Başlangıç | | +| Başlayın | | |---|---| -| [Hızlı başlangıç](https://docs.befailproof.ai/start/quickstart) | Kurulum yapın, bir ortamı bağlayın, ilk çalışmayı görün | +| [Hızlı başlangıç](https://docs.befailproof.ai/start/quickstart) | Yükleme, bir ortam bağlama, ilk çalıştırmayı görme | | [Kavramlar](https://docs.befailproof.ai/start/concepts) | Kanca sistemi nasıl çalışır | -| [Desteklenen ortamlar](https://docs.befailproof.ai/reference/harnesses) | Tümü 12 ve her birinin uygulayabileceği | +| [Desteklenen ortamlar](https://docs.befailproof.ai/reference/harnesses) | Tüm 12'si ve her birinin zorlayabileceği şey | -| Gözlemleyin | | +| Gözlemle | | |---|---| -| [Oturumlar](https://docs.befailproof.ai/sessions/overview) | Bir çalışmayı izleyin: modeller, araçlar, hatalar, gecikme | -| [İz oku](https://docs.befailproof.ai/sessions/read-a-trace) | Yürütme grafiği size ne anlatıyor | -| [Denetimler](https://docs.befailproof.ai/audits/overview) | Birçok oturumdaki başarısızlık desenleri bulun | -| [Yerel pano](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, hesap gerekli değil | +| [Oturumlar](https://docs.befailproof.ai/sessions/overview) | Bir çalıştırmayı takip et: modeller, araçlar, hatalar, gecikme | +| [İzleme okuyun](https://docs.befailproof.ai/sessions/read-a-trace) | Yürütme grafiği size ne söylüyor | +| [Denetimler](https://docs.befailproof.ai/audits/overview) | Birçok oturumda hata desenlerini bulun | +| [Yerel kontrol paneli](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, hesap gerekli değil | -| Uygulayın | | +| Zorla | | |---|---| -| [Yerleşik politikalar](https://docs.befailproof.ai/policies/builtin) | Tüm 40 politika parametrelerle | -| [Özel politikalar](https://docs.befailproof.ai/policies/custom) | Kendinizinkini yazın | +| [Yerleşik politikalar](https://docs.befailproof.ai/policies/builtin) | Tüm 39 politika parametrelerle | +| [Özel politikalar](https://docs.befailproof.ai/policies/custom) | Kendi yazınızı yazın | | [Yapılandırma](https://docs.befailproof.ai/policies/local-configuration) | Yapılandırma kapsamları ve birleştirme kuralları | -| Kendi ajanınızı enstrüman edin | | +| Kendi aracınızı enstrüman edin | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Ortamı olmayan bir ajanın çalışmalarını raporlayın | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Ortamı olmayan bir aracıdan çalıştırmaları rapor edin | | [Politika SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` başvurusu | --- ## Lisans -MIT ile [Commons Clause](https://commonsclause.com/) — dahili ve kişisel kullanım için ücretsiz; failproofai'nin kendisinin ticari yeniden satışı ayrı bir anlaşma gerektirir. Tam metin için [LICENSE](../../LICENSE) dosyasına bakın. +[Commons Clause](https://commonsclause.com/) ile MIT — dahili ve kişisel kullanım için ücretsiz; failproofai'nın kendisinin ticari olarak yeniden satılması ayrı bir anlaşma gerektirir. Tam metin için [LICENSE](../../LICENSE) adresine bakın. --- -## Katkı +## Katkıda bulunma -[CONTRIBUTING.md](../../CONTRIBUTING.md) dosyasına bakın. Yeni politikalar, kenar durumları ve çeviriler hepsi hoş geldiniz. +Bkz. [CONTRIBUTING.md](../../CONTRIBUTING.md). Yeni politikalar, kenar durumları ve çeviriler hoş geldiniz. -> **Başlamadan önce derleyin.** Önce `bun install && bun run build` çalıştırın. Bu depo failproofai'nin kendi kancalarını kendisinde çalıştırır ve bunlar `failproofai` ithalatını derlenmiş `dist/` paketine karşı çözer — derleme olmadan `Cannot find package 'failproofai'` kanca hatalarına çarparsınız. `src/` dosyalarını değiştirdikten sonra yeniden derleyin. Bkz. [In-repo dev kankaları çalışacak şekilde Derle](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). +> **Başlamadan önce inşa edin.** Öncelikle `bun install && bun run build` çalıştırın. Bu depo failproofai'nın kendi kancalarını kendisinde çalıştırır ve bunlar `failproofai` ithalatını derlenmiş `dist/` paketi ile karşılaştırırlar — inşa olmadan `Cannot find package 'failproofai'` kanca hatalarına çarparsınız. `src/` değiştirildikten sonra yeniden inşa edin. Bkz. +> [İn-repo dev kancaları çalışması için inşa edin](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -San Francisco ve Bengaluru'da [befailproof.ai](https://befailproof.ai) tarafından ❤️ ile yapılmıştır. +❤️ ile [befailproof.ai](https://befailproof.ai) tarafından SF ve Bengaluru'da inşa edildi. diff --git a/docs/i18n/README.vi.md b/docs/i18n/README.vi.md index 2d302fe4..d98cb9b5 100644 --- a/docs/i18n/README.vi.md +++ b/docs/i18n/README.vi.md @@ -20,29 +20,29 @@ **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) -**Quan sát và thực thi mọi công cụ chạy trên agents của bạn.** -Bất cứ nơi nào agents chạy, chúng tôi đều thấy được — và chúng tôi có thể từ chối. Failproof kết nối với 12 công cụ agent -— các CLI lập trình như Claude Code và Codex, các cổng chat như Hermes, -các trợ lý tự lưu trữ như OpenClaw — ghi lại mọi lần chạy và chặn các lệnh gọi công cụ -nguy hiểm trước khi chúng thực thi. 40 chính sách được tích hợp sẵn. Độ trễ bằng không. Chạy cục bộ. +**Quan sát và thực thi cho mỗi công cụ chạy các agents của bạn.** +Cho dù agents chạy ở đâu, chúng tôi đều nhìn thấy — và chúng tôi có thể từ chối. failproofai kết nối 12 công cụ agent +— các CLI mã hóa như Claude Code và Codex, các cổng chat như Hermes, +trợ lý tự lưu trữ như OpenClaw — ghi lại mọi lần chạy và chặn các lệnh gọi công cụ nguy hiểm +trước khi chúng thực thi. 39 chính sách tích hợp sẵn. Độ trễ bằng không. Chạy cục bộ.

- Failproof AI hoạt động + Failproof AI in action

--- ## Các công cụ được hỗ trợ -Mười hai công cụ trong hai lớp — mười CLI lập trình, và hai cổng chat và trợ lý -(Hermes, OpenClaw). Cùng các sự kiện, cùng chính sách, cùng lịch sử phiên làm việc, -bất kể công cụ nào mà agent chạy trên đó. +Mười hai công cụ trong hai lớp — mười CLI mã hóa và hai cổng chat và trợ lý +(Hermes, OpenClaw). Các sự kiện giống nhau, các chính sách giống nhau, lịch sử phiên giống nhau, +bất kể agent của bạn chạy trong công cụ nào. -Các agents chạy trên không có công cụ nào báo cáo thông qua [Python SDK](https://docs.befailproof.ai/reference/custom-agents), -nó cung cấp cho bạn tracing, phiên làm việc và kiểm toán. Thực thi ở đó cần một hook trong -runtime của riêng bạn — [hãy liên hệ với chúng tôi](mailto:support@befailproof.ai) và chúng tôi sẽ ánh xạ nó. +Các agents chạy trong không có công cụ nào báo cáo thông qua [Python SDK](https://docs.befailproof.ai/reference/custom-agents), +cung cấp cho bạn tracing, phiên và kiểm toán. Thực thi ở đó cần một hook trong +runtime của riêng bạn — [liên hệ với chúng tôi](mailto:support@befailproof.ai) và chúng tôi sẽ ánh xạ nó. {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -146,7 +146,7 @@ failproofai policies --install # hoặc chỉ chạy `failproofai` và chấp failproofai ``` -40 chính sách được tích hợp sẵn sẽ kích hoạt ngay lập tức. Bảng điều khiển tại `localhost:8020`. Vô hiệu hóa lời nhắc lần đầu bằng `FAILPROOFAI_NO_FIRST_RUN=1`. +39 chính sách tích hợp sẵn được kích hoạt ngay lập tức. Dashboard tại `localhost:8020`. Vô hiệu hóa lời nhắc lần đầu với `FAILPROOFAI_NO_FIRST_RUN=1`. --- @@ -155,25 +155,25 @@ failproofai | Chính sách | Những gì nó chặn | |---|---| | `sanitize-api-keys` | Các khóa API rò rỉ vào ngữ cảnh của agent | -| `block-env-files` | Đọc các tệp `.env` và các tệp bí mật khác | -| `warn-repeated-tool-calls` | Agent lặp lại trên cùng một lệnh gọi | -| `block-sudo` | Nâng cao đặc quyền | +| `block-env-files` | Đọc các tệp `.env` và tệp bí mật khác | +| `warn-repeated-tool-calls` | Agent lặp lại cùng một lệnh gọi | +| `block-sudo` | Nâng cao quyền hạn | | `warn-destructive-sql` | `DROP`, `TRUNCATE`, `DELETE` không giới hạn | | `block-terraform` / `block-kubectl` | Các thay đổi không được xem xét đối với cơ sở hạ tầng trực tiếp | | `block-rm-rf` | Xóa tệp đệ quy | -| `block-force-push` / `block-push-master` | `git push --force`, các lần đẩy trực tiếp đến `main` | +| `block-force-push` / `block-push-master` | `git push --force`, đẩy trực tiếp đến `main` | -Năm chính sách đầu tiên áp dụng cho bất kỳ agent nào có thể gọi một công cụ. Ba chính sách cuối cùng là những yêu thích -của nhà phát triển — CLI lập trình là lớp công cụ mà chúng tôi bao phủ sâu nhất. +Năm cái đầu tiên áp dụng cho bất kỳ agent nào có thể gọi một công cụ. Ba cái cuối cùng là +những yêu thích của nhà phát triển — CLI mã hóa là lớp công cụ chúng tôi bao phủ sâu nhất. -→ [Tất cả 40 chính sách được tích hợp sẵn](https://docs.befailproof.ai/policies/builtin) +→ [Tất cả 39 chính sách tích hợp sẵn](https://docs.befailproof.ai/policies/builtin) --- -## Chính sách của riêng bạn +## Các chính sách của riêng bạn -Thả một tệp vào `.failproofai/policies/` — nó sẽ tải tự động, không cần bất kỳ cờ nào. -Commit nó và toàn bộ đội sẽ nhận được nó khi kéo xuống tiếp theo. +Thả một tệp vào `.failproofai/policies/` — nó tải tự động, không cần cờ nào. +Cam kết nó và toàn bộ nhóm của bạn sẽ nhận được nó vào lần kéo tiếp theo. ```js import { customPolicies, deny, allow } from "failproofai"; @@ -189,44 +189,45 @@ customPolicies.add({ }); ``` -Ba quyết định có sẵn cho mọi chính sách: +Ba quyết định có sẵn cho mỗi chính sách: -| Quyết định | Hiệu quả | +| Quyết định | Hiệu ứng | |---|---| | `allow()` | Cho phép hoạt động | -| `deny(message)` | Chặn nó — tin nhắn quay lại agent | -| `instruct(message)` | Cho phép nó tiếp tục, nhưng thêm ngữ cảnh vào lời nhắc tiếp theo của agent | +| `deny(message)` | Chặn nó — tin nhắn quay trở lại agent | +| `instruct(message)` | Cho phép nó, nhưng thêm ngữ cảnh vào lời nhắc tiếp theo của agent | → [Hướng dẫn chính sách tùy chỉnh](https://docs.befailproof.ai/policies/custom) --- -## Khả năng quan sát +## Quan sát -Thực thi là một nửa. Nửa còn lại là thấy được agent thực sự đã làm gì. +Thực thi là một nửa. Nửa còn lại là nhìn thấy những gì agent thực sự đã làm. -Chạy `failproofai` không có đối số và nó phục vụ một bảng điều khiển trên `localhost:8020` +Chạy `failproofai` mà không có đối số và nó phục vụ một dashboard trên `localhost:8020` đọc lịch sử chạy đã có trên máy của bạn — không có tài khoản, không có đăng ký, không có gì -rời khỏi hộp. Bạn nhận được danh sách phiên, trình tự các lệnh gọi mô hình, lệnh gọi công cụ -và quyết định hook bên trong mỗi lần chạy, những gì bị chặn và chính sách nói với agent, và một kiểm toán ngoại tuyến (`failproofai audit`) quét lịch sử của bạn để tìm các mẫu rủi ro -và gợi ý các chính sách để ngăn chặn chúng. +rời khỏi hộp. Bạn nhận được danh sách phiên, chuỗi các lệnh gọi mô hình, các lệnh gọi công cụ +và quyết định hook bên trong mỗi lần chạy, những gì bị chặn và những gì chính sách đã nói với agent, +và kiểm toán ngoại tuyến (`failproofai audit`) quét lịch sử của bạn để tìm các mô hình rủi ro +và đề xuất các chính sách để ngăn chặn chúng. -→ [Bảng điều khiển cục bộ](https://docs.befailproof.ai/reference/local-dashboard) · +→ [Dashboard cục bộ](https://docs.befailproof.ai/reference/local-dashboard) · [Đọc một trace](https://docs.befailproof.ai/sessions/read-a-trace) · [Kiểm toán cục bộ](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI Observability** là phía lưu trữ của cùng một mô hình dữ liệu, cho các đội -chạy agents trên một đội: mỗi lần chạy từ mỗi công cụ ở một nơi, biểu đồ thực thi -với các sub-agents song song trên các làn riêng của chúng, độ trễ p50/p95/p99 -cho mô hình, công cụ và hook, chi phí cho mỗi mô hình và theo dõi cửa sổ ngữ cảnh, theo dõi lỗi, SQL -trên các trace của riêng bạn với bảng điều khiển có thể chia sẻ, các đánh giá được chấm bởi -dịch vụ của riêng bạn, các kiểm toán định kỳ biến các lỗi định kỳ thành những phát hiện được hỗ trợ bằng bằng chứng, và các cảnh báo -được định tuyến đến Slack, email hoặc webhook được ký. Tự lưu trữ trong cluster của riêng bạn -có sẵn trong gói Enterprise. +**Failproof AI Observability** là phía được lưu trữ của cùng một mô hình dữ liệu, cho các nhóm +chạy agents trên một loạt: mỗi lần chạy từ mỗi công cụ ở một nơi, một biểu đồ thực thi +với các agents phụ song song trên các làn của riêng chúng, độ trễ p50/p95/p99 cho các mô hình, công cụ và hooks, +chi phí trên mỗi mô hình và theo dõi cửa sổ ngữ cảnh, theo dõi lỗi, SQL trên các traces của riêng bạn +với các dashboard có thể chia sẻ, các đánh giá được tính điểm bởi dịch vụ của riêng bạn, +các kiểm toán theo lịch trình biến các lỗi định kỳ thành các kết quả được hỗ trợ bằng bằng chứng, +và các cảnh báo được định tuyến đến Slack, email hoặc một webhook đã ký. Tự lưu trữ trong +cụm của riêng bạn có sẵn trong gói Enterprise. -→ [Phiên làm việc](https://docs.befailproof.ai/sessions/overview) · +→ [Phiên](https://docs.befailproof.ai/sessions/overview) · [Kiểm toán](https://docs.befailproof.ai/audits/overview) · -[Đặt lịch demo](https://befailproof.ai/get-a-demo) +[Đặt một buổi demo](https://befailproof.ai/get-a-demo) --- @@ -234,46 +235,46 @@ có sẵn trong gói Enterprise. | Bắt đầu | | |---|---| -| [Hướng dẫn nhanh](https://docs.befailproof.ai/start/quickstart) | Cài đặt, kết nối một công cụ, xem lần chạy đầu tiên | -| [Khái niệm](https://docs.befailproof.ai/start/concepts) | Cách hệ thống hook hoạt động | -| [Các công cụ được hỗ trợ](https://docs.befailproof.ai/reference/harnesses) | Tất cả 12, và những gì mỗi công cụ có thể thực thi | +| [Quickstart](https://docs.befailproof.ai/start/quickstart) | Cài đặt, kết nối một công cụ, xem lần chạy đầu tiên | +| [Khái niệm](https://docs.befailproof.ai/start/concepts) | Hệ thống hook hoạt động như thế nào | +| [Các công cụ được hỗ trợ](https://docs.befailproof.ai/reference/harnesses) | Tất cả 12, và những gì mỗi cái có thể thực thi | | Quan sát | | |---|---| -| [Phiên làm việc](https://docs.befailproof.ai/sessions/overview) | Theo dõi một lần chạy: mô hình, công cụ, lỗi, độ trễ | -| [Đọc một trace](https://docs.befailproof.ai/sessions/read-a-trace) | Những gì biểu đồ thực thi đang cho bạn biết | -| [Kiểm toán](https://docs.befailproof.ai/audits/overview) | Tìm các mẫu lỗi trên nhiều phiên | -| [Bảng điều khiển cục bộ](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, không cần tài khoản | +| [Phiên](https://docs.befailproof.ai/sessions/overview) | Theo dõi một lần chạy: mô hình, công cụ, lỗi, độ trễ | +| [Đọc một trace](https://docs.befailproof.ai/sessions/read-a-trace) | Biểu đồ thực thi đang nói với bạn điều gì | +| [Kiểm toán](https://docs.befailproof.ai/audits/overview) | Tìm các mô hình lỗi trên nhiều phiên | +| [Dashboard cục bộ](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`, không cần tài khoản | | Thực thi | | |---|---| -| [Chính sách được tích hợp sẵn](https://docs.befailproof.ai/policies/builtin) | Tất cả 40 chính sách với các tham số | -| [Chính sách tùy chỉnh](https://docs.befailproof.ai/policies/custom) | Viết chính sách của riêng bạn | -| [Cấu hình](https://docs.befailproof.ai/policies/local-configuration) | Phạm vi cấu hình và quy tắc hợp nhất | +| [Chính sách tích hợp sẵn](https://docs.befailproof.ai/policies/builtin) | Tất cả 39 chính sách với các tham số | +| [Chính sách tùy chỉnh](https://docs.befailproof.ai/policies/custom) | Viết của riêng bạn | +| [Cấu hình](https://docs.befailproof.ai/policies/local-configuration) | Các phạm vi cấu hình và quy tắc hợp nhất | -| Thiết lập agents của riêng bạn | | +| Công cụ các agent của riêng bạn | | |---|---| | [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | Báo cáo các lần chạy từ một agent không có công cụ | -| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Tham khảo `allow` / `deny` / `instruct` | +| [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | Tham chiếu `allow` / `deny` / `instruct` | --- ## Giấy phép -MIT với [Commons Clause](https://commonsclause.com/) — miễn phí để sử dụng nội bộ và cá nhân; bán lại failproofai yêu cầu một thỏa thuận riêng. Xem [LICENSE](../../LICENSE) để biết toàn bộ văn bản. +MIT với [Commons Clause](https://commonsclause.com/) — miễn phí cho mục đích sử dụng nội bộ và cá nhân; bán lại thương mại của failproofai yêu cầu một thỏa thuận riêng biệt. Xem [LICENSE](../../LICENSE) để xem toàn bộ văn bản. --- ## Đóng góp -Xem [CONTRIBUTING.md](../../CONTRIBUTING.md). Các chính sách mới, trường hợp cạnh và bản dịch đều được chào đón. +Xem [CONTRIBUTING.md](../../CONTRIBUTING.md). Các chính sách mới, trường hợp cạnh và bản dịch đều được hoan nghênh. -> **Build trước khi bạn bắt đầu.** Chạy `bun install && bun run build` trước. Repo này chạy -> các hook của failproofai trên chính nó, và chúng giải quyết import `failproofai` dựa trên -> bundled `dist/` được biên dịch — nếu không có build bạn sẽ gặp lỗi hook `Cannot find package 'failproofai'`. -> Xây dựng lại sau khi thay đổi `src/`. Xem +> **Xây dựng trước khi bạn bắt đầu.** Chạy `bun install && bun run build` trước tiên. Repo này chạy +> các hook của failproofai trên chính nó, và chúng phân giải import `failproofai` dựa trên +> gói đã biên dịch `dist/` — mà không có bản dựng bạn sẽ gặp lỗi hook +> `Cannot find package 'failproofai'`. Xây dựng lại sau khi thay đổi `src/`. Xem > [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work). --- -Xây dựng với ❤️ bởi [befailproof.ai](https://befailproof.ai) tại SF và Bengaluru. +Được xây dựng với ❤️ bởi [befailproof.ai](https://befailproof.ai) ở SF và Bengaluru. diff --git a/docs/i18n/README.zh.md b/docs/i18n/README.zh.md index a7799b29..ec890d09 100644 --- a/docs/i18n/README.zh.md +++ b/docs/i18n/README.zh.md @@ -20,8 +20,8 @@ **翻译版本：** [简体中文](../../docs/i18n/README.zh.md) · [日本語](../../docs/i18n/README.ja.md) · [한국어](../../docs/i18n/README.ko.md) · [Español](../../docs/i18n/README.es.md) · [Português](../../docs/i18n/README.pt-br.md) · [Deutsch](../../docs/i18n/README.de.md) · [Français](../../docs/i18n/README.fr.md) · [Русский](../../docs/i18n/README.ru.md) · [हिन्दी](../../docs/i18n/README.hi.md) · [Türkçe](../../docs/i18n/README.tr.md) · [Tiếng Việt](../../docs/i18n/README.vi.md) · [Italiano](../../docs/i18n/README.it.md) · [العربية](../../docs/i18n/README.ar.md) · [עברית](../../docs/i18n/README.he.md) -**为每一个 Agent 运行环境提供可观测性与执行管控。** -无论你的 Agent 在哪里运行，我们都能看到——并且可以说不。Failproof 接入了 12 个 Agent 运行框架——包括 Claude Code、Codex 等编程 CLI，Hermes 等聊天网关，以及 OpenClaw 等自托管助手——捕获每一次运行，并在危险工具调用执行前将其拦截。40 条内置策略，零延迟，本地运行。 +**为你的 Agent 在每个执行环境中提供可观测性与执行控制。** +无论 Agent 在哪里运行，我们都能看见——并且可以说不。Failproof 接入了 12 个 Agent 执行框架——包括 Claude Code、Codex 等编程 CLI，Hermes 等对话网关，以及 OpenClaw 等自托管助手——捕获每一次运行，并在危险工具调用执行前将其拦截。39 条内置策略，零延迟，本地运行。 @@ -31,11 +31,11 @@ --- -## 支持的运行框架 +## 支持的执行框架 -共十二个框架，分为两类——十个编程 CLI，以及两个聊天与助手网关（Hermes、OpenClaw）。无论你的 Agent 运行在哪个框架中，事件、策略和会话历史完全一致。 +共十二个执行框架，分为两类——十个编程 CLI，以及两个对话与助手网关（Hermes、OpenClaw）。无论你的 Agent 运行在哪一个框架中，事件、策略和会话历史完全一致。 -对于未接入上述框架的 Agent，可通过 [Python SDK](https://docs.befailproof.ai/reference/custom-agents) 上报数据，获得追踪、会话和审计能力。在该场景下的执行管控需要在你自己的运行时中植入 hook——[联系我们](mailto:support@befailproof.ai)，我们来帮你完成映射。 +若 Agent 不在上述任何框架中运行，可通过 [Python SDK](https://docs.befailproof.ai/reference/custom-agents) 上报数据，获得追踪、会话和审计能力。执行控制则需要在你自己的运行时中集成 hook——[联系我们](mailto:support@befailproof.ai)，我们会协助完成映射。 {/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens @@ -135,36 +135,37 @@ ```sh npm install -g failproofai -failproofai policies --install # 或直接运行 `failproofai` 并在首次运行提示时确认 +failproofai policies --install # 或直接运行 `failproofai` 并接受首次运行提示 failproofai ``` -40 条内置策略立即生效。Dashboard 地址：`localhost:8020`。可通过设置 `FAILPROOFAI_NO_FIRST_RUN=1` 禁用首次运行提示。 +39 条内置策略立即生效。仪表板地址为 `localhost:8020`。可通过设置 `FAILPROOFAI_NO_FIRST_RUN=1` 禁用首次运行提示。 --- -## 拦截范围 +## 它能拦截什么 | 策略 | 拦截内容 | |---|---| -| `sanitize-api-keys` | API 密钥泄露到 Agent 上下文 | +| `sanitize-api-keys` | API 密钥泄漏到 Agent 上下文中 | | `block-env-files` | 读取 `.env` 及其他密钥文件 | -| `warn-repeated-tool-calls` | Agent 在同一调用上循环执行 | +| `warn-repeated-tool-calls` | Agent 在同一调用上陷入循环 | | `block-sudo` | 权限提升 | | `warn-destructive-sql` | `DROP`、`TRUNCATE`、无条件 `DELETE` | | `block-terraform` / `block-kubectl` | 未经审查的生产基础设施变更 | | `block-rm-rf` | 递归删除文件 | | `block-force-push` / `block-push-master` | `git push --force`、直接推送到 `main` | -前五条适用于任何可以调用工具的 Agent，后三条是开发者最爱——编程 CLI 是我们覆盖最深入的框架类型。 +前五条适用于任何能调用工具的 Agent，后三条是开发者最常用的——编程 CLI 是我们覆盖最深的执行框架类别。 -→ [全部 40 条内置策略](https://docs.befailproof.ai/policies/builtin) +→ [全部 39 条内置策略](https://docs.befailproof.ai/policies/builtin) --- ## 自定义策略 -将文件放入 `.failproofai/policies/` 目录即可自动加载，无需任何参数。提交到代码仓库后，全团队在下次拉取时即可生效。 +在 `.failproofai/policies/` 目录中放入一个文件——它会自动加载，无需任何标志。 +提交到代码仓库后，团队所有成员在下次拉取时即可生效。 ```js import { customPolicies, deny, allow } from "failproofai"; @@ -180,13 +181,13 @@ customPolicies.add({ }); ``` -每条策略可使用三种决策： +每条策略可做出以下三种决策： | 决策 | 效果 | |---|---| | `allow()` | 允许该操作 | -| `deny(message)` | 拦截操作——消息返回给 Agent | -| `instruct(message)` | 放行操作，但在 Agent 的下一次提示中附加上下文信息 | +| `deny(message)` | 拦截它——消息会回传给 Agent | +| `instruct(message)` | 放行，但在 Agent 的下一个提示中附加上下文 | → [自定义策略指南](https://docs.befailproof.ai/policies/custom) @@ -194,18 +195,18 @@ customPolicies.add({ ## 可观测性 -执行管控是一半，另一半是看清 Agent 实际做了什么。 +执行控制是一半，另一半是看清 Agent 究竟做了什么。 -不带任何参数运行 `failproofai`，它会在 `localhost:8020` 启动一个 Dashboard，读取已存储在本机的运行历史——无需账户，无需注册，数据不离开本机。你可以查看会话列表、每次运行中模型调用和工具调用的序列、hook 决策记录、哪些操作被拦截、策略向 Agent 传达了什么，以及离线审计（`failproofai audit`）——它会扫描你的历史记录，发现风险模式并推荐相应策略。 +不带参数运行 `failproofai`，它会在 `localhost:8020` 启动一个仪表板，读取已存储在本机上的运行历史——无需账号、无需注册、数据不离机。你可以查看会话列表、每次运行中模型调用的序列、工具调用和 hook 决策、被拦截的内容以及策略告知 Agent 的信息，还可以进行离线审计（`failproofai audit`），扫描历史记录中的风险模式并推荐相应策略加以防范。 -→ [本地 Dashboard](https://docs.befailproof.ai/reference/local-dashboard) · -[读取追踪记录](https://docs.befailproof.ai/sessions/read-a-trace) · +→ [本地仪表板](https://docs.befailproof.ai/reference/local-dashboard) · +[解读追踪记录](https://docs.befailproof.ai/sessions/read-a-trace) · [本地审计](https://docs.befailproof.ai/audits/local-audit) -**Failproof AI 可观测性**是同一数据模型的托管端，面向在集群中跨多个框架运行 Agent 的团队：所有框架的每次运行集中呈现，带有并行子 Agent 独立泳道的执行图，模型、工具和 hook 的 p50/p95/p99 延迟，按模型的费用和上下文窗口跟踪，错误追踪，基于自有 trace 数据的 SQL 查询与可分享 Dashboard，由你自己的服务评分的评估结果，将重复失败转化为有据可查发现的定时审计，以及路由到 Slack、邮件或签名 Webhook 的告警。在企业版计划中支持在你自己的集群中自托管部署。 +**Failproof AI Observability** 是同一数据模型的托管版本，专为在集群中运行 Agent 的团队而设计：来自所有框架的每次运行都汇聚在一处，执行图以独立泳道展示并行子 Agent，提供模型、工具和 hook 的 p50/p95/p99 延迟数据，按模型统计成本与上下文窗口用量，错误追踪，基于自有追踪数据的 SQL 查询与可分享仪表板，由你自己的服务评分的评估功能，将重复性故障转化为有据可查发现的定期审计，以及路由到 Slack、邮件或签名 Webhook 的告警。Enterprise 计划支持在你自己的集群中自托管。 -→ [Sessions](https://docs.befailproof.ai/sessions/overview) · -[Audits](https://docs.befailproof.ai/audits/overview) · +→ [会话](https://docs.befailproof.ai/sessions/overview) · +[审计](https://docs.befailproof.ai/audits/overview) · [预约演示](https://befailproof.ai/get-a-demo) --- @@ -214,42 +215,42 @@ customPolicies.add({ | 入门 | | |---|---| -| [快速开始](https://docs.befailproof.ai/start/quickstart) | 安装、接入框架、查看首次运行结果 | -| [核心概念](https://docs.befailproof.ai/start/concepts) | Hook 系统的工作原理 | -| [支持的框架](https://docs.befailproof.ai/reference/harnesses) | 全部 12 个框架及各自的执行管控能力 | +| [快速开始](https://docs.befailproof.ai/start/quickstart) | 安装、连接执行框架、查看第一次运行 | +| [核心概念](https://docs.befailproof.ai/start/concepts) | hook 系统的工作原理 | +| [支持的执行框架](https://docs.befailproof.ai/reference/harnesses) | 全部 12 个，以及每个可执行的控制能力 | -| 可观测性 | | +| 观测 | | |---|---| -| [Sessions](https://docs.befailproof.ai/sessions/overview) | 跟踪运行过程：模型、工具、错误、延迟 | -| [读取追踪记录](https://docs.befailproof.ai/sessions/read-a-trace) | 执行图所反映的信息 | -| [Audits](https://docs.befailproof.ai/audits/overview) | 跨多个会话发现失败模式 | -| [本地 Dashboard](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`，无需账户 | +| [会话](https://docs.befailproof.ai/sessions/overview) | 跟踪一次运行：模型、工具、错误、延迟 | +| [解读追踪记录](https://docs.befailproof.ai/sessions/read-a-trace) | 执行图在告诉你什么 | +| [审计](https://docs.befailproof.ai/audits/overview) | 在多个会话中发现故障模式 | +| [本地仪表板](https://docs.befailproof.ai/reference/local-dashboard) | `localhost:8020`，无需账号 | -| 执行管控 | | +| 执行控制 | | |---|---| -| [内置策略](https://docs.befailproof.ai/policies/builtin) | 全部 40 条策略及参数说明 | +| [内置策略](https://docs.befailproof.ai/policies/builtin) | 全部 39 条策略及其参数 | | [自定义策略](https://docs.befailproof.ai/policies/custom) | 编写你自己的策略 | -| [配置说明](https://docs.befailproof.ai/policies/local-configuration) | 配置作用域与合并规则 | +| [配置](https://docs.befailproof.ai/policies/local-configuration) | 配置作用域与合并规则 | -| 接入自定义 Agent | | +| 接入你自己的 Agent | | |---|---| -| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | 为无框架的 Agent 上报运行数据 | +| [Python SDK](https://docs.befailproof.ai/reference/custom-agents) | 从没有执行框架的 Agent 上报运行数据 | | [Policy SDK](https://docs.befailproof.ai/reference/policy-sdk) | `allow` / `deny` / `instruct` 参考文档 | --- ## 许可证 -MIT 附加 [Commons Clause](https://commonsclause.com/)——个人和企业内部使用免费；将 failproofai 本身作为商业产品转售需要单独签署协议。完整条款请见 [LICENSE](../../LICENSE)。 +MIT 附加 [Commons Clause](https://commonsclause.com/)——个人和内部使用免费；将 failproofai 本身用于商业转售需另行签订协议。完整条款请参阅 [LICENSE](../../LICENSE)。 --- -## 参与贡献 +## 贡献 -请参阅 [CONTRIBUTING.md](../../CONTRIBUTING.md)。欢迎贡献新策略、边界案例和翻译内容。 +请参阅 [CONTRIBUTING.md](../../CONTRIBUTING.md)。欢迎贡献新策略、边界情况处理和翻译。 -> **开始前请先构建项目。** 请先运行 `bun install && bun run build`。本仓库会将 failproofai 自身的 hook 应用于自己，这些 hook 会从编译后的 `dist/` 包中解析 `failproofai` 模块导入——未执行构建将导致出现 `Cannot find package 'failproofai'` 的 hook 错误。修改 `src/` 后需重新构建。详见 [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)。 +> **开始前请先构建。** 首先运行 `bun install && bun run build`。本仓库会在自身上运行 failproofai 的 hook，这些 hook 会将 `failproofai` 的导入解析到编译后的 `dist/` 包——如果没有构建，你会遇到 `Cannot find package 'failproofai'` 的 hook 错误。修改 `src/` 后需重新构建。详见 [Build before the in-repo dev hooks will work](../../CONTRIBUTING.md#build-before-the-in-repo-dev-hooks-will-work)。 --- -由 [befailproof.ai](https://befailproof.ai) 团队在旧金山和班加罗尔倾心打造 ❤️。 +由 [befailproof.ai](https://befailproof.ai) 团队在旧金山和班加罗尔用 ❤️ 打造。 diff --git a/docs/it/policies/builtin-catalog.mdx b/docs/it/policies/builtin-catalog.mdx index 36b79014..80b9b052 100644 --- a/docs/it/policies/builtin-catalog.mdx +++ b/docs/it/policies/builtin-catalog.mdx @@ -1,106 +1,110 @@ --- -title: "Catalogo delle politiche integrate" -description: "Rivedi ogni politica integrata di Failproof AI, il suo trigger, lo stato consigliato e i parametri configurabili." +title: "Catalogo delle policy builtin" +description: "Esamina ogni policy builtin di Failproof AI, il suo trigger, lo stato consigliato e i parametri configurabili." icon: "list-checks" --- -Il pacchetto installato è la fonte di verità per la disponibilità delle politiche. Esegui `failproofai policies` dopo ogni aggiornamento perché le voci del catalogo e il comportamento possono cambiare con la versione del pacchetto. +Il pacchetto installato è la fonte di verità per la disponibilità delle policy. Esegui `failproofai policies` dopo ogni aggiornamento perché le voci del catalogo e il comportamento possono cambiare con la versione del pacchetto. -## Baseline consigliata +## Configurazione di base consigliata -La selezione consigliata della configurazione guidata attualmente abilita i sanitizzatori di segreti, le protezioni dell'ambiente, l'auto-protezione, le protezioni dai comandi catastrofici e la sicurezza dei rami protetti: +La selezione consigliata dalla configurazione guidata abilita attualmente i sanitizzatori di segreti, le protezioni ambientali, l'autoprotection, i guard per i comandi catastrofici e la sicurezza dei rami protetti: ```text sanitize-jwt sanitize-api-keys sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars block-env-files block-secrets-write -block-self-pause block-failproofai-commands -block-sudo block-curl-pipe-sh -block-rm-rf block-push-master -block-force-push +block-failproofai-commands block-sudo +block-curl-pipe-sh block-rm-rf +block-push-master block-force-push ``` -La configurazione consigliata è deliberatamente più ristretta di **Everything**. Le politiche infrastrutturali e di workflow possono interrompere il lavoro valido e dovrebbero essere abilitate per i repository e le macchine che ne hanno bisogno. +`block-failproofai-commands` è **sempre attivo**. È elencato sopra per +completezza, ma si registra ad ogni valutazione indipendentemente dal fatto che +appaia nel tuo set abilitato, e non può essere disabilitato o messo in pausa — una +protezione contro l'agente che disattiva l'enforcement che l'agente potrebbe +disattivare non è una protezione. + +La configurazione consigliata è volutamente più ristretta di **Everything**. Le policy infrastrutturali e di workflow possono interrompere operazioni valide e dovrebbero essere abilitate solo per i repository e le macchine che ne hanno bisogno. ## Segreti e ambiente -| Politica | Trigger | Risultato | +| Policy | Trigger | Risultato | | --- | --- | --- | -| `sanitize-jwt` | `PostToolUse` | Redige i JWT dall'output dello strumento prima che il modello li veda. | -| `sanitize-api-keys` | `PostToolUse` | Redige le chiavi comuni di OpenAI, Anthropic, GitHub, AWS, Stripe e Google. | -| `sanitize-connection-strings` | `PostToolUse` | Redige le stringhe di connessione ai database contenenti credenziali. | -| `sanitize-private-key-content` | `PostToolUse` | Redige i corpi delle chiavi private PEM. | -| `sanitize-bearer-tokens` | `PostToolUse` | Redige i token bearer di autorizzazione. | -| `protect-env-vars` | `PreToolUse` sugli strumenti shell | Blocca i comandi che dumpa le variabili d'ambiente. | -| `block-env-files` | `PreToolUse` | Blocca le letture e le scritture dei file `.env`. | -| `block-read-outside-cwd` | `PreToolUse` sugli strumenti read, glob, grep o shell | Mantiene le letture all'interno della directory di lavoro della sessione. | -| `block-secrets-write` | `PreToolUse` sugli strumenti di scrittura | Blocca le scritture su nomi di file comuni di chiavi segrete e credenziali. | +| `sanitize-jwt` | `PostToolUse` | Rimuovi i JWT dall'output dello strumento prima che il modello li veda. | +| `sanitize-api-keys` | `PostToolUse` | Rimuovi le chiavi comuni di OpenAI, Anthropic, GitHub, AWS, Stripe e Google. | +| `sanitize-connection-strings` | `PostToolUse` | Rimuovi le stringhe di connessione al database contenenti credenziali. | +| `sanitize-private-key-content` | `PostToolUse` | Rimuovi i corpi delle chiavi private PEM. | +| `sanitize-bearer-tokens` | `PostToolUse` | Rimuovi i token bearer di autorizzazione. | +| `protect-env-vars` | `PreToolUse` su strumenti shell | Blocca i comandi che scaricano le variabili di ambiente. | +| `block-env-files` | `PreToolUse` | Blocca letture e scritture dei file `.env`. | +| `block-read-outside-cwd` | `PreToolUse` su strumenti read, glob, grep o shell | Mantieni le letture all'interno della directory di lavoro della sessione. | +| `block-secrets-write` | `PreToolUse` su strumenti di scrittura | Blocca le scritture ai nomi di file di chiavi segrete e credenziali comuni. | ## Comandi pericolosi e infrastruttura -| Politica | Trigger | Risultato | +| Policy | Trigger | Risultato | | --- | --- | --- | -| `block-self-pause` | `PreToolUse`, `PermissionRequest` | Impedisce a un agente di mettere in pausa la propria applicazione. | | `block-sudo` | `PreToolUse`, `PermissionRequest` | Blocca `sudo` a meno che un pattern di allow non corrisponda. | -| `block-curl-pipe-sh` | `PreToolUse` | Blocca gli script scaricati incanalati direttamente a una shell. | +| `block-curl-pipe-sh` | `PreToolUse` | Blocca gli script scaricati inviati direttamente a una shell. | | `block-rm-rf` | `PreToolUse` | Blocca i pattern di eliminazione ricorsiva catastrofici. | -| `block-failproofai-commands` | `PreToolUse` | Impedisce agli agenti di modificare o disinstallare Failproof AI. | +| `block-failproofai-commands` | `PreToolUse`, `PermissionRequest` | **Sempre attivo, non può essere disabilitato.** Blocca ogni invocazione CLI di Failproof AI, l'auto-pausa e la disinstallazione del package manager. | | `block-kubectl` | `PreToolUse` | Controlla i comandi Kubernetes. | | `block-terraform` | `PreToolUse` | Controlla i comandi Terraform e OpenTofu. | | `block-aws-cli` | `PreToolUse` | Controlla i comandi AWS CLI. | | `block-gcloud` | `PreToolUse` | Controlla i comandi Google Cloud CLI. | | `block-az-cli` | `PreToolUse` | Controlla i comandi Azure CLI. | | `block-helm` | `PreToolUse` | Controlla i comandi Helm. | -| `block-gh-pipeline` | `PreToolUse` | Controlla le operazioni mutanti di GitHub CLI per workflow, run, merge, release, cache e secret. | +| `block-gh-pipeline` | `PreToolUse` | Controlla le operazioni mutevoli di GitHub CLI per workflow, run, merge, release, cache e secret. | -## Sicurezza di Git e database +## Sicurezza Git e database -| Politica | Trigger | Risultato | +| Policy | Trigger | Risultato | | --- | --- | --- | | `block-push-master` | `PreToolUse` | Blocca i push diretti ai rami protetti configurati. | -| `block-force-push` | `PreToolUse` | Blocca i force-push; `--force-with-lease` rimane consentito nell'implementazione attuale. | -| `block-work-on-main` | `PreToolUse` | Blocca i commit e i merge su rami protetti. | -| `warn-git-amend` | `PreToolUse` | Avverte prima di riscrivere un commit con `--amend`. | -| `warn-git-stash-drop` | `PreToolUse` | Avverte prima di eliminare o cancellare permanentemente gli stash. | -| `warn-all-files-staged` | `PreToolUse` | Avverte su `git add -A`, `git add .` o `git add --all` ampi. | -| `warn-destructive-sql` | `PreToolUse` | Avverte su `DROP`, `TRUNCATE` e `DELETE` senza `WHERE` attraverso client di database riconosciuti. | -| `warn-schema-alteration` | `PreToolUse` | Avverte su operazioni di rinomina e colonne `ALTER TABLE` riconosciute. | +| `block-force-push` | `PreToolUse` | Blocca i force-push; `--force-with-lease` rimane consentito dall'implementazione attuale. | +| `block-work-on-main` | `PreToolUse` | Blocca i commit e i merge sui rami protetti. | +| `warn-git-amend` | `PreToolUse` | Avvisa prima di riscrivere un commit con `--amend`. | +| `warn-git-stash-drop` | `PreToolUse` | Avvisa prima di eliminare o cancellare definitivamente gli stash. | +| `warn-all-files-staged` | `PreToolUse` | Avvisa su ampi `git add -A`, `git add .` o `git add --all`. | +| `warn-destructive-sql` | `PreToolUse` | Avvisa su `DROP`, `TRUNCATE` e `DELETE` senza `WHERE` tramite client database riconosciuti. | +| `warn-schema-alteration` | `PreToolUse` | Avvisa su operazioni di colonna e rinomina di `ALTER TABLE` riconosciute. | -## Pacchetti, comportamento del sistema e loop degli agenti +## Pacchetti, comportamento del sistema e loop dell'agente -| Politica | Trigger | Risultato | +| Policy | Trigger | Risultato | | --- | --- | --- | -| `warn-package-publish` | `PreToolUse` | Avverte prima di pubblicare nei registri dei pacchetti. | -| `warn-global-package-install` | `PreToolUse` | Avverte prima dell'installazione globale dei pacchetti. | -| `prefer-package-manager` | `PreToolUse` | Istruisce l'agente a utilizzare un gestore di pacchetti consentito. | -| `warn-large-file-write` | `PreToolUse` sugli strumenti di scrittura | Avverte oltre la soglia di dimensione del file configurata. | -| `warn-background-process` | `PreToolUse` | Avverte su pattern di processi in background distaccati o di lunga durata. | -| `warn-repeated-tool-calls` | `PreToolUse` | Avverte dopo tre o più chiamate identiche dello strumento. | +| `warn-package-publish` | `PreToolUse` | Avvisa prima di pubblicare nei registri dei pacchetti. | +| `warn-global-package-install` | `PreToolUse` | Avvisa prima dell'installazione globale dei pacchetti. | +| `prefer-package-manager` | `PreToolUse` | Indica all'agente di utilizzare un package manager consentito. | +| `warn-large-file-write` | `PreToolUse` su strumenti di scrittura | Avvisa oltre la soglia di dimensione file configurata. | +| `warn-background-process` | `PreToolUse` | Avvisa su pattern di processi in background distaccati o di lunga durata. | +| `warn-repeated-tool-calls` | `PreToolUse` | Avvisa dopo tre o più chiamate di strumento identiche. | -## Workflow di fine compito +## Workflow di fine attività -Queste politiche richiedono un harness che emetta un evento `Stop` compatibile. +Queste policy richiedono un harness che emetta un evento `Stop` compatibile. -| Politica | Risultato | +| Policy | Risultato | | --- | --- | -| `require-commit-before-stop` | Rifiuta il completamento mentre il lavoro tracciato rimane uncommitted. | +| `require-commit-before-stop` | Rifiuta il completamento mentre il lavoro tracciato rimane non committato. | | `require-push-before-stop` | Rifiuta il completamento mentre i commit rimangono solo locali. | -| `require-pr-before-stop` | Richiede una pull request per il ramo attuale. | -| `require-no-conflicts-before-stop` | Richiede un merge pulito rispetto al ramo di base configurato. | -| `require-ci-green-before-stop` | Richiede il completamento corretto dei controlli CI di current-HEAD. | +| `require-pr-before-stop` | Richiede una pull request per il ramo corrente. | +| `require-no-conflicts-before-stop` | Richiede un merge pulito rispetto al ramo base configurato. | +| `require-ci-green-before-stop` | Richiede che i controlli CI di current-HEAD si completino con successo. | ## Riferimento dei parametri -Configura i parametri nell'oggetto `policyParams` dello scope selezionato. I tipi sono validati da ogni politica. +Configura i parametri sotto l'oggetto `policyParams` dell'ambito selezionato. I tipi sono validati da ogni policy. -| Politica | Parametro | Tipo e default | +| Policy | Parametro | Tipo e default | | --- | --- | --- | | `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; le voci contengono `regex` e `label` | | `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | | `block-sudo` | `allowPatterns` | `string[]`, `[]` | | `block-rm-rf` | `allowPaths` | `string[]`, `[]` | -| Bloccanti infrastrutturali | `allowPatterns` | `string[]`, `[]` | +| Blocchi infrastrutturali | `allowPatterns` | `string[]`, `[]` | | `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | | `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | | `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | @@ -125,5 +129,5 @@ Configura i parametri nell'oggetto `policyParams` dello scope selezionato. I tip ``` - Un pattern di allow amplia ciò che un agente può fare. Testa la tokenizzazione esatta e le varianti di comando sull'harness di destinazione prima di distribuirla su una flotta. + Un pattern di allow allarga ciò che un agente può fare. Testa la tokenizzazione esatta e le varianti di comando sull'harness target prima di distribuirla in una flotta. \ No newline at end of file diff --git a/docs/it/policies/failure-behavior.mdx b/docs/it/policies/failure-behavior.mdx index 35160dc7..a248d508 100644 --- a/docs/it/policies/failure-behavior.mdx +++ b/docs/it/policies/failure-behavior.mdx @@ -1,19 +1,20 @@ --- +--- title: "Comportamento in caso di errore" description: "Comprendi cosa accade quando la valutazione delle policy o il daemon locale non è disponibile." icon: "shield-alert" --- -Failproof AI è progettato in modo che un errore di enforcement sia visibile piuttosto che consentire silenziosamente operazioni rischiose. +Failproof AI è progettato affinché un errore di enforcement sia visibile piuttosto che consentire silenziosamente lavori rischiosi. ## Diagnosticare un blocco failure-closed - 1. Vai su **Admin → enforcement** e apri la macchina. - 2. Verifica il suo ultimo check-in, la deployment assegnata e la deployment segnalata. - 3. Vai su **Observe → policy** e apri la sessione della decisione negata. - 4. Conferma se il motivo segnala la raggiungibilità del daemon, lo skew di versione o la policy stessa. + 1. Vai a **Admin → enforcement** e apri la macchina. + 2. Controlla il suo ultimo check-in, il deployment assegnato e il deployment segnalato. + 3. Vai a **Observe → policy** e apri la sessione della decisione negata. + 4. Conferma se il motivo segnala raggiungibilità del daemon, version skew o la policy stessa. @@ -23,21 +24,45 @@ Failproof AI è progettato in modo che un errore di enforcement sia visibile piu failproofai config ``` - Rieseguire `failproofai config` aggiorna e riavvia il daemon dopo un aggiornamento del pacchetto. + Rieseguire `failproofai config` aggiorna e riavvia il daemon dopo un upgrade del pacchetto. -Su una macchina configurata per utilizzare `failproofaid`, il daemon è l'unico valutatore. Se non è raggiungibile o la sua versione di protocollo non corrisponde a quella della CLI, la valutazione dell'hook fallisce in modalità chiusa. L'azione viene negata con un motivo che dirige l'operatore a controllare o aggiornare il daemon. +Su una macchina configurata per usare `failproofaid`, il daemon è l'unico valutatore. Se non è raggiungibile o la sua versione del protocollo non corrisponde alla CLI, la valutazione dell'hook fallisce in modo chiuso. L'azione viene negata con un motivo che indirizza l'operatore a controllare o aggiornare il daemon. -Prima della configurazione del daemon, gli hook valutano le policy in process. Una volta registrata la configurazione del daemon, Failproof AI non ritorna silenziosamente a un secondo valutatore quando il daemon fallisce. +Prima della configurazione del daemon, gli hook valutano le policy in process. Una volta registrata la configurazione del daemon, Failproof AI non torna silenziosamente a un secondo valutatore quando il daemon fallisce. ## Rispondere a una decisione failure-closed 1. Esegui `failproofai config --status`. 2. Se le versioni differiscono, riesegui `failproofai config` dopo aver aggiornato il pacchetto. -3. Se il daemon non è raggiungibile, ispeziona lo stato del servizio e i log locali. -4. Riprendi il lavoro dell'agent solo dopo aver verificato che un percorso noto di valutazione delle policy è sano. +3. Se il daemon non è raggiungibile, ispeziona lo stato del suo servizio e i log locali. +4. Riprendi il lavoro dell'agent solo dopo aver verificato che un percorso di valutazione della policy noto è sano. - Non riprovare ripetutamente l'azione bloccata. Una risposta failure-closed significa che il sistema non ha potuto stabilire che l'azione fosse sicura. - \ No newline at end of file + Non ritentare ripetutamente l'azione bloccata. Una risposta failure-closed significa che il sistema non ha potuto stabilire che l'azione era sicura. + + +## Un pack non si caricherà + +Una macchina a cui è stato ordinato di applicare un pack, e che non può eseguirlo, nega piuttosto che continuare silenziosamente. Il trigger è un'**aspettativa registrata**, mai una vuota: una macchina senza pack installati è silenziosa, mentre un pack che è dichiarato e non si risolverà — o che registra meno di quanto dichiara il suo manifest — nega. + +La negazione è **ristretta**, a differenza di un daemon non raggiungibile. Un daemon che non può essere raggiunto significa che nessuna valutazione è avvenuta affatto, quindi nulla può essere conosciuto come sicuro. Un pack che non si carica ha un insieme enumerabile di guardie mancanti, perché ogni policy dichiarata porta il suo `match` — quindi nega solo gli eventi e i tool coperti da quelle policy, e tutto il resto procede. + +Non si attiva per: + +- un pack `observe`, che valuta e scarta per costruzione +- policy che non hai mai preso, o che hai esplicitamente disattivato +- un pack che il loader non ha mai ricevuto, dove "nessuna registrazione" non può essere distinta da un salto deliberato +- una pausa di sessione attiva +- un timeout di caricamento, che è transitorio — un momento di disco lento non deve negare fino a quando un umano interviene + +`UserPromptSubmit` **istruisce** invece di negare, indipendentemente da cosa dichiarava la policy mancante. Una negazione generale la porterebbe con sé e ti bloccherebbe fuori dall'agent che potrebbe risolvere il problema. + +### Cosa fare + +```bash +failproofai pack list +``` + +Elenca qualsiasi pack installato che non si carica, spiega il motivo, ed esce con codice non-zero. Poi o reinstallalo (`failproofai pack add `) o rimuovilo (`failproofai pack remove `) — rimuoverlo ritira l'aspettativa, e la negazione si ferma con essa. \ No newline at end of file diff --git a/docs/it/policies/packs.mdx b/docs/it/policies/packs.mdx new file mode 100644 index 00000000..10f70eb7 --- /dev/null +++ b/docs/it/policies/packs.mdx @@ -0,0 +1,110 @@ +--- +title: "Policy pack" +description: "Installa un set di policy pubblicato come release di GitHub e gestisci ciò che applica." +icon: "package" +--- + +Un pack è un set di policy pubblicato come release di GitHub. Un solo comando lo installa, i checksum della release vengono verificati prima che qualsiasi cosa venga eseguita e il digest viene registrato in modo che il pack non possa cambiare sulla tua macchina successivamente. + +## Installa le policy di Failproof AI + +```bash +failproofai pack add core +``` + +Questo installa il set che pubblichiamo, dalla copia contenuta nel package — quindi non richiede rete e non può fallire dietro a un proxy. Puoi prenderne parte: + +```bash +failproofai pack add core --policy block-rm-rf # una, o un gruppo separato da virgole +failproofai pack add core --category dangerous-commands # un'intera categoria +failproofai pack add core --all # tutto ciò che contiene +``` + +`failproofai pack list` mostra il nome di ogni categoria che il pack offre. + +## Vedi cosa contiene un pack, prima di installarlo + +```bash +failproofai pack list acme/support-agent +``` + +Elenca ogni policy che il pack contiene, raggruppate per categoria, contrassegnando quali l'autore attiva per default e quali sono facoltative. Legge **solo il manifest** — l'artifact principale non viene mai scaricato né importato, quindi guardare il pack di uno sconosciuto non può eseguire il codice di uno sconosciuto. Il manifest è comunque verificato rispetto al `SHA256SUMS` della release, quindi quello che stai leggendo è quello che verrebbe installato. + +`failproofai pack list` senza sorgente elenca i pack già installati qui. + +## Installa il pack di qualcun altro + +```bash +failproofai pack add acme/support-agent +``` + +Una qualsiasi di queste opzioni funziona — incolla quella che hai: + +| Sorgente | Risultato | +| --- | --- | +| `acme/support-agent` | Release più recente, **fissata** al tag esatto a cui è stata risolta | +| `acme/support-agent@v2.1.0` | Quella release | +| `github:acme/support-agent@v2.1.0` | La stessa, scritta esplicitamente | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | La stessa, copiata da un browser | + +Se non specifichi un tag, installa la release più recente **e la fissa**, poi ti dice quale tag ha scelto. Ciò che viene registrato nomina sempre esattamente una release, quindi una reinstallazione non può deviare. + +## Prendi parte di un pack + +Per default ottieni i **propri** default del pack — le policy che l'autore ha contrassegnato come sicure da attivare senza sorveglianza — non tutto ciò che contiene. + +```bash +failproofai pack add acme/support-agent --category billing,git +failproofai pack add acme/support-agent --policy block-refunds +failproofai pack add acme/support-agent --all +``` + +`--category` e `--policy` si combinano come un'unione (`--only` è accettato come sinonimo di `--policy`). Aggiungere di nuovo una versione più recente mantiene ciò che hai scelto invece di riattivare il resto. + +## Gestisci cosa è attivo + +```bash +failproofai policies # ogni sorgente in un unico elenco, pack inclusi +failproofai pack list # solo i pack, raggruppati per categoria +failproofai policies --uninstall block-refunds # disattiva una policy del pack +failproofai policies --install block-refunds # e riattivala +failproofai pack remove acme/support-agent +``` + +Un nome senza qualificazione significa quella **incorporata** quando esiste con quel nome. Qualifica esplicitamente il nome della copia del pack quando necessario: + +```bash +failproofai policies --uninstall acme/support-agent:block-refunds +``` + + +Se un pack contiene una policy il cui nome è anche una **builtin abilitata**, la builtin viene eseguita e la copia del pack viene saltata — altrimenti lo stesso controllo verrebbe valutato due volte. Disattiva la builtin per usare la copia del pack. + + +## Da dove provengono le policy di Failproof AI + +`core` legge la copia vendored nel package npm. Lo stesso set è pubblicato come release di GitHub, che è ciò che installi se vuoi una versione specifica: + +```bash +failproofai pack add core # da questo package, senza rete +failproofai pack add FailproofAI/policies # lo stesso set, dalla sua release di GitHub +``` + +## Cosa l'integrità garantisce e non garantisce + +`SHA256SUMS` viene fornito nella stessa release dell'artifact, quindi **non** è una firma e non prova nulla su chi l'ha pubblicato. Ciò che prova è che i byte sono quelli che quella release ha pubblicato — e poiché il digest viene registrato quando aggiungi il pack e viene ri-verificato prima di ogni importazione, un pack non può cambiare sulla tua macchina successivamente. Un repository che retag o sostituisce un asset smette di caricarsi invece di eseguire silenziosamente qualcos'altro. + +Al momento dell'installazione il pack viene anche **importato una volta** e verificato rispetto al suo manifest. Un pack il cui artifact non analizza, o che registra qualcosa di diverso da quello che dichiara, viene rifiutato prima che qualsiasi cosa venga attivata — piuttosto che installarsi correttamente e fallire alla tua prossima tool call. + +## Quando un pack non si caricherà + +Un pack che questa macchina è stata istruita ad applicare e non può eseguire **nega** gli eventi che le sue policy mancanti coprivano, invece di consentirli silenziosamente. Vedi [Failure behavior](/it/policies/failure-behavior). `failproofai pack list` nomina qualsiasi pack in quello stato ed esce con non-zero. + +## Offline e mirror + +| Variabile | Effetto | +| --- | --- | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Rifiuta di recuperare; i pack già installati continuano ad applicarsi | +| `FAILPROOFAI_PACK_BASE_URL` | Indirizza il recupero dei pack a un mirror invece di `github.com` | + +Pubblicare il tuo pack: vedi [Publish a pack](/it/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/it/policies/publish-a-pack.mdx b/docs/it/policies/publish-a-pack.mdx new file mode 100644 index 00000000..10ae47d1 --- /dev/null +++ b/docs/it/policies/publish-a-pack.mdx @@ -0,0 +1,91 @@ +--- +title: "Pubblicare un pack" +description: "Distribuisci le tue policy come release GitHub che chiunque può installare." +icon: "upload" +--- + +Un pack è costituito da tre file allegati a una release GitHub. `failproofai pack build` scrive tutti e tre a partire da un file di policy che hai già. + +## 1. Scrivi le policy + +Un file, usando la stessa API di qualsiasi policy personalizzata. Due campi extra sono importanti per un pack: + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-refunds", + description: "Refunds above the approved limit need a human", + category: "Billing", // groups it, and is what --category selects on + defaultEnabled: true, // switched on by a plain `pack add` + match: { events: ["PreToolUse"], tools: ["Bash"] }, + fn: async (ctx) => + String(ctx.toolInput?.command ?? "").includes("refund") + ? deny("Refunds need a human. Ask before running this.") + : allow(), +}); +``` + +`defaultEnabled` ha il valore predefinito **false** quando lo ometti. Un semplice `failproofai pack add` attiva solo quello che hai contrassegnato — installare ogni policy di uno sconosciuto senza controllo non è una decisione che l'installatore dovrebbe prendere per l'utente. + + +La voce deve essere **un file autonomo e autocontenuto**. Solo la voce è protetta dal digest, quindi un pack che importa file locali non potrebbe onestamente affermare che il digest copre ciò che viene eseguito. Raggruppa prima (`esbuild`, `bun build`, `rollup`) e costruisci il pack dal bundle — `pack build` rifiuta un'importazione locale piuttosto che distribuire una promessa che non può mantenere. + + +## 2. Costruisci gli asset della release + +```bash +failproofai pack build ./policies.mjs \ + --id acme/support-agent \ + --version 1.0.0 \ + --out ./dist-pack +``` + +Scrive tre file e convalida ogni policy con **le regole proprie del loader** prima — quindi un pack che non potrebbe mai essere installato fallisce qui, dove puoi correggerlo: + +| File | Cosa è | +| --- | --- | +| `failproofai-pack.json` | Il manifest: id, version, effect, e una voce per policy | +| `failproofai-pack.mjs` | La tua voce, esattamente come è | +| `SHA256SUMS` | ` ` per gli altri due | + +Rifiutato al momento della costruzione: un id che non è `publisher/name`, un nome di policy contenente `/`, una policy che dichiara `alwaysOn`, una `description`, `category` o `match` mancante, una voce che non registra nulla, e una voce che importa file locali. + +## 3. Allegali a una release + +Etichetta la release con la stessa versione che hai costruito, e allega tutti e tre i file come asset di release: + +```bash +gh release create 1.0.0 \ + ./dist-pack/failproofai-pack.json \ + ./dist-pack/failproofai-pack.mjs \ + ./dist-pack/SHA256SUMS +``` + +Ora chiunque può installarlo: + +```bash +failproofai pack add acme/support-agent +``` + +I nomi degli asset sono fissi — sono quelli da cui il CLI del consumer costruisce i suoi URL, senza chiamate API e senza discovery. + +## Distribuire una nuova versione + +Costruisci con il nuovo `--version`, etichetta una nuova release, allega di nuovo i tre asset. I consumer eseguono lo stesso `pack add` e mantengono qualsiasi sottoinsieme avevano scelto; una policy che avevano disattivato rimane disattivata durante l'aggiornamento. + +Cambiare il **name** di una policy è un breaking change: una macchina che l'aveva disattivata sta disattivando un nome che non esiste più, e il nuovo nome arriva con qualsiasi `defaultEnabled` dica. + +## Su cosa i tuoi utenti si stanno fidando + +`SHA256SUMS` si trova nella stessa release dell'artefatto, quindi dimostra che i byte sono quelli che hai pubblicato — non chi sei. Chiunque possa scrivere nel repository può scrivere entrambi i file. La protezione dei tuoi utenti è che il digest è bloccato quando installano, quindi quello che hai distribuito non può cambiare sotto di loro successivamente. + +Pubblica da un repository il cui accesso in scrittura controlli, e tratta una release pack come se stessi pubblicando un pacchetto. + +## Osserva prima di forzare + +Un manifest può dichiarare `"effect": "observe"`. Quelle policy vengono eseguite e i loro verdetti sono **registrati e scartati** — nulla viene bloccato. È il modo per misurare una nuova regola contro il traffico reale prima che possa interrompere il lavoro di chiunque. + +```json +{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +``` \ No newline at end of file diff --git a/docs/it/reference/failproof-cli.mdx b/docs/it/reference/failproof-cli.mdx index d390cdca..657ccb9f 100644 --- a/docs/it/reference/failproof-cli.mdx +++ b/docs/it/reference/failproof-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof AI CLI" -description: "Installa hook, gestisci politiche locali, connetti Cloud e gestisci il daemon locale." +description: "Installa gli hook, gestisci le politiche locali, connetti il Cloud e gestisci il daemon locale." icon: "terminal" --- Installa la CLI locale con `npm install -g failproofai`. Eseguila senza argomenti per aprire il dashboard delle politiche locali. -Il pacchetto richiede Node.js 20.9 o versione successiva. Bun 1.3 o versione successiva è supportato per sviluppo e installazioni da sorgente. `failproofai configure` e `failproofai setup` sono alias per `failproofai config`; `failproofai p` è un alias per `failproofai policies`. +Il pacchetto richiede Node.js 20.9 o più recente. Bun 1.3 o più recente è supportato per sviluppo e installazioni da sorgente. `failproofai configure` e `failproofai setup` sono alias per `failproofai config`; `failproofai p` è un alias per `failproofai policies`. ## Configura una macchina @@ -26,23 +26,28 @@ Esegui `failproofai` senza argomenti per aprire il dashboard delle politiche loc | --- | --- | | `failproofai config` | Esegui la configurazione interattiva della macchina | | `failproofai config --connect --token ` | Connetti l'acquisizione Cloud e la distribuzione delle politiche | -| `failproofai config --status` | Mostra lo stato della connessione, del daemon, della consegna e della pausa | -| `failproofai policies` | Elenca le politiche predefinite e personalizzate | +| `failproofai config --status` | Mostra lo stato della connessione, daemon, distribuzione e pausa | +| `failproofai policies` | Elenca le politiche integrate, personalizzate, convenzionali, pack e gestite da Cloud | | `failproofai policies --install` | Installa gli hook e abilita le politiche | -| `failproofai policy add ` | Abilita una politica predefinita | -| `failproofai policy remove ` | Disabilita una politica predefinita | -| `failproofai policies --uninstall` | Disabilita le politiche o rimuovi gli hook di harness | -| `failproofai audit` | Scansiona la cronologia locale dell'agente e apri la vista di audit locale | -| `failproofai audit --schedule [days] --email
` | Pianifica scansioni locali ricorrenti e invia i loro risultati via email | -| `failproofai audit --status` | Mostra l'indirizzo del rapporto, l'intervallo e la prossima scansione pianificata | -| `failproofai audit --no-schedule` | Interrompi le scansioni ricorrenti senza eliminare la cronologia di audit | +| `failproofai policy add ` | Abilita una politica — una integrata, o `:` da un pack installato | +| `failproofai policy remove ` | Disabilita una politica, stessa nomenclatura | +| `failproofai policies --uninstall` | Disabilita le politiche o rimuovi gli hook | +| `failproofai pack list` | Elenca i pack di politiche installati e tutte le politiche che contengono | +| `failproofai pack add ` | Installa un pack di politiche da un rilascio GitHub; nessun tag prende il più recente e lo fissa | +| `failproofai pack add --bundled` | Installa le politiche integrate come pack, da questo pacchetto, senza rete | +| `failproofai pack build ` | Compila i tre asset di rilascio per un tuo pack personalizzato | +| `failproofai pack remove ` | Disattiva un pack installato | +| `failproofai audit` | Scansiona la cronologia locale dell'agente e apri la vista di controllo locale | +| `failproofai audit --schedule [days] --email
` | Pianifica scansioni ricorrenti locali e invia i risultati per email | +| `failproofai audit --status` | Mostra l'indirizzo del report, l'intervallo e la prossima scansione pianificata | +| `failproofai audit --no-schedule` | Interrompi le scansioni ricorrenti senza eliminare la cronologia di controllo | | `failproofai harness list` | Elenca i percorsi di acquisizione aggiuntivi | -| `failproofai flush --wait` | Consegna il spool di eventi corrente | +| `failproofai flush --wait` | Distribuisci lo spool di eventi corrente | | `failproofai backfill --since 30d` | Rileggi la cronologia precedentemente passata | -| `failproofai config --pause [duration]` | Metti in pausa una sessione locale per 30 minuti per impostazione predefinita, fino a 8 ore | +| `failproofai config --pause [duration]` | Pausa una sessione locale per 30 minuti per impostazione predefinita, fino a 8 ore | | `failproofai config --resume` | Riprendi una sessione locale in pausa; aggiungi `--all` per cancellare tutte le pause | -| `failproofai update` | Completa le migrazioni dei pacchetti e aggiorna il daemon | -| `failproofai migrate --dry-run` | Anteprima o esegui le migrazioni del layout home in sospeso | +| `failproofai update` | Completa le migrazioni del pacchetto e aggiorna il daemon | +| `failproofai migrate --dry-run` | Anteprima o esegui le migrazioni di layout in sospeso | | `failproofai uninstall` | Rimuovi gli hook e il daemon prima di rimuovere il pacchetto | | `failproofai --version` | Stampa la versione del pacchetto installato | | `failproofai --help` | Mostra i comandi e l'utilizzo globale | @@ -51,31 +56,31 @@ Esegui `failproofai` senza argomenti per aprire il dashboard delle politiche loc | Flag | Utilizzo | | --- | --- | -| `--connect --token ` | Connettiti non in modo interattivo | -| `--machine-id ` | Imposta l'ID stabile della macchina | -| `--machine-label ` | Imposta o modifica l'etichetta del dashboard | -| `--no-transcripts` | Invia le decisioni senza il contenuto della trascrizione | -| `--disconnect` | Interrompi i pull delle politiche Cloud e la consegna degli eventi | +| `--connect --token ` | Connetti in modo non interattivo | +| `--machine-id ` | Imposta l'ID macchina stabile | +| `--machine-label ` | Imposta o cambia l'etichetta del dashboard | +| `--no-transcripts` | Invia le decisioni senza contenuto della trascrizione | +| `--disconnect` | Interrompi i pull delle politiche Cloud e la distribuzione degli eventi | | `--status` | Mostra lo stato attuale della macchina | -| `--pause [duration]` | Metti in pausa la sessione più recente nella directory corrente; accetta secondi, minuti o ore e per impostazione predefinita è 30 minuti | +| `--pause [duration]` | Pausa la sessione più recente nella directory corrente; accetta secondi, minuti o ore e il valore predefinito è 30 minuti | | `--resume` | Termina una pausa corrispondente in anticipo | -| `--session ` | Scegli una sessione esplicita per pausa o ripresa | -| `--all` | Con `--resume`, termina tutte le pause attive | +| `--session ` | Specifica una sessione esplicita per pausa o ripresa | +| `--all` | Con `--resume`, termina ogni pausa attiva | -Le pause locali sospendono le politiche predefinite, personalizzate e convenzionali per una sessione. Scadono sempre e non disabilitano le politiche gestite da Cloud. `block-self-pause` impedisce a un agente instrumentato di utilizzare questa scappatoia. +Le pause locali sospendono le politiche integrate, personalizzate, convenzionali e pack per una sessione. Scadono sempre e non disabilitano le politiche gestite da Cloud. `block-failproofai-commands` — sempre attivo e non può essere disabilitato o messo in pausa — impedisce a un agente strumentato di utilizzare questa scappatoia. ## Flag delle politiche | Flag | Utilizzo | | --- | --- | -| `--install`, `-i` | Abilita le politiche e installa gli hook di harness | +| `--install`, `-i` | Abilita le politiche e installa gli hook | | `--uninstall`, `-u` | Disabilita le politiche o rimuovi gli hook | -| `--cli ` | Scegli uno o più harness supportati | -| `--scope user\|project\|local\|all` | Scegli l'ambito della configurazione; `all` è per uninstall | +| `--cli ` | Specifica uno o più harness supportati | +| `--scope user\|project\|local\|all` | Scegli l'ambito della configurazione; `all` è per disinstallare | | `--beta` | Includi le politiche beta | -| `--custom`, `-c ` | Convalida e carica un file di politica personalizzato; ripetibile | +| `--custom`, `-c ` | Valida e carica un file di politica personalizzato; ripetibile | -## Flag di consegna e manutenzione +## Flag di distribuzione e manutenzione | Comando | Flag | | --- | --- | @@ -85,9 +90,9 @@ Le pause locali sospendono le politiche predefinite, personalizzate e convenzion | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` deve essere eseguito dopo `npm install -g failproofai@latest`; esegue le migrazioni del layout home, installa il binario daemon corrispondente e riavvia il servizio. `--no-daemon` esegue solo la migrazione del layout. +`failproofai update` dovrebbe essere eseguito dopo `npm install -g failproofai@latest`; esegue migrazioni del layout iniziale, installa il binario daemon corrispondente e riavvia il servizio. `--no-daemon` esegue solo la migrazione del layout. -## Percorsi di harness +## Percorsi harness ```text failproofai harness list [harness] @@ -95,9 +100,9 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -I nomi di harness supportati sono `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` e `goose`. +I nomi harness supportati sono `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` e `goose`. -Le etichette namespaziano gli ID dell'agente derivato quando due radici contengono copie dello stesso progetto. Le radici sovrapposte e le etichette duplicate vengono rifiutate per prevenire la raccolta duplicata o la corruzione del cursore. La configurazione del percorso aggiuntivo si ricarica senza un riavvio del daemon. +Le etichette assegnano uno spazio ai nomi degli ID agente derivati quando due root contengono copie dello stesso progetto. Root sovrapposti ed etichette duplicate vengono rifiutati per evitare la raccolta duplicata o il danneggiamento del cursore. La configurazione del percorso aggiuntivo si ricarica senza un riavvio del daemon. Gli ambienti container possono sostituire i percorsi aggiuntivi configurati da file con una variabile separata da virgole denominata `FAILPROOFAI__EXTRA_PATHS`, ad esempio: @@ -107,26 +112,28 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## Variabili di ambiente -Utilizza i file di configurazione per il comportamento persistente della macchina. Le variabili di ambiente sono più utili per container, test e un singolo processo. +Utilizza i file di configurazione per il comportamento persistente della macchina. Le variabili di ambiente sono molto utili per container, test e un singolo processo. | Variabile | Utilizzo | | --- | --- | -| `FAILPROOFAI_HOME` | Sposta il layout completo `~/.failproofai` | +| `FAILPROOFAI_HOME` | Riporta il layout completo `~/.failproofai` | | `FAILPROOFAI_LOG_LEVEL` | Imposta la verbosità della registrazione locale | -| `FAILPROOFAI_HOOK_LOG_FILE` | Scrivi la diagnostica dell'hook in un file selezionato | +| `FAILPROOFAI_HOOK_LOG_FILE` | Scrivi la diagnostica degli hook in un file selezionato | | `FAILPROOFAI_TELEMETRY_DISABLED=1` | Disabilita la telemetria anonima per questo processo | -| `FAILPROOFAI_NO_FIRST_RUN=1` | Salta la configurazione interattiva della prima esecuzione | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Salta l'audit locale post-configurazione | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignora la configurazione interattiva al primo avvio | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Ignora il controllo locale post-configurazione | | `FAILPROOFAI_LLM_BASE_URL` | Sovrascrivi l'endpoint compatibile con OpenAI utilizzato dalle politiche LLM | | `FAILPROOFAI_LLM_API_KEY` | Fornisci la chiave API utilizzata dalle politiche LLM | | `FAILPROOFAI_LLM_MODEL` | Seleziona il modello utilizzato dalle politiche LLM | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limita il caricamento del modulo di politica personalizzato | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Vincola il caricamento del modulo di politica personalizzato | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Rifiuta di scaricare pack e binari daemon; ciò che è installato continua a forzare | +| `FAILPROOFAI_PACK_BASE_URL` | Scarica i pack da uno specchio invece di `github.com` | | `FAILPROOFAI__EXTRA_PATHS` | Sostituisci i percorsi di acquisizione aggiuntivi configurati per un harness | | `NO_COLOR` | Disabilita l'output del terminale colorato | -Le variabili home specifiche dell'agente come `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` e `OPENCLAW_HOME` scavalcano dove Failproof AI scopre le sessioni locali per quell'harness. +Variabili home specifiche dell'agente come `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` e `OPENCLAW_HOME` sostituiscono dove Failproof AI scopre le sessioni locali per quel harness. -## Metti in pausa o rimuovi una macchina in sicurezza +## Pausa o rimuovi una macchina in sicurezza ```bash failproofai config --pause @@ -134,7 +141,7 @@ failproofai config --status failproofai config --resume ``` -Una pausa di sessione locale non disabilita le politiche gestite da Cloud. Ripristina le distribuzioni Cloud attraverso il flusso di lavoro di applicazione Cloud quando il rollout stesso è il problema. +Una pausa della sessione locale non disabilita le politiche gestite da Cloud. Ripristina le distribuzioni Cloud tramite il flusso di lavoro di forzamento Cloud quando il problema è il rollout stesso. Prima di rimuovere il pacchetto npm, rimuovi gli hook installati e il daemon: diff --git a/docs/it/start/quickstart.mdx b/docs/it/start/quickstart.mdx index 482f7805..6ce0bef9 100644 --- a/docs/it/start/quickstart.mdx +++ b/docs/it/start/quickstart.mdx @@ -1,36 +1,36 @@ --- title: "Avvio rapido" -description: "Cattura una sessione di agente, trova un errore e inizia a prevenirlo." +description: "Acquisisci una sessione di agent, trova un errore e inizia a prevenirlo." icon: "zap" --- -Questo avvio rapido mette una macchina a inviare sessioni, esegue un audit e distribuisce una policy. Usa la skill per configurare Failproof, oppure segui i passaggi manuali. +Questo avvio rapido configura una macchina per segnalare sessioni, esegue un audit e distribuisce una policy. Usa la skill per configurare Failproof, oppure segui i passaggi manuali. -**Quale percorso è il tuo?** Se il tuo agente funziona in uno dei 12 [harness](/it/reference/harnesses) supportati — una CLI di programmazione o un gateway come Hermes o OpenClaw — segui i passaggi qui sotto; hai bisogno di Node.js 20.9 o successivo. Se il tuo agente non ha un harness, strumentalo con l'[SDK Python](/it/reference/custom-agents) per il tracing e gli audit, quindi riprendi da [Esegui il tuo primo controllo di errore](/it/start/first-audit); l'enforcement su quel percorso richiede un hook nel tuo runtime. +**Qual è il tuo percorso?** Se il tuo agent viene eseguito in uno dei 12 [harness](/it/reference/harnesses) supportati — una CLI di coding o un gateway come Hermes oppure OpenClaw — segui i passaggi qui sotto; hai bisogno di Node.js 20.9 o successivo. Se il tuo agent non ha un harness, strumentalo con l'[SDK Python](/it/reference/custom-agents) per il tracing e gli audit, quindi prosegui verso [Esegui il tuo primo controllo di errore](/it/start/first-audit); l'enforcement su quel percorso richiede un hook nel tuo runtime. - + ```bash npx skills add FailproofAI/skills ``` - + ```text Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Il tuo agente ispeziona il progetto, sceglie l'integrazione rilevante, esegue la configurazione e la verifica. Consulta il [repository delle skill di FailproofAI](https://github.com/FailproofAI/skills) per le skill individuali e le opzioni di installazione avanzate. + Il tuo agent ispeziona il progetto, sceglie l'integrazione rilevante, esegue la configurazione e la verifica. Consulta il [repository delle skill di FailproofAI](https://github.com/FailproofAI/skills) per le singole skill e le opzioni di installazione avanzate. ## Prima di iniziare -1. Apri la [dashboard Failproof AI](https://app.befailproof.ai) e crea un account oppure accedi con la tua email di lavoro. -2. Vai su **Administration → Keys** e crea una chiave con `events:add` e `policies:pull`. -3. Copia il segreto monouso e conservalo sulla macchina di destinazione: +1. Apri il [dashboard di Failproof AI](https://app.befailproof.ai) e crea un account o accedi con la tua email aziendale. +2. Vai a **Administration → Keys** e crea una chiave con `events:add` e `policies:pull`. +3. Copia il segreto monouso e salvalo sulla macchina di destinazione: ```bash export FAILPROOFAI_KEY="" @@ -45,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - I transcript di sessione vengono inviati per impostazione predefinita. Aggiungi `--no-transcripts` per segnalare l'attività degli hook e le decisioni delle policy senza il contenuto dei transcript. + I transcript delle sessioni vengono inviati per impostazione predefinita. Aggiungi `--no-transcripts` per segnalare l'attività dei hook e le decisioni delle policy senza il contenuto del transcript. - Se questa macchina ha già una cronologia di agenti, visualizza un'anteprima e importa gli ultimi sette giorni, quindi attendi il completamento della consegna. Salta questo passaggio su una nuova macchina. + Se questa macchina ha già una cronologia di agent, visualizza in anteprima e importa gli ultimi sette giorni, quindi attendi il completamento della consegna. Salta questo passaggio su una nuova macchina. ```bash failproofai backfill --since 7d --dry-run @@ -57,28 +57,28 @@ export FAILPROOFAI_KEY="" Apri **Sessions** in Failproof AI e seleziona una sessione importata. - - Questo collega Failproof AI al tuo harness e installa le 40 policy integrate. Usale per vedere le decisioni delle policy locali e provare l'enforcement prima che Failproof AI auditi le tue sessioni e scriva policy per i tuoi agenti. + + Questo allega Failproof AI al tuo harness e installa le 39 policy integrate. Usale per vedere le decisioni delle policy locali e prova l'enforcement prima che Failproof AI auditi le tue sessioni e scriva policy per i tuoi agent. - Lascia che l'installer rilevi il tuo harness, oppure specifica uno esplicitamente. Ognuno dei 12 è un valore `--cli` valido — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + Lascia che il programma di installazione rilevi il tuo harness, oppure specifica esplicitamente uno. Ognuno dei 12 è un valore `--cli` valido — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash failproofai policies --install --cli claude --scope user # a coding CLI failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - Il blocco di una chiamata di tool prima dell'esecuzione è verificato su tutti e 12. I gate di fine turno sono verificati su 8 — vedi [capacità di enforcement](/it/reference/harnesses#enforcement-capability) per la matrice per-harness. + Il blocco di una chiamata di tool prima che venga eseguita è verificato su tutti i 12. I gate di fine turno sono verificati su 8 — vedi [enforcement capability](/it/reference/harnesses#enforcement-capability) per la matrice per harness. - Segui [Esegui il tuo primo controllo di errore](/it/start/first-audit). Usa un obiettivo concreto come "trova sessioni in cui l'agente ha ritentato uno strumento non riuscito senza cambiare il suo approccio." + Segui [Esegui il tuo primo controllo di errore](/it/start/first-audit). Usa un obiettivo concreto come "trova le sessioni in cui l'agent ha ritentato uno strumento che non funzionava senza cambiare il suo approccio." - Segui [Previeni il tuo primo errore con una policy](/it/start/first-policy). Inizia in modalità osservazione, ispeziona i match, quindi applica la versione revisionata. + Segui [Previeni il tuo primo errore con una policy](/it/start/first-policy). Inizia in modalità observe, ispeziona le corrispondenze, quindi applica l'enforcement sulla versione revisionata. - Esegui `failproofai config --status`. Una configurazione corretta segnala la connessione al cloud, lo stato del daemon e se l'enforcement è in pausa. + Esegui `failproofai config --status`. Una configurazione integra segnala la connessione al cloud, lo stato del daemon e se l'enforcement è in pausa. \ No newline at end of file diff --git a/docs/ja/policies/builtin-catalog.mdx b/docs/ja/policies/builtin-catalog.mdx index 6c509219..8654bcc1 100644 --- a/docs/ja/policies/builtin-catalog.mdx +++ b/docs/ja/policies/builtin-catalog.mdx @@ -1,71 +1,71 @@ --- title: "組み込みポリシーカタログ" -description: "Failproof AI の全組み込みポリシー、そのトリガー、推奨状態、設定可能なパラメーターを確認してください。" +description: "Failproof AI の組み込みポリシーごとに、トリガー・推奨状態・設定可能なパラメーターを確認できます。" icon: "list-checks" --- -インストールされたパッケージがポリシーの利用可否に関する唯一の正確な情報源です。カタログのエントリや動作はパッケージバージョンによって変わる場合があるため、アップグレードのたびに `failproofai policies` を実行してください。 +インストール済みパッケージがポリシーの可用性に関する信頼できる情報源です。カタログのエントリや動作はパッケージバージョンとともに変わる可能性があるため、アップグレード後は毎回 `failproofai policies` を実行してください。 ## 推奨ベースライン -ガイド付きセットアップの推奨選択では、現在シークレットのサニタイズ、環境の保護、自己保護、壊滅的コマンドのガード、保護ブランチの安全性が有効になっています。 +ガイド付きセットアップの推奨選択では、現在以下が有効化されます: シークレットのサニタイザー、環境保護、自己保護、破壊的コマンドのガード、保護されたブランチの安全機能。 ```text sanitize-jwt sanitize-api-keys sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars block-env-files block-secrets-write -block-self-pause block-failproofai-commands -block-sudo block-curl-pipe-sh -block-rm-rf block-push-master -block-force-push +block-failproofai-commands block-sudo +block-curl-pipe-sh block-rm-rf +block-push-master block-force-push ``` -推奨設定は意図的に **Everything**（すべて）より範囲を絞っています。インフラストラクチャおよびワークフローのポリシーは正当な作業を中断させる可能性があるため、必要なリポジトリやマシンに限定して有効にしてください。 +`block-failproofai-commands` は**常に有効**です。上記には網羅性のために記載していますが、有効セットに含まれるかどうかにかかわらず、すべての評価時に登録されます。無効化や一時停止はできません。エージェントが無効化できるガードは、エージェントに対するガードとして機能しないからです。 + +推奨設定は意図的に **Everything** より狭く設定されています。インフラストラクチャやワークフローのポリシーは正当な作業を妨げる可能性があるため、それらが必要なリポジトリやマシンに限定して有効化してください。 ## シークレットと環境 | ポリシー | トリガー | 結果 | | --- | --- | --- | -| `sanitize-jwt` | `PostToolUse` | モデルに渡る前にツール出力から JWT を編集（マスク）します。 | -| `sanitize-api-keys` | `PostToolUse` | OpenAI、Anthropic、GitHub、AWS、Stripe、Google の一般的なキーを編集します。 | -| `sanitize-connection-strings` | `PostToolUse` | 認証情報を含むデータベース接続文字列を編集します。 | -| `sanitize-private-key-content` | `PostToolUse` | PEM 形式の秘密鍵本文を編集します。 | -| `sanitize-bearer-tokens` | `PostToolUse` | 認可 Bearer トークンを編集します。 | -| `protect-env-vars` | シェルツールへの `PreToolUse` | 環境変数をダンプするコマンドをブロックします。 | -| `block-env-files` | `PreToolUse` | `.env` ファイルの読み取りおよび書き込みをブロックします。 | -| `block-read-outside-cwd` | 読み取り・glob・grep・シェルツールへの `PreToolUse` | セッションの作業ディレクトリ外への読み取りを防止します。 | -| `block-secrets-write` | 書き込みツールへの `PreToolUse` | 一般的なシークレットキーや認証情報のファイル名への書き込みをブロックします。 | +| `sanitize-jwt` | `PostToolUse` | モデルが参照する前にツール出力から JWT を削除します。 | +| `sanitize-api-keys` | `PostToolUse` | OpenAI、Anthropic、GitHub、AWS、Stripe、Google の一般的なキーを削除します。 | +| `sanitize-connection-strings` | `PostToolUse` | 認証情報を含むデータベース接続文字列を削除します。 | +| `sanitize-private-key-content` | `PostToolUse` | PEM 形式の秘密鍵の本文を削除します。 | +| `sanitize-bearer-tokens` | `PostToolUse` | Authorization の Bearer トークンを削除します。 | +| `protect-env-vars` | シェルツールに対する `PreToolUse` | 環境変数をダンプするコマンドをブロックします。 | +| `block-env-files` | `PreToolUse` | `.env` ファイルの読み書きをブロックします。 | +| `block-read-outside-cwd` | 読み取り・glob・grep・シェルツールに対する `PreToolUse` | 読み取りをセッションの作業ディレクトリ内に制限します。 | +| `block-secrets-write` | 書き込みツールに対する `PreToolUse` | 一般的なシークレットキーおよび認証情報のファイル名への書き込みをブロックします。 | ## 危険なコマンドとインフラストラクチャ | ポリシー | トリガー | 結果 | | --- | --- | --- | -| `block-self-pause` | `PreToolUse`、`PermissionRequest` | エージェントが自身の強制適用を一時停止するのを防止します。 | -| `block-sudo` | `PreToolUse`、`PermissionRequest` | 許可パターンに一致しない限り `sudo` をブロックします。 | -| `block-curl-pipe-sh` | `PreToolUse` | シェルに直接パイプされるダウンロードスクリプトをブロックします。 | -| `block-rm-rf` | `PreToolUse` | 壊滅的な再帰削除パターンをブロックします。 | -| `block-failproofai-commands` | `PreToolUse` | エージェントが Failproof AI を変更またはアンインストールするのを防止します。 | -| `block-kubectl` | `PreToolUse` | Kubernetes コマンドをゲートします。 | -| `block-terraform` | `PreToolUse` | Terraform および OpenTofu コマンドをゲートします。 | -| `block-aws-cli` | `PreToolUse` | AWS CLI コマンドをゲートします。 | -| `block-gcloud` | `PreToolUse` | Google Cloud CLI コマンドをゲートします。 | -| `block-az-cli` | `PreToolUse` | Azure CLI コマンドをゲートします。 | -| `block-helm` | `PreToolUse` | Helm コマンドをゲートします。 | -| `block-gh-pipeline` | `PreToolUse` | GitHub CLI のワークフロー、実行、マージ、リリース、キャッシュ、シークレット操作など、変更を伴う操作をゲートします。 | - -## Git とデータベースの安全性 +| `block-sudo` | `PreToolUse`、`PermissionRequest` | allow パターンに一致しない限り `sudo` をブロックします。 | +| `block-curl-pipe-sh` | `PreToolUse` | ダウンロードしたスクリプトをシェルに直接パイプする操作をブロックします。 | +| `block-rm-rf` | `PreToolUse` | 破壊的な再帰削除パターンをブロックします。 | +| `block-failproofai-commands` | `PreToolUse`、`PermissionRequest` | **常に有効、無効化不可。** Failproof AI CLI のすべての呼び出し、自己一時停止、パッケージマネージャーによるアンインストールをブロックします。 | +| `block-kubectl` | `PreToolUse` | Kubernetes コマンドを制御します。 | +| `block-terraform` | `PreToolUse` | Terraform および OpenTofu コマンドを制御します。 | +| `block-aws-cli` | `PreToolUse` | AWS CLI コマンドを制御します。 | +| `block-gcloud` | `PreToolUse` | Google Cloud CLI コマンドを制御します。 | +| `block-az-cli` | `PreToolUse` | Azure CLI コマンドを制御します。 | +| `block-helm` | `PreToolUse` | Helm コマンドを制御します。 | +| `block-gh-pipeline` | `PreToolUse` | GitHub CLI のワークフロー・実行・マージ・リリース・キャッシュ・シークレット操作における変更系コマンドを制御します。 | + +## Git とデータベースの安全機能 | ポリシー | トリガー | 結果 | | --- | --- | --- | -| `block-push-master` | `PreToolUse` | 設定された保護ブランチへの直接プッシュをブロックします。 | +| `block-push-master` | `PreToolUse` | 設定した保護ブランチへの直接プッシュをブロックします。 | | `block-force-push` | `PreToolUse` | 強制プッシュをブロックします。現在の実装では `--force-with-lease` は引き続き許可されます。 | | `block-work-on-main` | `PreToolUse` | 保護ブランチへのコミットおよびマージをブロックします。 | | `warn-git-amend` | `PreToolUse` | `--amend` でコミットを書き換える前に警告します。 | -| `warn-git-stash-drop` | `PreToolUse` | スタッシュを永続的に破棄またはクリアする前に警告します。 | -| `warn-all-files-staged` | `PreToolUse` | `git add -A`、`git add .`、`git add --all` など広範なステージングに対して警告します。 | -| `warn-destructive-sql` | `PreToolUse` | 認識されたデータベースクライアントを通じた `WHERE` 句なしの `DROP`、`TRUNCATE`、`DELETE` に対して警告します。 | -| `warn-schema-alteration` | `PreToolUse` | 認識された `ALTER TABLE` のカラム操作やリネーム操作に対して警告します。 | +| `warn-git-stash-drop` | `PreToolUse` | スタッシュを永続的にドロップまたはクリアする前に警告します。 | +| `warn-all-files-staged` | `PreToolUse` | `git add -A`、`git add .`、`git add --all` のような広範なステージング操作に対して警告します。 | +| `warn-destructive-sql` | `PreToolUse` | 認識されているデータベースクライアントを通じて `WHERE` 句なしで `DROP`、`TRUNCATE`、`DELETE` を実行する前に警告します。 | +| `warn-schema-alteration` | `PreToolUse` | 認識されている `ALTER TABLE` のカラム操作やリネーム操作に対して警告します。 | ## パッケージ、システム動作、エージェントループ @@ -73,30 +73,30 @@ block-force-push | --- | --- | --- | | `warn-package-publish` | `PreToolUse` | パッケージレジストリへの公開前に警告します。 | | `warn-global-package-install` | `PreToolUse` | グローバルパッケージのインストール前に警告します。 | -| `prefer-package-manager` | `PreToolUse` | 許可されたパッケージマネージャーを使用するようエージェントに指示します。 | -| `warn-large-file-write` | 書き込みツールへの `PreToolUse` | 設定されたファイルサイズのしきい値を超えた場合に警告します。 | +| `prefer-package-manager` | `PreToolUse` | 許可されたパッケージマネージャーを使用するよう、エージェントに指示します。 | +| `warn-large-file-write` | 書き込みツールに対する `PreToolUse` | 設定したファイルサイズのしきい値を超えた場合に警告します。 | | `warn-background-process` | `PreToolUse` | デタッチされた、または長時間稼働するバックグラウンドプロセスのパターンに対して警告します。 | -| `warn-repeated-tool-calls` | `PreToolUse` | 同一のツール呼び出しが3回以上発生した後に警告します。 | +| `warn-repeated-tool-calls` | `PreToolUse` | 同一のツール呼び出しが 3 回以上繰り返された場合に警告します。 | ## タスク終了時のワークフロー -これらのポリシーは、互換性のある `Stop` イベントを発行するハーネスが必要です。 +これらのポリシーには、互換性のある `Stop` イベントを発行するハーネスが必要です。 | ポリシー | 結果 | | --- | --- | -| `require-commit-before-stop` | トラッキングされた作業がコミットされていない間は完了を拒否します。 | -| `require-push-before-stop` | コミットがローカルのみの状態では完了を拒否します。 | -| `require-pr-before-stop` | 現在のブランチのプルリクエストを要求します。 | -| `require-no-conflicts-before-stop` | 設定されたベースブランチとのクリーンなマージを要求します。 | -| `require-ci-green-before-stop` | 現在の HEAD の CI チェックが正常に完了することを要求します。 | +| `require-commit-before-stop` | トラッキング中の作業がコミットされていない間は完了を拒否します。 | +| `require-push-before-stop` | コミットがローカルにのみ存在する間は完了を拒否します。 | +| `require-pr-before-stop` | 現在のブランチに対してプルリクエストを要求します。 | +| `require-no-conflicts-before-stop` | 設定したベースブランチに対してクリーンなマージ状態を要求します。 | +| `require-ci-green-before-stop` | 現在の HEAD の CI チェックが正常完了することを要求します。 | ## パラメーターリファレンス -選択したスコープの `policyParams` オブジェクトの下にパラメーターを設定します。型は各ポリシーによって検証されます。 +選択したスコープの `policyParams` オブジェクト配下でパラメーターを設定します。型は各ポリシーによって検証されます。 | ポリシー | パラメーター | 型とデフォルト値 | | --- | --- | --- | -| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`、`[]`；エントリには `regex` と `label` を含む | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`、`[]`。エントリには `regex` と `label` が含まれます。 | | `block-read-outside-cwd` | `allowPaths` | `string[]`、`[]` | | `block-sudo` | `allowPatterns` | `string[]`、`[]` | | `block-rm-rf` | `allowPaths` | `string[]`、`[]` | @@ -106,7 +106,7 @@ block-force-push | `block-work-on-main` | `protectedBranches` | `string[]`、`["main", "master"]` | | `prefer-package-manager` | `allowed`、`blocked` | `string[]`、`[]` | | `warn-large-file-write` | `thresholdKb` | `number`、`1024` | -| `require-push-before-stop` | `remote`、`baseBranch` | `string`、`"origin"`；`string`、`"main"` | +| `require-push-before-stop` | `remote`、`baseBranch` | `string`、`"origin"`; `string`、`"main"` | | `require-pr-before-stop` | `baseBranch` | `string`、`"main"` | | `require-no-conflicts-before-stop` | `baseBranch` | `string`、`"main"` | @@ -125,5 +125,5 @@ block-force-push ``` - 許可パターンはエージェントが実行できる範囲を広げます。フリート全体に展開する前に、対象ハーネス上で正確なトークン化とコマンドの変形をテストしてください。 + allow パターンはエージェントが実行できる操作の範囲を広げます。フリートにデプロイする前に、対象のハーネス上で正確なトークン化とコマンドのバリエーションを必ずテストしてください。 \ No newline at end of file diff --git a/docs/ja/policies/failure-behavior.mdx b/docs/ja/policies/failure-behavior.mdx index 648b86c8..ffc2d16c 100644 --- a/docs/ja/policies/failure-behavior.mdx +++ b/docs/ja/policies/failure-behavior.mdx @@ -1,19 +1,19 @@ --- -title: "障害時の動作" -description: "ポリシー評価またはローカルデーモンが利用できない場合に何が起こるかを理解する。" +title: "失敗時の動作" +description: "ポリシー評価またはローカルデーモンが利用できない場合の動作を理解する。" icon: "shield-alert" --- -Failproof AI は、強制執行の失敗がサイレントにリスクのある作業を許可するのではなく、可視化されるよう設計されています。 +Failproof AI は、強制実行に失敗した場合、危険な操作を黙認するのではなく、問題を可視化するように設計されています。 ## 失敗クローズのブロックを診断する - 1. **Admin → enforcement** に移動してマシンを開く。 - 2. 最終チェックイン、割り当てられたデプロイメント、および報告されたデプロイメントを確認する。 - 3. **Observe → policy** に移動して、拒否された決定のセッションを開く。 - 4. 理由がデーモンの到達可能性、バージョンの不一致、またはポリシー自体のいずれを報告しているか確認する。 + 1. **Admin → enforcement** に移動してマシンを開きます。 + 2. 最後のチェックイン、割り当てられたデプロイメント、および報告されたデプロイメントを確認します。 + 3. **Observe → policy** に移動して、拒否された決定のセッションを開きます。 + 4. 理由がデーモンの到達可能性、バージョンの不一致、またはポリシー自体に関するものかどうかを確認します。 @@ -23,21 +23,45 @@ Failproof AI は、強制執行の失敗がサイレントにリスクのある failproofai config ``` - `failproofai config` を再実行すると、パッケージのアップグレード後にデーモンが更新・再起動されます。 + パッケージのアップグレード後に `failproofai config` を再実行すると、デーモンが更新・再起動されます。 -`failproofaid` を使用するよう設定されたマシンでは、デーモンが唯一の評価エンジンです。デーモンに到達できない場合、またはそのプロトコルバージョンが CLI と一致しない場合、フックの評価は失敗クローズになります。アクションは拒否され、オペレーターにデーモンの確認または更新を促す理由が表示されます。 +`failproofaid` を使用するよう設定されたマシンでは、デーモンが唯一の評価者です。デーモンに到達できない場合、またはプロトコルバージョンが CLI と一致しない場合、フック評価は失敗クローズになります。アクションは拒否され、その理由としてデーモンの確認または更新を促すメッセージが表示されます。 -デーモン設定の前は、フックはプロセス内でポリシーを評価します。デーモン設定が記録された後、Failproof AI はデーモンが失敗した際に2番目の評価エンジンへサイレントにフォールバックしません。 +デーモン設定を行う前は、フックはインプロセスでポリシーを評価します。デーモン設定が記録されると、Failproof AI はデーモンが失敗した際に第二の評価者へ黙ってフォールバックすることはありません。 ## 失敗クローズの決定に対応する -1. `failproofai config --status` を実行する。 -2. バージョンが異なる場合は、パッケージを更新した後に `failproofai config` を再実行する。 -3. デーモンに到達できない場合は、サービスの状態とローカルログを確認する。 -4. ポリシー評価のパスが正常であることを確認した後にのみ、エージェントの作業を再開する。 +1. `failproofai config --status` を実行します。 +2. バージョンが異なる場合は、パッケージを更新した後に `failproofai config` を再実行します。 +3. デーモンに到達できない場合は、サービスの状態とローカルログを確認します。 +4. ポリシー評価のパスが正常であることを確認してから、エージェントの作業を再開します。 - ブロックされたアクションを繰り返し再試行しないでください。失敗クローズの応答は、システムがそのアクションの安全性を確認できなかったことを意味します。 - \ No newline at end of file + ブロックされたアクションを繰り返し再試行しないでください。失敗クローズの応答は、システムがそのアクションの安全性を確立できなかったことを意味します。 + + +## パックが読み込まれない場合 + +パックを強制適用するよう指示されたマシンが、そのパックを実行できない場合、静かに処理を続行するのではなく拒否します。トリガーとなるのは**記録された期待値**であり、空の期待値ではありません。パックがインストールされていないマシンは無音ですが、宣言されたにもかかわらず解決できないパック、またはマニフェストで宣言された数よりも少ないポリシーしか登録されないパックは拒否します。 + +この拒否は、到達不能なデーモンとは異なり、**限定的**です。デーモンに到達できない場合、評価がまったく行われていないため、何も安全とみなすことができません。一方、読み込まれないパックには欠落したガードの列挙可能なセットがあります。宣言されたすべてのポリシーには独自の `match` が含まれているため、それらのポリシーが対象とするイベントとツールのみが拒否され、それ以外はすべて処理が続行されます。 + +以下の場合には発動しません： + +- `observe` パック（これは評価後に結果を破棄する設計です） +- 採用していないポリシー、または明示的にオフにしたポリシー +- ローダーが受け取らなかったパック（「登録なし」と意図的なスキップを区別できません） +- アクティブなセッションの一時停止 +- 読み込みタイムアウト（一時的な問題です。ディスクの一時的な遅延によって、人間が介入するまで拒否し続けるべきではありません） + +`UserPromptSubmit` は、欠落したポリシーが何を宣言していたかにかかわらず、拒否するのではなく **instruct** します。一括拒否はこれにも適用されてしまい、問題を修正できるエージェントからロックアウトされる可能性があります。 + +### 対処方法 + +```bash +failproofai pack list +``` + +このコマンドは、読み込まれないインストール済みパックの名前とその理由を表示し、ゼロ以外の終了コードで終了します。その後、パックを再インストールするか（`failproofai pack add `）、削除します（`failproofai pack remove `）。削除すると期待値が取り消され、拒否も同時に解除されます。 \ No newline at end of file diff --git a/docs/ja/policies/packs.mdx b/docs/ja/policies/packs.mdx new file mode 100644 index 00000000..228f559d --- /dev/null +++ b/docs/ja/policies/packs.mdx @@ -0,0 +1,110 @@ +--- +title: "ポリシーパック" +description: "GitHubリリースとして公開されたポリシーセットをインストールし、適用内容を管理します。" +icon: "package" +--- + +パックとは、GitHubリリースとして公開されたポリシーのセットです。コマンド1つでインストールでき、実行前にリリース自身のチェックサムが検証され、ダイジェストが記録されるため、インストール後にパックの内容が変わることはありません。 + +## Failproof AI のポリシーをインストールする + +```bash +failproofai pack add core +``` + +これにより、npmパッケージ内に同梱されたコピーから弊社公開のポリシーセットがインストールされます。ネットワーク不要で、プロキシ環境でも失敗しません。一部だけ取り込む場合は次のようにします。 + +```bash +failproofai pack add core --policy block-rm-rf # 1つ、またはカンマ区切りで複数 +failproofai pack add core --category dangerous-commands # カテゴリ全体 +failproofai pack add core --all # パック内のすべて +``` + +`failproofai pack list` で、パックが提供するすべてのカテゴリを確認できます。 + +## インストール前にパックの内容を確認する + +```bash +failproofai pack list acme/support-agent +``` + +パックに含まれるすべてのポリシーをカテゴリ別にグループ化して一覧表示します。作者がデフォルトで有効にしているものと、オプトインのものが区別されます。**マニフェストのみ**を読み込むため、エントリーアーティファクトはダウンロードもインポートもされません。つまり、見知らぬパックを参照しても、見知らぬコードが実行されることはありません。マニフェストはリリースの`SHA256SUMS`と照合されるため、表示されている内容がそのままインストールされます。 + +ソースを指定せずに`failproofai pack list`を実行すると、現在インストール済みのパックが一覧表示されます。 + +## 他のユーザーのパックをインストールする + +```bash +failproofai pack add acme/support-agent +``` + +以下の形式はいずれも使用できます。手元にあるものをそのまま貼り付けてください。 + +| ソース | 結果 | +| --- | --- | +| `acme/support-agent` | 最新リリース、解決された正確なタグに**固定** | +| `acme/support-agent@v2.1.0` | 指定のリリース | +| `github:acme/support-agent@v2.1.0` | 同上（明示的な記法） | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | 同上（ブラウザからコピーした URL） | + +タグを指定しない場合、最新リリースをインストールして**固定**し、選択されたタグを通知します。記録される内容は常に特定のリリース1つを指すため、再インストール時にバージョンがずれることはありません。 + +## パックの一部だけ取り込む + +デフォルトでは、パック内のすべてではなく、作者が無人実行しても安全とマークした**パック自身のデフォルト**ポリシーのみが適用されます。 + +```bash +failproofai pack add acme/support-agent --category billing,git +failproofai pack add acme/support-agent --policy block-refunds +failproofai pack add acme/support-agent --all +``` + +`--category`と`--policy`は和集合として組み合わせられます（`--only`は`--policy`の別名として使用できます）。新しいバージョンで再追加した場合、選択した内容は維持され、残りが有効化し直されることはありません。 + +## 有効なポリシーを管理する + +```bash +failproofai policies # パックを含むすべてのソースを一覧表示 +failproofai pack list # パックのみ、カテゴリ別にグループ化 +failproofai policies --uninstall block-refunds # パックのポリシーを1つ無効化 +failproofai policies --install block-refunds # 再び有効化 +failproofai pack remove acme/support-agent +``` + +名前だけを指定した場合、その名前の**組み込みポリシー**が存在すればそちらが対象になります。パックのコピーを明示的に指定する場合は次のようにします。 + +```bash +failproofai policies --uninstall acme/support-agent:block-refunds +``` + + +パックが提供するポリシーの名前が**有効な組み込みポリシー**と重複している場合、組み込みポリシーが実行され、パックのコピーはスキップされます。これは、同じガードが2回評価されるのを防ぐためです。パックのコピーを使用したい場合は、組み込みポリシーを無効にしてください。 + + +## Failproof AI のポリシーの提供元 + +`core`は、npmパッケージ内に同梱されたコピーを読み込みます。同じセットはGitHubリリースとしても公開されており、特定のバージョンが必要な場合はそちらからインストールできます。 + +```bash +failproofai pack add core # パッケージ内のコピーを使用、ネットワーク不要 +failproofai pack add FailproofAI/policies # 同じセット、GitHubリリースから取得 +``` + +## 整合性検証でできること・できないこと + +`SHA256SUMS`はアーティファクトと同じリリースに同梱されているため、**署名ではなく**、誰が公開したかを証明するものではありません。証明されるのは、バイト列がそのリリースで公開されたものと一致することです。パック追加時にダイジェストが記録され、インポートのたびに再検証されるため、インストール後にパックの内容が変わることはありません。リリースのタグを付け替えたりアセットを差し替えたりしたリポジトリは、別のコードを静かに実行する代わりに、読み込みに失敗します。 + +インストール時には、パックが**一度インポートされ**、自身のマニフェストと照合されます。アーティファクトのパースに失敗したり、宣言内容と異なるものを登録しようとするパックは、アクティベーションされる前に拒否されます。インストールは成功したが次のツール呼び出しで失敗する、といった事態にはなりません。 + +## パックが読み込まれない場合 + +このマシンで適用するよう設定されているが実行できないパックが存在する場合、対象ポリシーが適用するはずだったイベントは、サイレントに許可されるのではなく**拒否**されます。詳しくは[Failure behavior](/ja/policies/failure-behavior)を参照してください。`failproofai pack list`はその状態のパックを表示し、ゼロ以外の終了コードで終了します。 + +## オフライン環境とミラー + +| 変数 | 効果 | +| --- | --- | +| `FAILPROOFAI_NO_DOWNLOAD=1` | フェッチを拒否。インストール済みのパックは引き続き適用される | +| `FAILPROOFAI_PACK_BASE_URL` | パックの取得先を`github.com`の代わりにミラーへ向ける | + +独自パックの公開方法については、[Publish a pack](/ja/policies/publish-a-pack)を参照してください。 \ No newline at end of file diff --git a/docs/ja/policies/publish-a-pack.mdx b/docs/ja/policies/publish-a-pack.mdx new file mode 100644 index 00000000..98d921d1 --- /dev/null +++ b/docs/ja/policies/publish-a-pack.mdx @@ -0,0 +1,91 @@ +--- +title: "パックを公開する" +description: "独自のポリシーをGitHubリリースとして公開し、誰でもインストールできるようにする。" +icon: "upload" +--- + +パックはGitHubリリースに添付された3つのファイルで構成されます。`failproofai pack build` は、既存のポリシーファイルからこの3つをすべて生成します。 + +## 1. ポリシーを記述する + +カスタムポリシーと同じAPIを使用した1つのファイルです。パックに特有の追加フィールドが2つあります。 + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-refunds", + description: "Refunds above the approved limit need a human", + category: "Billing", // groups it, and is what --category selects on + defaultEnabled: true, // switched on by a plain `pack add` + match: { events: ["PreToolUse"], tools: ["Bash"] }, + fn: async (ctx) => + String(ctx.toolInput?.command ?? "").includes("refund") + ? deny("Refunds need a human. Ask before running this.") + : allow(), +}); +``` + +`defaultEnabled` を省略した場合、デフォルトは **false** になります。通常の `failproofai pack add` は、明示的にマークしたポリシーのみを有効化します。見知らぬ人のすべてのポリシーを無人でインストールするかどうかは、インストーラーがユーザーに代わって決定すべきことではありません。 + + +エントリは**完全に自己完結した1つのファイル**でなければなりません。ダイジェストが固定されるのはエントリのみであるため、ローカルファイルをインポートするパックは、ダイジェストが実際に実行される内容を保証していると誠実には言えません。まず（`esbuild`、`bun build`、`rollup` などで）バンドルし、バンドルからパックをビルドしてください。`pack build` はローカルインポートを検出した場合、履行できない約束を出荷するのではなく、処理を拒否します。 + + +## 2. リリースアセットをビルドする + +```bash +failproofai pack build ./policies.mjs \ + --id acme/support-agent \ + --version 1.0.0 \ + --out ./dist-pack +``` + +このコマンドは3つのファイルを生成し、まず**ローダー自身のルール**ですべてのポリシーを検証します。インストールできないパックは、修正できるこの段階で失敗します。 + +| ファイル | 内容 | +| --- | --- | +| `failproofai-pack.json` | マニフェスト: ID、バージョン、エフェクト、各ポリシーのエントリ | +| `failproofai-pack.mjs` | エントリファイル（そのまま） | +| `SHA256SUMS` | 他の2ファイルの ` <ファイル名>` | + +ビルド時に拒否される条件: `publisher/name` 形式でないID、`/` を含むポリシー名、`alwaysOn` を宣言するポリシー、`description`・`category`・`match` のいずれかが欠落している場合、何も登録しないエントリ、ローカルファイルをインポートするエントリ。 + +## 3. リリースに添付する + +ビルド時に指定したバージョンでリリースにタグを付け、3つのファイルすべてをリリースアセットとして添付します。 + +```bash +gh release create 1.0.0 \ + ./dist-pack/failproofai-pack.json \ + ./dist-pack/failproofai-pack.mjs \ + ./dist-pack/SHA256SUMS +``` + +これで誰でもインストールできるようになります。 + +```bash +failproofai pack add acme/support-agent +``` + +アセット名は固定されています。コンシューマーのCLIはAPIコールや自動検出なしに、このアセット名からURLを構築します。 + +## 新バージョンの公開 + +新しい `--version` でビルドし、新しいリリースにタグを付け、3つのアセットを再度添付します。コンシューマーは同じ `pack add` を実行すれば、以前選択していたポリシーのサブセットが維持されます。無効化していたポリシーは、アップグレード後も無効のままです。 + +ポリシーの **name** を変更することは破壊的変更です。そのポリシーを無効化していたマシンは、もはや存在しない名前を無効化しようとすることになり、新しい名前は `defaultEnabled` の設定に従って有効化されます。 + +## ユーザーが信頼するもの + +`SHA256SUMS` はアーティファクトと同じリリースに存在するため、バイト列があなたが公開したものであることを証明しますが、あなたが誰であるかは証明しません。リポジトリへの書き込み権限を持つ人は、両方のファイルを書き換えることができます。ユーザーを守るのは、インストール時にダイジェストが固定されるという点です。つまり、公開後に内容が変更されても、インストール済みのユーザーには影響しません。 + +書き込みアクセスを自分でコントロールできるリポジトリから公開し、パックのリリースをパッケージの公開と同様に扱ってください。 + +## 適用する前に観察する + +マニフェストに `"effect": "observe"` を宣言することができます。これらのポリシーは実行され、判定結果が**記録されますが破棄されます**。つまり、何もブロックされません。新しいルールを実際のトラフィックに対して測定し、誰かの作業を中断させる前に効果を確認するための方法です。 + +```json +{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +``` \ No newline at end of file diff --git a/docs/ja/reference/failproof-cli.mdx b/docs/ja/reference/failproof-cli.mdx index 582444d9..8f1227a2 100644 --- a/docs/ja/reference/failproof-cli.mdx +++ b/docs/ja/reference/failproof-cli.mdx @@ -4,9 +4,9 @@ description: "フックのインストール、ローカルポリシーの管理 icon: "terminal" --- -`npm install -g failproofai` でローカル CLI をインストールします。引数なしで実行すると、ローカルポリシーダッシュボードが開きます。 +`npm install -g failproofai` でローカル CLI をインストールします。引数なしで実行するとローカルポリシーダッシュボードが開きます。 -このパッケージには Node.js 20.9 以降が必要です。Bun 1.3 以降は開発およびソースインストールに対応しています。`failproofai configure` と `failproofai setup` は `failproofai config` のエイリアスです。`failproofai p` は `failproofai policies` のエイリアスです。 +このパッケージには Node.js 20.9 以降が必要です。Bun 1.3 以降は開発環境およびソースインストールでサポートされています。`failproofai configure` と `failproofai setup` は `failproofai config` のエイリアスです。`failproofai p` は `failproofai policies` のエイリアスです。 ## マシンのセットアップ @@ -22,60 +22,65 @@ failproofai config --status 引数なしで `failproofai` を実行すると、ローカルポリシーダッシュボードが開きます。 -| コマンド | 内容 | +| コマンド | 動作 | | --- | --- | -| `failproofai config` | マシンのインタラクティブセットアップを実行する | -| `failproofai config --connect --token ` | Cloud のイベント取り込みとポリシー配信を接続する | -| `failproofai config --status` | 接続状況、デーモン、配信、一時停止の状態を表示する | -| `failproofai policies` | 組み込みポリシーとカスタムポリシーを一覧表示する | -| `failproofai policies --install` | フックをインストールしてポリシーを有効にする | -| `failproofai policy add ` | 組み込みポリシーを1つ有効にする | -| `failproofai policy remove ` | 組み込みポリシーを1つ無効にする | -| `failproofai policies --uninstall` | ポリシーを無効にするか、ハーネスフックを削除する | -| `failproofai audit` | ローカルエージェントの履歴をスキャンし、ローカル監査ビューを開く | +| `failproofai config` | 対話式のマシンセットアップを実行する | +| `failproofai config --connect --token ` | Cloud へのイベント取り込みとポリシー配信を接続する | +| `failproofai config --status` | 接続状態、デーモン、配信、一時停止の状態を表示する | +| `failproofai policies` | 組み込み、カスタム、規約、パック、Cloud 管理ポリシーを一覧表示する | +| `failproofai policies --install` | フックをインストールしてポリシーを有効化する | +| `failproofai policy add ` | ポリシーを 1 件有効化する — 組み込みポリシー、またはインストール済みパックの `:` | +| `failproofai policy remove ` | ポリシーを 1 件無効化する（命名規則は同様） | +| `failproofai policies --uninstall` | ポリシーを無効化するか、ハーネスフックを削除する | +| `failproofai pack list` | インストール済みポリシーパックと各パックに含まれるポリシーを一覧表示する | +| `failproofai pack add ` | GitHub リリースからポリシーパックをインストールする。タグ未指定の場合は最新版を取得してピン留めする | +| `failproofai pack add --bundled` | このパッケージからネットワーク不要で組み込みポリシーをパックとしてインストールする | +| `failproofai pack build ` | 独自パックのリリースアセット 3 点をビルドする | +| `failproofai pack remove ` | インストール済みパックを無効化する | +| `failproofai audit` | ローカルエージェント履歴をスキャンしてローカル監査ビューを開く | | `failproofai audit --schedule [days] --email
` | 定期的なローカルスキャンをスケジュールし、結果をメール送信する | -| `failproofai audit --status` | レポートの送信先アドレス、間隔、次回スキャン予定を表示する | +| `failproofai audit --status` | レポート送信先アドレス、間隔、次回スキャン予定を表示する | | `failproofai audit --no-schedule` | 監査履歴を削除せずに定期スキャンを停止する | | `failproofai harness list` | 追加のキャプチャパスを一覧表示する | | `failproofai flush --wait` | 現在のイベントスプールを配信する | -| `failproofai backfill --since 30d` | 過去に通過した履歴を再読み込みする | -| `failproofai config --pause [duration]` | ローカルセッションを一時停止する（デフォルト30分、最大8時間） | -| `failproofai config --resume` | 一時停止中のローカルセッションを再開する。`--all` を付けると全ての一時停止を解除する | -| `failproofai update` | パッケージのマイグレーションを完了し、デーモンを更新する | +| `failproofai backfill --since 30d` | 過去に処理済みの履歴を再読み込みする | +| `failproofai config --pause [duration]` | ローカルセッションを一時停止する（デフォルト 30 分、最大 8 時間） | +| `failproofai config --resume` | 一時停止中のローカルセッションを再開する。`--all` を追加すると全ての一時停止を解除する | +| `failproofai update` | パッケージのマイグレーションを完了してデーモンを更新する | | `failproofai migrate --dry-run` | ホームレイアウトの保留中マイグレーションをプレビューまたは実行する | | `failproofai uninstall` | パッケージを削除する前にフックとデーモンを削除する | | `failproofai --version` | インストール済みパッケージのバージョンを表示する | -| `failproofai --help` | コマンドとグローバルな使い方を表示する | +| `failproofai --help` | コマンドと全体的な使用方法を表示する | ## 設定フラグ | フラグ | 用途 | | --- | --- | -| `--connect --token ` | 非インタラクティブモードで接続する | +| `--connect --token ` | 非対話式で接続する | | `--machine-id ` | 固定マシン ID を設定する | | `--machine-label ` | ダッシュボードのラベルを設定または変更する | -| `--no-transcripts` | トランスクリプトの内容を含めずに判断結果のみ送信する | -| `--disconnect` | Cloud からのポリシー取得とイベント配信を停止する | +| `--no-transcripts` | トランスクリプトの内容を含めずに判定結果を送信する | +| `--disconnect` | Cloud ポリシーの取得とイベント配信を停止する | | `--status` | 現在のマシン状態を表示する | -| `--pause [duration]` | カレントディレクトリの最新セッションを一時停止する。秒・分・時間を指定可能で、デフォルトは30分 | -| `--resume` | 一致する一時停止を早期に終了する | +| `--pause [duration]` | カレントディレクトリの最新セッションを一時停止する。秒・分・時間を指定可能。デフォルトは 30 分 | +| `--resume` | 一致する一時停止を早期終了する | | `--session ` | 一時停止または再開の対象セッションを明示的に指定する | -| `--all` | `--resume` と組み合わせて、全てのアクティブな一時停止を終了する | +| `--all` | `--resume` と組み合わせて、アクティブな全ての一時停止を終了する | -ローカルの一時停止は、1つのセッションについて組み込みポリシー・カスタムポリシー・規約ポリシーを停止します。常に有効期限があり、Cloud 管理ポリシーは無効化しません。`block-self-pause` は、計装済みエージェントがこのエスケープハッチを自ら使用することを防ぎます。 +ローカルの一時停止は、組み込み・カスタム・規約・パックポリシーを 1 セッション分停止します。常に有効期限があり、Cloud 管理ポリシーは無効化されません。`block-failproofai-commands` — 常時有効であり、それ自体を無効化または一時停止することはできません — は、計装済みエージェントがこのエスケープハッチを使用することを防ぎます。 ## ポリシーフラグ | フラグ | 用途 | | --- | --- | -| `--install`, `-i` | ポリシーを有効にし、ハーネスフックをインストールする | -| `--uninstall`, `-u` | ポリシーを無効にするか、フックを削除する | -| `--cli ` | 対象とするハーネスを1つ以上指定する | +| `--install`, `-i` | ポリシーを有効化してハーネスフックをインストールする | +| `--uninstall`, `-u` | ポリシーを無効化するかフックを削除する | +| `--cli ` | サポートされているハーネスを 1 つ以上対象にする | | `--scope user\|project\|local\|all` | 設定スコープを選択する。`all` はアンインストール用 | | `--beta` | ベータポリシーを含める | -| `--custom`, `-c ` | カスタムポリシーファイルを検証して読み込む（繰り返し指定可能） | +| `--custom`, `-c ` | カスタムポリシーファイルを検証して読み込む。繰り返し指定可能 | -## 配信・メンテナンスフラグ +## 配信およびメンテナンスフラグ | コマンド | フラグ | | --- | --- | @@ -85,7 +90,7 @@ failproofai config --status | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` は `npm install -g failproofai@latest` の後に実行してください。ホームレイアウトのマイグレーション、対応するデーモンバイナリのインストール、サービスの再起動を行います。`--no-daemon` を指定するとレイアウトマイグレーションのみが実行されます。 +`failproofai update` は `npm install -g failproofai@latest` の後に実行してください。ホームレイアウトのマイグレーション、対応するデーモンバイナリのインストール、サービスの再起動を行います。`--no-daemon` はレイアウトのマイグレーションのみを実行します。 ## ハーネスパス @@ -97,9 +102,9 @@ failproofai harness remove-path サポートされているハーネス名は `claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity`、`goose` です。 -ラベルは、2つのルートに同じプロジェクトのコピーが存在する場合に、派生エージェント ID を名前空間で区別します。重複するルートや重複するラベルは、二重収集やカーソルの破損を防ぐために拒否されます。追加パスの設定はデーモンを再起動せずにリロードされます。 +ラベルは、2 つのルートに同じプロジェクトのコピーが含まれる場合に、派生したエージェント ID の名前空間を分離します。重複するルートおよび重複するラベルは、収集の二重化やカーソルの破損を防ぐために拒否されます。追加パスの設定はデーモンを再起動せずにリロードされます。 -コンテナ環境では、ファイルで設定した追加パスをカンマ区切りの変数 `FAILPROOFAI__EXTRA_PATHS` で置き換えられます。例： +コンテナ環境では、ファイルで設定された追加パスをカンマ区切りの変数 `FAILPROOFAI__EXTRA_PATHS` で置き換えることができます。例: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -107,22 +112,24 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## 環境変数 -永続的なマシン動作には設定ファイルを使用してください。環境変数はコンテナ、テスト、単一プロセスに最も適しています。 +永続的なマシン設定には設定ファイルを使用してください。環境変数は、コンテナ・テスト・単一プロセスの場合に最も役立ちます。 | 変数 | 用途 | | --- | --- | -| `FAILPROOFAI_HOME` | `~/.failproofai` のレイアウト全体を移動する | -| `FAILPROOFAI_LOG_LEVEL` | ローカルのログ出力レベルを設定する | -| `FAILPROOFAI_HOOK_LOG_FILE` | フックの診断情報を指定ファイルに書き出す | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | このプロセスの匿名テレメトリを無効にする | -| `FAILPROOFAI_NO_FIRST_RUN=1` | インタラクティブな初回セットアップをスキップする | +| `FAILPROOFAI_HOME` | `~/.failproofai` のレイアウト全体を別の場所に移動する | +| `FAILPROOFAI_LOG_LEVEL` | ローカルログの詳細レベルを設定する | +| `FAILPROOFAI_HOOK_LOG_FILE` | フックの診断情報を指定ファイルに書き込む | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | このプロセスの匿名テレメトリを無効化する | +| `FAILPROOFAI_NO_FIRST_RUN=1` | 対話式の初回セットアップをスキップする | | `FAILPROOFAI_NO_AUTO_AUDIT=1` | セットアップ後のローカル監査をスキップする | | `FAILPROOFAI_LLM_BASE_URL` | LLM ポリシーが使用する OpenAI 互換エンドポイントを上書きする | -| `FAILPROOFAI_LLM_API_KEY` | LLM ポリシーが使用する API キーを設定する | +| `FAILPROOFAI_LLM_API_KEY` | LLM ポリシーが使用する API キーを指定する | | `FAILPROOFAI_LLM_MODEL` | LLM ポリシーが使用するモデルを選択する | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | カスタムポリシーモジュールの読み込みにタイムアウトを設定する | -| `FAILPROOFAI__EXTRA_PATHS` | 特定のハーネスの追加キャプチャパス設定を上書きする | -| `NO_COLOR` | ターミナルのカラー出力を無効にする | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | カスタムポリシーモジュールの読み込み時間を制限する | +| `FAILPROOFAI_NO_DOWNLOAD=1` | パックとデーモンバイナリの取得を拒否する。インストール済みのものは引き続き適用される | +| `FAILPROOFAI_PACK_BASE_URL` | `github.com` の代わりにミラーからパックを取得する | +| `FAILPROOFAI__EXTRA_PATHS` | 特定ハーネスの設定済み追加キャプチャパスを置き換える | +| `NO_COLOR` | ターミナルのカラー出力を無効化する | `CLAUDE_PROJECTS_PATH`、`CURSOR_HOME`、`HERMES_HOME`、`OPENCLAW_HOME` などのエージェント固有のホーム変数は、Failproof AI が各ハーネスのローカルセッションを検出する場所を上書きします。 @@ -134,9 +141,9 @@ failproofai config --status failproofai config --resume ``` -ローカルセッションの一時停止は、Cloud 管理ポリシーを無効化しません。ロールアウト自体が問題の場合は、Cloud の強制適用ワークフローを通じて Cloud デプロイメントを復元してください。 +ローカルセッションの一時停止は Cloud 管理ポリシーを無効化しません。ロールアウト自体が問題の場合は、Cloud 強制適用ワークフローを通じて Cloud デプロイを復元してください。 -npm パッケージを削除する前に、インストール済みのフックとデーモンを削除してください： +npm パッケージを削除する前に、インストール済みのフックとデーモンを削除してください: ```bash failproofai uninstall --dry-run @@ -144,8 +151,8 @@ failproofai uninstall --yes npm rm -g failproofai ``` -バージョン固有の詳細については `failproofai --help` を実行してください。 +バージョン固有の詳細は `failproofai --help` を実行して確認してください。 - `npm rm -g failproofai` の前に `failproofai uninstall` を実行してください。npm はインストール済みのエージェントフックやデーモンサービスを削除しません。 + `npm rm -g failproofai` を実行する前に `failproofai uninstall` を実行してください。npm はインストール済みのエージェントフックやデーモンサービスを削除しません。 \ No newline at end of file diff --git a/docs/ja/start/quickstart.mdx b/docs/ja/start/quickstart.mdx index 66e728db..a88ec044 100644 --- a/docs/ja/start/quickstart.mdx +++ b/docs/ja/start/quickstart.mdx @@ -1,36 +1,36 @@ --- title: "クイックスタート" -description: "エージェントセッションをキャプチャし、失敗を発見して、防止策を導入する。" +description: "エージェントセッションをキャプチャし、障害を発見して、防止を開始する。" icon: "zap" --- -このクイックスタートでは、1台のマシンでセッションのレポートを開始し、監査を実行し、ポリシーをデプロイします。スキルを使って Failproof をセットアップするか、手動手順に従ってください。 +このクイックスタートでは、1台のマシンでセッションのレポートを開始し、監査を実行して、ポリシーをデプロイします。スキルを使って Failproof をセットアップするか、手動の手順に従ってください。 -**どちらのパスを選びますか？** エージェントが12種類のサポート対象[ハーネス](/ja/reference/harnesses)のいずれかで動作している場合（コーディングCLI、またはHermesやOpenClawなどのゲートウェイ）、以下の手順に従ってください。Node.js 20.9以降が必要です。エージェントにハーネスがない場合は、[Python SDK](/ja/reference/custom-agents)でトレースと監査を計装し、[最初の障害チェックを実行する](/ja/start/first-audit)から再合流してください。このパスでの強制実行にはランタイムへのフックが必要です。 +**どちらの方法を選びますか？** エージェントが12種類のサポートされた[ハーネス](/ja/reference/harnesses)（コーディング CLI、または Hermes や OpenClaw などのゲートウェイ）で動作している場合は、以下の手順に従ってください。Node.js 20.9 以降が必要です。エージェントにハーネスがない場合は、[Python SDK](/ja/reference/custom-agents) を使ってトレースと監査のインストルメンテーションを行い、[最初の障害チェックを実行する](/ja/start/first-audit) から再合流してください。このパスでの強制実行には、ランタイムにフックが必要です。 - + ```bash npx skills add FailproofAI/skills ``` - + ```text Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - エージェントがプロジェクトを検査し、適切なインテグレーションを選択してセットアップを実行し、動作確認を行います。個別のスキルや高度なインストールオプションについては、[FailproofAI スキルリポジトリ](https://github.com/FailproofAI/skills)を参照してください。 + エージェントがプロジェクトを検査し、適切なインテグレーションを選択してセットアップを実行し、検証します。個別のスキルや高度なインストールオプションについては、[FailproofAI skills リポジトリ](https://github.com/FailproofAI/skills) を参照してください。 - ## 始める前に + ## 開始前の準備 -1. [Failproof AI ダッシュボード](https://app.befailproof.ai)を開き、アカウントを作成するか、仕事用メールアドレスでサインインします。 -2. **Administration → Keys** に移動し、`events:add` および `policies:pull` 権限を持つキーを作成します。 -3. ワンタイムシークレットをコピーして、対象マシンに保存します： +1. [Failproof AI ダッシュボード](https://app.befailproof.ai) を開き、アカウントを作成するか、仕事用メールアドレスでサインインします。 +2. **Administration → Keys** に移動し、`events:add` と `policies:pull` のキーを作成します。 +3. ワンタイムシークレットをコピーして、対象マシンに保存します。 ```bash export FAILPROOFAI_KEY="" @@ -47,7 +47,7 @@ export FAILPROOFAI_KEY="" セッションのトランスクリプトはデフォルトで送信されます。トランスクリプトの内容を含めずにフックアクティビティとポリシー決定のみをレポートするには、`--no-transcripts` を追加してください。 - このマシンにすでにエージェントの履歴がある場合は、過去7日分をプレビューしてインポートし、配信が完了するまで待ちます。新しいマシンではこの手順をスキップしてください。 + このマシンにすでにエージェントの履歴がある場合は、過去7日間のデータをプレビューしてインポートし、配信が完了するまで待ちます。新しいマシンではこの手順をスキップしてください。 ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +55,30 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Failproof AI の **Sessions** を開き、インポートされたセッションを選択します。 + Failproof AI の **Sessions** を開き、インポートしたセッションを選択します。 - これにより Failproof AI がハーネスにアタッチされ、40種類の組み込みポリシーがインストールされます。Failproof AI がセッションを監査してエージェント向けのポリシーを作成する前に、ローカルでのポリシー決定を確認したり、強制実行を試したりするために使用してください。 + これにより Failproof AI がハーネスにアタッチされ、39個の組み込みポリシーがインストールされます。Failproof AI がセッションを監査してエージェント用のポリシーを作成する前に、ローカルのポリシー決定を確認したり、強制実行を試したりするために使用できます。 - インストーラーにハーネスを自動検出させるか、明示的に指定することもできます。12種類すべてが有効な `--cli` の値です — `claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity`、`goose`。 + インストーラーにハーネスを自動検出させるか、明示的に指定してください。12種類すべてが有効な `--cli` の値です — `claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity`、`goose`。 ```bash - failproofai policies --install --cli claude --scope user # コーディングCLI - failproofai policies --install --cli hermes --scope user # Slack/Telegramゲートウェイ + failproofai policies --install --cli claude --scope user # コーディング CLI + failproofai policies --install --cli hermes --scope user # Slack/Telegram ゲートウェイ ``` - 実行前のツール呼び出しのブロックは全12種類で検証済みです。ターン終了ゲートは8種類で検証済みです — ハーネスごとのマトリクスは[強制実行機能](/ja/reference/harnesses#enforcement-capability)を参照してください。 + 実行前のツール呼び出しのブロックは全12種類で検証済みです。ターン終了ゲートは8種類で検証済みです — ハーネスごとの対応状況は[強制実行の対応状況](/ja/reference/harnesses#enforcement-capability)を参照してください。 - [最初の障害チェックを実行する](/ja/start/first-audit)に従ってください。「エージェントがアプローチを変えずに失敗したツールを再試行したセッションを見つける」など、具体的な目標を設定してください。 + [最初の障害チェックを実行する](/ja/start/first-audit) に従ってください。「エージェントがアプローチを変えずに失敗したツールを再試行したセッションを見つける」など、具体的な目標を使用してください。 - [ポリシーで最初の障害を防止する](/ja/start/first-policy)に従ってください。まずオブザーブモードで開始し、マッチを確認してから、レビュー済みのバージョンを強制実行します。 + [ポリシーで最初の障害を防止する](/ja/start/first-policy) に従ってください。オブザーブモードで開始し、マッチを確認してから、レビュー済みのバージョンを強制適用してください。 - `failproofai config --status` を実行してください。正常なセットアップでは、クラウド接続、デーモンの状態、および強制実行が一時停止中かどうかが表示されます。 + `failproofai config --status` を実行してください。正常なセットアップでは、クラウド接続、デーモンの状態、および強制実行が一時停止されているかどうかが報告されます。 \ No newline at end of file diff --git a/docs/ko/policies/builtin-catalog.mdx b/docs/ko/policies/builtin-catalog.mdx index 6c647362..5f1e7d6b 100644 --- a/docs/ko/policies/builtin-catalog.mdx +++ b/docs/ko/policies/builtin-catalog.mdx @@ -1,70 +1,70 @@ --- title: "내장 정책 카탈로그" -description: "Failproof AI의 모든 내장 정책, 트리거, 권장 상태 및 설정 가능한 파라미터를 확인하세요." +description: "Failproof AI의 모든 내장 정책, 트리거, 권장 상태 및 구성 가능한 파라미터를 확인하세요." icon: "list-checks" --- -설치된 패키지가 정책 가용성의 기준이 됩니다. 카탈로그 항목과 동작이 패키지 버전에 따라 변경될 수 있으므로, 업그레이드할 때마다 `failproofai policies`를 실행하세요. +설치된 패키지가 정책 가용성의 기준이 됩니다. 패키지를 업그레이드할 때마다 `failproofai policies`를 실행하세요. 카탈로그 항목과 동작은 패키지 버전에 따라 변경될 수 있습니다. -## 권장 기준 설정 +## 권장 기본 설정 -가이드 설정의 권장 선택 항목은 현재 시크릿 새니타이저, 환경 보호, 자기 보호, 치명적 명령 차단, 보호 브랜치 안전 기능을 활성화합니다: +안내형 설정의 권장 선택 항목은 현재 시크릿 제거, 환경 보호, 자체 보호, 치명적 명령 차단, 보호 브랜치 안전 기능을 활성화합니다: ```text sanitize-jwt sanitize-api-keys sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars block-env-files block-secrets-write -block-self-pause block-failproofai-commands -block-sudo block-curl-pipe-sh -block-rm-rf block-push-master -block-force-push +block-failproofai-commands block-sudo +block-curl-pipe-sh block-rm-rf +block-push-master block-force-push ``` -권장 항목은 의도적으로 **전체** 설정보다 좁게 구성되어 있습니다. 인프라 및 워크플로 정책은 유효한 작업을 방해할 수 있으므로, 필요한 저장소와 머신에 한해 활성화해야 합니다. +`block-failproofai-commands`는 **항상 활성화**됩니다. 완전한 목록을 위해 위에 포함되었지만, 활성화 목록에 포함 여부와 관계없이 모든 평가 시 등록되며 비활성화하거나 일시 중지할 수 없습니다. 에이전트가 끌 수 있는 강제 집행 스위치는 진정한 보호 장치가 아니기 때문입니다. + +권장 설정은 의도적으로 **전체(Everything)** 보다 좁은 범위로 구성되어 있습니다. 인프라 및 워크플로 정책은 정상적인 작업을 방해할 수 있으므로, 필요한 저장소와 머신에서만 활성화해야 합니다. ## 시크릿 및 환경 | 정책 | 트리거 | 결과 | | --- | --- | --- | | `sanitize-jwt` | `PostToolUse` | 모델이 보기 전에 도구 출력에서 JWT를 제거합니다. | -| `sanitize-api-keys` | `PostToolUse` | OpenAI, Anthropic, GitHub, AWS, Stripe, Google의 주요 키를 제거합니다. | -| `sanitize-connection-strings` | `PostToolUse` | 자격 증명이 포함된 데이터베이스 연결 문자열을 제거합니다. | -| `sanitize-private-key-content` | `PostToolUse` | PEM 프라이빗 키 본문을 제거합니다. | -| `sanitize-bearer-tokens` | `PostToolUse` | 인증 bearer 토큰을 제거합니다. | -| `protect-env-vars` | 셸 도구에서 `PreToolUse` | 환경 변수를 출력하는 명령을 차단합니다. | +| `sanitize-api-keys` | `PostToolUse` | 일반적인 OpenAI, Anthropic, GitHub, AWS, Stripe, Google 키를 제거합니다. | +| `sanitize-connection-strings` | `PostToolUse` | 인증 정보가 포함된 데이터베이스 연결 문자열을 제거합니다. | +| `sanitize-private-key-content` | `PostToolUse` | PEM 개인 키 본문을 제거합니다. | +| `sanitize-bearer-tokens` | `PostToolUse` | 인증 Bearer 토큰을 제거합니다. | +| `protect-env-vars` | 셸 도구에서 `PreToolUse` | 환경 변수를 덤프하는 명령을 차단합니다. | | `block-env-files` | `PreToolUse` | `.env` 파일의 읽기 및 쓰기를 차단합니다. | -| `block-read-outside-cwd` | 읽기, glob, grep 또는 셸 도구에서 `PreToolUse` | 읽기 작업을 세션 작업 디렉토리 내로 제한합니다. | +| `block-read-outside-cwd` | 읽기, glob, grep, 셸 도구에서 `PreToolUse` | 세션 작업 디렉터리 내에서만 읽기를 허용합니다. | | `block-secrets-write` | 쓰기 도구에서 `PreToolUse` | 일반적인 시크릿 키 및 자격 증명 파일명에 대한 쓰기를 차단합니다. | -## 위험 명령 및 인프라 +## 위험한 명령 및 인프라 | 정책 | 트리거 | 결과 | | --- | --- | --- | -| `block-self-pause` | `PreToolUse`, `PermissionRequest` | 에이전트가 자체 적용을 일시 중지하지 못하도록 방지합니다. | -| `block-sudo` | `PreToolUse`, `PermissionRequest` | 허용 패턴이 일치하지 않는 한 `sudo`를 차단합니다. | -| `block-curl-pipe-sh` | `PreToolUse` | 다운로드한 스크립트를 셸에 직접 파이프하는 것을 차단합니다. | -| `block-rm-rf` | `PreToolUse` | 치명적인 재귀 삭제 패턴을 차단합니다. | -| `block-failproofai-commands` | `PreToolUse` | 에이전트가 Failproof AI를 변경하거나 제거하지 못하도록 방지합니다. | +| `block-sudo` | `PreToolUse`, `PermissionRequest` | allow 패턴이 일치하지 않는 한 `sudo`를 차단합니다. | +| `block-curl-pipe-sh` | `PreToolUse` | 셸로 직접 파이프되는 다운로드 스크립트를 차단합니다. | +| `block-rm-rf` | `PreToolUse` | 재귀적 삭제 패턴을 차단합니다. | +| `block-failproofai-commands` | `PreToolUse`, `PermissionRequest` | **항상 활성화, 비활성화 불가.** 모든 Failproof AI CLI 호출, 자체 일시 중지, 패키지 관리자 제거를 차단합니다. | | `block-kubectl` | `PreToolUse` | Kubernetes 명령을 제한합니다. | | `block-terraform` | `PreToolUse` | Terraform 및 OpenTofu 명령을 제한합니다. | | `block-aws-cli` | `PreToolUse` | AWS CLI 명령을 제한합니다. | | `block-gcloud` | `PreToolUse` | Google Cloud CLI 명령을 제한합니다. | | `block-az-cli` | `PreToolUse` | Azure CLI 명령을 제한합니다. | | `block-helm` | `PreToolUse` | Helm 명령을 제한합니다. | -| `block-gh-pipeline` | `PreToolUse` | GitHub CLI 워크플로, 실행, 병합, 릴리스, 캐시, 시크릿 등 변경 작업을 제한합니다. | +| `block-gh-pipeline` | `PreToolUse` | 변경을 유발하는 GitHub CLI의 workflow, run, merge, release, cache, secret 작업을 제한합니다. | ## Git 및 데이터베이스 안전 | 정책 | 트리거 | 결과 | | --- | --- | --- | | `block-push-master` | `PreToolUse` | 설정된 보호 브랜치로의 직접 푸시를 차단합니다. | -| `block-force-push` | `PreToolUse` | 강제 푸시를 차단합니다. 현재 구현에서 `--force-with-lease`는 허용됩니다. | +| `block-force-push` | `PreToolUse` | 강제 푸시를 차단합니다. `--force-with-lease`는 현재 구현에서 허용됩니다. | | `block-work-on-main` | `PreToolUse` | 보호 브랜치에서의 커밋 및 병합을 차단합니다. | | `warn-git-amend` | `PreToolUse` | `--amend`로 커밋을 재작성하기 전에 경고합니다. | | `warn-git-stash-drop` | `PreToolUse` | 스태시를 영구적으로 삭제하거나 초기화하기 전에 경고합니다. | -| `warn-all-files-staged` | `PreToolUse` | `git add -A`, `git add .`, `git add --all`과 같이 광범위한 스테이징 시 경고합니다. | -| `warn-destructive-sql` | `PreToolUse` | 인식된 데이터베이스 클라이언트를 통해 `WHERE` 없이 `DROP`, `TRUNCATE`, `DELETE` 실행 시 경고합니다. | +| `warn-all-files-staged` | `PreToolUse` | `git add -A`, `git add .`, `git add --all`과 같은 광범위한 스테이징 시 경고합니다. | +| `warn-destructive-sql` | `PreToolUse` | 인식된 데이터베이스 클라이언트를 통해 `WHERE` 없이 `DROP`, `TRUNCATE`, `DELETE`를 실행할 때 경고합니다. | | `warn-schema-alteration` | `PreToolUse` | 인식된 `ALTER TABLE` 컬럼 및 이름 변경 작업 시 경고합니다. | ## 패키지, 시스템 동작 및 에이전트 루프 @@ -73,10 +73,10 @@ block-force-push | --- | --- | --- | | `warn-package-publish` | `PreToolUse` | 패키지 레지스트리에 게시하기 전에 경고합니다. | | `warn-global-package-install` | `PreToolUse` | 전역 패키지 설치 전에 경고합니다. | -| `prefer-package-manager` | `PreToolUse` | 허용된 패키지 매니저를 사용하도록 에이전트에 지시합니다. | -| `warn-large-file-write` | 쓰기 도구에서 `PreToolUse` | 설정된 파일 크기 임계값을 초과할 경우 경고합니다. | +| `prefer-package-manager` | `PreToolUse` | 허용된 패키지 관리자를 사용하도록 에이전트에 지시합니다. | +| `warn-large-file-write` | 쓰기 도구에서 `PreToolUse` | 설정된 파일 크기 임계값을 초과하면 경고합니다. | | `warn-background-process` | `PreToolUse` | 분리되거나 장시간 실행되는 백그라운드 프로세스 패턴 시 경고합니다. | -| `warn-repeated-tool-calls` | `PreToolUse` | 동일한 도구 호출이 세 번 이상 반복될 경우 경고합니다. | +| `warn-repeated-tool-calls` | `PreToolUse` | 동일한 도구 호출이 3회 이상 반복되면 경고합니다. | ## 작업 종료 워크플로 @@ -85,14 +85,14 @@ block-force-push | 정책 | 결과 | | --- | --- | | `require-commit-before-stop` | 추적된 작업이 커밋되지 않은 상태로 남아 있으면 완료를 거부합니다. | -| `require-push-before-stop` | 커밋이 로컬에만 존재하는 경우 완료를 거부합니다. | +| `require-push-before-stop` | 커밋이 로컬에만 남아 있으면 완료를 거부합니다. | | `require-pr-before-stop` | 현재 브랜치에 대한 풀 리퀘스트를 요구합니다. | -| `require-no-conflicts-before-stop` | 설정된 베이스 브랜치와의 충돌 없는 병합을 요구합니다. | -| `require-ci-green-before-stop` | 현재 HEAD의 CI 검사가 성공적으로 완료되어야 합니다. | +| `require-no-conflicts-before-stop` | 설정된 기본 브랜치에 대해 충돌 없는 병합 상태를 요구합니다. | +| `require-ci-green-before-stop` | 현재 HEAD의 CI 검사가 성공적으로 완료될 것을 요구합니다. | ## 파라미터 참조 -선택된 스코프의 `policyParams` 객체 아래에서 파라미터를 설정합니다. 타입은 각 정책에서 유효성 검사합니다. +선택된 스코프의 `policyParams` 객체 아래에 파라미터를 구성합니다. 타입은 각 정책에 의해 검증됩니다. | 정책 | 파라미터 | 타입 및 기본값 | | --- | --- | --- | @@ -125,5 +125,5 @@ block-force-push ``` - 허용 패턴은 에이전트가 수행할 수 있는 작업 범위를 넓힙니다. 플릿 전체에 배포하기 전에 대상 하네스에서 정확한 토큰화 및 명령 변형을 테스트하세요. + allow 패턴은 에이전트가 수행할 수 있는 작업 범위를 넓힙니다. 플릿 전체에 배포하기 전에 대상 하네스에서 정확한 토크나이징 방식과 명령 변형을 테스트하세요. \ No newline at end of file diff --git a/docs/ko/policies/failure-behavior.mdx b/docs/ko/policies/failure-behavior.mdx index 1a19faa3..def8ca1b 100644 --- a/docs/ko/policies/failure-behavior.mdx +++ b/docs/ko/policies/failure-behavior.mdx @@ -4,16 +4,16 @@ description: "정책 평가 또는 로컬 데몬을 사용할 수 없을 때 어 icon: "shield-alert" --- -Failproof AI는 실행 실패가 위험한 작업을 조용히 허용하는 대신 눈에 띄게 드러나도록 설계되었습니다. +Failproof AI는 적용 실패가 위험한 작업을 조용히 허용하는 대신 가시적으로 드러나도록 설계되어 있습니다. -## 실패 차단 진단 +## 실패-폐쇄 차단 진단 - 1. **Admin → enforcement**로 이동하여 해당 머신을 엽니다. + 1. **Admin → enforcement**으로 이동하여 해당 머신을 엽니다. 2. 마지막 체크인, 할당된 배포, 보고된 배포를 확인합니다. 3. **Observe → policy**로 이동하여 거부된 결정의 세션을 엽니다. - 4. 이유가 데몬 접근성, 버전 불일치, 또는 정책 자체를 보고하는지 확인합니다. + 4. 이유가 데몬 도달 가능성, 버전 불일치, 또는 정책 자체를 보고하는지 확인합니다. @@ -23,21 +23,45 @@ Failproof AI는 실행 실패가 위험한 작업을 조용히 허용하는 대 failproofai config ``` - `failproofai config`를 다시 실행하면 패키지 업그레이드 후 데몬이 업데이트되고 재시작됩니다. + `failproofai config`를 다시 실행하면 패키지 업그레이드 후 데몬을 업데이트하고 재시작합니다. -`failproofaid`를 사용하도록 구성된 머신에서는 데몬이 유일한 평가자입니다. 데몬에 접근할 수 없거나 프로토콜 버전이 CLI와 일치하지 않으면 훅 평가가 실패 차단 방식으로 동작합니다. 작업은 거부되며, 운영자가 데몬을 확인하거나 업데이트하도록 안내하는 이유가 함께 표시됩니다. +`failproofaid`를 사용하도록 구성된 머신에서는 데몬이 유일한 평가자입니다. 데몬에 도달할 수 없거나 프로토콜 버전이 CLI와 일치하지 않으면 훅 평가가 실패-폐쇄 방식으로 처리됩니다. 작업은 거부되며, 운영자가 데몬을 확인하거나 업데이트하도록 안내하는 이유가 표시됩니다. -데몬 구성 전에는 훅이 프로세스 내에서 정책을 평가합니다. 데몬 구성이 기록된 이후에는 Failproof AI가 데몬 실패 시 자동으로 다른 평가자로 대체하지 않습니다. +데몬 구성 전에는 훅이 프로세스 내에서 정책을 평가합니다. 데몬 구성이 기록되면 Failproof AI는 데몬 실패 시 두 번째 평가자로 조용히 전환하지 않습니다. -## 실패 차단 결정에 대응하기 +## 실패-폐쇄 결정에 대응하기 1. `failproofai config --status`를 실행합니다. -2. 버전이 다른 경우, 패키지를 업데이트한 후 `failproofai config`를 다시 실행합니다. -3. 데몬에 접근할 수 없는 경우, 서비스 상태와 로컬 로그를 점검합니다. +2. 버전이 다를 경우 패키지 업데이트 후 `failproofai config`를 다시 실행합니다. +3. 데몬에 도달할 수 없는 경우 서비스 상태와 로컬 로그를 확인합니다. 4. 정책 평가 경로가 정상임을 확인한 후에만 에이전트 작업을 재개합니다. - 차단된 작업을 반복적으로 재시도하지 마십시오. 실패 차단 응답은 시스템이 해당 작업의 안전성을 확인할 수 없었음을 의미합니다. - \ No newline at end of file + 차단된 작업을 반복해서 재시도하지 마십시오. 실패-폐쇄 응답은 시스템이 해당 작업의 안전성을 확인할 수 없었음을 의미합니다. + + +## 팩이 로드되지 않는 경우 + +팩을 적용하도록 지시받은 머신이 해당 팩을 실행할 수 없으면, 조용히 계속 진행하는 대신 거부합니다. 트리거는 **기록된 기대치**이며, 비어 있는 기대치가 아닙니다. 팩이 설치되지 않은 머신은 아무런 반응을 하지 않지만, 선언된 팩이 해석되지 않거나 매니페스트에 선언된 것보다 적게 등록되면 거부합니다. + +거부는 도달할 수 없는 데몬의 경우와 달리 **범위가 좁습니다**. 데몬에 도달할 수 없다는 것은 평가 자체가 전혀 이루어지지 않았음을 의미하므로 어느 것도 안전하다고 알 수 없습니다. 로드되지 않는 팩은 누락된 가드의 열거 가능한 집합을 가지며, 선언된 모든 정책은 자체적인 `match`를 가지고 있으므로 해당 정책이 적용하는 이벤트와 도구에 대해서만 거부하고 나머지는 정상적으로 진행됩니다. + +다음의 경우에는 실행되지 않습니다: + +- 구성상 평가 후 폐기되는 `observe` 팩 +- 채택하지 않았거나 명시적으로 비활성화한 정책 +- 로더가 전혀 수신하지 못한 팩 — 이 경우 "등록 없음"을 의도적인 건너뜀과 구별할 수 없습니다 +- 활성 세션 일시 중지 +- 일시적인 로드 타임아웃 — 디스크가 잠깐 느린 순간 때문에 사람이 개입할 때까지 거부해서는 안 됩니다 + +`UserPromptSubmit`은 누락된 정책이 무엇을 선언했든 거부 대신 **instruct**합니다. 무조건적인 거부는 문제를 해결할 수 있는 에이전트에서 당신을 잠가 버릴 것입니다. + +### 해결 방법 + +```bash +failproofai pack list +``` + +이 명령은 로드되지 않는 설치된 팩의 이름과 이유를 출력하고 비정상 종료합니다. 이후 팩을 재설치하거나(`failproofai pack add `) 제거하십시오(`failproofai pack remove `). 제거하면 기대치가 철회되고 거부도 함께 중단됩니다. \ No newline at end of file diff --git a/docs/ko/policies/packs.mdx b/docs/ko/policies/packs.mdx new file mode 100644 index 00000000..df8675a3 --- /dev/null +++ b/docs/ko/policies/packs.mdx @@ -0,0 +1,110 @@ +--- +title: "Policy 팩" +description: "GitHub 릴리스로 게시된 policy 세트를 설치하고, 적용 항목을 관리합니다." +icon: "package" +--- + +팩은 GitHub 릴리스로 게시된 policy 세트입니다. 명령 하나로 설치할 수 있으며, 실행 전에 릴리스 자체의 체크섬이 검증되고, 설치 후 팩이 변경되지 않도록 다이제스트가 기록됩니다. + +## Failproof AI policy 설치 + +```bash +failproofai pack add core +``` + +이 명령은 패키지 내부에 포함된 사본에서 당사가 게시한 세트를 설치합니다. 따라서 네트워크가 필요 없고 프록시 환경에서도 실패하지 않습니다. 일부만 가져오려면: + +```bash +failproofai pack add core --policy block-rm-rf # 하나, 또는 쉼표로 구분된 몇 개 +failproofai pack add core --category dangerous-commands # 카테고리 전체 +failproofai pack add core --all # 팩의 모든 항목 +``` + +`failproofai pack list`를 실행하면 팩이 제공하는 모든 카테고리를 확인할 수 있습니다. + +## 설치 전에 팩 내용 확인 + +```bash +failproofai pack list acme/support-agent +``` + +팩에 포함된 모든 policy를 카테고리별로 그룹화하여 나열하며, 작성자가 기본적으로 활성화한 항목과 선택적으로 적용해야 하는 항목을 표시합니다. **매니페스트만** 읽으며, 엔트리 아티팩트는 다운로드되거나 임포트되지 않으므로 낯선 팩을 조회해도 낯선 코드가 실행되지 않습니다. 매니페스트는 여전히 릴리스의 `SHA256SUMS`와 대조 검증되므로, 읽고 있는 내용이 실제로 설치될 내용과 동일합니다. + +소스 없이 `failproofai pack list`를 실행하면 현재 설치된 팩 목록을 확인할 수 있습니다. + +## 다른 사람의 팩 설치 + +```bash +failproofai pack add acme/support-agent +``` + +아래 형식 중 어느 것이든 사용할 수 있습니다: + +| 소스 | 결과 | +| --- | --- | +| `acme/support-agent` | 최신 릴리스, 해당 태그로 **고정** | +| `acme/support-agent@v2.1.0` | 해당 릴리스 | +| `github:acme/support-agent@v2.1.0` | 동일, 명시적으로 작성한 형식 | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | 동일, 브라우저에서 복사한 형식 | + +태그를 지정하지 않으면 최신 릴리스를 설치하고 **고정**한 뒤, 선택된 태그를 알려줍니다. 기록되는 내용은 항상 정확히 하나의 릴리스를 명시하므로, 재설치 시 버전이 달라지는 일이 없습니다. + +## 팩의 일부만 가져오기 + +기본적으로 팩의 **자체** 기본값, 즉 작성자가 자동 활성화해도 안전하다고 표시한 policy만 적용되며, 팩의 모든 내용이 적용되지는 않습니다. + +```bash +failproofai pack add acme/support-agent --category billing,git +failproofai pack add acme/support-agent --policy block-refunds +failproofai pack add acme/support-agent --all +``` + +`--category`와 `--policy`는 합집합으로 결합됩니다(`--only`는 `--policy`의 동의어로 사용 가능). 새 버전으로 다시 추가하면 이전에 선택한 항목이 유지되며, 나머지 항목이 다시 켜지지 않습니다. + +## 활성화된 항목 관리 + +```bash +failproofai policies # 팩을 포함한 모든 소스를 한 목록으로 표시 +failproofai pack list # 팩만 카테고리별로 그룹화하여 표시 +failproofai policies --uninstall block-refunds # 팩 policy 하나 비활성화 +failproofai policies --install block-refunds # 다시 활성화 +failproofai pack remove acme/support-agent +``` + +이름만 지정하면 해당 이름의 **내장** policy를 의미합니다. 팩의 사본을 명시적으로 지정해야 할 때는: + +```bash +failproofai policies --uninstall acme/support-agent:block-refunds +``` + + +팩에 포함된 policy의 이름이 **활성화된 내장** policy와 동일한 경우, 내장 policy가 실행되고 팩의 사본은 건너뜁니다. 동일한 가드가 두 번 평가되는 것을 방지하기 위해서입니다. 팩의 사본을 사용하려면 내장 policy를 비활성화하세요. + + +## Failproof AI policy의 출처 + +`core`는 npm 패키지에 포함된 사본을 읽습니다. 동일한 세트가 GitHub 릴리스로도 게시되며, 특정 버전을 원할 경우 해당 방법으로 설치할 수 있습니다: + +```bash +failproofai pack add core # 이 패키지에서, 네트워크 불필요 +failproofai pack add FailproofAI/policies # 동일한 세트, GitHub 릴리스에서 +``` + +## 무결성 검증이 보장하는 것과 보장하지 않는 것 + +`SHA256SUMS`는 아티팩트와 동일한 릴리스에 포함되므로 **서명이 아니며**, 게시자가 누구인지는 증명하지 않습니다. 다만 바이트가 해당 릴리스에서 게시된 것과 동일하다는 것은 증명합니다. 팩을 추가할 때 다이제스트가 기록되고 임포트 전마다 재검증되므로, 이후 팩이 변경되어도 해당 머신에서 그대로 사용되는 일이 없습니다. 태그를 재설정하거나 에셋을 교체한 저장소는 다른 내용을 조용히 실행하는 대신 로딩이 중단됩니다. + +설치 시 팩은 **한 번 임포트**되어 자체 매니페스트와 대조 확인됩니다. 아티팩트를 파싱할 수 없거나 선언한 내용과 다른 항목을 등록하려는 팩은, 정상적으로 설치된 후 다음 도구 호출 시 실패하는 대신, 활성화 전에 거부됩니다. + +## 팩이 로드되지 않는 경우 + +머신이 적용하도록 설정된 팩을 실행할 수 없는 경우, 해당 팩의 누락된 policy가 처리하던 이벤트를 자동으로 허용하는 것이 아니라 **거부**합니다. 자세한 내용은 [실패 동작](/ko/policies/failure-behavior)을 참조하세요. `failproofai pack list`는 해당 상태의 팩 이름을 표시하고 0이 아닌 종료 코드로 종료합니다. + +## 오프라인 및 미러 사용 + +| 변수 | 효과 | +| --- | --- | +| `FAILPROOFAI_NO_DOWNLOAD=1` | 가져오기 거부; 이미 설치된 팩은 계속 적용됨 | +| `FAILPROOFAI_PACK_BASE_URL` | 팩 가져오기를 `github.com` 대신 미러로 지정 | + +자체 팩 게시에 대해서는 [팩 게시](/ko/policies/publish-a-pack)를 참조하세요. \ No newline at end of file diff --git a/docs/ko/policies/publish-a-pack.mdx b/docs/ko/policies/publish-a-pack.mdx new file mode 100644 index 00000000..49f7861d --- /dev/null +++ b/docs/ko/policies/publish-a-pack.mdx @@ -0,0 +1,91 @@ +--- +title: "팩 게시하기" +description: "직접 만든 정책을 GitHub 릴리스로 배포하여 누구나 설치할 수 있게 합니다." +icon: "upload" +--- + +팩은 GitHub 릴리스에 첨부된 세 개의 파일로 구성됩니다. `failproofai pack build`를 실행하면 이미 가지고 있는 정책 파일로부터 세 파일 모두 생성됩니다. + +## 1. 정책 작성하기 + +커스텀 정책과 동일한 API를 사용하는 파일 하나로 작성합니다. 팩에서 중요한 추가 필드가 두 가지 있습니다: + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-refunds", + description: "Refunds above the approved limit need a human", + category: "Billing", // groups it, and is what --category selects on + defaultEnabled: true, // switched on by a plain `pack add` + match: { events: ["PreToolUse"], tools: ["Bash"] }, + fn: async (ctx) => + String(ctx.toolInput?.command ?? "").includes("refund") + ? deny("Refunds need a human. Ask before running this.") + : allow(), +}); +``` + +`defaultEnabled`를 생략하면 기본값은 **false**입니다. `failproofai pack add`를 그냥 실행하면 표시해 둔 정책만 활성화됩니다. 처음 보는 사람의 모든 정책을 사용자 동의 없이 설치하는 건 설치 도구가 사용자 대신 결정할 일이 아닙니다. + + +엔트리는 **완전히 독립된 하나의 파일**이어야 합니다. 다이제스트 핀은 엔트리 파일에만 적용되므로, 로컬 파일을 임포트하는 팩은 다이제스트가 실제 실행 코드를 보장한다고 말할 수 없습니다. 먼저 번들링(`esbuild`, `bun build`, `rollup`)한 뒤 번들로부터 팩을 빌드하세요 — `pack build`는 지킬 수 없는 약속을 배포하는 대신 로컬 임포트가 있으면 거부합니다. + + +## 2. 릴리스 에셋 빌드하기 + +```bash +failproofai pack build ./policies.mjs \ + --id acme/support-agent \ + --version 1.0.0 \ + --out ./dist-pack +``` + +세 개의 파일을 생성하며, 모든 정책을 **로더 자체 규칙**으로 먼저 검증합니다. 따라서 설치가 절대 불가능한 팩은 여기서 실패하고, 수정할 기회가 생깁니다: + +| 파일 | 설명 | +| --- | --- | +| `failproofai-pack.json` | 매니페스트: id, 버전, effect, 정책별 항목 포함 | +| `failproofai-pack.mjs` | 그대로 복사된 엔트리 파일 | +| `SHA256SUMS` | 나머지 두 파일에 대한 ` ` | + +빌드 시 거부되는 경우: `publisher/name` 형식이 아닌 id, `/`가 포함된 정책 이름, `alwaysOn`을 선언하는 정책, `description`·`category`·`match` 누락, 아무것도 등록하지 않는 엔트리, 로컬 파일을 임포트하는 엔트리. + +## 3. 릴리스에 파일 첨부하기 + +빌드 시 사용한 버전과 동일한 태그로 릴리스를 생성하고, 세 파일을 릴리스 에셋으로 첨부합니다: + +```bash +gh release create 1.0.0 \ + ./dist-pack/failproofai-pack.json \ + ./dist-pack/failproofai-pack.mjs \ + ./dist-pack/SHA256SUMS +``` + +이제 누구나 설치할 수 있습니다: + +```bash +failproofai pack add acme/support-agent +``` + +에셋 이름은 고정되어 있습니다 — API 호출이나 별도의 탐색 과정 없이 설치 CLI가 URL을 구성할 때 사용하는 이름이기 때문입니다. + +## 새 버전 배포하기 + +새 `--version`으로 빌드하고, 새 릴리스에 태그를 달아 세 에셋을 다시 첨부하세요. 사용자는 동일한 `pack add` 명령으로 업그레이드하며, 이전에 선택한 정책 구성이 유지됩니다. 비활성화해 둔 정책은 업그레이드 후에도 비활성 상태를 유지합니다. + +정책의 **이름**을 변경하는 것은 하위 호환성을 깨는 변경입니다. 해당 이름을 비활성화해 둔 머신은 이제 존재하지 않는 이름을 끄고 있는 셈이 되고, 새 이름은 `defaultEnabled` 설정에 따라 활성화 여부가 결정됩니다. + +## 사용자가 신뢰하는 대상 + +`SHA256SUMS`는 아티팩트와 동일한 릴리스에 포함되어 있으므로, 게시한 바이트가 맞다는 것을 증명합니다 — 게시자가 누구인지는 증명하지 않습니다. 저장소에 쓰기 권한이 있는 사람은 두 파일 모두 수정할 수 있습니다. 사용자를 보호하는 것은 설치 시점에 다이제스트가 고정된다는 점입니다. 따라서 배포한 내용이 이후에 몰래 바뀌더라도 사용자에게는 영향을 미치지 않습니다. + +쓰기 권한을 직접 관리하는 저장소에서 게시하고, 팩 릴리스를 패키지 배포와 동일하게 취급하세요. + +## 적용 전 관찰하기 + +매니페스트에 `"effect": "observe"`를 선언할 수 있습니다. 해당 정책들은 실행되고 판정 결과가 **기록되지만 무시됩니다** — 아무것도 차단되지 않습니다. 누군가의 작업을 방해하기 전에 실제 트래픽을 기반으로 새 규칙을 측정하는 방법입니다. + +```json +{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +``` \ No newline at end of file diff --git a/docs/ko/reference/failproof-cli.mdx b/docs/ko/reference/failproof-cli.mdx index e04cb098..dbdbe489 100644 --- a/docs/ko/reference/failproof-cli.mdx +++ b/docs/ko/reference/failproof-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof AI CLI" -description: "훅 설치, 로컬 정책 관리, Cloud 연결, 로컬 데몬 운영." +description: "훅 설치, 로컬 정책 관리, Cloud 연결 및 로컬 데몬 운영." icon: "terminal" --- -`npm install -g failproofai`로 로컬 CLI를 설치합니다. 인수 없이 실행하면 로컬 정책 대시보드가 열립니다. +`npm install -g failproofai`로 로컬 CLI를 설치하세요. 인수 없이 실행하면 로컬 정책 대시보드가 열립니다. -이 패키지는 Node.js 20.9 이상이 필요합니다. 개발 및 소스 설치에는 Bun 1.3 이상이 지원됩니다. `failproofai configure`와 `failproofai setup`은 `failproofai config`의 별칭이며, `failproofai p`는 `failproofai policies`의 별칭입니다. +이 패키지는 Node.js 20.9 이상이 필요합니다. Bun 1.3 이상은 개발 및 소스 설치에 지원됩니다. `failproofai configure`와 `failproofai setup`은 `failproofai config`의 별칭이며, `failproofai p`는 `failproofai policies`의 별칭입니다. ## 머신 설정 @@ -22,62 +22,67 @@ failproofai config --status 인수 없이 `failproofai`를 실행하면 로컬 정책 대시보드가 열립니다. -| 명령어 | 결과 | +| 명령 | 결과 | | --- | --- | | `failproofai config` | 대화형 머신 설정 실행 | | `failproofai config --connect --token ` | Cloud 수집 및 정책 전달 연결 | -| `failproofai config --status` | 연결, 데몬, 전달, 일시 중지 상태 표시 | -| `failproofai policies` | 내장 및 사용자 정의 정책 목록 표시 | +| `failproofai config --status` | 연결, 데몬, 전달 및 일시 중지 상태 표시 | +| `failproofai policies` | 내장, 커스텀, 컨벤션, 팩 및 Cloud 관리 정책 목록 표시 | | `failproofai policies --install` | 훅 설치 및 정책 활성화 | -| `failproofai policy add ` | 내장 정책 하나 활성화 | -| `failproofai policy remove ` | 내장 정책 하나 비활성화 | -| `failproofai policies --uninstall` | 정책 비활성화 또는 하네스 훅 제거 | +| `failproofai policy add ` | 정책 하나 활성화 — 내장 정책 또는 설치된 팩의 `:` | +| `failproofai policy remove ` | 정책 하나 비활성화 (동일한 명명 방식) | +| `failproofai policies --uninstall` | 정책 비활성화 또는 하니스 훅 제거 | +| `failproofai pack list` | 설치된 정책 팩과 각 팩에 포함된 모든 정책 목록 표시 | +| `failproofai pack add ` | GitHub 릴리스에서 정책 팩 설치; 태그를 지정하지 않으면 최신 버전을 가져와 고정 | +| `failproofai pack add --bundled` | 내장 정책을 팩으로 설치 (네트워크 없이 이 패키지에서) | +| `failproofai pack build ` | 직접 만든 팩의 세 가지 릴리스 에셋 빌드 | +| `failproofai pack remove ` | 설치된 팩 비활성화 | | `failproofai audit` | 로컬 에이전트 기록 스캔 및 로컬 감사 뷰 열기 | | `failproofai audit --schedule [days] --email
` | 반복 로컬 스캔 예약 및 결과 이메일 전송 | -| `failproofai audit --status` | 보고 주소, 간격, 다음 예약 스캔 표시 | +| `failproofai audit --status` | 보고서 주소, 간격 및 다음 예약 스캔 표시 | | `failproofai audit --no-schedule` | 감사 기록을 삭제하지 않고 반복 스캔 중지 | | `failproofai harness list` | 추가 캡처 경로 목록 표시 | | `failproofai flush --wait` | 현재 이벤트 스풀 전달 | -| `failproofai backfill --since 30d` | 이전에 처리된 기록 다시 읽기 | -| `failproofai config --pause [duration]` | 기본 30분(최대 8시간) 동안 로컬 세션 하나 일시 중지 | -| `failproofai config --resume` | 일시 중지된 로컬 세션 재개; `--all`을 추가하면 모든 일시 중지 해제 | +| `failproofai backfill --since 30d` | 이전에 처리된 기록 재읽기 | +| `failproofai config --pause [duration]` | 하나의 로컬 세션을 기본 30분(최대 8시간) 동안 일시 중지 | +| `failproofai config --resume` | 일시 중지된 로컬 세션 재개; `--all` 추가 시 모든 일시 중지 해제 | | `failproofai update` | 패키지 마이그레이션 완료 및 데몬 업데이트 | -| `failproofai migrate --dry-run` | 대기 중인 홈 레이아웃 마이그레이션 미리 보기 또는 실행 | +| `failproofai migrate --dry-run` | 대기 중인 홈 레이아웃 마이그레이션 미리보기 또는 실행 | | `failproofai uninstall` | 패키지 제거 전 훅 및 데몬 제거 | | `failproofai --version` | 설치된 패키지 버전 출력 | -| `failproofai --help` | 명령어 및 전체 사용법 표시 | +| `failproofai --help` | 명령 및 전체 사용법 표시 | -## 설정 플래그 +## 구성 플래그 | 플래그 | 용도 | | --- | --- | | `--connect --token ` | 비대화형 방식으로 연결 | -| `--machine-id ` | 고정 머신 ID 설정 | +| `--machine-id ` | 안정적인 머신 ID 설정 | | `--machine-label ` | 대시보드 레이블 설정 또는 변경 | -| `--no-transcripts` | 트랜스크립트 내용 없이 결정 사항만 전송 | +| `--no-transcripts` | 트랜스크립트 내용 없이 결정 사항 전송 | | `--disconnect` | Cloud 정책 가져오기 및 이벤트 전달 중지 | | `--status` | 현재 머신 상태 표시 | -| `--pause [duration]` | 현재 디렉터리의 최신 세션을 일시 중지; 초, 분, 시간 단위 허용, 기본값 30분 | -| `--resume` | 해당 일시 중지 조기 종료 | -| `--session ` | 일시 중지 또는 재개할 특정 세션 지정 | +| `--pause [duration]` | 현재 디렉터리의 최신 세션 일시 중지; 초, 분 또는 시간 단위 허용, 기본값 30분 | +| `--resume` | 일치하는 일시 중지 조기 종료 | +| `--session ` | 일시 중지 또는 재개의 대상 세션 지정 | | `--all` | `--resume`과 함께 사용 시 모든 활성 일시 중지 종료 | -로컬 일시 중지는 한 세션에 대해 내장, 사용자 정의, 컨벤션 정책을 중단합니다. 항상 만료되며 Cloud 관리 정책은 비활성화하지 않습니다. `block-self-pause`는 계측된 에이전트가 이 우회 수단을 스스로 사용하지 못하도록 방지합니다. +로컬 일시 중지는 하나의 세션에 대해 내장, 커스텀, 컨벤션 및 팩 정책을 중단시킵니다. 일시 중지는 항상 만료되며 Cloud 관리 정책은 비활성화되지 않습니다. `block-failproofai-commands`는 항상 활성화되어 있으며 비활성화하거나 일시 중지할 수 없으므로, 계측된 에이전트가 이 탈출구를 직접 사용하는 것을 방지합니다. ## 정책 플래그 | 플래그 | 용도 | | --- | --- | -| `--install`, `-i` | 정책 활성화 및 하네스 훅 설치 | +| `--install`, `-i` | 정책 활성화 및 하니스 훅 설치 | | `--uninstall`, `-u` | 정책 비활성화 또는 훅 제거 | -| `--cli ` | 지원되는 하네스 하나 이상 지정 | -| `--scope user\|project\|local\|all` | 설정 범위 선택; `all`은 제거 시 사용 | +| `--cli ` | 지원되는 하니스 하나 이상 지정 | +| `--scope user\|project\|local\|all` | 구성 범위 선택; `all`은 언인스톨용 | | `--beta` | 베타 정책 포함 | -| `--custom`, `-c ` | 사용자 정의 정책 파일 유효성 검사 및 로드; 반복 사용 가능 | +| `--custom`, `-c ` | 커스텀 정책 파일 검증 및 로드; 반복 가능 | -## 전달 및 유지 관리 플래그 +## 전달 및 유지보수 플래그 -| 명령어 | 플래그 | +| 명령 | 플래그 | | --- | --- | | `backfill` | `--since <30d\|6m\|YYYY-MM-DD>`, `--dry-run` | | `flush` | `--wait`, `--timeout ` | @@ -85,9 +90,9 @@ failproofai config --status | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update`는 `npm install -g failproofai@latest` 실행 후에 사용해야 합니다. 홈 레이아웃 마이그레이션을 수행하고, 대응하는 데몬 바이너리를 설치하며, 서비스를 재시작합니다. `--no-daemon`은 레이아웃 마이그레이션만 수행합니다. +`failproofai update`는 `npm install -g failproofai@latest` 이후 실행해야 합니다. 홈 레이아웃 마이그레이션을 수행하고, 일치하는 데몬 바이너리를 설치하며, 서비스를 재시작합니다. `--no-daemon`은 레이아웃 마이그레이션만 수행합니다. -## 하네스 경로 +## 하니스 경로 ```text failproofai harness list [harness] @@ -95,11 +100,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -지원되는 하네스 이름은 `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`입니다. +지원되는 하니스 이름은 `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`입니다. -레이블은 두 루트에 동일한 프로젝트 복사본이 있을 때 파생된 에이전트 ID의 네임스페이스를 구분합니다. 중복 컬렉션이나 커서 손상을 방지하기 위해 겹치는 루트와 중복 레이블은 거부됩니다. 추가 경로 설정은 데몬 재시작 없이 다시 로드됩니다. +레이블은 두 루트에 동일한 프로젝트 복사본이 있을 때 파생된 에이전트 ID를 네임스페이스화합니다. 중복 루트와 중복 레이블은 수집 중복 또는 커서 손상을 방지하기 위해 거부됩니다. 추가 경로 구성은 데몬 재시작 없이 다시 로드됩니다. -컨테이너 환경에서는 파일로 설정된 추가 경로를 `FAILPROOFAI__EXTRA_PATHS`라는 쉼표로 구분된 변수로 대체할 수 있습니다. 예시: +컨테이너 환경에서는 파일로 구성된 추가 경로를 `FAILPROOFAI__EXTRA_PATHS`라는 쉼표로 구분된 변수로 대체할 수 있습니다. 예를 들면: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -107,26 +112,28 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## 환경 변수 -지속적인 머신 동작에는 설정 파일을 사용하세요. 환경 변수는 컨테이너, 테스트, 단일 프로세스에 가장 유용합니다. +지속적인 머신 동작에는 구성 파일을 사용하세요. 환경 변수는 컨테이너, 테스트 및 단일 프로세스에 가장 유용합니다. | 변수 | 용도 | | --- | --- | -| `FAILPROOFAI_HOME` | `~/.failproofai` 전체 레이아웃 위치 변경 | -| `FAILPROOFAI_LOG_LEVEL` | 로컬 로깅 상세도 설정 | -| `FAILPROOFAI_HOOK_LOG_FILE` | 훅 진단 내용을 지정한 파일에 기록 | +| `FAILPROOFAI_HOME` | 전체 `~/.failproofai` 레이아웃 재배치 | +| `FAILPROOFAI_LOG_LEVEL` | 로컬 로깅 상세 수준 설정 | +| `FAILPROOFAI_HOOK_LOG_FILE` | 훅 진단 정보를 선택한 파일에 기록 | | `FAILPROOFAI_TELEMETRY_DISABLED=1` | 이 프로세스의 익명 텔레메트리 비활성화 | -| `FAILPROOFAI_NO_FIRST_RUN=1` | 대화형 최초 실행 설정 건너뛰기 | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | 설정 후 자동 로컬 감사 건너뛰기 | -| `FAILPROOFAI_LLM_BASE_URL` | LLM 정책에서 사용하는 OpenAI 호환 엔드포인트 재정의 | -| `FAILPROOFAI_LLM_API_KEY` | LLM 정책에서 사용하는 API 키 제공 | -| `FAILPROOFAI_LLM_MODEL` | LLM 정책에서 사용할 모델 선택 | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | 사용자 정의 정책 모듈 로딩 제한 시간 설정 | -| `FAILPROOFAI__EXTRA_PATHS` | 특정 하네스의 설정된 추가 캡처 경로 대체 | -| `NO_COLOR` | 터미널 색상 출력 비활성화 | +| `FAILPROOFAI_NO_FIRST_RUN=1` | 대화형 최초 실행 설정 건너뜀 | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | 설정 후 자동 로컬 감사 건너뜀 | +| `FAILPROOFAI_LLM_BASE_URL` | LLM 정책에 사용되는 OpenAI 호환 엔드포인트 재정의 | +| `FAILPROOFAI_LLM_API_KEY` | LLM 정책에 사용되는 API 키 제공 | +| `FAILPROOFAI_LLM_MODEL` | LLM 정책에 사용되는 모델 선택 | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | 커스텀 정책 모듈 로딩 시간 제한 | +| `FAILPROOFAI_NO_DOWNLOAD=1` | 팩 및 데몬 바이너리 다운로드 거부; 설치된 항목은 계속 적용됨 | +| `FAILPROOFAI_PACK_BASE_URL` | `github.com` 대신 미러에서 팩 가져오기 | +| `FAILPROOFAI__EXTRA_PATHS` | 하나의 하니스에 대해 구성된 추가 캡처 경로 교체 | +| `NO_COLOR` | 터미널 컬러 출력 비활성화 | -`CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME`, `OPENCLAW_HOME`과 같은 에이전트별 홈 변수는 Failproof AI가 해당 하네스의 로컬 세션을 검색하는 위치를 재정의합니다. +`CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME`, `OPENCLAW_HOME` 등 에이전트별 홈 변수는 Failproof AI가 해당 하니스의 로컬 세션을 검색하는 위치를 재정의합니다. -## 머신을 안전하게 일시 중지하거나 제거하기 +## 머신 안전하게 일시 중지 또는 제거 ```bash failproofai config --pause @@ -134,7 +141,7 @@ failproofai config --status failproofai config --resume ``` -로컬 세션 일시 중지는 Cloud 관리 정책을 비활성화하지 않습니다. 롤아웃 자체에 문제가 있는 경우 Cloud 적용 워크플로를 통해 Cloud 배포를 복원하세요. +로컬 세션 일시 중지는 Cloud 관리 정책을 비활성화하지 않습니다. 롤아웃 자체가 문제인 경우 Cloud 적용 워크플로를 통해 Cloud 배포를 복원하세요. npm 패키지를 제거하기 전에 설치된 훅과 데몬을 먼저 제거하세요: @@ -144,8 +151,8 @@ failproofai uninstall --yes npm rm -g failproofai ``` -버전별 세부 정보는 `failproofai --help`를 실행하세요. +버전별 세부 사항은 `failproofai --help`를 실행하세요. - `npm rm -g failproofai` 전에 반드시 `failproofai uninstall`을 실행하세요. npm은 설치된 에이전트 훅이나 데몬 서비스를 제거하지 않습니다. + `npm rm -g failproofai` 전에 `failproofai uninstall`을 실행하세요. npm은 설치된 에이전트 훅이나 데몬 서비스를 제거하지 않습니다. \ No newline at end of file diff --git a/docs/ko/start/quickstart.mdx b/docs/ko/start/quickstart.mdx index 58f8d2e0..693d5f8c 100644 --- a/docs/ko/start/quickstart.mdx +++ b/docs/ko/start/quickstart.mdx @@ -1,12 +1,12 @@ --- title: "빠른 시작" -description: "에이전트 세션을 캡처하고, 실패를 찾아 예방하세요." +description: "에이전트 세션을 캡처하고, 실패를 찾아내고, 이를 방지하는 방법을 시작하세요." icon: "zap" --- -이 빠른 시작 가이드는 하나의 머신에서 세션을 보고하고, 감사를 실행하며, 정책을 배포하는 과정을 안내합니다. 스킬을 사용하거나 수동 단계를 따라 Failproof AI를 설정하세요. +이 빠른 시작 가이드는 하나의 머신이 세션을 보고하도록 설정하고, 감사를 실행하며, 정책을 배포하는 과정을 다룹니다. 스킬을 사용하거나 수동 단계를 따라 Failproof AI를 설정하세요. -**어떤 방법을 선택하시겠습니까?** 에이전트가 12개의 지원 [하네스](/ko/reference/harnesses) 중 하나에서 실행되는 경우 — 코딩 CLI, 또는 Hermes나 OpenClaw 같은 게이트웨이 — 아래 단계를 따르세요. Node.js 20.9 이상이 필요합니다. 에이전트에 하네스가 없다면, 추적 및 감사를 위해 [Python SDK](/ko/reference/custom-agents)로 계측한 후 [첫 번째 실패 검사 실행](/ko/start/first-audit)에서 다시 합류하세요. 이 경로에서 적용(enforcement)을 사용하려면 런타임에 훅이 필요합니다. +**어느 경로를 선택하시겠습니까?** 에이전트가 12개의 지원되는 [하네스](/ko/reference/harnesses) 중 하나에서 실행된다면 — 코딩 CLI이거나 Hermes 또는 OpenClaw 같은 게이트웨이 — 아래 단계를 따르세요. Node.js 20.9 이상이 필요합니다. 에이전트에 하네스가 없다면 [Python SDK](/ko/reference/custom-agents)로 트레이싱과 감사를 위한 계측을 수행한 후 [첫 번째 실패 점검 실행](/ko/start/first-audit)에서 다시 합류하세요. 해당 경로에서 강제 적용을 하려면 런타임에 훅이 필요합니다. @@ -16,20 +16,20 @@ icon: "zap" npx skills add FailproofAI/skills ``` - + ```text Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - 에이전트가 프로젝트를 검사하고, 관련 통합을 선택하여 설정을 수행한 다음 확인합니다. 개별 스킬 및 고급 설치 옵션은 [FailproofAI 스킬 저장소](https://github.com/FailproofAI/skills)를 참조하세요. + 에이전트가 프로젝트를 검사하고, 관련 통합을 선택하며, 설정을 수행하고 이를 확인합니다. 개별 스킬 및 고급 설치 옵션은 [FailproofAI 스킬 저장소](https://github.com/FailproofAI/skills)를 참고하세요. ## 시작하기 전에 -1. [Failproof AI 대시보드](https://app.befailproof.ai)를 열고 계정을 생성하거나 회사 이메일로 로그인하세요. -2. **관리 → 키**로 이동하여 `events:add` 및 `policies:pull` 권한이 있는 키를 생성하세요. +1. [Failproof AI 대시보드](https://app.befailproof.ai)를 열고 계정을 만들거나 업무용 이메일로 로그인하세요. +2. **Administration → Keys**로 이동하여 `events:add` 및 `policies:pull` 권한을 가진 키를 생성하세요. 3. 일회용 시크릿을 복사하여 대상 머신에 저장하세요: ```bash @@ -47,7 +47,7 @@ export FAILPROOFAI_KEY="" 세션 트랜스크립트는 기본적으로 전송됩니다. 트랜스크립트 내용 없이 훅 활동 및 정책 결정만 보고하려면 `--no-transcripts`를 추가하세요. - 이 머신에 이미 에이전트 기록이 있는 경우, 최근 7일치를 미리 보고 가져온 후 전송이 완료될 때까지 기다리세요. 새 머신에서는 이 단계를 건너뛰세요. + 이 머신에 이미 에이전트 기록이 있다면, 최근 7일치를 미리 보기하고 가져온 후 전송이 완료될 때까지 기다리세요. 새 머신에서는 이 단계를 건너뜁니다. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +55,30 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Failproof AI에서 **세션**을 열고 가져온 세션을 선택하세요. + Failproof AI에서 **Sessions**을 열고 가져온 세션을 선택하세요. - 이 단계는 Failproof AI를 하네스에 연결하고 40개의 내장 정책을 설치합니다. Failproof AI가 세션을 감사하고 에이전트에 맞는 정책을 작성하기 전에, 이를 사용하여 로컬 정책 결정을 확인하고 적용을 시험해 볼 수 있습니다. + 이 단계에서는 Failproof AI를 하네스에 연결하고 39개의 내장 정책을 설치합니다. 이를 활용하여 로컬 정책 결정을 확인하고, Failproof AI가 세션을 감사하여 에이전트를 위한 정책을 작성하기 전에 강제 적용을 시도해 볼 수 있습니다. - 설치 프로그램이 하네스를 자동으로 감지하도록 하거나, 명시적으로 지정할 수 있습니다. 12개 하네스 모두 유효한 `--cli` 값입니다 — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + 설치 프로그램이 하네스를 자동으로 감지하게 하거나 명시적으로 지정할 수 있습니다. 12개 모두 유효한 `--cli` 값입니다 — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash failproofai policies --install --cli claude --scope user # 코딩 CLI failproofai policies --install --cli hermes --scope user # Slack/Telegram 게이트웨이 ``` - 실행 전 도구 호출 차단은 12개 모두에서 검증되었습니다. 턴 종료 게이트는 8개에서 검증되었으며, 하네스별 매트릭스는 [적용 기능](/ko/reference/harnesses#enforcement-capability)을 참조하세요. + 실행 전 툴 호출 차단은 12개 모두에서 검증되었습니다. 턴 종료 게이트는 8개에서 검증되었습니다 — 하네스별 매트릭스는 [강제 적용 기능](/ko/reference/harnesses#enforcement-capability)을 참고하세요. - [첫 번째 실패 검사 실행](/ko/start/first-audit)을 따르세요. "에이전트가 접근 방식을 바꾸지 않고 실패한 도구를 재시도한 세션 찾기"와 같이 구체적인 목표를 사용하세요. + [첫 번째 실패 점검 실행](/ko/start/first-audit)을 따르세요. "에이전트가 접근 방식을 바꾸지 않고 실패한 툴을 재시도한 세션 찾기"와 같이 구체적인 목표를 사용하세요. - - [정책으로 첫 번째 실패 예방](/ko/start/first-policy)을 따르세요. 관찰 모드로 시작하여 매칭 항목을 검토한 후, 검토된 버전을 적용하세요. + + [정책으로 첫 번째 실패 방지](/ko/start/first-policy)를 따르세요. 관찰 모드에서 시작하여 일치 항목을 검사한 후, 검토된 버전으로 강제 적용하세요. - `failproofai config --status`를 실행하세요. 정상적인 설정은 클라우드 연결 상태, 데몬 상태, 적용이 일시 중지되었는지 여부를 보고합니다. + `failproofai config --status`를 실행하세요. 정상적인 설정은 클라우드 연결, 데몬 상태, 강제 적용 일시 정지 여부를 보고합니다. \ No newline at end of file diff --git a/docs/pt-br/policies/builtin-catalog.mdx b/docs/pt-br/policies/builtin-catalog.mdx index 2a403174..0960bdae 100644 --- a/docs/pt-br/policies/builtin-catalog.mdx +++ b/docs/pt-br/policies/builtin-catalog.mdx @@ -1,51 +1,55 @@ --- title: "Catálogo de políticas integradas" -description: "Consulte todas as políticas integradas do Failproof AI, seus gatilhos, estado recomendado e parâmetros configuráveis." +description: "Revise cada política integrada do Failproof AI, seu gatilho, estado recomendado e parâmetros configuráveis." icon: "list-checks" --- -O pacote instalado é a fonte de verdade para disponibilidade de políticas. Execute `failproofai policies` após cada atualização, pois entradas do catálogo e comportamentos podem mudar com a versão do pacote. +O pacote instalado é a fonte de verdade para a disponibilidade das políticas. Execute `failproofai policies` após cada atualização, pois as entradas do catálogo e o comportamento podem mudar com a versão do pacote. -## Baseline recomendado +## Linha de base recomendada -A seleção recomendada pela configuração guiada habilita atualmente sanitizadores de segredos, proteções de ambiente, autoproteção, bloqueios de comandos catastróficos e segurança de branches protegidos: +A seleção recomendada pelo assistente de configuração guiada habilita atualmente sanitizadores de segredos, proteções de ambiente, autoproteção, proteções contra comandos catastróficos e segurança de branches protegidas: ```text sanitize-jwt sanitize-api-keys sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars block-env-files block-secrets-write -block-self-pause block-failproofai-commands -block-sudo block-curl-pipe-sh -block-rm-rf block-push-master -block-force-push +block-failproofai-commands block-sudo +block-curl-pipe-sh block-rm-rf +block-push-master block-force-push ``` -O recomendado é deliberadamente mais restrito do que **Tudo**. Políticas de infraestrutura e fluxo de trabalho podem interromper trabalhos válidos e devem ser habilitadas apenas nos repositórios e máquinas que realmente precisam delas. +`block-failproofai-commands` está **sempre ativo**. Ele aparece acima apenas +por completude, mas se registra em toda avaliação independentemente de constar +no seu conjunto habilitado, e não pode ser desabilitado ou pausado — uma +proteção contra o agente que desativa a fiscalização que o próprio agente pode +desativar não é uma proteção. + +O conjunto recomendado é deliberadamente mais restrito do que **Tudo**. Políticas de infraestrutura e fluxo de trabalho podem interromper tarefas válidas e devem ser habilitadas apenas para os repositórios e máquinas que delas necessitem. ## Segredos e ambiente | Política | Gatilho | Resultado | | --- | --- | --- | -| `sanitize-jwt` | `PostToolUse` | Oculta JWTs da saída da ferramenta antes que o modelo os veja. | -| `sanitize-api-keys` | `PostToolUse` | Oculta chaves comuns de OpenAI, Anthropic, GitHub, AWS, Stripe e Google. | -| `sanitize-connection-strings` | `PostToolUse` | Oculta strings de conexão de banco de dados que contêm credenciais. | -| `sanitize-private-key-content` | `PostToolUse` | Oculta corpos de chaves privadas PEM. | -| `sanitize-bearer-tokens` | `PostToolUse` | Oculta tokens bearer de autorização. | +| `sanitize-jwt` | `PostToolUse` | Redige JWTs da saída da ferramenta antes que o modelo os veja. | +| `sanitize-api-keys` | `PostToolUse` | Redige chaves comuns de OpenAI, Anthropic, GitHub, AWS, Stripe e Google. | +| `sanitize-connection-strings` | `PostToolUse` | Redige strings de conexão de banco de dados que contenham credenciais. | +| `sanitize-private-key-content` | `PostToolUse` | Redige conteúdos de chaves privadas PEM. | +| `sanitize-bearer-tokens` | `PostToolUse` | Redige tokens de autorização bearer. | | `protect-env-vars` | `PreToolUse` em ferramentas de shell | Bloqueia comandos que expõem variáveis de ambiente. | | `block-env-files` | `PreToolUse` | Bloqueia leituras e escritas de arquivos `.env`. | -| `block-read-outside-cwd` | `PreToolUse` em ferramentas de leitura, glob, grep ou shell | Mantém as leituras dentro do diretório de trabalho da sessão. | -| `block-secrets-write` | `PreToolUse` em ferramentas de escrita | Bloqueia escritas em nomes de arquivo comuns de chaves secretas e credenciais. | +| `block-read-outside-cwd` | `PreToolUse` em ferramentas de leitura, glob, grep ou shell | Restringe leituras ao diretório de trabalho da sessão. | +| `block-secrets-write` | `PreToolUse` em ferramentas de escrita | Bloqueia escritas em nomes de arquivos comuns de chaves secretas e credenciais. | ## Comandos perigosos e infraestrutura | Política | Gatilho | Resultado | | --- | --- | --- | -| `block-self-pause` | `PreToolUse`, `PermissionRequest` | Impede que um agente pause sua própria aplicação de regras. | -| `block-sudo` | `PreToolUse`, `PermissionRequest` | Bloqueia `sudo`, a menos que um padrão de permissão corresponda. | +| `block-sudo` | `PreToolUse`, `PermissionRequest` | Bloqueia `sudo` a menos que um padrão de permissão corresponda. | | `block-curl-pipe-sh` | `PreToolUse` | Bloqueia scripts baixados e redirecionados diretamente para um shell. | | `block-rm-rf` | `PreToolUse` | Bloqueia padrões de exclusão recursiva catastrófica. | -| `block-failproofai-commands` | `PreToolUse` | Impede que agentes alterem ou desinstalarem o Failproof AI. | +| `block-failproofai-commands` | `PreToolUse`, `PermissionRequest` | **Sempre ativo, não pode ser desabilitado.** Bloqueia toda invocação da CLI do Failproof AI, autopausas e desinstalações via gerenciador de pacotes. | | `block-kubectl` | `PreToolUse` | Controla comandos do Kubernetes. | | `block-terraform` | `PreToolUse` | Controla comandos do Terraform e OpenTofu. | | `block-aws-cli` | `PreToolUse` | Controla comandos da AWS CLI. | @@ -58,36 +62,36 @@ O recomendado é deliberadamente mais restrito do que **Tudo**. Políticas de in | Política | Gatilho | Resultado | | --- | --- | --- | -| `block-push-master` | `PreToolUse` | Bloqueia pushes diretos para branches protegidos configurados. | +| `block-push-master` | `PreToolUse` | Bloqueia pushes diretos para branches protegidas configuradas. | | `block-force-push` | `PreToolUse` | Bloqueia force-pushes; `--force-with-lease` permanece permitido pela implementação atual. | -| `block-work-on-main` | `PreToolUse` | Bloqueia commits e merges em branches protegidos. | +| `block-work-on-main` | `PreToolUse` | Bloqueia commits e merges em branches protegidas. | | `warn-git-amend` | `PreToolUse` | Avisa antes de reescrever um commit com `--amend`. | | `warn-git-stash-drop` | `PreToolUse` | Avisa antes de descartar ou limpar stashes permanentemente. | -| `warn-all-files-staged` | `PreToolUse` | Avisa em uso amplo de `git add -A`, `git add .` ou `git add --all`. | -| `warn-destructive-sql` | `PreToolUse` | Avisa em comandos `DROP`, `TRUNCATE` e `DELETE` sem `WHERE` em clientes de banco de dados reconhecidos. | -| `warn-schema-alteration` | `PreToolUse` | Avisa em operações reconhecidas de `ALTER TABLE` para colunas e renomeações. | +| `warn-all-files-staged` | `PreToolUse` | Avisa em `git add -A`, `git add .` ou `git add --all` abrangentes. | +| `warn-destructive-sql` | `PreToolUse` | Avisa sobre `DROP`, `TRUNCATE` e `DELETE` sem `WHERE` em clientes de banco de dados reconhecidos. | +| `warn-schema-alteration` | `PreToolUse` | Avisa sobre operações reconhecidas de `ALTER TABLE` em colunas e renomeações. | -## Pacotes, comportamento do sistema e loops de agentes +## Pacotes, comportamento do sistema e loops do agente | Política | Gatilho | Resultado | | --- | --- | --- | | `warn-package-publish` | `PreToolUse` | Avisa antes de publicar em registros de pacotes. | | `warn-global-package-install` | `PreToolUse` | Avisa antes de instalar pacotes globalmente. | | `prefer-package-manager` | `PreToolUse` | Instrui o agente a usar um gerenciador de pacotes permitido. | -| `warn-large-file-write` | `PreToolUse` em ferramentas de escrita | Avisa acima do limite de tamanho de arquivo configurado. | -| `warn-background-process` | `PreToolUse` | Avisa em padrões de processos em segundo plano desanexados ou de longa duração. | -| `warn-repeated-tool-calls` | `PreToolUse` | Avisa após três ou mais chamadas de ferramenta idênticas. | +| `warn-large-file-write` | `PreToolUse` em ferramentas de escrita | Avisa quando o tamanho do arquivo ultrapassa o limite configurado. | +| `warn-background-process` | `PreToolUse` | Avisa sobre padrões de processos em segundo plano desacoplados ou de longa duração. | +| `warn-repeated-tool-calls` | `PreToolUse` | Avisa após três ou mais chamadas idênticas de ferramentas. | -## Fluxo de trabalho ao fim da tarefa +## Fluxo de trabalho de fim de tarefa -Estas políticas exigem um harness que emita um evento `Stop` compatível. +Estas políticas requerem um harness que emita um evento `Stop` compatível. | Política | Resultado | | --- | --- | | `require-commit-before-stop` | Recusa a conclusão enquanto houver trabalho rastreado sem commit. | | `require-push-before-stop` | Recusa a conclusão enquanto houver commits apenas locais. | | `require-pr-before-stop` | Exige um pull request para o branch atual. | -| `require-no-conflicts-before-stop` | Exige um merge limpo com o branch base configurado. | +| `require-no-conflicts-before-stop` | Exige um merge limpo contra o branch base configurado. | | `require-ci-green-before-stop` | Exige que as verificações de CI do HEAD atual sejam concluídas com sucesso. | ## Referência de parâmetros diff --git a/docs/pt-br/policies/failure-behavior.mdx b/docs/pt-br/policies/failure-behavior.mdx index 9dbdeae9..1526b902 100644 --- a/docs/pt-br/policies/failure-behavior.mdx +++ b/docs/pt-br/policies/failure-behavior.mdx @@ -1,10 +1,10 @@ --- -title: "Comportamento em caso de falha" +title: "Comportamento em falhas" description: "Entenda o que acontece quando a avaliação de políticas ou o daemon local está indisponível." icon: "shield-alert" --- -O Failproof AI é projetado para que uma falha de aplicação seja visível, em vez de permitir silenciosamente trabalhos de risco. +O Failproof AI é projetado para que uma falha de execução seja visível, em vez de permitir silenciosamente trabalhos de risco. ## Diagnosticar um bloqueio por falha fechada @@ -13,7 +13,7 @@ O Failproof AI é projetado para que uma falha de aplicação seja visível, em 1. Acesse **Admin → enforcement** e abra a máquina. 2. Verifique o último check-in, o deployment atribuído e o deployment reportado. 3. Acesse **Observe → policy** e abra a sessão da decisão negada. - 4. Confirme se o motivo indica inacessibilidade do daemon, incompatibilidade de versão ou a própria política. + 4. Confirme se o motivo indica inacessibilidade do daemon, divergência de versão ou a própria política. @@ -27,9 +27,9 @@ O Failproof AI é projetado para que uma falha de aplicação seja visível, em -Em uma máquina configurada para usar `failproofaid`, o daemon é o único avaliador. Se ele estiver inacessível ou se a versão do protocolo não corresponder à do CLI, a avaliação do hook falha de forma fechada. A ação é negada com um motivo que orienta o operador a verificar ou atualizar o daemon. +Em uma máquina configurada para usar `failproofaid`, o daemon é o único avaliador. Se ele estiver inacessível ou se a versão do protocolo não corresponder à da CLI, a avaliação do hook falha de forma fechada. A ação é negada com um motivo que orienta o operador a verificar ou atualizar o daemon. -Antes da configuração do daemon, os hooks avaliam as políticas no processo. Uma vez que a configuração do daemon é registrada, o Failproof AI não recorre silenciosamente a um segundo avaliador quando o daemon falha. +Antes da configuração do daemon, os hooks avaliam as políticas em processo. Uma vez que a configuração do daemon é registrada, o Failproof AI não recorre silenciosamente a um segundo avaliador quando o daemon falha. ## Responder a uma decisão por falha fechada @@ -39,5 +39,29 @@ Antes da configuração do daemon, os hooks avaliam as políticas no processo. U 4. Retome o trabalho do agente somente após confirmar que o caminho de avaliação de políticas está saudável. - Não tente repetidamente a ação bloqueada. Uma resposta por falha fechada significa que o sistema não conseguiu estabelecer que a ação era segura. - \ No newline at end of file + Não tente repetir a ação bloqueada várias vezes. Uma resposta por falha fechada significa que o sistema não conseguiu confirmar que a ação era segura. + + +## Um pack não carrega + +Uma máquina que foi instruída a aplicar um pack e não consegue executá-lo nega a ação em vez de continuar silenciosamente. O gatilho é uma **expectativa registrada**, nunca uma vazia: uma máquina sem packs instalados fica em silêncio, enquanto um pack declarado que não resolve — ou que registra menos do que seu manifesto declara — nega. + +A negação é **específica**, ao contrário de um daemon inacessível. Um daemon que não pode ser alcançado significa que nenhuma avaliação ocorreu, portanto nada pode ser considerado seguro. Um pack que não carrega tem um conjunto enumerável de guardas ausentes, pois cada política declarada carrega seu próprio `match` — portanto, ele nega apenas os eventos e ferramentas cobertos por essas políticas, e tudo o mais prossegue normalmente. + +Ele não é acionado para: + +- um pack `observe`, que avalia e descarta por construção +- políticas que você nunca adotou ou desativou explicitamente +- um pack que o loader nunca recebeu, onde "sem registros" não pode ser distinguido de um salto deliberado +- uma pausa de sessão ativa +- um timeout de carregamento, que é transitório — um momento lento de disco não deve negar até que um humano intervenha + +`UserPromptSubmit` **instrui** em vez de negar, independentemente do que a política ausente declarava. Uma negação genérica a incluiria e bloquearia o acesso ao agente que poderia resolver o problema. + +### O que fazer + +```bash +failproofai pack list +``` + +O comando nomeia qualquer pack instalado que não carrega, informa o motivo e encerra com código não zero. Em seguida, reinstale-o (`failproofai pack add `) ou remova-o (`failproofai pack remove `) — removê-lo cancela a expectativa, e a negação cessa junto com ela. \ No newline at end of file diff --git a/docs/pt-br/policies/packs.mdx b/docs/pt-br/policies/packs.mdx new file mode 100644 index 00000000..0b35ebfe --- /dev/null +++ b/docs/pt-br/policies/packs.mdx @@ -0,0 +1,110 @@ +--- +title: "Policy packs" +description: "Instale um conjunto de políticas publicado como uma release do GitHub e gerencie o que ele aplica." +icon: "package" +--- + +Um pack é um conjunto de políticas publicado como uma release do GitHub. Um único comando o instala, os checksums da própria release são verificados antes de qualquer execução, e o digest é registrado para que o pack não possa ser alterado na sua máquina depois disso. + +## Instalar as políticas do Failproof AI + +```bash +failproofai pack add core +``` + +Isso instala o conjunto que publicamos, a partir da cópia incluída no pacote — portanto, não precisa de rede e não falha por causa de um proxy. Instale apenas uma parte: + +```bash +failproofai pack add core --policy block-rm-rf # uma, ou algumas separadas por vírgula +failproofai pack add core --category dangerous-commands # uma categoria inteira +failproofai pack add core --all # tudo que ele contém +``` + +`failproofai pack list` lista todas as categorias que o pack oferece. + +## Ver o conteúdo de um pack antes de instalá-lo + +```bash +failproofai pack list acme/support-agent +``` + +Lista todas as políticas que o pack contém, agrupadas por categoria, indicando quais o autor ativa por padrão e quais são opt-in. Ele lê **apenas o manifesto** — o artefato de entrada nunca é baixado nem importado, portanto inspecionar o pack de um desconhecido não executa código de desconhecidos. O manifesto ainda é verificado contra o `SHA256SUMS` da própria release, então o que você está lendo é exatamente o que seria instalado. + +`failproofai pack list` sem nenhuma fonte lista os packs já instalados localmente. + +## Instalar o pack de outra pessoa + +```bash +failproofai pack add acme/support-agent +``` + +Qualquer um destes formatos funciona — use o que você tiver: + +| Fonte | Resultado | +| --- | --- | +| `acme/support-agent` | Release mais recente, **fixada** na tag exata que foi resolvida | +| `acme/support-agent@v2.1.0` | Essa release | +| `github:acme/support-agent@v2.1.0` | O mesmo, escrito explicitamente | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | O mesmo, copiado do navegador | + +Não informar uma tag instala a release mais recente **e a fixa**, informando qual tag foi escolhida. O que fica registrado sempre nomeia exatamente uma release, portanto uma reinstalação não pode resultar em uma versão diferente. + +## Usar apenas parte de um pack + +Por padrão, você recebe os **próprios** padrões do pack — as políticas que o autor marcou como seguras para ativar sem supervisão — e não tudo que ele contém. + +```bash +failproofai pack add acme/support-agent --category billing,git +failproofai pack add acme/support-agent --policy block-refunds +failproofai pack add acme/support-agent --all +``` + +`--category` e `--policy` se combinam como uma união (`--only` é aceito como sinônimo de `--policy`). Ao adicionar novamente em uma versão mais recente, o que você escolheu anteriormente é mantido em vez de reativar todo o restante. + +## Gerenciar o que está ativo + +```bash +failproofai policies # toda fonte em uma lista, packs incluídos +failproofai pack list # apenas packs, agrupados por categoria +failproofai policies --uninstall block-refunds # desativar uma política de pack +failproofai policies --install block-refunds # e reativar +failproofai pack remove acme/support-agent +``` + +Um nome simples refere-se ao **builtin** quando existe um com esse nome. Nomeie explicitamente a cópia de um pack quando necessário: + +```bash +failproofai policies --uninstall acme/support-agent:block-refunds +``` + + +Se um pack incluir uma política cujo nome também é um **builtin ativado**, o builtin é executado e a cópia do pack é ignorada — caso contrário, a mesma verificação seria avaliada duas vezes. Desative o builtin para usar a cópia do pack no lugar dele. + + +## De onde vêm as políticas do Failproof AI + +`core` lê a cópia incluída no pacote npm. O mesmo conjunto é publicado como uma release do GitHub, que é o que você instala quando quer uma versão específica: + +```bash +failproofai pack add core # deste pacote, sem rede +failproofai pack add FailproofAI/policies # o mesmo conjunto, da release do GitHub +``` + +## O que a integridade garante e o que não garante + +O `SHA256SUMS` é distribuído na mesma release que o artefato, portanto **não** é uma assinatura e não prova nada sobre quem o publicou. O que ele prova é que os bytes são os mesmos que aquela release publicou — e como o digest é registrado quando você adiciona o pack e re-verificado antes de cada importação, um pack não pode ser alterado na sua máquina depois disso. Um repositório que muda a tag ou substitui um asset para de carregar em vez de executar silenciosamente algo diferente. + +No momento da instalação, o pack também é **importado uma vez** e verificado contra seu próprio manifesto. Um pack cujo artefato não seja parseável, ou que registre algo diferente do que declara, é recusado antes que qualquer coisa seja ativada — em vez de instalar corretamente e falhar na sua próxima chamada de ferramenta. + +## Quando um pack não carrega + +Um pack que esta máquina foi instruída a aplicar e que não consegue executar **bloqueia** os eventos que suas políticas ausentes cobriam, em vez de permitir silenciosamente. Consulte [Comportamento em caso de falha](/pt-br/policies/failure-behavior). `failproofai pack list` identifica qualquer pack nesse estado e encerra com código não-zero. + +## Offline e espelhos + +| Variável | Efeito | +| --- | --- | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Recusa buscar dados; packs já instalados continuam sendo aplicados | +| `FAILPROOFAI_PACK_BASE_URL` | Direciona a busca de packs para um espelho em vez de `github.com` | + +Para publicar seu próprio pack, consulte [Publicar um pack](/pt-br/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/pt-br/policies/publish-a-pack.mdx b/docs/pt-br/policies/publish-a-pack.mdx new file mode 100644 index 00000000..17667dc5 --- /dev/null +++ b/docs/pt-br/policies/publish-a-pack.mdx @@ -0,0 +1,91 @@ +--- +title: "Publicar um pack" +description: "Distribua suas próprias políticas como um release do GitHub que qualquer pessoa pode instalar." +icon: "upload" +--- + +Um pack é composto por três arquivos anexados a um release do GitHub. O comando `failproofai pack build` gera os três a partir de um arquivo de políticas que você já possui. + +## 1. Escreva as políticas + +Um único arquivo, usando a mesma API de qualquer política customizada. Dois campos extras são importantes para um pack: + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-refunds", + description: "Refunds above the approved limit need a human", + category: "Billing", // groups it, and is what --category selects on + defaultEnabled: true, // switched on by a plain `pack add` + match: { events: ["PreToolUse"], tools: ["Bash"] }, + fn: async (ctx) => + String(ctx.toolInput?.command ?? "").includes("refund") + ? deny("Refunds need a human. Ask before running this.") + : allow(), +}); +``` + +`defaultEnabled` é **false** por padrão quando omitido. Um `failproofai pack add` simples ativa apenas o que você marcou — instalar todas as políticas de um desconhecido de forma automática não é uma decisão que o instalador deve tomar pelo usuário. + + +O entry deve ser **um único arquivo autocontido**. Apenas o entry recebe o pin de digest, então um pack que importa arquivos locais não poderia honestamente afirmar que o digest cobre o que é executado. Faça o bundle primeiro (`esbuild`, `bun build`, `rollup`) e construa o pack a partir do bundle — o `pack build` recusa uma importação local em vez de fazer uma promessa que não pode cumprir. + + +## 2. Construa os assets do release + +```bash +failproofai pack build ./policies.mjs \ + --id acme/support-agent \ + --version 1.0.0 \ + --out ./dist-pack +``` + +O comando gera três arquivos e valida cada política com as **próprias regras do loader** antes — assim, um pack que nunca poderia ser instalado falha aqui, onde você pode corrigir: + +| Arquivo | O que é | +| --- | --- | +| `failproofai-pack.json` | O manifesto: id, versão, efeito e uma entrada por política | +| `failproofai-pack.mjs` | Seu entry, literalmente | +| `SHA256SUMS` | ` ` para os outros dois | + +São recusados em tempo de build: um id que não seja `publisher/name`, um nome de política contendo `/`, uma política declarando `alwaysOn`, uma `description`, `category` ou `match` ausentes, um entry que não registra nada, e um entry que importa arquivos locais. + +## 3. Anexe ao release + +Crie a tag do release com a mesma versão que você usou no build e anexe os três arquivos como assets do release: + +```bash +gh release create 1.0.0 \ + ./dist-pack/failproofai-pack.json \ + ./dist-pack/failproofai-pack.mjs \ + ./dist-pack/SHA256SUMS +``` + +Agora qualquer pessoa pode instalá-lo: + +```bash +failproofai pack add acme/support-agent +``` + +Os nomes dos assets são fixos — são eles que a CLI do consumidor usa para construir suas URLs, sem chamadas de API nem descoberta automática. + +## Lançando uma nova versão + +Faça o build com o novo `--version`, crie um novo release com a tag correspondente e anexe os três assets novamente. Os consumidores executam o mesmo `pack add` e mantêm o subconjunto de políticas que haviam escolhido; uma política que foi desativada permanece desativada após a atualização. + +Alterar o **nome** de uma política é uma breaking change: uma máquina que havia desativado esse nome está desativando um nome que não existe mais, e o novo nome chega com o valor que `defaultEnabled` define. + +## O que seus usuários estão confiando + +O `SHA256SUMS` fica no mesmo release que o artefato, portanto prova que os bytes são os que você publicou — mas não quem você é. Quem pode escrever no repositório pode escrever ambos os arquivos. A proteção dos seus usuários está no fato de que o digest é fixado no momento da instalação, então o que você publicou não pode ser alterado depois. + +Publique a partir de um repositório cujo acesso de escrita você controla e trate um release de pack como a publicação de um pacote. + +## Observe antes de aplicar + +Um manifesto pode declarar `"effect": "observe"`. Essas políticas são executadas e seus vereditos são **registrados e descartados** — nada é bloqueado. É a forma de medir uma nova regra com tráfego real antes que ela possa interromper o trabalho de alguém. + +```json +{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +``` \ No newline at end of file diff --git a/docs/pt-br/reference/failproof-cli.mdx b/docs/pt-br/reference/failproof-cli.mdx index 253b4699..c19a5034 100644 --- a/docs/pt-br/reference/failproof-cli.mdx +++ b/docs/pt-br/reference/failproof-cli.mdx @@ -6,7 +6,7 @@ icon: "terminal" Instale o CLI local com `npm install -g failproofai`. Execute sem argumentos para abrir o painel de políticas local. -O pacote requer Node.js 20.9 ou superior. Bun 1.3 ou superior é suportado para desenvolvimento e instalações a partir do código-fonte. `failproofai configure` e `failproofai setup` são aliases de `failproofai config`; `failproofai p` é um alias de `failproofai policies`. +O pacote requer Node.js 20.9 ou mais recente. Bun 1.3 ou mais recente é compatível para desenvolvimento e instalações a partir do código-fonte. `failproofai configure` e `failproofai setup` são aliases de `failproofai config`; `failproofai p` é um alias de `failproofai policies`. ## Configurar uma máquina @@ -24,56 +24,61 @@ Execute `failproofai` sem argumentos para abrir o painel de políticas local. | Comando | Resultado | | --- | --- | -| `failproofai config` | Executa a configuração interativa da máquina | -| `failproofai config --connect --token ` | Conecta a ingestão Cloud e a entrega de políticas | -| `failproofai config --status` | Exibe o estado de conexão, daemon, entrega e pausa | -| `failproofai policies` | Lista as políticas internas e personalizadas | -| `failproofai policies --install` | Instala os hooks e ativa as políticas | -| `failproofai policy add ` | Ativa uma política interna | -| `failproofai policy remove ` | Desativa uma política interna | -| `failproofai policies --uninstall` | Desativa políticas ou remove os hooks do harness | -| `failproofai audit` | Escaneia o histórico local do agente e abre a visualização de auditoria local | -| `failproofai audit --schedule [days] --email
` | Agenda varreduras locais recorrentes e envia os resultados por e-mail | -| `failproofai audit --status` | Exibe o endereço de relatório, o intervalo e a próxima varredura agendada | -| `failproofai audit --no-schedule` | Interrompe as varreduras recorrentes sem excluir o histórico de auditoria | -| `failproofai harness list` | Lista os caminhos de captura adicionais | -| `failproofai flush --wait` | Entrega o spool de eventos atual | -| `failproofai backfill --since 30d` | Relê o histórico processado anteriormente | -| `failproofai config --pause [duration]` | Pausa uma sessão local por 30 minutos por padrão, com limite de 8 horas | -| `failproofai config --resume` | Retoma uma sessão local pausada; adicione `--all` para limpar todas as pausas | -| `failproofai update` | Conclui as migrações do pacote e atualiza o daemon | -| `failproofai migrate --dry-run` | Pré-visualiza ou executa as migrações pendentes do layout home | -| `failproofai uninstall` | Remove os hooks e o daemon antes de remover o pacote | -| `failproofai --version` | Exibe a versão do pacote instalado | -| `failproofai --help` | Exibe os comandos e o uso global | +| `failproofai config` | Executar a configuração interativa da máquina | +| `failproofai config --connect --token ` | Conectar a ingestão e a entrega de políticas do Cloud | +| `failproofai config --status` | Exibir estado de conexão, daemon, entrega e pausa | +| `failproofai policies` | Listar políticas integradas, personalizadas, de convenção, de pack e gerenciadas pelo Cloud | +| `failproofai policies --install` | Instalar hooks e habilitar políticas | +| `failproofai policy add ` | Habilitar uma política — integrada, ou `:` de um pack instalado | +| `failproofai policy remove ` | Desabilitar uma política, mesma nomenclatura | +| `failproofai policies --uninstall` | Desabilitar políticas ou remover os hooks do harness | +| `failproofai pack list` | Listar packs de políticas instalados e todas as políticas que cada um contém | +| `failproofai pack add ` | Instalar um pack de políticas a partir de uma release do GitHub; sem tag, usa a mais recente e a fixa | +| `failproofai pack add --bundled` | Instalar as políticas integradas como um pack, a partir deste pacote, sem necessidade de rede | +| `failproofai pack build ` | Compilar os três artefatos de release para um pack próprio | +| `failproofai pack remove ` | Desativar um pack instalado | +| `failproofai audit` | Escanear o histórico local do agente e abrir a visualização de auditoria local | +| `failproofai audit --schedule [days] --email
` | Agendar varreduras locais recorrentes e enviar os resultados por e-mail | +| `failproofai audit --status` | Exibir o endereço do relatório, o intervalo e a próxima varredura agendada | +| `failproofai audit --no-schedule` | Interromper varreduras recorrentes sem excluir o histórico de auditoria | +| `failproofai harness list` | Listar caminhos de captura adicionais | +| `failproofai flush --wait` | Entregar o spool de eventos atual | +| `failproofai backfill --since 30d` | Reler o histórico processado anteriormente | +| `failproofai config --pause [duration]` | Pausar uma sessão local por 30 minutos por padrão, por até 8 horas | +| `failproofai config --resume` | Retomar uma sessão local pausada; adicione `--all` para limpar todas as pausas | +| `failproofai update` | Concluir migrações do pacote e atualizar o daemon | +| `failproofai migrate --dry-run` | Visualizar ou executar migrações de layout pendentes no diretório home | +| `failproofai uninstall` | Remover hooks e o daemon antes de desinstalar o pacote | +| `failproofai --version` | Exibir a versão do pacote instalado | +| `failproofai --help` | Mostrar comandos e uso global | ## Flags de configuração | Flag | Uso | | --- | --- | -| `--connect --token ` | Conecta sem interação | -| `--machine-id ` | Define o ID estável da máquina | -| `--machine-label ` | Define ou altera o rótulo no painel | -| `--no-transcripts` | Envia decisões sem o conteúdo do transcript | -| `--disconnect` | Interrompe os pulls de política e a entrega de eventos do Cloud | -| `--status` | Exibe o estado atual da máquina | -| `--pause [duration]` | Pausa a sessão mais recente no diretório atual; aceita segundos, minutos ou horas e tem padrão de 30 minutos | -| `--resume` | Encerra antecipadamente uma pausa correspondente | -| `--session ` | Direciona uma sessão específica para pausar ou retomar | -| `--all` | Com `--resume`, encerra todas as pausas ativas | +| `--connect --token ` | Conectar de forma não interativa | +| `--machine-id ` | Definir o ID estável da máquina | +| `--machine-label ` | Definir ou alterar o rótulo do painel | +| `--no-transcripts` | Enviar decisões sem o conteúdo da transcrição | +| `--disconnect` | Interromper as atualizações de políticas e a entrega de eventos do Cloud | +| `--status` | Exibir o estado atual da máquina | +| `--pause [duration]` | Pausar a sessão mais recente no diretório atual; aceita segundos, minutos ou horas e tem como padrão 30 minutos | +| `--resume` | Encerrar uma pausa correspondente antecipadamente | +| `--session ` | Especificar uma sessão explícita para pausar ou retomar | +| `--all` | Com `--resume`, encerrar todas as pausas ativas | -Pausas locais suspendem as políticas internas, personalizadas e de convenção para uma sessão. Elas sempre expiram e não desativam as políticas gerenciadas pelo Cloud. `block-self-pause` impede que um agente instrumentado utilize essa brecha por conta própria. +Pausas locais suspendem políticas integradas, personalizadas, de convenção e de pack para uma sessão. Elas sempre expiram e não desabilitam políticas gerenciadas pelo Cloud. `block-failproofai-commands` — que está sempre ativo e não pode ser desabilitado ou pausado — impede que um agente instrumentado use este mecanismo de escape por conta própria. -## Flags de política +## Flags de políticas | Flag | Uso | | --- | --- | -| `--install`, `-i` | Ativa as políticas e instala os hooks do harness | -| `--uninstall`, `-u` | Desativa as políticas ou remove os hooks | -| `--cli ` | Direciona um ou mais harnesses suportados | -| `--scope user\|project\|local\|all` | Escolhe o escopo de configuração; `all` é usado para desinstalação | -| `--beta` | Inclui políticas beta | -| `--custom`, `-c ` | Valida e carrega um arquivo de política personalizado; repetível | +| `--install`, `-i` | Habilitar políticas e instalar hooks do harness | +| `--uninstall`, `-u` | Desabilitar políticas ou remover hooks | +| `--cli ` | Especificar um ou mais harnesses compatíveis | +| `--scope user\|project\|local\|all` | Escolher o escopo de configuração; `all` é para desinstalação | +| `--beta` | Incluir políticas beta | +| `--custom`, `-c ` | Validar e carregar um arquivo de política personalizado; pode ser repetido | ## Flags de entrega e manutenção @@ -85,7 +90,7 @@ Pausas locais suspendem as políticas internas, personalizadas e de convenção | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` deve ser executado após `npm install -g failproofai@latest`; ele realiza as migrações do layout home, instala o binário do daemon correspondente e reinicia o serviço. `--no-daemon` executa apenas a migração do layout. +`failproofai update` deve ser executado após `npm install -g failproofai@latest`; ele realiza migrações de layout do diretório home, instala o binário do daemon correspondente e reinicia o serviço. `--no-daemon` executa apenas a migração de layout. ## Caminhos do harness @@ -95,9 +100,9 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -Os nomes de harness suportados são `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` e `goose`. +Os nomes de harness compatíveis são `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` e `goose`. -Labels criam namespaces para IDs de agentes derivados quando duas raízes contêm cópias do mesmo projeto. Raízes sobrepostas e labels duplicados são rejeitados para evitar coleta duplicada ou corrupção de cursor. A configuração de caminhos extras é recarregada sem reiniciar o daemon. +Rótulos criam namespaces para IDs de agentes derivados quando duas raízes contêm cópias do mesmo projeto. Raízes sobrepostas e rótulos duplicados são rejeitados para evitar coleta duplicada ou corrupção de cursor. A configuração de caminhos extras é recarregada sem reiniciar o daemon. Ambientes de contêiner podem substituir os caminhos extras configurados em arquivo por uma variável separada por vírgulas chamada `FAILPROOFAI__EXTRA_PATHS`, por exemplo: @@ -111,20 +116,22 @@ Use arquivos de configuração para comportamento persistente da máquina. Vari | Variável | Uso | | --- | --- | -| `FAILPROOFAI_HOME` | Reposiciona o layout completo do `~/.failproofai` | -| `FAILPROOFAI_LOG_LEVEL` | Define o nível de verbosidade do log local | -| `FAILPROOFAI_HOOK_LOG_FILE` | Grava diagnósticos do hook em um arquivo específico | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Desativa a telemetria anônima para este processo | -| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignora a configuração interativa de primeira execução | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Ignora a auditoria local pós-configuração | -| `FAILPROOFAI_LLM_BASE_URL` | Substitui o endpoint compatível com OpenAI usado pelas políticas de LLM | -| `FAILPROOFAI_LLM_API_KEY` | Fornece a chave de API usada pelas políticas de LLM | -| `FAILPROOFAI_LLM_MODEL` | Seleciona o modelo usado pelas políticas de LLM | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limita o tempo de carregamento do módulo de política personalizado | -| `FAILPROOFAI__EXTRA_PATHS` | Substitui os caminhos de captura extras configurados para um harness | -| `NO_COLOR` | Desativa a saída colorida no terminal | - -Variáveis home específicas de agente, como `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` e `OPENCLAW_HOME`, substituem o local onde o Failproof AI descobre sessões locais para aquele harness. +| `FAILPROOFAI_HOME` | Realocar o layout completo de `~/.failproofai` | +| `FAILPROOFAI_LOG_LEVEL` | Definir a verbosidade do log local | +| `FAILPROOFAI_HOOK_LOG_FILE` | Gravar diagnósticos de hook em um arquivo específico | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Desabilitar telemetria anônima para este processo | +| `FAILPROOFAI_NO_FIRST_RUN=1` | Ignorar a configuração interativa de primeira execução | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Ignorar a auditoria local pós-configuração | +| `FAILPROOFAI_LLM_BASE_URL` | Substituir o endpoint compatível com OpenAI usado pelas políticas de LLM | +| `FAILPROOFAI_LLM_API_KEY` | Fornecer a chave de API usada pelas políticas de LLM | +| `FAILPROOFAI_LLM_MODEL` | Selecionar o modelo usado pelas políticas de LLM | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Limitar o tempo de carregamento de módulos de políticas personalizadas | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Recusar o download de packs e binários do daemon; o que está instalado continua sendo aplicado | +| `FAILPROOFAI_PACK_BASE_URL` | Buscar packs de um espelho em vez de `github.com` | +| `FAILPROOFAI__EXTRA_PATHS` | Substituir os caminhos de captura extras configurados para um harness | +| `NO_COLOR` | Desabilitar a saída colorida no terminal | + +Variáveis home específicas de agentes, como `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` e `OPENCLAW_HOME`, substituem onde o Failproof AI descobre sessões locais para aquele harness. ## Pausar ou remover uma máquina com segurança @@ -134,7 +141,7 @@ failproofai config --status failproofai config --resume ``` -Uma pausa de sessão local não desativa as políticas gerenciadas pelo Cloud. Restaure as implantações Cloud pelo fluxo de trabalho de enforcement do Cloud quando o próprio rollout for o problema. +Uma pausa de sessão local não desabilita políticas gerenciadas pelo Cloud. Restaure implantações do Cloud por meio do fluxo de trabalho de aplicação do Cloud quando o próprio rollout for o problema. Antes de remover o pacote npm, remova os hooks instalados e o daemon: diff --git a/docs/pt-br/start/quickstart.mdx b/docs/pt-br/start/quickstart.mdx index b43f7e46..c9036668 100644 --- a/docs/pt-br/start/quickstart.mdx +++ b/docs/pt-br/start/quickstart.mdx @@ -1,12 +1,12 @@ --- title: "Início Rápido" -description: "Capture uma sessão de agente, encontre uma falha e comece a evitá-la." +description: "Capture uma sessão de agente, encontre uma falha e comece a preveni-la." icon: "zap" --- -Este início rápido faz com que uma máquina reporte sessões, executa uma auditoria e implanta uma política. Use a skill para configurar o Failproof AI, ou siga os passos manuais. +Este guia de início rápido faz uma máquina reportar sessões, executa uma auditoria e implanta uma política. Use a skill para configurar o Failproof, ou siga os passos manuais. -**Qual caminho é o seu?** Se o seu agente roda em um dos 12 [harnesses](/pt-br/reference/harnesses) suportados — uma CLI de codificação, ou um gateway como Hermes ou OpenClaw — siga os passos abaixo; você precisa do Node.js 20.9 ou superior. Se o seu agente não tem harness, instrumente-o com o [SDK Python](/pt-br/reference/custom-agents) para rastreamento e auditorias, e então junte-se novamente em [Execute sua primeira verificação de falha](/pt-br/start/first-audit); a aplicação nesse caminho precisa de um hook no seu runtime. +**Qual é o seu caminho?** Se o seu agente roda em um dos 12 [harnesses](/pt-br/reference/harnesses) suportados — uma CLI de codificação, ou um gateway como Hermes ou OpenClaw — siga os passos abaixo; você precisa do Node.js 20.9 ou superior. Se o seu agente não tem harness, instrumente-o com o [Python SDK](/pt-br/reference/custom-agents) para rastreamento e auditorias, depois retorne em [Execute sua primeira verificação de falha](/pt-br/start/first-audit); a aplicação de políticas nesse caminho precisa de um hook no seu runtime. @@ -21,22 +21,22 @@ Este início rápido faz com que uma máquina reporte sessões, executa uma audi Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Seu agente inspeciona o projeto, escolhe a integração relevante, realiza a configuração e verifica o resultado. Veja o [repositório de skills do FailproofAI](https://github.com/FailproofAI/skills) para skills individuais e opções avançadas de instalação. + Seu agente inspeciona o projeto, escolhe a integração relevante, realiza a configuração e verifica o resultado. Consulte o [repositório de skills do FailproofAI](https://github.com/FailproofAI/skills) para skills individuais e opções avançadas de instalação. ## Antes de começar -1. Abra o [painel do Failproof AI](https://app.befailproof.ai) e crie uma conta ou entre com seu e-mail de trabalho. -2. Acesse **Administration → Keys** e crie uma chave com `events:add` e `policies:pull`. -3. Copie o secret de uso único e armazene-o na máquina de destino: +1. Abra o [painel do Failproof AI](https://app.befailproof.ai) e crie uma conta ou entre com seu e-mail corporativo. +2. Vá em **Administration → Keys** e crie uma chave com `events:add` e `policies:pull`. +3. Copie o segredo de uso único e armazene-o na máquina de destino: ```bash export FAILPROOFAI_KEY="" ``` - ## Instalar + ## Instalação @@ -45,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - Os transcritos de sessão são enviados por padrão. Adicione `--no-transcripts` para reportar atividade de hook e decisões de política sem o conteúdo do transcrito. + Os transcritos de sessão são enviados por padrão. Adicione `--no-transcripts` para reportar a atividade de hooks e decisões de políticas sem o conteúdo dos transcritos. - Se esta máquina já possui histórico de agente, visualize e importe os últimos sete dias e aguarde a conclusão da entrega. Pule esta etapa em uma máquina nova. + Se esta máquina já tem histórico de agente, pré-visualize e importe os últimos sete dias, depois aguarde a entrega ser concluída. Pule este passo em uma máquina nova. ```bash failproofai backfill --since 7d --dry-run @@ -58,19 +58,19 @@ export FAILPROOFAI_KEY="" Abra **Sessions** no Failproof AI e selecione uma sessão importada. - Isso conecta o Failproof AI ao seu harness e instala as 40 políticas integradas. Use-as para ver as decisões de política locais e experimentar a aplicação antes que o Failproof AI audite suas sessões e escreva políticas para seus agentes. + Isso conecta o Failproof AI ao seu harness e instala as 39 políticas integradas. Use-as para ver decisões de políticas locais e testar a aplicação antes que o Failproof AI audite suas sessões e escreva políticas para seus agentes. - Deixe o instalador detectar seu harness automaticamente, ou especifique um explicitamente. Qualquer um dos 12 é um valor válido para `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + Deixe o instalador detectar seu harness automaticamente, ou especifique um explicitamente. Cada um dos 12 é um valor válido para `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash failproofai policies --install --cli claude --scope user # uma CLI de codificação failproofai policies --install --cli hermes --scope user # um gateway Slack/Telegram ``` - O bloqueio de uma chamada de ferramenta antes de sua execução é verificado em todos os 12. Os gates de fim de turno são verificados em 8 — veja a [capacidade de aplicação](/pt-br/reference/harnesses#enforcement-capability) para a matriz por harness. + O bloqueio de uma chamada de ferramenta antes de sua execução é verificado em todos os 12. Os gates de fim de turno são verificados em 8 — consulte a [capacidade de aplicação](/pt-br/reference/harnesses#enforcement-capability) para a matriz por harness. - Siga [Execute sua primeira verificação de falha](/pt-br/start/first-audit). Use um objetivo concreto, como "encontrar sessões onde o agente repetiu uma ferramenta com falha sem mudar sua abordagem." + Siga [Execute sua primeira verificação de falha](/pt-br/start/first-audit). Use um objetivo concreto como "encontrar sessões em que o agente repetiu uma ferramenta com falha sem mudar sua abordagem." Siga [Previna sua primeira falha com uma política](/pt-br/start/first-policy). Comece no modo de observação, inspecione as correspondências e depois aplique a versão revisada. @@ -78,7 +78,7 @@ export FAILPROOFAI_KEY="" - Execute `failproofai config --status`. Uma configuração saudável reporta a conexão com a nuvem, o estado do daemon e se a aplicação está pausada. + Execute `failproofai config --status`. Uma configuração saudável reporta a conexão com a nuvem, o estado do daemon e se a aplicação de políticas está pausada. \ No newline at end of file diff --git a/docs/ru/policies/builtin-catalog.mdx b/docs/ru/policies/builtin-catalog.mdx index c51e0596..4972a0ad 100644 --- a/docs/ru/policies/builtin-catalog.mdx +++ b/docs/ru/policies/builtin-catalog.mdx @@ -1,98 +1,98 @@ --- -title: "Каталог встроенных политик" -description: "Просмотрите каждую встроенную политику Failproof AI, её триггер, рекомендуемое состояние и настраиваемые параметры." +title: "Встроенный каталог политик" +description: "Посмотрите каждую встроенную политику Failproof AI, её триггер, рекомендуемое состояние и настраиваемые параметры." icon: "list-checks" --- -Установленный пакет является источником истины для доступности политик. Запустите `failproofai policies` после каждого обновления, так как записи каталога и поведение могут измениться в зависимости от версии пакета. +Установленный пакет — источник истины для доступности политик. Запустите `failproofai policies` после каждого обновления, так как записи в каталоге и поведение могут измениться в зависимости от версии пакета. ## Рекомендуемая базовая конфигурация -Рекомендуемый выбор в настройке включает очистители секретов, защиту окружения, самозащиту, защиту от опасных команд и безопасность защищённых веток: +Рекомендуемый выбор в интерактивной установке в настоящее время включает дезинфекторы секретов, защиту окружения, самозащиту, охрану от опасных команд и защиту защищённых веток: ```text sanitize-jwt sanitize-api-keys sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars block-env-files block-secrets-write -block-self-pause block-failproofai-commands -block-sudo block-curl-pipe-sh -block-rm-rf block-push-master -block-force-push +block-failproofai-commands block-sudo +block-curl-pipe-sh block-rm-rf +block-push-master block-force-push ``` -«Рекомендуемое» намеренно уже, чем **Всё**. Политики инфраструктуры и рабочего процесса могут прерывать допустимые операции и должны быть включены для репозиториев и машин, которым они требуются. +`block-failproofai-commands` **всегда включена**. Она указана выше для полноты, но регистрируется при каждой оценке независимо от того, указана ли в вашем наборе включённых политик, и не может быть отключена или приостановлена — охрана, которую агент может отключить, не является охраной. + +Рекомендуемый набор намеренно уже, чем **Всё**. Инфраструктурные и рабочие политики могут помешать допустимым операциям и должны быть включены только для репозиториев и машин, в которых они необходимы. ## Секреты и окружение | Политика | Триггер | Результат | | --- | --- | --- | -| `sanitize-jwt` | `PostToolUse` | Скрывает JWT-токены из вывода инструмента, прежде чем модель их увидит. | -| `sanitize-api-keys` | `PostToolUse` | Скрывает общие ключи OpenAI, Anthropic, GitHub, AWS, Stripe и Google. | -| `sanitize-connection-strings` | `PostToolUse` | Скрывает строки подключения к базе данных, содержащие учётные данные. | -| `sanitize-private-key-content` | `PostToolUse` | Скрывает содержимое тел приватных ключей PEM. | -| `sanitize-bearer-tokens` | `PostToolUse` | Скрывает токены авторизации bearer. | -| `protect-env-vars` | `PreToolUse` на инструментах shell | Блокирует команды, которые выводят переменные окружения. | -| `block-env-files` | `PreToolUse` | Блокирует чтение и запись файлов `.env`. | -| `block-read-outside-cwd` | `PreToolUse` на инструментах read, glob, grep или shell | Ограничивает чтение рабочей директорией сеанса. | -| `block-secrets-write` | `PreToolUse` на инструментах write | Блокирует запись в файлы с именами секретных ключей и учётных данных. | +| `sanitize-jwt` | `PostToolUse` | Скрывать JWT из вывода инструмента перед отправкой модели. | +| `sanitize-api-keys` | `PostToolUse` | Скрывать общие ключи OpenAI, Anthropic, GitHub, AWS, Stripe и Google. | +| `sanitize-connection-strings` | `PostToolUse` | Скрывать строки подключения к БД с учётными данными. | +| `sanitize-private-key-content` | `PostToolUse` | Скрывать тело PEM приватных ключей. | +| `sanitize-bearer-tokens` | `PostToolUse` | Скрывать маркеры авторизации bearer. | +| `protect-env-vars` | `PreToolUse` на shell-инструментах | Блокировать команды, выводящие переменные окружения. | +| `block-env-files` | `PreToolUse` | Блокировать чтение и запись файлов `.env`. | +| `block-read-outside-cwd` | `PreToolUse` на инструментах чтения, glob, grep или shell | Ограничивать чтение текущей директорией сессии. | +| `block-secrets-write` | `PreToolUse` на инструментах записи | Блокировать запись в общие файлы ключей и учётных данных. | ## Опасные команды и инфраструктура | Политика | Триггер | Результат | | --- | --- | --- | -| `block-self-pause` | `PreToolUse`, `PermissionRequest` | Предотвращает агенту паузировать собственное принудительное исполнение. | -| `block-sudo` | `PreToolUse`, `PermissionRequest` | Блокирует `sudo`, если не совпадает шаблон разрешения. | -| `block-curl-pipe-sh` | `PreToolUse` | Блокирует загруженные скрипты, переданные напрямую в shell. | -| `block-rm-rf` | `PreToolUse` | Блокирует катастрофические рекурсивные шаблоны удаления. | -| `block-failproofai-commands` | `PreToolUse` | Предотвращает агентам изменение или удаление Failproof AI. | -| `block-kubectl` | `PreToolUse` | Ограничивает команды Kubernetes. | -| `block-terraform` | `PreToolUse` | Ограничивает команды Terraform и OpenTofu. | -| `block-aws-cli` | `PreToolUse` | Ограничивает команды AWS CLI. | -| `block-gcloud` | `PreToolUse` | Ограничивает команды Google Cloud CLI. | -| `block-az-cli` | `PreToolUse` | Ограничивает команды Azure CLI. | -| `block-helm` | `PreToolUse` | Ограничивает команды Helm. | -| `block-gh-pipeline` | `PreToolUse` | Ограничивает изменяющие операции GitHub CLI: рабочие процессы, запуски, слияния, релизы, кэш и секреты. | - -## Безопасность Git и базы данных +| `block-sudo` | `PreToolUse`, `PermissionRequest` | Блокировать `sudo` если не совпадает с разрешающим паттерном. | +| `block-curl-pipe-sh` | `PreToolUse` | Блокировать скрипты, загруженные и передаваемые напрямую в shell. | +| `block-rm-rf` | `PreToolUse` | Блокировать опасные паттерны рекурсивного удаления. | +| `block-failproofai-commands` | `PreToolUse`, `PermissionRequest` | **Всегда включена, не может быть отключена.** Блокировать каждый вызов CLI Failproof AI, самопаузу и удаление пакета. | +| `block-kubectl` | `PreToolUse` | Ограничивать команды Kubernetes. | +| `block-terraform` | `PreToolUse` | Ограничивать команды Terraform и OpenTofu. | +| `block-aws-cli` | `PreToolUse` | Ограничивать команды AWS CLI. | +| `block-gcloud` | `PreToolUse` | Ограничивать команды Google Cloud CLI. | +| `block-az-cli` | `PreToolUse` | Ограничивать команды Azure CLI. | +| `block-helm` | `PreToolUse` | Ограничивать команды Helm. | +| `block-gh-pipeline` | `PreToolUse` | Ограничивать изменяющие операции GitHub CLI с рабочими процессами, запусками, слияниями, релизами, кэшем и секретами. | + +## Безопасность Git и БД | Политика | Триггер | Результат | | --- | --- | --- | -| `block-push-master` | `PreToolUse` | Блокирует прямые отправки на настроенные защищённые ветки. | -| `block-force-push` | `PreToolUse` | Блокирует force-push; `--force-with-lease` остаётся разрешённым в текущей реализации. | -| `block-work-on-main` | `PreToolUse` | Блокирует коммиты и слияния на защищённых ветках. | -| `warn-git-amend` | `PreToolUse` | Предупреждает перед переписыванием коммита с `--amend`. | -| `warn-git-stash-drop` | `PreToolUse` | Предупреждает перед постоянным удалением или очисткой stash. | -| `warn-all-files-staged` | `PreToolUse` | Предупреждает при широком `git add -A`, `git add .` или `git add --all`. | -| `warn-destructive-sql` | `PreToolUse` | Предупреждает при `DROP`, `TRUNCATE` и `DELETE` без `WHERE` через известные клиенты базы данных. | -| `warn-schema-alteration` | `PreToolUse` | Предупреждает при известных операциях `ALTER TABLE` над столбцами и переименовании. | +| `block-push-master` | `PreToolUse` | Блокировать прямые отправки на настроенные защищённые ветки. | +| `block-force-push` | `PreToolUse` | Блокировать force-push; `--force-with-lease` остаётся допустимым при текущей реализации. | +| `block-work-on-main` | `PreToolUse` | Блокировать коммиты и слияния на защищённых ветках. | +| `warn-git-amend` | `PreToolUse` | Предупреждать перед переписанием коммита с `--amend`. | +| `warn-git-stash-drop` | `PreToolUse` | Предупреждать перед окончательным удалением или очисткой stash. | +| `warn-all-files-staged` | `PreToolUse` | Предупреждать на широком `git add -A`, `git add .` или `git add --all`. | +| `warn-destructive-sql` | `PreToolUse` | Предупреждать на `DROP`, `TRUNCATE` и `DELETE` без `WHERE` через известные клиенты БД. | +| `warn-schema-alteration` | `PreToolUse` | Предупреждать на известные операции `ALTER TABLE` с колонками и переименованиями. | ## Пакеты, поведение системы и циклы агента | Политика | Триггер | Результат | | --- | --- | --- | -| `warn-package-publish` | `PreToolUse` | Предупреждает перед публикацией в реестры пакетов. | -| `warn-global-package-install` | `PreToolUse` | Предупреждает перед глобальной установкой пакетов. | -| `prefer-package-manager` | `PreToolUse` | Инструктирует агента использовать разрешённый менеджер пакетов. | -| `warn-large-file-write` | `PreToolUse` на инструментах write | Предупреждает выше настроенного порога размера файла. | -| `warn-background-process` | `PreToolUse` | Предупреждает при отсоединённых или долгоживущих фоновых процессах. | -| `warn-repeated-tool-calls` | `PreToolUse` | Предупреждает после трёх или более идентичных вызовов инструмента. | +| `warn-package-publish` | `PreToolUse` | Предупреждать перед публикацией в реестры пакетов. | +| `warn-global-package-install` | `PreToolUse` | Предупреждать перед глобальной установкой пакета. | +| `prefer-package-manager` | `PreToolUse` | Инструктировать агента использовать допустимый менеджер пакетов. | +| `warn-large-file-write` | `PreToolUse` на инструментах записи | Предупреждать при превышении настроенного порога размера файла. | +| `warn-background-process` | `PreToolUse` | Предупреждать на отсоединённые или долгоживущие паттерны фоновых процессов. | +| `warn-repeated-tool-calls` | `PreToolUse` | Предупреждать после трёх или более одинаковых вызовов инструмента. | ## Рабочий процесс завершения задачи -Эти политики требуют обработчика, который выдаёт совместимое событие `Stop`. +Эти политики требуют harness, отправляющий совместимое событие `Stop`. | Политика | Результат | | --- | --- | -| `require-commit-before-stop` | Отказывает завершение, пока отслеживаемая работа остаётся незакоммичена. | -| `require-push-before-stop` | Отказывает завершение, пока коммиты остаются только локальными. | -| `require-pr-before-stop` | Требует pull request для текущей ветки. | -| `require-no-conflicts-before-stop` | Требует чистого слияния с настроенной базовой веткой. | -| `require-ci-green-before-stop` | Требует успешного завершения проверок CI для текущего HEAD. | +| `require-commit-before-stop` | Отказать в завершении при наличии неподтверждённых отслеживаемых изменений. | +| `require-push-before-stop` | Отказать в завершении при наличии локальных коммитов. | +| `require-pr-before-stop` | Требовать pull request для текущей ветки. | +| `require-no-conflicts-before-stop` | Требовать чистое слияние с настроенной базовой веткой. | +| `require-ci-green-before-stop` | Требовать успешное завершение проверок CI для текущей HEAD. | ## Справочник параметров -Настраивайте параметры в объекте `policyParams` выбранной области видимости. Типы проверяются каждой политикой. +Настраивайте параметры в объекте `policyParams` выбранной области. Типы проверяются каждой политикой. | Политика | Параметр | Тип и значение по умолчанию | | --- | --- | --- | @@ -100,7 +100,7 @@ block-force-push | `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | | `block-sudo` | `allowPatterns` | `string[]`, `[]` | | `block-rm-rf` | `allowPaths` | `string[]`, `[]` | -| Блокаторы инфраструктуры | `allowPatterns` | `string[]`, `[]` | +| Инфраструктурные блокировщики | `allowPatterns` | `string[]`, `[]` | | `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | | `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | | `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | @@ -125,5 +125,5 @@ block-force-push ``` - Шаблон разрешения расширяет возможности агента. Протестируйте точную токенизацию и варианты команд на целевом обработчике перед развёртыванием на всем парке. + Разрешающий паттерн расширяет возможности агента. Протестируйте точную токенизацию и варианты команд на целевом harness перед развёртыванием на множестве машин. \ No newline at end of file diff --git a/docs/ru/policies/failure-behavior.mdx b/docs/ru/policies/failure-behavior.mdx index b5436d9f..00887b7b 100644 --- a/docs/ru/policies/failure-behavior.mdx +++ b/docs/ru/policies/failure-behavior.mdx @@ -1,19 +1,19 @@ --- -title: "Поведение при сбое" +title: "Поведение при сбоях" description: "Узнайте, что происходит, когда оценка политики или локальный демон недоступны." icon: "shield-alert" --- -Failproof AI разработана таким образом, чтобы сбой при обеспечении соответствия был виден, а не скрыто разрешал рискованную работу. +Failproof AI разработан так, чтобы сбой при применении был видимым, а не позволял молчаливо проходить рискованным операциям. ## Диагностика блокировки при сбое 1. Перейдите в **Admin → enforcement** и откройте машину. - 2. Проверьте её последнее подключение, назначенное развёртывание и сообщённое развёртывание. - 3. Перейдите в **Observe → policy** и откройте сеанс запрещённого решения. - 4. Убедитесь, указывает ли причина на достижимость демона, несоответствие версий или саму политику. + 2. Проверьте её последнее выполнение, назначенное развёртывание и сообщённое развёртывание. + 3. Перейдите в **Observe → policy** и откройте сеанс отклонённого решения. + 4. Подтвердите, указывает ли причина на доступность демона, несовместимость версий или саму политику. @@ -23,21 +23,45 @@ Failproof AI разработана таким образом, чтобы сбо failproofai config ``` - Повторное выполнение `failproofai config` обновляет и перезапускает демон после обновления пакета. + Повторный запуск `failproofai config` обновляет и перезапускает демон после обновления пакета. -На машине, настроенной на использование `failproofaid`, демон является единственным оценивающим элементом. Если он недоступен или его версия протокола не совпадает с версией CLI, оценка хука заканчивается блокировкой. Действие отклоняется с причиной, которая направляет оператора на проверку или обновление демона. +На машине, настроенной на использование `failproofaid`, демон является единственным оценщиком. Если он недоступен или его версия протокола не совпадает с версией CLI, оценка хука не выполняется. Действие отклоняется с причиной, указывающей оператору на необходимость проверить или обновить демон. -До настройки демона хуки оценивают политики в процессе. После записи конфигурации демона Failproof AI не молча не переходит ко второму оценивающему элементу при сбое демона. +До настройки демона хуки оценивают политики в процессе. После регистрации конфигурации демона Failproof AI не откатывается молчаливо ко второму оценщику при сбое демона. -## Ответ на решение о блокировке при сбое +## Ответ на решение при отказе из-за сбоя 1. Запустите `failproofai config --status`. 2. Если версии отличаются, повторно запустите `failproofai config` после обновления пакета. 3. Если демон недоступен, проверьте состояние его сервиса и локальные логи. -4. Возобновите работу агента только после того, как известный путь оценки политики будет исправен. +4. Возобновите работу агента только после того, как известный путь оценки политики будет здоров. - Не пытайтесь повторно выполнить заблокированное действие. Ответ о блокировке при сбое означает, что система не могла установить, что действие безопасно. - \ No newline at end of file + Не повторяйте заблокированное действие многократно. Ответ при отказе из-за сбоя означает, что система не смогла установить, что действие было безопасным. + + +## Пакет не загружается + +Машина, которой было указано применить пакет, и которая не может его выполнить, отклоняет его, а не продолжает молча. Триггером является **зарегистрированное ожидание**, никогда не пустое: машина без установленных пакетов молчит, а пакет, который объявлен и не разрешается — или регистрирует меньше, чем объявляет его манифест — отклоняется. + +Отказ **узкий**, в отличие от недоступного демона. Демон, до которого нельзя дотянуться, означает, что оценка вообще не произошла, поэтому ничего нельзя считать безопасным. Пакет, который не загружается, имеет перечисляемый набор отсутствующих политик, потому что каждая объявленная политика имеет свой `match` — поэтому он отклоняет только события и инструменты, которые покрывали эти политики, а всё остальное продолжает работать. + +Он не срабатывает для: + +- пакета `observe`, который по конструкции оценивает и отбрасывает +- политик, которые вы никогда не принимали или явно отключили +- пакета, который загрузчик никогда не получил, где нельзя отличить "нет регистраций" от преднамеренного пропуска +- активной паузы сеанса +- таймаута загрузки, который временный — один момент медленного диска не должен отклоняться до тех пор, пока человек не вмешается + +`UserPromptSubmit` **инструктирует** вместо отказа, что бы ни объявляла отсутствующая политика. Полный отказ привёл бы к блокировке агента, который мог бы решить проблему. + +### Что делать + +```bash +failproofai pack list +``` + +Он называет все установленные пакеты, которые не загружаются, объясняет почему и завершается с ненулевым кодом. Затем либо переустановите его (`failproofai pack add `), либо удалите его (`failproofai pack remove `) — удаление снимает ожидание, и отказ заканчивается с ним. \ No newline at end of file diff --git a/docs/ru/policies/packs.mdx b/docs/ru/policies/packs.mdx new file mode 100644 index 00000000..babeb5d0 --- /dev/null +++ b/docs/ru/policies/packs.mdx @@ -0,0 +1,110 @@ +--- +title: "Наборы политик" +description: "Установите набор политик, опубликованный как релиз GitHub, и управляйте тем, что он обеспечивает." +icon: "package" +--- + +Набор — это совокупность политик, опубликованная как релиз GitHub. Одна команда устанавливает его, контрольные суммы самого релиза проверяются до запуска чего-либо, а дайджест записывается так, чтобы набор не мог измениться на вашем компьютере впоследствии. + +## Установите политики Failproof AI + +```bash +failproofai pack add core +``` + +Это устанавливает набор, который мы опубликовали, из копии внутри пакета — поэтому ему не требуется сетевой доступ и он не может сбиться за прокси. Возьмите его часть: + +```bash +failproofai pack add core --policy block-rm-rf # одну или несколько через запятую +failproofai pack add core --category dangerous-commands # целую категорию +failproofai pack add core --all # всё в нём +``` + +`failproofai pack list` перечисляет все категории, которые предлагает набор. + +## Посмотрите, что содержит набор, перед его установкой + +```bash +failproofai pack list acme/support-agent +``` + +Перечисляет все политики, которые содержит набор, сгруппированные по категориям, отмечая, какие из них автор включает по умолчанию, а какие являются опциональными. Читает **только манифест** — артефакт входа никогда не загружается и не импортируется, поэтому просмотр чужого набора не может выполнить чужой код. Манифест всё ещё проверяется против `SHA256SUMS` самого релиза, поэтому то, что вы читаете, — это то, что будет установлено. + +`failproofai pack list` без источника перечисляет уже установленные здесь наборы. + +## Установите чужой набор + +```bash +failproofai pack add acme/support-agent +``` + +Любой из этих вариантов работает — вставьте тот, который у вас есть: + +| Источник | Результат | +| --- | --- | +| `acme/support-agent` | Последний релиз, **закреплён** к точному тегу, который он разрешил | +| `acme/support-agent@v2.1.0` | Этот релиз | +| `github:acme/support-agent@v2.1.0` | То же самое, написано явно | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | То же самое, скопировано из браузера | + +Если не указывать тег, устанавливается последний релиз **и он закрепляется**, затем система сообщает вам, какой тег она выбрала. То, что записывается, всегда обозначает ровно один релиз, поэтому переустановка не может дрейфовать. + +## Возьмите часть набора + +По умолчанию вы получаете **собственные** значения по умолчанию набора — политики, которые его автор отметил как безопасные для включения без присмотра — а не всё, что он содержит. + +```bash +failproofai pack add acme/support-agent --category billing,git +failproofai pack add acme/support-agent --policy block-refunds +failproofai pack add acme/support-agent --all +``` + +`--category` и `--policy` комбинируются как объединение (`--only` принимается как синоним для `--policy`). Повторное добавление с более новой версией сохраняет то, что вы выбрали, вместо включения остального обратно. + +## Управляйте тем, что включено + +```bash +failproofai policies # все источники в одном списке, включая наборы +failproofai pack list # только наборы, сгруппированные по категориям +failproofai policies --uninstall block-refunds # выключить одну политику набора +failproofai policies --install block-refunds # и включить обратно +failproofai pack remove acme/support-agent +``` + +Простое имя означает **встроенное** когда оно существует с таким именем. Явно назовите копию набора, когда вам это нужно: + +```bash +failproofai policies --uninstall acme/support-agent:block-refunds +``` + + +Если набор поставляет политику, чьё имя также является **включённой встроенной**, встроенная политика работает и копия набора пропускается — иначе одна и та же защита была бы оценена дважды. Выключите встроенную политику, чтобы вместо этого использовать копию набора. + + +## Откуда берутся политики Failproof AI + +`core` читает копию, включённую в npm-пакет. Этот же набор опубликован как релиз GitHub, который вы устанавливаете, если хотите конкретную версию: + +```bash +failproofai pack add core # из этого пакета, без сети +failproofai pack add FailproofAI/policies # тот же набор из его релиза GitHub +``` + +## Что гарантирует целостность и что нет + +`SHA256SUMS` поставляется в том же релизе, что и артефакт, поэтому это **не** подпись и ничего не доказывает о том, кто его опубликовал. То, что это доказывает, — что байты являются теми, которые опубликовал этот релиз — и поскольку дайджест записывается при добавлении набора и повторно проверяется перед каждым импортом, набор не может измениться на вашем компьютере впоследствии. Репозиторий, который переделывает тег или заменяет актив, перестаёт загружаться вместо того, чтобы молча выполнить что-то другое. + +При установке набор также **импортируется один раз** и проверяется на соответствие его собственному манифесту. Набор, артефакт которого не анализируется или который регистрирует что-то отличное от того, что он объявляет, отклоняется до активации чего-либо — вместо того, чтобы установиться чисто и сбиться при следующем вызове инструмента. + +## Когда набор не загружается + +Набор, который этому компьютеру было приказано обеспечить и который не может выполнить, **отклоняет** события, которые покрывали его отсутствующие политики, вместо того, чтобы молча разрешить их. См. [Поведение при сбое](/ru/policies/failure-behavior). `failproofai pack list` называет любой набор в этом состоянии и выходит с ненулевым кодом. + +## Автономная работа и зеркала + +| Переменная | Эффект | +| --- | --- | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Отказывает в загрузке; установленные наборы продолжают обеспечиваться | +| `FAILPROOFAI_PACK_BASE_URL` | Направляет загрузку набора на зеркало вместо `github.com` | + +Публикация собственного набора: см. [Опубликуйте набор](/ru/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/ru/policies/publish-a-pack.mdx b/docs/ru/policies/publish-a-pack.mdx new file mode 100644 index 00000000..3a2e9fed --- /dev/null +++ b/docs/ru/policies/publish-a-pack.mdx @@ -0,0 +1,91 @@ +--- +title: "Публикация пакета" +description: "Поставляйте свои собственные политики как GitHub-релиз, который может установить кто угодно." +icon: "upload" +--- + +Пакет — это три файла, прикреплённые к GitHub-релизу. `failproofai pack build` создаёт все три файла на основе уже имеющегося файла политики. + +## 1. Напишите политики + +Один файл, использующий тот же API, что и любая пользовательская политика. Для пакета важны два дополнительных поля: + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-refunds", + description: "Refunds above the approved limit need a human", + category: "Billing", // groups it, and is what --category selects on + defaultEnabled: true, // switched on by a plain `pack add` + match: { events: ["PreToolUse"], tools: ["Bash"] }, + fn: async (ctx) => + String(ctx.toolInput?.command ?? "").includes("refund") + ? deny("Refunds need a human. Ask before running this.") + : allow(), +}); +``` + +`defaultEnabled` по умолчанию имеет значение **false**, если вы его опустите. Простая команда `failproofai pack add` включает только то, что вы отметили — установка всех политик незнакомца без участия пользователя — это решение, которое установщик не должен принимать за своего пользователя. + + +Точка входа должна быть **одним самостоятельным файлом**. Только точка входа закреплена по хешу, поэтому пакет, который импортирует локальные файлы, не может честно утверждать, что хеш покрывает то, что запустится. Сначала объедините файлы (`esbuild`, `bun build`, `rollup`), а затем создайте пакет из объединённого результата — `pack build` отказывает локальным импортам, чтобы не поставить обещание, которое оно не может выполнить. + + +## 2. Создайте релиз-артефакты + +```bash +failproofai pack build ./policies.mjs \ + --id acme/support-agent \ + --version 1.0.0 \ + --out ./dist-pack +``` + +Он создаёт три файла и проверяет каждую политику с использованием **собственных правил загрузчика** — так что пакет, который никогда не мог бы установиться, не пройдёт здесь, где вы сможете это исправить: + +| Файл | Что это | +| --- | --- | +| `failproofai-pack.json` | Манифест: id, версия, эффект и по одной записи на каждую политику | +| `failproofai-pack.mjs` | Ваша точка входа в неизменённом виде | +| `SHA256SUMS` | ` ` для остальных двух файлов | + +Отклоняется на этапе сборки: id, который не соответствует формату `publisher/name`, имя политики, содержащее `/`, политика, объявляющая `alwaysOn`, отсутствие `description`, `category` или `match`, точка входа, которая ничего не регистрирует, и точка входа, которая импортирует локальные файлы. + +## 3. Прикрепите их к релизу + +Отметьте релиз той же версией, которую вы создали, и прикрепите все три файла как артефакты релиза: + +```bash +gh release create 1.0.0 \ + ./dist-pack/failproofai-pack.json \ + ./dist-pack/failproofai-pack.mjs \ + ./dist-pack/SHA256SUMS +``` + +Теперь кто угодно может установить его: + +```bash +failproofai pack add acme/support-agent +``` + +Имена артефактов фиксированы — это то, из чего CLI потребителя строит свои URL-адреса, без вызовов API и без обнаружения. + +## Поставка новой версии + +Создайте пакет с новым `--version`, создайте новый релиз, снова прикрепите три артефакта. Потребители запустят тот же `pack add` и сохранят любое подмножество, которое они выбрали; политика, которую они отключили, останется отключённой при обновлении. + +Изменение **имени** политики — это критическое изменение: машина, которая его отключила, отключает имя, которое больше не существует, а новое имя приходит с тем, что говорит `defaultEnabled`. + +## Чему доверяют ваши пользователи + +`SHA256SUMS` находится в том же релизе, что и артефакт, поэтому он доказывает, что байты — это те, которые вы опубликовали, но не кто вы. Кто угодно, у кого есть доступ на запись в репозиторий, может записать оба файла. Защита ваших пользователей в том, что хеш закреплён при установке, поэтому то, что вы поставили, не может измениться после этого. + +Публикуйте из репозитория, доступ на запись в который вы контролируете, и относитесь к релизу пакета как к публикации пакета. + +## Наблюдайте перед тем, как применять + +Манифест может объявить `"effect": "observe"`. Эти политики запускаются, и их решения **записываются и отбрасываются** — ничего не блокируется. Это способ проверить новое правило на реальном трафике перед тем, как оно сможет помешать чьей-то работе. + +```json +{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +``` \ No newline at end of file diff --git a/docs/ru/reference/failproof-cli.mdx b/docs/ru/reference/failproof-cli.mdx index 2bd6e13f..22c8313c 100644 --- a/docs/ru/reference/failproof-cli.mdx +++ b/docs/ru/reference/failproof-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof AI CLI" -description: "Устанавливайте хуки, управляйте локальными политиками, подключайте облако и управляйте локальным демоном." +description: "Установите hooks, управляйте локальными политиками, подключитесь к Cloud и управляйте локальным daemon." icon: "terminal" --- -Установите локальный CLI с помощью `npm install -g failproofai`. Запустите его без аргументов, чтобы открыть панель управления локальными политиками. +Установите локальный CLI с помощью `npm install -g failproofai`. Запустите его без аргументов, чтобы открыть локальную панель управления политиками. -Пакет требует Node.js версии 20.9 или новее. Bun версии 1.3 или новее поддерживается для разработки и установки из исходного кода. `failproofai configure` и `failproofai setup` — это псевдонимы для `failproofai config`; `failproofai p` — это псевдоним для `failproofai policies`. +Пакет требует Node.js 20.9 или новее. Bun 1.3 или новее поддерживается для разработки и установки из исходного кода. `failproofai configure` и `failproofai setup` являются псевдонимами для `failproofai config`; `failproofai p` является псевдонимом для `failproofai policies`. ## Настройка машины @@ -20,60 +20,65 @@ failproofai policies --install failproofai config --status ``` -Запустите `failproofai` без аргументов, чтобы открыть панель управления локальными политиками. +Запустите `failproofai` без аргументов, чтобы открыть локальную панель управления политиками. | Команда | Результат | | --- | --- | | `failproofai config` | Запустить интерактивную настройку машины | -| `failproofai config --connect --token ` | Подключить облачную доставку событий и доставку политик | -| `failproofai config --status` | Показать состояние подключения, демона, доставки и паузы | -| `failproofai policies` | Список встроенных и пользовательских политик | -| `failproofai policies --install` | Установить хуки и включить политики | -| `failproofai policy add ` | Включить одну встроенную политику | -| `failproofai policy remove ` | Отключить одну встроенную политику | -| `failproofai policies --uninstall` | Отключить политики или удалить хуки интеграции | -| `failproofai audit` | Просканировать локальную историю агента и открыть локальное представление аудита | -| `failproofai audit --schedule [days] --email
` | Запланировать периодические локальные сканирования и отправить результаты по электронной почте | -| `failproofai audit --status` | Показать адрес отчета, интервал и время следующего запланированного сканирования | -| `failproofai audit --no-schedule` | Остановить периодические сканирования без удаления истории аудита | +| `failproofai config --connect --token ` | Подключить Cloud ingestion и доставку политик | +| `failproofai config --status` | Показать состояние подключения, daemon, доставки и паузы | +| `failproofai policies` | Список встроенных, пользовательских, соглашений, пакетов и управляемых Cloud политик | +| `failproofai policies --install` | Установить hooks и включить политики | +| `failproofai policy add ` | Включить одну политику — встроенную или `:` из установленного пакета | +| `failproofai policy remove ` | Отключить одну политику, аналогичное именование | +| `failproofai policies --uninstall` | Отключить политики или удалить hooks harness | +| `failproofai pack list` | Список установленных пакетов политик и всех политик в каждом | +| `failproofai pack add ` | Установить пакет политик из GitHub release; отсутствие тега выбирает новейший и закрепляет его | +| `failproofai pack add --bundled` | Установить встроенные политики как пакет из этого пакета без сетевого доступа | +| `failproofai pack build ` | Собрать три ресурса release для вашего собственного пакета | +| `failproofai pack remove ` | Деактивировать установленный пакет | +| `failproofai audit` | Сканировать локальную историю агента и открыть локальный audit view | +| `failproofai audit --schedule [days] --email
` | Планировать повторяющиеся локальные сканирования и отправлять их результаты по email | +| `failproofai audit --status` | Показать адрес отчета, интервал и следующее запланированное сканирование | +| `failproofai audit --no-schedule` | Остановить повторяющиеся сканирования без удаления истории аудита | | `failproofai harness list` | Список дополнительных путей захвата | -| `failproofai flush --wait` | Доставить текущий буфер событий | -| `failproofai backfill --since 30d` | Переквитировать ранее пройденную историю | -| `failproofai config --pause [duration]` | Приостановить одну локальную сессию на 30 минут по умолчанию, максимум 8 часов | -| `failproofai config --resume` | Возобновить одну приостановленную локальную сессию; добавьте `--all`, чтобы очистить все паузы | -| `failproofai update` | Завершить миграции пакета и обновить демон | -| `failproofai migrate --dry-run` | Просмотреть или запустить предполагаемые миграции структуры главной директории | -| `failproofai uninstall` | Удалить хуки и демон перед удалением пакета | -| `failproofai --version` | Печать установленной версии пакета | +| `failproofai flush --wait` | Доставить текущий event spool | +| `failproofai backfill --since 30d` | Перечитать ранее пройденную историю | +| `failproofai config --pause [duration]` | Приостановить одну локальную сессию на 30 минут по умолчанию, до 8 часов | +| `failproofai config --resume` | Возобновить одну приостановленную локальную сессию; добавьте `--all` для очистки всех пауз | +| `failproofai update` | Завершить миграции пакетов и обновить daemon | +| `failproofai migrate --dry-run` | Предпросмотреть или выполнить ожидающие миграции home-layout | +| `failproofai uninstall` | Удалить hooks и daemon перед удалением пакета | +| `failproofai --version` | Вывести версию установленного пакета | | `failproofai --help` | Показать команды и глобальное использование | ## Флаги конфигурации | Флаг | Использование | | --- | --- | -| `--connect --token ` | Подключиться неинтерактивно | +| `--connect --token ` | Подключение без интерактивного режима | | `--machine-id ` | Установить стабильный ID машины | -| `--machine-label ` | Установить или изменить метку на панели управления | -| `--no-transcripts` | Отправлять решения без содержания протокола | -| `--disconnect` | Остановить облачные запросы политик и доставку событий | +| `--machine-label ` | Установить или изменить ярлык панели | +| `--no-transcripts` | Отправлять решения без содержимого транскрипта | +| `--disconnect` | Остановить Cloud policy pulls и доставку событий | | `--status` | Показать текущее состояние машины | -| `--pause [duration]` | Приостановить новейшую сессию в текущей директории; принимает секунды, минуты или часы и по умолчанию составляет 30 минут | -| `--resume` | Завершить соответствующую паузу раньше времени | -| `--session ` | Выбрать явную сессию для паузы или возобновления | -| `--all` | С `--resume` завершить каждую активную паузу | +| `--pause [duration]` | Приостановить новую сессию в текущей директории; принимает секунды, минуты или часы и по умолчанию составляет 30 минут | +| `--resume` | Завершить соответствующую паузу раньше | +| `--session ` | Целевая явная сессия для паузы или возобновления | +| `--all` | С `--resume`, завершить все активные паузы | -Локальные паузы приостанавливают встроенные, пользовательские и конвенционные политики для одной сессии. Они всегда истекают и не отключают облачные управляемые политики. `block-self-pause` предотвращает использование инструментированным агентом этого способа избежать ограничений. +Локальные паузы приостанавливают встроенные, пользовательские, соглашения и пакетные политики для одной сессии. Они всегда истекают и не отключают управляемые Cloud политики. `block-failproofai-commands` — который всегда включен и не может быть отключен или приостановлен сам по себе — предотвращает использование этого лазейки инструментированным агентом. ## Флаги политик | Флаг | Использование | | --- | --- | -| `--install`, `-i` | Включить политики и установить хуки интеграции | -| `--uninstall`, `-u` | Отключить политики или удалить хуки | -| `--cli ` | Выбрать одну или несколько поддерживаемых интеграций | -| `--scope user\|project\|local\|all` | Выбрать область конфигурации; `all` для удаления | -| `--beta` | Включить бета-политики | -| `--custom`, `-c ` | Проверить и загрузить файл пользовательской политики; повторяемо | +| `--install`, `-i` | Включить политики и установить hooks harness | +| `--uninstall`, `-u` | Отключить политики или удалить hooks | +| `--cli ` | Целевой один или несколько поддерживаемых harnesses | +| `--scope user\|project\|local\|all` | Выбрать scope конфигурации; `all` для uninstall | +| `--beta` | Включить бета политики | +| `--custom`, `-c ` | Валидировать и загрузить пользовательский файл политики; повторяемо | ## Флаги доставки и обслуживания @@ -85,9 +90,9 @@ failproofai config --status | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` следует запустить после `npm install -g failproofai@latest`; он выполняет миграции структуры главной директории, устанавливает соответствующий бинарный файл демона и перезапускает сервис. `--no-daemon` выполняет только миграцию структуры. +`failproofai update` следует запускать после `npm install -g failproofai@latest`; он выполняет миграции home-layout, устанавливает соответствующий binary daemon и перезапускает сервис. `--no-daemon` выполняет только миграцию layout. -## Пути интеграции +## Пути Harness ```text failproofai harness list [harness] @@ -95,11 +100,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -Поддерживаемые имена интеграций: `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` и `goose`. +Поддерживаемые имена harness: `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` и `goose`. -Метки определяют пространство имен для ID производных агентов, когда два корня содержат копии одного проекта. Перекрывающиеся корни и дублирующиеся метки отклоняются, чтобы предотвратить дублирование сборки или повреждение курсора. Конфигурация дополнительных путей перезагружается без перезагрузки демона. +Ярлыки создают namespace производных ID агентов, когда два корня содержат копии одного проекта. Перекрывающиеся корни и дублирующиеся ярлыки отклоняются для предотвращения дублирования сбора или повреждения курсора. Конфигурация дополнительного пути перезагружается без перезагрузки daemon. -В контейнерных средах можно заменить пути дополнительных возможностей, сконфигурированные в файле, переменной, разделенной запятыми, с именем `FAILPROOFAI__EXTRA_PATHS`, например: +Окружение контейнеров может заменить сконфигурированные в файлах дополнительные пути переменной, разделенной запятыми, с именем `FAILPROOFAI__EXTRA_PATHS`, например: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -111,22 +116,24 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl | Переменная | Использование | | --- | --- | -| `FAILPROOFAI_HOME` | Переместить полный макет `~/.failproofai` | -| `FAILPROOFAI_LOG_LEVEL` | Установить уровень многословности локального логирования | -| `FAILPROOFAI_HOOK_LOG_FILE` | Записать диагностику хуков в выбранный файл | +| `FAILPROOFAI_HOME` | Переместить полный layout `~/.failproofai` | +| `FAILPROOFAI_LOG_LEVEL` | Установить verbosity локального логирования | +| `FAILPROOFAI_HOOK_LOG_FILE` | Записать диагностику hook в выбранный файл | | `FAILPROOFAI_TELEMETRY_DISABLED=1` | Отключить анонимную телеметрию для этого процесса | | `FAILPROOFAI_NO_FIRST_RUN=1` | Пропустить интерактивную настройку при первом запуске | | `FAILPROOFAI_NO_AUTO_AUDIT=1` | Пропустить локальный аудит после настройки | -| `FAILPROOFAI_LLM_BASE_URL` | Переопределить используемую конечную точку, совместимую с OpenAI для политик LLM | -| `FAILPROOFAI_LLM_API_KEY` | Предоставить ключ API, используемый политиками LLM | -| `FAILPROOFAI_LLM_MODEL` | Выбрать модель, используемую политиками LLM | +| `FAILPROOFAI_LLM_BASE_URL` | Переопределить используемую LLM политиками совместимую с OpenAI конечную точку | +| `FAILPROOFAI_LLM_API_KEY` | Предоставить API ключ, используемый LLM политиками | +| `FAILPROOFAI_LLM_MODEL` | Выбрать модель, используемую LLM политиками | | `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Ограничить загрузку модуля пользовательской политики | -| `FAILPROOFAI__EXTRA_PATHS` | Заменить сконфигурированные пути дополнительного захвата для одной интеграции | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Отказать в загрузке пакетов и binaries daemon; установленное остается в работе | +| `FAILPROOFAI_PACK_BASE_URL` | Загружать пакеты с зеркала вместо `github.com` | +| `FAILPROOFAI__EXTRA_PATHS` | Заменить сконфигурированные дополнительные пути захвата для одного harness | | `NO_COLOR` | Отключить цветной вывод терминала | -Переменные главной директории для конкретного агента, такие как `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` и `OPENCLAW_HOME`, переопределяют, где Failproof AI обнаруживает локальные сессии для этой интеграции. +Переменные home, специфичные для агента, такие как `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` и `OPENCLAW_HOME`, переопределяют место, где Failproof AI обнаруживает локальные сессии для этого harness. -## Безопасная пауза или удаление машины +## Безопасно приостановить или удалить машину ```bash failproofai config --pause @@ -134,9 +141,9 @@ failproofai config --status failproofai config --resume ``` -Пауза локальной сессии не отключает облачные управляемые политики. Восстановите облачные развертывания через рабочий процесс облачного обеспечения, когда само развертывание является проблемой. +Локальная пауза сессии не отключает управляемые Cloud политики. Восстановите Cloud deployments через Cloud enforcement workflow, когда сам rollout является проблемой. -Перед удалением пакета npm удалите установленные хуки и демон: +Перед удалением npm пакета удалите установленные hooks и daemon: ```bash failproofai uninstall --dry-run @@ -144,8 +151,8 @@ failproofai uninstall --yes npm rm -g failproofai ``` -Запустите `failproofai --help` для специфичных для версии деталей. +Запустите `failproofai --help` для версионно-специфичных деталей. - Запустите `failproofai uninstall` перед `npm rm -g failproofai`; npm не удаляет установленные хуки агента или сервис демона. + Запустите `failproofai uninstall` перед `npm rm -g failproofai`; npm не удаляет установленные agent hooks и сервис daemon. \ No newline at end of file diff --git a/docs/ru/start/quickstart.mdx b/docs/ru/start/quickstart.mdx index ce3425de..3036907c 100644 --- a/docs/ru/start/quickstart.mdx +++ b/docs/ru/start/quickstart.mdx @@ -1,35 +1,35 @@ --- title: "Быстрый старт" -description: "Захватите сеанс агента, найдите ошибку и начните её предотвращать." +description: "Захватите сеанс агента, найдите сбой и начните его предотвращать." icon: "zap" --- -Этот быстрый старт запустит один машину с отправкой сеансов, проведёт аудит и развернёт политику. Используйте навык для установки Failproof AI или следуйте ручным шагам. +Этот быстрый старт позволит одной машине отправлять сеансы, запустить аудит и развернуть политику. Используйте навык для настройки Failproof AI или выполните шаги вручную. -**Какой путь вам подходит?** Если ваш агент работает на одном из 12 поддерживаемых [хранилищ](/ru/reference/harnesses) — кодирующий CLI или шлюз вроде Hermes или OpenClaw — следуйте приведённым ниже шагам; вам нужен Node.js 20.9 или позже. Если ваш агент не имеет хранилища, инструментируйте его с помощью [Python SDK](/ru/reference/custom-agents) для трассировки и аудитов, затем вернитесь к [Запуск первой проверки ошибок](/ru/start/first-audit); принудительное применение на этом пути требует перехватчика в вашей среде выполнения. +**Какой путь вам подходит?** Если ваш агент работает в одной из 12 поддерживаемых [оболочек](/ru/reference/harnesses) — кодирующем CLI или шлюзе типа Hermes или OpenClaw — выполните шаги ниже; вам нужен Node.js 20.9 или позже. Если ваш агент не имеет оболочки, инструментируйте его с помощью [Python SDK](/ru/reference/custom-agents) для трассировки и аудитов, затем вернитесь к пункту [Запустите первую проверку сбоя](/ru/start/first-audit); принудительное применение на этом пути требует hook в вашей среде выполнения. - + ```bash npx skills add FailproofAI/skills ``` - + ```text Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Ваш агент проверит проект, выберет соответствующую интеграцию, выполнит настройку и проверит её. Ознакомьтесь с [репозиторием навыков FailproofAI](https://github.com/FailproofAI/skills) для получения информации об отдельных навыках и расширенных вариантах установки. + Ваш агент осмотрит проект, выберет соответствующую интеграцию, выполнит настройку и проверит её. Смотрите [репозиторий навыков FailproofAI](https://github.com/FailproofAI/skills) для отдельных навыков и расширенных опций установки. - + ## Перед началом -1. Откройте [панель управления Failproof AI](https://app.befailproof.ai) и создайте аккаунт или войдите с помощью рабочей электронной почты. -2. Перейдите в **Administration → Keys** и создайте ключ с правами `events:add` и `policies:pull`. +1. Откройте [панель управления Failproof AI](https://app.befailproof.ai) и создайте учётную запись или войдите с помощью рабочей электронной почты. +2. Перейдите в **Administration → Keys** и создайте ключ с разрешениями `events:add` и `policies:pull`. 3. Скопируйте одноразовый секрет и сохраните его на целевой машине: ```bash @@ -45,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - Расшифровки сеансов отправляются по умолчанию. Добавьте `--no-transcripts` для отправки активности перехватчиков и решений по политикам без содержимого расшифровок. + Расшифровки сеансов отправляются по умолчанию. Добавьте `--no-transcripts` для отправки активности hook и решений политики без содержимого расшифровок. - Если на этой машине уже есть история агента, выполните предпросмотр и импортируйте последние семь дней, затем дождитесь завершения доставки. Пропустите этот шаг на новой машине. + Если эта машина уже имеет историю агента, просмотрите и импортируйте последние семь дней, затем дождитесь завершения доставки. Пропустите этот шаг на новой машине. ```bash failproofai backfill --since 7d --dry-run @@ -57,28 +57,28 @@ export FAILPROOFAI_KEY="" Откройте **Sessions** в Failproof AI и выберите импортированный сеанс. - - Это подключит Failproof AI к вашему хранилищу и установит 40 встроенных политик. Используйте их для просмотра локальных решений по политикам и попробуйте принудительное применение перед тем, как Failproof AI проведёт аудит ваших сеансов и напишет политики для ваших агентов. + + Это подключает Failproof AI к вашей оболочке и устанавливает 39 встроенных политик. Используйте их для просмотра локальных решений политики и проверки принудительного применения перед тем, как Failproof AI выполнит аудит ваших сеансов и напишет политики для ваших агентов. - Позвольте установщику определить ваше хранилище или укажите его явно. Каждое из 12 хранилищ является допустимым значением `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + Позвольте установщику обнаружить вашу оболочку или укажите её явно. Каждая из 12 является допустимым значением `--cli` — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash failproofai policies --install --cli claude --scope user # a coding CLI failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - Блокировка вызова инструмента перед его выполнением проверяется на всех 12 хранилищах. Завершающие вентили проверяются на 8 — см. [возможности принудительного применения](/ru/reference/harnesses#enforcement-capability) для матрицы по хранилищам. + Блокировка вызова инструмента перед его запуском проверяется на всех 12. Шлюзы конца хода проверяются на 8 — смотрите [возможность принудительного применения](/ru/reference/harnesses#enforcement-capability) для матрицы по каждой оболочке. - - Следуйте инструкциям [Запуск первой проверки ошибок](/ru/start/first-audit). Используйте конкретную цель, такую как поиск сеансов, где агент повторил неудачный инструмент без изменения подхода. + + Выполните действия из раздела [Запустите первую проверку сбоя](/ru/start/first-audit). Используйте конкретную цель, например «найти сеансы, где агент повторил неудачный инструмент без изменения своего подхода». - - Следуйте инструкциям [Предотвратить первую ошибку с помощью политики](/ru/start/first-policy). Начните с режима наблюдения, проверьте совпадения, затем примените просмотренную версию. + + Выполните действия из раздела [Предотвратите свой первый сбой с помощью политики](/ru/start/first-policy). Начните в режиме наблюдения, проверьте совпадения, затем примените проверенную версию. - Запустите `failproofai config --status`. Здоровая установка выведет облачное соединение, состояние демона и информацию о том, приостановлено ли принудительное применение. + Запустите `failproofai config --status`. Здоровая настройка отражает облачное соединение, состояние демона и приостановлено ли принудительное применение. \ No newline at end of file diff --git a/docs/tr/policies/builtin-catalog.mdx b/docs/tr/policies/builtin-catalog.mdx index 960e083e..b4344ce2 100644 --- a/docs/tr/policies/builtin-catalog.mdx +++ b/docs/tr/policies/builtin-catalog.mdx @@ -1,102 +1,102 @@ --- title: "Yerleşik politika kataloğu" -description: "Her Failproof AI yerleşik politikasını, tetikleyicisini, önerilen durumunu ve yapılandırılabilir parametrelerini inceleyin." +description: "Her bir Failproof AI yerleşik politikasını, tetikleme koşullarını, önerilen durumunu ve yapılandırılabilir parametrelerini inceleyin." icon: "list-checks" --- -Kurulan paket, politika kullanılabilirliğinin tek kaynağıdır. Her yükseltmeden sonra `failproofai policies` komutunu çalıştırın, çünkü katalog girişleri ve davranış paket sürümüyle değişebilir. +Yüklü paket, politika mevcudiyetinin kaynağıdır. Her yükseltmeden sonra `failproofai policies` komutunu çalıştırın çünkü katalog girdileri ve davranış paket sürümüyle değişebilir. -## Önerilen temel yapılandırma +## Önerilen temel ayarlar -Kılavuzlu kurulumun önerilen seçimi şu anda gizli sanitizerleri, ortam korumalarını, kendi kendine korumayı, felaket komutu korumasını ve korunan dal güvenliğini etkinleştirir: +Rehberli kurulumun önerilen seçimi şu anda sır temizleyicileri, ortam korumalarını, kendi kendini korumayı, felaket komutları korumasını ve korumalı dal güvenliğini etkinleştirmektedir: ```text sanitize-jwt sanitize-api-keys sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars block-env-files block-secrets-write -block-self-pause block-failproofai-commands -block-sudo block-curl-pipe-sh -block-rm-rf block-push-master -block-force-push +block-failproofai-commands block-sudo +block-curl-pipe-sh block-rm-rf +block-push-master block-force-push ``` -Önerilen, **Her Şey** seçeneğinden kasıtlı olarak daha dar kapsamlıdır. Altyapı ve iş akışı politikaları geçerli işleri kesintiye uğratabilir ve bunlara ihtiyaç duyan depolar ve makinelerde etkinleştirilmelidir. +`block-failproofai-commands` **her zaman açıktır**. Bütünlük açısından yukarıda listelenmiştir, ancak etkinleştirilen ayarında yer alıp almadığına bakılmaksızın her değerlendirmede kaydolur ve devre dışı bırakılamaz veya duraklatılamaz — aracının zorlama mekanizmasını kapatabilmesine karşı bir koruma kendisi değer taşımaz. -## Gizli anahtarlar ve ortam +Önerilen, **Her şey** seçeneğinden kasıtlı olarak daha darıttır. Altyapı ve iş akışı politikaları geçerli işi kesintiye uğratabilir ve bunların etkinleştirilmesi gerekli olan depolar ve makineler için seçilmelidir. + +## Sırlar ve ortam | Politika | Tetikleyici | Sonuç | | --- | --- | --- | -| `sanitize-jwt` | `PostToolUse` | Model bunları görmeden önce araç çıktısından JWT'leri temizleyin. | -| `sanitize-api-keys` | `PostToolUse` | Ortak OpenAI, Anthropic, GitHub, AWS, Stripe ve Google anahtarlarını temizleyin. | -| `sanitize-connection-strings` | `PostToolUse` | Kimlik bilgileri içeren veritabanı bağlantı dizelerini temizleyin. | -| `sanitize-private-key-content` | `PostToolUse` | PEM özel anahtar gövdelerini temizleyin. | -| `sanitize-bearer-tokens` | `PostToolUse` | Yetkilendirme taşıyıcı jetonlarını temizleyin. | -| `protect-env-vars` | `PreToolUse` (kabuk araçlarında) | Ortam değişkenlerini döküm yapan komutları engelle. | -| `block-env-files` | `PreToolUse` | `.env` dosyalarının okunması ve yazılmasını engelle. | -| `block-read-outside-cwd` | `PreToolUse` (okuma, glob, grep veya kabuk araçlarında) | Okumaları oturum çalışma dizini içinde tut. | -| `block-secrets-write` | `PreToolUse` (yazma araçlarında) | Yaygın gizli anahtar ve kimlik bilgisi dosya adlarına yazılmasını engelle. | +| `sanitize-jwt` | `PostToolUse` | Araç çıktısından JWT'leri modelin görmesinden önce redakte edin. | +| `sanitize-api-keys` | `PostToolUse` | Yaygın OpenAI, Anthropic, GitHub, AWS, Stripe ve Google anahtarlarını redakte edin. | +| `sanitize-connection-strings` | `PostToolUse` | Kimlik bilgilerini içeren veritabanı bağlantı dizelerini redakte edin. | +| `sanitize-private-key-content` | `PostToolUse` | PEM özel anahtar gövdelerini redakte edin. | +| `sanitize-bearer-tokens` | `PostToolUse` | Yetkilendirme taşıyıcı jetonlarını redakte edin. | +| `protect-env-vars` | Shell araçlarında `PreToolUse` | Ortam değişkenlerini döken komutları engelleyin. | +| `block-env-files` | `PreToolUse` | `.env` dosyalarının okumalarını ve yazışlarını engelleyin. | +| `block-read-outside-cwd` | Okuma, glob, grep veya shell araçlarında `PreToolUse` | Okumaları oturum çalışma dizini içinde tutun. | +| `block-secrets-write` | Yazma araçlarında `PreToolUse` | Yaygın sır anahtarı ve kimlik bilgisi dosya adlarına yazmaları engelleyin. | ## Tehlikeli komutlar ve altyapı | Politika | Tetikleyici | Sonuç | | --- | --- | --- | -| `block-self-pause` | `PreToolUse`, `PermissionRequest` | Bir aracının kendi zorlama mekanizmasını duraklatmasını engelle. | -| `block-sudo` | `PreToolUse`, `PermissionRequest` | İzin deseni eşleşmedikçe `sudo` komutunu engelle. | -| `block-curl-pipe-sh` | `PreToolUse` | İndirilen betiklerin doğrudan kabuğa aktarılmasını engelle. | -| `block-rm-rf` | `PreToolUse` | Felaket niteliğinde yinelemeli silme desenlerini engelle. | -| `block-failproofai-commands` | `PreToolUse` | Aracıların Failproof AI'ı değiştirmesini veya kaldırmasını engelle. | -| `block-kubectl` | `PreToolUse` | Kubernetes komutlarını kısıtla. | -| `block-terraform` | `PreToolUse` | Terraform ve OpenTofu komutlarını kısıtla. | -| `block-aws-cli` | `PreToolUse` | AWS CLI komutlarını kısıtla. | -| `block-gcloud` | `PreToolUse` | Google Cloud CLI komutlarını kısıtla. | -| `block-az-cli` | `PreToolUse` | Azure CLI komutlarını kısıtla. | -| `block-helm` | `PreToolUse` | Helm komutlarını kısıtla. | -| `block-gh-pipeline` | `PreToolUse` | GitHub CLI iş akışı, çalıştırma, birleştirme, yayın, önbellek ve gizli işlemleri değiştiren komutları kısıtla. | +| `block-sudo` | `PreToolUse`, `PermissionRequest` | İzin deseni eşleşmediği sürece `sudo`'yu engelleyin. | +| `block-curl-pipe-sh` | `PreToolUse` | İndirilen betikleri doğrudan bir kabuğa yönlendirmeyi engelleyin. | +| `block-rm-rf` | `PreToolUse` | Felaket düzeyinde özyinelemeli silme desenleri engelleyin. | +| `block-failproofai-commands` | `PreToolUse`, `PermissionRequest` | **Her zaman açıktır, devre dışı bırakılamaz.** Her Failproof AI CLI çağrısını, kendi kendini duraklatmayı ve paket yöneticisi kaldırmalarını engelleyin. | +| `block-kubectl` | `PreToolUse` | Kubernetes komutlarını kısıtlayın. | +| `block-terraform` | `PreToolUse` | Terraform ve OpenTofu komutlarını kısıtlayın. | +| `block-aws-cli` | `PreToolUse` | AWS CLI komutlarını kısıtlayın. | +| `block-gcloud` | `PreToolUse` | Google Cloud CLI komutlarını kısıtlayın. | +| `block-az-cli` | `PreToolUse` | Azure CLI komutlarını kısıtlayın. | +| `block-helm` | `PreToolUse` | Helm komutlarını kısıtlayın. | +| `block-gh-pipeline` | `PreToolUse` | Değiştiren GitHub CLI iş akışı, çalıştırma, birleştirme, yayın, önbellek ve sır işlemlerini kısıtlayın. | ## Git ve veritabanı güvenliği | Politika | Tetikleyici | Sonuç | | --- | --- | --- | -| `block-push-master` | `PreToolUse` | Yapılandırılmış korunan dallara doğrudan göndermeyi engelle. | -| `block-force-push` | `PreToolUse` | Zorlamaya dayalı göndermeyi engelle; `--force-with-lease` mevcut uygulama tarafından izin verilir. | -| `block-work-on-main` | `PreToolUse` | Korunan dallarda işlemler ve birleştirmeleri engelle. | -| `warn-git-amend` | `PreToolUse` | `--amend` ile bir işlemi yeniden yazmadan önce uyar. | -| `warn-git-stash-drop` | `PreToolUse` | Stasları kalıcı olarak bırakmadan veya temizlemeden önce uyar. | -| `warn-all-files-staged` | `PreToolUse` | Geniş `git add -A`, `git add .` veya `git add --all` konusunda uyar. | -| `warn-destructive-sql` | `PreToolUse` | Tanınan veritabanı istemcileri aracılığıyla `WHERE` olmayan `DROP`, `TRUNCATE` ve `DELETE` konusunda uyar. | -| `warn-schema-alteration` | `PreToolUse` | Tanınan `ALTER TABLE` sütun ve yeniden adlandırma işlemleri konusunda uyar. | +| `block-push-master` | `PreToolUse` | Yapılandırılmış korumalı dallara doğrudan gönderileri engelleyin. | +| `block-force-push` | `PreToolUse` | Zorla gönderileri engelleyin; `--force-with-lease` mevcut uygulamada izin verilen olarak kalır. | +| `block-work-on-main` | `PreToolUse` | Korumalı dallarda işlemeleri ve birleştirmeleri engelleyin. | +| `warn-git-amend` | `PreToolUse` | `--amend` ile bir işlemeyi yeniden yazarken uyarı verin. | +| `warn-git-stash-drop` | `PreToolUse` | Hazırlamaları kalıcı olarak bırakmadan veya temizlemeden önce uyarı verin. | +| `warn-all-files-staged` | `PreToolUse` | Geniş `git add -A`, `git add .` veya `git add --all` sırasında uyarı verin. | +| `warn-destructive-sql` | `PreToolUse` | Tanınan veritabanı istemcileri aracılığıyla `WHERE` olmayan `DROP`, `TRUNCATE` ve `DELETE` sırasında uyarı verin. | +| `warn-schema-alteration` | `PreToolUse` | Tanınan `ALTER TABLE` sütun ve yeniden adlandırma işlemleri sırasında uyarı verin. | -## Paketler, sistem davranışı ve ajan döngüleri +## Paketler, sistem davranışı ve aracı döngüleri | Politika | Tetikleyici | Sonuç | | --- | --- | --- | -| `warn-package-publish` | `PreToolUse` | Paket kayıtlarına yayınlamadan önce uyar. | -| `warn-global-package-install` | `PreToolUse` | Genel paket kurulumundan önce uyar. | -| `prefer-package-manager` | `PreToolUse` | Aracıya izin verilen paket yöneticisini kullanmasını öner. | -| `warn-large-file-write` | `PreToolUse` (yazma araçlarında) | Yapılandırılmış dosya boyutu eşiğinin üstünde uyar. | -| `warn-background-process` | `PreToolUse` | Ayrılmış veya uzun süreli arka plan süreci desenleri konusunda uyar. | -| `warn-repeated-tool-calls` | `PreToolUse` | Üç veya daha fazla özdeş araç çağrısından sonra uyar. | +| `warn-package-publish` | `PreToolUse` | Paket kayıtlarına yayınlamadan önce uyarı verin. | +| `warn-global-package-install` | `PreToolUse` | Genel paket kurulumundan önce uyarı verin. | +| `prefer-package-manager` | `PreToolUse` | Aracıya izin verilen bir paket yöneticisini kullanmasını öğütleyin. | +| `warn-large-file-write` | Yazma araçlarında `PreToolUse` | Yapılandırılmış dosya boyutu eşiğinin üzerinde uyarı verin. | +| `warn-background-process` | `PreToolUse` | Ayrılmış veya uzun süreli arka plan işlem desenlerinde uyarı verin. | +| `warn-repeated-tool-calls` | `PreToolUse` | Üç veya daha fazla özdeş araç çağrısından sonra uyarı verin. | ## Görev sonu iş akışı -Bu politikalar uyumlu bir `Stop` olayı yayan bir harness gerektirir. +Bu politikalar uyumlu bir `Stop` olayı yayan bir sistem gerektirmektedir. | Politika | Sonuç | | --- | --- | -| `require-commit-before-stop` | İzlenen işler taahhüt edilmeden tamamlanmayı reddet. | -| `require-push-before-stop` | Taahhütler yerel kalırken tamamlanmayı reddet. | -| `require-pr-before-stop` | Mevcut dal için çekme isteği gerektir. | -| `require-no-conflicts-before-stop` | Yapılandırılmış temel dal karşısında temiz birleştirme gerektir. | -| `require-ci-green-before-stop` | Geçerli-HEAD CI denetimlerinin başarıyla tamamlanmasını gerektir. | +| `require-commit-before-stop` | İzlenen işler işlenmemişken tamamlamayı reddedin. | +| `require-push-before-stop` | İşlemeler yalnızca yerel olarak kalırken tamamlamayı reddedin. | +| `require-pr-before-stop` | Geçerli dal için bir çekme isteği gerektirin. | +| `require-no-conflicts-before-stop` | Yapılandırılmış temel dala karşı temiz bir birleştirme gerektirin. | +| `require-ci-green-before-stop` | Geçerli-HEAD CI denetimlerinin başarıyla tamamlanmasını gerektirin. | ## Parametre referansı -Seçilen kapsamın `policyParams` nesnesi altında parametreleri yapılandırın. Türler her politika tarafından doğrulanır. +Seçilen kapsamın `policyParams` nesnesi altında parametreleri yapılandırın. Türler her politika tarafından doğrulanmaktadır. | Politika | Parametre | Tür ve varsayılan | | --- | --- | --- | -| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; girişler `regex` ve `label` içerir | +| `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; girdiler `regex` ve `label` içerir | | `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | | `block-sudo` | `allowPatterns` | `string[]`, `[]` | | `block-rm-rf` | `allowPaths` | `string[]`, `[]` | @@ -125,5 +125,5 @@ Seçilen kapsamın `policyParams` nesnesi altında parametreleri yapılandırın ``` - İzin deseni, bir aracının yapabileceği işlemleri genişletir. Bunu bir filo genelinde dağıtmadan önce tam jetonlaştırma ve komut varyasyonlarını hedef harness üzerinde test edin. + İzin deseni, bir aracının yapabileceği işleri genişletir. Hedef sistem üzerinde tam tokenleşmeyi ve komut varyantlarını test edin ve bunu bir filoyu karşısında dağıtmadan önce doğrulayın. \ No newline at end of file diff --git a/docs/tr/policies/failure-behavior.mdx b/docs/tr/policies/failure-behavior.mdx index 45efee62..81458dd1 100644 --- a/docs/tr/policies/failure-behavior.mdx +++ b/docs/tr/policies/failure-behavior.mdx @@ -1,19 +1,20 @@ --- +--- title: "Hata davranışı" -description: "İlke değerlendirmesi veya yerel daemon kullanılamadığında ne olacağını anlayın." +description: "İlke değerlendirmesi veya yerel daemon'un kullanılamadığı durumları anlayın." icon: "shield-alert" --- -Failproof AI, bir zorlama hatasının görünür olması için tasarlanmıştır; riskli çalışmaya sessizce izin verilmez. +Failproof AI, bir zorlama hatasının sessizce riskli işlere izin vermek yerine görünür olması için tasarlanmıştır. -## Başarısız-kapalı bir engeli tanıla +## Başarısızlık-kapalı engeli tanılayın - - 1. **Admin → enforcement** seçeneğine gidin ve makineyi açın. - 2. Son check-in, atanan dağıtım ve bildirilen dağıtımını kontrol edin. - 3. **Observe → policy** seçeneğine gidin ve reddedilen kararın oturumunu açın. - 4. Nedenin daemon erişilebilirliği, sürüm uyumsuzluğu veya ilkenin kendisini bildirip bildirmediğini doğrulayın. + + 1. **Admin → enforcement** bölümüne gidin ve makineyi açın. + 2. Son check-in zamanını, atanmış deployment'ını ve bildirilen deployment'ını kontrol edin. + 3. **Observe → policy** bölümüne gidin ve reddedilen kararın oturumunu açın. + 4. Nedenin daemon erişilebilirliğini, sürüm uyumsuzluğunu veya ilkenin kendisini bildirip bildirmediğini doğrulayın. @@ -23,21 +24,45 @@ Failproof AI, bir zorlama hatasının görünür olması için tasarlanmıştır failproofai config ``` - `failproofai config` komutunu yeniden çalıştırmak, paket yükseltmesinden sonra daemon'u güncelleştirir ve yeniden başlatır. + `failproofai config` komutu paket yükseltmesinden sonra daemon'u günceller ve yeniden başlatır. -`failproofaid` kullanacak şekilde yapılandırılmış bir makinede, daemon tek değerlendiricisidir. Erişilemezse veya protokol sürümü CLI ile eşleşmezse, hook değerlendirmesi başarısız-kapalı olur. İşlem, operatörü daemon'u kontrol etmeye veya güncellemeye yönlendiren bir nedenle reddedilir. +`failproofaid` kullanacak şekilde yapılandırılmış bir makinede, daemon tek değerlendiricidir. Erişilemez ise veya protokol sürümü CLI ile eşleşmez ise, hook değerlendirmesi kapalı durumda başarısız olur. İşlem, operatörü daemon'u kontrol etmeye veya güncelleştirmeye yönlendiren bir nedenle reddedilir. -Daemon yapılandırmasından önce, hook'lar ilkeleri işlem içinde değerlendirir. Daemon yapılandırması kaydedildikten sonra, Failproof AI daemon başarısız olduğunda sessizce ikinci bir değerlendiriciye geri dönmez. +Daemon yapılandırmasından önce, hook'lar ilkeleri işlem içinde değerlendirir. Daemon yapılandırması kaydedildikten sonra, Failproof AI daemon başarısız olduğunda ikinci bir değerlendirici'ye sessizce geri dönmez. -## Başarısız-kapalı bir kararla yanıt ver +## Başarısızlık-kapalı karara yanıt verin 1. `failproofai config --status` komutunu çalıştırın. -2. Sürümler farklıysa, paketi güncelledikten sonra `failproofai config` komutunu yeniden çalıştırın. -3. Daemon erişilemezse, hizmet durumunu ve yerel günlükleri inceleyin. -4. Bilinen bir ilke değerlendirme yolu sağlıklı olduktan sonra, agent çalışmasını sürdürün. +2. Sürümler farklı ise, paketi güncelledikten sonra `failproofai config` komutunu çalıştırın. +3. Daemon erişilemez ise, hizmet durumunu ve yerel günlükleri inceleyin. +4. Bilinen bir ilke değerlendirmesi yolu sağlıklı olana kadar aracı işini devam ettirin. - Engellenen işlemi tekrar tekrar denemeyin. Başarısız-kapalı bir yanıt, sistemin işlemin güvenli olduğunu tespit edemediği anlamına gelir. - \ No newline at end of file + Engellenen işemi tekrarlı olarak denemeyin. Başarısızlık-kapalı yanıt, sistemin işlemin güvenli olduğunu doğrulayamadığı anlamına gelir. + + +## Bir paket yüklenmeyecek + +Bir paket zorunlu kılmak için söylenen ve çalıştıramayan bir makine, sessizce devam etmek yerine reddeder. Tetikleyici **kaydedilmiş bir beklenti**dir, hiçbir zaman boş değildir: kurulu paketi olmayan bir makine sessizdir, ancak bildirilen ve çözülmeyecek olan veya manifestinin bildirdiğinden daha az tescil eden bir paket reddeder. + +Reddetme **dar kapsamlı**dır, ulaşılamayan daemon'dan farklı olarak. Ulaşılamayan bir daemon hiçbir değerlendirme yapılmadığı anlamına gelir, bu nedenle hiçbir şey güvenli olarak bilinemez. Yüklenmeyecek bir pakette, her bildirilen ilke kendi `match`'e sahip olduğu için numaralandırılabilir eksik guardlar kümesi vardır — bu nedenle yalnızca bu ilkelerin kapsadığı olaylar ve araçları reddeder, diğer her şey devam eder. + +Aşağıdakiler için tetiklenmez: + +- yapısı gereği değerlendiren ve atan `observe` paketi +- asla almadığınız veya açıkça kapattığınız ilkeler +- yükleyicinin hiçbir zaman almadığı paket; burada "kayıt yok" bilinçli atlamadan ayrılamaz +- aktif bir oturum pausu +- bir yükleme timeout'u, bu geçici — bir yavaş disk anı sorun çözene kadar reddetmemelidir + +`UserPromptSubmit` eksik ilkenin ne bildirdiğine bakılmaksızın reddetten ziyade **talimatlar** verir. Genel bir reddetme, sorunun çözülmesini sağlayabilecek aracıyı kilitleyerek ilerler. + +### Ne yapmalı + +```bash +failproofai pack list +``` + +Yüklenmeyecek olan kurulu paketleri adlandırır, nedenini söyler ve sıfır olmayan bir değer döndürerek çıkış yapar. Daha sonra ya yeniden yükleyin (`failproofai pack add `) ya da kaldırın (`failproofai pack remove `) — kaldırılması beklentiyi geri çeker ve reddetme bununla birlikte durur. \ No newline at end of file diff --git a/docs/tr/policies/packs.mdx b/docs/tr/policies/packs.mdx new file mode 100644 index 00000000..73169d70 --- /dev/null +++ b/docs/tr/policies/packs.mdx @@ -0,0 +1,110 @@ +--- +title: "Policy paketleri" +description: "GitHub sürümü olarak yayınlanan bir politika setini kurun ve uygulamayı yönetin." +icon: "package" +--- + +Paket, GitHub sürümü olarak yayınlanan bir politika setidir. Tek bir komut ile kurulur, sürümün kendi sağlama toplamları çalıştırılmadan önce doğrulanır ve paket makininizin altında değişemeyecek şekilde özet kaydedilir. + +## Failproof AI politikalarını kurun + +```bash +failproofai pack add core +``` + +Bu, pakete dahil edilen kopya'dan yayınladığımız seti kurar — bu nedenle ağ gerektirmez ve proxy arkasında başarısız olamaz. Bir kısmını alın: + +```bash +failproofai pack add core --policy block-rm-rf # bir, veya virgülle ayrılmış birkaç tane +failproofai pack add core --category dangerous-commands # bir bütün kategori +failproofai pack add core --all # içindeki her şey +``` + +`failproofai pack list` paketin sunduğu her kategoriyi adlandırır. + +## Kurulmadan önce bir paketin içini görün + +```bash +failproofai pack list acme/support-agent +``` + +Paketin taşıdığı her politikayı, kategoriye göre gruplandırarak listeler ve yazarının varsayılan olarak hangileri açtığını ve hangilerin isteğe bağlı olduğunu işaretler. **Yalnızca manifesto'yu okur** — giriş yapıtı hiçbir zaman indirilmez ve hiçbir zaman içe aktarılmaz, bu nedenle bir yabancının paketine bakmak bir yabancının kodunu çalıştıramaz. Manifest hâlâ sürümün kendi `SHA256SUMS` karşısında kontrol edilir, bu nedenle okuduğunuz şey kurulacak olan şeydir. + +Hiçbir kaynak olmadan `failproofai pack list` zaten burada kurulan paketleri listeler. + +## Başka birinin paketini kurun + +```bash +failproofai pack add acme/support-agent +``` + +Bunların herhangi biri çalışır — elinizde olanı yapıştırın: + +| Kaynak | Sonuç | +| --- | --- | +| `acme/support-agent` | En yeni sürüm, **çözdüğü tam etikete sabitlenir** | +| `acme/support-agent@v2.1.0` | O sürüm | +| `github:acme/support-agent@v2.1.0` | Aynısı, açıkça yazılmış | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | Aynısı, tarayıcıdan kopyalanmış | + +Etiket belirtmemek en yeni sürümü kurar **ve sabitleri**, ardından hangi etiketi seçtiğini size söyler. Kaydedilen her şey her zaman tam olarak bir sürümü adlandırır, bu nedenle yeniden kurulum sapamaz. + +## Bir paketin bir kısmını alın + +Varsayılan olarak paketin **kendi** varsayılanlarını alırsınız — yazarının gözetimsiz açmaya emniyetli olarak işaretlediği politikalar — içerdiği her şey değil. + +```bash +failproofai pack add acme/support-agent --category billing,git +failproofai pack add acme/support-agent --policy block-refunds +failproofai pack add acme/support-agent --all +``` + +`--category` ve `--policy` birleşim olarak birleşir (`--only` , `--policy` için eş anlamlı olarak kabul edilir). Daha yeni bir sürümde yeniden eklemek, seçtiğiniz şeyi tutar ve geri kalanı yeniden açmaz. + +## Açık olanları yönetin + +```bash +failproofai policies # bir listede her kaynak, paketler dahil +failproofai pack list # yalnızca paketler, kategoriye göre gruplandırılmış +failproofai policies --uninstall block-refunds # bir paket politikasını kapat +failproofai policies --install block-refunds # ve tekrar aç +failproofai pack remove acme/support-agent +``` + +Düz bir ad, **bir tane varsa o ad için yerleşik** anlamına gelir. Gerektiğinde paketin kopyasını açıkça adlandırın: + +```bash +failproofai policies --uninstall acme/support-agent:block-refunds +``` + + +Bir paket, adı aynı zamanda **etkinleştirilmiş yerleşik** olan bir politika gönderirse, yerleşik çalışır ve paketin kopyası atlanır — aynı güvenlik başka türlü iki kez değerlendirilirdi. Paketin kopyasını kullanmak için yerleşikti kapatın. + + +## Failproof AI politikaları nereden geliyor + +`core` npm paketine satılan kopya'yı okur. Aynı set GitHub sürümü olarak yayınlanır, belirli bir sürüm istiyorsanız kurduğunuz şeydir: + +```bash +failproofai pack add core # bu paketten, ağ yok +failproofai pack add FailproofAI/policies # aynı set, GitHub sürümünden +``` + +## Bütünlük neler yapar ve yapmaz + +`SHA256SUMS` yapıtla aynı sürümde gönderilir, bu nedenle **imza değildir** ve onu kim yayınladığı hakkında hiçbir şey kanıtlamaz. Kanıtladığı şey, baytların o sürümün yayınladığı olanlar olduğudur — ve özet, paketi eklediğinizde kaydedilir ve her içe aktarımdan önce yeniden doğrulanır, makininizin altında bir paket değişemez. Etiketi yeniden etiketleyen veya bir varlığı değiştiren bir depo sessizce başka bir şey çalıştırmak yerine yüklenmesini durdurur. + +Kurulum zamanında paket de **bir kez içe aktarılır** ve kendi manifestosu karşısında kontrol edilir. Yapıtı ayrıştırılmayan veya bildirdiğinden başka bir şeyi kaydeden bir paket, herhangi bir şey etkinleştirilmeden önce reddedilir — temiz bir şekilde kurulu ve sonraki araç çağrısında başarısız olmak yerine. + +## Bir paket ne zaman yüklenmeyecek + +Bu makineye uygulanması söylenmiş ve çalıştırılamayan bir paket, sessizce izin vermek yerine eksik politikalarının kapsadığı olayları **reddeder**. Bkz. [Failure behavior](/tr/policies/failure-behavior). `failproofai pack list` o durumda herhangi bir paketi adlandırır ve sıfır dışı çıkar. + +## Çevrimdışı ve aynalar + +| Değişken | Etki | +| --- | --- | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Getirmeyi reddeder; zaten kurulan paketler uygulamaya devam eder | +| `FAILPROOFAI_PACK_BASE_URL` | Paket getirmeyi `github.com` yerine bir aynanın işaret etmesine yönlendirir | + +Kendi paketinizi yayınlamak: [Publish a pack](/tr/policies/publish-a-pack) bölümüne bakın. \ No newline at end of file diff --git a/docs/tr/policies/publish-a-pack.mdx b/docs/tr/policies/publish-a-pack.mdx new file mode 100644 index 00000000..45cd676f --- /dev/null +++ b/docs/tr/policies/publish-a-pack.mdx @@ -0,0 +1,91 @@ +--- +title: "Bir pack yayınla" +description: "Kendi politikalarını GitHub yayınında paylaş ve herkes kurabilsin." +icon: "upload" +--- + +Bir pack, bir GitHub yayınına bağlı üç dosyadan oluşur. `failproofai pack build`, zaten sahip olduğun bir politika dosyasından üçünü de yazar. + +## 1. Politikaları yaz + +Bir dosya, herhangi bir özel politika ile aynı API'yi kullanarak. Bir pack için iki fazladan alan önemlidir: + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-refunds", + description: "Refunds above the approved limit need a human", + category: "Billing", // groups it, and is what --category selects on + defaultEnabled: true, // switched on by a plain `pack add` + match: { events: ["PreToolUse"], tools: ["Bash"] }, + fn: async (ctx) => + String(ctx.toolInput?.command ?? "").includes("refund") + ? deny("Refunds need a human. Ask before running this.") + : allow(), +}); +``` + +`defaultEnabled`, bunu atlarsanız **false** değerini alır. Düz bir `failproofai pack add` sadece işaretlediklerini açar — bir yabancının her politikasını izinsiz yüklemek, yükleyenin kullanıcısı için yapması gereken bir karar değildir. + + +Girdi **tek bir bağımsız dosya** olmalıdır. Sadece girdi özet-sabitlenmiş olduğundan, yerel dosyaları ithal eden bir pack, özet tarafından neyin çalıştığını kapsadığını dürüstçe iddia edemez. Önce bundle et (`esbuild`, `bun build`, `rollup`) ve packı bundle'ından oluştur — `pack build` yerine getiremeyeceği bir sözü göndermek yerine yerel bir ithalatı reddeder. + + +## 2. Yayın varlıklarını oluştur + +```bash +failproofai pack build ./policies.mjs \ + --id acme/support-agent \ + --version 1.0.0 \ + --out ./dist-pack +``` + +Üç dosya yazar ve her politikayı önce **yükleyicinin kendi kurallarıyla** doğrular — bu nedenle asla yüklenemeyen bir pack burada başarısız olur, bunu düzeltebileceğin yer: + +| Dosya | Ne olduğu | +| --- | --- | +| `failproofai-pack.json` | Manifest: id, sürüm, etki ve politika başına bir girdi | +| `failproofai-pack.mjs` | Senin girdinin, kelimesi kelimesine | +| `SHA256SUMS` | Diğer ikisinin ` ` | + +Derleme sırasında reddedilir: `publisher/name` olmayan bir id, `/` içeren bir politika adı, `alwaysOn` bildiren bir politika, eksik `description`, `category` veya `match`, hiçbir şey kayıt etmeyen bir girdi ve yerel dosyaları ithal eden bir girdi. + +## 3. Bunları bir yayına ekle + +Yayını derlerken kullandığın sürümle etiketle ve üç dosyanın tamamını yayın varlıkları olarak ekle: + +```bash +gh release create 1.0.0 \ + ./dist-pack/failproofai-pack.json \ + ./dist-pack/failproofai-pack.mjs \ + ./dist-pack/SHA256SUMS +``` + +Artık herkes kurabilir: + +```bash +failproofai pack add acme/support-agent +``` + +Varlık adları sabittir — bunlar, bir tüketicinin CLI'sinin hiçbir API çağrısı ve keşif olmadan URL'lerini neyin oluşturduğudur. + +## Yeni bir sürüm göndermek + +Yeni `--version` ile derle, yeni bir yayın etiketle, üç varlığı tekrar ekle. Tüketiciler aynı `pack add` işlemini çalıştırırlar ve seçtikleri alt kümesini tutar; bir politikayı kapadıkları yükseltme sırasında kapalı kalır. + +Bir politikanın **adını** değiştirmek, kesintiye uğratan bir değişikliktir: kapatmış olduğu bir makine artık mevcut olmayan bir adı kapatıyor ve yeni ad, `defaultEnabled` söyledikleri ile varır. + +## Kullanıcılarınız neye güveniyor + +`SHA256SUMS` varlıkla aynı yayında yaşar, bu nedenle baytların yayınladığın olanlar olduğunu kanıtlar — kim olduğunu değil. Depoyu yazabilen herkes her iki dosyayı da yazabilir. Kullanıcılarınızın koruması, özet kurulum sırasında sabitlenmiş olmasıdır, bu nedenle gönderdiklerin sonrasında değiştiremez. + +Yazma erişimini kontrol ettiğin bir depodan yayınla ve bir pack yayınını bir paket yayınlamak gibi davran. + +## Zorunlu kılmadan önce gözle + +Bir manifest `"effect": "observe"` bildirebilir. Bu politikalar çalışır ve kararları **kaydedilir ve atılır** — hiçbir şey engellenmez. Yeni bir kuralı gerçek trafiğe karşı, birinin işini kesintiye uğratabilmesinden önce ölçmenin yoludur. + +```json +{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +``` \ No newline at end of file diff --git a/docs/tr/reference/failproof-cli.mdx b/docs/tr/reference/failproof-cli.mdx index 561537b8..71c1585a 100644 --- a/docs/tr/reference/failproof-cli.mdx +++ b/docs/tr/reference/failproof-cli.mdx @@ -1,14 +1,14 @@ --- title: "Failproof AI CLI" -description: "Yerel kancaları yükleyin, yerel politikaları yönetin, Bulut'a bağlanın ve yerel daemon'u işletin." +description: "Hook'ları yükleyin, yerel politikaları yönetin, Cloud'a bağlanın ve yerel daemon'u çalıştırın." icon: "terminal" --- -Yerel CLI'yi `npm install -g failproofai` ile yükleyin. Yerel politika panosunu açmak için argümansız çalıştırın. +Yerel CLI'yi `npm install -g failproofai` ile kurun. Hiçbir argüman olmadan çalıştırarak yerel politika panosunu açın. -Paket Node.js 20.9 veya daha yeni bir sürümü gerektirir. Geliştirme ve kaynak yüklemeleri için Bun 1.3 veya daha yeni bir sürüm desteklenir. `failproofai configure` ve `failproofai setup` komutları `failproofai config` için takma adlardır; `failproofai p` ise `failproofai policies` için takma addır. +Paket Node.js 20.9 veya daha yeni bir sürüm gerektirir. Geliştirme ve kaynak yüklemeleri için Bun 1.3 veya daha yeni sürüm desteklenir. `failproofai configure` ve `failproofai setup` komutları `failproofai config` için takma adlardır; `failproofai p` ise `failproofai policies` için takma addır. -## Makinayı ayarla +## Bir makineyi ayarlayın ```bash npm install -g failproofai @@ -20,62 +20,67 @@ failproofai policies --install failproofai config --status ``` -Yerel politika panosunu açmak için `failproofai` komutunu argümansız çalıştırın. +Hiçbir argüman olmadan `failproofai` komutunu çalıştırarak yerel politika panosunu açın. | Komut | Sonuç | | --- | --- | | `failproofai config` | Etkileşimli makine kurulumunu çalıştır | -| `failproofai config --connect --token ` | Bulut alımını ve politika teslimatını bağla | -| `failproofai config --status` | Bağlantı, daemon, teslimat ve duraklatma durumunu göster | -| `failproofai policies` | Yerleşik ve özel politikaları listele | -| `failproofai policies --install` | Kancaları yükle ve politikaları etkinleştir | -| `failproofai policy add ` | Bir yerleşik politikayı etkinleştir | -| `failproofai policy remove ` | Bir yerleşik politikayı devre dışı bırak | -| `failproofai policies --uninstall` | Politikaları devre dışı bırak veya harness kancalarını kaldır | -| `failproofai audit` | Yerel ajan geçmişini tara ve yerel denetim görünümünü aç | -| `failproofai audit --schedule [days] --email
` | Yinelenen yerel taramaları planla ve bulgularını e-postayla gönder | -| `failproofai audit --status` | Rapor adresini, aralığı ve sonraki planlanmış taramanın zamanını göster | -| `failproofai audit --no-schedule` | Yinelenen taramaları durdur, denetim geçmişini silme | +| `failproofai config --connect --token ` | Cloud giriş ve politika sunumunu bağla | +| `failproofai config --status` | Bağlantı, daemon, sunum ve duraklatma durumunu göster | +| `failproofai policies` | Yerleşik, özel, kural, paket ve Cloud tarafından yönetilen politikaları listele | +| `failproofai policies --install` | Hook'ları yükle ve politikaları etkinleştir | +| `failproofai policy add ` | Bir politikayı etkinleştir — yerleşik bir politika veya yüklenmiş bir paketten `:` | +| `failproofai policy remove ` | Bir politikayı devre dışı bırak, aynı adlandırma | +| `failproofai policies --uninstall` | Politikaları devre dışı bırak veya harness hook'larını kaldır | +| `failproofai pack list` | Yüklenmiş politika paketlerini ve her birinin taşıdığı tüm politikaları listele | +| `failproofai pack add ` | Bir politika paketini GitHub sürümünden yükle; etiket olmayan en yenisini alır ve sabitler | +| `failproofai pack add --bundled` | Yerleşik politikaları bir paket olarak bu paketten yükle, ağ olmadan | +| `failproofai pack build ` | Kendi paketiniz için üç sürüm varlığını oluştur | +| `failproofai pack remove ` | Yüklenmiş bir paketi devre dışı bırak | +| `failproofai audit` | Yerel agent geçmişini tara ve yerel denetim görünümünü aç | +| `failproofai audit --schedule [days] --email
` | Tekrarlayan yerel taramaları planla ve bulgularını e-posta ile gönder | +| `failproofai audit --status` | Rapor adresini, aralığı ve sonraki planlanan taramayı göster | +| `failproofai audit --no-schedule` | Denetim geçmişini silmeden tekrarlayan taramaları durdur | | `failproofai harness list` | Ek yakalama yollarını listele | -| `failproofai flush --wait` | Geçerli olay bobinini teslimat et | -| `failproofai backfill --since 30d` | Önceden geçen geçmişi yeniden oku | -| `failproofai config --pause [duration]` | Bir yerel oturumu varsayılan olarak 30 dakika, en fazla 8 saat için duraklat | -| `failproofai config --resume` | Duraklatılmış bir yerel oturumu devam ettir; tüm duraklamaları temizlemek için `--all` ekle | +| `failproofai flush --wait` | Geçerli olay sırasını sunum yap | +| `failproofai backfill --since 30d` | Daha önce geçen geçmişi yeniden oku | +| `failproofai config --pause [duration]` | Bir yerel oturumu varsayılan 30 dakika, en fazla 8 saat boyunca duraklatın | +| `failproofai config --resume` | Duraklatılmış bir yerel oturumu sürdür; tüm duraklatmaları temizlemek için `--all` ekle | | `failproofai update` | Paket göçlerini tamamla ve daemon'u güncelle | -| `failproofai migrate --dry-run` | Bekleyen ana dizin düzeni göçlerini önizle veya çalıştır | -| `failproofai uninstall` | Paketi kaldırmadan önce kancaları ve daemon'u kaldır | -| `failproofai --version` | Yüklü paket sürümünü yazdır | +| `failproofai migrate --dry-run` | Bekleyen ev-düzeni göçlerini önizle veya çalıştır | +| `failproofai uninstall` | Hook'ları ve daemon'u paketi kaldırmadan önce kaldır | +| `failproofai --version` | Yüklenmiş paket sürümünü yazdır | | `failproofai --help` | Komutları ve genel kullanımı göster | ## Yapılandırma bayrakları | Bayrak | Kullanım | | --- | --- | -| `--connect --token ` | Etkileşimsiz olarak bağla | +| `--connect --token ` | Etkileşimli olmayan şekilde bağlan | | `--machine-id ` | Sabit makine kimliğini ayarla | | `--machine-label ` | Pano etiketini ayarla veya değiştir | -| `--no-transcripts` | Kararları transkript içeriği olmadan gönder | -| `--disconnect` | Bulut politika çekişlerini ve olay teslimatını durdur | +| `--no-transcripts` | Transkript içeriği olmadan kararları gönder | +| `--disconnect` | Cloud politika çekmesini ve olay sunumunu durdur | | `--status` | Geçerli makine durumunu göster | -| `--pause [duration]` | Geçerli dizindeki en yeni oturumu duraklat; saniye, dakika veya saat kabul eder ve varsayılan olarak 30 dakikaya ayarlanır | -| `--resume` | Eşleşen bir duraklamayı erken sonlandır | -| `--session ` | Duraklatma veya devam etme için açık bir oturumu hedefle | -| `--all` | `--resume` ile beraber, aktif tüm duraklamaları sonlandır | +| `--pause [duration]` | Geçerli dizinde en yeni oturumu duraklatın; saniye, dakika veya saat kabul eder ve varsayılan 30 dakikadır | +| `--resume` | Eşleşen bir duraklatmayı erken sonlandır | +| `--session ` | Duraklatma veya devam ettirme için açık bir oturum hedefle | +| `--all` | `--resume` ile birlikte, tüm etkin duraklatmaları sonlandır | -Yerel duraklamalar, bir oturum için yerleşik, özel ve konvansiyon politikalarını askıya alır. Her zaman sona erer ve Bulut tarafından yönetilen politikaları devre dışı bırakmaz. `block-self-pause` enstrümente edilmiş bir ajanın bu kaçış kapısını kendi başına kullanmasını önler. +Yerel duraklatmalar, bir oturum için yerleşik, özel, kural ve paket politikalarını askıya alır. Her zaman sona erer ve Cloud tarafından yönetilen politikaları devre dışı bırakmaz. `block-failproofai-commands` — her zaman açık olur ve kendisi devre dışı bırakılamaz veya duraklatılamaz — enstrümante edilmiş bir agent'ın bu kaçış yolunu kendisi kullanmasını engeller. ## Politika bayrakları | Bayrak | Kullanım | | --- | --- | -| `--install`, `-i` | Politikaları etkinleştir ve harness kancalarını yükle | -| `--uninstall`, `-u` | Politikaları devre dışı bırak veya kancaları kaldır | -| `--cli ` | Desteklenen bir veya daha fazla harness'i hedefle | -| `--scope user\|project\|local\|all` | Yapılandırma kapsamını seç; kaldırma için `all` seçeneği kullan | +| `--install`, `-i` | Politikaları etkinleştir ve harness hook'larını yükle | +| `--uninstall`, `-u` | Politikaları devre dışı bırak veya hook'ları kaldır | +| `--cli ` | Bir veya daha fazla desteklenen harness'i hedefle | +| `--scope user\|project\|local\|all` | Yapılandırma kapsamını seç; `all` kaldırma için kullanılır | | `--beta` | Beta politikalarını dahil et | -| `--custom`, `-c ` | Özel politika dosyasını doğrula ve yükle; tekrarlanabilir | +| `--custom`, `-c ` | Özel bir politika dosyasını doğrula ve yükle; tekrarlanabilir | -## Teslimat ve bakım bayrakları +## Sunum ve bakım bayrakları | Komut | Bayraklar | | --- | --- | @@ -85,7 +90,7 @@ Yerel duraklamalar, bir oturum için yerleşik, özel ve konvansiyon politikalar | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` komutu `npm install -g failproofai@latest` komutundan sonra çalıştırılmalıdır; ana dizin düzeni göçlerini gerçekleştirir, eşleşen daemon ikili dosyasını yükler ve hizmeti yeniden başlatır. `--no-daemon` yalnızca düzen göçünü gerçekleştirir. +`failproofai update`, `npm install -g failproofai@latest` sonrası çalıştırılmalıdır; ev-düzeni göçlerini gerçekleştirir, eşleşen daemon ikili dosyasını yükler ve hizmeti yeniden başlatır. `--no-daemon` yalnızca düzeni göçü gerçekleştirir. ## Harness yolları @@ -95,11 +100,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -Desteklenen harness adları `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` ve `goose` dir. +Desteklenen harness adları `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` ve `goose`'tur. -Etiketler, iki kök aynı projenin kopyalarını içerdiğinde türetilen ajan kimliklerini ad alanına koyar. Çakışan kökler ve yinelenen etiketler, yinelenen toplanmayı veya imleç bozulmasını önlemek için reddedilir. Ek yol yapılandırması daemon yeniden başlatması olmadan yeniden yüklenir. +Etiketler, iki kök aynı projenin kopyalarını içerdiğinde türetilmiş agent kimliklerini ad alanı içinde tutar. Çakışan kökler ve yinelenen etiketler, yinelenen koleksiyonu veya imleç bozulmasını önlemek için reddedilir. Ek yol yapılandırması, daemon yeniden başlatması olmadan yeniden yüklenir. -Kapsayıcı ortamları dosya yapılandırılmış ek yolları `FAILPROOFAI__EXTRA_PATHS` adlı virgülle ayrılmış bir değişkenle değiştirebilir, örneğin: +Konteyner ortamları dosya tarafından yapılandırılan ek yolları `FAILPROOFAI__EXTRA_PATHS` adında virgülle ayrılmış bir değişkenle değiştirebilir, örneğin: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -107,26 +112,28 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## Ortam değişkenleri -Kalıcı makine davranışı için yapılandırma dosyalarını kullanın. Ortam değişkenleri kapsayıcılar, testler ve tek işlem için en faydalıdır. +Kalıcı makine davranışı için yapılandırma dosyalarını kullanın. Ortam değişkenleri konteynerler, testler ve tek bir işlem için en kullanışlı olanıdır. | Değişken | Kullanım | | --- | --- | -| `FAILPROOFAI_HOME` | Tamamen `~/.failproofai` düzenini yeniden konumlandır | -| `FAILPROOFAI_LOG_LEVEL` | Yerel günlükleme ayrıntılılığını ayarla | -| `FAILPROOFAI_HOOK_LOG_FILE` | Kanca tanılamalarını seçilen bir dosyaya yaz | +| `FAILPROOFAI_HOME` | Tam `~/.failproofai` düzenini yer değiştir | +| `FAILPROOFAI_LOG_LEVEL` | Yerel günlük ayrıntılı düzeyini ayarla | +| `FAILPROOFAI_HOOK_LOG_FILE` | Hook tanılamalarını seçilen bir dosyaya yaz | | `FAILPROOFAI_TELEMETRY_DISABLED=1` | Bu işlem için anonim telemetriyi devre dışı bırak | | `FAILPROOFAI_NO_FIRST_RUN=1` | Etkileşimli ilk çalıştırma kurulumunu atla | | `FAILPROOFAI_NO_AUTO_AUDIT=1` | Kurulum sonrası yerel denetimi atla | -| `FAILPROOFAI_LLM_BASE_URL` | LLM politikaları tarafından kullanılan OpenAI uyumlu uç noktayı geçersiz kıl | +| `FAILPROOFAI_LLM_BASE_URL` | LLM politikaları tarafından kullanılan OpenAI uyumlu uç noktasını geçersiz kıl | | `FAILPROOFAI_LLM_API_KEY` | LLM politikaları tarafından kullanılan API anahtarını sağla | | `FAILPROOFAI_LLM_MODEL` | LLM politikaları tarafından kullanılan modeli seç | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Özel politika modülü yüklemesini sınırla | -| `FAILPROOFAI__EXTRA_PATHS` | Yapılandırılmış ek yakalama yollarını bir harness için değiştir | -| `NO_COLOR` | Renkli terminal çıktısını devre dışı bırak | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Özel politika modülü yüklemeyi sınırla | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Paket ve daemon ikili dosyaları getirmeyi reddet; yüklenmiş olan enformasyon uygulamaya devam eder | +| `FAILPROOFAI_PACK_BASE_URL` | `github.com` yerine bir aynadan paketleri getir | +| `FAILPROOFAI__EXTRA_PATHS` | Bir harness için yapılandırılmış ek yakalama yollarını değiştir | +| `NO_COLOR` | Renkli terminal çıkışını devre dışı bırak | -`CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` ve `OPENCLAW_HOME` gibi ajena özgü ana dizin değişkenleri, Failproof AI'nin bu harness için yerel oturumları nerede keşfettiğini geçersiz kılar. +`CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` ve `OPENCLAW_HOME` gibi agent'a özgü ev değişkenleri, Failproof AI'nin bu harness için yerel oturumları bulduğu yeri geçersiz kılar. -## Bir makinayı güvenle duraklat veya kaldır +## Bir makineyi güvenli bir şekilde duraklatın veya kaldırın ```bash failproofai config --pause @@ -134,9 +141,9 @@ failproofai config --status failproofai config --resume ``` -Yerel bir oturum duraklaması, Bulut tarafından yönetilen politikaları devre dışı bırakmaz. Rollout'ın kendisi sorun olduğunda Bulut enforasyon iş akışı aracılığıyla Bulut dağıtımlarını geri yükleyin. +Yerel oturum duraklatması, Cloud tarafından yönetilen politikaları devre dışı bırakmaz. Sorun dağıtımın kendisi olduğunda, Cloud enforcement iş akışı aracılığıyla Cloud dağıtımlarını geri yükleyin. -npm paketini kaldırmadan önce yüklü kancaları ve daemon'u kaldırın: +npm paketini kaldırmadan önce, yüklenmiş hook'ları ve daemon'u kaldırın: ```bash failproofai uninstall --dry-run @@ -147,5 +154,5 @@ npm rm -g failproofai Sürüme özgü ayrıntılar için `failproofai --help` komutunu çalıştırın. - `npm rm -g failproofai` komutundan önce `failproofai uninstall` komutunu çalıştırın; npm yüklü ajan kancalarını veya daemon hizmetini kaldırmaz. + `npm rm -g failproofai` öncesinde `failproofai uninstall` komutunu çalıştırın; npm yüklenmiş agent hook'larını veya daemon hizmetini kaldırmaz. \ No newline at end of file diff --git a/docs/tr/start/quickstart.mdx b/docs/tr/start/quickstart.mdx index a5f8d7af..f531abeb 100644 --- a/docs/tr/start/quickstart.mdx +++ b/docs/tr/start/quickstart.mdx @@ -1,27 +1,27 @@ --- title: "Hızlı Başlangıç" -description: "Bir agent oturumunu yakala, bir hatayı bul ve onu önlemeye başla." +description: "Bir agent oturumunu yakalayın, bir hatayı bulun ve onu önlemeye başlayın." icon: "zap" --- -Bu hızlı başlangıç, bir makinenin oturum raporlaması sağlar, bir denetim çalıştırır ve bir politika dağıtır. Failproof AI'ı kurmak için beceriyi kullanın veya manuel adımları izleyin. +Bu hızlı başlangıç, bir makinenin oturumları raporlamasını sağlar, bir denetim çalıştırır ve bir politika dağıtır. Failproof AI'ı kurmak için beceriyi kullanın veya manuel adımları izleyin. -**Hangi yol sizin?** Agent'ınız desteklenen 12 [harness](/tr/reference/harnesses) türünden birinde çalışıyorsa — bir kodlama CLI'sı veya Hermes ya da OpenClaw gibi bir gateway — aşağıdaki adımları izleyin; Node.js 20.9 veya daha sonraki bir sürüme ihtiyacınız vardır. Agent'ınızın bir harness'i yoksa, izleme ve denetimler için [Python SDK](/tr/reference/custom-agents) ile araçlandırın, ardından [İlk başarısızlık kontrolünü çalıştır](/tr/start/first-audit) kısmında tekrar başlayın; bu yoldaki zorlamalar çalışma zamanınızda bir hook gerektirir. +**Sizin yolunuz hangisi?** Agent'ınız desteklenen 12 [harness'ten](/tr/reference/harnesses) birinde çalışıyorsa — bir kodlama CLI'si veya Hermes ya da OpenClaw gibi bir ağ geçidi — aşağıdaki adımları izleyin; Node.js 20.9 veya sonrası gereklidir. Agent'ınızın harness'i yoksa, izleme ve denetim için [Python SDK](/tr/reference/custom-agents) ile enstrüman edin, ardından [İlk hatanızı kontrol etmeyi çalıştırın](/tr/start/first-audit) bölümüne dönün; bu yoldaki zorlama, çalışma zamanınızda bir hook gerektirir. - + - + ```bash npx skills add FailproofAI/skills ``` - + ```text Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Agent'ınız projeyi inceler, ilgili entegrasyonu seçer, kurulumu gerçekleştirir ve doğrular. Bireysel beceriler ve gelişmiş kurulum seçenekleri için [FailproofAI beceriler deposuna](https://github.com/FailproofAI/skills) bakın. + Agent'ınız projeyi inceler, ilgili entegrasyonu seçer, kurulumu gerçekleştirir ve doğrular. Bireysel beceriler ve gelişmiş kurulum seçenekleri için [FailproofAI beceri deposu](https://github.com/FailproofAI/skills) bölümüne bakın. @@ -29,25 +29,25 @@ Bu hızlı başlangıç, bir makinenin oturum raporlaması sağlar, bir denetim ## Başlamadan önce 1. [Failproof AI panosunu](https://app.befailproof.ai) açın ve bir hesap oluşturun veya iş e-postanızla oturum açın. -2. **Administration → Keys** bölümüne gidin ve `events:add` ve `policies:pull` izinleriyle bir anahtar oluşturun. -3. Tek seferlik sırrı kopyalayın ve hedef makinede saklayın: +2. **Yönetim → Anahtarlar** bölümüne gidin ve `events:add` ve `policies:pull` izinleriyle bir anahtar oluşturun. +3. Bir kerelik sırrı kopyalayın ve hedef makinede saklayın: ```bash export FAILPROOFAI_KEY="" ``` - ## Yükle + ## Yükleme - + ```bash npm install -g failproofai failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - Oturum transkriptleri varsayılan olarak gönderilir. Transkript içeriği olmadan hook aktivitesi ve politika kararlarını raporlamak için `--no-transcripts` ekleyin. + Oturum transkriptleri varsayılan olarak gönderilir. Transkript içeriği olmadan hook etkinliğini ve politika kararlarını raporlamak için `--no-transcripts` ekleyin. - Bu makinede zaten agent geçmişi varsa, son yedi günü önizleyin ve içeri aktarın, ardından teslimi bitirmesini bekleyin. Yeni bir makinede bu adımı atlayın. + Bu makinenin zaten agent geçmişi varsa, son yedi günü önizleyin ve içeri aktarın, ardından teslimin bitmesini bekleyin. Yeni bir makinede bu adımı atlayın. ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +55,30 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - Failproof AI'da **Sessions** bölümünü açın ve içeri aktarılan bir oturumu seçin. + Failproof AI'da **Oturumlar** bölümünü açın ve içeri aktarılan bir oturum seçin. - - Bu, Failproof AI'ı harness'inize bağlar ve 40 yerleşik politikayı yükler. Yerel politika kararlarını görmek ve Failproof AI oturumlarınızı denetlemesi ve agent'larınız için politika yazması öncesinde zorlamayı denemek için bunları kullanın. + + Bu, Failproof AI'ı harness'ize bağlar ve 39 yerleşik politikayı yükler. Yerel politika kararlarını görmek ve Failproof AI oturumlarınızı denetlemeden ve agent'larınız için politikalar yazmadan önce zorlama denemek için bunları kullanın. - Yükleyicinin harness'inizi algılamasına izin verin veya açıkça bir tane adlandırın. 12'nin her biri geçerli bir `--cli` değeridir — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + Kurulucunun harness'inizi algılamasına izin verin veya açıkça adını belirtin. 12'nin her biri geçerli bir `--cli` değeridir — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash - failproofai policies --install --cli claude --scope user # bir kodlama CLI'sı - failproofai policies --install --cli hermes --scope user # bir Slack/Telegram gateway'i + failproofai policies --install --cli claude --scope user # bir kodlama CLI'si + failproofai policies --install --cli hermes --scope user # bir Slack/Telegram ağ geçidi ``` - Bir tool çağrısını çalıştırılmadan önce engelleme tüm 12'de doğrulanır. Dönüş sonu kapıları 8'de doğrulanır — harness başına matrix için [enforcement capability](/tr/reference/harnesses#enforcement-capability) bölümüne bakın. + Bir tool çağrısını çalışmadan önce engelleme tüm 12'de doğrulanır. Tur sonu kapıları 8'de doğrulanır — her harness için matris için [zorlama yeteneği](/tr/reference/harnesses#enforcement-capability) bölümüne bakın. - - [İlk başarısızlık kontrolünü çalıştır](/tr/start/first-audit) bölümünü izleyin. "Agent'ın yaklaşımını değiştirmeden başarısız bir aracı yeniden denediği oturumları bul" gibi somut bir hedef kullanın. + + [İlk hatanızı kontrol etmeyi çalıştırın](/tr/start/first-audit) bölümünü izleyin. "Agent'ın yaklaşımını değiştirmeden başarısız bir tool'u tekrar denediği oturumları bulun" gibi somut bir hedef kullanın. - - [İlk başarısızlığı bir politikayla önle](/tr/start/first-policy) bölümünü izleyin. Gözlem modunda başlayın, eşleşmeleri inceleyin, ardından incelenen sürümü uygulayın. + + [İlk hatanızı bir politikayla önleyin](/tr/start/first-policy) bölümünü izleyin. Gözlem modunda başlayın, eşleşmeleri inceleyin, ardından incelenen sürümü uygulayın. - `failproofai config --status` komutunu çalıştırın. Sağlıklı bir kurulum bulut bağlantısını, daemon durumunu ve zorlamanın durdurulup durdurulmadığını rapor eder. + `failproofai config --status` komutunu çalıştırın. Sağlıklı bir kurulum bulut bağlantısını, daemon durumunu ve zorlama duraklatılıp duraklatılmadığını raportar. \ No newline at end of file diff --git a/docs/vi/policies/builtin-catalog.mdx b/docs/vi/policies/builtin-catalog.mdx index a9125a97..fcbc0ace 100644 --- a/docs/vi/policies/builtin-catalog.mdx +++ b/docs/vi/policies/builtin-catalog.mdx @@ -1,106 +1,108 @@ --- -title: "Danh mục chính sách tích hợp" -description: "Xem xét từng chính sách Failproof AI tích hợp, bao gồm kích hoạt, trạng thái được khuyến nghị và các tham số có thể cấu hình." +title: "Danh mục chính sách tích hợp sẵn" +description: "Xem lại từng chính sách Failproof AI tích hợp sẵn, kích hoạt của nó, trạng thái được khuyến nghị và các tham số có thể cấu hình." icon: "list-checks" --- -Gói được cài đặt là nguồn chân thực về tính khả dụng của chính sách. Chạy `failproofai policies` sau mỗi lần nâng cấp vì các mục danh mục và hành vi có thể thay đổi theo phiên bản gói. +Gói đã cài đặt là nguồn xác thực cho tính khả dụng của chính sách. Chạy `failproofai policies` sau mỗi lần nâng cấp vì các mục trong danh mục và hành vi có thể thay đổi theo phiên bản gói. ## Đường cơ sở được khuyến nghị -Lựa chọn được khuyến nghị của hệ thống hướng dẫn hiện tại cho phép các công cụ vệ sinh bí mật, bảo vệ môi trường, tự bảo vệ, bảo vệ chống lệnh thảm họa và bảo mật nhánh được bảo vệ: +Lựa chọn được khuyến nghị của hướng dẫn thiết lập hiện tại bật các bộ làm sạch bí mật, bảo vệ môi trường, tự bảo vệ, lệnh bảo vệ khỏi thảm họa và an toàn nhánh được bảo vệ: ```text sanitize-jwt sanitize-api-keys sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars block-env-files block-secrets-write -block-self-pause block-failproofai-commands -block-sudo block-curl-pipe-sh -block-rm-rf block-push-master -block-force-push +block-failproofai-commands block-sudo +block-curl-pipe-sh block-rm-rf +block-push-master block-force-push ``` -Đường cơ sở được khuyến nghị có ý định hẹp hơn **Tất cả**. Các chính sách cơ sở hạ tầng và quy trình công việc có thể làm gián đoạn công việc hợp lệ và chỉ nên được bật cho các kho lưu trữ và máy cần thiết. +`block-failproofai-commands` **luôn bật**. Nó được liệt kê ở trên để +hoàn chỉnh, nhưng nó được đăng ký trên mọi lần đánh giá dù có xuất hiện trong +bộ chính sách đã bật của bạn hay không, và nó không thể bị vô hiệu hóa hoặc tạm dừng — một biện pháp bảo vệ chống lại tác nhân tắt thực thi mà chính tác nhân có thể tắt không phải là một biện pháp bảo vệ. + +Được khuyến nghị có ý định hẹp hơn **Mọi thứ**. Các chính sách cơ sở hạ tầng và quy trình làm việc có thể làm gián đoạn công việc hợp lệ và nên được bật cho các kho lưu trữ và máy cần chúng. ## Bí mật và môi trường | Chính sách | Kích hoạt | Kết quả | | --- | --- | --- | -| `sanitize-jwt` | `PostToolUse` | Che khuất JWT từ đầu ra công cụ trước khi mô hình thấy chúng. | -| `sanitize-api-keys` | `PostToolUse` | Che khuất các khóa OpenAI, Anthropic, GitHub, AWS, Stripe và Google thông thường. | -| `sanitize-connection-strings` | `PostToolUse` | Che khuất chuỗi kết nối cơ sở dữ liệu chứa thông tin xác thực. | -| `sanitize-private-key-content` | `PostToolUse` | Che khuất nội dung phần thân khóa riêng tư PEM. | -| `sanitize-bearer-tokens` | `PostToolUse` | Che khuất mã thông báo xác thực mang lại. | -| `protect-env-vars` | `PreToolUse` trên công cụ shell | Chặn các lệnh xả các biến môi trường. | +| `sanitize-jwt` | `PostToolUse` | Loại bỏ JWT khỏi đầu ra công cụ trước khi mô hình thấy chúng. | +| `sanitize-api-keys` | `PostToolUse` | Loại bỏ các khóa OpenAI, Anthropic, GitHub, AWS, Stripe và Google phổ biến. | +| `sanitize-connection-strings` | `PostToolUse` | Loại bỏ chuỗi kết nối cơ sở dữ liệu chứa thông tin xác thực. | +| `sanitize-private-key-content` | `PostToolUse` | Loại bỏ phần thân khóa riêng PEM. | +| `sanitize-bearer-tokens` | `PostToolUse` | Loại bỏ mã thông báo ủy quyền. | +| `protect-env-vars` | `PreToolUse` trên công cụ shell | Chặn các lệnh xả biến môi trường. | | `block-env-files` | `PreToolUse` | Chặn đọc và ghi các tệp `.env`. | | `block-read-outside-cwd` | `PreToolUse` trên công cụ đọc, glob, grep hoặc shell | Giữ các lần đọc bên trong thư mục làm việc của phiên. | -| `block-secrets-write` | `PreToolUse` trên công cụ ghi | Chặn ghi vào tên tệp khóa bí mật và thông tin xác thực thông thường. | +| `block-secrets-write` | `PreToolUse` trên công cụ ghi | Chặn ghi vào các tên tệp khóa bí mật và thông tin xác thực phổ biến. | ## Lệnh nguy hiểm và cơ sở hạ tầng | Chính sách | Kích hoạt | Kết quả | | --- | --- | --- | -| `block-self-pause` | `PreToolUse`, `PermissionRequest` | Ngăn chặn đại lý tạm dừng enforcement của riêng nó. | -| `block-sudo` | `PreToolUse`, `PermissionRequest` | Chặn `sudo` trừ khi mẫu cho phép khớp. | -| `block-curl-pipe-sh` | `PreToolUse` | Chặn các tập lệnh được tải xuống và đẩy trực tiếp vào shell. | +| `block-sudo` | `PreToolUse`, `PermissionRequest` | Chặn `sudo` trừ khi một mẫu cho phép khớp. | +| `block-curl-pipe-sh` | `PreToolUse` | Chặn các tập lệnh được tải xuống đưa trực tiếp vào shell. | | `block-rm-rf` | `PreToolUse` | Chặn các mẫu xóa đệ quy thảm họa. | -| `block-failproofai-commands` | `PreToolUse` | Ngăn chặn đại lý thay đổi hoặc gỡ cài đặt Failproof AI. | -| `block-kubectl` | `PreToolUse` | Kiểm soát các lệnh Kubernetes. | -| `block-terraform` | `PreToolUse` | Kiểm soát các lệnh Terraform và OpenTofu. | -| `block-aws-cli` | `PreToolUse` | Kiểm soát các lệnh AWS CLI. | -| `block-gcloud` | `PreToolUse` | Kiểm soát các lệnh Google Cloud CLI. | -| `block-az-cli` | `PreToolUse` | Kiểm soát các lệnh Azure CLI. | -| `block-helm` | `PreToolUse` | Kiểm soát các lệnh Helm. | -| `block-gh-pipeline` | `PreToolUse` | Kiểm soát các thao tác mutating GitHub CLI về quy trình công việc, chạy, hợp nhất, phát hành, bộ đệm và bí mật. | +| `block-failproofai-commands` | `PreToolUse`, `PermissionRequest` | **Luôn bật, không thể bị vô hiệu hóa.** Chặn mọi lệnh gọi CLI Failproof AI, tự tạm dừng và gỡ cài đặt trình quản lý gói. | +| `block-kubectl` | `PreToolUse` | Cửa hàng các lệnh Kubernetes. | +| `block-terraform` | `PreToolUse` | Cửa hàng các lệnh Terraform và OpenTofu. | +| `block-aws-cli` | `PreToolUse` | Cửa hàng các lệnh AWS CLI. | +| `block-gcloud` | `PreToolUse` | Cửa hàng các lệnh Google Cloud CLI. | +| `block-az-cli` | `PreToolUse` | Cửa hàng các lệnh Azure CLI. | +| `block-helm` | `PreToolUse` | Cửa hàng các lệnh Helm. | +| `block-gh-pipeline` | `PreToolUse` | Cửa hàng các hoạt động quy trình công việc, chạy, hợp nhất, phát hành, bộ nhớ đệm và bí mật GitHub CLI đang thay đổi. | ## An toàn Git và cơ sở dữ liệu | Chính sách | Kích hoạt | Kết quả | | --- | --- | --- | -| `block-push-master` | `PreToolUse` | Chặn các lần đẩy trực tiếp đến các nhánh được bảo vệ đã cấu hình. | -| `block-force-push` | `PreToolUse` | Chặn force-push; `--force-with-lease` vẫn được phép bởi triển khai hiện tại. | +| `block-push-master` | `PreToolUse` | Chặn đẩy trực tiếp đến các nhánh được bảo vệ được cấu hình. | +| `block-force-push` | `PreToolUse` | Chặn đẩy-lực; `--force-with-lease` vẫn được cho phép bằng triển khai hiện tại. | | `block-work-on-main` | `PreToolUse` | Chặn cam kết và hợp nhất trên các nhánh được bảo vệ. | -| `warn-git-amend` | `PreToolUse` | Cảnh báo trước khi viết lại commit với `--amend`. | -| `warn-git-stash-drop` | `PreToolUse` | Cảnh báo trước khi vĩnh viễn bỏ hoặc xóa stash. | -| `warn-all-files-staged` | `PreToolUse` | Cảnh báo trên `git add -A`, `git add .` hoặc `git add --all` rộng rãi. | -| `warn-destructive-sql` | `PreToolUse` | Cảnh báo trên `DROP`, `TRUNCATE` và `DELETE` không có `WHERE` thông qua các máy khách cơ sở dữ liệu đã biết. | -| `warn-schema-alteration` | `PreToolUse` | Cảnh báo trên các thao tác `ALTER TABLE` cột được công nhận và đổi tên. | +| `warn-git-amend` | `PreToolUse` | Cảnh báo trước khi viết lại cam kết bằng `--amend`. | +| `warn-git-stash-drop` | `PreToolUse` | Cảnh báo trước khi vĩnh viễn thả hoặc xóa các stash. | +| `warn-all-files-staged` | `PreToolUse` | Cảnh báo về `git add -A` rộng, `git add .` hoặc `git add --all`. | +| `warn-destructive-sql` | `PreToolUse` | Cảnh báo về `DROP`, `TRUNCATE` và `DELETE` không có `WHERE` thông qua các máy khách cơ sở dữ liệu được công nhận. | +| `warn-schema-alteration` | `PreToolUse` | Cảnh báo về các hoạt động đổi tên và cột `ALTER TABLE` được công nhận. | -## Gói, hành vi hệ thống và vòng lặp đại lý +## Gói, hành vi hệ thống và vòng lặp tác nhân | Chính sách | Kích hoạt | Kết quả | | --- | --- | --- | -| `warn-package-publish` | `PreToolUse` | Cảnh báo trước khi xuất bản vào kho lưu trữ gói. | +| `warn-package-publish` | `PreToolUse` | Cảnh báo trước khi xuất bản vào các sổ đăng ký gói. | | `warn-global-package-install` | `PreToolUse` | Cảnh báo trước khi cài đặt gói toàn cục. | -| `prefer-package-manager` | `PreToolUse` | Hướng dẫn đại lý sử dụng trình quản lý gói được phép. | -| `warn-large-file-write` | `PreToolUse` trên công cụ ghi | Cảnh báo trên ngưỡng kích thước tệp đã cấu hình. | -| `warn-background-process` | `PreToolUse` | Cảnh báo trên các mẫu quy trình nền tách hoặc lâu dài. | -| `warn-repeated-tool-calls` | `PreToolUse` | Cảnh báo sau ba hoặc nhiều lệnh công cụ giống hệt nhau. | +| `prefer-package-manager` | `PreToolUse` | Hướng dẫn tác nhân sử dụng trình quản lý gói được phép. | +| `warn-large-file-write` | `PreToolUse` trên công cụ ghi | Cảnh báo trên ngưỡng kích thước tệp được cấu hình. | +| `warn-background-process` | `PreToolUse` | Cảnh báo về các mẫu quy trình nền được tách rời hoặc dài hạn. | +| `warn-repeated-tool-calls` | `PreToolUse` | Cảnh báo sau ba lần hoặc nhiều lần gọi công cụ giống hệt nhau. | -## Quy trình công việc cuối nhiệm vụ +## Quy trình làm việc kết thúc nhiệm vụ -Các chính sách này yêu cầu một harness phát ra sự kiện `Stop` tương thích. +Các chính sách này yêu cầu một giàn giáo phát ra sự kiện `Stop` tương thích. | Chính sách | Kết quả | | --- | --- | -| `require-commit-before-stop` | Từ chối hoàn thành trong khi công việc được theo dõi vẫn chưa được cam kết. | -| `require-push-before-stop` | Từ chối hoàn thành trong khi cam kết vẫn chỉ ở địa phương. | +| `require-commit-before-stop` | Từ chối hoàn thành khi công việc được theo dõi vẫn chưa được cam kết. | +| `require-push-before-stop` | Từ chối hoàn thành khi cam kết vẫn chỉ ở cục bộ. | | `require-pr-before-stop` | Yêu cầu yêu cầu kéo cho nhánh hiện tại. | -| `require-no-conflicts-before-stop` | Yêu cầu hợp nhất sạch chống lại nhánh cơ sở đã cấu hình. | +| `require-no-conflicts-before-stop` | Yêu cầu hợp nhất sạch chống lại nhánh cơ sở được cấu hình. | | `require-ci-green-before-stop` | Yêu cầu kiểm tra CI HEAD hiện tại hoàn thành thành công. | ## Tham chiếu tham số -Cấu hình các tham số dưới đối tượng `policyParams` của phạm vi đã chọn. Các loại được xác nhận bởi từng chính sách. +Cấu hình tham số dưới đối tượng `policyParams` của phạm vi đã chọn. Các loại được xác thực bởi từng chính sách. -| Chính sách | Tham số | Loại và mặc định | +| Chính sách | Tham số | Loại và giá trị mặc định | | --- | --- | --- | | `sanitize-api-keys` | `additionalPatterns` | `pattern[]`, `[]`; các mục chứa `regex` và `label` | | `block-read-outside-cwd` | `allowPaths` | `string[]`, `[]` | | `block-sudo` | `allowPatterns` | `string[]`, `[]` | | `block-rm-rf` | `allowPaths` | `string[]`, `[]` | -| Các chặn cơ sở hạ tầng | `allowPatterns` | `string[]`, `[]` | +| Bộ chặn cơ sở hạ tầng | `allowPatterns` | `string[]`, `[]` | | `block-secrets-write` | `additionalPatterns` | `string[]`, `[]` | | `block-push-master` | `protectedBranches` | `string[]`, `["main", "master"]` | | `block-work-on-main` | `protectedBranches` | `string[]`, `["main", "master"]` | @@ -125,5 +127,5 @@ Cấu hình các tham số dưới đối tượng `policyParams` của phạm v ``` - Mẫu cho phép mở rộng những gì một đại lý có thể làm. Kiểm tra độ mã hóa chính xác và các biến thể lệnh trên harness đích trước khi triển khai nó trên toàn bộ hạm đội. + Một mẫu cho phép mở rộng những gì một tác nhân có thể làm. Kiểm tra tokenization chính xác và các biến thể lệnh trên giàn giáo mục tiêu trước khi triển khai nó trên toàn bộ hạm đội. \ No newline at end of file diff --git a/docs/vi/policies/failure-behavior.mdx b/docs/vi/policies/failure-behavior.mdx index e4fc4d1f..40d60830 100644 --- a/docs/vi/policies/failure-behavior.mdx +++ b/docs/vi/policies/failure-behavior.mdx @@ -1,19 +1,20 @@ --- -title: "Hành vi khi gặp sự cố" +--- +title: "Hành vi khi bị lỗi" description: "Hiểu điều gì xảy ra khi đánh giá chính sách hoặc daemon cục bộ không khả dụng." icon: "shield-alert" --- -Failproof AI được thiết kế để một lỗi thực thi là có thể nhìn thấy được thay vì im lặng cho phép công việc rủi ro. +Failproof AI được thiết kế để khi xảy ra lỗi thực thi, nó sẽ hiển thị rõ ràng thay vì im lặng cho phép công việc rủi ro. -## Chẩn đoán một khối failure-closed +## Chẩn đoán khối từ chối do lỗi 1. Đi đến **Admin → enforcement** và mở máy. - 2. Kiểm tra lần check-in cuối cùng, deployment được gán và deployment được báo cáo. - 3. Đi đến **Observe → policy** và mở phiên của quyết định từ chối. - 4. Xác nhận xem lý do báo cáo liên quan đến khả năng tiếp cận daemon, phiên bản không khớp, hay chính sách đó. + 2. Kiểm tra lần check-in cuối cùng, triển khai được gán và triển khai được báo cáo của nó. + 3. Đi đến **Observe → policy** và mở phiên của quyết định bị từ chối. + 4. Xác nhận xem lý do có báo cáo khả năng tiếp cận daemon, phiên bản không khớp hay chính sách đó. @@ -27,17 +28,41 @@ Failproof AI được thiết kế để một lỗi thực thi là có thể nh -Trên một máy được cấu hình để sử dụng `failproofaid`, daemon là bộ đánh giá duy nhất. Nếu nó không thể tiếp cận được hoặc phiên bản giao thức của nó không khớp với CLI, đánh giá hook sẽ thất bại. Hành động bị từ chối với một lý do hướng dẫn người vận hành kiểm tra hoặc cập nhật daemon. +Trên máy được cấu hình để sử dụng `failproofaid`, daemon là trình đánh giá duy nhất. Nếu nó không thể tiếp cận hoặc phiên bản giao thức của nó không khớp với CLI, đánh giá hook sẽ thất bại và từ chối. Hành động bị từ chối kèm theo lý do hướng dẫn người vận hành kiểm tra hoặc cập nhật daemon. -Trước khi cấu hình daemon, hook đánh giá chính sách trong quá trình. Sau khi cấu hình daemon được ghi lại, Failproof AI không im lặng quay lại bộ đánh giá thứ hai khi daemon gặp sự cố. +Trước khi cấu hình daemon, hook sẽ đánh giá chính sách trong quá trình xử lý. Khi cấu hình daemon được ghi lại, Failproof AI sẽ không im lặng quay lại trình đánh giá thứ hai khi daemon bị lỗi. -## Phản ứng với quyết định failure-closed +## Đối ứng với quyết định từ chối do lỗi 1. Chạy `failproofai config --status`. -2. Nếu các phiên bản khác nhau, chạy lại `failproofai config` sau khi cập nhật gói. -3. Nếu daemon không thể tiếp cận được, kiểm tra trạng thái dịch vụ và nhật ký cục bộ. -4. Tiếp tục công việc agent chỉ sau khi một đường dẫn đánh giá chính sách đã biết là khỏe mạnh. +2. Nếu các phiên bản khác nhau, hãy chạy lại `failproofai config` sau khi cập nhật gói. +3. Nếu daemon không thể tiếp cận, hãy kiểm tra trạng thái dịch vụ của nó và nhật ký cục bộ. +4. Chỉ tiếp tục công việc agent sau khi một đường dẫn đánh giá chính sách đã biết khỏe mạnh. - Không lặp đi lặp lại hành động bị chặn. Một phản ứng failure-closed có nghĩa là hệ thống không thể xác định rằng hành động là an toàn. - \ No newline at end of file + Không thử lại hành động bị chặn nhiều lần. Một phản hồi từ chối do lỗi có nghĩa là hệ thống không thể thiết lập rằng hành động là an toàn. + + +## Một gói sẽ không tải + +Máy được yêu cầu thực thi một gói nhưng không thể chạy nó sẽ từ chối thay vì tiếp tục im lặng. Kích hoạt là một **kỳ vọng được ghi lại**, không bao giờ là kỳ vọng trống: máy không có gói nào được cài đặt sẽ im lặng, trong khi một gói được khai báo nhưng sẽ không được phân giải — hoặc đăng ký ít hơn khai báo của nó — sẽ từ chối. + +Sự từ chối **hẹp**, không giống như daemon không thể tiếp cận. Daemon không thể tiếp cận có nghĩa là không có đánh giá nào xảy ra, vì vậy không gì có thể được biết là an toàn. Một gói không tải được có một tập hợp các bảo vệ bị thiếu có thể liệt kê, vì mỗi chính sách được khai báo đều mang theo `match` riêng — vì vậy nó chỉ từ chối các sự kiện và công cụ mà những chính sách đó bao quát, và mọi thứ khác diễn ra bình thường. + +Nó không kích hoạt cho: + +- gói `observe`, được đánh giá và loại bỏ theo cấu trúc +- chính sách bạn không bao giờ lấy, hoặc rõ ràng tắt +- gói mà trình tải không bao giờ nhận được, trong đó không thể phân biệt "không có đăng ký" và một bỏ qua có chủ đích +- tạm dừng phiên hoạt động +- hết thời gian tải, đây là tạm thời — một khoảnh khắc đĩa chậm không được từ chối cho đến khi con người can thiệp + +`UserPromptSubmit` **hướng dẫn** thay vì từ chối, bất kể chính sách bị thiếu đã khai báo gì. Một lệnh từ chối toàn diện sẽ đi kèm nó và khóa bạn không thể dùng agent có thể khắc phục sự cố. + +### Cần làm gì + +```bash +failproofai pack list +``` + +Nó liệt kê bất kỳ gói được cài đặt nào sẽ không tải, cho biết tại sao, và thoát với mã khác không. Sau đó hãy cài đặt lại nó (`failproofai pack add `) hoặc xóa nó (`failproofai pack remove `) — xóa nó sẽ rút lại kỳ vọng, và sự từ chối sẽ dừng lại cùng nó. \ No newline at end of file diff --git a/docs/vi/policies/packs.mdx b/docs/vi/policies/packs.mdx new file mode 100644 index 00000000..f403e2a1 --- /dev/null +++ b/docs/vi/policies/packs.mdx @@ -0,0 +1,110 @@ +--- +title: "Gói chính sách" +description: "Cài đặt một bộ chính sách được công bố dưới dạng GitHub release, và quản lý những gì nó thực thi." +icon: "package" +--- + +Một gói là một bộ chính sách được công bố dưới dạng GitHub release. Một lệnh cài đặt nó, các checksum của chính release được xác minh trước khi bất cứ điều gì chạy, và digest được ghi lại để gói không thể thay đổi trên máy của bạn sau đó. + +## Cài đặt chính sách Failproof AI + +```bash +failproofai pack add core +``` + +Điều đó cài đặt bộ mà chúng tôi công bố, từ bản sao bên trong gói — vì vậy nó không cần mạng và không thể thất bại đằng sau proxy. Lấy một phần của nó: + +```bash +failproofai pack add core --policy block-rm-rf # một, hoặc vài cái được phân tách bằng dấu phẩy +failproofai pack add core --category dangerous-commands # toàn bộ một loại +failproofai pack add core --all # mọi thứ trong đó +``` + +`failproofai pack list` liệt kê mọi loại mà gói cung cấp. + +## Xem gói chứa gì, trước khi cài đặt nó + +```bash +failproofai pack list acme/support-agent +``` + +Liệt kê mọi chính sách mà gói mang theo, được nhóm theo loại, đánh dấu những cái nào tác giả của nó bật theo mặc định và những cái nào là tùy chọn. Nó chỉ đọc **manifest duy nhất** — artifact nhập cảnh không bao giờ được tải xuống và không bao giờ được nhập, vì vậy xem xét gói của một người lạ không thể chạy mã của một người lạ. Manifest vẫn được kiểm tra so với `SHA256SUMS` của chính release, vì vậy những gì bạn đang đọc là những gì sẽ được cài đặt. + +`failproofai pack list` không có nguồn sẽ liệt kê các gói đã cài đặt ở đây. + +## Cài đặt gói của người khác + +```bash +failproofai pack add acme/support-agent +``` + +Bất kỳ cái nào trong số này đều hoạt động — dán những cái bạn có: + +| Nguồn | Kết quả | +| --- | --- | +| `acme/support-agent` | Release mới nhất, **ghim** vào tag chính xác mà nó được phân giải | +| `acme/support-agent@v2.1.0` | Release đó | +| `github:acme/support-agent@v2.1.0` | Cái tương tự, được viết rõ ràng | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | Cái tương tự, được sao chép từ trình duyệt | + +Không đặt tên tag cài đặt release mới nhất **và ghim nó**, rồi cho bạn biết tag nào mà nó đã chọn. Những gì được ghi lại luôn đặt tên chính xác một release, vì vậy cài đặt lại không thể trôi dạt. + +## Lấy một phần của gói + +Theo mặc định bạn nhận được **các** mặc định của gói — những chính sách mà tác giả của nó đánh dấu là an toàn để bật mà không cần giám sát — không phải mọi thứ nó chứa. + +```bash +failproofai pack add acme/support-agent --category billing,git +failproofai pack add acme/support-agent --policy block-refunds +failproofai pack add acme/support-agent --all +``` + +`--category` và `--policy` kết hợp như một hợp nhất (`--only` được chấp nhận như một từ đồng nghĩa cho `--policy`). Thêm lại ở một phiên bản mới hơn giữ lại những gì bạn đã chọn thay vì chuyển phần còn lại trở lại. + +## Quản lý những gì đang bật + +```bash +failproofai policies # mọi nguồn trong một danh sách, gói bao gồm +failproofai pack list # chỉ gói, được nhóm theo loại +failproofai policies --uninstall block-refunds # tắt một chính sách gói +failproofai policies --install block-refunds # và bật lại +failproofai pack remove acme/support-agent +``` + +Một tên trần nghĩa là **builtin** khi tồn tại tên đó. Đặt tên bản sao của gói một cách rõ ràng khi bạn cần: + +```bash +failproofai policies --uninstall acme/support-agent:block-refunds +``` + + +Nếu một gói gửi một chính sách có tên cũng là một **builtin được bật**, builtin chạy và bản sao của gói bị bỏ qua — cùng một biện pháp bảo vệ nếu không sẽ được đánh giá hai lần. Tắt builtin để sử dụng bản sao của gói thay thế. + + +## Chính sách Failproof AI đến từ đâu + +`core` đọc bản sao được đưa vào trong gói npm. Cùng một bộ được công bố dưới dạng GitHub release, đó là những gì bạn cài đặt nếu bạn muốn một phiên bản cụ thể: + +```bash +failproofai pack add core # từ gói này, không có mạng +failproofai pack add FailproofAI/policies # cùng một bộ, từ GitHub release của nó +``` + +## Tính toàn vẹn làm được gì và không làm được gì + +`SHA256SUMS` được gửi trong cùng release với artifact, vì vậy nó **không** phải là một chữ ký và không chứng minh điều gì về người công bố nó. Những gì nó chứng minh là các byte là những byte mà release công bố — và vì digest được ghi lại khi bạn thêm gói và được xác minh lại trước mỗi lần nhập, một gói không thể thay đổi trên máy của bạn sau đó. Một kho lưu trữ mà retags hoặc thay thế một asset dừng tải thay vì im lặng chạy cái gì đó khác. + +Lúc cài đặt gói cũng **được nhập một lần** và được kiểm tra so với manifest của chính nó. Một gói có artifact không phân tích cú pháp, hoặc đăng ký cái gì đó khác với những gì nó khai báo, bị từ chối trước khi bất cứ điều gì được kích hoạt — thay vì cài đặt sạch sẽ và thất bại lần gọi công cụ tiếp theo của bạn. + +## Khi một gói không tải được + +Một gói mà máy này được yêu cầu thực thi và không thể chạy **từ chối** các sự kiện mà chính sách bị thiếu của nó bao gồm, thay vì cho phép chúng im lặng. Xem [Failure behavior](/vi/policies/failure-behavior). `failproofai pack list` đặt tên bất kỳ gói nào ở trạng thái đó và thoát với mã khác không. + +## Ngoại tuyến và gương + +| Biến | Hiệu ứng | +| --- | --- | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Từ chối tìm nạp; các gói đã cài đặt tiếp tục thực thi | +| `FAILPROOFAI_PACK_BASE_URL` | Chỉ lấy gói tại một gương thay vì `github.com` | + +Công bố gói của riêng bạn: xem [Publish a pack](/vi/policies/publish-a-pack). \ No newline at end of file diff --git a/docs/vi/policies/publish-a-pack.mdx b/docs/vi/policies/publish-a-pack.mdx new file mode 100644 index 00000000..d768fc71 --- /dev/null +++ b/docs/vi/policies/publish-a-pack.mdx @@ -0,0 +1,91 @@ +--- +title: "Xuất bản một pack" +description: "Gửi các policies của riêng bạn dưới dạng GitHub release mà bất kỳ ai cũng có thể cài đặt." +icon: "upload" +--- + +Một pack bao gồm ba tệp được đính kèm vào GitHub release. `failproofai pack build` viết cả ba tệp từ một tệp policy mà bạn đã có. + +## 1. Viết các policies + +Một tệp, sử dụng cùng API như bất kỳ custom policy nào. Hai trường bổ sung quan trọng cho một pack: + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-refunds", + description: "Refunds above the approved limit need a human", + category: "Billing", // groups it, and is what --category selects on + defaultEnabled: true, // switched on by a plain `pack add` + match: { events: ["PreToolUse"], tools: ["Bash"] }, + fn: async (ctx) => + String(ctx.toolInput?.command ?? "").includes("refund") + ? deny("Refunds need a human. Ask before running this.") + : allow(), +}); +``` + +`defaultEnabled` mặc định là **false** khi bạn bỏ qua nó. Một `failproofai pack add` đơn giản chỉ bật những gì bạn đã đánh dấu — cài đặt mọi policy của người lạ mà không giám sát không phải là quyết định mà trình cài đặt nên đưa ra cho người dùng của nó. + + +Mục nhập phải là **một tệp tự chứa đầy đủ**. Chỉ mục nhập được ghim digest, vì vậy một pack nhập các tệp cục bộ không thể thành thật khẳng định rằng digest bao gồm những gì chạy. Gộp lại trước (`esbuild`, `bun build`, `rollup`) và xây dựng pack từ bundle — `pack build` từ chối nhập cục bộ thay vì gửi một lời hứa mà nó không thể giữ. + + +## 2. Xây dựng release assets + +```bash +failproofai pack build ./policies.mjs \ + --id acme/support-agent \ + --version 1.0.0 \ + --out ./dist-pack +``` + +Nó viết ba tệp và xác thực mọi policy với **các quy tắc của chính trình tải** trước — vì vậy một pack không bao giờ có thể cài đặt sẽ thất bại tại đây, nơi bạn có thể sửa nó: + +| Tệp | Nó là gì | +| --- | --- | +| `failproofai-pack.json` | Manifest: id, version, effect, và một mục cho mỗi policy | +| `failproofai-pack.mjs` | Mục nhập của bạn, nguyên văn | +| `SHA256SUMS` | ` ` cho hai cái kia | + +Bị từ chối tại thời điểm xây dựng: một id không phải `publisher/name`, tên policy chứa `/`, policy khai báo `alwaysOn`, thiếu `description`, `category` hoặc `match`, mục nhập không đăng ký bất cứ điều gì, và mục nhập nhập các tệp cục bộ. + +## 3. Đính kèm chúng vào một release + +Gắn thẻ release với cùng version mà bạn đã xây dựng, và đính kèm cả ba tệp làm release assets: + +```bash +gh release create 1.0.0 \ + ./dist-pack/failproofai-pack.json \ + ./dist-pack/failproofai-pack.mjs \ + ./dist-pack/SHA256SUMS +``` + +Bất kỳ ai cũng có thể cài đặt nó ngay bây giờ: + +```bash +failproofai pack add acme/support-agent +``` + +Tên asset được cố định — đó là những gì CLI của người tiêu dùng xây dựng URL từ, không có API call và không có discovery. + +## Gửi một phiên bản mới + +Xây dựng với `--version` mới, gắn thẻ release mới, đính kèm ba asset lại. Người tiêu dùng chạy cùng `pack add` và giữ bất kỳ tập hợp con nào họ đã chọn; một policy mà họ tắt sẽ vẫn tắt trong suốt quá trình nâng cấp. + +Thay đổi **name** của một policy là một breaking change: một máy đã tắt nó sẽ tắt một tên không còn tồn tại, và tên mới đến với bất kỳ `defaultEnabled` nào. + +## Những gì người dùng của bạn đang tin tưởng + +`SHA256SUMS` sống trong cùng release như artifact, vì vậy nó chứng minh các byte là những byte bạn đã xuất bản — không phải ai bạn. Bất kỳ ai có thể ghi vào kho lưu trữ đều có thể ghi cả hai tệp. Bảo vệ của người dùng bạn là digest được ghim khi họ cài đặt, vì vậy những gì bạn gửi không thể thay đổi dưới họ sau đó. + +Xuất bản từ một kho lưu trữ mà bạn kiểm soát quyền ghi, và coi một pack release giống như xuất bản một package. + +## Quan sát trước khi bạn thực thi + +Một manifest có thể khai báo `"effect": "observe"`. Những policies đó chạy và bản án của chúng được **ghi lại và loại bỏ** — không có gì bị chặn. Đó là cách để đo lường một quy tắc mới với lưu lượng thực tế trước khi nó có thể gián đoạn công việc của bất kỳ ai. + +```json +{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +``` \ No newline at end of file diff --git a/docs/vi/reference/failproof-cli.mdx b/docs/vi/reference/failproof-cli.mdx index 76fd4ef0..bfbb37e5 100644 --- a/docs/vi/reference/failproof-cli.mdx +++ b/docs/vi/reference/failproof-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof AI CLI" -description: "Cài đặt hooks, quản lý chính sách cục bộ, kết nối Cloud, và vận hành daemon cục bộ." +description: "Cài đặt hooks, quản lý chính sách cục bộ, kết nối Cloud và vận hành daemon cục bộ." icon: "terminal" --- -Cài đặt CLI cục bộ bằng `npm install -g failproofai`. Chạy nó mà không có tham số để mở bảng điều khiển chính sách cục bộ. +Cài đặt CLI cục bộ bằng `npm install -g failproofai`. Chạy lệnh mà không có tham số để mở bảng điều khiển chính sách cục bộ. -Gói yêu cầu Node.js 20.9 trở lên. Bun 1.3 trở lên được hỗ trợ cho phát triển và cài đặt từ mã nguồn. `failproofai configure` và `failproofai setup` là bí danh cho `failproofai config`; `failproofai p` là bí danh cho `failproofai policies`. +Gói yêu cầu Node.js 20.9 hoặc mới hơn. Bun 1.3 hoặc mới hơn được hỗ trợ cho phát triển và cài đặt từ mã nguồn. `failproofai configure` và `failproofai setup` là bí danh cho `failproofai config`; `failproofai p` là bí danh cho `failproofai policies`. ## Thiết lập máy @@ -25,57 +25,62 @@ Chạy `failproofai` mà không có tham số để mở bảng điều khiển | Lệnh | Kết quả | | --- | --- | | `failproofai config` | Chạy thiết lập máy tương tác | -| `failproofai config --connect --token ` | Kết nối Cloud ingestion và chính sách phân phối | -| `failproofai config --status` | Hiển thị trạng thái kết nối, daemon, phân phối và tạm dừng | -| `failproofai policies` | Liệt kê chính sách tích hợp và tùy chỉnh | +| `failproofai config --connect --token ` | Kết nối ingestion Cloud và cung cấp chính sách | +| `failproofai config --status` | Hiển thị trạng thái kết nối, daemon, cung cấp và tạm dừng | +| `failproofai policies` | Liệt kê chính sách tích hợp, tùy chỉnh, quy ước, gói và được quản lý bởi Cloud | | `failproofai policies --install` | Cài đặt hooks và bật chính sách | -| `failproofai policy add ` | Bật một chính sách tích hợp | -| `failproofai policy remove ` | Tắt một chính sách tích hợp | -| `failproofai policies --uninstall` | Tắt chính sách hoặc xóa harness hooks | -| `failproofai audit` | Quét lịch sử agent cục bộ và mở chế độ xem kiểm toán cục bộ | -| `failproofai audit --schedule [days] --email
` | Lên lịch quét cục bộ định kỳ và gửi email kết quả | +| `failproofai policy add ` | Bật một chính sách — một chính sách tích hợp, hoặc `:` từ gói đã cài đặt | +| `failproofai policy remove ` | Tắt một chính sách, cách đặt tên giống nhau | +| `failproofai policies --uninstall` | Tắt chính sách hoặc gỡ bỏ hooks harness | +| `failproofai pack list` | Liệt kê các gói chính sách đã cài đặt và mỗi chính sách mà mỗi gói chứa | +| `failproofai pack add ` | Cài đặt gói chính sách từ bản phát hành GitHub; không có tag sẽ lấy phiên bản mới nhất và ghim nó | +| `failproofai pack add --bundled` | Cài đặt các chính sách tích hợp dưới dạng gói, từ gói này, không có mạng | +| `failproofai pack build ` | Xây dựng ba tài sản phát hành cho gói của riêng bạn | +| `failproofai pack remove ` | Hủy kích hoạt gói đã cài đặt | +| `failproofai audit` | Quét lịch sử agent cục bộ và mở chế độ xem kiểm tra cục bộ | +| `failproofai audit --schedule [days] --email
` | Lên lịch quét cục bộ định kỳ và gửi email kết quả của chúng | | `failproofai audit --status` | Hiển thị địa chỉ báo cáo, khoảng thời gian và lần quét tiếp theo được lên lịch | -| `failproofai audit --no-schedule` | Dừng quét định kỳ mà không xóa lịch sử kiểm toán | -| `failproofai harness list` | Liệt kê các đường dẫn bắt thêm | -| `failproofai flush --wait` | Phân phối spool sự kiện hiện tại | -| `failproofai backfill --since 30d` | Đọc lại lịch sử đã truyền trước đó | -| `failproofai config --pause [duration]` | Tạm dừng một phiên cục bộ trong 30 phút theo mặc định, tối đa 8 giờ | -| `failproofai config --resume` | Tiếp tục một phiên cục bộ bị tạm dừng; thêm `--all` để xóa tất cả tạm dừng | +| `failproofai audit --no-schedule` | Dừng quét định kỳ mà không xóa lịch sử kiểm tra | +| `failproofai harness list` | Liệt kê các đường dẫn chụp bổ sung | +| `failproofai flush --wait` | Cung cấp bộ spool sự kiện hiện tại | +| `failproofai backfill --since 30d` | Đọc lại lịch sử đã qua trước đây | +| `failproofai config --pause [duration]` | Tạm dừng một phiên cục bộ trong 30 phút theo mặc định, lên đến 8 giờ | +| `failproofai config --resume` | Tiếp tục một phiên cục bộ bị tạm dừng; thêm `--all` để xóa tất cả các tạm dừng | | `failproofai update` | Hoàn thành di chuyển gói và cập nhật daemon | | `failproofai migrate --dry-run` | Xem trước hoặc chạy các di chuyển bố cục trang chủ đang chờ | -| `failproofai uninstall` | Xóa hooks và daemon trước khi gỡ cài đặt gói | -| `failproofai --version` | In phiên bản gói đã cài đặt | -| `failproofai --help` | Hiển thị các lệnh và cách sử dụng toàn cục | +| `failproofai uninstall` | Gỡ bỏ hooks và daemon trước khi gỡ bỏ gói | +| `failproofai --version` | In phiên bản gói được cài đặt | +| `failproofai --help` | Hiển thị lệnh và cách sử dụng toàn cục | ## Cờ cấu hình -| Cờ | Mục đích | +| Cờ | Sử dụng | | --- | --- | | `--connect --token ` | Kết nối không tương tác | | `--machine-id ` | Đặt ID máy ổn định | | `--machine-label ` | Đặt hoặc thay đổi nhãn bảng điều khiển | -| `--no-transcripts` | Gửi quyết định mà không có nội dung ghi âm | -| `--disconnect` | Dừng kéo chính sách Cloud và phân phối sự kiện | +| `--no-transcripts` | Gửi quyết định mà không có nội dung bản ghi | +| `--disconnect` | Dừng kéo chính sách Cloud và cung cấp sự kiện | | `--status` | Hiển thị trạng thái máy hiện tại | | `--pause [duration]` | Tạm dừng phiên mới nhất trong thư mục hiện tại; chấp nhận giây, phút hoặc giờ và mặc định là 30 phút | -| `--resume` | Kết thúc tạm dừng phù hợp sớm hơn | -| `--session ` | Nhắm mục tiêu một phiên rõ ràng để tạm dừng hoặc tiếp tục | +| `--resume` | Kết thúc tạm dừng khớp sớm | +| `--session ` | Nhắm mục tiêu phiên rõ ràng để tạm dừng hoặc tiếp tục | | `--all` | Với `--resume`, kết thúc mọi tạm dừng hoạt động | -Tạm dừng cục bộ tạm ngừng chính sách tích hợp, tùy chỉnh và quy ước cho một phiên. Chúng luôn hết hạn và không vô hiệu hóa chính sách được quản lý bởi Cloud. `block-self-pause` ngăn chặn một agent được hệ thống theo dõi sử dụng cơ chế thoát này. +Tạm dừng cục bộ tạm ngừng chính sách tích hợp, tùy chỉnh, quy ước và gói cho một phiên. Chúng luôn hết hạn và không vô hiệu hóa chính sách được quản lý bởi Cloud. `block-failproofai-commands` — luôn bật và không thể bị vô hiệu hóa hoặc tạm dừng — ngăn một agent được nhạy cảm sử dụng lối thoát này. ## Cờ chính sách -| Cờ | Mục đích | +| Cờ | Sử dụng | | --- | --- | -| `--install`, `-i` | Bật chính sách và cài đặt harness hooks | -| `--uninstall`, `-u` | Tắt chính sách hoặc xóa hooks | +| `--install`, `-i` | Bật chính sách và cài đặt hooks harness | +| `--uninstall`, `-u` | Tắt chính sách hoặc gỡ bỏ hooks | | `--cli ` | Nhắm mục tiêu một hoặc nhiều harness được hỗ trợ | -| `--scope user\|project\|local\|all` | Chọn phạm vi cấu hình; `all` dùng để gỡ cài đặt | -| `--beta` | Bao gồm chính sách beta | +| `--scope user\|project\|local\|all` | Chọn phạm vi cấu hình; `all` dành cho gỡ cài đặt | +| `--beta` | Bao gồm các chính sách beta | | `--custom`, `-c ` | Xác thực và tải tệp chính sách tùy chỉnh; có thể lặp lại | -## Cờ phân phối và bảo trì +## Cờ cung cấp và bảo trì | Lệnh | Cờ | | --- | --- | @@ -87,7 +92,7 @@ Tạm dừng cục bộ tạm ngừng chính sách tích hợp, tùy chỉnh và `failproofai update` nên được chạy sau `npm install -g failproofai@latest`; nó thực hiện di chuyển bố cục trang chủ, cài đặt nhị phân daemon phù hợp và khởi động lại dịch vụ. `--no-daemon` chỉ thực hiện di chuyển bố cục. -## Đường dẫn Harness +## Đường dẫn harness ```text failproofai harness list [harness] @@ -97,9 +102,9 @@ failproofai harness remove-path Các tên harness được hỗ trợ là `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity` và `goose`. -Nhãn đặt tên không gian các ID agent dẫn xuất khi hai gốc chứa bản sao của cùng một dự án. Các gốc chồng lấp và nhãn trùng lặp bị từ chối để ngăn chặn việc thu thập trùng lặp hoặc hỏng con trỏ. Cấu hình đường dẫn phụ tải lại mà không cần khởi động lại daemon. +Nhãn không gian ID agent dẫn xuất khi hai gốc chứa bản sao của cùng một dự án. Gốc chồng chéo và nhãn trùng lặp bị từ chối để ngăn chặn thu thập trùng lặp hoặc hỏng con trỏ. Cấu hình đường dẫn bổ sung tải lại mà không cần khởi động lại daemon. -Các môi trường container có thể thay thế các đường dẫn phụ được định cấu hình tệp bằng một biến được phân tách bằng dấu phẩy có tên `FAILPROOFAI__EXTRA_PATHS`, ví dụ: +Các môi trường container có thể thay thế các đường dẫn bổ sung được cấu hình bằng tệp bằng một biến được phân tách bằng dấu phẩy có tên `FAILPROOFAI__EXTRA_PATHS`, ví dụ: ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -107,24 +112,26 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## Biến môi trường -Sử dụng tệp cấu hình cho hành vi máy bền vững. Các biến môi trường hữu ích nhất cho container, bài kiểm tra và một quy trình. +Sử dụng tệp cấu hình cho hành vi máy bền vững. Biến môi trường hữu ích nhất cho container, bài kiểm tra và một quy trình. -| Biến | Mục đích | +| Biến | Sử dụng | | --- | --- | -| `FAILPROOFAI_HOME` | Chuyển địa chỉ bố cục `~/.failproofai` hoàn chỉnh | -| `FAILPROOFAI_LOG_LEVEL` | Đặt mức chi tiết ghi nhật ký cục bộ | +| `FAILPROOFAI_HOME` | Chuyển vị trí bố cục `~/.failproofai` hoàn chỉnh | +| `FAILPROOFAI_LOG_LEVEL` | Đặt chi tiết ghi nhật ký cục bộ | | `FAILPROOFAI_HOOK_LOG_FILE` | Ghi chẩn đoán hook vào tệp đã chọn | -| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Vô hiệu hóa telemetry ẩn danh cho quy trình này | +| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Tắt telemetry ẩn danh cho quy trình này | | `FAILPROOFAI_NO_FIRST_RUN=1` | Bỏ qua thiết lập chạy lần đầu tương tác | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Bỏ qua kiểm toán cục bộ sau thiết lập | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | Bỏ qua kiểm tra cục bộ sau thiết lập | | `FAILPROOFAI_LLM_BASE_URL` | Ghi đè điểm cuối tương thích OpenAI được sử dụng bởi chính sách LLM | | `FAILPROOFAI_LLM_API_KEY` | Cung cấp khóa API được sử dụng bởi chính sách LLM | | `FAILPROOFAI_LLM_MODEL` | Chọn mô hình được sử dụng bởi chính sách LLM | | `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | Ràng buộc tải mô-đun chính sách tùy chỉnh | -| `FAILPROOFAI__EXTRA_PATHS` | Thay thế các đường dẫn bắt phụ được cấu hình cho một harness | -| `NO_COLOR` | Vô hiệu hóa đầu ra terminal màu | +| `FAILPROOFAI_NO_DOWNLOAD=1` | Từ chối tìm nạp gói và nhị phân daemon; những gì được cài đặt tiếp tục thực thi | +| `FAILPROOFAI_PACK_BASE_URL` | Tìm nạp gói từ một bản sao thay vì `github.com` | +| `FAILPROOFAI__EXTRA_PATHS` | Thay thế các đường dẫn chụp bổ sung được cấu hình cho một harness | +| `NO_COLOR` | Tắt đầu ra terminal có màu | -Các biến trang chủ dành riêng cho agent như `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` và `OPENCLAW_HOME` ghi đè nơi Failproof AI khám phá các phiên cục bộ cho harness đó. +Các biến trang chủ dành riêng cho agent như `CLAUDE_PROJECTS_PATH`, `CURSOR_HOME`, `HERMES_HOME` và `OPENCLAW_HOME` ghi đè nơi Failproof AI phát hiện các phiên cục bộ cho harness đó. ## Tạm dừng hoặc xóa máy một cách an toàn @@ -134,9 +141,9 @@ failproofai config --status failproofai config --resume ``` -Tạm dừng phiên cục bộ không vô hiệu hóa chính sách được quản lý bởi Cloud. Khôi phục triển khai Cloud thông qua quy trình thực thi Cloud khi bản triển khai là vấn đề. +Tạm dừng phiên cục bộ không vô hiệu hóa chính sách được quản lý bởi Cloud. Khôi phục triển khai Cloud thông qua quy trình thực thi Cloud khi triển khai chính nó là vấn đề. -Trước khi xóa gói npm, hãy xóa hooks đã cài đặt và daemon: +Trước khi gỡ bỏ gói npm, gỡ bỏ hooks đã cài đặt và daemon: ```bash failproofai uninstall --dry-run @@ -144,8 +151,8 @@ failproofai uninstall --yes npm rm -g failproofai ``` -Chạy `failproofai --help` để biết chi tiết dành riêng cho phiên bản. +Chạy `failproofai --help` để biết chi tiết riêng cho phiên bản. - Chạy `failproofai uninstall` trước `npm rm -g failproofai`; npm không xóa agent hooks đã cài đặt hoặc dịch vụ daemon. + Chạy `failproofai uninstall` trước `npm rm -g failproofai`; npm không gỡ bỏ các hooks agent đã cài đặt hoặc dịch vụ daemon. \ No newline at end of file diff --git a/docs/vi/start/quickstart.mdx b/docs/vi/start/quickstart.mdx index 2bd07206..e6972ecf 100644 --- a/docs/vi/start/quickstart.mdx +++ b/docs/vi/start/quickstart.mdx @@ -1,17 +1,17 @@ --- title: "Bắt đầu nhanh" -description: "Ghi lại một phiên làm việc của agent, tìm kiếm lỗi và bắt đầu ngăn chặn nó." +description: "Ghi lại một phiên làm việc của agent, tìm ra lỗi và bắt đầu ngăn chặn nó." icon: "zap" --- -Hướng dẫn bắt đầu nhanh này giúp bạn có một máy báo cáo phiên làm việc, chạy kiểm toán và triển khai chính sách. Sử dụng skill để thiết lập Failproof AI, hoặc thực hiện theo các bước thủ công. +Bắt đầu nhanh này đưa một máy báo cáo phiên làm việc, chạy kiểm toán và triển khai một chính sách. Sử dụng skill để thiết lập Failproof AI, hoặc làm theo các bước thủ công. -**Đây là con đường của bạn?** Nếu agent của bạn chạy trên một trong 12 [harness được hỗ trợ](/vi/reference/harnesses) — một CLI mã hóa hoặc gateway như Hermes hay OpenClaw — hãy làm theo các bước dưới đây; bạn cần Node.js phiên bản 20.9 hoặc mới hơn. Nếu agent của bạn không có harness, hãy thiết lập nó bằng [Python SDK](/vi/reference/custom-agents) để tracing và kiểm toán, sau đó quay lại [Chạy kiểm tra lỗi đầu tiên của bạn](/vi/start/first-audit); thực thi trên đường đó cần hook trong runtime của bạn. +**Đường đi nào của bạn?** Nếu agent của bạn chạy trên một trong 12 [harness](/vi/reference/harnesses) được hỗ trợ — một CLI mã hóa hoặc một gateway như Hermes hoặc OpenClaw — hãy làm theo các bước dưới đây; bạn cần Node.js 20.9 trở lên. Nếu agent của bạn không có harness, hãy sử dụng [Python SDK](/vi/reference/custom-agents) để theo dõi và kiểm toán, sau đó quay lại [Chạy kiểm tra lỗi đầu tiên của bạn](/vi/start/first-audit); thực thi trên đường đó cần một hook trong runtime của bạn. - + ```bash npx skills add FailproofAI/skills ``` @@ -21,16 +21,16 @@ Hướng dẫn bắt đầu nhanh này giúp bạn có một máy báo cáo phi Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - Agent của bạn kiểm tra dự án, chọn tích hợp liên quan, thực hiện thiết lập và xác minh nó. Xem [kho lưu trữ skill FailproofAI](https://github.com/FailproofAI/skills) để tìm các skill riêng lẻ và các tùy chọn cài đặt nâng cao. + Agent của bạn kiểm tra dự án, chọn tích hợp phù hợp, thực hiện thiết lập và xác minh nó. Xem [FailproofAI skills repository](https://github.com/FailproofAI/skills) để tìm các skill riêng lẻ và các tùy chọn cài đặt nâng cao. - ## Trước khi bạn bắt đầu + ## Trước khi bắt đầu 1. Mở [bảng điều khiển Failproof AI](https://app.befailproof.ai) và tạo tài khoản hoặc đăng nhập bằng email công việc của bạn. -2. Đi tới **Administration → Keys** và tạo khóa với `events:add` và `policies:pull`. -3. Sao chép mã bí mật một lần và lưu trữ nó trên máy đích: +2. Đi đến **Administration → Keys** và tạo một khóa với `events:add` và `policies:pull`. +3. Sao chép bí mật một lần và lưu trữ nó trên máy đích: ```bash export FAILPROOFAI_KEY="" @@ -45,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - Bảng thoại phiên được gửi theo mặc định. Thêm `--no-transcripts` để báo cáo hoạt động hook và các quyết định chính sách mà không có nội dung bảng thoại. + Các bản ghi phiên được gửi theo mặc định. Thêm `--no-transcripts` để báo cáo hoạt động hook và quyết định chính sách mà không có nội dung bản ghi. - Nếu máy này đã có lịch sử agent, hãy xem trước và nhập bảy ngày qua, sau đó chờ quá trình gửi hoàn thành. Bỏ qua bước này trên máy mới. + Nếu máy này đã có lịch sử agent, hãy xem trước và nhập bảy ngày qua, sau đó chờ giao hàng hoàn thành. Bỏ qua bước này trên một máy mới. ```bash failproofai backfill --since 7d --dry-run @@ -57,23 +57,23 @@ export FAILPROOFAI_KEY="" Mở **Sessions** trong Failproof AI và chọn một phiên đã nhập. - - Điều này gắn Failproof AI vào harness của bạn và cài đặt 40 chính sách tích hợp sẵn. Sử dụng chúng để xem các quyết định chính sách cục bộ và thử thực thi trước khi Failproof AI kiểm toán phiên của bạn và viết chính sách cho các agent của bạn. + + Điều này gắn Failproof AI vào harness của bạn và cài đặt 39 chính sách tích hợp sẵn. Sử dụng chúng để xem quyết định chính sách cục bộ và thử thực thi trước khi Failproof AI kiểm toán phiên của bạn và viết chính sách cho agent của bạn. - Cho phép trình cài đặt phát hiện harness của bạn hoặc đặt tên một cách rõ ràng. Mỗi một trong 12 là giá trị `--cli` hợp lệ — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. + Cho phép trình cài đặt phát hiện harness của bạn hoặc đặt tên rõ ràng. Mỗi một trong 12 là một giá trị `--cli` hợp lệ — `claude`, `codex`, `copilot`, `cursor`, `opencode`, `pi`, `hermes`, `openclaw`, `factory`, `devin`, `antigravity`, `goose`. ```bash failproofai policies --install --cli claude --scope user # a coding CLI failproofai policies --install --cli hermes --scope user # a Slack/Telegram gateway ``` - Chặn lệnh gọi công cụ trước khi nó chạy được xác minh trên cả 12. Cổng cuối lượt được xác minh trên 8 — xem [khả năng thực thi](/vi/reference/harnesses#enforcement-capability) để tìm ma trận theo harness. + Chặn một lệnh gọi công cụ trước khi nó chạy được xác minh trên cả 12. Các cổng cuối lượt được xác minh trên 8 — xem [enforcement capability](/vi/reference/harnesses#enforcement-capability) để xem ma trận cho từng harness. - Theo dõi [Chạy kiểm tra lỗi đầu tiên của bạn](/vi/start/first-audit). Sử dụng mục tiêu cụ thể như tìm các phiên nơi agent thử lại một công cụ thất bại mà không thay đổi cách tiếp cận của nó. + Làm theo [Chạy kiểm tra lỗi đầu tiên của bạn](/vi/start/first-audit). Sử dụng một mục tiêu cụ thể chẳng hạn như "tìm phiên nơi agent đã thử lại một công cụ bị lỗi mà không thay đổi cách tiếp cận của nó." - Theo dõi [Ngăn chặn lỗi đầu tiên của bạn bằng chính sách](/vi/start/first-policy). Bắt đầu ở chế độ quan sát, kiểm tra các kết quả khớp, sau đó thực thi phiên bản được xem xét. + Làm theo [Ngăn chặn lỗi đầu tiên của bạn với chính sách](/vi/start/first-policy). Bắt đầu ở chế độ quan sát, kiểm tra các kết quả phù hợp, sau đó thực thi phiên bản được xem xét. diff --git a/docs/zh/policies/builtin-catalog.mdx b/docs/zh/policies/builtin-catalog.mdx index 8d457e33..67ff82cb 100644 --- a/docs/zh/policies/builtin-catalog.mdx +++ b/docs/zh/policies/builtin-catalog.mdx @@ -1,100 +1,100 @@ --- title: "内置策略目录" -description: "查看每个内置 Failproof AI 策略、其触发条件、推荐状态及可配置参数。" +description: "查阅每条 Failproof AI 内置策略的触发条件、推荐状态及可配置参数。" icon: "list-checks" --- -已安装的包是策略可用性的权威来源。每次升级后请运行 `failproofai policies`，因为目录条目和行为可能随包版本变化。 +已安装的软件包是策略可用性的唯一权威来源。每次升级后请运行 `failproofai policies`，因为目录条目和行为可能随软件包版本而变化。 ## 推荐基线 -引导式设置的推荐选项当前启用了密钥清理器、环境保护、自我保护、灾难性命令防护以及受保护分支安全： +引导安装的推荐选项目前启用了密钥脱敏、环境保护、自我保护、灾难性命令防护以及受保护分支安全： ```text sanitize-jwt sanitize-api-keys sanitize-connection-strings sanitize-private-key-content sanitize-bearer-tokens protect-env-vars block-env-files block-secrets-write -block-self-pause block-failproofai-commands -block-sudo block-curl-pipe-sh -block-rm-rf block-push-master -block-force-push +block-failproofai-commands block-sudo +block-curl-pipe-sh block-rm-rf +block-push-master block-force-push ``` -推荐选项有意比**全量**范围更窄。基础设施和工作流策略可能会打断正常工作，应仅在需要的仓库和机器上启用。 +`block-failproofai-commands` **始终开启**。上方列出它仅为完整起见，但无论是否出现在您的启用列表中，它都会在每次评估时注册，且无法被禁用或暂停——一个可被 Agent 自行关闭的守卫，根本算不上守卫。 + +推荐范围有意窄于**全部启用**。基础设施和工作流策略可能会中断正常工作，应仅在需要的仓库和机器上启用。 ## 密钥与环境 | 策略 | 触发条件 | 效果 | | --- | --- | --- | -| `sanitize-jwt` | `PostToolUse` | 在模型读取工具输出前，将其中的 JWT 脱敏处理。 | +| `sanitize-jwt` | `PostToolUse` | 在模型看到工具输出之前，将其中的 JWT 脱敏处理。 | | `sanitize-api-keys` | `PostToolUse` | 脱敏常见的 OpenAI、Anthropic、GitHub、AWS、Stripe 和 Google 密钥。 | | `sanitize-connection-strings` | `PostToolUse` | 脱敏包含凭据的数据库连接字符串。 | -| `sanitize-private-key-content` | `PostToolUse` | 脱敏 PEM 私钥内容。 | -| `sanitize-bearer-tokens` | `PostToolUse` | 脱敏授权 Bearer Token。 | -| `protect-env-vars` | `PreToolUse`（Shell 工具） | 阻止转储环境变量的命令。 | -| `block-env-files` | `PreToolUse` | 阻止对 `.env` 文件的读写操作。 | -| `block-read-outside-cwd` | `PreToolUse`（读取、glob、grep 或 Shell 工具） | 将读取范围限制在会话工作目录内。 | -| `block-secrets-write` | `PreToolUse`（写入工具） | 阻止向常见密钥和凭据文件名写入内容。 | +| `sanitize-private-key-content` | `PostToolUse` | 脱敏 PEM 私钥正文。 | +| `sanitize-bearer-tokens` | `PostToolUse` | 脱敏 Authorization bearer token。 | +| `protect-env-vars` | Shell 工具的 `PreToolUse` | 拦截会转储环境变量的命令。 | +| `block-env-files` | `PreToolUse` | 拦截对 `.env` 文件的读写操作。 | +| `block-read-outside-cwd` | 读取、glob、grep 或 shell 工具的 `PreToolUse` | 将读操作限制在会话工作目录内。 | +| `block-secrets-write` | 写入工具的 `PreToolUse` | 拦截对常见密钥和凭据文件名的写操作。 | ## 危险命令与基础设施 | 策略 | 触发条件 | 效果 | | --- | --- | --- | -| `block-self-pause` | `PreToolUse`、`PermissionRequest` | 防止 Agent 暂停自身的执行强制。 | -| `block-sudo` | `PreToolUse`、`PermissionRequest` | 阻止 `sudo`，除非匹配到允许模式。 | -| `block-curl-pipe-sh` | `PreToolUse` | 阻止将下载的脚本直接通过管道传递给 Shell 执行。 | -| `block-rm-rf` | `PreToolUse` | 阻止灾难性递归删除操作。 | -| `block-failproofai-commands` | `PreToolUse` | 防止 Agent 修改或卸载 Failproof AI。 | +| `block-sudo` | `PreToolUse`、`PermissionRequest` | 拦截 `sudo`，除非命令匹配允许规则。 | +| `block-curl-pipe-sh` | `PreToolUse` | 拦截将下载脚本直接通过管道传给 shell 的操作。 | +| `block-rm-rf` | `PreToolUse` | 拦截灾难性的递归删除模式。 | +| `block-failproofai-commands` | `PreToolUse`、`PermissionRequest` | **始终开启，无法禁用。** 拦截所有 Failproof AI CLI 调用、自我暂停以及包管理器卸载操作。 | | `block-kubectl` | `PreToolUse` | 管控 Kubernetes 命令。 | | `block-terraform` | `PreToolUse` | 管控 Terraform 和 OpenTofu 命令。 | | `block-aws-cli` | `PreToolUse` | 管控 AWS CLI 命令。 | | `block-gcloud` | `PreToolUse` | 管控 Google Cloud CLI 命令。 | | `block-az-cli` | `PreToolUse` | 管控 Azure CLI 命令。 | | `block-helm` | `PreToolUse` | 管控 Helm 命令。 | -| `block-gh-pipeline` | `PreToolUse` | 管控会产生变更的 GitHub CLI 工作流、运行、合并、发布、缓存和密钥操作。 | +| `block-gh-pipeline` | `PreToolUse` | 管控具有变更性质的 GitHub CLI 工作流、运行、合并、发布、缓存及密钥操作。 | ## Git 与数据库安全 | 策略 | 触发条件 | 效果 | | --- | --- | --- | -| `block-push-master` | `PreToolUse` | 阻止直接推送到已配置的受保护分支。 | -| `block-force-push` | `PreToolUse` | 阻止强制推送；当前实现中 `--force-with-lease` 仍被允许。 | -| `block-work-on-main` | `PreToolUse` | 阻止在受保护分支上执行提交和合并操作。 | -| `warn-git-amend` | `PreToolUse` | 在使用 `--amend` 重写提交前发出警告。 | -| `warn-git-stash-drop` | `PreToolUse` | 在永久丢弃或清除暂存区前发出警告。 | +| `block-push-master` | `PreToolUse` | 拦截直接推送到已配置的受保护分支。 | +| `block-force-push` | `PreToolUse` | 拦截强制推送；当前实现中 `--force-with-lease` 仍被允许。 | +| `block-work-on-main` | `PreToolUse` | 拦截在受保护分支上的提交和合并操作。 | +| `warn-git-amend` | `PreToolUse` | 在使用 `--amend` 改写提交前发出警告。 | +| `warn-git-stash-drop` | `PreToolUse` | 在永久丢弃或清空 stash 前发出警告。 | | `warn-all-files-staged` | `PreToolUse` | 对 `git add -A`、`git add .` 或 `git add --all` 等大范围暂存操作发出警告。 | -| `warn-destructive-sql` | `PreToolUse` | 通过已识别的数据库客户端执行 `DROP`、`TRUNCATE` 以及不带 `WHERE` 的 `DELETE` 时发出警告。 | +| `warn-destructive-sql` | `PreToolUse` | 对通过已识别数据库客户端执行的 `DROP`、`TRUNCATE` 以及不带 `WHERE` 的 `DELETE` 发出警告。 | | `warn-schema-alteration` | `PreToolUse` | 对已识别的 `ALTER TABLE` 列操作和重命名操作发出警告。 | ## 包管理、系统行为与 Agent 循环 | 策略 | 触发条件 | 效果 | | --- | --- | --- | -| `warn-package-publish` | `PreToolUse` | 在发布到包注册表前发出警告。 | +| `warn-package-publish` | `PreToolUse` | 在发布到包注册中心前发出警告。 | | `warn-global-package-install` | `PreToolUse` | 在全局安装包之前发出警告。 | -| `prefer-package-manager` | `PreToolUse` | 指示 Agent 使用允许的包管理器。 | -| `warn-large-file-write` | `PreToolUse`（写入工具） | 当文件大小超过配置阈值时发出警告。 | +| `prefer-package-manager` | `PreToolUse` | 指示 Agent 使用已允许的包管理器。 | +| `warn-large-file-write` | 写入工具的 `PreToolUse` | 当文件大小超过配置阈值时发出警告。 | | `warn-background-process` | `PreToolUse` | 对分离式或长期运行的后台进程模式发出警告。 | -| `warn-repeated-tool-calls` | `PreToolUse` | 在相同工具调用出现三次及以上后发出警告。 | +| `warn-repeated-tool-calls` | `PreToolUse` | 在三次或以上相同工具调用后发出警告。 | ## 任务结束工作流 -这些策略需要一个能触发兼容 `Stop` 事件的运行环境。 +这些策略需要能够发出兼容 `Stop` 事件的执行框架。 | 策略 | 效果 | | --- | --- | -| `require-commit-before-stop` | 当存在未提交的跟踪变更时，拒绝完成任务。 | -| `require-push-before-stop` | 当存在仅保留在本地的提交时，拒绝完成任务。 | +| `require-commit-before-stop` | 当已跟踪的工作存在未提交内容时，拒绝完成任务。 | +| `require-push-before-stop` | 当存在仅在本地的提交时，拒绝完成任务。 | | `require-pr-before-stop` | 要求为当前分支创建 Pull Request。 | -| `require-no-conflicts-before-stop` | 要求与配置的基础分支干净合并。 | -| `require-ci-green-before-stop` | 要求当前 HEAD 的 CI 检查全部成功完成。 | +| `require-no-conflicts-before-stop` | 要求与已配置的基础分支无合并冲突。 | +| `require-ci-green-before-stop` | 要求当前 HEAD 的 CI 检查全部通过。 | ## 参数参考 -在所选作用域的 `policyParams` 对象下配置参数，各策略会对类型进行校验。 +在对应作用域的 `policyParams` 对象下配置参数。每条策略会对参数类型进行校验。 -| 策略 | 参数 | 类型与默认值 | +| 策略 | 参数 | 类型及默认值 | | --- | --- | --- | | `sanitize-api-keys` | `additionalPatterns` | `pattern[]`，`[]`；条目包含 `regex` 和 `label` | | `block-read-outside-cwd` | `allowPaths` | `string[]`，`[]` | @@ -125,5 +125,5 @@ block-force-push ``` - 允许模式会扩大 Agent 的操作权限。在将其部署到整个机群之前，请在目标运行环境上充分测试确切的标记化规则和命令变体。 + 允许规则会扩大 Agent 的操作权限。在将其部署到整个机器集群之前，请先在目标执行框架上测试确切的 token 解析方式和命令变体。 \ No newline at end of file diff --git a/docs/zh/policies/failure-behavior.mdx b/docs/zh/policies/failure-behavior.mdx index df27dfc9..1d136950 100644 --- a/docs/zh/policies/failure-behavior.mdx +++ b/docs/zh/policies/failure-behavior.mdx @@ -1,19 +1,19 @@ --- -title: "失败行为" -description: "了解当策略评估或本地守护进程不可用时会发生什么。" +title: "故障行为" +description: "了解策略评估或本地守护进程不可用时会发生什么。" icon: "shield-alert" --- -Failproof AI 的设计原则是：执行失败时应明确可见，而非静默地允许高风险操作继续进行。 +Failproof AI 的设计原则是：执行失败时应清晰可见，而非静默放行有风险的操作。 -## 诊断关闭式失败拦截 +## 诊断失败关闭阻断 1. 前往 **Admin → enforcement**，打开对应机器。 - 2. 检查其最后一次签入时间、已分配的部署以及上报的部署。 + 2. 检查其最后签入时间、已分配的部署和上报的部署。 3. 前往 **Observe → policy**，打开被拒绝决策的会话。 - 4. 确认原因中报告的是守护进程可达性问题、版本偏差，还是策略本身的问题。 + 4. 确认原因是否报告了守护进程可达性问题、版本偏差或策略本身的问题。 @@ -23,21 +23,45 @@ Failproof AI 的设计原则是：执行失败时应明确可见，而非静默 failproofai config ``` - 重新运行 `failproofai config` 会在软件包升级后更新并重启守护进程。 + 升级包后重新运行 `failproofai config` 可更新并重启守护进程。 -在配置为使用 `failproofaid` 的机器上，守护进程是唯一的评估器。如果守护进程不可达，或其协议版本与 CLI 不匹配，钩子评估将以关闭失败的方式处理。操作将被拒绝，并附带原因提示操作员检查或更新守护进程。 +在配置为使用 `failproofaid` 的机器上，守护进程是唯一的评估器。如果守护进程不可达，或其协议版本与 CLI 不匹配，hook 评估将失败关闭。操作将被拒绝，并附有原因说明，指引操作人员检查或更新守护进程。 -在守护进程配置之前，钩子会在进程内评估策略。一旦记录了守护进程配置，当守护进程出现故障时，Failproof AI 不会静默地回退到第二个评估器。 +在配置守护进程之前，hook 会在进程内评估策略。一旦记录了守护进程配置，当守护进程出现故障时，Failproof AI 不会静默回退到第二个评估器。 -## 响应关闭式失败决策 +## 响应失败关闭决策 1. 运行 `failproofai config --status`。 -2. 如果版本不一致，请在更新软件包后重新运行 `failproofai config`。 -3. 如果守护进程不可达，请检查其服务状态和本地日志。 -4. 仅在确认策略评估路径正常后，再恢复代理工作。 +2. 如果版本不一致，更新包后重新运行 `failproofai config`。 +3. 如果守护进程不可达，检查其服务状态和本地日志。 +4. 仅在策略评估路径确认健康后，再恢复 Agent 工作。 - 请勿反复重试被拦截的操作。关闭式失败响应意味着系统无法确认该操作是安全的。 - \ No newline at end of file + 请勿反复重试被阻断的操作。失败关闭响应意味着系统无法确认该操作是安全的。 + + +## 包无法加载 + +如果一台机器被要求执行某个包，但无法运行该包，它会拒绝而不是静默继续。触发条件是**已记录的预期**，而非空预期：没有安装任何包的机器是静默的；而一个已声明但无法解析的包——或注册内容少于其清单声明的包——则会触发拒绝。 + +与守护进程不可达不同，此处的拒绝是**范围受限的**。守护进程无法访问意味着完全没有进行评估，因此无法确定任何操作是安全的。而无法加载的包有明确的缺失守卫集合，因为每条已声明的策略都携带自己的 `match`——所以它只拒绝这些策略所覆盖的事件和工具，其余操作照常进行。 + +以下情况不会触发拒绝： + +- `observe` 包，按其构造原理只评估不拦截 +- 从未采用或已显式关闭的策略 +- 加载器从未收到的包，此时"无注册"与有意跳过无法区分 +- 活跃会话暂停 +- 加载超时，这属于瞬态情况——偶发的磁盘慢响应不应在人工介入前就触发拒绝 + +无论缺失的策略声明了什么，`UserPromptSubmit` 都会使用 **instruct** 而非拒绝。全面拒绝会连带锁定你，使你无法使用本可修复问题的 Agent。 + +### 处理方法 + +```bash +failproofai pack list +``` + +该命令会列出所有无法加载的已安装包，说明原因，并以非零状态退出。然后可以重新安装（`failproofai pack add `）或移除（`failproofai pack remove `）——移除操作会撤销该预期，拒绝也随之停止。 \ No newline at end of file diff --git a/docs/zh/policies/packs.mdx b/docs/zh/policies/packs.mdx new file mode 100644 index 00000000..2614b202 --- /dev/null +++ b/docs/zh/policies/packs.mdx @@ -0,0 +1,110 @@ +--- +title: "策略包" +description: "安装以 GitHub 发布版本形式发布的策略集，并管理其执行内容。" +icon: "package" +--- + +策略包是以 GitHub 发布版本形式发布的一组策略。一条命令即可完成安装，运行前会验证发布版本自带的校验和，同时记录摘要，确保策略包在安装后不会在你的机器上被篡改。 + +## 安装 Failproof AI 策略 + +```bash +failproofai pack add core +``` + +该命令从 npm 包内置的副本安装我们发布的策略集——无需网络连接，也不会因代理服务器而失败。你也可以只安装其中的一部分： + +```bash +failproofai pack add core --policy block-rm-rf # 单个策略，或以逗号分隔的多个策略 +failproofai pack add core --category dangerous-commands # 某个完整分类 +failproofai pack add core --all # 包含所有内容 +``` + +`failproofai pack list` 会列出该策略包提供的所有分类。 + +## 在安装前查看策略包内容 + +```bash +failproofai pack list acme/support-agent +``` + +该命令会按分类列出策略包中的所有策略，标注哪些是作者默认启用的，哪些是可选启用的。它**只读取清单文件**——入口构件既不会被下载，也不会被导入，因此查看陌生人的策略包不会执行任何陌生代码。清单文件仍会与发布版本自带的 `SHA256SUMS` 进行校验，确保你所看到的内容与实际安装内容完全一致。 + +不带参数运行 `failproofai pack list` 会列出当前已安装的所有策略包。 + +## 安装他人发布的策略包 + +```bash +failproofai pack add acme/support-agent +``` + +以下格式均可使用——直接粘贴你手头有的即可： + +| 来源 | 结果 | +| --- | --- | +| `acme/support-agent` | 最新发布版本，**固定**到其解析到的确切标签 | +| `acme/support-agent@v2.1.0` | 指定发布版本 | +| `github:acme/support-agent@v2.1.0` | 同上，明确指定来源 | +| `https://github.com/acme/support-agent/releases/tag/v2.1.0` | 同上，从浏览器复制的链接 | + +不指定标签时，会安装最新发布版本**并固定到该版本**，同时告知你所选定的标签。记录的内容始终精确指向某一个发布版本，因此重新安装不会产生版本漂移。 + +## 只安装策略包的部分内容 + +默认情况下，你只会获得策略包**自身的**默认配置——即作者标记为可无人值守启用的策略——而非全部内容。 + +```bash +failproofai pack add acme/support-agent --category billing,git +failproofai pack add acme/support-agent --policy block-refunds +failproofai pack add acme/support-agent --all +``` + +`--category` 与 `--policy` 取并集（`--only` 是 `--policy` 的同义选项）。以更新版本重新添加时，会保留你之前的选择，而不会重新启用其余策略。 + +## 管理已启用的策略 + +```bash +failproofai policies # 以统一列表显示所有来源，包含策略包 +failproofai pack list # 仅显示策略包，按分类分组 +failproofai policies --uninstall block-refunds # 关闭某个策略包中的策略 +failproofai policies --install block-refunds # 重新开启 +failproofai pack remove acme/support-agent +``` + +裸名称指代同名的**内置策略**（如果存在）。需要时可通过以下方式明确指定策略包中的策略： + +```bash +failproofai policies --uninstall acme/support-agent:block-refunds +``` + + +如果策略包中某个策略的名称与某个**已启用的内置策略**相同，则内置策略会运行，策略包中的副本会被跳过——否则同一检查会被执行两次。若要使用策略包中的版本，请先关闭对应的内置策略。 + + +## Failproof AI 策略的来源 + +`core` 读取 npm 包中内置的副本。同一组策略也以 GitHub 发布版本的形式发布，如需安装特定版本可使用以下方式： + +```bash +failproofai pack add core # 来自当前包，无需网络 +failproofai pack add FailproofAI/policies # 同一组策略，来自 GitHub 发布版本 +``` + +## 完整性验证的保障范围 + +`SHA256SUMS` 与构件在同一个发布版本中发布，因此它**不是**签名，无法证明发布者身份。它所能证明的是：这些字节与该发布版本所发布的内容完全一致——由于摘要在添加策略包时记录，并在每次导入前重新验证，策略包在安装后无法在你的机器上被悄然篡改。若某个仓库重新打标签或替换了发布资产，该策略包将无法加载，而不是静默地运行其他内容。 + +安装时，策略包还会被**导入一次**，并与其自身的清单进行核对。若构件无法解析，或注册的内容与声明不符，则在激活任何内容之前就会拒绝该策略包——而不是安装成功后在下一次工具调用时才报错。 + +## 策略包无法加载时的行为 + +若本机被要求执行某个策略包但该包无法运行，**拒绝**该缺失策略所涵盖的事件，而不是静默放行。详见[故障行为](/zh/policies/failure-behavior)。`failproofai pack list` 会标注处于该状态的策略包并以非零状态码退出。 + +## 离线使用与镜像 + +| 变量 | 作用 | +| --- | --- | +| `FAILPROOFAI_NO_DOWNLOAD=1` | 拒绝任何网络请求；已安装的策略包继续正常执行 | +| `FAILPROOFAI_PACK_BASE_URL` | 将策略包拉取请求重定向到镜像，而非 `github.com` | + +如需发布自己的策略包，请参阅[发布策略包](/zh/policies/publish-a-pack)。 \ No newline at end of file diff --git a/docs/zh/policies/publish-a-pack.mdx b/docs/zh/policies/publish-a-pack.mdx new file mode 100644 index 00000000..7244b6f8 --- /dev/null +++ b/docs/zh/policies/publish-a-pack.mdx @@ -0,0 +1,91 @@ +--- +title: "发布 Pack" +description: "将您自己的策略作为 GitHub Release 发布，任何人都可以安装。" +icon: "upload" +--- + +一个 pack 由附加到 GitHub Release 上的三个文件组成。`failproofai pack build` 会从您已有的策略文件中生成这三个文件。 + +## 1. 编写策略 + +只需一个文件，使用与自定义策略相同的 API。Pack 有两个额外的字段需要关注： + +```js +import { customPolicies, deny, allow } from "failproofai"; + +customPolicies.add({ + name: "block-refunds", + description: "Refunds above the approved limit need a human", + category: "Billing", // groups it, and is what --category selects on + defaultEnabled: true, // switched on by a plain `pack add` + match: { events: ["PreToolUse"], tools: ["Bash"] }, + fn: async (ctx) => + String(ctx.toolInput?.command ?? "").includes("refund") + ? deny("Refunds need a human. Ask before running this.") + : allow(), +}); +``` + +省略 `defaultEnabled` 时，其默认值为 **false**。普通的 `failproofai pack add` 只会启用您标记了的策略——是否不加甄别地安装陌生人的所有策略，不应该由安装器替用户做决定。 + + +入口文件必须是**一个自包含的文件**。只有入口文件会被 digest 固定，因此一个导入本地文件的 pack 无法真实地声明 digest 涵盖了实际运行的内容。请先打包（使用 `esbuild`、`bun build` 或 `rollup`），再从打包产物构建 pack——`pack build` 会拒绝包含本地导入的文件，而不是发出一个无法兑现的承诺。 + + +## 2. 构建 Release 资产 + +```bash +failproofai pack build ./policies.mjs \ + --id acme/support-agent \ + --version 1.0.0 \ + --out ./dist-pack +``` + +该命令会生成三个文件，并首先使用**加载器自身的规则**验证每条策略——这样一个无法安装的 pack 会在此处报错，您可以就地修复： + +| 文件 | 说明 | +| --- | --- | +| `failproofai-pack.json` | 清单文件：id、版本、effect，以及每条策略的条目 | +| `failproofai-pack.mjs` | 您的入口文件，原样保留 | +| `SHA256SUMS` | 另外两个文件的 ` ` | + +以下情况会在构建时被拒绝：id 不符合 `publisher/name` 格式、策略名称包含 `/`、策略声明了 `alwaysOn`、缺少 `description`、`category` 或 `match`、入口文件未注册任何策略，以及入口文件导入了本地文件。 + +## 3. 将文件附加到 Release + +使用与构建时相同的版本号为 Release 打标签，并将三个文件作为 Release 资产附上： + +```bash +gh release create 1.0.0 \ + ./dist-pack/failproofai-pack.json \ + ./dist-pack/failproofai-pack.mjs \ + ./dist-pack/SHA256SUMS +``` + +任何人现在都可以安装它： + +```bash +failproofai pack add acme/support-agent +``` + +资产文件名是固定的——CLI 在构建 URL 时直接使用这些文件名，无需任何 API 调用或服务发现。 + +## 发布新版本 + +使用新的 `--version` 构建，为新 Release 打标签，再次附上三个资产文件。用户运行相同的 `pack add` 即可升级，并保留他们已选择的策略子集；他们曾关闭的策略在升级后依然保持关闭状态。 + +修改策略的**名称**是一个破坏性变更：曾将其关闭的机器现在关闭的是一个已不存在的名称，而新名称会按照 `defaultEnabled` 的设置生效。 + +## 用户信任的内容 + +`SHA256SUMS` 与产物文件存放在同一个 Release 中，因此它能证明这些字节是您发布的内容——但无法证明您的身份。任何对仓库有写权限的人都可以同时修改这两个文件。用户的保障在于：digest 在安装时被固定，因此您发布的内容事后无法在他们不知情的情况下被篡改。 + +请从您能控制写入权限的仓库发布，并像对待发布软件包一样对待 pack 的发布。 + +## 先观察，再执行 + +清单文件可以声明 `"effect": "observe"`。这些策略会运行，但其判决结果**仅被记录，然后丢弃**——不会阻断任何操作。这是在新规则正式拦截任何人的工作之前，先针对真实流量进行评估的方式。 + +```json +{ "id": "acme/support-agent", "version": "1.1.0", "effect": "observe", "policies": [ ... ] } +``` \ No newline at end of file diff --git a/docs/zh/reference/failproof-cli.mdx b/docs/zh/reference/failproof-cli.mdx index 2254ff43..5016b94f 100644 --- a/docs/zh/reference/failproof-cli.mdx +++ b/docs/zh/reference/failproof-cli.mdx @@ -1,12 +1,12 @@ --- title: "Failproof AI CLI" -description: "安装钩子、管理本地策略、连接云端，以及操作本地守护进程。" +description: "安装 hooks、管理本地策略、连接 Cloud 并操作本地守护进程。" icon: "terminal" --- -使用 `npm install -g failproofai` 安装本地 CLI。不带参数运行即可打开本地策略控制台。 +使用 `npm install -g failproofai` 安装本地 CLI。不带参数运行可打开本地策略仪表板。 -该软件包需要 Node.js 20.9 或更高版本。开发及源码安装支持 Bun 1.3 或更高版本。`failproofai configure` 和 `failproofai setup` 是 `failproofai config` 的别名；`failproofai p` 是 `failproofai policies` 的别名。 +该软件包需要 Node.js 20.9 或更高版本。开发和源码安装支持 Bun 1.3 或更高版本。`failproofai configure` 和 `failproofai setup` 是 `failproofai config` 的别名；`failproofai p` 是 `failproofai policies` 的别名。 ## 配置机器 @@ -20,32 +20,37 @@ failproofai policies --install failproofai config --status ``` -不带参数运行 `failproofai` 即可打开本地策略控制台。 +不带参数运行 `failproofai` 可打开本地策略仪表板。 -| 命令 | 功能说明 | +| 命令 | 说明 | | --- | --- | -| `failproofai config` | 运行交互式机器设置 | -| `failproofai config --connect --token ` | 连接云端数据采集和策略下发 | -| `failproofai config --status` | 显示连接状态、守护进程、下发及暂停状态 | -| `failproofai policies` | 列出内置和自定义策略 | -| `failproofai policies --install` | 安装钩子并启用策略 | -| `failproofai policy add ` | 启用一条内置策略 | -| `failproofai policy remove ` | 禁用一条内置策略 | -| `failproofai policies --uninstall` | 禁用策略或移除框架钩子 | -| `failproofai audit` | 扫描本地代理历史记录并打开本地审计视图 | -| `failproofai audit --schedule [days] --email
` | 计划定期本地扫描并通过邮件发送结果 | -| `failproofai audit --status` | 显示报告地址、扫描间隔及下次计划扫描时间 | -| `failproofai audit --no-schedule` | 停止定期扫描但不删除审计历史记录 | +| `failproofai config` | 运行交互式机器配置 | +| `failproofai config --connect --token ` | 连接 Cloud 数据采集和策略下发 | +| `failproofai config --status` | 显示连接、守护进程、下发及暂停状态 | +| `failproofai policies` | 列出内置、自定义、约定、pack 及 Cloud 托管策略 | +| `failproofai policies --install` | 安装 hooks 并启用策略 | +| `failproofai policy add ` | 启用单条策略——内置策略或来自已安装 pack 的 `:` | +| `failproofai policy remove ` | 禁用单条策略，命名方式相同 | +| `failproofai policies --uninstall` | 禁用策略或移除 harness hooks | +| `failproofai pack list` | 列出已安装的策略 pack 及其包含的所有策略 | +| `failproofai pack add ` | 从 GitHub release 安装策略 pack；不指定 tag 则获取最新版本并锁定 | +| `failproofai pack add --bundled` | 以 pack 形式安装内置策略，来源为本软件包，无需网络 | +| `failproofai pack build ` | 为自定义 pack 构建三个发布资产 | +| `failproofai pack remove ` | 停用已安装的 pack | +| `failproofai audit` | 扫描本地 agent 历史记录并打开本地审计视图 | +| `failproofai audit --schedule [days] --email
` | 定期安排本地扫描并将结果发送至指定邮箱 | +| `failproofai audit --status` | 显示报告地址、间隔时间及下次计划扫描时间 | +| `failproofai audit --no-schedule` | 停止定期扫描，但不删除审计历史 | | `failproofai harness list` | 列出额外的捕获路径 | -| `failproofai flush --wait` | 投递当前事件队列 | +| `failproofai flush --wait` | 投递当前事件缓冲队列 | | `failproofai backfill --since 30d` | 重新读取此前已处理的历史记录 | | `failproofai config --pause [duration]` | 暂停当前本地会话，默认 30 分钟，最长 8 小时 | | `failproofai config --resume` | 恢复已暂停的本地会话；添加 `--all` 可清除所有暂停 | | `failproofai update` | 完成软件包迁移并更新守护进程 | -| `failproofai migrate --dry-run` | 预览或执行待处理的主目录布局迁移 | -| `failproofai uninstall` | 在移除软件包前删除钩子和守护进程 | +| `failproofai migrate --dry-run` | 预览或执行待处理的 home 目录布局迁移 | +| `failproofai uninstall` | 在移除软件包前卸载 hooks 和守护进程 | | `failproofai --version` | 打印已安装的软件包版本 | -| `failproofai --help` | 显示命令和全局用法说明 | +| `failproofai --help` | 显示命令和全局用法 | ## 配置标志 @@ -53,29 +58,29 @@ failproofai config --status | --- | --- | | `--connect --token ` | 非交互式连接 | | `--machine-id ` | 设置稳定的机器 ID | -| `--machine-label ` | 设置或更改控制台标签 | -| `--no-transcripts` | 仅发送决策结果，不包含记录内容 | -| `--disconnect` | 停止云端策略拉取和事件投递 | +| `--machine-label ` | 设置或更改仪表板标签 | +| `--no-transcripts` | 仅发送决策结果，不包含对话记录内容 | +| `--disconnect` | 停止 Cloud 策略拉取和事件投递 | | `--status` | 显示当前机器状态 | | `--pause [duration]` | 暂停当前目录中最新的会话；接受秒、分钟或小时，默认 30 分钟 | | `--resume` | 提前结束匹配的暂停 | -| `--session ` | 指定目标会话进行暂停或恢复 | -| `--all` | 与 `--resume` 配合使用，结束所有活动暂停 | +| `--session ` | 为暂停或恢复指定明确的会话 | +| `--all` | 与 `--resume` 配合使用，结束所有活跃暂停 | -本地暂停会为某一会话暂停内置策略、自定义策略和约定策略。暂停始终会到期，且不会禁用云端管理的策略。`block-self-pause` 可防止被插桩的代理自行使用此逃生通道。 +本地暂停会为单个会话挂起内置、自定义、约定和 pack 策略。暂停始终会到期，且不会禁用 Cloud 托管策略。`block-failproofai-commands`——该策略始终开启且无法被禁用或暂停——可防止被监控的 agent 自行使用此逃逸入口。 ## 策略标志 | 标志 | 用途 | | --- | --- | -| `--install`, `-i` | 启用策略并安装框架钩子 | -| `--uninstall`, `-u` | 禁用策略或移除钩子 | -| `--cli ` | 指定一个或多个受支持的框架 | +| `--install`, `-i` | 启用策略并安装 harness hooks | +| `--uninstall`, `-u` | 禁用策略或移除 hooks | +| `--cli ` | 针对一个或多个受支持的 harness | | `--scope user\|project\|local\|all` | 选择配置作用域；`all` 用于卸载 | -| `--beta` | 包含测试版策略 | +| `--beta` | 包含 beta 策略 | | `--custom`, `-c ` | 验证并加载自定义策略文件；可重复使用 | -## 投递与维护标志 +## 数据投递与维护标志 | 命令 | 标志 | | --- | --- | @@ -85,9 +90,9 @@ failproofai config --status | `migrate` | `--dry-run` | | `uninstall` | `--purge`, `--dry-run`, `--yes` | -`failproofai update` 应在 `npm install -g failproofai@latest` 之后运行；它会执行主目录布局迁移、安装匹配的守护进程二进制文件并重启服务。`--no-daemon` 仅执行布局迁移。 +`failproofai update` 应在 `npm install -g failproofai@latest` 之后运行；它会执行 home 目录布局迁移、安装匹配的守护进程二进制文件并重启服务。`--no-daemon` 仅执行布局迁移。 -## 框架路径 +## Harness 路径 ```text failproofai harness list [harness] @@ -95,11 +100,11 @@ failproofai harness add-path [label=] failproofai harness remove-path ``` -支持的框架名称包括 `claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity` 和 `goose`。 +支持的 harness 名称包括 `claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity` 和 `goose`。 -当两个根目录包含同一项目的副本时，标签可为派生的代理 ID 提供命名空间隔离。系统会拒绝重叠的根目录和重复的标签，以防止重复采集或游标损坏。额外路径配置无需重启守护进程即可重新加载。 +当两个根目录包含同一项目的副本时，标签会为派生的 agent ID 提供命名空间。重叠的根目录和重复的标签会被拒绝，以防止重复采集或游标损坏。额外路径配置无需重启守护进程即可重新加载。 -容器环境可以使用名为 `FAILPROOFAI__EXTRA_PATHS` 的逗号分隔变量来替换文件中配置的额外路径，例如： +容器环境可以使用逗号分隔的变量 `FAILPROOFAI__EXTRA_PATHS` 替换文件配置的额外路径，例如： ```bash export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b" @@ -107,26 +112,28 @@ export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/opencl ## 环境变量 -对于持久化的机器行为，请使用配置文件。环境变量最适用于容器、测试和单进程场景。 +持久化机器行为请使用配置文件。环境变量最适合用于容器、测试和单进程场景。 | 变量 | 用途 | | --- | --- | -| `FAILPROOFAI_HOME` | 重新定位完整的 `~/.failproofai` 目录布局 | -| `FAILPROOFAI_LOG_LEVEL` | 设置本地日志详细程度 | -| `FAILPROOFAI_HOOK_LOG_FILE` | 将钩子诊断信息写入指定文件 | +| `FAILPROOFAI_HOME` | 重定位完整的 `~/.failproofai` 目录布局 | +| `FAILPROOFAI_LOG_LEVEL` | 设置本地日志详细级别 | +| `FAILPROOFAI_HOOK_LOG_FILE` | 将 hook 诊断信息写入指定文件 | | `FAILPROOFAI_TELEMETRY_DISABLED=1` | 为当前进程禁用匿名遥测 | -| `FAILPROOFAI_NO_FIRST_RUN=1` | 跳过交互式首次运行设置 | -| `FAILPROOFAI_NO_AUTO_AUDIT=1` | 跳过设置完成后的本地审计 | +| `FAILPROOFAI_NO_FIRST_RUN=1` | 跳过交互式首次运行配置 | +| `FAILPROOFAI_NO_AUTO_AUDIT=1` | 跳过配置完成后的本地审计 | | `FAILPROOFAI_LLM_BASE_URL` | 覆盖 LLM 策略使用的 OpenAI 兼容端点 | | `FAILPROOFAI_LLM_API_KEY` | 提供 LLM 策略使用的 API 密钥 | | `FAILPROOFAI_LLM_MODEL` | 选择 LLM 策略使用的模型 | -| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | 限制自定义策略模块的加载时间 | -| `FAILPROOFAI__EXTRA_PATHS` | 替换某一框架已配置的额外捕获路径 | -| `NO_COLOR` | 禁用终端彩色输出 | +| `FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS` | 限制自定义策略模块的加载超时 | +| `FAILPROOFAI_NO_DOWNLOAD=1` | 拒绝获取 pack 和守护进程二进制文件；已安装的内容继续执行 | +| `FAILPROOFAI_PACK_BASE_URL` | 从镜像而非 `github.com` 获取 pack | +| `FAILPROOFAI__EXTRA_PATHS` | 替换指定 harness 已配置的额外捕获路径 | +| `NO_COLOR` | 禁用彩色终端输出 | -代理专属的主目录变量（如 `CLAUDE_PROJECTS_PATH`、`CURSOR_HOME`、`HERMES_HOME` 和 `OPENCLAW_HOME`）会覆盖 Failproof AI 发现该框架本地会话时所使用的路径。 +Agent 专属的 home 变量（如 `CLAUDE_PROJECTS_PATH`、`CURSOR_HOME`、`HERMES_HOME` 和 `OPENCLAW_HOME`）可覆盖 Failproof AI 发现对应 harness 本地会话的路径。 -## 安全暂停或移除机器 +## 安全地暂停或移除机器 ```bash failproofai config --pause @@ -134,9 +141,9 @@ failproofai config --status failproofai config --resume ``` -本地会话暂停不会禁用云端管理的策略。如果问题出在云端发布流程本身，请通过云端执行工作流来恢复云端部署。 +本地会话暂停不会禁用 Cloud 托管策略。当发布流程本身出现问题时，请通过 Cloud 执行工作流恢复 Cloud 部署。 -在移除 npm 软件包之前，请先删除已安装的钩子和守护进程： +移除 npm 软件包之前，请先移除已安装的 hooks 和守护进程： ```bash failproofai uninstall --dry-run @@ -144,8 +151,8 @@ failproofai uninstall --yes npm rm -g failproofai ``` -运行 `failproofai --help` 可查看特定版本的详细说明。 +运行 `failproofai --help` 可查看特定版本的详细信息。 - 请在执行 `npm rm -g failproofai` 之前先运行 `failproofai uninstall`；npm 不会自动移除已安装的代理钩子或守护进程服务。 + 请在 `npm rm -g failproofai` 之前运行 `failproofai uninstall`；npm 不会移除已安装的 agent hooks 或守护进程服务。 \ No newline at end of file diff --git a/docs/zh/start/quickstart.mdx b/docs/zh/start/quickstart.mdx index afa417b8..3d568314 100644 --- a/docs/zh/start/quickstart.mdx +++ b/docs/zh/start/quickstart.mdx @@ -1,27 +1,27 @@ --- -title: "快速开始" -description: "捕获一个 Agent 会话，定位故障，并开始预防它。" +title: "快速入门" +description: "捕获一次 Agent 会话，发现故障，并开始预防它。" icon: "zap" --- -本快速入门将帮助你完成：让一台机器开始上报会话、运行审计、并部署策略。你可以使用技能包完成配置，也可以按照手动步骤操作。 +本快速入门将引导你完成：让一台机器上报会话、运行审计，并部署一条策略。你可以使用技能来配置 Failproof，也可以按照手动步骤操作。 -**选择你的路径：** 如果你的 Agent 运行在 12 个受支持的[运行环境](/zh/reference/harnesses)之一——例如编程 CLI，或者 Hermes、OpenClaw 等网关——请按照以下步骤操作；你需要 Node.js 20.9 或更高版本。如果你的 Agent 没有对应的运行环境，请使用 [Python SDK](/zh/reference/custom-agents) 对其进行追踪和审计的插桩，然后从[运行你的第一次故障检查](/zh/start/first-audit)继续；该路径下的执行强制需要在你的运行时中添加 hook。 +**你适合哪种方式？** 如果你的 Agent 运行在 12 个受支持的[运行框架](/zh/reference/harnesses)之一中——例如编码 CLI，或像 Hermes、OpenClaw 这样的网关——请按照以下步骤操作；你需要 Node.js 20.9 或更高版本。如果你的 Agent 没有对应的运行框架，请使用 [Python SDK](/zh/reference/custom-agents) 对其进行追踪和审计插桩，然后在[运行你的首次故障检查](/zh/start/first-audit)时重新加入；该路径上的执行控制需要在你的运行时中添加 hook。 - + - + ```bash npx skills add FailproofAI/skills ``` - + ```text Set up Failproof AI for this project, connect this machine, install the right hooks and policies, and verify that a session arrives. ``` - 你的 Agent 会检查项目、选择相关集成、执行配置并验证结果。有关各项技能和高级安装选项，请参阅 [FailproofAI skills repository](https://github.com/FailproofAI/skills)。 + 你的 Agent 会检查项目，选择相关集成，执行配置，并验证会话是否正常到达。有关各项技能和高级安装选项，请参阅 [FailproofAI skills 仓库](https://github.com/FailproofAI/skills)。 @@ -30,7 +30,7 @@ icon: "zap" 1. 打开 [Failproof AI 控制台](https://app.befailproof.ai)，创建账号或使用工作邮箱登录。 2. 前往 **Administration → Keys**，创建一个具有 `events:add` 和 `policies:pull` 权限的密钥。 -3. 复制一次性密钥，并在目标机器上进行存储： +3. 复制一次性密钥，并将其保存到目标机器上： ```bash export FAILPROOFAI_KEY="" @@ -45,9 +45,9 @@ export FAILPROOFAI_KEY="" failproofai config --connect https://app.befailproof.ai --token "$FAILPROOFAI_KEY" ``` - 默认情况下会发送会话记录。添加 `--no-transcripts` 参数可在不上传记录内容的情况下上报 hook 活动和策略决策。 + 默认情况下，会话转录内容会一并上传。添加 `--no-transcripts` 选项可仅上报 hook 活动和策略决策，而不包含转录内容。 - 如果此机器已有 Agent 历史记录，可预览并导入最近七天的数据，然后等待传输完成。新机器可跳过此步骤。 + 如果该机器上已有 Agent 历史记录，可以预览并导入最近七天的数据，然后等待上传完成。在全新机器上可跳过此步骤。 ```bash failproofai backfill --since 7d --dry-run @@ -55,30 +55,30 @@ export FAILPROOFAI_KEY="" failproofai flush --wait ``` - 在 Failproof AI 中打开 **Sessions**，选择一个已导入的会话。 + 在 Failproof AI 中打开 **Sessions** 并选择一个已导入的会话。 - - 此步骤将 Failproof AI 接入你的运行环境，并安装 40 条内置策略。你可以用它们查看本地策略决策，并在 Failproof AI 审计会话、为你的 Agent 生成策略之前先行体验执行强制功能。 + + 此步骤将 Failproof AI 与你的运行框架关联，并安装 39 条内置策略。你可以用它们查看本地策略决策，并在 Failproof AI 审计你的会话、为 Agent 生成策略之前，提前试验执行控制效果。 - 可让安装程序自动检测你的运行环境，也可以显式指定。以下 12 个值均为有效的 `--cli` 参数——`claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity`、`goose`。 + 你可以让安装程序自动检测你的运行框架，也可以显式指定一个。12 个运行框架均为有效的 `--cli` 值——`claude`、`codex`、`copilot`、`cursor`、`opencode`、`pi`、`hermes`、`openclaw`、`factory`、`devin`、`antigravity`、`goose`。 ```bash - failproofai policies --install --cli claude --scope user # 编程 CLI + failproofai policies --install --cli claude --scope user # 编码 CLI failproofai policies --install --cli hermes --scope user # Slack/Telegram 网关 ``` - 所有 12 个运行环境均已验证支持在工具调用执行前进行拦截。轮次结束门控已在 8 个运行环境上验证——详见[执行强制能力](/zh/reference/harnesses#enforcement-capability)中的各运行环境矩阵。 + 在工具调用执行前拦截的能力已在全部 12 个运行框架上验证；轮次结束时的拦截门控已在 8 个上验证——各运行框架的详细矩阵请参阅[执行控制能力](/zh/reference/harnesses#enforcement-capability)。 - 参考[运行你的第一次故障检查](/zh/start/first-audit)。请使用具体的目标，例如"查找 Agent 在工具调用持续失败时未改变方式而重复重试的会话"。 + 按照[运行你的首次故障检查](/zh/start/first-audit)进行操作。使用具体的目标，例如"找出 Agent 在工具调用失败后未改变策略而直接重试的会话"。 - 参考[使用策略预防你的第一次故障](/zh/start/first-policy)。从观察模式开始，检查匹配项，然后对审核后的版本启用强制执行。 + 按照[使用策略预防你的第一个故障](/zh/start/first-policy)进行操作。从观察模式开始，检查匹配结果，然后对审查后的版本启用执行控制。 - 运行 `failproofai config --status`。配置正常时，会输出云端连接状态、守护进程状态，以及执行强制是否已暂停。 + 运行 `failproofai config --status`。配置正常时，将显示云连接状态、守护进程状态，以及执行控制是否处于暂停状态。 \ No newline at end of file