企微群机器人通知 GuZhengSVT/dsh-WeCom-notify

dsh-WeCom-notify

一个 DeepSeek Harness（dsh）插件，将企业微信群机器人通知自动推送到你的手机。

这是什么？

dsh-WeCom-notify 是 DeepSeek Harness（dsh）的一个插件：通过企业微信官方群机器人 webhook，在 dsh 的关键节点自动把通知推到你的手机。

- 任务完成 / 阻塞：goal 生命周期变化时自动推送（✅ dsh 任务完成 / ⛔ dsh 任务阻塞）；
- 每轮对话完成：自动推送该轮 agent 回复总结；
- agent 主动汇报：wechat_notify 工具，供 agent 主动发进度；
- 即装即用：自带 dsh 设置 → 企业微信通知 面板，粘贴 webhook key 保存即生效，无需手写 yaml / 环境变量；
- 多群同时通知：支持填写多个 webhook key，一条通知同时发送到所有群。

全程无需 agent 记得调用工具——事件由 dsh 内部状态机触发，无法被 prompt injection 伪造。

✨ 特性

- 官方通道，零封号风险：走企业微信官方 webhook（qyapi.weixin.qq.com），免费个人注册即可用，无第三方中转；
- 设置面板，即装即用：dsh 设置 → 企业微信通知 图形化配置，多个 key 增删、@ 成员、节流参数一目了然，保存即热生效（无需重启），并持久化到 /wecom-notify/config.json（0600 权限）；
- 多群同时通知：一条消息并发发送到所有已配置的群（各群独立限频，互不拖累），逐群报告发送结果；
- 事件驱动：订阅 session/event（每轮总结）与 goal/changed（完成/阻塞）自动推送，不依赖 LLM 自觉；
- 异步非阻塞：fetch 异步发送（不是 execFileSync 同步阻塞事件循环）；
- 健壮调度：串行队列、节流（默认 10s 间隔）、内容去重（默认 30s 窗口）、指数退避重试、10s 超时；
- 中文可靠：UTF-8 按码点截断（不截断 emoji 代理对），markdown 转义防格式破坏；
- 零隐私硬编码：仓库不含任何本机路径与密钥；密钥仅存于你的用户数据目录；
- @ 提醒：支持 mentionUserid 在通知时 @ 指定成员；
- 降级不报错：未配置 key 时插件正常加载，通知降级为日志提示。

🙏 致谢：dsh-wechat-notify 的贡献

本项目是 wssfk12138/dsh-wechat-notify 的优化重写版，灵感与基础均来自该项目。

dsh-wechat-notify（v0.1.0，ClawBot 通道版）的贡献：

- 插件形态与接入方式：确立了「dsh 插件 + cordis.patch.yml 挂载 + 注册 wechat_notify 工具」的完整接入范式，本项目沿用同一生态位；
- 工具设计：wechat_notify(message) 的接口设计、可读的「已发送 / 失败原因」返回值约定、未配置时的友好提示，均继承自原项目；
- 中文可靠性思路：原项目「UTF-8 文件传递防乱码」的教训，直接催生了本项目「UTF-8 字节截断 + markdown 转义」的实现；
- 扫码登录先例：原项目的 wechat_login / wechat_login_confirm 证明了「在 dsh 内完成微信连接」的可行性。

本项目的改进（相对于 v0.1.0）：

| 维度 | dsh-wechat-notify (v0.1.0) | dsh-WeCom-notify (本项目) |
| 通道 | ClawBot 逆向接口（第三方中转，有封号风险） | 企业微信官方 webhook（零封号风险） |
| 配置 | 环境变量 / 手写 yaml | 设置面板图形化配置，即装即用 |
| 目标数 | 单个群 | 多个群同时通知 |
| 触发 | 依赖 LLM 记得调用工具 | 事件驱动自动推送（goal/session 状态机） |
| 发送 | execFileSync 同步阻塞 | 异步 fetch，队列/节流/去重/指数退避重试 |
| 文本 | UTF-8 文件传递 | UTF-8 码点截断 + markdown 转义 |

一句话：原项目证明了「dsh 应该能主动找到你」，本项目把这条链路换成了官方、自动、可靠、开箱即用的企业微信通道。

📋 前置要求
- DeepSeek Harness 运行环境（插件依赖 @deepseek-ai/cordis 与 @deepseek-ai/dsh-tools，由 dsh 自身解析）；
- 一个企业微信（免费个人注册即可），一个用于接收通知的群，群内已添加群机器人（群设置 → 群机器人 → 添加，复制 webhook 地址中的 key 参数）。

🚀 快速开始（即装即用，推荐）

1. 构建：npm install && npm run build（一次产出 host lib/index.js + 设置面板 lib/client.js）；
方式 A：bundle 装配（推荐——含设置面板）

把插件链接进 profile 依赖并以包名装配（loader 才能读到 package.json 的 dsh.client 声明，设置面板才会被浏览器加载）。macOS/Linux：

1. junction 链接到 profile node_modules ln -s /绝对/路径/dsh-WeCom-notify ~/.dsh/profiles/web/node_modules/dsh-wecom-notify
2. package.json 声明（dependencies + bundles）
dependencies: { "dsh-wecom-notify": "link:/绝对/路径/dsh-WeCom-notify" }
dsh.profile.bundles: [...原有, "dsh-wecom-notify"]

Windows 用 mklink /J。然后重启 dsh web。

方式 B：patch 挂载（仅 host 功能，无设置面板）

在 ~/.dsh/profiles/web/cordis.patch.yml 中（或 dsh web --patch ）：

- insert:
- id: wechat-notify
name: 'file:///绝对/路径/dsh-WeCom-notify/lib/index.js'
config: {} # 无需任何配置！

⚠️ 方式 B 的 file:// 入口不带设置面板（client 需包名装配）；功能（多 key / 事件通知 / API）完整。

使用

重启 dsh web，日志出现 [wechat-notify] plugin loaded；打开 dsh 设置 → 企业微信通知：
- 粘贴你的 webhook key（可多个，一行一个，「＋ 添加一个群」继续加）；
- 点 「发送测试消息」 先验证（逐群显示结果）→ 点 「保存配置」 立即生效。

也可以 npm run install-dsh 一键构建并写入 patch（默认写到 ~/.dsh/profiles/web/，方式 B）。

⚙️ 配置（优先级：设置面板文件 > cordis.yml config > 环境变量 > 默认值）

① 设置面板（推荐）

dsh 设置 → 企业微信通知 面板保存后写入 /wecom-notify/config.json（DSH_HOME 缺省 ~/.dsh，0600 权限）。
文件存在时以文件为准（面板里清空 = 显式清空）；如需回到静态配置，删除该文件即可。

| 字段 | 说明 |
| webhookKeys | 群机器人 webhook 的 key 数组（可多个，同时通知所有群） |
| webhookUrl | 附加的完整 webhook 地址（旧版兼容，额外目标） |
| mentionUserid | 通知时 @ 的企业微信 userid（可选） |
| minIntervalMs | 节流间隔（默认 10000） |
| dedupeWindowMs | 去重窗口（默认 30000） |
| triggerOnAgentIdle | agent 空闲时也通知（默认关，防噪音） |
| turnSummaryEnabled | 每轮对话完成推送总结（默认开） |
| maxBytes | 单条消息最大字节数（上限 4096，默认 3800） |

② cordis.yml config（静态声明，可选）

- insert:
- id: wechat-notify
name: 'file:///绝对/路径/dsh-WeCom-notify/lib/index.js' config: webhookKeys: # 多个 key，同时通知
- '你的第一个群机器人 webhook key'
- '你的第二个群机器人 webhook key' webhookKey: '旧版单 key（并入 webhookKeys）' webhookUrl: '完整 webhook 地址（附加目标）' mentionUserid: '通知时 @ 的企业微信 userid' minIntervalMs: 15000

③ 环境变量兜底（兼容旧版）

