البدء: من الصفر إلى إطار عمل عامل

يأخذك هذا الدرس التعليمي عبر إعدادك الأول لـ Apothem من أوله إلى آخره. تبدأ دون أي شيء مُثبَّت، وتنتهي بإعداد إطار عمل حقيقي — مُولَّد من ملف تعريفي كتبته، ومُتحقَّق منه، ومُؤكَّد أنه يعمل. خصِّص نحو خمس عشرة دقيقة. كل أمر أدناه حقيقي وقابل للتشغيل بالنسخ واللصق.

بنهاية الدرس ستكون قد:

1. ثبَّتَّ Apothem من مُثبِّت السكربت.
2. حرَّرت الملف التعريفي المشترك الذي يقود كل إطار عمل.
3. جسَّدت الإعداد الأصلي لإطار عمل.
4. تحقّقت من ذلك الإعداد وأكّدت تشغيلًا أول عاملًا.

سنستخدم Claude Code إطارَ عمل للمثال طوال الدرس، لأنه الإطار الافتراضي للمُثبِّت. تنطبق الخطوات نفسها على أي إطار عمل مدعوم — بدِّل الاسم حين تصل إلى قائمة أُطُر العمل.

ما تحتاج إليه أولًاCopy Anchor Link

• صدفة شبيهة بـ Unix (macOS، أو Linux، أو WSL). يغطّي مُثبِّت PowerShell نظام Windows؛ ويعرض هذا الدرس مسار bash.
• Python 3.10 أو أحدث على PATH لديك. تحقّق بالأمر python3 --version.
• مكتبتا زمن التشغيل اللتان يستوردهما المحرّك من مُفسِّرك: click وrich. أما بقية المكدّس (pyyaml، وjsonschema) فمُضمَّنة في الشجرة، لذا لا يلزم أن يكون قابلًا للاستيراد سوى هاتين المكتبتين. وإذا كانت click أو rich مفقودة، يتوقّف المُثبِّت ويطبع أمر التثبيت. ولأن الأمر ذا السطر الواحد يمرّر النص البرمجي إلى bash، فلا يستطيع المطالبة؛ لذا اضبط APOTHEM_AUTO_INSTALL_DEPS=1 (مثلًا curl -fsSL https://apothem.ahmedgad.com/install.sh | APOTHEM_AUTO_INSTALL_DEPS=1 bash) أو ثبّت الحزمتين أولًا.

يُشحَن Apothem بوصفه شجرة مصدر مُحزَّمة لا حزمةً منشورة — فلا توجد خطوة pip install. يستنسخ المُثبِّت الشجرة ويُشغِّل المحرّك منها مباشرةً.

الخطوة 1 — ثبِّت ApothemCopy Anchor Link

شغِّل المُثبِّت الشبكي:

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

يُنفِّذ المُثبِّت هذه الخطوات:

1. فحص المتطلّبات المسبقة. يعثر المُثبِّت على مُفسِّر Python 3.10+ حقيقي، ويتأكّد من أن مكتبتَي زمن التشغيل (click وrich) قابلتان للاستيراد. وإذا كانت إحداهما مفقودة، يُسمّيها ويتوقّف ويطبع أمر تثبيتها؛ واضبط APOTHEM_AUTO_INSTALL_DEPS=1 للتثبيت دون مطالبة، لأن التشغيل المُمرَّر عبر الأنبوب لا يستطيع المطالبة.
2. وضع المصدر. تُستنسَخ الشجرة المُحزَّمة إلى ~/.apothem (تجاوز ذلك بمتغيّر البيئة APOTHEM_HOME). وإعادة التشغيل تسحب وسم الإصدار في النسخة المستنسخة الموجودة بدلًا من تكرارها.
3. تمهيد الملف التعريفي. إن لم يكن لديك ملف تعريفي بعد، ينسخ المُثبِّت الملف التعريفي المثال إلى ~/.config/apothem/profile.yaml، ويثبّت Claude Code ويتحقّق منه بناءً عليه في التشغيل نفسه، ويُحذّرك من أن حقول الهوية عناصر نائبة.

يمكنك توجيه التثبيت بمتغيّرات البيئة. وهذه هي التي يُرجَّح أن تستخدمها أكثر من غيرها:

# Install a different user-scope harness and name the profile path explicitly.
# Put the variables on the `bash` side of the pipe: a variable placed before
# `curl` reaches only curl, not the installer.
curl -fsSL https://apothem.ahmedgad.com/install.sh | \
  APOTHEM_HARNESS=codex \
  APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  bash

لا يُثبِّت المُثبِّت إلا أُطُر العمل ذات نطاق المستخدم. ثبِّت إطار عمل ذا نطاق مشروع بعد ذلك، مع تسمية المشروع:

apothem install --harness cursor --project /path/to/project

ومن المتغيّرات الأخرى المعترَف بها APOTHEM_REPO وAPOTHEM_REF (أيّ مستودع بعيد يُستنسَخ وأيّ مرجع git يُسحَب؛ وعند تركه غير مضبوط يُحَلّ أحدث وسم إصدار موقَّع ويُتحقَّق منه؛ اضبط وسمًا لتقييدها به، أو main للفرع المتحرّك، وهو ليس وسمًا موقَّعًا، لذا يحتاج أيضًا إلى APOTHEM_ALLOW_UNVERIFIED=1)، وAPOTHEM_ALLOW_UNVERIFIED=1 (يُخفِّض فشل التحقّق من توقيع الوسم إلى تحذير، ويسمح بمرجع ليس وسمًا مثل main)، وAPOTHEM_SOURCE (يستخدم نسخة مسحوبة محلية موجودة بدلًا من الاستنساخ)، وAPOTHEM_SKIP_VERIFY=1 (يتخطّى التحقّق بعد التثبيت، وهو ما نريد تشغيله؛ فاتركه غير مضبوط).

عندما يُنهي المُثبِّت تشغيلًا كاملًا يطبع لافتةً تُبيِّن كيفية استدعاء المحرّك. ويضع غلاف apothem على PATH لديك (POSIX: $HOME/.local/bin؛ Windows: %LOCALAPPDATA%\Microsoft\WindowsApps)، فما إن يصبح ذلك الدليل على PATH حتى تُشغِّل المحرّك مباشرةً:

apothem <command>

وإذا تعذّر وضع الغلاف — أو لم يكن دليله على PATH بعد — تطبع اللافتة بديلًا مكتفيًا ذاتيًا لا يحتاج إلى غلاف:

PYTHONPATH="$HOME/.apothem/src" python3 -m apothem <command>

تكتب بقية هذا الدرس apothem <command>؛ وإذا كنت تستخدم الصيغة البديلة، فأضِف في البداية البادئة الدقيقة التي طبعتها لافتة المُثبِّت.

الخطوة 2 — اجعل الملف التعريفي ملككCopy Anchor Link

الملف التعريفي المشترك في ~/.config/apothem/profile.yaml هو مصدر الحقيقة الوحيد. يقرؤه كل محوّل إطار عمل ويشتقّ منه الإعداد الأصلي لإطار العمل ذاك. حرِّره مرة واحدة، فيبقى كل إطار عمل تُثبِّته متّسقًا.

افتحه في محرّر المحرّك، أو في أي محرّر نصوص:

apothem profile edit

يبدو الملف التعريفي الأدنى الصالح هكذا:

identity:
  name: "Example User"
preferences:
  style: "concise"
rules:
  - "Validate external input before writing files."

استبدل القيمة النائبة لـ name باسمك، وأضِف أي قواعد تريد أن يفرضها كل إطار عمل. أبقِ قيم الأمثلة زائفة — فالملف التعريفي مُعدّ ليكون آمنًا للمشاركة.

تأكّد من أن المحرّك يُعيد قراءة تعديلاتك دون أخطاء:

apothem profile show --json

إذا كان YAML مشوّهًا، فهنا ستراه — أصلِحه وأعِد التشغيل قبل المتابعة.

الخطوة 3 — جسِّد إعداد إطار عملCopy Anchor Link

إذا أنشأ تشغيلك في الخطوة 1 الملف التعريفي، فقد ثبّت Claude Code بالفعل بناءً على الهوية النائبة. حرِّر الملف التعريفي في الخطوة 2، ثم طبِّق هويتك بالأمر:

apothem update --harness claude-code

apothem install --harness claude-code

يقرأ هذا ملفك التعريفي ويكتب الإعداد الأصلي لـ Claude Code. ولرؤية كل إطار عمل يمكنك استهدافه:

apothem harnesses list

بعض أُطُر العمل ذات نطاق مشروع لا نطاق مستخدم، وتحتاج هذه إلى مسار --project ليعرف المحوّل أين يكتب:

apothem install --harness cursor --project .

الخطوة 4 — تحقَّق وأكِّد تشغيلًا أولCopy Anchor Link

التجسيد نصف القصة فقط. أكِّد الآن أن الإعداد وصل على نحو صحيح:

apothem verify --harness claude-code

يفحص verify أن ملفات الإعداد المُدارة لإطار العمل موجودة وقابلة للتحليل. وأضِف --profile PATH فيفشل أيضًا عندما يكون ملف مُثبَّت قد انحرف عمّا كان سيُنتِجه ذلك الملف التعريفي. والتشغيل النظيف يعني أن التجسيد نجح.

ولفحص الصحّة على مستوى الجهاز كله عبر كل محوّل مُسجَّل، شغِّل:

apothem doctor

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

تشغيلك الأول. افتح إطار العمل الذي أعددته للتوّ — Claude Code في مثالنا — وابدأ جلسة في أي مشروع. القواعد والتفضيلات التي كتبتها في الملف التعريفي صارت الآن جزءًا من سلوك تلك الأداة. هذا هو التشغيل الأول العامل: الملف التعريفي الذي حرّرته في الخطوة 2 يُشكِّل جلسة حقيقية.

ما الذي بنيتهCopy Anchor Link

بدءًا من جهاز فارغ، ثبَّتَّ Apothem، وألَّفت ملفًا تعريفيًا مشتركًا، وجسَّدت منه الإعداد الأصلي لإطار عمل، وتحقّقت من النتيجة، وأكّدت أنها تعمل. الملف التعريفي هو المُنتَج الدائم — غيِّره مرة واحدة وأعِد تشغيل apothem update --harness <name> لدفع التغيير إلى أي إطار عمل.

إلى أين بعد ذلكCopy Anchor Link

• أضِف أداة أخرى. تغطّي قائمة أُطُر العمل كل منصّة مدعومة واسم محوّلها. كرِّر الخطوة 3 بقيمة --harness جديدة.
• تعمَّق في مهمة واحدة. تغطّي وصفات الإرشاد العملي إضافة إطار عمل، وتحرير الملف التعريفي، وقيادة المُثبِّت. وتغطّي أدلّة الاستخدام كتابة القواعد، وتأليف الخطط، وتشغيل بوابة المطابقة.
• ابحث عن التفاصيل. يوثّق المرجع كل صنف أثَر ومخطط الملف التعريفي، ويغطّي مرجع واجهة سطر الأوامر كل أمر. ولكل محوّل صفحته الخاصة تحت أُطُر العمل.
• خطِّط لعمل يدوم أطول من جلسة. يشرح التخطيط القابل للاستئناف كيف يُخرِج Apothem العمل الطويل الأمد إلى حزمة .apothem/plans/ محلية للمشروع، بحيث تستأنفه جلسة جديدة على أي جهاز في مكانه.

الخطوة التالية الموصى بهاCopy Anchor Link

شغِّل apothem doctor لفحص إعدادك — فهو يُبلِغ عن حالة كل محوّل مُسجَّل، فيظهر إطار العمل الذي ثبّتّه للتوّ سليمًا بينما تظهر البقية غير مُثبَّتة بعد — قبل أن تنتقل إلى إضافة مزيد من أُطُر العمل.