ethan-skill 1.15.0 → 1.15.1

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.15.0] - 2026-04-12
+
+### Added
+
+- **`ethan upgrade` 显式升级命令**（新增 CLI）：
+  - 前台执行，有实时输出（`stdio: 'inherit'`）
+  - 支持 `--force` 选项跳过版本比较强制重装
+  - 成功：清除缓存并提示重启终端；失败：显示明确错误与手动命令
+  - 不再依赖静默后台升级的黑盒机制
+
+- **新 MCP 工具 `ethan_upgrade`**（30 → **31**）：
+  - 通过 Claude Desktop 查询当前版本状态、npm 最新版本与升级缓存信息
+  - 输出升级指引（终端命令），MCP 环境下无法直接执行 npm，提供可操作指令
+
+- **自动升级启动 banner**（`printUpdateBanner`）：
+  - 检测到新版本时，在命令输出前打印一行可见提示：
+    ```
+    📦  ethan v{latest} 可用（当前 v{current}）— 运行 ethan upgrade 立即更新
+    ```
+  - 使用缓存（24h 内）时同步输出，不增加延迟
+
+- **`ethan doctor` 版本更新状态节**：
+  - 显示当前版本、npm 最新版、上次检查时间
+  - 有新版本时提示 `ethan upgrade`，已最新时显示 ✅
+
+### Fixed
+
+- **自动升级永不重试 Bug**：
+  - 根因：`upgradedVersion` 在 spawn 成功（不等于 npm install 成功）后立即写入缓存，若后台 npm 进程静默失败，下次检查时 `upgradedVersion === latest` 导致永久跳过
+  - 修复：增加条件 `&& !compareVersions(currentVersion, latest)`，若当前版本仍低于 latest（说明升级失败），则重新触发
+
+- **后台升级失败完全静默**：
+  - spawn 失败（npm 不在 PATH）：原先 `catch` 静默返回；修复后在进程退出时打印 `⚠️ 找不到 npm` 提示
+  - spawn 成功但子进程立即报错（如 EACCES 权限）：新增 `child.on('error', ...)` 监听并打印提示
+
+- **Windows 下 npm 查找失败**：
+  - detached spawn 在 Windows 未启用 shell 模式，部分 nvm-windows 环境下 npm 无法找到
+  - 修复：Windows 平台启用 `shell: true`
+
+### Changed
+
+- 自动升级退出消息措辞调整：
+  - 旧：`🔄 Ethan 正在后台自动升级到 v{latest}，重启终端后生效。`
+  - 新：`🔄 Ethan 正在后台升级到 v{latest}，完成后重启终端生效。`
+
+---
+
 ## [1.14.0] - 2026-04-09
 
 ### Added

package/README.md

@@ -17,10 +17,10 @@
 | **36 个 Skill** | 标准化工作流节点，覆盖需求→接口设计→安全→部署→PRD→Git→测试→系统设计→数据库→Docker→CI/CD→性能→重构→可观测性→设计模式→OpenSpec→技术债→Mock→数据迁移→LLM设计→威胁建模→绿色编码→服务目录→移动审查→数据管道→ML实验 |
 | **11 个平台** | Cursor / Copilot / Cline / Windsurf / Zed / JetBrains / Continue / Claude Code 等 |
 | **10 个 Pipeline** | 链式工作流（开发 / 汇报 / 质量 / 完整周期 / 故障响应 / 新功能 / Spec规范 / Bug修复 / 安全审计 / 开源发布），有状态持久化推进 |
-| **28 个 MCP 工具** | AI 编辑器原生调用 Skill、Pipeline、Git、记忆库、估算、DORA 指标、PR 分析、故障复盘、脚手架、合规证据 |
+| **31 个 MCP 工具** | AI 编辑器原生调用 Skill、Pipeline、Git、记忆库、估算、DORA 指标、PR 分析、故障复盘、脚手架、合规证据、版本升级检查 |
 | **60+ CLI 命令** | Git 集成、开发工具、记忆库、估算、分析工具（diff/deps/dora/mermaid/adr/i18n/migrate/onboard/compliance 等）、插件 OS 全覆盖 |
 | **Slash 命令生成** | `ethan slash` 一键为 Claude Code 生成 `/ethan-xxx` 原生命令，其他平台生成速查表 |
-| **自动升级** | 检测到新版本时自动后台 `npm install -g` 静默升级，重启终端即用新版 |
+| **自动升级** | 启动时显示新版本 banner，自动后台 `npm install -g` 升级；失败时显示明确提示；支持 `ethan upgrade [--force]` 手动显式升级 |
 | **自定义 Skill** | `.ethan/skills/*.yaml/.md`，YAML frontmatter + Markdown body |
 | **自定义 Pipeline** | `.ethan/pipelines/*.yaml`，引用内置或自定义 Skill 自由组合 |
 | **浏览器扩展** | Chrome/Edge MV3，GitHub PR 一键 Review + 右键菜单 |
@@ -122,7 +122,7 @@ npx ethan-skill install --platform cursor --lang en
 }
 ```
 
-重启 AI 编辑器后，可使用全部 **28 个 MCP 工具**（详见下方 MCP 工具列表）。
+重启 AI 编辑器后，可使用全部 **31 个 MCP 工具**（详见下方 MCP 工具列表）。
 
 ### 方式三：全局安装
 
@@ -347,17 +347,38 @@ ethan slash
 
 ## 自动升级
 
-Ethan 每次启动都会静默检查 npm 最新版本（24h 缓存，不阻塞 CLI）。检测到新版本后，**自动在后台执行 `npm install -g ethan-skill@latest`**，退出时显示：
+Ethan 每次启动都会静默检查 npm 最新版本（24h 缓存，不阻塞 CLI）。检测到新版本后：
 
+1. **命令执行前**显示 banner 提醒：
+   ```
+   📦  ethan v{latest} 可用（当前 v{current}）— 运行 ethan upgrade 立即更新
+   ```
+
+2. **自动在后台**执行 `npm install -g ethan-skill@latest`，退出时显示：
+   ```
+   🔄  Ethan 正在后台升级到 v{latest}，完成后重启终端生效。
+   ```
+
+3. **失败时给出明确提示**（权限不足、npm 找不到等），不再静默忽略
+
+4. **智能重试**：若后台升级静默失败，下次启动自动重试（不会被缓存永久阻断）
+
+### 手动显式升级
+
+```bash
+ethan upgrade           # 查询最新版本并升级（有实时输出）
+ethan upgrade --force   # 跳过版本比较，强制重新安装
 ```
-🔄  Ethan 正在后台自动升级到 v{latest}，重启终端后生效。
-```
 
-无需手动运行升级命令，始终保持最新版本。
+### MCP 版本查询（Claude Desktop 用户）
+
+```
+调用 ethan_upgrade 工具查看当前版本状态与升级建议
+```
 
 ---
 
-## 28 个 MCP 工具
+## 31 个 MCP 工具
 
 配置 MCP Server 后，AI 编辑器（Cursor / Cline / Continue 等）可直接调用：
 
@@ -394,6 +415,7 @@ Ethan 每次启动都会静默检查 npm 最新版本（24h 缓存，不阻塞 C
 | `ethan_postmortem` | 生成故障复盘提示词（v1.12.0 新增）|
 | `ethan_scaffold` | 黄金路径脚手架提示词（v1.12.0 新增）|
 | `ethan_compliance` | 生成合规证据收集清单（soc2/gdpr/iso27001，v1.12.0 新增）|
+| `ethan_upgrade` | 检查版本状态，输出当前版本/最新版本/升级指引（v1.15.0 新增）|
 
 ---
 
@@ -552,6 +574,7 @@ npm run test:coverage    # 覆盖率报告
 
 | 版本 | 主要变更 |
 |------|---------|
