@localsummer/incspec 0.0.4 → 0.0.6

package/README.md

@@ -10,6 +10,8 @@
 
 # IncSpec
 
+![IncSpec 全局介绍](./assets/incspec.jpeg)
+
 IncSpec 通过**增量规范驱动开发**让人类与 AI 编程助手保持一致 - 这是一个 6+1 步工作流（6 步开发 + 归档），在修改代码前先捕获代码流程基线。**无需 API 密钥。**
 
 ## 为什么选择 IncSpec?
@@ -89,6 +91,8 @@ AI 编程助手在处理复杂前端代码库时常常力不从心，因为 API
               └───────────┘
 ```
 
+> **提示**: 如果已有基准报告，可使用 `incspec analyze --baseline=<file>` 直接跳过分析步骤，快速进入后续工作流。
+
 ## 快速开始
 
 ### 支持的 AI 工具
@@ -124,6 +128,9 @@ AI 编程助手在处理复杂前端代码库时常常力不从心，因为 API
 #### 步骤 1：安装 CLI
 
 ```bash
+# 从 Npm 安装（推荐）
+npm install -g @localsummer/incspec
+
 # 从 GitHub 克隆并安装
 git clone https://github.com/localSummer/IncSpec.git
 cd IncSpec
@@ -186,6 +193,17 @@ $ incspec status                              # 检查当前工作流状态
 $ incspec analyze src/views/Home --complete   # 标记步骤 1 完成
 ```
 
+**使用现有基准报告** (跳过分析):
+
+如果已有基准报告文件，可直接使用，跳过分析步骤：
+```bash
+$ incspec analyze --baseline=home-baseline-v1.md   # 直接使用现有基准报告
+```
+- 自动搜索 `baselines/` 和 `archives/` 目录
+- 若文件在归档目录，自动移动到 `baselines/` 目录
+- 模块名自动从文件名推断 (`xxx-baseline-vN.md` -> `xxx`)
+- 可通过 `--module` 覆盖模块名
+
 #### 2. 收集结构化需求
 
 定义你想要的变更：
@@ -422,6 +440,7 @@ incspec help <command>    # 显示特定命令帮助
 incspec analyze <source-path> [--module=name]   # 别名：a
 incspec a src/views/Home --module=home
 incspec analyze src/views/Home --complete -o baselines/home-baseline-v1.md
+incspec analyze --baseline=home-baseline-v1.md  # 使用现有基准(自动从归档恢复)
 
 # 步骤 2：收集结构化需求
 incspec collect-req                             # 别名：cr

package/commands/analyze.mjs

@@ -3,6 +3,7 @@
  */
 
 import * as path from 'path';
+import * as fs from 'fs';
 import {
   ensureInitialized,
   INCSPEC_DIR,
@@ -32,6 +33,49 @@ import {
 
 const STEP_NUMBER = 1;
 
+/**
+ * Search for a file in the archives directory
+ * @param {string} projectRoot - Project root path
+ * @param {string} fileName - File name to search
+ * @returns {string|null} - Full path if found, null otherwise
+ */
+function findInArchives(projectRoot, fileName) {
+  const archivesDir = path.join(projectRoot, INCSPEC_DIR, DIRS.archives);
+  if (!fs.existsSync(archivesDir)) {
+    return null;
+  }
+
+  // Recursive search: archives/ -> YYYY-MM/ -> [module/] -> files
+  const monthDirs = fs.readdirSync(archivesDir, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name)
+    .sort()
+    .reverse(); // Prioritize recent months
+
+  for (const month of monthDirs) {
+    const monthPath = path.join(archivesDir, month);
+
+    // Check files directly in month directory
+    const directPath = path.join(monthPath, fileName);
+    if (fs.existsSync(directPath)) {
+      return directPath;
+    }
+
+    // Check module subdirectories
+    const subDirs = fs.readdirSync(monthPath, { withFileTypes: true })
+      .filter(d => d.isDirectory());
+
+    for (const subDir of subDirs) {
+      const subPath = path.join(monthPath, subDir.name, fileName);
+      if (fs.existsSync(subPath)) {
+        return subPath;
+      }
+    }
+  }
+
+  return null;
+}
+
 /**
  * Execute analyze command
  * @param {Object} ctx - Command context
@@ -42,6 +86,57 @@ export async function analyzeCommand(ctx) {
   // Ensure initialized
   const projectRoot = ensureInitialized(cwd);
 
+  // Handle --baseline option: use existing baseline report
+  if (options.baseline) {
+    const baselineFile = typeof options.baseline === 'string' ? options.baseline : '';
+    if (!baselineFile) {
+      printError('请指定基准报告文件名');
+      process.exit(1);
+    }
+
+    const baselinesDir = path.join(projectRoot, INCSPEC_DIR, DIRS.baselines);
+    const baselinePath = path.join(baselinesDir, baselineFile);
+    let fromArchive = false;
+
+    // 1. First check baselines directory
+    if (!fs.existsSync(baselinePath)) {
+      // 2. Search in archives directory
+      const archivePath = findInArchives(projectRoot, baselineFile);
+      if (!archivePath) {
+        printError(`基准文件不存在: ${baselineFile}`);
+        printInfo('已搜索 baselines/ 和 archives/ 目录');
+        process.exit(1);
+      }
+
+      // 3. Move to baselines directory
+      fs.renameSync(archivePath, baselinePath);
+      fromArchive = true;
+      printInfo(`已从归档恢复: ${path.relative(projectRoot, archivePath)}`);
+    }
+
+    // Infer module name from filename (xxx-baseline-vN.md -> xxx)
+    let moduleName = typeof options.module === 'string' ? options.module : '';
+    if (!moduleName) {
+      const match = baselineFile.match(/^(.+)-baseline-v\d+\.md$/);
+      moduleName = match ? match[1] : path.basename(baselineFile, '.md');
+    }
+
+    // Handle workflow state
+    let workflow = readWorkflow(projectRoot);
+    if (!workflow?.currentWorkflow) {
+      const workflowName = typeof options.workflow === 'string' ? options.workflow : `analyze-${moduleName}`;
+      workflow = startWorkflow(projectRoot, workflowName);
+      printSuccess(`已创建新工作流: ${workflowName}`);
+    }
+
+    // Mark step as completed
+    updateStep(projectRoot, STEP_NUMBER, STATUS.COMPLETED, baselineFile);
+    print('');
+    printSuccess(`已使用现有基准报告: ${baselineFile}`);
+    printInfo(`运行 'incspec status' 查看进度`);
+    return;
+  }
+
   // Get source path
   let sourcePath = args[0];
   if (!sourcePath) {

package/commands/help.mjs

@@ -34,12 +34,13 @@ const COMMANDS = {
     description: '显示当前工作流状态',
   },
   analyze: {
-    usage: 'incspec analyze <source-path> [--module=name]',
+    usage: 'incspec analyze <source-path> [--module=name] [--baseline=file]',
     aliases: ['a'],
     description: '步骤1: 分析代码流程，生成基线快照',
     options: [
       ['-m, --module=<name>', '指定模块名称'],
       ['-w, --workflow=<name>', '指定工作流名称(避免交互提示)'],
+      ['-b, --baseline=<file>', '使用现有基准报告(自动从归档恢复)'],
       ['--complete', '标记步骤完成'],
       ['-o, --output=<file>', '完成时指定输出文件'],
     ],

package/package.json

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

package/templates/AGENTS.md

@@ -41,10 +41,13 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
 
 ### 步骤 1: 分析代码工作流
 
-**命令**: `incspec analyze <source-path> [--module=name]`
+**命令**: `incspec analyze <source-path> [--module=name] [--baseline=file]`
 
 **目的**: 生成包含 API 调用时序图和依赖关系图的基线快照。
 
+**选项**:
+- `--baseline=<file>`: 使用现有基准报告，自动从 baselines/ 或 archives/ 目录恢复
+
 **输出**: `incspec/baselines/{module}-baseline-v{n}.md`
 
 **关键交付物**:
@@ -215,7 +218,7 @@ incspec list -l                 # 长格式(含时间戳)
 incspec list -a                 # 包含归档
 
 # 6步工作流
-incspec analyze <path> [--module=name]    # 步骤1: 基线分析
+incspec analyze <path> [--module=name] [--baseline=file]  # 步骤1: 基线分析
 incspec collect-req / cr                  # 步骤2: 需求收集
 incspec collect-dep / cd                  # 步骤3: 依赖收集
 incspec design [--feature=name] / d       # 步骤4: 增量设计

package/templates/cursor-commands/analyze-codeflow.md

@@ -1,6 +1,6 @@
 ---
 description: 分析代码工作流，生成带编号的API调用时序图、依赖关系图和依赖总结
-argument-hint: <source_path> [target_path]
+argument-hint: <source-path> [target-dir]
 allowed-tools: Glob, Grep, Read, Write, Bash
 ---
 
@@ -9,17 +9,33 @@ allowed-tools: Glob, Grep, Read, Write, Bash
 在开始分析前，先用 Bash 执行:
 
 ```bash
