企业官网建设流程全解析

如何用 MIDSCENE_RECORD_MODEL_CALL 记录 Midscene 的模型请求与响应

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

当你在用 Midscene 跑 GUI Agent 任务时，想看清每一步到底向大模型发了什么请求、模型返回了什么内容（包括流式 Chunk），可以启用模型调用记录功能：设置环境变量MIDSCENE_RECORD_MODEL_CALL=true，Midscene 会把模型请求、响应和流式 Chunk 写入本地 JSONL 文件。该功能属于模型调试与可观测性中"记录模型调用"的能力，适用于排查定位不准、规划跑偏、页面理解不稳定等问题。

前提条件

• 运行环境是Node.js 或 Electron。本地文件写入只有这两种环境支持，浏览器和 Worker 中不会写入本地文件。
• 模型已按 模型配置 文档配置好（MIDSCENE_MODEL_BASE_URL、MIDSCENE_MODEL_API_KEY、MIDSCENE_MODEL_NAME、MIDSCENE_MODEL_FAMILY等），且任务能正常发起模型调用。
• 记录文件默认写入当前工作目录下的midscene_run目录，因此确认你对该目录有写权限。

启用记录并运行任务

在启动 Midscene 之前设置环境变量：

export MIDSCENE_RECORD_MODEL_CALL=true

之后再启动你的脚本、CLI 或 Electron 应用。记录按进程生效，设置后再启进程才会生效。

启用后，每个进程会在运行目录的model-requests子目录下生成一个文件：

midscene_run/model-requests/<启动时间>-<pid>.jsonl

其中<启动时间>是进程启动时刻、<pid>是进程 ID，文件名由运行时自动拼接（见 model-call-recorder.ts）。每行是一个独立的 JSON 事件，文件随任务运行持续追加。

记录文件里有什么

每个事件的type为以下四种之一：

• request：发出的模型请求；
• chunk：流式响应中的一个 Chunk；
• response：完整响应；
• error：调用过程中的错误。

除type外，每个事件还包含executionId，用于把同一个 execution ID 下的调用及其重试关联起来（例如一次aiAct调用产生的多轮请求）。对于 HTTP 模型请求，这个 ID 同时通过x-midscene-execution-id请求头发送给模型服务。不属于报告 execution 的调用（例如连接检查）会使用带unscoped-前缀的自动生成 ID。

文件内容的覆盖范围如下：

• 记录：请求 Body（包括自定义extraBody）、响应 Header 和 Body、流式响应、可能以 Base64 编码的截图；
• 不记录：请求 Header。

使用 Codex App Server 时，记录还会包含可获取的协议元数据。

验证记录是否生效

运行一次任务后做两步检查：

1. 查看文件是否生成：

ls midscene_run/model-requests/

能看到形如2026-09-14T09-30-00-000Z-12345.jsonl的文件即说明写入成功；目录不存在则说明记录未生效，先确认运行环境是 Node.js 或 Electron，且环境变量在进程启动前已设置。

2. 逐行检查事件结构：

head -n 3 midscene_run/model-requests/<你的文件>.jsonl

每行应为合法 JSON，包含timestamp和type（request、chunk、response、error之一）等字段。可以按executionId过滤同一个执行的请求与重试，核对请求体与响应内容是否符合预期。

使用限制与安全注意事项

文档对这份记录文件给出了明确的约束，使用前应了解：

• 文件包含请求体、响应体和可能 Base64 编码的截图，可能敏感且体积较大。文档建议仅在排查问题时启用记录，使用完成后妥善保管或删除文件。
• 记录格式不保证跨版本兼容，不要依赖字段结构做跨版本解析。
• 不要把模型调用记录提交到源码仓库；日志和 Trace 分享前先检查内容，因为它们可能包含模型输入、输出或截图。
• 环境变量说明见 model-config.mdx 的"模型调用记录"配置表：设置为true时开启写入本地 JSONL 文件；源码实现中1同样视为开启（见 isModelCallRecordingEnabled）。

排查效果不理想时的配合手段

如果目的是进一步定位模型连接或兼容性问题，文档给出了两条相邻路径，可与记录文件配合使用：

• 设置DEBUG选择器：DEBUG=midscene:ai:profile:stats打印模型延迟和 Token 使用量，DEBUG=midscene:ai:call打印 AI 响应详情，DEBUG=midscene:*打印全部 Midscene Debug 日志。
• 用npx midscene model verify（或项目未安装@midscene/cli时用npx @midscene/cli@latest model verify）检查模型连接与 Midscene 兼容性；该命令读取当前工作目录下的.env文件，.env中的变量会覆盖已有 Shell 环境变量。这类连接检查产生的调用不属于报告 execution，在记录文件中会以unscoped-前缀的executionId出现。

完成排查、确认问题原因后，关闭该环境变量并清理midscene_run/model-requests下的记录文件，即可结束本次调试。

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene