dsh-speak 1.4.0 → 1.5.0

package/README.md

@@ -6,6 +6,8 @@
 
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
+[![npm version](https://img.shields.io/npm/v/dsh-speak)](https://www.npmjs.com/package/dsh-speak)
+
 Let your agent **tell you** when a long task is done — no more staring at the screen.
 
 dsh-speak reads the final assistant reply aloud through system speech synthesis —
@@ -62,6 +64,11 @@ harness event (DSH session event / Claude Code Stop hook / anything)
 
 - **Automatic**: DSH web plugin watches the session event stream and announces the
   final reply (skips reasoning/tool-call narration, merges multi-step messages).
+- **Gets your attention**: announces approval requests (hears "需要你的审批" when
+  the agent is waiting on you) and questions the agent asks via `ask_user_question`.
+- **Bundle auto-registration** (1.3.0): declare the package in `dsh.profile.bundles`
+  and the plugin registers itself via the bundled `cordis.patch.yml` — no manual
+  patch entry needed.
 - **Best-effort**: never throws, never blocks the harness, never breaks a session.
 - **Natural voices**: Windows prefers natural voices — Windows 11 built-in packs,
   or voices registered via NaturalVoiceSAPIAdapter on Windows 10 (e.g. Xiaoxiao);
@@ -240,12 +247,27 @@ Engine parameters (see [docs/DESIGN.md](docs/DESIGN.md#5-configuration-reference
 speak.ps1 -Text "…" -Volume 50 -Rate 1 -MaxChars 300 -LongTextMessage "本次播报内容较长，请自行阅读。"
 ```
 
-DSH plugin environment variables:
+DSH plugin configuration — **prefer the profile patch `config` block** (visible in
+`dsh --dump-config`, per-profile, survives npm updates):
+
+```yaml
+# ~/.dsh/profiles/web/cordis.patch.yml
+- insert:
+    - id: speech-hook
+      name: 'dsh-speak'
+      config:
+        throttleMs: 1500        # merge delay before announcing (ms)
+        engine: ''              # engine path override; '' = auto-resolve
+        announceApprovals: true # speak approval requests
+        announceQuestions: true # speak ask_user_question content
+        stripApprovalPrefix: true  # strip the "escalate sandbox to ...: " prefix
+        longTextMode: message   # message | heading (speak largest md heading)
+        maxChars: 300           # engine per-utterance ceiling
+        volume: 50              # Windows only
+        rate: 0                 # 0 = engine default (Windows SAPI scale / macOS wpm)
+```
 
-| var | default | meaning |
-| --- | ------- | ------- |
-| `DSH_SPEAK_ENGINE` | empty (auto-resolved) | engine path override; otherwise resolved as `<package>/engine/<platform script>` → `~/.dsh/hooks/<platform script>` (Windows `speak.ps1` / macOS `speak.sh`) |
-| `DSH_SPEAK_THROTTLE_MS` | `1500` | merge delay before announcing |
+See [docs/CUSTOMIZATION.md](docs/CUSTOMIZATION.md) for the full customization guide.
 
 ## Customizing (survives npm updates)
 
@@ -259,20 +281,24 @@ You can tune behavior without forking, and your changes **survive `npm update`**
    Copy-Item "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-speak\engine\speak.ps1" "$env:USERPROFILE\.dsh\hooks\my-speak.ps1"
    # macOS
    cp ~/.dsh/profiles/web/node_modules/dsh-speak/engine/speak.sh ~/.dsh/hooks/my-speak.sh
-   # edit my-speak.ps1 / my-speak.sh to taste, then point the plugin at it:
-   setx DSH_SPEAK_ENGINE "$env:USERPROFILE\.dsh\hooks\my-speak.ps1"     # Windows
-   echo 'export DSH_SPEAK_ENGINE=~/.dsh/hooks/my-speak.sh' >> ~/.zshrc  # macOS
    ```
 
-   The plugin resolves the engine as `DSH_SPEAK_ENGINE` → package engine → `~/.dsh/hooks/`,
-   so your copy wins. `npm update` only touches the package — your engine stays.
+   Then point the plugin at your copy in the `config` block:
+
+   ```yaml
+   - insert:
+       - id: speech-hook
+         name: 'dsh-speak'
+         config:
+           engine: 'C:/Users/<you>/.dsh/hooks/my-speak.ps1'   # or ~/.dsh/hooks/my-speak.sh on macOS
+   ```
 
-2. **Environment variables** (no code changes): `DSH_SPEAK_ENGINE` (engine path),
-   `DSH_SPEAK_THROTTLE_MS` (announcement merge delay).
+   The plugin resolves the engine as `config.engine` → package engine → `~/.dsh/hooks/`,
+   so your copy wins. `npm update` only touches the package — your engine stays.
 
-3. **Edit the file inside `node_modules`** — works, but the next `npm update` overwrites it.
+2. **Edit the file inside `node_modules`** — works, but the next `npm update` overwrites it.
 
-4. **Fork the repo** — full control, publish your own package if you want.
+3. **Fork the repo** — full control, publish your own package if you want.
 
 ## Troubleshooting
 

package/README.zh-CN.md

@@ -4,6 +4,8 @@
 
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
 
+[![npm version](https://img.shields.io/npm/v/dsh-speak)](https://www.npmjs.com/package/dsh-speak)
+
 让 Agent 在长任务完成时**开口告诉你**——不用再盯着屏幕等。
 
 dsh-speak 通过系统语音合成把 Agent 的最终回复朗读出来——Windows 上优先使用自然
@@ -58,6 +60,10 @@ harness 事件（DSH 会话事件 / Claude Code Stop hook / 任意方式）
 
 - **全自动**：DSH web 插件监听会话事件流，自动播报最终回复
   （跳过 reasoning/工具调用旁白，合并同一回复的多步消息）。
+- **提醒你**：审批请求（Agent 等你操作时会播"需要你的审批"）和 Agent 通过
+  `ask_user_question` 提出的问题都会播报。
+- **Bundle 自动注册**（1.3.0）：把包声明进 `dsh.profile.bundles`，插件通过包内
+  自带的 `cordis.patch.yml` 自动注册，无需手动写 patch 条目。
 - **尽力而为**：绝不抛错、绝不阻塞 harness、绝不破坏会话。
 - **自然语音**：Windows 优先使用自然语音——Windows 11 内置语音包，或 Windows 10
   上经 NaturalVoiceSAPIAdapter 注册的语音（如晓晓）；macOS 使用系统朗读声音
@@ -225,12 +231,26 @@ powershell -NoProfile -ExecutionPolicy Bypass -File engine\speech-prompt.ps1 -Te
 speak.ps1 -Text "…" -Volume 50 -Rate 1 -MaxChars 300 -LongTextMessage "本次播报内容较长，请自行阅读。"
 ```
 
-DSH 插件环境变量：
+DSH 插件配置——**优先用 profile patch 的 `config` 块**（`dsh --dump-config` 可见、按 profile 隔离、升级不丢）：
+
+```yaml
+# ~/.dsh/profiles/web/cordis.patch.yml
+- insert:
+    - id: speech-hook
+      name: 'dsh-speak'
+      config:
+        throttleMs: 1500        # 播报前的合并延迟（毫秒）
+        engine: ''              # 引擎路径覆盖；'' = 自动解析
+        announceApprovals: true # 播报审批请求
+        announceQuestions: true # 播报 ask_user_question 提问内容
+        stripApprovalPrefix: true  # 剥离审批原因里的 "escalate sandbox to ...: " 前缀
+        longTextMode: message   # message | heading（念最大字号 markdown 标题）
+        maxChars: 300           # 引擎单次朗读字数上限
+        volume: 50              # 仅 Windows
+        rate: 0                 # 0 = 引擎默认（Windows SAPI 刻度 / macOS wpm）
+```
 
-| 变量 | 默认值 | 含义 |
-| --- | ------- | ---- |
-| `DSH_SPEAK_ENGINE` | 空（自动解析） | 引擎路径覆盖；否则按"包内 `engine/<平台脚本>` → `~/.dsh/hooks/<平台脚本>`"顺序解析（Windows `speak.ps1` / macOS `speak.sh`） |
-| `DSH_SPEAK_THROTTLE_MS` | `1500` | 播报前的合并延迟（毫秒） |
+完整自定义指南见 [docs/CUSTOMIZATION.md](docs/CUSTOMIZATION.zh-CN.md)。
 
 ## 自定义（升级不丢）
 
@@ -243,19 +263,24 @@ DSH 插件环境变量：
    Copy-Item "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-speak\engine\speak.ps1" "$env:USERPROFILE\.dsh\hooks\my-speak.ps1"
    # macOS
    cp ~/.dsh/profiles/web/node_modules/dsh-speak/engine/speak.sh ~/.dsh/hooks/my-speak.sh
-   # 按喜好编辑 my-speak.ps1 / my-speak.sh，然后让插件指向它：
-   setx DSH_SPEAK_ENGINE "$env:USERPROFILE\.dsh\hooks\my-speak.ps1"     # Windows
-   echo 'export DSH_SPEAK_ENGINE=~/.dsh/hooks/my-speak.sh' >> ~/.zshrc  # macOS
    ```
 
-   插件按 `DSH_SPEAK_ENGINE` → 包内引擎 → `~/.dsh/hooks/` 的顺序解析引擎，所以你的副本
-   优先生效；`npm update` 只动包本身，你的引擎安然无恙。
+   然后在 config 块里指向你的副本：
+
+   ```yaml
+   - insert:
+       - id: speech-hook
+         name: 'dsh-speak'
+         config:
+           engine: 'C:/Users/<你>/.dsh/hooks/my-speak.ps1'   # macOS 用 ~/.dsh/hooks/my-speak.sh
+   ```
 
-2. **环境变量**（零改代码）：`DSH_SPEAK_ENGINE`（引擎路径）、`DSH_SPEAK_THROTTLE_MS`（播报合并延迟）。
+   插件按 `config.engine` → 包内引擎 → `~/.dsh/hooks/` 的顺序解析引擎，所以你的副本
+   优先生效；`npm update` 只动包本身，你的引擎安然无恙。
 
-3. **直接改 `node_modules` 里的文件**——能改，但下次 `npm update` 会被覆盖。
+2. **直接改 `node_modules` 里的文件**——能改，但下次 `npm update` 会被覆盖。
 
-4. **fork 仓库**——完全掌控，想发自己的包也行。
+3. **fork 仓库**——完全掌控，想发自己的包也行。
 
 ## 排障
 

package/adapters/dsh/speech-hook.js

@@ -8,12 +8,11 @@
 // Trigger semantics:
 //   * only events with a `text` block are announced (reasoning / tool_use blocks
 //     are skipped)
-//   * when a tool/call event arrives, that round's assistant text is treated as
-//     process narration, so any pending announcement is cancelled — EXCEPT a
-//     call to `ask_user_question`, which is a question for the user and keeps
-//     the pending text so it is announced
-//   * `approval/asked` is announced immediately (approval reason, or a fixed
-//     prompt) since approvals are time-sensitive
+//   * a tool/call to `ask_user_question` announces the parsed question
+//     (title + single/multi + options); other tool calls cancel the pending
+//     announcement (that round's assistant text is process narration)
+//   * `approval/asked` is announced immediately (reason with the fixed English
+//     template prefix stripped, or a fixed prompt)
 //   * a final reply with no following tool/call is announced after a throttle
 //     delay (merges multi-step messages from the same reply)
 //
@@ -24,11 +23,20 @@
 //         name: 'file:///C:/Users/<your-username>/.../speech-hook.js'   # repo/file install (replace <your-username>)
 // (run adapters/dsh/install.ps1 to do this automatically for the file install)
 //
-// Configuration (environment variables, optional):
-//   DSH_SPEAK_ENGINE      path to the engine script (speak.ps1 / speak.sh)
-//                         (default: <package>/engine/<platform script>, then
-//                          ~/.dsh/hooks/<platform script>)
-//   DSH_SPEAK_THROTTLE_MS throttle delay before announcing (default: 1500)
+// Configuration — prefer the profile patch `config` block (see docs/CUSTOMIZATION.md):
+//   - insert:
+//       - id: speech-hook
+//         name: 'dsh-speak'
+//         config:
+//           throttleMs: 1500        # merge delay before announcing (ms)
+//           engine: ''              # engine path override; '' = auto-resolve
+//           announceApprovals: true # speak approval requests
+//           announceQuestions: true # speak ask_user_question content
+//           stripApprovalPrefix: true  # strip "escalate sandbox to ...: " prefix
+//           longTextMode: message   # message | heading (speak largest md heading)
+//           maxChars: 300           # engine per-utterance ceiling
+//           volume: 50              # Windows only
+//           rate: 0                 # 0 = engine default (Windows SAPI scale / macOS wpm)
 'use strict'
 const { spawn } = require('child_process')
 const fs = require('fs')
@@ -43,27 +51,40 @@ function log(...args) {
   } catch (e) { /* ignore */ }
 }
 
-const THROTTLE_MS = Number(process.env.DSH_SPEAK_THROTTLE_MS) || 1500
 const ENGINE_NAME = process.platform === 'darwin' ? 'speak.sh' : 'speak.ps1'
 
 /**
  * Locate the engine script:
- *   1. explicit DSH_SPEAK_ENGINE override
+ *   1. explicit override (config `engine`)
  *   2. <this package>/engine/<speak.ps1|speak.sh> — works both when running from
  *      a repo checkout and when installed into a profile's node_modules
  *   3. legacy file-copy location (~/.dsh/hooks/<speak.ps1|speak.sh>)
  */
-function resolveEngine() {
-  if (process.env.DSH_SPEAK_ENGINE) return process.env.DSH_SPEAK_ENGINE
+function resolveEngine(override) {
+  if (override) return override
   const bundled = path.join(__dirname, '..', '..', 'engine', ENGINE_NAME)
   if (fs.existsSync(bundled)) return bundled
   return path.join(os.homedir(), '.dsh', 'hooks', ENGINE_NAME)
 }
-const SPEAK_ENGINE = resolveEngine()
 
 module.exports = {
-  apply(ctx) {
-    log('plugin apply 执行（加载成功）; engine=', SPEAK_ENGINE, '; throttle=', THROTTLE_MS)
+  apply(ctx, config) {
+    config = config || {}
+    // resolved settings: config > default
+    const cfg = {
+      throttleMs: Number(config.throttleMs != null ? config.throttleMs : 1500) || 1500,
+      engine: resolveEngine(config.engine || ''),
+      announceApprovals: config.announceApprovals !== false,
+      announceQuestions: config.announceQuestions !== false,
+      stripApprovalPrefix: config.stripApprovalPrefix !== false,
+      longTextMode: config.longTextMode || 'message',
+      maxChars: Number(config.maxChars != null ? config.maxChars : 300) || 300,
+      volume: Number(config.volume != null ? config.volume : 50) || 50,
+      rate: Number(config.rate != null ? config.rate : 0) || 0,
+    }
+    log('plugin apply 执行（加载成功）; engine=', cfg.engine, '; throttle=', cfg.throttleMs,
+      '; longTextMode=', cfg.longTextMode, '; maxChars=', cfg.maxChars)
+
     let timer = null
     let pendingText = ''
 
@@ -86,11 +107,18 @@ module.exports = {
       let ps
       if (process.platform === 'darwin') {
         // macOS: run the say-based engine through bash
-        ps = spawn('/bin/bash', [SPEAK_ENGINE, '-f', tmp], { stdio: 'ignore' })
-        log('spawn bash (macOS engine) 已发起')
+        const args = ['-f', tmp, '-m', String(cfg.maxChars), '-M', cfg.longTextMode]
+        if (cfg.rate > 0) args.push('-r', String(cfg.rate))
+        ps = spawn('/bin/bash', [cfg.engine].concat(args), { stdio: 'ignore' })
+        log('spawn bash (macOS engine) 已发起:', args.join(' '))
       } else {
         ps = spawn('powershell.exe',
-          ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', SPEAK_ENGINE, '-File', tmp],
+          ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', cfg.engine,
+            '-File', tmp,
+            '-Volume', String(cfg.volume),
+            '-Rate', String(cfg.rate > 0 ? cfg.rate : 1),
+            '-MaxChars', String(cfg.maxChars),
+            '-LongTextMode', cfg.longTextMode],
           { windowsHide: true, stdio: 'ignore' })
         log('spawn powershell 已发起')
       }
@@ -105,14 +133,31 @@ module.exports = {
         if (type !== 'assistant/chunk') {
           log('事件 type=', type, 'surfaceOp=', event && event.surfaceOp, 'seq=', event && event.seq)
         }
-        // tool-call round: a call to ask_user_question is a question to the
-        // user — keep the pending text so it gets announced (the user should
-        // hear the question); any other tool call cancels the pending
-        // announcement (that round's assistant text is process narration)
+        // tool-call round: a call to ask_user_question announces the parsed
+        // question (title + mode + options); any other tool call cancels the
+        // pending announcement (that round's assistant text is narration)
         if (type === 'tool/call') {
           const toolName = event.data && event.data.name
-          if (toolName === 'ask_user_question') {
-            log('提问工具调用（ask_user_question）— 保留待播报文本')
+          if (toolName === 'ask_user_question' && cfg.announceQuestions) {
+            let spoken = ''
+            try {
+              const args = JSON.parse((event.data && event.data.arguments) || '{}')
+              const qs = Array.isArray(args.questions) ? args.questions : []
+              spoken = qs.map((q) => {
+                const mode = q.multi_select ? '多选' : '单选'
+                const labels = Array.isArray(q.options)
+                  ? q.options.map((o) => o.label).filter(Boolean).join('、')
+                  : ''
+                return (q.question || '') + '（' + mode + '）' + (labels ? '，选项：' + labels : '')
+              }).filter(Boolean).join('；')
+            } catch (e) { /* arguments 解析失败则回退原逻辑 */ }
+            if (spoken) {
+              cancelPending()
+              log('提问播报:', spoken.slice(0, 120))
+              speak(spoken)
+            } else {
+              log('提问工具调用（ask_user_question）— 保留待播报文本')
+            }
             return
           }
           cancelPending()
@@ -120,10 +165,15 @@ module.exports = {
         }
         // approval requested: announce it right away (time-sensitive), using
         // the approval reason if present
-        if (type === 'approval/asked') {
+        if (type === 'approval/asked' && cfg.announceApprovals) {
           cancelPending()
-          const reason = event.data && event.data.reason
-          const text = reason && reason.trim() ? reason : '需要你的审批，请查看界面。'
+          let reason = (event.data && event.data.reason) || ''
+          if (cfg.stripApprovalPrefix) {
+            // strip the fixed English template prefix (e.g. "escalate sandbox
+            // to danger-full-access: "), keep the human explanation
+            reason = reason.replace(/^escalate sandbox to danger-full-access\s*:\s*/i, '').trim()
+          }
+          const text = reason || '需要你的审批，请查看界面。'
           log('审批请求，播报:', text.slice(0, 60))
           speak(text)
           return
@@ -154,7 +204,7 @@ module.exports = {
           speak(pendingText)
           pendingText = ''
           timer = null
-        }, THROTTLE_MS)
+        }, cfg.throttleMs)
       } catch (e) {
         log('事件处理异常:', e.message)
       }

package/docs/CUSTOMIZATION.md

@@ -0,0 +1,89 @@
+# CUSTOMIZATION.md — customizing dsh-speak
+
+(中文版：docs/CUSTOMIZATION.zh-CN.md)
+
+dsh-speak is deliberately small, but it exposes three levels of customization:
+**configuration** (no code), **engine override** (copy & edit), and **extension**
+(new backends / adapters). Everything below survives `npm update`.
+
+---
+
+## 1. Configuration (recommended)
+
+Set options in the profile patch `config` block — visible in
+`dsh --dump-config`, per-profile, and never overwritten by npm:
+
+```yaml
+# ~/.dsh/profiles/web/cordis.patch.yml
+- insert:
+    - id: speech-hook
+      name: 'dsh-speak'
+      config:
+        throttleMs: 1500        # merge delay before announcing (ms)
+        engine: ''              # engine path override; '' = auto-resolve
+        announceApprovals: true # speak approval requests
+        announceQuestions: true # speak ask_user_question content
+        stripApprovalPrefix: true  # strip "escalate sandbox to ...: " prefix
+        longTextMode: message   # message | heading (speak largest md heading)
+        maxChars: 300           # engine per-utterance ceiling
+        volume: 50              # Windows only
+        rate: 0                 # 0 = engine default (Windows SAPI scale / macOS wpm)
+```
+
+### Option reference
+
+| option | default | effect |
+| ------ | ------- | ------ |
+| `throttleMs` | `1500` | how long a reply's text waits before being announced (merges multi-step messages) |
+| `engine` | `''` | explicit engine script path; `''` auto-resolves: `<package>/engine/<platform>` → `~/.dsh/hooks/<platform>` |
+| `announceApprovals` | `true` | announce `approval/asked` events (reason, or the fixed prompt) |
+| `announceQuestions` | `true` | announce `ask_user_question` calls as "question（单选/多选），选项：…" |
+| `stripApprovalPrefix` | `true` | strip the fixed English template prefix (`escalate sandbox to danger-full-access: `) from approval reasons, keeping the human explanation |
+| `longTextMode` | `message` | `message` = fixed prompt for over-long text; `heading` = speak the largest markdown heading instead (see below) |
+| `maxChars` | `300` | engine per-utterance ceiling (SAPI/NVSAPIAdapter fails silently beyond ~375-470) |
+| `volume` | `50` | Windows only (0-100); macOS volume follows the system |
+| `rate` | `0` | `0` = engine default (Windows SAPI scale, e.g. 1; macOS words-per-minute, e.g. 175) |
+
+### Long-text modes
+
+When cleaned text exceeds `maxChars`:
+
+- **`message`** (default): speak `LongTextMessage` (`本次播报内容较长，请自行阅读。`, overridable via engine param `-LongTextMessage` / `-l`).
+- **`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.
+
+---
+
+## 2. Engine override (copy & edit)
+
+To change what is actually spoken (voice selection, cleaning rules, defaults),
+copy the engine out of the package and point the plugin at your copy:
+
+```powershell
+# Windows
+Copy-Item "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-speak\engine\speak.ps1" "$env:USERPROFILE\.dsh\hooks\my-speak.ps1"
+# macOS
+cp ~/.dsh/profiles/web/node_modules/dsh-speak/engine/speak.sh ~/.dsh/hooks/my-speak.sh
+```
+
+Then set the engine path in config:
+
+```yaml
+config:
+  engine: 'C:/Users/<you>/.dsh/hooks/my-speak.ps1'   # or ~/.dsh/hooks/my-speak.sh on macOS
+```
+
+`npm update` never touches your copy.
+
+---
+
+## 3. Extension
+
+- **New engine backend**: the engine is the single seam. A new backend
+  (`speak-edge.ps1` for edge-tts, `speak-piper.ps1` for a local model, ...) keeps
+  the same parameter contract and cleaning pipeline — adapters never change.
+  See [DESIGN.md §7](DESIGN.md#7-extending).
+- **New harness adapter**: capture the final reply text → call the engine. The
+  DSH (event stream), Claude Code (Stop hook), and agent-called
+  (`speech-summary.ps1`) patterns are the three references.
+- **Your own published variant**: fork this repo, adjust, publish your own npm
+  package — the `dsh.bundle` manifest already makes it `dsh plugin add`-installable.

package/docs/CUSTOMIZATION.zh-CN.md

@@ -0,0 +1,88 @@
+# CUSTOMIZATION.zh-CN.md — dsh-speak 自定义指南
+
+（English: docs/CUSTOMIZATION.md）
+
+dsh-speak 刻意保持小巧，但提供三层自定义：**配置**（不改代码）、**引擎覆盖**（复制后改）、
+**扩展**（新后端 / 新适配器）。以下所有方式都不会被 `npm update` 覆盖。
+
+---
+
+## 一、配置（推荐）
+
+在 profile patch 的 `config` 块里设置——`dsh --dump-config` 可见、按 profile 隔离、
+npm 更新永不覆盖：
+
+```yaml
+# ~/.dsh/profiles/web/cordis.patch.yml
+- insert:
+    - id: speech-hook
+      name: 'dsh-speak'
+      config:
+        throttleMs: 1500        # 播报前的合并延迟（毫秒）
+        engine: ''              # 引擎路径覆盖；'' = 自动解析
+        announceApprovals: true # 播报审批请求
+        announceQuestions: true # 播报 ask_user_question 提问内容
+        stripApprovalPrefix: true  # 剥离审批原因里的 "escalate sandbox to ...: " 前缀
+        longTextMode: message   # message | heading（念最大字号 markdown 标题）
+        maxChars: 300           # 引擎单次朗读字数上限
+        volume: 50              # 仅 Windows
+        rate: 0                 # 0 = 引擎默认（Windows SAPI 刻度 / macOS wpm）
+```
+
+### 选项说明
+
+| 选项 | 默认值 | 效果 |
+| ---- | ------ | ---- |
+| `throttleMs` | `1500` | 回复文本等待多久才播报（合并同一回复的多步消息） |
+| `engine` | `''` | 显式引擎脚本路径；`''` 自动解析：包内 `engine/<平台>` → `~/.dsh/hooks/<平台>` |
+| `announceApprovals` | `true` | 播报 `approval/asked` 事件（审批原因，或固定提示语） |
+| `announceQuestions` | `true` | 把 `ask_user_question` 调用播报成"问题（单选/多选），选项：…" |
+| `stripApprovalPrefix` | `true` | 剥离审批原因里的固定英文模板前缀（`escalate sandbox to danger-full-access: `），保留中文说明 |
+| `longTextMode` | `message` | `message` = 超长念固定提示语；`heading` = 改念最大字号 markdown 标题（规则见下） |
+| `maxChars` | `300` | 引擎单次朗读上限（SAPI/NVSAPIAdapter 超过约 375-470 字会静默失败） |
+| `volume` | `50` | 仅 Windows（0-100）；macOS 音量跟随系统 |
+| `rate` | `0` | `0` = 引擎默认（Windows SAPI 刻度如 1；macOS words-per-minute 如 175） |
+
+### 超长文本模式
+
+清洗后文本超过 `maxChars` 时：
+
+- **`message`**（默认）：念 `LongTextMessage`（`本次播报内容较长，请自行阅读。`，
+  可用引擎参数 `-LongTextMessage` / `-l` 覆盖）。
+- **`heading`**：在原始文本里挑**最大字号**的 markdown 标题——`#` 数量最少者优先，
+  并列取第一个；没有标题行则取第一个非空行。选中的候选仍会清洗并受 `maxChars`
+  上限约束，若其本身仍超长则回退提示语。
+
+---
+
+## 二、引擎覆盖（复制后改）
+
+想改"实际念出来的内容"（音色选择、清洗规则、默认参数），把引擎复制出包并指向你的副本：
+
+```powershell
+# Windows
+Copy-Item "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-speak\engine\speak.ps1" "$env:USERPROFILE\.dsh\hooks\my-speak.ps1"
+# macOS
+cp ~/.dsh/profiles/web/node_modules/dsh-speak/engine/speak.sh ~/.dsh/hooks/my-speak.sh
+```
+
+然后在 config 里设引擎路径：
+
+```yaml
+config:
+  engine: 'C:/Users/<你>/.dsh/hooks/my-speak.ps1'   # macOS 用 ~/.dsh/hooks/my-speak.sh
+```
+
+`npm update` 永远不会碰你的副本。
+
+---
+
+## 三、扩展
+
+- **新引擎后端**：引擎是唯一接缝。新后端（`speak-edge.ps1` 封装 edge-tts、
+  `speak-piper.ps1` 接本地模型……）保持同样的参数契约与清洗管线——适配层不用改。
+  见 [DESIGN.zh-CN.md §7](DESIGN.zh-CN.md#7-扩展)。
+- **新 harness 适配层**：拿到最终回复文本 → 调引擎。DSH（事件流）、Claude Code
+  （Stop hook）、Agent 自调用（`speech-summary.ps1`）是三种参考范式。
+- **发布自己的变体**：fork 本仓库、按需调整、发布自己的 npm 包——`dsh.bundle`
+  manifest 已让它天然支持 `dsh plugin add` 安装。

package/docs/DESIGN.md

@@ -168,13 +168,24 @@ returns immediately. (Async spawning is safe here — the nested-spawn restricti
 | `-Rate`           | `1`                         | speech rate (SAPI scale)                 |
 | `-MaxChars`       | `300`                       | beyond this, replaced by `LongTextMessage` |
 | `-LongTextMessage`| `本次播报内容较长，请自行阅读。` | spoken instead of over-long text         |
+| `-LongTextMode`   | `message`                    | `message` (fixed prompt) \| `heading` (speak the largest markdown heading) |
 
-### DSH plugin (environment variables)
+### DSH plugin (profile `config` — recommended; env vars are legacy fallbacks)
 
-| var                  | default                                  | meaning                        |
-| -------------------- | ---------------------------------------- | ------------------------------ |
-| `DSH_SPEAK_ENGINE`   | empty (auto-resolved)                    | engine path override; otherwise resolved as `<package>/engine/<platform script>` → `~/.dsh/hooks/<platform script>` (Windows: `speak.ps1`, macOS: `speak.sh`) |
-| `DSH_SPEAK_THROTTLE_MS` | `1500`                                | merge delay before announcing  |
+```yaml
+config:
+  throttleMs: 1500
+  engine: ''                 # '' = auto-resolve
+  announceApprovals: true
+  announceQuestions: true
+  stripApprovalPrefix: true
+  longTextMode: message      # message | heading
+  maxChars: 300
+  volume: 50                 # Windows only
+  rate: 0                    # 0 = engine default
+```
+
+Full guide: docs/CUSTOMIZATION.md.
 
 ## 6. Pitfalls (hard-won; do not "fix" casually)
 
@@ -227,7 +238,7 @@ dependencies in the profile). This repository is prepared for that path:
 
 `speech-hook.js` locates `engine/speak.ps1` in this order:
 
-1. `DSH_SPEAK_ENGINE` environment override;
+1. `config.engine` override;
 2. `<package>/engine/speak.ps1` resolved relative to the plugin file — covers
    both a repo checkout and `node_modules/dsh-speak/` after `npm install`;
 3. legacy `%USERPROFILE%\.dsh\hooks\speak.ps1` (the file-install location).

package/docs/DESIGN.zh-CN.md

@@ -155,13 +155,24 @@ Claude Code *确实*有 Stop hook。hook JSON（含 `transcript_path`）从 stdi
 | `-Rate` | `1` | 语速（SAPI 刻度） |
 | `-MaxChars` | `300` | 超过此长度时替换为 `LongTextMessage` |
 | `-LongTextMessage` | `本次播报内容较长，请自行阅读。` | 超长文本时改念这句 |
+| `-LongTextMode` | `message` | `message`（固定提示语）\| `heading`（念最大字号 markdown 标题） |
 
-### DSH 插件（环境变量）
+### DSH 插件（profile `config` —— 推荐）
 
-| 变量 | 默认值 | 含义 |
-| ---- | ------ | ---- |
-| `DSH_SPEAK_ENGINE` | 空（自动解析） | 引擎路径覆盖；否则按"包内 `engine/<平台脚本>` → `~/.dsh/hooks/<平台脚本>`"顺序解析（Windows 为 `speak.ps1`，macOS 为 `speak.sh`） |
-| `DSH_SPEAK_THROTTLE_MS` | `1500` | 播报前的合并延迟（毫秒） |
+```yaml
+config:
+  throttleMs: 1500
+  engine: ''                 # '' = 自动解析
+  announceApprovals: true
+  announceQuestions: true
+  stripApprovalPrefix: true
+  longTextMode: message      # message | heading
+  maxChars: 300
+  volume: 50                 # 仅 Windows
+  rate: 0                    # 0 = 引擎默认
+```
+
+完整指南：docs/CUSTOMIZATION.zh-CN.md。
 
 ## 6. 踩坑记录（来之不易；不要随意"修复"）
 
@@ -212,7 +223,7 @@ DSH 的插件机制基于 Cordis，官方安装树外插件的路径是
 
 `speech-hook.js` 按以下顺序定位 `engine/speak.ps1`：
 
-1. `DSH_SPEAK_ENGINE` 环境变量覆盖；
+1. `config.engine` 覆盖；
 2. 相对插件文件解析 `<包>/engine/speak.ps1`——同时覆盖仓库检出和
    `npm install` 后的 `node_modules/dsh-speak/`；
 3. 旧的 `%USERPROFILE%\.dsh\hooks\speak.ps1`（文件安装的位置）。

package/engine/speak.ps1

@@ -29,7 +29,9 @@ param(
     [int]$Volume = 50,
     [int]$Rate = 1,
     [int]$MaxChars = 300,
-    [string]$LongTextMessage = '本次播报内容较长，请自行阅读。'
+    [string]$LongTextMessage = '本次播报内容较长，请自行阅读。',
+    [ValidateSet('message', 'heading')]
+    [string]$LongTextMode = 'message'
 )
 
 # ---------- input: pick text source ----------
@@ -41,6 +43,29 @@ if ($File) {
 }
 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).
+if ($text.Length -gt $MaxChars -and $LongTextMode -eq 'heading') {
+    $candidate = ''
+    $bestLevel = 7
+    $firstNonEmpty = ''
+    foreach ($line in ($text -split "`n")) {
+        if ($line -match '^\s*#{1,6}\s+') {
+            $level = ([regex]::Match($line, '^(\s*)(#+)')).Groups[2].Value.Length
+            if ($level -lt $bestLevel) {
+                $bestLevel = $level
+                $candidate = $line -replace '^\s*#+\s*', ''
+            }
+        } elseif (-not $firstNonEmpty -and $line.Trim()) {
+            $firstNonEmpty = $line
+        }
+    }
+    if (-not $candidate) { $candidate = $firstNonEmpty }
+    if ($candidate) { $text = $candidate }
+}
+
 # ---------- clean: markdown -> plain speech text ----------
 # code blocks, inline code, markdown links, bare URLs, emphasis/marker chars
 $text = $text -replace '```[\s\S]*?```', ' '
@@ -54,7 +79,7 @@ $text = [regex]::Replace($text, '[^一-龥　-〿＀-￯ - -~]', '')
 $text = $text -replace '\s+', ' '
 $text = $text.Trim()
 
-# ---------- length guard: adapter per-Speak ceiling ----------
+# ---------- final ceiling (also catches over-long heading candidates) ----------
 if ($text.Length -gt $MaxChars) { $text = $LongTextMessage }
 
 # ---------- speak ----------

package/engine/speak.sh

@@ -37,13 +37,14 @@ VOICE=""
 RATE=175          # words per minute (say default)
 MAX_CHARS=300
 LONG_MSG="本次播报内容较长，请自行阅读。"
+LONG_MODE="message"   # message | heading
 
 usage() {
-  echo "usage: speak.sh [-t text | -f file] [-v voice] [-r wpm] [-m maxchars] [-l longmsg]" >&2
+  echo "usage: speak.sh [-t text | -f file] [-v voice] [-r wpm] [-m maxchars] [-l longmsg] [-M message|heading]" >&2
   exit 1
 }
 
-while getopts "t:f:v:r:m:l:h" opt; do
+while getopts "t:f:v:r:m:l:M:h" opt; do
   case "$opt" in
     t) TEXT="$OPTARG" ;;
     f) FILE="$OPTARG" ;;
@@ -51,6 +52,7 @@ while getopts "t:f:v:r:m:l:h" opt; do
     r) RATE="$OPTARG" ;;
     m) MAX_CHARS="$OPTARG" ;;
     l) LONG_MSG="$OPTARG" ;;
+    M) LONG_MODE="$OPTARG" ;;
     h) usage ;;
     *) usage ;;
   esac
@@ -63,6 +65,26 @@ if [ -n "$FILE" ]; then
 fi
 if [ -z "$TEXT" ]; then exit 0; fi
 
+# ---------- length guard / long-text mode ----------
+# '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).
+if [ "${#TEXT}" -gt "$MAX_CHARS" ] && [ "$LONG_MODE" = "heading" ]; then
+  TEXT=$(printf '%s' "$TEXT" | /usr/bin/perl -CSD -e '
+    my $best = 7; my $cand = ""; my $first = "";
+    while (<STDIN>) {
+      if (/^[ \t]*(\#{1,6})[ \t]+(.*)$/) {
+        my $n = length($1);
+        if ($n < $best) { $best = $n; $cand = $2; }
+      } elsif ($first eq "" && /\S/) {
+        $first = $_;
+      }
+    }
+    $cand = $first if $cand eq "";
+    print $cand;
+  ')
+fi
+
 # ---------- clean (mirrors speak.ps1) ----------
 TEXT=$(printf '%s' "$TEXT" | /usr/bin/perl -CSD -pe '
   s/```[\s\S]*?```/ /g;          # code blocks
@@ -75,7 +97,7 @@ TEXT=$(printf '%s' "$TEXT" | /usr/bin/perl -CSD -pe '
 ')
 TEXT=$(printf '%s' "$TEXT" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
 
-# ---------- length guard ----------
+# ---------- final ceiling (also catches over-long heading candidates) ----------
 if [ "${#TEXT}" -gt "$MAX_CHARS" ]; then
   TEXT="$LONG_MSG"
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-speak",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Make your AI harness speak — verified voice announcements for DSH and other AI coding harnesses (Windows SAPI5 + macOS system voices)",
   "main": "adapters/dsh/speech-hook.js",
   "files": [