@weniatall/dsh-im-bot

v0.1.14

Published

14 days ago

IM bot integration for DeepSeek Harness: personal WeChat (Tencent iLink Bot) and WeCom intelligent robot (long-connection API) with bidirectional chat and turn-completion notifications

0High
0Medium
0Low

weniatall

deepseek-harness dsh wechat wecom weixin im bot notification

dsh-im-bot

DeepSeek Harness（DSH）的集成机器人插件：把企业微信智能机器人与个人微信接入 DSH，让微信成为会话的另一个入口与出口。

📥 微信 → DSH：在微信里发消息，直接驱动绑定的 DSH 会话；
📤 DSH → 微信：会话跑完自动把结果推回发起对话的那个聊天；
🔔 任务完成主动通知：不需要你盯着页面，长任务跑完结果自己送到手机上。

一、它能做什么

刻意只推给「发起过对话」的聊天：Web 端新开的会话不会打扰任何人。哪个聊天绑了哪个会话，设置页里一目了然，也能手动解除。

内置命令

在微信里直接发这些命令，不会进入模型上下文（不消耗 token、不污染历史）：

其它任何文本都会作为该会话的下一条消息投递进去。

二、两条通道的技术底座

企业微信 · 智能机器人（长连接 API 模式）

对接企业微信官方的智能机器人长连接：

主动连 wss://openws.work.weixin.qq.com，用 BotID + Secret 发 aibot_subscribe；
收 aibot_msg_callback（文本/图文混排/语音）与 aibot_event_callback；
发用 aibot_send_msg，显式带 chat_type（1 单聊 / 2 群聊）；
每 30 秒 ping 心跳，连续 3 次没回应判定假死重连；
收到 disconnected_event（同一机器人只能一条长连接，新连接会踢旧的）后指数退避重连，不会与另一个实例互踢。

为什么选长连接而不是回调 URL：不需要公网 IP、不需要 HTTPS 证书、不需要自己实现 AES 验签解密。代价是同一机器人同时只能有一条连接——所以如果你在别处也连了同一个 BotID，两边会互踢，表现为「刚连上又断」。

个人微信 · 腾讯 iLink Bot

对接腾讯 iLink Bot 的官方 HTTP 接口（与 iLink 官方 App 同一套协议）：

扫码登录取 ilink_bot_id + bot_token；
ilink/bot/getupdates 长轮询收消息，get_updates_buf 游标持久化到 ~/.dsh/im-bot/，重启不重复消费、不丢消息；
ilink/bot/sendmessage 发消息，必须回带该 peer 最近的 context_token；过期（errcode -14）时自动去掉 token 重试一次——这是通知能发出去的关键；
ilink/bot/sendtyping 显示「正在输入」，typing_ticket 缓存 600 秒。

不读取 ~/.hermes 下的任何文件。 如果你同时用 hermes 跑同一个 bot 账号，两边各自持游标会互相抢消息。本插件独立扫码、独立存储，互不干扰。

三、安装

# 从 npm 安装
dsh plugin --profile web add @weniatall/dsh-im-bot

# 或从本仓库本地打包安装
cd plugins/dsh-im-bot && npm pack
dsh plugin --profile web add ./weniatall-dsh-im-bot-0.1.14.tgz

重启生效

@deepseek-ai/dsh CLI 没有 service 子命令，用仓库自带脚本：

macOS / Linux：./scripts/dsh-web.sh restart
Windows：.\scripts\dsh-web.ps1 restart（或 scripts\dsh-web.cmd restart）

安装后插件默认完全关闭，不会建立任何连接。打开 设置 → 集成机器人 才启用。

四、配置

4.1 企业微信

企业微信管理后台 → 智能机器人 → 创建/进入机器人；
开启 API 模式，选择 长连接；
记下 BotID 与 Secret（长连接专用，与回调模式的 Token/EncodingAESKey 不同）；
在 DSH 设置页填入 BotID 与 Secret，勾选「启用企业微信通道」，保存。

状态标签变成「在线」即连接成功。

4.2 个人微信

DSH 设置页 →「个人微信 · 扫码登录」→ 点 扫码登录；
用微信扫码并在手机上确认；
登录成功后账号 ID、Token 自动写入，通道自动启用。

4.3 白名单（重要）

白名单为空时，任何人都不能使用机器人（安全默认）。否则任何知道机器人账号的人发条消息就能消耗你的模型额度。

单聊：填对方的 userid，每行一个；
群聊：勾选「允许群聊」，再填允许的群 ID（chatid）。群聊默认关闭。

企业微信里机器人创建者是超级管理员时，from.userid 是明文 userid；否则是加密 userid （需要通过「自建应用与智能机器人的对接」转换）。用你在回调里实际看到的那个值。

4.4 外部推送令牌（可选）

设置后即可让脚本/CI 主动推消息：

curl -X POST http://127.0.0.1:3080/dsh-im-bot/send \
  -H 'content-type: application/json' \
  -H 'x-dsh-im-bot-token: <你设置的令牌>' \
  -d '{"sessionId":"<会话ID>","text":"构建完成 ✅","format":"text"}'

