@topmindspace/tms-skills 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,3 +1,63 @@
+## [0.3.1] - 2026-09-29
+
+> 根包 0.3.0 → **0.3.1**（patch）；4 个技能 `version` 保持不动（top-ppt-html 0.1.19，其余 0.1.0）。
+> 整仓同 tag 发版，技能 `version` 独立演进（见 docs/PUBLISHING.md）。
+
+### topmind-cover：风格库按爆款封面重沉淀 + 样张重制
+
+- `references/cover-styles.md` 按 7 张爆款参考封面 + Manus 实战封面重沉淀为 **8 种风格**：
+  爆款干货（`gan-huo`）/ 巨字宣言（`big-type`）/ 品牌发布（`brand-launch`）/
+  教程步骤（`tutorial-steps`）/ IP 趣味（`ip-fun`）/ 资讯快报（`news-flash`）/
+  极简留白（`minimal`，保留）/ 杂志编辑（`magazine`，保留），
+  每种含适用场景、构图公式、配色 hex、标题写法规范（4~8 字、数字/关键词彩色突出）、
+  中英 prompt 配方、避坑；删除旧 6 风格。
+- `assets/examples/` 样张全部重制：**16 张**（8 风格 × 1200×675 主图 + 900×383 公众号中央裁剪版）
+  + `overview.png`（8 宫格总览图），逐张目检（标题逐字准确、无乱码、中央 60% 安全区），
+  7 次返工均为"底部元素超出安全区"；旧 12 张移除。
+- 提炼规律：标题字巨大化（占画面高 22%~45%）、左文右图通用分区、三层文字结构
+  （大标题 + 胶囊/笔刷副标题 + 底部标签条）、数字前置造冲击、背景极简浅色。
+- 根 README（中/英）、cover README（中/英）、cover SKILL.md 嵌入总览图（GitHub 绝对 URL）
+  + 8 风格一行式索引；用法"6 选 1"→"8 选 1"。
+
+### bug 修复
+
+- topmind-wechat-post `scripts/md2wechat.py`：本地图片文件缺失时未登记进"图片上传清单"
+  （用户按清单补图会漏传）；现登记 `⚠ 本地文件缺失` 行并计入"图片 N 张"计数。
+  HTML 仍保留断链占位（设计选择），清单已标注。
+
+## [0.3.0] - 2026-09-29
+
+> 根包 0.2.0 → **0.3.0**（minor，新功能）；4 个技能 `version` 保持不动（top-ppt-html 0.1.19，其余 0.1.0）。
+> 整仓同 tag 发版，技能 `version` 独立演进（见 docs/PUBLISHING.md）。
+
+### topmind-cover：封面风格库 + 12 张示例图（新功能）
+
+- `references/cover-styles.md` 扩为 **6 种风格库**：震撼大字报（`big-poster`）/ 科技未来感（`tech-future`）/
+  杂志编辑风（`magazine`）/ 极简留白（`minimal`）/ 国潮插画（`guochao`）/ 赛博故障艺术（`cyber-glitch`），
+  每种含适用场景、配色 hex、字体建议、中英 prompt 配方、避坑。
+- `assets/examples/` 新增 **12 张示例图**（6 风格 × 1200×675 主图 + 900×383 公众号中央裁剪版，共约 6.4MB），
+  附 `assets/examples/README.md`（清单 + 安全区说明 + 复用声明），随 npm 包发布。
+- SKILL.md 工作流新增"**步骤 0 选风格**"（三步必做：按题材 6 选 1 → 看示例图 → 按配方组 prompt）。
+- 标题**中央垂直 60% 安全区**上升为设计铁律（风格库新增"安全区铁律"章节）：标题字与关键主体
+  上下各预留 13%+，否则 900×383 中央裁剪会切掉标题。
+
+### 最佳实践整改
+
+- top-ppt-html / topmind-wechat-post 的 SKILL.md `description` 改**第三人称**（降误触发）；
+  topmind-cover `description` 同步微调（"一次配齐"→"全流程覆盖"），`triggers` 新增 `缩略图` / `thumbnail`。
+- topmind-wechat-post：站外取源坑与回推命令串收敛到 `references/workflow.md`，SKILL.md 只留索引；
+  新增跨技能路由索引（封面配图 → topmind-cover，X 长文 → topmind-x-article）；
+  二级标题序号由排版层自动生成（不再手写）。
+- 各技能 README（中/英）与 SKILL.md 对齐：cover 新增风格库与示例图章节、用法改"步骤 0 选风格"；
+  x-article 转换规则补"分隔线→空行"。
+
+### bug 修复
+
+- topmind-x-article `scripts/md2x.py`：`---` / `***` / `___` 分隔线转**空行**（原逻辑误当 frontmatter 吞掉）；
+  `***粗斜体***` 先去三重星号再处理 `**` / `__` / `*`，不再残留星号。
+- topmind-cover `scripts/crop-cover.py`：移除 `--slug` 悬空参数
+  （用法与文档统一：`crop-cover.py <主图> --out-dir <包>/images/`）。
+
 ## [0.2.0] - 2026-09-29
 
 ### 新增三个写作/配图技能

