سازگاری Plugin

OpenClaw قراردادهای قدیمی‌تر Plugin را پیش از حذف، از طریق آداپترهای سازگاری نام‌گذاری‌شده متصل نگه می‌دارد. این کار از Pluginهای بسته‌بندی‌شده و خارجی موجود محافظت می‌کند، در حالی که قراردادهای SDK، manifest، راه‌اندازی، پیکربندی، و runtime عامل تکامل می‌یابند.

# رجیستری سازگاری

قراردادهای سازگاری Plugin در رجیستری هسته در src/plugins/compat/registry.ts ردیابی می‌شوند.

هر رکورد شامل این موارد است:

• یک کد سازگاری پایدار
• وضعیت: active، deprecated، removal-pending، یا removed
• مالک: SDK، پیکربندی، راه‌اندازی، کانال، ارائه‌دهنده، اجرای Plugin، runtime عامل، یا هسته
• تاریخ‌های معرفی و منسوخ‌سازی در صورت کاربرد
• راهنمای جایگزینی
• مستندات، عیب‌یابی‌ها، و تست‌هایی که رفتار قدیمی و جدید را پوشش می‌دهند

رجیستری منبع برنامه‌ریزی نگه‌دارندگان و بررسی‌های آینده‌ی بازرس Plugin است. اگر رفتاری مرتبط با Plugin تغییر کند، رکورد سازگاری را در همان تغییری اضافه یا به‌روزرسانی کنید که آداپتر را اضافه می‌کند.

سازگاری تعمیر و مهاجرت Doctor به‌صورت جداگانه در src/commands/doctor/shared/deprecation-compat.ts ردیابی می‌شود. آن رکوردها شکل‌های قدیمی پیکربندی، چیدمان‌های دفتر نصب، و shimهای تعمیر را پوشش می‌دهند که ممکن است پس از حذف مسیر سازگاری runtime همچنان لازم باشد در دسترس بمانند.

بررسی‌های انتشار باید هر دو رجیستری را بررسی کنند. صرفا به این دلیل که رکورد سازگاری runtime یا پیکربندی متناظر منقضی شده است، یک مهاجرت Doctor را حذف نکنید؛ ابتدا بررسی کنید که هیچ مسیر ارتقای پشتیبانی‌شده‌ای وجود ندارد که هنوز به آن تعمیر نیاز داشته باشد. همچنین هر یادداشت جایگزینی را هنگام برنامه‌ریزی انتشار دوباره اعتبارسنجی کنید، چون مالکیت Plugin و ردپای پیکربندی می‌تواند با انتقال ارائه‌دهنده‌ها و کانال‌ها به خارج از هسته تغییر کند.

# بسته بازرس Plugin

بازرس Plugin باید خارج از مخزن اصلی OpenClaw، به‌عنوان یک بسته/مخزن جداگانه و متکی بر قراردادهای نسخه‌بندی‌شده‌ی سازگاری و manifest زندگی کند.

CLI روز اول باید چنین باشد:

openclaw-plugin-inspector ./my-plugin

باید این موارد را خروجی دهد:

• اعتبارسنجی manifest/schema
• نسخه سازگاری قرارداد که بررسی می‌شود
• بررسی‌های فراداده نصب/منبع
• بررسی‌های import مسیر سرد
• هشدارهای منسوخ‌سازی و سازگاری

برای خروجی پایدار و قابل خواندن توسط ماشین در حاشیه‌نویسی‌های CI، از --json استفاده کنید. هسته OpenClaw باید قراردادها و fixtureهایی را در معرض استفاده‌ی بازرس قرار دهد، اما نباید باینری بازرس را از بسته اصلی openclaw منتشر کند.

# مسیر پذیرش نگه‌دارندگان

برای مسیر پذیرش بسته قابل نصب، هنگام اعتبارسنجی بازرس خارجی در برابر بسته‌های Plugin OpenClaw از Blacksmith Testbox استفاده کنید. پس از ساخته شدن بسته، آن را از یک checkout تمیز OpenClaw اجرا کنید:

blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
blacksmith testbox run --id <tbx_id> "pnpm install && pnpm build && npm exec --yes @openclaw/[email protected] -- ./extensions/telegram --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/[email protected] -- ./extensions/discord --json"
blacksmith testbox run --id <tbx_id> "npm exec --yes @openclaw/[email protected] -- <clawhub-plugin-dir> --json"
blacksmith testbox stop <tbx_id>

این مسیر را برای نگه‌دارندگان به‌صورت اختیاری نگه دارید، چون یک بسته npm خارجی نصب می‌کند و ممکن است بسته‌های Plugin را که بیرون از مخزن clone شده‌اند بررسی کند. محافظ‌های مخزن محلی، نقشه export در SDK، فراداده رجیستری سازگاری، حذف تدریجی importهای منسوخ SDK، و مرزهای import افزونه‌های بسته‌بندی‌شده را پوشش می‌دهند؛ اثبات بازرس در Testbox، بسته را همان‌طور پوشش می‌دهد که نویسندگان Plugin خارجی آن را مصرف می‌کنند.

# سیاست منسوخ‌سازی

OpenClaw نباید یک قرارداد مستند Plugin را در همان انتشاری حذف کند که جایگزین آن را معرفی می‌کند.

دنباله مهاجرت چنین است:

1. قرارداد جدید را اضافه کنید.
2. رفتار قدیمی را از طریق یک آداپتر سازگاری نام‌گذاری‌شده متصل نگه دارید.
3. زمانی که نویسندگان Plugin می‌توانند اقدام کنند، عیب‌یابی‌ها یا هشدارها را صادر کنید.
4. جایگزین و زمان‌بندی را مستند کنید.
5. هر دو مسیر قدیمی و جدید را تست کنید.
6. تا پایان بازه مهاجرت اعلام‌شده صبر کنید.
7. فقط با تایید صریح انتشار ناسازگار حذف کنید.

رکوردهای منسوخ باید شامل تاریخ شروع هشدار، جایگزین، لینک مستندات، و تاریخ حذف نهایی باشند که بیش از سه ماه پس از شروع هشدار نباشد. مسیر سازگاری منسوخ با بازه حذف باز و بدون پایان اضافه نکنید، مگر اینکه نگه‌دارندگان صریحا تصمیم بگیرند سازگاری دائمی است و به‌جای آن آن را active علامت‌گذاری کنند.

# حوزه‌های سازگاری فعلی

رکوردهای سازگاری فعلی شامل این موارد هستند:

• importهای گسترده و قدیمی SDK مانند openclaw/plugin-sdk/compat
• شکل‌های قدیمی Plugin فقط مبتنی بر hook و before_agent_start
• entrypointهای قدیمی Plugin به‌شکل activate(api) تا زمانی که Pluginها به register(api) مهاجرت کنند
• aliasهای قدیمی SDK مانند openclaw/extension-api، openclaw/plugin-sdk/channel-runtime، سازنده‌های وضعیت openclaw/plugin-sdk/command-auth ،openclaw/plugin-sdk/test-utils (جایگزین‌شده با زیرمسیرهای تست متمرکز openclaw/plugin-sdk/*)، و aliasهای نوع ClawdbotConfig / OpenClawSchemaType
• allowlist و رفتار فعال‌سازی Pluginهای بسته‌بندی‌شده
• فراداده manifest قدیمی env-var برای ارائه‌دهنده/کانال
• hookها و aliasهای نوع قدیمی Plugin ارائه‌دهنده، تا زمانی که ارائه‌دهنده‌ها به hookهای صریح catalog، auth، thinking، replay، و transport منتقل شوند
• aliasهای قدیمی runtime مانند api.runtime.taskFlow، api.runtime.subagent.getSession، api.runtime.stt، و api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...) منسوخ
• ثبت تفکیک‌شده قدیمی memory-plugin تا زمانی که Pluginهای حافظه به registerMemoryCapability منتقل شوند
• helperهای قدیمی SDK کانال برای schemaهای پیام بومی، gating اشاره، قالب‌بندی پاکت ورودی، و nesting قابلیت تایید
• کلید route قدیمی کانال و aliasهای helper هدف قابل مقایسه، تا زمانی که Pluginها به openclaw/plugin-sdk/channel-route منتقل شوند
• hintهای فعال‌سازی که با مالکیت مشارکت manifest جایگزین می‌شوند
• fallback runtime در setup-api تا زمانی که descriptorهای راه‌اندازی به فراداده سرد setup.requiresRuntime: false منتقل شوند
• hookهای discovery ارائه‌دهنده، تا زمانی که hookهای catalog ارائه‌دهنده به catalog.run(...) منتقل شوند
• فراداده showConfigured / showInSetup کانال، تا زمانی که بسته‌های کانال به openclaw.channel.exposure منتقل شوند
• کلیدهای پیکربندی قدیمی runtime-policy، تا زمانی که Doctor اپراتورها را به agentRuntime مهاجرت دهد
• fallback فراداده پیکربندی کانال بسته‌بندی‌شده تولیدشده، تا زمانی که فراداده رجیستری‌محور channelConfigs اضافه شود
• فلگ‌های env برای غیرفعال‌سازی رجیستری Plugin پایدارشده و مهاجرت نصب، تا زمانی که جریان‌های تعمیر اپراتورها را به openclaw plugins registry --refresh و openclaw doctor --fix مهاجرت دهند
• مسیرهای پیکربندی قدیمی جست‌وجوی وب، دریافت وب، و x_search متعلق به Plugin، تا زمانی که Doctor آن‌ها را به plugins.entries.<plugin>.config مهاجرت دهد
• پیکربندی نوشته‌شده قدیمی plugins.installs و aliasهای مسیر بارگذاری Plugin بسته‌بندی‌شده، تا زمانی که فراداده نصب به دفتر Plugin مدیریت‌شده توسط state منتقل شود

کد جدید Plugin باید جایگزین فهرست‌شده در رجیستری و در راهنمای مهاجرت مشخص را ترجیح دهد. Pluginهای موجود می‌توانند تا زمانی که مستندات، عیب‌یابی‌ها، و یادداشت‌های انتشار یک بازه حذف را اعلام کنند، از مسیر سازگاری استفاده کنند.

# یادداشت‌های انتشار

یادداشت‌های انتشار باید منسوخ‌سازی‌های پیش‌روی Plugin را همراه با تاریخ‌های هدف و لینک‌های مستندات مهاجرت شامل شوند. این هشدار باید پیش از آن رخ دهد که یک مسیر سازگاری به removal-pending یا removed منتقل شود.