sessionId 会查绑定表找到对应聊天；也可直接给 channel + peer。
不配置令牌时该路由视同不存在（返回 404，不暴露存在性）。
令牌用恒定时间比较，避免通过响应时间猜测。

4.5 给模型用的工具

插件注册了原生工具 im_bot_send，模型可以自己决定在任务中途把进度或结果推给你：

im_bot_send(text="部署已完成，版本 v1.2.3", sessionId="<当前会话>")

五、工作原理

微信/企微 ──入站──▶ Channel(ilink|wecom)
                        │ 归一化 + 去重 + 白名单
                        ▼
                  命令？──是──▶ 本地执行并回发（不进模型）
                        │否
                        ▼
              agent.followup(createUserMessage)  ──▶ DSH 会话
                        │
                        │  （记录「本会话由哪个聊天发起」）
                        ▼
                   模型跑一轮
                        │
              session/event: turn/end
                        │  reason.kind
             ┌──────────┴──────────┐
       completed               error/aborted/max-tokens
             │                        │
        推送结果摘要              推送失败告警
             └──────────┬─────────────┘
                        ▼
                 回推原聊天（同一通道，断线则降级到另一通道）

为什么监听 session/event 而不是 agent/status：只有 turn/end 带 reason，能区分「正常完成」与「报错/被中止/超出 token」，这是「失败也要告警」的前提。 agent/status 只知道 idle / running。

六、可靠性设计

状态文件（~/.dsh/im-bot/，权限 0600）：

凭据（Bot Secret、iLink Token、HTTP 令牌）不进配置文件，统一存于 DSH 凭据存储（ctx.credentials），设置页只显示「已配置 / 未配置」。

七、排障

设置页显示「已保存」但通道一直「未启用」

检查总开关。通道启用开关与总开关是两个开关，总开关关闭时任何通道都不会连接。

企业微信「刚连上又断了」

同一个 BotID 在别处还有一条长连接。企微规定一个机器人同时只能有一条长连接，新连接会踢掉旧的。关掉另一处（比如另一个 DSH profile、或你在别的地方跑的脚本）。

微信发消息没反应

按顺序检查：

/status 看通道是否「在线」；
白名单是否包含你的 userid（留空 = 拒绝所有人）；
群聊是否同时勾了「允许群聊」并填了群 ID；
宿主日志里搜 im-bot:，拒绝原因会写成 拒绝 <channel>/<peer>（<reason>）。

会话有回复但微信没收到

/status 看绑定是否还在；
/notify 是否被关成了 off；
企业微信主动推送要求「用户先给机器人发过消息」——绑定本身就是由入站建立的，正常情况下满足；若账号被重置则需重新发一条消息；
iLink 通知需要 context_token，过期会自动降级重试；若仍失败，在微信里给机器人随便发条消息刷新会话。

桌面版 / headless profile 下没有双向

双向对话依赖 ctx.sessionController（由 dsh-web-app 提供）。desktop 与 headless 组合里没有它，此时设置页会提示「当前 Profile 不支持双向对话」，通道仍可出站推送。

想看当前配置与诊断

设置页底部「重新读取」会刷新状态；也可以在浏览器控制台调 ctx.connection.rpc.call('/dsh-im-bot', 'diagnostics', {}) 拿到完整诊断。

八、开发与测试

cd plugins/dsh-im-bot
npm test

测试包含四套，全部零网络、零宿主、零依赖：

另含两道宿主闸门：

node ../../scripts/check-host-settings.mjs plugins/dsh-im-bot im-bot   # 设置写入闸门
node ../../scripts/verify-pack-contents.mjs --plugin dsh-im-bot        # 发布内容闸门

配置形状的一个硬约束

schemastery 明确拒绝「volatile 字段嵌在另一个 volatile 对象里」：

volatile fields require a fixed object path without an enclosing volatile field

因此 Config 里所有可改字段都是扁平的（wecomBotId、ilinkBaseUrl、 notifyOnTurnComplete…），由 flatToNested() / nestedToFlat() 在扁平配置与 core 层使用的嵌套结构之间转换。改配置字段时三处要同步： Config、CONFIG_KEYS、这两个转换函数。

九、边界与已知限制

本期只做文本。图片/语音/文件/视频已在协议层留好位置，但未接入媒体链路（iLink 的媒体要走 AES-128-ECB CDN 协议）。收到媒体消息会回一句「当前仅支持文本消息」。
企业微信不支持流式刷新。回复是完整发一次；企微的 stream.id 流式回复留待后续。
企业微信回调 URL 模式未实现。它需要公网 HTTPS，与长连接二选一。
群机器人 webhook 未实现。它是单向的，不满足双向通信需求。
需要 Node ≥ 22：依赖全局 WebSocket（企微长连接）。Node 20 需要额外引入 ws 依赖。
不内嵌任何个人微信 hook。个人微信走腾讯官方 iLink Bot 接口，不是逆向 hook；但账号使用风险（被限制登录等）由使用者自行承担。
合规提示：请在企业微信管理员授权的范围内使用；不要把机器人用于群发营销或自动化骚扰。插件不做任何风控规避。

十、License

MIT