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

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

بروتوكول HarnessAdapterCopy Anchor Link

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

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

ولأنّ العقد هو typing.Protocol، فإنّ المحوِّل يُلبِّيه بالشكل لا بالوراثة. وفي وقت التشغيل يَحُلّ CLI كل محوِّل من سجلّ ثابت — جدول HARNESS_REGISTRY في src/apothem/lib/harness_registry_data.py، الذي يُعلِن harness_registry.py أنه مرجعي وقت التشغيل — بحيث يُحمَّل كل محوِّل من نسخة مسحوبة عادية دون أيّ بيانات وصفية لنقاط الدخول مُثبَّتة على sys.path. أمّا الجدول [project.entry-points."apothem.harnesses"] في pyproject.toml ومسح نظام الملفات discover_adapters() فهما فحص تكافؤ للمطابقة، لا مُحلِّل زمن التشغيل؛ إذ يؤكّد اختبارٌ أن مجموعة المحوِّلات المكتشَفة تساوي السجلّ الثابت، بحيث يظهر أيّ محوِّل صحيح الاصطلاح لكنه غير مُسجَّل بوصفه تراجعًا في التغطية بدلًا من أن يُحَلّ بصمت. وإضافة إطار عمل تعني إذن تسجيله في بيانات السجلّ (ومرآته في جدول نقاط الدخول لتكافؤ التحزيم) — ويفشل اختبار التكافؤ فشلًا صريحًا إن أُغفِل أيٌّ منهما.

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

يعيش كلُّ محوِّل في حزمته الفرعيّة الخاصّة تحت 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 يرى بالضبط منطق كشف الانحراف لذلك الإطار الواحد فحسب، دون ضوضاء تثبيت أو إلغاء تثبيت عليه أن يخوض فيها.

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

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

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

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

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

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

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

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

claude-code: المحوِّل كامل السطحCopy Anchor Link

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

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

لماذا تهمّ هذه الوحدةCopy Anchor Link

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

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