@kkeve/suite 0.0.18 → 0.0.20

package/dist/dsl/index.d.ts

@@ -9,7 +9,7 @@
  * 分层：DB 装载 / 内嵌场景展开 / 元素库 source 跳解析 / 变量表查询全部留在
  * 调用方（见 eve-backend 的 dslLoader）。这里只做纯函数投影。
  */
-export { toDecorator, type DslHop, type DslValue, type DslExpectation, type DslStep, type DslVariableRow, type ToDecoratorOptions, } from './toDecorator.js';
+export { toDecorator, stepExpectedText, type DslHop, type DslValue, type DslExpectation, type DslStep, type DslVariableRow, type ExpectedRenderContext, type ToDecoratorOptions, } from './toDecorator.js';
 /** 语义别名：调用方按「生成一份装饰器 spec」的语义引用时更直观 */
 export { toDecorator as generateDecoratorSpec } from './toDecorator.js';
 export { STEP_OPERATIONS, ASSERT_OPERATIONS, TEXT_ONLY_ASSERT_OPERATIONS, EXPECTED_VALUE_CTYPES, COMPARISON_EXPRESSIONS, isKnownOperation, isKnownAssert, isTextOnlyAssert, parseComparison, type StepOperation, } from './ops.js';

package/dist/dsl/index.js

@@ -11,9 +11,10 @@
  * 调用方（见 eve-backend 的 dslLoader）。这里只做纯函数投影。
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseComparison = exports.isTextOnlyAssert = exports.isKnownAssert = exports.isKnownOperation = exports.COMPARISON_EXPRESSIONS = exports.EXPECTED_VALUE_CTYPES = exports.TEXT_ONLY_ASSERT_OPERATIONS = exports.ASSERT_OPERATIONS = exports.STEP_OPERATIONS = exports.generateDecoratorSpec = exports.toDecorator = void 0;
+exports.parseComparison = exports.isTextOnlyAssert = exports.isKnownAssert = exports.isKnownOperation = exports.COMPARISON_EXPRESSIONS = exports.EXPECTED_VALUE_CTYPES = exports.TEXT_ONLY_ASSERT_OPERATIONS = exports.ASSERT_OPERATIONS = exports.STEP_OPERATIONS = exports.generateDecoratorSpec = exports.stepExpectedText = exports.toDecorator = void 0;
 var toDecorator_js_1 = require("./toDecorator.js");
 Object.defineProperty(exports, "toDecorator", { enumerable: true, get: function () { return toDecorator_js_1.toDecorator; } });
+Object.defineProperty(exports, "stepExpectedText", { enumerable: true, get: function () { return toDecorator_js_1.stepExpectedText; } });
 /** 语义别名：调用方按「生成一份装饰器 spec」的语义引用时更直观 */
 var toDecorator_js_2 = require("./toDecorator.js");
 Object.defineProperty(exports, "generateDecoratorSpec", { enumerable: true, get: function () { return toDecorator_js_2.toDecorator; } });

package/dist/dsl/toDecorator.d.ts

@@ -96,3 +96,20 @@ export interface ToDecoratorOptions {
 }
 /** 生成装饰器脚本源码（UTF-8 文本） */
 export declare function toDecorator(options: ToDecoratorOptions): string;
+/** 计算 expected 文案所需的最小上下文（与脚本投影共用，保证报告与脚本同文案） */
+export interface ExpectedRenderContext {
+    env: string;
+    variableList?: DslVariableRow[];
+    account?: {
+        name: string;
+        password: string;
+    };
+}
+/**
+ * 步骤 expected 文案的**公开**入口。
+ *
+ * 投影脚本（toDecorator）与报告 outline（run-dsl-task / report-data）必须产出
+ * 同一份文案，否则会出现「报告的预期」与「评测 Agent 看到的预期」不一致 ——
+ * 那正是「报错4」这类标签被当成字面量去页面搜索的根因。调用方统一走这里。
+ */
+export declare function stepExpectedText(step: DslStep, ctx: ExpectedRenderContext): string;

package/dist/dsl/toDecorator.js

@@ -21,6 +21,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toDecorator = toDecorator;
+exports.stepExpectedText = stepExpectedText;
 const ops_js_1 = require("./ops.js");
 // ─── 生成入口 ────────────────────────────────────────────────────────
 /** 生成装饰器脚本源码（UTF-8 文本） */
@@ -96,8 +97,7 @@ function renderStep(d, ctx) {
     }
     const out = [];
     const stepText = String(d.text || op);
-    const expTexts = (d.expectation || []).map((e) => String(e.text || '')).filter(Boolean);
-    const expected = expTexts.length ? expTexts.join('；') : '操作完成，页面正常响应';
+    const expected = expectedTextOf(d.expectation || [], (e) => resolveExpectationValue(e, ctx));
     const chain = chainExpr(d.context);
     const expLines = [];
     for (const e of d.expectation || []) {
@@ -275,7 +275,8 @@ function renderOpenPageWithGates(d, gates, ctx) {
     const stepText = String(d.text || 'OPEN_PAGE');
     const gateTexts = gates.map((g) => String(g.text || '')).filter(Boolean);
     const gateExpects = gates
-        .flatMap((g) => (g.expectation || []).map((e) => String(e.text || '')))
+        .filter((g) => (g.expectation || []).length > 0)
+        .map((g) => expectedTextOf(g.expectation || [], (e) => resolveExpectationValue(e, ctx)))
         .filter(Boolean);
     const expected = [...gateTexts, ...gateExpects].filter(Boolean).join('；') || '打开目标页面并等待就绪响应';
     const resolved = resolveOpenPage(d, ctx);
@@ -305,8 +306,137 @@ function renderOpenPageWithGates(d, gates, ctx) {
     out.push(`});`);
     return out;
 }
-// ─── 断言转译 ────────────────────────────────────────────────────────
-/** 渲染一条 expectation；返回 null 表示「纯文案载体，不产生断言」 */
+/**
+ * 步骤 expected 文案的**公开**入口。
+ *
+ * 投影脚本（toDecorator）与报告 outline（run-dsl-task / report-data）必须产出
+ * 同一份文案，否则会出现「报告的预期」与「评测 Agent 看到的预期」不一致 ——
+ * 那正是「报错4」这类标签被当成字面量去页面搜索的根因。调用方统一走这里。
+ */
+function stepExpectedText(step, ctx) {
+    const renderCtx = {
+        env: ctx.env,
+        variableList: ctx.variableList || [],
+        account: ctx.account,
+    };
+    return expectedTextOf(step.expectation || [], (e) => resolveExpectationValue(e, renderCtx));
+}
+/**
+ * 步骤的 expected 文案 —— 喂给评测 Agent 判断「预期是否真的达成」。
+ *
+ * 平台 expectation[].text 常常只是录制期标签（「报错1」「报错4」），不携带
+ * 任何可判定语义；真实预期藏在同一条 expectation 的 type + value + context 里
+ * （如 ELEMENT_NOT_EXIST + includes「业务逻辑错误」= 页面不应出现该错误）。
+ * 只把标签交给评测 Agent，它会去页面上找字面量「报错4」并据此误判失败。
+ *
+ * 因此按「可执行断言语义优先、标签作为备注」组装：
+ *   - 有可执行断言 → 渲染成人话（页面不存在包含「业务逻辑错误」的内容）；
+ *   - 纯文案载体（TEXT / 无 type）→ 标签本身就是人话，直接采用；
+ *   - 一个断言都渲染不出来时，退回平台标签，最后兜底为通用文案。
+ */
+function expectedTextOf(expectations, resolveValue) {
+    const semantic = [];
+    const labelOnly = [];
+    for (const e of expectations) {
+        const label = String(e.text || '').trim();
+        const type = String(e.type || '');
+        if (!type || (0, ops_js_1.isTextOnlyAssert)(type)) {
+            if (label)
+                labelOnly.push(label);
+            continue;
+        }
+        const phrase = describeExpectation(e, resolveValue(e));
+        // 未知断言在 renderExpectation 里会确定性报错；这里不能让 expected 抢先崩，
+        // 退化成标签即可，真正的失败由断言渲染抛出。
+        if (phrase)
+            semantic.push(label && !phrase.includes(label) ? `${phrase}（${label}）` : phrase);
+        else if (label)
+            labelOnly.push(label);
+    }
+    const parts = [...semantic, ...labelOnly].filter(Boolean);
+    return parts.length ? parts.join('；') : '操作完成，页面正常响应';
+}
+/** 单条可执行断言 → 人类可读预期；返回 null 表示无法给出语义（由调用方兜底） */
+function describeExpectation(e, val) {
+    const type = String(e.type || '');
+    const target = describeChain(e.context);
+    const value = String(val ?? '');
+    switch (type) {
+        case 'ELEMENT_EXIST':
+            return `页面存在${target}`;
+        case 'ELEMENT_NOT_EXIST':
+            return `页面不存在${target}`;
+        case 'ELEMENT_VISIBLE':
+            return `${target}可见`;
+        case 'ELEMENT_NOT_VISIBLE':
+            return `${target}不可见`;
+        case 'TEXT_EXIST':
+            if (isPageTitleAssertion(e))
+                return `页面标题包含「${value}」`;
+            return `页面存在包含「${value}」的内容${target}`;
+        case 'TEXT_NOT_EXIST':
+            if (!value.trim())
+                return null;
+            return `页面不存在包含「${value}」的内容${target}`;
+        case 'TEXT_EQUAL':
+            return `元素${target}文本等于「${value}」`;
+        case 'EXPECTED_VALUE': {
+            const ctype = String(e.ctype || 'text').toLowerCase();
+            const { mode, negated } = (0, ops_js_1.parseComparison)(String(e.cexpression || 'include'));
+            const dim = { text: '文本', class: '类名', placeholder: '占位提示', style: '样式', index: '元素个数' }[ctype] || ctype;
+            if (ctype === 'index')
+                return `元素${target}个数等于 ${value}`;
+            const op = mode === 'eq' ? (negated ? '不等于' : '等于') : (negated ? '不包含' : '包含');
+            return `元素${target}的${dim}${op}「${value}」`;
+        }
+        case 'EXPECTED__PAGET_VALUE': {
+            const ctype = String(e.ctype || 'url').toLowerCase();
+            const { mode, negated } = (0, ops_js_1.parseComparison)(String(e.cexpression || 'eq'));
+            const dim = ctype === 'title' ? '标题' : '地址';
+            const op = mode === 'eq' ? (negated ? '不等于' : '等于') : (negated ? '不包含' : '包含');
+            return `页面${dim}${op}「${value}」`;
+        }
+        case 'SCREEN_SHOT_COMPARE':
+        case 'SCREENSHOT_COMPARE':
+        case 'IMAGE_COMPARE':
+            return `页面截图与基线「${value || e.text || ''}」一致`;
+        default:
+            return null;
+    }
+}
+/** 定位链 → 人类可读描述（评测 Agent 据此知道「在哪个区域」观察） */
+function describeChain(context) {
+    let hops;
+    try {
+        hops = collectHops(context);
+    }
+    catch {
+        return '';
+    }
+    if (!hops.length)
+        return '';
+    // 单跳文本包含：平台最常见的「页面不应出现某文案」录制形态
+    if (hops.length === 1 && (hops[0].type === 'includes' || hops[0].type === 'text')) {
+        return `包含「${hops[0].value.trim()}」的元素`;
+    }
+    const parts = hops.map((h) => {
+        const text = h.value.trim();
+        if (h.type === 'includes' || h.type === 'text')
+            return `包含「${text}」`;
+        if (h.type === 'selector')
+            return `选择器「${text}」`;
+        return `${h.type}=「${text}」`;
+    });
+    return `（${parts.join(' → ')}）`;
+}
+/**
+ * 渲染一条 expectation 为 engine 断言；返回 null 表示「纯文案载体，不产生断言」。
+ *
+ * 注意投影脚本**不输出 `react: false`**：可执行断言只证明预期的一个子集，
+ * fn 执行成功不等于 expected 已达成，所以每个 goal 都保留评测阶段 —— Agent
+ * 先观察真实页面评测，达成即放行，未达成再继续探索；断言失败由引擎侧统一
+ * 参与终局覆盖，不允许被评审判成 pass。
+ */
 function renderExpectation(e, ctx) {
     const type = String(e.type || '');
     // 无 type / TEXT：纯「期望文案」载体，只喂 keveGoal.expected，不是断言

package/dist/engine-cypress/adapter.d.ts

@@ -15,7 +15,9 @@ import type { Cdp } from './cdp.js';
 import { type CyShotDiffResult } from './shotBuffer.js';
 /** 浏览器 → Node 的调用封装（端口来自 config.env.KEVE_BRIDGE_PORT） */
 export interface Bridge {
-    post(route: string, payload?: Record<string, unknown>): Promise<any>;
+    post(route: string, payload?: Record<string, unknown>, opts?: {
+        signal?: AbortSignal;
+    }): Promise<any>;
 }
 export declare function createBridge(): Bridge;
 declare function escapeRegExp(s: string): string;

package/dist/engine-cypress/adapter.js

@@ -56,11 +56,14 @@ function createBridge() {
         throw new Error('[cypress-engine] KEVE_BRIDGE_PORT 未注入：请确认 cypress.config 使用了 @kkeve/suite/engine-cypress 的 setupKeveBridge');
     const base = `http://127.0.0.1:${port}`;
     return {
-        async post(route, payload = {}) {
+        async post(route, payload = {}, opts = {}) {
             const res = await fetch(base + route, {
                 method: 'POST',
                 headers: { 'content-type': 'application/json' },
                 body: JSON.stringify(payload),
+                // 透传中止信号：goal 超时后必须能中断本次桥调用，否则浏览器侧会一直
+                // 等一个已经在 Agent 层判定为超时的响应。
+                signal: opts.signal,
             });
             return await res.json();
         },

package/dist/engine-cypress/bridge.js

@@ -302,7 +302,7 @@ async function setupKeveBridge(on, config) {
         }
         return { ok: true, resultsPath, reportDataPath, cases: reportData?.summary?.total ?? undefined };
     };
-    const handle = async (route, payload) => {
+    const handle = async (route, payload, signal) => {
         switch (route) {
             case '/echo':
                 return { ok: true, echoed: payload, at: Date.now() };
@@ -355,6 +355,9 @@ async function setupKeveBridge(on, config) {
                         method: String(payload.method || 'POST'),
                         headers: reqHeaders,
                         body: typeof payload.body === 'string' ? payload.body : JSON.stringify(payload.body ?? {}),
+                        // 浏览器侧 goal 超时 / 主动中止后，Node 侧必须同步停止在途 LLM 请求，
+                        // 否则桥会一直挂着一个上游连接，子进程无法及时收敛。
+                        signal,
                     });
                     const body = await resp.text();
                     const headers = {};
@@ -454,6 +457,17 @@ async function setupKeveBridge(on, config) {
         const chunks = [];
         req.on('data', (c) => chunks.push(c));
         req.on('end', async () => {
+            const controller = new AbortController();
+            const llmTimeoutMs = Number(process.env.KEVE_LLM_REQUEST_TIMEOUT_MS) > 0
+                ? Number(process.env.KEVE_LLM_REQUEST_TIMEOUT_MS)
+                : 300_000;
+            const timeout = setTimeout(() => controller.abort(), llmTimeoutMs);
+            // 浏览器侧 fetch 被 AbortSignal 中止时会断开连接，这里同步中止下游请求。
+            req.on('aborted', () => controller.abort());
+            res.on('close', () => {
+                if (!res.writableEnded)
+                    controller.abort();
+            });
             const route = String(req.url || '').split('?')[0];
             let payload = {};
             try {
@@ -465,16 +479,23 @@ async function setupKeveBridge(on, config) {
             }
             let out;
             try {
-                out = await handle(route, payload);
+                out = await handle(route, payload, controller.signal);
             }
             catch (err) {
                 out = { ok: false, error: err?.message || String(err) };
             }
-            res.writeHead(200, {
-                'content-type': 'application/json',
-                ...corsHeaders,
-            });
-            res.end(JSON.stringify(out));
+            finally {
+                clearTimeout(timeout);
+            }
+            // 客户端在等待期间主动断开（goal 超时 / 用例中止）时响应流可能已销毁，
+            // 此时再写回会抛 ERR_STREAM_WRITE_AFTER_END，把一个正常的中止变成噪声错误。
+            if (!res.writableEnded && !res.destroyed) {
+                res.writeHead(200, {
+                    'content-type': 'application/json',
+                    ...corsHeaders,
+                });
+                res.end(JSON.stringify(out));
+            }
         });
     });
     await new Promise((resolve, reject) => {

package/dist/engine-cypress/host.js

@@ -125,7 +125,7 @@ function readBrowserEnv(name) {
  *   - 读初始截图  → `/fs/read-binary`
  *   - LLM 调用    → `/llm/chat`（apiKey 不出 Node）
  */
-function createCyAgentHost(bridge) {
+function createCyAgentHost(bridge, signal) {
     const targetUrl = readBrowserEnv('KEVE_TARGET_URL') || resolveBaseUrl();
     const getEnv = (name) => {
         const direct = readBrowserEnv(name);
@@ -147,7 +147,7 @@ function createCyAgentHost(bridge) {
         const resp = await bridge.post('/shot/save', {
             name: `agent-step${stepIndex}-${safeName}`,
             pngBase64,
-        });
+        }, { signal });
         return resp?.ok ? String(resp.path || '') || undefined : undefined;
     };
     const loadInitialImages = async (paths) => {
@@ -159,7 +159,7 @@ function createCyAgentHost(bridge) {
             if (!rel)
                 continue;
             try {
-                const resp = await bridge.post('/fs/read-binary', { file: rel });
+                const resp = await bridge.post('/fs/read-binary', { file: rel }, { signal });
                 if (!resp?.ok || !resp.base64)
                     continue;
                 items.push({ type: 'text', text: `Screenshot (${label}):` });
@@ -186,7 +186,7 @@ function createCyAgentHost(bridge) {
             method: String(init?.method || 'POST'),
             headers,
             body: typeof init?.body === 'string' ? init.body : JSON.stringify(init?.body ?? {}),
-        });
+        }, { signal });
         if (!resp?.ok)
             throw new Error(resp?.error || 'llm/chat 桥调用失败');
         return new Response(String(resp.body ?? ''), {
@@ -215,11 +215,11 @@ function createCyAgentHost(bridge) {
  */
 function installGoalExplorer(engine, bridge) {
     const cdp = engine.rawPage();
-    const host = createCyAgentHost(bridge);
     (0, keveGoal_js_1.setCyGoalExplorer)(async (options, ctx) => {
         const page = new agent_page_js_1.CyAgentPage(cdp);
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), CY_GOAL_TIMEOUT_MS);
+        const host = createCyAgentHost(bridge, controller.signal);
         try {
             const result = await (0, agent_js_1.reactLoop)(page, options.step, options.expected, {
                 specFilePath: ctx.specFilePath,

package/dist/engine-cypress/keveGoal.js

@@ -140,10 +140,11 @@ function createCyKeveGoal(engine) {
             console.log(`[keveGoal] 📊 "${options.step}" 截图差异超阈值 — 确定性失败`);
         }
         else {
-            // fn 成功 / 失败都交给探索器（若引擎入口注册了 AI Re-Act）。
-            // fn 只是前置确定性校验，@keveGoal 的预期是否真正达成必须由 Agent
-            // 观察真实页面后给出最终结论 —— 即便 fn 已通过，也要产出推理轨迹与
-            // 执行后截图，否则报告里会缺少 AI 推理日志。
+            // fn 成功 / 失败都交给评测器。fn 只是前置动作与确定性校验：
+            //  - fn 成功 ≠ expected 达成（fn 可能只覆盖预期的一个子集）；
+            //  - fn 失败 ≠ 不可恢复（普通运行时错误下页面可能仍可探索自愈）。
+            // 「先评测、再决定放行还是探索」由这一轮承担：Agent 先观察真实页面评测
+            // expected，达成即 done(pass) 放行，未达成再继续探索。
             let explored;
             if (explorer) {
                 try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kkeve/suite",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "AI-powered full-stack test agent CLI - static analysis, unit test, component test, E2E test, execute, evaluate, and report",
   "license": "MIT",
   "bin": {

package/scripts/run-dsl-task.mjs

@@ -134,8 +134,12 @@ function normalizeStep(step) {
  * 投影 DSL 步骤为报告 outline，语义与 toDecorator 的 keveGoal 参数保持一致。
  * OPEN_PAGE 后紧跟的 WAIT_RESPONSE 会合并进同一个导航步骤，避免报告步骤数
  * 与脚本实际 keveGoal 数不一致。
+ *
+ * expected 文案统一走 stepExpectedText（与脚本投影同一个函数）：报告里展示的
+ * 预期与评测 Agent 读到的预期必须逐字一致，否则平台标签（「报错4」）会在报告
+ * 与评测两侧产生不同解读。
  */
-function buildCaseSteps(dslList) {
+function buildCaseSteps(dslList, ctx, stepExpectedText) {
   const steps = [];
   for (let i = 0; i < dslList.length; i++) {
     const d = dslList[i];
@@ -149,7 +153,8 @@ function buildCaseSteps(dslList) {
       if (gates.length) {
         const gateTexts = gates.map((g) => String(g?.text || '')).filter(Boolean);
         const gateExpects = gates
-          .flatMap((g) => (g?.expectation || []).map((e) => String(e?.text || '')))
+          .filter((g) => (g?.expectation || []).length > 0)
+          .map((g) => stepExpectedText(g, ctx))
           .filter(Boolean);
         steps.push({
           step: String(d?.text || 'OPEN_PAGE'),
@@ -160,8 +165,7 @@ function buildCaseSteps(dslList) {
       }
     }
     const stepText = String(d?.text || op || '');
-    const expTexts = (d?.expectation || []).map((e) => String(e?.text || '')).filter(Boolean);
-    const expected = expTexts.length ? expTexts.join('；') : '操作完成，页面正常响应';
+    const expected = stepExpectedText(d, ctx);
     if (!stepText) continue;
     steps.push({ step: stepText, expected });
   }
@@ -217,7 +221,7 @@ async function main() {
   fs.rmSync(resultFile, { force: true });
   fs.rmSync(manifestFile, { force: true });
 
-  const { toDecorator } = await import(
+  const { toDecorator, stepExpectedText } = await import(
     url.pathToFileURL(path.join(suiteRoot, 'dist/dsl/index.js')).href
   );
 
@@ -233,20 +237,26 @@ async function main() {
     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: input.env || 'test',
-      variableList: Array.isArray(item.variableList) ? item.variableList : [],
-      account: resolveAccount(item.accountInfo || input.accountInfo),
+      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);
+    const dslSteps = buildCaseSteps(dslList, renderCtx, stepExpectedText);
     caseEntries.push({
       caseId: `S${stepGroupId}`,
       stepGroupId,