@xiaobuyu/nodesign 0.0.1 → 0.0.2

package/server/engine/agent/hooks/post-guidance.js

@@ -1,206 +1,206 @@
-/**
- * PostToolUse 行为引导族 —— 工具跑完后注 additionalContext 引导 agent 下一步
- * （截图后自检 / 交付后告知 / 重生看门狗 / 风格锚落盘提醒）。
- * （2026-08-14 可维护性行动：从 hooks.js 原样迁出，语义零改动）
- *
- * makePostToolUseRecordDecisionHandler — 已移除（git 历史可查）。
- * 之前注 "继续做用户的当前任务" 跟 SDK preset 'claude_code' 教的内容重复，
- * 让 agent 行为像被牵着走。删除后 agent 记完决策自己判断下一步，更接近
- * SDK 默认行为。如未来观察到 agent 反复 record_decision 信号稀释，再考虑
- * 加回（那时改成更精准的 anti-loop 检测，不是无脑注引导）。
- */
-import path from 'node:path';
-
-/**
- * PostToolUse(screenshot_canvas) handler — agent 截图后引导它做视觉自检。
- *
- * input: PostToolUseHookInput (sdk.d.ts:1926)
- *   - tool_name / tool_input / tool_response / tool_use_id / duration_ms?
- *
- * output: PostToolUseHookSpecificOutput (sdk.d.ts:1938)
- *   - additionalContext?: string         注入下一轮 prompt
- *   - updatedToolOutput?: unknown        替换 tool 输出（不用）
- *
- * 注意：tool_response 里包含 image content block（base64）。agent 收到这条
- * additionalContext 时已经能"看到"图（multimodal）—— 我们只是用文字提示
- * 它接下来该做什么，不替换 image。
- *
- * 截图后的引导（2026-07-28；硬上限已撤销）：
- * 实测一个真实会话 9-33 张截图，每张 0.6 倍光栅后 ≈1k vision tokens，且
- * **永久留在上下文里**（SDK 不能回改历史工具输出）。
- *
- * 曾经加过"整会话超 12 张就把图换成文字"的硬闸，撤掉了：那等于在 agent 检查
- * 自己作品的时候把它的眼睛蒙上，而且蒙得悄无声息 —— 它只会以为"看起来 OK"。
- * 省下来的几十 k 换不来这个代价。现在只报数、给建议，看不看由它自己判断；
- * 真正的省是 0.6 倍光栅（每张 1.85k→1.0k）和压缩阈值，不是拦着不让看。
- */
-const SCREENSHOT_BUSY_HINT_AT = 6;   // 累到这个数开始提醒"大面积检查交给子代理"
-
-export function makePostToolUseScreenshotHandler({ ctx }) {
-  let takenInSession = 0;
-  let takenInTurn = 0;
-  let lastTurn = -1;
-  // 不 emit run.screenshot_taken —— mcp/tools/screenshot.js:114 已经 emit
-  // 完整字段（sizeBytes / viewport / fullPage）。hook 只负责注 additionalContext
-  // 引导 agent 行为，业务事件由 MCP 工具内部负责。
-  return async (input, _toolUseId, _options) => {
-    const args = input?.tool_input || {};
-    const wasFullPage = args.fullPage === true;
-    const wasPerPage = typeof args.pageIndex === 'number';
-    const turn = ctx?.counters?.turns ?? 0;
-    if (turn !== lastTurn) { lastTurn = turn; takenInTurn = 0; }
-    takenInTurn += 1;
-    takenInSession += 1;
-
-    // fullPage 截图体积是 viewport 的 N×（N=页数），且会留在 context 多 turn
-    // 直到 autoCompact。push agent 下次整 deck 自检走 vision-checker subagent，
-    // subagent context 是隔离的，主线只收文字 critique，几 K vs 几百 K 的差距。
-    // 08-21 起这里只注**状态**（张数计数），不再每张截图注一段"点 3 个问题 / 派 vision-checker"
-    // 的说教 —— 那些住 prelude（做完之前先自己看 / 何时请外援），每张都说是 N 倍重复，而且
-    // "整 deck 自检请派 vision-checker"跟 prelude 定的触发条件（自检两轮用户仍不满意）矛盾。
-    void wasFullPage; void wasPerPage;
-    if (takenInSession < SCREENSHOT_BUSY_HINT_AT) return {};
-    return {
-      hookSpecificOutput: {
-        hookEventName: 'PostToolUse',
-        additionalContext:
-          `**上下文提示**：本轮 ${takenInTurn} 张、本会话累计 ${takenInSession} 张截图（每张约 1k tokens，进了上下文不会释放）。没有额度上限，该看就看。`,
-      },
-    };
-  };
-}
-
-/**
- * PostToolUse(export_handoff) handler — agent 打交付包后引导它告知用户路径。
- */
-export function makePostToolUseExportHandler({ ctx: _ctx }) {
-  // 不 emit run.export_built —— mcp/tools/export-handoff.js:83 已经 emit
-  // 完整字段（format / path / sizeBytes / notes）。hook 从 tool_response 字符串
-  // substring 拼出来的 path 反而不准。hook 只负责注 additionalContext。
-  // 08-21：只在本 session 第一次打包时提醒一次；"收尾消息要自足"prelude 已讲，每次都注是重复
-  let said = false;
-  return async (_input, _toolUseId, _options) => {
-    if (said) return {};
-    said = true;
-    return {
-      hookSpecificOutput: {
-        hookEventName: 'PostToolUse',
-        additionalContext: '已生成交付包。把打包文件路径告诉用户（他从 UI 下载）；同一个交付只打包一次。',
-      },
-    };
-  };
-}
-
-// ── Phase Image-4：generate_image 重生看门狗 ──
-//
-// agent 同 outputName 调 generate_image 第 3 次起，注 systemMessage 建议：
-//   - 直接 chat 邀请用户在最近 2-3 张候选里选最好的（generate_image 已返 image
-//     content block，前端 chat 自动渲染，用户能直接看到）
-//   - 或 accept 当前最好的一版继续后续工作
-// 防"agent 闷头改 5-10 次同 prompt 浪费 token + 用户也得不到更好版本"。
-//
-// 计数策略：
-//   - in-memory Map（key: outputName 去 timestamp 的 base，value: count）
-//   - 进程重启清；session 内累积；不区分 session（agent 进程同步 hook）
-//   - 阈值固定 3，可后续 env 化
-//
-// outputName base 提取：
-//   - "deck-cover-v1" → "deck-cover"（去掉 -v\d / -\d / -draft 等 suffix）
-//   - 同 base 不同 suffix 仍计入同一组（避免 agent 改名绕过 watchdog）
-export function makePostToolUseGenerateImageRegenWatchdog() {
-  let nudgedOnce = false;   // 08-21：邀请反馈的判断准则每 session 说一次就够（以前每个 base 组第一张都说）
-  const REGEN_THRESHOLD = 3;
-  const counts = new Map();
-
-  function extractBase(outputName) {
-    if (!outputName || typeof outputName !== 'string') return null;
-    return outputName
-      .replace(/-(?:v\d+|draft\d*|final|new|old|alt|\d+)$/i, '')
-      .replace(/[-_]+/g, '-')
-      .toLowerCase();
-  }
-
-  return async (input, _toolUseId, _options) => {
-    try {
-      const outputName = input?.tool_input?.outputName;
-      const base = extractBase(outputName);
-      if (!base) return {};
-
-      const next = (counts.get(base) || 0) + 1;
-      counts.set(base, next);
-
-      // 第 1 次：邀请反馈 nudge（按 SKILL.md 高代价 / 低代价节点判断）
-      if (next === 1 && !nudgedOnce) {
-        nudgedOnce = true;
-        return {
-          hookSpecificOutput: {
-            hookEventName: 'PostToolUse',
-            additionalContext:
-              `<system-reminder>\n[image-feedback-nudge] 这是本组（base="${base}"）第 1 张图。\n\n`
-            + `如果是 cover / portrait / 跨页 anchor 这类高代价节点（会被当 referenceImages 种子用于全 deck），可以在 chat 里自然邀请用户确认一下方向（"这个 cover 当全 deck 视觉锚 OK 吗？"），收到反馈再做后续；section-divider / decoration / icon 这类单张可直接继续，工具 caption 已自动在 chat 显示。\n\n`
-            + `判断诀窍：错了会不会导致全 deck 重生？会 → 邀请反馈；不会 → 继续。\n`
-            + `</system-reminder>`,
-          },
-        };
-      }
-
-      if (next < REGEN_THRESHOLD) return {};
-
-      // ≥ 3 次同 base outputName → 注 systemMessage
-      return {
-        hookSpecificOutput: {
-          hookEventName: 'PostToolUse',
-          additionalContext:
-            `<system-reminder>\n[regen-watchdog] 你已经对 outputName base "${base}" 调 generate_image ${next} 次。\n\n`
-          + `如果是 conversational editing 微调（"再暖一点 / 换日落色"），可以继续；\n`
-          + `如果在反复尝试不同方向（每次 prompt 大改），**强烈建议**：\n`
-          + `  1. 直接在 chat 里邀请用户从最近 2-3 张候选选最好的（image content block 已自动在 chat 渲染）\n`
-          + `  2. 或 accept 当前最满意的那张，专心后续工作\n`
-          + `理由：reroll 同 prompt 越多次 token 浪费越大，且用户也未必能在第 N 张里看出明显差别。\n`
-          + `</system-reminder>`,
-        },
-      };
-    } catch (err) {
-      console.warn(`[hooks/regen-watchdog] threw:`, err.message);
-      return {};
-    }
-  };
-}
-
-/**
- * PostToolUse(record_decision) —— 锚定风格那一笔之后提醒落两处长期资产
- * （2026-07-28，配合"记忆归 SDK / 品牌归我们 / 指引归用户"的分工）
- *
- * 只在这一笔上注、每 session 一次：
- *   - 品牌档案 `agent-memory/brand/memory.md` —— 前端 BrandCard 会把色板 /
- *     字体渲染出来，是结构化资产，agent 不写就永远空着
- *   - 项目指引 `.claude/CLAUDE.md` —— SDK 每次 session 自动读进 system prompt，
- *     但只有用户能决定要不要固化，所以是"问一句"不是"直接写"
- *
- * 通用偏好不在这儿管：那是 SDK 自动记忆的活（autoMemoryDirectory 已指到
- * .claude/agent-memory/auto，前端记忆卡直接显示）。
- */
-export function makePostToolUseStyleAnchorNudge({ sharedRoot }) {
-  let nudged = false;
-  const ANCHOR_RE = /(style-anchor|风格锚|锚定|视觉基调|palette|配色方案)/i;
-  return async (input, _toolUseId, _options) => {
-    if (nudged) return {};
-    const t = input?.tool_input || {};
-    const blob = `${t.topic || ''} ${t.title || ''} ${t.decision || ''} ${t.rationale || ''}`;
-    if (!ANCHOR_RE.test(blob)) return {};
-    nudged = true;
-    const guidePath = sharedRoot ? path.join(sharedRoot, '.claude', 'CLAUDE.md') : '.claude/CLAUDE.md';
-    return {
-      hookSpecificOutput: {
-        hookEventName: 'PostToolUse',
-        additionalContext:
-          '这一笔看起来是在锚定这个项目的视觉方向。顺手做两件事（都只做一次）：\n'
-        + '1. 把这版风格写进 `.claude/agent-memory/brand/memory.md`（色号 / 字体链 / 版式语言 / 动效预算；⚠️ 带 .claude/ 前缀，写错位置 BrandCard 读不到），'
-        + '前端品牌档案卡会把色板和字体渲染出来给用户看，不写就一直空着。\n'
-        + `2. 如果这次定下来的还包含**项目级约束**（不只这一个 deck 适用，比如"这个项目一律不用 emoji"），`
-        + `在收尾时问用户一句要不要写进项目指引（${guidePath}，SDK 每次 session 自动读它）。用户点头你再写。\n`
-        + '用户的通用偏好不用你手动记，系统的自动记忆会管。',
-      },
-    };
-  };
-}
+/**
+ * PostToolUse 行为引导族 —— 工具跑完后注 additionalContext 引导 agent 下一步
+ * （截图后自检 / 交付后告知 / 重生看门狗 / 风格锚落盘提醒）。
+ * （2026-08-14 可维护性行动：从 hooks.js 原样迁出，语义零改动）
+ *
+ * makePostToolUseRecordDecisionHandler — 已移除（git 历史可查）。
+ * 之前注 "继续做用户的当前任务" 跟 SDK preset 'claude_code' 教的内容重复，
+ * 让 agent 行为像被牵着走。删除后 agent 记完决策自己判断下一步，更接近
+ * SDK 默认行为。如未来观察到 agent 反复 record_decision 信号稀释，再考虑
+ * 加回（那时改成更精准的 anti-loop 检测，不是无脑注引导）。
+ */
+import path from 'node:path';
+
+/**
+ * PostToolUse(screenshot_canvas) handler — agent 截图后引导它做视觉自检。
+ *
+ * input: PostToolUseHookInput (sdk.d.ts:1926)
+ *   - tool_name / tool_input / tool_response / tool_use_id / duration_ms?
+ *
+ * output: PostToolUseHookSpecificOutput (sdk.d.ts:1938)
+ *   - additionalContext?: string         注入下一轮 prompt
+ *   - updatedToolOutput?: unknown        替换 tool 输出（不用）
+ *
+ * 注意：tool_response 里包含 image content block（base64）。agent 收到这条
+ * additionalContext 时已经能"看到"图（multimodal）—— 我们只是用文字提示
+ * 它接下来该做什么，不替换 image。
+ *
+ * 截图后的引导（2026-07-28；硬上限已撤销）：
+ * 实测一个真实会话 9-33 张截图，每张 0.6 倍光栅后 ≈1k vision tokens，且
+ * **永久留在上下文里**（SDK 不能回改历史工具输出）。
+ *
+ * 曾经加过"整会话超 12 张就把图换成文字"的硬闸，撤掉了：那等于在 agent 检查
+ * 自己作品的时候把它的眼睛蒙上，而且蒙得悄无声息 —— 它只会以为"看起来 OK"。
+ * 省下来的几十 k 换不来这个代价。现在只报数、给建议，看不看由它自己判断；
+ * 真正的省是 0.6 倍光栅（每张 1.85k→1.0k）和压缩阈值，不是拦着不让看。
+ */
+const SCREENSHOT_BUSY_HINT_AT = 6;   // 累到这个数开始提醒"大面积检查交给子代理"
+
+export function makePostToolUseScreenshotHandler({ ctx }) {
+  let takenInSession = 0;
+  let takenInTurn = 0;
+  let lastTurn = -1;
+  // 不 emit run.screenshot_taken —— mcp/tools/screenshot.js:114 已经 emit
+  // 完整字段（sizeBytes / viewport / fullPage）。hook 只负责注 additionalContext
+  // 引导 agent 行为，业务事件由 MCP 工具内部负责。
+  return async (input, _toolUseId, _options) => {
+    const args = input?.tool_input || {};
+    const wasFullPage = args.fullPage === true;
+    const wasPerPage = typeof args.pageIndex === 'number';
+    const turn = ctx?.counters?.turns ?? 0;
+    if (turn !== lastTurn) { lastTurn = turn; takenInTurn = 0; }
+    takenInTurn += 1;
+    takenInSession += 1;
+
+    // fullPage 截图体积是 viewport 的 N×（N=页数），且会留在 context 多 turn
+    // 直到 autoCompact。push agent 下次整 deck 自检走 vision-checker subagent，
+    // subagent context 是隔离的，主线只收文字 critique，几 K vs 几百 K 的差距。
+    // 08-21 起这里只注**状态**（张数计数），不再每张截图注一段"点 3 个问题 / 派 vision-checker"
+    // 的说教 —— 那些住 prelude（做完之前先自己看 / 何时请外援），每张都说是 N 倍重复，而且
+    // "整 deck 自检请派 vision-checker"跟 prelude 定的触发条件（自检两轮用户仍不满意）矛盾。
+    void wasFullPage; void wasPerPage;
+    if (takenInSession < SCREENSHOT_BUSY_HINT_AT) return {};
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext:
+          `**上下文提示**：本轮 ${takenInTurn} 张、本会话累计 ${takenInSession} 张截图（每张约 1k tokens，进了上下文不会释放）。没有额度上限，该看就看。`,
+      },
+    };
+  };
+}
+
+/**
+ * PostToolUse(export_handoff) handler — agent 打交付包后引导它告知用户路径。
+ */
+export function makePostToolUseExportHandler({ ctx: _ctx }) {
+  // 不 emit run.export_built —— mcp/tools/export-handoff.js:83 已经 emit
+  // 完整字段（format / path / sizeBytes / notes）。hook 从 tool_response 字符串
+  // substring 拼出来的 path 反而不准。hook 只负责注 additionalContext。
+  // 08-21：只在本 session 第一次打包时提醒一次；"收尾消息要自足"prelude 已讲，每次都注是重复
+  let said = false;
+  return async (_input, _toolUseId, _options) => {
+    if (said) return {};
+    said = true;
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: '已生成交付包。把打包文件路径告诉用户（他从 UI 下载）；同一个交付只打包一次。',
+      },
+    };
+  };
+}
+
+// ── Phase Image-4：generate_image 重生看门狗 ──
+//
+// agent 同 outputName 调 generate_image 第 3 次起，注 systemMessage 建议：
+//   - 直接 chat 邀请用户在最近 2-3 张候选里选最好的（generate_image 已返 image
+//     content block，前端 chat 自动渲染，用户能直接看到）
+//   - 或 accept 当前最好的一版继续后续工作
+// 防"agent 闷头改 5-10 次同 prompt 浪费 token + 用户也得不到更好版本"。
+//
+// 计数策略：
+//   - in-memory Map（key: outputName 去 timestamp 的 base，value: count）
+//   - 进程重启清；session 内累积；不区分 session（agent 进程同步 hook）
+//   - 阈值固定 3，可后续 env 化
+//
+// outputName base 提取：
+//   - "deck-cover-v1" → "deck-cover"（去掉 -v\d / -\d / -draft 等 suffix）
+//   - 同 base 不同 suffix 仍计入同一组（避免 agent 改名绕过 watchdog）
+export function makePostToolUseGenerateImageRegenWatchdog() {
+  let nudgedOnce = false;   // 08-21：邀请反馈的判断准则每 session 说一次就够（以前每个 base 组第一张都说）
+  const REGEN_THRESHOLD = 3;
+  const counts = new Map();
+
+  function extractBase(outputName) {
+    if (!outputName || typeof outputName !== 'string') return null;
+    return outputName
+      .replace(/-(?:v\d+|draft\d*|final|new|old|alt|\d+)$/i, '')
+      .replace(/[-_]+/g, '-')
+      .toLowerCase();
+  }
+
+  return async (input, _toolUseId, _options) => {
+    try {
+      const outputName = input?.tool_input?.outputName;
+      const base = extractBase(outputName);
+      if (!base) return {};
+
+      const next = (counts.get(base) || 0) + 1;
+      counts.set(base, next);
+
+      // 第 1 次：邀请反馈 nudge（按 SKILL.md 高代价 / 低代价节点判断）
+      if (next === 1 && !nudgedOnce) {
+        nudgedOnce = true;
+        return {
+          hookSpecificOutput: {
+            hookEventName: 'PostToolUse',
+            additionalContext:
+              `<system-reminder>\n[image-feedback-nudge] 这是本组（base="${base}"）第 1 张图。\n\n`
+            + `如果是 cover / portrait / 跨页 anchor 这类高代价节点（会被当 referenceImages 种子用于全 deck），可以在 chat 里自然邀请用户确认一下方向（"这个 cover 当全 deck 视觉锚 OK 吗？"），收到反馈再做后续；section-divider / decoration / icon 这类单张可直接继续，工具 caption 已自动在 chat 显示。\n\n`
+            + `判断诀窍：错了会不会导致全 deck 重生？会 → 邀请反馈；不会 → 继续。\n`
+            + `</system-reminder>`,
+          },
+        };
+      }
+
+      if (next < REGEN_THRESHOLD) return {};
+
+      // ≥ 3 次同 base outputName → 注 systemMessage
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PostToolUse',
+          additionalContext:
+            `<system-reminder>\n[regen-watchdog] 你已经对 outputName base "${base}" 调 generate_image ${next} 次。\n\n`
+          + `如果是 conversational editing 微调（"再暖一点 / 换日落色"），可以继续；\n`
+          + `如果在反复尝试不同方向（每次 prompt 大改），**强烈建议**：\n`
+          + `  1. 直接在 chat 里邀请用户从最近 2-3 张候选选最好的（image content block 已自动在 chat 渲染）\n`
+          + `  2. 或 accept 当前最满意的那张，专心后续工作\n`
+          + `理由：reroll 同 prompt 越多次 token 浪费越大，且用户也未必能在第 N 张里看出明显差别。\n`
+          + `</system-reminder>`,
+        },
+      };
+    } catch (err) {
+      console.warn(`[hooks/regen-watchdog] threw:`, err.message);
+      return {};
+    }
+  };
+}
+
+/**
+ * PostToolUse(record_decision) —— 锚定风格那一笔之后提醒落两处长期资产
+ * （2026-07-28，配合"记忆归 SDK / 品牌归我们 / 指引归用户"的分工）
+ *
+ * 只在这一笔上注、每 session 一次：
+ *   - 品牌档案 `agent-memory/brand/memory.md` —— 前端 BrandCard 会把色板 /
+ *     字体渲染出来，是结构化资产，agent 不写就永远空着
+ *   - 项目指引 `.claude/CLAUDE.md` —— SDK 每次 session 自动读进 system prompt，
+ *     但只有用户能决定要不要固化，所以是"问一句"不是"直接写"
+ *
+ * 通用偏好不在这儿管：那是 SDK 自动记忆的活（autoMemoryDirectory 已指到
+ * .claude/agent-memory/auto，前端记忆卡直接显示）。
+ */
+export function makePostToolUseStyleAnchorNudge({ sharedRoot }) {
+  let nudged = false;
+  const ANCHOR_RE = /(style-anchor|风格锚|锚定|视觉基调|palette|配色方案)/i;
+  return async (input, _toolUseId, _options) => {
+    if (nudged) return {};
+    const t = input?.tool_input || {};
+    const blob = `${t.topic || ''} ${t.title || ''} ${t.decision || ''} ${t.rationale || ''}`;
+    if (!ANCHOR_RE.test(blob)) return {};
+    nudged = true;
+    const guidePath = sharedRoot ? path.join(sharedRoot, '.claude', 'CLAUDE.md') : '.claude/CLAUDE.md';
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext:
+          '这一笔看起来是在锚定这个项目的视觉方向。顺手做两件事（都只做一次）：\n'
+        + '1. 把这版风格写进 `.claude/agent-memory/brand/memory.md`（色号 / 字体链 / 版式语言 / 动效预算；⚠️ 带 .claude/ 前缀，写错位置 BrandCard 读不到），'
+        + '前端品牌档案卡会把色板和字体渲染出来给用户看，不写就一直空着。\n'
+        + `2. 如果这次定下来的还包含**项目级约束**（不只这一个 deck 适用，比如"这个项目一律不用 emoji"），`
+        + `在收尾时问用户一句要不要写进项目指引（${guidePath}，SDK 每次 session 自动读它）。用户点头你再写。\n`
+        + '用户的通用偏好不用你手动记，系统的自动记忆会管。',
+      },
+    };
+  };
+}

