@xiaobuyu/nodesign 0.0.1

package/server/lib/async-queue.js

@@ -0,0 +1,104 @@
+/**
+ * server/lib/async-queue.js — push/pull 解耦的异步队列
+ *
+ * 用途：SDK Query streamInput 模式下，runAgent 需要一个 AsyncIterable<SDKUserMessage>
+ * 持续 yield user message 让 query 一直活着；前端 POST /turn 把 message push 进
+ * 队列，generator 那头 pull 后 yield 给 SDK。
+ *
+ * 行为：
+ *   - push(item) 立即返回；waiter 等着就唤醒一个，否则进 items 数组
+ *   - next() 返回 Promise；items 有就立刻 resolve，否则 Promise 挂着等 push / close
+ *   - close() 终结流；所有 pending waiter 收到 { done: true }；后续 push 抛错
+ *   - return() 自动调 close（让 for-await-of 的 break 能正确收尾）
+ *
+ * 不是通用线程安全 queue —— 单事件循环内用，order 保证 FIFO。
+ *
+ * @template T
+ */
+export class AsyncQueue {
+  constructor() {
+    /** @type {T[]} */
+    this.items = [];
+    /** @type {Array<(r: IteratorResult<T>) => void>} */
+    this.waiters = [];
+    this.closed = false;
+  }
+
+  /**
+   * 当前积压 item 数量（已 push 未 pull 的）。
+   * 给 UI "已排队 N 条" 显示用。
+   */
+  get size() {
+    return this.items.length;
+  }
+
+  /**
+   * 是否还有 active waiter 在等（agent 已 pull 完积压，正等下一条）。
+   * 给"agent idle"判定用。
+   */
+  get isPending() {
+    return this.waiters.length > 0;
+  }
+
+  /**
+   * 推一个 item 进队列。
+   * @param {T} item
+   * @throws {Error} 已 close 时抛
+   */
+  push(item) {
+    if (this.closed) {
+      throw new Error('AsyncQueue: push after close');
+    }
+    if (this.waiters.length > 0) {
+      const w = this.waiters.shift();
+      w({ value: item, done: false });
+      return;
+    }
+    this.items.push(item);
+  }
+
+  /**
+   * 终结流。pending waiter 全部收到 done，items 里残留的 item 仍可 pull
+   * 直到清空，再之后 next() 返回 done。
+   *
+   * 幂等：多次调用 noop。
+   */
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    while (this.waiters.length > 0) {
+      const w = this.waiters.shift();
+      w({ value: undefined, done: true });
+    }
+  }
+
+  // ── AsyncIterator protocol ──
+
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+
+  /**
+   * @returns {Promise<IteratorResult<T>>}
+   */
+  next() {
+    if (this.items.length > 0) {
+      return Promise.resolve({ value: this.items.shift(), done: false });
+    }
+    if (this.closed) {
+      return Promise.resolve({ value: undefined, done: true });
+    }
+    return new Promise((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+
+  /**
+   * for-await-of 提前 break / throw 时被 runtime 调；触发 close。
+   * @returns {Promise<IteratorResult<T>>}
+   */
+  return() {
+    this.close();
+    return Promise.resolve({ value: undefined, done: true });
+  }
+}

package/server/lib/auto-relations.js

@@ -0,0 +1,130 @@
+/**
+ * server/lib/auto-relations.js — 自动落线层（2026-08-14，北极星路线 4）
+ *
+ * 有一类关系**不需要人或 agent 判断，机器可证**：html 里 `<img src>` 真实
+ * 指向工作区里的一张图，就是铁打的「取材」。这层把它们落成 `by:'auto'` 的
+ * ref 边 —— 关系密度从「靠自觉」变成「有底仓」，用户和 agent 的手画线在
+ * 底仓之上做增量。
+ *
+ * 三条纪律：
+ *   1. **只动自家的边**。自动边 id 恒为 `b:auto:ref:<hash>`（确定性 → 幂等），
+ *      对账时新增缺的、删掉失效的，**其余 id 一根手指都不碰** —— 用户/agent
+ *      画的线不归这层管。
+ *   2. **引用得真实存在**才落线。悬空 src 是裂图体检的事，不是关系。
+ *   3. **不画**。BindingLayer 对 auto+ref 不渲染 —— 一个站引三十张图，画出来
+ *      是蜘蛛网不是版面。它们的消费方是 agent 上下文（digest 收拢成一行）和
+ *      将来的主角判断（被 ref 指着的 = 素材，不该当 hero）。
+ *
+ * 触发：挂在 GET /artifacts 尾巴上 fire-and-forget（那里 manifests 现成），
+ * 每项目 30s 节流。产物身份的拼法与 BoardCanvas 的物件 id 同构 ——
+ * `deck:<file>` / `site:<root||''>` / 单页 `site:<entryRel>`。
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { readBoard, patchBoard } from '../projects/board-store.js';
+
+const MAX_HTML_BYTES = 512 * 1024;
+const AUTO_REF_PREFIX = 'b:auto:ref:';
+/** 每个项目对账节流（ms）—— /artifacts 是热接口，别把它变成扫盘器 */
+const THROTTLE_MS = 30_000;
+const lastRun = new Map();
+
+const hashId = (from, to) =>
+  AUTO_REF_PREFIX + crypto.createHash('sha1').update(`${from}|${to}`).digest('hex').slice(0, 12);
+
+/**
+ * 从一段 html 里抠出本地资源引用（src/href/poster + 内联 url()）。
+ * 返回**相对 html 所在目录**的原始引用串（未归一）。
+ */
+export function extractRefs(html) {
+  const out = new Set();
+  const push = (raw) => {
+    if (!raw) return;
+    const v = raw.trim().replace(/^['"]|['"]$/g, '').split(/[?#]/)[0];
+    if (!v || /^(https?:|data:|blob:|mailto:|javascript:|\/\/)/i.test(v)) return;
+    out.add(v);
+  };
+  for (const m of html.matchAll(/<(?:img|video|audio|source|embed)\b[^>]*?\s(?:src|poster)\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi)) push(m[1]);
+  for (const m of html.matchAll(/url\(\s*([^)]+?)\s*\)/gi)) push(m[1]);
+  return [...out];
+}
+
+/** 引用串 → 工作区相对路径（越界/绝对路径丢弃）。baseDir 是 html 所在目录（工作区相对）。 */
+export function resolveRef(raw, baseDir) {
+  try {
+    const decoded = decodeURIComponent(raw);
+    if (decoded.startsWith('/')) return null;               // 站内绝对路径按约定不出现，出现也不猜
+    const joined = path.posix.normalize(path.posix.join(baseDir || '.', decoded));
+    if (joined.startsWith('..') || path.posix.isAbsolute(joined)) return null;
+    return joined === '.' ? null : joined;
+  } catch { return null; }
+}
+
+/**
+ * 对账一个项目的自动 ref 边。
+ *
+ * @param {string} pid
+ * @param {string} workspaceRoot  绝对路径
+ * @param {Array} tasks           /artifacts 已算好的 tasks（id/artifacts 同构前端）
+ */
+export async function reconcileAutoRefs(pid, workspaceRoot, tasks) {
+  // 期望集：{ bid: { from, to } }
+  const desired = new Map();
+  for (const t of tasks || []) {
+    for (const a of t.artifacts || []) {
+      // 产物身份（与 BoardCanvas 的物件 id 同一拼法）
+      // ⚠️ 卡 id 按**形态**派生，别用「不是 deck 就是 site」的二分（2026-08-18 修）。
+      // docx 上线之后那个三元把 .docx 产物算成了 `site:` 前缀 —— id 对不上，
+      // 它的自动关系边落在一个不存在的端点上。规则跟前端 cardIdOf
+      // （web/src/lib/board-kinds.js）必须一致，两边岔开就是"同一件东西两份实现"。
+      const fromId = a.kind === 'site'
+        ? `site:${a.single ? a.entryRel : (a.root || t.id)}`
+        : `${a.kind || 'deck'}:${a.file}`;
+      // 这件产物的 html 们（deck 一份；站点 = 各页，路径相对站根）
+      const pages = a.kind === 'deck'
+        ? [a.file]
+        : (a.single ? [a.entryRel] : (a.pages || []).map(p => (a.root ? `${a.root}/${p}` : p)));
+      for (const rel of pages) {
+        if (!rel || !/\.html?$/i.test(rel)) continue;
+        let html;
+        try {
+          const abs = path.join(workspaceRoot, rel);
+          const st = await fs.stat(abs);
+          if (st.size > MAX_HTML_BYTES) continue;
+          html = await fs.readFile(abs, 'utf8');
+        } catch { continue; }
+        const baseDir = path.posix.dirname(rel.replace(/\\/g, '/'));
+        for (const raw of extractRefs(html)) {
+          const to = resolveRef(raw, baseDir === '.' ? '' : baseDir);
+          if (!to || to === rel) continue;
+          try { await fs.access(path.join(workspaceRoot, to)); } catch { continue; }   // 悬空不落线
+          desired.set(hashId(fromId, to), { from: fromId, to });
+        }
+      }
+    }
+  }
+
+  // 现状 → diff。只碰 b:auto:ref:* 的条目。
+  const board = await readBoard(pid);
+  const patch = {};
+  for (const [bid, b] of Object.entries(board.bindings || {})) {
+    if (bid.startsWith(AUTO_REF_PREFIX) && !desired.has(bid)) patch[bid] = null;
+  }
+  for (const [bid, { from, to }] of desired) {
+    const cur = board.bindings?.[bid];
+    if (cur && cur.from === from && cur.to === to) continue;
+    patch[bid] = { type: 'ref', from, to, by: 'auto' };
+  }
+  if (Object.keys(patch).length) await patchBoard(pid, { bindings: patch });
+  return { desired: desired.size, changed: Object.keys(patch).length };
+}
+
+/** 节流版：/artifacts 尾巴上 fire-and-forget 用 */
+export function reconcileAutoRefsThrottled(pid, workspaceRoot, tasks) {
+  const now = Date.now();
+  if (now - (lastRun.get(pid) || 0) < THROTTLE_MS) return;
+  lastRun.set(pid, now);
+  reconcileAutoRefs(pid, workspaceRoot, tasks).catch(() => { /* fail-soft：对账绝不拖累清单接口 */ });
+}

package/server/lib/binding-types.js

@@ -0,0 +1,60 @@
+/**
+ * 关系线的语义词汇表 —— 画布上一条线「是什么意思」的**唯一真相**。
+ *
+ * ## 为什么关系要单独存一张表
+ *
+ * 北极星是「任务文件夹能排出登录墙那种版面」。手摆之所以好看，是因为每张纸的
+ * 位置在回答「它和旁边那张什么关系」。而系统此前只知道每个产物的**尺寸和
+ * mtime** —— 关系数据不到位，再好的布局算法也只能排出「错落有致的网格」。
+ *
+ * 所以关系是 board.json 里的一等公民，跟 objects / zones 平级：
+ *
+ *   bindings: { "<id>": { type, from, to, label?, by? } }
+ *
+ * 端点 `from` / `to` 是 **object id 或 zone id**（用户明确要求文件夹之间也能连线）。
+ * 线本身不存坐标 —— 端点一移动，线自己跟着走。这是 tldraw `TLBinding` 的思路：
+ * 关系是独立记录，不是形状的属性，箭头形状本身不存端点坐标。**抄的是思路，
+ * 不是代码**（tldraw 是专有许可证）。
+ *
+ * ## 为什么是这五种
+ *
+ * 挑的标准是「这条关系能不能改变布局决定」。能影响摆放的才收，纯装饰的不收。
+ * 每一种都对应创作过程里一件真实发生的事：
+ *
+ * - **改自**：一个产物是另一个的下一版。这是版本谱系，最该被看见的一条 ——
+ *   用户翻旧版找的就是它。
+ * - **批注**：一段文字在说某个东西。annotation 形态存在的理由。
+ * - **顺序**：分镜、章节、流程的先后。它决定读序，也就决定排布方向。
+ * - **取材**：这张图用在那个 deck 里 / 这份资料喂给了那篇稿。跨任务的引用。
+ * - **对照**：并列比较（proto-暖调 vs proto-冷调）。无向，且**明确要求并排**，
+ *   是唯一一条直接给布局下指令的关系。
+ *
+ * ## 明确不做成线的：「成组」
+ *
+ * 「这几件属于同一批」的正确画法是**圈一个框**，不是两两连线 —— n 个成员
+ * 两两连线是 n(n-1)/2 条，五件就是十条，画面直接糊掉。成组用已有的 zone
+ * （工作区 / 文件夹）表达，agent 建文件夹收纳就是在表达成组。
+ */
+
+/**
+ * 词汇表。`directed` 决定渲染时画不画箭头，也决定 from/to 能不能互换。
+ * `label` 是没写自定义文字时线上显示的默认词。
+ */
+export const BINDING_TYPES = {
+  'derives-from': { label: '改自', directed: true },
+  annotates: { label: '批注', directed: true },
+  flow: { label: '接着', directed: true },
+  ref: { label: '取材', directed: true },
+  contrast: { label: '对照', directed: false },
+  // 关联（2026-08-14，手动连线上线时加）：五种预定义都不合身时的逃生舱。
+  // 含义由线上的 label 定义（用户写一句，agent 逐字读）。收它不违反
+  // 「纯装饰不收」——它对布局说「摆近点」（affinity），对 agent 说 label 那句话。
+  link: { label: '关联', directed: false },
+};
+
+/** 词汇表 id 列表，校验和 parity 断言都用它。 */
+export const BINDING_TYPE_IDS = Object.keys(BINDING_TYPES);
+
+export function isBindingType(t) {
+  return Object.prototype.hasOwnProperty.call(BINDING_TYPES, t);
+}

package/server/lib/board-kind-sizes.js

@@ -0,0 +1,62 @@
+/**
+ * board-kind-sizes —— 画布物件身位的服务端镜像（2026-08-14，agent 摆位批）
+ *
+ * read_board / arrange_on_board / create_on_board 要在服务端估算卡片矩形
+ * （挨着谁摆、会不会压到谁），而身位真相住在前端 `web/src/lib/board-kinds.js`
+ * （渲染方）。这里抄一份**常量**，web 侧有 parity 测试钉着两边一致 ——
+ * 改那边忘了改这边，测试直接红（跟 binding-types 的双份表同一套纪律）。
+ *
+ * 文字/涂鸦不在表里：它们的 w/h 是逐条存在 board.json 里的（本体即数据）。
+ */
+
+import { KINDS } from './kinds/index.js';
+
+export const DECK_EMBED_W = 640;
+export const ARTIFACT_HEADER_H = 28;
+export const ARTIFACT_PREVIEW_H = { deck: 360, site: 400, docx: 420, browse: 360 };
+
+// file 是 224x32 的细条卡（parity 测试上岗第一天就逮住我猜成 160x120 ——
+// 那是涂鸦的默认身位。别猜，抄表）
+export const KIND_SIZES = {
+  doc: { w: 200, h: 96 },
+  image: { w: 200, h: 176 },
+  video: { w: 240, h: 160 },
+  note: { w: 200, h: 148 },
+  file: { w: 224, h: 32 },
+};
+
+// 前缀表从注册表派生（「写死表家族」第 4 处，2026-08-18 收）：手写
+// `deck|site|docx` 的话加形态必漏，新形态的卡掉到 file 兜底（224×32 细条），
+// agent 摆位按错矩形算。⚠️ 新形态要同步给 ARTIFACT_PREVIEW_H 加一行
+//（两边都有 parity 测试钉着前端那份）。
+const KIND_PREFIX_RE = new RegExp(`^(${Object.keys(KINDS).join('|')}):`);
+
+const IMG_EXT = /\.(png|jpe?g|webp|gif|svg|avif)$/i;
+const VIDEO_EXT = /\.(mp4|webm|mov)$/i;
+
+/**
+ * 按 id + board.json 条目估身位。优先条目里存的 w/h（文字/涂鸦，或将来任何
+ * 显式尺寸），其次按 id 形态推：kind 前缀 → 产物卡，扩展名 → 图/视频/便签/文件。
+ */
+export function estimateSize(id, entry) {
+  if (entry && Number.isFinite(entry.w) && Number.isFinite(entry.h)) {
+    return { w: entry.w, h: entry.h };
+  }
+  const s = String(id || '');
+  if (s.startsWith('doc:')) return KIND_SIZES.doc;
+  // 浏览器卡是**单例**，id 就是 'browse'（没有路径可挂 —— 它背后不是文件）。
+  // 不给这条分支的话它会掉到最后的 file 兜底（224×32 的细条），agent 摆位时
+  // 就会拿一个错的矩形去算"挨着谁摆、会不会压到谁"。
+  if (s === 'browse') {
+    return { w: DECK_EMBED_W, h: ARTIFACT_HEADER_H + ARTIFACT_PREVIEW_H.browse };
+  }
+  const m = KIND_PREFIX_RE.exec(s);
+  if (m) {
+    const t = m[1];
+    return { w: DECK_EMBED_W, h: ARTIFACT_HEADER_H + ARTIFACT_PREVIEW_H[t] };
+  }
+  if (IMG_EXT.test(s)) return KIND_SIZES.image;
+  if (VIDEO_EXT.test(s)) return KIND_SIZES.video;
+  if (/\.(md|txt)$/i.test(s)) return KIND_SIZES.note;
+  return KIND_SIZES.file;
+}

package/server/lib/board-relations.js

@@ -0,0 +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');
+}

package/server/lib/browse-proxy.js

@@ -0,0 +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 };