Canvas atlas
让读者先理解整体,再进入细节。输出可以直接在 Obsidian 打开的 .canvas,而不是 Mermaid 截图。
确定范围
从请求和当前环境确定来源、读者的问题、输出位置及模式。只在缺失信息会改变范围时询问。遵守目标 vault 的就近规则。未指定 vault 时先查当前项目配置或 Obsidian CLI;无法确定则交付独立文件包,不猜路径。
single:一个 Canvas,用分组区分层次。用户要求单文件时,解释写入文本卡片,不强制生成伴随笔记。nested:一个总览加必要的子 Canvas。默认使用原生文件引用和链接导航。auto:默认。先设计一张总览;只有某个部分需要独立解释时才拆图。- 更新已有地图:读取整份现有 Canvas 和链接目标,按下方更新协议操作。
这些是意图选项,不是已经安装的 CLI 参数。不为本任务安装插件、启动云服务或发布内容。
阅读并提炼
- 写出读者看完地图应能回答的一个主问题。仓库可从入口、核心模块和一次真实执行链取证;笔记集合可从主张、依据、分歧和应用取证。不要把文件目录直接当架构。
- 选择有依据的视角。总览说明系统边界与模块职责;流程说明触发、处理、状态和输出;决策说明约束、取舍和未决问题。仅创建对当前材料有用的视角。
- 在工作草稿中记录每个元素的稳定语义键、职责、来源位置和已证实关系。仓库来源优先采用固定 commit 的文件链接;vault 内来源使用真实存在的笔记路径及标题或块引用。没有仓库远端时显示相对源码位置,不把 vault 外文件伪装成可嵌入笔记。
- 区分事实、推断和建议。推断及建议在卡片正文中明示。不要凭模块名称推断调用关系;不能确认的关系留在“待核实”说明中。
设计阅读路径
先为总览写一句能够独立成立的解释,再安排节点。
- 总览通常保留 5–9 个核心元素。数量是阅读预算,不是硬阈值;按内容调整。每张图只回答一个主要问题。
- 一个元素值得展开,需有独立子职责、内部流程或关键取舍。不要为每个文件生成子图。
- 子图默认不超过两层;更深层次需有明确阅读收益。子图提供返回父图的文字链接。
- 连线用动词或短语说明关系,例如“调用”“写入”“发布事件”“约束”。导航入口明确写“进入子图”,不混作业务调用。
- 总览中的子图入口仍需说明职责、输入与输出。读者不打开子图,也能看懂整体。
- 把限制和关键决策放在读者会看到的位置。不要为了显得完整,给每个节点机械填满七种文档字段。
生成可读的 Canvas
创建前读取 references/canvas-contract.md。需要完整格式说明时,使用环境已有的 json-canvas Skill;本 Skill 的最小契约足够生成基础图,不要求该 Skill 必须安装。
创建新图或调整风格前读取 references/visual-styles.md。分别选择构图 style 和配色 palette;未指定时按材料选择,并在交付时说明。它们是自然语言意图,不是 CLI 参数或 Canvas 字段。避免让每次输出都变成等宽网格,也不要用随机错位制造变化。
- 核心卡片写短标题、1–3 句解释及来源入口。详细已有笔记用 file 节点引用,不复制成另一份长期正文。
- 多数卡片保持中性,用少量强调色表达角色并提供简短图例。正文同时写明角色,不只依赖颜色。
- 按所选构图安排主卡、普通卡与边注的尺寸。高度随正文增长,不为了整齐裁掉文字;分组留足内边距。
- 在局部阅读单元内建立对齐关系;主题之间允许留白、错层和不同密度。连线优先走相邻卡片的对应侧,避免无意重叠或穿过无关节点。
- 连线标签过长时缩短标签或增加卡片间距,避免文字被节点遮住。流程视角要连接到可观察结果,例如事件通知后实际触发的重新加载。
- 单图分组是视觉组织,不承诺原生折叠。多图文件引用是导航,不承诺原生交互式展开。
对于多 Canvas 或 Portal 请求,另读 references/nesting-and-updates.md。所有文件引用按 vault 根目录解析;独立交付包说明应放在哪个目录,不能把相邻文件路径误当 vault 相对路径。
更新已有地图
保持已有节点和边的 ID。新节点可用语义键的稳定哈希产生 16 位小写十六进制 ID,并检查碰撞。跨文件可复用语义键,但同一 Canvas 内节点与边 ID 不得冲突。
只改受影响内容和关系。保留人工位置、尺寸、颜色、批注及不认识的现存字段。仅换配色时,只修改明确范围内的节点和边的 color,保持 ID、正文、坐标、尺寸、端点与连线标签不变。“换主题”未说明范围时,默认只换配色;要求重新构图时才调整布局。不凭标题相似就合并节点。新节点放在相邻空位。整图重排只在用户要求或当前布局无法容纳时进行,并说明原因。
🔴 CHECKPOINT(覆盖前):确认可恢复副本已生成、更新范围已写清,再写入现有 Canvas。
来源删除或变更不能自动证明节点无用。先标注待复核,保留有人工注释的节点。只有明确属于本轮替换范围的生成内容才移除。修改前保留可恢复副本,写入前确认文件自读取后没有被外部修改。
验证并交付
先检查数据,再检查 Obsidian 中的真实阅读体验。
- 严格解析每个
.canvas。检查 ID 唯一、边端点存在、坐标有限、宽高为正及节点必要字段。 用 Python 3.9+ 运行随附的只读检查器(与仓库 scripts/ 的最低版本一致),路径相对当前 Skill:python3 scripts/check_canvas.py --vault <vault根目录> <vault相对路径.canvas>。它递归检查 file 节点与 wikilink 引用到的 Canvas,要求链接使用明确的 vault 相对路径;不解析普通 Markdown 链接或 Obsidian 的模糊短名,也不验证 Markdown 标题、块 ID 或外部 URL 内容。其他链接需另行核对。 - 从目标 vault 根解析 file 节点与导航链接,确认文件存在。检查子图嵌入关系无环;返回父图的普通链接不算嵌入环。
- 抽查关键关系是否有来源。确认推断没有被画成事实。
- 在 Obsidian 打开总览,缩放到全图,再放大一个核心节点。确认主线清楚、文字完整、节点无意外遮挡。多图模式实际进入一个子图并返回。只检查 JSON 不能声明视觉验收通过。
- 更新任务额外比较前后 ID 与布局,确认未涉及的节点和人工批注保持不变。
交付总览入口、模式、来源快照和实际完成的检查。无法访问 Obsidian 时说明只通过静态验证,并提供可打开的文件包。不要用另一个 HTML 渲染器的截图代替原生验收。
调用示例
- “用 canvas-atlas 把这个仓库画成一张架构总览,突出真实运行链。”
- “为这些笔记生成总览及两个必要子图,采用原生 Obsidian 导航。”
- “更新任务执行子图,保留我拖动的位置和手写批注。”
- “用杂志构图和纸本配色做一张图,主结论突出,旁边放来源与边注。”
- “总览用群岛构图,子图按流程展开;统一花园配色。”
- “只把现有图换成暮色配色,不动布局和批注。”
方法参考 oh-my-mermaid 的视角分析与递归展开。这里直接使用 JSON Canvas 和 Obsidian 文件链接,不要求先生成 .omm/ 或解析 Mermaid。