---
name: bug-fix-loop-coordinator
description: Bug修复循环协调者。测试完成后，读取技术问题追踪台，按P0→P1→P2顺序协调修复，每修复一个触发针对性回归测试，循环直至P0+P1全清，输出可上线结论。所有信息通过文档传递，不依赖对话历史。触发词：「全自动修复循环」「按Bug清单修复」「修复所有问题」「循环修复到上线」「开始bug修复循环」。
---

# Bug 修复循环协调者（bug-fix-loop-coordinator）

> **核心定位**：测试→修复→回归的自动循环引擎。
> 信息传递媒介：全程通过文档（追踪台、修复记录、轮次追踪表）交换状态，不依赖对话历史。
> 终止条件：`技术问题追踪台.md` 中 P0=0 且 P1=0，全量回归通过。

---

## 知识导航表（执行前必读）

| 层级 | 文档 | 用途 |
|---|---|---|
| **D0 认知根** | `_内部总控/认知结构/L1_系统性文档/技术架构思维维度/知识库/测试后Bug修复到上线全流程_调研_20260324.md` | 修复流程最佳实践：先复现→TDD→最小改动→回归 |
| **D0-AI** | `_内部总控/认知结构/L1_系统性文档/技术架构思维维度/知识库/AI_Agent平台生产架构_调研_20260325.md` | **AI 平台架构全景（Layer 0-9，含代码示例和生产数据）**；修复排序规则见 `_内部总控/开发规范/AI平台架构分层框架.md`（薄包装层）|
| **D1 项目追踪** | `项目群/[项目]/技术架构师/技术问题追踪台.md` | 信息源：所有 Bug 的状态（未解决/修复中/已修复/回归通过）|
| **D2 轮次记录** | `项目群/[项目]/3_开发计划/test-round-tracker.md` | 循环进度追踪：第几轮，上一轮的状态快照 |
| **D3 测试规格** | `项目群/[项目]/测试工程师/test-spec-*.md`（最新版）| 回归测试的执行标准 |
| **D4 修复记录** | `项目群/[项目]/内部总控/修复记录.md` | 每次修复的 TDD 证据 |

---

## 核心设计原则

```
单一信息源：技术问题追踪台.md 是唯一的 Bug 状态来源
  → 所有角色只写入追踪台，不通过对话传递 Bug 信息

文档驱动循环：
  追踪台有未解决P0/P1 → 继续循环
  追踪台P0+P1清零 + 全量回归通过 → 退出循环

TDD 约束（通过 bug-fix-tdd-guard Rule 强制执行）：
  修复顺序：先写失败测试 → 再改代码 → 再运行全量CI
  
最小改动原则：
  每个 Bug 独立 PR，不合并，不借机重构
```

---

## 激活后立即执行

