@topmindspace/tms-skills 2.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/README.md +126 -103
  3. package/package.json +1 -1
  4. package/top-ppt-html/README.md +12 -11
  5. package/top-ppt-html/assets/theme-overview-architecture.png +0 -0
  6. package/top-ppt-html/assets/theme-overview-presentation.png +0 -0
  7. package/top-ppt-html/assets/theme-overview-research.png +0 -0
  8. package/top-ppt-html/assets/theme-overview.png +0 -0
  9. package/top-ppt-html/scripts/measure_height.py +3 -3
package/CHANGELOG.md CHANGED
@@ -2,8 +2,19 @@
2
2
 
3
3
  所有 monorepo 变更记录见本文件。
4
4
 
5
+ ## 2.0.1 — 2026-09-24（文档 + 发布链路）
6
+
7
+ ### Changed
8
+ - 文档全面对齐「双通道分发」：npm [`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills) 已公开发布（`2.0.0` 起），GitHub 直装仍可用。
9
+ - 明确 **GitHub ≠ npm 自动同步**：push 不更新 npm；**tag `v*` → `release.yml` 自动 npm publish**。
10
+ - `release.yml` 启用 npm 发布步骤（Secret `NPM_TOKEN`）；`docs/PUBLISHING.md` 补版本策略、打包矩阵 npm 列、排错表。
11
+
5
12
  ## 2.0.0 — 2026-09-24（技能 9.1.0 · 仓库/技能更名 + 层级扁平化）
6
13
 
14
+ ### Published
15
+ - 首次发布公共 npm：[`@topmindspace/tms-skills@2.0.0`](https://www.npmjs.com/package/@topmindspace/tms-skills)
16
+ - 安装：`npx @topmindspace/tms-skills install top-ppt-html`
17
+
7
18
  ### Changed
8
19
  - **仓库更名**：GitHub `topmindspace/topskills` → **`topmindspace/tms-skills`**（旧 URL 301）；本地根目录、`git remote`、npm 包名 `@topmindspace/tms-skills`、CLI `tms-skills` / `bin/tms-skills.js` 全部对齐。
9
20
  - **技能更名**：`top-slides-expert` / TopSlides Expert → **`top-ppt-html` / TopPPT HTML**（目录、frontmatter `name`、分发包、文档一致）。
package/README.md CHANGED
@@ -1,103 +1,126 @@
1
- # tms-skills
2
-
3
- **TopMindspace 智能体技能 monorepo** — 可安装的智能体技能集合，当前包含 **top-ppt-html**。
4
-
5
- 让 idea 飞，好想法被看见。
6
-
7
- ## 技能一览
8
-
9
- | 技能 | 状态 | 做什么 |
10
- |------|------|--------|
11
- | [`top-ppt-html`](./top-ppt-html/) | stable | 报告 / 演示 / 信息架构图：单文件 HTML + 版式保真的可编辑 16:9 PPTX |
12
-
13
- 更多技能将直接以仓库根目录下的技能目录加入（每个技能一个目录，含 `SKILL.md`）。
14
-
15
- ## 安装（GitHub 优先）
16
-
17
- 公共 npm 源上的 `@topmindspace/tms-skills` **可能尚未发布**。默认用 GitHub 直装，不依赖 npm 注册：
18
-
19
- ```bash
20
- # 列出已打包技能
21
- npx github:topmindspace/tms-skills list
22
-
23
- # 安装到 ./.agents/skills（默认；也会探测 .claude / .mimocode）
24
- npx github:topmindspace/tms-skills install top-ppt-html
25
-
26
- # 安装到指定目录
27
- npx github:topmindspace/tms-skills install top-ppt-html --to ./.claude/skills
28
-
29
- # 也可先 clone 再本地安装
30
- git clone https://github.com/topmindspace/tms-skills.git
31
- node tms-skills/bin/tms-skills.js install top-ppt-html
32
- ```
33
-
34
- 若已执行 `npm publish`（可选，见 [docs/PUBLISHING.md](./docs/PUBLISHING.md)），也可用 npm 包名：
35
-
36
- ```bash
37
- npx @topmindspace/tms-skills list
38
- npx @topmindspace/tms-skills install top-ppt-html
39
- ```
40
-
41
- > **排错**：若报「npm 公共源上找不到这个包」，说明 npm 包未发布（或包名写错）。请改用上面的 `npx github:topmindspace/tms-skills ...`，而不是 `npm install` / `npx <技能名>`。
42
-
43
- 安装器会把根目录下的技能目录 `<id>/`（含 `SKILL.md`）复制到目标目录。智能体通过 `SKILL.md` frontmatter（`name` + `description`）发现技能。
44
-
45
- ### 可选依赖（仅 PPTX 精导需要）
46
-
47
- HTML 生成只用 **Python 标准库**。原生 PPTX 导出需要 Node + 在技能目录安装 `pptxgenjs`：
48
-
49
- ```bash
50
- cd <install-dir>/top-ppt-html
51
- npm install
52
- ```
53
-
54
- ## 仓库结构
55
-
56
- ```
57
- tms-skills/
58
- ├─ top-ppt-html/ # 技能目录（SKILL.md + assets + references + scripts + evals）
59
- ├─ bin/tms-skills.js # npx CLI（list / install）
60
- ├─ docs/ # 发布与贡献说明
61
- ├─ scripts/ # 仓库级工具（隐私扫描等）
62
- ├─ .github/workflows/ # CI + Release
63
- ├─ package.json # @topmindspace/tms-skills
64
- ├─ LICENSE
65
- ├─ CHANGELOG.md
66
- └─ README.md
67
- ```
68
-
69
- ## 隐私与发布策略
70
-
71
- - 文档与技能中不得出现个人路径、主机名、凭据或本机智能体状态。
72
- - 不包含密钥、私有包源、绝对本地路径。
73
- - 构建产物（`dist/`、`node_modules/`、缓存、IDE 状态）一律 gitignore，不进包。
74
- - 触发文案与文档不得含私有/内部工具品牌。
75
-
76
- 详见 [docs/PUBLISHING.md](./docs/PUBLISHING.md)。
77
-
78
- ## CI / CD
79
-
80
- | 工作流 | 触发 | 做什么 |
81
- |--------|------|--------|
82
- | `ci.yml` | push / PR | 技能打包门禁、审计、隐私扫描、CLI 冒烟 |
83
- | `release.yml` | tag `v*` | 构建技能 zip + manifest，挂到 GitHub Release；可选 npm 发布 |
84
-
85
- 本地推送前建议：
86
-
87
- ```bash
88
- npm run check
89
- npm run audit
90
- npm run privacy
91
- ```
92
-
93
- ## 开发新技能
94
-
95
- 1. 在仓库根目录创建 `<skill-id>/`，`SKILL.md` frontmatter 的 `name` 必须与目录名一致。
96
- 2. 面向人的说明写在技能 `README.md`；智能体入口保持 `SKILL.md`。
97
- 3. 发布前运行该技能的 `scripts/package_skill.py --check`。
98
- 4. 在根 README 技能表与 `CHANGELOG.md` 登记。
99
- 5. 不要提交本机 IDE/智能体状态或绝对机器路径。
100
-
101
- ## 许可证
102
-
103
- MIT © TopMindspace — 见 [LICENSE](./LICENSE)。
1
+ # tms-skills
2
+
3
+ **TopMindspace 智能体技能 monorepo** — 可安装的智能体技能集合，当前包含 **top-ppt-html**。
4
+
5
+ 让 idea 飞，好想法被看见。
6
+
7
+ ## 技能一览
8
+
9
+ | 技能 | 状态 | 做什么 |
10
+ |------|------|--------|
11
+ | [`top-ppt-html`](./top-ppt-html/) | stable | 报告 / 演示 / 信息架构图：单文件 HTML + 版式保真的可编辑 16:9 PPTX |
12
+
13
+ 更多技能将直接以仓库根目录下的技能目录加入（每个技能一个目录，含 `SKILL.md`）。
14
+
15
+ ## 安装
16
+
17
+ 两条通道，装出来的东西一样。**GitHub = 永远跟仓库 HEAD**；**npm = 固定版本快照**（发版后不变）。
18
+
19
+ ### 通道 A · npm（推荐日常）
20
+
21
+ 已发布：[`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills)
22
+
23
+ ```bash
24
+ # 列出包内技能
25
+ npx @topmindspace/tms-skills list
26
+
27
+ # 安装到 ./.agents/skills（默认；也会探测 .claude / .mimocode）
28
+ npx @topmindspace/tms-skills install top-ppt-html
29
+
30
+ # 安装到指定目录
31
+ npx @topmindspace/tms-skills install top-ppt-html --to ./.claude/skills
32
+
33
+ # 钉版本
34
+ npx @topmindspace/tms-skills@2.0.0 install top-ppt-html
35
+ ```
36
+
37
+ ### 通道 B · GitHub 直装（跟最新提交 / 无 npm 网络）
38
+
39
+ ```bash
40
+ npx github:topmindspace/tms-skills list
41
+ npx github:topmindspace/tms-skills install top-ppt-html
42
+
43
+ # 或 clone 后本地安装
44
+ git clone https://github.com/topmindspace/tms-skills.git
45
+ node tms-skills/bin/tms-skills.js install top-ppt-html
46
+ ```
47
+
48
+ ### 手工
49
+
50
+ 解压 GitHub Release 的 `top-ppt-html.zip` 到技能目录（无 Node / 受限网络）。
51
+
52
+ 安装器会把根目录下的技能目录 `<id>/`（含 `SKILL.md`）复制到目标目录。智能体通过 `SKILL.md` frontmatter（`name` + `description`）发现技能。
53
+
54
+ > **排错**：不要用 `npm install <skill-id>`（技能 id 不是独立 npm 包）。npm 装的是安装器包 `@topmindspace/tms-skills`，技能由它 `install` 复制进目标目录。
55
+ >
56
+ > 若报「找不到这个包」：稍等索引同步，或改用通道 B；国内镜像可能滞后，可用 `--registry https://registry.npmjs.org/`。
57
+
58
+ ### 可选依赖（仅 PPTX 精导需要）
59
+
60
+ HTML 生成只用 **Python 标准库**。原生 PPTX 导出需要 Node + 在技能目录安装 `pptxgenjs`：
61
+
62
+ ```bash
63
+ cd <install-dir>/top-ppt-html
64
+ npm install
65
+ ```
66
+
67
+ ## 仓库结构
68
+
69
+ ```
70
+ tms-skills/
71
+ ├─ top-ppt-html/ # 技能目录（SKILL.md + assets + references + scripts + evals）
72
+ ├─ bin/tms-skills.js # npx CLI（list / install）
73
+ ├─ docs/ # 发布与贡献说明
74
+ ├─ scripts/ # 仓库级工具（隐私扫描等）
75
+ ├─ .github/workflows/ # CI + Release
76
+ ├─ package.json # @topmindspace/tms-skills
77
+ ├─ LICENSE
78
+ ├─ CHANGELOG.md
79
+ └─ README.md
80
+ ```
81
+
82
+ ## GitHub 与 npm 如何同步
83
+
84
+ | 动作 | GitHub | npm |
85
+ |------|:------:|:---:|
86
+ | 直接 push 到 main | 立即可见 | **不会**自动更新 |
87
+ | 打 tag `vX.Y.Z` 并 push | 出 GitHub Release | **自动** `npm publish`（见下） |
88
+ | 本地 `npm publish` | — | 立即更新 |
89
+
90
+ **不会**因为 GitHub 上改了代码就自动更新 npm——npm 只认**新的版本号**。日常迭代用通道 B 或等发版；发版走 tag 即可两边对齐。
91
+
92
+ 发版细节见 [docs/PUBLISHING.md](./docs/PUBLISHING.md)。
93
+
94
+ ## 隐私与发布策略
95
+
96
+ - 文档与技能中不得出现个人路径、主机名、凭据或本机智能体状态。
97
+ - 不包含密钥、私有包源、绝对本地路径。
98
+ - 构建产物（`dist/`、`node_modules/`、缓存、IDE 状态）一律 gitignore，不进包。
99
+ - 触发文案与文档不得含私有/内部工具品牌。
100
+
101
+ ## CI / CD
102
+
103
+ | 工作流 | 触发 | 做什么 |
104
+ |--------|------|--------|
105
+ | `ci.yml` | push / PR | 技能打包门禁、审计、隐私扫描、CLI 冒烟 |
106
+ | `release.yml` | tag `v*` | 技能 zip + manifest → GitHub Release；**并自动 npm publish** |
107
+
108
+ 本地推送前建议：
109
+
110
+ ```bash
111
+ npm run check
112
+ npm run audit
113
+ npm run privacy
114
+ ```
115
+
116
+ ## 开发新技能
117
+
118
+ 1. 在仓库根目录创建 `<skill-id>/`，`SKILL.md` frontmatter 的 `name` 必须与目录名一致。
119
+ 2. 面向人的说明写在技能 `README.md`；智能体入口保持 `SKILL.md`。
120
+ 3. 发布前运行该技能的 `scripts/package_skill.py --check`。
121
+ 4. 在根 README 技能表、`package.json` 的 `files`、CI 工作流与 `CHANGELOG.md` 登记。
122
+ 5. 不要提交本机 IDE/智能体状态或绝对机器路径。
123
+
124
+ ## 许可证
125
+
126
+ MIT © TopMindspace — 见 [LICENSE](./LICENSE)。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@topmindspace/tms-skills",
3
- "version": "2.0.0",
3
+ "version": "2.0.1",
4
4
  "description": "TopMindspace 智能体技能 monorepo — 通过 GitHub npx 安装技能（top-ppt-html 等）。",
