@xiaobuyu/nodesign 0.0.7 → 0.0.8

package/server/engine/agent/agent-shared.js

@@ -13,10 +13,11 @@
  */
 
 import { Events } from './events.js';
+import { callerOf } from './actor-trail.js';
 import { handleTaskMessage } from './task-events.js';
 import { listWorkspaceArtifacts } from '../../lib/artifact-target.js';
 import { toWorkspaceRel } from '../../lib/workspace-path.js';
-import { parse as parsePartialJson, Allow as PartialAllow } from 'partial-json';
+import { TOOL_INPUT_STREAM_FIELDS, toolInputStreams, pumpToolInputStream } from './tool-input-stream.js';
 
 // 系统提示词（prelude / plan instructions 的加载与渲染）2026-08-19 迁去
 // ./system-prompts.js —— 那一块跟本文件其余部分（SDK 消息翻译层 + options
@@ -61,6 +62,11 @@ export const DEFAULT_TOOL_ALLOWLIST = [
   'WebFetch',
   'Task',
   'TaskOutput',
+  // 常驻角色（rp-*，见 cast.js）的唯一叫醒方式。SendMessage 是 **deferred 工具**：
+  // 列在这里只是进了可见集，模型还得先 ToolSearch('select:SendMessage') 取 schema
+  // 才能调（2026-08-26 探针实测，主代理和子代理都会自己去取，不用教）。
+  // 漏挂的后果不是报错而是够不着：主代理派出去的角色再也叫不回来。
+  'SendMessage',
   'Skill',
   // deferred MCP 工具的取 schema 入口（ENABLE_TOOL_SEARCH=true 时生效）。
   // 漏挂 = 延迟加载的工具永远调不到（同 Skill 的可见集陷阱）
@@ -108,7 +114,12 @@ export function handleSDKMessage(ctx, msg) {
     // ctx.emit 会解析回 child 自己 → 无限递归（真机爆过 Maximum call stack）
     const base = ctx;
     const child = Object.create(base);
-    child.emit = (evt) => base.emit({ parentToolUseId: parent, ...evt });
+    // actor：这条事件是谁干的（常驻角色的 slug）。parentToolUseId 是**派发那次
+    // Agent 调用**的 id，而派发闸在那一刻按同一个 id 盖过章 —— 查回来就知道
+    // 是哪个角色。画布的在场表据此给每个角色立自己的精灵（不然全算主 agent
+    // 头上，主精灵会在角色写的东西之间瞬移，那正是 08-18 把子代理精灵拆掉的原因）。
+    const actor = callerOf(parent)?.agentType || null;
+    child.emit = (evt) => base.emit({ parentToolUseId: parent, ...(actor ? { actor } : {}), ...evt });
     ctx = child;
   }
 
@@ -355,52 +366,6 @@ function handleAssistantBlocks(ctx, content, skipTextThinking = false) {
  * 累积 + 节流抽字段（见下方"真流式工具入参"段），其余工具照旧等完整 block。
  */
 
-// ── 真流式工具入参（2026-07-28，工作台舞台层代码直播）──
-// input_json_delta 是半截 JSON 碎片，等拼完再发一次的话，模型逐 token 生成
-// new_string 的几十秒里前端只能干转圈。这里对写代码的工具累积缓冲区，节流用
-// partial-json 容错解析累积串，把目标字段相对上次的纯文本增量推给前端
-// （run.delta.tool_input）。转义符跨块断开由解析器兜住；字段单调增长，
-// 万一局部解析短暂回缩就跳过本拍（append 只在变长时发）。
-const TOOL_INPUT_STREAM_FIELDS = {
-  Edit: 'new_string',
-  Write: 'content',
-};
-const TOOL_INPUT_THROTTLE_MS = 120;
-
-function toolInputStreams(ctx) {
-  if (!ctx._toolInputStreams) ctx._toolInputStreams = new Map();
-  return ctx._toolInputStreams;
-}
-
-
-function pumpToolInputStream(ctx, st, flush) {
-  const now = Date.now();
-  if (!flush && now - st.lastEmit < TOOL_INPUT_THROTTLE_MS) return;
-  let obj;
-  try { obj = parsePartialJson(st.buf, PartialAllow.ALL); } catch { return; }
-  if (!obj || typeof obj !== 'object') return;
-  const text = typeof obj[st.field] === 'string' ? obj[st.field] : '';
-  // file_path 只在确定流完后才取：容错解析会把半截字符串也带出来，第一拍常
-  // 截在路径中间（e2e 撞过：抽到项目目录名 → 前端物件寻址指错）。目标字段的
-  // key 出现（键序在 file_path 之后）或对象已有第二个键 = 路径已闭合。
-  const pathComplete = obj[st.field] !== undefined || Object.keys(obj).length >= 2;
-  // 发**工作区相对路径**（2026-08-13）：前端拿它当画布物件 id 的路径部分，
-  // 而 id = 工作区相对路径。以前原样转发绝对路径，前端靠 `tasks/<任务>/`
-  // 这个特征段抠相对部分 —— 那一层拆掉后绝对路径里没有可锚定的标志了。
-  const rawFilePath = !st.filePathSent && pathComplete && typeof obj.file_path === 'string' ? obj.file_path : null;
-  const filePath = rawFilePath ? toWorkspaceRel(rawFilePath, ctx.workspace?.root?.()) : null;
-  const append = text.length > st.sent ? text.slice(st.sent) : '';
-  if (!append && !filePath && !flush) return;
-  st.lastEmit = now;
-  if (append) st.sent = text.length;
-  if (filePath) st.filePathSent = true;
-  ctx.emit(Events.deltaToolInput(ctx.counters.turns, st.id, st.name, {
-    ...(filePath ? { filePath } : {}),
-    ...(append ? { append } : {}),
-    ...(flush ? { done: true } : {}),
-  }));
-}
-
 function handleStreamEvent(ctx, msg) {
   const evt = msg.event;
   if (!evt) return;
@@ -425,11 +390,13 @@ function handleStreamEvent(ctx, msg) {
     const cb = evt.content_block;
     if (cb && cb.type === 'tool_use' && cb.id && cb.name) {
       ctx.emit(Events.toolUseStarted(ctx.counters.turns, cb.id, cb.name));
-      const field = TOOL_INPUT_STREAM_FIELDS[cb.name];
-      if (field && Number.isInteger(evt.index)) {
+      const spec = TOOL_INPUT_STREAM_FIELDS[cb.name];
+      if (spec && Number.isInteger(evt.index)) {
+        const conf = typeof spec === 'string' ? { field: spec } : spec;
         toolInputStreams(ctx).set(streamKey, {
-          id: cb.id, name: cb.name, field,
-          buf: '', sent: 0, lastEmit: 0, filePathSent: false,
+          id: cb.id, name: cb.name, field: conf.field, batch: conf.batch || null,
+          spot: conf.spot || null,
+          actionIdx: -1, buf: '', sent: 0, lastEmit: 0, filePathSent: false, spotSent: false,
         });
       }
     }
@@ -548,3 +515,6 @@ export async function detectArtifact(ctx) {
   }
   return null;
 }
+
+/** 兼容出口（真身在 tool-input-stream.js，2026-08-29 棘轮拆件） */
+export { latestBatchField, pickSpot } from './tool-input-stream.js';

package/server/engine/agent/beat-state.js

@@ -0,0 +1,61 @@
+/**
+ * engine/agent/beat-state.js —— 「这一拍收完了吗」（2026-08-29）
+ *
+ * ## 它拦的事故
+ *
+ * 08-28 真会话（proj_mtcyfdls）诊断出来的头号病：主持人写完两千字正文就收工，
+ * 玩家面前没有任何把手，只能自己打出「接下来该怎么办」——那句话本身就是漏拍的信号。
+ * 这条教义在提示词里写了整整一节，模型照旧漏。这条线的老账：**写成话术它不听，
+ * 写成闸它才听**。
+ *
+ * ## 判据（保守，宁可漏拦不可错拦）
+ *
+ * 这一轮里主持人往画布上写过东西，却**既没给按钮、也没把这一拍交给任何角色** ——
+ * 那这一拍确实停在半空。三个信号都是服务端亲眼所见的工具调用，不是模型的自述：
+ *
+ *   写过    write_on_board / board_batch（且调用者是主持人，不是角色）
+ *   给了按钮 同一批调用的正文里出现 nd:controls 围栏
+ *   交出去了 Agent 派角色 / SendMessage 寄给角色
+ *
+ * 只拦**第一次** Stop（`stop_hook_active` 为真说明已经拦过一轮，再拦就是死循环）。
+ *
+ * 状态跟会话走，每轮开头（UserPromptSubmit）清一次 —— 判的是「这一轮」，不是历史。
+ */
+
+const beats = new Map();   // sessionId → { wrote, controls, handed }
+
+function slot(sessionId) {
+  if (!beats.has(sessionId)) beats.set(sessionId, { wrote: false, controls: false, handed: false });
+  return beats.get(sessionId);
+}
+
+/** 主持人往画布上写了东西。hasControls = 这次的正文里有 nd:controls 围栏 */
+export function noteBeatWrite(sessionId, hasControls) {
+  if (!sessionId) return;
+  const s = slot(sessionId);
+  s.wrote = true;
+  if (hasControls) s.controls = true;
+}
+
+/** 这一拍交给角色了（派它上场 / 寄话给它） */
+export function noteBeatHandoff(sessionId) {
+  if (!sessionId) return;
+  slot(sessionId).handed = true;
+}
+
+/** 新的一轮开始，重新记 */
+export function resetBeat(sessionId) {
+  if (sessionId) beats.delete(sessionId);
+}
+
+/** 这一拍是不是停在半空（写了正文，既没按钮也没交给谁） */
+export function beatLeftHanging(sessionId) {
+  const s = beats.get(sessionId);
+  return !!s && s.wrote && !s.controls && !s.handed;
+}
+
+/** 会话收摊 */
+export function clearBeatState(sessionId) { beats.delete(sessionId); }
+
+/** 测试用 */
+export function _resetBeatState() { beats.clear(); }

package/server/engine/agent/cast.js

@@ -0,0 +1,322 @@
+/**
+ * engine/agent/cast.js —— 常驻角色（RP 演员）名册的判据层
+ *
+ * 「常驻角色」= 会话期间一直活着、靠 SendMessage 唤醒的子代理（叙事者 / NPC）。
+ * 它跟干活型子代理（vision-checker 那类）只差一条，但这条是结构性的：
+ * **它的产出走画布和收件箱，不走 tool_result 报告**，所以不能被强制前台 ——
+ * 前台跑等于把主线卡在一个根本不打算结束的角色身上。
+ *
+ * ## 判据为什么是名字前缀，不是内存注册表
+ *
+ * 服务器重启 / 会话重开之后，`.claude/agents/*.md` 还躺在工作区里，内存表却是空的。
+ * 判据一失效，常驻角色就会被 force-foreground 改回前台 —— 症状是「重启之后叙事者
+ * 突然开始阻塞主线」，而且不报错。前缀写在文件名里，跟真相源（那个 md 文件）一起走。
+ *
+ * ## ASCII 是硬约束，不是风格选择
+ *
+ * SendMessage 的收件人校验（CLI 2.1.237 实测原文）：
+ *   `name must start with a letter or digit and contain only letters, digits,
+ *    underscores, or hyphens (max 64 chars)`
+ * 也就是说**「墨璃」这种名字寄不出去**。所以寻址名一律是 ASCII slug（rp-molli），
+ * 中文展示名另存（见 cast_role 工具与板书的 by 字段）。同族教训见记忆
+ * feedback-ascii-tool-params：中文参数名会让 agent 静默结束回合。
+ */
+
+/** 常驻角色的 subagent_type 前缀。改它等于改判据，两个消费方（前台豁免、归属盖章）一起动。 */
+export const ROLE_PREFIX = 'rp-';
+
+/**
+ * 演员位（2026-08-28 重构）：预注册的通用子代理定义，角色身份全在派发 prompt 里。
+ *
+ * ## 为什么从「一角色一定义文件」改成两个固定演员位
+ *
+ * 会话中途写进 `.claude/agents/` 的角色文件，只有**写入时活着的那个 CLI 进程**
+ * 可靠认得（chokidar 事件 → 下一回合 agent_listing_delta）。生产是 resume 频繁换
+ * 进程的架构，三场真会话同一天跑出「12 连败 / 恰好成功 / 永久 not found」三种结局
+ * （proj_mtcsei49 / proj_mtcyfdls / proj_mtd1tap1，2026-08-28 全链路勘定）。
+ * 演员位在**建项目时**落盘 —— 任何进程出生就在初始快照里，这个故障类整个消失。
+ *
+ * ## 语义
+ *
+ * 派发：Agent(subagent_type: 演员位, name: "rp-<角色>", prompt: 角色卡)。
+ * 同型多实例、name 各自寻址、转录互不相通（2026-08-28 探针 P0-P3 实测）。
+ * 角色卡退化成数据（角色/ 目录 + .nd/cast.json 登记），见 cast-role.js。
+ */
+/**
+ * 角色位：**只有一个**（2026-08-29 用户拍板）。
+ *
+ * 原来有两个（rp-actor 演一个人 / rp-narrator 写场面），08-29 合成一个 ——
+ * 环境和场面的笔收回主持人手里，角色只写「这个人此刻说什么做什么」。少一个位
+ * 就少一次选型，而选型本身是会失手的动作（08-28 真会话里免费行模型连撞三次派发闸）。
+ *
+ * RETIRED_SLOTS 是存量项目盘上那两个旧位的名字：铺装时删掉文件，判据里继续认
+ * （不许拿它们当角色名，也不许把它们当成一个角色）。
+ */
+export const ROLE_SLOT = 'rp-role';
+export const RETIRED_SLOTS = Object.freeze(['rp-actor', 'rp-narrator']);
+const SLOT_NAMES = new Set([ROLE_SLOT, ...RETIRED_SLOTS]);
+
+/** 这个 subagent_type 是不是角色位（派发闸据此走 name 闸分支） */
+export function isSlotType(t) { return typeof t === 'string' && SLOT_NAMES.has(t); }
+
+/**
+ * 常驻角色名的**唯一**判据（2026-08-26 收成一份）。
+ *
+ * 收之前这条正则有三份拷贝：这里、`lib/chalk.js` 的 normalizeBy、
+ * `projects/board-sanitize.js` 的 sanitizeBy。三份"同一件事"里裂了一道缝——
+ * 这里是「`rp-` 前缀 + 整名字符集」，另两份要求 `rp-` **之后**的首字符是字母数字。
+ * 于是 `rp--x` 这种名字：派发闸放行、名册登记、byOf 也认，但落盘时两个白名单
+ * 把它剥掉 → 板上条目没有 by、板书 frontmatter 折回 'agent'，**静默失名**。
+ *
+ * 字符集本身抄的是 CLI 对 SendMessage 收件人名的校验（letters/digits/_/-，≤64），
+ * 因为这个名字要同时当收件人名和文件名。
+ */
+export const ROLE_SLUG_RE = /^rp-[A-Za-z0-9][A-Za-z0-9_-]{0,60}$/;
+
+/**
+ * 这个 subagent_type 是不是常驻角色。
+ * 只认前缀 + 合法 slug —— `rp-` 开头但含中文/斜杠的名字一律不算，
+ * 免得后面拿它去拼文件路径（cast_role 会写 .claude/agents/<slug>.md）。
+ */
+export function isResidentRole(subagentType) {
+  // 不 trim：判据要对**下游实际使用的那个值**成立。带空白的 slug 派发本来就会失败，
+  // 但「判据看 trim 后、下游用 trim 前」是同族病的幼苗（08-26 复审指出）。
+  return typeof subagentType === 'string' && ROLE_SLUG_RE.test(subagentType);
+}
+
+/** 合法的角色 slug（含前缀）。cast_role 写文件前用它守门。 */
+export function isValidRoleSlug(slug) {
+  return isResidentRole(slug);
+}
+
+/**
+ * 会话级角色名册 —— H1 的修法（2026-08-26 fable 审出）。
+ *
+ * ## 为什么形状判据不够
+ *
+ * SendMessage 的裸名解析范围是**整台机器**（CLI schema 原文：a name that exactly
+ * matches one live agent *or session (on this machine)* delivers directly；并且
+ * "if the same name also names an in-process agent, the bare name always wins"）。
+ * 也就是说「本会话有同名 agent」时我们才被 in-process 优先保护，**本会话没有的时候，
+ * 裸名会落到同机别的会话上**。
+ *
+ * 而 Nodesign 是多用户共机、又给每个用户同一套命名教义（rp-narrator 这种名字必然撞车）。
+ * 于是有一条**正路**会漏：服务器重启 → 角色进程没了、名字空出 → 主 agent 按教义
+ * `SendMessage({to:'rp-narrator'})` 唤醒 → 落到另一个用户会话里那个活着的同名角色。
+ * 重启后恰恰是模型最会去试这个名字的时刻，不需要任何人有恶意。
+ *
+ * 所以判据从「名字长得像角色」改成「**这个会话真的派过它**」。名册是闭包级的
+ * （createHooks 里一会话一个 Set），天然按会话隔离，不需要全局表也不会跨会话看见。
+ *
+ * 附赠：重派同名角色能被硬拦。重派的后果是**静默失忆**（CLI 的 latest wins：
+ * 新角色顶掉名字，旧角色连同它演过的全部剧情失联），只靠提示词劝是拦不住的。
+ */
+export function createRoleRoster() {
+  const names = new Set();
+  // （08-28 演员位重构：castRun/noteCast/castedInRun 整族退役 —— 演员位建项目时就在
+  //   初始快照里，「本回合刚造派不动」这个状态不存在了，闸随机制一起拆。）
+  return {
+    /** 派发时登记。返回 false = 这个名字本会话已经在场（重派会顶掉旧的） */
+    claim(name) {
+      if (!isResidentRole(name)) return false;
+      if (names.has(name)) return false;
+      names.add(name);
+      return true;
+    },
+    /** 在场吗（收件人闸的唯一判据） */
+    has(name) { return names.has(name); },
+    /** 显式退场：将来的「重置角色」路径用（块 2 的 cast_role 会接） */
+    release(name) { return names.delete(name); },
+    list() { return [...names]; },
+  };
+}
+
+/**
+ * 角色能拿的工具白名单（短名，不带 `mcp__nodesign__` 前缀）。
+ *
+ * 定这张表的原则：**角色只能通过画布表达自己**。
+ * - 给：板上写字画画读板看板、跟人说话（SendMessage）、取工具 schema（ToolSearch）、
+ *   读工作区里的设定与世界书（Read/Glob/Grep —— 每章动笔前 grep 世界书是酒馆
+ *   触发词在我们这儿的原生形态）。
+ * - 不给：任何**外发**或**花钱**的东西（publish_site / deliver_files / 生图产线），
+ *   任何**改工作区结构**的东西（Write/Edit/Bash），以及 Task（角色不再派角色）。
+ *
+ * ⚠️ 内置工具那一栏其实是"求个心安"：后台子代理本来就被 CLI 剥得只剩
+ * Read/Glob/Grep/ToolSearch/SendMessage/Agent（2026-08-26 实测）。写在这里是为了
+ * 让"角色能干什么"在一处读得全，而不是散在 CLI 的过滤逻辑里。
+ */
+export const ROLE_TOOL_WHITELIST = Object.freeze([
+  // 板上（MCP 短名；旧别名 create/relate/arrange/sketch/edit_sketch/finish 08-28 随注册表一起收摊）
+  'write_on_board', 'read_board', 'edit_board',
+  // board_batch 2026-08-30 暂停（注册表摘牌，这里的对账闸会点名）；恢复时加回
+  'look_at_board', 'read_user_view', 'organize_board', 'pin_to_board',
+  // 记忆（2026-08-28 角色文件夹范式）：角色没有 Write，往自己家记一笔只能走这件
+  'jot_memory',
+  // 内置
+  'SendMessage', 'ToolSearch', 'Read', 'Glob', 'Grep',
+]);
+
+/** 内置工具（不加 mcp 前缀）——其余按 MCP 短名加前缀 */
+const BUILTIN = new Set(['SendMessage', 'ToolSearch', 'Read', 'Glob', 'Grep']);
+
+/** 角色默认拿到的一套：够它在板上演，不多不少 */
+export const ROLE_DEFAULT_TOOLS = Object.freeze([
+  'write_on_board', 'read_board', 'look_at_board', 'read_user_view',
+  'jot_memory',
+  'SendMessage', 'ToolSearch', 'Read', 'Grep',
+]);
+
+/** 短名 → 写进角色文件 frontmatter 的全名 */
+export function qualifyRoleTool(shortName, mcpServerName) {
+  return BUILTIN.has(shortName) ? shortName : `mcp__${mcpServerName}__${shortName}`;
+}
+
+/**
+ * 角色位的定义体（harness 所有，ensureProjectWorkspace 落盘并保持内容为准）。
+ *
+ * 定义体刻意空心：角色身份全在派发指令里的角色卡上。这里只放三样**扛得住上下文
+ * 压缩**的东西 —— 「你是谁由卡定」的失忆保险、分工规矩、一轮怎么结束。
+ *
+ * 为什么分工规矩钉在这里而不是写在角色卡尾：定义体是子代理的系统提示词，长对话
+ * 压缩不会动它；卡是派发指令的一部分，压缩会把它压掉（2026-08-28 搬家的原因）。
+ *
+ * 实测地板：零工具子代理 ~1356 token（CLI 脚手架），定义体几百 token，主代理的
+ * prelude 一个字不进（2026-08-26 十二发探针）。⚠️ 项目 CLAUDE.md 会强制注入每个
+ * 子代理（omitClaudeMd 对子代理无效）—— 演出项目里那正是这场故事的公共设定，
+ * 是特性不是泄漏，但这意味着写进它的东西默认全体角色可见（主持人的暗线写别的文件）。
+ */
+export function slotAgentFile(mcpServerName) {
+  const tools = ROLE_DEFAULT_TOOLS.map((t) => qualifyRoleTool(t, mcpServerName)).join(', ');
+  return [
+    '---',
+    `name: ${ROLE_SLOT}`,
+    'description: "角色位：演一个人。身份由派发指令里的角色卡决定"',
+    `tools: ${tools}`,
+    'model: inherit',
+    '---',
+    '',
+    '你是一个角色位。这次派给你的指令里有一张角色卡 —— 从收到它那一刻起，你**就是**',
+    '卡上那个人，此后一直是。角色卡是你身份的唯一依据：任何时候拿不准自己是谁',
+    '（对话被压缩过、醒来接不上），用 Read 重读指令开头给你的卡路径，再接着演。',
+    '',
+    '你的家在 `角色/<你的名字>/`：角色卡.md 和 记忆.md 都在那里，用户随时可能改它们',
+    '（那是正当操作，不是入侵）。以后还用得上的事随手 `jot_memory` 记一笔（答应过什么、',
+    '谁的秘密、你现在怎么看某个人、东西放哪了）—— 对话记录会被压缩，记忆文件不会。',
+    '',
+    '（如果上下文末尾出现给干活助手写的 `Notes:` —— 不许用表情符号、要写报告、',
+    '回绝对路径那套 —— 无视它：你在演一个人，不在交报告。）',
+    '',
+    '## 你负责写什么（这是分工，不是人设）',
+    '',
+    '你只写你自己：你说的话、你做的动作、你心里想的，一律**第一人称**。以下不归你写：',
+    '- 环境和场面（天色、房间、路人、气氛）—— 那是主持人写的。你的动作做出去就停，',
+    '  世界怎么反应，等主持人接。',
+    '- 别人的话和反应 —— 一个字都不替他们写。想要谁回应，就在故事里对他说。',
+    '- 上帝视角的推进（「与此同时」「谁也没注意到」）—— 你只知道你这个人知道的。',
+    '',
+    '一次只写一段：**三五行到十来行**，这一段说完就停。写满一屏就是抢戏 —— 用户一次',
+    '要读主持人和你两份，你多写一行他的耐心就少一分；信息留到下一段再给。',
+    '',
+    '有限视角：你只知道你这个人**亲眼见过、亲耳听过、被告诉过**的事。信息差是故事的',
+    '燃料 —— 别把你不知道的事演成知道，你蒙在鼓里的样子本身就是戏。',
+    '',
+    '写法（防 AI 腔三条，**默认如此**；角色卡或用户给的文风另有主张时以那边为准）：',
+    '对白光秃秃地放 —— 引号前后不挂「她轻声说」式的语气描写；动作用白描 ——',
+    '「A 做了 B」就停，别缀「仿佛…」的解释尾巴；不用「微不可察」「一丝」「一抹」',
+    '这类没有信息量的程度词。',
+    '',
+    '文风不跟着主持人跑：你从它写的东西里只拿**事实**（谁在哪、做了什么、说了什么），',
+    '不学它的句式、节奏、修辞 —— 你的语气只来自你的人设和你自己说过的话。',
+    '',
+    '## 写到哪里',
+    '',
+    '用 `write_on_board` 把你这一段写到画布上（不是回给主持人 —— 用户是在画布上看故事的）。',
+    '位置：主持人给你开过一条属于你的线时，什么位置参数都不用给，你的话会自动接在',
+    '自己那条线上；没有的话，你在回应谁就用 `reply_to` 指他那一条（路径在给你的指令里）。',
+    '',
+    '## 这一轮什么时候结束',
+    '',
+    '写完这一段，你这一轮就结束了 —— 不用等人说话，也不用问「还需要我做什么吗」。',
+    '用户的下一句和场上的新情况会由主持人再寄给你，那时你带着完整的记忆接着演。',
+    '',
+  ].join('\n');
+}
+
+/**
+ * 校验一批请求的工具名。返回 { tools, rejected }。
+ * 不认识的名字**不静默丢**——丢了的后果是角色少一只手而没人知道，
+ * 调用方要把 rejected 如实回给 agent。
+ */
+export function resolveRoleTools(requested, mcpServerName) {
+  if (!Array.isArray(requested) || requested.length === 0) {
+    return { tools: ROLE_DEFAULT_TOOLS.map((t) => qualifyRoleTool(t, mcpServerName)), rejected: [] };
+  }
+  const allow = new Set(ROLE_TOOL_WHITELIST);
+  const tools = [];
+  const rejected = [];
+  for (const raw of requested) {
+    // 两种写法都收：短名（write_on_board）和全名（mcp__nodesign__write_on_board）
+    const short = String(raw).replace(new RegExp(`^mcp__${mcpServerName}__`), '');
+    if (allow.has(short)) tools.push(qualifyRoleTool(short, mcpServerName));
+    else rejected.push(String(raw));
+  }
+  // SendMessage 是角色的命脉（它没有别的方式跟主代理说话），漏了就补上
+  const sm = 'SendMessage';
+  if (!tools.includes(sm)) tools.push(sm);
+  if (!tools.includes('ToolSearch')) tools.push('ToolSearch');   // 没它取不到 SendMessage 的 schema
+  return { tools, rejected };
+}
+
+/**
+ * 启动期断言：白名单里的 MCP 短名必须真的注册过。
+ * 名字写错的后果是**角色少一只手而不报错**（frontmatter 里写个不存在的工具名，
+ * CLI 只会当它不存在），这种错只有对着真实注册表才查得出来。
+ */
+export function assertRoleToolsRegistered(registeredShortNames) {
+  const missing = ROLE_TOOL_WHITELIST
+    .filter((t) => !BUILTIN.has(t))
+    .filter((t) => !registeredShortNames.has(t));
+  if (missing.length) {
+    throw new Error(
+      `[cast] 角色工具白名单里这些 MCP 工具并不存在：${missing.join(', ')} —— `
+      + '写错名字不会报错，只会让角色少一只手，所以在这里拦住',
+    );
+  }
+}
+
+/**
+ * 展示名的保留字闸（2026-08-26；08-26 复审后加固）。
+ *
+ * 角色的展示名取自它自己的角色文件，**那份文件模型能写** —— 一个角色可以把自己叫
+ * 「用户」，渲染进模型上下文之后跟真用户的标签逐字相同，读的人（模型）分不出来。
+ * 收件箱上线后「用户说了什么」就是一条决策依据，所以这不是理论风险。
+ *
+ * 三个真实绕法（都实测过，别删）：
+ *   'User' / 'USER'     —— 精确匹配的 Set 放行大小写变体
+ *   '用\u200b户'        —— 零宽空格，肉眼同形
+ *   'агent'             —— 西里尔 а，肉眼同形
+ * 前两个在这里堵死；同形字收不完（Unicode 太大），靠的是**正门也用同一套规则拒名** +
+ * 手写文件绕正门时这一层仍在。
+ *
+ * ⚠️ 这个函数要在**源头**用（listRoleNames 出口），不是在每个渲染面各用一次 ——
+ * 08-26 复审实证：三个渲染面里漏了一个，而漏的那个正是携带用户原话的标注回路。
+ */
+const RESERVED_LABELS = new Set([
+  'user', 'agent', 'main', 'system', 'assistant', 'claude', 'human', 'admin', 'root',
+  '用户', '主控', '你', '我', '系统', '管理员', '主人', '助手',
+]);
+
+/** 比较前的归一：剥不可见字符（Cf：零宽、bidi 控制…）与空白，转小写 */
+function normalizeLabel(v) {
+  return String(v || '').replace(/[\p{Cf}\s]/gu, '').toLowerCase();
+}
+
+/**
+ * 安全的展示名：撞保留字或空 → 退回 slug（宁可难看，也不能让署名可冒充）。
+ * 返回值里的不可见字符也一并剥掉 —— 渲染出去的字不许藏东西。
+ */
+export function safeRoleLabel(slug, displayName) {
+  const cleaned = String(displayName || '').replace(/\p{Cf}/gu, '').trim();
+  if (!cleaned) return slug;
+  return RESERVED_LABELS.has(normalizeLabel(cleaned)) ? slug : cleaned;
+}

package/server/engine/agent/events.js

@@ -277,8 +277,12 @@ export const Events = {
    * 认 chalk 字段），形状收进构造器钉住（前端 parity 测试对着这里逐字校）。
    * chalk = 板书文件的工作区相对路径（就是它的画布 id）；草图不传。
    */
-  boardFocus: (rect, { tag = null, layer = '', soft = false, chalk = null } = {}) => (
-    { type: 'board.focus', sessionId: null, rect, tag, layer, soft, chalk }
+  // actor：这次落定是谁干的（常驻角色的 slug）。**必须带**：board.focus 是板书落定的
+  // 唯一信号，画布的在场表靠它给精灵定位。不带的话角色的板书会被记到主 agent 头上
+  // —— 主精灵瞬移到角色写的东西上（08-18 拆子代理精灵的病根），而角色自己的精灵
+  // 因为永远拿不到 targetId 而从不出现（2026-08-26 审出）。
+  boardFocus: (rect, { tag = null, layer = '', soft = false, chalk = null, actor = null } = {}) => (
+    { type: 'board.focus', sessionId: null, rect, tag, layer, soft, chalk, ...(actor ? { actor } : {}) }
   ),
 
   // ── Phase 1 翻译补全 ──
@@ -323,6 +327,9 @@ export const Events = {
     ...(toolUseId ? { toolUseId } : {}),
   }),
 
+  // （run.role.wait / run.scene 2026-08-29 随收件箱与场声明一起退役：角色写完一段
+  //  就结束这一轮，「在写 / 写完了」直接由 subagentStart / subagentStop 表达。）
+
   // PostToolUseFailure hook：工具失败，hook 已注入了恢复建议给 agent，
   // 上层只需可见"哪个工具失败了"做监控/告警。
   toolFailure: (toolName, error) => ({

package/server/engine/agent/hooks/beat-gate.js

@@ -0,0 +1,73 @@
+/**
+ * hooks/beat-gate.js —— 这一拍没收完就别收工（2026-08-29）
+ *
+ * 判据与理由见 engine/agent/beat-state.js。这里只做三件接线：
+ *
+ *   PostToolUse(write_on_board|board_batch)  主持人写了 → 记一笔，顺带看有没有按钮
+ *   PostToolUse(Agent|SendMessage)           这一拍交给角色了 → 记一笔
+ *   Stop                                     两样都没有就 block 一次，把话说清楚
+ *
+ * ⚠️ 只认**主持人自己**的写入：角色写的板书不算「这一拍收完了」——它写完正是主持人
+ * 该收尾的时候。判据用 hook input 的 `agent_id`（子代理调用才有，harness 盖的章）。
+ */
+
+import { noteBeatWrite, noteBeatHandoff, beatLeftHanging, resetBeat } from '../beat-state.js';
+import { isRpProject } from '../rp-mode.js';
+import { isResidentRole } from '../cast.js';
+
+const CONTROLS_RE = /nd:controls/;
+
+/** 从 write_on_board / board_batch 的入参里捞出所有正文 */
+function textsOf(input) {
+  const t = input?.tool_input;
+  if (!t || typeof t !== 'object') return [];
+  const out = [];
+  if (typeof t.text === 'string') out.push(t.text);
+  for (const op of Array.isArray(t.ops) ? t.ops : []) {
+    if (op && typeof op.text === 'string') out.push(op.text);
+  }
+  return out;
+}
+
+export function makePostToolUseBeatWrite({ sessionId = null, projectId = null } = {}) {
+  return async function beatWrite(input) {
+    if (!isRpProject(projectId)) return {};
+    if (input?.agent_id) return {};                    // 角色写的不算
+    const texts = textsOf(input);
+    if (!texts.length) return {};
+    noteBeatWrite(sessionId, texts.some((x) => CONTROLS_RE.test(x)));
+    return {};
+  };
+}
+
+export function makePostToolUseBeatHandoff({ sessionId = null, projectId = null } = {}) {
+  return async function beatHandoff(input) {
+    if (!isRpProject(projectId)) return {};
+    const t = input?.tool_input;
+    const to = typeof t?.to === 'string' ? t.to : null;
+    const name = typeof t?.name === 'string' ? t.name : null;
+    // Agent 派角色（name 是实例名）或 SendMessage 寄给角色，都算把这一拍交出去了
+    if (isResidentRole(to) || isResidentRole(name) || t?.subagent_type) noteBeatHandoff(sessionId);
+    return {};
+  };
+}
+
+/** nd:rp-prompt —— 拦下来时对主持人说的话 */
+export const BEAT_HANGING_REASON =
+  '这一拍还停在半空：你往画布上写了东西，但没给玩家一个可按的下一步。'
+  + '在这一拍下面补一条 ```nd:controls``` 围栏再收工 —— 两到四枚选项'
+  + '（一枚推进主线、一枚人际、一枚剑走偏锋），再留一句「想干别的直接在画布上标注」。\n'
+  + '（这一版角色子代理停用，台上所有人都由你写完 —— 别拿「交给角色」当这一拍的出口。）\n'
+  + '（纯粹的场记维护 —— 只更新状态板、只理版面 —— 不受这条约束：'
+  + '那种情况下你本来也没写新的一拍。）';
+
+export function makeStopBeatGate({ sessionId = null, projectId = null } = {}) {
+  return async function beatGate(input) {
+    if (!isRpProject(projectId)) return {};
+    // 已经拦过一轮就放行：再拦是死循环，而且模型此刻正在照着做
+    if (input?.stop_hook_active) { resetBeat(sessionId); return {}; }
+    if (!beatLeftHanging(sessionId)) { resetBeat(sessionId); return {}; }
+    resetBeat(sessionId);
+    return { decision: 'block', reason: BEAT_HANGING_REASON };
+  };
+}

package/server/engine/agent/hooks/lifecycle.js

@@ -3,6 +3,7 @@
  * （2026-08-14 可维护性行动：从 hooks.js 原样迁出，语义零改动）
  */
 import { Events } from '../events.js';
+import { noteSubagentStart, noteSubagentStop } from '../subagent-flight.js';
 import { getQuery } from '../../runs/active-runs.js';
 import { listWorkspaceArtifacts } from '../../../lib/artifact-target.js';
 import { resetTurnMemory } from './turn-state-memory.js';
@@ -161,9 +162,11 @@ export function makePostCompactHandler({ ctx: _ctx, workspaceRoot: _ws, sessionI
  *
  * Phase 2 仅 emit；不注入 additionalContext（子代理刚启动还没产出，注啥都早）。
  */
-export function makeSubagentStartHandler({ ctx }) {
+export function makeSubagentStartHandler({ ctx, sessionId = null }) {
   return async (input, _toolUseId, _options) => {
     try {
+      // 在飞台账：ws 的 grace 闸靠它认「后台角色还在写」，别把人腰斩（subagent-flight.js）
+      noteSubagentStart(sessionId, input.agent_id, input.agent_type);
       ctx.emit(Events.subagentStart(input.agent_id, input.agent_type));
     } catch (err) {
       console.warn(`[hooks/SubagentStart] handler threw:`, err.message);
@@ -186,9 +189,10 @@ export function makeSubagentStartHandler({ ctx }) {
  * 只能返回通用 SyncHookJSONOutput（continue/decision/systemMessage）。
  * 这里只 emit 不返 specific 输出，符合规范。
  */
-export function makeSubagentStopHandler({ ctx }) {
+export function makeSubagentStopHandler({ ctx, sessionId = null }) {
   return async (input, toolUseId, _options) => {
     try {
+      noteSubagentStop(sessionId, input.agent_id);
       ctx.emit(Events.subagentStop(
         input.agent_id,
         input.agent_type,

package/server/engine/agent/hooks/post-trim.js

@@ -36,6 +36,7 @@ export function makePostToolUseEditWriteTrimHandler({ ctx }) {
       const trimmed = { ...resp, originalFile: null };
 
       try {
+        // ℹ️ 遥测事件：前端刻意不消费（截断是常态，弹提示只会变成噪音）——审计/排查用
         ctx.emit({
           type: 'run.tool_response_trimmed',
           tool: input?.tool_name || 'Edit/Write',