سير عمل التثبيت

تدفُّق التثبيتCopy Anchor Link

flowchart TD
    accTitle: Apothem install workflow
    accDescr: Top-down flowchart of the apothem install command from CLI invocation through adapter lookup, profile load, adapter install call, native config write, and a follow-up apothem verify check that the operator runs.
    A[apothem install --harness X] --> B[Resolve adapter through registry]
    B --> C[Load and validate profile YAML<br/>before writes]
    C --> D[Adapter.install(profile, project)]
    D --> E[Write native config and support cohorts]
    E --> F[Operator runs: apothem verify --harness X]
    F --> G{All checks pass?}
    G -- yes --> H[Done]
    G -- no --> I[Report failures]

تدفُّق التحديثCopy Anchor Link

عند apothem update --harness X:

1. يُحمِّل ويتحقَّق من ~/.config/apothem/profile.yaml أو --profile PATH.
2. يحلّ إطار العمل المُحدَّد أو all عبر السجلّ المركزي.
3. يتحقَّق من خطّة التحويل الكاملة قبل أول عملية كتابة.
4. يستدعي Adapter.update(profile, project=...).
5. يُبلِغ عن النتائج: مُنشأ، ومُحدَّث، وبلا تغيير، ومُتخطّى، وتحذير، وخطأ.

تدفُّق إلغاء التثبيتCopy Anchor Link

عند apothem uninstall --harness X:

1. يستدعي Adapter.uninstall().
2. يزيل المُحوِّل الملفّات التي كتبها فقط؛ ويبقى الملف التعريفي المشترك بصيغة YAML والملفّات غير المتعلِّقة التي كتبها المُشغِّل دون مساس.
3. تُنسَخ الذاكرةُ والسياقاتُ ومخازنُ التعلّم في دليل العمل المشترك احتياطيًا وتُزال حين يكون هذا آخرَ إطار عمل مُثبَّت فيه. وتُزال من الموقع الذي سجّله التثبيت. ولا يُزال دليل plans/ أبدًا.

حلّ النطاقCopy Anchor Link

يكتب كل مُحوِّل إلى جذر تثبيته الثابت الخاص به: المنزل الشخصي للمستخدم لمُحوِّلات نطاق المستخدم، والمسار المحلّي للمشروع لمُحوِّلات نطاق المشروع. لا تكشف واجهة CLI عن راية --scope؛ وتتطلّب مُحوِّلات نطاق المشروع --project <path>. وتكتب سبعة من مُحوِّلات نطاق المشروع أيضًا مجلّدات مشتركة في المنزل الشخصي للمستخدم، مثل ~/.agents/skills/ و~/.config/apothem/، قبل أن تكتب ملف المشروع، ولا يُغيّر --project مكان كتابتها. ويسردها مرجع التثبيت. وكل وجهة مُوثَّقة في site/content/docs/harnesses/<harness>.mdx.

معالجة الأخطاءCopy Anchor Link

تتحقّق عمليّات التثبيت/التحديث قبل الكتابة، وتُنشئ نسخة احتياطية من الأهداف المُطابِقة الموجودة قبل استبدالها، ولا تدمج إلا الإدخالات الفرعية التي يديرها Apothem في أدلّة الاكتشاف المشتركة. وينفّذ --dry-run التحقّق نفسه، ويعيد النتيجة التي كانت ستسجّلها كل كتابة، مثل created أو updated، دون إنشاء أي أدلّة أو ملفّات.

قابلية التراجع (النسخ الاحتياطي والتراجع)Copy Anchor Link

كل تمريرة تثبيت قابلة للتراجع. تُلتقَط البايتات المُستبدَلة في جذر النسخ الاحتياطي الخاص بـApothem، وتُسجَّل التمريرة في دفتر إطار العمل تحت مُعرِّف تثبيت بصيغة ULID؛ ويختار apothem rollback تمريرةً مُسجَّلة ويستعيد تلك النسخ الاحتياطية المُلتقَطة.

%% provenance: hand-authored %%
%% verified: 2026-07-06 %%
%% cross-reference: this page's Error handling section (back up before replace); /docs/cli-reference/rollback %%
flowchart LR
    accTitle: Apothem backup and rollback lifecycle
    accDescr: At install time each replaced target's prior bytes are captured into the Apothem backup root and the pass is recorded in the harness ledger under a ULID install id. The rollback command selects a recorded install pass by latest or install-id, restores every captured backup from the backup root, and appends a rollback record to the ledger.
    subgraph Install
        direction TB
        I1["Back up existing targets<br/>before replacement"] --> I2["Apothem backup root"]
        I1 --> I3["Ledger install record<br/>ULID install-id"]
    end
    subgraph Rollback
        direction TB
        R1["Select install pass<br/>--last or --install-id ULID"] --> R2["Restore captured backups<br/>from the backup root"]
        R2 --> R3["Append rollback record<br/>to the harness ledger"]
    end
    I2 -.->|captured bytes| R2
    I3 -.->|resolves pass| R1