dk-frontend-skills 1.1.4 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dk-frontend-skills",
-  "version": "1.1.4",
+  "version": "2.0.0",
   "description": "dk-engineer - 幽默沉稳靠谱的前端开发助手 Claude Skills 配置包，一键注入 .claude/ 技能目录和 CLAUDE.md 人设配置",
   "author": "XiaoMa",
   "license": "MIT",
@@ -10,6 +10,9 @@
     "CLAUDE.md",
     "scripts/"
   ],
+  "bin": {
+    "dk-skills": "./scripts/cli.js"
+  },
   "scripts": {
     "postinstall": "node scripts/copy-skills.js"
   }

package/scripts/cli.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+const { getPackageSkills, getUserSkills } = require("./core");
+
+// 定位项目根目录和包目录
+const projectRoot = path.resolve(__dirname, "..", "..", "..");
+const packageDir = path.join(__dirname, "..");
+const claudeDest = path.join(projectRoot, ".claude");
+const settingsPath = path.join(claudeDest, "settings.json");
+
+const command = process.argv[2];
+const args = process.argv.slice(3);
+
+// ---------- 辅助函数 ----------
+
+function readSettings() {
+  if (!fs.existsSync(settingsPath)) return { skills: {}, always_apply_skills: [] };
+  try {
+    return JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+  } catch {
+    return { skills: {}, always_apply_skills: [] };
+  }
+}
+
+function writeSettings(settings) {
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * 保存技能选择结果到 settings.json
+ */
+function saveSkillSelection(choices) {
+  const settings = readSettings();
+  if (!settings.skills) settings.skills = {};
+
+  for (const { name, enabled } of choices) {
+    if (!settings.skills[name]) {
+      settings.skills[name] = {};
+    }
+    settings.skills[name].enabled = enabled;
+  }
+
+  writeSettings(settings);
+}
+
+// ---------- 命令：list ----------
+
+function cmdList() {
+  const pkgSkills = getPackageSkills(packageDir);
+  const userSkills = getUserSkills(claudeDest);
+
+  // 合并包内和用户已安装的技能状态
+  const skillMap = new Map();
+  for (const s of userSkills) skillMap.set(s.name, s);
+  for (const s of pkgSkills) {
+    if (!skillMap.has(s.name)) {
+      skillMap.set(s.name, { ...s, enabled: false, installed: false });
+    }
+  }
+
+  const allSkills = [...skillMap.values()];
+
+  console.log("\n📋 dk-frontend-skills 技能清单\n");
+  console.log("  状态    技能名               版本    描述");
+  console.log("  ─────────────────────────────────────────────────────");
+
+  for (const skill of allSkills) {
+    const status = skill.enabled ? "✅ 启用" : "⏸️  停用";
+    const name = skill.name.padEnd(20);
+    const ver = skill.version.padEnd(7);
+    const desc = skill.description || "(无描述)";
+    console.log(`  ${status}  ${name} ${ver} ${desc}`);
+  }
+
+  console.log(`\n  💡 运行 npx dk-skills 进入交互选择模式\n`);
+}
+
+// ---------- 命令：enable / disable ----------
+
+function cmdToggle(enable, names) {
+  if (names.length === 0) {
+    console.log(`  用法: npx dk-skills ${enable ? "enable" : "disable"} <技能名...>`);
+    return;
+  }
+
+  const pkgSkills = getPackageSkills(packageDir);
+  const pkgNames = new Set(pkgSkills.map((s) => s.name));
+  const userSkills = getUserSkills(claudeDest);
+  const userNames = new Set(userSkills.map((s) => s.name));
+
+  const notFound = names.filter((n) => !pkgNames.has(n));
+  if (notFound.length > 0) {
+    console.log(`  ⚠️  未知技能: ${notFound.join(", ")}`);
+    console.log(`  可用: ${[...pkgNames].join(", ")}\n`);
+    return;
+  }
+
+  const notInstalled = names.filter((n) => !userNames.has(n));
+  if (notInstalled.length > 0) {
+    console.log(`  ⚠️  以下技能尚未安装: ${notInstalled.join(", ")}`);
+    console.log(`  请先执行 npm i dk-frontend-skills 安装完整技能包\n`);
+    return;
+  }
+
+  const choices = userSkills.map((s) => ({
+    name: s.name,
+    enabled: names.includes(s.name) ? enable : s.enabled,
+  }));
+
+  saveSkillSelection(choices);
+
+  const action = enable ? "启用" : "停用";
+  console.log(`  ✅ 已${action}: ${names.join(", ")}\n`);
+}
+
+// ---------- 交互式 TUI 菜单 ----------
+
+function startInteractiveMenu() {
+  const pkgSkills = getPackageSkills(packageDir);
+
+  if (pkgSkills.length === 0) {
+    console.log("  ⚠️  包内没有可用技能\n");
+    process.exit(0);
+  }
+
+  // 读取当前 settings 中的启用状态
+  const userSkills = getUserSkills(claudeDest);
+  const userMap = new Map(userSkills.map((s) => [s.name, s.enabled]));
+
+  // choices 只包含包内有的技能
+  const skills = pkgSkills.map((s) => ({
+    ...s,
+    enabled: userMap.has(s.name) ? userMap.get(s.name) : false,
+  }));
+
+  let cursor = 0;
+  const toggled = skills.map((s) => s.enabled);
+  const stdin = process.stdin;
+  const stdout = process.stdout;
+
+  function render() {
+    stdout.write("\x1Bc"); // 清屏
+    stdout.write("╔══════════════════════════════════════════════╗\n");
+    stdout.write("║       dk-frontend-skills  技能选择          ║\n");
+    stdout.write("╠══════════════════════════════════════════════╣\n");
+    stdout.write("║  ↑↓ 导航   ␣ 开关   Enter 确认   q 退出   ║\n");
+    stdout.write("╚══════════════════════════════════════════════╝\n\n");
+
+    for (let i = 0; i < skills.length; i++) {
+      const s = skills[i];
+      const arrow = i === cursor ? "❯" : " ";
+      const check = toggled[i] ? "✓" : " ";
+      const name = s.name.padEnd(20);
+      const desc = s.description || "";
+      stdout.write(` ${arrow} [${check}] ${name} ${desc}\n`);
+    }
+
+    stdout.write("\n  选中: ");
+    const selectedNames = skills.filter((_, i) => toggled[i]).map((s) => s.name);
+    if (selectedNames.length === 0) {
+      stdout.write("(无)");
+    } else if (selectedNames.length <= 3) {
+      stdout.write(selectedNames.join(", "));
+    } else {
+      stdout.write(`${selectedNames.length} 个技能`);
+    }
+    stdout.write("\n");
+  }
+
+  function exitMenu(saved) {
+    stdin.setRawMode(false);
+    stdin.pause();
+    if (saved) {
+      console.log("\n  ✅ 技能选择已保存\n");
+    }
+    process.exit(0);
+  }
+
+  render();
+
+  readline.emitKeypressEvents(stdin);
+  if (stdin.isTTY) stdin.setRawMode(true);
+  stdin.resume();
+
+  stdin.on("keypress", (str, key) => {
+    if (!key) return;
+
+    if (key.name === "up") {
+      cursor = Math.max(0, cursor - 1);
+      render();
+    } else if (key.name === "down") {
+      cursor = Math.min(skills.length - 1, cursor + 1);
+      render();
+    } else if (key.name === "space") {
+      toggled[cursor] = !toggled[cursor];
+      render();
+    } else if (key.name === "return") {
+      const choices = skills.map((s, i) => ({ name: s.name, enabled: toggled[i] }));
+      saveSkillSelection(choices);
+      exitMenu(true);
+    } else if (key.name === "q" || (key.ctrl && key.name === "c")) {
+      exitMenu(false);
+    }
+  });
+}
+
+// ---------- 主入口 ----------
+
+const COMMANDS = ["list", "enable", "disable"];
+
+if (!command) {
+  // 无参数 → 启动交互菜单
+  startInteractiveMenu();
+} else if (command === "--help" || command === "-h") {
+  console.log(`
+  dk-frontend-skills CLI
+
+  用法:
+    npx dk-skills             交互式技能选择菜单
+    npx dk-skills list        查看技能清单
+    npx dk-skills enable  <技能名...>   启用指定技能
+    npx dk-skills disable <技能名...>   停用指定技能
+    npx dk-skills --help      显示帮助
+
+  示例:
+    npx dk-skills list
+    npx dk-skills enable vue fe-biz-patterns
+    npx dk-skills disable moai-framework-electron
+`);
+} else if (command === "list") {
+  cmdList();
+} else if (command === "enable") {
+  cmdToggle(true, args);
+} else if (command === "disable") {
+  cmdToggle(false, args);
+} else {
+  console.log(`  未知命令: ${command}\n  可用: ${COMMANDS.join(", ")}\n`);
+  process.exit(1);
+}

package/scripts/copy-skills.js

@@ -1,5 +1,12 @@
 const fs = require("fs");
 const path = require("path");
+const {
+  backupTimestamp,
+  appendLog,
+  backupDir,
+  installSkills,
+  installSettings,
+} = require("./core");
 
 // 获取用户项目根目录
 const projectRoot = path.resolve(__dirname, "..", "..", "..");
@@ -16,214 +23,6 @@ const mdDest = path.join(projectRoot, "CLAUDE.md");
 // 日志文件
 const logFile = path.join(claudeDest, ".install.log");
 
-// 时间戳格式：YYYY-MM-DD HH:mm:ss
-function timestamp() {
-  const d = new Date();
-  const pad = (n) => String(n).padStart(2, "0");
-  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
-}
-
-// 紧凑时间戳用于备份目录名：YYYYMMDD.HHmmss
-function backupTimestamp() {
-  const d = new Date();
-  const pad = (n) => String(n).padStart(2, "0");
-  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}.${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
-}
-
-/**
- * 追加日志到 .claude/.install.log
- * 如果 .claude 目录还不存在，先创建
- */
-function appendLog(level, message) {
-  const dir = path.dirname(logFile);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-  const line = `[${timestamp()}] [${level}] ${message}\n`;
-  fs.appendFileSync(logFile, line, "utf-8");
-}
-
-/**
- * 备份已有目录到 .claude/backups/<timestamp>/
- * 注意：排除 backups/ 自身，避免复制到子目录
- * 清理超过 3 份的旧备份
- */
-function backupDir(dir) {
-  if (!fs.existsSync(dir)) return null;
-
-  const backupsDir = path.join(dir, "backups");
-  if (!fs.existsSync(backupsDir)) {
-    fs.mkdirSync(backupsDir, { recursive: true });
-  }
-
-  const ts = backupTimestamp();
-  const bakPath = path.join(backupsDir, ts);
-  fs.mkdirSync(bakPath, { recursive: true });
-
-  // 逐项复制，排除 backups/ 避免自引用
-  for (const item of fs.readdirSync(dir)) {
-    if (item === "backups") continue;
-    fs.cpSync(path.join(dir, item), path.join(bakPath, item), { recursive: true });
-  }
-
-  appendLog("BACKUP", `backups/${ts}/ created`);
-  console.log(`  💾 备份 → .claude/backups/${ts}/`);
-
-  // 清理旧备份，只保留最近 3 份
-  const backups = fs
-    .readdirSync(backupsDir)
-    .filter((name) => /^\d{8}\.\d{6}$/.test(name))
-    .sort()
-    .reverse();
-
-  if (backups.length > 3) {
-    for (const old of backups.slice(3)) {
-      const oldPath = path.join(backupsDir, old);
-      fs.rmSync(oldPath, { recursive: true, force: true });
-      appendLog("CLEAN", `清除旧备份 backups/${old}/`);
-    }
-  }
-
-  return bakPath;
-}
-
-/**
- * 递归深合并
- * 用户值优先（原样保留），目标新增字段补充
- * 只有纯对象才递归合并，数组和原始值直接取用户的值
- */
-function deepMerge(userObj, pkgObj) {
-  const result = { ...userObj };
-
-  for (const key of Object.keys(pkgObj)) {
-    if (!(key in result)) {
-      // 用户没有这个 key，直接用包的
-      result[key] = pkgObj[key];
-    } else if (
-      isPlainObject(pkgObj[key]) &&
-      isPlainObject(result[key])
-    ) {
-      // 双方都是纯对象，递归合并
-      result[key] = deepMerge(result[key], pkgObj[key]);
-    }
-    // 其他情况：用户值优先，不动
-  }
-
-  return result;
-}
-
-function isPlainObject(val) {
-  return Object.prototype.toString.call(val) === "[object Object]";
-}
-
-/**
- * 读取技能目录下的 .meta.json
- * 没有则返回 null
- */
-function readMeta(skillDir) {
-  const metaPath = path.join(skillDir, ".meta.json");
-  if (fs.existsSync(metaPath)) {
-    try {
-      return JSON.parse(fs.readFileSync(metaPath, "utf-8"));
-    } catch {
-      return null;
-    }
-  }
-  return null;
-}
-
-/**
- * 安装技能
- * 逐个复制技能目录，补缺不覆盖，记录日志
- */
-function installSkills(skillsSource, skillsDest) {
-  if (!fs.existsSync(skillsSource)) return [];
-
-  if (!fs.existsSync(skillsDest)) {
-    fs.mkdirSync(skillsDest, { recursive: true });
-  }
-
-  const skillDirs = fs.readdirSync(skillsSource);
-  const results = [];
-
-  for (const dir of skillDirs) {
-    const srcSkill = path.join(skillsSource, dir);
-    const destSkill = path.join(skillsDest, dir);
-    const meta = readMeta(srcSkill);
-    const version = meta ? meta.version : "?";
-
-    if (!fs.existsSync(destSkill)) {
-      // 新安装
-      fs.cpSync(srcSkill, destSkill, { recursive: true });
-      appendLog("SKILL", `${dir} (${version}) → installed`);
-      results.push({ name: dir, version, action: "installed" });
-    } else {
-      // 补版本：检测元信息，有更新才覆盖
-      const destMeta = readMeta(destSkill);
-      const needUpdate = meta && destMeta && meta.version !== destMeta.version;
-
-      if (needUpdate) {
-        // 先备份旧技能
-        const bakName = `${dir}.bak.${backupTimestamp()}`;
-        const bakPath = path.join(skillsDest, bakName);
-        fs.cpSync(destSkill, bakPath, { recursive: true });
-
-        // 删旧的，复制新的
-        fs.rmSync(destSkill, { recursive: true, force: true });
-        fs.cpSync(srcSkill, destSkill, { recursive: true });
-
-        appendLog("SKILL", `${dir} (${destMeta.version} → ${meta.version}) → updated`);
-        results.push({ name: dir, version: meta.version, action: "updated" });
-      } else {
-        appendLog("SKILL", `${dir} (${version}) → skipped (exists)`);
-        results.push({ name: dir, version, action: "skipped" });
-      }
-    }
-  }
-
-  return results;
-}
-
-/**
- * 安装 settings.json
- * 用深度合并策略，用户自定义优先
- */
-function installSettings(sourceDir, destDir) {
-  const settingsSource = path.join(sourceDir, "settings.json");
-  const settingsDest = path.join(destDir, "settings.json");
-  const localSource = path.join(sourceDir, "settings.local.json");
-  const localDest = path.join(destDir, "settings.local.json");
-
-  if (fs.existsSync(settingsSource)) {
-    if (fs.existsSync(settingsDest)) {
-      // 深度合并
-      const userSettings = JSON.parse(fs.readFileSync(settingsDest, "utf-8"));
-      const pkgSettings = JSON.parse(fs.readFileSync(settingsSource, "utf-8"));
-      const merged = deepMerge(userSettings, pkgSettings);
-      fs.writeFileSync(settingsDest, JSON.stringify(merged, null, 2) + "\n", "utf-8");
-      appendLog("SETTINGS", "settings.json merged");
-    } else {
-      // 用户没有，直接复制
-      fs.copyFileSync(settingsSource, settingsDest);
-      appendLog("SETTINGS", "settings.json created");
-    }
-  }
-
-  // settings.local.json 同样处理
-  if (fs.existsSync(localSource)) {
-    if (fs.existsSync(localDest)) {
-      const userLocal = JSON.parse(fs.readFileSync(localDest, "utf-8"));
-      const pkgLocal = JSON.parse(fs.readFileSync(localSource, "utf-8"));
-      const merged = deepMerge(userLocal, pkgLocal);
-      fs.writeFileSync(localDest, JSON.stringify(merged, null, 2) + "\n", "utf-8");
-      appendLog("SETTINGS", "settings.local.json merged");
-    } else {
-      fs.copyFileSync(localSource, localDest);
-      appendLog("SETTINGS", "settings.local.json created");
-    }
-  }
-}
-
 // ===================== 主流程 =====================
 
 console.log("\n📦 dk-frontend-skills 技能包安装开始\n");
@@ -231,30 +30,28 @@ console.log("\n📦 dk-frontend-skills 技能包安装开始\n");
 if (fs.existsSync(claudeSource)) {
   if (fs.existsSync(claudeDest)) {
     // .claude 已存在 → 备份后再操作
-    appendLog("INFO", "Install started (upgrade)");
+    appendLog(logFile, "INFO", "Install started (upgrade)");
     backupDir(claudeDest);
 
     const skillsSource = path.join(claudeSource, "skills");
     const skillsDest = path.join(claudeDest, "skills");
 
-    installSkills(skillsSource, skillsDest);
-    installSettings(claudeSource, claudeDest);
+    installSkills(skillsSource, skillsDest, logFile);
+    installSettings(claudeSource, claudeDest, logFile);
   } else {
     // 全新安装
-    appendLog("INFO", "Install started (fresh)");
+    appendLog(logFile, "INFO", "Install started (fresh)");
     fs.cpSync(claudeSource, claudeDest, { recursive: true });
-    appendLog("INFO", `.claude/ directory created`);
+    appendLog(logFile, "INFO", `.claude/ directory created`);
   }
 }
 
 // 安装 CLAUDE.md
-// 用户已有则只备份不覆盖，防止冲掉自定义配置
 if (fs.existsSync(mdSource)) {
   if (!fs.existsSync(mdDest)) {
     fs.copyFileSync(mdSource, mdDest);
-    appendLog("INFO", "CLAUDE.md installed");
+    appendLog(logFile, "INFO", "CLAUDE.md installed");
   } else {
-    // 仅备份用户版本到 .claude/backups/，方便查阅
     const backupsDir = path.join(claudeDest, "backups");
     if (!fs.existsSync(backupsDir)) {
       fs.mkdirSync(backupsDir, { recursive: true });
@@ -262,14 +59,13 @@ if (fs.existsSync(mdSource)) {
     const bakName = `CLAUDE.md.${backupTimestamp()}`;
     const bakPath = path.join(backupsDir, bakName);
     fs.copyFileSync(mdDest, bakPath);
-    appendLog("BACKUP", `backups/${bakName} (CLAUDE.md user version preserved)`);
+    appendLog(logFile, "BACKUP", `backups/${bakName} (CLAUDE.md user version preserved)`);
   }
 }
 
 // 输出摘要
 console.log("✅ dk-frontend-skills 安装完成！\n");
 
-// 读取日志输出最后几行
 if (fs.existsSync(logFile)) {
   const logs = fs.readFileSync(logFile, "utf-8").trim().split("\n");
   const recent = logs.slice(-10);
@@ -280,6 +76,4 @@ if (fs.existsSync(logFile)) {
   console.log("");
 }
 
-// 卸载提醒
-console.log("💡 dk-frontend-skills 安装包仍留在 node_modules 中");
-console.log("   如需移除，可手动执行: npm uninstall dk-frontend-skills\n");
+console.log("💡 提示：运行 npx dk-skills 可交互选择启用/禁用技能\n");

package/scripts/core.js

@@ -0,0 +1,239 @@
+const fs = require("fs");
+const path = require("path");
+
+// 时间戳格式：YYYY-MM-DD HH:mm:ss
+function timestamp() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+// 紧凑时间戳用于备份目录名：YYYYMMDD.HHmmss
+function backupTimestamp() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}.${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+
+/**
+ * 追加日志到 .claude/.install.log
+ * 需要传入 logFile 路径
+ */
+function appendLog(logFile, level, message) {
+  const dir = path.dirname(logFile);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const line = `[${timestamp()}] [${level}] ${message}\n`;
+  fs.appendFileSync(logFile, line, "utf-8");
+}
+
+/**
+ * 备份已有目录到 dir/backups/<timestamp>/
+ * 排除 backups/ 自身，清理超过 3 份的旧备份
+ */
+function backupDir(dir) {
+  if (!fs.existsSync(dir)) return null;
+
+  const backupsDir = path.join(dir, "backups");
+  if (!fs.existsSync(backupsDir)) {
+    fs.mkdirSync(backupsDir, { recursive: true });
+  }
+
+  const ts = backupTimestamp();
+  const bakPath = path.join(backupsDir, ts);
+  fs.mkdirSync(bakPath, { recursive: true });
+
+  for (const item of fs.readdirSync(dir)) {
+    if (item === "backups") continue;
+    fs.cpSync(path.join(dir, item), path.join(bakPath, item), { recursive: true });
+  }
+
+  // 清理旧备份，只保留最近 3 份
+  const backups = fs
+    .readdirSync(backupsDir)
+    .filter((name) => /^\d{8}\.\d{6}$/.test(name))
+    .sort()
+    .reverse();
+
+  if (backups.length > 3) {
+    for (const old of backups.slice(3)) {
+      const oldPath = path.join(backupsDir, old);
+      fs.rmSync(oldPath, { recursive: true, force: true });
+    }
+  }
+
+  return bakPath;
+}
+
+function isPlainObject(val) {
+  return Object.prototype.toString.call(val) === "[object Object]";
+}
+
+/**
+ * 递归深合并，用户值优先，目标新增字段补充
+ */
+function deepMerge(userObj, pkgObj) {
+  const result = { ...userObj };
+
+  for (const key of Object.keys(pkgObj)) {
+    if (!(key in result)) {
+      result[key] = pkgObj[key];
+    } else if (isPlainObject(pkgObj[key]) && isPlainObject(result[key])) {
+      result[key] = deepMerge(result[key], pkgObj[key]);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 读取技能目录下的 .meta.json，没有则返回 null
+ */
+function readMeta(skillDir) {
+  const metaPath = path.join(skillDir, ".meta.json");
+  if (fs.existsSync(metaPath)) {
+    try {
+      return JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * 安装技能：逐个复制，补缺不覆盖
+ */
+function installSkills(skillsSource, skillsDest, logFile) {
+  if (!fs.existsSync(skillsSource)) return [];
+
+  if (!fs.existsSync(skillsDest)) {
+    fs.mkdirSync(skillsDest, { recursive: true });
+  }
+
+  const skillDirs = fs.readdirSync(skillsSource);
+  const results = [];
+
+  for (const dir of skillDirs) {
+    const srcSkill = path.join(skillsSource, dir);
+    const destSkill = path.join(skillsDest, dir);
+    const meta = readMeta(srcSkill);
+    const version = meta ? meta.version : "?";
+
+    if (!fs.existsSync(destSkill)) {
+      fs.cpSync(srcSkill, destSkill, { recursive: true });
+      appendLog(logFile, "SKILL", `${dir} (${version}) → installed`);
+      results.push({ name: dir, version, action: "installed" });
+    } else {
+      const destMeta = readMeta(destSkill);
+      const needUpdate = meta && destMeta && meta.version !== destMeta.version;
+
+      if (needUpdate) {
+        const bakName = `${dir}.bak.${backupTimestamp()}`;
+        const bakPath = path.join(skillsDest, bakName);
+        fs.cpSync(destSkill, bakPath, { recursive: true });
+        fs.rmSync(destSkill, { recursive: true, force: true });
+        fs.cpSync(srcSkill, destSkill, { recursive: true });
+        appendLog(logFile, "SKILL", `${dir} (${destMeta.version} → ${meta.version}) → updated`);
+        results.push({ name: dir, version: meta.version, action: "updated" });
+      } else {
+        appendLog(logFile, "SKILL", `${dir} (${version}) → skipped (exists)`);
+        results.push({ name: dir, version, action: "skipped" });
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * 安装 settings.json，深度合并
+ */
+function installSettings(sourceDir, destDir, logFile) {
+  const settingsSource = path.join(sourceDir, "settings.json");
+  const settingsDest = path.join(destDir, "settings.json");
+  const localSource = path.join(sourceDir, "settings.local.json");
+  const localDest = path.join(destDir, "settings.local.json");
+
+  for (const { src, dest, name } of [
+    { src: settingsSource, dest: settingsDest, name: "settings.json" },
+    { src: localSource, dest: localDest, name: "settings.local.json" },
+  ]) {
+    if (!fs.existsSync(src)) continue;
+
+    if (fs.existsSync(dest)) {
+      const userData = JSON.parse(fs.readFileSync(dest, "utf-8"));
+      const pkgData = JSON.parse(fs.readFileSync(src, "utf-8"));
+      const merged = deepMerge(userData, pkgData);
+      fs.writeFileSync(dest, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+      appendLog(logFile, "SETTINGS", `${name} merged`);
+    } else {
+      fs.copyFileSync(src, dest);
+      appendLog(logFile, "SETTINGS", `${name} created`);
+    }
+  }
+}
+
+/**
+ * 获取包内的技能列表（带元信息）
+ */
+function getPackageSkills(packageDir) {
+  const skillsSource = path.join(packageDir, ".claude", "skills");
+  if (!fs.existsSync(skillsSource)) return [];
+
+  return fs.readdirSync(skillsSource).map((name) => {
+    const meta = readMeta(path.join(skillsSource, name));
+    return {
+      name,
+      version: meta ? meta.version : "?",
+      description: meta ? meta.description : "",
+      tags: meta ? meta.tags : [],
+    };
+  });
+}
+
+/**
+ * 获取用户已安装的技能及其 settings 中的 enabled 状态
+ */
+function getUserSkills(claudeDest) {
+  const skillsDest = path.join(claudeDest, "skills");
+  if (!fs.existsSync(skillsDest)) return [];
+
+  const settingsPath = path.join(claudeDest, "settings.json");
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+    } catch {
+      settings = {};
+    }
+  }
+
+  const skillConfigs = settings.skills || {};
+
+  return fs.readdirSync(skillsDest).map((name) => {
+    const meta = readMeta(path.join(skillsDest, name));
+    const config = skillConfigs[name] || {};
+    return {
+      name,
+      version: meta ? meta.version : "?",
+      description: meta ? meta.description : config.description || "",
+      tags: meta ? meta.tags : [],
+      enabled: config.enabled !== false,
+    };
+  });
+}
+
+module.exports = {
+  timestamp,
+  backupTimestamp,
+  appendLog,
+  backupDir,
+  deepMerge,
+  readMeta,
+  installSkills,
+  installSettings,
+  getPackageSkills,
+  getUserSkills,
+};