@xiaobuyu/nodesign 0.0.6 → 0.0.8

package/server/engine/agent/subagent-flight.js

@@ -0,0 +1,73 @@
+/**
+ * engine/agent/subagent-flight.js —— 「这个会话还有后台角色在干活吗」（2026-08-28）
+ *
+ * ## 为什么需要这条路
+ *
+ * ws/index.js 的 grace 闸（07-27 建）只认 turn：用户关 tab / 切走后 turn 还在飞就
+ * 续命，等它干完再回收 SDK 进程。演员位范式造出了**第二种在飞工作** —— GM 的场务
+ * turn 几秒钟就结束，后台角色还要写好几分钟。闸不认识它，于是 08-28 泉此方场实录：
+ *
+ *   17:47:39 角色派出 → 17:48:17 GM turn 结束 → 17:49:29 grace 到期关会话
+ *   → 角色被腰斩在第三个 Read 上，板上永远没有第二拍，日志里连个 warn 都没有。
+ *
+ * 从用户视角看就是「角色不写了」。这正是 07-27 那道闸要保住的东西（"用户关 tab 时
+ * 后端应该把活干完"），只是当时在飞工作只有 turn 一种形态。
+ *
+ * ## 判据（2026-08-29 简化）
+ *
+ * **在飞 = SubagentStart 过且 SubagentStop 还没到**，就这一条。
+ *
+ * 08-29 之前它还要减掉「候场」——那时角色写完一段会挂在 await_user 上不收回合，
+ * 一个挂着的角色就能让会话永远关不掉（每个 SDK 进程 ~250MB 且 RSS 单调不减，
+ * 这台盒子 1vCPU/8G、swap=0）。新回路里角色写一段就结束这一轮，「永不收回合」这个
+ * 形态不存在了，减数也就跟着没了。
+ *
+ * 信号是 harness 在 spawn / 结束那一刻亲眼所见并盖的章，不是模型能写的东西。
+ *
+ * ## 生命周期
+ *
+ * 会话内存态，runSession 的 finally 里跟收件箱一起清。**这里不设时间上限** ——
+ * 兜底封顶在 ws/index.js 的续命次数上（一处判据一个真相源，别在两边各写一份）。
+ */
+
+import { agentNameOf } from './actor-trail.js';
+
+const flights = new Map();   // sessionId -> Map<agentId, { agentType, startedAt }>
+
+/** 子代理起飞。agentId 来自 SubagentStart hook input，harness 盖的章 */
+export function noteSubagentStart(sessionId, agentId, agentType = null) {
+  if (!sessionId || !agentId) return;
+  let m = flights.get(sessionId);
+  if (!m) { m = new Map(); flights.set(sessionId, m); }
+  m.set(agentId, { agentType, startedAt: Date.now() });
+}
+
+/** 子代理落地 */
+export function noteSubagentStop(sessionId, agentId) {
+  if (!sessionId || !agentId) return;
+  const m = flights.get(sessionId);
+  if (!m) return;
+  m.delete(agentId);
+  if (m.size === 0) flights.delete(sessionId);
+}
+
+/**
+ * 这个会话里还在飞的后台子代理。
+ *
+ * name 是实例名（角色）——翻不出来的（普通干活子代理）也照样算在飞，只是没名字。
+ *
+ * @param {string} sessionId
+ * @param {string|null} _projectId  旧签名的兼容位（候场判定退役后不再需要）
+ * @returns {Array<{ agentId, agentType, name, startedAt }>}
+ */
+export function workingSubagents(sessionId, _projectId = null) {
+  const m = flights.get(sessionId);
+  if (!m || m.size === 0) return [];
+  return [...m].map(([agentId, info]) => ({ agentId, name: agentNameOf(agentId), ...info }));
+}
+
+/** 会话收摊 */
+export function clearSessionFlights(sessionId) { flights.delete(sessionId); }
+
+/** 测试用：清空全局态 */
+export function _resetSubagentFlight() { flights.clear(); }

package/server/engine/agent/system-prompts.js

@@ -14,6 +14,7 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { DEFAULT_LOCALE } from '../../shared/locales.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -40,6 +41,13 @@ const ADULT_POLICY = {
   strict: '露骨的成人内容在这个账号档位下不写——涉及时收敛处理、用留白带过。',
 };
 
