@localsummer/incspec 0.2.4 → 0.2.6

package/README.md

@@ -33,7 +33,7 @@ AI 编程助手在处理复杂前端代码库时常常力不从心，因为 API
 - **依赖追踪**：6 维度分析 UI 依赖（API、Store、Types 等）。
 - **增量设计**：7 模块蓝图指导实现。
 - **无缝迭代**：将完成的工作合并为新基线，开启下一轮循环。
-- **历史可追溯**：归档按年月和模块组织，便于回顾历史决策。
+- **历史可追溯**：归档按年月和工作流名称组织，便于回顾历史决策。
 - 兼容你已有的 AI 工具：Cursor、Claude Code 及任何 AGENTS.md 兼容助手。
 
 ## IncSpec 对比一览
@@ -360,8 +360,8 @@ $ incspec archive -y    # 归档所有工作流产出，跳过确认
 ### 为什么需要归档?
 
 - **保持工作区整洁**：避免多轮迭代的文件混杂在一起。
-- **历史可追溯**：按年月和模块组织，便于回顾历史决策。
-- **迭代边界清晰**：每轮归档后，`baselines/`、`requirements/`、`increments/` 目录重新开始。
+- **历史可追溯**：按年月和工作流名称组织，便于回顾历史决策。
+- **迭代边界清晰**：每轮归档后，当前工作流产出从 `baselines/`、`requirements/`、`increments/` 移出，便于下一轮重新生成。
 
 ### 归档时机
 
@@ -375,7 +375,8 @@ $ incspec archive -y    # 归档所有工作流产出，跳过确认
 
 ```bash
 # 归档整个工作流（推荐）
-incspec archive --workflow      # 交互式确认
+incspec archive                 # 交互式确认（默认归档当前工作流）
+incspec archive --workflow      # 显式指定归档当前工作流
 incspec archive -y              # 跳过确认，直接归档
 
 # 归档指定文件
@@ -391,26 +392,25 @@ incspec list archives           # 仅列出归档文件
 
 ### 归档后的目录结构
 
-归档命令按年月和模块自动组织文件：
+归档命令按年月和工作流名称组织文件（文件直接放在工作流目录下）：
 
 ```
 incspec/
 ├── archives/
 │   └── 2024-12/                      # 按年月组织
-│       └── home-search-filter/       # 按工作流模块分组
-│           ├── baselines/
-│           │   ├── home-baseline-v1.md   # 初始基线
-│           │   └── home-baseline-v2.md   # 合并后的新基线
-│           ├── requirements/
-│           │   ├── structured-requirements.md
-│           │   └── ui-dependencies.md
-│           └── increments/
-│               └── search-filter-increment-v1.md
-├── baselines/                        # 归档后已清空，准备下一轮
-├── requirements/                     # 归档后已清空
-└── increments/                       # 归档后已清空
+│       └── home-search-filter/       # 工作流名称
+│           ├── home-baseline-v1.md
+│           ├── structured-requirements.md
+│           ├── ui-dependencies.md
+│           ├── search-filter-increment-v1.md
+│           └── home-baseline-v2.md
+├── baselines/                        # 当前工作流产出默认已移动
+├── requirements/                     # 当前工作流产出默认已移动
+└── increments/                       # 当前工作流产出默认已移动
 ```
 
+说明：若单文件归档且没有当前工作流，文件会直接进入 `archives/YYYY-MM/`。
+
 ### 归档工作流示意
 
 ```
@@ -435,23 +435,22 @@ incspec/
 ┌────────────────────────────────────────────┐
 │ 归档完成                                   │
 │                                            │
