dsh-wecom

DeepSeek Harness（dsh）企业微信智能机器人插件。通过企微"智能机器人"API 模式下的长连接（WebSocket）接入，将 WeCom 消息对接到 DSH Agent。

功能

模块	里程碑	状态
长连接	M1：WebSocket 订阅 + 心跳 + 指数退避重连	已实现
文本闭环	M2：文本消息 → Agent → markdown / stream 回复	已实现
幂等去重	M3：msgid LRU 去重 + 会话串行队列	已实现
多媒体	M4：图片/文件/语音下载到沙箱 + 临时素材上传	已实现
事件	M5：进入会话欢迎语 + 点赞/点踩审计日志	已实现
配置面板	M6：浏览器端「⚙ 企微」面板，connection.fetch 精确路由读写设置	已实现

回复模式

• markdown：过程中不刷新，Agent 回合结束后一次性给出最终内容。
• stream：逐 token 推送到企微流式打字机（内置 500ms 推送节流）。

⚠ 两种模式都先发一帧流式占位（"思考中…"）：企微要求「收到消息回调后 5 秒内回复」， 而 Agent 首个 token 通常远晚于此，不占位则 req_id 超时失效、后续所有帧被丢弃 （用户侧一直停在 "…"）。占位帧与后续刷新共用同一个 stream.id，最终被 finish=true 的全量内容原位替换，聊天记录里只留一条消息。 从首帧起 10 分钟内必须 finish=true，插件在 5 分钟时主动收尾。

安装

# 确保在 dsh host 的工作目录中
# 将插件目录链接进目标 profile
npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-plugin-wecom

安装后重启 host（修改源码后同样需要重启 host 才能生效）。

快速启动（控制台配置）

安装后，打开 DSH 控制台 → 插件 → wecom → 配置：

1. botId：企微智能机器人 Bot ID（API 模式 → 长连接页面获取）。
2. secret：Bot Secret（仅创建时显示一次，role('secret') 脱敏存储）。
3. preset：Agent 使用的 DSH preset 名称（默认 standard）。
4. replyMode：markdown 或 stream（默认 stream）。

另外，浏览器端会挂一个「⚙ 企微」入口（侧边栏 footer，缺失时回退为浮动按钮）， 可在页面内直接读写上述配置，无需重启 host。

配置面板的 RPC 通道（harness 0.1.5+）

宿主端通过 connection.fetch.register() 注册两条 exact 路由：

路径	方法	作用
/api/wecom-rpc/get	POST	读取当前配置（secret 回传 *** 占位）
/api/wecom-rpc/update	POST	写入配置补丁（patch 语义，未提供的字段保持原值）

⚠ 不要用 connection.rpc.handle()：0.1.5 起它在内部访问 owner.webServer， 而 connection 插件的 fiber 不再 inject webServer，cordis 4 会抛 cannot get property "webServer" without inject；错误被 connection 吞掉， host 无日志，浏览器只表现为 transport failure ... HTTP 405。

配置字段

字段	类型	默认	说明
botId	string	—	企微机器人 Bot ID（必填）
secret	string	—	Bot Secret（必填，role('secret') 脱敏）
preset	string	'standard'	DSH preset 名称
replyMode	`'markdown'	'stream'`	'stream'
sessionTtlMs	number	1800000	会话空闲超时（毫秒，最小值 60000）
welcomeText	string	—	进入会话欢迎语（markdown），留空使用默认文案

验证清单

M1：长连接跑通

• 日志依次出现 connecting to wss://... → ws opened, sending aibot_subscribe → subscribed ok
• 私聊机器人发"你好"，日志出现 message 事件
• 断网 10 秒恢复：日志 heartbeat timeout, force reconnect → 重连 → subscribed ok
• 起第二个实例：第一个实例收到 close 并警告（互踢验证）

M2：最小闭环

• 文本消息 → Agent → markdown 回复正常
• stream 模式打字机效果正常，finish 帧正确结束
• 群聊消息 @机器人 前缀被正确去除

M3：幂等 + 串行

• 断网重连后同一条消息重推：只处理一次，不重复回复
• 快速连发 3 条消息：回复顺序严格 = 发送顺序，无交叉
• 不同会话（两个人）并发发消息：互不阻塞

M4：多媒体

• 发送图片：沙箱目录出现 .png 文件，Agent 收到路径
• 发送文件/语音：同上，扩展名正确
• Agent 工具产出文件：用户收到文件消息，文件名正确
• 媒体下载失败：用户收到友好错误提示

M5：事件

• 首次打开机器人对话：自动收到欢迎语（自定义 welcomeText 生效）
• 点击消息 👍/👎：日志打印 feedback event

架构

企微长连接（wss） ←→ WsClient（ws.ts）
                         ↓ message / event
                   SessionBridge（bridge.ts）
                    ↙         ↓         ↘
              LRU 去重    会话队列     Agent 桥接
              (lru.ts)   (queue.ts)   (ctx.agents)
                                        ↓
                          DSH Agent（事件驱动回复）
                                        ↓
                    assistant/chunk → 流式推送
                    assistant/message → markdown 回复

• WsClient：企微长连接协议实现（订阅/心跳/重连/回复方法），与 DSH 解耦。
• SessionBridge：消息分发、白名单校验、幂等去重、会话串行队列、Agent 调用协调。
• MediaHandler：沙箱内媒体文件下载/上传（使用 Node 原生 fetch + FormData）。
• Agent 桥接：每个企微会话对应一个 DSH agent session，followup 发消息 → 事件总线监听 assistant/chunk（流式）或 assistant/message（完整）。

常见问题

处理失败：session "wecom:single:xxx" already exists

session store 的 id 在同一进程内唯一，sessions.prepare() 撞上同名会话就会抛错。常见诱因是 上一轮 bridge 的 agent 还没释放完（AgentHandle.dispose() 是异步的）就建了新 bridge （配置热更新 / 插件重载），或进程内已存在该会话的 agent。

插件按以下顺序自愈，不会再把这个错误抛给用户：

1. 本 bridge 已缓存 → 直接复用；
2. ctx.agents.get(sid) 有存活 agent → 借用（不重复 create，也不在释放时销毁它）；
3. create 报冲突 → 再借一次（并发刚落地）；
4. 仍冲突 → 同 id 重试一次（瞬时竞争，事务回滚后 store 已空）；
5. 仍失败 → 用 原id#时间戳 开新会话并告警（SessionStore 没有公开删除接口，残留会话只能绕开）；
6. 服务重启走串行 promise 链，先 await 旧 bridge 的 dispose() 再建新实例。

企微侧一直是 "…" 没有回复

先看 Web 控制台（:3080）里该会话有没有产出——有产出说明 Agent 正常，问题在回复时序： 企微要求收到回调后 5 秒内回一帧，本插件在 process() 一开始就发流式占位帧来满足它， 所有出口（成功 / 失败 / 超时）统一用 finish=true 收尾。 若仍无回复，查 host 日志里的 raw frame: 行——企微对失效/错误帧会回带 errcode。

日志关键词：

• adopt live agent for ... —— 走了借用分支；
• create session ... 冲突（...）；诊断: agent=... session=... sessions服务=... 存活会话=N —— 走了自愈分支，括号里是定位信息；
• ... 仍冲突（...），改用新会话 ... —— 最终兜底，会话上下文会重置。

License

Apache License 2.0