dsh-messager

DeepSeek Harness（DSH）任务状态通知插件：会话需要交互、任务完成、任务出错时，通过 系统通知（OS toast）、浏览器通知、飞书 / 企业微信 / Discord / 钉钉 / Telegram 推送提醒，不再依赖盯着会话列表的圆点。

单包双运行端（dual-runtime）结构：host 端（Node，服务端）负责系统通知与全部第三方通道， client 端（浏览器）负责 Web Notification；两者配置同源（settings 命名空间 messager），设置页「通知&信使」分区可编辑、实时生效 —— 配置通道经插件自身的 webServer 路由（/dsh-messager/config），不受 DSH 设置白名单限制，发行版（npx 安装）同样可用。

能力一览

需求	实现
触发时机	需要交互（审批 `approval/asked`、提问/计划待审 `ask_user_question`、客户端 pendingInteraction）、任务完成（`agent/status` running→idle 且仅根会话 + `turn/end` 原因）、任务出错（`agent/error`）
推送路径	系统通知（node-notifier toast）、浏览器通知（Notification API）、飞书（interactive 卡片 + HMAC-SHA256 签名）、企业微信（markdown + 可选加签）、Discord（embed 卡片）、钉钉（actionCard + 可选加签）、Telegram（Bot API HTML 消息）；`NotifyChannel` 接口可扩展
可配置	触发开关、各通道启停/verbosity/icon、去重冷却、标题前缀等，见配置

触发语义与 Web UI 状态圆点完全对齐：橙点 = 需要交互（pendingInteraction），绿点 = 任务完成 （running→idle 且非当前会话），蓝点 = 运行中（不通知）。

安装

📖 面向使用方的完整分步指南见 doc/用户安装指南.md —— 覆盖 源码方式（clone + 本地构建）与 pnpm 方式（本地 checkout / tarball / git / npm）两类安装。

正式安装只需一步（host 端 + 浏览器 client 端都会生效，之后直接 dsh web 启动即可， 不需要 --patch）：

# 在插件仓库构建产物
pnpm install
pnpm build

dsh plugin --profile web add <插件路径>
dsh web   # 或 dsh --profile web

pnpm install 与 pnpm build 在你的插件仓库目录内执行；<插件路径> 替换为该目录（绝对或相对路径均可）。完整的分步安装指南见 doc/用户安装指南.md。

--patch 不是安装步骤，而是可选的开发调试手段（见下节「本地开发」）：它只加载 host 端、不写 profile、仅对本次启动生效。装了 bundle 之后请勿再同时带 --patch 启动同一插件（host 端会加载两份，settings 命名空间重复注册报错）。

以源码方式运行 DSH（从 deepseek-harness 仓库根目录）时，把上述 dsh 换成 pnpm dsh 即可，命令与行为完全一致：pnpm dsh plugin --profile web add …、 pnpm dsh web。profile 目录仍为 $DSH_HOME/profiles/web（dsh web 即 --profile web 别名）。

从 git 安装时 pnpm ≥ 10 需要放行构建脚本：把 pnpm 提示的包名加入 profile 的 pnpm-workspace.yaml 的 allowBuilds（见 DSH 官方 publish 教程）。

设置分区「通知&信使」（所有环境可用）

安装后 DSH 设置页左侧菜单会出现 「通知&信使」 分区（排在「Agent预设」下方，位置随已有分区动态计算，不写死）。分区内是完整的配置表单，读写经插件自身的 webServer 路由（/dsh-messager/config，同源校验 + 脱敏视图）直达 host 端 settings 服务 —— 不依赖 DSH 的设置白名单，发行版（npx 安装）开箱即用，无需任何补丁。

配置与 settings.yaml 同源（同一命名空间）：任一处变更均实时生效。

本地开发

