sync: 旅程增量更新 + 设计工具适配层 + Skill 调用格式改进

来自 merge-epics 项目的技能同步，包含： d8d-iterate: - phase-01: 影响评估增加旅程维度（affected_journeys） - phase-02: 新增 Step 2.6 旅程定义增量更新 - phase-04/05: Skill 调用格式改进，添加核心规则和实际调用指令 - workflow: 状态机追加 update journeys，添加自动提交推送铁律 d8d-prototype: - step-01: 设计文件检测优先级调整 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-10 05:45:18 +00:00
parent 0c7bd7f06b
commit d1ca9a0840
6 changed files with 225 additions and 106 deletions
--- a/.claude/skills/d8d-iterate/phase-01-analyze.md
+++ b/.claude/skills/d8d-iterate/phase-01-analyze.md
@@ -58,6 +58,13 @@
 4. 读取现有 Epic 列表
   → 需要创建多少新 Story？
   → 是否影响已有 Epic 的 Story？
+
+5. 读取已有 Epic 的旅程文件
+   → 变更是否影响已有旅程的验证步骤？
+   → 新 FR 是否需要在已有旅程中增加步骤？
+   → 扫描 `{implementation_artifacts}/epic-*-journeys.md`
+   → 匹配规则：新 FR 所属模块 == 旅程头部 `> 对应需求` 范围
+   → 仅评估已有 Epic（新 Epic 的旅程走 d8d-dev 旅程定义子模式）
 ```

 #### Bugfix 类型影响评估
@@ -153,6 +160,12 @@ design:
 - 架构: 需要添加 BatchTask 模型和批量执行器
 - UX: 需要添加批量任务面板和仪表盘
 - Epic: 需要创建新 Epic (估计 7 个 Story)
+- 旅程: 受影响的旅程列表（无/如下）
+
+### 受影响的旅程
+- 列表: [epic-2 旅程 2.1 工作空间创建和管理, ...]
+- 影响类型: add_steps | extend_flow | no_impact
+- 新增步骤概要: {简述需要在旅程中新增的验证内容}

 ### 执行路径
 Phase 2 → Phase 3 → Phase 4 → Phase 5
--- a/.claude/skills/d8d-iterate/phase-02-docs.md
+++ b/.claude/skills/d8d-iterate/phase-02-docs.md
@@ -170,6 +170,98 @@ epics:

 3. 同步更新 `sprint-status.yaml`

+### Step 2.6: 旅程定义增量更新
+
+**条件**：`iterate-context.md` 中 `affected_journeys` 非空且不为 `no_impact`。
+
+**跳过条件**：
+
+```
+IF iterate-context.md 中 affected_journeys 为空或 no_impact:
+    → 跳过本步骤
+IF 变更创建了全新 Epic（不影响已有 Epic）:
+    → 跳过本步骤（新 Epic 的旅程在 Phase 5 首次旅程验证时自动生成）
+```
+
+**操作流程**：
+
+1. **读取受影响旅程文件**
+
+   从 `iterate-context.md` 的 `affected_journeys` 列表获取受影响的 Epic 编号，逐个读取：
+   ```
+   {implementation_artifacts}/epic-{N}-journeys.md
+   ```
+
+2. **确定增量策略**
+
+   根据影响类型执行不同策略：
+
+   **策略 A — add_steps（在已有旅程中插入步骤）**：
+
+   a. 读取 PRD 中新添加的 FR 条目，提取用户可见行为描述
+   b. 定位需要插入步骤的旅程和插入位置：
+      - 新步骤发生在已有步骤之间 → 插入到对应位置，后续步骤编号 +1
+      - 新步骤发生在已有步骤之后 → 追加到用户视角步骤末尾
+   c. 生成新步骤内容（遵循旅程真实性规则 R1-R7）：
+      - 用户视角步骤：从用户自然操作角度描述
+      - 技术验证步骤：包含具体 API 断言和数据状态变化
+      - 验收标准：可量化的断言
+   d. 更新"数据状态变化"表格，添加新阶段对应的行
+
+   **策略 B — extend_flow（扩展旅程范围）**：
+
+   a. 在受影响旅程的"跨越页面"中追加新页面路径
+   b. 在"前置条件"中添加新功能所需的状态
+   c. 在用户视角步骤末尾追加扩展步骤
+   d. 在技术验证步骤中追加对应的 API 验证
+
+3. **步骤编号重整**
+
+   插入新步骤后，重新编号所有后续步骤（用户视角步骤、技术验证步骤均需连续编号）。
+
+   **⚠️ 从最后一个受影响的旅程向前处理；在一个旅程内，从最高步骤编号向后处理。**
+   使用 Edit tool 的 oldText/newText 精确替换，避免中间偏移。
+
+4. **验证增量合并质量**
+
+   ```
+   检查项：
+   ✅ 已有步骤内容未被修改（只追加/插入新步骤）
+   ✅ 新步骤编号连续，与前后步骤衔接
+   ✅ 新步骤遵循旅程真实性规则 R1-R7
+   ✅ "数据状态变化"表格包含新阶段
+   ✅ "验收标准"列表包含新功能的断言
+   ✅ "跨越页面"包含新涉及的页面路径（如有）
+   ✅ "前置条件"包含新功能所需状态（如有）
+   ```
+
+5. **更新旅程文件头部**
+
+   如果新 FR 改变了旅程对应的 FR 范围，更新文件头部的 `> 对应需求：` 行。
+
+**增量合并模板（策略 A — 插入中间步骤）**：
+
+```
+--- 插入前（示例：步骤 3 后插入区域选择步骤）---
+3. 用户在创建对话框中看到"名称"输入框 -> 输入名称
+4. 用户点击"确认"按钮 -> 对话框关闭
+
+--- 插入后 ---
+3. 用户在创建对话框中看到"名称"输入框 -> 输入名称
+4. 用户在对话框中看到"区域"选择器 -> 选择目标区域（如"新加坡"）
+5. 用户点击"确认"按钮 -> 对话框关闭
+```
+
+**禁止行为**：
+
+```
+❌ 删除已有步骤（即使步骤描述不再完全准确，也应追加补充说明而非删除）
+❌ 修改已有步骤的编号而不调整后续编号（编号必须连续）
+❌ 重写整个旅程文件（增量优先，只修改受影响部分）
+❌ 在用户步骤中引用开发专用元素（违反 R1）
+❌ 添加未经源码验证的功能步骤（违反 R2）
+```
+
 ## 质量检查

 每个文档更新后，验证：
@@ -180,6 +272,7 @@ epics:
 ✅ 新 Story 的依赖关系正确
 ✅ pipeline-state 的计数正确
 ✅ 所有新增文件路径符合项目约定
+✅ 受影响旅程已增量更新（如有 affected_journeys）
 ```

 ## 输出
