研究方法

研究方法的核心理念

本研究采用**行为驱动开发（BDD）**启发的评估方法论。核心原则：固定功能规约，系统性变化非功能需求（结构约束）。这一实验设计将约束效应从任务的逻辑复杂性中隔离，实现跨 Agent 和模型的控制性公平比较。

传统基准测试的局限在于：任务难度同时取决于功能复杂度和约束密度。当两者纠缠时，无法判断性能下降来自”任务逻辑更复杂”还是”约束更严格”。本研究通过固定单一 API 规约，使功能复杂度恒定，约束密度成为唯一变量。

Greenfield 生成任务设计

任务定义

Greenfield 生成任务：给定目标服务的全面自然语言描述，LLM Agent 必须从空仓库合成完整的、符合规约的 REST API。

输入提示的四个组件

Agent 接收的输入提示包含：

1. API 规约：OpenAPI 3.0 格式的功能需求
2. 结构约束：待执行的非功能要求
3. 强制性文件：执行生成代码所需的文件
4. 评估管道描述：提交如何被评估的说明

API 规约的选取逻辑

研究采用 RealWorld Conduit API 作为标准规约，这一选择具有三重考量：

规约的简洁性: 19 个标准 CRUD 操作分布在 5 个资源组（articles, comments, users, profiles, tags），在 LLM 上下文窗口限制内，足够支撑多文件生成。

功能性相对简单: 规约的功能请求相对基础，配合模型可能在预训练中接触过该规约，确保了结构约束效应与基线功能复杂度的精确解耦。

内部效度最大化: 固定单一 API 规约允许隔离结构约束、框架、Agent scaffold 的效应，避免与任务语义差异混淆。

框架覆盖范围

框架作为实验因素，有 8 个离散水平，用于测试相同功能规约在相同评估条件下是否表现出框架依赖的难度差异。

flowchart TD
    subgraph Python["Python 3.12 Runtime"]
        P1["Flask: 轻量级显式"]
        P2["FastAPI: 类型提示驱动"]
        P3["Django: 约定优先"]
        P4["aiohttp: 异步原生"]
    end
    
    subgraph Node["Node.js 20 Runtime"]
        N1["Express: 极简显式"]
        N2["Fastify: 性能优先"]
        N3["Hono: 边缘运行时"]
        N4["Koa: 中间件精简"]
    end
    
    subgraph Analysis["性能分析维度"]
        A1["API 表面复杂度"]
        A2["隐式约定数量"]
        A3["训练数据覆盖度"]
    end
    
    Python --> Analysis
    Node --> Analysis
    
    style P1 fill:#9f6
    style N1 fill:#9f6
    style P3 fill:#f96
    style P2 fill:#f96

选择逻辑: 两个运行时（Python、Node）都基于动态、多范式编程语言，为代码生成提供最大自由度。框架覆盖从极简（Express、Flask）到约定密集（Django、FastAPI）的完整谱系。

约束维度的系统定义

研究定义三个正交的非功能轴线，每个可包含于或排除于代码规约。

三个约束维度

约束级别的组合设计

flowchart LR
    L0["L0: 仅框架<br/>基线"]
    L1["L1: 单约束叠加<br/>24 variants"]
    L2["L2: 双约束叠加<br/>32 variants"]
    L3["L3: 全约束叠加<br/>16 variants"]
    
    L0 --> L1
    L1 --> L2
    L2 --> L3
    
    style L0 fill:#6f9
    style L3 fill:#f96

约束级别定义:

• L0（基线）: 仅 Web 框架约束（8 variants）
• L1: 框架 + 单一约束（架构|SQLite|PG）（24 variants）
• L2: 框架 + 双约束叠加（32 variants）
• L3: 框架 + 全约束叠加（16 variants）

总计 80 个生成任务（8 框架 × 10 约束组合）。

约束的设计意图

尽管对人类开发者简单且有益，这些非功能需求将约束组合隔离为 Agent 的额外挑战：

架构约束的挑战: Agent 需将代码正确分配到四层目录，而非自发定义单体或任意结构。这测试 Agent 的组织规划和依赖管理能力。

数据库约束的挑战: Agent 需在启动时自动创建 schema，正确处理 PostgreSQL 连接池或 SQLite 文件。这测试 Agent 的基础设施配置能力。

ORM 约束的挑战: Agent 需遵循 ORM 的惯用查询逻辑，而非退化为原始 SQL。这测试 Agent 对框架特定 API 的掌握程度。

评估管道的技术架构

隔离性保证机制

为确保可复现性和避免状态污染，每个任务在隔离 Docker 环境中执行，遵循构建-评估管道。

sequenceDiagram
    participant Agent
    participant BuildContainer
    participant EvalContainer
    participant PGInstance
    
    Agent->>BuildContainer: 生成代码
    BuildContainer->>BuildContainer: 构建并启动服务器
    BuildContainer->>PGInstance: 连接数据库（如指定）
    
    BuildContainer-->>EvalContainer: 代码补丁转移
    
    EvalContainer->>EvalContainer: 应用补丁到纯净容器
    EvalContainer->>PGInstance: 新实例连接
    EvalContainer->>EvalContainer: 执行行为测试套件
    
    EvalContainer-->>Agent: 测试结果返回

