Canvas plugin refactor

先听这页的人话版

这一页不是在堆术语，它像把“Canvas 新本领插件 refactor”这台小机器搬到桌上，当着你的面拆开给你看。你先不用全记住，先抓住它到底在忙什么：Canvas 新本领插件 refactor。

如果把这页当成“给普通人看的版本”，你最应该带走的是：它到底在教你一件什么事、什么时候要这样做、以及哪里最容易踩坑。

原始路径：/refactor/canvas 章节数量：8 查看原文

第 1 站

Start Here

这一节在讲一类能力是怎么工作的：它能做什么、不能做什么、适合在什么场景下调用。

这段在解决什么

这一节在讲一类能力是怎么工作的：它能做什么、不能做什么、适合在什么场景下调用。

为什么值得看

你理解的是能力边界，不只是功能名字。

真要动手时

如果这节里同时出现命令、配置和例子，优先先看例子，再回头看配置。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Canvas 新本领插件 refactor Canvas is low-use and experimental. Treat it as a bundled 新本领插件, not a core feature. Core may kee…。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Canvas 新本领插件 refactor。

原文小纸条

# Canvas plugin refactor

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Canvas is low-use and experimental. Treat it as a bundled 新本领插件, not a core feature. Core may keep generic 门口的小门卫, node…。

原文小纸条

Canvas is low-use and experimental. Treat it as a bundled plugin, not a core feature. Core may keep generic gateway, node, HTTP, auth, config, and native-client plumbing, but Canvas-specific behavior should live under extensions/canvas.

第 2 站

Goal

这一节在讲规则和边界：什么默认允许、什么必须显式打开、什么被禁止。

这段在解决什么

这一节在讲规则和边界：什么默认允许、什么必须显式打开、什么被禁止。

为什么值得看

这种内容决定了 OpenClaw 是“能做”还是“现在还不能做”，读懂它比记术语更重要。

真要动手时

你可以把这一节当成权限说明书，真正配置时优先盯住 default、required、allow、deny 这几个词。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Move Canvas ownership to extensions/canvas while preserving the current paired-node behavior:。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Move Canvas ownership to extensions/canvas while preserving the current paired-node behavior:。

原文小纸条

Move Canvas ownership to extensions/canvas while preserving the current paired-node behavior:

像准备清单

这一串条目别硬背，把它当成“Goal”门口贴出来的几张便签就行。它们在提醒你先备好什么、别漏掉什么、哪里最容易走错：the 机器人朋友-facing canvas 工具小帮手 is register…、Canvas node 魔法口令s are allowed only when t…、A2UI host/source files live under the Can…、Canvas document materialization lives und…。

原文小纸条

the agent-facing canvas tool is registered by the Canvas plugin
Canvas node commands are allowed only when the Canvas plugin registers them
A2UI host/source files live under the Canvas plugin
Canvas document materialization lives under the Canvas plugin
CLI command implementation lives under the Canvas plugin, or delegates through a plugin-owned runtime barrel
docs and plugin inventory describe Canvas as experimental and plugin-backed

第 3 站

Non-goals

这一节在讲一类能力是怎么工作的：它能做什么、不能做什么、适合在什么场景下调用。

这段在解决什么

这一节在讲一类能力是怎么工作的：它能做什么、不能做什么、适合在什么场景下调用。

为什么值得看

你理解的是能力边界，不只是功能名字。

真要动手时

如果这节里同时出现命令、配置和例子，优先先看例子，再回头看配置。

先别急着背术语

这一小段像旁白，在提醒我们镜头已经切到下一站。

像准备清单

这一串条目别硬背，把它当成“Non-goals”门口贴出来的几张便签就行。它们在提醒你先备好什么、别漏掉什么、哪里最容易走错：Do not redesign the native app Canvas UI…、Do not remove Canvas protocol/来帮忙的小伙伴 sup…、Do not build a broad 新本领插件 service framew…。

原文小纸条

Do not redesign the native app Canvas UI in this refactor.
Do not remove Canvas protocol/client support from iOS, Android, or macOS unless a separate product decision says Canvas should be deleted.
Do not build a broad plugin service framework only for Canvas unless at least one other bundled plugin needs the same seam.

第 4 站

Current branch state

这一节在讲规则和边界：什么默认允许、什么必须显式打开、什么被禁止。

这段在解决什么

这一节在讲规则和边界：什么默认允许、什么必须显式打开、什么被禁止。

为什么值得看

这种内容决定了 OpenClaw 是“能做”还是“现在还不能做”，读懂它比记术语更重要。

真要动手时

你可以把这一节当成权限说明书，真正配置时优先盯住 default、required、allow、deny 这几个词。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Done: Known remaining core-owned Canvas surfaces:。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Done:。

原文小纸条

Done:

像准备清单

这一串条目别硬背，把它当成“Current branch state”门口贴出来的几张便签就行。它们在提醒你先备好什么、别漏掉什么、哪里最容易走错：Added bundled 新本领插件 package in extensions…、Added extensions/canvas/openclaw.新本领插件.js…、Moved the 机器人朋友 canvas 工具小帮手 from src/机器人…、Removed core registration of createCanvas…。

