explain-visually

用视觉方式解释

目标：让读者快速了解有哪些变化、如何运作以及原因，并且无需逐行阅读代码就能做出决定。用展示代替讲述，先简明扼要，再按需提供细节。全篇一页，约 1,000–1,500 字： 用简短的故事步骤讲解，并在选项行和切换项中提供做出决定所需的细节。

严格按照事实表述，尤其是标题：

• “已迁移”不等于“已保留”或“可正常工作”；“已遵循”不等于“未更改”。在同一句中说明例外： “263 条规则已迁移；有 1 条必须关闭”。
• 在条件发生变化后测得的数字，不代表“相同”：“关闭该规则后为 5.3 s”。
• 对部分成员成立的情况，不代表对整个群组都成立：点名说明（“react-x 和 react-jsx 作为插件加载”）。
• 面向初次接触这些工具的读者：每个工具或术语首次出现时，都在同一句中用几个字解释（“tsgolint，Oxc 的类型检查辅助工具”），故事和选项行中都要如此。

视觉风格取自 explainer-kit 技能；每章使用对应的 explain-with-* 技能。

适用场景

• 用户要求进行视觉化解释、撰写说明文，或提出“用视觉方式解释这个”。
• 解释代码更改、提案、计划或架构决策，帮助用户做出明智的决定。

1. 收集／研究信息和事实并写入 facts.md

• 如果已有事实文件（例如任务提供了该文件），则以其为准：跳至第 2 步。
• 使用最多 3 个并发子 Agent 研究事实／主题。
  • 输出每条事实，并在同一行注明来源（file:line、链接或运行的命令）。不要在思考过程中重复陈述事实；只写一次。
  • 通过命令获取数字（grep -c、jq、计时运行），不要手动计数。
  • 只要成本不高，就在真实仓库上测量（使用临时副本或 worktree，绝不要在仓库本身上测量）。注明方法和版本。不要把单次测量夸大成“每次”或“全部”。
  • 当计划陈述的每个说法都有来源时，就停止研究。
• 作为协调者，将研究结果整合到 facts.md。
• 记录用户必须决定的事项、每个选项所需的工作量、风险及其解决办法，以及哪些情况会改变建议。

2. 规划页面（不另写简报）

将计划写在 notes.md 的首行起（≤ 15 行）：一句话结论及其主要代价、3–5 个关键数字（每个数字在页面上只出现一次）、需要解释的 4–8 个术语、要展示的一段真实代码片段（配置或读者需要更改的代码，≤ 8 行），以及每章一行说明。章节如下：

章节	使用的技能	Section	适用时机
概览	本技能（kit 概览）	—	始终适用
故事	explain-with-storytelling	story	始终适用：5–7 个步骤，一张逐步演变的图示
代码	explain-with-code-walkthrough	code	仅当更改内容就是读者必须查看的代码时适用
决策	explain-with-preview，选项（JSON）	decide	用户需要做决定时适用

• 概览之后最多 3 章。脆弱性、依赖和复杂性应写入决策选项的行中（保留／失去／先修复／风险），不要另设章节。只有在不存在待决定事项时，单独的前后对比章节（explain-with-preview）才可替代代码章节。
• 概览： 标题要说明结论和主要代价（“lint 从 44 s 降至 5.3 s；有 1 条规则和 3 项检查需要移植”），配一条句子、一张主体图（按比例绘制；数字使用 kit 的 HTML ev-bars ev-bars--hero，确保在手机上也清晰可读），以及一条关键提示，最多带一个“决定”提示框。不要使用信息卡片网格。
• 只有用户提出要求时，才添加 explain-with-section-clips、-slides 或 -video。

3. 自行编写各章节

• 在同一轮中阅读 explainer-kit/assets/FRAGMENT-CONTRACT.md 和你要用的章节技能。此契约就是完整的 API：本页面绝不要读取 kit.css、kit.js、assemble.py 或 SCRIPTS-AND-TABS.md。
• 自行编写各章节，每个章节写入一个文件，并按顺序使用 Write 工具编写（绝不要使用 shell heredoc：一个多余的引号就会导致整个命令失败，而且每个文件都得重写）。页面规模这么小时，不要启动子 Agent。
• 按原样使用 kit 组件；不要新增主题、字体或组件，也不要编写自己的布局 CSS。
• 将计划中的真实代码片段作为推荐选项的 code 放入决策 JSON 中（如果谨慎选项会更改配置，也要放入该选项的 code），不要把代码片段单独写成章节。
• 参考资料放在详情中：文件路径写在代码标头中，链接放在决策的 Sources 切换项中。

4. 组装、检查一次，然后发布

python <kit>/assets/preview.py decide.json --out frag-decide.html
python <kit>/assets/assemble.py --page --toc --title "Short name" --overview overview.html \
  --section story=frag-story.html --section decide=frag-decide.html --out index.html
python <kit>/assets/check.py index.html

• 仅在所有文件写入都已返回后，才运行这些命令，并将它们串联成一条命令。
• 修复组装器报告的契约错误。
• 运行一次 check.py。仅修复它列出的问题，再运行一次，然后停止。不要截取或查看截图来寻找其他问题，也不要编写自己的浏览器脚本。
• 对照 facts.md 通读页面文本一次：核对数量、名称，并确保没有使用事实不支持的“每个／所有”之类的说法。
• 将单页作为工件发布（除非对方只要求写入文件）。回复不超过 5 行：给出答案、页面路径以及任何未检查的内容。