dsh-plugin-wechat-official

Readme

# dsh-plugin-wechat-official

**DeepSeek Harness 微信 ClawBot 渠道插件** —— 通过腾讯官方开放的 **微信 ClawBot 插件功能**（iLink 协议），让用户在**个人微信**中直接与 DeepSeek Harness Agent 对话。

> ✅ 全部基于腾讯官方通道（`ilinkai.weixin.qq.com`），**不使用**任何个人微信逆向协议、网页自动化、Hook 客户端或其它可能导致封号的非官方方案。
> 底层协议与 openclaw 的微信渠道插件 `@tencent-weixin/openclaw-weixin` 同一套（HTTP/JSON，腾讯仅作为消息管道，不存储输入输出内容）。

---

## 目录

- [工作原理](#工作原理)
- [前置条件](#前置条件)
- [安装](#安装)
- [配置](#配置)
- [首次运行（扫码登录）](#首次运行扫码登录)
- [使用](#使用)
- [连接续期（24 小时）](#连接续期24-小时)
- [访问控制](#访问控制)
- [合规与风险提示](#合规与风险提示)
- [常见问题](#常见问题)
- [项目结构](#项目结构)
- [开发与测试](#开发与测试)
- [参考](#参考)

---

## 工作原理

```
微信用户 ──▶ 微信 ClawBot（腾讯官方 iLink 服务）
                 │  getupdates 长轮询（游标 get_updates_buf）
                 ▼
        dsh-plugin-wechat-official（本插件，运行在 DSH 进程中）
                 │  文本 → createUserMessage → followup
                 ▼
        DSH Agent 会话（每个微信用户独立会话，持久化可恢复）
                 │  回复文本 ← assistant/message 事件
                 ▼
        sendmessage（必须回带 context_token 关联对话窗口）
                 │  sendtyping「正在输入」状态
                 ▼
微信用户 ◀── 收到 Agent 回复
```

关键机制：

| 机制 | 说明 |
|---|---|
| 官方通道 | 登录走 `get_bot_qrcode` / `get_qrcode_status` 扫码；收消息走 `getupdates` 长轮询；回消息走 `sendmessage` |
| 会话关联 | 每条入站消息带 `context_token`，回复时必须原样回带，否则消息无法关联到对话窗口 |
| 独立会话 | 每个微信用户对应一个 DSH Agent 会话（id 由用户 id 派生），历史经 sessionPersistence 持久化，重启可恢复 |
| 正在输入 | 通过 `getconfig` 获取 typing_ticket 后调用 `sendtyping`（status 1/2）显示「正在输入」 |
| 24h 续连 | iLink 连接约 24 小时有效，到期前提醒最近联系人，可回复 Y 立即重连，最后时限强制重连，全程不断线 |
| 按用户串行 | 同一用户的消息按顺序处理，回复不会交错错位 |

---

## 前置条件

1. **一个开通了「微信 ClawBot 插件功能」的微信个人账号**。ClawBot 是微信官方向用户提供的连接第三方 AI 服务的功能，在微信内按提示「连接」并同意《微信ClawBot功能使用条款》后即可使用（本插件是条款意义上的「第三方 AI 服务提供方」）。
2. **DeepSeek Harness**（`dsh` CLI）与 web profile 可正常运行（插件作为宿主插件挂载到 web profile 进程）。
3. **Node.js ≥ 22**（DSH 本身要求）。
4. 运行 DSH 的机器可访问 `ilinkai.weixin.qq.com`（出站网络）。**无需公网 IP / 域名 / 端口映射** —— ClawBot 是插件主动长轮询拉取消息，不需要微信回调你的服务器。

---

## 安装

### 1. 安装依赖包到 web profile

```bash
# 克隆本仓库
git clone https://github.com/echo-lgtm/dsh-plugin-wechat-official.git
cd dsh-plugin-wechat-official

# 安装到 DSH web profile
dsh plugin --profile web add file:$(pwd)
```

> 等价于在 `~/.dsh/profiles/web` 下执行 `pnpm add file:<仓库绝对路径>`。

### 2. 挂载插件行

编辑 `~/.dsh/profiles/web/cordis.patch.yml`，追加（把示例值替换成你的配置）：

```yaml
- insert:
    - id: wechat-clawbot
      name: 'dsh-plugin-wechat-official'
      config:
        # 扫码登录后凭证的存储目录（默认 $DSH_HOME/wechat-clawbot，可留空）
        storageDir: ''
        # 启动时自动恢复会话 / 无凭证时自动进入扫码登录
        autoLogin: true
        # 二维码展示：log（打印链接）| file（写 qrcode-url.txt）| both（默认）
        qrcodeOutput: 'both'
        # 访问控制：open | allowlist | disabled
        dmPolicy: 'open'
        allowFrom: []
        # Agent 工作目录（绝对路径；留空使用 DSH 进程当前目录）
        agentCwd: ''
```

### 3. 启动

```bash
dsh web
```

首次启动会在日志中打印二维码链接（并写入 `<storageDir>/qrcode-url.txt`）。

---

## 配置

| 字段 | 默认值 | 说明 |
|---|---|---|
| `storageDir` | `$DSH_HOME/wechat-clawbot` | 凭证与二维码文件存储目录 |
| `autoLogin` | `true` | 启动时自动恢复已保存会话；无凭证时自动进入扫码登录 |
| `qrcodeOutput` | `both` | 二维码展示方式：`log` / `file` / `both` |
| `qrcodeScanTimeoutMs` | `600000` | 等待扫码的最长时间（毫秒） |
| `sessionDurationMs` | `86400000` | iLink 连接有效期（毫秒，约 24 小时） |
| `reconnectWarningBeforeMs` | `7200000` | 到期前多久向最近联系人发送重连提醒（毫秒） |
| `reconnectReminderIntervalMs` | `1800000` | 用户回复 N 后再次提醒的间隔（毫秒） |
| `reconnectForceBeforeMs` | `1800000` | 到期前多久开始强制重连（毫秒） |
| `longPollTimeoutMs` | `38000` | 长轮询超时（毫秒，微信最多 hold 35 秒） |
| `dmPolicy` | `open` | 访问控制：`open`（所有人）/ `allowlist`（仅 `allowFrom`）/ `disabled`（关闭对话） |
| `allowFrom` | `[]` | `allowlist` 模式下允许的用户 id 列表（形如 `xxx@im.wechat`） |
| `renderMarkdown` | `true` | Agent 回复的 Markdown 是否转为微信友好的纯文本 |
| `welcomeText` | `你好，我是 DeepSeek Harness Agent…` | 新用户首次对话欢迎语 |
| `agentCwd` | DSH 进程 cwd | Agent 工作目录 |

> 连接参数（`sessionDurationMs` 等）如需调小测试，例如 `sessionDurationMs: 300000, reconnectWarningBeforeMs: 60000, reconnectReminderIntervalMs: 30000, reconnectForceBeforeMs: 60000` 可在一分钟内跑完整个续连流程。

---

## 首次运行（扫码登录）

1. 启动 `dsh web`，日志中会出现：
   ```
   wechat-clawbot: starting QR login…
   wechat-clawbot: scan QR in WeChat → https://…
   wechat-clawbot: QR url saved to …/qrcode-url.txt
   ```
2. 用手机微信打开该链接（或在微信内扫描二维码），按提示「连接」并确认。
3. 日志出现 `wechat-clawbot: login OK (bot …)` 后，即可在微信中向该机器人发送消息。
4. 凭证自动保存到 `storageDir/session.json`（0600 权限），下次启动自动恢复，无需重复扫码。

---

## 使用

在微信中向机器人发送消息：

- **直接发文字** → 转发给 DSH Agent，回复经 `sendmessage` 送达，期间对方可见「正在输入」。
- **发语音** → 若微信已附带转写文字，则以 `[语音] 转写内容` 形式转发给 Agent。
- **发图片 / 文件 / 视频** → 以占位描述（`[图片]` 等）转发给 Agent，由 Agent 决定如何回应。
- **内置指令**：

  | 指令 | 作用 |
  |---|---|
  | `/help` 或 `/指令` | 查看指令列表 |
  | `/time` | 查询当前连接剩余时间 |
  | `/status` | 查看 Bot 运行状态 |
  | `/重新连接` | 立即重新连接（需回复 Y 确认） |

每个用户拥有独立的 Agent 会话（带完整对话历史），也可在 DSH Web UI 的会话列表中查看。

---

## 连接续期（24 小时）

iLink 连接有效期约 24 小时。插件在到期前约 2 小时向最近联系人发送提醒：

```
[提醒] 连接还剩约 22.0 小时到期，是否现在重新连接？回复 Y 立即重连，N 稍后提醒
```

- 回复 **Y** → 立即重连：插件向该联系人推送新二维码，扫码确认后 **token 原子替换，连接无缝切换**。
- 回复 **N** → 按 `reconnectReminderIntervalMs` 间隔再次提醒。
- 到达 `reconnectForceBeforeMs` 时限 → 自动强制重连。
- 意外会话失效（token 过期）→ 自动清除凭证并重新进入扫码登录。

---

## 访问控制

- `dmPolicy: 'open'`（默认）：任何能向该机器人发消息的微信用户均可对话。
- `dmPolicy: 'allowlist'`：仅 `allowFrom` 中列出的用户 id 可对话，其余用户收到「没有权限」提示。
- `dmPolicy: 'disabled'`：关闭对话能力（仅保留指令与重连相关消息）。

> 用户 id 形如 `o9cq800kum_xxx@im.wechat`。可先以 `open` 模式运行，用 `/status` 或日志查看来访用户 id，再收紧为 `allowlist`。

---

## 合规与风险提示

1. 本插件只使用腾讯官方 ClawBot 接口，但请务必遵守《[微信ClawBot功能使用条款](https://github.com/hao-ji-xing/openclaw-weixin/blob/main/protocol.md)》与《微信个人账号使用规范》：不得利用该功能绕过/破解微信技术保护措施、不得从事违法违规行为。
2. 腾讯仅作为消息管道，**不存储**输入输出内容；接入的 AI 服务（即 DSH Agent）由你自行负责，输出结果责任自负。
3. 腾讯有权对连接的第三方 AI 服务进行识别、限流甚至阻断（条款 4.7 / 7.2），**不建议把核心业务完全依赖该通道**，应保留降级方案。
4. 请妥善保管 `storageDir/session.json`（内含 bot token）。

---

## 常见问题

| 问题 | 处理 |
|---|---|
| 启动后没有看到二维码 | 检查日志是否出现 `starting QR login…`；若 `storageDir` 下有旧 `session.json` 且仍有效则直接恢复，不会重新登录。删除 `session.json` 可强制重新登录 |
| 发送消息没有回复 | 确认日志中是否出现 `收到消息` / `deliver reply`；检查 `dmPolicy` 是否拦截；确认 Agent 服务（`agents` / `agentLoop`）可用 |
| 回复没有进入对话窗口 | 该现象通常是 `context_token` 丢失或过期——本插件始终回带用户**最新**入站消息的 context_token |
| 提示「连接即将到期」 | 正常现象，按提示回复 Y 重连即可；也可用 `/重新连接` 手动触发 |
| 收不到消息、日志持续报错 | 检查出站网络能否访问 `ilinkai.weixin.qq.com`；token 可能已失效，删除 `session.json` 后重启重新扫码 |

---

## 项目结构

```
dsh-plugin-wechat-official/
├── package.json            # 插件包定义（main 指向 lib/index.js，peerDeps 为 DSH 包）
├── cordis.patch.yml        # DSH profile 插件行声明（- insert: 条目）
├── lib/
│   ├── index.js            # Cordis 插件入口：Config schema / apply / 生命周期
│   ├── ilink.js            # iLink ClawBot 协议客户端（登录/长轮询/sendmessage/typing）
│   ├── channel.js          # 频道运行时：登录生命周期/轮询循环/指令/重连/访问控制
│   ├── bridge.js           # DSH Agent 桥接：会话映射/入队/回复提取（复用 DSH 核心）
│   ├── markdown.js         # Markdown → 微信友好纯文本
│   └── store.js            # 凭证持久化（原子写 + 0600）
├── scripts/
│   └── smoke.mjs           # 冒烟测试：本地模拟 iLink 服务器跑通全链路
├── test/                   # node:test 单元测试（ilink/markdown/bridge/channel）
└── README.md
```

## 开发与测试

```bash
npm run check    # 语法检查
npm test         # 单元测试（32 个用例）
npm run smoke    # 冒烟测试：本地模拟 iLink 服务器，验证登录→收消息→typing→回复全链路
```

---

## 参考

- OpenClaw 微信渠道文档：<https://docs.openclaw.ai/zh-CN/channels/wechat>
- 微信 ClawBot 使用条款（协议全文）：<https://github.com/hao-ji-xing/openclaw-weixin/blob/main/protocol.md>
- iLink 协议技术解析：<https://github.com/hao-ji-xing/openclaw-weixin/blob/main/weixin-bot-api.md>
- 官方插件包（腾讯）：<https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin>