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

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

عند الانتهاء سيكون لديك ما يلي.

1. Apothem مُثبَّتًا من مثبِّت البرنامج النصي.
2. ملف تعريف مشترك (مُحرَّر) يقود كل إطار عمل.
3. التهيئة الأصلية لإطار عمل واحد مُحوَّلة.
4. تأكيدٌ بأن تلك التهيئة قد تحقَّقت، وأن تشغيلًا أوّل عاملًا قد ثبت.

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

ما تحتاجه أولًا

• صدفة شبيهة بـ Unix (macOS، أو Linux، أو WSL). يغطّي مثبِّت PowerShell نظام Windows. يعرض هذا الدليل مسار bash.
• Python 3.10 أو أحدث على PATH. تأكَّد بـ python3 --version.
• المكتبتان لزمن التشغيل اللتان يستوردهما المحرّك من مفسّرك: click وrich. أما بقية الحزمة (pyyaml، jsonschema) فهي مضمّنة (vendored) داخل الشجرة، لذا يكفي أن تكون هاتان المكتبتان قابلتين للاستيراد. يفحصهما المثبِّت، ويذكر ما ينقص منهما، ويعرض تثبيت الأجزاء الناقصة نيابةً عنك، حتى تؤكّد وتتابع.

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

الخطوة 1 — ثبِّت Apothem

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

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، ويتوقّف ويطلب التحرير قبل المتابعة. هذا متعمَّد. النموذج يستخدم بيانات هوية بديلة، وعليك أن تجعله ملكك قبل كتابة أي تهيئة إطار عمل. ستفعل ذلك في الخطوة 2.

يمكن التحكّم في التثبيت بمتغيرات البيئة. أكثرها استخدامًا ما يلي.

# Install a different harness as the default, and point at a project profile.
APOTHEM_HARNESS=cursor \
APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

ومن المتغيرات الأخرى المعروفة: APOTHEM_REPO وAPOTHEM_REF (أيُّ بعيد يُستنسخ، وأيُّ مرجع git يُنزَّل؛ إن لم يُعرَّف، يحلّ أحدث وسم إصدار موقَّع ويتحقّق منه، فاضبط وسمًا للتثبيت أو main للفرع المتغيّر باستمرار)، وAPOTHEM_ALLOW_UNVERIFIED=1 (يخفّض فشل التحقّق من توقيع الوسم إلى تحذير)، و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 — اجعل ملف التعريف ملكك

ملف التعريف المشترك في ~/.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 — حوِّل تهيئة إطار العمل

سبق أن حوّل المثبِّت إطار العمل الافتراضي في الخطوة 1. لفعل ذلك صراحةً — أو لتحويل إطار عمل ثانٍ — شغِّل install.

apothem install --harness claude-code

يقرأ هذا ملف تعريفك ويكتب التهيئة الأصلية لـ Claude Code. ولمعاينة كل إطار عمل يمكنك تحديده، شغِّل:

apothem harnesses list

بعض أُطُر العمل ذات نطاق مشروع لا نطاق مستخدم، وتلك تتطلّب مسار --project ليعرف المحوِّل أين يكتب.

apothem install --harness cursor --project .

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

التحويل نصف القصّة فقط. بعد ذلك، تتأكّد من أن التهيئة طُبِّقت على نحو صحيح.

apothem verify --harness claude-code

يفحص verify أن ملف التهيئة المتوقَّع لإطار العمل موجود، وأنه يطابق ما يصرِّح به ملف التعريف. التشغيل النظيف يعني نجاح التحويل.

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

apothem doctor

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

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

ما الذي بنيتَه

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

إلى أين بعد ذلك

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

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

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