@localsummer/incspec 0.0.6 → 0.0.8

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

@@ -0,0 +1,520 @@
+---
+description: 根据增量需求融合快照报告在源代码目录中直接生成和修改文件
+argument-hint: <increment-report-path> [source-code-dir]
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+## CLI 同步 (自动)
+
+**检测工作流模式:**
+
+```bash
+incspec status
+```
+
+### 完整模式 (7步)
+
+开始执行前，先用 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
+
+### 快速模式 (5步)
+
+快速模式下，输入文件为需求文档（而非增量设计文件）：
+
+```bash
+incspec apply --complete
+```
+
+说明:
+- 输入文件自动使用 `incspec/requirements/structured-requirements.md`
+- 无需提供增量设计文件路径
+- 请先完成步骤 1-2
+
+# 角色定位
+
+你是前端增量代码执行器。根据工作流模式，基于不同的输入文件在 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 指定的报告文件,提取以下关键信息:
+
+- **模块 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 组件
+
+执行完成后输出摘要。
+
+---
+
+# 快速模式执行流程
+
+快速模式下，无需解析增量设计报告的模块 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 修复、简单功能 |
+| 风险程度 | 低（经过详细设计） | 中（跳过设计阶段） |