dsh-wechat-bridge

dsh-wechat-bridge —— 把 DSH 接到你的微信（含「龙虾」直连版）

把本机 DSH（DeepSeek Harness） 变成你微信里的一只「龙虾」🦞： 微信发消息 → DSH 干活 → 回复回微信。不需要 OpenClaw、不需要公网服务器、不需要网关。

手机微信 ──► 腾讯 iLink 官方通道 (ilinkai.weixin.qq.com) ──► weixin-bot.mjs ──► 本机 DSH
    ▲                                                              │
    └────────────────────────── 回复 ──────────────────────────────┘

Overview

解决什么问题？ 把微信变成 DSH 的移动终端：人在外面用手机微信发一条消息，家里/办公室电脑上的 DSH 就替你查资料、写代码、跑脚本、处理文件，结果直接回微信。任何能跑 dsh web 的机器都能挂上。

适合谁？ 已经会装 DSH 的开发者与重度用户；想要一个「随时在微信里」的私有 AI 助理、又不想搭公网服务器的人。

怎么做？ 直接实现腾讯官方 iLink Bot 协议（微信 ClawBot/「龙虾」的同款官方通道）——扫码配对 → 长轮询收消息 → 调用本机 DSH → 发回微信。官方 OpenClaw 插件本身也只是这套协议的客户端，AI 后端（OpenClaw/DeepSeek/…/DSH）完全自选，腾讯只是"管道"。本仓库 weixin-bot.mjs 即完整实现（协议依据腾讯官方开源 SDK @tencent-weixin/openclaw-weixin，对照版本 2.4.6，详见 RESEARCH.md）。

特性一览：

• 零运行时依赖：只用到 Node 内建模块，无需任何 npm 依赖、无需 daemon、无需 OpenClaw 全家桶；
• 扫码即用：个人微信免申请/免白名单，登录凭证自动续期（到期前提醒 + -14 自动重扫码）；
• 一人一上下文：每个微信联系人有独立的 DSH 对话记忆、工作目录与多个命名会话；
• 双向文件：/send 发电脑文件到微信；微信发来的图片/文件/视频自动下载解密落盘；
• 可审计：聊天记录、DSH 完整运行轨迹、运行日志三层可查。

Compatibility

• 以上组合是本仓库声明支持的验证基线；新版本 DSH 一般向后兼容（本桥接只调用 dsh headless 子命令），但升级 DSH 或官方 SDK 后，请先跑一遍 Quick start 里的「本地闭环测试」再连真实微信。
• 腾讯可能随时变更协议端点或字段；变更造成的失效属协议漂移，升级本仓库到最新版并重新验证即可。
• npm 包名 dsh-wechat-bridge 使用作者自有命名空间（未占用任何第三方 org 或保留命名空间）。

已验证

• ✅ 协议头与官方规范逐项一致（AuthorizationType / X-WECHAT-UIN / iLink-App-Id=bot / ClientVersion=132102 / Bearer）
• ✅ 扫码登录全流程（wait→scaned→confirmed、配对码、二维码刷新、节点跳转分支）
• ✅ 消息环：getupdates 游标持久化 → getconfig → sendtyping → sendmessage（context_token 逐条原样回传）→ 记忆注入
• ✅ 腾讯真实端点冒烟：真实二维码签发、状态轮询正常（probe）
• ✅ 真实 DSH 端到端：mock iLink + 真 headless，agent 回复经微信协议送达
• ✅ 登录续期/失效自动重连逻辑（代码路径，24h 周期需实机观察）
• ✅ 多会话闭环：mock iLink + DSH 回显，/new → 会话内对话 → /switch → /sessions → /clear 全链路 10 项断言通过
• ✅ 消费端安装实测（git 源等价版，2026-08-14）：npm install -g --prefix <dir> github:gtaifu/dsh-wechat-bridge#main → added 1 package、0 运行时依赖；产物为 files 白名单 6 项（lib/、bridge.mjs、weixin-bot.mjs、dsh-weixin.cmd、LICENSE、README.md）+ npm 自动附带的 package.json（npm pack --dry-run 复核：lib/ 展开后共 11 个文件），无 test/、data/、研究笔记
• ✅ 包外 bin 冒烟：dsh-weixin --help 正常；真实 DSH 任务：node bridge.mjs test → 回复「收到」、exit 0
• ⏳ npm 发布后按包名复跑：npm install -g dsh-wechat-bridge → 同款三连（install → bin 冒烟 → bridge.mjs test），作为纯 npm 包名的消费端闭环证据

