UltraExplainer 是做什么的？
将代码、系统、差异、计划、数据和概念转化为单个自包含的 HTML 页面，让一个重要的想法在第一屏就显而易见——然后用锚定证据来证明它。UltraExplainer 是三个部分协同工作：
- 合成方法（大脑）——如何决定展示什么，强调什么，舍弃什么，以及如何避免绘制源代码中没有的结构。见
references/synthesis-method.md。 - 变色龙工作室（技艺）——一个稳定的、与设计语言无关的组件契约（
assets/core.css），由七种完整的设计语言（assets/themes.css）重新定义样式。同一个差异在 Terminal 下呈现为 IDE 侧边栏，在 Blueprint 下呈现为标尺标注，在 Editorial 下呈现为图形。你选择适合主题的语言；发光是其中一个选项（Luminous），绝非默认。见references/aesthetic-languages.md和references/component-contract.md。 - 交互层（
assets/ux.js）——一个共享的状态→渲染引擎，支持滑块、场景切换、逐步演示、可排序/过滤的表格、滚动监视导航和路由节点边图。见references/interactivity.md。
身份：真理 + 正确的设计语言 + 经过验证的技艺。 不是“万物发光”，不是“框和箭头的乱炖”，不是“一堵相同的卡片墙”。
何时使用本技能
每当输出本质上是视觉化、关系型或可操作的，而 ASCII/Markdown 会使其混乱时，请使用 HTML 页面：
- 图表、架构概览或显示事物如何连接或流动的节点边图。
- 差异 / PR 审查（更改的代码 + 为何重要 + 影响范围）。
- 计划 / 需求审核或比较矩阵。
- 指标仪表盘，或任何 4+ 行 / 3+ 列的表格。
- 解释机制的概念讲解，或读者应通过更改输入来感受的交互式模型。
- 幻灯片，或用于上下文切换的项目回顾。
如果确切的答案适合一句话或一个数字，请在聊天中直接说出——不要制造一个页面（最小可行解释器规则）。当你确实构建时，给出一个聊天摘要和文件。
两种模式——在开始阶段决定
说明你处于哪种模式（以便用户可以纠正）：
- EXPLAIN（默认）——论题优先，适用于需要快速得出结论的审阅者、决策者或上下文切换者。显著性上限适用（T0 ≤ 3，T1 ≤ 7）。
- TEACH——问题优先，适用于需要可运行心智模型的学习者。具体先于抽象，预测后揭示，并以迁移检查结束。见
references/teaching.md。
方法简述
在生成任何非平凡内容之前，请阅读 references/synthesis-method.md。简短形式：
- 章程——一句话：“这解释*<工件>，在高度<A0–A4>，面向<受众>，以便他们能<任务>*，”加上模式（EXPLAIN/TEACH）。保持一个高度。
- 带有张力的论题——一个读者还不知道的陈述性主张（不是一个话题）。选择脊柱（眼睛跟随的单一轴线）。
- 证据账本——阅读真实来源；为每个节点/边/标签/数字记录
{声明，锚点 (文件:行 / 符号 / git 引用 / 指标+日期)，置信度 (已验证|推断|假设)}。无锚点 → 它不以事实形式渲染。 对于交互模型，每个滑块范围/默认值以及输入→输出函数都要锚定或标记为“说明性模型，未经测量”。 - 调和——将论题与矛盾证据对比；修订、限定范围，或展示矛盾。切勿默默忽略。
- 最小可行检查——不要过度渲染。简单答案 → 主句 + 一个视觉。
- 显著性分级——T0（论题 + 脊柱，≤3）/ T1（承重支撑，≤7）/ T2（收据，放在
<details>/悬停中）。超过上限 → 拆分或降级，绝不压缩以适应。（TEACH 模式将上限替换为理想难度预算。） - 选择设计语言——根据主题 × 受众 × 媒介对 7 种语言进行评分，并记录一行：
LANGUAGE: <名称> 因为 <主题 + 受众 + 媒介>。见下文。 - 表示——先考虑可操控性问题（“读者是否应该通过更改输入来感受一个关系？”）；如果是，则选择模型/步进器/场景。否则选择最低墨迹的静态形式。定量地编码幅度（大小/长度/位置），而不是等大小的框。
- 压缩——省略是技艺；折叠重复（“×12 个处理器”）；摘录承重的行，而不是整个文件。
- 门控——交付前通过所有三个门（见下文）。
三个交付门——真理高于一切
- 真理——每个节点/边/数字都追踪到真实锚点；推断/假设的内容被明确限定；论题已与矛盾证据调和；你重新打开了锚点。明确标记的“无法确认 X”胜过自信的捏造。交互式谎言（滑块操控捏造的关系）是头等大罪。
- 工艺——眯眼测试：从房间远处看，它读起来是刻意的设计语言，而不是重新着色的模板。恰好一个 T0 焦点。
- 已观察——你实际渲染了页面并查看了它。构建它，打开它（在约 1280 和约 360 下进行无头截图），捕获控制台错误，断言没有水平页面滚动并且论题在第一个视口内，然后自我纠正。停止断言你从未测量过的检查表属性。
如何构建页面（组装）
页面由 scripts/build.mjs 从 templates/_src/<名称>.body.html 中的主体片段组装而成。最快的路径：复制最接近的模板，更改 preset，并调整内容。
- 第 1 行指令（HTML 注释中的 JSON）选择语言和调整：
<!--ux: {"title":"…","preset":"blueprint","theme":"light","fx":"flat","head":"<style>…</style>"} -->preset：blueprint | editorial | terminal | instrument | notebook | swiss | luminous（默认luminous）presets: ["…","…"]→ 每个语言生成一个文件（变色龙演示）theme：light | dark（默认为预设的自然调整）fx：glow | flat（仅 Luminous）head/foot：额外的标记；<name>.head.html/<name>.foot.html侧边文件也会被合并
- 构建内联
core.css+themes.css+ux.js，链接预设的字体，设置data-theme-preset/data-theme/data-fx在绘制之前（无 FOUC），并输出templates/<name>.html。 - 运行：
node scripts/build.mjs <名称过滤器>（过滤器是子字符串；省略则构建所有）。 - 页面的唯一外部请求是 Google Fonts（带有系统后备字体——布局从不依赖它们），以及对于 Mermaid 页面，请求 Mermaid CDN。如果这些失败，它仍应看起来正常。
关键：当内联任何包含字面字符串
</script>的 JS 时（例如示例片段），请将其转义为<\/script>，否则它会提前关闭标签并将源代码转储到页面上。
选择设计语言
根据优点路由，记录原因。完整评分卡 + 每种语言的资料见 references/aesthetic-languages.md。
| 主题 | 默认语言 |
|---|---|
| 架构、模式、协议、基础设施拓扑 | Blueprint |
| 概念、ADR、事后分析、执行叙述 | Editorial |
| 差异、PR、CLI 工具、CI 管道、日志 | Terminal |
| 指标、基准、审计、仪表盘 | Instrument |
| 教学、演练、入职培训、温和解释 | Notebook |
| 比较、原则/宣言页、状态报告 | Swiss |
| 系统流程演示、产品愿景、炫酷简报 | Luminous（绝不默认） |
打破平局：尊重用户的明确请求（“做成终端样式”）；轮换以避免会话单调；绝不要仅仅因为它花哨就选择 Luminous。
选择表示形式
根据认知任务和数据形状路由，而不是内容类型。首先考虑可操控性。完整目录及路由见 references/representations.md；诚实的图表见 references/charts-honesty.md。
| 任务 | 表示（组件） |
|---|---|
| 一个主要的收获 / 是或否 | 字体排印论题主视觉（.ux-thesis），可能下方加一个视觉 |
| 读者应该感受一个关系 | 参数模型（[data-playground]）——滑块 + 绑定的读数 |
| 顺序 / 中间状态是意义 | 逐步演示（[data-stepper]）——代码↔数据同步进行 |
| 在不同配置下行为不同 | 场景切换（.ux-seg[data-scenario-ctl]）重新点亮一个图表 |
| 真正的线性序列 | 编号列表 / 流程条（.ux-spine）——不是流程图 |
| 分支 / 合并 / 循环流 | 节点边图（.ux-graph，≤12 个节点）或主题化 Mermaid |
| 密集的成对关系 | 矩阵热图（.ux-matrix）——比一团乱麻的图更好 |
| 代码更改 / PR | 注释差异 + 结论（.ux-diff + .ux-verdict）+ 影响范围 |
| 概念 / 误解 | 天真 vs. 正确面板（.ux-compare）+ 一个工作示例 |
| 比较 / 审计 / 矩阵 | 可排序、可过滤的表格（.ux-table，th[data-sort]，data-ux-filter） |
| 定量指标 | 以 Delta 为主导的 KPI 行（.ux-kpis）+ 最简洁诚实的图表（.ux-bars/.ux-linechart） |
| 计划 / 路线图 | 当前→目标块 + 风险分级时间线（.ux-timeline） |
| 演示 | 幻灯片（templates/slides） |
| 无合适项 | 使用主题令牌的自定义内联 SVG |
模板（templates/，源码在 templates/_src/）
| 模板 | 语言 | 演示内容 |
|---|---|---|
chameleon.<preset>.html | 全部 7 种 | 以每种语言渲染的相同解释——眯眼测试 |
blueprint → playground | Blueprint | 参数驱动模型（滑块、绑定的 KPI/条形图、预设） |
terminal-diff | Terminal | PR 审查：注释差异 + 结论 + 影响范围 |
instrument-dashboard | Instrument | KPI 刊头 + 诚实的线/条形图 + 可排序/过滤表 |
editorial-concept | Editorial | 概念解释：滚动监视导航 + 自定义 SVG + 天真 vs. 正确 + 边注 |
notebook-teach | Notebook | TEACH 模式：逐步演示 + 预测后揭示 + 迁移检查 |
swiss-comparison | Swiss | 决策矩阵：超大数字 + 可排序比较表 |
luminous-flow | Luminous | 场景切换（命中/未命中）+ 路由图 + 可选发光 |
mermaid | 任意 | 带缩放/平移/展开的主题化 Mermaid |
slides | 任意 | 全视口幻灯片，带键盘/滚动导航 |
参考路由——只读取当前输出所需的内容
| 需求 | 阅读 |
|---|---|
| 如何决定展示什么/如何展示（大脑） | references/synthesis-method.md |
| 7 种语言、选择评分卡、眯眼测试 | references/aesthetic-languages.md |
令牌层级、每个 .ux- 组件、构建/组装 | references/component-contract.md |
| 表示目录 + 数据形状 × 任务路由 | references/representations.md |
| 滑块、场景切换、步进器、图表、滚动监视——JS API | references/interactivity.md |
| 诚实的图表：数字账本、通道排名、轴规则 | references/charts-honesty.md |
| TEACH 模式：学习者状态、具体优先、预测揭示、迁移 | references/teaching.md |
| 按任务划分的剧本（pr-review、postmortem、ADR、性能分析……） | references/playbooks.md |
| 自包含性、溢出安全、验证循环、交付检查表 | references/self-contained.md |
| 主题化 Mermaid（何时 + 如何） | references/mermaid.md |
| 幻灯片 | references/slides.md |
不变规则
- 真理高于美和工艺。 锚定或省略；对推断/假设的内容进行限定；切勿发明层次、对称性、边或理由。交互式范围/函数必须锚定或标记为“说明性模型”。
- 每页一种语言，基于优点选择并记录。 它必须通过眯眼测试。发光仅属于 Luminous，通过
--fx-*路由，这样data-fx="flat"就能干净地移除它；静态内容上无持续呼吸/脉冲。 - 无水平页面滚动。 网格/弹性子项上使用
min-width:0；宽内容（差异、表格、Mermaid）在其自己的overflow-x:auto容器内滚动。在 360px 处验证。 - 两种主题都看起来协调。 浅色模式是重新调整的，而不是反转的。页面以其选择的主题打开，读者可以切换（按预设持久化）；尊重
prefers-reduced-motion；保持键盘焦点可见；打印安全。 - 组件仅使用语义化 +
--fx-*令牌——绝不使用十六进制颜色。 新外观来自主题包，而不是内联颜色。 - 切勿定义页面级的
.node类——Mermaid 内部使用它。所有 UltraExplainer 类都以.ux-为前缀。 - 交付前先观察。 渲染页面，查看它，修复问题。不要断言你没有测量的内容。
最终检查表
自包含文档放在正确路径 · 使用选择的 preset 构建 · 无控制台错误 · 桌面端或 360px 均无水平溢出 · 字体优雅降级 · 论题在第一个视口内显而易见且恰好一个焦点 · 表格/差异/图表在其自己的容器内滚动 · 主题（和 Luminous 发光）切换有效 · 每个声明都有锚点或限定 · 页面已实际渲染并检查。