dsh-speak 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alan2Z
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# dsh-speak 🔊 — Voice announcements for AI coding harnesses
+
+**English** · [中文](README.zh-CN.md)
+
+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 Windows speech synthesis,
+using natural voices (Windows 11 built-in, or [NaturalVoiceSAPIAdapter] on
+Windows 10) with graceful fallback to stock voices. It was built 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.
+
+```
+harness event (DSH session event / Claude Code Stop hook / anything)
+      │
+      ▼  adapters/…  (harness-specific trigger: filter, throttle, cancel)
+      ▼  engine/speak.ps1  (harness-agnostic: clean text → Windows SAPI5)
+      ▼  🔊 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).
+- **Best-effort**: never throws, never blocks the harness, never breaks a session.
+- **Natural voices**: prefers natural voices — Windows 11 built-in packs, or
+  voices registered via NaturalVoiceSAPIAdapter on Windows 10 (e.g. Xiaoxiao) —
+  and falls back to any installed voice.
+- **Robust text cleaning**: strips markdown/URLs/emoji that make SAPI `Speak()`
+  silently fail, and guards the adapter's per-utterance character ceiling.
+- **Portable engine**: any process can speak with one line:
+  `powershell -File speak.ps1 -Text "你好"`.
+
+## Prerequisites
+
+- Windows 10 or 11, PowerShell (any recent version).
+- Natural voices:
+  - **Windows 11**: natural voice packs are built into the system — no extra
+    installation. Enable/switch them in *Settings → Accessibility → Narrator* or
+    *Settings → Time & Language → Speech*.
+  - **Windows 10**: install
+    [NaturalVoiceSAPIAdapter](https://github.com/gexgd0419/NaturalVoiceSAPIAdapter)
+    and use its VoiceDownloader to download the natural voice pack(s) you want
+    (Chinese or any other language).
+- Without natural voices, the engine falls back to a stock voice (e.g. Huihui).
+
+## Quick start — DSH
+
+### Option A — npm plugin (recommended)
+
+```powershell
+# 1. install the plugin into your web profile (adds dsh-speak to
+#    ~/.dsh/profiles/web/package.json dependencies)
+dsh plugin --profile web add dsh-speak
+
+# 2. register it in ~/.dsh/profiles/web/cordis.patch.yml
+#    (for npm packages the bare package name is used — no file:/// URL needed):
+#    - insert:
+#        - id: speech-hook
+#          name: 'dsh-speak'
+
+# 3. restart the DSH web app — replies are now announced automatically
+```
+
+The engine ships inside the package (`node_modules/dsh-speak/engine/`), so no extra
+copying is needed.
+
+### Option B — file install (no npm needed)
+
+```powershell
+# 1. clone
+git clone https://github.com/Alan2Z/dsh-speak.git
+cd dsh-speak
+
+# 2. one-command install: copies engine + plugin, registers in cordis.patch.yml
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File adapters\dsh\install.ps1
+
+# 3. verify the engine speaks
+powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.dsh\hooks\speak.ps1" -Text "你好，语音播报已就绪。"
+
+# 4. restart the DSH web app — replies are now announced automatically
+```
+
+What the file installer did:
+
+| file | destination |
+| ---- | ----------- |
+| `engine/*.ps1` | `%USERPROFILE%\.dsh\hooks\` |
+| `adapters/dsh/speech-hook.js` | `%USERPROFILE%\.dsh\profiles\web\plugins\` |
+| registration entry | appended to `%USERPROFILE%\.dsh\profiles\web\cordis.patch.yml` (backed up first) |
+
+## Quick start — Claude Code
+
+Register the Stop hook in `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\\path\\to\\dsh-speak\\adapters\\claude-code\\stop-hook.ps1"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Quick start — any other harness
+
+Call the engine directly from your agent / wrapper / script:
+
+```powershell
+# announce a one-liner
+powershell -NoProfile -ExecutionPolicy Bypass -File engine\speak.ps1 -Text "构建完成"
+
+# announce a long summary (from a file)
+powershell -NoProfile -ExecutionPolicy Bypass -File engine\speech-summary.ps1 -Text "…"
+
+# ask for user attention (blocking, for prompts/approvals)
+powershell -NoProfile -ExecutionPolicy Bypass -File engine\speech-prompt.ps1 -Text "请做出选择"
+```
+
+## Configuration
+
+Engine parameters (see [docs/DESIGN.md](docs/DESIGN.md#5-configuration-reference)):
+
+```powershell
+speak.ps1 -Text "…" -Volume 50 -Rate 1 -MaxChars 300 -LongTextMessage "本次播报内容较长，请自行阅读。"
+```
+
+DSH plugin environment variables:
+
+| var | default | meaning |
+| --- | ------- | ------- |
+| `DSH_SPEAK_ENGINE` | `%USERPROFILE%\.dsh\hooks\speak.ps1` | engine path |
+| `DSH_SPEAK_THROTTLE_MS` | `1500` | merge delay before announcing |
+
+## Troubleshooting
+
+| symptom | cause | fix |
+| ------- | ----- | --- |
+| 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 |
+| 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) |
+
+Plugin diagnostics: `%TEMP%\dsh-speech-hook.log`.
+
+## Repository layout
+
+```
+engine/                  harness-agnostic speech engine (PowerShell + SAPI5)
+  speak.ps1              clean + speak (the only seam any adapter needs)
+  speech-prompt.ps1      blocking short announcement
+  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)
+    install.ps1          copies + registers + backs up
+  claude-code/
+    stop-hook.ps1        Claude Code Stop hook trigger
+docs/
+  DESIGN.md              full design rationale, pitfalls, extension guide
+```
+
+## Writing a new adapter
+
+Three reference patterns exist: **event-stream** (DSH), **stop-hook** (Claude Code),
+**agent-called** (`speech-summary.ps1` from a shell). In every case the adapter only
+needs to: capture the *final reply text* → invoke the engine. See
+[docs/DESIGN.md §7](docs/DESIGN.md#7-extending).
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+[NaturalVoiceSAPIAdapter]: https://github.com/gexgd0419/NaturalVoiceSAPIAdapter

package/README.zh-CN.md

@@ -0,0 +1,177 @@
+# dsh-speak 🔊 — 为 AI 编程 harness 提供语音播报
+
+让 Agent 在长任务完成时**开口告诉你**——不用再盯着屏幕等。
+
+dsh-speak 通过 Windows 语音合成把 Agent 的最终回复朗读出来，优先使用自然语音
+（Windows 11 内置，或 Windows 10 上经 [NaturalVoiceSAPIAdapter] 注册，如晓晓），
+没有时优雅回退到系统自带中文语音。本项目为
+[DeepSeek Harness](https://github.com/deepseek-ai/dsh) 而生，但结构上
+任何 harness 都能接入。
+
+> **项目定位**：本项目只是为了给想让 harness 开口说话的用户提供一种**已经验证过的方案**；
+> 没有意外的话，后续不会再更新。
+
+```
+harness 事件（DSH 会话事件 / Claude Code Stop hook / 任意方式）
+      │
+      ▼  adapters/…  （harness 专属触发器：过滤、节流、取消）
+      ▼  engine/speak.ps1  （与 harness 无关：清洗文本 → Windows SAPI5）
+      ▼  🔊 你听到最终回复
+```
+
+## 特性
+
+- **全自动**：DSH web 插件监听会话事件流，自动播报最终回复
+  （跳过 reasoning/工具调用旁白，合并同一回复的多步消息）。
+- **尽力而为**：绝不抛错、绝不阻塞 harness、绝不破坏会话。
+- **自然语音**：优先使用自然语音——Windows 11 内置语音包，或 Windows 10 上经
+  NaturalVoiceSAPIAdapter 注册的语音（如晓晓），回退到任意已安装语音。
+- **健壮的文本清洗**：去掉会让 SAPI `Speak()` 静默失败的 markdown/URL/emoji，
+  并守卫适配器单次朗读的字数上限。
+- **引擎可移植**：任意进程一行即可朗读：
+  `powershell -File speak.ps1 -Text "你好"`。
+
+## 前置条件
+
+- Windows 10 或 11，任意较新的 PowerShell。
+- 自然语音：
+  - **Windows 11**：系统已内置自然语音包，无需额外安装——在
+    *设置 → 辅助功能 → 讲述人* 或 *设置 → 时间和语言 → 语音* 中启用/切换即可。
+  - **Windows 10**：需要安装
+    [NaturalVoiceSAPIAdapter](https://github.com/gexgd0419/NaturalVoiceSAPIAdapter)，
+    并用它的 VoiceDownloader 手动下载你需要的中文或其他语言的自然语音包。
+- 没有自然语音时，引擎回退到系统自带语音（如 Huihui）。
+
+## 快速开始 — DSH
+
+### 方式 A — npm 插件（推荐）
+
+```powershell
+# 1. 把插件装进你的 web profile（会写入 ~/.dsh/profiles/web/package.json 的 dependencies）
+dsh plugin --profile web add dsh-speak
+
+# 2. 在 ~/.dsh/profiles/web/cordis.patch.yml 里注册（npm 包直接用包名，无需 file:/// URL）：
+#    - insert:
+#        - id: speech-hook
+#          name: 'dsh-speak'
+
+# 3. 重启 DSH web 应用 — 之后回复会被自动播报
+```
+
+引擎随包分发（`node_modules/dsh-speak/engine/`），无需额外拷贝。
+
+### 方式 B — 文件安装（不需要 npm）
+
+```powershell
+# 1. 克隆
+git clone https://github.com/Alan2Z/dsh-speak.git
+cd dsh-speak
+
+# 2. 一键安装：拷贝引擎 + 插件，并注册到 cordis.patch.yml
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File adapters\dsh\install.ps1
+
+# 3. 验证引擎能出声
+powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.dsh\hooks\speak.ps1" -Text "你好，语音播报已就绪。"
+
+# 4. 重启 DSH web 应用 — 之后回复会被自动播报
+```
+
+文件安装脚本做了这些事：
+
+| 文件 | 目标位置 |
+| ---- | -------- |
+| `engine/*.ps1` | `%USERPROFILE%\.dsh\hooks\` |
+| `adapters/dsh/speech-hook.js` | `%USERPROFILE%\.dsh\profiles\web\plugins\` |
+| 注册条目 | 追加到 `%USERPROFILE%\.dsh\profiles\web\cordis.patch.yml`（先备份） |
+
+## 快速开始 — Claude Code
+
+在 `~/.claude/settings.json` 注册 Stop hook：
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\\path\\to\\dsh-speak\\adapters\\claude-code\\stop-hook.ps1"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## 快速开始 — 其他任何 harness
+
+直接从你的 Agent / 包装脚本 / 工具里调用引擎：
+
+```powershell
+# 播报一句话
+powershell -NoProfile -ExecutionPolicy Bypass -File engine\speak.ps1 -Text "构建完成"
+
+# 播报较长总结（阻塞，读完才返回）
+powershell -NoProfile -ExecutionPolicy Bypass -File engine\speech-summary.ps1 -Text "…"
+
+# 需要用户注意时（阻塞，适合提问/授权场景）
+powershell -NoProfile -ExecutionPolicy Bypass -File engine\speech-prompt.ps1 -Text "请做出选择"
+```
+
+## 配置
+
+引擎参数（详见 [docs/DESIGN.zh-CN.md](docs/DESIGN.zh-CN.md#5-配置参考)）：
+
+```powershell
+speak.ps1 -Text "…" -Volume 50 -Rate 1 -MaxChars 300 -LongTextMessage "本次播报内容较长，请自行阅读。"
+```
+
+DSH 插件环境变量：
+
+| 变量 | 默认值 | 含义 |
+| --- | ------- | ---- |
+| `DSH_SPEAK_ENGINE` | `%USERPROFILE%\.dsh\hooks\speak.ps1` | 引擎路径 |
+| `DSH_SPEAK_THROTTLE_MS` | `1500` | 播报前的合并延迟（毫秒） |
+
+## 排障
+
+| 现象 | 原因 | 解决 |
+| ---- | ---- | ---- |
+| 完全没有声音、无报错 | 未启用/安装自然语音 | Win11：在 设置 → 讲述人/语音 中启用自然语音；Win10：安装 NaturalVoiceSAPIAdapter 并下载语音包。直接测 `speak.ps1` |
+| 长回复从不播报 | 适配器单次 `Speak` 有字数上限 | 已默认在 300 字处守卫——必要时调低 `-MaxChars` |
+| 含大量 emoji 的文本静默 | SAPI 遇到 emoji 会静默失败 | 引擎已自动剥离 |
+| 插件加载失败 | 插件名用了 Windows 原始路径 | 改用 `file:///C:/…` URL 形式（安装脚本会自动处理） |
+
+插件诊断日志：`%TEMP%\dsh-speech-hook.log`
+
+## 仓库结构
+
+```
+engine/                  与 harness 无关的语音引擎（PowerShell + SAPI5）
+  speak.ps1              清洗 + 朗读（适配层唯一需要打交道的接口）
+  speech-prompt.ps1      阻塞式短提示播报
+  speech-summary.ps1     阻塞式回复总结播报
+adapters/
+  dsh/                   DSH web 插件 + 一键安装脚本
+    speech-hook.js       会话事件触发器（节流 + 工具调用取消）
+    install.ps1          拷贝 + 注册 + 备份
+  claude-code/
+    stop-hook.ps1        Claude Code Stop hook 触发器
+docs/
+  DESIGN.zh-CN.md        完整设计文档：设计取舍、踩坑记录、扩展指南
+```
+
+## 编写新适配器
+
+三种参考模式：**事件流**（DSH）、**Stop hook**（Claude Code）、**Agent 自调用**
+（在 shell 里调 `speech-summary.ps1`）。无论哪种，适配器只需做一件事：
+拿到*最终回复文本* → 调用引擎。详见
+[docs/DESIGN.zh-CN.md §7 扩展](docs/DESIGN.zh-CN.md#7-扩展)。
+
+## License
+
+MIT — 见 [LICENSE](LICENSE)。
+
+[NaturalVoiceSAPIAdapter]: https://github.com/gexgd0419/NaturalVoiceSAPIAdapter

package/adapters/dsh/install.ps1

@@ -0,0 +1,81 @@
+# install.ps1 — one-command installer for the DSH adapter
+# ========================================================
+# 1. copies engine/*.ps1 to ~/.dsh/hooks/
+# 2. copies speech-hook.js to ~/.dsh/profiles/web/plugins/
+# 3. registers the plugin in ~/.dsh/profiles/web/cordis.patch.yml (backs it up first)
+#
+# Usage:
+#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File install.ps1
+#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File install.ps1 -DshHome C:\Users\you\.dsh -PluginsDir C:\Users\you\.dsh\profiles\web\plugins
+#
+# After installing, restart the DSH web app (the profile tree is composed at boot).
+
+param(
+    [string]$DshHome = (Join-Path $env:USERPROFILE '.dsh'),
+    [string]$EngineDir = '',
+    [string]$PluginsDir = ''
+)
+
+$ErrorActionPreference = 'Stop'
+$here = Split-Path -Parent $MyInvocation.MyCommand.Path
+$repoRoot = Resolve-Path (Join-Path $here '..\..')
+
+if (-not $EngineDir) { $EngineDir = Join-Path $DshHome 'hooks' }
+if (-not $PluginsDir) { $PluginsDir = Join-Path $DshHome 'profiles\web\plugins' }
+$cordisPatch = Join-Path $DshHome 'profiles\web\cordis.patch.yml'
+
+# ---------- 1. engine ----------
+Write-Host "==> Installing engine -> $EngineDir"
+New-Item -ItemType Directory -Force -Path $EngineDir | Out-Null
+Copy-Item -Force (Join-Path $repoRoot 'engine\*.ps1') $EngineDir
+Write-Host "    copied: $((Get-ChildItem (Join-Path $repoRoot 'engine\*.ps1')).Count) script(s)"
+
+# ---------- 2. plugin ----------
+Write-Host "==> Installing DSH plugin -> $PluginsDir"
+New-Item -ItemType Directory -Force -Path $PluginsDir | Out-Null
+Copy-Item -Force (Join-Path $here 'speech-hook.js') $PluginsDir
+$pluginUrl = 'file:///' + ((Join-Path $PluginsDir 'speech-hook.js') -replace '\\', '/' -replace ' ', '%20')
+
+# ---------- 3. register in cordis.patch.yml ----------
+Write-Host "==> Registering plugin in cordis.patch.yml"
+if (Test-Path $cordisPatch) {
+    $existing = Get-Content $cordisPatch -Raw -Encoding UTF8
+    if ($existing -match '(?m)^\s*- id:\s*speech-hook\b') {
+        Write-Host "    speech-hook already registered — skipping (nothing to do)."
+        Write-Host ""
+        Write-Host "Done. Restart the DSH web app to pick up the plugin."
+        exit 0
+    }
+    # backup before modifying
+    $backup = "$cordisPatch.bak-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
+    Copy-Item $cordisPatch $backup
+    Write-Host "    backup -> $backup"
+    $block = @"
+
+# speech-hook: auto voice-announce assistant replies (installed by dsh-speak)
+- insert:
+    - id: speech-hook
+      name: '$pluginUrl'
+"@
+    Add-Content -Path $cordisPatch -Value $block -Encoding UTF8
+    Write-Host "    appended insert entry -> $cordisPatch"
+} else {
+    New-Item -ItemType Directory -Force -Path (Split-Path $cordisPatch) | Out-Null
+    $content = @"
+# dsh profile patch layer (created by dsh-speak installer)
+# speech-hook: auto voice-announce assistant replies
+- insert:
+    - id: speech-hook
+      name: '$pluginUrl'
+"@
+    Set-Content -Path $cordisPatch -Value $content -Encoding UTF8
+    Write-Host "    created -> $cordisPatch"
+}
+
+Write-Host ""
+Write-Host "Installed. Next steps:"
+Write-Host "  1. Restart the DSH web app (profile tree is composed at boot)."
+Write-Host "  2. Verify voices: run"
+Write-Host "     powershell -NoProfile -ExecutionPolicy Bypass -File `"$EngineDir\speak.ps1`" -Text `"你好，语音播报已就绪。`""
+Write-Host "  3. If no sound: install NaturalVoiceSAPIAdapter and register natural voices"
+Write-Host "     (see README.md -> Prerequisites)."

package/adapters/dsh/speech-hook.js

@@ -0,0 +1,133 @@
+// speech-hook.js — DSH web adapter: auto voice-announce the final assistant reply
+// ==============================================================================
+// Listens to the session event stream (session/event), watches for
+// assistant/message append events, extracts the final reply text, and hands it to
+// engine/speak.ps1 through a hidden, non-blocking powershell process.
+//
+// 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
+//   * a final reply with no following tool/call is announced after a throttle
+//     delay (merges multi-step messages from the same reply)
+//
+// Registration: add an insert entry in ~/.dsh/profiles/web/cordis.patch.yml —
+//   - insert:
+//       - id: speech-hook
+//         name: 'dsh-speak'                       # npm package (preferred)
+//         name: 'file:///C:/Users/<you>/.../speech-hook.js'   # repo/file install
+// (run adapters/dsh/install.ps1 to do this automatically for the file install)
+//
+// Configuration (environment variables, optional):
+//   DSH_SPEAK_ENGINE      path to engine/speak.ps1
+//                         (default: <package>/engine/speak.ps1, then
+//                          %USERPROFILE%\.dsh\hooks\speak.ps1)
+//   DSH_SPEAK_THROTTLE_MS throttle delay before announcing (default: 1500)
+'use strict'
+const { spawn } = require('child_process')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+// diagnostic log (for troubleshooting; safe to remove once stable)
+const LOG = path.join(os.tmpdir(), 'dsh-speech-hook.log')
+function log(...args) {
+  try {
+    fs.appendFileSync(LOG, `[${new Date().toISOString()}] ${args.join(' ')}\n`)
+  } catch (e) { /* ignore */ }
+}
+
+const THROTTLE_MS = Number(process.env.DSH_SPEAK_THROTTLE_MS) || 1500
+
+/**
+ * Locate engine/speak.ps1:
+ *   1. explicit DSH_SPEAK_ENGINE override
+ *   2. <this package>/engine/speak.ps1 — works both when running from a repo
+ *      checkout and when installed into a profile's node_modules (npm install)
+ *   3. legacy file-copy location (~/.dsh/hooks/speak.ps1) from install.ps1
+ */
+function resolveEngine() {
+  if (process.env.DSH_SPEAK_ENGINE) return process.env.DSH_SPEAK_ENGINE
+  const bundled = path.join(__dirname, '..', '..', 'engine', 'speak.ps1')
+  if (fs.existsSync(bundled)) return bundled
+  return path.join(process.env.USERPROFILE, '.dsh', 'hooks', 'speak.ps1')
+}
+const SPEAK_ENGINE = resolveEngine()
+
+module.exports = {
+  apply(ctx) {
+    log('plugin apply 执行（加载成功）; engine=', SPEAK_ENGINE, '; throttle=', THROTTLE_MS)
+    let timer = null
+    let pendingText = ''
+
+    /** cancel a pending announcement (called when a tool-call round arrives) */
+    function cancelPending() {
+      if (timer) { clearTimeout(timer); timer = null }
+      pendingText = ''
+    }
+
+    function speak(text) {
+      log('speak 调用, 文本长度:', text ? text.length : 0)
+      if (!text || !text.trim()) return
+      const tmp = path.join(os.tmpdir(), `dsh-speech-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.txt`)
+      try {
+        fs.writeFileSync(tmp, text, 'utf8')
+      } catch (e) {
+        log('写临时文件失败:', e.message)
+        return
+      }
+      const ps = spawn('powershell.exe',
+        ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', SPEAK_ENGINE, '-File', tmp],
+        { windowsHide: true, stdio: 'ignore' })
+      log('spawn powershell 已发起')
+      ps.on('exit', (code) => { log('播报进程退出 code=', code); try { fs.unlinkSync(tmp) } catch (e) { /* 清理 */ } })
+      ps.on('error', (e) => { log('播报进程 error:', e.message); try { fs.unlinkSync(tmp) } catch (e2) { /* 清理 */ } })
+    }
+
+    ctx.on('session/event', (session, event) => {
+      try {
+        const type = event && event.type
+        // noise filter: assistant/chunk (streaming chunks) is not recorded
+        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)
+        if (type === 'tool/call') {
+          cancelPending()
+          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 })
+        const msg = event.data && (event.data.message || event.data)
+        if (!msg) return
+        let text = ''
+        const c = msg.content
+        if (typeof c === 'string') {
+          text = c
+        } else if (Array.isArray(c)) {
+          // only text blocks: reasoning / tool_use blocks are not announced
+          text = c
+            .filter(b => b && b.type === 'text' && typeof b.text === 'string')
+            .map(b => b.text)
+            .join('')
+        }
+        if (!text.trim()) return
+        log('缓存待播报文本长度:', text.length, '前 60:', text.slice(0, 60))
+        pendingText = text
+        if (timer) clearTimeout(timer)
+        // throttle: merge multi-step messages of one reply; a tool/call in
+        // between cancels the announcement
+        timer = setTimeout(() => {
+          speak(pendingText)
+          pendingText = ''
+          timer = null
+        }, THROTTLE_MS)
+      } catch (e) {
+        log('事件处理异常:', e.message)
+      }
+    })
+  },
+}

