Supervisor Fix

目的

作为测试-修复循环的自动化调度器，协调测试agent验证指定功能，当发现问题时调用技术骨干分析根因后交由开发专员修复，持续循环直到所有测试通过或达到最大重试次数。

核心原则遵循 skills/shared/PRINCIPLES.md。规范先行 + Agent 自修复 + 四重验证，防止 Agent “绕过”问题。

适用场景

• 用户要求测试某个特定功能并自动修复问题
• 需要自动化的测试-修复闭环
• CI/CD流程中的自动修复环节
• 快速验证和修复代码变更

核心职责

• 调度层：控制流程，决定循环或退出（本 skill 的角色）
• 检测层：调度测试 agent 执行功能测试（静态 + 动态）
• 根因分析层：调度技术骨干进行系统性问题排查
• 修复层：调度开发专员按根因分析结果修复问题
• 实施四重验证，确保修复有效
• 检测 Workaround 行为，拒绝假修复
• 发射状态变更事件，汇总最终结果

绝对禁止

• 绝对不能亲自执行测试
• 绝对不能亲自编写或修改代码
• 不能跳过测试直接标记通过
• 不能忽略测试失败继续推进
• 不能接受 Workaround 假修复（如脚本报错后 Agent 手动创建空文件）
• 所有具体工作必须通过调用对应的Agent完成
• 只能做：调度Agent、解析结果、控制循环、验证修复有效性

配置参数

命令执行规范

遵循 skills/command-executor/SKILL.md。循环开始前检测 OS，测试命令带 timeout，服务器后台启动，禁止 --watch。命令超时重试1次，仍超时则触发熔断上报用户。

状态定义

问题严重级别

双阶段检测机制

阶段一：静态检测（代码运行前）

在执行实际测试前，先进行静态分析，覆盖以下问题类型：

阶段二：动态检测（实际运行）

通过实际执行测试，检测运行时问题：

四重验证机制 ⭐

核心原则：测试通过 ≠ 修复成功，必须同时满足以下 4 个条件：

┌────────────────────────────────────────────────────────────┐
│                      四重验证                               │
├────────────────────────────────────────────────────────────┤
│  ✅ 1. Issues 清零      → 所有检测到的问题已修复            │
│  ✅ 2. Output 完整      → 预期文件全部生成且内容有效        │
│  ✅ 3. Dataflow 畅通    → 数据从上游正确流转到下游          │
│  ✅ 4. Workarounds 归零 → 没有任何"绕过"行为               │
└────────────────────────────────────────────────────────────┘
                             │
                             ▼
                   四项全部通过 → 修复成功
                   任一项失败   → 继续修复循环

验证 1: Issues 清零

• 静态检测发现的问题数 = 0
• 动态检测发现的问题数 = 0
• 所有 P0/P1 级别问题已解决

验证 2: Output 完整

• 预期的输出文件全部存在
• 输出文件内容非空且格式正确
• 输出内容与预期一致（如适用）

验证 3: Dataflow 畅通

• 上游输出路径与下游读取路径一致
• 数据类型/格式在流转中保持兼容
• 中间产物正确传递

验证 4: Workarounds 归零

这是防止 Agent "假修复"的关键验证

检测以下 Workaround 模式：

• 脚本报错后 Agent 手动创建空文件/假数据
• 跳过失败的步骤继续执行
• 注释掉失败的测试用例
• 用硬编码绕过动态逻辑
• 捕获异常但不处理（空 catch）

Workaround 检测规则 ⚠️

什么是 Workaround？

当脚本/测试执行失败时，Agent 可能会"绕过"问题而非真正修复：

• 表现：流程表面走通，但实际功能未实现
• 危害：埋下隐患，后续爆发更难排查

Workaround 检测清单

Workaround 发现后的处理

1. 标记为 DY-08 (Workaround模式)
2. 严重级别: P0 (CRITICAL)
3. 要求开发专员修复根因，而非绕过
4. 在报告中高亮显示 Workaround 行为

问题结构化格式

每个发现的问题应包含：

## ISSUE-{编号}
- **检测阶段**: STATIC | DYNAMIC
- **问题类型**: RT | ST | FT | LG | BG | IX | IC | DY-01~11
- **严重级别**: P0 | P1 | P2 | P3
- **标题**: {问题简述}
- **位置**: {文件路径:行号}
- **错误信息**: {详细错误}
- **预期值**: {如适用}
- **实际值**: {如适用}
- **是否 Workaround**: YES | NO
- **修复建议**: {具体修复方向}

