• 简体中文

      • 常见问题 FAQ

      会有哪些信息发送到 AI 模型？

      Midscene 会发送页面截图到 AI 模型。在某些场景下，例如调用 aiAsk 或 aiQuery 时传入 domIncluded: true，页面的 DOM 信息也会被发送。

      如果你担心数据隐私问题，请参阅 数据隐私。

      如何配置 midscene_run 目录？

      Midscene 会将运行产物（报告、日志、缓存等）保存在 midscene_run 目录下。默认情况下，该目录会创建在当前工作目录下。

      你可以通过环境变量 MIDSCENE_RUN_DIR 来自定义该目录的位置，支持相对路径或绝对路径：

      # 使用相对路径
export MIDSCENE_RUN_DIR="./my_custom_dir"

# 使用绝对路径
export MIDSCENE_RUN_DIR="/tmp/midscene_output"

      该目录包含以下子目录：

      • report/ - 测试报告文件（HTML 格式）
      • log/ - 调试日志文件
      • cache/ - 缓存文件（详见 缓存）

      更多配置选项请参阅 模型配置。

      如何提升运行效率？

      有几种方法可以提高运行效率：

      1. 使用即时操作接口，如 agent.aiTap('Login Button') 代替 agent.ai('Click Login Button')。
      2. 尽量使用较低的分辨率，降低输入 token 成本。
      3. 更换更快的模型服务。
      4. 使用缓存来加速调试过程。更多详情请参阅 缓存。

      浏览器界面持续闪动

      在本地可视化界面中遇到持续闪烁，通常是因为 viewport 的 deviceScaleFactor 与系统/浏览器的像素比不匹配（常见于高分辨率或 Retina 屏幕）。

      该闪动不会影响 Midscene 的截图或自动化运行，但会影响本地预览体验。解决方法：将 deviceScaleFactor 设置为与浏览器的 window.devicePixelRatio 一致，或使用 Puppeteer 的自动适配功能。

      // Puppeteer：将 deviceScaleFactor 设为 0 可自动使用设备像素比
await page.setViewport({
  deviceScaleFactor: 0,
});

// Playwright：不支持像 Puppeteer 一样使用 0 表示自动适配
const page = await browser.newPage({
  deviceScaleFactor: 2, // 请把这里的数字 2 替换为你的 window.devicePixelRatio
})

      如果不确定浏览器的像素比，可在任意页面按下 F12 打开控制台，输入 window.devicePixelRatio 查看；或在 Chrome 地址栏粘贴下面内容并回车以弹窗显示当前值：

      data:text/html,<script>alert(`deviceScaleFactor of your browser: ${devicePixelRatio}`)</script>

      如何通过链接控制报告中播放器的默认回放样式？

      在报告页面的链接后添加查询参数即可覆盖 Focus on cursor 和 Show element markers 开关的默认值，决定是否在报告中聚焦鼠标位置和元素标记。使用 focusOnCursor 和 showElementMarkers，参数值支持 true、false、1 或 0，例如：...?focusOnCursor=false&showElementMarkers=true。

      自定义网络超时

      当在网页上执行某个操作后，Midscene 会自动等待网络空闲。这是为了确保自动化过程的稳定性。如果等待超时，不会发生任何事情。

      默认的超时时间配置如下：

      1. 如果是页面跳转，则等待页面加载完成，默认超时时间为 5000ms
      2. 如果是点击、输入等操作，则等待网络空闲，默认超时时间为 2000ms

      当然，你可以通过配置参数修改默认超时时间，或者关闭这个功能：

      • 使用 Agent 上的 waitForNetworkIdleTimeout 和 waitForNavigationTimeout 参数
      • 使用 Yaml 脚本和 PlaywrightAiFixture 中的 waitForNetworkIdle 参数

      在 Chrome 插件中使用 Ollama 模型出现 403 错误

      需要设置环境变量 OLLAMA_ORIGINS="*"，以允许 Chrome 插件访问 Ollama 模型。

      元素定位出现偏移

      如果在使用 Midscene 时遇到元素定位不准确的问题，可以按照以下步骤排查和解决：

      1. 升级到最新版本

      确保你使用的是最新版本的 Midscene，新版本通常包含定位准确性的优化和改进。

      # Web 自动化
npm install @midscene/web@latest
# iOS 自动化
npm install @midscene/ios@latest
# CLI 工具
npm install @midscene/cli@latest
# 或者其他和你平台对应的 package

      2. 使用更好的视觉模型

      Midscene 的元素定位能力依赖于 AI 模型的视觉理解能力，所以请务必选择支持视觉能力的模型。

      通常来说新版本、参数大的模型会比老版本、参数小的模型表现更好。比如 Qwen3-VL 会好于 Qwen2.5-VL，它的 plus 版本会好于 flash 版本。

      更多模型选择建议请参考 模型策略。

      3. 检查 Model Family 配置

      确认你的模型配置中 MIDSCENE_MODEL_FAMILY 参数设置是否正确，MIDSCENE_MODEL_FAMILY 配置错误会影响 Midscene 对模型的适配逻辑。详见 模型配置。

      4. 分析定位偏移的原因

      定位偏移通常有两种情况：

      情况一：模型无法理解语义

      • 表现：定位结果随机落在不相关的元素上，每次执行结果差异较大。
      • 原因：模型可能无法理解图标按钮背后的语义。以 aiTap('个人中心') 为例，这是一个功能性描述，模型可能并不了解个人中心图标具体的样式；而 aiTap('人形头像 icon') 是一个视觉性的描述，模型可以根据其视觉特征完成元素定位。
      • 解决方法：优化提示词，结合视觉特征和位置信息来描述元素。 
        // ❌ 仅使用功能性描述
await agent.aiTap('个人中心');

// ✅ 使用视觉性描述
await agent.aiTap('人形头像 icon');

// ✅ 结合视觉特征和位置信息
await agent.aiTap('页面右上角的人形头像图标');

      情况二：模型识别准确但定位有偏差

      • 表现：定位结果落在目标元素附近，但有若干像素的偏移。
      • 解决方法：开启 deepThink 会对定位效果有明显提升。 
        await agent.aiTap('登录按钮', {
  deepThink: true
});

      更多关于 deepThink 的说明，请参阅 API 文档。

      豆包手机是否使用了 Midscene 作为底层方案？

      没有。