package/docs/DESIGN.md

@@ -0,0 +1,245 @@
+# DESIGN.md — dsh-speak: voice announcements for AI coding harnesses
+
+English · [中文](DESIGN.zh-CN.md)
+
+Status: **draft** — this document describes the current (proven) local implementation
+and the target generic structure of this repository. It is the reference for the
+README.
+
+---
+
+## 1. Why
+
+Agentic coding tools run long tasks (builds, tests, migrations, batch edits) while
+you work on something else. When a reply finally lands you have to keep checking
+the screen. **dsh-speak** reads the final reply aloud through Windows speech
+synthesis so you know *without looking* that a long task finished — and what its
+outcome was.
+
+The original implementation was built and proven in a local DSH (DeepSeek Harness)
+setup. This repository generalizes that working implementation into:
+
+- a **harness-agnostic engine** (PowerShell + Windows SAPI5) that any process can call,
+- **adapter layers** that turn harness-specific events into engine calls
+  (DSH session events, Claude Code Stop hooks, ...).
+
+## 2. Goals / non-goals
+
+Goals:
+
+- One-command install for DSH users (engine + plugin + registration).
+- Engine callable from any harness via a trivial command line.
+- Best-effort speech: never throws, never blocks a harness, never breaks a session.
+- Natural-sounding voices: Windows 11 built-in natural voice packs, or
+  NaturalVoiceSAPIAdapter on Windows 10; graceful fallback to stock voices.
+
+Non-goals (for now):
+
+- Cross-platform engines (macOS/Linux TTS). Windows-only by design.
+- In-repo packaging of NaturalVoiceSAPIAdapter (Windows 10 only) or voice data —
+  they are prerequisites, not bundled.
+- Streaming/queued playback, per-voice audio files, non-Chinese voice curation.
+
+## 3. Architecture
+
+```
+            +--------------------------------------------------------------+
+            |                         harness                               |
+            |   (DSH web app  |  Claude Code  |  anything with a shell)     |
+            +--------+-----------------------------+-----------------------+
+                     |                             |
+                     | session events              | Stop hook JSON (stdin)
+                     v                             v
+            +------------------+         +--------------------------+
+            |  adapters/dsh/   |         | adapters/claude-code/    |
+            |  speech-hook.js  |         | stop-hook.ps1            |
+            |  (event filter,  |         | (transcript extraction)  |
+            |   throttle,      |         +------------+-------------+
+            |   cancel)        |                      |
+            +--------+---------+                      |
+                     | text                           | text
+                     v                                v
+            +---------------------------------------------------------------+
+            |                   engine/speak.ps1  (harness-agnostic)        |
+            |   text -> clean (markdown/emoji/length) -> SAPI5 Speak()      |
+            +---------------------------------------------------------------+
+                     |
+                     v
+            Windows SAPI5 (System.Speech) — voices:
+              * preferred: a natural voice — Windows 11 built-in pack, or one
+                registered by NaturalVoiceSAPIAdapter on Windows 10
+                (e.g. "Microsoft Xiaoxiao")
+              * fallback:  any zh voice (e.g. "Microsoft Huihui")
+```
+
+### 3.1 Engine — `engine/speak.ps1`
+
+The only file a new adapter needs. Two input modes: `-Text "..."` inline, or
+`-File C:\path\msg.txt` (UTF-8). Also `-Volume`, `-Rate`, `-MaxChars`,
+`-LongTextMessage` (see §5).
+
+Processing pipeline (in order):
+
+1. **Read** text (file read is always UTF-8).
+2. **Strip markdown** — code blocks, inline code, links, bare URLs, emphasis chars.
+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: `本次播报内容较长，请自行阅读。`).
+6. **Speak** — `System.Speech.Synthesis.SpeechSynthesizer`, volume/rate applied,
+   best zh natural voice selected, then `Speak()`.
+
+Engine contract for adapters:
+
+- exit 0 always; never writes to stdout/stderr on failure paths;
+- synchronous (returns when the utterance finishes, or immediately on any failure);
+- safe to call from a sandboxed process *provided* the caller does not need to nest
+  another `powershell.exe` inside a harness sandbox (see §6.3).
+
+### 3.2 DSH adapter — `adapters/dsh/speech-hook.js`
+
+A DSH web-profile plugin (Cordis plugin) registered via `cordis.patch.yml`. DSH has
+no "reply finished" hook, so the plugin observes the session event stream:
+
+- listens to `session/event`;
+- filters `assistant/message` events with `surfaceOp == 'append'`;
+- extracts only `text` content blocks (reasoning / tool_use blocks are skipped);
+- buffers the text and starts a throttle timer (default 1500 ms) to merge
+  multi-step messages of one reply;
+- a `tool/call` event **cancels** the pending announcement — that round's assistant
+  text is process narration, not the final reply;
+- on fire: writes the text to a temp file and `spawn`s
+  `powershell.exe -File <engine> -File <tmp>` with `windowsHide` + `stdio: 'ignore'`
+  so the harness is never blocked; the temp file is deleted on exit.
+
+Registration snippet (also automated by `install.ps1`):
+
+```yaml
+# ~/.dsh/profiles/web/cordis.patch.yml
+- insert:
+    - id: speech-hook
+      name: 'file:///C:/Users/<you>/.dsh/profiles/web/plugins/speech-hook.js'
+```
+
+> Node's ESM loader does not accept Windows absolute paths as plugin names — the
+> `file:///C:/...` URL form is required.
+
+### 3.3 Claude Code adapter — `adapters/claude-code/stop-hook.ps1`
+
+Claude Code *does* have a Stop hook. The hook JSON (with `transcript_path`) arrives
+on stdin; the script scans the transcript backwards for the last assistant message
+that contains text (the final entry is often a pure tool call), writes it to a temp
+file and launches the engine in its own hidden powershell process, so the hook
+returns immediately. (Async spawning is safe here — the nested-spawn restriction in
+§6.3 is specific to DSH's sandbox.)
+
+## 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) |
+
+## 5. Configuration reference
+
+### Engine (`speak.ps1` parameters)
+
+| param             | default                     | meaning                                  |
+| ----------------- | --------------------------- | ---------------------------------------- |
+| `-Text`           | `''`                        | inline text (used when `-File` is empty) |
+| `-File`           | `''`                        | UTF-8 file to read                       |
+| `-Volume`         | `50`                        | 0–100                                    |
+| `-Rate`           | `1`                         | speech rate (SAPI scale)                 |
+| `-MaxChars`       | `300`                       | beyond this, replaced by `LongTextMessage` |
+| `-LongTextMessage`| `本次播报内容较长，请自行阅读。` | spoken instead of over-long text         |
+
+### DSH plugin (environment variables)
+
+| var                  | default                                  | meaning                        |
+| -------------------- | ---------------------------------------- | ------------------------------ |
+| `DSH_SPEAK_ENGINE`   | `%USERPROFILE%\.dsh\hooks\speak.ps1`     | engine path                    |
+| `DSH_SPEAK_THROTTLE_MS` | `1500`                                | merge delay before announcing  |
+
+## 6. Pitfalls (hard-won; do not "fix" casually)
+
+| # | pitfall | symptom | fix / rule |
+|---|---------|---------|------------|
+| 6.1 | Emoji / surrogate pairs reach `Speak()` | **silent** — no audio, no error | strip non-CJK/ASCII before speaking (engine step 3) |
+| 6.2 | Text longer than the adapter's per-`Speak` ceiling (~375–470 chars) | **silent** — the whole utterance is dropped, not truncated | length guard at 300 chars (engine step 5) |
+| 6.3 | Nested `Start-Process powershell` inside a DSH-sandboxed process | silent failure, no exception | keep the DSH chain synchronous at the adapter boundary (spawn once from the plugin; `speech-summary.ps1` calls `speak.ps1` synchronously) |
+| 6.4 | Plugin name with a raw Windows path in `cordis.patch.yml` | plugin fails to load | `file:///C:/...` URL form |
+| 6.5 | Matching adapter voices by name only | falls back to robotic stock voice | match `Name + Description` against `Natural\|Online` |
+| 6.6 | Reading/writing speech text as ANSI | mojibake or empty speech | always UTF-8 (`[System.IO.File]::ReadAllText(..., UTF8)`) |
+
+## 7. Extending
+
+### New engine backend
+The engine is the single seam for TTS backends. A future `speak-edge.ps1` could
+wrap `edge-tts`, or a `speak-piper.ps1` a local offline model — same parameter
+contract, same cleaning pipeline, swap the `Speak()` step. Adapters never change.
+
+### New harness adapter
+Implement: *capture the final reply text → call the engine*. DSH (event stream),
+Claude Code (Stop hook), and any shell-based harness (`speech-summary.ps1` called
+by the agent) are the three reference patterns.
+
+## 8. Scope
+
+This project is intentionally **not** a living product. It documents one proven way
+to give a harness a voice: a small engine + the two adapter patterns (event-stream
+and stop-hook) that worked. If you need more (voice management UI, more backends,
+cross-platform), treat the engine as the seam and build on top — this repository
+stays as a minimal, self-contained reference implementation.
+
+## 9. Publishing as an npm plugin (appendix)
+
+The DSH plugin mechanism is Cordis-based, and the official install path for
+out-of-tree plugins is `dsh plugin --profile web add <package>` (pnpm-managed
+dependencies in the profile). This repository is prepared for that path:
+
+### Package layout
+
+- `package.json` — `name: dsh-speak`, `main: adapters/dsh/speech-hook.js`,
+  `files` whitelists exactly what ships (plugin, `engine/*.ps1`, `install.ps1`,
+  docs, license). `prepublishOnly` runs `node --check` on the plugin.
+- The plugin entry is the same CJS module (`module.exports = { apply(ctx) }`)
+  already used by the file install — no code change is needed to publish.
+
+### Engine resolution (npm vs file install)
+
+`speech-hook.js` locates `engine/speak.ps1` in this order:
+
+1. `DSH_SPEAK_ENGINE` environment 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).
+
+Because the engine rides inside the npm package, `dsh plugin --profile web add
+dsh-speak` alone is sufficient — no separate copying step.
+
+### Publish steps (maintainer)
+
+```powershell
+npm login --registry=https://registry.npmjs.org   # official registry, 2FA required
+npm publish                                       # publishConfig.registry pins the official registry
+# bump "version" in package.json before every subsequent publish
+```
+
+> China note: if your global `.npmrc` points at a mirror (`registry.npmmirror.com`
+> etc.), `npm login`/`npm publish` would target the mirror, which does **not**
+> accept publishes. The package's `publishConfig.registry` pins publishing to the
+> official registry; just make sure the login used the official registry too.
+
+### Install steps (DSH user)
+
+```powershell
+dsh plugin --profile web add dsh-speak
+# then register in ~/.dsh/profiles/web/cordis.patch.yml:
+#   - insert:
+#       - id: speech-hook
+#         name: 'dsh-speak'
+# restart the DSH web app
+```

