@localsummer/incspec 0.0.10 → 0.1.1

package/README.md

@@ -444,6 +444,18 @@ incspec/
 3. **保留新基线** - 归档时新基线会被复制（而非移动）到归档目录，同时保留在 `baselines/` 作为下一轮起点。
 4. **定期清理** - 对于过期的归档，可手动删除或移至外部存储。
 
+## 回退与重置
+
+```bash
+incspec reset              # 全量重置，归档所有产出
+incspec reset --to=3       # 回退到步骤 3，保留 1-3，重置 4-7
+incspec reset -t 3         # 短选项形式
+```
+
+**回退行为:** 保留目标步骤及之前状态，重置后续步骤为 pending，被重置步骤的产出自动归档。
+
+**限制:** 目标步骤必须已完成（1-6），快速模式下不能回退到被跳过的步骤（3、4）。
+
 ## 目录结构
 
 ```
@@ -543,6 +555,10 @@ incspec archive --workflow     # 同上，显式指定
 incspec archive <file>         # 归档指定文件
 incspec archive <file> --keep  # 复制而非移动
 incspec archive -y             # 跳过确认提示
+
+incspec reset                  # 重置当前工作流（别名：rs）
+incspec reset --to=3           # 回退到步骤 3，保留步骤 1-3 的状态
+incspec reset -t 3             # 同上，短选项形式
 ```
 
 </details>
@@ -564,6 +580,7 @@ incspec archive -y             # 跳过确认提示
 | `validate` | `v` | 验证 |
 | `sync` | `s` | 同步 |
 | `update` | `up` | 更新 |
+| `reset` | `rs` | 重置/回退 |
 | `help` | `h` | 帮助 |
 
 </details>

package/commands/help.mjs

