diff --git a/docs/ar/reference/harnesses.mdx b/docs/ar/reference/harnesses.mdx index e11d15a6..7981efed 100644 --- a/docs/ar/reference/harnesses.mdx +++ b/docs/ar/reference/harnesses.mdx @@ -1,86 +1,92 @@ --- -title: "وسائط الوكيل" -description: "التقط الجلسات وطبق السياسات عبر جميع وسائط الوكيل المدعومة البالغ عددها 12." +title: "أجهزة التشغيل الوسيطة للعوامل" +description: "التقط الجلسات وفرض السياسات عبر جميع أجهزة التشغيل الوسيطة الـ 12 المدعومة." icon: "plug-zap" --- -الوسيط هو كل شيء يعمل الوكيل بداخله فعليًا. Failproof AI يدعم اثنا عشر منها، في فئتين: +جهاز التشغيل الوسيط هو المكان الذي يعمل فيه العامل بالفعل. يدعم Failproof AI اثني عشر منها، موزعة على فئتين: -- **واجهات سطر أوامر البرمجة** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **بوابات الدردشة والمساعدين** (2) — Hermes (Slack, Telegram, cron), OpenClaw (مساعد ذاتي الاستضافة) +- **أدوات سطر الأوامر للبرمجة** (10) — Claude Code وCodex وGitHub Copilot CLI وCursor وOpenCode وPi وFactory Droid وDevin CLI وAntigravity CLI وGoose +- **بوابات الدردشة والمساعدات** (2) — Hermes (Slack وTelegram وcron) وOpenClaw (مساعد ذاتي التشغيل) -نفس السياسات وسجل الجلسة نفسه ينطبق مهما كان الوكيل يعمل فيه. تقوم طبقة محول واحدة بتعيين أسماء الأحداث الأصلية لكل وسيط، وأسماء الأدوات، وحقول مدخلات الأدوات على 29 حدثًا قانونيًا قبل تشغيل أي سياسة. +تنطبق نفس السياسات وسجل الجلسات نفسه بغض النظر عن جهاز التشغيل الوسيط الذي يعمل فيه العامل. تقوم طبقة محول واحدة بتعيين أسماء الأحداث الأصلية لكل جهاز تشغيل وسيط وأسماء الأدوات وحقول مدخلات الأدوات إلى 29 حدثًا معياريًا قبل تشغيل أي سياسة. -وكيل يعمل في **لا شيء** من الاثني عشر يتم جهزه مباشرة باستخدام [Python SDK](/ar/reference/custom-agents). هذا عقد مختلف، ويستحق التوضيح بصراحة: SDK يوفر التتبع والجلسات والتقييمات والتدقيق — **لا يفرض السياسات بمفرده.** منع الإجراء غير الآمن قبل تنفيذه يحتاج إلى هوك إنفاذ عند حدود أداة وقت التشغيل الخاص بك؛ [تواصل معنا](mailto:support@befailproof.ai) وسنقوم بتعيينه. +عامل يعمل في **أيٍ من الاثني عشر** يتم تجهيزه مباشرة باستخدام [Python SDK](/ar/reference/custom-agents). هذا عقد مختلف ويستحق التوضيح صراحة: SDK يوفر التتبع والجلسات والتقييمات والتدقيقات — **لا يفرض السياسات من تلقاء نفسه.** يتطلب حجب إجراء غير آمن قبل تنفيذه خطاف إنفاذ عند حد أداة وقتك؛ [تواصل معنا](mailto:support@befailproof.ai) وسنقوم بتعيينه. -| الوسيط | نطاقات الهوك المدعومة | +| جهاز التشغيل الوسيط | نطاقات الخطاف المدعومة | | --- | --- | -| Claude Code | User, project, local | -| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | User, project | -| Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | -| Hermes, OpenClaw | User | +| Claude Code | مستخدم، مشروع، محلي | +| Codex وGitHub Copilot CLI وCursor وOpenCode وPi | مستخدم، مشروع | +| Factory Droid وDevin CLI وAntigravity CLI وGoose | مستخدم، مشروع | +| Hermes وOpenClaw | مستخدم | -كل تكامل يوحد أسماء أحداث الهوك الأصلية والأداة وحقول مدخلات الأدوات قبل تشغيل السياسات. لا يمكن للسياسة أن تعمل إلا على الأحداث التي يكشفها الوسيط؛ اختبر السلوك في نهاية الدوران والتعليمات على الوسيط والإصدار الدقيق الذي تنشره. +يقوم كل تكامل بتوحيد أسماء أحداث الخطاف الأصلية وأسماء الأدوات وحقول مدخلات الأدوات قبل تشغيل السياسات. لا يمكن للسياسة أن تعمل إلا على الأحداث التي يكشفها جهاز التشغيل الوسيط؛ اختبر سلوك نهاية الدور والتعليمات على جهاز التشغيل الوسيط والإصدار المحدد الذي تنشره. -## قدرة الإنفاذ +## القدرة على الإنفاذ -"منع" يعني أن الحكم الذي يعيده محول التكيف الحالي يتم استهلاكه بواسطة الوسيط المسمى. قد يعدل الحجب بعد الأداة النتيجة المعروضة للنموذج ولكن لا يمكنه التراجع عن تأثير جانبي للأداة قد حدث بالفعل. +"حجب" يعني أن القرار المعاد من محول التيار الحالي يتم استهلاكه بواسطة جهاز التشغيل الوسيط المسمى. قد يستبدل الحجب بعد الأداة النتيجة المعروضة للنموذج لكنه لا يمكنه التراجع عن تأثير جانبي للأداة حدث بالفعل. -| الوسيط | أحداث الحجب المتحقق منها | التحفظات التي لا يمكن ملاحظتها أو غير حاجزة | +| جهاز التشغيل الوسيط | أحداث الحجب المتحقق منها | تحذيرات الملاحظة فقط أو عدم الحجب | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`، وعدة أحداث المهمة/الإعدادات | `PostToolUse`، دورة حياة الجلسة، الإخطارات، وأحداث ما بعد الفشل هي ملاحظة فقط. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | يعدل الحجب بعد الأداة النتيجة بعد التنفيذ؛ أحداث بداية الجلسة والضغط كبير هي ملاحظة فقط في محول التكيف الحالي. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | يعدل الحجب بعد الأداة النتيجة بعد التنفيذ؛ أحداث الجلسة والإخطارات هي ملاحظة فقط. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` وأحداث الجلسة هي ملاحظة فقط. | -| OpenCode | `PreToolUse` | أحداث ما بعد الأداة ودورة الحياة هي ملاحظة فقط؛ معالجة الإيقاف الحالية هي إرشادات للدوران اللاحق بدلاً من أن تكون بوابة تم التحقق منها. | -| Pi | `PreToolUse`, `UserPromptSubmit` | أحداث ما بعد الأداة ودورة الحياة هي ملاحظة فقط؛ تنطبق إرشادات الإيقاف على دوران لاحق. | -| Hermes | `PreToolUse` | حكومات ما بعد الأداة والجلسة والإيقاف الفرعي ليست بوابات. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | أحداث ما بعد الأداة والجلسة والإيقاف الفرعي والضغط كبير هي ملاحظة فقط. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | حكومات ما بعد الأداة والإيقاف الفرعي هي ملاحظة فقط. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, مشروط `PermissionRequest` | لا تعمل هوكات الإذن في كل وضع إذن؛ أحداث ما بعد الأداة والجلسة هي ملاحظة فقط. | -| Antigravity CLI | `PreToolUse`, `Stop` | حكومات موجز المستخدم وما بعد الأداة هي ملاحظة فقط؛ لا يزال يمكن حقن تعليمات الموجز. | -| Goose | `PreToolUse` | أحداث موجز المستخدم وما بعد الأداة والجلسة هي ملاحظة فقط. يوجد هوك إيقاف حجب أصلي في المنطقة الأعلى ولكن لا يتم تثبيته بواسطة محول التكيف الحالي. | - -القدرات حساسة للإصدار. أعد الاختبار بعد ترقية CLI الوكيل، خاصة عندما تعتمد السياسة على سلوك الموجز أو الإيقاف أو الإذن أو ما بعد الأداة بدلاً من بوابة ما قبل الأداة الشائعة. - -## تثبيت الالتقاط وهوكات السياسة +| Claude Code | `PreToolUse` و`UserPromptSubmit` و`PermissionRequest` و`Stop` و`SubagentStop` و`PreCompact` وعدة أحداث مهام/إعدادات | `PostToolUse` ودورة حياة الجلسة والإخطارات وأحداث ما بعد الفشل تراقبة فقط. | +| Codex | `PreToolUse` و`PermissionRequest` و`UserPromptSubmit` و`Stop` و`SubagentStop` و`PostToolUse` | الحجب بعد الأداة يستبدل النتيجة بعد التنفيذ؛ أحداث بدء الجلسة والضغط تراقبة في المحول الحالي. | +| GitHub Copilot CLI | `PreToolUse` و`UserPromptSubmit` و`PermissionRequest` و`Stop` و`SubagentStop` و`PostToolUse` | الحجب بعد الأداة يستبدل النتيجة بعد التنفيذ؛ أحداث الجلسة والإخطارات تراقبة. | +| Cursor | `PreToolUse` و`UserPromptSubmit` و`Stop` | `PostToolUse` وأحداث الجلسة تراقبة. | +| OpenCode | `PreToolUse` | أحداث ما بعد الأداة ودورة الحياة تراقبة؛ المعالجة الحالية للإيقاف هي إرشادات لدور لاحق وليست بوابة محققة. | +| Pi | `PreToolUse` و`UserPromptSubmit` | أحداث ما بعد الأداة ودورة الحياة تراقبة؛ إرشادات الإيقاف تنطبق على دور لاحق. | +| Hermes | `PreToolUse` | يوفر مكون إضافي أصلي `instruct()` كمقاطعة واحدة محدودة مرئية للنموذج قبل السماح بتكرار API لاحق. قرارات ما بعد الأداة والجلسة وإيقاف العامل الثانوي ليست بوابات. | +| OpenClaw | `PreToolUse` و`UserPromptSubmit` و`Stop` | أحداث ما بعد الأداة والجلسة وإيقاف العامل الثانوي والضغط تراقبة. | +| Factory Droid | `PreToolUse` و`UserPromptSubmit` و`Stop` و`PreCompact` | قرارات ما بعد الأداة وإيقاف العامل الثانوي تراقبة. | +| Devin CLI | `PreToolUse` و`UserPromptSubmit` و`Stop` و`PermissionRequest` مشروط | لا تعمل خطاف الإذن في كل وضع إذن؛ أحداث ما بعد الأداة والجلسة تراقبة. | +| Antigravity CLI | `PreToolUse` و`Stop` | قرارات موجه المستخدم وما بعد الأداة تراقبة؛ يمكن حقن تعليمات الموجه. | +| Goose | `PreToolUse` | أحداث موجه المستخدم وما بعد الأداة والجلسة تراقبة. يوجد خطاف إيقاف حجب أصلي في المنطقة الأعلى لكن لا يتم تثبيته بواسطة المحول الحالي. | + +القدرات حساسة للإصدار. أعد الاختبار بعد ترقية عامل CLI، خاصة عندما تعتمد السياسة على سلوك الموجه أو الإيقاف أو الإذن أو ما بعد الأداة بدلاً من بوابة ما قبل الأداة الشائعة. + +### مكون إضافي أصلي من Hermes + +يتم دمج Hermes من خلال مكون إضافي أصلي محلي للملف الشخصي بدلاً من أمر shell. يقوم التثبيت بنسخ المكون الإضافي في كل ملف شخصي Hermes افتراضي ومسمى، وتمكينه في `config.yaml` الخاص بذلك الملف الشخصي، والهجرة فقط إدخالات خطاف shell FailproofAI القديمة. يتجنب هذا عملية توليد العملية على كل خطاف ويسمح `instruct()` بالوصول إلى النموذج من خلال نتيجة الأداة المحجوبة الأصلية من Hermes. + +أول تعليمة متطابقة تحجب الاستدعاء المعلق. يبقى طلب API نفسه محجوبًا؛ قد تحاول تكرار نموذج لاحق. دفتر يومية محلي للملف الشخصي ومحدودية لكل دور تمنع التعليمات الاستشارية من أن تصبح حلقة غير محدودة. `deny()` يبقى حجبًا صعبًا. قم بتشغيل `failproofai config --status` لاكتشاف ملف شخصي معطل أو غير كامل أو مكرر أو تم إلغاء تكوينه للتو. + +## تثبيت خطاف الالتقاط والسياسة - 1. افتح **الإدارة → المفاتيح** وأنشئ مفتاحًا بـ `events:add` و `policies:pull`، باسم الجهاز أو البيئة. - 2. على الجهاز الهدف، اربط CLI المحلي بالمفتاح المعروض وثبّت هوكات الوسيط. - 3. ابدأ جلسة وكيل جديدة، ثم تأكد من أحداث الهوك والجلسة الخاصة بها تحت **المراقبة → الأحداث**. - 4. افتح **المراقبة → السياسة** لنفس نطاق الوقت وتأكد من أن قرار السياسة نُسب إلى الجهاز. + 1. افتح **الإدارة → المفاتيح** وأنشئ مفتاحًا بـ `events:add` و`policies:pull`، مسمى للجهاز أو البيئة. + 2. على الجهاز المستهدف، اربط CLI المحلي بالمفتاح المعروض وثبّت خطاف جهاز التشغيل الوسيط. + 3. ابدأ جلسة عامل جديدة، ثم أكد خطافها وأحداث جلستها تحت **المراقبة → الأحداث**. + 4. افتح **المراقبة → السياسة** للإطار الزمني نفسه وأكد أن قرار السياسة منسوب إلى الجهاز. - يبدأ الاتصال بمفتاح الجهاز. تأكد من أنه يتضمن أذونات الاستيعاب وتسليم السياسة قبل نسخ سره. + يبدأ الاتصال بمفتاح الجهاز. أكد أنه يتضمن كلا من أذونات الاستيعاب وتسليم السياسة قبل نسخ سره. - ![درج مفتاح API جديد يستخدم لمنح أذونات استيعاب الأحداث وتسليم السياسة.](/images/dashboard/key-create.png) + ![درج مفتاح API الجديد المستخدم لمنح أذونات استيعاب الأحداث وتسليم السياسة.](/images/dashboard/key-create.png) - بعد تثبيت الهوكات، يجب أن يعرض تدفق الأحداث أحداثًا جديدة من الجهاز والبيئة التي اتصلت بها. + بعد تثبيت الخطافات، يجب أن يعرض دفق الأحداث أحداثًا جديدة من الجهاز والبيئة التي اتصلت بها. - ![تدفق الأحداث المباشر المستخدم لتأكيد أن وسيط جديد مثبت يقدم تقارير.](/images/dashboard/events-stream.png) + ![دفق الأحداث المباشر المستخدم للتأكد من أن جهاز تشغيل وسيط تم تثبيته حديثًا يبلغ.](/images/dashboard/events-stream.png) - أخيرًا، تحقق من نسبة قرارات السياسة إلى نفس الجهاز. هذا يؤكد أن الوسيط يقدم تقارير عن نشاط السياسة وكذلك أحداث التتبع. + أخيرًا، تحقق من أن قرارات السياسة منسوبة إلى نفس الجهاز. هذا يؤكد أن جهاز التشغيل الوسيط يبلغ عن نشاط السياسة بالإضافة إلى أحداث التتبع. - ![صفحة السياسة المستخدمة للتحقق من قرارات السياسة من وسيط متصل حديثًا.](/images/dashboard/policy-observe.png) + ![صفحة السياسة المستخدمة للتحقق من قرارات السياسة من جهاز تشغيل وسيط متصل حديثًا.](/images/dashboard/policy-observe.png) - اقرأ مفتاح الجهاز في الشل. `read -s` يأخذه في موجه لا يعكس، حتى لا يظهر أبدًا في أمر أو في سجل الشل: + اقرأ مفتاح الجهاز في shell. `read -s` يأخذه عند موجه لا يصدر صدى، لذا لا يظهر أبدًا في أمر أو في سجل shell: ```bash read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - ثم قم بإعداد الجهاز — يربط هذا هوكات لكل وسيط مكتشف، ويثبت المعالج، ويتصل بـ Cloud: + ثم قم بإعداد الجهاز — هذا يربط الخطافات لكل جهاز تشغيل وسيط تم اكتشافه، وينصب البرنامج الثابت، ويتصل بـ Cloud: ```bash failproofai config failproofai policies add FailproofAI/policies ``` - الإعداد لا يفعل أي سياسة بمفرده، وهذا ما الأمر الثاني موجود له. + الإعداد لا يمكّن أي سياسة من تلقاء نفسها، وهذا ما الأمر الثاني من أجله. - أو استهدف وسائط سميت ونطاق تكوين: + أو استهدف أجهزة تشغيل وسيطة مسماة ونطاق إعداد: ```bash failproofai policies --install \ @@ -88,7 +94,7 @@ icon: "plug-zap" --scope user ``` - نطاق المشروع يحافظ على تكوين الهوك مع مستودع. نطاق المستخدم يغطي العمل عبر المستودعات. Claude Code يدعم أيضًا نطاق محلي؛ يختلف الدعم حسب الوسيط و CLI يرفض المجموعات غير المدعومة. + نطاق المشروع يحتفظ بإعداد الخطاف مع المستودع. نطاق المستخدم يغطي العمل عبر المستودعات. Claude Code يدعم أيضًا نطاق محلي؛ الدعم يختلف حسب جهاز التشغيل الوسيط و CLI يرفض المجموعات غير المدعومة. تحقق من الجهاز وأحداثه: @@ -104,9 +110,9 @@ icon: "plug-zap" - يتم تسجيل المسارات الإضافية على الجهاز، وليس في Cloud. بعد إضافة واحد، افتح **المراقبة → الجلسات**، وقم بالتصفية لبيئة الجهاز، وتأكد من ظهور الجلسات من المسار الجديد. افتح جلسة وتحقق من الوكيل والوسيط وطوابع أوقات الأحداث قبل الاعتماد عليها في التدقيق. + يتم تسجيل المسارات الإضافية على الجهاز وليس في Cloud. بعد إضافة واحد، افتح **المراقبة → الجلسات**، صفّي إلى بيئة الجهاز، وأكد أن الجلسات من المسار الجديد تظهر. افتح جلسة وتحقق من العامل والجهاز الوسيط وطوابع زمن الحدث قبل الاعتماد عليها في تدقيق. - ![قائمة الجلسات المصفاة لبيئة استقبال البيانات من مسار الالتقاط الإضافي.](/images/dashboard/sessions-list.png) + ![قائمة الجلسات المصفاة إلى البيئة التي تتلقى البيانات من مسار الالتقاط الإضافي.](/images/dashboard/sessions-list.png) أضف مسارًا مع تسمية اختيارية، ثم افحص المسارات المكونة: @@ -123,5 +129,5 @@ icon: "plug-zap" - شغّل جلسة جديدة واحدة بعد التثبيت. تحقق من تدفق الأحداث المباشر وقرار السياسة الفعلي قبل توسيع الإطلاق. + قم بتشغيل جلسة واحدة جديدة بعد التثبيت. تحقق من كل من دفق الأحداث المباشر وقرار سياسة فعلي قبل توسيع الطرح. \ No newline at end of file diff --git a/docs/de/reference/harnesses.mdx b/docs/de/reference/harnesses.mdx index ddc0a8f0..6fae6cd0 100644 --- a/docs/de/reference/harnesses.mdx +++ b/docs/de/reference/harnesses.mdx @@ -1,17 +1,17 @@ --- title: "Agent-Harnesses" -description: "Sitzungen erfassen und Richtlinien für alle 12 unterstützten Agent-Harnesses durchsetzen." +description: "Sessions aufzeichnen und Richtlinien für alle 12 unterstützten Agent-Harnesses durchsetzen." icon: "plug-zap" --- Ein Harness ist die Umgebung, in der Ihr Agent tatsächlich ausgeführt wird. Failproof AI unterstützt zwölf davon, in zwei Kategorien: - **Coding-CLIs** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **Chat- und Assistant-Gateways** (2) — Hermes (Slack, Telegram, Cron), OpenClaw (selbst gehosteter Assistent) +- **Chat- und Assistent-Gateways** (2) — Hermes (Slack, Telegram, Cron), OpenClaw (selbst gehosteter Assistent) -Dieselben Richtlinien und dieselbe Sitzungshistorie gelten unabhängig davon, in welchem Harness ein Agent läuft. Eine Adapterschicht bildet die nativen Event-Namen, Tool-Namen und Tool-Input-Felder jedes Harness auf 29 kanonische Events ab, bevor eine Richtlinie ausgewertet wird. +Dieselben Richtlinien und dieselbe Session-Historie gelten unabhängig davon, in welchem Harness ein Agent ausgeführt wird. Eine Adapter-Schicht übersetzt die nativen Ereignisnamen, Tool-Namen und Tool-Eingabefelder jedes Harness auf 29 kanonische Ereignisse, bevor eine Richtlinie ausgeführt wird. -Ein Agent, der in **keinem** der zwölf Harnesses läuft, wird direkt mit dem [Python SDK](/de/reference/custom-agents) instrumentiert. Das ist ein anderer Vertrag, den es klar zu benennen gilt: Das SDK liefert Tracing, Sitzungen, Evaluierungen und Audits — **es setzt Richtlinien nicht eigenständig durch.** Um eine unsichere Aktion vor der Ausführung zu blockieren, wird ein Enforcement-Hook an der Tool-Grenze Ihrer Laufzeitumgebung benötigt; [kontaktieren Sie uns](mailto:support@befailproof.ai) und wir werden es einrichten. +Ein Agent, der in **keinem** der zwölf Harnesses läuft, wird direkt mit dem [Python SDK](/de/reference/custom-agents) instrumentiert. Das ist ein anderer Vertrag, und das sollte klar benannt werden: Das SDK liefert Tracing, Sessions, Evaluierungen und Audits — **es setzt Richtlinien nicht selbst durch.** Um eine unsichere Aktion vor ihrer Ausführung zu blockieren, ist ein Enforcement-Hook an der Tool-Grenze Ihrer Laufzeitumgebung erforderlich. [Kontaktieren Sie uns](mailto:support@befailproof.ai) und wir kümmern uns um die Zuordnung. | Harness | Unterstützte Hook-Scopes | | --- | --- | @@ -20,28 +20,34 @@ Ein Agent, der in **keinem** der zwölf Harnesses läuft, wird direkt mit dem [P | Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | | Hermes, OpenClaw | User | -Jede Integration normalisiert ihre nativen Hook-Event-Namen, Tool-Namen und Tool-Input-Felder, bevor Richtlinien ausgewertet werden. Eine Richtlinie kann nur auf Events reagieren, die der Harness exponiert; testen Sie das End-of-Turn- und Instruction-Verhalten auf genau dem Harness und der Version, die Sie einsetzen. +Jede Integration normalisiert ihre nativen Hook-Ereignisnamen, Tool-Namen und Tool-Eingabefelder, bevor Richtlinien ausgeführt werden. Eine Richtlinie kann nur auf Ereignisse reagieren, die der Harness bereitstellt. Testen Sie das Verhalten am Ende eines Turns sowie das Instruktionsverhalten auf dem genauen Harness und der Version, die Sie einsetzen. -## Enforcement-Fähigkeiten +## Durchsetzungsfähigkeit -„Blockieren" bedeutet, dass das vom aktuellen Adapter zurückgegebene Urteil vom genannten Harness verarbeitet wird. Post-Tool-Blockierung kann das dem Modell angezeigte Ergebnis ersetzen, aber keine Tool-Nebenwirkung rückgängig machen, die bereits eingetreten ist. +„Blockieren" bedeutet, dass der zurückgegebene Bescheid des aktuellen Adapters vom genannten Harness verarbeitet wird. Ein Post-Tool-Block kann das dem Modell angezeigte Ergebnis ersetzen, aber einen bereits eingetretenen Tool-Seiteneffekt nicht rückgängig machen. -| Harness | Verifizierte Blocking-Events | Nur-Beobachtungs- oder Nicht-Blocking-Einschränkungen | +| Harness | Verifizierte blockierende Ereignisse | Nur-Beobachtungs- oder nicht-blockierende Hinweise | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` und mehrere Task/Config-Events | `PostToolUse`, Sitzungs-Lifecycle, Benachrichtigungen und Post-Failure-Events sind beobachtend. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Post-Tool-Blockierung ersetzt das Ergebnis nach der Ausführung; Session-Start- und Compact-Events sind im aktuellen Adapter beobachtend. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Post-Tool-Blockierung ersetzt das Ergebnis nach der Ausführung; Sitzungs- und Benachrichtigungs-Events sind beobachtend. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` und Sitzungs-Events sind beobachtend. | -| OpenCode | `PreToolUse` | Post-Tool- und Lifecycle-Events sind beobachtend; die aktuelle Stop-Behandlung ist eine Anleitung für eine spätere Runde, kein verifiziertes Gate. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Post-Tool- und Lifecycle-Events sind beobachtend; Stop-Anleitung gilt für eine spätere Runde. | -| Hermes | `PreToolUse` | Post-Tool-, Sitzungs- und Subagent-Stop-Urteile sind keine Gates. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Post-Tool-, Sitzungs-, Subagent-Stop- und Compaction-Events sind beobachtend. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Post-Tool- und Subagent-Stop-Urteile sind beobachtend. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, bedingtes `PermissionRequest` | Permission-Hooks laufen nicht in jedem Permission-Modus; Post-Tool- und Sitzungs-Events sind beobachtend. | -| Antigravity CLI | `PreToolUse`, `Stop` | User-Prompt- und Post-Tool-Urteile sind beobachtend; Prompt-Instruktionen können dennoch injiziert werden. | -| Goose | `PreToolUse` | User-Prompt-, Post-Tool- und Sitzungs-Events sind beobachtend. Ein nativer blockierender Stop-Hook existiert vorgelagert, wird aber vom aktuellen Adapter nicht installiert. | - -Fähigkeiten sind versionsabhängig. Testen Sie nach dem Upgrade einer Agent-CLI erneut, insbesondere wenn eine Richtlinie auf Prompt-, Stop-, Permission- oder Post-Tool-Verhalten statt auf das übliche Pre-Tool-Gate angewiesen ist. +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` und mehrere Task-/Konfigurations-Ereignisse | `PostToolUse`, Session-Lifecycle, Benachrichtigungen und Post-Failure-Ereignisse sind beobachtend. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Post-Tool-Blockierung ersetzt das Ergebnis nach der Ausführung; Session-Start- und Compact-Ereignisse sind im aktuellen Adapter beobachtend. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Post-Tool-Blockierung ersetzt das Ergebnis nach der Ausführung; Session- und Benachrichtigungs-Ereignisse sind beobachtend. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` und Session-Ereignisse sind beobachtend. | +| OpenCode | `PreToolUse` | Post-Tool- und Lifecycle-Ereignisse sind beobachtend; die aktuelle Stop-Behandlung ist eine Empfehlung für einen späteren Turn, kein verifizierter Kontrollpunkt. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Post-Tool- und Lifecycle-Ereignisse sind beobachtend; Stop-Empfehlungen gelten für einen späteren Turn. | +| Hermes | `PreToolUse` | Ein natives Plugin liefert `instruct()` als einmalige, für das Modell sichtbare Unterbrechung, bevor eine spätere API-Iteration zugelassen wird. Post-Tool-, Session- und Subagent-Stop-Bescheide sind keine Kontrollpunkte. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Post-Tool-, Session-, Subagent-Stop- und Komprimierungs-Ereignisse sind beobachtend. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Post-Tool- und Subagent-Stop-Bescheide sind beobachtend. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, bedingtes `PermissionRequest` | Permission-Hooks werden nicht in jedem Permission-Modus ausgeführt; Post-Tool- und Session-Ereignisse sind beobachtend. | +| Antigravity CLI | `PreToolUse`, `Stop` | User-Prompt- und Post-Tool-Bescheide sind beobachtend; Prompt-Instruktionen können weiterhin injiziert werden. | +| Goose | `PreToolUse` | User-Prompt-, Post-Tool- und Session-Ereignisse sind beobachtend. Ein nativer blockierender Stop-Hook ist vorgelagert vorhanden, wird aber vom aktuellen Adapter nicht installiert. | + +Die Fähigkeiten sind versionsabhängig. Führen Sie nach dem Upgrade einer Agent-CLI erneut Tests durch, insbesondere wenn eine Richtlinie auf Prompt-, Stop-, Permission- oder Post-Tool-Verhalten anstatt auf den üblichen Pre-Tool-Kontrollpunkt angewiesen ist. + +### Natives Hermes-Plugin + +Hermes wird über ein profillokal installiertes natives Plugin integriert, nicht über einen Shell-Befehl. Die Installation kopiert das Plugin in jedes Standard- und benannte Hermes-Profil, aktiviert es in der `config.yaml` dieses Profils und migriert nur veraltete FailproofAI Shell-Hook-Einträge. Dadurch wird beim jedem Hook auf einen Prozess-Spawn verzichtet, und `instruct()` erreicht das Modell über Hermes' nativen Blocked-Tool-Result. + +Die erste passende Instruktion blockiert den ausstehenden Aufruf. Dieselbe API-Anfrage bleibt blockiert; eine spätere Modell-Iteration kann es erneut versuchen. Ein persistentes, profilweites Ledger und ein Turn-Cap verhindern, dass eine Empfehlungs-Instruktion zu einer unbegrenzten Schleife wird. `deny()` bleibt ein harter Block. Führen Sie `failproofai config --status` aus, um ein deaktiviertes, unvollständiges, dupliziertes oder neu unkonfiguriertes Profil zu erkennen. ## Capture- und Policy-Hooks installieren @@ -49,38 +55,38 @@ Fähigkeiten sind versionsabhängig. Testen Sie nach dem Upgrade einer Agent-CLI 1. Öffnen Sie **Administration → Keys** und erstellen Sie einen Schlüssel mit `events:add` und `policies:pull`, benannt nach der Maschine oder Umgebung. 2. Verbinden Sie auf der Zielmaschine die lokale CLI mit dem angezeigten Schlüssel und installieren Sie die Harness-Hooks. - 3. Starten Sie eine neue Agent-Sitzung und bestätigen Sie deren Hook- und Sitzungs-Events unter **Observe → Events**. - 4. Öffnen Sie **Observe → policy** für dasselbe Zeitfenster und bestätigen Sie, dass eine Richtlinienentscheidung der Maschine zugeordnet ist. + 3. Starten Sie eine neue Agent-Session und bestätigen Sie deren Hook- und Session-Ereignisse unter **Observe → Events**. + 4. Öffnen Sie **Observe → policy** für dasselbe Zeitfenster und bestätigen Sie, dass eine Richtlinienentscheidung der Maschine zugeordnet wird. - Die Verbindung beginnt mit einem Maschinenschlüssel. Vergewissern Sie sich, dass er sowohl Ingestion- als auch Policy-Delivery-Berechtigungen enthält, bevor Sie sein Secret kopieren. + Die Verbindung beginnt mit einem Machine-Key. Stellen Sie sicher, dass er sowohl Ingestion- als auch Policy-Delivery-Berechtigungen enthält, bevor Sie das Secret kopieren. - ![Die Drawer-Ansicht für neue API-Schlüssel zum Erteilen von Event-Ingestion- und Policy-Delivery-Berechtigungen.](/images/dashboard/key-create.png) + ![Die Drawer-Ansicht für neue API-Schlüssel zur Vergabe von Ereignis-Ingestion- und Policy-Delivery-Berechtigungen.](/images/dashboard/key-create.png) - Nach der Installation der Hooks sollte der Events-Stream neue Events von der verbundenen Maschine und Umgebung anzeigen. + Nach der Installation der Hooks sollte der Events-Stream neue Ereignisse von der verbundenen Maschine und Umgebung anzeigen. - ![Der Live-Events-Stream zur Bestätigung, dass ein neu installierter Harness Berichte sendet.](/images/dashboard/events-stream.png) + ![Der Live-Events-Stream zur Bestätigung, dass ein neu installierter Harness Daten meldet.](/images/dashboard/events-stream.png) - Überprüfen Sie abschließend, ob Richtlinienentscheidungen derselben Maschine zugeordnet sind. Dies bestätigt, dass der Harness sowohl Richtlinienaktivität als auch Trace-Events meldet. + Überprüfen Sie abschließend, ob Richtlinienentscheidungen derselben Maschine zugeordnet werden. Dies bestätigt, dass der Harness sowohl Richtlinienaktivitäten als auch Trace-Ereignisse meldet. - ![Die Policy-Seite zur Verifizierung von Richtlinienentscheidungen eines neu verbundenen Harness.](/images/dashboard/policy-observe.png) + ![Die Policy-Seite zur Überprüfung von Richtlinienentscheidungen eines neu verbundenen Harness.](/images/dashboard/policy-observe.png) - Lesen Sie den Maschinenschlüssel in die Shell ein. `read -s` nimmt ihn über eine Eingabeaufforderung entgegen, die nicht angezeigt wird, sodass er nie in einem Befehl oder der Shell-History erscheint: + Lesen Sie den Machine-Key in die Shell ein. `read -s` nimmt ihn über eine Eingabeaufforderung entgegen, die keine Ausgabe erzeugt, sodass er weder im Befehl noch im Shell-Verlauf erscheint: ```bash read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - Richten Sie dann die Maschine ein — dieser Schritt verdrahtet Hooks für jeden erkannten Harness, installiert den Daemon und verbindet sich mit Cloud: + Richten Sie dann die Maschine ein — dieser Befehl verdrahtet Hooks für jeden erkannten Harness, installiert den Daemon und stellt eine Verbindung zur Cloud her: ```bash failproofai config failproofai policies add FailproofAI/policies ``` - Das Setup aktiviert keine Richtlinie von sich aus — dafür ist der zweite Befehl gedacht. + Das Setup aktiviert selbst keine Richtlinie — dafür ist der zweite Befehl gedacht. - Oder wählen Sie gezielt bestimmte Harnesses und einen Konfigurationsscope: + Alternativ können Sie bestimmte Harnesses und einen Konfigurationsscope angeben: ```bash failproofai policies --install \ @@ -88,9 +94,9 @@ Fähigkeiten sind versionsabhängig. Testen Sie nach dem Upgrade einer Agent-CLI --scope user ``` - Der Project-Scope speichert die Hook-Konfiguration zusammen mit einem Repository. Der User-Scope deckt die Arbeit über mehrere Repositories hinweg ab. Claude Code unterstützt zusätzlich den Local-Scope; die Unterstützung variiert je nach Harness, und die CLI weist nicht unterstützte Kombinationen ab. + Der Project-Scope hält die Hook-Konfiguration beim Repository. Der User-Scope gilt für die Arbeit über Repositories hinweg. Claude Code unterstützt zusätzlich den Local-Scope; die Unterstützung variiert je nach Harness, und die CLI lehnt nicht unterstützte Kombinationen ab. - Überprüfen Sie die Maschine und ihre Events: + Überprüfen Sie die Maschine und ihre Ereignisse: ```bash failproofai config --status @@ -100,16 +106,16 @@ Fähigkeiten sind versionsabhängig. Testen Sie nach dem Upgrade einer Agent-CLI -## Einen nicht-standardmäßigen Sitzungspfad hinzufügen +## Einen nicht standardmäßigen Session-Pfad hinzufügen - Zusätzliche Pfade werden auf der Maschine registriert, nicht in Cloud. Nach dem Hinzufügen öffnen Sie **Observe → Sessions**, filtern nach der Umgebung der Maschine und bestätigen, dass Sitzungen vom neuen Pfad erscheinen. Öffnen Sie eine Sitzung und prüfen Sie den Agenten, den Harness und die Event-Zeitstempel, bevor Sie ihn für ein Audit verwenden. + Zusätzliche Pfade werden auf der Maschine registriert, nicht in der Cloud. Öffnen Sie nach dem Hinzufügen eines Pfades **Observe → Sessions**, filtern Sie nach der Umgebung der Maschine und bestätigen Sie, dass Sessions aus dem neuen Pfad erscheinen. Öffnen Sie eine Session und prüfen Sie Agent, Harness und Ereignis-Zeitstempel, bevor Sie sie in einem Audit verwenden. - ![Die Sitzungsliste gefiltert nach der Umgebung, die Daten vom zusätzlichen Capture-Pfad empfängt.](/images/dashboard/sessions-list.png) + ![Die Sessions-Liste, gefiltert nach der Umgebung, die Daten aus dem zusätzlichen Capture-Pfad empfängt.](/images/dashboard/sessions-list.png) - Fügen Sie einen Pfad mit einem optionalen Label hinzu und prüfen Sie die konfigurierten Pfade: + Fügen Sie einen Pfad mit einem optionalen Label hinzu und überprüfen Sie dann die konfigurierten Pfade: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -123,5 +129,5 @@ Fähigkeiten sind versionsabhängig. Testen Sie nach dem Upgrade einer Agent-CLI - Führen Sie nach der Installation eine neue Sitzung durch. Überprüfen Sie sowohl den Live-Event-Stream als auch eine tatsächliche Richtlinienentscheidung, bevor Sie den Rollout ausweiten. + Führen Sie nach der Installation eine neue Session aus. Überprüfen Sie sowohl den Live-Event-Stream als auch eine tatsächliche Richtlinienentscheidung, bevor Sie den Rollout ausweiten. \ No newline at end of file diff --git a/docs/es/reference/harnesses.mdx b/docs/es/reference/harnesses.mdx index df47004a..4e92fb7c 100644 --- a/docs/es/reference/harnesses.mdx +++ b/docs/es/reference/harnesses.mdx @@ -1,68 +1,84 @@ --- -title: "Agentes soportados" -description: "Captura sesiones y aplica políticas en los 12 agentes compatibles." +title: "Entornos de agente" +description: "Capture sesiones y aplique políticas en los 12 entornos de agente compatibles." icon: "plug-zap" --- -Un harness es el entorno en el que realmente se ejecuta tu agente. Failproof AI soporta doce de ellos, en dos categorías: +Un entorno es el espacio en el que tu agente realmente se ejecuta. Failproof AI admite doce de ellos, en dos categorías: -- **CLIs de programación** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **Gateways de chat y asistentes** (2) — Hermes (Slack, Telegram, cron), OpenClaw (asistente autoalojado) +- **CLIs de codificación** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose +- **Gateways de chat y asistente** (2) — Hermes (Slack, Telegram, cron), OpenClaw (asistente autoalojado) -Las mismas políticas y el mismo historial de sesiones se aplican independientemente del entorno en que se ejecute el agente. Una capa de adaptador mapea los nombres de eventos nativos, nombres de herramientas y campos de entrada de cada harness en 29 eventos canónicos antes de que se ejecute cualquier política. +Las mismas políticas y el mismo historial de sesión se aplican independientemente del entorno en que se ejecute el agente. Una capa de adaptadores traduce los nombres de eventos nativos, nombres de herramientas y campos de entrada de cada entorno a 29 eventos canónicos antes de que se ejecute cualquier política. -Un agente que no se ejecute en **ninguno** de los doce se instrumenta directamente con el [SDK de Python](/es/reference/custom-agents). Ese es un contrato distinto, y vale la pena dejarlo claro: el SDK proporciona trazabilidad, sesiones, evaluaciones y auditorías — **no aplica políticas por sí solo.** Para bloquear una acción insegura antes de que se ejecute se necesita un hook de aplicación en el límite de herramientas de tu runtime; [contáctanos](mailto:support@befailproof.ai) y lo mapearemos. +Un agente que no se ejecuta en **ninguno** de los doce se instrumenta directamente con el [SDK de Python](/es/reference/custom-agents). Este es un contrato diferente, y vale la pena mencionarlo claramente: el SDK proporciona trazado, sesiones, evaluaciones y auditorías — **no aplica políticas por sí solo.** Bloquear una acción no segura antes de que se ejecute requiere un hook de aplicación en el límite de herramientas de tu entorno de ejecución; [contáctanos](mailto:support@befailproof.ai) y lo mapeamos. -| Harness | Ámbitos de hook soportados | +| Entorno | Ámbitos de hook admitidos | | --- | --- | | Claude Code | Usuario, proyecto, local | | Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | Usuario, proyecto | | Factory Droid, Devin CLI, Antigravity CLI, Goose | Usuario, proyecto | | Hermes, OpenClaw | Usuario | -Cada integración normaliza los nombres de eventos nativos, nombres de herramientas y campos de entrada antes de que se ejecuten las políticas. Una política solo puede actuar sobre los eventos que el harness expone; prueba el comportamiento al final del turno y las instrucciones en el harness y versión exactos que vayas a desplegar. +Cada integración normaliza los nombres de eventos nativos, nombres de herramientas y campos de entrada antes de que se ejecuten las políticas. Una política solo puede actuar sobre los eventos que expone el entorno; prueba el comportamiento de fin de turno e instrucciones en el entorno y versión exactos que despliegues. ## Capacidades de aplicación -"Bloquear" significa que el veredicto devuelto por el adaptador actual es consumido por el harness indicado. El bloqueo post-herramienta puede reemplazar el resultado mostrado al modelo, pero no puede deshacer un efecto secundario de la herramienta que ya ocurrió. +"Bloquear" significa que el veredicto devuelto por el adaptador actual es consumido por el entorno indicado. El bloqueo post-herramienta puede reemplazar el resultado mostrado al modelo, pero no puede deshacer un efecto secundario de herramienta que ya ocurrió. -| Harness | Eventos de bloqueo verificados | Advertencias de solo observación o no bloqueantes | +| Entorno | Eventos de bloqueo verificados | Advertencias de solo observación o no bloqueantes | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` y varios eventos de tarea/configuración | `PostToolUse`, el ciclo de vida de sesión, las notificaciones y los eventos post-fallo son observacionales. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | El bloqueo post-herramienta reemplaza el resultado tras la ejecución; los eventos de inicio de sesión y compactación son observacionales en el adaptador actual. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | El bloqueo post-herramienta reemplaza el resultado tras la ejecución; los eventos de sesión y notificación son observacionales. | +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` y varios eventos de tarea/configuración | `PostToolUse`, ciclo de vida de sesión, notificaciones y eventos post-fallo son observacionales. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | El bloqueo post-herramienta reemplaza el resultado después de la ejecución; los eventos de inicio de sesión y compactación son observacionales en el adaptador actual. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | El bloqueo post-herramienta reemplaza el resultado después de la ejecución; los eventos de sesión y notificación son observacionales. | | Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` y los eventos de sesión son observacionales. | -| OpenCode | `PreToolUse` | Los eventos post-herramienta y de ciclo de vida son observacionales; el manejo actual de stop es una guía para un turno posterior, no una puerta verificada. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Los eventos post-herramienta y de ciclo de vida son observacionales; la guía de stop se aplica a un turno posterior. | -| Hermes | `PreToolUse` | Los veredictos post-herramienta, de sesión y de subagent-stop no son puertas de control. | +| OpenCode | `PreToolUse` | Los eventos post-herramienta y de ciclo de vida son observacionales; el manejo de stop actual es orientación para un turno posterior, no una barrera verificada. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Los eventos post-herramienta y de ciclo de vida son observacionales; la orientación de stop se aplica a un turno posterior. | +| Hermes | `PreToolUse` | Un plugin nativo entrega `instruct()` como una interrupción acotada y visible para el modelo antes de permitir una iteración de API posterior. Los veredictos post-herramienta, de sesión y de subagent-stop no son barreras. | | OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Los eventos post-herramienta, de sesión, subagent-stop y compactación son observacionales. | | Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Los veredictos post-herramienta y subagent-stop son observacionales. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` condicional | Los hooks de permiso no se ejecutan en todos los modos de permiso; los eventos post-herramienta y de sesión son observacionales. | -| Antigravity CLI | `PreToolUse`, `Stop` | Los veredictos de user-prompt y post-herramienta son observacionales; las instrucciones de prompt aún pueden inyectarse. | -| Goose | `PreToolUse` | Los eventos de user-prompt, post-herramienta y de sesión son observacionales. Existe un hook de stop nativo bloqueante en la capa superior, pero el adaptador actual no lo instala. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` condicional | Los hooks de permisos no se ejecutan en todos los modos de permiso; los eventos post-herramienta y de sesión son observacionales. | +| Antigravity CLI | `PreToolUse`, `Stop` | Los veredictos de prompt de usuario y post-herramienta son observacionales; las instrucciones de prompt aún pueden inyectarse. | +| Goose | `PreToolUse` | Los eventos de prompt de usuario, post-herramienta y de sesión son observacionales. Existe un hook de stop bloqueante nativo en upstream, pero no está instalado por el adaptador actual. | -Las capacidades dependen de la versión. Vuelve a probar tras actualizar un CLI de agente, especialmente cuando una política dependa del comportamiento de prompt, stop, permiso o post-herramienta en lugar de la puerta pre-herramienta habitual. +Las capacidades dependen de la versión. Vuelve a probar tras actualizar un CLI de agente, especialmente cuando una política depende del comportamiento de prompt, stop, permisos o post-herramienta en lugar de la barrera pre-herramienta común. -## Instalar hooks de captura y políticas +### Plugin nativo de Hermes + +Hermes se integra a través de un plugin nativo local del perfil en lugar de un +comando de shell. La instalación copia el plugin en todos los perfiles de Hermes +predeterminados y con nombre, lo habilita en el `config.yaml` de ese perfil, y +migra únicamente las entradas de hook de shell legacy de FailproofAI. Esto evita +generar un proceso en cada hook y permite que `instruct()` llegue al modelo a +través del resultado de herramienta bloqueada nativo de Hermes. + +La primera instrucción coincidente bloquea la llamada pendiente. La misma solicitud +de API permanece bloqueada; una iteración posterior del modelo puede volver a intentarlo. +Un registro persistente con ámbito de perfil y un límite por turno evitan que una +instrucción consultiva se convierta en un bucle sin límite. `deny()` sigue siendo +un bloqueo estricto. Ejecuta `failproofai config --status` para detectar un perfil +deshabilitado, incompleto, duplicado o sin configurar recientemente. + +## Instalar hooks de captura y política - 1. Abre **Administración → Claves** y crea una clave con `events:add` y `policies:pull`, con un nombre que identifique la máquina o el entorno. - 2. En la máquina de destino, conecta el CLI local con la clave mostrada e instala los hooks del harness. - 3. Inicia una nueva sesión de agente y confirma sus eventos de hook y sesión en **Observar → Eventos**. - 4. Abre **Observar → Política** para el mismo intervalo de tiempo y confirma que una decisión de política está atribuida a la máquina. + 1. Abre **Administración → Claves** y crea una clave con `events:add` y `policies:pull`, con un nombre asociado a la máquina o entorno. + 2. En la máquina de destino, conecta el CLI local con la clave mostrada e instala los hooks del entorno. + 3. Inicia una nueva sesión de agente y confirma sus hooks y eventos de sesión en **Observar → Eventos**. + 4. Abre **Observar → Política** para la misma ventana de tiempo y confirma que una decisión de política está atribuida a la máquina. - La conexión comienza con una clave de máquina. Confirma que incluye permisos de ingesta y entrega de políticas antes de copiar su secreto. + La conexión comienza con una clave de máquina. Confirma que incluye tanto permisos de ingesta como de entrega de políticas antes de copiar su secreto. - ![El panel para crear una nueva clave de API, utilizado para otorgar permisos de ingesta de eventos y entrega de políticas.](/images/dashboard/key-create.png) + ![El panel de nueva clave de API usado para conceder permisos de ingesta de eventos y entrega de políticas.](/images/dashboard/key-create.png) - Tras instalar los hooks, el flujo de Eventos debería mostrar nuevos eventos desde la máquina y el entorno que conectaste. + Tras instalar los hooks, el flujo de Eventos debería mostrar nuevos eventos de la máquina y el entorno que conectaste. - ![El flujo de Eventos en tiempo real utilizado para confirmar que un harness recién instalado está reportando.](/images/dashboard/events-stream.png) + ![El flujo de Eventos en vivo usado para confirmar que un entorno recién instalado está reportando.](/images/dashboard/events-stream.png) - Por último, verifica que las decisiones de política están atribuidas a la misma máquina. Esto confirma que el harness está reportando tanto la actividad de políticas como los eventos de traza. + Por último, verifica que las decisiones de política estén atribuidas a la misma máquina. Esto confirma que el entorno está reportando actividad de política además de eventos de trazado. - ![La página de Política utilizada para verificar las decisiones de política de un harness recién conectado.](/images/dashboard/policy-observe.png) + ![La página de Política usada para verificar decisiones de política de un entorno recién conectado.](/images/dashboard/policy-observe.png) Lee la clave de máquina en el shell. `read -s` la solicita en un prompt que no hace eco, por lo que nunca aparece en un comando ni en el historial del shell: @@ -71,16 +87,16 @@ Las capacidades dependen de la versión. Vuelve a probar tras actualizar un CLI read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - Luego configura la máquina — esto conecta hooks para cada harness detectado, instala el daemon y se conecta a Cloud: + Luego configura la máquina — esto conecta hooks para cada entorno detectado, instala el daemon y se conecta a Cloud: ```bash failproofai config failproofai policies add FailproofAI/policies ``` - La configuración no habilita ninguna política por sí sola; para eso sirve el segundo comando. + La configuración no habilita ninguna política por sí misma; para eso es el segundo comando. - También puedes apuntar a harnesses específicos y un ámbito de configuración: + O apunta a entornos específicos y un ámbito de configuración: ```bash failproofai policies --install \ @@ -88,7 +104,7 @@ Las capacidades dependen de la versión. Vuelve a probar tras actualizar un CLI --scope user ``` - El ámbito de proyecto mantiene la configuración de hooks junto al repositorio. El ámbito de usuario cubre el trabajo en múltiples repositorios. Claude Code también soporta el ámbito local; el soporte varía según el harness y el CLI rechaza las combinaciones no soportadas. + El ámbito de proyecto mantiene la configuración de hooks junto al repositorio. El ámbito de usuario cubre el trabajo en varios repositorios. Claude Code también admite ámbito local; la compatibilidad varía según el entorno y el CLI rechaza las combinaciones no admitidas. Verifica la máquina y sus eventos: @@ -104,12 +120,12 @@ Las capacidades dependen de la versión. Vuelve a probar tras actualizar un CLI - Las rutas adicionales se registran en la máquina, no en Cloud. Después de agregar una, abre **Observar → Sesiones**, filtra por el entorno de la máquina y confirma que aparecen sesiones desde la nueva ruta. Abre una sesión y comprueba el agente, el harness y las marcas de tiempo de los eventos antes de utilizarla en una auditoría. + Las rutas adicionales se registran en la máquina, no en Cloud. Después de agregar una, abre **Observar → Sesiones**, filtra por el entorno de la máquina y confirma que aparecen sesiones desde la nueva ruta. Abre una sesión y revisa el agente, el entorno y las marcas de tiempo de eventos antes de utilizarla en una auditoría. - ![La lista de Sesiones filtrada al entorno que recibe datos de la ruta de captura adicional.](/images/dashboard/sessions-list.png) + ![La lista de Sesiones filtrada al entorno que recibe datos desde la ruta de captura adicional.](/images/dashboard/sessions-list.png) - Agrega una ruta con una etiqueta opcional y luego inspecciona las rutas configuradas: + Agrega una ruta con una etiqueta opcional, luego inspecciona las rutas configuradas: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -123,5 +139,5 @@ Las capacidades dependen de la versión. Vuelve a probar tras actualizar un CLI - Ejecuta una sesión nueva tras la instalación. Verifica tanto el flujo de eventos en tiempo real como una decisión de política real antes de ampliar el despliegue. + Ejecuta una nueva sesión tras la instalación. Verifica tanto el flujo de eventos en vivo como una decisión de política real antes de ampliar el despliegue. \ No newline at end of file diff --git a/docs/fr/reference/harnesses.mdx b/docs/fr/reference/harnesses.mdx index be68d7fd..c0447170 100644 --- a/docs/fr/reference/harnesses.mdx +++ b/docs/fr/reference/harnesses.mdx @@ -1,86 +1,92 @@ --- title: "Harnais d'agents" -description: "Capturez les sessions et appliquez les politiques sur l'ensemble des 12 harnais d'agents supportés." +description: "Capturez les sessions et appliquez des politiques sur les 12 harnais d'agents pris en charge." icon: "plug-zap" --- -Un harnais désigne l'environnement dans lequel votre agent s'exécute réellement. Failproof AI en supporte douze, répartis en deux catégories : +Un harnais désigne l'environnement dans lequel votre agent s'exécute réellement. Failproof AI en prend en charge douze, répartis en deux catégories : -- **CLIs de développement** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose +- **CLI de codage** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose - **Passerelles de chat et d'assistant** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistant auto-hébergé) -Les mêmes politiques et le même historique de sessions s'appliquent quel que soit le harnais utilisé par l'agent. Une couche d'adaptation unifie les noms d'événements natifs, les noms d'outils et les champs d'entrée de chaque harnais en 29 événements canoniques avant qu'une politique ne s'exécute. +Les mêmes politiques et le même historique de sessions s'appliquent quel que soit le harnais utilisé par un agent. Une couche d'adaptation mappe les noms d'événements natifs, les noms d'outils et les champs d'entrée d'outils de chaque harnais vers 29 événements canoniques, avant toute exécution de politique. -Un agent qui ne s'exécute dans **aucun** des douze est instrumenté directement avec le [SDK Python](/fr/reference/custom-agents). Il s'agit d'un contrat différent, qu'il convient d'énoncer clairement : le SDK fournit le traçage, les sessions, les évaluations et les audits — **il n'applique pas les politiques de lui-même.** Bloquer une action non sécurisée avant son exécution nécessite un hook d'application au niveau de la frontière des outils de votre runtime ; [contactez-nous](mailto:support@befailproof.ai) et nous l'adapterons. +Un agent qui ne s'exécute dans **aucun** des douze harnais est instrumenté directement via le [SDK Python](/fr/reference/custom-agents). Il s'agit d'un contrat différent, qu'il convient d'énoncer clairement : le SDK fournit le traçage, les sessions, les évaluations et les audits — **il n'applique pas de politiques par lui-même.** Pour bloquer une action non sécurisée avant son exécution, un hook d'application est nécessaire à la frontière des outils de votre environnement d'exécution ; [contactez-nous](mailto:support@befailproof.ai) et nous vous proposerons un mapping adapté. -| Harnais | Portées de hook supportées | +| Harnais | Portées de hooks prises en charge | | --- | --- | -| Claude Code | Utilisateur, projet, local | -| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | Utilisateur, projet | -| Factory Droid, Devin CLI, Antigravity CLI, Goose | Utilisateur, projet | -| Hermes, OpenClaw | Utilisateur | +| Claude Code | User, project, local | +| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | User, project | +| Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | +| Hermes, OpenClaw | User | -Chaque intégration normalise ses noms d'événements de hook natifs, ses noms d'outils et ses champs d'entrée d'outils avant l'exécution des politiques. Une politique ne peut agir que sur les événements exposés par le harnais ; testez le comportement en fin de tour et les instructions sur le harnais et la version exacts que vous déployez. +Chaque intégration normalise ses noms d'événements de hooks natifs, ses noms d'outils et ses champs d'entrée d'outils avant l'exécution des politiques. Une politique ne peut agir que sur les événements exposés par le harnais ; testez le comportement de fin de tour et d'instruction sur le harnais et la version exacts que vous déployez. -## Capacités d'application +## Capacité d'application -« Bloquer » signifie que le verdict renvoyé par l'adaptateur actuel est consommé par le harnais concerné. Le blocage post-outil peut remplacer le résultat présenté au modèle, mais ne peut pas annuler un effet secondaire d'outil déjà survenu. +« Bloquer » signifie que le verdict retourné par l'adaptateur courant est consommé par le harnais désigné. Le blocage post-outil peut remplacer le résultat présenté au modèle, mais ne peut pas annuler un effet de bord d'outil déjà survenu. -| Harnais | Événements de blocage vérifiés | Observations ou mises en garde sur le non-blocage | +| Harnais | Événements de blocage vérifiés | Observations ou réserves de non-blocage | | --- | --- | --- | | Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, et plusieurs événements de tâche/configuration | `PostToolUse`, le cycle de vie de session, les notifications et les événements post-échec sont observationnels. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Le blocage post-outil remplace le résultat après exécution ; les événements de démarrage de session et de compaction sont observationnels dans l'adaptateur actuel. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Le blocage post-outil remplace le résultat après exécution ; les événements de session et de notification sont observationnels. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Le blocage post-outil remplace le résultat après l'exécution ; les événements de démarrage de session et de compactage sont observationnels dans l'adaptateur actuel. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Le blocage post-outil remplace le résultat après l'exécution ; les événements de session et de notification sont observationnels. | | Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` et les événements de session sont observationnels. | -| OpenCode | `PreToolUse` | Les événements post-outil et de cycle de vie sont observationnels ; la gestion actuelle des arrêts est une instruction pour un tour ultérieur plutôt qu'une vérification garantie. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Les événements post-outil et de cycle de vie sont observationnels ; l'instruction d'arrêt s'applique à un tour ultérieur. | -| Hermes | `PreToolUse` | Les verdicts post-outil, de session et d'arrêt de sous-agent ne sont pas des verrous. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Les événements post-outil, de session, d'arrêt de sous-agent et de compaction sont observationnels. | +| OpenCode | `PreToolUse` | Les événements post-outil et de cycle de vie sont observationnels ; la gestion actuelle de l'arrêt est une orientation pour un tour ultérieur plutôt qu'un verrou vérifié. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Les événements post-outil et de cycle de vie sont observationnels ; l'orientation d'arrêt s'applique à un tour ultérieur. | +| Hermes | `PreToolUse` | Un plugin natif délivre `instruct()` comme une interruption unique et visible du modèle avant d'autoriser une itération API ultérieure. Les verdicts post-outil, de session et d'arrêt de sous-agent ne sont pas des verrous. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Les événements post-outil, de session, d'arrêt de sous-agent et de compactage sont observationnels. | | Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Les verdicts post-outil et d'arrêt de sous-agent sont observationnels. | | Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` conditionnel | Les hooks de permission ne s'exécutent pas dans tous les modes de permission ; les événements post-outil et de session sont observationnels. | -| Antigravity CLI | `PreToolUse`, `Stop` | Les verdicts d'invite utilisateur et post-outil sont observationnels ; des instructions d'invite peuvent néanmoins être injectées. | -| Goose | `PreToolUse` | Les événements d'invite utilisateur, post-outil et de session sont observationnels. Un hook d'arrêt natif bloquant existe en amont mais n'est pas installé par l'adaptateur actuel. | +| Antigravity CLI | `PreToolUse`, `Stop` | Les verdicts de prompt utilisateur et post-outil sont observationnels ; les instructions de prompt peuvent toujours être injectées. | +| Goose | `PreToolUse` | Les événements de prompt utilisateur, post-outil et de session sont observationnels. Un hook d'arrêt bloquant natif existe en amont mais n'est pas installé par l'adaptateur actuel. | -Les capacités dépendent de la version. Effectuez de nouveaux tests après la mise à jour d'un CLI d'agent, notamment lorsqu'une politique s'appuie sur le comportement d'invite, d'arrêt, de permission ou post-outil plutôt que sur la vérification pré-outil habituelle. +Les capacités dépendent de la version. Effectuez de nouveaux tests après la mise à jour d'un CLI d'agent, notamment lorsqu'une politique repose sur le comportement des prompts, des arrêts, des permissions ou des événements post-outil plutôt que sur le verrou pré-outil commun. -## Installer les hooks de capture et de politique +### Plugin natif Hermes + +Hermes est intégré via un plugin natif local au profil plutôt que via une commande shell. L'installation copie le plugin dans chaque profil Hermes par défaut et nommé, l'active dans le `config.yaml` de ce profil, et migre uniquement les entrées de hooks shell FailproofAI legacy. Cela évite la création d'un processus à chaque hook et permet à `instruct()` d'atteindre le modèle via le résultat d'outil bloqué natif de Hermes. + +La première instruction correspondante bloque l'appel en attente. La même requête API reste bloquée ; une itération ultérieure du modèle peut effectuer une nouvelle tentative. Un registre persistant, limité au profil, et un plafond par tour empêchent qu'une instruction consultative ne devienne une boucle sans fin. `deny()` reste un blocage strict. Exécutez `failproofai config --status` pour détecter un profil désactivé, incomplet, dupliqué ou nouvellement non configuré. + +## Installer la capture et les hooks de politique - 1. Ouvrez **Administration → Clés** et créez une clé avec `events:add` et `policies:pull`, nommée d'après la machine ou l'environnement. + 1. Ouvrez **Administration → Clés** et créez une clé avec les permissions `events:add` et `policies:pull`, nommée selon la machine ou l'environnement. 2. Sur la machine cible, connectez le CLI local avec la clé affichée et installez les hooks du harnais. 3. Démarrez une nouvelle session d'agent, puis confirmez ses événements de hook et de session sous **Observer → Événements**. - 4. Ouvrez **Observer → politique** pour la même plage horaire et confirmez qu'une décision de politique est attribuée à la machine. + 4. Ouvrez **Observer → politique** pour la même fenêtre temporelle et confirmez qu'une décision de politique est attribuée à la machine. - La connexion démarre avec une clé machine. Vérifiez qu'elle inclut les permissions d'ingestion et de livraison de politique avant de copier son secret. + La connexion commence avec une clé machine. Vérifiez qu'elle inclut à la fois les permissions d'ingestion et de livraison de politiques avant de copier son secret. - ![Le panneau de création de clé API permettant d'accorder les permissions d'ingestion d'événements et de livraison de politique.](/images/dashboard/key-create.png) + ![Le panneau de création de clé API utilisé pour accorder les permissions d'ingestion d'événements et de livraison de politiques.](/images/dashboard/key-create.png) - Après l'installation des hooks, le flux d'événements devrait afficher de nouveaux événements provenant de la machine et de l'environnement connectés. + Après l'installation des hooks, le flux Événements devrait afficher de nouveaux événements provenant de la machine et de l'environnement que vous avez connectés. - ![Le flux d'événements en direct permettant de confirmer qu'un harnais nouvellement installé envoie bien des données.](/images/dashboard/events-stream.png) + ![Le flux Événements en direct utilisé pour confirmer qu'un harnais nouvellement installé envoie des données.](/images/dashboard/events-stream.png) - Enfin, vérifiez que les décisions de politique sont attribuées à la même machine. Cela confirme que le harnais signale bien l'activité de politique ainsi que les événements de trace. + Enfin, vérifiez que les décisions de politique sont attribuées à la même machine. Cela confirme que le harnais signale bien l'activité des politiques ainsi que les événements de trace. - ![La page Politique permettant de vérifier les décisions de politique d'un harnais nouvellement connecté.](/images/dashboard/policy-observe.png) + ![La page Politique utilisée pour vérifier les décisions de politique d'un harnais nouvellement connecté.](/images/dashboard/policy-observe.png) - Lisez la clé machine dans le shell. `read -s` la saisit via une invite qui n'affiche pas la saisie, de sorte qu'elle n'apparaît jamais dans une commande ni dans l'historique du shell : + Lisez la clé machine dans le shell. `read -s` la demande via une invite qui n'affiche pas la saisie, de sorte qu'elle n'apparaît jamais dans une commande ni dans l'historique du shell : ```bash read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - Configurez ensuite la machine — cette opération câble les hooks pour chaque harnais détecté, installe le daemon et se connecte au Cloud : + Configurez ensuite la machine — cela câble les hooks pour chaque harnais détecté, installe le démon et se connecte au Cloud : ```bash failproofai config failproofai policies add FailproofAI/policies ``` - La configuration n'active aucune politique par elle-même, c'est à cela que sert la seconde commande. + La configuration n'active aucune politique par elle-même ; c'est l'objet de la deuxième commande. - Ou ciblez des harnais nommés et une portée de configuration : + Vous pouvez également cibler des harnais nommés et une portée de configuration : ```bash failproofai policies --install \ @@ -88,7 +94,7 @@ Les capacités dépendent de la version. Effectuez de nouveaux tests après la m --scope user ``` - La portée projet conserve la configuration des hooks avec un dépôt. La portée utilisateur couvre le travail sur plusieurs dépôts. Claude Code supporte également la portée locale ; la prise en charge varie selon le harnais et le CLI rejette les combinaisons non supportées. + La portée projet conserve la configuration des hooks avec un dépôt. La portée utilisateur couvre le travail sur plusieurs dépôts. Claude Code prend également en charge la portée locale ; la prise en charge varie selon le harnais et le CLI rejette les combinaisons non prises en charge. Vérifiez la machine et ses événements : @@ -100,16 +106,16 @@ Les capacités dépendent de la version. Effectuez de nouveaux tests après la m -## Ajouter un chemin de session non défini par défaut +## Ajouter un chemin de session non par défaut Les chemins supplémentaires sont enregistrés sur la machine, et non dans le Cloud. Après en avoir ajouté un, ouvrez **Observer → Sessions**, filtrez sur l'environnement de la machine et confirmez que les sessions issues du nouveau chemin apparaissent. Ouvrez une session et vérifiez l'agent, le harnais et les horodatages des événements avant de vous y fier dans un audit. - ![La liste des sessions filtrée sur l'environnement recevant des données du chemin de capture supplémentaire.](/images/dashboard/sessions-list.png) + ![La liste des sessions filtrée sur l'environnement recevant les données du chemin de capture supplémentaire.](/images/dashboard/sessions-list.png) - Ajoutez un chemin avec un libellé optionnel, puis inspectez les chemins configurés : + Ajoutez un chemin avec un label optionnel, puis inspectez les chemins configurés : ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -123,5 +129,5 @@ Les capacités dépendent de la version. Effectuez de nouveaux tests après la m - Exécutez une nouvelle session après l'installation. Vérifiez à la fois le flux d'événements en direct et une décision de politique effective avant d'étendre le déploiement. + Exécutez une nouvelle session après l'installation. Vérifiez à la fois le flux d'événements en direct et une décision de politique effective avant d'élargir le déploiement. \ No newline at end of file diff --git a/docs/he/reference/harnesses.mdx b/docs/he/reference/harnesses.mdx index 3adcc949..5bd3fbc3 100644 --- a/docs/he/reference/harnesses.mdx +++ b/docs/he/reference/harnesses.mdx @@ -1,86 +1,92 @@ --- -title: "מנגנוני סוכנים" -description: "תפסו הפעלות ואכפו מדיניות בכל 12 מנגנונים סוכנים נתמכים." +title: "מנגנוני אג'נט" +description: "תפסו הפעלות והטילו מדיניות על כל 12 מנגנוני אג'נט תומכים." icon: "plug-zap" --- -מנגנון הוא כל דבר שהסוכן שלך בעצם רץ בתוכו. Failproof AI תומך בשנים עשר מהם, בשתי קטגוריות: +מנגנון הוא כל סביבה שבה אג'נט שלך למעשה רץ. Failproof AI תומך בשנים עשר מהם, בשתי קטגוריות: -- **CLI קידוד** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **שערי צ'אט ועוזר** (2) — Hermes (Slack, Telegram, cron), OpenClaw (עוזר בעצמאות) +- **CLI-ים לקידוד** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose +- **שערי צ'אט והפניות** (2) — Hermes (Slack, Telegram, cron), OpenClaw (עוזר עצמי-מארח) -אותן מדיניות ואותו היסטוריית הפעלה חלים בכל מנגנון שהסוכן רץ בו. שכבת מתאם אחת ממפה את שמות האירוע, שמות הכלים ושדות קלט הכלים המקוריים של כל מנגנון ל-29 אירועים קנוניים לפני שתי מדיניות רצה. +אותה מדיניות ואותו היסטוריון הפעלות חלים בכל מנגנון שבו אג'נט רץ. שכבת מתאם אחת ממפה את שמות האירועים המקוריים של כל מנגנון, שמות הכלים, ושדות קלט כלים ל-29 אירועים קנוניים לפני שמדיניות כלשהי בוצעת. -סוכן שרץ ב**כלום** מבין השנים עשר מעוצבים ישירות עם [SDK Python](/he/reference/custom-agents). זה חוזה שונה, וכדאי להצהיר זאת בבירור: ה-SDK מספק עקיבה, הפעלות, הערכות ואודיטים — **הוא לא אוכף מדיניות בעצמו.** חסימת פעולה לא בטוחה לפני ההוצאה לפועל דורשת hook אכיפה בגבול הכלים של זמן הריצה שלך; [צור קשר איתנו](mailto:support@befailproof.ai) והנו נמפה זאת. +אג'נט שרץ ב**אף אחד** מחמשת עשר המנגנונים מכויל ישירות עם [Python SDK](/he/reference/custom-agents). זה חוזה שונה, וכדאי להציג זאת בבירור: ה-SDK מעניק תיקיעת מעקב, הפעלות, הערכות וביקורות — **הוא לא אוכף מדיניות בעצמו.** חסימת פעולה לא בטוחה לפני שהיא בוצעת דורשת hook אכיפה בגבול הכלי של הרנטיים שלך; [צור קשר איתנו](mailto:support@befailproof.ai) ואנחנו נממפה זאת. -| מנגנון | היקפי hook נתמכים | +| מנגנון | טווחי hook נתמכים | | --- | --- | | Claude Code | משתמש, פרויקט, מקומי | | Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | משתמש, פרויקט | | Factory Droid, Devin CLI, Antigravity CLI, Goose | משתמש, פרויקט | | Hermes, OpenClaw | משתמש | -כל אינטגרציה מנרמלת את שמות אירוע hook המקוריים שלה, שמות כלים ושדות קלט כלים לפני שמדיניות רצה. מדיניות יכולה לפעול רק על אירועים שהמנגנון חושף; בדוק התנהגות סוף תור והוראה בדיוק על המנגנון והגרסה שבהם תפרוש. +כל אינטגרציה מנרמלת את שמות אירועי ה-hook המקוריים שלה, שמות כלים, ושדות קלט כלים לפני שמדיניות רצה. מדיניות יכולה לפעול רק על אירועים שהמנגנון חושף; בדקו התנהגות סיום תור והנחיה על המנגנון והגרסה הדקים שאתם משתמשים בהם. ## יכולת אכיפה -"חסום" פירושו שהפסק ההחזר של ההתאם הנוכחי נצרך על ידי המנגנון בשם. חסימה לאחר כלים עשויה להחליף את התוצאה המוצגת למודל אך לא יכולה לבטל אפקט צד של כלים שכבר קרה. +"חסום" פירושו שהקביעה שהוחזרה של המתאם הנוכחי נצרכת על ידי המנגנון שנקרא. חסימה אחרי כלי עשויה להחליף את התוצאה המוצגת למודל אך לא יכולה לבטל השפעה צד של כלי שכבר התרחשה. -| מנגנון | אירועי חסימה מאומתים | חסמים רק-ראיה או לא-חוסמים | +| מנגנון | אירועי חסימה מאומתים | הערות ملاحظة בלבד או לא ממזערות | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, וכמה אירועי משימה/קונפיגורציה | `PostToolUse`, מחזור חיים הפעלה, התראות, ואירועי לאחר כשל הם תצפיתיים. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | חסימה לאחר כלים מחליפה את התוצאה לאחר הביצוע; התחלת הפעלה ואירועי קומפקט הם תצפיתיים במתאם הנוכחי. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | חסימה לאחר כלים מחליפה את התוצאה לאחר הביצוע; אירועי הפעלה והתראה הם תצפיתיים. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` ואירועי הפעלה הם תצפיתיים. | -| OpenCode | `PreToolUse` | אירועי לאחר כלים ומחזור חיים הם תצפיתיים; ניהול עצירה נוכחי הוא הנחיה לתור מאוחר יותר ולא שער מאומת. | -| Pi | `PreToolUse`, `UserPromptSubmit` | אירועי לאחר כלים ומחזור חיים הם תצפיתיים; הנחיית עצירה חלה על תור מאוחר יותר. | -| Hermes | `PreToolUse` | אירועי לאחר כלים, הפעלה, וסוכן-עצירה משנית אינם שערים. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | אירועי לאחר כלים, הפעלה, סוכן-עצירה משנית, וקומפקציה הם תצפיתיים. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | אירועי לאחר כלים וסוכן-עצירה משנית הם תצפיתיים. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` מותנה | hook הרשאה לא רצה בכל מצב הרשאה; אירועי לאחר כלים והפעלה הם תצפיתיים. | -| Antigravity CLI | `PreToolUse`, `Stop` | אירועי הנחיה משתמש ולאחר כלים הם תצפיתיים; הנחיות הנחיה עדיין יכולות להיות מוזרקות. | -| Goose | `PreToolUse` | אירועי הנחיה משתמש, לאחר כלים, והפעלה הם תצפיתיים. hook עצירה חסימה מקור קיים אך לא מותקן על ידי המתאם הנוכחי. | - -יכולות רגישות לגרסה. בדוק מחדש לאחר שדרוג סוכן CLI, במיוחד כאשר מדיניות מסתמכת על התנהגות הנחיה, עצירה, הרשאה, או לאחר כלים ולא על שער הקדם-כלים הנפוץ. - -## התקן hook לכידת ומדיניות +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, ואירועי משימה/תצורה נוספים | `PostToolUse`, מחזור חיים הפעלות, התראות, ואירועי לאחר כשל הם תצפיתיים. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | חסימה אחרי כלי מחליפה את התוצאה אחרי ביצוע; אירועי התחלת הפעלה וקומפקט הם תצפיתיים במתאם הנוכחי. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | חסימה אחרי כלי מחליפה את התוצאה אחרי ביצוע; אירועי הפעלות והתראות הם תצפיתיים. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` ואירועי הפעלות הם תצפיתיים. | +| OpenCode | `PreToolUse` | אירועי אחרי כלי ומחזור חיים הם תצפיתיים; טיפול עצירה נוכחי הוא הנחיה לתור מאוחר יותר ולא שער מאומת. | +| Pi | `PreToolUse`, `UserPromptSubmit` | אירועי אחרי כלי ומחזור חיים הם תצפיתיים; הנחיית עצירה חלה על תור מאוחר יותר. | +| Hermes | `PreToolUse` | פלג-אין מקומי מעניק `instruct()` כהפסקה אחת מוגבלת וגלויה-מודל לפני שמאפשרים איטרציית API מאוחרת יותר. קביעות אחרי כלי, הפעלות וחסימת תת-אג'נט אינן שערים. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | אירועים אחרי כלי, הפעלות, עצירה תת-אג'נט, וקומפקט הם תצפיתיים. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | קביעות אחרי כלי וחסימת תת-אג'נט הן תצפיתיות. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` מותנה | hook-ות הרשאה לא רצות בכל מצב הרשאה; אירועים אחרי כלי והפעלות הם תצפיתיים. | +| Antigravity CLI | `PreToolUse`, `Stop` | קביעות הנחיה-משתמש ואחרי כלי הן תצפיתיות; הנחיות הנחיה יכולות עדיין להיות הוזנו. | +| Goose | `PreToolUse` | אירועי הנחיה-משתמש, אחרי כלי והפעלות הם תצפיתיים. hook עצירה חסימה מקומי קיים במפעל אך אינו מותקן על ידי המתאם הנוכחי. | + +יכולות רגישות לגרסה. בדקו מחדש לאחר שדרוג CLI של אג'נט, במיוחד כאשר מדיניות מסתמכת על התנהגות הנחיה, עצירה, הרשאה או אחרי כלי במקום שער הנחיה-טרום משותף. + +### Hermes native plugin + +Hermes משולב דרך פלג-אין מקומי מקומי-פרופיל במקום פקודת shell. ההתקנה מעתיקה את הפלג-אין לכל פרופיל Hermes ברירת מחדל ובשם, מאפשרת אותו בקובץ `config.yaml` של אותו פרופיל, ומהגרת רק ערכי hook shell FailproofAI מסוגיים. זה מונע ייצור תהליך בכל hook ומאפשר `instruct()` להגיע למודל דרך תוצאת כלי חסום מקומית של Hermes. + +ההנחיה ההתאמה הראשונה חוסמת את הקריאה הממתינה. אותו בקשת API נשארת חסומה; איטרציית מודל מאוחרת יותר עשויה לנסות שוב. קומץ קבע בטווח פרופיל וכובע לכל תור מונעים הנחיה יעוצה מלהיות לולאה בלתי מוגבלת. `deny()` נשאר חסימה קשה. הפעילו `failproofai config --status` כדי לגלות פרופיל מנוטרל, לא שלם, משוכפל או שנוצר מחדש. + +## התקן capture וhook-ות מדיניות - - 1. פתח **ניהול → מפתחות** וצור מפתח עם `events:add` ו`policies:pull`, ובשם למכונה או סביבה. - 2. במכונת היעד, התחבר ל-CLI המקומי עם המפתח המוצג והתקן את hook המנגנון. - 3. התחל הפעלת סוכן חדשה, ואז אשר את hook שלה ואירועי הפעלה תחת **צפייה → אירועים**. - 4. פתח **צפייה → מדיניות** לאותו חלון זמן ואשר שהחלטת מדיניות מיוחסת למכונה. + + 1. פתחו **Administration → Keys** וּיצרו מפתח עם `events:add` ו-`policies:pull`, בשם עבור המכונה או הסביבה. + 2. במכונת היעד, חברו את ה-CLI המקומי עם המפתח המוצג והתקינו את hook-ות המנגנון. + 3. התחילו הפעלה חדשה של אג'נט, ואז אשרו את ה-hook שלו ואירועי הפעלות תחת **Observe → Events**. + 4. פתחו **Observe → policy** לאותו חלון זמן ואשרו שקביעת מדיניות מיוחסת למכונה. - החיבור מתחיל עם מפתח מכונה. אשר שהוא כולל הן הרשאות ספיגה והן הרשאות עמידת מדיניות לפני העתקת הסוד שלו. + החיבור מתחיל עם מפתח מכונה. אשרו שהוא כולל הן הרשאות ספיגה והן הרשאות אספקת מדיניות לפני העתקת הסוד שלו. - ![ספריית מפתח API החדשה המשמשת להעניית הרשאות ספיגת אירוע והעמדת מדיניות.](/images/dashboard/key-create.png) + ![מגירת מפתח API חדשה המשמשת להענקת הרשאות ספיגה אירוע והעברת מדיניות.](/images/dashboard/key-create.png) - לאחר התקנת hook, סטרימ האירועים צריך להציג אירועים חדשים מהמכונה והסביבה שבהן התחברת. + לאחר התקנת ה-hook-ות, זרימת האירועים צריכה להראות אירועים חדשים מהמכונה והסביבה שחברתם. - ![סטרימ האירועים החי המשמש לאישור מנגנון שהותקן לאחרונה דיווח.](/images/dashboard/events-stream.png) + ![זרימת אירועים חיה המשמשת לאישור שמנגנון שהותקן לאחרונה מדווח.](/images/dashboard/events-stream.png) - לבסוף, ודא שהחלטות מדיניות מיוחסות לאותה מכונה. זה מאשר שהמנגנון דיווח פעילות מדיניות כמו גם אירועי עקיבה. + לבסוף, אימתו שקביעות מדיניות מיוחסות לאותה מכונה. זה מאשר שהמנגנון מדווח פעילות מדיניות כמו גם אירועי עקבות. - ![דף המדיניות המשמש לאימות החלטות מדיניות מנגנון המחובר לאחרונה.](/images/dashboard/policy-observe.png) + ![דף מדיניות המשמש לאימות קביעות מדיניות מחיבור חדש.](/images/dashboard/policy-observe.png) - קרא את מפתח המכונה ל-shell. `read -s` מקבל אותו בהנחיה שלא משדרת, כך שהוא לא מופיע בפקודה או בהיסטוריית shell: + קרא את מפתח המכונה לתוך ה-shell. `read -s` משיגה אותו בהנחיה שלא משקפת, כך שהוא לא מופיע בפקודה או בהיסטוריון shell: ```bash read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - ואז הגדר את המכונה — זה מחוט hook לכל מנגנון שזוהה, מתקין את daemon, ומתחבר ל-Cloud: + ואז הגדרו את המכונה — זה חוטים hook-ות לכל מנגנון שנוגד, מתקין את ה-daemon, וקורא קשר לעננן: ```bash failproofai config failproofai policies add FailproofAI/policies ``` - התקנה לא מאפשרת מדיניות בעצמה, וזה מה שהפקודה השנייה שלו. + ההגדרה אינה מאפשרת מדיניות בעצמה, שזו הסיבה לפקודה השנייה. - או לכוונן מנגנונים בשם ויקף קונפיגורציה: + או לתמרן מנגנונים בשם וטווח תצורה: ```bash failproofai policies --install \ @@ -88,9 +94,9 @@ icon: "plug-zap" --scope user ``` - היקף פרויקט שומר את קונפיגורציית hook עם מאגר. היקף משתמש מכסה עבודה על פני מאגרים. Claude Code תומך גם בהיקף מקומי; התמיכה משתנה לפי מנגנון ו-CLI דוחה שילובים לא נתמכים. + טווח פרויקט שומר תצורת hook עם מאגר. טווח משתמש מכסה עבודה על פני מאגרים. Claude Code תומך גם בטווח מקומי; התמיכה משתנה לפי מנגנון וה-CLI דוחה שילובים לא נתמכים. - אמת את המכונה ואת האירועים שלה: + אימתו את המכונה ואת האירועים שלה: ```bash failproofai config --status @@ -100,13 +106,13 @@ icon: "plug-zap" -## הוסף נתיב הפעלה שאינו ברירת מחדל +## הוסף נתיב הפעלות לא-ברירת מחדל - - נתיבים נוספים רשומים במכונה, לא ב-Cloud. לאחר הוספת אחד, פתח **צפייה → הפעלות**, סנן לסביבת המכונה, והשתכנע שהפעלות מהנתיב החדש מופיעים. פתח הפעלה ובדוק את הסוכן, המנגנון, וחותמות זמן האירוע לפני הסתמכות עליו בביקורת. + + נתיבים נוספים רשומים במכונה, לא בעננן. לאחר הוספת אחד, פתחו **Observe → Sessions**, סננו לסביבת המכונה, והאשרו שהפעלות מהנתיב החדש מופיעות. פתחו הפעלה ובדקו את האג'נט, המנגנון וחותמות זמן אירוע לפני שתסתמכו עליו בביקורת. - ![רשימת ההפעלות מסוננת לסביבה שמקבלת נתונים מנתיב הכידה נוסף.](/images/dashboard/sessions-list.png) + ![רשימת הפעלות סוננת לסביבה המקבלת נתונים מנתיב הלכידה הנוסף.](/images/dashboard/sessions-list.png) הוסף נתיב עם תווית אופציונלית, ואז בדוק את הנתיבים המוגדרים: @@ -123,5 +129,5 @@ icon: "plug-zap" - הרץ הפעלת סוכן חדשה אחת לאחר התקנה. אמת גם את סטרימ האירוע החי וגם החלטת מדיניות בפועל לפני הרחבת ההנדסת. + הפעילו הפעלה חדשה אחת לאחר ההתקנה. אימתו גם את זרימת האירוע החיה וגם קביעת מדיניות בפועל לפני הרחבת ההטלה. \ No newline at end of file diff --git a/docs/hi/reference/harnesses.mdx b/docs/hi/reference/harnesses.mdx index 7639945c..8daf7716 100644 --- a/docs/hi/reference/harnesses.mdx +++ b/docs/hi/reference/harnesses.mdx @@ -1,17 +1,17 @@ --- title: "एजेंट हार्नेस" -description: "सभी 12 समर्थित एजेंट हार्नेस में सत्र कैप्चर करें और नीतियों को लागू करें।" +description: "सभी 12 समर्थित एजेंट हार्नेस में सेशन कैप्चर करें और नीतियां लागू करें।" icon: "plug-zap" --- -एक हार्नेस वह है जिसके अंदर आपका एजेंट वास्तव में चलता है। Failproof AI इन्हें दो वर्गों में से बारह का समर्थन करता है: +एक हार्नेस वह है जिसमें आपका एजेंट वास्तव में चलता है। Failproof AI इनमें से बारह को समर्थन करता है, दो श्रेणियों में: - **कोडिंग CLIs** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **चैट और असिस्टेंट गेटवे** (2) — Hermes (Slack, Telegram, cron), OpenClaw (self-hosted assistant) +- **चैट और असिस्टेंट गेटवे** (2) — Hermes (Slack, Telegram, cron), OpenClaw (स्व-होस्टेड असिस्टेंट) -चाहे एजेंट किसी भी हार्नेस में चले, समान नीतियां और समान सत्र इतिहास लागू होता है। एक एडेप्टर परत प्रत्येक हार्नेस के मूल इवेंट नामों, टूल नामों, और टूल-इनपुट फील्ड को 29 विहित इवेंट पर मैप करती है, इससे पहले कि कोई नीति चले। +एक ही नीतियां और एक ही सेशन हिस्ट्री लागू होती हैं चाहे एजेंट किसी भी हार्नेस में चले। एक एडेप्टर लेयर प्रत्येक हार्नेस के नेटिव ईवेंट नामों, टूल नामों और टूल-इनपुट फील्ड्स को 29 कैनोनिकल ईवेंट्स में मैप करता है, इससे पहले कि कोई नीति चले। -एक एजेंट जो बारहों में से **किसी में नहीं** चलता है, वह [Python SDK](/hi/reference/custom-agents) के साथ सीधे इंस्ट्रूमेंट किया जाता है। यह एक अलग अनुबंध है, और स्पष्ट रूप से बताने के लायक है: SDK ट्रेसिंग, सत्र, मूल्यांकन और ऑडिट प्रदान करता है — **यह अपने आप पर नीतियों को लागू नहीं करता।** निष्पादन से पहले एक असुरक्षित कार्रवाई को अवरुद्ध करने के लिए आपके रनटाइम के टूल सीमा पर एक प्रवर्तन हुक की आवश्यकता है; [हमसे संपर्क करें](mailto:support@befailproof.ai) और हम इसे मैप करेंगे। +एक एजेंट जो बारह में से **किसी में भी** नहीं चलता, वह सीधे [Python SDK](/hi/reference/custom-agents) के साथ इंस्ट्रुमेंटेड होता है। यह एक अलग कॉन्ट्रैक्ट है, और स्पष्ट रूप से कहा जाना चाहिए: SDK ट्रेसिंग, सेशन, मूल्यांकन और ऑडिट प्रदान करता है — **यह अपने आप में नीतियां लागू नहीं करता।** किसी असुरक्षित कार्य को निष्पादन से पहले ब्लॉक करने के लिए आपके रनटाइम की टूल सीमा पर एक एनफोर्समेंट हुक की जरूरत है; [हमसे संपर्क करें](mailto:support@befailproof.ai) और हम इसे मैप करेंगे। | हार्नेस | समर्थित हुक स्कोप | | --- | --- | @@ -20,67 +20,73 @@ icon: "plug-zap" | Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | | Hermes, OpenClaw | User | -प्रत्येक इंटीग्रेशन नीतियों के चलने से पहले अपने मूल हुक इवेंट नामों, टूल नामों, और टूल-इनपुट फील्ड को सामान्य करता है। एक नीति केवल उन इवेंट पर कार्य कर सकती है जो हार्नेस उजागर करता है; बिल्कुल उसी हार्नेस और संस्करण पर टर्न के अंत और निर्देश व्यवहार का परीक्षण करें जो आप तैनात करते हैं। +प्रत्येक इंटीग्रेशन अपने नेटिव हुक ईवेंट नामों, टूल नामों और टूल-इनपुट फील्ड्स को सामान्यीकृत करता है इससे पहले कि नीतियां चलें। एक नीति केवल उन ईवेंट्स पर कार्य कर सकती है जो हार्नेस उजागर करता है; आप जो सटीक हार्नेस और संस्करण तैनात करते हैं उस पर टर्न-एंड और निर्देश व्यवहार का परीक्षण करें। -## प्रवर्तन क्षमता +## एनफोर्समेंट क्षमता -"ब्लॉक" का मतलब है कि वर्तमान एडेप्टर की प्राप्त राय नामित हार्नेस द्वारा उपभोग की जाती है। पोस्ट-टूल ब्लॉकिंग मॉडल को दिखाया गया परिणाम प्रतिस्थापित कर सकता है लेकिन एक टूल साइड इफेक्ट को पूर्ववत नहीं कर सकता जो पहले से हो चुका है। +"ब्लॉक" का मतलब है कि वर्तमान एडेप्टर की रिटर्न की गई निर्णय का नाम दिए गए हार्नेस द्वारा उपभोग किया जाता है। पोस्ट-टूल ब्लॉकिंग मॉडल को दिखाए गए परिणाम को बदल सकती है लेकिन एक टूल साइड इफेक्ट को पूर्ववत नहीं कर सकती जो पहले से ही हुई हो। -| हार्नेस | सत्यापित ब्लॉकिंग इवेंट | केवल-अवलोकन या गैर-ब्लॉकिंग चेतावनियां | +| हार्नेस | सत्यापित ब्लॉकिंग ईवेंट्स | केवल-अवलोकन या गैर-ब्लॉकिंग सावधानियां | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, और कई टास्क/कॉन्फ़िग इवेंट | `PostToolUse`, सत्र जीवनचक्र, सूचनाएं, और पोस्ट-विफलता इवेंट अवलोकनात्मक हैं। | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | पोस्ट-टूल ब्लॉकिंग निष्पादन के बाद परिणाम को प्रतिस्थापित करता है; सत्र-शुरुआत और कॉम्पैक्ट इवेंट वर्तमान एडेप्टर में अवलोकनात्मक हैं। | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | पोस्ट-टूल ब्लॉकिंग निष्पादन के बाद परिणाम को प्रतिस्थापित करता है; सत्र और सूचना इवेंट अवलोकनात्मक हैं। | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` और सत्र इवेंट अवलोकनात्मक हैं। | -| OpenCode | `PreToolUse` | पोस्ट-टूल और जीवनचक्र इवेंट अवलोकनात्मक हैं; वर्तमान स्टॉप हैंडलिंग एक सत्यापित गेट के बजाय बाद की बारी के लिए मार्गदर्शन है। | -| Pi | `PreToolUse`, `UserPromptSubmit` | पोस्ट-टूल और जीवनचक्र इवेंट अवलोकनात्मक हैं; स्टॉप मार्गदर्शन बाद की बारी पर लागू होता है। | -| Hermes | `PreToolUse` | पोस्ट-टूल, सत्र, और subagent-stop राय गेट नहीं हैं। | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | पोस्ट-टूल, सत्र, subagent-stop, और कॉम्पैक्शन इवेंट अवलोकनात्मक हैं। | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | पोस्ट-टूल और subagent-stop राय अवलोकनात्मक हैं। | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, सशर्त `PermissionRequest` | अनुमति हुक हर अनुमति मोड में नहीं चलते; पोस्ट-टूल और सत्र इवेंट अवलोकनात्मक हैं। | -| Antigravity CLI | `PreToolUse`, `Stop` | उपयोगकर्ता-प्रॉम्प्ट और पोस्ट-टूल राय अवलोकनात्मक हैं; प्रॉम्प्ट निर्देश अभी भी इंजेक्ट किए जा सकते हैं। | -| Goose | `PreToolUse` | उपयोगकर्ता-प्रॉम्प्ट, पोस्ट-टूल, और सत्र इवेंट अवलोकनात्मक हैं। एक मूल ब्लॉकिंग स्टॉप हुक अपस्ट्रीम में मौजूद है लेकिन वर्तमान एडेप्टर द्वारा स्थापित नहीं है। | - -क्षमताएं संस्करण-संवेदनशील हैं। एक एजेंट CLI को अपग्रेड करने के बाद फिर से परीक्षण करें, विशेष रूप से जब कोई नीति सामान्य पूर्व-टूल गेट के बजाय प्रॉम्प्ट, स्टॉप, अनुमति, या पोस्ट-टूल व्यवहार पर निर्भर करती है। - -## कैप्चर और नीति हुक स्थापित करें +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, और कई कार्य/कॉन्फ़िग ईवेंट्स | `PostToolUse`, सेशन लाइफसाइकल, नोटिफिकेशन, और पोस्ट-विफलता ईवेंट्स अवलोकनात्मक हैं। | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | पोस्ट-टूल ब्लॉकिंग निष्पादन के बाद परिणाम को बदलती है; सेशन-स्टार्ट और कॉम्पैक्ट ईवेंट्स वर्तमान एडेप्टर में अवलोकनात्मक हैं। | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | पोस्ट-टूल ब्लॉकिंग निष्पादन के बाद परिणाम को बदलती है; सेशन और नोटिफिकेशन ईवेंट्स अवलोकनात्मक हैं। | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` और सेशन ईवेंट्स अवलोकनात्मक हैं। | +| OpenCode | `PreToolUse` | पोस्ट-टूल और लाइफसाइकल ईवेंट्स अवलोकनात्मक हैं; वर्तमान स्टॉप हैंडलिंग एक सत्यापित गेट के बजाय बाद के टर्न के लिए मार्गदर्शन है। | +| Pi | `PreToolUse`, `UserPromptSubmit` | पोस्ट-टूल और लाइफसाइकल ईवेंट्स अवलोकनात्मक हैं; स्टॉप मार्गदर्शन बाद के टर्न पर लागू होती है। | +| Hermes | `PreToolUse` | एक नेटिव प्लगइन `instruct()` को एक बंधित, मॉडल-दृश्यमान बाधा के रूप में प्रदान करता है इससे पहले कि एक बाद की API पुनरावृत्ति की अनुमति दें। पोस्ट-टूल, सेशन, और सबएजेंट-स्टॉप निर्णय गेट नहीं हैं। | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | पोस्ट-टूल, सेशन, सबएजेंट-स्टॉप, और कॉम्पैक्शन ईवेंट्स अवलोकनात्मक हैं। | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | पोस्ट-टूल और सबएजेंट-स्टॉप निर्णय अवलोकनात्मक हैं। | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, सशर्त `PermissionRequest` | अनुमति हुक हर अनुमति मोड में नहीं चलते; पोस्ट-टूल और सेशन ईवेंट्स अवलोकनात्मक हैं। | +| Antigravity CLI | `PreToolUse`, `Stop` | उपयोगकर्ता-प्रॉम्प्ट और पोस्ट-टूल निर्णय अवलोकनात्मक हैं; प्रॉम्प्ट निर्देश अभी भी इंजेक्ट किए जा सकते हैं। | +| Goose | `PreToolUse` | उपयोगकर्ता-प्रॉम्प्ट, पोस्ट-टूल, और सेशन ईवेंट्स अवलोकनात्मक हैं। एक नेटिव ब्लॉकिंग स्टॉप हुक अपस्ट्रीम मौजूद है लेकिन वर्तमान एडेप्टर द्वारा इंस्टॉल नहीं किया गया है। | + +क्षमताएं संस्करण-संवेदनशील हैं। एजेंट CLI को अपग्रेड करने के बाद फिर से परीक्षण करें, विशेषकर जब कोई नीति प्रॉम्प्ट, स्टॉप, अनुमति, या पोस्ट-टूल व्यवहार पर निर्भर हो, सामान्य पूर्व-टूल गेट के बजाय। + +### Hermes नेटिव प्लगइन + +Hermes को शेल कमांड के बजाय एक प्रोफाइल-स्थानीय नेटिव प्लगइन के माध्यम से एकीकृत किया गया है। स्थापना प्लगइन को हर डिफ़ॉल्ट और नामित Hermes प्रोफाइल में कॉपी करता है, इसे उस प्रोफाइल के `config.yaml` में सक्षम करता है, और केवल विरासत FailproofAI शेल-हुक प्रविष्टियों को माइग्रेट करता है। यह प्रत्येक हुक पर प्रक्रिया स्पॉन से बचता है और `instruct()` को Hermes के नेटिव ब्लॉक-टूल परिणाम के माध्यम से मॉडल तक पहुंचने देता है। + +पहला मिलान वाला निर्देश लंबित कॉल को ब्लॉक करता है। एक ही API अनुरोध ब्लॉक रहता है; एक बाद की मॉडल पुनरावृत्ति पुनः प्रयास कर सकती है। एक स्थायी, प्रोफाइल-स्कोप्ड लेजर और एक प्रति-टर्न कैप एक सलाह निर्देश को एक अंतहीन लूप बनने से रोकता है। `deny()` एक कठिन ब्लॉक रहता है। एक अक्षम, अपूर्ण, डुप्लिकेट, या नई अनकॉन्फ़िगर्ड प्रोफाइल का पता लगाने के लिए `failproofai config --status` चलाएं। + +## कैप्चर और नीति हुक इंस्टॉल करें - 1. **Administration → Keys** खोलें और `events:add` और `policies:pull` के साथ एक कुंजी बनाएं, मशीन या परिवेश के लिए नामित करें। - 2. लक्ष्य मशीन पर, स्थानीय CLI को प्रदर्शित कुंजी के साथ कनेक्ट करें और हार्नेस हुक स्थापित करें। - 3. एक नया एजेंट सत्र शुरू करें, फिर **Observe → Events** के अंतर्गत इसके हुक और सत्र इवेंट की पुष्टि करें। - 4. एक ही समय विंडो के लिए **Observe → policy** खोलें और पुष्टि करें कि एक नीति निर्णय मशीन को जिम्मेदार ठहराया गया है। + 1. **Administration → Keys** खोलें और `events:add` और `policies:pull` के साथ एक कुंजी बनाएं, मशीन या वातावरण के लिए नामित। + 2. लक्ष्य मशीन पर, प्रदर्शित कुंजी के साथ स्थानीय CLI को कनेक्ट करें और हार्नेस हुक इंस्टॉल करें। + 3. एक नया एजेंट सेशन शुरू करें, फिर **Observe → Events** के तहत इसके हुक और सेशन ईवेंट्स की पुष्टि करें। + 4. एक ही समय विंडो के लिए **Observe → policy** खोलें और पुष्टि करें कि एक नीति निर्णय मशीन को जिम्मेदार है। - कनेक्शन एक मशीन कुंजी के साथ शुरू होता है। पुष्टि करें कि इसमें इसके गुप्त को कॉपी करने से पहले इनजेशन और नीति-वितरण दोनों अनुमतियां शामिल हैं। + कनेक्शन एक मशीन कुंजी के साथ शुरू होता है। इससे पहले कि इसका गुप्त कॉपी करें, पुष्टि करें कि इसमें इनजेशन और नीति-डिलीवरी दोनों अनुमतियां शामिल हैं। - ![नई API कुंजी दराज जिसे इवेंट इनजेशन और नीति वितरण अनुमतियां प्रदान करने के लिए उपयोग किया जाता है।](/images/dashboard/key-create.png) + ![इवेंट इनजेशन और नीति डिलीवरी अनुमतियां देने के लिए उपयोग की जाने वाली नई API कुंजी ड्रॉयर।](/images/dashboard/key-create.png) - हुक स्थापित करने के बाद, Events स्ट्रीम को आप जो मशीन और परिवेश कनेक्ट करते हैं उससे नए इवेंट दिखाने चाहिए। + हुक इंस्टॉल करने के बाद, इवेंट्स स्ट्रीम को मशीन और वातावरण से नई ईवेंट्स दिखानी चाहिए जिससे आपने कनेक्ट किया है। - ![लाइव Events स्ट्रीम जिसका उपयोग एक नए स्थापित हार्नेस की रिपोर्टिंग की पुष्टि करने के लिए किया जाता है।](/images/dashboard/events-stream.png) + ![नई इंस्टॉल की गई हार्नेस की रिपोर्टिंग की पुष्टि करने के लिए उपयोग की जाने वाली लाइव इवेंट्स स्ट्रीम।](/images/dashboard/events-stream.png) - अंत में, पुष्टि करें कि नीति निर्णय उसी मशीन को जिम्मेदार ठहराए गए हैं। यह पुष्टि करता है कि हार्नेस नीति गतिविधि के साथ-साथ ट्रेस इवेंट की रिपोर्ट कर रहा है। + अंत में, सत्यापित करें कि नीति निर्णय एक ही मशीन को जिम्मेदार हैं। यह पुष्टि करता है कि हार्नेस ट्रेस ईवेंट्स के साथ-साथ नीति गतिविधि की रिपोर्ट कर रहा है। - ![नीति पृष्ठ जिसका उपयोग एक नए कनेक्ट किए गए हार्नेस से नीति निर्णयों को सत्यापित करने के लिए किया जाता है।](/images/dashboard/policy-observe.png) + ![नई कनेक्ट की गई हार्नेस से नीति निर्णयों को सत्यापित करने के लिए उपयोग किया जाने वाला नीति पृष्ठ।](/images/dashboard/policy-observe.png) - मशीन कुंजी को शेल में पढ़ें। `read -s` इसे एक प्रॉम्प्ट पर लेता है जो प्रतिध्वनि नहीं करता, इसलिए यह कभी एक कमांड में या शेल इतिहास में दिखाई नहीं देता: + मशीन कुंजी को शेल में पढ़ें। `read -s` इसे एक प्रॉम्प्ट पर लेता है जो ईको नहीं करता, इसलिए यह कभी कमांड में या शेल हिस्ट्री में नहीं दिखता: ```bash read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - फिर मशीन को सेट करें — यह हर पता लगाए गए हार्नेस के लिए हुक तारों, daemon स्थापित करता है, और Cloud से कनेक्ट करता है: + फिर मशीन को सेटअप करें — यह हर पाई गई हार्नेस के लिए हुक वायर करता है, डेमन इंस्टॉल करता है, और Cloud से कनेक्ट करता है: ```bash failproofai config failproofai policies add FailproofAI/policies ``` - सेटअप अपने आप पर कोई नीति सक्षम नहीं करता है, जो दूसरी कमांड के लिए है। + सेटअप अपने आप में कोई नीति सक्षम नहीं करता है, जो दूसरी कमांड के लिए है। - या नामित हार्नेस और एक कॉन्फ़िगरेशन स्कोप को लक्ष्य करें: + या नामित हार्नेस और एक कॉन्फ़िगरेशन स्कोप को लक्षित करें: ```bash failproofai policies --install \ @@ -90,7 +96,7 @@ icon: "plug-zap" प्रोजेक्ट स्कोप हुक कॉन्फ़िगरेशन को एक रिपॉजिटरी के साथ रखता है। उपयोगकर्ता स्कोप रिपॉजिटरी में काम को कवर करता है। Claude Code स्थानीय स्कोप को भी समर्थन करता है; समर्थन हार्नेस के अनुसार भिन्न होता है और CLI असमर्थित संयोजनों को अस्वीकार करता है। - मशीन और इसके इवेंट की पुष्टि करें: + मशीन और इसकी ईवेंट्स को सत्यापित करें: ```bash failproofai config --status @@ -100,16 +106,16 @@ icon: "plug-zap" -## गैर-डिफ़ॉल्ट सत्र पाथ जोड़ें +## एक गैर-डिफ़ॉल्ट सेशन पथ जोड़ें - अतिरिक्त पाथ मशीन पर पंजीकृत हैं, Cloud में नहीं। एक जोड़ने के बाद, **Observe → Sessions** खोलें, मशीन के परिवेश को फ़िल्टर करें, और पुष्टि करें कि नए पाथ से सत्र दिखाई देते हैं। एक ऑडिट में इस पर भरोसा करने से पहले एक सत्र खोलें और एजेंट, हार्नेस, और इवेंट टाइमस्टैम्प की जांच करें। + अतिरिक्त पथ मशीन पर पंजीकृत होते हैं, Cloud में नहीं। एक को जोड़ने के बाद, **Observe → Sessions** खोलें, मशीन के वातावरण को फ़िल्टर करें, और नई पथ से सेशन दिखाई देने की पुष्टि करें। एक सेशन खोलें और इसे ऑडिट में पूरी तरह भरोसे से पहले एजेंट, हार्नेस, और ईवेंट टाइमस्टैम्प जांचें। - ![अतिरिक्त कैप्चर पाथ से डेटा प्राप्त करने वाले परिवेश के लिए फ़िल्टर किए गए सत्र सूची।](/images/dashboard/sessions-list.png) + ![अतिरिक्त कैप्चर पथ से डेटा प्राप्त करने वाले पर्यावरण के लिए फ़िल्टर किया गया सेशन सूची।](/images/dashboard/sessions-list.png) - एक वैकल्पिक लेबल के साथ एक पाथ जोड़ें, फिर कॉन्फ़िगर किए गए पाथ को निरीक्षण करें: + एक वैकल्पिक लेबल के साथ एक पथ जोड़ें, फिर कॉन्फ़िगर किए गए पथों का निरीक्षण करें: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -118,10 +124,10 @@ icon: "plug-zap" failproofai backfill --since 7d ``` - `failproofai harness remove-path claude checkout` के साथ एक पाथ हटाएं। + `failproofai harness remove-path claude checkout` के साथ एक पथ हटाएं। - स्थापन के बाद एक नया सत्र चलाएं। रोलआउट का विस्तार करने से पहले लाइव इवेंट स्ट्रीम और एक वास्तविक नीति निर्णय दोनों की पुष्टि करें। + स्थापना के बाद एक नया सेशन चलाएं। विस्तार रोलआउट से पहले लाइव ईवेंट स्ट्रीम और एक वास्तविक नीति निर्णय दोनों को सत्यापित करें। \ No newline at end of file diff --git a/docs/it/reference/harnesses.mdx b/docs/it/reference/harnesses.mdx index 6490d98f..c30f6531 100644 --- a/docs/it/reference/harnesses.mdx +++ b/docs/it/reference/harnesses.mdx @@ -1,86 +1,92 @@ --- -title: "Adattatori agente" -description: "Cattura sessioni e applica politiche su tutti i 12 adattatori agente supportati." +title: "Harness per agenti" +description: "Cattura sessioni e applica criteri su tutti i 12 harness di agenti supportati." icon: "plug-zap" --- -Un adattatore è ciò in cui l'agente effettivamente viene eseguito. Failproof AI supporta dodici di essi, in due classi: +Un harness è l'ambiente in cui il tuo agente effettivamente viene eseguito. Failproof AI supporta dodici di essi, divisi in due categorie: -- **CLI di codifica** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **Gateway di chat e assistenti** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistente self-hosted) +- **Coding CLI** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose +- **Chat e gateway assistenti** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistente self-hosted) -Le stesse politiche e la stessa cronologia delle sessioni si applicano indipendentemente da quale adattatore esegue l'agente. Un livello di adattamento mappa i nomi degli eventi nativi di ogni adattatore, i nomi degli strumenti e i campi di input degli strumenti su 29 eventi canonici prima che qualsiasi politica venga eseguita. +Gli stessi criteri e la stessa cronologia delle sessioni si applicano indipendentemente da quale harness esegue l'agente. Un livello di adattamento mappa i nomi degli eventi nativi di ogni harness, i nomi degli strumenti e i campi di input degli strumenti su 29 eventi canonici prima che venga eseguito qualsiasi criterio. -Un agente che viene eseguito in **nessuno** dei dodici viene strumentato direttamente con [Python SDK](/it/reference/custom-agents). Si tratta di un contratto diverso, e vale la pena dichiararlo esplicitamente: l'SDK fornisce tracciamento, sessioni, valutazioni e audit — **non applica politiche di per sé.** Bloccare un'azione non sicura prima che venga eseguita richiede un hook di applicazione al confine degli strumenti del runtime; [contattaci](mailto:support@befailproof.ai) e lo mapperemo. +Un agente che viene eseguito in **nessuno** dei dodici viene strumentato direttamente con [Python SDK](/it/reference/custom-agents). È un contratto diverso, e vale la pena dichiararlo chiaramente: l'SDK fornisce tracciamento, sessioni, valutazioni e audit — **non applica criteri autonomamente.** Il blocco di un'azione non sicura prima della sua esecuzione richiede un hook di enforcement al confine degli strumenti del tuo runtime; [contattaci](mailto:support@befailproof.ai) e lo mapperemo. -| Adattatore | Ambiti di hook supportati | +| Harness | Scope hook supportati | | --- | --- | -| Claude Code | Utente, progetto, locale | -| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | Utente, progetto | -| Factory Droid, Devin CLI, Antigravity CLI, Goose | Utente, progetto | -| Hermes, OpenClaw | Utente | +| Claude Code | User, project, local | +| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | User, project | +| Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | +| Hermes, OpenClaw | User | -Ogni integrazione normalizza i nomi degli eventi hook nativi, i nomi degli strumenti e i campi di input degli strumenti prima che le politiche vengano eseguite. Una politica può agire solo su eventi esposti dall'adattatore; testa il comportamento di fine turno e istruzione sull'esatto adattatore e versione che distribuisci. +Ogni integrazione normalizza i nomi degli eventi hook nativi, i nomi degli strumenti e i campi di input degli strumenti prima che vengono eseguiti i criteri. Un criterio può agire solo su eventi esposti dall'harness; testa il comportamento end-of-turn e le istruzioni sull'harness e sulla versione esatta che distribuisci. -## Capacità di applicazione +## Capacità di enforcement -"Blocco" significa che il verdetto restituito dall'adattatore corrente viene utilizzato dall'adattatore nominato. Il blocco post-strumento può sostituire il risultato mostrato al modello ma non può annullare un effetto collaterale dello strumento già avvenuto. +"Block" significa che il verdetto restituito dall'adattatore corrente viene consumato dall'harness denominato. Il blocco post-tool può sostituire il risultato mostrato al modello ma non può annullare un effetto collaterale dello strumento che si è già verificato. -| Adattatore | Eventi di blocco verificati | Avvertenze di osservazione o non blocco | +| Harness | Eventi di blocco verificati | Avvertenze osservazione-only o non-blocking | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, e diversi eventi di task/config | `PostToolUse`, ciclo di vita della sessione, notifiche ed eventi post-errore sono osservativi. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Il blocco post-strumento sostituisce il risultato dopo l'esecuzione; gli eventi di avvio della sessione e compattazione sono osservativi nell'adattatore corrente. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Il blocco post-strumento sostituisce il risultato dopo l'esecuzione; gli eventi di sessione e notifica sono osservativi. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` e gli eventi di sessione sono osservativi. | -| OpenCode | `PreToolUse` | Gli eventi post-strumento e del ciclo di vita sono osservativi; la gestione dello stop corrente è una guida per un turno successivo piuttosto che un gate verificato. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Gli eventi post-strumento e del ciclo di vita sono osservativi; la guida dello stop si applica a un turno successivo. | -| Hermes | `PreToolUse` | I verdetti post-strumento, sessione e subagent-stop non sono gate. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Gli eventi post-strumento, sessione, subagent-stop e compattazione sono osservativi. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | I verdetti post-strumento e subagent-stop sono osservativi. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` condizionale | Gli hook di permesso non vengono eseguiti in ogni modalità di permesso; gli eventi post-strumento e di sessione sono osservativi. | -| Antigravity CLI | `PreToolUse`, `Stop` | I verdetti di prompt utente e post-strumento sono osservativi; le istruzioni di prompt possono comunque essere iniettate. | -| Goose | `PreToolUse` | Gli eventi di prompt utente, post-strumento e di sessione sono osservativi. Esiste un hook di stop di blocco nativo a monte ma non viene installato dall'adattatore corrente. | - -Le capacità sono sensibili alla versione. Ritesta dopo l'aggiornamento di un CLI agente, soprattutto quando una politica si basa su comportamento di prompt, stop, permesso o post-strumento piuttosto che sul gate pre-strumento comune. - -## Installa hook di cattura e politica +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` e diversi eventi di task/config | `PostToolUse`, ciclo di vita della sessione, notifiche e eventi post-errore sono osservazionali. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Il blocco post-tool sostituisce il risultato dopo l'esecuzione; gli eventi session-start e compact sono osservazionali nell'adattatore corrente. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Il blocco post-tool sostituisce il risultato dopo l'esecuzione; gli eventi session e notification sono osservazionali. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` e gli eventi session sono osservazionali. | +| OpenCode | `PreToolUse` | Gli eventi post-tool e ciclo di vita sono osservazionali; la gestione dello stop corrente è una guida per un turno successivo piuttosto che un gate verificato. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Gli eventi post-tool e ciclo di vita sono osservazionali; la guida dello stop si applica a un turno successivo. | +| Hermes | `PreToolUse` | Un plugin nativo fornisce `instruct()` come un'interruzione limitata e visibile al modello prima di consentire un'iterazione API successiva. I verdetti post-tool, session e subagent-stop non sono gate. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Gli eventi post-tool, session, subagent-stop e compaction sono osservazionali. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | I verdetti post-tool e subagent-stop sono osservazionali. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` condizionato | Gli hook permission non vengono eseguiti in ogni modalità di permission; gli eventi post-tool e session sono osservazionali. | +| Antigravity CLI | `PreToolUse`, `Stop` | I verdetti user-prompt e post-tool sono osservazionali; le istruzioni di prompt possono comunque essere iniettate. | +| Goose | `PreToolUse` | Gli eventi user-prompt, post-tool e session sono osservazionali. Esiste un hook stop di blocco nativo a monte ma non è installato dall'adattatore corrente. | + +Le capacità sono sensibili alla versione. Ripeti i test dopo l'aggiornamento di un agent CLI, soprattutto quando un criterio si basa su comportamento di prompt, stop, permission o post-tool anziché sul gate pre-tool comune. + +### Plugin nativo di Hermes + +Hermes è integrato attraverso un plugin nativo profile-local anziché un comando shell. L'installazione copia il plugin in ogni profilo Hermes predefinito e denominato, lo abilita nel `config.yaml` di quel profilo e migra solo le voci FailproofAI del legacy shell-hook. Questo evita uno spawn di processo su ogni hook e permette a `instruct()` di raggiungere il modello attraverso il risultato di blocked-tool nativo di Hermes. + +La prima istruzione corrispondente blocca la chiamata in sospeso. La stessa richiesta API rimane bloccata; un'iterazione del modello successiva può riprovare. Un libro mastro persistente con ambito profilo e un limite per turno impediscono a un'istruzione consultiva di diventare un ciclo senza limiti. `deny()` rimane un blocco duro. Esegui `failproofai config --status` per rilevare un profilo disabilitato, incompleto, duplicato o non configurato di recente. + +## Installa hook di cattura e criteri - 1. Apri **Administration → Keys** e crea una chiave con `events:add` e `policies:pull`, nominata per la macchina o l'ambiente. - 2. Sulla macchina di destinazione, connetti il CLI locale con la chiave visualizzata e installa gli hook dell'adattatore. - 3. Avvia una nuova sessione agente, quindi conferma i relativi hook e gli eventi di sessione sotto **Observe → Events**. - 4. Apri **Observe → policy** per la stessa finestra temporale e conferma che una decisione di politica è attribuita alla macchina. + 1. Apri **Administration → Keys** e crea una chiave con `events:add` e `policies:pull`, denominata per la macchina o l'ambiente. + 2. Sulla macchina target, connetti la CLI locale con la chiave visualizzata e installa gli hook dell'harness. + 3. Avvia una nuova sessione agente, quindi conferma i suoi eventi hook e sessione sotto **Observe → Events**. + 4. Apri **Observe → policy** per la stessa finestra temporale e conferma che una decisione di criterio è attribuita alla macchina. - La connessione inizia con una chiave di macchina. Conferma che includa sia le autorizzazioni di acquisizione che di consegna delle politiche prima di copiare il suo segreto. + La connessione inizia con una chiave macchina. Conferma che includa sia le autorizzazioni di ingestione che di policy-delivery prima di copiare il suo segreto. - ![Il nuovo cassetto della chiave API utilizzato per concedere autorizzazioni di acquisizione di eventi e consegna delle politiche.](/images/dashboard/key-create.png) + ![Il cassetto della nuova chiave API utilizzato per concedere le autorizzazioni di event ingestion e policy delivery.](/images/dashboard/key-create.png) - Dopo aver installato gli hook, il flusso Events dovrebbe mostrare nuovi eventi dalla macchina e dall'ambiente che hai connesso. + Dopo l'installazione degli hook, il flusso Events dovrebbe mostrare nuovi eventi dalla macchina e dall'ambiente che hai connesso. - ![Il flusso Events live utilizzato per confermare che un adattatore appena installato sta segnalando.](/images/dashboard/events-stream.png) + ![Il flusso Events live utilizzato per confermare che un harness appena installato sta segnalando.](/images/dashboard/events-stream.png) - Infine, verifica che le decisioni di politica siano attribuite alla stessa macchina. Questo conferma che l'adattatore sta segnalando l'attività di politica così come gli eventi di tracciamento. + Infine, verifica che le decisioni di criterio siano attribuite alla stessa macchina. Questo conferma che l'harness sta segnalando l'attività di criterio oltre agli eventi di tracciamento. - ![La pagina Policy utilizzata per verificare le decisioni di politica da un adattatore appena connesso.](/images/dashboard/policy-observe.png) + ![La pagina Policy utilizzata per verificare le decisioni di criterio da un harness appena connesso.](/images/dashboard/policy-observe.png) - Leggi la chiave di macchina nella shell. `read -s` la accetta a un prompt che non fa echo, quindi non appare mai in un comando o nella cronologia della shell: + Leggi la chiave macchina nella shell. `read -s` la prende a un prompt che non viene mostrato, quindi non appare mai in un comando o nella cronologia della shell: ```bash read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - Quindi configura la macchina — questo collega hook per ogni adattatore rilevato, installa il daemon e si connette a Cloud: + Quindi imposta la macchina — questo collega gli hook per ogni harness rilevato, installa il daemon e si connette a Cloud: ```bash failproofai config failproofai policies add FailproofAI/policies ``` - La configurazione non abilita alcuna politica di per sé, ed è quello per cui serve il secondo comando. + La configurazione non abilita alcun criterio di per sé, ecco cosa fa il secondo comando. - Oppure seleziona adattatori denominati e un ambito di configurazione: + Oppure specifica harness denominati e uno scope di configurazione: ```bash failproofai policies --install \ @@ -88,7 +94,7 @@ Le capacità sono sensibili alla versione. Ritesta dopo l'aggiornamento di un CL --scope user ``` - L'ambito di progetto mantiene la configurazione dell'hook con un repository. L'ambito utente copre il lavoro su più repository. Claude Code supporta anche l'ambito locale; il supporto varia in base all'adattatore e il CLI rifiuta le combinazioni non supportate. + Lo scope di progetto mantiene la configurazione hook con un repository. Lo scope di user copre il lavoro tra repository. Claude Code supporta anche lo scope locale; il supporto varia in base all'harness e la CLI rifiuta le combinazioni non supportate. Verifica la macchina e i suoi eventi: @@ -100,13 +106,13 @@ Le capacità sono sensibili alla versione. Ritesta dopo l'aggiornamento di un CL -## Aggiungi un percorso di sessione non predefinito +## Aggiungi un percorso sessione non predefinito - I percorsi aggiuntivi vengono registrati sulla macchina, non in Cloud. Dopo averne aggiunto uno, apri **Observe → Sessions**, filtra per l'ambiente della macchina e conferma che le sessioni dal nuovo percorso vengono visualizzate. Apri una sessione e verifica l'agente, l'adattatore e i timestamp degli eventi prima di affidarsi su di essa in un audit. + I percorsi aggiuntivi vengono registrati sulla macchina, non in Cloud. Dopo aver aggiunto uno, apri **Observe → Sessions**, filtra in base all'ambiente della macchina e conferma che le sessioni dal nuovo percorso compaiono. Apri una sessione e controlla l'agente, l'harness e i timestamp degli eventi prima di fare affidamento su di esso in un audit. - ![L'elenco Sessions filtrato all'ambiente che riceve dati dal percorso di cattura aggiuntivo.](/images/dashboard/sessions-list.png) + ![L'elenco Sessions filtrato in base all'ambiente che riceve dati dal percorso di cattura aggiuntivo.](/images/dashboard/sessions-list.png) Aggiungi un percorso con un'etichetta opzionale, quindi ispeziona i percorsi configurati: @@ -123,5 +129,5 @@ Le capacità sono sensibili alla versione. Ritesta dopo l'aggiornamento di un CL - Esegui una nuova sessione dopo l'installazione. Verifica sia il flusso di eventi live che una decisione di politica effettiva prima di espandere l'implementazione. + Esegui una nuova sessione dopo l'installazione. Verifica sia il flusso di eventi live che un'effettiva decisione di criterio prima di espandere il rollout. \ No newline at end of file diff --git a/docs/ja/reference/harnesses.mdx b/docs/ja/reference/harnesses.mdx index 98da7ff2..059a8cd6 100644 --- a/docs/ja/reference/harnesses.mdx +++ b/docs/ja/reference/harnesses.mdx @@ -1,62 +1,68 @@ --- title: "エージェントハーネス" -description: "サポートされている12種類のエージェントハーネス全体でセッションをキャプチャし、ポリシーを適用します。" +description: "サポートされている12のエージェントハーネス全体でセッションをキャプチャし、ポリシーを適用します。" icon: "plug-zap" --- -ハーネスとは、エージェントが実際に動作する環境のことです。Failproof AI は2種類、計12のハーネスをサポートしています。 +ハーネスとは、エージェントが実際に動作する実行環境のことです。Failproof AI は2つのクラスに分かれた12種類のハーネスをサポートしています。 -- **コーディングCLI**（10種類）— Claude Code、Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi、Factory Droid、Devin CLI、Antigravity CLI、Goose -- **チャット・アシスタントゲートウェイ**（2種類）— Hermes（Slack、Telegram、cron）、OpenClaw（セルフホスト型アシスタント） +- **コーディングCLI**（10種類） — Claude Code、Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi、Factory Droid、Devin CLI、Antigravity CLI、Goose +- **チャット・アシスタントゲートウェイ**（2種類） — Hermes（Slack、Telegram、cron）、OpenClaw（セルフホスト型アシスタント） -どのハーネスでエージェントが動作していても、同じポリシーと同じセッション履歴が適用されます。1つのアダプター層が、各ハーネス固有のイベント名・ツール名・ツール入力フィールドを、ポリシー実行前に29種類の標準イベントへマッピングします。 +エージェントがどのハーネス上で動作していても、同じポリシーと同じセッション履歴が適用されます。アダプター層が各ハーネス固有のイベント名、ツール名、ツール入力フィールドを29個の正規化されたイベントにマッピングしてから、ポリシーが実行されます。 -12種類のいずれにも該当しないエージェントは、[Python SDK](/ja/reference/custom-agents) を使って直接インストルメント化されます。これは異なる契約であり、明確にお伝えしておくべき点があります。SDKはトレーシング・セッション・評価・監査を提供しますが、**ポリシーを単独で適用する機能はありません。** 実行前に安全でないアクションをブロックするには、ランタイムのツール境界に強制フックが必要です。[お問い合わせ](mailto:support@befailproof.ai)いただければ、マッピングをご支援します。 +12種類のいずれのハーネスも使用しないエージェントは、[Python SDK](/ja/reference/custom-agents) を使用して直接インストルメント化されます。これは異なる契約であり、明確にしておく価値があります。SDKはトレーシング、セッション、評価、監査を提供しますが、**それ自体ではポリシーを適用しません。** 実行前に安全でないアクションをブロックするには、ランタイムのツール境界に強制フックが必要です。[お問い合わせ](mailto:support@befailproof.ai)いただければ、マッピングを対応いたします。 -| ハーネス | サポートされるフックスコープ | +| ハーネス | サポートされているフックスコープ | | --- | --- | | Claude Code | User、project、local | | Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi | User、project | | Factory Droid、Devin CLI、Antigravity CLI、Goose | User、project | | Hermes、OpenClaw | User | -各インテグレーションは、ポリシー実行前にハーネス固有のフックイベント名・ツール名・ツール入力フィールドを正規化します。ポリシーはハーネスが公開するイベントに対してのみ作用します。エンドオブターンの動作やインストラクションの動作は、実際にデプロイするハーネスとバージョンで必ずテストしてください。 +各インテグレーションは、ポリシーが実行される前に、固有のフックイベント名、ツール名、ツール入力フィールドを正規化します。ポリシーはハーネスが公開するイベントにのみ作用できます。ターンの終了および指示の動作については、実際にデプロイするハーネスとバージョンで必ずテストしてください。 -## 強制適用の機能 +## 適用機能 -「ブロック」とは、現在のアダプターが返した判定を対象ハーネスが受け入れることを意味します。ツール後のブロックはモデルに示される結果を置き換えることができますが、既に発生したツールの副作用を元に戻すことはできません。 +「ブロック」とは、現在のアダプターが返す判定を対象ハーネスが消費することを意味します。ポストツールのブロックはモデルに表示される結果を置き換えることがありますが、すでに発生したツールの副作用を元に戻すことはできません。 -| ハーネス | 検証済みブロックイベント | 観察のみ、またはブロック非対応の注意事項 | +| ハーネス | 確認済みブロックイベント | 観測のみまたは非ブロックの注意事項 | | --- | --- | --- | -| Claude Code | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PreCompact`、およびいくつかのタスク/設定イベント | `PostToolUse`、セッションライフサイクル、通知、失敗後イベントは観察のみ。 | -| Codex | `PreToolUse`、`PermissionRequest`、`UserPromptSubmit`、`Stop`、`SubagentStop`、`PostToolUse` | ツール後のブロックは実行後に結果を置き換えます。セッション開始およびコンパクトイベントは現在のアダプターでは観察のみ。 | -| GitHub Copilot CLI | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PostToolUse` | ツール後のブロックは実行後に結果を置き換えます。セッションおよび通知イベントは観察のみ。 | -| Cursor | `PreToolUse`、`UserPromptSubmit`、`Stop` | `PostToolUse` およびセッションイベントは観察のみ。 | -| OpenCode | `PreToolUse` | ツール後およびライフサイクルイベントは観察のみ。現在のストップ処理は検証済みゲートではなく、後続ターンへのガイダンスとして機能。 | -| Pi | `PreToolUse`、`UserPromptSubmit` | ツール後およびライフサイクルイベントは観察のみ。ストップガイダンスは後続ターンに適用。 | -| Hermes | `PreToolUse` | ツール後、セッション、サブエージェントストップの判定はゲートとして機能しません。 | -| OpenClaw | `PreToolUse`、`UserPromptSubmit`、`Stop` | ツール後、セッション、サブエージェントストップ、コンパクションイベントは観察のみ。 | -| Factory Droid | `PreToolUse`、`UserPromptSubmit`、`Stop`、`PreCompact` | ツール後およびサブエージェントストップの判定は観察のみ。 | -| Devin CLI | `PreToolUse`、`UserPromptSubmit`、`Stop`、条件付き `PermissionRequest` | パーミッションフックはすべてのパーミッションモードで実行されるわけではありません。ツール後およびセッションイベントは観察のみ。 | -| Antigravity CLI | `PreToolUse`、`Stop` | ユーザープロンプトおよびツール後の判定は観察のみ。プロンプトインストラクションのインジェクションは引き続き可能。 | -| Goose | `PreToolUse` | ユーザープロンプト、ツール後、セッションイベントは観察のみ。ネイティブのブロッキングストップフックは上流に存在しますが、現在のアダプターではインストールされていません。 | - -機能はバージョンに依存します。エージェントCLIをアップグレードした後は、特にポリシーが共通のプリツールゲートではなく、プロンプト・ストップ・パーミッション・ツール後の動作に依存している場合は、必ず再テストを行ってください。 +| Claude Code | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PreCompact`、および複数のタスク/設定イベント | `PostToolUse`、セッションライフサイクル、通知、および障害後イベントは観測のみです。 | +| Codex | `PreToolUse`、`PermissionRequest`、`UserPromptSubmit`、`Stop`、`SubagentStop`、`PostToolUse` | ポストツールのブロックは実行後に結果を置き換えます。セッション開始およびコンパクトイベントは現在のアダプターでは観測のみです。 | +| GitHub Copilot CLI | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PostToolUse` | ポストツールのブロックは実行後に結果を置き換えます。セッションおよび通知イベントは観測のみです。 | +| Cursor | `PreToolUse`、`UserPromptSubmit`、`Stop` | `PostToolUse` およびセッションイベントは観測のみです。 | +| OpenCode | `PreToolUse` | ポストツールおよびライフサイクルイベントは観測のみです。現在の停止処理は、確認済みのゲートではなく、後続ターンへのガイダンスです。 | +| Pi | `PreToolUse`、`UserPromptSubmit` | ポストツールおよびライフサイクルイベントは観測のみです。停止ガイダンスは後続ターンに適用されます。 | +| Hermes | `PreToolUse` | ネイティブプラグインが、後続のAPIイテレーションを許可する前に、`instruct()` を1回の境界付きでモデルから見える割り込みとして届けます。ポストツール、セッション、サブエージェント停止の判定はゲートではありません。 | +| OpenClaw | `PreToolUse`、`UserPromptSubmit`、`Stop` | ポストツール、セッション、サブエージェント停止、およびコンパクションイベントは観測のみです。 | +| Factory Droid | `PreToolUse`、`UserPromptSubmit`、`Stop`、`PreCompact` | ポストツールおよびサブエージェント停止の判定は観測のみです。 | +| Devin CLI | `PreToolUse`、`UserPromptSubmit`、`Stop`、条件付き `PermissionRequest` | パーミッションフックはすべてのパーミッションモードで実行されるわけではありません。ポストツールおよびセッションイベントは観測のみです。 | +| Antigravity CLI | `PreToolUse`、`Stop` | ユーザープロンプトおよびポストツールの判定は観測のみです。プロンプト指示の注入は引き続き可能です。 | +| Goose | `PreToolUse` | ユーザープロンプト、ポストツール、およびセッションイベントは観測のみです。ネイティブのブロッキング停止フックが上流に存在しますが、現在のアダプターではインストールされていません。 | + +機能はバージョンに依存します。エージェントCLIをアップグレードした後は、特にポリシーが共通のプレツールゲートではなく、プロンプト、停止、パーミッション、またはポストツールの動作に依存している場合は、再テストを行ってください。 + +### Hermes ネイティブプラグイン + +Hermes はシェルコマンドではなく、プロファイルローカルのネイティブプラグインを通じてインテグレーションされています。インストール時にプラグインをすべてのデフォルトおよび名前付きHermesプロファイルにコピーし、そのプロファイルの `config.yaml` で有効化し、レガシーのFailproofAIシェルフックエントリのみを移行します。これにより各フックでのプロセス生成を回避し、Hermesのネイティブなブロック済みツール結果を通じて `instruct()` をモデルに届けることができます。 + +最初に一致した指示が保留中の呼び出しをブロックします。同じAPIリクエストはブロックされたままになり、後続のモデルイテレーションで再試行される場合があります。永続的なプロファイルスコープの台帳とターンごとの上限により、アドバイザリー指示が無限ループになることを防ぎます。`deny()` はハードブロックのままです。`failproofai config --status` を実行すると、無効化された、不完全な、重複している、または新たに未設定のプロファイルを検出できます。 ## キャプチャとポリシーフックのインストール - 1. **Administration → Keys** を開き、`events:add` と `policies:pull` の権限を持つキーを作成します。マシンまたは環境の名前を付けてください。 - 2. 対象マシンで、表示されたキーを使ってローカルCLIを接続し、ハーネスフックをインストールします。 + 1. **Administration → Keys** を開き、マシンまたは環境の名前を付けた `events:add` および `policies:pull` 権限を持つキーを作成します。 + 2. 対象マシンで、表示されたキーを使用してローカルCLIを接続し、ハーネスフックをインストールします。 3. 新しいエージェントセッションを開始し、**Observe → Events** でフックとセッションイベントを確認します。 - 4. 同じ時間帯の **Observe → policy** を開き、そのマシンにポリシー決定が帰属していることを確認します。 + 4. 同じ時間ウィンドウで **Observe → policy** を開き、ポリシー決定がそのマシンに帰属していることを確認します。 - 接続はマシンキーから始まります。シークレットをコピーする前に、インジェストとポリシー配信の両方の権限が含まれていることを確認してください。 + 接続はマシンキーから始まります。シークレットをコピーする前に、取り込みとポリシー配信の両方の権限が含まれていることを確認してください。 - ![イベントインジェストとポリシー配信の権限を付与するための新しいAPIキードロワー。](/images/dashboard/key-create.png) + ![イベント取り込みとポリシー配信権限を付与するための新しいAPIキードロワー。](/images/dashboard/key-create.png) - フックをインストールした後、Eventsストリームに接続したマシンと環境からの新しいイベントが表示されるはずです。 + フックをインストールした後、Eventsストリームには接続したマシンと環境からの新しいイベントが表示されるはずです。 ![新しくインストールされたハーネスが報告していることを確認するためのライブEventsストリーム。](/images/dashboard/events-stream.png) @@ -65,20 +71,20 @@ icon: "plug-zap" ![新しく接続されたハーネスからのポリシー決定を確認するためのPolicyページ。](/images/dashboard/policy-observe.png) - マシンキーをシェルに読み込みます。`read -s` はエコーされないプロンプトでキーを受け取るため、コマンドやシェル履歴に残ることはありません。 + マシンキーをシェルに読み込みます。`read -s` はエコーしないプロンプトでキーを受け取るため、コマンドやシェル履歴に表示されることはありません。 ```bash read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - 次にマシンをセットアップします。検出されたすべてのハーネスにフックを接続し、デーモンをインストールし、Cloudに接続します。 + 次にマシンをセットアップします。これにより、検出されたすべてのハーネスのフックが接続され、デーモンがインストールされ、Cloudに接続されます。 ```bash failproofai config failproofai policies add FailproofAI/policies ``` - セットアップ自体はポリシーを有効にしません。それが2番目のコマンドの役割です。 + セットアップ自体はポリシーを有効化しません。2番目のコマンドがその役割を担います。 または、特定のハーネスと設定スコープを指定することもできます。 @@ -88,7 +94,7 @@ icon: "plug-zap" --scope user ``` - プロジェクトスコープはフック設定をリポジトリと一緒に管理します。ユーザースコープはリポジトリをまたいだ作業をカバーします。Claude Code はローカルスコープもサポートしていますが、サポート状況はハーネスによって異なり、CLIはサポートされていない組み合わせを拒否します。 + プロジェクトスコープはフック設定をリポジトリと一緒に管理します。ユーザースコープはリポジトリをまたいだ作業をカバーします。Claude Code はローカルスコープもサポートしています。サポート状況はハーネスによって異なり、CLIはサポートされていない組み合わせを拒否します。 マシンとそのイベントを確認します。 @@ -100,16 +106,16 @@ icon: "plug-zap" -## デフォルト以外のセッションパスを追加する +## デフォルト以外のセッションパスの追加 - 追加パスはマシン上に登録されます（Cloud上ではありません）。追加後、**Observe → Sessions** を開き、マシンの環境でフィルタリングして、新しいパスからのセッションが表示されることを確認してください。セッションを開いて、監査で使用する前にエージェント・ハーネス・イベントのタイムスタンプを確認してください。 + 追加パスはCloudではなく、マシン上に登録されます。追加後、**Observe → Sessions** を開き、マシンの環境でフィルタリングして、新しいパスからのセッションが表示されることを確認します。セッションを開き、監査で使用する前にエージェント、ハーネス、およびイベントのタイムスタンプを確認してください。 ![追加のキャプチャパスからデータを受信している環境にフィルタリングされたSessionsリスト。](/images/dashboard/sessions-list.png) - オプションのラベルを付けてパスを追加し、設定済みパスを確認します。 + オプションのラベルを付けてパスを追加し、設定済みのパスを確認します。 ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -118,7 +124,7 @@ icon: "plug-zap" failproofai backfill --since 7d ``` - パスを削除するには `failproofai harness remove-path claude checkout` を使用します。 + `failproofai harness remove-path claude checkout` でパスを削除します。 diff --git a/docs/ko/reference/harnesses.mdx b/docs/ko/reference/harnesses.mdx index 36b7a4ad..8b46d3bc 100644 --- a/docs/ko/reference/harnesses.mdx +++ b/docs/ko/reference/harnesses.mdx @@ -1,86 +1,92 @@ --- title: "에이전트 하네스" -description: "지원되는 12개 에이전트 하네스 전반에 걸쳐 세션을 캡처하고 정책을 적용합니다." +description: "지원되는 12개의 에이전트 하네스 전반에서 세션을 캡처하고 정책을 적용합니다." icon: "plug-zap" --- -하네스란 에이전트가 실제로 실행되는 환경을 의미합니다. Failproof AI는 두 가지 범주로 나뉜 12개의 하네스를 지원합니다. +하네스는 에이전트가 실제로 실행되는 환경을 의미합니다. Failproof AI는 두 가지 유형으로 구분되는 12개의 하네스를 지원합니다: - **코딩 CLI** (10개) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose - **채팅 및 어시스턴트 게이트웨이** (2개) — Hermes (Slack, Telegram, cron), OpenClaw (자체 호스팅 어시스턴트) -에이전트가 어떤 하네스에서 실행되든 동일한 정책과 동일한 세션 히스토리가 적용됩니다. 하나의 어댑터 레이어가 각 하네스의 네이티브 이벤트 이름, 툴 이름, 툴 입력 필드를 정책이 실행되기 전에 29개의 표준 이벤트로 매핑합니다. +에이전트가 어떤 하네스에서 실행되든 동일한 정책과 세션 히스토리가 적용됩니다. 하나의 어댑터 레이어가 각 하네스의 네이티브 이벤트 이름, 도구 이름, 도구 입력 필드를 정책이 실행되기 전에 29개의 표준 이벤트로 매핑합니다. -12개 중 **어느 하네스에도** 속하지 않는 에이전트는 [Python SDK](/ko/reference/custom-agents)를 통해 직접 계측됩니다. 이는 별개의 계약이므로 명확히 짚고 넘어갈 필요가 있습니다. SDK는 트레이싱, 세션, 평가, 감사 기능을 제공하지만 **정책을 자체적으로 적용하지는 않습니다.** 툴이 실행되기 전에 안전하지 않은 동작을 차단하려면 런타임의 툴 경계에 실행 훅이 필요합니다. [문의하기](mailto:support@befailproof.ai)를 통해 연락 주시면 매핑해 드리겠습니다. +12개 중 **어느 것도** 사용하지 않는 에이전트는 [Python SDK](/ko/reference/custom-agents)를 통해 직접 계측됩니다. 이는 별도의 계약이므로 명확히 말씀드립니다: SDK는 추적, 세션, 평가, 감사를 제공하지만 **자체적으로는 정책을 적용하지 않습니다.** 실행 전에 안전하지 않은 동작을 차단하려면 런타임의 도구 경계에 실행 훅이 필요합니다. [문의하기](mailto:support@befailproof.ai)를 통해 연락하시면 매핑해 드립니다. -| 하네스 | 지원되는 훅 스코프 | +| 하네스 | 지원되는 훅 범위 | | --- | --- | | Claude Code | User, project, local | | Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | User, project | | Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | | Hermes, OpenClaw | User | -각 통합은 정책이 실행되기 전에 네이티브 훅 이벤트 이름, 툴 이름, 툴 입력 필드를 정규화합니다. 정책은 해당 하네스가 노출하는 이벤트에만 적용될 수 있으므로, 실제로 배포하는 하네스와 버전에서 직접 턴 종료 및 명령 동작을 테스트하시기 바랍니다. +각 통합은 정책이 실행되기 전에 네이티브 훅 이벤트 이름, 도구 이름, 도구 입력 필드를 정규화합니다. 정책은 해당 하네스가 노출하는 이벤트에만 작용할 수 있으므로, 실제로 배포하는 하네스와 버전에서 턴 종료 및 명령 동작을 테스트하시기 바랍니다. -## 적용 가능 범위 +## 적용 기능 -"차단(Block)"은 현재 어댑터가 반환한 판정(verdict)이 해당 하네스에 의해 처리됨을 의미합니다. 툴 실행 후(post-tool) 차단은 모델에게 표시되는 결과를 대체할 수 있지만, 이미 발생한 툴 부작용을 되돌릴 수는 없습니다. +"차단"이란 현재 어댑터가 반환한 판정이 해당 하네스에서 소비됨을 의미합니다. 도구 사후 차단은 모델에 표시되는 결과를 대체할 수 있지만, 이미 발생한 도구 부작용을 되돌릴 수는 없습니다. | 하네스 | 검증된 차단 이벤트 | 관찰 전용 또는 비차단 주의사항 | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` 및 여러 태스크/설정 이벤트 | `PostToolUse`, 세션 라이프사이클, 알림, 실패 후 이벤트는 관찰용입니다. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | 툴 실행 후 차단은 실행 완료 후 결과를 대체합니다. 세션 시작 및 컴팩트 이벤트는 현재 어댑터에서 관찰 전용입니다. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | 툴 실행 후 차단은 실행 완료 후 결과를 대체합니다. 세션 및 알림 이벤트는 관찰 전용입니다. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` 및 세션 이벤트는 관찰 전용입니다. | -| OpenCode | `PreToolUse` | 툴 실행 후 및 라이프사이클 이벤트는 관찰 전용입니다. 현재 stop 처리는 검증된 게이트가 아닌 다음 턴에 대한 안내입니다. | -| Pi | `PreToolUse`, `UserPromptSubmit` | 툴 실행 후 및 라이프사이클 이벤트는 관찰 전용입니다. stop 안내는 다음 턴에 적용됩니다. | -| Hermes | `PreToolUse` | 툴 실행 후, 세션, 서브에이전트 stop 판정은 게이트로 작동하지 않습니다. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | 툴 실행 후, 세션, 서브에이전트 stop, 컴팩션 이벤트는 관찰 전용입니다. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | 툴 실행 후 및 서브에이전트 stop 판정은 관찰 전용입니다. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, 조건부 `PermissionRequest` | 권한 훅은 모든 권한 모드에서 실행되지 않습니다. 툴 실행 후 및 세션 이벤트는 관찰 전용입니다. | -| Antigravity CLI | `PreToolUse`, `Stop` | 사용자 프롬프트 및 툴 실행 후 판정은 관찰 전용입니다. 프롬프트 지침은 여전히 주입될 수 있습니다. | -| Goose | `PreToolUse` | 사용자 프롬프트, 툴 실행 후, 세션 이벤트는 관찰 전용입니다. 네이티브 차단 stop 훅이 업스트림에 존재하지만 현재 어댑터에는 설치되어 있지 않습니다. | - -기능은 버전에 따라 달라질 수 있습니다. 에이전트 CLI를 업그레이드한 후에는, 특히 정책이 공통 프리툴 게이트가 아닌 프롬프트, stop, 권한, 또는 툴 실행 후 동작에 의존하는 경우 반드시 재테스트하시기 바랍니다. +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, 및 여러 태스크/설정 이벤트 | `PostToolUse`, 세션 라이프사이클, 알림, 실패 후 이벤트는 관찰용입니다. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | 도구 사후 차단은 실행 후 결과를 대체하며, 세션 시작 및 컴팩트 이벤트는 현재 어댑터에서 관찰용입니다. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | 도구 사후 차단은 실행 후 결과를 대체하며, 세션 및 알림 이벤트는 관찰용입니다. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` 및 세션 이벤트는 관찰용입니다. | +| OpenCode | `PreToolUse` | 도구 사후 및 라이프사이클 이벤트는 관찰용이며, 현재 중단 처리는 검증된 게이트가 아닌 이후 턴에 대한 안내입니다. | +| Pi | `PreToolUse`, `UserPromptSubmit` | 도구 사후 및 라이프사이클 이벤트는 관찰용이며, 중단 안내는 이후 턴에 적용됩니다. | +| Hermes | `PreToolUse` | 네이티브 플러그인이 `instruct()`를 이후 API 반복을 허용하기 전의 단일, 경계가 있는 모델 가시적 중단으로 전달합니다. 도구 사후, 세션, 서브에이전트 중단 판정은 게이트가 아닙니다. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | 도구 사후, 세션, 서브에이전트 중단, 컴팩션 이벤트는 관찰용입니다. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | 도구 사후 및 서브에이전트 중단 판정은 관찰용입니다. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, 조건부 `PermissionRequest` | 권한 훅이 모든 권한 모드에서 실행되지는 않으며, 도구 사후 및 세션 이벤트는 관찰용입니다. | +| Antigravity CLI | `PreToolUse`, `Stop` | 사용자 프롬프트 및 도구 사후 판정은 관찰용이지만, 프롬프트 명령은 여전히 주입될 수 있습니다. | +| Goose | `PreToolUse` | 사용자 프롬프트, 도구 사후, 세션 이벤트는 관찰용입니다. 네이티브 차단 중단 훅이 업스트림에 존재하지만 현재 어댑터에서는 설치되지 않습니다. | + +기능은 버전에 따라 달라집니다. 에이전트 CLI를 업그레이드한 후, 특히 정책이 공통 사전 도구 게이트가 아닌 프롬프트, 중단, 권한 또는 도구 사후 동작에 의존하는 경우에는 반드시 재테스트하십시오. + +### Hermes 네이티브 플러그인 + +Hermes는 셸 명령이 아닌 프로필 로컬 네이티브 플러그인을 통해 통합됩니다. 설치 시 플러그인이 모든 기본 및 명명된 Hermes 프로필에 복사되고, 해당 프로필의 `config.yaml`에서 활성화되며, 레거시 FailproofAI 셸 훅 항목만 마이그레이션됩니다. 이를 통해 각 훅마다 프로세스가 생성되는 것을 방지하고, `instruct()`가 Hermes의 네이티브 차단 도구 결과를 통해 모델에 도달할 수 있습니다. + +첫 번째로 일치하는 명령이 대기 중인 호출을 차단합니다. 동일한 API 요청은 차단된 상태로 유지되며, 이후 모델 반복에서 재시도할 수 있습니다. 영구적인 프로필 범위 원장과 턴당 상한이 권고 명령이 무한 루프가 되는 것을 방지합니다. `deny()`는 여전히 강력한 차단으로 유지됩니다. `failproofai config --status`를 실행하여 비활성화되거나, 불완전하거나, 중복되거나, 새로 구성되지 않은 프로필을 감지하세요. ## 캡처 및 정책 훅 설치 - 1. **Administration → Keys**를 열고 `events:add` 및 `policies:pull` 권한을 가진 키를 생성하고, 머신 또는 환경에 맞는 이름을 붙입니다. + 1. **Administration → Keys**를 열고 머신 또는 환경에 맞는 이름으로 `events:add`와 `policies:pull` 권한이 있는 키를 생성합니다. 2. 대상 머신에서 표시된 키로 로컬 CLI를 연결하고 하네스 훅을 설치합니다. - 3. 새 에이전트 세션을 시작한 후 **Observe → Events**에서 해당 훅 및 세션 이벤트를 확인합니다. - 4. 동일한 시간 범위의 **Observe → policy**를 열고 정책 결정이 해당 머신에 귀속되는지 확인합니다. + 3. 새 에이전트 세션을 시작한 다음 **Observe → Events**에서 훅 및 세션 이벤트를 확인합니다. + 4. 동일한 시간 범위에서 **Observe → policy**를 열고 해당 머신에 정책 결정이 귀속되는지 확인합니다. - 연결은 머신 키로 시작됩니다. 시크릿을 복사하기 전에 수집 및 정책 전달 권한이 모두 포함되어 있는지 확인하세요. + 연결은 머신 키로 시작됩니다. 비밀 키를 복사하기 전에 수집 및 정책 전달 권한이 모두 포함되어 있는지 확인하세요. - ![이벤트 수집 및 정책 전달 권한을 부여하는 새 API 키 드로어.](/images/dashboard/key-create.png) + ![이벤트 수집 및 정책 전달 권한을 부여하는 데 사용되는 새 API 키 드로어.](/images/dashboard/key-create.png) - 훅을 설치한 후, Events 스트림에 연결한 머신 및 환경의 새 이벤트가 표시되어야 합니다. + 훅을 설치한 후, Events 스트림에 연결한 머신 및 환경에서 새로운 이벤트가 표시되어야 합니다. - ![새로 설치된 하네스가 보고 중인지 확인하는 라이브 Events 스트림.](/images/dashboard/events-stream.png) + ![새로 설치된 하네스가 보고 중임을 확인하는 데 사용되는 라이브 Events 스트림.](/images/dashboard/events-stream.png) - 마지막으로, 정책 결정이 동일한 머신에 귀속되는지 확인합니다. 이를 통해 하네스가 트레이스 이벤트뿐만 아니라 정책 활동도 보고하고 있음을 확인할 수 있습니다. + 마지막으로, 동일한 머신에 정책 결정이 귀속되는지 확인합니다. 이를 통해 하네스가 추적 이벤트뿐만 아니라 정책 활동도 보고하고 있음을 확인할 수 있습니다. - ![새로 연결된 하네스의 정책 결정을 검증하는 Policy 페이지.](/images/dashboard/policy-observe.png) + ![새로 연결된 하네스의 정책 결정을 확인하는 데 사용되는 Policy 페이지.](/images/dashboard/policy-observe.png) - 머신 키를 셸로 읽어옵니다. `read -s`는 에코되지 않는 프롬프트에서 키를 입력받으므로 커맨드나 셸 히스토리에 절대 남지 않습니다. + 머신 키를 셸로 읽어옵니다. `read -s`는 에코되지 않는 프롬프트에서 키를 입력받으므로, 명령이나 셸 히스토리에 절대 나타나지 않습니다: ```bash read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - 그런 다음 머신을 설정합니다. 이 과정에서 감지된 모든 하네스에 훅을 연결하고, 데몬을 설치하며, Cloud에 연결합니다. + 그런 다음 머신을 설정합니다 — 감지된 모든 하네스에 훅을 연결하고, 데몬을 설치하며, Cloud에 연결합니다: ```bash failproofai config failproofai policies add FailproofAI/policies ``` - 설정 자체는 어떠한 정책도 활성화하지 않으며, 두 번째 명령이 그 역할을 합니다. + 설정 자체는 어떤 정책도 활성화하지 않으며, 그것이 두 번째 명령의 역할입니다. - 또는 특정 하네스와 설정 스코프를 지정할 수 있습니다. + 또는 특정 하네스와 설정 범위를 지정할 수 있습니다: ```bash failproofai policies --install \ @@ -88,9 +94,9 @@ icon: "plug-zap" --scope user ``` - 프로젝트 스코프는 훅 설정을 리포지토리와 함께 유지합니다. 유저 스코프는 리포지토리 전반의 작업을 포괄합니다. Claude Code는 로컬 스코프도 지원하며, 지원 여부는 하네스마다 다르고 CLI는 지원되지 않는 조합을 거부합니다. + 프로젝트 범위는 훅 설정을 레포지토리에 유지합니다. 사용자 범위는 레포지토리 전반의 작업을 커버합니다. Claude Code는 로컬 범위도 지원하며, 지원 여부는 하네스마다 다르고 CLI는 지원되지 않는 조합을 거부합니다. - 머신과 이벤트를 확인합니다. + 머신과 이벤트를 확인합니다: ```bash failproofai config --status @@ -100,16 +106,16 @@ icon: "plug-zap" -## 기본이 아닌 세션 경로 추가 +## 기본값이 아닌 세션 경로 추가 - 추가 경로는 Cloud가 아닌 머신에 등록됩니다. 경로를 추가한 후 **Observe → Sessions**를 열고, 머신의 환경으로 필터링하여 새 경로에서 세션이 나타나는지 확인합니다. 감사에 활용하기 전에 세션을 열어 에이전트, 하네스, 이벤트 타임스탬프를 검토하세요. + 추가 경로는 Cloud가 아닌 머신에 등록됩니다. 경로를 추가한 후 **Observe → Sessions**를 열고, 해당 머신의 환경으로 필터링하여 새 경로에서의 세션이 표시되는지 확인합니다. 감사에 활용하기 전에 세션을 열어 에이전트, 하네스, 이벤트 타임스탬프를 확인하세요. - ![추가 캡처 경로로부터 데이터를 수신하는 환경으로 필터링된 Sessions 목록.](/images/dashboard/sessions-list.png) + ![추가 캡처 경로에서 데이터를 수신하는 환경으로 필터링된 Sessions 목록.](/images/dashboard/sessions-list.png) - 선택적 레이블과 함께 경로를 추가한 후 설정된 경로를 확인합니다. + 선택적 레이블과 함께 경로를 추가한 다음 설정된 경로를 확인합니다: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -118,10 +124,10 @@ icon: "plug-zap" failproofai backfill --since 7d ``` - 경로를 제거하려면 `failproofai harness remove-path claude checkout`을 사용하세요. + `failproofai harness remove-path claude checkout`으로 경로를 제거합니다. - 설치 후 새 세션을 한 번 실행하세요. 롤아웃을 확대하기 전에 라이브 이벤트 스트림과 실제 정책 결정을 모두 확인하시기 바랍니다. + 설치 후 새 세션을 하나 실행하세요. 롤아웃을 확장하기 전에 라이브 이벤트 스트림과 실제 정책 결정을 모두 확인하시기 바랍니다. \ No newline at end of file diff --git a/docs/pt-br/reference/harnesses.mdx b/docs/pt-br/reference/harnesses.mdx index 18f33c03..8cdb365b 100644 --- a/docs/pt-br/reference/harnesses.mdx +++ b/docs/pt-br/reference/harnesses.mdx @@ -4,68 +4,74 @@ description: "Capture sessões e aplique políticas em todos os 12 harnesses de icon: "plug-zap" --- -Um harness é o ambiente no qual seu agente realmente executa. Failproof AI suporta doze deles, em duas categorias: +Um harness é o ambiente em que seu agente realmente executa. O Failproof AI suporta doze deles, em duas categorias: - **CLIs de codificação** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **Gateways de chat e assistentes** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistente auto-hospedado) +- **Gateways de chat e assistente** (2) — Hermes (Slack, Telegram, cron), OpenClaw (assistente auto-hospedado) As mesmas políticas e o mesmo histórico de sessões se aplicam independentemente de qual harness o agente utiliza. Uma camada de adaptador mapeia os nomes de eventos nativos, nomes de ferramentas e campos de entrada de ferramentas de cada harness para 29 eventos canônicos antes que qualquer política seja executada. -Um agente que não utiliza **nenhum** dos doze é instrumentado diretamente com o [SDK Python](/pt-br/reference/custom-agents). Esse é um contrato diferente, e vale dizer claramente: o SDK oferece rastreamento, sessões, avaliações e auditorias — **mas não aplica políticas por conta própria.** Bloquear uma ação insegura antes que ela seja executada requer um hook de enforcement no limite de ferramentas do seu runtime; [entre em contato](mailto:support@befailproof.ai) e iremos mapeá-lo. +Um agente que não roda em **nenhum** dos doze é instrumentado diretamente com o [Python SDK](/pt-br/reference/custom-agents). Esse é um contrato diferente, e vale deixar claro: o SDK fornece rastreamento, sessões, avaliações e auditorias — **ele não aplica políticas por conta própria.** Bloquear uma ação insegura antes de sua execução requer um hook de aplicação no limite de ferramentas do seu runtime; [entre em contato conosco](mailto:support@befailproof.ai) e faremos o mapeamento. | Harness | Escopos de hook suportados | | --- | --- | -| Claude Code | User, project, local | -| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | User, project | -| Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | -| Hermes, OpenClaw | User | +| Claude Code | Usuário, projeto, local | +| Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | Usuário, projeto | +| Factory Droid, Devin CLI, Antigravity CLI, Goose | Usuário, projeto | +| Hermes, OpenClaw | Usuário | -Cada integração normaliza os nomes de eventos de hook nativos, nomes de ferramentas e campos de entrada de ferramentas antes que as políticas sejam executadas. Uma política só pode agir sobre eventos que o harness expõe; teste o comportamento de fim de turno e de instrução no harness e versão exatos que você implanta. +Cada integração normaliza seus nomes de eventos de hook nativos, nomes de ferramentas e campos de entrada de ferramentas antes que as políticas sejam executadas. Uma política só pode agir sobre eventos que o harness expõe; teste o comportamento de fim de turno e de instrução no harness e versão exatos que você vai implantar. -## Capacidade de enforcement +## Capacidade de aplicação "Bloquear" significa que o veredicto retornado pelo adaptador atual é consumido pelo harness indicado. O bloqueio pós-ferramenta pode substituir o resultado exibido ao modelo, mas não pode desfazer um efeito colateral de ferramenta que já ocorreu. -| Harness | Eventos de bloqueio verificados | Ressalvas de observação apenas ou sem bloqueio | +| Harness | Eventos de bloqueio verificados | Ressalvas de observação ou não bloqueantes | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` e vários eventos de task/config | `PostToolUse`, ciclo de vida de sessão, notificações e eventos pós-falha são observacionais. | +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` e vários eventos de tarefa/configuração | `PostToolUse`, ciclo de vida de sessão, notificações e eventos pós-falha são observacionais. | | Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | O bloqueio pós-ferramenta substitui o resultado após a execução; eventos de início de sessão e compactação são observacionais no adaptador atual. | | GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | O bloqueio pós-ferramenta substitui o resultado após a execução; eventos de sessão e notificação são observacionais. | | Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` e eventos de sessão são observacionais. | -| OpenCode | `PreToolUse` | Eventos pós-ferramenta e de ciclo de vida são observacionais; o tratamento de stop atual é uma orientação para um turno posterior, não um gate verificado. | +| OpenCode | `PreToolUse` | Eventos pós-ferramenta e de ciclo de vida são observacionais; o tratamento de stop atual é uma orientação para um turno posterior, e não um gate verificado. | | Pi | `PreToolUse`, `UserPromptSubmit` | Eventos pós-ferramenta e de ciclo de vida são observacionais; a orientação de stop se aplica a um turno posterior. | -| Hermes | `PreToolUse` | Veredictos pós-ferramenta, de sessão e de subagent-stop não são gates. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Eventos pós-ferramenta, de sessão, subagent-stop e compactação são observacionais. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Veredictos pós-ferramenta e subagent-stop são observacionais. | +| Hermes | `PreToolUse` | Um plugin nativo entrega `instruct()` como uma interrupção delimitada e visível ao modelo antes de permitir uma iteração de API posterior. Veredictos pós-ferramenta, de sessão e de subagent-stop não são gates. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Eventos pós-ferramenta, de sessão, de subagent-stop e de compactação são observacionais. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Veredictos pós-ferramenta e de subagent-stop são observacionais. | | Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` condicional | Hooks de permissão não são executados em todos os modos de permissão; eventos pós-ferramenta e de sessão são observacionais. | -| Antigravity CLI | `PreToolUse`, `Stop` | Veredictos de user-prompt e pós-ferramenta são observacionais; instruções de prompt ainda podem ser injetadas. | -| Goose | `PreToolUse` | Eventos de user-prompt, pós-ferramenta e de sessão são observacionais. Existe um hook de stop de bloqueio nativo upstream, mas não é instalado pelo adaptador atual. | +| Antigravity CLI | `PreToolUse`, `Stop` | Veredictos de prompt de usuário e pós-ferramenta são observacionais; instruções de prompt ainda podem ser injetadas. | +| Goose | `PreToolUse` | Eventos de prompt de usuário, pós-ferramenta e de sessão são observacionais. Um hook de stop nativo com bloqueio existe upstream, mas não é instalado pelo adaptador atual. | -As capacidades são sensíveis à versão. Repita os testes após atualizar um CLI de agente, especialmente quando uma política depende de comportamento de prompt, stop, permissão ou pós-ferramenta em vez do gate pré-ferramenta comum. +As capacidades são sensíveis à versão. Repita os testes após atualizar um CLI de agente, especialmente quando uma política depende de comportamento de prompt, stop, permissão ou pós-ferramenta, em vez do gate comum de pré-ferramenta. -## Instalar hooks de captura e políticas +### Plugin nativo do Hermes + +O Hermes é integrado por meio de um plugin nativo local de perfil, em vez de um comando de shell. A instalação copia o plugin em todos os perfis Hermes padrão e nomeados, o habilita no `config.yaml` desse perfil e migra apenas entradas legadas de shell-hook do FailproofAI. Isso evita um spawn de processo a cada hook e permite que `instruct()` alcance o modelo por meio do resultado de ferramenta bloqueada nativo do Hermes. + +A primeira instrução correspondente bloqueia a chamada pendente. A mesma requisição de API permanece bloqueada; uma iteração posterior do modelo pode tentar novamente. Um ledger persistente com escopo de perfil e um limite por turno impedem que uma instrução consultiva se torne um loop ilimitado. `deny()` continua sendo um bloqueio definitivo. Execute `failproofai config --status` para detectar um perfil desabilitado, incompleto, duplicado ou não configurado recentemente. + +## Instalar hooks de captura e de política - 1. Abra **Administration → Keys** e crie uma chave com `events:add` e `policies:pull`, nomeada para a máquina ou ambiente. + 1. Abra **Administração → Chaves** e crie uma chave com `events:add` e `policies:pull`, nomeada para a máquina ou ambiente. 2. Na máquina de destino, conecte o CLI local com a chave exibida e instale os hooks do harness. - 3. Inicie uma nova sessão de agente e confirme seus eventos de hook e sessão em **Observe → Events**. - 4. Abra **Observe → policy** para a mesma janela de tempo e confirme que uma decisão de política está atribuída à máquina. + 3. Inicie uma nova sessão de agente e confirme seus eventos de hook e de sessão em **Observar → Eventos**. + 4. Abra **Observar → política** para a mesma janela de tempo e confirme que uma decisão de política está atribuída à máquina. - A conexão começa com uma chave de máquina. Confirme que ela inclui permissões de ingestão e entrega de políticas antes de copiar o segredo. + A conexão começa com uma chave de máquina. Confirme que ela inclui permissões de ingestão e de entrega de políticas antes de copiar seu secret. ![O drawer de nova chave de API usado para conceder permissões de ingestão de eventos e entrega de políticas.](/images/dashboard/key-create.png) - Após instalar os hooks, o stream de eventos deve mostrar novos eventos da máquina e do ambiente que você conectou. + Após instalar os hooks, o stream de Eventos deve mostrar novos eventos da máquina e do ambiente que você conectou. - ![O stream de eventos ao vivo usado para confirmar que um harness recém-instalado está reportando.](/images/dashboard/events-stream.png) + ![O stream de Eventos ao vivo usado para confirmar que um harness recém-instalado está reportando.](/images/dashboard/events-stream.png) - Por fim, verifique se as decisões de política estão atribuídas à mesma máquina. Isso confirma que o harness está reportando atividade de políticas além dos eventos de rastreamento. + Por fim, verifique se as decisões de política estão atribuídas à mesma máquina. Isso confirma que o harness está reportando atividade de política, além dos eventos de rastreamento. - ![A página de políticas usada para verificar decisões de política de um harness recém-conectado.](/images/dashboard/policy-observe.png) + ![A página de Política usada para verificar decisões de política de um harness recém-conectado.](/images/dashboard/policy-observe.png) - Leia a chave da máquina no shell. `read -s` a solicita em um prompt que não exibe a entrada, portanto ela nunca aparece em um comando ou no histórico do shell: + Leia a chave da máquina no shell. `read -s` a captura em um prompt que não exibe o input, para que ela nunca apareça em um comando ou no histórico do shell: ```bash read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN @@ -88,7 +94,7 @@ As capacidades são sensíveis à versão. Repita os testes após atualizar um C --scope user ``` - O escopo de projeto mantém a configuração de hooks junto ao repositório. O escopo de usuário cobre o trabalho entre repositórios. Claude Code também suporta escopo local; o suporte varia por harness e o CLI rejeita combinações não suportadas. + O escopo de projeto mantém a configuração de hook junto a um repositório. O escopo de usuário cobre o trabalho em múltiplos repositórios. Claude Code também suporta escopo local; o suporte varia por harness e o CLI rejeita combinações não suportadas. Verifique a máquina e seus eventos: @@ -104,9 +110,9 @@ As capacidades são sensíveis à versão. Repita os testes após atualizar um C - Caminhos extras são registrados na máquina, não no Cloud. Após adicionar um, abra **Observe → Sessions**, filtre pelo ambiente da máquina e confirme que as sessões do novo caminho aparecem. Abra uma sessão e verifique o agente, o harness e os timestamps de eventos antes de utilizá-la em uma auditoria. + Caminhos extras são registrados na máquina, não no Cloud. Após adicionar um, abra **Observar → Sessões**, filtre pelo ambiente da máquina e confirme que as sessões do novo caminho aparecem. Abra uma sessão e verifique o agente, o harness e os timestamps de eventos antes de usá-la em uma auditoria. - ![A lista de sessões filtrada pelo ambiente que recebe dados do caminho de captura adicional.](/images/dashboard/sessions-list.png) + ![A lista de Sessões filtrada para o ambiente que recebe dados do caminho de captura adicional.](/images/dashboard/sessions-list.png) Adicione um caminho com um rótulo opcional e inspecione os caminhos configurados: diff --git a/docs/ru/reference/harnesses.mdx b/docs/ru/reference/harnesses.mdx index 26bcb07f..ab295f89 100644 --- a/docs/ru/reference/harnesses.mdx +++ b/docs/ru/reference/harnesses.mdx @@ -1,86 +1,93 @@ --- title: "Адаптеры агентов" -description: "Захватывайте сеансы и применяйте политики на всех 12 поддерживаемых адаптерах агентов." +description: "Захватывайте сеансы и применяйте политики для всех 12 поддерживаемых адаптеров агентов." icon: "plug-zap" --- -Адаптер — это среда, в которой фактически работает ваш агент. Failproof AI поддерживает двенадцать адаптеров в двух категориях: +Адаптер — это среда, в которой фактически работает ваш агент. Failproof AI поддерживает двенадцать адаптеров, разделённых на две категории: - **Кодовые CLI** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **Шлюзы чатов и ассистентов** (2) — Hermes (Slack, Telegram, cron), OpenClaw (самостоятельно размещаемый ассистент) +- **Шлюзы чата и ассистентов** (2) — Hermes (Slack, Telegram, cron), OpenClaw (самостоятельно размещаемый ассистент) -Одни и те же политики и одна и та же история сеанса применяются независимо от того, в каком адаптере работает агент. Один слой адаптера преобразует собственные имена событий, имена инструментов и поля входных данных инструментов каждого адаптера в 29 канонических событий до применения любой политики. +Одни и те же политики и одна и та же история сеанса применяются независимо от того, в каком адаптере работает агент. Один уровень адаптации преобразует названия событий каждого адаптера, названия инструментов и поля входных данных инструментов в 29 канонических событий перед выполнением любой политики. -Агент, работающий **ни в одном** из двенадцати адаптеров, инструментируется непосредственно с помощью [Python SDK](/ru/reference/custom-agents). Это другой контракт, и стоит сказать прямо: SDK обеспечивает трассировку, сеансы, оценки и аудиты — **он не применяет политики самостоятельно.** Для блокировки небезопасного действия перед его выполнением требуется перехватчик применения на границе инструмента вашего времени выполнения; [свяжитесь с нами](mailto:support@befailproof.ai) и мы его реализуем. +Агент, работающий **ни в одном** из двенадцати адаптеров, инструментируется напрямую с помощью [Python SDK](/ru/reference/custom-agents). Это другой контракт, и стоит сказать ясно: SDK предоставляет трассировку, сеансы, оценки и аудиты — **он не применяет политики самостоятельно.** Блокирование небезопасного действия перед его выполнением требует крючка применения на границе инструментов вашего runtime; [свяжитесь с нами](mailto:support@befailproof.ai) и мы его реализуем. -| Адаптер | Поддерживаемые области перехватчиков | +| Адаптер | Поддерживаемые области действия крючков | | --- | --- | | Claude Code | User, project, local | | Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | User, project | | Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | | Hermes, OpenClaw | User | -Каждая интеграция нормализует собственные имена событий перехватчика, имена инструментов и поля входных данных инструментов перед применением политик. Политика может действовать только на события, которые предоставляет адаптер; протестируйте поведение в конце хода и поведение инструкций на точном адаптере и версии, которые вы развертываете. +Каждая интеграция нормализует названия событий крючков адаптера, названия инструментов и поля входных данных инструментов перед выполнением политик. Политика может действовать только на события, которые выкрывает адаптер; протестируйте поведение в конце очереди и инструкции на точном адаптере и версии, которые вы развёртываете. ## Возможности применения -«Блокировка» означает, что решение возвращаемого адаптером потребляется названным адаптером. Блокировка после инструмента может заменить результат, показываемый модели, но не может отменить побочный эффект инструмента, который уже произошел. +"Блокировка" означает, что возвращённый вердикт текущего адаптера использует названный адаптер. Блокирование после инструмента может заменить результат, показанный модели, но не может отменить побочный эффект инструмента, который уже произошёл. -| Адаптер | Проверенные события блокировки | Полностью наблюдательные или не блокирующие замечания | +| Адаптер | Проверенные события блокирования | Наблюдение или неблокирующие оговорки | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` и несколько событий задач/конфигурации | `PostToolUse`, жизненный цикл сеанса, уведомления и события после сбоя являются наблюдательными. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Блокировка после инструмента заменяет результат после выполнения; события начала сеанса и компактирования являются наблюдательными в текущем адаптере. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Блокировка после инструмента заменяет результат после выполнения; события сеанса и уведомления являются наблюдательными. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` и события сеанса являются наблюдательными. | -| OpenCode | `PreToolUse` | События после инструмента и жизненного цикла являются наблюдательными; текущая обработка остановки — это рекомендация для более позднего хода, а не проверенные ворота. | -| Pi | `PreToolUse`, `UserPromptSubmit` | События после инструмента и жизненного цикла являются наблюдательными; рекомендация остановки применяется к более позднему ходу. | -| Hermes | `PreToolUse` | Решения после инструмента, сеанса и остановки подагента не являются воротами. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | События после инструмента, сеанса, остановки подагента и компактирования являются наблюдательными. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Решения после инструмента и остановки подагента являются наблюдательными. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, условный `PermissionRequest` | Перехватчики разрешений работают не во всех режимах разрешений; события после инструмента и сеанса являются наблюдательными. | -| Antigravity CLI | `PreToolUse`, `Stop` | Решения запроса пользователя и после инструмента являются наблюдательными; инструкции запроса все еще можно внедрить. | -| Goose | `PreToolUse` | События запроса пользователя, после инструмента и сеанса являются наблюдательными. Существует родной перехватчик блокирующей остановки выше по течению, но не установлен текущим адаптером. | - -Возможности зависят от версии. Протестируйте снова после обновления CLI агента, особенно когда политика основана на поведении запроса, остановки, разрешения или после инструмента, а не на общих воротах перед инструментом. - -## Установка перехватчиков захвата и политики +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` и несколько событий задач/конфигурации | `PostToolUse`, жизненный цикл сеанса, уведомления и события после сбоя наблюдаются. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Блокирование после инструмента заменяет результат после выполнения; события начала сеанса и компактирования наблюдаются в текущем адаптере. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Блокирование после инструмента заменяет результат после выполнения; события сеанса и уведомления наблюдаются. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` и события сеанса наблюдаются. | +| OpenCode | `PreToolUse` | События после инструмента и жизненного цикла наблюдаются; текущая обработка остановки — это руководство для более позднего хода, а не проверенные ворота. | +| Pi | `PreToolUse`, `UserPromptSubmit` | События после инструмента и жизненного цикла наблюдаются; рекомендация остановки применяется к более позднему ходу. | +| Hermes | `PreToolUse` | Встроенный плагин доставляет `instruct()` как одно ограниченное прерывание, видимое модели, перед разрешением более позднего повтора API. Вердикты после инструмента, сеанса и остановки подагента не являются воротами. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | События после инструмента, сеанса, остановки подагента и компактирования наблюдаются. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Вердикты после инструмента и остановки подагента наблюдаются. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, условный `PermissionRequest` | Крючки разрешения не работают во всех режимах разрешения; события после инструмента и сеанса наблюдаются. | +| Antigravity CLI | `PreToolUse`, `Stop` | Вердикты подсказки пользователя и после инструмента наблюдаются; инструкции подсказки все ещё могут быть внедрены. | +| Goose | `PreToolUse` | События подсказки пользователя, после инструмента и сеанса наблюдаются. Встроенный крючок блокирующей остановки существует выше по потоку, но не установлен текущим адаптером. | + +Возможности зависят от версии. Переоттестируйте после обновления CLI агента, особенно если политика полагается на поведение подсказки, остановки, разрешения или после инструмента, а не на обычные ворота перед инструментом. + +### Встроенный плагин Hermes + +Hermes интегрируется через встроенный плагин, специфичный для профиля, а не через команду оболочки. +Установка копирует плагин в каждый профиль Hermes по умолчанию и именованный, включает его в `config.yaml` профиля и переносит только старые записи оболочки FailproofAI. Это избегает порождения процесса на каждый крючок и позволяет `instruct()` достичь модели через встроенный результат заблокированного инструмента Hermes. + +Первая совпадающая инструкция блокирует ожидающий вызов. Одна и та же запрос API остаётся заблокированным; более позднее повторение модели может повторить попытку. Постоянный реестр, ограниченный профилем, и предел за ход предотвращают превращение консультативной инструкции в неограниченный цикл. `deny()` остаётся жёсткой блокировкой. Запустите `failproofai config --status`, чтобы обнаружить отключённый, неполный, дублированный или недавно переконфигурированный профиль. + +## Установка крючков захвата и политики - - 1. Откройте **Administration → Keys** и создайте ключ с `events:add` и `policies:pull`, названный для машины или окружения. - 2. На целевой машине подключите локальный CLI с отображаемым ключом и установите перехватчики адаптера. - 3. Запустите новый сеанс агента, затем подтвердите его перехватчик и события сеанса в **Observe → Events**. - 4. Откройте **Observe → policy** для того же временного окна и подтвердите, что решение политики принято машиной. + + 1. Откройте **Administration → Keys** и создайте ключ с разрешениями `events:add` и `policies:pull`, названный для машины или окружения. + 2. На целевой машине подключите локальный CLI с отображаемым ключом и установите крючки адаптера. + 3. Начните новый сеанс агента, затем подтвердите его события крючка и сеанса в **Observe → Events**. + 4. Откройте **Observe → policy** для того же временного окна и подтвердите, что решение политики отнесено к машине. - Подключение начинается с ключа машины. Подтвердите, что он включает разрешения на ingestion и delivery политик перед копированием его секрета. + Соединение начинается с ключа машины. Подтвердите, что он включает как разрешения на приём, так и доставку политики, перед копированием его секрета. - ![Новое окно создания ключа API, используемое для предоставления разрешений на ingestion событий и delivery политик.](/images/dashboard/key-create.png) + ![Ящик создания нового ключа API, используемый для предоставления разрешений на приём событий и доставку политики.](/images/dashboard/key-create.png) - После установки перехватчиков поток Events должен показывать новые события с машины и окружения, которое вы подключили. + После установки крючков поток Events должен показывать новые события с машины и окружения, которые вы подключили. - ![Живой поток Events, используемый для подтверждения того, что новый установленный адаптер отправляет отчеты.](/images/dashboard/events-stream.png) + ![Поток live Events, используемый для подтверждения того, что недавно установленный адаптер отправляет данные.](/images/dashboard/events-stream.png) - Наконец, проверьте, что решения политики принимаются той же машиной. Это подтверждает, что адаптер отправляет отчеты как о деятельности политики, так и о событиях трассировки. + Наконец, убедитесь, что решения политики отнесены к той же машине. Это подтверждает, что адаптер отправляет как деятельность политики, так и события трассировки. - ![Страница Policy, используемая для проверки решений политики с недавно подключенного адаптера.](/images/dashboard/policy-observe.png) + ![Страница Policy, используемая для проверки решений политики из недавно подключённого адаптера.](/images/dashboard/policy-observe.png) - Прочитайте ключ машины в оболочку. `read -s` берет его в приглашении, которое не выводится эхом, поэтому он никогда не появляется в команде или в истории оболочки: + Прочитайте ключ машины в оболочку. `read -s` берёт его в подсказке, которая не выводит, поэтому он никогда не появляется в команде или истории оболочки: ```bash read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - Затем настройте машину — это подключит перехватчики для каждого обнаруженного адаптера, установит демон и подключится к Cloud: + Затем настройте машину — это проводит крючки для каждого обнаруженного адаптера, устанавливает демон и подключается к Cloud: ```bash failproofai config failproofai policies add FailproofAI/policies ``` - Настройка не включает никакие политики самостоятельно, поэтому нужна вторая команда. + Установка не включает никакую политику самостоятельно, что является целью второй команды. - Или нацеленно выберите именованные адаптеры и область конфигурации: + Или нацельтесь на названные адаптеры и область действия конфигурации: ```bash failproofai policies --install \ @@ -88,7 +95,7 @@ icon: "plug-zap" --scope user ``` - Область project сохраняет конфигурацию перехватчика с репозиторием. Область user охватывает работу через репозитории. Claude Code также поддерживает область local; поддержка варьируется в зависимости от адаптера и CLI отклоняет неподдерживаемые комбинации. + Область действия проекта сохраняет конфигурацию крючков с репозиторием. Область действия пользователя охватывает работу в разных репозиториях. Claude Code также поддерживает область действия local; поддержка варьируется по адаптерам и CLI отклоняет неподдерживаемые комбинации. Проверьте машину и её события: @@ -100,16 +107,16 @@ icon: "plug-zap" -## Добавьте путь сеанса, не установленный по умолчанию +## Добавьте нестандартный путь сеанса - - Дополнительные пути регистрируются на машине, а не в Cloud. После добавления одного откройте **Observe → Sessions**, отфильтруйте по окружению машины и подтвердите, что сеансы с нового пути отображаются. Откройте сеанс и проверьте агента, адаптер и временные метки событий перед использованием в аудите. + + Дополнительные пути регистрируются на машине, а не в Cloud. После добавления откройте **Observe → Sessions**, отфильтруйте по окружению машины и подтвердите, что сеансы из нового пути появляются. Откройте сеанс и проверьте агента, адаптер и временные метки событий перед использованием в аудите. - ![Список Sessions, отфильтрованный по окружению, получающему данные от дополнительного пути захвата.](/images/dashboard/sessions-list.png) + ![Список Sessions, отфильтрованный по окружению, получающему данные из дополнительного пути захвата.](/images/dashboard/sessions-list.png) - Добавьте путь с необязательной меткой, затем проверьте настроенные пути: + Добавьте путь с опциональной меткой, затем проверьте настроенные пути: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -118,10 +125,10 @@ icon: "plug-zap" failproofai backfill --since 7d ``` - Удалите путь с помощью `failproofai harness remove-path claude checkout`. + Удалите путь с `failproofai harness remove-path claude checkout`. - Запустите один новый сеанс после установки. Проверьте как живой поток событий, так и фактическое решение политики перед расширением развертывания. + Запустите один новый сеанс после установки. Проверьте как live поток событий, так и фактическое решение политики перед расширением развёртывания. \ No newline at end of file diff --git a/docs/tr/reference/harnesses.mdx b/docs/tr/reference/harnesses.mdx index 4105c451..09ac3cb6 100644 --- a/docs/tr/reference/harnesses.mdx +++ b/docs/tr/reference/harnesses.mdx @@ -1,86 +1,99 @@ --- -title: "Agent arayüzleri" -description: "12 desteklenen agent arayüzünde oturumları yakala ve politikaları uygula." +title: "Ajan araçları" +description: "Oturumları yakalayın ve desteklenen 12 ajan aracının tümünde politikaları uygulayın." icon: "plug-zap" --- -Bir arayüz, agendinizin gerçekte içinde çalıştığı ortamdır. Failproof AI bunlardan on ikisini destekler, iki sınıfta: +Araç, ajanınızın gerçekte çalıştığı her şeydir. Failproof AI bunlardan on ikisini destekler ve iki sınıfa ayrılır: - **Kodlama CLI'ları** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **Sohbet ve asistan ağ geçitleri** (2) — Hermes (Slack, Telegram, cron), OpenClaw (kendi barındırılan asistan) +- **Sohbet ve asistan ağ geçitleri** (2) — Hermes (Slack, Telegram, cron), OpenClaw (kendi kendine barındırılan asistan) -Aynı politikalar ve aynı oturum geçmişi, agendin hangi arayüzde çalıştığına bakılmaksızın geçerlidir. Bir adaptör katmanı, her arayüzün yerel olay adlarını, araç adlarını ve araç giriş alanlarını, herhangi bir politika çalışmadan önce 29 kurallı olaya eşler. +Aynı politikalar ve aynı oturum geçmişi, bir ajanın hangi araçta çalıştığından bağımsız olarak geçerlidir. Bir adaptör katmanı, her araçın yerel olay adlarını, araç adlarını ve araç-giriş alanlarını 29 kanonik olayıyla eşler ve herhangi bir politika çalışmadan önce bunu yapar. -On ikinin **hiçbirinde** çalışmayan bir agent, doğrudan [Python SDK](/tr/reference/custom-agents) ile enstrümente edilir. Bu farklı bir sözleşmedir ve açıkça belirtmeye değer: SDK izleme, oturumlar, değerlendirmeler ve denetimler sağlar — **kendi başına politikaları uygulamaz.** Güvensiz bir eylemi yürütülmeden önce engellemek, çalışma zamanınızın araç sınırında bir zorlama kancası gerektirir; [bize ulaşın](mailto:support@befailproof.ai) ve biz bunu eşleriz. +On ikiden **hiçbirinde** çalışmayan bir ajan, [Python SDK](/tr/reference/custom-agents) ile doğrudan araçlanır. Bu farklı bir sözleşmedir ve açıkça ifade etmek değerdir: SDK izleme, oturumlar, değerlendirmeler ve denetimler sağlar — **kendi başına politikaları uygulamaz.** Güvenli olmayan bir eylemi yürütülmeden önce engelleme, çalışma zamanınızın araç sınırında bir uygulama kancası gerektirir; [bizimle iletişime geçin](mailto:support@befailproof.ai) ve bunu eşleştireceğiz. -| Arayüz | Desteklenen kanca kapsamları | +| Araç | Desteklenen kanca kapsamları | | --- | --- | | Claude Code | Kullanıcı, proje, yerel | | Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | Kullanıcı, proje | | Factory Droid, Devin CLI, Antigravity CLI, Goose | Kullanıcı, proje | | Hermes, OpenClaw | Kullanıcı | -Her entegrasyon, politikalar çalışmadan önce yerel kanca olay adlarını, araç adlarını ve araç giriş alanlarını normalleştirir. Bir politika yalnızca arayüzün açığa çıkardığı olaylara göre hareket edebilir; tam olarak dağıttığınız arayüz ve sürüm üzerinde dönem sonu ve talimat davranışını test edin. +Her entegrasyon, politikalar çalışmadan önce yerel kanca olay adlarını, araç adlarını ve araç-giriş alanlarını normalleştirir. Bir politika yalnızca araçın açığa çıkardığı olaylara etki edebilir; dağıttığınız tam araç ve sürümde dönem sonu ve talimat davranışını test edin. -## Zorlama yeteneği +## Uygulama yeteneği -"Engelle" ile kastedilen, mevcut adaptörün döndürülen kararının adlandırılan arayüz tarafından tüketilmesidir. Araç sonrası engelleme, modele gösterilen sonucu değiştirebilir ancak zaten gerçekleşmiş bir araç yan etkisini geri alamaz. +"Engelle" şu anlama gelir: geçerli adaptörün döndürdüğü karar, adlandırılan araç tarafından tüketilir. Araç sonrası engelleme, modele gösterilen sonucu değiştirebilir ancak zaten gerçekleşen bir araç yan etkisini geri alamaz. -| Arayüz | Doğrulanmış engelleme olayları | Yalnızca gözlemli veya engelleme olmayan uyarılar | +| Araç | Doğrulanmış engelleme olayları | Yalnızca gözlem veya engellemeyen uyarılar | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` ve birkaç görev/yapılandırma olayı | `PostToolUse`, oturum yaşam döngüsü, bildirimler ve başarısızlık sonrası olaylar gözlemci niteliğindedir. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Araç sonrası engelleme yürütülmeden sonra sonucu değiştirir; oturum başlangıcı ve kompakt olaylar mevcut adaptörde gözlemci niteliğindedir. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Araç sonrası engelleme yürütülmeden sonra sonucu değiştirir; oturum ve bildirim olayları gözlemci niteliğindedir. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` ve oturum olayları gözlemci niteliğindedir. | -| OpenCode | `PreToolUse` | Araç sonrası ve yaşam döngüsü olayları gözlemci niteliğindedir; mevcut durdurma işlemi doğrulanmış bir kapı yerine daha sonraki bir dönem için rehberliktir. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Araç sonrası ve yaşam döngüsü olayları gözlemci niteliğindedir; durdurma rehberliği daha sonraki bir döneme uygulanır. | -| Hermes | `PreToolUse` | Araç sonrası, oturum ve subagent durdurma kararları kapı değildir. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Araç sonrası, oturum, subagent durdurma ve sıkıştırma olayları gözlemci niteliğindedir. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Araç sonrası ve subagent durdurma kararları gözlemci niteliğindedir. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, koşullu `PermissionRequest` | İzin kankaları her izin modunda çalışmaz; araç sonrası ve oturum olayları gözlemci niteliğindedir. | -| Antigravity CLI | `PreToolUse`, `Stop` | Kullanıcı istemi ve araç sonrası kararlar gözlemci niteliğindedir; komut satırı talimatları yine de enjekte edilebilir. | -| Goose | `PreToolUse` | Kullanıcı istemi, araç sonrası ve oturum olayları gözlemci niteliğindedir. Yerel bir engelleme durdurma kancası hizla mevcuttur ancak mevcut adaptör tarafından yüklenmez. | - -Yetenekler sürüme duyarlıdır. Bir agent CLI'sını yükselttikten sonra yeniden test edin, özellikle bir politika ortak ön araç kapısından ziyade komut satırı, durdurma, izin veya araç sonrası davranışına bağlıysa. - -## Yakalama ve politika kankaları yükleyin +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` ve birkaç görev/yapılandırma olayı | `PostToolUse`, oturum yaşam döngüsü, bildirimler ve başarısızlık sonrası olaylar gözlemseldir. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Araç sonrası engelleme, yürütülmeden sonra sonucu değiştirir; oturum başlatma ve kompakt olaylar geçerli adaptöde gözlemseldir. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Araç sonrası engelleme, yürütülmeden sonra sonucu değiştirir; oturum ve bildirim olayları gözlemseldir. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` ve oturum olayları gözlemseldir. | +| OpenCode | `PreToolUse` | Araç sonrası ve yaşam döngüsü olayları gözlemseldir; geçerli durma işleme, daha sonraki bir dönüş için rehberlik olup doğrulanmış bir kapı değildir. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Araç sonrası ve yaşam döngüsü olayları gözlemseldir; durma rehberliği daha sonraki bir dönüşe uygulanır. | +| Hermes | `PreToolUse` | Yerel bir eklenti, `instruct()` olayını daha sonraki bir API yinelemesine izin vermeden önce sınırlandırılmış, model tarafından görünen bir kesinti olarak sağlar. Araç sonrası, oturum ve alt ajan-durma kararları kapı değildir. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Araç sonrası, oturum, alt ajan-durma ve kompakt olaylar gözlemseldir. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Araç sonrası ve alt ajan-durma kararları gözlemseldir. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, koşullu `PermissionRequest` | İzin kancaları her izin modunda çalışmaz; araç sonrası ve oturum olayları gözlemseldir. | +| Antigravity CLI | `PreToolUse`, `Stop` | Kullanıcı isteği ve araç sonrası kararları gözlemseldir; istem talimatları yine de enjekte edilebilir. | +| Goose | `PreToolUse` | Kullanıcı isteği, araç sonrası ve oturum olayları gözlemseldir. Yerel engelleme durma kancası yukarı akışta bulunur ancak geçerli adaptör tarafından yüklenmez. | + +Yetenekler sürüme duyarlıdır. Bir ajan CLI'sini yükselttikten sonra yeniden test edin, özellikle bir politika yaygın ön araç kapısı yerine istemi, durma, izin veya araç sonrası davranışına dayalı olduğunda. + +### Hermes yerel eklentisi + +Hermes, bir shell komutu yerine profil-yerel yerel bir eklenti aracılığıyla entegre edilir. +Yükleme, eklentiyi her varsayılan ve adlandırılmış Hermes profiline kopyalar, bu profilde etkinleştirir +`config.yaml` ve yalnızca eski FailproofAI shell-kanca girişlerini taşır. Bu, her kancanın işlem başlatmaktan kaçınır ve +`instruct()` modele Hermes'in yerel engellenen araç sonucu aracılığıyla ulaşmasına izin verir. + +İlk eşleşen talimat bekleyen çağrıyı engeller. Aynı API isteği +engellenir kalır; daha sonraki bir model yinelemesi yeniden deneyebilir. Kalıcı, profil kapsamlı bir +defteri ve her dönüş için bir sınır, danışman bir tavsiyenin +sınırsız bir döngü haline gelmesini önler. `deny()` sabit bir blok kalır. Çalıştırın `failproofai config --status` +devre dışı, eksik, yinelenen veya yeni yapılandırılmamış bir profili tespit etmek için. + +## Yakalama ve politika kancalarını yükleyin - - 1. **Yönetim → Anahtarları** açın ve `events:add` ve `policies:pull` izinleriyle, makine veya ortam için adlandırılmış bir anahtar oluşturun. - 2. Hedef makinede, yerel CLI'ı gösterilen anahtarla bağlayın ve arayüz kankaları yükleyin. - 3. Yeni bir agent oturumu başlatın, ardından **Gözlemle → Olaylar** altında kanca ve oturum olaylarını doğrulayın. - 4. Aynı zaman penceresi için **Gözlemle → politika** seçeneğini açın ve bir politika kararının makineye atandığını doğrulayın. + + 1. **Yönetim → Anahtarlar** açın ve `events:add` ve `policies:pull` ile makine veya ortam için adlandırılmış bir anahtar oluşturun. + 2. Hedef makinede, yerel CLI'yi görüntülenen anahtarla bağlayın ve araç kancalarını yükleyin. + 3. Yeni bir ajan oturumu başlatın, ardından **Gözlemle → Olaylar** altında kanca ve oturum olaylarını onaylayın. + 4. Aynı zaman penceresi için **Gözlemle → politika** açın ve bir politika kararı makineye atfedildiğini onaylayın. - Bağlantı bir makine anahtarı ile başlar. Gizli anahtarını kopyalamadan önce hem içe alma hem de politika teslimi izinlerini içerdiğini doğrulayın. + Bağlantı bir makine anahtarı ile başlar. Gizliliğini kopyalamadan önce hem alma hem de politika sunumu izinlerini içerdiğini onaylayın. - ![Olay içe alma ve politika teslimi izinleri vermek için kullanılan yeni API anahtar çekme kutusu.](/images/dashboard/key-create.png) + ![Olay alımı ve politika sunumu izinleri vermek için kullanılan yeni API anahtar çekmecesi.](/images/dashboard/key-create.png) - Kankaları yükledikten sonra, Olaylar akışı bağladığınız makineden ve ortamdan yeni olayları göstermelidir. + Kancaları yükledikten sonra, Olaylar akışı bağladığınız makineden ve ortamdan yeni olayları göstermelidir. - ![Yeni yüklenen bir arayüzün raporlama yapması gerektiğini doğrulamak için kullanılan canlı Olaylar akışı.](/images/dashboard/events-stream.png) + ![Yeni yüklenen bir aracın rapor ettiğini onaylamak için kullanılan canlı Olaylar akışı.](/images/dashboard/events-stream.png) - Son olarak, politika kararlarının aynı makineye atandığını doğrulayın. Bu, arayüzün politika etkinliğinin yanı sıra izleme olaylarını da raporlama yapması gerektiğini doğrular. + Son olarak, politika kararlarının aynı makineye atfedildiğini doğrulayın. Bu, aracının izleme olaylarının yanı sıra politika etkinliğini de rapor ettiğini onaylar. - ![Yeni bağlanan bir arayüzden politika kararlarını doğrulamak için kullanılan Politika sayfası.](/images/dashboard/policy-observe.png) + ![Yeni bağlı bir araçtan politika kararlarını doğrulamak için kullanılan Politika sayfası.](/images/dashboard/policy-observe.png) - Makine anahtarını kabuğa okuyun. `read -s`, onu yankılamayan bir istemde alır, böylece hiçbir zaman bir komutta veya kabuk geçmişinde görünmez: + Makine anahtarını kabuk içine okuyun. `read -s` bunu yankı yapmayan bir isteme alır, bu nedenle hiçbir zaman bir komutta veya kabuk geçmişinde görünmez: ```bash read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - Ardından makineyi ayarlayın — bu, tespit edilen her arayüz için kankaları bağlar, daemonu yükler ve Buluta bağlanır: + Ardından makineyi kurun — bu her algılanan araç için kancaları bağlar, daemon'u yükler ve Cloud'a bağlanır: ```bash failproofai config failproofai policies add FailproofAI/policies ``` - Kurulum kendi başına hiçbir politikayı etkinleştirmez, bu ikinci komutun amacı budur. + Kurulum kendi başına politika sağlamaz, ikinci komut bunu yapar. - Veya adlandırılmış arayüzleri ve yapılandırma kapsamını hedefleyin: + Veya adlandırılmış araçları ve bir yapılandırma kapsamını hedefleyin: ```bash failproofai policies --install \ @@ -88,7 +101,7 @@ Yetenekler sürüme duyarlıdır. Bir agent CLI'sını yükselttikten sonra yeni --scope user ``` - Proje kapsamı, kanca yapılandırmasını bir depoda tutar. Kullanıcı kapsamı depolar arasında çalışmayı kapsar. Claude Code ayrıca yerel kapsamı destekler; destek arayüze göre değişir ve CLI desteklenmeyen kombinasyonları reddeder. + Proje kapsamı, kanca yapılandırmasını bir depo ile tutar. Kullanıcı kapsamı depolardaki işi kapsar. Claude Code yerel kapsamı da destekler; destek araçlara göre değişir ve CLI desteklenmeyen kombinasyonları reddeder. Makineyi ve olaylarını doğrulayın: @@ -103,13 +116,13 @@ Yetenekler sürüme duyarlıdır. Bir agent CLI'sını yükselttikten sonra yeni ## Varsayılan olmayan bir oturum yolu ekleyin - - Ekstra yollar makinede kaydedilir, Bulutta değil. Bir tane ekledikten sonra **Gözlemle → Oturumlar** seçeneğini açın, makine ortamına göre filtreleyin ve yeni yoldan oturumlar göründüğünü doğrulayın. Bir oturumu açın ve denetimde buna güvenmeden önce agent, arayüz ve olay zaman damgalarını kontrol edin. + + Fazladan yollar makinede kaydedilir, Cloud'da değil. Bir tane ekledikten sonra, **Gözlemle → Oturumlar** açın, ortamı makinenin ortamına filtreleyin ve yeni yoldan oturumlar görüntülendiğini onaylayın. Bir oturumu açın ve denetimde buna güvenmeden önce ajanı, aracı ve olay zaman damgalarını kontrol edin. ![Ek yakalama yolundan veri alan ortama filtrelenen Oturumlar listesi.](/images/dashboard/sessions-list.png) - İsteğe bağlı bir etiketle bir yol ekleyin, ardından yapılandırılmış yolları inceleyin: + İsteğe bağlı bir etiket ile bir yol ekleyin, ardından yapılandırılmış yolları inceleyin: ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -118,10 +131,10 @@ Yetenekler sürüme duyarlıdır. Bir agent CLI'sını yükselttikten sonra yeni failproofai backfill --since 7d ``` - `failproofai harness remove-path claude checkout` komutuyla bir yolu kaldırın. + `failproofai harness remove-path claude checkout` ile bir yolu kaldırın. - Kurulumdan sonra bir yeni oturum çalıştırın. Dağıtımı genişletmeden önce hem canlı olay akışını hem de gerçek bir politika kararını doğrulayın. + Yüklemeden sonra bir yeni oturum çalıştırın. Dağıtımı genişletmeden önce hem canlı olay akışını hem de gerçek bir politika kararını doğrulayın. \ No newline at end of file diff --git a/docs/vi/reference/harnesses.mdx b/docs/vi/reference/harnesses.mdx index bffd487a..e3da79fc 100644 --- a/docs/vi/reference/harnesses.mdx +++ b/docs/vi/reference/harnesses.mdx @@ -1,86 +1,92 @@ --- -title: "Điểm kết nối agent" -description: "Ghi lại phiên làm việc và thực thi chính sách trên tất cả 12 điểm kết nối agent được hỗ trợ." +title: "Agent harnesses" +description: "Capture sessions and enforce policies across all 12 supported agent harnesses." icon: "plug-zap" --- -Điểm kết nối là bất cứ nơi nào agent của bạn thực sự chạy. Failproof AI hỗ trợ mười hai điểm kết nối, được chia thành hai loại: +Harness là bất cứ thứ gì mà agent của bạn thực sự chạy bên trong đó. Failproof AI hỗ trợ mười hai harness, được chia thành hai loại: -- **CLI Coding** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose -- **Chat và cổng assistant** (2) — Hermes (Slack, Telegram, cron), OpenClaw (self-hosted assistant) +- **Coding CLIs** (10) — Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi, Factory Droid, Devin CLI, Antigravity CLI, Goose +- **Chat and assistant gateways** (2) — Hermes (Slack, Telegram, cron), OpenClaw (self-hosted assistant) -Cùng một chính sách và lịch sử phiên làm việc tương tự được áp dụng bất kể agent chạy trong điểm kết nối nào. Một lớp adapter ánh xạ từng tên sự kiện gốc, tên công cụ và trường đầu vào của công cụ của mỗi điểm kết nối thành 29 sự kiện chính tắc trước khi bất kỳ chính sách nào chạy. +Các chính sách và lịch sử phiên làm việc giống nhau áp dụng cho bất kỳ harness nào mà agent chạy trong đó. Một lớp adapter xây dựng lại các tên sự kiện, tên công cụ và trường đầu vào công cụ của mỗi harness thành 29 sự kiện chuẩn trước khi bất kỳ chính sách nào chạy. -Một agent chạy trong **không** điểm kết nối nào trong mười hai sẽ được theo dõi trực tiếp bằng [Python SDK](/vi/reference/custom-agents). Đó là một hợp đồng khác, và cần nói rõ ràng: SDK cung cấp tracing, phiên làm việc, đánh giá và kiểm toán — **nó không tự thực thi chính sách.** Chặn một hành động không an toàn trước khi nó thực thi cần một hook thực thi ở ranh giới công cụ của runtime của bạn; [liên hệ với chúng tôi](mailto:support@befailproof.ai) và chúng tôi sẽ ánh xạ nó. +Một agent chạy trong **không** harness nào trong mười hai harness sẽ được hỗ trợ trực tiếp bằng [Python SDK](/vi/reference/custom-agents). Đây là một hợp đồng khác, và đáng để phát biểu rõ ràng: SDK cung cấp tracing, sessions, evaluations và audits — **nó không tự thực hiện việc enforce policies.** Chặn một hành động không an toàn trước khi thực thi cần một enforcement hook ở ranh giới công cụ của runtime của bạn; [liên hệ với chúng tôi](mailto:support@befailproof.ai) và chúng tôi sẽ xây dựng lại nó. -| Điểm kết nối | Phạm vi hook được hỗ trợ | +| Harness | Supported hook scopes | | --- | --- | | Claude Code | User, project, local | | Codex, GitHub Copilot CLI, Cursor, OpenCode, Pi | User, project | | Factory Droid, Devin CLI, Antigravity CLI, Goose | User, project | | Hermes, OpenClaw | User | -Mỗi tích hợp chuẩn hóa tên sự kiện hook gốc, tên công cụ và trường đầu vào của công cụ trước khi chính sách chạy. Một chính sách chỉ có thể hoạt động trên các sự kiện mà điểm kết nối công khai; kiểm tra hành vi cuối lượt và hướng dẫn trên điểm kết nối và phiên bản chính xác mà bạn triển khai. +Mỗi tích hợp chuẩn hóa các tên sự kiện hook, tên công cụ và trường đầu vào công cụ của nó trước khi các chính sách chạy. Một chính sách chỉ có thể hoạt động trên các sự kiện mà harness để lộ; kiểm tra hành vi end-of-turn và instruction trên harness và phiên bản chính xác mà bạn triển khai. -## Khả năng thực thi +## Enforcement capability -"Block" có nghĩa là phán quyết được trả về của adapter hiện tại được điểm kết nối đã đặt tên sử dụng. Chặn sau công cụ có thể thay thế kết quả được hiển thị cho model nhưng không thể hoàn tác hiệu ứng phụ của công cụ đã xảy ra. +"Block" có nghĩa là verdict được trả về bởi adapter hiện tại được harness được đặt tên tiêu thụ. Chặn post-tool có thể thay thế kết quả được hiển thị cho mô hình nhưng không thể hoàn tác một tác dụng phụ của công cụ đã xảy ra. -| Điểm kết nối | Sự kiện chặn được xác minh | Cảnh báo chỉ quan sát hoặc không chặn | +| Harness | Verified blocking events | Observe-only or non-blocking caveats | | --- | --- | --- | -| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact` và một số sự kiện task/config | `PostToolUse`, vòng đời phiên, thông báo và sự kiện hậu lỗi chỉ là quan sát. | -| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Chặn sau công cụ thay thế kết quả sau khi thực thi; sự kiện bắt đầu phiên và compact chỉ được quan sát trong adapter hiện tại. | -| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Chặn sau công cụ thay thế kết quả sau khi thực thi; sự kiện phiên và thông báo chỉ được quan sát. | -| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` và sự kiện phiên chỉ được quan sát. | -| OpenCode | `PreToolUse` | Sự kiện sau công cụ và vòng đời chỉ được quan sát; xử lý stop hiện tại là hướng dẫn cho lượt sau hơn là một cổng được xác minh. | -| Pi | `PreToolUse`, `UserPromptSubmit` | Sự kiện sau công cụ và vòng đời chỉ được quan sát; hướng dẫn stop áp dụng cho lượt sau. | -| Hermes | `PreToolUse` | Phán quyết sau công cụ, phiên và subagent-stop không phải là cổng. | -| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Sự kiện sau công cụ, phiên, subagent-stop và compaction chỉ được quan sát. | -| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Phán quyết sau công cụ và subagent-stop chỉ được quan sát. | -| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PermissionRequest` có điều kiện | Hook quyền không chạy trong mọi chế độ quyền; sự kiện sau công cụ và phiên chỉ được quan sát. | -| Antigravity CLI | `PreToolUse`, `Stop` | Phán quyết lời nhắc user và sau công cụ chỉ được quan sát; hướng dẫn lời nhắc vẫn có thể được tiêm. | -| Goose | `PreToolUse` | Sự kiện lời nhắc user, sau công cụ và phiên chỉ được quan sát. Một hook stop chặn gốc tồn tại ở thượng nguồn nhưng không được cài đặt bởi adapter hiện tại. | - -Khả năng nhạy cảm với phiên bản. Kiểm tra lại sau khi nâng cấp CLI agent, đặc biệt khi một chính sách dựa vào hành vi lời nhắc, stop, quyền hoặc sau công cụ hơn là cổng pre-tool thông thường. - -## Cài đặt hook ghi lại và chính sách +| Claude Code | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PreCompact`, and several task/config events | `PostToolUse`, session lifecycle, notifications, and post-failure events are observational. | +| Codex | `PreToolUse`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PostToolUse` | Post-tool blocking replaces the result after execution; session-start and compact events are observational in the current adapter. | +| GitHub Copilot CLI | `PreToolUse`, `UserPromptSubmit`, `PermissionRequest`, `Stop`, `SubagentStop`, `PostToolUse` | Post-tool blocking replaces the result after execution; session and notification events are observational. | +| Cursor | `PreToolUse`, `UserPromptSubmit`, `Stop` | `PostToolUse` and session events are observational. | +| OpenCode | `PreToolUse` | Post-tool and lifecycle events are observational; current stop handling is guidance for a later turn rather than a verified gate. | +| Pi | `PreToolUse`, `UserPromptSubmit` | Post-tool and lifecycle events are observational; stop guidance applies to a later turn. | +| Hermes | `PreToolUse` | A native plugin delivers `instruct()` as one bounded, model-visible interruption before permitting a later API iteration. Post-tool, session, and subagent-stop verdicts are not gates. | +| OpenClaw | `PreToolUse`, `UserPromptSubmit`, `Stop` | Post-tool, session, subagent-stop, and compaction events are observational. | +| Factory Droid | `PreToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact` | Post-tool and subagent-stop verdicts are observational. | +| Devin CLI | `PreToolUse`, `UserPromptSubmit`, `Stop`, conditional `PermissionRequest` | Permission hooks do not run in every permission mode; post-tool and session events are observational. | +| Antigravity CLI | `PreToolUse`, `Stop` | User-prompt and post-tool verdicts are observational; prompt instructions can still be injected. | +| Goose | `PreToolUse` | User-prompt, post-tool, and session events are observational. A native blocking stop hook exists upstream but is not installed by the current adapter. | + +Khả năng phụ thuộc vào phiên bản. Kiểm tra lại sau khi nâng cấp một CLI của agent, đặc biệt khi một chính sách dựa vào hành vi prompt, stop, permission hoặc post-tool thay vì gate pre-tool phổ biến. + +### Hermes native plugin + +Hermes được tích hợp thông qua một native plugin cục bộ theo hồ sơ thay vì một lệnh shell. Installation sao chép plugin vào mỗi hồ sơ Hermes mặc định và được đặt tên, cho phép nó trong `config.yaml` của hồ sơ đó, và chỉ di chuyển các mục hook shell FailproofAI cũ. Điều này tránh được việc spawn process trên mỗi hook và cho phép `instruct()` tiếp cận mô hình thông qua kết quả blocked-tool native của Hermes. + +Chỉ thị phù hợp đầu tiên sẽ chặn lệnh gọi đang chờ xử lý. Yêu cầu API giống nhau vẫn bị chặn; một lần lặp lại mô hình sau có thể thử lại. Một sổ cấp hồ sơ lâu dài và một lỗi trên mỗi lượt ngăn chặn một hướng dẫn tư vấn trở thành một vòng lặp không giới hạn. `deny()` vẫn là một hard block. Chạy `failproofai config --status` để phát hiện một hồ sơ bị tắt, không hoàn chỉnh, bị trùng lặp hoặc mới được cấu hình lại. + +## Install capture and policy hooks - 1. Mở **Administration → Keys** và tạo một khóa có `events:add` và `policies:pull`, được đặt tên cho máy hoặc môi trường. - 2. Trên máy đích, kết nối CLI cục bộ với khóa được hiển thị và cài đặt hook điểm kết nối. - 3. Bắt đầu một phiên agent mới, sau đó xác nhận sự kiện hook và phiên của nó trong **Observe → Events**. - 4. Mở **Observe → policy** cho cửa sổ thời gian tương tự và xác nhận quyết định chính sách được gán cho máy. + 1. Mở **Administration → Keys** và tạo một khóa với `events:add` và `policies:pull`, được đặt tên cho máy hoặc môi trường. + 2. Trên máy đích, kết nối CLI cục bộ với khóa được hiển thị và cài đặt các hook harness. + 3. Bắt đầu một phiên agent mới, sau đó xác nhận các sự kiện hook và session của nó dưới **Observe → Events**. + 4. Mở **Observe → policy** cho cùng một cửa sổ thời gian và xác nhận một quyết định chính sách được gán cho máy. - Kết nối bắt đầu với một khóa máy. Xác nhận rằng nó bao gồm cả quyền tiêu thụ và cung cấp chính sách trước khi sao chép bí mật của nó. + Kết nối bắt đầu bằng một machine key. Xác nhận rằng nó bao gồm cả quyền ingestion và policy-delivery trước khi sao chép secret của nó. - ![Ngăn tạo khóa API mới được sử dụng để cấp quyền tiêu thụ sự kiện và cung cấp chính sách.](/images/dashboard/key-create.png) + ![The new API key drawer used to grant event ingestion and policy delivery permissions.](/images/dashboard/key-create.png) - Sau khi cài đặt hook, luồng Events sẽ hiển thị các sự kiện mới từ máy và môi trường bạn kết nối. + Sau khi cài đặt các hook, stream Events sẽ hiển thị các sự kiện mới từ máy và môi trường bạn đã kết nối. - ![Luồng Events trực tiếp được sử dụng để xác nhận một điểm kết nối mới được cài đặt đang báo cáo.](/images/dashboard/events-stream.png) + ![The live Events stream used to confirm a newly installed harness is reporting.](/images/dashboard/events-stream.png) - Cuối cùng, xác minh rằng quyết định chính sách được gán cho cùng một máy. Điều này xác nhận rằng điểm kết nối đang báo cáo hoạt động chính sách cũng như sự kiện trace. + Cuối cùng, xác minh rằng các quyết định chính sách được gán cho cùng một máy. Điều này xác nhận rằng harness đang báo cáo hoạt động chính sách cũng như trace events. - ![Trang Policy được sử dụng để xác minh quyết định chính sách từ một điểm kết nối mới được kết nối.](/images/dashboard/policy-observe.png) + ![The Policy page used to verify policy decisions from a newly connected harness.](/images/dashboard/policy-observe.png) - Đọc khóa máy vào shell. `read -s` lấy nó ở một dấu nhắc không kéo theo, vì vậy nó không bao giờ xuất hiện trong một lệnh hoặc lịch sử shell: + Đọc machine key vào shell. `read -s` sẽ nhận nó ở một prompt mà không hiển thị, vì vậy nó không bao giờ xuất hiện trong lệnh hoặc trong lịch sử shell: ```bash read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN ``` - Sau đó thiết lập máy — điều này tạo hook cho mọi điểm kết nối được phát hiện, cài đặt daemon và kết nối đến Cloud: + Sau đó thiết lập máy — điều này kết nối các hook cho mọi harness được phát hiện, cài đặt daemon và kết nối với Cloud: ```bash failproofai config failproofai policies add FailproofAI/policies ``` - Thiết lập không kích hoạt bất kỳ chính sách nào, đó là lý do tại sao lệnh thứ hai tồn tại. + Setup không cho phép chính sách nào của nó riêng, đó là lý do tại sao lệnh thứ hai tồn tại. - Hoặc nhắm mục tiêu các điểm kết nối được đặt tên và phạm vi cấu hình: + Hoặc nhắm mục tiêu các harness được đặt tên và một phạm vi cấu hình: ```bash failproofai policies --install \ @@ -88,9 +94,9 @@ Khả năng nhạy cảm với phiên bản. Kiểm tra lại sau khi nâng cấ --scope user ``` - Phạm vi project giữ cấu hình hook với một repository. Phạm vi user bao gồm công việc trên các repository. Claude Code cũng hỗ trợ phạm vi local; hỗ trợ khác nhau tùy theo điểm kết nối và CLI từ chối các kết hợp không được hỗ trợ. + Project scope giữ cấu hình hook với một repository. User scope bao quát công việc trên các repository. Claude Code cũng hỗ trợ local scope; hỗ trợ khác nhau theo harness và CLI từ chối các kết hợp không được hỗ trợ. - Xác minh máy và sự kiện của nó: + Xác minh máy và các sự kiện của nó: ```bash failproofai config --status @@ -100,13 +106,13 @@ Khả năng nhạy cảm với phiên bản. Kiểm tra lại sau khi nâng cấ -## Thêm đường dẫn phiên không mặc định +## Add a non-default session path - Các đường dẫn bổ sung được đăng ký trên máy, không phải trong Cloud. Sau khi thêm một đường dẫn, mở **Observe → Sessions**, lọc theo môi trường của máy và xác nhận các phiên từ đường dẫn mới xuất hiện. Mở một phiên và kiểm tra agent, điểm kết nối và dấu thời gian sự kiện trước khi sử dụng nó trong kiểm toán. + Các đường dẫn bổ sung được đăng ký trên máy, không phải trong Cloud. Sau khi thêm một đường dẫn, mở **Observe → Sessions**, lọc theo môi trường của máy và xác nhận các phiên từ đường dẫn mới xuất hiện. Mở một phiên và kiểm tra agent, harness và các dấu thời gian sự kiện trước khi dựa vào nó trong một audit. - ![Danh sách Sessions được lọc theo môi trường nhận dữ liệu từ đường dẫn ghi lại bổ sung.](/images/dashboard/sessions-list.png) + ![The Sessions list filtered to the environment receiving data from the additional capture path.](/images/dashboard/sessions-list.png) Thêm một đường dẫn với một nhãn tùy chọn, sau đó kiểm tra các đường dẫn được cấu hình: @@ -123,5 +129,5 @@ Khả năng nhạy cảm với phiên bản. Kiểm tra lại sau khi nâng cấ - Chạy một phiên mới sau khi cài đặt. Xác minh cả luồng sự kiện trực tiếp và quyết định chính sách thực tế trước khi mở rộng phân phối. + Chạy một phiên mới sau khi cài đặt. Xác minh cả stream sự kiện trực tiếp và một quyết định chính sách thực tế trước khi mở rộng rollout. \ No newline at end of file diff --git a/docs/zh/reference/harnesses.mdx b/docs/zh/reference/harnesses.mdx index 96ca6858..b2ef6ec5 100644 --- a/docs/zh/reference/harnesses.mdx +++ b/docs/zh/reference/harnesses.mdx @@ -1,17 +1,17 @@ --- -title: "Agent Harness" -description: "跨所有 12 个支持的 agent harness 捕获会话并执行策略。" +title: "Agent harnesses" +description: "捕获会话并在所有 12 个受支持的 agent harness 上执行策略。" icon: "plug-zap" --- -Harness 是你的 agent 实际运行的环境。Failproof AI 支持其中十二种，分为两类： +harness 是指你的 agent 实际运行所在的环境。Failproof AI 支持十二种，分为两类： -- **编程 CLI**（10 种）—— Claude Code、Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi、Factory Droid、Devin CLI、Antigravity CLI、Goose -- **对话与助手网关**（2 种）—— Hermes（Slack、Telegram、cron）、OpenClaw（自托管助手） +- **编码 CLI**（10 种）—— Claude Code、Codex、GitHub Copilot CLI、Cursor、OpenCode、Pi、Factory Droid、Devin CLI、Antigravity CLI、Goose +- **聊天与助手网关**（2 种）—— Hermes（Slack、Telegram、cron）、OpenClaw（自托管助手） -无论 agent 运行在哪个 harness 中，同一套策略和同一份会话历史均适用。一个适配器层会在任何策略执行之前，将每个 harness 的原生事件名称、工具名称和工具输入字段映射到 29 个标准化事件上。 +无论 agent 在哪个 harness 中运行，策略和会话历史记录均保持一致。一个适配器层会在策略执行之前，将每个 harness 的原生事件名称、工具名称和工具输入字段映射到 29 个标准事件上。 -如果 agent 不在上述十二种 harness 中运行，则需直接使用 [Python SDK](/zh/reference/custom-agents) 进行插桩。这是一份不同的契约，有必要明确说明：SDK 提供追踪、会话、评估和审计功能——**它本身并不执行策略。** 在不安全操作执行之前将其拦截，需要在你的运行时工具边界处设置执行钩子；请[联系我们](mailto:support@befailproof.ai)，我们将为你完成映射。 +如果 agent 不在上述十二种 harness 中运行，则需直接通过 [Python SDK](/zh/reference/custom-agents) 进行埋点。这是一种不同的契约，值得明确说明：SDK 提供追踪、会话、评估和审计功能，**但本身不执行策略。** 若要在不安全操作执行前将其拦截，需要在运行时的工具边界处设置执行钩子；请[联系我们](mailto:support@befailproof.ai)，我们将为你完成映射。 | Harness | 支持的钩子作用域 | | --- | --- | @@ -20,52 +20,58 @@ Harness 是你的 agent 实际运行的环境。Failproof AI 支持其中十二 | Factory Droid、Devin CLI、Antigravity CLI、Goose | User、project | | Hermes、OpenClaw | User | -每个集成会在策略执行之前对其原生钩子事件名称、工具名称和工具输入字段进行标准化处理。策略只能对该 harness 所暴露的事件起作用；请在你实际部署的 harness 及其版本上测试轮次结束和指令行为。 +每个集成在策略运行之前都会对其原生钩子事件名称、工具名称和工具输入字段进行规范化处理。策略只能作用于 harness 暴露的事件；请在你实际部署的 harness 及其版本上测试轮末和指令行为。 ## 执行能力 -"拦截"是指当前适配器返回的裁决由指定 harness 消费。工具执行后的拦截可能会替换模型所看到的结果，但无法撤销已经发生的工具副作用。 +"拦截"表示当前适配器返回的裁决由指定 harness 消费。工具后拦截可能会替换展示给模型的结果，但无法撤销已发生的工具副作用。 -| Harness | 已验证的拦截事件 | 仅观测或非拦截说明 | +| Harness | 已验证的拦截事件 | 仅观测或不可拦截的说明 | | --- | --- | --- | -| Claude Code | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PreCompact` 以及若干任务/配置事件 | `PostToolUse`、会话生命周期、通知及失败后事件仅供观测。 | -| Codex | `PreToolUse`、`PermissionRequest`、`UserPromptSubmit`、`Stop`、`SubagentStop`、`PostToolUse` | 工具执行后的拦截会在执行完成后替换结果；会话启动和压缩事件在当前适配器中仅供观测。 | -| GitHub Copilot CLI | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PostToolUse` | 工具执行后的拦截会在执行完成后替换结果；会话和通知事件仅供观测。 | -| Cursor | `PreToolUse`、`UserPromptSubmit`、`Stop` | `PostToolUse` 和会话事件仅供观测。 | -| OpenCode | `PreToolUse` | 工具后和生命周期事件仅供观测；当前的停止处理是对后续轮次的引导，而非已验证的拦截门。 | -| Pi | `PreToolUse`、`UserPromptSubmit` | 工具后和生命周期事件仅供观测；停止引导作用于后续轮次。 | -| Hermes | `PreToolUse` | 工具后、会话和子 agent 停止的裁决不构成拦截门。 | -| OpenClaw | `PreToolUse`、`UserPromptSubmit`、`Stop` | 工具后、会话、子 agent 停止和压缩事件仅供观测。 | -| Factory Droid | `PreToolUse`、`UserPromptSubmit`、`Stop`、`PreCompact` | 工具后和子 agent 停止的裁决仅供观测。 | -| Devin CLI | `PreToolUse`、`UserPromptSubmit`、`Stop`、条件性 `PermissionRequest` | 权限钩子并非在所有权限模式下都会运行；工具后和会话事件仅供观测。 | -| Antigravity CLI | `PreToolUse`、`Stop` | 用户提示和工具后的裁决仅供观测；仍可注入提示指令。 | -| Goose | `PreToolUse` | 用户提示、工具后和会话事件仅供观测。上游存在原生拦截停止钩子，但当前适配器未安装。 | - -各项能力对版本敏感。升级 agent CLI 后请重新测试，尤其是当策略依赖提示、停止、权限或工具后行为而非通用的工具前拦截门时。 +| Claude Code | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PreCompact` 及若干任务/配置事件 | `PostToolUse`、会话生命周期、通知和故障后事件均为观测性。 | +| Codex | `PreToolUse`、`PermissionRequest`、`UserPromptSubmit`、`Stop`、`SubagentStop`、`PostToolUse` | 工具后拦截在执行后替换结果；会话启动和压缩事件在当前适配器中为观测性。 | +| GitHub Copilot CLI | `PreToolUse`、`UserPromptSubmit`、`PermissionRequest`、`Stop`、`SubagentStop`、`PostToolUse` | 工具后拦截在执行后替换结果；会话和通知事件为观测性。 | +| Cursor | `PreToolUse`、`UserPromptSubmit`、`Stop` | `PostToolUse` 和会话事件为观测性。 | +| OpenCode | `PreToolUse` | 工具后和生命周期事件为观测性；当前的停止处理是对后续轮次的引导，而非已验证的门控。 | +| Pi | `PreToolUse`、`UserPromptSubmit` | 工具后和生命周期事件为观测性；停止引导适用于后续轮次。 | +| Hermes | `PreToolUse` | 原生插件在允许后续 API 迭代之前，以一次有界的、模型可见的中断形式传递 `instruct()`。工具后、会话和 subagent-stop 裁决不作为门控。 | +| OpenClaw | `PreToolUse`、`UserPromptSubmit`、`Stop` | 工具后、会话、subagent-stop 和压缩事件为观测性。 | +| Factory Droid | `PreToolUse`、`UserPromptSubmit`、`Stop`、`PreCompact` | 工具后和 subagent-stop 裁决为观测性。 | +| Devin CLI | `PreToolUse`、`UserPromptSubmit`、`Stop`、条件性 `PermissionRequest` | 权限钩子并非在所有权限模式下都运行；工具后和会话事件为观测性。 | +| Antigravity CLI | `PreToolUse`、`Stop` | 用户提示和工具后裁决为观测性；仍可注入提示指令。 | +| Goose | `PreToolUse` | 用户提示、工具后和会话事件为观测性。上游存在原生的阻塞性停止钩子，但当前适配器未安装。 | + +能力与版本相关。升级 agent CLI 后请重新测试，尤其是当策略依赖提示、停止、权限或工具后行为而非通用的工具前门控时。 + +### Hermes 原生插件 + +Hermes 通过 profile 本地原生插件而非 shell 命令集成。安装过程会将插件复制到每个默认和具名 Hermes profile 中，在该 profile 的 `config.yaml` 中启用它，并仅迁移遗留的 FailproofAI shell 钩子条目。这样可以避免每次钩子触发时产生进程开销，并让 `instruct()` 通过 Hermes 的原生阻塞工具结果传达给模型。 + +第一个匹配的指令会阻止待处理的调用。同一个 API 请求保持阻塞状态；后续模型迭代可能会重试。一个持久化的、profile 级别的账本和每轮次上限可防止建议性指令演变为无限循环。`deny()` 仍为硬性拦截。运行 `failproofai config --status` 可检测已禁用、不完整、重复或新增的未配置 profile。 ## 安装捕获和策略钩子 - - 1. 打开**管理 → 密钥**，创建一个具有 `events:add` 和 `policies:pull` 权限的密钥，并以机器或环境命名。 - 2. 在目标机器上，使用显示的密钥连接本地 CLI，并安装 harness 钩子。 - 3. 启动一个新的 agent 会话，然后在**观测 → 事件**下确认其钩子和会话事件。 - 4. 打开相同时间窗口的**观测 → 策略**，确认某条策略决策已归属到该机器。 + + 1. 打开 **Administration → Keys**，创建一个具有 `events:add` 和 `policies:pull` 权限的密钥，并以机器或环境命名。 + 2. 在目标机器上，使用显示的密钥连接本地 CLI 并安装 harness 钩子。 + 3. 启动一个新的 agent 会话，然后在 **Observe → Events** 下确认其钩子和会话事件。 + 4. 打开同一时间窗口下的 **Observe → policy**，确认策略决策已归因于该机器。 - 连接从机器密钥开始。在复制其密钥之前，请确认它包含摄取和策略分发两项权限。 + 连接从机器密钥开始。在复制其 secret 之前，请确认它同时包含数据采集和策略分发权限。 - ![用于授予事件摄取和策略分发权限的新 API 密钥抽屉。](/images/dashboard/key-create.png) + ![用于授予事件采集和策略分发权限的新 API 密钥抽屉。](/images/dashboard/key-create.png) - 安装钩子后，事件流应显示来自你所连接的机器和环境的新事件。 + 安装钩子后，Events 流应显示来自你所连接机器和环境的新事件。 - ![用于确认新安装的 harness 正在上报数据的实时事件流。](/images/dashboard/events-stream.png) + ![用于确认新安装的 harness 正在上报数据的实时 Events 流。](/images/dashboard/events-stream.png) - 最后，验证策略决策已归属到同一台机器。这可以确认 harness 不仅在上报追踪事件，也在上报策略活动。 + 最后，验证策略决策是否归因于同一台机器。这可确认 harness 正在同时上报策略活动和追踪事件。 - ![用于验证新连接 harness 策略决策的策略页面。](/images/dashboard/policy-observe.png) + ![用于验证新连接 harness 策略决策的 Policy 页面。](/images/dashboard/policy-observe.png) - 将机器密钥读入 shell。`read -s` 通过不回显的提示接收输入，因此它不会出现在命令或 shell 历史记录中： + 将机器密钥读入 shell。`read -s` 会在不回显的提示符处接收输入，因此它不会出现在命令或 shell 历史记录中： ```bash read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN @@ -78,9 +84,9 @@ Harness 是你的 agent 实际运行的环境。Failproof AI 支持其中十二 failproofai policies add FailproofAI/policies ``` - 配置本身不会启用任何策略，第二条命令正是为此而设。 + 初始设置本身不启用任何策略，这正是第二条命令的用途。 - 或者指定具体的 harness 和配置作用域： + 或者指定具名 harness 和配置作用域： ```bash failproofai policies --install \ @@ -88,7 +94,7 @@ Harness 是你的 agent 实际运行的环境。Failproof AI 支持其中十二 --scope user ``` - Project 作用域将钩子配置保留在仓库中。User 作用域覆盖跨仓库的工作。Claude Code 还支持 local 作用域；支持情况因 harness 而异，CLI 会拒绝不支持的组合。 + project 作用域将钩子配置保存在仓库中。user 作用域覆盖跨仓库的工作。Claude Code 还支持 local 作用域；支持情况因 harness 而异，CLI 会拒绝不支持的组合。 验证机器及其事件： @@ -103,13 +109,13 @@ Harness 是你的 agent 实际运行的环境。Failproof AI 支持其中十二 ## 添加非默认会话路径 - - 额外路径注册在机器上，而非 Cloud 中。添加后，打开**观测 → 会话**，按机器所在环境过滤，并确认来自新路径的会话已出现。打开一个会话，在将其用于审计之前检查 agent、harness 和事件时间戳。 + + 额外路径在机器上注册，而非在 Cloud 中注册。添加路径后，打开 **Observe → Sessions**，筛选到该机器的环境，并确认来自新路径的会话已出现。打开一个会话，在将其用于审计之前检查 agent、harness 和事件时间戳。 - ![过滤到接收附加捕获路径数据的环境的会话列表。](/images/dashboard/sessions-list.png) + ![Sessions 列表，已筛选到接收额外捕获路径数据的环境。](/images/dashboard/sessions-list.png) - 添加带有可选标签的路径，然后查看已配置的路径： + 添加一个路径（可附带可选标签），然后查看已配置的路径： ```bash failproofai harness add-path claude checkout=/srv/checkout/.claude @@ -118,10 +124,10 @@ Harness 是你的 agent 实际运行的环境。Failproof AI 支持其中十二 failproofai backfill --since 7d ``` - 使用 `failproofai harness remove-path claude checkout` 移除路径。 + 使用 `failproofai harness remove-path claude checkout` 删除路径。 - 安装后运行一个新会话。在扩大推广范围之前，先验证实时事件流和实际的策略决策均正常工作。 + 安装后运行一个新会话。在扩大推广范围之前，先验证实时事件流和实际的策略决策。 \ No newline at end of file