pageqa 0.5.1 → 0.7.0

package/dist/locator.js

@@ -0,0 +1,255 @@
+/**
+ * 元素定位符（Locator）：把「这次点的是哪个元素」表达成跨快照可复用的语义描述。
+ *
+ * 背景：bsk 的 `@eN` 引用只在**产生它的那次快照**内有效，下一次 snapshot 编号会重排，
+ * 因此回放脚本不能直接存 `@eN`。bsk 快照文本是一棵缩进的 aria 树，每个可交互节点形如：
+ *
+ *     @e1 link "Learn more" [→ iana.org]
+ *
+ * 其中的「角色 + 可访问名」（role + name）才是稳定的语义信息：页面微调后仍能重新命中。
+ * 本模块负责在**录制时**把 target 解析成定位符，并在**回放时**用新的快照把它解析回 `@eN`。
+ *
+ * 定位符不保证唯一：同名元素可能有多个（列表每行都有「操作」按钮、页面级与区域级各有一个
+ * 「操作」下拉）。因此还记录两样东西：
+ * - `nth`：录制时在所有同名候选中排第几；
+ * - `path`：录制时该节点的**祖先路径**（只保留有名字的祖先）。
+ * 回放时优先用祖先路径消歧——「同名第几个」在页面里同类元素数量变化后会指错，
+ * 而「在哪个区域下」是更强、更抗漂移的信号。
+ */
+/** 是否为 bsk 快照引用（`@e1` 或 `e1`）。回放时引用必须重新解析，CSS 选择器则可直接用。 */
+export function isRef(target) {
+    return /^@?e\d+$/.test(target.trim());
+}
+/** 归一化引用写法：`e1` -> `@e1`。 */
+export function normalizeRef(target) {
+    const t = target.trim();
+    return t.startsWith("@") ? t : "@" + t;
+}
+/** 缩进宽度（tab 按 2 空格计，bsk 用空格缩进，这里只是保险）。 */
+function indentWidth(line) {
+    let n = 0;
+    for (const ch of line) {
+        if (ch === " ")
+            n += 1;
+        else if (ch === "\t")
+            n += 2;
+        else
+            break;
+    }
+    return n;
+}
+/** 取出 `role "name"` 形式的角色与可访问名。 */
+function parseRoleName(text) {
+    const roleMatch = text.match(/^([A-Za-z][A-Za-z0-9_-]*)/);
+    const nameMatch = text.match(/"([^"]*)"/);
+    return {
+        role: roleMatch ? roleMatch[1] : "",
+        name: nameMatch ? nameMatch[1] : "",
+    };
+}
+/**
+ * 路径条目的两个边界。
+ *
+ * 有些节点的可访问名是**整页文本**（如 `main "Dropdown 下拉菜单 将动作或菜单折叠到…"`），
+ * 直接存进脚本既撑大体积，又因为页面改一个字就失配而毫无消歧价值。
+ * 因此名字截断、层数只留最深的几层——深层（menu / tabpanel / dialog）才是真正区分区域的信息。
+ * 截断在录制与回放两侧执行同一套规则，所以比较依旧有效。
+ */
+const PATH_NAME_MAX = 60;
+const PATH_DEPTH_MAX = 3;
+/** 路径节点（有名字的祖先）的可读写法。 */
+function pathLabel(role, name) {
+    const shown = name.length > PATH_NAME_MAX
+        ? name.slice(0, PATH_NAME_MAX - 3) + "..."
+        : name;
+    return `${role || "?"} ${JSON.stringify(shown)}`;
+}
+/**
+ * 解析 bsk 快照文本里所有带引用的行，得到「引用 -> 角色/可访问名/祖先路径」。
+ *
+ * 缩进即层级：维护一个缩进栈，遇到更浅或同级的新行就弹出更深/同级的节点，
+ * 因此每个引用都能拿到「它在哪个区域（tabpanel / dialog / 某个标题）之下」。
+ * `@vom` / `@view` / `@layers` / `L1 page` 等元信息行不参与树。
+ */
+export function parseSnapshotRefs(snapshotText) {
+    const refs = [];
+    const stack = [];
+    for (const line of snapshotText.split(/\r?\n/)) {
+        const body = line.trim();
+        if (!body)
+            continue;
+        if (body.startsWith("@vom") ||
+            body.startsWith("@view") ||
+            body.startsWith("@layers") ||
+            /^L\d+\b/.test(body)) {
+            continue;
+        }
+        const indent = indentWidth(line);
+        const refMatch = body.match(/^@e(\d+)\b\s*(.*)$/);
+        const { role, name } = parseRoleName(refMatch ? refMatch[2] : body);
+        // 弹出所有「缩进 >= 当前」的节点，剩下的就是本行的祖先
+        while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
+            stack.pop();
+        }
+        if (refMatch) {
+            refs.push({
+                ref: `@e${refMatch[1]}`,
+                role,
+                name,
+                path: stack
+                    .map((e) => e.label)
+                    .filter((l) => l !== null)
+                    .slice(-PATH_DEPTH_MAX),
+            });
+        }
+        stack.push({
+            indent,
+            label: name ? pathLabel(role, name) : null,
+        });
+    }
+    return refs;
+}
+/**
+ * 录制时构造定位符：从当时的快照里查出该引用对应的角色/可访问名、同名序号与祖先路径。
+ *
+ * target 是 CSS 选择器（或快照里查不到的引用）时，定位符退化为「只有 target 兜底」，
+ * 回放时直接按原 target 操作。
+ */
+export function buildLocator(target, snapshotText) {
+    const original = target.trim();
+    const bare = {
+        role: "",
+        name: "",
+        nth: -1,
+        target: original,
+        path: [],
+    };
+    if (!isRef(original))
+        return bare;
+    const ref = normalizeRef(original);
+    const refs = parseSnapshotRefs(snapshotText);
+    const self = refs.find((r) => r.ref === ref);
+    // 快照里查不到（例如模型用了一次更早快照的引用）：没有语义信息可用，只能留 target 兜底
+    if (!self)
+        return bare;
+    if (!self.role && !self.name)
+        return bare;
+    const same = refs.filter((r) => r.role === self.role && r.name === self.name);
+    const nth = same.findIndex((r) => r.ref === ref);
+    return {
+        role: self.role,
+        name: self.name,
+        nth,
+        target: original,
+        path: self.path,
+    };
+}
+/**
+ * 祖先路径的匹配度：从最深一级往上数，连续相同的层数。
+ * 只比尾部——页面结构微调通常发生在中间层，根节点往往没变。
+ */
+function pathScore(want, got) {
+    let score = 0;
+    const depth = Math.min(want.length, got.length);
+    for (let i = 1; i <= depth; i++) {
+        if (want[want.length - i] !== got[got.length - i])
+            break;
+        score += 1;
+    }
+    return score;
+}
+/**
+ * 回放时用**新的**快照把定位符解析回 `@eN`。
+ *
+ * 匹配策略逐级放宽，都不中则返回 null（由调用方决定退回 target 还是报错）：
+ *   1. role + name 全等（最常见，页面没变时必然命中）
+ *   2. role 相同且 name 包含（文案被加了前后缀，如「操作」→「操作 更多」）
+ *   3. 只看 name（角色被前端改过，如 button 变 a）
+ *
+ * 命中多个候选时，先按**祖先路径**消歧（「结构」tab 下的「操作」与产品级的「操作」
+ * 名字完全一样，只有所属区域能区分），路径也无法区分时才退回录制的同名序号 `nth`。
+ */
+export function resolveLocator(locator, snapshotText) {
+    const name = locator.name;
+    const role = locator.role;
+    if (!name && !role)
+        return null;
+    const refs = parseSnapshotRefs(snapshotText);
+    const exact = refs.filter((r) => r.role === role && r.name === name);
+    const fuzzy = exact.length
+        ? exact
+        : refs.filter((r) => r.role === role && name.length > 0 && r.name.includes(name));
+    const pool = fuzzy.length
+        ? fuzzy
+        : refs.filter((r) => name.length > 0 && r.name === name);
+    if (!pool.length)
+        return null;
+    if (pool.length === 1)
+        return pool[0].ref;
+    const path = locator.path ?? [];
+    if (path.length > 0) {
+        const scored = pool
+            .map((r) => ({ ref: r.ref, score: pathScore(path, r.path) }))
+            .filter((c) => c.score > 0)
+            .sort((a, b) => b.score - a.score);
+        if (scored.length > 0) {
+            const best = scored[0].score;
+            const top = scored.filter((c) => c.score === best);
+            if (top.length === 1)
+                return top[0].ref;
+            return top[locator.nth >= 0 && locator.nth < top.length ? locator.nth : 0]
+                .ref;
+        }
+    }
+    const idx = locator.nth >= 0 && locator.nth < pool.length ? locator.nth : 0;
+    return pool[idx].ref;
+}
+/**
+ * 定位不到时给出「当前页面里有什么」的线索。
+ *
+ * 「元素未找到」本身是条死路，用户只知道某步挂了。区分三种情况后，报告能直接回答
+ * 「是弹窗没打开」「是菜单点错了一个」还是「元素改名了」，用户据此就能判断该改脚本还是改用例。
+ */
+export function locatorHint(locator, snapshotText, limit = 3) {
+    const refs = parseSnapshotRefs(snapshotText);
+    const sameRole = refs.filter((r) => r.role === locator.role);
+    const head = locator.name.slice(0, 2);
+    const similar = head
+        ? sameRole.filter((r) => r.name.includes(head))
+        : [];
+    if (similar.length > 0) {
+        return {
+            kind: "similar-name",
+            items: similar.slice(0, limit).map((r) => pathLabel(r.role, r.name)),
+            roleCount: sameRole.length,
+        };
+    }
+    if (sameRole.length === 0) {
+        return { kind: "no-role", items: [], roleCount: 0 };
+    }
+    return {
+        kind: "role-only",
+        items: sameRole
+            .filter((r) => r.name)
+            .slice(0, limit)
+            .map((r) => pathLabel(r.role, r.name)),
+        roleCount: sameRole.length,
+    };
+}
+/** 定位符的可读描述，用于报告与日志（说明「当时点的是什么、在哪个区域」）。 */
+export function describeLocator(locator) {
+    if (!locator)
+        return "无定位符";
+    const parts = [];
+    if (locator.role)
+        parts.push(`role=${locator.role}`);
+    if (locator.name)
+        parts.push(`name=${JSON.stringify(locator.name)}`);
+    if (locator.nth > 0)
+        parts.push(`第 ${locator.nth + 1} 个同名元素`);
+    const area = locator.path?.at(-1);
+    if (area)
+        parts.push(`位于 ${area} 之下`);
+    return parts.length ? parts.join(" ") : `target=${locator.target}`;
+}
+//# sourceMappingURL=locator.js.map

