क्षमताएँ जोड़ना (योगदानकर्ता मार्गदर्शिका)

इसका उपयोग तब करें, जब 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.mediaModels.image छवियाँ बनाता है।

इन्हें अलग रखें, ताकि फ़ॉलबैक और नीति स्पष्ट बने रहें।

एम्बेडिंग प्रदाता

पुनः उपयोग योग्य वेक्टर एम्बेडिंग प्रदाताओं के लिए registerEmbeddingProvider(...) / अनुबंध embeddingProviders का उपयोग करें। यह अनुबंध जानबूझकर मेमोरी से व्यापक है: टूल, खोज, पुनर्प्राप्ति, आयातक या भावी सुविधा Plugin, मेमोरी इंजन पर निर्भर हुए बिना एम्बेडिंग का उपयोग कर सकते हैं। मेमोरी खोज भी सामान्य embeddingProviders का उपयोग करती है।

पुराना मेमोरी-विशिष्ट पंजीकरण API और memoryEmbeddingProviders अनुबंध अप्रचलित हैं। सभी नए एम्बेडिंग प्रदाताओं के लिए registerEmbeddingProvider और embeddingProviders का उपयोग करें।

समीक्षा जाँच-सूची

नई क्षमता जारी करने से पहले सत्यापित करें:

• कोई चैनल/टूल विक्रेता कोड को सीधे आयात नहीं करता।
• रनटाइम सहायक ही साझा पथ है।
• कम-से-कम एक अनुबंध परीक्षण बंडल किए गए स्वामित्व की पुष्टि करता है।
• कॉन्फ़िगरेशन दस्तावेज़ नई मॉडल/कॉन्फ़िगरेशन कुंजी का नाम बताते हैं।
• Plugin दस्तावेज़ स्वामित्व सीमा समझाते हैं।

यदि कोई PR क्षमता परत छोड़कर विक्रेता व्यवहार को चैनल/टूल में हार्डकोड करता है, तो उसे वापस भेजें और पहले अनुबंध परिभाषित करें।

संबंधित

• Plugin की आंतरिक संरचना — क्षमता मॉडल, स्वामित्व, लोड पाइपलाइन, रनटाइम सहायक।
• Plugin बनाना — पहला Plugin बनाने का ट्यूटोरियल।
• SDK का अवलोकन — आयात मैप और पंजीकरण API संदर्भ।
• Skills बनाना — पूरक योगदानकर्ता सतह।