package/README.en.md

@@ -9,17 +9,56 @@
 [![CI](https://img.shields.io/github/actions/workflow/status/topmindspace/tms-skills/ci.yml?style=flat-square&label=CI)](https://github.com/topmindspace/tms-skills/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
 
-**TopMindspace agent-skills monorepo** — turn good ideas into stage-ready **formal business presentations**.
+**TopMindspace agent-skills monorepo** — formal business presentations, WeChat articles, X long-form posts, cover art: four skills, one repo.
 
-Primary skill **[top-ppt-html](./top-ppt-html/)**: **HTML + PPT dual delivery**, built for **demo reports / formal business decks**.
+### top-ppt-html · Formal business presentations
 
-### Why top-ppt-html
+Built for **demo reports / formal business decks**: **HTML + PPT dual delivery**. Day-to-day, present with single-file HTML like slides; export **high-fidelity editable PPTX** when needed (charts carry data you can annotate). MD3-inspired: fitting information density, restrained type / shapes / color. Formal business presenting — not decoration.
 
-Plenty of PPT skills exist — some lean gadgety, some dump consulting density by default. **top-ppt-html** takes a different path:
+```bash
+npx @topmindspace/tms-skills install top-ppt-html
+```
+
+### topmind-wechat-post · WeChat article authoring
+
+Full lifecycle for WeChat articles: delivery package, review & rewrite, three quality gates (facts / logic / de-AI-flavor), WeChat inline typography (images must be embedded), publish checklist and status sync. Python stdlib only — zero dependencies.
+
+```bash
+npx @topmindspace/tms-skills install topmind-wechat-post
+```
+
+### topmind-x-article · One-click X long-form publishing
+
+Markdown draft → paste-ready plain text (`md2x.py` adapts to the X Article editor: images → `[图N]`, tables → "item: value" lists) + cover art + publish checklist. Publishing is done by hand-pasting; fetch the text back for verification after posting.
+
+```bash
+npx @topmindspace/tms-skills install topmind-x-article
+```
 
-- **Dual delivery**: day-to-day, present with **single-file HTML** like slides; export **high-fidelity editable PPTX** when needed (charts carry data you can annotate)
-- **MD3-inspired**: spatial layout, **fitting information density**, restrained type / shapes / color
-- **Stage-ready**: clear, atmospheric, multi-style — formal business presenting, not decoration
+### topmind-cover · Cover art generation
+
+Shared cover art for X long-form and WeChat: striking, eye-catching, theme-focused. Built-in **8-style cover style library** (viral dry-goods / giant-type manifesto / brand launch / tutorial steps / fun IP / news flash / minimalist / editorial magazine — each with use cases, hex palettes, font suggestions, Chinese+English prompt recipes) + **17 dual-size example images** (`assets/examples/`, shipped with the package): **pick a style → check the example → compose the prompt from the recipe**, then one-click crop to both platform sizes with `crop-cover.py` (X 1200×675, WeChat 900×383).
+
+```bash
+npx @topmindspace/tms-skills install topmind-cover
+```
+
+**Style gallery** (8-style overview; full-size per-style shots in `topmind-cover/assets/examples/<style>.png`, recipes in [`references/cover-styles.md`](./topmind-cover/references/cover-styles.md)):
+
+<p align="center">
+  <img src="https://github.com/topmindspace/tms-skills/raw/main/topmind-cover/assets/examples/overview.png" alt="topmind-cover · 8 cover-style overview" width="960" />
+</p>
+
+| Style | Best for |
+|-------|----------|
+| Viral dry-goods `gan-huo` | Tested picks, reviews, roundups; default for first-person "I tried it all for you" posts |
+| Giant-type manifesto `big-type` | Opinion pieces, deep essays, launch manifestos; default for one-sentence-stance pieces |
+| Brand launch `brand-launch` | Product launches, version updates, official best practices / whitepapers; first choice when a brand is the subject |
+| Tutorial steps `tutorial-steps` | Tutorials, onboarding guides, step-by-step walkthroughs, beginner-proof recipes |
+| Fun IP `ip-fun` | Case studies, data recaps, retrospectives, series (part 1 / part 2) |
+| News flash `news-flash` | News, flashes, hot-topic explainers, interview teasers, "myth-busting" angles |
+| Minimal `minimal` | Essays, book reviews, light takes, lifestyle musings; WeChat "light reading" pieces |
+| Editorial magazine `magazine` | In-depth interviews, profiles, business analysis, year-in-review; when "craft / trust" matters |
 
 > Let ideas fly — make good thinking visible.
 
@@ -27,7 +66,7 @@ Plenty of PPT skills exist — some lean gadgety, some dump consulting density b
   <img src="docs/assets/tms-skills-banner.png" alt="tms-skills · top-ppt-html — formal business presentations" width="960" />
 </p>
 
-> **Warning**: do not install `@topmindspace/tms-skills@^2` (2.0.0–2.1.1 deprecated). Current line is **0.1.x** (`latest`).
+> **Warning**: do not install `@topmindspace/tms-skills@^2` (2.0.0–2.1.1 deprecated). Current line is **0.2.x** (`latest`).
 
 ## Craft at a glance
 
@@ -70,7 +109,7 @@ Plenty of PPT skills exist — some lean gadgety, some dump consulting density b
 | Fullscreen | **F** | Immersive present mode |
 | Collapse toolbar | **B** | Mini bar (brand + expand); remembers per file |
 
-See [top-ppt-html/README.md](./top-ppt-html/README.md) and [SKILL.md](./top-ppt-html/SKILL.md).
+See [top-ppt-html/README.md](./top-ppt-html/README.md#html-header-toolbar) and [SKILL.md](./top-ppt-html/SKILL.md).
 
 ## Skills
 
@@ -79,9 +118,15 @@ See [top-ppt-html/README.md](./top-ppt-html/README.md) and [SKILL.md](./top-ppt-
 | [`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 |
 | [`topmind-wechat-post`](./topmind-wechat-post/) | **0.1.0** | WeChat article lifecycle: package, review, 3 quality gates, inline typography & publish checklist |
 | [`topmind-x-article`](./topmind-x-article/) | **0.1.0** | X long-form one-click publish: Markdown → paste-ready plain text + cover + checklist |
-| [`topmind-cover`](./topmind-cover/) | **0.1.0** | Cover art for X / WeChat: striking, theme-focused; size specs + style templates + crop tooling |
+| [`topmind-cover`](./topmind-cover/) | **0.1.0** | Cover art for X / WeChat: striking, theme-focused; 8-style cover style library + 17 dual-size example images, size specs + crop tooling |
+
+Installer [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills) is **0.3.1** (whole-repo same-tag releases).
+
+### topmind-cover · Cover style library
+
+Style index and the 8-grid overview are in the topmind-cover skill intro above.
 
-Installer [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills) is **0.2.0** (whole-repo same-tag releases).
+**Three steps to a cover**: ① pick 1 of 8 styles by topic → ② check the matching example in [`topmind-cover/assets/examples/`](./topmind-cover/assets/examples/) → ③ compose the prompt from that style's recipe in [`references/cover-styles.md`](./topmind-cover/references/cover-styles.md). 17 example images (8 styles × 1200×675 master + 900×383 WeChat center-crop + `overview.png` 8-grid overview, ~7.5MB) ship with the npm package; **safe-zone rule**: title text and key subject must stay inside the central vertical 60% safe zone.
 
 ## Install
 
@@ -91,7 +136,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.2.0 install top-ppt-html   # pin
+npx @topmindspace/tms-skills@0.3.1 install top-ppt-html   # pin
 ```
 
 ```bash

package/README.md

@@ -7,17 +7,56 @@
 [![CI](https://img.shields.io/github/actions/workflow/status/topmindspace/tms-skills/ci.yml?style=flat-square&label=CI)](https://github.com/topmindspace/tms-skills/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
 
-**TopMindspace 智能体技能 monorepo** — 把好想法做成可上台的正式商务演示。
+**TopMindspace 智能体技能 monorepo** —— 演示报告、公众号文章、X 长文、封面配图：四个技能，一个仓库。
 
-当前主技能 **[top-ppt-html](./top-ppt-html/)**：**HTML + PPT 双交付**，为**演示报告 / 正式商务演示**而生。
+### top-ppt-html · 正式商务演示
 
-### 为什么是 top-ppt-html
+为**演示报告 / 正式商务演示**而生：**HTML + PPT 双交付**。日常用单文件 HTML 等同幻灯片演示；需要时再导出**高保真可编辑 PPTX**（图表带数据、可标注）。参考 MD3：合适的信息密度、克制的文字 / 图形 / 形状 / 颜色。主场是正式商务演示，不是 gadget。
 
-市面 PPT 技能很多：有的偏花哨装饰，有的偏咨询 dump。**top-ppt-html** 走另一条路——
+```bash
+npx @topmindspace/tms-skills install top-ppt-html
+```
+
+### topmind-wechat-post · 公众号创作
+
+公众号文章全生命周期：交付包、审校改写、质量三关（事实 / 逻辑 / 去 AI 味）、微信内联排版（图片必内嵌）、发布清单与状态同步。脚本纯 Python 标准库，零依赖。
+
+```bash
+npx @topmindspace/tms-skills install topmind-wechat-post
+```
+
+### topmind-x-article · X 长文一键发布
+
+Markdown 原稿 → 可直接粘贴的纯文本（`md2x.py` 按 X Article 编辑器支持转制：图片→`[图N]`、表格→"项：值"列表）+ 封面图 + 发布清单。发布走人工粘贴，发布后抓回核对。
+
+```bash
+npx @topmindspace/tms-skills install topmind-x-article
+```
 
-- **双交付**：日常用**单文件 HTML**等同幻灯片演示；需要时再导出**高保真可编辑 PPTX**（图表带数据、可标注）
-- **参考 MD3**：整体空间布局、**合适的信息密度**、克制的文字 / 图形 / 形状 / 颜色
-- **产出即上台**：直观、美观大气、风格多样；主场是正式商务演示，不是 gadget
+### topmind-cover · 封面配图生成
+
+X 长文与公众号共用的封面图：震撼、醒目、主题突出。内置 **8 种封面风格库**（爆款干货 / 巨字宣言 / 品牌发布 / 教程步骤 / IP 趣味 / 资讯快报 / 极简留白 / 杂志编辑，含适用场景、配色 hex、字体建议、中英 prompt 配方）+ **17 张双尺寸示例图**（`assets/examples/`，随包发布）：**选风格 → 看示例 → 按配方组 prompt** 三步出图，`crop-cover.py` 一键裁出双平台尺寸（X 1200×675、公众号 900×383）。
+
+```bash
+npx @topmindspace/tms-skills install topmind-cover
+```
+
+**封面风格样张**（8 宫格总览；单风格大图见 `topmind-cover/assets/examples/<风格>.png`，配方见 [`references/cover-styles.md`](./topmind-cover/references/cover-styles.md)）：
+
+<p align="center">
+  <img src="https://github.com/topmindspace/tms-skills/raw/main/topmind-cover/assets/examples/overview.png" alt="topmind-cover · 8 封面风格总览" width="960" />
+</p>
+
+| 风格 | 适用场景 |
+|------|----------|
+| 爆款干货 `gan-huo` | 干货清单、评测、盘点、实测筛选；"我替你试完了/筛完了"类第一人称实测文默认选它 |
+| 巨字宣言 `big-type` | 观点评论、深度长文、产品/版本发布宣言；"一句话立场"类文章默认选它 |
+| 品牌发布 `brand-launch` | 产品发布、版本更新、官方最佳实践/白皮书；有明确品牌主体的内容首选 |
+| 教程步骤 `tutorial-steps` | 教程、上手指南、分步实操、保姆级攻略 |
+| IP 趣味 `ip-fun` | 实战案例、数据战报、复盘、系列连载（上/下篇） |
+| 资讯快报 `news-flash` | 资讯、快讯、热点解读、人物专访预告、"祛魅/揭秘"类选题 |
+| 极简留白 `minimal` | 随笔、书评、轻观点、生活感悟；公众号"轻阅读"类文章 |
+| 杂志编辑 `magazine` | 深度访谈、人物特写、商业分析、年度盘点；需要"质感/信任感"时用它 |
 
 > 让 idea 飞，好想法被看见。
 
@@ -25,7 +64,7 @@
   <img src="docs/assets/tms-skills-banner.png" alt="tms-skills · top-ppt-html — formal business presentations" width="960" />
 </p>
 
-> **警告**：不要安装 `@topmindspace/tms-skills@^2`（2.0.0–2.1.1 已弃用）。当前线 **0.1.x**（`latest`）。
+> **警告**：不要安装 `@topmindspace/tms-skills@^2`（2.0.0–2.1.1 已弃用）。当前线 **0.2.x**（`latest`）。
 
 ## 一眼看到工艺
 
@@ -77,9 +116,15 @@
 | [`top-ppt-html`](./top-ppt-html/) | **0.1.19** | 正式商务演示：HTML 可翻页 + 16:9 可编辑 PPTX；双交付 · MD3 密度克制；三模式 × 九风格；strict 0/0 |
 | [`topmind-wechat-post`](./topmind-wechat-post/) | **0.1.0** | 公众号文章全生命周期：交付包、审校改写、质量三关、微信内联排版与发布清单 |
 | [`topmind-x-article`](./topmind-x-article/) | **0.1.0** | X 长文一键发布：Markdown 原稿转可直接粘贴的纯文本 + 封面图 + 发布清单 |
-| [`topmind-cover`](./topmind-cover/) | **0.1.0** | 文章封面配图（X / 公众号共用）：震撼醒目主题突出，尺寸规范 + 风格模板 + 裁剪落盘 |
+| [`topmind-cover`](./topmind-cover/) | **0.1.0** | 文章封面配图（X / 公众号共用）：震撼醒目主题突出；8 风格封面风格库 + 17 张双尺寸示例图，尺寸规范 + 裁剪落盘 |
+
+安装器 [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills) 为 **0.3.1**（整仓同 tag 发版）。
+
+### topmind-cover · 封面风格库
+
+风格索引与 8 宫格总览样张见上文 topmind-cover 技能介绍处。
 
-安装器 [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills) 为 **0.2.0**（整仓同 tag 发版）。
+**三步出图**：① 按题材从 8 风格选 1 → ② 看 [`topmind-cover/assets/examples/`](./topmind-cover/assets/examples/) 对应示例图 → ③ 按 [`references/cover-styles.md`](./topmind-cover/references/cover-styles.md) 该风格的 prompt 配方组 prompt。17 张示例图（8 风格 × 1200×675 主图 + 900×383 公众号中央裁剪版 + `overview.png` 8 宫格总览，约 7.5MB）随 npm 包发布；**安全区铁律**：标题字与关键主体必须落在画面中央垂直 60% 安全区内。
 
 ## 安装
 
@@ -89,7 +134,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.19 install top-ppt-html   # 钉版本
+npx @topmindspace/tms-skills@0.3.1 install top-ppt-html   # 钉版本
 ```
 
 ```bash

package/bin/tms-skills.js

@@ -101,10 +101,37 @@ function copyDir(src, dest) {
     } else if (entry.isFile()) {
       if (entry.name.endsWith('.pyc')) continue;
       fs.copyFileSync(s, d);
+    } else {
+      console.warn(`warning: skipping non-regular file: ${s}`);
     }
   }
 }
 
+function normPath(p) {
+  const s = path.resolve(p);
+  return process.platform === 'win32' ? s.toLowerCase() : s;
+}
+
+/** 安装目标守卫（审计 严重-2）：
+ *  dest == 技能源目录  → --force 会先 rmSync 删掉源目录，再"成功"装出空目录（数据丢失 + 虚假成功）；
+ *  dest 在源目录内部  → copyDir 无限递归复制直至 ENAMETOOLONG，并留下垃圾目录树。
+ *  path.resolve 归一化后比对（dest === src，或 dest 以 src + 路径分隔符开头），
+ *  Windows 下额外做大小写归一。无论是否 --force，一律拒绝。
+ */
+function assertDestOutsideSource(src, dest) {
+  const absSrc = normPath(src);
+  const absDest = normPath(dest);
+  if (absDest === absSrc || absDest.startsWith(absSrc + path.sep)) {
+    die(
+      `Refusing to install into the skill's own directory tree.\n` +
+        `  skill source: ${absSrc}\n` +
+        `  destination:  ${absDest}\n` +
+        `Choose a --to directory outside the skill source ` +
+        `(installing into it would delete or recurse into the source).`
+    );
+  }
+}
+
 function install(skillId, targetRoot, { force = false } = {}) {
   assertSkillId(skillId);
   const src = skillDir(skillId);
@@ -112,6 +139,7 @@ function install(skillId, targetRoot, { force = false } = {}) {
     die(`Skill not found: ${skillId}\nAvailable: ${listSkillIds().join(', ') || '(none)'}`);
   }
   const dest = path.join(targetRoot, skillId);
+  assertDestOutsideSource(src, dest);
   fs.mkdirSync(targetRoot, { recursive: true });
   if (fs.existsSync(dest)) {
     if (!force) {
@@ -126,17 +154,19 @@ function install(skillId, targetRoot, { force = false } = {}) {
   console.log(`Installed ${skillId}`);
   console.log(`  from ${src}`);
   console.log(`  to   ${dest}`);
-  console.log('');
-  console.log('Optional (PPTX export only):');
-  console.log(`  cd "${dest}" && npm install`);
+  if (skillId === 'top-ppt-html') {
+    console.log('');
+    console.log('Optional (PPTX export only):');
+    console.log(`  cd "${dest}" && npm install`);
+  }
 }
 
 function usageText() {
   return `tms-skills — install TopMindspace agent skills
 
 Usage:
-  tms-skills list
-  tms-skills install <skill-id> [--to <dir>] [--force|-f]
+  tms-skills list|ls
+  tms-skills install <skill-id> [--to|-t <dir>] [--force|-f]
   tms-skills help
 
 Examples (npm recommended when published):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topmindspace/tms-skills",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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.19** (same tag as `@topmindspace/tms-skills@0.1.19`)
+- Version: **v0.1.19** (same tag as `@topmindspace/tms-skills@0.3.1`)
 - **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.19 install top-ppt-html
+npx @topmindspace/tms-skills@0.3.1 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.19**（与 `@topmindspace/tms-skills@0.1.19` 同 tag）
+- 版本：**v0.1.19**（与 `@topmindspace/tms-skills@0.3.1` 同 tag）
 - **智能体入口**：`SKILL.md` → `references/playbook.md`（L1）→ L2 按需
 - **人类维护者**：本 README（安装 / 命令 / 目录）；勿把本文件当生成规范
 
@@ -170,7 +170,7 @@ top-ppt-html/
 │  ├─ illustration-layout.md  #   L2 插画/配图 brief                                   │
 │  └─ …（modes / styles / design-system / content-rules / icons / default-surface /     │
 │        outline-design / pptx-export / high-fidelity / failure-modes / tech-design；  │
-│        归档见 docs/archive/refs/）                                                   │
+│        归档见 ../docs/archive/refs/）                                                   │
 ├─ evals/                       # Eval 框架（结果/过程/风格/效率四类目标）    │
 │  ├─ prompts.csv               #   14 条 prompt（显式/隐式/上下文/负对照）   │
 │  ├─ rubric.schema.json        #   风格目标结构化评分契约                    │
@@ -223,7 +223,7 @@ python scripts/check_triggers.py
 | `references/presentation-craft.md` | Mode A L1.5 工艺（反截断 / 大气正式） |
 | `assets/examples/` | 3 份黄金样张（每模式 1）+ TopMind showcase |
 | `evals/trigger-queries.json` | description 触发正/负例；`check_triggers.py` |
-| `docs/archive/` | 历史规范 / 旧示例 |
+| `../docs/archive/` | 历史规范 / 旧示例 |
 
 风格画廊与主题参考图：`assets/theme-overview*.png`（Gate 0）。完整规范索引见 playbook §十。
 

package/top-ppt-html/SKILL.md

@@ -1,11 +1,10 @@
 ---
 name: top-ppt-html
-description: "Use when 用户要做报告、演示、汇报、PPT、slides、deck、路演，或写研究报告、分析报告、咨询报告、白皮书、调研、评测、对标、经营分析、复盘、项目汇报、商务/HTML/网页报告，或做架构图、拓扑图、流程图、泳道图、方案图，或把材料做成可视化报告并导出 HTML/PPT/PPTX，或优化排版/版式/配色/图文布局，或要快速模式/fast/直接生成/一键出稿/少问一句。TopPPT HTML：正式商务演示双交付——零外链可翻页 HTML（日常上台）+ 高保真可编辑 16:9 PPTX（按需）；MD3 式密度克制；核心=版式·排版·色彩·内容；三模式（A 演示 / B 研究 / C 架构）× 9 风格。Do NOT use for 纯代码工程、非报告类网页或应用开发、视频/图片生成、直接改写已有 Word/PPT 源文件本身。"
+description: "为正式商务演示把材料做成可视化报告：零外链可翻页 HTML（日常上台）+ 高保真可编辑 16:9 PPTX（按需）双交付；MD3 式密度克制；三模式（A 演示 / B 研究 / C 架构）× 9 风格。Use when 用户要做报告、演示、汇报、PPT、slides、deck、路演，或写研究报告、分析报告、咨询报告、白皮书、调研、评测、对标、经营分析、复盘、项目汇报、商务/HTML/网页报告，或做架构图、拓扑图、流程图、泳道图、方案图，或把材料做成可视化报告并导出 HTML/PPT/PPTX，或优化报告的排版/版式/配色/图文布局，或做报告时说快速模式/fast/直接生成/一键出稿/少问一句。Do NOT use for 纯代码工程、非报告类网页或应用开发、视频/图片生成、直接改写已有 Word/PPT 源文件本身。"
 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.19"
-  author: TopMindspace
+version: 0.1.19
+author: TopMindspace
 ---
 # TopPPT HTML
 
@@ -88,7 +87,7 @@ metadata:
 **L2 一览**（命中条件与逐任务只读清单的**详表以 playbook §十为准**，此处仅索引）：
 
 - 模式契约与锁定版式 → `references/modes.md` · 完整路径七步 → `references/outline-design.md`
-- **A/Fast L1.5 → `default-surface.md` + `presentation-craft.md`** · 骨架 `layout-grammar.md` §七 · 插画 `illustration-layout.md`
+- **A/Fast L1.5 → `default-surface.md` + `presentation-craft.md`** · 骨架 `layout-grammar.md` §七 · 插画规范（L2）→ `illustration-layout.md`
 - 组件/版式**代码** → `components.md` · 页型表 `page-type-matrix.md` · 图表门面 `charts.md` + 决策树 `chart-decision-tree.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`

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

@@ -64,7 +64,7 @@
 
 ---
 
-> **六项问询**（一次问完、全部带意图推荐、不选即按推荐走）：①意图与模式推荐合并确认（本表）②篇幅（A 8–15 页 / B 12–25 页 / C 1–3 张图）③风格 9 套（始终选择——风格是 HTML 皮肤，与交付格式无关）④**亮暗主题**（浅色默认 / 深色沉浸；石墨深灰默认深色；HTML 与 PPTX 同主题导出——`REPORT_MODEL.theme`）⑤交付格式（仅 HTML / HTML+PPTX）⑥参考图确认（Gate 0 已展示整体图，问用户是否看到、要不要换）。载体优先结构化选项卡，宿主工具不支持则对话文本一次列全；问询顺序与完整措辞以 `SKILL.md` 为准。
+> **六项问询**（一次问完、全部带意图推荐、不选即按推荐走）：①意图与模式推荐合并确认（本表）②篇幅（A 8–15 页 / B 12–25 页 / C 1–3 张图共 6–8 页）③风格 9 套（始终选择——风格是 HTML 皮肤，与交付格式无关）④**亮暗主题**（浅色默认 / 深色沉浸；石墨深灰默认深色；HTML 与 PPTX 同主题导出——`REPORT_MODEL.theme`）⑤交付格式（仅 HTML / HTML+PPTX）⑥参考图确认（Gate 0 已展示整体图，问用户是否看到、要不要换）。载体优先结构化选项卡，宿主工具不支持则对话文本一次列全；问询顺序与完整措辞以 `SKILL.md` 为准。
 >
 > 六项问询收**形式参数**；模式确定后，内容主线/大纲/逐页规划走 `outline-design.md` 内容架构七步法（含按需大纲确认），再进入生成。
 

package/top-ppt-html/scripts/audit_docs.py

@@ -18,6 +18,9 @@
   ⑥ 任务路由可解析性 —— extract_snippet.py 的 TASK_ROUTES 每条 (文件, 节) 必须可
      实际抽取（防「文字声明同源」漂移：路由声明的节在文件里找不到即失败；
      空节路由 = 该文件只能整读，≥20KB 的 L2 文件不允许）
+   ⑦ 反引号引用可达 —— 反引号代码引用中的 `references/*.md` / `scripts/*`
+     路径必须存在（审计 轻微-15 门禁盲区：①–⑥ 只查 [text](path) 形式，
+     `references/pan-style.md` 曾漏网；glob/占位符写法跳过）
 
 何时跑：改 `references/*`、拆分/新增规范文件、调整选型表后（与 regression.py 互补——
 后者管交付物正确性，本工具管规范自洽性）。
@@ -162,6 +165,27 @@ def main() -> int:
         errs.append(f'任务路由空节（整读大文件，应补节号或标题关键词）：{empty_routes}')
     print(f'⑥ 任务路由可解析性：{len(ES.TASK_ROUTES)} 条路由 · 不可解析 {len(unresolved)} · 空节 {len(empty_routes)}')
 
+    # ⑦ 反引号引用可达（审计 轻微-15 门禁盲区：`references/pan-style.md` 曾漏网；
+    #    glob/占位符写法（* ? < > |）跳过；先按引用文件所在目录解析，再回落技能根）
+    bt_path = re.compile(r'(references|scripts)/([\w.\-/]+)')
+    bt_suffix = re.compile(r':\d+(?:-\d+)?$')
+    backtick_bad = 0
+    for rel in doc_files():
+        mp = ROOT / rel
+        text = mp.read_text(encoding='utf-8')
+        for span in set(re.findall(r'`([^`]+)`', text)):
+            for kind, p in bt_path.findall(span):
+                p = bt_suffix.sub('', p)
+                if not p or any(c in p for c in '*?<>|'):
+                    continue
+                tgt = mp.parent / kind / p
+                if not tgt.exists():
+                    tgt = ROOT / kind / p
+                if not tgt.exists():
+                    backtick_bad += 1
+                    errs.append(f'反引号引用不可达 {rel}: `{kind}/{p}`')
+    print(f'⑦ 反引号引用可达：异常 {backtick_bad} 处')
+
     print()
     if errs:
         print('审计未通过：')

package/top-ppt-html/scripts/audit_skill.py

@@ -159,8 +159,8 @@ def main() -> int:
     chk('② compatibility', 0 < clen <= 500,
         f'compatibility 缺失或超 500 字符（{clen}）',
         f'{clen} 字符')
-    meta_ver = re.search(r'^\s+version:\s*"?([\w.\-]+)"?\s*$', sk, re.M)
-    meta_author = re.search(r'^\s+author:\s*(\S+)\s*$', sk, re.M)
+    meta_ver = re.search(r'^\s*version:\s*"?([\w.\-]+)"?\s*$', sk, re.M)
+    meta_author = re.search(r'^\s*author:\s*(\S+)\s*$', sk, re.M)
     pkg_ver = ''
     try:
         import json as _json

package/top-ppt-html/scripts/build_pptx.js

@@ -62,6 +62,42 @@ const pptxgen = require('pptxgenjs');
 const fs = require('fs');
 const path = require('path');
 
+/* ═══ CLI 参数 fail-fast（审计 中等-12）═══
+ * 未知参数一律报错退出（exit 2），不再执行默认构建并写出文件；
+ * --help / -h 打印用法并正常退出（exit 0）。
+ * 位置参数只接受一个（输出文件名）。 */
+(function failFastOnUnknownArgs() {
+  const raw = process.argv.slice(2);
+  if (raw.includes('--help') || raw.includes('-h')) {
+    console.log(
+`用法：
+  node scripts/build_pptx.js [输出.pptx] --model=<模型.json> [--style=<风格>] [--theme=light|dark]
+
+  1) 抽模型：python scripts/extract_model.py <报告.html>（生成 <报告>.model.json）
+  2) 生成：  node scripts/build_pptx.js 报告.pptx --model=报告.model.json
+  3) 质检：  python scripts/validate_pptx.py 报告.pptx --strict --model=报告.model.json
+
+参数：
+  --model=<file>   内容模型 JSON（推荐：由 extract_model.py 从 HTML 报告抽取；缺省用内嵌示例）
+  --style=<name>   覆盖模型的风格（9 套风格 token 见 scripts/layout-constants.json）
+  --theme=light|dark  主题（--theme 覆盖 > 模型 theme > 默认 light）`);
+    process.exit(0);
+  }
+  const known = /^(--model=|--style=|--theme=)/;
+  let positional = 0;
+  for (const a of raw) {
+    if (a.startsWith('-')) {
+      if (!known.test(a)) {
+        console.error(`[build_pptx] FAIL: 未知参数 ${a} —— 拒绝执行（用 --help 查看用法）`);
+        process.exit(2);
+      }
+    } else if (++positional > 1) {
+      console.error(`[build_pptx] FAIL: 多余的位置参数 ${a} —— 只接受一个输出文件名`);
+      process.exit(2);
+    }
+  }
+})();
+
 /* ══════════ 版式常量单源（scripts/layout-constants.json · 两通道共用，禁止在此手写常量） ══════════ */
 const LC = JSON.parse(fs.readFileSync(path.join(__dirname, 'layout-constants.json'), 'utf-8'));
 const STYLE_PRESETS = LC.styles;                      // 9 套风格 token（light）

package/top-ppt-html/scripts/package_skill.py

@@ -64,11 +64,11 @@ NAME = 'top-ppt-html'                       # 技能全名 = 分发包顶层目
 OUT = ROOT / 'dist' / f'{NAME}.zip'
 MANIFEST = ROOT / 'dist' / f'{NAME}.manifest.json'
 DESC_LIMIT = 1024
-# 版本唯一事实源 = layout-constants.json `version`（v8.3 起 frontmatter 不携带非标 version 键，
-# manifest 版本一律取 LC；frontmatter 若显式声明则以其为准——但不鼓励）
+# 版本唯一事实源 = SKILL.md frontmatter `version`（须与 package.json version 一致，见 --check 比对）；
+# 回退读 package.json。注意：layout-constants.json 的 `version` 是版式常量版本（0.1），不是技能版本，禁止用作技能版本。
 try:
     VERSION = str(json.loads(
-        (ROOT / 'scripts' / 'layout-constants.json').read_text(encoding='utf-8')).get('version') or '0.0')
+        (ROOT / 'package.json').read_text(encoding='utf-8')).get('version') or '0.0')
 except (OSError, json.JSONDecodeError):
     VERSION = '0.0'
 

package/topmind-cover/README.en.md

@@ -0,0 +1,68 @@
+# topmind-cover · Cover Art Generation
+
+**[中文](./README.md)** | English
+
+A reusable skill for generating cover art for X long-form posts and WeChat articles. Goal: **striking, eye-catching, theme-focused**.
+
+## Style gallery
+
+<p align="center">
+  <img src="https://github.com/topmindspace/tms-skills/raw/main/topmind-cover/assets/examples/overview.png" alt="topmind-cover · 8 cover-style overview" width="960" />
+</p>
+
+| Style | Best for |
+|-------|----------|
+| Viral dry-goods `gan-huo` | Tested picks, reviews, roundups; default for first-person "I tried it all for you" posts |
+| Giant-type manifesto `big-type` | Opinion pieces, deep essays, launch manifestos; default for one-sentence-stance pieces |
+| Brand launch `brand-launch` | Product launches, version updates, official best practices / whitepapers; first choice when a brand is the subject |
+| Tutorial steps `tutorial-steps` | Tutorials, onboarding guides, step-by-step walkthroughs, beginner-proof recipes |
+| Fun IP `ip-fun` | Case studies, data recaps, retrospectives, series (part 1 / part 2) |
+| News flash `news-flash` | News, flashes, hot-topic explainers, interview teasers, "myth-busting" angles |
+| Minimal `minimal` | Essays, book reviews, light takes, lifestyle musings; WeChat "light reading" pieces |
+| Editorial magazine `magazine` | In-depth interviews, profiles, business analysis, year-in-review; when "craft / trust" matters |
+
+## Install
+
+```bash
+npx @topmindspace/tms-skills install topmind-cover
+```
+
+## Usage
+
+0. **Pick a style (3 steps, required)**: choose 1 of 8 styles from `references/cover-styles.md` by topic
+   → check `assets/examples/<style>.png` to confirm the visual language
+   → compose the prompt from that style's recipe (replace `{TITLE}` with the real title).
+1. Input: article title + 3 theme keywords + platform (x / wechat / both, default both).
+2. Generate with the agent's image-generation capability (landscape 16:9, 8% margin on all sides).
+3. Eyeball check (required): title text correct word for word, subject complete, theme legible at a glance;
+   title text and key subject stay inside the central vertical 60% safe zone (so the 900×383 center crop never cuts the title).
+4. Crop and save:
+
+```bash
+python3 scripts/crop-cover.py <main-image> --out-dir <package>/images/
+# produces 00-封面.png (1200×675) + 00-封面-公众号.png (900×383, center crop)
+```
+
+## Style library & examples
+
+- **Style library** `references/cover-styles.md`: 8 styles (viral dry-goods / giant-type manifesto / brand launch / tutorial steps / fun IP / news flash / minimalist / editorial magazine), each with use cases, hex palettes, font suggestions, Chinese+English prompt recipes, and pitfalls.
+- **Example images** [assets/examples/](./assets/examples/): 17 (8 styles × 1200×675 master + 900×383 WeChat center-crop + `overview.png` 8-grid overview, ~7.5MB), shipped with the package, free to reuse or adapt (manifest + safe-zone notes + reuse terms in [assets/examples/README.md](./assets/examples/README.md)).
+- **Safe-zone rule**: title text and key subject must stay inside the central vertical 60% safe zone (keep the top/bottom 13%+ free of title text), or the WeChat center crop will cut the title.
+
+## Sizes
+
+| Platform | Size | Aspect |
+|----------|------|--------|
+| X Article cover | 1200×675 | 16:9 (master image) |
+| WeChat cover large image | 900×383 | 2.35:1 (center crop) |
+
+## Design rules
+
+One image, one theme; subject fills 40%+ of the frame; big title ≤ 10 chars, high contrast; avoid clutter, tiny dense text, and competing subjects.
+
+## Development
+
+```bash
+python3 scripts/package_skill.py --check
+python3 scripts/negative_tests.py
+```