-│  ┌─────────────┐      ┌─────────────┐      │
-│  │ archives/   │      │ baselines/  │      │
-│  │ 2024-12/    │      │ (已清空)    │      │
-│  │ module/     │      │             │      │
-│  │  ├─baselines│      │ 准备下一轮  │      │
-│  │  ├─requirements    │ 迭代        │      │
-│  │  └─increments      └─────────────┘      │
-│  └─────────────┘                           │
+│  ┌─────────────┐      ┌─────────────────┐  │
+│  │ archives/   │      │ baselines/      │  │
+│  │ 2024-12/    │      │ requirements/   │  │
+│  │ workflow/   │      │ increments/     │  │
+│  │  ├─*.md     │      │ (当前工作流产出 │  │
+│  │  └─*.md     │      │ 已移动)         │  │
+│  └─────────────┘      └─────────────────┘  │
 └────────────────────────────────────────────┘
 ```
 
 ### 归档最佳实践
 
 1. **及时归档** - 完成一轮迭代后立即归档，避免文件堆积。
-2. **使用 --workflow** - 优先归档整个工作流，确保完整性。
-3. **保留新基线** - 归档时新基线会被复制（而非移动）到归档目录，同时保留在 `baselines/` 作为下一轮起点。
-4. **定期清理** - 对于过期的归档，可手动删除或移至外部存储。
+2. **优先归档整个工作流** - 直接执行 `incspec archive` 或 `--workflow`，确保产出完整。
+3. **明确移动/保留策略** - 默认移动到归档目录，需保留原文件时使用 `--keep`。
+4. **保持工作流命名清晰** - 归档目录按工作流名称分组，命名清晰更易追溯。
 
 ## 回退与重置
 
@@ -488,7 +487,7 @@ your-project/
 │   │   └── feature-increment-v1.md
 │   └── archives/                # 历史归档
 │       └── 2024-12/             # 按年月组织
-│           └── {module}/        # 按工作流模块分组
+│           └── {workflow}/      # 按工作流名称分组
 └── .cursor/
     └── commands/
         └── incspec/             # Cursor 命令

package/package.json

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

package/src/commands/analyze.mjs

@@ -87,6 +87,23 @@ export async function analyzeCommand(ctx) {
   // Ensure initialized
   const projectRoot = ensureInitialized(cwd);
 
+  // Handle --complete flag as independent mode (skip all interactive flows)
+  if (options.complete) {
+    const workflow = readWorkflow(projectRoot);
+    if (!workflow?.currentWorkflow) {
+      printError('没有活跃的工作流，无法标记完成。');
+      process.exit(1);
+    }
+    const output = typeof options.output === 'string' ? options.output : null;
+    if (!output) {
+      printError('请通过 --output 指定输出文件名。');
+      process.exit(1);
+    }
+    updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, output);
+    printSuccess(`步骤 ${STEP_NUMBER} 已标记为完成: ${output}`);
+    return;
+  }
+
   // Handle --baseline option: use existing baseline report
   if (options.baseline) {
     const baselineFile = typeof options.baseline === 'string' ? options.baseline : '';
@@ -234,11 +251,4 @@ export async function analyzeCommand(ctx) {
   print(colorize('完成分析后，运行以下命令标记完成:', colors.dim));
   print(colorize(`  incspec analyze --complete --output=${outputFile}`, colors.dim));
   print('');
-
-  // Handle --complete flag
-  if (options.complete) {
-    const output = typeof options.output === 'string' ? options.output : outputFile;
-    updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, output);
-    printSuccess(`步骤 1 已标记为完成: ${output}`);
-  }
 }

package/src/commands/apply.mjs

@@ -57,6 +57,17 @@ export async function applyCommand(ctx) {
   // Get workflow state
   const workflow = readWorkflow(projectRoot);
 
+  // Handle --complete flag as independent mode (skip all checks)
+  if (options.complete) {
+    if (!workflow?.currentWorkflow) {
+      printWarning('没有活跃的工作流，无法标记完成。');
+      return;
+    }
+    updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, '代码已应用');
+    printSuccess(`步骤 ${STEP_NUMBER} 已标记为完成`);
+    return;
+  }
+
   if (!workflow?.currentWorkflow) {
     printWarning('没有活跃的工作流。请先运行 incspec analyze 开始新工作流。');
     return;
@@ -176,9 +187,8 @@ export async function applyCommand(ctx) {
   printInfo(`完成后运行 'incspec status' 查看进度`);
   print('');
 
-  // Handle --complete flag
-  if (options.complete) {
-    updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, '代码已应用');
-    printSuccess(`步骤 5 已标记为完成`);
-  }
+  // Provide command to mark as complete
+  print(colorize('完成代码应用后，运行以下命令标记完成:', colors.dim));
+  print(colorize(`  incspec apply --complete`, colors.dim));
+  print('');
 }

package/src/commands/collect-dep.mjs

@@ -40,6 +40,21 @@ export async function collectDepCommand(ctx) {
   // Get workflow state
   const workflow = readWorkflow(projectRoot);
 
+  // Handle --complete flag as independent mode (skip all checks)
+  if (options.complete) {
+    if (!workflow?.currentWorkflow) {
+      printWarning('没有活跃的工作流，无法标记完成。');
+      return;
+    }
+    if (!isStepAllowed(STEP_NUMBER, workflow.mode)) {
+      printWarning('当前工作流为快速模式，步骤 3 已跳过，无需标记完成。');
+      return;
+    }
+    updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, OUTPUT_FILE);
+    printSuccess(`步骤 ${STEP_NUMBER} 已标记为完成: ${OUTPUT_FILE}`);
+    return;
+  }
+
   if (!workflow?.currentWorkflow) {
     printWarning('没有活跃的工作流。请先运行 incspec analyze 开始新工作流。');
     return;
@@ -91,9 +106,8 @@ export async function collectDepCommand(ctx) {
   printInfo(`完成后运行 'incspec status' 查看进度`);
   print('');
 
-  // Handle --complete flag
-  if (options.complete) {
-    updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, OUTPUT_FILE);
-    printSuccess(`步骤 3 已标记为完成: ${OUTPUT_FILE}`);
-  }
+  // Provide command to mark as complete
+  print(colorize('完成依赖采集后，运行以下命令标记完成:', colors.dim));
+  print(colorize(`  incspec collect-dep --complete`, colors.dim));
+  print('');
 }

package/src/commands/collect-req.mjs

@@ -40,6 +40,24 @@ export async function collectReqCommand(ctx) {
   // Get workflow state
   const workflow = readWorkflow(projectRoot);
 
+  // Handle --complete flag as independent mode (skip all checks)
+  if (options.complete) {
+    if (!workflow?.currentWorkflow) {
+      printWarning('没有活跃的工作流，无法标记完成。');
+      return;
+    }
+    updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, OUTPUT_FILE);
+    printSuccess(`步骤 ${STEP_NUMBER} 已标记为完成: ${OUTPUT_FILE}`);
+
+    // Quick mode hint
+    if (isQuickMode(workflow)) {
+      print('');
+      printInfo('快速模式: 跳过步骤 3、4，直接进入步骤 5');
+      print(colorize("  运行 'incspec apply' 继续", colors.cyan));
+    }
+    return;
+  }
+
   if (!workflow?.currentWorkflow) {
     printWarning('没有活跃的工作流。请先运行 incspec analyze 开始新工作流。');
     return;
@@ -81,16 +99,8 @@ export async function collectReqCommand(ctx) {
   printInfo(`完成后运行 'incspec status' 查看进度`);
   print('');
 
-  // Handle --complete flag
-  if (options.complete) {
-    updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, OUTPUT_FILE);
-    printSuccess(`步骤 2 已标记为完成: ${OUTPUT_FILE}`);
-
-    // Quick mode hint
-    if (isQuickMode(workflow)) {
-      print('');
-      printInfo('快速模式: 跳过步骤 3、4，直接进入步骤 5');
-      print(colorize("  运行 'incspec apply' 继续", colors.cyan));
-    }
-  }
+  // Provide command to mark as complete
+  print(colorize('完成需求收集后，运行以下命令标记完成:', colors.dim));
+  print(colorize(`  incspec collect-req --complete`, colors.dim));
+  print('');
 }

package/src/commands/design.mjs

@@ -42,6 +42,26 @@ export async function designCommand(ctx) {
   // Get workflow state
   const workflow = readWorkflow(projectRoot);
 
+  // Handle --complete flag as independent mode (skip all checks)
+  if (options.complete) {
+    if (!workflow?.currentWorkflow) {
+      printWarning('没有活跃的工作流，无法标记完成。');
+      return;
+    }
+    if (!isStepAllowed(STEP_NUMBER, workflow.mode)) {
+      printWarning('当前工作流为快速模式，步骤 4 已跳过，无需标记完成。');
+      return;
+    }
+    const output = typeof options.output === 'string' ? options.output : null;
+    if (!output) {
+      printWarning('请通过 --output 指定输出文件名。');
+      return;
+    }
+    updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, output);
+    printSuccess(`步骤 ${STEP_NUMBER} 已标记为完成: ${output}`);
+    return;
+  }
+
   if (!workflow?.currentWorkflow) {
     printWarning('没有活跃的工作流。请先运行 incspec analyze 开始新工作流。');
     return;
@@ -132,10 +152,8 @@ export async function designCommand(ctx) {
   printInfo(`完成后运行 'incspec status' 查看进度`);
   print('');
 
-  // Handle --complete flag
-  if (options.complete) {
-    const output = typeof options.output === 'string' ? options.output : outputFile;
-    updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, output);
-    printSuccess(`步骤 4 已标记为完成: ${output}`);
-  }
+  // Provide command to mark as complete
+  print(colorize('完成增量设计后，运行以下命令标记完成:', colors.dim));
+  print(colorize(`  incspec design --complete --output=${outputFile}`, colors.dim));
+  print('');
 }

package/src/commands/merge.mjs

@@ -55,6 +55,22 @@ export async function mergeCommand(ctx) {
   // Get workflow state
   const workflow = readWorkflow(projectRoot);
 
+  // Handle --complete flag as independent mode (skip all checks)
+  if (options.complete) {
+    if (!workflow?.currentWorkflow) {
+      printWarning('没有活跃的工作流，无法标记完成。');
+      return;
+    }
+    const output = typeof options.output === 'string' ? options.output : null;
+    if (!output) {
+      printWarning('请通过 --output 指定输出文件名。');
+      return;
+    }
+    updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, output);
+    printSuccess(`步骤 ${STEP_NUMBER} 已标记为完成: ${output}`);
+    return;
+  }
+
   if (!workflow?.currentWorkflow) {
     printWarning('没有活跃的工作流。请先运行 incspec analyze 开始新工作流。');
     return;
@@ -163,9 +179,8 @@ export async function mergeCommand(ctx) {
   printInfo(`完成后运行 'incspec status' 查看进度`);
   print('');
 
-  // Handle --complete flag
-  if (options.complete) {
-    updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, outputFile);
-    printSuccess(`步骤 6 已标记为完成: ${outputFile}`);
-  }
+  // Provide command to mark as complete
+  print(colorize('完成基线合并后，运行以下命令标记完成:', colors.dim));
+  print(colorize(`  incspec merge --complete --output=${outputFile}`, colors.dim));
+  print('');
 }

package/src/templates/AGENTS.md

@@ -109,7 +109,7 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
 
 **命令**: `incspec archive [--yes] [<file>] [--keep]`
 
-**目的**: 将已完成的工作流产出归档到 `incspec/archives/YYYY-MM/{module}/`
+**目的**: 将已完成的工作流产出归档到 `incspec/archives/YYYY-MM/{workflow}/`
 
 **验证**: 归档前执行 `incspec validate` 确保项目健康。归档操作本身会验证文件移动正确性。
 
@@ -123,7 +123,7 @@ incspec/
 ├── baselines/              # 基线快照 (版本控制)
 ├── requirements/           # 需求与依赖
 ├── increments/             # 增量设计 (版本控制)
-└── archives/               # 历史归档 (按月/模块)
+└── archives/               # 历史归档 (按月/工作流)
 ```
 
 ## 编号系统

