写代码场景下，AI 中转站的软件工程评测指南

把 AI 中转站（API Gateway / Aggregator）放在软件工程的坐标系中审视，它的本质是一个具备状态机解析与上下文调度的应用层（L7）代理网关。

从 IDE 单行补全发展到以 Claude Code CLI、OpenAI Codex CLI 为代表的终端 Agent 协同与 Specification Driven Development（规范驱动开发） 范式，代码场景对 API 代理层的要求发生了根本性变化。暂且剥离网络稳定性、高并发压测等通用网关指标，纯粹站在“代码生成与软件工程”这一业务场景下，评估 AI 中转站的核心在于：该代理层是否会破坏代码语法、中断 Agent 交互状态机、丢弃长上下文依赖，或剥离研发端的优化协议。

针对写代码与软件开发场景，AI 中转站的专业级评测应聚焦于以下四个核心工程维度：

一、代码语法与特殊字符高保真度（Syntax & Escape Integrity）

代码生成对字符和格式的精确度极度敏感。代码不仅仅是普通文本，它包含了严格的缩进、换行符、转义字符以及 JSON/XML 结构的嵌入。

1. 特殊字符与转义符零损耗（Zero-Loss Escaping）

• 底层原理：在流式传输（SSE）吐出代码 Chunk 时，代码中包含大量 \n（换行）、\t（缩进）、\"（双引号转义）、正则表达式中的 \\d 或 JSON 字符串。中转站如果在分块拼装或透传时进行了不妥当的 Unescape 或编码转换（如 UTF-8 多字节字符被截断），会导致客户端接收到的代码直接报语法错误。
• 评测方法：
• 转义符压力测试：要求模型生成包含极端转义字符的代码（如复杂正则表达式、包含嵌套 JSON 字符串的 Python 代码、包含 C++ 指针与宏定义的代码）。
• 验收标准：将中转站透传的流数据直接写入文件，使用本地 Lint 工具（如 eslint、flake8）或 AST 解析器（如 Babel / Tree-sitter）进行语法解析。AST 解析成功率必须为 100%。

2. 缩进与换行格式保持（Whitespace & Indentation Preservation）

• 底层原理：Python、YAML 等语言依赖缩进表达作用域（Scope）；不同操作系统的换行符（\n vs \r\n）也会直接影响 Git 的 Diff 比对。
• 评测方法：发送包含深度嵌套逻辑（如 8 层 loop 内的 Python 函数）的代码重构请求。
• 验收标准：比对原始输出与中转站透传输出的空格与 Tab 数量，字节级匹配度须达 100%，严禁中转站自动“美化”或“压缩”空白符。

二、Agent 工具链与结构化输出解析（Tool Call & Schema Fidelity）

现代代码 Agent 在写代码时，不再是单纯输出 Markdown，而是频繁发起 Tool Call（如 read_file、edit_file、run_terminal_command）。

1. JSON Schema 结构严格透传（Structured Output Fidelity）

• 底层原理：Agent 在修改本地代码时，会输出包含 path、old_str、new_str 等字段的结构化 JSON。如果中转站破坏了 Tool Call 的序列化格式，或者丢弃了某些嵌套字段，Agent 端就会解析失败并抛出崩溃异常。
• 评测方法：
• 多工具嵌套调用测试：构造包含多文件联动修改的 Agent 任务（如同时对 5 个 TypeScript 文件进行接口重构），抓取中转站转发的 Tool Call 报文。
• 验收标准：中转站透传的 Tool Call 结构体必须与上游官方 API 完全一致，不得出现字段缺失、数据类型变更（如 string 变 number）或 JSON 提前截断。

2. 多轮对话状态链连续性（Multi-turn State Continuity）

• 底层原理：Agent 解决一个复杂 Bug 通常需要 10~30 轮交互：读文件 -> 尝试修改 -> 跑测试 -> 报错 -> 再次修改。中转站必须完美透传 role: "assistant" 中带有 tool_use，以及 role: "user" 中带有 tool_result 的长对话链。
• 评测方法：运行一个真实的 10 轮以上 Agent 调试流程。
• 验收标准：验证在第 N 轮交互时，中转站完整保留并转发了前 N-1 轮的所有 Tool Call ID 与状态节点，不出现历史 Context 丢失或状态错乱。

三、代码长上下文与缓存协议（Context Depth & Prompt Caching）

代码工程场景的典型特征是 Context 巨大——一个中大型项目的代码库上下文（Codebase Context）动辄 100k~200k Token。

1. Prompt Caching 协议透传（Cache Control Pass-Through）

• 底层原理：在规范驱动开发（SDD）或大型项目开发中，项目的 Architecture Spec 和公共 Base 代码是固定的。Agent 会在 Request 中加上 cache_control 标记，让模型服务端复用 KV Cache。中转站如果剥离了这个 Protocol 标记，会导致每次微调一行代码都需要重新 Prefill 几十万 Token。
• 评测方法：连续推送带有 cache_control 标记的 100k Token 工程上下文。
• 验收标准：
• 请求端：抓包确认中转站发给上游的 Request 中，cache_control 字段未被剥离。
• 响应端：检查返回的 usage 结构体中是否精准回传了 cache_read_input_tokens 计数。

2. 长上下文真实性（Needle in a Codebase）

• 底层原理：验证中转站是否为了节省成本，暗中使用 RAG 裁剪代码、压缩 Prompt 或偷换小模型，导致大模型的代码全局感知能力下降。
• 评测方法：
• 跨文件依赖查找：在一个 150k Token 的代码工程中，把一个隐蔽的接口定义放在 File A（开头），把调用放在 File B（结尾），中间填充大量无关代码，提问模型如何修改该接口。
• 验收标准：比对中转站返回的代码修改结果与官方 API 直连结果。如果中转站因为裁剪了 Context 而漏掉了跨文件的变量关联或类型定义，即可判定为上下文破坏。

四、代码生成完整性与指令保护（Output Horizon & Instruction Protection）

写代码场景最忌讳代码中断，比如一个 500 行的算法模块，生成到 300 行突然无故截断。

1. Max Output Tokens 极限支撑（Max Output Horizon）

• 底层原理：单文件重构或生成完整模块时，需要模型一次性输出 4k、8k 甚至 16k Token 的纯代码。中转站的代理缓冲区（Buffer）或超时控制逻辑如果不完善，会导致长代码吐到半山腰直接中断。
• 评测方法：要求模型生成一个超长且无冗余逻辑的完整代码模块（如手写一个包含数百个枚举和转换逻辑的 Parser）。
• 验收标准：中转站透传的响应体必须能达到模型支持的最大 max_tokens 极限，且末尾的 finish_reason 必须明确为 "stop"（正常结束）或 "length"（达到长度上限），严禁无故提前 EOF。

2. System Prompt 零篡改（System Prompt Integrity）

• 底层原理：代码 Agent 会在 System Prompt 里注入极其严苛的代码规范（如“必须使用 TypeScript 严格模式”、“所有函数必须写 JSDoc”）。部分中转站会注入自己的全局 Prompt，甚至自动裁剪 System Prompt。
• 评测方法：注入包含特殊 Code Style 约束的 System Prompt，要求模型生成代码。
• 验收标准：检查生成的代码是否 100% 遵守了 System Prompt 中的约束。通过抓包对比 Raw Request，确保中转站未对 System Prompt 进行任何字节级篡改。

总结：代码场景评测 Checksheet