+// 界面语言的人话名（2026-08-26 i18n）。注给模型看的是「中文（zh-CN）」这种带 id 的写法：
+// 光写「中文」模型不知道对应哪个 tag，光写 tag 又不如人话直白。
+const UI_LOCALE_NAME = {
+  'zh-CN': '中文（zh-CN）',
+  en: 'English（en）',
+};
+
 /**
  * 「底线」那一节在 prelude 里有**两份并排写着**的版本，标记块框起来：
  * `nd:policy:full`（对外开放平台的完整产物政策）和 `nd:policy:min`。渲染时留一份、
@@ -51,6 +59,14 @@ const ADULT_POLICY = {
  */
 const POLICY_BLOCK = /<!-- nd:policy:(full|min):start -->\n([\s\S]*?)<!-- nd:policy:\1:end -->\n/g;
 
+/**
+ * 项目模式分区（2026-08-27）：prelude 里设计道专属的节框在 `nd:mode:design` 块里，
+ * 演出（常驻角色）专属的节框在 `nd:mode:rp` 块里，渲染时按项目模式留一族、删一族。
+ * 没框的部分是共用骨架。同一个文件里可以有**多个**同名标记块（设计道的节不连续）。
+ * 为什么是标记块不是两份 md：见 POLICY_BLOCK 注释 —— 单一真相源 + 切错当场炸。
+ */
+const MODE_BLOCK = /<!-- nd:mode:(design|rp):start -->\n([\s\S]*?)<!-- nd:mode:\1:end -->\n/g;
+
 // 加载期断言：两份都必须在。少一份说明有人编辑 prelude 时把标记删了，那时候
 // 正则会静默退化成"一份都不删"（uncensored 路径拿到完整底线）或"整节消失"。
 {
@@ -60,6 +76,23 @@ const POLICY_BLOCK = /<!-- nd:policy:(full|min):start -->\n([\s\S]*?)<!-- nd:pol
       throw new Error(`[system-prompts] nodesign-prelude.md 缺少 nd:policy:${want} 标记块 —— 提示词渲染会静默走错版本`);
     }
   }
+  const modes = [...NODESIGN_PRELUDE.matchAll(MODE_BLOCK)].map((m) => m[1]);
+  for (const want of ['design', 'rp']) {
+    if (NODESIGN_PRELUDE && !modes.includes(want)) {
+      throw new Error(`[system-prompts] nodesign-prelude.md 缺少 nd:mode:${want} 标记块 —— 模式分区渲染会静默失效`);
+    }
+  }
+}
+
+// 占位符也要断言：`.replace('{{X}}', v)` 在占位符不存在时**静默什么都不做**，
+// 于是线上会悄悄发出一份没有成人档、或者没有语言指令的提示词，不报错。
+// 标记块那套已经这么防了，占位符这两个之前漏了（08-26 补）。
+{
+  for (const ph of ['{{ADULT_POLICY}}', '{{UI_LOCALE}}']) {
+    if (NODESIGN_PRELUDE && !NODESIGN_PRELUDE.includes(ph)) {
+      throw new Error(`[system-prompts] nodesign-prelude.md 缺少 ${ph} 占位符 —— 渲染会静默少一段`);
+    }
+  }
 }
 
 /**
@@ -76,11 +109,19 @@ const POLICY_BLOCK = /<!-- nd:policy:(full|min):start -->\n([\s\S]*?)<!-- nd:pol
  *   前提不成立。留下的一条不随档位变，也不随谁在用变。
  *
  *   ⚠️ 默认 false。调用方拿不到模型名时落**完整**那份，绝不落 min。
+ *
+ *   `mode`：项目模式（projects.mode）。'design'（默认）留设计道分区，'rp' 留
+ *   演出分区。认不出的值落 design —— 存量项目全是 design，猜错方向宁可多给不少给。
  */
 export function renderPrelude(level = 'loose', opts = {}) {
   const keep = opts.uncensored === true ? 'min' : 'full';
+  const keepMode = opts.mode === 'rp' ? 'rp' : 'design';
+  // 认不出的 locale 落中文：这个产品是中文优先的，拿不准时给中文不给英文。
+  const localeName = UI_LOCALE_NAME[opts.locale] || UI_LOCALE_NAME[DEFAULT_LOCALE];
   return NODESIGN_PRELUDE
     .replace(POLICY_BLOCK, (_all, which, body) => (which === keep ? body : ''))
+    .replace(MODE_BLOCK, (_all, which, body) => (which === keepMode ? body : ''))
     .replace('{{ADULT_POLICY}}', ADULT_POLICY[level] || ADULT_POLICY.loose)
+    .replace('{{UI_LOCALE}}', localeName)
     .trim();
 }