```
Step 0  【确认项目路径】
        从对话上下文确认当前项目目录
        Read: 项目群/[项目]/技术架构师/技术问题追踪台.md
        → 若文件不存在：
          告知用户「技术问题追踪台不存在，请先运行测试工程师（关卡C）生成追踪台」
          停止执行
        → 存在则继续

Step 1  【轮次记录初始化】
        Read: 项目群/[项目]/3_开发计划/test-round-tracker.md
        → 若不存在：从模板创建（见附录A）
        → 记录当前轮次号 N = 已有轮次数 + 1
        更新 test-round-tracker.md，写入本轮开始状态：
          - 轮次 N
          - 开始时间
          - 本轮来自上一轮的遗留 Bug 数（读追踪台统计）

Step 1.5  【D0 产品认知根确认——在处理任何 Bug 之前】
        
        这一步确保修复循环始终在「产品意图」的框架下运行，
        而不是纯粹根据技术严重程度做决策。
        
        Read: 项目群/[项目]/产品经理/产品定义.md（或等价路径）
        
        提取并记录以下内容作为本轮循环的「产品上下文」：
        
        1. 核心价值承诺（产品对用户最重要的 3 条承诺）
        2. 各功能闭环（A/B/C/D/E/F）的用户价值
        3. 产品诚信强制项（标注了「强制设计规则」的条目）
        4. 当前 MVP 边界（哪些在范围内，哪些不在）
        
        将此上下文写入本轮循环的「产品视角评估基准」（内存中持有，dispatch 时传递给 fixer）
        
        IF 产品定义不存在：
          → 警告：「⚠️ 未找到产品定义文档。修复循环将只能做「不影响用户行为」的技术修复。
                    涉及用户可见行为的 Bug 需要产品定义支持，请先创建产品定义。」
          → 继续，但标记所有涉及用户行为的 Bug 为「需人工决策」

Step 1.8  【架构层分类（AI 平台专项，替代纯 P0/P1/P2 排序）】
        Read: _内部总控/开发规范/AI平台架构分层框架.md
        
        对追踪台中所有未解决 Bug 进行架构层标注：
          Layer 0/1（部署模型/状态管理）：状态不持久化、build lock、任务可见性等
          Layer 2（并发模型）：rate limit、并发死锁、资源竞争
          Layer 3（LLM 调用管理）：截断、context 不完整、token 超限
          Layer 4（数据隔离）：跨用户数据串扰
          Layer 5（Agent 框架）：路由绕过、工作流入口混乱、工具调用错误
          Layer 6-9（可观测/安全/性能/扩展）：监控缺失、注入风险等
          前端：UI/交互/显示问题
        
        修复排序原则（从 AI平台架构分层框架.md）：
          1. 先修低层（Layer 0/1 优先于 Layer 5 优先于前端）
          2. 同层内：AI 确定先修，AI 不确定列出选项等用户决策
          3. 不用 P0/P1/P2 作为主排序轴（仅作同层内参考）
        
        构建架构层排序后的执行队列：
        arch_sorted_queue = [
          [Layer 1] BUG-XX（状态管理问题），
          [Layer 3] PRIN-01-XX（LLM截断）× N，
          [Layer 5] BUG-YY（Agent框架问题），
          [前端] BUG-ZZ（UI问题），
          ...
        ]
        
        输出摘要：
        「🏗️ 架构层分析完成：
         Layer 1（状态管理）：N 个
         Layer 3（LLM调用）：N 个
         Layer 5（Agent框架）：N 个
         前端：N 个
         
         修复将从 Layer 1 开始，逐层推进。」

Step 2  【读取 Bug 清单 + 产品影响评估 + 构建层序队列】
        Read: 技术问题追踪台.md
        
        统计（辅助参考）：
        - P0_bugs = [未解决的P0列表]
        - P1_bugs = [未解决的P1列表]
        - P2_bugs = [未解决的P2列表]
        
        【产品影响判断（标注，不改变层序主轴）】
        使用 Step 1.5 的「产品上下文」，对每个 Bug 判断产品重要性：
        □ 破坏产品核心价值承诺 → 标注「产品高优」
        □ 涉及产品诚信问题 → 标注「产品高优」
        □ 出现在认知飞轮关键节点 → 标注「产品高优」
        
        【构建层序修复队列（主轴：架构层，第二轴：AI确定/不确定）】
        参考 Step 1.8 的层分类结果，构建最终队列：
          [L1 层 Bug（AI确定）] → [L1 层 Bug（AI不确定，等决策）] →
          [L3 层 Bug（AI确定）] → ... → [FE Bug] → ...
        
        同层内「产品高优」标注的 Bug 排在其他 Bug 前面
        
        IF 所有 Bug 均已清零：
          → 跳至 Step 7（触发全量回归）
        
        输出摘要：
        「📊 第 N 轮修复循环（层序）
         架构层：L1=N | L3=N | L5=N | FE=N
         辅助：P0=N | P1=N | P2=N
         修复顺序：先低层（L1→FE），同层内 AI 确定优先」

Step 3  【按层序逐条修复】
        FOR each bug in 层序队列:
          Step 3.1  输出当前Bug信息：
                    「🔧 处理 Bug: [TC-XXX] [架构层] [Bug描述]
                     复现步骤：[从追踪台读取]
                     涉及模块：[从追踪台读取]
                     AI 确定？[是/否]」
          
          IF AI 不确定（多方案或涉及设计决策）：
            → 列出选项，等待用户决策后再修复
          
          Step 3.2  确定负责角色：
                    - 后端Bug → role-后端开发
                    - 前端Bug → role-前端开发
                    - AI行为Bug → role-AI工程师
                    
          Step 3.3  Spawn fixer 子智能体执行修复（含产品上下文）：
                    Read: 修复记录.md（了解是否有类似修复参考）
                    
                    从 Step 1.5 的产品上下文中，提取与此 Bug 相关的功能描述
                    
                    调用 /fixer 子智能体（隔离上下文，防止开发偏见），传入：
                    ---
                    模式：单Bug修复（模式A）
                    Bug ID：[TC-XXX]
                    Bug描述：[从追踪台读取的完整描述]
                    失败现象：[从追踪台读取]
                    复现步骤：[从追踪台读取]
                    期望结果：[从 test-spec 读取对应验收标准]
                    涉及模块：[从追踪台读取]
                    代码库路径：[当前项目路径]
                    追踪台路径：[技术问题追踪台.md 完整路径]
                    修复记录路径：[修复记录.md 完整路径]
                    
                    【产品上下文（来自 Step 1.5）—— fixer D0 使用】
                    产品定义路径：[产品定义.md 完整路径]
                    相关功能描述：[从产品定义中提取与此 Bug 相关的功能段落]
                    用户价值承诺：[该功能对用户的核心价值，1-2句话]
                    产品诚信约束：[如有强制设计规则，列出]
                    ---
                    
                    ⚠️ 注意：fixer 必须先完成 D0（产品认知根确认）再开始技术修复。
                    如果 fixer 报告「这是产品设计问题，不是实现问题」→ 写入产品问题追踪台，不做技术修复。
                    
                    ⚠️ 为什么用子智能体而不是开发角色：
                    子智能体从干净上下文启动，不知道「协调者知道什么」，
                    以纯粹的怀疑者视角分析 Bug，避免「既知道答案又验证答案」的偏见。
          
          Step 3.4  等待 fixer 子智能体返回报告，解析结果：
                    
                    IF fixer 返回 status=success：
                      → 确认 TDD 证据存在（失败测试 + 通过测试 + CI 通过）
                      → 确认追踪台已更新（fixer 会自动更新，但要验证）
                      → 输出：「✅ [TC-XXX] fixer 报告修复成功」
                      → 继续 Step 3.5（独立回归验证）
                    
                    IF fixer 返回 status=escalated（3次失败）：
                      → 输出：「⚠️ [TC-XXX] fixer 三次修复失败，需人工介入」
                      → 更新追踪台状态为「需人工介入」
                      → 暂停当前 P0 处理，等待用户指令
                    
                    IF fixer 返回 status=cannot_reproduce：
                      → 输出：「⚠️ [TC-XXX] 无法复现，复现步骤需要更新」
                      → 向用户报告，请求提供更多复现信息
                    
                    输出：「▶️ 触发针对 [TC-XXX] 的独立回归验证...」
                    触发 role-测试工程师（回归模式），传入：
                      - 复现该Bug的测试用例
                      - 相关联的测试用例（影响范围内的）
                    
          Step 3.5  解析回归结果：
                    IF 回归通过:
                      更新 技术问题追踪台.md → 状态: 「已修复（轮次N，日期）」
                      追加到 修复记录.md（TDD证据：测试ID + 修复说明）
                      输出：「✅ [TC-XXX] 修复验证通过」
                    ELSE:
                      输出：「❌ [TC-XXX] 回归失败，重新分析...」
                      更新追踪台状态为「修复中（验证失败）」
                      回到 Step 3.2 重新分析根因（最多3次，超过则标记为「需人工介入」）
          
          Step 3.6  IF 本 Bug 标记「需人工介入」:
                    输出：「⚠️ [TC-XXX] 三次修复未通过回归，需要人工介入」
                    等待用户指令（暂停循环，不继续下一个P0）

Step 4  【P0 全清检查】
        Re-Read: 技术问题追踪台.md
        IF 仍有未解决P0:
          → 回到 Step 3（处理下一个P0）
        ELSE:
          → 输出「✅ P0 全清，开始处理 P1」
          → 继续 Step 5

Step 5  【P1 修复循环（类同 Step 3，严重程度 P1）】
        FOR each bug in P1_bugs（实时从追踪台读取最新列表）:
          [与 Step 3.1~3.6 相同的流程，severity = P1]
          
        P1 处理完毕后：更新 test-round-tracker.md（本轮P1修复完成）

Step 6  【本轮 P2 处置（默认自动跳过，除非调用方明确指定处理）】
        Read: P2_bugs（当前未解决P2列表）
        
        Read: p2_handling 参数（从调用方输入读取，默认 = "skip"）
        
        IF p2_handling == "skip"（默认）:
          → 输出 P2 清单（仅列表，不等待）：
            「📋 跳过 [P2_count] 个 P2（记入技术债，不阻止上线）：
             [ID] [描述]
             ...
             ⏩ 自动进入全量回归验证」
          → 将所有 P2 在追踪台标记为「已知技术债（跳过上线）」
          → 直接进入 Step 7
        
        IF p2_handling == "fix_all":
          → 与 P1 相同流程逐个修复，完成后进入 Step 7
        
        IF p2_handling == "ask"（仅当调用方明确传入时）:
          → 输出 P2 清单，暂停等待用户决策：
            「P2 不阻止上线。现在修还是跳过？[A/B/C]」
          → 等待用户回复

Step 7  【全量回归测试（上线前最终验证）】
        输出：「▶️ P0+P1 全清，触发全量回归测试...」
        触发 role-测试工程师（全量模式）：
          - 执行完整 test-spec 中所有测试用例
          - 传入：test-spec 路径、当前版本号
          
Step 8  【解析全量回归结果】
        IF 全量回归通过（无新P0/P1）：
          → 进入 Step 9（输出上线报告）
        ELSE 发现新 Bug（回归引入的）：
          更新追踪台：将新 Bug 写入（标注「Round N 全量回归发现」）
          更新 test-round-tracker.md（本轮发现新Bug）
          IF 新 Bug 有 P0/P1:
            → 输出：「⚠️ 全量回归发现新P0/P1，进入第 N+1 轮循环」
            → 回到 Step 1（轮次N+1）
          ELSE（只有P2新Bug）:
            → 更新追踪台
            → 回到 Step 6 让用户决策
            
Step 9  【收敛：输出可上线结论】
        Read: 技术问题追踪台.md（最终状态）
        Read: test-round-tracker.md（所有轮次记录）
        Read: 修复记录.md（所有修复的TDD证据）
        
        输出综合报告（写入 测试工程师/最终测试报告.md）：
        
        「✅ 测试-修复循环完成
        
         执行概览：
           共 N 轮修复循环
           修复 Bug 总数：P0×A + P1×B + P2×C
           全量回归：通过（Round N）
        
         Bug 处置情况：
           ✅ 已修复：[列表]
           📋 技术债（P2跳过）：[列表]
        
         可上线结论：✅ 所有阻塞问题已清除，可以进入 DevOps
         
         下一步：触发 role-DevOps 执行上线发布」
        
        触发 P0 Bug 的 Blameless Postmortem（若本次有P0）：
        「📝 建议：有 [P0_count_total] 个 P0 Bug，建议在上线后24h内完成 Postmortem
          路径：内部总控/Postmortem-[日期].md
          目的：分析为什么这些P0能逃过测试，改进测试体系」
```

