从 agent 轨迹里找可访问性缺陷：评分看不出的事

如果你的评估只看“任务有没有完成”，它很可能已经给了满分，而 agent 在你的产品上猜了八次 404、把插件 DLL 当纯文本读、还给 CI runner 埋下了一个没人注意的网络改道。微软开发者博客 2026 年 11 月 5 日的一篇文章记录了这样一次评估：同一任务跑五遍，五个脚本都能用，轨迹里却有 15 个问题（来源：Your best AX fixes are hiding in agent trajectories）。

这里的 AX 指 agent experience，即 agent 使用你的 API、CLI 和文档时的体验，不是无障碍（accessibility）。文章的主张可以压成一句：评分回答“有没有完成”，轨迹回答“在哪里挣扎”，后者才是产品要改的地方。本文按提供的材料整理这七类模式、对应的修法和适用边界。

一次“全通过”的评估长什么样#

材料给出的实验设置是：GitHub Copilot Chat，模型 Claude Sonnet 5.5，不装扩展，同一任务重复五次——写一个 CI 脚本，调用 Dev Proxy 的 API，记录某个 Node.js 工具调用了哪些 GitHub API。Dev Proxy 是微软的本地代理，用来拦截应用的 HTTP 请求。

结果是：五份脚本都能工作，五条轨迹合计 15 个问题，每次运行发出 29 到 39 个请求，最多消耗 120 万 token。文章的解释是 agent 很“执着”：404 之后换一个 URL 再试，报错之后换一个值再试，直到错误消失。挣扎因此很少反映在分数上。

轨迹里值得找的七种模式#

1. 先猜 URL，再考虑搜索

agent 常常跳过搜索，按记忆中的文档站点结构直接拼路径。材料中，五次运行里有四次在读任何文档之前就请求了 https://learn.microsoft.com/en-us/microsoft-cloud/dev/dev-proxy/technical-reference/api，返回 404；真实页面是 technical-reference/proxy-api。两次运行多花五到七步才找到，另外两次干脆放弃文档、改为凭记忆试错。读文档之后猜测仍在继续：有运行访问了 technical-reference/plugins/executionsummaryplugin，而该页实际位于 technical-reference/executionsummaryplugin。四次运行合计八次 404。

对应的修法不复杂：翻 404 日志里那些“几乎存在”的文档路径，每一条都值得加一个重定向；同时把文档 URL 直接打印在 CLI 输出里，让 agent 不必猜。日志未必能告诉你访问者是不是 agent，但重定向对人和 agent 都有效。

2. 接口只差一步：错误说错，不说对

面向人的帮助文本，读者遇到不清楚的地方可以去翻文档；agent 则把它当成规格说明。材料的例子是 Dev Proxy 列出 POST /proxy 和 GET /proxy/rootCertificate，却不显示请求体和必需参数。有运行照列表直接调用证书接口，收到 400：

{ "errors": { "format": ["The format field is required."] } }

错误没说 format 接受哪些值，agent 依次试了 pem、crt、cer、der，只有 crt 有效。每一轮都是额外的请求和 token。修法是：跑一遍自己的 CLI help，再故意触发最常见的几个错误，确认每条信息都说明“合法输入长什么样”，给示例或允许值列表。

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

单次运行里出现一次绕路是噪声；每条轨迹都写出同一段绕路，说明产品缺了一项能力。材料里有两个例子。

其一是报告生成没有完成信号。录制停止后报告才写出，agent 无法知道何时写完。四次运行轮询输出目录，最长 30 秒；第五次直接等两秒：

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

材料评价说，在繁忙的 CI runner 上这个写法迟早会失败；轮询更稳，但每次轮询都得猜该等哪个文件。

其二是没有插件列表命令。五次运行都选择把插件 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

它确实有效，所以任何只看结果的评分都不会报错，但它既不稳健也谈不上高效。修法有两条：任何在调用返回之后才完成的操作，都要有告知“完成了”的方式；任何需要 agent 从中选择的东西，比如插件或模板，都要有列举命令。

4. 文档边界之外，靠模型记忆补

开发者会把你的工具和其他运行时、框架一起用，而文档常常写到自己的边界就停了。要让 Node.js 应用走 Dev Proxy，应用的 fetch 需要一个较新 Node 版本才支持的开关。材料中五次运行都从记忆里知道这一点，并写出“undici 默认不遵守 HTTPS_PROXY，需要启用 NODE_USE_ENV_PROXY，要求 Node 22.21.0+ 或 24.0+”，但没有一次是在 Dev Proxy 文档里找到的。

这次都答对了，风险在于模型知道得更少时：代码看起来正常，实际什么都没记录，也不报错。轨迹里的信号是“陈述了事实但没有引用来源”的推理。可做的检查是：列出开发者常与你搭配的运行时和框架，逐个补上配置说明；对你没写的那些，跑一个任务，看 agent 自己填了什么。

5. agent 会拒绝为“第一次运行”设计的默认值

默认配置和入门模板通常服务于第一次运行：让人在几分钟内确认链路通了、看到产品能做什么。对具体任务，它反而挡路。Dev Proxy 的默认配置会在示例 API 上模拟随机错误，agent 立刻判断“应该避开默认配置，否则会注入随机错误”，于是自建配置；而新建配置是空的，每次运行各建一套，同一个目标用了三种不同插件。

修法不是删掉默认值，而是在它旁边为常见任务准备 preset，让每次运行都从同一个正确起点出发，并把 preset 写进 agent 会早早读到的 CLI help。

6. 搜索结果里的旧快照

agent 经常通过搜索引擎读你的说明，而索引提供的是快照。你上个月改过的页面，可能仍以旧内容排在前面；译文和你为 agent 发布的 skill 文件同理。agent 分不清旧快照和当前页面。

材料中的例子：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——help 随安装版本发布，不会过期。可做的检查是：拿几个开发者真正会交给 agent 的任务，按 agent 会用的搜索词搜一遍，确认结果（包括译文和自家 skill）描述的是当前版本。你无法刷新别人的索引，但可以在每页顶部写明版本要求，让它出现在搜索摘要里。

7. help 文本没声明的默认值

材料在这一节处被截断，只能确认其论点：agent 从 help 文本学习 CLI，并逐字理解。一个读起来像“打开开关”的选项，agent 会假定它默认关闭；如果它其实默认开启，agent 就永远不会传关闭它的值，因为没人告诉它要传。多数选项的代价只是运行行为与预期不符；而对于会改变工具之外状态的默认值，agent 交出的脚本就带着它不知道的副作用，而任务仍然成功，评估同样抓不到。材料给出的 Dev Proxy 例子在截断处停止（“Dev Proxy sets itself as the …”），后续内容本文不作推断。

模式、轨迹信号与修法对照#

在自己的产品上怎么开始#

1. 先留住轨迹。记录每一步的工具调用、参数、返回，以及客户端能提供的推理说明。没有轨迹，评估只能告诉你成败。
2. 跨运行对照。同一段弯路只出现一次，可能是偶发；出现四次以上，通常是产品缺口。
3. 按出口修，而不是按 agent 修。把改进落在重定向、错误体、列举命令、完成信号、preset 和版本标注上，这些对人和 agent 都生效。
4. 用同一任务复跑。观察请求数与步数是否下降、404 是否消失，而不是只看脚本能不能跑。

边界与不确定性#

• 材料来自单一产品（Dev Proxy）、单一模型与客户端组合、五次运行，数字与模式不能当作行业统计。
• “15 个问题”是文章自述的计数，材料未给出判定口径。
• 提供的正文在第七种模式处截断，结论可能在未提供部分；本文不据此推断全文。
• 文中的 curl、PowerShell 与 JavaScript 片段均引自媒体材料，未执行，不作为可运行示例或预期输出。
• “AX”在此语境指 agent experience；把它读成无障碍会偏离材料主题。

对面向开发者的接口平台而言，最便宜的改进往往不是新增端点，而是让已有端点可被猜中、可被列举、可被确认完成，并在错误信息里把“什么是对的”说清楚。这些改动大多不需要新的服务能力，只需要把已经存在于团队脑子里的信息，写进 agent 最先读到的地方。