@xiaobuyu/nodesign 0.0.2 → 0.0.4

package/server/lib/board-groups.js

@@ -0,0 +1,167 @@
+/**
+ * server/lib/board-groups.js —— 画布的「组」与「小地图」（2026-08-23 黑板）
+ *
+ * 黑板不设几何容器（用户拍板：frame 给黑板开小灶，终局产物卡也要走同一套）。
+ * 「组」是派生的：**被线连在一起的一群东西算一组**（连通分量），再加上显式
+ * `tag` 字段把没连线的也归到一起。read_board 按组分段输出、用户按组整选、渲染
+ * 按组画包络，三处读同一个判据 —— 入座算法里「关系组独占成行」用的也是连通
+ * 分量，没有第二份真相。
+ *
+ * 小地图：把一层的物件投到一张 ≤ 48×16 的字符网格上。模型读网格的整体感远比
+ * 读三十行坐标强；从 board.json 直接算，零成本。
+ */
+
+/**
+ * 连通分量 + tag 合并。
+ * @param {string[]} ids           这一层的物件 id
+ * @param {object}  bindings       board.bindings
+ * @param {(id:string)=>string|null} tagOf
+ * @returns {Array<{ members: string[], tags: Set<string>, edges: string[] }>}  大组在前
+ */
+export function groupObjects(ids, bindings, tagOf = () => null) {
+  const parent = new Map(ids.map(id => [id, id]));
+  const find = (x) => {
+    while (parent.get(x) !== x) { parent.set(x, parent.get(parent.get(x))); x = parent.get(x); }
+    return x;
+  };
+  const union = (a, b) => {
+    if (!parent.has(a) || !parent.has(b)) return;
+    const ra = find(a); const rb = find(b);
+    if (ra !== rb) parent.set(ra, rb);
+  };
+  const edgesIn = [];
+  const cross = [];
+  for (const [bid, b] of Object.entries(bindings || {})) {
+    if (b.by === 'auto' && b.type === 'ref') continue;   // 自动取材边不成组（蜘蛛网）
+    if (!parent.has(b.from) || !parent.has(b.to)) continue;
+    // tag 优先：两端 tag 不同（或一端有一端没有）的线是"组间线"，不把两张图粘成一组
+    // （08-23 真踩：两张草图之间一条 ref 线让 read_board 把它们报成一组 6 列）
+    const ta = tagOf(b.from); const tb = tagOf(b.to);
+    if (ta !== tb) { cross.push([bid, b]); continue; }
+    union(b.from, b.to); edgesIn.push([bid, b]);
+  }
+  // 同 tag 归一组
+  const byTag = new Map();
+  for (const id of ids) {
+    const t = tagOf(id);
+    if (!t) continue;
+    if (!byTag.has(t)) byTag.set(t, id); else union(byTag.get(t), id);
+  }
+  const groups = new Map();
+  for (const id of ids) {
+    const r = find(id);
+    if (!groups.has(r)) groups.set(r, { members: [], tags: new Set(), edges: [] });
+    const g = groups.get(r);
+    g.members.push(id);
+    const t = tagOf(id); if (t) g.tags.add(t);
+  }
+  for (const [bid, b] of edgesIn) {
+    const g = groups.get(find(b.from));
+    if (g) g.edges.push(bid);
+  }
+  const out = [...groups.values()].sort((a, b) => b.members.length - a.members.length);
+  out.cross = cross.map(([bid]) => bid);   // 组间线 id（调用方愿意列就列）
+  return out;
+}
+
+const GLYPHS = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+
+/**
+ * ASCII 小地图。
+ * @param {Array<{id:string,x:number,y:number,w:number,h:number}>} rects
+ * @param {{ cols?: number, rows?: number, viewport?: {x,y,w,h}|null }} opts
+ * @returns {{ grid: string, legend: Array<[string,string]>, bbox: {x,y,w,h} }|null}
+ */
+export function asciiMinimap(rects, { cols = 48, rows = 16, viewport = null } = {}) {
+  if (!rects.length) return null;
+  let x0 = Infinity; let y0 = Infinity; let x1 = -Infinity; let y1 = -Infinity;
+  for (const r of rects) {
+    x0 = Math.min(x0, r.x); y0 = Math.min(y0, r.y);
+    x1 = Math.max(x1, r.x + r.w); y1 = Math.max(y1, r.y + r.h);
+  }
+  if (viewport) {
+    x0 = Math.min(x0, viewport.x); y0 = Math.min(y0, viewport.y);
+    x1 = Math.max(x1, viewport.x + viewport.w); y1 = Math.max(y1, viewport.y + viewport.h);
+  }
+  const W = Math.max(1, x1 - x0); const H = Math.max(1, y1 - y0);
+  // 等比：一个字符格近似正方（字符高宽比约 2:1，所以横向给两倍格数）
+  const scale = Math.max(W / cols, H / (rows * 2));
+  const gw = Math.max(1, Math.ceil(W / scale));
+  const gh = Math.max(1, Math.ceil(H / (scale * 2)));
+  const grid = Array.from({ length: gh }, () => Array(gw).fill('·'));
+  const legend = [];
+  if (viewport) {
+    // 视口边框用 +─│ 画在底下，物件盖在上面
+    const cx0 = Math.floor((viewport.x - x0) / scale); const cx1 = Math.min(gw - 1, Math.floor((viewport.x + viewport.w - x0) / scale));
+    const cy0 = Math.floor((viewport.y - y0) / (scale * 2)); const cy1 = Math.min(gh - 1, Math.floor((viewport.y + viewport.h - y0) / (scale * 2)));
+    for (let x = cx0; x <= cx1; x += 1) { if (grid[cy0]) grid[cy0][x] = '─'; if (grid[cy1]) grid[cy1][x] = '─'; }
+    for (let y = cy0; y <= cy1; y += 1) { if (grid[y]) { grid[y][cx0] = '│'; grid[y][cx1] = '│'; } }
+    if (grid[cy0]) { grid[cy0][cx0] = '┌'; grid[cy0][cx1] = '┐'; }
+    if (grid[cy1]) { grid[cy1][cx0] = '└'; grid[cy1][cx1] = '┘'; }
+  }
+  rects.forEach((r, i) => {
+    const g = i < GLYPHS.length ? GLYPHS[i] : '#';
+    legend.push([g, r.id]);
+    const cx0 = Math.floor((r.x - x0) / scale); const cx1 = Math.min(gw - 1, Math.max(cx0, Math.ceil((r.x + r.w - x0) / scale) - 1));
+    const cy0 = Math.floor((r.y - y0) / (scale * 2)); const cy1 = Math.min(gh - 1, Math.max(cy0, Math.ceil((r.y + r.h - y0) / (scale * 2)) - 1));
+    for (let y = cy0; y <= cy1; y += 1) for (let x = cx0; x <= cx1; x += 1) if (grid[y]) grid[y][x] = g;
+  });
+  return {
+    grid: grid.map(row => row.join('')).join('\n'),
+    legend,
+    bbox: { x: Math.round(x0), y: Math.round(y0), w: Math.round(W), h: Math.round(H) },
+    cell: Math.round(scale),
+  };
+}
+
+/* ────────────────────────────────────────────────────────────────────────
+ * 相对位置（2026-08-23 晚，用户问「我们有没有告诉 agent 各模块的相对位置」——没有，
+ * 之前只给绝对坐标和一张小地图；模型对"组 2 在组 1 左侧、同高"这种话的理解远好于
+ * 读坐标）。下面把组的包围盒之间、组与用户视口之间的关系说成人话；组内再认一下
+ * 列（x 聚类）给出阅读顺序提示。
+ * ──────────────────────────────────────────────────────────────────────── */
+
+export function bboxOfRects(rects) {
+  let x0 = Infinity; let y0 = Infinity; let x1 = -Infinity; let y1 = -Infinity;
+  for (const r of rects) { x0 = Math.min(x0, r.x); y0 = Math.min(y0, r.y); x1 = Math.max(x1, r.x + r.w); y1 = Math.max(y1, r.y + r.h); }
+  return Number.isFinite(x0) ? { x: x0, y: y0, w: x1 - x0, h: y1 - y0 } : null;
+}
+
+/** b 相对 a 在哪（以 a 为参照）：左/右/上/下 + 距离；重叠则说重叠 */
+export function relationOf(a, b) {
+  if (!a || !b) return null;
+  const gapX = b.x >= a.x + a.w ? b.x - (a.x + a.w) : (b.x + b.w <= a.x ? a.x - (b.x + b.w) : -1);
+  const gapY = b.y >= a.y + a.h ? b.y - (a.y + a.h) : (b.y + b.h <= a.y ? a.y - (b.y + b.h) : -1);
+  if (gapX < 0 && gapY < 0) return '重叠';
+  const horiz = gapX >= 0 && (gapY < 0 || gapX >= gapY);
+  if (horiz) {
+    const side = b.x >= a.x + a.w ? '右侧' : '左侧';
+    const vAlign = Math.abs(b.y - a.y) < 60 ? '顶齐' : (b.y > a.y ? '偏下' : '偏上');
+    return `${side} ${Math.round(gapX)}px（${vAlign}）`;
+  }
+  const side = b.y >= a.y + a.h ? '下方' : '上方';
+  const hAlign = Math.abs(b.x - a.x) < 60 ? '左齐' : (b.x > a.x ? '偏右' : '偏左');
+  return `${side} ${Math.round(gapY)}px（${hAlign}）`;
+}
+
+/** 组内的列：按左边缘聚类（容差 60px），返回每列的成员数（自左向右） */
+export function columnsOf(rects) {
+  const xs = [...rects].sort((a, b) => a.x - b.x);
+  const cols = [];
+  for (const r of xs) {
+    const c = cols.find(k => Math.abs(k.x - r.x) < 60);
+    if (c) { c.n += 1; c.x = (c.x * (c.n - 1) + r.x) / c.n; } else cols.push({ x: r.x, n: 1 });
+  }
+  return cols;
+}
+
+/** 视口与一块区域的关系 */
+export function viewportRelation(vp, box) {
+  if (!vp || !box) return null;
+  const ix = Math.max(0, Math.min(vp.x + vp.w, box.x + box.w) - Math.max(vp.x, box.x));
+  const iy = Math.max(0, Math.min(vp.y + vp.h, box.y + box.h) - Math.max(vp.y, box.y));
+  const cover = (ix * iy) / Math.max(1, box.w * box.h);
+  if (cover >= 0.95) return '整块在用户视口里';
+  if (cover > 0) return `用户视口盖住它约 ${Math.round(cover * 100)}%`;
+  return `在用户视口之外（视口${relationOf(box, vp) || '别处'}）`;
+}

package/server/lib/board-hero.js

@@ -0,0 +1,76 @@
+/**
+ * server/lib/board-hero.js —— 主角判断的服务端镜像（2026-08-23 黑板）
+ *
+ * 前端 `web/src/lib/hero.js` 的 pickHero 决定哪张产物卡放大 1.5 倍。服务端摆东西
+ * （sketch_on_board / create_on_board 的避让、read_board 的尺寸、look_at_board 的
+ * 取景）在这之前只认基础尺寸，于是"锚在主角卡右边"会落进主角卡的身体里
+ * （08-23 首跑真踩：纸本站是主角 960 宽，草图从 640 处起算，整张压进去）。
+ *
+ * **镜像不是重写**：下面 pickHero 的函数体必须与 web/src/lib/hero.js 逐字相同，
+ * board-hero.test.js 读两份源码比对。npm 包不带 web/src，所以不能 import 过来。
+ */
+import { DECK_EMBED_W, ARTIFACT_HEADER_H, ARTIFACT_PREVIEW_H } from './board-kind-sizes.js';
+import { layerOf } from './canvas-id.js';
+
+// ── 以下到 END-MIRROR 与 web/src/lib/hero.js 逐字一致 ──
+const ELIGIBLE = new Set(['deck', 'site', 'docx']);
+const FOCUS_PER_EDGE = 0.5;
+const FOCUS_CAP = 1.5;
+export function pickHero(items, bindings) {
+  const score = new Map();
+  for (const it of items || []) {
+    if (ELIGIBLE.has(it.type)) score.set(String(it.id), 3);
+  }
+  if (!score.size) return null;
+  const bump = (id, d) => { if (score.has(id)) score.set(id, score.get(id) + d); };
+  const focus = new Map();
+  for (const b of Object.values(bindings || {})) {
+    if (b.type === 'derives-from') { bump(b.from, 2); bump(b.to, -3); }
+    if (b.type === 'ref' && b.by === 'auto') bump(b.to, -3);
+    if (b.by === 'user' || b.by === 'agent') {
+      for (const end of [b.from, b.to]) {
+        if (!score.has(end)) continue;
+        const used = focus.get(end) || 0;
+        if (used >= FOCUS_CAP) continue;
+        focus.set(end, used + FOCUS_PER_EDGE);
+        bump(end, FOCUS_PER_EDGE);
+      }
+    }
+  }
+  const ranked = [...score.entries()].sort((a, z) => z[1] - a[1] || a[0].localeCompare(z[0]));
+  if (ranked.length === 1) return ranked[0][0];
+  if (ranked[0][1] === ranked[1][1]) return null;   // 并列 = 没证据
+  return ranked[0][0];
+}
+// ── END-MIRROR ──
+
+export const HERO_SCALE = 1.5;   // = web board-kinds.js HERO_SCALE
+
+const TYPE_RE = /^(deck|site|docx):/;
+
+/**
+ * 这块板此刻的主角 id（只看桌面根层，与前端入座同口径）：board.hero 显式覆盖，
+ * 否则按关系线推。前端还会把谱系收叠藏起来的旧版排除在外 —— 那些卡本来就被
+ * 改自边重罚，结果一致，这里不重复实现收叠。
+ */
+export function boardHeroId(board) {
+  const known = new Set(Object.keys(board?.zones || {}));
+  const items = [];
+  for (const [id, e] of Object.entries(board?.objects || {})) {
+    if (!Number.isFinite(e?.x) || e.kind) continue;
+    if (layerOf(id, e, known) !== '') continue;
+    const m = TYPE_RE.exec(id);
+    if (m) items.push({ id, type: m[1] });
+  }
+  if (board?.hero && items.some(it => it.id === board.hero)) return board.hero;
+  return pickHero(items, board?.bindings || {});
+}
+
+export function heroSize(id) {
+  const m = TYPE_RE.exec(String(id || ''));
+  if (!m) return null;
+  return {
+    w: Math.round(DECK_EMBED_W * HERO_SCALE),
+    h: ARTIFACT_HEADER_H + Math.round(ARTIFACT_PREVIEW_H[m[1]] * HERO_SCALE),
+  };
+}

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

