@xiaobuyu/nodesign 0.0.1

package/server/engine/browse/page-digest.js

@@ -0,0 +1,119 @@
+/**
+ * server/engine/browse/page-digest.js — 「这一页上有什么」的唯一一份采集器（2026-08-18）
+ *
+ * 两个消费者：`browser_read`（全量：正文 + 标题层级 + 链接清单）和
+ * `browser_navigate`（**打开就顺手带回一份摘要**）。
+ *
+ * ## 为什么 navigate 要带摘要
+ *
+ * 量过一轮（2026-08-18，这台机器）：冷启动 738ms、导航 1.0~4.5s、读页
+ * 29~183ms、视口截图 0.2~4.2s。**浏览器本体不慢**。慢的是回合数 ——
+ * `navigate` → `read` → `screenshot` 是三次模型往返，每一次的模型延迟都比
+ * 上面任何一个数字大。而 navigate 之后紧跟一次 read 几乎是必然的（不看看
+ * 页面上有什么，下一步无从决定）。
+ *
+ * 所以把 read 的采集器抽出来给 navigate 复用：一次导航直接回答"打开了，
+ * 上面有这些东西，站内可以往这几个地方去"。**省掉的是一整个回合**，
+ * 这是这条通道唯一真能砍掉的时间。
+ *
+ * 抽出来还有第二个收益：`browser_read` 报的东西和 `browser_navigate` 报的
+ * 东西**只有一个来源**。抄两份的下场是"同一页，两个工具说的结构数不一样"。
+ */
+
+/**
+ * 页面里跑的采集器。⚠️ 整段在浏览器上下文执行，不能引用外面的东西。
+ *
+ * @param {import('playwright').Page} page
+ * @param {{selector?: string|null, links?: boolean}} opts
+ */
+export function collectPage(page, { selector = null, links = true } = {}) {
+  return page.evaluate(({ sel, want }) => {
+    const root = sel ? document.querySelector(sel) : (document.querySelector('main') || document.body);
+    if (!root) return { missing: true };
+    const headings = [...root.querySelectorAll('h1,h2,h3')]
+      .map(h => `${'#'.repeat(Number(h.tagName[1]))} ${(h.textContent || '').trim().slice(0, 90)}`)
+      .filter(t => t.length > 2).slice(0, 40);
+    // ⛔ 链接**不能**跟正文共用 root。没传 selector 时正文 root 是 `main`
+    // （对：导航文字是噪音），但链接跟着 main 一收，站名、整条导航、页脚法务
+    // 链接就全没了 —— 实测 6 个链接只报出 1 个。而链接清单正是"下一步去哪"
+    // 的唯一依据，browser_click 的全部意义也是跟这些链接。
+    // 所以：正文按 root 收，链接按**整页**收，再标出它在哪个区。
+    const linkRoot = sel ? root : document;
+    const regionOf = (el) => {
+      for (let n = el; n && n !== document.documentElement; n = n.parentElement) {
+        const tag = n.tagName ? n.tagName.toLowerCase() : '';
+        if (tag === 'nav') return 'nav';
+        if (tag === 'header') return 'header';
+        if (tag === 'footer') return 'footer';
+        if (tag === 'aside') return 'aside';
+        const role = n.getAttribute && n.getAttribute('role');
+        if (role === 'navigation') return 'nav';
+        if (role === 'contentinfo') return 'footer';
+      }
+      return 'content';
+    };
+    const seen = new Set();
+    const RANK = { content: 0, header: 1, nav: 1, aside: 2, footer: 3 };
+    // ⚠️ **排序必须在截断之前**，而且得在页面里做：按文档顺序取前 80 条，
+    // 侧边导航就把配额吃干了（MDN 实测 79 条站内链接里前 30 条有 29 条是 nav，
+    // 正文那几条一条都没进来）。要跟的多半是正文里那几条。
+    const all = want ? [...linkRoot.querySelectorAll('a[href]')].map((a) => {
+      const href = a.href;
+      if (!href || !/^https?:/.test(href) || seen.has(href)) return null;
+      seen.add(href);
+      const label = (a.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 60);
+      return { href, label, internal: a.hostname === location.hostname, region: regionOf(a) };
+    }).filter(Boolean) : [];
+    const linkList = all
+      .map((l, i) => ({ l, i }))
+      .sort((x, y) => (RANK[x.l.region] ?? 0) - (RANK[y.l.region] ?? 0) || x.i - y.i)
+      .map(x => x.l)
+      .slice(0, 80);
+    return {
+      text: (root.innerText || '').replace(/\n{3,}/g, '\n\n').trim(),
+      headings, linkList,
+      textScope: sel || (document.querySelector('main') ? 'main' : 'body'),
+      counts: {   // ⚠️ 这几个数是**整页**的，别跟着正文 root 缩（原来标着"页面结构"其实是 main 里的）
+        sections: document.querySelectorAll('section, article').length,
+        images: document.querySelectorAll('img').length,
+        forms: document.querySelectorAll('form').length,
+      },
+    };
+  }, { sel: selector, want: links });
+}
+
+/** 区标只在非 content 时打 —— 正文链接是默认情况，标了全是噪音 */
+const fmtLink = (l) => `  ${l.label || '(无文字)'}${l.region && l.region !== 'content' ? ` [${l.region}]` : ''} → ${l.href}`;
+
+/**
+ * 采集结果 → 给 agent 的文本行。
+ *
+ * @param {object} data  collectPage 的返回
+ * @param {{compact?: boolean, cap?: number}} opts
+ *   compact = navigate 用的摘要档：短正文 + 少量标题 + 站内链接，够决定下一步就行
+ * @returns {string[]} 行（调用方自己在前面拼"现在在哪"）
+ */
+export function formatPage(data, { compact = false, cap } = {}) {
+  const textCap = cap ?? (compact ? 700 : 4000);
+  const maxHeadings = compact ? 12 : 40;
+  const maxInner = compact ? 14 : 30;
+  const body = data.text.length > textCap
+    ? `${data.text.slice(0, textCap)}\n… （还有 ${data.text.length - textCap} 个字符${compact ? '，要全文用 browser_read' : '，要全文就加大 maxChars 或用 selector 缩范围'}）`
+    : data.text;
+  // linkList 已经在页面里按区排过序（正文优先），这里只分站内/站外
+  const inner = data.linkList.filter(l => l.internal);
+  const outer = data.linkList.filter(l => !l.internal);
+  const headings = data.headings.slice(0, maxHeadings);
+
+  return [
+    `结构（整页）：${data.counts.sections} 个 section/article · ${data.counts.images} 张图 · ${data.counts.forms} 个表单`,
+    compact ? null
+      : `正文读的是 <${data.textScope}>${data.textScope === 'main' ? '（导航/页脚的文字不在里面，但它们的链接在下面）' : ''}`,
+    headings.length ? `\n标题层级：\n${headings.join('\n')}` : null,
+    `\n正文：\n${body || '(读不到文字 —— 可能整页是图或靠 JS 渲染，试 browser_navigate 带 waitUntil:"networkidle"，或直接截图看)'}`,
+    inner.length
+      ? `\n站内链接（${inner.length}${inner.length > maxInner ? `，列前 ${maxInner}` : ''}）—— 往里翻就跟这些：\n${inner.slice(0, maxInner).map(fmtLink).join('\n')}`
+      : null,
+    outer.length && !compact ? `\n站外链接（${outer.length}，只列前 8）：\n${outer.slice(0, 8).map(fmtLink).join('\n')}` : null,
+  ].filter(Boolean);
+}

package/server/engine/browse/refs.js

@@ -0,0 +1,196 @@
+/**
+ * server/engine/browse/refs.js — 元素引用（ref_N）登记 + 词法找元（2026-08-21）
+ *
+ * 给 `browser_find` / `browser_computer` 用。形状照 Anthropic 的 browser use
+ * toolset（browser_toolset_20260801）：`find` 返回带 `[ref_N]` 的元素清单，后面的
+ * 点击/悬停/滚到 可以拿 ref 当靶子，不必再从截图上读坐标。
+ *
+ * ## ref 的生命周期（照规格，不自作聪明）
+ *
+ * - ref 挂在**页面的 window** 上（`window.__nd_refs`）：导航 = 新 document =
+ *   自动清空。这正是规格要的"ref scoped to the tab, valid until it navigates"。
+ * - 同一页内编号**只增不回卷**：agent 手里的 ref_3 在它重新 find 之后还是那个元素
+ *   （规格原话：don't renumber references you've already handed out）。
+ * - 元素被页面重渲染拆掉 = `isConnected` 为假 = stale。按规格回一条可执行的错误
+ *   文本，agent 重新 find 一次就好。
+ *
+ * ## find 是**词法**匹配，不是语义
+ *
+ * Claude in Chrome 的 find 背后有个小模型；我们这台 1 vCPU 的机器不为每次找元
+ * 多付一次模型调用。这里用的是：query 分词（英文按词、中文按字+双字）对元素的
+ * 可见文字 / aria-label / placeholder / alt / 角色 / href 打分。工具描述里**明说**
+ * 这一点 —— agent 用元素上真出现的词去找，比用它脑补的意图词命中得多。
+ */
+
+/**
+ * 在页面里跑：收集候选元素、登记 ref、按 query 打分。
+ * ⚠️ 整段在浏览器上下文执行，不能引用外面的东西。
+ *
+ * @param {import('playwright').Page} page
+ * @param {{query: string, limit?: number}} opts
+ * @returns {Promise<{matches: object[], candidates: number, url: string}>}
+ */
+export function findInPage(page, { query, limit = 20 }) {
+  return page.evaluate(({ q, limit }) => {
+    const W = window;
+    if (!W.__nd_refs || W.__nd_refs.url !== location.href) {
+      W.__nd_refs = { n: 0, els: new Map(), byEl: new WeakMap(), url: location.href };
+    }
+    const reg = W.__nd_refs;
+    const refOf = (el) => {
+      const had = reg.byEl.get(el);
+      if (had) return had;
+      const id = `ref_${++reg.n}`;
+      reg.els.set(id, el);
+      reg.byEl.set(el, id);
+      return id;
+    };
+
+    const SEL = 'a[href], button, input, select, textarea, summary, label, [role], [onclick], '
+      + '[contenteditable=""], [contenteditable="true"], [tabindex]:not([tabindex="-1"]), '
+      + 'h1, h2, h3, img[alt], [aria-label]';
+    const vw = W.innerWidth;
+    const vh = W.innerHeight;
+    const visible = (el) => {
+      if (el.tagName === 'INPUT' && el.type === 'hidden') return false;
+      if (typeof el.checkVisibility === 'function'
+        && !el.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })) return false;
+      const r = el.getBoundingClientRect();
+      return r.width > 0 && r.height > 0;
+    };
+    const roleOf = (el) => {
+      const r = el.getAttribute('role');
+      if (r) return r;
+      const t = el.tagName.toLowerCase();
+      if (t === 'a') return 'link';
+      if (t === 'button' || t === 'summary') return 'button';
+      if (t === 'input') {
+        const ty = (el.type || 'text').toLowerCase();
+        if (['button', 'submit', 'reset', 'image'].includes(ty)) return 'button';
+        if (ty === 'checkbox') return 'checkbox';
+        if (ty === 'radio') return 'radio';
+        if (ty === 'range') return 'slider';
+        if (ty === 'file') return 'file';
+        return 'textbox';
+      }
+      if (t === 'textarea') return 'textbox';
+      if (t === 'select') return 'combobox';
+      if (/^h[1-6]$/.test(t)) return 'heading';
+      if (t === 'img') return 'image';
+      if (t === 'label') return 'label';
+      if (el.isContentEditable) return 'textbox';
+      return 'generic';
+    };
+    const clean = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+    const nameOf = (el) => {
+      const aria = clean(el.getAttribute('aria-label'));
+      if (aria) return aria;
+      const by = el.getAttribute('aria-labelledby');
+      if (by) {
+        const t = clean(by.split(/\s+/).map(id => document.getElementById(id)?.textContent || '').join(' '));
+        if (t) return t;
+      }
+      const t = el.tagName.toLowerCase();
+      if (t === 'input' || t === 'textarea' || t === 'select') {
+        if (el.labels && el.labels.length) { const l = clean(el.labels[0].textContent); if (l) return l; }
+        const ph = clean(el.getAttribute('placeholder'));
+        if (ph) return ph;
+        if (t === 'input' && ['button', 'submit', 'reset'].includes((el.type || '').toLowerCase())) return clean(el.value);
+      }
+      if (t === 'img') return clean(el.getAttribute('alt'));
+      return clean(el.innerText || el.textContent).slice(0, 80) || clean(el.getAttribute('title'));
+    };
+
+    // ── query 分词：英文按词；中文按单字 + 双字（"搜索框" 能命中 "搜索"）──
+    const qlow = clean(q).toLowerCase();
+    const toks = new Set();
+    for (const m of qlow.match(/[a-z0-9_-]+/g) || []) toks.add(m);
+    for (const run of qlow.match(/[㐀-鿿]+/g) || []) {
+      for (let i = 0; i < run.length; i += 1) {
+        toks.add(run[i]);
+        if (i + 1 < run.length) toks.add(run.slice(i, i + 2));
+      }
+    }
+    const ROLE_WORDS = {
+      button: ['button', 'btn', '按钮', '按键'],
+      link: ['link', 'anchor', '链接'],
+      textbox: ['input', 'field', 'textbox', 'search', 'box', 'textarea', 'editor', '输入框', '搜索框', '文本框', '输入', '搜索'],
+      checkbox: ['checkbox', 'check', '复选框', '勾选'],
+      radio: ['radio', '单选'],
+      combobox: ['select', 'dropdown', 'combobox', '下拉', '选择'],
+      heading: ['heading', 'title', 'header', '标题'],
+      image: ['image', 'img', 'picture', 'photo', 'logo', 'icon', '图', '图片', '图标'],
+      tab: ['tab', '标签页', '页签'],
+      menuitem: ['menu', 'menuitem', '菜单'],
+      slider: ['slider', 'range', '滑块'],
+      file: ['file', 'upload', '上传', '文件'],
+    };
+
+    const els = [...document.querySelectorAll(SEL)].filter(visible);
+    const scored = [];
+    els.forEach((el, order) => {
+      const name = nameOf(el);
+      const role = roleOf(el);
+      const href = el.tagName === 'A' ? (el.getAttribute('href') || '') : '';
+      const hint = [el.id, el.className && String(el.className), el.getAttribute('placeholder'),
+        el.getAttribute('title'), el.getAttribute('name'), href].filter(Boolean).join(' ').toLowerCase();
+      const nlow = name.toLowerCase();
+      const rwords = ROLE_WORDS[role] || [role];
+      let score = 0;
+      if (qlow && nlow === qlow) score += 6;
+      else if (qlow && nlow.includes(qlow)) score += 4;
+      for (const tk of toks) {
+        if (tk.length >= 2 && nlow.includes(tk)) score += 3;
+        else if (tk.length === 1 && /[㐀-鿿]/.test(tk) && nlow.includes(tk)) score += 1;
+        if (rwords.includes(tk)) score += 2;
+        if (hint.includes(tk)) score += 1;
+      }
+      if (score <= 0) return;
+      const r = el.getBoundingClientRect();
+      const inView = r.bottom > 0 && r.right > 0 && r.top < vh && r.left < vw;
+      if (inView) score += 0.5;
+      scored.push({
+        el, order, score, role, name, href,
+        x: Math.round(r.left + r.width / 2), y: Math.round(r.top + r.height / 2),
+        w: Math.round(r.width), h: Math.round(r.height), inView,
+      });
+    });
+    scored.sort((a, b) => b.score - a.score || a.order - b.order);
+    const matches = scored.slice(0, limit).map(({ el, order, ...rest }) => ({ ref: refOf(el), ...rest }));
+    return { matches, candidates: els.length, url: location.href };
+  }, { q: query, limit });
+}
+
+/** 把一个 ref 解析成 ElementHandle；stale/未知 → null。 */
+export async function handleForRef(page, ref) {
+  const h = await page.evaluateHandle((id) => {
+    const r = window.__nd_refs;
+    const el = r && r.els.get(id);
+    return el && el.isConnected ? el : null;
+  }, ref);
+  const el = h.asElement();
+  if (!el) { await h.dispose().catch(() => {}); return null; }
+  return el;
+}
+
+/** 规格里那句可执行的 stale 错误文本（agent 读了知道下一步是什么） */
+export const staleRefText = (ref) =>
+  `Error: ${ref} is stale or not found on the current page. Call browser_find again to get fresh references.`;
+
+/** find 结果 → 给 agent 的行 */
+export function formatMatches(r, query) {
+  if (!r.matches.length) {
+    return [
+      `「${query}」没找到匹配的元素（这一页有 ${r.candidates} 个可交互/可读元素）。`,
+      '匹配是词法的：换成元素上**真出现**的词（按钮文字、占位符、链接文案），或者写角色词（button/link/input/图片）。',
+      '还是没有就 browser_read 看看页面上到底有什么字，或 browser_computer screenshot 直接看。',
+    ];
+  }
+  const lines = [`找到 ${r.matches.length} 个（候选 ${r.candidates}）—— ref 可直接给 browser_computer，坐标是视口像素：`];
+  for (const m of r.matches) {
+    const where = m.inView ? `@(${m.x},${m.y})` : `@(${m.x},${m.y}) [视口外${m.y < 0 ? '↑' : '↓'}，点之前先 scroll_to]`;
+    const href = m.href && m.role === 'link' ? `  → ${m.href.slice(0, 70)}` : '';
+    lines.push(`  ${m.ref}  ${m.role}  「${m.name || '(无文字)'}」 ${m.w}×${m.h} ${where}${href}`);
+  }
+  return lines;
+}

package/server/engine/browse/registry.js

@@ -0,0 +1,307 @@
+/**
+ * server/engine/browse/registry.js — 常驻浏览器登记处（2026-08-18）
+ *
+ * agent 用浏览器看设计参考这条线的本体。**进程级单例，按 projectId 键。**
+ *
+ * ## 为什么是常驻，为什么按项目键
+ *
+ * 在这之前所有浏览器工具都是 launch→用→close 即弃（`screenshot-url.js` 那套），
+ * 所以**没有会话**：点不了链接、翻不了子页、登录态留不住、Cookie 同意弹窗每次重新
+ * 弹，想看第三层页面只能猜 URL。用户要的正是这条：让 agent 能真的**逛**。
+ *
+ * 键按 **projectId**（用户拍板）：项目 owner 唯一，所以这等于 per-user per-project；
+ * 登录态天然跨会话复用 —— 用户的原话是「**此后**从浏览器中获得的可复用内容」，
+ * 那个"此后"包含下一次开新对话。
+ *
+ * ## 这台机器只有 1 vCPU，所以每条约束都是硬的
+ *
+ * - 常驻浏览器 **≤ 2**：空闲实测 185 MiB PSS / 0.1% CPU，内存不是矛盾，但超了就
+ *   按 LRU 关最久没用的**空闲**那个；一个都腾不出来就**拒绝并告诉 agent**，
+ *   不静默排队（静默降级是这个仓库的老账）
+ * - 同项目的调用走 **mutex 串行**：同一个项目可能同时开着两个会话，两个 agent 抢
+ *   一个 page 会互相把对方导航走
+ * - 空闲 5 分钟回收（保留 profile）。timer `.unref()` —— 别让它拖着进程不退出
+ *
+ * ## 跟感知通道刻意分开的两条通道
+ *
+ * `perception-page.js` 的 `launchPerceptionBrowser` 是**感知通道**：URL 由我们构造
+ * （artifact-file loopback）、允许 loopback、用完即弃。这里是**浏览通道**：URL 由
+ * agent 自由指定、**loopback 一律禁**（SSRF 闸）、常驻带持久 profile。
+ * 两个函数并排放着而不是合成一个带 flag 的 —— 「同一件东西有多个实例」的反面是
+ * 「两件不同的东西硬塞进一个函数」，安全语义会被 flag 搅浑。共享的只有
+ * `FIDELITY_LAUNCH_ARGS` 那一份常量。
+ */
+
+import path from 'node:path';
+import { mutex } from 'async-mutex-lite';
+import { getProjectWorkspace } from '../../projects/workspace.js';
+import { FIDELITY_LAUNCH_ARGS } from '../mcp/tools/helpers/perception-page.js';
+import { attachSsrfGuard } from '../../lib/ssrf-guard.js';
+import { startBrowseProxy } from '../../lib/browse-proxy.js';
+
+/**
+ * 常驻上限（内存）。1 vCPU 上活跃画面流另有 ≤1 的上限，见 screencast 那一层。
+ *
+ * ⚠️ 写法要 NaN-safe：`Number('yes')` 是 NaN，而 `live.size >= NaN` **恒为 false**
+ * → 上限静默消失，chromium 无限起。这台机器 1 核 8G **无 swap**，尖峰直接进
+ * 内核 OOM killer。（隔壁 IDLE_MS 用的 `|| 默认` 写法本来就是 NaN-safe 的。）
+ */
+const MAX_RESIDENT = Number(process.env.ND_BROWSE_MAX) > 0
+  ? Math.floor(Number(process.env.ND_BROWSE_MAX)) : 2;
+/** 空闲多久回收。仿 h3box 的 ControlPersist=600 与 WS grace 的思路。 */
+const IDLE_MS = Number(process.env.ND_BROWSE_IDLE_MS || 0) || 5 * 60 * 1000;
+const NAV_TIMEOUT_MS = 30_000;
+
+/**
+ * 视口：桌面宽（看设计参考要的是版面不是移动端），**且坐标 1:1**。
+ * 08-21 从 1440×900 改 1366×768：改的时候 shot-pipeline 阈值还是 1568/1.15MP，1440×900=1.30MP
+ * 会被缩 0.94 倍 → browser_computer 从图上读的坐标和页面像素差 6%。同日阈值抬到 2000px/3.75MP
+ * 后 1440×900 其实也不缩了，但 1366×768 留着：便宜（≈1372 token/张）、是文档推荐档、坐标 1:1。
+ * 也是 Anthropic computer-use 文档给 web 应用推荐的档位。改它要连 browse-computer.test.js
+ * 的"视口在阈值内"断言一起过。
+ */
+const VIEWPORT = { width: 1366, height: 768 };
+
+/** projectId → entry */
+const live = new Map();
+
+/**
+ * ⭐ 把 UA 里的 HeadlessChrome 换成 Chrome。
+ *
+ * 依据是一篇受控实验（arXiv:2606.14525，Tranco Top 10K × 4 万次抓取）：在「只有
+ * headless 被封」的 784 个站上，**仅仅**把 UA 与 Client Hints 里的 `HeadlessChrome`
+ * 换成 `Chrome`，590 个（**75%**）当场转 HTTP 2xx。也就是说 headed 相对 headless
+ * 那 8 个百分点的优势，四分之三来自这个头部信号 —— 不是「headed 本身更像人」。
+ * 所以我们不装 Xvfb（1 vCPU 付不起一颗核，而且 headed vs **新** headless 全世界
+ * 没人测过），改这个字符串就吃满大头。
+ *
+ * ⚠️ 这不是为了绕强反爬（数据中心 IP 是改不掉的底噪，最凶的墙怎么配都拦 ——
+ * 那是「人接手」存在的理由）。这是为了不在最脏的一档上白挨拦。
+ */
+function chromeUa(raw) {
+  return String(raw).replace(/HeadlessChrome\//g, 'Chrome/');
+}
+
+async function launchBrowseBrowser(projectId) {
+  const { chromium } = await import('playwright');
+  // profile 必须落在 `<pid>/` 下、`shared/` **之外**：shared 是 agent 的 cwd 也是
+  // artifact-file 的服务根 —— 放进去等于 (a) cookie jar 能被当文件服出去
+  // (b) agent 能 Read 到自己的 cookie (c) 进 per-project git。
+  // 放兄弟位就都避开了，而且删项目时 removeProjectWorkspace 删的是整个 `<pid>/`
+  // （核过），profile 跟着走，不用额外写清理。
+  const userDataDir = path.join(getProjectWorkspace(projectId), '.browser', 'default');
+
+  // ⭐ 出网闸在**代理层**（2026-08-18 第二遍）：`--proxy-server` 之后 chromium 的
+  // 每一次连接都从这儿走 —— 包括 CDP 的 Fetch 阶段看不见的那些（WebSocket 握手、
+  // `<link rel=prefetch>`、sendBeacon、还没装上闸的弹窗）。理由与实测见
+  // lib/browse-proxy.js 文件头。CDP 那道闸保留当纵深，不再是唯一一道。
+  // ⚠️ `bypass: ''` 是必须的：默认会放过 loopback，那正好是我们最要拦的。
+  const { port: proxyPort } = await startBrowseProxy();
+
+  const context = await chromium.launchPersistentContext(userDataDir, {
+    channel: 'chromium',            // ⭐ 不是默认的 headless_shell，见 chromeUa 的注释
+    headless: true,
+    proxy: { server: `http://127.0.0.1:${proxyPort}`, bypass: '' },
+    // ⭐ WebRTC 是代理**看不见**的那条路：它走 UDP，不经 HTTP 代理，能被用来
+    // 探内网存活（STUN 打内网地址）。看设计参考完全不需要 WebRTC，所以直接
+    // 掐掉非代理 UDP —— 这是 Chromium 官方给的那个开关，不是我们发明的。
+    args: [...FIDELITY_LAUNCH_ARGS, '--force-webrtc-ip-handling-policy=disable_non_proxied_udp'],
+    viewport: VIEWPORT,
+    locale: 'zh-CN',                // 面向中文用户；顺带摆脱默认的 en-US@posix 那种怪指纹
+    timezoneId: 'Asia/Shanghai',
+    acceptDownloads: false,         // 下载不是这条线要的，而且是一条额外的写盘面
+  });
+
+  // proxied: true —— 第二道（连上后看对端 IP）在代理下是纯冗余，而且会把每个页面
+  // 都误杀（代理自己就是 127.0.0.1）。第一道（Fetch 阶段）保留当纵深。
+  const guard = await attachSsrfGuard(context, undefined, { proxied: true });
+  // 持久 context 自带一个空白页；没有就造一个
+  const page = context.pages()[0] || await context.newPage();
+  await guard.armPage(page);        // ⭐ 必须 await 完才允许导航（竞态是攻出来的）
+
+  // UA 与 Client Hints 一起改 —— 只改 UA 字符串的话 sec-ch-ua 还在报 headless
+  const cdp = await context.newCDPSession(page);
+  const realUa = await page.evaluate(() => navigator.userAgent);
+  const ua = chromeUa(realUa);
+  const m = realUa.match(/Chrome\/(\d+)/);
+  const major = m ? m[1] : '147';
+  await cdp.send('Emulation.setUserAgentOverride', {
+    userAgent: ua,
+    acceptLanguage: 'zh-CN,zh;q=0.9,en;q=0.8',
+    platform: 'Linux x86_64',
+    userAgentMetadata: {
+      brands: [
+        { brand: 'Chromium', version: major },
+        { brand: 'Google Chrome', version: major },
+        { brand: 'Not?A_Brand', version: '24' },
+      ],
+      fullVersion: `${major}.0.0.0`,
+      platform: 'Linux',
+      platformVersion: '6.1.0',
+      architecture: 'x86',
+      model: '',
+      mobile: false,
+    },
+  }).catch(() => { /* 覆盖不上就退回只改 UA 字符串那一档，别因此起不来 */ });
+
+  return { context, page, guard, ua };
+}
+
+function touch(entry) {
+  entry.lastUsed = Date.now();
+  clearTimeout(entry.idleTimer);
+  entry.idleTimer = setTimeout(() => { closeFor(entry.projectId, 'idle').catch(() => {}); }, IDLE_MS);
+  entry.idleTimer.unref?.();
+}
+
+/** 关掉某个项目的浏览器（**保留 profile** —— 登录态是资产） */
+export async function closeFor(projectId, why = 'explicit') {
+  const entry = live.get(projectId);
+  if (!entry) return false;
+  live.delete(projectId);
+  clearTimeout(entry.idleTimer);
+  // 先让画面流那一层知道（它要通知正在看的人，并且停掉编码），再关浏览器 ——
+  // 反过来的话 CDP 会话已经死了，stopScreencast 只会抛一堆没意义的错
+  try { (await import('./screencast.js')).forget(projectId); } catch { /* */ }
+  try { await entry.context.close(); } catch { /* 已经死了就算了 */ }
+  console.log(`[browse] closed ${projectId} (${why})`);
+  return true;
+}
+
+/** 腾一个位子出来：按 LRU 关最久没用的**空闲**实例。@returns 腾出来了没 */
+async function evictOne() {
+  const idle = [...live.values()].filter(e => !e.busy).sort((a, b) => a.lastUsed - b.lastUsed);
+  if (!idle.length) return false;
+  await closeFor(idle[0].projectId, 'evicted (LRU)');
+  return true;
+}
+
+/**
+ * 拿到某个项目的浏览器（懒启动）。**同项目串行**。
+ *
+ * @param {string} projectId
+ * @param {(h: {page: import('playwright').Page, guard: object, ua: string}) => Promise<any>} fn
+ * @returns {Promise<any>} fn 的返回值
+ * @throws 超上限时抛错，**不静默排队** —— agent 该看到"满了"这件事
+ */
+export async function withBrowser(projectId, fn) {
+  return mutex(`browse:${projectId}`, async () => {
+    let entry = live.get(projectId);
+    // ⚠️ 页可能已经不在了而 entry 还在：出网闸连到坏 IP 时会 `page.close()`
+    // （ssrf-guard 的 [connected] 兜底）。任意页面塞一个
+    // `<link rel=prefetch href=http://127.0.0.1:4001/>` 就能让常驻页变成一具尸体，
+    // 而 5 分钟空闲计时器才会清它 —— 等于给外站开了个远程杀开关。
+    // 这里发现就重建（别让 agent 拿着 "Target has been closed" 猜发生了什么）。
+    if (entry && entry.page.isClosed()) {
+      console.log(`[browse] ${projectId} 的页已被掐（多半是出网闸），重建`);
+      await closeFor(projectId, 'page was closed underneath us');
+      entry = null;
+    }
+    if (!entry) {
+      if (live.size >= MAX_RESIDENT && !(await evictOne())) {
+        throw Object.assign(
+          new Error(`浏览器实例已满（${live.size}/${MAX_RESIDENT} 都在用）。`
+            + '等一会儿再试，或者让别的会话先收工 —— 这台机器只有 1 个 CPU 核，常驻上限是硬的。'),
+          { status: 503 },
+        );
+      }
+      const t0 = Date.now();
+      const h = await launchBrowseBrowser(projectId);
+      entry = { projectId, ...h, lastUsed: Date.now(), busy: false, idleTimer: null };
+      live.set(projectId, entry);
+      console.log(`[browse] launched ${projectId} in ${Date.now() - t0}ms (${live.size}/${MAX_RESIDENT} resident)`);
+    }
+    entry.busy = true;
+    try {
+      touch(entry);
+      return await fn({ page: entry.page, guard: entry.guard, ua: entry.ua, context: entry.context });
+    } finally {
+      entry.busy = false;
+      touch(entry);   // 用完重新起计时，别让长调用被自己的旧计时器掐掉
+    }
+  });
+}
+
+// ⚠️ **刻意没有 onSessionEnd。** 计划里写了「会话结束时在 session-loop 的 finally
+// 里关掉该项目的浏览器」，落地时否掉了，理由两条：
+//   ① `active-runs` 是按 sessionId 键的，**没有「这个项目还有别的活会话吗」这个
+//      查询**。同一个项目同时开两个会话是常见的（用户经常这么用），照着关就是把
+//      另一个会话正在看的页面关掉。
+//   ② 5 分钟空闲回收已经覆盖了"人走了"这件事，而且它按**实际使用**判，不按会话
+//      生命周期判 —— 后者跟"浏览器还有没有人要用"其实不是一回事。
+// 与其造一个用不上的导出摆在这儿（这个仓库有过"全仓无人写入的字段假装第一优先级"
+// 那种账），不如写清为什么没有。
+
+/**
+ * 把某个项目的浏览器**钉住**：期间它不空闲、不会被 LRU 挤掉、不会被空闲计时器关。
+ *
+ * 为什么需要（审查抓到的）：`browser_request_help` 是在 `withBrowser` **外面**等人的
+ * （它必须放开 mutex，否则人在窗里点的每一下都会排在 agent 这次调用后面 = 死锁）。
+ * 于是等人的那 120 秒里 `busy` 是 false、`lastUsed` 不动 —— `evictOne` 正好挑
+ * "最久没用的空闲实例"，它就是那个**人正在过验证码的浏览器**。
+ *
+ * @returns {() => void} 松手（幂等）
+ */
+export function hold(projectId, why = 'held') {
+  const entry = live.get(projectId);
+  if (!entry) return () => {};
+  entry.busy = true;
+  entry.holds = (entry.holds || 0) + 1;
+  touch(entry);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const e = live.get(projectId);
+    if (!e) return;
+    e.holds = Math.max(0, (e.holds || 1) - 1);
+    if (!e.holds) e.busy = false;
+    touch(e);            // 松手时重新起计时，别让它带着旧计时器立刻被回收
+    console.log(`[browse] ${projectId} 松手（${why}）`);
+  };
+}
+
+/**
+ * 人在窗里动了一下 → 重置空闲计时。
+ * 没有这条的话：人安静看五分钟，浏览器在他眼前被关掉（空闲计时只认 agent 的调用）。
+ */
+export function touchProject(projectId) {
+  const entry = live.get(projectId);
+  if (entry) touch(entry);
+  return !!entry;
+}
+
+/**
+ * 刷新页面之后拿回「现在有没有浏览器 / agent 是不是正举着手」。
+ * 求助 banner 原来只靠一次性的 WS 事件，刷新即失传 —— agent 在那儿等两分钟没人知道。
+ */
+export function browseState(projectId) {
+  const e = live.get(projectId);
+  return {
+    live: !!e,
+    url: e ? e.page.url() : null,
+    busy: e ? !!e.busy : false,
+  };
+}
+
+/**
+ * 拿到某项目**已经在跑**的浏览器（不懒启动）。
+ * 给 WS 画面通道用：用户开窗时如果 agent 还没开始浏览，就该显示"还没开始"，
+ * 而不是替 agent 起一个浏览器（那会让 1 vCPU 上的常驻名额被看客占掉）。
+ */
+export function peek(projectId) {
+  const e = live.get(projectId);
+  return e ? { page: e.page, context: e.context, guard: e.guard } : null;
+}
+
+/** 给体检/日志用 */
+export function status() {
+  return [...live.values()].map(e => ({
+    projectId: e.projectId,
+    url: (() => { try { return e.page.url(); } catch { return '(gone)'; } })(),
+    idleMs: Date.now() - e.lastUsed,
+    busy: e.busy,
+  }));
+}
+
+export const _limits = { MAX_RESIDENT, IDLE_MS, NAV_TIMEOUT_MS, VIEWPORT };