@topmindspace/tms-skills 0.1.0 → 2.0.0

package/CHANGELOG.md

@@ -1,26 +1,123 @@
-# Changelog
-
-## 0.1.0 — 2026-09-24
-
-首个公开版本。
-
-### 安装
-
-```bash
-npx @topmindspace/tms-skills install top-ppt-html
-# 或
-npx github:topmindspace/tms-skills install top-ppt-html
-```
-
-### 包含
-
-- 技能 **top-ppt-html**（品牌 TopPPT HTML）：单文件 HTML 报告 + 可编辑 16:9 PPTX
-- 安装器 CLI **tms-skills**（`list` / `install`）
-- 双通道分发：npm 钉版本 / GitHub 跟 HEAD
-- tag 发版自动：GitHub Release + npm publish；**Release 只保留最近 2 个**
-
-### 版本策略
-
-- 安装器 `@topmindspace/tms-skills` 与技能 `top-ppt-html` **各自独立**按 semver 演进
-- 默认 **patch / minor**；**major 仅用于**技能 id、CLI、注入标记等破坏性变更
-- 改代码 ≠ 发 npm：必须 bump 版本并打 tag（或手工 publish）
+# Changelog
+
+所有 monorepo 变更记录见本文件。
+
+## 2.0.0 — 2026-09-24（技能 9.1.0 · 仓库/技能更名 + 层级扁平化）
+
+### Changed
+- **仓库更名**：GitHub `topmindspace/topskills` → **`topmindspace/tms-skills`**（旧 URL 301）；本地根目录、`git remote`、npm 包名 `@topmindspace/tms-skills`、CLI `tms-skills` / `bin/tms-skills.js` 全部对齐。
+- **技能更名**：`top-slides-expert` / TopSlides Expert → **`top-ppt-html` / TopPPT HTML**（目录、frontmatter `name`、分发包、文档一致）。
+- **注入标记**：`__TOPSLIDES_*__` → `__TOPPPT_*__`；**环境变量**：`TOP_SLIDES_*` → `TOP_PPT_*`；**JS API**：`TopSlidesPptx` → `TopPptHtml`。
+- **层级扁平化**：移除冗余的 `skills/` 中间层，技能目录直接放在仓库根（`top-ppt-html/`）；安装器改为扫描根目录下含 `SKILL.md` 的技能目录。
+- 版本：技能 `9.0.1` → **`9.1.0`**（`layout-constants.json` `version: 9.1`）；monorepo `1.1.1` → **`2.0.0`**（包名/CLI/结构破坏性变更）。
+
+### Migration
+| Old | New |
+|-----|-----|
+| repo `topmindspace/topskills` | `topmindspace/tms-skills` |
+| npm `@topmindspace/topskills` | `@topmindspace/tms-skills` |
+| CLI `topskills` / `bin/topskills.js` | `tms-skills` / `bin/tms-skills.js` |
+| skill id / dir `top-slides-expert` | `top-ppt-html` |
+| brand `TopSlides Expert` | `TopPPT HTML` |
+| `skills/<id>/` | `<id>/`（仓库根） |
+| `__TOPSLIDES_*__` markers | `__TOPPPT_*__` |
+| `TOP_SLIDES_*` env | `TOP_PPT_*` |
+| `TopSlidesPptx` | `TopPptHtml` |
+
+无静默别名；旧标识见 `docs/PUBLISHING.md` 废弃清单，仅 CHANGELOG / 迁移说明可提及。
+
+## 1.1.1 — 2026-09-23（技能 9.0.1 · PPTX 往返与双形态修复）
+
+### Fixed
+- **PPTX 双形态载荷静默丢字**：`build_pptx.js` / `pptx-export.js` 用 `typeof x === 'object'` 区分 `[[t,d]…]` 与 `[{t,d,accent}…]`，但 `typeof [] === 'object'`，数组形态 steps/levels/lane/nodes 的标题与描述被读成 `undefined` 后落空（第 8 章 steps 仅 4/7 关键串）。改为 `isRec()`（非数组对象）判定，双引擎同步。
+- **PPTX 模型往返误报（挡交付）**：`validate_pptx.validate_model_roundtrip` 关键串比对语料原先只取幻灯片形状文本，把原生图表 `chart.labels`（落在 chart part）和 notes-only 字段（`lead` / `image.hint` 等）误判为 `MODEL_ROUNDTRIP_CONTENT_MISSING`；v9 将 `roundtripMin` 提到 0.80 后 9 个随包示例全部 FAIL。现语料改为 **形状文本 ∪ 演讲者备注 ∪ 关联 chart part 文本**（`_roundtrip_corpus` + `slide_chart_text`），`slide_notes` 真正参与内容比对；探针跳过 `hint`/`src`/`alt` 等元数据键。
+- 示例矩阵顶层金字塔描述过长触发 `CONTAINER_OVERFLOW`：顶层槽位收窄后改为「自动执行」；9 示例 `validate_pptx --strict --model` 全 0/0。
+
+### Changed
+- 随包示例按 v9.0 模板重建（内嵌 MODEL_SCHEMA 8.3 → 9.0）；4 张 `theme-overview*.png` 主题参考图刷新。
+- 版本：技能 `9.0.0` → **`9.0.1`**（`package.json` npm 语义化）；monorepo `1.1.0` → **`1.1.1`**。版本单源仍为 `layout-constants.json` `version: 9.0`。
+
+### Verified
+- 全链路回归通过：HTML strict + B 通道精导 strict 0/0 + A 通道 strict 0/0 + 双区组合页探针 + 深色主题探针 + `negative_tests` + 任务路由遍历 + python-pptx 双裁判。
+- 审计全绿：`audit_styles` / `audit_docs` / `audit_skill` / `audit_css`；`package_skill.py --check` 通过。
+
+## 1.1.0 — 2026-09-23（安装口径 + 隐私门禁）
+
+### Changed
+- **安装口径改为 GitHub 优先**：根 README / 技能 README / `bin/topskills.js` / `docs/PUBLISHING.md` 统一以 `npx github:topmindspace/topskills ...` 为默认；npm 包名降为「已 publish 后的可选通道」。补充「找不到这个包」排错说明。
+- `package.json` description 与新增 `npm run privacy` 脚本对齐上述口径。
+
+### Fixed
+- **隐私扫描器自身泄漏**：`ci_privacy_scan.py` 不再硬编码本机用户名；改为通用 home 用户名段检测 + 可选本地词表 `scripts/.privacy-deny.local`（gitignore）。
+- **扫描器自扫失明**：旧版词表写在 raw string 里导致字面量扫不到自己；新版附合成样本自检，并拒绝在扫描器源码中出现用户名形态 token。
+- **CI 日志二次泄漏**：扫描命中项一律脱敏输出（`xx***y(len=n)`），不回显密钥/路径原文。
+- 删除本地临时脚本 `scripts/_find_dup.py`（`scripts/_*` 约定为用后即删）。
+
+### Added
+- 隐私扫描扩展：GitHub/npm token、AWS key、Bearer、密钥赋值形态；`git ls-files` 禁止跟踪路径门禁（临时脚本 / `.env` / 密钥 / 缓存 / 智能体本地状态）。
+- `docs/PUBLISHING.md` 增加安装口径表、隐私扫描器自身约束、打包矩阵中的 `.privacy-deny.local` 行。
+
+## 9.0.0 — 2026-09-23（v9 质量整改）
+
+### Added
+- `references/reform-plan.md`：整体整改方案（根因 / 设定纠偏 / 复杂度收敛 / 门禁重建 / 图文演讲 V1–V4 / **布局语法**）。
+- **`references/layout-grammar.md`**：布局语法——12 列网格、预设骨架 **P1–P12**、元素级排版（图标/列表/卡/指标/图表/图文/结构图）、组合槽位、对齐与填充率。
+- `layout-constants.layoutSystem`：骨架/元素/填充率/多重心/对齐/`pageToPreset`/`defaultCharts` 单源。
+- v9 硬门禁：`HTML_TAG_IN_TEXT` / `TITLE_ONLY_PAGE` / `UNDERFILL_PAGE` / `CHART_SKEW_INVALID` / `CHART_OVERSIZE`。
+- **`LAYOUT_*` 门禁**：`NO_SKELETON` / `MULTI_FOCUS` / `ALIGN_DRIFT` / `SPACING_OFF_TOKEN` / `ICON_SIZE` / `LABEL_COLLIDE` / `FILL`。
+- scaffold：`PAGE_TO_PRESET` + `data-skel`/`data-page-type`/`layoutPreset`；图/exhibit 页强制 P8 主从；默认图表 8 核心轮换。
+- **`render_from_model.py`**：模型驱动生成 HTML（只填 REPORT_MODEL，`--inplace` 回填正文；`[n]` 自动转 cite）。
+- 结构图正交箭头：`engine.css` `.lane__arr`/`.arch__conn`/`.flow-*`；PPTX lane/diagram 线段+三角箭头。
+- `layoutSlots` 并入 `layout-constants`（`lib_layout_regions` 优先读 LC）；cards 双端兼容 `[[k,v]]`/`str`/`{t,d}`。
+- `cross_verify` 逐页文本改为 **≥80% 覆盖**（与 roundtripMin 同源）。
+- playbook §〇 排版总序 + §三-b 图文演讲 V1–V4；content-rules §二-b 模型字段禁 HTML 标签。
+- 负向测试 N15–N17（标签泄漏 / 极偏 donut / 模型夹带标签）。
+
+### Fixed
+- SKILL.md 超重与 references 内容重复（audit_skill）；CSS 未引用类清零（`flow-*` 接入 scaffold）。
+- render_from_model：agenda 对齐、Exhibit 顺序编号、donut/matrix/threecol/halftable/comparison 版式类映射。
+- cards 双端 points 形态兼容；页高估算按栅格折行 + 8% 容差。
+- 临时脚本与死代码清理；tech-design/README 单写路径对齐。
+
+### Docs
+- 根 README / PUBLISHING 中文化；技能 `description` 重写（445 字，做什么+何时用+何时不用）。
+- README 历史版本长文移除，统一看本 CHANGELOG；版本表述统一 v9.0。
+
+### Changed
+- 过空页、留白失衡（任一轴）、大图、文本溢出、内容保真（50%→80%）纳入 strict。
+- 废除「presentation 每页 1 张大图」；图表面积随信息复杂度。
+- scaffold `cards` 契约改为 `{title, points[]}`（与双引擎一致，修复空卡）。
+- `extract_model` 自动剥离模型字段中的 HTML 标签。
+- 承载口径扩展（ul/arch/lane/…）；页高估算改重承载 + 8% 静态容差。
+
+## 1.0.0 — 2026-09-23
+
+### Added
+- `@topmindspace/topskills` monorepo with `npx` installer (`topskills list|install`).
+- GitHub Actions CI (audit + package gate + privacy scan) and release workflow.
+- MIT license and release-ready root documentation.
+
+### Changed
+- Skill renamed **`topreport` / TopReport → `top-slides-expert` / TopSlides Expert**.
+- Environment variables renamed: `TOPREPORT_*` → `TOP_SLIDES_*`.
+- Injection markers renamed: `__TOPREPORT_*__` → `__TOPSLIDES_*__`.
+- JS API renamed: `TopReportPptx` → `TopSlidesPptx`.
+- Skill lives at `skills/top-slides-expert/` so more skills can join this repo.
+
+### Removed / deprecated
+- Legacy `topreport`, `TopReport`, `TOPREPORT_*`, `MIGA_*` identifiers (no silent aliases).
+- Private host path probes and IDE/agent local state from the publishable tree.
+- Internal optimization planning notes (`OPTIMIZATION-PLAN.md`) from the release tree.
+- Build artifacts (`dist/`, `node_modules/`, caches) from version control.
+
+### Migration
+| Old | New |
+|-----|-----|
+| skill id `topreport` | `top-slides-expert` |
+| brand `TopReport` | `TopSlides Expert` |
+| `TOPREPORT_NODE_EXE` | `TOP_SLIDES_NODE_EXE` |
+| `TOPREPORT_NODE_PATH` | `TOP_SLIDES_NODE_PATH` |
+| `TOPREPORT_BROWSER_CHANNEL` | `TOP_SLIDES_BROWSER_CHANNEL` |
+| `__TOPREPORT_*__` markers | `__TOPSLIDES_*__` |
+| `TopReportPptx` | `TopSlidesPptx` |
+| `MIGA_*` env | removed — use `TOP_SLIDES_*` |

