地铁图架构图

---
name: transit-atlas
description: 把对一个系统的描述（架构、数据流、工作流或生命周期）变成一个离线、可交互的单文件系统地图，画成城市地铁图的样子。可以搜索、缩放、平移，点击站点会聚焦并打开列出全部关系的侧边档案，还能按类型筛选。交付时把已提供的事实、推断和未知分开，未知项始终标在地图上。当有人想要一张能探索的架构图、系统图、数据流图、流程图，或点名要地铁图风格时使用。
version: 1.0.0
---

# 地铁图架构图

你只写一个数据对象。样式和布局都由它计算得出，所以任何系统画出来都是同一种样子。你不设置任何位置或颜色，也不改模板。

数据格式和各项上限见 `references/schema.md`，样式数值和规则见 `references/style.md`。

## 需要问的信息

一次问完，放在同一条消息里，简报已经说清楚的就别再问。

必须有：
1. 这个系统是什么，用对方自己的描述。贴笔记、文档或代码都可以。
其他都不是必须的。

可选：
2. 谁会看这张图。它决定选哪些路径作为线路、线路怎么命名。数据里没有对应的字段；没人说明时不要猜，照常往下做。
3. 最重要的几条路径，它们会变成线路。
4. 语言：英文或中文，默认跟简报一致。
5. 画的是真实系统，还是虚构示例。

## 步骤

1. **把每句话归类。** 对方明确说过的记为 `fact`；你据此想出来的记为 `inferred`，并在 `basis` 里写明理由；缺失的记为 `unknown`，`basis` 写成要去问的问题。
2. **选线路。** 从系统里选出最多八条路径。每条必须是一段不分叉的路线；分叉就另开一条线，共用分叉的那一站。允许绕回起点形成环线。
3. **写数据。** 把 `assets/starter.system.json` 复制成工作文件再填写。读取和依赖关系通常不要放在线路上，也就是不写 `line`。
4. **生成。** `node /绝对路径/transit-atlas/scripts/build.mjs /工作目录/system.json /工作目录/map.html`，不到一秒。请用绝对路径，因为工作文件通常不在技能文件夹里。最后一个参数就是输出路径，名字随意：要 `index.html` 就传 `/工作目录/index.html`。
5. **检查。** `node /绝对路径/transit-atlas/scripts/check.mjs /工作目录/map.html`。修改数据并重新生成，直到通过。如果在一二八零乘八百的屏幕上显示全图时标签小于十一像素，标签挨得太近、读起来像同一句说明，或者标签盖住了轨道，检查都会失败。上限六十站时约需两秒。
6. **实际操作并亲眼看。** `node /绝对路径/transit-atlas/scripts/drive.mjs /工作目录/map.html /工作目录/shots`，十五到四十秒。它会在动效开启和减弱两种状态下，以一二八零和一四四零两种宽度以及手机尺寸，测试搜索、缩放、平移、聚焦、档案、筛选和交接清单。它写出的每一张截图都要打开看。如果线路缠在一起，就换一批路径作为线路，或把某条线路改成直接联系，然后重新生成。
7. **写交接说明。** `node /绝对路径/transit-atlas/scripts/handoff.mjs /工作目录/map.html` 会从文件本身打印出三份清单，随地图一起发出。

## 如何记录你知道的内容

