任务完成提示音 Chatbot-zhou/dsh-task-complete-sound

任务完成提示音（Task Completion Sound）

一个 DeepSeek Harness 组合包（bundle）插件：任务结束时播放一声提示音，让你在别的窗口忙别的事时也能注意到任务已经完成。

icon

- 五种合成音色，可在「设置 → 通用」里逐个试听并切换
- 配置走官方 Config：提示音开关、默认音色、是否包含子代理、最小间隔、总音量都是受校验的配置字段，写入 profile 的设置文档（不再是浏览器本地存储）
- 零构建、无安装脚本：唯一的运行时依赖是与宿主同版本的 @deepseek-ai/schemastery（配置 schema），不需要任何构建步骤或构建授权
- 不打包任何音频文件：所有音效都由 Web Audio 实时合成
- 自动过滤子代理：默认只有顶层任务真正结束才响，子代理先结束不会误报（可用配置改为包含）
- 无界面侵入：监视器不渲染任何 DOM；只有浏览器拦截音频时才出现一次性解锁提示

目录

- 安装
- 发布到社区前必须修改
- 五种音色
- 修改音效
- 插件配置
- 工作原理
- 显示名与图标
- 已知限制与延期工作
- 模型体验
- 故障排查
- 目录结构
- 许可证

安装

本包是一个标准组合包：package.json 声明 dsh.bundle.patch，指向 cordis.patch.yml，该 patch 按包名插入一行插件。

方式一：本地目录（开发/自用）

先在插件目录里装好它自己的依赖（link: 安装不会替它装）：

cd /绝对路径/dsh-task-complete-sound
pnpm install

再把它装进 profile：

dsh plugin --profile desktop add /绝对路径/dsh-task-complete-sound

dsh plugin 会在 profile 目录里转发给 pnpm，因此依赖与组合包列表会自动更新：

{
"dependencies": { "dsh-task-complete-sound": "link:/绝对路径/dsh-task-complete-sound" },
"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-task-complete-sound"] } }
}

方式二：直接从 GitHub 安装

本包没有构建脚本，也没有 prepare 脚本（交付的是可直接运行的纯 JS，不经过 TypeScript 构建），因此 git 安装不需要任何构建授权：

dsh plugin --profile desktop add github:Chatbot-zhou/dsh-task-complete-sound

官方文档提到 git 安装会因 prepare 脚本而要求用户配置 allowBuilds 授权。本包不存在这一步——这也是本包选择「源码即可运行」而不是「发布构建产物」的原因。

方式三：tarball 或注册表

pnpm pack # 产出 dsh-task-complete-sound-2.0.0.tgz
dsh plugin --profile desktop add ./dsh-task-complete-sound-2.0.0.tgz
dsh plugin --profile desktop add dsh-task-complete-sound # 已发布到 npm 时

桌面端（DeepSeek Harness 应用）

桌面端没有终端时：

1. 在对话里让 Harness 安装该包（内部使用插件管理器的 install_bundle，等价于上面的 add）；
2. 之后在 设置 → 插件 里可以看到该组合包的卡片、开关与卸载按钮。

生效范围与卸载

- 安装进 profile 后，该 profile 下所有会话都生效，并且跨重启保持。
- 卸载：dsh plugin --profile desktop remove <包名>，或在 设置 → 插件 里卸载。
- 只想临时静音：在 设置 → 插件 里关掉这条组合包即可，不必卸载。

本包没有 scripts（因此安装时不需要任何构建授权），唯一的运行时依赖是 @deepseek-ai/schemastery，声明在 dependencies 里由包管理器正常安装。

仓库与发布

- 仓库：<https://github.com/Chatbot-zhou/dsh-task-complete-sound>
- 包名：dsh-task-complete-sound（无作用域）

发布到 npm（可选）

pnpm publish # 无作用域包不需要 --access public

如果该名字在 npm 上已被占用，可改用你自己的作用域（例如 @chatbot-zhou/dsh-task-complete-sound），并同步修改 cordis.patch.yml 里插件行的 name: —— 包名与 patch 行必须始终一致，否则那一行解析不到模块。

打包前自检

pnpm pack # 应为 10 个文件

package.json cordis.patch.yml index.js client.js icon.svg
locale/en.json locale/zh.json README.md CHANGELOG.md LICENSE

