json-canvas

json-canvas 技能概览

json-canvas 技能能做什么

json-canvas 技能用于帮助智能体创建或编辑符合规范的 .canvas 文件，适配 Obsidian 及类似制图工具所使用的 JSON Canvas 格式。它真正擅长的并不是“画得好看”，而是“生成结构正确的 canvas JSON”，包括节点、边、分组、位置、尺寸和图层顺序，让画布应用能够真正打开并编辑。

谁适合安装 json-canvas

这个 json-canvas skill 最适合已经明确知道自己想在画布上表达什么内容、但不想手动编写 schema 的用户。它适用于笔记整理、思维导图、流程图、架构草图、研究看板，以及各类轻量级制图流程——前提是你需要的产出是一个真实可用的 .canvas 文件，而不是一段对图的文字描述。

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

普通提示词往往能把格式写到“差不多对”，但经常漏掉必填字段、节点类型或数组结构。json-canvas 的价值在于它围绕 JSON Canvas 的对象模型来工作：顶层 nodes 和 edges、四种节点类型（text、file、link、group），以及像节点数组顺序会影响 z-order 这样的实际细节。如果你的目标是在 Obsidian 中继续制图，而不是只生成一份看起来像 JSON 的示例，那么它能明显减少后续清理成本。

如何使用 json-canvas 技能

安装场景与何时调用 json-canvas

如果你的智能体平台支持 GitHub skills，可按常规技能安装流程，从 MarsWang42/OrbitOS 添加 json-canvas。从仓库证据来看，目前只暴露了 SKILL.md，因此可以预期这是一个偏精简的技能，重点提供格式规则与使用指引，而不是附带 helper scripts 或 validators。凡是任务里明确提到 .canvas、JSON Canvas、Obsidian Canvas，或要求最终产出必须是可编辑 canvas JSON 的可视化图表时，就适合调用它。

什么样的输入最适合 json-canvas

这个技能在你提供“图要怎么表达”时效果最好，而不只是给一个主题。高质量输入通常包括：

• 要表示的节点列表或内容分区
• 节点之间的关系
• 期望使用的节点类型：text、file、link、group
• 大致布局方向：left-to-right、top-down、clustered
• 是否需要用 groups 在视觉上包裹相关节点
• 如果使用 file 或 link 节点，对应的文件引用或 URL

一个较弱的提示词：
“Make a canvas for my project.”

一个更强的提示词：
“Create a .canvas for a project roadmap with three groups: planning, build, launch. Use text nodes for tasks, link nodes for docs URLs, connect task dependencies with edges, and arrange groups left to right.”

如何把模糊目标变成可用提示词

如果想获得稳定的 json-canvas usage 效果，就要同时说明内容和结构。一个实用的提示词写法是：

1. 先定义画布用途。
2. 列出节点类别。
3. 说明关键边关系。
4. 给出版式规则。
5. 明确要求只输出有效的 .canvas JSON。

示例：
“Use the json-canvas skill to generate valid .canvas JSON for diagramming a hiring pipeline. Include groups for sourcing, screening, interview, and offer. Add text nodes for each stage, link nodes for ATS and policy docs, and edges showing candidate flow. Keep nodes spaced for readability and place groups in process order.”

先看什么文件，以及工作流建议

优先阅读 EN/.agents/skills/json-canvas/SKILL.md。重点关注：

• 顶层文件结构
• 节点类型与必填字段
• 边的建模方式
• 通过节点数组顺序控制 z-index 的规则

实用工作流：

1. 先起草节点清单。
2. 生成一个最小可用 canvas。
3. 在你的 canvas app 里打开它。
4. 第二轮再修布局、分组或缺失链接。

相比一开始就要求“最终成品级画布”，这种方式更可靠，因为格式是否正确，比视觉是否精致更容易优先验证。

json-canvas 技能常见问题

json-canvas 只适合在 Obsidian 里画图吗？

不是。json-canvas for Diagramming 适用于所有能读取 JSON Canvas 规范的目标应用。Obsidian 是最直接的使用场景，但它的核心价值是基于标准生成 .canvas 文件，而不是提供只对 Obsidian 生效的样式魔法。

它比直接让 LLM 写 JSON 更好吗？

通常是的，尤其当你的最终产物必须能被稳定加载时。通用提示词在非常小的示例上可能也能工作，但这个技能会把模型约束到实际的 canvas schema 和节点语义上。一旦图里出现多种节点类型、分组区域或大量边关系，这一点就非常重要。

json-canvas 适合新手吗？

适合，前提是你清楚自己想做什么样的画布。你不需要深入掌握规范细节，但需要能够把实体和关系说清楚。如果你连节点或流程都还列不出来，技能仍然能生成结果，但后续很可能需要大量手工修改。

什么情况下不该使用 json-canvas 技能？

如果你只需要静态图片、Mermaid 图、Excalidraw 导出，或纯文本提纲，就没必要用它。另一种不太适合的情况是：你的图依赖某些高级、且只存在于特定应用中的行为，而这些行为并不在基础 JSON Canvas 格式里表达。

如何提升 json-canvas 技能的使用效果

给模型的是画布方案，不只是主题

提升质量最明显的方法，是明确点出节点和边，而不只是丢一个主题。与其说“make a system architecture canvas”，不如直接提供：

• services
• dependencies
• external links
• grouping logic
• preferred reading order

这样不仅能提升生成结果的有效性，也会让布局决策更合理，使这份 json-canvas guide 在实际使用中更有操作性。

规避常见的 json-canvas 失败模式

最常见的问题包括：缺少必填属性、分组表达含糊、布局难以阅读。要降低这些问题，可以：

• 明确要求只输出有效的 .canvas JSON
• 要求使用唯一 node IDs
• 指定大致的画布方向
• 把“必须连接”的边和可选的视觉连线分开说明
• 如果希望 groups 在空间上包裹节点，要明确写出来

如果画布能打开但看起来不对，往往说明结构本身是有效的，只是定位和布局做得不好。

分两步迭代，json-canvas 输出通常更好

一个好的 json-canvas install 决策，往往取决于这个技能是否支持高效迭代。这里是支持的，前提是你分阶段使用它：

• pass 1: 先生成 schema 正确的 nodes 和 edges
• pass 2: 再细调 coordinates、widths、heights 和 groups
• pass 3: 如果视觉层叠很重要，再调整 nodes 顺序

由于节点数组顺序会影响 z-index，所以如果你希望 groups 在内容后面，或者标签显示在最上层，就要明确提出这一点。

初稿之后，接下来该怎么提要求

完成第一次生成后，最好用有约束的方式继续修改：

• “Convert these URLs to link nodes.”
• “Wrap these five nodes in a group node.”
• “Reposition nodes to reduce edge crossings.”
• “Keep the same IDs but add missing dependency edges.”
• “Put groups on lower z-index than text nodes.”

这种受约束的后续修改，通常比从头重新生成整张画布的效果更好。