@@ -119,9 +119,12 @@ const COMMANDS = {
     ],
   },
   reset: {
-    usage: 'incspec reset',
+    usage: 'incspec reset [--to=<step>]',
     aliases: ['rs'],
-    description: '重置当前工作流，归档已有产出',
+    description: '重置当前工作流，归档已有产出（支持部分回退）',
+    options: [
+      ['-t, --to=<step>', '回退到指定步骤（1-6），保留该步骤及之前的状态'],
+    ],
   },
   sync: {
     usage: 'incspec sync [--cursor] [--claude] [--all] [--project|--global]',

package/commands/init.mjs

@@ -121,7 +121,7 @@ export async function initCommand(ctx) {
   print('');
   print(colorize('下一步:', colors.bold));
   print(colorize(`  1. 运行 'incspec status' 查看工作流状态`, colors.dim));
-  print(colorize(`  2. 运行 'incspec cursor-sync' 同步 Cursor 命令`, colors.dim));
+  print(colorize(`  2. 运行 'incspec sync' 同步 Cursor 命令`, colors.dim));
   print(colorize(`  3. 使用 /incspec/inc-analyze 开始第一个工作流`, colors.dim));
   print('');
 }

package/commands/reset.mjs

@@ -1,5 +1,5 @@
 /**
- * reset command - Reset current workflow
+ * reset command - Reset current workflow (full or partial)
  */
 
 import * as fs from 'fs';
@@ -12,7 +12,9 @@ import {
 import {
   readWorkflow,
   archiveWorkflow,
+  resetToStep,
   STATUS,
+  STEPS,
 } from '../lib/workflow.mjs';
 import { archiveSpec } from '../lib/spec.mjs';
 import {
@@ -22,6 +24,7 @@ import {
   printSuccess,
   printInfo,
   printWarning,
+  printError,
 } from '../lib/terminal.mjs';
 
 /**
@@ -77,7 +80,7 @@ function getOutputDirForStepIndex(stepIndex) {
  * Collect output files from workflow steps
  * @param {string} projectRoot
  * @param {Object} workflow
- * @returns {Array<{path: string, name: string}>}
+ * @returns {Array<{path: string, name: string, stepIndex: number}>}
  */
 function collectWorkflowOutputs(projectRoot, workflow) {
   const outputs = [];
@@ -102,6 +105,7 @@ function collectWorkflowOutputs(projectRoot, workflow) {
       outputs.push({
         path: outputPath,
         name: step.output,
+        stepIndex: index,
       });
     }
   });
@@ -110,24 +114,104 @@ function collectWorkflowOutputs(projectRoot, workflow) {
 }
 
 /**
- * Execute reset command
- * @param {Object} ctx - Command context
+ * Collect output files for specific step indices
+ * @param {string} projectRoot
+ * @param {Array<{index: number, output: string}>} resetOutputs
+ * @returns {Array<{path: string, name: string, stepIndex: number}>}
  */
-export async function resetCommand(ctx) {
-  const { cwd } = ctx;
+function collectResetOutputs(projectRoot, resetOutputs) {
+  const outputs = [];
 
-  // Ensure initialized
-  const projectRoot = ensureInitialized(cwd);
+  for (const item of resetOutputs) {
+    const dir = getOutputDirForStepIndex(item.index);
+    if (!dir) {
+      continue;
+    }
 
-  // Read current workflow
+    const outputPath = path.join(projectRoot, INCSPEC_DIR, dir, item.output);
+    if (fs.existsSync(outputPath)) {
+      outputs.push({
+        path: outputPath,
+        name: item.output,
+        stepIndex: item.index,
+      });
+    }
+  }
+
+  return outputs;
+}
+
+/**
+ * Archive output files
+ * @param {string} projectRoot
+ * @param {Array<{path: string, name: string}>} outputs
+ * @param {string} moduleName
+ * @returns {number} Number of archived files
+ */
+function archiveOutputFiles(projectRoot, outputs, moduleName) {
+  let archivedCount = 0;
+
+  for (const output of outputs) {
+    try {
+      archiveSpec(projectRoot, output.path, true, moduleName);
+      print(colorize(`  - ${output.name}`, colors.dim));
+      archivedCount++;
+    } catch (e) {
+      printWarning(`归档失败: ${output.name} - ${e.message}`);
+    }
+  }
+
+  return archivedCount;
+}
+
+/**
+ * Execute partial reset (reset to specific step)
+ * @param {string} projectRoot
+ * @param {number} targetStep
+ */
+function executePartialReset(projectRoot, targetStep) {
   const workflow = readWorkflow(projectRoot);
+  const workflowName = workflow.currentWorkflow;
+  const moduleName = extractModuleName(workflowName);
+
+  print('');
+  print(colorize('  incspec 工作流部分回退', colors.bold, colors.cyan));
+  print(colorize('  ───────────────────────', colors.dim));
+  print('');
+  print(colorize(`工作流: ${workflowName}`, colors.dim));
+  print(colorize(`回退目标: 步骤 ${targetStep}`, colors.dim));
+  print('');
+
+  // Perform partial reset
+  const { workflow: updatedWorkflow, resetOutputs } = resetToStep(projectRoot, targetStep);
+
+  // Collect and archive output files from reset steps
+  const outputs = collectResetOutputs(projectRoot, resetOutputs);
+
+  if (outputs.length > 0) {
+    print(colorize('归档被重置步骤的产出文件:', colors.dim));
+
+    const archivedCount = archiveOutputFiles(projectRoot, outputs, moduleName);
 
-  if (!workflow?.currentWorkflow) {
     print('');
-    printInfo('当前无活跃工作流，无需重置');
-    return;
+    printSuccess(`已归档 ${archivedCount} 个产出文件到 archives/${new Date().toISOString().slice(0, 7)}/${moduleName}/`);
+  } else {
+    printInfo('被重置步骤无产出文件需要归档');
   }
 
+  // Show reset result
+  print('');
+  const targetStepInfo = STEPS[targetStep - 1];
+  printSuccess(`已回退到步骤 ${targetStep} (${targetStepInfo.name})`);
+  print(colorize(`当前步骤已设为: ${updatedWorkflow.currentStep}`, colors.dim));
+}
+
+/**
+ * Execute full reset
+ * @param {string} projectRoot
+ */
+function executeFullReset(projectRoot) {
+  const workflow = readWorkflow(projectRoot);
   const workflowName = workflow.currentWorkflow;
   const moduleName = extractModuleName(workflowName);
 
@@ -145,17 +229,10 @@ export async function resetCommand(ctx) {
   if (outputs.length > 0) {
     print(colorize('归档产出文件:', colors.dim));
 
-    for (const output of outputs) {
-      try {
-        const archivePath = archiveSpec(projectRoot, output.path, true, moduleName);
-        print(colorize(`  - ${output.name}`, colors.dim));
-      } catch (e) {
-        printWarning(`归档失败: ${output.name} - ${e.message}`);
-      }
-    }
+    const archivedCount = archiveOutputFiles(projectRoot, outputs, moduleName);
 
     print('');
-    printSuccess(`已归档 ${outputs.length} 个产出文件到 archives/${new Date().toISOString().slice(0, 7)}/${moduleName}/`);
+    printSuccess(`已归档 ${archivedCount} 个产出文件到 archives/${new Date().toISOString().slice(0, 7)}/${moduleName}/`);
   } else {
     printInfo('无产出文件需要归档');
   }
@@ -164,3 +241,49 @@ export async function resetCommand(ctx) {
   archiveWorkflow(projectRoot);
   printSuccess('工作流已重置');
 }
+
+/**
+ * Execute reset command
+ * @param {Object} ctx - Command context
+ */
+export async function resetCommand(ctx) {
+  const { cwd, options } = ctx;
+
+  // Ensure initialized
+  const projectRoot = ensureInitialized(cwd);
+
+  // Read current workflow
+  const workflow = readWorkflow(projectRoot);
+
+  if (!workflow?.currentWorkflow) {
+    print('');
+    printInfo('当前无活跃工作流，无需重置');
+    return;
+  }
+
+  // Check for --to option
+  const targetStepStr = options.to || options.t;
+
+  if (targetStepStr) {
+    // Partial reset mode
+    const targetStep = parseInt(targetStepStr, 10);
+
+    if (isNaN(targetStep)) {
+      print('');
+      printError(`无效的步骤编号: ${targetStepStr}`);
+      print(colorize('用法: incspec reset --to=<步骤编号>', colors.dim));
+      print(colorize('示例: incspec reset --to=3', colors.dim));
+      return;
+    }
+
+    try {
+      executePartialReset(projectRoot, targetStep);
+    } catch (error) {
+      print('');
+      printError(error.message);
+    }
+  } else {
+    // Full reset mode (original behavior)
+    executeFullReset(projectRoot);
+  }
+}

package/commands/sync.mjs

@@ -114,12 +114,12 @@ async function syncCursor(ctx) {
       {
         name: `当前目录 (${cwd}/.cursor/commands/incspec/)`,
         value: 'project',
-        description: '仅对当前目录生效',
+        description: colorize('仅对当前目录生效', colors.blue),
       },
       {
         name: '全局目录 (~/.cursor/commands/incspec/)',
         value: 'global',
-        description: '对所有项目生效',
+        description: colorize('对所有项目生效', colors.blue),
       },
     ];
 
@@ -182,12 +182,12 @@ async function syncClaude(ctx) {
       {
         name: `当前目录 (${cwd}/.claude/skills/inc-spec-skill/)`,
         value: 'project',
-        description: '仅对当前目录生效',
+        description: colorize('仅对当前目录生效', colors.blue),
       },
       {
         name: '全局目录 (~/.claude/skills/inc-spec-skill/)',
         value: 'global',
-        description: '对所有项目生效（推荐）',
+        description: colorize('对所有项目生效（推荐）', colors.blue),
       },
     ];
 

package/index.mjs

@@ -34,13 +34,14 @@ function parseArgs(args) {
     options: {},
   };
 
-  const valueOptions = new Set(['module', 'feature', 'source-dir', 'output', 'workflow']);
+  const valueOptions = new Set(['module', 'feature', 'source-dir', 'output', 'workflow', 'to']);
   const shortValueMap = new Map([
     ['m', 'module'],
     ['f', 'feature'],
     ['s', 'source-dir'],
     ['o', 'output'],
     ['w', 'workflow'],
+    ['t', 'to'],
   ]);
   let i = 0;
 

package/lib/cursor.mjs

@@ -19,8 +19,8 @@ const GLOBAL_CURSOR_DIR = path.join(os.homedir(), '.cursor', 'commands', 'incspe
 /** Claude commands source directory (user local) */
 const CLAUDE_COMMANDS_DIR = path.join(os.homedir(), '.claude', 'commands', 'ai-increment');
 
-/** Built-in templates directory (fallback when Claude commands not installed) */
-const TEMPLATES_DIR = fileURLToPath(new URL('../templates/cursor-commands', import.meta.url));
+/** Built-in templates directory */
+const TEMPLATES_DIR = fileURLToPath(new URL('../templates/commands', import.meta.url));
 
 /**
  * Command mapping from Claude to Cursor

package/lib/workflow.mjs

@@ -507,6 +507,81 @@ export function archiveWorkflow(projectRoot) {
   return workflow;
 }
 
+/**
+ * Reset workflow to a specific step (partial reset)
+ * Keeps steps 1 to targetStep, resets steps after targetStep to pending
+ * @param {string} projectRoot
+ * @param {number} targetStep - 1-based step number to reset to (1-6)
+ * @returns {{workflow: Object, resetOutputs: Array<{index: number, stepNumber: number, output: string}>}}
+ */
+export function resetToStep(projectRoot, targetStep) {
+  const workflow = readWorkflow(projectRoot);
+  if (!workflow || !workflow.currentWorkflow) {
+    throw new Error('工作流未初始化或无活跃工作流');
+  }
+
+  // Validate targetStep: must be 1-6 (step 7 is archive, cannot be a reset target)
+  if (targetStep < 1 || targetStep > 6) {
+    throw new Error(`无效的目标步骤: ${targetStep}，有效范围为 1-6`);
+  }
+
+  // Check if target step is completed
+  const targetIndex = targetStep - 1;
+  const targetStepData = workflow.steps[targetIndex];
+  if (!targetStepData || targetStepData.status !== STATUS.COMPLETED) {
+    throw new Error(`目标步骤 ${targetStep} 尚未完成，无法回退到此步骤`);
+  }
+
+  // Handle quick mode: cannot reset to skipped steps
+  const mode = workflow.mode || MODE.FULL;
+  if (mode === MODE.QUICK && QUICK_MODE_SKIPPED.includes(targetStep)) {
+    throw new Error(`快速模式下步骤 ${targetStep} 被跳过，无法回退到此步骤`);
+  }
+
+  // Collect outputs from steps that will be reset (targetStep+1 to 7)
+  const resetOutputs = [];
+  for (let i = targetStep; i < STEPS.length; i++) {
+    const stepData = workflow.steps[i];
+    if (stepData && stepData.output && stepData.output !== '-') {
+      resetOutputs.push({
+        index: i,
+        stepNumber: i + 1,
+        output: stepData.output,
+      });
+    }
+  }
+
+  // Reset steps after targetStep
+  const now = formatLocalDateTime(new Date());
+  for (let i = targetStep; i < STEPS.length; i++) {
+    const stepNumber = i + 1;
+    // In quick mode, keep skipped steps as skipped
+    if (mode === MODE.QUICK && QUICK_MODE_SKIPPED.includes(stepNumber)) {
+      workflow.steps[i] = {
+        status: STATUS.SKIPPED,
+        output: null,
+        completedAt: workflow.steps[i]?.completedAt || now,
+      };
+    } else {
+      workflow.steps[i] = {
+        status: STATUS.PENDING,
+        output: null,
+        completedAt: null,
+      };
+    }
+  }
+
+  // Set currentStep to next step after targetStep
+  workflow.currentStep = getNextStep(targetStep, mode) || targetStep + 1;
+
+  writeWorkflow(projectRoot, workflow);
+
+  return {
+    workflow,
+    resetOutputs,
+  };
+}
+
 /**
  * Get step info by number
  * @param {number} stepNumber

package/package.json

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

package/templates/AGENTS.md

@@ -141,7 +141,8 @@ incspec archive [--yes] [--keep]    # 步骤7
 # 验证与同步
 incspec validate / v [--strict]     # 验证完整性
 incspec sync [--cursor|--claude|--all] [--global|--project]  # IDE集成
-incspec reset [--archive|--clean]   # 重置工作流状态
+incspec reset                       # 完全重置工作流（归档所有产出）
+incspec reset --to=<step>           # 部分回退到指定步骤（保留1-N，重置N+1至7）
 ```
 
 ## 文件格式示例
@@ -210,6 +211,10 @@ baseline: home-baseline-v1
 | No baseline found | 先完成步骤 1 (analyze) |
 | Previous step not completed | 运行 `incspec status` 检查进度 |
 | Validation failed | 检查文件格式和编号序列 |
-| 工作流卡住 | 运行 `incspec reset` 重置状态 |
+| 工作流卡住或状态异常 | `incspec reset` 完全重置，或 `incspec reset --to=N` 回退到步骤N |
+
+**工作流重置**:
+- 完全重置: `incspec reset` - 归档所有产出，回到初始状态
+- 部分回退: `incspec reset --to=N` - 保留步骤1-N，重置N+1至7（示例：`--to=3` 保留1-3，重置4-7）
 
 记住: **基线是真相，增量是提案**。通过工作流周期保持它们同步。

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

@@ -101,6 +101,8 @@ description: 设计优先的前端功能增量编码工作流。适用于实现
 - `incspec status` - 查看工作流状态
 - `incspec list` - 列出规范文件
 - `incspec validate` - 验证项目健康状态
+- `incspec reset` - 重置工作流到初始状态
+- `incspec reset --to=N` - 回退到步骤N，保留1-N，重置N+1至7（示例：`--to=3` 保留1-3，重置4-7）
 
 ## 步骤详情
 
@@ -223,20 +225,36 @@ incspec archive <file> --keep      # 复制而非移动
 - 步骤5后: 验证所有文件已正确创建/修改
 - 步骤7后: 确认工作区已清理
 
-**关键人工确认点:**
-- 完整模式: 步骤2后 + 步骤4后
-- 快速模式: 步骤2后 (需求确认后才能开始编码)
+**工作流重置:**
+- 完全重置: `incspec reset` - 归档所有产出，回到初始状态
+- 部分回退: `incspec reset --to=N` - 保留步骤1-N，重置步骤N+1至7。示例：步骤5发现设计有误 → `--to=3` → 重做步骤4-7
+
+**人工确认点:**
+
+| 步骤 | 确认级别 | 快速模式 | 说明 |
+|------|----------|----------|------|
+| 1. 代码流程分析 | 自动 | 适用 | 技术性分析，错误会在后续暴露 |
+| 2. 需求收集 | **必须确认** | 适用 | 需求理解错误会导致全部返工 |
+| 3. 依赖收集 | 自动 | 跳过 | 遗漏会在编译阶段暴露 |
+| 4. 增量设计 | **必须确认** | 跳过 | 架构方案需审批后才能编码 |
+| 5. 代码应用 | 自动 | 适用 | 按蓝图执行，完成后报告结果 |
+| 6. 基线合并 | 自动 | 适用 | 技术性操作，无决策 |
+| 7. 归档 | 建议确认 | 适用 | 涉及文件移动，用户应知晓范围 |
+
+- **完整模式**: 步骤2 + 步骤4必须确认
+- **快速模式**: 仅步骤2必须确认（步骤3、4被跳过）
 
 ## 常见陷阱
 
-| 陷阱 | 后果 |
-|------|------|
-| 跳过代码流程分析 | 集成问题，返工 |
-| 接受模糊需求 | 编码时发现歧义 |
-| 遗漏依赖 | 导入错误，运行时失败 |
-| 编码先于设计 | 在不符合架构的实现上浪费精力 |
-| 跳过基线合并 | 对当前系统状态产生混淆 |
-| 忽略归档 | 工作区杂乱，历史丢失 |
+| 陷阱 | 后果 | 解决方案 |
+|------|------|----------|
+| 跳过代码流程分析 | 集成问题，返工 | 始终从步骤1开始，建立准确基线 |
+| 接受模糊需求 | 编码时发现歧义 | 步骤2必须确认，消除所有模糊术语 |
+| 遗漏依赖 | 导入错误，运行时失败 | 完整模式严格执行步骤3 |
+| 编码先于设计 | 在不符合架构的实现上浪费精力 | 完整模式严格执行步骤4，步骤4设计获批后才执行步骤5 |
+| 跳过基线合并 | 对当前系统状态产生混淆 | 每次增量后必须执行步骤6 |
+| 忽略归档 | 工作区杂乱，历史丢失 | 工作流完成后立即执行步骤7 |
+| 工作流状态不一致 | CLI命令执行失败 | 使用 `incspec status` 检查状态，必要时使用 `incspec reset` 修复 |
 
 ## 参考资源