---

## 文档更新规范

### 技术问题追踪台 状态流转

```
未解决 → 修复中 → 修复中（验证失败）→ 修复中
未解决 → 修复中 → 已修复（Round N, 日期）→ 回归通过（Round N）
未解决 → 需人工介入（3次修复失败）
```

### 修复记录.md 追加格式

每次成功修复后追加：

```markdown
## [TC-XXX] [Bug描述] — Round N — [日期]

**优先级**：P0 / P1 / P2
**根因**：[5 Whys 第一层结论]
**修复内容**：[修改了什么文件，改了什么]

**TDD 证据**：
- 失败测试（Red）：`tests/xxx/test_yyy.py::test_zzz`
- 修复后通过（Green）：✅
- 全量CI：✅（[CI运行时间]）

**回归验证**：[哪些测试用例被重新验证]
**合并记录**：[PR ID 或 commit hash]
```

---

## 循环终止条件（精确定义）

```
可以上线（退出循环）的条件：全部满足
  ① 技术问题追踪台.md 中 P0 未解决数 = 0
  ② 技术问题追踪台.md 中 P1 未解决数 = 0
  ③ 最近一轮全量回归测试通过（无新P0/P1）
  ④ 每个 P0/P1 修复都有对应的 TDD 证据（在修复记录.md）

不可上线（继续循环）的条件：任一满足
  ① 追踪台仍有未解决P0
  ② 追踪台仍有未解决P1
  ③ 全量回归发现新的P0/P1（即使历史P0/P1已清）
  ④ 有P0/P1修复没有通过回归测试
```

