dsh-speak 1.4.0 → 1.7.0

package/docs/DESIGN.zh-CN.md

@@ -1,7 +1,6 @@
 # DESIGN.zh-CN.md — dsh-speak：为 AI 编程 harness 提供语音播报
 
-状态：**草稿** — 本文档描述当前（已验证的）本地实现与本文档仓库的目标通用结构，
-是 README 的参考依据。
+状态：**维护中** — 本文档描述当前实现与仓库结构，是 README 的参考依据。
 
 （英文版：docs/DESIGN.md）
 
@@ -32,11 +31,12 @@ Agent 工具会跑长任务（构建、测试、迁移、批量修改），而
 
 非目标（当前阶段）：
 
-- Windows 引擎（`speak.ps1`）+ macOS 引擎（`speak.sh`，系统自带 `say`）均已
-  **正式支持**（macOS 自 1.2.0 起随 npm 包分发）。不支持 Linux/无头 TTS。
+- 不支持 Linux/无头 TTS（Windows 用 `speak.ps1` + SAPI5；macOS 用 `speak.sh`
+  + 系统 `say`，macOS 引擎自 1.2.0 起随 npm 包分发）。
 - 在仓库内打包 NaturalVoiceSAPIAdapter（仅 Windows 10 需要）或语音数据——
   它们是前置依赖，不打进仓库。
-- 流式/队列播放、按音色输出音频文件、非中文音色管理。
+- 按音色输出音频文件、非中文音色管理（语音**播放队列**已在 1.7.0 实现——
+  见 §3.2 的 host FIFO 队列）。
 
 ## 3. 架构
 
@@ -106,13 +106,29 @@ Agent 工具会跑长任务（构建、测试、迁移、批量修改），而
 - 监听 `session/event`；
 - 过滤 `assistant/message` 且 `surfaceOp == 'append'` 的事件；
 - 只提取 `text` 内容块（reasoning / tool_use 块跳过）；
-- 缓冲文本并启动节流定时器（默认 1500 ms）以合并同一回复的多步消息；
-- `tool/call` 事件会**取消**待播报——该轮 assistant 文本是过程旁白，不是最终回复；
-- 触发时：把文本写入临时文件，`spawn` 出
-  `powershell.exe -File <engine> -File <tmp>`，带 `windowsHide` + `stdio: 'ignore'`，
-  绝不阻塞 harness；退出后删除临时文件。
-
-注册片段（`install.ps1` 也会自动完成）：
+- 默认模式：缓冲文本并启动节流定时器（默认 1500 ms）以合并同一回复的多步消息，
+  `tool/call` 事件会**取消**待播报（该轮 assistant 文本是过程旁白），但
+  **`turn/end` 会在回合结束时兜底补播最终回复**（带工具调用的回复也能听到）；
+- **host 语音队列**（1.7.0，源自 PR #2）：所有播报（最终回复、审批、提问、
+  可选事件、手动重播）统一进入 FIFO 队列，**同一时间只运行一个语音进程**，
+  读完自动播下一条；`/dsh-speak/control` POST 路由（play/stop/status）和
+  `/dsh-speak/ws` WebSocket 广播权威播放状态（正在读哪条、队列长度）。
+- **最终回复重播**（1.7.0）：回合尾部（最终回复）操作栏的 🔊 按钮调 control
+  路由重播**该条最终回复**；语音执行完全由 host 拥有（浏览器关掉也继续）。
+- **`queueAllMessages` 开关**（1.7.0，默认关）：关 = 默认节流最终回复 + 可选
+  事件；开 = 每条 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` 工作——向后兼容。
+
+注册片段（`install.ps1` 也会自动完成；npm 安装用裸包名 `'dsh-speak'` 即可，
+这是文件安装方式用的路径）：
 
 ```yaml
 # ~/.dsh/profiles/web/cordis.patch.yml
