DearMrChai/dsh-plugin-task-notify

dsh-plugin-task-notify

DeepSeek Harness 的长任务音频提醒——子代理完成时响一声短促的"嘟"，整轮任务跑完、该回来操作时响一声清晰的"叮"。纯浏览器端实现；兼容任意 AI 提供商。

DSH（DeepSeek Harness）长任务完成提醒：你发出消息不响；子任务（子代理）完成响一声"嘟"；整轮任务跑完、该回来操作了，响一声"叮"（附带可选标题闪动 / TTS 播报）。纯浏览器端做提醒，和你用哪家 AI 模型无关。

Features / 特性

- Beep on sub-task / 嘟（子任务完成）：监听子代理工具调用（subagent、subagent_fork 等）的结束；每次完成播放一声短促的"嘟"，对快速连续完成设有自动合并窗口。
- Ding on turn end / 叮（整轮完成）：整轮开始时启动计时器；若整轮运行超过可配置阈值（默认 5 分钟），则在代理回到空闲时播放一声上扬的双音"叮"——提示你该回来了。短轮次保持静默。
- Multi-session / 多会话全局：默认监控所有会话；可配置为仅监控当前会话。
- Self-contained audio / 声音自包含：使用 Web Audio API 合成，无外部资源；可选通过 speechSynthesis 进行 TTS 播报（默认关闭），模板可自定义——用 {time} 作为实际时长的占位符。
- Two-half structure / 两个半结构：Host 半部分注册设置命名空间；Client 半部分运行浏览器端提醒。

Install / 安装

From the plugin market / 从插件市场安装

dsh plugin add dsh-plugin-task-notify

重启 dsh web，设置卡片会出现在 Settings → Plugins 下。

Manual install / 手动安装

1. 构建（或使用预构建的 lib/ 产物）：
pnpm install && pnpm build

lib/ 目录随包预构建；仅在修改 src/ 后才需要重新构建。
2. 将整个包复制到 DSH profile 中：
/profiles/web/node_modules/dsh-plugin-task-notify/

3. 在 profile 的 cordis.patch.yml 中添加条目（inject: [settings] 这一行是必需的）：
- insert:
- id: task-notify
name: dsh-plugin-task-notify
inject: [settings]
config:
enabled: true
thresholdMinutes: 5

4. 重启 DSH。设置卡片会出现在 Settings → Plugins 下。

⚠️ inject: [settings] 这一行至关重要。 没有它，cordis 加载器永远不会等待 settings 服务，于是 Host 半部分的 apply() 会执行，但命名空间永远不会注册——设置卡片就会悄无声息地不出现。参见下方的 Troubleshooting。

Configuration / 配置项

| Field | Meaning | Default |
| --- | --- | --- |
| enabled | 总开关 | true |
| thresholdMinutes | 整轮结束"叮"的阈值（分钟） | 5 |
| subReminderEnabled | 子任务"嘟"开关 | true |
| mergeMs | 连续子任务合并窗口（毫秒） | 500 |
| masterVolume | "叮"音量，0..1 | 0.6 |
| subVolume | "嘟"音量，0..1 | 0.5 |
| ttsEnabled | TTS 播报（默认关闭） | false |
| ttsTemplate | TTS 模板，{time} = 实际时长 | 任务完成，用时约 {time} 分钟 |
| titleFlash | 回合结束时标题栏闪烁 | true |
| globalSessions | 监控所有会话 | true |
| batchSingleBeep | 所有子任务每回合只响一声 | false |

声音触发规则 / Sound trigger rules

- 你发送消息：静音。
- 子任务完成：一个子代理系列的工具调用从 runningCalls 中消失 → 短促蜂鸣。合并窗口会对快速连续完成去重；batchSingleBeep 使整个回合只响一声。
- 回合结束：会话从运行中转为空闲，且计时器 ≥ 阈值 → 上升双音“叮” + 可选标题闪烁 + 可选 TTS（使用你的自定义模板，其中 {time} 替换为实际时长）。

浏览器注意 / Browser notes

- 音频播放前需要一次用户手势（点击/按键）——先点击页面或发送一条消息。
- TTS 在后台标签页中可能被限流；Web Audio 的蜂鸣/叮声不受影响。
- 页面关闭时停止；DSH 宿主继续运行，但声音需要浏览器保持打开。

兼容性 / Compatibility

- 面向 DSH 0.1.0-rc.8 客户端契约（与 dsh-plugin-agent-workflow 同一基线）。
- 仅使用公开的会话快照（sessions.list、running、runningCalls）和标准设置槽位。
- 设置卡片陈旧值修复（0.2.1，2026-09）：卡片现在接收实时绑定的设置作用域并订阅它，因此保存的值会立即渲染（槽位渲染器会永久缓存一次性的 inject() 快照）。
- DSH 0.1.2-rc.1 快照形状修复（2026-09）：客户端通知器此前将 snap.runningCalls / snap.turnTimings 作为扁平字段读取，但在 0.1.2-rc.1 上，SessionSnapshot 只暴露 running（运行调用树 / 回合计时已移入聊天视图 views.get('chat')?.legacy）。读取扁平字段会在 walk 内部抛出 TypeError: items is not iterable → 每个 SessionTracker.adopt() 都失败 → trackers= 0，整个通知器静默，且每次同步时错误都会重复。修复：新增 runningCallsOf() / turnTimingsOf() 适配器，优先读取 views.get('chat')?.legacy?.runningCalls，回退到扁平字段，缺失时降级为空；walk 现在用 Array.isArray 做保护。在 0.1.2-rc.1 上，回合结束的“叮”可用（它只需要 running）；子代理的“嘟”在那里是静默空操作，因为不借助聊天视图服务就无法通过 sessions 访问运行调用树。

排坑 / Troubleshooting

保存后卡片立即显示陈旧值（控件看起来像“没生效”，尽管设置文件实际上已更新）：
DSH 插槽渲染器会按注册缓存每个插槽条目的 inject() 结果（dsh-client-ui-renderer 的 cachedRootInject，一个以条目为键的 WeakMap）。因此，设置卡片会永远收到 inject 闭包在首次渲染时返回的内容。0.2.0 的卡片被注入了一个一次性的 value 快照，所以在保存后（保存通过实时的 scope.set 写入），卡片会回退到冻结的快照，并显示保存前的状态。修复（0.2.1）：inject 闭包将实时绑定的设置作用域交给卡片，而不是快照；卡片订阅它（scope.subscribe + scope.getSnapshot().value），并在每次写入完成后重新读取，因此保存后无需重新加载即可更新卡片。

设置卡片不显示，即使插件在插件列表中显示为已挂载且处于活动状态：

cordis 加载器只从补丁行读取 inject，而不是从插件模块的 export const inject 读取。如果补丁行省略了 inject: [settings]，宿主半部分的 apply() 会运行，但任何异步延迟（如 installSettingsSection）都不会触发——设置命名空间永远不会被注册，卡片也永远不会出现。修复：将 inject: [settings] 添加到补丁行，并在 apply() 中使用同步的 ctx.settings.register()。

许可证

MIT © DearMrChai