Configuration

​

title: التكوين description: “تنسيق ملف الإعدادات، ونظام النطاقات الثلاثة، وقواعد الدمج” icon: gear

​

نطاقات التكوين

​

قواعد الدمج

project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← اتحاد منقى من التكرارات

project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← المشروع يفوز، يتم تجاهل العام

project:  (لا توجد إدخالة block-sudo)
local:    (لا توجد إدخالة block-sudo)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← ينتقل إلى العام

​

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

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "sanitize-jwt",
    "block-env-files",
    "block-read-outside-cwd"
  ],
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    },
    "block-push-master": {
      "protectedBranches": ["main", "release", "prod"]
    },
    "block-rm-rf": {
      "allowPaths": ["/tmp"]
    },
    "block-read-outside-cwd": {
      "allowPaths": ["/shared/data", "/opt/company"]
    },
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
      ]
    },
    "warn-large-file-write": {
      "thresholdKb": 512
    }
  },
  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
}

​

مرجع الحقول

​

enabledPolicies

​

policyParams

​

hint (شامل)

{
  "policyParams": {
    "block-force-push": {
      "hint": "حاول إنشاء فرع جديد بدلاً من ذلك."
    },
    "block-sudo": {
      "allowPatterns": ["sudo apt-get"],
      "hint": "استخدم apt-get مباشرة بدون sudo."
    },
    "custom/my-policy": {
      "hint": "اطلب موافقة المستخدم أولاً."
    }
  }
}

​

customPoliciesPath

​

سياسات قائمة على الاتفاقية

​

llm

{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​

إدارة الإعدادات من سطر الأوامر

• إعدادات عميل الوكيل — يخبر الوكيل باستدعاء failproofai --hook <event> في كل استخدام أداة:
  • Claude Code: ~/.claude/settings.json (مستخدم), <cwd>/.claude/settings.json (مشروع), <cwd>/.claude/settings.local.json (محلي)
  • OpenAI Codex: ~/.codex/hooks.json (مستخدم), <cwd>/.codex/hooks.json (مشروع) — Codex ليس له نطاق محلي
  • GitHub Copilot CLI (نسخة تجريبية): ~/.copilot/hooks/failproofai.json (مستخدم), <cwd>/.github/hooks/failproofai.json (مشروع) — Copilot ليس له نطاق محلي. إدخالات الخطاف تستخدم حقول أوامر Copilot المفتاحة بنظام التشغيل bash/powershell مع timeoutSec؛ يحمل الملف علامة version: 1 على المستوى الأعلى. دعم GitHub Copilot CLI نسخة تجريبية بينما نتحقق من مخطط سجل events.jsonl (الذي لا تحدده المستندات العامة) مقابل جلسات حقيقية أكثر.
  • Cursor Agent (نسخة تجريبية): ~/.cursor/hooks.json (مستخدم), <cwd>/.cursor/hooks.json (مشروع) — Cursor ليس له نطاق محلي. إدخالات الخطاف تستخدم نموذج {type, command, timeout} على شكل Claude (لا انقسام bash/powershell)، لكن يتم تخزينها تحت مفاتيح أحداث camelCase (preToolUse, beforeSubmitPrompt, …) في مصفوفة مسطحة وفقاً لمخطط الخطافات الخاص بـ Cursor؛ يحمل الملف علامة version: 1 على المستوى الأعلى. يقوم المعالج بتحويل camelCase → PascalCase عبر CURSOR_EVENT_MAP بحيث تعمل السياسات المدمجة الموجودة بدون تغيير. دعم Cursor Agent نسخة تجريبية بينما نتحقق من نسخة Cursor على القرص (غير محددة في المستندات العامة) مقابل عمليات تثبيت حقيقية أكثر.
  • OpenCode (نسخة تجريبية): ~/.config/opencode/opencode.json + ~/.config/opencode/plugins/failproofai.mjs (مستخدم), <cwd>/.opencode/opencode.json + <cwd>/.opencode/plugins/failproofai.mjs (مشروع) — OpenCode ليس له نطاق محلي. على عكس المحررات الخمسة الأخرى، OpenCode ليس له نظام خطاف أوامر خارجية: يحمل في الذاكرة مكوّنات JavaScript/TypeScript مسجلة بشكل صريح عبر مصفوفة plugin: [] في opencode.json (الاكتشاف التلقائي من .opencode/plugins/ ليس كيف يتم تحميل المكونات على opencode v1.14.33). التثبيت ينقط مكون شيم صغير يستدعي ثنائي failproofai عبر subprocess ويترجم استجابة JSON على شكل Claude الخاصة بالثنائي إلى دلالات المكون: throw new Error() لرفض حدث الأداة (يلغي استدعاء الأداة)، client.session.prompt(...) للتعليمات و لرفض Stop / SubagentStop (يرسل سبب الرفض كرسالة المستخدم التالية — القناة الوحيدة للإعادة القسرية منذ أن session.idle إخطار فقط والرمي منه لا يعمل)، بدون عملية للسماح. يقوم الشيم بتحويل أسماء الأدوات (lowercase → PascalCase عبر OPENCODE_TOOL_MAP) ومفاتيح حجج إدخال الأداة (camelCase → snake_case عبر OPENCODE_TOOL_INPUT_MAP لـ Read / Write / Edit، مثلاً filePath → file_path, oldString → old_string) قبل إعادة التوجيه إلى الثنائي، بحيث تعمل عمليات التحقق من المسارات المدمجة مثل block-read-outside-cwd, block-env-files, و block-secrets-write بدون تغيير على استدعاءات أداة OpenCode. الجلسات تعيش في قاعدة بيانات OpenCode SQLite في ~/.local/share/opencode/opencode.db؛ عارض الجلسات في لوحة التحكم يقرأها عبر opencode db --format json و opencode export <id>. دعم OpenCode نسخة تجريبية بينما نتحقق من السلوك عبر الإصدارات ومقابل جلسات حقيقية أكثر. انظر مستندات مكونات OpenCode.
  • Pi (نسخة تجريبية): ~/.pi/agent/settings.json (مستخدم), <cwd>/.pi/settings.json (مشروع) — Pi ليس له نطاق محلي. يحمل Pi حزم ملحقات TypeScript عند البدء؛ ملف الإعدادات مصفوفة نصية مسطحة {"packages": ["./relative/path", …]}. يكتب failproofai إدخالة مصفوفة حزم واحدة تشير إلى دليل pi-extension/ المجمع الخاص به. يشترك الملحق داخلياً في أحداث Pi tool_call / user_bash / input / session_start ويقذف إلى failproofai --hook <Event> --cli pi؛ يقوم المعالج بتحويل underscore_lower_snake_case → PascalCase عبر PI_EVENT_MAP بحيث تعمل السياسات المدمجة الموجودة بدون تغيير. يتم أيضاً تحويل حجج إدخال الأداة عبر PI_TOOL_INPUT_MAP (تسليم Pi للقراءة / الكتابة / التحرير path بدلاً من file_path؛ تعيين المفتاح على المستوى الأعلى يسمح بتشغيل block-env-files و block-secrets-write — block-read-outside-cwd كان لديه بالفعل بديل path). دعم Pi نسخة تجريبية بينما تستقر ملحقات Pi API وتخطيط سجل الجلسة.
  • Hermes (hermes-agent): ~/.hermes/config.yaml (نطاق المستخدم فقط — Hermes ليس له إعدادات المشروع/المحلي). Hermes هو بوابة Slack/Telegram، لذلك تثبيت واحد يعترض استدعاءات الأدوات من كل منصة (Slack/Telegram/cli/cron) و الوكلاء الفرعيين الداخليين. إدخالات الخطاف هي زوج {command, timeout} (المهلة الزمنية بالثواني) تحت خريطة hooks: مفتاحها بأحداث snake_case من Hermes (pre_tool_call / post_tool_call / on_session_start / on_session_end / subagent_stop); يقوم المعالج بتحويل الأحداث عبر HERMES_EVENT_MAP وأسماء الأدوات عبر HERMES_TOOL_MAP بحيث تعمل السياسات المدمجة بدون تغيير. يتم تحرير الإعدادات من خلال استدارة YAML Document حفاظاً على التعليقات بحيث تبقى الإعدادات الأخرى للمشغل، والتثبيت يعيّن hooks_auto_accept: true بحيث تعمل بوابة بدون رأس (لا TTY) الخطافات بدون موجه موافقة. يصدر المقيّم عقد stdout الخاص بـ Hermes {"decision":"block","reason"} (يتجاهل Hermes أكواد الخروج). القيود: Hermes ليس له حدث نهاية الدور Stop، لذا فإن المدمجات require-*-before-stop لن تعمل أبداً لـ Hermes (غير قابلة للتطبيق، وليس كسر)؛ instruct تنخفض إلى السماح مع ملاحظة مسجلة (لا قناة سياق إضافية)؛ وإعادة تسمية سرية الإخراج (sanitize-*) لا يمكن إعادة كتابة إخراج الأداة على عقد shell-hook. Hermes هو أيضاً مصدر تدقيق غير متصل — لوحة التحكم تقرأ جلسات بوابتها مباشرة من ~/.hermes/state.db.
• policies-config.json — يخبر failproofai بالسياسات التي يجب تقييمها وبأية معاملات (مشاركة عبر جميع عملاء الوكيل)

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 --cli claude codex copilot cursor opencode pi

• تم اكتشاف عميل واحد — يختار ذلك العميل تلقائياً بدون فور.
• عملاء متعددة مكتشفة في محطة طرفية تفاعلية — يعرض موجه اختيار مفرد بمفاتيح الأسهم مجمع في قسم Detected (N) (مع صف إجمالي للتثبيت لكل عميل مكتشفة N + كل عميل مكتشفة بشكل فردي) وقسم Not installed (M) · install hooks ahead of time يسرد كل عميل مكتشفة مدعومة كخيار تثبيت آجل (↑↓ للتحريك، أدخل للاختيار، ^C للخروج). يعرض تدفق الإلغاء قسم Detected فقط.
• عملاء متعددة مكتشفة في تشغيل غير تفاعلي (CI، لا TTY) — يثبت لجميع العملاء المكتشفة بدون فور.
• لم يتم اكتشاف أي — ينخفض إلى claude، مع تحذير بأنه لم يتم العثور على ثنائي وكيل في PATH؛ أمر الخطاف لا يزال مكتوباً بحيث ينشط بمجرد تثبيت واحد.

​

مثال: إعدادات على مستوى المشروع مع إعدادات افتراضية للفريق

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}