@xiaobuyu/nodesign 0.0.1

package/server/engine/agent/hooks/failure.js

@@ -0,0 +1,120 @@
+/**
+ * PostToolUseFailure handler — 工具失败时给 agent 恢复建议。
+ * （2026-08-14 可维护性行动：从 hooks.js 原样迁出，语义零改动）
+ *
+ * input: PostToolUseFailureHookInput (sdk.d.ts:1908)
+ *   - tool_name: string
+ *   - tool_input: unknown
+ *   - tool_use_id: string
+ *   - error: string
+ *   - is_interrupt?: boolean
+ *   - duration_ms?: number
+ *
+ * output: PostToolUseFailureHookSpecificOutput (sdk.d.ts:1921)
+ *   - additionalContext?: string
+ */
+import { Events } from '../events.js';
+import { recordIssue, signatureOf } from '../../../lib/issues-store.js';
+
+export function makePostToolUseFailureHandler({ ctx, projectId, sessionId }) {
+  return async (input, _toolUseId, _options) => {
+    const tool = input?.tool_name || 'unknown';
+    const error = String(input?.error || '').slice(0, 500);
+    const isInterrupt = Boolean(input?.is_interrupt);
+
+    try {
+      ctx.emit(Events.toolFailure(tool, error));
+    } catch { /* ignore */ }
+
+    // is_interrupt: 用户中断 → 不注入建议（agent 应该停下，不是恢复）
+    if (isInterrupt) return {};
+
+    // 自动层问题记录（2026-07-30）：每次真失败按"错误类"累加计数。
+    // 这层不依赖 agent 自觉 —— 它太会兜底了，工具坏了换个姿势就绕过去，
+    // 表面上活儿还是干完的，于是"某个工具本周失败 40 次"没人知道。
+    // fail-soft：记录本身绝不能变成新的故障源。
+    try {
+      recordIssue({
+        source: 'auto',
+        toolName: tool,
+        summary: `${tool} 失败：${error.slice(0, 120)}`,
+        detail: error,
+        projectId,
+        sessionId,
+        signature: signatureOf(`${tool}|${error}`),
+      });
+    } catch { /* ignore */ }
+
+    let advice;
+    if (tool === 'mcp__nodesign__screenshot_canvas') {
+      advice =
+        '截图失败。常见原因：\n'
+        + '  1. 产物文件还没创建 → 先 Write 创建首版\n'
+        + '  2. playwright spawn 慢 / 失败 → 换 Read 产物文件让用户看代码\n'
+        + '  3. fullPage 截图太大 → 换 fullPage:false 截视口';
+    } else if (tool === 'Bash' && /apply-seccomp|unshare\(CLONE_NEWUSER\)/.test(error)) {
+      // 沙盒启动自身的偶发（2026-08-15 实测约 1-2/14）：seccomp 那步的 unshare
+      // 跟运行时起线程抢跑，EINVAL。跟命令本身、跟权限都没关系 —— **原样重跑
+      // 一次就过**。必须点破：08-15 真会话里 agent 把它误判成"隔离闸拦住了"，
+      // 拿一个假结论去回答用户。
+      // 上游 issue：https://github.com/anthropics/claude-code/issues/86928
+      // 现在 ops/sandbox-shim/bwrap 那个垫片已经把它治住了，这条留着兜底：
+      // 垫片靠识别 SDK 内部命令前缀工作，SDK 升级后失配就会静默退回偶发。
+      advice =
+        '这不是你的命令有问题，也不是权限拦截 —— 是沙盒启动时的已知偶发'
+        + '（apply-seccomp / unshare EINVAL，约十几分之一的概率）。\n'
+        + '**把刚才那条命令原样再跑一次就行**，别改写命令，也别据此推断"某个东西被拦了"。';
+    } else if (tool === 'Bash') {
+      advice =
+        'Bash 命令失败。常见：\n'
+        + '  1. sandbox 拦截（命令访问越界文件 / 不允许的网络）→ 换 Read / Glob / Grep / MCP 工具\n'
+        + '  2. cwd 越界 → 路径相对 workspace\n'
+        + '  3. 命令本身错（参数 / 文件不存在）→ 检查 stderr';
+    } else if (tool === 'Write' || tool === 'Edit') {
+      advice =
+        `${tool} 失败。检查：\n`
+        + '  1. 路径相对 workspace 还是绝对路径\n'
+        + '  2. Edit 的 old_string 是否完整匹配（含空格/缩进）\n'
+        + '  3. 文件是否存在（不存在用 Write 创建）';
+    } else if (tool === 'Read') {
+      advice = `Read 失败：${error}\n  1. 确认路径相对 workspace\n  2. 用 Glob 找文件确认存在`;
+    } else if (tool === 'mcp__nodesign__generate_image') {
+      // 按错因分流恢复建议（多数 generate_image 失败可恢复，**默认应重试不是放弃**）
+      const errLower = error.toLowerCase();
+      let cause;
+      if (/http 429|rate.?limit|too many request/.test(errLower)) {
+        cause = '网关限流（429）→ 等 3-5 秒**直接重试**，不必改 prompt。短时间内连续生图触发的，过会儿就 OK';
+      } else if (/http 5\d\d|timeout|gateway|econnreset|socket/.test(errLower)) {
+        cause = '网关 / 上游临时故障（5xx / 网络抖动）→ **直接重试 1-2 次**，多数情况下第二次就成；连续 3 次同错才考虑改思路';
+      } else if (/no parts|no image|safety|blocked|policy/.test(errLower)) {
+        cause = '模型拒生（安全过滤 / 内容策略）→ 调 prompt：换更具体的视觉词（流派 / 镜头 / 灯光），去掉可能触发安全过滤的人物 / 暴力 / 品牌侵权描述，重试';
+      } else if (/http 400|invalid|bad request/.test(errLower)) {
+        cause = 'Prompt 或参数问题（400）→ 检查：去掉否定描述（"no cars" → "empty street"）/ 加风格锚（"Saul Bass minimalist" / "Fujifilm color science"）/ aspectRatio + imageSize 组合是否合法，重试';
+      } else if (/path|reference|enoent|not.?found/.test(errLower)) {
+        cause = 'referenceImages 路径错 → 用 Glob 确认文件存在；只接 workspace 相对路径（assets/...），不接 http url；选 1-2 张最切题的不要全 14 张';
+      } else if (/quota|budget|limit/.test(errLower)) {
+        cause = '配额 / 预算限制 → 看 PM2 日志确认；非紧急情况下告诉用户，等用户决定';
+      } else {
+        cause = '错因未知 → **先重试 1 次**（多数是网络抖动）；同错重现再调 prompt 关键参数（5 元素公式 / 风格锚 / 文字带引号）。不要第一次失败就放弃';
+      }
+      advice =
+        `generate_image 失败：${error}\n\n`
+        + `→ ${cause}\n\n`
+        + `**重要**：generate_image 多数失败是可恢复的（网关抖动 / prompt 微调）。第一次失败就放弃 = 用户没图用，跟"agent 不会生图"体感一样差。**默认应重试 1-2 次**，连续 3 次同错才考虑换思路 / 询问用户。`;
+    } else {
+      advice =
+        `${tool} 失败：${error}\n`
+        + '常见恢复：\n'
+        + '  1. 先重试 1 次（网络抖动 / 临时上游故障多数情况下二次成功）\n'
+        + '  2. 同错重现 → 分析错因调整参数 / 换工具\n'
+        + '  3. 仅当连续失败且阻塞主线 → 在 chat 里跟用户说当前卡点 + 你打算怎么绕过';
+    }
+
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUseFailure',
+        additionalContext: `[工具失败恢复建议]\n${advice}`,
+      },
+    };
+  };
+}

package/server/engine/agent/hooks/file-events.js

@@ -0,0 +1,75 @@
+/**
+ * 文件改动 → 前端刷新 的两条通路（2026-08-14 可维护性行动：从 hooks.js 原样迁出）。
+ *
+ * ⚠️ `toWorkspaceRel` 2026-08-13 提到 `server/lib/workspace-path.js`：
+ * 发给前端当物件寻址依据的路径全都要过它，而那些 emit 不只在这个文件里
+ * （agent-shared 的流式 tool_input 也发 filePath）。
+ *
+ * （这里曾经有「任务 → 会话」的认领机制（2026-07-28 ~ 08-07）：会话第一次往
+ * `tasks/<任务>/` 写东西时落一个 `.nd-task.json` 记住是谁的家，还配了一个
+ * PostToolUse(Bash) 钩子扫命令行里的 `tasks/<名>`。整套随任务层一起退役 ——
+ * 产物属于项目，不属于任何一次对话。）
+ */
+import { Events } from '../events.js';
+import { toWorkspaceRel } from '../../../lib/workspace-path.js';
+import { setActiveArtifact } from '../../../lib/artifact-target.js';
+
+/**
+ * FileChanged handler（P0+ s1 C4）：agent 写文件后 SDK 触发，转发给 EventBus。
+ *
+ * input: FileChangedHookInput (sdk.d.ts:557)
+ *   - file_path: string         绝对路径或相对 cwd
+ *   - event: 'change' | 'add' | 'unlink'
+ *
+ * 不在这里做 .html 过滤 —— 全部转发让前端按需消费（C18 ContextUsageBar /
+ * C20 file changes 列表都可能用）。前端 Project.jsx 只对 canvas.html bump reloadToken。
+ *
+ * 返回 {}：不干预 SDK，不影响 agent loop。
+ */
+export function makeFileChangedHandler({ ctx, workspaceRoot }) {
+  // eslint-disable-next-line no-unused-vars
+  return async (input, _toolUseId, _options) => {
+    try {
+      // 同下 emitter：发工作区相对路径，前端拿它直接当物件 id 的路径部分
+      ctx.emit(Events.fileChanged(toWorkspaceRel(input.file_path, workspaceRoot), input.event));
+    } catch (err) {
+      console.warn(`[hooks/FileChanged] handler threw:`, err.message);
+    }
+    return {};
+  };
+}
+
+/**
+ * PostToolUse(写文件系工具) → 直发 run.file_changed（2026-07-28）。
+ *
+ * SDK 的 FileChanged hook 是 watcher 型（要先声明 watchPaths 才启动），实测从未
+ * 触发。这里走确定性路径：Write/Edit/MultiEdit/NotebookEdit 成功完成即从入参拿
+ * 路径发事件 —— agent 每写完一笔，前端立刻 reload iframe / 刷产物墙 / 打角标，
+ * 不再等 run.done。PostToolUse 只在工具成功后触发（失败走 PostToolUseFailure），
+ * 不会把写坏的半成品刷给用户。
+ */
+export function makePostToolUseFileChangedEmitter({ ctx, workspaceRoot, sharedRoot, sessionId }) {
+  // eslint-disable-next-line no-unused-vars
+  return async (input, _toolUseId, _options) => {
+    try {
+      const t = input?.tool_input;
+      const filePath = typeof t?.file_path === 'string' ? t.file_path
+        : typeof t?.notebook_path === 'string' ? t.notebook_path : null;
+      if (filePath) {
+        // 刚写的这份 html 就是"当前产物"——list_pages / screenshot / read_page
+        // 不给 path 时默认打它，子代理不必知道任务目录长什么样（artifact-target.js）。
+        // 形态（deck / site）不在这里定：resolveArtifactTarget 每次解析都按任务现状
+        // 重算，免得"先写 index.html 记成 site、后来目录变了"这种陈旧状态。
+        const rel = toWorkspaceRel(filePath, workspaceRoot);
+        setActiveArtifact(sessionId, rel);
+        // 发**工作区相对路径**：画布物件的 id 就是这个字符串。以前发绝对路径，
+        // 前端靠 `tasks/<任务>/` 这个特征段把相对部分抠出来 —— 那一层拆掉之后
+        // 绝对路径里再没有可锚定的标志，寻址静默失败（舞台卡掉 dock）。
+        ctx.emit(Events.fileChanged(rel, 'change'));
+      }
+    } catch (err) {
+      console.warn('[hooks/PostToolUse:file-changed] emit failed:', err.message);
+    }
+    return {};
+  };
+}

package/server/engine/agent/hooks/lifecycle.js

@@ -0,0 +1,233 @@
+/**
+ * 会话生命周期族：SessionStart / Stop / PostCompact / SubagentStart / SubagentStop。
+ * （2026-08-14 可维护性行动：从 hooks.js 原样迁出，语义零改动）
+ */
+import { Events } from '../events.js';
+import { getQuery } from '../../runs/active-runs.js';
+import { mutateSpecJson } from '../../../projects/workspace.js';
+import { listWorkspaceArtifacts } from '../../../lib/artifact-target.js';
+import { resetTurnMemory } from './turn-state-memory.js';
+
+/**
+ * Context usage 警告分档（按真实容量算，kimi=256k）：
+ *   soft   70% — 提醒：还能再写一阵；下个段落收尾时落档
+ *   firm   85% — 加紧：开始整理结论 / 准备 spec.json
+ *   urgent 92% — 已过 SDK auto-compact 触发线（90%×真实=230k for 256k 容量），立即收尾
+ */
+const CONTEXT_USAGE_WARN_LEVELS = [
+  { percent: 70, tone: 'soft' },
+  { percent: 85, tone: 'firm' },
+  { percent: 92, tone: 'urgent' },
+];
+
+/**
+ * SessionStart handler（升级原 noop 占位）。
+ *
+ * input: SessionStartHookInput (sdk.d.ts:3577)
+ *   - source: 'startup' | 'resume' | 'clear' | 'compact'
+ *   - agent_type?: string                  父 agent 类型（--agent 时有）
+ *   - model?: string
+ *
+ * Phase 2 范围：仅 emit 事件让上层可见。不注 additionalContext / initialUserMessage —
+ * spec.json 的恢复走 UserPromptSubmit 路径（每次用户输入前重新注入），而不是
+ * SessionStart 一次性注入（一次性注入只在 session 开头有效，跨多个 turn 后过期）。
+ */
+export function makeSessionStartHandler({ ctx }) {
+  return async (input, _toolUseId, _options) => {
+    try {
+      ctx.emit(Events.sessionStart(input.source, input.agent_type, ctx.appModel || input.model));
+    } catch (err) {
+      console.warn(`[hooks/SessionStart] handler threw:`, err.message);
+    }
+    return {};
+  };
+}
+
+/**
+ * Stop handler（P0+ s1 C6）—— agent 准备结束 query 时触发。
+ *
+ * 两件事：
+ * 1. emit run.stop_reflection（hasCanvas 信号给前端）
+ * 2. SDK getContextUsage 拉上下文占用 → emit run.context_usage + 三档 70/85/92% 注 systemMessage
+ *
+ * input: StopHookInput (sdk.d.ts:5247)
+ *   - stop_hook_active: boolean
+ *   - last_assistant_message?: string
+ */
+export function makeStopReflectionHandler({ ctx, workspaceRoot }) {
+  return async (_input, _toolUseId, _options) => {
+    let warnContextUsage = null;
+    try {
+      // 任务模型下产物住 tasks/<任务>/，这里以前只探 cwd 根的 canvas.html —— 自
+      // 任务模型上线起就恒为 false，从来没真过。走统一寻址（deck 和站点都算数）。
+      const hasCanvas = workspaceRoot
+        ? (await listWorkspaceArtifacts(workspaceRoot)).length > 0
+        : false;
+
+      ctx.emit({
+        type: 'run.stop_reflection',
+        hasCanvas,
+      });
+
+      // SDK 0.2.86+ getContextUsage —— 每个 turn 收尾时拉一次上下文占用，
+      // emit 给前端做可视化条 + 三档（70/85/92%）注 systemMessage 提示 agent 主动收尾
+      // （Kimi gateway 上限 256k，曾经爆过 418k；spoofing 后 SDK auto-compact
+      //  在 256k×0.9=230k 触发兜底）
+      if (ctx.runId) {
+        try {
+          const query = getQuery(ctx.runId);
+          if (query?.getContextUsage) {
+            const usage = await query.getContextUsage();
+            if (usage && typeof usage.totalTokens === 'number') {
+              // 2026-07-30：这里原来手搓了第二种事件体 { used, max, percent, categories }。
+              // 事件名跟 session-loop 那条一样，字段名一个都对不上 —— 前端读的是
+              // totalTokens / maxTokens / percentage，所以这条在前端一直是纯噪音，
+              // 全靠 store 的 merge「不覆盖已有值」才没显形。而每个 turn 的**最后**
+              // 一条 context_usage 恰好总是它，任何"取最新一条"的下游拿到的都是
+              // 一片 undefined。现在统一走 Events.contextUsage，全局只此一种形状。
+              const evt = Events.contextUsage(usage, ctx.appModel);
+              ctx.emit({ ...evt, runId: ctx.runId });
+
+              const used = evt.totalTokens;
+              const realMax = evt.maxTokens;
+              const percent = evt.percentage;
+
+              // realMax 有可能是 null（appModel 认不出、SDK 也没给容量）——
+              // 那时 percentage 退回 SDK 自己的值，但下面的文案要拿 realMax 做减法，
+              // 算不出容量就不提醒（宁可不说，也别说个编的数字）
+              const hit = (Number.isFinite(realMax) && realMax > 0)
+                ? [...CONTEXT_USAGE_WARN_LEVELS].reverse().find((l) => percent >= l.percent)
+                : null;
+              if (hit) {
+                const usedStr = used.toLocaleString();
+                const maxStr = realMax.toLocaleString();
+                const remain = Math.max(0, realMax - used).toLocaleString();
+                let body;
+                if (hit.tone === 'soft') {
+                  body = `上下文已用 ${percent}%（${usedStr}/${maxStr} tokens），还能再写一阵；下一个段落收尾时把当前进度落一张便利贴（record_decision 或 Write notes/<slug>.md），避免后续 compact 丢上下文。`;
+                } else if (hit.tone === 'firm') {
+                  body = `上下文已用 ${percent}%（${usedStr}/${maxStr}，剩 ~${remain}）。从下一轮开始整理结论 / 落档，避免被自动 compact 硬切。`;
+                } else {
+                  body = `上下文已用 ${percent}%（${usedStr}/${maxStr}）。已逼近 SDK auto-compact 触发线（90%）；立即收尾或把结论落进便利贴（record_decision / notes/），否则下一轮可能被压缩中断当前思路。`;
+                }
+                warnContextUsage = `<system-reminder>\n[context-usage] ${body}\n</system-reminder>`;
+              }
+            }
+          }
+        } catch (err) {
+          console.warn(`[hooks/Stop] getContextUsage fail:`, err.message);
+        }
+      }
+    } catch (err) {
+      console.warn(`[hooks/Stop] handler threw:`, err.message);
+    }
+    if (warnContextUsage) {
+      return { systemMessage: warnContextUsage };
+    }
+    return {};
+  };
+}
+
+/**
+ * PostCompact handler（P0+ s1 C7）—— SDK 自动 compact 后把 summary 持久化到 spec.json。
+ *
+ * input: PostCompactHookInput (sdk.d.ts:1879)
+ *   - trigger: 'manual' | 'auto'
+ *   - compact_summary: string
+ *
+ * 失败 fail-soft：spec.json 写不进去 console.warn 但不抛错（不阻塞 query）。
+ */
+export function makePostCompactHandler({ ctx, workspaceRoot, sessionId }) {
+  return async (input, _toolUseId, _options) => {
+    try {
+      // 压缩后上一轮的状态块已经被摘要吞了，"同上轮"没有所指 —— 让下一轮重新全量
+      resetTurnMemory(sessionId);
+      if (!workspaceRoot) return {};
+      const summary = input?.compact_summary;
+      if (!summary || typeof summary !== 'string') return {};
+
+      // 串行 read-modify-write 防 spec.json 三路并发覆盖（详见 workspace.js mutateSpecJson）
+      // historyCount 在回调内 capture 出去 —— 之前 emit 里直接引用 spec 是 ReferenceError，
+      // 整段被 try 静默吞，导致 run.compact_persisted 事件永远不发。
+      let historyCount = 0;
+      await mutateSpecJson(workspaceRoot, (spec) => {
+        if (!Array.isArray(spec.history)) spec.history = [];
+        spec.history.push({
+          ts: new Date().toISOString(),
+          source: 'compact',
+          trigger: input.trigger || 'auto',
+          summary,
+        });
+        historyCount = spec.history.length;
+      });
+
+      try {
+        ctx.emit({
+          type: 'run.compact_persisted',
+          trigger: input.trigger || 'auto',
+          summaryLength: summary.length,
+          historyCount,
+        });
+      } catch { /* emit fail-safe */ }
+    } catch (err) {
+      console.warn(`[hooks/PostCompact] handler threw:`, err.message);
+    }
+    return {};
+  };
+}
+
+/**
+ * SubagentStart handler — 子代理启动时主动 emit 事件给 EventBus。
+ *
+ * input: SubagentStartHookInput (sdk.d.ts:5258)
+ *   - agent_id: string
+ *   - agent_type: string
+ *
+ * 与 SDK system 'task_started' message 路径并行：task_* message 走的是 SDK
+ * agentProgressSummaries 通道（30s 摘要），而 hook 是子代理 spawn 时立即触发，
+ * 时序更前 + 更可靠。session-loop.js 已对 task_started 翻译成 run.task.started，
+ * 这条 hook emit 的 run.subagent.start 是更主动的入口。
+ *
+ * Phase 2 仅 emit；不注入 additionalContext（子代理刚启动还没产出，注啥都早）。
+ */
+export function makeSubagentStartHandler({ ctx }) {
+  return async (input, _toolUseId, _options) => {
+    try {
+      ctx.emit(Events.subagentStart(input.agent_id, input.agent_type));
+    } catch (err) {
+      console.warn(`[hooks/SubagentStart] handler threw:`, err.message);
+    }
+    return {};
+  };
+}
+
+/**
+ * SubagentStop handler — 子代理结束时主动 emit。
+ *
+ * input: SubagentStopHookInput (sdk.d.ts:5269)
+ *   - stop_hook_active: boolean
+ *   - agent_id: string
+ *   - agent_transcript_path: string       子代理转录文件路径
+ *   - agent_type: string
+ *   - last_assistant_message?: string     子代理最后一条 assistant 文本
+ *
+ * 注意：SubagentStop 没有 specific output 类型（sdk.d.ts:5291 的 union 里没列），
+ * 只能返回通用 SyncHookJSONOutput（continue/decision/systemMessage）。
+ * 这里只 emit 不返 specific 输出，符合规范。
+ */
+export function makeSubagentStopHandler({ ctx }) {
+  return async (input, toolUseId, _options) => {
+    try {
+      ctx.emit(Events.subagentStop(
+        input.agent_id,
+        input.agent_type,
+        input.last_assistant_message,
+        input.agent_transcript_path,
+        toolUseId,    // main agent 调 Task 时的 tool_use_id；前端按它 match 卡
+      ));
+    } catch (err) {
+      console.warn(`[hooks/SubagentStop] handler threw:`, err.message);
+    }
+    return {};
+  };
+}

