@topmindspace/tms-skills 0.3.6 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,158 @@
+## [0.4.1] - 2026-09-29
+
+> **本版备发**（tag v0.4.1 待打；npm 待发布；commit = 本轮审计报告落盘时的 `git log` 首条）。
+> 根包 0.4.0 → **0.4.1**（patch）；技能版本：top-ppt-html 0.2.0 → **0.2.1**（修技能数据 bug 则 patch）、
+> topmind-cover 保持 0.2.0（仅换样张图+描述文案，无功能变更）、topmind-wechat-post / topmind-x-article 保持 0.1.0。
+> 本轮是第十三轮集成轮（A 文档抛光 + B 示例与描述 + C 新代码复审），改动最小、无新功能。
+> 另含第十四轮集成轮（wechat-post/x-article 真 bug 修复 + installer 测试扩展）：**不 bump 版本**，全部并入 0.4.1。
+
+### 安装器 bug 修复（高危 · Worker C 复审发现）
+
+- `uninstall`/`install` 的 `assertDestOutsideSource` 守卫被符号链接绕过：`path.resolve` 不解析软链，
+  `--to <软链指向包根>` 会跟随链接 `rmSync` 删掉包内技能源目录（已实测验证旧代码确会删源）
+- 修复：`bin/tms-skills.js` 改用 `realpath` 归一化比对（`realOrResolved()`：dest 不存在时向上找最深存在祖先），+25/−4
+- `scripts/test_installer_cli.js` 新增 case11/case12（uninstall/install 经软链指包根 → 拒绝、源目录完好），12 用例全过
+
+### top-ppt-html 0.2.1（Worker C 复审发现 · 低危数据 bug）
+
+- `assets/icons/index.json`：「组织」图标关键词含裸「架构」，会把「系统架构」类标题配上人物组织图 → 已收窄为「组织架构」
+
+### 文档抛光（Worker A）
+
+- topmind-cover/SKILL.md：冲击力自检清单 10→9（合并逐字正确项）、设计铁律去重
+- impact-language.md：删除与 cover-styles.md 重复的「白色清新」章节（只在 cover-styles 保留，出处回指用户参考图）
+- 根 README 中英：封面技能描述 8 种风格 → 11 种；top-ppt-html README 中英版本口径改为与 `@topmindspace/tms-skills@0.4.1` 同 tag
+
+### 示例与描述（Worker B）
+
+- `white-clean-alt.png`（white-clean-2）已重生成：标题「极简收纳全攻略」摆正、逐字正确；配套
+  `white-clean-alt-wechat.png`（900×383）新增落盘并纳入 git；示例目录 README 计数同步为 26 张
+- 4 处 description 更新（cover package.json + SKILL frontmatter 加「11 种风格模板」；ppt-html package.json + SKILL frontmatter 加「48 图标 + 弹性版式」）；overview alt 文案 8→11
+- cover 安装文案复核：`list` 输出已准确，未动安装器
+
+### 第十四轮集成（Worker A/B/C）——不 bump 版本，全部并入 0.4.1
+
+- **topmind-wechat-post 修 6 真 bug**（`scripts/md2wechat.py`，Worker A 专审发现）：
+  - yaml/diff 代码块高亮正则在分支内误用 `(?m)` → `re.error` 崩溃（编译期统一 `re.M|re.S`，分支内去掉）
+  - URL 含平衡括号被截断 → 新增括号嵌套匹配扫描器替代旧正则
+  - `[文字](url "title")` 带 title 链接认不出 → 链接解析支持 title
+  - 脚注 URL 的 `&` 被转义两次 → 修正转义顺序
+  - 坏主题 JSON 的 Traceback → 干净报错；目录当输入的报错文案修正
+  - 嵌套围栏被提前闭合 → 围栏匹配支持嵌套
+  - `scripts/negative_tests.py` 新增 6 个 case，15/15 绿
+- **topmind-x-article 修嵌套围栏**（`scripts/md2x.py`，Worker A 专审发现）；
+  `scripts/negative_tests.py` 新增 2 个 case，8/8 绿
+- **installer 回归测试扩展**（Worker C）：`scripts/test_installer_cli.js` 新增 case13–22，
+  覆盖 symlink 守卫纵深（realpath 归一化）与 installer 回归，72 断言全绿；`bin/` 未动，无真实绕过
+- **分发体积与性能**（Worker B）：无真问题。0.4.1 tarball 解包 29.1MB（0.3.9 18.4MB，
+  +10.7MB 系封面示例画廊预期增量）；top10 大文件全合法素材；48 图标 PNG 最大 27.4KB 无异常；
+  install 耗时 0.3s 不需优化；`sync_npm_files.js --check` 通过
+- 技能版本号保持：wechat-post / x-article 保持 0.1.0（纯 bug 修复按技能版本规则不 bump）；
+  cover 保持 0.2.0、ppt-html 保持 0.2.1、根包保持 0.4.1
+
+## [0.4.0] - 2026-09-29
+
+> **本版备发**（tag v0.4.0 待打；npm 待发布；commit = 本轮审计报告落盘时的 `git log` 首条）。
+> 根包 0.3.9 → **0.4.0**（minor，本轮是功能轮）；技能版本：top-ppt-html 0.1.19 → **0.2.0**、topmind-cover 0.1.0 → **0.2.0**、topmind-wechat-post / topmind-x-article 保持 0.1.0。
+> 本轮是"对标业界+浅色封面+图标包版式"的功能轮（第十二轮）。
+
+### 安装器（Worker A）
+
+- 新增 `uninstall <id> [--to]` 命令：卸载已安装技能，`--to` 指向文件/缺目录时干净报错 exit 1
+- `install` 已装版本感知：已装同版本拒绝安装并给出三行摘要（当前版本/来源/提示 uninstall 或覆盖），不再静默覆盖
+- `scripts/test_installer_cli.js`：10 用例 38 断言，覆盖 install/uninstall/list/负向输入
+- `--help` 更新、根 README.md/README.en.md 安装章节重写（`github:` 口径、钉版本示例同步 0.4.0）
+- `.github/workflows/ci.yml` 新增 "Installer CLI tests" step
+
+### topmind-cover 0.2.0（Worker B）
+
+- 新增 3 个浅色风格：`white-clean`（排第一，标题冲击目标 1/3 字高）、`bg-blur`（背景虚化突出前景）、`paper-collage`（纸拼贴质感）
+- `cover-styles.md` 11 风格重排为浅色优先；`impact-language.md` 补条目；SKILL.md 新增"直出/讨论"决策流
+- 6 张新风格样张 + `overview.png` 重建；`references/ref-white-clean-1/2.png` 新增参考图
+
+### top-ppt-html 0.2.0（Worker C）
+
+- 内置原创图标包 `assets/icons/`：48 SVG + 48 PNG + `index.json` 映射，7 个默认图标兜底；`scripts/check_icons.py`（`--strict`）做图标一致性门禁；`references/icons.md` 文档化
+- 3 种 layout variant：bento-grid / timeline / 2-col-feature（`references/layout-variants.md`）；`references/style-pack.md` 风格包文档化
+- `validate_report.py` 新增内容覆盖率检查（<95% WARN）；随门禁修复 6 个真实丢字 bug
+- `scripts/layout-constants.json` 加 adaptiveText 弹性文本规则；HTML/PPTX 弹性适配减少溢出截断
+
+## [0.3.9] - 2026-09-29
+
+> **本版备发**（tag v0.3.9 待打；npm 待发布；commit = 本轮审计报告落盘时的 `git log` 首条）。
+> 注：0.3.7、0.3.8 未发布，全部内容已并入本版。
+> 根包 0.3.8 → **0.3.9**（patch）；4 个技能 `version` 保持不动（top-ppt-html 0.1.19，其余 0.1.0）。
+> 本轮是"新鲜眼睛"横扫（第十一轮）：只找前十轮没覆盖的盲区，改动最小。
+
+### 代码异味横扫（第十一轮 Worker A）
+
+- TODO 注释 6 命中 → 0 真遗留（均为有意为之：文档纪律说明/scaffold 指导注释/校验正则/示例代称）
+- 死代码：全仓 Python + top-ppt-html JS 逐函数交叉 grep，零死函数；12 个 CLI 参数逐个验证全部在用
+- 跨技能一致性修复：19 处错误信息半角冒号 `错误:` → 全角 `错误：`（多数派 47 处）；`validate_report.py` 加 `-h/--help` 早退（exit 0），与其他 argparse CLI 一致
+- 重复逻辑（仅记录，不重构）：`esc()` HTML 转义三处逐字相同、`read_frontmatter()` 跨技能同构、`load_constants()` 各自实现——均为四技能同构门禁的有意设计
+
+### 对抗输入测试（第十一轮 Worker B：5 真崩溃全部修复）
+
+- `bin/tms-skills.js`：`--to` 指向已存在文件时 `mkdirSync` 抛未捕获堆栈 → try/catch 干净报错 exit 1
+- `md2wechat.py`：`resolve_image` 的 `shutil.copy2`/`os.makedirs` 未捕获 OSError（磁盘满/目录当图片）→ 干净报错 exit 1
+- `md2x.py`：输出写入 `mkdir`+`write_text` 未捕获 OSError → 干净报错 exit 1；目录当输入的报错文案修正（"找不到输入文件"→"输入是目录不是文件"）
+- `crop-cover.py`：`out_dir.mkdir` 与渲染循环 `out.save` 未捕获 OSError（磁盘满→截断 PNG）→ 干净报错 exit 1
+- 对抗矩阵：100KB 单行/emoji+零宽+混合换行/非法 UTF-8/空文件/纯标题/48MB 图片，其余全部干净通过
+
+### 文档一致性（第十一轮 Worker C）
+
+- 审计结论抽查 5 处全部为真（architecture 归一化/SKILL.md 13KB 预算/cover 触发词/ip-fun 原位垫色块补丁/footer 移出 content 标记）
+- SKILL.md vs --help 漂移修复 1 处：wechat-post SKILL.md 注释声称 `--workspace` 参数，全仓无此参数 → 改为 `--base`
+- README 示例 10/10 实跑通过（/tmp 干净目录，本地包安装）
+
+## [0.3.8] - 2026-09-29
+
+> **本版未发布**（未打 tag、未推 npm；0.3.8 全部内容已并入 0.3.9）。
+> 根包 0.3.6 → **0.3.8**（patch）；4 个技能 `version` 保持不动（top-ppt-html 0.1.19，其余 0.1.0）。
+> 本轮只动 top-ppt-html + 文档：渲染产出目检修复（A）+ PPTX 双引擎保真修复 11 bug（B）+ 文档修正（C）。
+
+### 模板 footer 修复（第十轮 Worker A：渲染产出目检）
+
+- `top-ppt-html/assets/templates/{presentation,research,architecture}.html`：`<footer>` 移出 `__TOPPPT_CONTENT_START__`/`__TOPPPT_CONTENT_END__` 标记之外——此前自动渲染取 content 区间时会连带删除页脚，目检确认已修复。
+
+### PPTX 双引擎保真修复（第十轮 Worker B：PPTX 实检，11 bug 全部像素复验）
+
+- `top-ppt-html/scripts/build_pptx.js` + `assets/pptx-export.js`（双端同规则）：
+  - 图表数据标签小数位：按模型数值实际小数位（上限 2 位）生成 format code，修复小数标签被截断
+  - hbar 条形图：类目轴自下而上绘制，反转数据使首项居顶；单系列颜色按数据点分配（跟随数据归属，与 A 通道一致）
+  - streamgraph 退化：相邻 ribbon quad 沿走向微叠 0.02in，消除拼接处抗锯齿发丝缝
+  - boxplot：min 标签默认移到须线帽下方，不再被组标签带压住叠印
+  - marimekko：单元格归一化兼容裸数值或 `[标签,数值]` 对（裸数值沿用旧行为），修复 NaN 崩坏
+  - pyramid：标题列宽按层内宽比例（labelFrac≈0.3）分配，顶层窄时改单框混排，修复窄层标题/说明叠印
+  - KPI：第 4 个起的支撑指标不再静默截断——容量按最小允许行高计算、行高按全部指标自适应压缩，超容显式告警
+  - donut 图例：百分比列 x（`donut.legendPctX` 5.3 → 10.8）右移，修复图例数值被圆环覆盖
+  - table：内容高度逐格预估、超高全表收字号，字号触底仍装不下则显式告警（不再撑高行压脚注）
+  - exhibit 徽标：纯编号自动补 `Exhibit ` 前缀（与 HTML 视觉一致），已带前缀的不重复
+  - sankey/streamgraph note：note 与 footnote 均参与 `chartBottom` 结算，修复 note 重叠
+- `top-ppt-html/scripts/layout-constants.json`：`donut.legendPctX` 5.3 → 10.8（单源），已由 `sync_runtime.py` 同步至 `pptx-export.js`、画廊、`templates/*.html`、示例的内联副本与 `__TOPPPT_RUNTIME_SHA__` 戳
+
+### 文档修正（第十轮 Worker C）
+
+- 根 README（中英）：当前线 0.2.x → 0.3.x；`topmind-cover` "17 张双尺寸" → "16 张双尺寸 + 1 张风格总览图"
+- `docs/PUBLISHING.md`：`latest` 指向 0.3.1 → 0.3.6
+- `topmind-wechat-post/README`（中英）：二级标题编号示例 `01` → `1`
+
+## [0.3.7] - 2026-09-29
+
+> **本版未发布**（未打 tag、未推 npm；0.3.7 全部内容已并入 0.3.8）。
+> 根包 0.3.6 → **0.3.7**（patch）；4 个技能 `version` 保持不动（top-ppt-html 0.1.19，其余 0.1.0）。
+> 本轮只动 topmind-cover：文字排印与装饰系统（第九轮）。
+
+### 文字排印与装饰系统（第九轮）
+
+- `topmind-cover/references/impact-language.md`：新增第七节"文字装饰系统"（+38 行）：6 种可靠装饰（关键词变色/字号对比/色块衬底/轻微阴影立体/手绘划线圈注箭头/小元素旋转≤8°）各给效果/风险/适用风格/提示词写法四列 + 8 风格各 2~3 种必用装饰指定 + 7 条装饰禁令（禁大标题透视/一句话超 3 色/三重叠加/竖排+旋转/色块吞字/装饰压笔画/装饰超量）
+- `topmind-cover/references/cover-styles.md`（316→359 行）：8 风格提示词新增"文字特效"段（中英双语，全部含色号与量化参数，如"钩子词放大 1.5 倍""色块高 1.2 倍字高""投影偏移 1/10 字高"）；各风格"绝不"清单追加装饰禁令；news-flash 单色铁律放宽为"纯黑打底+爆点词朱红点睛"（仍 ≤3 色，与参考图布局/配色/文字结构全错开）；brand-launch 品牌词发光描边改为荧光绿块衬底
+- `topmind-cover/SKILL.md`（114→116 行）：冲击力自检清单追加第 9/10 条——中文逐字正确（装饰未导致错字/乱码/笔画粘连）、装饰手法 ≤ 该风格指定数量（minimal 只许 1 种）；"必过 8 项"同步为"必过 10 项"
+- 16 张样张全部重生成（标题沿用第八轮）：三重目检通过——中文逐字正确（装饰是错字重灾区，逐字核对）、每张 ≥2 种装饰生效且不乱（minimal 仅 1 种）、与 7 张参考图无实质相似；返工 1 次（magazine 首版比例错误）
+
 ## [0.3.6] - 2026-09-29
 
