درخت‌های کاری مدیریت‌شده

درخت‌های کاری مدیریت‌شده به هر وظیفهٔ عامل، شاخه و نسخهٔ تسویه‌شدهٔ git اختصاصی می‌دهند، بدون اینکه دایرکتوری‌های موقت درون مخزن مبدأ قرار گیرند. OpenClaw آن‌ها را زیر دایرکتوری وضعیت خود ایجاد می‌کند، در پایگاه دادهٔ وضعیت مشترک ثبت می‌کند و پیش از حذف، از محتوای ردیابی‌شده و ردیابی‌نشدهٔ نادیده‌گرفته‌نشدهٔ آن‌ها عکس فوری می‌گیرد.

چیدمان و نام‌ها

هر درخت کاری در مسیر زیر قرار دارد:

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

اثر انگشت مخزن، ۱۶ نویسهٔ هگزادسیمال نخست هش SHA-256 از دایرکتوری مشترک متعارف git و نشانی مبدأ است. نام ارائه‌شده باید با [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 همچنان برای همهٔ فراخوانندگان اعمال می‌شود. حذف نشست فقط زمانی درخت کاری را حذف می‌کند که این کار بدون اتلاف باشد. درخت‌های کاری تغییریافته یا شاخه‌های دارای کامیت‌های ارسال‌نشده در دسترس باقی می‌مانند؛ پاک‌سازی ساعتی پس از ۷ روز بی‌کاری از درخت‌های کاری نشست عکس فوری می‌گیرد و فعالیت اخیر نشست را فعالیت درخت کاری محسوب می‌کند. درخت‌های کاری حذف‌شده مطابق توضیحات زیر از عکس‌های فوری خود قابل بازیابی می‌مانند.

sessions.create می‌تواند هنگام هدف‌گیری وظیفه‌ای در پروژه‌ای غیر از فضای کاری پیکربندی‌شدهٔ عامل، یک cwd مطلق را همراه با worktree: true دربرگیرد. آن مسیر صریح میزبان به operator.admin نیاز دارد؛ ایجاد عادی گفت‌وگوی درخت کاری همچنان operator.write است و به فضای کاری پیکربندی‌شده لنگر می‌ماند.

sessions.create همچنین همراه با worktree: true مقادیر worktreeBaseRef و worktreeName را برای انتخاب ارجاع پایه و نام درخت کاری می‌پذیرد (شاخه به 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 و نشست که بیش از ۷ روز بی‌کار بوده‌اند عکس فوری می‌گیرد و آن‌ها را حذف می‌کند، حتی اگر تغییریافته باشند. درخت‌های کاری دستی هرگز به‌طور خودکار حذف نمی‌شوند.
• رکوردهای عکس فوری تا ۳۰ روز قابل بازیابی باقی می‌مانند. سپس پاک‌سازی، ارجاع عکس فوری و ردیف دفتر ثبت را حذف می‌کند.
• قفل یک فرایند زندهٔ 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 در Control UI زیر Settings همان کنش‌ها را به‌همراه ایجاد با انتخابگر شاخهٔ پایه ارائه می‌دهد، مالک هر درخت کاری را نشان می‌دهد (دستی، 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 از یک عامل مقصد بدون سندباکس استفاده کنید.