@xiaobuyu/nodesign 0.0.1

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

@@ -0,0 +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 {};
+    }
+  };
+}

package/server/engine/agent/hooks.js

@@ -0,0 +1,354 @@
+/**
+ * server/engine/agent/hooks.js — agent hooks 组装层
+ *
+ * 2026-08-14 可维护性行动：1975 行的单文件拆成「这里只做注册与出厂断言，
+ * handler 工厂按家族住 hooks/ 目录」。改某个钩子的行为去对应模块；
+ * 改「哪个事件挂哪些钩子」才来这里。
+ *
+ *   hooks/pre-defaults.js            PreToolUse 默认值矫正（Agent 前台 / Grep content）
+ *   hooks/pre-injectors.js           首调注入族（cookbook / 协议 / 提醒，每 session 一次）
+ *   hooks/pre-starter-files.js       skill 起手文件拷贝（Skill 主路 + Bash 兜底）
+ *   hooks/pre-board-neighborhood.js  关系线邻域注入（Read|Edit|Write）
+ *   hooks/user-prompt-submit.js      每 turn 状态注入（路径地图 / 决策 / 便利贴 / 产物清单）
+ *   hooks/file-events.js             文件改动 → run.file_changed（watcher 型 + 确定性直发）
+ *   hooks/lifecycle.js               SessionStart / Stop / PostCompact / Subagent 生命周期
+ *   hooks/post-trim.js               Edit|Write tool_response.originalFile 瘦身
+ *   hooks/post-canvas-focus.js       改动落页检测 → run.canvas_focus_page
+ *   hooks/post-guidance.js           行为引导（截图自检 / 交付告知 / 重生看门狗 / 风格锚）
+ *   hooks/canvas-validate.js         canvas.html 一致性校验（anchor 唯一 / layout 组件 / role）
+ *   hooks/failure.js                 PostToolUseFailure 恢复建议 + 自动问题记录
+ *   hooks/tool-prompts.js            prompts/tools/*.md 懒加载缓存（注入族共用）
+ *
+ * 调用方式：session-loop.js 在拼 sdkOptions 时调
+ *   hooks: createHooks({ ctx, workspaceRoot, projectId })
+ *
+ * SDK Hook 接口：
+ *   HookCallback = (input, toolUseId, { signal }) => Promise<HookJSONOutput>
+ *   HookJSONOutput.SyncHookJSONOutput 关键字段（sdk.d.ts:5283）：
+ *     - continue?: boolean              false 中断 query
+ *     - decision?: 'approve' | 'block'  控制流（PreToolUse 用 block 拒工具）
+ *     - hookSpecificOutput?: { ... }    各 hook 自己的输出（如
+ *                                       PreToolUseHookSpecificOutput.permissionDecision /
+ *                                       UserPromptSubmitHookSpecificOutput.additionalContext)
+ *     - systemMessage?: string          注入 system message 给后续轮
+ *     - reason?: string                 给用户看的原因（block 时）
+ *
+ *   返回 {} 表示"通过，不干预"。
+ *
+ * 设计原则：
+ *   - hook handler 必须**快**（不阻塞 agent loop）。fs 读取限制小文件 + 失败 fail-soft。
+ *   - hook handler 不抛异常（SDK 内部会吞，但保险起见自己 try/catch）。
+ *   - hook handler 通过 ctx.emit 发事件让前端可见，但不阻塞返回。
+ *   - additionalContext 注入要简短直接 —— 不让 agent 觉得需要"回应这条系统消息"，
+ *     只是提示"已发生 X"。
+ */
+
+import {
+  makePreToolUseAgentForceForegroundHandler,
+  makePreToolUseGrepContentDefaultHandler,
+} from './hooks/pre-defaults.js';
+import {
+  makePreToolUseGetPendingChangesProtocolInjector,
+  makePreToolUseAskUserQuestionProtocolInjector,
+  makePreToolUseHybridReferenceInjector,
+  makePreToolUsePaintStillCookbookInjector,
+  makePreToolUseRollFilmCookbookInjector,
+  makePreToolUseGenerateImageCookbookInjector,
+  makePreToolUseGenerateImageReadPageReminder,
+  makePreToolUseExposeTweaksSyntaxInjector,
+  makePreToolUseTaskVisionCheckerDispatchInjector,
+} from './hooks/pre-injectors.js';
+import {
+  makePreToolUseSkillStarterFilesCopier,
+  makePreToolUseBashStarterFilesFallback,
+} from './hooks/pre-starter-files.js';
+import { makePreToolUseBoardNeighborhoodInjector } from './hooks/pre-board-neighborhood.js';
+import { makePreToolUsePerformanceLogGuard } from './hooks/pre-performance-log-guard.js';
+import { makePreToolUseWorkspaceScopeGuard } from './hooks/pre-workspace-scope-guard.js';
+import { PROJECTS_DATA_ROOT } from '../../projects/workspace.js';
+import { makeUserPromptSubmitHandler } from './hooks/user-prompt-submit.js';
+import {
+  makeFileChangedHandler,
+  makePostToolUseFileChangedEmitter,
+} from './hooks/file-events.js';
+import {
+  makeSessionStartHandler,
+  makeStopReflectionHandler,
+  makePostCompactHandler,
+  makeSubagentStartHandler,
+  makeSubagentStopHandler,
+} from './hooks/lifecycle.js';
+import { makePostToolUseEditWriteTrimHandler } from './hooks/post-trim.js';
+import { makePostToolUseCanvasFocusPageHandler } from './hooks/post-canvas-focus.js';
+import {
+  makePostToolUseScreenshotHandler,
+  makePostToolUseExportHandler,
+  makePostToolUseGenerateImageRegenWatchdog,
+  makePostToolUseStyleAnchorNudge,
+} from './hooks/post-guidance.js';
+import { makePostToolUseCanvasValidationHandler } from './hooks/canvas-validate.js';
+import { makePostToolUseSiteValidationHandler } from './hooks/site-validate.js';
+import { makePostToolUseFailureHandler } from './hooks/failure.js';
+import { makePostToolUseSubagentReportRecovery } from './hooks/post-subagent-report.js';
+
+/**
+ * 工厂：根据当前 run 上下文 + workspace 路径生成 hooks 配置。
+ *
+ * @param {object} deps
+ * @param {import('./context.js').AgentContext} deps.ctx
+ * @param {string} deps.workspaceRoot
+ * @param {string} [deps.projectId]
+ * @returns {Partial<Record<string, Array<{ matcher?: string, hooks: Function[], timeout?: number }>>>}
+ */
+export function createHooks({ ctx, workspaceRoot, sharedRoot, sessionId, projectId } = {}) {
+  return assertHooksWellFormed({
+    // ── P0+ stage 1（不动）──
+
+    // FileChanged → EventBus emit run.file_changed → 前端 reload iframe。
+    // ⚠️ 2026-07-28 实测：这是 watcher 型 hook，需要有 hook 先返回
+    // hookSpecificOutput.watchPaths 声明监听路径 watcher 才会启动 —— 我们从没
+    // 声明过，所以它一次都没触发过。注册保留（将来开 watcher 可覆盖 bash/子代理
+    // 写文件），实时刷新真正走下面 PostToolUse 的确定性直发。
+    FileChanged: [{
+      hooks: [makeFileChangedHandler({ ctx, workspaceRoot })],
+    }],
+
+    // ~~PreToolUse(Bash) 白名单~~ Phase 3d 删 —— 改用 session-loop.js sandbox option
+    // OS 级隔离（macOS sandbox-exec / Linux bubblewrap），filesystem.allowWrite/denyRead
+    // 替代命令级正则。
+
+    // PreToolUse Agent：强制子代理前台跑，主 agent 才拿得到报告。
+    //
+    // matcher 写 'Task|Agent'：SDK 0.3 起工具真名叫 **Agent**，'Task' 是旧别名
+    // （sdk.mjs 的 i6 表 Task→Agent，binary 侧 matcher 也吃这个别名 —— 2026-08-03
+    // 双 matcher 探针实测两个都命中）。两个都写，换 SDK 版本时不会静默失配。
+    PreToolUse: [{
+      // 演出记录隐私闸：Read/Grep 直接点到演出文件夹的对话记录 → deny + 教义
+      //（RP 台词只走 chatai 通路不进设计会话；写不拦——建场要种开场白）。
+      // ⚠️ 边界写清楚：**只拦点名那一种读法**。`Grep path=<目录>` 和 Bash `cat`
+      // 都过得去 —— 08-15 补过那两条（Grep 注排除 glob + Bash 命令闸），因为
+      // 连带面太宽被用户撤回：固定记录名靠项目 .gitignore 兜（ripgrep 默认跳过
+      // 被 gitignore 的文件），剩下的靠 rp-craft 的隐私纪律。
+      matcher: 'Read|Grep',
+      hooks: [makePreToolUsePerformanceLogGuard({ workspaceRoot })],
+    }, {
+      // 项目边界闸：结构化工具不进 bwrap，沙盒管不着它们跨项目读写 ——
+      // 数据根里、又不在本工作区里的路径一律拒。见 pre-workspace-scope-guard.js
+      matcher: 'Read|Grep|Glob|Write|Edit|NotebookEdit',
+      hooks: [makePreToolUseWorkspaceScopeGuard({ workspaceRoot, dataRoot: PROJECTS_DATA_ROOT })],
+    }, {
+      matcher: 'Task|Agent',
+      hooks: [
+        makePreToolUseAgentForceForegroundHandler(),
+        // vision-checker 派遣 prompt 模板首次注入（仅当 subagent_type='vision-checker'）
+        makePreToolUseTaskVisionCheckerDispatchInjector(),
+      ],
+    }, {
+      // ⚠️ Grep 的输入改写只许有这一个 handler——两个各返回 updatedInput 会互相抹掉
+      matcher: 'Grep',
+      hooks: [makePreToolUseGrepContentDefaultHandler()],
+    }, {
+      // Skill 加载 deskskill 时才拷起手文件（canvas.template.html 等）——
+      // 2026-07-27 起从 session-loop init 挪到这里：session ≠ 默认 deck 任务
+      matcher: 'Skill',
+      hooks: [makePreToolUseSkillStarterFilesCopier({ workspaceRoot })],
+    }, {
+      // 兜底：agent 没走 Skill 直接 cp canvas.template.html → 现场补拷
+      matcher: 'Bash',
+      hooks: [makePreToolUseBashStarterFilesFallback({ workspaceRoot })],
+    }, {
+      // get_pending_changes 首次调用时注入 DirectEdit 逐 kind 处理协议全文
+      // （prelude 只留流程骨架，~90 行细则挪到 prompts/tools/direct-edit-protocol.md）
+      matcher: 'mcp__nodesign__get_pending_changes',
+      hooks: [makePreToolUseGetPendingChangesProtocolInjector()],
+    }, {
+      // generate_image 两个 hook 串：先目标页提醒（已有），再首次注 cookbook 完整版
+      matcher: 'mcp__nodesign__generate_image',
+      hooks: [
+        makePreToolUseGenerateImageReadPageReminder(),
+        makePreToolUseGenerateImageCookbookInjector(),
+      ],
+    }, {
+      // roll_film 首次调用时注入 H3 三字段提示词手册（纪律配方全在里面）
+      matcher: 'mcp__nodesign__roll_film',
+      hooks: [makePreToolUseRollFilmCookbookInjector()],
+    }, {
+      // paint_still 首次调用时注入本地生图手册（四模型选型+BFL 官方提示词实践）
+      // 08-20 起 lookup_tags 也触发：纪律是"先查后画"，手册得在第一次查的时候就到
+      matcher: 'mcp__nodesign__(paint_still|lookup_tags)',
+      hooks: [makePreToolUsePaintStillCookbookInjector()],
+    }, {
+      // AskUserQuestion 首次调用时注入 NoDesign 的 preview 协议（2026-07-28 从
+      // prelude 挪来：常驻 1.2k tokens，但只有真要问用户时才用得上）
+      matcher: 'AskUserQuestion',
+      hooks: [makePreToolUseAskUserQuestionProtocolInjector()],
+    }, {
+      // expose_tweaks 首次调用时注入完整语法
+      matcher: 'mcp__nodesign__expose_tweaks',
+      hooks: [makePreToolUseExposeTweaksSyntaxInjector()],
+    }, {
+      // 关系线邻域（2026-08-14 切片③）：agent 摸某个文件时，把连着它的线注进来。
+      // UserPromptSubmit 的全图摘要截断后，这里做精确补充。每个文件一个会话只注一次。
+      matcher: 'Read|Edit|Write',
+      hooks: [makePreToolUseBoardNeighborhoodInjector({ workspaceRoot, projectId })],
+    }, {
+      matcher: 'Write',
+      hooks: [
+        // Write canvas.html 首次调用时提醒 agent 先 Read 拿 verbatim boilerplate
+        // （SDK 对 Write 没有 Edit 那样的"必须 Read"强约束，凭印象重写 importmap /
+        // shadcn-lite 容易差字节 → deck 看着写出来但浏览器加载不出 React）
+        // 首次写 HTML 时注入该形态的技术参考（deck: 模板结构 / 标记规约 / 库速查 /
+        // 常坑；site: 目录约定 / 相对路径铁律 / 响应式与中文排版）。2026-07-28 从
+        // prelude 搬来：那是参考知识不是行为，常驻 1.4k tokens 每轮都在，但只有真
+        // 动 HTML 的那一刻用得上。
+        makePreToolUseHybridReferenceInjector({ workspaceRoot }),
+      ],
+    }],
+
+    // Stop —— agent 准备结束 query 时触发，发自检事件给前端
+    Stop: [{
+      hooks: [makeStopReflectionHandler({ ctx, workspaceRoot })],
+    }],
+
+    // PostCompact —— compact 后把摘要写入 spec.json 长期记忆
+    PostCompact: [{
+      hooks: [makePostCompactHandler({ ctx, workspaceRoot, sessionId })],
+    }],
+
+    // ── Phase 2 升级 ──
+
+    // SessionStart —— 之前是 noop 占位；现在 emit 一条事件让上层知道
+    // session 是 startup / resume / clear / compact（注：clear 是 /clear 斜杠命令）
+    SessionStart: [{
+      hooks: [makeSessionStartHandler({ ctx })],
+    }],
+
+    // UserPromptSubmit —— 每次用户输入前注入工作区状态（素材 / 决策 / 便利贴 / 关系线 /
+    // 产物 / tweaks）。08-21 起首轮全量、之后只报变化（hooks/turn-state-memory.js）。
+    UserPromptSubmit: [{
+      hooks: [makeUserPromptSubmitHandler({ ctx, workspaceRoot, sessionId, projectId })],
+    }],
+
+    // PostToolUse —— 按 MCP 工具名分别注 additionalContext，引导 agent 利用
+    // 工具结果。matcher 字段是 SDK 标准（与 PreToolUse 'Bash' 同语义）。
+    PostToolUse: [
+      // Edit/Write 后干掉 tool_response.originalFile：FileEditOutput/FileWriteOutput
+      // 默认含完整原文件（sdk-tools.d.ts:2270, 2328），这是上下文累积大头。
+      // canvas.html 25KB 一次 Edit ≈ 6k tokens，30 turn 累积可达 180k+ → 触发 256k 上限。
+      // 模型有 structuredPatch (diff 行) 看改动够了，原文件需要再用 Read 拿。
+      {
+        matcher: 'Edit|Write',
+        hooks: [makePostToolUseEditWriteTrimHandler({ ctx })],
+      },
+      // 子代理报告丢失兜底（2026-08-18）：SDK 触 maxTurns 时返回的错误类型不带
+      // result 字段，最后那条消息（报告本身）整个消失。这个 handler 在报告看起来
+      // 是空的时候把转录 JSONL 的路径递给主 agent —— 从"整轮白烧"变成"多读一个
+      // 文件"。matcher 两个别名都写，理由同上面 PreToolUse 那处。
+      {
+        matcher: 'Task|Agent',
+        hooks: [makePostToolUseSubagentReportRecovery()],
+      },
+      // 写完一笔立刻让前端应用（2026-07-28）：写文件系工具成功即从入参直发
+      // run.file_changed，deck iframe / 产物墙不再等 run.done 才刷新。
+      // （FileChanged watcher hook 从未真正触发过，见上方 FileChanged 注释）
+      {
+        matcher: 'Write|Edit|MultiEdit|NotebookEdit',
+        hooks: [makePostToolUseFileChangedEmitter({ ctx, workspaceRoot, sharedRoot, sessionId })],
+      },
+      // （曾有 Bash mkdir 认领任务钩子，08-08 扁平化随任务模型一起拆除。当时删了
+      // hooks 数组却留下 `{ matcher: 'Bash' }` 空壳 —— SDK initialize 的大 try 被
+      // 它的 TypeError 打穿，全部程序化钩子 + 全部 in-process MCP server 无声蒸发，
+      // 潜伏六天（2026-08-14 空壳钩子灭门案）。删钩子必须删整个条目；下方
+      // assertHooksWellFormed 出厂断言从此拦这类残骸。）
+      // Canvas 焕新升级 S1d — Edit/Write canvas.html 时检测改动落在哪些 page →
+      // emit run.canvas_focus_page（前端 SlideNavigator 跳页 + pulse 高亮）。
+      // 不返 hookSpecificOutput，纯 emit；不阻塞 agent，不注 additionalContext。
+      {
+        matcher: 'Edit|Write',
+        hooks: [makePostToolUseCanvasFocusPageHandler({ ctx })],
+      },
+      {
+        matcher: 'mcp__nodesign__screenshot_canvas',
+        hooks: [makePostToolUseScreenshotHandler({ ctx })],
+      },
+      {
+        matcher: 'mcp__nodesign__export_handoff',
+        hooks: [makePostToolUseExportHandler({ ctx })],
+      },
+      // Phase Image-4：generate_image 调用计数 hook ——
+      // agent 同 outputName regenerate 第 3 次时注 systemMessage 建议
+      // 直接 chat 邀请用户在已有候选中拍板，避免闷头改浪费 token。
+      {
+        matcher: 'mcp__nodesign__generate_image',
+        hooks: [makePostToolUseGenerateImageRegenWatchdog()],
+      },
+      // 2026-05-08 canvas 范式重整 #1/#3/#5/#6 反馈通道 ——
+      // Edit/Write canvas.html 后跑一致性校验（mode-CSS / 必装 CSS / anchor 唯一 /
+      // layout 推荐组件 / role 必装），有 issue 注 systemMessage 单 turn 反馈。
+      // 跨 turn 持续延期下一轮（spec.json schema 扩展）。
+      {
+        matcher: 'Edit|Write',
+        hooks: [
+          makePostToolUseCanvasValidationHandler({ ctx, workspaceRoot }),
+          // 站点页两条硬规则（viewport / 根路径）—— 08-21 起手模板删了，规则改靠 lint 传播
+          makePostToolUseSiteValidationHandler({ workspaceRoot }),
+        ],
+      },
+      // record_decision 一般**不注** additionalContext（"继续主任务"那种跟 SDK
+      // preset 重复，agent 自己懂）。唯一例外是"锚定风格"这一笔：那是项目级
+      // 长期资产该落盘的时刻，而品牌档案 / 项目指引这两处 SDK 不知道。
+      {
+        matcher: 'mcp__nodesign__record_decision',
+        hooks: [makePostToolUseStyleAnchorNudge({ sharedRoot })],
+      },
+    ],
+
+    // PostToolUseFailure —— 任意工具失败时统一处理：emit 事件 + 给 agent
+    // 注入恢复建议（避免重试同样的错）。
+    PostToolUseFailure: [{
+      hooks: [makePostToolUseFailureHandler({ ctx, projectId, sessionId })],
+    }],
+
+    // SubagentStart / SubagentStop —— 主动捕子代理生命周期。当前只 emit 事件
+    // 给上层观察；不阻塞流程。stage 2 真接通子代理时这里加调度逻辑。
+    SubagentStart: [{
+      hooks: [makeSubagentStartHandler({ ctx })],
+    }],
+    SubagentStop: [{
+      hooks: [makeSubagentStopHandler({ ctx })],
+    }],
+  });
+}
+
+/**
+ * 出厂断言（2026-08-14 空壳钩子灭门案第 2 层）：createHooks 出口处校验每个事件
+ * 数组的每个条目都有非空 hooks 数组且全是函数。校验放出口不放调用方 —— 跟着
+ * 真相源走，任何调用路径都逃不过。
+ *
+ * 为什么必须启动即炸：一个 `{ matcher: 'Bash' }` 空壳条目会让 SDK 0.3.218
+ * initialize 的大 try 抛 TypeError 并整段吞掉 —— 全部程序化钩子 + 全部
+ * in-process MCP server 无声蒸发，mcp_servers 里连 failed 都不留，会话照常跑。
+ * 静默降级是六天暗账，启动炸是五分钟定位。
+ */
+function assertHooksWellFormed(hooksByEvent) {
+  for (const [event, entries] of Object.entries(hooksByEvent)) {
+    if (!Array.isArray(entries)) {
+      throw new Error(`[hooks] ${event} 不是数组 —— createHooks 出厂断言拦截`);
+    }
+    entries.forEach((entry, i) => {
+      const bad = !entry
+        || !Array.isArray(entry.hooks)
+        || entry.hooks.length === 0
+        || entry.hooks.some((h) => typeof h !== 'function');
+      if (bad) {
+        const label = entry?.matcher ? ` (matcher: ${entry.matcher})` : '';
+        throw new Error(
+          `[hooks] ${event}[${i}]${label} 是空壳/坏条目（hooks 必须是非空函数数组）。`
+          + '删钩子要删整个条目 —— 空壳会让 SDK initialize 把全部钩子和 in-process '
+          + 'MCP server 无声吞掉（2026-08-14 灭门案）。',
+        );
+      }
+    });
+  }
+  return hooksByEvent;
+}

