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

ใช้แนวทางนี้เมื่อ OpenClaw ต้องการโดเมนที่ใช้ร่วมกันใหม่ เช่น embeddings การสร้างภาพ การสร้างวิดีโอ หรือพื้นที่ฟีเจอร์ในอนาคตที่มีผู้ให้บริการรองรับ

กฎคือ:

• Plugin = ขอบเขตความเป็นเจ้าของ
• ความสามารถ = สัญญาแกนหลักที่ใช้ร่วมกัน

อย่าเริ่มด้วยการเชื่อมผู้ให้บริการเข้ากับช่องทางหรือเครื่องมือโดยตรง ให้เริ่มจากการกำหนดความสามารถก่อน

เมื่อใดควรสร้างความสามารถ

สร้างความสามารถใหม่เมื่อทั้งหมดต่อไปนี้เป็นจริง:

1. มีผู้ให้บริการมากกว่าหนึ่งรายที่น่าจะนำไปใช้งานได้
2. ช่องทาง เครื่องมือ หรือ Plugin ฟีเจอร์ควรใช้งานได้โดยไม่ต้องสนใจผู้ให้บริการ
3. แกนหลักต้องเป็นเจ้าของพฤติกรรม fallback นโยบาย การกำหนดค่า หรือการส่งมอบ

หากงานนั้นเป็นเฉพาะผู้ให้บริการและยังไม่มีสัญญาที่ใช้ร่วมกัน ให้หยุดและกำหนดสัญญาก่อน

ลำดับมาตรฐาน

1. กำหนดสัญญาแกนหลักแบบมี type
2. เพิ่มการลงทะเบียน Plugin สำหรับสัญญานั้น
3. เพิ่มตัวช่วยรันไทม์ที่ใช้ร่วมกัน
4. เชื่อม Plugin ผู้ให้บริการจริงหนึ่งรายการเป็นหลักฐาน
5. ย้ายผู้บริโภคฟีเจอร์/ช่องทางไปใช้ตัวช่วยรันไทม์
6. เพิ่มการทดสอบสัญญา
7. จัดทำเอกสารการกำหนดค่าที่ผู้ปฏิบัติงานเห็นและโมเดลความเป็นเจ้าของ

สิ่งใดอยู่ที่ใด

แกนหลัก:

• ประเภทคำขอ/คำตอบ
• รีจิสทรีผู้ให้บริการ + การ resolve
• พฤติกรรม fallback
• schema การกำหนดค่าพร้อม metadata เอกสาร title / description ที่ส่งต่อบนโหนดออบเจ็กต์ซ้อน wildcard รายการอาร์เรย์ และ composition
• พื้นผิวตัวช่วยรันไทม์

Plugin ผู้ให้บริการ:

• การเรียก API ของผู้ให้บริการ
• การจัดการ auth ของผู้ให้บริการ
• การ normalize คำขอเฉพาะผู้ให้บริการ
• การลงทะเบียน implementation ของความสามารถ

Plugin ฟีเจอร์/ช่องทาง:

• เรียก api.runtime.* หรือตัวช่วย plugin-sdk/*-runtime ที่ตรงกัน
• ไม่เรียก implementation ของผู้ให้บริการโดยตรง

Seam ของผู้ให้บริการและ harness

ใช้ provider hooks เมื่อพฤติกรรมเป็นของสัญญาผู้ให้บริการโมเดล ไม่ใช่ลูปเอเจนต์ทั่วไป ตัวอย่างเช่น พารามิเตอร์คำขอเฉพาะผู้ให้บริการหลังจากเลือก transport แล้ว การตั้งค่า auth-profile ที่ต้องการ prompt overlays และการกำหนดเส้นทาง fallback ต่อเนื่องหลังจาก model/profile failover

ใช้ agent harness hooks เมื่อพฤติกรรมเป็นของรันไทม์ที่กำลังดำเนินการ turn Harness สามารถจัดประเภทผลลัพธ์ของโปรโตคอลที่ชัดเจน เช่น เอาต์พุตว่าง reasoning ที่ไม่มีเอาต์พุตที่มองเห็นได้ หรือแผนแบบมีโครงสร้างที่ไม่มีคำตอบสุดท้าย เพื่อให้นโยบาย fallback ของโมเดลภายนอกตัดสินใจ retry ได้

รักษา seam ทั้งสองให้แคบ:

• แกนหลักเป็นเจ้าของนโยบาย retry/fallback
• Provider plugins เป็นเจ้าของคำใบ้คำขอ/auth/routing เฉพาะผู้ให้บริการ
• Harness plugins เป็นเจ้าของการจัดประเภท attempt เฉพาะรันไทม์
• 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 ที่ bundled หนึ่งรายการขึ้นไป
• การกำหนดค่า เอกสาร การทดสอบ

ตัวอย่างที่ทำงานจริง: การสร้างภาพ

การสร้างภาพทำตามรูปแบบมาตรฐาน:

1. แกนหลักกำหนด ImageGenerationProvider
2. แกนหลักเปิดเผย registerImageGenerationProvider(...)
3. แกนหลักเปิดเผย runtime.imageGeneration.generate(...)
4. Plugin openai, google, fal และ minimax ลงทะเบียน implementation ที่มีผู้ให้บริการรองรับ
5. ผู้ให้บริการในอนาคตลงทะเบียนสัญญาเดียวกันโดยไม่ต้องเปลี่ยนช่องทาง/เครื่องมือ

คีย์การกำหนดค่าถูกแยกจากการกำหนดเส้นทางการวิเคราะห์ภาพโดยเจตนา:

• agents.defaults.imageModel วิเคราะห์ภาพ
• agents.defaults.imageGenerationModel สร้างภาพ

แยกสองอย่างนี้ไว้เพื่อให้ fallback และนโยบายยังคงชัดเจน

ผู้ให้บริการ embedding

ใช้ embeddingProviders สำหรับผู้ให้บริการ vector embedding ที่นำกลับมาใช้ซ้ำได้ สัญญานี้ ตั้งใจให้กว้างกว่า memory: เครื่องมือ การค้นหา retrieval ตัวนำเข้า หรือ Plugin ฟีเจอร์ในอนาคตสามารถใช้ embeddings ได้โดยไม่ต้องขึ้นกับ memory engine

การค้นหา memory สามารถใช้ embeddingProviders ทั่วไปได้ สัญญา memoryEmbeddingProviders เดิมเป็นความเข้ากันได้ที่ deprecated ระหว่างที่ผู้ให้บริการเฉพาะ memory ที่มีอยู่กำลัง migrate; ผู้ให้บริการ embedding ที่นำกลับมาใช้ซ้ำได้ใหม่ควรใช้ embeddingProviders

รายการตรวจสอบการรีวิว

ก่อนส่งมอบความสามารถใหม่ ให้ตรวจสอบว่า:

• ไม่มีช่องทาง/เครื่องมือ import โค้ดผู้ให้บริการโดยตรง
• ตัวช่วยรันไทม์คือ path ที่ใช้ร่วมกัน
• มีการทดสอบสัญญาอย่างน้อยหนึ่งรายการที่ assert ความเป็นเจ้าของแบบ bundled
• เอกสารการกำหนดค่าระบุชื่อ model/config key ใหม่
• เอกสาร Plugin อธิบายขอบเขตความเป็นเจ้าของ

หาก PR ข้ามเลเยอร์ความสามารถและ hardcode พฤติกรรมผู้ให้บริการลงในช่องทาง/เครื่องมือ ให้ส่งกลับและกำหนดสัญญาก่อน

ที่เกี่ยวข้อง

• ส่วนภายในของ Plugin — โมเดลความสามารถ ความเป็นเจ้าของ ไปป์ไลน์การโหลด ตัวช่วยรันไทม์
• การสร้าง Plugin — บทช่วยสอน Plugin แรก
• ภาพรวม SDK — เอกสารอ้างอิง import map และ API การลงทะเบียน
• การสร้าง Skills — พื้นผิวผู้มีส่วนร่วมที่ใช้ร่วมกัน