@ccchase/dsh-plugin-wechat

WeChat bridge plugin for DeepSeek Harness — 用微信跟你 DSH 里的 agent 对话，支持收发图片/文件。

基于腾讯官方 @tencent-weixin/openclaw-weixin（iLink Bot 通道）。 腾讯插件代码在构建时内嵌进本包（vendor/），其 openclaw/plugin-sdk 引用被改写为包内 stubs—— 不需要 openclaw，不需要任何额外包，装这一个就够了。

快速开始（使用者版）

前提

• 本机已运行 DSH（npx @deepseek-ai/dsh web）
• 准备一个用于扫码的微信（推荐小号；一个微信只能连一个 bot，且连接后不可重复扫码）

第 1 步：安装到 DSH

npx @deepseek-ai/dsh plugin --profile web add @ccchase/dsh-plugin-wechat

第 2 步：挂载（只需一次）

编辑 ~/.dsh/profiles/web/cordis.patch.yml，在文件末尾追加：

- insert:
    - id: wechat-bridge
      name: '@ccchase/dsh-plugin-wechat'
      config:
        cwd: 'C:\Users\你的用户名'   # agent 会话工作目录（默认用户主目录，可省略）
        autoStart: true

⚠️ 注意：这个文件如果之后被其他插件配置覆盖，需要把这两行加回去（本插件常见故障根因）。

第 3 步：重启 DSH

npx @deepseek-ai/dsh web

启动日志出现 [wechat-bridge] ✅ 微信账号已加载 即挂载成功。

第 4 步：微信登录（首次）

在运行 DSH 的本机执行：

npx @ccchase/dsh-plugin-wechat login

手机微信扫码确认，凭据自动保存（~/.openclaw/openclaw-weixin/accounts/）。重启 DSH 后桥接自动生效。

第 5 步：使用

给这个微信发消息即可，agent 回复自动回到微信。每个微信用户固定对应一个 DSH 会话（~/.openclaw/openclaw-weixin/dsh-bridge-state.json 记录）。

图片 / 文件收发

agent → 微信用户（发送）

agent 在回复中独占一行输出 MEDIA: 指令即可发送图片或文件（指令行不会显示给用户）：

MEDIA:C:\Users\me\photo.png     # 本地绝对路径
MEDIA:report.pdf                # 相对路径（基于会话工作目录）
MEDIA:file:///C:/tmp/a.pdf      # file:// 路径
MEDIA:https://example.com/a.png # 远程 URL（自动下载后发送）

• 按 MIME 自动路由：image/* → 图片消息、video/* → 视频消息、其他（pdf/doc/zip 等）→ 文件消息
• 支持一条回复携带多个 MEDIA: 指令，文本作为 caption 跟随第一个媒体
• 发送失败时会收到 ⚠️ 文件发送失败：<原因> 通知，文本回复不受影响
• 首条消息会向 agent 注入能力提示，agent 自然语言驱动即可

微信用户 → agent（接收）

• 用户发来的图片/文件/视频自动下载解密，保存到 <会话cwd>/.wechat-inbox/（保留原文件名）
• 保存路径以 [微信媒体] 用户发来图片，已保存至 <路径> 形式注入 agent 上下文
• 单条接收上限 100MB（腾讯端上限）

配置项

| 配置 | 默认 | 说明 | |---|---|---| | cwd | 用户主目录 | agent 会话工作目录 | | mediaEnabled | true | 媒体收发总开关 | | mediaInboxDir | <cwd>/.wechat-inbox | 接收媒体保存目录 | | maxMediaBytes | 104857600 | 单条接收媒体大小上限（字节） |

常用操作

| 操作 | 命令 | |---|---| | 升级插件 | npx @deepseek-ai/dsh plugin --profile web add @ccchase/dsh-plugin-wechat（重新执行即可） | | 卸载 | npx @deepseek-ai/dsh plugin --profile web remove @ccchase/dsh-plugin-wechat | | 换工作目录 | 改 cordis.patch.yml 的 cwd，删除 ~/.openclaw/openclaw-weixin/dsh-bridge-state.json（新建会话），重启 | | 独立运行（不挂 DSH 进程） | node node_modules/@ccchase/dsh-plugin-wechat/lib/bridge.js，环境变量 BRIDGE_CWD 覆盖工作目录 | | 运行测试 | npm test |

故障排查

| 现象 | 原因 / 解法 | |---|---| | 启动日志无 [wechat-bridge] | 挂载行丢失：检查 cordis.patch.yml | | ❌ 没有已登录的微信账号 | 未登录：执行 npx @ccchase/dsh-plugin-wechat login | | 微信发消息无回复 | 看 DSH 终端 [wechat-bridge] 日志：getUpdates 异常多为网络问题，会自动重试 | | 登录返回"已连接过，无需重复连接" | 该微信号已连过 bot，凭据仍有效，无需重新登录 | | 媒体发送失败 | 检查 [wechat-bridge] 日志中的上传错误；CDN 上传/下载失败多为网络问题，可重试 |

工作原理

微信用户 → 腾讯 iLink Bot API (ilinkai.weixin.qq.com)
               ↑ 长轮询 getupdates + contextToken 回显
        bridge.js（DSH 插件进程内）
               ↓ ctx.apiProxy（进程内服务，不走 HTTP）
           DSH harness（session.prompt + events.mux 事件流）

• 消息串行处理，agent 回复完整后发回微信
• 媒体发送走腾讯 CDN（AES-128-ECB 加密上传），接收时自动下载解密
• 插件启动时会等待 DSH 就绪（最多 1 分钟），就绪后自动开始轮询

开发

npm install
npm run build:vendor   # 从 node_modules 内嵌腾讯插件并 patch import
npm test               # 单元 + 集成测试（node:test）