+| **v1.15.0** | 自动升级全面增强：启动 banner 提醒、智能重试（失败后不永久阻断）、错误明确提示；新增 `ethan upgrade [--force]` 显式升级命令；新增 MCP 工具 `ethan_upgrade`；`ethan doctor` 新增版本更新状态节；MCP 工具 30 → 31 |
 | **v1.14.0** | 新增 3 个专业化 Agent（qa/security/data），内置 Agent 5 → 8；新增 4 种协作模式（`--mode sequential/parallel/review-loop/consensus`）；新增 `ethan agent new` 交互式创建自定义 Agent；新增 MCP 工具 `ethan_agent_list/show`，MCP 工具 28 → 30 |
 | **v1.13.0** | Multi-Agent 编排系统（`src/agents/`）；5 个内置角色 Agent（architect/coder/reviewer/devops/pm）；新增 `ethan agent list/show/run` CLI；新增 MCP 工具 `ethan_agent_orchestrate`；MCP 工具 27 → 28；新增宣传落地页 `docs/landing.html` |
 | **v1.12.0** | 新增 10 个 Skill（技术债/Mock服务/数据迁移/LLM设计/威胁建模/绿色编码/服务目录/移动审查/数据管道/ML实验）；Skills 26 → 36；新增 3 条 Pipeline（bugfix/security-audit/open-source-release）；新增 19 个分析 CLI 命令（diff/deps/dora/adr/mermaid/i18n/onboard/migrate/postmortem/decision-log/knowledge/oss/prompt-lib/scaffold/benchmark/sync/compliance 等）；MCP 工具 22 → 27 |

package/dist/cli/index.js

