Integration

Dsh Wechat Bridge

Name: Dsh Wechat Bridge
Rating: 3.5 (1 reviews)
Author: gtaifu

By gtaifu 👁 25 views ▲ 0 votes

DeepSeek Harness (dsh) transport plugin: chat with your agents on WeChat via official Tencent iLink bot API — zero runtime deps, no OpenClaw, QR-code login, one friend = one persistent agent session.

GitHub

README

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

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/Node-%3E%3D18-green.svg)](package.json)
[![Gitee](https://img.shields.io/badge/Gitee-gtaifu%2Fdsh--wechat--bridge-red.svg)](https://gitee.com/gtaifu/dsh-wechat-bridge)

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

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

## 关键发现：微信龙虾的真相

调研确认（依据腾讯官方开源 SDK `@tencent-weixin/openclaw-weixin` 源码，详见 [RESEARCH.md](./RESEARCH.md)）：
微信「龙虾」/ClawBot 的底层是腾讯官方 **iLink Bot 协议**——纯 HTTP/JSON 的云端消息通道：
**扫码配对 → 长轮询收消息 → 你的程序调任意 AI → 发回微信**。官方 OpenClaw 插件本身也只是这套协议的客户端，AI 后端（OpenClaw/DeepSeek/…/DSH）完全自选，腾讯只是"管道"。
因此直连版 = iLink 协议客户端 + DSH 后端，本仓库 `weixin-bot.mjs` 即完整实现。

## 快速开始（龙虾直连）

环境：Node 18+，DSH 已安装可用（`dsh web` 能跑即可），零 npm 依赖。

```powershell
cd dsh-wechat-bridge

# 1) 扫码登录（一次性，凭证 24h 有效）
node weixin-bot.mjs login

# 2) 开始监听（保持终端开着）
node weixin-bot.mjs run
```

登录时终端会打印二维码链接：**在手机微信里打开该链接并确认**，几秒后即配对成功。
用户侧无需申请/审核：微信「我 → 设置 → 插件」中添加「ClawBot/龙虾」插件即可（个人用户免白名单）。

配对成功后，微信里直接给 Bot 发消息，DSH 就会收到并干活。常用内置指令：

| 指令 | 作用 |
|---|---|
| `/help` | 指令列表 |
| `/status` | 连接剩余时间 + 对话记忆条数 |
| `/time` | 本次连接剩余时间 |
| `/clear` | 清除你们之间的对话记忆（工作目录文件保留） |
| `/reconnect` | 手动重新连接 |
| `/send <文件路径> [说明]` | 把电脑上的文件发给你（绝对路径直接用；相对路径按你的工作目录算；图片/视频按媒体发送，其余按文件发送） |

> 每个微信联系人（`from_user_id`）有独立的 DSH 对话记忆与工作目录（`data/workspaces/`），
> 跨轮次的文件操作结果持续保留；记忆按条数/字符双上限滚动裁剪。

## 工作原理

- **协议**：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` 同款记忆机制）。
- **会话续期**：凭证会过期（官方 SDK 以 `errcode -14` 判定失效；社区实测约 24h）。本实现双保险：
  ① 到期前 2h 主动发微信提醒并生成新二维码；② 任何时候收到 `-14` 都自动重新扫码续连，无缝换 token。

## 配置

| 选项 | 默认 | 说明 |
|---|---|---|
| `--base-url` | `https://ilinkai.weixin.qq.com` | iLink 端点（测试时可指向 mock） |
| `--channel-version` | `2.4.6` | base_info.channel_version |
| `--bot-agent` | `dsh-wechat-bridge/…` | base_info.bot_agent（仅观测用途） |
| `--data-dir` | `./data` | 凭证/记忆/工作目录根 |
| `--auth-file` | `<data-dir>/weixin-auth.json` | 登录凭证（含 token，勿外传） |
| `--allow-from` | 全部 | 只响应指定用户 ID（逗号分隔） |
| `--reply-max-chars` | `3800` | 单条回复截断上限 |
| `--no-typing` | 关 | 不发"正在输入"状态 |
| `--session-ms` / `--relogin-before-ms` | 24h / 2h | 会话有效期 / 到期提醒提前量 |
| `--dsh-bin` `--timeout-ms` `--max-turns` `--max-history-chars` | 同 bridge | DSH 调用相关 |

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

## 本地闭环测试（无需真实微信）

```powershell
# 终端 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
```

## 查看微信 ↔ DSH 的历史记录

交互记录存在两层，均有命令直达：

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

| 层级 | 内容 | 位置 |
|---|---|---|
| 对话记忆 | 微信消息原文 + DSH 最终回复（含时间戳） | `data/history/<hash>.json`（`chats`/`history` 命令） |
| DSH 轨迹 | 每次任务的**完整 agent 运行**：提示词、工具调用、中间结果、耗时 | `~/.dsh/sessions/--<工作目录编码>--/session-*/session.jsonl.zstd`（`sessions` 命令列出） |
| 运行日志 | 收发消息、耗时、错误（带时间戳） | `weixin-bot.mjs run` 的终端输出（stderr，`[bridge …]` 行） |

- `<chat>` 参数可用完整 chatId（如 `wx:o9cq80…@im.wechat`）、用户 ID 或 `chats` 显示的键（hash）。
- 查看某次 DSH 完整轨迹（需系统装有 `zstd`，`sessions` 命令输出里有现成命令行）：
  `zstd -d -c "<轨迹目录>\session.jsonl.zstd" | more`
- 每个联系人还有独立**工作目录** `data/workspaces/<hash>/`：DSH 在对话中创建/修改的文件都留在那里。

## 安全与合规（重要）

- **这是腾讯官方通道**（《微信 ClawBot 功能使用条款》背书），与逆向个人微信协议的封号风险方案本质不同；但条款明确：腾讯只是"管道"、有权限速/过滤/中止服务，**不得用于营销、客服、高频群发**。
- 凭证 `weixin-auth.json` 含 bot token，**不要提交到版本控制或外传**；token 即"以你的微信身份收发消息"的凭据。
- 任何能给你微信发消息的人都能触发本机 DSH 执行（等于你电脑的操作权）：建议 `--allow-from` 只放行自己的微信号；bot 指令也仅在你自己的对话生效。
- DSH 以你本机账号权限执行任务，请维持本机 DSH 自身的沙箱/审批配置。

## 已知限制

- 媒体消息（图片/语音/文件/视频）会自动下载解密到 `data/media/<hash>/` 并告知路径；语音存为官方原始 `.silk` 格式（未做转码），图片/视频/文件按原格式保存。
- 单条回复超 `--reply-max-chars` 会截断（完整结果在 DSH 工作目录/终端）。
- 群聊：官方插件当前声明仅 direct chat，群消息不保证。
- 凭证约 24h 过期需重扫续连（自动提醒 + `-14` 自动重连，见"工作原理"）。
- 腾讯可随时变更协议（本实现对照官方 SDK 2.4.6，来源见 [RESEARCH.md](./RESEARCH.md)）。
- 同一时刻只有一条 DSH 任务在跑（不同联系人串行排队）。

## 参考资料与替代实现

- 协议调研笔记（来源清单、实现备忘、与官方 SDK 的差异）：[RESEARCH.md](./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`
- 本仓库 `lib/ws.mjs` 为 ClawChat 小程序直连网关预留的零依赖 WebSocket 基础（未启用）

## 仓库文件

| 文件 | 说明 |
|---|---|
| `weixin-bot.mjs` | **龙虾直连版**：iLink 客户端 + DSH 后端（login/run/status/logout/probe） |
| `bridge.mjs` | 通用桥接（CLI/HTTP），供 OpenClaw exec 工具、wechaty 等调用 |
| `lib/core.mjs` | 共享核心：DSH headless 调用、对话记忆、工作目录 |
| `lib/ilink.mjs` | iLink 协议客户端（对照官方 SDK 2.4.6 实现，含 `getuploadurl`/通用 `sendMessageItems`） |
| `lib/ilink-media.mjs` | 媒体通道：CDN 上传（AES-128-ECB）+ 下载解密落盘 + MIME/密钥工具 |
| `lib/ws.mjs` | 零依赖 WebSocket 服务端（备用：未来 ClawChat 小程序直连网关用） |
| `test-mock-ilink.mjs` | mock iLink 服务器（闭环测试） |
| `test-ws.mjs` | ws 帧编解码单元测试 |
| `dsh-weixin.cmd` | Windows 启动器（任意目录运行 `dsh-weixin login/run/…`） |
| `RESEARCH.md` | 协议调研笔记（来源清单、实现备忘） |
| `LICENSE` / `package.json` | MIT 许可证 / 包信息 |

## 已验证

- ✅ 协议头与官方规范逐项一致（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 周期需实机观察）

integration