dsh-speak 1.5.0 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +131 -63
  2. package/README.zh-CN.md +125 -61
  3. package/adapters/dsh/speech-hook.js +486 -140
  4. package/client/client.js +304 -0
  5. package/docs/DESIGN.md +112 -31
  6. package/docs/DESIGN.zh-CN.md +98 -26
  7. package/engine/speak.ps1 +64 -15
  8. package/engine/speak.sh +58 -66
  9. package/package.json +36 -3
  10. package/docs/CUSTOMIZATION.md +0 -89
  11. package/docs/CUSTOMIZATION.zh-CN.md +0 -88
package/docs/CUSTOMIZATION.zh-CN.md DELETED
@@ -1,88 +0,0 @@
1
- # CUSTOMIZATION.zh-CN.md — dsh-speak 自定义指南
2
-
3
- （English: docs/CUSTOMIZATION.md）
4
-
5
- dsh-speak 刻意保持小巧，但提供三层自定义：**配置**（不改代码）、**引擎覆盖**（复制后改）、
6
- **扩展**（新后端 / 新适配器）。以下所有方式都不会被 `npm update` 覆盖。
7
-
8
- ---
9
-
10
- ## 一、配置（推荐）
11
-
12
- 在 profile patch 的 `config` 块里设置——`dsh --dump-config` 可见、按 profile 隔离、
13
- npm 更新永不覆盖：
14
-
15
- ```yaml
16
- # ~/.dsh/profiles/web/cordis.patch.yml
17
- - insert:
18
- - id: speech-hook
19
- name: 'dsh-speak'
20
- config:
21
- throttleMs: 1500 # 播报前的合并延迟（毫秒）
22
- engine: '' # 引擎路径覆盖；'' = 自动解析
23
- announceApprovals: true # 播报审批请求
24
- announceQuestions: true # 播报 ask_user_question 提问内容
25
- stripApprovalPrefix: true # 剥离审批原因里的 "escalate sandbox to ...: " 前缀
26
- longTextMode: message # message | heading（念最大字号 markdown 标题）
27
- maxChars: 300 # 引擎单次朗读字数上限
28
- volume: 50 # 仅 Windows
29
- rate: 0 # 0 = 引擎默认（Windows SAPI 刻度 / macOS wpm）
30
- ```
31
-
32
- ### 选项说明
33
-
34
- | 选项 | 默认值 | 效果 |
35
- | ---- | ------ | ---- |
36
- | `throttleMs` | `1500` | 回复文本等待多久才播报（合并同一回复的多步消息） |
37
- | `engine` | `''` | 显式引擎脚本路径；`''` 自动解析：包内 `engine/<平台>` → `~/.dsh/hooks/<平台>` |
38
- | `announceApprovals` | `true` | 播报 `approval/asked` 事件（审批原因，或固定提示语） |
39
- | `announceQuestions` | `true` | 把 `ask_user_question` 调用播报成"问题（单选/多选），选项：…" |
40
- | `stripApprovalPrefix` | `true` | 剥离审批原因里的固定英文模板前缀（`escalate sandbox to danger-full-access: `），保留中文说明 |
41
- | `longTextMode` | `message` | `message` = 超长念固定提示语；`heading` = 改念最大字号 markdown 标题（规则见下） |
42
- | `maxChars` | `300` | 引擎单次朗读上限（SAPI/NVSAPIAdapter 超过约 375-470 字会静默失败） |
43
- | `volume` | `50` | 仅 Windows（0-100）；macOS 音量跟随系统 |
44
- | `rate` | `0` | `0` = 引擎默认（Windows SAPI 刻度如 1；macOS words-per-minute 如 175） |
45
-
46
- ### 超长文本模式
47
-
48
- 清洗后文本超过 `maxChars` 时：
49
-
50
- - **`message`**（默认）：念 `LongTextMessage`（`本次播报内容较长，请自行阅读。`，
51
- 可用引擎参数 `-LongTextMessage` / `-l` 覆盖）。
52
- - **`heading`**：在原始文本里挑**最大字号**的 markdown 标题——`#` 数量最少者优先，
53
- 并列取第一个；没有标题行则取第一个非空行。选中的候选仍会清洗并受 `maxChars`
54
- 上限约束，若其本身仍超长则回退提示语。
55
-
56
- ---
57
-
58
- ## 二、引擎覆盖（复制后改）
59
-
60
- 想改"实际念出来的内容"（音色选择、清洗规则、默认参数），把引擎复制出包并指向你的副本：
61
-
62
- ```powershell
63
- # Windows
64
- Copy-Item "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-speak\engine\speak.ps1" "$env:USERPROFILE\.dsh\hooks\my-speak.ps1"
65
- # macOS
66
- cp ~/.dsh/profiles/web/node_modules/dsh-speak/engine/speak.sh ~/.dsh/hooks/my-speak.sh
67
- ```
68
-
69
- 然后在 config 里设引擎路径：
70
-
71
- ```yaml
72
- config:
73
- engine: 'C:/Users/<你>/.dsh/hooks/my-speak.ps1' # macOS 用 ~/.dsh/hooks/my-speak.sh
74
- ```
75
-
76
- `npm update` 永远不会碰你的副本。
77
-
78
- ---
79
-
80
- ## 三、扩展
81
-
82
- - **新引擎后端**：引擎是唯一接缝。新后端（`speak-edge.ps1` 封装 edge-tts、
83
- `speak-piper.ps1` 接本地模型……）保持同样的参数契约与清洗管线——适配层不用改。
84
- 见 [DESIGN.zh-CN.md §7](DESIGN.zh-CN.md#7-扩展)。
85
- - **新 harness 适配层**：拿到最终回复文本 → 调引擎。DSH（事件流）、Claude Code
86
- （Stop hook）、Agent 自调用（`speech-summary.ps1`）是三种参考范式。
87
- - **发布自己的变体**：fork 本仓库、按需调整、发布自己的 npm 包——`dsh.bundle`
88
- manifest 已让它天然支持 `dsh plugin add` 安装。