الانتقال إلى المحتوى الرئيسي

​
المتطلبات

  • Node.js >= 20.9.0
  • Bun >= 1.3.0 (اختياري - مطلوب فقط عند البناء من المصدر)

​
التثبيت

npm install -g failproofai

​
البدء السريع

1

فعّل السياسات

السياسات هي قواعد تعمل قبل وبعد كل استدعاء أداة للوكيل. تعترض الأوامر التدميرية وتسريب الأسرار وأوضاع الفشل الأخرى قبل أن تسبب ضررًا.
failproofai policies --install
يكتب هذا إدخالات hooks في واجهات سطر الأوامر المثبتة للوكيل (ملف Claude Code ~/.claude/settings.json، ملف OpenAI Codex ~/.codex/hooks.json، ملف GitHub Copilot CLI ~/.copilot/hooks/failproofai.json، ملف Cursor Agent ~/.cursor/hooks.json، ملف المكون الإضافي المُنشأ من OpenCode في ~/.config/opencode/plugins/failproofai.mjs بالإضافة إلى إدخال تسجيل في مصفوفة plugin الخاصة بـ ~/.config/opencode/opencode.json، ملف Pi ~/.pi/agent/settings.json، أو ملف Gemini CLI ~/.gemini/settings.json). عندما يكون هناك أكثر من واحد، ستُطلب منك الخيارات؛ مرر --cli claude codex copilot cursor opencode pi gemini (أي مجموعة جزئية) لتخطي الطلب.دعم GitHub Copilot CLI و Cursor Agent و OpenCode و Pi و Gemini CLI هو إصدار تجريبي — ثبّت باستخدام --cli copilot أو --cli cursor أو --cli opencode أو --cli pi أو --cli gemini.
failproofai policies --install --scope project
failproofai policies --install --cli codex --scope project
failproofai policies --install --cli copilot --scope project
failproofai policies --install --cli cursor --scope project
failproofai policies --install --cli opencode --scope project
failproofai policies --install --cli pi --scope project
failproofai policies --install --cli gemini --scope project
failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
2

تحقق

failproofai policies
يعرض كل سياسة، وما إذا كانت مفعلة، وأي معاملات مُكوّنة.
3

شغّل لوحة المعلومات

failproofai
يفتح لوحة معلومات محلية على http://localhost:8020 حيث يمكنك استعراض الجلسات وفحص استدعاءات الأدوات وإدارة السياسات.
4

شغّل وكيلك

شغّل Claude Code كالمعتاد. إذا حاول الوكيل فعل شيء محفوف بالمخاطر، فإن failproofai سيعترضه تلقائيًا. اتركه يعمل بدون مراقبة واستعرض ما حدث في لوحة المعلومات.

​
كيف تعمل السياسات

في كل مرة يشغّل الوكيل أداة، يستدعي Claude Code failproofai كعملية فرعية: 
Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
                                                 evaluates policies
                                                 writes decision to stdout
تُرجع كل سياسة واحدة من ثلاث قرارات:
  • allow - يستمر الوكيل بشكل طبيعي
  • deny - يتم حجب الإجراء، يُخبر الوكيل السبب
  • instruct - يتم إضافة سياق إضافي إلى مطالبة الوكيل
تعمل السياسات في عمليتك المحلية. لا يتم إرسال أي شيء إلى خدمة بعيدة.

​
اضبط سياسات الفريق باستخدام السياسات المبنية على الاتفاقيات

أسرع طريقة لإنشاء معايير الجودة عبر فريقك هي اتفاقية .failproofai/policies/. أسقط ملفات السياسات في هذا المجلد وسيتم تحميلها تلقائيًا — لا أعلام، لا تغييرات في الإعدادات، لا أوامر تثبيت.
1

إنشاء مجلد السياسات

mkdir -p .failproofai/policies
2

إضافة ملفات السياسات

انسخ الأمثلة الأولية أو اكتب ملفاتك الخاصة:
cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
أو أنشئ واحدة جديدة:
// .failproofai/policies/team-policies.mjs
import { customPolicies, allow, deny, instruct } from "failproofai";

customPolicies.add({
  name: "test-before-commit",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
      return instruct("Run tests before committing.");
    }
    return allow();
  },
});
3

ارفع إلى git

git add .failproofai/policies/
git commit -m "Add team quality policies"
كل عضو في الفريق لديه failproofai مثبتًا سيستقبل هذه السياسات تلقائيًا. لا توجد حاجة لإعداد لكل مطور.
التزم بـ .failproofai/policies/ في مستودعك حتى يشارك الفريق بأكمله نفس المعايير. مع اكتشاف فريقك لأوضاع فشل جديدة، أضف سياسات واضغط — سيحصل الجميع على التحديث في git pull التالي. بمرور الوقت، تصبح هذه السياسات معيارًا جودة حيًا يستمر في التحسن.

​
تخزين البيانات

تبقى جميع الإعدادات والسجلات على جهازك:
المسارما يخزنه
~/.failproofai/policies-config.jsonإعدادات السياسة العامة
~/.failproofai/hook-activity.jsonlسجل تنفيذ Hook
~/.failproofai/hook.logسجل تصحيح أخطاء أداة Hook المخصصة
.failproofai/policies-config.jsonإعدادات كل مشروع (مرتكبة)
.failproofai/policies-config.local.jsonالتجاوزات الشخصية (مُستثناة من git)

​
الإزالة

failproofai policies --uninstall
يزيل إدخالات hooks من ~/.claude/settings.json. يتم الاحتفاظ بملفات الإعدادات في ~/.failproofai/.

​
الخطوات التالية

الإعدادات

النطاقات وتنسيق ملف الإعدادات

السياسات المدمجة

جميع 26 سياسة مع المعاملات

السياسات المخصصة

اكتب سياساتك الخاصة في JavaScript

مراقب الوكيل

راقب الجلسات واستعرض نشاط السياسة