@@ -628,11 +628,11 @@ program
     const platformDirMap = {
         'claude-code': path.join(dir, '.claude/commands'),
         codebuddy: path.join(dir, '.codebuddy/commands'),
-        cursor: path.join(dir, '.cursor/rules'),
+        cursor: path.join(dir, '.cursor/commands'), // v0.50+ 支持独立命令文件
+        cline: path.join(dir, '.cline/commands'), // 支持独立命令文件
+        windsurf: path.join(dir, '.windsurf/commands'), // Wave 6+ 支持独立命令文件
         copilot: path.join(dir, '.github'),
-        cline: dir,
-        windsurf: path.join(dir, '.windsurf/rules'),
-        zed: dir,
+        zed: path.join(dir, '.zed/prompts'), // /prompt 机制，独立 .md 文件
         jetbrains: path.join(dir, '.github'),
         continue: dir,
         lingma: path.join(dir, '.lingma/rules'),
@@ -642,9 +642,11 @@ program
         const outDir = platformDirMap[p];
         if (!fs.existsSync(outDir))
             fs.mkdirSync(outDir, { recursive: true });
-        if (p === 'claude-code' || p === 'codebuddy') {
+        // 支持独立命令文件的平台：claude-code / codebuddy / cursor / cline / windsurf
+        const INDIVIDUAL_FILE_PLATFORMS = ['claude-code', 'codebuddy', 'cursor', 'cline', 'windsurf'];
+        if (INDIVIDUAL_FILE_PLATFORMS.includes(p)) {
             const isClaudeCode = p === 'claude-code';
-            const cmdDir = isClaudeCode ? '.claude/commands' : '.codebuddy/commands';
+            const cmdDir = path.relative(dir, outDir); // 用于日志展示
             // ── 每个 Skill 生成独立 .md slash 命令文件 ──────────────────────────────
             for (const skill of skills) {
                 const stepsText = skill.steps
@@ -752,7 +754,7 @@ program
                 console.log(`  ✅  claude-code  →  工作流: ${cmdDir}/ethan-{cmd}.md × ${WORKFLOW_SLASH_COMMANDS.length}`);
                 console.log(`       使用方式：在 Claude Code 聊天中输入 /ethan-commit、/ethan-auto 等`);
                 console.log(`       ⚡ 动态注入：提示词自动注入对话，无需复制粘贴`);
-                // ── Agent 命令（Claude Code 专属：每个 Agent 一个 .md 文件）─────────────
+                // ── Agent 命令（Claude Code：每个 Agent 一个动态 .md 文件）─────────────
                 const { getActiveAgents } = await Promise.resolve().then(() => __importStar(require('../agents/index')));
                 const agents = getActiveAgents(dir);
                 // ethan-agent-list.md
@@ -767,7 +769,7 @@ program
                 const agentNewContent = `---\ndescription: "Ethan — 创建自定义 Agent，生成 .ethan/agents/<id>.yaml"\n---\n\n` +
                     `$(ethan agent new $ARGUMENTS 2>/dev/null)\n`;
                 fs.writeFileSync(path.join(outDir, 'ethan-agent-new.md'), agentNewContent, 'utf-8');
-                // 每个内置 Agent 生成独立快捷命令
+                // 每个内置 Agent 生成独立快捷命令（动态）
                 let agentFileCount = 3;
                 for (const agent of agents) {
                     const agentSkillList = agent.skillIds.slice(0, 8).join('、') + (agent.skillIds.length > 8 ? '...' : '');
@@ -780,7 +782,7 @@ program
                 console.log(`  ✅  claude-code  →  Agents: ${cmdDir}/ethan-agent-*.md × ${agentFileCount}（含 ${agents.length} 个 Agent 快捷键）`);
             }
             else {
-                // CodeBuddy：静态提示词（各 /ethan-xxx 命令文件）
+                // codebuddy / cursor / cline / windsurf：静态提示词（各 /ethan-xxx 命令文件）
                 for (const cmd of WORKFLOW_SLASH_COMMANDS) {
                     const content = `---\n` +
                         `description: "Ethan — ${cmd.name}：${cmd.description}"\n` +
@@ -789,8 +791,45 @@ program
                     fs.writeFileSync(path.join(outDir, `ethan-${cmd.id}.md`), content, 'utf-8');
                     total++;
                 }
-                console.log(`  ✅  codebuddy    →  工作流: ${cmdDir}/ethan-{cmd}.md × ${WORKFLOW_SLASH_COMMANDS.length}`);
-                console.log(`       使用方式：在 CodeBuddy 聊天中输入 /ethan-commit、/ethan-auto 等`);
+                console.log(`  ✅  ${p.padEnd(12)} →  工作流: ${cmdDir}/ethan-{cmd}.md × ${WORKFLOW_SLASH_COMMANDS.length}`);
+                console.log(`       使用方式：在 ${p} 聊天中输入 /ethan-commit、/ethan-auto 等`);
+                // ── Agent 命令（静态提示词，适用于 codebuddy/cursor/cline/windsurf）──────
+                const { getActiveAgents: getAgentsStatic } = await Promise.resolve().then(() => __importStar(require('../agents/index')));
+                const agentsStatic = getAgentsStatic(dir);
+                // ethan-agent-list.md（静态）
+                const agentListRows = agentsStatic
+                    .map((a) => `| /ethan-agent-${a.id} | ${a.emoji} ${a.name} | ${a.role} |`)
+                    .join('\n');
+                fs.writeFileSync(path.join(outDir, 'ethan-agent-list.md'), `---\ndescription: "Ethan — 查看所有可用 Agent 及其 Skill 分配"\n---\n\n` +
+                    `# Ethan Agent 列表\n\n` +
+                    `| 命令 | Agent | 职责 |\n|------|-------|------|\n${agentListRows}\n\n` +
+                    `运行：\`ethan agent list\`\n`, 'utf-8');
+                // ethan-agent-run.md（静态）
+                fs.writeFileSync(path.join(outDir, 'ethan-agent-run.md'), `---\ndescription: "Ethan — Multi-Agent 编排：将任务分配给多个专业 Agent 协作执行"\n---\n\n` +
+                    `# Ethan Multi-Agent 编排\n\n` +
+                    `用法：\`ethan agent run <pipeline> -c "任务描述"\`\n\n` +
+                    `示例：\`ethan agent run dev-workflow -c "实现用户登录功能"\`\n\n` +
+                    `可用模式：sequential / parallel / review-loop / consensus\n`, 'utf-8');
+                // ethan-agent-new.md（静态）
+                fs.writeFileSync(path.join(outDir, 'ethan-agent-new.md'), `---\ndescription: "Ethan — 创建自定义 Agent，生成 .ethan/agents/<id>.yaml"\n---\n\n` +
+                    `# 创建自定义 Agent\n\n` +
+                    `运行：\`ethan agent new\`\n\n` +
+                    `将在 \`.ethan/agents/\` 目录下生成 Agent 配置文件。\n`, 'utf-8');
+                // 每个内置 Agent 生成独立静态命令文件
+                let staticAgentFileCount = 3;
+                for (const agent of agentsStatic) {
+                    const agentSkillList = agent.skillIds.slice(0, 8).join('、') + (agent.skillIds.length > 8 ? '...' : '');
+                    const agentContent = `---\ndescription: "Ethan — ${agent.emoji} ${agent.name}：${agent.role}"\n---\n\n` +
+                        `# ${agent.emoji} ${agent.name}\n\n` +
+                        `**职责**: ${agent.role}\n\n` +
+                        `**负责 Skill**: ${agentSkillList}\n\n` +
+                        `**运行方式**：\`ethan agent run --no-copy -c "<任务描述>"\`\n\n` +
+                        `**示例**：\`ethan agent run --no-copy -c "对当前代码进行安全审查"\`\n`;
+                    fs.writeFileSync(path.join(outDir, `ethan-agent-${agent.id}.md`), agentContent, 'utf-8');
+                    staticAgentFileCount++;
+                    total++;
+                }
+                console.log(`  ✅  ${p.padEnd(12)} →  Agents: ${cmdDir}/ethan-agent-*.md × ${staticAgentFileCount}（含 ${agentsStatic.length} 个 Agent 快捷键）`);
             }
         }
         else {
@@ -861,7 +900,8 @@ program
             total++;
         }
     }
-    const totalFiles = (platform === 'claude-code' || platform === 'codebuddy')
+    const INDIVIDUAL_FILE_PLATFORMS_CHECK = ['claude-code', 'codebuddy', 'cursor', 'cline', 'windsurf'];
+    const totalFiles = INDIVIDUAL_FILE_PLATFORMS_CHECK.includes(platform)
         ? skills.length + WORKFLOW_SLASH_COMMANDS.length
         : total;
     console.log(`\n共生成 ${totalFiles} 个 Slash 命令文件（目录：${dir}）`);
@@ -1295,6 +1335,15 @@ pipelineCmd
     }
     writeStats(stats);
 });