---

## 与其他角色的接口

**我读取**：
- `技术问题追踪台.md`（唯一信息源）
- `test-spec-*.md`（回归范围参考）
- `test-round-tracker.md`（轮次状态）

**我触发**（按需调用）：
- `role-后端开发` / `role-前端开发` / `role-AI工程师`（修复）
- `role-测试工程师`（回归测试）
- `issue-tracker`（新发现的 Bug 写入追踪台）

**我写入**：
- `test-round-tracker.md`（轮次进度）
- `修复记录.md`（修复历史和TDD证据汇总）
- `测试工程师/最终测试报告.md`（收敛后的综合报告）

---

## 附录 A：test-round-tracker.md 初始化模板

```markdown
# 测试-修复轮次追踪表

> 由 bug-fix-loop-coordinator 自动维护
> 记录每轮测试→修复的进度，作为循环协调的状态机

| 轮次 | 日期 | 范围 | P0开始 | P1开始 | P2开始 | P0结束 | P1结束 | P2结束 | 新Bug | 结论 |
|------|------|------|--------|--------|--------|--------|--------|--------|-------|------|
| 初始（测试后）| - | 全量测试 | - | - | - | [P0] | [P1] | [P2] | - | 待修复 |

> 初始行由 role-测试工程师 关卡C 完成后填入
> 后续每轮由 bug-fix-loop-coordinator 维护
```