package/dist/locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.js","sourceRoot":"","sources":["../src/locator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA4BH,2DAA2D;AAC3D,MAAM,UAAU,KAAK,CAAC,MAAc;IAClC,OAAO,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;AACxC,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IACxB,OAAO,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;AACzC,CAAC;AAED,0CAA0C;AAC1C,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,IAAI,EAAE,KAAK,GAAG;YAAE,CAAC,IAAI,CAAC,CAAC;aAClB,IAAI,EAAE,KAAK,IAAI;YAAE,CAAC,IAAI,CAAC,CAAC;;YACxB,MAAM;IACb,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,mCAAmC;AACnC,SAAS,aAAa,CAAC,IAAY;IACjC,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAC1C,OAAO;QACL,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE;QACnC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE;KACpC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,aAAa,GAAG,EAAE,CAAC;AACzB,MAAM,cAAc,GAAG,CAAC,CAAC;AAEzB,yBAAyB;AACzB,SAAS,SAAS,CAAC,IAAY,EAAE,IAAY;IAC3C,MAAM,KAAK,GACT,IAAI,CAAC,MAAM,GAAG,aAAa;QACzB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,GAAG,CAAC,CAAC,GAAG,KAAK;QAC1C,CAAC,CAAC,IAAI,CAAC;IACX,OAAO,GAAG,IAAI,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,YAAoB;IACpD,MAAM,IAAI,GAAkB,EAAE,CAAC;IAC/B,MAAM,KAAK,GAA+C,EAAE,CAAC;IAE7D,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,IACE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;YACvB,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;YACxB,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;YAC1B,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EACpB,CAAC;YACD,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAEjC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;QAClD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAEpE,+BAA+B;QAC/B,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM,IAAI,MAAM,EAAE,CAAC;YACpE,KAAK,CAAC,GAAG,EAAE,CAAC;QACd,CAAC;QACD,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,CAAC,IAAI,CAAC;gBACR,GAAG,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE;gBACvB,IAAI;gBACJ,IAAI;gBACJ,IAAI,EAAE,KAAK;qBACR,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;qBACnB,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC;qBACtC,KAAK,CAAC,CAAC,cAAc,CAAC;aAC1B,CAAC,CAAC;QACL,CAAC;QACD,KAAK,CAAC,IAAI,CAAC;YACT,MAAM;YACN,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;SAC3C,CAAC,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,YAAoB;IAC/D,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAY;QACpB,IAAI,EAAE,EAAE;QACR,IAAI,EAAE,EAAE;QACR,GAAG,EAAE,CAAC,CAAC;QACP,MAAM,EAAE,QAAQ;QAChB,IAAI,EAAE,EAAE;KACT,CAAC;IACF,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IAC7C,iDAAiD;IACjD,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9E,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IACjD,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG;QACH,MAAM,EAAE,QAAQ;QAChB,IAAI,EAAE,IAAI,CAAC,IAAI;KAChB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,SAAS,CAAC,IAAc,EAAE,GAAa;IAC9C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAChD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;YAAE,MAAM;QACzD,KAAK,IAAI,CAAC,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAgB,EAChB,YAAoB;IAEpB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1B,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,IAAI,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACrE,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM;QACxB,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,IAAI,CAAC,MAAM,CACT,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CACnE,CAAC;IACN,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM;QACvB,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAC3D,IAAI,CAAC,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAE1C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC;IAChC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,IAAI;aAChB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;aAC5D,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;aAC1B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YAC7B,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;YACnD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;YACxC,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;iBACvE,GAAG,CAAC;QACT,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;AACvB,CAAC;AAYD;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,OAAgB,EAChB,YAAoB,EACpB,KAAK,GAAG,CAAC;IAET,MAAM,IAAI,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI;QAClB,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC/C,CAAC,CAAC,EAAE,CAAC;IACP,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO;YACL,IAAI,EAAE,cAAc;YACpB,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YACpE,SAAS,EAAE,QAAQ,CAAC,MAAM;SAC3B,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IACtD,CAAC;IACD,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,QAAQ;aACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;aACrB,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;aACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACxC,SAAS,EAAE,QAAQ,CAAC,MAAM;KAC3B,CAAC;AACJ,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,eAAe,CAAC,OAAuB;IACrD,IAAI,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC;IAC5B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACrD,IAAI,OAAO,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrE,IAAI,OAAO,CAAC,GAAG,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAClC,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC;IACtC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,OAAO,CAAC,MAAM,EAAE,CAAC;AACrE,CAAC"}

package/dist/record.d.ts

@@ -0,0 +1,50 @@
+import type { ReplayStep } from "./replay.js";
+import { type RunVarValue } from "./vars.js";
+/** 工具层上报的一次执行（ok=false 表示 bsk 报错，录制时会被忽略）。 */
+export interface ToolExecEvent {
+    /** 工具名：navigate / snapshot / click / fill / upload / hover / scroll / wait / assert_text。 */
+    name: string;
+    /** 模型给出的入参。 */
+    params: Record<string, unknown>;
+    ok: boolean;
+    /** 本次操作前页面最后一次快照文本（用于构造语义定位符）。 */
+    lastSnapshot: string;
+}
+export interface RecorderOptions {
+    /**
+     * 本次带模型的运行是否启用了 Jev 语义断言。
+     *
+     * 需要记下来：Jev 允许模型用「标题包含 Example」这种语义化措辞做断言，
+     * 而回放默认是字符串包含匹配，这类断言在回放时会误报失败。
+     * 脚本里标记该断言是语义录制的，回放失败时才能给出「加 --semantic 重试」的提示。
+     */
+    semantic?: boolean;
+}
+export declare class Recorder {
+    private readonly vars;
+    private readonly steps;
+    private lastCompletedStep;
+    /** 整场运行是否解析到过步骤自述；一次都没解析到时不给步骤号（见 recorded）。 */
+    private sawNarration;
+    /** 自述的尾部缓冲，用于跨 delta 匹配（流式输出会把「完成」切开）。 */
+    private tail;
+    private readonly semantic;
+    constructor(vars?: RunVarValue[], options?: RecorderOptions);
+    /**
+     * 喂入模型输出的文本增量，跟踪「已完成到第几步」。
+     *
+     * 模型是先调用工具、再自述「第 k 步完成：…」，因此某个工具调用归属哪一步只能用
+     * 「它之前最后一次自述 + 1」来近似——映射不准时退化为 null，不影响回放正确性。
+     */
+    noteText(delta: string): void;
+    /** 记录一次工具执行。仅成功的操作会进入脚本；`snapshot` 不记录（回放不需要「看」）。 */
+    noteTool(event: ToolExecEvent): void;
+    /**
+     * 当前已录制的步骤快照。
+     *
+     * 整场运行一次都没解析到步骤自述时，把步骤号一律留空：
+     * 全部指向「第 1 步」是自信的错误，报告会指着用例第一行说「卡在这里」，
+     * 比如实留空更误导。
+     */
+    get recorded(): ReplayStep[];
+}

package/dist/record.js

@@ -0,0 +1,167 @@
+/**
+ * 录制层：把一次带模型的运行里**成功执行过的浏览器操作**记成可回放的步骤。
+ *
+ * 两个关键判断：
+ * - 只记成功的操作。失败的尝试是模型探索过程的一部分（它随后会重试别的元素），
+ *   记下来只会让回放照着踩坑。
+ * - 记语义定位符而不是 `@eN`。`@eN` 只在当时那次快照内有效（见 locator.ts）。
+ */
+import { buildLocator } from "./locator.js";
+import { restorePlaceholders } from "./vars.js";
+/**
+ * 从模型输出的自述里取「第 k 步完成」，用于把操作映射回用例步骤号。
+ *
+ * 模型写法并不统一，实测见过「第 3 步完成」「第3步已完成」「步骤 3 完成」「步骤 3：完成」。
+ * 只认第一种会让整场运行的步骤映射全部落到第 1 步——比映射不出来更糟（报告会指错用例行）。
+ */
+const STEP_DONE_PATTERNS = [
+    /第\s*(\d+)\s*步\s*(?:已)?\s*完\s*成/g,
+    /步\s*骤\s*(\d+)\s*(?:已)?\s*完\s*成/g,
+];
+/** 自述可能被流式输出切在「完/成」之间，保留一小段尾巴拼回来再匹配。 */
+const NARRATION_TAIL = 64;
+export class Recorder {
+    vars;
+    steps = [];
+    lastCompletedStep = 0;
+    /** 整场运行是否解析到过步骤自述；一次都没解析到时不给步骤号（见 recorded）。 */
+    sawNarration = false;
+    /** 自述的尾部缓冲，用于跨 delta 匹配（流式输出会把「完成」切开）。 */
+    tail = "";
+    semantic;
+    constructor(vars = [], options = {}) {
+        this.vars = vars;
+        this.semantic = options.semantic ?? false;
+    }
+    /**
+     * 喂入模型输出的文本增量，跟踪「已完成到第几步」。
+     *
+     * 模型是先调用工具、再自述「第 k 步完成：…」，因此某个工具调用归属哪一步只能用
+     * 「它之前最后一次自述 + 1」来近似——映射不准时退化为 null，不影响回放正确性。
+     */
+    noteText(delta) {
+        // 在「上一段尾巴 + 本次增量」上匹配：只取已完成的步骤号（取最大值），
+        // 因此重叠窗口造成的重复命中无害。
+        const window = this.tail + delta;
+        for (const pattern of STEP_DONE_PATTERNS) {
+            pattern.lastIndex = 0;
+            let m;
+            while ((m = pattern.exec(window)) !== null) {
+                this.sawNarration = true;
+                this.lastCompletedStep = Math.max(this.lastCompletedStep, Number(m[1]));
+            }
+        }
+        this.tail = window.slice(-NARRATION_TAIL);
+    }
+    /** 记录一次工具执行。仅成功的操作会进入脚本；`snapshot` 不记录（回放不需要「看」）。 */
+    noteTool(event) {
+        if (!event.ok)
+            return;
+        const step = this.lastCompletedStep + 1;
+        const p = event.params ?? {};
+        const text = (key) => String(p[key] ?? "");
+        const restore = (value) => restorePlaceholders(value, this.vars);
+        /** target + 定位符（target 为空时不做定位符解析）。 */
+        const targetOf = () => {
+            const target = restore(text("target").trim());
+            const locator = target
+                ? buildLocator(target, event.lastSnapshot)
+                : null;
+            return {
+                target,
+                // 定位符的「可访问名」同样要还原占位符：列表里点的是「刚刚创建的那条」
+                // （如 `自动化测试产品${timestamp}`），名字里若写死录制当次的时间戳，
+                // 回放时新时间戳对不上，这一步必然定位失败。
+                locator: locator
+                    ? { ...locator, name: restore(locator.name) }
+                    : null,
+            };
+        };
+        switch (event.name) {
+            case "navigate":
+                this.steps.push({
+                    kind: "navigate",
+                    step,
+                    url: restore(text("url")),
+                });
+                return;
+            case "click":
+            case "hover":
+            case "scroll": {
+                const { target, locator } = targetOf();
+                if (!target)
+                    return;
+                this.steps.push({ kind: event.name, step, target, locator });
+                return;
+            }
+            case "fill": {
+                const { target, locator } = targetOf();
+                if (!target)
+                    return;
+                const raw = text("value");
+                const value = restore(raw);
+                this.steps.push({
+                    kind: "fill",
+                    step,
+                    target,
+                    value,
+                    // 占位符被还原时留一份「录制当次真正填了什么」，便于人工核对
+                    ...(value !== raw ? { recordedValue: raw } : {}),
+                    locator,
+                });
+                return;
+            }
+            case "upload": {
+                const { target, locator } = targetOf();
+                this.steps.push({
+                    kind: "upload",
+                    step,
+                    file: restore(text("file")),
+                    ...(target ? { target, locator } : { locator: null }),
+                });
+                return;
+            }
+            case "wait": {
+                const ms = Number(p["ms"]);
+                this.steps.push({
+                    kind: "wait",
+                    step,
+                    ms: Number.isFinite(ms) && ms > 0 ? ms : 1000,
+                });
+                return;
+            }
+            case "assert_text": {
+                const raw = text("expectation");
+                if (!raw)
+                    return;
+                const expectation = restore(raw);
+                this.steps.push({
+                    kind: "assert_text",
+                    step,
+                    expectation,
+                    ...(expectation !== raw ? { recordedExpectation: raw } : {}),
+                    // 语义录制的断言在字符串匹配下可能误报，标记出来供回放给出提示
+                    ...(this.semantic ? { semantic: true } : {}),
+                });
+                return;
+            }
+            default:
+                // snapshot 以及未知工具：不进入回放脚本
+                return;
+        }
+    }
+    /**
+     * 当前已录制的步骤快照。
+     *
+     * 整场运行一次都没解析到步骤自述时，把步骤号一律留空：
+     * 全部指向「第 1 步」是自信的错误，报告会指着用例第一行说「卡在这里」，
+     * 比如实留空更误导。
+     */
+    get recorded() {
+        const steps = [...this.steps];
+        if (this.sawNarration)
+            return steps;
+        return steps.map((s) => ({ ...s, step: null }));
+    }
+}
+//# sourceMappingURL=record.js.map

package/dist/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"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"}