@localsummer/incspec 0.0.4 → 0.0.5

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.5",
   "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

@@ -18,6 +18,22 @@ incspec analyze <source_path> --module=<module> --workflow=analyze-<module>
 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 最后一级目录名，若用户显式指定模块名则使用该值
 - `<output-file>` 必须与最终写入的文件名一致