host 端（快速）：从 DSH 仓库根目录运行 pnpm dsh web --patch <插件路径>/cordis.yml，直接加载 TS 源码（HMR 生效）。源码模式下的 host 经 tsx 运行，该路径无需构建即可加载。
完整双运行端：浏览器（client）端要求插件以包身份进入 Loader 才会被 clientModules 扫描编入 Web bundle（--patch 的文件路径入口不会被扫描），因此完整开发请安装到 profile：
```
dsh plugin --profile web add <插件路径>   # 源码模式：pnpm dsh plugin ...
pnpm dsh web   # 从 DSH 源码仓库运行
```
plugin add 后需要重启 pnpm dsh web（clientModules 启动时扫描，运行中的实例不会热加入新 bundle）。修改 client 端代码后在自己的仓库重新 pnpm run build:client 并刷新页面即可（bundle 带 rev hash 会重新拉取；DSH 仓库的 dev:web watcher 只盯 workspace 内的 client 插件，不盯外部插件）。

浏览器通知需要用户授予权限：首次加载插件时若权限为 default 会自动请求一次；被拒绝时浏览器通道静默降级（其余通道不受影响），可在浏览器站点设置中重新授权。

配置

配置优先级：schema 默认值 → base（该插件行的 config:）→ 用户层（Web 设置页）。 host 端把 Loader config 注册为 settings 命名空间 messager 的 base 层，因此：

base 的写法按使用方式不同：dev 调试写在 cordis.yml（patch 覆盖层）里该行的 config:；正式安装写在 profile 的 cordis.patch.yml 里按 id: messager 覆盖该行，或直接改 bundle 包内的 cordis.patch.yml；
用户层三处入口，同源不冲突、任一处变更均实时生效（host 端 watch 重建通道； client 端经 settings/document-updated 失效重拉）：
1. 设置页分区：设置 →「通知&信使」分区（完整字段表单，所有环境可用）；
2. 设置文档：直接编辑 $DSH_HOME/settings.yaml 的 messager: 段（完整字段，含 dedup 节流等表单未展示的项）；
3. RPC：settings.describe / settings.mutate（host 侧可用；Web 端白名单不影响本插件的分区，因为分区走插件自己的配置路由）。

配置读写链路：设置分区 → GET/POST /dsh-messager/config（webServer 路由，同源校验） → host 端 settings 服务（describe 脱敏视图 / mutate 逐字段 ops）→ settings.yaml。写后 settings/document-updated 事件（DSH 内置转发）驱动前端刷新。

🌐 国际化：分区菜单与表单文案随 DSH 设置的语言切换（中文 / English），字典注册在 ctx.locale（zh/en 键集一致，缺失键 fail loud 显示键名）。

字段	类型	默认值	说明
`triggers.interaction`	boolean	`true`	需要交互时通知（审批/提问/计划待审）
`triggers.completed`	boolean	`true`	任务完成时通知
`triggers.error`	boolean	`true`	任务出错时通知
`system.enabled`	boolean	`true`	系统通知通道
`system.icon`	string	-	图标绝对路径（node-notifier 需要文件路径，且该文件必须存在）
`system.verbosity`	`minimal\|normal\|detailed`	`normal`	系统通知内容繁复度
`browser.enabled`	boolean	`true`	浏览器通知通道
`browser.icon`	string	-	图标 URL 或 data URL
`browser.onlyWhenHidden`	boolean	`true`	仅页面隐藏/未聚焦时弹（看着界面不打扰）
`browser.verbosity`	`minimal\|normal\|detailed`	`normal`	浏览器通知内容繁复度
`feishu.enabled`	boolean	`false`	飞书机器人（webhook）通道
`feishu.webhookUrl`	string	-	自定义机器人 webhook 地址
`feishu.secret`	string（secret）	-	签名密钥（机器人「安全设置-签名校验」）
`feishu.timeoutMs`	number	`5000`	单次请求超时
`feishu.verbosity`	`minimal\|normal\|detailed`	`normal`	卡片内容繁复度
`wecom.enabled`	boolean	`false`	企业微信群机器人（webhook）通道
`wecom.webhookUrl`	string	-	群机器人 webhook 地址（含 `?key=`）
`wecom.secret`	string（secret）	-	加签密钥（「安全设置-加签」，HMAC-SHA256，无需 URL 编码）
`wecom.timeoutMs`	number	`5000`	单次请求超时
`wecom.verbosity`	`minimal\|normal\|detailed`	`normal`	消息内容繁复度
`discord.enabled`	boolean	`false`	Discord 通道（webhook）
`discord.webhookUrl`	string	-	Discord webhook 地址（`.../api/webhooks/<id>/<token>`）
`discord.timeoutMs`	number	`5000`	单次请求超时
`discord.verbosity`	`minimal\|normal\|detailed`	`normal`	embed 内容繁复度
`dingtalk.enabled`	boolean	`false`	钉钉自定义机器人（webhook）通道
`dingtalk.webhookUrl`	string	-	自定义机器人 webhook 地址（含 `?access_token=`）
`dingtalk.secret`	string（secret）	-	加签密钥（「安全设置-加签」，HMAC-SHA256 + URL 编码）
`dingtalk.timeoutMs`	number	`5000`	单次请求超时
`dingtalk.verbosity`	`minimal\|normal\|detailed`	`normal`	卡片内容繁复度
`telegram.enabled`	boolean	`false`	Telegram 通道（Bot API）
`telegram.botToken`	string（secret）	-	Bot Token（@BotFather 获取）
`telegram.chatId`	string	-	接收 chat_id（数字 ID 或 `@频道用户名`）
`telegram.timeoutMs`	number	`5000`	单次请求超时
`telegram.verbosity`	`minimal\|normal\|detailed`	`normal`	消息内容繁复度
`dedup.interactionCooldownMs`	number	`10000`	同会话同触发冷却（也用于跨标签去重窗口）
`dedup.completedDebounceMs`	number	`1000`	完成通知防抖（等待 turn/end 原因、合并边界）
`dedup.perChannelPerMinute`	number	`20`	每通道每分钟上限（防第三方限流/刷屏）
`message.titlePrefix`	string	-	标题前缀，如 `[DSH]`
`message.includeSessionTitle`	boolean	`true`	正文附带会话标题
`message.guiUrl`	string	`http://127.0.0.1:3080`	通知「打开」链接/按钮目标

内容繁复度：minimal 只有标题；normal 增加会话标题/工具名/结束原因/错误摘要； detailed 再增加 turn/step、审批原因与 GUI 链接。

触发信号（事件 → 通知映射）

触发	host 端（system/feishu/wecom/discord/dingtalk/telegram）	client 端（browser）
审批	`session/event` `approval/asked`	摘要 `pendingInteraction==='approval'` 出现
提问/计划待审	`session/event` `tool/call`（`ask_user_question`）	`pendingInteraction==='question'/'plan-review'` 出现
任务完成	`agent/status` running→idle（仅根会话）＋`turn/end` 原因	摘要 `running:true→false` 且非当前会话
任务出错	`agent/error`	-（host 端覆盖）

通道扩展

新增第三方通道（钉钉/企业微信/Telegram…）实现 NotifyChannel 接口并在 src/index.ts 的 buildChannels() 注册即可：

export interface NotifyChannel {
  readonly id: string
  send(payload: NotificationPayload): Promise<void>
}

项目结构

dsh-messager/
├── package.json          # dsh.bundle + dsh.client 双声明；exports["./client"]
├── tsconfig.json         # host 端（Node）
├── tsconfig.client.json  # client 端声明输出（lib/types/client）
├── tsdown.config.ts      # client bundle（__ModuleLoader__.load 契约）
├── cordis.yml            # 本地开发覆盖层（host 端）
├── cordis.patch.yml      # 分发包配置层（安装后生效）
├── assets/icon.png       # 默认通知图标
├── src/
│   ├── index.ts          # host apply：事件接线 + settings 注册 + 通道构建 + 路由挂载
│   ├── config.ts         # Config schema（Loader config 与 settings 共用）
│   ├── config-shared.ts  # 配置路由的跨端共享类型（host/client 共用）
│   ├── config-route.ts   # webServer 配置路由（GET 视图 / POST ops，同源校验）
│   ├── signals.ts        # 事件 → Signal 提取（纯函数）
│   ├── notify.ts         # 调度：过滤/冷却/防抖/限流 + NotifyChannel 接口
│   ├── templates.ts      # verbosity 模板渲染（纯函数）
│   ├── settings.ts       # settings 命名空间注册（base = Loader config）
│   ├── channels/         # system（node-notifier）、feishu/wecom/discord/dingtalk/telegram（webhook/Bot API+签名）
│   └── client/           # 浏览器端：sessions diff、Notification、设置分区、配置同步
│       ├── index.ts      # 分区注册（动态 order）+ 浏览器通知 + 配置路由访问器
│       ├── section.tsx   # 设置页「通知&信使」分区组件
│       ├── settings-form.tsx  # 共享表单体（分组 + FieldRow + 操作栏）
│       ├── card-controller.ts # 表单控制器（纯逻辑，可单测）
│       ├── fetch-scope.ts     # ScopeLike 的 fetch 适配层（配置路由）
│       ├── locales.ts    # zh/en 字典（ctx.locale 注册）
│       ├── config.ts     # 浏览器通知的配置句柄（走配置路由）
│       └── diff.ts       # 会话摘要 diff（纯函数）
└── tests/                # vitest 单元测试（126 个）

测试

pnpm test       # 126 个单元测试：信号提取/模板/调度/各通道签名与载荷/配置解析/client diff/配置路由/fetch scope/字典一致性/表单门控
pnpm typecheck  # host 端
pnpm build      # host tsc + client 声明 + client bundle（lib/）

已知边界

浏览器通知需站点权限；onlyWhenHidden=false 时页面可见也会弹。
多标签页经 localStorage 冷却去重；不同浏览器各自通知。
子代理结束不触发完成通知（仅根会话），避免噪音。
通道失败（webhook 超时、toast 不可用）只记日志，不影响其他通道与插件运行。
完成/交互的去重状态为内存态，DSH 重启后重置（可接受）。

系统通知（node-notifier）跨平台前提

node-notifier 在三个平台调用完全不同的底层程序，平台差异如下：

平台	底层	前提条件 / 差异
Windows	PowerShell ToastNotification	内建，无需额外安装；`sound` 仅在 Windows 有可靠映射
macOS	terminal-notifier	首次使用需联网下载第三方二进制，且需登录图形会话（Dock 存在）；`sound` 不生效
Linux	notify-send（libnotify）	需安装 `libnotify-bin`，并有一个运行中的通知守护进程（GNOME Shell / Plasma / mako / dunst 等）；`sound` 不生效

图标：system.icon 需是存在的文件路径。Windows 对缺失路径多会静默降级，但 Linux/macOS 可能直接报错，故通道层已做存在性校验，无效时降级为不带图标。
环境差异不是插件 bug：Linux 若缺通知守护进程、macOS 若无法联网下载 terminal-notifier 或不在图形会话中，通知可能不弹出或静默失败——此时请先排查上述前提，而非插件；失败时调度层会 logWarn 记录具体错误。

后续规划

第三方通道扩展：邮件
触发扩展：后台 job 完成、goal 轮次完成
通知历史、按会话静音、勿扰时段

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
assets		assets
doc		doc
src		src
tests		tests
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
cordis.patch.yml		cordis.patch.yml
cordis.yml		cordis.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.client.json		tsconfig.client.json
tsconfig.json		tsconfig.json
tsdown.config.ts		tsdown.config.ts
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

dsh-messager

能力一览

安装

设置分区「通知&信使」（所有环境可用）

本地开发

配置

触发信号（事件 → 通知映射）

通道扩展

项目结构

测试

已知边界

系统通知（node-notifier）跨平台前提

后续规划

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

dsh-messager

能力一览

安装

设置分区「通知&信使」（所有环境可用）

本地开发

配置

触发信号（事件 → 通知映射）

通道扩展

项目结构

测试

已知边界

系统通知（node-notifier）跨平台前提

后续规划

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages