Agent 工作台工程:有能力的模型为何仍失败

Agent 工作台工程:有能力的模型为何仍失败

本节摘要:一个有能力的模型,不够。可靠的 Agent 需要一个工作台(workbench)——指令、状态、范围、反馈、验证、审查、交接。把这些剥掉,即便是前沿模型产出的工作也不安全到可交付。诊断很扎心:你把一个前沿模型丢进真实仓库,让它「加输入校验」,它打开四个文件、写出看起来合理的代码、宣布成功、停下。你跑测试——两个失败;第三个被改的文件和校验毫无关系;没有任何记录说明 Agent 假设了什么、先试了什么、还剩什么没做。模型没在 Python 上犯错,它在**「工作」上犯错——它不知道什么算「完成」、哪里允许写、哪些测试是权威的、下一次会话该怎么接手。这不是模型 bug,是工作台 bug**。本节是第 15 章压轴主题(工作台工程,第 31~42 节)的开篇,定义工作台的七个面(Instructions/State/Scope/Feedback/Verification/Review/Handoff),并给出一个关键洞见:工作台独立于模型——你可以换模型保留这些面,但不能换掉这些面还指望保留可靠性。更重要的是,本节把这七面还原到底层的分布式系统八原语(函数/工人/触发器/运行时/HTTP-RPC/队列/会话持久化/授权策略)——所有流行的工作台/外壳(harness)模式(Ralph Loop、PEV、OAP、Guides-Sensors、渐进压缩、MCP、沙箱)都只是这些老原语换了新名字。 receipts 也很硬:Terminal Bench 2.0 同模型只换外壳就从 30 名外冲到第 5;Vercel 删掉 80% 工具,成功率从 80% 跳到 100%;Harvey 法律 Agent 单靠外壳优化准确率翻倍;88% 企业 AI Agent 项目到不了生产,失败聚集在运行时而非推理。读完本节,你应能用「提示 vs 工作台」「框架 vs 工作台」两道区分,把厂商 UX 描述翻译回工程原语。

对应原课程:Phase 14 · Lesson 31 · agent-workbench-why-models-fail(原英文 phases/14-agent-engineering/31-agent-workbench-why-models-fail/docs/en.md)。前置:第 01 节(Agent 循环)、第 26 节(失败模式)。

学习目标

阅读完本节,你应当能够:

1. 把模型能力与执行可靠性分开。
2. 说出决定一个 Agent 能否交付的七个工作台面。
3. 在一个小仓库任务上,对比「仅提示」运行与「工作台引导」运行。
4. 产出一份失败模式报告,把每个缺失的面映射到它引起的症状。
5. 把七个工作台面还原到底层的分布式系统八原语。

一、问题与直觉

你把一个前沿模型丢进真实仓库,让它加输入校验。它打开四个文件,写出看起来合理的代码,宣布成功,停下。你跑测试——两个失败。第三个被改的文件和校验毫无关系。没有任何记录说明 Agent 假设了什么、先试了什么、还剩什么没做。

模型没在 Python 上犯错。它在**「工作」上**犯错。它不知道什么算「完成」、哪里允许写、哪些测试是权威的、下一次会话该怎么接手。

这不是模型 bug,是工作台 bug。模型周围的面,缺了把「一次性生成」变成「可靠、可续跑的工程」的那些部分。

循环闭合在状态文件上,而非聊天历史。聊天是易失的;仓库才是真相之源(system of record)。

七个工作台面

工作台是任务期间包裹模型的运行环境。它有七个面:

工作台独立于模型。你可以换模型、保留这些面;但你不能换掉这些面、还指望保留可靠性。

工作台 vs 提示工程

提示告诉模型「这一轮你要什么」。工作台告诉模型「跨轮、跨会话如何做工作」。大多数 Agent 失败故事,是穿着提示工程外衣的工作台失败。

工作台 vs 框架

框架给你运行时(LangGraph、AutoGen、Agents SDK)。工作台给 Agent 一个在运行时里面干活的地方。两者都需要。这个小专题(第 31~42 节)讲的是第二个。

从原语推理,而非从厂商分类

当下关于「外壳工程(harness engineering)」的写作很多。Addy Osmani、OpenAI、Anthropic、LangChain、Martin Fowler、MongoDB、HumanLayer、Augment Code、Thoughtworks 等都在谈。它们对外壳的边界、范围、词汇各执一词。我们不必选边——七个面是 UX 层;每个工作台底下,都是同一套撑起任何可靠后端的分布式系统原语。

暂时剥掉 Agent 标签。一次 Agent 运行,是跨越时间、进程、机器的计算。要让它可靠,你需要和生产系统一样的原语:

现在把七个工作台面映射到这些原语:

• 指令 —— 策略 + 函数元数据。规则是检查(函数)。路由器(AGENTS.md)是挂在运行时启动上的策略。
• 状态 —— 会话持久化。一个运行时每步读取的键控存储。文件、KV 或 DB;持久化语义才承重,存储后端不重要。
• 范围 —— 按任务的授权策略。允许/禁用 glob 是 ACL;需审批的是权限格。
• 反馈 —— 写进队列的调用日志。每次 shell 调用是一条记录,持久、可重放。
• 验证 —— 一个函数。对输入确定。任务关闭时触发。失败即关闭(fails closed)。
• 审查 —— 一个独立工人,对建造者产物只读授权、对审查报告只写授权。
• 交接 —— 由会话结束触发器发出的持久记录。下次会话的启动触发器读它。

Agent 循环本身是一个工人——消费事件(用户消息、工具结果、定时 tick)、调用函数(模型、再模型选的工具)、写记录(状态、反馈)、发触发器(验证、审查、交接)。毫无神秘;和作业处理器同形。

流行模式,翻译成原语

每个流行的外壳模式都归约到这八个原语。翻译表:

表里每一项,都是 Agent 社区到达了一个在分布式系统里早有名字的原语、然后给它起了个新名字。做营销标签有用;做工程词汇没用。

receipts 实际说了什么

「外壳胜过模型」的主张,现在有数字撑腰。值得知道,因为它们也是对「等个更聪明的模型就行」唯一诚实的反驳:

• Terminal Bench 2.0 —— 同模型,只换外壳,把一个编码 Agent 从 30 名外移到第 5 名(LangChain《Anatomy of an Agent Harness》)。
• Vercel —— 删掉其 Agent 80% 的工具;成功率从 80% 跳到 100%(MongoDB)。
• Harvey —— 法律 Agent 单靠外壳优化,准确率翻倍(MongoDB)。
• 88% 的企业 AI Agent 项目到不了生产。失败聚集在运行时,而非推理(preprints.org,《Harness Engineering for Language Agents》,2026-03)。
• 一项 2025 年基准研究,跨三个流行开源框架报告约 50% 任务完成率;长上下文 WebAgent 在长上下文条件下从 40-50% 崩到 10% 以下,主因是无限循环与目标丢失。

要点不是「外壳永远赢」。模型确实会随时间吸收外壳技巧。要点是:今天,承重的工程在模型周围,不在模型内部;而承载那分量的原语,是每个生产系统一直都需要的那些。

⚠️ 厂商写作停在哪里:不必客气地说——LangChain 的《Anatomy》枚举了十一组件,却不命名队列、工人作为部署单元、触发器语义、会话持久化为独立关注点、授权策略,把外壳当成你配置的对象而非你部署的系统。Addy Osmani 落地了 Agent = Model + Harness 与棘轮模式,却没说外壳用什么造的。Anthropic 与 OpenAI 在面上最深,但留在自家运行时内。这些都是在写一个已存在系统的 UX 描述;而我们写的是系统本身。系统造对了,七面从原语里自然掉出来;造错了,再多 AGENTS.md 抛光也修不好缺失的队列。听到「外壳工程」时,翻译回原语:提示与规则是策略与函数,脚手架是运行时,护栏是授权+验证,钩子是触发器,记忆是会话持久化,Ralph Loop 是重新入队,子智能体是工人,沙箱是计算面。词汇会变,工程不变。

二、从零实现

原课程 code/main.py 把一个小仓库任务跑两遍:先仅提示,再接好七个面。同模型、同任务。脚本数失败运行缺失了哪些面,打印失败模式报告。

仓库任务故意很小:给一个单文件的 FastAPI 式处理器加输入校验,并写一个通过的测试。

# 仅提示运行:Agent 没有范围/反馈/验证/审查/交接
def prompt_only_run(task):
    files_touched = agent.edit_files(task, allowed=ALL_FILES)  # 无范围
    return {"claim": "success",                              # 在 400 上宣布成功
            "touched": files_touched,                         # 含无关文件
            "tests_run": False}                               # 没跑验证

# 工作台运行:七面接好
def workbench_run(task):
    scope = load_scope_contract(task)            # 范围:允许/禁用 glob
    state = load_agent_state()                   # 状态:上次到哪
    while not done(state):
        out = agent.step(state, scope)           # 循环读状态与范围
        feedback = capture(out.shell_cmd)        # 反馈:真实命令输出进队列
        state = update(state, out, feedback)
        if verify(state, scope):                 # 验证:测试+lint+范围检查
            if reviewer.approve(state):          # 审查:第二角色
                write_handoff(state)             # 交接:持久记录
                return "shipped"
    return "blocked"
​

运行 python3 code/main.py 会输出两次运行的并排日志、一份总结仅提示运行的 failure_modes.json、工作台运行的一行裁决。

💡 设计要点:这节的 Agent 是个微小的基于规则的桩;重点是面,不是模型。在剩余的小专题里,你会把每个面重建为真实、可复用的产物。核心心法是「循环闭合在状态文件上,而非聊天历史」——聊天易失,仓库才是真相之源,这与第 07 节 MemGPT「外部存储是磁盘」、第 17 节「会话存储」一脉相承,只是这里把整个工程纪律显式化。

三、框架对比

工作台面在野外已存在,只是没人这么叫:

• Claude Code、Codex、Cursor —— AGENTS.md/CLAUDE.md 是指令面;斜杠命令是范围;钩子是验证。
• LangGraph、OpenAI Agents SDK —— 检查点与会话存储是状态面;handoff 是交接面。
• 真实仓库的 CI —— 测试/lint/类型检查是验证;PR 模板是交接;CODEOWNERS 是审查。

工作台工程,就是把这些面显式化、可复用,而不是让每个团队重新发现的纪律。

四、可复用产物

原课程 outputs/skill-workbench-audit.md:一个可移植的技能,审计一个已有仓库的七个工作台面,报告哪些缺失、哪些部分、哪些健康。丢到任何 Agent 设置旁,它告诉你先修什么。

五、练习

1. (Easy) 挑一个你已跑 Agent 的仓库。给七面打 0(缺失)到 2(健康)。你最弱的面是哪个?
2. (Medium) 扩展 main.py,让仅提示运行也产出一条假的「成功」声明。验证验证门能抓住它。
3. (Medium) 为你自己的产品加第八个面。论证它为何不塌进现有七面之一。
4. (Hard) 用一个幻觉出额外文件写的不同桩 Agent 重跑脚本。哪个面先抓住它?
5. (Hard) 把第 26 节的五种行业复发失败模式映射到七面。每个面设计来吸收哪种模式?

本节要点回顾

1. 有能力的模型不够:剥掉工作台七面,前沿模型产出的工作也不安全到可交付。
2. 七个工作台面:指令、状态、范围、反馈、验证、审查、交接——决定 Agent 能否交付。
3. 工作台独立于模型:换模型可保留面,换掉面保不住可靠性。
4. 循环闭合在状态文件,非聊天历史:聊天易失,仓库是真相之源。
5. 工作台 vs 提示:提示管「这一轮」,工作台管「跨轮跨会话」;大多失败是穿着提示外衣的工作台失败。
6. 工作台 vs 框架:框架给运行时,工作台给 Agent 在运行时里干活的地方;两者都要。
7. 八分布式原语:函数/工人/触发器/运行时/HTTP-RPC/队列/会话持久化/授权策略——所有外壳模式的老底。
8. 流行模式都是老原语换新名:Ralph Loop=重新入队,PEV=三工人,OAP=授权策略,沙箱=计算面,MCP=带能力的工人 RPC。
9. receipts 硬:同模型换外壳从 30 名外到第 5;删 80% 工具成功率 80%→100%;Harvey 翻倍;88% 项目到不了生产,失败在运行时非推理。
10. 承重工程在模型周围,不在内部:今天如此;词汇会变,工程不变——听到「外壳工程」翻译回八原语。

下一节,我们开始逐个重建工作台面——从最小 Agent 工作台起步:用最少代码搭出一个带范围、状态、反馈、验证的能跑真实仓库任务的骨架,后续节再逐面加深。