讲稿图解 (visual-onepager)

目标

输入一段话，输出一个 .html 文件，让完全不懂这个领域的人看完能复述出核心结论。

不是"把原文搬到网页上"。是重新组织信息：先抽结论，再选视觉形式，最后用大白话写每一句。

三条铁律（违反就是失败）

1. 零术语。原文出现的每个专业名词，要么删掉，要么换成日常说法。做不到就在页面上留一句括号注解。
2. 5 秒测试。读者只看标题 + 每节的图，5 秒内能说出"这页在讲什么"。做不到就是信息密度过高，必须拆。
3. 不编数据。原文没有的数字一律不出现。需要数字才能讲清楚的地方，写"需要 XXX 数据"，不要编一个。

形象度铁律（2026-10-09 追加，实测教训）

光有"框+ 文字"的图不算图。 每一张图都必须满足至少一条：

• 画出状态：用具象图形表现（叠起的纸、散点、放大镜、气泡），不是只写文字
• 承载关系：表达先后、对比、包含、传导之一
• 承载数据：有真实数值和单位

三条都不满足的图，删掉它，别凑数。

每节必须有一句"金句"

每个 <h2> 下面第一件事，是一条 ≤20 字的结论句（用 .punch 样式，浅蓝底+ 左侧蓝条）。
这是读者扫视时唯一会停留的地方，不能省。示例：

• ✅ "它不会说'我不知道'，只会顺着语感往下接。"
• ✅ "模型一个字都没改，改的只是'喂进去什么'。"
• ✅ "备料在先，开卷在后——顺序反了就答不对。"
• ❌ "接下来介绍 RAG 的工作原理。"（这是主题句，不是结论句）

工作流

Phase 1 — 抽取（不写代码）

先在心里/纸上做这四件事，写下来：

要点多于 7 个 → 必须合并或砍掉。 这是单页，不是清单。

Phase 2 — 配图（每节选一种，别全都用柱状图）

读 references/chart-recipes.md 拿代码配方。按"这个要点想让读者看懂什么"来选：

★ 规则修订：图表类型上限（2026-10-09 改）

旧规则："整页最多 2 种图表类型"——这条定得太死，会逼得只敢用最朴素的表达。
实测后果：做出来的页面只有对比表和灰方框流程图，用户反馈"太简单、不够形象"。

新规则：

真正的约束不是"类型数量"，而是"每张图都在干活"。
判断标准：把这张图删掉，读者理解会受损吗？不会 → 删掉。

Phase 3 — 写文案

读 references/plain-language.md。核心是改写规则和术语替换表，还有交付前的自检清单。

写的时候：
- 每节 = 一个 <h2> + 一句 .punch 金句 + 一段解释 + 一张图
- 标题写结论，不写主题。❌"数据同步流程" ✅"改一个数，别处自动跟着变"
- 流程图/思维导图的卡片里加 flow-tag 标注成本（"离线做一次" / "每次都做"）

Phase 4 — 生成 HTML

用 assets/template.html 作为骨架，把内容填进各个 slot。模板已经把排版、配色、字号、打印样式调好了。

硬性要求：
- 单文件，零外部依赖。不引 CDN，不引外部字体，不引 JS 库。图表全部用内联 SVG 或 CSS 画。
- 理由：这个文件要能被直接双击打开、能微信发出去、能塞进 U 盘，不依赖网络。
- 例外：用户明确要"可交互/可筛选"时，才允许引 Chart.js CDN，并告知离线会失效。
- 字体只用系统字体栈（见模板里的 --font）。
- 配色只用模板里已定义的 CSS 变量，不新增颜色。中文要能正常显示。
- SVG 示意图必须加 role="img" + aria-label，并配 .legend 解释颜色含义。
- 完成后必须调 present_files 打开预览。

Phase 5 — 自检（别跳过）

5a. 静态检查（秒级）
- 外链 grep：应无任何 http / <script> / CDN
- 标签开闭配对
- 无 BOM + charset="UTF-8" 在位

5b. 真实浏览器检查（有 playwright 就必须做）

用 playwright-core + 本机 Chrome/Edge，在 1280 / 768 / 375 三档视口下检测：
- 横向溢出（scrollWidth > clientWidth）
- 元素矩形相交（HTML 块级 + SVG 内的 <text> 之间）
- 文字裁切（scrollWidth > clientWidth）
- 输出 fullPage 截图

5c. 截图肉眼复核（不可省略）

> 实测教训：自动检测全绿≠ 视觉没问题。
> 负 margin、absolute 定位、preserveAspectRatio="none" 这三类写法，
> 几何上都不溢出，但视觉上会"挤在一起/串行"。
> SVG 示意图和思维导图必须放大截图看。

5d. 内容自检

对照 references/plain-language.md 末尾的自检清单逐条过。任何一条不过，改完再交。

输出规范

• 文件名用中文：讲清楚-XXX.html（XXX 是主题，4~8 字）。
• 放在用户当前工作目录下，不要塞进临时目录。
• 交付时在回复里用 3~5 句话说明：核心结论是什么、用了哪几种图、哪一节最值得先看。

常见翻车点

参考文件

边界

• 输入是数据表格 / 多份文档 / 需要计算 → 交给 sheetagent 或 long-report-agent，本 skill 只负责"已经想清楚的内容 → 单页"。
• 需要超过一页的完整报告 → 用 tencent-pptx 或 可研报告撰写skill。

与infographic-maker 的区别（选型必读）

两者都做"把复杂内容变图"，但产物完全不同，不要混用：

判断：要能改、能查、能存档 → 用本技能；只要一张好看的图 → 用 infographic-maker。

实战经验（2026-10-09，三轮迭代实测）

这一节记录踩过的坑，比配方本身更重要。

★ 经验 1：规则定太死，会逼出"最朴素的表达"

第一版定了「整页图表类型 ≤ 2 种」，结果只敢用对比表 + 灰方框流程图，
用户直接反馈"太简单、不够形象、没有图"。

教训：规则是为了保证质量，不是为了限制表达。
当一条规则开始压制输出时，先怀疑规则。

现在的写法是分场景给上限，并加了一条真正的约束：

> 每张图都要在干活。 把这张图删掉，读者理解会受损吗？不会 → 删掉。

★ 经验 2：自动检测全绿 ≠ 视觉没问题

用 playwright-core做三档视口（1280/768/375）检测横向溢出、元素矩形相交、
文字裁切，全部通过，但截图里仍有明显问题：

必须肉眼复核的三类写法：负 margin、absolute 定位、preserveAspectRatio="none"。

★ 经验 3：SVG 的三个具体坑

1. preserveAspectRatio="none" 会横向拉伸线宽。2px 线在1000px 宽的 viewBox 里
   变成粗条。解法：vector-effect:non-scaling-stroke。
2. 箭头不要压在图形上。先定每段占多宽、算出段中心，再把箭头只画在两段空隙里。
3. 标签统一两行：主标题 y=196、副标题 y=213，行距 17px 是实测不重叠的最小值。

★ 经验 4：不编数据，是硬约束

讲RAG 的时候最容易想当然地写"准确率提升 30%"。没有数据源就不能写。
宁可用对比表讲清机制，也不编一个数字让页面好看。

同理，机制类内容优先用示意图（不需要数字就能表达），
而不是硬凑柱状图。

经验 5：flow-tag 是高性价比的加分项

流程图的每一步标上"离线做一次" / "每次都做"，
读者立刻知道哪些是一次性成本、哪些是持续开销。
这比多写三行解释有用。

★ 经验 6：技能要能被复核，不能只被相信

浏览器检测脚本的思路值得复用（已验证可跑）：

// 完整可跑脚本见 scripts/check.mjs（已实测可跑）。核心片段如下:
import { chromium } from 'playwright-core';
import path from 'node:path';

const exe = process.env.CHROME_PATH;            // 本机 Chrome/Edge 可执行文件路径
const file = path.resolve(process.argv[2]);     // 待检 HTML
const browser = await chromium.launch({ executablePath: exe });
for (const w of [1280, 768, 375]) {
  const page = await browser.newPage({ viewport: { width: w, height: 900 } });
  await page.goto('file:///' + file);
  const r = await page.evaluate(() => {
    const de = document.documentElement;
    // ① 横向溢出 ② 元素矩形相交 ③ 文字裁切
    const overflow = de.scrollWidth > de.clientWidth + 1;
    const texts = [...document.querySelectorAll('text')];
    const clip = texts.some(t => t.scrollWidth > t.clientWidth + 1);
    return { overflow, clip };
  });
  await page.screenshot({ path: `shot-${w}.png`, fullPage: true });
  console.log(w, r);
}
await browser.close();

三个视口都要跑：1280 看桌面、768 看平板、375 看手机（手机最容易暴露溢出）。
窄屏单列是把连线、SVG 布局搞坏的头号原因。