技术文章

外部链接将在新标签页打开。

代理轨迹里的可访问性问题:运行都通过时该看什么信号

一句话回答

评测分数只能说明代理完成了任务,不能说明它走得顺不顺。微软团队用 Dev Proxy 做的 5 次运行全部产出可用脚本,轨迹里却有 15 处问题:猜错文档 URL、错误信息不给合法值、每次重造同一 workaround、用记忆补文档空白、绕开默认配置、信任搜索旧快照、忽略 help 未声明的默认值。本文梳理这七类信号、对应的检查动作,以及这些案例的证据边界。

核心要点 TL;DR
  • 运行通过不等于路径合理:先看重复步骤、无来源断言和 404/400 重试,再看分数。
  • 七类信号里多数修复落在文档、错误信息和 help 文本上,而不是模型能力上。
  • 案例来自微软团队对 Dev Proxy 的 5 次评估,本文未复现;抓取到的原文在第七类信号处截断。

评测分数(eval score)只回答一件事:代理有没有把任务做完。它不回答代理是怎么做完的——绕了多少路、在哪里靠猜、哪些代码看着正确其实随时会坏。要回答后者,得看轨迹(trajectory):代理每一步发出什么请求、收到什么、以及它为什么这么走(Microsoft for Developers)。

先澄清用词:本文说的“可访问性”不是 WCAG 意义上的无障碍,而是代理能否顺利到达并使用你的文档、CLI 帮助、错误提示和搜索结果。微软那篇文章把它归入 AX(agent experience,代理体验)。

证据基础也要说清楚。以下案例来自微软开发者博客 2026 年 11 月 5 日的文章:作者让 GitHub Copilot Chat(Claude Sonnet 5.5、不带扩展)把同一个任务跑了 5 次,任务是用 Dev Proxy 的 API 写一个 CI 脚本,记录某个 Node.js 工具调用了哪些 GitHub API。5 个脚本都能运行,轨迹里却有 15 处问题,每次运行花 29 到 39 个请求、最多 120 万 token。这些数字是来源报告的结果,本文没有复现;抓取到的正文在第七类信号处被截断,后面会单独标注。

分数衡量结果,轨迹衡量路径#

分数会漏掉问题,是因为代理很执着:遇到 404 就换一个 URL 再试,报错就换一个值再试,直到错误消失。任务最终成功,过程中的猜测就被抹平了。轨迹把这些步骤重新展开——而在所有运行里重复出现的步骤,通常正是产品侧可以修的东西。

七类信号:从猜错地址到看不见的默认值#

1. 先猜 URL,再考虑要不要搜

代理常常跳过检索,直接按记忆里的文档站点结构拼一个地址。猜错一次就多花一步和相应的 token;连错一两次,有的代理会彻底放弃文档,此后纯靠记忆和试错,过时与编造的答案就是这么来的。

案例:5 次运行里有 4 次在没读文档前先请求 technical-reference/api,返回 404(真实页面是 technical-reference/proxy-api)。两次多花 5 到 7 步才找到,另两次放弃文档。读过文档之后猜测仍在继续:technical-reference/plugins/executionsummaryplugin 同样不存在。4 次运行合计 8 次 404。

动作:翻 404 日志里那些“几乎存在”的文档路径,逐个加跳转;同时在 CLI 输出里打印文档 URL,让代理不必猜。

2. 接口只说哪里错,不说什么是对的

help 和错误信息往往是写给“能自己去翻文档的人”的,代理却把它们当规格说明。只说错了什么、不说正确值长什么样,代理就会猜一个值、读下一条错误、再猜一次。

案例:Dev Proxy 的端点列表只写 POST /proxy、GET /proxy/rootCertificate,不写请求体和必填参数。代理照列表调用得到 400,响应体是 {"errors":{"format":["The format field is required."]}}。错误没有给出合法值,代理依次试了 pem、crt、cer、der,只有 crt 有效。

动作:跑一遍 CLI help,再故意触发最常见的几个错误,确认每条都给出合法输入的样子——一个示例,或者全部允许值。

3. 每次运行都在重造同一个 workaround

单次出现是噪声;每次出现,说明产品缺一个东西,而每个开发者的代理都要为这个缺口付出 token,最后拿到比“本该有的功能”更脆弱的代码。

案例一:报告在停止录制后异步写盘,没有完成信号。4 次运行轮询输出目录最多 30 秒,第 5 次直接睡 2 秒。在繁忙的 CI runner 上,这个写法早晚会失败。

await api('POST', '/proxy', { recording: false });
await sleep(2000); // let the reporters flush their files

案例二:没有列出插件的命令,5 次运行全都把插件 DLL 当原始字节读,用正则抓类名。以下片段是来源文章中复述的代理生成代码,本次未执行:

$b = [IO.File]::ReadAllBytes("$d\plugins\DevProxy.Plugins.dll")
$s = [Text.Encoding]::Unicode.GetString($b)
[regex]::Matches($s, '\b[A-Z]\w*(Plugin|Reporter)\b') | % { $_.Value } | sort -u

动作:凡是调用返回后才完成的操作,给出一个完成信号;凡是代理需要从中挑选的东西(插件、模板),给一个列举命令。

4. 文档停在工具边界,代理用记忆补

开发者会把你的工具和其他运行时、框架一起用,而文档常常写到自己的边界就停了。缺口由模型记忆填上:恰好知道,运行成功,你永远收不到反馈;不知道或记的是旧版本,就会写出看着对、实际什么都不做且不报错的代码。

案例:要让 Node.js 应用走 Dev Proxy,应用的 fetch 需要一个较新 Node 版本才支持的选择项。5 次运行都从记忆里知道要用 NODE_USE_ENV_PROXY,并且要求 Node 22.21.0+ 或 24.0+,但没有一次是在 Dev Proxy 文档里读到的。轨迹里这类缺口表现为“陈述了一个事实、却没引用任何来源”的推理。

动作:列出开发者常搭配的运行时与框架,逐个补接入步骤;对跳过的那几个,跑一次任务,看代理自己把什么填了进去。

5. 代理会主动绕开“为首次运行设计”的默认配置

默认配置和脚手架服务于首次运行:让人在几分钟内确认装好了、能看到产品能做什么。这个目标它完成得很好,但面对具体任务常常碍事。代理一旦判断默认值不合适,就会从零搭自己的配置,于是每次运行搭出不同的东西。

案例:Dev Proxy 的默认配置在示例 API 上注入随机错误。代理立刻识别出它会干扰真实流量记录并自建配置;而自建的配置是空的,结果同一个目标,各次运行选了三种不同的插件组合。

动作:保留让首次运行成功的默认值,同时在旁边为每个常见任务准备预设,并把预设写进代理会较早读到的 CLI help。

6. 代理信任搜索结果里的旧快照

代理经常通过搜索引擎读你的指引,而索引提供的是快照。上个月改过的页面,搜索结果里可能还是旧内容;翻译页和自己发布的 agent skill 同理。代理分不清快照和当前版本,于是破坏性变更之后,排名靠前的旧副本会长期继续产出坏代码。

案例:Dev Proxy API 自 v3.3.1 起要求 token。一次运行的搜索返回两条旧结果:一条是 6 月抓取的乌克兰语 API 参考翻译,一条来自 Dev Proxy 自己的 agent skill——源文件在运行前六周已更新,但索引到的版本仍是不带 token 的调用。这类调用现在返回 401。来源给出的旧写法如下,本次未执行:

curl -X POST http://localhost:8897/proxy \
 -H "Content-Type: application/json" \
 -d '{"recording": true}'

那次运行最终没出错,只因为它先读了随安装版本一起分发的 CLI help——那份文本不会过期。

动作:拿几个开发者常交给代理的任务,用代理会用的关键词自己搜一遍,检查结果(包括翻译页和你自己的 skill)描述的是不是当前版本;在每页顶部写明适用版本,让它进入搜索摘要。

7. help 文本没写明的默认值,代理当作不存在

代理从 help 学 CLI,而且字面理解:一个选项读起来像“开关”,它就假设不传即关闭。如果实际默认是开启,代理永远不会传关闭它的值,因为没人告诉它要传。多数情况下代价只是行为不符预期;如果这个默认值改动了工具之外的东西,代理就会交出一个带未知副作用的脚本——任务照样成功,评测照样抓不到。

边界:抓取到的正文恰在这里被截断,原文举的具体默认项及其后果没有出现在本次材料中,细节待核实。可确认的只有这条信号的读法:逐个检查 help 里没有标注默认值的选项,凡是会改变工具外部状态的,都写明默认值和关闭方式。

把轨迹读成一份待办清单#

  1. 固定一个可重复的任务,跑 3 到 5 次。全部通过才有观察价值:失败运行暴露的是模型能力问题,通过运行暴露的才是产品问题。
  2. 按“重复次数”排序。同一段异常步骤出现在多数运行里,优先级最高。
  3. 给每一步归类:猜地址→查 404 日志与跳转;试值→改错误信息;自建补丁→补缺失功能;无来源断言→补文档空白;绕开默认→给任务预设;引用旧快照→标版本;默认值误解→改 help 文本。
  4. 修完用同一任务再跑一遍,看这类步骤是否消失。这一步别只盯分数,分数本来就不会动。

这些信号能说明什么,不能说明什么#

能说明:代理在你的文档和接口上遇到的具体摩擦点,以及这些摩擦是否稳定复现。这正是“可访问性”的实用定义——不是能不能用,而是要用起来得绕多少路。

不能说明:某类修复一定提升任务成功率。来源作者的建议是基于 5 次运行的模式归纳,不是对照实验;本次材料也没有提供修复后的复测数据。加上样本只有 5 次运行、单一模型、单一产品,这七类信号更接近一份检查清单,而不是普遍规律。先修你自己轨迹里出现频率最高的那一类,比照着清单全改更划算。

常见问题(FAQ)

没有完整的轨迹日志,从哪里开始查?
404 日志、CLI help、最常见的错误信息这三处不需要轨迹也能查,而且恰好覆盖七类信号里成本最低的几项。轨迹主要用来确认哪些步骤在所有运行里重复出现。
这里的“可访问性”指什么?
指代理能否顺利到达并使用你的文档、CLI 帮助、错误提示和搜索结果,也就是微软文章所说的 AX(agent experience,代理体验),不是 WCAG 意义上的无障碍合规。

参考来源

  1. Your best AX fixes are hiding in agent trajectories

以上为本文写作时的参考资料,引用观点以原文为准。

作者:沐小悠

本文约 11 分钟读完 · 关键词:代理轨迹、AX、agent experience、Dev Proxy、CLI 帮助文本

更多文章 GET 示例接口

「」标签下的其他文章