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

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

قاعده:

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

یک ارائه‌دهنده را مستقیماً به کانال یا ابزار متصل نکنید. ابتدا قابلیت را تعریف کنید.

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

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

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

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

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

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

هر بخش در کجا قرار می‌گیرد

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

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

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

هر دو درز را محدود نگه دارید:

• هسته مالک خط‌مشی تلاش مجدد/جایگزینی است.
• 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. هسته api.runtime.imageGeneration.generate(...) و .listProviders(...) را ارائه می‌کند.
4. Plugin‌های ارائه‌دهنده (comfy، deepinfra، fal، google، litellm، microsoft-foundry، minimax، openai، openrouter، vydra، xai) پیاده‌سازی‌های متکی بر ارائه‌دهنده را ثبت می‌کنند.
5. ارائه‌دهندگان آینده همان قرارداد را بدون تغییر کانال‌ها/ابزارها ثبت می‌کنند.

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

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

آن‌ها را جدا نگه دارید تا جایگزینی و خط‌مشی صریح باقی بمانند.

ارائه‌دهندگان تعبیه‌سازی

برای ارائه‌دهندگان قابل استفادهٔ مجددِ تعبیه‌سازی برداری از registerEmbeddingProvider(...) / قرارداد embeddingProviders استفاده کنید. این قرارداد عمداً گسترده‌تر از حافظه است: ابزارها، جست‌وجو، بازیابی، واردکننده‌ها یا Plugin‌های قابلیت آینده می‌توانند بدون وابستگی به موتور حافظه، تعبیه‌سازی‌ها را مصرف کنند. جست‌وجوی حافظه نیز embeddingProviders عمومی را مصرف می‌کند.

API ثبت قدیمی مختص حافظه و قرارداد memoryEmbeddingProviders منسوخ شده‌اند. برای همهٔ ارائه‌دهندگان تعبیه‌سازی جدید از registerEmbeddingProvider و embeddingProviders استفاده کنید.

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

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

• هیچ کانال/ابزاری کد ارائه‌دهنده را مستقیماً وارد نمی‌کند.
• یاریگر زمان اجرا مسیر مشترک است.
• دست‌کم یک آزمون قرارداد، مالکیت همراه را تأیید می‌کند.
• مستندات پیکربندی نام مدل/کلید پیکربندی جدید را ذکر می‌کنند.
• مستندات Plugin مرز مالکیت را توضیح می‌دهند.

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

مرتبط

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