dsh-sounds

English

DSH Web 插件：在 agent 回合完成或失败时、后台（子代理）会话结束时、以及 agent 请求输入或权限时播放音效。音效库使用 opencode 内置的完整音效包 —— 45 个音效，分为五组（alert-*、bip-bop-*、nope-*、staplebops-*、yup-*；MIT 协议，来自 anomalyco/opencode packages/ui/src/assets/audio）—— 嵌入客户端 bundle 中。

DSH 设置面板中的"声音"区域允许你为每个事件选择音效（分组菜单 + 逐行预览）、开关功能、调节音量，以及恢复 opencode 默认设置。

事件 → 音效映射（opencode 默认值）

事件	音效	opencode pack key
当前会话回合完成（turn/end，reason completed）	bip-bop-01	done
回合失败（reason error）或触发输出 token 上限（max-tokens）	nope-03	error
后台 / 子代理会话完成（无窗口 → 无 reason 详情）	yup-01	subagent_done
Agent 等待用户输入（pendingInteraction 为 question / plan-review）	bip-bop-03	question
Agent 请求权限（pendingInteraction 为 approval）	staplebops-06	permission

静音设计：aborted（用户点击停止）、blocked（输入被拒绝）、interrupted（崩溃恢复），以及页面加载时已关闭的回合或切换到会话时的历史记录（历史不播放音效）。

功能说明

• 检测完全在浏览器端运行：客户端监听 sessions service —— running 状态翻转和待处理交互，以及当前会话的对话窗口中精确的 turn/end reason。音效以 base64 data URI 形式嵌入 bundle（无需额外路由，离线可用）。

• 设置 UI：原生 DSH Settings 区域（settings.section 插槽，id dsh-sounds，导航标签"声音"），包含启用开关、音量滑块（默认 40%，与 opencode 一致）、每个事件的选择行（按音效组分组的菜单，当前音效标记）、逐事件开关、逐行试听按钮，以及"恢复 opencode 默认"重置（音效和开关状态）。

• 系统通知（Windows 通知中心）：同一事件管道也会触发浏览器 Notification，镜像 opencode 的注意力语义 —— 仅在页面未聚焦时显示 toast。设置面板有"通知"组：主开关、权限行（含"请求通知权限"按钮，浏览器要求用户手势触发），以及逐事件开关。点击 toast 会聚焦 DSH 页面。

• 逐事件开关（音效和通知）持久化在 localStorage（dsh-sounds.events、dsh-sounds.notifications）中，而非宿主设置命名空间，因此开关变更仅需刷新页面即可生效 —— 无需重启宿主。

• 自动播放策略：浏览器在首次用户手势前会阻止音频播放。插件会排队最新的音效，并在首次点击/按键时回放。

• 偏好设置存储在 dsh-sounds 设置命名空间（宿主端），通过插件自身的 fenced /sounds API 路由提供给浏览器（loopback-trust fence，与核心 /api 传输相同）。默认值：

  dsh-sounds:
    enabled: true
    volume: 0.4          # 0..1（opencode 默认音量）
    done: bip-bop-01
    error: nope-03
    subagentDone: yup-01
    question: bip-bop-03
    permission: staplebops-06
  

安装

# 在包含此 checkout 的目录中执行：
dsh plugin --profile web add ../path/to/dsh-sounds-<version>.tgz

然后重启 Web 应用（dsh web）以使 profile 加载新的 bundle。请从打包的 tarball 安装（而非 link: 路径），以确保包作为真实目录存在于 profile 的 node_modules 中，使其自身的 imports 能正确解析。

手动验证 / 临时控制

页面加载后，打开 DevTools 控制台：

window.__dshSounds.prefs()              // 当前偏好设置
window.__dshSounds.play("done")         // 播放指定事件类型的音效
window.__dshSounds.playName("yup-01")   // 播放指定名称的嵌入音效
window.__dshSounds.preview("nope-03")   // 试听（忽略启用开关）
window.__dshSounds.setPrefs({ volume: 0.8 })  // 持久化偏好补丁

开发

node scripts/build-client.mjs   # 将 assets/*.mp3 嵌入 lib/client.js
node scripts/test-client.mjs    # 检测引擎的 stub-loader 模拟

客户端 bundle 使用 shell 的模块加载器格式手写（window.__ModuleLoader__.load({ id, factory })），仅依赖平台种子模块（react、@deepseek-ai/dsh-client-ui-primitives）—— 源文件为 src/client.template.js；lib/client.js 为生成产物。要刷新音效库，替换 assets/ 下的 mp3 文件（文件名即 opencode 文件名）并重新构建。

本地 shell 补丁：设置导航图标

设置面板的导航图标在 DSH shell 中硬编码（@deepseek-ai/dsh-client-ui-settings-general：models/agent-presets/plugins 有特殊图标，其他 section id 回退到齿轮图标）。目前没有注册 section 图标的通道，因此通过一个小型本地补丁为"声音"区域添加扬声器图标：

node scripts/patch-nav-icon.mjs   # 幂等操作；dsh 升级后重新运行

补丁在已安装的客户端 bundle 中添加了一个 if (id === "dsh-sounds") 分支。dsh 升级重装包后会还原此补丁 —— 重新运行脚本即可（标记注释使其在已应用时为空操作）。

许可证

MIT。音频资源来自 opencode（MIT）。

---

English

DSH web plugin: plays sound effects when an agent turn completes or fails, when a background (subagent) session finishes, and when the agent asks for input or requests permissions. The sound library is opencode's full built-in pack — 45 sounds in five families (alert-*, bip-bop-*, nope-*, staplebops-*, yup-*; MIT, from anomalyco/opencode packages/ui/src/assets/audio) — embedded in the client bundle.

A "声音" section in the DSH Settings panel lets you pick a sound for each event (grouped menu + per-row preview), toggle the feature, adjust volume, and reset to the opencode defaults.

Event → sound mapping (opencode defaults)

Event	Sound	opencode pack key
Current session turn completed (turn/end reason completed)	bip-bop-01	done
Turn failed (reason error) or hit the output-token cap (max-tokens)	nope-03	error
Background / subagent session finished (no window → no reason detail)	yup-01	subagent_done
Agent is waiting for user input (pendingInteraction question / plan-review)	bip-bop-03	question
Agent requests permissions (pendingInteraction approval)	staplebops-06	permission

Silent by design: aborted (user pressed stop), blocked (input rejected), interrupted (crash repair), and any turn that was already closed when the page loaded or when you switched to its session (history never beeps).

What it does

• Detection runs entirely in the browser: the client half watches the sessions service — the list store for running flips and pending interactions, and the staged session's conversation window for exact turn/end reasons. Sounds are embedded in the bundle as base64 data URIs (no extra routes, works offline).

• Settings UI: a native DSH Settings section (settings.section slot, id dsh-sounds, nav label "声音") with an enable switch, a volume slider (default 40%, same as opencode), one picker row per event (sound menu grouped by pack family, current sound marked), a per-event on/off switch, a per-row 试听 preview button, and a "恢复 opencode 默认" reset (sounds AND switches).

• System notifications (Windows notification center): the same event pipeline also fires browser Notifications, mirroring opencode's attention semantics — toasts appear only while the page is not focused. The Settings panel has a "通知" group: a master switch, a permission row with a "请求通知权限" button (browsers require a user gesture), and one on/off switch per event. Clicking a toast focuses the DSH page.

• Per-event switches (sounds and notifications) are persisted in localStorage (dsh-sounds.events, dsh-sounds.notifications), not the host settings namespace, so switch changes take effect on a page refresh alone — no host restart required.

• Autoplay policy: browsers gate audio until the first user gesture. The plugin queues the newest sound and replays it on the first click/keypress.

• Preferences live in the dsh-sounds settings namespace (host half), served to the browser through the plugin's own fenced /sounds/api routes (loopback-trust fence, same as the core /api transport). Defaults:

  dsh-sounds:
    enabled: true
    volume: 0.4          # 0..1 (opencode's default volume)
    done: bip-bop-01
    error: nope-03
    subagentDone: yup-01
    question: bip-bop-03
    permission: staplebops-06
  

Install

# from the directory containing this checkout:
dsh plugin --profile web add ../path/to/dsh-sounds-<version>.tgz

Then restart the web app (dsh web) so the profile boots the new bundle. Install from the packed tarball (not a link: path) so the package lives as a real directory in the profile's node_modules and its own imports resolve.

Manual verification / ad-hoc control

After the page loads, open the DevTools console:

window.__dshSounds.prefs()              // current prefs
window.__dshSounds.play("done")         // play one event kind
window.__dshSounds.playName("yup-01")   // play one embedded sound
window.__dshSounds.preview("nope-03")   // preview (ignores the enable switch)
window.__dshSounds.setPrefs({ volume: 0.8 })  // persist a patch

Development

node scripts/build-client.mjs   # embed assets/*.mp3 into lib/client.js
node scripts/test-client.mjs    # stub-loader simulation of the detection engine

The client bundle is hand-written in the shell's module-loader format (window.__ModuleLoader__.load({ id, factory })) and consumes only the platform seed modules (react, @deepseek-ai/dsh-client-ui-primitives) — the source of truth is src/client.template.js; lib/client.js is generated. To refresh the sound library, replace the mp3 files under assets/ (names are the opencode filenames) and rebuild.

Local shell patch: settings nav icon

The Settings panel nav glyphs are hardcoded in the DSH shell (@deepseek-ai/dsh-client-ui-settings-general: models/agent-presets/plugins get special icons, every other section id falls back to the gear). There is no registration channel for a section icon, so a tiny local patch adds a speaker glyph for the "声音" section:

node scripts/patch-nav-icon.mjs   # idempotent; re-run after a dsh upgrade

The patch is a single if (id === "dsh-sounds") branch in the installed client bundle. A dsh upgrade that reinstalls the package reverts it — re-run the script (the marker comment makes it a no-op when already applied).

License

MIT. Audio assets are from opencode (MIT).

回到顶部