@localsummer/incspec 0.0.6 → 0.0.7

package/templates/inc-spec-skill/references/apply-increment-code.md

@@ -0,0 +1,392 @@
+---
+description: 根据增量需求融合快照报告在源代码目录中直接生成和修改文件
+argument-hint: <increment-report-path> [source-code-dir]
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+## CLI 同步 (自动)
+
+开始执行前，先用 Bash 执行:
+
+```bash
+incspec apply <increment-report-path> [--source-dir=<source-code-dir>]
+```
+
+完成代码变更后，再用 Bash 执行:
+
+```bash
+incspec apply <increment-report-path> [--source-dir=<source-code-dir>] --complete
+```
+
+说明:
+- 若未提供 `source-code-dir`，省略 `--source-dir`
+- 若提示没有活跃工作流，请先完成步骤 1-4
+
+# 角色定位
+
+你是前端增量代码执行器。基于《增量需求融合快照》报告,在 source-code-dir 中直接创建新文件和修改现有文件,完成增量需求的代码实施。
+
+# 输入参数
+
+1. **increment-report-path** (必填): `increment-codeflow-v2.md` 报告的完整路径
+2. **source-code-dir** (可选): 源代码根目录,默认为当前工作目录
+
+# 执行流程
+
+## 步骤 1: 读取并解析报告
+
+读取 increment-report-path 指定的报告文件,提取以下关键信息:
+
+- **模块 2: 完整的变更链条设计表** - 获取所有变更编号 (C1, C2...) 及其变更逻辑说明
+- **模块 3: 规划后的 API 调用时序图** - 解析 Mermaid 时序图,确认变更链路:
+  - 识别所有 🆕 标记的新增步骤 [N1], [N2]...
+  - 识别所有 ✏️ 标记的修改步骤 [S1-Modified], [S2-Modified]...
+  - 识别所有 ❌ 标记的删除步骤 [S3-Deleted]...
+  - 理解每个变更在运行时序中的执行顺序和上下文位置
+- **模块 4: 规划后的依赖关系图** - 解析 Mermaid 依赖图,确认依赖关系:
+  - 识别所有 🆕 新增节点 (N1, N2...) 及其依赖关系
+  - 识别所有 ✏️ 修改节点 (D1_MOD, D2_MOD...) 及其新增/修改的依赖链路
+  - 识别所有 ❌ 删除节点 (D3_DEL...) 及其需要移除的依赖
+  - 构建完整的依赖拓扑图,用于后续的排序和验证
+- **模块 5: 完整的新增/修改文件清单** - 获取操作类型、文件路径和详细修改内容
+
+## 步骤 2: 按依赖顺序排序变更
+
+综合利用三个来源的信息,进行精确的依赖排序:
+
+### 2.1 依赖关系分析
+
+基于步骤 1 解析的信息,构建变更的依赖拓扑:
+
+1. **从模块 4 提取依赖关系**:
+   - 分析依赖图中的箭头方向 (A → B 表示 B 依赖 A)
+   - 识别新增节点之间的依赖链 (如 N2 -.-> N1)
+   - 识别修改节点与新增节点的依赖关系 (如 D2_MOD -.-> N1)
+   - 记录需要先创建的基础依赖
+
+2. **从模块 3 提取时序约束**:
+   - 分析时序图中的消息流向 (调用者 → 被调用者)
+   - 确认每个 [Nx] 节点在运行时的先后顺序
+   - 识别同步调用和异步调用的时序关系
+   - 确保被调用的方法/组件先于调用者定义
+
+3. **从模块 2 提取逻辑依赖**:
+   - 分析"关联旧节点"列,确定变更的起点
+   - 分析"变更逻辑说明",识别隐含的依赖 (如"调用 API"意味着依赖 API 定义)
+   - 提取文件路径,按文件类型分层
+
+### 2.2 排序规则
+
+按以下优先级进行拓扑排序:
+
+1. **架构分层优先** (从底层到上层):
+   - Types/Interfaces → Utils → API → Store → Component
+   - 基础设施 → 业务逻辑 → UI 展示
+
+2. **依赖拓扑优先**:
+   - 无依赖的节点优先 (入度为 0)
+   - 依赖已完成节点的变更次之
+   - 确保不存在循环依赖
+
+3. **时序约束优先**:
+   - 在时序图中先出现的定义先生成
+   - 被调用方先于调用方
+
+4. **变更编号顺序**:
+   - 同优先级的变更按 C1, C2, C3... 顺序执行
+
+### 2.3 验证与调整
+
+排序完成后,进行验证:
+
+- **循环依赖检测**: 如发现循环依赖,报告错误并中止
+- **完整性检查**: 确保所有 Cx 变更都被排序
+- **逻辑一致性**: 验证排序结果与时序图、依赖图的一致性
+
+## 步骤 3: 执行代码变更
+
+按排序后的顺序逐个执行变更,根据操作类型使用不同的工具:
+
+### 3.1 新建文件 (使用 Write 工具)
+
+对于操作类型为"新建"的变更:
+
+1. **搜索参考文件**: 在 source-code-dir 中查找同类型的现有文件
+   - 新建组件 → 搜索 `**/*.tsx` 找相似组件
+   - 新建 Store → 搜索 `**/store/*.ts` 或 `**/stores/*.ts`
+   - 新建 API → 搜索 `**/api/*.ts` 或 `**/services/*.ts`
+   - 新建类型定义 → 搜索 `**/types/*.ts` 或 `**/*.d.ts`
+
+2. **读取参考文件**: 使用 Read 工具读取 1-2 个最相关的参考文件,学习:
+   - Import 语句的组织方式
+   - 代码风格和格式化规范
+   - 命名约定 (camelCase/PascalCase)
+   - 注释风格
+   - 项目特定的模式和惯用法
+
+3. **生成完整代码**: 基于报告模块 5 的"详细修改内容 (Code Spec)"和参考文件:
+   - 按参考文件的风格组织 import 语句
+   - 包含完整的 TypeScript 类型定义
+   - 实现报告中描述的所有功能点
+   - 添加必要的错误处理逻辑
+   - 保持与项目一致的代码风格
+
+4. **确保目录存在**: 如果目标文件的目录不存在,先创建目录
+   ```bash
+   mkdir -p $(dirname <target-file-path>)
+   ```
+
+5. **写入文件**: 使用 Write 工具将生成的代码写入 `source-code-dir/<目标文件路径>`
+
+### 3.2 修改文件 (使用 Edit 工具)
+
+对于操作类型为"修改"的变更:
+
+1. **读取原文件**: 使用 Read 工具读取 `source-code-dir/<目标文件路径>` 的完整内容
+
+2. **定位修改点**: 根据报告模块 5 的"详细修改内容 (Code Spec)"和模块 2 的"变更逻辑说明",确定需要修改的代码位置:
+   
+   **常见修改模式**:
+   
+   - **新增 State 字段**:
+     - 定位到 interface/type 定义
+     - 在合适位置添加新字段及其类型
+   
+   - **新增 Action/Method**:
+     - 定位到 class 或 object 定义
+     - 在合适位置添加新方法
+     - 确保方法签名完整 (参数、返回值类型)
+   
+   - **修改数据处理逻辑**:
+     - 定位到具体的函数或方法
+     - 在数据解析/转换的位置添加新字段处理
+   
+   - **新增 Effect/Hook**:
+     - 定位到组件内部
+     - 添加 useEffect/useCallback 等 Hook
+   
+   - **新增 Import**:
+     - 定位到文件顶部的 import 区域
+     - 按项目的 import 排序规则添加
+
+3. **执行精准修改**: 使用 Edit 工具进行修改
+   - 找到需要修改的代码块 (包含足够的上下文以确保唯一性)
+   - 指定 old_string (要替换的代码)
+   - 指定 new_string (替换后的代码)
+   - 如果是重命名变量等全局替换,使用 `replace_all: true`
+
+4. **分步修改**: 如果一个文件有多处修改:
+   - 按从上到下的顺序逐个执行 Edit
+   - 每次 Edit 后重新读取文件,确认修改成功
+   - 避免多个 old_string 重叠导致冲突
+
+### 3.3 删除代码 (使用 Edit 工具)
+
+对于操作类型为"删除"的变更:
+
+1. **读取原文件**: 确认要删除的代码确实存在
+2. **精准删除**: 使用 Edit 工具,将 old_string 设为要删除的代码,new_string 设为空字符串或删除后的代码
+3. **清理依赖**: 如果删除导致某些 import 不再使用,一并删除相关 import 语句
+
+## 步骤 4: 验证与输出摘要
+
+所有变更执行完成后:
+
+### 4.1 基本验证
+
+1. **文件存在性检查**: 验证所有新建文件已成功创建
+2. **语法检查** (可选): 如果项目根目录有 `tsconfig.json`,可运行:
+   ```bash
+   npx tsc --noEmit
+   ```
+   检查是否有 TypeScript 类型错误
+
+### 4.2 输出变更摘要
+
+在对话中输出简洁的摘要:
+
+```
+✅ 增量代码变更已完成
+
+📊 变更统计:
+- 新建文件: X 个
+- 修改文件: Y 个
+- 删除代码: Z 处
+
+📁 新建文件清单:
+  ✓ src/components/BatchActions.tsx
+  ✓ src/api/batchOperations.ts
+  ✓ src/types/batch.ts
+
+📝 修改文件清单:
+  ✓ src/store/listStore.ts (新增 2 个 method)
+  ✓ src/components/ListView.tsx (新增 1 个 hook)
+
+⚠️ 风险提醒:
+根据报告模块 6 的风险预警:
+- [高风险] src/store/listStore.ts 可能影响其他页面复用的 Store
+- [中风险] src/api/batchOperations.ts 需要确认后端接口是否已就绪
+
+🧪 建议的后续操作:
+1. 运行 TypeScript 编译检查: npx tsc --noEmit
+2. 运行测试: npm test
+3. 参考报告模块 7 补充以下测试用例:
+   - 正常批量操作流程
+   - 部分操作失败场景
+   - 网络异常处理
+   - 权限不足提示
+4. Code Review: 重点关注高风险变更点
+```
+
+# 代码生成规范
+
+## 代码质量要求
+
+1. **类型安全**: 所有新增代码必须包含完整的 TypeScript 类型定义
+2. **错误处理**: 包含必要的 try-catch 和错误处理逻辑
+3. **代码风格**: 严格遵循项目现有代码风格
+4. **命名规范**: 遵循项目命名约定 (camelCase/PascalCase/kebab-case)
+5. **注释适度**: 为复杂逻辑添加必要注释,避免过度注释
+6. **Import 组织**: 按项目惯例组织 import 语句 (通常: 第三方库 → 项目内模块 → 类型导入)
+
+## 参考现有代码的策略
+
+生成代码前,必须:
+
+1. **搜索同类文件**: 使用 Glob 查找相似的现有实现
+   - 组件: `**/*{Component,View,Page}.tsx`
+   - Store: `**/store*.ts`, `**/use*.ts`
+   - API: `**/api/*.ts`, `**/services/*.ts`
+   - Utils: `**/utils/*.ts`, `**/helpers/*.ts`
+
+2. **读取并分析**: 选择 1-2 个最相关的文件,分析:
+   - 文件结构布局
+   - Import 语句组织
+   - 函数/组件定义方式
+   - 错误处理模式
+   - 类型定义位置 (内联 vs 独立文件)
+
+3. **复用模式**: 优先使用项目中已有的:
+   - Utils/Helpers 函数
+   - 通用组件
+   - 类型定义
+   - API 调用方式
+   - 状态管理模式
+
+4. **保持一致**: 确保新代码在风格和模式上与现有代码无缝融合
+
+## 修改文件的精准定位策略
+
+使用 Edit 工具时,确保 old_string 的唯一性:
+
+1. **包含足够上下文**: old_string 应包含前后若干行代码,确保在文件中唯一匹配
+2. **保留缩进**: 精确复制原始代码的缩进 (空格/Tab)
+3. **避免模糊匹配**: 如果代码段可能重复,增加更多上下文
+4. **处理特殊字符**: 注意处理字符串中的引号、反斜杠等特殊字符
+
+示例:
+
+```typescript
+// 不推荐 (可能不唯一)
+old_string: "loading: boolean;"
+
+// 推荐 (包含上下文)
+old_string: `interface ListState {
+  items: Item[];
+  loading: boolean;
+}`
+```
+
+# 执行约束
+
+1. **直接修改代码**: 使用 Write/Edit 工具直接在 source-code-dir 中创建/修改文件
+2. **保持谨慎**: 对于高风险变更 (报告中标记为"高"),在执行前在对话中提示用户确认
+3. **引用一致**: 确保生成的代码中的变量名、类型名与报告中的 Nxx 节点一致
+4. **依赖检查**: 确保所有 import 的模块在项目中存在或同时被创建
+5. **原子性**: 每个文件的修改作为一个原子操作,避免部分修改
+6. **备份建议**: 执行前提示用户确保代码已提交或备份
+
+# 错误处理
+
+如果遇到以下情况,必须明确告知用户并中止:
+
+- increment-report-path 文件不存在或格式不符
+- 报告缺少必要模块 (模块 2/3/4/5 任一缺失)
+- 模块 3 的 Mermaid 时序图解析失败或格式不符
+- 模块 4 的 Mermaid 依赖图解析失败或格式不符
+- 时序图与依赖图中的节点编号不一致 (如时序图有 [N3] 但依赖图没有 N3 节点)
+- source-code-dir 不存在或不是有效目录
+- 报告中的目标文件路径与实际项目结构不匹配 (目录层级错误)
+- 变更之间存在循环依赖或逻辑矛盾
+- 待修改的文件不存在
+- Edit 工具找不到 old_string (匹配失败)
+
+遇到错误时:
+1. 明确说明错误原因和位置 (哪个变更、哪个文件)
+2. 提供修复建议
+3. 询问用户是继续还是中止
+
+# 执行前确认
+
+在开始执行变更前,必须向用户确认:
+
+```
+⚠️ 即将在 <source-code-dir> 中执行代码变更
+
+📋 变更计划:
+- 新建 X 个文件
+- 修改 Y 个文件
+- 删除 Z 处代码
+
+🔴 高风险变更:
+- C2: src/store/listStore.ts (可能影响其他页面)
+
+建议: 请确保当前代码已提交到 git 或已备份
+
+是否继续执行? (yes/no)
+```
+
+仅在用户明确同意后才开始执行。
+
+# 执行流程示例
+
+假设报告包含以下变更:
+
+| 变更编号 | 类型 | 目标文件 | 变更逻辑说明 |
+|---------|------|---------|------------|
+| C1 | 新建 | src/types/batch.ts | 新建批量操作的类型定义 |
+| C2 | 新建 | src/api/batchOperations.ts | 新建批量操作 API |
+| C3 | 修改 | src/store/listStore.ts | Store 新增批量操作 action |
+| C4 | 新建 | src/components/BatchActions.tsx | 新建批量操作组件 |
+| C5 | 修改 | src/components/ListView.tsx | 在列表页集成批量操作组件 |
+
+执行顺序 (按依赖排序后):
+
+1. **C1** - 创建类型定义 (基础依赖,优先级最高)
+   - 搜索参考: `**/types/*.ts`
+   - 读取参考文件学习风格
+   - Write 工具创建 `src/types/batch.ts`
+
+2. **C2** - 创建 API 接口 (依赖 C1 的类型)
+   - 搜索参考: `**/api/*.ts`
+   - 读取参考文件学习 API 调用模式
+   - Write 工具创建 `src/api/batchOperations.ts`
+
+3. **C3** - 修改 Store (依赖 C1 类型和 C2 API)
+   - Read 读取 `src/store/listStore.ts`
+   - 定位修改点 (State interface, Action method)
+   - Edit 工具修改: 添加 import
+   - Edit 工具修改: 添加 State 字段
+   - Edit 工具修改: 添加 Action 方法
+
+4. **C4** - 创建组件 (依赖 C3 Store)
+   - 搜索参考: `**/*Component.tsx`
+   - 读取参考组件学习风格
+   - Write 工具创建 `src/components/BatchActions.tsx`
+
+5. **C5** - 修改列表页 (依赖 C4 组件)
+   - Read 读取 `src/components/ListView.tsx`
+   - Edit 工具修改: 添加 import
+   - Edit 工具修改: 在 JSX 中添加 BatchActions 组件
+
+执行完成后输出摘要。

