dsh-voice-alert

DSH（DeepSeek Harness）对话语音播报插件：一轮对话结束自动播报「完成」语音，出现错误 / 工具失败时播报「失败」语音。播放绝不改动系统音量或静音状态。

v0.4.3 关键修复：默认不再做「静音预热」 —— 实测发现预热会在播报前多开关一次音频端点， 打断蓝牙耳机上正在播放的音乐（v0.3.5 引入的副作用）。现在 prewarmMs: 0（默认不预热），需要时设回 350 可恢复旧行为；同时把 §5.1 的两个实战坑（默认设备登记 / 预热副作用）写清楚。

v0.4.1 / v0.4.2：waveOut 设为默认播放内核；python 解释器自动探测（跳过 WindowsApps 存根）；自测真实播放用例之间加等待、不再叠响。

v0.4.0 开源准备（可直接分发给别人，零配置开箱即用）：

默认提醒方式 = 🎵 音效：装完即用，不需要任何 API Key、不需要任何音频文件（20 个音效随包提供）。
默认播放内核 = waveOut / WAV（playerEngine: "wav"）：实测在蓝牙耳机下 不吞第一声、不打断正在播的音乐；由 ffmpeg 首次播放时自动转 WAV 并缓存（60ms / 200300KB）。旧内核 "mci"（DirectShow）保留为可选。
默认音色库为空：插件不内置任何具体音色（克隆音色是各人自己的）；想用自己的声音按 §4.1 填自己的音色 ID + Key，再一键生成三条语音。
个人路径全部中性化：originalsDir 默认在插件自己的数据目录内、ffmpegPath 默认走 PATH 探测、playerScript/volumeProbeScript 默认留空（只用自带播放器）。使用者无需改代码。
新增 .gitignore（排除 __pycache__ / config.json / 音频产物）。发布前已核查：无密钥、无用户名、无内网信息。

v0.3.9 备选播放内核 waveOut / WAV（默认仍是 MCI，行为零变化，config.playerEngine = "wav" 一键切换）：

为什么：主内核 MCI type mpegvideo 走 DirectShow，会创建播放图并打开音频端点；在蓝牙耳机上可能触发链路重协商，打断其他正在播放的音乐（用户 2026-09-16 反复反馈"播报/音效后音乐显示在播但没声音"）。waveOut（winsound）是 Windows 最基础的播放路径：不启 DirectShow 图、不枚举设备、不改端点格式，对链路和其他播放器冲击最小。
实现：新增 lib/play_wav_out.py（waveOut 播放器，含 350ms 静音预热 + 毫秒级阶段日志）；host 侧新增 ensureWavCache() 用 ffmpeg 一次性把 mp3 转成 WAV 并缓存（实测单文件 64ms / 236KB，源文件更新会自动重转），playKind/playSfx 在 wav 引擎下优先走它，任何失败自动回退 MCI，绝不因为换内核而静音。
实测：wav 内核 611ms 出声、总耗时 5.8s（与 MCI 的 605ms / 6.1s 相当）。
自测新增 12 组断言（内核解析/缓存路径/命令形状/真实转换/真实 wav 播放），全绿。

v0.3.8 延迟优化（用户要求：对话结束到出声更快）+ 延迟可测量：

预热与打开文件并行：静音预热放进子线程，主线程同时做 MCI open（实测 open 只要 38ms，现在完全被预热窗口吞掉）——唤醒效果不变。
实测：播放器进程启动 → 开始出声 = 610ms（其中预热 350ms + 链路稳定等待 150ms 是"第一次就有声"的代价）；加上 powershell/python 启动（约 200400ms），**对话结束到听见声音约 0.81.0 秒**。触发本身仍是 1ms 内（play launched 与 turn-end 同毫秒）。
毫秒级阶段日志：日志变成 [时间.毫秒] sfx-player: +610ms play issued rc=0，以后任何延迟疑问都能直接对着日志算，不用再猜。自测新增两条断言锁住「进程启动→出声 <900ms」和「open 发生在预热窗口内」。

v0.3.7 「强制重新生成」改成一次性（用户 2026-09-16 确认）：勾上后本次把三条语音全部重新合成（真实调用 TTS），提交成功后自动取消勾选；提交失败则保留勾选便于直接重试。标签改为「强制重新生成（仅本次）」并加了说明气泡。原来的坑：勾选框不会复位，勾一次后每次生成都强制重做三条、白耗额度。

顺带明确语义：不勾时插件比对每条语音的「指纹」（文案 + 音色 ID + 语速 + 音调 + 音量）——全都没变就复用现有 mp3、完全不调用 TTS；哪条变了只重做那一条；文件缺失也会自动重做。

v0.3.6 把「没声音怎么办」写进界面：总控卡「▶ 试听一下」正下方新增常驻提示（dva-audio-tip）——「点了试听没声音？把系统音量拖一下再点一次就有声了 —— 蓝牙耳机 / 虚拟声卡空闲挂起时，系统会把第一次播放吞掉，调音量正好把它唤醒」。

v0.3.5 修「刚生成语音后点试听没声音，调一下系统音量就有声音」（用户实测报告，根因探针实测非推测）：

实测证据：MCI open/play 返回码全 0、status position 正常推进（229→482→733→983 ms）、mode=playing、系统音量 35% 非静音——音频确实在"播放"；而同一时刻 Core Audio 探针（IMMDeviceEnumerator）读出默认输出设备 = 耳机 (EDIFIER Lolli Pro 5)，即蓝牙耳机（三个 role 一致）。蓝牙 A2DP 链路空闲后会挂起，这段时间 Windows 仍把音频"成功"送进驱动、耳机端不出声；调节系统音量会立刻激活链路——这正是"调一下音量之后就有声音"的来源。虚拟声卡端点未唤醒时同理。
修复：播放前先用 350 ms 静音预热默认端点（同步等待链路建立），再播真实音频；预热只播静音，不读写任何音量 / 静音接口（硬规则不变）。
顺带修一处旧缺陷：MCI play 的返回码此前被完全忽略，播放失败会被当成"播完了"（静默误报成功）。现在检查返回码，失败重试一次。
诊断留痕：播放全程写进插件日志（--log-file），含 prewarm ok / play_rc / positions —— 以后遇到无声可查 <data>\voice-alert.log 直接判断是"没播起来"还是"播了但端点没出声"。
若仍偶发无声：多半是蓝牙耳机 / 虚拟声卡的省电策略所致，可在「设备管理器 → 蓝牙适配器 → 电源管理」取消勾选"允许计算机关闭此设备以节约电源"，或改用有线耳机。

v0.3.4 依用户反馈再修（界面不再出现任何具体人名，插件可直接分发给别人用）：

音色名一律由使用者在「音色备注」里自己填（默认留空）；界面只叫「🎙 我的音色 · 语音合成」。
音效改成可勾选列表：20 个音效各占一行，行内三个勾选框（完成/失败/审批，同事件互斥）+ 音效名 + 「▶ 试听」。列表由 React 直接渲染，根治 v0.3.3「选了没反应」（下拉 option 被重渲染清空）。
一键生成 + 明确反馈：点「🎙 生成语音（一键更新）」会先自动保存文案再合成；运行中显示 x/y 进度，结束后明确显示「✅ 语音更新成功！已重新合成 N 条，复用 M 条」，失败显示「⚠️ 语音更新失败：… 合成出错」。
克隆入口写进界面：新增「克隆音色」行 + 两个链接——声音复刻控制台、产品介绍/开通。
修复「有时点试听没声音」：所有播放入口（引擎播报 / /preview / /sfx/play）串行化——等上一个播完再开下一个，避免两个 python+MCI 进程抢声卡导致后一个静默失败。

v0.3.3 新增音效提醒：内置 20 个音效（提醒 10：叮咚/电话铃/消息提示/闹钟/滴滴/清脆叮/钟声/成功号角/欢快音/木鱼；大自然 10：鸟鸣/蝉鸣/蛙鸣/雨声/海浪/溪流/风声/篝火/雷鸣/森林），设置页一个全局「提醒方式」三选：🗣 语音播报 / 🎵 音效 / 🔕 关闭。音效模式完全不调用 TTS、不需要 API Key；选音效时展开「完成 / 失败 / 审批」三个勾选（默认成功号角 / 木鱼 / 叮咚），每行可一键试听。详见 §4.2。

v0.3.3 同版修正：「🎙 我的音色 · 语音合成」卡常驻页面（不再藏进折叠区）——三条播报文案 + 试听 + 一键生成主按钮一目了然。

