dsh-plugin-wecom-bot

DeepSeek Harness（DSH）插件：通过企业微信「智能机器人」长连接收发消息， 把发给机器人的文本当作任务下发给 DSH agent 执行，并把结果回传到企业微信。

• 零公网依赖：长连接模式由插件主动连出到企业微信网关（WebSocket）， 不需要公网 URL、不需要消息加解密、不需要可信 IP 白名单。
• 仅一个运行时依赖（ws）：Node 内置 WebSocket 不带 ALPN 扩展， 会被企业微信网关 400 拒绝（详见「常见问题」），因此使用 ws 库。
• 支持私聊与群聊 @机器人，多轮上下文（per-user 会话）或一次性任务（per-message）。

工作原理

企业微信成员 ──私聊/群聊──▶ 智能机器人 ──wss://openws.work.weixin.qq.com──▶ 本插件
                                                                             │
         ◀── aibot_respond_msg（stream 流式回复）◀── agent 任务结果 ─────────┤
                                                                             ▼
                                                              DSH agents.create → followup
                                                              → whenIdle → 汇总文本

协议实现基于官方文档 《智能机器人长连接》， 并与 cc-connect、 CowAgent 两个开源实现交叉验证。

一、企业微信后台：创建智能机器人

1. 登录 企业微信管理后台。

2. 进入 应用管理 → 智能机器人 → 创建智能机器人。

3. 填写名称、头像等信息，创建完成后记录两个凭证：

   BotID:  xxxxxxxxxxxxxxxx
   Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   

   ⚠️ Secret 只显示一次，请立即保存。

4. 把机器人添加到会话：创建后在企业微信 App 里搜索该机器人，即可直接私聊； 也可以把它拉进群聊，群成员 @机器人 发任务。

二、安装插件

在插件源码目录（本目录）执行：

# 1. 先装插件自身的依赖（link: 安装方式要求插件自带 node_modules）
pnpm install

# 2. 装进 web profile
dsh plugin --profile web add .

这会用 pnpm 把插件装进 ~/.dsh/profiles/web，并把 dsh-plugin-wecom-bot 追加到该 profile 的 dsh.profile.bundles（bundle 层）。重启 dsh web 生效。

本机没有 pnpm 时可用 corepack 启用，或在工作区内安装： npm install --prefix .tools/pnpm pnpm --cache .npm-cache， 然后把 .tools/pnpm/node_modules/.bin 加入 PATH。

三、配置凭证

两种方式任选其一：

方式 A：环境变量（默认，推荐）

export WECOM_BOT_ID="wwxxxxxxxxxxxxxx"
export WECOM_BOT_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
dsh web

方式 B：profile patch 覆盖（~/.dsh/profiles/web/cordis.patch.yml）：

- id: wecom-bot
  config:
    botId: wwxxxxxxxxxxxxxx
    botSecret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

patch 覆盖的是整行 config，覆盖时如需保留其他选项要一并写全 （完整选项见下表）。

未配置时插件保持空闲、仅打印提示，不影响 dsh web 启动。

四、启动验证

dsh web

日志里应出现：

wecom-bot: connecting
wecom-bot: subscribed
wecom-bot: connected

然后在企业微信里私聊机器人发一条消息，例如：

帮我总结一下这个目录下 README.md 的主要内容

机器人先回复「✅ 已收到任务，agent 处理中…」，agent 跑完后回传最终结果。

五、bot 工作区命令

企业微信里给机器人发以下命令可以查看/切换工作区（决定 agent 在哪个 目录干活；每个企业微信成员独立记住自己的目录，多轮会话有效）：

示例：

查看工作区
#ws productv4-web
切换工作区 /Users/zhaohanghang/work/java/bp_product_web
#cwd /Users/zhaohanghang/work/java/plug

说明：

• 切换命令会持久化销毁旧目录的 agent 会话，下一条任务用新目录重建 agent（旧会话结果已 flush 保存）。
• 路径不存在/不是目录会返回错误提示；按标题匹配到多个工作区时需用完整路径。
• 需要 sessionMode: per-user（默认值）才支持切换；per-message 模式下 每条消息都新建 agent，切换不持久。

会话管理（多会话）

