hawkongz/dsh-task-reminder

dsh-task-reminder
DeepSeek Harness Web UI 的对话任务完成提醒

License: MIT
Platform
Stars

语言： English | 简体中文

📋 目录

- 功能特性
- 快速开始
- 安装
- 使用方法
- 故障排查
- 主题
- 贡献
- 许可证

当你在另一个窗口浏览新闻时，DeepSeek Harness 中的智能体回合仍在持续运行——而任务完成的唯一信号只是会话列表变为空闲状态。本插件将这一时刻转化为真正的提醒，且无需离开你已经在使用的浏览器界面。

当对话任务停止时，插件会发送一条 Windows 系统通知（Web Notification——即操作系统右下角显示的原生通知，在浏览器处于后台时依然可见；点击它即可返回该会话），并播放合成的提示音。插件覆盖三种停止原因：任务完成、智能体正在等待你的回答（ask_user_question 待处理），以及错误停止（任何失败的回合——例如网关 HTTP 错误 400 / 401 / 429 / 500 / 502、服务提供商中断或连接失败）——一次停止只上报一次，且错误优先。通知时机有两种模式：始终（每次完成都通知，无论浏览器窗口是否在前台）或仅在未聚焦时（当你切换标签页或浏览器窗口失去焦点时）。没有应用内卡片：操作系统通知是唯一的视觉通道。所有配置都在其专属设置页面上完成，并在重启后保持。

整个插件都运行在浏览器端。宿主部分（index.js）是一个空的 apply() {}，且没有运行时依赖——宿主将其作为客户端插件下发到页面。

✨ 功能特性

* 以 Windows 系统通知作为唯一视觉通道： Web Notification API，即应用处于后台时你也能看到的操作系统通知。点击它会将窗口置于前台并打开该会话。插件覆盖三种停止原因：任务完成、等待你的回答（智能体阻塞在 ask_user_question / 计划审核中——通过读取只读的 uiSession.sessionStatus 快照来检测，绝不通过加入问题瀑布流来检测），以及错误停止（api-session/error——任何失败的回合：例如网关 HTTP 错误 400 / 401 / 429 / 500 / 502、服务提供商中断或传输失败）。一次停止只上报一次，错误优先：当停止事件到达时，插件会对其进行分类
从会话的持久日志中（turn/end 原因）——已完成的回合（或达到输出上限的回合）报告完成，失败的回合报告错误并附带网关自身的消息，且绝不显示完成提示，已取消的回合不报告任何内容。分类读取还会获取最后一个 turn/start：当最新的回合仍处于打开状态时（那个 turn/end 属于上一个回合），插件会重试直到它落地——按下 Stop 绝不会被误报为完成。提示音和提示会一起在同一轮中发出。如果分类不可用，完成提示会立即发出，而 5 秒内到达的同一次停止错误会撤回它——错误优先，每次停止一条提醒。当分类正在进行时重复出现的边沿（过期的列表重放）会被进行中守卫和完成→完成去重所拦截。两种计时模式——始终（每次停止）或仅在未聚焦时（标签页切换走或窗口未聚焦）——在设置页面上选择其一。浏览器在首次加载时请求一次通知权限——Notification API 没有免权限路径，这就是为什么仅页面内的插件从不显示此类提示。如果权限之后被重置，System 提示行下方的请求通知权限按钮会重新询问。被拒绝或不支持 Notification API 会降级为设置页面上的清晰提示，而不是静默失败。
* 四种合成提示音： 双音（经典）、上升三音、上升琶音和柔和三角波——使用 Web Audio 实时生成，因此不附带任何音频文件。选择一种音效会立即以当前音量播放；没有单独的预览按钮。无论提示计时模式如何，每次停止时都会响起提示音。
* 专用设置页面： Settings → Task reminder（Settings → General 中不再有相关行），并支持一键恢复默认值。
* 带去重的三通道完成检测： 主机转发的 api-session/status 事件、官方会话列表自身的 running 位，以及 uiSession.sessionStatus 快照中的 running 位（与侧边栏运行指示灯相同的来源——当分叉会话的列表投影过期时，这是可靠路径）共享一张边沿表，因此一次完成绝不会触发两次；当分类正在进行时重复出现的边沿还会被进行中守卫和完成→完成去重额外拦截。
* 所有值都持久化在浏览器本地存储中，并在重启后保留，因此主机端不需要设置命名空间。

🚀 快速开始

你需要： 运行着 web 配置文件的 DeepSeek Harness
（dsh web），PATH 中有 pnpm（dsh plugin 命令会转发给它），
以及一个可以强制刷新的浏览器。

第 1 步 — 打开终端

* macOS / Linux：打开 Terminal。
* Windows：Win + R，输入 powershell，按 Enter。

第 2 步 — 用一条命令安装并注册
dsh plugin 将包安装到 profile 目录，并在一步中将 bundle 追加到 profile 的 dsh.profile.bundles —— 无需手动注册：

Windows (PowerShell) — 从任意目录运行
dsh plugin --profile web add @hawkongz/dsh-task-reminder

macOS / Linux
dsh plugin --profile web add @hawkongz/dsh-task-reminder

这会从 npm registry 安装已发布的包 —— 与其他所有 DSH 插件的安装方式相同。（非作用域名称 dsh-task-reminder 永久不可用：npm 认为它与现有包 dsh-taskreminder 过于相似而拒绝，因此作用域名称是唯一的 registry 形式。）

若要从 GitHub 仓库安装 —— 默认分支或固定的 release 标签 —— 请使用 github: 规范：

默认分支
dsh plugin --profile web add github:hawkongz/dsh-task-reminder

固定 release 而非默认分支：追加标签
dsh plugin --profile web add github:hawkongz/dsh-task-reminder#

第 3 步 —— 重启并验证

重启宿主（dsh web），然后硬刷新浏览器（Ctrl + F5）。浏览器不会热读取已更改的 client.js，因此每次更新后这两个步骤都是必需的。验证注册：

dsh --profile web --dump-config | Select-String task-reminder

完成。 打开 Settings → Task reminder：如果页面出现，说明插件已生效。首次加载时，浏览器会显示一次性的通知权限提示 —— 选择 Allow，系统 toast 即设置完成。在任意会话中运行一个任务并等待提醒 —— 在默认的 Always 模式下，即使你正在观看对话，toast 也会触发。

📦 安装

前置条件

* DeepSeek Harness（dsh web），带有 web profile。
* PATH 中有 pnpm —— dsh plugin 会在 profile 目录内将其参数转发给 pnpm。
* Node.js 20 或更新版本（用于自检）。
* 支持 Web Audio 以及（可选）Notification API 的浏览器。

使用 dsh plugin 安装

dsh plugin --profile web add @hawkongz/dsh-task-reminder

这会将包安装到 profile 中，并将 @hawkongz/dsh-task-reminder 追加到 profile 的 dsh.profile.bundles（该行本身携带 id task-reminder）；随后加载器会应用 bundle 的 cordis.patch.yml 并插入 task-reminder 行。若要从 GitHub 安装，请改用 github:hawkongz/dsh-task-reminder[#]。该包不附带构建脚本，因此 pnpm 永远不会阻止安装（不同于需要在 profile 的 pnpm-workspace.yaml 中添加 allowBuilds 条目的 git 托管包）。

该包包含插件所需的一切：index.js（宿主部分）、client.js（浏览器部分）、cordis.patch.yml（bundle 行），以及 test/ 下的自检。

卸载

dsh plugin --profile web remove @hawkongz/dsh-task-reminder

remove 会在一步中移除该包并协调 bundle 列表。
然后重启 dsh web，使该行从组合配置中移除。

本地开发安装

要在检出副本上进行迭代，而不是使用已发布的包，请将其链接到配置文件中（这正是 plugin_manager 工具的 install_bundle 操作在内部所创建的内容）：

Windows (PowerShell) — 在包含检出副本的目录中执行
dsh plugin --profile web add link:.\dsh-task-reminder

或使用绝对路径，可在任意位置执行
dsh plugin --profile web add link:C:\Users\20105\OneDrive\Desktop\ds\dsh-task-reminder

记住重启规则：编辑 client.js，运行 node test/verify-client.mjs，重启 dsh web，强制刷新浏览器——宿主不会热读取已更改的 client.js。

📖 用法

设置页面

设置 → 任务提醒（设置导航顺序 44）：

| 设置项 | 默认值 | 持久化键 |
| :--- | :--- | :--- |
| 系统通知 | 开启 | dsh.task-reminder.notify |
| 通知时机（始终 / 仅在未聚焦时） | 始终 | dsh.task-reminder.notify-mode |
| 完成音效 | 开启 | dsh.task-reminder.sound |
| 提示音效果（四个选项） | 双音（经典） | dsh.task-reminder.sound-choice |
| 提示音音量（0–100） | 80 | dsh.task-reminder.volume |

恢复默认值按钮会写回：通知开启（始终）、音效开启、第一个效果、音量 80。

浏览器控制台辅助工具

在浏览器 DevTools 控制台中：

// 窗口聚焦状态、五项设置、通知时机、通知权限、
// 每个会话的运行记录、通道计数器、重复抑制、
// 最近的停止记录以及每种类型的最后一次停止
__dshTaskReminder.state()

// 立即发送任务完成通知并播放提示音（不等待任务）
__dshTaskReminder.test()

// 仅以当前音量播放所选效果
__dshTaskReminder.sound()

自检

node test/verify-client.mjs

在桩服务下运行浏览器部分（无需浏览器），并断言模块标识、接线、边缘检测、带重复边缘抑制的三个去重通道、两种通知时机模式、三种停止原因（完成、待处理问题、错误）及其轮次/结束分类（包括防止取消被误报的未闭合轮次重试）以及针对一次停止的延迟错误撤回、无论窗口状态如何每次停止都播放提示音、五项设置的默认值 / 读取 / 写入 / 恢复、每种效果和音量的振荡器参数、所有通知权限路径以及页面内的权限请求按钮、用户手势下挂起的 AudioContext 恢复，以及销毁。

🔧 故障排除

* 设置页面缺失。 该插件在 dsh.client.inject 中声明了
@deepseek-ai/dsh-client-ui-settings；请确保安装已完成，然后重启 dsh web 并强制刷新。如果页面
仍未出现，请重新运行
dsh plugin --profile web add @hawkongz/dsh-task-reminder。
* 代码更改没有生效。 宿主进程只在启动时读取客户端插件，而浏览器会缓存旧的 bundle。重启 dsh web，然后强制刷新（Ctrl + F5）。
* 没有出现系统 toast。 沿着链路排查，从成本最低的检查开始：
1. __dshTaskReminder.state() —— notificationSupported 必须为 true，notificationPermission 必须为 granted，并且每次完成后 stats.notifications 必须递增（1 表示浏览器接受了 toast；那么丢失就发生在操作系统一侧，而不是插件中）。
2. 权限仍为 default？设置页面在 System toast 行下显示一个 Request notification permission 按钮——点击一次并选择 Allow。权限为 denied？在浏览器地址栏的站点设置中允许该站点发送通知，然后再次点击该按钮。权限是按源（origin）划分的——为此应用授予一次权限即可覆盖其上的所有插件。
3. 浏览器接受了但屏幕上没有显示？Windows 正在抑制浏览器 toast。检查：设置 → 系统 → 通知（总开关以及你的浏览器的按应用开关），专注助手设置为 Off（“仅优先”会隐藏普通 toast），并用 Win + N 打开通知中心——toast 可能已经落在那里而未被注意到。
4. 十秒隔离测试——在页面控制台中运行 new Notification('DSH test', { body: 'can you see me' })。如果那个 toast 也不可见，那么抑制发生在 Windows/浏览器一侧，任何插件代码都无法修复。
* 提示音无声。 音量可能为 0，浏览器标签页可能被静音，或者自动播放策略会让 AudioContext 保持挂起状态，直到你第一次交互——在页面任意位置点击或输入一次，然后它就会播放。
* 浏览器会话的第一次提示音会延迟几秒。 Chrome 内的第一次音频渲染会启动操作系统音频设备（在某些 Windows 机器上需要 3-5 秒），而自动播放策略只允许从用户手势开始启动——任何页面内代码都无法在手势之前启动音频，所以每个网站都承担这个成本。消除它的习惯：打开页面后，在页面任意位置点击一次（插件会在第一次手势时恢复上下文并播放一个无声的预热音）；等你切换效果或任务完成时，设备已经预热，提示音就会立即响起。
* 当你在观看对话时 toast 触发了。 这是 Always 时机模式在发挥作用。将 Toast timing 行切换为 Only when unfocused，toast 就只会在标签页被切换走或浏览器窗口失去焦点时触发。

📌 主题
dsh deepseek-harness cordis cordis-plugin web-ui notification reminder web-audio

🤝 贡献

请参阅 CONTRIBUTING.md。

📄 许可证

根据 MIT 许可证授权。