Getting started

title: البدء السريع description: “ثبّت failproofai، فعّل السياسات، واترك وكلاءك يعملون بموثوقية” icon: rocket

المتطلبات

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

التثبيت

npm install -g failproofai

bun add -g failproofai

البدء السريع

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

السياسات هي قواعد تعمل قبل وبعد كل استدعاء أداة لدى الوكيل. تلتقط الأوامر الضارة، تسرب الأسرار، وأوضاع الفشل الأخرى قبل أن تسبب ضررًا.

failproofai policies --install

يكتب هذا إدخالات hook في أدوات الوكيل المثبتة لديك (ملف Claude Code ~/.claude/settings.json، ملف OpenAI Codex ~/.codex/hooks.json، ملف GitHub Copilot CLI ~/.copilot/hooks/failproofai.json، ملف Cursor Agent ~/.cursor/hooks.json، مكون OpenCode المولد في ~/.config/opencode/plugins/failproofai.mjs بالإضافة إلى إدخال التسجيل في مصفوفة plugin في ~/.config/opencode/opencode.json، ملف Pi ~/.pi/agent/settings.json، أو ملف Hermes ~/.hermes/config.yaml). عند وجود أكثر من واحد ستُطلب منك المتابعة؛ مرر --cli claude codex copilot cursor opencode pi hermes (أي مجموعة فرعية) لتخطي الطلب.دعم GitHub Copilot CLI و Cursor Agent و OpenCode و Pi موجود في مرحلة تجريبية — ثبّت باستخدام --cli copilot أو --cli cursor أو --cli opencode أو --cli pi. يثبّت Hermes (hermes-agent، بوابة Slack/Telegram) بنطاق المستخدم باستخدام --cli hermes وهو أيضًا مصدر تدقيق دون اتصال.

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 hermes --scope user
failproofai policies --install block-sudo block-rm-rf sanitize-api-keys

التحقق

failproofai policies

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

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

failproofai

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

تشغيل وكيلك

شغّل 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/. ضع ملفات السياسة في هذا الدليل وسيتم تحميلها تلقائيًا — لا أعلام، لا تغييرات إعدادات، لا أوامر تثبيت.

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

mkdir -p .failproofai/policies

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

انسخ أمثلة المبتدئين أو اكتب خاصتك:

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();
  },
});

الالتزام بـ 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

يزيل إدخالات hook من ~/.claude/settings.json. ملفات الإعدادات في ~/.failproofai/ يتم الاحتفاظ بها.

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

الإعدادات

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

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

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

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

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

مراقب الوكيل

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

البداية

المفاهيم الأساسية

CLI

الأدوات

متقدم

أمثلة

title: البدء السريع description: “ثبّت failproofai، فعّل السياسات، واترك وكلاءك يعملون بموثوقية” icon: rocket

المتطلبات

التثبيت

البدء السريع

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

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

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

إلغاء التثبيت

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

الإعدادات

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

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

مراقب الوكيل

​title: البدء السريع description: “ثبّت failproofai، فعّل السياسات، واترك وكلاءك يعملون بموثوقية” icon: rocket

​المتطلبات

​التثبيت

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

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

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

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

​إلغاء التثبيت

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

الإعدادات

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

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

مراقب الوكيل

title: البدء السريع description: “ثبّت failproofai، فعّل السياسات، واترك وكلاءك يعملون بموثوقية” icon: rocket

المتطلبات

التثبيت

البدء السريع

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

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

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

إلغاء التثبيت

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