@xiaobuyu/nodesign 0.0.6 → 0.0.8

package/server/engine/mcp/tools/read-board.js

@@ -16,43 +16,57 @@ import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 import { readBoard } from '../../../projects/board-store.js';
 import { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
-import { layerOf } from '../../../lib/canvas-id.js';
+import { layerOf, bareTag } from '../../../lib/canvas-id.js';
 import { relationsDigest, bindingLine } from '../../../lib/board-relations.js';
 import { groupObjects, asciiMinimap, bboxOfRects, relationOf, columnsOf, viewportRelation } from '../../../lib/board-groups.js';
+import { laneSummaries } from '../../../lib/board-lanes.js';
+import { capacityOf, DEFAULT_CHALK_W } from '../../../lib/sketch-layout.js';
+import { sheetSummaries, rollCardRect, slotRectOf, nextSpotInSlot, freeColumnsInSheet, latestSheetId } from '../../../lib/board-sheets.js';
 import { getViewpoint } from '../../../projects/viewpoint-store.js';
 import { chalkExcerpts, CHALK_DIR } from '../../../lib/chalk.js';
 import { getSharedDir } from '../../../projects/workspace.js';
+import { promises as fs } from 'node:fs';
+import { byOf, describeBy } from '../actor.js';
+import { listRoleNames } from '../../agent/role-card.js';
+import path from 'node:path';
 
 /** 同一"行"的 y 容差：入座算法一行内顶对齐，40 世界像素内视作同行 */
 const ROW_TOLERANCE = 40;
 
-function describeEntry(board, id, entry, glyph = null, excerpts = null) {
+function describeEntry(board, id, entry, glyph = null, excerpts = null, staleIds = null, view = null) {
+  // view = { by: 当前读者, names: slug→展示名 }。读 read_board 的可能是主 agent，
+  // 也可能是常驻角色 —— 同一句「你写的」对两个读者含义相反，所以称呼要带视角。
+  const who = (b) => describeBy(b || 'agent', view?.by || 'agent', view?.names);
+  const mine = (b) => (b || 'agent') === (view?.by || 'agent');
   const sz = estimateSizeOn(board, id, entry);
   const at = `@(${Math.round(entry.x)},${Math.round(entry.y)}) ${Math.round(sz.w)}x${Math.round(sz.h)}`;
   const g = glyph ? `[${glyph}] ` : '';
   const flags = `${entry.staging ? ' 〔草稿〕' : ''}${entry.tag ? ` #${entry.tag}` : ''}`;
   const ch = excerpts?.get(id);
-  if (ch) return `- ${g}[板书·${ch.by === 'user' ? '用户' : '你'}写的] 「${ch.first}」 ${at} (path: ${id})${ch.anchor ? ` 关于 ${ch.anchor}` : ''}${ch.replyTo ? ` 回应 ${ch.replyTo}` : ''}${flags}`;
+  if (ch) return `- ${g}[板书·${who(ch.by)}写的] 「${ch.first}」 ${at} (path: ${id})${ch.anchor ? ` 关于 ${ch.anchor}` : ''}${ch.replyTo ? ` 回应 ${ch.replyTo}` : ''}${flags}`;
   if (entry.kind === 'text') {
     const t = String(entry.data?.t || '').replace(/\s+/g, ' ').slice(0, entry.data?.format === 'md' ? 60 : 24);
     const md = entry.data?.format === 'md' ? 'md' : '手写';
-    return `- ${g}[${md}] 「${t}」 ${at} (id: ${id})${entry.by === 'agent' ? ' ·你写的' : ''}${flags}`;
+    return `- ${g}[${md}] 「${t}」 ${at} (id: ${id})${entry.by ? ` ·${who(entry.by)}写的` : ''}${flags}`;
   }
-  if (entry.kind === 'scribble') return `- ${g}[涂鸦] ${at} (id: ${id})${entry.by === 'agent' ? ' ·你画的' : ''}${flags}`;
-  return `- ${g}${id} ${at}${entry.by === 'agent' ? ' ·你摆的' : ''}${flags}`;
+  if (entry.kind === 'scribble') return `- ${g}[涂鸦] ${at} (id: ${id})${entry.by ? ` ·${who(entry.by)}画的` : ''}${flags}`;
+  // 过期座位要明说（iss_mt38ucyq：旧路径条目被 agent 当"失效卡"差点建议删素材母版）
+  const stale = staleIds?.has(id) ? ' 〔⚠️磁盘上已无此路径 —— 多半被移动/改名了，以磁盘为准，别据此判失效或建议删除〕' : '';
+  return `- ${g}${id} ${at}${entry.by ? ` ·${who(entry.by)}摆的` : ''}${flags}${stale}`;
+  // eslint-disable-next-line no-unused-vars -- mine 留给后续按视角过滤用
 }
 
-export function makeReadBoardTool({ projectId }) {
+export function makeReadBoardTool({ projectId, sharedRoot = null }) {
   return tool(
     'read_board',
     `Read the workbench canvas: an ASCII minimap, then GROUPS (things linked by lines or
 sharing a #tag), then loose items row by row, then relation lines.
 
-Use this BEFORE arranging (arrange_on_board), writing notes (create_on_board) or
-sketching (sketch_on_board) — placement without looking is guessing. Coordinates are
-world pixels. Only seated items appear (fresh artifacts get a seat within a second).
+Use this BEFORE moving things (edit_board) or writing/sketching (write_on_board) —
+placement without looking is guessing. Coordinates are world pixels. Only seated items
+appear (files you just wrote are seated automatically within a couple of seconds).
 Items marked 〔草稿〕 are still staging (yours from this turn, half-transparent until
-finish_sketch / end of turn). The user's current viewport (if known) is drawn as a box
+edit_board commit / end of turn). The user's current viewport (if known) is drawn as a box
 on the minimap and listed with what is inside it.`,
     {
       layer: z.string().max(300).optional()
@@ -61,7 +75,11 @@ on the minimap and listed with what is inside it.`,
         .describe('Only list items/lines carrying this #tag (one group, e.g. a sketch you made)'),
       minimap: z.boolean().optional().describe('Also print an ASCII minimap (off by default — the relative-position summary is usually enough)'),
     },
-    async ({ layer, tag, minimap }) => {
+    async ({ layer, tag: rawTag, minimap }, extra) => {
+      const tag = rawTag ? bareTag(rawTag) : rawTag;   // #状态板 也认（查询侧统一剥 #）
+      // 视角：谁在读这块板。常驻角色读到自己写的板书才该显示「你写的」，
+      // 读到别人的显示那个人的名字（展示名只是渲染，判断一律用 slug）。
+      const view = { by: byOf(extra), names: await listRoleNames(sharedRoot) };
       if (!projectId) {
         return { content: [{ type: 'text', text: 'No project bound.' }], isError: true };
       }
@@ -82,10 +100,23 @@ on the minimap and listed with what is inside it.`,
       const excerpts = await chalkExcerpts(getSharedDir(projectId), (byLayer.get(want) || []).map(it => it.id));
       const items = (byLayer.get(want) || [])
         .filter(({ entry }) => !tag || entry.tag === tag)
+        // 收卷（2026-08-27 收纳器）：收着的组不逐件列 —— 版图里压成一行，这是 agent
+        // 上下文的收纳（跟画布收纳同一刀）。显式 tag= 点名看某组时照常展开列。
+        .filter(({ entry }) => tag || !entry.tag || !board.rolls?.[entry.tag])
         // 板书条目但文件已经没了 = 幽灵座位，别列给 agent（删文件那条路会清座位，这是兜底）
         .filter(({ id }) => !id.startsWith(`${CHALK_DIR}/`) || excerpts.has(id))
         .sort((a, b) => (a.entry.y - b.entry.y) || (a.entry.x - b.entry.x));
       const entryOf = new Map(items.map(it => [it.id, it.entry]));
+      // 座位 vs 磁盘对账（iss_mt38ucyq）：文件挪走后旧座位可能还挂几十秒
+      // （改名对账/前端回写有时差）。查一遍真身，过期的在条目上点名。
+      const root = getSharedDir(projectId);
+      const staleIds = new Set();
+      await Promise.all(items.map(async ({ id, entry }) => {
+        if (entry.kind === 'text' || entry.kind === 'scribble' || id === 'browse') return;
+        const bare = String(id).replace(/^(deck|site|docx):/, '');
+        if (!bare || bare.includes('..') || /^(text|scribble|b):/.test(bare)) return;
+        try { await fs.access(path.resolve(root, bare)); } catch { staleIds.add(id); }
+      }));
 
       // 小地图（用户视口画框）
       const vp = getViewpoint(projectId);
@@ -129,7 +160,7 @@ on the minimap and listed with what is inside it.`,
           lines.push('', `组 ${i + 1}${tags ? ` ${tags}` : ''}（${g.members.length} 件 ${g.edges.length} 线${staging ? '，草稿' : ''}）：`);
           const sorted = g.members.map(id => ({ id, entry: entryOf.get(id) }))
             .sort((a, b) => (a.entry.y - b.entry.y) || (a.entry.x - b.entry.x));
-          for (const { id, entry } of sorted) lines.push(describeEntry(board, id, entry, glyphOf.get(id), excerpts));
+          for (const { id, entry } of sorted) lines.push(describeEntry(board, id, entry, glyphOf.get(id), excerpts, staleIds, view));
           for (const bid of g.edges.slice(0, 12)) lines.push(`    ${bindingLine(board.bindings[bid], board)} (line id: ${bid})`);
           if (g.edges.length > 12) lines.push(`    …还有 ${g.edges.length - 12} 条线`);
         });
@@ -147,7 +178,7 @@ on the minimap and listed with what is inside it.`,
               rowY = entry.y;
               lines.push(`— 行 y≈${Math.round(rowY)} —`);
             }
-            lines.push(describeEntry(board, id, entry, glyphOf.get(id), excerpts));
+            lines.push(describeEntry(board, id, entry, glyphOf.get(id), excerpts, staleIds, view));
           }
         }
       }
@@ -160,7 +191,82 @@ on the minimap and listed with what is inside it.`,
           }).join('、')}`);
         }
       }
