长时运行的编码 Agent 需要 Harness，而不只是更大的模型

长时运行的编码 Agent 最令人头疼的失败模式，并不总是一个糟糕的补丁，而是这样一个时刻：任务已被压缩过两次，好几个工具已经运行过，一个子 Agent 也交回了摘要，却没有人能回答一个简单的问题——哪些已经得到证实，哪些仍只是假设，下一步该做什么？

买更大的上下文窗口回答不了这个问题。在每个会话开头放一段更长的策略提示词，同样回答不了。

实用的默认做法，是做出两个相互独立的决定：

1. 根据可能让任务失败的输入与执行约束来选择模型路由。
2. 通过一个运行框架（harness）来执行工作：由它记录状态、为动作设上限、核查证据，并产出可用于重新启动的交接记录。

本指南刻意不做通用的编码模型排行榜。它给出一种实用方法，帮你为长时运行的编码任务选定首个 ChinaAPI 路由，然后阐明更重要的一点： 模型只是一个推理组件；能长期可靠运行的 Agent，是围绕模型构建的一整套操作系统。

当前的路由清单

我们于 2026-07-24 采集、经网关对账的目录快照包含 25 个按 token 计费的在线 model IDs。每一个都带有 Reasoning 和 Tools 这两个目录元数据标签； 11 个标称 1M token 上下文窗口，其中 六个 同时具备 1M 上下文、工具支持和视觉输入。

这是一张可用情况与公开能力的地图，而不是基准测试。它不能证明某个模型会正确使用工具、能修复更多 bug，或在你的流量下保持可靠；但它确实说明，Agent 构建者已经有足够多不同的路由可选，不必再把每个任务都当作一次纯文本的旗舰模型提示。

我们的立场很明确： 按任务需要的证据和你能强制执行的预算来选择路由，而不是看“旗舰”这个词。 如果验收检查需要截图，选用 1M 纯文本模型只是表面上的节省。如果有边界的抽取或编写测试任务用低成本路由就能通过验收，把高价编码路由设为默认就是错误的默认。

准确的 ID、当前展示价格和目录变动，请先查看 实时价格 再投入生产使用。 Cursor、 Cline和 LiteLLM 指南展示了同一个 OpenAI-compatible 端点在各工具设置中的填写方式。

模型路由不等于任务契约

一个 Agent 即便用上了出色的模型，仍可能以再普通不过的方式把一项长任务搞砸：

• 一次代码仓库扫描悄无声息地耗尽了全部上下文预算。
• 工具循环不断重试，直到成本高得出人意料。
• 分支已经变了，上一个会话留下的 TODO 却仍被当作当前事实。
• 几个子 Agent 都交回了看似合理的摘要，却没有父 Agent 核对它们与当前的 diff 和 CI 是否一致。
• 验收测试从未运行过，最终回答却说“已完成”。

这些主要不是语言模型的问题，而是任务状态、权限和验证的问题。

OpenAI 将其 Codex 运行框架（harness）描述为 Agent 循环中负责编排用户、模型与工具的那一层。其工程团队也把围绕 Agent 开展的工作描述为定义环境与反馈回路，而不只是给出更好的提示词。 阅读 Agent 循环的讲解 和 Harness Engineering 报告。

实际的结论很简单：把模型选择当作任务卡片中的一个字段，而不是任务计划本身。

每个长任务都从一张有边界的任务卡片开始

这张任务卡片足够小，可以和执行轨迹一起保存；又足够具体，能防止一个开放式的编码请求变成一个没有边界的 Agent 循环。其中的具体模型只是候选，并不代表经过实测更优。

{
  "task_id": "repo-bugfix-01",
  "task_type": "repository_bugfix",
  "candidate_model": "LongCat-2.0",
  "escalation_model": "glm-5.2",
  "source_modalities": ["repository_text", "issue", "test_log"],
  "context_requirement": "1m",
  "needs_tools": true,
  "max_tool_rounds": 8,
  "max_attempts": 2,
  "max_cost_usd": "set per task",
  "acceptance_checks": [
    "targeted test passes",
    "diff stays inside the named module",
    "no unsupported claim in the handoff"
  ],
  "human_approval_required_for": ["production deploy", "data deletion", "credential change"]
}

最值得先关注的两个字段并不是模型名称，而是 source_modalities 和 acceptance_checks。

如果 Agent 需要把浏览器截图与某次 CSS 改动对照核实，先选一个具备相应输入能力的模型，再比较 token 价格。如果没有任何测试能确认任务结果，就在 Agent 开始改代码之前写好评审或审批步骤。如果任务承受不起破坏性命令，就把权限边界做成可执行的机制，而不是指望模型会重读一条警告。

下面是上述候选模型最精简的 OpenAI-compatible 起步示例：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CHINAAPI_API_KEY"],
    base_url="https://api.chinaapi.ai/v1",
)

response = client.chat.completions.create(
    model="LongCat-2.0",
    messages=[
        {"role": "system", "content": "Work only within the stated task card."},
        {"role": "user", "content": "Inspect the failing test before proposing a patch."},
    ],
)
print(response.choices[0].message.content)

请使用当前准确的 model ID，具体见 实时价格。这段代码只是打通了一条请求路径，并不是一个完整的自主编码 Agent。生产环境中的循环仍需要自己的工具 schema、沙箱、授权策略、遥测和验收执行器。

