初始化项目版本

.agents/skills/canvas-workspace/references/axhub-nodes.md

@@ -0,0 +1,112 @@
+# Axhub 画布节点
+
+Axhub 画布节点本质上是标准 Excalidraw 元素，Axhub 扩展信息存放在 `customData` 中。
+
+## 通用字段
+
+| 字段 | 含义 |
+| --- | --- |
+| `customData.title` | 面向用户的节点标题 |
+| `customData.previewUrl` | 预览模式中渲染的 URL |
+| `customData.openUrl` | 节点操作中打开的 URL |
+| `customData.previewKind` | 渲染类型，例如 `web`、`doc`、`image`、`none` |
+| `customData.resourceType` | 资源类型：`prototype`、`doc` 或 `theme` |
+| `customData.resourceId` | 项目 metadata 中的资源 id 或名称 |
+| `customData.embedViewMode` | `link` 表示紧凑链接卡片，`preview` 表示渲染嵌入预览 |
+| `customData.embedContentScale` | 预览内容缩放比例，例如 `0.5` 表示画布节点按 50% 显示，但 iframe 使用 2 倍视口渲染 |
+| `customData.screenshotUrl` | 运行时已捕获的持久化预览截图 URL |
+| `customData.annotation` | 元素批注文本 |
+| `customData.annotationUpdatedAt` | 批注更新时间，ISO 8601 格式 |
+
+## 嵌入资源节点
+
+嵌入资源使用 `type: "embeddable"`。
+
+### 原型节点
+
+通过 `customData.resourceType: "prototype"` 识别；也可以结合指向原型的 `link` 或 `previewUrl` 判断。
+
+常见字段：
+
+```json
+{
+  "type": "embeddable",
+  "link": "/?resourceType=prototype&resourceId=<prototype-id>&view=demo&sidebar=collapsed",
+  "customData": {
+    "title": "原型标题",
+    "previewUrl": "http://localhost:<port>/prototypes/<prototype-id>",
+    "openUrl": "/?resourceType=prototype&resourceId=<prototype-id>&view=demo&sidebar=collapsed",
+    "previewKind": "web",
+    "resourceType": "prototype",
+    "resourceId": "<prototype-id>",
+    "embedViewMode": "link"
+  }
+}
+```
+
+### 文档节点
+
+通过 `customData.type: "axhub-doc"` 或 `customData.resourceType: "doc"` 识别。
+当画布任务需要生成文档、说明、PRD、清单、列表、报告或其他文本内容时，优先把正文写成 `src/resources/` 下的 Markdown，再用文档节点引用该资源；画布只放摘要或入口。
+
+常见字段：
+
+```json
+{
+  "type": "embeddable",
+  "link": "/api/markdown-file?path=<encoded-path>",
+  "customData": {
+    "type": "axhub-doc",
+    "title": "文档标题",
+    "previewUrl": "/api/markdown-file?path=<encoded-path>",
+    "previewKind": "doc",
+    "resourceType": "doc",
+    "resourceId": "<doc-id>",
+    "embedViewMode": "link"
+  }
+}
+```
+
+### 主题节点
+
+通过 `customData.resourceType: "theme"` 或 `customData.type: "axhub-theme"` 识别。
+
+主题节点与原型/文档节点使用相同的 `embeddable` 结构，`resourceType` 为 `theme`，`previewKind` 通常为 `web` 或 `none`。
+
+## Drawio 节点
+
+Drawio 节点是图片元素。`files[fileId].dataURL` 保存带 Drawio XML 的 SVG 预览，`customData.type` 固定为 `axhub-drawio`。
+
+只有用户明确要求 Draw.io、`.drawio`、diagrams.net、可编辑 Draw.io 资产，或 `canvas-workspace` 已选择 Drawio 节点时，才在当前原型的 `canvas.excalidraw` 中创建或更新这种节点。
+识别 Drawio 节点以 `customData.type: "axhub-drawio"` 为准；`previewKind` 只是预览展示元信息。
+
+```json
+{
+  "type": "image",
+  "fileId": "drawio-file-<id>",
+  "customData": {
+    "type": "axhub-drawio",
+    "title": "Drawio 图表",
+    "previewKind": "drawio"
+  }
+}
+```
+
+创建或更新 Drawio 节点时：
+
+- 推荐持久化资源文件后缀为 `.drawio.svg`，例如 `src/prototypes/<prototype-name>/canvas-assets/diagrams/<diagram-id>.drawio.svg`。
+- `files[fileId].dataURL` 应是 `data:image/svg+xml;base64,...`。
+- SVG 根节点应使用 `data-drawio="<base64-encoded mxfile>"` 保存 Drawio XML，便于后续在 diagrams.net 编辑器里继续编辑。
+- 如果只是初始化一个空 Drawio 节点，可以使用默认空图 XML；如果已经确定使用 Draw.io 承载流程图或关系图，应把图结构写入 Drawio XML，而不是只写普通 Excalidraw 文本框。
+
+## 图片文件
+
+图片元素通过 `files[element.fileId]` 读取图片数据。
+
+原型嵌入节点如果存在 `customData.screenshotUrl`，优先使用该截图地址。截图文件常见位置：
+
+```text
+src/prototypes/<prototype-name>/canvas-assets/embed-<elementId>.png
+```
+
+截图缓存不等同于页面实现素材；只有用户明确要求把它作为素材使用时，才把它当作实现资产处理。