NattoCB/dsh-plugin-wechat-bridge ↗★ 2
dsh-plugin-wechat-bridge
DSH bundle plugin: bridge WeChat (ilink bot) messages into a DSH agent session, with runtime enable/disable hot-plug and a Settings UI tab. 适合需要通过微信远程驱动智能体并接收结束通知的用户。
Install
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:NattoCB/dsh-plugin-wechat-bridgeREADME
Read the full README ↗Configuration
配置项
| 键 | 默认值 | 含义 |
|---|---|---|
enabled | false | 设置项缺失时的开机自启开关;每次变更实时重新应用 |
mediaEnabled | true | 接收入站媒体(下载 / 解密 / 落盘) |
defaultProvider | '' | 桥接会话的 provider 覆盖(空 = 跟随全局默认;Settings UI 可编辑)。每条微信消息都会重新强制此选择——在会话里手动切换模型不影响微信回复 |
defaultModel | '' | 桥接会话的 model 覆盖(空 = 跟随全局默认;Settings UI 可编辑) |
allowedPeers | '' | 入站白名单:允许驱动 agent 的机器人内部联系人 ID(非微信号/昵称),逗号分隔;留空 = 拒绝所有人(fail-closed);Settings 页签可编辑 |
notifyEnabled | true | 单向会话通知开关:任何顶层 DSH 会话的 turn 结束时向白名单微信推送固定模板简讯;Settings 页签可开关 |
dataDir | ~/.dsh/wechat-bridge | state.json(账号 / 令牌 / 偏移)所在目录 |
defaultCwd | '' | 新会话的工作目录(否则 ~/.dsh/wechat-bridge/WeChatSpace) |
enabled、mediaEnabled、defaultProvider、defaultModel、allowedPeers、notifyEnabled 同时以 wechat-bridge: 段存在于 ~/.dsh/settings.yaml,编辑保存即热生效:
wechat-bridge:
enabled: true # 实时开关;每次变更服务都会重新应用
mediaEnabled: true
defaultProvider: '' # 桥接会话 provider(空 = 跟随全局默认)
defaultModel: '' # 桥接会话 model(空 = 跟随全局默认)
allowedPeers: 'NhatoCola_F, abCdEf_12345' # 入站白名单(机器人内部 ID),逗号分隔
notifyEnabled: true # 单向会话通知(见下节)
故障排查:errcode -14「session timeout」
ilink 的业务错误放在 HTTP 200 响应体里({"errcode":-14,"errmsg":"session timeout"}),插件现在会把它们当真实错误透出:
- 轮询侧:getupdates 返回 -14 表示 bot 会话在服务端过期——轮询暂停 60 分钟并在 Settings 状态卡显示红字警告。恢复方式:重新扫码绑定(成功后自动恢复,无需重启)。
- 通知/回复侧:context_token 过期时主动推送会被服务端拒绝。失败的通知会进入暂存队列(≤20 条、24 小时),下次该 peer 的入站消息刷新 token 后自动合并补发;「发送测试」(
POST /wechat-bridge/notify-test)可随时手动验证并顺带冲刷队列。GET /wechat-bridge/status暴露lastNotify、notifyBacklog(待补发条数)、peerTokenAgeHours(token 新鲜度)与每个账号的health。服务端拒绝发送有两种 HTTP200 错误形态(errcode与ret),两者都会作为真实错误抛出并进入补发队列。注意:单向通知不依赖当日微信会话是否存在——会话只在入站消息时懒创建;真正的门是 context_token 新鲜度。
入站白名单(fail-closed)
allowedPeers 是默认拒绝的入站闸门:只有列表内的 ID 能驱动 agent 会话。
- 留空 = 拒绝所有人(安全默认,而非放行所有人)。
- 这里的 ID 不是微信号,也不是昵称,而是微信机器人协议的内部联系人 ID(一串奇怪的字符,如
NhatoCola_F),无法从微信资料里查到。 - 获取方式:用对方微信给机器人发一条消息——即使未入白名单,机器人也会自动回复该 ID;同时该 ID 会出现在 Settings 页签「入站白名单」卡的「已对话过的 ID」chip 列表里,点一下即可填入输入框。
- Settings 页签「入站白名单」卡可直接编辑(逗号分隔,中英文逗号均可,保存时自动规范化)并持久化到
settings.yaml;/wechat-bridge/configAPI 同样接受allowedPeers字段。 - 配置热生效,无需重启。
单向会话通知(notifyEnabled,默认开启)
开启时,DSH 内任何顶层会话(GUI 会话、automation 会话……)的每个 turn 结束,都会向 allowedPeers 白名单微信推送一条固定模板简讯——纯模板拼接,不经过任何 LLM 总结:
【会话通知:(会话 id 特征段,如 abcdef)】
- 严格单向、互不污染:通知只经微信 API 直发,不写入任何会话、不注入任何 agent——每日桥接会话完全看不到这些通知;你在微信里回信仍照常进入当天会话。桥接自身的
wechat-*会话整体跳过(回复本来就直接发给对方,避免重复推送与「通知 → 回信 → 再通知」循环)。 - 过滤规则:子代理子会话(
origin=subagent或delegationDepth>0)不推;崩溃日志重载时补写的interrupted回合关闭事件不推;回合无文本输出时按结束原因给固定占位(如⚠️ 回合失败: ...)。 - 送达条件:微信 ilink 协议要求
context_token(来自对方最近一条入站消息),所以只推送给至少发过一次消息的白名单联系人;没聊过的联系人无法主动推送(协议限制)。桥接服务处于启用状态且notifyEnabled=true时才会推送。 /wechat status会显示当前 notify 开关;HTTP 状态 API(/wechat-bridge/status)含notifyEnabled字段。
运行时启停(热插拔)
- Settings UI 页签:状态卡(运行状态 + 启用/停用按钮,点击立即生效;账号轮询会话过期时显示红字警告并指引重新扫码)、会话通知卡(单向通知开关 + 「发送测试」按钮 + context_token 过期提示)、入站白名单卡(直接编辑 + 已对话过的 ID chips + 获取 ID 提示)、默认模型卡(两个下拉框选择 provider/model,选项来自 DSH 已注册模型;卡片提示「每条消息都强制此模型,会话内切换不生效」)、账号卡(账号 id、token 状态、最近登录时间 + 移除)、扫码绑定。
- 斜杠命令(任意 DSH 会话):
/wechat status— 运行中?账号数?通知开关?/wechat enable— 立即启动轮询循环(同时写入settings.wechat-bridge.enabled=true)/wechat disable— 立即停止轮询循环(写入settings.wechat-bridge.enabled=false)/wechat accounts— 列出已配置账号/wechat qrlogin— 发起二维码登录;返回sessionId/wechat qrstatus— 轮询扫码状态;confirmed时保存账号并启用/wechat rm— 移除账号
- 设置项(热重载):编辑
~/.dsh/settings.yaml的wechat-bridge.enabled,保存即重新读取并启停轮询循环。
UI 页签调用插件自带的 HTTP API(/wechat-bridge/*),由宿主 webserver 提供——不依赖任何外部服务。
会话模型
- 会话 id:
wechat--(本机时区,如2026-08-15);当天首条入站消息时惰性创建,零点从不预创建。 - 标题:``,以
user标题源钉住,自动标题生成不会覆盖它。 - 默认 cwd:
~/.dsh/wechat-bridge/WeChatSpace(启动时创建,可用defaultCwd覆盖)。 - 联系人身份保持
weixin::::编码(协议层,与 CodePilot 同源);只有插件自身的命名使用wechat-*。
文件结构
src/index.js WechatBridgeService:轮询循环、agent 驱动、按天会话、热插拔、单向会话通知、/wechat 命令、/wechat-bridge/* HTTP API(服务端渲染二维码)
client/client.js 客户端 bundle:注册 Settings「微信桥接」section 槽位(React)
src/weixin-api.js ilink bot 协议客户端(getupdates/sendmessage/sendtyping/getconfig/qrlogin)
src/weixin-media.js 入站媒体 CDN 下载 + AES 解密、出站媒体 CDN 上传
src/weixin-ids.js synthetic chatId 编解码(weixin::::
)
src/weixin-types.js 协议枚举/常量
src/notify.js 单向会话通知纯函数(模板渲染、回合文本抽取、会话名/子会话过滤;可单测)
src/store.js JSON 文件持久化(账号、context_tokens、偏移;旧目录迁移)
cordis.patch.yml bundle patch(注册 wechat-bridge 服务)
package.json 声明 dsh.bundle + dsh.client(web)
node_modules/ vendored qrcode/pngjs/dijkstrajs(二维码 data-URL 渲染,无需 pnpm)
说明与范围
- 出站媒体通过
wechat_send_file工具由 agent 主动触发;语音入站仅落盘,不做转写。 - 仅私聊,无群聊语义。
- 需要具备
ilink bot权限(bot_type=3)的微信账号。 - 持久化是单个原子 JSON 文件(
state.json)——对单个 DSH 进程足够。 - 按聊天队列在单进程内串行;跨进程轮询锁与消息去重覆盖多进程场景(仍建议保持端口单属主)。
MIT License · GitHub 仓库 · 提 issue
配置项
| 键 | 默认值 | 含义 |
|---|---|---|
enabled | false | 设置项缺失时的开机自启开关;每次变更实时重新应用 |
mediaEnabled | true | 接收入站媒体(下载 / 解密 / 落盘) |
defaultProvider | '' | 桥接会话的 provider 覆盖(空 = 跟随全局默认;Settings UI 可编辑)。每条微信消息都会重新强制此选择——在会话里手动切换模型不影响微信回复 |
defaultModel | '' | 桥接会话的 model 覆盖(空 = 跟随全局默认;Settings UI 可编辑) |
allowedPeers | '' | 入站白名单:允许驱动 agent 的机器人内部联系人 ID(非微信号/昵称),逗号分隔;留空 = 拒绝所有人(fail-closed);Settings 页签可编辑 |
notifyEnabled | true | 单向会话通知开关:任何顶层 DSH 会话的 turn 结束时向白名单微信推送固定模板简讯;Settings 页签可开关 |
dataDir | ~/.dsh/wechat-bridge | state.json(账号 / 令牌 / 偏移)所在目录 |
defaultCwd | '' | 新会话的工作目录(否则 ~/.dsh/wechat-bridge/WeChatSpace) |
enabled、mediaEnabled、defaultProvider、defaultModel、allowedPeers、notifyEnabled 同时以 wechat-bridge: 段存在于 ~/.dsh/settings.yaml,编辑保存即热生效:
wechat-bridge:
enabled: true # 实时开关;每次变更服务都会重新应用
mediaEnabled: true
defaultProvider: '' # 桥接会话 provider(空 = 跟随全局默认)
defaultModel: '' # 桥接会话 model(空 = 跟随全局默认)
allowedPeers: 'NhatoCola_F, abCdEf_12345' # 入站白名单(机器人内部 ID),逗号分隔
notifyEnabled: true # 单向会话通知(见下节)