@xiaobuyu/nodesign 0.0.7 → 0.0.8

package/server/projects/board-store.js

@@ -20,15 +20,17 @@
 import { promises as fs } from 'fs';
 import path from 'path';
 import { getSharedDir, ensureProjectWorkspace, gitRenamesSince } from './workspace.js';
-import { CHALK_DIR } from '../lib/chalk.js';
+import { CHALK_DIR, trashChalkFile } from '../lib/chalk.js';
+import { estimateSizeOn } from '../lib/board-kind-sizes.js';
 
 export {
   DEFAULT_BOARD_SIZE, MAX_BOARD_BYTES, MAX_OBJECTS, MAX_ZONES, MAX_BINDINGS,
 } from './board-limits.js';
 export { TEXT_FONTS } from './board-sanitize.js';
-import { DEFAULT_BOARD_SIZE, MAX_BOARD_BYTES, MAX_OBJECTS, MAX_ZONES, MAX_BINDINGS } from './board-limits.js';
+import { DEFAULT_BOARD_SIZE, MAX_BOARD_BYTES, MAX_OBJECTS, MAX_ZONES, MAX_BINDINGS, MAX_LANES, MAX_SHEETS } from './board-limits.js';
 import {
-  clampNum, sanitizeSize, sanitizeTag, sanitizeObject, sanitizeBinding, sanitizeZone, sanitizeBoard, isSafeCanvasId,
+  clampNum, sanitizeSize, sanitizeTag, sanitizeObject, sanitizeBinding, sanitizeZone, sanitizeBoard, sanitizeLane, sanitizeRoll, sanitizeSheet,
+  isSafeCanvasId,
 } from './board-sanitize.js';
 
 // 分区自动铺位常数 —— 与前端 BoardCanvas 的 ZONE_* 保持一致（数值约定，非共享代码）
@@ -107,7 +109,14 @@ export function patchBoard(pid, patch) {
         if (!isSafeCanvasId(rawId)) continue;
         const id = fwd(rawId);
         if (o === null) { delete board.objects[id]; removed.add(id); continue; }
-        const s = sanitizeObject(o, board.size);
+        // **合并语义**（2026-08-25）：patch 条目盖在已有条目上，缺席字段保留。
+        // 病根：前端本地 layout 会落后于服务端（board.json 一次性加载闸门），
+        // 入座把 agent 刚写的条目当新客回写一条 {x,y,z} —— 整条替换语义下
+        // by/seat/w/h/tag/staging 全被抹掉且零报错（08-25 体检三陷阱之②）。
+        // 合并后瘦条目只更新它带来的字段。要删整条传 null；单字段清除走
+        // 各自的专用路（commitStaging 清 staging、removeByTag 摘 tag）。
+        const merged = board.objects[id] ? { ...board.objects[id], ...o } : o;
+        const s = sanitizeObject(merged, board.size);
         if (s && (board.objects[id] || Object.keys(board.objects).length < MAX_OBJECTS)) board.objects[id] = s;
       }
     }
@@ -115,13 +124,81 @@ export function patchBoard(pid, patch) {
       for (const [id, b] of Object.entries(patch.bindings)) {
         if (typeof id !== 'string' || id.length > 300) continue;
         if (b === null) { delete board.bindings[id]; continue; }
-        const s = sanitizeBinding(b);
+        // 合并语义同 objects（08-25）：改材质/label 的瘦 patch 别抹掉 follow 等字段
+        const s = sanitizeBinding(board.bindings[id] ? { ...board.bindings[id], ...b } : b);
         if (!s) continue;
         // 端点也要转发：agent 本轮拿旧路径连的线，落下来必须连到新名字上
         const fixed = { ...s, from: fwd(s.from), to: fwd(s.to) };
         if (board.bindings[id] || Object.keys(board.bindings).length < MAX_BINDINGS) board.bindings[id] = fixed;
       }
     }