package/README.md

@@ -1,102 +1,103 @@
-# tms-skills
-
-**TopMindspace 智能体技能 monorepo** — 可安装的智能体技能集合，当前包含 **top-ppt-html**。
-
-让 idea 飞，好想法被看见。
-
-## 技能一览
-
-| 技能 | 版本 | 做什么 |
-|------|------|--------|
-| [`top-ppt-html`](./top-ppt-html/) | 0.1.0 | 报告 / 演示 / 信息架构图：单文件 HTML + 版式保真的可编辑 16:9 PPTX |
-
-安装器包 [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills) 亦为 **0.1.0**（与技能版本各自独立演进）。
-
-更多技能以仓库根目录下的技能目录加入（每个目录含 `SKILL.md`）。
-
-## 安装
-
-两条通道，装出来同一套技能。**npm = 钉版本快照**；**GitHub = 跟仓库 HEAD**。
-
-### npm（推荐）
-
-```bash
-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.0 install top-ppt-html   # 钉版本
-```
-
-### GitHub 直装
-
-```bash
-npx github:topmindspace/tms-skills install top-ppt-html
-
-git clone https://github.com/topmindspace/tms-skills.git
-node tms-skills/bin/tms-skills.js install top-ppt-html
-```
-
-### 手工
-
-解压 GitHub Release 的 `top-ppt-html.zip` 到技能目录。
-
-安装器把根目录下的技能目录 `<id>/`（含 `SKILL.md`）复制到目标目录；智能体通过 frontmatter（`name` + `description`）发现技能。
-
-> **排错**：不要 `npm install <skill-id>`（技能 id 不是独立 npm 包）。「找不到包」→ 换 GitHub 直装，或 `--registry https://registry.npmjs.org/`。
-
-### 可选依赖（仅 PPTX 精导）
-
-HTML 生成零第三方依赖（Python 标准库）。PPTX 导出需要 Node + pptxgenjs：
-
-```bash
-cd <install-dir>/top-ppt-html
-npm install
-```
-
-## 仓库结构
-
-```
-tms-skills/
-├─ top-ppt-html/             # 技能（SKILL.md + assets + references + scripts + evals）
-├─ bin/tms-skills.js         # CLI：list / install
-├─ docs/                     # 发布规范
-├─ scripts/                  # 仓库级工具（隐私扫描）
-├─ .github/workflows/        # CI + Release
-├─ package.json              # @topmindspace/tms-skills
-├─ LICENSE · CHANGELOG.md · README.md
-```
-
-## 发布与同步
-
-| 动作 | GitHub | npm |
-|------|:------:|:---:|
-| push 到 main | 立即可见 | **不变** |
-| tag `vX.Y.Z` | Release + zip | **自动 publish** |
-
-- **push 不会更新 npm**；必须 bump 版本并打 tag。
-- **Release 只保留最近 2 个**（CI 自动清理）；npm 可钉任意历史版本。
-- 安装器与技能 **版本各自独立**；默认 patch/minor，major 仅破坏性变更。
-
-详见 [docs/PUBLISHING.md](./docs/PUBLISHING.md)。
-
-## CI
-
-| 工作流 | 触发 | 做什么 |
-|--------|------|--------|
-| `ci.yml` | push / PR | 打包门禁、审计、隐私扫描、CLI 冒烟 |
-| `release.yml` | tag `v*` | 技能 zip → Release；npm publish；Release 保留 2 个 |
-
-```bash
-npm run check && npm run audit && npm run privacy
-```
-
-## 开发新技能
-
-1. 根目录建 `<skill-id>/`，`SKILL.md` 的 `name` 与目录一致。
-2. 人类说明写 `README.md`；智能体入口保持 `SKILL.md`。
-3. 发布前 `scripts/package_skill.py --check`。
-4. 登记：根 README、`package.json` 的 `files`、`ci.yml`、`CHANGELOG.md`。
-
-## 许可证
-
-MIT © TopMindspace — [LICENSE](./LICENSE)
+# tms-skills
+
+**TopMindspace 智能体技能 monorepo** — 可安装的智能体技能集合，当前包含 **top-ppt-html**。
+
+让 idea 飞，好想法被看见。
+
+## 技能一览
+
+| 技能 | 状态 | 做什么 |
+|------|------|--------|
+| [`top-ppt-html`](./top-ppt-html/) | stable | 报告 / 演示 / 信息架构图：单文件 HTML + 版式保真的可编辑 16:9 PPTX |
+
+更多技能将直接以仓库根目录下的技能目录加入（每个技能一个目录，含 `SKILL.md`）。
+
+## 安装（GitHub 优先）
+
+公共 npm 源上的 `@topmindspace/tms-skills` **可能尚未发布**。默认用 GitHub 直装，不依赖 npm 注册：
+
+```bash
+# 列出已打包技能
+npx github:topmindspace/tms-skills list
+
+# 安装到 ./.agents/skills（默认；也会探测 .claude / .mimocode）
+npx github:topmindspace/tms-skills install top-ppt-html
+
+# 安装到指定目录
+npx github:topmindspace/tms-skills install top-ppt-html --to ./.claude/skills
+
+# 也可先 clone 再本地安装
+git clone https://github.com/topmindspace/tms-skills.git
+node tms-skills/bin/tms-skills.js install top-ppt-html
+```
+
+若已执行 `npm publish`（可选，见 [docs/PUBLISHING.md](./docs/PUBLISHING.md)），也可用 npm 包名：
+
+```bash
+npx @topmindspace/tms-skills list
+npx @topmindspace/tms-skills install top-ppt-html
+```
+
+> **排错**：若报「npm 公共源上找不到这个包」，说明 npm 包未发布（或包名写错）。请改用上面的 `npx github:topmindspace/tms-skills ...`，而不是 `npm install` / `npx <技能名>`。
+
+安装器会把根目录下的技能目录 `<id>/`（含 `SKILL.md`）复制到目标目录。智能体通过 `SKILL.md` frontmatter（`name` + `description`）发现技能。
+
+### 可选依赖（仅 PPTX 精导需要）
+
+HTML 生成只用 **Python 标准库**。原生 PPTX 导出需要 Node + 在技能目录安装 `pptxgenjs`：
+
+```bash
+cd <install-dir>/top-ppt-html
+npm install
+```
+
+## 仓库结构
+
+```
+tms-skills/
+├─ top-ppt-html/             # 技能目录（SKILL.md + assets + references + scripts + evals）
+├─ bin/tms-skills.js         # npx CLI（list / install）
+├─ docs/                     # 发布与贡献说明
+├─ scripts/                  # 仓库级工具（隐私扫描等）
+├─ .github/workflows/        # CI + Release
+├─ package.json              # @topmindspace/tms-skills
+├─ LICENSE
+├─ CHANGELOG.md
+└─ README.md
+```
+
+## 隐私与发布策略
+
+- 文档与技能中不得出现个人路径、主机名、凭据或本机智能体状态。
+- 不包含密钥、私有包源、绝对本地路径。
+- 构建产物（`dist/`、`node_modules/`、缓存、IDE 状态）一律 gitignore，不进包。
+- 触发文案与文档不得含私有/内部工具品牌。
+
+详见 [docs/PUBLISHING.md](./docs/PUBLISHING.md)。
+
+## CI / CD
+
+| 工作流 | 触发 | 做什么 |
+|--------|------|--------|
+| `ci.yml` | push / PR | 技能打包门禁、审计、隐私扫描、CLI 冒烟 |
+| `release.yml` | tag `v*` | 构建技能 zip + manifest，挂到 GitHub Release；可选 npm 发布 |
+
+本地推送前建议：
+
+```bash
+npm run check
+npm run audit
+npm run privacy
+```
+
+## 开发新技能
+
+1. 在仓库根目录创建 `<skill-id>/`，`SKILL.md` frontmatter 的 `name` 必须与目录名一致。
+2. 面向人的说明写在技能 `README.md`；智能体入口保持 `SKILL.md`。
+3. 发布前运行该技能的 `scripts/package_skill.py --check`。
+4. 在根 README 技能表与 `CHANGELOG.md` 登记。
+5. 不要提交本机 IDE/智能体状态或绝对机器路径。
+
+## 许可证
+
+MIT © TopMindspace — 见 [LICENSE](./LICENSE)。

