dsh-email-notify

📧 dsh-email-notify DeepSeek Harness 的开源任务通知插件 · 简体中文 · English

dsh-email-notify 是 DeepSeek Harness（DSH）的邮件通知插件，支持以下触发方式：

1. 官方自动化任务完成：监听 schedule 注入的 user/message，在任务轮次结束（turn/end）后发送任务完成邮件。
2. 对话完成通知：在对话输入框左侧开启「邮件通知」开关后，当前会话每完成一轮都会发送一封完成邮件。
3. 审批/提问提醒：等待用户审批或回答 ask_user_question 时发送提醒邮件。

自动化任务 user/message → 标记任务轮次 → turn/end → 发送任务完成邮件
                                   └→ 同轮抑制会话完成邮件
用户普通 turn/end → 检查 notify-sessions.json → SMTP 发送完成邮件

✨ 特性

• 🔔 自动化任务完成通知：官方定时/自动化任务结束后发送任务完成邮件。
• 💬 对话完成通知：在对话输入框左侧开启「邮件通知」开关，当前会话每完成一轮自动发信；开关状态按会话持久化。
• ⏳ 审批邮件提醒：设置中开启后，等待用户审批时发送提醒邮件；可分别选择「工作区审批提醒」与「Auto review 转手动审批提醒」，默认关闭。
• ❓ 提问邮件提醒：设置中开启后，Agent 使用 ask_user_question 等待用户回答时发送提醒邮件，正文包含问题与选项；默认关闭。
• 🚫 任务轮次去重：自动化任务执行的那一轮不会再发会话完成邮件；任务结束后用户继续对话，会话通知恢复正常。
• 💾 开关状态持久化：对话开关状态保存在 ~/.dsh/email-notify/notify-sessions.json。
• 🎛️ 一级设置页：在 DSH 设置侧边栏直接显示「邮件通知」，无需进入「Web UI 插件」子级，全部配置在页内完成。
• 📨 一键测试邮件：配置完成后点一下按钮即可验证 SMTP 是否可用。
• 🏷️ 会话名称优先：通知邮件主题与正文使用会话名称；会话 ID 作为会话属性放在正文中。
• 🧩 模板可自定义：任务通知、对话通知、审批通知、提问通知分别有独立的主题/正文模板，默认已填好当前格式。
• 👥 多收件人：收件人支持逗号、分号或换行分隔。
• 🔒 安全优先：所有 HTTP API 仅接受 loopback 请求；授权码以 secret 声明，浏览器侧脱敏显示。
• 🤖 Agent 公告可关：默认向 Agent 系统提示注入插件说明，可在设置中关闭。

📦 安装

前置依赖

• DeepSeek Harness（含 Web GUI 与官方桌面端），DSH 0.1.1-rc.x / 0.1.5-rc.x / 0.2.0-rc.x / 0.2.1-rc.x——插件对四代客户端/宿主接缝都做了适配，装同一份构建即可
• Node.js ^22.19.0 || >=24
• pnpm 10.x
• 自动化任务通知依赖 DSH 官方 schedule（0.2.1-rc.x 默认包含）；任务看板轮询已停用

从源码安装

git clone https://github.com/MCviseron/dsh-email-notify.git
cd dsh-email-notify
pnpm install      # prepare 钩子会自动执行 pnpm build
dsh plugin --profile web add "$PWD"

Windows Git Bash 下 $PWD 会展开为绝对路径；如果 dsh CLI 不在 PATH 中，可改用：

```sh

npx -y @deepseek-ai/dsh plugin --profile web add "$PWD"

`

安装完成后校验并重启：

dsh --profile web --dump-config   # 确认 bundle 中包含 dsh-email-notify
dsh web

刷新 Web GUI，打开设置，即可在侧边栏看到「邮件通知」一级设置页。

卸载

dsh plugin --profile web remove dsh-email-notify

卸载后刷新 Web GUI 即可；本地源码目录不会被删除。

🚀 快速开始（QQ 邮箱）

1. 登录 QQ 邮箱 → 设置 → 账户。
2. 找到「POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV 服务」，开启 SMTP 服务。
3. 按提示发送短信后生成一个授权码——它不是 QQ 登录密码。
4. 打开 Web GUI「设置 → 邮件通知」，填写：

