Agent 为什么总翻车？因为你只配了模型，忘了给它搭脚手架

我先说一件前几天刚发生的事。

我用 Kimi K3 跑了一批任务，其中一个是给 AIHOT 加热点榜单功能，背后需要接入 500 个新信源。K3 非常勤恳地完成了所有开发、推了 PR、过了 CI、部署上线。

然后，AIHOT 将近 1 小时没有任何新资讯进站。

原因是 K3 在新功能上线的同时，把那 500 个信源的历史数据一次性全部回填，塞进来了 9000 条信息，直接把处理队列堵死了。

问题出在 K3 身上吗？不，问题出在 Harness 上。

没有限速写入，没有分批导入，没有队列监控告警——这是脚手架层面的设计缺失，不是模型能力的问题。换 GPT-5.6 Sol 来做，我后来测了，照样没考虑这个并发问题。

这就是今天要聊的话题：Harness Engineering——决定 Agent 在现实任务中成功还是失败的那套脚手架。

有一个 GitHub 仓库叫 awesome-harness-engineering，系统整理了这个领域的 12 个核心组件。我把它结合自己的实战体感，给大家拆解一遍。

先说清楚：Harness ≠ 模型

这个概念很多人搞混。

模型是大脑，负责推理和决策；Harness 是骨架和神经系统，负责让大脑的决策能够落地执行。

一个更精准的定义：

Harness Engineering 是设计围绕 AI Agent 的脚手架的学科——环境交付、工具接口、规划产物、验证循环、记忆系统和沙箱——它决定了 Agent 在实际任务中成功还是失败。

这里有一个很反直觉但非常重要的结论：同一个模型，Harness 配置的差异，可以让 benchmark 分数相差 5 个百分点以上。 Anthropic 的 2026 年 Agentic Coding Trends Report 里明确写了这个数据。

换句话说：你以为在比模型，其实在比脚手架。

12 个组件，逐一拆解

1. Agent 循环

这是一切的基础。最经典的是 ReAct 框架：Reasoning（推理）→ Acting（执行）→ Observing（观测）→ 循环。

Agent 每次行动前先推理，执行后观测结果，再推理下一步。

听起来简单，但工程上有很多细节：

• 循环的终止条件是什么？最大步数？Token 上限？任务完成判断？
• 工具调用失败了，循环该怎么走？直接重试？降级？报错退出？
• 长时间运行的 Agent，如何支持断点续跑而不是从头重来？

LangGraph 做的就是把这个循环图形化、持久化，让你能精确控制每一个节点的行为和状态转移。

2. 规划与任务分解

"帮我优化服务器性能"——这种任务，直接扔给 Agent，大概率翻车。

好的 Harness 在 Agent 动手之前，会先让它出一个计划：把大任务拆成可验证的小步骤，每步有明确的输入输出定义，有检查点，有回滚条件。

多 Agent 场景下，规划层更重要——谁负责什么、任务之间的依赖关系是什么、失败了怎么切换——这些都是 Orchestrator 该做的事，不是靠模型自己脑补的。

我的体感：模型越强，它的计划越像样；但再强的模型，计划仍然需要 Harness 来强制校验和执行，而不是当口头承诺。

3. 上下文传递与压缩

这一块是我觉得被严重低估的一个设计变量。

Token 是有限的，但任务的上下文是无限的。怎么办？

三个主要策略：

• 分层检索把上下文存到向量库，按需召回，而不是全部塞进 prompt
• 滚动压缩对话历史太长了，用模型摘要成精华，丢掉细节
• Prompt 缓存把固定的系统 prompt 缓存起来，只传变化的部分

我在 AIHOT 里现在已经踩过上下文设计的坑：Agent 处理长对话时，如果不做压缩，Token 成本指数级上涨，还容易迷失方向。好的上下文传递策略，比换一个贵 10 倍的模型更值钱。

4. 工具设计

这里有一个我非常认同的设计哲学：工具要窄，不要宽。

query(sql) 这种工具，可以执行任意 SQL，看起来很强大，但 Agent 拿到它以后会出各种你意想不到的操作。 get_order_by_id(order_id: str) 这种工具，只干一件事，Schema 明确，参数有校验，失败信息清晰——这才是对 Agent 友好的工具设计。

另外，工具的错误描述和工具本身一样重要。Agent 调工具失败了，如果错误信息只是 500 Internal Server Error，它只能乱试；如果错误信息是 order_id 格式不正确，期望格式：ORD-XXXXXX，它一次就能修正。

5. 技能与 MCP

MCP（Model Context Protocol）是今年 AI 工程里最重要的基础设施之一，没有之一。

它解决的问题是：如何让 Agent 以标准化的方式连接到外部工具和数据源，而不是为每个工具单独写一套集成逻辑。

更进一步的是 Agent Skills——把 Agent 的能力定义成可复用、可移植的模块，一次定义，在 OpenAI、Anthropic、Gemini 上都能跑。这让能力积累从"个人经验"变成了"可传递的资产"。

Composio 已经预包装了 250+ 个 SaaS 服务的集成，这就是 MCP 生态成熟之后应该有的样子。

6. 权限与授权

这块最容易被忽视，也最容易出问题。

很多人的权限设计是：在 System Prompt 里写"你不能删除数据"。

这根本不是权限，这是祈祷。

