json-canvas

json-canvas skill 概览

json-canvas skill 能做什么

json-canvas skill 用来帮助 AI 代理创建和编辑遵循 JSON Canvas 1.0 结构的 .canvas 文件，这也是 Obsidian 风格可视化画布所采用的格式。它真正的价值不在于“通用画图”，而在于稳定产出合法的 nodes 和 edges JSON：包括正确的 ID、坐标和引用关系，让文件能正常打开，而不是留下那些不易察觉、但会导致画布异常的结构问题。

谁适合安装 json-canvas

这个 json-canvas skill 最适合已经明确想要什么结果的用户：比如思维导图、流程图、项目看板、概念图或笔记画布，但不想手写底层 schema。尤其适合这些场景：你本来就在用 Obsidian、会把 .canvas 文件放进 repo 管理，或者你更需要可重复、可追踪的 AI 辅助修改，而不是一次性的视觉化建议。

为什么它比通用提示词更好

普通提示词也许能描述“方框和箭头”，但往往会漏掉真正关键的格式细节：唯一的 16 位十六进制 ID、合法的 fromNode 和 toNode 引用、不互相重叠的摆放位置，以及文本节点与分组节点的区别。json-canvas skill 给代理提供了明确的目标格式和示例，因此生成后需要返工修补的情况会少很多。

采用前需要了解什么

这个 skill 本来就是为窄场景设计的。它擅长处理 .canvas 文件结构和常见编辑流程；但它不能替代完整的可视化布局引擎、语义化制图工具，或自动设计优化器。如果你的核心需求是更精致的样式效果，或者导出到多种图表格式，那么 json-canvas for Diagramming 可能会显得过于底层。反过来，如果你的需求是尽快得到合法可用的 canvas JSON，它就非常合适。

如何使用 json-canvas skill

安装场景下先看哪里

如果你想在支持 skills 的环境里完成 json-canvas install，先从 kepano/obsidian-skills 仓库添加这个 skill，然后优先阅读 skills/json-canvas/SKILL.md，再看 skills/json-canvas/references/EXAMPLES.md。这两个文件是最实用的核心材料：前者讲清楚必需结构和工作流，后者给出完整示例，方便你直接按模式比照。

json-canvas skill 需要什么输入才更好用

json-canvas usage 的效果，很大程度取决于你的请求是否具体。最好提供：

• 目标文件路径，或现有的 .canvas 内容
• 你要新建画布，还是编辑已有画布
• 需要哪些节点类型，例如 text 或 group
• 大致布局意图，例如从左到右的流程，或 kanban 列布局
• 节点之间希望怎样连接
• 对尺寸或间距是否有要求

一个比较弱的请求是“做一个项目画布”。更强的写法则是：“Create a new .canvas with three group columns labeled To Do, In Progress, Done, each 300x500, spaced 50px apart, and add three text task nodes inside the first two groups.”

如何把模糊目标变成高质量提示词

想提升 json-canvas guide 的产出质量，最好同时要求“生成”和“校验”。一个稳妥的提示词结构可以是：

1. 用自然语言说明目标。
2. 明确是新建还是修改。
3. 定义节点清单及其关系。
4. 要求代理在最终输出前校验 JSON 和边引用。

示例：
“Use the json-canvas skill to create a new .canvas file for a product launch plan. Add one central text node, four supporting text nodes around it, connect each support node to the center, keep 100px spacing to avoid overlap, generate unique 16-character hex IDs, and return valid JSON only.”

能节省时间的实用工作流建议

为了获得更好的 json-canvas usage 效果，建议先简单、再迭代：

• 先让它生成一个结构合法的最小画布
• 打开或检查这个结果
• 然后一次只要求一种修改：加节点、重分组、重连边、或调整位置

如果你是在编辑已有文件，务必让代理先解析当前已有的 ID，再新增任何内容。最常见的损坏原因，就是 ID 冲突，以及边指向了不存在的节点。如果布局对你很重要，要明确写出间距规则；否则 JSON 可能 technically 合法，但视觉上会非常乱。

json-canvas skill 常见问题

json-canvas 适合新手吗？

适合，前提是你已经知道这个画布应该包含什么内容。这个 skill 能帮你省掉大部分 schema 猜测工作，让新手不用背规范也能生成合法的 .canvas 文件。但如果你连图的逻辑结构都还没想清楚，它就没那么理想了；这个 skill 的强项是把结构编码出来，而不是替你完成整套信息设计。

什么时候应该用 json-canvas，而不是普通 AI 提示词？

当输出必须是一个能工作的 .canvas 文件时，就该优先用 json-canvas，尤其是要修改现有画布的时候。通用提示词可以帮你头脑风暴结构，但只要正确性很关键，这个 skill 会更稳：唯一 ID、合法数组、真实节点引用，以及兼容 Obsidian 的格式，都是它的优势。

json-canvas 能覆盖所有制图需求吗？

不能。json-canvas for Diagramming 更适合节点—边画布、简单看板，以及基于笔记链接的可视化组织。它不是 BPMN 工具、精美演示图形工具，也不是高级自动布局系统的替代品。如果你需要更广泛的图表标准支持，或更丰富的样式控制，应该使用别的工具；只有在确实需要时，再考虑转换成 .canvas。

它的主要边界和不适配场景是什么？

如果你的目标根本不是 .canvas 文件，或者你需要很强的自动布局优化，又或者你的单一事实源应该保留在 Mermaid、Excalidraw、电子表格等其他格式里，那就不建议用这个 skill。另一个典型误区是过于模糊的提示，比如“让它看起来更漂亮”；这个 skill 在结构、连接和摆放意图都明确时表现最好。

如何提升 json-canvas skill 的效果

提供更强的结构化输入

想明显提升输出质量，最有效的方法就是一开始就给出更清晰的结构。明确你要哪些节点、它们之间怎么连接，以及预期的空间布局模式。比如“hub-and-spoke”“three-column board”或“timeline from left to right”这类描述，能让代理更合理地摆放节点，而不是靠猜。

预防最常见的失败模式

大多数 json-canvas 问题都很机械：

• ID 重复
• 边指向不存在的节点
• 坐标重叠
• 缺少必填字段，例如 type、x、y、width、height

在返回文件之前，要求代理校验所有 ID 和引用关系。如果是在修改现有 canvas，要明确要求它保留已有 ID，除非这次修改确实需要新增节点或边。

在第一版结果之后继续迭代

把第一版结果当成脚手架，而不是终稿。然后每次只优化一层：

• 调整间距和对齐
• 增加分组
• 细化标签和文本内容
• 增删连接关系

这通常比一次性要求生成一个信息密度很高的最终画布更有效，因为视觉结构上的错误，越早发现越容易修正；等到大规模生成完再找问题，成本会高得多。

有意识地利用示例和仓库模式

要提升 json-canvas skill 的效果，不要全部靠抽象描述，尽量直接借用 references/EXAMPLES.md 里的模式。如果你的目标结果像项目看板，就让代理沿用基于 group 的模式；如果更像概念图，就要求采用简单的文本节点连接模式。复用仓库里原生的模式，通常能得到更干净的 JSON，也更少遇到兼容性上的意外。