dsh-WeCom-notify

A DeepSeek Harness (dsh) plugin that pushes WeChat Work (企业微信) group-robot notifications to your phone — automatically.

---

这是什么？

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

• 任务完成 / 阻塞：goal 生命周期变化时自动推送（✅ dsh 任务完成 / ⛔ dsh 任务阻塞）；
• 每轮对话完成：自动推送该轮 agent 回复总结；
• agent 主动汇报：同时保留 wechat_notify 工具，供 agent 主动发进度。

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

✨ 特性

• 官方通道，零封号风险：走企业微信官方 webhook（qyapi.weixin.qq.com），免费个人注册即可用，无第三方中转；
• 事件驱动：订阅 session/event（每轮总结）与 goal/changed（完成/阻塞）自动推送，不依赖 LLM 自觉；
• 异步非阻塞：fetch 异步发送（不是 execFileSync 同步阻塞事件循环）；
• 健壮调度：串行队列、节流（默认 10s 间隔）、内容去重（默认 30s 窗口）、指数退避重试、10s 超时；
• 中文可靠：UTF-8 按码点截断（不截断 emoji 代理对），markdown 转义防格式破坏；
• 零隐私硬编码：配置全部来自环境变量，仓库不含任何本机路径与密钥；
• @ 提醒：支持 WECHAT_MENTION_USERID 在通知时 @ 指定成员；
• 降级不报错：未配置 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（零封号风险）
触发	依赖 LLM 记得调用工具	事件驱动自动推送（goal/session 状态机）
发送	execFileSync 同步阻塞	异步 fetch，队列/节流/去重/指数退避重试
文本	UTF-8 文件传递	UTF-8 码点截断 + markdown 转义

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

📋 前置要求

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

⚙️ 配置（cordis.yml config 优先，环境变量兜底，零落盘）

配置遵循 dsh 官方插件规范：通过 cordis.yml 挂载时的 config 字段注入（Schemastery 校验）； 未在 config 声明的字段回退到环境变量，再回退到默认值。优先级：config > 环境变量 > 默认值。

cordis.yml config 字段（推荐）

字段	必填	说明
webhookKey	✅（或 URL）	群机器人 webhook 的 key
webhookUrl	可选	完整 webhook 地址（优先级高于 key）
mentionUserid	可选	通知时 @ 的企业微信 userid（管理后台通讯录可查）
minIntervalMs	可选	节流间隔，默认 10000
dedupeWindowMs	可选	去重窗口，默认 30000
triggerOnAgentIdle	可选	agent 空闲时也通知（默认关，防噪音）
turnSummaryEnabled	可选	每轮对话完成推送总结（默认开）
maxBytes	可选	单条消息最大字节数（上限 4096，默认 3800；超长截断）

- insert:
    - id: wechat-notify
      name: 'file:///绝对/路径/dsh-WeCom-notify/lib/index.js'
      config:
        webhookKey: '你的群机器人 webhook key'
        minIntervalMs: 15000

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

环境变量	说明
WECHAT_WEBHOOK_KEY	群机器人 webhook 的 key
WECHAT_WEBHOOK_URL	完整 webhook 地址（优先级高于 key）
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 时插件可正常加载，通知降级为日志提示，不报错。

🚀 安装与挂载（安装即用）

插件以 esbuild 编译产物（lib/index.js）挂载，与 dsh 生态其他插件一致（Node 原生 TS 不支持 node_modules 路径，因此必须用编译后的 JS）。

一键安装（推荐）

npm install          # 安装 esbuild（一次性）
npm run install-dsh  # 编译 + 写入 ~/.dsh/profiles/web/cordis.patch.yml
dsh web              # 重启，日志出现 [wechat-notify] plugin loaded 即成功

手动安装

1. npm install && npm run build 编译出 lib/index.js。
2. 确认本目录的 node_modules/@deepseek-ai 能解析 @deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/schemastery（指向 dsh 安装的依赖；npm run install-dsh 不处理此项，依赖解析靠 node_modules 向上查找）。
3. 在 ~/.dsh/profiles/web/cordis.patch.yml（或 dsh web --patch xxx.yml）中：

   - insert:
       - id: wechat-notify
         name: 'file:///绝对/路径/dsh-WeCom-notify/lib/index.js'
         config:
           webhookKey: '你的群机器人 webhook key'
   

4. 启动 dsh web。

⚠️ 入口必须是编译后的 lib/index.js，不要指向 src/index.ts：dsh 的 loader 用 Node 原生 import，不支持 node_modules 路径下的 .ts（曾导致启动报错）。

🧪 验证

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

# 冒烟：真实发一条到群里
WECHAT_WEBHOOK_KEY=<你的key> node scripts/smoke.ts

端到端：给 dsh 一个带 goal 的任务，goal 完成时自动收到「✅ dsh 任务完成」通知。

🔧 工作原理（通俗版）

1. dsh 内部状态机触发事件（goal 完成/阻塞、每轮对话结束、agent 空闲）；
2. 插件把事件渲染成企业微信 markdown 消息（转义 + 截断，中文不乱码）；
3. 进入调度器：串行队列 → 节流 → 去重 → 指数退避重试；
4. 异步 fetch 发送到企业微信官方 webhook；
5. 你手机收到通知；agent 主动调用 wechat_notify 走同一条链路。

📁 结构

src/            # TypeScript 源码（开发用）
├── index.ts      # 插件入口：事件订阅 + 工具注册
├── config.ts     # cordis.yml Config（Schemastery）+ 环境变量兜底
├── notifier.ts   # 调度：队列 / 节流（drain 强制间隔）/ 去重 / 串行发送
├── client.ts     # 企业微信 webhook 客户端（重试 / 超时 / 限频）
├── templates.ts  # markdown 渲染 / 转义 / UTF-8 截断
└── extract.ts    # session/event 提取（每轮总结）
lib/index.js    # esbuild 编译产物（dsh 实际加载的入口）
test/           # node:test 单元测试
scripts/        # install-dsh（一键安装）、smoke（冒烟）

🗺️ 路线图（Roadmap）

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

🤝 贡献

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

📄 许可

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