| 环境变量 | 说明 |
| WECHAT_WEBHOOK_KEYS | 多个 key，逗号/分号/换行分隔（key1,key2） |
| WECHAT_WEBHOOK_KEY | 单个 key（旧版，并入 keys） |
| WECHAT_WEBHOOK_URL | 完整 webhook 地址（附加目标） |
| WECHAT_MENTION_USERID | 通知时 @ 的企业微信 userid |
| NOTIFY_MIN_INTERVAL_MS | 节流间隔 |
| NOTIFY_DEDUPE_WINDOW_MS | 去重窗口 |
| NOTIFY_TRIGGER_AGENT_IDLE | agent 空闲时也通知（1/true 开启） |
| NOTIFY_TURN_SUMMARY | 每轮总结推送（0/false 关闭） |
| NOTIFY_MAX_BYTES | 单条消息最大字节数（上限 4096） |

未配置 key 时插件正常加载，通知降级为日志提示，不报错。

🧪 验证

单元测试（51 个用例）+ 类型检查
npm test
npm run typecheck

冒烟：真实发一条到群里（多 key 逗号分隔）
WECHAT_WEBHOOK_KEY= node scripts/smoke.ts
WECHAT_WEBHOOK_KEYS='key1,key2' node scripts/smoke.ts

端到端：打开 dsh 设置 → 企业微信通知 → 填 key → 发送测试消息 → 保存；再给 dsh 一个带 goal 的任务，goal 完成时自动收到「✅ dsh 任务完成」。

🔧 工作原理（通俗版）

1. dsh 内部状态机触发事件（goal 完成/阻塞、每轮对话结束、agent 空闲）；
2. 插件把事件渲染成企业微信 markdown 消息（转义 + 截断，中文不乱码）；
3. 进入调度器：串行队列 → 节流 → 去重（同一内容）→ 多目标并发发送；
4. 异步 fetch 发送到每个已配置的群（各群独立限频、独立重试）；
5. 你手机收到通知；agent 主动调用 wechat_notify 走同一条链路；
6. 设置面板通过同源 API（/wecom-notify/api）读写配置，保存即热生效并持久化。

📁 结构

src/ # TypeScript 源码 ├── index.ts # 插件入口：事件订阅 + 工具 + webServer 配置 API（/wecom-notify/api） ├── config.ts # 配置：多 key / 持久化文件层 / 优先级合并（面板文件 > config > env） ├── notifier.ts # 调度：队列 / 节流 / 去重 / 多目标发送 / 配置热更新 ├── client.ts # 企业微信 webhook 客户端（单目标 + 多目标并发汇总） ├── templates.ts # markdown 渲染 / 转义 / UTF-8 截断 ├── extract.ts # session/event 提取（每轮总结） └── client/ └── index.ts # 设置面板（settings.section：key 编辑 / 保存 / 测试） lib/index.js # esbuild 编译产物（dsh 实际加载的 host 入口） lib/client.js # tsdown 编译产物（浏览器端设置面板，ModuleLoader 加载） test/ # node:test 单元测试（51 用例） scripts/ # build（构建）、install-dsh（一键安装）、smoke（冒烟）

🗺️ 路线图（Roadmap）

- [ ] 富文本与图片/文件消息
- [ ] 双向交互（收到你的企业微信 → 触发 agent）
- [ ] 发送历史与消息模板
- [ ] 抽象多通道（Server酱 / PushPlus / 钉钉 / 飞书 / Telegram / Slack）

❓ FAQ

npm install 报 404（@deepseek-ai/dsh-compact）？
tsdown 的传递依赖引用了尚未发布的 rc 包，npm install 可能失败。构建脚本会自动回退到 DSH checkout 里的 tsdown（DSH_CHECKOUT= npm run build），产物不受影响。

为什么设置面板在 patch 挂载（file://）下不显示？
浏览器端的 client 模块由 dsh 的 modules 服务扫描「声明了 dsh.client 的包」发现； file:// 直接入口不是包，请用 bundle 装配（方式 A）。

改了 key 但没生效？
设置面板保存的文件（/wecom-notify/config.json）优先级最高；如你改的是 cordis.yml/环境变量但文件已存在，删除该文件即可回到静态配置。

🛠️ 开发

维护 / 二次开发见 docs/development-notes.md——设置面板组件契约（settings.section）、client bundle 构建、包名装配、配置热更新与踩坑记录。

🤝 贡献

欢迎提 Issue 和 PR。dsh 目前是 developer preview，接口可能调整，提交前请以最新的 dsh 插件文档为准。

📄 许可

MIT © GuZhengSVT，致谢 wssfk12138/dsh-wechat-notify。