dsh-task-complete-sound

Task Complete Sound

任务在 Harness Web UI 中完成时播放选定的提示音预设。

目标 Profile

插件会安装到这里；不确定时保持 web。

npx -y @deepseek-ai/dsh plugin --profile web add github:Chatbot-zhou/dsh-task-complete-sound#1e639644e36640179369b5536fdce7e1e81b9b72

兼容性与来源证明

Task Complete Sound 以 dsh-task-complete-sound 发布，当前版本为 2.0.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。

DSH 兼容范围: *
运行环境: web
发布来源: github
Registry 更新时间: 2026/9/30

版本

2.0.0stable

2026/9/30

DeepSeek Harness Plugin Hub

← Plugins

dsh-task-complete-sound

Task Complete Sound

任务在 Harness Web UI 中完成时播放选定的提示音预设。

目标 Profile

插件会安装到这里；不确定时保持 web。

npx -y @deepseek-ai/dsh plugin --profile web add github:Chatbot-zhou/dsh-task-complete-sound#1e639644e36640179369b5536fdce7e1e81b9b72

README

任务完成提示音（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 应用）

桌面端没有终端时：

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

生效范围与卸载

安装进 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）。

三种常见调整配方

想更沉、更厚重

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

想更亮、更醒神

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

想更长、更有余韵

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

修改后如何生效

编辑 client.js 并保存后：

刷新当前页面（桌面窗口 Ctrl+R，浏览器 F5）。客户端 bundle 通常会被模块系统自动换新，刷新是确保拿到最新代码的可靠手段；
如果刷新后仍是旧音效，重启一次应用（profile 重新加载时会重新读取包）；
改的是 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

兼容性与来源证明

Task Complete Sound 以 dsh-task-complete-sound 发布，当前版本为 2.0.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。

DSH 兼容范围: *
运行环境: web
发布来源: github
Registry 更新时间: 2026/9/30

版本

2.0.0stable

2026/9/30

README

任务完成提示音（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 应用）

桌面端没有终端时：

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

生效范围与卸载

安装进 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

打包前自检

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

旧版本把选择存在 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）。

三种常见调整配方

想更沉、更厚重

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

想更亮、更醒神

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

想更长、更有余韵

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

修改后如何生效

编辑 client.js 并保存后：

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

插件配置（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`	总音量系数，叠乘在每个音色自身峰值之上

在 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 默认值，而不会保留用户在设置里的选择。要么把字段写全，要么只用设置界面。

设置行与镜像的关系

内部常量与插槽

常量	默认值	作用
`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 里就会随重建丢失，从而静默吞掉那次完成。

音频解锁

音量与削顶

显示名与图标

插件卡片上的名称与描述来自 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

Task Complete Sound

兼容性与来源证明

版本

相关插件

Task Complete Sound

README

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

目录

安装

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

方式二：直接从 GitHub 安装

方式三：tarball 或注册表

桌面端（DeepSeek Harness 应用）

生效范围与卸载

仓库与发布

发布到 npm（可选）

打包前自检

五种音色

修改音效

音调参数完整参考

三步新增一个音色

三种常见调整配方

修改后如何生效

插件配置（Config）

在 profile 里覆盖

设置行与镜像的关系

内部常量与插槽

关于 @deepseek-ai/schemastery 依赖

工作原理

判定规则

音频解锁

音量与削顶

显示名与图标

已知限制与延期工作

模型体验

KV 缓存影响

故障排查

目录结构

许可证

兼容性与来源证明

版本

相关插件

相关插件

相关插件

README

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

目录

安装

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

方式二：直接从 GitHub 安装

方式三：tarball 或注册表

桌面端（DeepSeek Harness 应用）

生效范围与卸载

仓库与发布

发布到 npm（可选）

打包前自检

五种音色

修改音效

音调参数完整参考

三步新增一个音色

三种常见调整配方

修改后如何生效

插件配置（Config）

在 profile 里覆盖

设置行与镜像的关系

内部常量与插槽

关于 @deepseek-ai/schemastery 依赖

工作原理

判定规则

音频解锁

音量与削顶

显示名与图标

已知限制与延期工作

模型体验

KV 缓存影响

故障排查

目录结构

许可证

关于 `@deepseek-ai/schemastery` 依赖

关于 `@deepseek-ai/schemastery` 依赖