توثيق settings.json
اضبط تنفيذ خطّافات Claude Code والأذونات والأحداث والمُهَل وزمن تشغيل Python والتحقّق وأسبقية الإعدادات الطبقيّة لمنظومة Apothem.
النطاق. يصف هذا المستند ملف توصيل الخطّافات (
settings.json) الخاصّ بـ مُحوِّل Claude Code. تستخدم بقيّة أُطُر العمل أسطح إعداداتها الأصليّة الخاصّة بها — انظرsite/content/docs/harnesses/<harness>.mdxلمعرفة نقطة دخول الإعداد المكافئة لكل مُحوِّل.
نظرة عامة
يضبط settings.json تنفيذ خطّافات Claude Code لمنظومة Apothem.
وهو يُصرِّح أيّ الخطّافات تُطلَق على أيّ الأحداث، ومُهَلها، وسطح
الأذونات على المستوى الأعلى. يشحن Apothem قالبًا كنسيًّا واحدًا لأنّ Claude Code
يُحمِّل ~/.claude/settings.json عبر كل المنصّات المدعومة.
زمن تشغيل بـ Python فقط
يستخدم كل خطّاف مُعَدّ شكل أمر exec الخاص بـ Claude Code. ويحمل القالب المشحون الرمزين ${PYTHON_BIN} و${HARNESS_ROOT}؛ وapothem install يستبدل ${PYTHON_BIN} بالمفسِّر المُحلَّل المطلق:
{
"type": "command",
"command": "${PYTHON_BIN}",
"args": ["${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py", "PreToolUse", "pretooluse-write"]
}يُصيِّر apothem install الرمز إلى المسار المطلق لجذر إطار العمل
(صيغة الشرطة المائلة الأماميّة، صالحة على 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.
أحداث الخطّافات
قيم المُهَل تُماثِل الميزانيات الكنسيّة لأحداث الخطّافات — الجدول أدناه يُعيد إنتاجها لراحة القارئ؛ والمصدر الكنسيّ هو الحاكم.
| الحدث | المُطلِق | المُهلة | الغرض | التفويض |
|---|---|---|---|---|
| SessionStart | جلسة Claude Code جديدة | 30 ثانية | تهيئة السياق، وقراءة الذاكرة، وفحص حالة الخطّة | CM-14 |
| PreToolUse | قبل Write/Edit/NotebookEdit/Bash | 10 ثوانٍ | التحقّق من امتثال CM-7 + البيانات الأمامية | CM-7، CM-22 |
| PostToolUse | بعد كل استدعاء أداة (المطابِق *) | 10 ثوانٍ | تنبيه استشاري للضغط الاستباقي | إدارة السياق (الضغط الاستباقي) |
| Stop | الخروج من الجلسة | 60 ثانية | التخريج عند نهاية الجلسة | CM-14/CM-22/CM-24/CM-26 |
يُسجِّل هذا القالب أربعة أحداث. ولا يُسجِّل PreCompact ولا PostCompact؛ أما قالبا Codex وQwen Code فيسجّلانهما، ويسردهما مرجع الخطّافات لكل إطار عمل على حدة.
يقبل dispatch.py إضافةً UserPromptSubmit وNotification في قائمته
البيضاء للأحداث. لم يُوصَّل أيٌّ منهما في القوالب المشحونة؛ أضِف كتلة matcher بنفس
نمط المُحدِّد + التوزيع لتفعيله.
الحقول على المستوى الأعلى
| الحقل | الغرض | مطلوب |
|---|---|---|
permissions | كائن بمصفوفة allow تسرد أسماء الأدوات المُوافَق عليها مسبقًا (أدوات القراءة فقط افتراضيًّا) | نعم |
hooks | خريطة من اسم الحدث ← مصفوفة كتل {matcher, hooks[]}؛ انظر أحداث الخطّافات أدناه | نعم |
model | مُحدِّد نموذج قابل للحلّ من قِبَل المضيف. يُقبَل لقبٌ أو معرِّف كامل عندما يختار المُشغِّل ضبط أحدهما. | اختياري |
defaultShell | الصَّدَفة الافتراضيّة لاستدعاءات أداة Bash. لا يضبط Apothem هذا في القالب المشترك. | اختياري |
autoUpdatesChannel | قناة تحديث Claude Code. لا يضبط Apothem هذا في القالب المشترك. | اختياري |
effortLevel | جهد الاستدلال الافتراضيّ (low، medium، high، max) | اختياري |
التحقّق
ثلاثة مُحقِّقات تُغطّي سطح الخطّافات، بصرامة متصاعدة:
# بنيويّ + نظافة 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 المصطلحات الداخليّة للخطّة في محتوى يُكتَب خارج جذر تثبيت إطار العمل (~/.claude/ لمُحوِّل Claude Code).
راجِع المحتوى بحثًا عن انتهاكات CM-7 (انظر
src/apothem/rules/persistent-conventions-vigilance.md). لغة النطاق فقط
لأدوات قاعدة الشِّفرة.
عدم تحميل settings.json
يقرأ Claude Code الملف ~/.claude/settings.json. تحقّق من تثبيت Apothem في
جذر إطار العمل المتوقَّع وأعِد تشغيل الجلسة بعد تغيير الملف.
الخطّافات لا تفعل شيئًا بصمت
عقد الخطّاف هو «اخرج دائمًا بالرمز 0، وأصدِر دائمًا JSON صالحًا». إن تعذّر تحديد موضع
المُفسِّر، يُعيد المُحدِّد فراغًا ويصير الأمر بلا عمل (no-op). شغِّل chaos_pass.py
للتأكّد من أنّ كل خطّاف مُعَدّ يُعيد مظروفًا صالحًا — فهو يلتقط مسارات الحلّ المُتدهورة
التي ستُخفيها جلسة حيّة.
الأسبقيّة الطبقيّة
يحلّ Claude Code كائن الإعدادات الفعّال بتركيب ثلاث طبقات بترتيب تصاعديّ للأسبقيّة:
| الطبقة | الموقع | مُودَع؟ | المسوّغ |
|---|---|---|---|
| 1. النظام | افتراضيات إطار العمل المُترجَمة داخل Claude Code نفسه | لا ينطبق (يتحكّم فيه المُورِّد) | الأرضية؛ يرث كل مُشغِّل الخطَّ الأساسي نفسه. |
| 2. المشروع | <harness-root>/settings.json | ✅ مُودَع | أعراف المشروع المشتركة: الخطّافات، والأذونات، وخوادم MCP، وتوصيل شريط الحالة. ويقع قالب مصدر Apothem داخل دليل القوالب الخاص بمحوّل Claude Code. |
| 3. محلّيّ للمستخدِم | <harness-root>/settings.local.json (gitignored) — مُقَولَب بوصفه settings.local.example.json ضمن examples/harnesses/claude-code/ | ❌ Gitignored | تجاوزات خاصّة بالمُشغِّل: رموز API، ومسارات محلّيّة للجهاز، وميزات اختيارية. |
تتجاوز قيم الطبقة الأعلى قيم الطبقة الأدنى على مستوى المفتاح-الورقة — حين
تُصرِّح طبقتا المشروع والمحلّيّة للمستخدِم كلتاهما بإدخال permissions.allow، يُؤخَذ
الاتّحاد؛ وحين تُصرِّحان معًا بقيمة قياسيّة مثل theme، تفوز القيمة المحلّيّة للمستخدِم. أمّا
دلالة الدمج الدقيقة لكل مفتاح فيملكها إطار العمل الخاصّ بـ Claude Code.
إنشاء تجاوُز محلّيّ للمستخدِم
- انسخ
examples/harnesses/claude-code/settings.local.example.jsonإلى<harness-root>/settings.local.json. يطابق اسم الملفsettings.local.jsonنمط.gitignore، فلا يهبط الملف أبدًا في التحكّم بالإصدارات. - حرِّر النسخة المحلّية، وأبقِ فقط المفاتيح المراد تجاوزها؛ إذ يُركّب إطار العمل الطبقات، فترث المفاتيح الغائبة من طبقة المشروع.
- تحقّق من أن الملف يُحلَّل بوصفه JSON صالحًا قبل الحفظ؛ فإطار العمل يرفض JSON المُشوَّه عند بدء الجلسة.