minimal-agent 0.10.0 → 0.12.0

package/src/tools/webbrowser/browserDaemon.ts

@@ -0,0 +1,270 @@
+import { spawn } from 'node:child_process';
+import { dirname, isAbsolute } from 'node:path';
+
+import { resolveAgentBrowserPath, resolveBundledChromium, resolveSystemBrowser } from './agentBrowserPath.js';
+import {
+  browserGlobalArgs,
+  runBounded,
+  sessionArgs,
+  spawnRunner,
+  type AgentBrowserRunner,
+} from './browser.js';
+
+export interface BrowserDaemonInfo {
+  sessionName: string;
+  streamPort: number;
+  pid?: number;
+  alreadyRunning: boolean;
+}
+
+/** Daemon 启动（拉起 Chrome + CDP 就绪）总预算：超时即掐断并抛可操作错误，绝不无限挂。 */
+export const DAEMON_BRINGUP_TIMEOUT_MS = 45_000;
+/** 单次 `stream status` 探测预算：daemon socket 卡死时不拖累调用方。 */
+export const STATUS_TIMEOUT_MS = 8_000;
+
+const ports = new Map<string, number>();
+const starts = new Map<string, Promise<BrowserDaemonInfo>>();
+
+/** Daemon 生命周期可选项：透传父级中断 signal + 覆盖启动预算 + 回收注入（测试用）。 */
+export interface EnsureDaemonOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  reclaim?: ReclaimDeps;
+}
+
+/**
+ * Daemon 子进程执行缝（默认走真实实现）：单测注入假 runner/resolveBin 即可确定性覆盖
+ * 「启动有界/可中断」等分支，不碰真 Chrome、不用 mock.module（见项目测试约定）。
+ */
+export interface DaemonDeps {
+  resolveBin: () => Promise<string | null>;
+  runner: AgentBrowserRunner;
+}
+
+const realDaemonDeps: DaemonDeps = {
+  resolveBin: resolveAgentBrowserPath,
+  runner: spawnRunner,
+};
+
+/** 回收残留进程用的杀进程执行器（默认真实 spawn，等它结束再 resolve；单测注入假实现断言作用域）。 */
+export type ReclaimExec = (file: string, args: string[]) => Promise<void>;
+
+const realReclaimExec: ReclaimExec = (file, args) =>
+  new Promise<void>((resolve) => {
+    try {
+      const child = spawn(file, args, { stdio: 'ignore', windowsHide: true });
+      child.on('close', () => resolve());
+      child.on('error', () => resolve());
+    } catch {
+      resolve();
+    }
+  });
+
+export interface ReclaimDeps {
+  binDir?: () => Promise<string | null>;
+  platform?: NodeJS.Platform;
+  exec?: ReclaimExec;
+}
+
+/**
+ * 回收「本仓库/本 App 的」残留 agent-browser daemon + 其 Chrome 子树（Windows `taskkill /F /T`）。
+ *
+ * 根因：agent-browser 的 daemon 是「黏」的后台进程，`--profile`/`--executable-path` 等 launch-only
+ * flag 首次启动即固化、之后忽略（见 readStatus 头注）。一次无 profile 的启动就毒化整个 session，
+ * 之后复用继承临时 profile、重启 App 也不解，且孤儿 Chrome 堆积。宿主（Desktop runtime）在启动时
+ * 调用一次本函数，把上一轮残留清干净，下次 bring-up 便以我们的持久 `--profile` 干净重启。
+ *
+ * 安全：**仅**按「已解析二进制所在目录前缀」作用域匹配 agent-browser.exe，绝不误伤安装版桌面 App
+ * 或系统上别处的 agent-browser 用法（对标 scripts/dev-browser.ts::reclaimStalePort）。无法作用域限定
+ * （PATH 上裸二进制 / 没装）时保守放弃，不做全局杀。幂等、best-effort（失败静默）。
+ */
+export async function reclaimStaleDaemons(deps: ReclaimDeps = {}): Promise<void> {
+  const platform = deps.platform ?? process.platform;
+  const exec = deps.exec ?? realReclaimExec;
+  const resolveDir =
+    deps.binDir ??
+    (async () => {
+      const bin = await resolveAgentBrowserPath();
+      return bin && isAbsolute(bin) ? dirname(bin) : null;
+    });
+  const dir = await resolveDir();
+  if (!dir) return;
+  ports.clear();
+  if (platform === 'win32') {
+    const root = dir.toLowerCase().replace(/'/g, "''");
+    const ps =
+      // (a) 本 App 路径下的 agent-browser daemon + 其 Chrome 子树。
+      `Get-CimInstance Win32_Process -Filter "Name='agent-browser.exe'" | ` +
+      `Where-Object { $_.ExecutablePath -and $_.ExecutablePath.ToLower().StartsWith('${root}') } | ` +
+      `ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }; ` +
+      // (b) 真孤儿 agent-browser Chrome（父进程已死）。daemon 崩溃后残留、上面的 agent-browser 树
+      //     够不着，堆积起来会把新 daemon 的 Chrome 拉起拖到几十秒（实测 18 棵孤儿 → 卡 43s；
+      //     清空后同一启动仅 1s）。**只杀父进程已不在的孤儿**，绝不误伤有活父进程的正常浏览器
+      //     （安装版 App 的活浏览器父 agent-browser 健在 → 不匹配，天然豁免）。
+      `$alive=@{}; Get-CimInstance Win32_Process | ForEach-Object { $alive[[int]$_.ProcessId]=$true }; ` +
+      `Get-CimInstance Win32_Process -Filter "Name='chrome.exe'" | ` +
+      `Where-Object { ($_.CommandLine -match 'agent-browser-chrome' -or $_.CommandLine -match '\\.minimal-agent.{0,40}profiles') -and -not $alive.ContainsKey([int]$_.ParentProcessId) } | ` +
+      `ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }`;
+    await exec('powershell', ['-NoProfile', '-NonInteractive', '-Command', ps]);
+  } else {
+    // unix：按可执行路径前缀 pkill agent-browser（其 Chrome 子进程随之收尾）。unix 孤儿会被
+    // reparent 到 init，无「父已死」信号，故此处不做等价的孤儿 Chrome 清扫（Windows 才是主战场）。
+    await exec('pkill', ['-f', `${dir}/agent-browser`]);
+  }
+}
+
+function parsePort(text: string): number | null {
+  const match = text.match(/ws:\/\/(?:127\.0\.0\.1|localhost):([0-9]+)/i);
+  if (!match) return null;
+  const port = Number(match[1]);
+  return Number.isInteger(port) && port > 0 && port < 65_536 ? port : null;
+}
+
+function browserRuntimeMissing(text: string): boolean {
+  return /browser\s+(?:not found|was not found)|chrom(?:e|ium).*(?:not found|missing)|executable.*(?:not found|does not exist)|run ['\"]?agent-browser install/i.test(text);
+}
+
+export { browserRuntimeMissing as _browserRuntimeMissing };
+
+async function readStatus(
+  bin: string,
+  sessionName: string,
+  opts: EnsureDaemonOptions = {},
+  deps: DaemonDeps = realDaemonDeps,
+): Promise<{ port: number | null; connected: boolean }> {
+  // Profile/executable flags are launch-only. Repeating them against a running
+  // daemon makes agent-browser ignore the profile and emit misleading warnings.
+  // 有界：daemon socket 卡死时不把 status 探测拖成无限挂（getStreamPort/ensureDaemon 都靠它）。
+  const result = await runBounded(
+    bin,
+    [...sessionArgs(sessionName), 'stream', 'status'],
+    { signal: opts.signal, timeoutMs: opts.timeoutMs ?? STATUS_TIMEOUT_MS },
+    deps.runner,
+  );
+  if (result.code !== 0) return { port: null, connected: false };
+  const text = `${result.stdout}\n${result.stderr}`;
+  return { port: parsePort(text), connected: /Connected:\s*true/i.test(text) };
+}
+
+export async function ensureDaemon(
+  sessionName = 'minimal-agent',
+  opts: EnsureDaemonOptions = {},
+  deps: DaemonDeps = realDaemonDeps,
+): Promise<BrowserDaemonInfo> {
+  const bin = await deps.resolveBin();
+  if (!bin) throw new Error('未找到 agent-browser 可执行文件');
+  const status = await readStatus(bin, sessionName, { signal: opts.signal }, deps);
+  if (status.port && status.connected) {
+    ports.set(sessionName, status.port);
+    return { sessionName, streamPort: status.port, alreadyRunning: true };
+  }
+  // 半死 daemon（socket 端口在、但 Chrome 已亡 connected:false）：对谁都没用，先回收再重启，
+  // 否则新 open 可能连到无 Chrome 的僵尸 daemon 上卡死。回收对健康的共享 daemon 无影响（那会
+  // 走上面的 connected 分支直接复用）。
+  if (status.port && !status.connected) {
+    await reclaimStaleDaemons(opts.reclaim);
+  }
+  const pending = starts.get(sessionName);
+  if (pending) return pending;
+
+  const budget = opts.timeoutMs ?? DAEMON_BRINGUP_TIMEOUT_MS;
+  const start = (async () => {
+    // Bring-up 边界：父级 signal abort 或超预算即掐断所有内部子进程。旧缺陷是 ensureDaemon
+    // 全程无 timeout、不接 signal —— Chrome/CDP 起不来时无限挂、用户 stop/ESC 也掐不断
+    // （「访问网站卡 5m53s」的根因）。这里统一一个控制器兜住整段启动。
+    const ac = new AbortController();
+    let timedOut = false;
+    const onParent = () => ac.abort(opts.signal?.reason);
+    const timer = setTimeout(() => {
+      timedOut = true;
+      ac.abort();
+    }, budget);
+    if (opts.signal) {
+      if (opts.signal.aborted) ac.abort(opts.signal.reason);
+      else opts.signal.addEventListener('abort', onParent, { once: true });
+    }
+    const bringUpError = () =>
+      new Error(
+        timedOut
+          ? `内置浏览器启动超时：Chrome 未在 ${Math.round(budget / 1000)}s 内就绪（可能被残留浏览器进程占用）。可稍后重试，或改用 WebFetch 读取网页。`
+          : '内置浏览器启动已被中断。',
+      );
+    const run = (args: string[]) => deps.runner(bin, args, ac.signal);
+    try {
+      const globals = await browserGlobalArgs(sessionName);
+      // Prefer a stable system browser executable, but always use KakadeAI's
+      // isolated profile. Bundled Chromium remains an offline fallback.
+      const systemBrowser = resolveSystemBrowser();
+      let opened = await run([
+        ...globals,
+        ...(systemBrowser ? ['--executable-path', systemBrowser] : []),
+        'open',
+        'about:blank',
+      ]);
+      if (ac.signal.aborted) throw bringUpError();
+      if (opened.code !== 0 && browserRuntimeMissing(`${opened.stderr}\n${opened.stdout}`)) {
+        const chromium = resolveBundledChromium();
+        if (chromium) {
+          opened = await run([...globals, '--executable-path', chromium, 'open', 'about:blank']);
+        } else {
+          const installed = await run(['install']);
+          if (installed.code === 0) opened = await run([...globals, 'open', 'about:blank']);
+        }
+        if (ac.signal.aborted) throw bringUpError();
+      }
+      if (opened.code !== 0) {
+        throw new Error((opened.stderr || opened.stdout || '浏览器启动失败').trim());
+      }
+      const streamPort = await waitForStreamPort(sessionName, 10_000, deps);
+      ports.set(sessionName, streamPort);
+      return { sessionName, streamPort, alreadyRunning: false };
+    } finally {
+      clearTimeout(timer);
+      opts.signal?.removeEventListener('abort', onParent);
+    }
+  })().finally(() => starts.delete(sessionName));
+  starts.set(sessionName, start);
+  return start;
+}
+
+export async function stopDaemon(
+  sessionName = 'minimal-agent',
+  deps: DaemonDeps = realDaemonDeps,
+  reclaim?: ReclaimDeps,
+): Promise<void> {
+  const bin = await deps.resolveBin();
+  ports.delete(sessionName);
+  if (bin) {
+    await runBounded(bin, [...sessionArgs(sessionName), 'close'], { timeoutMs: STATUS_TIMEOUT_MS }, deps.runner);
+  }
+  // 优雅 close 之外再 tree-kill 一遍本 App 路径下的残留：崩溃/close 不彻底时仍杜绝临时 profile
+  // 孤儿 Chrome 堆积（实测同时存活 ≥2 棵孤儿 Chrome 树的根因）。
+  await reclaimStaleDaemons(reclaim);
+}
+
+export async function getStreamPort(
+  sessionName = 'minimal-agent',
+  deps: DaemonDeps = realDaemonDeps,
+): Promise<number | null> {
+  const cached = ports.get(sessionName);
+  if (cached) return cached;
+  const bin = await deps.resolveBin();
+  if (!bin) return null;
+  const port = (await readStatus(bin, sessionName, {}, deps)).port;
+  if (port) ports.set(sessionName, port);
+  return port;
+}
+
+export async function waitForStreamPort(
+  sessionName = 'minimal-agent',
+  timeoutMs = 10_000,
+  deps: DaemonDeps = realDaemonDeps,
+): Promise<number> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const port = await getStreamPort(sessionName, deps);
+    if (port) return port;
+    await new Promise((resolve) => setTimeout(resolve, 120));
+  }
+  throw new Error('浏览器已启动，但实时画面端口未就绪');
+}

package/src/tools/webbrowser/browserOutcome.js

@@ -0,0 +1,273 @@
+/**
+ * ============================================================
+ *  browserOutcome.ts —— 浏览器动作的「成功率」设施
+ * ------------------------------------------------------------
+ *  三件事，全部是纯函数，因此可以被单测钉死：
+ *    ① 页面指纹与变化判定（动作到底生效了没有）
+ *    ② 选择器失败时的候选推荐（把「没找到」变成「最接近的是这几个」）
+ *    ③ 同一目标连续失败的熔断计数
+ *
+ *  为什么这些属于「成功率」而不是「锦上添花」：模型的每一次重试都是一个 LLM 往返，
+ *  而它重试时**手上没有当前页面**——失败只回了一句 `selector not found`。于是最常见
+ *  的失败形状不是「做错了」，是「原地换着选择器盲猜三五轮，然后放弃」。
+ * ============================================================
+ */
+/** 会被验证「是否真的改变了页面」的动作。 */
+export const VERIFIED_BROWSER_ACTIONS = new Set([
+    'click',
+    'fill',
+    'type',
+    'select',
+    'press',
+    'drag',
+]);
+/**
+ * 两份快照中内容不同的行号。行数不同则返回 null —— 那本身就是结构变化。
+ *
+ * ⚠️ 两边都先 `trim()`。动作前的快照是原始 stdout、动作后那份在别处被 trim 过，
+ * 一个尾随换行就让行数对不上、直接判成「结构变了」，于是**所有**动作都判 changed，
+ * 噪声扣除彻底失效。基准集跑出来才发现——纯逻辑单测里两边都是我手写的字符串，
+ * 永远不会有这种不对称。
+ */
+export function differingLineIndexes(a, b) {
+    const left = a.trim().split('\n');
+    const right = b.trim().split('\n');
+    if (left.length !== right.length)
+        return null;
+    const diff = new Set();
+    for (let i = 0; i < left.length; i += 1) {
+        if (left[i].trim() !== right[i].trim())
+            diff.add(i);
+    }
+    return diff;
+}
+/**
+ * 判定一次动作是否真的改变了页面。
+ *
+ * **噪声是测出来的，不是猜出来的**：`after` 之后隔一小段再拍一张 `noiseAfter`，
+ * 两张之间自己变了的**行位置**就是噪声源（时钟、未读数、轮询列表）。再看
+ * 「动作前→动作后」变了的行里，除掉这些位置之后还剩不剩。
+ *
+ * ⚠️ 噪声基线取在**动作之后**而不是之前。噪声是页面的持续属性，前后测等价；
+ * 而放在后面换来两件事：`before === after` 时（正是要判 unchanged 的情形）根本
+ * 不必采样，零成本；采样的那段等待也不再推迟动作本身的发出。
+ *
+ * 三个实测踩过的坑，这里同时避开：
+ *   · 直接比全页文本 → 时钟每 200ms 一跳，恒判「变了」，判定形同虚设；
+ *   · 忽略所有文本只看结构 → 点击把 `StaticText "closed"` 变成 `"opened"` 这种
+ *     **真正生效**的纯文本变化被报成「完全没有变化」。误报比不报更糟：它在教模型
+ *     不要相信一个正确的动作；
+ *   · 按行**内容**标定噪声 → 时钟每次都是新值，永远匹配不上自己。所以按行**位置**。
+ *
+ * 行数一变就直接算 changed —— 结构动了，不必再细究。
+ */
+export function classifyPageEffect(before, after, noiseAfter) {
+    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;
+    // 没有可用的噪声基线时不做扣除：宁可把「生效了」判宽，也不能把一次真实变化
+    // 误报成没变——那会让模型放弃一条本来走通了的路。
+    if (noisy === null)
+        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, action) {
+    switch (verdict.effect) {
+        case 'changed':
+            return null; // 正常路径不加噪声
+        case 'unchanged':
+            return (`⚠️ 动作已发出，但页面结构在动作前后**完全没有变化**。\n`
+                + `这通常意味着三种情况之一：${action} 命中的不是可交互元素、点击被遮挡层拦住了、`
+                + `或者这个操作本来就不改变页面（比如点了一个纯展示文本）。\n`
+                + `请对照下面的最新快照确认目标是否正确，不要用同一个选择器直接重试。`
+                // 豁免了行才提。这不是免责声明，是让模型知道这个结论有多硬：
+                // 被豁免的位置上，「自己在跳」和「被我改了又在跳」不可区分。
+                + (verdict.maskedLines > 0
+                    ? `\n（说明：页面上有 ${verdict.maskedLines} 行在持续自行变化（时钟/轮询一类），`
+                        + `已从判定中排除。若你这次操作本该影响的正是这些位置，这个结论可能不准。）`
+                    : ''));
+        case 'unknown':
+            return '（未能取得动作前后的页面快照，无法判断这次操作是否生效——请自行核对。）';
+    }
+}
+/**
+ * 解析快照里的元素引用行。
+ *
+ * 匹配 `ref=eN` 而不是 `[ref=eN]`：真实行是 `[level=1, ref=e1]`，ref 常和别的属性
+ * 混在同一个方括号里。第一版按 `[ref=` 起头写，于是带属性的行（heading/button 这类
+ * 最该被推荐的）全部漏掉——真实样本进测试之后才暴露。
+ *
+ * ⚠️ **两种形状都要认**。文档和工具描述里写的是 `@eN`，但 agent-browser 实际输出的是
+ * `[ref=e1]`：
+ *   `- link "Learn more" [ref=e2]`
+ * 第一版只认 `@eN`，于是候选推荐在真实页面上**一个都匹配不到** —— 单测全绿，实机零命中。
+ * 是跑了一次真的 example.com 才发现的。两种都收，并统一成 `@eN` 交给模型（那是它被教的
+ * 引用写法）。
+ */
+export function parseSnapshotCandidates(snapshot) {
+    const out = [];
+    for (const raw of snapshot.split('\n')) {
+        const line = raw.trim();
+        const match = /@e(\d+)|\bref=e(\d+)/.exec(line);
+        if (!match)
+            continue;
+        const id = match[1] ?? match[2];
+        out.push({ ref: `@e${id}`, line: line.slice(0, 160) });
+    }
+    return out;
+}
+/**
+ * 归一化成可比较的词：小写、去标点、拆词。
+ *
+ * ⚠️ 连字符和下划线**必须**当分隔符。真实 CSS 选择器几乎全是 `a.learn-more-link`、
+ * `#btn_submit`、`[data-testid=...]` 这个形状，不拆的话整串是一个词，和快照里的
+ * `link "Learn more"` 永远匹配不上 —— 功能在最常见的输入上直接失效。
+ * 第一版漏了这两个字符，单测（用的是中文与空格分词的样本）全绿，实机零命中。
+ */
+function tokenize(value) {
+    return value
+        .toLowerCase()
+        .replace(/[#.>[\]="'`(),:{}\-_/*+~|]/g, ' ')
+        .split(/\s+/)
+        .filter((token) => token.length > 1);
+}
+/**
+ * 选择器没命中时，从快照里挑出最像目标的几个候选。
+ *
+ * 打分只用「词重叠」这一件事，不引模糊匹配库：这里要的不是排序精度，是**给模型一个
+ * 能立刻拿去用的 `@eN` 列表**，而不是让它对着 `selector not found` 再猜一轮。
+ * 排名差一点无所谓，列表里有正确答案就赢了。
+ */
+export function suggestSelectorCandidates(snapshot, selector, limit = 5) {
+    const wanted = tokenize(selector);
+    if (wanted.length === 0)
+        return [];
+    const scored = parseSnapshotCandidates(snapshot)
+        .map((candidate) => {
+        const tokens = new Set(tokenize(candidate.line));
+        let score = 0;
+        for (const token of wanted) {
+            if (tokens.has(token))
+                score += 2;
+            else if (candidate.line.toLowerCase().includes(token))
+                score += 1;
+        }
+        return { candidate, score };
+    })
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+    return scored.map((entry) => entry.candidate);
+}
+/**
+ * 同一目标连续失败的熔断计数。
+ *
+ * 语义**刻意与 ComputerUse 的 `refuseWhenStuck` 一致**：清零的条件是「**这个动作**
+ * 成功了一次」，读取类动作（snapshot/getContent）成功**不清**写操作的账。
+ * 原因在那边写过：`失败 → snapshot → 失败 → snapshot …` 正是模型打转时最常见的形状，
+ * 让 snapshot 清零等于熔断永远数不到上限。
+ */
+export class BrowserAttemptLedger {
+    counts = new Map();
+    static key(conversationKey, action, selector) {
+        return `${conversationKey}${action}${selector ?? ''}`;
+    }
+    recordFailure(conversationKey, action, selector) {
+        const key = BrowserAttemptLedger.key(conversationKey, action, selector);
+        const next = (this.counts.get(key) ?? 0) + 1;
+        this.counts.set(key, next);
+        return next;
+    }
+    recordSuccess(conversationKey, action, selector) {
+        this.counts.delete(BrowserAttemptLedger.key(conversationKey, action, selector));
+    }
+    failures(conversationKey, action, selector) {
+        return this.counts.get(BrowserAttemptLedger.key(conversationKey, action, selector)) ?? 0;
+    }
+    /** 会话结束时清账，避免长期驻留。 */
+    forget(conversationKey) {
+        for (const key of [...this.counts.keys()]) {
+            if (key.startsWith(`${conversationKey}`))
+                this.counts.delete(key);
+        }
+    }
+}
+/** 同一 (动作, 选择器) 连续失败到这个次数就拒绝再试。 */
+export const BROWSER_FAILURE_LIMIT = 3;
+export const browserAttempts = new BrowserAttemptLedger();
+/** 单行最长保留字符数；超出就地截断，不因为一行长就丢掉整行的引用信息。 */
+const MAX_SNAPSHOT_LINE_CHARS = 300;
+/**
+ * 把快照收进上下文预算。
+ *
+ * 失败回执里带整份快照曾经是**最贵的一笔开销**：大页面 30k 字符 ≈ 8k token，而一次
+ * 失败往往连着几次。更糟的是这些 token 大半花在纯文本节点上——模型下一步要用的是
+ * **可引用的元素**（带 ref 的行），成段的正文对「换个目标重试」毫无帮助。
+ *
+ * 所以预算不是简单截断，是**按价值取舍**：带 ref 的行优先保留（那是可操作面），
+ * 纯文本行只在还有余量时补。
+ *
+ * ⚠️ 但取舍**只决定留哪些行，不决定行的顺序**。快照是一棵缩进树，把带 ref 的行
+ * 全部提到前面会让缩进层级与父子关系错位——模型看到的是一棵结构被打乱、看上去却
+ * 仍然合法的树，判断「这个按钮在哪个对话框里」时比截断更有害。所以输出严格按原序，
+ * 连续被删的段落就地留一条 `… 省略 N 行` 占位，让模型知道**哪里**有东西被省了。
+ */
+export function budgetSnapshot(snapshot, opts = {}) {
+    const maxLines = opts.maxLines ?? 80;
+    const maxChars = opts.maxChars ?? 6_000;
+    const lines = snapshot.split('\n').filter((line) => line.trim().length > 0);
+    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 keep = new Array(lines.length).fill(false);
+    let kept = 0;
+    let chars = 0;
+    const take = (index) => {
+        if (keep[index] || kept >= maxLines)
+            return;
+        const cost = clip(lines[index]).length + 1;
+        // 放不下就跳过这一行继续看下一行——`break` 会让一条超长行连累后面所有放得下的。
+        if (chars + cost > maxChars)
+            return;
+        keep[index] = true;
+        kept += 1;
+        chars += cost;
+    };
+    for (let i = 0; i < lines.length; i += 1)
+        if (hasRef(lines[i]))
+            take(i);
+    for (let i = 0; i < lines.length; i += 1)
+        if (!hasRef(lines[i]))
+            take(i);
+    const out = [];
+    let gap = 0;
+    const flushGap = () => {
+        if (gap > 0)
+            out.push(`  … 省略 ${gap} 行`);
+        gap = 0;
+    };
+    for (let i = 0; i < lines.length; i += 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 读取正文。');
+}