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 主动发进度；
• 即装即用：自带 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 的贡献

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

📋 前置要求

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

② 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

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

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

🧪 验证

# 单元测试（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—— 设置面板组件契约（settings.section）、client bundle 构建、包名装配、配置热更新与踩坑记录。

🤝 贡献

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

📄 许可

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