fischer-agentkit/docs/plans/2026-06-12-020-feat-pipeline-adversarial-loop-plan.md

title	status	created	origin	type
feat: Pipeline 级别对抗闭环（Coding Harness）	active	2026-06-12	头脑风暴对话 - Worker ↔ Verifier 对抗闭环改进方案	feat

feat: Pipeline 级别对抗闭环（Coding Harness）

问题框架

当前 Pipeline Engine 的 retry_count 和 retry_policy 实现的是盲目重试（指数退避重跑相同逻辑），QualityGate 是单向验证（validate → pass/fail）。Worker 产出失败后不知道具体哪里有问题，重试时无法定向修复。

目标： 实现 Worker → Verifier → 带反馈打回 Worker → 定向修复 → 再次审查的对抗闭环，通过 Pipeline YAML 配置即可启用。

---

高层技术设计

对抗流转状态机

stateDiagram-v2
    [*] --> Worker: 执行 Stage
    Worker --> Verifier: 产出完成
    Verifier --> [*]: 审查通过 (passed=true)
    Verifier --> Worker: 审查不通过 (round < max)
    Worker --> Verifier: 根据反馈修复
    Verifier --> Escalate: 轮次耗尽 (round >= max)
    Escalate --> [*]: 转人工或标记失败

反馈数据结构

ReviewFeedback
├── passed: bool
├── score: float (0-1)
├── summary: str (自然语言审查报告)
└── issues: list[ReviewIssue]
    ├── severity: critical/major/minor
    ├── category: logic_error/security/style/test_failure/architecture
    ├── description: str
    ├── location: str? (文件路径/行号)
    └── suggestion: str?

配置扩展

在 PipelineStage 新增 4 个字段：

• verifier: str | None — Verifier Agent 名称
• max_adversarial_rounds: int — 最大对抗轮次（默认 3）
• feedback_mode: str — 反馈模式（structured+natural / structured / natural）
• escalate_on_exhaust: str | None — 轮次耗尽后的升级目标

---

实施单元

U1. 扩展 Pipeline Schema — 对抗字段和反馈数据模型

Goal: 在 pipeline_schema.py 中新增对抗闭环所需的数据模型和字段

Requirements:

• PipelineStage 支持配置 Verifier 和对抗参数
• 提供结构化的 ReviewFeedback 和 ReviewIssue 数据模型
• 提供 AdversarialState 用于追踪对抗轮次

Dependencies: 无

Files:

• src/agentkit/orchestrator/pipeline_schema.py (修改)
• tests/unit/test_pipeline_schema.py (修改)

Approach:

1. 新增 ReviewIssue Pydantic 模型（severity, category, description, location, suggestion）
2. 新增 ReviewFeedback Pydantic 模型（passed, issues, summary, score）
3. 新增 AdversarialState Pydantic 模型（current_round, max_rounds, feedback_history, last_feedback）
4. 在 PipelineStage 新增 4 个字段：
   • verifier: str | None = None
   • max_adversarial_rounds: int = 3
   • feedback_mode: str = "structured+natural"
   • escalate_on_exhaust: str | None = None

Test scenarios:

1. Happy path: 创建带 verifier 字段的 PipelineStage，验证字段默认值正确
2. Happy path: 创建 ReviewFeedback 对象，验证序列化和反序列化正常
3. Edge case: verifier=None 时，PipelineStage 正常创建（向后兼容）
4. Edge case: max_adversarial_rounds=0 时正常创建

---

U2. Pipeline Engine 增强 — 对抗流转执行逻辑

Goal: 在 PipelineEngine 中实现 _execute_stage_with_adversarial 方法，处理 Worker ↔ Verifier 对抗循环

Requirements:

• 当 Stage 配置了 verifier 时自动进入对抗模式
• Verifier 审查不通过时，带反馈打回 Worker 重做
• 超过最大轮次后执行升级处理
• 保持与现有 _execute_stage 的向后兼容

Dependencies: U1

Files:

• src/agentkit/orchestrator/pipeline_engine.py (修改)
• tests/unit/test_pipeline_adversarial.py (新增)

Approach:

1. 新增 _execute_stage_with_adversarial 方法：

   • 检查 stage.verifier 是否存在，不存在则走原有逻辑
   • 初始化 AdversarialState
   • 进入对抗循环（1 到 max_adversarial_rounds）：
     • 执行 Worker Agent
     • 执行 Verifier 审查 Worker 产出
     • 如果通过：返回成功结果
     • 如果不通过：
       • 记录反馈到 feedback_history
       • 如果轮次耗尽：调用 _escalate 处理
       • 否则：调用 _execute_agent_with_feedback 打回 Worker

2. 新增 _execute_agent_with_feedback 方法：

   • 构建反馈上下文（previous_attempt_failed, review_feedback, instruction）
   • 合并到原有上下文
   • 调用 Dispatcher 执行 Agent

3. 新增 _execute_verifier 方法：

   • 调用 Verifier Agent 执行审查
   • 解析返回结果为 ReviewFeedback 对象
   • 记录审查日志

4. 新增 _escalate 方法：

   • 如果配置了 escalate_on_exhaust：转发到升级目标（如 human_approval）
   • 否则：返回失败结果，附带审查历史

5. 修改 _execute_stage 方法：

   • 检查是否配置了 verifier
   • 如果配置了，路由到 _execute_stage_with_adversarial
   • 否则保持原有逻辑

Test scenarios:

1. Happy path: Stage 无 verifier → 走原有逻辑，正常完成
2. Happy path: Stage 有 verifier，审查通过 → 一次完成
3. Happy path: Stage 有 verifier，审查不通过 → 打回 Worker → 修复后通过
4. Edge case: 超过 max_adversarial_rounds → 触发 escalate_on_exhaust
5. Edge case: escalate_on_exhaust=None → 返回失败，附带审查历史
6. Error path: Verifier 执行异常 → 记录错误，返回失败
7. Error path: Worker 重试时再次异常 → 继续下一轮或轮次耗尽
8. Integration: 完整对抗流程的状态追踪正确（feedback_history 长度=实际轮次）

---

U3. 反馈上下文构建和注入机制

Goal: 实现结构化的反馈上下文构建，让 Worker Agent 能理解审查反馈并定向修复

Requirements:

• 反馈上下文包含结构化问题列表和自然语言审查报告
• Worker 能根据反馈上下文调整生成策略
• 支持 feedback_mode 配置（structured+natural / structured / natural）

Dependencies: U2

Files:

• src/agentkit/orchestrator/pipeline_engine.py (修改，续 U2)
• tests/unit/test_pipeline_adversarial.py (修改，续 U2)

Approach:

1. 构建反馈上下文字典：

feedback_context = {
    "previous_attempt_failed": True,
    "review_feedback": {
        "summary": feedback.summary,
        "issues": [
            {
                "severity": issue.severity,
                "category": issue.category,
                "description": issue.description,
                "suggestion": issue.suggestion,
            }
            for issue in feedback.issues
        ],
        "previous_score": feedback.score,
    },
    "instruction": (
        "Your previous output did not pass review. "
        "Please fix the issues listed above and regenerate."
    ),
}

2. 根据 feedback_mode 调整上下文：

   • structured+natural: 包含完整 issues 列表和 summary
   • structured: 只包含 issues 列表
   • natural: 只包含 summary 和 instruction

3. 合并到原有上下文：

   • merged_context = {**context, **feedback_context}
   • 传递给 Agent 执行

Test scenarios:

1. Happy path: feedback_mode="structured+natural" → 上下文包含 issues 和 summary
2. Happy path: feedback_mode="structured" → 上下文只包含 issues
3. Happy path: feedback_mode="natural" → 上下文只包含 summary
4. Edge case: feedback.feedback_history 有多轮记录 → 合并所有历史反馈

---

U4. 创建 code_reviewer Skill 配置示例

Goal: 创建代码审查 Verifier Agent 的 Skill 配置，作为对抗模式的的标准 Verifier 模板

Requirements:

• 配置为 direct 执行模式
• system_prompt 定义严格的代码审查角色和检查维度
• 配置 output_schema 确保返回结构化的 ReviewFeedback 格式

Dependencies: U1（需要 ReviewFeedback schema 存在）

Files:

• configs/skills/code_reviewer.yaml (新增)

Approach:

1. 创建 code_reviewer.yaml：

   • name: code_reviewer
   • execution_mode: direct
   • intent_match: "code.*review|review.*code"
   • system_prompt: 定义代码审查角色、检查维度（逻辑正确性、安全漏洞、架构设计、测试覆盖、代码风格）
   • tools: [shell_tool]（用于运行测试用例）
   • quality_gate: 配置 required_fields 和 output_schema

2. output_schema 定义：

   • passed: boolean
   • issues: array of {severity, category, description, location?, suggestion?}
   • summary: string
   • score: number (0-1)

Test expectation: none — 这是配置文件，通过 YAML 加载测试验证格式正确性

---

U5. 创建 coding_harness Pipeline 配置示例

Goal: 创建完整的编码对抗 Pipeline 配置示例，展示如何使用对抗闭环功能

Requirements:

• 包含 develop → test → review（对抗模式） → archive 四个阶段
• review 阶段配置 verifier、max_adversarial_rounds、escalate_on_exhaust
• 使用变量引用传递阶段间产出

Dependencies: U4

Files:

• configs/pipelines/coding_harness.yaml (新增)

Approach:

1. 创建 coding_harness.yaml：

   • name: coding_harness, version: "1.0"
   • 阶段 1 (develop): developer_agent 实现功能
   • 阶段 2 (test): tester_agent 运行测试，依赖 develop
   • 阶段 3 (review): developer_agent 修复问题，verifier=code_reviewer, max_adversarial_rounds=3, escalate_on_exhaust=human_approval
   • 阶段 4 (archive): archiver_agent 提交代码，依赖 review

2. 配置变量引用：

   • test 阶段输入: code="{{develop.code}}", test_files="{{develop.test_files}}"
   • review 阶段输入: code="{{develop.code}}", test_results="{{test.test_results}}"
   • archive 阶段输入: code="{{review.final_code}}"

Test expectation: none — 这是配置文件，通过 YAML 加载测试验证格式和引用正确性

---

U6. 编写单元测试 — 对抗流转和反馈注入

Goal: 为对抗闭环功能编写完整的单元测试覆盖

Requirements:

• 覆盖 U1-U3 定义的所有测试场景
• 使用 mock 模拟 Dispatcher 和 Agent 执行
• 验证对抗流转逻辑正确性

Dependencies: U1, U2, U3

Files:

• tests/unit/test_pipeline_adversarial.py (新增)

Approach:

创建以下测试类：

1. TestPipelineSchemaAdversarial:

   • test_stage_with_verifier
   • test_stage_without_verifier_backward_compat
   • test_review_feedback_serialization
   • test_adversarial_state_tracking

2. TestAdversarialExecution:

   • test_no_verifier_passthrough
   • test_verifier_passes_first_round
   • test_verifier_fails_then_worker_fixes
   • test_max_rounds_exhausted_escalate
   • test_max_rounds_exhausted_no_escalate
   • test_verifier_execution_error
   • test_worker_retry_error

3. TestFeedbackContext:

   • test_structured_and_natural_mode
   • test_structured_only_mode
   • test_natural_only_mode
   • test_multiple_rounds_feedback_merge

4. TestEscalation:

   • test_escalate_to_human_approval
   • test_escalate_to_fallback_agent
   • test_no_escalation_configured

Test scenarios: 见各测试类定义

---

U7. 编写集成测试 — 完整 Coding Harness Pipeline

Goal: 编写集成测试验证完整的 Coding Harness Pipeline 端到端流程

Requirements:

• 加载 coding_harness.yaml 配置
• 模拟完整的 develop → test → review → archive 流程
• 验证对抗闭环在 review 阶段正常工作

Dependencies: U4, U5, U6

Files:

• tests/integration/test_coding_harness_pipeline.py (新增)

Approach:

1. 创建集成测试：

   • 使用 MockDispatcher 模拟 Agent 执行
   • 模拟 develop 阶段产出代码
   • 模拟 test 阶段运行测试
   • 模拟 review 阶段：第一次审查不通过 → 打回修复 → 第二次审查通过
   • 模拟 archive 阶段提交代码

2. 验证点：

   • Pipeline 最终状态为 COMPLETED
   • review 阶段经历了 2 轮对抗
   • feedback_history 记录了审查反馈
   • 各阶段输出变量正确传递

Test scenarios:

1. Happy path: 完整 Pipeline 执行，review 阶段 2 轮对抗后通过
2. Edge case: review 阶段 3 轮对抗后仍不通过 → escalate 到 human_approval
3. Error path: test 阶段失败 → Pipeline 中止，不进入 review

---

范围边界

包含：

• Pipeline Schema 扩展（对抗字段和反馈数据模型）
• Pipeline Engine 对抗流转执行逻辑
• 反馈上下文构建和注入
• code_reviewer Skill 配置示例
• coding_harness Pipeline 配置示例
• 单元测试和集成测试

不包含（延期到后续工作）：

• 任务复杂度评估器（自动判断是否启用对抗团队）
• IM 异步秒级响应（Leader 立即回执 + 后台异步调度）
• 多路并行调研对抗（多路 Researcher + 独立 Verifier）
• 对抗成本监控（Token 消耗、时间、修复成功率记录）
• Verifier 多角色拆分（LogicReviewer / SecurityReviewer / StyleReviewer 并行审查）

---

风险和依赖

风险

1. Agent 反馈理解能力： Worker Agent 可能无法完全理解结构化反馈并定向修复。缓解措施：使用 feedback_mode="structured+natural" 提供自然语言说明。

2. Verifier 审查质量： code_reviewer 的审查质量取决于 system_prompt 和 LLM 能力。缓解措施：提供高质量的 system_prompt 模板，支持后续优化。

3. Token 消耗： 多轮对抗可能消耗大量 Token。缓解措施：max_adversarial_rounds 默认 3，可配置。

依赖

• 现有 Pipeline Engine 基础设施（DAG 拓扑排序、并行执行、变量解析）
• 现有 Dispatcher 接口（dispatch、get_task_status）
• 现有 Agent 配置系统（ConfigDrivenAgent、SkillConfig）

---

系统级影响

• 向后兼容： PipelineStage 新增字段都有默认值，现有 Pipeline 配置无需修改
• 性能影响： 无 verifier 配置的 Stage 走原有逻辑，无性能影响；有 verifier 的 Stage 可能增加执行时间（多轮对抗）
• 可观测性： 对抗轮次和审查结果记录在 StageResult 的 output_data 中，可通过日志和状态管理查询