藏在 agent 轨迹里的 AX 修复线索：七个模式与对应的产品改动

评估分数只回答一个问题：agent 有没有把任务做完。要改进产品与 agent 的配合，需要看另一份材料，也就是轨迹（trajectory），即 agent 每一步动作及其理由的记录。微软 Dev Proxy 团队做过一次评估：5 次运行全部产出了能用的 CI 脚本，评分上看不出异常；轨迹里却记录了 15 个问题，每次运行花掉 29–39 次请求，最高消耗 120 万 token（Microsoft for Developers）。

先说术语。从正文讨论的内容看，这里的 AX 指 agent experience，即 agent 使用你的产品时的体验，与无障碍（accessibility）无关；材料本身没有给出术语定义，这是根据上下文作的判断。本文沿用这个用法。

为什么「全部通过」仍值得读轨迹#

分数是结果指标，轨迹是过程记录。材料给出的关键观察是：agent 很执着。遇到 404 就换一个 URL 猜，遇到报错就换一个值试，直到错误消失。这种试错不会让任务失败，所以不会出现在分数里，但它会消耗请求和 token，并且可能产出「能跑但脆弱」的代码。

更有价值的信号是重复：单次运行里的绕路是噪声，五次运行里出现同一段绕路，说明产品缺了东西。下面七个模式按这个思路整理。

七个可复用的轨迹模式#

1. 先猜 URL，再考虑搜索

agent 常常跳过搜索，直接按它对文档站结构的记忆拼路径。材料中，5 次运行里有 4 次在阅读任何文档之前，先请求了 https://learn.microsoft.com/en-us/microsoft-cloud/dev/dev-proxy/technical-reference/api，返回 404；真实路径是 technical-reference/proxy-api。两次运行多花 5–7 步才找到，另外两次干脆放弃文档。

读文档之后猜测仍在继续：一次运行找到真实 API 页后，又去请求 technical-reference/plugins/executionsummaryplugin，而该页实际在 technical-reference/executionsummaryplugin。4 次运行合计产生 8 次 404。

修复方向：翻 404 日志里那些「几乎存在」的文档路径，每条都值得加一个重定向；同时在 CLI 输出里打印文档 URL，让 agent 不必猜。

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

帮助文本和错误信息往往是写给「能自己去翻文档的人」的，agent 却把它当规范读。Dev Proxy 的端点列表只写了 GET /proxy/rootCertificate，没有请求体和必填参数。一次运行照此调用，得到 400：

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

错误没有列出合法值，agent 只能依次试 pem、crt、cer、der，只有 crt 有效。

修复方向：把 CLI help 跑一遍，再手动触发最常见的几个错误，确认每条信息都给出合法输入的示例或允许值列表。

3. 每次运行都在重造同一个绕过方案

产品缺什么，agent 就自己搭什么。Dev Proxy 在停止录制后不久写报告，但没有「写完了」的信号。材料里 4 次运行轮询输出目录，最长等 30 秒；第 5 次直接睡 2 秒：

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

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

更奇怪的是插件。Dev Proxy 没有列出插件的命令，于是 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

它能工作，所以评分永远不会暴露它，但它既不健壮也谈不上高效。轨迹能暴露，因为同一个反常步骤在每次运行里都出现。以上两段代码为材料中的示例片段，本文未执行。

修复方向：每个「调用返回后才真正完成」的操作都需要完成信号；每个需要 agent 从中挑选的对象（插件、模板）都需要一条列表命令。

4. 文档的缺口由模型记忆填补

开发者会把你的工具和其他运行时、框架一起用，而文档常常写到工具边界为止。要让 Node.js 应用走 Dev Proxy，fetch 需要一个只有较新 Node 版本才支持的开关。材料中 5 次运行都从记忆里知道这一点：需要 NODE_USE_ENV_PROXY，要求 Node 22.21.0+ 或 24.0+。这次全对，但没有一次是从 Dev Proxy 文档里读到的。

风险在于不可预测：模型知道就成功，你不会收到任何信号；模型不知道或记的是旧版本，代码看起来正确，实际悄悄没生效。轨迹里的表现是「陈述了一个事实，但没引用任何来源」。

