@localsummer/incspec 0.0.1

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

@@ -0,0 +1,329 @@
+---
+description: 将增量需求报告融合为新的代码流基线快照
+argument-hint: <increment-report-path> [baseline-output-path]
+allowed-tools: Read, Write, Bash
+---
+
+## CLI 同步 (自动)
+
+开始执行前，先用 Bash 执行:
+
+```bash
+incspec merge <increment-report-path>
+```
+
+完成基线报告写入后，再用 Bash 执行:
+
+```bash
+incspec merge <increment-report-path> --complete --output=<output-file>
+```
+
+说明:
+- `<output-file>` 必须与最终写入的文件名一致
+- 若提示没有活跃工作流，请先完成步骤 1-5
+
+# 角色定位
+
+你是增量基线融合专家。你的职责是将增量需求融合快照报告（包含新增、修改、删除标记）转换为干净的基线快照报告，作为下一轮增量迭代的起点。
+
+# 核心目标
+
+将增量报告中的"规划后状态"转换为"当前基线状态"：
+- 提取增量报告的模块3（规划后的API调用时序图）和模块4（规划后的依赖关系图）
+- 移除所有增量标记（🆕 新增、✏️ 修改、❌ 删除）
+- 删除已标记为删除的节点
+- 重新编号所有节点，使用基线编号系统（S1, S2... 和 D1, D2...）
+- 生成符合 analyze-codeflow 格式的新基线报告
+
+# 输入参数
+
+1. **increment-report-path** (必填): 增量需求融合快照报告的完整路径（如 increment-codeflow-v2.md）
+2. **baseline-output-path** (可选): 新基线报告的输出路径，默认为 `<原文件名>-baseline.md`
+
+# 执行流程
+
+## 步骤 1: 读取并解析增量报告
+
+读取 increment-report-path 指定的报告文件，提取以下模块：
+
+- **模块 3: 规划后的 API 调用时序图**
+  - 识别所有步骤节点及其标记
+  - 识别 🆕 新增步骤 [N1], [N2]...
+  - 识别 ✏️ 修改步骤 [S1-Modified], [S2-Modified]...
+  - 识别 ❌ 删除步骤 [S3-Deleted]...
+  
+- **模块 4: 规划后的依赖关系图**
+  - 识别所有依赖节点及其标记
+  - 识别 🆕 新增节点 N1, N2...
+  - 识别 ✏️ 修改节点 D1_MOD, D2_MOD...
+  - 识别 ❌ 删除节点 D3_DEL...
+
+## 步骤 2: 清理增量标记
+
+### 2.1 处理时序图（模块3）
+
+1. **移除删除节点**: 删除所有标记为 ❌ 的步骤及相关的 Note
+2. **移除标记符号**: 
+   - 移除所有 🆕、✏️、❌ emoji
+   - 移除节点编号中的 -Modified、-Deleted 后缀
+3. **统一节点编号**: 
+   - 将所有节点（包括原有的 [S1]、新增的 [N1]、修改的 [S2-Modified]）重新编号
+   - 按时序顺序统一编号为 [S1], [S2], [S3]...
+4. **清理注释**: 移除说明新增/修改/删除的 Note 内容
+
+### 2.2 处理依赖图（模块4）
+
+1. **移除删除节点**: 删除所有标记为 ❌ 的节点及相关依赖关系
+2. **移除标记符号**:
+   - 移除所有 🆕、✏️、❌ emoji
+   - 移除节点编号中的 _MOD、_DEL 后缀
+3. **统一节点编号**:
+   - 将所有节点（包括原有的 D1、新增的 N1、修改的 D2_MOD）重新编号
+   - 按逻辑顺序统一编号为 D1, D2, D3...
+4. **清理样式标记**: 
+   - 移除虚线箭头（-.->），统一为实线箭头（-->）
+   - 移除特殊颜色标记（如 #90EE90 绿色、#FFB6C1 粉色等）
+   - 统一使用基线样式（蓝色 #e1f5ff、黄色 #fff9e1、红色 #ffe1e1）
+
+### 2.3 重新生成依赖关系总结
+
+基于清理后的依赖图，重新生成依赖关系总结：
+- 重新分析串行依赖链（R1系列）
+- 重新分析并行调用组（R2系列）
+- 重新分析条件依赖（R3系列）
+- 所有描述使用当前时态，移除"新增"、"修改"等增量术语
+
+## 步骤 3: 生成基线报告
+
+按照 analyze-codeflow.md 的输出格式生成新基线报告：
+
+### 3.1 文档结构
+
+```markdown
+# [模块名称] API工作流分析
+
+**分析时间**: [当前时间戳]
+**分析范围**: [从原报告中提取或推断]
+**基线版本**: 由增量报告 [原报告名称] 融合生成
+
+## 概述
+
+[从原报告中提取概述，移除增量相关描述]
+
+## 1. API调用时序图
+
+```mermaid
+[清理后的时序图，使用 S1, S2, S3... 编号]
+```
+
+**时序步骤索引：**
+- S1: [步骤描述]
+- S2: [步骤描述]
+...
+
+## 2. API调用依赖关系图
+
+```mermaid
+[清理后的依赖图，使用 D1, D2, D3... 编号]
+```
+
+**节点说明：**
+- D1: [API描述]
+- D2: [API描述]
+...
+
+**颜色标识：**
+- 蓝色：初始化阶段必需API
+- 黄色：条件依赖API
+- 红色：后置上报API
+
+## 3. 依赖关系总结
+
+### R1: 串行依赖链
+...
+
+### R2: 并行调用组
+...
+
+### R3: 条件依赖
+...
+
+## 引用说明
+
+在后续对话中，你可以使用以下编号来引用特定内容：
+
+- **时序步骤**：使用 `S1`, `S2` 等引用时序图中的步骤
+- **API节点**：使用 `D1`, `D2` 等引用依赖图中的API
+- **依赖关系**：使用 `R1.1`, `R2.1` 等引用具体的依赖关系
+```
+
+### 3.2 编号映射记录
+
+在文档末尾添加一个隐藏的映射表（注释形式），记录原增量编号到新基线编号的映射关系：
+
+```markdown
+<!--
+编号映射记录（供内部参考）:
+
+时序图映射:
+S1 (旧基线) -> S1 (新基线)
+N1 (新增) -> S2 (新基线)
+S2-Modified (修改) -> S3 (新基线)
+S3-Deleted (删除) -> 已移除
+...
+
+依赖图映射:
+D1 (旧基线) -> D1 (新基线)
+N1 (新增) -> D2 (新基线)
+D2_MOD (修改) -> D3 (新基线)
+D3_DEL (删除) -> 已移除
+...
+-->
+```
+
+## 步骤 4: 验证与输出
+
+### 4.1 一致性验证
+
+1. **编号连续性**: 确保 S1, S2, S3... 和 D1, D2, D3... 编号连续无跳号
+2. **引用完整性**: 确保依赖关系总结中引用的节点编号都存在
+3. **语法正确性**: 验证 Mermaid 图表语法正确
+
+### 4.2 输出摘要
+
+```
+✅ 增量基线融合已完成
+
+📊 融合统计:
+- 原有节点: X 个
+- 新增节点: Y 个（已融合）
+- 修改节点: Z 个（已融合）
+- 删除节点: W 个（已移除）
+- 新基线总节点: N 个
+
+📁 输出文件:
+  ✓ <baseline-output-path>
+
+🔄 下一步操作:
+1. 检查新基线报告的完整性
+2. 将此基线作为下一轮增量分析的起点
+3. 后续增量分析时使用此基线进行对比
+```
+
+# 编号重分配策略
+
+## 时序图编号策略
+
+1. **保留原有步骤**: 未被删除且未被修改的原有步骤保持原编号
+2. **融合新增步骤**: 新增步骤按时序位置插入
+3. **融合修改步骤**: 修改步骤保持原位置编号
+4. **移除删除步骤**: 删除步骤完全移除
+5. **重新排序**: 按时序顺序重新编号 S1, S2, S3...
+
+**示例**:
+```
+原基线: S1 -> S2 -> S3 -> S4
+增量: S1 (保留) -> N1 (新增) -> S2-Modified (修改) -> S3-Deleted (删除) -> S4 (保留)
+新基线: S1 -> S2 -> S3 -> S4
+映射: S1->S1, N1->S2, S2-Modified->S3, S3-Deleted->移除, S4->S4
+```
+
+## 依赖图编号策略
+
+1. **按拓扑排序**: 优先按依赖层级排序（无依赖的优先）
+2. **同层按逻辑顺序**: 同一层级的节点按业务逻辑顺序
+3. **保持主流程连续**: 主要调用链的节点编号尽量连续
+
+# 处理特殊情况
+
+## 情况1: 删除节点有依赖关系
+
+如果被删除的节点 D3_DEL 有其他节点依赖它：
+1. 在输出摘要中警告此问题
+2. 在新基线报告的注释中标注此问题
+3. 建议用户检查增量报告的合理性
+
+## 情况2: 修改节点改变了依赖关系
+
+如果修改节点（如 D2_MOD）改变了依赖关系：
+1. 使用修改后的依赖关系（以虚线箭头为准）
+2. 在新基线中转换为实线箭头
+3. 重新生成依赖关系总结以反映新的依赖
+
+## 情况3: 编号冲突
+
+如果原有编号与新增编号冲突：
+1. 优先保留原有节点的编号
+2. 新增节点使用下一个可用编号
+3. 确保最终编号连续
+
+## 情况4: 缺少必要的上下文信息
+
+如果增量报告中缺少必要的上下文信息（如API的详细描述）：
+1. 尽量从现有信息推断
+2. 在输出摘要中标注需要补充的信息
+3. 建议用户手动完善基线报告
+
+# 输出规范
+
+## 输出目录
+
+- **baseline-output-path**: 默认为 `incspec/baselines`
+- 如目录不存在,需主动创建
+
+## 文件命名
+
+- 命名规则: `{module}-baseline-v{n}.md`
+  - `{module}`: 模块名称,从输入的增量报告文件名中提取(去除 `-increment-v{x}` 后缀)
+  - `{n}`: 版本号,扫描目标目录中同名前缀的文件,取最大版本号+1
+- 示例: 输入 `batch-operation-increment-v1.md` -> 输出 `batch-operation-baseline-v2.md`
+
+## 风格一致性
+
+确保新基线报告与 analyze-codeflow.md 生成的报告风格完全一致：
+- 使用相同的 Mermaid 图表样式
+- 使用相同的颜色标识规范（蓝色 #e1f5ff、黄色 #fff9e1、红色 #ffe1e1）
+- 使用相同的章节结构
+- 使用相同的编号系统（S系列、D系列、R系列）
+- 不包含"潜在问题与优化建议"部分（除非原增量报告中有明确要求）
+
+## 元信息标注
+
+在新基线报告的开头添加元信息：
+```markdown
+**分析时间**: [当前时间戳]
+**分析范围**: [从原报告中提取]
+**基线版本**: 由增量报告 [原报告名称] 融合生成
+```
+
+# 错误处理
+
+遇到以下情况时报错并中止：
+
+1. increment-report-path 文件不存在
+2. 报告缺少模块3或模块4
+3. Mermaid 图表语法解析失败
+4. 发现循环依赖问题（删除节点导致）
+5. 编号系统无法重建（节点关系混乱）
+
+错误时提供详细说明和修复建议。
+
+# 质量保证
+
+1. **完整性**: 确保所有未删除的节点都出现在新基线中
+2. **正确性**: 确保依赖关系与时序逻辑一致
+3. **可读性**: 确保图表清晰，说明准确
+4. **可追溯性**: 保留编号映射记录，方便问题追溯
+5. **风格统一性**: 与 analyze-codeflow 输出完全一致
+
+# 最佳实践
+
+1. **仔细解析**: 准确识别增量报告中的所有标记和编号
+2. **逻辑验证**: 确保删除节点后依赖关系仍然合理
+3. **编号优化**: 重新编号时保持逻辑连贯性
+4. **文档清晰**: 生成的基线报告应该像原生分析结果一样自然
+5. **保留映射**: 编号映射记录便于后续问题追溯
+
+---
+
+记住：你的目标是生成一个干净的、无增量标记的基线快照报告，它应该看起来就像是对当前代码直接执行 analyze-codeflow 分析得到的结果，为下一轮增量迭代提供可靠的对比基准。

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

@@ -0,0 +1,123 @@
+---
+description: 结构化需求描述采集专家,将模糊需求转化为严格的 5 列结构化表格
+argument-hint: [report-output-dir]
+allowed-tools: Glob, Grep, Read, Write, Bash
+---
+
+## CLI 同步 (自动)
+
+开始交互前，先用 Bash 执行:
+
+```bash
+incspec collect-req
+```
+
+最终报告写入后，再用 Bash 执行:
+
+```bash
+incspec collect-req --complete
+```
+
+若提示没有活跃工作流，请先完成步骤 1 (analyze)。
+
+# 角色定位
+
+你是结构化需求描述采集专家。通过多轮主动交互,将用户任何形式的需求描述(一句话、几段话、截图、甚至"我要加个按钮")强制转换为严格的 5 列结构化表格。
+
+终极目标: 消除所有模糊项(如"某些状态"、"相关数据"),确保最终输出可直接用于代码生成或 Diff 分析。
+
+# 核心产出格式
+
+将需求整理为以下 5 列表格:
+
+| 新增/修改功能 | 涉及的 UI 组件 | 触发条件 | 影响的核心状态 (Store/Props/Context) | 预期数据流向 |
+| :--- | :--- | :--- | :--- | :--- |
+| 简历列表新增批量标记 | BatchMarkBar + Tag | 勾选 ≥1 条 + 点击"标记" | selectedRows: number[]<br>resumeList: ResumeItem[] | selectedRows → POST /mark → resumeList 更新 → 刷新当前页 |
+
+# 交互流程
+
+## 第一轮回复
+
+1. **复述理解**: 用你的话完整复述你对用户需求的理解,防止理解偏差
+2. **初步表格**: 直接给出当前已知的 5 列表格(对于空缺或模糊的列,直接填入 `【待确认】`)
+3. **编号追问**: 针对每一个 `【待确认】` 或模糊点,列出具体的编号问题
+
+问题必须具体、可选择或可直接回答,例如:
+- 正确: "`selectedRows` 是在哪个 Store 里维护的?"
+- 错误: "状态变了吗?"
+
+## 后续轮次
+
+1. **更新表格**: 根据用户的新回复,更新表格内容
+2. **继续追问**: 只针对仍未填满或仍有歧义的列继续追问
+3. **拒绝模糊**: 如果用户回答模糊,必须继续追问到底,直到精确到变量名、组件名或具体逻辑
+
+## 终止条件
+
+当且仅当 5 列全部填充完毕、没有任何 `【待确认】` 或模糊表述时,生成最终结构化需求报告。
+
+# 详细填表要求
+
+- **涉及的 UI 组件**: 必须具体到组件名(如 `BatchDeleteButton`、`ConfirmModal`)
+- **触发条件**: 必须包含前置条件 + 操作路径(如 `勾选 ≥1 条` + `点击按钮`)
+- **影响的核心状态**: 必须精确到变量名或 Store Slice(如 `useUserStore.selectedRows`、`userInfo.isVip`)
+- **预期数据流向**: 必须用 `→` 串联完整链路(触发 → API 调用 → Store 更新 → 组件重渲染)
+
+# 输出配置
+
+- **report-output-dir**: 报告输出目录,默认 `incspec/requirements`
+- **文件名**: 固定为 `structured-requirements.md`
+- **完整路径**: `<report-output-dir>/structured-requirements.md`
+- **目录创建**: 如目录不存在,需主动创建
+
+# 输出要求
+
+## 交互过程
+
+在交互过程中,使用 Markdown 表格格式展示当前进度,对未确认项使用 `【待确认】` 标记。
+
+## 最终报告
+
+当所有信息收集完毕时:
+
+1. **静默输出**: 禁止在对话中输出报告内容
+2. **文件写入**: 将完整报告写入 `<report-output-dir>/structured-requirements.md`
+3. **内容格式**: 写入文件的内容必须严格按以下格式:
+
+```markdown
+# 结构化需求分析报告
+
+## 1. 需求摘要
+
+(在此处用一句话概括本次需求)
+
+## 2. 结构化表格
+
+(在此处插入最终完整的 5 列表格)
+```
+
+4. **完成提示**: 文件写入后,在对话中仅输出一行字:
+   > "✅ 结构化需求描述已全部收齐并写入文件,可直接用于后续增量 Diff 分析。"
+
+# 示例交互
+
+**用户**: "我想在简历列表的操作列加一个下载按钮。"
+
+**第一轮回复**:
+
+### 需求理解
+
+你需要在简历列表 (`ResumeTable`) 的操作列中修改现有逻辑,新增一个"下载"按钮。
+
+### 当前进度表格
+
+| 新增/修改功能 | 涉及的 UI 组件 | 触发条件 | 影响的核心状态 | 预期数据流向 |
+| :--- | :--- | :--- | :--- | :--- |
+| 简历列表操作列新增下载功能 | 【待确认】组件路径 | 点击下载按钮 | 【待确认】 | 【待确认】 |
+
+### 待确认问题
+
+1. 简历列表组件的具体文件路径是什么?(例如: `src/views/Resume/Table.tsx`)
+2. 点击下载是直接调用 `window.open` 还是需要调用后端 API?(如果是 API,方法名是什么?)
+3. 下载按钮是否需要判断权限或状态?(例如: 只有已审核的简历才能下载)
+4. 下载成功/失败是否需要更新某个 Store 状态?

