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-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 参数）。

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

构建：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 权限）。 文件存在时以文件为准（面板里清空 = 显式清空）；如需回到静态配置，删除该文件即可。

字段	说明
`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=<你的key> node scripts/smoke.ts
WECHAT_WEBHOOK_KEYS='key1,key2' node scripts/smoke.ts

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

🔧 工作原理（通俗版）

dsh 内部状态机触发事件（goal 完成/阻塞、每轮对话结束、agent 空闲）；
插件把事件渲染成企业微信 markdown 消息（转义 + 截断，中文不乱码）；
进入调度器：串行队列 → 节流 → 去重（同一内容）→ 多目标并发发送；
异步 fetch 发送到每个已配置的群（各群独立限频、独立重试）；
你手机收到通知；agent 主动调用 wechat_notify 走同一条链路；
设置面板通过同源 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 插件文档为准。

dsh-WeCom-notify

dsh-WeCom-notify

这是什么？

✨ 特性

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

📋 前置要求

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

方式 A：bundle 装配（推荐——含设置面板）

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

使用

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

① 设置面板（推荐）

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

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

🧪 验证

🔧 工作原理（通俗版）

📁 结构

🗺️ 路线图（Roadmap）

❓ FAQ

🛠️ 开发

🤝 贡献

📄 许可

Community comments

dsh-WeCom-notify

dsh-WeCom-notify

这是什么？

✨ 特性

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

📋 前置要求

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

方式 A：bundle 装配（推荐——含设置面板）

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

使用

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

① 设置面板（推荐）

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

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

🧪 验证

🔧 工作原理（通俗版）

📁 结构

🗺️ 路线图（Roadmap）

❓ FAQ

🛠️ 开发

🤝 贡献

📄 许可

Community comments

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

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