别再迷信模型能力：构建生产级 AI Agent 的 5 个工程真相

1. 引言：Agent 浪潮下的“工程冷思考”

在 Agent 领域，开发者往往陷入一种“算力崇拜”：认为只要换上更贵的模型，Agent 的表现就会脱胎换骨。然而现实是，即便堆砌最强的模型，你的 Agent 仍然可能在简单任务中反复“撞墙”。

作为 OpenClaw 的核心开发者，我们在实践中发现：Agent 的成功率往往不在于模型本身，而在于围绕它构建的“工程约束（Harness）”。如果模型是引擎，工程架构就是底座。本文将揭示构建生产级 Agent 的五个工程真相：成功不在于让模型“更聪明”，而在于让系统“更确定”。

2. 真相一：测试与约束（Harness）比模型本身更关键

决定一个 Agent 系统能否收敛的，往往是其外围的工程条件。我们将其总结为 Harness（工程约束） 的四个核心：验收基线（Acceptance Baseline）、执行边界（Execution Boundary）、反馈信号（Feedback Signal）以及回退手段（Fallback Measures）。

案例深思：从 Codex 到 Anthropic 的极限实验

OpenAI Codex： 3 名工程师在 5 个月内产出百万行代码，其核心竞争力并非单纯的生成能力，而是为其配备了临时可观测性栈（Observability Stack）。通过 VictoriaLogs、Metrics 和 Traces，Agent 能够主动查询系统状态（如图 3 所示），在自验证闭环中修正行为，而非被动等待报错。

Anthropic C 编译器实验： 在构建能编译 Linux 内核的编译器时，高性能模型在接近极限时会不断产生回归 Bug。最终项目得以推进，靠的是“高质量测试先行”以及引入 GCC 作为对照验证。

工程直觉

Agent 的本质是在概率空间搜索答案。如果没有清晰的自动化验证和执行边界，Agent 就会在“快反馈、错方向”的象限里高效地产生随机性。

“Agent 只有在有清晰测试的情况下，才会朝正确方向优化，否则只会高效地写 Bug。”

3. 真相二：上下文工程的核心是“分层”与“按需加载”

开发者常把上下文窗口（Context Window）当成垃圾桶。但从底层逻辑看，Transformer 注意力的复杂度是 O(n²)。随着上下文增加，关键信号会被噪声稀释，导致“上下文腐化（Context Rot）”。

从提示工程转向上下文工程

我们在 OpenClaw 的实践中强调，上下文必须进行生命周期管理：

系统提示作为索引（Skills 模式）： 避免预加载全量知识。系统提示应只保留 Skills 索引，完整文档按需加载。这种“延迟加载”能显著降低 Token 稀释风险。

MCP vs. CLI 的抉择： 需警惕模型上下文协议（MCP）带来的副作用。MCP 往往会一次性返回完整结果且无法在前端过滤，容易导致上下文迅速膨胀。相比之下，CLI 结合单句描述的 Skill 模式更易于控制和压缩。

标识符保护协议： 在进行摘要或压缩时，绝对不要改动标识符（如 UUID、Hash、IP、Port、URL、文件名）。这些精确值一旦被“模糊化”，后续工具调用将引发毁灭性故障。

架构师视角： “克制”的上下文反而能带来最稳定的决策。

4. 真相三：工具设计的重心从 API 转向 ACI（Agent-Computer Interface）

工具定义的质量直接决定了 Agent 的行动上限。差的设计会让强模型变笨，而符合 ACI 原则 的设计则能让模型实现质跃。

从 API 到 ACI 的进化

ACI 要求工具设计应对应 Agent 的目标，而非底层 API 的粒度。

维度

API 导向 (差的设计)

ACI 导向 (优的设计)

原子性

分离的 create_file, set_perm

目标导向的 create_script(path, content, exe)

描述深度

仅功能描述：读取日志

边界定义：Use when / Don't use when

示例驱动

无示例，依赖模型推断

Tool Use Examples：附带 1-5 个真实调用示例

高级能力

静态加载全部定义

Tool Search：根据需求动态发现工具定义

数据真相： 增加 1-5 个调用示例，能将工具调用的准确率从 72% 提升至 90%。此外，引入代码化工具编排（Programmatic Tool Calling），让中间数据在执行环境中流转而非反复穿过模型，能将长任务的 Token 消耗从 15万降至 2千。

5. 真相四：文件系统才是 Agent 长任务的“真实大脑”

Agent 不具备原生时间连续性。对于跨 Session 的长任务，依赖对话上下文保存状态是极其脆弱的。

外部化状态管理与四层记忆架构

我们提倡将 Agent 的状态彻底外部化，构建四层存储体系：

工作记忆（Work Memory）： 当前 Session 的消息流。

程序性记忆（Procedural Memory）： 即 Skills，定义“如何做”，按需加载。

情景记忆（Episodic Memory）： JSONL 格式的完整会话历史。

语义记忆（Semantic Memory）： 即 MEMORY.md。这是 Agent 主动写入的稳定事实，可读、可改、可检索。

长任务执行模式

在 OpenClaw 中，我们采用 Initializer Agent（负责生成 feature-list.json 等进度文件）与 Coding Agent（负责具体执行）的协作模式。Coding Agent 是**可重入（Re-entrant）**的，它不依赖上一轮对话，而是通过读取文件系统中的任务清单和 Git 记录来恢复现场。

“真正跨 session 传递状态的，不是上下文窗口，而是文件系统里的进度文件和 git 记录。”

6. 真相五：评测陷阱——你的基础设施可能在“拖后腿”

很多开发者在 Agent 表现下滑时会忙着改 Prompt，却忽略了评测系统本身的缺陷。

核心指标对齐

Pass@k（能力评测）： 衡量上限。只要 k 次尝试中有一次成功即可。用于探索模型能力的边界。

Pass^k（回归测试）： 衡量可靠性。要求 k 次运行必须全部通过。这是生产环境上线前的硬指标。

警惕基础设施错误（Infra Error）

Source Context 中的实验数据显示了一个惊人的真相：在 1x 资源受限的环境下，基础设施错误率高达 6.5%，这往往会被误认为是模型能力的退化；而当环境切换到 Uncapped（无限制）时，这类错误会降至接近 0%。

架构师建议： 先修评测系统，再改 Agent 代码。评测应以产出物导向（Outcome-based），关注系统最终的状态变更（如数据库记录），而非 Agent 说了什么（Transcript）。

7. 结语：从“尝试”转向“确定性”

构建 Agent 不再是简单的 Prompt 堆砌，而是一场严谨的工程实践。当我们能够通过完美的 Harness 约束模型、通过 ACI 优化工具、通过文件系统外化状态并建立科学的评测体系时，Agent 才能从“概率性的玩具”变成“确定性的生产力”。

思考题： 当我们的工程基础设施（Harness）足够完美时，我们是否还需要追求最强大的模型，还是说一个“足够好”的模型配合完美的工程架构，才是 AI 时代的终局方案？

原文：x.com