@olierjs/fugue-cli 0.1.2 → 0.1.3

package/README.md

@@ -52,6 +52,8 @@ $fugue-show-me 检查取消与重试交错时的状态变化，画出可能的
 
 需要可视化解释时，总览路由到 [fugue-show-me](skills/fugue-show-me/SKILL.md)：由 `show-me` 选择通用表达形式，需要分析状态变化、检查行为规则或展示缺陷路径时配合 `statechart`。适配维护在独立目录中；更新上游时整体替换原版目录并更新来源记录。
 
+`fugue-show-me` 根据这些方法组织全局视图和必要的交互、状态细节，再通过本层的 [Pele 输出脚本](skills/fugue-show-me/scripts/render-html.mjs) 将 Mermaid 统一展示为单文件 HTML。图在正文直接可见，采用 Flexoki 浅色与深色主题，按信息角色分色，支持自适应和缩放。首次生成页面会将 `pele@1.12.0` 安装到独立用户缓存，生成的页面可离线打开；该展示链路不导入或修改上游的内部渲染模块。
+
 ## 状态图依赖
 
 `statechart` 使用 Node.js 和 npm；模型检查还需要 [mise](https://mise.jdx.dev/getting-started.html)。macOS 可先安装：
@@ -75,7 +77,7 @@ node ~/.agents/skills/statechart/scripts/statechart.mjs --help
 
 ```sh
 npm pack
-npm install -g ./olierjs-fugue-cli-0.1.2.tgz
+npm install -g ./olierjs-fugue-cli-0.1.3.tgz
 fugue-cli --version
 fugue-cli guide
 ```
@@ -94,7 +96,7 @@ npm pack
 `npm pack` 的 `prepack` 自动构建各平台二进制，并将版本写入命令。发布目标固定为 npmjs，包名为 `@olierjs/fugue-cli`。发布验收后的包：
 
 ```sh
-npm publish ./olierjs-fugue-cli-0.1.2.tgz --access public
+npm publish ./olierjs-fugue-cli-0.1.3.tgz --access public
 ```
 
 Go 命令入口位于 [cmd/fugue-cli](cmd/fugue-cli/main.go)，指南源码位于 [guide.md](internal/cli/guide.md)，入口技能位于 [SKILL.md](skills/fugue-stack/SKILL.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olierjs/fugue-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Fugue 需求交付工作指南与 Agent 技能",
   "type": "module",
   "bin": { "fugue-cli": "bin/fugue-cli.mjs" },

package/skills/fugue-show-me/SKILL.md

@@ -1,16 +1,44 @@
 ---
 name: fugue-show-me
-description: 使用 show-me 和 statechart 可视化解释当前实现、代码变更、运行结果或状态变化；当用户需要图解、结构示意或缺陷路径时使用。
+description: 组合 show-me 与 statechart 的分析视角，用 Pele 将 Mermaid 展示为可读的 HTML 图解；解释实现、代码变更、运行结果、状态变化或缺陷路径时使用。
 ---
 
 # 可视化解释
 
-先阅读并遵循[上游 show-me](../show-me/SKILL.md)，由它指导表达形式的选择。
+上游 skill 保持独立。本层负责按问题选择分析方法、组织面向人的视图，再用 Pele 统一展示；不修改上游，也不调用它们的内部渲染模块。
 
-需要分析状态转换、并发、重试、取消、恢复或缺陷路径，并检查行为规则、对比修复时，阅读并遵循[上游 statechart](../statechart/SKILL.md)的建模、模型检查、出图与交付要求。用 `show-me` 解释整体结构，用 `statechart` 展示状态变化和缺陷路径，按当前问题需要组合。
+## 获取信息与组织视图
 
-原版脚本安装的 TLC 使用 ASCII 模型标识符和字符串值，中文状态与步骤标签写在映射文件中，再从模型生成中文图示。
+先阅读并遵循[上游 show-me](../show-me/SKILL.md)，由它指导表达形式的选择。技能提供分析方法，事实来自当前源码、差异、文档和实际运行结果。
 
-说明使用用户的语言，依据当前源码、差异或已有材料，只展示本次问题需要的内容。
+| 问题需要的视角 | 方法与信息 | 适合的图 |
+| --- | --- | --- |
+| 系统全貌、职责边界、数据流 | 按 `show-me` 从材料中提取组件、输入输出与关系 | 流程图、分组结构图 |
+| 谁先做什么、谁调用谁 | 按 `show-me` 跟随真实调用或事件顺序 | 时序图 |
+| 状态、并发、重试、取消、恢复、缺陷路径 | 阅读并遵循[上游 statechart](../statechart/SKILL.md)，获取模型状态、转换、规则、检查结果和复现证据 | 上游生成的状态图与缺陷路径图 |
+
+按问题选用必要的方法；普通结构解释不强制建模。任务中其他已选技能的输出也可作为材料，使用前核对其依据和适用范围。
+
+模型负责组织信息：统一不同材料的对象名称、版本和粒度；区分已确认行为、模型假设与待确认关系。涉及多个组件或分支时先给出边界和主路径的总览，再按问题展开关键交互或状态细节。一张图回答一个问题，避免把全部实现细节堆进总览；说明使用用户的语言，标签优先写读者关心的行为。
+
+图中按职责或状态区分颜色，沿用 [Pele 展示说明](references/pele.md)中的颜色角色；由模型明确标注输入、处理、判断、外部交互、完成、失败和跳过，保留对应文字标签。不要按节点顺序轮流染色，也不让脚本从节点名称猜业务含义。浅色和深色使用同一套颜色含义，原模型的规则结果和缺陷路径标记优先。
+
+使用 `statechart` 时保留上游的建模、模型检查、复现及交付要求。原版 TLC 使用 ASCII 模型标识符和字符串值，中文状态与步骤标签写在映射文件中。将它生成的 `.mmd` 直接交给展示层，保留状态、边、步骤编号和缺陷标记；另画的简洁总览不能替代经检查的模型图，Pele 的渲染成功也不证明行为正确。
+
+## 用 Pele 交付图示
+
+选择 Mermaid 表达并需要 HTML 时，用本层的 [Pele 输出脚本](scripts/render-html.mjs) 渲染。输入可以同时包含模型编写的总览、时序图和 `statechart` 生成的状态图，顺序就是页面阅读顺序。用易懂的文件名作为各图标题。
+
+```bash
+node <本 skill 目录>/scripts/render-html.mjs --title "发布流程说明" --out /绝对路径/说明.html /绝对路径/全局视图.mmd /绝对路径/状态流转.mmd
+```
+
+脚本通过 Pele 的公开 API 生成内嵌 SVG，并将 Pele 的浏览器包一并嵌入 HTML，用它提供自适应、中文字体测量和缩放。采用官方站点的 Flexoki 浅色与深色配色，页面内可切换，`--theme light|dark` 指定初始主题。首次安装固定版本依赖，后续复用本层的独立缓存；页面打开时无需联网或启动服务。集成到已有 HTML、调整主题或定位兼容问题时，阅读 [Pele 展示说明](references/pele.md)。
+
+核心图放在对应说明旁、默认可见，简短说明补充结论、范围与必要证据。源码和模型检查材料可放附录，下载入口仅作补充。在支持 Mermaid 的对话或文档中可直接使用会渲染的 `mermaid` 代码块；表达形式更适合树、伪代码或表格时，继续遵循 `show-me`，无需强制转成图。
+
+## 交付检查
+
+打开最终交付的 HTML 或图片，检查实际图示；不能用“文件已生成”、HTML 源码或下载链接存在代替检查。HTML 检查桌面和窄屏，确认核心图已显示、中文标签及连线可读、大图可查看完整内容；本地静态页面还需确认离线可显示。渲染失败就修复后重新检查，不把下载源码当成完成。无法预览时明确说明未验证的范围。
 
 将上游的 `Bash(open ...)` 对应为当前宿主可用的终端或文件预览工具，按实际操作系统打开 HTML 或图片。交付本地文件时提供绝对路径链接；仅在实际打开成功后说明已打开。

package/skills/fugue-show-me/assets/diagram.css

@@ -0,0 +1,77 @@
+/* Flexoki light/dark palettes from https://pele.run/theming and the official site. */
+:root {
+  color-scheme: light;
+  --bg: #fffcf0; --surface: #f2f0e5; --surface-alt: #e6e4d9;
+  --text: #100f0f; --muted: #6f6e69; --border: #cecdc3; --accent: #205ea6;
+  --page-muted: #575653; --link: #205ea6;
+  --role-input: #24837b; --role-process: #205ea6; --role-decision: #ad8301;
+  --role-external: #5e409d; --role-success: #66800b; --role-failure: #af3029; --role-skipped: #6f6e69;
+  --role-strength: 18%;
+  --pele-series-1: #af3029; --pele-series-2: #bc5215; --pele-series-3: #ad8301; --pele-series-4: #66800b;
+  --pele-series-5: #24837b; --pele-series-6: #205ea6; --pele-series-7: #5e409d; --pele-series-8: #a02f6f;
+}
+html[data-theme="dark"] {
+  color-scheme: dark;
+  --bg: #100f0f; --surface: #1c1b1a; --surface-alt: #282726;
+  --text: #cecdc3; --muted: #878580; --border: #403e3c; --accent: #4385be;
+  --page-muted: #878580; --link: #66a0c8;
+  --role-input: #3aa99f; --role-process: #4385be; --role-decision: #d0a215;
+  --role-external: #8b7ec8; --role-success: #879a39; --role-failure: #d14d41; --role-skipped: #878580;
+  --role-strength: 24%;
+  --pele-series-1: #d14d41; --pele-series-2: #da702c; --pele-series-3: #d0a215; --pele-series-4: #879a39;
+  --pele-series-5: #3aa99f; --pele-series-6: #4385be; --pele-series-7: #8b7ec8; --pele-series-8: #ce5d97;
+}
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--surface); color: var(--text); font: 16px/1.65 var(--font); }
+main { max-width: 1200px; margin: auto; padding: 40px 28px; }
+.page-heading { display: flex; justify-content: space-between; align-items: start; gap: 20px; }
+h1 { font-size: clamp(26px,4vw,38px); line-height: 1.3; margin: 0 0 12px; }
+h2 { font-size: 20px; margin: 0 0 16px; }
+header p { color: var(--page-muted); font-size: 14px; }
+.theme-controls { display: flex; flex-shrink: 0; padding: 3px; gap: 3px; border: 1px solid var(--border); border-radius: 9px; background: var(--bg); }
+.theme-controls button { cursor: pointer; font: inherit; font-size: 13px; min-height: 36px; padding: 5px 14px; border: 0; border-radius: 6px; background: transparent; color: var(--muted); }
+.theme-controls button[aria-pressed="true"] { background: var(--surface-alt); color: var(--text); font-weight: 600; }
+nav { display: flex; flex-wrap: wrap; gap: 10px 20px; margin: 20px 0; }
+a { color: var(--link); text-decoration: underline; text-underline-offset: 4px; overflow-wrap: anywhere; }
+.legend { display: flex; flex-wrap: wrap; gap: 10px 22px; padding: 0; margin: 22px 0 32px; list-style: none; font-size: 13px; color: var(--page-muted); }
+.legend li { display: inline-flex; align-items: center; gap: 8px; }
+.legend i { width: 12px; height: 12px; border-radius: 3px; background: var(--role-color); }
+section { min-width: 0; margin: 24px 0; padding: 24px; background: var(--bg); border: 1px solid var(--border); border-radius: 12px; }
+.diagram {
+  width: 100%; min-width: 0;
+  --pele-bg: var(--bg); --pele-fg: var(--text); --pele-fg-on-light: #100f0f; --pele-fg-on-dark: #fffcf0;
+  --pele-muted: var(--muted); --pele-line: var(--muted); --pele-surface: var(--surface);
+  --pele-surface-alt: var(--surface-alt); --pele-border: var(--border); --pele-accent: var(--accent);
+  --pele-critical: var(--role-failure); --pele-error: var(--role-failure); --pele-font: var(--font);
+}
+.diagram > svg { display: block; max-width: 100%; height: auto; margin-inline: auto; }
+.fugueInput { --role-color: var(--role-input); }
+.fugueProcess { --role-color: var(--role-process); }
+.fugueDecision { --role-color: var(--role-decision); }
+.fugueExternal { --role-color: var(--role-external); }
+.fugueSuccess { --role-color: var(--role-success); }
+.fugueFailure { --role-color: var(--role-failure); }
+.fugueSkipped { --role-color: var(--role-skipped); }
+
+/* Neutral model states follow the theme; rule outcomes keep their source colors. */
+.diagram .pele-state:is(.works,.worksPath) > :is(rect,path,circle,ellipse,polygon) { fill: var(--surface) !important; }
+.diagram .pele-state:is(.works,.worksPath) .pele-label { fill: var(--text) !important; }
+
+/* Roles are explicit Mermaid classes, never guessed from labels or source order. */
+.diagram .pele-node:is(.fugueInput,.fugueProcess,.fugueDecision,.fugueExternal,.fugueSuccess,.fugueFailure,.fugueSkipped):not([class*="wrong" i]):not([class*="fixed" i]):not([class*="mixed" i]):not([class*="after" i]):not([class*="worse" i]) > :is(rect,path,circle,ellipse,polygon) {
+  fill: color-mix(in srgb, var(--role-color) var(--role-strength), var(--bg)) !important;
+  stroke: var(--path-border, var(--role-color)) !important;
+}
+.diagram .pele-node:is(.fugueInput,.fugueProcess,.fugueDecision,.fugueExternal,.fugueSuccess,.fugueFailure,.fugueSkipped):not([class*="wrong" i]):not([class*="fixed" i]):not([class*="mixed" i]):not([class*="after" i]):not([class*="worse" i]) .pele-label { fill: var(--text) !important; }
+
+/* Blue path borders remain blue, with their original width and step numbers. */
+.diagram .pele-state[class*="Path"] { --path-border: var(--role-process); }
+.diagram .pele-state[class*="Path"] > :is(rect,path,circle,ellipse,polygon) { stroke: var(--role-process) !important; }
+a:focus-visible,button:focus-visible,.diagram:focus-visible { outline: 2px solid var(--accent); outline-offset: 4px; }
+noscript { color: var(--page-muted); }
+@media(max-width:640px) {
+  main { padding: 24px 14px; }
+  .page-heading { flex-direction: column; gap: 8px; }
+  section { padding: 16px 10px; }
+  h2 { font-size: 18px; }
+}

