ltao0829/dsh-task-notify

dsh-task-notify

AI 编程代理的生命周期通知层，当前支持 DeepSeek Harness。

CI
npm version
License: BSD-3-Clause

AI 编程代理越来越多地运行长时间、自主的任务：一轮任务可能持续数分钟，而用户通常已经切到别的窗口。本项目在代理任务生命周期之上补上了缺失的通知层：当代理完成、失败、后台任务结束、或开始等待人工介入（审批 / 计划评审 / 提问）时，立即通过页面 toast、操作系统级桌面通知以及可选提示音提醒你。

借鉴 Codex 的桌面通知体验，而非 Codex 集成。与 OpenAI 无关联，也不受 OpenAI 赞助。 目前本项目以 DeepSeek Harness（DSH）插件形式发布；其生命周期检测核心与宿主无关，设计目标是逐步演进为支持更多编程代理的适配器。

为什么需要它

长任务代理反转了传统注意力模型：用户提交任务后就会切走，而不是盯着终端。纯 UI 状态提示（后台标签页里的一个 spinner）恰恰在关键时刻失效——用户没有在看。dsh-task-notify 把生命周期变化转化为可打断的、系统级的信号，闭合自主代理与分心用户之间的反馈环。

演示

占位 —— 请替换为 10–30 秒的 GIF/MP4 录屏，录制方法见 docs/demo-guide.md。

| 任务完成 | 需要审核 | 后台任务失败 |
| --- | --- | --- |
| 任务完成 | 需要审核 | 后台任务失败 |

功能

- 对话任务完成提醒 —— 助手一轮任务（思考或工具调用）结束时提醒。
- 后台任务完成提醒 —— 后台命令或子代理作业结束时提醒（completed / failed / killed）。
- 需要审核提醒 —— 运行中等待审批 / 计划评审 / 回答提问时提醒。
- 失败提醒 —— 对话任务报错或后台任务失败 / 被终止时提醒。
- 三种通知通道 —— 浏览器系统通知 + 页面 toast + 可选双音提示音。
- 逐项开关 —— 每类事件和每种通道均可独立开关。

安装

前置：先安装 Node.js 和 pnpm。

从 npm 安装（推荐）
dsh plugin --profile web add @ltao0829/dsh-task-notify

或从 Git 安装
dsh plugin --profile web add git+https://github.com/ltao0829/dsh-task-notify.git

重启 dsh web 并刷新页面。首次在页面里点击/按键时，浏览器会请求「通知」权限，点允许即可收到系统通知。

配置

设置界面「插件」区会出现「任务完成提醒」卡片，配置存于 localStorage（键 dsh.taskNotify.v1）：

| 开关 | 默认 | 说明 |
| --- | --- | --- |
| 启用提醒 | 开 | 总开关 |
| 对话任务完成提醒 | 开 | 助手一轮任务结束时提醒 |
| 后台任务完成提醒 | 开 | 后台命令 / 子代理作业结束时提醒 |
| 需要审核时提醒 | 开 | 运行中等待审批 / 计划评审 / 提问时提醒 |
| 失败时提醒 | 开 | 对话任务报错或后台任务失败 / 被终止时提醒 |
| 浏览器系统通知 | 开 | 同时发送操作系统通知（需授权） |
| 提示音 | 关 | 同时播放提示音 |

架构

coding agent（编程代理）
│
▼
宿主适配器（当前为 DeepSeek Harness；
未来可扩展 Claude Code / Codex / OpenCode）
│
▼
会话快照（N-1 与 N）
│
▼
生命周期检测器 ──►  事件：turn | job | review | failure
│
▼
通知分发器
│          │          │
▼          ▼          ▼
系统通知     toast      提示音

检测器（src/detect.ts）是纯函数：快照进去，生命周期事件出来。它不依赖 DSH 或 DOM，因此未来支持更多编程代理只需实现新的快照提供者，而无需重写通知核心。

- 首个快照只建立基线 —— 刷新页面不会为历史任务补发提醒。
- src/detect.ts 与宿主无关（纯数据进 / 纯数据出），可独立单测。

项目结构

src/index.ts                         宿主半部 —— 注册设置区
src/detect.ts                        纯生命周期检测器（快照 diff）
src/client/index.ts                  浏览器半部 —— 监听器 + 失败监听器
src/client/notify.ts                 toast / 系统通知 / 提示音
src/client/settings.ts               localStorage 设置存储
src/client/TaskNotifySettingsCard.tsx 设置卡片
tests/*.spec.ts                      检测器、设置、通知、生命周期测试

安全与隐私

- 无外部服务器，无云后端。
- 无遥测、无分析、无追踪。
- 无需 API 密钥。
- 通知全部在浏览器本地生成。
- 设置仅保存在本地 localStorage。
- 插件不会上传或外传对话内容。

与其他 DSH 插件一样，插件以你 DSH 进程的权限运行。

路线图

当前阶段

- [x] 对话任务完成通知
- [x] 后台任务通知
- [x] 审批 / 计划评审 / 提问通知
- [x] 失败通知
- [x] 系统通知 + toast + 提示音
- [x] npm 正式发布（@ltao0829/dsh-task-notify）
- [x] CI/CD（typecheck + test + build + pack dry-run）

近期

- [ ] npm 下载量 / 采用度跟踪
- [ ] 跨平台通知后端
- [ ] 通知自定义
- [ ] 更完善的测试覆盖

长期

- [ ] 与代理无关的生命周期 API
- [ ] 更多编程代理集成（Claude Code、Codex、OpenCode……）
- [ ] 可复用的通知核心

相关项目

- dsh-launcher —— DeepSeek Harness Web 的一键启动器。

两者共同构成一套面向 AI 编程代理工作流的小型工具集。

同一作者的另一个项目：buaa-auto-auth —— 为一台 Windows 机器每天自动完成校园网（SRun）认证。

贡献

见 CONTRIBUTING.md。

兼容性与一次性 Profile 验证

- Node.js：>=20.0.0（在 Node 20 及 Node 22/24 上均通过验证）
- DeepSeek Harness：>=0.1.0-rc.6  限制与边界说明：Catalog 准入及一次性 Profile 验收证明插件生命周期契约与标准 Web Profile 启动兼容；系统级操作系统通知依然依赖用户在浏览器前端授予通知权限。

开发

pnpm install
pnpm run typecheck
pnpm test
pnpm run build
pnpm run verify:profile

License

BSD-3-Clause