@@ -192,4 +285,6 @@ phase-02-docs:
  ux_updated: true | false
  epic_created: true | false
  pipeline_state_updated: true | false
+  journeys_updated: true | false
+  affected_journeys: ["epic-N 旅程 X.Y", ...]
 ```
--- a/.claude/skills/d8d-iterate/phase-04-dev.md
+++ b/.claude/skills/d8d-iterate/phase-04-dev.md
@@ -6,8 +6,8 @@

 根据变更类型和 Phase 2 的分析结果，选择 d8d-dev 的运行模式：

-| 场景 | d8d-dev 模式 | 参数 |
-|------|-------------|------|
+| 场景 | d8d-dev 模式 | Skill 调用参数 |
+|------|-------------|---------------|
 | 新 Epic | 单 Epic 模式 | `--epic epic-{N}` |
 | 新 Story | 单 Story 模式 | `--story {story-id}` |
 | Bug 修复 | 单 Story 模式 | `--story {story-id}` |
@@ -16,57 +16,48 @@

 ## 执行方式

+### ⛔ 核心规则
+
+1. **不要调用 d8d-dev 无参数** — 可能触发完整模式，重跑所有 Epic
+2. **不要使用 `--force`** — 会清除所有已有状态
+3. **确认 pipeline-state 已更新** — Phase 2 必须先更新 pipeline-state.yaml
+4. **增量优先** — 只实现新增或变更的部分，保留所有已有代码
+
 ### 方式 A: 新 Epic 开发

-Phase 2 创建了新 Epic（如 Epic 7）时：
+Phase 2 创建了新 Epic（如 Epic 7）时使用。
+
+**⛔ 使用 Skill tool 调用 d8d-dev，参数格式：**

 ```