per-user 模式下每个企业微信成员默认有一个 default 会话（多轮上下文 + 独立工作目录）。你可以创建/切换多个命名会话，把不同上下文分开管理：

示例：

会话列表
#new chat-v2
#use default
当前会话

说明：

• 会话按成员隔离：每个成员看到并管理自己的会话列表。
• 每个会话有独立的工作目录与 agent 多轮记忆；切换工作区 作用于当前活跃会话。
• 普通任务自动路由到当前活跃会话执行；首次发任务会自动创建 default 会话。
• 「会话列表」会展示每个会话的最近一次结果（截断）与任务次数。
• 会话仅在 sessionMode: per-user 下持久存在；per-message 模式无持久会话，相关命令会给出提示。

六、权限审批（企业微信内完成）

agent 执行需要权限提升的操作（如沙箱升级、写敏感区域）时，DSH 会发起 审批。本插件把审批请求转发到企业微信，你在聊天里直接回复即可，无需 打开网页：

🔐 需要审批 #1
会话：default
工具：execute_command
原因：命令需要提升权限以完成操作

回复「同意 #1」批准，或「拒绝 #1」拒绝
（也可直接回复 同意 / 拒绝，匹配你最近一条审批）

• 审批推送对象：发起任务的成员（私聊直接回，群聊里只有发起者回复才有效）。
• 回复支持：同意 / 批准 / 允许 / 是 / ok / y（批准）， 拒绝 / 不同意 / 否 / no / n（拒绝）；可带编号 #1 精确定位多条审批。
• 回复了不存在的编号（或审批已取消/超时）会提示「没有匹配的待审批项」， 不会被误当成任务。
• ⚠️ 审批挂起期间，该成员的新任务和切换工作区都会排队等待（同一成员 的 agent 是串行的）——长时间不回复会阻塞后续操作，建议设置 approvalTimeoutMs 让审批自动超时（超时按拒绝处理）。
• 任何会话的审批都会转发到企业微信（默认 forwardAllApprovalsToWecom: true）： bot 驱动的话精确推给发起任务的成员；非 bot 会话（如 Web GUI）则会回退推给 最近活跃的成员，在聊天里通过后 agent 继续执行，等同于在会话界面里点「同意」。 若希望仅转发 bot 自身创建的 agent、把其余留给网页审批，可将 forwardAllApprovalsToWecom 设为 false。该开关可在 Web 「设置 → 插件配置」的 wecom-bot 卡片里直接勾选（插件向宿主注册了 wecom-bot 设置命名空间，无需改动 profile 的 patch），也可在 cordis.patch.yml 中配置同名选项。

七、配置项

八、开发与测试

npm test        # node --test，跑协议/客户端/命令层单测

代码结构：

lib/wecom.js     # 协议纯函数：帧构建/解析、消息提取、@提及剥离、字节分块、事件汇总
lib/client.js    # 长连接客户端：订阅/心跳/重连/应答，socket 工厂可注入
lib/commands.js  # 工作区/会话命令层：命令解析、目标目录解析、工作区与会话列表格式化（纯函数可单测）
lib/index.js     # Cordis 插件：配置 schema、agent 任务调度、消息流、工作区/会话命令集成、wecom-bot 设置命名空间
lib/web/client.js # 浏览器半侧：在 Web 设置「插件配置」注册 wecom-bot 卡片（「是否需要转移审批」开关）
test/            # node:test 单测（FakeSocket 回放协议帧 + 命令解析用例）

九、已知限制

• 必须带 ALPN 握手（已处理）：企业微信长连接网关要求 TLS ClientHello 携带 ALPN http/1.1，Node 内置 WebSocket（undici）与 http.request 默认 都不带，握手会被网关以 400 拒绝。本插件用 ws 库 + 显式 ALPN 的 https.Agent 建连解决；若改用其他客户端，请注意同样的问题。
• 同一机器人同时只允许一个长连接：另一处连上时本连接会收到 disconnected_event 并被网关断开。
• 消息频率受企业微信限制（约 30 条/分钟）。
• 语音消息按转写文本处理；图片/文件消息暂不处理（会被忽略）。
• 最终回复超过 maxReplyChars 会被截断。