{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

System Atlas

把可探索的等距架构地图构建为 HTML。

Skill 元数据

参考：完整 SKILL.md

System Atlas Skill

一个 atlas 就是一个数据文件（data.mjs），渲染两个视图：一张交互式等距地图（单个自包含 atlas.html——悬停读、点击钉住、进去看步骤、可检视的移动数据包、每次只揭示几个结构的章节），和一个生成的文本孪生（SYSTEM.md），含决策表、每个结构、各流，以及按 ID 排列的开放问题。数据文件是唯一需要人编辑的东西；两个视图都从它重建。它放在手写词汇表（CONTEXT.md）和 ADR 旁边。

做什么： 带渐进揭示的交互式架构图、跨反馈轮次的问题跟踪、生成的文本孪生、可重复的更新循环。 不做什么： 静态一次性图（用 architecture-diagram 或 excalidraw skill）、只需 README 的成品系统、或 PR 用的单张图。

何时使用

当有人想可视化地讨论、设计、审查或解释一个架构时——"make an atlas"、"map the system"、"make the architecture explorable"、"visualize the codebase/agent/pipeline so we can talk about it"、"a diagram I can click around"、"walk me through how it fits together"——或当一场架构讨论正在产出一堆需要跨反馈轮次跟踪的开放问题时，都用。决策变化后更新已有 atlas 也用。最适合系统还足够新、词汇/决策/问题仍在变动、且会有不止一轮反馈的时候。

前置条件

• Node.js（任一近期版本；构建只用 node:fs、node:path、node:url——无需 npm install）。
• 一个静态服务器用于验证（npx serve 或 python3 -m http.server）。

如何运行

mkdir -p <atlas home>/atlas
cp <skill>/assets/{template.html,build.mjs} <atlas home>/atlas/
cp <skill>/assets/data.example.mjs <atlas home>/atlas/data.mjs   # then fill it in
node <atlas home>/atlas/build.mjs   # writes ../SYSTEM.md and ../atlas.html

数据文件每个字段都在 assets/data.example.mjs 中有文档。

速查

流程

按顺序走——每一步都是第一轮踩坑换来的。

1. 画图前先读输入。 愿景文档、repo 现有表面、用户允许的任何先例（问——他们可能禁某个分支或来源）。若要基于框架构建，先读其文档；把长文档经 delegate_task 交给子代理，带上你具体的设计问题，让它返回一份入门材料，含坑和"它不给我们什么"清单。在此之前画图会产出对不上任何真实东西的框。
2. 画图前先讨论。 在对话里提出结构，映射到运行时真实原语，只问你无法从 repo 推导出的问题。其余取默认值并说明取了哪些。
3. 第一个 atlas——整个系统。 把 assets/ 复制到 atlas home（把 data.example.mjs 改名为 data.mjs），填数据，用 node 构建，发布。atlas home 在哪取决于 repo 的文档策略——提交任何东西前先问。文档友好的 repo：树内 docs/<system>/atlas/。只提交 ADR 和 CONTEXT.md 的 repo：把 atlas、SYSTEM.md、research/ 放 git 忽略的 scratch 目录，发布时把 SYSTEM.md + research 附到 spec issue。（曾因一次性提交整套，产出 3900 行 docs PR 和四轮审查，调和同一设计的三种重述。）若有用得上的 HTML 产物指引，经 skill_view 加载 design-md 或 architecture-diagram skill；无论如何读 references/design-language.md 了解视觉规则。
4. 渐进揭示。 一次给整个系统读起来是噪音。约十章；每章最多加三个结构，跑一个只触及已揭示结构的小流；最后一章用流选择器展示全部。未揭示结构留在索引里、变暗、带章节号。面板摘要优先：一句，然后 Read more 和 Steps 折叠。
5. 形状和标签。 框上的字母不够。给每个角色一个形状，在画布上每个结构下方放可读名字标签——见 design-language。
6. 文本孪生。 CONTEXT.md 只是词汇表（名词，各一行）；ADR 只用于难逆转、无上下文会意外、且是真实权衡结果的决策——这两个是树内部分。SYSTEM.md 是生成的，research/ 放证据；两者随 atlas 放（按第 3 步，scratch 目录或 docs/）。除非被要求不要开 issue。
7. 按问题 ID 反馈。 每个问题是 Q-<code><n>，带状态：open（一个字符串）、resolved {q, r}（答案 + 日期）、或 routed {q, to}（交给命名的下一步）。记录用户原话。若他们说某样东西"不是问题"，丢掉；若说"我没懂这个"，在 resolved 之前用具体例子解释。每轮后：重建、重新发布、更新记忆。
8. 深挖反哺。 用子代理（delegate_task）针对一份共享 brief 做研究（我们拥有的接口、区分候选的需求、成本使用模型、固定交付形状）。写一份综合，带归一化的成本/契合度表。把决议折进数据作 {q, r: '… (from the deep dive, date)'}。若用户拒绝提案，扫荡每个文件重写——在过期章节顶挂个横幅不够。
9. 保持最新。 单一来源，每次变更后重建并重新发布，绝不手编生成文件，并在 docs 文件夹留 README.md 解释这套东西（表见 references/process-and-lessons.md）。

发布

atlas.html 是单个自包含文件——无构建步骤，除一个 Google Fonts 样式表外无外部资产。用任一静态服务器（npx serve、python3 -m http.server）服务该文件夹并交出 URL，或让 repo 的 pages 托管服务提交的文件。一个 URL，每次数据变更后重新发布，绝无第二份拷贝。若你保留稳定发布 URL，把它放进 META.artifactUrl，让 SYSTEM.md 链接到它。

常见坑

• 保持 <!doctype html> 在最前，<meta charset="utf-8"> 紧随其后——否则怪异模式和乱码箭头。
• 渲染器每次绘制重建整个场景：悬停处理器里一个多余的 render() 会把光标下的元素拆下来，浏览器停止合成点击——截图里地图看着完美，但什么都不响应。
• 某些应用内浏览器把 file:// 渲染成静态快照；经静态服务器验证，而非从磁盘。
• 绝不删问题——resolved 或标 dropped，让 ID 稳定。
• 每次决策后 grep 输出里的过期词（pending、旧模型名、被拒设计）——人会读全部。
• 用 shell heredoc 写大 HTML/JS 很脆；用 write_file，保持数据块 JSON 可序列化。

验证

• node <atlas home>/atlas/build.mjs 退出 0，并写出 SYSTEM.md 和 atlas.html。
• 对构建出的脚本做语法检查（new Function(js)），然后在真实浏览器约 1280×800 打开服务页面；检查第一章、中间一章、最后一章、一个内部视图和浅色主题。
• 点一个结构，确认面板说 pinned 并提供 Go inside；点一个数据包圆点，确认 payload 打开。
• 每个结构有 one、what、how、short 标签、角色 kind 和它的问题；ghosts 有标记；章节存在且各章有流；最后一章是整个系统。
• SYSTEM.md 带决策表、带 ID 和状态的问题索引，以及"本文件如何维护"页脚。
• 项目记忆记录 atlas URL、docs 路径、带日期的锁定决策、用户拒绝了什么及原因、下一步。