system-atlas

系统图谱

一份图谱是一份数据文件，可生成两种视图：一个交互式等距地图（单个独立的 HTML 文件），以及一个生成的文本对应版本（SYSTEM.md），其中包含决策表、每个结构、各项流程和按 ID 列出的未决问题。数据文件是唯一需要编辑的文件；两种视图都会根据它重新生成。它与手写的词汇表（CONTEXT.md）和 ADR 放在一起。

这种形式的理由是：架构讨论产生决策、问题和词汇的速度，比任何单份文档所能容纳的都快；与你讨论的人也想要看见系统，而不是阅读它。地图是给他们看的；文本对应版本是给仓库和下次的你看的；单一事实来源则确保两者内容一致。

这项技能源自一次漫长的设计讨论，以及几轮反馈中构建的真实 Agent 架构图谱。用户在那次讨论中的修正构成了以下规则；references/process-and-lessons.md 记录了整个过程。

何时使用——何时不使用

当系统还处于早期阶段，词汇、决策和问题仍在变化，并且还会有不止一轮反馈时，使用它。不要将它用于只需要 README 的成熟系统，也不要用于 PR 中的一张图。

流程

按顺序执行——每一步都是在第一轮中根据一次修正总结出来的。

1. 绘制前先阅读输入材料。 阅读愿景文档、仓库现有内容，以及用户允许参考的先例（先询问——用户可能会禁止查看某个分支或来源）。如果要基于某个框架构建，先阅读其文档；将较长的文档交给子 Agent，附上具体的设计问题，并让它返回一份入门指南，列出容易踩的坑以及“它无法提供什么”。不做这些就开始绘制，最终画出的方框将毫无实际依据。
2. 绘制前先讨论。 在聊天中提出结构方案，将其对应到运行时实际的原语，并且只询问无法从仓库推断出的问题。其余事项采用默认设置，并说明采用了哪些默认设置。以普通聊天文本提问。
3. 第一张全景图——整个系统。 将 assets/ 复制到全景图目录（将 template.html、build.mjs 和 data.example.mjs 分别重命名为 data.mjs），填入数据，构建并发布。全景图目录的位置取决于仓库的文档策略。 有些仓库可以自由提交设计文档——那么将其放在仓库内的 docs/<system>/atlas/ 就合适。另一些仓库则有意只提交 ADR 和 CONTEXT.md，规范和证据都放在问题跟踪系统中；这种情况下，将全景图、SYSTEM.md 和 research/ 放在 Git 忽略的临时目录中，并在发布规范时，将 SYSTEM.md 和研究资料作为评论附加到规范问题中；仓库内只保留 docs/<system>/adr/ 和 docs/<system>/CONTEXT.md。提交任何内容前，先询问适用哪种策略。吃过亏才学到：提交整套文档，结果产生了一个长达 3,900 行的文档 PR，还经历了四轮审查，来协调同一设计的三种重述——而只提交 ADR 和术语表，就有一个地方可以保持一致。如果你的 Agent 有用于 HTML 工件的设计指导技能，在动模板前先加载；无论如何，都要阅读 references/design-language.md 了解视觉规则。
4. 渐进式披露。 一次展示整个系统会显得杂乱（“很难读懂”是收到的第一条修正意见）。分成大约十个章节；每章最多新增三个结构，并运行一个只涉及已展示结构的小流程；最后一章展示所有内容，并提供流程选择器。尚未展示的结构仍保留在索引中，淡化显示，并标注其章节编号。面板采用摘要优先：先用一句话概括，然后折叠显示 阅读更多 和 步骤。
5. 形状和标签。 方框上的字母不够（“改进方框形状和标签”是收到的第二条修正意见）。为每种角色指定一种形状，并在画布上每个结构下方放置易读的名称标签——参见 design-language。
6. 文本对应版本。 CONTEXT.md 只是术语表，不包含其他内容（领域模型格式：名词，每个占一行）；ADR 只记录那些难以撤销、脱离上下文就令人意外、且确实经过权衡取舍的决策——这两项是存放在仓库内的内容。SYSTEM.md 由生成器生成，research/ 存放证据；两者都与全景图放在一起（根据第 3 步，存于临时目录或 docs/）。除非用户要求，否则不要创建问题。
7. 按问题 ID 记录反馈。 每个问题都使用 Q-<code><n>，并标注状态：未解决（字符串）、已解决 {q, r}（答案 + 日期）或已转交 {q, to}（交给一个具名的后续步骤，例如深入研究）。记录用户原话。如果用户说某项“不是问题”，就删除；如果用户说“我不明白”，先用具体示例解释，再标记为已解决。每轮之后：重新构建、重新发布、更新记忆。
8. 让深入研究的结果反馈回来。 让子 Agent 根据同一份简报开展研究（包含我们负责的接口、区分候选方案的要求、用于估算成本的使用模型，以及固定的交付物格式）。撰写综合结果，并附上经过标准化的成本/适配度对照表。将解决结果合并到数据中，格式为 {q, r: '… (from the deep dive, date)'}。如果用户否决某个提案，要全面检查并重写所有文件——只在顶部加一条说明，却让过时内容留在原处是不够的；用户会发现。
9. 保持内容最新。 “这张全景图对我很有用——但前提是它能保持更新。”只保留一个事实来源；每次更改后都重新构建并发布，绝不手动编辑生成文件，并在文档文件夹中保留一份 README.md，说明这套文档的内容（参见 process-and-lessons 中的表格）。

发布地图

atlas.html 是一个独立文件——无需构建步骤，除了 Google Fonts 样式表外，不依赖外部资源。选择对方实际能够打开的方式发布：

• 如果你的 Agent 可以发布托管的 HTML 制品，就在那里发布，并在每次重新构建后保持 URL 不变；将其填入 META.artifactUrl，这样生成的 SYSTEM.md 就会链接到它。
• 否则，使用任意静态服务器提供该文件夹（npx serve、python3 -m http.server），并提供本地 URL；或者提交该文件，让仓库的 Pages 托管服务提供它。

无论哪种方式，规则都一样：只有一个 URL，每次数据变更后都重新发布，绝不保留第二份副本。

完成后的标准

• <atlas home>/data.mjs 存在且是唯一编辑的源文件；运行 bun <atlas home>/build.mjs 可无错误地生成 SYSTEM.md 和 atlas.html。
• 地图已发布到稳定的 URL，并且每次数据变更后都会在该 URL 上重新发布。
• 每个结构都有 one、what、how、short 标签、角色 kind 和问题；幽灵结构已标记；章节已创建且每章都有流程；最后一章涵盖整个系统。
• SYSTEM.md 包含决策表、带 ID 和状态的问题索引，以及“如何维护此文件”页脚。
• 项目记忆记录地图 URL、文档路径、带日期的已锁定决策、用户拒绝的内容及原因，以及下一步。

发布前验证

对构建生成的脚本进行语法检查（new Function(js)），然后查看它：使用静态服务器提供该文件夹，并在真实浏览器中打开——在某些应用内浏览器中，file:// 会以静态快照形式渲染，且字体可能无法加载。将窗口大小调整为约 1280×800，并分别截取第一章、中间章节、最后一章、内部视图和浅色主题的屏幕截图。确保 <!doctype html> 位于首行，且 <meta charset="utf-8"> 紧随其后：缺少 doctype 时，页面会以怪异模式渲染；缺少靠前的字符集声明时，箭头会显示为乱码。点击一个结构，确认面板显示 已固定 并提供 进入内部 选项；再点击一个数据包圆点：此渲染器每次绘制都会重建整个场景，因此如果悬停处理程序中有多余的 render()，鼠标下方的元素就会被分离，浏览器也会停止合成点击事件——地图在屏幕截图中看起来依然完美，但点击毫无响应。每次做出决策后，都要在输出中搜索过时的词语（pending、旧模型名称、被拒绝的设计）——对方会逐字阅读所有内容。

此技能中的文件

• assets/template.html — 地图渲染器（标题和顶部条带统计数据在构建时注入）
• assets/build.mjs — 将 data.mjs 转换为 atlas.html + SYSTEM.md
• assets/data.example.mjs — 包含所有字段说明的最简起始模板；复制为 data.mjs
• references/design-language.md — 布局、配色、等距视图规范、按角色划分的形状、标签、文案规则、章节模板
• references/process-and-lessons.md — 首次会话的分步流程、README 表格、子 Agent 深入分析模式、成本模型习惯及经验教训