从录制的会话中派生 API 客户端
第一次访问时使用浏览器是正确的工具，但第一百次访问时它就成了错误工具。本技能在您使用网站时录制其网络流量一次，然后将捕获的请求转化为一个独立的客户端（脚本、CLI 或库），直接与网站的内部 API 通信。
录制内容本身已包含一切所需：agent-browser 默认将文本响应体（JSON/HTML/JS）嵌入 HAR 文件中，因此即使在关闭浏览器后，也可以离线分析端点结构。
工作流程
1. 录制 启动 HAR 捕获，在浏览器中执行客户端所需的所有流程
2. 识别 从噪声中找出真正的 API 端点
3. 提取 获取请求结构、响应模式以及认证材料
4. 生成 编写客户端，每个流程对应一个函数
5. 验证 在完成前对每个端点进行真实调用
1. 录制
agent-browser network har start # 默认嵌入文本响应体
# ... 驱动浏览器：搜索、打开详情页、分页等 ...
agent-browser network har stop /tmp/site.har
- 对客户端应支持的每个流程都进行操作，并且每个流程至少执行两次，使用不同的输入（两个搜索词、两个详情页）。比较记录的 URL 可以揭示哪些部分是参数。
- 如果网站需要登录，在启动 HAR 录制之前登录，以免不必要的凭据落入录制文件中。会话 cookie 将在第 3 步单独导出。
--content all同时嵌入二进制体（base64）；--content none禁用嵌入。每个响应体上限为 2 MB。
会话打开时，agent-browser network requests 和 network request <id> 也可以交互式显示相同数据——但只有 HAR 能在页面导航和浏览器关闭后保留下来，因此对于多页面操作，优先使用 HAR。
2. 识别端点
使用 jq 查询 HAR：
# 所有 JSON API 调用：方法、URL、状态
jq -r '.log.entries[]
| select(.response.content.mimeType | test("json"))
| "\(.request.method) \(.response.status) \(.request.url)"' /tmp/site.har
忽略分析和基础设施噪声：遥测端点（/collect、/track、/beacon、/log）、第三方域名（google-analytics、segment、sentry、datadog、intercom、hotjar）以及静态资源。真正的 API 通常在第一方域内、返回 JSON、并且与你执行的操作相关。
3. 提取结构和认证
# 查看一个端点的完整详情：请求头、POST 体、响应体
jq '.log.entries[] | select(.request.url | test("api/search"))
| {request: {method: .request.method, headers: .request.headers,
postData: .request.postData.text},
response: .response.content.text}' /tmp/site.har
- 响应结构：读取
.response.content.text——这是真实的负载，从中推导类型。 - 认证：比较各个端点的请求头。查找
authorization、cookie、x-csrf-token、x-api-key以及特定的x-*头。仅复制那些必要的——在第 5 步通过删除来测试。 - Cookie：使用
agent-browser cookies get --json > cookies.json导出当前会话，供客户端在运行时加载。切勿将 cookie 值硬编码到生成的源代码中。
4. 生成客户端
- 每个录制的流程对应一个函数（如
search(query)、getItem(id)），根据观察到的响应体进行类型定义。 - 认证材料（cookie、bearer token）从文件或环境变量加载，并在过期时给出清晰的错误信息，提示用户重新运行浏览器登录。
- 重现 API 实际需要的请求头——某些网站如果没有匹配的
user-agent、referer或x-requested-with会返回 403。 - 将录制查询字符串中出现过的分页、排序和过滤参数保留为函数选项。
5. 验证
针对实时 API 调用每个生成的函数，并将响应形状与录制内容进行比较。常见失败：
| 症状 | 原因 | 修复 |
|---|---|---|
| 401/403 | 会话过期或缺失 | 通过 agent-browser 重新登录，重新导出 cookie |
| 403/419 (写入) | CSRF token 是按会话或表单生成的 | 先获取 token 端点，或将该流程保留为浏览器驱动 |
| 能用后失效 | 签名/过期请求参数 | 对该步骤改用浏览器；其他部分仍可派生 |
| 响应形状与 HAR 不同 | A/B 测试或与地域相关的响应 | 重新录制，将差异视为可选字段 |
注意事项
- 内部 API 没有版本号且会随时变更——保留 HAR 文件以便日后重新派生客户端。
- 尊重网站的条款、服务及速率限制；批量拉取时添加延迟。
- HAR 文件包含实时会话凭据（cookie、token、POST 体）。请像对待秘密一样对待它们：不要纳入版本控制，使用完毕后删除。