-Skill tool: d8d-dev
-Arguments:
-  --epic epic-7
-
-  项目: {project_name}
-  PRD: {planning_artifacts}/prd.md
-  架构: {planning_artifacts}/architecture.md
-  UX设计: {planning_artifacts}/ux-design-specification.md
-  Epic: {planning_artifacts}/epics.md (Epic 7 部分)
-
-  === 前置产物 ===
-  已完成 Epic: 1-6 (全部 PASS)
-  新增 Epic: 7 (7 个 Story, 全部 pending)
-
-  === 上下文 ===
-  这是一个增量开发，在已有 MVP 基础上添加新功能。
-  请只实现 Epic 7 的 Story，不要修改已有 Epic 的代码。
-  如果需要修改已有文件（如添加 import、增加字段），
-  确保不破坏已有功能。
-
-  === 指令 ===
-  使用单 Epic 模式，依次实现 Epic 7 的所有 Story。
-  每个 Story 执行完整的 CREATE-SPEC → IMPLEMENT → TEST → REVIEW → MARK-DONE 循环。
+skill: "d8d-dev"
+args: "--epic epic-7"
 ```

+调用示例：
+```
+Skill(skill: "d8d-dev", args: "--epic epic-7")
+```
+
+调用后 d8d-dev 会自动：
+- 读取 PRD、架构、UX、Epic 定义
+- 逐 Story 执行 CREATE-SPEC → IMPLEMENT → TEST → REVIEW → MARK-DONE
+- 更新 pipeline-state.yaml
+
 ### 方式 B: 单 Story 修复

-定位到具体 Story 进行修复：
+定位到具体 Story 进行修复。
+
+**⛔ 使用 Skill tool 调用 d8d-dev，参数格式：**

 ```
-Skill tool: d8d-dev
-Arguments:
-  --story {story-id}
+skill: "d8d-dev"
+args: "--story {story-id}"
+```

-  项目: {project_name}
-  PRD: {planning_artifacts}/prd.md
-  Epic: {planning_artifacts}/epics.md (相关 Story)
-
-  === Bug 上下文 ===
-  问题描述: {bug 描述}
-  根因分析: {分析结果}
-  修复方案: {方案}
-
-  === 指令 ===
-  使用单 Story 模式，修复指定 Story 的问题。
-  不做额外的代码改动。
+调用示例：
+```
+Skill(skill: "d8d-dev", args: "--story 7-3")
 ```

 ### 方式 C: Bug 直接修复（无 Story）
@@ -76,14 +67,15 @@ Arguments:
 1. 读取相关代码文件
 2. 定位问题
 3. 使用 Edit tool 修复
-4. 运行测试验证
+4. 运行 typecheck 验证
+5. **⛔ 自动提交推送（零暂停）**：
+   ```bash
+   git add <修改文件>
+   git commit -m "fix(scope): 描述"
+   git push origin $(git branch --show-current)
+   ```

-## 注意事项
-
-1. **不要调用 `d8d-dev --force`**：这会清除所有已有状态
-2. **不要调用 `d8d-dev` 无参数**：可能触发完整模式，重跑所有 Epic
-3. **确认 pipeline-state 已更新**：Phase 2 必须先更新 pipeline-state.yaml
-4. **监控执行结果**：如果 d8d-dev 报错，检查是否因为 pipeline-state 不一致
+**注意**：此方式不调用 Skill tool，直接在当前对话中执行修复。修复完成后必须自动提交推送，不询问用户。

 ## 输出

--- a/.claude/skills/d8d-iterate/phase-05-verify.md
+++ b/.claude/skills/d8d-iterate/phase-05-verify.md
@@ -8,49 +8,76 @@

 ### Step 5.1: 回归测试

-调用 d8d-dev 的回归验证模式：
+**⛔ 必须调用 Skill tool 执行 d8d-dev 回归验证。**

+从 `iterate-context.md` 读取变更分析，确定验证范围：
+
+- **feature 新 Epic** → 验证已有 Epic 的功能点，跳过新增 Epic
+- **feature 横切增强** → 验证受影响 Epic 的功能点
+- **bugfix 单文件** → 低风险可跳过，其他情况验证受影响范围
+
+**调用方式**（⛔ 这是实际调用指令，必须执行）：
+
+使用 `Skill` tool 调用 d8d-dev 技能，参数格式：
 ```
