@xiaobuyu/nodesign 0.0.1 → 0.0.3

package/server/lib/async-queue.js

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

@@ -1,130 +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：对账绝不拖累清单接口 */ });
-}
+/**
+ * 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

@@ -1,60 +1,72 @@
-/**
- * 关系线的语义词汇表 —— 画布上一条线「是什么意思」的**唯一真相**。
- *
- * ## 为什么关系要单独存一张表
- *
- * 北极星是「任务文件夹能排出登录墙那种版面」。手摆之所以好看，是因为每张纸的
- * 位置在回答「它和旁边那张什么关系」。而系统此前只知道每个产物的**尺寸和
- * 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);
-}
+/**
+ * 关系线的语义词汇表 —— 画布上一条线「是什么意思」的**唯一真相**。
+ *
+ * ## 为什么关系要单独存一张表
+ *
+ * 北极星是「任务文件夹能排出登录墙那种版面」。手摆之所以好看，是因为每张纸的
+ * 位置在回答「它和旁边那张什么关系」。而系统此前只知道每个产物的**尺寸和
+ * 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);
+
+/**
+ * 材质（2026-08-23 黑板）：与语义正交的第二个轴。
+ *   ink     墨线 —— 版面线的默认材质，安静
+ *   pencil  手绘 —— 铅笔抖动，像人顺手拉的一笔
+ *   yarn    丝线 —— 侦探板上的红线 + 图钉，推理态、声量大
+ * 前端 board-bindings.js 的 BINDING_MATERIALS 必须与这份 id 一一对应（parity 测试）。
+ */
+export const BINDING_MATERIALS = ['ink', 'pencil', 'yarn'];
+export function isBindingMaterial(m) {
+  return BINDING_MATERIALS.includes(m);
+}
+
+export function isBindingType(t) {
+  return Object.prototype.hasOwnProperty.call(BINDING_TYPES, t);
+}