package/server/engine/agent/hooks/post-subagent-report.js

@@ -1,104 +1,104 @@
-/**
- * hooks/post-subagent-report.js — 子代理报告丢了的时候别整轮重跑（2026-08-18）
- *
- * ## 问题
- *
- * SDK 的子代理触到 `maxTurns` 时返回的是 SDKResultError，**那个类型没有 result
- * 字段** —— 最后一条 assistant 消息（也就是报告本身）直接消失，主 agent 拿到的
- * 是空的或者只有开场白。工作已经做完、token 已经烧掉，结果拿不到。
- *
- * 2026-08-05 真实记录：两次派 explorer，一次 59292 tokens / 16 轮工具调用 / 110s，
- * 回来只有一句开场白；一次 31228 tokens / 17 轮，回来 "(returned no output.)"。
- * 中间轮次少的那次正常。主 agent 的绕行只能是"拆小重派"或"放弃子代理" ——
- * 等于放弃了子代理隔离上下文的全部价值，长研究任务反而不敢派了。
- *
- * ## 做法
- *
- * 我们改不了 SDK 那个类型，但 `task_notification` 上带着 **`output_file`** ——
- * 子代理的完整转录 JSONL。所以：报告看起来是空的时候，把转录路径递给主 agent，
- * 让它 Read 一遍把结论捞出来。**从"整轮白烧"变成"多读一个文件"。**
- *
- * ⚠️ 判据故意保守（只在摘要短得不像报告时才提示）：把这句话贴在每次正常的
- * 子代理返回后面是噪音，而噪音会训练 agent 忽略提示。
- */
-
-/** tool_use_id → 最近一次 task_notification（agent-shared 在收到时写进来） */
-const lastNotification = new Map();
-const MAX_TRACKED = 200;
-
-export function recordTaskNotification(msg) {
-  if (!msg?.tool_use_id) return;
-  lastNotification.set(msg.tool_use_id, {
-    status: msg.status,
-    summary: msg.summary || '',
-    outputFile: msg.output_file || null,
-    toolUses: msg.usage?.tool_uses ?? null,
-    tokens: msg.usage?.total_tokens ?? null,
-  });
-  // 别无限长：一个会话里子代理数量有限，但进程是长命的
-  if (lastNotification.size > MAX_TRACKED) {
-    const first = lastNotification.keys().next().value;
-    lastNotification.delete(first);
-  }
-}
-
-/** 已经消费过的 id（用来区分"没记上"和"记过又用掉了"，见下面那段） */
-const consumed = new Set();
-let missing = 0;
-
-/** 报告"看起来是空的"的判据 —— 短于这个就不像一份报告 */
-const SUSPICIOUS_LEN = 200;
-
-export function makePostToolUseSubagentReportRecovery() {
-  return async (input) => {
-    const id = input?.tool_use_id;
-    if (!id) return {};
-    const note = lastNotification.get(id);
-    if (!note) {
-      // ⚠️ 这条分支是「静默死」的经典形状：`recordTaskNotification` 必须**先于**
-      // 这个 hook 跑，否则整个 handler 什么都不做而且一声不响。这个仓库为
-      // 「hook 静默死」付过三次账（最贵一次 19 个会话 0 触发、38k tokens 白跑），
-      // 所以宁可留一行日志：真出问题时它会成堆出现，而不是一片安静。
-      // 正常也会走到这儿（同一个 id 第二次进来，note 已被一次性消费掉），
-      // 所以只在**从来没见过这个 id** 时才记。
-      if (!consumed.has(id)) {
-        missing += 1;
-        console.warn(`[subagent-report] tool_use_id ${id} 没有对应的 task_notification`
-          + `（累计 ${missing} 次）—— 如果这个数字在涨，说明 recordTaskNotification`
-          + ' 没有跑在这个 hook 之前，兜底其实是死的。');
-      }
-      return {};
-    }
-    consumed.add(id);
-    if (consumed.size > MAX_TRACKED) consumed.delete(consumed.values().next().value);
-    lastNotification.delete(id);          // 一次性
-
-    const looksEmpty = note.summary.trim().length < SUSPICIOUS_LEN;
-    // 摘要有内容就什么都不说 —— 报告回来了，再贴一段提示是噪音，
-    // 而噪音会训练 agent 忽略提示。
-    if (!looksEmpty) return {};
-    const didRealWork = (note.toolUses ?? 0) >= 4 || (note.tokens ?? 0) >= 8000;
-
-    const lines = [
-      `⚠️ 这个子代理回来的内容只有 ${note.summary.trim().length} 个字符`
-      + `（status=${note.status}${note.toolUses != null ? `，跑了 ${note.toolUses} 次工具调用` : ''}`
-      + `${note.tokens != null ? `，${note.tokens} tokens` : ''}）。`,
-    ];
-    if (didRealWork) {
-      lines.push('它**确实干了活**，但最终报告没回传 —— SDK 的子代理触到轮次上限时'
-        + '返回的错误类型不带 result 字段，最后那条消息会整个丢掉。');
-    }
-    if (note.outputFile) {
-      lines.push(`完整转录在 \`${note.outputFile}\`。**Read 它把结论捞出来，别整轮重派** ——`
-        + 'token 已经烧掉了，重跑一遍只是再烧一次。转录是 JSONL，从后往前读最快。');
-    } else {
-      lines.push('没有转录路径可捞。要重派的话把任务拆小（工具调用轮次少的时候不会丢）。');
-    }
-    return {
-      hookSpecificOutput: {
-        hookEventName: 'PostToolUse',
-        additionalContext: lines.join('\n'),
-      },
-    };
-  };
-}
+/**
+ * hooks/post-subagent-report.js — 子代理报告丢了的时候别整轮重跑（2026-08-18）
+ *
+ * ## 问题
+ *
+ * SDK 的子代理触到 `maxTurns` 时返回的是 SDKResultError，**那个类型没有 result
+ * 字段** —— 最后一条 assistant 消息（也就是报告本身）直接消失，主 agent 拿到的
+ * 是空的或者只有开场白。工作已经做完、token 已经烧掉，结果拿不到。
+ *
+ * 2026-08-05 真实记录：两次派 explorer，一次 59292 tokens / 16 轮工具调用 / 110s，
+ * 回来只有一句开场白；一次 31228 tokens / 17 轮，回来 "(returned no output.)"。
+ * 中间轮次少的那次正常。主 agent 的绕行只能是"拆小重派"或"放弃子代理" ——
+ * 等于放弃了子代理隔离上下文的全部价值，长研究任务反而不敢派了。
+ *
+ * ## 做法
+ *
+ * 我们改不了 SDK 那个类型，但 `task_notification` 上带着 **`output_file`** ——
+ * 子代理的完整转录 JSONL。所以：报告看起来是空的时候，把转录路径递给主 agent，
+ * 让它 Read 一遍把结论捞出来。**从"整轮白烧"变成"多读一个文件"。**
+ *
+ * ⚠️ 判据故意保守（只在摘要短得不像报告时才提示）：把这句话贴在每次正常的
+ * 子代理返回后面是噪音，而噪音会训练 agent 忽略提示。
+ */
+
+/** tool_use_id → 最近一次 task_notification（agent-shared 在收到时写进来） */
+const lastNotification = new Map();
+const MAX_TRACKED = 200;
+
+export function recordTaskNotification(msg) {
+  if (!msg?.tool_use_id) return;
+  lastNotification.set(msg.tool_use_id, {
+    status: msg.status,
+    summary: msg.summary || '',
+    outputFile: msg.output_file || null,
+    toolUses: msg.usage?.tool_uses ?? null,
+    tokens: msg.usage?.total_tokens ?? null,
+  });
+  // 别无限长：一个会话里子代理数量有限，但进程是长命的
+  if (lastNotification.size > MAX_TRACKED) {
+    const first = lastNotification.keys().next().value;
+    lastNotification.delete(first);
+  }
+}
+
+/** 已经消费过的 id（用来区分"没记上"和"记过又用掉了"，见下面那段） */
+const consumed = new Set();
+let missing = 0;
+
+/** 报告"看起来是空的"的判据 —— 短于这个就不像一份报告 */
+const SUSPICIOUS_LEN = 200;
+
+export function makePostToolUseSubagentReportRecovery() {
+  return async (input) => {
+    const id = input?.tool_use_id;
+    if (!id) return {};
+    const note = lastNotification.get(id);
+    if (!note) {
+      // ⚠️ 这条分支是「静默死」的经典形状：`recordTaskNotification` 必须**先于**
+      // 这个 hook 跑，否则整个 handler 什么都不做而且一声不响。这个仓库为
+      // 「hook 静默死」付过三次账（最贵一次 19 个会话 0 触发、38k tokens 白跑），
+      // 所以宁可留一行日志：真出问题时它会成堆出现，而不是一片安静。
+      // 正常也会走到这儿（同一个 id 第二次进来，note 已被一次性消费掉），
+      // 所以只在**从来没见过这个 id** 时才记。
+      if (!consumed.has(id)) {
+        missing += 1;
+        console.warn(`[subagent-report] tool_use_id ${id} 没有对应的 task_notification`
+          + `（累计 ${missing} 次）—— 如果这个数字在涨，说明 recordTaskNotification`
+          + ' 没有跑在这个 hook 之前，兜底其实是死的。');
+      }
+      return {};
+    }
+    consumed.add(id);
+    if (consumed.size > MAX_TRACKED) consumed.delete(consumed.values().next().value);
+    lastNotification.delete(id);          // 一次性
+
+    const looksEmpty = note.summary.trim().length < SUSPICIOUS_LEN;
+    // 摘要有内容就什么都不说 —— 报告回来了，再贴一段提示是噪音，
+    // 而噪音会训练 agent 忽略提示。
+    if (!looksEmpty) return {};
+    const didRealWork = (note.toolUses ?? 0) >= 4 || (note.tokens ?? 0) >= 8000;
+
+    const lines = [
+      `⚠️ 这个子代理回来的内容只有 ${note.summary.trim().length} 个字符`
+      + `（status=${note.status}${note.toolUses != null ? `，跑了 ${note.toolUses} 次工具调用` : ''}`
+      + `${note.tokens != null ? `，${note.tokens} tokens` : ''}）。`,
+    ];
+    if (didRealWork) {
+      lines.push('它**确实干了活**，但最终报告没回传 —— SDK 的子代理触到轮次上限时'
+        + '返回的错误类型不带 result 字段，最后那条消息会整个丢掉。');
+    }
+    if (note.outputFile) {
+      lines.push(`完整转录在 \`${note.outputFile}\`。**Read 它把结论捞出来，别整轮重派** ——`
+        + 'token 已经烧掉了，重跑一遍只是再烧一次。转录是 JSONL，从后往前读最快。');
+    } else {
+      lines.push('没有转录路径可捞。要重派的话把任务拆小（工具调用轮次少的时候不会丢）。');
+    }
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: lines.join('\n'),
+      },
+    };
+  };
+}