@xiaobuyu/nodesign 0.0.1

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

@@ -0,0 +1,143 @@
+/**
+ * mcp/tools/read-tavern-json.js — read_tavern_json MCP tool（2026-08-15）
+ *
+ * 搬酒馆的东西进来时的读取口。**不要用 Read 去读这类文件**：真样本
+ * （Izumi 0814.json）464KB、210 条提示词，启用的只有 56 条 —— Read 一次就是
+ * 十几万 token 进上下文，换来的绝大部分是停用的备选条目。
+ *
+ * 两步走：先 `摘要` 看结构（每条只给名字/角色/字数/一句引子），挑好了再
+ * `取` 正文。转成 编排.yaml 和设定文件是 agent 自己的活，这个工具只读不写。
+ */
+
+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';
+
+const MAX_FETCH_CHARS = 24_000;
+
+function 渲染摘要(d, 文件名) {
+  const L = [];
+  if (d.形态 === 'preset') {
+    L.push(`酒馆 Chat Completion 预设：${文件名}`);
+    L.push(`启用 ${d.启用.length} 条（其中有正文的 ${d.启用.filter(e => e.字数 > 0).length} 条，合计 ${d.合计字数} 字）· 停用 ${d.停用.length} 条`);
+    const p = d.参数;
+    L.push(`参数：temperature ${p.temperature} · top_p ${p.top_p} · 最大输出 ${p.最大输出} · reasoning_effort ${p.reasoning_effort ?? '未设'}`);
+    L.push('');
+    L.push('启用条目（顺序 = 进模型顺序）:');
+    for (const [i, e] of d.启用.entries()) {
+      const 标 = e.占位 ? '〔占位·酒馆运行时填，搬过来丢掉〕'
+        : e.分隔 ? '〔分节标题·无正文〕' : `${e.字数}字`;
+      L.push(`${String(i + 1).padStart(2)}. ${e.名字}  [${e.角色}] ${标}${e.深度 != null ? ` 深度${e.深度}` : ''}`);
+      if (e.引子) L.push(`      ${e.引子}…`);
+    }
+    if (d.停用.length) {
+      L.push('');
+      L.push(`停用的 ${d.停用.length} 条（同一功能的备选，酒馆里只开一个；名字列表）：`);
+      L.push(d.停用.map(e => e.名字).join(' / '));
+    }
+    L.push('');
+    L.push('占位条目（marker，酒馆运行时填角色卡/历史，搬过来一律丢）：' + (d.占位条目.join(' / ') || '无'));
+    L.push('分节标题（0 字，只是把开关分组，也不用搬）：' + (d.分隔条目.join(' / ') || '无'));
+  } else if (d.形态 === 'card') {
+    L.push(`酒馆角色卡：${d.名字}（${文件名}）`);
+    for (const f of d.字段) L.push(`- ${f.字段}  ${f.字数}字　${f.引子}…`);
+    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.停用 ? ' (停用)' : ''}`);
+      }
+    }
+  } 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('要正文就再调一次本工具：mode="fetch"，entries=["名字或名字的一部分", …]。');
+  return L.join('\n');
+}
+
+export function makeReadTavernJsonTool({ workspaceRoot, sharedRoot }) {
+  return tool(
+    'read_tavern_json',
+    `Read a SillyTavern (酒馆) export JSON — a chat-completion **preset**, a
+**character card** (V2/V3), or a **lorebook** — without pouring the whole file
+into your context.
+
+Use this instead of Read for any 酒馆 JSON. A real preset in the wild is 460KB
+with 210 prompt entries of which only 56 are enabled; Read would burn six digits
+of tokens on disabled alternates.
+
+Two steps:
+1. mode "digest" (default) — structure only: every entry's name, role, size and a
+   60-char peek, plus which are enabled/disabled, plus sampler params.
+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).`,
+    {
+      path: z.string().describe(
+        'Path to the .json. Relative paths resolve against the session workspace, '
+        + 'then the shared project dir (e.g. "assets/Izumi 0814.json").',
+      ),
+      // ⚠️ 参数名和枚举值一律 ASCII —— 工具 schema 是模型要照着填的东西，
+      // 中文键名在这条路上不可靠（全仓其他工具也都是 ASCII，别开这个头）
+      mode: z.enum(['digest', 'fetch']).optional()
+        .describe('digest = structure only (default); fetch = full text of the picked entries'),
+      entries: z.array(z.string()).optional()
+        .describe('For mode="fetch": entry names (partial match ok) or ids'),
+    },
+    async ({ path: rel, mode = 'digest', entries = [] }) => {
+      const fail = (text) => ({ content: [{ type: 'text', text }], isError: true });
+      try {
+        const raw = String(rel || '').trim();
+        if (!raw) return fail('read_tavern_json needs a path.');
+        const candidates = path.isAbsolute(raw)
+          ? [raw]
+          : [workspaceRoot && path.resolve(workspaceRoot, raw),
+             sharedRoot && path.resolve(sharedRoot, raw)].filter(Boolean);
+        let abs = null;
+        for (const c of candidates) {
+          try { await fs.access(c); abs = c; break; } catch { /* 下一个 */ }
+        }
+        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 kind = detectKind(doc);
+        if (!kind) {
+          return fail('认不出这是酒馆的哪种导出（预设要有 prompts + prompt_order；角色卡要有 first_mes；世界书要有 entries）。普通 JSON 用 Read 就行。');
+        }
+
+        if (mode === 'fetch') {
+          const 出 = fetchEntries(doc, entries);
+          if (!出.length) return fail(`没找到这些条目：${entries.join(' / ')}。先用 mode="digest" 看名字。`);
+          let 总 = 0;
+          const 块 = [];
+          for (const e of 出) {
+            if (总 >= MAX_FETCH_CHARS) { 块.push(`〔余下 ${出.length - 块.length} 条超出单次上限，分批取〕`); break; }
+            const 文 = e.正文.slice(0, MAX_FETCH_CHARS - 总);
+            总 += 文.length;
+            块.push(`### ${e.名字}${e.角色 ? `  [${e.角色}]` : ''}\n${文}`);
+          }
+          return { content: [{ type: 'text', text: 块.join('\n\n') }] };
+        }
+
+        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/record-decision.js