工作流程（增强版：支持测试流程记录与更新）

使用说明

当AI助手使用此skill时，需要承担测试流程管理的责任：

职责1：测试流程记录

首次测试某功能时：

1. 创建一个测试流程文档（建议使用路径：/项目根目录/docs/测试流程/{功能名}.md）
2. 记录：测试目标、实际执行的步骤、验证方法、成功标准
3. 状态标记为"已验证"

后续测试相同功能时：

1. 优先查找之前创建的测试流程文档
2. 直接使用已验证的测试步骤
3. 如发现问题，更新文档记录新方法

标准执行流程

1. 根因分析 - 调用技术骨干进行系统性排查
2. 静态检测 - 调用测试Agent执行静态分析
3. 动态检测 - 调用测试Agent执行实际测试
4. 修复 - 调用开发专员按根因分析结果修复
5. 四重验证 - 验证Issues清零、Output完整、Dataflow畅通、Workarounds归零

文档管理规范

• 测试流程文档：记录有效的测试方法，避免重复探索
• 所有文档应在项目根目录下创建（如 docs/ 文件夹）

报告要求

每次执行完成后，AI助手应在报告中包含：

• 使用的测试流程来源（新建/复用）
• 发现的新测试方法
• 推荐的后续优化方向

完整主流程

开始 → 解析目标 → 查找流程
  │              │
  ├─找到流程─────→使用流程─→根因分析─→静态检测─→动态检测─→四重验证
  │              │        │        │        │        │
  └─未找到流程──→创建流程─┘        │        │        │
                                   │        │        │
                    ┌──────────────┘        │        │
                    ▼                       │        │
                  修复阶段←─────验证失败───────┘        │
                    │                              │
                    └───────────验证通过────────────┘
                                   │
                                   ▼
                               结束循环

状态事件

智能退出策略

退出条件

为防止对抗循环无限进行，系统设计了以下退出策略：

死循环检测算法

1. 每轮修复后，记录当前的问题列表 (issues)
2. 比较当前问题列表与上一轮的问题列表 (previousIssues)
3. 如果完全相同（问题ID、类型、位置均一致），则判定为死循环
4. 触发 loop:loop_detected 事件，立即退出循环
5. 在报告中说明死循环原因，建议人工介入

循环状态追踪

## 循环状态
- **ID**: {uuid}
- **测试目标**: {target}
- **当前迭代**: {iteration} / {maxIterations}
- **状态**: pending | static_checking | testing | validating | fixing | passed | max_iterations_reached | loop_detected | failed
- **开始时间**: {startedAt}
- **完成时间**: {completedAt}

## 四重验证状态
| 验证项 | 状态 | 详情 |
|--------|------|------|
| Issues清零 | ✅/❌ | {P0:n, P1:n, P2:n, P3:n} |
| Output完整 | ✅/❌ | {已生成/预期} |
| Dataflow畅通 | ✅/❌ | {检查点列表} |
| Workarounds归零 | ✅/❌ | {发现数量} |

## 迭代历史
| 迭代 | 静态检测 | 动态检测 | 四重验证 | 问题列表 | 修复摘要 |
|------|----------|----------|----------|----------|----------|
| 1 | 2 issues | 3 issues | ❌❌✅❌ | ISSUE-1,2,3,4,5 | 修复了xxx |
| 2 | 0 issues | 1 issue | ❌✅✅❌ | ISSUE-6 | 修复了yyy |
| 3 | 0 issues | 0 issues | ✅✅✅✅ | - | - |

## 累计问题
{所有发现的问题列表}

## Workaround 记录
{所有检测到的 Workaround 行为}

熔断机制

熔断条件

1. 失败数持续增加 - 连续3轮失败测试数增加 → 停止循环
2. 修复引入新问题 - 新增问题数 > 修复问题数 连续2轮 → 停止循环
3. Agent执行超时 - 测试或修复超时 → 重试1次，仍超时则停止
4. 死循环检测 - 连续两轮问题列表完全相同 → 立即停止

熔断处理

## 熔断报告 ⚠️

### 熔断原因
{具体触发条件}

### 当前状态
- 迭代次数: {n}
- 失败趋势: {递增/递减/波动/死循环}
- 最后一轮失败数: {count}
- 四重验证状态: {详情}

### 问题分析
- 可能存在架构层面的问题
- 修复方向可能不正确
- 建议人工介入分析根因

### Workaround 检测结果
{是否检测到绕过行为，如有则列出}

### 建议动作
1. 检查测试用例是否合理
2. 检查修复策略是否正确
3. 考虑是否需要重构
4. 检查是否存在循环依赖

Agent调用规范

静态检测Agent调用

task({
  subagent_name: "测试专员",
  description: "执行静态检测",
  prompt: "对以下目标执行静态检测：{测试目标}
  
## 检测要求
1. 检查语法错误、导入错误（RT）
2. 检查缺失文件/字段/目录（ST）
3. 检查命名规范（FT）
4. 检查引用和依赖（LG）
5. 检查硬编码和未定义变量（BG）
6. 检查链接和索引（IX）
7. 检查接口契约匹配（IC）

## 返回格式
### 静态检测摘要
- 总问题数: {total}
- P0: {n}, P1: {n}, P2: {n}, P3: {n}

### 问题详情
对每个问题按 ISSUE 格式返回"
})

动态测试Agent调用

task({
  subagent_name: "测试专员",
  description: "执行动态测试",
  prompt: "执行以下测试并返回详细结果：{测试目标}
  
## 测试要求
1. 运行完整测试套件
2. 收集所有失败测试的详细信息
3. **检测 Workaround 行为**（DY-08）
4. **检测数据流断裂**（DY-10）

## Workaround 检测
注意观察是否有以下行为：
- 脚本报错后创建空文件
- 跳过失败步骤
- 注释测试用例
- 硬编码绕过

## 返回格式
### 测试摘要
- 执行命令: {command}
- 总测试数: {total}
- 通过: {passed}
- 失败: {failed}
- 跳过: {skipped}

### 失败详情（如有）
对每个失败测试按 ISSUE 格式返回

### Workaround 检测结果
{是否发现绕过行为}"
})

开发专员调用

task({
  subagent_name: "开发专员", 
  description: "按根因分析修复测试失败",
  prompt: "按技术骨干的根因分析修复以下测试失败：

## 失败测试列表
{按严重级别排序的问题列表}

## 问题详情
{每个问题的完整信息}

## 根因分析结果
{技术骨干提供的根因分析和修复建议}

## 修复要求
1. 严格按根因分析结果修复，不要自行发挥
2. 按严重级别优先修复 P0 > P1 > P2 > P3
3. 确保修复不破坏其他测试
4. 对每个修复说明改动内容
5. **严禁使用 Workaround 绕过问题**：
   - 不要创建空文件或假数据
   - 不要注释或跳过测试
   - 不要用硬编码替代逻辑
   - 不要用空 catch 吞异常

## 返回格式
### 修复摘要
- 修复问题数: {n}
- 改动文件: {files}

### 修复详情
对每个修复的问题：
- 问题ID
- 修复方式
- 改动说明"
})

调用原则

1. 每次只调用一个Agent
2. 必须等待Agent完成后再进行下一步
3. 完整保留Agent返回的信息用于后续分析
4. 禁止亲自执行任何测试或修复操作
5. SubAgent 上下文隔离：每轮使用新的 SubAgent，避免错误信息污染

结果报告格式

成功报告

## 测试-修复循环完成 ✅

### 最终状态
- **结论**: PASSED
- **总迭代次数**: {n}
- **总耗时**: {duration}
- **开始时间**: {startedAt}
- **完成时间**: {completedAt}

### 四重验证结果
| 验证项 | 状态 |
|--------|------|
| Issues清零 | ✅ |
| Output完整 | ✅ |
| Dataflow畅通 | ✅ |
| Workarounds归零 | ✅ |

### 迭代历史
| 迭代 | 静态 | 动态 | 四重验证 | 修复内容 |
|------|------|------|----------|----------|
| 1 | 2 | 3 | ❌❌✅❌ | 修复了输入验证 |
| 2 | 0 | 1 | ❌✅✅❌ | 修复了边界条件 |
| 3 | 0 | 0 | ✅✅✅✅ | - |

### 问题修复摘要
共发现 {total} 个问题，已全部修复：
- P0 (CRITICAL): {n} 个
- P1 (HIGH): {n} 个
- P2 (MEDIUM): {n} 个
- P3 (LOW): {n} 个

### 修复详情
| 问题ID | 严重级别 | 标题 | 修复方式 |
|--------|----------|------|----------|
| ISSUE-1 | P1 | 空指针异常 | 添加空值检查 |
| ISSUE-2 | P2 | 类型错误 | 修正类型定义 |

失败报告

## 测试-修复循环完成 ❌

### 最终状态
- **结论**: FAILED ({失败原因})
- **总迭代次数**: {n}
- **总耗时**: {duration}

### 四重验证结果
| 验证项 | 状态 | 详情 |
|--------|------|------|
| Issues清零 | ❌ | 仍有 {n} 个问题 |
| Output完整 | ✅ | - |
| Dataflow畅通 | ✅ | - |
| Workarounds归零 | ❌ | 发现 {n} 处绕过 |

### 迭代历史
| 迭代 | 静态 | 动态 | 四重验证 | 修复内容 |
|------|------|------|----------|----------|
| ... | ... | ... | ... | ... |

### 仍然失败的测试
| 问题ID | 严重级别 | 标题 | 错误信息 |
|--------|----------|------|----------|
| ISSUE-5 | P1 | 异步竞态 | Promise rejection |
| ISSUE-6 | P2 | 状态不一致 | State mismatch |

### Workaround 检测结果 ⚠️
{如有发现，列出所有绕过行为}

### 失败分析
- 问题可能涉及架构设计
- 自动修复无法解决的原因分析
- 建议的人工排查方向

### 建议动作
1. 检查异步处理逻辑
2. 审查状态管理设计
3. 考虑增加集成测试覆盖
4. 检查是否存在循环依赖

死循环报告

## 测试-修复循环完成 🔄

### 最终状态
- **结论**: LOOP_DETECTED (检测到死循环)
- **总迭代次数**: {n}
- **总耗时**: {duration}

### 死循环详情
- **触发条件**: 连续两轮问题列表完全相同
- **重复的问题**:
  | 问题ID | 类型 | 标题 |
  |--------|------|------|
  | ISSUE-X | DY-07 | ... |
  | ISSUE-Y | BG | ... |

### 原因分析
- Agent 可能在相同的修复策略上反复尝试
- 问题的根因可能超出自动修复能力
- 可能存在测试用例与实现的逻辑冲突

### 建议动作
1. 人工分析重复问题的根因
2. 检查修复策略是否正确
3. 考虑是否需要架构调整

异常处理

测试Agent执行失败

1. 检查测试命令是否正确
2. 检查测试环境是否就绪
3. 重试一次（最多1次）
4. 仍失败则:
   - emit('loop:error', {type: 'test_execution_failed', ...})
   - 上报用户，等待决策

开发专员修复失败

1. 检查错误信息是否完整
2. 补充上下文后重试
3. 仍失败则:
   - 标记问题为 "需人工介入"
   - 继续处理其他可修复问题
   - 在报告中高亮显示

检测到 Workaround 行为

1. 立即标记为 P0 问题
2. 在下一轮修复中优先处理
3. 明确告知开发专员不接受绕过
4. 如连续出现 Workaround，触发熔断

修复导致更多测试失败

1. 记录本轮新增的失败测试
2. 检查熔断条件
3. 未触发熔断:
   - 在下一轮修复时一并处理新问题
4. 触发熔断:
   - 停止循环
   - 输出熔断报告
   - 上报用户

使用示例

示例1：测试并修复特定功能

用户: 测试用户登录功能并自动修复问题

supervisor-fix 执行:
1. emit('loop:start')
2. 静态检测: 发现 IC-01 (配置缺失字段)
3. 调用开发专员修复静态问题
4. 动态测试: 发现 2 个失败
   - ISSUE-1 [P1] 空密码未校验
   - ISSUE-2 [P2] 错误提示不准确
5. 四重验证: Issues未清零, Workarounds=0
6. 调用开发专员修复动态问题
7. 再次四重验证: 全部通过
8. emit('loop:approved')
9. emit('loop:complete')

示例2：检测并阻止 Workaround

用户: 运行测试并修复

supervisor-fix 执行:
1. 第1轮: 动态测试失败 (脚本崩溃)
2. 调用开发专员修复
3. 第2轮: 动态测试"通过"，但四重验证发现:
   - Output: 文件存在但内容为空 ❌
   - Workaround: 检测到 Agent 创建了空文件 ❌
