مخطّط ملف التعريف المشترك

ملف تعريف Apothem المشترك هو ملفّ YAML في ~/.config/apothem/profile.yaml، أو في المسار المُزوَّد عبر --profile PATH. وهو المصدر الدلالي للحقيقة فيما يخصّ الهويّة، والتفضيلات، والقواعد المشتركة، والتجاوزات الخاصّة بكل إطار عمل، واستبعادات أطر العمل. تشتقّ المحوِّلات الملفّات الأصليّة لكل إطار عمل من ملف التعريف هذا ومن cohort الحمولة المُحزَّمة لـ Apothem.

نموذج وقت التشغيل هو src/apothem/lib/profile.py؛ والمخطّط JSON هو src/apothem/schemas/profile.schema.json.

ملف التعريف الصالح الأدنى

الحقل الوحيد المطلوب هو identity.name:

identity:
  name: "Example User"

السقالة التي يكتبها `profile init`

يكتب apothem profile init سقالةً أوفى قليلًا — حقول هويّة نائبة يُتوقَّع من المُشغِّل أن يُخصِّصها — ويتحقّق منها قبل الإبلاغ عن النجاح:

identity:
  name: "Example User"
  email: "[email protected]"
  github: "example-user"

يطبع الأمر دفعةً تخصيصيّة تُسمّي هذه الحقول. وإذا وصلت لاحقًا هويّة لا تزال نائبة إلى install أو update، طبع هذان الأمران ملاحظةً إرشاديّةً واحدة وتابعا — لا يختلق Apothem أبدًا هويّة نائبة ولا يتوقّف بسببها.

الحقول المعياريّة

الحقل	مطلوب	الافتراضي	ملاحظات
`identity.name`	نعم	لا شيء	اسم عرض غير فارغ للمُشغِّل.
`identity.role`	لا	`senior software engineer`	نصّ الدور المشترك.
`identity.email`	لا	محذوف	يجب أن يكون بصيغة بريد إلكتروني عند وجوده.
`identity.website`	لا	محذوف	يجب أن يكون بصيغة URI عند وجوده.
`identity.github`	لا	محذوف	اسم مستخدم GitHub دون `@`.
`preferences.language`	لا	`python`	يُطبَّع إلى أحرف صغيرة.
`preferences.style`	لا	`concise`	أحد `concise` أو `verbose` أو `balanced`.
`preferences.formatter`	لا	محذوف	سلسلة غير فارغة عند وجودها.
`preferences.test_framework`	لا	محذوف	سلسلة غير فارغة عند وجودها.
`rules`	لا	`[]`	سلاسل فريدة غير فارغة؛ تُطبَّع الأسطر الجديدة إلى LF.
`seriousness`	لا	`PERSONAL_USE`	أحد `EXPLORING` أو `PERSONAL_USE` أو `SHARED` أو `PUBLIC_LAUNCH`.
`harnesses`	لا	`{}`	تجاوزات خاصّة بكل إطار عمل مُفهرسة بمعرّف إطار العمل المدعوم.
`exclude_harnesses`	لا	`[]`	معرّفات أطر العمل المدعومة المُستبعَدة من `--harness all`.

مفاتيح أطر العمل

يقبل المخطّط هذه المعرّفات السبعة عشر لأطر العمل بالضبط:

antigravity
claude-code
codebuddy
codex
cursor
gemini-cli
github-copilot
glm
hermes
kimi-code
kiro
open-claw
opencode
qwen-code
trae
windsurf
zed

تفشل الحقول العليا غير المعروفة، ومفاتيح أطر العمل غير المعروفة، وأنواع القيم الخاطئة، والاستبعادات المكرّرة، وحقول الهويّة المُشوَّهة، قبل أن تكتب install أو update. تتضمّن الأخطاء المتوقَّعة حقلًا، وسببًا، وإصلاحًا، وقيمةً آمنةً مُنقَّحةً عند الفائدة، وfiles_written: [] لإخفاقات التحقّق.

من حقل ملف التعريف إلى الملفّ الأصليّ

ملف التعريف هو الماذا؛ والمحوِّلات هي الكيف. ويُفسِّر فهمُ التدفّق من طرف إلى طرف لماذا يمكن لتعديل واحد على ملفّ YAML واحد أن يُعيد تشكيل كلّ إطار عمل مُثبَّت.

يحمل حقل ملف التعريف نيّةً دلاليّة، لا قُصاصة تهيئة حرفيّة. فـ identity.name هو «مَن المُشغِّل»، لا سطرًا من JSON. تحمل cohort الحمولة المُحزَّمة (commands وrules وskills وhooks وtemplates وstatuslines وoutput-styles وagents) محتوًى سلوكيًّا بصيغة Apothem المحايدة الخاصّة. لا يعرف الحقل ولا الـ cohort كيف تبدو تهيئة أيّ إطار عمل — فتلك المعرفة تخصّ المحوِّلات وحدها.

عند تشغيلك apothem update، يكون التدفّق:

حمِّل ملف التعريف وتحقّق منه مقابل المخطّط JSON. لا يُكتَب شيء حتى يصير ملف التعريف بكامله صالحًا، فلا يُثبِّت خطأ مطبعيّ نصف تثبيت أبدًا.
حلّ المحوِّلات لإطار العمل المُختار (أو all، مطروحًا منه أيّ exclude_harnesses) عبر السجلّ المركزي.
جسّد — يقرأ كل محوِّل ملف التعريف نفسه والـ cohort نفسها، ثم يترجمها إلى لهجة إطار عمله. حقلٌ مثل preferences.style يصير قيمة تهيئة أصليّة في إطار عمل، وسياق تعليمات مُعرَّضًا في آخر؛ وقاعدةٌ في rules[] تصير ملفّ .mdc لـ Cursor، أو قسمًا من تعليمات على نطاق المستودع لـ Copilot، أو مُدخلَ شجرة دعم حيث لا يملك إطار العمل سطح قواعد أصليًّا.
اكتب الملفّات الأصليّة — تهيئة واحدة مُعرَّضة، أو cohort مُحوَّلة، أو شجرة دعم فرعيّة مُشار إليها من مرساة إطار العمل الأصليّة.

يقود ملف التعريف نفسه كلّ إطار عمل، فلا يمكن أن تتعارض التجسيدات حول النيّة. وخلايا القدرة التي لا يدعمها إطار العمل (أو التي لا تزال منتظِرة للاكتشاف) تطفو بوصفها تحذيرات مُهيكَلة قبل أيّ كتابة، بدلًا من اختلاقها على سطح مورِّد لا وجود له. هذا ما يجعل ضمان «تعديل-واحد-أطر-عمل-كثيرة» حقيقيًّا: يُحرَّر ملف التعريف مرّة واحدة، ويُعيد كل محوِّل اشتقاق ملفّاته الأصليّة من ذلك المصدر الوحيد.