+// ─── upgrade 命令 ───────────────────────────────────────────────────────────
+program
+    .command('upgrade')
+    .description('检查并升级到最新版本')
+    .option('--force', '跳过版本检查，强制重新安装最新版本')
+    .action(async (options) => {
+    const { checkAndPrintUpdate } = await Promise.resolve().then(() => __importStar(require('./update-check')));
+    await checkAndPrintUpdate(pkg.version, pkg.name, options.force ?? false);
+});
 // ─── doctor 命令 ────────────────────────────────────────────────────────────
 program
     .command('doctor')
@@ -1373,6 +1422,40 @@ program
     }
     console.log('\n' + '─'.repeat(60));
     const allBuilt = ruleFiles.every(({ file }) => fs.existsSync(path.join(ROOT, file)));
+    // 版本更新状态检查
+    console.log(`\n[版本更新状态]`);
+    console.log(`  当前版本  : v${pkg.version}`);
+    const updateCachePath = path.join(os.homedir(), '.ethan-update-cache.json');
+    if (fs.existsSync(updateCachePath)) {
+        try {
+            const updateCache = JSON.parse(fs.readFileSync(updateCachePath, 'utf-8'));
+            const lastCheckedAgo = Math.round((Date.now() - updateCache.lastChecked) / 1000 / 60);
+            console.log(`  npm 最新版 : v${updateCache.latestVersion}`);
+            console.log(`  上次检查  : ${lastCheckedAgo} 分钟前`);
+            const needsUpdate = (() => {
+                const parse = (v) => v.replace(/^v/, '').split('.').map(Number);
+                const [cMaj, cMin, cPat] = parse(pkg.version);
+                const [lMaj, lMin, lPat] = parse(updateCache.latestVersion);
+                if (lMaj !== cMaj)
+                    return lMaj > cMaj;
+                if (lMin !== cMin)
+                    return lMin > cMin;
+                return lPat > cPat;
+            })();
+            if (needsUpdate) {
+                console.log(`  升级状态  : ⚠️  有新版本可用，运行 ethan upgrade 升级`);
+            }
+            else {
+                console.log(`  升级状态  : ✅ 已是最新`);
+            }
+        }
+        catch {
+            console.log(`  升级状态  : ⚠️  缓存文件损坏，将在下次运行时重建`);
+        }
+    }
+    else {
+        console.log(`  升级状态  : ⏳ 尚未检查（下次运行 ethan 命令时自动检查）`);
+    }
     if (!allBuilt) {
         console.log('\n💡 提示：运行 npm run build:rules 生成规则文件\n');
     }