@@ -125,6 +141,29 @@ Agent 工具会跑长任务（构建、测试、迁移、批量修改），而
 > Node 的 ESM 加载器不接受 Windows 绝对路径作为插件名——必须用
 > `file:///C:/...` URL 形式。
 
+### 3.4 DSH 浏览器端 — `client/client.js`
+
+一个 DSH client bundle（`window.__ModuleLoader__.load({ id: 'dsh-speak',
+factory })`），注册两条 UI：
+
+- **回合尾部的 Speak 按钮**（1.7.0，源自 PR #2）：注册进
+  `conversation.chat.assistant-actions` slot（该回合最终回复的操作栏）。点击 🔊
+  调 `/dsh-speak/control` 重播该条最终回复，再点停止，点另一条切换；按钮状态
+  （播放中/暂停）由 `/dsh-speak/ws` WebSocket 的 host 权威状态推导（session +
+  turn 身份匹配）。
+- **设置 → dsh-speak 设置独立设置页**（1.7.0）：注册进 `settings.section` slot。
+  用 `@deepseek-ai/dsh-client-ui-primitives` 的 Button/DisclosureRow/Input
+  绘制（Toggle/Options/SettingInput 组件），所有配置项（总开关、自动朗读、
+  queueAllMessages、Markdown 清洗、代码块、maxChars、longTextMode、固定提示语、
+  审批/提问、5 类可选事件）都通过 `settingsScope.bind({ namespace: 'dsh-speak' })`
+  读写。
+
+- 包通过 `package.json` 的 `dsh.client: { platform: 'web' }` +
+  `exports['./client']` 声明浏览器端；DSH 的 client-modules 扫描到后自动加载。
+- **刻意手写、零构建**：只用平台 seed 模块 + 官方 primitives（bundle-purity
+  gate 允许用 primitives，禁止 import 官方包内部组件），与构建出来的 bundle
+  契约一致。
+
 ### 3.3 Claude Code 适配层 — `adapters/claude-code/stop-hook.ps1`
 
 Claude Code *确实*有 Stop hook。hook JSON（含 `transcript_path`）从 stdin 传入；
@@ -137,11 +176,19 @@ Claude Code *确实*有 Stop hook。hook JSON（含 `transcript_path`）从 stdi
 | assistant 轮次 / 事件            | 是否播报 |
 | -------------------------------- | -------- |
 | 最终文本回复，无工具调用         | ✅ 节流后播报 |
-| 文本 + tool/call(s)              | ❌（取消——旁白） |
-| 文本 + `ask_user_question` 调用  | ✅ 保留提问文本并播报 |
+| 文本 + tool/call(s)              | 🟡 节流被取消（中间轮次）；**回合结束时兜底补播最终回复** |
+| 文本 + `ask_user_question` 调用  | ✅ 每个问题单独播报："问题N"（多问题时）+ "选项N"序号，问题间停顿 `questionGapMs` |
 | `approval/asked`（审批请求）     | ✅ 立即播报（审批原因，否则固定提示语） |
 | 只有 reasoning，无文本           | ❌（无 text 块） |
 | 流式分块                         | ❌（被过滤） |
+| `turn/end`（回合结束）           | 🟡 默认关；开则播报"第 N 轮对话完成/中断/异常结束" |
+| `command/done`（命令完成）       | 🟡 默认关；开则播报"命令执行完成/失败" |
+| `goal/change`（目标变更）        | 🟡 默认关；开则播报"已创建目标/目标已完成…（前 40 字）" |
+| `tool/result`（工具结果）        | 🟡 默认关；开则仅当带 `error` 或 `isError` 内容块时播报"工具调用出错"（英文详情/技术 code 截掉，只保留中文详情） |
+| `todo/write`（待办更新）         | 🟡 默认关；开则播报"待办已更新：n/m 完成" |
+
+| `assistant/message`（queueAllMessages 开）| ✅ 每条立即入队（中间消息也读） |
+| 手动重播（每条消息 🔊 按钮）         | ✅ 清队列 → 停当前 → 读该回合 |
 
 ## 5. 配置参考
 
@@ -153,15 +200,52 @@ Claude Code *确实*有 Stop hook。hook JSON（含 `transcript_path`）从 stdi
 | `-File` | `''` | 要读取的 UTF-8 文件 |
 | `-Volume` | `50` | 0–100 |
 | `-Rate` | `1` | 语速（SAPI 刻度） |
-| `-MaxChars` | `300` | 超过此长度时替换为 `LongTextMessage` |
+| `-MaxChars` | 平台相关 | 超过此长度时替换为 `LongTextMessage`（macOS 默认 0 = 不限） |
 | `-LongTextMessage` | `本次播报内容较长，请自行阅读。` | 超长文本时改念这句 |
+| `-LongTextMode` | `message` | `message`（固定提示语）\| `heading`（念最大字号 markdown 标题） |
+| `-CleanMarkdownFormatting` | `true` | Markdown 转自然语音（保留链接文字去 URL） |
+| `-ReadInlineCode` | `true` | 朗读行内代码（去掉反引号） |
+| `-CodeBlocks` | `smart` | `all` \| `smart` \| `replace`（围栏代码块） |
+| `-CodeBlockMaxChars` | `300` | `smart` 模式的代码块字数上限 |
+| `-CodeBlockReplacementText` | `You can see the code in our history.` | `replace` 时的替代文本 |
 
-### DSH 插件（环境变量）
+### DSH 插件（profile `config`；1.7.0 起同样可在 Web UI 的 dsh-speak 设置页里改）
 
-| 变量 | 默认值 | 含义 |
-| ---- | ------ | ---- |
-| `DSH_SPEAK_ENGINE` | 空（自动解析） | 引擎路径覆盖；否则按"包内 `engine/<平台脚本>` → `~/.dsh/hooks/<平台脚本>`"顺序解析（Windows 为 `speak.ps1`，macOS 为 `speak.sh`） |
-| `DSH_SPEAK_THROTTLE_MS` | `1500` | 播报前的合并延迟（毫秒） |
+```yaml
+config:
+  enabled: true                # 总开关
+  automaticSpeech: true        # 自动朗读最终回复
+  queueAllMessages: false      # true = 所有 assistant 消息立即入队
+  replayFullRead: false        # true = 手动重播跳过超长文本截断，完整朗读
+  cleanMarkdownFormatting: true
+  readInlineCode: true
+  codeBlocks: smart            # all | smart | replace
+  codeBlockMaxChars: 300
+  codeBlockReplacementText: 'You can see the code in our history.'
+  throttleMs: 1500
+  engine: ''                   # '' = 自动解析
+  announceApprovals: true
+  announceQuestions: true
+  stripApprovalPrefix: true
+  questionGapMs: 2000          # 多个提问播报之间的停顿（毫秒）
+  longTextMode: message        # message | heading
+  longTextMessage: '本次播报内容较长，请自行阅读。'
+  maxChars: 300                # macOS 默认 0 = 不限
+  volume: 50                   # 仅 Windows
+  rate: 0                      # 0 = 引擎默认
+  # —— 可选事件播报（默认全关）——
+  announceTurnEnd: false     # turn/end
+  announceCommandDone: false # command/done
+  announceGoalChange: false  # goal/change
+  announceToolErrors: false  # tool/result 带 error 或 isError 块时
+  announceTodoWrite: false   # todo/write
+```
+
+配置解析顺序：schema 默认值 → patch `config`（base）→ UI 用户设置（user 层）。
+浏览器端 dsh-speak 设置页（`client/client.js`）与 patch YAML 读写同一个 settings
+文档。平台差异：`maxChars` macOS 默认 0（`say` 无上限）、Windows 默认 300。
+
+完整配置指南见 README 的"配置"一节。
 
 ## 6. 踩坑记录（来之不易；不要随意"修复"）
 
@@ -189,10 +273,9 @@ hook）、任意 shell harness（Agent 自己调 `speech-summary.ps1`）就是
 
 ## 8. 项目定位
 
-本项目**刻意不是**一个持续迭代的产品。它记录了一条被验证过的、让 harness
-开口说话的实现路径：一个小引擎 + 两种可复用的适配范式（事件流 / Stop hook）。
-如果你需要更多（音色管理界面、更多后端、跨平台），把引擎当作接缝在其上扩展——
-本仓库保持为最小、自包含的参考实现。
+本项目保持**小而自包含**的设计：一个小引擎 + 两种可复用的适配范式（事件流 /
+Stop hook），并**持续维护**。需要更多能力（音色管理界面、更多后端、跨平台）时，
+把引擎当作接缝在其上扩展。
 
 ## 9. 发布为 npm 插件（附录）
 
@@ -212,7 +295,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,9 +29,27 @@ param(
     [int]$Volume = 50,
     [int]$Rate = 1,
     [int]$MaxChars = 300,
-    [string]$LongTextMessage = '本次播报内容较长，请自行阅读。'
+    [string]$LongTextMessage = '本次播报内容较长，请自行阅读。',
+    [ValidateSet('message', 'heading')]
+    [string]$LongTextMode = 'message',
+    # 命令行参数一律是字符串（-File 模式不做类型转换），这里用 [string] 接收，
+    # 在脚本内部再转布尔，兼容 '1'/'0'/'true'/'True'/'yes'/'on' 等写法。
+    [string]$CleanMarkdownFormatting = 'true',
+    [string]$ReadInlineCode = 'true',
+    [ValidateSet('all', 'smart', 'replace')]
+    [string]$CodeBlocks = 'smart',
+    [int]$CodeBlockMaxChars = 300,
+    [string]$CodeBlockReplacementText = 'You can see the code in our history.',
+    # 手动重播完整朗读：跳过超长文本的 heading/message 截断，分段完整朗读
+    [string]$FullRead = '0'
 )
 
