ethan-skill 1.10.5 → 1.11.0

package/dist/cli/index.js

@@ -372,7 +372,7 @@ const WORKFLOW_SLASH_COMMANDS = [
         description: '启动指定 Pipeline 的有状态工作流会话',
         prompt: `# Ethan — 启动工作流\n\n` +
             `我需要启动一个 Ethan 有状态工作流会话。请告诉我：\n\n` +
-            `1. 选择 Pipeline：dev-workflow | reporting | quality-workflow | full-dev-cycle | incident-response | new-feature\n` +
+            `1. 选择 Pipeline：dev-workflow | reporting | quality-workflow | full-dev-cycle | incident-response | new-feature | spec-workflow\n` +
             `2. 描述任务上下文（如"实现用户登录功能"）\n\n` +
             `启动后，逐步执行每个 Skill 步骤，完成后用 \`ethan workflow done\` 推进。\n\n` +
             `CLI 用法：\`ethan workflow start <pipeline> -c "任务描述"\``,
@@ -465,6 +465,54 @@ const WORKFLOW_SLASH_COMMANDS = [
             `同时给出 T-shirt Size（XS/S/M/L/XL）和主要风险点。\n\n` +
             `CLI 用法：\`ethan estimate --style hours|story-points|days\``,
     },
+    // ── OpenSpec 集成 ────────────────────────────────────────────
+    {
+        id: 'spec-proposal',
+        name: 'Spec 变更提案',
+        category: 'OpenSpec',
+        description: '在编码前生成完整 OpenSpec 变更提案包（proposal + design + tasks + spec delta）',
+        prompt: `# Ethan — Spec Proposal\n\n` +
+            `请基于 OpenSpec 规范，为本次变更生成完整提案包。在开始编码之前，先对齐需求意图和实现范围。\n\n` +
+            `**请提供**：\n` +
+            `1. 变更描述（做什么、为什么）\n` +
+            `2. 涉及的功能模块（capability）\n\n` +
+            `**将生成文件**：\n` +
+            `- \`openspec/changes/[id]/proposal.md\`（变更提案）\n` +
+            `- \`openspec/changes/[id]/design.md\`（技术方案）\n` +
+            `- \`openspec/changes/[id]/tasks.md\`（分阶段任务）\n` +
+            `- \`openspec/changes/[id]/specs/[capability].md\`（spec delta）\n\n` +
+            `原则：**Review intent, not just code**\n\n` +
+            `CLI 用法：\`ethan spec proposal <capability> -c "变更描述"\``,
+    },
+    {
+        id: 'spec-review',
+        name: 'Spec 意图审查',
+        category: 'OpenSpec',
+        description: '对比 spec delta 与代码实现，执行意图级 Review，输出对齐矩阵和偏差报告',
+        prompt: `# Ethan — Spec Review（意图审查）\n\n` +
+            `请执行意图级 Spec Review，对照 openspec/changes/ 中的 spec delta 与代码变更：\n\n` +
+            `**审查维度**：\n` +
+            `1. 🗺️ **意图对齐矩阵**：每个 spec 需求/场景 → 对应代码位置 → ✅/⚠️/❌\n` +
+            `2. 🔴 **意图偏差（Critical）**：实现与 spec 意图相反或严重不符\n` +
+            `3. 🟡 **遗漏需求（Warning）**：spec 中有但代码未实现的场景\n` +
+            `4. 💡 **超范围实现（Info）**：代码实现了 spec 未定义的功能\n\n` +
+            `请先读取 openspec/changes/ 中最新的变更提案，再对照代码变更执行审查。\n\n` +
+            `CLI 用法：\`ethan spec review\``,
+    },
+    {
+        id: 'spec-validate',
+        name: 'Spec 规范校验',
+        category: 'OpenSpec',
+        description: '校验 openspec/ 目录结构完整性：Requirements 编号、GIVEN/WHEN/THEN 格式',
+        prompt: `# Ethan — Spec Validate\n\n` +
+            `请校验项目 openspec/ 目录的规范完整性，检查：\n\n` +
+            `- 每个 capability 是否包含 Purpose / Requirements / Scenarios 章节\n` +
+            `- Requirements 编号是否连续（REQ-001, REQ-002...）\n` +
+            `- Scenario 是否使用完整的 GIVEN/WHEN/THEN 格式\n` +
+            `- 是否存在空内容的占位模板\n\n` +
+            `输出：问题列表（按严重程度分级）+ 合格/不合格摘要\n\n` +
+            `CLI 用法：\`ethan spec validate [capability]\``,
+    },
 ];
 program
     .command('slash')
