agent-browser 0.32.3 把 HAR 变成客户端素材

北京时间 7 月 20 日凌晨发布的 agent-browser 0.32.3，把两项能力装进同一个版本：HAR 默认保存可离线分析的文本响应体，项目同时提供把流量转成客户端的正式 Skill。对反复自动化同一网站的 Agent 来说，工作流由“每次都重走页面”转向“首次用浏览器发现流程，之后尽量复用直接请求”。

确定事实有清楚的时间锚点。GitHub PR #1578 于 2026 年 7 月 19 日 16:38:57Z 合并，合并提交是 ad97a049231322a6583cbee311958a8999b3f34f；版本 0.32.3 随后于 17:03:44Z 发布。Release 的两项 New Features 分别是 HAR response body capture，以及 derive-client Skill。

边界也同样清楚：agent-browser network har start 与 network har stop 在父提交的 README 中已经存在。此次不是“新增 HAR 录制”，而是让录制可带响应体、为 CLI 与 MCP 增加 content 模式，并加入从这些请求与响应派生客户端的方法说明。

对开发者的直接影响，是一次真实交互可以同时留下请求参数、响应结构与认证线索，浏览器关闭后仍能研究端点。但这并不等于网站提供了稳定公开 API，更不意味着 HAR 可以进入代码仓库；Cookie、Bearer Token、POST 数据和业务响应都可能成为新的泄露面。

从“能导出 HAR”到“HAR 足以离线研究”

过去的 start 和 stop 已经能围绕一段浏览器操作导出 HAR。PR #1578 改变的是 HAR 里的 response.content：默认 text 模式会在响应加载完成后，通过 Chrome DevTools Protocol 的 Network.getResponseBody 取回文本类响应，并写入 content.text。实现选择在 loading finished 后及时抓取，而不是等到 stop 时才取，原因是浏览器导航后可能清理响应缓冲。

默认文本类型不是“所有看起来可读的文件”这种模糊判断，而是按 MIME 类型筛选。代码覆盖 text/*、JSON、XML、HTML、JavaScript、表单、GraphQL，以及带 +json、+xml 后缀的类型；SVG 也会因 image/svg+xml 的后缀被纳入。图片、视频和 application/octet-stream 在默认模式下不会嵌入。

三种模式的差别如下：

启动方式	响应体行为	适合场景	主要代价
har start 或 --content text	默认嵌入文本类响应体	分析 JSON API、HTML 与脚本返回	HAR 会包含更多业务数据与隐私字段
har start --content all	尝试嵌入全部响应体，二进制以 base64 保存	必须研究文件或二进制协议	文件更大，敏感内容范围更广
har start --content none	不嵌入响应体，只保留大小与 MIME 等元数据	只看请求拓扑或最小化数据留存	无法离线读取真实响应结构

项目 Skill 和网络文档都写明单个响应体上限是 2 MB。实现代码进一步设置了每次录制 64 MB 的嵌入总预算。这里的“上限”不是截断后仍写入：实现只有在响应体不为空、长度不超过单体上限、累计值也不越过总预算时才保存。因此，HAR 中没有 content.text 不一定代表服务器没有响应，也可能是 MIME 未命中、浏览器未能及时取回、单体超限或会话预算已用尽。

二进制模式同样需要精确描述。all 会接受二进制响应；CDP 若返回 base64Encoded: true，HAR 才在 content 中增加 encoding: "base64"。这不是把所有文本都重新编码，也不是解除 2 MB 限制。默认 text 仍是产品刻意选择的中间点：足以分析常见站点 API，又避免自动吞入每张图片和每段视频。

derive-client 如何把录制变成客户端

新增 Skill 把流程拆成五步：Record、Identify、Extract、Generate、Verify。第一步仍由浏览器完成，因为真实页面最擅长处理登录、交互、跳转和动态参数；后四步则把浏览器留下的网络事实，压缩成可复用的 HTTP 调用。

录制阶段要求覆盖客户端准备支持的每个流程，并让同一流程至少以不同输入执行两次。例如搜索两个关键词、打开两个详情页。这样做不是为了增加样本量本身，而是通过对比 URL、查询串和 POST body，识别哪些字段是稳定路径，哪些字段才是可参数化输入。只录一遍，Agent 很容易把某个商品 ID、分页游标或实验参数误认为固定常量。

识别阶段先从噪声中挑出真正的业务端点。Skill 建议按 JSON MIME、请求方法、状态码和域名检查 HAR，同时排除 /collect、/track、/beacon 等遥测，以及分析、报错和静态资源域名。这里没有承诺全自动识别；“第一方、JSON、与刚才动作时间相关”只是高质量启发式，仍需把请求和用户动作逐一对应。

抽取阶段才使用本次新增最关键的材料：.response.content.text。有了真实响应体，Agent 可以观察字段是否可选、列表如何分页、错误结构是什么，再据此生成类型。与此同时，请求 headers、query、POST body 和 Cookie 暴露了认证与参数形态。Skill 特别要求比较多个端点的 header，只重放真正必要的 authorization、cookie、x-csrf-token、x-api-key 或站点自定义字段，而不是把浏览器发出的全部 header 原样固化。

生成阶段倡导“一个录制流程对应一个函数”，例如 search(query) 或 getItem(id)，并把分页、排序、筛选做成参数。认证材料应从文件或环境变量加载；过期时，客户端要明确提示重新通过浏览器登录并导出 Cookie，而不是把一次录制中的值写死在源码。

最后一步 Verify 决定了这是不是工程资产。Skill 要求每个生成函数都真实调用一次，并把在线响应形态与 HAR 样本比较。也就是说，响应体嵌入让“生成”更有根据，却没有取消验证。一次录制只能证明某组输入在某个时间成功过，不能替代接口契约、错误处理和回归测试。

凭证：登录前录还是登录后录

Skill 建议需要登录时先完成登录，再启动 HAR，目的是避免用户名、密码、一次性验证码和登录交换过程不必要地进入录制。这个建议有效，但不能被误读成“登录后的 HAR 不含凭证”。已认证页面发出的每个请求仍可能携带会话 Cookie、Bearer Token、API key、设备标识或租户信息，POST body 与响应体也可能含个人数据。

更稳妥的边界是把 HAR 当成短期密钥材料，而不是普通调试日志：

• 录制前缩小流程，只采集生成客户端真正需要的页面和动作。
• 默认优先 text；若只需请求拓扑，改用 none，不要为了完整而选择 all。
• HAR、Cookie 导出文件和生成过程的临时日志都不进入版本控制。
• 生成代码只读取运行时凭证，不复制录制时的 Cookie、Token 或用户数据。
• 验证完成后删除原始敏感文件；若确需保留，使用访问控制和加密存储。

项目目前给出了“不要硬编码”“不要提交”“完成后删除”的操作原则，但 Release 与 Skill 没有宣布自动脱敏器。用户不应假设工具会替换所有 authorization、set-cookie、查询参数、POST 字段或响应中的隐私信息。响应体默认落盘提高了离线分析价值，也同时把安全审查从可选项变成必要步骤。

CSRF 让写操作不能机械重放

读接口经常只依赖会话 Cookie；写接口则可能要求每会话、每页面甚至每表单生成的 CSRF token。Skill 把 403/419 明确列为典型症状，并给出两类处理：先调用 token 端点刷新，再执行写请求；如果无法稳定建模，就让该步骤继续由浏览器完成。

这一区别很重要。HAR 里看见 x-csrf-token，只能证明某次请求使用过这个值，不能证明它是长期 API key。把录制值硬编码进客户端，可能很快失效；更坏的情况是，生成器错误地绕过来源检查、确认页面或风控步骤，把原本需要用户意图确认的写操作变成无提示调用。

因此，派生客户端应把读和写分开评估。查询、列表、详情等幂等流程更适合先转成直连；下单、发送、删除、修改权限等写操作，则要确认 token 来源、有效期、Referer 与 Origin 要求、重试语义以及用户确认机制。不能稳定重建这些条件时，保留浏览器回退不是失败，而是正确的安全边界。

内部 API 的价值与维护成本

derive-client 的描述明确使用“网站内部 API”，而不是“公开 API”。这意味着接口通常没有对外版本承诺，也可能随前端部署、A/B 测试、地区、账号层级和风控策略变化。Skill 自己列出了几种失效信号：请求先成功后失败，可能是签名参数或短期参数；响应形态与 HAR 不同，可能是实验或地区差异；Cookie 过期则需要重新登录。

响应体样本也不是完整 schema。两次搜索能帮助识别 query 参数，却未必覆盖空结果、权限错误、分页末尾、限流、字段缺失和不同账号返回。生成类型时应把仅在部分样本出现的字段视为可选，并保留原始响应检查。若客户端用于生产任务，还需要契约测试、速率限制、退避与错误分类，而不是只要首次 200 就宣布完成。

服务条款是另一条边界。浏览器能访问某个请求，不等于站点允许批量直连、绕过页面流程或自动执行。Skill 要求尊重条款和 rate limit，并为批量抓取增加延迟。对企业使用者而言，还应确认数据处理、账号共享、审计记录和第三方接口政策；技术上可重放，不自动等于合规上可部署。

接下来要验证什么

第一，看项目是否加入自动凭证扫描和可配置脱敏。默认嵌入文本响应体后，只提醒“把 HAR 当秘密”仍依赖操作者纪律；如果能在保存、生成和清理三个阶段识别 Cookie、Bearer Token、CSRF、POST 敏感字段，工作流才更适合团队共享。

第二，看派生客户端是否能识别漂移。理想状态不是接口变化后静默报错，而是把最新调用与保存的 HAR 结构比较，指出 URL、必要 header、请求 schema 或响应字段发生了什么变化，并触发重新录制。

第三，看浏览器回退是否成为明确能力。短期签名、动态 CSRF、设备校验和高风险写操作不适合强行直连；一个可靠系统应允许函数级选择 HTTP 或浏览器，并在 401、403、419 或结构漂移时安全降级。

第四，看验证能否超越单个成功样本。至少要覆盖两组输入、空结果、分页、过期凭证与错误状态；涉及写操作时，还要验证幂等性和用户确认。只有这些测试成立，“从 HAR 派生客户端”才从演示技巧变成可维护的 Agent 基础设施。