package/src/templates/commands/inc-archive.md

@@ -30,7 +30,7 @@ incspec archive --workflow --yes
 
 # 角色定位
 
-你是 incspec 工作流归档助手。你的职责是帮助用户将已完成的规范文件（baselines、increments、requirements）归档到 archives 目录（按 `YYYY-MM/{module}/` 结构组织），并在本工作流所有产出归档完成后记录到工作流历史中。
+你是 incspec 工作流归档助手。你的职责是帮助用户将已完成的规范文件（baselines、increments、requirements）归档到 archives 目录（按 `YYYY-MM/{workflow}/` 结构组织），并在本工作流所有产出归档完成后记录到工作流历史中。
 
 # 核心目标
 
@@ -130,12 +130,12 @@ incspec archive --workflow --yes
 ### 4.1 检查归档目录
 
 ```bash
-# 查看归档目录结构: archives/YYYY-MM/{module}/
+# 查看归档目录结构: archives/YYYY-MM/{workflow}/
 ls -la incspec/archives/
 ls -la incspec/archives/2025-12/  # 当月目录
 ```
 
-确认文件已复制/移动到归档目录（按年月和工作流模块分组）。
+确认文件已复制/移动到归档目录（按年月和工作流名称分组）。
 
 ### 4.2 检查工作流历史
 
@@ -170,7 +170,7 @@ incspec validate
 🔍 验证结果: 通过
 ```
 
-注意：归档目录结构为 `archives/YYYY-MM/{module}/`，其中 `{module}` 为当前工作流名称。
+注意：归档目录结构为 `archives/YYYY-MM/{workflow}/`，其中 `{workflow}` 为当前工作流名称；若单文件归档且无工作流，则归档到 `archives/YYYY-MM/`。
 
 # 特殊情况处理