dsh-speak 1.5.0 → 1.7.0

package/README.md

@@ -17,55 +17,27 @@ on macOS using the built-in `say` (can follow a Siri natural voice). It was buil
 for [DeepSeek Harness](https://github.com/deepseek-ai/dsh)
 and is structured so any harness can plug in.
 
-> **Project status**: this project exists only to provide an **already-verified
-> solution** for users who want their harness to speak. Barring unexpected
-> circumstances, it will not be updated further.
-
-## TL;DR — install for DSH
-
-1. Install the package into your web profile (pick one):
-
-   ```powershell
-   dsh plugin --profile web add dsh-speak
-   # or, without pnpm:
-   npm install --prefix "$env:USERPROFILE\.dsh\profiles\web" dsh-speak
-   ```
-
-   On macOS (bash):
-
-   ```bash
-   npm install --prefix "$HOME/.dsh/profiles/web" dsh-speak
-   ```
-
-2. Append to `~/.dsh/profiles/web/cordis.patch.yml`:
-
-   ```yaml
-   - insert:
-       - id: speech-hook
-         name: 'dsh-speak'
-   ```
-
-3. Restart the DSH web app — replies are now announced aloud.
-
-> **Let your agent do it?** Paste this repo URL
-> (`https://github.com/Alan2Z/dsh-speak`) into your DSH session and ask it to
-> install the plugin — your agent follows this very README. Approving the
-> out-of-workspace writes (`~/.dsh`) is all that's needed.
-
-```
-harness event (DSH session event / Claude Code Stop hook / anything)
-      │
-      ▼  adapters/…  (harness-specific trigger: filter, throttle, cancel)
-      ▼  engine/speak.ps1 / speak.sh  (harness-agnostic: clean text → SAPI5 / say)
-      ▼  🔊 you hear the final reply
-```
-
 ## Features
 
 - **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`.
+- **Final-reply replay** (1.7.0): every final reply (turn tail) has a 🔊 button
+  in its action bar — click to replay that message, click again to stop, click
+  another to switch. Speech execution stays fully owned by the DSH host (keeps
+  speaking even with the browser closed).
+- **Host speech queue** (1.7.0): only one native speech process runs at a time;
+  queued items continue automatically. A WebSocket syncs the live state (which
+  message is speaking, queue length) to the UI.
+- **Optional event announcements** (1.6.0): turn end, command done, goal changes,
+  tool errors, and todo updates can each be announced, toggled independently
+  (off by default).
+- **Visual configuration** (1.7.0): a dedicated Settings → dsh-speak settings
+  page — every option (master switch, automatic speech, Markdown cleaning, code
+  blocks, event toggles, fixed prompt, …) is editable from the Web UI, no
+  hand-edited YAML.
+- **Master switch** (1.6.0): silence everything with one toggle.
 - **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.
@@ -79,6 +51,20 @@ harness event (DSH session event / Claude Code Stop hook / anything)
 - **Portable engine**: any process can speak with one line:
   Windows `powershell -File speak.ps1 -Text "你好"` / macOS `./speak.sh -t "你好"`.
 
+## How it works
+
+```
+harness event (DSH session event / Claude Code Stop hook / anything)
+      │
+      ▼  adapters/…  (harness-specific trigger: filter, throttle, cancel)
+      ▼  engine/speak.ps1 / speak.sh  (harness-agnostic: clean text → SAPI5 / say)
+      ▼  🔊 you hear the final reply
+```
+
+The adapter turns harness-specific events into engine calls; the engine cleans the
+text and speaks it, fully decoupled from any harness. Full design:
+[docs/DESIGN.md](docs/DESIGN.md).
+
 ## Prerequisites
 
 Windows:
@@ -100,9 +86,9 @@ macOS:
 - Chinese voices: see the [macOS](#macos) section (incl. the Siri natural-voice
   picker and its pitfalls).
 
-## Quick start — DSH
+## Install & quick start
 
-### Option A — npm plugin (recommended)
+### DSH — Option A: npm plugin (recommended)
 
 ```powershell
 # 1. install the plugin into your web profile (adds dsh-speak to
@@ -124,11 +110,22 @@ dsh plugin --profile web add dsh-speak
 > ```powershell
 > npm install --prefix "$env:USERPROFILE\.dsh\profiles\web" dsh-speak
 > ```
+>
+> On macOS (bash):
+>
+> ```bash
+> npm install --prefix "$HOME/.dsh/profiles/web" dsh-speak
+> ```
 
 The engine ships inside the package (`node_modules/dsh-speak/engine/`), so no extra
 copying is needed.
 
-### Option B — file install (no npm needed)
+> **Let your agent do it?** Paste this repo URL
+> (`https://github.com/Alan2Z/dsh-speak`) into your DSH session and ask it to
+> install the plugin — your agent follows this very README. Approving the
+> out-of-workspace writes (`~/.dsh`) is all that's needed.
+
+### DSH — Option B: file install (no npm needed)
 
 ```powershell
 # 1. clone
@@ -152,14 +149,12 @@ What the file installer did:
 | `adapters/dsh/speech-hook.js` | `%USERPROFILE%\.dsh\profiles\web\plugins\` |
 | registration entry | appended to `%USERPROFILE%\.dsh\profiles\web\cordis.patch.yml` (backed up first) |
 
-## macOS
+### macOS
 
 The same adapter runs natively on macOS — the plugin auto-detects the platform and
 calls `engine/speak.sh` (the built-in `say` command) instead of `speak.ps1`.
 **Since 1.2.0 the macOS engine ships in the npm package** — no extra software.
 
-### Install (npm — same as Windows)
-
 ```bash
 # 1. install into your web profile (no pnpm needed — only `dsh plugin` requires it)
 npm install --prefix "$HOME/.dsh/profiles/web" dsh-speak
@@ -169,13 +164,13 @@ npm install --prefix "$HOME/.dsh/profiles/web" dsh-speak
 #        - id: speech-hook
 #          name: 'dsh-speak'
 
-# 3. no restart needed — the patch watcher hot-reloads; pure-text replies are
-#    announced after ~1.5 s (tool-calling replies are intentionally not announced)
+# 3. no restart needed — the patch watcher hot-reloads; replies are announced
+#    after the throttle (~1.5 s); tool-calling replies are announced at turn end
 ```
 
 > With pnpm installed, `dsh plugin --profile web add dsh-speak` works identically.
 
-### Voices (important — two pitfalls)
+#### Voices (important — two pitfalls)
 
 - By default the engine follows the **system reading voice** (*Settings →
   Accessibility → Spoken Content → System Voice*). On **macOS 26** that picker has
@@ -194,7 +189,7 @@ npm install --prefix "$HOME/.dsh/profiles/web" dsh-speak
 - Use `-v Eddy|Flo|Tingting` to force a specific voice (`say -v '?'` lists them).
 - `say` has no volume flag — volume follows the system output volume.
 
-### Test the engine alone (no DSH needed)
+#### Test the engine alone (no DSH needed)
 
 ```bash
 curl -sfL -o ~/speak.sh "https://cdn.jsdelivr.net/gh/Alan2Z/dsh-speak@main/engine/speak.sh"
@@ -203,7 +198,7 @@ chmod +x ~/speak.sh
 ~/speak.sh -t "测试" -v Eddy -r 200              # explicit voice + rate
 ```
 
-## Quick start — Claude Code
+### Claude Code
 
 Register the Stop hook in `~/.claude/settings.json`:
 
@@ -224,7 +219,7 @@ Register the Stop hook in `~/.claude/settings.json`:
 }
 ```
 
-## Quick start — any other harness
+### Any other harness
 
 Call the engine directly from your agent / wrapper / script:
 
@@ -232,7 +227,7 @@ Call the engine directly from your agent / wrapper / script:
 # announce a one-liner
 powershell -NoProfile -ExecutionPolicy Bypass -File engine\speak.ps1 -Text "构建完成"
 
-# announce a long summary (from a file)
+# announce a long summary (blocking, returns when done)
 powershell -NoProfile -ExecutionPolicy Bypass -File engine\speech-summary.ps1 -Text "…"
 
 # ask for user attention (blocking, for prompts/approvals)
@@ -241,14 +236,23 @@ powershell -NoProfile -ExecutionPolicy Bypass -File engine\speech-prompt.ps1 -Te
 
 ## Configuration
 
-Engine parameters (see [docs/DESIGN.md](docs/DESIGN.md#5-configuration-reference)):
+### Engine parameters
+
+See [docs/DESIGN.md §5 configuration reference](docs/DESIGN.md#5-configuration-reference):
 
 ```powershell
 speak.ps1 -Text "…" -Volume 50 -Rate 1 -MaxChars 300 -LongTextMessage "本次播报内容较长，请自行阅读。"
 ```
 
-DSH plugin configuration — **prefer the profile patch `config` block** (visible in
-`dsh --dump-config`, per-profile, survives npm updates):
+### DSH plugin config
+
+**Either way works, and they stay in sync** (both write the same settings
+document):
+
+1. **Web UI (1.7.0, recommended)**: a dedicated Settings → dsh-speak settings
+   page. Every option is editable and saved there (visible in `dsh --dump-config`,
+   per-profile, survives npm updates).
+2. **Profile patch `config` block** (equivalent):
 
 ```yaml
 # ~/.dsh/profiles/web/cordis.patch.yml
@@ -256,18 +260,80 @@ DSH plugin configuration — **prefer the profile patch `config` block** (visibl
     - id: speech-hook
       name: 'dsh-speak'
       config:
+        enabled: true           # master switch: false silences everything
+        automaticSpeech: true   # auto-speak final replies
+        queueAllMessages: false # true = enqueue every assistant message as it arrives
+        replayFullRead: false   # true = manual replay skips the long-text truncation, reads everything
+        cleanMarkdownFormatting: true # convert Markdown to natural speech
+        readInlineCode: true    # read inline code without backticks
+        codeBlocks: smart       # all | smart | replace (fenced code blocks)
+        codeBlockMaxChars: 300  # smart-mode code block character limit
+        codeBlockReplacementText: 'You can see the code in our history.' # replace-mode text
         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
+        stripApprovalPrefix: true  # strip "escalate sandbox to ...: " prefix
+        questionGapMs: 2000      # pause between multiple question announcements (ms)
         longTextMode: message   # message | heading (speak largest md heading)
-        maxChars: 300           # engine per-utterance ceiling
+        longTextMessage: '本次播报内容较长，请自行阅读。' # fixed prompt for message mode
+        maxChars: 300           # per-utterance ceiling (macOS default 0 = unlimited)
         volume: 50              # Windows only
         rate: 0                 # 0 = engine default (Windows SAPI scale / macOS wpm)
+        # —— optional event announcements (1.6.0, all off by default) ——
+        announceTurnEnd: false     # turn/end — "第 N 轮对话完成"
+        announceCommandDone: false # command/done — command finished/failed
+        announceGoalChange: false  # goal/change — goal created/updated/completed
+        announceToolErrors: false  # tool/result error — announce (english dropped)
+        announceTodoWrite: false   # todo/write — todo list updated
 ```
 
-See [docs/CUSTOMIZATION.md](docs/CUSTOMIZATION.md) for the full customization guide.
+> Resolution order: schema default → patch `config` → UI user settings. Fields
+> written in YAML show up in the UI too. Platform note: `maxChars` defaults to
+> 0 on macOS (`say` has no ceiling) and 300 on Windows (SAPI safe limit).
+
+#### Option reference
+
+| option | default | effect |
+| ------ | ------- | ------ |
+| `enabled` | `true` | **master switch**: when off, nothing is ever announced (final reply / approvals / questions / optional events / replay) |
+| `automaticSpeech` | `true` | auto-speak final replies; manual replay always remains available |
+| `queueAllMessages` | `false` | `true` enqueues every assistant message as it arrives (intermediate messages spoken too, FIFO); default only speaks the throttled final reply |
+| `replayFullRead` | `false` | `true` makes manual replay skip the long-text heading truncation (`longTextMode: heading`) and read everything in chunks |
+| `cleanMarkdownFormatting` | `true` | converts Markdown into natural speech text (link labels kept, URLs/heading/emphasis cleaned) |
+| `readInlineCode` | `true` | read inline code without backtick markers |
+| `codeBlocks` | `smart` | fenced code blocks: `all` read / `smart` (read when ≤ `codeBlockMaxChars`) / `replace` with the replacement text |
+| `codeBlockMaxChars` | `300` | code block character limit for `smart` mode |
+| `codeBlockReplacementText` | `You can see the code in our history.` | replacement spoken in `replace` mode (or over-limit `smart`) |
+| `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`: each question spoken separately with a "问题N" prefix (when several) and "选项N" prefixes matching the UI numbering; a `questionGapMs` pause between questions |
+| `questionGapMs` | `2000` | pause between multiple question announcements (ms); 0 = no pause |
+| `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) |
+| `longTextMessage` | `本次播报内容较长，请自行阅读。` | the fixed prompt spoken for over-long text in `message` mode (editable in the UI) |
+| `maxChars` | platform | per-utterance ceiling. **macOS default 0 (`say` has no ceiling); Windows default 300** (SAPI 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) |
+| `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) |
+| `announceTodoWrite` | `false` | announce "待办已更新：n/m 完成" when the agent updates its todos (`todo/write`) |
+
+#### Long-text modes
+
+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.
+
+Full architecture and design rationale: [docs/DESIGN.md](docs/DESIGN.md).
 
 ## Customizing (survives npm updates)
 
@@ -322,10 +388,12 @@ engine/                  harness-agnostic speech engine (PowerShell + SAPI5 / ba
   speech-summary.ps1     blocking reply-summary announcement
 adapters/
   dsh/                   DSH web plugin + one-command installer
-    speech-hook.js       session-event trigger (throttle + tool-call cancel)
+    speech-hook.js       session-event trigger (throttle/cancel + optional events + FIFO speech queue + WebSocket + settings registration)
     install.ps1          copies + registers + backs up
   claude-code/
     stop-hook.ps1        Claude Code Stop hook trigger
+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
 ```

package/README.zh-CN.md

@@ -1,5 +1,7 @@
 # dsh-speak 🔊 — 为 AI 编程 harness 提供语音播报
 
+**中文** · [English](README.md)
+
 ![鲸鱼娘大喇叭](鲸鱼娘大喇叭.png)
 
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
@@ -15,53 +17,23 @@ dsh-speak 通过系统语音合成把 Agent 的最终回复朗读出来——Win
 [DeepSeek Harness](https://github.com/deepseek-ai/dsh) 而生，但结构上
 任何 harness 都能接入。
 
-> **项目定位**：本项目只是为了给想让 harness 开口说话的用户提供一种**已经验证过的方案**；
-> 没有意外的话，后续不会再更新。
-
-## 三分钟安装 — DSH
-
-1. 把包装进你的 web profile（二选一）：
-
-   ```powershell
-   dsh plugin --profile web add dsh-speak
-   # 或（没有 pnpm 时）：
-   npm install --prefix "$env:USERPROFILE\.dsh\profiles\web" dsh-speak
-   ```
-
-   macOS 上（bash）：
-
-   ```bash
-   npm install --prefix "$HOME/.dsh/profiles/web" dsh-speak
-   ```
-
-2. 在 `~/.dsh/profiles/web/cordis.patch.yml` 末尾追加：
-
-   ```yaml
-   - insert:
-       - id: speech-hook
-         name: 'dsh-speak'
-   ```
-
-3. 重启 DSH web 应用——之后回复就会被朗读出来。
-
-> **想让 Agent 帮你装？** 把本仓库地址（`https://github.com/Alan2Z/dsh-speak`）
-> 丢给你的 DSH 会话，让它照着这份 README 安装即可——它读的就是你正在看的这份文档。
-> 只需要同意它对 `~/.dsh`（工作区外）的写入审批。
-
-```
-harness 事件（DSH 会话事件 / Claude Code Stop hook / 任意方式）
-      │
-      ▼  adapters/…  （harness 专属触发器：过滤、节流、取消）
-      ▼  engine/speak.ps1 / speak.sh  （与 harness 无关：清洗文本 → SAPI5 / say）
-      ▼  🔊 你听到最终回复
-```
-
 ## 特性
 
 - **全自动**：DSH web 插件监听会话事件流，自动播报最终回复
   （跳过 reasoning/工具调用旁白，合并同一回复的多步消息）。
 - **提醒你**：审批请求（Agent 等你操作时会播"需要你的审批"）和 Agent 通过
   `ask_user_question` 提出的问题都会播报。
+- **最终回复重播**（1.7.0）：每条最终回复（回合尾部）操作栏有 🔊 按钮——点击
+  重播该条回复、再点停止、点另一条切换。语音执行完全由 DSH host 拥有（浏览器
+  关掉也继续读）。
+- **host 语音队列**（1.7.0）：同一时间只运行一个语音进程，队列自动串行；
+  WebSocket 实时同步"正在读哪条、队列长度"到 UI。
+- **多事件可选播报**（1.6.0）：回合结束、命令完成、目标变更、工具出错、
+  待办更新等事件都可选播报，各自独立开/关（默认关）。
+- **可视化配置**（1.7.0）：设置 → dsh-speak 设置独立设置页，所有配置项（总开关、
+  自动朗读、Markdown 清洗、代码块、事件开关、固定提示语…）直接改，无需手写
+  YAML。
+- **总开关**（1.6.0）：一键静音所有播报。
 - **Bundle 自动注册**（1.3.0）：把包声明进 `dsh.profile.bundles`，插件通过包内
   自带的 `cordis.patch.yml` 自动注册，无需手动写 patch 条目。
 - **尽力而为**：绝不抛错、绝不阻塞 harness、绝不破坏会话。
@@ -73,9 +45,22 @@ harness 事件（DSH 会话事件 / Claude Code Stop hook / 任意方式）
 - **引擎可移植**：任意进程一行即可朗读：
   Windows `powershell -File speak.ps1 -Text "你好"` / macOS `./speak.sh -t "你好"`。
 
+## 工作原理
+
+```
+harness 事件（DSH 会话事件 / Claude Code Stop hook / 任意方式）
+      │
+      ▼  adapters/…  （harness 专属触发器：过滤、节流、取消）
+      ▼  engine/speak.ps1 / speak.sh  （与 harness 无关：清洗文本 → SAPI5 / say）
+      ▼  🔊 你听到最终回复
+```
+
+适配器负责把 harness 专属事件转成引擎调用；引擎负责清洗文本并朗读，
+与 harness 完全解耦。完整设计见 [docs/DESIGN.zh-CN.md](docs/DESIGN.zh-CN.md)。
+
 ## 前置条件
 
-Windows：
+### Windows
 
 - Windows 10 或 11，任意较新的 PowerShell。
 - 自然语音：
@@ -86,14 +71,14 @@ Windows：
     并用它的 VoiceDownloader 手动下载你需要的中文或其他语言的自然语音包。
 - 没有自然语音时，引擎回退到系统自带语音（如 Huihui）。
 
-macOS：
+### macOS 要求
 
 - macOS（Apple Silicon / Intel 均可），系统自带 `say` 命令，**无需安装任何软件**。
-- 中文音色见 [macOS](#macos) 一节（含 Siri 自然音色的选择入口与坑）。
+- 中文音色与 Siri 音色的选择入口/坑见 [macOS](#macos) 一节。
 
-## 快速开始 — DSH
+## 安装与快速开始
 
-### 方式 A — npm 插件（推荐）
+### DSH — 方式 A：npm 插件（推荐）
 
 ```powershell
 # 1. 把插件装进你的 web profile（会写入 ~/.dsh/profiles/web/package.json 的 dependencies）
@@ -113,10 +98,20 @@ dsh plugin --profile web add dsh-speak
 > ```powershell
 > npm install --prefix "$env:USERPROFILE\.dsh\profiles\web" dsh-speak
 > ```
+>
+> macOS（bash）：
+>
+> ```bash
+> npm install --prefix "$HOME/.dsh/profiles/web" dsh-speak
+> ```
 
 引擎随包分发（`node_modules/dsh-speak/engine/`），无需额外拷贝。
 
-### 方式 B — 文件安装（不需要 npm）
+> **想让 Agent 帮你装？** 把本仓库地址（`https://github.com/Alan2Z/dsh-speak`）
+> 丢给你的 DSH 会话，让它照着这份 README 安装即可——它读的就是你正在看的这份文档。
+> 只需要同意它对 `~/.dsh`（工作区外）的写入审批。
+
+### DSH — 方式 B：文件安装（不需要 npm）
 
 ```powershell
 # 1. 克隆
@@ -140,14 +135,12 @@ powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.dsh\hooks
 | `adapters/dsh/speech-hook.js` | `%USERPROFILE%\.dsh\profiles\web\plugins\` |
 | 注册条目 | 追加到 `%USERPROFILE%\.dsh\profiles\web\cordis.patch.yml`（先备份） |
 
-## macOS
+### macOS
 
 同一套适配层原生支持 macOS——插件自动检测平台，改调 `engine/speak.sh`
 （系统自带的 `say` 命令）而不是 `speak.ps1`。**自 1.2.0 起 macOS 引擎随 npm 包
 正式分发**，无需安装任何额外软件。
 
-### 安装（npm 方式，与 Windows 等价）
-
 ```bash
 # 1. 装进你的 web profile（没有 pnpm 也能装——dsh plugin 才依赖 pnpm）
 npm install --prefix "$HOME/.dsh/profiles/web" dsh-speak
@@ -157,13 +150,13 @@ npm install --prefix "$HOME/.dsh/profiles/web" dsh-speak
 #        - id: speech-hook
 #          name: 'dsh-speak'
 
-# 3. 无需重启——patch 监视器会热更新；纯文字回复约 1.5 秒后自动播报
-#    （带工具调用的回复按设计不播报）
+# 3. 无需重启——patch 监视器会热更新；回复在节流后（约 1.5 秒）自动播报；
+#    带工具调用的回复会在回合结束时补播最终回复
 ```
 
 > 装过 pnpm 也可以 `dsh plugin --profile web add dsh-speak`，效果相同。
 
-### 音色（重要，有两个坑）
+#### 音色（重要，有两个坑）
 
 - 默认跟随**系统朗读声音**（系统设置 → 辅助功能 → 朗读内容 → 系统朗读声音）。
   **macOS 26** 上该选择框旁有个 **ⓘ 圆圈图标**，点开才是完整音色列表——普通
@@ -178,7 +171,7 @@ npm install --prefix "$HOME/.dsh/profiles/web" dsh-speak
 - 想强制指定音色用 `-v Eddy|Flo|Tingting`（`say -v '?'` 列出可用音色）。
 - `say` 没有音量参数——音量跟随系统输出音量。
 
-### 单独测试引擎（不装 DSH 也行）
+#### 单独测试引擎（不装 DSH 也行）
 
 ```bash
 curl -sfL -o ~/speak.sh "https://cdn.jsdelivr.net/gh/Alan2Z/dsh-speak@main/engine/speak.sh"
@@ -187,7 +180,7 @@ chmod +x ~/speak.sh
 ~/speak.sh -t "测试" -v Eddy -r 200              # 指定音色 + 语速
 ```
 
-## 快速开始 — Claude Code
+### Claude Code
 
 在 `~/.claude/settings.json` 注册 Stop hook：
 
@@ -208,7 +201,7 @@ chmod +x ~/speak.sh
 }
 ```
 
-## 快速开始 — 其他任何 harness
+### 其他任何 harness
 
 直接从你的 Agent / 包装脚本 / 工具里调用引擎：
 
@@ -225,13 +218,21 @@ powershell -NoProfile -ExecutionPolicy Bypass -File engine\speech-prompt.ps1 -Te
 
 ## 配置
 
-引擎参数（详见 [docs/DESIGN.zh-CN.md](docs/DESIGN.zh-CN.md#5-配置参考)）：
+### 引擎参数
+
+详见 [docs/DESIGN.zh-CN.md §5 配置参考](docs/DESIGN.zh-CN.md#5-配置参考)：
 
 ```powershell
 speak.ps1 -Text "…" -Volume 50 -Rate 1 -MaxChars 300 -LongTextMessage "本次播报内容较长，请自行阅读。"
 ```
 
-DSH 插件配置——**优先用 profile patch 的 `config` 块**（`dsh --dump-config` 可见、按 profile 隔离、升级不丢）：
+### DSH 插件配置
+
+**两种改法，任选其一**（改 UI 或改 YAML 都写进同一个 settings 文档，彼此同步）：
+
+1. **Web UI（1.7.0，推荐）**：设置 → dsh-speak 设置独立设置页。所有配置项都能直接改并
+   保存（`dsh --dump-config` 可见、按 profile 隔离、升级不丢）。
+2. **profile patch 的 `config` 块**（等效）：
 
 ```yaml
 # ~/.dsh/profiles/web/cordis.patch.yml
@@ -239,18 +240,79 @@ DSH 插件配置——**优先用 profile patch 的 `config` 块**（`dsh --dump
     - id: speech-hook
       name: 'dsh-speak'
       config:
+        enabled: true           # 总开关：false 时完全不播报
+        automaticSpeech: true   # 自动朗读最终回复
+        queueAllMessages: false # true = 所有 assistant 消息立即入队朗读（中间消息也读）
+        replayFullRead: false   # true = 手动重播跳过超长文本截断，完整朗读
+        cleanMarkdownFormatting: true # Markdown 转自然语音
+        readInlineCode: true    # 朗读行内代码（去掉反引号）
+        codeBlocks: smart       # all | smart | replace（围栏代码块）
+        codeBlockMaxChars: 300  # smart 模式下的代码块字数上限
+        codeBlockReplacementText: 'You can see the code in our history.' # replace 时的替代文本
         throttleMs: 1500        # 播报前的合并延迟（毫秒）
         engine: ''              # 引擎路径覆盖；'' = 自动解析
         announceApprovals: true # 播报审批请求
         announceQuestions: true # 播报 ask_user_question 提问内容
         stripApprovalPrefix: true  # 剥离审批原因里的 "escalate sandbox to ...: " 前缀
+        questionGapMs: 2000      # 多个提问播报之间的停顿（毫秒）
         longTextMode: message   # message | heading（念最大字号 markdown 标题）
-        maxChars: 300           # 引擎单次朗读字数上限
+        longTextMessage: '本次播报内容较长，请自行阅读。' # message 模式下的固定提示语
+        maxChars: 300           # 引擎单次朗读字数上限（macOS 默认 0 = 不限）
         volume: 50              # 仅 Windows
         rate: 0                 # 0 = 引擎默认（Windows SAPI 刻度 / macOS wpm）
+        # —— 可选事件播报（1.6.0，默认全关）——
+        announceTurnEnd: false     # 回合结束（"第 N 轮对话完成"）
+        announceCommandDone: false # 命令完成/失败（command/done）
+        announceGoalChange: false  # 目标创建/更新/完成（goal/change）
+        announceToolErrors: false  # 工具调用出错时播报（英文详情截掉，tool/result）
+        announceTodoWrite: false   # 待办列表更新（todo/write）
 ```
 
-完整自定义指南见 [docs/CUSTOMIZATION.md](docs/CUSTOMIZATION.zh-CN.md)。
+> 解析顺序：schema 默认值 → patch `config` → UI 用户设置。写进 YAML 的字段
+> 同样出现在 UI 中。平台差异：`maxChars` 在 macOS 默认 0（`say` 无上限），
+> Windows 默认 300（SAPI 安全上限）。
+
+#### 选项说明
+
+| 选项 | 默认值 | 效果 |
+| ---- | ------ | ---- |
+| `enabled` | `true` | **总开关**：关闭后所有播报都不触发（最终回复/审批/提问/可选事件/重播） |
+| `automaticSpeech` | `true` | 自动朗读最终回复；手动重播始终可用 |
+| `queueAllMessages` | `false` | `true` 时每条 assistant 消息立即入队朗读（中间消息也读，FIFO）；默认只读节流后的最终回复 |
+| `replayFullRead` | `false` | `true` 时手动重播跳过超长文本的标题截断（`longTextMode: heading`），完整分段朗读 |
+| `cleanMarkdownFormatting` | `true` | 把 Markdown 转成自然语音文本（链接保留文字去 URL、标题/强调符号清理） |
+| `readInlineCode` | `true` | 朗读行内代码（去掉反引号标记） |
+| `codeBlocks` | `smart` | 围栏代码块处理：`all` 全读 / `smart`（≤`codeBlockMaxChars` 才读）/ `replace` 用替代文本 |
+| `codeBlockMaxChars` | `300` | `smart` 模式下的代码块字数上限 |
+| `codeBlockReplacementText` | `You can see the code in our history.` | `replace` 模式（或超限的 `smart`）下朗读的替代文本 |
+| `throttleMs` | `1500` | 回复文本等待多久才播报（合并同一回复的多步消息） |
+| `engine` | `''` | 显式引擎脚本路径；`''` 自动解析：包内 `engine/<平台>` → `~/.dsh/hooks/<平台>` |
+| `announceApprovals` | `true` | 播报 `approval/asked` 事件（审批原因，或固定提示语） |
+| `announceQuestions` | `true` | 播报 `ask_user_question`：每个问题单独朗读，带"问题N"序号（多问题时）与"选项N"序号（与 UI 编号一致）；多个问题之间停顿 `questionGapMs` |
+| `questionGapMs` | `2000` | 多个提问播报之间的停顿（毫秒），0 = 不停顿 |
+| `stripApprovalPrefix` | `true` | 剥离审批原因里的固定英文模板前缀（`escalate sandbox to danger-full-access: `），保留中文说明 |
+| `longTextMode` | `message` | `message` = 超长念固定提示语；`heading` = 改念最大字号 markdown 标题（规则见下） |
+| `longTextMessage` | `本次播报内容较长，请自行阅读。` | `message` 模式下超长文本改念的固定提示语（UI 可编辑） |
+| `maxChars` | 平台相关 | 引擎单次朗读上限。**macOS 默认 0（`say` 无上限）；Windows 默认 300**（SAPI 超过约 375-470 字会静默失败） |
+| `volume` | `50` | 仅 Windows（0-100）；macOS 音量跟随系统 |
+| `rate` | `0` | `0` = 引擎默认（Windows SAPI 刻度如 1；macOS words-per-minute 如 175） |
+| `announceTurnEnd` | `false` | 回合结束时播报"第 N 轮对话完成/中断/异常结束"（`turn/end`） |
+| `announceCommandDone` | `false` | 命令执行完成/失败时播报（`command/done`） |
+| `announceGoalChange` | `false` | 目标创建/更新/完成/暂停/恢复时播报（`goal/change`，含目标标题前 40 字） |
+| `announceToolErrors` | `false` | 工具调用返回错误时播报"工具调用出错"（英文错误详情/技术 code 截掉，只保留中文详情；`tool/result` 带 `error` 或 `isError` 内容块时） |
+| `announceTodoWrite` | `false` | agent 更新待办列表时播报"待办已更新：n/m 完成"（`todo/write`） |
+
+#### 超长文本模式
+
+清洗后文本超过 `maxChars` 时：
+
+- **`message`**（默认）：念 `longTextMessage`（`本次播报内容较长，请自行阅读。`，
+  可在 UI 或 YAML 里编辑）。
+- **`heading`**：在原始文本里挑**最大字号**的 markdown 标题——`#` 数量最少者优先，
+  并列取第一个；没有标题行则取第一个非空行。选中的候选仍会清洗并受 `maxChars`
+  上限约束，若其本身仍超长则回退提示语。
+
+完整架构与设计取舍见 [docs/DESIGN.zh-CN.md](docs/DESIGN.zh-CN.md)。
 
 ## 自定义（升级不丢）
 
@@ -304,10 +366,12 @@ engine/                  与 harness 无关的语音引擎（PowerShell + SAPI5
   speech-summary.ps1     阻塞式回复总结播报
 adapters/
   dsh/                   DSH web 插件 + 一键安装脚本
-    speech-hook.js       会话事件触发器（节流 + 工具调用取消）
+    speech-hook.js       会话事件触发器（节流/取消 + 可选事件 + FIFO 语音队列 + WebSocket + settings 注册）
     install.ps1          拷贝 + 注册 + 备份
   claude-code/
     stop-hook.ps1        Claude Code Stop hook 触发器
+client/
+  client.js              DSH 浏览器端 bundle：回合尾部 Speak/Stop 按钮 + 设置 → dsh-speak 设置页
 docs/
   DESIGN.zh-CN.md        完整设计文档：设计取舍、踩坑记录、扩展指南
 ```