dsh-chubby-whale 1.1.59 → 1.1.61

package/CHANGELOG.md

@@ -4,6 +4,57 @@
 
 ## [未发布]
 
+## [1.1.61] - 2026-11-07
+
+### 修复（B89 宿主 HTTP 层分身）
+- **413 永远送不到客户端**：`readBody` 发现超限先 `abortRequest()`→`destroy()` 再抛错，连接被主动断掉，`sendTooLarge` 写的 413 根本没机会发出（真实 socket 探针：声明超限与 chunked 超限**全部** `ECONNRESET`、0 个 413）。现在区分两种语义：声明超限=不读流不断连，流式超限=1MB 预算内 drain 后再判
+- **UTF-8 BOM 让合法 JSON 变成空请求**：`readJsonBody` 未剥 BOM，`JSON.parse` 必抛 → `body={}`；带 BOM 的备份包原本被判 400 `BAD_BODY`
+- **二次写响应抛 `ERR_HTTP_HEADERS_SENT`**：宿主 webserver 在 `headersSent` 后只 `destroy()` → 客户端丢掉已写好的响应；四个 writer 统一加短路
+
+### 修复（B89 客户端网络层分身）
+- **非对象 SSE 帧进 events**：`data: null` 会让 `chat.ts` 读 `obj.error` 抛 TypeError → 白回退一轮 `/chat`（白烧一次模型）；现在只收对象帧，其余计 `invalid`
+- **恢复快捷键抢别的键**：`keyCode=87` 兜底不看 `key`，`Ctrl+Shift+Z` 会被当成恢复快捷键
+
+### 修复（B89 纯函数工具层分身）
+- **切句器卡死**：增量以句末标点开头时（`。你好。世界。`）既不吐也不前进，后面整段攒到 `maxLen` 才出
+- **书名劫持普通陈述**：「我在看三国」「三国好看」被判成说书点播
+- **否定句反着做**：「不要讲故事」→ 真的讲起来了；「讲个故事吗。」不认提问
+- **脏 fallback 透传 TTS**：`poemRate('胡说')` 原样进 TTS rate
+- **`lock(0)` 闭麦一分钟**：空文本估算 0 被 `|| 60000` 兜成 60s；且 `expire()` 与 `active()` 差 1ms 界线（`t===until` 时不释放）
+- **对仗分类静默错档**：`pickCouplet(null, ' 春联')` 会落「书院」
+
+### 修复（主代理）
+- **`/chat` 超时被报成普通失败**：只认 `AbortError`/20/2，`AbortSignal.timeout()` 的 `TimeoutError`（code 23）漏判（`story.ts` 早已补）
+- **endpoint 切换重复写盘**：先自己写一次再让实例 setter 写一次，setter 抛错时落盘值与实例值分叉；改为有实例时只走 setter
+- **多文件拖入静默丢弃**：只取第一张，其余文件没有任何提示；现在先提示「一次一张（共 N 个）」再处理第一张
+- 文档：坑 49（读体超限的两种语义、新路由必须用 `sendTooLarge` 收尾）；`story.ts` 的超限注释改为新语义
+
+### 测试
+- 新增 `test-host-http.mjs`(32)、`test-net-client.mjs`(122+4 变异体)、`test-utils-pure.mjs`(153)、`test-multidrop.mjs`(10)，均接入 `npm test`
+- 全链 **3258 项 0 失败**（`node tools/test-count.mjs`：45 个套件，失败 0，未识别 0）
+
+## [1.1.60] - 2026-11-07
+
+### 修复（B87 数据端口收口：路由不再直读 data/）
+- **`/poem-titles` 与 `/melodies`、`/melody` 直读 `data/`**：违反 ADR 0002「路由只经端口取数据」，且 `poem-titles` 的 handler 连 `dataPort` 参数都没有。现在 `DataPort` 增**可选**方法 `readPoemTitles()` / `readMelodies()`：本地带 mtime 缓存 + BOM 容错 + 坏 JSON 返回 null 并留痕；云端声明就拉、未声明/网络坏时回退本地
+- 路由口径：**端口存在即权威**（返回 null 也不回读文件），只有端口缺方法时才走文件回退（回退分支注释写明移除条件）；`/melody` 响应字段完全未变
+- 装配漏注入：`index.ts` 给 `poem-titles` 补上 `dataPort`（此前不注入等于永远走回退）
+- 过时文案：`test-data-layer` 端口面断言 6 项→8 项；`test-content-routes` 的「已知缺口」改为「已收口」
+
+### 修复（B88 念诗回调与待命出声）
+- **同一使用方连念两首，旧诗的 onDone 会清新诗的锁**：`client.ts` 的 `narrateOwner` 是**按使用方**分的，菜单「念首诗」两次共用同一句柄、ownerId 不变，挡不住。现在 `culture.ts` 加 per-call 令牌 `poemGen`：只有最新一首的 onDone 能停进度、清锁、说「念完啦」，且同一次收尾只放行一次
+- **`sayLine` 用 `bridge.get()`**：待命关着刷新后 `get()` 为 null，开场问候/情绪台词只有气泡没声（而念诗/说书/提醒走 `ensure()` 一直有声）。改为 `ensure()`，与其它朗读路径一致；真正管静音的是「语音朗读」开关（关掉后 ensure/spoken 都不动）
+- 念诗 `speak` 同步抛错时补 `release()`（与 `actions/content.ts` 同口径），不再等 5 分钟叙述锁自愈
+- 语音实例的卸载回收不再依赖 `earOn`：`ensure()` 可能在待命关着时建实例，原来那种情况 SPA 卸载不会 dispose
+
+### 变更（B86 主代理）
+- `VoiceStats.asrBusyDropped`：ASR「忙则丢」的丢段次数计入统计（原来只在 diag 流里可见）
+- 文档：《坑》补坑 47（叙述锁只有一份 / 持有者令牌 / `narrateOverdue` 读法）、坑 48（ASR 无单飞无纪元与取舍）；《并发纪律》更正「纪元只覆盖对话」→ 覆盖对话与 ASR，规则 5 补 `clearNarrate` 只认持有者
+
+### 测试
+- 新增 `test-dataport-poem.mjs`(56)、`test-poem-narration.mjs`(34)，均接入 `npm test`
+- 全链 **2936 项 0 失败**（`node tools/test-count.mjs`：41 个套件，失败 0，未识别 0）
+
 ## [1.1.59] - 2026-11-07
 
 ### 修复（B82 装配层分身：云端 TTS 从未接线）

package/dist/client.js

@@ -14,7 +14,7 @@
   }
 
   // src/client/version.ts
-  var VERSION = "1.1.59";
+  var VERSION = "1.1.61";
 
   // src/client/styles.ts
   var W = 240;
@@ -352,10 +352,14 @@
   var DEFAULT_CHAT_RATE = "-20%";
   var DEFAULT_STORY_RATE = "-35%";
   var DEFAULT_POEM_RATE = "-25%";
+  function validPercent(v) {
+    const s = String(v == null ? "" : v).trim();
+    return /^-(?:[1-9]\d?)%$/.test(s) ? s : "";
+  }
   function readPercentRate(key, fallback) {
     try {
-      const s = String(localStorage.getItem(key) || "").trim();
-      if (/^-(?:[1-9]\d?)%$/.test(s)) return s;
+      const s = validPercent(localStorage.getItem(key));
+      if (s) return s;
     } catch (e) {
     }
     return fallback;
@@ -364,7 +368,7 @@
     return readPercentRate("chubby-story-rate", DEFAULT_STORY_RATE);
   }
   function poemRate(fallback = DEFAULT_POEM_RATE) {
-    return readPercentRate("chubby-poem-rate", fallback);
+    return readPercentRate("chubby-poem-rate", validPercent(fallback) || DEFAULT_POEM_RATE);
   }
   function chatRate() {
     try {
@@ -603,6 +607,7 @@
   function createSentenceBuffer(maxLen = 40) {
     const limit = Math.max(2, Number(maxLen) || 40);
     let tail = "";
+    let lead = "";
     function take(force) {
       const out = [];
       for (; ; ) {
@@ -611,18 +616,25 @@
         if (!tail) break;
         const m = tail.match(/[\s\S]*?[。！？!?；;\n]/);
         if (m && m[0].length >= 2) {
-          const seg = m[0].trim();
+          const seg = (lead + m[0]).trim();
+          lead = "";
           tail = tail.slice(m[0].length);
           if (seg) out.push(seg);
           continue;
         }
-        if (force || tail.length >= limit) {
-          const seg = tail.trim();
-          tail = "";
-          if (seg) out.push(seg);
+        if (m) {
+          lead += m[0];
+          tail = tail.slice(m[0].length);
+          continue;
         }
         break;
       }
+      if (force || tail.length + lead.length >= limit) {
+        const seg = (lead + tail).trim();
+        lead = "";
+        tail = "";
+        if (seg) out.push(seg);
+      }
       return out;
     }
     return {
@@ -1256,6 +1268,7 @@
       skippedSilent: 0,
       uploaded: 0,
       asrFail: 0,
+      asrBusyDropped: 0,
       asrRetry: 0,
       asrTexts: 0,
       heard: 0,
@@ -1770,6 +1783,10 @@
         return;
       }
       if (asrBusy) {
+        try {
+          stats.asrBusyDropped = (stats.asrBusyDropped || 0) + 1;
+        } catch (e) {
+        }
         try {
           opts.onDiag && opts.onDiag({ stage: "asr-busy-drop", hint: "上一段还在识别，这一段丢弃（不排队）" });
         } catch (e) {
@@ -4418,7 +4435,8 @@
   var COUPLET_CATS = ["书院", "格言", "谐趣", "名胜", "书房", "春联", "寿联", "景观", "中药", "叠字", "数字"];
   deepFreeze(COUPLET_CATS);
   function pickCouplet(excludeUpper, cat) {
-    const byCat = cat ? COUPLETS.filter((c) => c.cat === cat) : COUPLETS;
+    const key = cat == null ? "" : String(cat).trim();
+    const byCat = key ? COUPLETS.filter((c) => c.cat === key) : COUPLETS;
     const base = byCat.length > 0 ? byCat : COUPLETS;
     const pool = base.length > 1 && excludeUpper ? base.filter((c) => c.upper !== excludeUpper) : base;
     const src = pool.length > 0 ? pool : base;
@@ -4434,6 +4452,7 @@
     recentStarts.set(key, now);
     return true;
   }
+  var poemGen = 0;
   function recitePoem(host, poem) {
     if (!beginOnce("poem")) {
       host.bubble("正在念呢，稍等～", 2e3);
@@ -4451,21 +4470,28 @@
     host.bubble("念诗·" + poem.title + "（" + author + "）" + (totalLines > 1 ? "· 共 " + totalLines + " 句" : ""), 15e3);
     host.talkFor(6e3);
     const speech = intro + collapsePoemBody(body);
+    const my = ++poemGen;
     host.narrate(estimateSpeakMs(speech));
     host.say(host.persona.line("poemStart"), 4e3);
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      if (my !== poemGen) return;
+      try {
+        stopProgress();
+      } catch (e) {
+      }
+      host.clearNarrate();
+      host.say(host.persona.line("poemDone"), 6e3, { rate: "-8%", pitch: "+15Hz" });
+    };
     try {
       host.speak(speech, {
         rate: poemRate(host.narrationRate()),
-        onDone: () => {
-          try {
-            stopProgress();
-          } catch (e) {
-          }
-          host.clearNarrate();
-          host.say(host.persona.line("poemDone"), 6e3, { rate: "-8%", pitch: "+15Hz" });
-        }
+        onDone: release
       });
     } catch (e) {
+      release();
     }
   }
   function finishSpeech(host, doneText) {
@@ -5552,8 +5578,8 @@
         const v = host.voice();
         const cur = v && v.endpointInfo ? v.endpointInfo().mode : readEndpointMode();
         const next = cur === "ape" ? "classic" : "ape";
-        writeEndpointMode(next);
         if (v && v.setEndpointMode) v.setEndpointMode(next);
+        else writeEndpointMode(next);
         const real = v && v.endpointInfo ? v.endpointInfo().mode : next;
         host.bubble(real === "ape" ? "端点检测：自适应（试用）" : "端点检测：经典（稳定）", 4e3);
       } catch (e) {
@@ -6162,7 +6188,8 @@
     let until = 0;
     return {
       lock(ms2) {
-        const dur = Math.max(NARRATE_MIN_MS, Math.min(Number(ms2) || 6e4, NARRATE_MAX_MS));
+        const n = ms2 == null ? NaN : Number(ms2);
+        const dur = Math.max(NARRATE_MIN_MS, Math.min(Number.isNaN(n) ? 6e4 : n, NARRATE_MAX_MS));
         until = Date.now() + dur;
       },
       clear() {
@@ -6178,7 +6205,7 @@
       },
       expire(now) {
         const t = typeof now === "number" ? now : Date.now();
-        if (!until || t <= until) return false;
+        if (!until || t < until) return false;
         until = 0;
         return true;
       }
@@ -6858,6 +6885,16 @@
   ];
   deepFreeze(BOOK_ALIAS);
   var BARE_STRIP = /[\s。，！？、,.!?…~～]/g;
+  var BARE_TAIL_PARTICLES = "吧啊呀呢么嘛哈哦嗯啦";
+  function isBareBookName(bare, book, alias) {
+    if (!bare) return false;
+    if (bare === book) return true;
+    const core = BARE_TAIL_PARTICLES.indexOf(bare.slice(-1)) >= 0 ? bare.slice(0, -1) : bare;
+    if (core === book) return true;
+    const m = alias.exec(core);
+    return !!m && m.index === 0 && core.length <= m[0].length + 1;
+  }
+  var NEGATED_ASK = /(不|别|甭|勿|无需)(要|用|想|再|许|必)?\s*(讲|说|念|背|来|放|听|唱)/;
   function matchPoemTitle(text) {
     const t = String(text || "");
     if (!t) return "";
@@ -6867,12 +6904,13 @@
     return "";
   }
   function isQuestion(text) {
-    return /[?？]|为什么|怎么|如何|什么|谁|哪[儿里]?|多少|几点|几号|是不是|能不能|要不要|吗\s*$|呢\s*$/.test(String(text || ""));
+    return /[?？]|为什么|怎么|如何|什么|谁|哪[儿里]?|多少|几点|几号|是不是|能不能|要不要|吗[。．.!！…~～]*\s*$|呢[。．.!！…~～]*\s*$/.test(String(text || ""));
   }
   function detectIntent(rawText) {
     const t = String(rawText || "").trim();
     if (!t || t.length > 30) return null;
     if (isQuestion(t)) return null;
+    if (NEGATED_ASK.test(t)) return null;
     if (poemTitles().length === 0) ensurePoemTitles();
     const byTitle = matchPoemTitle(t);
     if (byTitle) {
@@ -6885,17 +6923,17 @@
       const asksCulture = /讲|说|来|听|教|学|点|考/.test(t);
       if (asksCulture) return { kind: "culture", sub: /成语/.test(t) ? "idiom" : "chengyu" };
     }
-    let book = "";
-    for (const [re, name] of BOOK_ALIAS) {
-      if (re.test(t)) {
-        book = name;
+    let hit = null;
+    for (const pair of BOOK_ALIAS) {
+      if (pair[0].test(t)) {
+        hit = pair;
         break;
       }
     }
-    if (book) {
+    if (hit) {
       const bare = t.replace(BARE_STRIP, "");
-      const asksBook = /讲|说书|听|来(一)?段|来(一)?回/.test(t) || bare.length <= book.length + 1;
-      if (asksBook) return { kind: "story", book };
+      const asksBook = /讲|说书|听|来(一)?段|来(一)?回/.test(t) || isBareBookName(bare, hit[1], hit[0]);
+      if (asksBook) return { kind: "story", book: hit[1] };
     }
     if (/讲故事|讲个故事|说书|来段|讲一段/.test(t)) return { kind: "story", book: "" };
     return null;
@@ -7003,7 +7041,9 @@
       const payload = line.slice(5).trim();
       if (!payload || payload === "[DONE]") continue;
       try {
-        events.push(JSON.parse(payload));
+        const v = JSON.parse(payload);
+        if (v && typeof v === "object") events.push(v);
+        else invalid++;
       } catch (e) {
         invalid++;
       }
@@ -7375,7 +7415,7 @@
         if (data && data.upgraded) host.bubble("本鲸又长大一点啦！", 4e3);
       } catch (err) {
         if (!host.epoch.isCurrent(myEpoch)) return;
-        const timedOut = !!err && (err.name === "AbortError" || err.code === 20 || err.code === 2);
+        const timedOut = !!err && (err.name === "AbortError" || err.name === "TimeoutError" || err.code === 20 || err.code === 2 || err.code === 23);
         const tip = timedOut ? "主人，本鲸等太久啦（网络慢），再问一次？" : host.persona.line("error");
         if (d1) d1.lastChat = { stage: timedOut ? "timeout" : "error", error: String(err && err.message || err).slice(0, 60), at: Date.now() };
         fishTip(host, tip, 5e3);
@@ -7709,6 +7749,7 @@
     if (!ctrl || !shift) return false;
     const key = str(e.key).toLowerCase();
     if (key === "w") return true;
+    if (key && key !== "unidentified") return false;
     const code = Number(e.keyCode != null ? e.keyCode : e.which);
     return code === 87;
   }
@@ -7812,7 +7853,12 @@
       e.preventDefault();
       e.stopPropagation();
       const dt = e.dataTransfer;
-      const file = dt && dt.files && dt.files[0];
+      const files = dt && dt.files ? dt.files : null;
+      const file = files && files[0];
+      try {
+        if (files && files.length > 1 && typeof opts.onMany === "function") opts.onMany(files.length);
+      } catch (e2) {
+      }
       try {
         opts.onFile(file);
       } catch (e2) {
@@ -8683,6 +8729,12 @@
                 });
               } catch (e2) {
               }
+            },
+            onMany: (n) => {
+              try {
+                showBubble("一次先看一张哦～先看第一张（共 " + n + " 个）", 3200);
+              } catch (e2) {
+              }
             }
           });
         }, []);
@@ -9352,11 +9404,17 @@
           return reminderPoller.start();
         }, []);
         R.useEffect(() => {
-          if (!earOnRef.current) return;
-          void bridge.start();
-          return () => {
-            bridge.dispose();
+          const cleanup = () => {
+            try {
+              bridge.dispose();
+            } catch (e) {
+            }
           };
+          if (earOnRef.current) {
+            void bridge.start();
+            return cleanup;
+          }
+          return cleanup;
         }, []);
         function speakText(text, o) {
           try {
@@ -9397,7 +9455,7 @@
           }
           try {
             if (localStorage.getItem("chubby-voice") === "off") return;
-            const v = bridge.get();
+            const v = bridge.ensure();
             if (v && v.speak && !v.speaking()) v.speak(text, { rate: voiceOpts && voiceOpts.rate || chatRate(), pitch: voiceOpts && voiceOpts.pitch || "" });
           } catch (e) {
           }

package/dist/host/body.js

@@ -6,6 +6,15 @@
  * 这里只统一「读 + 判 + 解析」；日志标签、413 响应由调用方决定（保持原有各路由的日志文案）。
  */
 import { isBodyTooLarge, readBody } from './http.js';
+/**
+ * 去掉文本开头的 UTF-8 BOM（U+FEFF）。
+ * Node 的 Buffer.toString('utf8') 不会再吞 BOM，而 JSON.parse 不容忍它（坑 15 / 坑 37 的同一个坑）：
+ * 带 BOM 的 `{"a":1}` 会落到「解析失败 → body={}」，客户端拿到的是「空请求」而不是自己的数据。
+ * 这里只在解析前剥一次，`raw` 仍是原始字节，调用方要原样留证不受影响。
+ */
+function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
 /**
  * 带上限读请求体并解析 JSON。
  * - 超过 maxBytes：返回 {ok:false,tooLarge:true}（不抛），调用方回 413；
@@ -22,7 +31,7 @@ export async function readJsonBody(req, maxBytes) {
             return { ok: false, tooLarge: true };
         throw err;
     }
-    const text = raw.toString('utf8');
+    const text = stripBom(raw.toString('utf8'));
     let body = {};
     try {
         body = text ? JSON.parse(text) : {};

package/dist/host/data/cloud.js

@@ -6,6 +6,9 @@
  *   culture/chengyu.json、culture/idioms.json、culture/minsu-00..09.json、
  *   story/index.json、story/<书名>.json。
  *
+ * 诗名索引 / 曲库（2026-11-07 端口收口新增）也按同一口径处理：云端清单里声明了
+ * poem-titles.json / melodies.json 就按需拉取，没声明就回退本地实现（包内只读文件）。
+ *
  * 策略：
  *   · 按需拉：用到哪本小说/哪类文化/哪片诗才拉哪个文件；
  *   · 内存缓存：拉过的文件留在进程内；清单每 30 秒最多检查一次，
@@ -353,5 +356,58 @@ export function createCloudDataPort(opts) {
             return out;
         }, () => local.readDaily());
     }
-    return { readStoryIndex, readStoryBook, readCulture, readPoemsChunk, readDuilian, readDaily };
+    /**
+     * 回退到本地实现的可选端口方法：老宿主 / 测试假端口可能没实现 readPoemTitles /
+     * readMelodies（DataPort 上它们是可选方法）。缺失或抛错都按「本地也没数据」（null）
+     * 处理，绝不把异常带出数据层——路由拿到的不是数据就是 null。
+     */
+    async function localOrNull(read) {
+        if (typeof read !== 'function')
+            return null;
+        try {
+            return await read.call(local);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 诗名索引：云端清单声明了 poem-titles.json 就取云端，否则回退本地包内文件。
+     * 清单没声明属于「数据缺失」（DataUnavailable）：静默回退、不进 60 秒冷却；
+     * 坏 JSON / 网络失败走链路失败分支：记 CLOUD-DATA-FAIL 后回退本地，绝不抛。
+     */
+    async function readPoemTitles() {
+        return withFallback('readPoemTitles', async () => {
+            const raw = await readFile('poem-titles.json');
+            const titles = [];
+            if (raw && Array.isArray(raw.titles)) {
+                for (const item of raw.titles)
+                    if (typeof item === 'string' && item)
+                        titles.push(item);
+            }
+            if (titles.length === 0)
+                dataUnavailable('poem titles empty');
+            return { titles };
+        }, () => localOrNull(local.readPoemTitles));
+    }
+    /**
+     * 曲库：云端清单声明了 melodies.json 就取云端，否则回退本地。
+     * 返回顶层浅拷贝 + 新 songs 数组：fileCache 里的原始 parse 结果不直接递给路由
+     * （与 normalize 系列同一条所有权纪律）。非对象结构按数据缺失处理。
+     */
+    async function readMelodies() {
+        return withFallback('readMelodies', async () => {
+            const raw = await readFile('melodies.json');
+            if (!raw || typeof raw !== 'object')
+                dataUnavailable('melodies bad structure');
+            const songs = Array.isArray(raw.songs)
+                ? raw.songs.filter((s) => s && typeof s === 'object').map((s) => ({ ...s }))
+                : [];
+            return { ...raw, songs };
+        }, () => localOrNull(local.readMelodies));
+    }
+    return {
+        readStoryIndex, readStoryBook, readCulture, readPoemsChunk, readDuilian, readDaily,
+        readPoemTitles, readMelodies,
+    };
 }

package/dist/host/data/local.js

@@ -35,10 +35,15 @@ export function createLocalDataPort(opts) {
     const POEMS_FILE = join(opts.dataDir, 'poems.json');
     const DUILIAN_FILE = join(opts.dataDir, 'duilian.json');
     const DAILY_FILE = join(opts.dataDir, 'daily.json');
+    /** 诗名索引 / 曲库：随包只读数据文件（路由经 DataPort 的同名可选方法取，见 ports.ts） */
+    const POEM_TITLES_FILE = join(opts.dataDir, 'poem-titles.json');
+    const MELODIES_FILE = join(opts.dataDir, 'melodies.json');
     const cultureCache = new Map();
     let poemsCache = null;
     let duilianCache = null;
     let dailyCache = null;
+    let poemTitlesCache = null;
+    let melodiesCache = null;
     /**
      * 文件最后修改时间（读不到返回 0）；缓存据此失效，改数据不必重启。
      * mtimeMs 在 NTFS / ext4 / APFS 上可靠；FAT / exFAT 只有 2 秒精度，
@@ -85,6 +90,31 @@ export function createLocalDataPort(opts) {
             out.note = d.note;
         return out;
     }
+    /**
+     * 诗名索引：只认 {titles:[...]}，过滤空串/非字符串（与改造前 poem-titles 路由的过滤口径一致）；
+     * 空表按「没数据」处理（调用方返回 null，路由走既有 ok:false 兜底）。
+     */
+    function pickTitles(raw) {
+        const list = raw && Array.isArray(raw.titles) ? raw.titles : [];
+        const out = [];
+        for (const item of list)
+            if (typeof item === 'string' && item)
+                out.push(item);
+        return out;
+    }
+    /**
+     * 曲库：保留整份对象（路由自己取 songs / notes / lyrics），songs 条目浅拷贝后返回，
+     * 缓存本体不交给调用方（与其它读口同一条缓存所有权纪律）。
+     * 合法 JSON 但不是对象（例如字面量 null / 数字）按不可用处理，路由走既有失败兜底。
+     */
+    function cloneMelodies(raw) {
+        if (!raw || typeof raw !== 'object')
+            return null;
+        const songs = Array.isArray(raw.songs)
+            ? raw.songs.filter((s) => s && typeof s === 'object').map((s) => ({ ...s }))
+            : [];
+        return { ...raw, songs };
+    }
     async function readStoryIndex() {
         try {
             const books = await opts.story.listBooks();
@@ -166,5 +196,49 @@ export function createLocalDataPort(opts) {
         dailyCache = { value: out, mtimeMs: mt };
         return cloneItems(out);
     }
-    return { readStoryIndex, readStoryBook, readCulture, readPoemsChunk, readDuilian, readDaily };
+    /**
+     * 诗名索引：缺文件 / 坏 JSON / 空表一律 null（不抛），路由按既有 ok:false 兜底。
+     * 缓存口径与其它读口一致：按 mtime 失效，坏 JSON 这类确定性失败可以记空缓存，
+     * 瞬时读错误不写缓存（否则一次文件占用会把诗名永久锁成空）。
+     */
+    async function readPoemTitles() {
+        const mt = fileMtime(POEM_TITLES_FILE);
+        if (poemTitlesCache && mt > 0 && poemTitlesCache.mtimeMs === mt) {
+            const hit = poemTitlesCache.value;
+            return hit ? { titles: hit.titles.slice() } : null;
+        }
+        const loaded = await loadJsonFile(POEM_TITLES_FILE, 'POEM-TITLES-LOAD-FAIL');
+        let out = null;
+        if (loaded.ok) {
+            const titles = pickTitles(loaded.raw);
+            if (titles.length > 0)
+                out = { titles };
+            // 合法 JSON 但结构不对/空表：留痕，与「文件坏了」同口径按不可用处理
+            else
+                console.error('POEM-TITLES-LOAD-FAIL file=' + POEM_TITLES_FILE + ' err=empty or bad structure');
+        }
+        if (!loaded.cacheable)
+            return out;
+        poemTitlesCache = { value: out, mtimeMs: mt };
+        return out ? { titles: out.titles.slice() } : null;
+    }
+    /** 曲库：缺文件 / 坏 JSON / 非对象一律 null（不抛）；返回副本，缓存本体不外泄 */
+    async function readMelodies() {
+        const mt = fileMtime(MELODIES_FILE);
+        if (melodiesCache && mt > 0 && melodiesCache.mtimeMs === mt) {
+            return melodiesCache.value === null ? null : cloneMelodies(melodiesCache.value);
+        }
+        const loaded = await loadJsonFile(MELODIES_FILE, 'MELODIES-LOAD-FAIL');
+        const out = loaded.ok ? cloneMelodies(loaded.raw) : null;
+        if (loaded.ok && !out)
+            console.error('MELODIES-LOAD-FAIL file=' + MELODIES_FILE + ' err=bad structure');
+        if (!loaded.cacheable)
+            return out;
+        melodiesCache = { value: out, mtimeMs: mt };
+        return out ? cloneMelodies(out) : null;
+    }
+    return {
+        readStoryIndex, readStoryBook, readCulture, readPoemsChunk, readDuilian, readDaily,
+        readPoemTitles, readMelodies,
+    };
 }

package/dist/host/http.js

@@ -4,6 +4,14 @@
  */
 /** 请求体超限的错误码（readBody 抛出，路由据此回 413） */
 const BODY_TOO_LARGE = 'BODY_TOO_LARGE';
+/**
+ * 超限后还愿意「读掉并丢弃」的字节数上限。
+ * 为什么需要：readBody 抛错后路由要写 413，但如果先 destroy 了连接，413 永远送不到客户端
+ * （客户端只看得到 ECONNRESET，实测见 scripts/test-host-http.mjs）。超一点点是常态
+ * （16KB 上限的请求多发了 1KB、2MB 的备份包多打了 200KB），把这点尾巴读空再抛，
+ * 413 才真的能回出去；超过预算（对方还在猛发）仍然立刻断连，不拿内存和带宽陪跑。
+ */
+const DRAIN_GRACE = 1024 * 1024;
 function bodyTooLarge() {
     const e = new Error('body too large');
     e.code = BODY_TOO_LARGE;
@@ -54,10 +62,12 @@ export function sendTooLarge(res) {
     catch { }
 }
 /**
- * 请求体超限时把连接断掉。
- * 为什么必须断：只从 for-await 里 throw 出去只是「不再消费」，客户端还在发的 body 会继续占着
+ * 超限且「丢弃预算」也用完时把连接断掉。
+ * 为什么此时必须断：只从 for-await 里 throw 出去只是「不再消费」，客户端还在发的 body 会继续占着
  * socket，HTTP 服务也走不到 keep-alive 复用，等于每个超大请求漏一条连接。
  * destroy 优先（客户端立刻收到 RST，剩余数据丢弃）；没有 destroy 就 resume 把剩下的读空丢掉。
+ * 注意：这条路径客户端收不到 413（连接先断了），所以只在明显超大时才用——
+ * 小额超限走 readBody 里的有限 drain，让 413 能送达。
  */
 function abortRequest(req) {
     // destroy/半截读取都可能触发 error（EPIPE/ECONNRESET），先挂空监听，避免冒成未捕获异常
@@ -80,26 +90,42 @@ function abortRequest(req) {
     catch { }
 }
 /**
- * 读请求体，超过 maxBytes 立刻中止并抛 BODY_TOO_LARGE。
- * 先看 content-length（有就直接拒，连读都不读），读的过程中累计超限也当场抛，不把整份大包收进内存。
- * 抛错前先 abortRequest 断连，否则超限后客户端仍在传的 body 会一直占着连接。
+ * 读请求体，超过 maxBytes 判超限并抛 BODY_TOO_LARGE。
+ * 两道保险：
+ *   · 先看 content-length：声明值已超限就**连读都不读**直接拒（既有语义，调用方据此“不读流、不落盘”）；
+ *   · 读的过程中累计超限（无 content-length / 声明偏小）也当场判超限，不把整份大包收进内存。
+ *
+ * 超限后不立刻 destroy：路由要写 413，先断连接的话客户端只看到 ECONNRESET（413 永远送不到）。
+ * 声明超限时函数直接返回、一个字节都不读，连接由 sendTooLarge 的 `connection: close` 收掉；
+ * 流式超限时先在 maxBytes + DRAIN_GRACE 的预算内把剩余数据读掉并丢弃，再把错误抛给路由；
+ * 预算用尽还不结束才 abortRequest 断连，避免超大/慢速的体占住连接与内存。
  */
 export async function readBody(req, maxBytes) {
     const declared = Number(req && req.headers && req.headers['content-length']);
     if (Number.isFinite(declared) && declared > maxBytes) {
-        abortRequest(req);
-        throw bodyTooLarge();
+        throw bodyTooLarge(); // 不读、不断连：让路由的 413 送得出去
     }
     const chunks = [];
     let total = 0;
+    let overflow = false;
     for await (const chunk of req) {
         const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
         total += buf.length;
-        if (total > maxBytes) {
-            abortRequest(req); // 先把连接断掉，再抛给路由回 413
+        if (!overflow) {
+            if (total <= maxBytes) {
+                chunks.push(buf);
+                continue;
+            }
+            // 刚越线：半份数据对调用方没意义，先放掉，别继续涨内存
+            overflow = true;
+            chunks.length = 0;
+        }
+        if (total > maxBytes + DRAIN_GRACE) {
+            abortRequest(req); // 丢弃预算也用完：不陪跑，直接断连
             throw bodyTooLarge();
         }
-        chunks.push(buf);
     }
+    if (overflow)
+        throw bodyTooLarge(); // 已经读空，路由这时写 413 能送到客户端
     return Buffer.concat(chunks);
 }

package/dist/host/respond.js

@@ -7,8 +7,20 @@
  * 注意：本插件大量使用「HTTP 200 承载业务失败（ok:false）」的既有约定，sendError 默认沿用；
  * 需要真状态码（400/405/500）时显式传 status。
  */
+/**
+ * 响应是否已经写过：已发头或已 end 过就别再写。
+ * Node 的 ServerResponse 二次 writeHead 会抛 ERR_HTTP_HEADERS_SENT；而本插件大量
+ * 「catch 里无条件 sendError」的写法（backup / culture / misc / tts 等）一旦在回包之后再抛，
+ * 这个异常会从 catch 里冒出去，宿主 webserver 只能把连接 destroy 掉——客户端反而丢掉已经
+ * 写好的那份响应。这里统一改成「已经回过就不动」：保留第一份响应，也不再往外抛。
+ */
+function alreadyResponded(res) {
+    return Boolean(res && (res.headersSent || res.writableEnded));
+}
 /** 返回 JSON 响应；status 缺省 200（与既有路由一致） */
 export function sendJson(res, payload, status = 200) {
+    if (alreadyResponded(res))
+        return;
     res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
     res.end(JSON.stringify(payload));
 }
@@ -19,16 +31,22 @@ export function sendError(res, error, extra, status = 200) {
 }
 /** 纯文本响应（图片缺失等非 JSON 场景） */
 export function sendText(res, status, text, contentType = 'text/plain; charset=utf-8') {
+    if (alreadyResponded(res))
+        return;
     res.writeHead(status, { 'content-type': contentType });
     res.end(text);
 }
 /** 二进制响应（音频等）；额外响应头由调用方给，保持各接口原有缓存策略 */
 export function sendBuffer(res, buffer, contentType, headers = {}) {
+    if (alreadyResponded(res))
+        return;
     res.writeHead(200, Object.assign({ 'content-type': contentType }, headers));
     res.end(buffer);
 }
 /** SSE 响应头（流式聊天）；不再被缓冲的 x-accel-buffering 是给反向代理看的 */
 export function sendSseHeaders(res) {
+    if (alreadyResponded(res))
+        return;
     res.writeHead(200, {
         'content-type': 'text/event-stream; charset=utf-8',
         'cache-control': 'no-store',

package/dist/host/routes/culture.js

@@ -6,7 +6,8 @@
  *   读到旧格式 {"chengyu:名称": true} 时自动迁移成新结构。
  * 一轮讲完只清空同一类别的记录，别的类别进度保留；一轮重来时先排除上一则，
  * 避免「刚讲完又立刻同一则」（与念诗同口径，见 poem.ts 的同名处理）。
- * 数据经 DataPort 取（本地/云端由 index.ts 注入）；数据源读不到只记 CULTURE-LOAD-FAIL，按空池处理，绝不整类报错。
+ * 数据经 DataPort 取（本地/云端由 index.ts 注入；曲库走 readMelodies，见下方回退注释）；
+ * 数据源读不到只记 CULTURE-LOAD-FAIL，按空池处理，绝不整类报错。
  * 原子写/坏文件隔离走 host/atomic.ts，JSON 响应走 host/respond.ts。
  */
 import { readFile } from 'node:fs/promises';
@@ -30,6 +31,26 @@ export function createCultureHandlers(opts) {
             return [];
         }
     }
+    /**
+     * 曲库数据：优先经 DataPort.readMelodies（ADR 0002「路由只经端口取数据」）。
+     * 端口存在该方法就只认端口：返回 null 由调用方按既有 ok:false 语义兜底，不再回读文件。
+     */
+    async function loadMelodies() {
+        const port = opts.dataPort;
+        if (port && typeof port.readMelodies === 'function') {
+            return await port.readMelodies();
+        }
+        /**
+         * 过渡回退（2026-11-07，B86 数据端口收口）：`DataPort.readMelodies` 是本次新增的
+         * 可选方法。离线单测、旧宿主、以及还没升级装配层的假端口可能没有它；直接删掉
+         * 文件读取会让这些环境的曲库整体消失。端口实现存在时本分支不会执行。
+         *
+         * 移除条件：`readMelodies` 改为必选、且所有装配都注入实现后，删掉本分支、
+         * 以及本文件顶部 `readFile`（node:fs/promises）这个 import。
+         * 注意 `join` 仍被 SEEN_FILE 使用，不能一起删。
+         */
+        return JSON.parse(await readFile(join(opts.dataDir, 'melodies.json'), 'utf8'));
+    }
     // 新格式字段 ← 内部前缀；民间故事写 tales + minsu 两份，让 C# 也能读
     function splitKey(k) {
         const i = k.indexOf(':');
@@ -199,8 +220,10 @@ export function createCultureHandlers(opts) {
     }
     async function handleMelodies(_req, res) {
         try {
-            const txt = await readFile(join(opts.dataDir, 'melodies.json'), 'utf8');
-            const data = JSON.parse(txt);
+            const data = await loadMelodies();
+            // 端口/文件都给不出数据（null）时沿用既有失败语义：ok:false + songs:[]
+            if (data == null)
+                throw new Error('melodies unavailable');
             const songs = (data?.songs || []).map((s) => ({ name: s.name, bpm: s.bpm }));
             sendJson(res, { ok: true, songs });
         }
@@ -212,8 +235,9 @@ export function createCultureHandlers(opts) {
         try {
             const url = new URL(req.url, 'http://x');
             const name = url.searchParams.get('name') || '';
-            const txt = await readFile(join(opts.dataDir, 'melodies.json'), 'utf8');
-            const data = JSON.parse(txt);
+            const data = await loadMelodies();
+            if (data == null)
+                throw new Error('melodies unavailable');
             const song = (data?.songs || []).find((s) => s.name === name);
             if (!song) {
                 sendJson(res, { ok: false, error: 'song not found' });

package/dist/host/routes/poem-titles.js

@@ -8,7 +8,12 @@
  *
  * 为什么单独一条路由：634 个标题约 11 KB，原先内联在 client bundle 里，
  * 改成按需下发后只有真正点诗的人付这份体积。
- * 数据是随包发布的只读文件：读成功后在内存里缓存一份；失败不缓存，补回文件即恢复。
+ *
+ * 取数口径（ADR 0002「路由只经端口取数据」）：
+ *   · 优先 `opts.dataPort.readPoemTitles()`（DataPort 上的可选方法，本地/云端各自实现）。
+ *     端口存在就**只认端口**：返回 null / 空表都按既有 ok:false 兜底，不再回读文件；
+ *   · 只有端口**根本没有该能力**（旧宿主装配 / 离线单测的假端口）时才回退读包内文件，
+ *     原因与移除条件见 loadTitlesFromFile 上方注释。
  */
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -16,31 +21,62 @@ import { sendJson } from '../respond.js';
 export function createPoemTitlesHandler(opts) {
     // 生产装配（index.ts）总会传 DATA_DIR；这里兜底用 cwd/data（与 client seedFromDisk 的查找出发点一致）
     const FILE = join(opts.dataDir || join(process.cwd(), 'data'), 'poem-titles.json');
-    /** 成功读到的标题（只缓存成功结果：文件后来补上时不用重启就能恢复） */
+    /** 成功读到的标题（只缓存成功结果：文件后来补上时不用重启就能恢复）——仅文件回退分支使用 */
     let cached = null;
-    function loadTitles() {
+    /** 过滤空串/非字符串：端口与文件两条路径共用同一口径，响应字段不变 */
+    function pickTitles(list) {
+        const out = [];
+        if (!Array.isArray(list))
+            return out;
+        for (const item of list)
+            if (typeof item === 'string' && item)
+                out.push(item);
+        return out;
+    }
+    /**
+     * 过渡回退：从包内 data/poem-titles.json 读（改造前的唯一取数路径）。
+     *
+     * 为什么还留着：`DataPort.readPoemTitles` 是 2026-11-07（B86 数据端口收口）才加的
+     * 可选方法。离线环境、测试里的最小假端口、以及还没升级装配层的旧宿主都可能没有
+     * 这个方法；若把它当必选，这些宿主会直接拿不到诗名。端口能力存在时本函数**不会被调用**
+     * （见 handlePoemTitles 的 fromPort 判断），所以不影响新装配。
+     *
+     * 移除条件：`DataPort.readPoemTitles` 改为必选、且装配层已注入端口
+     * （index.ts 的 `createPoemTitlesHandler({ dataDir: DATA_DIR, dataPort })`）之后，
+     * 删掉本函数、FILE、cached 以及 node:fs / node:path 两个 import。
+     */
+    function loadTitlesFromFile() {
         if (cached)
             return cached;
         const raw = readFileSync(FILE, 'utf8');
         const data = JSON.parse(String(raw).replace(/^\uFEFF/, ''));
-        const list = Array.isArray(data && data.titles) ? data.titles : [];
-        const titles = [];
-        for (const item of list)
-            if (typeof item === 'string' && item)
-                titles.push(item);
+        const titles = pickTitles(data && data.titles);
         if (titles.length === 0)
             throw new Error('empty titles');
         cached = titles;
         return titles;
     }
     async function handlePoemTitles(_req, res) {
+        // 只看「端口有没有这个方法」：有就只认端口（null 也算端口给出的结论），绝不再碰文件
+        const fromPort = typeof (opts.dataPort && opts.dataPort.readPoemTitles) === 'function';
         try {
-            const titles = loadTitles();
+            let titles;
+            if (fromPort) {
+                // 端口实现承诺不抛（坏 JSON/缺文件 → null）；空表按没数据走既有失败兜底
+                const data = await opts.dataPort.readPoemTitles();
+                titles = pickTitles(data && data.titles);
+                if (titles.length === 0)
+                    throw new Error('empty titles');
+            }
+            else {
+                titles = loadTitlesFromFile();
+            }
             sendJson(res, { ok: true, count: titles.length, titles });
         }
         catch (err) {
             // 读不到就明确报失败：客户端会降级为「不识别具体诗名」，其他意图照常
-            console.error('POEM-TITLES-LOAD-FAIL file=' + FILE + ' err=' + String((err && err.message) || err));
+            const src = fromPort ? ' source=dataPort' : ' file=' + FILE;
+            console.error('POEM-TITLES-LOAD-FAIL' + src + ' err=' + String((err && err.message) || err));
             sendJson(res, { ok: false, titles: [], error: String((err && err.message) || err) });
         }
     }

package/dist/host/routes/story.js

@@ -142,8 +142,9 @@ export function createStoryHandlers(opts) {
         }
         try {
             const url = new URL(req.url, 'http://x');
-            // 先按 content-length 直接拒：readJsonBody 超限时为保证不把大包收进内存会先断连接，
-            // 断早了客户端就只能看到连接重置；这里先回一个能收到的 413，再交给下面的流式读取兜底。
+            // 先按 content-length 直接拒：能省掉白读一个大包（也避免慢客户端长时间占连接）。
+            // 2026-11-07 起 readBody 对「声明超限」不再断连（不读流、直接抛，由 sendTooLarge 的
+            // connection: close 收尾），所以下面那层流式读取是兜底而不是唯一出路。
             const declared = Number(req?.headers?.['content-length']);
             if (Number.isFinite(declared) && declared > RESET_MAX_BODY) {
                 sendTooLarge(res);

package/dist/index.js

@@ -275,7 +275,7 @@ export function apply(ctx, rawConfig) {
     const culture = createCultureHandlers({ dataDir: DATA_DIR, runtimeDir: RUNTIME_DIR, dataPort });
     const poem = createPoemHandler({ runtimeDir: RUNTIME_DIR, dataPort });
     // 诗名索引：客户端点诗识别按需拉取（数据是包内只读文件，读一次后进程内缓存）
-    const poemTitles = createPoemTitlesHandler({ dataDir: DATA_DIR });
+    const poemTitles = createPoemTitlesHandler({ dataDir: DATA_DIR, dataPort });
     const briefing = createBriefingHandlers({
         loadGrowth: store.loadGrowth,
         loadReminders: store.loadReminders,

package/dist/shared/sse.js

@@ -7,9 +7,9 @@
  *
  * 约定：调用方把已收到的字符串拼进 buffer，交给 parseSseBuffer，
  * 返回：
- *   events  —— 这一批完整事件里 data 行解析出的对象（非 JSON / 非 data 行会被跳过）
+ *   events  —— 这一批完整事件里 data 行解析出的**对象**（非 JSON / 非 data 行会被跳过）
  *   rest    —— 还没收完的尾巴，需拼到下一次
- *   invalid —— 解析失败的行数（便于发现上游格式变化，不抛异常）
+ *   invalid —— 解析失败、或解析出来不是对象的行数（便于发现上游格式变化，不抛异常）
  */
 export function parseSseBuffer(buffer) {
     const events = [];
@@ -28,7 +28,14 @@ export function parseSseBuffer(buffer) {
         if (!payload || payload === '[DONE]')
             continue;
         try {
-            events.push(JSON.parse(payload));
+            const v = JSON.parse(payload);
+            // 只收对象：`data: null` / 数字 / 字符串都不是本协议的帧。放进去会让调用方
+            // （client/chat.ts 直接读 obj.error / obj.delta）在 null 上抛 TypeError，
+            // 表现成「流式没接上 → 回退普通 /chat」，白烧一轮模型。这类帧计入 invalid。
+            if (v && typeof v === 'object')
+                events.push(v);
+            else
+                invalid++;
         }
         catch (e) {
             invalid++;

package/docs//345/217/221/345/270/203/350/247/204/350/214/203.md

@@ -12,14 +12,14 @@
 
 | 项 | 值 |
 | --- | --- |
-| `package.json` version | 1.1.58 |
-| `src/client/version.ts` VERSION | 1.1.58（由 `scripts/gen-version.mjs` 生成） |
-| 最近 Gitee tag | `v1.1.58`（提交 `7510365`） |
-| Gitee `main` HEAD | `7510365` |
-| GitHub `main` | `900e7a8`；tag `v1.1.58` → `900e7a8`（API 解包核对 1.1.58） |
-| npm latest | **1.1.58**（2026-11-07 实读；发布返回 202，约 2–4 分钟后可见）。已发布版本：1.1.48 / 1.1.50 / 1.1.51 / 1.1.53 / 1.1.54 / 1.1.56 / 1.1.57 / 1.1.58；1.1.49、1.1.52、1.1.55 仅 Gitee+GitHub（跳档不影响 `latest`） |
+| `package.json` version | 1.1.60 |
+| `src/client/version.ts` VERSION | 1.1.60（由 `scripts/gen-version.mjs` 生成） |
+| 最近 Gitee tag | `v1.1.60`（提交 `96c9ce9`） |
+| Gitee `main` HEAD | `96c9ce9` |
+| GitHub `main` | `f7a4186`；tag `v1.1.60` → `f7a4186`（API 解包核对 1.1.60） |
+| npm latest | **1.1.60**（2026-11-07 实读；发布返回 202，约 2–4 分钟后可见）。已发布版本：1.1.48 / 1.1.50 / 1.1.51 / 1.1.53 / 1.1.54 / 1.1.56 / 1.1.57 / 1.1.58 / 1.1.59 / 1.1.60；1.1.49、1.1.52、1.1.55 仅 Gitee+GitHub（跳档不影响 `latest`） |
 | README 版本 | 无硬编码版本号 |
-| `npm test` | **2723 项**：861 单测 + 59 限额 + 58 流式 + 17 说书安全 + 110 行为回归 + 50 语音契约 + 18 客户端冒烟 + 18 宿主冒烟 + 171 语音队列 + 32 TTS 引擎 + 79 数据层 + 112 仓储 + 83 人格 + 57 说书 + 31 聊天路由 + 33 菜单动作 + 74 说书客户端 + 24 连播开关 + 88 内容路由 + 80 渲染层 + 86 缓存存储 + 37 动作 + 97 杂项路由 + 96 聊天客户端 + 84 配置备份 + 171 媒体提醒 + 59 语音桥 + 32 平台 |
+| `npm test` | **2936 项**（41 个套件，`node tools/test-count.mjs` 核准、失败 0）。口径：每个脚本取自身最后一条汇总行求和，不再手工加总 |
 | `npm pack --dry-run` | **129 个文件 / 17.1 MB**（包）；`data/cache`、运行数据、`config.json`、`src/`、`scripts/`、`tools/` 均不进包 |
 ## 一、版本号规则
 

package/docs//345/235/221.md

@@ -530,4 +530,29 @@ dsh: warning: 1 entry did not activate
 
 **修复**：补 `scripts/test-stream-ledger.mjs`（58 项，含**静态接线断言**：`index.ts` 的装配块必须含四个依赖）+ 负向验证（注释掉 `loadState` 必须红）。
 
-**教训**：修关键路径要同时留**回归测试**，否则下一轮重构会静默改回去。
+**教训**：修关键路径要同时留**回归测试**，否则下一轮重构会静默改回去。
+
+## 坑 47：叙述锁只有一份，谁都能解（诗尾 onDone 解掉说书的锁）
+
+- **现象**：念诗播到一半点「讲段书」，诗那一段播完的 `clearNarrate()` 会把说书刚上的锁清掉——说书段从此没有叙述锁、气泡不更新，麦克风还会在朗读中途开始拾音（把 TTS 当主人说话）。
+- **原因**：`narration.ts` 只有一份 `until`，`clearNarrate` 是无条件清；而念诗/说书/菜单动作三个使用方共用同一对 `narrate/clearNarrate`。TTS 是**串行排队**的，上一段的 onDone 天然晚到。
+- **现在做法**（2026-11-07，B84）：`client.ts` 用 `makeNarrateHandle(label)` 给每个使用方发一个**持有者令牌**（`narrateOwner`）；`clearNarrate()` 先撤自己的探针，**只有仍是自己持有时才清锁**。「停止说话」与叙述锁过期看门狗走**权威清锁** `resetNarration()`（不看持有者，立刻静音）。
+- **还挡不住的**：同一使用方连点两次（连念两首），两次共用一个令牌；彻底修要 per-call token（改 culture/content 的 host 签名）。
+- **诊断**：`__chubbyWhale.narrateOverdue`（计数）与 `narrateOverdueInfo`（`label/estMs/afterMs/lockLeftMs/at`）。只说书长段（估算 >2 分钟、`story.ts` 不挂兜底）会打点：到 `max(30s, 1.5×估算)` 仍是持有者且说书 busy 为 true 时**只报警不放锁**。看到计数涨 = 朗读 onDone 可能丢了，不是锁坏了。
+
+## 坑 48：ASR 既没有单飞也没有纪元
+
+- **现象**：极短时间两段录音会让两个 `/asr` 并发（第二个照发、`uploaded` 计 2）；Stop→start 之后上一轮的识别结果仍被当成本轮的新话送进聊天；P0 打断只停 TTS、不停在途识别；主动 abort 还会被计成「识别失败」。
+- **原因**：`onWindowDone` 可重入，没有在途标志；只有 `if (!running) return`，而 Stop→start 后 `running` 又为 true。
+- **现在做法**（2026-11-07，B83）：`asrBusy` 单飞（**忙则丢，不排队**：识别是「说完马上回话」的交互，排队会让第二句等第一段，断网时队列还会无界）；`asrEpoch` 在 `start()`/`stop()`/`stopSpeaking()` 各 +1，`prepare` 之后、`res.json()` 之后、catch 里都校验，过期一律不送、不写缓存、不改状态；`abortAsrFlight()` 负责早退清理。
+- **取舍要记住**：打断让在途识别作废是规格要求（epoch+1）的必然结果——极端「鱼在说话 + 主人同期开口 + 同时停止说话」时，那句要重说。
+
+## 坑 49：读请求体的「超限」有两种语义，混用会让 413 送不到
+
+- **现象**：上传超限时客户端只看到 `ECONNRESET`（连接被重置），永远收不到 413；前端把它当成网络故障。
+- **原因**（B89 修复前）：`readBody` 一发现超限就 `abortRequest()` → `destroy()` 再抛错。连接被主动断掉，`sendTooLarge()` 写的 413 根本没机会发出去。
+- **现在两种语义（必须分清）**：
+  1. **声明超限**（`content-length` 已超上限）：不读流、**不断连**，直接抛 `BODY_TOO_LARGE`；由调用方回 413（`sendTooLarge` 带 `connection: close` 收尾）。
+  2. **流式超限**（没声明或流比声明大）：先在一个小预算（`DRAIN_GRACE`，1MB）内把剩余体读掉，让响应能写出去；预算外才断连。
+- **给新路由的规矩**：判定超限后**必须**用 `sendTooLarge` 回包（它带 `connection: close`）。若改用普通 `sendJson`，未读完的 body 会留在连接里，keep-alive 复用就会错位（下个请求读到上一个的残体）。
+- **别再加「先按 content-length 预判再拒」的 workaround**：`story.ts` 曾为了绕开这个坑自己加了一层预判，现在读取层已修好，预判只是省流量，不再是必需。

package/docs//345/271/266/345/217/221/347/272/252/345/276/213.md

@@ -73,6 +73,9 @@ TTS 结束 → 再等 700ms（ECHO_MUTE_MS）让混响散掉
 ASR 结果与本鱼最近说过的 6 句做相似度比对 → 命中即判回声丢弃
 ```
 
+   > 2026-11-07 补充（B84）：叙述锁现在**按持有者令牌归属**——`clearNarrate()` 只在仍是自己持有时才清锁，
+   > 旧段 onDone（TTS 串行排队，天然晚到）不会再把新使用方的锁解掉；「停止说话」与过期看门狗走权威清锁。
+   > 想读长段朗读是否卡住：看 `__chubbyWhale.narrateOverdue` / `narrateOverdueInfo`（只报警，不动锁）。
 ## 四、状态机
 
 ```
@@ -105,7 +108,9 @@ ASR 结果与本鱼最近说过的 6 句做相似度比对 → 命中即判回
 
 - **没有真正的任务队列**：P1/P2 用"空闲轮询 + 标志位"实现，不是调度器。极端情况下（连续多次提醒）仍会串行播报，只是不会互相打断。
 - **恢复性打断有代价**：P0 打断说书后，说书的进度停在当前段，需要主人点「接着说」继续。
-- **纪元机制只覆盖对话**：说书进度、提醒、ASR 各自用自己的标志，没有统一事务。
+- **纪元机制覆盖对话与 ASR**（2026-11-07 起）：说书进度、提醒仍各用自己的标志，没有统一事务。
+  对话走 `chatEpoch`，ASR 走 `asrEpoch`（start/stop/stopSpeaking 各 +1，await 后逐个校验）；两者互不覆盖，
+  但都要遵守同一条：**过期结果不许再改任何状态**。
 - 并发问题难用自动化测出来（需要真实麦克风 + 真实网络抖动），本文的规则来自实际故障复盘，**未做压力测试**。
 
 ---

package/docs//345/276/205/351/207/215/345/220/257/347/224/237/346/225/210.md

@@ -300,3 +300,26 @@ Measure-Command { Invoke-RestMethod -Method Post -Uri http://127.0.0.1:3080/api/
 2. 统计卡四项（数据源/模型/TTS/备份）不再是恒定假值；
 3. 朗读中喊「别」能立刻停；换唤醒词后不重开待命也能叫醒；
 4. 说书连播 + 缩放拖拽均正常（缩放不会在拖动后丢失）。
+
+## 十七、2026-11-07 凌晨批次（B78–B88：1.1.59 → 1.1.60）待重启核对
+
+> 覆盖：云端 TTS 真接线、ASR 单飞与纪元、叙述锁持有者、读图超时、数据端口收口。
+> 客户端改动刷新（`Ctrl+F5`）；宿主改动（index/routes/data）需重启 dsh web。
+
+| # | 改动 | 涉及文件 | 为什么 | 怎么验证 |
+|---|------|----------|--------|----------|
+| 1 | 云端 TTS 真的注入 | `src/index.ts`、`host/routes/tts.ts` | `cloudTts` 构造后从未注入，配了 Key 也从没走过云端（三层降级只有两层） | 配了 `cloudVoice.apiKey` 的主人重启后说一句话，日志应出现云端合成而非 edge-tts；失败仍回退 edge-tts |
+| 2 | TTS 常驻 worker 由 `ctx.effect` 回收 | `src/index.ts` | 原来 `dispose()` 传不出来，只能等 5 分钟 idle | 反复禁用/启用插件，`tasklist` 里不应堆积 python 进程 |
+| 3 | ASR 单飞 + 纪元 | `client/voice.ts` | 极短时间两段录音会并发识别；Stop→start 后旧话照送；P0 打断不作废在途识别 | 快速说两句：只应识别一次并回一次；说书时打断再说话，旧话不应被补送 |
+| 4 | 叙述锁持有者令牌 | `client.ts`、`actions/culture.ts` | 诗尾 onDone 会解掉说书的锁（说书段无锁、气泡不更新、麦克风提前拾音） | 念诗播到一半点「讲段书」：说书继续、气泡照更新、麦克风不抢话 |
+| 5 | 念诗 per-call 令牌 | `actions/culture.ts` | 同一使用方连念两首，旧诗的迟到回调会清新诗的锁 | 连点两次「念首诗」：第一首的回调不应打断第二首的进度 |
+| 6 | `sayLine` 改 `ensure()` | `client.ts` | 待命关着刷新后，开场问候/情绪台词只有气泡没声 | 关待命→刷新→触发一句人设台词：应有声音（关「语音朗读」仍全静） |
+| 7 | 读图 30s 超时 | `client/image.ts` | `FileReader` 永不回调时气泡卡在「本鲸看看这张图…」 | 拖一张大图/被占用文件：30s 内应给出失败提示而不是一直转 |
+| 8 | 诗名/曲库走 DataPort | `host/data/*`、`routes/poem-titles.ts`、`culture.ts`、`index.ts` | 两处路由直读 `data/`，违反 ADR 0002；且 `poem-titles` 未注入 `dataPort` | 重启后点「念首诗」「讲个典故」：诗名索引与曲库正常（走端口），不再依赖文件回退 |
+
+### 重启后自检（4 条）
+
+1. 菜单标题栏版本显示 **1.1.60**；
+2. 配了云端语音 Key 时，日志出现云端合成；
+3. 念诗↔说书互不抢锁；待命关刷新后问候仍有声；
+4. 快速连说两句只回一次（ASR 单飞生效）。

package/docs//350/267/250/345/271/263/345/217/260/344/270/216/345/210/206/345/267/245.md

@@ -127,3 +127,10 @@
 | B83 | 2026-11-07 | ASR 并发治理：单飞（忙则丢）+ 纪元（start/stop/stopSpeaking 各 +1，await 后校验）+ 打断作废在途 + 主动作废不计失败；新增 `test-asr-concurrency.mjs`(49) | 双 tsc 0 / verify-voice 50 / voice-queue 171 / 2845 项 0 失败 | 见 git |
 | B84 | 2026-11-07 | 组件入口分身：叙述锁**持有者令牌**（诗尾 onDone 不解说书的锁）/ 说书长段只报警探针（`narrateOverdue`）/ 待命与唤醒文案改真 / `wakeHint` 恒空；新增 `test-entry-narration.mjs`(37) | 双 tsc 0 / 2845 项 0 失败 | 见 git |
 | B85 | 2026-11-07 | `tools/test-count.mjs` 精确统计断言数（逐脚本取最后汇总行），修正人工加总可能的漏项 | 39 套件 / 2845 项 / 失败 0 | 见 git |
+| B86 | 2026-11-07 | 主代理：文档口径（坑 47 叙述锁持有者 / 坑 48 ASR 单飞与纪元；并发纪律「纪元覆盖对话与 ASR」+ `clearNarrate` 只认持有者）；`VoiceStats.asrBusyDropped` 计入丢段 | 2845→2846 项 0 失败 | 4dddf98 / 4373330 |
+| B87 | 2026-11-07 | 数据端口分身：`DataPort` 增可选 `readPoemTitles`/`readMelodies`（本地 mtime 缓存+BOM 容错+拷贝隔离，云端声明即拉/缺失回退）；`poem-titles`/`culture` 端口优先、文件回退仅限方法缺失；`index.ts` 补注入 `dataPort`；`test-data-layer` 端口面 6→8；新增 `test-dataport-poem.mjs`(56) | 双 tsc 0 / 2936 项 0 失败 | 见 git |
+| B88 | 2026-11-07 | 念诗/待命分身：`poemGen` per-call 令牌（旧诗 onDone 不再清新诗的锁）/ `sayLine` 改 `bridge.ensure()`（待命关刷新后问候有声音）/ speak 抛错补 `release()` / 语音清理器不依赖 `earOn`；新增 `test-poem-narration.mjs`(34，含 3 条收尾契约) | 双 tsc 0 / 2936 项 0 失败 | 见 git |
+| B89a | 2026-11-07 | 宿主 HTTP 分身：413 永远送不到（超限先 destroy）/ UTF-8 BOM 变空请求 / 二次写抛 `ERR_HTTP_HEADERS_SENT`；新增 `test-host-http.mjs`(32) | 双 tsc 0 / 3258 项 0 失败 | 见 git |
+| B89b | 2026-11-07 | 客户端网络分身：非对象 SSE 帧进 events（null 让 chat 读 `.error` 抛错白回退一轮）/ 恢复快捷键 keyCode 兜底越权；新增 `test-net-client.mjs`(122+4 变异体) | 双 tsc 0 / 3258 项 0 失败 | 见 git |
+| B89c | 2026-11-07 | 纯函数工具分身：切句器句首标点卡死 / 书名劫持陈述 / 否定句反着做 / 脏 fallback 透传 TTS / `lock(0)` 闭麦 60s 与 expire 界线 / 对仗分类 trim；新增 `test-utils-pure.mjs`(153) | 双 tsc 0 / 3258 项 0 失败 | 见 git |
+| B89d | 2026-11-07 | 主代理：`/chat` 超时补 `TimeoutError`(23) / endpoint 只留 setter 一个写入口 / 多文件拖入先提示「一次一张」+ `test-multidrop.mjs`(10) / 坑 49 两种超限语义 / story 超限注释改真 | 双 tsc 0 / 3258 项 0 失败 | 见 git |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-chubby-whale",
-  "version": "1.1.59",
+  "version": "1.1.61",
   "description": "DSH 网页版桌面宠物「肥鲸」——蓝发鲸鱼娘，固定在 harness 页面右下角：会眨眼、能拖拽、点击可聊天，支持语音对话、念诗说书、饭点提醒。",
   "keywords": [
     "dsh",
@@ -74,7 +74,7 @@
   "scripts": {
     "build": "node scripts/gen-version.mjs && node scripts/check-bom.mjs && tsc -p tsconfig.json && tsc -p tsconfig.client.json && esbuild src/client.ts --bundle --format=iife --external:react --charset=utf8 --outfile=dist/client.js",
     "prepublishOnly": "npm run build",
-    "test": "tsc -p tsconfig.json && tsc -p tsconfig.client.json && node scripts/check-imports.mjs && node scripts/gen-module-index.mjs --check && node scripts/check-boundaries.mjs && node scripts/check-diag-keys.mjs && node scripts/check-text.mjs && node scripts/test.mjs && node scripts/test-chat-limits.mjs && node scripts/test-stream-ledger.mjs && node scripts/test-story-security.mjs && node scripts/test-behavior-regressions.mjs && node scripts/verify-voice.mjs && node scripts/smoke-client.mjs && node scripts/ape-bench.mjs && node scripts/smoke-host.mjs && node scripts/test-voice-queue.mjs && node scripts/test-tts-engine.mjs && node scripts/test-data-layer.mjs && node scripts/test-repos.mjs && node scripts/test-personality.mjs && node scripts/test-story-player.mjs && node scripts/test-chat-routes.mjs && node scripts/test-menu-actions.mjs && node scripts/test-story-client.mjs && node scripts/test-story-auto.mjs && node scripts/test-content-routes.mjs && node scripts/test-render-layer.mjs && node scripts/test-store-cache.mjs && node scripts/test-actions-rest.mjs && node scripts/test-misc-routes.mjs && node scripts/test-chat-client.mjs && node scripts/test-prefs-config.mjs && node scripts/test-media-reminders.mjs && node scripts/test-image-reader.mjs && node scripts/test-boundaries-guard.mjs && node scripts/test-assembly.mjs && node scripts/test-asr-concurrency.mjs && node scripts/test-entry-narration.mjs && node scripts/test-voice-bridge.mjs && node scripts/platform-check.mjs",
+    "test": "tsc -p tsconfig.json && tsc -p tsconfig.client.json && node scripts/check-imports.mjs && node scripts/gen-module-index.mjs --check && node scripts/check-boundaries.mjs && node scripts/check-diag-keys.mjs && node scripts/check-text.mjs && node scripts/test.mjs && node scripts/test-chat-limits.mjs && node scripts/test-stream-ledger.mjs && node scripts/test-story-security.mjs && node scripts/test-behavior-regressions.mjs && node scripts/verify-voice.mjs && node scripts/smoke-client.mjs && node scripts/ape-bench.mjs && node scripts/smoke-host.mjs && node scripts/test-voice-queue.mjs && node scripts/test-tts-engine.mjs && node scripts/test-data-layer.mjs && node scripts/test-repos.mjs && node scripts/test-personality.mjs && node scripts/test-story-player.mjs && node scripts/test-chat-routes.mjs && node scripts/test-menu-actions.mjs && node scripts/test-story-client.mjs && node scripts/test-story-auto.mjs && node scripts/test-content-routes.mjs && node scripts/test-dataport-poem.mjs && node scripts/test-render-layer.mjs && node scripts/test-store-cache.mjs && node scripts/test-actions-rest.mjs && node scripts/test-misc-routes.mjs && node scripts/test-chat-client.mjs && node scripts/test-prefs-config.mjs && node scripts/test-media-reminders.mjs && node scripts/test-image-reader.mjs && node scripts/test-boundaries-guard.mjs && node scripts/test-assembly.mjs && node scripts/test-asr-concurrency.mjs && node scripts/test-host-http.mjs && node scripts/test-entry-narration.mjs && node scripts/test-poem-narration.mjs && node scripts/test-multidrop.mjs && node scripts/test-utils-pure.mjs && node scripts/test-net-client.mjs && node scripts/test-voice-bridge.mjs && node scripts/platform-check.mjs",
     "version:check": "node tools/version-check.mjs",
     "typecheck": "node scripts/gen-version.mjs && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
     "smoke:client": "node scripts/smoke-client.mjs",