第二章：多智能体系统的三种基本拓扑

while iteration < MAX_QA_ITERATIONS:
    status = run_qa_reviewer()   # 审查
    if status == "approved":
        return True              # 通过，退出
    run_qa_fixer()               # 失败，修复
    iteration += 1

return False  # 达到上限，失败

# qa/loop.py - QA 审查者
client = create_client(
    project_dir, spec_dir, qa_model,
    agent_type="qa_reviewer",   # ← 角色特定的工具配置
    **qa_thinking_kwargs,
)

async with client:
    status, response, _ = await run_qa_agent_session(client, ...)

# 使用 async with 确保 Agent 进程被干净地关闭

# QA 修复者 - 与审查者完全隔离
fix_client = create_client(
    project_dir, spec_dir, qa_model,
    agent_type="qa_fixer",      # ← 不同的角色，不同的工具
    **fixer_thinking_kwargs,
)

async with fix_client:
    fix_status, fix_response, _ = await run_qa_fixer_session(fix_client, ...)

if status == "approved":
    # 通过 → 直接成功退出

elif status == "rejected":
    # 被拒绝 → 让 Fixer 修复，然后重试
    # 这是正常的失败路径

elif status == "error":
    # 意外错误 → 记录错误上下文，供下次迭代参考
    consecutive_errors += 1

    # 自我纠正：把错误信息注入下一次的 Prompt
    last_error_context = {
        "error_type": "missing_implementation_plan_update",
        "error_message": response,
        "expected_action": "You MUST update implementation_plan.json ...",
        "file_path": str(spec_dir / "implementation_plan.json"),
    }

# 在记录当前迭代之前，先检查历史中是否有相同问题
history = get_iteration_history(spec_dir)
has_recurring, recurring_issues = has_recurring_issues(
    current_issues, history
)

# 注意顺序：先检查，再记录（防止当前问题和自身匹配）
record_iteration(spec_dir, qa_iteration, "rejected", current_issues, ...)

if has_recurring:
    # 同一个问题出现 3 次以上 → 机器搞不定，升级给人类
    await escalate_to_human(spec_dir, recurring_issues, qa_iteration)
    return False

# 来自 agents/tools_pkg/models.py（简化）
AGENT_TYPES = [
    "spec_gatherer",      # Spec 创建第一步：交互式需求收集
    "spec_researcher",    # Spec 创建：研究外部集成
    "spec_writer",        # Spec 创建：编写规格文档
    "spec_critic",        # Spec 创建：批评和改进规格
    "planner",            # 规划：分解任务为子任务
    "coder",              # 实现：执行具体子任务
    "qa_reviewer",        # 质量保证：审查实现结果
    "qa_fixer",           # 质量保证：修复审查发现的问题
    "validation_fixer",   # 验证：修复规划阶段的验证错误
    "followup_planner",   # 规划：为已完成的 Spec 添加后续子任务
    "insights",           # 代码洞察：分析代码库生成见解
    "roadmap",            # 路线图：AI 辅助产品规划
]

# 每个 Agent 都是独立进程，独立上下文

# 第 1 次 Coder 运行（子任务 1）
async with create_client(..., agent_type="coder") as client:
    await run_agent_session(client, subtask_1)
    # 进程在 async with 块结束时被销毁
    # 所有上下文消失

# 第 2 次 Coder 运行（子任务 2）
async with create_client(..., agent_type="coder") as client:
    await run_agent_session(client, subtask_2)
    # 这个 Agent 对子任务 1 的细节一无所知
    # 它只能从文件系统获取信息

# prompt_generator.py 中的 generate_subtask_prompt()

def generate_subtask_prompt(subtask, spec_dir, project_dir):
    """为每个新 Agent 会话构建精准的上下文注入"""

    # 1. 当前子任务的目标
    prompt = f"## 你的任务\n{subtask['description']}\n"

    # 2. 只有相关的记忆（不是全部历史）
    memory = load_relevant_memory(spec_dir, subtask)
    if memory:
        prompt += f"## 来自之前会话的记忆\n{memory}\n"

    # 3. 要修改的文件列表（不是整个代码库）
    prompt += f"## 要修改的文件\n{subtask['files_to_modify']}\n"

    # 4. 参考模式（告诉 Agent 去哪里找例子）
    prompt += f"## 参考以下文件的代码模式\n{subtask['patterns_from']}\n"

    return prompt

# lab2_workspace/payment.py — 这是被测试的代码，故意埋了几个问题
BAD_PAYMENT_CODE = '''
import json

def process_payment(user_id, amount, card_number):
    """处理支付"""
    # 问题1: 没有金额验证（负数、零值）
    # 问题2: 信用卡号直接打印到日志（PCI 违规）
    # 问题3: 没有事务处理（部分失败无法回滚）
    print(f"Processing payment for {user_id}: ${amount}, card: {card_number}")

    result = {
        "status": "success",
        "user_id": user_id,
        "amount": amount,
    }

    # 问题4: 直接写文件没有错误处理
    with open("payments.log", "a") as f:
        f.write(json.dumps(result) + "\\n")

    return result

def refund_payment(transaction_id, amount):
    """退款"""
    # 问题5: 没有验证 transaction_id 是否存在
    # 问题6: amount 可能超过原始支付金额
    print(f"Refund: {transaction_id}, ${amount}")
    return {"status": "refunded"}
'''

"""
Lab 2.1 - 实现 QA 验证循环
目标：用迭代循环拓扑，让 AI 自动找到并修复代码质量问题
"""
import asyncio
import json
from pathlib import Path
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

# --- 配置 ---
WORK_DIR = Path("./lab2_workspace")
WORK_DIR.mkdir(exist_ok=True)
QA_REPORT_FILE = WORK_DIR / "qa_report.json"
MAX_ITERATIONS = 5

# 写入有问题的代码
(WORK_DIR / "payment.py").write_text(BAD_PAYMENT_CODE)  # 上面定义的有问题代码


# ============================================================
# TODO 1: 实现 QA 审查者 Agent
# ============================================================

async def run_qa_reviewer(iteration: int) -> tuple[str, list]:
    """
    运行 QA 审查者，返回 (status, issues)

    status: "approved" | "rejected"
    issues: 发现的问题列表，每个问题是 {"id": "...", "title": "...", "severity": "..."}

    提示：
    - 创建一个 ClaudeAgentOptions，system_prompt 告诉它是代码审查员
    - 要求它把发现的问题以 JSON 格式写入 qa_report.json
    - 格式：{"status": "approved"/"rejected", "issues": [...]}
    - allowed_tools 需要包含 Read 和 Write
    - 在 prompt 里告诉它要检查哪个文件，输出写到哪里
    """

    # TODO: 创建审查者 Agent
    reviewer_prompt = f"""
    请审查 payment.py 中的代码质量问题。

    重点检查：
    1. 输入验证（金额、参数合法性）
    2. 安全问题（敏感信息泄露、日志安全）
    3. 错误处理（文件操作、事务性）
    4. 业务逻辑正确性（退款金额验证等）

    这是第 {iteration} 次审查。

    将结果以以下 JSON 格式写入 qa_report.json：
    {{
        "status": "approved" 或 "rejected",
        "issues": [
            {{"id": "issue-1", "title": "问题标题", "severity": "critical/high/medium"}}
        ]
    }}

    如果没有发现问题，写入 {{"status": "approved", "issues": []}}
    """

    # TODO: 运行 Agent，等待完成
    # 提示：读取 qa_report.json 获取结果

    # 暂时返回 mock 数据，你需要替换为真实的 Agent 调用
    raise NotImplementedError("请实现 QA 审查者 Agent")


# ============================================================
# TODO 2: 实现 QA 修复者 Agent
# ============================================================

async def run_qa_fixer(issues: list, iteration: int) -> bool:
    """
    根据 issues 列表修复 payment.py

    返回 True 表示修复成功，False 表示失败

    提示：
    - 把 issues 格式化进 prompt
    - 告诉 Fixer 直接修改 payment.py
    - allowed_tools 需要包含 Read, Write, Edit
    """

    issues_text = "\n".join(
        f"- [{issue['severity'].upper()}] {issue['title']}"
        for issue in issues
    )

    fixer_prompt = f"""
    请修复 payment.py 中的以下问题（第 {iteration} 次修复）：

    {issues_text}

    要求：
    - 直接修改 payment.py，不要只给建议
    - 保持原有的函数签名和返回格式
    - 修复后代码应该可以正常运行
    """

    # TODO: 实现修复者 Agent
    raise NotImplementedError("请实现 QA 修复者 Agent")


# ============================================================
# TODO 3: 实现递归问题检测
# ============================================================

def detect_recurring_issues(
    current_issues: list,
    history: list[dict],
    threshold: int = 2
) -> list:
    """
    检测在多次迭代中反复出现的问题

    Args:
        current_issues: 本次发现的问题列表
        history: 历史迭代记录 [{"iteration": 1, "issues": [...]}]
        threshold: 出现多少次认为是递归问题

    Returns:
        反复出现的问题列表

    提示：
    - 按 issue["id"] 或 issue["title"] 统计出现次数
    - 出现次数 >= threshold 的就是递归问题
    """

    # TODO: 实现递归检测逻辑
    # 从 history 中提取所有历史 issue 的 title
    # 统计 current_issues 中每个 issue 的历史出现次数
    # 返回超过 threshold 的问题

    raise NotImplementedError("请实现递归问题检测")


# ============================================================
# 主循环（骨架已实现，补全 TODO 部分后即可运行）
# ============================================================

async def run_qa_loop():
    """QA 验证主循环"""
    history = []
    iteration = 0

    print("=" * 60)
    print("QA 验证循环启动")
    print("=" * 60)

    while iteration < MAX_ITERATIONS:
        iteration += 1
        print(f"\n--- 第 {iteration}/{MAX_ITERATIONS} 次迭代 ---")

        # 1. 运行审查者
        print("运行 QA 审查者...")
        status, issues = await run_qa_reviewer(iteration)

        if status == "approved":
            print(f"\n✅ QA 通过！（第 {iteration} 次迭代）")
            return True

        print(f"❌ 发现 {len(issues)} 个问题：")
        for issue in issues:
            print(f"  [{issue['severity'].upper()}] {issue['title']}")

        # 2. 检测递归问题
        recurring = detect_recurring_issues(issues, history)
        if recurring:
            print(f"\n⚠️ 检测到 {len(recurring)} 个递归问题，AI 无法自动解决：")
            for issue in recurring:
                print(f"  - {issue['title']}")
            print("需要人工介入。")
            return False

        # 3. 记录本次迭代
        history.append({"iteration": iteration, "issues": issues})

        if iteration >= MAX_ITERATIONS:
            print("\n⚠️ 达到最大迭代次数，仍有未解决的问题。")
            return False

        # 4. 运行修复者
        print("\n运行 QA 修复者...")
        success = await run_qa_fixer(issues, iteration)
        if not success:
            print("修复失败，终止循环。")
            return False

        print("✅ 修复完成，重新审查...")

    return False


if __name__ == "__main__":
    result = asyncio.run(run_qa_loop())
    print(f"\n最终结果：{'通过' if result else '失败'}")

    # 打印最终的 payment.py
    print("\n=== 最终的 payment.py ===")
    print((WORK_DIR / "payment.py").read_text())