Midscene.js 多语言支持5 步跑通第一条中英文混合指令【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene用 Midscene.js 写国际化自动化脚本时指令、元素定位、断言都可以直接写成自然语言中文、英文或两者混排都不影响执行。本文从一个真实场景出发带你在 5 步内跑通一条中英文混合指令并给出缓存、模型与调试报告的工程化配置方法。场景一个中英文混排的后台自动化脚本怎么写某运营后台左侧菜单是英文表单标签是中文报错文案又是英文。传统写法要么维护两套 selector 映射要么把文案翻译成断言字符串每次界面改版都要跟着改。Midscene.js 的思路是把界面理解交给多模态模型你直接用界面语言写指令模型自己负责识别。痛点在于三件事——指令语言、缓存策略、模型选择下面按实际执行顺序逐一解决。用中文指令跑通第一条脚本先装 CLI 并配置一个多模态模型的 API KeyMIDSCENE_MODEL_API_KEY、MIDSCENE_MODEL_BASE_URL再写一个最短脚本web: url: http://localhost:3000 flow: - aiAct: 点击顶部导航栏的 Login 按钮 - aiInput: prompt: 用户名字段Username value: admin上面这段演示最简 YAML 脚本aiAct用中文prompt描述里保留了界面里的英文标签。运行后执行结果落在midscene_run/目录打开生成的 HTML 报告就能看到每一步的截图与规划。npx midscene/cli run demo.yml一行命令执行脚本并自动生成调试报告报告里每步都带截图和 AI 规划中英文指令的成败一目了然。Playground 中直接输入自然语言指令验证效果指令语言可以是中文也可以是英文。跨语言定位、输入与断言怎么分工定位和输入解决找到并操作元素。aiLocate返回元素位置aiTap直接点两者的 prompt 写哪种语言都行// 指令用中文prompt 里保留界面英文标签 const btn await agent.aiLocate(页面右上角的 Sign in 按钮); await agent.aiInput(用户名输入框, admin);这段演示中文指令 英文界面词的定位组合prompt 里把界面上真实出现的英文原文写进去比纯意译命中率更高。测试数据同理aiInput的value可以是任意语言aiQuery提取的数据字段名建议保持英文方便后续断言复用const products await agent.aiQuery( 页面中的商品列表{name: string, price: number}[] );这段演示中文 prompt 提取结构化数据、字段名用英文的惯例避免数据层混入不可控的翻译。断言解决验证结果。aiAssert的文案应与界面显示语言一致// 中文断言 await agent.aiAssert(页面顶部出现登录成功提示); // 英文断言 await agent.aiAssert(A Login success toast appears at the top);跨语言断言的关键不是翻译指令而是让断言文本贴近界面实际渲染的文案断言失败时报告里会标出模型判断依据。缓存与模型何时配、配什么、不配会怎样缓存默认关闭不配置时每条指令每次都调用模型中英文指令的耗时没有区别但重复执行的 CI 成本会累积。开启方式是指定id的策略配置const agent new PuppeteerAgent(page, { cache: { id: mixed-lang-demo }, });这段演示读写缓存规划与定位结果写入./midscene_run/cache目录相同 prompt 下次执行直接复用。注意缓存键就是 prompt 原文——中文指令和英文指令是两条独立缓存互不命中。agent: cache: id: mixed-lang-demo strategy: read-writeYAML 模式同样支持id加strategy生产环境可以用read-only避免缓存被意外改写。官方文档给出的效果是执行耗时从 51 秒降到 28 秒左图为未启用缓存时的执行报告同一脚本启用缓存后的耗时明显下降。右图为启用缓存后的执行报告命中的步骤直接复用规划结果。模型用环境变量切换无需改代码MIDSCENE_MODEL_API_KEYsk-xxx MIDSCENE_MODEL_NAMEqwen2.5-vl-72b-instruct npx midscene/cli run demo.yml选模型的实操方法是拿同一个脚本换不同模型各跑一遍用报告对比每步耗时和定位精度而不是凭文档结论。模型配置的完整清单见 apps/site/docs/zh/model-config.mdx。踩坑实录三个真实报错的解法报错cache: true requires an explicit cache ID。直接写cache: true会抛错原因见 packages/core/src/agent/cache-config.ts缓存必须绑定显式id否则无法区分脚本。解法是永远写{ id: ... }YAML 模式可以偷懒写cache: true它会自动取脚本文件名当 ID。现象换了一种语言描述同一步骤缓存全失效、耗时翻倍。缓存键是 prompt 原文点击 Login 按钮和Click the Login button命中不了同一条缓存。解法是同一脚本内指令语言保持一致确需换语言时把id后缀也改掉让新旧缓存并存而不是互相污染。现象Web 场景下定位偶尔失败报告里显示走了 AI 重规划。这是 XPath 定位缓存的失效回退页面结构变化后缓存的 XPath 校验不通过系统自动回退到视觉模型重新定位结果仍正确但多花一次调用。解法是对改版频繁的页面用read-only策略并在改版后清理midscene_run/cache里的旧文件。端到端一份混合语言脚本从运行到报告把前面的能力合起来下面这份脚本在同一个后台完成登录、切换语言、验证、取数全流程web: url: http://localhost:3000 output: ./result.json agent: cache: { id: admin-mixed, strategy: read-write } flow: - aiAct: 点击 Login 按钮进入登录页 - aiInput: { prompt: 账号输入框, value: admin } - aiInput: { prompt: password field, value: secret } - aiAct: 点击确定按钮 - aiAssert: 左侧菜单显示 Dashboard 标签 - aiAct: switch the language to 简体中文 - aiAssert: 菜单首项显示仪表盘 - aiQuery: 当前用户信息{name: string, role: string}这段演示指令语言、界面语言、测试数据三者各自独立中文描述操作英文描述界面词数据字段名保持英文。执行npx midscene/cli run admin-mixed.yml后result.json拿到结构化数据报告落在midscene_run/report失败步骤会带截图和 AI 规划中英文指令都能直接定位问题。执行报告以截图加 AI 规划的形式展示每一步是多语言脚本的主要调试入口。收尾三件事和下一步指令语言在单个脚本内保持统一缓存键才不会互相失效cache一律显式给id改版页面记得清midscene_run/cache模型差异用报告实测不凭感觉切换。下一步clone 仓库git clone https://gitcode.com/GitHub_Trending/mid/midscene从 apps/site/docs/zh/automate-with-scripts-in-yaml.mdx 挑一个 YAML 示例把其中两条指令改成另一种语言对比两次的报告耗时和定位结果。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考