-      if (board.hero && !tag) lines.push('', `★ 显式主角：${board.hero}（arrange_on_board 的 feature/unfeature 管它）`);
+      if (board.hero && !tag) lines.push('', `★ 显式主角：${board.hero}（edit_board 的 feature/unfeature 管它）`);
+
+      // 纸的清单（2026-08-29 纸范式）：agent 的空间账本 —— 每张纸的名字/位置/件数/
+      // 剩余空地。at 坐标以当前纸版心左上为原点，这一节就是坐标系的地图。
+      if (!want && !tag) {
+        try {
+          const ss = sheetSummaries(board);
+          if (ss.length) {
+            const latest = latestSheetId(board);
+            lines.push('', '纸（sheet）：at:{x,y} 写的是纸内像素（版心左上为原点）。'
+              + '**写满不会自动翻页** —— 排不下时写入被拒收，下一页由你自己 open_sheet 规划：');
+            for (const s of ss) {
+              // 剩多少地方按**字**报（08-29 刀 D）：agent 手里的东西是字，
+              // 只给像素等于让它每次落笔前做一道做不准的算术
+              const cap = capacityOf(DEFAULT_CHALK_W, s.freeH);
+              lines.push(`  ${s.id}${s.id === latest ? '（当前）' : ''}${s.title ? `（${s.title}）` : ''}：世界 (${s.x},${s.y}) ${s.w}x${s.h}，${s.count} 件，剩 ~${s.freeH}px 高（≈${cap.lines} 行 / ${cap.cjk} 字）${s.lastId ? `，最新 ${s.lastId}` : ''}`);
+              // 规划过的块各剩多少（08-29 刀 E）：填到一半要知道还有哪块地是空的，
+              // 不然只能靠猜 —— 猜错的下场是写入被拒收，白跑一趟
+              // 这张纸还剩哪些空地（08-29 刀 F）：只报"最后一件下面剩多少"是不够的 ——
+              // 那一列到底了不等于这张纸满了，右边可能整片空着，而 agent 要靠这个
+              // 判断"还放不放得下、要不要开新一页"
+              const free = freeColumnsInSheet(board, s.id);
+              if (free.length > 1) {
+                const cells = free.map((f) => `x=${f.x} 剩 ${capacityOf(DEFAULT_CHALK_W, f.freeH).lines} 行`);
+                lines.push(`    空地：${cells.join(' / ')}`);
+              }
+              const sheet = board.sheets?.[s.id];
+              for (const [nm, sl] of Object.entries(sheet?.slots || {})) {
+                const r = slotRectOf({ ...sheet, id: s.id }, nm);
+                const spot = nextSpotInSlot(board, r, { w: 1, h: 1 });
+                const freeH = spot.full ? 0 : Math.max(0, r.y + r.h - spot.y);
+                const c = capacityOf(r.w, freeH);
+                lines.push(`    · ${nm}${sl.about ? `（${sl.about}）` : ''}${sl.for === 'artifacts' ? '【收产物】' : ''}：块内 (${sl.x},${sl.y}) ${sl.w}x${sl.h}，剩 ≈${c.lines} 行 / ${c.cjk} 字`);
+              }
+            }
+          }
+          // 暂存架（2026-08-30）：机器到货的默认座 —— 上了墙但还没进版面，等 agent 安置
+          const shelf = Object.entries(board.objects || {})
+            .filter(([, e]) => e?.seat === 'shelf' && !e.zone && Number.isFinite(e?.x))
+            .map(([id]) => id);
+          const pend = Array.isArray(board.pending) ? board.pending : [];
+          const unplaced = [...shelf, ...pend];
+          if (unplaced.length) {
+            lines.push('', `📦 暂存架上 ${unplaced.length} 件等安置（机器只码在架上，版面归你）：`);
+            for (const r of unplaced.slice(0, 8)) lines.push(`  ${r}`);
+            if (unplaced.length > 8) lines.push(`  …还有 ${unplaced.length - 8} 件`);
+            lines.push('  安置的手：open_sheet{plan:[{slot:"图",at:{…},w,h,for:"artifacts"}…]} 规划产物地，'
+              + '或逐件 pin_to_board{path,slot} / edit_board{ops:[{op:"move",…}]}。');
+          }
+        } catch { /* 纸读不出不挡座次 */ }
+      }
+
+      // 版图（2026-08-27 空间规划）：线 = 同 tag 的纵列。这是 agent 的符号地图 ——
+      // 摆放按关系（续哪条线/岔自哪条）声明，几何机器排，别按坐标猜。
+      if (!tag) {
+        const laneList = laneSummaries(board);
+        if (laneList.length) {
+          lines.push('', '线的清单（一条线 = 同一个 tag 的一纵列；{tag,chain:true} 接着写，open_lane 开新的一条）：');
+          for (const l of laneList) {
+            // 收着的线一行带过：细节不进上下文（要看就 read_board tag= 点名，或 unroll）
+            const roll = board.rolls?.[l.tag];
+            if (roll) {
+              const rc = rollCardRect(board, l.tag);
+              lines.push(`  #${l.tag}：已收卷${roll.label ? `（「${roll.label}」）` : ''}，${l.count} 件收在卷里`
+                + `${rc ? `，卷卡占位约 @(${rc.x},${rc.y}) ${rc.w}x${rc.h}` : ''}`
+                + ` —— 座位和文件都在（Read 照常），edit_board unroll 展开；别往收着的线里接新话`);
+              continue;
+            }
+            const dirTxt = '';
+            lines.push(l.registered
+              ? `  #${l.tag}：${l.count} 节${l.parent ? `，岔自 ${l.parent}` : ''}，列头 (${l.x},${l.y})`
+                + `${l.frontier ? `，接着写会落 (${l.frontier.x},${l.frontier.y}) 附近` : ''}${l.lastId ? `，最新 ${l.lastId}` : ''}${dirTxt}`
+              : `  #${l.tag}：${l.count} 件（未登记的野线 —— chain:true 照样能续）${dirTxt}`);
+          }
+        }
+      }
 
       // 用户视点（有上报才有）
       if (vp && !tag) {
@@ -183,7 +289,8 @@ on the minimap and listed with what is inside it.`,
         } catch { /* 关系读不到不挡座次 */ }
       }
 
-      lines.push('', '（口径：稀疏表只列摆过的；层归属为服务端近似；尺寸为形态估算）');
+      lines.push('', '（口径：稀疏表只列摆过的；层归属为服务端近似；尺寸=存档真值优先、缺了按形态估；'
+        + '角色精灵贴着该角色最新一条板书（那条四周留了 60px 身位）；带⚠️的条目=座位与磁盘对不上账）');
       return { content: [{ type: 'text', text: lines.join('\n') }] };
     },
   );

package/server/engine/mcp/tools/read-tavern-json.js

@@ -13,10 +13,38 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import { tool } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
-import { detectKind, digest, fetchEntries } from '../../../lib/tavern-json.js';
+import { detectKind, digest, fetchEntries, extractCardFromPng, listBookEntries } from '../../../lib/tavern-json.js';
 
 const MAX_FETCH_CHARS = 24_000;
 
+/**
+ * 世界书条目表。四方世界卡这种 570 条的怪物逐条带引子会刷出上千行 ——
+ * 超过 80 条就转紧凑档：常驻的全列（那是要人工挑进 CLAUDE.md 的），
+ * 触发的只报名字+触发词不带引子，并指路 export_book 一步落盘。
+ */
+function 渲染世界书(条目, 标题) {
+  const L = [标题 + '：'];
+  const compact = 条目.length > 80;
+  const 常驻 = 条目.filter(e => e.常驻 && !e.停用);
+  const 触发 = 条目.filter(e => !e.常驻 && !e.停用);
+  const 停用数 = 条目.filter(e => e.停用).length;
+  if (compact) {
+    L.push(`启用 ${常驻.length + 触发.length}（常驻 ${常驻.length} / 触发 ${触发.length}）· 停用 ${停用数}`);
+    L.push('');
+    L.push(`常驻条目（每轮在场的候选 —— 逐条人工过：内容进 CLAUDE.md，引擎件不搬）：`);
+    for (const e of 常驻) L.push(`- ${e.名字}  ${e.字数}字`);
+    L.push('');
+    L.push(`触发条目 ${触发.length} 条（名字｜触发词）——别逐条 fetch，用 mode="export_book" 一步落成 世界书/ 文件：`);
+    for (const e of 触发) L.push(`- ${e.名字} ｜ ${e.触发.slice(0, 4).join(' ')}`);
+  } else {
+    for (const e of 条目) {
+      L.push(`- ${e.名字}  ${e.常驻 ? '常驻' : `触发[${e.触发.join(' ')}]`} ${e.字数}字${e.停用 ? ' (停用)' : ''}`);
+      if (e.引子) L.push(`    ${e.引子}…`);
+    }
+  }
+  return L.join('\n');
+}
+
 function 渲染摘要(d, 文件名) {
   const L = [];
   if (d.形态 === 'preset') {
@@ -46,17 +74,11 @@ function 渲染摘要(d, 文件名) {
     if (d.开场白备选) L.push(`- alternate_greetings  ${d.开场白备选} 条备选开场白`);
     if (d.世界书.length) {
       L.push('');
-      L.push(`内嵌世界书 ${d.世界书.length} 条：`);
-      for (const e of d.世界书) {
-        L.push(`- ${e.名字}  ${e.常驻 ? '常驻' : `触发[${e.触发.join(' ')}]`} ${e.字数}字${e.停用 ? ' (停用)' : ''}`);
-      }
+      L.push(渲染世界书(d.世界书, `内嵌世界书 ${d.世界书.length} 条`));
     }
   } else {
-    L.push(`酒馆世界书：${文件名}，${d.条目.length} 条`);
-    for (const e of d.条目) {
-      L.push(`- ${e.名字}  ${e.常驻 ? '常驻' : `触发[${e.触发.join(' ')}]`} ${e.字数}字${e.停用 ? ' (停用)' : ''}`);
-      if (e.引子) L.push(`    ${e.引子}…`);
-    }
+    L.push(`酒馆世界书：${文件名}`);
+    L.push(渲染世界书(d.条目, `${d.条目.length} 条`));
   }
   L.push('');
   L.push('要正文就再调一次本工具：mode="fetch"，entries=["名字或名字的一部分", …]。');
@@ -80,10 +102,18 @@ Two steps:
 2. mode "fetch" with entries[] — full text of just the ones you picked (name,
    partial name, or id). Capped at ${MAX_FETCH_CHARS} chars per call.
 
-This tool only reads. Turning a preset into 编排.yaml + 设定 files is your job —
-you decide the grouping, and you drop what does not belong (markers are filled by
-酒馆 at runtime and have no place here; platform-specific jailbreak sections are
-pointless on this platform).`,
+Also reads **PNG character cards** directly (V2 chara / V3 ccv3 embedded data) —
+point path at the .png, no conversion needed.
+
+mode "export_book" is the one writing mode: dumps every enabled lorebook entry to
+workspace files in one call (triggered entries one file each with trigger keys in
+frontmatter → grep them before writing a chapter; constant entries under 常驻/ for
+you to curate into CLAUDE.md). Use it for big world cards — hundreds of entries
+must not flow through your context. Judgment stays yours: what goes to CLAUDE.md,
+and dropping 酒馆 engine machinery (MVU variables / HTML status bars / CoT
+frameworks / regex_scripts — this platform has its own 状态板/明骰/记忆). Markers
+are filled by 酒馆 at runtime and have no place here; jailbreak sections are
+pointless on this platform.`,
     {
       path: z.string().describe(
         'Path to the .json. Relative paths resolve against the session workspace, '
@@ -91,12 +121,14 @@ pointless on this platform).`,
       ),
       // ⚠️ 参数名和枚举值一律 ASCII —— 工具 schema 是模型要照着填的东西，
       // 中文键名在这条路上不可靠（全仓其他工具也都是 ASCII，别开这个头）
-      mode: z.enum(['digest', 'fetch']).optional()
-        .describe('digest = structure only (default); fetch = full text of the picked entries'),
+      mode: z.enum(['digest', 'fetch', 'export_book']).optional()
+        .describe('digest = structure only (default); fetch = full text of picked entries; export_book = write every enabled lorebook entry to workspace files (triggered ones one file each with keys in frontmatter, constant ones under 常驻/) — the mechanical half of an import, judgment stays yours'),
       entries: z.array(z.string()).optional()
         .describe('For mode="fetch": entry names (partial match ok) or ids'),
+      out: z.string().max(120).optional()
+        .describe('For mode="export_book": target folder, workspace-relative (default 世界书)'),
     },
-    async ({ path: rel, mode = 'digest', entries = [] }) => {
+    async ({ path: rel, mode = 'digest', entries = [], out }) => {
       const fail = (text) => ({ content: [{ type: 'text', text }], isError: true });
       try {
         const raw = String(rel || '').trim();
@@ -112,8 +144,15 @@ pointless on this platform).`,
         if (!abs) return fail(`File not found: ${raw}\nLooked in:\n${candidates.map(c => `  ${c}`).join('\n')}`);
 
         let doc;
-        try { doc = JSON.parse(await fs.readFile(abs, 'utf8')); } catch (e) {
-          return fail(`这个文件不是合法 JSON：${e.message}`);
+        const buf = await fs.readFile(abs);
+        if (buf.length > 3 && buf.readUInt32BE(0) === 0x89504e47) {
+          // 酒馆的卡就是一张 PNG（V3 ccv3 / V2 chara 藏在 tEXt 块里）
+          doc = extractCardFromPng(buf);
+          if (!doc) return fail('这张 PNG 里没有角色卡数据（tEXt 块无 ccv3/chara）——它可能只是普通图片。');
+        } else {
+          try { doc = JSON.parse(buf.toString('utf8')); } catch (e) {
+            return fail(`这个文件不是合法 JSON：${e.message}`);
+          }
         }
         const kind = detectKind(doc);
         if (!kind) {
@@ -134,6 +173,35 @@ pointless on this platform).`,
           return { content: [{ type: 'text', text: 块.join('\n\n') }] };
         }
 
+        if (mode === 'export_book') {
+          const all = listBookEntries(doc);
+          const live = all.filter(e => !e.停用 && e.正文.trim());
+          if (!live.length) return fail('这份文件里没有启用且有正文的世界书条目。');
+          const root = sharedRoot || workspaceRoot;
+          const dirRel = String(out || '世界书').replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+          if (!dirRel || dirRel.split('/').some(s2 => s2 === '..' || s2.startsWith('.'))) return fail('out 目录不合法。');
+          const slug = (t) => String(t).replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-+|-+$/g, '').slice(0, 32) || 'entry';
+          const used = new Set();
+          let 触发数 = 0; let 常驻数 = 0;
+          for (const e of live) {
+            const sub = e.常驻 ? `${dirRel}/常驻` : dirRel;
+            await fs.mkdir(path.join(root, sub), { recursive: true });
+            let name = slug(e.名字);
+            for (let i = 2; used.has(`${sub}/${name}`); i += 1) name = `${slug(e.名字)}-${i}`;
+            used.add(`${sub}/${name}`);
+            const fm = ['---', 'nd: lore',
+              `keys: ${JSON.stringify(e.触发)}`,
+              `constant: ${e.常驻}`, `source: ${path.basename(abs)}`, '---', '', e.正文.trim(), ''];
+            await fs.writeFile(path.join(root, sub, `${name}.md`), fm.join('\n'), 'utf8');
+            if (e.常驻) 常驻数 += 1; else 触发数 += 1;
+          }
+          return { content: [{ type: 'text', text:
+            `Exported ${live.length} entries → ${dirRel}/：触发 ${触发数} 条（一条一文件，frontmatter 带 keys —— `
+            + `每章动笔前拿本章的人名/地名/物件 grep 这个目录，命中就 Read）；常驻 ${常驻数} 条在 ${dirRel}/常驻/`
+            + `（逐条人工过：世界观内容挑十条以内进 CLAUDE.md，MVU/状态栏/CoT/回复格式这类酒馆引擎件不搬 —— `
+            + `平台有自己的状态板/明骰/记忆）。停用条目已跳过。` }] };
+        }
+
         return { content: [{ type: 'text', text: 渲染摘要(digest(doc), path.basename(abs)) }] };
       } catch (err) {
         return fail(`read_tavern_json failed: ${err?.message || String(err)}`);

package/server/engine/mcp/tools/report-issue.js

@@ -31,18 +31,24 @@ export function makeReportIssueTool({ projectId, sessionId, ctx }) {
   return tool(
     'report_issue',
     `Write to the maintainer of this HARNESS — the tools and environment you work
-in. This goes to their issue list, not to the user. Three kinds:
+in. This goes to their issue list, not to the user.
+
+This harness is in BETA and you are one of its primary testers: the maintainer
+actively wants these reports and reads every one. When you hesitate between
+reporting and not reporting — report. Three kinds:
 
 - "bug": something in the harness behaved WRONGLY — a tool crashed on valid
   input, returned corrupt output, or contradicted its own description.
 - "friction": it worked, but the path was painful — a missing parameter, a
-  return shape you had to fight, a workaround you have now done more than once
-  (the workaround IS the report).
+  return shape you had to fight, a workaround (one detour is enough to report;
+  the workaround IS the report).
 - "idea": nothing is broken, but while working you saw something the harness
   could do better or do at all — a tool that should exist, a flag that would
-  collapse three steps into one, a default that fights real usage. The
-  maintainer reads every one of these and good ones get built — if a concrete
-  improvement occurred to you, report it rather than let it evaporate.
+  collapse three steps into one, a default that fights real usage, or a
+  METHODOLOGY you worked out on the job (a technique, a judgment rule, a
+  sequence that reliably works) that the harness should teach every session,
+  bake into a skill, or automate. Good ones get built — report it rather than
+  let it evaporate.
 
 This is NOT a substitute for doing the work. Finish the task the way you would
 have anyway — route around the problem, deliver the result — and log this on
@@ -50,7 +56,8 @@ the side. Never report and then hand back less than you could have.
 
 Do NOT report:
 - Your own mistakes (wrong path, malformed edit) — not harness issues
-- One-off flakes that a retry fixed
+- A one-off flake that a single retry fixed (the automatic layer counts those);
+  a flake that RECURS is friction — report it
 - Anything about the design work itself (that belongs in the conversation)
 - Praise or vague sentiment ("the tools are great", "X could be better
   somehow") — a report with no actionable content is noise
@@ -94,6 +101,7 @@ every time; a viewportOnly flag would remove the whole detour" is actionable.`,
           };
         }
         try {
+          // ℹ️ 遥测事件：前端刻意不消费 —— 摩擦上报的读者是站主（信箱/审计），不是当场的用户
           ctx?.emit?.({ type: 'run.friction_reported', kind, summary, toolName: toolName || null, count: rec.count });
         } catch { /* emit fail-safe */ }
         return {

package/server/engine/mcp/tools/role-memory.js

@@ -0,0 +1,83 @@
+/**
+ * mcp/tools/role-memory.js —— jot_memory：角色往自己家里记一笔（2026-08-28）
+ *
+ * 角色文件夹范式（用户拍板）：`角色/<名>/` 是一个角色的家 —— 角色卡.md 住这，
+ * 记忆.md 也住这，**用户随时能改**。角色没有 Write/Edit（白名单如此，不放开），
+ * 所以「角色自己记记忆」只能是一件 MCP 工具：身份从 byOf 盖章来（不是自称），
+ * 落点由 harness 拼（角色写不了别人家）。
+ *
+ * 记忆是**追加式日志**：一次一条、带时间戳小节。改写/整理归用户和 GM（他们有真编辑
+ * 权），角色只增不删 —— 「角色能抹掉自己说过的话」不是我们要的性质。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { byOf } from '../actor.js';
+import { isResidentRole, isSlotType } from '../../agent/cast.js';
+import { readCastRegistry } from '../../agent/role-card.js';
+
+const ROLES_DIR = '角色';
+const MEMORY_FILE = '记忆.md';
+const MAX_NOTE = 2000;
+
+/** 这个角色的家在哪：登记表里卡的目录优先，没登记就按 slug 开家 */
+export async function roleHomeDir(workspaceRoot, slug) {
+  const reg = await readCastRegistry(workspaceRoot);
+  const card = reg.roles?.[slug]?.card;
+  if (typeof card === 'string' && card.startsWith(`${ROLES_DIR}/`)) {
+    const dir = path.dirname(card);
+    // 登记表模型可写 —— 家必须还在 角色/ 里，逃出去就按 slug 兜底
+    if (!dir.includes('..')) return dir;
+  }
+  return `${ROLES_DIR}/${slug}`;
+}
+
+export function makeJotMemoryTool({ workspaceRoot }) {
+  return tool(
+    'jot_memory',
+    `Jot one note into YOUR OWN memory file (角色/<你>/${MEMORY_FILE}).
+
+For resident roles only. Use it for things future-you must remember across scenes:
+promises made, secrets learned, how you feel about someone now, where an item went.
+One event per call, a few lines. Append-only — the user and the GM curate the file,
+you never rewrite history. When you wake up lost, Read your card and this file.`,
+    {
+      text: z.string().min(1).max(MAX_NOTE).describe('The note. A few lines, first person, concrete.'),
+    },
+    async (args, extra) => {
+      const fail = (msg) => ({ content: [{ type: 'text', text: msg }], isError: true });
+      if (!workspaceRoot) return fail('没有工作区。');
+      const me = byOf(extra);
+      // ⛔ 演员位（rp-actor/rp-narrator）单独说：它**是**角色，只是实例名还没解析出来
+      // （别名桥要到派发结果或第一次 SendMessage 才学到）。08-28 真会话实录：角色刚上场
+      // 就 jot，连吃两次「你是主控」，于是它以为自己不是角色 —— 而它没有 Write 权限，
+      // 那句指引把它引向一条走不通的路。话术必须说实话，并给一条走得通的出路。
+      if (isSlotType(me)) {
+        return fail('你的实例名这会儿还没解析出来（刚上场、还没被点过名），记不进你的记忆文件。'
+          + '先照常演，下一拍再记；要是一直记不上，让主控用 SendMessage 点你一次。');
+      }
+      if (!isResidentRole(me)) {
+        return fail('只有常驻角色有记忆文件。你是主控 —— 项目记忆走 记忆/ 目录（Write/Edit）。');
+      }
+      const text = String(args.text || '').trim();
+      if (!text) return fail('空的记不了。');
+
+      const homeRel = await roleHomeDir(workspaceRoot, me);
+      const dir = path.join(workspaceRoot, homeRel);
+      const file = path.join(dir, MEMORY_FILE);
+      if (!path.resolve(file).startsWith(path.resolve(workspaceRoot, ROLES_DIR) + path.sep)) {
+        return fail('记忆文件路径异常，拒绝写入。');
+      }
+      await fs.mkdir(dir, { recursive: true });
+      let head = '';
+      try { await fs.access(file); } catch {
+        head = `# 记忆\n\n<!-- ${me} 的记忆：角色自己 jot_memory 追加，用户和 GM 可整理改写。 -->\n`;
+      }
+      const stamp = new Date().toISOString().slice(0, 16).replace('T', ' ');
+      await fs.appendFile(file, `${head}\n## ${stamp}\n\n${text}\n`, 'utf8');
+      return { content: [{ type: 'text', text: `记下了 → ${homeRel}/${MEMORY_FILE}` }] };
+    },
+  );
+}

package/server/engine/mcp/tools/roll-dice.js

@@ -0,0 +1,82 @@
+/**
+ * mcp/tools/roll-dice.js —— roll_dice：服务端真随机骰（2026-08-28，沉浸感机制刀①）
+ *
+ * ## 为什么必须是工具
+ *
+ * 「明骰」此前是教义（GM 手写骰表），骰子本身却只能由模型**编一个数** ——
+ * 玩家一旦意识到骰运是编的，跑团的信任根基当场塌掉。这里用 crypto 真随机投，
+ * 结果同时走两条路：工具返回给 GM（写进正文与骰表），`run.dice` 事件直达前端
+ * （用户看到与 GM 笔无关的第一手骰面 —— 明骰才真的"明"）。
+ *
+ * 只注册给 GM（不进角色工具白名单）：判定归场务的笔，角色要检定就在戏里喊。
+ * 参数 ASCII（feedback-ascii-tool-params）。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import crypto from 'node:crypto';
+
+/** 判定结果一句话（纯函数可断言）。nd:rp-prompt */
+export function describeRoll({ label, n, sides, modifier, advantage, rolls, kept, total, dc }) {
+  const adv = advantage === 'adv' ? '（优势取高）' : advantage === 'dis' ? '（劣势取低）' : '';
+  const mod = modifier ? (modifier > 0 ? `+${modifier}` : `${modifier}`) : '';
+  const faces = rolls.length > 1 ? `[${rolls.join(', ')}]` : `[${rolls[0]}]`;
+  const crit = sides === 20 && n === 1
+    ? (kept === 20 ? ' —— **自然 20**，给它一个镜头' : kept === 1 ? ' —— **自然 1**，给它一个镜头' : '')
+    : '';
+  const vs = dc != null ? ` vs DC ${dc} —— ${total >= dc ? '**成功**' : '**失败**'}` : '';
+  return `🎲 ${label}：${n}d${sides}${mod}${adv} → ${faces}${mod ? ` ${mod}` : ''} = **${total}**${vs}${crit}`;
+}
+
+export function makeRollDiceTool({ projectId, ctx = null, rngInt = crypto.randomInt } = {}) {
+  return tool(
+    'roll_dice',
+    `Roll real server-side dice (cryptographic RNG) for a check. The result also fires a
+run.dice event straight to the user's screen — open dice the GM's pen cannot fake, which
+is the whole point: never make up a roll yourself. After rolling: write the outcome into
+the beat (a TRPG-style hint beats reporting raw numbers) and log it in the 明骰表.
+Failure buys information or a cost; success buys a new problem — never a flat nothing.`,
+    {
+      label: z.string().min(1).max(60)
+        .describe('What this check is, shown to the user (e.g. "斥候·侦查" or "哥布林·突袭")'),
+      sides: z.number().int().min(2).max(1000).default(20).optional().describe('Die faces (default 20)'),
+      n: z.number().int().min(1).max(20).default(1).optional().describe('How many dice (default 1)'),
+      modifier: z.number().int().min(-100).max(100).default(0).optional().describe('Flat bonus/malus added to the total'),
+      advantage: z.enum(['none', 'adv', 'dis']).default('none').optional()
+        .describe('adv = roll twice keep high, dis = keep low (n must be 1)'),
+      dc: z.number().int().min(1).max(1000).optional().describe('Difficulty class; result line says success/failure'),
+    },
+    async (args, _extra) => {
+      if (!projectId) return { content: [{ type: 'text', text: 'No project bound.' }], isError: true };
+      const sides = args.sides ?? 20;
+      const n = args.n ?? 1;
+      const modifier = args.modifier ?? 0;
+      const advantage = args.advantage ?? 'none';
+      if (advantage !== 'none' && n !== 1) {
+        return { content: [{ type: 'text', text: 'advantage/disadvantage 只对单骰（n=1）有意义。' }], isError: true };
+      }
+      const rolls = [];
+      const times = advantage === 'none' ? n : 2;
+      for (let i = 0; i < times; i += 1) rolls.push(rngInt(1, sides + 1));
+      const kept = advantage === 'adv' ? Math.max(...rolls)
+        : advantage === 'dis' ? Math.min(...rolls)
+          : null;
+      const total = (advantage === 'none' ? rolls.reduce((a, b) => a + b, 0) : kept) + modifier;
+      const outcome = args.dc != null ? (total >= args.dc ? 'success' : 'failure') : null;
+      const line = describeRoll({
+        label: args.label, n, sides, modifier, advantage,
+        rolls, kept: kept ?? rolls[0], total, dc: args.dc ?? null,
+      });
+      // 明骰直达用户（fail-soft：事件坏了不拦骰）—— 这条是"骰子可信"的另一半
+      try {
+        ctx?.emit?.({
+          type: 'run.dice', sessionId: null,
+          label: args.label, sides, n, modifier, advantage,
+          rolls, total, ...(args.dc != null ? { dc: args.dc, outcome } : {}),
+        });
+      } catch { /* fail-soft */ }
+      return { content: [{ type: 'text', text:
+        `${line}\n（用户已在屏幕上看到这一骰 —— 正文按结果写后果，骰表记一行。）` }] };
+    },
+  );
+}

package/server/engine/mcp/tools/roll-film.js

@@ -254,7 +254,7 @@ and move on.`,
       shots: z.array(z.object({
         prompt: z.string().describe('H3 three-field English prompt'),
         duration: z.number().min(5.2).max(12.25).default(8),
-        name: z.string().regex(/^[\w-]{1,40}$/).describe('shot slug, unique in batch'),
+        name: z.string().regex(/^[\w一-鿿぀-ヿ-]{1,40}$/).describe('shot slug, unique in batch'),
         first_frame: z.string().optional(),
         last_frame: z.string().optional(),
         steps: z.number().int().min(4).max(8).optional().describe('default 8; 4 = fast draft'),