@xiaobuyu/nodesign 0.0.7 → 0.0.8

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

@@ -101,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'),

package/server/engine/mcp/tools/screenshot.js

@@ -87,7 +87,7 @@ to also read your own console.log output from the page (grouped, capped).
 
 FILMSTRIP — the eye for ANIMATION. A single still cannot show easing, overshoot,
 hard cuts between tweens, or "the whole move played off-screen". Pass
-frames (2-30 ms offsets, e.g. [0,120,240,400,700]) + trigger:"window.game.reload()" (JS that
+frames (2-30 ms offsets within a 30s window, e.g. [0,120,240,400,700]) + trigger:"window.game.reload()" (JS that
 starts the move) and you get ONE contact sheet: the same viewport at each of those
 moments, timestamped. One image = one motion curve — judge attack, overshoot,
 settle and cuts directly. click:"#start" performs a REAL trusted click instead
@@ -168,7 +168,7 @@ Do NOT use this tool when:
         .optional()
         .describe("Console capture level for the caption. Default 'warn' returns only warnings/errors (the count of filtered log lines is reported). Pass 'all' to also get console.log/info/debug output — the only way to read your own debug logging from the page."),
       frames: z
-        .array(z.number().min(0).max(15000))
+        .array(z.number().min(0).max(30000))
         .min(1)
         .max(30)
         .optional()

package/server/engine/mcp/tools/set-vars.js

@@ -0,0 +1,150 @@
+/**
+ * mcp/tools/set-vars.js —— `set_vars`：改状态表里的几格（2026-08-30）
+ *
+ * ## 它跟 `edit_board set_text` 的分工
+ *
+ * set_text 是「重写这条板书的整篇正文」。状态板每拍都要动几个数字，用 set_text 就得
+ * 把整张卡连叙述带表格重写一遍 —— 那正是它老写漏、老写错的地方（改一个数字要重述
+ * 十几行，模型每次都在重新生成不该变的部分）。
+ *
+ * set_vars 只动表里那一格，别的一个字不碰。落盘走的是**跟 set_text 同一个**
+ * 重写函数（lib/chalk-rewrite.js），所以 frontmatter 保留、卡高重算、
+ * 用户拖出来的留白留得住这三条不会两边不一致。
+ *
+ * ## 为什么写口要大声失败，不 fail-soft
+ *
+ * 状态表的真相是一份**三方可写**的自由文本：set_vars、agent 的 set_text/Edit、
+ * 以及用户自己（chalk_edit 就是为让他随手改板书造的）。写口只守得住自己那一路。
+ * 所以这一路必须**看不懂就当场停**：表被改坏时若还 fail-soft 地"尽力写"，
+ * 结果是表被写成第二种坏格式，而且没有任何人知道。
+ * 读侧另有一层报警（每轮状态块的 vars 节，见 hooks/user-prompt-submit.js）。
+ *
+ * ⚠️ 笔权（只有作者能改自己的板书）在这里**不判**：状态表是场务件，不是谁的台词。
+ * 谁在管这一场，谁就该能改数字。这跟 edit_board 对叙事板书的规矩是两回事。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { readBoard, patchBoard } from '../../../projects/board-store.js';
+import { rewriteChalkBody } from '../../../lib/chalk-rewrite.js';
+import {
+  findStateTable, applyVars, parseStateTable, renderRows,
+  STATE_TABLE_TAG, VALUE_MAX, KEY_MAX,
+} from '../../../lib/state-table.js';
+
+/** 一次最多改几个键：再多就不是"改状态"是"重建状态表"，那该用 set_text */
+const MAX_KEYS = 20;
+
+export function makeSetVarsTool({ projectId, sharedRoot }) {
+  return tool(
+    'set_vars',
+    `Update values in the board's state table — the one chalk note tagged "${STATE_TABLE_TAG}".
+
+Use this every beat for anything that changed and must be remembered: HP, 好感度, 时间,
+线索, 持有物, 进度. It edits ONLY those cells; the rest of the note (your prose, the
+layout, other tables) is left byte-for-byte alone, and the card is re-measured for you.
+
+Why not edit_board set_text: that rewrites the whole note, so changing one number means
+regenerating a dozen lines that should not change. That is where numbers get silently lost.
+
+The table is plain markdown living in a note the user can see and edit:
+
+  | 键 | 值 |
+  | --- | --- |
+  | 好感度_苏绵 | 3 |
+
+Values you set here show up at the top of your NEXT turn, so you do not have to carry
+them in your head. Keys: letters/digits/CJK/_/-/·, max ${KEY_MAX} chars. Values are
+single-line, max ${VALUE_MAX} chars — long text belongs in the note body, not a cell.
+
+If there is no state table yet, this tool creates nothing: write one first with
+write_on_board (tag: "${STATE_TABLE_TAG}"), then set values here.`,
+    {
+      vars: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+        .describe('Keys to set, e.g. {"好感度_苏绵": 5, "时间": "戌时"}. Existing keys are updated, new ones appended.'),
+    },
+    async (args) => {
+      const fail = (msg) => ({ content: [{ type: 'text', text: msg }], isError: true });
+      if (!projectId || !sharedRoot) return fail('没有项目工作区，set_vars 不可用。');
+
+      const vars = args?.vars && typeof args.vars === 'object' ? args.vars : null;
+      const keys = vars ? Object.keys(vars) : [];
+      if (!keys.length) return fail('vars 是空的 —— 给至少一个键值对。');
+      if (keys.length > MAX_KEYS) {
+        return fail(`一次改了 ${keys.length} 个键，超过 ${MAX_KEYS} 上限。`
+          + `改这么多说明你在重建整张表 —— 那用 write_on_board / edit_board 的 set_text 重写更合适。`);
+      }
+
+      const found = await findStateTable(sharedRoot);
+      if (!found.found) {
+        if (found.reason === 'multiple') {
+          return fail(`板上有 ${found.rels.length} 条 tag 是「${STATE_TABLE_TAG}」的板书：${found.rels.join('、')}。`
+            + `状态表只能有一条 —— 先把多余的那条改掉 tag 或撤下来（edit_board remove），我不猜该改哪一条。`);
+        }
+        return fail(`板上还没有状态表。先用 write_on_board 落一条（\`tag: "${STATE_TABLE_TAG}"\`），`
+          + `正文里放一张两列的表：\n\n| 键 | 值 |\n| --- | --- |\n| 好感度_苏绵 | 3 |\n\n然后再来 set_vars。`);
+      }
+
+      let applied;
+      try {
+        applied = applyVars(found.body, vars);
+      } catch (err) {
+        // ⚠️ 两种失败要说成两句话（真工具探针当场抓到的：原来一律说"表看不懂"，
+        // 于是模型传了个坏键、却被指去修一张根本没坏的表）。
+        // 错误归因说错方向，比不报错好不了多少 —— 它会让人去改对的东西。
+        if (err.code === 'BAD_KEY') {
+          return fail(`这个键不能用，一个格都没改：${err.message}\n`
+            + `（表本身没问题，换个键名重来。）`);
+        }
+        // 大声失败：读不懂就停，绝不"尽力写" —— 写坏的表下一次会被写得更坏，
+        // 而这一路是三个写入方里唯一守得住的那个
+        return fail(`${found.rel} 的状态表看不懂，这次一个键都没改：${err.message}\n`
+          + `（先把表修好 —— 它是普通 markdown，Read 那个文件就能看见。）`);
+      }
+
+      if (!applied.changed.length && !applied.added.length) {
+        return { content: [{ type: 'text', text: `表里这几个键已经是这个值了，没动：${keys.join('、')}（${found.rel}）` }] };
+      }
+
+      // 落盘 + 板上重算：走跟 set_text 同一个函数，三条语义（frontmatter 保留 /
+      // 卡高重算 / 用户拖出来的留白留得住）不会两边不一致
+      const board = await readBoard(projectId);
+      const entry = board.objects?.[found.rel] || {};
+      let box;
+      try {
+        box = await rewriteChalkBody(found.abs, applied.body, entry);
+      } catch (err) {
+        return fail(`${found.rel} 写不进去（${err.message}）—— 表没改成。`);
+      }
+      if (board.objects?.[found.rel]) {
+        // patchBoard 收的是 diff 对象不是回调（board-store.js:85）
+        try {
+          await patchBoard(projectId, { objects: { [found.rel]: { ...entry, w: box.w, h: box.h } } });
+        } catch { /* 板上尺寸没跟上不影响真相（文件已经改了），下次 reflow 会对 */ }
+      }
+
+      const lines = [];
+      if (applied.changed.length) {
+        lines.push(`改了 ${applied.changed.length} 格：`
+          + applied.changed.map((c) => `${c.key} ${c.from || '（空）'} → ${c.to}`).join('；'));
+      }
+      if (applied.added.length) {
+        lines.push(`新增 ${applied.added.length} 格：`
+          + applied.added.map((c) => `${c.key} = ${c.value}`).join('；'));
+      }
+      if (applied.clamped.length) {
+        // 钳住但要说（入参不许静默改口径）
+        lines.push(`⚠️ 这几个值被清洗过（换行压成空格、竖线换成斜杠、超 ${VALUE_MAX} 字截断）：${applied.clamped.join('、')}`);
+      }
+      lines.push(`表在 ${found.rel}，现在共 ${applied.rows.length} 格。下一轮开头你会看到它。`);
+      return { content: [{ type: 'text', text: lines.join('\n') }] };
+    },
+  );
+}
+
+/** 给测试与 SKILL 用的样板表（保持和工具描述里那段一致） */
+export function sampleStateTable(rows = [{ key: '好感度_苏绵', value: '3' }]) {
+  return renderRows(rows).join('\n');
+}
+
+export { parseStateTable };

package/server/engine/mcp/tools/sheet-replan.js

@@ -0,0 +1,46 @@
+/**
+ * mcp/tools/sheet-replan.js —— edit_board 的 replan op（2026-08-30 刀⑧，
+ * 行数棘轮拆件）。
+ *
+ * 版位原来只能在 open_sheet 那一刻定，写到一半发现规划错了只能整张重来 ——
+ * 「先画格子」得是能修正的动作。按名合并：点名的版位增改，没点名的原样保留；
+ * 新声明 for:'artifacts' 时旧的产物位摘牌（一张纸只有一个产物位）。
+ */
+
+import { innerRect, currentSheet } from '../../../lib/board-sheets.js';
+import { currentSheetIdOf } from '../../../lib/sheet-state.js';
+import { capacityOf } from '../../../lib/sketch-layout.js';
+import { clampPlan } from './open-sheet.js';
+
+/**
+ * @returns {{ error:string } | { sheetId:string, entry:object, report:string }}
+ *   entry = 该纸更新后的完整登记项（调用方放进 sheets patch）
+ */
+export function applyReplan({ board, sheetsPatch, sessionId, op }) {
+  const base = { ...board, sheets: { ...(board.sheets || {}), ...sheetsPatch } };
+  const sh = op.sheet && base.sheets?.[op.sheet]
+    ? { id: op.sheet, ...base.sheets[op.sheet] }
+    : currentSheet(base, currentSheetIdOf(sessionId));
+  if (!sh) return { error: '还没有纸 —— 先 open_sheet' };
+  const inn = innerRect(sh);
+  // prevSlots：below 可以引用纸上已有的版位（「在 main 底下补一块」是最常见的补法）
+  const { slots: addSlots, clampedSlots } = clampPlan(op.plan, { w: inn.w, h: inn.h }, base.sheets[sh.id].slots || {});
+  const merged = { ...(base.sheets[sh.id].slots || {}) };
+  if (Object.values(addSlots).some((sl) => sl.for === 'artifacts')) {
+    for (const nm of Object.keys(merged)) {
+      if (merged[nm].for === 'artifacts') { merged[nm] = { ...merged[nm] }; delete merged[nm].for; }
+    }
+  }
+  // 属性级合并（2026-08-30）：replan 只想改尺寸时不该把旧的 about / for 一并抹掉
+  for (const [nm, sl] of Object.entries(addSlots)) merged[nm] = { ...(merged[nm] || {}), ...sl };
+  const names = Object.entries(addSlots).map(([nm, sl]) => {
+    const c = capacityOf(sl.w, sl.h);
+    return `${nm} at (${sl.x},${sl.y}) ${sl.w}x${sl.h}（~${c.lines} 行 / ~${c.cjk} 字）`;
+  });
+  return {
+    sheetId: sh.id,
+    entry: { ...base.sheets[sh.id], slots: merged },
+    report: `· replan：纸 ${sh.id} 增改版位 ${names.join('；')}`
+      + `${clampedSlots.length ? `；⚠ 钳进版心：${clampedSlots.join(', ')}` : ''}。没点名的版位原样保留。`,
+  };
+}

package/server/engine/mcp/tools/web-search.js

@@ -494,7 +494,7 @@ Suggested flow for image-led pages:
           // 落盘了就发 file_changed —— generate_image 一直在发，这里漏了，
           // 于是参考图落进工作区之后前端毫无感知（素材抽屉要刷新才看得见）
           for (const img of downloadedImages) {
-            try { ctx?.emit?.({ type: 'run.file_changed', path: img.relPath, change: 'add' }); } catch { /* */ }
+            try { ctx?.emit?.({ type: 'run.file_changed', filePath: img.relPath, event: 'add' }); } catch { /* */ }
           }
         }