package/docs/DESIGN.zh-CN.md

@@ -0,0 +1,232 @@
+# DESIGN.zh-CN.md — dsh-speak：为 AI 编程 harness 提供语音播报
+
+状态：**草稿** — 本文档描述当前（已验证的）本地实现与本文档仓库的目标通用结构，
+是 README 的参考依据。
+
+（英文版：docs/DESIGN.md）
+
+---
+
+## 1. 为什么
+
+Agent 工具会跑长任务（构建、测试、迁移、批量修改），而你正在忙别的。回复终于落地时，
+你不得不反复看屏幕。**dsh-speak** 通过 Windows 语音合成把最终回复读出来，让你
+*不用看屏幕* 就知道长任务完成了——以及结果是什么。
+
+最初实现是在本地 DSH（DeepSeek Harness）环境里搭建并验证过的。本仓库把这份可用的
+实现通用化为：
+
+- **与 harness 无关的引擎**（PowerShell + Windows SAPI5），任意进程都可调用；
+- **适配层**，把 harness 专属事件转成引擎调用（DSH 会话事件、Claude Code Stop hook…）。
+
+## 2. 目标 / 非目标
+
+目标：
+
+- DSH 用户一键安装（引擎 + 插件 + 注册）。
+- 引擎可通过一行命令行从任意 harness 调用。
+- 尽力而为的播报：绝不抛错、绝不阻塞 harness、绝不破坏会话。
+- 自然语音：Windows 11 内置自然语音包，或 Windows 10 上经 NaturalVoiceSAPIAdapter
+  注册；优雅回退到系统自带语音。
+
+非目标（当前阶段）：
+
+- 跨平台引擎（macOS/Linux TTS）。设计上仅限 Windows。
+- 在仓库内打包 NaturalVoiceSAPIAdapter（仅 Windows 10 需要）或语音数据——
+  它们是前置依赖，不打进仓库。
+- 流式/队列播放、按音色输出音频文件、非中文音色管理。
+
+## 3. 架构
+
+```
+            +--------------------------------------------------------------+
+            |                         harness                              |
+            |   (DSH web 应用  |  Claude Code  |  任何有 shell 的东西)     |
+            +--------+-----------------------------+-----------------------+
+                     |                             |
+                     | 会话事件                     | Stop hook JSON (stdin)
+                     v                             v
+            +------------------+         +--------------------------+
+            |  adapters/dsh/   |         | adapters/claude-code/    |
+            |  speech-hook.js  |         | stop-hook.ps1            |
+            |  (事件过滤、     |         | (transcript 提取)        |
+            |   节流、取消)    |         +------------+-------------+
+            +--------+---------+                      |
+                     | 文本                           | 文本
+                     v                                v
+            +---------------------------------------------------------------+
+            |               engine/speak.ps1  （与 harness 无关）           |
+            |   文本 -> 清洗(markdown/emoji/长度) -> SAPI5 Speak()          |
+            +---------------------------------------------------------------+
+                     |
+                     v
+            Windows SAPI5 (System.Speech) — 音色：
+              * 优先：自然语音 — Windows 11 内置语音包，或 Windows 10 上经
+                NaturalVoiceSAPIAdapter 注册（如 "Microsoft Xiaoxiao"）
+              * 回退：任意 zh 语音（如 "Microsoft Huihui"）
+```
+
+### 3.1 引擎 — `engine/speak.ps1`
+
+新适配器唯一需要打交道的文件。两种输入模式：`-Text "..."` 直接传入，或
+`-File C:\path\msg.txt`（UTF-8）。另有 `-Volume`、`-Rate`、`-MaxChars`、
+`-LongTextMessage`（见 §5）。
+
+处理管线（按顺序）：
+
+1. **读取**文本（读文件一律 UTF-8）。
+2. **剥离 markdown** — 代码块、行内代码、链接、裸 URL、强调符号。
+3. **剥离 emoji / 不可打印字符** — 只保留中文汉字、中文标点、全角区间、
+   ASCII 可打印（正则 `[^一-龥　-〿＀-￯ - -~]`）。
+4. **压缩空白。**
+5. **长度守卫** — 清洗后文本超过 `MaxChars`（默认 300）时，替换为
+   `LongTextMessage`（默认：`本次播报内容较长，请自行阅读。`）。
+6. **朗读** — `System.Speech.Synthesis.SpeechSynthesizer`，应用音量/语速，
+   选择最佳 zh 自然语音，然后 `Speak()`。
+
+引擎对适配器的契约：
+
+- 总是以 0 退出；失败路径不向 stdout/stderr 写内容；
+- 同步（读完整个句子才返回，或任何失败时立即返回）；
+- 沙箱进程可安全调用，*前提* 是调用方不需要在 harness 沙箱内再嵌套一个
+  `powershell.exe`（见 §6.3）。
+
+### 3.2 DSH 适配层 — `adapters/dsh/speech-hook.js`
+
+一个 DSH web 配置插件（Cordis 插件），通过 `cordis.patch.yml` 注册。DSH 没有
+"回复完成" hook，所以插件观察会话事件流：
+
+- 监听 `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` 也会自动完成）：
+
+```yaml
+# ~/.dsh/profiles/web/cordis.patch.yml
+- insert:
+    - id: speech-hook
+      name: 'file:///C:/Users/<you>/.dsh/profiles/web/plugins/speech-hook.js'
+```
+
+> Node 的 ESM 加载器不接受 Windows 绝对路径作为插件名——必须用
+> `file:///C:/...` URL 形式。
+
+### 3.3 Claude Code 适配层 — `adapters/claude-code/stop-hook.ps1`
+
+Claude Code *确实*有 Stop hook。hook JSON（含 `transcript_path`）从 stdin 传入；
+脚本从后往前扫描 transcript，找最后一条含文本的 assistant 消息（末尾常常是纯
+工具调用），写入临时文件后在自己独立的隐藏 powershell 进程里启动引擎，hook 立即
+返回。（此处异步 spawn 是安全的——§6.3 的嵌套限制仅存在于 DSH 沙箱内。）
+
+## 4. 事件流真值表（DSH）
+
+| assistant 轮次包含                | 是否播报 |
+| --------------------------------- | -------- |
+| 最终文本回复，无工具调用          | ✅ 节流后播报 |
+| 文本 + tool/call(s)               | ❌（取消——旁白） |
+| 只有 reasoning，无文本            | ❌（无 text 块） |
+| 流式分块                          | ❌（被过滤） |
+
+## 5. 配置参考
+
+### 引擎（`speak.ps1` 参数）
+
+| 参数 | 默认值 | 含义 |
+| ---- | ------ | ---- |
+| `-Text` | `''` | 内联文本（`-File` 为空时使用） |
+| `-File` | `''` | 要读取的 UTF-8 文件 |
+| `-Volume` | `50` | 0–100 |
+| `-Rate` | `1` | 语速（SAPI 刻度） |
+| `-MaxChars` | `300` | 超过此长度时替换为 `LongTextMessage` |
+| `-LongTextMessage` | `本次播报内容较长，请自行阅读。` | 超长文本时改念这句 |
+
+### DSH 插件（环境变量）
+
+| 变量 | 默认值 | 含义 |
+| ---- | ------ | ---- |
+| `DSH_SPEAK_ENGINE` | `%USERPROFILE%\.dsh\hooks\speak.ps1` | 引擎路径 |
+| `DSH_SPEAK_THROTTLE_MS` | `1500` | 播报前的合并延迟（毫秒） |
+
+## 6. 踩坑记录（来之不易；不要随意"修复"）
+
+| # | 坑 | 现象 | 修复/规则 |
+|---|-----|------|-----------|
+| 6.1 | emoji / 代理对进入 `Speak()` | **静默**——没声音也没报错 | 朗读前剥离非 CJK/ASCII 字符（引擎第 3 步） |
+| 6.2 | 文本超过适配器单次 `Speak` 上限（约 375–470 字） | **静默**——整段被丢弃，而不是截断 | 300 字长度守卫（引擎第 5 步） |
+| 6.3 | 在 DSH 沙箱进程内嵌套 `Start-Process powershell` | 静默失败，无异常 | DSH 链路在适配器边界保持同步（插件只 spawn 一次；`speech-summary.ps1` 同步调用 `speak.ps1`） |
+| 6.4 | `cordis.patch.yml` 里插件名用 Windows 原始路径 | 插件加载失败 | 用 `file:///C:/...` URL 形式 |
+| 6.5 | 只按名字匹配适配器音色 | 回退到机械感的系统语音 | 用 `Name + Description` 匹配 `Natural\|Online` |
+| 6.6 | 用 ANSI 读写播报文本 | 乱码或完全无声 | 一律 UTF-8（`[System.IO.File]::ReadAllText(..., UTF8)`） |
+
+## 7. 扩展
+
+### 新的引擎后端
+引擎是 TTS 后端的唯一接缝。未来可以加 `speak-edge.ps1`（封装 `edge-tts`）或
+`speak-piper.ps1`（本地离线模型）——同样的参数契约、同样的清洗管线，只换
+`Speak()` 这一步。适配层永远不用改。
+
+### 新的 harness 适配层
+实现思路：*捕获最终回复文本 → 调用引擎*。DSH（事件流）、Claude Code（Stop
+hook）、任意 shell harness（Agent 自己调 `speech-summary.ps1`）就是三种参考范式。
+
+## 8. 项目定位
+
+本项目**刻意不是**一个持续迭代的产品。它记录了一条被验证过的、让 harness
+开口说话的实现路径：一个小引擎 + 两种可复用的适配范式（事件流 / Stop hook）。
+如果你需要更多（音色管理界面、更多后端、跨平台），把引擎当作接缝在其上扩展——
+本仓库保持为最小、自包含的参考实现。
+
+## 9. 发布为 npm 插件（附录）
+
+DSH 的插件机制基于 Cordis，官方安装树外插件的路径是
+`dsh plugin --profile web add <包名>`（由 pnpm 管理 profile 依赖）。本仓库已为
+该路径做好准备：
+
+### 包结构
+
+- `package.json` — `name: dsh-speak`，`main: adapters/dsh/speech-hook.js`，
+  `files` 白名单精确列出发布内容（插件、`engine/*.ps1`、`install.ps1`、文档、
+  LICENSE）。`prepublishOnly` 会对插件跑 `node --check`。
+- 插件入口就是文件安装已用的同一个 CJS 模块（`module.exports = { apply(ctx) }`）
+  ——发布**不需要改任何代码**。
+
+### 引擎解析（npm 安装 vs 文件安装）
+
+`speech-hook.js` 按以下顺序定位 `engine/speak.ps1`：
+
+1. `DSH_SPEAK_ENGINE` 环境变量覆盖；
+2. 相对插件文件解析 `<包>/engine/speak.ps1`——同时覆盖仓库检出和
+   `npm install` 后的 `node_modules/dsh-speak/`；
+3. 旧的 `%USERPROFILE%\.dsh\hooks\speak.ps1`（文件安装的位置）。
+
+因为引擎随 npm 包分发，用户只需 `dsh plugin --profile web add dsh-speak`
+一条命令，无需额外拷贝。
+
+### 发布步骤（维护者）
+
+```powershell
+npm login --registry=https://registry.npmjs.org   # 官方源，npm 强制要求 2FA
+npm publish                                       # publishConfig.registry 已锁定官方源
+# 后续每次发布前先在 package.json 里 bump "version"
+```
+
+> 中国区注意：如果你的全局 `.npmrc` 指向镜像（如 `registry.npmmirror.com`），
+> `npm login`/`npm publish` 会打到镜像站——镜像**不接受发布**。本包的
+> `publishConfig.registry` 已把发布锁定到官方源；登录时也要用官方源。
+
+### 安装步骤（DSH 用户）
+
+```powershell
+dsh plugin --profile web add dsh-speak
+# 然后在 ~/.dsh/profiles/web/cordis.patch.yml 注册：
+#   - insert:
+#       - id: speech-hook
+#         name: 'dsh-speak'
+# 重启 DSH web 应用
+```

