Lab 006：同一需求从 PRD 到代码，哪个 Agent 最会问问题？

实验假设：
  H1：提问越多的 Agent 最终实现质量越高（待验证）
  H2：不同 Agent 的提问类型有偏好差异（技术型 vs 业务型）（待验证）
  H3：不提问直接编码的 Agent 返工率更高（待验证）

# agent_clarity_experiment.py
"""
Agent 澄清能力评测 Runner。
每个 Agent 独立处理同一份模糊 PRD，记录提问、计划和实现。
"""
import json
import time
from dataclasses import dataclass, asdict, field

@dataclass
class AgentResponse:
    agent_name: str
    prd_id: str
    # 澄清阶段
    questions_asked: list[str] = field(default_factory=list)
    questions_categories: list[str] = field(default_factory=list)  # "business" | "technical" | "edge_case"
    clarification_score: float = 0.0  # 覆盖率
    # 计划阶段
    plan: str = ""
    plan_score: float = 0.0
    # 实现阶段
    code_files: list[str] = field(default_factory=list)
    implementation_score: float = 0.0
    # 汇总
    composite_score: float = 0.0
    time_seconds: float = 0.0

# 标准答案：每份 PRD 应该被澄清的关键点
GOLDEN_CLARIFICATIONS = {
    "PRD-01": [
        {"point": "密码规则", "category": "business", "importance": "HIGH"},
        {"point": "邮箱验证", "category": "business", "importance": "HIGH"},
        {"point": "第三方登录", "category": "business", "importance": "MEDIUM"},
        {"point": "手机号注册", "category": "business", "importance": "MEDIUM"},
        {"point": "验证码防刷", "category": "technical", "importance": "HIGH"},
        {"point": "密码加密方式", "category": "technical", "importance": "HIGH"},
        {"point": "用户名规则", "category": "business", "importance": "MEDIUM"},
        {"point": "注册后自动登录", "category": "business", "importance": "LOW"},
        {"point": "国际化", "category": "technical", "importance": "LOW"},
        {"point": "法律合规（隐私政策）", "category": "edge_case", "importance": "HIGH"},
    ],
    # ... PRD-02 到 PRD-05 类似
}

def run_single(agent_name: str, prd_id: str, prd_content: str, runner) -> AgentResponse:
    """让一个 Agent 处理一份 PRD"""
    response = AgentResponse(agent_name=agent_name, prd_id=prd_id)
    start = time.time()
    
    # 阶段 1：澄清（Agent 读 PRD 后提出问题）
    print(f"  [{agent_name}] 阶段 1: 澄清 {prd_id}")
    questions = runner.ask_clarification(agent_name, prd_content)
    response.questions_asked = questions
    
    # 计算覆盖率：Agent 的问题命中了几个标准澄清点
    golden = GOLDEN_CLARIFICATIONS.get(prd_id, [])
    hits = sum(1 for g in golden if any(
        keyword_match(g["point"], q) for q in questions
    ))
    response.clarification_score = hits / len(golden) if golden else 0
    
    # 分类问题
    response.questions_categories = [
        classify_question(q) for q in questions
    ]
    
    # 阶段 2：计划（Agent 基于 PRD + 澄清回答生成计划）
    print(f"  [{agent_name}] 阶段 2: 计划 {prd_id}")
    # 提供人工准备好的标准答案
    answers = prepare_standard_answers(golden)
    plan = runner.generate_plan(agent_name, prd_content, questions, answers)
    response.plan = plan
    
    # 阶段 3：实现（Agent 按计划编码）
    print(f"  [{agent_name}] 阶段 3: 实现 {prd_id}")
    code = runner.implement(agent_name, plan)
    response.code_files = [f["path"] for f in code]
    
    response.time_seconds = time.time() - start
    return response

def keyword_match(clarification_point: str, question: str) -> bool:
    """检查问题是否命中了澄清点（关键词匹配）"""
    # 简单的关键词匹配，实际可以用 LLM 做语义匹配
    keywords = clarification_point.split("，")
    return any(kw in question for kw in keywords)

def classify_question(question: str) -> str:
    """分类问题类型"""
    business_keywords = ["用户", "业务", "流程", "规则", "场景"]
    technical_keywords = ["数据库", "API", "缓存", "性能", "框架"]
    edge_keywords = ["边界", "异常", "并发", "安全", "兼容"]
    
    if any(kw in question for kw in edge_keywords):
        return "edge_case"
    if any(kw in question for kw in business_keywords):
        return "business"
    if any(kw in question for kw in technical_keywords):
        return "technical"
    return "other"

Claude Code 的典型提问：
  1. "密码需要满足什么复杂度要求？（长度、大小写、特殊字符）"  → 4.5 分
  2. "注册后需要邮箱验证吗？验证链接有效期多长？"  → 4.8 分
  3. "是否需要考虑 GDPR / 个人信息保护法的合规要求？"  → 5.0 分
  4. "是否需要手机号注册？如果需要，短信验证码防刷策略是什么？"  → 4.5 分

Codex CLI 的典型提问：
  1. "数据库用什么？MySQL 还是 PostgreSQL？"  → 2.5 分
  2. "前端框架用 React 还是 Vue？"  → 2.0 分
  3. "密码加密用 bcrypt 还是 argon2？"  → 3.0 分
  4. "需要 Redis 做 session 存储吗？"  → 2.0 分

综合得分
  0.8 ┤  ● Claude Code
      │
  0.6 ┤      ● Cursor Agent
      │
  0.4 ┤            ● Codex CLI
      │
  0.2 ┤                  ● Copilot Workspace
      │
  0.0 ┼──────┬──────┬──────┬──────┬──
      0.2    0.4    0.6    0.8    1.0
              提问覆盖率