@topmindspace/tms-skills 0.1.0

package/top-ppt-html/references/pptx-export.md

@@ -0,0 +1,209 @@
+# PPTX 生成（预览 + 智能体精导 · 常量与 schema 双单源）
+
+把 HTML 报告生成为**可编辑的 16:9 PPTX**。核心架构：**报告内嵌的 `window.REPORT_MODEL` 是唯一事实源**——HTML 是阅读与演示界面，PPTX 是协作与修改格式，两者来自同一内容模型，PPTX 内全部是原生形状/文本框/表格，**带数据的图表为原生数据图表（chart part + 内嵌 Excel 工作簿，双击即可"编辑数据"）**；**默认零图片（`pictures=0` 全原生可编辑）**，仅当模型显式声明 `section.image` 时放行对应图片；无素材时用 `image.placeholder` 出**配图占位**（原生形状，`pictures` 不增）。版式常量单源（`scripts/layout-constants.json`）+ **DSL schema 单源（`scripts/model-schema.json`）**，双端校验同源、产出一致。全程不依赖任何外部技能（质检脚本 `scripts/validate_pptx.py` 已内置，纯标准库）。
+
+## 架构总览
+
+```
+                HTML 报告（页面 + window.REPORT_MODEL，mode 生成时锁定）
+                 │                          │
+   页面预览（WYSIWYG · 不导出文件）        智能体精导（唯一交付通道）
+   header「预览 PPTX」→ 模态页序列         extract_model.py → model.json
+   （内嵌零依赖序列化引擎 slidesXml，       → build_pptx.js --model=（PptxGenJS）
+    与精导同一序列化语义，所见即所得）      → validate_pptx.py --strict（0/0 才交付）
+   + 常显「复制 AI 提示词」（引导用户         │
+     回 AI 对话补生成 PPTX）                └── gen_channel_a.js（Node 组装同引擎产物，
+                                              仅供回归双裁判，页面不使用）
+                 │
+   单源：layout-constants.json（页面几何 / 三模式独立比例尺 modeTypeScale / 页型几何 / 9 风格 token × 亮暗双套 styles+stylesDark）
+       + model-schema.json（29 种页型字段与必填约束 + 30 类 chartTypes 白名单；sync_runtime.py 注入浏览器端 validateModel，
+         extract_model.py 直接读取——双端校验同源，杜绝漂移）
+```
+
+- **页面预览**：收到/打开报告的人点 header「预览 PPTX」（快捷键 P）即可查看页序列，无需任何环境。预览模态与精导通道使用**同一序列化语义**（`slidesOf → slideXml`）——**版式与文本所见即所得**；带数据的原生图表在交付 PPTX 中为真 chart part（双击可编辑数据），预览侧为形状近似，**图表形态以精导产物为准**。**页面不直接导出文件**：浏览器端跑不了 strict 质检硬门禁，达不到交付质量；预览模态常显**可复制 AI 提示词**，用户想获得 PPTX 时复制给 AI，由智能体走精导通道生成（`?` 帮助弹窗 / 快捷键 H 有同样说明）。
+- **智能体精导**：正式 PPTX 的唯一交付路径——从报告抽模型 → 生成 → **过 strict 质检** → 交付。生成时用户选了「HTML+PPTX」交付格式的，交付时一并生成；交付后用户随时可通过页面提示词回来补生成。
+- **双单源**：页面几何/三模式独立比例尺（`typeScale` 基准 + `modeTypeScale` 模式取值）/页型几何/9 风格 token 全在 `scripts/layout-constants.json`；**页型 DSL schema（字段/必填/适用模式）在 `scripts/model-schema.json`**。通道 B 直接 `require`；页面运行时由 `sync_runtime.py` 注入（同时注入三模板的引擎/UI/运行时内联副本）。**改常量只改 JSON，改 schema 只改 schema JSON，然后跑 `python scripts/sync_runtime.py`**。
+
+## 内容模型（生成报告时与正文同步填写）
+
+三份模式模板（`assets/templates/{presentation|research|architecture}.html`）尾部已带对应模式的占位。字段：
+
+> **模型单写路径**：内容只写 `window.REPORT_MODEL`，再 `python scripts/render_from_model.py 报告.html --inplace` 回填正文——禁止 HTML/模型双写。
+
+| 字段 | 说明 |
+|------|------|
+| `mode` | `presentation` / `research` / `architecture`（与 `data-mode` 一致，生成时锁定；校验器检查） |
+| `style` | 9 套风格之一（不写则取页面 `data-style`） |
+| `theme` | `light` / `dark`（不写则取页面 `data-theme`，默认 light）——**PPTX 按此导出亮色版或深色版**（深色走 `stylesDark` token，与 HTML 深色主题同源；validate_report 检查与 `data-theme` 一致） |
+| `title` / `subtitle` / `meta` | 封面 |
+| `agenda` | `[[编号, 标题, 说明]…]`；>8 条自动双列、行高自适应；**architecture 极简形态可省略**（封面后直接进图，PPTX 相应少一页大纲） |
+| `sections` | 章节页数组，页型见下表 |
+| `closing` | `{title, points:[[k,v]×3]}` 收尾页（主题一致强调带：accent-soft 底） |
+
+**必须是严格 JSON**（双引号、无尾逗号、无注释），否则 `extract_model.py` 无法解析。
+
+### 章节页型（sections[].type）——29 种，字段约束单源 `scripts/model-schema.json`
+
+**通用（演示为主，research 可用）**
+
+| type | 对应 HTML 版式 | 关键字段 |
+|------|---------------|---------|
+| `points`（默认） | 要点列表页 | `points:[[k,v]]`、`metrics:[[值,注]]` |
+| `metrics` | 指标带页（R4） | `lead`、`metrics:[[值,注]]` |
+| `kpi` | 大数指标页（`components.md` §41） | `hero:[值,标签,delta?]`、`metrics:[[值,注]]` |
+| `table` | 密表页（R3；research 行上限 16，行高按可用高度自适应） | `table:{head, rows, colW?}` |
+| `timeline` | 时间线/路线页 | `phases:[[标签,名称,说明,'done'/'now'/'']]` |
+| `steps` | 步骤条页（`components.md` §47） | `steps:[[标题,说明]…]`（元素可为 `{t,d,accent}`）、`groups:[[标签,步数]…]?`、`note?` |
+| `bar` | 数据图表页——**原生数据图表**（16 类原生通道）或**形状还原图表**（14 类形状通道，附数据表） | `chart:{type?, labels, values, series?, points?, start?, target?, max?, unit?, colors?, dataTable?}`、`note`（`type` 取值见 `chartTypes` 30 类） |
+| `donut` | 环形图页（`components.md` §42：**原生数据图表** + 中心合计 + 数值图例） | `chart:{labels, values, unit?, centerLabel?, colors?, dataTable?}`、`note` |
+| `heatmap` | 热力矩阵页（`components.md` §48：4 级色阶，只用强调色明度阶梯） | `rowHeads:[]`、`colHeads:[]`、`cells:[[]]`、`unit?`、`scaleLabel:[低,高]?`、`note?` |
+| `bullet` | 达成对比页（`components.md` §49：底槽 + 实际条 + 目标刻度） | `items:[[标签,实际,目标]…]`、`unit?`、`max?`、`note?` |
+| `pyramid` | 金字塔页（`components.md` §50：自上而下逐层加宽） | `levels:[[标题,说明]…]`（元素可为 `{t,d,accent}`）、`note?` |
+| `image` | 素材图片页（`components.md` §11c：full/half/bleed/grid/compare/wall 六版式，比例与位置锁定；支持配图占位） | `image:{src?\|items?:[]\|placeholder?:true, layout?, fit?, caption?, alt?, hint?}`、`points:[[k,v]]`（half 右栏注解）、`note?` |
+| `cards` | 卡片网格（g-3/g-4） | `cards:[{title, points:[]}]`、`columns` |
+| `split` | **双区组合页**（g-side；左/右各可为要点｜图表｜表格｜图片，组合版式的通用解） | `left:{type?:'points'(默认)/'table'/'image'/图表类型名, points?/head?/rows?/labels?/values?/series?/image?/cap?}`、`right:{…同构，缺省 type='bar'}` |
+| `comparison` | 对比页（`components.md` §40：左右双面板） | `left/right:{title, points:[[k,v]…]}`、`verdict` |
+| `quote` | 金句页（`components.md` §39：主题一致强调带，accent-soft 底） | `quote`、`author`、`context?` |
+| `diagram` | 分层架构（.arch / A1，含层间连接；**architecture 模式自动走全幅图页型**） | `layers:[[层名,[节点…],'focus'?]]`、`legend:[]` |
+
+**research 密排专属**
+
+| type | 对应 HTML 版式 | 关键字段 |
+|------|---------------|---------|
+| `twocol` | 双栏论证页（R1） | `paragraphs:[[小标题,正文]…]`（两栏自动均分） |
+| `exhibit` | Exhibit 编号图表页（R2） | `exhibitNo`、`chart:{type?, labels,values,max?,unit?,series?,dataTable?}`（type 见 chartTypes） |
+| `threecol` | 三栏证据页（R6） | `paragraphs:[[小标题,正文]…]`（三栏自动均分） |
+| `halftable` | 半表半图页（R7） | `table:{head,rows}` + `chart:{type:'hbar',…,dataTable?}`（左表右图互证） |
+| `matrix` | 矩阵图页（R8） | `rowHeads:[]`、`colHeads:[]`、`cells:[[str 或 {t,accent}]…]` |
+
+**architecture 专属**
+
+| type | 对应 HTML 版式 | 关键字段 |
+|------|---------------|---------|
+| `lane` | 泳道页（A2；A3 管线映射为单泳道） | `lanes:[[行头,[步骤…]…]…]`（步骤 str 或 `{t,accent}`） |
+
+**复杂信息图专属（research / architecture）**——形状通道高保真还原 + 数据表：
+
+| type | 对应 HTML 版式 | 关键字段 |
+|------|---------------|---------|
+| `sankey` | 桑基图页（节点-流带，流向与流量） | `flows:[[源,汇,值]…]`、`unit?`、`chart.dataTable?`、`note?` |
+| `treemap` | 树图页（面积编码的层级构成） | `items:[[标签,值]…]`、`unit?`、`chart.dataTable?`、`note?` |
+| `boxplot` | 箱线图页（分布对比 min/q1/median/q3/max） | `groups:[[标签,min,q1,med,q3,max]…]`、`unit?`、`chart.dataTable?`、`note?` |
+| `network` | 关系网络页（节点-边拓扑） | `nodes:[[id,标签]…]`、`edges:[[源,汇]…]`、`chart.dataTable?`、`note?` |
+| `marimekko` | 马赛克图页（列宽 × 列高双重编码） | `cols:[[标签,总量]…]`、`cells:[[]…]`、`unit?`、`chart.dataTable?`、`note?` |
+| `streamgraph` | 流带图页（时间上的构成演变） | `series:[{name,values}…]`、`labels:[]?`、`chart.dataTable?`、`note?` |
+
+> 几何常量见 `layout-constants.json` `pageTypes.{sankey,treemap,boxplot,network,marimekko,streamgraph}`（含节点/流带上限、采样点下限、双边界追踪约束）；版式与生成规则详见 `references/infographics.md`。
+
+**通用可选字段（全部页型）**：`soWhat`（so-what 结论条，accent 左边线 + soft 底）、`footnote`（页脚来源行）、`flags`（**待核实标注清单** `["…"]` → accent 强调色清单条，提示用户二次确认，并写入演讲者备注）、`image`（素材图片 / 配图占位，见 `image` 页型）、`exhibitNo`（非 exhibit 页型也可带 Exhibit 徽标）。research 模式 `soWhat/footnote` **只在关键论证页填写**（克制条款）；comparison 页型的 `verdict` 为 accent 实底结论条。
+
+> **素材图片（单源 `layout-constants.json` 的 `imageSpec`）**：`image` 三选一必填——`src`（用户图，data: 内联或相对路径）｜`items:[{src,alt?,caption?,placeholder?}]`（多图版式）｜`placeholder:true`（**配图占位**，无素材时锁版式用）。
+> - **六版式**（`layout`）：`full` 版心全宽 3:1｜`half` 左图右注 4:3｜`bleed` 通栏出血 21:9｜`grid` 多图网格 4:3（2/3/4/6 张）｜`compare` 双图 A/B 4:3｜`wall` Logo 墙 1:1。比例写在 `imageSpec.ratioDefault`，**HTML 用同比例锁定类、PPTX 用同一比例算高度并垂直居中**——两通道版式一致。
+> - **裁切**（`fit`）：`cover`（默认，裁切填满）/ `contain`（完整显示留白）。
+> - **占位符**：由**原生圆角矩形 + 虚线 + 居中标签文本**渲染（`pictures` 不增，可编辑可替换）；标签串由双引擎按 `imageSpec` 拼同一串（`配图占位 · 建议 2400×800px`），保证 `cross_verify` 逐页文本一致；同时写入演讲者备注提示替换。占位**不算图片**，不触发 `PICTURES_*` 门禁。
+> - **路径解析**：相对路径以**模型文件所在目录**为锚（模型与报告同目录 ⇒ 报告里的相对路径口径一致）；文件缺失报 `IMAGE_SRC_MISSING` 并回落成占位框（不留空洞）。
+> - **准入门**：`imageAdmission`（`forbidden` 禁图片化区域 / `allowed` 可保留的复杂视觉资产 / `maxPageAreaPct` 40% / `fullSlideRiskPct` 90%）。
+> - **素材准备**：`python scripts/prepare_images.py <图片|目录> --layout full|half|grid…` → 产出可粘贴的 `.media` HTML 片段与 `image` 模型对象（自动缩放/压缩/内联，体积超限自动转相对路径）。
+
+> **图表双通道**：图表类型与通道归属以 `scripts/layout-constants.json` 的 `charts.registry` 为唯一事实源（四元组：`html` 实现 / `pptx` 通道 / `nativeType` 或 `path` 几何约束 / `dataTable` 策略）。
+> - **原生通道（16 类，`pptx:"native"`）**：`bar / hbar / stack / stackline / line / dualline / area / donut / multidonut / pie / radar / scatter / bubble` + 3 类原生技巧 `waterfall`（堆叠柱 + 隐藏基底 + 累计连接线）、`gauge`（doughnut + firstSliceAng 270° 扇形）、`pareto`（多类型组合：柱 + 累计折线）——一律走 `pptxgenjs addChart`，产出真 chart part + 内嵌 Excel 工作簿，PowerPoint/WPS 中双击即可"编辑数据"。`chart.series` 传多系列（`[{name, values}…]`）；`chart.points` 传 XY 点（scatter `[[x,y]…]` / bubble `[[x,y,size]…]`）。
+> - **形状通道（`pptx:"shape"`，20 类）**：全部走 OOXML 原生形状高保真还原（`charts.registry[type].path` 约束采样点下限、双边界追踪、禁预设形状替代）。按**载荷形态**分两组：
+>   - **可作 `chart.type` 的 14 类**（载荷 = `chart:{labels, values, series?, start?, target?, max?, unit?}`）：`funnel / gantt / vsbar / progress / sparkline / slope / dumbbell / lollipop / dotplot / bulletchart / waffle / radialbar / rose / candlestick`——由 `bar` / `exhibit` / `halftable` / `split` 页型承载。
+>   - **专属页型 6 类**（载荷是结构化数组：`flows` / `items` / `groups` / `nodes+edges` / `cols+cells` / `series`，不适合作 `chart.type`）：`sankey / treemap / boxplot / network / marimekko / streamgraph`——由同名 `sections[].type` 承载，见页型表「复杂信息图专属」。
+> - **可达性不变量**：`charts.types` 的每个类型都必须「模型可表达」——可作 `chart.type`（`model-schema.json` 的 `chartTypes`，**30 类** = 16 原生 + 14 形状）**或**可作 `sections[].type`（上述 6 类信息图页型）。`sync_runtime.py` 双向校验（`registry.types == chartTypes ∪ 信息图页型`），出现孤儿类型即 WARN——防止「登记了但模型表达不了、双引擎实现沦为死代码」。
+> - **验证口径**：36 类图表**全部**经探针模型实测双通道——原生通道断言 chart part 落位（`MODEL_CHART_COUNT` 按类型计数），形状通道断言**命中专属渲染器**（`build_pptx.js` 对未命中类型打印回落告警）且 A/B 逐页文本一致（`cross_verify.py`）。示例矩阵**永久覆盖 13 类**（`bar` / `donut` / `hbar` / `waterfall` + 6 类信息图页型 + `gantt` / `rose` / `candlestick`）；其余类型靠探针回归，改图表代码后应重跑探针。
+> - **数据可追溯（`chart.dataTable`）**：`notes`（默认，数据表写入演讲者备注）/ `inline`（图表下方附原生小字号表格）/ `off`（仅 sparkline 等装饰微图允许）。**形状通道图表的 `dataTable` 不得为 off**（豁免：登记表**自身**声明 `off` 的纯装饰微图，如 `sparkline`——`sync_runtime.py` 与 `validate_pptx.py` 同口径）。校验器 `MODEL_CHART_COUNT` 按类型断言（原生通道必须落成 chart part），`MODEL_CHART_DATATABLE` 硬拦"形状拼图无数据表"与"声明 inline 却无表格落位"。
+> - **A/B 双通道语义一致**：A 通道（浏览器预览 `pptx-export.js`）对所有类型做形状近似（类别标签与数值都落为文本），B 通道交付走原生图表；`cross_verify.py` 对两侧文本做归一化（chart categories 并入 + `NUMERIC_TOKEN` 纯数值过滤 + `sorted(set())` 去重），并额外核对 **B 通道原生图表数值 ↔ 模型数值**（类别标签一致不代表数值一致）。
+> - **通道能力边界（演讲者备注）**：A 预览通道**不产 notesSlide**（浏览器预览也看不到备注），故 `MODEL_CHART_NOTES_MISSING` 与 `MODEL_CHART_COUNT` 同走 `--allow-shape-charts` 豁免；**交付通道（B）不豁免**——`dataTable=notes` 的图表必须在备注里真的有数据表。
+>
+> **自适应排版**：所有文本块按可用高度自适应字号/行距（`fitFont`），表格行高按可用高度计算，列表/泳道/矩阵/卡片行高随容器收敛——保证不越界、不重叠（`validate_pptx.py` 硬拦越界与文本溢出）。
+
+> 保真机制：每种子页型对应 HTML 的一种锁定版式（`components.md` §36d/§37–38b/§39–42 ↔ 页型表），坐标/字号按同一套常量映射（`layout-constants.json` 的 `pageTypes` + `modeTypeScale`）。**三模式独立比例尺**：research 密排（正文 10.5pt、h1 22pt）；architecture 与 presentation 同基但 diagram 走全幅几何。图表颜色：**9 套风格各有自己的编码色板 c1–c5**（单源 `styleDataColors` / `styleDataColorsDark`，按 `model.theme` 选择），多系列图表自动取用（`dataColors(style, theme)`）；未登记风格时回落「accent / faint / body / line」四阶单色系。**页型字段与必填约束以 `model-schema.json` 为唯一事实源**（`:array` = 非空数组、`:str` = 非空字符串），浏览器端 `validateModel` 与 `extract_model.py` 校验同一份定义。
+
+## 页面预览（已内置三模板）
+
+三份模式模板均已集成：header 工具组「预览 PPTX」（快捷键 P）+「?」PPT 生成指引弹窗（快捷键 H，精导通道说明 + 可复制提示词）+ 内嵌预览运行时 + 对应模式模型占位。**生成报告时只需做一件事：把 `window.REPORT_MODEL` 填成与正文一致的内容（mode 用模板默认值，勿改）。**
+
+- 预览模态读取 `slidesXml`（与精导同一序列化输出）渲染 16:9 页序列——所见即所得
+- 打开即自检（schema 单源驱动）：模型完整 → 正常预览 + 提示词；不完整 → 尽力渲染 + 缺失清单 + 提示词
+- 预览模态常显**「复制 AI 提示词」**：用户任何时候想获得 PPTX，复制提示词回到 AI 对话即可
+- 快捷键：`T` 主题 / `P` 预览 / `H` 帮助 / `Esc` 关闭（无 `E` 导出）
+- **无模式切换**：模式生成时锁定；风格下拉可实时切换（纯视觉皮肤）
+
+> 运行时更新（`assets/pptx-export.js`）后：跑 `python scripts/sync_runtime.py`，模板内联副本与常量/schema 块自动刷新，禁止手改。**运行时只含序列化与校验，不含 ZIP 打包/下载**——打包骨架在 `scripts/gen_channel_a.js`，仅供回归双裁判。
+
+## 智能体精导（唯一交付通道 · 硬门禁）
+
+```bash
+# 1. 抽模型（报告 → model.json，自动补 style/mode，schema 单源校验 + 模型-正文一致性抽查）
+python scripts/extract_model.py "<输出目录>/YYYY-MM-DD-主题.html"
+
+# 2. 生成（PptxGenJS；--style / --theme=light|dark 可覆盖模型风格与亮暗主题；常量自动取 layout-constants.json）
+NODE_PATH=<pptxgenjs 所在 node_modules> <node> scripts/build_pptx.js "报告.pptx" --model="报告.model.json"
+
+# 3. 质检（硬门禁，0 errors / 0 warnings 才交付；--model 启用模型往返保真检查）
+python scripts/validate_pptx.py "报告.pptx" --strict --model="报告.model.json"
+```
+
+> **模型往返保真检查**（`--model`）：验证 PPTX 页数结构与模型一致（封面 + 大纲（有 agenda 时）+ sections + 收尾——**architecture 无 agenda 时按实际断言**），且每个章节标题、封面标题、收尾标题都真实落位在对应的幻灯片上——内容不丢、不串页。错配会报 `MODEL_ROUNDTRIP_*` 警告（strict 下阻止交付）。
+> **逐页覆盖**：逐页内容覆盖（section 代表性文本 ≥50% 落在对应页）+ 主题 token 对照（`MODEL_THEME_BG_MISMATCH`，亮暗一致性）。
+> **原生图表门禁**：`MODEL_CHART_COUNT` 硬门禁——模型里每个带数据的图表必须落成原生 chart part（可编辑数据），形状拼图不放行。
+
+## PPT 优秀实践（交付基线）
+
+精导产物在"可编辑"之外对齐 PowerPoint 原生使用习惯：
+
+1. **原生数据图表（16 类）**：`bar / hbar / stack / stackline / line / dualline / area / donut / multidonut / pie / radar / scatter / bubble` + 原生技巧 `waterfall / gauge / pareto` 全部走 `pptxgenjs addChart`——真 chart part（`ppt/charts/chartN.xml`）+ 内嵌 Excel 工作簿（`ppt/embeddings/*.xlsx`），在 PowerPoint / WPS 中双击即可"编辑数据"；类别/数值标签由图表自带，单系列按数据点着色（峰值 accent、其余中性，保持 HTML 视觉）。多类型组合图（瀑布/帕累托）用 `addChart([{type,data,options}…], outer)`。
+2. **数据表随行**：`chart.dataTable` 三态——`notes`（默认：数据表以「项目 | 数值」文本写入演讲者备注，零版面占用、可复制回 Excel）、`inline`（图表下方附原生小字号表格，压缩图表高度不越界）、`off`（仅 sparkline 等装饰微图）。**形状通道图表的 `dataTable` 不得为 off**（`MODEL_CHART_DATATABLE` 硬拦）——保证非原生图表的数据同样可核对。
+3. **演讲者备注**：`lead` / `soWhat` / `note` / `footnote` / 图表口径 / 数据表自动写入页备注（notesSlide）——细节沉到备注区不堆版面，讲稿口径随文件走；封面/收尾页同样有备注。
+4. **文档元数据**：`pptx.title/subject/author/company` 从模型填充——文件属性完整，检索与归档友好。
+5. **默认零图片全原生（声明式放行 + 配图占位）**：默认 `pictures=0`（表格为原生 table、文字为原生文本框，全部可就地编辑）；**仅当模型显式声明 `section.image` / `split.left.image` / `split.right.image` 时才导出图片**，且图片数不得超过声明数（`PICTURES_NOT_DECLARED` 硬拦）——图片源只允许 data: 内联或相对路径（外链报 `IMAGE_SRC_EXTERNAL`）。**无素材时用 `image.placeholder` 出配图占位**：原生圆角矩形 + 虚线 + 居中标签（可编辑、`pictures` 不增），交付前替换 `src` 即可；版式/比例/图注位置已由 `imageSpec` 锁死。
+6. **自适应排版（有限缩字号）**：每个文本块按可用高度在字号阶梯里选"装得下"的最大值；内容偏多时按 `containers.fontShrink` **有限下探**（最多 4 档，floor：presentation/architecture 10pt、research 9pt）。优先顺序：列表化/精炼 → 换/扩组合或拆页 → 最后才缩字号。表格行高按可用高度计算，列表/泳道/矩阵/卡片行高随容器收敛——保证不越界、不重叠；`fitFont` 与 `estTextH` 在 `build_pptx.js`（交付）与 `pptx-export.js`（预览）中同算法，两通道排版一致。
+7. **版面安全边界**：所有页型几何来自 `layout-constants.json` 的 `pageTypes`；内容安全下界 `layout.contentBottom`（有 so-what/来源行时收紧为 `contentBottomWithNote`）。校验器对越界（`SHAPE_OUTSIDE_SLIDE`）、负坐标、非正尺寸、文本溢出估算、字号下限、未声明图片数一律拦截。
+8. **图标路标（PPTX 通道）**：HTML 内联 SVG 图标不跨通道。PPTX 卡片头渲染 **accent 小方块路标**（与 `.card__ico` accent 底同语义），要点列表用 accent 实心方块标记——保持「路标不是装饰」的可扫读性，且全为原生形状可编辑。模型不携带 icon ID。
+
+> A 通道预览引擎（`pptx-export.js`）保持形状渲染作浏览器缩略：**版式与文本所见即所得**；带数据的原生图表在交付 PPTX 中为真 chart part（双击可编辑数据），预览侧为形状近似——**图表形态以精导产物为准**。`cross_verify` 对图表文本做归一化比对（类别标签并入、纯数值 token 过滤），双通道语义一致。
+
+## 版式与质量如何保证
+
+1. **同源**：模型从报告抽取（含一致性抽查），PPTX 内容与页面不会走样；改报告就重新抽模型。
+2. **双单源**：两通道共用 `layout-constants.json`（页面几何 `pw/ph/mx`、**12 列网格 `grid`**、**语义字阶 `typography` C0–T14**、三模式排版比例尺、页型几何、**9 风格 token × 亮暗**、**图表登记四元组 `charts.registry`**、**容器内边距 `containers`**、**锚点容差 `anchorTolerance`**、**图片准入门 `imageAdmission`**、**图片规格 `imageSpec`（版式/比例/建议尺寸/占位标签/体积上限）**、**深度模式 `deepMode`**）与 `model-schema.json`（**29 页型 DSL + chartTypes + chartDataTable 策略**）；`sync_runtime.py` 注入并校验（含页型四件套、图表登记四元组、语义字阶 role、**图片版式↔比例锁定类↔双引擎实现**四项完整性），杜绝漂移。
+3. **同版式**：锁定版式库——HTML 组件与 PPTX 页型成对出现（`components.md` §36d/§37–38b/§39–42/§47–50 ↔ 页型表）；不允许临场发明结构（锁定版式纪律）。**新增页型四件套**：schema 条目 + 几何常量 + 双引擎渲染（`build_pptx.js` 与 `pptx-export.js` 角度/坐标规则严格一致）+ 样例与校验断言，缺一不可。
+4. **双硬门槛**：信息结构可编辑（原生文本框/形状/表格；图片默认 0、声明式放行）+ 视觉语义保真（页型几何同源映射）；结构重排优先于缩字号，缩字号仅限 `fontShrink` 有限下探。
+5. **硬门禁**：`validate_pptx.py --strict` 检查非法尺寸、越界元素、字体下限、未声明图片数、覆盖率、信息密度、**按类型的原生图表断言（`MODEL_CHART_COUNT`）**、**数据表落位（`MODEL_CHART_DATATABLE`）**，0/0 才交付。
+6. **断点可恢复**：REPORT_MODEL 即"恢复锚点"——上下文中断后重跑 extract→build 即恢复，不重新生成。
+
+## 回归双裁判（维护工具 · 页面不使用）
+
+`scripts/gen_channel_a.js` 在 Node 侧加载页面预览运行时（`assets/pptx-export.js`）并组装完整 PPTX 包（打包骨架在此）——产出与页面预览同引擎、与通道 B 同模型，用于：
+
+- `validate_pptx.py --strict` 双通道产物均 0/0
+- `cross_verify.py`（python-pptx 第三方裁判）：A/B 产物均可被 python-pptx 严格解析且逐页文本一致（段间 `\n` vs breakLine `\n\n` 已归一）
+- **改 `pptx-export.js` / `build_pptx.js` 序列化骨架后必跑**（历史踩坑：rels 路径与 `a:graphic` 命名空间两处 OOXML 规范缺陷即由该双裁判暴露）
+- `probe_image_export.py`（素材图片探针）：示例矩阵刻意保持 `pictures=0` 基线，**真实素材图片的路径解析 / half·grid 版式 / cover·contain 裁切 / 声明式放行门禁靠本探针覆盖**——用 `assets/` 下的主题总览图构造最小模型，断言 strict 0/0 且 `pictures == 声明数`。`regression.py` 已自动纳入。
+
+## 路径 C · 渲染回归（可选，需本机 PowerPoint）
+
+对单页视觉还原度要求极高时：用 PowerPoint COM 导出 PNG 逐页对照 HTML。**可选质量增强，不是交付硬门禁**（环境依赖重）。日常覆盖：页面预览模态已提供 WYSIWYG 对照。
+
+## 质量门禁（闭环）
+
+| 产物 | 校验工具（均在本技能内） | 通过标准 |
+|------|---------|---------|
+| HTML 报告 | `scripts/validate_report.py <报告.html>` | 全 PASS（模式感知预算 + 页高模型与溢出估算 + 模型一致性 + 页型↔版式对应 + 锚点闭环 + 图表登记与最小尺寸 + Exhibit 连续性 + **强调带约束/待核实标注/素材图片（零外链·alt·版式与比例锁定类对应·占位可见标签·内联体积）** + 预览配套断言） |
+| PPTX（精导交付） | `scripts/validate_pptx.py <报告.pptx> --strict --model=<报告.model.json>` | 0 errors / 0 warnings（含**模型往返保真**、**按类型原生图表硬门禁**、**数据表落位**、**越界/文本溢出/未声明图片**、**图片版式·裁切·多图数量·相对路径文件存在性**） |
+| 素材图片（真实位图） | `scripts/probe_image_export.py` | build→strict 0/0 且 `pictures == 声明数`（示例矩阵零图片，真实素材路径/版式靠本探针覆盖） |
+| 素材准备（用户图片） | `scripts/prepare_images.py <图片\|目录>` | 产出 `.media` HTML 片段 + `image` 模型对象；超体积自动转相对路径；低于建议分辨率给出提示 |
+| PPTX（A 通道回归产物） | 同上 strict 裁判 + `scripts/cross_verify.py`（python-pptx 第三方裁判） | A/B 产物均可被 python-pptx 严格解析、逐页文本一致（图表类别与数值 token 已对称归一化）、B 通道原生图表数值与模型一致 |
+| 风格与单源（改色/改常量后） | `scripts/audit_styles.py` | 9 风格 × light/dark × WCAG 配对全达标 + engine.css ↔ layout-constants.json 双源一致 + **单源完整性**（styleAccents 覆盖 / charts 登记表自洽 / 校验预算键齐全） |
+| 常量 / schema / 页型四件套 / 图表四元组 | `scripts/sync_runtime.py` | 注入成功 + 双端引用校验 PASS + **每个 schema 页型都有几何映射** + **charts.types ↔ registry 双向一致** + **非原生图表 dataTable 不为 off** + 语义字阶 role 存在 + 哈希摘要一致 |
+| 交付说明 | `scripts/quality_gate.py 报告.html --deliver` | 文件与体积、模式、风格、篇幅、交付格式、校验结论与引用条数**七要素齐备即过**，缺一即 FAIL——**不要手拼** |
+
+> **双裁判教训**：手写序列化器与自研校验器同源存在盲区——PowerPoint 宽容掩盖了两处 OOXML 规范缺陷（presentation 的 rels 须在 `ppt/_rels/presentation.xml.rels`；`p:graphicFrame` 内 graphic 元素须用 `a:graphic` 命名空间），由 python-pptx 严格解析暴露并修复。
+> **渲染冒烟（可选路径 C 开源版）**：`soffice --headless --convert-to pdf <报告.pptx>`（LibreOffice，保真度约 85%）；本机未装可跳过，strict + python-pptx 双裁判已覆盖结构与可解析性。
+
+## 环境备注（外部依赖仅两个，均已说明）
+
+- **Node + pptxgenjs**：仅精导通道与回归双裁判需要。在技能目录执行 `npm install pptxgenjs`，或把 `NODE_PATH` 指向任意已含 pptxgenjs 的 node_modules；`regression.py` 会自动探测（`TOP_PPT_NODE_PATH` / `NODE_PATH` / 仓库内 node_modules / 全局 npm root）。
+- **Python（标准库）**：跑 `validate_report.py` / `validate_pptx.py` / `extract_model.py`（读 `model-schema.json` 单源）/ `sync_runtime.py` / `audit_styles.py`，无第三方依赖；`cross_verify.py` 可选依赖 python-pptx（未装则自动跳过该第三方裁判，不影响交付判定）。
+- 页面预览运行时零依赖（浏览器纯序列化，无 ZIP 打包）。

