การเพิ่มความสามารถ (คู่มือผู้ร่วมพัฒนา)

ใช้แนวทางนี้เมื่อ 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 — พื้นที่สำหรับผู้มีส่วนร่วมที่ใช้ร่วมกัน