@localsummer/incspec 0.1.3 → 0.2.0

package/commands/apply.mjs

@@ -15,6 +15,7 @@ import {
   updateStep,
   STATUS,
   isQuickMode,
+  getMissingPrereqs,
 } from '../lib/workflow.mjs';
 import { listSpecs } from '../lib/spec.mjs';
 import {
@@ -29,6 +30,20 @@ import {
 
 const STEP_NUMBER = 5;
 
+function resolveIncrementPath(projectRoot, candidate) {
+  if (!candidate || typeof candidate !== 'string') {
+    return null;
+  }
+
+  const possiblePaths = [
+    candidate,
+    path.join(projectRoot, candidate),
+    path.join(projectRoot, INCSPEC_DIR, DIRS.increments, candidate),
+  ];
+
+  return possiblePaths.find(p => fs.existsSync(p)) || null;
+}
+
 /**
  * Execute apply command
  * @param {Object} ctx - Command context
@@ -48,6 +63,12 @@ export async function applyCommand(ctx) {
   }
 
   const quickMode = isQuickMode(workflow);
+  const missingSteps = getMissingPrereqs(workflow, STEP_NUMBER);
+  if (missingSteps && missingSteps.length > 0 && !options.force) {
+    printWarning(`请先完成步骤 ${missingSteps.join(', ')} 后再继续。`);
+    printInfo('如需强制执行，请添加 --force。');
+    return;
+  }
 
   // Get source directory
   const config = readProjectConfig(projectRoot);
@@ -86,6 +107,13 @@ export async function applyCommand(ctx) {
         printWarning('未找到增量设计文件。请先运行步骤 4 (design)。');
         return;
       }
+    } else {
+      const resolved = resolveIncrementPath(projectRoot, incrementPath);
+      if (!resolved) {
+        printWarning(`增量设计文件不存在: ${incrementPath}`);
+        return;
+      }
+      incrementPath = resolved;
     }
     inputPath = incrementPath;
     inputType = 'increment';

package/commands/collect-dep.mjs

@@ -12,6 +12,8 @@ import {
   readWorkflow,
   updateStep,
   STATUS,
+  isStepAllowed,
+  getMissingPrereqs,
 } from '../lib/workflow.mjs';
 import {
   colors,
@@ -43,6 +45,18 @@ export async function collectDepCommand(ctx) {
     return;
   }
 
+  if (!isStepAllowed(STEP_NUMBER, workflow.mode)) {
+    printWarning('当前工作流为快速模式，步骤 3 已跳过。');
+    return;
+  }
+
+  const missingSteps = getMissingPrereqs(workflow, STEP_NUMBER);
+  if (missingSteps && missingSteps.length > 0 && !options.force) {
+    printWarning(`请先完成步骤 ${missingSteps.join(', ')} 后再继续。`);
+    printInfo('如需强制执行，请添加 --force。');
+    return;
+  }
+
   const outputPath = path.join(INCSPEC_DIR, DIRS.requirements, OUTPUT_FILE);
 
   print('');

package/commands/collect-req.mjs

@@ -13,6 +13,7 @@ import {
   updateStep,
   STATUS,
   isQuickMode,
+  getMissingPrereqs,
 } from '../lib/workflow.mjs';
 import {
   colors,
@@ -44,6 +45,13 @@ export async function collectReqCommand(ctx) {
     return;
   }
 
+  const missingSteps = getMissingPrereqs(workflow, STEP_NUMBER);
+  if (missingSteps && missingSteps.length > 0 && !options.force) {
+    printWarning(`请先完成步骤 ${missingSteps.join(', ')} 后再继续。`);
+    printInfo('如需强制执行，请添加 --force。');
+    return;
+  }
+
   const outputPath = path.join(INCSPEC_DIR, DIRS.requirements, OUTPUT_FILE);
 
   print('');

package/commands/design.mjs

@@ -13,6 +13,8 @@ import {
   readWorkflow,
   updateStep,
   STATUS,
+  isStepAllowed,
+  getMissingPrereqs,
 } from '../lib/workflow.mjs';
 import { getNextVersion, listSpecs } from '../lib/spec.mjs';
 import {
@@ -45,6 +47,18 @@ export async function designCommand(ctx) {
     return;
   }
 
+  if (!isStepAllowed(STEP_NUMBER, workflow.mode)) {
+    printWarning('当前工作流为快速模式，步骤 4 已跳过。');
+    return;
+  }
+
+  const missingSteps = getMissingPrereqs(workflow, STEP_NUMBER);
+  if (missingSteps && missingSteps.length > 0 && !options.force) {
+    printWarning(`请先完成步骤 ${missingSteps.join(', ')} 后再继续。`);
+    printInfo('如需强制执行，请添加 --force。');
+    return;
+  }
+
   // Get feature name
   let featureName = typeof options.feature === 'string' ? options.feature : '';
   if (!featureName) {

package/commands/help.mjs

@@ -52,6 +52,7 @@ const COMMANDS = {
     description: '步骤2: 收集结构化需求',
     options: [
       ['--complete', '标记步骤完成'],
+      ['--force', '忽略前置步骤检查'],
     ],
   },
   'collect-dep': {
@@ -60,6 +61,7 @@ const COMMANDS = {
     description: '步骤3: 采集 UI 依赖',
     options: [
       ['--complete', '标记步骤完成'],
+      ['--force', '忽略前置步骤检查'],
     ],
   },
   design: {
@@ -70,6 +72,7 @@ const COMMANDS = {
       ['-f, --feature=<name>', '指定功能名称'],
       ['--complete', '标记步骤完成'],
       ['-o, --output=<file>', '完成时指定输出文件'],
+      ['--force', '忽略前置步骤检查'],
     ],
   },
   apply: {
@@ -79,6 +82,7 @@ const COMMANDS = {
     options: [
       ['-s, --source-dir=<path>', '指定源代码目录'],
       ['--complete', '标记步骤完成'],
+      ['--force', '忽略前置步骤检查'],
     ],
   },
   merge: {
@@ -88,6 +92,7 @@ const COMMANDS = {
     options: [
       ['--complete', '标记步骤完成'],
       ['-o, --output=<file>', '完成时指定输出文件'],
+      ['--force', '忽略前置步骤检查'],
     ],
   },
   list: {
@@ -145,18 +150,26 @@ const COMMANDS = {
   },
 };
 
+const ALIAS_MAP = Object.entries(COMMANDS).reduce((map, [name, def]) => {
+  (def.aliases || []).forEach((alias) => {
+    map[alias] = name;
+  });
+  return map;
+}, {});
+
 /**
  * Execute help command
  * @param {Object} ctx - Command context
  */
 export async function helpCommand(ctx = {}) {
   const { command } = ctx;
+  const resolvedCommand = command && !COMMANDS[command] ? ALIAS_MAP[command] : command;
 
   print('');
 
-  if (command && COMMANDS[command]) {
+  if (resolvedCommand && COMMANDS[resolvedCommand]) {
     // Show specific command help
-    showCommandHelp(command);
+    showCommandHelp(resolvedCommand);
   } else if (command) {
     print(colorize(`未知命令: ${command}`, colors.red));
     print('');

package/commands/list.mjs

@@ -39,6 +39,9 @@ export async function listCommand(ctx) {
   const types = type ? [type] : ['baselines', 'requirements', 'increments'];
 
   for (const t of types) {
+    if (t === 'archives') {
+      continue;
+    }
     const specs = listSpecs(projectRoot, t);
 
     print(colorize(`${DIRS[t] || t}/`, colors.bold, colors.yellow));
@@ -62,7 +65,8 @@ export async function listCommand(ctx) {
   }
 
   // Show archives if requested
-  if (type === 'archives' || options.all || options.a) {
+  const shouldShowArchives = type === 'archives' || options.all || options.a;
+  if (shouldShowArchives) {
     const archivePath = path.join(projectRoot, INCSPEC_DIR, DIRS.archives);
     print(colorize(`${DIRS.archives}/`, colors.bold, colors.yellow));
     

package/commands/merge.mjs

@@ -2,6 +2,7 @@
  * merge command - Step 6: Merge to baseline
  */
 
+import * as fs from 'fs';
 import * as path from 'path';
 import {
   ensureInitialized,
@@ -13,6 +14,7 @@ import {
   updateStep,
   STATUS,
   isQuickMode,
+  getMissingPrereqs,
 } from '../lib/workflow.mjs';
 import { listSpecs, getNextVersion } from '../lib/spec.mjs';
 import {
@@ -26,6 +28,20 @@ import {
 
 const STEP_NUMBER = 6;
 
+function resolveIncrementPath(projectRoot, candidate) {
+  if (!candidate || typeof candidate !== 'string') {
+    return null;
+  }
+
+  const possiblePaths = [
+    candidate,
+    path.join(projectRoot, candidate),
+    path.join(projectRoot, INCSPEC_DIR, DIRS.increments, candidate),
+  ];
+
+  return possiblePaths.find(p => fs.existsSync(p)) || null;
+}
+
 /**
  * Execute merge command
  * @param {Object} ctx - Command context
@@ -45,6 +61,12 @@ export async function mergeCommand(ctx) {
   }
 
   const quickMode = isQuickMode(workflow);
+  const missingSteps = getMissingPrereqs(workflow, STEP_NUMBER);
+  if (missingSteps && missingSteps.length > 0 && !options.force) {
+    printWarning(`请先完成步骤 ${missingSteps.join(', ')} 后再继续。`);
+    printInfo('如需强制执行，请添加 --force。');
+    return;
+  }
 
   // Calculate output file
   const moduleName = workflow.currentWorkflow.replace(/^analyze-/, '');
@@ -73,6 +95,13 @@ export async function mergeCommand(ctx) {
         printWarning('未找到增量设计文件。请先运行步骤 4 (design)。');
         return;
       }
+    } else {
+      const resolved = resolveIncrementPath(projectRoot, incrementPath);
+      if (!resolved) {
+        printWarning(`增量设计文件不存在: ${incrementPath}`);
+        return;
+      }
+      incrementPath = resolved;
     }
   }
 

package/commands/validate.mjs

@@ -98,15 +98,25 @@ export async function validateCommand(ctx) {
           if (!body.includes('## 1.') && !body.includes('# ')) {
             warnings.push(`${spec.name}: 可能缺少标准章节结构`);
           }
-          if (!body.includes('sequenceDiagram') && !body.includes('graph ')) {
-            warnings.push(`${spec.name}: 未检测到 Mermaid 图表`);
+          const hasSequenceDiagram = /sequenceDiagram/.test(body);
+          const hasGraph = /\bgraph\s+/.test(body);
+          if (!hasSequenceDiagram) {
+            warnings.push(`${spec.name}: 未检测到 Mermaid sequenceDiagram`);
+          }
+          if (!hasGraph) {
+            warnings.push(`${spec.name}: 未检测到 Mermaid graph`);
           }
         }
 
         // Check for required sections in increments
         if (type === 'increments') {
-          const requiredSections = ['模块1', '模块2', '模块3', '模块4', '模块5'];
-          const missingSections = requiredSections.filter(s => !body.includes(s));
+          const requiredSections = Array.from({ length: 7 }, (_, i) => {
+            const num = i + 1;
+            return new RegExp(`^##\\s*(?:模块\\s*)?${num}(?:[.:：\\s]|$)`, 'm');
+          });
+          const missingSections = requiredSections
+            .map((pattern, index) => (pattern.test(body) ? null : index + 1))
+            .filter(Boolean);
           if (missingSections.length > 0) {
             warnings.push(`${spec.name}: 可能缺少模块 ${missingSections.join(', ')}`);
           }

package/lib/cursor.mjs

@@ -227,39 +227,6 @@ ${INCSPEC_DIR}/
 `,
   });
 
-  // Add archive command from template
-  const archiveSourcePath = getSourcePath('inc-archive.md');
-  if (archiveSourcePath) {
-    const archiveContent = fs.readFileSync(archiveSourcePath, 'utf-8');
-    commands.push({
-      name: 'inc-archive.md',
-      content: archiveContent,
-    });
-  } else {
-    commands.push({
-      name: 'inc-archive.md',
-      content: `---
-description: [incspec] 归档规范文件到 archives 目录
----
-
-# 归档规范文件
-
-请运行以下命令归档规范文件:
-
-\`\`\`bash
-# 归档当前工作流全部产出文件（默认模式）
-incspec archive --yes
-
-# 归档指定文件（默认移动模式，删除原文件）
-incspec archive <file-path> --yes
-
-# 归档并保留原文件（复制模式）
-incspec archive <file-path> --keep --yes
-\`\`\`
-`,
-    });
-  }
-
   return commands;
 }
 

package/lib/spec.mjs

@@ -13,6 +13,17 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+function getVersionPattern(type, prefix) {
+  const safePrefix = escapeRegExp(prefix);
+  if (type === 'baselines') {
+    return new RegExp(`^${safePrefix}-baseline-v(\\d+)\\.md$`);
+  }
+  if (type === 'increments') {
+    return new RegExp(`^${safePrefix}-increment-v(\\d+)\\.md$`);
+  }
+  return new RegExp(`^${safePrefix}.*-v(\\d+)\\.md$`);
+}
+
 function ensureUniqueArchivePath(filePath) {
   if (!fs.existsSync(filePath)) {
     return filePath;
@@ -69,8 +80,7 @@ export function listSpecs(projectRoot, type) {
  */
 export function getNextVersion(projectRoot, type, prefix) {
   const specs = listSpecs(projectRoot, type);
-  const safePrefix = escapeRegExp(prefix);
-  const pattern = new RegExp(`^${safePrefix}.*-v(\\d+)\\.md$`);
+  const pattern = getVersionPattern(type, prefix);
 
   const versions = specs
     .map(s => {
@@ -91,8 +101,7 @@ export function getNextVersion(projectRoot, type, prefix) {
  */
 export function getLatestSpec(projectRoot, type, prefix) {
   const specs = listSpecs(projectRoot, type);
-  const safePrefix = escapeRegExp(prefix);
-  const pattern = new RegExp(`^${safePrefix}.*-v(\\d+)\\.md$`);
+  const pattern = getVersionPattern(type, prefix);
 
   const versioned = specs
     .map(s => {

package/lib/terminal.mjs

@@ -174,6 +174,12 @@ export async function prompt(message, defaultValue = '') {
  * @returns {Promise<any>}
  */
 export async function select({ message, choices }) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    const fallback = choices[0]?.value ?? null;
+    printWarning('当前环境不支持交互选择，已使用默认选项。');
+    return fallback;
+  }
+
   return new Promise((resolve) => {
     let cursor = 0;
 
@@ -249,6 +255,12 @@ export async function select({ message, choices }) {
  * @returns {Promise<any[]>}
  */
 export async function checkbox({ message, choices }) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    const selected = choices.filter(c => c.checked).map(c => c.value);
+    printWarning('当前环境不支持交互多选，已使用默认选项。');
+    return selected;
+  }
+
   return new Promise((resolve) => {
     let cursor = 0;
     const selected = choices.map(c => c.checked || false);

package/lib/workflow.mjs

@@ -222,9 +222,6 @@ export function readWorkflow(projectRoot) {
 
   const content = fs.readFileSync(workflowPath, 'utf-8');
   const normalized = normalizeWorkflowContent(content);
-  if (normalized.updated) {
-    fs.writeFileSync(workflowPath, normalized.content, 'utf-8');
-  }
   return parseWorkflow(normalized.content);
 }
 
@@ -730,3 +727,51 @@ export function getNextStep(currentStep, mode) {
 export function shouldSkipStep(stepNumber, mode) {
   return mode === MODE.QUICK && QUICK_MODE_SKIPPED.includes(stepNumber);
 }
+
+/**
+ * Check if a step is allowed in the current mode
+ * @param {number} stepNumber - Step number (1-based)
+ * @param {string} mode - Workflow mode
+ * @returns {boolean}
+ */
+export function isStepAllowed(stepNumber, mode = MODE.FULL) {
+  return !shouldSkipStep(stepNumber, mode);
+}
+
+/**
+ * Get prerequisite steps for a given step
+ * @param {number} stepNumber - Step number (1-based)
+ * @param {string} mode - Workflow mode
+ * @returns {number[]|null} Null if step is not allowed in the mode
+ */
+export function getPrerequisiteSteps(stepNumber, mode = MODE.FULL) {
+  if (stepNumber <= 1) {
+    return [];
+  }
+
+  if (mode === MODE.QUICK) {
+    if (!QUICK_MODE_STEPS.includes(stepNumber)) {
+      return null;
+    }
+    return QUICK_MODE_STEPS.filter(step => step < stepNumber);
+  }
+
+  return Array.from({ length: stepNumber - 1 }, (_, i) => i + 1);
+}
+
+/**
+ * Get missing prerequisite steps for a given step
+ * @param {Object} workflow
+ * @param {number} stepNumber - Step number (1-based)
+ * @returns {number[]|null} Null if step is not allowed in the mode
+ */
+export function getMissingPrereqs(workflow, stepNumber) {
+  const mode = workflow?.mode || MODE.FULL;
+  const requiredSteps = getPrerequisiteSteps(stepNumber, mode);
+  if (requiredSteps === null) {
+    return null;
+  }
+
+  const steps = workflow?.steps || [];
+  return requiredSteps.filter(step => steps[step - 1]?.status !== STATUS.COMPLETED);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localsummer/incspec",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "面向 AI 编程助手的增量规范驱动开发工具",
   "bin": {
     "incspec": "index.mjs"

package/templates/AGENTS.md

@@ -48,7 +48,7 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
 
 ### 步骤 2: 收集结构化需求
 
-**命令**: `incspec collect-req` (别名: `cr`)
+**命令**: `incspec collect-req [--force]` (别名: `cr`)
 
 **目的**: 交互式需求收集,转换为 5 列格式。
 
@@ -58,7 +58,7 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
 
 ### 步骤 3: 收集 UI 依赖
 
-**命令**: `incspec collect-dep` (别名: `cd`)
+**命令**: `incspec collect-dep [--force]` (别名: `cd`)
 
 **目的**: 映射新增/修改 UI 组件的所有上下文依赖。
 
@@ -68,7 +68,7 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
 
 ### 步骤 4: 设计增量
 
-**命令**: `incspec design [--feature=name]` (别名: `d`)
+**命令**: `incspec design [--feature=name] [--force]` (别名: `d`)
 
 **目的**: 创建全面的增量设计蓝图。
 
@@ -87,7 +87,7 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
 
 ### 步骤 5: 应用代码变更
 
-**命令**: `incspec apply [increment-path]` (别名: `ap`)
+**命令**: `incspec apply [increment-path] [--force]` (别名: `ap`)
 
 **目的**: 根据增量蓝图执行代码生成和修改。
 
@@ -97,7 +97,7 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
 
 ### 步骤 6: 合并到基线
 
-**命令**: `incspec merge [increment-path]` (别名: `m`)
+**命令**: `incspec merge [increment-path] [--force]` (别名: `m`)
 
 **目的**: 将增量整合到新的基线快照中。
 
@@ -145,11 +145,11 @@ incspec list / ls [-l] [-a]         # 列出规格文件
 
 # 7步工作流
 incspec analyze <path> [--quick] [--module=name] [--baseline=file]  # 步骤1
-incspec collect-req / cr            # 步骤2
-incspec collect-dep / cd            # 步骤3 (快速模式跳过)
-incspec design / d [--feature=name] # 步骤4 (快速模式跳过)
-incspec apply / ap [path]           # 步骤5
-incspec merge / m [path]            # 步骤6
+incspec collect-req / cr [--force]  # 步骤2 (--force 跳过前置检查)
+incspec collect-dep / cd [--force]  # 步骤3 (快速模式跳过)
+incspec design / d [--feature=name] [--force]  # 步骤4 (快速模式跳过)
+incspec apply / ap [path] [--force] # 步骤5
+incspec merge / m [path] [--force]  # 步骤6
 incspec archive [--yes] [--keep]    # 步骤7
 
 # 验证与同步
@@ -223,10 +223,15 @@ baseline: home-baseline-v1
 |------|----------|
 | Workflow not initialized | 运行 `incspec init` |
 | No baseline found | 先完成步骤 1 (analyze) |
-| Previous step not completed | 运行 `incspec status` 检查进度 |
+| Previous step not completed | 运行 `incspec status` 检查进度，或添加 `--force` 跳过前置检查 |
 | Validation failed | 检查文件格式和编号序列 |
 | 工作流卡住或状态异常 | `incspec reset` 完全重置，或 `incspec reset --to=N` 回退到步骤N |
 
+**前置步骤检查**:
+- 步骤 2-6 执行前会自动检查前置步骤是否完成
+- 若前置步骤未完成，命令会提示并阻止执行
+- 添加 `--force` 可跳过此检查，强制执行当前步骤
+
 **工作流重置**:
 - 完全重置: `incspec reset` - 归档所有产出，回到初始状态
 - 部分回退: `incspec reset --to=N` - 保留步骤1-N，重置N+1至7（示例：`--to=3` 保留1-3，重置4-7）

package/templates/inc-spec-skill/SKILL.md

@@ -104,6 +104,8 @@ description: 设计优先的前端功能增量编码工作流。适用于实现
 | 合并 | 完整/快速 | `incspec merge <report>` | `--complete --output=<file>` |
 | 归档 | 完整/快速 | `incspec archive --yes` | - |
 
+**前置步骤检查**: 步骤 2-6 执行前会自动检查前置步骤是否完成。若前置步骤未完成，命令会提示并阻止执行。添加 `--force` 可跳过此检查。
+
 管理命令:
 - `incspec status` - 查看工作流状态
 - `incspec list` - 列出规范文件
@@ -273,6 +275,7 @@ incspec archive <file> --keep      # 复制而非移动
 | 跳过基线合并 | 对当前系统状态产生混淆 | 每次增量后必须执行步骤6 |
 | 忽略归档 | 工作区杂乱，历史丢失 | 工作流完成后立即执行步骤7 |
 | 工作流状态不一致 | CLI命令执行失败 | 使用 `incspec status` 检查状态，必要时使用 `incspec reset` 修复 |
+| 前置步骤未完成 | 命令被阻止执行 | 按顺序完成前置步骤，或添加 `--force` 强制执行 |
 
 ## 参考资源