Agent 选型矩阵：什么任务配什么工具

名称: Claude Code
定位: 高级代码生成与重构 Agent
核心优势:
  - 代码理解深度：业界领先的代码推理能力
  - 上下文窗口：200K tokens，能理解大型代码库
  - 多步推理：能处理复杂的跨文件重构
  - 安全意识：内置安全边界检查
适用场景:
  - 新功能开发（从 0 到 1）
  - 复杂重构（跨模块依赖梳理）
  - 架构设计辅助
  - 代码审查（深度理解意图）
局限性:
  - 速度较慢（推理深度换取质量）
  - 批量简单任务性价比不高
  - CLI 工具，需要终端交互

# 场景：将同步数据库操作重构为异步
$ claude "Refactor all database calls in src/services/ to use async/await.
          Update call sites accordingly. Keep tests passing."

# Claude Code 会自动：
# 1. 扫描所有相关文件
# 2. 识别同步调用点
# 3. 逐个修改并更新调用链
# 4. 运行测试验证
# 5. 输出变更摘要

# 输出示例：
# ✅ Modified 14 files across 3 directories
# ✅ All 247 tests passing
# ✅ No breaking API changes detected
#
# Changes:
# - src/services/user_service.py: Converted 8 methods to async
# - src/services/order_service.py: Converted 12 methods to async
# - src/api/handlers.py: Updated 23 call sites
# - tests/test_services.py: Updated 15 test cases

名称: Codex (OpenAI CLI / API)
定位: 快速批量代码操作 Agent
核心优势:
  - 批量处理：擅长一次性处理大量相似修改
  - 速度快：响应延迟低于 Claude Code
  - API 友好：适合自动化流水线集成
  - 成本可控：按调用计费，适合大规模任务
适用场景:
  - 批量 Bug 修复（同一类问题多个文件）
  - 代码风格统一（Lint 规则自动修复）
  - API 迁移（旧接口→新接口）
  - 测试用例批量生成
  - CI/CD 流水线中的自动化修复
局限性:
  - 复杂推理不如 Claude Code
  - 上下文理解深度有限
  - 不适合从 0 到 1 的创造性编码

from openai import OpenAI
import asyncio

class CodexBatchFixer:
    """使用 Codex 进行批量代码修复"""

    def __init__(self, api_key: str):
        self.client = OpenAI(api_key=api_key)

    async def fix_deprecated_calls(self, repo_path: str,
                                    old_api: str, new_api: str) -> list:
        """批量修复已弃用的 API 调用"""
        # 1. 找到所有使用旧 API 的文件
        affected_files = self.scan_for_pattern(repo_path, old_api)
        print(f"Found {len(affected_files)} files with deprecated calls")

        fixes = []
        for file_path in affected_files:
            code = self.read_file(file_path)

            # 2. 调用 Codex 生成修复补丁
            response = self.client.responses.create(
                model="codex",
                input=f"""Fix all usages of {old_api} to {new_api} in:
{code}

Return only the fixed code.""",
            )

            # 3. 应用修复
            fixed_code = response.output_text
            if self.validate_fix(code, fixed_code, old_api, new_api):
                self.apply_patch(file_path, code, fixed_code)
                fixes.append(file_path)

        return fixes

# 实战：修复整个项目中的 deprecated warnings
fixer = CodexBatchFixer(api_key=os.environ["OPENAI_API_KEY"])
fixed = await fixer.fix_deprecated_calls(
    repo_path="/opt/data/legacy-project",
    old_api="urllib.urlopen()",
    new_api="urllib.request.urlopen()"
)
print(f"Fixed {len(fixed)} files automatically")

名称: OpenCode
定位: 开源轻量级编码 Agent
核心优势:
  - 开源免费：无订阅费用
  - 可定制：源码级修改，适配特殊需求
  - 轻量快速：启动快，资源占用低
  - 社区生态：丰富的插件和扩展
适用场景:
  - 代码审查（快速 lint 级检查）
  - 简单代码补全
  - 文档生成（README、注释）
  - 教育/学习环境
  - 预算受限的项目
局限性:
  - 推理深度不如商业产品
  - 复杂任务需要多次交互
  - 社区版本稳定性参差不齐

拿到一个新任务
│
├─ 是批量任务（≥5个文件/实例）吗？
│  ├─ 是 → 修改模式是否简单（替换/格式）？
│  │       ├─ 是 → Codex 或 OpenCode（追求成本）
│  │       └─ 否 → Claude Code（需要理解语义）
│  │
│  └─ 否 → 需要从零创建代码吗？
│           ├─ 是 → Claude Code（最强生成能力）
│           └─ 否 → 是代码审查吗？
│                    ├─ 是 → Claude Code（深度审查）
│                    │       或 OpenCode（快速 lint）
│                    └─ 否 → 是文档/注释吗？
│                             └─ OpenCode（性价比最高）

# 需求：实现一个 OAuth2 认证模块
# 涉及：配置、路由、模型、服务层、中间件、测试

# ❌ Codex 的局限
# - 缺乏全局架构理解
# - 各组件之间的衔接需要人工协调
# - 容易遗漏边界情况

# ✅ Claude Code 的优势
# - 一次性理解整个需求
# - 自动生成配套的模型、服务、测试
# - 自动处理依赖关系
# - 生成的代码风格一致

$ claude "Implement OAuth2 authentication module with:
  - PKCE flow support
  - Token refresh mechanism
  - Integration with existing user service
  - Comprehensive test suite
  Follow the project's existing patterns in src/auth/"

# 结果：Claude Code 生成 12 个文件，247 行代码，
# 所有测试通过，风格与现有代码完全一致

# 场景：安全扫描发现 50+ 个 SQL 注入风险点
# 需要将字符串拼接改为参数化查询

# 问题特征：
# - 影响文件数：52
# - 修改模式统一：cursor.execute(f"...{var}...")
#                → cursor.execute("...%s...", (var,))
# - 每个文件修改点：1-5 处
# - 总修改量：约 120 处

# ✅ Codex 的优势
# 1. 批量扫描：一次调用处理一个文件
# 2. 速度：每个文件处理 < 3 秒
# 3. 成本：50 个文件 × 低价 API = 总成本可控
# 4. 一致性：统一的处理逻辑，风格一致

# 估算对比：
# Claude Code: 50 files × ~15s × 高单价 = ~12.5 分钟，高成本
# Codex:       50 files × ~3s  × 低单价 = ~2.5 分钟，低成本
# OpenCode:    50 files × ~5s  × 免费    = ~4 分钟，零成本
#              (但质量稳定性不如 Codex)

# Codex 批量处理脚本：
async def bulk_sql_fix(project_path):
    """使用 Codex 批量修复 SQL 注入"""
    scanner = SQLInjectionScanner(project_path)
    vulnerabilities = scanner.scan()

    fixer = CodexBatchProcessor(
        prompt_template="""Fix SQL injection in:
{code}
Change string concatenation to parameterized queries.
Return fixed code only.""",
        max_concurrency=10  # 并发处理
    )

    results = await fixer.process_batch(vulnerabilities)
    return results

# 第一层：OpenCode 快速扫描（Lint 级别）
# 秒级出结果，过滤掉明显的风格问题和基础错误
opencode_result = await opencode.review(
    pr_diff=diff,
    rules=["pep8", "security-basic", "complexity"]
)

# 第二层：Claude Code 深度审查（语义级别）
# 对第一层通过的 PR 进行深度分析
if opencode_result.passed:
    claude_result = await claude_code.review(
        pr_diff=diff,
        context={
            "business_context": "This PR modifies payment processing",
            "risk_level": "HIGH",
            "focus_areas": ["security", "edge_cases", "data_consistency"],
        }
    )

           质量
            ▲
           / \
          /   \
         /     \
   Claude Code  \
       /         \
      /           \
     /    最优区    \
    /   (混合使用)   \
   /                 \
  /    Codex          \
 /          OpenCode   \
速度 ◀────────────────▶ 成本
(快)                  (低)

class AgentRouter:
    """根据任务特征自动选择最合适的 Agent"""

    def select_agent(self, task: Task) -> str:
        """动态路由决策"""
        features = self.extract_features(task)

        # 决策规则引擎
        if features.file_count > 10 and features.pattern_complexity == "low":
            return "codex"  # 批量简单任务

        if features.requires_architectural_understanding:
            return "claude_code"  # 需要架构理解

        if features.task_type in ["lint", "format", "docs"]:
            return "opencode"  # 轻量任务

        if features.task_type == "new_feature" and features.complexity == "high":
            return "claude_code"  # 复杂新功能

        if features.is_ci_cd_task:
            return "codex"  # CI/CD 任务优先速度

        if features.budget_constrained:
            return "opencode"  # 预算优先

        # 默认
        return "claude_code"

    def extract_features(self, task: Task) -> TaskFeatures:
        """从任务描述中提取特征"""
        # 分析任务描述、涉及文件数、修改模式等
        return TaskFeatures(
            file_count=self.count_affected_files(task),
            pattern_complexity=self.assess_pattern_complexity(task),
            requires_architectural_understanding=...
        )

class AdaptiveRouter(AgentRouter):
    """带反馈学习的自适应路由器"""

    def __init__(self):
        super().__init__()
        self.performance_history = []  # 记录每次选择的结果

    def record_outcome(self, task: Task, agent: str,
                       quality: float, speed: float, cost: float):
        """记录任务执行结果"""
        self.performance_history.append({
            "task_features": self.extract_features(task),
            "agent_used": agent,
            "quality_score": quality,
            "speed_score": speed,
            "cost": cost,
        })

    def optimize_rules(self):
        """基于历史数据优化路由规则"""
        # 分析各 Agent 在不同任务特征下的表现
        # 动态调整选择阈值
        for feature_combo in self.group_by_features():
            best_agent = self.find_best_agent(feature_combo)
            self.update_routing_rule(feature_combo, best_agent)