package/server/engine/agent/tool-input-stream.js

@@ -0,0 +1,165 @@
+/**
+ * server/engine/agent/tool-input-stream.js —— 真流式工具入参（2026-07-28 建，
+ * 2026-08-29 从 agent-shared.js 拆出：行数棘轮，胖了就拆别抬上限）
+ *
+ * input_json_delta 是半截 JSON 碎片。等拼完再发的话，模型逐 token 生成 new_string
+ * 的几十秒里前端只能干转圈。这里对点名的工具累积缓冲区，节流用 partial-json 容错
+ * 解析累积串，把目标字段相对上次的**纯文本增量**推给前端（run.delta.tool_input）。
+ *
+ * 转义符跨块断开由解析器兜住；字段单调增长，万一局部解析短暂回缩就跳过本拍
+ * （append 只在变长时发）。
+ */
+
+import { Events } from './events.js';
+import { toWorkspaceRel } from '../../lib/workspace-path.js';
+import { parse as parsePartialJson, Allow as PartialAllow } from 'partial-json';
+
+// ── 真流式工具入参（2026-07-28，工作台舞台层代码直播）──
+// input_json_delta 是半截 JSON 碎片，等拼完再发一次的话，模型逐 token 生成
+// new_string 的几十秒里前端只能干转圈。这里对写代码的工具累积缓冲区，节流用
+// partial-json 容错解析累积串，把目标字段相对上次的纯文本增量推给前端
+// （run.delta.tool_input）。转义符跨块断开由解析器兜住；字段单调增长，
+// 万一局部解析短暂回缩就跳过本拍（append 只在变长时发）。
+/**
+ * `spot`（2026-08-29 占位契约刀 C）：跟 text 一起抽出来的**位置字段**。
+ *
+ * 在这之前流式板书的字画在"视口里一块空地"（BoardCanvas 的 liveChalkSpotFor），
+ * 跟 agent 给的 at 毫无关系 —— 写完淡出、真卡在真位置接棒，用户看到的是字从假
+ * 位置跳到真位置。站主要的是「先把位置选好，内容流到选定位置」。
+ *
+ * 时机不用另外等：判据跟 file_path 那套一样 —— **目标字段（text）的 key 一出现，
+ * 就说明排在它前面的字段都已闭合**（所以 write_on_board 的 schema 把 at/sheet/
+ * width 排到了 text 前面）。也就是说框在第一个字到达的那一刻立起来，正好。
+ *
+ * ⚠️ 不能只看 `at` 在不在：容错解析会把**没写完的数字**也交出来（`{"x": 123`
+ * 流到一半是 `{x:12}`，完全合法且看不出来），用它当坐标就是错的位置。
+ */
+export const TOOL_INPUT_STREAM_FIELDS = {
+  Edit: 'new_string',
+  Write: 'content',
+  // 板书直播（2026-08-25 流式路 A）：write_on_board 的 text 逐 token 流到画布上
+  // 的舞台粉笔卡（StageLayer chalk 档）—— 粉笔字在用户眼前一行行长出来。
+  mcp__nodesign__write_on_board: { field: 'text', spot: ['slot', 'at', 'sheet', 'width', 'h', 'near', 'side', 'reply_to', 'chain'] },
+  // board_batch 批内嵌套（08-25 用户报「流式名存实亡」：skill 教的是一章一次
+  // batch，正文藏在 actions[].input.text 里，顶层字段抽取器抓不到 —— 等于亲手
+  // 教了大家绕开流式）。batch 档抽**最新一条** write_on_board 动作的 text，
+  // 换动作时发 reset 让前端另起一张。
+  mcp__nodesign__board_batch: { batch: 'write_on_board', field: 'text', spot: ['slot', 'at', 'sheet', 'width', 'h', 'near', 'side', 'reply_to', 'chain'] },
+};
+const TOOL_INPUT_THROTTLE_MS = 120;
+
+export function toolInputStreams(ctx) {
+  if (!ctx._toolInputStreams) ctx._toolInputStreams = new Map();
+  return ctx._toolInputStreams;
+}
+
+
+/** 批内嵌套抽取（纯函数好钉测试）：最新一条 <tool> 动作的 <field> 字符串与它的序号 */
+export function latestBatchField(obj, toolName, field) {
+  const actions = Array.isArray(obj?.actions) ? obj.actions : [];
+  for (let i = actions.length - 1; i >= 0; i -= 1) {
+    const a = actions[i];
+    const name = String(a?.name || '');
+    if ((name === toolName || name.endsWith(`__${toolName}`)) && typeof a?.input?.[field] === 'string') {
+      return { idx: i, text: a.input[field], input: a.input };
+    }
+  }
+  return null;
+}
+
+/**
+ * 位置字段抽取（占位契约刀 C）。只在**目标字段已经出现**时调用 —— 那时排在它
+ * 前面的位置字段都已闭合，数字不会是流到一半的半截值。
+ *
+ * ⚠️ 一个位置字段都没有时返回的是**空对象不是 null**（2026-08-29 刀 F）：
+ * "什么都没点名" 本身就是一条位置信息 —— 那是**纸内顺排**，前端照服务端同一条
+ * 规则算得出落点。返回 null 的话这条事件根本不发，前端只能把字先写在视口一块
+ * 空地上、等落盘再跳过去（站主看到的"流式完毕之后再移动"）。而顺排恰恰是最
+ * 常见的调用形态。
+ *
+ * @returns {object|null} null 只在入参根本不是对象时出现
+ */
+export function pickSpot(input, fields) {
+  if (!input || typeof input !== 'object') return null;
+  const out = {};
+  for (const k of fields) {
+    const v = input[k];
+    if (v === undefined || v === null) continue;
+    // at 是 {x,y}：两个坐标都得是有限数才算数（缺一个就是没写完）
+    if (k === 'at') {
+      if (typeof v === 'object' && Number.isFinite(v.x) && Number.isFinite(v.y)) {
+        out.at = { x: v.x, y: v.y };
+      }
+      continue;
+    }
+    if (typeof v === 'string' || Number.isFinite(v) || typeof v === 'boolean') out[k] = v;
+  }
+  return out;
+}
+
+export 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;
+  let text = '';
+  let reset = false;
+  let host = obj;              // 位置字段所在的对象（batch 档是那条动作的 input）
+  if (st.batch) {
+    const hit = latestBatchField(obj, st.batch, st.field);
+    if (hit) {
+      if (st.actionIdx !== hit.idx) { st.actionIdx = hit.idx; st.sent = 0; st.spotSent = false; reset = true; }
+      text = hit.text;
+      host = hit.input;
+    }
+  } else {
+    text = typeof obj[st.field] === 'string' ? obj[st.field] : '';
+  }
+  // 位置（刀 C）：目标字段已出现 = 排在它前面的位置字段都闭合了，这一拍可以定框。
+  // 一条动作只发一次（batch 换动作时 spotSent 已随 reset 归位）。
+  const spot = (!st.spotSent && st.spot && host?.[st.field] !== undefined)
+    ? { ...pickSpot(host, st.spot), ...(st.batch ? { batchIdx: st.actionIdx } : {}) } : null;
+  // 新纸预告（刀④ 2026-08-30）：batch 的典型形状是 [open_sheet, write{slot}, …]，
+  // 流式发生时**一个动作都没执行**、新纸还没登记 —— 前端只能退到「最新那张纸」
+  // （偏一整屏）或空地（叠一堆）。这里把「这条 write 排在一个 open_sheet 后面」
+  // 这件事随 spot 带出去，slot 的规划矩形也从流进来的 plan 里抠出来，
+  // 前端就能把框立在新纸将要出现的地方。
+  if (spot && st.batch && Array.isArray(obj.actions)) {
+    const opened = obj.actions.slice(0, st.actionIdx)
+      .filter((a) => typeof a?.name === 'string' && a.name.replace(/^mcp__\w+__/, '') === 'open_sheet')
+      .pop();
+    if (opened) {
+      spot.freshSheet = true;
+      const plan = Array.isArray(opened.input?.plan) ? opened.input.plan : [];
+      const sl = spot.slot ? plan.find((p) => p?.slot === spot.slot) : null;
+      if (sl && Number.isFinite(sl.at?.x) && Number.isFinite(sl.at?.y)
+        && Number.isFinite(sl.w) && Number.isFinite(sl.h)) {
+        spot.planSlot = { x: sl.at.x, y: sl.at.y, w: sl.w, h: sl.h };
+      }
+    }
+  }
+  // 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 && !spot && !flush && !reset) return;
+  st.lastEmit = now;
+  if (append) st.sent = text.length;
+  if (filePath) st.filePathSent = true;
+  if (spot) st.spotSent = true;
+  ctx.emit(Events.deltaToolInput(ctx.counters.turns, st.id, st.name, {
+    ...(filePath ? { filePath } : {}),
+    ...(spot ? { spot } : {}),
+    ...(append ? { append } : {}),
+    ...(reset ? { reset: true } : {}),
+    ...(flush ? { done: true } : {}),
+  }));
+}
+

package/server/engine/agents/explorer.md

@@ -44,7 +44,7 @@
 - `Read` / `Glob` / `Grep` —— 看本地 `./assets/` 里的素材 / `./spec.json` 决策档案
 - `TodoWrite` —— 3 步以上研究列计划
 
-**工具集外的工具**（用了也无效，且打破子代理边界）：Write / Edit / Bash / screenshot_canvas / export / record_decision /
+**工具集外的工具**（用了也无效，且打破子代理边界）：Write / Edit / Bash / screenshot_canvas / export /
 AskUserQuestion —— 你的产物是信息不是修改，跟用户对话由主 agent 负责。研究就是研究。
 
 ---

package/server/engine/agents/index.js

@@ -137,7 +137,7 @@ export function createAgents({ mainModel, sdkModel, fastModel } = {}) {
     //   - TodoWrite（多步研究列计划）
     // 不给：Write/Edit（不写代码）/ Bash（不要 shell shenanigans）/
     //       AskUserQuestion（子代理不直接跟用户说话）/ screenshot/export/
-    //       record_decision（不是它的角色）/ Task（不允许嵌套子代理）
+    //       Task（不允许嵌套子代理）
     // ⏸ explorer 研究员（2026-08-14 用户暂时停用："有点没用"）。定义与
     // prompt（explorer.md）原样保留，恢复 = 取消注释 + prelude 补回子代理
     // 清单那两行。停用期间搜索/读外链由主 agent 直接用 web_search / WebFetch。

package/server/engine/mcp/actor.js

@@ -0,0 +1,59 @@
+/**
+ * engine/mcp/actor.js —— 板上写入的署名（2026-08-26）
+ *
+ * 板上每一样东西都带 `by`。在常驻角色之前它只有两个值（'agent' / 'user'），
+ * 现在多了第三类：**具名角色**（叙事者、NPC），值是它的 slug（`rp-moli`）。
+ *
+ * 为什么署 slug 而不署展示名：slug 是 harness 在派发那一刻盖的章（见 actor-trail.js），
+ * 展示名住在角色文件里、而那个文件模型能改。署名要能当证据用，就不能取自被署名者
+ * 自己写的文本。展示名由读侧按 slug 查出来（role-card.js），查不到就显示 slug 本身。
+ */
+
+import { callerOf, agentNameOf } from '../agent/actor-trail.js';
+import { isResidentRole, isSlotType, safeRoleLabel } from '../agent/cast.js';
+
+/** MCP handler 的 extra 里取本次 tool_use id（2026-08-26 实测就在这个键上） */
+export function toolUseIdOf(extra) {
+  return extra?._meta?.['claudecode/toolUseId'] || null;
+}
+
+/**
+ * 这次板上写入该署谁的名。
+ * @returns {'agent'|string}  主 agent → 'agent'；常驻角色 → 它的 slug
+ */
+export function byOf(extra) {
+  const caller = callerOf(toolUseIdOf(extra));
+  const type = caller?.agentType;
+  // 落到**演员位**（rp-actor/rp-narrator）说明盖章那一刻别名还没学到实例名。
+  // 这里**当场再解一次** —— 别名可能在盖章之后才学到（08-28 真会话实录：
+  // 19:59 派发、20:10 角色调 jot_memory 被拒、20:10 GM 一发 SendMessage 别名补上、
+  // 20:21 同一个工具就成了。差的就是"用盖章那一刻的快照"还是"用此刻的表"）。
+  if (isSlotType(type)) {
+    const nm = agentNameOf(caller?.agentId);
+    if (isResidentRole(nm) && !isSlotType(nm)) return nm;
+  }
+  return isResidentRole(type) ? type : 'agent';
+}
+
+/**
+ * 把一个 `by` 渲染成给**这个读者**看的称呼。
+ *
+ * read_board 的输出可能被主 agent 读，也可能被角色自己读 —— 同一句「你写的」对两个
+ * 读者含义相反。所以渲染要带视角：谁在读，就管谁叫「你」。
+ *
+ * @param by         板上那条东西的署名（'user' / 'agent' / 'rp-*'）
+ * @param viewer     当前读者（同上取值）
+ * @param names      slug → 展示名（只当展示层，见 role-card.listRoleNames）
+ */
+export function describeBy(by, viewer, names) {
+  if (by === viewer) return '你';
+  if (by === 'user') return '用户';
+  if (by === 'agent') return '主控';
+  return safeRoleLabel(by, names?.get?.(by));
+}
+
+/**
+ * 保留字的第二道防线。真正的闸在源头（`listRoleNames` 出口，见 cast.js
+ * `safeRoleLabel` 的注释）；这里留一层是给「名字没经过那条路」的调用点兜底。
+ */
+export { safeRoleLabel as roleLabel } from '../agent/cast.js';

package/server/engine/mcp/capability-gate.js

@@ -1,8 +1,12 @@
 /**
  * engine/mcp/capability-gate.js — 工具 × 本机能力位（runtime/capabilities.js）的唯一对照表 + 闸。
  *
- * 两种模式：
- *   - block：能力缺席时工具描述前缀「⛔ CURRENTLY UNAVAILABLE + 装法」（照 roll_film 的先例，agent 看到就不会调），
+ * 三种模式：
+ *   - unregister：能力缺席时**整件工具不注册**（连名字都不进模型上下文）。给那种
+ *            「缺了就完全没有替代路径、而且短期内不会回来」的工具用——站主的本地
+ *            GPU 盒子平时不开机，留着名字只会让 agent 反复去撞 SSH 拒连（08-24
+ *            信箱实证：paint_still 连撞两次，一次超时一次参数被拒才放弃）。
+ *   - block：能力缺席时工具描述前缀「⛔ CURRENTLY UNAVAILABLE + 装法」，
  *            真调了也在这里拦住，返回同一句话让它转告用户——不让裸的 ENOENT / 500 漏到 agent 面前
  *   - note ：工具仍可用，只在描述末尾加一句降级说明（build_docx 没有 LibreOffice 时仍能出文件，只是没页图）
  * 没探过（capabilityState 为 null：单测 / 脚本直接 import）→ 原样放行，这层不猜。
@@ -26,17 +30,32 @@ export const TOOL_CAPABILITIES = Object.freeze({
   web_search: { cap: 'webSearch', mode: 'block' },
   generate_image: { cap: 'imageGen', mode: 'block' },
   publish_site: { cap: 'publish', mode: 'block' },
+  // 站主自己的 5090 盒子（NODESIGN_LOCAL_BOX + NODESIGN_H3BOX_SSH）。盒子是手动
+  // 开关的，平时关着，所以用 unregister：不在线时连工具名都不给 agent 看见。
+  // 通用生图仍有 generate_image 顶着，不存在能力真空。
+  paint_still: { cap: 'localBox', mode: 'unregister' },
+  roll_film: { cap: 'localBox', mode: 'unregister' },
 });
 
 export function unavailableMessage(c) {
   return `本机缺 ${c.label}（${c.detail}）。装法：${c.fix}`;
 }
 
+/** 这件工具在当前能力状态下该不该注册（false = 连名字都不给） */
+export function shouldRegisterTool(toolDef) {
+  const spec = TOOL_CAPABILITIES[toolDef.name];
+  if (!spec || spec.mode !== 'unregister') return true;
+  const c = capabilityState(spec.cap);
+  // 没探过（单测 / 脚本直接 import）一律注册 —— 这层不猜，跟 withCapabilityGate 同纪律
+  return !c || c.available;
+}
+
 export function withCapabilityGate(toolDef) {
   const spec = TOOL_CAPABILITIES[toolDef.name];
   if (!spec) return toolDef;
   const c = capabilityState(spec.cap);
   if (!c || c.available) return toolDef;
+  // unregister 档走 shouldRegisterTool，走到这里说明调用方没过滤 —— 按 block 兜底
   const msg = unavailableMessage(c);
   if (spec.mode === 'note') {
     return { ...toolDef, description: `${toolDef.description}\n\n⚠️ ${msg} 本工具仍可用，但依赖它的步骤（页图/体检）会缺席。` };