@xiaobuyu/nodesign 0.0.1 → 0.0.2

package/server/engine/agent/hooks/tool-prompts.js

@@ -1,31 +1,31 @@
-/**
- * 工具 prompt lazy 注入文件加载（首调即缓存）。仿 agents/index.js loadPrompt 模式。
- *
- * 用途：cookbook / tweaks-syntax / vision-checker-dispatch 这些 reference 文档
- * 不放系统 prompt 恒驻（每 turn 拖累），改由 PreToolUse hook 在 agent 首次调对应工具时
- * 通过 additionalContext 注入。文件存 prompts/tools/*.md，模块加载时一次性读完缓存到 map。
- *
- * fail-soft：缺失 / 读失败返回 stub 字符串，hook 注入也不至于崩；console.warn 让部署
- * 日志能立刻发现。
- */
-import fsSync from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-// prompts/ 住在 agent/ 层（本模块在 agent/hooks/ 下一层，要往上跳一级）
-const PROMPTS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'prompts', 'tools');
-
-const TOOL_PROMPT_CACHE = {};
-export function loadToolPrompt(name) {
-  if (TOOL_PROMPT_CACHE[name] !== undefined) return TOOL_PROMPT_CACHE[name];
-  const file = path.join(PROMPTS_DIR, `${name}.md`);
-  try {
-    TOOL_PROMPT_CACHE[name] = fsSync.readFileSync(file, 'utf8');
-  } catch (err) {
-    console.warn(`[hooks] failed to load tool prompt ${name}.md (${err.message}); using stub`);
-    TOOL_PROMPT_CACHE[name] =
-      `(tool prompt ${name}.md not found at ${file}. PreToolUse hook will skip lazy injection — `
-      + `agent fallbacks to whatever guidance lives in SKILL.md core.)`;
-  }
-  return TOOL_PROMPT_CACHE[name];
-}
+/**
+ * 工具 prompt lazy 注入文件加载（首调即缓存）。仿 agents/index.js loadPrompt 模式。
+ *
+ * 用途：cookbook / tweaks-syntax / vision-checker-dispatch 这些 reference 文档
+ * 不放系统 prompt 恒驻（每 turn 拖累），改由 PreToolUse hook 在 agent 首次调对应工具时
+ * 通过 additionalContext 注入。文件存 prompts/tools/*.md，模块加载时一次性读完缓存到 map。
+ *
+ * fail-soft：缺失 / 读失败返回 stub 字符串，hook 注入也不至于崩；console.warn 让部署
+ * 日志能立刻发现。
+ */
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// prompts/ 住在 agent/ 层（本模块在 agent/hooks/ 下一层，要往上跳一级）
+const PROMPTS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'prompts', 'tools');
+
+const TOOL_PROMPT_CACHE = {};
+export function loadToolPrompt(name) {
+  if (TOOL_PROMPT_CACHE[name] !== undefined) return TOOL_PROMPT_CACHE[name];
+  const file = path.join(PROMPTS_DIR, `${name}.md`);
+  try {
+    TOOL_PROMPT_CACHE[name] = fsSync.readFileSync(file, 'utf8');
+  } catch (err) {
+    console.warn(`[hooks] failed to load tool prompt ${name}.md (${err.message}); using stub`);
+    TOOL_PROMPT_CACHE[name] =
+      `(tool prompt ${name}.md not found at ${file}. PreToolUse hook will skip lazy injection — `
+      + `agent fallbacks to whatever guidance lives in SKILL.md core.)`;
+  }
+  return TOOL_PROMPT_CACHE[name];
+}

package/server/engine/agent/hooks/turn-state-memory.js

@@ -1,56 +1,56 @@
-/**
- * hooks/turn-state-memory.js — 每轮状态注入的"上一轮记忆"（2026-08-21）
- *
- * UserPromptSubmit 每轮把工作区状态（素材 / 产物 / 便利贴 / 关系线 / 决策 / tweaks）
- * 注给模型。以前每轮全量，30 轮下来上下文里是十几份几乎一样的块（实测 540~1300
- * token/轮）。现在**首轮全量、之后只报变化**：每节算一个指纹存在这里，下一轮对照。
- *
- * 键按 sessionId（一次对话一份记忆）。两种情况要清掉让下一轮重新全量：
- *   - 上下文压缩之后（PostCompact）：旧的那份已经被摘要吞了，"同上轮"没有所指
- *   - 进程重启：Map 本来就空
- * 上限 300 个会话，LRU 淘汰 —— 会话结束不另外清（多数会话没几轮，留着也就几百字节）。
- */
-
-const MAX_SESSIONS = 300;
-/** sessionId → { sections: Map<key, {hash:string, items:string[]|null}>, turns: number } */
-const memory = new Map();
-
-/** djb2：够用的短指纹，不引 crypto */
-export function fingerprint(text) {
-  let h = 5381;
-  const s = String(text);
-  for (let i = 0; i < s.length; i += 1) h = ((h << 5) + h + s.charCodeAt(i)) | 0;
-  return (h >>> 0).toString(36);
-}
-
-export function getTurnMemory(sessionId) {
-  if (!sessionId) return null;
-  const m = memory.get(sessionId);
-  if (m) { memory.delete(sessionId); memory.set(sessionId, m); }   // LRU 触碰
-  return m || null;
-}
-
-export function setTurnMemory(sessionId, sections) {
-  if (!sessionId) return;
-  const prev = memory.get(sessionId);
-  memory.delete(sessionId);
-  memory.set(sessionId, { sections, turns: (prev?.turns || 0) + 1 });
-  while (memory.size > MAX_SESSIONS) memory.delete(memory.keys().next().value);
-}
-
-/** 压缩后 / 想强制下一轮全量时调 */
-export function resetTurnMemory(sessionId) {
-  if (sessionId) memory.delete(sessionId);
-}
-
-/** 两个清单的差 → { added, removed }（给素材 / 便利贴这种按项报变化的节用） */
-export function diffItems(prevItems, nextItems) {
-  const prev = new Set(prevItems || []);
-  const next = new Set(nextItems || []);
-  return {
-    added: [...next].filter(x => !prev.has(x)),
-    removed: [...prev].filter(x => !next.has(x)),
-  };
-}
-
-export const _memory = memory;   // 测试用
+/**
+ * hooks/turn-state-memory.js — 每轮状态注入的"上一轮记忆"（2026-08-21）
+ *
+ * UserPromptSubmit 每轮把工作区状态（素材 / 产物 / 便利贴 / 关系线 / 决策 / tweaks）
+ * 注给模型。以前每轮全量，30 轮下来上下文里是十几份几乎一样的块（实测 540~1300
+ * token/轮）。现在**首轮全量、之后只报变化**：每节算一个指纹存在这里，下一轮对照。
+ *
+ * 键按 sessionId（一次对话一份记忆）。两种情况要清掉让下一轮重新全量：
+ *   - 上下文压缩之后（PostCompact）：旧的那份已经被摘要吞了，"同上轮"没有所指
+ *   - 进程重启：Map 本来就空
+ * 上限 300 个会话，LRU 淘汰 —— 会话结束不另外清（多数会话没几轮，留着也就几百字节）。
+ */
+
+const MAX_SESSIONS = 300;
+/** sessionId → { sections: Map<key, {hash:string, items:string[]|null}>, turns: number } */
+const memory = new Map();
+
+/** djb2：够用的短指纹，不引 crypto */
+export function fingerprint(text) {
+  let h = 5381;
+  const s = String(text);
+  for (let i = 0; i < s.length; i += 1) h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+  return (h >>> 0).toString(36);
+}
+
+export function getTurnMemory(sessionId) {
+  if (!sessionId) return null;
+  const m = memory.get(sessionId);
+  if (m) { memory.delete(sessionId); memory.set(sessionId, m); }   // LRU 触碰
+  return m || null;
+}
+
+export function setTurnMemory(sessionId, sections) {
+  if (!sessionId) return;
+  const prev = memory.get(sessionId);
+  memory.delete(sessionId);
+  memory.set(sessionId, { sections, turns: (prev?.turns || 0) + 1 });
+  while (memory.size > MAX_SESSIONS) memory.delete(memory.keys().next().value);
+}
+
+/** 压缩后 / 想强制下一轮全量时调 */
+export function resetTurnMemory(sessionId) {
+  if (sessionId) memory.delete(sessionId);
+}
+
+/** 两个清单的差 → { added, removed }（给素材 / 便利贴这种按项报变化的节用） */
+export function diffItems(prevItems, nextItems) {
+  const prev = new Set(prevItems || []);
+  const next = new Set(nextItems || []);
+  return {
+    added: [...next].filter(x => !prev.has(x)),
+    removed: [...prev].filter(x => !next.has(x)),
+  };
+}
+
+export const _memory = memory;   // 测试用

package/server/engine/agent/hooks/user-prompt-submit.js

