@topmindspace/tms-skills 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,7 +1,68 @@
+## Unreleased
+
+## 0.1.2 — 2026-09-24
+
+### top-ppt-html · P2 cleanup（advanced 按需 · Mode A 次级骨架 · icons 压缩）
+
+- **Advanced charts 按需**：默认读面 = `charts-discipline` + 核图 8；`charts-extended.md` **禁止预读**，仅意图命中 `extract_snippet.py --chart`。`charts.variety.preferCoreFirst` + validate WARN（A/B）；advanced **计入** `minTypes`（不降 `presentation=4`，不缩 registry）。
+- **Mode A 骨架分层**：主力 P1–P4+P6/P10；次级 P7–P9/P11–P12（`layoutSystem.modeSkels` + layout-grammar / default-surface / recommend_layout 同口径）；画廊侧重主力。
+- **icons.md 压缩**：语义表 + 禁区 + 尺寸档 + 高频 20 SVG（~8.7KB）；完整枚举 → `docs/archive/refs/icons-catalog.md`；package 仍 REQUIRED。
+- **docs 对齐**：SKILL / playbook / presentation-craft / modes / charts 门面同步；Fast Mode + 长文溢出序保持不变。
+
+### Installer
+
+- 安装器 `@topmindspace/tms-skills` → **0.1.2**（随技能包内容更新）。
+
+
+
+### top-ppt-html · Long-text / Quality round（反截断 + 门禁加深）
+
+- **反截断政策**：Mode A / content-rules / presentation-craft「长文与信息承载」——溢出顺序固定为 重构→拆页/分章→换形态→有限 fontShrink；**禁止**静默截断 / 砍 so-what / 为疏朗删实质。单页字数改预警（presentation char 1800），不为「字多」单独 FAIL。
+- **结构引导取代硬砍刀**：列表/卡片 `maxItemChars` 等改为引导 + prefer；checklist 同步。
+- **layout-qa 加深**：`LAYOUT_QA_TRUNCATION` / `OVERFLOW_NO_SPLIT` / `HALF_EMPTY` / `ALIGN_RHYTHM`；presentation `--strict` 仍自动 layout-qa。负例 L4–L6。
+- **recommend_layout**：高容量意图 → 多页序列（议程→主张→证据卡→明细），禁一页塞爆。
+- **P1-3 charts facade**：纪律优先 → 核图 8 → extended 按需；**不降** `minTypes.presentation=4`。
+- **P1-4 会场字号**：pptx-export venue 表（小会议室 / 默认 / 礼堂）。
+- **P1-6 chrome**：跨页页脚 y 漂移 `CHROME_DRIFT` WARN + 文档说明。
+
+### top-ppt-html · Presentation Craft（Mode A 工艺）
+
+- **P0-1 图表多样性（用户明确保留）**：**不降** `minTypes.presentation`（仍为 **4**）；registry/advanced 图种保留。纪律改为「按内容选型拉开多样」+ 禁反模式（简单全幅 / 极偏 donut / 为过门禁硬上冷门图）；playbook §五 / layout-qa 同步。
+- **P0-2 default-surface**：升为 Mode A / Fast 演示主读面（12 页型 + 8 核图 + V1–V4；P5–P12/advanced 按需）；SKILL L2 索引指向。
+- **P0-3 layout-qa 默认**：`validate_report --strict` 在 presentation 下自动 `--layout-qa`；`quality_gate` 同口径；B/C 不强制。
+- **P0-4 主张标题**：Mode A action/claim title（禁话题标签）写入 content-rules / modes；校验 WARN。
+- **P0-5 `presentation-craft.md`**：中英术语一页纸清单（one idea / 3s / whitespace / CRAP / motion=none / WCAG…）；package REQUIRED。
+- **P1**：fillTarget A 58–75% + intentional whitespace 豁免；`recommend_layout` 偏 V1–V4、降 donut 默认权重；Fast 路演/汇报/发布/演讲/demo→A；motion=none 铁律短句。
+
+### top-ppt-html · Batch 3（瘦身）
+
+- **归档 L2**：`industry-benchmark.md` / `design-system-engine.md` → `docs/archive/refs/`（生成路径不读）。
+- **layoutSlots 单源**：删除 `scripts/layout_slots.json`；`lib_layout_regions.js` / `sync_runtime.py` 只读 `layout-constants.layoutSlots`。
+- **示例**：`assets/examples/` 仅留 3 份黄金样张（每模式 1）；其余 → `docs/archive/examples/`；`build_examples.py` 瘦身为自检（全量脚本归档）。
+- **主题 PNG**：`theme-overview*.png` 量化压缩约 −70%。
+- **default-surface.md**：12 页型 + 8 图 + V1–V4 速查；playbook §五标注默认 8 核心图。
+- **package**：MIN refs ≥20、examples ≥3；`recommend_layout.py` 入 REQUIRED；README 缩为安装+命令索引。
+
+### top-ppt-html · Batch 2（布局选型 + layout-qa + PPTX 对齐）
+
+- **recommend_layout.py**：`--mode A|B|C` + `--intent` / `--from-model` / `--stdin` → `{pageType,skel,chart,rationale,v?}`（V1–V4 / 极偏禁 donut / sizeByComplexity）。
+- **validate_report.py --layout-qa**：缺 data-skel、连续同骨架、极偏 donut、演示简单全幅、V 契约；negative_tests 增 L1–L3。
+- **cross_verify.py** 默认 SKIP，`--full-ab` 才跑；regression 同口径。
+- **build_pptx.js** 尊重 `layoutPreset`（缺省由 pageToPreset 回填，写入备注）。
+- **smoke_pptx.sh** + CI skill-gates 冒烟：extract_model → build_pptx → validate_pptx --strict。
+
 # Changelog
 
 ## Unreleased
 