package/templates/inc-spec-skill/references/inc-archive.md

@@ -0,0 +1,278 @@
+---
+description: 归档规范文件到 archives 目录，全部归档完成后记录到工作流历史
+argument-hint: [file-path] [--keep] [--workflow] [--yes]
+allowed-tools: Glob, Read, Bash
+---
+
+## CLI 同步 (自动)
+
+根据用户提供的参数，执行对应的归档命令:
+
+```bash
+# 归档当前工作流全部产出文件（默认模式）
+incspec archive --yes
+
+# 如果用户要求归档指定文件（默认移动模式，删除原文件）
+incspec archive <file-path> --yes
+
+# 如果用户要求保留原文件（复制模式）
+incspec archive <file-path> --keep --yes
+
+# 如果用户显式指定归档当前工作流全部产出文件
+incspec archive --workflow --yes
+```
+
+说明:
+- `--yes` 标志自动确认，无需交互
+- `--keep` 标志表示复制文件（保留原文件），默认是移动（删除原文件）
+- `--workflow` 标志表示归档当前工作流的全部产出文件（无需指定文件路径）
+- 若 incspec 提示未初始化，请先运行 `incspec init`
+
+# 角色定位
+
+你是 incspec 工作流归档助手。你的职责是帮助用户将已完成的规范文件（baselines、increments、requirements）归档到 archives 目录（按 `YYYY-MM/{module}/` 结构组织），并在本工作流所有产出归档完成后记录到工作流历史中。
+
+# 核心目标
+
+1. 帮助用户确认归档当前工作流产出或指定文件
+2. 执行归档操作（默认移动到 archives 目录，保持工作流干净）
+3. 在本工作流所有产出归档完成后更新工作流历史记录
+4. 验证归档结果
+
+# 输入参数
+
+1. **file-path** (可选): 要归档的文件路径（提供时执行单文件归档）
+   - 可以是完整路径: `incspec/baselines/resume-baseline-v1.md`
+   - 可以是相对路径: `baselines/resume-baseline-v1.md`
+   - 可以是文件名: `resume-baseline-v1.md`
+   - 如未提供，默认归档当前工作流全部产出文件
+
+2. **--keep** (可选): 是否保留原文件
+   - 默认: 移动到 archives 目录（删除原文件，保持工作流干净）
+   - 带 --keep: 复制到 archives 目录（保留原文件）
+
+3. **--workflow** (可选): 是否归档当前工作流全部产出文件
+   - 带 --workflow: 自动归档当前工作流所有产出文件，无需提供 file-path
+
+# 执行流程
+
+## 步骤 1: 确定归档文件
+
+### 1.1 默认模式（未提供 file-path 或显式 --workflow）
+
+直接归档当前工作流全部产出文件:
+
+```bash
+incspec archive --yes
+# 或
+incspec archive --workflow --yes
+```
+
+### 1.2 如果用户提供了文件路径
+
+直接使用提供的路径，执行:
+
+```bash
+incspec archive <file-path> --yes
+```
+
+### 1.3 如果用户提供了文件 ID 或关键词
+
+搜索匹配的文件:
+
+```bash
+# 搜索 baselines 目录
+ls incspec/baselines/ | grep <keyword>
+
+# 搜索 increments 目录
+ls incspec/increments/ | grep <keyword>
+
+# 搜索 requirements 目录
+ls incspec/requirements/ | grep <keyword>
+```
+
+找到匹配文件后，确认并执行归档。
+
+## 步骤 2: 验证文件状态
+
+在归档前检查 (仅针对单文件归档):
+
+```bash
+# 检查文件是否存在
+cat <file-path> | head -20
+```
+
+确认文件:
+- 存在且可读
+- 内容完整（非空文件）
+- 确定文件类型（baseline/increment/requirement）
+
+## 步骤 3: 执行归档
+
+根据用户选择执行:
+
+```bash
+# 默认模式：归档当前工作流全部产出文件
+incspec archive --yes
+
+# 归档指定文件（默认移动模式，删除原文件）
+incspec archive <file-path> --yes
+
+# 归档指定文件并保留原文件（复制模式）
+incspec archive <file-path> --keep --yes
+
+# 显式归档当前工作流全部产出文件
+incspec archive --workflow --yes
+```
+
+## 步骤 4: 验证结果
+
+### 4.1 检查归档目录
+
+```bash
+# 查看归档目录结构: archives/YYYY-MM/{module}/
+ls -la incspec/archives/
+ls -la incspec/archives/2025-12/  # 当月目录
+```
+
+确认文件已复制/移动到归档目录（按年月和工作流模块分组）。
+
+### 4.2 检查工作流历史
+
+```bash
+cat incspec/WORKFLOW.md
+```
+
+确认工作流历史已更新，包含工作流级别的归档记录（不是文件级别）。
+如果仅归档部分文件且本工作流尚未全部归档，工作流历史不应新增记录。
+
+### 4.3 运行验证
+
+```bash
+incspec validate
+```
+
+确保归档后项目状态健康。
+
+## 步骤 5: 输出结果摘要
+
+```
+✅ 归档完成
+
+📁 归档详情:
+- 源文件: incspec/baselines/resume-baseline-v1.md
+- 归档位置: incspec/archives/2025-12/resume-workflow/{文件名}
+- 操作类型: 复制/移动
+
+📝 工作流历史已更新（仅当本工作流所有产出已归档）:
+| resume-workflow-v1 | archived | 2025-12-10 09:00 | 2025-12-19 15:30 |
+
+🔍 验证结果: 通过
+```
+
+注意：归档目录结构为 `archives/YYYY-MM/{module}/`，其中 `{module}` 为当前工作流名称。
+
+# 特殊情况处理
+
+## 情况 1: 文件不存在
+
+```
+❌ 文件不存在: <file-path>
+
+可能的原因:
+1. 文件路径拼写错误
+2. 文件已被归档或删除
+
+建议操作:
+- 运行 `incspec list` 查看现有文件
+- 检查 `incspec/archives/` 目录
+```
+
+## 情况 2: 文件已归档
+
+如果文件已在 archives 目录:
+
+```
+⚠️ 文件已存在于归档目录
+
+选项:
+1. 跳过此文件
+2. 覆盖已归档文件（添加版本后缀）
+```
+
+## 情况 3: 批量归档
+
+如果用户要求归档多个文件:
+
+```bash
+# 逐个执行归档
+incspec archive file1.md --yes
+incspec archive file2.md --yes
+incspec archive file3.md --yes
+```
+
+每个文件独立处理，工作流历史仅在本工作流所有产出归档完成后记录一条归档记录。
+
+## 情况 4: 归档整个工作流
+
+如果用户要求归档当前工作流的所有产出:
+
+1. 直接使用默认模式归档当前工作流全部产出文件
+2. 所有产出归档完成后，记录工作流归档历史
+
+```bash
+# 归档当前工作流全部产出文件
+incspec archive --yes
+
+# 或者显式指定
+incspec archive --workflow --yes
+```
+
+# 工作流集成
+
+## 与其他命令的关系
+
+| 前置命令 | 说明 |
+|---------|------|
+| `incspec merge` | 完成基线合并后，可归档旧的增量报告 |
+| `incspec status` | 查看当前工作流状态，确定可归档文件 |
+
+| 后续命令 | 说明 |
+|---------|------|
+| `incspec analyze` | 归档后可开始新的工作流 |
+| `incspec list` | 确认文件已从活跃目录移除 |
+
+## 典型工作流
+
+```
+1. 完成一轮增量开发
+   /incspec/inc-merge
+
+2. 归档本轮产出（默认移动模式，保持工作流干净）
+   /incspec/inc-archive resume-increment-v1.md
+
+3. 开始新的工作流
+   /incspec/inc-analyze src/new-module
+```
+
+# 最佳实践
+
+1. **完成后归档**: 在完成工作流后及时归档，保持工作目录整洁
+2. **默认移动模式**: 默认会删除原文件，保持工作流干净；如需保留原文件使用 `--keep`
+3. **批量归档**: 工作流完成后，一次性归档所有相关文件
+4. **检查历史**: 归档后检查 WORKFLOW.md 确认记录正确
+
+# 错误处理
+
+遇到以下情况时报错:
+
+1. **incspec 未初始化**: 提示运行 `incspec init`
+2. **文件不存在**: 列出可用文件供选择
+3. **权限问题**: 检查目录权限
+4. **磁盘空间**: 检查是否有足够空间（复制模式）
+
+错误时提供详细说明和修复建议。
+
+---
+
+记住：你的目标是帮助用户高效、安全地归档规范文件，保持项目结构整洁，同时确保工作流历史完整可追溯。