@kkeve/suite 0.0.18 → 0.0.19

package/dist/dsl/toDecorator.js

@@ -106,7 +106,7 @@ function renderStep(d, ctx) {
             expLines.push(a);
     }
     const emit = (body) => {
-        out.push(`await keveGoal({ step: ${q(stepText)}, expected: ${q(expected)} }, async () => {`);
+        out.push(`await keveGoal({ step: ${q(stepText)}, expected: ${q(expected)}${reactOption(d)} }, async () => {`);
         for (const b of [...body, ...expLines])
             out.push(`  ${b}`);
         out.push(`});`);
@@ -232,7 +232,7 @@ function renderStep(d, ctx) {
             // 区域截图容错：元素不在当前页面（权限阻断等）时降级为整页截图，
             // 是否一致由基线比对决定，截图本身不做权限硬门。
             if (shotChain) {
-                out.push(`await keveGoal({ step: ${q(stepText)}, expected: ${q(expected)} }, async () => {`);
+                out.push(`await keveGoal({ step: ${q(stepText)}, expected: ${q(expected)}${reactOption(d)} }, async () => {`);
                 out.push(`  try {`);
                 out.push(`    await engine.screenshot(${q(shotName)}, ${shotChain});`);
                 out.push(`  } catch (_shotErr: any) {`);
@@ -299,13 +299,50 @@ function renderOpenPageWithGates(d, gates, ctx) {
                 body.push(`await __gate${gi}; // 等 ${String(g.text || '就绪响应')}`);
         });
     }
-    out.push(`await keveGoal({ step: ${q(stepText)}, expected: ${q(expected)} }, async () => {`);
+    out.push(`await keveGoal({ step: ${q(stepText)}, expected: ${q(expected)}${reactOption(d)} }, async () => {`);
     for (const b of body)
         out.push(`  ${b}`);
     out.push(`});`);
     return out;
 }
 // ─── 断言转译 ────────────────────────────────────────────────────────
+/**
+ * 步骤是否只有「纯文案期望」，必须依赖 LLM 才能判定。
+ *
+ * 平台 DSL 里有两类 expectation：
+ *  - 可执行断言（ELEMENT_NOT_EXIST / TEXT_EXIST …）→ 转译成 engine 断言，
+ *    成败在脚本里已经确定，无需再看页面；
+ *  - 纯文案载体（TEXT / 无 type）→ 不产生任何断言，只以文字描述预期，
+ *    脚本无法自证，只能交给 Agent 观察页面后判定。
+ *
+ * 只有第二类（且该步骤没有可执行断言）才需要保留 Agent Re-Act。
+ */
+function needsAgentJudge(d) {
+    const expects = d.expectation || [];
+    if (!expects.length)
+        return false;
+    const hasExecutable = expects.some((e) => {
+        const type = String(e.type || '');
+        return type && !(0, ops_js_1.isTextOnlyAssert)(type);
+    });
+    if (hasExecutable)
+        return false;
+    return expects.some((e) => {
+        const type = String(e.type || '');
+        return !type || (0, ops_js_1.isTextOnlyAssert)(type);
+    });
+}
+/**
+ * keveGoal 的 react 参数片段。
+ *
+ * 平台 DSL 是确定性录制产物：凡能自证的步骤都显式 react: false，跳过 Agent
+ * Re-Act —— 否则每个步骤都会额外发起一轮 LLM 探索，既拖长整体耗时至超出
+ * Cypress 用例超时（表现为「任务卡住」），也会让「报错1」这类仅作平台标签的
+ * expected 文案参与最终结论。
+ */
+function reactOption(d) {
+    return needsAgentJudge(d) ? '' : ', react: false';
+}
 /** 渲染一条 expectation；返回 null 表示「纯文案载体，不产生断言」 */
 function renderExpectation(e, ctx) {
     const type = String(e.type || '');

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.d.ts

@@ -17,6 +17,16 @@ export interface KeveGoalCallOptions {
     precondition?: string;
     step: string;
     expected: string;
+    /**
+     * 是否在 fn 之后追加一轮 Agent Re-Act 做最终判定。
+     *
+     * 默认 true（AI 场景 / 手写用例）：fn 只是前置动作与确定性校验，预期是否真正
+     * 达成由 Agent 观察真实页面后判定。
+     *
+     * DSL 投影脚本会显式传 false：整条链路的判定已由确定性断言给出，Re-Act 只会
+     * 额外消耗 LLM 预算，并让「报错1」这类平台标签参与结论。
+     */
+    react?: boolean;
 }
 /** agent Re-Act 的结果（P0-3 接入；未接入时由 fn 结果直接判定） */
 export interface CyGoalExploreResult {

package/dist/engine-cypress/keveGoal.js

@@ -75,6 +75,7 @@ function createCyKeveGoal(engine) {
         let fnErrorRaw;
         let fnResult;
         let fnBlocked = false;
+        const reactEnabled = options.react !== false;
         const fnSource = fn?.toString() || undefined;
         const owned = !(0, shotBuffer_js_1.isGoalShotDiffCaptureActive)();
         if (owned)
@@ -139,6 +140,26 @@ function createCyKeveGoal(engine) {
             };
             console.log(`[keveGoal] 📊 "${options.step}" 截图差异超阈值 — 确定性失败`);
         }
+        else if (!reactEnabled) {
+            // 确定性模式：断言是否通过就是结论，不再发起 LLM 探索。
+            reactResult = {
+                expectedMet: !fnError,
+                conclusion: fnError ? 'fail' : 'pass',
+                actions: [{
+                        action: {
+                            tool: 'done',
+                            verdict: fnError ? 'fail' : 'pass',
+                            text: fnError ? `Assertion failed: ${fnError}` : '确定性断言全部通过',
+                        },
+                        toolOutput: '',
+                        result: 'ok',
+                    }],
+                agentScreenshots: [],
+            };
+            logLine(fnError
+                ? `[keveGoal] ⚙️ "${options.step}" 确定性模式：fn 失败，跳过 Agent Re-Act`
+                : `[keveGoal] ⚙️ "${options.step}" 确定性模式：fn 通过，跳过 Agent Re-Act`);
+        }
         else {
             // fn 成功 / 失败都交给探索器（若引擎入口注册了 AI Re-Act）。
             // fn 只是前置确定性校验，@keveGoal 的预期是否真正达成必须由 Agent

package/dist/engine-playwright/keve-test.d.ts

@@ -32,6 +32,13 @@ export interface KeveGoalCallOptions {
     precondition?: string;
     step: string;
     expected: string;
+    /**
+     * 是否在 fn 之后追加一轮 Agent Re-Act 做最终判定。
+     *
+     * 默认 true（AI 场景 / 手写用例）；DSL 投影脚本传 false，判定完全由确定性
+     * 断言给出，避免为每个步骤额外消耗一轮 LLM。
+     */
+    react?: boolean;
 }
 type KeveFixture = {
     keveGoal: (options: KeveGoalCallOptions, fn?: () => Promise<void>) => Promise<void>;

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

@@ -189,6 +189,7 @@ exports.test = test_1.test.extend({
             let fnErrorRaw; // 原始错误对象（ScreenshotDiffError 等带结构的错误需要保留结构）
             let fnResult; // fn 返回值透传（flow 产物，如 createDashboard 的看板名）
             let fnBlocked = false; // true when fn error is environment-blocked (skip agent Re-Act)
+            const reactEnabled = options.react !== false;
             // 截图对比：fn 前开缓冲、fn 后收集 —— engine.expectScreenshot 的结果经此进 attachment
             (0, screenshotDiff_js_1.beginGoalShotDiffCapture)();
             if (fn) {
@@ -297,6 +298,27 @@ exports.test = test_1.test.extend({
                         conclusion: 'fail',
                     };
                 }
+                else if (!reactEnabled) {
+                    // 确定性模式（DSL 投影脚本）：断言结果即结论，不再发起 LLM 探索。
+                    console.log(fnError
+                        ? `[keveGoal] ⚙️ "${options.step}" deterministic mode: fn failed — skipping agent Re-Act`
+                        : `[keveGoal] ⚙️ "${options.step}" deterministic mode: fn passed — skipping agent Re-Act`);
+                    reactResult = {
+                        expectedMet: !fnError,
+                        actions: [{
+                                action: {
+                                    tool: 'done',
+                                    verdict: fnError ? 'fail' : 'pass',
+                                    text: fnError ? `Assertion failed: ${fnError}` : '确定性断言全部通过',
+                                },
+                                toolOutput: '',
+                                result: 'ok',
+                            }],
+                        finalSnapshot: '',
+                        agentScreenshots: [],
+                        conclusion: fnError ? 'fail' : 'pass',
+                    };
+                }
                 else {
                     // ── Per-goal timeout: prevent one slow goal from exhausting the test timeout ──
                     // Default 300s per goal; total test timeout should be ≥ (goals × 300s + overhead)

package/package.json

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