5
5
  "license": "MIT",
6
6
  "author": "TopMindspace",
package/top-ppt-html/README.md CHANGED
@@ -30,24 +30,25 @@
30
30
 
31
31
  ### 安装
32
32
 
33
- 本技能是 [`tms-skills`](https://github.com/topmindspace/tms-skills) monorepo 中的一个技能包（路径 `top-ppt-html/`）。**推荐从 GitHub 直装**（不依赖 npm 是否已发布）：
33
+ 本技能是 [`tms-skills`](https://github.com/topmindspace/tms-skills) monorepo 中的一个技能包（路径 `top-ppt-html/`）。npm 安装器已发布：[`@topmindspace/tms-skills`](https://www.npmjs.com/package/@topmindspace/tms-skills)。
34
34
 
35
35
  ```bash
36
- npx github:topmindspace/tms-skills install top-ppt-html
36
+ # 推荐 · npm
37
+ npx @topmindspace/tms-skills install top-ppt-html
37
38
  # 或指定目录
38
- npx github:topmindspace/tms-skills install top-ppt-html --to ./.agents/skills
39
- # 或 clone 后本地安装
40
- git clone https://github.com/topmindspace/tms-skills.git
41
- node tms-skills/bin/tms-skills.js install top-ppt-html
42
- ```
39
+ npx @topmindspace/tms-skills install top-ppt-html --to ./.agents/skills
43
40
 
44
- 若 `@topmindspace/tms-skills` 已发布到 npm（可选步骤），也可：
41
+ # 跟仓库 HEAD · GitHub 直装
42
+ npx github:topmindspace/tms-skills install top-ppt-html
45
43
 
46
- ```bash
47
- npx @topmindspace/tms-skills install top-ppt-html
44
+ # clone 后本地安装
45
+ git clone https://github.com/topmindspace/tms-skills.git
46
+ node tms-skills/bin/tms-skills.js install top-ppt-html
48
47
  ```
49
48
 
50
- > 报「npm 公共源上找不到这个包」= npm 包未发布或包名不对，改用 GitHub 直装即可。
49
+ > **GitHub 更新不会自动进 npm。** 日常可钉 npm 版本；要最新技能用 GitHub 直装，或等 maintainer 打 tag 发版。
50
+ >
51
+ > 「找不到这个包」→ 换 GitHub 直装，或 `--registry https://registry.npmjs.org/`（镜像索引可能滞后）。不要 `npm install top-ppt-html`（技能 id 不是独立 npm 包）。
51
52
 
52
53
  也可将本目录（或 GitHub Release 附件 `top-ppt-html.zip` 解压结果）复制到智能体技能目录，目录名保持 `top-ppt-html`。技能识别面为 `SKILL.md`（frontmatter 的 `name` / `description` 即触发描述）。
53
54
 
package/top-ppt-html/scripts/measure_height.py CHANGED
@@ -52,11 +52,11 @@ def main() -> int:
52
52
  exe = shutil.which(name)
53
53
  if exe:
54
54
  candidates.append(exe)
55
- # 常见用户安装路径（Windows Python Launcher / 用户目录）
55
+ # 常见用户安装路径不写死绝对盘符/用户名；仅用 PATH / py launcher
56
56
  for extra in (
57
- r'C:\Users\p64101\AppData\Local\Programs\Python\Python312\python.exe',
57
+ r'py',
58
58
  ):
59
- if Path(extra).exists():
59
+ if Path(extra).exists() or shutil.which(extra):
60
60
  candidates.append(extra)
61
61
  alt = None
62
62
  for exe in candidates: