@xiaobuyu/nodesign 0.0.1 → 0.0.3

package/server/lib/board-relations.js

@@ -1,133 +1,133 @@
-/**
- * server/lib/board-relations.js — 关系线的 agent 读侧（2026-08-14，切片③）
- *
- * 在此之前 bindings 是**只写不读**的：agent 有 relate_on_board 能画线、用户
- * 在画布上看得见，但没有任何一层把「用户画了什么关系」喂回 agent —— 线是
- * 装饰。这份文件是读侧的唯一实现，两个消费口都从这儿取：
- *
- *   1. UserPromptSubmit 摘要（relationsDigest）：每轮把全图压成 ≤N 行，
- *      用户画的排前面 —— 他专门画的线就是他想让你知道的事。
- *   2. PreToolUse 邻域（fileNeighborhood）：agent 摸某个文件时，只注连着
- *      这个文件的边（摘要被截断时的精确补充）。
- *
- * 端点是画布 id（= kind 前缀 + 工作区相对路径，或画布原生 id `text:`/
- * `scribble:`）。手写字端点渲染**内容本身**——这是「标注作用全局」的关键一步：
- * 用户在画布上写的字经由一条线变成 agent 眼里的上下文。涂鸦端点诚实占位
- * （笔画内容看不见，要看得截图），不假装理解。
- */
-
-import { readBoard } from '../projects/board-store.js';
-import { BINDING_TYPES } from './binding-types.js';
-import { KINDS } from './kinds/index.js';
-
-// ⚠️ **从注册表派生，别手写**（2026-08-18 修）。这行原来写死 `['deck:','site:']`，
-// 于是 docx 上线之后 `docx:` 前缀的卡不在表里 —— **它们身上的关系线 agent 一条也
-// 看不见**（endpointMatchesRel 永远不匹配），而且错得很安静。
-// 这是「加形态时最容易漏的写死处」家族的第三处（前两处是前端 cardIdOf 和
-// BoardCanvas 的 type:'deck'，08-17 已修）。
-const KIND_PREFIXES = Object.keys(KINDS).map(id => `${id}:`);
-
-// 目录型形态的前缀（kind 条目声明了 directory 的那些）。2026-08-18 补修：
-// 下面 endpointMatchesRel 的收敛循环原来写死 `['site:']` —— 上面 KIND_PREFIXES
-// 修掉写死表的同一天，这半个同款病漏掉了：word 文件夹卡（docx:报告）身上的边，
-// agent 摸成员文件（报告/终稿v2.docx）时注不进 fileNeighborhood。
-const DIR_KIND_PREFIXES = Object.entries(KINDS)
-  .filter(([, def]) => def.directory).map(([id]) => `${id}:`);
-
-/** 端点 id → 给 agent 看的一小段描述 */
-export function describeEndpoint(end, board) {
-  const obj = board?.objects?.[end];
-  if (obj?.kind === 'text') {
-    const t = String(obj.data?.t || '').replace(/\s+/g, ' ').trim().slice(0, 80);
-    return `手写字「${t}」`;
-  }
-  if (obj?.kind === 'scribble') return '一笔涂鸦（笔画内容要看得截图画布）';
-  for (const p of KIND_PREFIXES) {
-    if (end.startsWith(p)) {
-      const rel = end.slice(p.length);
-      const kind = p.slice(0, -1);
-      return rel ? `${rel}（${kind}）` : `工作区根上的${kind}`;
-    }
-  }
-  return end;   // 裸文件路径或文件夹路径
-}
-
-/** 一条边 → 一行中文。方向用箭头表达，无向用平线。 */
-export function bindingLine(b, board) {
-  const t = BINDING_TYPES[b.type];
-  const word = b.label || t?.label || b.type;
-  const joint = t?.directed ? `─${word}→` : `─${word}─`;
-  const who = b.by === 'user' ? '〔用户画的〕' : b.by === 'agent' ? '〔你画的〕' : '';
-  return `${describeEndpoint(b.from, board)} ${joint} ${describeEndpoint(b.to, board)}${who}`;
-}
-
-/**
- * 全图摘要。用户画的排前面（他专门画的 = 他想让你知道的），截断报余量。
- * 没有任何线 → null（沉默，不占 prompt）。
- */
-export async function relationsDigest(pid, { limit = 12 } = {}) {
-  if (!pid) return null;
-  const board = await readBoard(pid);
-  const all = Object.values(board.bindings || {});
-  if (!all.length) return null;
-  // 手画的逐条列；自动 ref（内容引用对账出来的底仓）**收拢成每源一行**——
-  // 一个站引三十张图，铺开就把摘要刷没了。优先级 user > agent > auto。
-  const manual = [
-    ...all.filter(b => b.by === 'user'),
-    ...all.filter(b => b.by === 'agent'),
-    ...all.filter(b => b.by !== 'user' && b.by !== 'agent' && !(b.by === 'auto' && b.type === 'ref')),
-  ];
-  const autoRefs = all.filter(b => b.by === 'auto' && b.type === 'ref');
-  const lines = manual.slice(0, limit).map(b => `  ${bindingLine(b, board)}`);
-  const more = manual.length - lines.length;
-  if (more > 0) lines.push(`  …还有 ${more} 条（摸到相关文件时会单独提示）`);
-  if (autoRefs.length) {
-    const bySrc = new Map();
-    for (const b of autoRefs) {
-      if (!bySrc.has(b.from)) bySrc.set(b.from, []);
-      bySrc.get(b.from).push(b.to);
-    }
-    for (const [from, tos] of [...bySrc].slice(0, 4)) {
-      const sample = tos.slice(0, 3).join('、');
-      lines.push(`  ${describeEndpoint(from, board)} ─取材─ ${tos.length} 件素材（自动对账：${sample}${tos.length > 3 ? ' 等' : ''}）`);
-    }
-    if (bySrc.size > 4) lines.push(`  …另有 ${bySrc.size - 4} 件产物的取材清单省略`);
-  }
-  return lines.join('\n');
-}
-
-/** 某个端点 id 是否指向这个工作区相对路径（裸路径或任一 kind 前缀形态）。
- *  导出仅供测试钉规则（fileNeighborhood 是唯一业务调用方）。 */
-export function endpointMatchesRel(end, rel) {
-  if (end === rel) return true;
-  for (const p of KIND_PREFIXES) if (end === p + rel) return true;
-  // 目录型产物的收敛（2026-08-14 根站病族普查补上的）：站点/word 文件夹的边
-  // 挂在**根卡**上，agent 摸的是里面的文件 —— 原来只做精确匹配，等于站点页的
-  // 一跳邻域从来注入不出来。按"住在这个根里"匹配；根站（root=空串）收根层
-  // 散文件（.md 除外）—— 与前端 resolveObjectId 同一条规则，两边别岔开。
-  for (const p of DIR_KIND_PREFIXES) {
-    if (!end.startsWith(p)) continue;
-    const root = end.slice(p.length);
-    if (root === '') {
-      if (!rel.includes('/') && !/\.md$/i.test(rel)) return true;
-      continue;
-    }
-    if (rel === root || rel.startsWith(`${root}/`)) return true;
-  }
-  return false;
-}
-
-/**
- * 一跳邻域：连着某个文件/文件夹的全部边。没有 → null。
- * PreToolUse 注入用 —— agent 正要摸的东西，它身上的线最相关。
- */
-export async function fileNeighborhood(pid, rel, { limit = 6 } = {}) {
-  if (!pid || !rel) return null;
-  const board = await readBoard(pid);
-  const hits = Object.values(board.bindings || {})
-    .filter(b => endpointMatchesRel(b.from, rel) || endpointMatchesRel(b.to, rel));
-  if (!hits.length) return null;
-  const lines = hits.slice(0, limit).map(b => `  ${bindingLine(b, board)}`);
-  if (hits.length > limit) lines.push(`  …还有 ${hits.length - limit} 条`);
-  return lines.join('\n');
-}
+/**
+ * server/lib/board-relations.js — 关系线的 agent 读侧（2026-08-14，切片③）
+ *
+ * 在此之前 bindings 是**只写不读**的：agent 有 relate_on_board 能画线、用户
+ * 在画布上看得见，但没有任何一层把「用户画了什么关系」喂回 agent —— 线是
+ * 装饰。这份文件是读侧的唯一实现，两个消费口都从这儿取：
+ *
+ *   1. UserPromptSubmit 摘要（relationsDigest）：每轮把全图压成 ≤N 行，
+ *      用户画的排前面 —— 他专门画的线就是他想让你知道的事。
+ *   2. PreToolUse 邻域（fileNeighborhood）：agent 摸某个文件时，只注连着
+ *      这个文件的边（摘要被截断时的精确补充）。
+ *
+ * 端点是画布 id（= kind 前缀 + 工作区相对路径，或画布原生 id `text:`/
+ * `scribble:`）。手写字端点渲染**内容本身**——这是「标注作用全局」的关键一步：
+ * 用户在画布上写的字经由一条线变成 agent 眼里的上下文。涂鸦端点诚实占位
+ * （笔画内容看不见，要看得截图），不假装理解。
+ */
+
+import { readBoard } from '../projects/board-store.js';
+import { BINDING_TYPES } from './binding-types.js';
+import { KINDS } from './kinds/index.js';
+
+// ⚠️ **从注册表派生，别手写**（2026-08-18 修）。这行原来写死 `['deck:','site:']`，
+// 于是 docx 上线之后 `docx:` 前缀的卡不在表里 —— **它们身上的关系线 agent 一条也
+// 看不见**（endpointMatchesRel 永远不匹配），而且错得很安静。
+// 这是「加形态时最容易漏的写死处」家族的第三处（前两处是前端 cardIdOf 和
+// BoardCanvas 的 type:'deck'，08-17 已修）。
+const KIND_PREFIXES = Object.keys(KINDS).map(id => `${id}:`);
+
+// 目录型形态的前缀（kind 条目声明了 directory 的那些）。2026-08-18 补修：
+// 下面 endpointMatchesRel 的收敛循环原来写死 `['site:']` —— 上面 KIND_PREFIXES
+// 修掉写死表的同一天，这半个同款病漏掉了：word 文件夹卡（docx:报告）身上的边，
+// agent 摸成员文件（报告/终稿v2.docx）时注不进 fileNeighborhood。
+const DIR_KIND_PREFIXES = Object.entries(KINDS)
+  .filter(([, def]) => def.directory).map(([id]) => `${id}:`);
+
+/** 端点 id → 给 agent 看的一小段描述 */
+export function describeEndpoint(end, board) {
+  const obj = board?.objects?.[end];
+  if (obj?.kind === 'text') {
+    const t = String(obj.data?.t || '').replace(/\s+/g, ' ').trim().slice(0, 48);
+    return `手写字「${t}」`;
+  }
+  if (obj?.kind === 'scribble') return '一笔涂鸦（笔画内容要看得截图画布）';
+  for (const p of KIND_PREFIXES) {
+    if (end.startsWith(p)) {
+      const rel = end.slice(p.length);
+      const kind = p.slice(0, -1);
+      return rel ? `${rel}（${kind}）` : `工作区根上的${kind}`;
+    }
+  }
+  return end;   // 裸文件路径或文件夹路径
+}
+
+/** 一条边 → 一行中文。方向用箭头表达，无向用平线。 */
+export function bindingLine(b, board) {
+  const t = BINDING_TYPES[b.type];
+  const word = b.label || t?.label || b.type;
+  const joint = t?.directed ? `─${word}→` : `─${word}─`;
+  const who = b.by === 'user' ? '〔用户画的〕' : b.by === 'agent' ? '〔你画的〕' : '';
+  return `${describeEndpoint(b.from, board)} ${joint} ${describeEndpoint(b.to, board)}${who}`;
+}
+
+/**
+ * 全图摘要。用户画的排前面（他专门画的 = 他想让你知道的），截断报余量。
+ * 没有任何线 → null（沉默，不占 prompt）。
+ */
+export async function relationsDigest(pid, { limit = 12 } = {}) {
+  if (!pid) return null;
+  const board = await readBoard(pid);
+  const all = Object.values(board.bindings || {});
+  if (!all.length) return null;
+  // 手画的逐条列；自动 ref（内容引用对账出来的底仓）**收拢成每源一行**——
+  // 一个站引三十张图，铺开就把摘要刷没了。优先级 user > agent > auto。
+  const manual = [
+    ...all.filter(b => b.by === 'user'),
+    ...all.filter(b => b.by === 'agent'),
+    ...all.filter(b => b.by !== 'user' && b.by !== 'agent' && !(b.by === 'auto' && b.type === 'ref')),
+  ];
+  const autoRefs = all.filter(b => b.by === 'auto' && b.type === 'ref');
+  const lines = manual.slice(0, limit).map(b => `  ${bindingLine(b, board)}`);
+  const more = manual.length - lines.length;
+  if (more > 0) lines.push(`  …还有 ${more} 条（摸到相关文件时会单独提示）`);
+  if (autoRefs.length) {
+    const bySrc = new Map();
+    for (const b of autoRefs) {
+      if (!bySrc.has(b.from)) bySrc.set(b.from, []);
+      bySrc.get(b.from).push(b.to);
+    }
+    for (const [from, tos] of [...bySrc].slice(0, 4)) {
+      const sample = tos.slice(0, 3).join('、');
+      lines.push(`  ${describeEndpoint(from, board)} ─取材─ ${tos.length} 件素材（自动对账：${sample}${tos.length > 3 ? ' 等' : ''}）`);
+    }
+    if (bySrc.size > 4) lines.push(`  …另有 ${bySrc.size - 4} 件产物的取材清单省略`);
+  }
+  return lines.join('\n');
+}
+
+/** 某个端点 id 是否指向这个工作区相对路径（裸路径或任一 kind 前缀形态）。
+ *  导出仅供测试钉规则（fileNeighborhood 是唯一业务调用方）。 */
+export function endpointMatchesRel(end, rel) {
+  if (end === rel) return true;
+  for (const p of KIND_PREFIXES) if (end === p + rel) return true;
+  // 目录型产物的收敛（2026-08-14 根站病族普查补上的）：站点/word 文件夹的边
+  // 挂在**根卡**上，agent 摸的是里面的文件 —— 原来只做精确匹配，等于站点页的
+  // 一跳邻域从来注入不出来。按"住在这个根里"匹配；根站（root=空串）收根层
+  // 散文件（.md 除外）—— 与前端 resolveObjectId 同一条规则，两边别岔开。
+  for (const p of DIR_KIND_PREFIXES) {
+    if (!end.startsWith(p)) continue;
+    const root = end.slice(p.length);
+    if (root === '') {
+      if (!rel.includes('/') && !/\.md$/i.test(rel)) return true;
+      continue;
+    }
+    if (rel === root || rel.startsWith(`${root}/`)) return true;
+  }
+  return false;
+}
+
+/**
+ * 一跳邻域：连着某个文件/文件夹的全部边。没有 → null。
+ * PreToolUse 注入用 —— agent 正要摸的东西，它身上的线最相关。
+ */
+export async function fileNeighborhood(pid, rel, { limit = 6 } = {}) {
+  if (!pid || !rel) return null;
+  const board = await readBoard(pid);
+  const hits = Object.values(board.bindings || {})
+    .filter(b => endpointMatchesRel(b.from, rel) || endpointMatchesRel(b.to, rel));
+  if (!hits.length) return null;
+  const lines = hits.slice(0, limit).map(b => `  ${bindingLine(b, board)}`);
+  if (hits.length > limit) lines.push(`  …还有 ${hits.length - limit} 条`);
+  return lines.join('\n');
+}

package/server/lib/browse-proxy.js

@@ -1,180 +1,180 @@
-/**
- * server/lib/browse-proxy.js — 浏览通道的出网闸，装在**代理层**（2026-08-18）
- *
- * ## 为什么闸从 CDP 挪到代理
- *
- * 第一版把闸装在 CDP 的 `Fetch.requestPaused` 上。它拦得住导航、子资源、跳转每一跳、
- * 跨源 iframe —— 但审查真攻出来四条它**根本看不见**的路：
- *
- *   - **WebSocket 握手**（`ws://127.0.0.1:4001` 双向读到了数据）
- *   - **`<link rel=prefetch>` / speculation rules**（打到了生产 :4001）
- *   - **`navigator.sendBeacon`**
- *   - **还没装上闸的弹窗**（`window.open` / `target=_blank`，在那 250ms 窗口里
- *     能发 GET 和 POST，还能循环开）
- *
- * 共同点是它们都不走 `Fetch` 那个阶段。**逐条补是补不完的** —— 下一个 web 平台特性
- * 又会开一条。所以闸挪到**所有出网都必经的那一层**：给这个浏览器挂一个我们自己的
- * HTTP 代理，`--proxy-server` 之后 chromium 的每一次连接都从这儿走。
- * 实测代理确实看得到上面四条全部（包括 WS 的 `CONNECT 127.0.0.1:4001`）。
- *
- * ## 附带白拿的两件
- *
- * 1. ⭐ **DNS 重绑定被根除，不再是"缓解"。** 我们自己解析、自己**连那个验过的 IP**
- *    （pin），浏览器拿不到第二次解析的机会。CDP 那版只能是"解析一次→浏览器再解析
- *    一次"，中间有 TOCTOU 窗口，而且主机名缓存把窗口变成了保证 30 秒的洞。
- * 2. **没有初始化竞态。** 代理在浏览器启动参数里，第一个字节之前就生效；
- *    CDP 那版要等 `Fetch.enable` 握手完，弹窗根本等不到。
- *
- * CDP 那道闸**保留**当纵深（它能给出漂亮的按请求记账），但不再是唯一一道。
- *
- * ## 感知通道不挂代理
- *
- * 感知通道（看自己产物）**故意**走 loopback 的 artifact-file，它必须能到 127.0.0.1。
- * 所以只有浏览通道的浏览器带 `--proxy-server`，两条通道在这一层物理分开。
- */
-
-import http from 'node:http';
-import net from 'node:net';
-import dns from 'node:dns/promises';
-import { blockReason } from './ssrf-guard.js';
-
-/** 允许连的端口。80/443 之外的公网端口极少是设计参考站，而放开等于多一片攻击面。 */
-const ALLOWED_PORTS = new Set([80, 443, 8080, 8443]);
-const RESOLVE_TIMEOUT_MS = 4000;
-const CONNECT_TIMEOUT_MS = 15_000;
-
-let server = null;
-let port = 0;
-const blocked = [];
-
-function note(target, reason) {
-  blocked.push({ target, reason, at: Date.now() });
-  if (blocked.length > 200) blocked.shift();
-}
-
-/**
- * 解析 + 判定，返回可以连的那个 IP（**pin 住它**，不把主机名交给下游再解析一次）。
- * @returns {Promise<{ip: string, family: number} | {deny: string}>}
- */
-async function resolveAllowed(host, portNum) {
-  if (!ALLOWED_PORTS.has(portNum)) {
-    return { deny: `port ${portNum} is not allowed (only ${[...ALLOWED_PORTS].join('/')})` };
-  }
-  const bare = host.toLowerCase().replace(/^\[|\]$/g, '');
-  if (bare === 'localhost' || bare.endsWith('.localhost') || bare.endsWith('.local')) {
-    return { deny: `${bare} resolves inside the local network` };
-  }
-  // 字面量 IP 不劳烦 DNS
-  if (/^\d+\.\d+\.\d+\.\d+$/.test(bare) || bare.includes(':')) {
-    const why = blockReason(bare);
-    return why ? { deny: why } : { ip: bare, family: bare.includes(':') ? 6 : 4 };
-  }
-  let addrs;
-  try {
-    addrs = await Promise.race([
-      dns.lookup(bare, { all: true, verbatim: true }),
-      new Promise((_, rej) => setTimeout(() => rej(new Error('dns timeout')), RESOLVE_TIMEOUT_MS)),
-    ]);
-  } catch (err) {
-    // ⚠️ kind:'dns' 是给 denyBody 分文案用的：解析失败**不是策略拦截**。
-    // 第一版对 NXDOMAIN 也甩「内网与本机地址是硬边界」，agent 上报时据此
-    // 推理出一整套"代理有两个解析器"的错误理论 —— 错误提示比没提示更贵。
-    return { deny: `cannot resolve ${bare}: ${err.message}`, kind: 'dns' };
-  }
-  if (!addrs.length) return { deny: `${bare} resolved to nothing`, kind: 'dns' };
-  // **任一**地址落在禁止段就整个拒 —— 多 A 记录里混一条内网是标准起手式，
-  // "挑一个能用的"等于自己开门
-  for (const a of addrs) {
-    const why = blockReason(a.address);
-    if (why) return { deny: `${bare} → ${why}` };
-  }
-  return { ip: addrs[0].address, family: addrs[0].family };
-}
-
-// 按拒因分文案：DNS 解析失败要说清"这个域名现在指不到任何地方"，
-// 策略拦截才配那句硬边界 —— 两种拒混着说，agent 会朝错误的方向排障。
-const denyTail = (kind) => (kind === 'dns'
-  ? '这是域名解析失败（域名可能不存在、拼错或已下线），不是出网策略拦截。'
-  : '内网与本机地址是硬边界，不是可配置项。');
-
-const denyBody = (reason, kind) => {
-  const body = `拒绝出网：${reason}\n\n${denyTail(kind)}`;
-  return `HTTP/1.1 403 Forbidden\r\nContent-Type: text/plain; charset=utf-8\r\n`
-    + `Content-Length: ${Buffer.byteLength(body)}\r\nConnection: close\r\n\r\n${body}`;
-};
-
-/** 启动（幂等）。@returns {Promise<{port:number, blocked:Array}>} */
-export async function startBrowseProxy() {
-  if (server) return { port, blocked };
-
-  server = http.createServer();
-
-  // 明文 http：绝对形式的请求行（`GET http://host/path`）
-  server.on('request', async (req, res) => {
-    let u;
-    try { u = new URL(req.url); } catch {
-      res.writeHead(400); return res.end('proxy: bad absolute-form request');
-    }
-    const p = Number(u.port || (u.protocol === 'https:' ? 443 : 80));
-    const verdict = await resolveAllowed(u.hostname, p);
-    if (verdict.deny) {
-      note(`${u.hostname}:${p}`, verdict.deny);
-      res.writeHead(403, { 'Content-Type': 'text/plain; charset=utf-8' });
-      return res.end(`拒绝出网：${verdict.deny}\n\n${denyTail(verdict.kind)}`);
-    }
-    // 连**验过的那个 IP**，Host 头保留原主机名（虚拟主机才认得出）
-    const upstream = http.request({
-      host: verdict.ip, port: p, method: req.method,
-      path: u.pathname + u.search,
-      headers: { ...req.headers, host: u.host },
-      timeout: CONNECT_TIMEOUT_MS,
-      setHost: false,
-    }, (up) => {
-      res.writeHead(up.statusCode || 502, up.headers);
-      up.pipe(res);
-    });
-    upstream.on('error', (err) => {
-      if (!res.headersSent) res.writeHead(502, { 'Content-Type': 'text/plain' });
-      res.end(`proxy upstream error: ${err.message}`);
-    });
-    req.pipe(upstream);
-  });
-
-  // CONNECT：https / wss 都走这条（**WS 就是靠它被盖住的**）
-  server.on('connect', async (req, socket, head) => {
-    const [rawHost, rawPort] = String(req.url || '').split(':');
-    const p = Number(rawPort || 443);
-    const verdict = await resolveAllowed(rawHost || '', p);
-    if (verdict.deny) {
-      note(`${rawHost}:${p}`, verdict.deny);
-      socket.write(denyBody(verdict.deny, verdict.kind));
-      return socket.destroy();
-    }
-    const up = net.connect({ host: verdict.ip, port: p }, () => {
-      socket.write('HTTP/1.1 200 Connection Established\r\nProxy-Agent: nodesign-browse\r\n\r\n');
-      if (head?.length) up.write(head);
-      socket.pipe(up); up.pipe(socket);
-    });
-    up.setTimeout(CONNECT_TIMEOUT_MS, () => up.destroy());
-    up.on('error', () => { try { socket.destroy(); } catch { /* */ } });
-    socket.on('error', () => { try { up.destroy(); } catch { /* */ } });
-  });
-
-  await new Promise((resolve, reject) => {
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', resolve);
-  });
-  port = server.address().port;
-  server.unref?.();
-  console.log(`[browse-proxy] listening on 127.0.0.1:${port}`);
-  return { port, blocked };
-}
-
-/** 给工具的返回值用：这次调用期间拦了什么 */
-export function blockedSince(n) {
-  return blocked.slice(n);
-}
-export function blockedCount() {
-  return blocked.length;
-}
-export const _proxy = { ALLOWED_PORTS };
+/**
+ * server/lib/browse-proxy.js — 浏览通道的出网闸，装在**代理层**（2026-08-18）
+ *
+ * ## 为什么闸从 CDP 挪到代理
+ *
+ * 第一版把闸装在 CDP 的 `Fetch.requestPaused` 上。它拦得住导航、子资源、跳转每一跳、
+ * 跨源 iframe —— 但审查真攻出来四条它**根本看不见**的路：
+ *
+ *   - **WebSocket 握手**（`ws://127.0.0.1:4001` 双向读到了数据）
+ *   - **`<link rel=prefetch>` / speculation rules**（打到了生产 :4001）
+ *   - **`navigator.sendBeacon`**
+ *   - **还没装上闸的弹窗**（`window.open` / `target=_blank`，在那 250ms 窗口里
+ *     能发 GET 和 POST，还能循环开）
+ *
+ * 共同点是它们都不走 `Fetch` 那个阶段。**逐条补是补不完的** —— 下一个 web 平台特性
+ * 又会开一条。所以闸挪到**所有出网都必经的那一层**：给这个浏览器挂一个我们自己的
+ * HTTP 代理，`--proxy-server` 之后 chromium 的每一次连接都从这儿走。
+ * 实测代理确实看得到上面四条全部（包括 WS 的 `CONNECT 127.0.0.1:4001`）。
+ *
+ * ## 附带白拿的两件
+ *
+ * 1. ⭐ **DNS 重绑定被根除，不再是"缓解"。** 我们自己解析、自己**连那个验过的 IP**
+ *    （pin），浏览器拿不到第二次解析的机会。CDP 那版只能是"解析一次→浏览器再解析
+ *    一次"，中间有 TOCTOU 窗口，而且主机名缓存把窗口变成了保证 30 秒的洞。
+ * 2. **没有初始化竞态。** 代理在浏览器启动参数里，第一个字节之前就生效；
+ *    CDP 那版要等 `Fetch.enable` 握手完，弹窗根本等不到。
+ *
+ * CDP 那道闸**保留**当纵深（它能给出漂亮的按请求记账），但不再是唯一一道。
+ *
+ * ## 感知通道不挂代理
+ *
+ * 感知通道（看自己产物）**故意**走 loopback 的 artifact-file，它必须能到 127.0.0.1。
+ * 所以只有浏览通道的浏览器带 `--proxy-server`，两条通道在这一层物理分开。
+ */
+
+import http from 'node:http';
+import net from 'node:net';
+import dns from 'node:dns/promises';
+import { blockReason } from './ssrf-guard.js';
+
+/** 允许连的端口。80/443 之外的公网端口极少是设计参考站，而放开等于多一片攻击面。 */
+const ALLOWED_PORTS = new Set([80, 443, 8080, 8443]);
+const RESOLVE_TIMEOUT_MS = 4000;
+const CONNECT_TIMEOUT_MS = 15_000;
+
+let server = null;
+let port = 0;
+const blocked = [];
+
+function note(target, reason) {
+  blocked.push({ target, reason, at: Date.now() });
+  if (blocked.length > 200) blocked.shift();
+}
+
+/**
+ * 解析 + 判定，返回可以连的那个 IP（**pin 住它**，不把主机名交给下游再解析一次）。
+ * @returns {Promise<{ip: string, family: number} | {deny: string}>}
+ */
+async function resolveAllowed(host, portNum) {
+  if (!ALLOWED_PORTS.has(portNum)) {
+    return { deny: `port ${portNum} is not allowed (only ${[...ALLOWED_PORTS].join('/')})` };
+  }
+  const bare = host.toLowerCase().replace(/^\[|\]$/g, '');
+  if (bare === 'localhost' || bare.endsWith('.localhost') || bare.endsWith('.local')) {
+    return { deny: `${bare} resolves inside the local network` };
+  }
+  // 字面量 IP 不劳烦 DNS
+  if (/^\d+\.\d+\.\d+\.\d+$/.test(bare) || bare.includes(':')) {
+    const why = blockReason(bare);
+    return why ? { deny: why } : { ip: bare, family: bare.includes(':') ? 6 : 4 };
+  }
+  let addrs;
+  try {
+    addrs = await Promise.race([
+      dns.lookup(bare, { all: true, verbatim: true }),
+      new Promise((_, rej) => setTimeout(() => rej(new Error('dns timeout')), RESOLVE_TIMEOUT_MS)),
+    ]);
+  } catch (err) {
+    // ⚠️ kind:'dns' 是给 denyBody 分文案用的：解析失败**不是策略拦截**。
+    // 第一版对 NXDOMAIN 也甩「内网与本机地址是硬边界」，agent 上报时据此
+    // 推理出一整套"代理有两个解析器"的错误理论 —— 错误提示比没提示更贵。
+    return { deny: `cannot resolve ${bare}: ${err.message}`, kind: 'dns' };
+  }
+  if (!addrs.length) return { deny: `${bare} resolved to nothing`, kind: 'dns' };
+  // **任一**地址落在禁止段就整个拒 —— 多 A 记录里混一条内网是标准起手式，
+  // "挑一个能用的"等于自己开门
+  for (const a of addrs) {
+    const why = blockReason(a.address);
+    if (why) return { deny: `${bare} → ${why}` };
+  }
+  return { ip: addrs[0].address, family: addrs[0].family };
+}
+
+// 按拒因分文案：DNS 解析失败要说清"这个域名现在指不到任何地方"，
+// 策略拦截才配那句硬边界 —— 两种拒混着说，agent 会朝错误的方向排障。
+const denyTail = (kind) => (kind === 'dns'
+  ? '这是域名解析失败（域名可能不存在、拼错或已下线），不是出网策略拦截。'
+  : '内网与本机地址是硬边界，不是可配置项。');
+
+const denyBody = (reason, kind) => {
+  const body = `拒绝出网：${reason}\n\n${denyTail(kind)}`;
+  return `HTTP/1.1 403 Forbidden\r\nContent-Type: text/plain; charset=utf-8\r\n`
+    + `Content-Length: ${Buffer.byteLength(body)}\r\nConnection: close\r\n\r\n${body}`;
+};
+
+/** 启动（幂等）。@returns {Promise<{port:number, blocked:Array}>} */
+export async function startBrowseProxy() {
+  if (server) return { port, blocked };
+
+  server = http.createServer();
+
+  // 明文 http：绝对形式的请求行（`GET http://host/path`）
+  server.on('request', async (req, res) => {
+    let u;
+    try { u = new URL(req.url); } catch {
+      res.writeHead(400); return res.end('proxy: bad absolute-form request');
+    }
+    const p = Number(u.port || (u.protocol === 'https:' ? 443 : 80));
+    const verdict = await resolveAllowed(u.hostname, p);
+    if (verdict.deny) {
+      note(`${u.hostname}:${p}`, verdict.deny);
+      res.writeHead(403, { 'Content-Type': 'text/plain; charset=utf-8' });
+      return res.end(`拒绝出网：${verdict.deny}\n\n${denyTail(verdict.kind)}`);
+    }
+    // 连**验过的那个 IP**，Host 头保留原主机名（虚拟主机才认得出）
+    const upstream = http.request({
+      host: verdict.ip, port: p, method: req.method,
+      path: u.pathname + u.search,
+      headers: { ...req.headers, host: u.host },
+      timeout: CONNECT_TIMEOUT_MS,
+      setHost: false,
+    }, (up) => {
+      res.writeHead(up.statusCode || 502, up.headers);
+      up.pipe(res);
+    });
+    upstream.on('error', (err) => {
+      if (!res.headersSent) res.writeHead(502, { 'Content-Type': 'text/plain' });
+      res.end(`proxy upstream error: ${err.message}`);
+    });
+    req.pipe(upstream);
+  });
+
+  // CONNECT：https / wss 都走这条（**WS 就是靠它被盖住的**）
+  server.on('connect', async (req, socket, head) => {
+    const [rawHost, rawPort] = String(req.url || '').split(':');
+    const p = Number(rawPort || 443);
+    const verdict = await resolveAllowed(rawHost || '', p);
+    if (verdict.deny) {
+      note(`${rawHost}:${p}`, verdict.deny);
+      socket.write(denyBody(verdict.deny, verdict.kind));
+      return socket.destroy();
+    }
+    const up = net.connect({ host: verdict.ip, port: p }, () => {
+      socket.write('HTTP/1.1 200 Connection Established\r\nProxy-Agent: nodesign-browse\r\n\r\n');
+      if (head?.length) up.write(head);
+      socket.pipe(up); up.pipe(socket);
+    });
+    up.setTimeout(CONNECT_TIMEOUT_MS, () => up.destroy());
+    up.on('error', () => { try { socket.destroy(); } catch { /* */ } });
+    socket.on('error', () => { try { up.destroy(); } catch { /* */ } });
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  port = server.address().port;
+  server.unref?.();
+  console.log(`[browse-proxy] listening on 127.0.0.1:${port}`);
+  return { port, blocked };
+}
+
+/** 给工具的返回值用：这次调用期间拦了什么 */
+export function blockedSince(n) {
+  return blocked.slice(n);
+}
+export function blockedCount() {
+  return blocked.length;
+}
+export const _proxy = { ALLOWED_PORTS };