dsh-audio-cue

DSH（DeepSeek Harness）宿主插件：审批询问与一轮对话结束时播放声音提示。 纯宿主半、零外部依赖；不注册工具、不注册服务、不碰任何现有文件。

# 从 GitHub 安装（0.2.x / 0.1.7 线需要 --config.store-dir，见下方说明）
dsh plugin --profile web add github:anne43983959/dsh-audio-cue

装完重启对应实例生效 —— 宿主模块与客户端 bundle 都在启动时装载。

---

它监听什么

#	事件	派发方式	作用
①	approval/request	waterfall	审批询问音 —— 订阅者必须放行 next()，否则会否决整条审批链
②	session/event → event.type === "turn/end"	emit	回合结束主路径（拿得到 session，可挡掉子代理收工那一声）
③	agent/turn-stopping	serial	回合结束兜底：延迟 2 s，且只在主路径没送来 turn/end 时才出声
④	tools/execute → ask_user_question	waterfall	提问音 —— 同样必须放行 next()

为什么回合结束要挂两条：② 能按 session.header.origin === "subagent" 过滤子代理，但走 scope carrier；③ 首参是字符串所以没有 scope 过滤、必然可达，却拿不到 agent 身份。于是 ② 当主路径、③ 当兜底 —— 兜底先看"这段时间主路径有没有送来 turn/end"，送到了就不出声。

---

这份代码里有两次实测事故，改之前请先读

事故一：watcher 弄死了审批链（v0.1.0）

approval/request 是 cordis 的 waterfall 事件：

// dsh-user-approval/lib/index.js:176
ctx.waterfall(scopeTarget(req.agent, req.agent), "approval/request", req, () => Promise.resolve("unavailable"))

而 waterfall 的语义是「listener 最外层先跑；不调用 next() 即否决整条链，含内置行为」（cordis/lib/index.js:311-325）。初版的 listener 签名只有 (payload)，next 被丢掉、返回 undefined，于是：

观察者不调 next() ⇒ 返回 undefined
   ⇒ OUTCOMES 归一化成 "unavailable"
   ⇒ dsh-sandbox 抛 "sandbox escalation requires approval, but no approval channel is available"

后果：提权被拒、审批面板永不出现、整条 GUI 审批通道形同虚设 —— 而插件日志里一行错都没有。 实测：本插件在册时两次提权 outcome=unavailable；摘除后同样的调用立刻 allowed-once ×2。

同一个文件里 turn/end 与 approval/asked 也挂错了 —— 它们是 session.append 的日志记录类型，不是总线事件，ctx.on("turn/end") 永远收不到。

事故二：从来就没响过（v0.1.0 → v0.1.2）

初版 play() 用 detached: true + powershell 5.1 在宿主进程里 spawn 播放。它确实被调用过（否则不会截断审批瀑布），但从未出过声，而且失败被 try/catch 吞干净。

v0.1.1 试图修事件源，却只写了失败路径的日志 —— 结果下一轮排查把"没有失败日志"误读成"play() 从未被调用"，白白多绕一轮。

v0.1.2 同时改两处后出声：去掉 detached、播放器换成 pwsh 7 绝对路径（失败自动回退 powershell 5.1），并把成功路径也写进日志。 ⚠️ 两处是同时改的，没做单变量对照；任何一处改回去都要重测。

完整时间线见 CHANGELOG.md。

---

配置

配置写在 profile 的 bundle patch 层（本插件自带的 cordis.patch.yml，或 profile 的 cordis.patch.yml 覆盖）：

键	默认	说明
enabled	true	总开关
approval	true	审批询问响
ask	true	提问（ask_user_question）响，与审批同一声
turnEnd	true	一轮结束响
ignoreSubagents	true	子代理会话的回合结束不响
fallbackTurnStopping	true	回合结束兜底路径开关
fallbackDelayMs	2000	兜底延迟（毫秒）
selfTest	false	自检音：装载后自动播一声，仅用于排查"宿主进程能不能出声"
selfTestMs	2500	自检音延迟（毫秒）

怎么读日志

实例日志里所有行都以 [dsh-audio-cue] 开头：

日志行	含义
v0.1.3 已加载… + `players=[…]	assets: approval=true turnEnd=true`
play >> session/event:turn/end	回合结束声已触发（正常每轮一行）
play >> approval/request	审批声已触发
spawn failed (…): <原因>	播放器起不来（ENOENT / EPERM …）
player exit=<非0> / fallback -> …	第一个播放器失败，已自动换另一个
subagent turn/end skipped	子代理会话被挡掉（正常）
turn-stopping fallback skipped（…）	主路径活着，兜底按设计让位（正常）
event agent/turn-stopping → 兜底出声	主路径不可达，兜底补了一声

安装（三种方式）

# ① GitHub（推荐）
dsh plugin --profile web add github:anne43983959/dsh-audio-cue

# ② 本地源码（开发用）
dsh plugin --profile web add link:<本仓库绝对路径>

# ③ 0.1.7 线 / 0.2.x 若报 ERR_PNPM_UNEXPECTED_STORE
#    带上该 profile 的 pnpm store 目录（值取 node_modules\.modules.yaml 的 storeDir）
dsh plugin --profile web add github:anne43983959/dsh-audio-cue --config.store-dir="<storeDir>"

注意 --profile 必须写在 plugin 之后。 卸载 / 回滚：dsh plugin --profile web remove dsh-audio-cue。

自检

node scripts/smoke.mjs

离线跑，不出声：断言四条事件源都在位，且每一处 waterfall 订阅都放行了 next()。改完代码务必跑一次。

素材

用途	文件	大小	音色
审批	assets/approval.wav	418,322 B	clean UI confirmation chime（2.37 s）
回合结束	assets/turn-end.wav	302,250 B	glassy bright crisp short ascending

两段均为 44.1 kHz / 16-bit / 立体声 WAV，取自 BudgetPixel 免费音效库（原始 URL 见 git 历史）。换素材只需替换 assets/ 下的同名文件，重启实例生效。

兼容

• dsh.compatibility.runtime: >=0.1.1-rc.1 <0.3.0
• 用到的四个事件名在 DSH 0.1.5 / 0.1.7 / 0.2.0 三代内核里都存在（agent/turn-stopping 在 0.2.0-rc.2 上核实过；换版本请先 grep 一次再信任）。
• 纯宿主半，没有客户端 bundle —— 不受客户端模块 id / 座位契约变化影响。

License

MIT