过去两年，谈到 AI Agent ，我们最常问的是：用了什么模型？上下文窗口有多长？ Benchmark 又提升了多少？

现在，问题正在发生变化。

当 Agent 开始读取项目、修改文件、运行命令、调用外部工具，甚至持续工作几十分钟时，我们更关心的是：它会不会找错文件？失败以后能不能继续？中断之后能不能恢复？高风险操作是否会等待确认？最后，它怎么证明自己真的完成了任务？

这意味着， Agent 工程的竞争正在从 “ 模型会不会答 ” ，转向 “ 系统能不能把任务稳定地跑完 ” 。而连接模型与真实执行环境的这套系统，通常被称为 Harness 。

（从回答一个问题到完成一个任务）

Prompt 解决 “ 怎么说 ” ，却解决不了整个任务

早期使用大模型时，我们主要研究 Prompt ：把角色、任务、约束、示例和输出格式写清楚，再通过 Zero-shot 、 Few-shot 、角色提示或多轮对话改善结果。

对于 “ 写一个冒泡排序函数 ” 这样的单次任务，这通常已经够用。

Ivan 在直播中特别提醒， Role Prompting 的价值主要是补充受众和判断角度。写一句 “ 你是一名专家 ” ，并不会自动提高事实准确性；模型仍然需要明确的任务边界、证据和验证方式。

但如果任务变成 “ 修复一个项目里的登录故障 ” ，模型需要的信息会迅速增加：项目结构、相关代码、错误日志、开发规范、测试方法，以及当前已经做到哪一步。更重要的是，这些信息并不是一次性给完的。 Agent 搜索代码、读取文件、运行测试后，每一步都会产生新的结果。

因此，工程问题从 “Prompt 应该怎么写 ” ，变成了 “ 模型在这一步究竟应该看到什么 ” 。 这就是 Context Engineering （上下文工程） 。

上下文越长，不等于上下文越好

Context 是模型在一次推理中实际收到的全部信息，可能包括系统指令、用户任务、项目文件、对话记录、工具说明和工具返回结果。

这里需要区分两个概念：

• Context Window 表示最多能装多少；

• Context 表示这一次实际装了什么。

把整个项目、全部日志、完整对话和所有工具说明统统塞给模型，看似信息充分，实际上容易让关键线索被噪声淹没。好的上下文工程并不追求 “ 装得最多 ” ，而是让模型每一步都拿到刚好合适的信息。

直播中用了一个很实际的例子：测试命令可能返回 2000 行日志，但真正重要的往往只是失败用例、异常堆栈和末尾几十行。如果 Harness 原样把日志全部塞回 Context ，模型下一轮还要重新找错误，相关代码反而可能被挤出去。更实用的方式是限制输出长度、提取报错附近内容，把完整日志保存到外部；模型先看摘要，需要证据时再读取原文。

它通常包括四件事：

1. 选择 ：保留当前任务真正相关的信息；

2. 检索 ：需要时再从文件、知识库或工具中取得资料；

3. 压缩 ：清理重复日志，概括过长的执行历史；

4. 保存 ：把计划、决策和进度写到上下文之外，避免会话一长就丢失。

这也解释了为什么 `AGENTS.md` 不适合写成一本百科全书。它更像项目地图：告诉 Agent 架构、测试、安全等详细规范放在哪里，真正需要时再读取。

可是， Context 不会自己搜索、整理、压缩和保存。谁来做这些工作？答案就是 Harness 。

Harness ：模型外面的 “ 任务运行系统 ”

可以把 Harness 理解为运行在模型之外的一套执行系统。模型负责理解任务、判断下一步； Harness 负责调用模型、组织任务、执行工具、保存状态，并根据真实结果继续推进。

一个更直观的表达是： Agent = Model + Harness

（Model 、 Harness 、 Sandbox 与 Agent 应用的关系）

如果把模型比作发动机， Harness 就像整车的传动、制动、仪表、导航和安全系统。发动机再强，如果没有稳定的控制系统，车也很难安全抵达目的地。

