dsh-speak 1.7.4 → 1.8.0

package/README.md

@@ -91,6 +91,18 @@ macOS:
 - Chinese voices: see the [macOS](#macos) section (incl. the Siri natural-voice
   picker and its pitfalls).
 
+DSH web app:
+
+- Tested against **DSH 0.1.5-rc.1**. Two host/client APIs changed after 0.1.1, both
+  handled here (1.8.0):
+  - `@deepseek-ai/dsh-settings` deleted the `installSettingsSection` /
+    `settingsNamespace` helpers — the plugin now registers its namespace through
+    the `settings` **service**. On those older releases the plugin aborted the
+    host boot (`settingsNamespace is not a function`); a missing settings provider
+    now just leaves the composed patch `config` in force.
+  - the Session snapshot stopped carrying Conversation target data — the 🔊 button
+    resolves the clicked message through the Chat target hook `useChat`.
+
 ## Install & quick start
 
 ### DSH — Option A: npm plugin (recommended)
@@ -324,7 +336,7 @@ document):
 | `announceTurnEnd` | `false` | announce "第 N 轮对话完成/中断/异常结束" on turn end (`turn/end`) |
 | `announceCommandDone` | `false` | announce when a command finishes or fails (`command/done`) |
 | `announceGoalChange` | `false` | announce goal created/updated/completed/paused/resumed (`goal/change`, objective head) |
-| `announceToolErrors` | `false` | announce "工具调用出错" when a tool call returns an error (`tool/result` with `error` or an `isError` content block; English details / technical codes dropped, Chinese details kept) |
+| `announceToolErrors` | `false` | announce "工具调用出错" when a tool call returns an error: `tool/result` carrying `error` (structured failure identity) or a result block with `isError === true`. A **non-zero shell exit does NOT count** — pwsh/bash report `exit code: N` as result data by design, so only infrastructure failures (spawn errors, aborts) and structured tool failures (e.g. fs) set `isError` (English details / technical codes dropped, Chinese details kept) |
 | `announceTodoWrite` | `false` | announce "待办已更新：n/m 完成" when the agent updates its todos (`todo/write`) |
 
 #### Long-text modes
@@ -334,9 +346,17 @@ When cleaned text exceeds `maxChars`:
 - **`message`** (default): speak `longTextMessage` (`本次播报内容较长，请自行阅读。`,
   editable in the UI or YAML).
 - **`heading`**: pick the *largest* markdown heading in the raw text — fewest `#`
-  wins, tie → first; if there is no heading line, the first non-empty line is used.
-  The chosen candidate is still cleaned and subject to the `maxChars` ceiling,
-  falling back to the message if it is itself too long.
+  wins, tie → first. When there is **no heading at all**, speak a coherent opening
+  instead of just the first line: the leading `maxChars` window, trimmed back to
+  its last sentence end, and kept whole when that would drop more than half the
+  window. Sentence ends are recognised bilingually: full-width `。！？；` and `…`
+  always count, while half-width `.!?;` only count when followed by whitespace, a
+  closing quote/bracket, or (for the very last character) one read past the window —
+  so an English `period + space` at the edge still lands, but a decimal point such
+  as `Version 0.1.` does not. (Before 1.8.0 this fallback spoke the first non-empty
+  line only, which sounded like the narration stopped after line 1.) The chosen
+  candidate is still cleaned and subject to the `maxChars` ceiling, falling back to
+  the message if it is itself too long.
 
 Full architecture and design rationale: [docs/DESIGN.md](docs/DESIGN.md).
 
@@ -356,6 +376,16 @@ You can tune behavior without forking, and your changes **survive `npm update`**
 
    Then point the plugin at your copy in the `config` block:
 
+   > **Windows: keep the file's UTF-8 BOM.** `speak.ps1` is a UTF-8 script and Windows
+   > PowerShell 5.1 only knows that from the 3-byte BOM (`EF BB BF`) at the start; an
+   > editor that saves it without one makes the system ANSI code page decode it instead,
+   > and Chinese text inside the script turns to mojibake — the symptom is **silence or
+   > wrong trimming, with no error**. The shipped script keeps all of its *logic* ASCII-only
+   > for that reason, so a lost BOM only garbles the Chinese comments and the default
+   > prompt. After editing, check with
+   > `Get-Content -Encoding Byte -TotalCount 3 your-speak.ps1` (expect `239 187 191`), or
+   > run `node scripts/test-engine-static.js`.
+
    ```yaml
    - insert:
        - id: speech-hook
@@ -377,6 +407,8 @@ You can tune behavior without forking, and your changes **survive `npm update`**
 | ------- | ----- | --- |
 | No sound at all, no error | no natural voice enabled/installed | Win11: enable a natural voice in *Settings → Narrator / Speech*; Win10: install NaturalVoiceSAPIAdapter + a voice pack. Test `speak.ps1` directly |
 | Long replies never spoken | adapter per-`Speak` character ceiling | already guarded at 300 chars — lower `-MaxChars` if needed |
+| Narration stops after the first line | with `longTextMode: heading`, text over `maxChars` and no markdown heading made the engine speak only the first non-empty line (pre-1.8.0) | fixed in 1.8.0 (speaks a coherent opening instead); to change the policy use `message` mode or raise `maxChars` |
+| `工具调用出错：Error: cannot read …` spoken | the "is this Chinese?" detail filter only checked for the presence of a CJK character, so a Chinese directory name inside an English error passed it (1.8.0 regression) | fixed in 1.8.0 — the detail now needs more Chinese characters than Latin letters |
 | Emoji-heavy text silent | SAPI fails silently on emoji | already stripped by the engine |
 | Plugin not loading | raw Windows path as plugin name | use the `file:///C:/…` URL form (installer does this) |
 | macOS: voice suddenly became "婷婷" | opening the "Spoken Content / Siri Voice" pane drifted the system voice | re-pick via Settings → Accessibility → Spoken Content → System Voice → ⓘ entry |
@@ -401,6 +433,15 @@ client/
   client.js              DSH browser bundle: turn-tail Speak/Stop button + Settings → dsh-speak settings page
 docs/
   DESIGN.md              full design rationale, pitfalls, extension guide
