install

تثبيت إعداد محوّل إطار عمل من الملف التعريفي المشترك.

الموجزCopy Anchor Link

apothem install --harness NAME|all [--profile PATH] [--dry-run]
                 [--clean|--fresh] [--yes] [--project PATH]
                 [--quiet|-q] [--verbose|-v]
                 [--format plain|json] [--json] [--no-color]

يحمّل الملف التعريفي المشترك ويتحقّق منه، ويختار محوّلًا مُسمّى أو مجموعة all الشاملة للسجلّ كله، ويتحقّق من خطة التجسيد، ويكتب الإعداد الأصلي لإطار العمل إضافةً إلى حزم الدعم. وتتطلّب المحوّلات ذات نطاق المشروع --project PATH.

يُحَلّ الاسم المستعار بصيغة الاستمرار apothem installing (ويُقبَل أيضًا بالصيغة apothem Installing) إلى المعالج نفسه.

التشغيل الأول دون ملف تعريفيCopy Anchor Link

عند إغفال --profile وعدم وجود ملف تعريفي في المسار الافتراضي (~/.config/apothem/profile.yaml)، يكتب install الملف التعريفي المبدئي هناك أولًا، ويطبع Created a starter profile at <path>، ثم يتابع. يحمل الملف التعريفي المبدئي حقول هوية نائبة، لذا يطبع التثبيت أيضًا ملاحظة الهوية النائبة؛ خصّص الملف التعريفي، ثم شغّل update لتطبيقه. ومع --json يُبلَّغ عن الإنشاء بوصفه مُدخَلًا في warnings يحمل "operation": "profile_created".

• لا يكتب --dry-run الملف التعريفي أبدًا: تستخدم المعاينة الملف التعريفي المبدئي في الذاكرة وتُبلغ عن "operation": "profile_scaffold_preview".
• لا يُنشَأ أبدًا ملفٌ مُحدَّد صراحةً عبر --profile PATH وغير موجود؛ بل يخرج الأمر بالرمز 1 مع profile.not_found.

معاينة نطاق الأثرCopy Anchor Link

يتفرّع install --harness all إلى نطاقات مختلطة: تكتب المحوّلات ذات نطاق المشروع تحت جذر --project المُمرَّر، بينما تكتب المحوّلات ذات نطاق المستخدم تحت دليلك المنزلي — خارج ذلك الجذر. وقبل أن يكتب التثبيت أيّ ملف، يطبع الأمر الأهداف الفعلية مُجمَّعةً تحت عنوانين: تلك الموجودة داخل جذر المشروع، وتلك الموجودة تحت دليلك المنزلي. ويسرد عنوانٌ ثالث المجلّدات المشتركة في دليلك المنزلي التي تكتبها المحوّلات ذات نطاق المشروع، خارج --project: مجلد المهارات و~/.config/apothem/ (انظر المجلّدات في دليلك المنزلي). والاستثناء الوحيد هو --clean: فخطوة التنظيف الكامل فيه تعمل قبل هذه المعاينة، فتكتب نسخة احتياطية وتُزيل الأهداف السابقة، كما هو موضّح أدناه.

عندما يكتب الاختيار خارج جذر المشروع، سواء إلى مجلد محوّل متجذّر في الدليل المنزلي أو إلى مجلد مشترك، يحرس تأكيدٌ تفاعلي عمليات الكتابة المتجذّرة في الدليل المنزلي. ويمضي كلٌّ من --yes، والصدفة غير التفاعلية (دون TTY)، و--dry-run، و--format json دون مطالبة. ولا يكتب --dry-run وحده شيئًا؛ أما --format json فيتخطّى المعاينة ومطالبة التأكيد لكنه يُجري عمليات الكتابة مع ذلك. ورفض مطالبة الدليل المنزلي يُلغي التثبيت قبل كتاباته. ومع --clean، تعمل خطوة التنظيف الكامل أولًا ضمن تأكيدها الخاص بكل هدف: تكتب نسخة احتياطية تحت ~/.apothem/backups وتُزيل الأهداف التي تؤكّدها. وتبقى تلك الإزالات والنسخة الاحتياطية في مكانها عند رفض مطالبة التثبيت.

المجلّدات في دليلك المنزليCopy Anchor Link

تكتب سبعة محوّلات ذات نطاق المشروع مهارات Apothem، والقواعد والقوالب التي تُحيل إليها المهارات، إلى مجلّدات في دليلك المنزلي:

