@kkeve/suite 0.0.23 → 0.0.25

package/dist/dsl/toDecorator.js

@@ -160,7 +160,17 @@ function renderStep(d, ctx) {
         const executableLineCount = [...body, ...expLines].length;
         // P1 纵深防御：断言里若残留未解析占位符，说明解析链路有漏（正常已在
         // stringExpr 处编译期报错），一律不许短路 —— 自证式断言不能当作确定性事实。
-        const hasUnresolved = [...body, ...expLines].some((b) => /\$\{[^}]+\}/.test(b));
+        // stringExpr 对已知合法引用生成 ${String(X)} 模板，运行时变量在这里不是
+        // 「未解析占位符」，不应阻断确定性短路。其余残留 ${...} 仍是解析漏洞。
+        const hasUnresolved = [...body, ...expLines].some((b) => {
+            for (const m of String(b).matchAll(/\$\{([^}]+)\}/g)) {
+                const raw = String(m[1]).trim();
+                const name = /^String\(\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*\)$/.exec(raw)?.[1] || raw;
+                if (!ctx.runtimeVars.has(name))
+                    return true;
+            }
+            return false;
+        });
         const deterministic = expectedFullyCovered && !pageLevelOp && executableLineCount > 0 && !hasUnresolved;
         out.push(`await keveGoal({ step: ${q(stepText)}, expected: ${q(expected)}${deterministic ? ', deterministic: true' : ''} }, async () => {`);
         for (const b of [...body, ...expLines])
@@ -285,7 +295,7 @@ function renderStep(d, ctx) {
                     : undefined);
             const targetCtx = valueCtx || d.child?.context || d.child;
             if (Array.isArray(targetCtx) && targetCtx.length) {
-                emit([`await engine.drag(${chain}, ${chainExpr(targetCtx, ctx)});`, ...waitExprs(d)]);
+                emit([`await engine.drag(${chainExpr(normalizeDragSource(d.context), ctx)}, ${chainExpr(targetCtx, ctx)});`, ...waitExprs(d)]);
             }
             else {
                 throw new Error(`DRAGGING 缺少目标元素，拒绝退化为悬停: ${stepText}`);
@@ -1063,6 +1073,23 @@ function collectHops(context) {
     }
     return out;
 }
