preflite 1.1.1 → 1.1.3

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

@@ -9,8 +9,9 @@
 
 | 字段           | 必填  | 说明                                   |
 | ------------ | --- | ------------------------------------ |
-| `version`    | 是   | 固定为数字 `1`，其它值保存失败。                   |
+| `version`    | 是   | 固定为数字 `2`，其它值保存失败。                   |
 | `scriptVars` | 否   | 执行前由人填的变量声明数组；步骤文案里用 `{{变量名}}` 引用。   |
+| `networkMocks` | 否   | 网络 mock 规则数组，在测试开始前启动代理并配置到设备。每条规则描述一个 API 的 URL 匹配与 mock 响应序列。 |
 | `steps`      | 是   | 顶层步骤数组，按顺序执行；**展开后总条数 ≤ 500**（含子步骤）。 |
 
 
@@ -25,6 +26,70 @@
 | `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. 步骤类型与设计原则
@@ -100,7 +165,10 @@
 
 ## 4. 易错校验（生成后自查）
 
-- `version !== 1` → 失败。
+- `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 → 失败。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preflite",
-  "version": "1.1.1",
+  "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",