@topmindspace/tms-skills 0.1.17 → 0.1.19

package/CHANGELOG.md

@@ -1,3 +1,87 @@
+## [0.1.19] - 2026-09-28
+
+### 排版修复 · 大纲篇章化 · 参考资料去假 · 图标真导出 · PPTX 高保真增强
+
+> 源起：2026-09-28 用户复盘五类问题（顶栏重叠 / 卡片不齐 / 大纲罗列页标题 / 参考资料占位 / PPTX 格式错乱），并要求「业界怎么解决的，不要闭门造车」。本次对照 Slidev `pptx-editable` / PptxGenJS / think-cell 混合通道模式系统整改。
+
+#### A. HTML 排版硬伤
+- **顶栏副标题压住右侧工具钮**：`.brand__txt` 此前无基础样式，flex `min-width:auto` 钉死整行文字宽，省略号永不触发。补 `min-width:0; overflow:hidden`，`.brand` / `.bar__in` / `.nav` 收缩链修复；≤1360px 自动收起副标题。
+- **卡片高度不一致**：`.card` 改 flex 列 + 底对齐；`.g-quad` / `.g-half` / `.g-*--equal` 强制等高；`.g-half` 提升进 `engine.css` 并改 `align-items:stretch`（此前 research 专属且 `start` 违反「同构同高」契约）；纯卡片栅格不再误用 `.a-start`。
+
+#### B. 大纲 = 章节大纲（3–7 章），不是页目录
+- **结构契约**：`agenda` 条目 = 章（篇/section），每章 1+ 页；页标题逐页出现，章标题只在 Agenda 出现一次。预算 3–7 章（含参考资料 +1 仍 ≤8）。
+- **生成器**：`render_from_model` / `scaffold_report` 按 eyebrow `NN ·` 章前缀归并，删掉「agenda 条数 ≠ 页数就按页强制重建」逻辑；锚点落该章第一页。
+- **schema / 阈值**：`model-schema` 加 `agendaMax=7` / `agendaHint`；`layout-constants.contentQuality.agenda` 加 `chapterMin/Max`；`agendaComfortMax` 16→8。
+- **文档**：`content-rules` §Agenda 重写；`SKILL` 铁律 4；`components-atoms` / `failure-modes` F20 / `layout-grammar` 阈值同步。
+- **样张**：showcase 大纲 12 条页标题 → 9 章（`05 · 图表工艺` 下 3 页只占 1 条）。
+
+#### C. 参考资料只列真实来源（宁缺毋假）
+- **冒烟枪**：`render_from_model.py:738` 对每个 `[n]` 生成 `「来源名称，时间；口径。」`；scaffold 写「来源 N（替换为真实来源名称）」。
+- **新规则**：只列 `model.refs` 真实来源；**无真实来源整节省略**（连导航 `#refs` 入口一并摘掉，避免悬空锚点）。硬拦占位串（`来源名称` / `替换为真实来源` / `某行业报告`）。
+- **模板**：三份模式模板参考节改为注释掉的真实样例 + 「无真实来源则删整节」说明；`example.com` 假条目清除。
+- **文档**：`content-rules` §五 规则 4 重写；`SKILL` 铁律 10；`layouts-research` / `.ref-link` 示例改真实机构名。
+
+#### D. 图标真导出（SVG→PNG，不再用 accent 方块替代）
+- **新模块**：`scripts/icon_lib.js`（20 语义图标单源）· `scripts/build_icon_assets.js`（sharp 栅格化）· `scripts/icon-assets.json`（PNG 缓存，gitignore）· `scripts/icon_raster.js`。
+- **链路**：模型 `cards[].icon` / HTML `data-icon` → `extract_model` 回填 → `build_pptx` 嵌 PNG。`objectName: icon:*`，`validate_pptx` 单独计数 `icon_pictures`，**不进** `pictures=0` 内容图门禁。缺 sharp/资产回落 accent 方块。
+- **schema**：`cards[].icon` 字段 + 取值说明（`icon_lib.js` 键）。
+
+#### E. PPTX 高保真增强（对照业界混合通道）
+- **发射前叠印断言**：`assertNoOverlap` / `rectsOverlap` 在 `addShape` 前自检组合布局（图表∩inline 数据表等），计入 `OVERLAP_PREEMIT`。
+- **表格行高自适应**：`addTable` 超容量压到 hardFloor / 整体缩放；表头独立 `headRowH`；`fit:'shrink'`。
+- **`regionOf('bar')` 双偏移纠正**：`chartX/chartW` 此前被当偏移再加 `mx`，柱图右移 0.6in 与标题/表格不齐——改与 donut/table/hbar 同口径对齐版心。双引擎同步。
+- **图例收进图高**：waffle / marimekko / slope 图例带含在 `h` 内，与 inline 数据表留间隙（几何铁律②）。
+- **文本自动收缩**：标题 / 卡片 / 结论条 / 页脚统一 `fit:'shrink'`（PowerPoint 字体度量 ≠ 浏览器）。
+
+#### F. 文档与工程
+- `icons.md` / `pptx-export.md` / `high-fidelity.md`（新增「已落地的高保真增强」对照表）/ `failure-modes` F20 / `tech-design`（图标单源登记）/ `package_skill`（三模块进必收）。
+- 业界调研纪要：`docs/industry-pptx-research.md`（Slidev pptx-editable / PptxGenJS / think-cell / Marp / reveal.js 路线对比与取舍）。
+
+#### 回归
+- 技能审计 ✓ · 文档审计 ✓ · 研究 HTML 94/0/0 ✓ · 展示 HTML 85/2/0 ✓ · 两份 PPTX `errors:[] warnings:[]` ✓ · 打包校验 106 文件 ✓。
+
+### 红线未动
+反截断、图表多样性地板、Mode A craft、runtime SHA 同版本门禁、中文「演示文稿」术语、整仓 npm 发版、motion=none、结论条无「So what」标签、无左侧 accent 装饰轨、双单源 + sync_runtime、strict 0/0 交付。
+
+## [0.1.18] - 2026-09-28
+
+### PPTX 导出质量整改 · 双通道几何收敛 + 门禁盲区补齐
+
+> 源起：2026-09-28 研究报告双通道交付复盘（HTML/PPTX），PPTX 有 4 类硬伤（含两处大面积文字叠印）、HTML 有 4 类空间利用问题、门禁全绿而效果不合格。本次按六类根因（R1–R7）系统整改。
+
+#### A. 几何叠印硬伤（R1/R2 · PPTX 导出）
+- **架构节点标题/注解叠印**：注解改为钳制在标题下边（原底对齐 `y=lh-0.5` 在 `lh≈0.59` 时与标题完全重合）；节点高不足降级单框混排。双引擎同步。
+- **verdict/soWhat 同槽叠印**：共用 annotation 结论条槽位——渲染器互斥（verdict 优先）、`extract_model` WARN、`model-schema` 加 `mutualExclusionHint`。HTML 同步去重。
+- **图例压来源行**：图例改落图区底部（`bodyBottom-0.28`），禁 `PH-0.62` 固定偏移。
+- **`sec.note` 压 so-what 带**：`note` 与 `footnote` 合并到 `footnoteY=6.72`，禁用 `note.y=6.55` 绘制。
+- **图表类目标签越出图区**：标签带含在图高 `h` 内（原画到 `y+h` 外）。
+- **图片底边侵入注释带**：有图注时下界收到 `contentBottomWithNote`。
+
+#### B. 列宽 / 槽位几何（R3）
+- **三栏只占半幅（栏宽 1.69in）**：`regionOf('twocol')` 单栏宽被当总宽——改用版心全宽推导。双引擎同步。
+- **KPI 支撑指标铺满整页**：A 通道 `regOf('kpi','metrics')` 缺分支——补 dividerX 右侧分栏。
+- **halftable 图表越过 so-what**：`regOf('halftable')` 忽略 opts.top/bottom——传导 opts。
+
+#### C. Agenda 分页与列序统一（R4）
+- >8 条自动双列（列优先）；**>12 条自动分页**（Agenda I/II）；长标题截断全称沉 notes（`titleMaxChars=36`）。双引擎 + HTML 同步。
+
+#### D. 门禁盲区补齐（R6）
+- **新增 `ELEMENT_OVERLAP`**（元素两两重叠 ≥0.05in²）与 **`LAYOUT_FILL`**（版心填充率 <55%）。
+- **Agenda 容量契约**：条数 ≤16、标题 ≤36 字、>8 条须双列。
+- **图表还原度分级**（`charts.fidelityMap`）：low = area/radar/treemap/sankey/streamgraph/marimekko/boxplot/network；决策树标注 + 改判建议。
+- **跨通道一致性**（`cross_verify`）：Agenda 阅读顺序、图片数量、图表数据标签。
+
+#### E. 图标与图片正确使用
+- **图标**：`render_from_model` 内置语义图标库 + `card_head()`；PPTX 保持 accent 方块路标。
+- **图片**：`r_image` 支持真图渲染、占位同串、`fit=contain`、多图版式（grid/compare/wall）。
+
+#### 文档同步
+- `page-type-matrix` 容量契约 + 还原度；`failure-modes` F19/F20；`pptx-export` 几何铁律；`chart-decision-tree` 还原度列；`content-rules` / `components-atoms` / `modes` / `layouts-combo` 契约更新。
+- Pages 源同步：`docs/showcase.html` / `docs/style-gallery.html` 与技能侧 assets 副本逐字节一致（meta → v0.1.18）。
+
+### 红线未动
+反截断、图表多样性地板、Mode A craft、runtime SHA 同版本门禁、中文「演示文稿」术语、整仓 npm 发版、motion=none、结论条无「So what」标签、无左侧 accent 装饰轨、大纲 >8 → 2col。
+
 ## [0.1.17] - 2026-09-26
 
 ### Release