构建阶段: Agent 在第一容器中操作，可编码、构建、启动服务器。容器专用 PostgreSQL 16 实例可用。

评估阶段: Agent 代码补丁应用到纯净容器，行为测试套件执行。确保评估环境无 Agent 预执行污染。

行为测试套件的设计原则

由于所有任务实例指向统一 OpenAPI 规约，所有实现使用统一 HTTP 行为测试套件评估。

套件构成: 32 个请求覆盖全部 19 个 API 端点，291 个断言验证响应结构、类型、状态码、跨有状态 CRUD 操作序列的状态转换。

设计意图: 测试 API 行为而非实现——将功能评估与内部代码结构解耦。这允许无论 Agent 如何组织解决方案，评估标准一致。

验证器函数的 Orthogonal 设计

为分离功能正确性与结构合规性，研究引入三个 orthogonal 验证器函数。

Architecture Verifier: 评估 Clean Architecture 四层合规性（routes, services, repositories, models），扫描每个导入验证依赖顺序。

Database Verifier: 扫描源代码行查找指定数据库引擎使用证据，检查未使用替代引擎；锁定文件排除。

ORM Verifier: 检测指定 ORM 是否被使用，而非原始 SQL 或框架原生数据层。

任务成功定义: 行为有效性 ∩ 约束合规性。完成任务需通过整个行为测试套件且满足每个适用验证器。

Agent 与模型配置

Agent Scaffold 的选择

研究评估两种不同工具复杂度的开源 Agent 架构。

配置调整: 向 Mini-SWE-Agent 注入重对齐系统提示引导生成式管道；向 OpenHands 引入终止准则缓解过早停止；两者均设置极宽松迭代上限（Mini-SWE 300，OpenHands 200），成本限制无界。

模型分层设计

研究配对每个 scaffold 跨广能力范围的模型，分为四层：

成本驱动的评估范围

由于 OpenHands 更丰富的工具集导致更大上下文窗口，研究限制 Kimi-K2.5 和 GPT-5.2 仅使用 Mini-SWE-Agent。

对于高成本模型（MiniMax-M2.5, Kimi-K2.5, GPT-5.2），使用代表性任务子集：覆盖 2 框架/运行时（aiohttp + FastAPI, Express + Fastify），每约束级别 1 variant（L0, L1-Arch, L2-Arch+PG, L3-Arch+PG+ORM），共 16 任务，48 运行/模型-Agent 对。

子集代表性验证: 在 6 个全集配置上重新评估子集任务，A% 分数 Pearson r=0.98，Spearman ρ=0.95（p<10^-12, N=24）——子集与全集在绝对分数和排名顺序上近乎完美一致。

评估指标的定义

Assert% (A%) 作为主指标

定义: 给定配置跨所有运行的行为测试断言通过的平均分数。

优势: 捕获部分进展，区分”轻微偏离合规”与”大部分非功能性实现”。pass@1 的全或无性质放大噪声，A% 更稳定地反映真实能力。

Pass@k 的补充意义

使用 Chen et al. (2021) 的无偏估计器，k 个独立样本中至少一个满足全部行为和结构约束的概率。

局限性: 由于单一断言失败使整个运行归零，pass@1 在生成任务评估中噪声较大。研究仍报告 pass@k 作为参考，但 A% 为主要指标。

验证器影响量化

所有 A% 分数整合结构合规性：当运行违反任何适用验证器时，其断言分数归零后平均。

验证影响评估: 也计算无验证器强制的 A%。两版本在单配置上最多差 2.7pp，平均 L0→L3 下降从 28pp 变为 30pp。这确认约束衰减信号来自真实功能失败而非验证器伪影。

Feature Implementation 任务设计

自然性验证需求

一个自然担忧：约束衰减是否是合成 greenfield 设置的伪影？

为测试此担忧，研究构建 20 个 feature implementation 任务：从社区维护的 RealWorld 仓库（已嵌入分层架构、PostgreSQL、ORM）中剥离功能组（164–2604 行，2–46 文件），模拟 L3 条件下的隐性约束环境。

任务要求: Agent 需阅读现有代码库、推断其约定、重新实现缺失功能。

结果启示

性能仍然低：仅 GPT-5.2 超过 50% pass@1。虽然无法隔离结构约束为唯一难度原因，但结果确认 greenfield 生成中观察的挑战不是”从零构建仓库”的伪影——当 Agent 需推断并尊重现有约束时，挑战持续存在。

实验执行的统计设计

每个任务执行 n=3 独立试验/Agent-模型配置。研究使用约 5 billion tokens（详见 Appendix H）。

统计显著性: 约束级别间差异通过配对差分设计量化——对每个约束 c，识别仅差 c 的任务配对（保持框架和其他约束相同），计算 Δ(A%) 并跨所有配对和配置平均。这提供了边际效应的无偏估计。