+scripts/                 tests + manual dev helpers (not shipped in the npm package)
+  test-engine-static.js    engine invariants: .ps1 BOM + PowerShell parse, .sh LF (also run by prepublishOnly)
+  test-engine-longtext.js  long-text guard contract for BOTH engines (speak.ps1 -DryRun / speak.sh's perl)
+  test-speech-hook.js      host plugin: event triggers, queue, tool-error detail filter
+  test-client-bundle.js    browser bundle: slot registration + component rendering
+  test-settings-integration.js  settings-service wiring + removed-API guard
+  session-log-dump.js      read a DSH session log (manual: what text reached the engine)
+  settings-ui-check.py     Playwright UI check (manual: needs a running, authenticated dsh)
+  dsh-events-check.py      Playwright disclosure check (manual)
 ```
 
 ## Writing a new adapter

package/README.zh-CN.md

@@ -80,6 +80,18 @@ harness 事件（DSH 会话事件 / Claude Code Stop hook / 任意方式）
 - macOS（Apple Silicon / Intel 均可），系统自带 `say` 命令，**无需安装任何软件**。
 - 中文音色与 Siri 音色的选择入口/坑见 [macOS](#macos) 一节。
 
+### DSH 版本
+
+- 已在 **DSH 0.1.5-rc.1** 上验证。0.1.1 之后有两处 host/客户端 API 变更，本插件
+  1.8.0 均已适配：
+  - `@deepseek-ai/dsh-settings` 删除了 `installSettingsSection` /
+    `settingsNamespace` 两个辅助导出——插件改为通过 `settings` **服务**注册
+    namespace（旧版本上原实现会让宿主启动直接崩掉：
+    `settingsNamespace is not a function`）。没有 settings provider 时，插件照旧
+    按 patch `config` 工作。
+  - Session snapshot 不再携带会话视图（Conversation target）数据——🔊 按钮改为
+    通过 Chat 目标的 hook `useChat` 取被点击消息的文本。
+
 ## 安装与快速开始
 
 ### DSH — 方式 A：npm 插件（推荐）
@@ -303,7 +315,7 @@ speak.ps1 -Text "…" -Volume 50 -Rate 1 -MaxChars 300 -LongTextMessage "本次
 | `announceTurnEnd` | `false` | 回合结束时播报"第 N 轮对话完成/中断/异常结束"（`turn/end`） |
 | `announceCommandDone` | `false` | 命令执行完成/失败时播报（`command/done`） |
 | `announceGoalChange` | `false` | 目标创建/更新/完成/暂停/恢复时播报（`goal/change`，含目标标题前 40 字） |
-| `announceToolErrors` | `false` | 工具调用返回错误时播报"工具调用出错"（英文错误详情/技术 code 截掉，只保留中文详情；`tool/result` 带 `error` 或 `isError` 内容块时） |
+| `announceToolErrors` | `false` | 工具调用返回错误时播报"工具调用出错"（英文错误详情/技术 code 截掉，只保留中文详情）。触发条件：`tool/result` 带 `error`（结构化失败身份）或结果块 `isError === true`。注意 **shell 命令非零退出不算**——pwsh/bash 把 `exit code: N` 当结果数据上报（dsh 明文如此设计），只有基础设施失败（spawn 错误、abort）和 fs 这类结构化失败才置 `isError` |
 | `announceTodoWrite` | `false` | agent 更新待办列表时播报"待办已更新：n/m 完成"（`todo/write`） |
 
 #### 超长文本模式
@@ -313,7 +325,12 @@ speak.ps1 -Text "…" -Volume 50 -Rate 1 -MaxChars 300 -LongTextMessage "本次
 - **`message`**（默认）：念 `longTextMessage`（`本次播报内容较长，请自行阅读。`，
   可在 UI 或 YAML 里编辑）。
 - **`heading`**：在原始文本里挑**最大字号**的 markdown 标题——`#` 数量最少者优先，
-  并列取第一个；没有标题行则取第一个非空行。选中的候选仍会清洗并受 `maxChars`
+  并列取第一个。**整段没有任何标题时**改念"有头有尾的开头"：取开头 `maxChars`
+  长度的窗口并回退到窗口内最后一个句末标点；若这样会砍掉半个窗口以上则保留整窗。
+  句末标点中英双语识别：全角 `。！？；` 与 `…` 无条件算；半角 `.!?;` 只在后面跟
+  空白、右引号/右括号时才算，落在窗口最后一位时会**多读一位**判断——所以英文
+  「句号+空格」在边缘照样算，而 `Version 0.1.` 这种小数点不算。（1.8.0 之前这里只念
+  第一个非空行，听感上就是"从第二行开始不念了"。）选中的候选仍会清洗并受 `maxChars`
   上限约束，若其本身仍超长则回退提示语。
 
 完整架构与设计取舍见 [docs/DESIGN.zh-CN.md](docs/DESIGN.zh-CN.md)。
@@ -333,6 +350,14 @@ speak.ps1 -Text "…" -Volume 50 -Rate 1 -MaxChars 300 -LongTextMessage "本次
 
    然后在 config 块里指向你的副本：
 
+   > **Windows：务必保住文件的 UTF-8 BOM。** `speak.ps1` 是 UTF-8 脚本，而 Windows
+   > PowerShell 5.1 只能靠开头那三个字节 `EF BB BF` 知道这一点；编辑器保存时若把它
+   > 丢掉，系统会改用 ANSI 代码页解码，脚本里的中文会变乱码——症状是**静默无声或
+   > 修剪错乱，且不报错**。为此仓库里的脚本已把**逻辑部分全部写成纯 ASCII**，所以
+   > 丢 BOM 只会让中文注释和默认提示语变乱码。改完可以用
+   > `Get-Content -Encoding Byte -TotalCount 3 你的-speak.ps1` 检查（应为 `239 187 191`），
+   > 或跑 `node scripts/test-engine-static.js`。
+
    ```yaml
    - insert:
        - id: speech-hook
@@ -354,6 +379,8 @@ speak.ps1 -Text "…" -Volume 50 -Rate 1 -MaxChars 300 -LongTextMessage "本次
 | ---- | ---- | ---- |
 | 完全没有声音、无报错 | 未启用/安装自然语音 | Win11：在 设置 → 讲述人/语音 中启用自然语音；Win10：安装 NaturalVoiceSAPIAdapter 并下载语音包。直接测 `speak.ps1` |
 | 长回复从不播报 | 适配器单次 `Speak` 有字数上限 | 已默认在 300 字处守卫——必要时调低 `-MaxChars` |
+| 念到第二行就停/像是被切断 | `longTextMode: heading` 下，文本超过 `maxChars` 且整段没有 markdown 标题时，旧版引擎只念第一个非空行（1.8.0 之前） | 1.8.0 已修（改念"有头有尾的开头"）；想换策略可用 `message` 模式或调高 `maxChars` |
+| 听到 `工具调用出错：Error: cannot read …` | "是否中文"的详情判据只检查"含有汉字"，英文报错里夹着中文目录名就能骗过它（1.8.0 引入的回归） | 1.8.0 已修——详情需满足"汉字数量多于拉丁字母数量" |
 | 含大量 emoji 的文本静默 | SAPI 遇到 emoji 会静默失败 | 引擎已自动剥离 |
 | 插件加载失败 | 插件名用了 Windows 原始路径 | 改用 `file:///C:/…` URL 形式（安装脚本会自动处理） |
 | macOS：音色突然变成"婷婷" | 打开过"朗读内容 / Siri 声音"设置面板导致系统朗读声音漂移 | 系统设置 → 辅助功能 → 阅读与朗读 → 系统声音 → ⓘ 入口重新选择 |
@@ -378,6 +405,15 @@ client/
   client.js              DSH 浏览器端 bundle：回合尾部 Speak/Stop 按钮 + 设置 → dsh-speak 设置页
 docs/
   DESIGN.zh-CN.md        完整设计文档：设计取舍、踩坑记录、扩展指南
+scripts/                 测试 + 手动开发辅助脚本（不随 npm 包发布）
+  test-engine-static.js    引擎静态不变量：.ps1 的 BOM + PowerShell 语法解析、.sh 的 LF（prepublishOnly 也会跑）
+  test-engine-longtext.js  两个引擎的长文守卫契约（speak.ps1 -DryRun / speak.sh 的 perl）
+  test-speech-hook.js      宿主插件：事件触发、队列、工具出错详情过滤
+  test-client-bundle.js    浏览器 bundle：slot 注册 + 组件渲染
+  test-settings-integration.js  settings 服务接线 + 已删除 API 的回归守卫
+  session-log-dump.js      读取 DSH 会话日志（手动：看引擎究竟收到了什么文本）
+  settings-ui-check.py     Playwright UI 检查（手动：需要运行中且已鉴权的 dsh）
+  dsh-events-check.py      Playwright 折叠行检查（手动）
 ```
 
 ## 编写新适配器

package/adapters/dsh/speech-hook.js

@@ -19,8 +19,9 @@
 //       - on: every assistant/message is enqueued immediately as it arrives
 //   * a `/dsh-speak/control` POST route (play/stop/status) and a
 //     `/dsh-speak/ws` WebSocket publish the authoritative speech state
-//   * a `dsh-speak` settings namespace via installSettingsSection; schema
-//     defaults → patch config → UI user layer
+//   * a `dsh-speak` settings namespace registered through the settings SERVICE
+//     (`ctx.inject(['settings'])` → `settings.register`); schema defaults →
+//     patch config → UI user layer
 //   * `enabled` master switch: when off, nothing is ever enqueued (no sound)
 //
 // Trigger semantics:
@@ -72,7 +73,7 @@ function resolveEngine(override) {
 const DEFAULT_MAX_CHARS = process.platform === 'darwin' ? 0 : 300
 
 // ---------------------------------------------------------------------------
-// Settings namespace (best-effort; see installSettingsSection in dsh-settings)
+// Settings namespace (best-effort; registered through the `settings` service)
 // ---------------------------------------------------------------------------
 // The schema mirrors every config key. Values resolve as:
 // schema default → patch `config` (base) → user settings layer (the UI).
@@ -141,14 +142,29 @@ function resolveConfig(value) {
 }
 
 /**
- * Build the settings schema + entry for installSettingsSection. Best-effort:
+ * Resolve a module specifier from the plugin's own location first, then from
+ * the booted profile tree. `@deepseek-ai/schemastery` is a peer of this package
+ * and lives beside it after an npm/pnpm install; the profile-tree fallback
+ * covers the file:// install used by install.ps1 and repo checkouts.
+ * @returns the module, or null when neither base resolves it.
+ */
+function requirePeer(ctx, spec) {
+  const bases = [__filename, ctx.baseUrl].filter(Boolean)
+  for (const base of bases) {
+    try { return createRequire(base)(spec) } catch (e) { /* try the next base */ }
+  }
+  return null
+}
+
+/**
+ * Build the settings schema + entry for the settings namespace. Best-effort:
  * any failure (missing peer packages) returns null and the plugin keeps the
- * patch config. The registration itself happens on a timer tick in apply.
+ * patch config.
  */
 function buildSettingsNamespace(ctx, patch) {
   try {
-    const profileRequire = createRequire(ctx.baseUrl || __filename)
-    const z = profileRequire('@deepseek-ai/schemastery')
+    const z = requirePeer(ctx, '@deepseek-ai/schemastery')
+    if (!z) throw new Error('@deepseek-ai/schemastery 不可解析')
     const schema = z.object({
       enabled: z.boolean().default(true),
       automaticSpeech: z.boolean().default(true),
@@ -188,33 +204,49 @@ module.exports = {
     config = config || {}
     let cfg = resolveConfig(config)
 
-    // Register the settings namespace on a timer tick so apply never blocks;
-    // cfg is replaced wholesale on settings changes.
-    ctx.inject(['timer'], timerCtx => {
-      timerCtx.timer.timeout(() => {
-        const prepared = buildSettingsNamespace(ctx, config)
-        if (!prepared) return
-        let settingsModule
+    // ---- settings namespace -------------------------------------------------
+    // Wire the namespace through the settings SERVICE.
+    //
+    // dsh 0.1.2-alpha.1 deleted the `installSettingsSection` / `settingsNamespace`
+    // convenience exports from `@deepseek-ai/dsh-settings`; what remains — and
+    // has not changed since 0.1.0-rc.7 — is the `settings` service itself
+    // (`ctx.settings.register(ns, schema, { base })` → `{ get, watch, update,
+    // replace }`). Referencing the removed names is fatal: an ESM named import
+    // of a deleted export is a module-evaluation SyntaxError that kills the host
+    // boot, and a lazy `settingsModule.installSettingsSection(...)` call — what
+    // this plugin used to do inside a timer callback — throws
+    // `settingsNamespace is not a function` and crashed dsh before it served.
+    //
+    // `ctx.inject(['settings'])` is the graceful-degradation boundary: on a host
+    // with no settings provider the callback never runs and the composed patch
+    // config stands as-is.
+    const prepared = buildSettingsNamespace(ctx, config)
+    if (prepared) {
+      ctx.inject(['settings'], scopedCtx => {
+        // `scope.get()` is the live resolved value (schema default → patch
+        // config → UI user layer), so re-deriving cfg from it on every change
+        // is what makes a settings edit take effect without a restart.
+        let settingsSource = () => prepared.entry
+        const applySettings = () => {
+          try { cfg = resolveConfig(settingsSource()) } catch (e) { log('settings 变更应用失败:', e && e.message) }
+        }
         try {
-          const profileRequire = createRequire(ctx.baseUrl || __filename)
-          settingsModule = profileRequire('@deepseek-ai/dsh-settings')
+          const scope = scopedCtx.settings.register(SETTINGS_NS, prepared.schema, { base: prepared.entry })
+          settingsSource = () => scope.get()
+          // Unload restores the composed entry, so a disabled plugin cannot
+          // leave the queue reading a value nobody can see or change any more.
+          scopedCtx.effect(() => () => {
+            settingsSource = () => prepared.entry
+            applySettings()
+          })
+          scope.watch(applySettings)
+          applySettings()
+          log('settings namespace 已注册:', SETTINGS_NS)
         } catch (e) {
-          log('dsh-settings 不可用，跳过 settings namespace 注册:', e && e.message)
-          return
+          log('settings namespace 注册失败，继续使用 patch config:', e && e.message)
         }
-        // Keep a live source getter: installSettingsSection passes the resolved
-        // scope thunk to setSource, and onChange must re-derive cfg from it
-        // (installSettingsSection only calls setSource on attach/detach).
-        let settingsSource = () => prepared.entry
-        settingsModule.installSettingsSection(ctx, settingsModule.settingsNamespace(SETTINGS_NS), prepared.schema, prepared.entry, {
-          setSource: source => { settingsSource = source; cfg = resolveConfig(source()) },
-          onChange: () => {
-            try { cfg = resolveConfig(settingsSource()) } catch (e) { log('settings 变更应用失败:', e && e.message) }
-            log('settings 变更已应用; cfg=', JSON.stringify(cfg))
-          },
-        })
-      }, 0)
-    })
+      })
+    }
 
     // ---- host-owned FIFO speech queue + WebSocket state sync (PR #2) ----
     let activeSpeech = null
@@ -472,7 +504,13 @@ module.exports = {
         if (type === 'approval/asked' && cfg.announceApprovals) {
           cancelPending()
           let reason = String((event.data && event.data.reason) || '')
-          if (cfg.stripApprovalPrefix) reason = reason.replace(/^escalate sandbox to danger-full-access\s*:\s*/i, '').trim()
+          if (cfg.stripApprovalPrefix) {
+            // 通用剥离行首"动作标签: "前缀（英文动作短语 + 冒号，如
+            // "Store decision fact in workspace memory (dsh-speak): <内容>"、
+            // "escalate sandbox to danger-full-access: <原因>"），只念冒号后的
+            // 具体内容；中文开头或无冒号的 reason 原样保留（如"删除 xxx"）。
+            reason = reason.replace(/^[A-Za-z][^:：\n]*?[:：]\s*/, '').trim()
+          }
           enqueue(hostItem('approval', session, event, reason || '需要你的审批，请查看界面。', null))
           return
         }
@@ -510,16 +548,31 @@ module.exports = {
         if (type === 'tool/result' && cfg.announceToolErrors) {
           const data = event.data
           const err = data && data.error
-          // 真实错误标记：error 字段（name/code）或 message 内容块 isError === true
-          // （pwsh 等工具失败时没有 error 字段，错误文本在 isError 内容块里）
+          // 真实错误标记有两处：结构化失败身份 data.error（name/code），以及结果块上的
+          // isError。0.1.2 起 createToolResultMessage 把结果块包进一个 ToolResultBlock
+          // （{ type:'tool-result', toolCallId, content:[…], isError }），文字在它嵌套的
+          // content 里；更早的版本把 isError 直接放在 text 块上。两种形状都读。
+          //
+          // 注意：pwsh / bash 把「命令非零退出」当作结果数据上报（`exit code: N`），
+          // 不置 isError —— 只有基础设施失败（spawn 错误、abort）才是 isError 结果，
+          // 所以失败的命令本身不会播报工具出错。
           const errText = (Array.isArray(data && data.message && data.message.content) ? data.message.content : [])
             .filter(block => block && block.isError === true)
-            .map(block => block.text || block.code || '').filter(Boolean).join(' ')
+            .map(block => {
+              const parts = Array.isArray(block.content) ? block.content : [block]
+              return parts.map(part => (part && (part.text || part.code)) || '').filter(Boolean).join(' ')
+            })
+            .filter(Boolean).join(' ')
           if (err || errText) {
             const detail = (errText || (err && err.code) || (err && err.name) || '').replace(/\s+/g, ' ').trim().slice(0, 60)
-            // 纯英文错误详情（PowerShell 固定模板 / 技术 code）对中文用户可读性差，
-            // 播报时截掉，只保留含中文的详情（如"文件不存在"）
-            const readable = /[\u4e00-\u9fff]/.test(detail) ? `：${detail}` : ''
+            // 详情只在"确实是一句中文描述"时才念：英文模板（Error: / ENOENT / 技术
+            // code）对中文用户可读性差，应当截掉。判据是**汉字数量多于拉丁字母数量**，
+            // 而不是"含有汉字"——后者会被路径里的中文目录名骗过：
+            // `Error: cannot read "D:\...\第二轮测试用的不存在文件.txt"` 含 12 个汉字，
+            // 却是纯英文报错（1.8.0 修正）。
+            const cjkCount = (detail.match(/[\u4e00-\u9fff]/g) || []).length
+            const latinCount = (detail.match(/[A-Za-z]/g) || []).length
+            const readable = cjkCount > latinCount ? `：${detail}` : ''
             enqueue(hostItem('tool/result', session, event, `工具调用出错${readable}`, null))
           }
           return

package/client/client.js

@@ -225,44 +225,61 @@ window.__ModuleLoader__.load({
       function visibleText(node) {
         return Array.isArray(node && node.blocks) ? node.blocks.filter(block => block && block.kind === 'text' && typeof block.text === 'string').map(block => block.text).join('') : ''
       }
+      // Constant selector used when the framework does not hand us a Chat target
+      // hook: the selectors then see no snapshot and the button renders disabled
+      // instead of crashing its row.
+      function useAbsentChat(selector) { return selector(null) }
+      /**
+       * Find the finalized assistant node carrying `messageId` in the Chat target.
+       *
+       * DSH >= 0.1.2 excludes Conversation target data from the Session snapshot,
+       * so the chat nodes are no longer reachable through `useSession`; the Chat
+       * target selector hook (`useChat`, declared by
+       * `@deepseek-ai/dsh-client-ui-chat` for every session-scoped slot) is the
+       * only read path. `snapshot.nodes` is a ChatNodeStore whose `values()` are
+       * the `{ key, kind, data, location }` nodes: the finalized assistant
+       * content lives in `data.finalNode` (assistant node) or
+       * `data.closing.finalNode` (turn-tail node), carrying messageId / turn /
+       * seq / blocks.
+       */
+      function finalNodeFor(snapshot, messageId) {
+        const nodes = snapshot && snapshot.nodes
+        if (!nodes || typeof nodes.values !== 'function') return null
+        for (const node of nodes.values()) {
+          const data = node && node.data
+          if (!data) continue
+          const final = data.finalNode || (data.closing && data.closing.finalNode) || (node.kind === 'assistant' ? data : null)
+          if (final && final.messageId != null && String(final.messageId) === messageId) return final
+        }
+        return null
+      }
       function SpeakAction(props) {
         const messageId = props.messageId == null ? null : String(props.messageId)
-        const turnData = props.useSession(snapshot => {
-          // DSH 会话投影：snapshot.chat.nodes 是按 key 索引的 Map，value 为
-          // { key, kind, data, location }。最终 assistant 消息内容在节点的
-          // data.finalNode（assistant 节点）或 data.closing.finalNode
-          // （turn-tail 节点）里，含 messageId / turn / seq / blocks。
-          const nodes = snapshot && snapshot.chat && snapshot.chat.nodes
-          if (!nodes || typeof nodes.values !== 'function') return { turn: null, text: '' }
-          const all = [...nodes.values()]
-          const finalOf = node => {
-            const d = node && node.data
-            if (!d) return null
-            if (d.finalNode) return d.finalNode
-            if (d.closing && d.closing.finalNode) return d.closing.finalNode
-            return d.kind === 'assistant' ? d : null
-          }
-          const entries = all.map(node => ({ final: finalOf(node) }))
-          const addressed = entries.find(entry => entry.final && String(entry.final.messageId) === messageId)
-          if (!addressed || !Number.isFinite(addressed.final.turn)) return { turn: null, text: '' }
-          const turn = addressed.final.turn
-          // 只重播点击的那条消息（assistant-actions 只渲染在回合尾部 = 最终回复），
-          // 不合并整个回合的所有中间消息
-          const text = visibleText(addressed.final)
-          return { turn, text }
+        // Both selectors return primitives: `useChat` is a snapshot selector
+        // hook, and a fresh object per read would make the subscription churn.
+        const useChat = typeof props.useChat === 'function' ? props.useChat : useAbsentChat
+        const turn = useChat(snapshot => {
+          const final = finalNodeFor(snapshot, messageId)
+          return final && Number.isFinite(final.turn) ? final.turn : null
+        })
+        // 只重播点击的那条消息（assistant-actions 只渲染在回合尾部 = 最终回复），
+        // 不合并整个回合的所有中间消息
+        const text = useChat(snapshot => {
+          const final = finalNodeFor(snapshot, messageId)
+          return final ? visibleText(final) : ''
         })
         const active = useSpeechState()
-        const speaking = active.speaking && String(active.sessionId) === String(props.sessionId) && active.turn === turnData.turn
+        const speaking = active.speaking && String(active.sessionId) === String(props.sessionId) && active.turn === turn
         const [pending, setPending] = React.useState(false)
         const label = speaking ? t('actionStop') : t('actionSpeakTurn')
         return e('button', {
           type: 'button', className: 'dsh-speak-message-action', 'aria-label': label, 'aria-pressed': speaking,
-          'data-speaking': speaking || undefined, title: label, disabled: pending || !turnData.text.trim(),
+          'data-speaking': speaking || undefined, title: label, disabled: pending || !text.trim(),
           onClick: () => {
             if (pending) return
             setPending(true)
             const action = speaking ? 'stop' : 'play'
-            const payload = speaking ? { action } : { action, sessionId: props.sessionId, turn: turnData.turn, messageId, text: turnData.text }
+            const payload = speaking ? { action } : { action, sessionId: props.sessionId, turn, messageId, text }
             void control(payload).catch(console.error).finally(() => setPending(false))
           },
         }, speaking ? e(IconPauseOutline16) : e(IconVolume2))

package/docs/DESIGN.md

@@ -94,8 +94,13 @@ Processing pipeline (in order):
 3. **Strip emoji / non-printable** — keep CJK, CJK punctuation, full-width ranges,
    ASCII printable (regex `[^一-龥　-〿＀-￯ - -~]`).
 4. **Collapse whitespace.**
-5. **Length guard** — if cleaned text exceeds `MaxChars` (default 300), replace with
-   `LongTextMessage` (default: `本次播报内容较长，请自行阅读。`).
+5. **Length guard** — over `MaxChars` (default 300) the text is handled by
+   `LongTextMode`: `message` (the default) replaces it with `LongTextMessage`
+   (default: `本次播报内容较长，请自行阅读。`); `heading` speaks the largest
+   markdown heading, or — when the text has no heading at all — a coherent
+   opening: the leading `MaxChars` window trimmed back to its last sentence end
+   (that fallback used to speak only the first line, which sounded like the
+   narration was cut off).
 6. **Speak** — `System.Speech.Synthesis.SpeechSynthesizer`, volume/rate applied,
    best zh natural voice selected, then `Speak()`.
 
@@ -135,14 +140,20 @@ no "reply finished" hook, so the plugin observes the session event stream:
 - **Optional event announcements** (1.6.0, all off by default): `turn/end`,
   `command/done`, `goal/change`, `tool/result` (on error), and `todo/write` each
   have an independent toggle and announce a fixed phrase on fire (see §5).
-- **Settings namespace registration** (1.6.0): one timer tick after apply the
-  plugin calls `installSettingsSection(ctx, 'dsh-speak', schema, patchConfig,
-  hooks)`, resolving config as schema default → patch `config` → UI user layer.
-  `onChange` re-derives `cfg` from a saved `settingsSource()` thunk (note:
-  `installSettingsSection` only calls `setSource` on attach/detach, so changes
-  must be re-read in `onChange`). On hosts without a settings service (dsh <
-  0.1.0-rc.7 or no provider mounted) the registration is skipped silently and
-  the plugin works purely from the patch config — backward compatible.
+- **Settings namespace registration** (1.6.0): the plugin wires its namespace
+  through the settings *service* — `ctx.inject(['settings'])` →
+  `settings.register('dsh-speak', schema, { base: patchConfig })` → re-derive
+  `cfg` from `scope.get()` on every `scope.watch` notification, and restore the
+  composed patch config when the fiber unloads. Resolution stays schema default
+  → patch `config` → UI user layer.
+  The plugin never imports `@deepseek-ai/dsh-settings`: DSH 0.1.2-alpha.1 deleted
+  the `installSettingsSection` / `settingsNamespace` helpers, and referencing
+  them is fatal — a missing named export is a module-evaluation error, and the
+  old lazy call threw `settingsNamespace is not a function` inside a timer
+  callback, which crashed the host (dsh exited 1 instead of booting). The service
+  itself never changed. On hosts without a settings service the inject callback
+  never runs and the plugin works purely from the patch config — graceful
+  degradation with no version check.
 
 Registration snippet (also automated by `install.ps1`; npm installs use the bare
 package name `'dsh-speak'` — this is the file-install path):
@@ -168,7 +179,13 @@ that registers two pieces of UI:
   Clicking 🔊 POSTs to `/dsh-speak/control` to replay that final message; clicking
   again stops; clicking another switches. The button's speaking/paused state is
   derived from the authoritative host state over the `/dsh-speak/ws` WebSocket
-  (matched by session + turn identity).
+  (matched by session + turn identity). The replayed text is resolved through the
+  Chat target selector hook `useChat` (`@deepseek-ai/dsh-client-ui-chat` declares
+  it for every session-scoped slot): DSH 0.1.2 excluded Conversation target data
+  from the Session snapshot, so `useSession(s => s.chat.nodes)` no longer yields
+  the chat nodes. The two selectors return primitives only, because a fresh
+  object per read would churn the subscription, and a missing `useChat` prop
+  degrades the button to disabled instead of throwing inside its row.
 - **Settings → dsh-speak settings page** (1.7.0): registered into the
   `settings.section` slot, drawn with `@deepseek-ai/dsh-client-ui-primitives`
   (Button / DisclosureRow / Input; Toggle / Options / SettingInput helpers). Every
@@ -179,7 +196,12 @@ that registers two pieces of UI:
 
 - The package declares its browser half via `package.json`
   `dsh.client: { platform: 'web' }` + `exports['./client']`; DSH's client-modules
-  scanner picks it up and loads it automatically.
+  scanner picks it up and loads it automatically. `dsh.client.inject` names the
+  package rows that DECLARE the two slots it occupies
+  (`@deepseek-ai/dsh-client-ui-chat`, `@deepseek-ai/dsh-client-ui-settings`) so
+  their factories arrive first; `dsh.client.external` lists
+  `@deepseek-ai/dsh-client-ui-primitives`, which the shell seeds in its static
+  module table.
 - **Deliberately handwritten, zero build**: it only uses platform seed modules
   and official primitives (the bundle-purity gate allows primitives but forbids
   importing official package internals), matching the built bundles' contract.
@@ -206,7 +228,7 @@ returns immediately. (Async spawning is safe here — the nested-spawn restricti
 | `turn/end`                       | 🟡 off by default; announces "第 N 轮对话完成/中断/异常结束" |
 | `command/done`                   | 🟡 off by default; announces "命令执行完成/失败" |
 | `goal/change`                    | 🟡 off by default; announces "已创建目标/目标已完成…" (head) |
-| `tool/result`                    | 🟡 off by default; announces "工具调用出错" only when `error` or an `isError` content block is present (English details / technical codes are dropped, Chinese details kept) |
+| `tool/result`                    | 🟡 off by default; announces "工具调用出错" only for a structured failure (`error`, or a result block with `isError === true`). A non-zero shell exit is result data (`exit code: N`), not an error — pwsh/bash deliberately settle it as a completed call, so only infrastructure failures (spawn errors, aborts) and structured tool failures (e.g. fs) announce. Since 0.1.2 the `ToolResultBlock` wrapper nests the text under `content[]`, so the detail is read from there (English details / technical codes dropped, Chinese details kept) |
 | `todo/write`                     | 🟡 off by default; announces "待办已更新：n/m 完成" |
 | `assistant/message` (queueAllMessages on) | ✅ every message enqueued immediately (intermediate spoken too) |
 | manual replay (per-message 🔊)   | ✅ clear queue → stop current → speak that turn |
@@ -223,7 +245,8 @@ returns immediately. (Async spawning is safe here — the nested-spawn restricti
 | `-Rate`           | `1`                         | speech rate (SAPI scale)                 |
 | `-MaxChars`       | platform                    | beyond this, replaced by `LongTextMessage` (macOS default 0 = unlimited) |
 | `-LongTextMessage`| `本次播报内容较长，请自行阅读。` | spoken instead of over-long text         |
-| `-LongTextMode`   | `message`                    | `message` (fixed prompt) \| `heading` (speak the largest markdown heading) |
+| `-LongTextMode`   | `message`                    | `message` (fixed prompt) \| `heading` (speak the largest markdown heading; **with no heading, speak a coherent opening**: the leading `MaxChars` window trimmed back to its last sentence end, kept whole when that would drop more than half the window. Full-width `。！？；…` always end a sentence; half-width `.!?;` only when followed by whitespace/a closing quote or bracket — read one character PAST the window for the last position, so an English `period + space` at the edge counts while `Version 0.1.` does not) |
+| `-DryRun`         | `0`                          | print the text that WOULD be spoken as UTF-8 on stdout and exit without audio (maintainer aid for diffing the cleaning pipeline and the long-text guard) |
 | `-CleanMarkdownFormatting` | `true`               | convert Markdown to natural speech (link labels kept, URLs stripped) |
 | `-ReadInlineCode` | `true`                       | read inline code without backtick markers |
 | `-CodeBlocks`     | `smart`                      | `all` \| `smart` \| `replace` (fenced code blocks) |
@@ -281,6 +304,7 @@ Full configuration guide: the README's Configuration section.
 | 6.6 | Reading/writing speech text as ANSI | mojibake or empty speech | always UTF-8 (`[System.IO.File]::ReadAllText(..., UTF8)`) |
 | 6.7 | A repo `.sh` checked out as CRLF by `core.autocrlf=true`; `npm pack` bundles the **working-tree** file | the published `speak.sh` dies in bash on macOS (`command not found`, `syntax error near {`), silent failure | `.gitattributes` pins `*.sh text eol=lf` (check `file engine/speak.sh` for CRLF before publishing) |
 | 6.8 | Log path hard-coded as `/tmp` | on macOS `os.tmpdir()` is `/var/folders/.../T`, the log is not at `/tmp` | look for the log at `os.tmpdir()` (= `$TMPDIR`) |
+| 6.9 | Engine `.ps1` saved **without the UTF-8 BOM** (any editor or script that rewrites the file drops it — it is byte metadata, not content, and nothing in the file records the requirement) | Windows PowerShell 5.1 decodes the file with the system ANSI code page, so Chinese **literals in code** become mojibake: the emoji/CJK filter then drops real text (silent no audio) or the sentence-end classes stop matching (silent wrong trimming). Comments only look garbled | two rules: (a) the engine's CODE stays ASCII-only — PowerShell punctuation is built from `[char]` code points and ranges are written as `\u` escapes, and `speak.sh`'s Perl guard writes punctuation as `\x{...}` escapes (Perl source is bytes without `use utf8`, so a Chinese literal in a pattern is read as Latin-1 and matches nothing — a macOS-only "trims nothing" bug 1.8.0 shipped and `npm test` caught it on a real machine) — so a lost BOM only garbles comments and the two default prompts; (b) `scripts/test-engine-static.js` asserts the BOM on every `engine/*.ps1` plus a PowerShell parse check (also in `prepublishOnly`), and `scripts/test-engine-longtext.js` asserts the extracted Perl guard is ASCII-only |
 
 ## 7. Extending
 

package/docs/DESIGN.zh-CN.md

@@ -86,8 +86,11 @@ Agent 工具会跑长任务（构建、测试、迁移、批量修改），而
 3. **剥离 emoji / 不可打印字符** — 只保留中文汉字、中文标点、全角区间、
    ASCII 可打印（正则 `[^一-龥　-〿＀-￯ - -~]`）。
 4. **压缩空白。**
-5. **长度守卫** — 清洗后文本超过 `MaxChars`（默认 300）时，替换为
-   `LongTextMessage`（默认：`本次播报内容较长，请自行阅读。`）。
+5. **长度守卫** — 超过 `MaxChars`（默认 300）的文本由 `LongTextMode` 决定：
+   `message`（默认）替换为 `LongTextMessage`（默认：`本次播报内容较长，请自行
+   阅读。`）；`heading` 念最大字号的 markdown 标题，而**整段没有标题时**改念
+   "有头有尾的开头"——取开头 `MaxChars` 窗口并回退到窗口内最后一个句末标点
+   （旧实现这里只念第一个非空行，听感上就是"从第二行开始不念了"）。
 6. **朗读** — `System.Speech.Synthesis.SpeechSynthesizer`，应用音量/语速，
    选择最佳 zh 自然语音，然后 `Speak()`。
 
@@ -119,13 +122,17 @@ Agent 工具会跑长任务（构建、测试、迁移、批量修改），而
   事件；开 = 每条 assistant 消息立即入队朗读（中间消息也读）。
 - **可选事件播报**（1.6.0，默认全关）：`turn/end`、`command/done`、
   `goal/change`、`tool/result`（出错时）、`todo/write` 各自独立开关（见 §5）。
-- **settings namespace 注册**（1.6.0）：apply 后在一个 timer tick 里调用
-  `installSettingsSection(ctx, 'dsh-speak', schema, patchConfig, hooks)`，配置
-  解析为 schema 默认 → patch `config` → UI 用户设置三层。`onChange` 时通过
-  `settingsSource()` 重新解析 cfg（注意：`installSettingsSection` 只在
-  attach/detach 时调 `setSource`，变更时需自己在 `onChange` 里重读 source）。
-  若宿主没有 settings 服务（dsh < 0.1.0-rc.7 或未挂载 provider），注册静默
-  跳过，插件完全按 patch `config` 工作——向后兼容。
+- **settings namespace 注册**（1.6.0）：插件通过 settings **服务**接线——
+  `ctx.inject(['settings'])` → `settings.register('dsh-speak', schema, { base:
+  patchConfig })` → 每次 `scope.watch` 通知时从 `scope.get()` 重新解析 cfg，
+  fiber 卸载时恢复成组合层的 patch config。配置解析仍是 schema 默认 → patch
+  `config` → UI 用户设置三层。
+  插件**不再 import** `@deepseek-ai/dsh-settings`：DSH 0.1.2-alpha.1 删除了
+  `installSettingsSection` / `settingsNamespace` 两个辅助导出，引用它们是致命
+  的——缺失的具名导出会在模块求值期直接报错；旧代码在 timer 回调里懒调用，抛
+  `settingsNamespace is not a function` 把宿主打崩（dsh 直接退出 1，起不来）。
+  服务本身从未变过。宿主没有 settings 服务时 inject 回调永不执行，插件完全按
+  patch `config` 工作——优雅退化，无需版本判断。
 
 注册片段（`install.ps1` 也会自动完成；npm 安装用裸包名 `'dsh-speak'` 即可，
 这是文件安装方式用的路径）：
@@ -150,7 +157,12 @@ factory })`），注册两条 UI：
   `conversation.chat.assistant-actions` slot（该回合最终回复的操作栏）。点击 🔊
   调 `/dsh-speak/control` 重播该条最终回复，再点停止，点另一条切换；按钮状态
   （播放中/暂停）由 `/dsh-speak/ws` WebSocket 的 host 权威状态推导（session +
-  turn 身份匹配）。
+  turn 身份匹配）。重播文本改为通过 Chat 目标的 selector hook `useChat` 取
+  （`@deepseek-ai/dsh-client-ui-chat` 为所有 session 作用域 slot 声明了它）：
+  DSH 0.1.2 起 Session snapshot 不再携带 Conversation 目标数据，
+  `useSession(s => s.chat.nodes)` 已经取不到聊天节点。两个 selector 只返回原始值
+  （每次读返回新对象会让订阅反复失效），拿不到 `useChat` 时按钮退化为禁用，而不是
+  在自己的操作栏里抛错。
 - **设置 → dsh-speak 设置独立设置页**（1.7.0）：注册进 `settings.section` slot。
   用 `@deepseek-ai/dsh-client-ui-primitives` 的 Button/DisclosureRow/Input
   绘制（Toggle/Options/SettingInput 组件），所有配置项（总开关、自动朗读、
@@ -160,6 +172,10 @@ factory })`），注册两条 UI：
 
 - 包通过 `package.json` 的 `dsh.client: { platform: 'web' }` +
   `exports['./client']` 声明浏览器端；DSH 的 client-modules 扫描到后自动加载。
+  `dsh.client.inject` 列出**声明**它占用那两个 slot 的包 row
+  （`@deepseek-ai/dsh-client-ui-chat`、`@deepseek-ai/dsh-client-ui-settings`），
+  保证它们的 factory 先到达；`dsh.client.external` 列出
+  `@deepseek-ai/dsh-client-ui-primitives`（shell 的静态模块表里已 seed）。
 - **刻意手写、零构建**：只用平台 seed 模块 + 官方 primitives（bundle-purity
   gate 允许用 primitives，禁止 import 官方包内部组件），与构建出来的 bundle
   契约一致。
@@ -184,7 +200,7 @@ Claude Code *确实*有 Stop hook。hook JSON（含 `transcript_path`）从 stdi
 | `turn/end`（回合结束）           | 🟡 默认关；开则播报"第 N 轮对话完成/中断/异常结束" |
 | `command/done`（命令完成）       | 🟡 默认关；开则播报"命令执行完成/失败" |
 | `goal/change`（目标变更）        | 🟡 默认关；开则播报"已创建目标/目标已完成…（前 40 字）" |
-| `tool/result`（工具结果）        | 🟡 默认关；开则仅当带 `error` 或 `isError` 内容块时播报"工具调用出错"（英文详情/技术 code 截掉，只保留中文详情） |
+| `tool/result`（工具结果）        | 🟡 默认关；开则仅对**结构化失败**播报"工具调用出错"（带 `error`，或结果块 `isError === true`）。shell 命令非零退出是结果数据（`exit code: N`）而非错误——pwsh/bash 有意按"已完成调用"结算，所以只有基础设施失败（spawn 错误、abort）和 fs 这类结构化失败才播报。0.1.2 起结果块被包进 `ToolResultBlock`，文字在其嵌套的 `content[]` 里（英文详情/技术 code 截掉，只保留中文详情） |
 | `todo/write`（待办更新）         | 🟡 默认关；开则播报"待办已更新：n/m 完成" |
 
 | `assistant/message`（queueAllMessages 开）| ✅ 每条立即入队（中间消息也读） |
@@ -202,7 +218,8 @@ Claude Code *确实*有 Stop hook。hook JSON（含 `transcript_path`）从 stdi
 | `-Rate` | `1` | 语速（SAPI 刻度） |
 | `-MaxChars` | 平台相关 | 超过此长度时替换为 `LongTextMessage`（macOS 默认 0 = 不限） |
 | `-LongTextMessage` | `本次播报内容较长，请自行阅读。` | 超长文本时改念这句 |
-| `-LongTextMode` | `message` | `message`（固定提示语）\| `heading`（念最大字号 markdown 标题） |
+| `-LongTextMode` | `message` | `message`（固定提示语）\| `heading`（念最大字号 markdown 标题；**整段没有标题时改念"有头有尾的开头"**：取开头 `MaxChars` 窗口并回退到窗口内最后一个句末标点，若这样会砍掉半个窗口以上则保留整窗。全角 `。！？；…` 无条件算句末；半角 `.!?;` 只在后面跟空白、右引号/右括号时才算——最后一位会**多读一位**判断，所以英文「句号+空格」在边缘照样算，`Version 0.1.` 这种小数点不算） |
+| `-DryRun` | `0` | 把「将要朗读的文本」按 UTF-8 打到 stdout 后直接退出、完全不出声（调试清洗与长文守卫用） |
 | `-CleanMarkdownFormatting` | `true` | Markdown 转自然语音（保留链接文字去 URL） |
 | `-ReadInlineCode` | `true` | 朗读行内代码（去掉反引号） |
 | `-CodeBlocks` | `smart` | `all` \| `smart` \| `replace`（围栏代码块） |
@@ -259,6 +276,7 @@ config:
 | 6.6 | 用 ANSI 读写播报文本 | 乱码或完全无声 | 一律 UTF-8（`[System.IO.File]::ReadAllText(..., UTF8)`） |
 | 6.7 | 仓库内 `.sh` 被 git 按 `core.autocrlf=true` 检出为 CRLF，`npm pack` 打包的是**工作区**文件 | 发布包里的 `speak.sh` 在 macOS 上 bash 语法错误（`command not found`、`syntax error near {`），静默失败 | `.gitattributes` 里 `*.sh text eol=lf` 锁定 LF（发布前 `file engine/speak.sh` 确认无 CRLF） |
 | 6.8 | 日志路径写死 `/tmp` | macOS 上 `os.tmpdir()` 是 `/var/folders/.../T`，`/tmp` 里找不到日志 | 日志路径按 `os.tmpdir()`（= `$TMPDIR`）查找 |
+| 6.9 | 引擎 `.ps1` 被**丢掉 UTF-8 BOM** 保存（任何重写文件的编辑器/脚本都会丢——BOM 是字节级元数据而不是内容，文件里没有任何东西记录"我需要 BOM"） | Windows PowerShell 5.1 改用系统 ANSI 代码页解码，**代码里的中文标点**变乱码：emoji/CJK 过滤范围错乱会连中文一起丢掉（**静默无声**），句末标点类失配则修剪静默失效；中文注释只是显示为乱码 | 两条规则：(a) 引擎**代码保持纯 ASCII** ——PowerShell 的中文标点用 `[char]` 码位拼、范围写成 `\u` 转义，`speak.sh` 的 Perl 守卫也是同理用 `\x{...}` 码位转义（Perl 源码没有 `use utf8` 时按字节处理，模式里直接写中文会被当成 Latin-1 而**完全匹配不到**——这是 1.8.0 实际发布出去的 macOS 专属"完全不修剪"bug，由真机 `npm test` 抓出）；这样丢 BOM 只影响注释和两个默认提示语；(b) `scripts/test-engine-static.js` 对每个 `engine/*.ps1` 断言 BOM + PowerShell 语法解析（也挂 `prepublishOnly`），`scripts/test-engine-longtext.js` 断言抽出的 Perl 守卫是纯 ASCII |
 
 ## 7. 扩展
 

package/engine/speak.ps1

@@ -29,6 +29,9 @@ param(
     [int]$Volume = 50,
     [int]$Rate = 1,
     [int]$MaxChars = 300,
+    # 本脚本唯一的非 ASCII 代码字面量。丢了 UTF-8 BOM 时 PowerShell 5.1 会按 ANSI
+    # 代码页把它解码成乱码——DSH 插件总是显式传 -LongTextMessage，所以只影响手动
+    # CLI 调用；脚本逻辑（句末判定 / 字符过滤 / 分句）已全部改成纯 ASCII 源码。
     [string]$LongTextMessage = '本次播报内容较长，请自行阅读。',
     [ValidateSet('message', 'heading')]
     [string]$LongTextMode = 'message',
@@ -41,11 +44,15 @@ param(
     [int]$CodeBlockMaxChars = 300,
     [string]$CodeBlockReplacementText = 'You can see the code in our history.',
     # 手动重播完整朗读：跳过超长文本的 heading/message 截断，分段完整朗读
-    [string]$FullRead = '0'
+    [string]$FullRead = '0',
+    # 只把「将要朗读的文本」按 UTF-8 写到 stdout、完全不出声（调试清洗与长文
+    # 守卫用；正常调用无需传，插件不会传）
+    [string]$DryRun = '0'
 )
 
 $cleanMarkdown = $CleanMarkdownFormatting -in @('1', 'true', 'yes', 'on')
 $readInlineCode = $ReadInlineCode -in @('1', 'true', 'yes', 'on')
+$dryRunMode = $DryRun -in @('1', 'true', 'yes', 'on')
 # 注意：PowerShell 变量大小写不敏感，内部变量名不能与参数名仅差大小写
 # （曾用 $fullRead 导致自赋值污染参数 $FullRead，使 -not 判断失效）
 $fullReadMode = $FullRead -in @('1', 'true', 'yes', 'on')
@@ -61,13 +68,12 @@ if (-not $text -or -not $text.Trim()) { exit 0 }
 
 # ---------- length guard: adapter per-Speak ceiling ----------
 # 'message': fixed prompt. 'heading': speak the largest markdown heading instead
-# (fewest '#' wins, tie -> first; no heading -> first non-empty line; the
-# cleaned candidate is still subject to the ceiling below). FullRead 手动重播
-# 跳过该守卫（见文件底部"完整朗读"分支）。
-if (-not $fullReadMode -and $text.Length -gt $MaxChars -and $LongTextMode -eq 'heading') {
+# (fewest '#' wins, tie -> first; with NO heading, speak a coherent opening of
+# the text — see below; the cleaned candidate is still subject to the ceiling
+# below). FullRead 手动重播跳过该守卫（见文件底部"完整朗读"分支）。
+if (-not $fullReadMode -and $MaxChars -gt 0 -and $text.Length -gt $MaxChars -and $LongTextMode -eq 'heading') {
     $candidate = ''
     $bestLevel = 7
-    $firstNonEmpty = ''
     # 代码块 fence 内的行跳过：其中的 "# 注释" 不是 markdown 标题，
     # 否则长回复里的代码注释会被误当成标题只念注释
     $inCodeBlock = $false
@@ -80,12 +86,50 @@ if (-not $fullReadMode -and $text.Length -gt $MaxChars -and $LongTextMode -eq 'h
                 $bestLevel = $level
                 $candidate = $line -replace '^\s*#+\s*', ''
             }
-        } elseif (-not $firstNonEmpty -and $line.Trim()) {
-            $firstNonEmpty = $line
         }
     }
-    if (-not $candidate) { $candidate = $firstNonEmpty }
-    if ($candidate) { $text = $candidate }
+    if ($candidate) {
+        # 有标题：只念最大的标题（"长回复只报标题"）
+        $text = $candidate
+    } else {
+        # 没有标题：**不能只念第一个非空行** —— 那会念出"……官方文档写明："这类
+        # 断头句然后静默停住，听感上就是"从第二行开始不念了"（1.8.0 修复）。
+        # 改为取开头 MaxChars 长度的窗口，并在窗口内最后一个句末标点处收尾。
+        # 中英双语判据：
+        #   * 全角 。！？； 与省略号 … 无条件算句末（中文标点不含歧义）；
+        #   * 半角 .!?; 只在后面跟空白、右引号/右括号时才算，否则 "0.1.2"、
+        #     "file.txt"、"e.g." 里的小数点/扩展名会被当成句子结尾；
+        #   * 半角标点不认"到窗口结尾"本身就结束：窗口末尾若是小数点，认了等于没
+        #     修剪。但会多读一位来判断（见下），所以"句号+空格"在窗口边缘照样成立。
+        # 收尾后若不足半个窗口，就保留整个窗口：一整句超长文本不该被砍成一个词。
+        #
+        # 标点类一律用 [char] 码位拼出来，让源码里**不出现非 ASCII 代码字面量**：
+        #   1) PowerShell 把 ’ ” ‘ “ 也当字符串引号，直接写进单引号串会提前截断
+        #      （报 Missing ')' in method call）；
+        #   2) 更要紧的是——脚本一旦丢掉 UTF-8 BOM，Windows PowerShell 5.1 会按
+        #      ANSI 代码页解码，代码里的中文标点会变乱码，句末判定**静默失效**。
+        #      代码保持纯 ASCII 后，丢 BOM 只会让中文注释变乱码，不影响行为。
+        #   。 ！ ？ ； … = 0x3002 0xFF01 0xFF1F 0xFF1B 0x2026
+        #   ） 】 」 』 = 0xFF09 0x3011 0x300D 0x300F
+        $fullWidthEnders = [string]([char]0x3002) + [char]0xFF01 + [char]0xFF1F + [char]0xFF1B + [char]0x2026
+        $closers = [string]([char]0x22) + [char]0x201D + [char]0x2019 + [char]0xFF09 + [char]0x3011 + [char]0x300D + [char]0x300F + [char]0x29 + '\' + [char]0x5D + [char]0x7D
+        $sentenceEndPattern = '(?:[' + $fullWidthEnders + ']|[.!?;](?=[\s' + $closers + ']))'
+        $window = $text.Substring(0, [Math]::Min($text.Length, $MaxChars))
+        # 多看一个字符再判定，但只在窗口内收尾：句号落在窗口最后一位时，它后面那个
+        # 空格在窗口之外，多看一位才能认出"句号+空格"确实是句末；而"句号+数字"
+        # （`Version 0.1.` 的第 300 位）依旧被拒。切点永远不超过窗口长度。
+        $scan = $text.Substring(0, [Math]::Min($text.Length, $MaxChars + 1))
+        # 取**落在窗口内**的最后一个句末标点：scan 多读的那一位会让最后一个匹配可能
+        # 落在窗口之外（窗口外正好是个全角句号时），那种匹配必须忽略——但也不能因此
+        # 丢掉窗口内更早的合法边界，所以逐个过滤而不是只看最后一个。
+        $cut = 0
+        foreach ($match in [regex]::Matches($scan, $sentenceEndPattern)) {
+            $end = $match.Index + $match.Length
+            if ($end -le $window.Length) { $cut = $end }
+        }
+        if ($cut -ge [Math]::Floor($window.Length / 2)) { $window = $window.Substring(0, $cut) }
+        $text = $window
+    }
 }
 
 # ---------- clean: Markdown -> natural speech text ----------
@@ -104,13 +148,27 @@ if ($cleanMarkdown) {
     $text = $text -replace '[*_~]+', ''
 }
 # Keep all Unicode letters, including Portuguese accents; remove unsafe symbols.
-$text = [regex]::Replace($text, '[^\p{L}\p{N}一-龥　-〿＀-￯ - -~]', '')
+# 范围写成 \u 转义（纯 ASCII 源码，丢 BOM 也不会乱码）：
+#   \u4e00-\u9fa5 汉字、\u3000-\u303f 中文标点、\uff00-\uffef 全角、
+#   \u2000-\u206f 通用标点（含 … 和 —）、\u0020-\u007e ASCII 可打印。
+$text = [regex]::Replace($text, '[^\p{L}\p{N}\u4e00-\u9fa5\u3000-\u303f\uff00-\uffef\u2000-\u206f\u0020-\u007e]', '')
 $text = $text -replace '\s+', ' '
 $text = $text.Trim()
 
 # ---------- final ceiling (also catches over-long heading candidates) ----------
 if (-not $fullReadMode -and $text.Length -gt $MaxChars) { $text = $LongTextMessage }
 
+# ---------- dry run: expose the text that would be spoken, silently ----------
+# Maintainer aid: makes the cleaning pipeline and the long-text guard observable
+# without a speaker, so a truncated candidate can be diffed against its source.
+# Written as raw UTF-8 bytes so a redirected capture never depends on the
+# console code page.
+if ($dryRunMode) {
+    $bytes = [System.Text.Encoding]::UTF8.GetBytes($text)
+    [Console]::OpenStandardOutput().Write($bytes, 0, $bytes.Length)
+    exit 0
+}
+
 # ---------- speak ----------
 Add-Type -AssemblyName System.Speech
 $synth = New-Object System.Speech.Synthesis.SpeechSynthesizer
@@ -132,7 +190,8 @@ $synth.Rate = $Rate
 # 标点切成不超过 450 字的段，逐段朗读（自动播报不经过这里，走上面的守卫）。
 $SPEAK_CHUNK = 400
 if ($fullReadMode -and $text.Length -gt $SPEAK_CHUNK) {
-    $parts = [regex]::Split($text, '(?<=[。！？；.!?;])')
+    # 分句标点同样用 \u 转义（纯 ASCII 源码）
+    $parts = [regex]::Split($text, '(?<=[\u3002\uff01\uff1f\uff1b.!?;])')
     $chunk = ''
     foreach ($part in $parts) {
         if ($part.Length -eq 0) { continue }

package/engine/speak.sh

@@ -55,15 +55,45 @@ fi
 # `heading` is meaningful only when a positive long-text ceiling is configured.
 # -F (full read, manual replay) skips this guard entirely.
 if [ "$FULL_READ" != "1" ] && [ "$MAX_CHARS" -gt 0 ] && [ "${#TEXT}" -gt "$MAX_CHARS" ] && [ "$LONG_MODE" = "heading" ]; then
+  export DSH_SPEAK_MAX_CHARS="$MAX_CHARS"
   TEXT=$(printf '%s' "$TEXT" | /usr/bin/perl -CSD -e '
-    my $best = 7; my $cand = ""; my $first = ""; my $inCode = 0;
-    while (<STDIN>) {
-      if (/^\s*```/) { $inCode = !$inCode; next; }   # 跳过代码块内的 "# 注释"
+    my $text = do { local $/; <STDIN> };
+    my $best = 7; my $cand = ""; my $inCode = 0;
+    for my $line (split /\n/, $text, -1) {
+      $line =~ s/\r$//;
+      if ($line =~ /^\s*```/) { $inCode = !$inCode; next; }   # 跳过代码块内的 "# 注释"
       next if $inCode;
-      if (/^[ \t]*(\#{1,6})[ \t]+(.*)$/) { my $n = length($1); if ($n < $best) { $best = $n; $cand = $2; } }
-      elsif ($first eq "" && /\S/) { $first = $_; }
+      if ($line =~ /^[ \t]*(\#{1,6})[ \t]+(.*)$/) { my $n = length($1); if ($n < $best) { $best = $n; $cand = $2; } }
     }
-    print($cand eq "" ? $first : $cand);
+    if ($cand ne "") { print $cand; exit }
+    # 没有标题：**不能只念第一个非空行**（会念出"……写明："这种断头句然后静默
+    # 停住，听感上就是"从第二行开始不念了"）。改为取开头 MaxChars 窗口，并在窗口
+    # 内最后一个句末标点处收尾。中英双语判据与 speak.ps1 保持一致：
+    #   * 全角 。！？；… 无条件算句末；
+    #   * 半角 .!?; 只在后面跟空白、右引号/右括号时才算，否则
+    #     "0.1.2"、"file.txt"、"e.g." 里的小数点/扩展名会被当成句末；
+    #   * 半角标点不认"到窗口结尾"本身就结束：窗口末尾若是小数点，认了等于没修剪。
+    #     但会多读一位来判断，所以"句号+空格"在窗口边缘照样成立。
+    # 收尾后若不足半个窗口，就保留整个窗口，避免一整句超长文本被砍成一个词。
+    #
+    # 标点一律写成 \x{...} 码位转义，让这段 Perl 源码保持**纯 ASCII**：Perl 源码默认
+    # 按字节处理（这里没有 use utf8），直接写中文标点会被当成 Latin-1 单字节字符，
+    # 模式就再也匹配不到解码后的正文，表现为**完全不修剪**（1.8.0 实测踩到）。
+    # 码位与 speak.ps1 里 [char] 构造的集合一一对应：
+    #   。 ！ ？ ； …   = \x{3002} \x{FF01} \x{FF1F} \x{FF1B} \x{2026}
+    #   ） 】 」 』 = \x{FF09} \x{3011} \x{300D} \x{300F}
+    #   " ” ’ ) ] }    = " \x{201D} \x{2019} ) ] }
+    my $max = $ENV{DSH_SPEAK_MAX_CHARS} || 300;
+    my $window = length($text) > $max ? substr($text, 0, $max) : $text;
+    my $scan = length($text) > $max + 1 ? substr($text, 0, $max + 1) : $text;
+    my @ends;
+    while ($scan =~ /(?:[\x{3002}\x{FF01}\x{FF1F}\x{FF1B}\x{2026}]|[.!?;](?=[\s"\x{201D}\x{2019}\)\]\}\x{FF09}\x{3011}\x{300D}\x{300F}]))/g) { push @ends, pos($scan); }
+    # 只认落在窗口内的最后一个句末标点：多读的那一位可能让最后一个匹配落在窗口
+    # 之外，那种匹配要忽略，但不能因此丢掉窗口内更早的合法边界。
+    my $cut = 0;
+    foreach my $end (@ends) { $cut = $end if $end <= length($window); }
+    $window = substr($window, 0, $cut) if $cut >= int(length($window) / 2);
+    print $window;
   ')
 fi
 

package/engine/speech-prompt.ps1

@@ -5,6 +5,8 @@
 #
 #   powershell.exe -NoProfile -ExecutionPolicy Bypass -File speech-prompt.ps1 -Text "请做出选择"
 
+# 唯一的非 ASCII 代码字面量：丢 UTF-8 BOM 时 PowerShell 5.1 会按 ANSI 代码页把它
+# 解码成乱码——调用方通常显式传 -Text，所以只影响不带参数的调用。
 param([string]$Text = '请做出选择')
 
 if (-not $Text) { exit 0 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-speak",
-  "version": "1.7.4",
+  "version": "1.8.0",
   "description": "Make your AI harness speak — voice announcements for DSH and other AI coding harnesses (Windows SAPI5 + macOS system voices)",
   "main": "adapters/dsh/speech-hook.js",
   "exports": {
@@ -27,9 +27,8 @@
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-ui-conversation",
-        "@deepseek-ai/dsh-client-ui-settings",
-        "@deepseek-ai/dsh-client-runtime"
+        "@deepseek-ai/dsh-client-ui-chat",
+        "@deepseek-ai/dsh-client-ui-settings"
       ],
       "external": [
         "@deepseek-ai/dsh-client-ui-primitives"
@@ -53,7 +52,8 @@
     "say"
   ],
   "scripts": {
-    "prepublishOnly": "node --check adapters/dsh/speech-hook.js && node --check client/client.js"
+    "test": "node scripts/test-engine-static.js && node scripts/test-engine-longtext.js && node scripts/test-client-bundle.js && node scripts/test-speech-hook.js && node scripts/test-settings-integration.js",
+    "prepublishOnly": "node scripts/test-engine-static.js && node --check adapters/dsh/speech-hook.js && node --check client/client.js"
   },
   "dependencies": {
     "ws": "^8.18.0"
@@ -68,13 +68,9 @@
   "author": "Alan2Z",
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.7",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "peerDependenciesMeta": {
-    "@deepseek-ai/dsh-settings": {
-      "optional": true
-    },
     "@deepseek-ai/schemastery": {
       "optional": true
     }