package/README.en.md

@@ -76,9 +76,9 @@ See [top-ppt-html/README.md](./top-ppt-html/README.md) and [SKILL.md](./top-ppt-
 
 | Skill | Version | What it does |
 |-------|---------|--------------|
-| [`top-ppt-html`](./top-ppt-html/) | **0.1.17** | Formal business decks: paginated HTML + editable 16:9 PPTX; dual delivery · MD3-inspired density; 3 modes × 9 styles; strict 0/0 |
+| [`top-ppt-html`](./top-ppt-html/) | **0.1.19** | Formal business decks: paginated HTML + editable 16:9 PPTX; dual delivery · MD3-inspired density; 3 modes × 9 styles; strict 0/0 |
 
-Installer [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills) is also **0.1.17** (whole-repo same-tag releases).
+Installer [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills) is also **0.1.19** (whole-repo same-tag releases).
 
 ## Install
 
@@ -88,7 +88,7 @@ Installer [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspa
 npx @topmindspace/tms-skills list
 npx @topmindspace/tms-skills install top-ppt-html
 npx @topmindspace/tms-skills install top-ppt-html --to ./.claude/skills
-npx @topmindspace/tms-skills@0.1.17 install top-ppt-html   # pin
+npx @topmindspace/tms-skills@0.1.19 install top-ppt-html   # pin
 ```
 
 ```bash

package/README.md

@@ -74,9 +74,9 @@
 
 | 技能 | 版本 | 做什么 |
 |------|------|--------|
-| [`top-ppt-html`](./top-ppt-html/) | **0.1.17** | 正式商务演示：HTML 可翻页 + 16:9 可编辑 PPTX；双交付 · MD3 密度克制；三模式 × 九风格；strict 0/0 |
+| [`top-ppt-html`](./top-ppt-html/) | **0.1.19** | 正式商务演示：HTML 可翻页 + 16:9 可编辑 PPTX；双交付 · MD3 密度克制；三模式 × 九风格；strict 0/0 |
 
-安装器 [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills) 同为 **0.1.17**（整仓同 tag 发版）。
+安装器 [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills) 同为 **0.1.19**（整仓同 tag 发版）。
 
 ## 安装
 
@@ -86,7 +86,7 @@
 npx @topmindspace/tms-skills list
 npx @topmindspace/tms-skills install top-ppt-html
 npx @topmindspace/tms-skills install top-ppt-html --to ./.claude/skills
-npx @topmindspace/tms-skills@0.1.17 install top-ppt-html   # 钉版本
+npx @topmindspace/tms-skills@0.1.19 install top-ppt-html   # 钉版本
 ```
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topmindspace/tms-skills",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "TopMindspace 智能体技能 monorepo — 通过 npm / GitHub npx 安装技能（top-ppt-html：HTML+PPT 双交付，正式商务演示文稿）。",
   "license": "MIT",
   "author": "TopMindspace",

package/top-ppt-html/README.en.md

@@ -18,7 +18,7 @@ Plenty of PPT skills exist. This one is for **formal business presenting**: clea
 </p>
 
 - Skill id: `top-ppt-html`; brand: **TopPPT HTML**
-- Version: **v0.1.17** (same tag as `@topmindspace/tms-skills@0.1.17`)
+- Version: **v0.1.19** (same tag as `@topmindspace/tms-skills@0.1.19`)
 - **Agent entry**: `SKILL.md` → `references/playbook.md` (L1) → L2 on demand
 - **Human maintainers**: this README (install / commands / layout); do not treat it as the generation spec
 
@@ -73,7 +73,7 @@ Also: arrow-key paging; **Esc** closes modals. After style/theme change, re-run
 
 ```bash
 npx @topmindspace/tms-skills install top-ppt-html
-npx @topmindspace/tms-skills@0.1.17 install top-ppt-html
+npx @topmindspace/tms-skills@0.1.19 install top-ppt-html
 npx github:topmindspace/tms-skills install top-ppt-html
 ```
 

package/top-ppt-html/README.md

@@ -18,7 +18,7 @@
 </p>
 
 - 技能标识：`top-ppt-html`；品牌名：**TopPPT HTML**
-- 版本：**v0.1.17**（与 `@topmindspace/tms-skills@0.1.17` 同 tag）
+- 版本：**v0.1.19**（与 `@topmindspace/tms-skills@0.1.19` 同 tag）
 - **智能体入口**：`SKILL.md` → `references/playbook.md`（L1）→ L2 按需
 - **人类维护者**：本 README（安装 / 命令 / 目录）；勿把本文件当生成规范
 

package/top-ppt-html/SKILL.md

@@ -4,7 +4,7 @@ description: "Use when 用户要做报告、演示、汇报、PPT、slides、dec
 license: MIT
 compatibility: "Python 3 stdlib for HTML generation; Node >=18 + pptxgenjs for PPTX; optional playwright for browser regression / theme captures."
 metadata:
-  version: "0.1.17"
+  version: "0.1.19"
   author: TopMindspace
 ---
 # TopPPT HTML
@@ -102,13 +102,13 @@ metadata:
 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` ≥ 一屏；主内容不得溢出画布或压进结论条/注释带。放不下按「重构承载 → 拆页/分章 → 换布局形态 → 有限缩字号」（`containers.overflowRule`）；**禁止**静默截断或为疏朗删结论条/证据。大纲 **>8 条**用 `.agenda--2col`（两列/两排）。结论条 = MD3 tonal surface（无「So what」标签、**无左侧 accent 轨**）；要点卡/关键列表按 `icons.md` 克制取用图标。
+4. **每页一屏 + 高度稳定**——`section.band` ≥ 一屏；主内容不得溢出画布或压进结论条/注释带。放不下按「重构承载 → 拆页/分章 → 换布局形态 → 有限缩字号」（`containers.overflowRule`）；**禁止**静默截断或为疏朗删结论条/证据。**大纲 = 3–7 章（每章 1+ 页），禁逐页标题罗列**（`outline-design.md` ⑤）。结论条 = MD3 tonal surface（无「So what」标签、**无左侧 accent 轨**）；要点卡/关键列表按 `icons.md` 克制取用图标。
 5. **PPT 式翻页 + 骨架固定**——`section.band` 即一页；方向键翻页、页码可点；Agenda 第二页（arch 内容页 ≤4 可省）；页头只留 eyebrow + 标题 + 可选导语，页脚全文一个；页头页脚之外不加装饰。
 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 §二）。
-10. **引用与待核实**——外部数据 `[n]` + 文末参考资料（来源+时间+口径）双向对齐；research 关键图表 Exhibit N 连续编号 + 来源行；`.tbd` 强调色标注必须配图例（content-rules §五-b），单页 ≤12 处；只标色不解释即不合格。
+10. **引用与待核实**——外部数据 `[n]` + 文末参考资料（来源+时间+口径）双向对齐；**只列真实来源，无则省略参考资料整节，禁占位条目**；research 关键图表 Exhibit N 连续编号 + 来源行；`.tbd` 强调色标注必须配图例（content-rules §五-b），单页 ≤12 处；只标色不解释即不合格。
 11. **容器级门禁 + 语义字号**——溢出按**归属容器**判定，越过容器即失败（哪怕未越页）；容器保留内边距，不得缩字号解决溢出；表格正文用 `body` 层级，`micro` 只给轴标签/单位/短标签；连续句不拆文本框。
 12. **双单源 + 校验闭环**——schema 只改 `scripts/model-schema.json`，其余常量只改 `scripts/layout-constants.json`，改后必跑 `sync_runtime.py`（禁手改注入副本）；**HTML strict 0/0 才交付**，带 PPTX 加验 `validate_pptx.py --strict --model=` 0/0；页面只提供「预览 PPTX」与提示词，不做文件导出。
 
@@ -132,7 +132,7 @@ metadata:
 
 ## 版本口径
 
-包 semver（现 0.1.17）≠ schema 线（layout-constants / model-schema，现 `0.1`）；patch 不抬 schema。
+包 semver（现 0.1.19）≠ schema 线（layout-constants / model-schema，现 `0.1`）；patch 不抬 schema。
 
 ## 环境依赖