正确的做法是：权限通过工具 Schema 的声明、状态机的约束、中间件的拦截来强制执行，而不是靠自然语言告诫模型。

具体来说：

• 只读操作 vs 写操作，分成不同的工具，不同的权限集
• 高风险操作（删除、付款、发送消息）需要通过独立的授权步骤才能触发
• Agent 的权限范围和人类用户的权限范围完全隔离，不能互相越界

这套东西，IETF 有相关标准在推进，叫 OAuth for Agents。

7. 记忆与状态

Agent 的记忆分三层：

Letta（MemGPT）是目前三层记忆架构的最佳参考实现之一。核心思想是：记忆不是被动存储，而是一个随任务执行主动更新、随时间主动演化的活系统。

我在 Claude Code 里用的 auto-memory Skill，本质上就是在做这件事——把每次有价值的对话结论写到文件里，下次对话自动加载，让 Agent 越用越"懂你"。

8. 任务运行器与编排

多 Agent 系统本质上是分布式系统，它会遇到分布式系统的所有经典问题：

• 状态一致性：A 和 B 同时修改同一个文件，谁的算数？
• 失败恢复：某个子 Agent 挂了，任务怎么接管？
• 任务交接：A 做完了，把结果以什么格式交给 B？

LangGraph 的 checkpoint-resume 机制、CrewAI 的角色化编排、AutoGen 的对话式多 Agent——每种框架在这些问题上的取舍都不同。没有银弹，看你的任务特性选。

9. 验证与 CI 集成

Agent 写的代码、生成的配置、输出的文档——都需要验证。

好的 Harness 里，验证是内建的，不是人工的。每次 Agent 提交修改，自动跑测试，自动做 lint，失败了自动反馈给 Agent 让它修。

这就是为什么 Kimi K3 能在 2 小时内完成 10 个任务然后自己提 PR 过 CI——这不是模型的能力，这是 Harness 提供了可靠的验证反馈循环。

如果没有这个循环，Agent 其实是在"盲写"，它不知道自己写对了没有，只能等你人工检查。

10. 可观测性与追踪

这一块，我的血泪教训是：你以为 Agent 在做 A，它其实在做 B，而你完全不知道。

好的可观测性意味着：

• 每一步推理有日志，知道 Agent 在想什么
• 每一次工具调用有追踪，知道调了什么、入参是什么、返回是什么
• 成本、延迟、Token 消耗有监控，知道钱花在哪里
• 异常有告警，不用人工盯着

LLM Observability 工具这两年发展很快，LangSmith、Langfuse、Phoenix 都是这个方向的代表。核心不是工具，是养成"Agent 行为必须透明"的工程文化。

11. 调试与开发者体验

本地调试 Agent 是一件比调试普通代码难得多的事，因为 Agent 的行为有概率性，同样的输入不一定给同样的输出。

好的 DX 应该包括：

• 本地可以快速复现线上 Agent 的行为（不是每次都要调用真实 API）
• 能回放某一次 Agent 的执行轨迹，逐步检查每一步决策
• 能针对单个工具写 unit test，不用跑整个 Agent 流程

这个领域还不够成熟，但方向是对的：把 Agent 的调试体验做到接近普通代码的调试体验。

12. 人工介入（Human-in-the-Loop）

最后这个组件，说起来简单，做好了是壁垒。

核心原则：不可逆操作，必须人工确认。

• 查数据 → 可以自动
• 删数据 → 必须暂停，给人看，等确认
• 发邮件 → 必须暂停，给人看，等确认
• 付款、部署生产 → 必须暂停，给人看，等确认

不同的是，HITL 不只是"暂停等确认"，还可以是"在检查点展示 Agent 的计划，人工审批后再执行"——这让人类始终在决策回路里，而不是事后追责。

Martin Fowler 对这件事的描述是："Humans on the loop，而不是 Humans in the loop"——不是每次都要人插手，而是要让人能随时插手。

最反直觉的一条设计哲学

读完这 12 个组件，你可能会觉得：Harness 要做的事情真多，好麻烦。

但这个 awesome list 的介绍里有一句话让我印象很深：

最好的 Harness 在设计时就意识到，随着模型能力的提升，这些组件将变得不再必要。

这是一种非常清醒的工程态度：你今天搭的脚手架，是为了弥补模型现在还不够强的地方。模型越来越强，有些 Harness 组件会逐渐退出历史舞台。

三年前，我们要为 Agent 写大量的 few-shot 示例，教它怎么调工具——现在的模型基本不需要了。

今天，我们还在为 Agent 写复杂的规划提示词、手动管理上下文压缩——也许两年后，这些也会变得不必要。

设计 Harness 的正确心态是：搭好脚手架，但不要依恋它。随时准备把某个组件拆掉，让模型自己接管那块能力。

总结

Harness Engineering 的核心价值，是把 Agent 能力从"实验室里能跑"变成"生产环境里靠谱"。

回到我在开头说的那次翻车：K3 写了没有限速的批量导入，根本原因是 Harness 没有提供"队列容量感知"这个反馈信号。换 Fable 5 来，大概率也一样翻。这是一个 Harness 问题，不是模型问题。

这 12 个组件，没有哪个是可选的——只是不同阶段，你会先踩哪个坑的区别。

awesome-harness-engineering 这个仓库整理得很全，需要的时候当手册查。

你现在在做 Agent 系统，踩过哪些 Harness 层面的坑？评论区聊聊。

— 完 —