package/engine/speak.ps1

@@ -0,0 +1,76 @@
+# speak.ps1 — Harness-agnostic speech engine (Windows SAPI5 + NaturalVoiceSAPIAdapter)
+# ====================================================================================
+# Reads text (inline or from a UTF-8 file), cleans it for speech synthesis, and reads
+# it aloud through Windows SAPI5, preferring natural voices registered by
+# NaturalVoiceSAPIAdapter (https://github.com/gexgd0419/NaturalVoiceSAPIAdapter).
+#
+# This script knows NOTHING about any harness (DSH, Claude Code, ...). Any process
+# can call it:
+#
+#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File speak.ps1 -Text "hello"
+#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File speak.ps1 -File C:\tmp\msg.txt
+#
+# It is best-effort by design: it never throws, never blocks the caller for longer
+# than the utterance itself, and exits 0 even if something failed.
+#
+# Design notes (see docs/DESIGN.md for full rationale):
+#   * Markdown symbols, URLs and emoji are stripped before speaking — SAPI5 Speak()
+#     silently fails (produces no audio, no error) when it hits emoji/surrogates.
+#   * NaturalVoiceSAPIAdapter has a per-Speak character ceiling (~375-470 chars);
+#     beyond that it silently speaks nothing. Text longer than $MaxChars is replaced
+#     with $LongTextMessage instead.
+#   * Adapter-registered voices often have plain names ("Microsoft Xiaoxiao") that do
+#     not contain the word "Natural", so matching checks Name + Description.
+# ====================================================================================
+
+param(
+    [string]$Text = '',
+    [string]$File = '',
+    [int]$Volume = 50,
+    [int]$Rate = 1,
+    [int]$MaxChars = 300,
+    [string]$LongTextMessage = '本次播报内容较长，请自行阅读。'
+)
+
+# ---------- input: pick text source ----------
+if ($File) {
+    if (-not (Test-Path $File)) { exit 0 }
+    $text = [System.IO.File]::ReadAllText($File, [System.Text.Encoding]::UTF8)
+} else {
+    $text = [string]$Text
+}
+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, '[^一-龥　-〿＀-￯ - -~]', '')
+$text = $text -replace '\s+', ' '
+$text = $text.Trim()
+
+# ---------- length guard: adapter per-Speak ceiling ----------
+if ($text.Length -gt $MaxChars) { $text = $LongTextMessage }
+
+# ---------- speak ----------
+Add-Type -AssemblyName System.Speech
+$synth = New-Object System.Speech.Synthesis.SpeechSynthesizer
+$synth.Volume = $Volume
+
+# prefer a zh natural voice (NaturalVoiceSAPIAdapter-registered), fall back to any zh
+$voices = $synth.GetInstalledVoices()
+$voice = $voices | Where-Object {
+    $_.VoiceInfo.Culture.Name -like 'zh*' -and
+    ($_.VoiceInfo.Name + ' ' + $_.VoiceInfo.Description) -match 'Natural|Online'
+} | Select-Object -First 1
+if (-not $voice) { $voice = $voices | Where-Object { $_.VoiceInfo.Culture.Name -like 'zh*' } | Select-Object -First 1 }
+if ($voice) { $synth.SelectVoice($voice.VoiceInfo.Name) }
+
+$synth.Rate = $Rate
+$synth.Speak($text)
+exit 0

