مساحات العمل المُدارة

تمنح أشجار العمل المُدارة مهمة الوكيل فرع Git ونسخة عمل خاصة بها، من دون وضع أدلة مؤقتة داخل مستودع المصدر. ينشئها OpenClaw ضمن دليل حالته، ويسجلها في قاعدة بيانات الحالة المشتركة، ويلتقط لقطات لمحتوياتها المتعقبة وغير المتعقبة وغير المتجاهلة قبل الإزالة.

التخطيط والأسماء

توجد كل شجرة عمل في:

<openclaw-state-dir>/worktrees/<repo-fingerprint>/<name>

بصمة المستودع هي أول 16 محرفًا سداسيًا عشريًا من تجزئة SHA-256 محسوبة على دليل Git المشترك المتعارف عليه وعنوان URL للأصل. يجب أن يطابق الاسم المُقدَّم [a-z0-9][a-z0-9-]{0,63}. عند عدم تقديم اسم، ينشئ OpenClaw اسمًا يبدأ بـ wt- متبوعًا بثمانية محارف سداسية عشرية عشوائية.

ينشئ OpenClaw الفرع openclaw/<name> عند مرجع الأساس المطلوب. عند عدم تقديم مرجع أساس، يجلب origin، ويستخدم الفرع الافتراضي البعيد عند توفره، ويرجع إلى HEAD المحلي عندما يكون المستودع غير متصل أو لا يحتوي على مستودع بعيد صالح للاستخدام.

توفير الملفات المتجاهلة

أضف .worktreeinclude إلى جذر مستودع المصدر لنسخ ملفات محددة متجاهلة وغير متعقبة إلى شجرة عمل جديدة. يستخدم الملف صياغة أنماط gitignore، بنمط واحد في كل سطر، مع تعليقات تبدأ بـ #:

.env.localfixtures/generated/**

لا تكون مؤهلة إلا الملفات التي يبلغ Git بأنها متجاهلة وغير متعقبة معًا. تكون الملفات المتعقبة موجودة بالفعل عبر Git ولا تُنسخ أبدًا في هذه الخطوة. لا يستبدل OpenClaw ملفات الوجهة ولا يتبع الأدلة ذات الروابط الرمزية، ويحافظ على أوضاع الملفات المنسوخة.

تشغيل إعداد المستودع

إذا كان .openclaw/worktree-setup.sh موجودًا في مستودع المصدر وقابلًا للتنفيذ، يشغّله OpenClaw مع تعيين شجرة العمل الجديدة بوصفها دليله الحالي. يتلقى السكربت:

OPENCLAW_SOURCE_TREE_PATH=<source checkout>OPENCLAW_WORKTREE_PATH=<managed worktree>

يؤدي الخروج بقيمة غير صفرية إلى إلغاء الإنشاء وإزالة شجرة العمل والفرع الجديدين. هذا عقد محلي للمستودع؛ ولا يوجد مفتاح إعداد في OpenClaw له.

أشجار عمل الجلسات

ابدأ محادثة معزولة من مساحة عمل Git التابعة للوكيل النشط باستخدام جلسة مدعومة بشجرة عمل: فعّل Worktree في صفحة New session ضمن Control UI (التي توفر أيضًا أداة اختيار فرع الأساس واسمًا اختياريًا لشجرة العمل)، أو استخدم قائمة Chat actions على iOS أو إجراء التجاوز بجانب New Chat على Android. لا يتوفر الخيار إلا لوكيل مدعوم بـ Git عندما يمتلك العميل هذه الإمكانية؛ أما العملاء الذين لا يمكنهم إجراء فحص تمهيدي لها فيعرضون خطأ Gateway بدلًا من ذلك.

يمكن لوكلاء البرمجة أيضًا استدعاء spawn_task عندما يكتشفون عمل متابعة مؤكدًا خارج المهمة الحالية. يعرض Control UI شريحة اقتراح من دون بدء أي شيء، بينما يعرض TUI المدعوم بـ Gateway مطالبة تفاعلية بالإجراءات نفسها. يؤدي تحديد Start in worktree إلى إنشاء شجرة عمل جديدة مملوكة للجلسة من المشروع المقترح وإرسال المطالبة المستقلة بوصفها أول دورة فيها؛ ولا يؤدي رفض الاقتراح إلى أي تغيير في المستودع. الاقتراحات ومعرّفاتها مؤقتة ولا تستمر بعد إعادة تشغيل Gateway.

لا يتيح OpenClaw هذه الأدوات إلا لجلسات المشغّل التي تحتوي على واجهة Gateway قابلة للتفاعل. لا تتلقاها جلسات القنوات وجلسات TUI المحلية أو المضمنة إلى أن تمتلك تلك الواجهات عقد إجراءات مهام محمولًا ومحدد الأنواع.

تكون شجرة العمل المُدارة الناتجة مملوكة للجلسة، وتستخدم كل عملية تشغيل للوكيل في تلك الجلسة نسخة العمل الخاصة بها. عندما تكون مساحة العمل دليلًا فرعيًا من المستودع، تُثبّت شجرة العمل عند جذر المستودع وتعمل الجلسة من الدليل الفرعي المطابق داخلها. يستخدم إنشاء شجرة عمل الجلسة نطاق operator.write الخاص بالطريقة، لكن خطوة .openclaw/worktree-setup.sh لا تعمل إلا للمتصلين ذوي نطاق operator.admin لأنها تنفذ شيفرة المستودع؛ ويظل توفير .worktreeinclude مطبقًا على كل متصل. لا تؤدي إزالة الجلسة إلى إزالة شجرة العمل إلا عندما يمكن فعل ذلك من دون فقدان. تظل أشجار العمل غير النظيفة أو الفروع التي تحتوي على تثبيتات غير مدفوعة متاحة؛ وتلتقط عملية التنظيف كل ساعة لقطات لأشجار عمل الجلسات بعد 7 أيام من الخمول، مع اعتبار نشاط الجلسة الحديث نشاطًا لشجرة العمل. تظل أشجار العمل المُزالة قابلة للاستعادة من لقطاتها كما هو موضح أدناه.

قد يتضمن sessions.create مسار cwd مطلقًا مع worktree: true عندما تستهدف المهمة مشروعًا غير مساحة عمل الوكيل المُعدّة. يتطلب مسار المضيف الصريح هذا نطاق operator.admin؛ بينما يظل إنشاء محادثة شجرة عمل عادية ضمن نطاق operator.write ومثبتًا على مساحة العمل المُعدّة.

يقبل sessions.create أيضًا الخيارين worktreeBaseRef وworktreeName إلى جانب worktree: true لاختيار مرجع الأساس واسم شجرة العمل (ويصبح الفرع openclaw/<name>)، ويظل كلاهما ضمن نطاق operator.write. تُعاد شجرة العمل المنشأة ضمن نتيجة الإنشاء وتُحفظ في صف الجلسة بالشكل worktree: { id, branch, repoRoot }، بحيث يمكن لقوائم الجلسات عرض نسخة العمل والفرع. عند حذف جلسة، يُبلّغ عن نسخة عمل غير نظيفة جرى الاحتفاظ بها باستخدام worktreePreserved بدلًا من تركها بصمت.

اللقطات والتنظيف والاستعادة

تنشئ الإزالة أولًا تثبيتًا اصطناعيًا يحتوي على الملفات المتعقبة وغير المتعقبة وغير المتجاهلة، وتثبّته عند refs/openclaw/snapshots/<id>. تُستبعد الملفات التي يتجاهلها Git من قاعدة بيانات كائنات المستودع؛ وتُنسخ الملفات المحددة بواسطة .worktreeinclude مرة أخرى أثناء الاستعادة. إذا فشل إنشاء اللقطة، تتوقف الإزالة. يمكن للحذف القسري الصريح المتابعة من دون لقطة.

يطبق OpenClaw قواعد التنظيف التالية:

• عند نهاية التشغيل، لا يزيل شجرة عمل إلا عندما يكون ناتج git status --porcelain فارغًا ولا يعثر git log HEAD --not --remotes --oneline على أي تثبيتات غير مدفوعة. وإلا فإنه يحرر قفل النشاط فقط.
• يلتقط التنظيف كل ساعة لقطات لأشجار العمل غير المقفلة والمملوكة لـ Workboard أو للجلسات، ويزيلها إذا ظلت خاملة لأكثر من 7 أيام، حتى عندما تكون غير نظيفة. لا تُزال أشجار العمل اليدوية تلقائيًا أبدًا.
• تظل سجلات اللقطات قابلة للاستعادة لمدة 30 يومًا. بعد ذلك يحذف التنظيف مرجع اللقطة وصف السجل.
• يحمي قفل عملية OpenClaw نشطة وأي قفل أجنبي أو غير معروف لشجرة عمل Git شجرة العمل من جمع المهملات.

تعيد الاستعادة إنشاء openclaw/<name> عند التثبيت الأصلي السابق للّقطة، ثم تعيد بناء اختلافات اللقطة كتعديلات غير مرحّلة وملفات غير متعقبة. يُبقي هذا تثبيت اللقطة الاصطناعي خارج سجل الفرع. يظل مرجع اللقطة مسجلًا لإثبات المصدر.

CLI

openclaw worktrees list [--json]openclaw worktrees create <repo-root> [--name <name>] [--base-ref <ref>] [--json]openclaw worktrees remove <id> [--force] [--json]openclaw worktrees restore <id> [--json]openclaw worktrees gc [--json]

توفر صفحة Worktrees ضمن Settings في Control UI الإجراءات نفسها، بالإضافة إلى الإنشاء باستخدام أداة اختيار فرع الأساس، وتعرض مالك كل شجرة عمل (يدويًا، أو Workboard، أو الجلسة المالكة مع رابط إلى محادثتها)، وتوفر إعادة محاولة قسرية عندما تبلغ الإزالة عن فشل اللقطة.

طرق Gateway

يتطلب worktrees.list نطاق operator.read، وتتطلب الطرق التي تُجري تغييرات نطاق operator.admin. يحتاج worktrees.branches إلى operator.write لمساحات عمل الوكلاء المُعدّة، بينما يتطلب أي مسار مضيف آخر نطاق operator.admin (مطابقًا لشرط cwd في sessions.create). يقرأ المراجع الموجودة فقط ولا يجلب أبدًا، وتُعاد الفروع الموجودة عن بُعد فقط مؤهلة باسم المستودع البعيد (origin/feature-a) بحيث يمكن استخدام كل اسم مُعاد بوصفه مرجع أساس.

مساحات عمل Workboard

يمكن لـ Plugin Workboard المضمن تجسيد مساحة عمل بطاقة بوصفها شجرة عمل مُدارة:

{  "kind": "worktree",  "path": "/absolute/path/to/source-checkout",  "branch": "main"}

يحدد path نسخة عمل Git المصدرية. ويكون branch اختياريًا ويصبح مرجع الأساس. عندما يبدأ الإرسال عامل البطاقة، ينشئ Workboard أو يعيد استخدام wb-<card-id>، ويشغّل الوكيل الفرعي مع نسخة العمل المُدارة بوصفها دليل عمله، ويكتب المسار والفرع المحسومين مرة أخرى في البطاقة. يتطلب التجسيد الذي يشغّله Gateway نطاق operator.admin. عند نهاية التشغيل، لا يزيل Workboard نسخة العمل إلا عندما يمكن إثبات عدم فقدان أي شيء؛ ويظل العمل غير النظيف أو التثبيتات غير المدفوعة متاحة.

ترفض الوكلاء المضمنة والمعزولة حاليًا دليل عمل لمهمة يقع خارج مساحة عمل الوكيل المُعدّة. استخدم وكيلًا مستهدفًا غير معزول لبطاقات Workboard ذات أشجار العمل المُدارة إلى أن يدعم وقت تشغيل العزل تركيبًا إضافيًا لنسخة العمل.