@@ -540,6 +588,9 @@ program
                     'explain': 'ethan explain $ARGUMENTS --no-copy',
                     'test-case': 'ethan test-case $ARGUMENTS --no-copy',
                     'estimate': 'ethan estimate --no-copy $ARGUMENTS',
+                    'spec-proposal': 'ethan spec proposal --no-copy $ARGUMENTS',
+                    'spec-review': 'ethan spec review --no-copy',
+                    'spec-validate': 'ethan spec validate --no-copy $ARGUMENTS',
                 };
                 // 需要参数的命令：无参调用时显示用法说明（printf 内 \n 为换行）
                 const PIPELINE_LIST = 'dev-workflow: 需求理解->拆解->设计->实现\\n' +
@@ -547,7 +598,8 @@ program
                     '- new-feature: PRD->技术调研->接口->拆解->实现\\n' +
                     '- quality-workflow: 代码审查->故障排查\\n' +
                     '- reporting: 进度跟踪->任务报告->周报\\n' +
-                    '- incident-response: 故障排查->技术调研->任务报告';
+                    '- incident-response: 故障排查->技术调研->任务报告\\n' +
+                    '- spec-workflow: Spec提案->方案设计->任务拆解->实现->意图审查';
                 const SLASH_USAGE_FALLBACKS = {
                     'auto': '## Ethan Auto-Pilot — 缺少参数\\n\\n' +
                         '用法: /ethan-auto <pipeline> [-c 任务描述]\\n\\n' +
@@ -3547,5 +3599,196 @@ skillIds:
     console.log(`\n✅ 自定义 Pipeline 模板已生成：${filePath}`);
     console.log(`\n💡 编辑后运行：ethan workflow start ${options.name} -c "任务描述"\n`);
 });
