给 Agent 做界面,约束比自由更值钱

2026-11-20T07:11:47+08:00 | 6分钟阅读 | 更新于 2026-11-20T07:11:47+08:00

@
给 Agent 做界面,约束比自由更值钱

一个朋友上周想让 agent 批量改图。装好 GIMP,写好提示词,跑起来第一件事是截图找菜单。分辨率一换,坐标全错。折腾两天,放弃了。

这类失败很常见,也很容易被归结成「模型还不够强」。但微软 AX 团队今年七月放出来的一组实测,指向另一个解释:卡住的往往不是模型能力,是界面本身。

一、同一件事,参数赢了 JSON

他们造了一个合成 CLI,叫 podctl,用来创建多服务部署。场景故意做得很复杂:两个服务、三层嵌套、数组、混合类型、服务之间有依赖引用,一个部署规格三十多个值。

然后做了两个二进制。一个只接受一个个参数,另一个只接受一整块 –json 载荷。两个共用同一套校验后端,最后归一成同一个结构。测试时把当前那个改名成 podctl,让 agent 看到的名字保持一致。因为 CLI 对模型来说是陌生的,它只能从 help 和 schema 里自己摸清输入模型。

五个模型各跑五次,harness 用 GitHub Copilot Chat。

模型参数JSON
Claude Sonnet 55/55/5
Claude Sonnet 4.65/55/5
GPT-5.3-Codex5/55/5
MAI-Code-1-Flash5/53/5
Claude Haiku 4.55/52/5

参数这一列全是满分,包括最小的那档模型。JSON 那列,强模型追平了,小模型直接掉到一半以下。

成本差得更难看。按 GitHub Models 的价格算,同一件事 JSON 模式贵 4 到 11 倍,GPT-5.3-Codex 从 0.05 美元涨到 0.54 美元。

钱花在哪了?重试。原始 token 差本来是 4 到 14 倍,缓存抵消了一部分,抵消不掉的是输出:JSON 路径的输出 token 是参数路径的 7 到 14 倍。模型把载荷拼错,读报错,想办法绕,写临时文件、套变量、换转义方式,这些全是输出,而输出是最贵的那类。

二、真正卡住它的是引号

有个容易被跳过的细节:shell 转义。

agent 把 JSON 当命令行参数传的时候,得先替 shell 把引号处理好。每个 shell 的规则都不一样,而且没有一个简单。模型经常生成了合法的 JSON,死在转义上。

主实验跑在 Windows,agent 默认用 PowerShell。Haiku 4.5 那五次失败里,有三次是内容完全正确、就是过不了 shell,它试过 base64、临时文件、here-string、绕 cmd.exe,token 烧完还是没进去。

同一份载荷,同一个模型,换到 macOS 的 Bash 重跑,成本差距从 9 倍缩到 1.5 倍。参数在两个 shell 上都稳。

这段我读的时候想的是:这跟「JSON 好不好」关系不大。参数的输入空间在 help 里写死了,能填的就那么几个名字和几个枚举值。JSON 把一个可枚举的空间换成了一个需要靠生成去满足的语法空间,多出来的每一层都是失败点。强模型能恢复,但恢复要花钱;弱模型恢复不了,就直接错了。

三、输入和输出,被做反了

这组实验最容易被误读的地方在这儿:它讲的是输入,不是输出。

输入要收窄,输出要定形。这两件事方向相反,很多工具刚好做反:输入给一整块 JSON,输出吐一张给人看的对齐表格。

输出侧的要求,其实早有人总结过。一个长期做 agent 工作流的作者写了八条,其中最要紧的是这三条:

  • --json 写 stdout,进度、警告、spinner 全写 stderr。stdout 是 API,stderr 是日志。终端宽度一变表格就换行,这类东西是 agent 静默失败的主要来源。
  • 退出码就是 agent 的控制流。0 成功、2 参数错、3 找不到、4 没权限、5 冲突,分开之后 agent 拿到 5 就能跳过创建走下一步。全返回 1 的话,它只能去读 stderr 猜,猜错概率不低。
  • 命令要幂等。agent 会重试,网络会断,命令会被打断。create 第二次失败它就得写特例,ensure 或 apply 天生没这问题。kubectl 那套设计在 agent 手上比在人手上更值钱。

这三条加起来做的是同一件事:把「读文字判断成败」换成「读状态判断成败」。

四、人味设计成了障碍

Speakeasy 那篇复盘是我今年读到最诚实的一篇。

他们两年前设计 CLI 的原则是「假设用户没有背景、让交互像对话、保持简单」。落地就是 Huh 做的交互提示、加载动画、进度表格,还有一步步引导的多阶段流程。他们当时挺自豪。

然后 agent 开始用它了。

提示框在等一个永远不会来的输入。spinner 在占上下文,还不提供任何信息。引导流程的每一步都是一个可能卡住的点。他们自己的原话:我们最自豪的功能,成了 agent 采用路上最大的障碍。

改法不复杂:--skip-interactive 把提示整个绕过,拿默认值走或者快速失败;退出码分类;把文档塞进 CLI 自己,用 speakeasy agent 这个子命令做渐进披露,让 agent 离线也能一层层往下查。

有个细节我印象很深。他们用 eval 对比开 skill 和不开 skill 的任务完成率,早期结论是「一个触发正确、但没帮上忙的 skill,比没有 skill 更糟,它吃掉上下文,什么也没产出」。这句话值得贴在每个写 skill 的人的显示器上。

我的判断是,CLI 不需要为「人机双用」重做一套设计。人机共用一个二进制完全可以,条件是三件事:交互可关、输出可选、文档可被程序读到。少了任何一个,自动化路径都会在某处断掉。

五、另一条更贵的路

如果说 Speakeasy 是给已有 CLI 开逃生舱,CLI-Anything 走的是反方向:给根本没有 CLI 的软件,造一个。

它昨天在 GitHub 趋势榜排第四,单日 899 个 star,仓库总共六万星。做法是不让 agent 截图点像素,而是给 GIMP、Blender、LibreOffice、Audacity、OBS、Kdenlive 这些真软件套一层有状态的命令行。命令最后调真的后端:LibreOffice 出 PDF,Blender 渲染 3D。

论文里把这一层叫 harness,给了个六元组的契约:状态空间、命令词表、检视面、渲染关系、验证层、发现层。翻成大白话,项目文件存哪、有哪些动词、怎么查当前状态、怎么出成品、怎么验它是对的、agent 怎么知道这工具存在。

有两条原则我认为是对的。一是委托真软件,不做玩具重实现,能力不打折。二是后端缺失时测试要 fail 不许 skip,因为 skip 会把「没测」伪装成「通过」,这个坑在 CI 里踩一次就够。

但账要算清楚。四十多个 harness 就是四十多条上游依赖,GIMP 和 Blender 的版本一动,适配层就漂。README 里写着两千多个测试,这个数字既是质量证明,也是维护成本的说明书。而且有命令树不等于模型会用,所以它还得给每个 harness 配一份 SKILL.md 当发现层,否则 agent 根本不知道该先调哪个。

两条路都合理,适用面不同。给已有 CLI 加逃生舱便宜、当天能上;给没有 API 的长尾软件造 harness 贵,但覆盖的是原来根本没法自动化的那部分。

六、几条能立刻用上的

如果你手上有工具想让 agent 用,我建议按这个顺序动:

  • 先把 help 写清楚。它就是 API 文档,模型第一件事永远是读它。
  • 输入用参数,输出用 JSON,别反着来。
  • 失败给结构化信号,退出码加一个能解析的 error 对象,别指望模型读自然语言。
  • 交互全部可关,破坏性命令给 --dry-run。
  • 写一份 SKILL.md,讲清楚什么时候该用、按什么顺序调。这比写一篇博客有用得多。

软件的上一个界面是人,现在多了一个用户。给这个新用户做界面,难的地方不在加功能,而在把「你随便填」改成「你只能这么来」。约束不是在限制它的能力,是替它把不确定性提前消掉。

参考来源

Me

Cut out summary from your post content here.

The remaining content of your post.