node_modules/、pnpm-lock.yaml、.gitignore 都不会被打进去。

五种音色

| 按钮 | id | 音色性格 | 合成配方概要 |
| 清脆 | chime | 默认。明亮的两声上行 | 880 Hz → 1318.5 Hz |
| 木鱼 | wood | 干燥的木质敲击，不刺耳 | 260 Hz 腔体 + 520 Hz 主体 + 1040 Hz 只留 45 ms 当「敲击沿」 |
| 柔和 | soft | 温暖的低音和弦，最不打扰 | C4 261.63 + G4 392，C5 523.25 延迟 30 ms 且只给 0.10 音量，衰减 900 ms |
| 厚重 | deep | 低沉厚实，有「份量」 | G3 196 正弦 + 同音三角波增密 + D4 293.66 五度 + G4 392 八度，22–34 ms 慢起音 |
| 水滴 | drop | 短促下滑 | 1300 Hz → 900 Hz |

选择存放在 profile 的设置文档里（见插件配置），因此清浏览器数据也不会丢。如果存的值对应的音色已经被删除（例如旧版本的 bell/pluck），会自动回落到 chime，不会出现「没有选中项」的状态。

旧版本把选择存在 localStorage 的 dsh.task-complete-sound.preset。升级后该值仍会被读取作为回退，并会在配置仍是默认值时自动迁移一次，所以不会被打回默认音色。另外桌面窗口（dsh-app://）与浏览器页（http://127.0.0.1:19387）是两个不同的源，旧版路径下的 localStorage 互不相通。

修改音效

所有音效都定义在 client.js 顶部的 PRESETS 数组里，没有任何音频文件。改完保存即生效（见文末「修改后如何生效」）。

音调参数完整参考

每个音色是一个对象 { id, tones }，其中 tones 是若干「音调」的数组。每个音调是定长数组，按位置取值：

[频率, 起始偏移, 时长, 峰值, 波形, 终止频率, 起音]

| 位置 | 名称 | 单位 | 说明 |
| 1 | frequency | Hz | 起始频率。人耳可听范围约 20–20000；低音区 80–300 更「沉」，中音区 400–800 更「实」，1200 Hz 以上偏「尖」 |
| 2 | offsetMs | ms | 相对音色起点的延迟。0 = 与其它音同时开始；给它 100–300 就得到「两声」或琶音效果 |
| 3 | durationMs | ms | 该音从起音到完全衰减为 0 的总时长。越长越有余韵 |
| 4 | peak | 0–1 | 峰值音量。同一音色里各音调的峰值之和建议 ≤ 0.9，否则会在输出端削顶（听起来发糊） |
| 5 | type | — | 波形：'sine'（最纯净）、'triangle'（圆润，多奇次谐波）、'square'（洪亮但偏硬）、'sawtooth'（最亮最硬） |
| 6 | endFrequency | Hz | 可选，0 = 不滑音。给一个 > 0 的值，音高会从起始频率指数滑到该值（下滑如 [440, 0, 260, 0.45, 'triangle', 392]） |
| 7 | attackMs | ms | 可选，起音时间，省略时默认 5 ms。调大它 = 把「咔哒」换成「份量」，是做出「厚重」感最有效的一个参数；内部会自动限制在该音时长的 1/2 以内，所以填超大值也不会出错 |

还有一组音色级常量：

| 名称 | 位置 | 说明 |
| id | 每个 PRESETS 条目 | 音色标识。决定 localStorage 里存的值，也决定文案键名 preset.<id> |
| DEFAULT_PRESET | client.js 顶部 | 默认音色（当前 'chime'），也是存储值失效时的回落目标 |
| RAMP_SECONDS | client.js 顶部 | 默认起音时长，0.005 秒；被音调第 7 位的 attackMs 覆盖 |

三步新增一个音色

第 1 步：在 PRESETS 里加一个条目（放在你希望它出现的顺序位置；设置行按钮的排列顺序 = 数组顺序）。

{
id: 'ping',
tones: [
[1046.5, 0, 150, 0.4, 'sine', 0, 8],
[1568, 90, 260, 0.3, 'sine', 0, 8],
],
},

第 2 步：在 zh 与 en 两个字典里各加一条同名键。两个字典的键必须完全一致，否则切换语言时该按钮会显示原始键名。

