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

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

กฎคือ:

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

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

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

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

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

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

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

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

# อะไรอยู่ที่ไหน

แกนหลัก:

• ชนิด request/response
• รีจิสทรีผู้ให้บริการ + การ resolve
• พฤติกรรม fallback
• สคีมา config พร้อมเมทาดาทาเอกสาร title / description ที่เผยแพร่ต่อบน nested object, wildcard, array-item และ composition nodes
• พื้นผิวตัวช่วยรันไทม์

Plugin ผู้ขาย:

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

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

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

# รอยต่อของผู้ให้บริการและ harness

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

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

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

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

# ตัวอย่างที่ทำครบแล้ว: การสร้างภาพ

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

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

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

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

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

# เช็กลิสต์การตรวจทาน

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

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

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

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

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