以 OpenAI Codex 和 DeepSeek Harness 为例：前者更接近已经落地的 Coding Agent 产品，涵盖 CLI 、 IDE 接入、权限、沙箱和会话管理；后者强调可组合、可替换的插件架构。二者形态不同，却都在回应相似的问题：工具怎么接入、任务怎么持续、状态怎么保存、权限怎么控制、失败怎么恢复。

一套较完整的 Harness ，至少涉及六层能力：

1. 接入与交互层 ： Chat 、 IDE 、 CLI 、 API ，以及进度展示和审批入口；

2. 编排与控制层 ： 目标、计划、任务列表、 Agent Loop 、重试和子 Agent ；

3. 模型适配层 ： 消息格式、模型路由、工具调用、结构化输出；

4. Context 与状态层 ： Session 、 Memory 、 RAG 、压缩和 Checkpoint ；

5. 工具与集成层 ： 文件系统、 Shell 、浏览器、 MCP 和 Skill ；

6. 执行与基础设施层 ： Sandbox 、容器、工作区、网络、密钥和配额。

权限、人工确认、 Trace 、评测、成本和审计等能力，则会贯穿各层。

（Harness 的六层结构与横切能力）

这六层是一种职责地图，并不意味着每个项目都必须建立六个目录或六套独立服务。小项目完全可以放在同一个进程中，但消息适配、工具执行和状态保存最好保持边界，否则换模型、恢复任务或排查故障时会越来越困难。

Agent Loop ：不是 “ 多调用几次模型 ” 这么简单

Agent 的基本工作方式是一个循环：模型决定下一步， Harness 执行工具，把结果写回上下文，再让模型继续判断。

例如，在 “ 为销售统计项目增加月度汇总功能 ” 的任务里， Agent 可能经历：读取 `app.py` 、分析 `sales.csv` 、修改函数、运行测试、发现失败、查看错误、再次修改，直到测试通过并生成结果文件。

但只写一个 `while true` 并不能得到可靠的 Agent 。没有边界的循环会出现很多问题：任务完成了还不停、同一个错误反复出现、每轮重读整个项目、重复执行有副作用的操作，或者 Token 与费用不断增长。

因此， Loop Engineering 真正设计的是循环中的控制机制：

• 目标和可验证的完成条件；

• 当前状态与下一步动作；

• 执行结果和高质量反馈；

• 最大轮数、费用或时间预算；

• 无进展、无法处理或需要人工判断时的停止规则。

其中最重要的一点是： 不能只听模型自己宣布 “ 完成了 ” 。

“ 优化这个 Python 项目 ” 无法验证； “ 修复除零错误、补充测试、全量测试通过、不修改现有 API 、最多运行 5 轮 ” 才是可以执行和检查的目标。

反馈同样不能只写 “ 测试失败，请重试 ” 。有用的反馈应该说明：哪个用例失败、期望结果是什么、实际结果是什么、错误出现在哪里，以及当前使用的是哪个代码版本。网络错误、参数错误、权限错误和逻辑错误需要进入不同处理路径，机械重跑只会让 Loop 卡住。

验证、状态与权限，决定 Agent 能不能进入生产环境

可靠的 Agent 系统通常会把执行者与裁判分开。 Agent 负责修改， Evaluator 负责检查。检查可以是确定性的测试、 Lint 、类型检查和构建，也可以是 Review Agent 、 LLM Judge 或人工审核。

反馈也要足够具体。与其说 “ 测试失败，请重试 ” ，不如告诉 Agent ：哪个用例失败、期望是什么、实际结果是什么、错误位于哪里。这样下一轮才是在纠错，而不是碰运气。

同时，日志和状态不能混为一谈。日志记录 “ 发生过什么 ” ，状态则要回答 “ 下一轮从哪里继续 ” 。 Checkpoint 至少需要保存当前步骤、已完成步骤、修改过的文件和最近一次结果。恢复时还要保证幂等性，避免重复写数据、重复发消息或重复部署。