+> **本版已发布**（commit 5dc0bb8，tag v0.3.6，GitHub Release + npm @0.3.6，latest 已切换）。
 > 根包 0.3.5 → **0.3.6**（patch）；4 个技能 `version` 保持不动（top-ppt-html 0.1.19，其余 0.1.0）。
 > 本轮只动 topmind-cover：冲击力升级（第八轮）。
 

package/README.en.md

@@ -39,14 +39,14 @@ npx @topmindspace/tms-skills install topmind-x-article
 
 ### topmind-cover · Cover art generation
 
-Shared cover art for X long-form and WeChat: striking, eye-catching, theme-focused. **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). 8-style index and recipes: [`references/cover-styles.md`](./topmind-cover/references/cover-styles.md).
+Shared cover art for X long-form and WeChat: striking, eye-catching, theme-focused. **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). 11-style index and recipes: [`references/cover-styles.md`](./topmind-cover/references/cover-styles.md).
 
 ```bash
 npx @topmindspace/tms-skills install topmind-cover
 ```
 
 <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" />
+  <img src="https://github.com/topmindspace/tms-skills/raw/main/topmind-cover/assets/examples/overview.png" alt="topmind-cover · 11 cover-style overview" width="960" />
 </p>
 
 > Let ideas fly — make good thinking visible.
@@ -55,18 +55,18 @@ npx @topmindspace/tms-skills install topmind-cover
   <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.2.x** (`latest`).
+> **Warning**: do not install `@topmindspace/tms-skills@^2` (2.0.0–2.1.1 deprecated). Current line is **0.3.x** (`latest`).
 
 ## Skills
 
 | Skill | Version | What it does |
 |-------|---------|--------------|
-| [`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 |
+| [`top-ppt-html`](./top-ppt-html/) | **0.2.1** | 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; 8-style cover style library + 17 dual-size example images |
+| [`topmind-cover`](./topmind-cover/) | **0.2.0** | Cover art for X / WeChat: striking, theme-focused; 11-style cover style library + 26 example images (incl. 3 alt samples) + 1 style overview |
 
-Installer [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills) is **0.3.6** (whole-repo same-tag releases).
+Installer [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills) is **0.4.1** (whole-repo same-tag releases).
 
 ## Install
 
@@ -76,7 +76,8 @@ 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.3.6 install top-ppt-html   # pin
+npx @topmindspace/tms-skills@0.4.1 install top-ppt-html   # pin
+npx @topmindspace/tms-skills uninstall top-ppt-html --to ./.claude/skills
 ```
 
 ```bash
@@ -84,7 +85,9 @@ npx @topmindspace/tms-skills@0.3.6 install top-ppt-html   # pin
 npx github:topmindspace/tms-skills install top-ppt-html
 ```
 
-Default probe order: `./.agents` → `./.claude` → `./.cursor` → `./.codex` → `./.mimocode`, then user-level `~/.claude`, etc. Or pass `--to`. Do not `npm install top-ppt-html` (skill id is not a standalone package).
+Default probe order: `./.agents` → `./.claude` → `./.cursor` → `./.codex` → `./.mimocode`, then user-level `~/.claude`, etc. Or pass `--to`. When `--to` is omitted, the install summary explicitly prints the auto-detected target directory. Do not `npm install top-ppt-html` (skill id is not a standalone package).
+
+`install` details: if a same-named skill already exists, the installed version is reported and overwriting is refused — pass `--force` to replace (or `uninstall` first). On success, a three-line summary is printed: where it was installed / installed skill version and installer version / next steps.
 
 PPTX export needs `npm install` in the skill folder (pptxgenjs). HTML generation uses Python stdlib only.
 
@@ -93,7 +96,7 @@ PPTX export needs `npm install` in the skill folder (pptxgenjs). HTML generation
 ```
 tms-skills/
 ├─ top-ppt-html/             # skill (SKILL.md + assets + references + scripts)
-├─ bin/tms-skills.js         # CLI: list / install
+├─ bin/tms-skills.js         # CLI: list / install / uninstall
 ├─ docs/                     # publishing · showcase shots · banner · Pages source
 ├─ scripts/                  # repo gates / privacy scan
 ├─ package.json              # @topmindspace/tms-skills

package/README.md

@@ -37,14 +37,14 @@ npx @topmindspace/tms-skills install topmind-x-article
 
 ### topmind-cover · 封面配图生成
 
-X 长文与公众号共用的封面图：震撼、醒目、主题突出。**选风格 → 看示例 → 按配方组 prompt** 三步出图，`crop-cover.py` 一键裁出双平台尺寸（X 1200×675、公众号 900×383）。8 种风格索引与配方见 [`references/cover-styles.md`](./topmind-cover/references/cover-styles.md)。
+X 长文与公众号共用的封面图：震撼、醒目、主题突出。**选风格 → 看示例 → 按配方组 prompt** 三步出图，`crop-cover.py` 一键裁出双平台尺寸（X 1200×675、公众号 900×383）。11 种风格索引与配方见 [`references/cover-styles.md`](./topmind-cover/references/cover-styles.md)。
 
 ```bash
 npx @topmindspace/tms-skills install topmind-cover
 ```
 
 <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" />
+  <img src="https://github.com/topmindspace/tms-skills/raw/main/topmind-cover/assets/examples/overview.png" alt="topmind-cover · 11 封面风格总览" width="960" />
 </p>
 
 > 让 idea 飞，好想法被看见。
@@ -53,18 +53,18 @@ npx @topmindspace/tms-skills install topmind-cover
   <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.2.x**（`latest`）。
+> **警告**：不要安装 `@topmindspace/tms-skills@^2`（2.0.0–2.1.1 已弃用）。当前线 **0.3.x**（`latest`）。
 
 ## 技能一览
 
 | 技能 | 版本 | 做什么 |
 |------|------|--------|
-| [`top-ppt-html`](./top-ppt-html/) | **0.1.19** | 正式商务演示：HTML 可翻页 + 16:9 可编辑 PPTX；双交付 · MD3 密度克制；三模式 × 九风格；strict 0/0 |
+| [`top-ppt-html`](./top-ppt-html/) | **0.2.1** | 正式商务演示：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 / 公众号共用）：震撼醒目主题突出；8 风格封面风格库 + 17 张双尺寸示例图 |
+| [`topmind-cover`](./topmind-cover/) | **0.2.0** | 文章封面配图（X / 公众号共用）：震撼醒目主题突出；11 风格封面风格库 + 26 张示例图（含 3 张 alt 样张） + 1 张风格总览图 |
 
-安装器 [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills) 为 **0.3.6**（整仓同 tag 发版）。
+安装器 [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills) 为 **0.4.1**（整仓同 tag 发版）。
 
 > SKILL.md frontmatter 除标准 `name`/`description` 外，本仓库扩展了 `action_category` / `triggers` / `triggers_cn` / `updated` 字段供安装器与路由使用。
 
@@ -76,7 +76,8 @@ npx @topmindspace/tms-skills install topmind-cover
 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.3.6 install top-ppt-html   # 钉版本
+npx @topmindspace/tms-skills@0.4.1 install top-ppt-html   # 钉版本
+npx @topmindspace/tms-skills uninstall top-ppt-html --to ./.claude/skills
 ```
 
 ```bash
@@ -84,7 +85,9 @@ npx @topmindspace/tms-skills@0.3.6 install top-ppt-html   # 钉版本
 npx github:topmindspace/tms-skills install top-ppt-html
 ```
 
-默认探测：`./.agents` → `./.claude` → `./.cursor` → `./.codex` → `./.mimocode`，再用户级 `~/.claude` 等；也可用 `--to`。不要 `npm install top-ppt-html`（技能 id 不是独立包）。
+默认探测：`./.agents` → `./.claude` → `./.cursor` → `./.codex` → `./.mimocode`，再用户级 `~/.claude` 等；也可用 `--to`。未给 `--to` 时安装摘要会明确打印探测到的目标目录。不要 `npm install top-ppt-html`（技能 id 不是独立包）。
+
+`install` 细节：若同名技能已存在，会报出已装版本并拒绝覆盖，需加 `--force` 才替换（或先 `uninstall` 再装）。安装成功后打印三行摘要：装到哪里 / 装的技能版本与安装器版本 / 下一步。
 
 PPTX 精导需在技能目录 `npm install`（pptxgenjs）。HTML 生成仅 Python 标准库。
 
@@ -93,7 +96,7 @@ PPTX 精导需在技能目录 `npm install`（pptxgenjs）。HTML 生成仅 Pyth
 ```
 tms-skills/
 ├─ top-ppt-html/             # 技能（SKILL.md + assets + references + scripts）
-├─ bin/tms-skills.js         # CLI：list / install
+├─ bin/tms-skills.js         # CLI：list / install / uninstall
 ├─ docs/                     # 发布规范 · showcase 截图 · banner · Pages 源
 ├─ scripts/                  # 仓库级门禁 / 隐私扫描
 ├─ package.json              # @topmindspace/tms-skills

package/bin/tms-skills.js

@@ -10,6 +10,7 @@
  *   npx @topmindspace/tms-skills install top-ppt-html
  *   npx @topmindspace/tms-skills install top-ppt-html --to ./skills-out
  *   npx @topmindspace/tms-skills install top-ppt-html --force
+ *   npx @topmindspace/tms-skills uninstall top-ppt-html --to ./skills-out
  *   npx github:topmindspace/tms-skills install top-ppt-html   # follow repo HEAD
  */
 'use strict';
@@ -69,6 +70,30 @@ function readSkillMeta(skillId) {
   return { id: skillId, description: String(desc).slice(0, 120) };
 }
 
+/** 读技能目录下 SKILL.md frontmatter 的 version 字段（读不到返回 ''，调用方兜底）。 */
+function readSkillVersion(skillPath) {
+  try {
+    const p = path.join(skillPath, 'SKILL.md');
+    if (!fs.existsSync(p)) return '';
+    const text = fs.readFileSync(p, 'utf8');
+    const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!m) return '';
+    const v = m[1].match(/^version:\s*(.+?)\s*$/m);
+    return v ? v[1] : '';
+  } catch {
+    return '';
+  }
+}
+
+function installerVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+    return pkg.version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
 function resolveDefaultTarget() {
   const home = process.env.HOME || process.env.USERPROFILE || '';
   const candidates = [
@@ -112,15 +137,34 @@ function normPath(p) {
   return process.platform === 'win32' ? s.toLowerCase() : s;
 }
 
+/** realpath 能解析就解析（跟符号链接），失败回退 path.resolve。
+ *  dest 可能还不存在（install 流程）：往上找最深存在的祖先解析后再拼回。
+ *  否则 --to 经符号链接指向包内时，词法比对会被绕过（rmSync 会跟链接删掉源）。 */
+function realOrResolved(p) {
+  let cur = path.resolve(p);
+  const tail = [];
+  for (;;) {
+    try {
+      return path.join(fs.realpathSync(cur), ...tail);
+    } catch {
+      const parent = path.dirname(cur);
+      if (parent === cur) return path.join(cur, ...tail);
+      tail.unshift(path.basename(cur));
+      cur = parent;
+    }
+  }
+}
+
 /** 安装目标守卫（审计 严重-2）：
  *  dest == 技能源目录  → --force 会先 rmSync 删掉源目录，再"成功"装出空目录（数据丢失 + 虚假成功）；
  *  dest 在源目录内部  → copyDir 无限递归复制直至 ENAMETOOLONG，并留下垃圾目录树。
- *  path.resolve 归一化后比对（dest === src，或 dest 以 src + 路径分隔符开头），
+ *  realpath 归一化后比对（dest === src，或 dest 以 src + 路径分隔符开头），
+ *  防止 --to 经符号链接指向包内绕过词法比对；
  *  Windows 下额外做大小写归一。无论是否 --force，一律拒绝。
  */
 function assertDestOutsideSource(src, dest) {
-  const absSrc = normPath(src);
-  const absDest = normPath(dest);
+  const absSrc = normPath(realOrResolved(src));
+  const absDest = normPath(realOrResolved(dest));
   if (absDest === absSrc || absDest.startsWith(absSrc + path.sep)) {
     die(
       `Refusing to install into the skill's own directory tree.\n` +
@@ -132,7 +176,7 @@ function assertDestOutsideSource(src, dest) {
   }
 }
 
-function install(skillId, targetRoot, { force = false } = {}) {
+function install(skillId, targetRoot, { force = false, defaultTarget = false } = {}) {
   assertSkillId(skillId);
   const src = skillDir(skillId);
   if (!fs.existsSync(path.join(src, 'SKILL.md'))) {
@@ -140,25 +184,85 @@ function install(skillId, targetRoot, { force = false } = {}) {
   }
   const dest = path.join(targetRoot, skillId);
   assertDestOutsideSource(src, dest);
-  fs.mkdirSync(targetRoot, { recursive: true });
+  try {
+    fs.mkdirSync(targetRoot, { recursive: true });
+  } catch (e) {
+    die(
+      `Cannot create install directory: ${targetRoot}\n` +
+        `  reason: ${e.message}\n` +
+        'Choose a --to directory that can be created (not a file, not unwritable).'
+    );
+  }
   if (fs.existsSync(dest)) {
     if (!force) {
+      // 已装过：报出已装版本，要求 --force 才覆盖（不静默覆盖）。
+      const installedVer = readSkillVersion(dest) || 'unknown';
+      const packageVer = readSkillVersion(src) || 'unknown';
       die(
-        `Destination already exists: ${dest}\n` +
-          'Refusing to overwrite. Pass --force (or -f) to replace.'
+        `Already installed: ${dest}\n` +
+          `  installed version: ${installedVer} (this package ships ${packageVer})\n` +
+          'Refusing to overwrite. Pass --force (or -f) to replace, or remove it first:\n' +
+          `  tms-skills uninstall ${skillId} --to ${targetRoot}`
       );
     }
     fs.rmSync(dest, { recursive: true, force: true });
   }
   copyDir(src, dest);
+  // 安装摘要三行：装到哪里 / 装了什么版本 / 下一步。
+  const toNote = defaultTarget ? '  (default, auto-detected — no --to given)' : '';
+  const skillVer = readSkillVersion(dest) || 'unknown';
   console.log(`Installed ${skillId}`);
-  console.log(`  from ${src}`);
-  console.log(`  to   ${dest}`);
+  console.log(`  to:      ${dest}${toNote}`);
+  console.log(`  version: skill ${skillVer} (installer ${installerVersion()})`);
+  console.log(`  next:    ${nextStep(skillId, dest)}`);
+}
+
+function nextStep(skillId, dest) {
   if (skillId === 'top-ppt-html') {
-    console.log('');
-    console.log('Optional (PPTX export only):');
-    console.log(`  cd "${dest}" && npm install`);
+    return `optional (PPTX export only): cd "${dest}" && npm install — then restart your agent so it picks up the skill`;
+  }
+  return 'restart your agent so it picks up the skill';
+}
+
+/** 列出目标根目录下已安装的技能（有 SKILL.md 的子目录）。 */
+function listInstalledIds(targetRoot) {
+  try {
+    return fs
+      .readdirSync(targetRoot, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && fs.existsSync(path.join(targetRoot, d.name, 'SKILL.md')))
+      .map((d) => d.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function uninstall(skillId, targetRoot) {
+  assertSkillId(skillId);
+  const src = skillDir(skillId);
+  const dest = path.join(targetRoot, skillId);
+  // 守卫：--to 指到包内时，dest 会命中安装器自带的技能源目录 → 一律拒绝，
+  // 防止把仓库自身的技能目录删掉（同 install 的 assertDestOutsideSource）。
+  if (fs.existsSync(path.join(src, 'SKILL.md'))) {
+    assertDestOutsideSource(src, dest);
+  }
+  if (!fs.existsSync(dest)) {
+    const installed = listInstalledIds(targetRoot);
+    die(
+      `Nothing to uninstall: ${dest}\n` +
+        `  skill '${skillId}' is not installed under ${targetRoot}.` +
+        (installed.length ? `\n  installed here: ${installed.join(', ')}` : '')
+    );
   }
+  if (!fs.existsSync(path.join(dest, 'SKILL.md'))) {
+    die(
+      `Refusing to uninstall: ${dest}\n` +
+        `  not a skill directory (missing SKILL.md) — will not delete arbitrary folders.`
+    );
+  }
+  fs.rmSync(dest, { recursive: true, force: true });
+  console.log(`Uninstalled ${skillId}`);
+  console.log(`  from ${dest}`);
 }
 
 function usageText() {
@@ -167,16 +271,33 @@ function usageText() {
 Usage:
   tms-skills list|ls
   tms-skills install <skill-id> [--to|-t <dir>] [--force|-f]
+  tms-skills uninstall <skill-id> [--to|-t <dir>]
   tms-skills help
 
+Behavior:
+  install    copies <skill-id>/ into <dir>/<skill-id>/. If the skill is already
+             installed, the installed version is reported and --force is required
+             to overwrite. Prints where/what-version/next-steps when done.
+  uninstall  removes <dir>/<skill-id>/ (refuses: not installed, not a skill
+             directory, or the package's own skill source).
+  No --to: the target directory is auto-detected (probe order below) and
+  printed explicitly in the install summary.
+
+Target probe order (no --to): ./.agents/skills, ./.claude/skills,
+  ./.cursor/skills, ./.codex/skills, ./.mimocode/skills, then
+  ~/.claude/skills, ~/.agents/skills, ~/.cursor/skills, ~/.codex/skills.
+
 Examples (npm recommended when published):
   npx @topmindspace/tms-skills list
   npx @topmindspace/tms-skills install top-ppt-html
   npx @topmindspace/tms-skills install top-ppt-html --to ./.agents/skills
   npx @topmindspace/tms-skills install top-ppt-html --force
+  npx @topmindspace/tms-skills uninstall top-ppt-html --to ./.agents/skills
 
   # Follow repo HEAD:
   npx github:topmindspace/tms-skills install top-ppt-html
+
+Privacy: the installer is fully local — it never collects or uploads anything.
 `;
 }
 
@@ -225,7 +346,26 @@ function main(argv) {
       }
     }
     const targetRoot = to ? path.resolve(to) : resolveDefaultTarget();
-    install(skillId, targetRoot, { force });
+    install(skillId, targetRoot, { force, defaultTarget: !to });
+    return;
+  }
+
+  if (cmd === 'uninstall') {
+    const skillId = args[1];
+    if (!skillId || skillId.startsWith('-')) {
+      die('Missing skill id.\n\n' + usageText());
+    }
+    let to = null;
+    for (let i = 2; i < args.length; i++) {
+      if (args[i] === '--to' || args[i] === '-t') {
+        to = args[++i];
+        if (!to) die('Option --to requires a directory path.');
+      } else {
+        die(`Unknown option: ${args[i]}\n\n` + usageText());
+      }
+    }
+    const targetRoot = to ? path.resolve(to) : resolveDefaultTarget();
+    uninstall(skillId, targetRoot);
     return;
   }
 

package/package.json

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

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

@@ -10,7 +10,7 @@
 **Let ideas fly — make good thinking visible.** A high-craft skill for **demo reports / formal business presentations**: **HTML + PPT dual delivery** — day-to-day, present with paginated HTML like slides; export **layout-faithful editable PPTX** when needed. **MD3-inspired**: fitting information density, restrained type / shapes / color. Core craft is layout, typography, color, and content structure — not gadget soup.
 
 - Skill id: `top-ppt-html`; brand: **TopPPT HTML**
-- Version: **v0.1.19** (same tag as `@topmindspace/tms-skills@0.3.6`)
+- Version: **v0.2.1** (same tag as `@topmindspace/tms-skills@0.4.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
 
@@ -55,7 +55,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.3.6 install top-ppt-html
+npx @topmindspace/tms-skills@0.4.1 install top-ppt-html
 npx github:topmindspace/tms-skills install top-ppt-html
 ```
 

package/top-ppt-html/README.md

@@ -10,7 +10,7 @@
 **让 idea 飞，好想法被看见。** 为**演示报告 / 正式商务演示**而生的高品质演示文稿技能：**HTML + PPT 双交付**——日常用可翻页 HTML 等同幻灯片；需要时再导出**版式保真可编辑 PPTX**。参考 **MD3**：合适信息密度、克制文字/图形/颜色。核心工艺是版式、排版、色彩与内容组织——不是 gadget 堆砌。
 
 - 技能标识：`top-ppt-html`；品牌名：**TopPPT HTML**
-- 版本：**v0.1.19**（与 `@topmindspace/tms-skills@0.3.6` 同 tag）
+- 版本：**v0.2.1**（与 `@topmindspace/tms-skills@0.4.1` 同 tag）
 - **智能体入口**：`SKILL.md` → `references/playbook.md`（L1）→ L2 按需
 - **人类维护者**：本 README（安装 / 命令 / 目录）；勿把本文件当生成规范