用途：make-explainer 面向“把一项工作讲清楚”的需求，可生成分支回顾（branch recap）、diff 审查、概念或方案讲解（concept/plan explainer）、人工测试清单（checklist）以及幻灯片（slides），最终产出一个精致的离线 HTML 页面。
主要能力与工作方式：你只需编写一个 JSON 文件 explainer.json，包含标题与一组带类型的章节（tldr、text、kpis、cards、table、risks、files、steps、timeline、compare、callout、code、details、checklist、diagram、chart、motion、image 等）。脚本负责校验规格、检查文风并构建页面；你不需要写 HTML、CSS、SVG 或脚本。文本字段只接受 markdown-lite：段落、粗体、斜体、code、text 和 - 列表，其他内容按纯文本显示。
使用流程：在 explainer.json 所在的项目目录运行脚本。首次构建前运行 doctor.mjs --json 检查依赖（只需 Node）；若报告缺失，会说明每一项、用途、大小和命令，征得同意后用 --fix 安装。选择形式：recap/checklist 先用 gather.mjs git 收集已提交的工作，再用 scaffold.mjs 生成骨架；concept 与 slides 直接用 scaffold.mjs 生成。填充文件时把每个 TODO 替换为基于事实与改动文件的真实文字，事实（数字、文件、提交）不要重打；无法填写的章节可删除。然后运行 validate.mjs，修正它打印的每一行，直到显示 valid。最后运行 build.mjs 生成 HTML，默认输出到 ~/.agent/diagrams/（或 PA_OUTPUT_DIR），可用 --out 指定，用 --theme 选主题（默认 dusk，另有 press、poster 等）。构建后会打印所用主题和 HTML 路径；含视频或交互图表的章节会在页面旁生成 <name>.assets/ 文件夹，需与页面放在一起。可选运行 check.mjs 在桌面与手机宽度下打开页面，检查控制台错误、横向滚动、幻灯片无法到达最后一页、图表浮层无法关闭等问题，但需要 Playwright 和浏览器。
写作规则：章节标题要陈述结论而非标签；label 不超过 4 个词，标题不超过 8 个词；避免 emoji 过密和“leverage”“seamless”“delve”等填充词，禁止遗留 TODO 或 lorem ipsum；超出软上限（标题、段落、卡片、列表、页面字数等）会产生警告。按内容选择合适章节：数字用 kpis，文件列表用 files，步骤用 steps，选项用 compare，尽量不用大段文字。checklist 需提供 intro，列出分支交付的每个功能和评审修复点以及已有自动化测试覆盖。slides 中每个章节即一页，需保持精简（最多 6 个要点、8 行表格、12 行代码、80 个词）。
适用场景与限制：适合需要把代码分支、改动、概念、方案或测试计划整理成一页离线说明或幻灯片的场景。页面不发起网络请求，CSP 会阻止网络请求；链接仅限 http/https。若无法运行 shell 命令，则只能写出 explainer.json 并把脚本命令交给用户自行执行。分类：编程与开发（coding）。