Midscene 的缓存策略 read-write、read-only 与 write-only 怎么选【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene如果你的 Midscene 自动化脚本里包含重复执行的规划类操作ai、aiAct或 Web 元素定位操作aiLocate、aiTap每次运行都要重新调用 AI 模型执行时间和模型开销都会居高不下。Midscene 的缓存机制可以让你在相同任务指令、相似页面环境下复用已缓存的执行计划和元素 XPath而cache选项中的strategy配置了三种行为read-write、read-only、write-only。本文按文档给出的适用条件说明这三种策略各自解决什么问题、如何配置以及如何验证缓存是否命中。缓存什么、存在哪里先明确缓存覆盖的范围这决定了三种策略的讨论前提来源缓存文档任务指令缓存对规划类操作如ai、aiAct以 prompt 指令为缓存键存储 AI 返回的执行计划可用于各类自动化任务。元素定位缓存仅 Web对定位类操作如aiLocate、aiTap以定位 prompt 为缓存键存储元素 XPath下次执行时先验证 XPath 是否仍然有效。失效机制缓存失效时自动回退到 AI 模型重新分析。规划缓存回退如果缓存的aiAct规划运行时失败例如偶现弹窗本次没有出现Midscene 本次运行回退到正常 AI 规划并清空这条过期缓存的 flow即使回退成功也不会把回退生成的 flow 写回原 prompt 的规划缓存下一次运行相同 prompt 时会重新生成完整的规划缓存。查询结果永不缓存aiBoolean、aiQuery、aiAssert的查询结果不会被缓存。缓存内容保存到./midscene_run/cache目录下扩展名为.cache.yaml。文档给出的一个效果示例缓存命中后执行耗时从 51 秒降低到 28 秒文档示例具体数值随你的脚本和页面变化另外注意缓存是加速手段不是替代 AI 服务。当页面 DOM 结构变化导致缓存失效时Midscene 仍会调用 AI 重新执行任务。三种策略的适用条件strategy的默认值是read-write不配置cache选项时缓存处于禁用状态等效于cache: false每次都调用 AI 模型适合需要实时结果或调试时使用。策略行为文档给出的适用场景read-write自动读取已有缓存执行过程中自动更新缓存文件默认策略日常开发与常规执行write-only只写不读每次执行都调用 AI 模型并把结果写入缓存文件初次建立缓存或更新缓存read-only只读缓存不自动写文件需手动调用agent.flushCache()生产环境确保缓存一致性选择思路由此而来第一次为一个脚本建立缓存或缓存内容需要整体刷新时用write-only——它不读旧缓存保证全部结果由本次 AI 调用生成并写入文件日常开发执行用read-write默认——命中则复用未命中则调用 AI 并自动更新文件无需额外代码生产环境中如果希望只消费、不修改已入库的缓存文件用read-only配合显式的flushCache()决定何时写文件。配置方式直接创建 AgentJavaScript三种策略在构造 Agent 时通过cache选项配置。下面的my-cache-id是文档示例用的缓存 ID需要替换为你自己的唯一标识// read-write默认两种写法等价 const agent new PuppeteerAgent(page, { cache: { id: my-cache-id }, }); // 显式指定 strategy const agent new PuppeteerAgent(page, { cache: { strategy: read-write, id: my-cache-id }, }); // read-only只读缓存写文件需手动触发 const agent new PuppeteerAgent(page, { cache: { strategy: read-only, id: my-cache-id }, }); // 手动写入缓存 await agent.flushCache(); // write-only只写不读每次都会调用 AI 模型 const agent new PuppeteerAgent(page, { cache: { strategy: write-only, id: my-cache-id }, });YAML 脚本模式YAML 中在agent下配置cache字段说明见 YAML 脚本文档agent: cache: id: my-cache-test # 必填 strategy: read-write # 可选可选值read-only | read-write | write-onlyYAML 模式还支持cache: true自动使用文件名作为 cache ID。Playwright AI Fixture使用midscene/web/playwright的PlaywrightAiFixture时把同样的cache选项传给 fixtureexport const test base.extendPlayWrightAiFixtureType( PlaywrightAiFixture({ cache: true, // 或 cache: { id: my-fixture-cache } }), );read-only模式下需要在测试步骤完成后手动持久化缓存通过 fixture 提供的agentForPage获取底层 agent 再调用flushCache()。文档示例只在测试通过时 flushtest.afterEach(async ({ page, agentForPage }, testInfo) { // Only flush cache if the test passed if (testInfo.status passed) { console.log(Test passed, flushing Midscene cache...); const agent await agentForPage(page); await agent.flushCache(); } else { console.log(Test ${testInfo.status}, skipping Midscene cache flush.); } });兼容方式不推荐旧方式是通过环境变量MIDSCENE_CACHE1配合cacheId选项行为等同于 read-write 模式const agent new PuppeteerAgent(originPage, { cacheId: puppeteer-swag-sab });MIDSCENE_CACHE1 tsx demo.ts新代码直接使用cache选项即可。一条典型的组合路径把文档中各策略的适用说明串起来一个连续的操作路径是建缓存先用write-only或read-write完整跑一遍脚本让 AI 规划结果和 XPath 写入./midscene_run/cache下的.cache.yaml文件。日常执行切换为默认的read-write命中则复用未命中自动回退 AI 并更新缓存文件。生产/CI 消费切换为read-only读取入库的缓存只有在你确认要更新缓存文件时才显式调用agent.flushCache()写文件。注意第 3 步的前提CI 环境不会自动拿到本地生成的缓存文件文档明确指出需要在 CI 中将缓存文件提交到仓库并再次检查缓存命中条件否则缓存会一直不命中。验证缓存是否命中与调试文档给出的验证方式查看报告文件缓存命中时会看到cache提示并且该步执行时间明显降低。调试日志设置环境变量DEBUGmidscene:cache:*可以获得缓存相关的调试日志。检查缓存文件./midscene_run/cache目录下是否生成了对应的.cache.yaml文件没有生成时按 FAQ 逐项确认——直接创建 Agent 是否在构造函数里设置了cache: { id: ... }Fixture 是否设置了cache: true或cache: { id: ... }YAML 是否设置了agent.cache.idread-only 模式是否调用了flushCache()。缓存清理与单 API 关闭缓存缓存文件会变旧Midscene 提供完全手动的清理能力显式调用agent.flushCache({ cleanUnused: true })时系统会保留本次运行中用过的和新生成的缓存记录删除未使用的旧记录然后写入文件。各模式下的行为read-write调用后清理并写入文件read-only手动 flush 覆盖 read-only 限制同样会清理并写入文件write-only不执行清理因为它不读取缓存。不传cleanUnused: true时flushCache()只写文件、不清理。文档示例是在afterEach中统一调用afterEach(async () { if (agent) { await agent.flushCache({ cleanUnused: true }); } if (resetFn) { await resetFn(); } });如果只想对个别 API 关闭缓存整体启用缓存的情况下可以给单次调用传cacheable: false。cacheable选项默认值为true各 API 的用法见 API 参考。边界与已知限制XPath 定位缓存的严格策略相同 XPath 下新元素的文本内容与缓存不同时、页面 DOM 结构与缓存时不同时缓存不会命中。以下 Web 场景定位缓存不可用依赖 DOM 结构Canvas 内部图形内容、跨域 iframe 内部 DOM、closed 模式的 Shadow DOM、WebGL / 动态 SVG 内容。缓存未命中或不可用时流程回退到 AI 服务查找元素或重新规划脚本不会因此失败但会失去加速效果。查询类结果aiBoolean、aiQuery、aiAssert始终实时执行不要指望它们命中缓存。页面结构变化是缓存失效的常见原因文档明确缓存不是确保脚本长期稳定执行的工具AI 服务仍然是必需的兜底。手动删除缓存的方式删除./midscene_run/cache目录中的缓存文件或直接编辑缓存文件内容。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Midscene 的缓存策略 read-write、read-only 与 write-only 怎么选？
Midscene 的缓存策略 read-write、read-only 与 write-only 怎么选【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene如果你的 Midscene 自动化脚本里包含重复执行的规划类操作ai、aiAct或 Web 元素定位操作aiLocate、aiTap每次运行都要重新调用 AI 模型执行时间和模型开销都会居高不下。Midscene 的缓存机制可以让你在相同任务指令、相似页面环境下复用已缓存的执行计划和元素 XPath而cache选项中的strategy配置了三种行为read-write、read-only、write-only。本文按文档给出的适用条件说明这三种策略各自解决什么问题、如何配置以及如何验证缓存是否命中。缓存什么、存在哪里先明确缓存覆盖的范围这决定了三种策略的讨论前提来源缓存文档任务指令缓存对规划类操作如ai、aiAct以 prompt 指令为缓存键存储 AI 返回的执行计划可用于各类自动化任务。元素定位缓存仅 Web对定位类操作如aiLocate、aiTap以定位 prompt 为缓存键存储元素 XPath下次执行时先验证 XPath 是否仍然有效。失效机制缓存失效时自动回退到 AI 模型重新分析。规划缓存回退如果缓存的aiAct规划运行时失败例如偶现弹窗本次没有出现Midscene 本次运行回退到正常 AI 规划并清空这条过期缓存的 flow即使回退成功也不会把回退生成的 flow 写回原 prompt 的规划缓存下一次运行相同 prompt 时会重新生成完整的规划缓存。查询结果永不缓存aiBoolean、aiQuery、aiAssert的查询结果不会被缓存。缓存内容保存到./midscene_run/cache目录下扩展名为.cache.yaml。文档给出的一个效果示例缓存命中后执行耗时从 51 秒降低到 28 秒文档示例具体数值随你的脚本和页面变化另外注意缓存是加速手段不是替代 AI 服务。当页面 DOM 结构变化导致缓存失效时Midscene 仍会调用 AI 重新执行任务。三种策略的适用条件strategy的默认值是read-write不配置cache选项时缓存处于禁用状态等效于cache: false每次都调用 AI 模型适合需要实时结果或调试时使用。策略行为文档给出的适用场景read-write自动读取已有缓存执行过程中自动更新缓存文件默认策略日常开发与常规执行write-only只写不读每次执行都调用 AI 模型并把结果写入缓存文件初次建立缓存或更新缓存read-only只读缓存不自动写文件需手动调用agent.flushCache()生产环境确保缓存一致性选择思路由此而来第一次为一个脚本建立缓存或缓存内容需要整体刷新时用write-only——它不读旧缓存保证全部结果由本次 AI 调用生成并写入文件日常开发执行用read-write默认——命中则复用未命中则调用 AI 并自动更新文件无需额外代码生产环境中如果希望只消费、不修改已入库的缓存文件用read-only配合显式的flushCache()决定何时写文件。配置方式直接创建 AgentJavaScript三种策略在构造 Agent 时通过cache选项配置。下面的my-cache-id是文档示例用的缓存 ID需要替换为你自己的唯一标识// read-write默认两种写法等价 const agent new PuppeteerAgent(page, { cache: { id: my-cache-id }, }); // 显式指定 strategy const agent new PuppeteerAgent(page, { cache: { strategy: read-write, id: my-cache-id }, }); // read-only只读缓存写文件需手动触发 const agent new PuppeteerAgent(page, { cache: { strategy: read-only, id: my-cache-id }, }); // 手动写入缓存 await agent.flushCache(); // write-only只写不读每次都会调用 AI 模型 const agent new PuppeteerAgent(page, { cache: { strategy: write-only, id: my-cache-id }, });YAML 脚本模式YAML 中在agent下配置cache字段说明见 YAML 脚本文档agent: cache: id: my-cache-test # 必填 strategy: read-write # 可选可选值read-only | read-write | write-onlyYAML 模式还支持cache: true自动使用文件名作为 cache ID。Playwright AI Fixture使用midscene/web/playwright的PlaywrightAiFixture时把同样的cache选项传给 fixtureexport const test base.extendPlayWrightAiFixtureType( PlaywrightAiFixture({ cache: true, // 或 cache: { id: my-fixture-cache } }), );read-only模式下需要在测试步骤完成后手动持久化缓存通过 fixture 提供的agentForPage获取底层 agent 再调用flushCache()。文档示例只在测试通过时 flushtest.afterEach(async ({ page, agentForPage }, testInfo) { // Only flush cache if the test passed if (testInfo.status passed) { console.log(Test passed, flushing Midscene cache...); const agent await agentForPage(page); await agent.flushCache(); } else { console.log(Test ${testInfo.status}, skipping Midscene cache flush.); } });兼容方式不推荐旧方式是通过环境变量MIDSCENE_CACHE1配合cacheId选项行为等同于 read-write 模式const agent new PuppeteerAgent(originPage, { cacheId: puppeteer-swag-sab });MIDSCENE_CACHE1 tsx demo.ts新代码直接使用cache选项即可。一条典型的组合路径把文档中各策略的适用说明串起来一个连续的操作路径是建缓存先用write-only或read-write完整跑一遍脚本让 AI 规划结果和 XPath 写入./midscene_run/cache下的.cache.yaml文件。日常执行切换为默认的read-write命中则复用未命中自动回退 AI 并更新缓存文件。生产/CI 消费切换为read-only读取入库的缓存只有在你确认要更新缓存文件时才显式调用agent.flushCache()写文件。注意第 3 步的前提CI 环境不会自动拿到本地生成的缓存文件文档明确指出需要在 CI 中将缓存文件提交到仓库并再次检查缓存命中条件否则缓存会一直不命中。验证缓存是否命中与调试文档给出的验证方式查看报告文件缓存命中时会看到cache提示并且该步执行时间明显降低。调试日志设置环境变量DEBUGmidscene:cache:*可以获得缓存相关的调试日志。检查缓存文件./midscene_run/cache目录下是否生成了对应的.cache.yaml文件没有生成时按 FAQ 逐项确认——直接创建 Agent 是否在构造函数里设置了cache: { id: ... }Fixture 是否设置了cache: true或cache: { id: ... }YAML 是否设置了agent.cache.idread-only 模式是否调用了flushCache()。缓存清理与单 API 关闭缓存缓存文件会变旧Midscene 提供完全手动的清理能力显式调用agent.flushCache({ cleanUnused: true })时系统会保留本次运行中用过的和新生成的缓存记录删除未使用的旧记录然后写入文件。各模式下的行为read-write调用后清理并写入文件read-only手动 flush 覆盖 read-only 限制同样会清理并写入文件write-only不执行清理因为它不读取缓存。不传cleanUnused: true时flushCache()只写文件、不清理。文档示例是在afterEach中统一调用afterEach(async () { if (agent) { await agent.flushCache({ cleanUnused: true }); } if (resetFn) { await resetFn(); } });如果只想对个别 API 关闭缓存整体启用缓存的情况下可以给单次调用传cacheable: false。cacheable选项默认值为true各 API 的用法见 API 参考。边界与已知限制XPath 定位缓存的严格策略相同 XPath 下新元素的文本内容与缓存不同时、页面 DOM 结构与缓存时不同时缓存不会命中。以下 Web 场景定位缓存不可用依赖 DOM 结构Canvas 内部图形内容、跨域 iframe 内部 DOM、closed 模式的 Shadow DOM、WebGL / 动态 SVG 内容。缓存未命中或不可用时流程回退到 AI 服务查找元素或重新规划脚本不会因此失败但会失去加速效果。查询类结果aiBoolean、aiQuery、aiAssert始终实时执行不要指望它们命中缓存。页面结构变化是缓存失效的常见原因文档明确缓存不是确保脚本长期稳定执行的工具AI 服务仍然是必需的兜底。手动删除缓存的方式删除./midscene_run/cache目录中的缓存文件或直接编辑缓存文件内容。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考