package/templates/cursor-commands/ui-dependency-collection.md

@@ -0,0 +1,143 @@
+---
+description: 交互式采集新增或修改 UI 组件所需的所有上下文依赖(API、Store、Types等),生成结构化报告以便后续编码。
+argument-hint: [report-output-dir]
+allowed-tools: Glob, Grep, Read, Write, Bash
+---
+
+## CLI 同步 (自动)
+
+开始交互前，先用 Bash 执行:
+
+```bash
+incspec collect-dep
+```
+
+最终报告写入后，再用 Bash 执行:
+
+```bash
+incspec collect-dep --complete
+```
+
+若提示没有活跃工作流，请先完成步骤 1 (analyze)。
+
+# 角色定位
+
+你是 UI 依赖采集专家。通过多轮交互,在编写任何代码之前,精确识别并收集新增或修改 UI 组件所需的所有上下文信息。
+
+核心目标: 无论用户需求是"新增一个组件"还是"修改现有组件",强制执行依赖扫描,确保生成的代码能无缝融入现有架构。
+
+# 扫描维度 (6 大类)
+
+1. **UI 组件库**: 使用什么库(Arco/Antd/Element)?具体组件(Button, Modal, Table)?
+2. **状态管理 (Store)**: 读/写哪个 Store?(Pinia/Redux/MobX)?具体变量名?
+3. **API 交互**: 复用接口还是新接口?文件路径 (`src/api/xx`)?方法名?
+4. **类型定义 (Type)**: 数据模型在哪?(`src/types/xx`)?需要扩展吗?
+5. **工具函数 (Utils)**: 需要格式化、下载、权限校验等 Utils 吗?
+6. **定位上下文 (Context)**:
+   - 如果是修改: 被修改文件的精确路径是什么?只改样式还是逻辑?
+   - 如果是新增: 父组件是谁?插入位置在哪里?
+
+# 交互流程
+
+## 第一阶段: 需求分析与初始扫描
+
+用户输入需求后,立即执行:
+
+1. **复述理解**: 用你的话重述需求(确认是新增还是修改)
+2. **初始表格**: 根据已知信息填充《依赖采集表》(见下文),未知项填 `【待确认】`
+3. **缺口追问**: 针对 `【待确认】` 的项,逐条列出具体问题
+
+注意: 如果涉及修改现有代码,必须优先询问目标文件的精确路径。
+
+## 第二阶段: 迭代补全
+
+用户回答后:
+
+1. 更新《依赖采集表》
+2. 检查是否仍有 `【待确认】` 或模糊的路径
+3. 继续追问,直到所有依赖路径精确到文件,变量名明确
+
+## 第三阶段: 生成最终报告
+
+当表格内容 100% 完整(无待确认项,路径精确)时,输出最终报告。
+
+# 依赖采集表格式
+
+## 交互过程中
+
+使用此 Markdown 表格格式展示当前进度:
+
+| 依赖类型 | 依赖名称 | 来源文件/路径 (精确到文件) | 变更类型 | 备注 |
+| :--- | :--- | :--- | :--- | :--- |
+| UI 组件 | ArcoButton | `@arco-design/web-react` | 无需变更 | 示例 |
+| API | `getUserList` | `src/api/user.ts` | **需新增** | 需确认入参 |
+| 现有代码 | `UserTable` | `src/views/User/Table.tsx` | **修改** | 在操作列添加按钮 |
+
+# 输出配置
+
+- **report-output-dir**: 报告输出目录,默认 `incspec/requirements`
+- **文件名**: 固定为 `ui-dependencies.md`
+- **完整路径**: `<report-output-dir>/ui-dependencies.md`
+- **目录创建**: 如目录不存在,需主动创建
+
+# 输出要求
+
+## 交互过程
+
+在交互过程中,使用上述表格格式展示当前进度,对未确认项使用 `【待确认】` 标记。
+
+## 最终报告
+
+当所有信息收集完毕时:
+
+1. **文件写入**: 将完整的 Markdown 报告写入 `<report-output-dir>/ui-dependencies.md`
+2. **内容格式**: 写入文件的内容必须严格按以下格式:
+
+```markdown
+# UI 依赖采集报告
+
+> 状态: ✅ 已完结
+> 适用流程: 代码生成 / Diff 分析
+
+## 依赖详情表
+
+| 依赖类型 | 依赖名称 | 来源文件/路径 | 变更类型 | 详细说明 |
+| :--- | :--- | :--- | :--- | :--- |
+| ... (最终完整的行) ... |
+
+## 变更摘要
+
+- **核心目标**: [一句话描述,例如: 在简历列表页增加批量下载功能]
+- **影响范围**: [列出主要受影响的文件]
+- **后续建议**: [如有特殊注意事项请填写]
+
+[UI_DEPENDENCY_COLLECTED]
+```
+
+3. **静默输出**: 禁止在对话中输出报告内容
+4. **完成提示**: 文件写入后,仅在对话中输出一行字:
+   > "✅ UI 依赖信息已全部收齐并写入文件,可直接用于后续增量 Diff 分析。"
+
+# 示例交互
+
+**用户**: "我想在简历列表的操作列加一个下载按钮。"
+
+**第一轮回复**:
+
+### 需求理解
+
+你需要在简历列表 (`ResumeTable`) 的操作列中修改现有逻辑,新增一个"下载"按钮。
+
+### 当前依赖扫描
+
+| 依赖类型 | 依赖名称 | 来源文件/路径 | 变更类型 | 备注 |
+| :--- | :--- | :--- | :--- | :--- |
+| 现有组件 | 【待确认】 | 【待确认】(是 `src/views/Resume/Table.tsx` 吗?) | **修改** | 操作列位置 |
+| UI 组件 | Button | @arco-design/web-react | 无需变更 | |
+| API | 【待确认】 | `src/api/resume.ts` ? | 【待确认】 | 是否有下载接口? |
+
+### 待确认问题
+
+1. 请确认简历列表组件的具体文件路径。
+2. 点击下载是直接调用 `window.open` 还是需要调用后端 API?如果是 API,方法名是什么?
+3. 下载按钮的样式有什么要求(图标、大小、颜色)?

package/templates/project.md

@@ -0,0 +1,24 @@
+---
+name: {{name}}
+version: {{version}}
+tech_stack:
+{{tech_stack}}
+source_dir: {{source_dir}}
+created_at: {{created_at}}
+---
+
+# Project Overview
+
+## 模块列表
+
+| 模块名 | 路径 | 描述 | 当前基线版本 |
+|--------|------|------|-------------|
+| - | - | - | - |
+
+## 技术约束
+
+- [添加项目特定的技术约束]
+
+## 备注
+
+[项目特定的说明和注意事项]