字段 · 值 SMTP 服务器 · smtp.qq.com SMTP 端口 · 465 使用 SSL/TLS · 开 发件邮箱 · 你的QQ号@qq.com 邮箱授权码 · 第 3 步生成的授权码 发件人地址 · 你的QQ号@qq.com 或 DSH 通知 收件人 · 接收通知的邮箱（可多个）

1. 点击 「发送测试邮件」，收到邮件即配置成功。

使用 587 端口 + STARTTLS 时：SMTP 端口填 587，关闭「使用 SSL/TLS」。

其他邮箱服务商（Gmail、Outlook、163 等）只需替换 SMTP 服务器、端口与凭据。

💬 对话完成通知

配置好 SMTP 后，在任意对话的输入框左侧会看到「邮件通知」开关：

• 开启后仅对当前会话生效；
• 该会话每完成一轮（turn/end）都会发送一封完成邮件；
• 关闭开关后不再发送；
• 开关状态持久化在 ~/.dsh/email-notify/notify-sessions.json，Host 重启后仍然保留。

对话完成邮件默认标题为 [DSH 对话完成] {{sessionName}}，默认正文为 DSH 会话「{{sessionName}}」已于 {{time}} 完成一轮对话。，并把 {{sessionId}} 作为「会话属性」写入正文；标题与正文都可以在设置中的「对话通知主题模板 / 对话通知正文模板」里修改。

⏳ 审批邮件提醒

在「设置 → 邮件通知」中开启 「审批邮件提醒」（默认关闭）后，DSH 等待用户审批时会发送一封提醒邮件，内容包含审批提示、工具名、调用 ID、会话名称、会话 ID 与时间。

可分别选择两种模式：

• 工作区审批提醒：沙箱/工作区权限升级等需要用户审批的场景。
• Auto review 转手动审批提醒：官方 dsh-experimental-auto-review 插件判定拒绝并把调用转交用户手动审批的场景。

Auto review 转手动审批提醒选项只有在官方 auto review 插件已安装并启用时才显示/可选；未安装或未启用时插件不会提供该选项，只保留工作区审批提醒。

审批邮件默认标题为 [DSH 审批提醒] {{sessionName}} 的 {{toolName}} 等待审批，正文优先使用界面上的本地化审批提示（displayReason），并附带原始审批原因与会话 ID；标题与正文都可以在设置中的「审批通知主题模板 / 审批通知正文模板」里修改。

❓ 提问邮件提醒

在「设置 → 邮件通知」中开启 「提问邮件提醒」（默认关闭）后，Agent 使用 ask_user_question 等待用户回答时会发送一封提醒邮件。正文包含：

• 会话名称与会话 ID；
• 问题数量；
• 每个问题的标题、问题正文、可选项与说明；
• 是否可多选。

默认标题为 [DSH 提问] {{sessionName}} 需要你的回答，正文与标题都可以在「提问通知主题模板 / 提问通知正文模板」中修改；提问提醒只观察、不回答，不会影响 Agent 等待用户的流程。

⚙️ 设置项

设置 · 默认值 · 说明 启用插件 · true · 关闭后不发信 向 Agent 公告本插件 · true · 在系统提示中注入插件能力说明 自动化任务通知 · true · 官方定时/自动化任务结束后发信；该轮抑制会话完成邮件 审批邮件提醒 · false · 等待用户审批时发送提醒；默认关闭 工作区审批提醒 · true · 审批提醒开启后，工作区/沙箱审批是否发信 Auto review 转手动审批提醒 · true · 审批提醒开启后，官方 auto review 转手动审批是否发信；插件不可用时该项不可选 提问邮件提醒 · false · Agent 使用 ask_user_question 等待回答时发送提醒；默认关闭 SMTP 服务器 · smtp.qq.com · 任意 SMTP 服务 SMTP 端口 · 465 · QQ 邮箱 SSL；STARTTLS 常用 587 使用 SSL/TLS · true · 465 开；587 + STARTTLS 关 发件邮箱 · 空 · SMTP 登录账号 邮箱授权码 · 空 · 不是登录密码；留空时不发送任何邮件 发件人地址 · 空 · 可写作 名称 收件人 · 空 · 逗号/分号/换行分隔 任务通知主题模板 · [DSH 任务完成] {{taskTitle}} - {{resultText}} · 自动化任务通知主题 任务通知正文模板 · 见默认值 · 自动化任务通知正文 对话通知主题模板 · [DSH 对话完成] {{sessionName}} · 对话完成通知主题 对话通知正文模板 · 见默认值 · 对话完成通知正文，包含会话 ID 属性 审批通知主题模板 · [DSH 审批提醒] {{sessionName}} 的 {{toolName}} 等待审批 · 审批提醒主题 审批通知正文模板 · 见默认值 · 审批提醒正文，包含会话 ID 属性 提问通知主题模板 · [DSH 提问] {{sessionName}} 需要你的回答 · 提问提醒主题 提问通知正文模板 · 见默认值 · 提问提醒正文，包含问题与选项