修复方向：列出开发者最常搭配的运行时与框架，为每个补一段接入说明；对没覆盖到的，跑一次任务，看 agent 自己填了什么。

5. 默认配置服务首次运行，不服务具体任务

默认配置和脚手架通常是为了让第一次运行跑通：几分钟内看到产品能做什么。这个目标没错，但面对具体任务时往往是障碍。Dev Proxy 的默认配置会在示例 API 上注入随机错误，用来演示流量确实经过了代理；要录真实流量，它就是干扰。材料中 agent 立刻判断要避开，自建配置，结果新建出来是空的，三次运行为同一目标选了三套不同插件。

修复方向：保留让首次运行成功的默认值，同时在旁边为每个常见任务提供一个 preset，并在 CLI help 里列出来，因为 agent 会较早读到 help。

6. agent 信任搜索结果，而搜索给的是快照

agent 经常通过搜索引擎读你的说明，索引里存的却是快照。上月更新的页面可能仍以旧内容排在前面，翻译页和你为 agent 发布的 skill 文件同理。agent 分不清旧快照和当前页面。材料中，Dev Proxy 自 v3.3.1 起 API 要求 token，而一次运行的搜索返回了两条在变更前索引的结果：一条是 6 月抓取的乌克兰语 API 参考翻译，另一条是自家 agent skill 文件，该文件在运行前六周已加入鉴权。两条都展示了不带 token 的调用：

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

现在这样调用会返回 401。那次运行最后做对了，只因为它此前读过 CLI help，而 help 随安装版本一起发布，不会过期。该片段同样来自材料，未在本文环境执行。

修复方向：用 agent 会输入的关键词（例如「产品名 API authentication」）实际搜一遍，检查结果，包括翻译页和自家 skill，描述的是不是当前版本。你无法刷新别人的索引，但可以在每页顶部写明版本要求，让它进入搜索摘要，告诉 agent 这份快照对应哪个版本。

7. help 没写的默认值，agent 当作关闭

agent 从 help 文本学 CLI，并且按字面理解。一个选项如果读起来像「打开某个开关」，agent 会假定它默认关闭，不传就等于关闭；而如果它实际默认开启，agent 永远不会去传关闭值，因为没人告诉它要传。对多数选项，代价只是行为与预期不符；如果这个默认值会影响工具之外的东西，脚本就带上了 agent 不知道的副作用，而任务照样成功，评分也照样发现不了。

材料摘要提到，5 个脚本里有 3 个会静默改道 CI runner 的网络流量。正文在该模式处被截断，具体是哪个默认项、如何设置，本次材料未提供，属于待核实部分。可迁移的检查方法是：找出 help 里所有「像开关」的选项，凡是默认开启且影响工具外部（系统代理、网络路由、全局配置）的，都把默认值和关闭方式写清楚。

把轨迹变成修复清单#

以下流程是根据上述模式整理的建议，不是材料给出的官方方法：

1. 固定任务，多次运行。材料用的是 5 次，足以看出重复，不足以下统计结论。
2. 记录过程成本。每次运行的请求数、token、总步数，与任务是否成功分开记。
3. 按模式标注每一步。404 猜测、报错后试值、重复出现的绕过代码、无来源的事实陈述、绕开默认配置、旧快照、未声明的默认值。
4. 区分归因。是产品缺功能（没有列表命令、没有完成信号），还是 help 文本不完整、文档缺集成说明、索引过期、模型知识不足。归因不同，修法完全不同。
5. 修复后重跑同一任务。比较请求数是否下降，以及同一模式是否还出现。

边界#

这些观察来自单一产品（Dev Proxy）、单一配置（GitHub Copilot Chat + Claude Sonnet 5.5，无扩展）的 5 次运行，材料未给出评估的时间窗。它适合用来建立「该看什么」的清单，不适合引用为比例或普遍规律。分数与轨迹不一致也不说明分数无用：一个判断结果，一个解释过程，分工不同。

真正可复用的结论只有一句：当同一个笨拙步骤在多次运行的轨迹里反复出现，那不是模型的问题，而是你的产品或文档少给了一步。