# بازآرایی 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 قرار می‌گیرد، یا از طریق یک barrel زمان اجرای متعلق به Plugin واگذار می‌شود
• مستندات و فهرست موجودی Plugin، Canvas را به‌عنوان آزمایشی و متکی بر Plugin توصیف می‌کنند

# غیرهدف‌ها

• در این بازآرایی، رابط کاربری Canvas در برنامه بومی را بازطراحی نکنید.
• پشتیبانی پروتکل/کلاینت Canvas را از iOS، Android، یا macOS حذف نکنید، مگر اینکه یک تصمیم محصولی جداگانه بگوید Canvas باید حذف شود.
• فقط برای Canvas یک چارچوب گسترده سرویس Plugin نسازید، مگر اینکه دست‌کم یک Plugin همراه دیگر به همان seam نیاز داشته باشد.

# وضعیت فعلی شاخه

انجام‌شده:

• بسته 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 به‌عنوان 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 قرار گرفت.
• dispatch عمومی ارتقای WebSocket برای مسیرهای HTTP متعلق به Plugin اضافه شد.
• URL میزبان ویژه Canvas در Gateway و احراز هویت قابلیت Node با سطح عمومی Plugin میزبانی‌شده و کمک‌کننده‌های قابلیت Node جایگزین شد.
• resolverهای رسانه میزبانی‌شده متعلق به Plugin اضافه شدند تا URLهای سند Canvas به‌جای import کردن داخلیات سند Canvas توسط هسته، از طریق Plugin Canvas resolve شوند.
• api.registerNodeCliFeature(...) اضافه شد تا Canvas بتواند openclaw nodes canvas را به‌عنوان قابلیت Node متعلق به Plugin اعلام کند، بدون اینکه مسیر فرمان والد را دستی بنویسد.
• importهای production از extensions/canvas/runtime-api.js در src/** حذف شدند.
• منبع bundle مربوط به A2UI از apps/shared/OpenClawKit/Tools/CanvasA2UI به extensions/canvas/src/host/a2ui-app منتقل شد.
• پیاده‌سازی build/copy مربوط به A2UI زیر extensions/canvas/scripts منتقل شد و سیم‌کشی build ریشه با hookهای دارایی عمومی Plugin همراه جایگزین شد.
• alias پیکربندی قدیمی و سطح‌بالای زمان اجرا canvasHost حذف شد.
• مهاجرت doctor مربوط به Canvas نگه داشته شد تا openclaw doctor --fix پیکربندی‌های قدیمی canvasHost را به plugins.entries.canvas.config.host بازنویسی کند.
• سازگاری پروتکل Canvas مربوط به عامل‌های قدیمی پشت پروتکل Gateway نسخه ۴ حذف شد. کلاینت‌های بومی و Gatewayها اکنون فقط از pluginSurfaceUrls.canvas به‌همراه node.pluginSurface.refresh استفاده می‌کنند؛ مسیر منسوخ canvasHostUrl، canvasCapability، و node.canvas.capability.refresh در این بازآرایی آزمایشی عمداً پشتیبانی نمی‌شود.
• فهرست موجودی تولیدشده Plugin برای شامل کردن Canvas به‌روزرسانی شد.
• مستندات مرجع Plugin در docs/plugins/reference/canvas.md اضافه شد.

سطوح شناخته‌شده Canvas که هنوز متعلق به هسته هستند:

• handlerهای Canvas در برنامه بومی زیر apps/ هنوز عمداً سطح Plugin Canvas را مصرف می‌کنند
• handlerهای پروتکل/کلاینت Canvas در برنامه بومی زیر apps/
• خروجی artifact منتشرشده هنوز برای lookup زمان اجرای سازگار با گذشته از dist/canvas-host/a2ui استفاده می‌کند، اما گام copy اکنون متعلق به Plugin است

# شکل هدف

extensions/canvas باید مالک این موارد باشد:

• manifest و فراداده بسته Plugin
• ثبت ابزار عامل
• سیاست فرمان invoke در Node
• میزبان Canvas و زمان اجرای A2UI
• منبع bundle مربوط به Canvas A2UI و اسکریپت‌های build/copy دارایی
• ایجاد سند Canvas و resolve دارایی
• پیاده‌سازی CLI مربوط به Canvas
• صفحه مستندات Canvas و ورودی فهرست موجودی Plugin

هسته باید فقط مالک seamهای عمومی باشد:

• کشف و ثبت Plugin
• رجیستری عمومی ابزار عامل
• رجیستری عمومی سیاست invoke در Node
• HTTP/auth عمومی Gateway و dispatch ارتقای WebSocket
• resolve عمومی URL سطح Plugin میزبانی‌شده
• ثبت عمومی resolver رسانه میزبانی‌شده
• انتقال عمومی قابلیت Node
• لوله‌کشی عمومی پیکربندی
• کشف عمومی hook دارایی Plugin همراه

برنامه‌های بومی می‌توانند handlerهای فرمان Canvas را به‌عنوان کلاینت‌های پروتکل نگه دارند. آن‌ها مالک زمان اجرای Plugin نیستند.

# گام‌های مهاجرت

1. plugins.entries.canvas.config.host را به‌عنوان سطح پیکربندی متعلق به Plugin در نظر بگیرید.
2. مستندات را به‌روزرسانی کنید تا Canvas به‌عنوان یک Plugin همراه آزمایشی توصیف شود.
3. تست‌های متمرکز Canvas، بررسی‌های فهرست موجودی Plugin، بررسی‌های API مربوط به SDK Plugin، و gateهای build/type تحت تأثیر مرزهای زمان اجرا را اجرا کنید.

# چک‌لیست audit

پیش از کامل دانستن بازآرایی:

• rg "src/canvas-host|../canvas-host" هیچ import زنده‌ای از منبع برنگرداند.
• rg "canvas-tool|createCanvasTool" src هیچ پیاده‌سازی ابزار Canvas متعلق به هسته پیدا نکند.
• rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway هیچ پیش‌فرض allowlist سخت‌کدشده‌ای بیرون از تست‌های عمومی سیاست 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 هیچ مالکیت زمان اجرای 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 قبول شود، یا baselineهای 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.ts
pnpm test src/gateway/server.plugin-node-capability-auth.test.ts src/gateway/server-import-boundary.test.ts
pnpm test extensions/canvas/src/config-migration.test.ts src/commands/doctor-legacy-config.migrations.test.ts
pnpm 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.ts
pnpm tsgo:extensions
pnpm plugins:inventory:check
pnpm plugin-sdk:api:check

اگر barrel زمان اجرا، import تنبل، بسته‌بندی، یا سطوح منتشرشده Plugin تغییر کرد، پیش از push، pnpm build را اجرا کنید.