workflow-test-fix-cycle

工作流测试修复循环

端到端测试修复工作流管道：生成包含渐进式层级（L0-L3）的测试会话、AI 代码验证和任务生成（阶段 1），然后执行迭代修复循环，并通过自适应策略引擎持续运行，直至通过率 >= 95%（阶段 2）。

架构概览

┌────────────────────────────────────────────────────────────────────────────┐
│  Workflow Test-Fix Cycle Orchestrator (SKILL.md)                            │
│  → Full pipeline: Test generation + Iterative execution                     │
│  → Phase dispatch: Read phase docs, execute, pass context                   │
└───────────────┬────────────────────────────────────────────────────────────┘
                │
   ┌────────────┴────────────────────────┐
   ↓                                     ↓
┌─────────────────────────┐   ┌─────────────────────────────┐
│ Phase 1: Test-Fix Gen   │   │ Phase 2: Test-Cycle Execute  │
│ phases/01-test-fix-gen  │   │ phases/02-test-cycle-execute │
│ 5 sub-phases:           │   │ 3 stages:                    │
│ ① Create Session        │   │ ① Discovery                  │
│ ② Gather Context        │   │ ② Main Loop (iterate)        │
│ ③ Test Analysis (Gemini)│   │ ③ Completion                 │
│ ④ Generate Tasks        │   │                              │
│ ⑤ Summary               │   │ Agents (via spawn_agent):    │
│                         │   │ @cli-planning-agent           │
│ Agents (via spawn_agent)│   │ @test-fix-agent               │
│ @test-context-search    │   │                              │
│ @context-search         │   │ Strategy: conservative →      │
│ @cli-execution          │   │ aggressive → surgical          │
│ @action-planning        │   │                              │
└────────┬────────────────┘   └────────────┬──────────────────┘
         ↓                                 ↓
   IMPL-001..002.json              Pass Rate >= 95%
   TEST_ANALYSIS_RESULTS.md        Auto-complete session

Task Pipeline:
┌──────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌──────────────┐
│  IMPL-001    │───→│  IMPL-001.3     │───→│  IMPL-001.5     │───→│  IMPL-002    │
│  Test Gen    │    │  Code Validate  │    │  Quality Gate   │    │  Test & Fix  │
│  L1-L3       │    │  L0 + AI Issues │    │  Coverage 80%+  │    │  Max 10 iter │
│@code-developer│   │ @test-fix-agent │    │ @test-fix-agent │    │@test-fix-agent│
└──────────────┘    └─────────────────┘    └─────────────────┘    └──────────────┘
                                                                        │
                                                              Fix Loop: │
                                                    ┌──────────────────┘
                                                    ↓
                                              ┌──────────┐
                                              │ @cli-plan│───→ IMPL-fix-N.json
                                              │  agent   │
                                              ├──────────┤
                                              │@test-fix │───→ Apply & re-test
                                              │  agent   │
                                              └──────────┘

核心设计原则

1. 两阶段管道：生成（阶段 1）创建会话和任务，执行（阶段 2）运行迭代修复循环
2. 纯编排器：分派到各阶段文档、解析输出，并在阶段之间传递上下文
3. 阶段 1 自动继续：阶段 1 内的子阶段自动运行
4. 子 Agent 生命周期：通过 spawn_agent → wait_agent → close_agent 显式管理生命周期
5. 渐进式测试层级：L0（静态）→ L1（单元）→ L2（集成）→ L3（端到端）
6. AI 代码问题检测：针对 AI 生成代码中的常见问题进行验证
7. 智能策略引擎：根据迭代上下文，在保守 → 激进 → 精准修复之间切换
8. CLI 回退链：Gemini → Qwen → Codex，增强分析韧性
9. 渐进式测试：迭代期间运行受影响的测试，最终验证时运行完整测试套件
10. 角色路径加载：在 MANDATORY FIRST STEPS 中通过路径引用加载子 Agent 角色

自动模式

阶段 1 生成测试会话和任务。阶段 2 执行迭代修复循环，直至通过率 >= 95% 或达到最大迭代次数。**阶段 1 和阶段 2 之间，你必须停止并等待用户确认后才能继续执行。**获批后，阶段 2 将自动运行。

子 Agent API 参考

spawn_agent

创建一个新的子 Agent 并分配任务。

const agentId = spawn_agent({
  agent_type: "{agent_type}",
  message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. Run: `ccw spec load --category "planning execution"`

## TASK CONTEXT
${taskContext}

## DELIVERABLES
${deliverables}
`
})

wait_agent

获取子 Agent 的结果（这是获取结果的唯一方式）。

const result = wait_agent({
  timeout_ms: 1800000  // 30 minutes
})

if (result.timed_out) {
  followup_task({ target: agentId, message: "STATUS_CHECK: Report current progress, findings so far, and estimated remaining work." })
  const status = wait_agent({ timeout_ms: 180000 })  // 3 min
  if (status.timed_out) {
    followup_task({ target: agentId, message: "FINALIZE: Output all current findings immediately. Time limit reached.", interrupt: true })
    const forced = wait_agent({ timeout_ms: 180000 })  // 3 min
    if (forced.timed_out) {
      close_agent({ target: agentId })
    }
  }
}

followup_task

为活动中的子 Agent 分配新任务（用于澄清或后续工作）。

followup_task({
  target: agentId,
  message: `
## CLARIFICATION ANSWERS
${answers}

## NEXT STEP
Continue with plan generation.
`
})

close_agent

清理子 Agent 资源（不可逆）。

close_agent({ target: agentId })

用法

workflow-test-fix-cycle <input> [options]

# Input (Phase 1 - Test Generation)
source-session-id    WFS-* session ID (Session Mode - test validation for completed implementation)
feature description  Text description of what to test (Prompt Mode)
/path/to/file.md     Path to requirements file (Prompt Mode)

# Options (Phase 2 - Cycle Execution)
--max-iterations=N   Custom iteration limit (default: 10)

# Examples
workflow-test-fix-cycle WFS-user-auth-v2                                              # Session Mode
workflow-test-fix-cycle "Test the user authentication API endpoints in src/auth/api.ts" # Prompt Mode - text
workflow-test-fix-cycle ./docs/api-requirements.md                                     # Prompt Mode - file
workflow-test-fix-cycle "Test user registration" --max-iterations=15                    # With custom iterations

# Resume (Phase 2 only - session already created)
workflow-test-fix-cycle --resume-session="WFS-test-user-auth"                          # Resume interrupted session

质量门槛：测试通过率 >= 95%（考虑关键性）或 100% 最大迭代次数：10（默认值，可调整） CLI 工具：Gemini → Qwen → Codex（回退链）

测试策略概览

渐进式测试层级（L0-L3）：

层级	名称	重点
L0	静态分析	编译、导入、类型、AI 代码问题
L1	单元测试	函数/类行为（正常/负面/边界情况）
L2	集成测试	组件交互、API 契约、故障模式
L3	端到端测试	用户旅程、关键路径（可选）

核心特性：

• AI 代码问题检测——针对 AI 生成代码中的常见问题进行验证（幻觉导入、占位代码、模拟代码泄漏等）
• 项目类型检测——应用相应的测试模板（React、Node API、CLI、库等）
• 质量门槛——IMPL-001.3（代码验证）和 IMPL-001.5（测试质量）确保高标准

详细规范：请参阅 test-task-generate 工作流工具，了解完整的 L0-L3 要求和质量阈值。

执行流程

Input → Detect Mode (session | prompt | resume)
  │
  ├─ resume mode → Skip to Phase 2
  │
  └─ session/prompt mode → Phase 1
       │
Phase 1: Test-Fix Generation (phases/01-test-fix-gen.md)
  ├─ Sub-phase 1.1: Create Test Session → testSessionId
  ├─ Sub-phase 1.2: Gather Test Context (spawn_agent) → contextPath
  ├─ Sub-phase 1.3: Test Generation Analysis (spawn_agent → Gemini) → TEST_ANALYSIS_RESULTS.md
  ├─ Sub-phase 1.4: Generate Test Tasks (spawn_agent) → IMPL-*.json, IMPL_PLAN.md, TODO_LIST.md
  └─ Sub-phase 1.5: Phase 1 Summary
       │
  ⛔ MANDATORY CONFIRMATION GATE
  │   Present plan summary → request_user_input → User approves/cancels
  │   NEVER auto-proceed to Phase 2
       │
Phase 2: Test-Cycle Execution (phases/02-test-cycle-execute.md)
  ├─ Discovery: Load session, tasks, iteration state
  ├─ Main Loop (for each task):
  │   ├─ Execute → Test → Calculate pass_rate
  │   ├─ 100% → SUCCESS: Next task
  │   ├─ 95-99% + low criticality → PARTIAL SUCCESS: Approve
  │   └─ <95% → Fix Loop:
  │       ├─ Select strategy: conservative/aggressive/surgical
  │       ├─ spawn_agent(@cli-planning-agent) → IMPL-fix-N.json
  │       ├─ spawn_agent(@test-fix-agent) → Apply fix & re-test
  │       └─ Re-test → Back to decision
  └─ Completion: Final validation → Summary → Sync session state → Auto-complete session

核心规则

1. 立即开始：第一步是初始化 functions.update_plan
2. 不进行初步分析：第 1 阶段之前不要读取文件
3. 解析每项输出：从每个阶段／子阶段提取数据，供下一阶段使用
4. 阶段内自动继续：阶段内的子阶段自动运行；第 2 阶段开始后，各轮迭代自动运行
5. 按需加载阶段文档：按需读取阶段文档（phases/01-*.md、phases/02-*.md）
6. 任务附加模型：子任务执行附加 → 执行 → 折叠
7. 必须设置确认关卡：第 1 阶段完成后，必须停止并向用户展示生成的计划。开始第 2 阶段之前，必须通过 request_user_input 等待用户明确批准。绝不能从第 1 阶段自动进入第 2 阶段
8. 第 2 阶段持续运行：用户批准后，第 2 阶段持续运行，直至通过率达到 95% 以上或达到最大迭代次数
9. 明确生命周期：wait_agent 完成后始终调用 close_agent，以释放资源

阶段执行

第 1 阶段：测试修复生成

读取：phases/01-test-fix-gen.md

分为 5 个子阶段，用于创建测试会话并生成任务 JSON：

1. 创建测试会话 → testSessionId
2. 收集测试上下文（spawn_agent → wait_agent → close_agent）→ contextPath
3. 测试生成分析（spawn_agent → wait_agent → close_agent）→ TEST_ANALYSIS_RESULTS.md
4. 生成测试任务（spawn_agent → wait_agent → close_agent）→ IMPL-001.json、IMPL-001.3.json、IMPL-001.5.json、IMPL-002.json、IMPL_PLAN.md、TODO_LIST.md
5. 第 1 阶段总结 → ⛔ 必须：展示计划，并等待用户确认后再进入第 2 阶段

使用的 Agent（通过 spawn_agent）：

• test_context_search_agent（agent_type: test_context_search_agent）- 收集上下文（会话模式）
• context_search_agent（agent_type: context_search_agent）- 收集上下文（提示词模式）
• cli_execution_agent（agent_type: cli_execution_agent）- 使用 Gemini 进行测试分析
• action_planning_agent（agent_type: action_planning_agent）- 生成任务 JSON

第 2 阶段：测试周期执行

读取：phases/02-test-cycle-execute.md

采用自适应策略进行 3 阶段迭代执行：

1. 发现 - 加载会话、任务和迭代状态
2. 主循环 - 执行任务 → 测试 → 分析失败 → 修复 → 重新测试
3. 完成 - 最终验证 → 总结 → 自动完成会话

使用的 Agent（通过 spawn_agent）：

• cli_planning_agent（agent_type: cli_planning_agent）- 分析失败、提取根本原因、生成修复任务
• test_fix_agent（agent_type: test_fix_agent）- 执行测试、修复代码、分配关键性

策略引擎：保守（第 1–2 轮）→ 激进（通过率 >80%）→ 手术式（回归）

输出产物

目录结构

{projectRoot}/.workflow/active/WFS-test-[session]/
├── workflow-session.json              # Session metadata
├── IMPL_PLAN.md                       # Test generation and execution strategy
├── TODO_LIST.md                       # Task checklist
├── .task/
│   ├── IMPL-001.json                  # Test understanding & generation
│   ├── IMPL-001.3-validation.json     # Code validation gate
│   ├── IMPL-001.5-review.json         # Test quality gate
│   ├── IMPL-002.json                  # Test execution & fix cycle
│   └── IMPL-fix-{N}.json             # Generated fix tasks (Phase 2)
├── .process/
│   ├── [test-]context-package.json    # Context and coverage analysis
│   ├── TEST_ANALYSIS_RESULTS.md       # Test requirements and strategy (L0-L3)
│   ├── iteration-state.json           # Current iteration + strategy + stuck tests
│   ├── test-results.json              # Latest results (pass_rate, criticality)
│   ├── test-output.log                # Full test output
│   ├── fix-history.json               # All fix attempts
│   ├── iteration-{N}-analysis.md      # CLI analysis report
│   └── iteration-{N}-cli-output.txt
└── .summaries/iteration-summaries/

进度跟踪

初始化（必须）

// Initialize progress tracking after input parsing
functions.update_plan([
  { id: "phase-1", title: "Phase 1: Test-Fix Generation", status: "in_progress" },
  { id: "phase-2", title: "Phase 2: Test-Cycle Execution", status: "pending" }
])

阶段转换

// After Phase 1 completes (before mandatory confirmation gate)
functions.update_plan([
  { id: "phase-1", status: "completed" },
  { id: "phase-2", status: "in_progress" }
])

// After Phase 2 completes (pass rate >= 95% or max iterations)
functions.update_plan([{ id: "phase-2", status: "completed" }])

恢复模式

// When --resume-session skips Phase 1
functions.update_plan([
  { id: "phase-1", title: "Phase 1: Test-Fix Generation", status: "completed" },
  { id: "phase-2", title: "Phase 2: Test-Cycle Execution", status: "in_progress" }
])

错误处理

阶段	场景	操作
1.1	未找到源会话（会话模式）	返回包含会话 ID 的错误
1.1	没有已完成的 IMPL 任务（会话模式）	返回错误，源不完整
1.2	收集上下文失败	返回错误，检查源产物
1.2	Agent 超时	使用延长的超时时间重试，调用 close_agent，然后返回错误
1.3	Gemini 分析失败	返回错误，检查上下文包
1.4	任务生成失败	重试一次，然后返回错误
2	测试执行错误	记录日志，并结合错误上下文重试
2	CLI 分析失败	回退：Gemini → Qwen → Codex → 手动处理
2	Agent 执行错误	保存状态，调用 close_agent，使用简化的上下文重试
2	达到最大迭代次数	生成失败报告，标记为受阻
2	检测到回归	回滚上次修复，切换到手术式策略
2	检测到测试停滞	采用替代策略继续，并在失败报告中记录

生命周期错误处理：

try {
  const agentId = spawn_agent({ message: "..." });
  const result = wait_agent({ timeout_ms: 1800000 });  // 30 minutes
  // ... process result ...
  close_agent({ target: agentId });
} catch (error) {
  if (agentId) close_agent({ target: agentId });
  throw error;
}

协调者检查清单

阶段 1（生成）：

• 检测输入类型（会话 ID / 描述 / 文件路径 / 恢复）
• 使用 2 个顶层阶段初始化 functions.update_plan
• 阅读 phases/01-test-fix-gen.md，了解详细的子阶段执行流程
• 执行 5 个子阶段，遵循 spawn_agent → wait_agent → close_agent 生命周期
• 验证所有阶段 1 输出（4 个或更多任务 JSON、IMPL_PLAN.md、TODO_LIST.md）
• 确保每个子阶段完成后关闭所有 Agent
• ⛔ 必须：展示计划摘要并通过 request_user_input 请求确认
  • 显示：会话 ID、任务数量、测试层级、质量门槛
  • 选项："Proceed to Execution" / "Review Plan" / "Cancel"
  • 如果选择 "Cancel" → 返回，不要启动阶段 2
  • 如果选择 "Review Plan" → 显示 IMPL_PLAN.md，然后返回
  • 仅当用户选择 "Proceed to Execution" 时才继续阶段 2

阶段 2（执行）：

• 阅读 phases/02-test-cycle-execute.md，了解详细的执行逻辑
• 加载会话状态和任务队列
• 使用 spawn_agent → wait_agent → close_agent 执行迭代式测试修复循环
• 通过 functions.update_plan 跟踪迭代
• 成功时自动完成会话（通过率 >= 95%）
• 确保每次迭代后关闭所有 Agent

恢复模式：

• 如果提供了 --resume-session，则跳过阶段 1
• 将现有会话直接加载到阶段 2

相关技能

前置技能：

• workflow-plan 或 workflow-execute - 完成实现（会话模式）
• 提示词模式无需前置技能

阶段 1 Agent（阶段 1 中由 phases/01-test-fix-gen.md 通过 spawn_agent 使用）：

• test_context_search_agent（agent_type: test_context_search_agent）- 测试覆盖率分析（会话模式）
• context_search_agent（agent_type: context_search_agent）- 代码库分析（提示词模式）
• cli_execution_agent（agent_type: cli_execution_agent）- 使用 Gemini 分析测试要求
• action_planning_agent（agent_type: action_planning_agent）- 生成任务 JSON

阶段 2 Agent（阶段 2 中由 phases/02-test-cycle-execute.md 通过 spawn_agent 使用）：

• cli_planning_agent（agent_type: cli_planning_agent）- CLI 分析、根因提取、任务生成
• test_fix_agent（agent_type: test_fix_agent）- 测试执行、代码修复、重要性分配

后续操作：

• 会话同步：$session-sync -y "测试修复循环完成：{pass_rate}% 通过率"
• 成功时自动完成会话
• 为后续工作创建问题（完成后的扩展）