实时进度也不等于可靠状态。 SSE 可以把 “ 正在读文件、正在测试、需要审批 ” 等事件推送到前端，让用户知道任务没有卡住；但前端掉线时可能漏掉事件，真正的 Run State 、 Checkpoint 和产物仍需保存在后端。

权限也需要分级：读取项目和运行测试可以自动允许；修改环境可以按策略决定；删除目录、访问外网或执行部署等高风险操作则应等待人工确认。 Sandbox 的价值，就是让代码可以运行，但不能 “ 想去哪就去哪 ” 。

任务变复杂以后， Loop 会进一步演进成 Graph

一个 Loop 适合围绕单一目标持续迭代。但真实任务往往包含并行工作、前后依赖、多角色协作、交叉检查和人工审批。如果把所有分支都塞进一个循环，系统会越来越难维护。

这时，任务可以表达成 Graph ：

• Node 负责执行代码、工具或 Agent ；

• Edge 决定下一步流向；

• State 在节点之间传递数据和进度。

例如， Code Agent 与 Test Agent 可以并行工作， Review Agent 在汇总后检查；如果验证失败，流程沿指定边返回修改；如果通过，则进入交付。这里的 Graph 指任务执行图，并不是知识图谱或 GraphRAG 。

（Graph 中 Node 、 Edge 与 State 的关系）

多 Agent 也不是一个 “ 默认提速开关 ” 。每个子 Agent 都需要自己的 Context 、工具权限、状态和执行环境，还会产生沟通与合并成本。只有当任务边界清楚、结果可以独立检查，或确实需要不同权限和长时间并行时，拆分才有价值。多个 Agent 同时修改同一文件，反而会制造冲突。

真正可靠的系统，还需要 Trace 、 Verify 与 Eval

这三个词经常一起出现，却回答不同问题：

• Trace 记录这次任务经过了哪些模型调用、工具参数、文件变化、错误、重试和审批，用于复盘与排错；

• Verify 在当前任务交付前检查结果，例如测试、 Lint 、构建、格式或业务规则；

• Eval 用一组固定任务比较不同模型、 Skill 或 Harness 版本的成功率、成本和耗时。

能用测试、 Schema 和业务规则确定的内容，应优先使用确定性检查。 LLM Judge 或 Review Agent 更适合处理代码可读性、文章质量等难以写死的标准，人工审核则应保留给业务判断、设计质量和高风险操作。

分享还谈到 “ 自我进化 Skill” ：系统可以从 Trace 中发现重复失败并提出规则修改建议，但不能因为一次偶然结果就悄悄修改长期规则。可靠的更新至少需要版本记录、回归测试、人工确认和回滚机制。

对开发者真正有用的三个结论

第一， 不要只用模型榜单判断 Agent 效果。 同一个模型放进不同 Harness ，表现可能完全不同。工具设计、上下文质量、验证机制和恢复能力都会直接影响结果。

第二， 先定义 “ 怎样算完成 ” ，再让 Agent 开始。 可验证的目标、预算和停止条件，比一句 “ 请把它做好 ” 更重要。

第三， 把稳定经验从 Prompt 中沉淀出来。 工具负责执行具体动作， Skill 保存某类任务的方法， Harness 控制整个任务怎样运行。重复任务不应每次都依赖临时提示。

Harness 并不是凭空出现的新技术。工具调用、状态机、队列、沙箱、工作流早已存在。它的新意在于：当 Agent 开始承担长时间、可执行、会产生真实副作用的任务时，这些能力第一次需要围绕模型被系统化地组织起来。

下一阶段的 Agent 工程，竞争的不只是 “ 谁的模型更聪明 ” ，而是谁能让模型在合适的上下文里，使用受控的工具，依据真实反馈持续推进，并用可验证的结果结束任务。

这也许正是从 Prompt Engineering 走向 Harness Engineering 的真正含义。