Midscene Yaml Generator

红旗自检 — 发现自己在做以下事情时立即停止

• 编写 require('@midscene/web') 或 import ... from '@midscene' → 停止，改用 CLI
• 创建 package.json 或运行 npm init → 停止，项目已有依赖或不需要 package.json（外部项目用 npx @midscene/web）
• 安装 @midscene/cli 或 npx midscene → 停止，正确包名是 @midscene/web
• 查找 Chrome 可执行文件路径 → 停止，在 .env 中设置 PUPPETEER_EXECUTABLE_PATH 或运行 node scripts/health-check.js
• 编写 .js 或 .ts 文件来执行 YAML → 停止，改用 CLI
• 安装 puppeteer 或 playwright → 停止，依赖已在 package.json 中

→ 回到正轨：生成 .yaml 文件，用 CLI 执行。

关键规则（必读）

1. Extended 模式必须同时声明 engine: extended 和 features: [...] — 使用变量、循环、条件、导入等任何扩展功能时，两者缺一不可，否则运行时静默失败
2. ${ENV:XXX} 在平台配置中不需要 Extended 模式 — 仅在 flow 步骤中使用 ${varName} 变量插值才需要 Extended。示例：url: "${ENV:SITE_URL}" → Native 即可；value: "${username}" → 需要 Extended
3. 每个 aiInput 必须有 value 参数 — 没有 value 的 aiInput 等于空操作
4. 循环必须有安全上限 — while 循环必须设置 maxIterations；for/repeat 的 count 不应超过 10000
5. name 变量仅 task 内有效 — 跨 task 传递数据需用 output: { filePath, dataName } 导出为 JSON 文件
6. 仅使用 schema 中已定义的关键字 — 优先参考本文档中的映射表和选中的模板文件，对合法关键字有疑问时再用 Read 工具读取 schema/native-keywords.json 确认
7. viewportHeight 默认值为 960（非 720），viewportWidth 默认值为 1280
8. 语义保护: 自动修复 MUST NOT 修改 ai:、aiTap:、aiInput:、aiAssert:、aiQuery:、aiWaitFor: 等步骤的字符串描述值 — 这些是用户意图，修改可能改变语义
9. 省略默认值: 不要显式设置与默认值相同的值。engine: native → 省略（native 是默认）；viewportHeight: 960 → 省略；headless: false → 省略。只写与默认值不同的配置

常见致命错误参见下方「输出前自检清单」。

首次使用

前置条件: Node.js >= 22、.env 已配置。

项目上下文检测（重要）

生成 YAML 前先判断当前环境：

# 检测方式（生成前自动执行）
ls scripts/midscene-run.js 2>/dev/null && echo "PROJECT" || echo "EXTERNAL"

外部项目注意：

• 无需创建 package.json，npx @midscene/web 会自动下载
• 无需 npm install，无需安装任何额外依赖
• 包名是 @midscene/web（不是 @midscene/cli，不是 midscene）
• dry-run: npx @midscene/web <file> --dry-run（注意：外部 CLI 的 dry-run 可能仍需 Chrome）

.env 配置

在项目根目录创建 .env 文件：

# AI 模型（必须）
MIDSCENE_MODEL_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
MIDSCENE_MODEL_API_KEY=sk-your-key
MIDSCENE_MODEL_NAME=doubao-seed-2.0

# Chrome 路径（可选，自动检测失败时设置）
# Windows 示例:
# PUPPETEER_EXECUTABLE_PATH=C:\Program Files\Google\Chrome\Application\chrome.exe
# Mac 示例:
# PUPPETEER_EXECUTABLE_PATH=/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
# Linux 示例:
# PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome

重要: Chrome 路径务必写入 .env 而非临时设置环境变量，避免每次重复配置。

如果在项目内，运行健康检查：

node scripts/health-check.js

快速体验："生成一个在 example.com 搜索 Midscene 的 YAML"

典型工作流

用户需求 → 检测项目上下文（项目内 or 外部项目）
         → [Generator] 生成 YAML
         → [Generator] 自动 dry-run 验证
         → 验证失败？→ [Generator] 自动修复
         → [Runner] 执行
         → 执行失败？→ [Runner] 分析 + 修复 YAML → 重新执行
         → 成功 → 展示报告摘要

用户意图决策树

无论用户怎么描述（"脚本"、"程序"、"代码"），你的输出始终是 .yaml 文件。

职责范围

Generator 的唯一输出产物是 .yaml 文件（输出到 ./midscene-output/）。绝不输出 .js、.ts、package.json 或任何非 YAML 文件。

Generator 负责：需求分析 → YAML 生成 → dry-run 验证 → 自动修复（最多 3 次） → 接收 Runner ESCALATE 进行针对性修改。职责边界: Generator 负责 dry-run 阶段修复（最多 3 次）；Runner 负责执行阶段修复（最多 2 次）

不负责（用户/Runner 负责）：.env 创建和 API Key 配置、Chrome 安装、npm install、YAML 执行和报告解读、编写任何 JavaScript/TypeScript 代码

触发条件

当用户描述一个浏览器自动化需求（自然语言），需要生成 Midscene YAML 文件时使用。

常见触发短语："生成 YAML"、"写自动化脚本"、"创建测试用例"、"自动化 XXX"、"Generate a YAML for..."、"Automate the login flow"

工作流程

第 1 步：分析需求复杂度

生成前先说明：(a) 选择的模式及原因 (b) 基于的模板 (c) 需要的澄清

根据用户描述判断所需模式：

选择 Native 模式 — 当需求仅涉及：

• 打开网页 / 启动应用
• 点击、悬停、输入、滚动、键盘操作等基础交互
• AI 自动规划执行（ai）
• 数据提取（aiQuery）
• 验证断言（aiAssert）
• 等待条件（aiWaitFor）
• 工具操作（sleep、javascript、recordToReport）
• 平台特定操作（runAdbShell、runWdaRequest、launch）

选择 Extended 模式 — 当需求涉及以下任一：

• 条件判断（"如果...则..."）
• 循环操作（"重复"、"遍历"、"翻页"）
• 变量和动态数据（"定义变量"、"参数化"）
• 外部 API 调用（"调用接口"）
• 错误处理重试（"失败了就..."、"重试"）
• 并行任务（"同时做..."）
• 数据转换处理（"过滤"、"排序"、"映射"）
• 导入复用子流程（"复用"、"导入"）

经验法则: 先用 Native 写，当你发现自己需要 if、for 或变量时，切换到 Extended。

第 2 步：确定目标平台

根据用户描述判断平台配置：

Web 平台常用配置：headless、viewportWidth/Height(默认 1280×960)、userAgent、deviceScaleFactor(设 0 修复闪烁)、cookie(会话恢复)、bridgeMode(复用浏览器)、chromeArgs、serve(本地文件)、waitForNetworkIdle。

完整 Web/Android/iOS/Computer 配置选项详见 skills/midscene-yaml-generator/REFERENCE.md 的「平台配置详情」章节。

第 3 步：自然语言 → YAML 转换

动作选择优先级（重要）

默认使用即时动作；仅在步骤不确定时降级使用 ai:

经验法则:

• 步骤明确 → 用 aiTap/aiInput 等即时动作，执行更快更稳定
• 步骤不确定、需要 AI 自主规划 → 用 ai:（如 ai: "完成整个结账流程"）
• 两者可混合使用：先用 ai: 处理复杂交互，再用 aiQuery 提取数据

黄金路径 — 最简可工作示例（优先用即时动作）: