عقد تحزيم الحزمCopy Anchor Link

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

المُنتَجاتCopy Anchor Link

شكل بيان الحزمCopy Anchor Link

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

• 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/<name>.py قابل للتنفيذ، وإمّا سياق رسالة استشاري في hooks/messages/<name>.md يُسلَّم عبر المُوزِّع).

تعداد الحزمCopy Anchor Link

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

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

لا يُعيد بيان الحزم ذكر تعيين أُطُر العمل. بدلًا من ذلك، يشير 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/.

على سبيل المثال، تُحَلّ مهارة من حزمة 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 المحلول حرفيًا كما هو.

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

يصف plugin.schema.json ملف plugin.json — رزمة ذاتية الوصف من أعضاء الفهرس (skills / commands / agents / hooks / rules) ذات حقول مطلوبة: name، وversion بصيغة SemVer، وdescription. وتغطّي البيانات الوصفية الاختيارية displayName (الاسم المعروض بدلًا من name) وحقول إدراج دليل الإضافات: documentationUrl، وsupportUrl، وprivacyPolicyUrl، وtermsOfServiceUrl، وكلٌّ منها عنوان https://، إضافةً إلى مسار icon داخل الإضافة. وتضبط رزمة Claude Code المُولَّدة الحقول displayName وdocumentationUrl وsupportUrl. ويقرأ دليل Anthropic حقول الإدراج، ويتجاهلها Claude Code وقت التحميل. وتُبلغ مزامنة سوق claude.ai عن الرابطين بوصفهما مفتاحين غير معروفين وتُجرِّدهما، فيعرض السوق هناك «1 with warnings». وهذا التحذير متوقَّع، وتُحمَّل الإضافة دون تغيير. بيان الإضافة هو الوحدة التي يُجسِّدها محوّل إطار العمل في سطح الإضافات الأصلي لديه؛ وتختار الحزم الأعضاء الذين تحملهم الإضافة، ويحلّ بيان الانتشار المكان الذي يستقرّ فيه هؤلاء الأعضاء لكل إطار عمل.

قرار التحزيم — رزمة جامعة واحدة، وحزم منطقيةCopy Anchor Link

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

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

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