preflite 1.1.0 → 1.1.3

package/dist/mcp/visual-flow/types.js

@@ -2,4 +2,4 @@
  * 可视化编排 IR（与 Midscene 业务脚本双写：存库 + 生成 `scriptContent`）。
  * 版本字段便于后续迁移；步骤与 {@link generateScriptFromVisualFlow} 对齐。
  */
-export const VISUAL_FLOW_VERSION = 1;
+export const VISUAL_FLOW_VERSION = 2;

package/dist/mcp/visual-flow/validate.js

@@ -61,6 +61,156 @@ function parseScriptVars(raw) {
     }
     return { ok: true, value: out };
 }
+function parseSingleMockRule(o, path) {
+    const urlPattern = typeof o.urlPattern === 'string' && o.urlPattern.trim() ? o.urlPattern.trim() : "";
+    const urlRegex = typeof o.urlRegex === 'string' && o.urlRegex.trim() ? o.urlRegex.trim() : "";
+    if (!urlPattern && !urlRegex)
+        return { ok: false, message: `${path}.urlPattern 或 urlRegex 必填其一` };
+    if (urlPattern && urlPattern.length > 1000)
+        return { ok: false, message: `${path}.urlPattern 过长` };
+    if (urlRegex) {
+        try {
+            new RegExp(urlRegex);
+        }
+        catch {
+            return { ok: false, message: `${path}.urlRegex 无效` };
+        }
+    }
+    const queryParams = o.queryParams != null && typeof o.queryParams === 'object' && !Array.isArray(o.queryParams) ? Object.fromEntries(Object.entries(o.queryParams).filter(([, v]) => typeof v === 'string').map(([k, v]) => [k, v])) : undefined;
+    const method = typeof o.method === 'string' ? o.method.trim().toUpperCase() : '';
+    if (method && !['GET', 'POST', 'PUT', 'DELETE', 'PATCH'].includes(method))
+        return { ok: false, message: `${path}.method 须为 GET|POST|PUT|DELETE|PATCH` };
+    if (!Array.isArray(o.responses) || o.responses.length === 0)
+        return { ok: false, message: `${path}.responses 须为非空数组` };
+    if (o.responses.length > 50)
+        return { ok: false, message: `${path}.responses 超过上限 50` };
+    const responses = [];
+    const bodyStr = (b) => String(b);
+    for (let j = 0; j < o.responses.length; j++) {
+        const rPath = `${path}.responses[${j}]`;
+        const ri = o.responses[j];
+        if (!ri || typeof ri !== 'object' || Array.isArray(ri))
+            return { ok: false, message: `${rPath} 须为对象` };
+        const r = ri;
+        if (r.body == null)
+            return { ok: false, message: `${rPath}.body 必填` };
+        const body = bodyStr(r.body);
+        if (body.length > 1_000_000)
+            return { ok: false, message: `${rPath}.body 过长` };
+        const status = r.status != null ? Number(r.status) : 200;
+        if (!Number.isFinite(status) || status < 100 || status > 599)
+            return { ok: false, message: `${rPath}.status 须为 100～599` };
+        const callIndex = r.callIndex != null ? Number(r.callIndex) : undefined;
+        if (callIndex != null && (!Number.isFinite(callIndex) || callIndex < 1))
+            return { ok: false, message: `${rPath}.callIndex 须为正整数` };
+        const delay = r.delay != null ? Number(r.delay) : undefined;
+        if (delay != null && (!Number.isFinite(delay) || delay < 0 || delay > 60_000))
+            return { ok: false, message: `${rPath}.delay 须为 0～60000` };
+        responses.push({ status: Math.floor(status), body, ...(callIndex != null ? { callIndex: Math.floor(callIndex) } : {}), ...(delay != null ? { delay: Math.floor(delay) } : {}), ...(typeof r.headers === 'object' && r.headers && !Array.isArray(r.headers) && Object.keys(r.headers).length > 0 ? { headers: Object.fromEntries(Object.entries(r.headers).filter(([, v]) => typeof v === 'string').map(([k, v]) => [k, v])) } : {}), ...(typeof r.requestBodyMatch === 'object' && r.requestBodyMatch && !Array.isArray(r.requestBodyMatch) && Object.keys(r.requestBodyMatch).length > 0 ? { requestBodyMatch: Object.fromEntries(Object.entries(r.requestBodyMatch).filter(([, v]) => typeof v === 'string').map(([k, v]) => [k, v])) } : {}) });
+    }
+    const description = typeof o.description === 'string' && o.description.trim() ? o.description.trim().slice(0, 500) : undefined;
+    return { ok: true, value: { ...(urlPattern ? { urlPattern } : {}), ...(urlRegex ? { urlRegex } : {}), ...(queryParams && Object.keys(queryParams).length > 0 ? { queryParams } : {}), ...(method ? { method: method } : {}), responses, ...(description ? { description } : {}) } };
+}
+function parseNetworkMocks(raw) {
+    if (raw === undefined || raw === null)
+        return { ok: true, value: [] };
+    if (!Array.isArray(raw))
+        return { ok: false, message: 'visualFlow.networkMocks 须为数组' };
+    if (raw.length > 50)
+        return { ok: false, message: 'mock 规则数量超过上限 50' };
+    const out = [];
+    for (let i = 0; i < raw.length; i++) {
+        const path = `networkMocks[${i}]`;
+        const item = raw[i];
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            return { ok: false, message: `${path} 须为对象` };
+        }
+        const o = item;
+        const urlPattern = typeof o.urlPattern === 'string' && o.urlPattern.trim() ? o.urlPattern.trim() : "";
+        const urlRegex = typeof o.urlRegex === 'string' && o.urlRegex.trim() ? o.urlRegex.trim() : "";
+        if (!urlPattern && !urlRegex)
+            return { ok: false, message: `${path}.urlPattern 或 urlRegex 必填其一` };
+        if (urlPattern && urlPattern.length > 1000)
+            return { ok: false, message: `${path}.urlPattern 过长` };
+        if (urlRegex) {
+            try {
+                new RegExp(urlRegex);
+            }
+            catch {
+                return { ok: false, message: `${path}.urlRegex 不是有效的正则表达式` };
+            }
+        }
+        const queryParams = o.queryParams != null && typeof o.queryParams === 'object' && !Array.isArray(o.queryParams)
+            ? Object.fromEntries(Object.entries(o.queryParams).filter(([, v]) => typeof v === "string").map(([k, v]) => [k, v]))
+            : undefined;
+        const method = typeof o.method === 'string' ? o.method.trim().toUpperCase() : '';
+        if (method && !['GET', 'POST', 'PUT', 'DELETE', 'PATCH'].includes(method)) {
+            return { ok: false, message: `${path}.method 须为 GET|POST|PUT|DELETE|PATCH` };
+        }
+        if (!Array.isArray(o.responses) || o.responses.length === 0) {
+            return { ok: false, message: `${path}.responses 须为非空数组` };
+        }
+        if (o.responses.length > 50) {
+            return { ok: false, message: `${path}.responses 数量超过上限 50` };
+        }
+        const responses = [];
+        for (let j = 0; j < o.responses.length; j++) {
+            const rPath = `${path}.responses[${j}]`;
+            const rItem = o.responses[j];
+            if (!rItem || typeof rItem !== 'object' || Array.isArray(rItem)) {
+                return { ok: false, message: `${rPath} 须为对象` };
+            }
+            const r = rItem;
+            if (r.body == null)
+                return { ok: false, message: `${rPath}.body 必填` };
+            const body = String(r.body);
+            if (body.length > 1_000_000)
+                return { ok: false, message: `${rPath}.body 过长（上限 1MB）` };
+            const status = r.status != null ? Number(r.status) : 200;
+            if (!Number.isFinite(status) || status < 100 || status > 599) {
+                return { ok: false, message: `${rPath}.status 须为 100～599` };
+            }
+            const callIndex = r.callIndex != null ? Number(r.callIndex) : undefined;
+            if (callIndex != null && (!Number.isFinite(callIndex) || callIndex < 1)) {
+                return { ok: false, message: `${rPath}.callIndex 须为正整数` };
+            }
+            const delay = r.delay != null ? Number(r.delay) : undefined;
+            if (delay != null && (!Number.isFinite(delay) || delay < 0 || delay > 60_000)) {
+                return { ok: false, message: `${rPath}.delay 须为 0～60000` };
+            }
+            const headers = r.headers != null && typeof r.headers === 'object' && !Array.isArray(r.headers)
+                ? Object.fromEntries(Object.entries(r.headers)
+                    .filter(([, v]) => typeof v === 'string')
+                    .map(([k, v]) => [k, v]))
+                : undefined;
+            const requestBodyMatch = r.requestBodyMatch != null && typeof r.requestBodyMatch === 'object' && !Array.isArray(r.requestBodyMatch)
+                ? Object.fromEntries(Object.entries(r.requestBodyMatch)
+                    .filter(([, v]) => typeof v === 'string')
+                    .map(([k, v]) => [k, v]))
+                : undefined;
+            responses.push({
+                status: Math.floor(status),
+                body,
+                ...(callIndex != null ? { callIndex: Math.floor(callIndex) } : {}),
+                ...(delay != null ? { delay: Math.floor(delay) } : {}),
+                ...(headers && Object.keys(headers).length > 0 ? { headers } : {}),
+                ...(requestBodyMatch && Object.keys(requestBodyMatch).length > 0 ? { requestBodyMatch } : {}),
+            });
+        }
+        const description = typeof o.description === 'string' && o.description.trim()
+            ? o.description.trim().slice(0, 500)
+            : undefined;
+        out.push({
+            ...(urlPattern ? { urlPattern } : {}),
+            ...(urlRegex ? { urlRegex } : {}),
+            ...(queryParams && Object.keys(queryParams).length > 0 ? { queryParams } : {}),
+            ...(method ? { method: method } : {}),
+            responses,
+            ...(description ? { description } : {}),
+        });
+    }
+    return { ok: true, value: out };
+}
 function isNonEmptyString(v) {
     return typeof v === 'string' && v.trim().length > 0;
 }
