@xiaobuyu/nodesign 0.0.1 → 0.0.2

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

@@ -1,143 +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)}`);
-      }
-    },
-  );
-}
+/**
+ * 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

@@ -1,140 +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,
-        };
-      }
-    },
-  );
-}
+/**
+ * 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,
+        };
+      }
+    },
+  );
+}