การปรับโครงสร้าง 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 ของ Plugin แบบทั่วไปสำหรับเส้นทาง HTTP ที่ Plugin เป็นเจ้าของ
• แทนที่ URL โฮสต์ Gateway และการตรวจสอบสิทธิ์ความสามารถของ Node ที่เจาะจงกับ Canvas ด้วยพื้นผิว 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
• ซอร์สบันเดิล Canvas A2UI และสคริปต์บิลด์/คัดลอกแอสเซ็ต
• การสร้างเอกสาร 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 ของ SDK Plugin และเกตการบิลด์/ประเภทที่ได้รับผลกระทบจากขอบเขตของ 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 ต้องพบเฉพาะ wrapper สำหรับความเข้ากันได้หรือเส้นทางที่ Plugin เป็นเจ้าของ
• pnpm plugins:inventory:check ผ่าน
• pnpm plugin-sdk:api:check ผ่าน หรือมีการอัปเดตและตรวจทานค่าฐาน API ที่สร้างขึ้นโดยเจตนา
• การทดสอบ Canvas แบบเจาะจงผ่าน
• การทดสอบเลนที่เปลี่ยนแปลงสำหรับเส้นทางโฮสต์ 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 ก่อนพุช หากมีการเปลี่ยนแปลง runtime barrel, การนำเข้าแบบ lazy, การจัดแพ็กเกจ หรือพื้นผิว Plugin ที่เผยแพร่