@localsummer/incspec 0.0.6 → 0.0.8

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. **磁盘空间**: 检查是否有足够空间（复制模式）
+
+错误时提供详细说明和修复建议。
+
+---
+
+记住：你的目标是帮助用户高效、安全地归档规范文件，保持项目结构整洁，同时确保工作流历史完整可追溯。

package/templates/inc-spec-skill/references/merge-to-baseline.md

@@ -0,0 +1,415 @@
+---
+description: 将增量需求报告融合为新的代码流基线快照
+argument-hint: <increment-report-path> [baseline-output-dir]
+allowed-tools: Read, Write, Bash
+---
+
+## CLI 同步 (自动)
+
+**检测工作流模式:**
+
+```bash
+incspec status
+```
+
+### 完整模式 (7步)
+
+开始执行前，先用 Bash 执行:
+
+```bash
+incspec merge <increment-report-path>
+```
+
+完成基线报告写入后，再用 Bash 执行:
+
+```bash
+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 产出）转换为干净的基线快照报告
+- **快速模式**: 重新分析当前代码状态（已应用变更后），生成新版本基线快照
+
+# 核心目标
+
+将增量报告中的"规划后状态"转换为"当前基线状态"：
+- 提取增量报告的模块3（规划后的API调用时序图）和模块4（规划后的依赖关系图）
+- 移除所有增量标记（🆕 新增、✏️ 修改、❌ 删除）
+- 删除已标记为删除的节点
+- 重新编号所有节点，使用基线编号系统（S1, S2... 和 D1, D2...）
+- 生成符合 analyze-codeflow 格式的新基线报告
+
+# 输入参数
+
+1. **increment-report-path** (必填): 增量需求融合快照报告的完整路径（如 increment-codeflow-v2.md）
+2. **baseline-output-dir** (可选): 新基线报告的输出路径，默认为 `<原文件名>-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-dir>
+
+🔄 下一步操作:
+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-dir**: 默认为 `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 分析得到的结果，为下一轮增量迭代提供可靠的对比基准。
+
+---
+
+# 快速模式执行流程
+
+快速模式下，合并步骤实际是"重新分析"：不依赖增量设计报告，而是直接分析当前代码状态生成新基线。
+
+## 核心区别
+
+| 对比项 | 完整模式 | 快速模式 |
+|-------|---------|---------|
+| 输入文件 | 增量设计报告 | 无（直接分析代码） |
+| 执行逻辑 | 清理增量标记、重新编号 | 重新执行 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. 此基线将作为下一轮增量分析的起点
+```