# Canvas Design:AI Agent 使用指南 本指南供在用户项目中读取、创建和编辑 `.canvas` 文件的 AI agent 使用。适用于 Canvas Design `0.2.0` 和 `0.2.1` 的已实现功能。扩展标识为 `EvenSo.canvas-design`,VS Code CLI 定位安装目录时使用小写 `evenso.canvas-design`。 画布文件是 [JSON Canvas 1.0](https://jsoncanvas.org/spec/1.0/) JSON,直接用文件编辑工具修改即可。读取和编辑 JSON 不要求 VS Code 正在运行;查看插件渲染和请求截图需要本地 VS Code 打开目标项目,并启用 Canvas Design。终端截图还需要 Node.js,建议使用 22 或更新版本。 ## 推荐工作流程 1. 确认项目根目录、目标 Canvas 文件,以及用户提供的节点路径。先读取目标项目自己的 `AGENTS.md` 或其他 agent 指令。 2. 读取当前文件,按节点 `id` 定位;同时检查相关分组、连线和文件引用。不要按标题、截图位置或数组下标猜测节点。 3. 只修改完成请求所需的字段。保留其他节点、稳定 ID、未知字段、扩展字段和数组顺序。 4. 写入前重新检查源文件是否已被用户或其他 agent 修改;发现变化时基于最新内容重新应用修改。若 VS Code 中有未保存的编辑,先协调保存,避免磁盘内容与编辑器内容互相覆盖。 5. 验证 JSON 和下面的格式约束,检查文件差异,确认没有额外改动。 6. 如果任务涉及视觉效果,保存后请求真实编辑器截图,用图像工具打开返回的 PNG,检查布局、文本、颜色、遮挡和资源加载。需要时继续修改并再次验证。 7. 交付时说明修改了哪个文件、哪些节点和验证结果。无法运行截图时明确说明,不能把 JSON 校验当作视觉验证。 ## 根据复制的路径定位节点 用户可以在画布中右键节点,选择 **Copy Node Path**,得到: ```text design/home.canvas#node=hero-title ``` - `#node=` 前面是 Canvas 文件路径,相对包含该文件的 VS Code 工作区根目录;文件不属于任何已打开的工作区时为绝对路径。目录分隔符统一为 `/`。 - 多根工作区中,路径相对该文件实际所属的根目录。如果多个项目都有同名文件,先确认用户指的是哪个项目。 - 后面是经 `encodeURIComponent` 编码的节点 ID。只解码 ID,不对前面的文件路径进行 URL 解码。 - 在文件的 `nodes` 数组中按 `id` 精确匹配。找不到或有重复匹配时重新读取并核实,不要悄悄修改其他节点。 - 从最后一个 `#node=` 分隔符拆分,兼容文件名本身包含 `#node=` 的情况。这是定位文本,不是磁盘文件名或 VS Code 打开命令。 - 分组和普通节点都使用自身 ID;分组、排序和坐标变化不会改变定位结果。 - 在父画布中复制嵌套 Canvas 的路径,定位到的是父文件的 `file` 节点。修改子画布内部节点时读取被引用的 `.canvas`;用户也可以先双击进入子画布再复制节点路径。 JavaScript 定位示例,`reference` 为用户给出的文本,`data` 为刚读取并解析的 Canvas 对象: ```js const separator = reference.lastIndexOf('#node='); if (separator < 1) throw new Error('Expected a Canvas file path followed by #node='); const canvasPath = reference.slice(0, separator); const nodeId = decodeURIComponent(reference.slice(separator + '#node='.length)); const matches = (data.nodes ?? []).filter((node) => node.id === nodeId); if (matches.length !== 1) throw new Error(`Expected exactly one node with id ${nodeId}`); const node = matches[0]; ``` 节点 ID 不是 HTML/CSS 选择器,也不是节点的标题。不要对它进行大小写转换、重新生成或模糊匹配。 ## 文件结构和最小示例 新文件可以从 `{"nodes":[],"edges":[]}` 开始。已有文件的其他根字段保持原样。 下面是两个文本节点和一条连线的完整有效示例: ```json { "nodes": [ { "id": "hero-title", "type": "text", "x": 0, "y": 0, "width": 320, "height": 100, "text": "Welcome", "canvasDesign": { "shape": "rectangle", "fill": "#F0EDFFFF", "stroke": "#B6A7EFFF", "radius": 16, "fontSize": 28, "parentId": null } }, { "id": "hero-description", "type": "text", "x": 400, "y": 0, "width": 320, "height": 100, "text": "A canvas shared by people and agents." } ], "edges": [ { "id": "hero-connection", "fromNode": "hero-title", "fromSide": "right", "toNode": "hero-description", "toSide": "left", "toEnd": "arrow" } ] } ``` ### 标准字段 | 对象 | 必需字段及约束 | | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | 所有节点 | 非空且在节点数组内唯一的字符串 `id`;`type`;安全整数 `x`、`y`、`width`、`height`。宽高必须大于 0,建议至少 20;坐标可以为负。 | | `text` | 字符串 `text`,包括矩形、椭圆和 HTML 卡片。空字符串有效。 | | `file` | 字符串 `file`,引用本地图片、其他文件或嵌套 `.canvas`。 | | `link` | 字符串 `url`;插件仅打开 `http` 和 `https` 链接。 | | `group` | 可选 `label`、图片 `background` 和 `backgroundStyle`(`cover`、`ratio`、`repeat`)。分组也是普通节点,子节点仍在同一个 `nodes` 数组中。 | | 连线 | 非空且在连线数组内唯一的字符串 `id`,以及指向现有节点 ID 的 `fromNode`、`toNode`。 | | 连线端点 | `fromSide`、`toSide` 可为 `top`、`right`、`bottom`、`left`;`fromEnd`、`toEnd` 可为 `none`、`arrow`。可选字符串 `label`。 | | 标准颜色 | 节点和连线的 `color` 仅使用字符串 `"1"` 至 `"6"`,或 `#RRGGBB`。不要将透明度写入标准 `color`。 | 新增节点和连线时生成新的唯一 ID,例如 `crypto.randomUUID()`;编辑已有对象时保留 ID。`.canvas` 是严格 JSON,不允许注释、尾逗号、`NaN` 或 `Infinity`。 ### 插件样式和局部修改 插件专有字段放在节点的 `canvasDesign` 对象中: | 字段 | 用法 | | --------------------- | ------------------------------------------------------------------------------- | | `shape` | `rectangle` 或 `ellipse`;都保留标准 `type: "text"`。 | | `fill`、`stroke` | `#RRGGBB` 或 `#RRGGBBAA`;`AA` 是最后两位透明度,`00` 为全透明,`FF` 为不透明。 | | `radius` | 圆角,0–256;椭圆不使用该值。 | | `fontSize` | 文本字号,编辑器输入范围为 1–256。 | | `parentId` | 所属分组 ID;显式设为 `null` 表示场景根节点。 | | `type`、`html`、`css` | HTML 卡片,见后文。 | 分组的旧六位填充色会以约 31% 不透明度显示;需要明确透明度时写八位颜色。PNG 和 `.canvas` 文件节点采用无外框显示,不应用卡片背景、边框和圆角;透明图片和嵌套画布空白处会透出下层内容。 修改一个扩展字段时,合并已有对象。例如修改标题和填充色: ```js node.text = 'Updated title'; node.canvasDesign = { ...node.canvasDesign, fill: '#E8F0FFFF' }; ``` 不要用只有 `fill` 的新对象替换整个 `canvasDesign`,否则可能丢失样式、HTML、分组关系和其他扩展数据。未知根、节点和连线字段也同样保留。直接编辑文件时保持原缩进、LF/CRLF 和末尾换行习惯;不为一次小改动重新排列整个文档。 文件编辑不要求调用插件内部的 `Operation`、`EditSession` 或 Webview 消息协议。这些不是终端 agent 的公共编辑 API。视觉编辑使用 VS Code 的撤销栈;外部文件写入不要假设能作为一次视觉操作撤销,应保留可审阅的 diff。 ## 分组、层级、移动和删除 - `nodes` 数组越靠后的节点越在前面。Outliner 的显示顺序与数组相反。除非任务要求调整遮挡关系,不改变数组顺序。 - 显式分组使用 `canvasDesign.parentId`,父节点必须是现有 `group`,层级必须无环。未设置该字段时,编辑器按几何包含关系推断最小的包围分组;明确不属于任何分组时设为 `null`。 - 所有节点使用画布绝对坐标,子节点坐标不是相对父分组的坐标。改变分组归属时保持 `x`、`y`。 - 移动整个分组时,对该分组及其所有后代都应用相同位移;只改分组矩形的坐标不会让外部 JSON 编辑自动移动子节点。 - 重排分组时保持整个子树的相对顺序,分组背景应位于后代节点之前,避免遮挡子节点。 - 删除节点时删除所有连接到它的连线。按插件的“删除分组”语义操作时,删除该分组、所有后代及关联连线。若任务只要求取消分组,则保留子节点和绝对坐标,更新归属关系并移除分组;不要混淆两种操作。 ## 本地资源和嵌套画布 `file` 使用本地路径,优先相对当前 Canvas 所在目录解析,再尝试已打开的工作区根目录。创建新引用时建议使用相对 Canvas 文件的路径,并用 `/` 分隔。例如 `design/home.canvas` 引用项目中的 `assets/logo.png`,可写为 `../assets/logo.png`。 引用必须落在当前 Canvas 目录或打开的工作区内,符号链接解析后的实际位置也必须满足边界限制。需要使用外部资源时,先将用户授权使用的资源放入项目内,再建立引用;不要假设任意绝对路径、远程图片 URL 或 symlink 都能显示。 嵌套 Canvas 保持为 `file` 引用,不把子文件的节点复制进父文件。需要修改复用组件的内容时编辑子文件,并考虑它会影响其他引用位置;只调整父画布里的位置和尺寸时编辑父文件的引用节点。避免循环引用,预览最多展开四层。现有 `subpath` 保留,值须以 `#` 开头;插件目前不展开它。 图片等比适配节点区域,暂不支持裁剪。Markdown 和其他文档作为文件引用卡片显示,双击打开,不在画布里渲染 Markdown 内容。 ## HTML 卡片 HTML 卡片仍是标准 `text` 节点,`text` 是给其他 Canvas 阅读器显示的备用文字: ```json { "id": "project-card", "type": "text", "x": 0, "y": 180, "width": 320, "height": 200, "text": "Project status: Ready", "canvasDesign": { "type": "html", "html": "

Project

Ready

", "css": ".card { box-sizing: border-box; height: 100%; padding: 24px; background: #f0edff; color: #27334b; }" } } ``` 编写静态 HTML 片段和 CSS,不需要完整网页。HTML 和 CSS 在独立 Shadow DOM 中显示,原始源码保留在 JSON 中,渲染时过滤不支持的内容。支持常见静态元素、内联样式、`