-incspec analyze <source_path> --module=<module> --workflow=analyze-<module>
+incspec analyze <source-path> --module=<module> --workflow=analyze-<module>
 ```
 
 完成报告写入后，再用 Bash 执行:
 
 ```bash
-incspec analyze <source_path> --module=<module> --workflow=analyze-<module> --complete --output=<output-file>
+incspec analyze <source-path> --module=<module> --workflow=analyze-<module> --complete --output=<output-file>
 ```
 
+**使用现有基准报告** (跳过分析):
+
+若已有基准报告文件，可直接使用:
+
+```bash
+incspec analyze --baseline=<baseline-file> [--module=<module>] [--workflow=<workflow>]
+```
+
+说明:
+- `<baseline-file>` 文件名，自动搜索 baselines/ 和 archives/ 目录
+- 若文件在归档目录，自动移动到 baselines/ 目录
+- `<module>` 默认从文件名推断 (xxx-baseline-vN.md -> xxx)
+- `<workflow>` 默认为 analyze-<module>
+
+---
+
 说明:
-- `<module>` 默认为 source_path 最后一级目录名，若用户显式指定模块名则使用该值
+- `<module>` 默认为 source-path 最后一级目录名，若用户显式指定模块名则使用该值
 - `<output-file>` 必须与最终写入的文件名一致
 - 若 incspec 提示未初始化，请先运行 `incspec init`
 
@@ -29,19 +45,19 @@ incspec analyze <source_path> --module=<module> --workflow=analyze-<module> --co
 
 你需要完成以下任务：
 
-1. **代码分析**：检查 source_path 目录下的所有组件和Store文件，识别初始化阶段的API调用
+1. **代码分析**：检查 source-path 目录下的所有组件和Store文件，识别初始化阶段的API调用
 2. **时序图绘制**：构建带编号的API调用时序图，展示调用顺序
 3. **依赖图绘制**：构建带编号的API依赖关系图，展示依赖关系
 4. **依赖总结**：生成带编号的依赖关系文字总结
-5. **Markdown输出**：将分析结果输出到 target_path 目录
+5. **Markdown输出**：将分析结果输出到 target-dir 目录
 
 **重要提示**：默认情况下，只输出上述核心分析内容。只有在用户明确要求提供"潜在问题与优化建议"时，才在文档末尾添加该部分内容。
 
 ## 输出配置
 
-- **target_path**: 报告输出目录，默认 `incspec/baselines`
+- **target-dir**: 报告输出目录，默认 `incspec/baselines`
 - **文件命名**: `{module}-baseline-v{n}.md`
-  - `{module}`: 模块名称，从 source_path 的最后一级目录名推断，或由用户指定
+  - `{module}`: 模块名称，从 source-path 的最后一级目录名推断，或由用户指定
   - `{n}`: 版本号，扫描目标目录中同名前缀的文件，取最大版本号+1，若无则为 1
 - **示例**: 分析 `src/views/resume` 目录，输出 `incspec/baselines/resume-baseline-v1.md`
 
@@ -69,7 +85,7 @@ incspec analyze <source_path> --module=<module> --workflow=analyze-<module> --co
 
 ### 第一步：代码扫描
 
-- 使用 Glob 工具扫描 source_path 目录下的所有文件
+- 使用 Glob 工具扫描 source-path 目录下的所有文件
 - 关注文件类型：
   - 组件文件（.jsx, .tsx, .js, .ts）
   - Store文件（Zustand, MobX等）
@@ -116,7 +132,7 @@ incspec analyze <source_path> --module=<module> --workflow=analyze-<module> --co
 # [模块名称] API工作流分析
 
 **分析时间**: [自动生成的时间戳]
-**分析范围**: [source_path的相对路径或绝对路径]
+**分析范围**: [source-path的相对路径或绝对路径]
 
 ## 概述
 
@@ -271,8 +287,8 @@ graph TD
 
 ## 工作流程
 
-1. **确认路径**：验证 source_path 和 target_path 的有效性
-2. **生成元信息**：记录分析时间（使用当前时间戳）和分析范围（source_path）
+1. **确认路径**：验证 source-path 和 target-dir 的有效性
+2. **生成元信息**：记录分析时间（使用当前时间戳）和分析范围（source-path）
 3. **扫描目录**：使用 Glob 工具获取所有相关文件
 4. **分析文件**：使用 Read 工具逐个分析文件中的API调用
 5. **构建模型**：在内存中构建完整的API调用关系模型
@@ -280,7 +296,7 @@ graph TD
 7. **生成图表**：使用Mermaid语法创建带编号的可视化图表
 8. **编写文档**：按照规范格式生成Markdown文档（包含元信息和三个核心部分）
 9. **可选增强**：仅当用户明确要求时，在文档末尾添加"潜在问题与优化建议"部分
-10. **保存输出**：使用 Write 工具保存到 target_path
+10. **保存输出**：使用 Write 工具保存到 target-dir
 
 ## 质量标准
 

package/templates/cursor-commands/analyze-increment-codeflow.md

@@ -1,6 +1,6 @@
 ---
 description: 基于现状、需求和依赖,生成增量需求的设计蓝图(时序、依赖、文件变更),指导代码生成
-argument-hint: [旧需求快照] [结构化需求] [UI依赖报告] [report-output-dir]
+argument-hint: [baseline-snapshot-path] [structured-requirements-path] [ui-dependencies-path] [report-output-dir]
 allowed-tools: Glob, Grep, Read, Write, Bash
 ---
 
@@ -31,9 +31,9 @@ incspec design --feature=<feature> --complete --output=<output-file>
 
 接收以下三份材料(由用户提供或从指定文件读取):
 
-1. **旧需求快照**(来自 `analyze-codeflow`): 包含 S1~Sxx 时序编号、Dxx 依赖节点、Rxx 关系总结
-2. **结构化需求描述**(来自 `structured-requirements-collection`): 包含新增/修改功能、触发条件、核心状态、数据流向的 5 列表格
-3. **UI依赖采集报告**(来自 `ui-dependency-collection`): 包含依赖类型、来源路径、变更类型的依赖详情表
+1. **baseline-snapshot-path** (来自 `analyze-codeflow`): 包含 S1~Sxx 时序编号、Dxx 依赖节点、Rxx 关系总结
+2. **structured-requirements-path** (来自 `structured-requirements-collection`): 包含新增/修改功能、触发条件、核心状态、数据流向的 5 列表格
+3. **ui-dependencies-path** (来自 `ui-dependency-collection`): 包含依赖类型、来源路径、变更类型的依赖详情表
 
 # 执行流程
 

package/templates/cursor-commands/merge-to-baseline.md

@@ -1,6 +1,6 @@
 ---
 description: 将增量需求报告融合为新的代码流基线快照
-argument-hint: <increment-report-path> [baseline-output-path]
+argument-hint: <increment-report-path> [baseline-output-dir]
 allowed-tools: Read, Write, Bash
 ---
 
@@ -38,7 +38,7 @@ incspec merge <increment-report-path> --complete --output=<output-file>
 # 输入参数
 
 1. **increment-report-path** (必填): 增量需求融合快照报告的完整路径（如 increment-codeflow-v2.md）
-2. **baseline-output-path** (可选): 新基线报告的输出路径，默认为 `<原文件名>-baseline.md`
+2. **baseline-output-dir** (可选): 新基线报告的输出路径，默认为 `<原文件名>-baseline.md`
 
 # 执行流程
 
@@ -202,7 +202,7 @@ D3_DEL (删除) -> 已移除
 - 新基线总节点: N 个
 
 📁 输出文件:
-  ✓ <baseline-output-path>
+  ✓ <baseline-output-dir>
 
 🔄 下一步操作:
 1. 检查新基线报告的完整性
@@ -268,7 +268,7 @@ D3_DEL (删除) -> 已移除
 
 ## 输出目录
 
-- **baseline-output-path**: 默认为 `incspec/baselines`
+- **baseline-output-dir**: 默认为 `incspec/baselines`
 - 如目录不存在,需主动创建
 
 ## 文件命名