dsh-WeCom-notify

<p align="center"> <h1 align="center">dsh-WeCom-notify</h1> <p align="center"> A <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> (dsh) plugin that pushes <strong>WeChat Work (企业微信) group-robot notifications</strong> to your phone — automatically. </p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/github/license/GuZhengSVT/dsh-WeCom-notify" alt="License"></a> <img src="https://img.shields.io/badge/DeepSeek%20Harness-plugin-blue" alt="DeepSeek Harness plugin"> <img src="https://img.shields.io/badge/WeCom-企业微信%20webhook-brightgreen" alt="WeCom webhook"> <img src="https://img.shields.io/badge/Event--driven-auto%20notify-orange" alt="Event-driven"> <img src="https://img.shields.io/badge/Settings%20UI-即装即用-purple" alt="Settings UI"> </p> </p> ---

这是什么？

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

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

本项目是 https://github.com/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 应该能主动找到你」，本项目把这条链路换成了官方、自动、可靠、**开箱即用**的企业微信通道。

📋 前置要求

- https://github.com/deepseek-ai/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： ``bash

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 <文件>）： `yaml - 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 设置 → 企业微信通知 面板保存后写入 <DSH_HOME>/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（静态声明，可选）

`yaml - 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 时插件正常加载，通知降级为日志提示，不报错。

🧪 验证

`sh

单元测试（51 个用例）+ 类型检查

npm test npm run typecheck

冒烟：真实发一条到群里（多 key 逗号分隔）

WECHAT_WEBHOOK_KEY=<你的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=<dsh源码目录> npm run build），产物不受影响。 **为什么设置面板在 patch 挂载（file://）下不显示？** 浏览器端的 client 模块由 dsh 的 modules 服务扫描「声明了 dsh.client 的**包**」发现； file:// 直接入口不是包，请用 bundle 装配（方式 A）。 **改了 key 但没生效？** 设置面板保存的文件（<DSH_HOME>/wecom-notify/config.json）优先级最高；如你改的是 cordis.yml`/环境变量但文件已存在，删除该文件即可回到静态配置。

🛠️ 开发

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

🤝 贡献

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

📄 许可

[MIT](LICENSE) © GuZhengSVT，致谢 https://github.com/wssfk12138/dsh-wechat-notify。