توثيق settings.json

النطاق. يصف هذا المستند ملف توصيل الخطّافات (settings.json) الخاصّ بـ مُحوِّل Claude Code. تستخدم بقيّة الـ harness أسطح إعداداتها الأصليّة الخاصّة بها — انظر site/content/docs/harnesses/<harness>.mdx لمعرفة نقطة دخول الإعداد المكافئة لكل مُحوِّل.

نظرة عامة

يضبط settings.json تنفيذ خطّافات Claude Code لمنظومة Apothem. وهو يُصرِّح أيّ الخطّافات تُطلَق على أيّ الأحداث، ومُهَلها، وسطح الأذونات على المستوى الأعلى. يشحن Apothem قالبًا كنسيًّا واحدًا لأنّ Claude Code يُحمِّل ~/.claude/settings.json عبر كل المنصّات المدعومة.

زمن تشغيل بـ Python فقط

يستخدم كل خطّاف مُعَدّ شكل أمر exec الخاصّ بـ Claude Code. يحمل القالب المشحون رمز ${HARNESS_ROOT}:

{
  "type": "command",
  "command": "python",
  "args": ["${HARNESS_ROOT}/apothem/hooks/dispatch.py", "PreToolUse", "pretooluse-write"]
}

يُصيِّر apothem install الرمز إلى المسار المطلق لجذر الـ harness (صيغة الشرطة المائلة الأماميّة، صالحة على Windows وmacOS وLinux)، بحيث يستدعي settings.json المثبَّت المُوزِّع المُجَسَّد عند ~/.claude/.apothem/support/hooks/dispatch.py مباشرةً. المُوزِّع وبوّابة المطابقة (~/.claude/.apothem/support/conformity/gate.py، مع فيكسترات الـ schema بجانبها عند ~/.claude/.apothem/support/schemas/) كلاهما نصّان برمجيّان مستقلّان من المكتبة القياسيّة — لا يلزم على المضيف حزمة apothem قابلة للاستيراد، وقالب واحد يخدم كل منصّة.

مخطّط إعداد الخطّافات

الأذونات

"permissions": {
  "allow": ["Read", "Glob", "Grep"]
}

تتطلّب الأدوات غير الموجودة في allow موافقة صريحة لكل استدعاء أو إذنًا على مستوى مساحة العمل. الأدوات للقراءة فقط مُوافَق عليها مسبقًا؛ عمليّات الكتابة (Write وEdit وNotebookEdit وBash) تمرّ عبر مُحقِّق PreToolUse.

أحداث الخطّافات

قيم المُهَل تُماثِل الكتلة الكنسيّة في CLAUDE.md §7.4 — الجدول أدناه يُعيد إنتاجها لراحة القارئ؛ والعمود الكنسيّ هو الحاكم.

يقبل dispatch.py إضافةً UserPromptSubmit وNotification في قائمته البيضاء للأحداث. لم يُوصَّل أيٌّ منهما في القوالب المشحونة؛ أضِف كتلة matcher بنفس نمط المُحدِّد + التوزيع لتفعيله.

الحقول على المستوى الأعلى

التحقّق

ثلاثة مُحقِّقات تُغطّي سطح الخطّافات، بصرامة متصاعدة:

# بنيويّ + نظافة Python (سريع، دون اتصال)
python scripts/dev/validate_hooks.py

# المنظومة الكاملة (البنية + الفرونت-ماتر + فحوص الخطّافات المُفوَّضة)
python scripts/dev/validate_ecosystem.py

# مسح خصاميّ (يعصف بكل أمر خطّاف مُعَدّ بمدخلات مُتدهورة)
python scripts/dev/chaos_pass.py

يجب أن تخرج الثلاثة جميعًا بالرمز 0 قبل إيداع تغييرات الخطّافات أو الإعدادات.

اختبار دخان عابر لحدث مفرد:

python src/apothem/hooks/dispatch.py --event-name SessionStart

الخرج المتوقَّع: مظروف JSON من سطر واحد يحتوي على hookSpecificOutput.

مشكلات شائعة

انتهاء مُهلة SessionStart

الأكثر شيوعًا أنّ مُحدِّد find-python يكتشف شِيم Microsoft Store ويفشل في حلّ مُفسِّر حقيقيّ. تحقّق:

python src/apothem/hooks/dispatch.py --event-name SessionStart

إن طبع الأمر مظروف JSON صالحًا لكن لوحة Claude Code أظهرت انتهاء مُهلة، فارفع timeout الحدث في settings.json. وإن فشل الأمر على مستوى الصَّدَفة، فثبِّت CPython 3.10+ حقيقيًّا واضمن أنّه على الـ PATH أو قابل للاكتشاف بواسطة المُحدِّد.

كل Write/Edit مَحظور

يُعلِّم PreToolUse المصطلحات الداخليّة للخطّة في محتوى يُكتَب خارج جذر تثبيت الـ harness (~/.claude/ لمُحوِّل Claude Code). راجِع المحتوى بحثًا عن انتهاكات CM-7 (انظر src/apothem/rules/persistent-conventions-vigilance.md). لغة النطاق فقط لأدوات قاعدة الشِّفرة.

عدم تحميل settings.json

يقرأ Claude Code الملف ~/.claude/settings.json. تحقّق من تثبيت Apothem في جذر الـ harness المتوقَّع وأعِد تشغيل الجلسة بعد تغيير الملف.

الخطّافات لا تفعل شيئًا بصمت

عقد الخطّاف هو «اخرج دائمًا بالرمز 0، وأصدِر دائمًا JSON صالحًا». إن تعذّر تحديد موضع المُفسِّر، يُعيد المُحدِّد فراغًا ويصير الأمر بلا عمل (no-op). شغِّل chaos_pass.py للتأكّد من أنّ كل خطّاف مُعَدّ يُعيد مظروفًا صالحًا — فهو يلتقط مسارات الحلّ المُتدهورة التي ستُخفيها جلسة حيّة.

الأسبقيّة الطبقيّة

يحلّ Claude Code كائن الإعدادات الفعّال بتركيب ثلاث طبقات بترتيب تصاعديّ للأسبقيّة:

تتجاوز قيم الطبقة الأعلى قيم الطبقة الأدنى على مستوى المفتاح-الورقة — حين تُصرِّح طبقتا المشروع والمحلّيّة للمستخدِم كلتاهما بإدخال permissions.allow، يُؤخَذ الاتّحاد؛ وحين تُصرِّحان معًا بقيمة قياسيّة مثل theme، تفوز القيمة المحلّيّة للمستخدِم. أمّا دلالة الدمج الدقيقة لكل مفتاح فيملكها harness الخاصّ بـ Claude Code.

إنشاء تجاوُز محلّيّ للمستخدِم

1. انسخ settings.local.example.json (جذر المستودع) إلى <harness-root>/settings.local.json. اسم الملف settings.local.json يطابق نمط .gitignore، فلا يهبط الملف أبدًا في التحكّم بالإصدارات.
2. حرِّر النسخة المحلّيّة — أبقِ فقط المفاتيح المراد تجاوزها؛ يركّب الـ harness الطبقات، لذا ترث المفاتيح الغائبة من طبقة المشروع.
3. تحقّق من أنّ الملف يُحلَّل كـ JSON صالح قبل الحفظ — يرفض الـ harness JSON المُشوَّه عند بدء الجلسة.