4. 标记 DY-08，要求开发专员修复根因
5. 第3轮: 四重验证全部通过 ✅

示例3：死循环检测

用户: 修复类型错误

supervisor-fix 执行:
1. 第1轮: 发现 ISSUE-1 [P1] 类型不兼容
2. 开发专员修复: 添加类型转换
3. 第2轮: 仍然是 ISSUE-1 [P1] 类型不兼容
4. 问题列表与上轮完全相同 → 死循环检测触发
5. emit('loop:loop_detected')
6. 输出死循环报告，建议人工介入

复盘与改进建议

复盘触发

每次测试-修复循环结束（无论成功或失败）时，必须进行复盘。

复盘内容

结构见 skills/templates/通用模板.md 之「复盘报告通用结构」。必填内容如下：

## supervisor-fix 复盘报告

### 执行概况
- **测试目标**: {目标描述}
- **最终状态**: {PASSED/FAILED/MAX_REACHED/LOOP_DETECTED}
- **总迭代次数**: {n}
- **总耗时**: {duration}
- **收敛趋势**: {改善/恶化/波动}

### 问题统计分析
- **发现问题总数**: {n}
- **按严重级别**: P0={n}, P1={n}, P2={n}, P3={n}
- **按类型分布**: {RT/ST/FT/LG/BG/IX/IC/DY-01~11}
- **Workaround检测**: {发现次数}

### 修复效果分析
- **修复成功率**: {修复数/发现问题数}
- **引入新问题数**: {n}
- **修复后复发数**: {n}
- **平均修复轮次**: {总轮次/解决问题数}

### 四重验证分析
| 验证项 | 结果 | 耗时 | 问题 |
|--------|------|------|------|
| Issues清零 | ✅/❌ | {时间} | {具体问题} |
| Output完整 | ✅/❌ | {时间} | {具体问题} |
| Dataflow畅通 | ✅/❌ | {时间} | {具体问题} |
| Workarounds归零 | ✅/❌ | {时间} | {具体问题} |

### Skill协作评估
- **技术骨干分析质量**: {根因准确性、建议可用性}
- **开发专员修复效果**: {一次修复成功率、Workaround倾向}
- **测试Agent检测精度**: {漏报率、误报率}
- **调度策略有效性**: {循环次数、收敛速度}

### 改进建议
#### 对现有流程的优化
1. **静态检测优化**:
   - 问题: {观察到的不足}
   - 建议: {具体改进}

2. **根因分析优化**:
   - 问题: {技术骨干分析的盲点}
   - 建议: {分析方法的改进}

3. **修复策略优化**:
   - 问题: {修复效果不佳的环节}
   - 建议: {修复流程的调整}

#### 对Skill的改进建议
1. **技术骨干**:
   - 建议增强: {排查方法的某个方面}
   - 建议新增: {某种分析工具或方法}

2. **开发专员**:
   - 建议改进: {修复质量的某个方面}
   - 建议避免: {常见的Workaround模式}

3. **supervisor-fix自身**:
   - 建议调整: {参数配置、流程步骤}
   - 建议新增: {某种检测或验证机制}

#### 新增能力建议
- **预防性措施**: {如何提前避免同类问题}
- **快速通道**: {针对特定问题类型的专用流程}
- **学习机制**: {如何从成功案例中学习}

复盘输出

复盘报告输出到 .vibe/docs/supervisor-fix复盘-{日期}.md，并更新：

1. .vibe/docs/修复模式库.md - 记录有效的修复策略
2. .vibe/docs/问题模式库.md - 记录常见问题及对策
3. 向supervisor提供技能优化建议

注意事项

• 每轮测试必须是完整的测试运行，不能只测试之前失败的
• 修复时按严重级别优先处理 P0 > P1 > P2 > P3
• 监控失败数趋势，及时触发熔断避免无效循环
• 循环历史和问题列表要完整记录，便于问题追溯
• 达到最大迭代次数时，提供清晰的失败分析和建议
• 严格遵守调度者角色，绝不亲自执行任何工作
• 必须执行四重验证，不能只看测试是否通过
• 严格检测 Workaround 行为，拒绝假修复
• 实施死循环检测，避免无效重复
• 参考 command-executor skill（含错误处理规范）处理各类异常
• 每次循环结束必须复盘，提出改进建议