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

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

قاعده:

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

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

# چه زمانی یک قابلیت بسازیم

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

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

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

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

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

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

هسته:

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

Plugin فروشنده:

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

Plugin ویژگی/کانال:

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

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

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

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

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

• هسته مالک سیاست تلاش دوباره/جایگزین است.
• 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 تصویرها را تولید می‌کند.

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

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

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

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

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

# مرتبط

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