@topmindspace/tms-skills 2.0.0 → 2.0.2

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

@@ -1,252 +1,252 @@
-# 整体整改方案 v9（质量 · 性能 · 可靠）
-
-> **何时读**：改技能架构、门禁、图表选型、图文版式、导出链路前必读。
-> **定位**：v9 质量整改方案——诊断根因、收敛复杂度、重建门禁、布局语法、演讲向图文模式、模型单写。
-> **状态**：P0/P1 已落地并随 **v9.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. ~~发布 v9.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，负向测试锁死。
-
-> 整改顺序永远是：**补证据含义 → 改承载形态 → 调容器网格 → 有限缩字号 → 拆页**。禁止用装饰、放大图、砍口径过检。
+# 整体整改方案 v9（质量 · 性能 · 可靠）
+
+> **何时读**：改技能架构、门禁、图表选型、图文版式、导出链路前必读。
+> **定位**：v9 质量整改方案——诊断根因、收敛复杂度、重建门禁、布局语法、演讲向图文模式、模型单写。
+> **状态**：P0/P1 已落地并随 **v9.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. ~~发布 v9.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，负向测试锁死。
+
+> 整改顺序永远是：**补证据含义 → 改承载形态 → 调容器网格 → 有限缩字号 → 拆页**。禁止用装饰、放大图、砍口径过检。