@@ -1,215 +1,215 @@
-/**
- * UserPromptSubmit handler — 每次用户输入前注入工作区**状态**（2026-08-21 重做）
- *
- * 注的是状态不是指令：cwd、素材清单、旧决策、便利贴、画布关系线、产物清单、tweaks 开关。
- * 怎么用这些东西（路径表、"先看有没有现成的素材"、工具怎么选）住 prelude，那是缓存的
- * system prompt；每轮再说一遍是上下文里的 N 倍重复。
- *
- * ## 首轮全量，之后只报变化
- *
- * 以前每轮全量（实测 540~1300 token/轮），30 轮下来对话历史里是十几份几乎相同的块。
- * 现在每节算指纹记在 turn-state-memory.js（按 sessionId）：
- *   - 首轮（或压缩后 / 进程重启后）：全量 + 结尾"请基于这些信息处理用户的请求"
- *   - 之后：变了的节全文（标「有变化」），素材/便利贴这种清单只报新增/移除；没变的节
- *     只在末尾一行点名"未变：…"（让模型知道它们还在，但不重复内容）；一节都没变就一句话
- *
- * ## 素材块从 turn-compose 搬过来（同日）
- *
- * 以前 assets 摘要是 turn-compose 拼进**用户消息**里的 <system> 块，跟这里的状态块是
- * 两条线两个真相源；而且那块写着"assets/ 是 symlink 别用 Glob"—— 08-07 扁平化后早就是
- * 真目录了。现在合成这一条线，symlink 那句删掉。
- *
- * input: UserPromptSubmitHookInput — output: { hookSpecificOutput: { additionalContext } }
- */
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { readUiConfigFile } from '../../../projects/ui-config.js';
-import { readAssetsSummary } from '../../../projects/assets-summary.js';
-import { relationsDigest } from '../../../lib/board-relations.js';
-import {
-  getActiveArtifact, listWorkspaceArtifacts, taskManifest, kindDef,
-  KIND_DECK, KIND_SITE, ENTRY_FILE,
-} from '../../../lib/artifact-target.js';
-import { getTurnMemory, setTurnMemory, fingerprint, diffItems } from './turn-state-memory.js';
-
-/** UserPromptSubmit hook 读取 spec.json 时的最大字节数 */
-const SPEC_JSON_MAX_BYTES = 200 * 1024;
-/** spec.json.decisions 注入摘要时取最近 N 条 */
-const SPEC_DECISIONS_TAIL = 5;
-
-/** PDF/Office 文档的解法（系统自带工具；python 包没装且装不上 —— 08-19 上报实锤）。只在首次出现二进制文档时说一遍。 */
-const BINARY_DOC_HINT = 'PDF / PPTX / DOCX / XLSX 直接 Read 拿不到结构化内容（二进制或 zip 包）。用系统自带的工具解'
-  + '（pdfplumber/PyPDF2/python-docx/openpyxl 这些 python 包**没装且装不上**，别试）：'
-  + 'pdf 文本 `pdftotext -layout 文件.pdf -`；pdf 转页图 `pdftoppm -png -r 100 文件.pdf 页前缀` 再 Read 图片；pdf 嵌入图 `pdfimages -png`。'
-  + 'docx/pptx/xlsx 用 `soffice --headless --convert-to txt|csv|pdf --outdir 目录 文件`（xlsx 转 csv；⚠️ soffice 吃不下中文文件名，先拷成 ASCII 名，并加 `-env:UserInstallation=file:///tmp/lo-任意名` 免得和渲染管线抢 profile）；'
-  + 'docx/pptx 里的嵌入图直接 `unzip -o 文件 "word/media/*"`（pptx 是 `ppt/media/*`）。'
-  + '**提取出来的不只是文本，通常还包含嵌入图片** —— 提取完一定 Read 看图片，别只看 stdout 文本就以为信息齐了。';
-
-/**
- * 采集各节。每节 { key, title, text, items? }：text 是全量文案；items 是可按项报变化的清单。
- * 任一节采不到就不出现（跟以前一样：扫不动就不说，别拿错信息误导）。
- */
-async function collectSections({ workspaceRoot, sessionId, projectId }) {
-  const sections = [];
-
-  // cwd：唯一真正动态的一行。路径表（./ notes/ assets/ .claude/agent-memory/ 各是什么）在 prelude
-  sections.push({ key: 'cwd', title: '工作区', text: `你的 cwd 是 ${workspaceRoot} —— 项目工作区，产物直接住这儿（路径表见 prelude「你跑在哪」）。` });
-
-  // 素材：顶层 assets/ + assets/references/**（逛站采回来的）
-  try {
-    const a = await readAssetsSummary(workspaceRoot);
-    if (a.count > 0) {
-      const all = Array.isArray(a.allPaths) ? a.allPaths : [];
-      const shown = Array.isArray(a.paths) ? a.paths : [];
-      const text = `${a.summary}\n完整路径（直接 Read；Glob/Grep 也能用）：\n${shown.map(p => `- ${p}`).join('\n')}`
-        + (a.hasBinaryDocs ? `\n${BINARY_DOC_HINT}` : '');
-      sections.push({ key: 'assets', title: '素材', text, items: all, hasBinaryDocs: a.hasBinaryDocs });
-    }
-  } catch { /* 素材读不到就沉默 */ }
-
-  // spec.json 遗产决策：取最近 N 条
-  try {
-    const specPath = path.join(workspaceRoot, 'spec.json');
-    const stat = await fs.stat(specPath);
-    if (stat.size <= SPEC_JSON_MAX_BYTES) {
-      const spec = JSON.parse(await fs.readFile(specPath, 'utf8'));
-      const decisions = Array.isArray(spec?.decisions) ? spec.decisions : [];
-      if (decisions.length > 0) {
-        const recent = decisions.slice(-SPEC_DECISIONS_TAIL);
-        const lines = recent.map((d, i) => {
-          const idx = decisions.length - recent.length + i + 1;
-          const title = (d?.title || '(无标题)').slice(0, 80);
-          const rationale = (d?.rationale || '').slice(0, 200);
-          return `  ${idx}. ${title}${rationale ? ` — ${rationale}` : ''}`;
-        }).join('\n');
-        sections.push({ key: 'decisions', title: '旧决策档案', text: `旧决策档案（spec.json 遗产，共 ${decisions.length} 条，最近 ${recent.length} 条；新决策一律走 record_decision → 任务便利贴）：\n${lines}` });
-      }
-    }
-  } catch { /* spec.json 不存在 / 解析失败：noop */ }
-
-  // 便利贴：metadata-not-content，只列文件和首行标题
-  try {
-    const notesDir = path.join(workspaceRoot, 'notes');
-    const noteFiles = (await fs.readdir(notesDir)).filter(n => n.endsWith('.md') && !n.startsWith('.'));
-    const lines = []; const items = [];
-    for (const n of noteFiles.slice(0, 12)) {
-      let title = ''; let faces = 0;
-      try {
-        const raw = await fs.readFile(path.join(notesDir, n), 'utf8');
-        title = (raw.match(/^#\s+(.{1,60})/m)?.[1] || '').trim();
-        faces = raw.split(/\n---\n/).length;
-      } catch { /* 列出文件名就够 */ }
-      const meta = [title, faces > 1 ? `${faces} 面` : ''].filter(Boolean).join(' · ');
-      lines.push(`  notes/${n}${meta ? `（${meta}）` : ''}`);
-      items.push(`notes/${n}`);
-    }
-    if (lines.length) sections.push({ key: 'notes', title: '便利贴', text: `便利贴（和用户共享，他看得到也可能改过；细节 Read）：\n${lines.join('\n')}`, items });
-  } catch { /* notes/ 不存在：noop */ }
-
-  // 画布关系线：用户画的排前面
-  try {
-    const digest = await relationsDigest(projectId, { limit: 12 });
-    if (digest) {
-      sections.push({ key: 'relations', title: '画布关系线', text: `画布关系线（用户和你手动画的连线，端点跟着改名走；语义看线上的词）：\n${digest}\n  产出新东西后记得用 relate_on_board 把「改自/对照/接着/取材」画上去。` });
-    }
-  } catch { /* 板读不到就沉默 */ }
-
-  // 产物清单：按形态报（deck 报页数，站点报页面清单 + 产物根）
-  try {
-    const artifacts = await listWorkspaceArtifacts(workspaceRoot);
-    if (artifacts.length === 0) {
-      sections.push({ key: 'artifacts', title: '产物', text: `这个工作区还没有产物 —— 直接在工作区根上写：deck 写 ${ENTRY_FILE[KIND_DECK]}，站点写 ${ENTRY_FILE[KIND_SITE]}。` });
-    } else {
-      const active = getActiveArtifact(sessionId)?.path || null;
-      const lines = [];
-      let manifest = null;
-      for (const a of artifacts.slice(0, 8)) {
-        let note = '';
-        try {
-          if (!manifest) manifest = await taskManifest(workspaceRoot);
-          const art = manifest?.artifacts?.find(x => x.entryRel === a.rel) || null;
-          note = art ? await kindDef(art.kind).describe(workspaceRoot, art) : '还判不出形态';
-        } catch { note = '读不到'; }
-        lines.push(`  ${a.rel}（${note}）${a.rel === active ? '  ← 画布工具默认打这份' : ''}`);
-      }
-      sections.push({ key: 'artifacts', title: '产物', text: `现有产物：\n${lines.join('\n')}` });
-    }
-  } catch { /* 扫不动就不说 */ }
-
-  // tweaks 开关：文件不存在 = 用户没碰过 = 沉默
-  try {
-    const cfg = await readUiConfigFile(workspaceRoot);
-    if (cfg) {
-      const on = cfg?.tweaks_mode_enabled !== false;
-      sections.push({ key: 'tweaks', title: 'Tweaks 开关', text: on
-        ? '【Tweaks 模式：启用】用户偏好"可调产品"——deck 形态稳定后，建议调 expose_tweaks 暴露核心微调参数（颜色 / 字号 / 排版密度等）让用户拖滑杆即时改样式。'
-        : '【Tweaks 模式：禁用】用户在 toolbar 关闭了 Tweaks——这次跳过 expose_tweaks，按对话方式让用户提需求你来 Edit。已暴露的 controls 保留不动，不新增 / 不重 expose。' });
-    }
-  } catch { /* 读失败：默认行为，不注入 */ }
-
-  return sections;
-}
-
-/**
- * 把各节渲染成这一轮的注入文本（纯函数，可单测）。
- * @param {Array} sections  collectSections 的结果
- * @param {Map|null} prev   上一轮记忆（null = 首轮）
- * @returns {{ text: string|null, next: Map }}
- */
-export function renderTurnState(sections, prev) {
-  const next = new Map();
-  for (const s of sections) next.set(s.key, { hash: fingerprint(s.text), items: s.items ? [...s.items] : null, hasBinaryDocs: !!s.hasBinaryDocs });
-  if (!sections.length) return { text: null, next };
-
-  if (!prev) {
-    const body = sections.map(s => s.text).join('\n\n');
-    return { text: `[NoDesign 工作台自动注入的当前状态]\n\n${body}\n\n请基于这些信息处理用户的请求。`, next };
-  }
-
-  const changed = []; const unchanged = []; const gone = [];
-  for (const s of sections) {
-    const p = prev.get(s.key);
-    if (!p) { changed.push(`（新出现）${s.text}`); continue; }
-    if (p.hash === next.get(s.key).hash) { unchanged.push(s.title); continue; }
-    if (s.items && p.items) {
-      const d = diffItems(p.items, s.items);
-      const bits = [];
-      if (d.added.length) bits.push(`新增 ${d.added.length}：${d.added.slice(0, 8).join('、')}${d.added.length > 8 ? ' 等' : ''}`);
-      if (d.removed.length) bits.push(`移除 ${d.removed.length}：${d.removed.slice(0, 8).join('、')}${d.removed.length > 8 ? ' 等' : ''}`);
-      if (bits.length) {
-        let line = `${s.title}（有变化）：${bits.join('；')}（现共 ${s.items.length} 件）`;
-        if (s.hasBinaryDocs && !p.hasBinaryDocs) line += `\n${BINARY_DOC_HINT}`;
-        changed.push(line);
-        continue;
-      }
-    }
-    changed.push(`（有变化）${s.text}`);
-  }
-  for (const [key] of prev) if (!next.has(key)) gone.push(key);
-  const lines = [];
-  if (changed.length) lines.push(...changed);
-  if (gone.length) lines.push(`（已不存在：${gone.join('、')}）`);
-  if (!changed.length && !gone.length) {
-    return { text: `[工作台状态：与上轮相同（${unchanged.join('、')}）]`, next };
-  }
-  lines.push(`未变：${unchanged.join('、') || '（无）'}`);
-  return { text: `[工作台状态 · 只报变化]\n\n${lines.join('\n\n')}`, next };
-}
-
-export function makeUserPromptSubmitHandler({ ctx: _ctx, workspaceRoot, sessionId, projectId }) {
-  return async (_input, _toolUseId, _options) => {
-    try {
-      if (!workspaceRoot) return {};
-      const sections = await collectSections({ workspaceRoot, sessionId, projectId });
-      const prev = getTurnMemory(sessionId)?.sections || null;
-      const { text, next } = renderTurnState(sections, prev);
-      setTurnMemory(sessionId, next);
-      if (!text) return {};
-      // 不 emit 业务事件 —— additionalContext 注入是私域提示，不需要前端展示
-      return { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text } };
-    } catch (err) {
-      console.warn('[hooks/UserPromptSubmit] handler threw:', err.message);
-      return {};
-    }
-  };
-}
+/**
+ * UserPromptSubmit handler — 每次用户输入前注入工作区**状态**（2026-08-21 重做）
+ *
+ * 注的是状态不是指令：cwd、素材清单、旧决策、便利贴、画布关系线、产物清单、tweaks 开关。
+ * 怎么用这些东西（路径表、"先看有没有现成的素材"、工具怎么选）住 prelude，那是缓存的
+ * system prompt；每轮再说一遍是上下文里的 N 倍重复。
+ *
+ * ## 首轮全量，之后只报变化
+ *
+ * 以前每轮全量（实测 540~1300 token/轮），30 轮下来对话历史里是十几份几乎相同的块。
+ * 现在每节算指纹记在 turn-state-memory.js（按 sessionId）：
+ *   - 首轮（或压缩后 / 进程重启后）：全量 + 结尾"请基于这些信息处理用户的请求"
+ *   - 之后：变了的节全文（标「有变化」），素材/便利贴这种清单只报新增/移除；没变的节
+ *     只在末尾一行点名"未变：…"（让模型知道它们还在，但不重复内容）；一节都没变就一句话
+ *
+ * ## 素材块从 turn-compose 搬过来（同日）
+ *
+ * 以前 assets 摘要是 turn-compose 拼进**用户消息**里的 <system> 块，跟这里的状态块是
+ * 两条线两个真相源；而且那块写着"assets/ 是 symlink 别用 Glob"—— 08-07 扁平化后早就是
+ * 真目录了。现在合成这一条线，symlink 那句删掉。
+ *
+ * input: UserPromptSubmitHookInput — output: { hookSpecificOutput: { additionalContext } }
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { readUiConfigFile } from '../../../projects/ui-config.js';
+import { readAssetsSummary } from '../../../projects/assets-summary.js';
+import { relationsDigest } from '../../../lib/board-relations.js';
+import {
+  getActiveArtifact, listWorkspaceArtifacts, taskManifest, kindDef,
+  KIND_DECK, KIND_SITE, ENTRY_FILE,
+} from '../../../lib/artifact-target.js';
+import { getTurnMemory, setTurnMemory, fingerprint, diffItems } from './turn-state-memory.js';
+
+/** UserPromptSubmit hook 读取 spec.json 时的最大字节数 */
+const SPEC_JSON_MAX_BYTES = 200 * 1024;
+/** spec.json.decisions 注入摘要时取最近 N 条 */
+const SPEC_DECISIONS_TAIL = 5;
+
+/** PDF/Office 文档的解法（系统自带工具；python 包没装且装不上 —— 08-19 上报实锤）。只在首次出现二进制文档时说一遍。 */
+const BINARY_DOC_HINT = 'PDF / PPTX / DOCX / XLSX 直接 Read 拿不到结构化内容（二进制或 zip 包）。用系统自带的工具解'
+  + '（pdfplumber/PyPDF2/python-docx/openpyxl 这些 python 包**没装且装不上**，别试）：'
+  + 'pdf 文本 `pdftotext -layout 文件.pdf -`；pdf 转页图 `pdftoppm -png -r 100 文件.pdf 页前缀` 再 Read 图片；pdf 嵌入图 `pdfimages -png`。'
+  + 'docx/pptx/xlsx 用 `soffice --headless --convert-to txt|csv|pdf --outdir 目录 文件`（xlsx 转 csv；⚠️ soffice 吃不下中文文件名，先拷成 ASCII 名，并加 `-env:UserInstallation=file:///tmp/lo-任意名` 免得和渲染管线抢 profile）；'
+  + 'docx/pptx 里的嵌入图直接 `unzip -o 文件 "word/media/*"`（pptx 是 `ppt/media/*`）。'
+  + '**提取出来的不只是文本，通常还包含嵌入图片** —— 提取完一定 Read 看图片，别只看 stdout 文本就以为信息齐了。';
+
+/**
+ * 采集各节。每节 { key, title, text, items? }：text 是全量文案；items 是可按项报变化的清单。
+ * 任一节采不到就不出现（跟以前一样：扫不动就不说，别拿错信息误导）。
+ */
+async function collectSections({ workspaceRoot, sessionId, projectId }) {
+  const sections = [];
+
+  // cwd：唯一真正动态的一行。路径表（./ notes/ assets/ .claude/agent-memory/ 各是什么）在 prelude
+  sections.push({ key: 'cwd', title: '工作区', text: `你的 cwd 是 ${workspaceRoot} —— 项目工作区，产物直接住这儿（路径表见 prelude「你跑在哪」）。` });
+
+  // 素材：顶层 assets/ + assets/references/**（逛站采回来的）
+  try {
+    const a = await readAssetsSummary(workspaceRoot);
+    if (a.count > 0) {
+      const all = Array.isArray(a.allPaths) ? a.allPaths : [];
+      const shown = Array.isArray(a.paths) ? a.paths : [];
+      const text = `${a.summary}\n完整路径（直接 Read；Glob/Grep 也能用）：\n${shown.map(p => `- ${p}`).join('\n')}`
+        + (a.hasBinaryDocs ? `\n${BINARY_DOC_HINT}` : '');
+      sections.push({ key: 'assets', title: '素材', text, items: all, hasBinaryDocs: a.hasBinaryDocs });
+    }
+  } catch { /* 素材读不到就沉默 */ }
+
+  // spec.json 遗产决策：取最近 N 条
+  try {
+    const specPath = path.join(workspaceRoot, 'spec.json');
+    const stat = await fs.stat(specPath);
+    if (stat.size <= SPEC_JSON_MAX_BYTES) {
+      const spec = JSON.parse(await fs.readFile(specPath, 'utf8'));
+      const decisions = Array.isArray(spec?.decisions) ? spec.decisions : [];
+      if (decisions.length > 0) {
+        const recent = decisions.slice(-SPEC_DECISIONS_TAIL);
+        const lines = recent.map((d, i) => {
+          const idx = decisions.length - recent.length + i + 1;
+          const title = (d?.title || '(无标题)').slice(0, 80);
+          const rationale = (d?.rationale || '').slice(0, 200);
+          return `  ${idx}. ${title}${rationale ? ` — ${rationale}` : ''}`;
+        }).join('\n');
+        sections.push({ key: 'decisions', title: '旧决策档案', text: `旧决策档案（spec.json 遗产，共 ${decisions.length} 条，最近 ${recent.length} 条；新决策一律走 record_decision → 任务便利贴）：\n${lines}` });
+      }
+    }
+  } catch { /* spec.json 不存在 / 解析失败：noop */ }
+
+  // 便利贴：metadata-not-content，只列文件和首行标题
+  try {
+    const notesDir = path.join(workspaceRoot, 'notes');
+    const noteFiles = (await fs.readdir(notesDir)).filter(n => n.endsWith('.md') && !n.startsWith('.'));
+    const lines = []; const items = [];
+    for (const n of noteFiles.slice(0, 12)) {
+      let title = ''; let faces = 0;
+      try {
+        const raw = await fs.readFile(path.join(notesDir, n), 'utf8');
+        title = (raw.match(/^#\s+(.{1,60})/m)?.[1] || '').trim();
+        faces = raw.split(/\n---\n/).length;
+      } catch { /* 列出文件名就够 */ }
+      const meta = [title, faces > 1 ? `${faces} 面` : ''].filter(Boolean).join(' · ');
+      lines.push(`  notes/${n}${meta ? `（${meta}）` : ''}`);
+      items.push(`notes/${n}`);
+    }
+    if (lines.length) sections.push({ key: 'notes', title: '便利贴', text: `便利贴（和用户共享，他看得到也可能改过；细节 Read）：\n${lines.join('\n')}`, items });
+  } catch { /* notes/ 不存在：noop */ }
+
+  // 画布关系线：用户画的排前面
+  try {
+    const digest = await relationsDigest(projectId, { limit: 12 });
+    if (digest) {
+      sections.push({ key: 'relations', title: '画布关系线', text: `画布关系线（用户和你手动画的连线，端点跟着改名走；语义看线上的词）：\n${digest}\n  产出新东西后记得用 relate_on_board 把「改自/对照/接着/取材」画上去。` });
+    }
+  } catch { /* 板读不到就沉默 */ }
+
+  // 产物清单：按形态报（deck 报页数，站点报页面清单 + 产物根）
+  try {
+    const artifacts = await listWorkspaceArtifacts(workspaceRoot);
+    if (artifacts.length === 0) {
+      sections.push({ key: 'artifacts', title: '产物', text: `这个工作区还没有产物 —— 直接在工作区根上写：deck 写 ${ENTRY_FILE[KIND_DECK]}，站点写 ${ENTRY_FILE[KIND_SITE]}。` });
+    } else {
+      const active = getActiveArtifact(sessionId)?.path || null;
+      const lines = [];
+      let manifest = null;
+      for (const a of artifacts.slice(0, 8)) {
+        let note = '';
+        try {
+          if (!manifest) manifest = await taskManifest(workspaceRoot);
+          const art = manifest?.artifacts?.find(x => x.entryRel === a.rel) || null;
+          note = art ? await kindDef(art.kind).describe(workspaceRoot, art) : '还判不出形态';
+        } catch { note = '读不到'; }
+        lines.push(`  ${a.rel}（${note}）${a.rel === active ? '  ← 画布工具默认打这份' : ''}`);
+      }
+      sections.push({ key: 'artifacts', title: '产物', text: `现有产物：\n${lines.join('\n')}` });
+    }
+  } catch { /* 扫不动就不说 */ }
+
+  // tweaks 开关：文件不存在 = 用户没碰过 = 沉默
+  try {
+    const cfg = await readUiConfigFile(workspaceRoot);
+    if (cfg) {
+      const on = cfg?.tweaks_mode_enabled !== false;
+      sections.push({ key: 'tweaks', title: 'Tweaks 开关', text: on
+        ? '【Tweaks 模式：启用】用户偏好"可调产品"——deck 形态稳定后，建议调 expose_tweaks 暴露核心微调参数（颜色 / 字号 / 排版密度等）让用户拖滑杆即时改样式。'
+        : '【Tweaks 模式：禁用】用户在 toolbar 关闭了 Tweaks——这次跳过 expose_tweaks，按对话方式让用户提需求你来 Edit。已暴露的 controls 保留不动，不新增 / 不重 expose。' });
+    }
+  } catch { /* 读失败：默认行为，不注入 */ }
+
+  return sections;
+}
+
+/**
+ * 把各节渲染成这一轮的注入文本（纯函数，可单测）。
+ * @param {Array} sections  collectSections 的结果
+ * @param {Map|null} prev   上一轮记忆（null = 首轮）
+ * @returns {{ text: string|null, next: Map }}
+ */
+export function renderTurnState(sections, prev) {
+  const next = new Map();
+  for (const s of sections) next.set(s.key, { hash: fingerprint(s.text), items: s.items ? [...s.items] : null, hasBinaryDocs: !!s.hasBinaryDocs });
+  if (!sections.length) return { text: null, next };
+
+  if (!prev) {
+    const body = sections.map(s => s.text).join('\n\n');
+    return { text: `[NoDesign 工作台自动注入的当前状态]\n\n${body}\n\n请基于这些信息处理用户的请求。`, next };
+  }
+
+  const changed = []; const unchanged = []; const gone = [];
+  for (const s of sections) {
+    const p = prev.get(s.key);
+    if (!p) { changed.push(`（新出现）${s.text}`); continue; }
+    if (p.hash === next.get(s.key).hash) { unchanged.push(s.title); continue; }
+    if (s.items && p.items) {
+      const d = diffItems(p.items, s.items);
+      const bits = [];
+      if (d.added.length) bits.push(`新增 ${d.added.length}：${d.added.slice(0, 8).join('、')}${d.added.length > 8 ? ' 等' : ''}`);
+      if (d.removed.length) bits.push(`移除 ${d.removed.length}：${d.removed.slice(0, 8).join('、')}${d.removed.length > 8 ? ' 等' : ''}`);
+      if (bits.length) {
+        let line = `${s.title}（有变化）：${bits.join('；')}（现共 ${s.items.length} 件）`;
+        if (s.hasBinaryDocs && !p.hasBinaryDocs) line += `\n${BINARY_DOC_HINT}`;
+        changed.push(line);
+        continue;
+      }
+    }
+    changed.push(`（有变化）${s.text}`);
+  }
+  for (const [key] of prev) if (!next.has(key)) gone.push(key);
+  const lines = [];
+  if (changed.length) lines.push(...changed);
+  if (gone.length) lines.push(`（已不存在：${gone.join('、')}）`);
+  if (!changed.length && !gone.length) {
+    return { text: `[工作台状态：与上轮相同（${unchanged.join('、')}）]`, next };
+  }
+  lines.push(`未变：${unchanged.join('、') || '（无）'}`);
+  return { text: `[工作台状态 · 只报变化]\n\n${lines.join('\n\n')}`, next };
+}
+
+export function makeUserPromptSubmitHandler({ ctx: _ctx, workspaceRoot, sessionId, projectId }) {
+  return async (_input, _toolUseId, _options) => {
+    try {
+      if (!workspaceRoot) return {};
+      const sections = await collectSections({ workspaceRoot, sessionId, projectId });
+      const prev = getTurnMemory(sessionId)?.sections || null;
+      const { text, next } = renderTurnState(sections, prev);
+      setTurnMemory(sessionId, next);
+      if (!text) return {};
+      // 不 emit 业务事件 —— additionalContext 注入是私域提示，不需要前端展示
+      return { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text } };
+    } catch (err) {
+      console.warn('[hooks/UserPromptSubmit] handler threw:', err.message);
+      return {};
+    }
+  };
+}