'preset.ping': '叮咚', // zh 字典 'preset.ping': 'Ping', // en 字典

第 3 步：刷新页面。设置行会多出一个「叮咚」按钮，点一下即可试听。

提醒：id 一旦发布过就不要再改，因为用户 localStorage 里存的是它——改 id 等于让老用户的选择失效（会静默回落到 chime）。

三种常见调整配方

想更沉、更厚重

1. 把主频降到 150–260 Hz；
2. 叠加一个同频率的 'triangle' 波形（增加谐波密度，比单纯加大音量更「厚」）；
3. 补一个五度（×1.5）或八度（×2）在上面，音量给主频的 1/3–1/2，保留清晰度；
4. 把第 7 位 attackMs 调到 20–35，去掉「啪」的那一下；
5. 峰值总和控制在 0.9 以内。

想更亮、更醒神

1. 主频提到 900–1400 Hz；
2. 换成 'triangle' 或 'square'；
3. 起音保持默认 5 ms 甚至更短 —— 亮感就来自快起音；
4. 想做成「叮-咚」两声，用第 2 位 offsetMs 让第二个音延后 120–200 ms 并适当降调。

想更长、更有余韵

1. 加大第 3 位 durationMs（800–1200 ms 就很绵长）；
2. 同时把峰值调低一点（例如 0.3），否则长音听起来会吵；
3. 高音层给更短的时长、低音层给更长的时长，就得到「高音先消失、低音在回荡」的自然衰减。

修改后如何生效

编辑 client.js 并保存后：

1. 刷新当前页面（桌面窗口 Ctrl+R，浏览器 F5）。客户端 bundle 通常会被模块系统自动换新，刷新是确保拿到最新代码的可靠手段；
2. 如果刷新后仍是旧音效，重启一次应用（profile 重新加载时会重新读取包）；
3. 改的是 package.json（例如包名、exports、icon）时，必须重启应用才能重新解析包清单。

改坏了怎么排查：打开开发者工具（F12）看 Console，插槽渲染失败会明确打印 slot entry crashed in 'settings.general.item' 并附上错误原文——本插件的设置行一旦渲染抛错就会被静默清空，控制台是唯一的线索。

插件配置（Config）

Host 半边按官方要求导出 Schemastery Config：所有部署可调的参数都在这里，默认值直接写在 schema 上。

| 字段 | 类型 | 默认值 | 作用 |
| enabled | boolean | true | 完成提示音总开关 |
| preset | 'chime' \| 'wood' \| 'soft' \| 'deep' \| 'drop' | 'chime' | 默认音色，也是存储值失效时的回落目标 |
| includeSubagents | boolean | false | 子代理会话结束时是否也提示 |
| minGapMs | number（0–10000，步长 1） | 500 | 两次完成提示之间的最小间隔 |
| volume | number（0–1，步长 0.05） | 1 | 总音量系数，叠乘在每个音色自身峰值之上 |

全部字段都标了 .volatile()（运行时可改的偏好）：Host 侧用 config.<字段>.get() 读取，浏览器半边通过设置镜像 ctx.configForms 读同一份值，并把你选的音色写回去。因此选择写在 profile 的设置文档里，不再依赖浏览器存储。

在 profile 里覆盖

直接改 profile 的 cordis.patch.yml：

- id: task-complete-sound
name: 'dsh-task-complete-sound'
config:
preset: deep
volume: 0.6
includeSubagents: false

改完保存即可 —— 配置变更会触发热替换，不需要重启。

⚠️ patch 会整体替换该行的 config，不是逐键深合并。因此一旦你手写了 config，它就是那一行的完整配置：没写的字段回到 schema 默认值，而不会保留用户在设置里的选择。要么把字段写全，要么只用设置界面。

设置行与镜像的关系

设置行只在 Host 正在服务这个命名空间时注册（ctx.configForms.whileServed([NS], …)）。这是官方约定：没有组合出设置文档的部署看不到这一行，也就不会出现一个按不动的开关；同时提示音仍按 schema 默认值正常工作。

内部常量与插槽

| 常量 | 默认值 | 作用 |
| NS / LOCALE_NS | 'task-complete-sound' | 行 id、设置命名空间、语言命名空间三者同名 |
| PRESET_STORAGE_KEY | 'dsh.task-complete-sound.preset' | 旧版浏览器存储键，现在只作为回退读取并镜像写入 |
| RAMP_SECONDS | 0.005 | 默认起音时长；被音调第 7 位 attackMs 覆盖 |

四条插槽注册（改 order 可调整位置）：

| 插槽 | id | order | 作用 |
| shell.overlay | task-complete-sound | 100 | 全窗口监视器，不渲染 DOM |
| shell.overlay | task-complete-sound-unlock | 101 | 音频解锁提示（仅在浏览器拦截音频时出现） |
| conversation.composer.dock | task-complete-sound | 5 | 会话级监视器，不渲染 DOM |
| settings.general.item | task-complete-sound | 21 | 设置行的音色选择按钮组（仅命名空间被服务时注册） |

关于 @deepseek-ai/schemastery 依赖

- 官方要求 Config 必须实现 Standard Schema 接口，不能导出普通对象，因此必须引入 Schemastery。
- 它是构建产物里的副本，对 profile 安装的插件不可见（宿主只从 app.asar 内部解析自己的包），所以本插件把它声明为 dependencies 并精确锁定 3.18.4 —— 与当前安装附带的版本一致，避免两份实现漂移。
- 开发时（把插件目录 link: 进 profile）需要先在插件目录里装一次：

pnpm install

从 npm 安装的正式包则由 pnpm 自动装好，使用者无需任何额外操作。

工作原理

package.json dsh.bundle.patch → cordis.patch.yml（按包名插入一行插件） dsh.client → 浏览器半边；exports 暴露 client/locale/package.json index.js Host 半边：导出 Schemastery Config（全部偏好字段）， apply 为空——它只为占一条 Loader 行，让客户端模块系统把浏览器半边送出去，并持有受校验的配置 client.js 浏览器半边：监视器 ×2 + 解锁提示 + 设置行 + 合成器 locale/en.json 插件展示名与描述（英文） locale/zh.json 同上（中文） icon.svg 插件卡片图标（自包含 SVG，渲染为图片而非内联 HTML）

判定规则

任务"完成"＝顶层会话的运行标记从 true 变为 false，这对应 Host 的 agent/status → idle：整轮任务（含所有工具调用与排队输入）真正结束。
- 全窗口监视器：从 shell.overlay 拿 useSessions，把所有非子代理会话压成一个 "<会话id>:<0|1>" 字符串做比较——字符串能被默认的选择器相等性判断命中，因此不会因为每次生成新数组/对象而反复重渲染。
- 会话级监视器：从 conversation.composer.dock 拿当前会话的 useSession，独立判断同一件事。
- 两条通路共用同一个 500 ms 节流，所以同时命中只会响一声，而任意一条可用就足够——这是刻意的冗余。
- 转换判定：只有当某个会话 id 在前后两次快照里都存在、且由 true 变 false 时才算完成。因此「新出现的会话」「被归档/删除的会话」「页面刚加载的第一次快照」都不会响。
- 子代理被跳过：session.origin === 'subagent' 的会话不参与判定，避免子代理结束、主任务还在跑时误报。
- 基线放在模块作用域：客户端条目可能被销毁重建（模块热替换、profile 重载），基线若放在组件内的 useRef 里就会随重建丢失，从而静默吞掉那次完成。

音频解锁

Chromium 规定页面在首次用户交互前不允许出声。所以插件会在激活时探测一次音频上下文状态，并在此后每次鼠标按下/按键时重试；如果探测到仍被拦截，就在左下角显示一次性提示「提示音需要一次点击才能播放 · 点此试听」。Electron 桌面窗口通常不需要手势，因此很少看到它。

音量与削顶

每个音调独立走 振荡器 → 增益包络 → 输出，包络是「5 ms（或指定起音）线性升到峰值 → 线性降到 0」。同一音色里各音调的峰值之和是本插件刻意控制在 0.9 以下的上限——因为叠加的多个振荡器初相位一致，峰值会直接相加，超过 1.0 就会被输出端削平。

显示名与图标

插件卡片上的名称与描述来自 locale/en.json 与 locale/zh.json 的 meta 字段：

{
"meta": {
"title": "任务完成提示音", "description": "任务结束时播放提示音，五种合成音色可选，可在设置中逐个试听。"
}
}

- en.json 是发现入口，必须存在；
- 字段缺失时逐级回落：标题 → package.json 的 name → 完整插件名；描述 → package.json 的 description → 无描述；
- package.json 里需要导出这两个资源，并把图标放进 files：

{
"icon": "./icon.svg",
"exports": {
"./package.json": "./package.json",
"./locale/.json": "./locale/.json"
},
"files": ["locale/*.json", "icon.svg"]
}

- icon 路径相对于声明它的清单文件；支持 SVG/PNG/JPEG/WebP，上限 256 KiB；绝对路径、URL、目录外路径、指向目录外的符号链接都会被拒绝；SVG 以图片方式渲染（不是内联 HTML），所以不能依赖外部 CSS 或脚本。

已知限制与延期工作

- 增删 Config 字段需要重启一次。.volatile() 字段运行时可改、改完热替换即生效；但改动 schema 本身（新增/删除字段）需要重启应用，让 Host 重新加载模块 —— 浏览器半边会自行换新。
- 必须有一个打开的页面。提示音由页面发声，因此应用完全退出、或页面关闭时不会有任何系统级通知。
- 首次交互前可能被浏览器拦截。这是 Chromium 的自动播放策略，不是本插件的缺陷；此时会显示一次性解锁提示。
- 音效是实时合成的，不是采样。因此音色偏「电子」，做不出真实乐器或录音的质感；好处是零资产、零体积、任意调参。
- 没有「仅本会话静音」。静音粒度是：整包开关（设置 → 插件）、enabled 配置字段，其余是 5 个音色本身。没有按会话、按时段或按任务类型的静音。

模型体验

无。本包是纯浏览器侧的界面与提示插件，不注册任何面向模型的内容，也不参与提示词组装。

KV 缓存影响

无；本包既不组装也不发送提供方请求。

故障排查

| 现象 | 原因与处理 |
| 设置 → 通用里没有「任务完成提示音」这一行 | ① 先确认组合包已启用（设置 → 插件）；② 客户端 bundle 没换新，刷新页面后重启应用；③ 该行渲染时抛错会被静默清空——按 F12 看 Console 里的 slot entry crashed in 'settings.general.item' |
| 任务结束了但没响 | ① 确认页面处于打开状态；② 按 F12 看 Console 有无音频相关告警；③ 确认系统音量与 Windows 音量合成器里本应用的音量；④ 该会话是否被判定为子代理（子代理不响） |
| 第一次不响，之后正常 | 浏览器自动播放限制，点一下左下角的解锁提示即可；Electron 桌面窗口一般不会遇到 |
| 声音偏轻 / 听不清 | 加大 PRESETS 里的第 4 位峰值（注意总和 ≤ 0.9），或改用 'triangle'/'square' 波形 |
| 声音发糊、像破音 | 同一音色的峰值之和超过了 1.0，调低各音峰值 |
| 选了某个音色后重启又变回「清脆」 | 该 id 对应的音色已被删除（例如旧版本的 bell/pluck），插件回落到 Config.preset 的默认值——这是预期行为 |
| patch 里写了 config 之后，设置界面里的选择被重置了 | patch 的 config 是整体替换而非逐键合并，没写的字段会回到 schema 默认值；把字段写全，或只用设置界面 |

目录结构

dsh-task-complete-sound/
├── package.json 组合包清单：dsh.bundle.patch / dsh.client / exports / files / icon / dependencies ├── cordis.patch.yml 配置层：按包名插入一行插件 ├── index.js Host 半边：导出 Schemastery Config，空 apply ├── client.js 浏览器半边：预设、合成器、监视器、设置行、解锁提示 ├── locale/ │ ├── en.json 展示元数据（发现入口） │ └── zh.json 展示元数据（中文） ├── icon.svg 插件卡片图标 ├── README.md 本文档 ├── CHANGELOG.md 版本历史 ├── LICENSE MIT ├── .gitignore 忽略 node_modules └── node_modules/ 本地开发用（pnpm install 产出，不发布）

node_modules/ 只在「把插件目录 link 进 profile」这种开发方式下需要 pnpm install；从 npm 安装的正式包由 pnpm 自动处理。

许可证

MIT