package/server/engine/agent/hooks/post-canvas-focus.js

@@ -0,0 +1,80 @@
+/**
+ * PostToolUse(Edit|Write canvas.html) handler — Canvas 焕新升级 S1d。
+ * （2026-08-14 可维护性行动：从 hooks.js 原样迁出，语义零改动）
+ *
+ * focus_page：检测改动落在哪些 <section data-page="N"> + 改动里有没有
+ *   data-anchor="..." 引用 → emit run.canvas_focus_page(pages, anchor?)
+ *   → 前端 SlideNavigator 自动 scrollIntoView + 1.5s pulse 高亮
+ *
+ * 不返 hookSpecificOutput / 不阻塞 agent / 不注 additionalContext。
+ *
+ * 检测策略（Edit / Write 都要看）：
+ *   - Edit：从 tool_input.new_string 找 data-page / data-anchor
+ *     （保守 — 只看新增的，不重复扫旧 content）
+ *   - Write：从 tool_input.content 找（整文件都是新内容）
+ *   - 非 canvas.html 文件：跳过
+ *   - file_path 是相对 cwd 的，没法判断到底是不是 canvas.html，按 basename 匹配
+ *
+ * 失败 fail-soft：emit fail / 解析炸都不抛，console.warn 一行。
+ */
+import { Events } from '../events.js';
+
+export function makePostToolUseCanvasFocusPageHandler({ ctx }) {
+  return async (input, _toolUseId, _options) => {
+    try {
+      const filePath = input?.tool_input?.file_path;
+      if (!filePath || typeof filePath !== 'string') return {};
+      // deck 现在叫 <名>.html（canvas.html 只是常用名）：名字兜底 + 读文件看 deck wrap 标记
+      if (!/\.html?$/i.test(filePath)) return {};
+      if (!/(?:^|[/\\])canvas\.html$/i.test(filePath)) {
+        let isDeck = false;
+        try {
+          const { promises: fsp } = await import('node:fs');
+          const head = (await fsp.readFile(filePath, 'utf8')).slice(0, 200_000);
+          isDeck = head.includes('__nd-deck-wrap');
+        } catch { /* 相对路径读不到 / 文件没了：不是 deck 就当 */ }
+        if (!isDeck) return {};
+      }
+
+      // 取改动文本：Edit 看 new_string，Write 看 content
+      const toolName = input?.tool_name;
+      let changeText = '';
+      if (toolName === 'Edit') {
+        changeText = String(input?.tool_input?.new_string || '');
+      } else if (toolName === 'Write') {
+        changeText = String(input?.tool_input?.content || '');
+      } else {
+        return {};
+      }
+      if (!changeText) return {};
+
+      // focus_page —— 找 <section ... data-page="N"> + 可选 data-anchor
+      try {
+        const pageMatches = [...changeText.matchAll(
+          /<section\b[^>]*\bdata-page\s*=\s*['"]?(\d+)['"]?/gi
+        )];
+        const pages = [...new Set(pageMatches.map(m => parseInt(m[1], 10)))]
+          .filter(n => Number.isFinite(n));
+
+        // 找 data-anchor — 取第一个，前端用它精确定位元素
+        const anchorMatch = changeText.match(/\bdata-anchor\s*=\s*['"]([^'"]+)['"]/i);
+        const anchor = anchorMatch ? anchorMatch[1] : null;
+
+        // Edit 改的是 page 内某段时不会包含 <section data-page>，要从 file path
+        // 上推 ——但 hook 时 canvas.html 已写完，可以读出来定位。为避免 hook IO
+        // 阻塞 agent，这次先只 emit 显式带 data-page 的改动；不带 page 但带 anchor
+        // 也 emit（前端能找到 anchor 元素自己反推 page）。
+        if (pages.length > 0 || anchor) {
+          ctx.emit(Events.canvasFocusPage(pages, anchor));
+        }
+      } catch (err) {
+        console.warn(`[hooks/canvas_focus_page] handler partial failure:`, err.message);
+      }
+
+      return {};
+    } catch (err) {
+      console.warn(`[hooks/canvas_focus_page] outer handler threw:`, err.message);
+      return {};
+    }
+  };
+}