package/skills/fugue-show-me/references/pele.md

@@ -0,0 +1,68 @@
+# Pele 展示层
+
+Pele 只负责把 Mermaid 画成 SVG。模型决定要解释什么、采用哪个视角和保留哪些关系；源码、运行结果与上游检查结果提供事实依据。展示层不重新判断这些事实。
+
+## 生成单文件 HTML
+
+```bash
+node <本 skill 目录>/scripts/render-html.mjs \
+  --title "取消与恢复的实现" \
+  --out /绝对路径/说明.html \
+  /绝对路径/全局视图.mmd \
+  /绝对路径/调用顺序.mmd \
+  /绝对路径/状态与缺陷.mmd
+```
+
+仅传入本次解释需要的图，不要求凑齐示例中的三种视角。输入与产物放在目标源码仓库之外，除非用户明确要求保存到仓库。
+
+脚本使用 `pele@1.12.0`，首次通过 npm 安装到用户缓存目录的 `fugue-show-me/pele-1.12.0`，遵循 `XDG_CACHE_HOME`，默认在 `~/.cache` 下。缓存独立于 `statechart`；不读取上游缓存、导入上游私有模块或依赖上游 PNG 渲染实现。
+
+所有输入先调用 `render()` 检查并生成 SVG，成功后才写 HTML；错误会使命令失败，不生成仅剩下载入口的页面。HTML 同时内嵌 SVG、Mermaid 源码和 Pele 的浏览器包。浏览器通过 `mount()` 使用实际字体和容器宽度布局，缩放、拖动、复位及键盘操作复用 Pele 自带能力。
+
+打开后查看每张图，而不是仅检查命令成功。浏览器发生绘图错误时，Pele 会在图旁显示错误；这仍是不完整的交付，需要修复并重新检查。
+
+## 主题与颜色含义
+
+使用 Pele 官方站点的 Flexoki 浅色与深色配色：浅色为暖白 `#fffcf0`，深色为墨黑 `#100f0f`。页面内提供切换按钮；命令加 `--theme dark` 可指定初始深色，默认浅色。颜色通过同一份 CSS 变量切换，不重新布局图，也不改变缩放位置。
+
+| 信息角色 | Mermaid 类名 | 色系 |
+| --- | --- | --- |
+| 输入、上下文与事实 | `fugueInput` | 青色 |
+| 程序处理步骤 | `fugueProcess` | 蓝色 |
+| 判断、确认与等待 | `fugueDecision` | 黄色 |
+| 外部系统交互 | `fugueExternal` | 紫色 |
+| 完成与目标达成 | `fugueSuccess` | 绿色 |
+| 失败与阻断 | `fugueFailure` | 红色 |
+| 跳过与未执行 | `fugueSkipped` | 灰色 |
+
+流程图用标准 Mermaid 类标注，类的主题样式由本层 HTML 提供：
+
+```mermaid
+flowchart LR
+  input[任务事实]:::fugueInput --> check{来源是否完整}:::fugueDecision
+  check -->|完整| run[执行处理]:::fugueProcess
+  check -->|缺失| stop[失败并保留事实]:::fugueFailure
+  run --> done[交付结果]:::fugueSuccess
+```
+
+状态图在展示副本中增加 `class s0 fugueInput` 这样的颜色角色即可，保留原 `class`、状态、边、编号和规则标记。已标记的错误或修复状态保持原有结果配色；缺陷路径继续使用蓝框及原有线宽。不得为了颜色修改模型或把失败状态改成通过。
+
+时序图用标准 `box rgba(...) 分组名` 区分参与方，透明填色能与浅、深背景叠合；分组名写明职责。需要突出某段交互时可使用 `rect rgba(...)`。采用上表的对应色系，不按参与方顺序随机分色。
+
+页面图例只列出图中实际使用的颜色角色。颜色增强信息分组，文字标签继续承载含义。两种主题均需检查实际节点填色、标签和连线，测量文字与其真实背景的对比度。
+
+配色来源：[官方站点 Flexoki 主题定义](https://github.com/obsidianmd/pele/blob/bdbad5df4dea13b9a14a83a92aed62c4769e49f5/website/src/styles/pele-theme.scss)。
+
+## 集成到已有 HTML
+
+可以调整生成页面的布局、说明和 CSS，保留每张图的容器、源码数据与初始化脚本。也可按以下原则自行组装：
+
+- 使用 Pele 的公开 `render()` / `mount()` API；浏览器单文件使用 `pele/global` 导出的包并内嵌它，不依赖 CDN。
+- 把 SVG 放在相应说明旁。多张图各用独立的 `idPrefix`，避免箭头、渐变、标题和描述的 ID 冲突。
+- 图示 CSS 位于 `assets/diagram.css`，生成时内嵌到 HTML。用 `--pele-bg`、`--pele-fg`、`--pele-muted`、`--pele-line`、`--pele-surface`、`--pele-surface-alt`、`--pele-border` 等 CSS 变量匹配宿主页面。源图的 `classDef` 可能表达错误、修复和缺陷路径，不为统一配色覆盖这些语义。
+- 用 `mount()` 读取实际中文字体并随容器宽度重排；需要缩放时使用它的 `zoom` 选项，不自行实现图布局或缩放系统。仍然过密的图应先拆分视角，而不是继续缩小文字。
+- 内嵌源码、标题和说明时正确转义 HTML 与脚本结束标签。图中禁用外部图片以保持离线显示，保留 Pele 的许可文本。
+
+Pele 使用自己的布局与主题；Mermaid 的 `themeVariables` 不生效，任意 HTML 标签也不受支持。遇到不支持的语法，按原含义调整或拆图后重新验证；状态与缺陷路径的含义必须保持，不静默改用另一套渲染器。
+
+官方依据：[API](https://pele.run/api)、[主题](https://pele.run/theming)、[兼容性](https://pele.run/compatibility)、[安全与嵌入](https://pele.run/security)。

package/skills/fugue-show-me/scripts/render-html.mjs

@@ -0,0 +1,116 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+
+const version = '1.12.0';
+const fontFamily = "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', sans-serif";
+const html = text => text.replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char]);
+const json = value => JSON.stringify(value).replace(/</g, '\\u003c');
+const roles = [
+  ['fugueInput', '输入事实'], ['fugueProcess', '处理步骤'], ['fugueDecision', '判断与等待'],
+  ['fugueExternal', '外部交互'], ['fugueSuccess', '完成'], ['fugueFailure', '失败与阻断'], ['fugueSkipped', '跳过'],
+];
+
+async function loadPele() {
+  const cache = join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'fugue-show-me', `pele-${version}`);
+  if (!existsSync(join(cache, 'node_modules', 'pele', 'package.json'))) {
+    await mkdir(dirname(cache), { recursive: true });
+    const staging = await mkdtemp(`${cache}-`);
+    try {
+      await writeFile(join(staging, 'package.json'), '{"private":true}\n');
+      console.error(`首次安装 pele@${version}，缓存位置：${cache}`);
+      const result = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--ignore-scripts', '--save-exact', `pele@${version}`], {
+        cwd: staging,
+        encoding: 'utf8',
+        env: { ...process.env, PATH: `${dirname(process.execPath)}${process.platform === 'win32' ? ';' : ':'}${process.env.PATH || ''}` },
+        shell: process.platform === 'win32',
+      });
+      if (result.status !== 0) throw new Error(result.error?.message || result.stderr || 'Pele 安装失败');
+      try { await rename(staging, cache); }
+      catch (error) { if (!existsSync(join(cache, 'node_modules', 'pele', 'package.json'))) throw error; }
+    } finally {
+      await rm(staging, { recursive: true, force: true });
+    }
+  }
+  const require = createRequire(join(cache, 'package.json'));
+  const { render } = await import(pathToFileURL(require.resolve('pele')).href);
+  const bundle = await readFile(require.resolve('pele/global'), 'utf8');
+  const license = await readFile(join(dirname(require.resolve('pele/package.json')), 'LICENSE'), 'utf8');
+  return { render, bundle, license };
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({ options: {
+    out: { type: 'string', short: 'o' }, title: { type: 'string' }, theme: { type: 'string', default: 'light' }, help: { type: 'boolean', short: 'h' },
+  }, allowPositionals: true });
+  const usage = '用法：node render-html.mjs --out 说明.html [--title 标题] [--theme light|dark] 总览.mmd [细节.mmd ...]';
+  if (values.help) { console.log(usage); return; }
+  if (!values.out || !positionals.length) throw new Error(usage);
+  if (!['light', 'dark'].includes(values.theme)) throw new Error('主题必须是 light 或 dark');
+  const sources = await Promise.all(positionals.map(async file => ({
+    title: basename(file, extname(file)), source: await readFile(file, 'utf8'),
+  })));
+  const { render, bundle, license } = await loadPele();
+  const diagrams = sources.map((diagram, index) => {
+    const id = `diagram-${index + 1}`;
+    try {
+      const { svg } = render(diagram.source, { idPrefix: id, fontFamily, images: false });
+      return { ...diagram, id, svg };
+    } catch (error) { throw new Error(`${positionals[index]}：${error.message}`, { cause: error }); }
+  });
+  const title = values.title || '图解说明';
+  const css = await readFile(new URL('../assets/diagram.css', import.meta.url), 'utf8');
+  const nodeClasses = diagrams.flatMap(({ svg }) => [...svg.matchAll(/<g\b[^>]*\bclass="([^"]*)"/g)].map(match => match[1].split(/\s+/)))
+    .filter(classes => classes.includes('pele-node') && !classes.some(name => /wrong|fixed|mixed|after|worse/i.test(name)));
+  const usedRoles = roles.filter(([name]) => nodeClasses.some(classes => classes.includes(name)));
+  const legend = usedRoles.length ? `<ul class="legend" aria-label="颜色含义">${usedRoles.map(([name, label]) => `<li class="${name}"><i aria-hidden="true"></i>${label}</li>`).join('')}</ul>` : '';
+  const sections = diagrams.map(({ title, id, svg }) => `<section aria-labelledby="${id}-heading">
+<h2 id="${id}-heading">${html(title)}</h2>
+<div class="diagram" id="${id}" role="region" aria-label="${html(title)}">${svg}</div>
+</section>`).join('\n');
+  const page = `<!doctype html>
+<html lang="zh-CN" data-theme="${values.theme}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${html(title)}</title><style>
+:root { --font: ${fontFamily}; }
+${css}
+</style></head><body><main>
+<header><div class="page-heading"><h1>${html(title)}</h1><div class="theme-controls" role="group" aria-label="页面主题"><button type="button" data-theme-option="light" aria-pressed="${values.theme === 'light'}">浅色</button><button type="button" data-theme-option="dark" aria-pressed="${values.theme === 'dark'}">深色</button></div></div><p>先看全局，再查看需要的细节。图内可缩放、拖动和复位；聚焦图后也可使用 +、−、0 和方向键。</p></header>
+<nav aria-label="图示目录">${diagrams.map(({ id, title }) => `<a href="#${id}-heading">${html(title)}</a>`).join('')}</nav>
+${legend}
+${sections}
+<noscript>当前展示静态图；启用 JavaScript 后可使用自适应布局和缩放。</noscript>
+</main>
+<script id="diagram-sources" type="application/json">${json(diagrams.map(({ id, source }) => ({ id, source })))}</script>
+<script>/* Pele ${version}\n${license.replace(/\*\//g, '* /')}\n*/\n${bundle.replace(/<\/script/gi, '<\\/script')}</script>
+<script>
+for (const button of document.querySelectorAll('[data-theme-option]')) {
+  button.addEventListener('click', () => {
+    document.documentElement.dataset.theme = button.dataset.themeOption;
+    for (const option of document.querySelectorAll('[data-theme-option]')) {
+      option.setAttribute('aria-pressed', String(option === button));
+    }
+  });
+}
+for (const { id, source } of JSON.parse(document.getElementById('diagram-sources').textContent)) {
+  const container = document.getElementById(id);
+  pele.mount(container, source, {
+    idPrefix: id,
+    images: false,
+    zoom: { always: true, labels: { zoomIn: '放大', zoomOut: '缩小', reset: '显示全图' } },
+    onRender() { container.dataset.rendered = 'true'; delete container.dataset.renderError; },
+    onError(error) { container.dataset.renderError = String(error); },
+  });
+}
+</script></body></html>`;
+  const output = resolve(values.out);
+  await mkdir(dirname(output), { recursive: true });
+  await writeFile(output, page);
+  console.log(`已生成 ${diagrams.length} 张图：${output}`);
+}
+
+main().catch(error => { console.error(error.message); process.exitCode = 1; });