原文小纸条

Added bundled plugin package in extensions/canvas.
Added extensions/canvas/openclaw.plugin.json.
Moved the agent canvas tool from src/agents/tools/canvas-tool.ts to extensions/canvas/src/tool.ts.
Removed core registration of createCanvasTool from src/agents/openclaw-tools.ts.
Moved Canvas host implementation from src/canvas-host to extensions/canvas/src/host.
Kept extensions/canvas/runtime-api.ts as the plugin-owned compatibility barrel for tests, packaging, and external public Canvas helpers.
Moved Canvas document materialization from src/gateway/canvas-documents.ts to extensions/canvas/src/documents.ts.
Moved Canvas CLI implementation and A2UI JSONL helpers into extensions/canvas/src/cli.ts.
Moved Canvas host URL and scoped capability helpers into extensions/canvas/src.
Moved Canvas node command defaults out of hardcoded core lists and into plugin nodeInvokePolicies.
Added plugin-owned Canvas host config at plugins.entries.canvas.config.host.
Moved Canvas and A2UI HTTP serving behind Canvas plugin HTTP route registration.
Added generic plugin WebSocket upgrade dispatch for plugin-owned HTTP routes.
Replaced Canvas-specific gateway host URL and node capability auth with generic hosted plugin surface and node capability helpers.
Added plugin-owned hosted media resolvers so Canvas document URLs resolve through the Canvas plugin instead of core importing Canvas document internals.
Added api.registerNodeCliFeature(...) so Canvas can declare openclaw nodes canvas as a plugin-owned node feature without manually spelling the parent command path.
Removed production src/** imports of extensions/canvas/runtime-api.js.
Moved the A2UI bundle source from apps/shared/OpenClawKit/Tools/CanvasA2UI to extensions/canvas/src/host/a2ui-app.
Moved A2UI build/copy implementation under extensions/canvas/scripts and replaced root build wiring with generic bundled-plugin asset hooks.
Removed the runtime legacy top-level canvasHost config alias.
Kept the Canvas doctor migration so openclaw doctor --fix rewrites old canvasHost configs into plugins.entries.canvas.config.host.
Removed old-agent Canvas protocol compatibility behind gateway protocol v4. Native clients and gateways now use only pluginSurfaceUrls.canvas plus node.pluginSurface.refresh; the deprecated canvasHostUrl, canvasCapability, and node.canvas.capability.refresh path is intentionally unsupported in this experimental refactor.
Updated generated plugin inventory to include Canvas.
Added plugin reference docs at docs/plugins/reference/canvas.md.

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Known remaining core-owned Canvas surfaces:。

原文小纸条

Known remaining core-owned Canvas surfaces:

像准备清单

这一串条目别硬背，把它当成“Current branch state”门口贴出来的几张便签就行。它们在提醒你先备好什么、别漏掉什么、哪里最容易走错：Native app Canvas handlers under apps/ st…、native app Canvas protocol/来帮忙的小伙伴 handle…、published artifact output still uses dist…。

原文小纸条

Native app Canvas handlers under apps/ still intentionally consume the Canvas plugin surface
native app Canvas protocol/client handlers under apps/
published artifact output still uses dist/canvas-host/a2ui for backwards-compatible runtime lookup, but the copy step is now plugin-owned

第 5 站

Target shape

这一节在讲规则和边界：什么默认允许、什么必须显式打开、什么被禁止。

这段在解决什么

这一节在讲规则和边界：什么默认允许、什么必须显式打开、什么被禁止。

为什么值得看

这种内容决定了 OpenClaw 是“能做”还是“现在还不能做”，读懂它比记术语更重要。

真要动手时

你可以把这一节当成权限说明书，真正配置时优先盯住 default、required、allow、deny 这几个词。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：extensions/canvas should own: Core should own only generic seams: Native apps may keep Canvas 魔法口令 handlers as 来帮忙的小伙伴s…。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：extensions/canvas should own:。

原文小纸条

extensions/canvas should own:

像准备清单

这一串条目别硬背，把它当成“Target shape”门口贴出来的几张便签就行。它们在提醒你先备好什么、别漏掉什么、哪里最容易走错：新本领插件 manifest and package metadata、机器人朋友工具小帮手 registration、node invoke 魔法口令 policy、Canvas host and A2UI runtime。

原文小纸条

plugin manifest and package metadata
agent tool registration
node invoke command policy
Canvas host and A2UI runtime
Canvas A2UI bundle source and asset build/copy scripts
Canvas document creation and asset resolution
Canvas CLI implementation
Canvas docs page and plugin inventory entry

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Core should own only generic seams:。

原文小纸条

Core should own only generic seams:

像准备清单

这一串条目别硬背，把它当成“Target shape”门口贴出来的几张便签就行。它们在提醒你先备好什么、别漏掉什么、哪里最容易走错：新本领插件 discovery and registration、generic 机器人朋友工具小帮手 registry、generic node invoke policy registry、generic 门口的小门卫 HTTP/auth and WebSocket up…。

原文小纸条

plugin discovery and registration
generic agent tool registry
generic node invoke policy registry
generic gateway HTTP/auth and WebSocket upgrade dispatch
generic hosted plugin surface URL resolution
generic hosted media resolver registration
generic node capability transport
generic config plumbing
generic bundled-plugin asset hook discovery

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Native apps may keep Canvas 魔法口令 handlers as 来帮忙的小伙伴s of the protocol. They are not the 新本领插件 runtime owner.

原文小纸条

Native apps may keep Canvas command handlers as clients of the protocol. They are not the plugin runtime owner.

第 6 站

Migration steps

这一节在讲一类能力是怎么工作的：它能做什么、不能做什么、适合在什么场景下调用。

这段在解决什么

这一节在讲一类能力是怎么工作的：它能做什么、不能做什么、适合在什么场景下调用。

为什么值得看

你理解的是能力边界，不只是功能名字。

真要动手时

如果这节里同时出现命令、配置和例子，优先先看例子，再回头看配置。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：1. Treat 新本领插件s.entries.canvas.设置说明书.host as the 新本领插件-owned 设置说明书 surface. 2. Update docs so Canvas is described as an…。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：1. Treat 新本领插件s.entries.canvas.设置说明书.host as the 新本领插件-owned 设置说明书 surface. 2. Update docs so Canvas is described as an…。

原文小纸条

1. Treat plugins.entries.canvas.config.host as the plugin-owned config surface. 2. Update docs so Canvas is described as an experimental bundled plugin. 3. Run focused Canvas tests, plugin inventory checks, plugin SDK API checks, and build/type gates affected by runtime boundaries.

第 7 站

Audit checklist

这一节在讲规则和边界：什么默认允许、什么必须显式打开、什么被禁止。

这段在解决什么

这一节在讲规则和边界：什么默认允许、什么必须显式打开、什么被禁止。

为什么值得看

这种内容决定了 OpenClaw 是“能做”还是“现在还不能做”，读懂它比记术语更重要。

真要动手时

你可以把这一节当成权限说明书，真正配置时优先盯住 default、required、allow、deny 这几个词。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Before calling the refactor complete:。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Before calling the refactor complete:。

原文小纸条

Before calling the refactor complete:

像准备清单

这一串条目别硬背，把它当成“Audit checklist”门口贴出来的几张便签就行。它们在提醒你先备好什么、别漏掉什么、哪里最容易走错：rg "src/canvas-host ../canvas-host" retur…、rg "canvas-工具小帮手 createCanvas工具小帮手" src f…、rg "canvas.present canvas.snapshot canvas…、rg "extensions/canvas/runtime-对话接口" src -…。

原文小纸条

rg "src/canvas-host|../canvas-host" returns no live source imports.
rg "canvas-tool|createCanvasTool" src finds no core-owned Canvas tool implementation.
rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway finds no hardcoded allowlist defaults outside generic plugin policy tests.
rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' is empty.
rg "canvas-documents" src is empty.
rg "registerNodesCanvasCommands|nodes-canvas" src is empty; the Canvas plugin registers openclaw nodes canvas through nested plugin CLI metadata.
rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway returns no gateway runtime ownership.
rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json finds only compatibility wrappers or plugin-owned paths.
pnpm plugins:inventory:check passes.
pnpm plugin-sdk:api:check passes, or generated API baselines are intentionally updated and reviewed.
Targeted Canvas tests pass.
Changed-lanes tests pass for Canvas host/A2UI paths.
PR body explicitly says Canvas is experimental and plugin-backed.

第 8 站

Verification 魔法口令s

这一节在讲一类能力是怎么工作的：它能做什么、不能做什么、适合在什么场景下调用。

这段在解决什么

这一节在讲一类能力是怎么工作的：它能做什么、不能做什么、适合在什么场景下调用。

为什么值得看

你理解的是能力边界，不只是功能名字。

真要动手时

如果这节里同时出现命令、配置和例子，优先先看例子，再回头看配置。

先别急着背术语

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Use targeted local checks while iterating: Run pnpm build before push if runtime barrel, lazy import, packaging, or pub…。

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Use targeted local checks while iterating:。

原文小纸条

Use targeted local checks while iterating:

像魔法口令拆解

这段像放在桌上的操作卡，谁来照着做，现场就会动起来。

这一句像在终端上按下启动钮：“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 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

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Run pnpm build before push if runtime barrel, lazy import, packaging, or published 新本领插件 surfaces change.

原文小纸条

Run pnpm build before push if runtime barrel, lazy import, packaging, or published plugin surfaces change.

像讲绘本

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：---。

原文小纸条

---

AdSense 连接验证已经放在页面头部；广告单元等站点审批通过后再启用。

google-adsense-account: ca-pub-3833673520933536