داخل تصميم محوِّل تعدُّد أطر العمل

يُجسِّد Apothem ملف تعريف مشتركًا واحدًا في سبعة عشر تهيئة أصليّة لإطار العمل. سبعة عشر هدفًا، وسبعة عشر صيغة من صيغ المُورِّدين، وسبعة عشر موقع تثبيت — وواجهةٌ موحَّدة واحدة يعتمد عليها كلٌّ من المُشغِّل وCLI. تشرح هذه التدوينة كيف تُبقي طبقة المحوِّلات هذا العقد متماسكًا.

بروتوكول HarnessAdapter

يُنفِّذ كلُّ محوِّل إطار عمل بروتوكولًا بنيويًّا هو HarnessAdapter. البروتوكول هو الدَّرز بين CLI والتفاصيل الخاصّة بالمُورِّد. يُعلِن عن العمليّات التي يستدعيها CLI وعن البيانات الوصفيّة التي يقرؤها CLI:

• name — المُعرِّف المُسجَّل للمحوِّل.
• output_path — حيث تهبط التهيئة المُجسَّدة على القرص.
• install — عرض التهيئة الأصليّة لإطار العمل وكتابتها.
• uninstall — إزالة التهيئة المُجسَّدة، مع ترك ملف التعريف المشترك دون مساس.
• is_installed — الإبلاغ عمّا إذا كانت تهيئة إطار العمل موجودة.
• verify — كشف الانحراف بين ملف التعريف والتهيئة على القرص.

ولأنّ العقد هو typing.Protocol، فإنّ المحوِّل يُلبِّيه بالشكل لا بالوراثة. يُحمِّل CLI المحوِّلات ديناميكيًّا عبر importlib.metadata من الجدول [project.entry-points."apothem.harnesses"] في pyproject.toml. وإضافة إطار عمل تعني نشر حزمة فرعية تُعرِّض البروتوكول — دون أيّ تعديل في المُوزِّع المركزي.

حزمة فرعية واحدة لكلّ محوِّل

يعيش كلُّ محوِّل في حزمته الفرعيّة الخاصّة تحت src/apothem/harnesses/<name>/:

• __init__.py — صنف <Name>Adapter الذي يُنفِّذ البروتوكول ويُفوِّض إلى وحدات الإجراءات الشقيقة.
• install.py / uninstall.py / update.py / verify.py — تنفيذات كلِّ إجراء التي يستوردها صنف المحوِّل ويستدعيها.
• materializer.py — دالّة اختياريّة materialize_native_config(profile) -> str تعرض ملف التعريف المشترك بوصفه نصّ تهيئة أصليًّا لإطار العمل.

تقسيمُ كلِّ إجراء إلى وحدته الخاصّة يُبقي صنف المحوِّل نحيلًا: إنّه مُوزِّع يصل توابع البروتوكول بدوالّ الإجراءات. والقارئ الذي يفتح verify.py يرى بالضبط منطق كشف الانحراف لذلك الإطار الواحد فحسب، دون ضوضاء تثبيت أو إلغاء تثبيت عليه أن يخوض فيها.

ثلاثة أصناف من المحوِّلات

أطر العمل السبعة عشر لا تستهلك التهيئة جميعها بالطريقة نفسها. يُصنِّفها Apothem في ثلاثة أصناف وفقًا لمقدار التحويل الذي يحتاجه ملف التعريف قبل أن يبلغ إطار العمل.

الصنف I — الانتشار الخام

يستهلك إطار العمل الأعمالَ نفسها التي يكتبها Apothem أصلًا — قواعد .md مُسطَّحة وagents وhooks — دون أيّ خطوة عرض. ينسخ المحوِّل القوالب الخام إلى شجرة تهيئة إطار العمل. لا يوجد materializer.py، لأنّه لا شيء يُعرَض؛ فأعمال ملف التعريف هي المُخرَج.

الصنف II-A — الخام إضافةً إلى قوالب المُورِّد

يستهلك إطار العمل أعمال Apothem الخام AND مجموعةً من ملفّات القوالب الخاصّة بالمُورِّد (ملفّات الإعدادات أو البيان أو السقالة التي يتطلّبها إطار العمل). ينسخ المحوِّل الأعمال الخام وقوالب المُورِّد معًا. تعيش قوالب المُورِّد بجانب المحوِّل تحت دليل templates/.

الصنف II-B — المعروض من ملف التعريف

يريد إطار العمل ملفّ تهيئة أصليًّا واحدًا مَعروضًا من الحقول البنيويّة لملف التعريف المشترك. يقرأ materializer.py الخاصّ بالمحوِّل ملفَّ التعريف ويُصدِر النصّ الأصليّ لإطار العمل — ملفّ config.yaml لـ Hermes، أو openclaw.json لـ Open-Claw، أو opencode.json لـ OpenCode، أو settings.json لـ Qwen Code. الصنف II-B هو حيث يتركّز عمل التوفيق بين الصِّيَغ؛ الغوص العميق في تقارب الاصطلاحات يتناوله بالتفصيل.

claude-code: المحوِّل المرجعيّ كامل السطح

محوِّل claude-code هو التنفيذ المرجعيّ لأوسع سطح تهيئة — القواعد وagents وhooks وoutput-styles والإعدادات وأدلّة الاصطلاحات. ينتمي إلى الصنف II-A: ينشر قوالب Apothem الخام ويُسطِّح أدلّة الاصطلاحات، ويشحن قوالب إعدادات المُورِّد تحت src/apothem/harnesses/claude_code/templates/. لا يحمل materializer.py — فهو لا يعرض ملفّ تهيئة أصليًّا من ملف التعريف؛ بل ينشر الأعمال وأدلّة الاصطلاحات مباشرةً.

حدٌّ متعمَّد واحد: محوِّل claude-code لا يُدير CLAUDE.md. ذلك الملفّ أرضٌ يملكها المُشغِّل. يُجسِّد Apothem سطح التهيئة المحيط — القواعد وhooks والإعدادات — ويترك صوت CLAUDE.md الخاصّ بالمُشغِّل دون مساس. والمحوِّل الذي يطمسه سيمحو تعليمات المشروع المكتوبة يدويًّا عند كلّ apothem install، فيرسم المحوِّل الخطّ عند حدّ الدليل ويتوقّف.

لماذا تهمّ هذه الوحدة

يمنح البروتوكول المُشغِّل نموذجًا ذهنيًّا واحدًا عبر سبع عشرة أداة. تتصرّف apothem install وapothem verify و apothem uninstall بالطريقة نفسها سواء عرض الهدف ملفًّا واحدًا أم سطَّح شجرة أدلّة. تعيش فروق المُورِّدين داخل حزم المحوِّلات الفرعيّة، خلف البروتوكول، حيث ينبغي لها أن تكون.

اقرأ المرجع الموجَّه إلى المُشغِّل في أطر العمل ونموذج ملف التعريف في المفاهيم.