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

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

يستخدم failproofai ملفات تكوين JSON للتحكم في السياسات النشطة، وكيفية تصرفها، وأين يتم تحميل السياسات المخصصة. تم تصميم التكوين ليكون سهل المشاركة مع فريقك - قم بالتزام به في المستودع الخاص بك وسيحصل كل مطور على نفس شبكة الأمان للوكيل.

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

هناك ثلاثة نطاقات تكوين، يتم تقييمها بترتيب الأولوية:
النطاقمسار الملفالغرض
مشروع.failproofai/policies-config.jsonإعدادات لكل مستودع، مرتبطة بالتحكم في الإصدار
محلي.failproofai/policies-config.local.jsonتجاوزات شخصية لكل مستودع، في gitignored
عام~/.failproofai/policies-config.jsonالإعدادات الافتراضية على مستوى المستخدم عبر جميع المشاريع
عندما يتلقى failproofai حدث hook، فإنه يقوم بتحميل ودمج جميع الملفات الثلاثة الموجودة للمجلد الحالي.

​
قواعد الدمج

enabledPolicies - اتحاد جميع النطاقات الثلاثة. السياسة المفعلة في أي مستوى تكون نشطة. 
project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← إزالة التكرار من الاتحاد
policyParams - النطاق الأول الذي يحدد معاملات السياسة المعينة يفوز كليًا. لا يوجد دمج عميق للقيم ضمن معاملات السياسة. 
project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

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

project:  (no block-sudo entry)
local:    (no block-sudo entry)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← ينتقل إلى العام
customPoliciesPath - النطاق الأول الذي يحدده يفوز. llm - النطاق الأول الذي يحدده يفوز.

​
صيغة ملف التكوين

{
  "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

النوع: string[] قائمة أسماء السياسات التي سيتم تفعيلها. يجب أن تطابق الأسماء بالضبط معرفات السياسة التي يعرضها failproofai policies. انظر السياسات المدمجة للقائمة الكاملة. السياسات غير الموجودة في enabledPolicies غير نشطة، حتى لو كانت لديها إدخالات في policyParams.

​
policyParams

النوع: Record<string, Record<string, unknown>> تجاوزات معاملات لكل سياسة. المفتاح الخارجي هو اسم السياسة؛ المفاتيح الداخلية خاصة بكل سياسة. تتوثق كل سياسة معاملاتها المتاحة في السياسات المدمجة. إذا كانت السياسة لديها معاملات ولكنك لم تحددها، يتم استخدام الإعدادات الافتراضية المدمجة للسياسة. المستخدمون الذين لا يقومون بتكوين policyParams على الإطلاق يحصلون على سلوك مطابق للإصدارات السابقة. المفاتيح غير المعروفة داخل كتلة معاملات السياسة يتم تجاهلها بصمت في وقت إطلاق hook ولكن يتم وضع علامة عليها كتحذيرات عند تشغيل failproofai policies.

​
hint (عام)

النوع: string (اختياري) رسالة تُضاف إلى السبب عندما تُرجع سياسة deny أو instruct. استخدمها لإعطاء Claude توجيهات قابلة للتنفيذ دون تعديل السياسة نفسها. يعمل مع أي نوع سياسة — مدمج، مخصص (custom/)، اتفاقية مشروع (.failproofai-project/)، أو اتفاقية مستخدم (.failproofai-user/). 
{
  "policyParams": {
    "block-force-push": {
      "hint": "Try creating a fresh branch instead."
    },
    "block-sudo": {
      "allowPatterns": ["sudo apt-get"],
      "hint": "Use apt-get directly without sudo."
    },
    "custom/my-policy": {
      "hint": "Ask the user for approval first."
    }
  }
}
عندما يرفض block-force-push، يرى Claude: “Force-pushing is blocked. Try creating a fresh branch instead.” القيم غير الحرفية والسلاسل الفارغة يتم تجاهلها بصمت. إذا لم يتم تعيين hint، فإن السلوك لم يتغير (متوافق للخلف).

​
customPoliciesPath

النوع: string (مسار مطلق) المسار إلى ملف JavaScript يحتوي على سياسات hook مخصصة. يتم تعيينه تلقائيًا بواسطة failproofai policies --install --custom <path> (يتم حل المسار إلى مسار مطلق قبل تخزينه). يتم تحميل الملف جديدًا في كل حدث hook - لا يوجد تخزين مؤقت. انظر السياسات المخصصة لتفاصيل الإنشاء.

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

بالإضافة إلى customPoliciesPath الصريح، يقوم failproofai تلقائيًا باكتشاف وتحميل ملفات السياسة من المجلدات .failproofai/policies/:
المستوىالمجلدالنطاق
مشروع.failproofai/policies/مشاركة مع الفريق عبر التحكم في الإصدار
مستخدم~/.failproofai/policies/شخصي، ينطبق على جميع المشاريع
مطابقة الملفات: يتم تحميل الملفات المطابقة فقط لـ *policies.{js,mjs,ts} (مثل security-policies.mjs, workflow-policies.js). الملفات الأخرى في المجلد يتم تجاهلها. لا يلزم التكوين: لا تتطلب سياسات الاتفاقية إدخالات في policies-config.json. فقط أسقط الملفات في المجلد وسيتم التقاطها في حدث hook التالي. التحميل المتحد: يتم مسح كلا مجلدي الاتفاقية للمشروع والمستخدم. جميع الملفات المطابقة من كلا المستويين يتم تحميلها (بخلاف customPoliciesPath الذي يستخدم نطاق-أول-يفوز). انظر السياسات المخصصة لمزيد من التفاصيل والأمثلة.

​
llm

النوع: object (اختياري) تكوين عميل LLM للسياسات التي تقوم باستدعاءات AI. غير مطلوب لمعظم الإعدادات. 
{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​
إدارة التكوين من CLI

تقوم أوامر policies --install و policies --uninstall بالكتابة إلى settings.json لـ Claude Code (نقاط دخول hook)، بينما policies-config.json هو الملف الذي تديره مباشرة. الاثنان منفصلان:
  • settings.json - يخبر Claude Code باستدعاء failproofai --hook <event> في كل استخدام أداة
  • policies-config.json - يخبر failproofai بالسياسات التي يجب تقييمها وبأي معاملات
يمكنك تحرير policies-config.json مباشرة في أي وقت؛ التغييرات تصبح نافذة المفعول فورًا في حدث hook التالي بدون الحاجة لإعادة التشغيل.

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

التزم .failproofai/policies-config.json بمستودعك: 
{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}
يمكن لكل مطور بعد ذلك إنشاء .failproofai/policies-config.local.json (في gitignored) للتجاوزات الشخصية دون التأثير على زملائه.