+// ─── spec 命令组 ─────────────────────────────────────────────────────────────
+const specCmd = program.command('spec').description('OpenSpec 规范驱动开发工具集');
+specCmd
+    .command('init <capability>')
+    .description('初始化 openspec/specs/[capability]/spec.md 规范文件')
+    .option('-d, --dir <dir>', '项目目录', process.cwd())
+    .action(async (capability, options) => {
+    const { writeSpecFile, specTemplate } = await Promise.resolve().then(() => __importStar(require('../spec/index')));
+    const filePath = writeSpecFile(capability, specTemplate(capability), options.dir);
+    console.log(`\n✅ Spec 文件已创建：${filePath}`);
+    console.log(`\n💡 编辑文件填写需求和场景，再运行 ethan spec validate ${capability} 检查格式\n`);
+});
+specCmd
+    .command('list')
+    .description('列出所有 openspec/specs/ 下的 capability')
+    .option('-d, --dir <dir>', '项目目录', process.cwd())
+    .action(async (options) => {
+    const { hasOpenSpec, listSpecs, listChanges } = await Promise.resolve().then(() => __importStar(require('../spec/index')));
+    if (!hasOpenSpec(options.dir)) {
+        console.log('\n⚠️  当前项目未检测到 openspec/ 目录。');
+        console.log('运行 ethan spec init <capability> 初始化第一个 spec 文件。\n');
+        return;
+    }
+    const specs = listSpecs(options.dir);
+    const changes = listChanges(options.dir);
+    console.log('\n📋 OpenSpec 规范目录\n');
+    if (specs.length === 0) {
+        console.log('  （openspec/specs/ 暂无 spec 文件）');
+    }
+    else {
+        for (const spec of specs) {
+            const lines = spec.content.split('\n').filter(Boolean);
+            const reqCount = (spec.content.match(/### REQ-/g) || []).length;
+            const scenCount = (spec.content.match(/### Scenario/g) || []).length;
+            console.log(`  📄 ${spec.capability}  (${reqCount} 需求, ${scenCount} 场景)`);
+            if (lines[0])
+                console.log(`     ${lines[0].replace(/^#+\s*/, '')}`);
+        }
+    }
+    console.log(`\n📁 变更提案：${changes.length} 个`);
+    for (const c of changes.slice(0, 5)) {
+        const title = c.proposalContent?.split('\n').find((l) => l.startsWith('# '))?.replace('# ', '') || c.id;
+        console.log(`  📝 ${c.id}  ${title}`);
+    }
+    console.log('');
+});
+specCmd
+    .command('show <capability>')
+    .description('显示指定 capability 的 spec.md 内容')
+    .option('-d, --dir <dir>', '项目目录', process.cwd())
+    .action(async (capability, options) => {
+    const { listSpecs } = await Promise.resolve().then(() => __importStar(require('../spec/index')));
+    const specs = listSpecs(options.dir);
+    const spec = specs.find((s) => s.capability === capability);
+    if (!spec) {
+        console.error(`\n❌ 未找到 capability: ${capability}`);
+        console.error(`可用：${specs.map((s) => s.capability).join(', ') || '（无）'}\n`);
+        process.exit(1);
+    }
+    console.log(`\n📄 ${capability}\n\n${spec.content}\n`);
+});
+specCmd
+    .command('validate [capability]')
+    .description('校验 openspec/ 规范完整性（Requirements 编号、GIVEN/WHEN/THEN 格式）')
+    .option('-d, --dir <dir>', '项目目录', process.cwd())
+    .option('--no-copy', '不复制到剪贴板', false)
+    .action(async (capability, options) => {
+    const { hasOpenSpec, listSpecs } = await Promise.resolve().then(() => __importStar(require('../spec/index')));
+    if (!hasOpenSpec(options.dir)) {
+        console.error('\n❌ 当前项目未检测到 openspec/ 目录。\n');
+        process.exit(1);
+    }
+    const specs = listSpecs(options.dir);
+    const filtered = capability ? specs.filter((s) => s.capability === capability) : specs;
+    if (filtered.length === 0) {
+        console.error(capability ? `\n❌ 未找到 capability: ${capability}\n` : '\n⚠️  openspec/specs/ 下没有任何 spec 文件\n');
+        process.exit(1);
+    }
+    let totalIssues = 0;
+    for (const spec of filtered) {
+        const issues = [];
+        const content = spec.content;
+        if (!content.includes('## Purpose') && !content.includes('## 用途'))
+            issues.push('缺少 ## Purpose 章节');
+        if (!content.includes('## Requirements') && !content.includes('## 需求'))
+            issues.push('缺少 ## Requirements 章节');
+        if (!content.includes('## Scenarios') && !content.includes('## 场景'))
+            issues.push('缺少 ## Scenarios 章节');
+        const gwtRegex = /GIVEN[\s\S]*?WHEN[\s\S]*?THEN/i;
+        if (content.includes('Scenario') && !gwtRegex.test(content))
+            issues.push('存在 Scenario 但未使用 GIVEN/WHEN/THEN 格式');
+        totalIssues += issues.length;
+        const icon = issues.length === 0 ? '✅' : issues.length <= 2 ? '⚠️ ' : '❌';
+        console.log(`\n${icon} ${spec.capability}`);
+        if (issues.length === 0) {
+            console.log('   规范结构完整，无问题。');
+        }
+        else {
+            issues.forEach((issue) => console.log(`   - ${issue}`));
+        }
+    }
+    console.log(`\n汇总：${filtered.length} 个 capability，发现 ${totalIssues} 个问题。${totalIssues === 0 ? ' 🎉 全部通过！' : ''}\n`);
+});
+specCmd
+    .command('proposal <capability>')
+    .description('生成 OpenSpec 变更提案包（proposal.md + design.md + tasks.md + spec delta）')
+    .option('-c, --context <context>', '变更描述（如"新增用户邮箱二次验证"）', '')
+    .option('-d, --dir <dir>', '项目目录', process.cwd())
+    .option('--no-copy', '不复制到剪贴板', false)
+    .action(async (capability, options) => {
+    const description = options.context || capability;
+    const { listSpecs, generateChangeId, proposalTemplate, designTemplate, tasksTemplate, specDeltaTemplate, writeChangeFiles, hasOpenSpec, } = await Promise.resolve().then(() => __importStar(require('../spec/index')));
+    if (!hasOpenSpec(options.dir)) {
+        console.log('\n⚠️  未检测到 openspec/ 目录，自动初始化...');
+        const { writeSpecFile, specTemplate } = await Promise.resolve().then(() => __importStar(require('../spec/index')));
+        writeSpecFile(capability, specTemplate(capability), options.dir);
+        console.log(`   已创建 openspec/specs/${capability}/spec.md\n`);
+    }
+    const changeId = generateChangeId();
+    const proposal = proposalTemplate(changeId, description);
+    const design = designTemplate(description);
+    const tasks = tasksTemplate(description);
+    const specDelta = specDeltaTemplate(capability, description);
+    const changeDir = writeChangeFiles(changeId, { proposal, design, tasks, specDeltas: [{ capability, content: specDelta }] }, options.dir);
+    const specs = listSpecs(options.dir);
+    console.log(`\n✅ 变更提案包已生成：${changeDir}`);
+    console.log(`   📝 proposal.md — 填写变更描述和影响范围`);
+    console.log(`   🏗️  design.md — 填写技术方案和架构决策`);
+    console.log(`   📋 tasks.md — 填写分阶段任务列表`);
+    console.log(`   📄 specs/${capability}.md — 填写需求变更 delta`);
+    console.log(`\n💡 编辑完成后运行 ethan spec review 执行意图审查\n`);
+    console.log(`   Change ID: ${changeId}`);
+    if (specs.length > 0) {
+        console.log(`   已有 Capability: ${specs.map((s) => s.capability).join(', ')}`);
+    }
+    console.log('');
+});
+specCmd
+    .command('review')
+    .description('意图级 Spec Review：对比 spec delta 与代码变更，输出对齐矩阵和偏差报告')
+    .option('--change-id <id>', '指定 Change ID（不填则取最新）', '')
+    .option('-d, --dir <dir>', '项目目录', process.cwd())
+    .option('--no-copy', '不复制到剪贴板', false)
+    .action(async (options) => {
+    const { hasOpenSpec, loadLatestChange, listChanges, truncateSpec } = await Promise.resolve().then(() => __importStar(require('../spec/index')));
+    if (!hasOpenSpec(options.dir)) {
+        console.error('\n❌ 当前项目未检测到 openspec/ 目录。先运行 ethan spec init <capability> 初始化。\n');
+        process.exit(1);
+    }
+    const changes = listChanges(options.dir);
+    if (changes.length === 0) {
+        console.error('\n⚠️  未找到任何变更提案（openspec/changes/ 为空）。先运行 ethan spec proposal <capability> 创建提案。\n');
+        process.exit(1);
+    }
+    const change = options.changeId
+        ? (changes.find((c) => c.id === options.changeId) ?? loadLatestChange(options.dir))
+        : loadLatestChange(options.dir);
+    if (!change) {
+        console.error(`\n❌ 未找到 Change ID: ${options.changeId}\n`);
+        process.exit(1);
+    }
+    const gitDiff = (0, utils_1.isGitRepo)(options.dir) ? (0, utils_1.getBranchDiff)(options.dir) : '';
+    const truncatedDiff = gitDiff ? (0, utils_1.truncateDiff)(gitDiff, 6000) : '（非 git 仓库或无代码变更）';
+    let prompt = `# Spec Review — ${change.id}\n\n`;
+    if (change.proposalContent) {
+        prompt += `## 变更提案\n\n${truncateSpec(change.proposalContent, 800)}\n\n`;
+    }
+    if (change.specDeltas.length > 0) {
+        prompt += `## Spec Delta（需求变更）\n\n`;
+        for (const delta of change.specDeltas) {
+            prompt += `### ${delta.capability}\n\n${truncateSpec(delta.content, 600)}\n\n`;
+        }
+    }
+    prompt += `## 代码变更（Diff）\n\n\`\`\`diff\n${truncatedDiff}\n\`\`\`\n\n`;
+    prompt += `---\n\n## 意图审查任务\n\n`;
+    prompt += `请对照上方 spec delta 与代码 diff，执行意图级 Review：\n\n`;
+    prompt += `1. **意图对齐矩阵**\n\n   | Spec 需求/场景 | 代码位置 | 状态 | 说明 |\n   |---|---|---|---|\n\n`;
+    prompt += `2. **🔴 意图偏差（Critical）**：实现与 spec 意图严重不符，必须修复\n`;
+    prompt += `3. **🟡 遗漏需求（Warning）**：spec 有但代码未实现\n`;
+    prompt += `4. **💡 超范围实现（Info）**：代码实现了 spec 未定义的功能\n`;
+    prompt += `5. **审查结论**：可合并 / 需要修复 / 需要更新 spec\n\n`;
+    prompt += `> Review intent, not just code。`;
+    if (options.copy !== false) {
+        copyToClipboard(prompt);
+        console.log(`\n✅ Spec Review 提示词已复制到剪贴板（Change: ${change.id}）`);
+        console.log('   粘贴到 AI 编辑器执行意图审查。\n');
+    }
+    else {
+        console.log(prompt);
+    }
+});
 program.parse(process.argv);
 //# sourceMappingURL=index.js.map