-Skill tool: d8d-dev
-Arguments:
-  --regression
-
-  项目: {project_name}
-
-  === 指令 ===
-  使用回归验证模式，逐 Story 验证已有功能。
-  跳过本次新增的 Epic/Story（已在 Phase 4 验证过）。
-  只验证 Epic 1-6 的功能点。
+skill: "d8d-dev"
+args: "--regression 回归验证已有功能。变更类型: {change_type}。{change_scope描述}"
 ```

-**条件跳过**：
+示例：
+- 新 Epic 7 → `args: "--regression 回归验证已有功能。变更类型: feature。验证 Epic 1-6 所有功能点，跳过新增的 Epic 7（已在 Phase 4 验证过）。"`
+- 横切增强 → `args: "--regression 回归验证已有功能。变更类型: feature。验证受影响 Epic 的功能点（{affected_epics}）。"`
+
+**条件跳过判断**：

 ```
-IF 变更类型 == bugfix 且只修改了单个文件:
-    → 可选执行回归（取决于风险等级）
+IF 变更类型 == bugfix 且只修改了单个文件 且 risk == low:
+    → 可跳过回归验证，记录跳过原因

 IF 变更类型 == regression:
-    → 这就是主要任务，执行完整回归
+    → 这就是主要任务，必须执行完整回归

 IF 变更类型 == feature 且 risk == low:
-    → 执行回归（推荐但不强制）
+    → 推荐执行回归（不强制）
 ```

+**⛔ 结果判定**（Skill 调用返回后立即判断）：
+
+- 全部 PASS → 零暂停，自动继续 Step 5.2 旅程验证
+- 有 FAIL → **⛔ 自动修复流程**：
+  1. 分析失败原因，定位 bug
+  2. 使用 Edit tool 修复
+  3. typecheck 验证修复
+  4. 自动提交推送：
+     ```bash
+     git add <修改文件>
+     git commit -m "fix(scope): 描述"
+     git push origin $(git branch --show-current)
+     ```
+  5. 重新执行回归验证
+  6. 若仍 FAIL → 记录失败列表，跳过旅程验证，进入 Step 5.3 变更报告
+- 修复过程中零暂停，不询问用户是否提交
+
 ### Step 5.2: 旅程验证

-回归测试全部通过后，**零暂停**自动执行旅程验证：
+**⛔ 回归验证 PASS 后零暂停自动执行。回归有 FAIL 则跳过本步骤。**

+**调用方式**（⛔ 这是实际调用指令，必须执行）：
+
+使用 `Skill` tool 调用 d8d-dev 技能，参数格式：
 ```
-Skill tool: d8d-dev
-Arguments:
-  --journey
-
-  === 指令 ===
-  使用旅程验证模式，验证跨 Story 的用户旅程。
-  包含已有旅程 + 新增功能的旅程。
+skill: "d8d-dev"
+args: "--journey 旅程验证。验证所有用户旅程，包括已有旅程和新增功能的旅程。"
 ```

-**铁律**：回归验证 PASS 后才能执行旅程验证。功能不存在时测旅程无意义。
+**铁律**：
+- 回归验证 PASS 后才能执行旅程验证
+- 功能不存在时测旅程无意义（⛔ 不得跳过回归直接旅程）
+
+**⛔ 结果判定**：
+
+- 全部 PASS → 记录结果，继续 Step 5.3
+- 有 FAIL → 尝试记录失败旅程及原因，继续 Step 5.3

 ### Step 5.3: 生成变更报告

@@ -60,47 +87,33 @@ Arguments:
 # 变更报告

 ## 概要
- 变更类型: feature
- 用户需求: 增加多城市批量任务调度功能
- 执行路径: Phase 2 → Phase 4 → Phase 5
- 风险等级: low
+- 变更类型: {change_type}
+- 用户需求: {user_request}
+- 执行路径: {executed_phases}
+- 风险等级: {risk_level}

 ## Phase 2 — 文档增量更新
 | 文档 | 操作 | 状态 |
 |------|------|------|
-| PRD | 添加 FR-013~018 | ✅ |
-| 架构 | 添加 BatchTask 模型 | ✅ |
-| UX | 添加批量任务面板 | ✅ |
-| Epic | 创建 Epic 7 | ✅ |
-| Pipeline State | 更新计数 | ✅ |
+| ... | ... | ... |

 ## Phase 4 — 增量开发
 | Story | 标题 | 状态 |
 |-------|------|------|
-| 7-1 | BatchTask 数据模型 | ✅ PASS |
-| 7-2 | 批量任务 API | ✅ PASS |
-| 7-3 | 任务调度引擎 | ✅ PASS |
-| 7-4 | 批量任务面板 UI | ✅ PASS |
-| 7-5 | 批量任务仪表盘 | ✅ PASS |
-| 7-6 | 批量导出 | ✅ PASS |
-| 7-7 | 历史记录集成 | ✅ PASS |
+| ... | ... | ... |

 ## Phase 5 — 回归验证
- Epic 1-6: ✅ 全部 PASS (26/26)
+- 结果: PASS / FAIL / SKIPPED
+- 详情: {regression_details}

 ## Phase 5 — 旅程验证
- 10/10 旅程全部 PASS
+- 结果: PASS / FAIL / SKIPPED
+- 详情: {journey_details}

 ## 文件变更统计
 - 新增文件: {count}
 - 修改文件: {count}
 - 删除文件: {count}
-
-## 测试结果
- 单元测试: {passed}/{total} passed
- E2E 测试: {passed}/{total} passed
- 回归测试: {passed}/{total} passed
- 旅程验证: {passed}/{total} passed
 ```

 ### Step 5.4: 更新最终状态
@@ -120,9 +133,9 @@ result: success
 ```yaml
 phase-05-verify:
  regression: completed
-  regression_result: PASS | FAIL
-  journey: completed  # 回归 PASS 后自动执行
-  journey_result: PASS | FAIL
+  regression_result: PASS | FAIL | SKIPPED
+  journey: completed | skipped
+  journey_result: PASS | FAIL | SKIPPED
 ```

 ## 错误处理
@@ -131,16 +144,20 @@ phase-05-verify:
 IF 回归测试发现退化:
    → 记录退化的 Story
    → 生成退化报告
-    → 不自动修复，建议用户决定处理方式
    → 跳过旅程验证（功能不完整时测旅程无意义）
+    → 在变更报告中标注

 IF 回归 PASS 但旅程验证 FAIL:
    → 记录失败的旅程
-    → 尝试自动修复（最多 3 轮）
-    → 仍然 FAIL 则报告给用户
+    → 在变更报告中标注

 IF Phase 4 开发部分失败:
    → 跳过 Phase 5
    → 在报告中标注失败项
    → 建议用户使用 d8d-dev --story 逐个修复
+
+IF Skill tool 调用 d8d-dev 失败:
+    → 检查 d8d-dev 技能是否存在
+    → 检查 pipeline-state.yaml 是否一致
+    → 记录错误，报告给用户
 ```
--- a/.claude/skills/d8d-iterate/workflow.md
+++ b/.claude/skills/d8d-iterate/workflow.md
@@ -51,7 +51,7 @@
                       ↓
              ┌─────────────────┐
              │    Phase 2      │ 文档增量更新 (按需)
-              │    UPDATE-DOCS  │ edit-prd → update arch/ux → new epic
+              │    UPDATE-DOCS  │ edit-prd → update arch/ux → new epic → update journeys
              └────────┬────────┘
                       ↓
              ┌─────────────────┐
@@ -113,6 +113,7 @@ target_epic: epic-N  # 如果适用
 - 架构: 添加新模型/路由
 - UX: 添加新页面模式
 - Epic: 创建新 Epic 及 Story
+- 旅程: 需要增量更新的旅程列表（无/如下）
 ```

 **iterate-progress.md**:
@@ -199,3 +200,4 @@ Phase 5 — 旅程验证:
 3. **状态持久化**：每个 Phase 完成后更新三个状态文件
 4. **错误恢复**：Phase 失败时记录状态，支持从断点恢复
 5. **复用子技能**：通过 Skill tool 调用 d8d-requirements/d8d-prototype/d8d-dev，不重新实现
+6. **自动提交推送**：每个 Phase 产生代码变更后立即 git commit + git push，不询问用户。包括 bug 修复、文档更新、状态文件变更 — 全部自动提交推送
--- a/.claude/skills/d8d-prototype/steps/step-01-analyze.md
+++ b/.claude/skills/d8d-prototype/steps/step-01-analyze.md
@@ -8,7 +8,7 @@

 ## 执行序列

-### 1.1 检查可复用的现有素材 + .pen 设计文件提取
+### 1.1 检查可复用的现有素材

 在开始生成之前，**先检查项目中是否有客户/设计师提供的现有页面或设计素材**：