| 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 追加格式
每次成功修复后追加：
## [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 初始化模板
# 测试-修复轮次追踪表
> 由 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）
