Swarms — انشعاب عامل‌ها و هماهنگ‌سازی در حالت کد

وضعیت: منتشرشده — با docs/tools/swarm.md جایگزین شده است. این سند به‌عنوان سابقه طراحی پیاده‌سازی باقی می‌ماند.

1. چیستی و چرایی

یک swarm مجموعه‌ای از چندین زیرعامل است که به‌صورت قطعی از طریق یک اسکریپت حالت کد هماهنگ‌سازی می‌شوند: انشعاب N خواننده، راستی‌آزمایی خصمانه یافته‌ها، ترکیب نتایج از طریق یک اولویت‌بند حالت‌مند و تکرار بر اساس دروازه‌های تصمیم‌گیری. جریان کنترل (Promise.all، while، if) خودِ هماهنگ‌سازی است — عامدانه هیچ DSL گرافی، حالت جدید یا سطح ابزار سطح‌بالای جدیدی وجود ندارد.

حالت کد OpenClaw ‏(QuickJS-WASI، عکس فوری/ازسرگیری، درخواست‌های پل) زیرساخت زیربنایی است. یک فراخوانی پل متوقف‌شده پس از عکس فوری VM و راه‌اندازی مجدد Gateway دوام می‌آورد و دقیقاً از همان نقطه‌ای که متوقف شده بود از سر گرفته می‌شود — قدرتمندتر از طراحی‌های مبتنی بر بازپخش ژورنال، بدون هیچ محدودیت قطعی‌بودن برای اسکریپت‌ها.

نام‌گذاری: نام محصول/مستندات Swarm است. شناسه‌های کد بدون تغییر می‌مانند: API مهمان agents.*، پیکربندی tools.swarm، ستون‌های گروه swarm.

2. تصمیم‌ها (نگه‌دارنده، 2026-07-17)

• هزینه: سقف‌های پیکربندی اعمال می‌شوند؛ بودجه توکن برای هر swarm اختیاری است. بودجه اجباری وجود ندارد.
• تأییدها: فرزندان به‌صورت بسته در برابر خطا / غیرتعاملی اجرا می‌شوند. اقداماتی که به تأیید نیاز دارند رد می‌شوند؛ ردشدن در نتیجه فرزند گزارش می‌شود؛ اسکریپت تصمیم می‌گیرد. انشعاب عامل‌ها اپراتور را با درخواست‌های مکرر آزار نمی‌دهد.
• نسخه v1 فقط شامل اسکریپت‌های موردیِ نوشته‌شده توسط مدل است. گردش‌کارهای ذخیره‌شده/نام‌گذاری‌شده و نقطه ورود CLI/cron: بعداً (حالت کد بدون رابط از قبل برای cron وجود دارد).
• هویت فرزند: به‌طور پیش‌فرض عامل worker اختصاصی از طریق پیکربندی tools.swarm.defaultAgentId (که در برابر فهرست مجاز مقصدهای موجود زیرعامل اعتبارسنجی می‌شود)؛ بازنویسی agentId برای هر spawn. هسته هیچ شناسه عامل همراهی ارائه نمی‌کند؛ مستندات یک پیکربندی عامل سبک worker را توصیه می‌کنند.
• هیچ تغییری در منبع Codex وجود ندارد. چارچوب Codex از الگوی spawn/wait استفاده می‌کند (§8).

3. نمای کلی معماری

اسکریپت حالت کد (QuickJS VM، gateway)          اسکریپت Codex V8 (فرایند codex)  agents.run(...) ── فراخوانی پل متوقف‌شده       tools.sessions_spawn / tools.agents_wait        │                                                │ RPC آیتم/ابزار/فراخوانی (هرکدام ≤600s)        ▼                                                ▼             هسته (مستقل از چارچوب، این مخزن)  sessions_spawn {collect:true, outputSchema, fastMode, groupId}  agents_wait {ids, timeoutSeconds}        │  رجیستری زیرعامل (SQLite): رکوردهای تکمیل گردآورنده، شناسه گروه swarm        │  فرزندان = نشست‌های معمولی زیرعامل (محدودشده به lane، تأییدهای بسته در برابر خطا)        │  sessions.changed SSE ──► نقطه‌های Control UI / نوار کناری / پیام وضعیت کانال

یک مالک مرجع برای معناشناسی spawn/complete/settle (ابزارهای هسته + رجیستری). دو انتقال انتظار: QuickJS یک فراخوانی پل را به‌طور نامحدود متوقف می‌کند (عکس فوری)؛ Codex در RPCهای محدود، agents_wait را نظرسنجی می‌کند.

4. دروازه پیکربندی (v1)

tools.swarm جدید (سراسری + بازنویسی برای هر عامل، با همان الگوی ادغام tools.codeMode):

"tools": {  "swarm": {    "enabled": false,            // دروازه اصلی، به‌طور پیش‌فرض خاموش    "maxConcurrent": 8,          // فرزندانی که هم‌زمان اجرا می‌شوند (سقف lane مربوط به swarm)    "maxChildrenPerGroup": 50,   // فرزندان فعال در هر گروه swarm    "maxTotalPerGroup": 200,     // تعداد spawn در طول عمر هر گروه (پشت‌بند مهار اجرای خارج از کنترل)    "waitTimeoutSecondsMax": 600,    "defaultAgentId": ""         // اختیاری؛ شناسه عامل فرزند هنگامی که spawn فاقد agentId است  }}

• Zod: اجتماع boolean | strict object مانند CodeModeSchema (src/config/zod-schema.agent-runtime.ts)؛ swarm: true → {enabled: true}.
• نوع‌ها در src/config/types.tools.ts (هم برای هر عامل و هم tools سطح‌بالا)، برچسب‌ها در schema.labels.ts، راهنما در schema.help.runtime.ts.
• تابع کمکی تفکیک resolveSwarmConfig(cfg, agentId) مشابه resolveCodeModeConfig ‏(src/agents/code-mode.ts:215) که همه اعداد را محدود می‌کند.
• آثار دروازه هنگام غیرفعال‌بودن: ابزار agents_wait در کاتالوگ‌ها وجود ندارد؛ پارامترهای collect/outputSchema/fastMode/groupId در sessions_spawn با خطایی واضح که کلید پیکربندی را نام می‌برد رد می‌شوند. هیچ رفتار دیگری تغییر نمی‌کند.
• defaultAgentId از طریق resolveSubagentAllowedTargetIds (src/agents/subagent-target-policy.ts) اعتبارسنجی می‌شود؛ شناسه ناشناخته → خطای spawn، نه بازگشت به گزینه جایگزین.

5. هسته: spawn در حالت گردآورنده + agents_wait ‏(v1)

5.1 افزوده‌های sessions_spawn (همگی مشروط به فعال‌بودن swarm)

• collect: boolean — هنگامی که true باشد، اجرای فرزند با expectsCompletionMessage: false و یک رکورد تکمیل گردآورنده به‌جای تحویل اعلان/هدایت ثبت می‌شود. ابزار بلافاصله { runId, sessionKey } را برمی‌گرداند. هیچ اتصال کانال/رشته‌ای وجود ندارد.
• outputSchema: object — JSON Schema. یک ابزار ساختگی structured_output به سطح ابزار فرزند افزوده می‌شود؛ پیوست اعلان سیستمی به آن دستور می‌دهد دقیقاً یک‌بار با نتیجه نهایی خود این ابزار را فراخوانی کند. در صورت شکست اعتبارسنجی، فرزند یک‌بار برای تلاش مجدد تلنگر دریافت می‌کند؛ پس از آن رکورد تکمیل شامل structured: undefined به‌همراه متن خام و یک schemaError خواهد بود.
• fastMode: true | "auto" | false — از طریق resolveSubagentModelAndThinkingPlan (src/agents/subagent-spawn-plan.ts) در کنار مدل/تفکر به وصله نشست فرزند منتقل می‌شود و از محور موجود FastMode (src/shared/fast-mode.ts) استفاده می‌کند. حذف‌شده = ارث‌بری.
• groupId: string — مهر گروه swarm. مقدار پیش‌فرض swarm:<requesterSessionKey>:<runId-of-requesting-run> است. روی رکورد رجیستری و ردیف نشست فرزند نگه‌داری می‌شود. برای سقف‌ها، فهرست‌کردن، بایگانی دسته‌ای و نقطه‌ها استفاده می‌شود.
• label: string از قبل وجود دارد — در نقطه‌ها و subagents list نمایش داده می‌شود.
• شناسه عامل فرزند: params.agentId → در غیر این صورت tools.swarm.defaultAgentId → در غیر این صورت عامل درخواست‌کننده (رفتار موجود).

5.2 تأییدهای بسته در برابر خطا

فرزندان گردآورنده با زمینه تأیید غیرتعاملی اجرا می‌شوند: هر فراخوانی ابزاری که به تأیید اپراتور نیاز داشته باشد به‌صورت یک رد ساخت‌یافته (approval_required) که برای فرزند قابل مشاهده است تفکیک می‌شود و انتظار می‌رود فرزند مانع را در نتیجه خود گزارش کند. پیاده‌سازی: استفاده مجدد از زیرساخت سیاست تأیید اجرای دستور/ابزار با تفکیک‌کننده اجباری deny برای اجراهای فرزند در حالت گردآورنده. هیچ رویداد تأییدی از فرزندان گردآورنده به سطوح اپراتور ارسال نمی‌شود.

5.3 ابزار agents_wait (جدید، مشروط به دروازه)

agents_wait({ ids: string[], timeoutSeconds?: number })→ {    completed: [{ runId, status: "done"|"failed"|"killed"|"timeout",                  result: string, structured?: unknown, schemaError?: string,                  sessionKey, label?, usage?: {inputTokens, outputTokens} }],    pending: string[]  }

• به‌محض تکمیل حداقل یک شناسه (معناشناسی نخستین تکمیل / رقابت که پایپ‌لاین‌ها را ممکن می‌کند)، یا هنگام پایان مهلت با completed: [] بازمی‌گردد.
• مقدار پیش‌فرض timeoutSeconds برابر 30 است و به waitTimeoutSecondsMax محدود می‌شود.
• توان‌تکرار: شناسه‌های از قبل تکمیل‌شده رکوردهایشان را دوباره برمی‌گردانند (رکوردها تا زمان بایگانی گروه نگه داشته می‌شوند). شناسه ناشناخته → ورودی خطای مختص شناسه، نه پرتاب استثنا.
• مالکیت: فقط نشستی که یک اجرا را spawn کرده است (یا زنجیره والد آن) می‌تواند منتظرش بماند — همان قاعده مالکیت wait در حالت کد (code-mode.ts:1684).
• رجیستری: رکوردهای تکمیل در ذخیره SQLite موجود رجیستری زیرعامل (subagent-registry.store.sqlite.ts) قرار دارند — فیلدهای جدید، بدون ذخیره جدید و بدون افزایش نسخه طرح‌واره (فقط ستون‌های افزایشی؛ محدودیت §9 را ببینید).

5.4 اعمال سقف‌ها

• maxConcurrent: فرزندان گردآورنده در lane موجود زیرعامل اجرا می‌شوند، اما به‌ازای هر گروه swarm شمارش می‌شوند؛ spawnهای فراتر از سقف در صف FIFO قرار می‌گیرند (سمت میزبان، در مسیر spawn — runId بلافاصله برگردانده می‌شود و اجرا با آزادشدن یک جایگاه آغاز می‌شود).
• maxChildrenPerGroup / maxTotalPerGroup: پس از عبور از سقف، spawn با یک خطای نوع‌دار رد می‌شود؛ متن خطا کلید پیکربندی را نام می‌برد.
• عمق: فرزندان گردآورنده معناشناسی DEFAULT_SUBAGENT_MAX_SPAWN_DEPTH را حفظ می‌کنند (فرزندان برگ هستند، مگر اینکه تودرتویی صراحتاً پیکربندی شده باشد).

6. قرارداد آزمون (v1، lane A)

• واحد: تفکیک/محدودسازی پیکربندی؛ ردشدن در دروازه هنگام غیرفعال‌بودن؛ پیش‌فرض‌گذاری groupId؛ اعمال سقف (صف + رد)؛ معناشناسی رقابت wait؛ توان‌تکرار wait؛ رد مالکیت؛ اعتبارسنجی خروجی ساخت‌یافته + تلنگر برای تلاش مجدد + مسیر schemaError؛ انتقال fastMode به وصله نشست؛ اعتبارسنجی defaultAgentId.
• یکپارچه‌سازی (vitest، زمان‌اجرای مدل شبیه‌سازی‌شده): spawn کردن 3 فرزند گردآورنده، انتظار در یک حلقه، بررسی ترتیب نخستین تکمیل و تخلیه نهایی؛ شبیه‌سازی راه‌اندازی مجدد gateway: بارگذاری مجدد رجیستری → wait از رکورد تکمیل ماندگارشده تفکیک می‌شود.
• همه آزمون‌ها در *.test.ts هم‌مکان هستند؛ هیچ فراخوانی مدل زنده‌ای وجود ندارد.

7. سطح مهمان QuickJS ‏(lane B، پس از هسته)

• متغیرهای سراسری مهمان در CONTROLLER_SOURCE (src/agents/code-mode.worker.ts:190-374) نصب می‌شوند و نام‌های رزروشده در code-mode-namespaces.ts افزوده می‌شوند:
  • agents.run(prompt, opts) → Promise<result|structured> — میان‌بُر: spawn گردآورنده + انتظار متوقف‌شده روی یک متد پل اختصاصی (agentWait) که میزبان آن را هنگام تکمیل خاتمه می‌دهد (بدون نظرسنجی؛ ایمن برای عکس فوری).
  • agents.session(system, opts) → Promise<handle>؛ handle.send(input, opts) → Promise<...>؛ handle.close(). (نسخه v1.1 — پس از run() منتشر می‌شود؛ از mode:"session" + رکوردهای گردآورنده برای هر نوبت استفاده می‌کند.)
  • phase(title)، log(message) — اعلان‌های پل بدون انتظار برای نتیجه → رویدادهای پیشرفت swarm.
• متدهای پل افزوده‌شده به CodeModeBridgeMethod ‏(code-mode.ts:91): agentSpawn، agentWait، swarmNote. ‏agentSpawn/agentWait ذاتاً برای بازپخش ایمن هستند: کلید توان‌تکرار (codeModeRunId, bridgeId) روی رکورد رجیستری ذخیره می‌شود؛ راه‌اندازی مجدد از تکمیل‌های ماندگارشده دوباره خاتمه می‌یابد و هرگز دو بار spawn نمی‌کند.
• فراخوانی‌های پل در انتظار agentWait، ‏TTL عکس فوری اجرا را افزایش می‌دهند (مجموعه عامل‌های در انتظار سیگنال است؛ بدون پرچم).
• فایل مجازی API.read("agents.d.ts") سطح نوع‌دار + الگوهای انشعاب / دروازه / چرخه (createCodeModeApiVirtualFiles، code-mode-namespaces.ts:876) را مستند می‌کند.

8. تصویرسازی چارچوب Codex ‏(lane بعدی)

• sessions_spawn (با پارامترهای جدید) و agents_wait از پل ابزار پویا موجود عبور می‌کنند؛ در اسکریپت‌های حالت کد Codex، آن‌ها به‌طور خودکار به‌شکل tools.* ظاهر می‌شوند (راستی‌آزمایی‌شده: codex-rs/code-mode/src/runtime/globals.rs:14-65، codex-rs/core/src/tools/spec_plan.rs:448-507).
• agents_wait کلاس مهلت طولانی ابزار پویا را دریافت می‌کند (سقف 600s؛ extensions/codex/src/app-server/dynamic-tool-execution.ts:37-39) و برای مهلت/بازپخش ایمن علامت‌گذاری می‌شود.
• کلید گروه برای والدهای Codex: ‏swarm:<parentSessionKey>:<turnId>.
• زیرعامل‌های بومی Codex‏ spawn_agent هم‌زیستی دارند؛ ردیف‌های آینه وظیفه آن‌ها همان سطح پیشرفت را تغذیه می‌کنند.

9. ماندگاری و نگه‌داری

• هیچ ذخیره جدیدی وجود ندارد. رکوردهای رجیستری جدول‌های SQLite موجود رجیستری زیرعامل را گسترش می‌دهند؛ فرزندان ردیف‌های معمولی sessions هستند. فقط ستون‌های افزایشی — هر تغییری که مستلزم افزایش نسخه طرح‌واره SQLite باشد ابتدا به تأیید صریح نگه‌دارنده نیاز دارد (سیاست مخزن).
• شناسه گروه swarm روی رکورد رجیستری + فراداده نشست فرزند.
• نگه‌داری: رکوردهای تکمیل‌شده گردآورنده تا زمان بایگانی گروه باقی می‌مانند: هنگامی که اجرای والد پایان می‌یابد (یا TTL منقضی می‌شود)، فرزندان گروه به‌صورت دسته‌ای بایگانی می‌شوند (پویش موجود DEFAULT_SUBAGENT_ARCHIVE_AFTER_MINUTES گسترش می‌یابد تا به‌ازای هر گروه عمل کند).

10. سطح پیشرفت («نقطه‌ها») — lane بعدی

• ضمنی و مبتنی بر چارچوب. از SSE موجود sessions.changed + رجیستری مشتق می‌شود؛ یادداشت‌های phase/log معناشناسی را می‌افزایند. بدون رندر مبتنی بر عامل.
• Control UI: رندرکننده swarm در خانواده ویجت‌های فضای کاری (ui/src/lib/workspace/widgets/) — شبکه نقطه‌ای گروه‌بندی‌شده بر اساس مرحله، خط روایت‌گر، وضعیت/برچسب/مدل هر نقطه؛ درخت فرزندان نوار کناری بدون تغییر است.
• کانال‌ها: یک پیام وضعیت ویرایش‌شده و نرخ‌محدودشده برای هر گروه (مطابق docs/concepts/streaming.md؛ هرگز پیام جداگانه برای هر فرزند ارسال نمی‌شود).

11. صفحه آزمایشگاه‌ها (رابط کاربری کنترل، مسیر مستقل)

Settings → Labs: کلیدهای تغییر وضعیت قابلیت‌های آزمایشی، با نخستین موارد Code Mode و Swarm. هر ردیف: نام، توضیح یک‌خطی، پیوند مستندات، و کلید تغییری که از طریق RPC موجود config.patch متصل است (merge-patch در RFC 7396 — تنظیم tools.codeMode.enabled / tools.swarm.enabled)؛ همچنین، در صورت کاربرد، راهنمای «نیازمند راه‌اندازی مجدد» نمایش داده می‌شود. قابل کشف است، اما متن به‌روشنی وضعیت آزمایشی را بیان می‌کند. بین‌المللی‌سازی: همه رشته‌ها از مسیر عادی en.ts + پایپ‌لاین همگام‌سازی عبور می‌کنند.

12. استقرار (بعداً)

• placement انتخاب هنگام ایجاد: "local" (پیش‌فرض) | "cloud:<profile>" از طریق توزیع موجود محیط worker (sessions.dispatch)؛ استقرار تجمیعی بعداً، اگر فرزندان SSH-sandbox در جعبه مشترک ناکافی باشند.
• ماشین مجازی Orchestrator همیشه روی Gateway باقی می‌ماند؛ settle/dots/budget نسبت به استقرار بی‌تفاوت‌اند.

13. موارد خارج از اهداف

• بدون DSL گراف — جریان کنترل همان گراف است (عمدی و مستندسازی‌شده).
• بدون تغییر در کد منبع Codex؛ بدون استفاده مجدد از اجزای داخلی Code Mode در Codex.
• بدون گردش‌کارهای ذخیره‌شده/نام‌گذاری‌شده در v1؛ بدون نقطه ورود CLI.
• بدون انتقال تأیید اپراتور از هر فرزند به سطح بالاتر.
• بدون تأمین منابع ابری 1:1 در مقیاس fan-out.
• بدون شیم‌های سازگاری در زمان اجرای پایدار؛ swarm سطحی جدید و محدودشده با گیت است.

14. مراحل ساخت / تقسیم‌بندی PR

1. مسیر A (هسته): پیکربندی §4 + ایجاد/انتظار/سقف‌ها/تأییدها در §5 + آزمون‌های §6.
2. مسیر C (صفحه آزمایشگاه‌ها): §11 — مستقل است و می‌تواند نخست ادغام شود.
3. مسیر B (سطح QuickJS): §7 — پس از ادغام قراردادهای A.
4. رندرکننده نقطه‌ها (§10)، نگاشت Codex (§8)، agents.session (§7 v1.1)، استقرار (§12)، بازنویسی مستندات کاربر — PRهای بعدی به همین ترتیب.

هر PR: پایپ‌لاین CI سبز، $autoreview پاک، به‌طور پیش‌فرض پشت گیت غیرفعال، و شاخه main قابل انتشار.