+### top-ppt-html 0.1.1 — Batch 1（工作流单写 · Fast Mode）
+
+- **模型单写统一**：playbook / SKILL / pptx-export 命令链均为 scaffold → 只填 `REPORT_MODEL` → `render_from_model --inplace` → `validate_report --strict`（禁 HTML/模型双写）。
+- **`render_from_model.py` 纳入 package REQUIRED**；references 最小篇数注释对齐实有数量（≥24）。
+- **Fast Mode**：触发词跳过 Gate 0 + 六项；默认 B/mckinsey/light 等；标准路径仍为硬门禁；`audit_skill` 适配豁免声明。
+- **归档** `references/reform-plan.md` → `docs/archive/reform-plan.md`；硬门禁改指 `qualityGates` + `failure-modes`。
+- 技能 `package.json` 版本对齐仓库叙事 `0.1.1`（LC 仍为 `0.1`）。
+
 ## 0.1.1 — 2026-09-24
 
 ### Fixes (P0 / P1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topmindspace/tms-skills",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "TopMindspace 智能体技能 monorepo — 通过 npm / GitHub npx 安装技能（top-ppt-html 等）。",
   "license": "MIT",
   "author": "TopMindspace",

package/top-ppt-html/README.md

@@ -89,7 +89,7 @@ top-ppt-html/
 ├─ assets/                      #                                           │ 且
 │  ├─ templates/                #   三份模式模板（presentation/research/architecture）  │ 入库
 │  │                            #   + engine.css / ui.js（公共引擎/UI，sync_runtime 注入源）
-│  ├─ examples/                 #   9 份示例 + 9 份 REPORT_MODEL（复制起点 · 覆盖全部 9 风格）   │
+│  ├─ examples/                 #   3 份黄金样张 + model（每模式 1；风格见 style-gallery）      │
 │  ├─ pptx-export.js            #   PPTX 预览运行时（含常量/schema 注入块）   │
 │  ├─ style-gallery.html        #   风格 × 模式 × 亮暗主题交互画廊            │
 │  └─ theme-overview*.png       #   3 张主题参考图（整体=演示 / 研究 / 架构）  │
@@ -101,14 +101,14 @@ top-ppt-html/
 │  ├─ layouts-combo.md          #   §32–§34/§39–§50 组合与选型表 §46              │
 │  ├─ charts.md                 #   逻辑索引（图表 § 路由）                       │
 │  ├─ charts-basic.md           #   §16–§35 基础图表代码                          │
-│  ├─ charts-extended.md        #   §52–§70 扩展图表代码                          │
+│  ├─ charts-extended.md        #   §52–§70 advanced（意图命中才读，禁预读）        │
 │  ├─ charts-discipline.md      #   §64/§66 误用与多样性纪律                      │
 │  ├─ infographics.md           #   铁律与边界（逻辑入口）；代码已拆分见下两行          │
 │  ├─ infographics-stats.md     #   统计图形族 §1–§6 / §71–§77                        │
 │  ├─ infographics-structure.md #   结构图形族 §78–§82                                │
-│  └─ …（modes / styles / design-system + design-system-engine / content-rules / icons /  │
+│  └─ …（modes / styles / design-system / content-rules / icons / default-surface /     │
 │        outline-design / pptx-export / high-fidelity /                               │
-│        failure-modes / tech-design / industry-benchmark）                            │
+│        failure-modes / tech-design；归档见 docs/archive/refs/）                         │
 ├─ evals/                       # Eval 框架（结果/过程/风格/效率四类目标）    │
 │  ├─ prompts.csv               #   14 条 prompt（显式/隐式/上下文/负对照）   │
 │  ├─ rubric.schema.json        #   风格目标结构化评分契约                    │
@@ -120,135 +120,43 @@ top-ppt-html/
 └─ （本地状态目录）                      # IDE / 智能体本地状态                  ← 不进包、不入库
 ```
 
-**口径**：`assets/`（输出用素材）+ `references/`（按需加载规范）+ `scripts/`（确定性工具）构成官方规范的三类打包资源；`dist/`、依赖、缓存、IDE/智能体本地状态目录、`scripts/_*` 一律不进包也不入库（与 `.gitignore` 同口径，由 `package_skill.py` 校验）。
+---
 
-## 四、开发指南
+## 常用命令（细节见 `references/playbook.md`）
 
-### 4.1 脚本清单
-
-| 脚本 | 用途 | 何时跑 |
-|------|------|--------|
-| `env_probe.py` | **公共环境探测模块**（Node 可执行文件 / 含 pptxgenjs 的 node_modules / python-pptx 可用性；统一解析优先级与安装指引，被 regression / probe_image_export 复用，杜绝各写一份） | 无需单独跑；`python scripts/env_probe.py` 可自检 |
-| `sync_runtime.py` | 常量/schema 双注入（pptx-export.js 常量块 + 三模板引擎/UI/运行时内联副本）+ 双端引用与**页型四件套**校验 | **改 layout-constants.json / model-schema.json / engine.css / ui.js / pptx-export.js 后必跑** |
-| `audit_styles.py` | 9 风格 × 亮/暗 WCAG 对比度 + engine.css ↔ JSON 双源一致 + **单源完整性**（强调色表 / 图表登记表 / 校验预算键） | 改任何风格色值或常量后必跑 |
-| `audit_docs.py` | **文档一致性审计**：§ 引用可解析性（跨文件稳定编号）+ 文件前缀规范性 + §46 选型表对 36 图表/29 页型全覆盖 + 图表代码节齐备 + 元数据与必需文件 + **任务路由可解析**（TASK_ROUTES 每条路由实际抽取验证） | 改 `references/*` 或拆分规范文件后 |
-| `audit_skill.py` | **技能工程审计（效率预算与门禁）**：SKILL.md（≤13KB）/ L1 playbook / 单份 reference / 模板的体积上限 · description 软硬上限 · 三档披露（L0/L1/L2）· **Gate 0 位于六项问询之前** · 交互轮次与必读文件预算声明 · 引用完整性 · **内容重复（归一化滑窗，含表格/公式/短语）** | 改 `SKILL.md` / `references/*` 后（与 `audit_docs.py` 互补） |
-| `audit_css.py` | **CSS 类覆盖率审计（报告制）**：engine.css 选择器类 ↔ 消费方语料（模板剔除注入镜像 + 示例 + 运行时 + references 代码配方），列出疑似死类供维护者决策 | 删除/新增 engine.css 规则后 |
-| `scaffold_report.py` | **报告骨架生成器**（替代"整份复制模板"）：锁模式/风格/主题 + `data-skel`/`layoutPreset` + REPORT_MODEL；`--plan`/`--preset`/`--list-types` | **每次生成第一步** |
-| `render_from_model.py` | **模型驱动生成**：只填 REPORT_MODEL → `--inplace` 回填 HTML（`[n]`→cite；29 页型渲染器） | 填完模型后 |
-| `extract_snippet.py` | **L2 节级片段抽取**：`--task` 任务路由 / `--chart` 图表代码节 / `--page-type` schema 字段 / `--file --section` 精确节——避免整读 70KB+ 规范 | 取 L2 代码/规范时优先于整文件读 |
-| `lib_layout_regions.js` | **页型布局区域 IR**：槽位 → 英寸矩形（layout_slots + layout-constants 派生）；B 通道 exhibit 已消费 | 改布局 IR 后必跑 sync + regression |
-| `quality_gate.py` | **交付一键质量门禁**：HTML strict + 可选 PPTX strict + evals 确定性 + rubric 启发式五维 + `--deliver` 自动生成七要素交付说明（缺一即 FAIL）+ 分项耗时 | 正式交付前推荐 |
-| `checks_html.py` | **HTML 检查公共库**（承载正则 / 图表通道 / 多样性下限 / 组合版式）——validate_report / quality_gate / run_evals 共用，禁止再手抄 | 被上述脚本 import |
-| `measure_height.py` | **页高与容器裁切真值测量**（可选 · Playwright）：无头浏览器量 band 真实高度 vs 视口，并检测「内容越过归属容器」（静态估算的盲区）；缺依赖自动跳过 | regression 内部 / 排版争议时 |
-| `build_examples.py` | 从模板 + 内容包重建 9 份示例（三模式 × 9 风格全覆盖，含 REPORT_MODEL 与 theme） | 改模板/内容包后 |
-| `validate_report.py` | HTML 质检（三模式预算 + 页高模型与溢出估算 + 模型一致性 + 页型↔版式对应 + 图表登记） | 每份报告交付前（`--strict` 连 WARN 不放过） |
-| `extract_model.py` | 从 HTML 抽取 REPORT_MODEL（自动兜底 style/mode/theme） | 精导第一步 |
-| `build_pptx.js` | PptxGenJS 生成 PPTX（`--model=` 必选，`--style=` / `--theme=light\|dark` 可覆盖） | 精导第二步 |
-| `validate_pptx.py` | PPTX 质检（`--strict` 0/0 硬门禁；`--model` 启用往返保真） | 精导第三步 |
-| `gen_channel_a.js` | A 通道：加载页面预览运行时组装 PPTX（回归双裁判专用） | regression 内部 |
-| `cross_verify.py` | python-pptx 第三方裁判：A/B 产物逐页文本一致 + **B 通道原生图表数值 ↔ 模型一致**（可选依赖，未装则跳过） | regression 内部 |
-| `prepare_images.py` | **用户图片素材准备**（读尺寸/格式/体积 → 按版式建议尺寸缩放压缩 → data: 内联或相对路径 → 产出 `.media` HTML 片段 + `image` 模型对象） | 报告要配用户图片时 |
-| `probe_image_export.py` | **素材图片导出探针**（真实位图 build→strict 0/0 且 `pictures == 声明数`；示例矩阵刻意零图片，真实素材路径/版式/门禁靠它覆盖） | regression 内部 / 改图片相关代码后 |
-| `negative_tests.py` | **门禁反向验证**（故障注入 · 14 例）：往合格产物里埋已知缺陷（Exhibit 漏编号 / 引用错配与跳号 / 备注被剔离 / 图表数值篡改 / 标题鉴别力 / 字号越尺 / 未登记图表类型 / 多样性塌陷 / 图片外链 / tbd 无图例 / 模型主题与模式矛盾 / 锚点断裂），断言门禁必须报错——正向全绿只能证明“没误报”，这里证明“真能报” | regression 内部 / 改校验器后必跑 |
-| `regression.py` | **一键全链路回归**（9 示例 HTML strict + 双通道 PPTX 0/0 + 双裁判交叉一致 + 素材图片探针 + 深色主题探针 + 门禁反向验证 + **任务路由全量遍历** + 浏览器页高/裁切真值） | 任何模板/常量/schema/运行时/示例改动后必跑 |
-| `render_compare.py` | **深度模式渲染对照**（PPTX→PDF→位图 + HTML/PPTX 并排对照 + 偏差登记；缺 LibreOffice 自动跳过） | 深度模式交付时（可选） |
-| `capture_theme_overview.js` | playwright 截图画廊 → 3 张主题参考图（演示态=整体图；带 Tab 断言防雷同） | 改画廊后（可选，非交付依赖） |
-| `package_skill.py` | **发布前校验 + 打包**：必需文件齐全 / frontmatter 合规（name 与包名一致、description ≤1024）/ 无临时·缓存路径 → `dist/top-ppt-html.zip` + 发布清单 `dist/top-ppt-html.manifest.json`（版本/条目/SHA-256）；`--check` 只校验 | 发布时 / 提交前自检 |
-
-### 4.2 单源纪律（最重要的一条规矩）
-
-**几何/字号/页型/图表登记/校验预算/强调色/去AI味词一律只改 `scripts/layout-constants.json`，页型字段只改 `scripts/model-schema.json`，公共片段只改注入源，然后跑 `sync_runtime.py`**——禁止手改任何注入副本（模板内联块、pptx-export.js 常量块）。
-
-改一套风格色值只需**两处手改 + 一处受审计**（校验器阈值、图表登记、强调色表、去AI味词表全部从 JSON 读；画廊配色也从 JSON 派生，无手抄副本）：
-
-1. `assets/templates/engine.css`（CSS 侧单源，light + dark 两个块）
-2. `scripts/layout-constants.json` 的 `styles`（light）/ `stylesDark`（dark）/ `styleAccents`（强调色族，供单一强调色检查）
-3. `assets/templates/ui.js` 的 `STYLES` 色板（header 下拉 12px 小色块）——在运行时块之前执行、无法直接读 `PRESETS`，故由 `audit_styles.py` 校验其与 JSON accent 一致（不一致即报 DIFF）
-
-然后按顺序跑：`sync_runtime.py` → `audit_styles.py` → `audit_docs.py` → `audit_skill.py`（三项审计必须全绿）→ `build_examples.py` → `regression.py`。
-
-### 4.3 新增一个 PPTX 页型（四件套，缺一不可）
-
-1. `scripts/model-schema.json` 加页型条目（字段/必填/适用模式）
-2. `scripts/layout-constants.json` 加页型几何（`pageTypes`）**并在 `pageTypeGeometry` 登记映射**（`sync_runtime.py` 会校验四件套完整性）
-3. 双引擎渲染：`scripts/build_pptx.js` 与 `assets/pptx-export.js` 各实现（坐标/字号/文本内容严格一致，否则 cross_verify 会报文本差异）
-4. `scripts/build_examples.py` 内容包覆盖新页型 + 校验断言（probes）
-
-### 4.4 新增一种图表类型
-
-1. `scripts/layout-constants.json` 的 `charts.types` 加类型名 + `charts.minSize` 配最小尺寸 + `charts.registry` 登记四元组（html / pptx 通道 / nativeType 或 path / dataTable 策略）
-2. 补实现代码：普通图表写进 `references/charts.md`（内联 SVG + `data-chart` 标记 + `f-*`/`s-*` 语义类配色）；复杂信息图页型写进 `references/infographics.md` §六/§八
-3. `references/components.md` §46 选型表补一行（内容形态 → 版式 → PPTX 页型映射）
-4. 跑 `sync_runtime.py`（图表登记四元组与可达性不变量）+ `audit_styles.py`（图表登记表自洽）+ `regression.py`
-
-### 4.5 新增一种图片版式
-
-1. `scripts/layout-constants.json` 的 `imageSpec.layouts` 加版式名 + `ratioDefault`（比例，如 `"3:1"`）+ `ratioCssClass`（HTML 锁定类，如 `media--r3-1`）+ `recommendedSizePx`（建议像素）
-2. `assets/templates/engine.css` 补该锁定类（`.media--r3-1{aspect-ratio:3/1}`）
-3. 双引擎渲染：`scripts/build_pptx.js` 与 `assets/pptx-export.js` 的 `imageLayoutShapes` 各加一个分支（几何与比例必须完全一致，否则 HTML/PPTX 会走样）
-4. `references/components.md` §11c-1 版式表补一行（layout ↔ HTML 版式 ↔ 比例 ↔ 建议像素 ↔ 适用）
-5. 跑 `sync_runtime.py`（会校验「版式 ↔ 比例 ↔ 锁定类 ↔ 双引擎实现」四向完整）+ `build_examples.py` + `regression.py`
-
-> **配图占位**无需新代码：任何版式的 `image.placeholder` 都复用同一几何（原生圆角矩形 + 虚线 + 居中标签），标签串由 `imageSpec.placeholderLabel` 派生，双引擎自动一致。
-
-### 4.6 新增一套风格
+```bash
+# 标准 / Fast 共用链（模型单写）
+python scripts/scaffold_report.py --mode research --style mckinsey --theme light \
+  --title "标题" --sections 8 --out report.html
+# 只填 window.REPORT_MODEL 后：
+python scripts/render_from_model.py report.html --inplace
+python scripts/validate_report.py report.html --strict --layout-qa
+python scripts/quality_gate.py report.html --deliver
+
+# 布局建议 / PPTX
+python scripts/recommend_layout.py --mode B --intent "经营分析" --pages 10 --json
+python scripts/extract_model.py report.html report.model.json
+node scripts/build_pptx.js report.pptx --model=report.model.json
+python scripts/validate_pptx.py report.pptx --strict --model=report.model.json
+bash scripts/smoke_pptx.sh
+
+# 门禁
+python scripts/package_skill.py --check
+python scripts/audit_skill.py && python scripts/audit_docs.py
+python scripts/audit_styles.py && python scripts/audit_css.py
+python scripts/negative_tests.py
+```
 
-`references/styles.md` 写 light+dark 两个覆盖块 → 按上节三处联动改单源（含 `layout-constants.json` 的 `styleAccents` 强调色族与 `styleDataColors` / `styleDataColorsDark` 编码色板 c1–c5）→ `assets/style-gallery.html` 的 `STYLE_META` 数组加一项（可选 `darkMain:true` 表示深色优先卡；卡片列表与配色由单源 `PRESETS` 自动派生）→ `audit_styles.py` 全绿 → 重截参考图。
+## 目录要点
 
-## 五、构建与打包
+| 路径 | 用途 |
+|------|------|
+| `SKILL.md` | L0 路由（≤13KB） |
+| `references/playbook.md` | L1 决策层 |
+| `references/default-surface.md` | Mode A 主读：12 页型 + 核图 8 + V1–V4；主力骨架 P1–P4+P6/P10 |
+| `assets/examples/` | 3 份黄金样张（每模式 1） |
+| `assets/style-gallery.html` | 9 风格 × 模式 × 亮暗 |
+| `docs/archive/` | 历史规范 / 旧示例 / 全量 build_examples |
 
-```bash
-# 环境：Python 标准库（零三方依赖）；cross_verify 可选 python-pptx
-#       Node + pptxgenjs（仅精导与回归）：在技能目录 npm install（依 package.json）
-
-python scripts/sync_runtime.py        # ① 单源注入 + 页型四件套 / 图表四元组 / 可达性不变量校验
-python scripts/audit_styles.py        # ② WCAG + 双源 + 单源完整性（含编码色板 9×2×5）审计
-python scripts/audit_docs.py          # ③ 文档一致性审计（§ 引用/前缀规范/§46 覆盖度/代码节）
-python scripts/audit_skill.py         # ④ 技能工程审计（体积预算 / 三档披露 / Gate 0 / 交互预算）
-python scripts/build_examples.py      # ⑤ 重建示例矩阵
-python evals/run_evals.py --budget    # ⑥ 效率预算自检（可选：--list / --score <报告.html> --trace <trace.json>）
-python scripts/regression.py          # ⑦ 全链路回归（发布前必绿）
-
-# 参考图（可选，需 playwright）
-npm install playwright && npx playwright install chromium
-node scripts/capture_theme_overview.js            # 或 --channel=msedge 用本机浏览器；--scale=1.25 控单张体积
-
-# 打包发布（校验不通过不产出 zip）
-python scripts/package_skill.py --check   # 只跑发布门禁：必需文件 / frontmatter / 无临时路径
-python scripts/package_skill.py           # → dist/top-ppt-html.zip + dist/top-ppt-html.manifest.json
-```
+风格画廊与主题参考图：`assets/theme-overview*.png`（Gate 0）。完整规范索引见 playbook §十。
 
-**提交与打包口径**（详见 `.gitignore` 与 `package_skill.py` 头部说明）：
-
-| 类别 | 路径 | 进包 | 入库 |
-|------|------|:----:|:----:|
-| 技能源（入口/规范/素材/工具） | `SKILL.md` `README.md` `package.json` `assets/` `references/` `scripts/` | ✅ | ✅ |
-| 构建与回归产物 | `dist/`（zip、回归 PPTX、探针产物、manifest） | ❌ | ❌ |
-| 工具中间产物 | `report-assets/`（prepare_images）、`render-compare/`（render_compare） | ❌ | ❌ |
-| 依赖与缓存 | `node_modules/`、`__pycache__/`、`.venv/` | ❌ | ❌ |
-| 本地状态 | IDE / 智能体会话与本地缓存目录（如 `.vscode/`、会话记忆等） | ❌ | ❌ |
-| 临时脚本 | `scripts/_*`（下划线开头，用后即删） | ❌ | ❌ |
-
-## 六、FAQ / 故障排查
-
-- **技能没被智能体触发？** 检查 `SKILL.md` frontmatter 的 `description` 是否超 1024 字符（超限会被平台截断或拒载）——触发词（Use when）必须留在前 80% 以内。
-- **PPTX 出来是浅色但页面是深色？** `REPORT_MODEL.theme` 未与 `data-theme` 同步（validate_report 会 WARN）；`build_pptx.js --theme=dark` 可强制覆盖。
-- **regression 报找不到 Node 或 pptxgenjs？** 在技能目录 `npm install pptxgenjs`，或设 `TOP_PPT_NODE_EXE` / `TOP_PPT_NODE_PATH` 环境变量指向已有安装。
-- **regression 里 cross_verify 被跳过？** 说明本机没装 python-pptx（可选第三方裁判）；`pip install python-pptx` 后即可启用，不影响交付判定。
-- **改了 engine.css 但模板没变？** 模板里是注入副本——跑 `python scripts/sync_runtime.py`，禁止手改模板内联块。
-- **预览与导出的 PPTX 不一致？** 两者共用同一序列化引擎，先跑 `sync_runtime.py` 确认常量/schema 未漂移，再跑 `regression.py` 的 cross_verify。
-- **浅色模式下最后一页/金句页变成深色？** 该页用了 `band--deep`（反相强调页，浅色主题下必然渲染为深色）——收尾/CTA 改用 `band--accent`，金句改用 `band--accent--solid`；校验器会 WARN（`band--deep` ≤1 处且不得作末页）。
-- **数字没法核实，怎么提示用户改？** 用 `.tbd` 标色 + `.tbd-legend`/`.flagbar` 说明（模型同步写 `section.flags`）；规则见 `content-rules.md` 五-b，**只标色不解释会被校验器 WARN**。
-- **PPTX 里能放图片吗？** 默认 `pictures=0`（全原生可编辑）；需要时在模型里显式声明 `section.image`（或 `split.right.image`），图片数不得超过声明数（`PICTURES_NOT_DECLARED` 硬拦），`src` 仅允许 data: 内联或相对路径。
-- **某页在浏览器里偏高/偏低？** 页高模型默认"每页一屏 + 垂直居中"（`--band-min`）；内容约六七成屏改用 `.band--top`，长结构页（参考资料/附录）用 `.band--flow`。详见 `design-system.md` §1c。
-
-## 七、版本、规范与兼容
-
-- **当前发布版**：v0.1.0（风格语汇 styleIdentity · 布局语法 · 模型单写 · 硬门禁）。**版本单源 = `scripts/layout-constants.json` `version`**；`model-schema.json` / `layoutSlots` 同步该值；`package_skill.py` 与 `sync_runtime.py` 校验一致。
-- **frontmatter**：仅 `name` + `description`（触发词写清「做什么 + 何时用」，控制在 700 字符软上限内）。
-- **目录与 token 预算**：`SKILL.md`（≤13KB 路由）→ L1 `references/playbook.md`（≤22KB 决策）→ L2 按需（`extract_snippet.py` 节级取码）→ `scripts/` 工具 → `assets/` 素材。`audit_skill.py` 把关体积 / 三档披露 / Gate 0 / 与 references 去重。
-- **工作流（模型单写）**：`scaffold_report.py` → 只填 `REPORT_MODEL` → `render_from_model.py --inplace` → `validate_report --strict`（含 PPTX 再走 extract/build/validate_pptx）。
-- **变更流水**：见仓库根目录 `CHANGELOG.md`。
-- **命名**：`top-ppt-html`；注入标记 `__TOPPPT_*__`；环境变量 `TOP_PPT_NODE_*`；JS API `TopPptHtml`。
-- **发布门禁**：`package_skill.py --check` 通过后产出 `dist/top-ppt-html.zip` + manifest（SHA-256）。

package/top-ppt-html/SKILL.md

@@ -1,35 +1,50 @@
 ---
 name: top-ppt-html
-description: "TopPPT HTML：报告 / 演示 / 信息架构图生成器。单文件零外链 HTML（可翻页、亮暗双主题）+ 版式保真的原生可编辑 16:9 PPTX。三模式（A 演示·每屏一主张 / B 研究·咨询密排 / C 架构·图为王）× 9 风格；布局骨架 P1–P12；内容只填 REPORT_MODEL，render_from_model 回填正文；strict 0/0 才交付。Use when 用户要做报告、演示、汇报、PPT、slides、deck、路演，或写研究报告、分析报告、咨询报告、白皮书、调研、评测、对标、经营分析、复盘、项目汇报、商务/HTML/网页报告，或做架构图、拓扑图、流程图、泳道图、方案图，或把材料/数据做成可视化报告，或导出 HTML/PPT/PPTX（保真、可编辑、高保真、1:1），或优化排版、版式、配色、密度、图文布局。Do NOT use for 纯代码工程、非报告类网页或应用开发、视频/图片生成、直接改写已有 Word/PPT 源文件本身。"
+description: "TopPPT HTML：报告 / 演示 / 信息架构图生成器。单文件零外链 HTML（可翻页、亮暗双主题）+ 版式保真的原生可编辑 16:9 PPTX。三模式（A 演示·每屏一主张 / B 研究·咨询密排 / C 架构·图为王）× 9 风格；布局骨架 P1–P12；内容只填 REPORT_MODEL，render_from_model 回填正文；strict 0/0 才交付。Use when 用户要做报告、演示、汇报、PPT、slides、deck、路演，或写研究报告、分析报告、咨询报告、白皮书、调研、评测、对标、经营分析、复盘、项目汇报、商务/HTML/网页报告，或做架构图、拓扑图、流程图、泳道图、方案图，或把材料/数据做成可视化报告，或导出 HTML/PPT/PPTX（保真、可编辑、高保真、1:1），或优化排版、版式、配色、密度、图文布局，或要快速模式/fast/直接生成/一键出稿/少问一句。Do NOT use for 纯代码工程、非报告类网页或应用开发、视频/图片生成、直接改写已有 Word/PPT 源文件本身。"
 ---
 
 # TopPPT HTML
 
 **让 idea 飞，好想法被看见。** 一套技能、三种模式、两种交付：**单文件 HTML 报告**（可翻页、可演示、header 自带工具栏）+ **版式保真的原生可编辑 PPTX**（智能体精导唯一交付通道）。两者同源于一个内容模型 `REPORT_MODEL`。设计对齐 Material Design 3，执行克制（Google/Apple 风）；研究模式对齐咨询机构（McKinsey/BCG）的密度与论证结构，但**克制优先**——不加多余的页头标签、页脚信息与装饰。
 
-## Gate 0 · 先给参考图（任何生成动作之前 · 硬门禁）
+## Gate 0 · 先给参考图（**标准模式**硬门禁）
 
-用户表达做报告意向后，**第一件事**是展示参考图，再进入问询：
+标准路径下，用户表达做报告意向后，**第一件事**是展示参考图，再进入六项问询：
 
 | 给什么 | 路径 | 何时 |
 |--------|------|------|
-| 整体图（默认先给这张） | `assets/theme-overview.png` | 每次开场 |
-| 按模式拆分的参考图 | 演示 → `assets/theme-overview.png`；研究 → `-research.png`；架构 → `-architecture.png` | 模式已明确时给对应那张（演示态与整体图相同，不再单独存 presentation 副本） |
-| 交互画廊（实时切风格×模式×亮暗） | `assets/style-gallery.html` | 用户想边看边挑 |
+| 整体图（默认） | `assets/theme-overview.png` | 每次开场 |
+| 按模式拆分 | 演示→整体图；研究→`-research.png`；架构→`-architecture.png` | 模式已明确 |
+| 交互画廊 | `assets/style-gallery.html` | 用户想边看边挑 |
 
-**理由**：风格与主题是用户最需要"看见"才能决策的形式参数。**跳过参考图直接问询 = 不合格**（`audit_skill.py` 校验 Gate 0 位于六项问询之前）。
+**标准模式**：跳过参考图直接问询 = 不合格。**Fast Mode**（下节）豁免 Gate 0 与六项。
+
+
+## Fast Mode · 快速模式（用户显式 opt-in）
+
+触发词任一即进入（**跳过 Gate 0 与六项问询**）：`快速模式` / `fast` / `直接生成` / `一键出稿` / `fast mode` / `少问一句`。
+
+| 参数 | 默认 | 推断 |
+|------|------|------|
+| mode | **B** | **路演/汇报/发布/演讲/demo/融资→A**；架构/拓扑→C；未点明→B |
+| style | B→mckinsey · A→business-blue · C→graphite-dark | |
+| theme | light（graphite→dark） | |
+| 篇幅 | A=10 / B=12 / C=6 | |
+| format | html only（用户要 PPT→html+pptx） | |
+
+流程：一行宣布「Fast 选用：…」→ 走 playbook §二轻量命令链（骨架→模型单写→回填→strict→`quality_gate --deliver`；可选 pptx）。路径永远轻量；回复末可附 `assets/style-gallery.html`。开场须声明「已跳过参考图」。**标准模式**仍强制 Gate 0 + 六项。
 
 ## 唯一入口流程
 
 ```
-听意图 → Gate 0 参考图 → 六项问询（1 轮）→ 内容架构 → 起骨架
-      → 只填内容模型 → 回填正文 → validate --strict 0/0 → 交付
-      （命令与 PPTX 链见 tech-design §六 / pptx-export）
+听意图 → [Fast? → 快路径] : [Gate 0 → 六项（1 轮）→ 内容架构]
+      → 起骨架 → 模型单写（禁改 HTML 正文）→ 脚本回填 → strict 0/0 → 交付
+      （命令链见 playbook §二/§九；PPTX 见 pptx-export）
 ```
 
 **预算（硬）**：交互轮次 **≤3**；默认必读仅 2 份——本文件 + L1 决策层 `references/playbook.md`；L2 深度文件命中才读、读一份用一份、不预读。
 
-## 六项问询（一次问完 · 唯一一次形式参数确认）
+## 六项问询（标准模式 · 一次问完 · 唯一一次形式参数确认）
 
 用户表达意图后**一次问完六项**，每项都带意图推荐；用户不选即按推荐执行，不再追问。
 
@@ -70,23 +85,23 @@ description: "TopPPT HTML：报告 / 演示 / 信息架构图生成器。单文
 **L2 一览**（命中条件与逐任务只读清单的**详表以 playbook §十为准**，此处仅索引）：
 
 - 模式契约与锁定版式 → `references/modes.md` · 完整路径七步 → `references/outline-design.md`
-- **布局骨架/元素/组合/留白 → `references/layout-grammar.md`（P1–P12 · 每页动手前）**
-- 组件/版式**代码**与 §46 选型表 → `references/components.md` · 图表**代码** → `references/charts.md` · 信息图页型 → `references/infographics.md`（→ stats / structure 两分册）
-- 配色/主题/字阶 → `references/styles.md` + `references/design-system.md`（`design-system-engine.md` 为实现镜像，生成场景不读）· 写作纪律 → `references/content-rules.md` · 图标语义表 → `references/icons.md`
-- PPTX 精导 → `references/pptx-export.md` · 深度高保真 → `references/high-fidelity.md` · 修复顺序 → `references/failure-modes.md` · 技能维护 → `references/tech-design.md` + `references/industry-benchmark.md`
+- **A/Fast 主读 → `references/default-surface.md`** + **`presentation-craft.md`** · 骨架分层见 `layout-grammar.md` §七
+- 组件/版式**代码** → `components.md` · 图表门面 `charts.md`（纪律+核图；extended 按需取节）· 信息图 → `infographics.md`
+- 配色/主题/字阶 → `styles.md` + `design-system.md` · 写作 → `content-rules.md` · 图标语义 → `icons.md`
+- PPTX 精导 → `references/pptx-export.md` · 深度高保真 → `references/high-fidelity.md` · 修复顺序 → `references/failure-modes.md` · 技能维护 → `references/tech-design.md`
 
 **操作方式**：定模式/页型/组合/图 → 只读 `playbook.md`；取代码 → `extract_snippet.py`；**禁止整读** `layouts-combo.md` / `charts-basic.md` 等大文件；**同一阶段不重复读同一文件**。
 
 ## 铁律（12 条 · 交付硬门禁）
 
-> 本节是**门禁语义**；阈值与细则见 playbook（常量在 scripts 下的 layout 常量 JSON）。排版只读 `layout-grammar.md`。
+> 门禁语义；阈值见 playbook / layout 常量 JSON。排版读 `layout-grammar.md`。**motion=none**（无炫技转场；见 `presentation-craft.md`）。
 
 1. **单文件零外链**——无 CDN/外部字体/外部图片，图形一律内联 SVG；`<img src>` 仅 `data:` 或相对路径且必带 `alt`（单图 ≤1.5MB、全篇 ≤8MB）；无素材图不留空不省略，用配图占位（`components.md` §11c-3）。
 2. **模式先定后写**——从对应模式模板起步；`data-mode` = `REPORT_MODEL.mode`，页面无模式切换；MD3 映射；PPTX 字号走三模式独立比例尺。
 3. **亮暗双主题一致**——CSS 变量整块换肤 + header 切换 + 文件级记忆；`REPORT_MODEL.theme` 与页面一致，PPTX 同主题导出；强调带只用 accent 家族，**末页禁 `band--deep`**。
-4. **每页一屏 + 高度稳定**——`section.band` ≥ 一屏高且垂直居中；六七成屏用 `.band--top`，长结构页 `.band--flow`。放不下按「优化内容 → 升级承载 → 扩组合 → 分区 → 拆页 → 最后才有限缩字号」（下限 `containers.fontShrink`）；禁止砍决策必需信息，拆页保持信息完整。
+4. **每页一屏 + 高度稳定**——`section.band` ≥ 一屏高且垂直居中；六七成屏用 `.band--top`，长结构页 `.band--flow`。放不下按「重构承载 → 拆页/分章 → 换布局形态 → 有限缩字号」（`containers.overflowRule`）；**禁止**静默截断或为疏朗删 so-what/证据；拆页保持信息完整。
 5. **PPT 式翻页 + 骨架固定**——`section.band` 即一页；方向键翻页、页码可点；Agenda 第二页（arch 内容页 ≤4 可省）；页头只留 eyebrow + 标题 + 可选导语，页脚全文一个；页头页脚之外不加装饰。
-6. **标题与字号**——主标题粗体（`--fw-title/--fw-display`）；research 主标题必须是**结论句**（≥12 字含数字/判断词）；字号随模式（playbook §一），全部 `clamp()`，图表不缩水。
+6. **标题与字号**——主标题粗体；research=结论句（≥12 字）；**presentation=主张/行动句**（禁话题标签）；字号随模式，`clamp()`，图表不缩水。
 7. **组合版式 + 细节保全**——默认一页 = 主件 + 从件 + 注释层（矩阵 playbook §四）；先判定决策必需信息再定形态，**禁砍口径列/时间列/维度**；密度 L/M/H 禁连续 3 页同档；同一版式不连用超 2 页（扩展签名可 3 页）。
 8. **列表优先 + 去 AI 味 + 图标克制**——大段文字转列表（research 双/三栏正文除外）；`aiFlavor` 词表零命中；图标每屏 3–8 个（架构图为王可无）。
 9. **图表够大 + 够多样 + 双通道**——尺寸 ≥ `charts.minSize`；`data-chart` 须在 `charts.registry`（36 种）登记；多样性下限与相邻不同型按 `charts.variety`（playbook §五）；原生通道 `addChart` 双击可编辑数据，形状通道须按登记策略附数据表（口径注解见 tech-design §二）。
@@ -105,7 +120,7 @@ description: "TopPPT HTML：报告 / 演示 / 信息架构图生成器。单文
 
 - **零依赖可用**：HTML 生成与全部 Python 脚本只用 **Python 标准库**。
 - **PPTX 精导**：另需 Node + pptxgenjs（安装与 `TOP_PPT_NODE_EXE`/`TOP_PPT_NODE_PATH` 探测细节见 `pptx-export.md` 环境备注，探测失败会打印指引）。
-- **硬门禁**：标签泄漏/空页/极偏图/简单大图等见 `layout-constants.qualityGates` 与 `reform-plan.md`。
+- **硬门禁**：标签泄漏/空页/极偏图/简单大图 → `scripts/layout-constants.json`（qualityGates）+ `failure-modes.md`。
 - **可选**：浏览器页高/裁切真值、参考图重生成需 playwright（`regression.py` 自动探测，缺失即跳过）。
 - **一键回归**：`scripts/regression.py`——模板/常量/schema/运行时/示例改动后必跑。
 - **技能自检**：`audit_skill.py`（体积/披露/Gate 0/内容重复）· `audit_docs.py`（§ 引用 + 任务路由可解析）· `audit_styles.py`（9 风格 × 亮暗 token 与对比度）· `audit_css.py`（CSS 类覆盖率 · 报告制）。

package/top-ppt-html/package.json

@@ -1,6 +1,6 @@
 {
   "name": "top-ppt-html",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": true,
   "description": "TopPPT HTML：报告 / 演示 / 信息架构图技能。单文件 HTML + 版式保真的可编辑 PPTX；布局骨架 P1–P12；模型单写；strict 0/0 交付。",
   "license": "MIT",

package/top-ppt-html/references/charts-discipline.md

@@ -45,7 +45,9 @@
 | 同页放两张同型图 | 两个视觉重心互相打架 | 改 `split` / `halftable` 并让两图**编码不同维度** |
 | 多系列图用单色明度阶梯 | 三条线分不清谁是谁 | `f-c1~c5` / `s-c1~c5` 编码色板（见 `design-system.md` §9b） |
 
-### 66-2 多样性纪律（校验器硬拦 · 阈值单源 `layout-constants.json` `charts.variety`）
+### 66-2 多样性纪律（校验器硬拦 · 参数单源 `layout-constants.json` `charts.variety`）
+
+> **preferCoreFirst**：优先用核图 8 拉开多样性；`charts-extended` / advanced **意图命中才加载**。advanced 一旦使用即计入类型数下限（不罚）；**禁止**为过 `minTypes` 硬上冷门图。
 
 1. **类型数下限**：全篇不同 `data-chart` 类型数 ≥ `min(minTypes[mode], ⌈图表页数 × 0.6⌉)`（research 上限 6 / presentation 4 / architecture 3）。
 2. **不连续同型**：相邻图表页不得使用同一 `data-chart` 类型——读者视角就是"又一张一样的图"。

package/top-ppt-html/references/charts.md

@@ -1,28 +1,37 @@
-# 图表全库（逻辑索引 · 节级物理文件）
+# 图表全库（逻辑索引 · 纪律优先 · 按需取码）
 
-> 本文件已拆分，**禁止整读**。§编号保持不变。取码入口：
+> 本文件已拆分，**禁止整读**物理大文件。§编号跨文件稳定。取码：
 > `python scripts/extract_snippet.py --file charts.md --section <编号>`
+> 或 `--chart <类型>`（自动路由）。
 
-| § 范围 | 物理文件 |
-|--------|----------|
-| §16、17、18、19、20、21 … | `charts-basic.md` |
-| §52、53、54、55、57、58 … | `charts-extended.md` |
-| §64、66 … | `charts-discipline.md` |
+## 读序（P1-3 facade · 不缩减 registry）
 
-原始前言与说明保留如下（规范正文已迁出）。
+1. **先纪律**：`charts-discipline.md`（§64 合理性 · §66 误用与多样性）——选型与反模式。
+2. **核图 8**（Mode A / Fast 默认池）：`bar` · `hbar` · `line` · `donut` · `progress` · `area` · `stack` · `dualline` → 代码在 `charts-basic.md`。
+3. **基础扩展**：其余 basic 类型按意图取节（仍属 `charts-basic.md`）。
+4. **高级 / extended**：waterfall、sankey 相关形状、boxplot… → **意图命中才读** `charts-extended.md`；勿预读。
+5. **信息图页型**（非 `chart.type`）：`infographics.md` §71–§77。
+
+**多样性地板不变**：`charts.variety.minTypes.presentation ≥ 4`（及 B/C 对应下限）；registry 36 种不删。  
+**preferCoreFirst**：先拉开核图 8；advanced 使用时**计入** minTypes（不罚），但**禁止预读/默认选用** `charts-extended.md`——仅意图命中时 `extract_snippet.py --chart`；**禁**为凑下限垫冷门图。
+
+| § 范围 | 物理文件 | 何时读 |
+|--------|----------|--------|
+| §64、§66 | `charts-discipline.md` | **默认先读**（误用/多样性） |
+| §16–§31、§29b、§35 等 | `charts-basic.md` | 核图与常规图代码 |
+| §52–§70（除纪律节） | `charts-extended.md` | advanced / 意图命中 |
 
 # 图表全库（纯 SVG · `data-chart` 标记）
 
-复制即用。所有类名依赖 `design-system.md` 的 token；版式与页型见 `components.md`，复杂信息图页型见 `infographics.md`。
+复制即用。类名依赖 `design-system.md` token；版式见 `components.md`；复杂信息图见 `infographics.md`。
 
-**约定**：图表 svg 一律加 `class="chart" data-chart="类型"`（**36 种登记类型**：donut / multidonut / pie / radar / gauge / rose / bar / stack / stackline / waterfall / line / dualline / area / scatter / bubble / funnel / gantt / hbar / vsbar / treemap / progress / sparkline / sankey / slope / dumbbell / lollipop / marimekko / dotplot / bulletchart / waffle / boxplot / pareto / radialbar / streamgraph / candlestick / network），供动效脚本与 `validate_report.py` 识别。**类型登记表与最小尺寸的唯一事实源 = `scripts/layout-constants.json` 的 `charts`**（新增类型必须同时登记 `types` 与 `minSize`）。
+**约定**：图表 svg 一律 `class="chart" data-chart="类型"`（**36 种登记**：donut / multidonut / pie / radar / gauge / rose / bar / stack / stackline / waterfall / line / dualline / area / scatter / bubble / funnel / gantt / hbar / vsbar / treemap / progress / sparkline / sankey / slope / dumbbell / lollipop / marimekko / dotplot / bulletchart / waffle / boxplot / pareto / radialbar / streamgraph / candlestick / network）。事实源 = `scripts/layout-constants.json` → `charts`（`types` + `minSize`）。
 
-> **编号说明**：跨文件唯一稳定编号（§1–§77）。本文件收录图表 §16–§31、§29b、§35、§52–§70。
-> **六类信息图**（sankey / treemap / boxplot / network / marimekko / streamgraph）**不作为 `chart.type`**——它们是**专属页型**，HTML 写法见 `infographics.md` §71–§77。
+> **编号说明**：跨文件唯一稳定编号（§1–§77）。图表 §16–§31、§29b、§35、§52–§70。  
+> **六类信息图**（sankey / treemap / boxplot / network / marimekko / streamgraph）**不是** `chart.type`——专属页型见 `infographics.md`。
 
 ---
 
-# 第一部分 · 基础图表
-
-> 单维对比 / 趋势 / 占比 / 分布等常规图表；多系列配色见 §29b。
+# 第一部分 · 基础图表（核图优先）
 
+> 单维对比 / 趋势 / 占比 / 分布；多系列配色见 §29b。Mode A 默认从核图 8 起选。