package/package.json

@@ -1,48 +1,48 @@
-{
-  "name": "@topmindspace/tms-skills",
-  "version": "0.1.0",
-  "description": "TopMindspace 智能体技能 monorepo — 通过 GitHub npx 安装技能（top-ppt-html 等）。",
-  "license": "MIT",
-  "author": "TopMindspace",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/topmindspace/tms-skills.git"
-  },
-  "homepage": "https://github.com/topmindspace/tms-skills#readme",
-  "bugs": {
-    "url": "https://github.com/topmindspace/tms-skills/issues"
-  },
-  "keywords": [
-    "agent-skills",
-    "ai-skills",
-    "slides",
-    "pptx",
-    "report",
-    "top-ppt-html"
-  ],
-  "type": "commonjs",
-  "bin": {
-    "tms-skills": "bin/tms-skills.js"
-  },
-  "files": [
-    "bin",
-    "top-ppt-html",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "list": "node bin/tms-skills.js list",
-    "install:skills": "node bin/tms-skills.js install top-ppt-html",
-    "check": "python top-ppt-html/scripts/package_skill.py --check",
-    "privacy": "python scripts/ci_privacy_scan.py",
-    "audit": "python top-ppt-html/scripts/audit_styles.py && python top-ppt-html/scripts/audit_docs.py && python top-ppt-html/scripts/audit_skill.py && python top-ppt-html/scripts/audit_css.py",
-    "package:skill": "python top-ppt-html/scripts/package_skill.py"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@topmindspace/tms-skills",
+  "version": "2.0.0",
+  "description": "TopMindspace 智能体技能 monorepo — 通过 GitHub npx 安装技能（top-ppt-html 等）。",
+  "license": "MIT",
+  "author": "TopMindspace",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/topmindspace/tms-skills.git"
+  },
+  "homepage": "https://github.com/topmindspace/tms-skills#readme",
+  "bugs": {
+    "url": "https://github.com/topmindspace/tms-skills/issues"
+  },
+  "keywords": [
+    "agent-skills",
+    "ai-skills",
+    "slides",
+    "pptx",
+    "report",
+    "top-ppt-html"
+  ],
+  "type": "commonjs",
+  "bin": {
+    "tms-skills": "bin/tms-skills.js"
+  },
+  "files": [
+    "bin",
+    "top-ppt-html",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "list": "node bin/tms-skills.js list",
+    "install:skills": "node bin/tms-skills.js install top-ppt-html",
+    "check": "python top-ppt-html/scripts/package_skill.py --check",
+    "privacy": "python scripts/ci_privacy_scan.py",
+    "audit": "python top-ppt-html/scripts/audit_styles.py && python top-ppt-html/scripts/audit_docs.py && python top-ppt-html/scripts/audit_skill.py && python top-ppt-html/scripts/audit_css.py",
+    "package:skill": "python top-ppt-html/scripts/package_skill.py"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/top-ppt-html/README.md

@@ -3,7 +3,7 @@
 **让 idea 飞，好想法被看见。** 一套面向 AI 智能体的商务报告生成技能：把想法、调研、分析、架构方案，变成**专业级的 HTML 报告 + 版式保真的可编辑 PPTX**。
 
 - 技能标识：`top-ppt-html`（安装/打包目录名与此一致）；品牌名：**TopPPT HTML**
-- 版本：**v0.1.0** · 完整规范见 `SKILL.md`（智能体入口）+ `references/playbook.md`（唯一常读入口）+ `references/layout-grammar.md`（排版）+ 其余按需 L2
+- 版本：**v9.1.0** · 完整规范见 `SKILL.md`（智能体入口）+ `references/playbook.md`（唯一常读入口）+ `references/layout-grammar.md`（排版）+ 其余按需 L2
 
 ## 一、技能简介
 
@@ -30,25 +30,24 @@
 
 ### 安装
 
-本技能是 [`tms-skills`](https://github.com/topmindspace/tms-skills) monorepo 中的一个技能包（路径 `top-ppt-html/`）。npm 安装器已发布：[`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills)。
+本技能是 [`tms-skills`](https://github.com/topmindspace/tms-skills) monorepo 中的一个技能包（路径 `top-ppt-html/`）。**推荐从 GitHub 直装**（不依赖 npm 是否已发布）：
 
 ```bash
-# 推荐 · npm
-npx @topmindspace/tms-skills install top-ppt-html
-# 或指定目录
-npx @topmindspace/tms-skills install top-ppt-html --to ./.agents/skills
-
-# 跟仓库 HEAD · GitHub 直装
 npx github:topmindspace/tms-skills install top-ppt-html
-
-# clone 后本地安装
+# 或指定目录
+npx github:topmindspace/tms-skills install top-ppt-html --to ./.agents/skills
+# 或 clone 后本地安装
 git clone https://github.com/topmindspace/tms-skills.git
 node tms-skills/bin/tms-skills.js install top-ppt-html
 ```
 
-> **GitHub 更新不会自动进 npm。** 日常可钉 npm 版本；要最新技能用 GitHub 直装，或等 maintainer 打 tag 发版。
->
-> 「找不到这个包」→ 换 GitHub 直装，或 `--registry https://registry.npmjs.org/`（镜像索引可能滞后）。不要 `npm install top-ppt-html`（技能 id 不是独立 npm 包）。
+若 `@topmindspace/tms-skills` 已发布到 npm（可选步骤），也可：
+
+```bash
+npx @topmindspace/tms-skills install top-ppt-html
+```
+
+> 报「npm 公共源上找不到这个包」= npm 包未发布或包名不对，改用 GitHub 直装即可。
 
 也可将本目录（或 GitHub Release 附件 `top-ppt-html.zip` 解压结果）复制到智能体技能目录，目录名保持 `top-ppt-html`。技能识别面为 `SKILL.md`（frontmatter 的 `name` / `description` 即触发描述）。
 
@@ -245,10 +244,10 @@ python scripts/package_skill.py           # → dist/top-ppt-html.zip + dist/top
 
 ## 七、版本、规范与兼容
 
-- **当前发布版**：v0.1.0（风格语汇 styleIdentity · 布局语法 · 模型单写 · 硬门禁）。**版本单源 = `scripts/layout-constants.json` `version`**；`model-schema.json` / `layoutSlots` 同步该值；`package_skill.py` 与 `sync_runtime.py` 校验一致。
+- **当前发布版**：v9.1.0（仓库/技能更名 `top-ppt-html` · 层级扁平化 · 注入标记 `__TOPPPT_*__`）。**版本单源 = `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`。
+- **工作流（v9 单写）**：`scaffold_report.py` → 只填 `REPORT_MODEL` → `render_from_model.py --inplace` → `validate_report --strict`（含 PPTX 再走 extract/build/validate_pptx）。
+- **变更流水**：见仓库根目录 `CHANGELOG.md`（本 README 不再堆叠版本长文）。
+- **命名**：`top-ppt-html`；注入标记 `__TOPPPT_*__`；环境变量 `TOP_PPT_NODE_*`。旧标识 `topreport` / `top-slides-expert` / `TopSlides*` / `TOPREPORT_*` / `TOPSLIDES_*` / `MIGA_*` 已移除。
 - **发布门禁**：`package_skill.py --check` 通过后产出 `dist/top-ppt-html.zip` + manifest（SHA-256）。

package/top-ppt-html/SKILL.md

@@ -105,7 +105,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`。
+- **v9 门禁**：标签泄漏/空页/极偏图/简单大图等见 `layout-constants.qualityGates` 与 `reform-plan.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 类覆盖率 · 报告制）。