把聊天循环变成可恢复系统的五项控制

1. 任务图，而不是不断滚动的对话

每个节点都应有输入、输出、状态、依赖、负责人和验收检查。代码仓库扫描可以在实现之前运行；测试不能在相关代码存在之前运行；生产操作可以等待人工审批。把这些关系显式化，就能防止 Agent 把每个可用的工具都当成合理的下一步。

2. 带来源与有效期的记忆

PLAN.md、 STATE.md和 HANDOFF.md 只有能回溯到事实时才有用。要记录每条陈述的来源、写入时间、适用的分支，以及下次应在何时复核。当前的代码、提交、pull request、CI 和测试，都比旧摘要更有权威。

这就是实践中的记忆垃圾回收。记忆不是应当无限增长的档案库，而是一份工作索引，底层事实一旦变化就应当修剪。

3. 能解释失败原因的执行轨迹

保存工具调用、输入引用、结果、测试输出、重试次数和状态转换。目的不是监控，也不是尽可能多地记日志，而是让日后的问题有据可答：任务失败，是因为模型选了一个糟糕的修改，是因为先前的假设已经过时，是因为某个工具不可用，还是因为根本没有验收规则？

4. 可强制执行的边界

提示词是有用的软约束；权限、沙箱、hook、linter、测试、审批和回滚路径则是更硬的约束。把不可逆或后果重大的操作放在后者的把关之下。

Claude Code 的子 Agent 文档从另一个角度呈现了同样的区分：隔离的工作单元可以让主上下文免受冗长探索的干扰，但它们的产出仍需要由上层工作流来评估。 它的子 Agent 指南 可以作为设计这道边界时的背景参考。

5. 新会话真正用得上的检查点

交接记录不应是一本按时间顺序记下的日记。它应保留最初的目标、已验证的事实、所做的决定与取舍、尚未解决的风险、确切的下一步动作，以及需要先读的事实来源。这样，新会话就能从被压缩过的对话中恢复，而不必把所有旧猜测一并带进来。

有了这些控制之后，人的角色也更清晰了：设定目标和边界，审批后果重大的决策，审视风险，验收结果。操作细节由系统来承载，而不是靠某个人的短期记忆。

长上下文有帮助，但它不负责治理

人们很容易把模型架构和 Agent 治理混为一谈。两者在长会话中交汇，但解决的是不同的问题。

MoE 在扩大参数容量的同时，对每个 token 只激活模型的一部分。MLA 降低了长上下文推理中注意力计算与 KV 缓存处理的成本。DeepSeek 的 V3 报告在其效率设计中介绍了这两项技术。 阅读技术报告。

这些进步能让更长的上下文变得用得起，却无法判断一份旧的交接记录是否已经过时、某个子 Agent 的结论是否经过评审，或某次部署是否需要审批。

长上下文回答的是“模型能否容纳更多材料？”

治理回答的是“哪些材料仍然成立，谁可以据此行动，任务出错时我们又该如何恢复？”

不要用其中一个去替代另一个。

把失败转化为评测输入，而不是玄学

Agent 失败的执行轨迹是原材料，而不是现成的训练样本。

先对它分类。是记忆文件误导了 Agent？是交接记录漏掉了某个风险？是调度器把不该并行的任务并行了？是 Agent 跳过了 CI 证据？还是模型在一份合理的任务契约下依然失败了？每一类都指向不同的修复方式：新鲜度检查、检查点字段、hook、评测用例、更好的工具接口，或调整后的路由规则。

只有这样，反复出现的失败才能用作监督样本、偏好数据、强化学习或回归测试的素材。一个分不清“糟糕的执行轨迹”与“定义不充分的任务”的系统，只会更高效地训练噪声。

本指南不做哪些声明

对于表中各模型在代码仓库级 bug 修复完成度、工具调用成功率、Agent 循环延迟、被采纳补丁的成本或恢复质量方面的表现，我们尚未发布经过重复测试的 ChinaAPI 结果。因此，我们不会把任何候选称为通用的最佳编码模型，不会承诺任何模型的可用性，也不会把目录元数据变成性能排名。

目录可能会变，而 1M 上下文窗口代表的是容量，不是证据质量。部署前请核对准确的 model ID 和展示价格。在你自己的代码仓库上跑一组固定任务，保存验收结果和总修复时间，只有当某条路由在可用结果上胜出之后，才将其升级为正式路由。

务实的工作顺序并不光鲜，但很可靠：

route by required inputs and constraints
→ bound the task with a card and acceptance checks
→ execute under permissions, trace, and budgets
→ checkpoint verified facts for recovery
→ convert recurring failures into evals and guardrails

这样，编码 Agent 就不只是一个接上终端的模型，而会成为一个能解释自身工作、能跨越会话边界延续的系统，并把唯一能随规模扩展的控制面交给人：目标、边界、判断与验收。

来源与方法

• 本文中的 ChinaAPI 目录事实来自经网关对账的 models-data.json 快照（采集于 2026-07-24）。各项计数反映的是该快照中的字段，并不构成对质量或可用性的保证。
• OpenAI，《Unrolling the Codex agent loop》
• OpenAI，《Harness Engineering》
• Claude Code，《Create custom subagents》
• DeepSeek-V3 技术报告