+$cleanMarkdown = $CleanMarkdownFormatting -in @('1', 'true', 'yes', 'on')
+$readInlineCode = $ReadInlineCode -in @('1', 'true', 'yes', 'on')
+# 注意：PowerShell 变量大小写不敏感，内部变量名不能与参数名仅差大小写
+# （曾用 $fullRead 导致自赋值污染参数 $FullRead，使 -not 判断失效）
+$fullReadMode = $FullRead -in @('1', 'true', 'yes', 'on')
+
 # ---------- input: pick text source ----------
 if ($File) {
     if (-not (Test-Path $File)) { exit 0 }
@@ -41,21 +59,52 @@ if ($File) {
 }
 if (-not $text -or -not $text.Trim()) { exit 0 }
 
-# ---------- clean: markdown -> plain speech text ----------
-# code blocks, inline code, markdown links, bare URLs, emphasis/marker chars
-$text = $text -replace '```[\s\S]*?```', ' '
-$text = $text -replace '`[^`]*`', ' '
-$text = $text -replace '\[([^\]]*)\]\([^\)]*\)', '$1'
-$text = $text -replace 'https?://\S+', ' '
-$text = $text -replace '[-#*_~|>+]+', ' '
-# emoji / special symbols (Speak() fails silently on them): keep CJK, CJK punct,
-# full-width ranges, ASCII printable
-$text = [regex]::Replace($text, '[^一-龥　-〿＀-￯ - -~]', '')
+# ---------- 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') {
+    $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 -> natural speech text ----------
+if ($cleanMarkdown) {
+    $text = [regex]::Replace($text, '```[^\n]*\n?([\s\S]*?)```', {
+        param($match)
+        $code = $match.Groups[1].Value
+        if ($CodeBlocks -eq 'all' -or ($CodeBlocks -eq 'smart' -and $code.Length -le $CodeBlockMaxChars)) { return " $code " }
+        return " $CodeBlockReplacementText "
+    })
+    if ($readInlineCode) { $text = $text -replace '`([^`]*)`', '$1' } else { $text = $text -replace '`[^`]*`', ' ' }
+    $text = $text -replace '\[([^\]]*)\]\([^\)]*\)', '$1'
+    $text = $text -replace 'https?://\S+', ' '
+    $text = $text -replace '(?m)^\s{0,3}(?:#{1,6}\s+|[-*+]\s+|\d+[.)]\s+|>\s?)', ' '
+    $text = $text -replace '(\*\*|__|~~)(.*?)\1', '$2'
+    $text = $text -replace '[*_~]+', ''
+}
+# Keep all Unicode letters, including Portuguese accents; remove unsafe symbols.
+$text = [regex]::Replace($text, '[^\p{L}\p{N}一-龥　-〿＀-￯ - -~]', '')
 $text = $text -replace '\s+', ' '
 $text = $text.Trim()
 
-# ---------- length guard: adapter per-Speak ceiling ----------
-if ($text.Length -gt $MaxChars) { $text = $LongTextMessage }
+# ---------- final ceiling (also catches over-long heading candidates) ----------
+if (-not $fullReadMode -and $text.Length -gt $MaxChars) { $text = $LongTextMessage }
 
 # ---------- speak ----------
 Add-Type -AssemblyName System.Speech
@@ -72,5 +121,30 @@ if (-not $voice) { $voice = $voices | Where-Object { $_.VoiceInfo.Culture.Name -
 if ($voice) { $synth.SelectVoice($voice.VoiceInfo.Name) }
 
 $synth.Rate = $Rate
-$synth.Speak($text)
+
+# ---------- 完整朗读（FullRead，手动重播） ----------
+# Windows SAPI 单次 Speak 有约 375-470 字上限，超长会静默失败；因此按句末
+# 标点切成不超过 450 字的段，逐段朗读（自动播报不经过这里，走上面的守卫）。
+$SPEAK_CHUNK = 400
+if ($fullReadMode -and $text.Length -gt $SPEAK_CHUNK) {
+    $parts = [regex]::Split($text, '(?<=[。！？；.!?;])')
+    $chunk = ''
+    foreach ($part in $parts) {
+        if ($part.Length -eq 0) { continue }
+        if ($chunk.Length + $part.Length -gt $SPEAK_CHUNK) {
+            if ($chunk) { $synth.Speak($chunk); $chunk = '' }
+            # 单段仍超长：硬切
+            while ($part.Length -gt $SPEAK_CHUNK) {
+                $synth.Speak($part.Substring(0, $SPEAK_CHUNK))
+                $part = $part.Substring($SPEAK_CHUNK)
+            }
+            $chunk = $part
+        } else {
+            $chunk += $part
+        }
+    }
+    if ($chunk) { $synth.Speak($chunk) }
+} else {
+    $synth.Speak($text)
+}
 exit 0

package/engine/speak.sh

@@ -1,49 +1,32 @@
 #!/usr/bin/env bash
 # speak.sh — macOS speech engine (uses the built-in `say` command)
-# ==============================================================================
-# The macOS counterpart of engine/speak.ps1. Reads text (inline or UTF-8 file),
-# cleans it for speech synthesis, and reads it aloud via the system `say`
-# command. Any process can call it:
-#
-#   ./speak.sh -t "你好，构建完成"
-#   ./speak.sh -f /tmp/msg.txt -v Eddy -r 200
-#
-# Best-effort by design: never throws, exits 0 even if something failed.
-#
-# Voice selection:
-#   * no -v (default): follow the system voice — on recent macOS this is the
-#     Siri voice chosen in Settings > Siri > Voice (e.g. "声音 1"), on older
-#     versions the Spoken Content voice. This is the least surprising default.
-#   * -v <name>: force a voice by name (e.g. Eddy, Flo, Tingting — see
-#     `say -v '?'`).
-#   * NOTE: the Siri voices ("声音 1-4") are NOT exposed to `say` — they do not
-#     appear in `say -v '?'` and cannot be selected by name; they only work as
-#     the system default.
-#
-# Notes:
-#   * LC_ALL is pinned to a UTF-8 locale so the perl cleaning pipeline and bash
-#     character counting behave identically regardless of the caller's locale
-#     (a C/POSIX locale would silently strip all CJK text).
-#   * The cleaning pipeline mirrors speak.ps1 (markdown/URL/emoji stripped).
-#   * `say` has no volume flag — volume is controlled by the system output.
-#   * Length guard: text over $MAX_CHARS is replaced with $LONG_MSG.
-# ==============================================================================
+# ==================================================================
+# Reads text (inline or UTF-8 file), optionally converts Markdown into natural
+# speech text, and reads it aloud with the system voice. A zero max length means
+# unlimited text, which is safe for macOS `say`.
 
 export LC_ALL="${LC_ALL:-en_US.UTF-8}"
 
 TEXT=""
 FILE=""
 VOICE=""
-RATE=175          # words per minute (say default)
-MAX_CHARS=300
+RATE=175
+MAX_CHARS=0
 LONG_MSG="本次播报内容较长，请自行阅读。"
+LONG_MODE="message"
+CLEAN_MARKDOWN=1
+READ_INLINE_CODE=1
+CODE_BLOCKS="smart"
+CODE_BLOCK_MAX_CHARS=300
+CODE_BLOCK_REPLACEMENT="You can see the code in our history."
+FULL_READ=0
 
 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] [-C 0|1] [-I 0|1] [-B all|smart|replace] [-K codechars] [-R replacement] [-F]" >&2
   exit 1
 }
 
-while getopts "t:f:v:r:m:l:h" opt; do
+while getopts "t:f:v:r:m:l:M:C:I:B:K:R:Fh" opt; do
   case "$opt" in
     t) TEXT="$OPTARG" ;;
     f) FILE="$OPTARG" ;;
@@ -51,39 +34,70 @@ 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" ;;
+    C) CLEAN_MARKDOWN="$OPTARG" ;;
+    I) READ_INLINE_CODE="$OPTARG" ;;
+    B) CODE_BLOCKS="$OPTARG" ;;
+    K) CODE_BLOCK_MAX_CHARS="$OPTARG" ;;
+    R) CODE_BLOCK_REPLACEMENT="$OPTARG" ;;
+    F) FULL_READ=1 ;;
     h) usage ;;
     *) usage ;;
   esac
 done
 
-# ---------- input ----------
 if [ -n "$FILE" ]; then
   [ -f "$FILE" ] || exit 0
   TEXT=$(/usr/bin/perl -CSD -e 'print <>' "$FILE")
 fi
-if [ -z "$TEXT" ]; then exit 0; fi
+[ -n "$TEXT" ] || exit 0
 
-# ---------- clean (mirrors speak.ps1) ----------
+# `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
+  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 = $_; }
+    }
+    print($cand eq "" ? $first : $cand);
+  ')
+fi
+
+if [ "$CLEAN_MARKDOWN" = "1" ]; then
+  export DSH_SPEAK_CODE_BLOCKS="$CODE_BLOCKS"
+  export DSH_SPEAK_CODE_BLOCK_MAX_CHARS="$CODE_BLOCK_MAX_CHARS"
+  export DSH_SPEAK_CODE_BLOCK_REPLACEMENT="$CODE_BLOCK_REPLACEMENT"
+  export DSH_SPEAK_READ_INLINE_CODE="$READ_INLINE_CODE"
+  TEXT=$(printf '%s' "$TEXT" | /usr/bin/perl -CSD -0pe '
+    my $mode = $ENV{DSH_SPEAK_CODE_BLOCKS} || "smart";
+    my $limit = $ENV{DSH_SPEAK_CODE_BLOCK_MAX_CHARS} || 300;
+    my $replacement = $ENV{DSH_SPEAK_CODE_BLOCK_REPLACEMENT} || "";
+    s{```[^\n]*\n?(.*?)```}{
+      my $code = $1;
+      $mode eq "all" || ($mode eq "smart" && length($code) <= $limit) ? " $code " : " $replacement ";
+    }gse;
+    if (($ENV{DSH_SPEAK_READ_INLINE_CODE} || "1") eq "1") { s/`([^`]*)`/$1/g; }
+    else { s/`[^`]*`/ /g; }
+    s/\[([^\]]*)\]\([^\)]*\)/$1/g;
+    s|https?://\S+| |g;
+    s/^\s{0,3}(?:\#{1,6}\s+|[-*+]\s+|\d+[.)]\s+|>\s?)/ /gm;
+    s/(\*\*|__|~~)(.*?)\1/$2/g;
+    s/[\*_~]+//g;
+  ')
+fi
+
+# Retain all letters (including Portuguese accents) and numbers, while removing
+# emoji/symbols that make the native synthesizer unreliable.
 TEXT=$(printf '%s' "$TEXT" | /usr/bin/perl -CSD -pe '
-  s/```[\s\S]*?```/ /g;          # code blocks
-  s/`[^`]*`/ /g;                  # inline code
-  s/\[([^\]]*)\]\([^\)]*\)/$1/g;  # markdown links
-  s|https?://\S+| |g;             # bare URLs
-  s/[-#*_~|>+]+/ /g;              # emphasis / marker chars
-  s/[^\p{Han}\x{3000}-\x{303F}\x{FF00}-\x{FFEF}\x{2000}-\x{206F}\x{20}-\x{7E}]//g;  # emoji / specials
-  s/\s+/ /g;                      # collapse whitespace
+  s/[^\p{L}\p{N}\p{Han}\x{3000}-\x{303F}\x{FF00}-\x{FFEF}\x{2000}-\x{206F}\x{20}-\x{7E}]//g;
+  s/\s+/ /g;
 ')
 TEXT=$(printf '%s' "$TEXT" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
 
-# ---------- length guard ----------
-if [ "${#TEXT}" -gt "$MAX_CHARS" ]; then
-  TEXT="$LONG_MSG"
-fi
+if [ "$FULL_READ" != "1" ] && [ "$MAX_CHARS" -gt 0 ] && [ "${#TEXT}" -gt "$MAX_CHARS" ]; then TEXT="$LONG_MSG"; fi
+[ -n "$TEXT" ] || exit 0
 
-# ---------- speak (no -v => system default voice) ----------
-if [ -n "$VOICE" ]; then
-  say -v "$VOICE" -r "$RATE" "$TEXT"
-else
-  say -r "$RATE" "$TEXT"
-fi
+if [ -n "$VOICE" ]; then say -v "$VOICE" -r "$RATE" "$TEXT"; else say -r "$RATE" "$TEXT"; fi
 exit 0

package/package.json

@@ -1,12 +1,19 @@
 {
   "name": "dsh-speak",
-  "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)",
+  "version": "1.7.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": {
+    ".": "./adapters/dsh/speech-hook.js",
+    "./client": "./client/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
   "files": [
     "adapters/dsh/speech-hook.js",
     "adapters/dsh/install.ps1",
     "cordis.patch.yml",
+    "client/",
     "engine/",
     "docs/",
     "README.md",
@@ -16,6 +23,17 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "external": [
+        "@deepseek-ai/dsh-client-ui-primitives"
+      ]
     }
   },
   "keywords": [
@@ -35,7 +53,10 @@
     "say"
   ],
   "scripts": {
-    "prepublishOnly": "node --check adapters/dsh/speech-hook.js"
+    "prepublishOnly": "node --check adapters/dsh/speech-hook.js && node --check client/client.js"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
   },
   "engines": {
     "node": ">=18"
@@ -46,6 +67,18 @@
   },
   "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
+    }
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   }