@xiaobuyu/nodesign 0.0.1 → 0.0.3

package/server/engine/browse/card.js

@@ -1,137 +1,137 @@
-/**
- * server/engine/browse/card.js — 桌面上那张浏览器卡（2026-08-18）
- *
- * `/artifacts` 每次都会调它，所以要便宜：一次读小 json + 一次 stat，读不到就 null。
- *
- * ## 为什么它是一张卡，而不只是一扇窗
- *
- * 建这条通道时我在 `BrowserWindow.jsx` 的文件头里写过：「这扇窗不是产物…
- * **你不会想在桌面上永久摆着一张"某次浏览"的卡片**」。用户 2026-08-18 拍反了，
- * 而且理由比我的判断硬：agent 逛站这件事**用户要能随时进去看、随时接手**。
- * 只由 `run.browser_opened` 事件开窗意味着"错过就没了"——刷新一下、切个项目回来，
- * 那扇窗和它背后正在等人的 agent 就都找不见了。
- *
- * 所以卡片的性质要说清楚，它跟另外三种产物卡**不一样**：
- * - deck / 站点 / word 的真相是**磁盘上的文件**，卡是文件的投影；
- * - 这张卡的真相是**一段浏览痕迹**（`.browser/state.json`），卡是"上次逛到哪"的
- *   投影，背后那只 chromium 是**运行时**，可以不在（空闲 5 分钟就回收）。
- *
- * ## 它是「工具卡」这一类的第一张（2026-08-18 下午，用户定的类别）
- *
- * 用户的原话：「可以是单纯的内容卡，也可以是单纯的**工具卡**（工具存放工具采集到的
- * 内容，以及可互动工具的显示）」。所以这张卡同时是两样东西：
- *
- * 1. **一个目录**（`assets/references/web/`，一站一子文件夹）—— 工具采回来的东西
- *    住在里面，按站点产物那条范式：目录 = 单位，文件名表明类别；
- * 2. **一个可交互的东西** —— 双击进去是活的浏览器画面，能接手操作。
- *
- * 类别是**两条叠加的轴**（也是用户定的）：内容轴（这是什么）× 来源轴（谁产出的）。
- * 这张卡在内容轴上是 `tool`、来源轴上是 `tool`；agent 写的 deck 是 `work`+`agent`；
- * 用户传的图是 `material`+`user`。桌面按任意一条轴过滤。
- *
- * 后果是具体的：它不进 kinds 注册表（那张表登记的是**产物**形态）、不能导出、
- * 不进上下文托盘。它是入口 + 容器。
- */
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { browseState } from './registry.js';
-import { readVisit, framePath } from './state.js';
-import { CAPTURE_DIR } from './capture.js';
-import { getSharedDir } from '../../projects/workspace.js';
-
-/**
- * @param {string} projectId
- * @returns {Promise<null | {url: string, host: string, title: string|null,
- *                           at: string, live: boolean, busy: boolean, hasPreview: boolean}>}
- *   null = 这个项目没逛过任何站 → 桌面上就不该有这张卡
- */
-export async function browseCard(projectId) {
-  let visit = null;
-  let state = { live: false, url: null, busy: false };
-  try {
-    visit = await readVisit(projectId);
-    state = browseState(projectId);
-  } catch { return null; }
-  // 活实例的 url 才是当下；没有活实例时用落盘的那个（卡活得比实例长）
-  const raw = state.live ? (state.url || visit?.url) : visit?.url;
-  const url = (raw && /^https?:/.test(raw)) ? raw : null;
-  const sites = await collectedSites(projectId);
-  /**
-   * ⭐ 存在判据是**两者之一**：有访问记录，或者采到过东西。
-   *
-   * 只看访问记录是不够的（第一版就是，普查时逮到）：`state.json` 是 2026-08-18
-   * 下午才开始写的，而 `assets/references/web/` 里线上已经躺着别的项目采的东西 ——
-   * 那些项目会一张卡都没有，采集成果彻底看不见。反过来"逛过但没采"也该有卡
-   * （它是入口）。所以两条任一成立就出卡。
-   */
-  if (!url && !sites.length) return null;
-  const hasPreview = await fs.stat(framePath(projectId)).then(() => true, () => false);
-  return {
-    sites,
-    url,
-    host: (() => {
-      if (!url) return sites[0]?.site || '采集';   // 只有采集没有访问记录时，卡上写第一个站
-      try { return new URL(url).hostname.replace(/^www\./, ''); } catch { return url; }
-    })(),
-    title: visit?.title || null,
-    at: visit?.at || null,
-    live: !!state.live,
-    busy: !!state.busy,
-    hasPreview,
-  };
-}
-
-/**
- * 这个工具采回来的东西，**按站分组**（目录 = 单位）。
- *
- * 只 readdir 两层（站目录 + 里面的文件），不进 `.meta/`。封面取第一张 screenshot ——
- * 卡面和窗里的分组头都用它。读不到就当没有：采集清单列不出来不该让整张卡消失。
- */
-async function collectedSites(projectId) {
-  const root = path.join(getSharedDir(projectId), CAPTURE_DIR);
-  let ents;
-  try { ents = await fs.readdir(root, { withFileTypes: true }); } catch { return []; }
-  const groups = new Map();   // 站名 → { site, count, cover, dir }
-  const add = (site, dir, file) => {
-    const g = groups.get(site) || { site, count: 0, cover: null, dir };
-    g.count += 1;
-    if (!g.cover && /\.screenshot\.(webp|png)$/i.test(file)) g.cover = `${dir}/${file}`;
-    groups.set(site, g);
-  };
-
-  for (const d of ents) {
-    if (d.name.startsWith('.')) continue;
-    if (d.isDirectory()) {
-      // 现行布局：一站一文件夹
-      let files;
-      try { files = await fs.readdir(path.join(root, d.name)); } catch { continue; }
-      for (const f of files.filter(n => !n.startsWith('.'))) {
-        add(d.name, `${CAPTURE_DIR}/${d.name}`, f);
-      }
-    }
-  }
-
-  /**
-   * ⚠️ **存量：平铺在 `web/` 根上的老采集**（一站一文件夹是 2026-08-18 下午才改的）。
-   * 线上真有 —— 普查时另一个项目躺着 8 个。不认它们的话那张卡会写"采过 0 个站"，
-   * 而文件明明在，用户只会觉得东西丢了。
-   *
-   * 归站靠**出处 sidecar 里的 sourceUrl**，不是猜文件名前缀（老命名是
-   * `<host>-<时间>.<档>`，host 里带点、时间带横线，切出来的东西不能当站名）。
-   * **刻意不搬文件**：references 是用户数据，静默 mv 会打断任何引用了老路径的
-   * 东西（便签里记的路径、站点里 `<img src>`）。读的时候认就够了。
-   */
-  const loose = ents.filter(e => e.isFile() && !e.name.startsWith('.')).slice(0, 60);
-  for (const f of loose) {
-    let host = '早期采集';
-    try {
-      const stem = f.name.replace(/\.[^.]+$/, '');
-      const meta = JSON.parse(await fs.readFile(path.join(root, '.meta', `${stem}.json`), 'utf8'));
-      if (meta?.sourceUrl) host = new URL(meta.sourceUrl).hostname.replace(/^www\./, '');
-    } catch { /* 没出处就归到"早期采集" */ }
-    add(host, CAPTURE_DIR, f.name);
-  }
-
-  return [...groups.values()].sort((a, b) => b.count - a.count || a.site.localeCompare(b.site));
-}
+/**
+ * server/engine/browse/card.js — 桌面上那张浏览器卡（2026-08-18）
+ *
+ * `/artifacts` 每次都会调它，所以要便宜：一次读小 json + 一次 stat，读不到就 null。
+ *
+ * ## 为什么它是一张卡，而不只是一扇窗
+ *
+ * 建这条通道时我在 `BrowserWindow.jsx` 的文件头里写过：「这扇窗不是产物…
+ * **你不会想在桌面上永久摆着一张"某次浏览"的卡片**」。用户 2026-08-18 拍反了，
+ * 而且理由比我的判断硬：agent 逛站这件事**用户要能随时进去看、随时接手**。
+ * 只由 `run.browser_opened` 事件开窗意味着"错过就没了"——刷新一下、切个项目回来，
+ * 那扇窗和它背后正在等人的 agent 就都找不见了。
+ *
+ * 所以卡片的性质要说清楚，它跟另外三种产物卡**不一样**：
+ * - deck / 站点 / word 的真相是**磁盘上的文件**，卡是文件的投影；
+ * - 这张卡的真相是**一段浏览痕迹**（`.browser/state.json`），卡是"上次逛到哪"的
+ *   投影，背后那只 chromium 是**运行时**，可以不在（空闲 5 分钟就回收）。
+ *
+ * ## 它是「工具卡」这一类的第一张（2026-08-18 下午，用户定的类别）
+ *
+ * 用户的原话：「可以是单纯的内容卡，也可以是单纯的**工具卡**（工具存放工具采集到的
+ * 内容，以及可互动工具的显示）」。所以这张卡同时是两样东西：
+ *
+ * 1. **一个目录**（`assets/references/web/`，一站一子文件夹）—— 工具采回来的东西
+ *    住在里面，按站点产物那条范式：目录 = 单位，文件名表明类别；
+ * 2. **一个可交互的东西** —— 双击进去是活的浏览器画面，能接手操作。
+ *
+ * 类别是**两条叠加的轴**（也是用户定的）：内容轴（这是什么）× 来源轴（谁产出的）。
+ * 这张卡在内容轴上是 `tool`、来源轴上是 `tool`；agent 写的 deck 是 `work`+`agent`；
+ * 用户传的图是 `material`+`user`。桌面按任意一条轴过滤。
+ *
+ * 后果是具体的：它不进 kinds 注册表（那张表登记的是**产物**形态）、不能导出、
+ * 不进上下文托盘。它是入口 + 容器。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { browseState } from './registry.js';
+import { readVisit, framePath } from './state.js';
+import { CAPTURE_DIR } from './capture.js';
+import { getSharedDir } from '../../projects/workspace.js';
+
+/**
+ * @param {string} projectId
+ * @returns {Promise<null | {url: string, host: string, title: string|null,
+ *                           at: string, live: boolean, busy: boolean, hasPreview: boolean}>}
+ *   null = 这个项目没逛过任何站 → 桌面上就不该有这张卡
+ */
+export async function browseCard(projectId) {
+  let visit = null;
+  let state = { live: false, url: null, busy: false };
+  try {
+    visit = await readVisit(projectId);
+    state = browseState(projectId);
+  } catch { return null; }
+  // 活实例的 url 才是当下；没有活实例时用落盘的那个（卡活得比实例长）
+  const raw = state.live ? (state.url || visit?.url) : visit?.url;
+  const url = (raw && /^https?:/.test(raw)) ? raw : null;
+  const sites = await collectedSites(projectId);
+  /**
+   * ⭐ 存在判据是**两者之一**：有访问记录，或者采到过东西。
+   *
+   * 只看访问记录是不够的（第一版就是，普查时逮到）：`state.json` 是 2026-08-18
+   * 下午才开始写的，而 `assets/references/web/` 里线上已经躺着别的项目采的东西 ——
+   * 那些项目会一张卡都没有，采集成果彻底看不见。反过来"逛过但没采"也该有卡
+   * （它是入口）。所以两条任一成立就出卡。
+   */
+  if (!url && !sites.length) return null;
+  const hasPreview = await fs.stat(framePath(projectId)).then(() => true, () => false);
+  return {
+    sites,
+    url,
+    host: (() => {
+      if (!url) return sites[0]?.site || '采集';   // 只有采集没有访问记录时，卡上写第一个站
+      try { return new URL(url).hostname.replace(/^www\./, ''); } catch { return url; }
+    })(),
+    title: visit?.title || null,
+    at: visit?.at || null,
+    live: !!state.live,
+    busy: !!state.busy,
+    hasPreview,
+  };
+}
+
+/**
+ * 这个工具采回来的东西，**按站分组**（目录 = 单位）。
+ *
+ * 只 readdir 两层（站目录 + 里面的文件），不进 `.meta/`。封面取第一张 screenshot ——
+ * 卡面和窗里的分组头都用它。读不到就当没有：采集清单列不出来不该让整张卡消失。
+ */
+async function collectedSites(projectId) {
+  const root = path.join(getSharedDir(projectId), CAPTURE_DIR);
+  let ents;
+  try { ents = await fs.readdir(root, { withFileTypes: true }); } catch { return []; }
+  const groups = new Map();   // 站名 → { site, count, cover, dir }
+  const add = (site, dir, file) => {
+    const g = groups.get(site) || { site, count: 0, cover: null, dir };
+    g.count += 1;
+    if (!g.cover && /\.screenshot\.(webp|png)$/i.test(file)) g.cover = `${dir}/${file}`;
+    groups.set(site, g);
+  };
+
+  for (const d of ents) {
+    if (d.name.startsWith('.')) continue;
+    if (d.isDirectory()) {
+      // 现行布局：一站一文件夹
+      let files;
+      try { files = await fs.readdir(path.join(root, d.name)); } catch { continue; }
+      for (const f of files.filter(n => !n.startsWith('.'))) {
+        add(d.name, `${CAPTURE_DIR}/${d.name}`, f);
+      }
+    }
+  }
+
+  /**
+   * ⚠️ **存量：平铺在 `web/` 根上的老采集**（一站一文件夹是 2026-08-18 下午才改的）。
+   * 线上真有 —— 普查时另一个项目躺着 8 个。不认它们的话那张卡会写"采过 0 个站"，
+   * 而文件明明在，用户只会觉得东西丢了。
+   *
+   * 归站靠**出处 sidecar 里的 sourceUrl**，不是猜文件名前缀（老命名是
+   * `<host>-<时间>.<档>`，host 里带点、时间带横线，切出来的东西不能当站名）。
+   * **刻意不搬文件**：references 是用户数据，静默 mv 会打断任何引用了老路径的
+   * 东西（便签里记的路径、站点里 `<img src>`）。读的时候认就够了。
+   */
+  const loose = ents.filter(e => e.isFile() && !e.name.startsWith('.')).slice(0, 60);
+  for (const f of loose) {
+    let host = '早期采集';
+    try {
+      const stem = f.name.replace(/\.[^.]+$/, '');
+      const meta = JSON.parse(await fs.readFile(path.join(root, '.meta', `${stem}.json`), 'utf8'));
+      if (meta?.sourceUrl) host = new URL(meta.sourceUrl).hostname.replace(/^www\./, '');
+    } catch { /* 没出处就归到"早期采集" */ }
+    add(host, CAPTURE_DIR, f.name);
+  }
+
+  return [...groups.values()].sort((a, b) => b.count - a.count || a.site.localeCompare(b.site));
+}

package/server/engine/browse/handover.js

@@ -1,59 +1,59 @@
-/**
- * server/engine/browse/handover.js — agent 求助 / 人接手（2026-08-18）
- *
- * 用户拍的方向是「**agent 需要帮助的时候人类才介入**」，不做人与 agent 同时操作的
- * 共享控制。所以这一层很小：agent 举手 → 用户在窗里点几下 → 用户说"好了" → agent 继续。
- *
- * ## 为什么 agent 要**阻塞等**
- *
- * 接手期间页面状态被人改（过验证墙、登录、关弹窗），agent 并行去干别的会基于陈旧
- * 状态出错。所以 `browser_request_help` 就停在这儿等。
- *
- * ## 为什么必须有超时
- *
- * 人可能就走了。没有超时的话 agent 会挂到会话结束 —— 那是最糟的失败形态
- * （用户看到的是"它卡住了"，而不是"它说了它需要什么"）。
- */
-
-/** projectId → { resolve, timer, reason, since } */
-const waiting = new Map();
-
-export const HELP_TIMEOUT_MS = Number(process.env.ND_BROWSE_HELP_TIMEOUT_MS || 0) || 120_000;
-
-/**
- * agent 举手，等人。
- * @returns {Promise<{released: boolean, url: string|null, waitedMs: number, by: string}>}
- *   released=false 表示等超时了（人没来）
- */
-export function requestHelp(projectId, reason, { timeoutMs = HELP_TIMEOUT_MS } = {}) {
-  // 同一项目重复举手：把前一次直接放走（agent 不该被自己的两次求助卡死）
-  const prev = waiting.get(projectId);
-  if (prev) { clearTimeout(prev.timer); prev.resolve({ released: false, url: null, waitedMs: 0, by: 'superseded' }); }
-
-  const since = Date.now();
-  return new Promise((resolve) => {
-    const done = (v) => {
-      if (!waiting.has(projectId)) return;
-      clearTimeout(waiting.get(projectId).timer);
-      waiting.delete(projectId);
-      resolve({ ...v, waitedMs: Date.now() - since });
-    };
-    const timer = setTimeout(() => done({ released: false, url: null, by: 'timeout' }), timeoutMs);
-    timer.unref?.();
-    waiting.set(projectId, { resolve: done, timer, reason, since });
-  });
-}
-
-/** 人点了「好了继续」 */
-export function releaseHelp(projectId, { url = null, by = 'human' } = {}) {
-  const w = waiting.get(projectId);
-  if (!w) return false;
-  w.resolve({ released: true, url, by });
-  return true;
-}
-
-/** 有人在等吗（前端开窗时用来决定要不要亮 banner） */
-export function pendingHelp(projectId) {
-  const w = waiting.get(projectId);
-  return w ? { reason: w.reason, waitingMs: Date.now() - w.since } : null;
-}
+/**
+ * server/engine/browse/handover.js — agent 求助 / 人接手（2026-08-18）
+ *
+ * 用户拍的方向是「**agent 需要帮助的时候人类才介入**」，不做人与 agent 同时操作的
+ * 共享控制。所以这一层很小：agent 举手 → 用户在窗里点几下 → 用户说"好了" → agent 继续。
+ *
+ * ## 为什么 agent 要**阻塞等**
+ *
+ * 接手期间页面状态被人改（过验证墙、登录、关弹窗），agent 并行去干别的会基于陈旧
+ * 状态出错。所以 `browser_request_help` 就停在这儿等。
+ *
+ * ## 为什么必须有超时
+ *
+ * 人可能就走了。没有超时的话 agent 会挂到会话结束 —— 那是最糟的失败形态
+ * （用户看到的是"它卡住了"，而不是"它说了它需要什么"）。
+ */
+
+/** projectId → { resolve, timer, reason, since } */
+const waiting = new Map();
+
+export const HELP_TIMEOUT_MS = Number(process.env.ND_BROWSE_HELP_TIMEOUT_MS || 0) || 120_000;
+
+/**
+ * agent 举手，等人。
+ * @returns {Promise<{released: boolean, url: string|null, waitedMs: number, by: string}>}
+ *   released=false 表示等超时了（人没来）
+ */
+export function requestHelp(projectId, reason, { timeoutMs = HELP_TIMEOUT_MS } = {}) {
+  // 同一项目重复举手：把前一次直接放走（agent 不该被自己的两次求助卡死）
+  const prev = waiting.get(projectId);
+  if (prev) { clearTimeout(prev.timer); prev.resolve({ released: false, url: null, waitedMs: 0, by: 'superseded' }); }
+
+  const since = Date.now();
+  return new Promise((resolve) => {
+    const done = (v) => {
+      if (!waiting.has(projectId)) return;
+      clearTimeout(waiting.get(projectId).timer);
+      waiting.delete(projectId);
+      resolve({ ...v, waitedMs: Date.now() - since });
+    };
+    const timer = setTimeout(() => done({ released: false, url: null, by: 'timeout' }), timeoutMs);
+    timer.unref?.();
+    waiting.set(projectId, { resolve: done, timer, reason, since });
+  });
+}
+
+/** 人点了「好了继续」 */
+export function releaseHelp(projectId, { url = null, by = 'human' } = {}) {
+  const w = waiting.get(projectId);
+  if (!w) return false;
+  w.resolve({ released: true, url, by });
+  return true;
+}
+
+/** 有人在等吗（前端开窗时用来决定要不要亮 banner） */
+export function pendingHelp(projectId) {
+  const w = waiting.get(projectId);
+  return w ? { reason: w.reason, waitingMs: Date.now() - w.since } : null;
+}

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

@@ -1,119 +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);
-}
+/**
+ * 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);
+}