package/engine/speech-prompt.ps1

@@ -0,0 +1,22 @@
+# speech-prompt.ps1 — Short prompt announcement (synchronous, blocking)
+# Use when a harness/agent needs the user's attention (a question, an approval
+# request). Reads the text through engine/speak.ps1 and waits until it finishes,
+# so the caller knows the announcement was actually spoken.
+#
+#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File speech-prompt.ps1 -Text "请做出选择"
+
+param([string]$Text = '请做出选择')
+
+if (-not $Text) { exit 0 }
+
+$speak = Join-Path $PSScriptRoot 'speak.ps1'
+if (-not (Test-Path $speak)) { exit 0 }
+
+$tmp = Join-Path $env:TEMP ('speech-prompt-' + [guid]::NewGuid().ToString('N') + '.txt')
+try {
+    [System.IO.File]::WriteAllText($tmp, $Text, [System.Text.UTF8Encoding]::new($false))
+    & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $speak -File $tmp
+    exit $LASTEXITCODE
+} finally {
+    if (Test-Path $tmp) { Remove-Item $tmp -Force -ErrorAction SilentlyContinue }
+}

package/engine/speech-summary.ps1

@@ -0,0 +1,27 @@
+# speech-summary.ps1 — Reply summary announcement (synchronous, blocking)
+# For harnesses with no "reply finished" event (e.g. DSH has no Stop hook): the
+# agent calls this at the end of its final reply.
+#
+#   powershell.exe -NoProfile -ExecutionPolicy Bypass -File speech-summary.ps1 -Text "总结文本"
+#
+# NOTE: keep this SYNCHRONOUS. An earlier version spawned the inner powershell
+# asynchronously with Start-Process; DSH's sandbox blocks nested sub-process
+# spawning, so it silently produced no audio. The synchronous call chain
+# (summary -> speak.ps1) is the reliable path (cost: caller waits for the
+# utterance to finish).
+
+param([string]$Text = '')
+
+if (-not $Text) { exit 0 }
+
+$speak = Join-Path $PSScriptRoot 'speak.ps1'
+if (-not (Test-Path $speak)) { exit 0 }
+
+$tmp = Join-Path $env:TEMP ('speech-summary-' + [guid]::NewGuid().ToString('N') + '.txt')
+try {
+    [System.IO.File]::WriteAllText($tmp, $Text, [System.Text.UTF8Encoding]::new($false))
+    & powershell.exe -NoProfile -ExecutionPolicy Bypass -File $speak -File $tmp
+    exit $LASTEXITCODE
+} finally {
+    if (Test-Path $tmp) { Remove-Item $tmp -Force -ErrorAction SilentlyContinue }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "dsh-speak",
+  "version": "1.0.0",
+  "description": "Make your AI harness speak — verified voice announcements for DSH and other AI coding harnesses (Windows SAPI5 + natural voices)",
+  "main": "adapters/dsh/speech-hook.js",
+  "files": [
+    "adapters/dsh/speech-hook.js",
+    "adapters/dsh/install.ps1",
+    "engine/",
+    "docs/",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "tts",
+    "text-to-speech",
+    "voice",
+    "speech",
+    "voice-announcement",
+    "sapi5",
+    "windows",
+    "powershell"
+  ],
+  "scripts": {
+    "prepublishOnly": "node --check adapters/dsh/speech-hook.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Alan2Z/dsh-speak.git"
+  },
+  "author": "Alan2Z",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  }
+}