Midscene.js 多语言支持：5 步跑通第一条中英文混合指令-编程实验室

Midscene.js 多语言支持：5 步跑通第一条中英文混合指令

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

用 Midscene.js 写国际化自动化脚本时，指令、元素定位、断言都可以直接写成自然语言，中文、英文或两者混排都不影响执行。本文从一个真实场景出发，带你在 5 步内跑通一条中英文混合指令，并给出缓存、模型与调试报告的工程化配置方法。

场景：一个中英文混排的后台，自动化脚本怎么写

某运营后台左侧菜单是英文，表单标签是中文，报错文案又是英文。传统写法要么维护两套 selector 映射，要么把文案翻译成断言字符串，每次界面改版都要跟着改。Midscene.js 的思路是把界面理解交给多模态模型：你直接用界面语言写指令，模型自己负责识别。痛点在于三件事——指令语言、缓存策略、模型选择，下面按实际执行顺序逐一解决。

用中文指令跑通第一条脚本

先装 CLI 并配置一个多模态模型的 API Key（MIDSCENE_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-write

YAML 模式同样支持id加strategy，生产环境可以用read-only避免缓存被意外改写。官方文档给出的效果是执行耗时从 51 秒降到 28 秒：

左图为未启用缓存时的执行报告，同一脚本启用缓存后的耗时明显下降。

右图为启用缓存后的执行报告，命中的步骤直接复用规划结果。

模型用环境变量切换，无需改代码：

MIDSCENE_MODEL_API_KEY=sk-xxx MIDSCENE_MODEL_NAME=qwen2.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），仅供参考