cursor, github-copilot, windsurf, zed  ->  ~/.agents/skills/ (codex writes it too)
codebuddy                               ->  ~/.codebuddy/skills/
kiro                                    ->  ~/.kiro/skills/
trae                                    ->  ~/.trae/skills/
all seven                               ->  ~/.config/apothem/rules/ and templates/ (codex uses them too)

• يختار --project ملف القواعد والمشروعَ الذي ينتمي إليه التثبيت. ولا يغيّر المكان الذي تذهب إليه المهارات: فالتثبيت مع --project A والتثبيت مع --project B يكتبان المجلّدات نفسها.
• كل تثبيت يسمّي مجلّدًا يكتب الملفات نفسها. ويجدها التثبيت الثاني ويُبلغ عن unchanged، ولا يهمّ الترتيب الذي تثبّت به.
• تُكتَب المجلّدات المنزلية قبل أي شيء في المشروع. فإن فشلت كتابةٌ هناك، يتوقّف تثبيت المحوّل مع الخطأ ويبقى المشروع دون تغيير. ويسمّي الخطأ المسار المُعترِض، مثل ملف اسمه ~/.agents حيث ينبغي أن يكون المجلّد.
• يُكتَب كل مجلّد مهارة في مجلّد مخفي .<name>.apothem-staging بجواره ثم تُعاد تسميته إلى مكانه عند اكتماله، فلا تترك كتابةٌ فاشلة أو مقطوعة أبدًا مجلّد مهارة مكتوبًا جزئيًا تحت اسمه النهائي. شغّل التثبيت مجدّدًا لإكماله؛ فهو يستبدل أي مجلّد تجهيز متبقٍّ.
• الرابط الرمزي عند أحد هذه المجلّدات أو فوقه، كالذي تُنشئه أدوات إدارة ملفات الإعداد النقطية لـ ~/.config أو ~/.agents، يُتَّبَع حين يقود إلى مكان داخل دليلك المنزلي. أما الرابط الذي يخرج من دليلك المنزلي فيوقف التثبيت مع target escapes the allowed materialization root، وكذلك الرابط الموجود داخل مجلّد مهارة.
• لا يضيف التثبيت أي ملف مهارة أو قاعدة إلى مستودعك. ويحصل المشروع على ملف القواعد الخاص بالمحوّل، إضافةً إلى مجلّد البيانات .apothem/ الذي يُنشئه كل تثبيت على مستوى المشروع.
• مجلّد المهارة الذي يحمل اسم مهارة من Apothem ولم يكتبه Apothem يُتخطّى. ويطبع التثبيت سطر Warning: ويحمل غلاف --format json مُدخَلًا في warnings يحمل "outcome": "warning" و"operation": "skill_conflict" ويسمّي المجلّد. أعد تسمية المجلّد أو انقله، ثم شغّل update.
• يطبع كل تثبيت وتحديث وتشغيل تجريبي من هذا النوع ملاحظة Note: تسمّي المجلّدات التي يكتبها خارج --project. وفي غلاف JSON تكون مُدخَلًا في warnings يحمل "operation": "user_level_write" وقائمة paths.

ملاحظات القدراتCopy Anchor Link

لا يُسقِط كل محوّل إلا القدرات التي يدعمها إطار عمله أصليًا؛ أمّا القدرات التي لا سطح أصليًا لها فيُبلَّغ عنها، ولا تُستبعَد بصمت. وفي الوضع plain يكون ذلك ملاحظةً مُجمَّعة واحدة لكل إطار عمل (مثلًا Note: <harness> - 9 capabilities not projected; pass --verbose for detail)؛ ومع --verbose تطبع كل قدرة سطر تعليلها الخاص. وأي تحذير آخر من المحوّل يُطبَع هو أيضًا في الوضع plain على سطر Warning: خاص به، مثل تحذير Zed الذي يسمّي ملف تعليمات يحجبه الملف .rules الجديد. ويحمل غلاف --format json دائمًا مصفوفة warnings كاملةً بصرف النظر عن مستوى الإسهاب.

يطبع التثبيت والتحديث أيضًا تنبيهات استشارية على هيئة أسطر Note:. ولا يغيّر التنبيه الاستشاري أبدًا ما يكتبه التثبيت. عندما يكتب تثبيتٌ جذرًا مشتركًا، أي مسارًا تحمّله أدوات أخرى أيضًا (مثل مجلد المهارات ~/.agents/skills/)، تسمّي الملاحظة تلك الأدوات، وتضع بين قوسين الأداة التي لا تحمّل المسار إلا تحت شرط، مثل Open-Claw (only under its default state directory). والتثبيت الذي يكتب مجلّدًا تكتبه تثبيتات أخرى أيضًا (دور holder) يذكر أن المجلّد يبقى حتى إلغاء تثبيت آخر تثبيت لـ Apothem يستخدمه، ويسمّي التثبيتات التي تستخدمه الآن. وعندما يستهدف تثبيتٌ أداةً تحمّل بالفعل محتوى Apothem من الجذر المشترك لتثبيت آخر، تسمّي الملاحظة التثبيت الذي وضعه: المالك المُسجَّل ما دام لا يزال يستخدم المجلّد، وإلا فأقدم تثبيت يستخدمه. وفي غلاف --format json يكون كل تنبيه استشاري مُدخَلًا في warnings يحمل "outcome": "advisory" و"operation": "shared_root"؛ ويكون role فيه owner أو holder أو reader، ويسرد holders التثبيتات التي تستخدم المجلّد، ويسمّي owner_of_record المالك المُسجَّل.

ويطبع التثبيت الذي يسجّل خطّافات أيضًا ملاحظات عن ملف الخطّافات. فالتنبيه الاستشاري hook_review يسمّي الخطوة التي تحتاجها الأداة قبل أن تشغّل الخطّافات (إعادة تشغيل ومراجعة، أو منح الثقة لمساحة العمل)، أو خطر ملف خطّافات يُودِعه مستودعٌ ويسمّي مفسّر هذا الجهاز. ويظهر التنبيه الاستشاري hook_import لأداة تشغّل أيضًا الخطّافات الموجودة في ملفات إعدادات Claude Code، مثل تلك التي يكتبها تثبيت Apothem لـ Claude Code، ويسمّي مفتاح الأداة الخاص لإيقاف ذلك الاستيراد وما يوقفه المفتاح أيضًا. وكلٌّ منهما مُدخَل في warnings يحمل "outcome": "advisory"، وharness، وpath ملف الخطّافات، وmessage.

يحمل أمر الخطّاف مسار المشروع ومسار المفسّر داخل علامتي اقتباس مزدوجتين، وهو ما يقرؤه كلٌّ من sh وGit Bash وPowerShell. والمسار الذي يحتوي $، أو علامة اقتباس خلفية، أو علامة اقتباس مزدوجة، أو شرطة مائلة عكسية من شأنه أن يجعل الأمر يشغّل ملفًا مختلفًا، لذا يتوقّف التثبيت (و--dry-run) مع خطأ يسمّي المسار ولا يكتب شيئًا؛ انقل المشروع أو أعد تسميته ثم شغّله مجدّدًا. أما المسافة أو الفاصلة العليا في المسار فلا بأس بها.

تحصل خوادم MCP في الملف التعريفي على ثلاثة تنبيهات استشارية، يسمّي كلٌّ منها حقل الملف التعريفي المعنيّ:

لا يطبع تنبيه بيانات الاعتماد أبدًا القيمة التي عثر عليها. ولا تُعلَّم أبدًا قيمةٌ تحتوي مرجعًا من نوع ${...}.

إعدادات المُشغِّل التي تحمل تعليقاتCopy Anchor Link

بعض إعدادات أُطُر العمل ملفات تحرّرها أنت أيضًا، مثل settings.json، وopencode.json (الذي قد يكون بصيغة JSONC)، وopenclaw.json (JSON5)، وconfig.yaml. يدمج التثبيت مفاتيحه في هذه الملفات ويُبقي كل مفتاح أضفته.

يعيد الدمج كتابة الملف بصيغة JSON أو YAML عادية، وهذا من شأنه أن يُسقِط التعليقات، والفواصل اللاحقة، وصياغة JSON5. لذلك:

• عندما لا يغيّر الدمج أي قيمة (مثلًا، إذا كنت قد أضفت مفاتيح Apothem بنفسك مسبقًا)، يُترَك الملف كما هو بايتًا ببايت.
• عندما يتعيّن على الدمج تغيير قيمة في ملف يحمل تعليقات أو صياغة JSON5، أو في ملف لا يمكن تحليله إطلاقًا، لا يكتب التثبيت شيئًا لإطار العمل ذاك ويخرج بالرمز 1 مع رمز الخطأ config.unparseable. ويسمّي الحقل fix المفاتيح التي كان التثبيت سيضيفها، لتتمكّن من تحويل الملف إلى JSON أو YAML عادية، أو إضافة تلك المفاتيح يدويًا ثم إعادة التشغيل.
• عندما يحمل مفتاحٌ يملؤه التثبيت بخريطة (mapping) أو بقائمة (مثل skills.external_dirs في config.yaml) قيمةً مفردة (scalar)، أو شكل الحاوية الآخر، في ملفك، لا يكتب التثبيت شيئًا لإطار العمل ذاك ويخرج بالرمز 1 مع رمز الخطأ نفسه، لأن ملء المفتاح من شأنه أن يُهدِر قيمتك. ويسمّي الخطأ المفتاح؛ غيّره إلى الشكل الذي يسمّيه، أو أزِله، ثم أعد التشغيل. أما المفتاح الذي تركته فارغًا (skills: دون شيء تحته) فيُملأ.

الخياراتCopy Anchor Link

مخرجات JSONCopy Anchor Link

عند تمرير --json (أو --format json)، يُكتَب مستند JSON واحد إلى stdout:

{
  "schema_version": 1,
  "status": "success",
  "command": "install",
  "action": "installed",
  "harness": "claude-code",
  "profile_path": "C:\\Users\\Example\\.config\\apothem\\profile.yaml",
  "project": null,
  "files_written": ["C:\\Users\\Example\\.claude\\settings.json"],
  "results": [],
  "warnings": [],
  "error": null,
  "output_path": "C:\\Users\\Example\\.claude\\settings.json"
}

مع --dry-run، لا يُكتَب شيء ويسرد results كل مسار كان التثبيت سيكتبه، ولكلٍّ منها النتيجة التي كانت ستكون له (created أو updated أو unchanged)، ولملفٍ تحرّره أنت أيضًا، الفرق الموحّد في detail.diff — وهي الخطة نفسها التي يعرضها apothem diff:

{
  "schema_version": 1,
  "status": "dry_run",
  "command": "install",
  "action": "dry_run",
  "harness": "claude-code",
  "files_written": [],
  "results": [
    {
      "harness": "claude-code",
      "outcome": "created",
      "operation": "write_text",
      "path": "C:\\Users\\Example\\.claude\\settings.json",
      "message": "dry run: no filesystem changes made"
    }
  ],
  "warnings": [],
  "error": null
}

عند تمرير --clean، يحمل الغلاف إضافةً إلى ذلك كائن clean يصف مرحلة الإزالة — قائمة مآل كل هدف، وما إذا كان التشغيل معاينةً، ودليل النسخ الاحتياطي المختوم بالوقت (null في التشغيل التجريبي):

{
  "clean": {
    "dry_run": true,
    "backup_dir": null,
    "targets": [
      {
        "path": "C:\\Users\\Example\\.claude",
        "present": true,
        "removed": false,
        "skipped_reason": null
      }
    ]
  }
}

يعاين التشغيل التجريبي مع البداية النظيفة المرحلتين كلتيهما في مستند واحد: معاينة الإزالة تحت clean، ومعاينة الكتابة الجديدة تحت results.

تستخدم أخطاء التحقّق المتوقّعة الغلاف نفسه وتتضمّن كائن خطأ:

{
  "schema_version": 1,
  "status": "error",
  "command": "install",
  "harness": "all",
  "files_written": [],
  "error": {
    "code": "project.required",
    "field": "project",
    "reason": "project-scope harnesses require --project: cursor, gemini-cli, github-copilot, kimi-code, windsurf, codebuddy, kiro, trae, zed, glm.",
    "fix": "Pass --project PATH or select only user-scope harnesses."
  }
}

أمثلةCopy Anchor Link

apothem install --harness claude-code
apothem install --harness claude-code --dry-run
apothem install --harness cursor --project . --profile ~/profile.yaml --json
apothem install --harness all --project . --dry-run --json
apothem installing --harness claude-code   # continuous-form alias
apothem Installing --harness claude-code   # capitalized variant

رموز الخروجCopy Anchor Link

انظر أيضًاCopy Anchor Link

• apothem installing — اسم مستعار بصيغة الاستمرار لهذا الأمر (موثّق هنا؛ تقبل واجهة سطر الأوامر الصيغتين كلتيهما)
• apothem update — إعادة تطبيق الملف التعريفي الحالي على إطار عمل
• apothem verify — تأكيد أن المحوّل فعّال
• البدء — دليل التثبيت الكامل