package/server/engine/agent/init-contract.js

@@ -0,0 +1,69 @@
+/**
+ * server/engine/agent/init-contract.js — 开局契约自检（2026-08-20 从 session-loop.js
+ * 拆出，行数棘轮；逻辑原样）。session-loop 在每条 system:init 到达时调一次。
+ */
+
+import { recordIssue, signatureOf } from '../../lib/issues-store.js';
+
+// ── 开局契约自检（2026-08-14 空壳钩子灭门案第 3 层，真正治本）──
+//
+// 背景：一个 `{ matcher: 'Bash' }` 空壳钩子条目让 SDK initialize 的大 try 吞掉
+// TypeError → 全部程序化钩子 + 全部 in-process MCP server 无声蒸发，mcp_servers
+// 里连 failed 都不留，会话照常跑 —— 潜伏六天。能静默这么久的结构性原因是这里
+// 从来不消费 system:init：SDK 开局就把「会话里实际有哪些 server / 工具」告诉了
+// 我们，但没人看。
+//
+// 现在对账：nodesign 必须 connected，且 server 实例声明的每个工具（探针实测
+// deferred 工具也在 init.tools 里，27/27）都必须出现。不满足 → recordIssue 进
+// 自动层 + throw 杀会话（外层 catch 走真错路径：markRunFailed + run.error 前端
+// 显式可见）。已知代价：SDK 改 init 形状会误杀会话 —— 但误杀 5 分钟定位，
+// 静默降级是 6 天暗账；工具残废的会话产出是负价值还烧钱，杀掉比放行仁慈。
+export function assertInitContract(init, { sessionId, projectId, isResume, initialPermissionMode, platform, sdkModel, nodesignServer }) {
+  const problems = [];
+  const nd = (init.mcp_servers || []).find((s) => s.name === 'nodesign');
+  if (!nd) {
+    problems.push('mcp_servers 里没有 nodesign（in-process MCP server 蒸发，连 failed 状态都不留）');
+  } else if (nd.status !== 'connected') {
+    problems.push(`nodesign server status=${nd.status}（预期 connected）`);
+  }
+  const registered = new Set(init.tools || []);
+  const expected = (nodesignServer.toolNames || []).map((n) => `mcp__nodesign__${n}`);
+  const missing = expected.filter((n) => !registered.has(n));
+  if (missing.length) {
+    problems.push(`nodesign 工具缺 ${missing.length}/${expected.length}：${missing.join(', ')}`);
+  }
+  // 权限模式对账（2026-08-15）：**要的和拿到的可能不一样，而且是静默的**。
+  // 实测：会话模型是 haiku 时 `permissionMode:'auto'` 会被无声降级成 'default'，
+  // init 里照报 default，没有任何报错 —— 分类器一次都不跑，我们却以为它在把关。
+  // 只警告不杀：降级后的会话还能干活，杀掉代价大于收益；但必须在日志里喊出来。
+  const wantMode = isResume ? null : (initialPermissionMode === 'plan' ? 'plan' : platform.permissionModeDefault);
+  if (wantMode && init.permissionMode && init.permissionMode !== wantMode) {
+    console.warn(
+      `[session-loop] ⚠️ sid=${sessionId.slice(0, 8)} 权限模式被降级：要 ${wantMode}，`
+      + `实际 ${init.permissionMode}（模型 ${sdkModel} 可能不支持该模式）`,
+    );
+  }
+  if (!problems.length) {
+    console.info(
+      `[session-loop] sid=${sessionId.slice(0, 8)} init 契约自检 ✓ `
+      + `(nodesign connected, ${expected.length}/${expected.length} tools, `
+      + `mode=${init.permissionMode ?? '未报'})`,
+    );
+    return;
+  }
+  const detail = problems.join('；');
+  // 自动层留案底（fail-soft：记录本身不能变成新故障源）。signature 只含缺失
+  // 集合不含 sessionId —— 同一种蒸发聚成一行计数。
+  try {
+    recordIssue({
+      source: 'auto',
+      toolName: 'session_init_contract',
+      summary: `开局契约自检失败：${detail.slice(0, 120)}`,
+      detail,
+      projectId,
+      sessionId,
+      signature: signatureOf(`session_init_contract|${missing.join(',')}|${nd ? nd.status : 'absent'}`),
+    });
+  } catch { /* ignore */ }
+  throw new Error(`开局契约自检失败（杀会话）：${detail}`);
+}