🧩 模板变量

任务、对话、审批、提问四类通知都各自支持主题与正文模板；不存在的变量会被替换为空字符串。

任务通知变量（自动化任务）

变量 · 说明 · 示例 {{taskTitle}} · 任务标题（提醒 prompt 第一行） · 每周巡检 {{result}} · turn 结束原因 · completed / error / aborted {{resultText}} · 结果中文文案 · 成功 / 失败 / 已取消 {{taskId}} · schedule ID · schedule-... {{executionId}} · 触发消息 ID · 1f31... {{startedAt}} · turn 开始时间 · 2026/10/18 09:00:00 {{endedAt}} · turn 结束时间 · 2026/10/18 09:05:12 {{durationText}} · 耗时 · 5 分钟 12 秒 {{error}} · 失败详情 · timeout {{sessionName}} · 会话名称 · 发送邮箱通知dsh插件 {{sessionId}} / {{session}} · 会话 ID · session-... {{scheduleId}} · 首个 schedule ID · schedule-... {{occurrenceAt}} · 计划触发时间 · 2026-10-18T01:00:00.000Z {{prompt}} · 首个提醒 prompt · 每周巡检... {{taskCount}} · 本批任务数 · 1

对话通知变量

变量 · 说明 {{sessionName}} · 会话名称（优先展示） {{sessionId}} / {{session}} · 会话 ID（会话属性） {{time}} · 完成时间

审批通知变量

变量 · 说明 {{sessionName}} · 会话名称（优先展示） {{sessionId}} / {{session}} · 会话 ID（会话属性） {{modeText}} · 模式中文名，如 工作区审批提醒 {{mode}} · 模式标识：workspace / auto-review {{toolName}} · 工具名 {{callId}} · 调用 ID（可能为空） {{time}} · 审批请求时间 {{prompt}} · 审批提示内容 {{reason}} · 原始审批原因

提问通知变量

变量 · 说明 {{sessionName}} · 会话名称（优先展示） {{sessionId}} / {{session}} · 会话 ID（会话属性） {{count}} · 问题数量 {{questions}} · 全部问题与选项的格式化文本 {{question}} · 第一个问题的题干 {{time}} · 提问时间

🔧 工作原理

1. Host 监听每个会话的 session/event。
2. 收到 user/message 且 source.kind === 'schedule' 时，解析 [SCHEDULE REMINDER] / [SCHEDULE REMINDER BATCH]，记录该会话的待执行自动化任务。
3. 下一次 turn/start 将该任务绑定到当前轮次；turn/end 时发送任务完成邮件，并跳过同一轮的对话完成邮件。
4. 普通用户消息的 turn/end 仍按会话开关状态发送对话完成邮件；任务结束后的后续对话不受影响。
5. Host 监听 approval/request waterfall（只观察并 next() 放行）：审批提醒开启且对应模式选中时，发送包含审批提示内容的提醒邮件。
6. Host 监听 user-questions/request waterfall（只观察并 next() 放行）：提问提醒开启时，发送包含问题与选项的提醒邮件。
7. 所有会话相关通知优先解析 ctx.sessionTitle 里的会话名称；会话 ID 作为会话属性写入正文。
8. Web 侧一级设置页通过插件自带的 loopback 设置桥读写配置，并调用「测试邮件」接口；输入框开关通过 conversation-notify/describe / conversation-notify/set 接口读写；审批模式可用性通过 approval/availability 接口读取；诊断信息通过 approval/status 读取。

自动化任务 user/message → 标记任务轮次 → turn/end → 任务完成邮件
用户普通 turn/end → 检查 notify-sessions.json → 会话完成邮件

🔒 安全说明

• 插件所有 HTTP API（测试邮件、设置读写）仅接受 loopback 请求，并校验 Host 头与同源 Origin，不信任 X-Forwarded-For。
• SMTP 授权码以 role('secret') 声明：浏览器读取配置时脱敏（显示为空），真实授权码不会回传前端。
• 已通知执行 ID 与收件人等状态保存在用户主目录私有路径，不写入仓库。
• 如发现安全问题，请参考 SECURITY.md，不要在公开 Issue 中粘贴真实授权码。

🗂️ 项目结构

dsh-email-notify/
├── src/
│   ├── index.ts                  # 插件入口：配置、系统提示、路由注册
│   ├── notifier.ts               # 自动化任务轮次、模板渲染、发信
│   ├── mailer.ts                 # nodemailer 封装、收件人解析、配置校验
│   ├── routes.ts                 # 测试邮件 / 设置桥接 HTTP API
│   ├── loopback.ts               # loopback 请求校验
│   └── client/                   # Web GUI 设置页 + 对话开关（React）
│       ├── index.ts              # 注册 settings.section 与 conversation.input.left
│       ├── EmailNotifySettingsCard.tsx
│       ├── ConversationNotifyCheckbox.tsx
│       ├── locales.ts            # 中英文案
│       └── settings-scope.ts     # 设置桥接客户端
├── lib/                          # 构建产物（git 忽略，pnpm build 生成）
├── cordis.patch.yml              # DSH bundle patch
├── build.mjs                     # esbuild 构建脚本
└── package.json

🛠️ 开发

pnpm install      # 安装依赖（prepare 钩子自动构建）
pnpm typecheck    # TypeScript 类型检查
pnpm build        # 构建 lib/index.js 与 lib/client.js
pnpm check        # typecheck + build

提交 PR 前请保证 pnpm check 通过；CI 会在 GitHub Actions 上自动执行相同的检查。

更多约定见 CONTRIBUTING.md，变更历史见 CHANGELOG.md。

❓ 常见问题

测试邮件发送失败？

• 确认使用的是邮箱授权码而不是登录密码。
• 465 端口请开启「使用 SSL/TLS」；587 端口请关闭并确认服务商支持 STARTTLS。
• 确认「发件人地址」非空，格式可为 name@example.com 或 名称 。
• 检查网络/防火墙是否能访问 SMTP 服务器（QQ 邮箱一般无需代理）。

自动化任务完成了但没收到邮件？

• 确认「自动化任务通知」已开启。
• 自动化任务必须由官方 schedule 注入；普通定时提醒也会走同一路径。
• 查看 Host 日志中是否有 [dsh-email-notify] automation completion send failed。
• 诊断接口：http://127.0.0.1:/api/dsh-email-notify/approval/status。

开启了「邮件通知」但对话完成后没收到邮件？

• 确认 SMTP 配置完整，且「发送测试邮件」可以成功收到。
• 开关状态是按会话记录的：换一个对话需要重新开启。
• 查看 Host 日志中是否有 [dsh-email-notify] conversation completion send failed 或 send failed。

审批邮件提醒没有收到？

• 确认「审批邮件提醒」已开启（默认关闭），且对应的「工作区审批提醒」/「Auto review 转手动审批提醒」模式已开启。
• 「Auto review 转手动审批提醒」只有在官方 auto review 插件已安装并启用时才可选。
• 当前审批请求必须处于等待用户审批状态；审批提醒不会改变审批结果。
• 查看 Host 日志中是否有 [dsh-email-notify] approval notify failed。

提问邮件提醒没有收到？

• 确认「提问邮件提醒」已开启（默认关闭）。
• 只有 Agent 通过 ask_user_question 向你提问时才会触发；普通对话不会触发。
• 提问提醒只观察、不回答，不会改变 Agent 的等待流程。
• 查看 Host 日志中是否有 [dsh-email-notify] ask notify failed；也可以打开 http://127.0.0.1:/api/dsh-email-notify/approval/status 查看 askObserved / askSent / lastAsk。
• 若要清空所有会话的开关状态，删除 ~/.dsh/email-notify/notify-sessions.json 后重启 Host。

📄 License