minimal-agent 0.12.0 → 0.14.0

package/src/tools/webbrowser/browserFrames.ts

@@ -0,0 +1,54 @@
+export type BrowserFrameInfo = {
+  id: string;
+  parentId?: string;
+  url: string;
+  name?: string;
+};
+
+/** Fixed, read-only expression for observing nested same-origin frame trees. */
+export const FRAME_INFO_EXPRESSION = `(() => { const walk = (doc, parentId = '', path = '') => Array.from(doc.querySelectorAll('iframe,frame')).flatMap((el, index) => { const id = 'dom-frame-' + (path ? path + '-' : '') + index; const item = { id, ...(parentId ? { parentId } : {}), url: el.src || '', name: el.name || undefined }; try { return [item, ...walk(el.contentDocument, id, id.replace('dom-frame-', ''))]; } catch { return [item]; } }); return walk(document); })()`;
+
+/** Normalize the recursive, browser-owned frame tree returned by CDP. */
+export function normalizeFrameTree(value: unknown): BrowserFrameInfo[] {
+  const frames: BrowserFrameInfo[] = [];
+  const walk = (node: unknown, parentId?: string): void => {
+    if (!node || typeof node !== 'object') return;
+    const item = node as {
+      frame?: { id?: unknown; url?: unknown; name?: unknown };
+      childFrames?: unknown[];
+    };
+    if (typeof item.frame?.id !== 'string' || !item.frame.id) return;
+    const id = item.frame.id;
+    frames.push({
+      id,
+      ...(parentId ? { parentId } : {}),
+      url: typeof item.frame.url === 'string' ? item.frame.url : '',
+      ...(typeof item.frame.name === 'string' && item.frame.name
+        ? { name: item.frame.name }
+        : {}),
+    });
+    for (const child of item.childFrames ?? []) walk(child, id);
+  };
+  walk(value);
+  return frames;
+}
+
+export function normalizeFrameInfo(value: unknown): BrowserFrameInfo[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((item) => {
+    if (!item || typeof item !== 'object') return [];
+    const frame = item as Record<string, unknown>;
+    if (typeof frame.id !== 'string' || typeof frame.url !== 'string')
+      return [];
+    return [
+      {
+        id: frame.id,
+        url: frame.url,
+        ...(typeof frame.parentId === 'string'
+          ? { parentId: frame.parentId }
+          : {}),
+        ...(typeof frame.name === 'string' ? { name: frame.name } : {}),
+      },
+    ];
+  });
+}

package/src/tools/webbrowser/browserInteractionResolver.js

@@ -0,0 +1,17 @@
+export function resolveInteractionStrategy(target) {
+    if (target.locator?.by === 'ax')
+        return 'ax';
+    if (target.locator?.by === 'role' ||
+        target.locator?.by === 'label' ||
+        target.locator?.by === 'text' ||
+        target.locator?.by === 'placeholder' ||
+        target.locator?.by === 'testid')
+        return 'role-locator';
+    if (target.locator || target.selector)
+        return 'playwright-locator';
+    if (target.node_id !== undefined)
+        return 'dom-cua';
+    if (target.x !== undefined && target.y !== undefined)
+        return 'visual-coordinate';
+    return 'cdp';
+}

package/src/tools/webbrowser/browserInteractionResolver.ts

@@ -0,0 +1,40 @@
+/**
+ * Deterministic interaction strategy selection shared by batch results and
+ * future adapters. MCP/WebMCP is intentionally absent: this project uses the
+ * visible supervised browser and falls back through its strongest local
+ * representation.
+ */
+export type BrowserInteractionStrategy =
+  | 'ax'
+  | 'role-locator'
+  | 'playwright-locator'
+  | 'dom-cua'
+  | 'visual-coordinate'
+  | 'cdp';
+
+export type BrowserInteractionTarget = {
+  locator?: { by?: string };
+  selector?: string;
+  node_id?: number;
+  x?: number;
+  y?: number;
+};
+
+export function resolveInteractionStrategy(
+  target: BrowserInteractionTarget,
+): BrowserInteractionStrategy {
+  if (target.locator?.by === 'ax') return 'ax';
+  if (
+    target.locator?.by === 'role' ||
+    target.locator?.by === 'label' ||
+    target.locator?.by === 'text' ||
+    target.locator?.by === 'placeholder' ||
+    target.locator?.by === 'testid'
+  )
+    return 'role-locator';
+  if (target.locator || target.selector) return 'playwright-locator';
+  if (target.node_id !== undefined) return 'dom-cua';
+  if (target.x !== undefined && target.y !== undefined)
+    return 'visual-coordinate';
+  return 'cdp';
+}

package/src/tools/webbrowser/browserLocator.js

@@ -0,0 +1,140 @@
+/**
+ * Browser locators shared by BrowserBatch and future visible-DOM adapters.
+ *
+ * This deliberately emits a small, self-contained browser expression instead
+ * of retaining DOM node handles.  A locator is resolved again for every step,
+ * so a navigation or React re-render cannot silently reuse a stale element.
+ */
+const quote = (value) => JSON.stringify(value);
+/** Build an expression returning `Element[]` in the selected document. */
+export function buildLocatorExpression(locator, selector, rootExpression = 'document') {
+    if (selector) {
+        return `Array.from(${rootExpression}.querySelectorAll(${quote(selector)}))`;
+    }
+    if (!locator)
+        throw new Error('step requires selector or locator');
+    if (locator.by === 'ax') {
+        throw new Error('AX locator must be resolved against the live accessibility tree first');
+    }
+    const root = locator.within
+        ? `${buildLocatorExpression(locator.within, undefined, rootExpression)}.flatMap((scope) => Array.from(scope.querySelectorAll('*')))`
+        : `Array.from(${rootExpression}.querySelectorAll('*'))`;
+    const value = quote(locator.value);
+    const exact = locator.exact === true;
+    const compare = (expression, expected = value) => exact
+        ? `${expression}.trim()===${expected}`
+        : `${expression}.includes(${expected})`;
+    let predicate;
+    switch (locator.by) {
+        case 'css':
+            return applyFilters(`Array.from(${rootExpression}.querySelectorAll(${value}))`, locator);
+        case 'role': {
+            const name = locator.name ? quote(locator.name) : value;
+            const nameCompare = locator.name
+                ? `(function(name){return ${exact ? `name.trim()===${name}` : `name.includes(${name})`};})(__name)`
+                : 'true';
+            predicate = `(__role===${value}&&${nameCompare})`;
+            break;
+        }
+        case 'label':
+            predicate = `Array.from(__el.labels||[]).some((label)=>${compare("(label.textContent||'')")})`;
+            break;
+        case 'placeholder':
+            predicate = compare(`__el.getAttribute('placeholder')||''`);
+            break;
+        case 'alt':
+            predicate = compare(`__el.getAttribute('alt')||''`);
+            break;
+        case 'title':
+            predicate = compare(`__el.getAttribute('title')||''`);
+            break;
+        case 'testid':
+            predicate = compare(`__el.getAttribute('data-testid')||''`);
+            break;
+        case 'text':
+            predicate = `(!__el.children.length&&${compare("(__el.textContent||'')")})`;
+            break;
+    }
+    const expression = `(() => {
+    const __accessibleName = (el) => {
+      const labelled = el.getAttribute('aria-label');
+      if (labelled) return labelled;
+      const ids = (el.getAttribute('aria-labelledby')||'').split(/\\s+/).filter(Boolean);
+      if (ids.length) return ids.map((id)=>${rootExpression}.getElementById(id)?.textContent||'').join(' ').trim();
+      if (el.labels?.length) return Array.from(el.labels).map((label)=>label.textContent||'').join(' ').trim();
+      return (el.innerText||el.textContent||'').trim();
+    };
+    const __implicitRole = (el) => {
+      const explicit = el.getAttribute('role');
+      if (explicit) return explicit;
+      const tag = el.tagName.toLowerCase();
+      if (tag === 'button') return 'button';
+      if (tag === 'a' && el.hasAttribute('href')) return 'link';
+      if (tag === 'textarea') return 'textbox';
+      if (tag === 'select') return 'combobox';
+      if (tag === 'input') {
+        const type = (el.getAttribute('type')||'text').toLowerCase();
+        if (type === 'checkbox') return 'checkbox';
+        if (type === 'radio') return 'radio';
+        if (type === 'button' || type === 'submit' || type === 'reset') return 'button';
+        return 'textbox';
+      }
+      return '';
+    };
+    return ${root}.filter((__el) => {
+      const __role = __implicitRole(__el);
+      const __name = __accessibleName(__el);
+      return ${predicate};
+    });
+  })()`;
+    const filtered = applyFilters(expression, locator);
+    const framePath = locator.frame ?? locator.framePath ?? locator.frame_path;
+    if (!framePath?.length)
+        return filtered;
+    // Same-origin frame traversal is explicit.  Cross-origin frames cannot be
+    // inspected through Runtime.evaluate and must be handled by a backend that
+    // can attach to the child target; never pretend the parent matched instead.
+    let frameRoot = rootExpression;
+    for (const frame of framePath) {
+        const frameSelector = frame.by === 'css'
+            ? quote(frame.value)
+            : quote(`iframe[title*="${frame.value.replaceAll('"', '\\"')}"]`);
+        frameRoot = `(() => { const frame = ${frameRoot}.querySelector(${frameSelector}); if (!frame || !frame.contentDocument) throw new Error('frameLocator could not resolve a same-origin iframe'); return frame.contentDocument; })()`;
+    }
+    return buildLocatorExpression({
+        ...locator,
+        frame: undefined,
+        framePath: undefined,
+        frame_path: undefined,
+        frameId: undefined,
+        frame_id: undefined,
+    }, selector, frameRoot);
+}
+function applyFilters(expression, locator) {
+    const filters = [];
+    if (locator.has_text)
+        filters.push(`(__el.textContent||'').includes(${quote(locator.has_text)})`);
+    return filters.length
+        ? `Array.from(${expression}).filter((__el)=>${filters.join('&&')})`
+        : expression;
+}
+export function buildTargetExpression(locator, selector) {
+    const elements = buildLocatorExpression(locator, selector);
+    const strict = locator?.strict !== false;
+    const nth = locator?.nth ?? 0;
+    return `(() => {
+    const __matches = ${elements}.filter((__candidate) => {
+      const __style = getComputedStyle(__candidate);
+      const __rect = __candidate.getBoundingClientRect();
+      return __style.display!=='none' && __style.visibility!=='hidden' && __style.pointerEvents!=='none' && (!!__rect.width || !!__rect.height);
+    });
+    if (!__matches.length) throw new Error('Locator matched no elements');
+    if (__matches.length > 1 && ${strict}) throw new Error('Locator matched '+__matches.length+' elements; use nth or strict:false');
+    const __el = __matches[${nth}];
+    if (!__el) throw new Error('Locator nth is outside the matched elements');
+    const __style = getComputedStyle(__el);
+    const __rect = __el.getBoundingClientRect();
+    if (__style.display==='none'||__style.visibility==='hidden'||__style.pointerEvents==='none'||(!__rect.width&&!__rect.height)) throw new Error('Locator matched a hidden element');
+    return __el;
+  })()`;
+}

package/src/tools/webbrowser/browserLocator.ts

@@ -0,0 +1,194 @@
+/**
+ * Browser locators shared by BrowserBatch and future visible-DOM adapters.
+ *
+ * This deliberately emits a small, self-contained browser expression instead
+ * of retaining DOM node handles.  A locator is resolved again for every step,
+ * so a navigation or React re-render cannot silently reuse a stale element.
+ */
+
+export type BrowserLocator = {
+  by:
+    | 'css'
+    | 'ax'
+    | 'role'
+    | 'text'
+    | 'label'
+    | 'placeholder'
+    | 'alt'
+    | 'title'
+    | 'testid';
+  value: string;
+  /** AX node id (or numeric index printed by the latest snapshot). */
+  generation?: number;
+  name?: string;
+  exact?: boolean;
+  strict?: boolean;
+  nth?: number;
+  within?: BrowserLocator;
+  has_text?: string;
+  frame?: BrowserLocator[];
+  framePath?: BrowserLocator[];
+  frame_path?: BrowserLocator[];
+  /** CDP frame id returned by frameInfo; enables cross-origin frame context. */
+  frameId?: string;
+  frame_id?: string;
+};
+
+const quote = (value: string) => JSON.stringify(value);
+
+/** Build an expression returning `Element[]` in the selected document. */
+export function buildLocatorExpression(
+  locator: BrowserLocator | undefined,
+  selector: string | undefined,
+  rootExpression = 'document',
+): string {
+  if (selector) {
+    return `Array.from(${rootExpression}.querySelectorAll(${quote(selector)}))`;
+  }
+  if (!locator) throw new Error('step requires selector or locator');
+
+  if (locator.by === 'ax') {
+    throw new Error(
+      'AX locator must be resolved against the live accessibility tree first',
+    );
+  }
+
+  const root = locator.within
+    ? `${buildLocatorExpression(locator.within, undefined, rootExpression)}.flatMap((scope) => Array.from(scope.querySelectorAll('*')))`
+    : `Array.from(${rootExpression}.querySelectorAll('*'))`;
+  const value = quote(locator.value);
+  const exact = locator.exact === true;
+  const compare = (expression: string, expected = value) =>
+    exact
+      ? `${expression}.trim()===${expected}`
+      : `${expression}.includes(${expected})`;
+
+  let predicate: string;
+  switch (locator.by) {
+    case 'css':
+      return applyFilters(
+        `Array.from(${rootExpression}.querySelectorAll(${value}))`,
+        locator,
+      );
+    case 'role': {
+      const name = locator.name ? quote(locator.name) : value;
+      const nameCompare = locator.name
+        ? `(function(name){return ${exact ? `name.trim()===${name}` : `name.includes(${name})`};})(__name)`
+        : 'true';
+      predicate = `(__role===${value}&&${nameCompare})`;
+      break;
+    }
+    case 'label':
+      predicate = `Array.from(__el.labels||[]).some((label)=>${compare("(label.textContent||'')")})`;
+      break;
+    case 'placeholder':
+      predicate = compare(`__el.getAttribute('placeholder')||''`);
+      break;
+    case 'alt':
+      predicate = compare(`__el.getAttribute('alt')||''`);
+      break;
+    case 'title':
+      predicate = compare(`__el.getAttribute('title')||''`);
+      break;
+    case 'testid':
+      predicate = compare(`__el.getAttribute('data-testid')||''`);
+      break;
+    case 'text':
+      predicate = `(!__el.children.length&&${compare("(__el.textContent||'')")})`;
+      break;
+  }
+
+  const expression = `(() => {
+    const __accessibleName = (el) => {
+      const labelled = el.getAttribute('aria-label');
+      if (labelled) return labelled;
+      const ids = (el.getAttribute('aria-labelledby')||'').split(/\\s+/).filter(Boolean);
+      if (ids.length) return ids.map((id)=>${rootExpression}.getElementById(id)?.textContent||'').join(' ').trim();
+      if (el.labels?.length) return Array.from(el.labels).map((label)=>label.textContent||'').join(' ').trim();
+      return (el.innerText||el.textContent||'').trim();
+    };
+    const __implicitRole = (el) => {
+      const explicit = el.getAttribute('role');
+      if (explicit) return explicit;
+      const tag = el.tagName.toLowerCase();
+      if (tag === 'button') return 'button';
+      if (tag === 'a' && el.hasAttribute('href')) return 'link';
+      if (tag === 'textarea') return 'textbox';
+      if (tag === 'select') return 'combobox';
+      if (tag === 'input') {
+        const type = (el.getAttribute('type')||'text').toLowerCase();
+        if (type === 'checkbox') return 'checkbox';
+        if (type === 'radio') return 'radio';
+        if (type === 'button' || type === 'submit' || type === 'reset') return 'button';
+        return 'textbox';
+      }
+      return '';
+    };
+    return ${root}.filter((__el) => {
+      const __role = __implicitRole(__el);
+      const __name = __accessibleName(__el);
+      return ${predicate};
+    });
+  })()`;
+
+  const filtered = applyFilters(expression, locator);
+  const framePath = locator.frame ?? locator.framePath ?? locator.frame_path;
+  if (!framePath?.length) return filtered;
+
+  // Same-origin frame traversal is explicit.  Cross-origin frames cannot be
+  // inspected through Runtime.evaluate and must be handled by a backend that
+  // can attach to the child target; never pretend the parent matched instead.
+  let frameRoot = rootExpression;
+  for (const frame of framePath) {
+    const frameSelector =
+      frame.by === 'css'
+        ? quote(frame.value)
+        : quote(`iframe[title*="${frame.value.replaceAll('"', '\\"')}"]`);
+    frameRoot = `(() => { const frame = ${frameRoot}.querySelector(${frameSelector}); if (!frame || !frame.contentDocument) throw new Error('frameLocator could not resolve a same-origin iframe'); return frame.contentDocument; })()`;
+  }
+  return buildLocatorExpression(
+    {
+      ...locator,
+      frame: undefined,
+      framePath: undefined,
+      frame_path: undefined,
+      frameId: undefined,
+      frame_id: undefined,
+    },
+    selector,
+    frameRoot,
+  );
+}
+
+function applyFilters(expression: string, locator: BrowserLocator): string {
+  const filters: string[] = [];
+  if (locator.has_text)
+    filters.push(`(__el.textContent||'').includes(${quote(locator.has_text)})`);
+  return filters.length
+    ? `Array.from(${expression}).filter((__el)=>${filters.join('&&')})`
+    : expression;
+}
+
+export function buildTargetExpression(
+  locator: BrowserLocator | undefined,
+  selector: string | undefined,
+): string {
+  const elements = buildLocatorExpression(locator, selector);
+  const strict = locator?.strict !== false;
+  const nth = locator?.nth ?? 0;
+  return `(() => {
+    const __matches = ${elements}.filter((__candidate) => {
+      const __style = getComputedStyle(__candidate);
+      const __rect = __candidate.getBoundingClientRect();
+      return __style.display!=='none' && __style.visibility!=='hidden' && __style.pointerEvents!=='none' && (!!__rect.width || !!__rect.height);
+    });
+    if (!__matches.length) throw new Error('Locator matched no elements');
+    if (__matches.length > 1 && ${strict}) throw new Error('Locator matched '+__matches.length+' elements; use nth or strict:false');
+    const __el = __matches[${nth}];
+    if (!__el) throw new Error('Locator nth is outside the matched elements');
+    const __style = getComputedStyle(__el);
+    const __rect = __el.getBoundingClientRect();
+    if (__style.display==='none'||__style.visibility==='hidden'||__style.pointerEvents==='none'||(!__rect.width&&!__rect.height)) throw new Error('Locator matched a hidden element');
+    return __el;
+  })()`;
+}

package/src/tools/webbrowser/browserOutcome.js

@@ -85,16 +85,9 @@ export function describeEffect(verdict, action) {
         case 'changed':
             return null; // 正常路径不加噪声
         case 'unchanged':
-            return (`⚠️ 动作已发出，但页面结构在动作前后**完全没有变化**。\n`
-                + `这通常意味着三种情况之一：${action} 命中的不是可交互元素、点击被遮挡层拦住了、`
-                + `或者这个操作本来就不改变页面（比如点了一个纯展示文本）。\n`
-                + `请对照下面的最新快照确认目标是否正确，不要用同一个选择器直接重试。`
-                // 豁免了行才提。这不是免责声明，是让模型知道这个结论有多硬：
-                // 被豁免的位置上，「自己在跳」和「被我改了又在跳」不可区分。
-                + (verdict.maskedLines > 0
-                    ? `\n（说明：页面上有 ${verdict.maskedLines} 行在持续自行变化（时钟/轮询一类），`
-                        + `已从判定中排除。若你这次操作本该影响的正是这些位置，这个结论可能不准。）`
-                    : ''));
+            return `⚠️ 动作已发出，但页面结构在动作前后**完全没有变化**。\n这通常意味着三种情况之一：${action} 命中的不是可交互元素、点击被遮挡层拦住了、或者这个操作本来就不改变页面（比如点了一个纯展示文本）。\n请对照下面的最新快照确认目标是否正确，不要用同一个选择器直接重试。${verdict.maskedLines > 0
+                ? `\n（说明：页面上有 ${verdict.maskedLines} 行在持续自行变化（时钟/轮询一类），已从判定中排除。若你这次操作本该影响的正是这些位置，这个结论可能不准。）`
+                : ''}`;
         case 'unknown':
             return '（未能取得动作前后的页面快照，无法判断这次操作是否生效——请自行核对。）';
     }
@@ -179,7 +172,7 @@ export function suggestSelectorCandidates(snapshot, selector, limit = 5) {
 export class BrowserAttemptLedger {
     counts = new Map();
     static key(conversationKey, action, selector) {
-        return `${conversationKey}${action}${selector ?? ''}`;
+        return `${conversationKey}\u0000${action}\u0000${selector ?? ''}`;
     }
     recordFailure(conversationKey, action, selector) {
         const key = BrowserAttemptLedger.key(conversationKey, action, selector);
@@ -191,12 +184,12 @@ export class BrowserAttemptLedger {
         this.counts.delete(BrowserAttemptLedger.key(conversationKey, action, selector));
     }
     failures(conversationKey, action, selector) {
-        return this.counts.get(BrowserAttemptLedger.key(conversationKey, action, selector)) ?? 0;
+        return (this.counts.get(BrowserAttemptLedger.key(conversationKey, action, selector)) ?? 0);
     }
     /** 会话结束时清账，避免长期驻留。 */
     forget(conversationKey) {
         for (const key of [...this.counts.keys()]) {
-            if (key.startsWith(`${conversationKey}`))
+            if (key.startsWith(`${conversationKey}\u0000`))
                 this.counts.delete(key);
         }
     }
@@ -228,7 +221,9 @@ export function budgetSnapshot(snapshot, opts = {}) {
     if (lines.length <= maxLines && snapshot.length <= maxChars)
         return snapshot;
     const hasRef = (line) => /@e\d+|\bref=e\d+/.test(line);
-    const clip = (line) => line.length <= MAX_SNAPSHOT_LINE_CHARS ? line : `${line.slice(0, MAX_SNAPSHOT_LINE_CHARS)}…`;
+    const clip = (line) => line.length <= MAX_SNAPSHOT_LINE_CHARS
+        ? line
+        : `${line.slice(0, MAX_SNAPSHOT_LINE_CHARS)}…`;
     // 两轮**只挑不排**：先在原序上标记要留的可操作行，再用余量补纯文本行。
     const keep = new Array(lines.length).fill(false);
     let kept = 0;
@@ -267,7 +262,5 @@ export function budgetSnapshot(snapshot, opts = {}) {
     }
     flushGap();
     const dropped = lines.length - kept;
-    return (`${out.join('\n')}\n`
-        + `… 为控制上下文，共省略 ${dropped} 行（按原顺序保留，优先保住可引用的元素）。`
-        + '需要完整页面请单独调用 snapshot，或用 getContent 读取正文。');
+    return `${out.join('\n')}\n… 为控制上下文，共省略 ${dropped} 行（按原顺序保留，优先保住可引用的元素）。需要完整页面请单独调用 snapshot，或用 getContent 读取正文。`;
 }

package/src/tools/webbrowser/browserOutcome.ts

@@ -82,36 +82,35 @@ export function classifyPageEffect(
   after: string | undefined,
   noiseAfter?: string,
 ): BrowserEffectVerdict {
-  if (before === undefined || after === undefined) return { effect: 'unknown', maskedLines: 0 };
+  if (before === undefined || after === undefined)
+    return { effect: 'unknown', maskedLines: 0 };
   const actual = differingLineIndexes(before, after);
   if (actual === null) return { effect: 'changed', maskedLines: 0 }; // 行数变了 = 结构变了
   if (actual.size === 0) return { effect: 'unchanged', maskedLines: 0 };
-  const noisy = noiseAfter !== undefined ? differingLineIndexes(after, noiseAfter) : null;
+  const noisy =
+    noiseAfter !== undefined ? differingLineIndexes(after, noiseAfter) : null;
   // 没有可用的噪声基线时不做扣除：宁可把「生效了」判宽，也不能把一次真实变化
   // 误报成没变——那会让模型放弃一条本来走通了的路。
   if (noisy === null) return { effect: 'changed', maskedLines: 0 };
-  for (const index of actual) if (!noisy.has(index)) return { effect: 'changed', maskedLines: 0 };
+  for (const index of actual)
+    if (!noisy.has(index)) return { effect: 'changed', maskedLines: 0 };
   return { effect: 'unchanged', maskedLines: actual.size };
 }
 
 /** 给模型的效果说明。措辞要让它知道**下一步该干什么**，不只是知道结果。 */
-export function describeEffect(verdict: BrowserEffectVerdict, action: string): string | null {
+export function describeEffect(
+  verdict: BrowserEffectVerdict,
+  action: string,
+): string | null {
   switch (verdict.effect) {
     case 'changed':
       return null; // 正常路径不加噪声
     case 'unchanged':
-      return (
-        `⚠️ 动作已发出，但页面结构在动作前后**完全没有变化**。\n`
-        + `这通常意味着三种情况之一：${action} 命中的不是可交互元素、点击被遮挡层拦住了、`
-        + `或者这个操作本来就不改变页面（比如点了一个纯展示文本）。\n`
-        + `请对照下面的最新快照确认目标是否正确，不要用同一个选择器直接重试。`
-        // 豁免了行才提。这不是免责声明，是让模型知道这个结论有多硬：
-        // 被豁免的位置上，「自己在跳」和「被我改了又在跳」不可区分。
-        + (verdict.maskedLines > 0
-          ? `\n（说明：页面上有 ${verdict.maskedLines} 行在持续自行变化（时钟/轮询一类），`
-            + `已从判定中排除。若你这次操作本该影响的正是这些位置，这个结论可能不准。）`
-          : '')
-      );
+      return `⚠️ 动作已发出，但页面结构在动作前后**完全没有变化**。\n这通常意味着三种情况之一：${action} 命中的不是可交互元素、点击被遮挡层拦住了、或者这个操作本来就不改变页面（比如点了一个纯展示文本）。\n请对照下面的最新快照确认目标是否正确，不要用同一个选择器直接重试。${
+        verdict.maskedLines > 0
+          ? `\n（说明：页面上有 ${verdict.maskedLines} 行在持续自行变化（时钟/轮询一类），已从判定中排除。若你这次操作本该影响的正是这些位置，这个结论可能不准。）`
+          : ''
+      }`;
     case 'unknown':
       return '（未能取得动作前后的页面快照，无法判断这次操作是否生效——请自行核对。）';
   }
@@ -206,29 +205,47 @@ export function suggestSelectorCandidates(
 export class BrowserAttemptLedger {
   private counts = new Map<string, number>();
 
-  private static key(conversationKey: string, action: string, selector?: string): string {
-    return `${conversationKey}${action}${selector ?? ''}`;
+  private static key(
+    conversationKey: string,
+    action: string,
+    selector?: string,
+  ): string {
+    return `${conversationKey}\u0000${action}\u0000${selector ?? ''}`;
   }
 
-  recordFailure(conversationKey: string, action: string, selector?: string): number {
+  recordFailure(
+    conversationKey: string,
+    action: string,
+    selector?: string,
+  ): number {
     const key = BrowserAttemptLedger.key(conversationKey, action, selector);
     const next = (this.counts.get(key) ?? 0) + 1;
     this.counts.set(key, next);
     return next;
   }
 
-  recordSuccess(conversationKey: string, action: string, selector?: string): void {
-    this.counts.delete(BrowserAttemptLedger.key(conversationKey, action, selector));
+  recordSuccess(
+    conversationKey: string,
+    action: string,
+    selector?: string,
+  ): void {
+    this.counts.delete(
+      BrowserAttemptLedger.key(conversationKey, action, selector),
+    );
   }
 
   failures(conversationKey: string, action: string, selector?: string): number {
-    return this.counts.get(BrowserAttemptLedger.key(conversationKey, action, selector)) ?? 0;
+    return (
+      this.counts.get(
+        BrowserAttemptLedger.key(conversationKey, action, selector),
+      ) ?? 0
+    );
   }
 
   /** 会话结束时清账，避免长期驻留。 */
   forget(conversationKey: string): void {
     for (const key of [...this.counts.keys()]) {
-      if (key.startsWith(`${conversationKey}`)) this.counts.delete(key);
+      if (key.startsWith(`${conversationKey}\u0000`)) this.counts.delete(key);
     }
   }
 }
@@ -267,7 +284,9 @@ export function budgetSnapshot(
 
   const hasRef = (line: string): boolean => /@e\d+|\bref=e\d+/.test(line);
   const clip = (line: string): string =>
-    line.length <= MAX_SNAPSHOT_LINE_CHARS ? line : `${line.slice(0, MAX_SNAPSHOT_LINE_CHARS)}…`;
+    line.length <= MAX_SNAPSHOT_LINE_CHARS
+      ? line
+      : `${line.slice(0, MAX_SNAPSHOT_LINE_CHARS)}…`;
 
   // 两轮**只挑不排**：先在原序上标记要留的可操作行，再用余量补纯文本行。
   const keep = new Array<boolean>(lines.length).fill(false);
@@ -292,15 +311,13 @@ export function budgetSnapshot(
     gap = 0;
   };
   for (let i = 0; i < lines.length; i += 1) {
-    if (keep[i]) { flushGap(); out.push(clip(lines[i])); }
-    else gap += 1;
+    if (keep[i]) {
+      flushGap();
+      out.push(clip(lines[i]));
+    } else gap += 1;
   }
   flushGap();
 
   const dropped = lines.length - kept;
-  return (
-    `${out.join('\n')}\n`
-    + `… 为控制上下文，共省略 ${dropped} 行（按原顺序保留，优先保住可引用的元素）。`
-    + '需要完整页面请单独调用 snapshot，或用 getContent 读取正文。'
-  );
+  return `${out.join('\n')}\n… 为控制上下文，共省略 ${dropped} 行（按原顺序保留，优先保住可引用的元素）。需要完整页面请单独调用 snapshot，或用 getContent 读取正文。`;
 }