+    // 线注册表（08-27 空间规划）：合并语义同 objects；parent 也走改名转发
+    if (patch?.lanes && typeof patch.lanes === 'object') {
+      board.lanes = board.lanes || {};
+      for (const [name, l] of Object.entries(patch.lanes)) {
+        const tag = sanitizeTag(name);
+        if (!tag) continue;
+        if (l === null) { delete board.lanes[tag]; continue; }
+        const s = sanitizeLane(board.lanes[tag] ? { ...board.lanes[tag], ...l } : l);
+        if (!s) continue;
+        const fixed = s.parent ? { ...s, parent: fwd(s.parent) } : s;
+        if (board.lanes[tag] || Object.keys(board.lanes).length < MAX_LANES) board.lanes[tag] = fixed;
+      }
+      if (!Object.keys(board.lanes).length) delete board.lanes;
+    }
+    // 卷（2026-08-27 收纳器）：合并语义同 lanes；null = 展开（删条目）。
+    // 只动状态位不动成员座位 —— 展开即归位靠的就是这里什么都不搬。
+    if (patch?.rolls && typeof patch.rolls === 'object') {
+      board.rolls = board.rolls || {};
+      for (const [name, r] of Object.entries(patch.rolls)) {
+        const tag = sanitizeTag(name);
+        if (!tag) continue;
+        if (r === null) { delete board.rolls[tag]; continue; }
+        const s = sanitizeRoll(board.rolls[tag] ? { ...board.rolls[tag], ...r } : r);
+        if (!s) continue;
+        if (board.rolls[tag] || Object.keys(board.rolls).length < MAX_LANES) board.rolls[tag] = s;
+      }
+      if (!Object.keys(board.rolls).length) delete board.rolls;
+    }
+    // 纸（2026-08-29 纸范式）：合并语义同 lanes；null = 撕掉登记（成员座位不动）。
+    // 纸名不是路径，不走改名转发。
+    if (patch?.sheets && typeof patch.sheets === 'object') {
+      board.sheets = board.sheets || {};
+      for (const [name, s0] of Object.entries(patch.sheets)) {
+        const nm = sanitizeTag(name);
+        if (!nm) continue;
+        if (s0 === null) { delete board.sheets[nm]; continue; }
+        const s = sanitizeSheet(board.sheets[nm] ? { ...board.sheets[nm], ...s0 } : s0);
+        if (!s) continue;
+        if (board.sheets[nm] || Object.keys(board.sheets).length < MAX_SHEETS) board.sheets[nm] = s;
+      }
+      if (!Object.keys(board.sheets).length) delete board.sheets;
+    }
+    // 跟随规则（2026-08-30）：`{ 组tag: {target,side?,label?} | null }`。规则和线分开存
+    // —— 线要求两端此刻都在板上，规则不要求，所以「开场先立规则再写第一章」这条
+    // skill 教了、模型也一直照做的顺序，第一次真的走得通。
+    if (patch?.follows && typeof patch.follows === 'object') {
+      board.follows = board.follows || {};
+      for (const [g, r] of Object.entries(patch.follows)) {
+        const gt = sanitizeTag(g);
+        if (!gt) continue;
+        if (r === null) { delete board.follows[gt]; continue; }
+        board.follows[gt] = r;
+      }
+      const clean = sanitizeBoard({ ...board, follows: board.follows }).follows;
+      if (clean) board.follows = clean; else delete board.follows;
+    }
+    // 待摆产物队列（刀 G）：整表替换（写方只有 board-seater 一个，diff 没意义）
+    if (patch?.pending !== undefined) {
+      const clean = sanitizeBoard({ ...board, pending: patch.pending }).pending;
+      if (clean?.length) board.pending = clean; else delete board.pending;
+    }
+    // 暂存架原点（2026-08-30）：整值替换，写方只有 board-seater / board-tasklist；
+    // null = 撤架（下批到货重立）
+    if (patch?.shelf !== undefined) {
+      const clean = sanitizeBoard({ ...board, shelf: patch.shelf }).shelf;
+      if (clean) board.shelf = clean; else delete board.shelf;
+    }
     // 主角覆盖：null = 撤销（回到 pickHero 自动推断），字符串 = 显式立主角
     if (patch?.hero !== undefined) {
       if (patch.hero === null) delete board.hero;
@@ -205,7 +282,8 @@ export function removeByTag(pid, tag) {
       // 以进程身份删任意文件；sanitize 现在也拒 `..`，这里是第二道闸）
       if (id.startsWith(`${CHALK_DIR}/`)) {
         const abs = chalkAbsPath(pid, id);
-        if (abs) { try { await fs.unlink(abs); } catch { /* 已经没了 */ } }
+        // 软删进 .nd/trash/（08-25：擦掉的板书要捞得回来）
+        if (abs) await trashChalkFile(getSharedDir(pid), abs);
         delete board.objects[id]; gone.add(id); removed += 1; continue;
       }
       delete o.tag;
@@ -214,6 +292,8 @@ export function removeByTag(pid, tag) {
       if (b.tag === t || gone.has(b.from) || gone.has(b.to)) { delete board.bindings[id]; removed += 1; }
     }
     if (board.hero && gone.has(board.hero)) delete board.hero;
+    // 擦组连卷的状态位一起清（收着的组被 erase_group 后不该留一张空卷卡）
+    if (board.rolls?.[t]) { delete board.rolls[t]; if (!Object.keys(board.rolls).length) delete board.rolls; }
     await writeBoard(pid, board);
     return { board, removed };
   });
@@ -451,6 +531,8 @@ export async function reconcileBoardRenames(pid) {
  *    文件夹没坐标（还没被摆过）时就摆到桌面上，前端下一轮会给它安排位置。
  */
 export function pinToZone(pid, { objectId, zoneId = '' }) {
+  // 08-27 审计修：这里是 patchBoard 之外唯一的 objects 写入口，原先没有数量闸 ——
+  // 反复 pin 新 id 可把 board.objects 撑过 MAX_OBJECTS（只剩 2MB 字节兜底）。
   return withBoardLock(pid, async () => {
     const board = await readBoard(pid);
     const now = Date.now();
@@ -494,12 +576,19 @@ export function pinToZone(pid, { objectId, zoneId = '' }) {
     }
     if (!slot) slot = { x: PAD, y: PAD };
 
+    if (!board.objects[oid] && Object.keys(board.objects).length >= MAX_OBJECTS) {
+      throw new Error(`board 已有 ${MAX_OBJECTS} 件，pin 不进新条目（失控兜底，正常用不该撞到）`);
+    }
     const zMax = Math.max(10, ...Object.values(board.objects).map(o => o.z || 0));
+    // 落座即写估算 w/h（2026-08-29 纸范式刀 3）：此前 pin 出来的条目只有坐标，
+    // read_board 只能报形态表猜值。估算先落盘、前端渲染后按真值回写（useMeasuredSize）。
+    const sz = estimateSizeOn(board, oid, board.objects[oid] || null);
     board.objects[oid] = {
       ...(board.objects[oid] || {}),
       x: clampNum(slot.x, 0, board.size.w, PAD),
       y: clampNum(slot.y, 0, board.size.h, PAD),
       z: zMax + 1,
+      ...(Number.isFinite(board.objects[oid]?.w) ? {} : { w: Math.round(sz.w), h: Math.round(sz.h) }),
     };
     await writeBoard(pid, board);
     return { board, zone: zid ? { id: zid } : null, placed: board.objects[oid] };

package/server/projects/session-jsonl.js

@@ -0,0 +1,110 @@
+/**
+ * server/projects/session-jsonl.js — SDK 会话转录（jsonl）的文件层（2026-08-30 拆出）。
+ *
+ * 这里只有"那个文件在哪、在不在、怎么安全地截短"这三件事，跟任何业务无关。
+ * 分开住是因为读它的人不止一个：回退要截断它，模型切换要靠它判断"这个会话跑过没有"
+ * （没跑过的会话没有历史，跨通路闸不该拦），以后想做分支浏览的也得从它读。
+ *
+ * 转录的位置由 SDK 定：`<CLAUDE_CONFIG_DIR>/projects/<encodeCwdForSDK(cwd)>/<sid>.jsonl`。
+ * 扁平化之后同一个项目所有会话共用一个 cwd，所以它们的 jsonl 都在同一个目录下、按 sid 分文件。
+ */
+
+import path from 'path';
+import { promises as fs } from 'fs';
+import { encodeCwdForSDK } from './workspace.js';
+import { platform } from '../runtime/platform.js';
+
+const GLOBAL_CLAUDE_CONFIG_DIR = platform.claudeConfigDir;
+
+/** 这个会话的转录文件路径。 */
+export function sessionJsonlPath(sessionRoot, sid) {
+  return path.join(GLOBAL_CLAUDE_CONFIG_DIR, 'projects', encodeCwdForSDK(sessionRoot), `${sid}.jsonl`);
+}
+
+/** 转录在不在 —— 等价于"这个会话跑过至少一轮"。 */
+export async function jsonlExistsForSession(sessionRoot, sid) {
+  try {
+    await fs.access(sessionJsonlPath(sessionRoot, sid));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 对话层回滚（2026-08-08）：把 jsonl 截断到 userMessageId 那条之前（含它与其后全部）。
+ * jsonl 是追加式日志，截到 prefix = 它历史上真实存在过的状态，resume 天然自洽；
+ * 之后的 file-history-snapshot 属于被撤销的编辑，一并丢弃是正确语义。
+ * 原子写（tmp+rename）。找不到该 uuid 返 null（fail-soft：文件回滚仍算成功）。
+ */
+export async function truncateJsonlAtMessage(sessionRoot, sid, userMessageId) {
+  const jsonlPath = sessionJsonlPath(sessionRoot, sid);
+  try {
+    const raw = await fs.readFile(jsonlPath, 'utf8');
+    const lines = raw.split('\n');
+    let cut = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (!lines[i] || !lines[i].includes(userMessageId)) continue;
+      try { if (JSON.parse(lines[i]).uuid === userMessageId) { cut = i; break; } } catch { /* 非 JSON 行跳过 */ }
+    }
+    if (cut < 0) {
+      console.warn(`[sessions.rewind] uuid ${userMessageId.slice(0, 8)} 不在 jsonl 里，跳过对话截断`);
+      return null;
+    }
+    const kept = lines.slice(0, cut).join('\n');
+    const tmp = `${jsonlPath}.tmp-rewind`;
+    await fs.writeFile(tmp, kept ? `${kept}\n` : '');
+    await fs.rename(tmp, jsonlPath);
+    return lines.filter(Boolean).length - lines.slice(0, cut).filter(Boolean).length;
+  } catch (err) {
+    console.warn(`[sessions.rewind] jsonl 截断失败（不影响文件回滚）：${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * 砍掉转录末尾的那条用户消息（连同它之后的一切）。
+ *
+ * 专给 fork 用。SDK 的 `forkSession(upToMessageId)` 是**含**那条的（08-30 探针实测：
+ * fork 到第二条用户消息，新转录里那条还在），而「从这里分叉」用户点的是**自己那句
+ * 说错的话** —— 含着它 fork 出来等于什么都没改。所以 fork 完再补这一刀。
+ *
+ * 为什么不能拿原来那个 uuid 去截：fork 会 **remap 每条消息的 uuid**（SDK 文档原话
+ * "remapping every message UUID"），原 id 在新文件里根本不存在。而 fork 既然截止在
+ * 那条消息，它必然就是新转录里最后一条**真**用户消息 —— tool_result 也顶着
+ * type='user' 的壳，所以要把那种排掉，认的是带 text block（或纯字符串正文）的那条。
+ *
+ * @returns {Promise<number|null>} 删掉的行数；没找到用户消息返回 null（fail-soft）
+ */
+export async function truncateJsonlAtLastUserMessage(sessionRoot, sid) {
+  const jsonlPath = sessionJsonlPath(sessionRoot, sid);
+  try {
+    const raw = await fs.readFile(jsonlPath, 'utf8');
+    const lines = raw.split('\n');
+    let cut = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+      if (!lines[i]) continue;
+      let o;
+      try { o = JSON.parse(lines[i]); } catch { continue; }
+      if (o.type !== 'user') continue;
+      const c = o.message?.content;
+      const isRealUserText = typeof c === 'string'
+        || (Array.isArray(c) && c.some((b) => b?.type === 'text'));
+      if (!isRealUserText) continue;   // tool_result 也是 type='user'
+      cut = i;
+      break;
+    }
+    if (cut < 0) {
+      console.warn(`[fork] ${sid.slice(0, 8)} 的转录里找不到用户消息，跳过补刀`);
+      return null;
+    }
+    const kept = lines.slice(0, cut).join('\n');
+    const tmp = `${jsonlPath}.tmp-fork`;
+    await fs.writeFile(tmp, kept ? `${kept}\n` : '');
+    await fs.rename(tmp, jsonlPath);
+    return lines.filter(Boolean).length - lines.slice(0, cut).filter(Boolean).length;
+  } catch (err) {
+    console.warn(`[fork] 转录补刀失败：${err.message}`);
+    return null;
+  }
+}

package/server/projects/store.js

@@ -82,6 +82,15 @@ if (!projectsColNames.has('auto_named')) {
   console.log('[projects/store] projects.auto_named column added');
 }
 
+// 模式分离（2026-08-27）：design（设计工作台，现状）vs rp（演出：常驻角色演故事）。
+// 两种模式共用全部基础设施（画布/黑板/会话/精灵），差异只在提示词分区与工具面
+// （对照表在 engine/mcp/mode-profile.js 一份）。默认 'design' 让全部存量项目零行为变化。
+// 会话启动时读一次 —— 切模式**下个会话生效**，跟"改人设下次上场生效"同一节奏。
+if (!projectsColNames.has('mode')) {
+  db.exec("ALTER TABLE projects ADD COLUMN mode TEXT NOT NULL DEFAULT 'design'");
+  console.log('[projects/store] projects.mode column added (default design)');
+}
+
 // 多用户内测（2026-07-30）：项目归属。NULL 的存量行由 bootstrapAuth() 回填 admin
 if (!projectsColNames.has('owner_id')) {
   db.exec('ALTER TABLE projects ADD COLUMN owner_id TEXT');
@@ -151,6 +160,7 @@ function rowToProject(row) {
     skillId: row.skill_id,
     description: row.description || null,
     kind: row.kind || 'project',
+    mode: row.mode || 'design',
     autoNamed: !!row.auto_named,
     ownerId: row.owner_id || null,
     activeSessionId: row.active_session_id,
@@ -204,6 +214,7 @@ export function createProject({
   skillId = 'deskskill-engine-mini',
   description = null,
   kind = 'project',
+  mode = 'design',
   autoNamed = false,
   ownerId = null,
 }) {
@@ -211,15 +222,18 @@ export function createProject({
   if (kind !== 'project' && kind !== 'quick') {
     throw new Error(`createProject: kind 非法 (${kind})`);
   }
+  if (mode !== 'design' && mode !== 'rp') {
+    throw new Error(`createProject: mode 非法 (${mode})`);
+  }
   const id = newProjectId();
   const desc = (typeof description === 'string' && description.trim()) ? description.trim() : null;
   db.prepare(
-    `INSERT INTO projects (id, name, skill_id, description, kind, auto_named, owner_id) VALUES (?, ?, ?, ?, ?, ?, ?)`,
-  ).run(id, name.trim(), skillId, desc, kind, autoNamed ? 1 : 0, ownerId);
+    `INSERT INTO projects (id, name, skill_id, description, kind, mode, auto_named, owner_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(id, name.trim(), skillId, desc, kind, mode, autoNamed ? 1 : 0, ownerId);
   return getProject(id);
 }
 
-/** 更新（仅允许 name / skill_id / description / active_session_id / kind / autoNamed） */
+/** 更新（仅允许 name / skill_id / description / active_session_id / kind / mode / autoNamed） */
 export function updateProject(id, patch) {
   validateProjectId(id);
   // 用户显式改名 = 这名字他自己定了，系统不再拿摘要覆盖
@@ -228,12 +242,16 @@ export function updateProject(id, patch) {
   if ('kind' in patch && patch.kind !== 'project' && patch.kind !== 'quick') {
     throw new Error(`updateProject: kind 非法 (${patch.kind})`);
   }
+  if ('mode' in patch && patch.mode !== 'design' && patch.mode !== 'rp') {
+    throw new Error(`updateProject: mode 非法 (${patch.mode})`);
+  }
   const map = {
     name: 'name',
     skillId: 'skill_id',
     description: 'description',
     activeSessionId: 'active_session_id',
     kind: 'kind',
+    mode: 'mode',
     autoNamed: 'auto_named',
   };
   const sets = [];
@@ -264,6 +282,41 @@ export function setActiveSession(projectId, sessionId) {
 }
 
 /** 列 project 关联的 runs（用于级联清理） */
+/**
+ * 两个模式各自的用量（控制台那两张卡）。
+ *
+ * ⛔ **排掉站主自己**：他一个人的设计项目就比所有用户加起来还多，混进去这两个数
+ *    就只是在量他自己。同仓口径，见 feedback-creative-tool-metrics。
+ *
+ * ⚠️ 两条查询分开跑不合并：runs 要 join run_model_usage 才拿得到钱，而那张表
+ *    一个 run 有多行（一轮里换过几个模型就几行），并到项目那条里会把 projects
+ *    乘出好几份。COUNT(DISTINCT) 能救回来，但读的人得先看出这里有个陷阱。
+ *
+ * @returns {Array<{mode, projects, users, runs, costUsd, firstAt}>}
+ */
+export function modeStats() {
+  const HUMANS = "p.owner_id IN (SELECT id FROM users WHERE role <> 'admin')";
+  const out = new Map();
+  for (const r of db.prepare(
+    `SELECT p.mode AS mode, COUNT(*) AS projects, COUNT(DISTINCT p.owner_id) AS users,
+            MIN(p.created_at) AS firstAt
+     FROM projects p WHERE ${HUMANS} GROUP BY p.mode`,
+  ).all()) out.set(r.mode, { ...r, runs: 0, costUsd: 0 });
+
+  for (const r of db.prepare(
+    `SELECT p.mode AS mode, COUNT(DISTINCT r.id) AS runs,
+            COALESCE(SUM(m.cost_usd), 0) AS costUsd
+     FROM runs r
+     JOIN projects p ON p.id = r.project_id
+     LEFT JOIN run_model_usage m ON m.run_id = r.id
+     WHERE ${HUMANS} GROUP BY p.mode`,
+  ).all()) {
+    const e = out.get(r.mode) || { mode: r.mode, projects: 0, users: 0, firstAt: null };
+    out.set(r.mode, { ...e, runs: r.runs, costUsd: r.costUsd });
+  }
+  return [...out.values()];
+}
+
 export function listRunsForProject(projectId) {
   validateProjectId(projectId);
   return db.prepare('SELECT id FROM runs WHERE project_id = ? ORDER BY created_at DESC').all(projectId);

package/server/projects/viewpoint-store.js

@@ -30,9 +30,27 @@ function sanitizeViewpoint(raw, userId) {
   } : null;
   if (camera && Object.values(camera).some(v => v === null)) return null;
   const str = (v, n) => (typeof v === 'string' && v.length <= n ? v : null);
+  /**
+   * 设备档（2026-08-28 移动端第二轮）。**浏览器判好了报上来**，这边只验不算 ——
+   * 真屏幕多大、是不是手指，只有浏览器知道；服务端手里只有相机矩形和缩放，
+   * 反推屏幕要除以缩放，而且分不清「390 宽的手机」和「拖窄了的桌面窗口」。
+   * 认不出的档一律当桌面：宁可给手机用户一份桌面版式（能用，只是要缩放），
+   * 也别给桌面用户一份 342 宽的窄条（那是坏的）。
+   */
+  const dc = raw.device && typeof raw.device === 'object' ? raw.device : null;
+  const dw = num(dc?.w, 200, 8000); const dh = num(dc?.h, 200, 8000);
+  // ⚠️ 夹持在这儿是错的判法：一个夹出来的 8000 会变成 8000 宽的版式建议。
+  // 尺寸不在真实屏幕的范围里就**整个丢掉 device**，退回相机×缩放那条老路。
+  const device = (dc && dw !== null && dh !== null && dw === Number(dc.w) && dh === Number(dc.h)) ? {
+    class: (dc.class === 'phone' || dc.class === 'tablet') ? dc.class : 'desktop',
+    w: dw, h: dh,
+    dpr: num(dc.dpr, 0.5, 8),
+    coarse: !!dc.coarse,
+  } : null;
   return {
     userId: userId || null,
     camera,
+    device,
     zoom: num(raw.zoom, 0.01, 100),
     layer: str(raw.layer, 300) || '',
     openWindow: str(raw.openWindow, 300),
@@ -56,18 +74,32 @@ export function getViewpoint(pid) {
   return v;
 }
 
+/** 档位的人话（注入和工具共用一份措辞；桌面不说 —— 那是默认情况，说了是噪音） */
+export function describeDevice(v) {
+  const d = v?.device;
+  if (!d || d.class === 'desktop') return null;
+  const name = d.class === 'phone' ? '手机' : '平板';
+  return `${name}（屏幕 ${d.w}x${d.h}px，触屏）`;
+}
+
 /** 一行人话（注入/工具共用一份措辞）。rects 可选：给了就报视口里有什么 */
 export function describeViewpoint(v, rects = null) {
   if (!v) return null;
   const bits = [];
+  const dev = describeDevice(v);
+  if (dev) bits.push(`用的是${dev}`);
   if (v.layer) bits.push(`在文件夹「${v.layer}」里`);
   if (v.camera) {
     bits.push(`视口 (${Math.round(v.camera.x)},${Math.round(v.camera.y)}) ${Math.round(v.camera.w)}x${Math.round(v.camera.h)}${v.zoom ? ` 缩放 ${Number(v.zoom).toFixed(2)}` : ''}`);
     if (rects) {
       const c = v.camera;
-      const inside = rects.filter(r => !(r.x + r.w < c.x || r.x > c.x + c.w || r.y + r.h < c.y || r.y > c.y + c.h)).map(r => r.id);
-      if (inside.length) bits.push(`视口里有 ${inside.length} 件：${inside.slice(0, 10).join('、')}${inside.length > 10 ? ' 等' : ''}`);
-      else bits.push('视口里是空地');
+      const inside = rects.filter(r => !(r.x + r.w < c.x || r.x > c.x + c.w || r.y + r.h < c.y || r.y > c.y + c.h));
+      // 带坐标和占位（08-27 用户提）：agent 摆放要知道视口里谁占了哪，不该再专门调工具去问
+      if (inside.length) {
+        bits.push(`视口里 ${inside.length} 件（id@(x,y)宽x高）：${inside.slice(0, 12)
+          .map(r => `${r.id}@(${Math.round(r.x)},${Math.round(r.y)})${Math.round(r.w)}x${Math.round(r.h)}`)
+          .join('、')}${inside.length > 12 ? ' 等' : ''}`);
+      } else bits.push('视口里是空地');
     }
   }
   if (v.openWindow) bits.push(`开着窗：${v.openWindow}${v.openPage ? `（${v.openPage}）` : ''}`);

package/server/projects/workspace-slots.js

@@ -0,0 +1,30 @@
+/**
+ * projects/workspace-slots.js —— 角色位铺装（2026-08-28 建；08-29 收成一个位）
+ *
+ * 预注册的角色子代理定义（rp-role）**必须在会话启动前就在盘上**：会话中途写入的
+ * agent 定义只有当时活着的那个 CLI 进程认得，换进程后永久 not found（08-28 三场
+ * 真会话勘定，机制见 engine/agent/cast.js）。所以铺装挂在 ensureProjectWorkspace 里，
+ * 跟着每次 ensure 走。
+ *
+ * 内容以代码为准：教义升级后重启即生效，也顺手把模型对定义体的手改抹平
+ * （判据不建在模型可写的东西上 —— 派发闸照读文件核 tools，这里保证文件是正版）。
+ *
+ * 退役的旧位（rp-actor / rp-narrator）在这里**删文件**：留着的话老名字仍然派得出去，
+ * 派出来的还是旧分工（写场面的那支笔已经收回主持人手里了）。
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { ROLE_SLOT, RETIRED_SLOTS, slotAgentFile } from '../engine/agent/cast.js';
+import { MCP_SERVER_NAME } from '../engine/mcp/server-name.js';
+
+export async function ensureActorSlots(root) {
+  const dir = path.join(root, '.claude', 'agents');
+  const file = path.join(dir, `${ROLE_SLOT}.md`);
+  const want = slotAgentFile(MCP_SERVER_NAME);
+  let have = null;
+  try { have = await fs.readFile(file, 'utf8'); } catch { /* 还没有 */ }
+  if (have !== want) await fs.writeFile(file, want, 'utf8');
+  for (const old of RETIRED_SLOTS) {
+    try { await fs.unlink(path.join(dir, `${old}.md`)); } catch { /* 本来就没有 */ }
+  }
+}

package/server/projects/workspace-templates.js

@@ -54,3 +54,32 @@ export const DEFAULT_CLAUDE_MD = `# 项目档案
 ## 用户习惯
 （称呼、语气、工作方式偏好。）
 `;
+
+// rp（演出）项目的档案模板（2026-08-28；08-30 随角色子代理停用改口径）。
+// ⚠️ 原注：这份文件**每个角色子代理也强制吃**（项目 CLAUDE.md 进所有子代理上下文，
+// omitClaudeMd 透不过去 —— 08-26 实测）。08-30 起主 agent 代演全场，暂时没有子代理
+// 在读它，但这条约束等角色回来还成立，别按"只有一个读者"重排栏目。
+// 详细设定别塞 —— 放世界书文件按需 grep，这份是每轮都重发的常驻开销。
+export const DEFAULT_CLAUDE_MD_RP = `# 演出档案
+
+这份文件每次会话都完整进入 agent 的上下文。放**定了就不常变**的东西；
+会生长的记忆 agent 自己记在 记忆/ 里。详细设定放世界书文件（用到时 grep），
+别塞进这里 —— 这份是每轮都重发的常驻开销。改硬约束要经用户点头。
+
+## 世界观锚
+（一句话定调：什么世界、什么时代、什么基调。例：低魔剑与魔法，冒险者公会体系。
+从酒馆世界书搬来的常驻条目也放这，十条以内 —— 其余降级成触发文件。）
+
+## 台面规矩
+（这一场怎么玩：想跟谁演（一对一 / 一群人）/ 难度档（爽·写实·严酷）/
+代笔档（全代入·大纲）/ 骰子规则 / 文风与叙事禁令 / 禁区题材。）
+
+## 人物
+（在场人物一览：每人三行核心 —— 是谁、什么关系、绝不做什么。这里是名录；
+每个人完整的人设在 角色/<名>/角色卡.md（cast_role 写的那张），写他的话之前先读。）
+
+## 称呼与习惯
+（用户扮演谁、怎么称呼；语气与节奏偏好。）
+`;
+// ⚠️ 上面四节的节名是「演出档案骨架」的唯一真相 —— blackboard-rp SKILL 的酒馆导入
+// 落点表按同一套节名指路（08-28 对账：此前两处各写一套骨架，字段对不上）。改节名两处同改。

package/server/projects/workspace.js

@@ -42,8 +42,9 @@ import { spawn } from 'child_process';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { mutex } from 'async-mutex-lite';
-import { validateProjectId } from './store.js';
+import { validateProjectId, getProject } from './store.js';
 import { resolveModelContextWindow } from '../engine/agent/model-context.js';
+import { ensureActorSlots } from './workspace-slots.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -87,7 +88,7 @@ export function validateSessionId(sid) {
 }
 
 import {
-  DEFAULT_GITIGNORE, DEFAULT_CLAUDE_MD,
+  DEFAULT_GITIGNORE, DEFAULT_CLAUDE_MD, DEFAULT_CLAUDE_MD_RP,
 } from './workspace-templates.js';
 import { migrateMemoryLayout } from './memory-migration.js';
 
@@ -219,16 +220,11 @@ export function getSessionMetaDir(projectId, sessionId) {
 // ── ensure ──
 
 /**
- * 创建项目工作区（幂等）。完成后保证：
- *   - .claude/{CLAUDE.md, settings.json} 模板写入（仅不存在时）
- *   - .claude/{skills, agents, agent-memory} 目录存在
- *   - assets/ 存在、.gitignore 写入
- *   - 旧的三层结构（tasks/ + per-session 沙盒）已扁平化
- *   - .git 存在（项目级历史；扁平化前是 per-session 的）
- *
- * 扁平化跟着 ensure 走而不是单独一次性脚本：跟 removeRootLegacyArtifacts 同一个
- * 范式 —— 幂等、按项目惰性触发、跑过一次之后是 no-op。这样线上不需要停机窗口，
- * 也不存在"迁移脚本漏了哪个项目"。
+ * 创建项目工作区（幂等）。完成后保证：.claude/{CLAUDE.md, settings.json} 模板
+ * （仅不存在时）、.claude/{skills, agents, agent-memory} 与 assets/ 目录、演员位
+ * 定义、.gitignore、旧三层结构已扁平化、.git 存在（项目级历史）。
+ * 扁平化跟着 ensure 走而不是一次性脚本：幂等、按项目惰性触发、跑过即 no-op ——
+ * 线上不需要停机窗口，也不存在"迁移脚本漏了哪个项目"。
  */
 export async function ensureProjectWorkspace(projectId) {
   await removeRootLegacyArtifacts(projectId);
@@ -239,16 +235,19 @@ export async function ensureProjectWorkspace(projectId) {
   await fs.mkdir(path.join(root, '.claude', 'agent-memory'), { recursive: true });
   await fs.mkdir(path.join(root, 'assets'), { recursive: true });
 
+  // 演员位（2026-08-28 重构）：预注册 RP 子代理定义，必须先于任何会话在盘上（拆件见文件）
+  await ensureActorSlots(root);
+
   // .gitignore 每次比对而不是"不存在才写"：扁平化新增了 .claude/projects/ 和
   // .nd/ 两条，老项目的文件里没有，不补的话 SDK 转录会被 commit 进项目历史。
   await ensureGitignore(path.join(root, '.gitignore'));
-  // 记忆体系改版迁移（2026-08-24，幂等：源不在了就什么都不做）——
-  // CLAUDE.md 从 .claude/ 挪到工作区根（画布可见，SDK 两处都读、根优先级同级），
-  // 老的偏好/风格档案并进去，SDK auto-memory 的存量从 .claude/agent-memory/auto
-  // 搬到画布可见的 记忆/。三步全是"搬走后源删除"，跑几遍结果一样。
+  // 记忆体系改版迁移（2026-08-24，幂等：源不在了就什么都不做；三步全是"搬走后源删除"）
+  // —— CLAUDE.md 挪工作区根、旧偏好/风格档案并入、auto-memory 存量搬 记忆/。细节见函数文档。
   await migrateMemoryLayout(root, { fileExists });
   if (!(await fileExists(path.join(root, 'CLAUDE.md')))) {
-    await fs.writeFile(path.join(root, 'CLAUDE.md'), DEFAULT_CLAUDE_MD, 'utf8');
+    // rp 项目的档案按"戏"设栏（templates 注释）；已有 CLAUDE.md 的一字不动，用户内容优先于模板换代
+    const isRp = (getProject(projectId)?.mode || 'design') === 'rp';
+    await fs.writeFile(path.join(root, 'CLAUDE.md'), isRp ? DEFAULT_CLAUDE_MD_RP : DEFAULT_CLAUDE_MD, 'utf8');
   }
   // settings.json：每次 merge defaults 让代码层 default 升级时现存 project 自动跟上
   // （用户字段优先，缺失的 NoDesign default 字段补进去）

package/server/runtime/capabilities.js

@@ -17,6 +17,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { isAvailable as rembgAvailable, REMBG_SETUP_HINT } from '../engine/mcp/tools/helpers/rembg.js';
+// 盒子开没开机只有一个判据 —— h3box-ssh.localBoxEnabled。这里曾经自己写了一遍
+// `=== 'on'`，跟那边 `!== 'off'`（默认开）的默认值正好相反，同一个变量两套读法。
+import { localBoxEnabled } from '../engine/mcp/tools/h3box-ssh.js';
 
 const isWin = process.platform === 'win32';
 
@@ -96,8 +99,9 @@ export const CAPABILITY_DEFS = Object.freeze([
     } },
   { id: 'localBox', kind: 'service', level: 'feature', label: '本地 GPU 盒子（paint_still / roll_film）', uses: '自部署生图 / 文生视频',
     fix: 'NODESIGN_LOCAL_BOX=on + NODESIGN_H3BOX_SSH（站主自己的 5090 盒子；一般用户用不上）',
-    probe: () => (process.env.NODESIGN_LOCAL_BOX === 'on' && process.env.NODESIGN_H3BOX_SSH
-      ? { available: true, detail: process.env.NODESIGN_H3BOX_SSH } : { available: false, detail: process.env.NODESIGN_LOCAL_BOX === 'on' ? 'NODESIGN_H3BOX_SSH 为空' : 'NODESIGN_LOCAL_BOX 未开' }) },
+    probe: () => (localBoxEnabled() && process.env.NODESIGN_H3BOX_SSH
+      ? { available: true, detail: process.env.NODESIGN_H3BOX_SSH }
+      : { available: false, detail: !localBoxEnabled() ? '站主标记为关机（NODESIGN_LOCAL_BOX=off）' : 'NODESIGN_H3BOX_SSH 为空' }) },
 ]);
 
 function bin(name, extra = []) {