@agile-team/wl-skills-kit 2.1.0 → 2.1.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [2.1.1] - 2026-04-26
+
+### 🔧 修复与迁移增强
+
+#### bin 字段修复
+- `package.json` 新增 `"main": "./bin/wl-skills.js"` —— 修复 npm v9+ 发布时 bin 条目被剔除导致 `npx` 无法找到入口的问题
+- bin 命令从 `wl-skills-kit` 重命名为 `wl-skills`（避免与包名重复触发 npm 校验警告；全局安装后可直接用 `wl-skills update`）
+
+#### 旧版用户升级支持
+- `bin/wl-skills.js` 新增 `LEGACY_PATHS` 迁移清理机制：
+  - `update` 时自动检测并移除 v1.x/v2.0 遗留文件（旧 flat 结构 Skill 路径、废弃 `docs/` 文件等）
+  - 共 24 个旧版路径纳入清理名单，避免新旧结构并存产生 AI 调度歧义
+  - 输出 "迁移: N 个旧版文件已移除" 统计信息
+- README 新增"从早期版本升级"章节（含 `env.local.json` 迁移注意事项）
+
+---
+
 ## [2.1.0] - 2026-04-26
 
 ### 🎯 多 AI 编辑器适配解耦 + 文档体系完善

package/README.md

@@ -163,6 +163,26 @@ npx @agile-team/wl-skills-kit clean --keep-reports
 npx @agile-team/wl-skills-kit update --dry-run
 ```
 
+> 全局安装后也可直接用 `wl-skills` 命令（如 `wl-skills update`）。
+
+---
+
+## 从早期版本升级
+
+> **适用场景**：已安装 v1.x 或 v2.0 的业务项目，希望升级到当前版本。
+
+```bash
+# 执行增量更新即可
+npx @agile-team/wl-skills-kit update
+```
+
+`update` 命令会自动完成：
+1. **写入新文件** — 新结构下的所有文件覆盖写入
+2. **迁移清理** — 检测并移除旧版遗留文件（如 `skills/prototype-scan/`、`docs/menu-sync-design.md` 等），避免新旧路径并存产生歧义
+3. **保护累积数据** — `reports/*.md` 已存在则跳过，团队累积的菜单/字典数据不丢失
+
+> **注意**：如果项目在旧的 `.github/skills/menu-sync/env/env.local.json` 中有自定义配置，`update` 会将其迁移位置（删旧、新路径文件由 `init` 写入默认模板）。**请在 `update` 前备份** 或 `update` 后手动迁移到 `.github/skills/sync/menu-sync/env/env.local.json`。
+
 ---
 
 ## Skill 概览

package/bin/wl-skills.js

@@ -162,6 +162,36 @@ function isReportFile(relPath) {
   return relPath.startsWith(".github/reports/") && relPath.endsWith(".md");
 }
 
+// ─── 旧版遗留路径（v1.x/v2.0 → v2.1 迁移清理）───────────────────────────
+// update 时自动检测并移除，避免旧结构与新结构并存产生歧义。
+const LEGACY_PATHS = [
+  // Skill 目录重组：flat → core/sync/ops 分级（v2.1）
+  ".github/skills/prototype-scan/SKILL.md",
+  ".github/skills/api-contract/SKILL.md",
+  ".github/skills/page-codegen/SKILL.md",
+  ".github/skills/page-codegen/TPL-LIST.md",
+  ".github/skills/page-codegen/TPL-MASTER-DETAIL.md",
+  ".github/skills/page-codegen/TPL-TREE-LIST.md",
+  ".github/skills/page-codegen/TPL-DETAIL-TABS.md",
+  ".github/skills/page-codegen/TPL-FORM-ROUTE.md",
+  ".github/skills/page-codegen/TPL-CHANGE-HISTORY.md",
+  ".github/skills/page-codegen/TPL-RECORD-FORM.md",
+  ".github/skills/page-codegen/TPL-DRIVEN.md",
+  ".github/skills/page-codegen/TPL-OPERATION-STATION.md",
+  ".github/skills/menu-sync/SKILL.md",
+  ".github/skills/menu-sync/env/env.local.json",
+  ".github/skills/menu-sync/env/guide.md",
+  ".github/skills/convention-extract/SKILL.md", // 已更名为 convention-audit
+  // docs/ 废弃文件：内容已迁移至 guides/ 或 reports/（v2.0）
+  ".github/docs/menu-sync-design.md",
+  ".github/docs/use-skill.md",
+  ".github/docs/wl-skills-kit.md",
+  ".github/docs/SYS_MENU_INFO.md", // 已迁移至 reports/
+  // _compat/ 旧说明文件（v2.0 → v2.1 重构为可执行配置层）
+  ".github/skills/_compat/ai-model-matrix.md",
+  ".github/skills/_compat/editor-setup.md",
+];
+
 // ─── 编辑器配置生成（从 _compat/editors.json 读取，特化 frontmatter 注入）─────
 
 const AUTO_HEADER_NOTE =
@@ -311,7 +341,33 @@ function runInstall(incremental) {
     }
   }
 
-  // ── Step 3: 写 manifest ────────────────────────────────────────────
+  // ── Step 3: 迁移清理（仅 update，清理旧版遗留文件）──────────────────
+
+  if (incremental) {
+    let migrated = 0;
+    if (dryRun) console.log("\n  [Step 3] 旧版遗留文件检查（迁移清理）:\n");
+    for (const legacyRel of LEGACY_PATHS) {
+      const legacyFull = path.join(TARGET_DIR, legacyRel);
+      if (fs.existsSync(legacyFull)) {
+        if (dryRun) {
+          console.log("  迁移清理  " + legacyRel + "  (旧版遗留，将被移除)");
+        } else {
+          removeFileAndEmptyParents(legacyFull);
+        }
+        migrated++;
+      }
+    }
+    if (!dryRun && migrated > 0) {
+      console.log(
+        "    迁移: " + migrated + " 个旧版文件已移除（路径已变更，见 CHANGELOG.md）",
+      );
+    }
+    if (dryRun && migrated === 0) {
+      console.log("  （无旧版遗留文件）");
+    }
+  }
+
+  // ── Step 4: 写 manifest ────────────────────────────────────────────
 
   if (!dryRun) writeManifest(newManifest);
 

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@agile-team/wl-skills-kit",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "AI Skill 模板包 — 一键导入 AI 指令 + 组件文档 + 通用组件 + 领域样例，覆盖 Copilot/Cursor/Windsurf/Kiro 等主流 AI 编辑器",
+  "main": "./bin/wl-skills.js",
   "bin": {
-    "wl-skills-kit": "./bin/wl-skills.js"
+    "wl-skills": "./bin/wl-skills.js"
   },
   "files": [
     "bin/",