@topmindspace/tms-skills 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## Unreleased
+
+## 0.1.1 — 2026-09-24
+
+### Fixes (P0 / P1)
+
+- **Release 顺序与稳健性**：Privacy → 技能门禁 → Package → Collect → GitHub Release → **npm publish（已发布则跳过，避免 E409）** → 再 Prune。
+- **Prune 策略**：只删旧 GitHub Release（保留 2 个）；**不再删除 git tags**。
+- **多技能发现**：`scripts/discover_skills.js` + CI/Release 动态打包/门禁；`npm run sync:files` 同步 `package.json` `files`。
+- **CLI**：校验 skill id；目标目录已存在时须 `--force`；文档口径与 README 对齐（npm 推荐 / GitHub 跟 HEAD）。
+- **python3**：根与技能 `package.json`、workflows 统一 `python3`。
+- **打包门禁**：`references/layout-grammar.md` 纳入 REQUIRED；去掉与 `theme-overview.png` 完全重复的 `theme-overview-presentation.png`。
+- **Lockfile**：提交 `top-ppt-html/package-lock.json`；CI 优先 `npm ci --omit=dev`。
+- **npm 2.x**：文档警告勿装 `^2`；提供 `scripts/deprecate-npm-2x.sh`（须维护者本地 npm 登录后执行）。
+
 ## 0.1.0 — 2026-09-24
 
 首个公开版本。

package/README.md

@@ -18,6 +18,12 @@
 
 两条通道，装出来同一套技能。**npm = 钉版本快照**；**GitHub = 跟仓库 HEAD**。
 
+
+> **警告 / Warning**：不要安装 `@topmindspace/tms-skills@^2`。npm 上残留的 **2.0.0–2.1.1** 是仓库重置前的过时线；当前线是 **0.1.x**（`latest` 亦指向 0.1.x）。维护者登录 npm 后可运行 `scripts/deprecate-npm-2x.sh` 标记弃用。
+>
+> Do **not** install `^2`. Versions 2.0.0–2.1.1 are obsolete after the repo reset; use **0.1.x**. Maintainers with npm auth should run `scripts/deprecate-npm-2x.sh`.
+
+
 ### npm（推荐）
 
 ```bash
@@ -74,7 +80,7 @@ tms-skills/
 | tag `vX.Y.Z` | Release + zip | **自动 publish** |
 
 - **push 不会更新 npm**；必须 bump 版本并打 tag。
-- **Release 只保留最近 2 个**（CI 自动清理）；npm 可钉任意历史版本。
+- **Release 只保留最近 2 个**（CI 只删旧 Release，**git tags 保留**）；npm 可钉任意历史版本。
 - 安装器与技能 **版本各自独立**；默认 patch/minor，major 仅破坏性变更。
 
 详见 [docs/PUBLISHING.md](./docs/PUBLISHING.md)。
@@ -84,7 +90,7 @@ tms-skills/
 | 工作流 | 触发 | 做什么 |
 |--------|------|--------|
 | `ci.yml` | push / PR | 打包门禁、审计、隐私扫描、CLI 冒烟 |
-| `release.yml` | tag `v*` | 技能 zip → Release；npm publish；Release 保留 2 个 |
+| `release.yml` | tag `v*` | 门禁 → zip → Release → npm publish（已存在则跳过）→ prune Release 留 2（tags 保留） |
 
 ```bash
 npm run check && npm run audit && npm run privacy
@@ -95,7 +101,7 @@ 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`。
+4. 登记：根 README、`npm run sync:files`、`CHANGELOG.md`（CI 按发现的技能跑门禁，无需再硬编码）。
 
 ## 许可证
 

package/bin/tms-skills.js

@@ -1,160 +1,200 @@
-#!/usr/bin/env node
-/**
- * tms-skills — TopMindspace agent skills installer
- *
- * Usage (GitHub is the primary install source — npm publish is optional):
- *   npx github:topmindspace/tms-skills list
- *   npx github:topmindspace/tms-skills install top-ppt-html
- *   npx github:topmindspace/tms-skills install top-ppt-html --to ./skills-out
- *   npx @topmindspace/tms-skills install top-ppt-html   # only after npm publish
- */
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-
-const ROOT = path.resolve(__dirname, '..');
-// Skills live at repo root (one directory per skill with SKILL.md).
-const INFRA_DIRS = new Set(['bin', 'docs', 'scripts', 'node_modules', 'dist', 'release-assets']);
-
-function die(msg, code = 1) {
-  console.error(msg);
-  process.exit(code);
-}
-
-function skillDir(skillId) {
-  return path.join(ROOT, skillId);
-}
-
-function listSkillIds() {
-  return fs
-    .readdirSync(ROOT, { withFileTypes: true })
-    .filter((d) => d.isDirectory() && !INFRA_DIRS.has(d.name) && !d.name.startsWith('.'))
-    .filter((d) => fs.existsSync(path.join(ROOT, d.name, 'SKILL.md')))
-    .map((d) => d.name)
-    .sort();
-}
-
-function readSkillMeta(skillId) {
-  const skillPath = skillDir(skillId);
-  const skillMd = path.join(skillPath, 'SKILL.md');
-  if (!fs.existsSync(skillMd)) return { id: skillId, description: '' };
-  const text = fs.readFileSync(skillMd, 'utf8');
-  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!m) return { id: skillId, description: '' };
-  const desc = (m[1].match(/^description:\s*"(.*)"\s*$/m) || m[1].match(/^description:\s*(.+)\s*$/m) || [])[1] || '';
-  return { id: skillId, description: String(desc).slice(0, 120) };
-}
-
-function resolveDefaultTarget() {
-  const candidates = [
-    path.join(process.cwd(), '.agents', 'skills'),
-    path.join(process.cwd(), '.claude', 'skills'),
-    path.join(process.cwd(), '.mimocode', 'skills'),
-    path.join(process.env.HOME || process.env.USERPROFILE || '', '.claude', 'skills'),
-    path.join(process.env.HOME || process.env.USERPROFILE || '', '.agents', 'skills'),
-  ];
-  for (const dir of candidates) {
-    if (dir && fs.existsSync(path.dirname(dir))) {
-      return dir;
-    }
-  }
-  return path.join(process.cwd(), '.agents', 'skills');
-}
-
-function copyDir(src, dest) {
-  fs.mkdirSync(dest, { recursive: true });
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    const s = path.join(src, entry.name);
-    const d = path.join(dest, entry.name);
-    if (entry.isDirectory()) {
-      if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '__pycache__') continue;
-      copyDir(s, d);
-    } else if (entry.isFile()) {
-      if (entry.name.endsWith('.pyc')) continue;
-      fs.copyFileSync(s, d);
-    }
-  }
-}
-
-function install(skillId, targetRoot) {
-  const src = skillDir(skillId);
-  if (!fs.existsSync(path.join(src, 'SKILL.md'))) {
-    die(`Skill not found: ${skillId}\nAvailable: ${listSkillIds().join(', ') || '(none)'}`);
-  }
-  const dest = path.join(targetRoot, skillId);
-  fs.mkdirSync(targetRoot, { recursive: true });
-  if (fs.existsSync(dest)) {
-    fs.rmSync(dest, { recursive: true, force: true });
-  }
-  copyDir(src, dest);
-  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`);
-}
-
-function usage() {
-  console.log(`tms-skills — install TopMindspace agent skills
-
-Usage:
-  tms-skills list
-  tms-skills install <skill-id> [--to <dir>]
-  tms-skills help
-
-Examples:
-  npx github:topmindspace/tms-skills list
-  npx github:topmindspace/tms-skills install top-ppt-html
-  npx github:topmindspace/tms-skills install top-ppt-html --to ./.agents/skills
-
-  # Optional npm package (only after @topmindspace/tms-skills is published):
-  npx @topmindspace/tms-skills install top-ppt-html
-`);
-}
-
-function main(argv) {
-  const args = argv.slice(2);
-  const cmd = args[0];
-
-  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
-    usage();
-    return;
-  }
-
-  if (cmd === 'list' || cmd === 'ls') {
-    const ids = listSkillIds();
-    if (!ids.length) {
-      console.log('No skills found in package.');
-      return;
-    }
-    for (const id of ids) {
-      const meta = readSkillMeta(id);
-      console.log(`${id}`);
-      if (meta.description) console.log(`  ${meta.description}…`);
-    }
-    return;
-  }
-
-  if (cmd === 'install') {
-    const skillId = args[1];
-    if (!skillId || skillId.startsWith('-')) {
-      die('Missing skill id.\n\n' + usage());
-    }
-    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.');
-      }
-    }
-    const targetRoot = to ? path.resolve(to) : resolveDefaultTarget();
-    install(skillId, targetRoot);
-    return;
-  }
-
-  die(`Unknown command: ${cmd}\n\n` + usage());
-}
-
-main(process.argv);
+#!/usr/bin/env node
+/**
+ * tms-skills — TopMindspace agent skills installer
+ *
+ * Recommended channel (when published): npm @topmindspace/tms-skills
+ * GitHub npx remains available for HEAD / offline clone.
+ *
+ * Usage:
+ *   npx @topmindspace/tms-skills list
+ *   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 github:topmindspace/tms-skills install top-ppt-html   # follow repo HEAD
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+// Skills live at repo root (one directory per skill with SKILL.md).
+const INFRA_DIRS = new Set(['bin', 'docs', 'scripts', 'node_modules', 'dist', 'release-assets']);
+const SKILL_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function die(msg, code = 1) {
+  console.error(msg);
+  process.exit(code);
+}
+
+function skillDir(skillId) {
+  return path.join(ROOT, skillId);
+}
+
+function assertSkillId(skillId) {
+  if (!skillId || typeof skillId !== 'string') {
+    die('Missing skill id.\n\n' + usageText());
+  }
+  if (
+    skillId.includes('..') ||
+    skillId.includes('/') ||
+    skillId.includes('\\') ||
+    path.isAbsolute(skillId) ||
+    !SKILL_ID_RE.test(skillId)
+  ) {
+    die(
+      `Invalid skill id: ${JSON.stringify(skillId)}\n` +
+        'Skill ids must match ^[a-z0-9]+(?:-[a-z0-9]+)*$ (no paths, dots, or slashes).'
+    );
+  }
+}
+
+function listSkillIds() {
+  return fs
+    .readdirSync(ROOT, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !INFRA_DIRS.has(d.name) && !d.name.startsWith('.'))
+    .filter((d) => fs.existsSync(path.join(ROOT, d.name, 'SKILL.md')))
+    .map((d) => d.name)
+    .sort();
+}
+
+function readSkillMeta(skillId) {
+  const skillPath = skillDir(skillId);
+  const skillMd = path.join(skillPath, 'SKILL.md');
+  if (!fs.existsSync(skillMd)) return { id: skillId, description: '' };
+  const text = fs.readFileSync(skillMd, 'utf8');
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return { id: skillId, description: '' };
+  const desc = (m[1].match(/^description:\s*"(.*)"\s*$/m) || m[1].match(/^description:\s*(.+)\s*$/m) || [])[1] || '';
+  return { id: skillId, description: String(desc).slice(0, 120) };
+}
+
+function resolveDefaultTarget() {
+  const candidates = [
+    path.join(process.cwd(), '.agents', 'skills'),
+    path.join(process.cwd(), '.claude', 'skills'),
+    path.join(process.cwd(), '.mimocode', 'skills'),
+    path.join(process.env.HOME || process.env.USERPROFILE || '', '.claude', 'skills'),
+    path.join(process.env.HOME || process.env.USERPROFILE || '', '.agents', 'skills'),
+  ];
+  for (const dir of candidates) {
+    if (dir && fs.existsSync(path.dirname(dir))) {
+      return dir;
+    }
+  }
+  return path.join(process.cwd(), '.agents', 'skills');
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '__pycache__') continue;
+      copyDir(s, d);
+    } else if (entry.isFile()) {
+      if (entry.name.endsWith('.pyc')) continue;
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function install(skillId, targetRoot, { force = false } = {}) {
+  assertSkillId(skillId);
+  const src = skillDir(skillId);
+  if (!fs.existsSync(path.join(src, 'SKILL.md'))) {
+    die(`Skill not found: ${skillId}\nAvailable: ${listSkillIds().join(', ') || '(none)'}`);
+  }
+  const dest = path.join(targetRoot, skillId);
+  fs.mkdirSync(targetRoot, { recursive: true });
+  if (fs.existsSync(dest)) {
+    if (!force) {
+      die(
+        `Destination already exists: ${dest}\n` +
+          'Refusing to overwrite. Pass --force (or -f) to replace.'
+      );
+    }
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+  copyDir(src, dest);
+  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`);
+}
+
+function usageText() {
+  return `tms-skills — install TopMindspace agent skills
+
+Usage:
+  tms-skills list
+  tms-skills install <skill-id> [--to <dir>] [--force|-f]
+  tms-skills help
+
+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
+
+  # Follow repo HEAD:
+  npx github:topmindspace/tms-skills install top-ppt-html
+`;
+}
+
+function usage() {
+  console.log(usageText());
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  const cmd = args[0];
+
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    usage();
+    return;
+  }
+
+  if (cmd === 'list' || cmd === 'ls') {
+    const ids = listSkillIds();
+    if (!ids.length) {
+      console.log('No skills found in package.');
+      return;
+    }
+    for (const id of ids) {
+      const meta = readSkillMeta(id);
+      console.log(`${id}`);
+      if (meta.description) console.log(`  ${meta.description}…`);
+    }
+    return;
+  }
+
+  if (cmd === 'install') {
+    const skillId = args[1];
+    if (!skillId || skillId.startsWith('-')) {
+      die('Missing skill id.\n\n' + usageText());
+    }
+    let to = null;
+    let force = false;
+    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 if (args[i] === '--force' || args[i] === '-f') {
+        force = true;
+      } else {
+        die(`Unknown option: ${args[i]}\n\n` + usageText());
+      }
+    }
+    const targetRoot = to ? path.resolve(to) : resolveDefaultTarget();
+    install(skillId, targetRoot, { force });
+    return;
+  }
+
+  die(`Unknown command: ${cmd}\n\n` + usageText());
+}
+
+main(process.argv);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@topmindspace/tms-skills",
-  "version": "0.1.0",
-  "description": "TopMindspace 智能体技能 monorepo — 通过 GitHub npx 安装技能（top-ppt-html 等）。",
+  "version": "0.1.1",
+  "description": "TopMindspace 智能体技能 monorepo — 通过 npm / GitHub npx 安装技能（top-ppt-html 等）。",
   "license": "MIT",
   "author": "TopMindspace",
   "repository": {
@@ -26,21 +26,24 @@
   },
   "files": [
     "bin",
-    "top-ppt-html",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "top-ppt-html"
   ],
   "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"
+    "discover": "node scripts/discover_skills.js",
+    "sync:files": "node scripts/sync_npm_files.js",
+    "prepack": "node scripts/sync_npm_files.js",
+    "install:skills": "node -e \"const {discoverSkills}=require('./scripts/discover_skills'); const {spawnSync}=require('child_process'); for (const id of discoverSkills()) { const r=spawnSync(process.execPath,['bin/tms-skills.js','install',id],{stdio:'inherit'}); if(r.status) process.exit(r.status||1); }\"",
+    "check": "node scripts/run_skill_gates.js check",
+    "privacy": "python3 scripts/ci_privacy_scan.py",
+    "audit": "node scripts/run_skill_gates.js audit",
+    "package:skill": "node scripts/run_skill_gates.js package"
   },
   "publishConfig": {
     "access": "public"