@@ -10,6 +10,7 @@
  */
 
 import { KINDS } from './kinds/index.js';
+import { boardHeroId, heroSize } from './board-hero.js';
 
 export const DECK_EMBED_W = 640;
 export const ARTIFACT_HEADER_H = 28;
@@ -60,3 +61,25 @@ export function estimateSize(id, entry) {
   if (/\.(md|txt)$/i.test(s)) return KIND_SIZES.note;
   return KIND_SIZES.file;
 }
+
+/**
+ * 按**这块板**估尺寸：主角卡（board-hero 的判断）放大 1.5 倍，其余同 estimateSize。
+ * 凡是拿尺寸去避让/取景/列座次的地方都该用它 —— 主角不是特例，是版面常态。
+ * heroId 按 board 对象缓存一次（同一次工具调用里反复问不重算）。
+ */
+const heroCache = new WeakMap();
+export function estimateSizeOn(board, id, entry) {
+  if (entry && Number.isFinite(entry.w) && Number.isFinite(entry.h)) return { w: entry.w, h: entry.h };
+  if (board && typeof board === 'object') {
+    let hero = heroCache.get(board);
+    if (hero === undefined) {
+      hero = boardHeroId(board);
+      heroCache.set(board, hero);
+    }
+    if (hero && hero === id) {
+      const hs = heroSize(id);
+      if (hs) return hs;
+    }
+  }
+  return estimateSize(id, entry);
+}

package/server/lib/board-relations.js

@@ -38,7 +38,7 @@ const DIR_KIND_PREFIXES = Object.entries(KINDS)
 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);
+    const t = String(obj.data?.t || '').replace(/\s+/g, ' ').trim().slice(0, 48);
     return `手写字「${t}」`;
   }
   if (obj?.kind === 'scribble') return '一笔涂鸦（笔画内容要看得截图画布）';

package/server/lib/chalk.js

@@ -0,0 +1,121 @@
+/**
+ * server/lib/chalk.js —— 板书（2026-08-23 黑板三期：真相住文件）
+ *
+ * 板书 = agent（或用户）写在画布上的一段话，**本体是 `notes/板书/<stamp>-<slug>.md`**，
+ * board.json 只存它摆在哪、跟谁连线。为什么是文件而不是 board.json 里的 text 物件：
+ *   - agent 要能 Read/Grep/Edit 自己说过的话，git 要有历史（板书是对话，不是记号）
+ *   - board.json 512KB 一把锁整份重写，当对话容器撑不住
+ *   - 跟「kind 文件即真相」一致：删文件即消失，改名/搬家走同一套对账
+ * 草图里的节点仍是画布原生 text（它们是几何的一部分，不是散文）—— 两种东西本来
+ * 就不一样，不硬凑。
+ *
+ * frontmatter（只认这几个键，其余原样当正文）：
+ *   nd: chalk            标记（没有它就是普通便利贴）
+ *   by: agent|user
+ *   at: ISO 时间
+ *   anchor: <canvas id>  这段话关于谁（落盘时顺手画 annotates 线）
+ *   reply_to: <path>     回应哪一条板书（线程）
+ *   tag: <tag>           归哪一组
+ *   session: <sid>       （沿用便利贴的归属字段）
+ */
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+
+export const CHALK_DIR = 'notes/板书';
+const FM_RE = /^---\n([\s\S]{0,800}?)\n---\n?/;
+
+export function parseChalk(raw) {
+  const m = FM_RE.exec(raw);
+  if (!m) return { body: raw, chalk: null, sessionId: null };
+  const head = m[1];
+  const get = (k) => { const r = new RegExp(`(?:^|\\n)${k}:\\s*(.+?)\\s*(?:\\n|$)`).exec(head); return r ? r[1].trim() : null; };
+  const body = raw.slice(m[0].length).replace(/^\n+/, '').replace(/\n+$/, '');
+  if (get('nd') !== 'chalk') return { body, chalk: null, sessionId: get('session') };
+  return {
+    body,
+    sessionId: get('session'),
+    chalk: {
+      by: get('by') === 'user' ? 'user' : 'agent',
+      at: get('at'),
+      anchor: get('anchor'),
+      replyTo: get('reply_to'),
+      tag: get('tag'),
+    },
+  };
+}
+
+export function renderChalk({ body, by = 'agent', at = new Date().toISOString(), anchor = null, replyTo = null, tag = null, sessionId = null }) {
+  const lines = ['---', 'nd: chalk', `by: ${by}`, `at: ${at}`];
+  if (anchor) lines.push(`anchor: ${anchor}`);
+  if (replyTo) lines.push(`reply_to: ${replyTo}`);
+  if (tag) lines.push(`tag: ${tag}`);
+  if (sessionId) lines.push(`session: ${sessionId}`);
+  lines.push('---', '', String(body).trim(), '');
+  return lines.join('\n');
+}
+
+/** 文件名：时间戳 + 正文首行做的短名（只留字母数字中日文，≤24），保证可读可排序 */
+export function chalkFileName(body, now = new Date()) {
+  const stamp = now.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, '').replace('T', '-');
+  const first = String(body || '').split('\n').find(l => l.trim()) || '';
+  const slug = first.replace(/^#+\s*/, '').replace(/[*_`>#\[\]()]/g, '').replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-+|-+$/g, '').slice(0, 24) || 'chalk';
+  return `${stamp}-${slug}.md`;
+}
+
+/** 写一条板书到工作区；返回相对路径 */
+export async function writeChalkFile(sharedRoot, fileName, content, { overwrite = false } = {}) {
+  const dir = path.join(sharedRoot, CHALK_DIR);
+  await fs.mkdir(dir, { recursive: true });
+  let name = fileName;
+  if (!overwrite) {
+    // 同一秒两条同首行的板书会撞名（fable 08-23 P2）：存在就加序号，绝不静默覆盖
+    for (let i = 2; i < 100; i += 1) {
+      try { await fs.access(path.join(dir, name)); } catch { break; }
+      name = fileName.replace(/\.md$/, `-${i}.md`);
+    }
+  }
+  const abs = path.join(dir, name);
+  await fs.writeFile(abs, content, 'utf8');
+  return `${CHALK_DIR}/${name}`;
+}
+
+/** 最近的板书（给注入用）：按文件名（=时间戳）倒序，读前几条的首行 */
+export async function recentChalk(sharedRoot, { limit = 8 } = {}) {
+  const dir = path.join(sharedRoot, CHALK_DIR);
+  let names;
+  try { names = (await fs.readdir(dir)).filter(n => n.endsWith('.md') && !n.startsWith('.')); } catch { return []; }
+  names.sort().reverse();
+  const out = [];
+  for (const n of names.slice(0, limit)) {
+    try {
+      const raw = await fs.readFile(path.join(dir, n), 'utf8');
+      const { body, chalk } = parseChalk(raw);
+      if (!chalk) continue;
+      const first = (body.split('\n').find(l => l.trim()) || '').replace(/^#+\s*/, '').slice(0, 80);
+      out.push({ path: `${CHALK_DIR}/${n}`, first, ...chalk });
+    } catch { /* 单条读不到就跳 */ }
+  }
+  return out;
+}
+
+/** 给一批画布 id 里的板书读首行（read_board 用）：Map<id, {first, by, anchor, replyTo}> */
+export async function chalkExcerpts(sharedRoot, ids) {
+  const out = new Map();
+  const base = path.resolve(sharedRoot, CHALK_DIR);
+  for (const id of ids) {
+    if (typeof id !== 'string' || !id.startsWith(`${CHALK_DIR}/`)) continue;
+    const name = id.slice(CHALK_DIR.length + 1);
+    // 读侧同一道闸：单段文件名、不越界（fable 08-23：id 可控，别拿它直接 join）
+    if (!name || name.includes('/') || name.includes('..') || name.startsWith('.')) continue;
+    const abs = path.resolve(base, name);
+    if (!abs.startsWith(base + path.sep)) continue;
+    try {
+      const raw = await fs.readFile(abs, 'utf8');
+      const { body, chalk } = parseChalk(raw);
+      if (!chalk) continue;
+      const first = (body.split('\n').find(l => l.trim()) || '').replace(/^#+\s*/, '').replace(/\*\*/g, '').slice(0, 60);
+      out.set(id, { first, ...chalk });
+    } catch { /* 文件没了：留给对账 */ }
+  }
+  return out;
+}