界面音效 SOH4C4759/dsh-ui-sound

dsh-ui-sound

DeepSeek Harness Web GUI 的界面音效插件：把「界面交互」和「任务状态更新」都变成可听见的语义反馈，每一类反馈都能在设置页里单独挑音效、单独开关。

⚠️ 这是社区移植版，不是上游官方延续

本仓库是 dsh-plugin-uisfx（MIT，作者 XanthanL）在 DSH 0.2.0 上的移植适配版。
上游声明支持 dsh 0.1.0-rc.6；在 0.2.0 上它的宿主行无法激活、任务音静默失效。
请优先使用上游——只有当你确实运行在 0.2.0+ 且撞上那些问题时才需要本版。
改了什么、依据是什么，逐条记录在 PROVENANCE.md。

音效引擎来自开源项目 uisfx（MIT，Copyright © Yuki Capital），共 78 个 cue × 12 个音色包，全部由 Web Audio 实时合成，不含任何音频文件、不发起网络请求。
见 NOTICE 与 vendor/uisfx-0.4.0.js。

安装

dsh plugin --profile <你的 profile> add github:SOH4C4759/dsh-ui-sound
然后重启 dsh

lib/ 是构建产物且已随仓库提交，没有构建步骤，git 源安装开箱可用。装完在 设置 → 音效 里配置。

它解决什么

DSH 默认几乎没有声音反馈：任务跑完了？失败了？按钮点中了没有？只能靠眼睛确认。
本插件补上两类语义音效：

- 交互音效 —— 按钮按下时按语义分类发声（普通 / 主要 / 开关 / 发送 / 关闭 / 危险 / 链接），键盘 Enter、Space 激活同样发声。
- 任务状态音效 —— 当前会话开始运行、运行成功结束、运行失败结束，以及出现需要你处理的交互（授权请求 / 提问 / 计划复核）时发声。

触发时机

| 情景 id | 默认 cue | 什么时候响 |
| task.start | start | 当前会话的 agent 开始运行 |
| task.success | success | 当前会话正常结束一轮 |
| task.failure | error | 当前会话因错误结束一轮 |
| task.pending | notification | 任意会话出现待处理交互（授权 / 提问 / 计划复核） |
| click.normal | press | 普通按钮 |
| click.primary | select | 主要 / 强调按钮 |
| click.toggle | toggle-on | 开关、checkbox、aria-pressed |
| click.send | send | 发送 / 提交 |
| click.close | close | 关闭 / 取消 |
| click.danger | delete | 删除 / 清空 / 危险操作 |
| click.link | open | 链接 |

三条刻意的取舍：

1. 任务音只跟「你正在看的那个会话」。子代理和后台会话会不停地起停，全都发声等于噪声。
判据是会话列表里 retainedBy.mainView > 0 的那一行——和 DSH 自己判定「当前会话」的规则一致。
你切到设置页、文件页时，沿用最后一个主视图会话，不会突然静音。
2. 待处理提醒对所有会话生效。它的价值就在于你没在看那个会话时提醒你，所以不按主视图过滤，用 提醒音 开关单独控制。
3. 首帧只记基线。页面加载时已经在跑的会话不会补一声「开始」。

配置

设置 → 音效。可配置项：

| 设置 | 默认值 | 说明 |
| 启用音效 | 开 | 总开关 |
| 音量 | 55% | 0–100% |
| 音色包 | zen | 12 种整体音色，一键切换整套性格 |
| 任务音 | 开 | task.start / success / failure 三类 |
| 按钮音 | 开 | 所有 click. |
| 提醒音 | 开 | task.pending |
| 每情景 cue | 见上表 | 每个情景独立下拉选择 + 试听按钮 |

持久化落点（可直接手改，改完刷新页面生效）：

%USERPROFILE%\.dsh\ui-sound\config.json

{
"enabled": true,
"volume": 0.55,
"pack": "zen",
"taskSounds": true,
"clickSounds": true,
"attentionSounds": true,
"mapping": { "task.success": "complete", "click.send": "send" }
}

宿主半会校验并裁剪这个文件：音量夹到 0–1，未知音色包回落到 zen，未知 cue 回落到该情景的默认值——一个手滑写错的键不会让其它配置一起失效。设置页的改动也写回同一个文件，所以清浏览器数据不会丢配置。

12 个音色包

minimal（干练精确） / soft（圆润温暖） / glass（明亮清脆） / arcade（像素游戏） / mechanical（机械硬朗） / organic（木石水声） / dreamy（空灵慢速） / scifi（全息数字） / rubber（弹性俏皮） / cinematic（深沉大片） / studio（克制精准） / zen（纸、木、风铃，默认）

浏览器自动播放策略

浏览器不允许网页在没有用户手势前启动 AudioContext，因此页面加载后第一次点击之前不会有声音，这是浏览器行为、不是插件故障。插件在第一次 pointerdown 时预热并恢复 AudioContext，所以从第一次点击起就该有声；若仍无声，先点一下页面任意位置。

给其它插件用的 API

浏览器半通过 ctx.reflect.provide("uiSound", service) 暴露服务：
ctx.uiSound.play("task.success") // 按情景触发（受对应开关与总开关约束）
ctx.uiSound.playCue("achievement") // 直接播一个 cue
ctx.uiSound.preview("success") // 设置页那种无门控试听
ctx.uiSound.getPrefs() // 当前偏好

调试入口：window.__dshUISound()（player）、window.__dshUISoundDebug()（当前 prefs）。

架构

- 宿主半 lib/index.js：只注入 webServer，提供 /ui-sound/api/settings（GET/POST）与 /ui-sound/api/status，只接受回环地址 + 同源的请求；偏好走临时文件 + rename 原子写入。
- 浏览器半 lib/client.js：内联 uisfx 0.4.0 引擎 + DSH 集成层。
任务状态来自 ctx.sessions.list 的行级 running 与 ctx.uiSession.sessionStatus 的 pendingInteraction （uiSession 通过 ctx.inject 等待，见下）；交互音来自 document 捕获阶段的 pointerdown / 键盘合成 click。
- 不依赖 Host 设置命名空间、不依赖 webRuntime——前者外部 bundle 插件拿不稳，后者在 DSH 0.2.0 里不存在。

与 dsh-plugin-uisfx 的关系

本插件是 dsh-plugin-uisfx（MIT）在 DSH 0.2.0-rc.2 上的就地移植适配版，音效引擎与其 78 cue / 12 音色包完整保留，只重写了 DSH 集成层。原版在本版本上失效的三处（都不报错、只静默失效）：

| 原版读取 | 0.2.0 实情 | 后果 |
| 宿主 inject: ["webServer","webRuntime"] | 没有任何包提供 webRuntime | 宿主行无法激活 |
| ctx.sessions.list.getSnapshot().current | 快照是 { ids, byId, phase, projectionsBySession } | 任务状态监听静默失效 |
| snapshot.pending | SessionSnapshot 只有 pendingSubmissions，待处理交互在 uiSession.sessionStatus.pendingInteraction | 提醒音永远不会响 |

另有一处设计修正：attentionSounds 开关在上游被定义、在设置页可点，但没有任何代码读它；本版把 task.pending 接到该开关上。

修复于 v0.1.2 的一处移植缺陷：uiSession 由 dsh-client-ui-session 提供，而它在自己的 API 依赖就绪后才注册；本插件以 immediately: true 先启动，旧版的一次性 ctx.get("uiSession") 通常拿到 undefined，于是「待处理提醒」整页静默。现在改用 ctx.inject(["uiSession"], …)：服务出现后再订阅 sessionStatus，服务始终缺席时其余功能（点击音、设置页）照常加载。回归检查见 scripts/verify-client-wiring.mjs。

逐文件的来源、改动幅度与许可归属见 PROVENANCE.md。

校验（改代码前后都该跑）

仓库里的 lib/ 是提交进版本库的产物，所以 CI 不构建，只守会被手改悄悄破坏的不变量。
四条命令本地与 CI 完全一致，不需要 pnpm install（不依赖任何 npm 包）：

node scripts/verify-bundle.mjs # 发布形态契约：manifest、exports/files 目标、入口语法
node scripts/verify-package.mjs # 发布元数据、浏览器半契约、宿主半离线求值、文档里的条数
node scripts/verify-client-wiring.mjs # 浏览器半接线：晚注册的 uiSession 也必须接上提醒音
node scripts/verify-publish-guards.mjs # 本机绝对路径 / 账号名 / 凭据 / 内网地址

四者分工不重叠：

- verify-bundle.mjs 管「包装出来能不能被加载」——dsh.bundle.patch、每个 exports/files 目标是否真实存在、入口文件能否解析。它接受一个可选 root，所以既能查检出，也能查解包后的发布压缩包（release.yml 就是这么复核产物的）。
- verify-package.mjs 管「发布出去是否安全、是否还在用当前 dsh 的 API」——真实 LICENSE 文件、非 private、repository/author/meta；浏览器半只有一个 ModuleLoader 工厂、只 require("react")、不再读 0.2.0 已移除的 list.current 与 snapshot.pending。它会真的 import lib/index.js（宿主半只依赖 node: 内置模块），读回 SCENARIO_IDS / PACK_IDS / CUE_IDS / DEFAULT_PREFS，核对 README 写的 11 情景 / 12 音色包 / 78 cue 是否就是代码真实值，并验一遍 normalizePrefs 的裁剪行为。文档漂移会让 CI 红，不会等读者踩坑才发现。
- verify-client-wiring.mjs 管「服务晚到一步时还接不接得上」——在 node:vm 里用最小 Cordis 上下文加载真实 lib/client.js，先 apply、后注册 uiSession，断言订阅确实发生、待处理交互只响一次、拆卸后释放订阅；同时覆盖没有 ctx.inject 的旧宿主与始终不挂 uiSession 的宿主。它只验接线（是否决定播放），不验声音本身。
- verify-publish-guards.mjs 扫全树文本文件，命中作者本机路径、账号名、token 字面量或内网网段即失败。

.github/workflows/ci.yml 在 push / PR 上跑全部四条，另加一次 npm pack 并核对压缩包里含全部运行期文件； release.yml 在 v tag 上出发布包。发布流程见 RELEASING.md。

更新记录

v0.1.2

- 修复 issue #1：uiSession 晚于本插件注册时，「待处理提醒」整页不响。改用 ctx.inject(["uiSession"], …) 等待服务出现后订阅，并新增 scripts/verify-client-wiring.mjs 回归检查。

v0.1.1

- 发布契约：版本复用守卫、随包发布打包检查、安装包 tarball 资产。

已知边界（未做）

- 只做合成音效，不支持导入自定义音频文件（uisfx 引擎本身是参数化合成，没有采样播放通道）。
- 不做 hover 音（78 个 cue 里有 hover，但悬停发声在长时间使用中会变成噪声）。
- 不做工具调用级别的逐次音效（一轮里几十次工具调用，会淹没真正重要的状态变化）。

许可与归属

- 本仓库新增与重写的代码：MIT，Copyright © 2026 林冠宇 (SOH4C4759)，见 LICENSE。
- 内联的 uisfx 0.4.0 运行时：MIT，Copyright © Yuki Capital，全文见 NOTICE。
- 移植自 dsh-plugin-uisfx：MIT，Copyright © 2026 dsh-uisfx contributors，全文见 NOTICE。
- 逐文件的来源与改动幅度见 PROVENANCE.md。

若你是上述任一权利人或维护者，对归属写法或移植本身有异议，开一条 issue 即可，我们会立即调整或下架。