@kkeve/suite 0.0.13 → 0.0.17

package/dist/{core → engine-playwright}/keve-test.js

@@ -2,11 +2,11 @@
 /**
  * keve-test — Playwright test fixture: keveGoal (唯一操作原语)
  *
- * keveGoal 执行 fn 后 → 截图+fn逻辑+expected → AI判断是否一致
- *   一致     → 通过
- *   不一致   → AI 告诉你还差什么 → Re-Act 探索 → 探索成功
+ * keveGoal 执行 fn 后 → 截图+fn逻辑+expected → Agent Re-Act 观察页面后给最终结论
  *   fn 无    → Re-Act 直接探索
+ *   fn 成功  → 仍进 Re-Act，确认预期达成并产出推理轨迹
  *   fn 异常  → Re-Act 自愈
+ *   确定性事实（环境阻断 / 页面已关闭 / 截图差异超阈值）→ 短路，不烧 token
  *
  * keveAssert 已被吸收：keveGoal 的 expected 即断言语义
  *
@@ -56,33 +56,38 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.test = exports.sceneGoalsMap = exports.sceneEvalMetaMap = exports.sceneCodeMap = exports.getModelScenes = exports.keveScene = exports.keveModel = exports.expect = void 0;
+exports.test = exports.sceneGoalsMap = exports.sceneMetaMap = exports.sceneEvalMetaMap = exports.sceneCodeMap = exports.getModelScenes = exports.keveScene = exports.keveModel = exports.expect = void 0;
 const test_1 = require("@playwright/test");
 Object.defineProperty(exports, "expect", { enumerable: true, get: function () { return test_1.expect; } });
-const keve_registry_1 = require("./keve-registry");
-const agent_1 = require("../page-agent/agent");
-const keve_aspect_1 = require("./keve-aspect");
-const learned_actions_1 = require("./learned-actions");
+const keve_registry_js_1 = require("../core/decorator/keve-registry.js");
+const agent_js_1 = require("../page-agent/agent.js");
+const keve_aspect_js_1 = require("../core/decorator/keve-aspect.js");
+const learned_actions_js_1 = require("../core/learned-actions.js");
+const config_js_1 = require("../config.js");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
-// ─── CDP Mode ──────────────────────────────────────────────────────
-// CDP 连接逻辑已移到 global-setup.ts，通过全局变量共享 Browser 对象
-const global_setup_1 = require("./global-setup");
-var keve_decorators_1 = require("./keve-decorators");
-Object.defineProperty(exports, "keveModel", { enumerable: true, get: function () { return keve_decorators_1.keveModel; } });
-Object.defineProperty(exports, "keveScene", { enumerable: true, get: function () { return keve_decorators_1.keveScene; } });
-Object.defineProperty(exports, "getModelScenes", { enumerable: true, get: function () { return keve_decorators_1.getModelScenes; } });
-var keve_registry_2 = require("./keve-registry");
-Object.defineProperty(exports, "sceneCodeMap", { enumerable: true, get: function () { return keve_registry_2.sceneCodeMap; } });
-Object.defineProperty(exports, "sceneEvalMetaMap", { enumerable: true, get: function () { return keve_registry_2.sceneEvalMetaMap; } });
+// ─── 登录态注入 ─────────────────────────────────────────────────────
+// 不再由测试侧启动浏览器 / CDP 接管。登录 cookie 由服务端解析后随环境变量下发，
+// 这里只负责在启动浏览器前把 storageState 就位（global-setup 已写好文件）。
+const global_setup_js_1 = require("./global-setup.js");
+const screenshotDiff_js_1 = require("../core/judge/screenshotDiff.js");
+const goal_heuristics_js_1 = require("../core/judge/goal-heuristics.js");
+var keve_decorators_js_1 = require("../core/decorator/keve-decorators.js");
+Object.defineProperty(exports, "keveModel", { enumerable: true, get: function () { return keve_decorators_js_1.keveModel; } });
+Object.defineProperty(exports, "keveScene", { enumerable: true, get: function () { return keve_decorators_js_1.keveScene; } });
+Object.defineProperty(exports, "getModelScenes", { enumerable: true, get: function () { return keve_decorators_js_1.getModelScenes; } });
+var keve_registry_js_2 = require("../core/decorator/keve-registry.js");
+Object.defineProperty(exports, "sceneCodeMap", { enumerable: true, get: function () { return keve_registry_js_2.sceneCodeMap; } });
+Object.defineProperty(exports, "sceneEvalMetaMap", { enumerable: true, get: function () { return keve_registry_js_2.sceneEvalMetaMap; } });
+Object.defineProperty(exports, "sceneMetaMap", { enumerable: true, get: function () { return keve_registry_js_2.sceneMetaMap; } });
 // Re-export goal metadata for consumer convenience
-var keve_registry_3 = require("./keve-registry");
-Object.defineProperty(exports, "sceneGoalsMap", { enumerable: true, get: function () { return keve_registry_3.sceneGoalsMap; } });
+var keve_registry_js_3 = require("../core/decorator/keve-registry.js");
+Object.defineProperty(exports, "sceneGoalsMap", { enumerable: true, get: function () { return keve_registry_js_3.sceneGoalsMap; } });
 // ─── Register Built-in Aspects ───────────────────────────────────────
 // NOTE: action-log-write aspect 已废弃。
 // AI 探索过程数据现在通过 keveGoalResult attachment 直接流到 KeveReporter，
 // 由 KeveReporter 统一写入 confidence-data.jsonl（含 reactSteps）。
-keve_aspect_1.keveAspect.register({
+keve_aspect_js_1.keveAspect.register({
     name: 'learnedActions-update',
     phase: 'after',
     order: 20,
@@ -90,7 +95,7 @@ keve_aspect_1.keveAspect.register({
         if (!result?.actions?.length)
             return;
         const url = ctx.page.url();
-        learned_actions_1.learnedActions.add(ctx.step, result.actions, url, result.success);
+        learned_actions_js_1.learnedActions.add(ctx.step, result.actions, url, result.success);
     },
 });
 // ─── (diagnostic extraction moved to page-agent/diagnostic.ts, called via onAfterTask hook) ──
@@ -98,47 +103,52 @@ keve_aspect_1.keveAspect.register({
 exports.test = test_1.test.extend({
     // ── 将内置 testInfo 包装为可解构 fixture ─────────────────────────
     // 测试方法可直接写 { page, keveGoal, testInfo }，不再报 "unknown parameter" 错误
+    // ── engine: 引擎无关操作适配器 ──────────────────────────────────────
+    engine: async ({ page }, use) => {
+        const { createEngine } = await Promise.resolve().then(() => __importStar(require('./engineAdapter.js')));
+        const engine = createEngine(page);
+        await use(engine);
+    },
     testInfo: async ({}, use, testInfo) => {
         await use(testInfo);
     },
     browser: async ({}, use, testInfo) => {
-        if ((0, global_setup_1.isCdpMode)()) {
-            const browser = await (0, global_setup_1.getCdpBrowser)(); // 复用全局共享的 CDP browser
-            await use(browser);
-            // CDP 模式下不关闭浏览器（共享连接，关闭会影响后续用例）
-        }
-        else {
-            const browser = await test_1.chromium.launch(testInfo.project?.use?.launchOptions || {});
-            await use(browser);
-            await browser.close();
-        }
+        const browser = await test_1.chromium.launch(testInfo.project?.use?.launchOptions || {});
+        await use(browser);
+        await browser.close();
     },
-    page: async ({ browser }, use) => {
-        if ((0, global_setup_1.isCdpMode)()) {
-            const contexts = browser.contexts();
-            const cdpContext = contexts.length > 0 ? contexts[0] : await browser.newContext();
-            // CDP 模式：优先复用已有 page（保留登录状态），仅在无可用 page 时新开
-            const existingPages = cdpContext.pages();
-            let page;
-            if (existingPages.length > 0) {
-                // 复用第一个非 about:blank 的 page（通常是用户已登录的 tab）
-                page = existingPages.find(p => p.url() !== 'about:blank') || existingPages[0];
-                // 导航到 about:blank 作为起始页（清空之前的状态，但保留 cookie）
-                try {
-                    await page.goto('about:blank', { timeout: 3000 });
-                }
-                catch { /* ignore */ }
-            }
-            else {
-                page = await cdpContext.newPage();
+    page: async ({ browser }, use, testInfo) => {
+        // 建 context 时带上 storageState（服务端 cookies 写入的登录态），
+        // 裸 newPage() 会丢失 cookies 导致用例未登录失败。
+        // global-setup 正常会先写好；直接裸跑 playwright test 时这里兜底就地生成。
+        let storageState = testInfo.project?.use?.storageState;
+        if (!storageState && (0, global_setup_js_1.readInjectedCookies)().length > 0) {
+            storageState = (0, global_setup_js_1.resolveStorageStatePath)();
+            try {
+                (0, global_setup_js_1.writeStorageState)(storageState);
             }
-            await use(page);
-            // CDP 模式下不关闭 page（保留浏览器 tab 给下一个用例复用）
+            catch { /* 写失败则裸跑，用例会自行暴露登录问题 */ }
         }
-        else {
-            const page = await browser.newPage();
-            await use(page);
-            await page.close();
+        // 视频录制：playwright config use.video = { mode:'on', dir } → recordVideo
+        //（自定义 context 不会自动附加视频附件，需在 context 关闭后显式 attach）
+        const videoOpt = testInfo.project?.use?.video;
+        const videoOn = !!videoOpt && (videoOpt === 'on' || videoOpt.mode === 'on' || videoOpt.mode === 'retain-on-failure');
+        const context = await browser.newContext({
+            storageState,
+            ...(videoOn ? { recordVideo: { dir: typeof videoOpt === 'object' && videoOpt.dir ? videoOpt.dir : undefined } } : {}),
+        });
+        const page = await context.newPage();
+        await use(page);
+        const video = page.video();
+        await page.close();
+        await context.close();
+        // 视频文件在 context 关闭后才定稿：显式挂附件 → results.json attachments
+        if (video) {
+            try {
+                const videoPath = await video.path();
+                await testInfo.attach('video', { path: videoPath });
+            }
+            catch { /* 无视频不阻塞 */ }
         }
     },
     // ── keveGoal: 唯一操作原语 ────────────────────────────────────────
@@ -152,9 +162,9 @@ exports.test = test_1.test.extend({
                 order: goalOrder++,
             };
             const sceneTitle = testInfo.title;
-            if (!keve_registry_1.sceneGoalsMap.has(sceneTitle))
-                keve_registry_1.sceneGoalsMap.set(sceneTitle, []);
-            keve_registry_1.sceneGoalsMap.get(sceneTitle).push(goalMeta);
+            if (!keve_registry_js_1.sceneGoalsMap.has(sceneTitle))
+                keve_registry_js_1.sceneGoalsMap.set(sceneTitle, []);
+            keve_registry_js_1.sceneGoalsMap.get(sceneTitle).push(goalMeta);
             const ctx = {
                 page,
                 step: options.step,
@@ -165,7 +175,7 @@ exports.test = test_1.test.extend({
                 specFilePath: testInfo.file,
             };
             // Run before aspects
-            await keve_aspect_1.keveAspect.runPhase('before', ctx);
+            await keve_aspect_js_1.keveAspect.runPhase('before', ctx);
             // ── Capture goal-before screenshot (fn 之前的页面原始状态) ──
             // 语义：记录"测试动作发生前"的页面，供报告 before/after 对照
             let goalScreenshotBefore = '';
@@ -176,24 +186,46 @@ exports.test = test_1.test.extend({
             let result;
             const fnSource = fn?.toString() || undefined;
             let fnError;
+            let fnErrorRaw; // 原始错误对象（ScreenshotDiffError 等带结构的错误需要保留结构）
+            let fnResult; // fn 返回值透传（flow 产物，如 createDashboard 的看板名）
             let fnBlocked = false; // true when fn error is environment-blocked (skip agent Re-Act)
+            // 截图对比：fn 前开缓冲、fn 后收集 —— engine.expectScreenshot 的结果经此进 attachment
+            (0, screenshotDiff_js_1.beginGoalShotDiffCapture)();
             if (fn) {
                 try {
-                    await fn();
+                    fnResult = await fn();
                     console.log(`[keveGoal] "${options.step}" fn executed`);
                 }
                 catch (err) {
                     fnError = err?.message || String(err);
+                    fnErrorRaw = err;
                     console.log(`[keveGoal] "${options.step}" fn error: ${fnError}`);
                     // ── Detect environment-blocked errors: skip Agent Re-Act, directly BLOCKED ──
                     // When fn fails due to empty URL, connection refused, timeout, or navigation to invalid URL,
                     // Agent exploration cannot fix environment issues — waste of time and tokens.
-                    fnBlocked = isEnvironmentBlockedError(err);
+                    fnBlocked = (0, goal_heuristics_js_1.isEnvironmentBlockedError)(err);
                     if (fnBlocked) {
                         console.log(`[keveGoal] 🚫 "${options.step}" BLOCKED — environment error detected, skipping agent Re-Act`);
                     }
+                    // ── Detect page-level permission block (forbidden / unauthorized) ──
+                    // When the page redirected to a forbidden/unauthorized URL (e.g. kwaibi /pc/dashboard/forbidden),
+                    // the fn error is typically a locator timeout — but the root cause is access denial,
+                    // not a missing element. Mark as blocked and annotate the error for accurate reporting.
+                    if (!fnBlocked && fnError) {
+                        try {
+                            const blockedUrl = page.url();
+                            if (/\/forbidden|\/unauthorized|\/403|\/no-permission/i.test(blockedUrl)) {
+                                fnBlocked = true;
+                                fnError = `页面访问被阻断（当前 URL=${blockedUrl}），目标元素未渲染 — 权限或数据问题，非用例缺陷`;
+                                console.log(`[keveGoal] 🚫 "${options.step}" BLOCKED — page redirected to forbidden/unauthorized: ${blockedUrl}`);
+                            }
+                        }
+                        catch { /* page.url() may fail if page is closed */ }
+                    }
                 }
             }
+            // fn 结束（无论成败）即取出本 goal 的对比结果；不再有引擎路径会往里写
+            const shotDiffs = (0, screenshotDiff_js_1.drainGoalShotDiff)();
             // ── Capture fn-after screenshot (fn 执行后的页面状态，传给 agent 说明执行前后) ──
             let fnAfterScreenshot = '';
             if (fn) {
@@ -204,7 +236,7 @@ exports.test = test_1.test.extend({
             }
             // ── Hand off to agent: agent does Re-Act (OR shortcut to blocked if fnBlocked) ──
             const currentUrl = page.url();
-            const learnedHint = learned_actions_1.learnedActions.getHint(options.step, currentUrl);
+            const learnedHint = learned_actions_js_1.learnedActions.getHint(options.step, currentUrl);
             let reactResult;
             let reactTimedOut = false;
             if (fnBlocked) {
@@ -224,43 +256,92 @@ exports.test = test_1.test.extend({
                 };
             }
             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)
-                const GOAL_TIMEOUT_MS = 300_000;
-                const goalTimeoutController = new AbortController();
-                const goalTimeout = setTimeout(() => {
-                    goalTimeoutController.abort();
-                    console.log(`[keveGoal] ⏰ "${options.step}" timed out after ${GOAL_TIMEOUT_MS}ms — stopping agent`);
-                }, GOAL_TIMEOUT_MS);
+                // ── Page liveness check: if fn killed the page, skip Agent Re-Act ──
+                // When fn error involves page/browser close, the page is dead —
+                // Agent cannot take a11y snapshots or interact. Skip immediately.
+                let pageAlive = true;
                 try {
-                    reactResult = await (0, agent_1.reactLoop)(page, options.step, options.expected, {
-                        learnedActionsHint: learnedHint,
-                        specFilePath: ctx.specFilePath,
-                        fnSource,
-                        fnResult: fnError ? { error: fnError } : { success: true },
-                        signal: goalTimeoutController.signal,
-                        goalScreenshotBefore: goalScreenshotBefore || undefined,
-                        fnAfterScreenshot: fnAfterScreenshot || undefined,
-                    });
+                    await page.url();
+                }
+                catch {
+                    pageAlive = false;
                 }
-                catch (reactErr) {
-                    reactTimedOut = true;
-                    const isGoalTimeout = goalTimeoutController.signal.aborted;
-                    const msg = isGoalTimeout
-                        ? `Goal timed out (${GOAL_TIMEOUT_MS}ms)`
-                        : (reactErr?.message || String(reactErr));
-                    console.log(`[keveGoal] reactLoop interrupted: ${msg.slice(0, 200)}`);
+                if (!pageAlive) {
+                    console.log(`[keveGoal] 🚫 "${options.step}" BLOCKED — page is dead after fn error, skipping agent Re-Act`);
                     reactResult = {
                         expectedMet: false,
-                        actions: [],
+                        actions: [{
+                                action: { tool: 'done', verdict: 'blocked', text: `Page closed after fn error: ${fnError}` },
+                                toolOutput: '',
+                                result: 'ok',
+                            }],
                         finalSnapshot: '',
                         agentScreenshots: [],
-                        conclusion: isGoalTimeout ? 'blocked' : 'fail',
+                        conclusion: 'blocked',
                     };
                 }
-                finally {
-                    clearTimeout(goalTimeout);
+                else if (fnErrorRaw instanceof screenshotDiff_js_1.ScreenshotDiffError) {
+                    // ── 截图对比超阈值：确定性事实，跳过 Agent Re-Act ──
+                    // diff 不是探索能修复的（页面就该和基线不一样才报错），探索只会烧 token；
+                    // 对比结果已入 shotDiffs，attachment 会带上完整差异证据。
+                    console.log(`[keveGoal] 📊 "${options.step}" screenshot diff exceeded — skipping agent Re-Act`);
+                    reactResult = {
+                        expectedMet: false,
+                        actions: [{
+                                action: { tool: 'done', verdict: 'fail', text: fnError },
+                                toolOutput: fnErrorRaw.shotDiff?.message || '',
+                                result: 'ok',
+                            }],
+                        finalSnapshot: '',
+                        agentScreenshots: [],
+                        conclusion: 'fail',
+                    };
                 }
+                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)
+                    const GOAL_TIMEOUT_MS = 300_000;
+                    const goalTimeoutController = new AbortController();
+                    const goalTimeout = setTimeout(() => {
+                        goalTimeoutController.abort();
+                        console.log(`[keveGoal] ⏰ "${options.step}" timed out after ${GOAL_TIMEOUT_MS}ms — stopping agent`);
+                    }, GOAL_TIMEOUT_MS);
+                    try {
+                        reactResult = await (0, agent_js_1.reactLoop)(page, options.step, options.expected, {
+                            learnedActionsHint: learnedHint,
+                            specFilePath: ctx.specFilePath,
+                            fnSource,
+                            fnResult: fnError ? { error: fnError } : { success: true },
+                            signal: goalTimeoutController.signal,
+                            goalScreenshotBefore: goalScreenshotBefore || undefined,
+                            fnAfterScreenshot: fnAfterScreenshot || undefined,
+                            targetUrl: process.env.KEVE_TARGET_URL || '',
+                            getEnv: (name) => process.env[name] || '',
+                            saveScreenshot: saveAgentScreenshot,
+                            loadInitialImages: loadInitialImages,
+                            llm: reactLlmConfig(),
+                        });
+                    }
+                    catch (reactErr) {
+                        reactTimedOut = true;
+                        const isGoalTimeout = goalTimeoutController.signal.aborted;
+                        const msg = isGoalTimeout
+                            ? `Goal timed out (${GOAL_TIMEOUT_MS}ms)`
+                            : (reactErr?.message || String(reactErr));
+                        console.log(`[keveGoal] reactLoop interrupted: ${msg.slice(0, 200)}`);
+                        reactResult = {
+                            expectedMet: false,
+                            actions: [],
+                            finalSnapshot: '',
+                            agentScreenshots: [],
+                            conclusion: isGoalTimeout ? 'blocked' : 'fail',
+                            diagnostics: undefined,
+                        };
+                    }
+                    finally {
+                        clearTimeout(goalTimeout);
+                    }
+                } // end of page-alive else (agent Re-Act path)
             } // end of else (non-blocked path)
             // ── Deterministic override: fn assertion failure cannot be overridden by Agent "pass" ──
             // When fn has a hard assertion failure (Expected X, Received Y), the value mismatch
@@ -268,7 +349,7 @@ exports.test = test_1.test.extend({
             // show 15px, so consistent") and override to pass, but 15px ≠ 16px is a definitive failure.
             // This is the per-goal equivalent of pipeline afterHook (case-gen-validate) —
             // deterministic check > LLM judgment.
-            if (fnError && !fnBlocked && reactResult.expectedMet && isAssertionFailure(fnError)) {
+            if (fnError && !fnBlocked && reactResult.expectedMet && (0, goal_heuristics_js_1.isAssertionFailure)(fnError)) {
                 console.log(`[keveGoal] ⚠️ "${options.step}" Agent said PASS but fn had assertion failure — overriding to FAIL`);
                 console.log(`[keveGoal]    fn assertion: ${fnError}`);
                 reactResult.expectedMet = false;
@@ -282,13 +363,19 @@ exports.test = test_1.test.extend({
                     ? undefined
                     : reactResult.conclusion === 'blocked'
                         ? new Error(`Blocked: ${fnBlocked ? fnError : (reactTimedOut ? `Agent 超时 (300000ms)` : (reactResult.actions?.filter((a) => a.action?.tool === 'done').pop()?.action?.text || 'Agent blocked'))}`)
-                        : (fnError && isAssertionFailure(fnError) && !fnBlocked)
-                            ? new Error(`Assertion failed: ${fnError}`)
-                            : new Error(`Expected not achieved: ${options.expected}`),
+                        : (fnErrorRaw instanceof screenshotDiff_js_1.ScreenshotDiffError)
+                            ? new Error(fnError) // 截图对比：保留带差异率/区块数/基线版本的结构化错误文案
+                            : (fnError && (0, goal_heuristics_js_1.isAssertionFailure)(fnError) && !fnBlocked)
+                                ? new Error(`Assertion failed: ${fnError}`)
+                                : new Error(`Expected not achieved: ${options.expected}`),
             };
             // Attach Agent conclusion for downstream consumers
             if (reactResult.conclusion)
                 result.conclusion = reactResult.conclusion;
+            // Attach runtime diagnostics for downstream consumers (Playwright side must
+            // copy them here because the attachment reads from `result`).
+            if (reactResult.diagnostics)
+                result.diagnostics = reactResult.diagnostics;
             console.log(reactResult.expectedMet
                 ? `[keveGoal] ✅ "${options.step}" PASSED`
                 : `[keveGoal] ❌ "${options.step}" FAILED (${reactResult.conclusion || 'fail'}) — ${result.error?.message || 'expected not achieved'}`);
@@ -384,21 +471,31 @@ exports.test = test_1.test.extend({
                     }),
                     finalSnapshot: result.finalSnapshot ? String(result.finalSnapshot).slice(0, 500) : undefined,
                     diagnosticHints,
+                    diagnostics: result.diagnostics,
                     goalScreenshotBefore: goalScreenshotBefore || undefined,
                     goalScreenshotAfter: goalScreenshotAfter || undefined,
-                    agentScreenshots: result.agentScreenshots || [],
+                    // agent 未单独留图时，用 fn-after 兜底，保证报告至少有一张执行后截图。
+                    // 不能写 `|| [...]`：空数组是 truthy，会把兜底截图短路丢弃。
+                    agentScreenshots: result.agentScreenshots?.length
+                        ? result.agentScreenshots
+                        : (fnAfterScreenshot ? [fnAfterScreenshot] : []),
+                    // 截图对比证据（matched/created/exceeded 全量保留；平台 stepsDetail 回收为 evidence.screenshotDiff）
+                    screenshotDiff: shotDiffs.length ? shotDiffs : undefined,
                     // refinePatch: (result as any).refinePatch || undefined, // 已注释：scriptRefine 已禁用
                     conclusion: result.conclusion || undefined,
                 }), 'utf-8'),
             });
             // Run after aspects
-            await keve_aspect_1.keveAspect.runPhase('after', ctx, result, result.error);
+            await keve_aspect_js_1.keveAspect.runPhase('after', ctx, result, result.error);
             // Throw if not successful
             if (!result.success) {
                 const failReason = result.error?.message || 'expected state not achieved';
                 console.log(`[keveGoal] ❌ "${options.step}" FAILED — reason: ${failReason}`);
                 throw result.error || new Error(`keveGoal "${options.step}" failed: ${failReason}`);
             }
+            // 透传 fn 返回值：flow 辅助函数（如 createDashboard 返回看板名）可包进 keveGoal，
+            // 脚本失败时由 Agent Re-Act 自愈，成功时把产物继续传给后续步骤
+            return fnResult;
         };
         await use(keveGoalFn);
         // keveGoals attachment 已删除：step/expected/precondition/order 已合并进
@@ -407,124 +504,77 @@ exports.test = test_1.test.extend({
     }
 });
 // Register extended test with keve-decorators so @keveModel uses the correct test
-const keve_decorators_2 = require("./keve-decorators");
-(0, keve_decorators_2.setKeveTest)(exports.test);
+const keve_decorators_js_2 = require("../core/decorator/keve-decorators.js");
+(0, keve_decorators_js_2.setKeveTest)(exports.test);
 // ── 辅助函数 ──
 /**
- * Detect environment-blocked errors from fn execution.
- *
- * When fn (deterministic script) fails with these patterns, Agent Re-Act cannot
- * fix the issue — the error is environmental, not application-level:
- *
- * 1. Empty/undefined URL → page.goto(''), page.goto(undefined)
- * 2. Connection refused / net::ERR_CONNECTION_REFUSED
- * 3. Navigation timeout (page not reachable)
- * 4. Invalid URL format
- * 5. SSO redirect / auth failure (not the app's fault)
- *
- * Returns true → keveGoal skips Agent Re-Act and directly reports BLOCKED
- * with the fn error as the blocking reason.
+ * 截图并保存到当前轮次的 reports/round-N，返回相对 taskDir 的路径
+ * @param phase 'before' | 'after-fn' — 用于文件名前缀
  */
-function isEnvironmentBlockedError(err) {
-    const msg = (err?.message || String(err)).toLowerCase();
-    // Empty/undefined URL: page.goto('') or page.goto(undefined)
-    if (msg.includes('url must not be empty') || msg.includes('url is empty')
-        || msg.includes('invalid url') || msg.includes('url is undefined')
-        || msg.includes('navigation to ""') || msg.includes("navigation to ''")) {
-        return true;
-    }
-    // page.goto(undefined): Playwright type error "url: expected string, got undefined"
-    // This happens when process.env.PAGE_* is not set — environment config issue, not app issue
-    if ((msg.includes('expected string') || msg.includes('expected a string'))
-        && (msg.includes('got undefined') || msg.includes('got null') || msg.includes('received undefined'))) {
-        return true;
-    }
-    // Connection refused / network unreachable
-    if (msg.includes('err_connection_refused') || msg.includes('connection refused')
-        || msg.includes('net::err_connection') || msg.includes('err_name_not_resolved')
-        || msg.includes('err_address_unreachable') || msg.includes('err_internet_disconnected')
-        || msg.includes('err_connection_timed_out') || msg.includes('err_connection_reset')) {
-        return true;
-    }
-    // Navigation timeout (page not reachable in time)
-    if (msg.includes('navigation timeout of') || msg.includes('timeout of') && msg.includes('exceeded')
-        || msg.includes('page.goto: timeout') || msg.includes('navigating to') && msg.includes('timed out')) {
-        return true;
-    }
-    // Playwright locator/waitForSelector timeout — selector not found on page (fn script issue, not app crash)
-    // e.g. "Timeout 15000ms exceeded while waiting for locator('.selector') to be visible"
-    // This is a script-quality issue (wrong selector), not an env blocked error.
-    // Return false here — let Agent take over rather than treating as BLOCKED.
-    // Note: we intentionally do NOT return true; these should fall through to Agent Re-Act.
-    // IDC network segment restriction
-    if (msg.includes('unable to access on the idc network segment')
-        || msg.includes('idc network segment') || msg.includes('40314')) {
-        return true;
-    }
-    // SSO / auth redirect (not the app's fault)
-    if (msg.includes('sso redirect') || msg.includes('login redirect detected')
-        || msg.includes('err_too_many_redirects')) {
-        return true;
-    }
-    return false;
+async function captureScreenshot(page, stepName, order, phase) {
+    const buf = await page.screenshot({ type: 'png', timeout: 15000 });
+    const safeName = stepName.replace(/[^a-zA-Z0-9一-鿿]/g, '_').slice(0, 30);
+    return writeScreenshot(buf, `goal-${phase}-${order}-${safeName}`);
 }
 /**
- * Detect assertion failures from fn execution (Expected/Received patterns).
- *
- * When fn (deterministic script) throws a hard assertion failure with concrete
- * Expected vs Received values, the mismatch is a *fact*, not a judgment.
- * The Agent may rationalize "consistency" (e.g. "both pages show 15px → consistent → pass")
- * and override to pass, but 15px ≠ 16px is a definitive failure.
- *
- * This function identifies such assertion failures so keveGoal can:
- *   - Override Agent "pass" → "fail" when the fn proved a value mismatch
- *   - Use the precise assertion message in the error (instead of generic "expected not achieved")
- *
- * Returns true for assertion errors, false for environment/runtime errors.
+ * 当前轮次截图目录绝对路径（与 Cypress 桥同名同层）。
+ * 新布局为 <taskRoot>/reports/round-N/screenshots；缺失时回退旧布局，
+ * 兼容历史执行环境。
  */
-function isAssertionFailure(error) {
-    const msg = (error || '').toLowerCase();
-    // Exclude Playwright API type errors (parameter type mismatch, not value assertion)
-    // e.g. "page.goto: url: expected string, got undefined" — this is an env config error,
-    // not a functional assertion failure. isEnvironmentBlockedError() handles it instead.
-    if (msg.includes('expected string') || msg.includes('expected a string')
-        || msg.includes('expected number') || msg.includes('expected boolean')) {
-        // Only exclude if it looks like an API parameter error (not an assertion)
-        if (msg.includes('got undefined') || msg.includes('got null')
-            || msg.includes('received undefined') || msg.includes('received null')) {
-            return false;
-        }
+function screenshotsDir() {
+    if (process.env.KEVE_RESULT_DIR) {
+        return path.join(path.resolve(process.env.KEVE_RESULT_DIR), 'screenshots');
     }
-    // Jest/Vitest/playwright assertion: "Expected: X, Received: Y"
-    if (msg.includes('expected') && msg.includes('received'))
-        return true;
-    // AssertionError / assert keyword
-    if (msg.includes('assertionerror') || msg.includes('assertion failed')
-        || msg.includes('assertion error'))
-        return true;
-    // expect(x).toBe(y) / expect(x).toEqual(y) pattern
-    // Note: must NOT match Playwright timeout messages like "Timeout 15000ms exceeded waiting for locator(...) to be visible"
-    // Those are env/timeout errors, not value assertion failures.
-    if ((msg.includes(' to be ') && !msg.includes('timeout') && !msg.includes('waiting for') && !msg.includes('exceeded'))
-        || msg.includes(' to equal ') || msg.includes(' to deeply equal '))
-        return true;
-    // Playwright expect: "expected string, received number" etc.
-    if (msg.includes('expected ') && (msg.includes(' but ') || msg.includes(' got ') || msg.includes(' received ')))
-        return true;
-    return false;
-}
-/**
- * 截图并保存到 test-artifacts，返回相对 taskDir 的路径
- * @param phase 'before' | 'after-fn' — 用于文件名前缀
- */
-async function captureScreenshot(page, stepName, order, phase) {
-    const buf = await page.screenshot({ type: 'png', timeout: 15000 });
     const taskDir = process.env.KEVE_TASK_DIR || '.keve';
     const round = process.env.KEVE_ROUND || 'latest';
-    const screenshotsDir = path.join(taskDir, 'test-artifacts', `round-${round}`, 'screenshots');
-    fs.mkdirSync(screenshotsDir, { recursive: true });
-    const safeName = stepName.replace(/[^a-zA-Z0-9一-鿿]/g, '_').slice(0, 30);
-    const file = path.join(screenshotsDir, `goal-${phase}-${order}-${safeName}-${Date.now()}.png`);
-    fs.writeFileSync(file, buf);
+    return path.join(taskDir, 'test-artifacts', `round-${round}`, 'screenshots');
+}
+/** 落盘 PNG，返回相对 taskDir 的路径 */
+function writeScreenshot(png, baseName) {
+    const taskDir = process.env.KEVE_TASK_DIR || '.keve';
+    const dir = screenshotsDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, `${baseName}-${Date.now()}.png`);
+    fs.writeFileSync(file, png);
     return path.relative(taskDir, file);
 }
+/** Agent 单步截图落盘（宿主注入给 reactLoop，与 Cypress 桥的命名同形） */
+async function saveAgentScreenshot(pngBase64, stepIndex, stepName) {
+    const safeName = stepName.replace(/[^a-zA-Z0-9一-鿿]/g, '_').slice(0, 30);
+    return writeScreenshot(Buffer.from(pngBase64, 'base64'), `agent-step${stepIndex}-${safeName}`);
+}
+/** 读取 goal-before / fn-after 图片，转成多模态 ContentItem（唯一注意：路径是相对 taskDir） */
+async function loadInitialImages(paths) {
+    const taskDir = process.env.KEVE_TASK_DIR || '.keve';
+    const items = [];
+    for (const [label, rel] of [
+        ['goal-before', paths.goalScreenshotBefore],
+        ['fn-after', paths.fnAfterScreenshot],
+    ]) {
+        if (!rel)
+            continue;
+        try {
+            const file = path.isAbsolute(rel) ? rel : path.join(taskDir, rel);
+            if (!fs.existsSync(file))
+                continue;
+            const b64 = fs.readFileSync(file).toString('base64');
+            items.push({ type: 'text', text: `Screenshot (${label}):` });
+            items.push({ type: 'image_url', image_url: { url: `data:image/png;base64,${b64}` } });
+        }
+        catch { /* 单张图读失败不影响探索 */ }
+    }
+    return items;
+}
+/** Re-Act 的 LLM 配置：优先 keve.yaml，其次进程环境变量（与 config.ts DEFAULT_CONFIG 同源） */
+function reactLlmConfig() {
+    let cfg = { base_url: '', model: '', api_key: '' };
+    try {
+        cfg = (0, config_js_1.loadConfig)().llm;
+    }
+    catch { /* 配置缺失时退回环境变量 */ }
+    return {
+        baseURL: cfg.base_url || process.env.KEVE_LLM_BASE_URL || '',
+        model: cfg.model || process.env.KEVE_LLM_MODEL_NAME || process.env.KEVE_LLM_MODEL || '',
+        apiKey: cfg.api_key || process.env.KEVE_LLM_API_KEY || '',
+    };
+}