- **关系算事实还是推断。** 简报明确说这两者按这个方向相连，才算 `fact`。相邻两步只有在简报明确说了这个先后时才算事实，比如写了“然后”“之后”，或者作为一个流程按序给出。只是并列或前后提到的不算：如果简报列了药房、再列提醒，却没说前者引出后者，这条关系就是 `inferred`。简报没说的机制（谁读取、写入、触发了什么）都是 `inferred`，哪怕看起来理所当然。
- **递送用哪种关系。** 把消息、提醒或物品送到某人那里，用 `sends`。只有东西确实退回去时才用 `returns`。
- **人还是步骤。** 简报说的是“谁”，就用 `actor`：一个人、一个岗位或一个团队。简报说的是“做什么”，就用 `process`，如果简报说了由谁做，再写 `owner`。所有站点都用这同一个标准，相似的东西才会长得一样。“护士做分诊”是一个叫分诊的 `process`，负责方是护士；除非还要表现别人把工作交给护士，护士才另成 `actor`。
- **复合问题。** 如果有人可能答得上一部分、答不上另一部分，或者要由不同的人回答，就拆开，每部分用各自的 `basis`。“病历怎样保存、谁能删除”，如果档案管理员和医生要分别回答，就是两个问题；只有一个答案能同时解决两部分时，才算一个。
- **一个未解决的问题。** 计数按问题算，不按条目算。优先只用一个未知站点。如果某些轨道只因它而存在，就把它们标为 `unknown`，并使用一字不差的 `basis`：它们只算一次，交接清单也只列一次。措辞不同就算不同的问题。
- **简报单薄时的 `note`。** 交接清单会把 `note` 印在“简报里明确说过”之下，所以它只能写简报说过的话。如果简报只提到站点的名字，就不要写 `note`。你自己的解释写在 `inferred` 条目的 `basis` 里，绝不写进 `note`。
- **线路的 `role`。** 可选。它显示在交接清单的“线路”部分和 `handoff.mjs` 的输出里，与事实分开，所以可以写你自己的简短说明。
- **实体场所。** 按它的作用选类型：东西在那里等人来取，用 `queue`；东西存放在那里，用 `store`；人在那里完成一个步骤，用 `process`。如果一个步骤的性质本身就是疑问，用 `process` 并标为 `unknown`。
- **点按筛选会发生什么。** 在图例里，点线路只看这一条，点站点类型隐藏这一类，点确定程度则高亮这一级。类型被隐藏时，未知站点仍留在地图上并保留名字；轨道上的标记牌随轨道一起隐藏。“全部显示”恢复一切。点击站点时，地图会把它和所有相连的站点一起框在屏幕里。如果读者会用筛选，请告诉他们。

第六步需要 `playwright`，安装方法：`npm install playwright`，然后 `npx playwright install chromium`。如果它装在别处，把 `NODE_PATH` 指向它的 `node_modules` 文件夹。

## 交付物

- `map.html`：单个文件，不发出任何外部请求，从磁盘直接打开。
- 一段交接说明，分成三部分：已提供的事实、待确认的推断、仍未解决的未知。

## 遇到不理想的情况

- **简报太单薄。** 在图上复述对方给的事实，什么都不要编。凡是你自己想出来的都标为 `inferred`，并在交接说明里列出来。一张小而诚实的图，胜过一张满满当当却靠编造的图。
- **没人答得上来。** 照常往下做。保留 `unknown` 和它的问题，把你的假设标为 `inferred`，并在交接说明里写明。绝不能为了图好看，把未知改成事实。
- **对方想要更详细或更简略。** 长链会自动折叠，所以常见的十到二十站地图一打开就看得清。链上每一站仍占一列，每多一条线可能多占一行，所以如果检查提示标签过小，就拆成一张总图和几张分区图。要更简略，就合并步骤、减少线路。硬上限是六十站、八条线、一百二十条关系。
- **没有真实链接。** 这张图不放链接，也不需要。如果提到了某份文档或负责人却没有名字，就记成未知；绝不编造网址、姓名、数字或客户。
- **虚构内容。** 把 `meta.fictional` 设为 `true`，标题牌上就会写明。
- **语言。** 全部内容用同一种语言。中文图里必须保留外文的产品名，放进 `meta.keepLatin`。
- **检查提示标签重叠或读起来像同一句说明。** 缩短它点名的那些标签，或换一批路径作为线路。位置是不能手动设置的。
- **往回走的联系。** 如果确实是直接联系，就保留。布局会让它走开阔的通道；看过截图后如果还是显得缠绕，想想它是否应该单独成线。

## 交付前检查

- [ ] 最终文件通过 `check.mjs`。
- [ ] 动效开启和减弱时都通过 `drive.mjs`。
- [ ] 每张截图都看过，电脑和手机都看了，地图读得清楚。
- [ ] 每条事实和每条 `note` 都能追到对方提供的内容。
- [ ] 每条推断都有理由，每个未知都有问题。
- [ ] 未知项在图上看得见，手机打开时屏幕上就有一个标记，每个未解决的问题在交接说明里只列一次。
- [ ] 没有编造的姓名、数字、客户或链接。
- [ ] 全部文字是同一种语言，虚构的图已标明。
- [ ] 交接说明把事实、推断和未知分开了。

## 什么时候不要用

- 要表现服务之间准确的先后和时序：时序图更合适。
- 要表现精确的数据库结构，或超过六十站又无法拆分的系统。
- 读者只看纸质版：这张图的价值在于交互。
- 系统其实只是一串直线步骤：一份清单就够了。

## 运行要求

- 版本不低于十八的 `node`，用于生成和检查脚本，这两个脚本没有其他依赖。
- `playwright` 和它的浏览器，只有 `scripts/drive.mjs` 需要。
- 成品能在任何当前版本的浏览器里运行，不需要服务器，也不需要网络。