package/top-ppt-html/references/reform-plan.md

@@ -0,0 +1,252 @@
+# 整体整改方案（质量 · 性能 · 可靠）
+
+> **何时读**：改技能架构、门禁、图表选型、图文版式、导出链路前必读。
+> **定位**：质量整改方案——诊断根因、收敛复杂度、重建门禁、布局语法、演讲向图文模式、模型单写。
+> **状态**：P0/P1 已落地并随 **0.1.0** 发布；P2 见文末。
+> **原则**：先保决策信息，再谈美观；门禁抓真缺陷，不为过检堆规则；单源可验证，双写可收敛。
+
+---
+
+## 〇、问题现象 ↔ 根因对照
+
+| 现象（用户截图） | 直接原因 | 系统根因 |
+|-----------------|---------|---------|
+| 正文出现 `<a class="cite">…</a>` 字面量 | 填内容时把 HTML 源码当纯文本写入 | **双写无净化**：HTML 正文与 `REPORT_MODEL` 各自维护，模型字段未禁止标签；校验只匹配「正确 markup」，不拦「标签泄漏」 |
+| 除标题外大面积空白 | 页高模型强制 `min-height:100vh` + 内容不足 | **过空页仅 WARN**；`empty` 阈值 80–120 字过松；组合版式只强制 research |
+| 文字输出不全 / 截断 | `fitFont` 触底后仍裁切；模型-正文只对标题 | **保真阈值 50%**（`hits*2 < probes`）放行半页缺失；正文长度不校验 |
+| 环图标签叠字（0.5 / 0%） | 手写 SVG 标签框过窄换行；或 0.5% 与百分比串叠放 | **绕过锁定组件**：自由 SVG 无标签盒/避让规则；极小扇区仍用 donut |
+| 简单图占一整页「大图」 | presentation 契约写「1 张大图」；`minSize` 只有下限 | **设定错误**：无「信息复杂度 ↔ 面积」上限；`imageAdmission` 是死配置 |
+| 架构/流程图难看 | PPTX `diagram` 只有等高层带 + 小矩形连接件 | **结构图退化**：无真边/正交路由/菱形判断；A3 管线被压成单泳道 |
+| HTML 略好但仍有问题 | 同一套填内容习惯 + 同一套门禁假过 | 双通道同源缺陷，HTML 只是 CSS 稍好掩盖了结构问题 |
+
+**一句话诊断**：**基本设定过宽 + 双写失控 + 门禁假过 + 过度工程化导致填内容时绕过组件**。不是「再加几条校验」能了事，需要收敛复杂度并重建质量底线。
+
+---
+
+## 一、基本设定哪里不对
+
+### 1.1 演示模式「1 张大图」是错误默认
+
+| 原设定 | 问题 | 新设定 |
+|--------|------|--------|
+| presentation 每页 1 张大图 | 简单 2 类占比也被做成整页 donut | **按信息复杂度定面积**：≤2 类且极偏 → KPI 大数；3–5 类中等 → 图 + 注解带；复杂结构才全幅 |
+| `charts.minSize` 只有下限 | 图可以无限大，与内容量脱钩 | 增加 **`charts.sizeByComplexity`**：数据点/类别数决定推荐区间，超出上/下限 WARN→FAIL |
+| 全幅图页 `fig--full` 随手可用 | 「简单图放大」合法化 | 全幅仅允许：架构总览 / ≥8 节点结构 / ≥8 系列趋势 / 用户指定素材大图 |
+
+### 1.2 图文模式缺「演讲构图」契约
+
+现有 `image` 页型只有六版式（full/half/bleed/grid/compare/wall），**没有演讲向的「主视觉 + 口头注解」节奏**。新增 **图文演讲版式（V1–V4）**，见 §四。
+
+### 1.3 内容双写没有唯一事实源
+
+- HTML 正文手写 + `REPORT_MODEL` 手写 → 必然漂移（标签泄漏、空页、截断的温床）。
+- **v9 方向**：`REPORT_MODEL` 为内容唯一源；HTML 由「锁定组件 + 模型字段」填充，禁止把 HTML 标签写进模型字符串字段。
+- **过渡（本版立即执行）**：模型字段净化 + 标签泄漏硬门禁 + 一致性按段落覆盖率（≥80%）而非 50%。
+
+---
+
+## 二、是否过度工程化？——是，且在制造缺陷
+
+### 2.1 复杂度清单（现状）
+
+| 层 | 规模 | 缺陷贡献 |
+|----|------|---------|
+| 页型 | 29 种 | scaffold/引擎/schema 三方易漂（已抓到 **cards 契约错**：scaffold 出 `[[k,v]]`，引擎要 `{title,points}`） |
+| 图表 | 36 登记 / 30 chart.type | 形状通道 20 类是缺陷农场；A/B 双引擎近 4k 行重复 |
+| 单源 JSON | 5 份 | `sync_runtime` 注入链一断就静默不一致 |
+| 门禁码 | 40+ | 关键码不在 `STRICT_FAILURE_CODES`，**假过** |
+| 文档 L2 | 20+ 文件 | 生成时读不完 → 绕过锁定组件自由发挥 |
+
+### 2.2 收敛原则（v9）
+
+1. **默认生成面收窄**：演示/研究默认 **12 页型 + 12 图表**；其余标「高级/按需」，不进默认选型表。
+2. **双引擎职责砍半**：B 通道（`build_pptx.js`）是唯一交付；A 通道只做缩略预览，**不再要求逐页文本全等**（改为「标题 + 主文本 ≥80%」）。
+3. **单源合并**：`layout_slots.json` 并入 `layout-constants.json`；`regionOf` 只保留 `lib_layout_regions.js` 一份。
+4. **门禁只保留会改变交付决策的**：装饰性/节奏类降为报告；见 §三。
+5. **文档**：L1 playbook 含「演讲图文构图 + 图表面积规则」；失败模式从 16 类压到 **10 类硬缺陷**。
+
+### 2.3 明确不砍
+
+- 原生可编辑 PPTX（`pictures=0`）——产品差异点。
+- 亮暗双主题 + 9 风格——皮肤层，不制造内容缺陷。
+- 双单源常量（几何/字阶）——版式可复现的基础。
+- 负向测试（`negative_tests.py`）——防止门禁退化。
+
+---
+
+## 三、质量门禁重建（抓截图级真缺陷）
+
+### 3.1 新硬门禁（strict 必拦）
+
+| 码 | 判据 | 对应现象 |
+|----|------|---------|
+| `HTML_TAG_IN_TEXT` | 可见文本剥离后仍含 `<a ` / `</a>` / `class="cite"` / `href=` / `<strong` 等 | 标签泄漏 |
+| `TITLE_ONLY_PAGE` | 去掉页头后正文 < 40 字且承载组件 = 0 | 空白内容页 |
+| `UNDERFILL_PAGE` | 承载 < 2 且非金句/章节幕/收尾 | 半空页 |
+| `TEXT_INCOMPLETE` | 模型字段与 PPTX/HTML 文本长度比 < 0.8，或句末无标点且长度截断 | 文字不全 |
+| `CHART_SKEW_INVALID` | donut/pie 最小扇区 < 5% 或类别 = 2 且 max/min > 20 | 环图叠字/不可读 |
+| `CHART_OVERSIZE` | 简单图（≤3 点或 ≤2 类）占内容区 > 55% | 简单大图 |
+| `IMAGE_SIMPLE_CONTENT` | `imageAdmission.forbidden` 语义被图片化（简单流程/柱状/表格截图） | 简单图当大图 |
+| `STRUCTURE_DEGRADED` | 含分支/判断语义却只有 `→` 文本箭头或空 `.arch` | 架构图难看 |
+
+### 3.2 升级为 strict（原 WARN）
+
+- `LOW_TEXT_DENSITY` / `LOW_CONTENT_DENSITY` / `EMPTY_OR_UNMEASURABLE_SLIDE`
+- `UNBALANCED_EMPTY_SPACE`（**任一轴**留白 > 0.28，不再要求右+下同时）
+- `UNJUSTIFIED_LARGE_IMAGE`（面积 ≥ 40% 且不在 allowed）
+- `TEXT_OVERFLOW_ESTIMATE`
+- `MODEL_ROUNDTRIP_CONTENT_MISSING`（阈值 50% → **80%**）
+
+### 3.3 降级为报告（不挡交付）
+
+- 图表多样性类型数下限、相邻同型、版式节奏连用、research 标题判断词正则
+- rubric 启发式 tone 维
+- CSS 死类、风格 WCAG 微调
+
+> **理由**：截图里没有一例是「图表不够多样」造成的；全是空白、泄漏、截断、失衡、错误选型。门禁预算应砸在后者。
+
+### 3.4 负向测试新增（`negative_tests.py`）
+
+N15 标签泄漏 · N16 标题空页 · N17 极偏 donut · N18 简单图超大 · N19 正文截断 50% · N20 cards 元组契约
+
+---
+
+## 四、图文演讲模式（美观 · 合理 · 可讲）
+
+> 目标：**3 秒看清主张，30 秒讲完证据**。不是「配图好看的报告」，是「台上能指着讲的材料」。
+
+### 4.1 构图契约（V1–V4）
+
+| 版式 | 结构 | 适用 | 面积比（视觉 : 注解） |
+|------|------|------|----------------------|
+| **V1 主视觉 + 右侧注解** | 图/照片 55–60% · 3–4 条要点 + 1 句 so-what | 产品、场景、对比图 | 6:4 |
+| **V2 上图下带** | 通栏图 50–55% · 下方指标带/三卡 | 总览 → 分解 | 55:45 |
+| **V3 大数 + 佐证图** | KPI 40% · 小图/迷你表 35% · 口径 25% | 极偏占比、单点结论 | 不用 donut |
+| **V4 双图对照** | A/B 各 40% · 中缝结论条 20% | 前后、方案、竞品 | 8:2 |
+
+### 4.2 硬规则
+
+1. **简单数据禁止全幅图**：≤2 类占比、单指标进度 → **V3**；全幅留给结构/全景/素材。
+2. **图旁必须有口头注解**：3–4 条，每条 ≤2 行；禁止「一张图 + 标题」独页（金句/章节幕除外）。
+3. **标签不进扇区内部**：环图/饼图数值放**图例行**或**引出线**，禁止叠在弧上（治叠字）。
+4. **极偏数据换形态**：min/max ≥ 20 或 min 扇区 < 5% → KPI / 进度条 / 对比条，**禁 donut/pie**。
+5. **图注与来源沉底**：`caption` 一行 + `footnote` 口径；不进主视觉。
+6. **照片 vs 图表**：情绪/场景用照片（`media`）；比较/趋势/构成用内联 SVG；**简单图表永不截图**。
+7. **演讲节奏页**：每 4–6 页插 V3/金句/指标带，避免连续密排。
+
+### 4.3 与三模式关系
+
+- **A presentation**：默认走 V1–V4；「1 张大图」废除。
+- **B research**：保留密排，但证据页主图仍受 `CHART_SKEW_INVALID` / `CHART_OVERSIZE` 约束。
+- **C architecture**：图为王不变，但必须真结构（边/分支/泳道），禁止文字箭头退化。
+
+---
+
+## 四-b、布局语法（核心：每页整齐优雅）
+
+> 详规见 **`references/layout-grammar.md`**。本节是方案层摘要。
+
+### 4.b.1 为什么要预设网格/骨架
+
+自由排版是「不整齐」的根因：左缘漂移、间距游离、双视觉重心、半空页。v9 规定：
+
+1. **12 列网格强制**（PPTX `grid.x[]` ↔ HTML 栅格类同源）。
+2. **预设骨架 P1–P12**：内容先选骨架再填，禁止临场发明栅格。
+3. **三层槽位**：Chrome / Primary / Secondary / Annotation，面积比 22/55/20/18 量级。
+4. **间距只准 token**（`--sp-*` / `--gap` / `containers.pad`）。
+
+### 4.b.2 骨架一览（与 V1–V4 对齐）
+
+| 演讲图文 | 骨架 | 列比 | 权重 |
+|----------|------|------|------|
+| V1 主视觉+注解 | P1 | 7:5 | 60:40 |
+| V2 上图下带 | P2 | 12+4/4/4 | 55:45 |
+| V3 大数佐证 | P3 | 5:7 | 45:55 |
+| V4 双图对照 | P4 | 6:6 | 50:50 |
+| 三栏/四象限/拼贴/全幅 | P5/P6/P10/P9 | … | 见 grammar |
+
+### 4.b.3 元素级优雅标准（摘要）
+
+| 元素 | 整齐关键 |
+|------|----------|
+| 图标 | 仅 16/20/24；光学对齐 x-height；图文距 8px |
+| 列表 | 项 ≤2 行；项距 12；加粗结论同一文本框 |
+| 卡片 | 等高 stretch；内边距一致；禁空卡 |
+| 指标 | 数字基线对齐；单位 45% 字号 |
+| 图表 | 标签不叠弧；标签盒防换行；环径 ≤ 内容高 45% |
+| 图文 | 比例锁；顶边对齐；图注在下 |
+| 结构图 | 正交边+箭头；同层等高；禁裸 `→` |
+
+### 4.b.4 留白与填充率
+
+- presentation Body 填充 **62–78%**；research 70–85%；architecture 图 75–90%。
+- 合法空页仅：章节幕 / 金句 / 收尾。
+- 门禁：`LAYOUT_FILL_*` / `LAYOUT_MULTI_FOCUS` / `LAYOUT_ALIGN_DRIFT` / `LAYOUT_SPACING_OFF_TOKEN`。
+
+### 4.b.5 排版总序
+
+**角色 → 骨架 P__ → 元素落位 → 间距 token → 对齐/留白 → LAYOUT_* 门禁**。禁止跳步直接堆组件。
+
+---
+
+## 五、可靠性与性能
+
+| 项 | 现状 | v9 |
+|----|------|-----|
+| 生成失败 | 缺字段只 console.warn | `extract_model` 缺关键字段 → 非 0；`build_pptx` 空页计入 strict |
+| 校验耗时 | 多脚本手跑 | **`quality_gate.py` 一键** = validate_report + validate_pptx + 新硬门禁 + deliver |
+| 预览 | A 通道全页 OOXML | 缩略级即可；交付只认 B |
+| 回归 | `regression.py` 全量 | 保留；示例矩阵覆盖新硬门禁负例 |
+| 文档体积 | L2 易爆 | 默认只读 SKILL + playbook；新规则进 playbook §六 |
+
+---
+
+## 六、分阶段落地
+
+### P0（本迭代 · 必须）——已落地
+
+1. 门禁：`HTML_TAG_IN_TEXT` / `TITLE_ONLY_PAGE` / 极偏 donut / 简单图超大 / 正文保真 ≥80%
+2. 升级 empty / unbalanced / large-image / overflow 为 strict
+3. 修复 **scaffold cards** 契约 → `{title, points}`
+4. `extract_model` 模型字段 **strip HTML 标签**（cite 只允许模型侧 `[n]` 纯文本）
+5. playbook + content-rules 写入 **V1–V4 图文演讲契约** 与 **图表面积/极偏规则**
+6. `layout-constants` 增加 `qualityGates` / `charts.sizeByComplexity` / **`layoutSystem`（P1–P12）**
+7. **`layout-grammar.md` + `LAYOUT_*` 门禁**（骨架/单重心/对齐/间距/填充率）
+8. 负向测试 N15–N17
+
+### P1（下一迭代）——大部分落地
+
+1. **骨架 P1–P12 进 scaffold**（`data-skel` + `layoutPreset` + 打印骨架序列）
+2. **默认图表收敛 8 核心**（`layoutSystem.defaultCharts`）；高级图型标 advanced
+3. **A/B 文本保真 80%**（`cross_verify` 覆盖率，不再要求逐字全等）
+4. **泳道/层间正交箭头**（HTML `.lane__arr`/`.arch__conn` + PPTX line+triangle）
+5. **布局 IR 单源**：`layoutSlots` 并入 `layout-constants`（`lib_layout_regions` 优先读 LC）
+6. **模型驱动生成**：`render_from_model.py`（只填 REPORT_MODEL → 回填 HTML）；图/exhibit scaffold 强制 P8 主从
+
+### P2（后续增强）
+
+1. 渲染对照纳入 quality_gate（有 LibreOffice 时）
+2. 视觉基线（示例截图 diff）
+3. ~~发布 0.1.0 + CHANGELOG~~ **已完成**
+
+---
+
+## 七、验收标准（Definition of Done）
+
+- [x] 截图四类问题（标签泄漏 / 空白 / 截断 / 简单大图）在负向测试中 **全部被 FAIL 抓住**
+- [x] 示例矩阵 9 份 `validate_report` 全绿（0 FAIL）
+- [x] 模型单写样张：`render_from_model` 产出 0 硬缺陷
+- [ ] PPTX 全链：`regression.py`（含 Node 环境时）`validate_pptx --strict` 0/0
+- [x] 文档：playbook/layout-grammar 含新契约；failure-modes 与错误码对齐
+
+---
+
+## 八、决策摘要（给评审）
+
+1. **设定要改**：废除「演示 = 1 张大图」；图表面积跟信息复杂度走；极偏数据禁环图。
+2. **复杂度要砍**：默认 12 页型 + 12 图表；双引擎砍半；门禁从 40+ 装饰项收敛到 **8 个真缺陷硬门禁**。
+3. **双写要收**：模型字段禁 HTML；一致性 80%；中期模型驱动生成。
+4. **图文要有演讲构图**：V1–V4，主视觉 + 口头注解，简单数据用大数不用整页图。
+5. **质量靠门禁不靠自觉**：截图级缺陷必须 FAIL，负向测试锁死。
+
+> 整改顺序永远是：**补证据含义 → 改承载形态 → 调容器网格 → 有限缩字号 → 拆页**。禁止用装饰、放大图、砍口径过检。