@@ -0,0 +1,140 @@
+/**
+ * mcp/tools/record-decision.js — record_decision MCP tool
+ *
+ * agent 在做关键设计决策时调，把"做了什么 + 为什么"写成共享便利贴
+ * `notes/决策.md` 的一面（`---` 分面）。2026-07-30 起决策
+ * 不再进 spec.json.decisions[]：便利贴是 agent 和用户的**共享层**——
+ * 用户在画布上直接看到、能翻、能改；spec.json 只是 agent 自己的暗档案，
+ * 用户看不见，头脑风暴根本进不来。旧会话已有的 spec.json decisions[]
+ * 仍被 hooks 注入（只读遗产），新决策一律走这里。
+ *
+ * 便利贴格式约定（前端 NoteSticker 按此渲染）：
+ *   - 一个 .md = 一张贴；`\n---\n` 分面，翻页看
+ *   - 每面第一行 `# 标题`
+ *
+ * 落点：工作区 `notes/`（扁平模型，2026-08-08 起）—— 没有"任务归属"了，
+ * 便利贴直接住项目桌面。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { Events } from '../../agent/events.js';
+
+const NOTE_FILE = '决策.md';
+
+/**
+ * @param {object} deps
+ * @param {string} deps.workspaceRoot
+ * @param {string} [deps.sessionId]
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeRecordDecisionTool({ workspaceRoot, sessionId, ctx }) {
+  return tool(
+    'record_decision',
+    `Record a key design decision as a face of the project's decision sticky note
+(notes/决策.md). The note is SHARED with the user — it renders as
+a flippable sticky on their canvas, they can read and edit it. Use this to
+capture WHY you made a particular choice — color, type scale, layout metaphor,
+copy strategy — so the intent survives across sessions and the user can push
+back on it.
+
+Use this tool when:
+- You make a non-trivial choice that has multiple defensible alternatives
+  (e.g., picking a primary color, deciding deck length, choosing a layout)
+- The user gives feedback that changes a previous decision (record both)
+- You want to document a constraint discovered mid-work
+
+Do NOT use this tool for:
+- Trivial implementation details (CSS class names, file structure)
+- Things obvious from the canvas itself (the visible design speaks for itself)
+- Every change — over-recording bloats the note and dilutes signal
+
+For free-form shared notes (brainstorm material, reference digests, handoff
+context), just Write notes/<slug>.md directly — same sticky-note
+rendering, no tool needed.`,
+    {
+      title: z
+        .string()
+        .min(2)
+        .max(200)
+        .describe('Short decision title (e.g., "Primary color = #3366FF")'),
+      rationale: z
+        .string()
+        .min(2)
+        .max(2000)
+        .describe('Why this choice — connect to brief / user feedback / design principle'),
+      scope: z
+        .string()
+        .optional()
+        .describe('Where it applies (e.g., "Global", "Cover page", "All H1 headings")'),
+      alternatives: z
+        .array(z.string())
+        .optional()
+        .describe('Alternatives considered, briefly noting why rejected'),
+    },
+    async ({ title, rationale, scope, alternatives }) => {
+      try {
+        if (!workspaceRoot) {
+          return {
+            content: [{ type: 'text', text: 'No workspace bound; cannot record decision.' }],
+            isError: true,
+          };
+        }
+        const alts = Array.isArray(alternatives)
+          ? alternatives.map(s => String(s).trim()).filter(Boolean) : [];
+        const face = [
+          `# ${title.trim()}`,
+          '',
+          rationale.trim(),
+          ...(scope ? ['', `- 范围：${scope.trim()}`] : []),
+          ...(alts.length ? [`- 备选：${alts.join(' / ')}`] : []),
+          `- ${new Date().toISOString().slice(0, 10)}`,
+        ].join('\n');
+
+        const notesDir = path.join(workspaceRoot, 'notes');
+        await fs.mkdir(notesDir, { recursive: true });
+        const noteFile = path.join(notesDir, NOTE_FILE);
+        let prev = '';
+        try { prev = await fs.readFile(noteFile, 'utf8'); } catch { /* 首条 */ }
+        const next = prev.trim() ? `${prev.replace(/\s+$/, '')}\n\n---\n\n${face}\n` : `${face}\n`;
+        await fs.writeFile(noteFile, next, 'utf8');
+
+        const faceCount = next.split(/\n---\n/).length;
+        try {
+          // MCP 工具写盘不走 PostToolUse(Write/Edit) 那条 file_changed 直发，
+          // 自己补一发，前端便利贴才会当场刷新
+          // 工作区相对路径（fileChanged 正字法；曾发绝对路径=前端只吃到清单重拉，
+          // 寻址和版本 key 全失配。2026-08-14 普查改）
+          ctx?.emit?.(Events.fileChanged(`notes/${NOTE_FILE}`, 'change'));
+          ctx?.emit?.({
+            type: 'run.decision_recorded',
+            title: title.trim(),
+            scope: scope?.trim() || null,
+            decisionsCount: faceCount,
+          });
+        } catch { /* emit fail-safe */ }
+
+        return {
+          content: [{
+            type: 'text',
+            // ⚠️ 这里曾写 `tasks/${task}/...` —— 扁平化删掉 task 变量时漏了这行，
+            // `task` 成悬空引用：决策照写、事件照发，**返回时 ReferenceError 被
+            // 外层 catch 接住**，agent 每次调用都收到报错以为失败（还可能重试出
+            // 重复面）。悬空引用潜伏族第二案（第一案 reloadToken，2026-08-08）。
+            text: `Decision recorded as face ${faceCount} of notes/${NOTE_FILE}: "${title.trim()}"`,
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text',
+            text: `Record decision failed: ${err?.message || String(err)}`,
+          }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/server/engine/mcp/tools/relate-on-board.js

@@ -0,0 +1,110 @@
+/**
+ * mcp/tools/relate-on-board.js — relate_on_board MCP tool（2026-08-07）
+ *
+ * 让 agent 在画布上**画出产物之间的关系**。
+ *
+ * ## 为什么这个工具重要
+ *
+ * 北极星是「任务文件夹能排出登录墙那种版面」。手摆之所以好看，是因为每张纸的
+ * 位置在回答「它和旁边那张什么关系」—— 而系统此前只知道每个产物的尺寸和
+ * mtime。**关系数据不到位，再好的布局算法也只能排出「错落有致的网格」。**
+ *
+ * 关键洞察是：**关系不需要推断，agent 手里本来就有**。它知道 proto-暖调 和
+ * proto-冷调 是同一拍的两个试作、知道哪张图是哪次批注的结果、知道这版改自那版。
+ * 这些信息现在全在会话里，一落到画布就只剩文件名。这个工具就是那条落差。
+ *
+ * 线不存坐标：端点是物件 id 或工作区 id，端点一移动线自己跟着走。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { patchBoard } from '../../../projects/board-store.js';
+import { BINDING_TYPES, BINDING_TYPE_IDS } from '../../../lib/binding-types.js';
+
+/** 词汇表渲染成工具描述里的一段表，免得两处各写各的 */
+const VOCAB = BINDING_TYPE_IDS
+  .map(id => `- ${id} (${BINDING_TYPES[id].label})${BINDING_TYPES[id].directed ? '' : ' — undirected'}`)
+  .join('\n');
+
+let seq = 0;
+const nextId = () => `b:a${Date.now().toString(36)}${(seq++ % 1000).toString(36)}`;
+
+export function makeRelateOnBoardTool({ projectId, ctx }) {
+  return tool(
+    'relate_on_board',
+    `Draw a relationship line between two things on the workbench canvas.
+
+The canvas knows *what* each artifact is, but not *how they relate*. You are
+the only one who knows that — you made them. Recording it lets the user see
+lineage at a glance, and lets layout put related things near each other.
+
+Relationship types:
+${VOCAB}
+
+Endpoints are canvas ids — a kind prefix plus the workspace-relative path,
+exactly as the file sits on disk:
+- a file: 'assets/generated/x.webp', 'notes/灵感.md'
+- a deck: 'deck:海报/proto-暖调.html'
+- a site: 'site:伊蕾娜手账研究站'
+- a folder: just its path, '海报' or '海报/初稿'
+
+Use it right after you produce something that relates to earlier work:
+- made v2 of a poster → derives-from, from the new one to the old one
+- produced two variants to compare → contrast between them
+- storyboard panels in order → flow, each to the next
+- used a reference image in a deck → ref, from the deck to the image
+
+Do NOT use it for "these are all in the same folder" — that is what the
+folder already says. Only record relationships that are not obvious from
+where the files live.`,
+    {
+      type: z.enum(BINDING_TYPE_IDS).describe('Relationship kind (see list above)'),
+      from: z.string().min(1).max(300).describe('Source canvas id — see forms above'),
+      to: z.string().min(1).max(300).describe('Target canvas id — see forms above'),
+      label: z.string().max(60).optional()
+        .describe('Optional short words on the line. Omit to use the default for the type.'),
+    },
+    async ({ type, from, to, label }) => {
+      if (!projectId) {
+        return { content: [{ type: 'text', text: 'No project bound; cannot draw relationships.' }], isError: true };
+      }
+      if (from === to) {
+        return {
+          content: [{ type: 'text', text: 'from and to are the same thing — a relationship needs two ends.' }],
+          isError: true,
+        };
+      }
+      const id = nextId();
+      // by:'agent' 不只是记录出处 —— 用户画的线 agent 不该擅自删，反过来也一样
+      const binding = { type, from, to, by: 'agent', ...(label ? { label } : {}) };
+      const board = await patchBoard(projectId, { bindings: { [id]: binding } });
+
+      // 服务端会丢掉非法的线（未知 type / 自环）。**丢了要说**，否则 agent 以为
+      // 画上了，用户看不到，两边都不知道发生了什么。
+      if (!board.bindings?.[id]) {
+        return {
+          content: [{ type: 'text', text: `Relationship rejected by the board (bad type or endpoints): ${type} ${from} -> ${to}` }],
+          isError: true,
+        };
+      }
+
+      // 广播：前端整份重拉。**sessionId 必须显式给 null** —— ctx 会把自己的
+      // sessionId 补进事件，那样只有当前会话的连接收得到，别的 tab 看不见。
+      try {
+        ctx?.emit?.({
+          type: 'board.updated',
+          sessionId: null,
+          summary: `已画一条「${BINDING_TYPES[type].label}」关系`,
+        });
+      } catch { /* emit fail-safe：广播失败不该让工具报错，线已经落盘了 */ }
+
+      const arrow = BINDING_TYPES[type].directed ? '->' : '<->';
+      return {
+        content: [{
+          type: 'text',
+          text: `Drew ${type} (${BINDING_TYPES[type].label}): ${from} ${arrow} ${to}`,
+        }],
+      };
+    },
+  );
+}