@localsummer/incspec 0.0.6 → 0.0.8

package/templates/cursor-commands/apply-increment-code.md

@@ -6,6 +6,14 @@ allowed-tools: Read, Write, Edit, Bash, Grep, Glob
 
 ## CLI 同步 (自动)
 
+**检测工作流模式:**
+
+```bash
+incspec status
+```
+
+### 完整模式 (7步)
+
 开始执行前，先用 Bash 执行:
 
 ```bash
@@ -22,17 +30,45 @@ incspec apply <increment-report-path> [--source-dir=<source-code-dir>] --complet
 - 若未提供 `source-code-dir`，省略 `--source-dir`
 - 若提示没有活跃工作流，请先完成步骤 1-4
 
+### 快速模式 (5步)
+
+快速模式下，输入文件为需求文档（而非增量设计文件）：
+
+```bash
+incspec apply --complete
+```
+
+说明:
+- 输入文件自动使用 `incspec/requirements/structured-requirements.md`
+- 无需提供增量设计文件路径
+- 请先完成步骤 1-2
+
 # 角色定位
 
-你是前端增量代码执行器。基于《增量需求融合快照》报告,在 source-code-dir 中直接创建新文件和修改现有文件,完成增量需求的代码实施。
+你是前端增量代码执行器。根据工作流模式，基于不同的输入文件在 source-code-dir 中直接创建新文件和修改现有文件，完成增量需求的代码实施。
+
+## 模式说明
+
+- **完整模式**: 基于《增量需求融合快照》报告（步骤 4 产出）执行代码变更
+- **快速模式**: 基于《结构化需求报告》（步骤 2 产出）直接执行代码变更，跳过增量设计步骤
 
 # 输入参数
 
+## 完整模式
+
 1. **increment-report-path** (必填): `increment-codeflow-v2.md` 报告的完整路径
 2. **source-code-dir** (可选): 源代码根目录,默认为当前工作目录
 
+## 快速模式
+
+1. **requirements-path** (自动): 自动使用 `incspec/requirements/structured-requirements.md`
+2. **baseline-path** (自动): 自动使用步骤 1 生成的基线报告
+3. **source-code-dir** (可选): 源代码根目录,默认为当前工作目录
+
 # 执行流程
 
+> 以下为完整模式的执行流程。快速模式流程请参见 [快速模式执行流程](#快速模式执行流程) 部分。
+
 ## 步骤 1: 读取并解析报告
 
 读取 increment-report-path 指定的报告文件,提取以下关键信息:
@@ -390,3 +426,95 @@ old_string: `interface ListState {
    - Edit 工具修改: 在 JSX 中添加 BatchActions 组件
 
 执行完成后输出摘要。
+
+---
+
+# 快速模式执行流程
+
+快速模式下，无需解析增量设计报告的模块 3/4/5，直接基于需求文档和基线报告执行代码变更。
+
+## 输入文件
+
+1. **基线报告**: 步骤 1 生成的 `{module}-baseline-v{n}.md`（理解现有代码结构）
+2. **需求文档**: 步骤 2 生成的 `structured-requirements.md`（明确变更目标）
+
+## 执行步骤
+
+### 步骤 1: 读取输入文件
+
+1. **读取基线报告**: 从 `incspec/baselines/` 获取最新的基线快照
+   - 理解当前代码架构
+   - 识别现有 API 调用流程
+   - 识别现有依赖关系
+
+2. **读取需求文档**: 从 `incspec/requirements/structured-requirements.md` 获取结构化需求
+   - 提取 5 列结构化表格
+   - 明确变更目标和影响范围
+
+### 步骤 2: 分析变更影响
+
+基于基线报告和需求文档，分析变更影响：
+
+1. **识别影响的组件**: 根据需求表格中的"涉及的 UI 组件"列
+2. **识别影响的状态**: 根据需求表格中的"影响的核心状态"列
+3. **理解数据流向**: 根据需求表格中的"预期数据流向"列
+4. **确定变更范围**: 结合基线报告中的依赖关系
+
+### 步骤 2.5: 执行前确认
+
+在开始执行变更前，必须向用户确认：
+
+```
+⚠️ 即将在 <source-code-dir> 中执行代码变更（快速模式）
+
+📋 变更计划:
+- 基于需求: incspec/requirements/structured-requirements.md
+- 参考基线: incspec/baselines/{module}-baseline-v{n}.md
+- 预计变更: 新建 X 个文件，修改 Y 个文件
+
+🔴 风险提示:
+- 快速模式跳过了增量设计步骤，变更未经详细设计审查
+- 建议: 请确保当前代码已提交到 git 或已备份
+
+是否继续执行? (yes/no)
+```
+
+仅在用户明确同意后才开始执行。
+
+### 步骤 3: 直接执行代码变更
+
+按照需求文档的描述，直接在源代码目录执行变更：
+
+1. **搜索参考文件**: 在 source-code-dir 中查找同类型的现有文件
+2. **读取参考文件**: 学习项目代码风格和模式
+3. **执行变更**: 使用 Write/Edit 工具创建或修改文件
+4. **验证完整性**: 确保所有依赖正确引入
+
+### 步骤 4: 输出变更摘要
+
+```
+✅ 快速模式代码变更已完成
+
+📊 变更统计:
+- 新建文件: X 个
+- 修改文件: Y 个
+- 删除代码: Z 处
+
+📁 变更文件清单:
+  ✓ src/components/NewFeature.tsx (新建)
+  ✓ src/store/featureStore.ts (修改)
+
+🧪 建议的后续操作:
+1. 运行 TypeScript 编译检查: npx tsc --noEmit
+2. 运行测试: npm test
+3. 手动验证功能是否正确实现
+```
+
+## 快速模式 vs 完整模式
+
+| 对比项 | 完整模式 | 快速模式 |
+|-------|---------|---------|
+| 输入文件 | 增量设计报告 (模块 2-5) | 需求文档 + 基线报告 |
+| 变更规划 | 详细的变更链条设计 | 基于需求直接分析 |
+| 适用场景 | 复杂功能、多组件交互 | Bug 修复、简单功能 |
+| 风险程度 | 低（经过详细设计） | 中（跳过设计阶段） |

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

@@ -6,6 +6,14 @@ allowed-tools: Read, Write, Bash
 
 ## CLI 同步 (自动)
 
+**检测工作流模式:**
+
+```bash
+incspec status
+```
+
+### 完整模式 (7步)
+
 开始执行前，先用 Bash 执行:
 
 ```bash
@@ -22,9 +30,27 @@ incspec merge <increment-report-path> --complete --output=<output-file>
 - `<output-file>` 必须与最终写入的文件名一致
 - 若提示没有活跃工作流，请先完成步骤 1-5
 
+### 快速模式 (5步)
+
+快速模式下，不依赖增量设计报告，直接重新分析当前代码生成新基线：
+
+```bash
+incspec merge --complete --output=<output-file>
+```
+
+说明:
+- 快速模式下无需提供增量设计报告路径
+- 实际执行的是对当前代码的重新分析
+- 请先完成步骤 1-2 和步骤 5 (应用代码变更)
+
 # 角色定位
 
-你是增量基线融合专家。你的职责是将增量需求融合快照报告（包含新增、修改、删除标记）转换为干净的基线快照报告，作为下一轮增量迭代的起点。
+你是增量基线融合专家。根据工作流模式执行不同的融合策略。
+
+## 模式说明
+
+- **完整模式**: 将增量需求融合快照报告（步骤 4 产出）转换为干净的基线快照报告
+- **快速模式**: 重新分析当前代码状态（已应用变更后），生成新版本基线快照
 
 # 核心目标
 
@@ -327,3 +353,63 @@ D3_DEL (删除) -> 已移除
 ---
 
 记住：你的目标是生成一个干净的、无增量标记的基线快照报告，它应该看起来就像是对当前代码直接执行 analyze-codeflow 分析得到的结果，为下一轮增量迭代提供可靠的对比基准。
+
+---
+
+# 快速模式执行流程
+
+快速模式下，合并步骤实际是"重新分析"：不依赖增量设计报告，而是直接分析当前代码状态生成新基线。
+
+## 核心区别
+
+| 对比项 | 完整模式 | 快速模式 |
+|-------|---------|---------|
+| 输入文件 | 增量设计报告 | 无（直接分析代码） |
+| 执行逻辑 | 清理增量标记、重新编号 | 重新执行 analyze-codeflow |
+| 产出 | 融合后的基线 | 全新的基线快照 |
+
+## 执行步骤
+
+### 步骤 1: 确认代码变更已完成
+
+确保步骤 5 (应用代码变更) 已完成，代码库处于变更后的状态。
+
+### 步骤 2: 获取分析范围
+
+从当前工作流状态中获取：
+- 原始分析的源代码路径 (source-path)
+- 模块名称 (module)
+
+### 步骤 3: 重新执行代码分析
+
+使用 analyze-codeflow.md 的分析方法，对当前代码状态进行完整分析：
+
+1. **扫描代码目录**: 识别所有组件、Store、API 调用
+2. **构建时序图**: 生成新的 API 调用时序图（S1, S2, S3...）
+3. **构建依赖图**: 生成新的依赖关系图（D1, D2, D3...）
+4. **总结依赖关系**: 生成新的依赖关系总结（R1, R2, R3...）
+
+### 步骤 4: 输出新基线
+
+- **输出目录**: `incspec/baselines/`
+- **文件命名**: `{module}-baseline-v{n+1}.md`（版本号递增）
+- **元信息**: 标注为"由快速模式工作流生成"
+
+### 步骤 5: 输出摘要
+
+```
+✅ 快速模式基线生成已完成
+
+📊 分析统计:
+- 时序步骤: X 个 (S1-SX)
+- 依赖节点: Y 个 (D1-DY)
+- 依赖关系: Z 组 (R1-RZ)
+
+📁 输出文件:
+  ✓ incspec/baselines/{module}-baseline-v{n+1}.md
+
+🔄 下一步操作:
+1. 检查新基线报告的完整性
+2. 运行 `incspec archive --yes` 归档当前工作流
+3. 此基线将作为下一轮增量分析的起点
+```

package/templates/cursor-commands/structured-requirements-collection.md

@@ -99,6 +99,12 @@ incspec collect-req --complete
 4. **完成提示**: 文件写入后,在对话中仅输出一行字:
    > "✅ 结构化需求描述已全部收齐并写入文件,可直接用于后续增量 Diff 分析。"
 
+## 快速模式提示
+
+若当前工作流为快速模式 (通过 `incspec status` 确认)，完成需求收集后输出:
+
+> "✅ 结构化需求已收齐。快速模式下，直接运行 `incspec apply` 进入代码应用阶段。"
+
 # 示例交互
 
 **用户**: "我想在简历列表的操作列加一个下载按钮。"

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

@@ -0,0 +1,286 @@
+---
+name: inc-spec-skill
+description: 设计优先的前端功能增量编码工作流。适用于实现新UI组件、修改现有功能，或当用户提及"增量编码"、"代码流程分析"、"需求收集"，以及需要带有API/Store依赖追踪的结构化功能开发时使用。
+---
+
+# AI增量编码
+
+## 目录
+
+- [快速开始](#快速开始)
+- [工作流概览](#工作流概览)
+- [CLI集成](#cli集成)
+- [步骤详情](#步骤详情)
+- [最佳实践](#最佳实践)
+- [参考资源](#参考资源)
+
+## 快速开始
+
+**完整模式 (7步):**
+```
+1. 分析现有代码    → incspec analyze <path>
+2. 收集需求        → incspec collect-req
+3. 收集依赖        → incspec collect-dep
+4. 设计增量        → incspec design
+5. 应用代码变更    → incspec apply <report>
+6. 合并到基线      → incspec merge <report>
+7. 归档工作流      → incspec archive --yes
+```
+
+**快速模式 (5步):**
+```
+1. 分析现有代码    → incspec analyze <path> --quick
+2. 收集需求        → incspec collect-req
+3. 应用代码变更    → incspec apply (基于需求文档)
+4. 合并到基线      → incspec merge (重新分析生成)
+5. 归档工作流      → incspec archive --yes
+```
+
+首次使用前初始化: `incspec init`
+
+## 执行规则
+
+当用户请求满足以下条件时，**直接开始执行**，无需搜索确认:
+- 明确指定了模式（完整/快速）
+- 提供了目标路径或基线文件
+- 意图清晰无歧义
+
+**默认行为**:
+- 未指定模式时，默认使用完整模式
+- 提供 `--baseline=<file>` 时，跳过步骤1的代码分析，直接使用已有基线
+- 提供 `--quick` 时，启用快速模式流程
+- 选项可自由组合，Agent 应根据用户意图推断最优组合
+
+## 工作流概览
+
+### 完整模式 (7步)
+
+适用于复杂功能开发，需要完整的 UI 依赖分析和增量设计。
+
+| 步骤 | 目的 | 产出 |
+|------|------|------|
+| 1. 代码流程分析 | 记录当前API/Store/组件交互 | 基线快照 |
+| 2. 需求收集 | 将模糊需求转换为结构化5列表格 | 需求报告 |
+| 3. 依赖收集 | 识别所有API/Store/类型依赖 | 依赖报告 |
+| 4. 增量设计 | 生成实现蓝图 | 增量快照 |
+| 5. 代码应用 | 按蓝图创建/修改文件 | 更新后的代码库 |
+| 6. 基线合并 | 将增量转换为干净基线 | 新基线 |
+| 7. 归档 | 归档工作流产出到 `archives/YYYY-MM/` | 干净的工作区 |
+
+### 快速模式 (5步)
+
+适用于简单功能或不涉及复杂 UI 依赖的变更。
+
+| 步骤 | 目的 | 产出 |
+|------|------|------|
+| 1. 代码流程分析 | 记录当前API/Store/组件交互 | 基线快照 |
+| 2. 需求收集 | 将模糊需求转换为结构化5列表格 | 需求报告 |
+| 5. 代码应用 | 基于需求直接创建/修改文件 | 更新后的代码库 |
+| 6. 基线合并 | 重新分析生成新基线 | 新基线 |
+| 7. 归档 | 归档工作流产出 | 干净的工作区 |
+
+**模式选择建议:**
+- **完整模式**: 复杂 UI 功能、多组件交互、需要详细设计审查
+- **快速模式**: Bug 修复、简单功能、不涉及 UI 依赖变更
+
+## CLI集成
+
+每个步骤与 `incspec` CLI同步以跟踪工作流状态:
+
+| 步骤 | 开始 | 完成 |
+|------|------|------|
+| 分析 | `incspec analyze <path> --module=<m>` 或 `--baseline=<file>` | `--complete --output=<file>` |
+| 需求 | `incspec collect-req` | `--complete` |
+| 依赖 | `incspec collect-dep` | `--complete` |
+| 设计 | `incspec design --feature=<f>` | `--complete --output=<file>` |
+| 应用 | `incspec apply <report>` | `--complete` |
+| 合并 | `incspec merge <report>` | `--complete --output=<file>` |
+| 归档 | `incspec archive --yes` | - |
+
+管理命令:
+- `incspec status` - 查看工作流状态
+- `incspec list` - 列出规范文件
+- `incspec validate` - 验证项目健康状态
+
+## 步骤详情
+
+### 步骤1: 代码流程分析
+
+分析现有代码，创建API调用、依赖关系和组件交互的文档化基线。
+
+**命令:** `incspec analyze <path> [--module=<m>] [--quick] [--baseline=<file>]`
+
+**选项:**
+- `--quick`: 启用快速模式 (5步流程)
+- `--baseline=<file>`: 复用已有基线，跳过代码分析
+
+**输入:** 源代码目录路径 (如 `src/pages/dashboard`) 或现有基线文件 (`--baseline=<file>`)
+
+**输出:** 基线报告，包含:
+- 编号的API调用序列图 (如 `[1]`、`[2]`)
+- 组件/Store依赖关系图
+- 数据流摘要
+
+详见 [references/analyze-codeflow.md](references/analyze-codeflow.md)。
+
+### 步骤2: 需求收集
+
+将模糊的用户需求转换为严格的5列结构化表格，消除所有歧义术语。
+
+**输入:** 用户的非正式需求描述
+
+**输出:** 结构化表格，包含以下列:
+1. 需求ID
+2. 详细描述 (不含"某些"、"相关"等模糊术语)
+3. 验收标准
+4. 依赖项
+5. 实现备注
+
+详见 [references/structured-requirements-collection.md](references/structured-requirements-collection.md)。
+
+### 步骤3: 依赖收集
+
+在代码生成前识别所有上下文依赖。
+
+**输入:** 步骤2的结构化需求
+
+**输出:** 完整的依赖清单:
+- **API:** 端点、方法、请求/响应类型
+- **Store:** 模块、状态属性、actions
+- **类型:** 现有和新增的TypeScript接口
+- **组件:** 共享组件、工具函数
+
+详见 [references/ui-dependency-collection.md](references/ui-dependency-collection.md)。
+
+### 步骤4: 增量设计
+
+基于当前状态、需求和依赖生成实现蓝图。**设计获批前不编写任何代码。**
+
+**输入:** 基线(步骤1) + 需求(步骤2) + 依赖(步骤3)
+
+**输出:** 增量快照，包含:
+- 集成新调用的API序列图
+- 文件修改计划 (新增/修改/删除)
+- 分步实现指导
+
+详见 [references/analyze-increment-codeflow.md](references/analyze-increment-codeflow.md)。
+
+### 步骤5: 代码应用
+
+通过创建新文件和修改现有文件执行增量蓝图。
+
+**输入:** 步骤4的增量快照 + 源代码目录
+
+**输出:** 修改后的代码库:
+- 按蓝图创建的新文件
+- 更新的现有文件
+- 正确的导入和类型定义
+
+详见 [references/apply-increment-code.md](references/apply-increment-code.md)。
+
+### 步骤6: 基线合并
+
+将增量快照(带有新增/修改/删除标记)转换为干净基线，为下次迭代做准备。
+
+**输入:** 步骤4的增量快照
+
+**输出:** 代表当前系统状态的干净基线(无增量标记)
+
+详见 [references/merge-to-baseline.md](references/merge-to-baseline.md)。
+
+### 步骤7: 归档
+
+将已完成的工作流产出归档到 `archives/YYYY-MM/{module}/` 目录。
+
+**输入:** 要归档的文件(可选，默认为当前工作流)
+
+**操作:**
+```bash
+incspec archive --yes              # 归档所有工作流产出
+incspec archive <file> --yes       # 归档指定文件
+incspec archive <file> --keep      # 复制而非移动
+```
+
+详见 [references/inc-archive.md](references/inc-archive.md)。
+
+## 最佳实践
+
+**顺序执行:** 按步骤顺序执行。完整模式按 1-7 执行，快速模式按 1-2-5-6-7 执行。跳过步骤会导致集成问题。
+
+**设计先于编码:** 完整模式下，步骤4设计获批前不编写任何代码。快速模式跳过设计步骤，适用于简单变更。
+
+**不可跳过依赖:** 完整模式下，遗漏依赖(步骤3)是集成失败的首要原因。
+
+**CLI同步:** 始终与 `incspec` CLI同步以保证工作流可追溯。
+
+**模式选择:**
+- 不确定时优先选择完整模式
+- 仅在变更范围明确、不涉及复杂依赖时使用快速模式
+
+**验证节点:**
+- 步骤2后: 需求中无模糊术语
+- 步骤4后 (完整模式): 编码前审查蓝图
+- 步骤5后: 验证所有文件已正确创建/修改
+- 步骤7后: 确认工作区已清理
+
+**关键人工确认点:**
+- 完整模式: 步骤2后 + 步骤4后
+- 快速模式: 步骤2后 (需求确认后才能开始编码)
+
+## 常见陷阱
+
+| 陷阱 | 后果 |
+|------|------|
+| 跳过代码流程分析 | 集成问题，返工 |
+| 接受模糊需求 | 编码时发现歧义 |
+| 遗漏依赖 | 导入错误，运行时失败 |
+| 编码先于设计 | 在不符合架构的实现上浪费精力 |
+| 跳过基线合并 | 对当前系统状态产生混淆 |
+| 忽略归档 | 工作区杂乱，历史丢失 |
+
+## 参考资源
+
+| 文件 | 用途 |
+|------|------|
+| [analyze-codeflow.md](references/analyze-codeflow.md) | 代码流程分析和API序列图 |
+| [structured-requirements-collection.md](references/structured-requirements-collection.md) | 5列需求结构化 |
+| [ui-dependency-collection.md](references/ui-dependency-collection.md) | API/Store/类型依赖收集 |
+| [analyze-increment-codeflow.md](references/analyze-increment-codeflow.md) | 设计优先的增量蓝图 |
+| [apply-increment-code.md](references/apply-increment-code.md) | 基于蓝图的代码应用 |
+| [merge-to-baseline.md](references/merge-to-baseline.md) | 增量到基线转换 |
+| [inc-archive.md](references/inc-archive.md) | 工作流产出归档 |
+
+## 使用示例
+
+**任务:** 为产品仪表板添加筛选功能
+
+```
+步骤1: 分析产品仪表板代码流程
+       → 记录当前数据获取、store结构、API端点
+
+步骤2: 结构化筛选需求
+       → 将"添加一些筛选器"转换为具体筛选类型(类别、价格、评分)
+       → 定义确切行为和组合逻辑(AND/OR)
+
+步骤3: 收集依赖
+       → 识别筛选API端点、store扩展、共享筛选组件
+
+步骤4: 生成增量蓝图
+       → 规划FilterPanel集成、状态管理变更、文件修改
+
+步骤5: 应用增量
+       → 创建FilterPanel组件，修改ProductDashboard，更新store
+
+步骤6: 合并到基线
+       → 生成新仪表板状态的干净快照
+
+步骤7: 归档
+       → 归档工作流产出，为下次增量做准备(如添加排序功能)
+```
+
+## 开发工作流集成
+
+- **版本控制:** 步骤7(完整周期)后提交
+- **代码审查:** 在步骤4审查增量蓝图
+- **测试:** 在步骤5添加测试
+- **文档:** 在步骤6更新文档