@kkeve/suite 0.0.21 → 0.0.22

package/dist/dsl/toDecorator.js

@@ -203,7 +203,12 @@ function renderStep(d, ctx) {
             break;
         case 'DRAGGING': {
             // 拖拽：context 为源，value/child 携带目标链；缺失目标不得伪装成悬停成功
-            const valueCtx = (typeof d.value === 'object' && d.value !== null ? d.value.context : undefined);
+            const rawValue = d.value;
+            const valueCtx = Array.isArray(rawValue)
+                ? rawValue
+                : (rawValue && typeof rawValue === 'object'
+                    ? rawValue.context || rawValue.value
+                    : undefined);
             const targetCtx = valueCtx || d.child?.context || d.child;
             if (Array.isArray(targetCtx) && targetCtx.length) {
                 emit([`await engine.drag(${chain}, ${chainExpr(targetCtx)});`, ...waitExprs(d)]);

package/dist/engine-playwright/keve-test.js

@@ -133,8 +133,10 @@ exports.test = test_1.test.extend({
         //（自定义 context 不会自动附加视频附件，需在 context 关闭后显式 attach）
         const videoOpt = testInfo.project?.use?.video;
         const videoOn = !!videoOpt && (videoOpt === 'on' || videoOpt.mode === 'on' || videoOpt.mode === 'retain-on-failure');
+        const viewport = testInfo.project?.use?.viewport;
         const context = await browser.newContext({
             storageState,
+            ...(viewport ? { viewport } : {}),
             ...(videoOn ? { recordVideo: { dir: typeof videoOpt === 'object' && videoOpt.dir ? videoOpt.dir : undefined } } : {}),
         });
         const page = await context.newPage();

package/dist/engine-playwright/pw-config.js

@@ -88,6 +88,7 @@ export default defineConfig({
   ],
   use: {
     baseURL: ${baseURLLine},${cdp ? `\n    // CDP mode: login state preserved via connected Chrome` : `\n    storageState: path.resolve(projectRoot, '.auth/storage-state.json'),`}
+    viewport: { width: 2560, height: 1440 },
     trace: 'on-first-retry',
     screenshot: 'off',
     video: 'on',
@@ -136,6 +137,7 @@ export default defineConfig({
   ],
   use: {
     baseURL: ${baseURLLine},${cdp ? `\n    // CDP mode: login state preserved via connected Chrome` : `\n    storageState: resolve(projectRoot, '.auth', 'storage-state.json'),`}
+    viewport: { width: 2560, height: 1440 },
     trace: 'on-first-retry',
     screenshot: 'off',
     video: 'on',

package/dist/runner/index.d.ts

@@ -0,0 +1,85 @@
+import { type DslStep, type DslVariableRow } from '../dsl/index.js';
+export type ExecutionEngine = 'cypress' | 'playwright';
+export interface ResolveEngineBinOptions {
+    engine: ExecutionEngine;
+    /** 平台执行侧根目录（声明并安装了 cypress / @playwright/test / esbuild） */
+    backendRoot: string;
+    /** 本 runner 包根目录；本地调试等场景可退回到自身 node_modules */
+    suiteRoot: string;
+}
+/**
+ * 按引擎解析可执行文件路径。
+ * 候选顺序：环境变量显式指定 → backendRoot/node_modules → suiteRoot/node_modules。
+ * 三种调用方（线上 runner / 本地调试 open 模式）共用同一份候选顺序，
+ * 避免「平台能跑、本地跑不起来」这类环境差异问题各自排查一遍。
+ */
+export declare function resolveEngineBin({ engine, backendRoot, suiteRoot }: ResolveEngineBinOptions): string | undefined;
+/** esbuild 模块路径解析，Cypress 预处理器依赖。候选顺序与 resolveEngineBin 一致。 */
+export declare function resolveEsbuildModule(backendRoot: string, suiteRoot: string): string | undefined;
+export interface BuildExecEnvOptions {
+    input: {
+        backendRoot?: string;
+        env?: string;
+        targetUrl?: string;
+        ssoCookiesJson?: string;
+        identitySsoCookies?: Record<string, string>;
+        llm?: {
+            baseUrl?: string;
+            model?: string;
+            apiKey?: string;
+        };
+    };
+    taskDir: string;
+    round: string | number;
+    engine: ExecutionEngine;
+    /** 兜底 backendRoot：input.backendRoot 为空时使用 */
+    defaultBackendRoot: string;
+    suiteRoot: string;
+}
+/**
+ * 两个引擎共用的 KEVE_* 环境变量契约。
+ * run（headless 批跑）和 open（交互调试）模式必须拼出完全一致的变量集，
+ * 否则同一份静态 cypress.config.mjs / playwright.config.mjs 在两种模式下读到不同的值。
+ */
+export declare function buildExecEnv({ input, taskDir, round, engine, defaultBackendRoot, suiteRoot, }: BuildExecEnvOptions): NodeJS.ProcessEnv;
+export interface CaseInput {
+    stepGroupId: number | string;
+    caseName?: string;
+    dslList: DslStep[];
+    variableList?: DslVariableRow[];
+    accountInfo?: {
+        accountInfo?: {
+            name?: string;
+            password?: string;
+        };
+        name?: string;
+        password?: string;
+    } | null;
+}
+export interface ProjectCasesOptions {
+    cases: CaseInput[];
+    engine: ExecutionEngine;
+    specDir: string;
+    env: string;
+    ssoInject?: boolean;
+    /** 用例级账号未指定时的兜底账号 */
+    defaultAccountInfo?: CaseInput['accountInfo'];
+}
+export interface CaseEntry {
+    caseId: string;
+    stepGroupId: number;
+    caseName: string;
+    specFile: string;
+    stepCount: number;
+    steps: {
+        step: string;
+        expected: string;
+    }[];
+}
+/**
+ * 逐条用例投影成装饰器脚本，落盘到 specDir，并返回报告索引（caseEntries）。
+ * run / open 两种模式共用同一份投影，脚本内容、步骤文案完全一致。
+ */
+export declare function projectCasesToSpecs({ cases, engine, specDir, env, ssoInject, defaultAccountInfo, }: ProjectCasesOptions): CaseEntry[];
+/** 供报告补全步骤文案的最小用例清单（cases/test-cases.yaml） */
+export declare function buildCasesYaml(caseEntries: CaseEntry[]): string;

package/dist/runner/index.js

@@ -0,0 +1,220 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEngineBin = resolveEngineBin;
+exports.resolveEsbuildModule = resolveEsbuildModule;
+exports.buildExecEnv = buildExecEnv;
+exports.projectCasesToSpecs = projectCasesToSpecs;
+exports.buildCasesYaml = buildCasesYaml;
+/**
+ * runner — 平台任务执行的「纯函数」库面：bin 定位 / env 契约 / 用例投影
+ *
+ * 为什么单独拆出这一层：
+ *   run-dsl-task.mjs（cli 面，非交互批跑）和本地调试工具的交互模式（client 面，
+ *   cypress.open() / playwright --ui）需要跑出**完全一致**的 spec 脚本和环境变量，
+ *   否则同一条用例在两种模式下会有不同行为，调试时看到的和线上跑的不是一回事。
+ *
+ * 分层约定（见 autotest-core同步新执行链路技术方案.md 2.7 节）：
+ *   - suite（本文件）：只负责「给我 cases + env 描述，还你 spec 文件路径和 env 变量」，
+ *     零 spawn、零 process.exit、零文件系统之外的副作用。
+ *   - cli（run-dsl-task.mjs / 本地调试工具的 execution-adapter.js）：决定「谁来跑、
+ *     以什么方式跑（headless / 交互）」，调用本文件的函数拼出可执行动作。
+ *   - backend：只消费 cli 入口的输入输出契约（execution-input.json /
+ *     execution-result.json），不 import 本文件一个函数。
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const index_js_1 = require("../dsl/index.js");
+/**
+ * 按引擎解析可执行文件路径。
+ * 候选顺序：环境变量显式指定 → backendRoot/node_modules → suiteRoot/node_modules。
+ * 三种调用方（线上 runner / 本地调试 open 模式）共用同一份候选顺序，
+ * 避免「平台能跑、本地跑不起来」这类环境差异问题各自排查一遍。
+ */
+function resolveEngineBin({ engine, backendRoot, suiteRoot }) {
+    const envVar = engine === 'cypress'
+        ? process.env.KEVE_CYPRESS_BIN
+        : process.env.KEVE_PLAYWRIGHT_BIN;
+    const binName = engine === 'cypress' ? 'cypress' : 'playwright';
+    const candidates = [
+        envVar,
+        path.join(backendRoot, 'node_modules', '.bin', binName),
+        path.join(suiteRoot, 'node_modules', '.bin', binName),
+    ].filter(Boolean);
+    return candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0];
+}
+/** esbuild 模块路径解析，Cypress 预处理器依赖。候选顺序与 resolveEngineBin 一致。 */
+function resolveEsbuildModule(backendRoot, suiteRoot) {
+    const candidates = [
+        process.env.KEVE_ESBUILD_MODULE,
+        path.join(backendRoot, 'node_modules', 'esbuild', 'lib', 'main.js'),
+        path.join(suiteRoot, 'node_modules', 'esbuild', 'lib', 'main.js'),
+    ].filter(Boolean);
+    return candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0];
+}
+/**
+ * 两个引擎共用的 KEVE_* 环境变量契约。
+ * run（headless 批跑）和 open（交互调试）模式必须拼出完全一致的变量集，
+ * 否则同一份静态 cypress.config.mjs / playwright.config.mjs 在两种模式下读到不同的值。
+ */
+function buildExecEnv({ input, taskDir, round, engine, defaultBackendRoot, suiteRoot, }) {
+    const backendRoot = input.backendRoot || defaultBackendRoot;
+    return {
+        ...process.env,
+        KEVE_TASK_DIR: taskDir,
+        KEVE_RESULT_DIR: path.join(taskDir, 'reports', `round-${round}`),
+        KEVE_CASES_DIR: path.join(taskDir, 'cases'),
+        KEVE_ARTIFACT_BASE: taskDir,
+        KEVE_ROUND: String(round),
+        KEVE_ENV: input.env || 'test',
+        KEVE_TARGET_URL: input.targetUrl || '',
+        KEVE_STORAGE_STATE: path.join(taskDir, '.auth', 'storage-state.json'),
+        KEVE_SSO_COOKIES: input.ssoCookiesJson || '[]',
+        KEVE_IDENTITY_SSO_COOKIES: JSON.stringify(input.identitySsoCookies || {}),
+        KEVE_LLM_BASE_URL: input.llm?.baseUrl || process.env.KEVE_LLM_BASE_URL || '',
+        KEVE_LLM_MODEL_NAME: input.llm?.model || process.env.KEVE_LLM_MODEL_NAME || '',
+        KEVE_LLM_API_KEY: input.llm?.apiKey || process.env.KEVE_LLM_API_KEY || '',
+        KEVE_ENGINE: engine,
+        KEVE_ESBUILD_MODULE: resolveEsbuildModule(backendRoot, suiteRoot) || '',
+    };
+}
+/** 从账号信息里提取 toDecorator 需要的占位账号（不下发密码到脚本正文以外的位置） */
+function resolveAccount(accountInfo) {
+    const account = accountInfo?.accountInfo || accountInfo;
+    if (!account?.name)
+        return undefined;
+    return { name: String(account.name), password: String(account.password || '') };
+}
+/**
+ * 投影 DSL 步骤为报告 outline，语义与 toDecorator 的 keveGoal 参数保持一致。
+ * OPEN_PAGE 后紧跟的 WAIT_RESPONSE 会合并进同一个导航步骤，避免报告步骤数
+ * 与脚本实际 keveGoal 数不一致。
+ */
+function buildCaseSteps(dslList, ctx) {
+    const steps = [];
+    for (let i = 0; i < dslList.length; i++) {
+        const d = dslList[i];
+        const op = String(d?.operation || '');
+        if (op === 'OPEN_PAGE') {
+            let j = i + 1;
+            const gates = [];
+            while (j < dslList.length && String(dslList[j]?.operation || '') === 'WAIT_RESPONSE') {
+                gates.push(dslList[j++]);
+            }
+            if (gates.length) {
+                const gateTexts = gates.map((g) => String(g?.text || '')).filter(Boolean);
+                const gateExpects = gates
+                    .filter((g) => (g?.expectation || []).length > 0)
+                    .map((g) => (0, index_js_1.stepExpectedText)(g, ctx))
+                    .filter(Boolean);
+                steps.push({
+                    step: String(d?.text || 'OPEN_PAGE'),
+                    expected: [...gateTexts, ...gateExpects].filter(Boolean).join('；') || '打开目标页面并等待就绪响应',
+                });
+                i = j - 1;
+                continue;
+            }
+        }
+        const stepText = String(d?.text || op || '');
+        const expected = (0, index_js_1.stepExpectedText)(d, ctx);
+        if (!stepText)
+            continue;
+        steps.push({ step: stepText, expected });
+    }
+    return steps;
+}
+/**
+ * 逐条用例投影成装饰器脚本，落盘到 specDir，并返回报告索引（caseEntries）。
+ * run / open 两种模式共用同一份投影，脚本内容、步骤文案完全一致。
+ */
+function projectCasesToSpecs({ cases, engine, specDir, env, ssoInject = true, defaultAccountInfo, }) {
+    fs.mkdirSync(specDir, { recursive: true });
+    const importFrom = engine === 'cypress' ? '@kkeve/suite/engine-cypress' : '@kkeve/suite/keve-test';
+    const caseEntries = [];
+    for (const item of cases) {
+        const stepGroupId = Number(item.stepGroupId);
+        if (!Number.isFinite(stepGroupId)) {
+            throw new Error(`用例缺少合法 stepGroupId: ${JSON.stringify(item.stepGroupId)}`);
+        }
+        const dslList = Array.isArray(item.dslList) ? item.dslList : [];
+        if (!dslList.length) {
+            throw new Error(`用例 ${stepGroupId} 的 dslList 为空，拒绝生成空脚本`);
+        }
+        const account = resolveAccount(item.accountInfo || defaultAccountInfo);
+        const variableList = Array.isArray(item.variableList) ? item.variableList : [];
+        const renderCtx = { env, variableList, account };
+        const caseName = item.caseName || `用例 ${stepGroupId}`;
+        const code = (0, index_js_1.toDecorator)({
+            stepGroupId,
+            caseName,
+            dslList,
+            env,
+            variableList,
+            account,
+            ssoInject,
+            importFrom,
+        });
+        const fileName = `sg${stepGroupId}.spec.ts`;
+        fs.writeFileSync(path.join(specDir, fileName), code, 'utf-8');
+        caseEntries.push({
+            caseId: `S${stepGroupId}`,
+            stepGroupId,
+            caseName,
+            specFile: fileName,
+            stepCount: dslList.length,
+            steps: buildCaseSteps(dslList, renderCtx),
+        });
+    }
+    return caseEntries;
+}
+/** 供报告补全步骤文案的最小用例清单（cases/test-cases.yaml） */
+function buildCasesYaml(caseEntries) {
+    const lines = ['modules:', '  - name: plan', '    cases:'];
+    for (const entry of caseEntries) {
+        lines.push(`      - id: ${entry.caseId}`);
+        lines.push(`        title: ${JSON.stringify(entry.caseName)}`);
+        if (Array.isArray(entry.steps) && entry.steps.length) {
+            lines.push('        steps:');
+            for (const step of entry.steps) {
+                lines.push(`          - step: ${JSON.stringify(step.step || '')}`);
+                lines.push(`            expected: ${JSON.stringify(step.expected || '')}`);
+            }
+        }
+        else {
+            lines.push('        steps: []');
+        }
+    }
+    return lines.join('\n') + '\n';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kkeve/suite",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "description": "AI-powered full-stack test agent CLI - static analysis, unit test, component test, E2E test, execute, evaluate, and report",
   "license": "MIT",
   "bin": {
@@ -55,6 +55,10 @@
     "./spec/keve-read-doc": {
       "types": "./dist/spec/keve-read-doc.d.ts",
       "default": "./dist/spec/keve-read-doc.js"
+    },
+    "./runner": {
+      "types": "./dist/runner/index.d.ts",
+      "default": "./dist/runner/index.js"
     }
   },
   "files": [
@@ -91,4 +95,4 @@
     "tsx": "^4.19.0",
     "typescript": "^6.0.2"
   }
-}
+}

package/scripts/run-dsl-task.mjs

@@ -7,11 +7,21 @@
  *     并把已展开、已解析的 dslList 写进 execution-input.json；
  *   - 本 runner 只做「投影 → 落盘 → 执行 → 出报告」，不直连业务库。
  *
+ * 分层约定（详见 autotest-core同步新执行链路技术方案.md 2.7 节）：
+ *   - bin 解析 / env 契约 / DSL→spec 投影这三件「纯函数」逻辑统一在
+ *     @kkeve/suite/runner 导出，本文件只负责「调函数 + 决定怎么跑」。
+ *   - 本地调试工具（autotest-core）的交互模式（mode=open）调用同一套
+ *     @kkeve/suite/runner 函数，不再自行重写一份，避免 run / open 行为漂移。
+ *
  * 两个引擎共用同一份 @kkeve/suite 装饰器脚本与同一份 report-data.json 生成逻辑，
  * 因此 Cypress / Playwright 的报告结构完全一致。
  *
  * 用法：
- *   node run-dsl-task.mjs --input execution-input.json
+ *   node run-dsl-task.mjs --input execution-input.json [--mode=run|open]
+ *
+ * mode=run（默认）：无头批跑，产出 execution-result.json / manifest.json / report-data.json。
+ * mode=open：交互调试。只做「投影 → 落盘 → 拉起 cypress.open() / playwright --ui」，
+ *   不等待测试结果；进程生命周期（杀旧进程、串行队列等）由调用方（本地调试工具）管理。
  *
  * 输出：
  *   <taskRoot>/runs/execution-result.json（执行摘要，供 backend 回写任务终态）
@@ -30,7 +40,13 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as url from 'node:url';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import {
+  resolveEngineBin,
+  buildExecEnv as buildExecEnvFromSuite,
+  projectCasesToSpecs,
+  buildCasesYaml,
+} from '../dist/runner/index.js';
 
 const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
 const suiteRoot = path.resolve(__dirname, '..');
@@ -43,33 +59,6 @@ const runtimeDir = path.join(__dirname, 'runtime');
  */
 const defaultBackendRoot = path.resolve(suiteRoot, '..', '..', '..', 'eve-backend');
 
-function resolveCypressBin(backendRoot) {
-  const candidates = [
-    process.env.KEVE_CYPRESS_BIN,
-    path.join(backendRoot, 'node_modules', '.bin', 'cypress'),
-    path.join(suiteRoot, 'node_modules', '.bin', 'cypress'),
-  ].filter(Boolean);
-  return candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0];
-}
-
-function resolveEsbuildModule(backendRoot) {
-  const candidates = [
-    process.env.KEVE_ESBUILD_MODULE,
-    path.join(backendRoot, 'node_modules', 'esbuild', 'lib', 'main.js'),
-    path.join(suiteRoot, 'node_modules', 'esbuild', 'lib', 'main.js'),
-  ].filter(Boolean);
-  return candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0];
-}
-
-function resolvePlaywrightBin(backendRoot) {
-  const candidates = [
-    process.env.KEVE_PLAYWRIGHT_BIN,
-    path.join(backendRoot, 'node_modules', '.bin', 'playwright'),
-    path.join(suiteRoot, 'node_modules', '.bin', 'playwright'),
-  ].filter(Boolean);
-  return candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0];
-}
-
 function parseArgs(argv) {
   const args = {};
   for (let i = 0; i < argv.length; i++) {
@@ -130,58 +119,10 @@ function normalizeStep(step) {
   };
 }
 
-/**
- * 投影 DSL 步骤为报告 outline，语义与 toDecorator 的 keveGoal 参数保持一致。
- * OPEN_PAGE 后紧跟的 WAIT_RESPONSE 会合并进同一个导航步骤，避免报告步骤数
- * 与脚本实际 keveGoal 数不一致。
- *
- * expected 文案统一走 stepExpectedText（与脚本投影同一个函数）：报告里展示的
- * 预期与评测 Agent 读到的预期必须逐字一致，否则平台标签（「报错4」）会在报告
- * 与评测两侧产生不同解读。
- */
-function buildCaseSteps(dslList, ctx, stepExpectedText) {
-  const steps = [];
-  for (let i = 0; i < dslList.length; i++) {
-    const d = dslList[i];
-    const op = String(d?.operation || '');
-    if (op === 'OPEN_PAGE') {
-      let j = i + 1;
-      const gates = [];
-      while (j < dslList.length && String(dslList[j]?.operation || '') === 'WAIT_RESPONSE') {
-        gates.push(dslList[j++]);
-      }
-      if (gates.length) {
-        const gateTexts = gates.map((g) => String(g?.text || '')).filter(Boolean);
-        const gateExpects = gates
-          .filter((g) => (g?.expectation || []).length > 0)
-          .map((g) => stepExpectedText(g, ctx))
-          .filter(Boolean);
-        steps.push({
-          step: String(d?.text || 'OPEN_PAGE'),
-          expected: [...gateTexts, ...gateExpects].filter(Boolean).join('；') || '打开目标页面并等待就绪响应',
-        });
-        i = j - 1;
-        continue;
-      }
-    }
-    const stepText = String(d?.text || op || '');
-    const expected = stepExpectedText(d, ctx);
-    if (!stepText) continue;
-    steps.push({ step: stepText, expected });
-  }
-  return steps;
-}
-
-/** 从账号信息里提取 toDecorator 需要的占位账号（不下发密码到脚本正文以外的位置） */
-function resolveAccount(accountInfo) {
-  const account = accountInfo?.accountInfo || accountInfo;
-  if (!account?.name) return undefined;
-  return { name: String(account.name), password: String(account.password || '') };
-}
-
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (!args.input) fail('缺少 --input <execution-input.json>');
+  const mode = args.mode === 'open' ? 'open' : 'run';
 
   const inputFile = path.resolve(args.input);
   const input = readJson(inputFile, '执行输入');
@@ -221,51 +162,22 @@ async function main() {
   fs.rmSync(resultFile, { force: true });
   fs.rmSync(manifestFile, { force: true });
 
-  const { toDecorator, stepExpectedText } = await import(
-    url.pathToFileURL(path.join(suiteRoot, 'dist/dsl/index.js')).href
-  );
-
-  // ── 逐条用例投影成装饰器脚本 ──
-  const caseEntries = [];
-  for (const item of cases) {
-    const stepGroupId = Number(item.stepGroupId);
-    if (!Number.isFinite(stepGroupId)) fail(`用例缺少合法 stepGroupId: ${JSON.stringify(item.stepGroupId)}`);
-    const rawList = Array.isArray(item.dslList) ? item.dslList : [];
-    if (!rawList.length) fail(`用例 ${stepGroupId} 的 dslList 为空，拒绝生成空脚本`);
-
-    const dslList = rawList.map(normalizeStep);
-    const importFrom = engine === 'cypress'
-      ? '@kkeve/suite/engine-cypress'
-      : '@kkeve/suite/keve-test';
-    const account = resolveAccount(item.accountInfo || input.accountInfo);
-    const renderCtx = {
-      env: input.env || 'test',
-      variableList: Array.isArray(item.variableList) ? item.variableList : [],
-      account,
-    };
-    const code = toDecorator({
-      stepGroupId,
-      caseName: item.caseName || `用例 ${stepGroupId}`,
-      dslList,
-      env: renderCtx.env,
-      variableList: renderCtx.variableList,
-      account: renderCtx.account,
-      ssoInject: input.ssoInject !== false,
-      importFrom,
-    });
-
-    const fileName = `sg${stepGroupId}.spec.ts`;
-    fs.writeFileSync(path.join(specDir, fileName), code, 'utf-8');
-    const dslSteps = buildCaseSteps(dslList, renderCtx, stepExpectedText);
-    caseEntries.push({
-      caseId: `S${stepGroupId}`,
-      stepGroupId,
-      caseName: item.caseName || `用例 ${stepGroupId}`,
-      specFile: fileName,
-      stepCount: dslList.length,
-      steps: dslSteps,
-    });
-    console.log(`[run-dsl-task] 生成脚本 ${fileName}（${dslList.length} 步）`);
+  // ── 逐条用例投影成装饰器脚本（run / open 两种模式共用同一份实现） ──
+  const normalizedCases = cases.map((item) => ({
+    ...item,
+    stepGroupId: Number(item.stepGroupId),
+    dslList: (Array.isArray(item.dslList) ? item.dslList : []).map(normalizeStep),
+  }));
+  const caseEntries = projectCasesToSpecs({
+    cases: normalizedCases,
+    engine,
+    specDir,
+    env: input.env || 'test',
+    ssoInject: input.ssoInject !== false,
+    defaultAccountInfo: input.accountInfo,
+  });
+  for (const entry of caseEntries) {
+    console.log(`[run-dsl-task] 生成脚本 ${entry.specFile}（${entry.stepCount} 步）`);
   }
 
   // ── 用例定义写入 cases/test-cases.yaml，让报告能补全步骤文案 ──
@@ -277,6 +189,14 @@ async function main() {
     'utf-8',
   );
 
+  if (mode === 'open') {
+    // 交互调试：只负责「投影 + 拉起交互入口」，不等待退出、不写执行结果。
+    // 进程生命周期（杀旧进程、串行排队、端口探测）留给调用方（本地调试工具）管理，
+    // 这是宿主（Electron/CLI）的关注点，不属于本 runner 的职责。
+    await openInteractive({ engine, input, taskRoot, specDir, resultDir, round });
+    return;
+  }
+
   // ── 执行 ──
   const runner = engine === 'cypress' ? runCypress : runPlaywright;
   const exitCode = runner({ input, taskDir: taskRoot, specDir, resultDir, round });
@@ -333,6 +253,50 @@ async function main() {
   process.exit(result.ok ? 0 : 1);
 }
 
+/**
+ * mode=open：拉起交互入口（cypress.open() / playwright test --ui）。
+ * env 契约与 run 模式完全一致（见 buildExecEnv），因此同一份 cypress.config.mjs /
+ * playwright.config.mjs 在两种模式下行为一致。本函数只负责「拉起」，不管进程生命周期：
+ * cypress.open() 阻塞到窗口关闭；playwright --ui 常驻进程交由调用方 detach + 管理。
+ */
+async function openInteractive({ engine, input, taskRoot, specDir, resultDir, round }) {
+  fs.mkdirSync(resultDir, { recursive: true });
+  const execEnv = buildExecEnvFromSuite({
+    input, taskDir: taskRoot, round, engine, defaultBackendRoot, suiteRoot,
+  });
+
+  if (engine === 'playwright') {
+    const configPath = path.join(runtimeDir, 'playwright.config.mjs');
+    const backendRoot = input.backendRoot || defaultBackendRoot;
+    const cli = resolveEngineBin({ engine: 'playwright', backendRoot, suiteRoot });
+    if (!cli || !fs.existsSync(cli)) fail('找不到 Playwright 可执行文件，请设置 KEVE_PLAYWRIGHT_BIN');
+    const child = spawn(cli, ['test', '--ui', '--config', configPath], {
+      cwd: taskRoot,
+      env: execEnv,
+      detached: true,
+      stdio: 'inherit',
+    });
+    child.unref();
+    console.log(`[run-dsl-task] Playwright UI 已拉起（pid=${child.pid}）`);
+    return;
+  }
+
+  const configPath = path.join(runtimeDir, 'cypress.config.mjs');
+  const backendRoot = input.backendRoot || defaultBackendRoot;
+  const cypressBin = resolveEngineBin({ engine: 'cypress', backendRoot, suiteRoot });
+  if (!cypressBin || !fs.existsSync(cypressBin)) fail('找不到 Cypress 可执行文件，请设置 KEVE_CYPRESS_BIN');
+  // cypress open 阻塞到窗口关闭才返回，和线上无头跑一致地走同一个 CLI 可执行文件。
+  spawnSync(cypressBin, [
+    'open',
+    '--project', taskRoot,
+    '--config-file', configPath,
+  ], {
+    cwd: taskRoot,
+    stdio: 'inherit',
+    env: { ...execEnv, ELECTRON_RUN_AS_NODE: '' },
+  });
+}
+
 /** reports/latest 软链指向最新轮次，便于 backend 按任务读取最近一次报告 */
 function updateLatestLink(reportsDir, resultDir) {
   const latestDir = path.join(reportsDir, 'latest');
@@ -389,25 +353,6 @@ function writeManifest({ manifestFile, taskRoot, taskId, engine, casePath, round
   return manifest;
 }
 
-/** 供报告补全步骤文案的最小用例清单 */
-function buildCasesYaml(caseEntries) {
-  const lines = ['modules:', '  - name: plan', '    cases:'];
-  for (const entry of caseEntries) {
-    lines.push(`      - id: ${entry.caseId}`);
-    lines.push(`        title: ${JSON.stringify(entry.caseName)}`);
-    if (Array.isArray(entry.steps) && entry.steps.length) {
-      lines.push('        steps:');
-      for (const step of entry.steps) {
-        lines.push(`          - step: ${JSON.stringify(step.step || '')}`);
-        lines.push(`            expected: ${JSON.stringify(step.expected || '')}`);
-      }
-    } else {
-      lines.push('        steps: []');
-    }
-  }
-  return lines.join('\n') + '\n';
-}
-
 function readReportData(resultDir) {
   const file = path.join(resultDir, 'report-data.json');
   if (!fs.existsSync(file)) return null;
@@ -578,12 +523,12 @@ function summarizeReport(reportData) {
 function runPlaywright({ input, taskDir, specDir, resultDir, round }) {
   const configPath = path.join(runtimeDir, 'playwright.config.mjs');
   const backendRoot = input.backendRoot || defaultBackendRoot;
-  const cli = resolvePlaywrightBin(backendRoot);
+  const cli = resolveEngineBin({ engine: 'playwright', backendRoot, suiteRoot });
   if (!cli || !fs.existsSync(cli)) fail('找不到 Playwright 可执行文件，请设置 KEVE_PLAYWRIGHT_BIN');
   const result = spawnSync(cli, ['test', '--config', configPath], {
     cwd: taskDir,
     stdio: 'inherit',
-    env: buildExecEnv({ input, taskDir, round, engine: 'playwright' }),
+    env: buildExecEnvFromSuite({ input, taskDir, round, engine: 'playwright', defaultBackendRoot, suiteRoot }),
   });
   if (result.error) fail(`Playwright 启动失败: ${result.error.message}`);
   return result.status ?? 1;
@@ -596,7 +541,7 @@ function useCypressConfig({ taskDir, specDir, resultDir }) {
 function runCypress({ input, taskDir, specDir, resultDir, round }) {
   const configPath = useCypressConfig({ taskDir, specDir, resultDir });
   const backendRoot = input.backendRoot || defaultBackendRoot;
-  const cypressBin = resolveCypressBin(backendRoot);
+  const cypressBin = resolveEngineBin({ engine: 'cypress', backendRoot, suiteRoot });
   if (!cypressBin || !fs.existsSync(cypressBin)) {
     fail('找不到 Cypress 可执行文件，请设置 KEVE_CYPRESS_BIN');
   }
@@ -609,7 +554,7 @@ function runCypress({ input, taskDir, specDir, resultDir, round }) {
     cwd: taskDir,
     stdio: 'inherit',
     env: {
-      ...buildExecEnv({ input, taskDir, round, engine: 'cypress' }),
+      ...buildExecEnvFromSuite({ input, taskDir, round, engine: 'cypress', defaultBackendRoot, suiteRoot }),
       // Cypress 内部会 fork Electron；清空该变量避免以纯 Node 模式启动
       ELECTRON_RUN_AS_NODE: '',
     },
@@ -618,31 +563,6 @@ function runCypress({ input, taskDir, specDir, resultDir, round }) {
   return result.status ?? 1;
 }
 
-/** 两个引擎共用同一套环境变量契约 */
-function buildExecEnv({ input, taskDir, round, engine }) {
-  const backendRoot = input.backendRoot || defaultBackendRoot;
-  return {
-    ...process.env,
-    KEVE_TASK_DIR: taskDir,
-    KEVE_RESULT_DIR: path.join(taskDir, 'reports', `round-${round}`),
-    KEVE_CASES_DIR: path.join(taskDir, 'cases'),
-    // 媒体相对路径以任务根为基准，保证 report-data.json 里不出现 `..`
-    KEVE_ARTIFACT_BASE: taskDir,
-    KEVE_ROUND: round,
-    KEVE_ENV: input.env || 'test',
-    KEVE_TARGET_URL: input.targetUrl || '',
-    KEVE_STORAGE_STATE: path.join(taskDir, '.auth', 'storage-state.json'),
-    KEVE_SSO_COOKIES: input.ssoCookiesJson || '[]',
-    KEVE_IDENTITY_SSO_COOKIES: JSON.stringify(input.identitySsoCookies || {}),
-    KEVE_LLM_BASE_URL: input.llm?.baseUrl || process.env.KEVE_LLM_BASE_URL || '',
-    KEVE_LLM_MODEL_NAME: input.llm?.model || process.env.KEVE_LLM_MODEL_NAME || '',
-    KEVE_LLM_API_KEY: input.llm?.apiKey || process.env.KEVE_LLM_API_KEY || '',
-    KEVE_ENGINE: engine,
-    // Cypress 预处理器位于 suite 静态配置目录，esbuild 需由 backend 提供
-    KEVE_ESBUILD_MODULE: resolveEsbuildModule(backendRoot),
-  };
-}
-
 export {
   deriveTargetUrl,
   isLocalPlaceholderUrl,

package/scripts/runtime/cypress.config.mjs

@@ -17,6 +17,8 @@ const resultDir = process.env.KEVE_RESULT_DIR || path.join(taskDir, 'reports', '
 const targetUrl = process.env.KEVE_TARGET_URL || '';
 
 export default {
+  viewportWidth: 2560,
+  viewportHeight: 1440,
   e2e: {
     ...(targetUrl ? { baseUrl: targetUrl } : {}),
     specPattern: 'specs/**/*.spec.ts',

package/scripts/runtime/playwright.config.mjs

@@ -32,6 +32,7 @@ export default defineConfig({
   use: {
     baseURL: process.env.KEVE_TARGET_URL || '',
     storageState: process.env.KEVE_STORAGE_STATE,
+    viewport: { width: 2560, height: 1440 },
     trace: 'off',
     screenshot: 'off',
     video: 'on',