@xiaobuyu/nodesign 0.0.6 → 0.0.8

package/server/lib/artifact-target.js

@@ -95,7 +95,10 @@ export function clearActiveArtifact(sessionId) {
 }
 
 function normalizeRel(p) {
-  return String(p).replace(/\\/g, '/').replace(/^\.\//, '');
+  // 尾部 ?query / #hash 一并剥掉：agent 常把预览 URL 原样拿来当 path
+  //（'dist/index.html?t=18&panel=0' 落 not found，08-24 清账两案）。
+  // 磁盘文件名里合法出现 ? # 的场景在这套产物约定里不存在。
+  return String(p).replace(/\\/g, '/').replace(/^\.\//, '').replace(/[?#].*$/, '');
 }
 
 async function exists(p) {
@@ -108,13 +111,9 @@ function insideWorkspace(workspaceRoot, absPath) {
   return absPath === root || absPath.startsWith(root + path.sep);
 }
 
-/**
- * 站点的页面清单（相对产物根）。
- */
-export async function listSitePages(workspaceRoot) {
-  const m = await KINDS[KIND_SITE].manifest(workspaceRoot, null);
-  return m.pages;
-}
+// （listSitePages 2026-08-24 拆除：调用 KINDS.site.manifest 这个不存在的方法，
+//  一调必 TypeError，全仓无调用方 —— 死代码假装公开 API。页面清单读
+//  taskManifest().artifacts[].pages。）
 
 /**
  * 推断某个 html 路径的产物形态。
@@ -209,11 +208,28 @@ export async function resolveArtifactTarget(workspaceRoot, relPath, sessionId) {
     const hit = await tryPath(relPath);
     if (hit) { setActiveArtifact(sessionId, hit.relPath, hit.kind); return hit; }
     const abs = path.resolve(workspaceRoot, relPath);
+    if (!insideWorkspace(workspaceRoot, abs)) return { ok: false, message: 'path escapes workspace' };
+    // 回退：agent 常拿**产物根相对**或**源目录相对**路径来喂（'index.html'、
+    // 'dist/index.html'），而这里收的是工作区相对（'jet-engine/dist/index.html'）。
+    // 没命中时按各站点实例的 root / srcRoot 补前缀再试一轮，省一次注定失败的
+    // 往返（08-24 案：三个工具三种写法全 not found）。
+    const m = await taskManifest(workspaceRoot);
+    const rel = normalizeRel(relPath);
+    const prefixes = new Set();
+    for (const a of (m?.artifacts || [])) {
+      if (a.kind !== KIND_SITE || a.single) continue;
+      if (a.root) prefixes.add(a.root);
+      if (a.srcRoot && a.srcRoot !== a.root) prefixes.add(a.srcRoot);
+    }
+    for (const pre of prefixes) {
+      const hit2 = await tryPath(`${pre}/${rel}`);
+      if (hit2) { setActiveArtifact(sessionId, hit2.relPath, hit2.kind); return hit2; }
+    }
+    const candidates = (m?.artifacts || []).map(a => a.entryRel).filter(Boolean);
     return {
       ok: false,
-      message: insideWorkspace(workspaceRoot, abs)
-        ? `${relPath} not found. Write it first, or check the path.`
-        : 'path escapes workspace',
+      message: `${relPath} not found. Write it first, or check the path (workspace-relative).`
+        + (candidates.length ? `\nExisting artifact entries:\n${candidates.map(c => `- ${c}`).join('\n')}` : ''),
     };
   }
 
@@ -272,9 +288,10 @@ export function requireBrowsable(target) {
 
 /** 给各工具复用的 path 参数描述（保持措辞一致） */
 export const ARTIFACT_PATH_DESC =
-  'Relative path of the artifact entry (deck: "canvas.html", site: "index.html" '
-  + 'or its built output like "dist/index.html", word: "文档.docx"). '
-  + 'Omit to use the artifact you are currently working on.';
+  'WORKSPACE-relative path of the artifact entry (deck: "canvas.html", '
+  + 'root site: "index.html" or "dist/index.html", site in a folder: full path '
+  + 'like "my-site/dist/index.html", word: "文档.docx"). All artifact tools share '
+  + 'this one convention. Omit to use the artifact you are currently working on.';
 
 // ── 兼容层：老名字继续可用，内部全部走上面的实现 ────────────────────────────
 export const CANVAS_PATH_DESC = ARTIFACT_PATH_DESC;

package/server/lib/board-anchor.js

@@ -0,0 +1,49 @@
+/**
+ * server/lib/board-anchor.js —— 锚点解析（2026-08-27 行数棘轮拆件）
+ *
+ * 从 mcp/tools/write-on-board.js **原样**搬出：真 id > tag 包络 > **救援入座**
+ * （文件真在只是还没座位 —— 当场给它排一个再锚。入座下沉后防抖 1.5s 内的窗口、
+ * 以及历史欠座都从这里兜住，「还没有座位」这个失败类只剩"确实不存在"一种真情况）。
+ *
+ * readBoard / seatArtifacts 走注入，不在这里 import —— lib 不该反向抓 engine/runs
+ * 和 projects 层的东西；纯几何依赖（canvas-id / board-kind-sizes）留作直接 import。
+ */
+
+import { layerOf, normalizeCanvasId, tagEnvelope } from './canvas-id.js';
+import { estimateSizeOn } from './board-kind-sizes.js';
+
+/**
+ * @param {object} deps
+ *   projectId       救援入座要按项目发
+ *   known           Set(board.zones 的键) —— layerOf 的分层判据
+ *   readBoard       (pid) => board       救援后重读
+ *   seatArtifacts   (pid, [rel]) => {seated}
+ * @returns {(raw: string, b: object) => Promise<{anchorId,zone,rect,board,rescued?}|null>}
+ */
+export function makeAnchorResolver({ projectId, known, readBoard, seatArtifacts }) {
+  const sizeOf = (b) => (id, e) => estimateSizeOn(b, id, e);
+  return async function resolveAnchor(raw, b) {
+    const nid = normalizeCanvasId(raw);
+    const e = nid ? b.objects?.[nid] : null;
+    if (e && Number.isFinite(e.x)) {
+      return { anchorId: nid, zone: layerOf(nid, e, known), rect: { x: e.x, y: e.y, ...estimateSizeOn(b, nid, e) }, board: b };
+    }
+    const env = tagEnvelope(b, raw, sizeOf(b));
+    if (env) {
+      return { anchorId: env.anchorId, zone: layerOf(env.anchorId, b.objects[env.anchorId], known), rect: { x: env.x, y: env.y, w: env.w, h: env.h }, board: b };
+    }
+    if (nid) {
+      const bare = nid.replace(/^(deck|site|docx|text|scribble):/, '');
+      const { seated } = await seatArtifacts(projectId, [bare]).catch(() => ({ seated: 0 }));
+      if (seated) {
+        const nb = await readBoard(projectId);
+        const ne = nb.objects?.[nid] || nb.objects?.[bare];
+        const realId = nb.objects?.[nid] ? nid : bare;
+        if (ne && Number.isFinite(ne.x)) {
+          return { anchorId: realId, zone: layerOf(realId, ne, known), rect: { x: ne.x, y: ne.y, ...estimateSizeOn(nb, realId, ne) }, board: nb, rescued: true };
+        }
+      }
+    }
+    return null;
+  };
+}

package/server/lib/board-dirty.js

@@ -0,0 +1,93 @@
+/**
+ * server/lib/board-dirty.js —— 板上动静（2026-08-29 纸范式刀 4）
+ *
+ * 病根：用户拖拽落盘（HTTP PATCH /board）与文件搬家（POST /move）此前**完全静默**
+ * —— board.updated 七处 emit 全是 agent 侧动作，agent 对「用户刚动过什么」只能等
+ * 下一轮注入撞运气。这里立一份进程内的动静台账：
+ *
+ *   写方   api/board.js PATCH（位置真变了才记 —— 尺寸回写不算动静）、
+ *          api/board.js erase、api/assets.js /move
+ *   读方   UserPromptSubmit「板上动静」节（下轮必达）、
+ *          PreToolUse 板工具注入器（agent 下一次摸板时插话，按会话恰好一次）
+ *
+ * HTTP 层就是用户（agent 侧写板走 board-store 直调不过这里），所以不用猜作者。
+ * 进程内存不落盘：动静是「此刻」，重启即作废。
+ */
+
+const CAP = 60;
+const TTL_MS = 30 * 60 * 1000;
+let seq = 0;                 // 单调序号（同毫秒两笔动静时间戳会撞车，序号不会）
+const store = new Map();     // pid → [{seq, at, kind, id, to?}]
+const markers = new Map();   // `${pid}:${sessionId}` → 上次已告知的序号
+
+function prune(list, now) {
+  const keep = list.filter(e => now - e.at <= TTL_MS);
+  return keep.length > CAP ? keep.slice(keep.length - CAP) : keep;
+}
+
+/** 记一批动静。kind ∈ moved | removed | mv（文件搬家，带 to）| erased（整组擦） */
+export function noteBoardDirty(pid, events) {
+  if (!pid || !events?.length) return;
+  const now = Date.now();
+  const list = store.get(pid) || [];
+  for (const e of events) {
+    if (!e || typeof e.id !== 'string') continue;
+    list.push({ seq: ++seq, at: now, kind: e.kind || 'moved', id: e.id.slice(0, 300), ...(e.to ? { to: String(e.to).slice(0, 300) } : {}) });
+  }
+  store.set(pid, prune(list, now));
+}
+
+/** 某序号之后的动静（新在后）。sinceSeq=0 = 全部未过期的 */
+export function dirtyEvents(pid, sinceSeq = 0) {
+  const now = Date.now();
+  const list = prune(store.get(pid) || [], now);
+  store.set(pid, list);
+  return list.filter(e => e.seq > sinceSeq);
+}
+
+export function lastSeen(pid, sessionId) {
+  return markers.get(`${pid}:${sessionId}`) || 0;
+}
+
+export function markSeen(pid, sessionId, seenSeq = seq) {
+  if (pid && sessionId) markers.set(`${pid}:${sessionId}`, seenSeq);
+}
+
+/**
+ * 有限负责制（刀⑤ 2026-08-30，站主原话改的）：agent 只对**自己专注的工作区**
+ * （当前纸的内部）的摆放负责 —— 挪进当前纸的东西点名出来、要它处理；挪出纸面
+ * 的是用户自留地，只报不催。板整个是「用户随便动、agent 别拔河」，这条只是把
+ * 「动到哪儿了」按纸分拣，agent 才知道哪些动静该接手。
+ *
+ * @param events   dirtyEvents 的产物
+ * @param board    现在的板（位置以现状为准，不看动静发生时的旧坐标）
+ * @param sheetOf  (id) => sheetId|null —— 由调用方绑好 board 的判定函数
+ * @param currentSheetId  agent 此刻的当前纸
+ * @returns {{ inMine: string[], elsewhere: string[] }}  两拨 id
+ */
+export function splitDirtyByCharge(events, { sheetOf, currentSheetId } = {}) {
+  const inMine = []; const elsewhere = [];
+  const seen = new Set();
+  for (const e of events) {
+    if (e.kind === 'erased' || seen.has(e.id)) continue;
+    seen.add(e.id);
+    const sid = sheetOf ? sheetOf(e.kind === 'mv' ? (e.to || e.id) : e.id) : null;
+    (currentSheetId && sid === currentSheetId ? inMine : elsewhere).push(e.id);
+  }
+  return { inMine, elsewhere };
+}
+
+/** 一批动静的人话（注入两处共用一份措辞） */
+export function describeDirty(events, { limit = 6 } = {}) {
+  if (!events?.length) return null;
+  const verbs = { moved: '挪了', removed: '从板上移走了', mv: '把文件搬到', erased: '擦掉了整组' };
+  const lines = events.slice(-limit).map((e) => {
+    if (e.kind === 'mv') return `${verbs.mv} ${e.to}（原 ${e.id}）`;
+    if (e.kind === 'erased') return `${verbs.erased} #${e.id}`;
+    return `${verbs[e.kind] || '动了'} ${e.id}`;
+  });
+  const more = events.length > limit ? `（还有 ${events.length - limit} 条更早的）` : '';
+  return `${lines.join('；')}${more}`;
+}
+
+export function _resetBoardDirty() { store.clear(); markers.clear(); }

package/server/lib/board-excerpt.js

@@ -0,0 +1,80 @@
+/**
+ * lib/board-excerpt.js —— 板书的一句话预览（首页卡片用）
+ *
+ * 为什么单开一个而不是并进封面管线（lib/cover.js）：**板书不是产物**。
+ * 封面管线的输入是 taskManifest 里的 artifacts（deck / site / docx …），
+ * 拿 chromium 截一张印样贴到卡上。板书是写在画布上的字，没有入口文件、
+ * 没有画幅，截图这条路对它没有意义 —— 结果就是整个演出项目的卡常年一片空白
+ * 加一行"还没出东西"，而里面躺着一整个故事。
+ *
+ * 它该有的样子不是"贴一张印样"，是**这张纸上写着什么**：把最近一条板书的开头
+ * 直接写在卡的空白纸上。所以这里只出文本，不出图。
+ *
+ * 便宜是硬要求：首页 /projects/stats 一次要过一遍所有项目。所以
+ *   - 按**文件名**倒序（板书文件名以 YYYYMMDD-HHMMSS 打头），不 stat 每个文件
+ *   - 只读最新那一个文件的前几 KB
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+/** 板书本体的落点（跟 write-on-board 里那份一致） */
+export const CHALK_DIR = path.join('notes', '板书');
+
+/** 读文件只取头一截：一条板书可能很长，预览只要开头几行 */
+const HEAD_BYTES = 4096;
+
+/**
+ * 去掉 frontmatter 和几个行首记号，压成能直接写在卡上的几行。
+ * 不做完整 markdown 渲染 —— 卡上那几行是"笔迹"，不是排版好的正文。
+ */
+export function excerptOf(raw, max) {
+  const body = String(raw || '')
+    .replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '')
+    // ⛔ 围栏块整段扔掉。板书里最常见的围栏是 ```nd:controls（画布上那排控件的
+    // 声明）—— 它在卡上会变成一坨源码，而它根本不是这段故事的字。
+    // 后半个 |``` 收尾未闭合的围栏：宁可少几行，也不能把源码倒到卡上。
+    .replace(/^[ \t]*```[\s\S]*?^[ \t]*```[ \t]*$|^[ \t]*```[\s\S]*$/gm, '');
+  const lines = body.split(/\r?\n/)
+    // 行首：标题 / 引用 / 列表点 / 任务框，都是排版记号不是字
+    .map((l) => l.replace(/^\s*(?:#{1,6}\s+|>\s+|[-*+]\s+)/, '').replace(/^\s*\[[ xX]\]\s*/, ''))
+    // 行内：强调和行内码只留字。卡上那几行是笔迹，星号和反引号原样显示就是噪音
+    .map((l) => l.replace(/\*\*([^*]+)\*\*/g, '$1').replace(/(?<!\*)\*([^*\n]+)\*(?!\*)/g, '$1')
+      .replace(/`([^`\n]+)`/g, '$1').trim())
+    .filter(Boolean);
+  if (!lines.length) return '';
+  let out = '';
+  for (const l of lines) {
+    if (out.length + l.length > max && out) break;
+    out += (out ? '\n' : '') + l;
+    if (out.length >= max) break;
+  }
+  return out.length > max ? `${out.slice(0, max)}…` : out;
+}
+
+/**
+ * @returns {Promise<null | { count: number, text: string }>} 没有板书就 null
+ */
+export async function chalkPreview(sharedDir, { max = 150 } = {}) {
+  const dir = path.join(sharedDir, CHALK_DIR);
+  let names;
+  try {
+    names = (await fs.readdir(dir)).filter((n) => n.endsWith('.md'));
+  } catch { return null; }          // 没这个目录 = 这个项目没写过板书
+  if (!names.length) return null;
+  // 文件名带时间戳前缀，按名倒序就是按时间倒序（省掉 N 次 stat）
+  names.sort().reverse();
+  let raw = '';
+  try {
+    const fh = await fs.open(path.join(dir, names[0]), 'r');
+    try {
+      const buf = Buffer.alloc(HEAD_BYTES);
+      const { bytesRead } = await fh.read(buf, 0, HEAD_BYTES, 0);
+      // ⚠️ 按字节截会把最后一个多字节字符劈成两半，转字符串时变成替换字符。
+      // 预览允许丢尾巴，但不允许出现乱码 —— 所以砍掉可能不完整的那一个。
+      raw = buf.subarray(0, bytesRead).toString('utf8').replace(/�+$/, '');
+    } finally { await fh.close(); }
+  } catch { return null; }
+  const text = excerptOf(raw, max);
+  return text ? { count: names.length, text } : null;
+}

package/server/lib/board-follow.js

@@ -0,0 +1,111 @@
+/**
+ * server/lib/board-follow.js —— 跟随线（2026-08-25 范式重做，第三件）
+ *
+ * 来历：08-25 黑板 RP 真会话里「状态板每章重新锚定到最新章节」是用户自己提出的
+ * 需求，agent 每章手工 move_group + remove/add 线两次、做了十几遍。这里把它做成
+ * 板上第一条**约束**：一条带 `follow: <目标tag>` 的线，to 端永远指向该 tag 最新
+ * 落板的那件 —— 新件一落，服务端自动重指线、并把 from 端所在的组挪到它旁边。
+ *
+ * 设计取舍：
+ * - 约束的家安在**线上**（不另立 rules 区）：线本来就是「A 关于 B」的真相，
+ *   follow 只是把 B 从一件东西升级成「一族东西的最新一件」。
+ * - 挪组连 seat:'user' 一起（08-28 全放开）：平移保相对格局本来就是这条线先证明的；
+ *   首跟也不再把用户件留在原地（撕组比挪用户件更丑）。
+ * - fail-soft：跟随失败绝不连累落板本身。
+ */
+
+import { readBoard, patchBoard } from '../projects/board-store.js';
+import { estimateSizeOn } from './board-kind-sizes.js';
+import { layerOf } from './canvas-id.js';
+import { placeBeside } from './board-sheets.js';
+import { UNIT } from './rect.js';
+
+/**
+ * 某 tag 有新件落板：把所有 follow 这个 tag 的线重指到 newId，并挪各自的组。
+ * @returns {Promise<{followed: number}>}
+ */
+export async function applyFollows(projectId, { tag, newId }) {
+  if (!tag || !newId) return { followed: 0 };
+  const board = await readBoard(projectId);
+  const followers = Object.entries(board.bindings || {})
+    .filter(([, b]) => b.follow === tag && b.to !== newId);
+  /**
+   * 挂账的跟随规则兑现（2026-08-30）：`board.follows` 里目标是本 tag、但还没有线的，
+   * 现在这一刻目标第一次出现 —— 当场把线补出来，交给下面同一段几何走「首跟」。
+   *
+   * 规则和线分开存就是为了这一刻：立规则时目标可以是空的（skill 教的顺序如此），
+   * 线只在两端都真实存在时才有意义。
+   */
+  for (const [groupTag, rule] of Object.entries(board.follows || {})) {
+    if (rule?.target !== tag) continue;
+    const already = Object.entries(board.bindings || {})
+      .some(([, b]) => b.follow === tag && board.objects?.[b.from]?.tag === groupTag);
+    if (already) continue;
+    const member = Object.entries(board.objects || {})
+      .filter(([, e]) => e?.tag === groupTag && Number.isFinite(e?.x))
+      .sort((a, b) => a[1].y - b[1].y)[0];
+    if (!member || member[0] === newId) continue;
+    followers.push([`b:f${Date.now().toString(36)}${groupTag.length}`, {
+      type: 'annotates', from: member[0], to: '', by: 'agent',
+      label: rule.label || '跟随', follow: tag, ...(rule.side ? { followSide: rule.side } : {}),
+    }]);
+  }
+  if (!followers.length) return { followed: 0 };
+  const target = board.objects?.[newId];
+  if (!target || !Number.isFinite(target.x)) return { followed: 0 };
+  // 只认主控的新件（08-28 用户拍板）：状态板这类跟随组挂在 GM 的叙事链上，
+  // 角色台词/用户落痕就算落进同一个 tag 也不把面板拽走。判据按板上作者，
+  // 不靠"角色自觉别打 tag"（08-27 真会话：GM 亲手让角色打 章节，面板跟着台词跑了）。
+  if ((target.by || 'agent') !== 'agent') return { followed: 0 };
+  const known = new Set(Object.keys(board.zones || {}));
+  const targetRect = { x: target.x, y: target.y, ...estimateSizeOn(board, newId, target) };
+  const targetZone = layerOf(newId, target, known);
+
+  const objects = {}; const bindings = {};
+  let followed = 0;
+  for (const [bid, b] of followers) {
+    // 新目标自己在跟随组里（状态板的卡也打了目标 tag 之类的配置错误）：跳过防自噬
+    const fromEntry = board.objects?.[b.from];
+    const groupTag = fromEntry?.tag || null;
+    if (groupTag && board.objects?.[newId]?.tag === groupTag) continue;
+    const oldTarget = board.objects?.[b.to];
+    bindings[bid] = { ...b, to: newId };
+    followed += 1;
+
+    // 挪 from 端的组（同 tag 全员；没 tag 就只挪 from 自己）
+    const members = groupTag
+      ? Object.entries(board.objects).filter(([, e]) => e.tag === groupTag && Number.isFinite(e?.x))
+      : (fromEntry && Number.isFinite(fromEntry.x) ? [[b.from, fromEntry]] : []);
+    if (!members.length) continue;
+
+    // **平移跟随**（08-25 用户报「跟随坏了」后改）：旧目标有座位时，整组按
+    // 新旧目标的位移平移 —— 全员照挪、seat:user 也挪。用户拖动 = 调整相对
+    // 格局（保留），不 = 取消跟随；旧行为（user 座罢工）在他把三张卡都拖过
+    // 之后让 follow 永久死掉。要真停用有 unfollow。
+    if (oldTarget && Number.isFinite(oldTarget.x)) {
+      const dx = Math.round(target.x - oldTarget.x);
+      const dy = Math.round(target.y - oldTarget.y);
+      if (dx || dy) for (const [id, e] of members) objects[id] = { ...e, x: e.x + dx, y: e.y + dy };
+      continue;
+    }
+
+    // 首跟（旧目标没座位可参照）：解一个位置整组放过去（08-28 起含 user 座 —— 撕组更丑）
+    const movable = members;
+    if (!movable.length) continue;
+    const rects = members.map(([id, e]) => ({ id, x: e.x, y: e.y, ...estimateSizeOn(board, id, e) }));
+    const bb = {
+      x: Math.min(...rects.map(r => r.x)), y: Math.min(...rects.map(r => r.y)),
+      w: Math.max(...rects.map(r => r.x + r.w)) - Math.min(...rects.map(r => r.x)),
+      h: Math.max(...rects.map(r => r.y + r.h)) - Math.min(...rects.map(r => r.y)),
+    };
+    // 首跟 = 精确贴放（2026-08-29 纸范式：环搜退役）。跟随组的位置本来就该
+    // 紧贴目标的固定一侧 —— 压上什么由之后的平移跟随自然化解，不代找洞。
+    void targetZone; void known;
+    const p = placeBeside(targetRect, { w: bb.w, h: bb.h }, b.followSide || 'right', UNIT);
+    const dx = Math.round(p.x - bb.x); const dy = Math.round(p.y - bb.y);
+    if (!dx && !dy) continue;
+    for (const [id, e] of movable) objects[id] = { ...e, x: e.x + dx, y: e.y + dy };
+  }
+  if (followed || Object.keys(objects).length) await patchBoard(projectId, { objects, bindings });
+  return { followed };
+}

package/server/lib/board-groups.js

@@ -121,11 +121,7 @@ export function asciiMinimap(rects, { cols = 48, rows = 16, viewport = null } =
  * 列（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;
-}
+export { bboxOf as bboxOfRects } from './rect.js';
 
 /** b 相对 a 在哪（以 a 为参照）：左/右/上/下 + 距离；重叠则说重叠 */
 export function relationOf(a, b) {

package/server/lib/board-hero.js

@@ -27,7 +27,9 @@ export function pickHero(items, bindings) {
   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') {
+    // 「手画的线」= 用户 / 主控 / 常驻角色画的（08-26：RP 场里大半线是角色画的，
+    // 只认 user|agent 的话主角推断的信号会大量流失）。auto 那支在上面已单独处理。
+    if (b.by && b.by !== 'auto') {
       for (const end of [b.from, b.to]) {
         if (!score.has(end)) continue;
         const used = focus.get(end) || 0;

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

@@ -19,13 +19,48 @@ 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 },
 };
 
+/**
+ * 文件夹卡的身位（2026-08-29 占位契约刀 A）。真身在前端
+ * `web/src/lib/board-geometry.js` 的 FOLDER_CARD —— zones 存档 08-13 瘦身后只剩
+ * 坐标，尺寸就是这个常量，两边靠 parity 测试钉着。
+ *
+ * ⛔ 它以前从不参与落位：三处障碍集合都只遍历 objects，文件夹对落位系统**结构性
+ * 隐形**（生产 128 块真板实测：文件夹被压 112 次 —— 被产物 34、被文件 33、
+ * 被文档 23、被板书 13）。现在它跟别的物件一样是障碍，见 board-obstacles.js。
+ */
+export const FOLDER_CARD = { w: 288, h: 240 };
+
+/**
+ * 文件夹卡矩形（id = 目录路径，跟 zones 的键一致）。
+ *
+ * ⚠️ 每张文件夹卡只住在**一层**：`世界书/常驻` 的卡摆在 `世界书` 那一层里，
+ * 它存的坐标是那一层的坐标——拿它当根层矩形用就是跨层幻影（2026-08-30
+ * proj_mtfpehm3 案：铺在根层的纸被别的层的卡「占满」，一连 6 发容量拒收里
+ * 4 发是假的）。所以取矩形必须点名要哪一层的；`layer: null` 是给「所有层
+ * 一起数」的调用方（目前只有对账/测试）留的口。
+ *
+ * @param {string|null} layer  ''=根层（缺省）；'世界书'=那一层里的子文件夹卡；null=全部
+ */
+export function zoneRects(board, { layer = '' } = {}) {
+  const out = [];
+  for (const [path, z] of Object.entries(board?.zones || {})) {
+    if (!Number.isFinite(z?.x) || !Number.isFinite(z?.y)) continue;
+    if (layer !== null) {
+      const i = path.lastIndexOf('/');
+      const parent = i > 0 ? path.slice(0, i) : '';
+      if (parent !== layer) continue;
+    }
+    out.push({ id: path, x: z.x, y: z.y, ...FOLDER_CARD, folder: true });
+  }
+  return out;
+}
+
 // 前缀表从注册表派生（「写死表家族」第 4 处，2026-08-18 收）：手写
 // `deck|site|docx` 的话加形态必漏，新形态的卡掉到 file 兜底（224×32 细条），
 // agent 摆位按错矩形算。⚠️ 新形态要同步给 ARTIFACT_PREVIEW_H 加一行
@@ -44,7 +79,6 @@ export function estimateSize(id, entry) {
     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 摆位时
   // 就会拿一个错的矩形去算"挨着谁摆、会不会压到谁"。
@@ -58,7 +92,8 @@ export function estimateSize(id, entry) {
   }
   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;
+  // 文本类文件卡带内容预览（08-24：md/json 等升级出预览体），身位=note
+  if (/\.(md|markdown|txt|json|csv|ya?ml)$/i.test(s)) return KIND_SIZES.note;
   return KIND_SIZES.file;
 }
 

package/server/lib/board-lanes.js

@@ -0,0 +1,58 @@
+/**
+ * server/lib/board-lanes.js —— 线（lane）的几何与符号地图（2026-08-27 空间规划第一刀）
+ *
+ * ## 设计总纲：模型声明拓扑，机器做几何
+ *
+ * 模型对坐标是瞎的（把摆放写成话术必然失效 —— 轮次机同一课），但它对**关系**很强。
+ * 所以「线」不是新概念：**线就是 tag** —— chain:true 早就是「接在同 tag 最新一条
+ * 下面」（continue 动词现成）。这里补的只有三件真正缺的：
+ *
+ *   1. **开列** —— 2026-08-29 纸范式后由「铺纸」承担（一条线 = 它自己的一叠纸，
+ *      见 board-sheets.js）；这里的 allocateLaneColumn 扫空列已退役。
+ *   2. **注册表**：board.lanes = { tag: {x,y,w,parent} }，持久在 board.json 里
+ *      （版面地理要跟板走，不跟会话走）。frontier **不存** —— 从成员现算，存了就是
+ *      第二份真相源（feedback-single-source-of-truth）。
+ *   3. **符号地图**（laneSummaries）：read_board 用它报「有哪些线、各几节、接着写
+ *      落哪」—— agent 的空间意识是读得起这张地图，不是看得见像素。
+ *
+ * 头脑风暴回路因此零空间推理：用户在旧节点标注提问 → agent 回答带
+ * open_lane:<那条的id> → 分支列长出来；后续 {tag, chain:true} 续。
+ * RP 场景位、跑团拍行是同一注册表的后续消费方（先不建，地基兼容）。
+ */
+
+import { UNIT } from './rect.js';
+
+/**
+ * 符号地图：板上现在有哪些线。已注册的报起点/节数/frontier/岔自谁；
+ * 没注册但成串的 tag（≥2 件）也报 —— 那是登记制之前长出来的「野线」，
+ * chain:true 照样能续，别让 agent 以为它们不存在。
+ */
+export function laneSummaries(board) {
+  const members = new Map();   // tag → [{id, y, bottom}]（有座位的才算）
+  for (const [id, e] of Object.entries(board?.objects || {})) {
+    if (!e?.tag || !Number.isFinite(e.y)) continue;
+    if (!members.has(e.tag)) members.set(e.tag, []);
+    members.get(e.tag).push({ id, y: e.y, bottom: e.y + (e.h || 5 * UNIT) });
+  }
+  const out = [];
+  const seen = new Set();
+  for (const [tag, l] of Object.entries(board?.lanes || {})) {
+    seen.add(tag);
+    const ms = (members.get(tag) || []).sort((a, b) => a.y - b.y);
+    const last = ms[ms.length - 1] || null;
+    out.push({
+      tag, registered: true, x: l.x, y: l.y, parent: l.parent || null,
+      count: ms.length, lastId: last?.id || null,
+      frontier: { x: l.x, y: last ? Math.round(last.bottom) + UNIT : l.y },
+    });
+  }
+  for (const [tag, ms0] of members) {
+    if (seen.has(tag) || ms0.length < 2) continue;
+    const ms = ms0.sort((a, b) => a.y - b.y);
+    out.push({
+      tag, registered: false, x: null, y: null, parent: null,
+      count: ms.length, lastId: ms[ms.length - 1].id, frontier: null,
+    });
+  }
+  return out;
+}

package/server/lib/board-obstacles.js

@@ -0,0 +1,80 @@
+/**
+ * server/lib/board-obstacles.js —— 一层桌面上「谁占着地方」的唯一真相源
+ * （2026-08-29 占位契约刀 A）
+ *
+ * ## 为什么要有这个文件
+ *
+ * 落位/压上判定原来在三个地方各写了一遍**一模一样**的障碍集合：
+ *   write-on-board.js 的 obstaclesOf / edit-board.js 的 obstaclesNear / board-seater.js
+ * 三份都只遍历 `board.objects`，于是**不住在 objects 里的东西对落位系统结构性隐形**：
+ *
+ *   - 文件夹卡（`board.zones`，只存 {x,y}，尺寸是常量 FOLDER_CARD）
+ *   - 卷卡（`board.rolls`，前端合成物，矩形由 rollCardRect 现算）
+ *
+ * 生产 128 块真板实测（根层、剔掉圈注类的合法压盖）：**文件夹被压 112 次**
+ * （被产物 34 / 被文件 33 / 被文档 23 / 被板书 13 / 被文件夹 7 / 被文字 2）。
+ * 站主点名的「文件夹能被板书覆盖」就是这 13 次，而且它是 100% 必现不是概率问题 ——
+ * 工具连"压住了谁"都报不出来，因为那块地在它眼里根本是空的。
+ *
+ * 收成一份的另一半理由：加一类物件要改三处，改漏一处就是新的隐形物件。
+ * 现在加在这儿一次，三个调用点自动同步。
+ *
+ * ## 边界（写清楚，免得被读成"全量占位"）
+ *
+ * 这套东西**只约束 agent 的自动落位**，不约束用户的手 —— 用户把卡拖到哪都合法，
+ * 拖出纸、拖成重叠都不会被纠正（纸范式纲领：纸是分配纪律不是本体容器）。
+ *
+ * 不进障碍集合的东西，都是真的不占板面，不是漏了：舞台贴/精灵（浮层，几秒即散，
+ * 且精灵自己会避让真卡）、聊天卡/小地图/工具栏（屏幕固定 UI，不在世界坐标系里）、
+ * 包络 chip（纯派生的一圈虚线）、连线（是线不是面）。
+ */
+
+import { layerOf } from './canvas-id.js';
+import { estimateSizeOn, zoneRects } from './board-kind-sizes.js';
+import { inflateSpriteSeats, rollCardRect } from './board-sheets.js';
+
+/**
+ * 一层的障碍集。
+ *
+ * @param {object} board    整块板（要读 zones/rolls/hero）
+ * @param {string} zone     层名；'' = 根层桌面（文件夹卡和卷卡只在这一层）
+ * @param {object} [opts]
+ * @param {object} [opts.objects]  用哪份 objects（缺省 board.objects；edit_board
+ *   要用带上本批改动的 live 副本，那份才是"这一刻"的板）
+ * @param {Set|string[]} [opts.exclude]  排除的 id（主角自己、同组成员）
+ * @param {boolean} [opts.furniture=true]  含不含"常驻家具"（文件夹卡/卷卡）。
+ *   **落位要（true），铺纸不要（false）**：纸不渲染，一张纸的矩形盖在文件夹上
+ *   用户什么也看不见，而纸内落位本来就会避开文件夹；把家具算进铺纸避让，只换来
+ *   第一张纸被推离用户视口 —— "在用户眼皮底下开工"当场失效（写这条时刚被自己
+ *   的端到端测试逮住：纸从 (0,0) 滑到 y=384 绕开一个文件夹）。
+ * @returns {Array<{id,x,y,w,h}>}
+ */
+export function obstaclesIn(board, zone = '', { objects = null, exclude = null, furniture = true } = {}) {
+  const objs = objects || board?.objects || {};
+  const known = new Set(Object.keys(board?.zones || {}));
+  const skip = exclude instanceof Set ? exclude : new Set(exclude || []);
+  const rects = [];
+  for (const [id, e] of Object.entries(objs)) {
+    if (skip.has(id) || !Number.isFinite(e?.x)) continue;
+    if (layerOf(id, e, known) !== zone) continue;
+    rects.push({ id, x: e.x, y: e.y, ...estimateSizeOn(board, id, e) });
+  }
+  // 每层还住着不在 objects 里的占面积物件：文件夹卡按**所在层**取
+  //（子文件夹卡住在父层里，2026-08-30 跨层幻影案之前这儿把它们全当根层矩形，
+  //  文件夹层内的落位则完全看不见它们 —— 同一个错的两面）；卷卡只在根层。
+  if (furniture) {
+    for (const z of zoneRects(board, { layer: zone })) {
+      if (!skip.has(z.id)) rects.push(z);
+    }
+  }
+  if (!zone && furniture) {
+    for (const tag of Object.keys(board?.rolls || {})) {
+      if (skip.has(tag)) continue;
+      const r = rollCardRect(board, tag);
+      // 卷起来的成员座位照旧留在 objects 里当障碍（收纳不等于腾地），这一条
+      // 只为让"压住了卷标签"也能被如实报出来。
+      if (r) rects.push({ id: `roll:${tag}`, ...r });
+    }
+  }
+  return inflateSpriteSeats(rects, objs);
+}