创建或编辑 JSON Canvas（.canvas）可视化画…

在创建或编辑 `.canvas` 文件、思维导图、流程图或 Obsidian Canvas 时，按 JSON Canvas Spec 1.0 组织 nodes/edges、节点类型、边、颜色与布局并做完整性校验。

适用场景

解决思路

1. 创建 `.canvas` 文件时，先写入包含 `nodes` 和 `edges` 两个顶层数组的基础结构；`nodes` 存放节点对象，`edges` 存放连接节点的边对象。
2. 为每个节点生成唯一的 16 字符十六进制 ID（例如 `6f0ad84f44ce9c17`）。
3. 添加节点时，必须包含必需字段：`id`、`type`、`x`、`y`、`width`、`height`。
4. 添加边时，用 `fromNode` 和 `toNode` 引用有效的节点 ID。
5. 创建新 Canvas 后验证：解析 JSON 确认有效，并检查所有 `fromNode`/`toNode` 都存在于 `nodes` 数组中。
6. 向已有 Canvas 添加节点时，读取并解析现有 `.canvas` 文件。
7. 生成不会与现有节点或边 ID 冲突的唯一 ID。
8. 选择不会与已有节点重叠的 `x`、`y` 位置，节点间保留 50-100px 间距。
9. 将新节点对象追加到 `nodes` 数组。
10. 可选：添加连接新节点与已有节点的边。
11. 添加节点后验证：确认所有 ID 唯一，且所有边引用都能解析到现有节点。
12. 连接两个节点时，先确定源节点和目标节点的 ID。
13. 生成唯一的边 ID。
14. 将 `fromNode` 和 `toNode` 分别设为源节点和目标节点 ID。
15. 可选：设置 `fromSide`/`toSide`（`top`、`right`、`bottom`、`left`）指定锚点。
16. 可选：设置 `label` 为边添加描述文本。
17. 将边追加到 `edges` 数组。
18. 连接后验证：确认 `fromNode` 和 `toNode` 都引用现有节点 ID。
19. 编辑已有 Canvas 时，读取并解析 `.canvas` 文件为 JSON。
20. 按 `id` 定位目标节点或边。
21. 修改所需属性（如 `text`、位置、`color` 等）。
22. 将更新后的 JSON 写回文件。
23. 编辑后验证：重新检查所有 ID 唯一性和边引用完整性。
24. 节点是放置在画布上的对象；`nodes` 数组顺序决定 z-index：第一个节点在最底层，最后一个节点在最顶层。
25. 通用节点属性：`id` 必需、string、唯一 16 字符十六进制标识符；`type` 必需、string、取 `text`、`file`、`link` 或 `group`；`x` 必需、integer、像素 X 坐标；`y` 必需、integer、像素 Y 坐标；`width` 必需、integer、像素宽度；`height` 必需、integer、像素高度；`color` 可选、`canvasColor`、可用预设字符串 `1`-`6` 或十六进制（如 `#FF0000`）。
26. 文本节点：必须有 `text` 字段（string），内容为带 Markdown 语法的纯文本。
27. 换行陷阱：JSON 字符串中用 `\n` 表示换行；不要使用字面量 `\\n`，否则 Obsidian 会渲染成反斜杠和 n 字符。
28. 文件节点：必须有 `file` 字段（string），表示系统内文件路径；可选 `subpath`（string），链接到标题或块，以 `#` 开头。
29. 链接节点：必须有 `url` 字段（string），表示外部 URL。
30. 分组节点：`type` 为 `group`，用作组织其他节点的可视容器；把子节点放在分组边界内。可选 `label`（string）文本标签；可选 `background`（string）背景图片路径；可选 `backgroundStyle`（string）取 `cover`、`ratio` 或 `repeat`。
31. 边通过 `fromNode` 和 `toNode` ID 连接节点。
32. 边属性：`id` 必需、唯一标识符；`fromNode` 必需、源节点 ID；`fromSide` 可选、取 `top`、`right`、`bottom`、`left`；`fromEnd` 可选、默认 `none`、取 `none` 或 `arrow`；`toNode` 必需、目标节点 ID；`toSide` 可选、取 `top`、`right`、`bottom`、`left`；`toEnd` 可选、默认 `arrow`、取 `none` 或 `arrow`；`color` 可选、`canvasColor`、线颜色；`label` 可选、文本标签。
33. `canvasColor` 类型接受十六进制字符串或预设编号：`1`=红、`2`=橙、`3`=黄、`4`=绿、`5`=青、`6`=紫。预设颜色值有意未定义，应用程序使用自己的品牌色。
34. 生成 16 字符小写十六进制字符串（64 位随机值），例如 `6f0ad84f44ce9c17`、`a3b2c1d0e9f8a7b6`。
35. 布局指南：坐标可为负数（画布无限延伸）；`x` 向右递增，`y` 向下递增；位置是左上角坐标。
36. 布局指南：节点之间留 50-100px 间距；分组内部留 20-50px 内边距。
37. 布局指南：对齐到网格（10 或 20 的倍数）以获得更整洁布局。
38. 布局建议尺寸：小文本 200-300 × 80-150；中等文本 300-450 × 150-300；大文本 400-600 × 300-500；文件预览 300-500 × 200-400；链接预览 250-400 × 100-200。
39. 创建或编辑 Canvas 后按验证清单检查：所有 `id` 值在节点和边之间唯一。
40. 验证：每个 `fromNode` 和 `toNode` 都引用现有节点 ID。
41. 验证：每种节点类型的必需字段都存在（文本节点有 `text`，文件节点有 `file`，链接节点有 `url`）。
42. 验证：`type` 是 `text`、`file`、`link`、`group` 之一。
43. 验证：`fromSide`/`toSide` 值是 `top`、`right`、`bottom`、`left` 之一。
44. 验证：`fromEnd`/`toEnd` 值是 `none`、`arrow` 之一。
45. 验证：颜色预设是 `1` 到 `6` 或有效十六进制（如 `#FF0000`）。
46. 验证：JSON 有效且可解析。
47. 如果验证失败，检查重复 ID、悬空边引用或格式错误的 JSON 字符串（尤其是文本内容中未转义的换行）。
48. 需要完整示例（思维导图、项目看板、研究画布、流程图）时，查看 `references/EXAMPLES.md`。
49. 参考规范：JSON Canvas Spec 1.0（https://jsoncanvas.org/spec/1.0/）和 JSON Canvas GitHub（https://github.com/obsidianmd/jsoncanvas）。

适用边界 · 注意事项

• 当目标格式不是 JSON Canvas 1.0 或不使用 `.canvas` 文件时，不适用。
• 当需要 Obsidian 专有插件、动态渲染或非 JSON Canvas 支持的功能时，不适用。
• 当仅需普通 Markdown/文本笔记、无需可视化节点和边时，不适用。