+/**
+ * 拖拽源链归一化：录制器常见的「父容器 → 文本 → 列表项」链会把列表项限制在
+ * 文本叶节点后代内，导致确定性定位落空。同用例里可稳定命中的点击链是
+ * 「列表项 → 文本/includes」，拖拽源也应优先使用该形态。
+ */
+function normalizeDragSource(context) {
+    const hops = Array.isArray(context) ? context : [];
+    if (hops.length < 2)
+        return context;
+    const prev = hops[hops.length - 2];
+    const tail = hops[hops.length - 1];
+    const isListItemTail = String(tail?.value ?? '') === '[data-e2e-name="列表项"]';
+    const isTextHop = String(prev?.type || '') === 'includes' || String(prev?.type || '') === 'text';
+    if (isListItemTail && isTextHop)
+        return [tail, prev];
+    return context;
+}
 /** 截图基线 key 兜底：步骤文案 → 稳定 key（同步骤重复生成不变） */
 function sanitizeShotKey(text) {
     return String(text || 'shot').replace(/[^a-zA-Z0-9\u4e00-\u9fff]/g, '_').slice(0, 40);

package/dist/engine-cypress/cdp.js

@@ -209,7 +209,7 @@ function createCdp(send) {
     async function goto(url, timeout = 30000) {
         const before = await currentUrl();
         await evaluateInAut(`location.href = ${JSON.stringify(url)}`);
-        const landed = await pollUntil(async () => {
+        const waitComplete = async () => {
             const snap = await snapshot();
             if (snap.readyState !== 'complete')
                 return undefined;
@@ -217,8 +217,21 @@ function createCdp(send) {
                 return undefined;
             // 同 URL 的显式 re-goto 场景：URL 不变时直接以 readyState 为准
             return snap;
-        }, timeout);
-        if (!landed) {
+        };
+        const landed = await pollUntil(waitComplete, timeout);
+        if (landed)
+            return;
+        // 页面存在长连接时 document.readyState 可能一直停在 interactive，
+        // 但新文档实际已经可交互且 URL 已切到目标。此时不能再判导航超时。
+        const interactive = await pollUntil(async () => {
+            const snap = await snapshot();
+            if (snap.readyState === 'loading' || snap.readyState === 'uninitialized')
+                return undefined;
+            if (snap.url !== url)
+                return undefined;
+            return snap;
+        }, 5000);
+        if (!interactive) {
             throw new Error(`[cypress-engine] 导航超时（${timeout}ms）：${url}`);
         }
     }

package/dist/engine-cypress/keveGoal.js

@@ -40,10 +40,108 @@ function logLine(line) {
     console.log(line);
     (0, state_js_1.addLog)(line);
 }
+function openGoalPanelLog(order, step) {
+    // keveGoal 同源实现也被非 Cypress 宿主引用，必须显式探测运行时能力。
+    const cypress = globalThis.Cypress;
+    if (typeof cypress?.log !== 'function')
+        return null;
+    try {
+        return cypress.log({
+            name: 'keveGoal',
+            // order 从 0 起算，展示与旧链路一致从「步骤1」开始。
+            displayName: `步骤${order + 1}`,
+            message: step,
+        }) || null;
+    }
+    catch (err) {
+        console.warn(`[keveGoal] 步骤面板日志创建失败（不影响执行）：${err?.message || err}`);
+        return null;
+    }
+}
+function closeGoalPanelLog(log, success, errorMessage) {
+    if (!log)
+        return;
+    try {
+        // 失败态必须走 log.error()：实测 set('state','failed') 会被 end() 重置回 passed。
+        // 成功态不手写 ✅/❌，交给 Cypress 原生状态染色。
+        if (!success)
+            log.error(new Error(errorMessage || 'keveGoal failed'));
+        log.end();
+    }
+    catch (err) {
+        console.warn(`[keveGoal] 步骤面板日志收敛失败（不影响执行）：${err?.message || err}`);
+    }
+}
+/**
+ * 面板单行承载有限：长错误折叠空白并截断，避免一次失败把后续步骤刷出视口。
+ *
+ * 折叠空白是必须的 —— 面板实测会把 message 里的 `\n` 折叠成空格，
+ * 这里显式做一遍，保证 stdout / 报告 / 面板三处文本一致。
+ */
+function clip(text, max = 220) {
+    const s = String(text || '').replace(/\s+/g, ' ').trim();
+    return s.length > max ? `${s.slice(0, max)}…` : s;
+}
+/**
+ * 把失败归因拆成「实际」与「判定」两段，供面板详情行与 errorMessage 复用。
+ *
+ * 面板实测限制（见方案文档第十节）：
+ *  - message 里的 `\n` 会被折叠成空格 → 多字段必须用显式分隔符连接；
+ *  - `consoleProps` 不会展开、点击也不渲染 → 信息必须直接可见，不能藏起来。
+ * 因此这里只产出可直接铺在面板上的单段文本，不做多行排版。
+ */
+function describeGoalFailure(input) {
+    const actual = input.fnBlocked
+        ? `环境阻断 — ${clip(input.fnError || '未知环境错误')}`
+        : input.shotDiff
+            ? `截图差异超阈值 — ${clip(input.fnError || '未知差异')}`
+            : input.fnError
+                ? `${input.assertion ? 'fn 断言未通过' : 'fn 执行报错'} — ${clip(input.fnError)}`
+                : 'Agent Re-Act 结束后仍未达到预期';
+    const judge = input.fnBlocked
+        ? 'blocked · 环境错误，跳过 Agent Re-Act'
+        : input.overriddenByFn
+            ? 'fail · fn 断言覆盖 Agent 的 PASS'
+            : input.fnError
+                ? input.assertion
+                    ? 'fail · fn 断言未通过'
+                    : 'fail · fn 报错后 Agent 仍未达成'
+                : 'fail · Agent Re-Act 未达成预期';
+    // 用「自述」而非「结论」：Agent 判 pass 却因 fn 断言被判 fail 时，
+    // 这句话与最终判定可能相反，如实呈现才能暴露冲突，而不是掩盖它。
+    const verdict = input.agentText
+        ? `${judge}（Agent 自述：${clip(input.agentText, 120)}）`
+        : judge;
+    return { actual, verdict };
+}
+/**
+ * 失败步骤在红色主行之后追加一条详情行。
+ *
+ * 独立成条而非塞进主行 message：实测详情条不继承红色，天然是「详情位」的
+ * 视觉层次，且主行保持「步骤N + 动作」的整洁形态，长文案不会污染步骤列表。
+ */
+function appendGoalFailurePanelLine(order, detail) {
+    const cypress = globalThis.Cypress;
+    if (typeof cypress?.log !== 'function')
+        return;
+    try {
+        cypress.log({
+            name: 'keveGoal',
+            displayName: `↳ 步骤${order + 1} 失败原因`,
+            // 不重复步骤文案：主行已显示「步骤N + 动作」，displayName 也带了步骤号，
+            // 详情行只承载「期望 / 实际 / 判定」三段，避免同样的信息占两倍行高。
+            message: detail,
+        });
+    }
+    catch (err) {
+        console.warn(`[keveGoal] 步骤面板失败详情写入失败（不影响执行）：${err?.message || err}`);
+    }
+}
 function createCyKeveGoal(engine) {
     return async (options, fn) => {
         const state = (0, state_js_1.requireTestState)();
         const order = (0, state_js_1.nextGoalOrder)();
+        const panelLog = openGoalPanelLog(order, options.step);
         const goalMeta = {
             precondition: options.precondition,
             step: options.step,
@@ -201,26 +299,50 @@ function createCyKeveGoal(engine) {
             };
         }
         // ── 确定性覆盖：fn 断言失败不允许被 Agent 判成 pass ──
+        // 覆盖发生在此处，事后无法从 reactResult 反推（conclusion 已被改写），
+        // 因此就地留痕，供面板与 errorMessage 说明「为什么和 Agent 的结论相反」。
+        let overriddenByFn = false;
         if (fnError && !fnBlocked && reactResult.expectedMet && (0, goal_heuristics_js_1.isAssertionFailure)(fnError)) {
             console.log(`[keveGoal] ⚠️ "${options.step}" Agent 判 PASS 但 fn 断言失败 — 覆盖为 FAIL`);
             reactResult.expectedMet = false;
             reactResult.conclusion = 'fail';
+            overriddenByFn = true;
         }
         const conclusion = reactResult.expectedMet ? 'pass' : (reactResult.conclusion || 'fail');
         const success = reactResult.expectedMet;
+        // 失败归因必须自带上下文：只报「哪一步 / 为什么」其中的一半，都要回查报告
+        // 才能定位。这里把第几步、步骤文案、fn 真实异常、Agent 判定理由一并带上。
+        const agentText = (reactResult.actions || [])
+            .filter((a) => a.action?.tool === 'done')
+            .pop()?.action?.text;
+        const failure = describeGoalFailure({
+            fnError,
+            fnBlocked,
+            shotDiff: fnErrorRaw?.name === 'ScreenshotDiffError',
+            assertion: Boolean(fnError && (0, goal_heuristics_js_1.isAssertionFailure)(fnError)),
+            overriddenByFn,
+            agentText,
+        });
+        const failureDetail = `期望:${clip(options.expected, 160)} ｜ 实际:${failure.actual} ｜ 判定:${failure.verdict}`;
         const errorMessage = success
             ? undefined
             : conclusion === 'blocked'
-                ? `Blocked: ${fnBlocked ? fnError : (reactResult.actions || []).filter((a) => a.action?.tool === 'done').pop()?.action?.text || 'Agent blocked'}`
+                ? `Blocked: [步骤${order + 1} ${options.step}] ${fnBlocked ? fnError : agentText || 'Agent blocked'}`
                 : fnErrorRaw?.name === 'ScreenshotDiffError'
-                    ? fnError
+                    ? `[步骤${order + 1} ${options.step}] ${fnError}`
                     : fnError && (0, goal_heuristics_js_1.isAssertionFailure)(fnError)
-                        ? `Assertion failed: ${fnError}`
-                        : `Expected not achieved: ${options.expected}`;
+                        ? `Assertion failed: [步骤${order + 1} ${options.step}] ${fnError}`
+                        : `Expected not achieved: [步骤${order + 1} ${options.step}] ${options.expected} — ${failure.actual}`;
         // 与 Playwright keve-test.ts 的终局日志同形，保证两端执行轨迹可逐行对照
         logLine(success
             ? `[keveGoal] ✅ "${options.step}" PASSED`
             : `[keveGoal] ❌ "${options.step}" FAILED (${conclusion}) — ${errorMessage}`);
+        closeGoalPanelLog(panelLog, success, errorMessage);
+        if (!success) {
+            // 主行红条 + 独立详情行：面板上不点开任何东西就能回答
+            // 第几步 / 期望什么 / 实际发生什么 / 谁判的。
+            appendGoalFailurePanelLine(order, failureDetail);
+        }
         // ── goal-after：优先取 agent done 时刻的截图，否则用 fn-after ──
         let goalScreenshotAfter = '';
         try {

package/dist/page-agent/tools.js

@@ -158,7 +158,9 @@ exports.tools.set('done', tool({
     execute: async function (input) {
         const icons = { pass: '✅', fail: '❌', blocked: '🚫' };
         let verdict = input.verdict;
-        // 强制校验：verdict 缺失或非法时从 text 推断（MacroTool 扁平化导致 verdict 变 optional）
+        // 强制校验：verdict 缺失或非法时从 text 推断（MacroTool 扁平化导致 verdict 变 optional）。
+        // verdict 与可推断文本都缺失时不能默认 pass —— Agent 已把动作做完但没给出结论，
+        // 交给上层按保守语义判定，而不是在工具层制造假绿。
         if (!icons[verdict]) {
             console.warn(`[done] ⚠️ verdict missing or invalid ("${input.verdict}"), inferring from text`);
             const t = String(input.text || '').toLowerCase();
@@ -168,9 +170,12 @@ exports.tools.set('done', tool({
             else if (t.includes('blocked') || t.includes('阻塞') || t.includes('阻止')) {
                 verdict = 'blocked';
             }
-            else {
+            else if (t.length > 0) {
                 verdict = 'pass'; // 有 text 且无否定词 → 默认 pass
             }
+            else {
+                throw new Error('done 缺少 verdict 且没有可推断的 text，不能默认判定通过');
+            }
         }
         return `${icons[verdict]} Task ${verdict}: ${input.text}`;
     },

package/package.json

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