عقد تجميع المجموعات

تُحدِّد هذه الوثيقة العقد المستقرّ القابل للاستهلاك في المراحل اللاحقة لتجميع المجموعات (cohort) وبيانات الإضافات. يقرأ المستهلِك هذا العقد ليُعدِّد المجموعات ويحلّ أهدافها الأصليّة لكل إطار عمل دون إعادة اشتقاق التعيين.

القطع الأثريّة

شكل بيان المجموعات

بيان المجموعات كائن من المستوى الأعلى يحوي ثلاثة مفاتيح:

• version — سلسلة SemVer للبيان.
• cohorts[] — مدخل واحد لكل مجموعة. لكل مدخل id (من المجموعة المغلقة core | developer | security | research | ai-engineering | full)، وname، وdescription، وmembers (كائن يُجمِّع معرِّفات الأعضاء حسب نوع الفهرس: skills / agents / commands / rules / hooks).
• per_harness_targets — عقد الحلّ (أدناه).

كل معرِّف عضو هو اسم مستقرّ بصيغة kebab-case يقابل قطعة أثريّة حقيقيّة تحت src/apothem/ (skills/<name>/، agents/<name>.md، commands/<name>.md، rules/<name>.md، أو مدخل hooks/).

تعداد المجموعات

يُحمِّل المستهلِك cohort-manifest.yaml، ويتحقّق منه مقابل cohort.schema.json، ثم يكرِّر على cohorts[]. لكل مجموعة يقرأ members.<type> للحصول على معرِّفات أعضاء كل نوع فهرس.

حلّ الأهداف الأصليّة لكل إطار عمل (دون إعادة اشتقاق)

لا يُعيد بيان المجموعات صياغة تعيين إطار العمل. بدلًا من ذلك، يشير per_harness_targets.source إلى lib/propagation-manifest.yaml، مصدر الحقيقة الوحيد. قاعدة الحلّ:

لعضو مجموعة من نوع الفهرس T (واحد من skills، agents، commands، rules، hooks) وإطار عمل هدف H (واحد من المُدرَجة في per_harness_targets.harnesses)، يكون هدف الإضافة الأصلي هو حقل target للمدخل في lib/propagation-manifest.yaml تحت harnesses.H.install الذي يطابق source الخاص به T/.

على سبيل المثال، تُحلّ مهارة (skill) مجموعة core المثبَّتة لـ claude_code عبر المدخل harnesses.claude_code.install ذي source: "skills/" إلى target: "${HARNESS_ROOT}/skills/". وتُحلّ المهارة نفسها لـ opencode إلى ${HARNESS_ROOT}/skills/؛ ولـ gemini_cli إلى ${PROJECT_ROOT}/.gemini/skills/. لا يخترع المستهلِكون أهداف أطر العمل أبدًا — بل يبحثون عنها.

تُحلّ النائبتان ${HARNESS_ROOT} / ${PROJECT_ROOT} وقت التثبيت بواسطة كل محوِّل إطار عمل؛ ويتعامل مستهلِكو المجموعات مع target المحلولة حرفيًّا.

دور بيان الإضافة

يصف plugin.schema.json ملفّ plugin.json — حزمة ذاتيّة الوصف من أعضاء الفهرس (skills / commands / agents / hooks / rules) ذات name مطلوب، وversion بصيغة SemVer، وdescription. بيان الإضافة هو الوحدة التي يُجسِّدها محوِّل إطار العمل في سطح إضافته الأصلي؛ تختار المجموعات أيّ أعضاء تحمل الإضافة، ويحلّ بيان الانتشار مكان هبوط هؤلاء الأعضاء لكل إطار عمل.

قرار التجميع — حزمة مظلّيّة واحدة، مجموعات منطقيّة

المجموعات هي طبقة اختيار منطقيّة (هذا البيان)، لا مجموعة من الحزم المنفصلة القابلة للتثبيت بشكل مستقلّ. تشحن Apothem حزمة مظلّيّة واحدة تحمل الفهرس الكامل؛ يتيح بيان المجموعات للمستهلِك انتقاء مجموعة جزئيّة متماسكة، ويحلّ بيان الانتشار مكان هبوط كل عضو منتقًى لكل إطار عمل.

تقسيم الفهرس إلى حزم منفصلة لكل مجموعة (مثل حزمة لكل عائلة developer / security / research) قابل للتحقيق دون ازدواجيّة على مستوى المستودع عبر نمط الروابط الرمزيّة للإضافة الفوقيّة الموثَّق لدى سطح التوزيع الأساسي: يُدرِج فهرس سوق واحد عدّة إضافات مجموعات، ويحتفظ كل دليل إضافة مجموعة بـروابط رمزيّة إلى الفهرس المشترك أحادي المصدر بدلًا من النسخ. عند تثبيت مجموعة، يُلغي إطار العمل مرجعيّة كل رابط رمزي داخل السوق — ناسخًا محتوى الهدف إلى ذاكرة التخزين المؤقّت لتلك المجموعة — بحيث تكون المجموعة المثبَّتة قائمة بذاتها، بينما يحتفظ المستودع بمصدر حقيقة واحد موصول بروابط رمزيّة (الوصل بدلًا من التكرار، تمامًا كما يفضّل انضباط إزالة التكرار). القراءة السابقة التي تَعتبر أنّ حزم المجموعات "تُكرِّر الفهرس آليًّا" خلطت بين ازدواجيّة ذاكرة التخزين المؤقّت وقت التثبيت (النسخ المعتاد لكل إضافة الذي يقوم به إطار العمل) وازدواجيّة المستودع؛ ونمط الروابط الرمزيّة يتجنّب الأخيرة.

تشحن Apothem حاليًّا حزمة مظلّيّة واحدة لأنّها أبسط سطح توزيع، لا لأنّ المجموعات مستحيلة آليًّا. تبنّي صيغة لكل مجموعة هو مفاضلة حقيقيّة بين تجربة المستخدم والصيانة، لا انتهاكًا لإزالة التكرار: الميزة تجربة "ثبِّت هذه العائلة فقط" أكثر دقّة؛ والتكاليف هي صيانة N من أدلّة الروابط الرمزيّة للمجموعات إضافةً إلى مداخلها في السوق، وسطح أكبر للمطابقة / الاختبار / golden، ونسخ ذاكرة التخزين المؤقّت وقت التثبيت لكل مجموعة. تُقدِّم طبقة المجموعات المنطقيّة أعلاه بالفعل نتيجة الاختيار "ثبِّت ما تحتاجه فقط" من الحزمة الواحدة؛ أمّا التجميع لكل مجموعة فهو الخطوة التالية كلّما رُغِبت تجربة التثبيت الأكثر دقّة.