已知限制

• 媒体消息自动下载解密到 data/media/<hash>/ 并告知路径；语音存为官方原始 .silk 格式（未转码），图片/视频/文件按原格式保存。
• 单条回复超 --reply-max-chars 会截断（完整结果在 DSH 工作目录/终端）。
• 群聊：官方插件当前声明仅 direct chat，群消息不保证。
• 凭证有效期由腾讯服务器决定（社区实测约 24h），到期自动重扫续连（自动提醒 + -14 自动重连，见「工作原理」）。
• 同一时刻只有一条 DSH 任务在跑（不同联系人串行排队）。

Install / Uninstall

安装

方式 A（npm 全局安装，npm 发布后可用）：

npm install -g dsh-wechat-bridge

方式 B（Git 源码安装，当前即可用，零依赖秒装）：

git clone https://github.com/gtaifu/dsh-wechat-bridge.git
cd dsh-wechat-bridge
npm install -g .          # 把 dsh-weixin 命令注册到全局

Windows 下也可以不安装：双击/运行仓库里的 dsh-weixin.cmd，或直接 node weixin-bot.mjs <子命令>。

升级

npm update -g dsh-wechat-bridge                              # 方式 A
cd dsh-wechat-bridge; git pull; npm install -g .             # 方式 B

禁用

• 停止接收消息：在运行 dsh-weixin run 的终端按 Ctrl+C（不再启动即禁用）；
• 清除本机登录凭证：dsh-weixin logout；
• 不删除任何历史数据，随时可重新 login 恢复。

彻底移除

npm uninstall -g dsh-wechat-bridge    # 移除命令（方式 B 同样按包名卸载）
Remove-Item -Recurse -Force .\data    # 删除凭证/记忆/工作目录/媒体（默认 <仓库>/data）

DSH 自身的运行轨迹在 ~/.dsh/sessions/（由 DSH 管理，与本插件独立），如需一并清除请自行处理。

Quick start

环境：Node 18+；DSH 已安装且 dsh web 能跑；零 npm 依赖。

最小配置：连真实微信

dsh-weixin login     # 1) 扫码登录（凭证有效期由腾讯决定，本地自动续连）
dsh-weixin run       # 2) 开始监听（保持终端开着）

1. 登录时终端会打印二维码链接：在手机微信里打开该链接并确认，几秒后配对成功；
2. 微信「我 → 设置 → 插件」中添加「ClawBot/龙虾」插件即可（个人用户免白名单）；
3. 配对成功后，直接在微信里给 Bot 发消息，DSH 就会收到并干活。

常用内置指令：

每个微信联系人（from_user_id）有独立的 DSH 对话记忆与工作目录（data/workspaces/）， 跨轮次的文件操作结果持续保留；记忆按条数/字符双上限滚动裁剪。 想让某个会话的工作目录指向别处（如代码仓库根目录）？见 Configuration 的「指定会话的工作目录」。

每个联系人还可拥有多个命名会话：默认会话 main（chatId = wx:<ID>，与旧版完全兼容）。 /new <名字> 新建并切换、/switch <名字> 切换、/sessions 列出；每个会话有独立的记忆流与工作目录， "当前会话"指针存于 data/sessions-registry/<hash>.json（缺失或损坏时自动回落 main）。

可复现示例：本地闭环（无需真实微信）

# 终端 A：mock iLink 服务器
node test-mock-ilink.mjs --port 8899

# 终端 B：完整流程（DSH 层回显，不消耗模型）
$env:DSH_BRIDGE_MOCK_DSH="1"
node weixin-bot.mjs login --base-url http://127.0.0.1:8899 --data-dir .\test-data
$env:DSH_WXBOT_MAX_MSGS="2"
node weixin-bot.mjs run  --base-url http://127.0.0.1:8899 --data-dir .\test-data

