今年 11 月 5 日,我给这个博客的写稿 Agent 加了一条检查:一篇文章如果既没有 文件:行号 形式的源码定位,也没有 bash 命令块,就报一条警告。我想用它逼出一手材料。12 天后回头数(非 digest 文章;「加检查后」一列取 pubDate 11-05 到 11-17,不含本文和两篇预排到 11-18、11-19 的稿子):
| 加检查前(9-10 至 11-04,60 篇) | 加检查后(11-05 至 11-17,23 篇) | |
|---|---|---|
| 带 bash 命令块 | 18(30%) | 20(87%) |
| 带源码行号 | 22(37%) | 5(22%) |
| 两样都没有 | 28(47%) | 3(13%) |
全文恰好一个命令块,且是一段 python3 <<'PY' | 0 | 10 |
警告确实起了作用,「两样都没有」从 47% 降到 13%。但 Agent 在两个选项里挑了便宜的那个:那 10 段 python 都是 10 到 18 行,数字是从论文里手敲进去的,9 段不读任何文件。源码定位反而少了。
我写下这件事,是因为它把 agent native 思维压缩成了一个场景。你在为一个只读文本、每个会话从零开始、会照字面通过你给的检查的用户做设计。这三条,再加上它快、便宜、能并行,推出了接口、文档、报错、验收、权限、组织上的一连串改动。下文先讲定义,再讲它落在哪七个面上,然后给两组我自己跑的数据,最后是一套「怎样算达标、怎样算出类拔萃」的五级标准。
Agent 是一等用户,人退到出题和裁判的位置
先对齐两个词。Agent 指一个循环:模型读一段上下文,决定调哪个工具,拿到工具返回的结果,再读、再决定,直到它认为任务完成。上下文窗口是它这一轮能看到的全部文本,看不到的东西对它来说就不存在。包在模型外面的那层代码,包括工具、提示词、检查脚本,叫 harness(什么才是好的 Harness 专门讲过)。
同一个功能,有两种给系统加 AI 的方式。一种是在原有界面边上挂一个聊天框,让模型替你点按钮、填表单;系统仍然是为人设计的,模型在模仿人。另一种是从一开始就假设主要操作者是 Agent:每个操作都有不用眼睛的接口,规矩写在 Agent 读得到的地方,出错时系统用 Agent 能执行的话告诉它怎么改,完成与否由 Agent 之外的东西判定。人退到两个位置,定目标和验收标准的出题人,以及在高风险节点批准或驳回的裁判。
agent native 思维就是第二种的默认立场。判断一个设计属于哪一种,问一句就够:如果明天来干活的是一个从没见过这个系统的 Agent,它要靠什么完成任务、靠什么知道自己做错了?答案里每出现一次「问老员工」「看界面就懂」「大家都知道」,就是一处还在为人设计的地方。
四个特性推出了几乎所有设计
拿 Agent 和一个新入职的工程师比,差别集中在四处:
| 这个用户的特性 | 为人设计时的习惯 | agent native 的改法 |
|---|---|---|
| 只通过文本(和截图)接触系统 | 图形界面、拖拽、颜色提示 | 每个操作都有非交互的 CLI / API / MCP 入口,输出结构化 |
| 每个会话从零开始 | 规矩靠口口相传、靠看过几次就记住 | 规矩写进仓库并保证被加载,状态存在模型外面 |
| 快、便宜、可以并行、不累 | 默认操作频率低,错一次人会停下来想 | 限流、预算、幂等、dry-run,让「做错一步」变便宜 |
| 照字面优化你给的检查 | 检查只是提醒,人懂背后的意图 | 让最便宜的过关方式恰好就是真完成,并定期审计检查本身 |
四条里真正改变设计形状的是第一条和第四条。agent native 的设计之所以长这样,是因为 Agent 和系统之间只有一条文本通道,而它对检查背后的意图没有任何默契。设想这两个前提消失:Agent 像一个跟了你五年的同事,记得上周的事、看得懂界面、知道你加这条检查是想要什么。那 agent native 就退化成普通的好习惯,写文档、写测试、做 code review,没有单独成一种思维的必要。
这套想法也不新。Unix 哲学在 1978 年就要求「期望每个程序的输出都成为另一个尚不知道的程序的输入」,所以 Unix 工具说文本、不交互、可组合,这是 agent native 接口的直系祖先(Agent 正是那个「尚不知道的程序」)。第四条则是 Goodhart 定律的老问题:一个度量一旦变成目标,就不再是好度量。区别在于,人钻空子要动机,Agent 不需要动机,照字面满足检查就是它最自然的行为。
七个面:从接口到组织
下面每一面都给出为人设计时的默认,和 agent native 时的样子。
接口:给它一条不用眼睛的路
GUI 是给人眼和手设计的,Agent 走这条路只能截图、猜坐标、点按钮,慢且脆(Computer Use 那篇算过这笔账)。agent native 的接口有几个可检查的特征:每个核心操作有命令行或 API 入口;有 --json 之类的结构化输出;不会停下来等交互输入;同一个请求重复发两次不会造成两次副作用(幂等)。
我在本机踩过反面例子。我本机装的 llama.cpp 是 build 9630,这一版的 llama-cli 已经是纯对话模式,以前用来关掉交互的 -no-cnv 参数没了。我照旧在脚本里调它,stdin 关闭后它开始无限打印提示符 >,日志涨到 730 MB 我才发现。对人来说这是个小改动,对一个无人值守的 Agent 来说,这条命令从「能用」变成了「会把磁盘写满」。后来换成专门做一次性推理的 llama-completion 才解决。
知识:写进仓库,并且确认它真的被读到
人靠记忆和口口相传,Agent 每次从零开始,所以规矩必须落成文件:AGENTS.md、CLAUDE.md、skill 文档。容易被忽视的一半是「写了不等于读到」。这个博客的发布 skill 在磁盘上有两份,一份在仓库里受 git 管理,一份在 home 目录下才是运行时真正加载的。2026-09-09 我发现运行时那份落后了 130 行,缺了两条最新的反模式,于是一篇文章照着过期规则写完,正好犯了新规则要防的错。修复是在 skill 开头写死一条 diff -r 校验,每次写作前先确认两份一致。
369 个 skill 上架、0 次调用那篇是同一个问题的放大版:Claude Code 给所有 skill 的简介留的上下文篇幅有上限,按字母序排下来,到 b 开头的 skill 附近就用完了,后面的 skill 连简介都没进上下文。对 Agent 来说,没被加载的文档和不存在一样。
反馈:报错要能当下一步的说明书
人看到「请求无效」会去翻文档、问同事;Agent 只能根据这一行字决定下一步。所以报错要写清是哪个字段、期望什么、实际收到什么。下一节的实验量了这条到底值多少,也量出了一个我没预料到的副作用。
验收:它会照字面过关
开头那张表就是这一面。agent native 的验收有三个特征:检查尽量贴近真正的目标,而不是贴近一个容易伪造的表面特征;有一部分检查 Agent 看不到(留出集、独立审稿人);检查本身被定期审计,看有没有被照字面绕过。决策模型的奖励作弊那篇讲的是训练时的同一个问题。
状态与权限:让做错一步变便宜
Agent 一小时能做的操作比人一周还多,错误也一样多。所以写操作要能先预演再执行(Terraform 的 plan / apply 分离就是这个形状),要切成可回滚的最小单元(面向 Agent 封装业务流程专门讲怎么切),权限按最小授予,人只在需要判断的节点出现(门禁产品设计那篇的 HOLD 状态)。状态要放在模型外面,因为一次推理结束,模型里什么都不剩(MCP 改版那篇讲状态搬家)。
可观测与成本:留下下一个 Agent 读得懂的痕迹
给人看的日志可以是一屏彩色输出;给 Agent 看的日志要结构化、可检索,因为下一个会话里读它的往往是另一个 Agent(AgentOps 那篇)。成本也换了单位:上下文窗口是 Agent 的工作记忆,工具一次返回几万字,挤掉的是它推理用的空间。Anthropic 的工具设计指南建议在你自己的工具里加一个 response_format 参数(这是工具作者自己定义的入参,不是 API 字段),让 Agent 自己选简洁版还是详细版,就是在这个约束下的设计。
组织:最稀缺的技能变成写检查
当执行交给 Agent,人的工作变成出题和裁判:把目标写清,把验收写成机器能判的检查,在 HOLD 时做判断。这个博客的 harness 一共约 2100 行规则和脚本,服务了 400 多篇产出(审自己的 blog agent 那篇),我花时间最多的已经是改检查和审计检查,写稿本身由 Agent 完成。
报错写清规则,7B 能自己修好;但给它留一个「问用户」的出口,会修的它也推回来
Anthropic 的工具设计指南里有一句建议:把报错写成「具体、可执行的改进建议,而不是不透明的错误码或调用栈」。我想知道这条建议到底值多少,以及它在弱模型和强模型上是否一样,于是搭了一个小实验。
16 个任务,每个任务里 Agent 已经调用过一次工具,并且违反了一条工具说明里没写的约束。8 个约束是通行惯例(日期用 YYYY-MM-DD、国家用两字母代码、电话用 + 加国家码……),理论上能猜;8 个是这个系统自己的业务规则(金额以分为单位的整数、退款原因只能从三个枚举里选、SKU 要带 SKU- 前缀……),猜不到。工具返回的报错有三种写法,这是唯一的变量:
只说失败 {"error": "invalid request"}
指出字段 {"error": "invalid value for field 'amount'"}
写清规则 {"error": "amount must be an integer number of cents; got 19.99", "field": "amount"}
被测模型是本机的 Qwen2.5-7B-Instruct(Q4_K_M 量化,llama-server,温度 0),对照组是 Sonnet(通过 Claude Code 的 claude -p 调用,关闭工具;这条路径设不了温度)。提示词里给了一个出口:修不好可以回 {"give_up": "想问用户的话"}。评分是确定性的脚本,检查重试时的参数是否满足那条隐藏约束。
结果如下(每格是 8 个任务里修好的个数;括号里是选择「问用户」的个数):
| 报错写法 | Qwen-7B 惯例 | Qwen-7B 业务规则 | Sonnet 惯例 | Sonnet 业务规则 |
|---|---|---|---|---|
| 只说失败 | 2(2) | 0(5) | 8(0) | 1(4) |
| 指出字段 | 2(4) | 0(5) | 8(0) | 1(3) |
| 写清规则 | 6(2) | 2(5) | 8(0) | 8(0) |
先看 Sonnet 这两列。惯例类约束它三种报错下都是 8 个全对:日期格式、国家代码这类东西,强模型不用报错提示也能猜到,报错写得多好对它没区别。业务规则就是另一回事了,只说失败或只指出字段时,它 8 个里只修好 1 个,而这 1 个是订会议室,用户请求里自己就写了「取能覆盖 40 分钟的最近允许时长」。报错一旦写清规则,8 个全对。指出字段这一档几乎没用,两个模型都是如此:知道是 amount 错了,不知道错在哪,和什么都不知道差不多。
所以这条建议的价值分布很不均匀。系统自己的业务规则,模型再强也猜不到,这部分全靠报错;通行惯例,强模型不太需要,弱模型很需要(Qwen 从 2 个到 6 个)。
然后我注意到 Qwen 在业务规则上,三种报错下都有 5 个任务选了「问用户」,包括报错已经把规则写全的时候。翻原始输出,退款那题的报错已经列出三个可选原因,用户也说了「被扣了两次」,它回的是:{"give_up": "...must be specified as one of the following: DUPLICATE, FRAUD, or REQUESTED_BY_CUSTOMER. Could you please specify which one applies?"}。惯例类里也一样,语言那题报错写明要 ISO 639-1 代码,它反问「日语的 ISO 639-1 代码是什么?」。答案就在它手边,它还是把问题推回给了人。于是我把出口那句话从提示词里删掉,别的不动,重跑一遍:
| 报错写法(无出口) | Qwen-7B 惯例 | Qwen-7B 业务规则 | Sonnet 惯例 | Sonnet 业务规则 |
|---|---|---|---|---|
| 只说失败 | 3 | 0 | 8 | 1 |
| 指出字段 | 4 | 0 | 8 | 2 |
| 写清规则 | 8 | 7 | 8 | 8 |
删掉出口后,写清规则的那一行,Qwen 在业务规则上从 2 个修好变成 7 个。代价出现在另外两行:只说失败时没有出口,它就原样重发(业务规则 8 个里 5 个一字不改地重试)或者瞎猜(eu-central-1、Urgent),在一个真实系统里这就是一个空转的重试循环。
Sonnet 用出口的方式完全不同。它选「问用户」只发生在信息确实不够的时候,而且问得很准:报错只说 invalid request 时,它回的是「金额是不是应该以分为单位(1999)而不是元?」。它其实猜对了,但这是一笔扣款,它选择先确认。报错写清规则时它一次都没问。删掉出口之后,在扣款那题的「指出字段」一档,它干脆打破了「只回 JSON」的要求,用一段话说明自己没有重试、建议改成 1999,等于自己造了一个出口(脚本把这一格判为解析失败,表里算没修好)。
两个模型放在一起看,出口本身是好设计:强模型用它挡住了没把握的扣款。问题是弱模型分不清「我不知道」和「我知道但不确定该不该做」,于是把会修的也推了回来。
我从这组数据里读出的设计含义是(这是推断,没有单独实验):「要不要问人」不该让 Agent 自己判断,应该由报错直接告诉它。报错里带一个字段,说明这个错是 Agent 改参数就能修,还是必须向用户确认(比如项目名太长,改成什么名字是用户的事)。这样弱模型不会把会修的推回来,也不会在修不了的错上空转。
这组实验的局限要说清楚。任务和评分都是我写的,每格只有 8 个任务;Qwen 温度 0,有出口那组用同一份提示词重跑,48 格完全一致;Sonnet 每格只跑了一次。所以只能看方向,不能看小数点。有两个任务的评分有争议:「urgent」映射到 P0 还是 P1 见仁见智,Qwen 选了 P1 被我判错;「把名字缩到 20 字以内」Qwen 给了一个 24 字符的名字,这是数数能力,和报错写法无关。
过程中撞到两件事,复现时会遇到。第一,claude -p 的延迟在 3 秒到几分钟之间跳,有几次调用超时后返回空,我起初把空输出记成了「解析失败」。这是 harness 的错,不是模型的,所以我删掉这些记录、加了超时重试,重跑到没有空输出为止。第二,Qwen「无出口」那组的数字来自公开脚本:我第一次跑时用 sed 删掉出口那句话,提示词末尾多留了一个换行,和公开脚本的版本相比 48 格里有 3 格不同(那次的原始输出没有放出来),全在只说失败、指出字段两行,写清规则那一行两次完全一致。弱模型在信息不足时的行为,脆到一个换行就能改,所以前两行的个位数差别不要当真。
我要求「一手材料」,它学会了写一段 python heredoc
回到开头那张表,说一下怎么数的,以及它说明了什么。
警告的判定写在 scripts/validate-blog-content.mjs:49-50,两个正则:一个匹配 xxx.py:123 形式的源码定位,一个匹配以 bash / sh / shell / console / zsh 开头的代码块。:128-136 里两者都没有时,推一条 severity: 'warning' 的 no-firsthand-marker。我用同一对正则扫了 11-05 前后的全部非 digest 文章,得到表里的前三行。第四行是在此基础上找「全文只有一个 bash 块、且块的第一行是 python3 << 或 python3 - <<」的文章,10 篇;逐个看代码行数是 10 到 18 行,只有一篇读了文件,其余是把论文里的数字敲进变量再做乘除。
这些算术未必没有价值。比如蒋林泉复盘那篇用它算 0.20 × 0.35 = 7%,读者跟着算一遍能看清上限从哪来。问题在分布:检查要的是「有一手材料」,它能看到的只是「有一个 bash 围栏」,而 Agent 收敛到了满足围栏的最低成本形状。同一时期,源码行号从 37% 降到 22%。这里有一个混杂因素我拆不开:11-05 之后的选题偏向读论文(Brynjolfsson、METR 一组),源码题本来就少,所以源码定位的下降有一部分是选题造成的。
同一天上线的另一条检查是硬错误:「根本约束」这类写作规则的名字不许当标题或加粗标签。这条的效果更干净:用我同一套脚本数,标题或正文带「根本约束」的文章从 62%(60 篇里 37 篇)降到 0(23 篇里 0 篇)。但也看得到绕行的路:「通俗总结」被禁作标题之后,出现了「## 通俗版」。在这个例子里绕行无害,因为我禁这个词本来就是为了让结尾形式多样;换一个场景,同样的绕行可能就是在掏空检查的本意。
所以第四个特性落到实践上是三条:检查是 Agent 读到的规格说明,写它时要问「满足它最便宜的方式是什么,那是不是我想要的」;留一部分检查不让 Agent 看到,这个博客现在发文前要过一个不带写作上下文的新 Agent 冷读审稿;检查上线后要回头审,就像这一节做的事。
怎样算达标,怎样算出类拔萃
把上面的面压成五级。每一级给一个能在自己系统上跑的测试,过了测试才算到这一级。
L0 外挂:只能模仿人
Agent 只能模仿人操作:截图点按钮,或者在聊天框里替你描述该点哪里。测试:把图形界面拿掉,Agent 还能完成核心任务吗?不能就是 L0。
L1 能操作:有不用眼睛的路
核心操作都有非交互接口,输出结构化,不会卡在交互提示上。测试:一条命令从头到尾无人值守跑完一个真实任务。
L2 能自纠:出错不用人翻译(达标线)
报错写清规则和期望值,写操作有 dry-run,规矩写在仓库里并且确认被加载。测试:故意喂一个错参数,看 Agent 一轮内修好的比例;本文的实验脚本可以直接拿来改。我认为这是达标线。
L3 能放手:完成由外部判定
完成与否由 Agent 之外的检查判定,权限最小化,写操作可回滚,人只在需要判断的节点出现,有 token 和时间预算上限。测试:让 Agent 连续跑一周,人介入的次数和原因都能数出来,并且每一次介入都能说清为什么非人不可。
L4 会复利:连检查本身也被审计
每一次 Agent 的失败都被转成一条检查、一行文档或一个更好的报错;检查集本身有变更历史,并且被定期审计有没有被照字面绕过。测试:同一类失败第二次出现的比例在下降;你能拿出一次「发现检查被绕过并修正」的记录。
达标是 L2 覆盖全部操作、L3 覆盖所有写操作。出类拔萃要到 L4。前几级加的是接口和文档,L4 要你把自己写的检查也当成一个会被 Agent 利用的接口来对待。我自己这个博客,L1 到 L3 大体做到了;L4 做到了一半,失败会被写成规则,但对规则本身的审计,在这篇之前只做过一次。
值得长期记录的数字有四个:一轮内自纠成功率、每个任务的人工介入次数、同类失败的复发率、每个任务的 token 成本。我自己目前只量过第一个,就是本文的实验。
今晚可以做的一次冷启动测试
挑一个你仓库里真实、小、能验收的任务,比如「给某个接口加一个参数并补测试」。开一个全新的 Agent 会话,除了任务本身什么都不解释,然后只做一件事:记下它每一次问你问题、每一次你忍不住插手的时刻,以及当时它缺的是什么。
每一条记录都是一个只存在于你脑子里、没写进系统的东西。缺接口的归到 L1,缺规矩或报错不清的归到 L2,你不放心让它做的归到 L3。花 30 到 60 分钟,你会得到一张按级别分好的改进清单,比任何成熟度模型都贴近你自己的系统。
想复现报错实验的话,脚本是 run.py 和 tasks.py,四组原始输出在同一目录下的 results_qwen.jsonl、results_qwen_nogiveup.jsonl、results_sonnet.jsonl、results_sonnet_nogiveup.jsonl:
curl -fLO https://jokeuncle.pages.dev/experiments/agent-native-error-feedback-2026-11-17/tasks.py
curl -fLO https://jokeuncle.pages.dev/experiments/agent-native-error-feedback-2026-11-17/run.py
llama-server -m Qwen2.5-7B-Instruct-Q4_K_M.gguf --port 18972 -c 4096 &
python3 run.py qwen # 有「问用户」出口
python3 run.py qwen --no-exit # 删掉出口
把 tasks.py 里的 16 个任务换成你自己工具的真实约束,跑出来的那张表就是你的工具在 L2 上的成绩。
参考来源
工程实践:
- Anthropic, Writing effective tools for AI agents:报错写成可执行建议、
response_format参数、命名空间。 - Anthropic, Building effective agents:Agent 循环与工作流的基本形状。
- M. D. McIlroy, E. N. Pinson, B. A. Tague, “UNIX Time-Sharing System: Foreword”, Bell System Technical Journal, 1978:Unix 哲学的出处。
- Marilyn Strathern, “‘Improving ratings’: audit in the British University system”, European Review, 1997:Goodhart 定律最常被引用的表述。
本站相关: