架构解释器 是做什么的？
每个解释器生成一个自包含的HTML文件：运行时、拓扑、文字、字体和样式全部内联，运行时无需网络调用。可以放在任何地方托管、离线打开、通过<iframe>嵌入页面，或附加到邮件中。
模型
一个拓扑，多种投影。 系统只需要一次性地完整建模。其他所有内容都是对该单一图的选择器——绝不会出现第二个图。
拓扑 节点 + 边 + 元数据 ← 你只需建模这个
──────────────────────────────────────
角色 解析策略 —— 词汇、折叠深度、展示哪些事实
视角 关注点叠加层 —— 哪些边存在，每个节点展示哪个事实
阶段 过去 / 现在 / 计划 —— 存在状态和样式
节拍 叙事 —— 镜头、焦点、文字、顺序
运行时强制两条规则，你不得打破：
- 颜色属于视角。 节点的种类用形状表示——圆角表示数据源、书脊表示存储、人物表示人工步骤、倒角表示网关。永远不要引入按种类配色的方案；否则会变成彩虹图并使视角切换失去意义。
- 没有导览讲解的图是不完整的。 零节拍时，构建检查会失败。这条规则确保这些图是自解释的，而不是只有漂亮的外表。
工作流程——按顺序执行
1. 采访。不要臆想系统。
最大的失败模式是生成一个看起来合理但用户从未描述过的架构。在写任何东西之前先提问。如果工具支持，使用其结构化提问功能。
覆盖以下内容：
- 层级。 顶级阶段或分组有哪些（5-8个）？这些将成为L1方框。
- 每层的组件。 只展示值得展示的内容。“PostgreSQL”是一个方框；它的表则不是。
- 生命周期。 完整走一遍一个典型的请求或任务的端到端流程。这会生成边。
- 读者是谁。 通常是高管/架构师/工程师，但需要询问——可能是“客户/我们团队”或“学生/实践者”。
- 哪些关注点重要。 数据流加上2-4个：成本、延迟、信任与治理、故障模式、所有权、安全。每个视角需要自己的一组边或事实。
- 是否有历史。 v0→今天→计划是客户工作和路线图中最有价值的轴线。如果系统没有有意义的历史，可以跳过。
- 核心论据。 读者阅读后应该相信什么？这将形成节拍。如果用户没有核心论据，解释器就没有灵魂——迫使对方思考。
2. 选择主维度
深度很少是最有趣的维度。询问这个图是为了什么：
| 目的 | 主维度 |
|---|---|
| 教学工作原理 | 时间 —— 节拍逐步引导一个请求 |
| 客户/利益相关者演示 | 阶段 —— 存在什么、提议什么 |
| 设计评审、风险评估 | 视角 —— 故障模式、信任边界 |
| 入职培训、参考资料 | 深度 —— 层级再到组件 |
3. 编写规范
在编写之前完整阅读references/spec-format.md。 它包含节点/边/节拍的完整参考和所有可选字段。
复制assets/runtime/specs/llm-eval.js作为工作示例——它使用了所有特性，是一个很好的模仿模板。将新规范写入specs/<name>.js，然后将src/spec.js指向它（只需一行——入口点和构建检查都通过它读取）。
4. 构建
首先将assets/runtime复制到一个工作目录并在其中构建。不要在已安装的技能文件夹内运行npm install——它通常是共享或符号链接的安装位置。
cp -R <skill-dir>/assets/runtime ./解释器
cd 解释器
npm install # 需要网络；约20秒
npm run build # 先检查规范，然后生成 dist/index.html
构建检查输出会告诉你投影数量。如果失败，修复规范——永远不要削弱检查器。 它强制执行的每一条规则都是因为之前某个实际交付的图因缺少该规则而效果更差。关于每条规则的含义，参见references/spec-format.md。
5. 视觉验证——必做，两种尺寸
这是最常被跳过、也是最关键的步骤。布局计算非常复杂，失败通常是静默的：标签被裁剪、边穿过五个方框、镜头框住空白区域。不检查就绝不能宣布完成。
node scripts/shots.mjs # 桌面矩阵 → shots/
然后以手机尺寸（390×844）自行截图并检查图片。检查：
- 每个角色 × 阶段组合渲染时无重叠或裁剪。
- 每个视角实际改变了画面——如果两个视角看起来一样，说明它们的边集配置错误。
- 节拍框定。 逐个浏览节拍；每个节拍应该框定其焦点并保持上下文可见，而不是空白区域也不是整个系统。
- 标签。 没有任何标签被裁剪或覆盖在方框之上。
- 手机。 自适应为单列，100%缩放可读，控件不溢出。
- 控制台。 零错误，包括在沙箱化的iframe中。
如果有什么看起来不对，在更改布局代码之前先阅读references/troubleshooting.md。
6. 交付
将构建好的dist/index.html交给用户。告诉用户该文件是自包含的，可以托管、嵌入或离线打开。
仅限Claude Code / Claude应用。 使用
SendUserFile发送文件。如果用户会反复查看（大多数解释器都是），也使用create_artifact持久化。
不可协商规则
- 每个节点都有
why——一句话说明该方框存在的原因，而不是它是什么。 - 高管能看到的内容，需用高管词汇并提供
detail。 - 至少6个节拍，每个都有实质性文字。过于单薄的节拍只会产生幻灯片效果，而不是论证。
- ≤34个叶子节点。超出则拆分为多个解释器，而不是硬塞。
- 每次构建一个主题。读者可以获得亮/暗切换，仅此而已。
定制
- 不同视觉方向 ——
src/themes.js包含五个主题（house,swiss,editorial,draft,shadcn）。修改src/App.jsx中的THEME_ID。如果添加字体，必须正确设置metrics.charFactor否则每个标签都会裁剪；参见references/troubleshooting.md。 - 更多角色/视角/阶段 —— 纯规范数据，无需代码更改。
- 从源码生成 —— 编写一个脚本遍历代码仓库并生成
DIAGRAM树是一种合理的扩展，但why、detail和节拍仍然需要来自人类。
适用范围
此技能用于构建解释性图表，而不是实时仪表盘、自由绘图工具或基础设施清单。如果用户想要一个可以随时拖拽编辑的图表，他们应该使用drawio。如果他们想在一个页面上展示一个数字，他们应该使用图表。