@@ -321,6 +471,23 @@ function parseStep(raw, path) {
                 },
             };
         }
+        case 'setMock': {
+            if (!o.rule || typeof o.rule !== 'object' || Array.isArray(o.rule)) {
+                return { ok: false, message: `${path}.rule 须为 NetworkMockRule 对象` };
+            }
+            const mockParsed = parseSingleMockRule(o.rule, `${path}.rule`);
+            if (!mockParsed.ok)
+                return mockParsed;
+            return { ok: true, step: { type: 'setMock', rule: mockParsed.value } };
+        }
+        case 'removeMock': {
+            if (!isNonEmptyString(o.urlPattern))
+                return { ok: false, message: `${path}.urlPattern 必填` };
+            return { ok: true, step: { type: 'removeMock', urlPattern: o.urlPattern.trim() } };
+        }
+        case 'clearMocks': {
+            return { ok: true, step: { type: 'clearMocks' } };
+        }
         case 'callScript': {
             if (!isNonEmptyString(o.targetTestCaseId)) {
                 return { ok: false, message: `${path}.targetTestCaseId 必填` };
@@ -591,6 +758,9 @@ export function tryParseVisualFlow(raw) {
     const scriptVarsParsed = parseScriptVars(o.scriptVars);
     if (!scriptVarsParsed.ok)
         return scriptVarsParsed;
+    const networkMocksParsed = parseNetworkMocks(o.networkMocks);
+    if (!networkMocksParsed.ok)
+        return networkMocksParsed;
     const steps = [];
     for (let i = 0; i < o.steps.length; i++) {
         const r = parseStep(o.steps[i], `steps[${i}]`);
@@ -612,6 +782,7 @@ export function tryParseVisualFlow(raw) {
             version: VISUAL_FLOW_VERSION,
             ...(scriptVarsParsed.value.length ? { scriptVars: scriptVarsParsed.value } : {}),
             steps,
+            ...(networkMocksParsed.value.length ? { networkMocks: networkMocksParsed.value } : {}),
         },
     };
 }

package/docs/visual-flow-ir-llm.md

@@ -0,0 +1,221 @@
+# 可视化编排 IR（供模型生成 JSON）
+
+本文档供 **对话编排 / 自动生成 `visualFlow`** 的系统提示使用：只描述 **JSON 形状、字段含义与校验约束**，不含代码生成、HTTP 接口等平台实现细节。人类可读的平台语义、codegen 对照与落库说明见 `**VISUAL_FLOW_IR.md`**；字段以 `**backend/src/contexts/visual-flow/types.ts`**、校验以 `**validate.ts`** 为准。
+
+---
+
+## 1. 根对象 `VisualFlowDocument`
+
+
+| 字段           | 必填  | 说明                                   |
+| ------------ | --- | ------------------------------------ |
+| `version`    | 是   | 固定为数字 `2`，其它值保存失败。                   |
+| `scriptVars` | 否   | 执行前由人填的变量声明数组；步骤文案里用 `{{变量名}}` 引用。   |
+| `networkMocks` | 否   | 网络 mock 规则数组，在测试开始前启动代理并配置到设备。每条规则描述一个 API 的 URL 匹配与 mock 响应序列。 |
+| `steps`      | 是   | 顶层步骤数组，按顺序执行；**展开后总条数 ≤ 500**（含子步骤）。 |
+
+
+### 1.1 `scriptVars[]` 每项
+
+
+| 字段             | 必填  | 选填 / 备注                            |
+| -------------- | --- | ---------------------------------- |
+| `name`         | 是   | —                                  |
+| `description`  | 否   | 给人看的说明。                            |
+| `defaultValue` | 否   | 默认填值，字符串。                          |
+| `scope`        | 否   | `global`、`local` 或 `temp`；缺省按平台约定。 |
+
+
+### 1.2 `networkMocks[]` 每项
+
+| 字段           | 必填  | 说明                                   |
+| -------------- | --- | -------------------------------------- |
+| `urlPattern`   | 是   | 请求 URL 的子串匹配（`includes` 语义）。首个匹配的规则生效。 |
+| `method`       | 否   | HTTP 方法：`GET`、`POST`、`PUT`、`DELETE` 或 `PATCH`。不填则匹配任意方法。 |
+| `responses`    | 是   | 非空响应序列数组，按顺序匹配第一项满足条件的响应。 |
+| `description`  | 否   | 给人看的说明。 |
+
+#### `responses[]` 每项
+
+| 字段               | 必填  | 说明                                   |
+| ------------------ | --- | -------------------------------------- |
+| `body`             | 是   | 响应体字符串（通常为 JSON）。上限 1MB。 |
+| `status`           | 否   | HTTP 状态码，默认 200。范围 100～599。 |
+| `callIndex`        | 否   | 仅第 n 次调用时匹配（1-based）。用于实现状态性 mock：首次返回错误，二次返回成功。 |
+| `requestBodyMatch` | 否   | 键值对映射，必须在请求体的 JSON 中存在且值匹配才会命中。 |
+| `headers`          | 否   | 额外的响应头。Content-Type 默认为 `application/json; charset=utf-8`。 |
+| `delay`            | 否   | 响应延迟毫秒数。范围 0～60000。 |
+
+#### 匹配规则
+
+1. 遍历 `networkMocks`，找到第一条 `urlPattern` 是请求 URL 子串的规则。
+2. 递增该规则的调用计数器。
+3. 按顺序遍历 `responses`，找到第一项满足 `callIndex` 和 `requestBodyMatch` 的响应并返回。
+4. 若无匹配响应或请求不匹配任何规则，透明转发到真实服务器。
+
+#### 示例
+
+```json
+{
+  "networkMocks": [
+    {
+      "urlPattern": "getMafangRosterNewFlowSwitch",
+      "description": "启用码放新流程",
+      "responses": [
+        {
+          "status": 200,
+          "body": "{\"code\":200,\"data\":{\"newFlowEnabled\":true},\"subcode\":200}"
+        }
+      ]
+    },
+    {
+      "urlPattern": "copyWorkScheduleGroup",
+      "method": "POST",
+      "description": "日复制先弹确认再成功",
+      "responses": [
+        {
+          "callIndex": 1,
+          "status": 200,
+          "body": "{\"code\":\"WORK_SCHEDULE_PARTITION_MAFANG_COPY_SKIP_CONFIRM\",\"data\":{\"blockedCount\":2}}"
+        },
+        {
+          "callIndex": 2,
+          "requestBodyMatch": {"mafangSkipConfirmed": "true"},
+          "status": 200,
+          "body": "{\"code\":200,\"data\":{\"flag\":true}}"
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 2. 步骤类型与设计原则
+
+### 核心原则：所有 UI 交互都使用 `aiAct`
+
+- `aiAct` 是**唯一**的 UI 交互步骤类型。
+- 一个 `aiAct` 覆盖**一个完整的用户意图**，由视觉模型自行规划具体的点击、长按、滑动、输入等动作。
+- 例如，"长按第一个订单，在弹出菜单中选择「删除」，如果有确认弹窗则确认删除"——这是一个完整的意图，应当用**一个** `aiAct` 表达。
+
+### 其他步骤类型
+
+除 `aiAct` 外的步骤类型分为以下几类，各自有明确的非交互用途：
+
+| 类别 | 类型 | 说明 |
+|------|------|------|
+| **应用管理** | `launch` / `closeApp` / `installApp` / `uninstallApp` | 启动、关闭、安装、卸载应用 |
+| **等待** | `sleep` | 固定延时等待（页面跳转、动画、列表更新等） |
+| **断言** | `assert` | 视觉断言，验证 UI 状态是否符合预期 |
+| **上下文** | `setAIActContext` | 设置后续 `aiAct` 的突发情况处理策略（如权限弹窗、营销弹窗） |
+| **报告** | `recordToReport` | 向测试报告写入标题和内容 |
+| **变量** | `setVar` / `assignVar` / `transformVar` | 从屏幕读取数据、赋值或转换变量 |
+| **流程控制** | `if` / `ifDeviceType` / `whileLoop` / `forLoop` | 条件判断、按设备类型分支、循环 |
+| **脚本调用** | `callScript` | 调用其他测试用例 |
+
+### 每条步骤的公共规则
+
+- 每个步骤对象 **必须有** `type`（字符串）。
+- `**launch` / `closeApp` / `uninstallApp`**：使用包名类字段（`packageName` 或 `bundleId`）表达应用目标。
+- `aiAct` / `assert` / `setAIActContext`：用 `prompt` 写 **短而可执行** 的界面描述（可见文案、区域）。
+- 突发情况处理使用 `setAIActContext`：例如 `"遇到权限弹窗请同意，营销弹窗请拒绝"`。该上下文会带给后续 act 操作，由视觉模型自行处理弹窗等临时干扰。
+- `prompt` 保持简洁明确，只写必要信息。**`assert` 的 `prompt` 只需写明判断逻辑**，已有变量用 `{{}}` 插值即可，不要重复上下文。好：`"屏幕上的登录状态文本是{{expectedStatus}}"`；差：一段描述"看当前屏幕……由于……说明……"的长句。
+- 页面跳转、启动、刷新、动画结束、列表更新等"页面稳定"场景，使用 `sleep` 固定等待（如 2000～5000ms）。
+- `assert` 放在关键校验点，通常是本次改动点或必要回归点；普通步骤执行失败会自然阻塞流程。
+- `**if` / `ifDeviceType`**：`thenSteps` 非空数组；`**elseSteps`** 为 **选填**：可整段省略、或 `[]`、或 `null`（均表示「无 else 分支」）；若写出 `elseSteps` 且为非空数组，则其中为正常子步骤。
+- `**whileLoop` / `forLoop`**：`bodySteps` **非空数组**（无选填分支数组名）。
+- **同一条「线性执行路径」上**：`setVar` 的 `name` **不得重复**（含分支内继承规则，与校验一致）。
+- `**setVar.name` / `assignVar.name` / `transformVar.name`**：支持 Unicode 字母（含中文）/数字/`_`/`$`，且首字符为非数字；须匹配 `^[$_\\p{L}][\\p{L}\\p{N}_$]*$`（`/u` 语义），长度 1～64，并避开运行时保留名（如 `agent`、`page`、`console`、`process`、`sleep` 等，详见校验）。
+- 字符串字段中引用已声明变量时，**必须**使用 `**{{变量名}}`**、`{{变量名[0]}}`、`{{变量名.1}}`、`{{变量名.length}}` 等插值形式；其中 `.length` 用于读取数组长度（非数组按 `0` 处理）。
+- 已声明变量在字符串字段中统一使用插值形式；例如已声明 `timeBefore`、`timeAfter` 时，写成 `"{{timeBefore}}和{{timeAfter}}不同"`。
+
+---
+
+## 3. 步骤类型：必填、选填与约束
+
+列 **选填**：除「—」外，写出可出现的字段名；未列出者表示不宜随意加未知键（以 `types.ts` 为准）。
+
+
+| `type`                                                           | 必填字段                                            | 选填字段                                                      | 说明与取值约束                                                                                                                                                |
+| ---------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `launch`                                                         | `packageName`                                   | —                                                         | Android 包名 / iOS bundle id / 鸿蒙 bundle name。                                                                                                           |
+| `installApp`                                                     | `appRef`                                        | —                                                         | 本地路径、`file://` 或 `http(s)` 安装包地址。                                                                                                                      |
+| `uninstallApp`                                                   | `bundleId`                                      | —                                                         | 要卸载的应用标识。                                                                                                                                              |
+| `closeApp`                                                       | `packageName`                                   | —                                                         | 关闭正在运行的应用。                                                                                                                                             |
+| `setAIActContext`                                                | `prompt`                                        | —                                                         | 设置后续 aiAct 操作的上下文，适合声明权限弹窗、营销弹窗、升级提示等突发情况处理策略。                                                                                                   |
+| `recordToReport`                                                 | `title`, `content`                              | —                                                         | 二者均为字符串，**允许空串**；有长度上限（校验）。                                                                                                                            |
+| `assert`                                                         | `prompt`                                        | —                                                         | 断言命题。                                                                                                                                                  |
+| `sleep`                                                          | `ms`                                            | —                                                         | 整数 **0～3600000**（毫秒）；页面稳定、动画结束、跳转缓冲使用本步骤。                                                                                                             |
+| `aiAct`                                                          | `prompt`                                        | —                                                         | **唯一的 UI 交互步骤类型**。描述完整的用户意图、关键约束和完成条件，让视觉模型自行规划具体操作。                                                                                                 |
+| `if`                                                             | `conditionPrompt`, `thenSteps`                  | `**elseSteps`**                                           | 条件为真执行 `thenSteps`；无 else 则省略 `elseSteps` / `[]` / `null`。                                                                                             |
+| `ifDeviceType`                                                   | `interfaceType`, `thenSteps`                    | `**elseSteps`**                                           | `interfaceType` 仅 `android`、`ios`、`harmony`；无 else 同上。                                                                                                 |
+| `whileLoop`                                                      | `conditionPrompt`, `maxIterations`, `bodySteps` | —                                                         | `maxIterations`：1～1000 整数。                                                                                                                             |
+| `forLoop`                                                        | `count`, `bodySteps`                            | —                                                         | `count`：1～500 整数。                                                                                                                                      |
+| `setVar`                                                         | `name`, `method`, `expression`                  | —                                                         | `method` 仅 `aiQuery`、`aiAsk`、`aiBoolean`、`aiNumber`、`aiString`。`aiQuery` 的 `expression` 可为自然语言或整段 JSON 抽取需求；其余 method 的 `expression` 为对应 API 的 prompt。 |
+| `assignVar`                                                      | `name`, `value`                                 | —                                                         | 字面值或带 `{{}}` 的模板；**不用**于从屏读数（读屏用 `setVar`）。                                                                                                            |
+| `transformVar`                                                   | `name`, `rule`                                  | `source`、`start`、`end`、`jsonPath`、`pattern`、`replacement` | `rule`：`onlyNumber`、`cut`、`jsonPath`、`replace`、`handleAmount`；按规则选用上述选填字段。                                                                             |
+| `callScript`                                                     | `targetTestCaseId`, `scopeId`, `varBindings`    | `**targetName`**                                          | `targetTestCaseId`：24 位 hex；`scopeId`：`sub` + 12 位小写 hex；`varBindings` 可为 `{}`；`targetName` 仅展示用。                                                      |
+
+
+步骤 `type` 使用上表枚举；生成后先调用 `validate_visual_flow`，按返回信息修正结构。
+
+---
+
+## 4. 易错校验（生成后自查）
+
+- `version !== 2` → 失败。
+- `networkMocks` 超过 50 条规则或单条规则的 `responses` 超过 50 项 → 失败。
+- `networkMocks[].urlPattern` 为空或过长（>1000）→ 失败。
+- `networkMocks[].responses` 为空数组 → 失败。
+- `if` / `ifDeviceType` 的 `thenSteps` 为空，或 `whileLoop` / `forLoop` 的 `bodySteps` 为空 → 失败。
+- `sleep.ms`、`whileLoop.maxIterations`、`forLoop.count` 超出上表范围 → 失败。
+- `callScript.targetTestCaseId` 非 24 位 hex，或 `scopeId` 不符合 `sub`+12hex → 失败。
+- 同一路径重复 `setVar.name` → 失败。
+- 声明过的变量在 `prompt` / `value` / `expression` / `varBindings` 等字符串字段中使用 `{{}}` 插值。
+- 页面稳定等待使用 `sleep`；关键结果检查使用 `assert`。
+- `assert` 聚焦关键校验点，通常是本次改动点或必要回归点。
+- **所有 UI 交互必须使用 `aiAct`**。
+
+---
+
+## 5. 完整示例（含 `scriptVars`、条件分支、`assert`）
+
+下列为**可直接通过结构校验**的示意：请把包名、文案改成目标应用真实情况。
+
+```json
+{
+  "version": 1,
+  "scriptVars": [
+    { "name": "phone", "description": "登录手机号", "defaultValue": "" }
+  ],
+  "steps": [
+    { "type": "launch", "packageName": "com.example.app" },
+    { "type": "setAIActContext", "prompt": "遇到权限弹窗请同意，营销弹窗请拒绝" },
+    { "type": "sleep", "ms": 3000 },
+    {
+      "type": "if",
+      "conditionPrompt": "当前是否已在登录页（能看到手机号输入框）",
+      "thenSteps": [
+        {
+          "type": "aiAct",
+          "prompt": "在手机号输入框中输入{{phone}}，然后点击「获取验证码」按钮"
+        },
+        { "type": "sleep", "ms": 3000 },
+        { "type": "assert", "prompt": "出现短信验证码输入框或倒计时提示" }
+      ],
+      "elseSteps": [
+        { "type": "aiAct", "prompt": "点击底部或顶部的「我的」或个人中心入口" }
+      ]
+    },
+    { "type": "assert", "prompt": "页面显示已登录态（头像、昵称或「退出登录」其一）" },
+    { "type": "sleep", "ms": 500 },
+    { "type": "closeApp", "packageName": "com.example.app" }
+  ]
+}
+```
+
+---
+
+**维护约定**：新增或变更步骤类型时，须同步 `**types.ts`** / `**validate.ts`** / `**VISUAL_FLOW_IR_LLM.md`** / `**VISUAL_FLOW_IR.md`**，保持模型提示与保存校验一致。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preflite",
-  "version": "1.1.0",
+  "version": "1.1.3",
   "description": "Preflight — Local mobile AI testing via MCP. AI-assisted testing on real Android/iOS/Harmony devices.",
   "license": "Apache-2.0",
   "type": "module",
@@ -9,6 +9,8 @@
   },
   "files": [
     "dist/",
+    "docs/visual-flow-ir-llm.md",
+    "scripts/",
     "README.md",
     "LICENSE"
   ],

package/scripts/hdc-bridge.sh

@@ -0,0 +1,4 @@
+# hdc bridge
+# Usage: eval "$(hdc-bridge.sh)" or source it
+# Should not be executed directly
+echo "hdc() { command hdc -s \"${HDC_S:-127.0.0.1:17815}\" \"\$@\"; }"

package/scripts/nvm-use-repo.sh

@@ -0,0 +1,31 @@
+# shellcheck shell=bash
+# Sourced by run-midscene-task.sh: load nvm and run `nvm use` in the repo root.
+# No side effects: failure does not exit; caller decides whether to error on insufficient Node version.
+
+_try_source_nvm() {
+  if [[ -n "${NVM_DIR:-}" && -s "${NVM_DIR}/nvm.sh" ]]; then
+    # shellcheck disable=SC1090
+    source "${NVM_DIR}/nvm.sh"
+    return 0
+  fi
+  local d
+  for d in "${HOME}/.nvm" "/usr/local/opt/nvm"; do
+    if [[ -s "${d}/nvm.sh" ]]; then
+      export NVM_DIR="${d}"
+      # shellcheck disable=SC1090
+      source "${d}/nvm.sh"
+      return 0
+    fi
+  done
+  return 1
+}
+
+_nvm_use_repo() {
+  local repo_root="${1:?repo root}"
+  _try_source_nvm || return 1
+  local dsave="${PWD}"
+  cd "${repo_root}" || return 1
+  nvm use >/dev/null 2>&1 || true
+  cd "${dsave}" || true
+  return 0
+}

package/scripts/run-midscene-task.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Midscene subprocess entry: prefer Node/tsx from runtime package; fall back to nvm + npx in dev mode.
+set -euo pipefail
+
+TASK_SCRIPT="${1:?usage: run-midscene-task.sh <path-to-task-script.ts>}"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/nvm-use-repo.sh"
+
+cd "${REPO_ROOT}"
+
+NODE_BIN="${PREFLIGHT_RUNTIME_NODE:-}"
+if [[ -z "${NODE_BIN}" && -x "${REPO_ROOT}/node/bin/node" ]]; then
+  NODE_BIN="${REPO_ROOT}/node/bin/node"
+fi
+if [[ -z "${NODE_BIN}" ]]; then
+  _nvm_use_repo "${REPO_ROOT}" || true
+  NODE_BIN="$(command -v node || true)"
+fi
+if [[ -z "${NODE_BIN}" || ! -x "${NODE_BIN}" ]]; then
+  echo "[run-midscene-task] Node not found. Install Node 20+ or use the runtime package's node/bin/node." >&2
+  exit 1
+fi
+
+if [[ -d "${REPO_ROOT}/node/bin" ]]; then
+  export PATH="${REPO_ROOT}/node/bin:${PATH}"
+fi
+
+major="$("${NODE_BIN}" -p "parseInt(process.versions.node,10)" 2>/dev/null || echo 0)"
+if [[ "${major}" -lt 20 ]]; then
+  echo "[run-midscene-task] Node >= 20 required (current: $("${NODE_BIN}" -v 2>/dev/null || echo unknown))." >&2
+  echo "[run-midscene-task] Install Node 20+ or set PREFLIGHT_RUNTIME_NODE or MIDSCENE_RUN_COMMAND to override." >&2
+  exit 1
+fi
+
+TSX_CLI="${REPO_ROOT}/node_modules/tsx/dist/cli.mjs"
+if [[ -f "${TSX_CLI}" ]]; then
+  exec "${NODE_BIN}" "${TSX_CLI}" "${TASK_SCRIPT}"
+fi
+
+exec npx tsx "${TASK_SCRIPT}"