@memef1f1y/dsh-plugin-tts 0.6.4 → 0.6.7

package/TODO.md

@@ -1,23 +1,34 @@
-# TODO（待办）
-
-## 发布与引流
-
-- [x] **B站介绍视频已发布**，简介已放便携运行时网盘链接（`E:\rvc-portable-torch2.7-cu128.zip`，4.35GB）。
-- [x] 便携运行时 zip 已上传个人网盘。
-- [x] B站视频链接已填入 `docs/USER-GUIDE.md` §10（https://www.bilibili.com/video/BV1ukbQ6qECo/）。
-- [x] macOS 实测：已在 Apple Silicon macOS 26 上完整跑通（`npm run test:all` 全绿），
-      修复了 mac-verify.sh 的 od 空格 bug、darwin PyAV 补丁、rvc-server 边界 500→400，
-      并新增 live/边界 标准测试（见 `tests/` 与 `tests/README.md`）。
-- [x] 中英文国际化：设置面板/气泡/诊断/音色包/RVC 报错全部 zh/en，含语言切换与持久化
-      （见 `lib/client.js` 的 i18n 层 + `tests/i18n-keys.mjs`、`tests/client-load.mjs`）。
-- [x] CI：`.github/workflows/test.yml` 已加（Node 22/24，跑 smoke/i18n/client-load/patch；
-      注：Edge TTS worker 依赖原生 `WebSocket`，需 Node ≥ 22，故矩阵不含 20）。
-
-## 后续功能（按需启动）
-
-- [ ] 校准文件（calibration.json）多机同步/备份。
-- [ ] 多个音色包仓库并存（设置里保存多个仓库地址）。
-- [ ] 试听 A/B（UI 内对比两个音色包输出）。
-- [ ] 便携运行时 Linux 实测（macOS 用 `docs/macos-test-prompt.md` 同款流程）。
-- [x] ~~Edge TTS 一键诊断~~（设置面板「诊断」，已上线）。
-- [x] ~~便携运行时跨平台脚本泛化~~（`tools/package-runtime.py --platform`，代码已交付，待实测）。
+# TODO（待办）
+
+## 2026-09-27 Mac 交接前进度（已 push，工作区干净）
+
+- [x] 五提供者指南：Edge / Index-TTS2 / CosyVoice / Cloud TTS / RVC per-provider guides + agent handoff header（`docs/`，2026-09-22）。
+- [x] 分块播放：indexed chunk serve order、prewarm skip、starved chunk clamp、orphan sweep + overlap detector、fluency trio（cosy trim / chunk retry-skip / stall watchdog，2026-09-22）。
+- [x] 诊断：diag log JSON 导出 + triage（calibration / cache / model / jobs）+ per-provider triage + chunk forensics（host build tag / job summaries / early-done，2026-09-25）。
+- [x] 发布：npm `@memef1f1y/dsh-plugin-tts`，v0.6.1 chunk-order、v0.6.2 loader-name、v0.6.3 scroll-follow v2（2026-09-25~26）。
+- [x] scroll-follow v2：stepwise signal + latch-off + highlight + spans；`ttsFollow` 提至 apply scope + ratio fallback 修复（HEAD `149fb9d`，v0.6.4，2026-09-26，已 push，`origin/main` 同步，工作区干净）。
+- [ ] 待 Mac 端：`docs/scroll-follow-v2.md` 在 UTF-8 下读出乱码（疑似 GBK 存档），需确认源编码并转 UTF-8；`TODO.md` 此前停留在 08-17，本次已补齐。
+
+> 交接注意：`dsh-plugin-TTS/` 外层（`edge-tts-worker.cjs` 旧独立 worker、`README.md` 旧版、6 个 `rvc-*.log`、`.npm-cache/`）不在 git 内，Mac 端只需 clone `plugin/` 本体（`https://github.com/1624318455/dsh-plugin-tts.git`，`main@149fb9d`）；外层文件无需带走，log 已被 `plugin/.gitignore` 的 `*.log` 排除。
+
+## 发布与引流
+
+- [x] **B站介绍视频已发布**，简介已放便携运行时网盘链接（`E:\rvc-portable-torch2.7-cu128.zip`，4.35GB）。
+- [x] 便携运行时 zip 已上传个人网盘。
+- [x] B站视频链接已填入 `docs/USER-GUIDE.md` §10（https://www.bilibili.com/video/BV1ukbQ6qECo/）。
+- [x] macOS 实测：已在 Apple Silicon macOS 26 上完整跑通（`npm run test:all` 全绿），
+      修复了 mac-verify.sh 的 od 空格 bug、darwin PyAV 补丁、rvc-server 边界 500→400，
+      并新增 live/边界 标准测试（见 `tests/` 与 `tests/README.md`）。
+- [x] 中英文国际化：设置面板/气泡/诊断/音色包/RVC 报错全部 zh/en，含语言切换与持久化
+      （见 `lib/client.js` 的 i18n 层 + `tests/i18n-keys.mjs`、`tests/client-load.mjs`）。
+- [x] CI：`.github/workflows/test.yml` 已加（Node 22/24，跑 smoke/i18n/client-load/patch；
+      注：Edge TTS worker 依赖原生 `WebSocket`，需 Node ≥ 22，故矩阵不含 20）。
+
+## 后续功能（按需启动）
+
+- [ ] 校准文件（calibration.json）多机同步/备份。
+- [ ] 多个音色包仓库并存（设置里保存多个仓库地址）。
+- [ ] 试听 A/B（UI 内对比两个音色包输出）。
+- [ ] 便携运行时 Linux 实测（macOS 用 `docs/macos-test-prompt.md` 同款流程）。
+- [x] ~~Edge TTS 一键诊断~~（设置面板「诊断」，已上线）。
+- [x] ~~便携运行时跨平台脚本泛化~~（`tools/package-runtime.py --platform`，代码已交付，待实测）。