v0.3.2 设置页 UI 傻瓜化重做（lib/client.js）：中文优先字体（微软雅黑，标题 16px/正文 14px/行距 1.6）、卡片式分区（语音播报总控大卡 → 常用设置卡 → 「高级设置」折叠卡，默认收起）、主次分明的按钮布局（「▶ 试听一下」大按钮 + 强调色主按钮，hover/active 反馈）；高级项（文案/API Key/音色库/系统音量/日志）收进折叠面板，折叠只影响可见性、DOM 元素全部保留。

v0.3.1 在 DSH 原生设置页新增音色库能力（lib/client.js 渲染的「语音播报」分区，见 §4.1：克隆/预设双路由、批量导入、试合验证；v0.3.1 已移除 v0.3.0 的朗读面板）。

A DSH plugin that deterministically plays a fixed voice alert when a conversation turn finishes and a different one when something failed, plus a settings-section voice library.

功能总览 · At a glance（中英对照 / Bilingual）

播报事件 · Alert events

中文	English
每个 turn 结束自动播报「完成」语音	Plays a "done" voice when any conversation turn ends
turn 内出现错误（`agent/error` 或工具 `isError`）播报「失败」	Plays a "fail" voice when the turn had errors (`agent/error` or tool `isError`)
同 turn 只播一次（去重）、错误优先（不叠加完成）、错误播报节流（默认 5s）	Per-turn dedup, error-first (never stacks "done"), error throttling (5s default)
「失败」后 3s 内抑制「完成」防连声，可关闭	Suppresses "done" for 3s after a "fail" — no back-to-back sounds; disable with 0
用户中断（aborted）默认不播；子代理会话默认跳过，均可配置	User aborts silent by default; subagent sessions skipped — both configurable

三种提醒方式 · Three alert modes

中文	English
🗣 语音：用火山克隆音色朗读三条文案（完成/失败/审批）	🗣 Voice: cloned-voice TTS reads your three lines (done/fail/approval)
🎵 音效：内置 20 个音效（提醒 10 + 大自然 10），零配置、无需 API Key 开箱即用	🎵 SFX: 20 built-in sounds (10 alerts + 10 nature), zero config, no API key needed
🔕 关闭：完成/失败/审批都不提醒	🔕 Off: no alerts at all
每个音效可勾选「完成/失败/审批」任一事件并单独试听	Every SFX can be assigned to done/fail/approval (one event each) with per-row preview

音色库 · Voice library

中文	English
火山克隆音色 / 预设音色双路由（`seed-icl-2.0` / `seed-tts-2.0`），自动识别类型	Clone & preset TTS routing (`seed-icl-2.0` / `seed-tts-2.0`), type auto-detected
批量导入（多行 `ID,备注` 或 JSON）、自动去重、逐条试合验证	Batch import (`ID,note` lines or JSON) with dedup and trial-synthesis verification
生成指纹复用：文案/音色/语速/音调/音量没变就复用既有 mp3，零 TTS 消耗	Fingerprint reuse: unchanged text/voice/params reuse existing mp3s, zero TTS calls
默认音色库为空，音色名由使用者自填——不含任何具体人名	Empty default voice library, names filled in by the user — no personal data shipped

播放与兼容 · Playback & compatibility

中文	English
默认 waveOut/WAV 播放内核（不吞第一声、不打断蓝牙音乐），MCI 可选，失败自动回退	waveOut/WAV player by default (no lost first sound, doesn't cut Bluetooth music), MCI optional, auto-fallback
绝不改动系统音量或静音状态（winmm 原样播放）	Never touches system volume or mute state (winmm plays as-is)
播放进程经隐藏 PowerShell → Start-Process 独立拉起，DSH 会话销毁杀不到声音	Player spawned detached via hidden PowerShell → Start-Process, immune to session teardown
播放失败全线静默降级（缺文件→蜂鸣、异常→仅日志），绝不影响 DSH 运行	Silent fallback everywhere (missing file → beep, exceptions → log only), never affects DSH
蓝牙耳机专项适配：默认不预热（`prewarmMs: 0`）不再打断音乐，实测文档齐全	Bluetooth headset tuning: prewarm off by default (no music cuts), documented with measurements

界面与诊断 · UI & diagnostics

中文	English
DSH 原生设置页「语音播报」分区：总控卡 + 常用设置 + 高级折叠，中文优先字体	Native DSH settings section "语音播报": master card + common settings + collapsible advanced, CJK-first typography
毫秒级阶段日志（`<data>\voice-alert.log`），任何延迟/无声可对着日志定位	Millisecond stage logs (voice-alert.log) to pinpoint latency or silence
免凭据控制通道：写 `control.txt` 即触发真播，`status.json` 快照验收	Credential-free control: write `control.txt` to trigger a real play, read `status.json` to verify
278/299 项自测断言（含真实播放链路），HTTP 路由仅回环	278/299 self-check assertions incl. real playback; HTTP routes loopback-only

1. 它做什么

事件	语音	文件（默认优先播放增益版）
任意一个 turn 结束	完成	`voice-alert-complete-poetic-loud.mp3`
该 turn 内出现过错误（`agent/error` 或工具 `isError`）	失败	`voice-alert-fail-poetic-loud.mp3`
立即错误播报（工具失败/agent 报错当下，节流 5s）	失败	同上
手动验证（HTTP 路由）	完成/失败/审批	`voice-alert-approval-poetic-loud.mp3`

音频永不改动系统音量与静音状态：播放器用 winmm/MCI「原样播放」（系统多大就多大，系统静音就无声），不读写任何音频控制接口。响度问题通过音频文件本身解决（见 §4）。

2. 事件依据（官方源码实证，非猜测）

用途	事件	出处（已装官方包）
判「一个 turn 结束」	`session/event` 且 `event.type === "turn/end"`	`@deepseek-ai/dsh-agent-loop/lib/index.js:994`（`finally` 里 append `turn/end`）
识别 turn 开始（用于归属错误）	`session/event` 且 `event.type === "turn/start"`	同上 `:926`
判「出现错误」	`agent/error`，payload `{agent, turn, step, error}`	同上 `:863`（`throwError`），且在 `turn/end` 之前发出（`:991` → `:994`）
判「工具失败」	`tools/result` 的 `result.isError`	`@deepseek-ai/dsh-tools/lib/types/index.js:3287`（以 `exec.agent` 为 scope 派发）

关键结论：

turn/end 每个 turn 只发一次（不是每个 step），所以含大量工具调用的长任务只会按 turn 播报；含工具的一轮会话不会因为 step 多而重复播报。
agent/status（running→idle）只在「整个 agent 彻底空闲」时变化，不是每 turn 信号，因此没有采用。
session/event 的历史回放不发事件（构造函数种子不 emit，见 dsh-session/lib/index.js 注释），所以 DSH 重启 / 恢复会话不会误报。

3. 去重与错误优先（实现要点）

同一 turn 只播一次：以 sessionId#turn 为键登记，重复的 turn/end 直接忽略（缓存上限由 dedupeCacheSize 控制）。
错误优先：turn/start 打开该会话的 turn 记录；该 turn 内出现 agent/error 或 tools/result.isError 即把该 turn 标记为 errored； turn/end 时若已 errored → 只播失败，不叠加播完成。
错误节流：立即失败播报受 errorMinIntervalMs（默认 5000ms）约束，同一时间窗内只播一次。
断「失败+完成」连声（2026-09-15 新增）：任意 fail 语音播出后 suppressCompleteAfterFailMs（默认 3000ms）之内， turn/end 的 complete 一律抑制并记日志（suppressedComplete 计数）。两个开关彼此独立：errorMinIntervalMs 管 fail 自身节流， suppressCompleteAfterFailMs 只管「fail 之后是否还允许立刻播 complete」；设 0 关闭本闸门。实测场景（宿主日志 2026-09-15 11:28:23）：agent/error 播 fail 后 0.26s，同 turn 的 turn/end 又播 complete → 本闸门消除。
turn/end 的 reason 映射：completed / max-tokens → 完成；error / blocked → 失败；aborted（用户中断）默认不播（abortPlays: none|complete|fail）。
子代理会话默认不播：按会话 header 的 origin === "subagent" / delegationDepth > 0 判定（skipSubagentSessions，默认 true），避免一个长任务里子代理每轮都播；需要时设 countSubagentErrors: true 让子代理错误也计入父会话。

4. 响度（"声音太小"的根因与解法）

真因：系统主音量只有 9.0%（未静音）。用户明确选择不调整系统音量（2026-08-26 铁律），因此只从音频文件侧解决。原始 poetic MP3 实测（ffmpeg volumedetect）：

文件	原始 mean_volume	原始 max_volume	增益版 mean	增益版 max	提升
voice-alert-complete-poetic.mp3	−20.8 dB	−7.0 dB	−8.7 dB	−0.6 dB	+12.1 dB
voice-alert-fail-poetic.mp3	−20.9 dB	−5.1 dB	−8.7 dB	−0.5 dB	+12.2 dB
voice-alert-approval-poetic.mp3	−19.9 dB	−5.3 dB	−8.8 dB	0.0 dB	+11.1 dB

处理链：volume=+26dB,alimiter=limit=0.98:level=disabled（限幅器把峰值压在 0.98≈−0.17 dBFS 之下，不削波）。
生成方式：本地 ffmpeg 一键增益（该脚本是本机开发脚本，含本机绝对路径，不随开源包发布），输出到 <home>\.dsh\data\dsh-voice-alert\audio\voice-alert-<kind>-poetic-loud.mp3。
原始 MP3 一律不改动，插件播放优先级：增益版 → 原始版 → 蜂鸣降级。
增益版与原始版都用插件自带的 lib/play_mp3_mci.py 播放（--file，winmm/MCI「原样播放」机制）。仅当你自己在 config.json 里配了 playerScript（可选的共享播放器）时，原始版才改走它的 --kind 入口。两者都不读写任何音频控制接口：系统音量多大就多大，系统静音就无声。
关闭增益版：config.json 里 "preferLoudAudio": false。

4.1 音色库（需求 A · v0.3.0）

设置页「语音播报」分区新增音色库小节，管理两类火山 TTS 音色：

类型	端点	Resource	Key	判定
克隆（`clone`）	`/api/v3/tts/unidirectional`	`seed-icl-2.0`	控制台 Key（`tts.apiKey`）	ID 以 `S_` 开头
预设（`preset`）	`/api/v3/plan/tts/unidirectional`	`seed-tts-2.0`	Agent Plan Key（`presetApiKey`，`ark-…`）	ID 以 `zh_`/`BV` 等开头

每行显示：类型徽标、音色 ID、可用性（✓可用 / 缺 key）、备注（可编辑）、「设为当前」、「试合」、「删除」。
试合：约 20 字短文本真实调用一次 TTS（不写入任何文件），成功显示 ✓ N B，失败显示火山返回的错误码/信息。
批量导入：粘贴多行 ID,备注（# 为注释）或 JSON 数组，自动识别类型、自动去重，幂等可反复导入。
删除：正在使用的克隆音色不可删；其余随时可删。改完点「保存音色库」把整个数组写回 config.json，手工添加的音色重启不丢。
生成侧按 kind 路由：合成前按音色类型选 endpoint/resource/key/speaker，混用必 401/403 的坑已被显式拒绝——预设音色被选但 presetApiKey 未配置时，返回明确错误 preset-key-missing，绝不静默用错 Key。
生成接口（POST /generate）支持 speakerId 参数，缺省用当前选中音色；音色切换会改变生成指纹，自动触发重合成。
预设音色 Key 入口：音色库小节底部「预设音色 Key」输入框（ark-…，留空不修改），随「保存音色库」写入 config.json 的 presetApiKey。

默认音色库为空（v0.4.0 开源决定）：插件不代你选音色。克隆音色到火山「声音复刻」做（拿到 S_ 开头的 ID），预设音色需要自己的 Agent Plan Key（ark-…）。两者都在设置页「音色库」里添加或批量导入，只存本机 config.json。

4.2 音效提醒（需求 B · v0.3.3）

不想折腾火山音色 / 不需要 API Key 时，把「提醒方式」切到 🎵 音效 即可：turn 结束就播一个内置音效。

内置 20 个音效（<data>\sfx\*.mp3，单声道 44.1 kHz / libmp3lame 128k，已做响度统一）：

分组	音效
提醒（10）	叮咚 / 电话铃 / 消息提示 / 闹钟 / 滴滴 / 清脆叮 / 钟声 / 成功号角 / 欢快音 / 木鱼
大自然（10）	鸟鸣 / 蝉鸣 / 蛙鸣 / 雨声 / 海浪 / 溪流 / 风声 / 篝火 / 雷鸣 / 森林

默认分配：完成 → 成功号角，失败 → 木鱼，审批 → 叮咚（sfxByKind，可逐个更换）。
选择方式（v0.3.4）：每个音效一行，行内三个勾选框（完成/失败/审批，同一事件只能勾一个）+ 音效名 + 「▶ 试听」；列表由 React 直接渲染（不再用 DOM 追加 option，那会被重渲染清空）。
试听：「▶ 试听」走 GET /sfx/play?name=<key>，不经过引擎，绝不会影响完成/失败的判定；v0.3.4 起试听会排队（等上一个播完），连点不再出现"没声音"。
完整性：GET /sfx/list 返回目录 + 每个文件是否在库（present），设置页显示「共 20 个内置音效，已在库 N 个」。
来源：提醒 10 个来自 Windows 系统音效（转 mp3）+ 1 个合成木鱼音；大自然 10 个来自 pacdv.com / mixkit.co 免费音效库。全部随插件本机存放，无外链。
安全：播放文件名只接受 [a-z0-9-] 的目录 key（sfxPathFor 再校验一次），/sfx/play?name=../../x 直接 400；音效同样走 scratch copy，不会被播放占用。

提醒方式三种取值

`alertMode`	行为	需要 API Key
`voice`（默认）	用你的克隆音色朗读三条文案（原行为）	需要
`sfx`	播内置音效，完全不调用 TTS	不需要
`off`	完成 / 失败 / 审批都不提醒	不需要

enabled（总开关）优先级最高：关掉后三种模式一律静音（引擎层拦截，UI 保存立即生效）。

5. 配置

<home>\.dsh\data\dsh-voice-alert\config.json（首次启动自动写入默认值；不存在则用内置默认值，默认开启）。优先级：内置默认值 < config.json < 插件 cordis.patch.yml 的 config 行 < 环境变量。

键	默认	说明
`enabled`	`true`	总开关（关掉 = 语音和音效都静音）
`alertMode`	`"voice"`	提醒方式：`voice` 语音 / `sfx` 音效 / `off` 关闭（v0.3.3）
`sfxByKind`	成功号角 / 木鱼 / 叮咚	音效模式下三类事件各播哪个音效（v0.3.3，key 必须是内置目录里的）
`sfxDir`	`<data>\sfx`	内置音效目录（v0.3.3）
`playOnTurnEnd`	`true`	每个 turn 结束播一次
`playFailOnError`	`true`	出错当下立即播失败（受节流约束）
`turnEndPlaysFailWhenErrored`	`true`	该 turn 已出错 → turn 结束只播失败
`errorMinIntervalMs`	`5000`	错误播报最短间隔（fail 自身节流）
`suppressCompleteAfterFailMs`	`3000`	fail 播出后 N ms 内的 complete 一律抑制（断连声）；`0` 关闭
`abortPlays`	`"none"`	用户中断的 turn：`none` / `complete` / `fail`
`skipSubagentSessions`	`true`	子代理会话不播
`countSubagentErrors`	`false`	子代理错误是否计入父会话
`preferLoudAudio`	`true`	优先播放增益版（音量不低的那一档）
`loudSuffix` / `audioDir` / `originalsDir`	`-loud` / `<data>\audio` / 原始目录	音频定位
`pythonPath` / `playerScript` / `bundledPlayer`	见文件	播放器路径
`fallbackBeep`	`true`	播不了时蜂鸣降级
`controlFile` / `controlResultFile` / `statusFile`	`<data>\control.txt` / `control-result.txt` / `status.json`	免凭据文件控制通道
`controlPollMs`	`2000`	控制文件轮询间隔
`logPath` / `logMaxBytes`	`<data>\voice-alert.log` / 1MB	插件日志
`voices`	`[]`（空库）	音色库（完整数组，可被 `/voices/save` 整体覆盖，手工添加重启不丢）
`selectedVoiceId`	`""`	当前选中音色（生成缺省用它；为空时需先在音色库点「设为当前」）
`presetApiKey`	`""`	预设音色用的 Agent Plan Key（`ark-…`）；未配置时预设音色合成拒绝返回 `preset-key-missing`

环境变量覆盖：DSH_VOICE_ALERT_PYTHON / DSH_VOICE_ALERT_PLAYER / DSH_VOICE_ALERT_LOG / DSH_VOICE_ALERT_DISABLED=1。

5.1 蓝牙耳机注意事项（实测 2026-09-16）

如果默认输出是蓝牙耳机，可能遇到「播报/试听后音乐显示在播却没声音」或「播报打断音乐」。这不是插件的问题：

实测证据：50ms 逐帧采样（会话音量 / 会话状态 / 端点状态 / 端点采样率格式）显示—— 播报期间音乐会话音量恒为 100%、未静音、会话 Active、端点 state=1 与 44100Hz/2ch 全程不变，播报自身每次 play_rc=0、position 平滑推进。也就是说 Windows 音频层没有任何"断开音乐"的动作。
真正的原因在蓝牙链路层：A2DP 链路在「新音频会话加入/离开」时会重协商，这段时间耳机端可能短暂不出声或吞掉正在播的流（Windows 完全看不到这一层）。调一下系统音量 / 重播一次通常能恢复。
判定方法：换 USB/有线耳机（或内置声卡）后一切正常 → 即可确认是蓝牙链路问题。
缓解手段（按省事排序）：
1. 默认输出改成有线 / USB 耳机（最彻底）；
2. 播放内核：v0.4.0 起默认就是 waveOut（实测对蓝牙更温和）；若你手工改成了 "mci"，改回 "wav" 即可；
3. 设备管理器 → 蓝牙适配器 → 电源管理 → 取消「允许计算机关闭此设备以节约电源」；
4. 更新蓝牙驱动 / 重新配对耳机；耳机若支持多点连接，别让手机同时连着抢占。
实战复盘（2026-09-16，两个坑都值得记，按用户实测修正过）：

坑一：默认音频设备没有「登记」 —— 换成蓝牙耳机后，仅在快捷面板里把它选成输出设备还不够； Windows 11 还需要在 设置 → 系统 → 声音 → 点该设备 → 属性 → 常规 → 「设为默认声音设备」→ 选"音频" 正式登记（等价于把 eConsole / eMultimedia / eCommunications 三个角色都指到它）。没登记时：音乐放一会儿就自己断（与插件无关），登记后立即恢复正常。
- 判据：探针显示音乐会话音量 100%、会话全程 Active、端点 state=1、端点格式恒定、音频峰值 > 0 —— 数据一直在送，只是输出链路被系统掐了。
- 排查顺序：同一副耳机连手机正常、连电脑断时，先查这条，别急着怀疑蓝牙硬件。
坑二：插件的「静音预热」会打断蓝牙音乐（v0.3.5 引入，v0.4.3 起默认关闭）。预热本是为修"第一声没声音"，但它会在播报前多打开一次音频端点，蓝牙链路因此重新协商，于是把正在播放的音乐打断。实测：同一个播放动作，去掉预热后音乐不再被打断。
- 现在默认 prewarmMs: 0（不预热）；万一你的设备确实需要唤醒链路，设成 350 即可恢复旧行为。

6. 播放链路（为什么这样启动）

DSH 宿主 (node) ──spawn──> powershell.exe（隐藏、无管道、unref）
                             └─ Start-Process ─> python.exe（播放器，父进程是 powershell）

python 不是 DSH 的直接子进程，powershell 约 1s 后自行退出，播放进程随即成为独立进程； DSH 会话/job 销毁只能杀掉那个已经退出的 launcher，杀不到正在播放的声音。
🔴 实测坑（勿改回）：spawn(..., { detached: true })（DETACHED_PROCESS）在本机让 powershell.exe 静默退出、什么都不执行（退出码 0）。用 marker 探针实测：detached→无副作用，非 detached→子进程正常生成。因此"独立"由 Start-Process 实现，而不是 node 的 detached 标志（见 lib/player.js 顶部注释与 test/self-check.mjs 的 LAUNCH_OPTIONS 断言）。
播放失败全线静默降级（缺文件 → 蜂鸣；异常 → 只写日志），绝不影响 DSH 运行。

7. 部署（desktop + web）

cd <你的插件源码目录>          # 例：你 clone 下来的 dsh-voice-alert/
# 把整个目录拷到 ~\.dsh\local-plugins\dsh-voice-alert，再在 profile 里声明 link: 依赖与 bundles

本机原有的两个开发脚本（dev-deploy-local.ps1 / dev-install-profiles.ps1）含本机绝对路径， 不随开源包发布，因此上面的命令需要你按自己的环境手动执行。

安装形态与本机既有插件一致：local-plugins 持久目录 + profile dependencies 的 link: 声明 + bundles 声明 + node_modules Junction。不使用 file:（tgz）依赖，避免触发 DSH 的 plugin-install-recovery 死循环。改完需要重启 DSH 才加载（重启需用户批准）。

8. 自检（可独立运行，不经 DSH）

node test\self-check.mjs              # 全量：逻辑 + 播放链路 marker 实证 + 真实出声
node test\self-check.mjs --no-sound   # 只跑逻辑与形状断言，不出声

⚠️ 完整模式会真的出声（会连续播几条语音/音效，用来验证音频链路）。它绕过提醒方式设置 直接调播放器，所以即使你把「提醒方式」设成语音，也会听到音效测试用例在响。 不想被吵就用 --no-sound（v0.4.2 起真实播放用例之间已加等待，不会几条叠在一起合唱）。

覆盖 278 项断言（完整模式含真实播放/播放器触发时 299 项）：事件回调是否真的驱动播放、每 turn 去重、错误优先、5s 节流、fail→complete 连声闸门（1s 内不播 / 4s 后照播 / 设 0 关闭）、子代理跳过、abort 策略、总开关、播放命令形状（必须 powershell Start-Process、不得 DETACHED_PROCESS）、增益版优先/原始版回退/无音频静默降级、免凭据控制通道（控制文件触发 + status.json 快照 + 非法内容拒绝）、 HTTP 路由层（注册路径 + 回环 200 / 非回环 403 / 未知 kind 400），以及真实播放链路 （marker 文件证明子进程真的被拉起——直接链路与控制文件链路各验一次，并用同步播放验证 exit code 0 与占用音频设备时长）。 v0.3.0 追加：音色库保存/导入/去重（saveVoicesConfig/parseVoiceImport/mergeVoiceImport）、试合探针（mock TTS）、 kind 路由（clone vs preset 的 endpoint/resource/key/speaker 选择，mock 断言）； v0.3.1 起额外断言不再注册任何 /reading/* 路由（朗读功能已移除）。

9. 诊断接口与免凭据控制通道

9.1 HTTP 路由（回环）

路由	作用
`GET /dsh-voice-alert/status`	解析后的配置、音频解析结果（增益版/原始版）、计数器
`GET /dsh-voice-alert/play?kind=complete\|fail\|approval`	手动真播一次，用于重启后验证
`GET /dsh-voice-alert/reload`	重新读取 `config.json`（不用重启 DSH）
`GET /dsh-voice-alert/voices`	音色库列表 + 选中 ID + 各音色可用性（clone 有 key / preset 有 key）
`POST /dsh-voice-alert/voices/save`	保存整个 voices 数组 + 选中 + `presetApiKey`（写入 config.json）
`POST /dsh-voice-alert/voices/import`	批量导入（多行 `ID,备注` 或 JSON 数组，自动识别类型、去重）
`POST /dsh-voice-alert/voices/probe`	试合：约 20 字真实 TTS 一次（不写文件），返回 `{ok, bytes, code, error}`
`GET /dsh-voice-alert/sfx/list`	内置音效目录（20 项 + 每项是否在库 `present`）+ 当前 `alertMode`/`sfxByKind`（v0.3.3）
`GET /dsh-voice-alert/sfx/play?name=<key>`	试听一个内置音效；`name` 必须是目录 key，否则 400（v0.3.3）

🔴 DSH Desktop 上的 403 是官方设计，不是插件 bug（2026-09-15 实证）：桌面壳把所有 HTTP 路由（含插件路由）包了一层浏览器访问闸门——

C:\Program Files\DSH Desktop Beta\resources\app\lib\webserver.js:42-53 DesktopWebServer.permits() → 不通过则 rejectBrowserRequest() → 403 + 头 cache-control: no-store、x-content-type-options: nosniff、体 forbidden；
...\resources\app\lib\desktop-browser-access-5-Ph3Uv7.js:47-51 decideDesktopBrowserAccess()：请求带 Electron 渲染器能力头 x-dsh-desktop-renderer:<每代随机 token> → 放行；否则若 ordinaryBrowserEnabled === false → denied（即 403）；ordinaryBrowserEnabled 只在 desktop-network-*.js:21-23 的「compatibility 模式且 (openBrowser 或 networkExposure=lan)」时为真。
反证：curl http://127.0.0.1:43120/、/api/ping、/dsh-todo-float-ball/health 同样全部 403 —— 与该插件无关。

因此普通本机请求无法（也不应）绕过这层闸门；要让它放行只能改 DSH Desktop 的浏览器访问设置（需重启，属用户决策）。插件自身也另有一道回环校验（非回环一律 403，与外壳闸门无关，已在自检中覆盖）。

9.2 免凭据控制通道（推荐用这个做验收）

动作	做法
真播一次	写入 `%USERPROFILE%\.dsh\data\dsh-voice-alert\control.txt`，内容 `kind=complete`（或 `fail` / `approval`）；插件在 `controlPollMs`（默认 2s）内播放并自动删除该文件
读取状态	读 `%USERPROFILE%\.dsh\data\dsh-voice-alert\status.json`（与 `/status` 同一份 JSON：配置、音频解析、规则、计数器、控制通道说明）
上次触发结果	读 `%USERPROFILE%\.dsh\data\dsh-voice-alert\control-result.txt`

# 触发一次真播放（无需任何凭据）
Set-Content "$env:USERPROFILE\.dsh\data\dsh-voice-alert\control.txt" "kind=complete" -Encoding ascii
Start-Sleep -Seconds 3
Get-Content "$env:USERPROFILE\.dsh\data\dsh-voice-alert\status.json"

在 DSH 窗口内（DevTools 控制台）也可以直接 await fetch('/dsh-voice-alert/status').then(r=>r.json()) —— 渲染器请求自带能力头，会通过外壳闸门。

10. 卸载

从两个 profile 的 package.json 删掉 dependencies 项与 bundles 项（可从 .bak-* 恢复）；
删除 <profile>\node_modules\dsh-voice-alert Junction（只是链接，不删数据）；
可选：删除 <home>\.dsh\local-plugins\dsh-voice-alert 与 <home>\.dsh\data\dsh-voice-alert。

License

MIT

dsh-voice-alert

v0.4.1 / v0.4.2：waveOut 设为默认播放内核；python 解释器自动探测（跳过 WindowsApps 存根）；自测真实播放用例之间加等待、不再叠响。

v0.4.0 开源准备（可直接分发给别人，零配置开箱即用）：

默认提醒方式 = 🎵 音效：装完即用，不需要任何 API Key、不需要任何音频文件（20 个音效随包提供）。
默认播放内核 = waveOut / WAV（playerEngine: "wav"）：实测在蓝牙耳机下 不吞第一声、不打断正在播的音乐；由 ffmpeg 首次播放时自动转 WAV 并缓存（60ms / 200300KB）。旧内核 "mci"（DirectShow）保留为可选。
默认音色库为空：插件不内置任何具体音色（克隆音色是各人自己的）；想用自己的声音按 §4.1 填自己的音色 ID + Key，再一键生成三条语音。
个人路径全部中性化：originalsDir 默认在插件自己的数据目录内、ffmpegPath 默认走 PATH 探测、playerScript/volumeProbeScript 默认留空（只用自带播放器）。使用者无需改代码。
新增 .gitignore（排除 __pycache__ / config.json / 音频产物）。发布前已核查：无密钥、无用户名、无内网信息。

v0.3.9 备选播放内核 waveOut / WAV（默认仍是 MCI，行为零变化，config.playerEngine = "wav" 一键切换）：

为什么：主内核 MCI type mpegvideo 走 DirectShow，会创建播放图并打开音频端点；在蓝牙耳机上可能触发链路重协商，打断其他正在播放的音乐（用户 2026-09-16 反复反馈"播报/音效后音乐显示在播但没声音"）。waveOut（winsound）是 Windows 最基础的播放路径：不启 DirectShow 图、不枚举设备、不改端点格式，对链路和其他播放器冲击最小。
实现：新增 lib/play_wav_out.py（waveOut 播放器，含 350ms 静音预热 + 毫秒级阶段日志）；host 侧新增 ensureWavCache() 用 ffmpeg 一次性把 mp3 转成 WAV 并缓存（实测单文件 64ms / 236KB，源文件更新会自动重转），playKind/playSfx 在 wav 引擎下优先走它，任何失败自动回退 MCI，绝不因为换内核而静音。
实测：wav 内核 611ms 出声、总耗时 5.8s（与 MCI 的 605ms / 6.1s 相当）。
自测新增 12 组断言（内核解析/缓存路径/命令形状/真实转换/真实 wav 播放），全绿。

v0.3.8 延迟优化（用户要求：对话结束到出声更快）+ 延迟可测量：

预热与打开文件并行：静音预热放进子线程，主线程同时做 MCI open（实测 open 只要 38ms，现在完全被预热窗口吞掉）——唤醒效果不变。
实测：播放器进程启动 → 开始出声 = 610ms（其中预热 350ms + 链路稳定等待 150ms 是"第一次就有声"的代价）；加上 powershell/python 启动（约 200400ms），**对话结束到听见声音约 0.81.0 秒**。触发本身仍是 1ms 内（play launched 与 turn-end 同毫秒）。
毫秒级阶段日志：日志变成 [时间.毫秒] sfx-player: +610ms play issued rc=0，以后任何延迟疑问都能直接对着日志算，不用再猜。自测新增两条断言锁住「进程启动→出声 <900ms」和「open 发生在预热窗口内」。

顺带明确语义：不勾时插件比对每条语音的「指纹」（文案 + 音色 ID + 语速 + 音调 + 音量）——全都没变就复用现有 mp3、完全不调用 TTS；哪条变了只重做那一条；文件缺失也会自动重做。

v0.3.5 修「刚生成语音后点试听没声音，调一下系统音量就有声音」（用户实测报告，根因探针实测非推测）：

实测证据：MCI open/play 返回码全 0、status position 正常推进（229→482→733→983 ms）、mode=playing、系统音量 35% 非静音——音频确实在"播放"；而同一时刻 Core Audio 探针（IMMDeviceEnumerator）读出默认输出设备 = 耳机 (EDIFIER Lolli Pro 5)，即蓝牙耳机（三个 role 一致）。蓝牙 A2DP 链路空闲后会挂起，这段时间 Windows 仍把音频"成功"送进驱动、耳机端不出声；调节系统音量会立刻激活链路——这正是"调一下音量之后就有声音"的来源。虚拟声卡端点未唤醒时同理。
修复：播放前先用 350 ms 静音预热默认端点（同步等待链路建立），再播真实音频；预热只播静音，不读写任何音量 / 静音接口（硬规则不变）。
顺带修一处旧缺陷：MCI play 的返回码此前被完全忽略，播放失败会被当成"播完了"（静默误报成功）。现在检查返回码，失败重试一次。
诊断留痕：播放全程写进插件日志（--log-file），含 prewarm ok / play_rc / positions —— 以后遇到无声可查 <data>\voice-alert.log 直接判断是"没播起来"还是"播了但端点没出声"。
若仍偶发无声：多半是蓝牙耳机 / 虚拟声卡的省电策略所致，可在「设备管理器 → 蓝牙适配器 → 电源管理」取消勾选"允许计算机关闭此设备以节约电源"，或改用有线耳机。

v0.3.4 依用户反馈再修（界面不再出现任何具体人名，插件可直接分发给别人用）：

音色名一律由使用者在「音色备注」里自己填（默认留空）；界面只叫「🎙 我的音色 · 语音合成」。
音效改成可勾选列表：20 个音效各占一行，行内三个勾选框（完成/失败/审批，同事件互斥）+ 音效名 + 「▶ 试听」。列表由 React 直接渲染，根治 v0.3.3「选了没反应」（下拉 option 被重渲染清空）。
一键生成 + 明确反馈：点「🎙 生成语音（一键更新）」会先自动保存文案再合成；运行中显示 x/y 进度，结束后明确显示「✅ 语音更新成功！已重新合成 N 条，复用 M 条」，失败显示「⚠️ 语音更新失败：… 合成出错」。
克隆入口写进界面：新增「克隆音色」行 + 两个链接——声音复刻控制台、产品介绍/开通。
修复「有时点试听没声音」：所有播放入口（引擎播报 / /preview / /sfx/play）串行化——等上一个播完再开下一个，避免两个 python+MCI 进程抢声卡导致后一个静默失败。

v0.3.3 同版修正：「🎙 我的音色 · 语音合成」卡常驻页面（不再藏进折叠区）——三条播报文案 + 试听 + 一键生成主按钮一目了然。

A DSH plugin that deterministically plays a fixed voice alert when a conversation turn finishes and a different one when something failed, plus a settings-section voice library.

功能总览 · At a glance（中英对照 / Bilingual）

播报事件 · Alert events

中文	English
每个 turn 结束自动播报「完成」语音	Plays a "done" voice when any conversation turn ends
turn 内出现错误（`agent/error` 或工具 `isError`）播报「失败」	Plays a "fail" voice when the turn had errors (`agent/error` or tool `isError`)
同 turn 只播一次（去重）、错误优先（不叠加完成）、错误播报节流（默认 5s）	Per-turn dedup, error-first (never stacks "done"), error throttling (5s default)
「失败」后 3s 内抑制「完成」防连声，可关闭	Suppresses "done" for 3s after a "fail" — no back-to-back sounds; disable with 0
用户中断（aborted）默认不播；子代理会话默认跳过，均可配置	User aborts silent by default; subagent sessions skipped — both configurable

三种提醒方式 · Three alert modes

中文	English
🗣 语音：用火山克隆音色朗读三条文案（完成/失败/审批）	🗣 Voice: cloned-voice TTS reads your three lines (done/fail/approval)
🎵 音效：内置 20 个音效（提醒 10 + 大自然 10），零配置、无需 API Key 开箱即用	🎵 SFX: 20 built-in sounds (10 alerts + 10 nature), zero config, no API key needed
🔕 关闭：完成/失败/审批都不提醒	🔕 Off: no alerts at all
每个音效可勾选「完成/失败/审批」任一事件并单独试听	Every SFX can be assigned to done/fail/approval (one event each) with per-row preview

音色库 · Voice library

中文	English
火山克隆音色 / 预设音色双路由（`seed-icl-2.0` / `seed-tts-2.0`），自动识别类型	Clone & preset TTS routing (`seed-icl-2.0` / `seed-tts-2.0`), type auto-detected
批量导入（多行 `ID,备注` 或 JSON）、自动去重、逐条试合验证	Batch import (`ID,note` lines or JSON) with dedup and trial-synthesis verification
生成指纹复用：文案/音色/语速/音调/音量没变就复用既有 mp3，零 TTS 消耗	Fingerprint reuse: unchanged text/voice/params reuse existing mp3s, zero TTS calls
默认音色库为空，音色名由使用者自填——不含任何具体人名	Empty default voice library, names filled in by the user — no personal data shipped

播放与兼容 · Playback & compatibility

中文	English
默认 waveOut/WAV 播放内核（不吞第一声、不打断蓝牙音乐），MCI 可选，失败自动回退	waveOut/WAV player by default (no lost first sound, doesn't cut Bluetooth music), MCI optional, auto-fallback
绝不改动系统音量或静音状态（winmm 原样播放）	Never touches system volume or mute state (winmm plays as-is)
播放进程经隐藏 PowerShell → Start-Process 独立拉起，DSH 会话销毁杀不到声音	Player spawned detached via hidden PowerShell → Start-Process, immune to session teardown
播放失败全线静默降级（缺文件→蜂鸣、异常→仅日志），绝不影响 DSH 运行	Silent fallback everywhere (missing file → beep, exceptions → log only), never affects DSH
蓝牙耳机专项适配：默认不预热（`prewarmMs: 0`）不再打断音乐，实测文档齐全	Bluetooth headset tuning: prewarm off by default (no music cuts), documented with measurements

界面与诊断 · UI & diagnostics

中文	English
DSH 原生设置页「语音播报」分区：总控卡 + 常用设置 + 高级折叠，中文优先字体	Native DSH settings section "语音播报": master card + common settings + collapsible advanced, CJK-first typography
毫秒级阶段日志（`<data>\voice-alert.log`），任何延迟/无声可对着日志定位	Millisecond stage logs (voice-alert.log) to pinpoint latency or silence
免凭据控制通道：写 `control.txt` 即触发真播，`status.json` 快照验收	Credential-free control: write `control.txt` to trigger a real play, read `status.json` to verify
278/299 项自测断言（含真实播放链路），HTTP 路由仅回环	278/299 self-check assertions incl. real playback; HTTP routes loopback-only

1. 它做什么

事件	语音	文件（默认优先播放增益版）
任意一个 turn 结束	完成	`voice-alert-complete-poetic-loud.mp3`
该 turn 内出现过错误（`agent/error` 或工具 `isError`）	失败	`voice-alert-fail-poetic-loud.mp3`
立即错误播报（工具失败/agent 报错当下，节流 5s）	失败	同上
手动验证（HTTP 路由）	完成/失败/审批	`voice-alert-approval-poetic-loud.mp3`

2. 事件依据（官方源码实证，非猜测）

用途	事件	出处（已装官方包）
判「一个 turn 结束」	`session/event` 且 `event.type === "turn/end"`	`@deepseek-ai/dsh-agent-loop/lib/index.js:994`（`finally` 里 append `turn/end`）
识别 turn 开始（用于归属错误）	`session/event` 且 `event.type === "turn/start"`	同上 `:926`
判「出现错误」	`agent/error`，payload `{agent, turn, step, error}`	同上 `:863`（`throwError`），且在 `turn/end` 之前发出（`:991` → `:994`）
判「工具失败」	`tools/result` 的 `result.isError`	`@deepseek-ai/dsh-tools/lib/types/index.js:3287`（以 `exec.agent` 为 scope 派发）

关键结论：

turn/end 每个 turn 只发一次（不是每个 step），所以含大量工具调用的长任务只会按 turn 播报；含工具的一轮会话不会因为 step 多而重复播报。
agent/status（running→idle）只在「整个 agent 彻底空闲」时变化，不是每 turn 信号，因此没有采用。
session/event 的历史回放不发事件（构造函数种子不 emit，见 dsh-session/lib/index.js 注释），所以 DSH 重启 / 恢复会话不会误报。

3. 去重与错误优先（实现要点）

同一 turn 只播一次：以 sessionId#turn 为键登记，重复的 turn/end 直接忽略（缓存上限由 dedupeCacheSize 控制）。
错误优先：turn/start 打开该会话的 turn 记录；该 turn 内出现 agent/error 或 tools/result.isError 即把该 turn 标记为 errored； turn/end 时若已 errored → 只播失败，不叠加播完成。
错误节流：立即失败播报受 errorMinIntervalMs（默认 5000ms）约束，同一时间窗内只播一次。
断「失败+完成」连声（2026-09-15 新增）：任意 fail 语音播出后 suppressCompleteAfterFailMs（默认 3000ms）之内， turn/end 的 complete 一律抑制并记日志（suppressedComplete 计数）。两个开关彼此独立：errorMinIntervalMs 管 fail 自身节流， suppressCompleteAfterFailMs 只管「fail 之后是否还允许立刻播 complete」；设 0 关闭本闸门。实测场景（宿主日志 2026-09-15 11:28:23）：agent/error 播 fail 后 0.26s，同 turn 的 turn/end 又播 complete → 本闸门消除。
turn/end 的 reason 映射：completed / max-tokens → 完成；error / blocked → 失败；aborted（用户中断）默认不播（abortPlays: none|complete|fail）。
子代理会话默认不播：按会话 header 的 origin === "subagent" / delegationDepth > 0 判定（skipSubagentSessions，默认 true），避免一个长任务里子代理每轮都播；需要时设 countSubagentErrors: true 让子代理错误也计入父会话。

4. 响度（"声音太小"的根因与解法）

文件	原始 mean_volume	原始 max_volume	增益版 mean	增益版 max	提升
voice-alert-complete-poetic.mp3	−20.8 dB	−7.0 dB	−8.7 dB	−0.6 dB	+12.1 dB
voice-alert-fail-poetic.mp3	−20.9 dB	−5.1 dB	−8.7 dB	−0.5 dB	+12.2 dB
voice-alert-approval-poetic.mp3	−19.9 dB	−5.3 dB	−8.8 dB	0.0 dB	+11.1 dB

处理链：volume=+26dB,alimiter=limit=0.98:level=disabled（限幅器把峰值压在 0.98≈−0.17 dBFS 之下，不削波）。
生成方式：本地 ffmpeg 一键增益（该脚本是本机开发脚本，含本机绝对路径，不随开源包发布），输出到 <home>\.dsh\data\dsh-voice-alert\audio\voice-alert-<kind>-poetic-loud.mp3。
原始 MP3 一律不改动，插件播放优先级：增益版 → 原始版 → 蜂鸣降级。
增益版与原始版都用插件自带的 lib/play_mp3_mci.py 播放（--file，winmm/MCI「原样播放」机制）。仅当你自己在 config.json 里配了 playerScript（可选的共享播放器）时，原始版才改走它的 --kind 入口。两者都不读写任何音频控制接口：系统音量多大就多大，系统静音就无声。
关闭增益版：config.json 里 "preferLoudAudio": false。

4.1 音色库（需求 A · v0.3.0）

设置页「语音播报」分区新增音色库小节，管理两类火山 TTS 音色：

类型	端点	Resource	Key	判定
克隆（`clone`）	`/api/v3/tts/unidirectional`	`seed-icl-2.0`	控制台 Key（`tts.apiKey`）	ID 以 `S_` 开头
预设（`preset`）	`/api/v3/plan/tts/unidirectional`	`seed-tts-2.0`	Agent Plan Key（`presetApiKey`，`ark-…`）	ID 以 `zh_`/`BV` 等开头

每行显示：类型徽标、音色 ID、可用性（✓可用 / 缺 key）、备注（可编辑）、「设为当前」、「试合」、「删除」。
试合：约 20 字短文本真实调用一次 TTS（不写入任何文件），成功显示 ✓ N B，失败显示火山返回的错误码/信息。
批量导入：粘贴多行 ID,备注（# 为注释）或 JSON 数组，自动识别类型、自动去重，幂等可反复导入。
删除：正在使用的克隆音色不可删；其余随时可删。改完点「保存音色库」把整个数组写回 config.json，手工添加的音色重启不丢。
生成侧按 kind 路由：合成前按音色类型选 endpoint/resource/key/speaker，混用必 401/403 的坑已被显式拒绝——预设音色被选但 presetApiKey 未配置时，返回明确错误 preset-key-missing，绝不静默用错 Key。
生成接口（POST /generate）支持 speakerId 参数，缺省用当前选中音色；音色切换会改变生成指纹，自动触发重合成。
预设音色 Key 入口：音色库小节底部「预设音色 Key」输入框（ark-…，留空不修改），随「保存音色库」写入 config.json 的 presetApiKey。

4.2 音效提醒（需求 B · v0.3.3）

不想折腾火山音色 / 不需要 API Key 时，把「提醒方式」切到 🎵 音效 即可：turn 结束就播一个内置音效。

内置 20 个音效（<data>\sfx\*.mp3，单声道 44.1 kHz / libmp3lame 128k，已做响度统一）：

分组	音效
提醒（10）	叮咚 / 电话铃 / 消息提示 / 闹钟 / 滴滴 / 清脆叮 / 钟声 / 成功号角 / 欢快音 / 木鱼
大自然（10）	鸟鸣 / 蝉鸣 / 蛙鸣 / 雨声 / 海浪 / 溪流 / 风声 / 篝火 / 雷鸣 / 森林

默认分配：完成 → 成功号角，失败 → 木鱼，审批 → 叮咚（sfxByKind，可逐个更换）。
选择方式（v0.3.4）：每个音效一行，行内三个勾选框（完成/失败/审批，同一事件只能勾一个）+ 音效名 + 「▶ 试听」；列表由 React 直接渲染（不再用 DOM 追加 option，那会被重渲染清空）。
试听：「▶ 试听」走 GET /sfx/play?name=<key>，不经过引擎，绝不会影响完成/失败的判定；v0.3.4 起试听会排队（等上一个播完），连点不再出现"没声音"。
完整性：GET /sfx/list 返回目录 + 每个文件是否在库（present），设置页显示「共 20 个内置音效，已在库 N 个」。
来源：提醒 10 个来自 Windows 系统音效（转 mp3）+ 1 个合成木鱼音；大自然 10 个来自 pacdv.com / mixkit.co 免费音效库。全部随插件本机存放，无外链。
安全：播放文件名只接受 [a-z0-9-] 的目录 key（sfxPathFor 再校验一次），/sfx/play?name=../../x 直接 400；音效同样走 scratch copy，不会被播放占用。

提醒方式三种取值

`alertMode`	行为	需要 API Key
`voice`（默认）	用你的克隆音色朗读三条文案（原行为）	需要
`sfx`	播内置音效，完全不调用 TTS	不需要
`off`	完成 / 失败 / 审批都不提醒	不需要

enabled（总开关）优先级最高：关掉后三种模式一律静音（引擎层拦截，UI 保存立即生效）。

5. 配置

键	默认	说明
`enabled`	`true`	总开关（关掉 = 语音和音效都静音）
`alertMode`	`"voice"`	提醒方式：`voice` 语音 / `sfx` 音效 / `off` 关闭（v0.3.3）
`sfxByKind`	成功号角 / 木鱼 / 叮咚	音效模式下三类事件各播哪个音效（v0.3.3，key 必须是内置目录里的）
`sfxDir`	`<data>\sfx`	内置音效目录（v0.3.3）
`playOnTurnEnd`	`true`	每个 turn 结束播一次
`playFailOnError`	`true`	出错当下立即播失败（受节流约束）
`turnEndPlaysFailWhenErrored`	`true`	该 turn 已出错 → turn 结束只播失败
`errorMinIntervalMs`	`5000`	错误播报最短间隔（fail 自身节流）
`suppressCompleteAfterFailMs`	`3000`	fail 播出后 N ms 内的 complete 一律抑制（断连声）；`0` 关闭
`abortPlays`	`"none"`	用户中断的 turn：`none` / `complete` / `fail`
`skipSubagentSessions`	`true`	子代理会话不播
`countSubagentErrors`	`false`	子代理错误是否计入父会话
`preferLoudAudio`	`true`	优先播放增益版（音量不低的那一档）
`loudSuffix` / `audioDir` / `originalsDir`	`-loud` / `<data>\audio` / 原始目录	音频定位
`pythonPath` / `playerScript` / `bundledPlayer`	见文件	播放器路径
`fallbackBeep`	`true`	播不了时蜂鸣降级
`controlFile` / `controlResultFile` / `statusFile`	`<data>\control.txt` / `control-result.txt` / `status.json`	免凭据文件控制通道
`controlPollMs`	`2000`	控制文件轮询间隔
`logPath` / `logMaxBytes`	`<data>\voice-alert.log` / 1MB	插件日志
`voices`	`[]`（空库）	音色库（完整数组，可被 `/voices/save` 整体覆盖，手工添加重启不丢）
`selectedVoiceId`	`""`	当前选中音色（生成缺省用它；为空时需先在音色库点「设为当前」）
`presetApiKey`	`""`	预设音色用的 Agent Plan Key（`ark-…`）；未配置时预设音色合成拒绝返回 `preset-key-missing`

环境变量覆盖：DSH_VOICE_ALERT_PYTHON / DSH_VOICE_ALERT_PLAYER / DSH_VOICE_ALERT_LOG / DSH_VOICE_ALERT_DISABLED=1。

5.1 蓝牙耳机注意事项（实测 2026-09-16）

如果默认输出是蓝牙耳机，可能遇到「播报/试听后音乐显示在播却没声音」或「播报打断音乐」。这不是插件的问题：

实测证据：50ms 逐帧采样（会话音量 / 会话状态 / 端点状态 / 端点采样率格式）显示—— 播报期间音乐会话音量恒为 100%、未静音、会话 Active、端点 state=1 与 44100Hz/2ch 全程不变，播报自身每次 play_rc=0、position 平滑推进。也就是说 Windows 音频层没有任何"断开音乐"的动作。
真正的原因在蓝牙链路层：A2DP 链路在「新音频会话加入/离开」时会重协商，这段时间耳机端可能短暂不出声或吞掉正在播的流（Windows 完全看不到这一层）。调一下系统音量 / 重播一次通常能恢复。
判定方法：换 USB/有线耳机（或内置声卡）后一切正常 → 即可确认是蓝牙链路问题。
缓解手段（按省事排序）：
1. 默认输出改成有线 / USB 耳机（最彻底）；
2. 播放内核：v0.4.0 起默认就是 waveOut（实测对蓝牙更温和）；若你手工改成了 "mci"，改回 "wav" 即可；
3. 设备管理器 → 蓝牙适配器 → 电源管理 → 取消「允许计算机关闭此设备以节约电源」；
4. 更新蓝牙驱动 / 重新配对耳机；耳机若支持多点连接，别让手机同时连着抢占。
实战复盘（2026-09-16，两个坑都值得记，按用户实测修正过）：

坑一：默认音频设备没有「登记」 —— 换成蓝牙耳机后，仅在快捷面板里把它选成输出设备还不够； Windows 11 还需要在 设置 → 系统 → 声音 → 点该设备 → 属性 → 常规 → 「设为默认声音设备」→ 选"音频" 正式登记（等价于把 eConsole / eMultimedia / eCommunications 三个角色都指到它）。没登记时：音乐放一会儿就自己断（与插件无关），登记后立即恢复正常。
- 判据：探针显示音乐会话音量 100%、会话全程 Active、端点 state=1、端点格式恒定、音频峰值 > 0 —— 数据一直在送，只是输出链路被系统掐了。
- 排查顺序：同一副耳机连手机正常、连电脑断时，先查这条，别急着怀疑蓝牙硬件。
坑二：插件的「静音预热」会打断蓝牙音乐（v0.3.5 引入，v0.4.3 起默认关闭）。预热本是为修"第一声没声音"，但它会在播报前多打开一次音频端点，蓝牙链路因此重新协商，于是把正在播放的音乐打断。实测：同一个播放动作，去掉预热后音乐不再被打断。
- 现在默认 prewarmMs: 0（不预热）；万一你的设备确实需要唤醒链路，设成 350 即可恢复旧行为。

6. 播放链路（为什么这样启动）

DSH 宿主 (node) ──spawn──> powershell.exe（隐藏、无管道、unref）
                             └─ Start-Process ─> python.exe（播放器，父进程是 powershell）

python 不是 DSH 的直接子进程，powershell 约 1s 后自行退出，播放进程随即成为独立进程； DSH 会话/job 销毁只能杀掉那个已经退出的 launcher，杀不到正在播放的声音。
🔴 实测坑（勿改回）：spawn(..., { detached: true })（DETACHED_PROCESS）在本机让 powershell.exe 静默退出、什么都不执行（退出码 0）。用 marker 探针实测：detached→无副作用，非 detached→子进程正常生成。因此"独立"由 Start-Process 实现，而不是 node 的 detached 标志（见 lib/player.js 顶部注释与 test/self-check.mjs 的 LAUNCH_OPTIONS 断言）。
播放失败全线静默降级（缺文件 → 蜂鸣；异常 → 只写日志），绝不影响 DSH 运行。

7. 部署（desktop + web）

cd <你的插件源码目录>          # 例：你 clone 下来的 dsh-voice-alert/
# 把整个目录拷到 ~\.dsh\local-plugins\dsh-voice-alert，再在 profile 里声明 link: 依赖与 bundles

本机原有的两个开发脚本（dev-deploy-local.ps1 / dev-install-profiles.ps1）含本机绝对路径， 不随开源包发布，因此上面的命令需要你按自己的环境手动执行。

8. 自检（可独立运行，不经 DSH）

node test\self-check.mjs              # 全量：逻辑 + 播放链路 marker 实证 + 真实出声
node test\self-check.mjs --no-sound   # 只跑逻辑与形状断言，不出声

⚠️ 完整模式会真的出声（会连续播几条语音/音效，用来验证音频链路）。它绕过提醒方式设置 直接调播放器，所以即使你把「提醒方式」设成语音，也会听到音效测试用例在响。 不想被吵就用 --no-sound（v0.4.2 起真实播放用例之间已加等待，不会几条叠在一起合唱）。

9. 诊断接口与免凭据控制通道

9.1 HTTP 路由（回环）

路由	作用
`GET /dsh-voice-alert/status`	解析后的配置、音频解析结果（增益版/原始版）、计数器
`GET /dsh-voice-alert/play?kind=complete\|fail\|approval`	手动真播一次，用于重启后验证
`GET /dsh-voice-alert/reload`	重新读取 `config.json`（不用重启 DSH）
`GET /dsh-voice-alert/voices`	音色库列表 + 选中 ID + 各音色可用性（clone 有 key / preset 有 key）
`POST /dsh-voice-alert/voices/save`	保存整个 voices 数组 + 选中 + `presetApiKey`（写入 config.json）
`POST /dsh-voice-alert/voices/import`	批量导入（多行 `ID,备注` 或 JSON 数组，自动识别类型、去重）
`POST /dsh-voice-alert/voices/probe`	试合：约 20 字真实 TTS 一次（不写文件），返回 `{ok, bytes, code, error}`
`GET /dsh-voice-alert/sfx/list`	内置音效目录（20 项 + 每项是否在库 `present`）+ 当前 `alertMode`/`sfxByKind`（v0.3.3）
`GET /dsh-voice-alert/sfx/play?name=<key>`	试听一个内置音效；`name` 必须是目录 key，否则 400（v0.3.3）

🔴 DSH Desktop 上的 403 是官方设计，不是插件 bug（2026-09-15 实证）：桌面壳把所有 HTTP 路由（含插件路由）包了一层浏览器访问闸门——

C:\Program Files\DSH Desktop Beta\resources\app\lib\webserver.js:42-53 DesktopWebServer.permits() → 不通过则 rejectBrowserRequest() → 403 + 头 cache-control: no-store、x-content-type-options: nosniff、体 forbidden；
...\resources\app\lib\desktop-browser-access-5-Ph3Uv7.js:47-51 decideDesktopBrowserAccess()：请求带 Electron 渲染器能力头 x-dsh-desktop-renderer:<每代随机 token> → 放行；否则若 ordinaryBrowserEnabled === false → denied（即 403）；ordinaryBrowserEnabled 只在 desktop-network-*.js:21-23 的「compatibility 模式且 (openBrowser 或 networkExposure=lan)」时为真。
反证：curl http://127.0.0.1:43120/、/api/ping、/dsh-todo-float-ball/health 同样全部 403 —— 与该插件无关。

9.2 免凭据控制通道（推荐用这个做验收）

动作	做法
真播一次	写入 `%USERPROFILE%\.dsh\data\dsh-voice-alert\control.txt`，内容 `kind=complete`（或 `fail` / `approval`）；插件在 `controlPollMs`（默认 2s）内播放并自动删除该文件
读取状态	读 `%USERPROFILE%\.dsh\data\dsh-voice-alert\status.json`（与 `/status` 同一份 JSON：配置、音频解析、规则、计数器、控制通道说明）
上次触发结果	读 `%USERPROFILE%\.dsh\data\dsh-voice-alert\control-result.txt`

# 触发一次真播放（无需任何凭据）
Set-Content "$env:USERPROFILE\.dsh\data\dsh-voice-alert\control.txt" "kind=complete" -Encoding ascii
Start-Sleep -Seconds 3
Get-Content "$env:USERPROFILE\.dsh\data\dsh-voice-alert\status.json"

在 DSH 窗口内（DevTools 控制台）也可以直接 await fetch('/dsh-voice-alert/status').then(r=>r.json()) —— 渲染器请求自带能力头，会通过外壳闸门。

10. 卸载

从两个 profile 的 package.json 删掉 dependencies 项与 bundles 项（可从 .bak-* 恢复）；
删除 <profile>\node_modules\dsh-voice-alert Junction（只是链接，不删数据）；
可选：删除 <home>\.dsh\local-plugins\dsh-voice-alert 与 <home>\.dsh\data\dsh-voice-alert。

License

MIT

loyalchiiina/dsh-voice-alert

dsh-voice-alert

功能总览 · At a glance（中英对照 / Bilingual）

播报事件 · Alert events

三种提醒方式 · Three alert modes

音色库 · Voice library

播放与兼容 · Playback & compatibility

界面与诊断 · UI & diagnostics

1. 它做什么

2. 事件依据（官方源码实证，非猜测）

3. 去重与错误优先（实现要点）

4. 响度（"声音太小"的根因与解法）

4.1 音色库（需求 A · v0.3.0）

4.2 音效提醒（需求 B · v0.3.3）

提醒方式三种取值

5. 配置

5.1 蓝牙耳机注意事项（实测 2026-09-16）

6. 播放链路（为什么这样启动）

7. 部署（desktop + web）

8. 自检（可独立运行，不经 DSH）

9. 诊断接口与免凭据控制通道

9.1 HTTP 路由（回环）

9.2 免凭据控制通道（推荐用这个做验收）

10. 卸载

License

Community comments

loyalchiiina/dsh-voice-alert

dsh-voice-alert

功能总览 · At a glance（中英对照 / Bilingual）

播报事件 · Alert events

三种提醒方式 · Three alert modes

音色库 · Voice library

播放与兼容 · Playback & compatibility

界面与诊断 · UI & diagnostics

1. 它做什么

2. 事件依据（官方源码实证，非猜测）

3. 去重与错误优先（实现要点）

4. 响度（"声音太小"的根因与解法）

4.1 音色库（需求 A · v0.3.0）

4.2 音效提醒（需求 B · v0.3.3）

提醒方式三种取值

5. 配置

5.1 蓝牙耳机注意事项（实测 2026-09-16）

6. 播放链路（为什么这样启动）

7. 部署（desktop + web）

8. 自检（可独立运行，不经 DSH）

9. 诊断接口与免凭据控制通道

9.1 HTTP 路由（回环）

9.2 免凭据控制通道（推荐用这个做验收）

10. 卸载

License

Community comments