سازگاری Plugin

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

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

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

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

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

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

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

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

بسته بازرس Plugin

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

CLI روز نخست باید این باشد:

openclaw-plugin-inspector ./my-plugin

باید این موارد را منتشر کند:

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

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

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

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

pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json"pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json"pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- <clawhub-plugin-dir> --json"

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

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

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

توالی مهاجرت این است:

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

رکوردهای منسوخ باید شامل تاریخ شروع هشدار، جایگزین، پیوند مستندات، و تاریخ حذف نهایی حداکثر سه ماه پس از شروع هشدار باشند. مسیر سازگاری منسوخ با پنجره حذف بی‌انتها اضافه نکنید، مگر اینکه نگه‌دارندگان صریحا تصمیم بگیرند این سازگاری دائمی است و به‌جای آن وضعیتش را 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های بسته‌بندی‌شده
• فراداده قدیمی مانیفست env-var ارائه‌دهنده/کانال
• hookها و aliasهای نوع قدیمی Plugin ارائه‌دهنده، تا زمانی که ارائه‌دهندگان به hookهای صریح کاتالوگ، احراز هویت، thinking، replay و انتقال مهاجرت کنند
• aliasهای قدیمی زمان اجرا مانند api.runtime.taskFlow، api.runtime.subagent.getSession، api.runtime.stt و api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...) منسوخ
• ثبت split قدیمی Plugin حافظه، تا زمانی که Pluginهای حافظه به registerMemoryCapability مهاجرت کنند
• helperهای قدیمی SDK کانال برای اسکیماهای پیام native، کنترل mention، قالب‌بندی envelope ورودی، و تو در تویی قابلیت تأیید
• aliasهای قدیمی کلید مسیر کانال و helper هدف قابل‌مقایسه، تا زمانی که Pluginها به openclaw/plugin-sdk/channel-route مهاجرت کنند
• hintهای فعال‌سازی که با مالکیت contribution در مانیفست جایگزین می‌شوند
• fallback زمان اجرای setup-api، تا زمانی که descriptorهای راه‌اندازی به فراداده سرد setup.requiresRuntime: false منتقل شوند
• hookهای discovery ارائه‌دهنده، تا زمانی که hookهای کاتالوگ ارائه‌دهنده به catalog.run(...) منتقل شوند
• فراداده showConfigured / showInSetup کانال، تا زمانی که بسته‌های کانال به openclaw.channel.exposure منتقل شوند
• کلیدهای پیکربندی قدیمی runtime-policy، تا زمانی که Doctor اپراتورها را به agentRuntime مهاجرت دهد
• fallback فراداده تولیدشده پیکربندی کانال‌های بسته‌بندی‌شده، تا زمانی که فراداده registry-first channelConfigs اضافه شود
• پرچم‌های env برای غیرفعال‌سازی رجیستری Plugin پایدارشده و مهاجرت نصب، تا زمانی که جریان‌های تعمیر اپراتورها را به openclaw plugins registry --refresh و openclaw doctor --fix مهاجرت دهند
• مسیرهای پیکربندی قدیمی جست‌وجوی وب، دریافت وب، و x_search متعلق به Plugin، تا زمانی که Doctor آن‌ها را به plugins.entries.<plugin>.config مهاجرت دهد
• پیکربندی authored قدیمی plugins.installs و aliasهای مسیر بارگذاری Plugin بسته‌بندی‌شده، تا زمانی که فراداده نصب به دفتر Plugin مدیریت‌شده توسط state منتقل شود

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

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

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