@catcuts-skills/handover 1.0.1 → 1.0.4

package/README.md

@@ -48,15 +48,44 @@ npm test
 
 ### 卸载
 
+**重要**：由于 npm 的限制，全局卸载时 preuninstall hook 可能不会执行。请按照以下步骤正确卸载：
+
+#### 方式 1：使用 npm scripts（推荐）
+
 ```bash
 # 全局卸载
+npm run uninstall:global
 npm uninstall -g @catcuts-skills/handover
 
 # 项目级卸载
+npm run uninstall:local
 npm uninstall @catcuts-skills/handover
 ```
 
-卸载时会自动清理 skill 文件。
+#### 方式 2：手动清理（如果方式 1 失败）
+
+```bash
+# 1. 清理技能文件
+rm -rf ~/.claude/skills/handover
+rm -rf ~/.agents/skills/handover
+
+# 2. 卸载 npm 包
+npm uninstall -g @catcuts-skills/handover
+```
+
+**Windows PowerShell**:
+```powershell
+# 1. 清理技能文件
+Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\skills\handover"
+Remove-Item -Recurse -Force "$env:USERPROFILE\.agents\skills\handover"
+
+# 2. 卸载 npm 包
+npm uninstall -g @catcuts-skills/handover
+```
+
+#### 为什么需要两步？
+
+npm 的 `preuninstall` hook 在全局卸载时**不保证被执行**，这是 npm 的已知限制。因此需要先手动清理技能文件，再卸载 npm 包。
 
 ## 使用
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@catcuts-skills/handover",
-    "version": "1.0.1",
+    "version": "1.0.4",
     "description": "跨会话工作交接工具。支持归档当前进度和恢复历史进度两个模式。",
     "main": "index.js",
     "scripts": {
@@ -16,7 +16,7 @@
         "scripts/"
     ],
     "optionalDependencies": {
-        "add-skill": "^1.0.29"
+        "skills": "^1.1.2"
     },
     "keywords": [
         "claude-code",
@@ -35,7 +35,7 @@
     "bugs": {
         "url": "https://github.com/catcuts/agent-skills/issues"
     },
-    "homepage": "https://github.com/catcuts/agent-skills#readme",
+    "homepage": "https://github.com/catcuts/agent-skills/tree/main/skills/handover#readme",
     "engines": {
         "node": ">=18.0.0"
     }

package/scripts/install-skill.js

@@ -2,7 +2,7 @@
 
 /**
  * Handover Skill 安装脚本
- * 使用 add-skill 将 skill 安装到 Claude Code
+ * 使用 skills 将 skill 安装到 Claude Code
  *
  * 命令行参数 (推荐):
  * --dry-run: 测试模式,只显示将要执行的命令,不实际安装
@@ -16,10 +16,30 @@
 const { execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
+const os = require('os');
+const { printUsageGuide } = require('./usage-guide');
 
 // 获取包根目录
 const packageRoot = path.resolve(__dirname, '..');
 
+// 获取用户主目录
+const homeDir = os.homedir();
+
+// 技能名称
+const skillName = 'handover';
+
+// 需要清理的路径列表
+const pathsToClean = {
+    // skills CLI 的规范副本目录（这是问题的根源）
+    canonical: path.join(homeDir, '.agents', 'skills', skillName),
+
+    // Claude Code 全局技能目录（符号链接）
+    claudeGlobal: path.join(homeDir, '.claude', 'skills', skillName),
+
+    // Claude Code 项目级技能目录（如果存在）
+    claudeLocal: path.join(process.cwd(), '.claude', 'skills', skillName),
+};
+
 // 解析命令行参数
 const args = process.argv.slice(2);
 const dryRun = args.includes('--dry-run');
@@ -51,11 +71,111 @@ function log(message, type = 'info') {
     console.log(`${prefix} ${message}`);
 }
 
+// 检查路径是否为符号链接
+function isSymlink(filePath) {
+    try {
+        return fs.lstatSync(filePath).isSymbolicLink();
+    } catch (e) {
+        return false;
+    }
+}
+
+// 安全删除路径（支持符号链接、文件、目录）
+function safeRemovePath(filePath, description) {
+    try {
+        if (!fs.existsSync(filePath)) {
+            return { success: true, removed: false, message: `不存在：${description}(${filePath})` };
+        }
+
+        const stats = fs.lstatSync(filePath);
+        const isLink = stats.isSymbolicLink();
+        const isDir = stats.isDirectory();
+
+        if (isLink) {
+            fs.unlinkSync(filePath);
+            return {
+                success: true,
+                removed: true,
+                message: `已删除符号链接: ${description}(${filePath})`
+            };
+        } else if (isDir) {
+            fs.rmSync(filePath, { recursive: true, force: true });
+            return {
+                success: true,
+                removed: true,
+                message: `已删除目录: ${description}(${filePath})`
+            };
+        } else {
+            fs.unlinkSync(filePath);
+            return {
+                success: true,
+                removed: true,
+                message: `已删除文件: ${description}(${filePath})`
+            };
+        }
+    } catch (error) {
+        return {
+            success: false,
+            removed: false,
+            message: `删除失败: ${description}(${filePath}) - ${error.message}`
+        };
+    }
+}
+
+// 清理旧的安装文件
+function cleanOldInstallations() {
+    log('\n正在清理旧的安装文件...', 'info');
+
+    const results = [];
+
+    // 1. 清理规范副本目录（.agents/skills/handover）
+    const canonicalResult = safeRemovePath(
+        pathsToClean.canonical,
+        '规范副本'
+    );
+    results.push({ path: pathsToClean.canonical, ...canonicalResult });
+
+    // 2. 清理 Claude Code 全局符号链接
+    const globalResult = safeRemovePath(
+        pathsToClean.claudeGlobal,
+        '全局技能链接'
+    );
+    results.push({ path: pathsToClean.claudeGlobal, ...globalResult });
+
+    // 3. 清理 Claude Code 项目级安装（如果存在）
+    const localResult = safeRemovePath(
+        pathsToClean.claudeLocal,
+        '项目级技能'
+    );
+    results.push({ path: pathsToClean.claudeLocal, ...localResult });
+
+    // 输出清理结果
+    let removedCount = 0;
+    results.forEach((result) => {
+        if (result.removed) {
+            log(`  ✓ ${result.message}`, 'success');
+            removedCount++;
+        } else if (result.success) {
+            log(`  ⊗ ${result.message} (跳过)`, 'info');
+        } else {
+            log(`  ✗ ${result.message}`, 'warning');
+        }
+    });
+
+    if (removedCount > 0) {
+        log(`\n已清理 ${removedCount} 个旧安装文件`, 'success');
+    } else {
+        log('未发现需要清理的文件', 'info');
+    }
+
+    return removedCount > 0;
+}
+
 // 错误处理
 function handleError(error) {
     log(`安装失败: ${error.message}`, 'error');
     log('\n您可以尝试手动安装:', 'warning');
-    log(`  npx add-skill "${packageRoot}" -a claude-code ${isGlobal ? '-g' : ''} -y`);
+    log(`  npx skills add "${packageRoot}" ${isGlobal ? '-g' : ''} -y`);
     process.exit(1);
 }
 
@@ -63,12 +183,15 @@ try {
     log(`开始安装 Handover Skill...`, 'info');
     log(`安装范围: ${isGlobal ? '全局(GLOBAL)' : '项目级(LOCAL)'}`, 'info');
 
-    // 构建 add-skill 命令
+    // 清理旧的安装文件（解决增量更新导致的文件残留问题）
+    cleanOldInstallations();
+
+    // 构建 skills 命令
     const commandParts = [
         'npx',
-        'add-skill',
+        'skills',
+        'add',
         `"${packageRoot}"`,
-        // '-a', 'claude-code'  // 由 add-skill 自动检测，如果检测失败那么会自动弹出菜单让用户手动选择
     ];
 
     if (isGlobal) {
@@ -90,7 +213,7 @@ try {
     }
 
     // 执行安装
-    log('\n正在执行 add-skill...', 'info');
+    log('\n正在执行 skills add...', 'info');
     execSync(command, {
         stdio: 'inherit',
         cwd: packageRoot,
@@ -101,6 +224,9 @@ try {
         `Skill 已安装到: ${isGlobal ? '~/.claude/skills/handover' : '.claude/skills/handover'}`,
         'info'
     );
+
+    // 显示使用指南
+    printUsageGuide();
 } catch (error) {
     handleError(error);
 }

package/scripts/uninstall-skill.js

@@ -16,6 +16,9 @@ const path = require('path');
 const fs = require('fs');
 const os = require('os');
 
+// 技能名称
+const skillName = 'handover';
+
 // 解析命令行参数
 const args = process.argv.slice(2);
 const forceGlobal = args.includes('--global');
@@ -46,18 +49,49 @@ function log(message, type = 'info') {
     console.log(`${prefix} ${message}`);
 }
 
-// 递归删除目录
-function removeDirectory(dirPath) {
-    if (!fs.existsSync(dirPath)) {
-        return false;
-    }
-
+// 安全删除路径（支持符号链接、文件、目录）
+function safeRemovePath(filePath, description) {
     try {
-        fs.rmSync(dirPath, { recursive: true, force: true });
-        return true;
+        if (!fs.existsSync(filePath)) {
+            return { success: true, removed: false, message: '不存在' };
+        }
+
+        const stats = fs.lstatSync(filePath);
+        const isLink = stats.isSymbolicLink();
+        const isDir = stats.isDirectory();
+
+        if (isLink) {
+            fs.unlinkSync(filePath);
+            return {
+                success: true,
+                removed: true,
+                message: `已删除符号链接: ${description}`
+            };
+        } else if (isDir) {
+            fs.rmSync(filePath, { recursive: true, force: true });
+            return {
+                success: true,
+                removed: true,
+                message: `已删除目录: ${description}`
+            };
+        } else {
+            fs.unlinkSync(filePath);
+            return {
+                success: true,
+                removed: true,
+                message: `已删除文件: ${description}`
+            };
+        }
     } catch (error) {
-        log(`删除 ${dirPath} 失败: ${error.message}`, 'error');
-        return false;
+        // 忽略"文件不存在"错误，可能已被并发删除
+        if (error.code === 'ENOENT') {
+            return { success: true, removed: false, message: '已不存在' };
+        }
+        return {
+            success: false,
+            removed: false,
+            message: `删除失败: ${error.message}`
+        };
     }
 }
 
@@ -65,42 +99,72 @@ try {
     log(`开始卸载 Handover Skill...`, 'info');
     log(`卸载范围: ${isGlobal ? '全局(GLOBAL)' : '项目级(LOCAL)'}`, 'info');
 
-    let removedCount = 0;
+    log('\n正在清理技能文件...', 'info');
+
+    const results = [];
 
     if (isGlobal) {
         // 全局卸载
         const homeDir = os.homedir();
-        const paths = [
-            path.join(homeDir, '.claude', 'skills', 'handover'),
-            path.join(homeDir, '.agents', 'skills', 'handover'),
-        ];
-
-        paths.forEach((dirPath) => {
-            if (removeDirectory(dirPath)) {
-                log(`已删除: ${dirPath}`, 'success');
-                removedCount++;
-            }
-        });
+
+        // 1. 清理规范副本目录（.agents/skills/handover）
+        const canonicalResult = safeRemovePath(
+            path.join(homeDir, '.agents', 'skills', skillName),
+            '规范副本'
+        );
+        results.push(canonicalResult);
+
+        // 2. 清理 Claude Code 全局符号链接
+        const globalResult = safeRemovePath(
+            path.join(homeDir, '.claude', 'skills', skillName),
+            '全局技能链接'
+        );
+        results.push(globalResult);
     } else {
         // 项目级卸载
         const cwd = process.cwd();
-        const paths = [
-            path.join(cwd, '.claude', 'skills', 'handover'),
-            path.join(cwd, '.agents', 'skills', 'handover'),
-        ];
-
-        paths.forEach((dirPath) => {
-            if (removeDirectory(dirPath)) {
-                log(`已删除: ${dirPath}`, 'success');
-                removedCount++;
-            }
-        });
+
+        // 1. 清理项目级规范副本（如果存在）
+        const canonicalResult = safeRemovePath(
+            path.join(cwd, '.agents', 'skills', skillName),
+            '项目级规范副本'
+        );
+        results.push(canonicalResult);
+
+        // 2. 清理 Claude Code 项目级技能
+        const localResult = safeRemovePath(
+            path.join(cwd, '.claude', 'skills', skillName),
+            '项目级技能'
+        );
+        results.push(localResult);
     }
 
+    // 输出清理结果
+    let removedCount = 0;
+    let errorCount = 0;
+
+    results.forEach((result) => {
+        if (result.removed) {
+            log(`  ✓ ${result.message}`, 'success');
+            removedCount++;
+        } else if (result.success) {
+            log(`  ⊗ ${result.message} (跳过)`, 'info');
+        } else {
+            log(`  ✗ ${result.message}`, 'error');
+            errorCount++;
+        }
+    });
+
+    // 总结
     if (removedCount > 0) {
-        log(`\n卸载成功! 已删除 ${removedCount} 个目录`, 'success');
-    } else {
-        log('\n未找到已安装的 skill 文件', 'warning');
+        log(`\n✓ 卸载成功! 已删除 ${removedCount} 个文件/目录`, 'success');
+    } else if (errorCount === 0) {
+        log('\n⊗ 未找到需要卸载的文件', 'warning');
+    }
+
+    if (errorCount > 0) {
+        log(`\n⚠ 有 ${errorCount} 个项目删除失败，请手动清理`, 'warning');
+        process.exit(1);
     }
 } catch (error) {
     log(`卸载失败: ${error.message}`, 'error');

package/scripts/usage-guide.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+/**
+ * 技能使用指南生成器
+ * 在安装成功后显示友好的使用指南
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * 读取 package.json 中的信息
+ */
+function getPackageInfo() {
+    const packageRoot = path.resolve(__dirname, '..');
+    const packageJsonPath = path.join(packageRoot, 'package.json');
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+
+    return {
+        name: packageJson.name.split('/')[1] || packageJson.name,
+        description: packageJson.description,
+        homepage: packageJson.homepage || '',
+        repository: packageJson.repository?.url || '',
+    };
+}
+
+/**
+ * 读取 SKILL.md 中的触发指令
+ */
+function getSkillInstructions() {
+    const packageRoot = path.resolve(__dirname, '..');
+    const skillMdPath = path.join(packageRoot, 'SKILL.md');
+
+    if (!fs.existsSync(skillMdPath)) {
+        return null;
+    }
+
+    const content = fs.readFileSync(skillMdPath, 'utf-8');
+    // 匹配 description 行中的指令说明
+    const match = content.match(/^description:\s*(.+)$/m);
+    return match ? match[1].trim() : null;
+}
+
+/**
+ * 打印使用指南
+ */
+function printUsageGuide() {
+    const pkg = getPackageInfo();
+    const instructions = getSkillInstructions();
+
+    // 如果 SKILL.md 中有指令说明，使用它；否则使用 package.json 的 description
+    const usageInfo = instructions || pkg.description;
+
+    const guide = `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  🎉 技能安装成功！
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📦 技能名称:    ${pkg.name}
+📝 功能描述:    ${pkg.description}
+
+🚀 如何使用:
+   ${usageInfo}
+
+📖 更多信息:
+   ${pkg.homepage ? `   文档: ${pkg.homepage}` : ''}
+   ${pkg.repository ? `   仓库: ${pkg.repository}` : ''}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+
+    console.log(guide);
+}
+
+module.exports = { printUsageGuide };