package/docs/HOST-CONTRACT.md

@@ -1,36 +1,36 @@
-# DSH 宿主插槽契约（实测记录）
-
-> 本文件是 2026-09 用控制台日志反推出的真实契约，不是官方文档。
-> 宿主升级后可能漂移——插件代码已按“多形态兼容 + DOM 兜底”来写，
-> 漂移时看控制台 `[tts]` 日志即可重新定位（方法见末尾）。
-
-## 1. 涉及的插槽与 props
-
-| 插槽 | props（含标准钩子） |
-|---|---|
-| `conversation.chat.assistant-actions`（单条朗读按钮） | `inputActions, messageId, sessionId, useChat, useConversation, useInput, usePanelInfo, useProjection, useResource, useSession, useSessionPendingInteraction, useSessions, useTrajectory, useWorkspaces` |
-| `conversation.input.left`（自动朗读开关） | 同上（无 `messageId`） |
-
-`messageId` 与下述 `eventNodes[].messageId` 精确对应，是按钮定位正文的主键。
-
-## 2. 快照形状（`hook(s => s)` 所见）
-
-- **`useSession`**：`{sessionId, queue, pendingSubmissions, running, subagent, removed, openState, openError, hasMore, loadingOlder, promptError, blank}`——**只有队列/运行状态，没有消息**。切勿用它找正文。
-- **`useTrajectory`**：`{eventNodes, eventLocations, requests, callSchemas, partial, runningCalls}`——**正文主数据源**。`eventNodes[]` 形如 `{kind, seq, messageId, time, turn, step, blocks, usage, …}`，`kind` 区分 `assistant/user`，AI 正文在 `blocks: [{kind: "text", text}]`，`seq` 单调递增。`partial` 非空表示正在流式。
-- **`useChat`**：`{order: string[]（id 顺序）, nodes: 内部 store（`byKey` 实测为空）, locations, navigation, timeline{turnOrder, turns}, legacy{nodes（与 eventNodes 同源的数组镜像）}}`——备用链路。
-- **`useConversation`**：`{views: {eventDefinitions, viewDefinitions, contexts, contextsByKind, contextsBySeq, contextsByTarget, inputs, locationIndex, …}, activeTargets}`——视图元数据，不是消息。
-- **`useProjection`**：实测返回空。
-- **`useResource`**：`{status, value, failure}`。
-
-## 3. 客户端据此实现的规则（`lib/client.js`）
-
-- 按钮：`messageId` 跨所有快照按 id 找 → `blocks` 正文 → 找不到走 DOM 逐层上爬（首个 ≥20 字祖先即气泡）；按钮永不 `disabled`，真没文本弹 toast。
-- 自动朗读：只看 `useTrajectory.eventNodes`（优先）等内容源的新增；**切会话静默重建基线；一次新增 >3 条按历史同步静默跟进；朗读必须过活体闩**（本页面生命周期内见过 `running/queue/pending/partial`，或用户侧增长已陈化 ≥2 秒）——三者缺一即历史，必须安静。
-- 空会话基线记为 -1，保证新会话首条回复正常朗读。
-
-## 4. 契约漂移时的取证方法
-
-1. 确认构建号：控制台应有 `[tts] client build <tag> loaded`（没有 = 跑的是旧包，先硬刷新/重启 `dsh web`）。
-2. 挂载形状：`[tts] slot: <插槽> props: …` 行列出各钩子的数据形状（只含键名/数量/首节点正文长度，不含正文）。
-3. 自动朗读判决：每次触发会打 `[tts] auto-read speak key=… fresh=… src=… seq=…`，`src` 即放行的 feeder。
-4. 一键打包：控制台运行 `copy(JSON.stringify(__dshTtsDebug.dump()))`，把剪贴板内容贴到 issue。
+# DSH 宿主插槽契约（实测记录）
+
+> 本文件是 2026-09 用控制台日志反推出的真实契约，不是官方文档。
+> 宿主升级后可能漂移——插件代码已按“多形态兼容 + DOM 兜底”来写，
+> 漂移时看控制台 `[tts]` 日志即可重新定位（方法见末尾）。
+
+## 1. 涉及的插槽与 props
+
+| 插槽 | props（含标准钩子） |
+|---|---|
+| `conversation.chat.assistant-actions`（单条朗读按钮） | `inputActions, messageId, sessionId, useChat, useConversation, useInput, usePanelInfo, useProjection, useResource, useSession, useSessionPendingInteraction, useSessions, useTrajectory, useWorkspaces` |
+| `conversation.input.left`（自动朗读开关） | 同上（无 `messageId`） |
+
+`messageId` 与下述 `eventNodes[].messageId` 精确对应，是按钮定位正文的主键。
+
+## 2. 快照形状（`hook(s => s)` 所见）
+
+- **`useSession`**：`{sessionId, queue, pendingSubmissions, running, subagent, removed, openState, openError, hasMore, loadingOlder, promptError, blank}`——**只有队列/运行状态，没有消息**。切勿用它找正文。
+- **`useTrajectory`**：`{eventNodes, eventLocations, requests, callSchemas, partial, runningCalls}`——**正文主数据源**。`eventNodes[]` 形如 `{kind, seq, messageId, time, turn, step, blocks, usage, …}`，`kind` 区分 `assistant/user`，AI 正文在 `blocks: [{kind: "text", text}]`，`seq` 单调递增。`partial` 非空表示正在流式。
+- **`useChat`**：`{order: string[]（id 顺序）, nodes: 内部 store（`byKey` 实测为空）, locations, navigation, timeline{turnOrder, turns}, legacy{nodes（与 eventNodes 同源的数组镜像）}}`——备用链路。
+- **`useConversation`**：`{views: {eventDefinitions, viewDefinitions, contexts, contextsByKind, contextsBySeq, contextsByTarget, inputs, locationIndex, …}, activeTargets}`——视图元数据，不是消息。
+- **`useProjection`**：实测返回空。
+- **`useResource`**：`{status, value, failure}`。
+
+## 3. 客户端据此实现的规则（`lib/client.js`）
+
+- 按钮：`messageId` 跨所有快照按 id 找 → `blocks` 正文 → 找不到走 DOM 逐层上爬（首个 ≥20 字祖先即气泡）；按钮永不 `disabled`，真没文本弹 toast。
+- 自动朗读：只看 `useTrajectory.eventNodes`（优先）等内容源的新增；**切会话静默重建基线；一次新增 >3 条按历史同步静默跟进；朗读必须过活体闩**（本页面生命周期内见过 `running/queue/pending/partial`，或用户侧增长已陈化 ≥2 秒）——三者缺一即历史，必须安静。
+- 空会话基线记为 -1，保证新会话首条回复正常朗读。
+
+## 4. 契约漂移时的取证方法
+
+1. 确认构建号：控制台应有 `[tts] client build <tag> loaded`（没有 = 跑的是旧包，先硬刷新/重启 `dsh web`）。
+2. 挂载形状：`[tts] slot: <插槽> props: …` 行列出各钩子的数据形状（只含键名/数量/首节点正文长度，不含正文）。
+3. 自动朗读判决：每次触发会打 `[tts] auto-read speak key=… fresh=… src=… seq=…`，`src` 即放行的 feeder。
+4. 一键打包：控制台运行 `copy(JSON.stringify(__dshTtsDebug.dump()))`，把剪贴板内容贴到 issue。