# 检查 mock 捕获的收发记录与协议头
Invoke-RestMethod http://127.0.0.1:8899/__captured
Invoke-RestMethod http://127.0.0.1:8899/__headers

# 对腾讯真实端点冒烟（取真实二维码，不登录）
node weixin-bot.mjs probe

Configuration

所有选项为命令行参数，均有 DSH_WXBOT_* / DSH_BRIDGE_* 环境变量等价项：

环境变量等价项：DSH_WXBOT_BASE_URL、DSH_WXBOT_AUTH_FILE、DSH_WXBOT_ALLOW_FROM、 DSH_WXBOT_REPLY_MAX、DSH_WXBOT_NO_TYPING、DSH_BRIDGE_*（DSH 层）。

指定会话的工作目录与权限（workspace 覆盖）

默认每个会话的 DSH 工作目录是 data/workspaces/<hash>/。想让某个会话直接跑在别的目录 （例如某个代码仓库根目录），在数据目录下放一个 workspace-overrides.json（值可以是 纯字符串路径，也可以带权限的 { dir, permission } 对象）：

{
  "0bf36b275c23e653": {
    "dir": "D:\\path\\to\\your\\workspace",
    "permission": "danger-full-access"
  }
}

• <hash> 即该会话默认工作目录名（safeKey(chatId) 前 16 位，可用 node weixin-bot.mjs chats 的「键」列查看，或直接看 data/workspaces/ 下的目录名）；
• permission 可选：read-only / workspace-write / danger-full-access。不设则跟随 DSH 全局设置；danger-full-access（即 full access）表示不限制文件读写、不弹审批。 桥接会以 DSH_PERMISSION_MODE 环境变量传给该会话的 DSH 进程；
• 配置后重启 dsh-weixin run 生效：该会话后续的 DSH 任务以覆盖路径为工作目录、 以覆盖权限运行，/send 的相对路径也按它计算，sessions//status 显示的就是覆盖后的 目录与权限；
• 也可用环境变量 DSH_BRIDGE_WORKSPACES（JSON 对象，临时覆盖）或代码内 buildConfig({ workspaces: {...} }) 传入；优先级：代码内 > 环境变量 > 配置文件；
• 文件在 data/ 下（已 gitignore），属本机配置，不会进入版本库。

通用桥接 bridge.mjs 另有 serve 子命令（HTTP 壳，端口默认 8317、绑定 127.0.0.1、可选 --token 🔒 鉴权），供 OpenClaw exec 工具、wechaty 等外部程序调用，详见 node bridge.mjs 帮助。

Permissions & data

本插件在本机运行，不涉及云服务。它访问/写入以下内容：

Troubleshooting

常见错误

日志位置

• 运行日志：weixin-bot.mjs run 的终端输出（stderr，[bridge …] 行，含收发/耗时/错误）；
• 对话记忆：data/history/<hash>.json；
• DSH 完整轨迹：~/.dsh/sessions/--<工作目录编码>--/session-*/session.jsonl.zstd。

三层均可命令直达：

node weixin-bot.mjs chats                              # 所有微信对话（联系人/轮数/DSH 会话数）
node weixin-bot.mjs history --chat <ID> --last 20      # 微信消息与 DSH 回复的对话原文
node weixin-bot.mjs sessions --chat <ID>               # 每条消息对应的 DSH 完整运行轨迹清单

<chat> 可用完整 chatId（如 wx:o9cq80…@im.wechat）、用户 ID 或 chats 显示的 hash 键。 查看某次 DSH 完整轨迹：zstd -d -c "<轨迹目录>\session.jsonl.zstd" | more 每个联系人的工作目录默认是 data/workspaces/<hash>/（配置了覆盖时为其指定目录）。

回滚

cd dsh-wechat-bridge; git checkout <上一个稳定 tag>; npm install -g .   # 源码安装
npm install -g dsh-wechat-bridge@<旧版本>                               # npm 安装

回滚不影响 data/ 下的历史与工作目录；重大操作前建议先备份 data/。

Development

构建：无需构建、零依赖，改完即跑（node weixin-bot.mjs …）。

测试：

npm test                # 单元测试：WS 帧编解码 6 项断言（node test-ws.mjs）
npm run test:loop       # 起 mock iLink 服务器（配合 Quick start 的本地闭环）

程序化入口：package.json main 指向 lib/core.mjs（导出 buildConfig / runChat / loadHistory / clearHistory / safeKey 等，供嵌入调用）；CLI 入口为 bin: dsh-weixin → weixin-bot.mjs。

贡献：fork → 新分支 → 跑通 npm test 与本地闭环 → 提交 PR。提交前确认不包含 data/、weixin-auth.json 或任何研究笔记（.gitignore 已覆盖）；仓库保持 dsh-plugin topic 以便雷达收录。

工作原理

• 协议：iLink Bot API（端点 https://ilinkai.weixin.qq.com/ilink/bot/...），与官方 SDK 2.4.6 行为一致：
  • 请求头：AuthorizationType: ilink_bot_token、随机 X-WECHAT-UIN、iLink-App-Id: bot、iLink-App-ClientVersion: 132102、Authorization: Bearer <token>
  • 登录：get_bot_qrcode（POST）→ get_qrcode_status（长轮询，支持配对码/二维码刷新/节点跳转）
  • 收消息：getupdates 长轮询 35s，get_updates_buf 游标持久化到磁盘（重启不丢）
  • 回复：getconfig（取 typing_ticket，缓存 24h）→ sendtyping(1) → sendmessage（必须原样带回该消息的 context_token）→ sendtyping(2)
  • 发文件：getuploadurl（filekey/md5/AES 密钥/加密后大小）→ CDN 上传 AES-128-ECB 密文（响应头 x-encrypted-param）→ sendmessage 携带 file_item/image_item/video_item
  • 收文件：媒体 item 的 media.encrypt_query_param → CDN 下载 → AES-128-ECB 解密 → 落盘 data/media/<hash>/
  • errcode/ret === -14 视为 token 失效，自动重新扫码续连
• DSH 后端：复用 lib/core.mjs——headless 一次性会话 + 历史注入 + 独立工作目录（与 bridge.mjs 同款记忆机制）。
• 会话续期：本地计时默认 24h（--session-ms 可调，提前 2h 提醒），到点主动向服务器"体检"——此时微信通道通常仍存活，续连二维码可直接发到微信；但实际有效性由腾讯服务器决定（官方 SDK 以 errcode -14 判定失效，社区实测约 24h~30h+，官方无承诺时长）。本实现双保险： ① 本地计时到期主动体检（服务器说仍有效 → 沿用 token 并刷新计时，说需重绑 → 发二维码）；② 任何时候收到 -14 都自动重新扫码续连，无缝换 token。

仓库文件

参考资料与替代实现

• 协议调研笔记（来源清单、实现备忘、与官方 SDK 的差异）：RESEARCH.md
• 同类"免 OpenClaw"实现（若想换 Python/Go 或参考配对细节）：zongrongjin/weixin-ilink（Python SDK）、jeffkit/ilink-hub、openilink/openilink-hub（Go + 多语言 SDK）、liiiiwh/weixin-clawbot-skill、minibear2021/wechat_clawbot_sdk

License & security

• 许可证：MIT，见 LICENSE。
• 报告安全问题：请私下报告（GitHub Security → Report a vulnerability，或 [SECURITY] 前缀 issue），详见 SECURITY.md；不要在公开 issue 贴 token 或复现细节。
• 这是腾讯官方通道（《微信 ClawBot 功能使用条款》背书），与逆向个人微信协议的封号风险方案本质不同；但条款明确：腾讯只是"管道"、有权限速/过滤/中止服务，不得用于营销、客服、高频群发。
• 凭证 weixin-auth.json 含 bot token，不要提交到版本控制或外传（.gitignore 已覆盖；npm 发布包不含 data/）。
• 任何能给你微信发消息的人都能触发本机 DSH 执行（等于你电脑的操作权）：建议 --allow-from 只放行自己的微信号；bot 指令也仅在你自己的对话生效。
• DSH 以你本机账号权限执行任务，请维持本机 DSH 自身的沙箱/审批配置。