# Canvas Atlas

> Obsidian Canvas 知识地图：将代码仓库、笔记集合或研究材料整理成可追溯、可逐层阅读的 .canvas。用于架构总览、系统理解、主题地图、多 Canvas 导航（architecture map, knowledge map, repo-to-canvas, multi-canvas navigation），支持单图、嵌套图、可选构图与配色及保留人工布局的更新；不用于纯 Mermaid/HTML 图，也不用于没有 Obsidian vault 的一次性示意图。

- Skill: `oldwinter/canvas-atlas` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx get-skill add oldwinter/canvas-atlas`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oldwinter/canvas-atlas/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: oldwinter (https://skillmd.com/u/oldwinter)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/oldwinter/canvas-atlas

---


# Canvas atlas

让读者先理解整体，再进入细节。输出可以直接在 Obsidian 打开的 `.canvas`，而不是 Mermaid 截图。

## 确定范围

从请求和当前环境确定来源、读者的问题、输出位置及模式。只在缺失信息会改变范围时询问。遵守目标 vault 的就近规则。未指定 vault 时先查当前项目配置或 Obsidian CLI；无法确定则交付独立文件包，不猜路径。

- `single`：一个 Canvas，用分组区分层次。用户要求单文件时，解释写入文本卡片，不强制生成伴随笔记。
- `nested`：一个总览加必要的子 Canvas。默认使用原生文件引用和链接导航。
- `auto`：默认。先设计一张总览；只有某个部分需要独立解释时才拆图。
- 更新已有地图：读取整份现有 Canvas 和链接目标，按下方更新协议操作。

这些是意图选项，不是已经安装的 CLI 参数。不为本任务安装插件、启动云服务或发布内容。

## 阅读并提炼

1. 写出读者看完地图应能回答的一个主问题。仓库可从入口、核心模块和一次真实执行链取证；笔记集合可从主张、依据、分歧和应用取证。不要把文件目录直接当架构。
2. 选择有依据的视角。总览说明系统边界与模块职责；流程说明触发、处理、状态和输出；决策说明约束、取舍和未决问题。仅创建对当前材料有用的视角。
3. 在工作草稿中记录每个元素的稳定语义键、职责、来源位置和已证实关系。仓库来源优先采用固定 commit 的文件链接；vault 内来源使用真实存在的笔记路径及标题或块引用。没有仓库远端时显示相对源码位置，不把 vault 外文件伪装成可嵌入笔记。
4. 区分事实、推断和建议。推断及建议在卡片正文中明示。不要凭模块名称推断调用关系；不能确认的关系留在“待核实”说明中。

## 设计阅读路径

先为总览写一句能够独立成立的解释，再安排节点。

- 总览通常保留 5–9 个核心元素。数量是阅读预算，不是硬阈值；按内容调整。每张图只回答一个主要问题。
- 一个元素值得展开，需有独立子职责、内部流程或关键取舍。不要为每个文件生成子图。
- 子图默认不超过两层；更深层次需有明确阅读收益。子图提供返回父图的文字链接。
- 连线用动词或短语说明关系，例如“调用”“写入”“发布事件”“约束”。导航入口明确写“进入子图”，不混作业务调用。
- 总览中的子图入口仍需说明职责、输入与输出。读者不打开子图，也能看懂整体。
- 把限制和关键决策放在读者会看到的位置。不要为了显得完整，给每个节点机械填满七种文档字段。

## 生成可读的 Canvas

创建前读取 [references/canvas-contract.md](references/canvas-contract.md)。需要完整格式说明时，使用环境已有的 `json-canvas` Skill；本 Skill 的最小契约足够生成基础图，不要求该 Skill 必须安装。

创建新图或调整风格前读取 [references/visual-styles.md](references/visual-styles.md)。分别选择构图 `style` 和配色 `palette`；未指定时按材料选择，并在交付时说明。它们是自然语言意图，不是 CLI 参数或 Canvas 字段。避免让每次输出都变成等宽网格，也不要用随机错位制造变化。

- 核心卡片写短标题、1–3 句解释及来源入口。详细已有笔记用 file 节点引用，不复制成另一份长期正文。
- 多数卡片保持中性，用少量强调色表达角色并提供简短图例。正文同时写明角色，不只依赖颜色。
- 按所选构图安排主卡、普通卡与边注的尺寸。高度随正文增长，不为了整齐裁掉文字；分组留足内边距。
- 在局部阅读单元内建立对齐关系；主题之间允许留白、错层和不同密度。连线优先走相邻卡片的对应侧，避免无意重叠或穿过无关节点。
- 连线标签过长时缩短标签或增加卡片间距，避免文字被节点遮住。流程视角要连接到可观察结果，例如事件通知后实际触发的重新加载。
- 单图分组是视觉组织，不承诺原生折叠。多图文件引用是导航，不承诺原生交互式展开。

对于多 Canvas 或 Portal 请求，另读 [references/nesting-and-updates.md](references/nesting-and-updates.md)。所有文件引用按 vault 根目录解析；独立交付包说明应放在哪个目录，不能把相邻文件路径误当 vault 相对路径。

## 更新已有地图

保持已有节点和边的 ID。新节点可用语义键的稳定哈希产生 16 位小写十六进制 ID，并检查碰撞。跨文件可复用语义键，但同一 Canvas 内节点与边 ID 不得冲突。

只改受影响内容和关系。保留人工位置、尺寸、颜色、批注及不认识的现存字段。仅换配色时，只修改明确范围内的节点和边的 `color`，保持 ID、正文、坐标、尺寸、端点与连线标签不变。“换主题”未说明范围时，默认只换配色；要求重新构图时才调整布局。不凭标题相似就合并节点。新节点放在相邻空位。整图重排只在用户要求或当前布局无法容纳时进行，并说明原因。

🔴 CHECKPOINT（覆盖前）：确认可恢复副本已生成、更新范围已写清，再写入现有 Canvas。

来源删除或变更不能自动证明节点无用。先标注待复核，保留有人工注释的节点。只有明确属于本轮替换范围的生成内容才移除。修改前保留可恢复副本，写入前确认文件自读取后没有被外部修改。

## 验证并交付

先检查数据，再检查 Obsidian 中的真实阅读体验。

1. 严格解析每个 `.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 内容。其他链接需另行核对。
2. 从目标 vault 根解析 file 节点与导航链接，确认文件存在。检查子图嵌入关系无环；返回父图的普通链接不算嵌入环。
3. 抽查关键关系是否有来源。确认推断没有被画成事实。
4. 在 Obsidian 打开总览，缩放到全图，再放大一个核心节点。确认主线清楚、文字完整、节点无意外遮挡。多图模式实际进入一个子图并返回。只检查 JSON 不能声明视觉验收通过。
5. 更新任务额外比较前后 ID 与布局，确认未涉及的节点和人工批注保持不变。

交付总览入口、模式、来源快照和实际完成的检查。无法访问 Obsidian 时说明只通过静态验证，并提供可打开的文件包。不要用另一个 HTML 渲染器的截图代替原生验收。

## 调用示例

- “用 canvas-atlas 把这个仓库画成一张架构总览，突出真实运行链。”
- “为这些笔记生成总览及两个必要子图，采用原生 Obsidian 导航。”
- “更新任务执行子图，保留我拖动的位置和手写批注。”
- “用杂志构图和纸本配色做一张图，主结论突出，旁边放来源与边注。”
- “总览用群岛构图，子图按流程展开；统一花园配色。”
- “只把现有图换成暮色配色，不动布局和批注。”

方法参考 [oh-my-mermaid](https://github.com/oh-my-mermaid/oh-my-mermaid) 的视角分析与递归展开。这里直接使用 JSON Canvas 和 Obsidian 文件链接，不要求先生成 `.omm/` 或解析 Mermaid。

