การปรับโครงสร้าง Plugin Canvas

Canvas มีการใช้งานน้อยและอยู่ในขั้นทดลอง ให้ถือว่าเป็น Plugin ที่รวมมาในชุด ไม่ใช่ฟีเจอร์หลัก ส่วนแกนอาจคงระบบเชื่อมต่อทั่วไปสำหรับ Gateway, Node, HTTP, การยืนยันตัวตน, การกำหนดค่า และไคลเอนต์เนทีฟไว้ได้ แต่พฤติกรรมเฉพาะของ Canvas ควรอยู่ภายใต้ extensions/canvas

เป้าหมาย

ย้ายความเป็นเจ้าของ Canvas ไปยัง extensions/canvas โดยคงพฤติกรรม Node ที่จับคู่ไว้ในปัจจุบัน:

• เครื่องมือ canvas สำหรับเอเจนต์ได้รับการลงทะเบียนโดย Plugin Canvas
• อนุญาตคำสั่ง Node ของ Canvas เฉพาะเมื่อ Plugin Canvas ลงทะเบียนคำสั่งเหล่านั้น
• ไฟล์โฮสต์/ซอร์สของ A2UI อยู่ภายใต้ Plugin Canvas
• การสร้างเอกสาร Canvas ให้อยู่ในรูปที่ใช้งานได้อยู่ภายใต้ Plugin Canvas
• การใช้งานคำสั่ง CLI อยู่ภายใต้ Plugin Canvas หรือมอบหมายผ่าน runtime barrel ที่ Plugin เป็นเจ้าของ
• เอกสารและรายการ Plugin ระบุว่า Canvas เป็นฟีเจอร์ทดลองที่ทำงานผ่าน Plugin

สิ่งที่ไม่ใช่เป้าหมาย

• อย่าออกแบบ UI Canvas ของแอปเนทีฟใหม่ในการปรับโครงสร้างครั้งนี้
• อย่าลบการรองรับโปรโตคอล/ไคลเอนต์ Canvas ออกจาก iOS, Android หรือ macOS เว้นแต่จะมีการตัดสินใจด้านผลิตภัณฑ์แยกต่างหากให้ลบ Canvas
• อย่าสร้างเฟรมเวิร์กบริการ Plugin แบบกว้างเพียงเพื่อ Canvas เว้นแต่จะมี Plugin อื่นที่รวมมาในชุดอย่างน้อยหนึ่งรายการต้องใช้จุดเชื่อมเดียวกัน

สถานะของบรานช์ปัจจุบัน

เสร็จแล้ว:

• เพิ่มแพ็กเกจ Plugin ที่รวมมาในชุดใน extensions/canvas
• เพิ่ม extensions/canvas/openclaw.plugin.json
• ย้ายเครื่องมือ canvas ของเอเจนต์จาก src/agents/tools/canvas-tool.ts ไปยัง extensions/canvas/src/tool.ts
• ลบการลงทะเบียน createCanvasTool ในแกนออกจาก src/agents/openclaw-tools.ts
• ย้ายการใช้งานโฮสต์ Canvas จาก src/canvas-host ไปยัง extensions/canvas/src/host
• คง extensions/canvas/runtime-api.ts ไว้เป็น compatibility barrel ที่ Plugin เป็นเจ้าของ สำหรับการทดสอบ การจัดแพ็กเกจ และตัวช่วย Canvas สาธารณะภายนอก
• ย้ายการสร้างเอกสาร Canvas ให้อยู่ในรูปที่ใช้งานได้จาก src/gateway/canvas-documents.ts ไปยัง extensions/canvas/src/documents.ts
• ย้ายการใช้งาน CLI ของ Canvas และตัวช่วย JSONL ของ A2UI ไปไว้ใน extensions/canvas/src/cli.ts
• ย้าย URL โฮสต์ Canvas และตัวช่วยความสามารถแบบจำกัดขอบเขตไปไว้ใน extensions/canvas/src
• ย้ายค่าเริ่มต้นของคำสั่ง Node สำหรับ Canvas ออกจากรายการที่ฮาร์ดโค้ดในแกนไปไว้ใน nodeInvokePolicies ของ Plugin
• เพิ่มการกำหนดค่าโฮสต์ Canvas ที่ Plugin เป็นเจ้าของใน plugins.entries.canvas.config.host
• ย้ายการให้บริการ HTTP ของ Canvas และ A2UI ไปอยู่เบื้องหลังการลงทะเบียนเส้นทาง HTTP ของ Plugin Canvas
• เพิ่มการส่งต่อการอัปเกรด WebSocket แบบทั่วไปสำหรับเส้นทาง HTTP ที่ Plugin เป็นเจ้าของ
• แทนที่ URL โฮสต์ Canvas และการยืนยันสิทธิ์ความสามารถของ Node ที่เฉพาะเจาะจงกับ Canvas ใน Gateway ด้วยพื้นผิว Plugin แบบโฮสต์และตัวช่วยความสามารถของ Node ที่เป็นแบบทั่วไป
• เพิ่มตัวแก้ไขสื่อที่โฮสต์ซึ่ง Plugin เป็นเจ้าของ เพื่อให้ URL เอกสาร Canvas แก้ไขผ่าน Plugin Canvas แทนที่แกนจะนำเข้ารายละเอียดภายในของเอกสาร Canvas
• เพิ่ม api.registerNodeCliFeature(...) เพื่อให้ Canvas สามารถประกาศ openclaw nodes canvas เป็นฟีเจอร์ Node ที่ Plugin เป็นเจ้าของได้โดยไม่ต้องระบุพาธคำสั่งแม่ด้วยตนเอง
• ลบการนำเข้า extensions/canvas/runtime-api.js ของ src/** ในโปรดักชัน
• ย้ายซอร์สบันเดิล A2UI จาก apps/shared/OpenClawKit/Tools/CanvasA2UI ไปยัง extensions/canvas/src/host/a2ui-app
• ย้ายการใช้งานสำหรับสร้าง/คัดลอก A2UI ไปไว้ภายใต้ extensions/canvas/scripts และแทนที่การเชื่อมต่อระบบสร้างที่รูทด้วยฮุกแอสเซ็ต Plugin ที่รวมมาในชุดแบบทั่วไป
• ลบชื่อแทนการกำหนดค่าระดับบนสุด canvasHost แบบเก่าที่ runtime ใช้ออก
• คงการย้ายข้อมูล Canvas ของ doctor ไว้ เพื่อให้ openclaw doctor --fix เขียนการกำหนดค่า canvasHost แบบเก่าใหม่เป็น plugins.entries.canvas.config.host
• ลบความเข้ากันได้ของโปรโตคอล Canvas สำหรับเอเจนต์รุ่นเก่าภายใต้โปรโตคอล Gateway v4 ขณะนี้ไคลเอนต์เนทีฟและ Gateway ใช้เฉพาะ pluginSurfaceUrls.canvas ร่วมกับ node.pluginSurface.refresh เท่านั้น โดยพาธ canvasHostUrl, canvasCapability และ node.canvas.capability.refresh ที่เลิกใช้แล้วไม่ได้รับการรองรับโดยเจตนาในการปรับโครงสร้างเชิงทดลองครั้งนี้
• อัปเดตรายการ Plugin ที่สร้างขึ้นให้รวม Canvas
• เพิ่มเอกสารอ้างอิง Plugin ที่ docs/plugins/reference/canvas.md

พื้นผิว Canvas ที่แกนยังเป็นเจ้าของและทราบว่ายังคงเหลืออยู่:

• ตัวจัดการ Canvas ของแอปเนทีฟภายใต้ apps/ ยังคงใช้งานพื้นผิวของ Plugin Canvas โดยเจตนา
• ตัวจัดการโปรโตคอล/ไคลเอนต์ Canvas ของแอปเนทีฟภายใต้ apps/
• เอาต์พุตอาร์ติแฟกต์ที่เผยแพร่ยังคงใช้ dist/canvas-host/a2ui สำหรับการค้นหา runtime ที่เข้ากันได้ย้อนหลัง แต่ขณะนี้ขั้นตอนการคัดลอกเป็นของ Plugin แล้ว

โครงสร้างเป้าหมาย

extensions/canvas ควรเป็นเจ้าของ:

• ไฟล์ manifest และข้อมูลเมตาของแพ็กเกจ Plugin
• การลงทะเบียนเครื่องมือของเอเจนต์
• นโยบายคำสั่งเรียกใช้ Node
• โฮสต์ Canvas และ runtime ของ A2UI
• ซอร์สบันเดิล A2UI ของ Canvas และสคริปต์สร้าง/คัดลอกแอสเซ็ต
• การสร้างเอกสาร Canvas และการแก้ไขแอสเซ็ต
• การใช้งาน CLI ของ Canvas
• หน้าเอกสาร Canvas และรายการในบัญชี Plugin

แกนควรเป็นเจ้าของเฉพาะจุดเชื่อมทั่วไป:

• การค้นหาและลงทะเบียน Plugin
• รีจิสทรีเครื่องมือของเอเจนต์แบบทั่วไป
• รีจิสทรีนโยบายการเรียกใช้ Node แบบทั่วไป
• HTTP/การยืนยันตัวตนของ Gateway และการส่งต่อการอัปเกรด WebSocket แบบทั่วไป
• การแก้ไข URL ของพื้นผิว Plugin แบบโฮสต์โดยทั่วไป
• การลงทะเบียนตัวแก้ไขสื่อแบบโฮสต์โดยทั่วไป
• การขนส่งความสามารถของ Node แบบทั่วไป
• ระบบเชื่อมต่อการกำหนดค่าแบบทั่วไป
• การค้นหาฮุกแอสเซ็ตของ Plugin ที่รวมมาในชุดแบบทั่วไป

แอปเนทีฟอาจคงตัวจัดการคำสั่ง Canvas ไว้ในฐานะไคลเอนต์ของโปรโตคอล แอปเหล่านี้ไม่ใช่เจ้าของ runtime ของ Plugin

ขั้นตอนการย้าย

1. ถือว่า plugins.entries.canvas.config.host เป็นพื้นผิวการกำหนดค่าที่ Plugin เป็นเจ้าของ
2. อัปเดตเอกสารเพื่ออธิบายว่า Canvas เป็น Plugin แบบทดลองที่รวมมาในชุด
3. เรียกใช้การทดสอบ Canvas แบบเจาะจง การตรวจสอบรายการ Plugin การตรวจสอบ API ของ Plugin SDK และเกตการสร้าง/ชนิดข้อมูลที่ได้รับผลกระทบจากขอบเขต runtime

รายการตรวจสอบการตรวจประเมิน

ก่อนระบุว่าการปรับโครงสร้างเสร็จสมบูรณ์:

• rg "src/canvas-host|../canvas-host" ไม่พบการนำเข้าซอร์สที่ใช้งานอยู่
• rg "canvas-tool|createCanvasTool" src ไม่พบการใช้งานเครื่องมือ Canvas ที่แกนเป็นเจ้าของ
• rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway ไม่พบค่าเริ่มต้นของรายการอนุญาตที่ฮาร์ดโค้ดไว้นอกการทดสอบนโยบาย Plugin แบบทั่วไป
• rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' ว่างเปล่า
• rg "canvas-documents" src ว่างเปล่า
• rg "registerNodesCanvasCommands|nodes-canvas" src ว่างเปล่า โดย Plugin Canvas ลงทะเบียน openclaw nodes canvas ผ่านข้อมูลเมตา CLI ของ Plugin แบบซ้อน
• rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway ไม่พบความเป็นเจ้าของ runtime ของ Gateway
• rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json พบเฉพาะตัวห่อหุ้มเพื่อความเข้ากันได้หรือพาธที่ Plugin เป็นเจ้าของ
• pnpm plugins:inventory:check ผ่าน
• pnpm plugin-sdk:api:check ผ่าน หรือระเบียนสัญญา API ที่สร้างขึ้นได้รับการอัปเดตและตรวจทานโดยเจตนา
• การทดสอบ Canvas แบบเจาะจงผ่าน
• การทดสอบ changed-lanes สำหรับพาธโฮสต์ Canvas/A2UI ผ่าน
• เนื้อหา PR ระบุอย่างชัดเจนว่า Canvas เป็นฟีเจอร์ทดลองและทำงานผ่าน Plugin

คำสั่งตรวจสอบ

ใช้การตรวจสอบภายในเครื่องแบบเจาะจงระหว่างการปรับแก้:

pnpm test extensions/canvas/src/host/server.test.ts extensions/canvas/src/host/server.state-dir.test.ts extensions/canvas/src/host/file-resolver.test.tspnpm test src/gateway/server.plugin-node-capability-auth.test.ts src/gateway/server-import-boundary.test.tspnpm test extensions/canvas/src/config-migration.test.ts src/commands/doctor-legacy-config.migrations.test.tspnpm test test/scripts/changed-lanes.test.ts test/scripts/build-all.test.ts extensions/canvas/scripts/bundle-a2ui.test.ts test/scripts/bundled-plugin-assets.test.ts extensions/canvas/scripts/copy-a2ui.test.ts src/infra/run-node.test.tspnpm tsgo:extensionspnpm plugins:inventory:checkpnpm plugin-sdk:api:check

เรียกใช้ pnpm build ก่อน push หาก runtime barrel, การนำเข้าแบบ lazy, การจัดแพ็กเกจ หรือพื้นผิว Plugin ที่เผยแพร่มีการเปลี่ยนแปลง