dsh-speak 1.2.0 → 1.4.0

package/README.md

@@ -4,6 +4,8 @@
 
 ![鲸鱼娘大喇叭](鲸鱼娘大喇叭.png)
 
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
 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 —
@@ -245,6 +247,33 @@ DSH plugin environment variables:
 | `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 |
 
+## Customizing (survives npm updates)
+
+You can tune behavior without forking, and your changes **survive `npm update`**:
+
+1. **Copy the engine out and edit it** (recommended — this is where defaults live: volume,
+   rate, `MaxChars`, `LongTextMessage`, voice logic):
+
+   ```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
+   # 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.
+
+2. **Environment variables** (no code changes): `DSH_SPEAK_ENGINE` (engine path),
+   `DSH_SPEAK_THROTTLE_MS` (announcement merge delay).
+
+3. **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.
+
 ## Troubleshooting
 
 | symptom | cause | fix |

package/README.zh-CN.md

@@ -2,6 +2,8 @@
 
 ![鲸鱼娘大喇叭](鲸鱼娘大喇叭.png)
 
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
 让 Agent 在长任务完成时**开口告诉你**——不用再盯着屏幕等。
 
 dsh-speak 通过系统语音合成把 Agent 的最终回复朗读出来——Windows 上优先使用自然
@@ -230,6 +232,31 @@ DSH 插件环境变量：
 | `DSH_SPEAK_ENGINE` | 空（自动解析） | 引擎路径覆盖；否则按"包内 `engine/<平台脚本>` → `~/.dsh/hooks/<平台脚本>`"顺序解析（Windows `speak.ps1` / macOS `speak.sh`） |
 | `DSH_SPEAK_THROTTLE_MS` | `1500` | 播报前的合并延迟（毫秒） |
 
+## 自定义（升级不丢）
+
+想调行为又不想 fork，而且改完**不会被 `npm update` 覆盖**：
+
+1. **把引擎复制出来改**（推荐——默认参数都在这：音量、语速、字数上限、超长提示语、音色逻辑）：
+
+   ```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
+   # 按喜好编辑 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` 只动包本身，你的引擎安然无恙。
+
+2. **环境变量**（零改代码）：`DSH_SPEAK_ENGINE`（引擎路径）、`DSH_SPEAK_THROTTLE_MS`（播报合并延迟）。
+
+3. **直接改 `node_modules` 里的文件**——能改，但下次 `npm update` 会被覆盖。
+
+4. **fork 仓库**——完全掌控，想发自己的包也行。
+
 ## 排障
 
 | 现象 | 原因 | 解决 |

package/adapters/dsh/speech-hook.js

@@ -9,7 +9,11 @@
 //   * 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
+//     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 final reply with no following tool/call is announced after a throttle
 //     delay (merges multi-step messages from the same reply)
 //
@@ -101,12 +105,29 @@ module.exports = {
         if (type !== 'assistant/chunk') {
           log('事件 type=', type, 'surfaceOp=', event && event.surfaceOp, 'seq=', event && event.seq)
         }
-        // tool-call round: cancel pending announcement (that round's assistant
-        // text is process narration, not the final reply)
+        // 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)
         if (type === 'tool/call') {
+          const toolName = event.data && event.data.name
+          if (toolName === 'ask_user_question') {
+            log('提问工具调用（ask_user_question）— 保留待播报文本')
+            return
+          }
           cancelPending()
           return
         }
+        // approval requested: announce it right away (time-sensitive), using
+        // the approval reason if present
+        if (type === 'approval/asked') {
+          cancelPending()
+          const reason = event.data && event.data.reason
+          const text = reason && reason.trim() ? reason : '需要你的审批，请查看界面。'
+          log('审批请求，播报:', text.slice(0, 60))
+          speak(text)
+          return
+        }
         if (!event || type !== 'assistant/message') return
         if (event.surfaceOp && event.surfaceOp !== 'append') return
         // the message object lives at event.data.message (event.data wraps { turn, step, message })

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-speak bundle patch: auto-register the speech-hook plugin when this package
+# is used as a DSH bundle (declared in dsh.profile.bundles).
+- insert:
+    - id: speech-hook
+      name: dsh-speak

package/docs/DESIGN.md

@@ -147,12 +147,14 @@ returns immediately. (Async spawning is safe here — the nested-spawn restricti
 
 ## 4. Event-flow truth table (DSH)
 
-| assistant round contains        | announced? |
-| ------------------------------- | ----------- |
-| final text reply, no tool call  | ✅ after throttle |
-| text + tool/call(s)             | ❌ (cancelled — narration) |
-| reasoning only, no text         | ❌ (no text block) |
-| streaming chunks                | ❌ (filtered) |
+| assistant round / event          | announced? |
+| -------------------------------- | ----------- |
+| final text reply, no tool call   | ✅ after throttle |
+| text + tool/call(s)              | ❌ (cancelled — narration) |
+| text + `ask_user_question` call  | ✅ the question text is kept and announced |
+| `approval/asked`                 | ✅ immediately (reason, else a fixed prompt) |
+| reasoning only, no text          | ❌ (no text block) |
+| streaming chunks                 | ❌ (filtered) |
 
 ## 5. Configuration reference
 

package/docs/DESIGN.zh-CN.md

@@ -134,12 +134,14 @@ Claude Code *确实*有 Stop hook。hook JSON（含 `transcript_path`）从 stdi
 
 ## 4. 事件流真值表（DSH）
 
-| assistant 轮次包含                | 是否播报 |
-| --------------------------------- | -------- |
-| 最终文本回复，无工具调用          | ✅ 节流后播报 |
-| 文本 + tool/call(s)               | ❌（取消——旁白） |
-| 只有 reasoning，无文本            | ❌（无 text 块） |
-| 流式分块                          | ❌（被过滤） |
+| assistant 轮次 / 事件            | 是否播报 |
+| -------------------------------- | -------- |
+| 最终文本回复，无工具调用         | ✅ 节流后播报 |
+| 文本 + tool/call(s)              | ❌（取消——旁白） |
+| 文本 + `ask_user_question` 调用  | ✅ 保留提问文本并播报 |
+| `approval/asked`（审批请求）     | ✅ 立即播报（审批原因，否则固定提示语） |
+| 只有 reasoning，无文本           | ❌（无 text 块） |
+| 流式分块                         | ❌（被过滤） |
 
 ## 5. 配置参考
 

package/package.json

@@ -1,17 +1,23 @@
 {
   "name": "dsh-speak",
-  "version": "1.2.0",
+  "version": "1.4.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": [
     "adapters/dsh/speech-hook.js",
     "adapters/dsh/install.ps1",
+    "cordis.patch.yml",
     "engine/",
     "docs/",
     "README.md",
     "README.zh-CN.md",
     "LICENSE"
   ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
   "keywords": [
     "dsh",
     "dsh-plugin",