افزودن قابلیت‌ها (راهنمای مشارکت‌کنندگان)

وقتی OpenClaw به یک دامنه مشترک جدید مانند جاسازی‌ها، تولید تصویر، تولید ویدئو، یا یک حوزه قابلیت آینده با پشتوانه فروشنده نیاز دارد، از این راهنما استفاده کنید.

قاعده:

• Plugin = مرز مالکیت
• قابلیت = قرارداد مشترک هسته

کار را با اتصال مستقیم یک فروشنده به یک کانال یا ابزار شروع نکنید. با تعریف قابلیت شروع کنید.

چه زمانی یک قابلیت ایجاد کنیم

وقتی همه موارد زیر درست هستند، یک قابلیت جدید ایجاد کنید:

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

اگر کار فقط مربوط به فروشنده است و هنوز هیچ قرارداد مشترکی وجود ندارد، توقف کنید و ابتدا قرارداد را تعریف کنید.

توالی استاندارد

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

چه چیزی کجا قرار می‌گیرد

هسته:

• نوع‌های درخواست/پاسخ.
• رجیستری ارائه‌دهنده + حل‌وفصل.
• رفتار جایگزینی.
• شِمای پیکربندی همراه با فراداده مستندات title / description منتشرشده روی گره‌های آبجکت تودرتو، وایلدکارت، آیتم آرایه، و ترکیب.
• سطح کمک‌کننده زمان اجرا.

Plugin فروشنده:

• فراخوانی‌های API فروشنده.
• مدیریت احراز هویت فروشنده.
• نرمال‌سازی درخواست ویژه فروشنده.
• ثبت پیاده‌سازی قابلیت.

Plugin قابلیت/کانال:

• api.runtime.* یا کمک‌کننده متناظر plugin-sdk/*-runtime را فراخوانی می‌کند.
• هرگز پیاده‌سازی فروشنده را مستقیما فراخوانی نمی‌کند.

مرزهای ارائه‌دهنده و مهار

وقتی رفتار به قرارداد ارائه‌دهنده مدل تعلق دارد نه حلقه عمومی عامل، از قلاب‌های ارائه‌دهنده استفاده کنید. نمونه‌ها شامل پارامترهای درخواست ویژه ارائه‌دهنده پس از انتخاب انتقال، ترجیح پروفایل احراز هویت، همپوشانی‌های پرامپت، و مسیریابی جایگزین پیگیری پس از جابه‌جایی مدل/پروفایل هستند.

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

هر دو مرز را باریک نگه دارید:

• هسته مالک سیاست تلاش دوباره/جایگزینی است.
• Pluginهای ارائه‌دهنده مالک اشاره‌های درخواست/احراز هویت/مسیریابی ویژه ارائه‌دهنده هستند.
• Pluginهای مهار مالک طبقه‌بندی تلاش ویژه زمان اجرا هستند.
• Pluginهای شخص ثالث اشاره برمی‌گردانند، نه جهش مستقیم در وضعیت هسته.

چک‌لیست فایل

برای یک قابلیت جدید، انتظار داشته باشید این نواحی را تغییر دهید:

• src/<capability>/types.ts
• src/<capability>/...registry/runtime.ts
• src/plugins/types.ts
• src/plugins/registry.ts
• src/plugins/captured-registration.ts
• src/plugins/contracts/registry.ts
• src/plugins/runtime/types-core.ts
• src/plugins/runtime/index.ts
• src/plugin-sdk/<capability>.ts
• src/plugin-sdk/<capability>-runtime.ts
• یک یا چند بسته Plugin باندل‌شده.
• پیکربندی، مستندات، تست‌ها.

مثال کامل: تولید تصویر

تولید تصویر از شکل استاندارد پیروی می‌کند:

1. هسته ImageGenerationProvider را تعریف می‌کند.
2. هسته registerImageGenerationProvider(...) را در دسترس می‌گذارد.
3. هسته runtime.imageGeneration.generate(...) را در دسترس می‌گذارد.
4. Pluginهای openai، google، fal، و minimax پیاده‌سازی‌های دارای پشتوانه فروشنده را ثبت می‌کنند.
5. فروشنده‌های آینده همان قرارداد را بدون تغییر کانال‌ها/ابزارها ثبت می‌کنند.

کلید پیکربندی عمدا از مسیریابی تحلیل بینایی جدا است:

• agents.defaults.imageModel تصاویر را تحلیل می‌کند.
• agents.defaults.imageGenerationModel تصاویر را تولید می‌کند.

این‌ها را جدا نگه دارید تا جایگزینی و سیاست صریح بمانند.

ارائه‌دهنده‌های جاسازی

برای ارائه‌دهنده‌های جاسازی برداری قابل استفاده مجدد، از embeddingProviders استفاده کنید. این قرارداد عمدا گسترده‌تر از حافظه است: ابزارها، جست‌وجو، بازیابی، واردکننده‌ها، یا Pluginهای قابلیت آینده می‌توانند بدون وابستگی به موتور حافظه از جاسازی‌ها استفاده کنند.

جست‌وجوی حافظه می‌تواند از embeddingProviders عمومی استفاده کند. قرارداد قدیمی‌تر memoryEmbeddingProviders یک سازگاری منسوخ‌شده است تا زمانی که ارائه‌دهنده‌های ویژه حافظه موجود مهاجرت کنند؛ ارائه‌دهنده‌های جاسازی قابل استفاده مجدد جدید باید از embeddingProviders استفاده کنند.

چک‌لیست بازبینی

پیش از انتشار یک قابلیت جدید، بررسی کنید:

• هیچ کانال/ابزاری کد فروشنده را مستقیما وارد نمی‌کند.
• کمک‌کننده زمان اجرا مسیر مشترک است.
• دست‌کم یک تست قرارداد مالکیت باندل‌شده را اثبات می‌کند.
• مستندات پیکربندی نام مدل/کلید پیکربندی جدید را ذکر می‌کنند.
• مستندات Plugin مرز مالکیت را توضیح می‌دهند.

اگر یک PR لایه قابلیت را دور می‌زند و رفتار فروشنده را در یک کانال/ابزار سخت‌کد می‌کند، آن را برگردانید و ابتدا قرارداد را تعریف کنید.

مرتبط

• درونیات Plugin — مدل قابلیت، مالکیت، خط لوله بارگذاری، کمک‌کننده‌های زمان اجرا.
• ساخت Pluginها — آموزش اولین Plugin.
• نمای کلی SDK — نقشه ایمپورت و مرجع API ثبت.
• ایجاد Skills — سطح همراه مشارکت‌کننده.