@kkeve/suite 0.0.15 → 0.0.18

package/dist/core/judge/pngCodec.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * pngCodec — 纯 Node PNG 编解码（零依赖，zlib 内置）
+ *
+ * 为什么不用 pngjs/pixelmatch：@kkeve/suite 依赖树里没有这两个包，
+ * 执行环境（keve-wiki / 调度节点）也不保证能现场安装 —— 而引擎侧截图对比
+ * 是核心链路，不能带可选依赖。Playwright 截图恒为 8-bit、非交错、
+ * colorType 2(RGB)/6(RGBA)，覆盖这两类 + 灰度(0/4)即可覆盖全部引擎产物。
+ *
+ * 支持范围（超出范围抛错，不静默出错误结果）：
+ *   - bitDepth: 8
+ *   - colorType: 0(灰度) / 2(RGB) / 4(灰+A) / 6(RGBA)
+ *   - interlace: 0（Progressive PNG 抛错）
+ */
+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.decodePng = decodePng;
+exports.encodePng = encodePng;
+const zlib = __importStar(require("node:zlib"));
+// ── CRC32 ──
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/** Paeth 预测器（PNG 规范 §6.4） */
+function paeth(a, b, c) {
+    const p = a + b - c;
+    const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+    return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+/** 解码 PNG → RGBA。仅支持 8-bit / colorType 0,2,4,6 / 非交错 */
+function decodePng(buf) {
+    if (buf.length < 8 || !buf.subarray(0, 8).equals(PNG_SIGNATURE)) {
+        throw new Error('pngCodec: 不是合法的 PNG 文件（签名不符）');
+    }
+    let width = 0, height = 0, bitDepth = 0, colorType = -1, interlace = 0;
+    const idatParts = [];
+    let pos = 8;
+    while (pos + 8 <= buf.length) {
+        const len = buf.readUInt32BE(pos);
+        const type = buf.toString('ascii', pos + 4, pos + 8);
+        const data = buf.subarray(pos + 8, pos + 8 + len);
+        pos += 12 + len; // length + type + data + crc
+        if (type === 'IHDR') {
+            width = data.readUInt32BE(0);
+            height = data.readUInt32BE(4);
+            bitDepth = data[8];
+            colorType = data[9];
+            interlace = data[12];
+        }
+        else if (type === 'IDAT') {
+            idatParts.push(Buffer.from(data));
+        }
+        else if (type === 'IEND') {
+            break;
+        }
+    }
+    if (!width || !height)
+        throw new Error('pngCodec: IHDR 缺失或非法');
+    if (bitDepth !== 8)
+        throw new Error(`pngCodec: 不支持 bitDepth=${bitDepth}（仅支持 8，Playwright 截图恒为 8）`);
+    if (interlace !== 0)
+        throw new Error('pngCodec: 不支持交错 PNG（Progressive）');
+    const channelsByColor = { 0: 1, 2: 3, 4: 2, 6: 4 };
+    const channels = channelsByColor[colorType];
+    if (!channels)
+        throw new Error(`pngCodec: 不支持 colorType=${colorType}（仅支持 0/2/4/6）`);
+    const raw = zlib.inflateSync(Buffer.concat(idatParts));
+    const stride = width * channels;
+    if (raw.length < (stride + 1) * height) {
+        throw new Error(`pngCodec: IDAT 数据不足（期望 ${(stride + 1) * height} 字节，实际 ${raw.length}）`);
+    }
+    // 反滤波（逐扫描线）
+    const out = new Uint8Array(width * height * 4);
+    const prev = new Uint8Array(stride);
+    const cur = new Uint8Array(stride);
+    for (let y = 0; y < height; y++) {
+        const rowStart = y * (stride + 1);
+        const filter = raw[rowStart];
+        for (let i = 0; i < stride; i++) {
+            const x = raw[rowStart + 1 + i];
+            const a = i >= channels ? cur[i - channels] : 0;
+            const b = prev[i];
+            const c = i >= channels ? prev[i - channels] : 0;
+            let v;
+            switch (filter) {
+                case 0:
+                    v = x;
+                    break;
+                case 1:
+                    v = x + a;
+                    break;
+                case 2:
+                    v = x + b;
+                    break;
+                case 3:
+                    v = x + ((a + b) >> 1);
+                    break;
+                case 4:
+                    v = x + paeth(a, b, c);
+                    break;
+                default: throw new Error(`pngCodec: 非法滤波类型 ${filter}（行 ${y}）`);
+            }
+            cur[i] = v & 0xff;
+        }
+        // 展开为 RGBA
+        const o = y * width * 4;
+        for (let x = 0; x < width; x++) {
+            const s = x * channels;
+            if (colorType === 6) {
+                out[o + x * 4] = cur[s];
+                out[o + x * 4 + 1] = cur[s + 1];
+                out[o + x * 4 + 2] = cur[s + 2];
+                out[o + x * 4 + 3] = cur[s + 3];
+            }
+            else if (colorType === 2) {
+                out[o + x * 4] = cur[s];
+                out[o + x * 4 + 1] = cur[s + 1];
+                out[o + x * 4 + 2] = cur[s + 2];
+                out[o + x * 4 + 3] = 255;
+            }
+            else if (colorType === 0) {
+                out[o + x * 4] = out[o + x * 4 + 1] = out[o + x * 4 + 2] = cur[s];
+                out[o + x * 4 + 3] = 255;
+            }
+            else { // 4: 灰+alpha
+                out[o + x * 4] = out[o + x * 4 + 1] = out[o + x * 4 + 2] = cur[s];
+                out[o + x * 4 + 3] = cur[s + 1];
+            }
+        }
+        prev.set(cur);
+    }
+    return { width, height, data: out };
+}
+// ── Encode ──
+function chunk(type, data) {
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length, 0);
+    const typeBuf = Buffer.from(type, 'ascii');
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])), 0);
+    return Buffer.concat([len, typeBuf, data, crc]);
+}
+/** RGBA → PNG（colorType 6，filter 0）。data 长度必须为 w*h*4 */
+function encodePng(width, height, data) {
+    if (data.length !== width * height * 4) {
+        throw new Error(`pngCodec: encodePng 数据长度不符（期望 ${width * height * 4}，实际 ${data.length}）`);
+    }
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 8; // bitDepth
+    ihdr[9] = 6; // colorType RGBA
+    ihdr[10] = 0; // compression
+    ihdr[11] = 0; // filter
+    ihdr[12] = 0; // interlace
+    // filter 0 逐行打包
+    const raw = Buffer.alloc((width * 4 + 1) * height);
+    for (let y = 0; y < height; y++) {
+        raw[y * (width * 4 + 1)] = 0;
+        Buffer.from(data.buffer, data.byteOffset + y * width * 4, width * 4)
+            .copy(raw, y * (width * 4 + 1) + 1);
+    }
+    return Buffer.concat([
+        PNG_SIGNATURE,
+        chunk('IHDR', ihdr),
+        chunk('IDAT', zlib.deflateSync(raw, { level: 6 })),
+        chunk('IEND', Buffer.alloc(0)),
+    ]);
+}

package/dist/core/judge/screenshotDiff.d.ts

@@ -0,0 +1,112 @@
+/**
+ * screenshotDiff — 截图基线对比（平台「截图基线」断言的引擎侧实现）
+ *
+ * 判定语义（对齐《keve 统一用例工作台与场景插件完整方案》§2 视觉优先修正 + §9.5 首跑闭环）：
+ *   无基线            → status 'baseline_required'：保存候选基线（state=candidate），
+ *                        首跑**不算通过**，差异率为 null，需人工审核转正后再次运行才做正式比对
+ *   表里已有候选      → status 'baseline_required'：未审核候选不得作为正式有效基线，
+ *                        不做像素比对、不判 matched/exceeded（差异率 null）
+ *   截图尺寸变化      → status 'size_mismatch'：不得因 viewport 变化自动重新自举来掩盖变化；
+ *                        按原 key+env 定位既有基线并明确报告尺寸差异
+ *   diffRatio ≤ 阈值  → status 'matched'：静默通过，仅记录证据（仅对 state=active 的基线）
+ *   diffRatio > 阈值  → status 'exceeded'：抛 ScreenshotDiffError（确定性事实，AI 不可翻案；
+ *                        keveGoal 对该错误短路跳过 Agent Re-Act —— diff 不是探索能修复的）
+ *
+ * 基线存储：<KEVE_BASELINE_DIR|cwd/baselines>/{key}.{env}.{w}x{h}.png + .meta.json
+ *   meta: { version, state: 'candidate'|'active', sourceType, threshold, masks, updatedAt }
+ *   key 建议沿用老平台基线 id（如 step-24497），可回溯迁移来源。
+ *
+ * 证据产物：actual 截图与 diff 热区图落盘 test-artifacts，路径写入结果，
+ * 由 keveGoalResult attachment 流到平台 stepsDetail 回收（evidence.screenshotDiff）。
+ */
+export interface ShotDiffRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface ShotDiffRegion extends ShotDiffRect {
+    /** 区块内差异像素占区块像素比例（%） */
+    ratio: number;
+}
+export interface ShotDiffResult {
+    key: string;
+    /** matched=比对一致（active 基线）｜exceeded=超阈值（抛错）｜baseline_required=无基线/候选未审核（不算通过）｜size_mismatch=尺寸变化不自举 */
+    status: 'matched' | 'exceeded' | 'baseline_required' | 'size_mismatch';
+    /** 差异率（%，全图像素口径）；baseline_required / size_mismatch 时为 null（不是 0） */
+    diffRatio: number | null;
+    threshold: number;
+    baselineVersion: number;
+    baselineState?: 'candidate' | 'active';
+    baselinePath: string;
+    /** 当前实际截图（绝对路径） */
+    actualPath: string;
+    /** 差异热区图（绝对路径，status=created 时与 actualPath 相同） */
+    diffPath: string;
+    env: string;
+    viewport: string;
+    regions: ShotDiffRegion[];
+    /** 供报告/AI 复核的一句话结论 */
+    message: string;
+    comparedAt: string;
+}
+export interface ExpectScreenshotOptions {
+    /** 差异率阈值（%），缺省取 KEVE_SHOT_DIFF_THRESHOLD（默认 1.0） */
+    threshold?: number;
+    /** 全页截图（默认视口截图） */
+    fullPage?: boolean;
+    /** 临时掩码（本次生效；持久掩码在基线 meta.masks） */
+    mask?: ShotDiffRect[];
+}
+/** 超阈值错误：携带完整对比结果，keveGoal 据此短路并透传 attachment */
+export declare class ScreenshotDiffError extends Error {
+    shotDiff: ShotDiffResult;
+    constructor(result: ShotDiffResult);
+}
+export declare function baselineDir(): string;
+export interface BaselinePaths {
+    pngPath: string;
+    metaPath: string;
+    env: string;
+    viewport: string;
+    width: number;
+    height: number;
+}
+/** 基线路径 = {safeKey}.{env}.{w}x{h} —— env×viewport 进 key，避免跨环境/跨视口假差异 */
+export declare function resolveBaselinePaths(key: string, width: number, height: number): BaselinePaths;
+/**
+ * 按 key+env 查找已存在基线（任意视口）。
+ * 命中表示「该目标曾建档」——此时若精确视口不存在，属于**截图尺寸变化**，
+ * 不允许重新自举成新候选来掩盖变化（方案 §9.4 / A20）。
+ */
+export declare function findBaselineByKeyEnv(key: string, preferWidth?: number, preferHeight?: number): BaselinePaths | null;
+export interface BaselineMeta {
+    version: number;
+    state: 'candidate' | 'active';
+    sourceType?: 'first-run' | 'imported' | 'manual';
+    sourceUrl?: string;
+    threshold: number;
+    masks: ShotDiffRect[];
+    updatedAt: string;
+}
+/** 无基线：保存候选基线，返回 created（判 PASS） */
+export declare function createBaseline(key: string, png: Buffer, opts?: {
+    sourceUrl?: string;
+    threshold?: number;
+}): ShotDiffResult;
+/**
+ * 有基线：像素对比 → matched（≤阈值，pass）/ exceeded（>阈值，抛 ScreenshotDiffError）。
+ * 尺寸不一致按重叠区对比并在 message 中注明（视口不变的常规场景不受影响）。
+ */
+export declare function compareWithBaseline(key: string, png: Buffer, opts?: {
+    threshold?: number;
+    mask?: ShotDiffRect[];
+}): ShotDiffResult;
+/** keveGoal 执行 fn 前调用：开始收集本 goal 内的对比结果 */
+export declare function beginGoalShotDiffCapture(): void;
+/** 当前是否处于 goal 收集期（engine 判断是否需要自开临时缓冲） */
+export declare function isGoalShotDiffCaptureActive(): boolean;
+/** keveGoal fn 结束（无论成败）后调用：取出本 goal 的全部对比结果 */
+export declare function drainGoalShotDiff(): ShotDiffResult[];
+/** engine.expectScreenshot 内部调用：记录到当前 goal 缓冲（若在收集期） */
+export declare function recordShotDiff(r: ShotDiffResult): void;