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 两个开源实现交叉验证。
一、企业微信后台：创建智能机器人
-
登录 企业微信管理后台。
-
进入 应用管理 → 智能机器人 → 创建智能机器人。
-
填写名称、头像等信息，创建完成后记录两个凭证：
BotID: xxxxxxxxxxxxxxxx
Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
⚠️ Secret 只显示一次，请立即保存。
-
把机器人添加到会话：创建后在企业微信 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 / #工作区 | 列出全部已注册工作区 + 当前目录 |
切换工作区 <名称或路径> / #ws <名称或路径> | 切换到指定工作区（按标题或绝对/相对路径），下一条消息在新目录执行 |
#cwd / 查看目录 | 显示当前工作目录 |
#cwd <路径> | 直接设置工作目录 |
示例：
查看工作区
#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 会话（多轮上下文 +
独立工作目录）。你可以创建/切换多个命名会话，把不同上下文分开管理：
| 命令 | 作用 |
|---|
会话列表 / #sessions | 列出当前成员的全部会话（含目录、状态、任务次数、最近结果），▶ 标记当前活跃会话 |
当前会话 / #session | 查看当前活跃会话的详细信息（含完整最近结果） |
查看会话 <名称> / #session <名称> | 查看指定会话的详细信息 |
切换会话 <名称> / #use <名称> | 切换到指定会话，后续消息在该会话上下文执行 |
新建会话 <名称> / #new <名称> | 新建会话并切换过去（新会话从配置工作目录开始） |
删除会话 <名称> / #rm <名称> | 删除指定会话（删除活跃会话时自动回落到剩余会话） |
示例：
会话列表
#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 中配置同名选项。
七、配置项
| 配置键 | 默认值 | 说明 |
|---|
botId | 环境变量 WECOM_BOT_ID | 智能机器人 BotID |
botSecret | 环境变量 WECOM_BOT_SECRET | 智能机器人 Secret |
wsEndpoint | wss://openws.work.weixin.qq.com | 长连接网关 |
heartbeatIntervalMs | 30000 | 心跳间隔（毫秒） |
reconnectBaseDelayMs | 1000 | 重连初始退避（毫秒） |
reconnectMaxDelayMs | 30000 | 重连最大退避（毫秒） |
sessionMode | per-user | per-user 每个成员一个 agent 会话（多轮上下文）；per-message 每条消息新建 agent |
cwd | 进程 cwd | agent 的工作目录 |
provider / model | 默认模型选择 | 覆盖 agent 使用的模型（留空用 agentDefaultModel） |
reasoningEffort | 默认 | 推理档位（如 high/medium/low） |
agentPreset | 部署默认（standard） | agent 装配预设：决定工具/提示。留空用部署默认（web profile 为 standard，含 bash/fs 等完整工具）；可选 code / minimal。缺失 preset 时 agent 无工具，任务会"假执行"（模型输出伪工具调用文本） |
ignoreOlderThanSec | 300 | 忽略超过该秒数的历史消息（重连补发防抖） |
maxReplyChars | 6000 | 最终回复最大字符数，超出截断 |
ackOnReceive | true | 先推一条「已收到」中间态 |
stripGroupMentions | true | 群聊消息去掉 @机器人 提及前缀 |
approvalTimeoutMs | 0 | 审批超时（毫秒），0=不超时（agent 保持挂起等回复）；超时按拒绝处理 |
forwardAllApprovalsToWecom | true |
八、开发与测试
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 会被截断。
