给前端 Agent 工具调用做离线回放时，我会先把 MSW 场景表建起来

最近给一个前端 Agent 工作台补工具调用面板时，我遇到一个很实际的问题：后端工具服务还在频繁调整，前端却要验证成功、超时、鉴权失败、参数缺失和流式返回。只靠真实接口联调，页面状态经常被环境波动带偏。后来我把工具调用抽成一组 MSW 场景表，让本地开发、组件预览和 CI 测试都能按同一份输入回放。

前端 Agent 工具调用从 fixture、MSW handler、场景切换到回放报告的流程图

原创示意图：把工具调用请求、fixture contract、MSW handler、浏览器回放和 Node 测试串成一条可复现链路。来源：Codex image generation

问题背景

这个工作台里，Agent 会把一次任务拆成搜索知识库、读取文件、生成摘要、写入草稿等多个工具调用。前端要展示 pending、running、retrying、blocked、done，还要保留每一步的 request、response、耗时和错误摘要。早期直接连开发环境后端，问题很快暴露：后端 fixture 改了，前端截图回归跟着变；某个工具限流，整个页面卡在等待；新同事想复现异常态，还得找一组刚好失败的数据。

MSW 的浏览器集成文档说明，它会在浏览器里注册 Service Worker，在网络层负责请求拦截。MDN 对 Service Worker 的解释也贴近这个场景：它位于 Web 应用、浏览器和网络之间，可以拦截请求并根据网络状态采取动作。这个能力让我把前端调试入口从真实环境状态里抽出来，改成可声明、可切换、可提交到仓库的场景。

踩坑和关键难点

第一个坑是场景粒度。工具调用如果只按接口路径 mock，很快会长出一堆散乱 handler。Agent 页面真正关心的是一次任务里的步骤顺序、每一步状态和错误类型，所以我把 fixture 命名成 tool.search.success、tool.file.timeout、tool.write.blocked 这类业务场景，再映射到具体 HTTP 响应。

第二个坑是浏览器和测试环境要共用同一套数据。MSW 的 Node.js 集成文档写到，在 Node.js 中它会 patch http、https 等原生请求模块，并通过 setupServer 控制当前进程里的 API mocking。这样浏览器里用 setupWorker，Vitest 或脚本测试里用 setupServer，handler 和 fixture 就能复用。

第三个坑是回放要能解释失败。MSW 的处理请求文档支持返回 mock response，也可以 passthrough 原请求，甚至只做观察不返回响应。我会把命中的 handler、场景名、入参摘要和 fixture 版本写进前端调试面板，避免页面失败后还要猜命中了哪条 mock。

解决思路

我把目录拆成三层：fixtures 存纯 JSON，handlers 负责把请求转成响应，scenarios 负责按 URL 参数或测试配置启用一组 overrides。MSW 的动态场景文档提醒，运行时可以按 query parameter 切换不同 mock scenarios，并且 handler 顺序会影响解析优先级。异常场景要放在基础 handler 前面，避免被通用成功响应提前命中。

落地时，我会让页面地址带上 ?scenario=tool-timeout，本地启动后先等待 worker.start() 完成，再渲染应用。MSW 浏览器集成文档也提醒，Service Worker 注册是异步操作，没等待完成可能和首屏请求产生竞态。CI 里则在测试 setup 阶段执行 server.listen()，每个用例后 server.resetHandlers()，最后 server.close()，避免临时 override 污染后续测试。

关键步骤

第一步是给每个工具调用定义稳定 contract：toolName、callId、inputHash、status、durationMs、errorCode、displayMessage。第二步是把真实联调里出现过的异常沉淀成 fixture，敏感字段脱敏，只保留能解释 UI 状态的字段。第三步是让调试面板显示当前 scenario、命中的 handler 和 fixture 版本。第四步是在 CI 里固定跑三类场景：全成功、单工具失败、重试后成功。