---

## 变更记录

### v1.0 — 2026-03-24 — 初始创建

**根因**：当前 Skill 体系中测试（role-测试工程师）和修复（各开发角色）之间缺乏协调机制。测试发现 Bug 后需要人工判断优先级、手动触发修复、手动触发回归，整个过程不能自动持续到产品达到上线标准。

**设计决策**：
- 单一信息源（追踪台）驱动循环，不依赖对话历史 → 支持跨会话持久化
- TDD 约束由 `bug-fix-tdd-guard` Rule 在开发角色激活时强制注入，而非在此 Skill 内用文字约束
- 循环终止条件精确量化（追踪台P0+P1=0 + 全量回归通过）
- P2 处理让用户决策（不强制，因为P2不阻止上线）

**Level**：L3 集成型（与 role-测试工程师、issue-tracker、fixer子智能体、bug-fix-tdd-guard Rule 联动）

**配套**：
- 新建 `.cursor/rules/bug-fix-tdd-guard.mdc`
- 新建 `.cursor/agents/fixer.md`（修复子智能体，Step 3.3 dispatch 对象）
- 新建 `test-round-tracker.md` 模板（项目级文档）
- 更新 `role-menu.mdc` 注册触发词

### v1.2 — 2026-03-24 — Step 6 P2 默认自动跳过（不暂停等待人工决策）

**根因**：v1.1 的 Step 6 在 P2 处理时暂停等待用户选择，打断了全自动循环。
Agent 拥有完整权限，P2 不阻止上线，应默认自动跳过，只在调用方明确传入 p2_handling="ask" 时才暂停。

**修改内容**：
- Step 6：从「暂停等待用户决策」改为「p2_handling 参数驱动，默认=skip 自动跳过」

---

### v1.1 — 2026-03-24 — Step 3.3 改为 spawn fixer 子智能体

**根因**：v1.0 dispatch「对应开发角色」，但开发角色是 Skill（需用户触发），不是可被 spawn 的子智能体。fixer 子智能体创建后，应直接 spawn 以实现隔离上下文修复，防止协调者的上下文污染修复过程。

**修改内容**：
- Step 3.3：从「触发对应开发角色」改为「spawn /fixer 子智能体（模式A）」
- Step 3.4：从「开发角色完成修复后」改为「解析 fixer 报告，根据 status 分支处理」
- 新增：fixer 的三种返回状态处理（success/escalated/cannot_reproduce）