good-boy4069/dsh-mobile-remote

dsh-mobile-remote

手机微信 = 你的 DeepSeek Harness 电脑遥控器。

微信扫码绑定机器人后，在任何网络（4G/任何 WiFi）通过微信指挥你的 dsh agent：
发命令、发任务、收结果、/ls 看电脑文件夹目录、双向收发文件、主动推送通知、多会话切换。

- 全权限模式：agent 全部工具可用，不弹确认直接执行（permissionMode 可切 strict 逃生舱）
- 语音消息：不存不转写，回复「无法识别语音消息」
- 消息经腾讯 iLink 服务器中转（微信没有第三方 API），非端到端加密——见「风险与边界」

突出特点与优势

相比同类 dsh 微信桥接插件（dsh-weixin、dsh-chatnode-wechat、dsh-im-bridge 等）：

1. 协议最扎实：wire 细节逐字对照腾讯官方 openclaw-weixin SDK v2.4.6（核对笔记与参考源码见 docs/）——出站 aes_key 编码、上传/消息两套媒体编号、CDN 上传下载流程全部与官方一致；入站 AES 密钥双编码态（base64 原字节 / base64 hex）全支持，坏密钥明确报错不降级
2. 双向文件收发：入站图片/文件/视频自动下载解密落盘（稳定命名防崩溃重放 + 明文 md5 校验 + 100MB 上限）；出站 /send 与模型回复中的 [[send-file:路径]] 双入口，共用唯一路径白名单校验（symlink 穿透/越界/目录一律拒绝）
3. 主动通知闭环：模型工具 weixin_send（文本+文件）+ 未绑定会话完成通知（规则化去重防双发）；会话令牌过期（-14）返回精确文案，健康面板自动降级提示重新扫码，运行中重新扫码热轮换凭据无需重启
4. 多会话遥控：/sessions 列表 + /switch 编号/标题双语义切换，手机上在多个电脑任务间跳转；会话被其他窗口接管时旧窗口收到提示，杜绝输出串台
5. 可靠性工程（同类少见的重点投入）：恰一次处理管线（队列+游标同次原子落盘）、outbox at-least-once 投递与崩溃恢复续传、全局处理限额器(8)+下载信号量(3)+背压节流、drain 重入互斥与游标引用身份校验、凭据双写冗余；182 项自动化测试全绿 + 严格 typecheck + 宿主包零值导入门禁
6. 可观测性：/health 健康端点（字段白名单、零内部标识泄露）、登录页三态状态条（运行中/缺凭据/未启动+原因）、gateway.log 文件日志（1MB 轮转、0600）
7. 安全边界清晰：白名单是唯一使用边界、登录页仅 loopback 可访问、错误文案不泄露密钥与路径、weixin_send 文件受同一路径白名单约束

安装

1. 安装插件到 web profile
npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-mobile-remote

2. 启动 dsh web（或重启）
dsh web

扫码登录

1. dsh web 运行后，本机浏览器打开 http://127.0.0.1:3080/mobile-remote-weixin/login
2. 手机微信扫码，按提示确认（若手机要求输入数字验证码，页面会提示输入）
3. 登录成功后即可在微信里给机器人发消息

登录页顶部有网关状态条（绿=运行中 / 黄=缺凭据 / 红=未启动+原因）；
GET /mobile-remote-weixin/health 返回健康快照（仅本机可访问，无内部标识字段）。

命令

| 命令 | 作用 |
|---|---|
| /status | 会话状态 + 会话标识 + 工作区 |
| /new | 断开当前会话，下条消息开新会话 |
| /stop | 停止运行中任务 |
| /reply  | 追问当前任务 |
| /sessions | 最近 10 个会话（当前绑定标 ⭐） |
| /switch  | 切换会话：纯数字先按 /sessions 编号，越界/无列表回退标题匹配 |
| /切换聊天窗口： | 恒按标题匹配切换（标题恰为纯数字时用它直达） |
| /send  | 把工作区/收件目录内的文件发到微信 |
| /ls [路径] | 看电脑文件夹目录 |
| /workspace | 查看当前工作区 |
| /help | 再次显示命令清单 |

文件收发

- 收：微信发来的图片/文件/视频自动下载解密，落盘到 /.wechat-inbox//
（文件名 = 原名 + 消息哈希，稳定命名防崩溃重放重复落盘；大小上限 maxMediaBytes，默认 100MiB）。
模型会看到 [收到文件]  提示，可用 vision 等工具继续处理。
- 发：/send  直接发；agent 回复中独占一行写 [[send-file:路径]] 也会把文件发到微信
（该指令行不会发给用户）。路径必须落在工作区或收件目录内（同一校验函数，symlink 穿透/越界一律拒绝）。
- 语音消息维持拒识，不下载不落盘。

主动通知

- weixin_send 工具：微信会话的 agent 可用它把文本/文件推送到微信（绑定的聊天窗口；
未绑定时回落到 notifyChatId 通知目标）。enableWeixinSendTool（默认开）可整体关闭。
- 完成通知：配置 notifyChatId + notifyOnTurnEnd: true 后，未绑定微信的会话任务完成时
会推送 ✅ 任务完成：会话「标题」 到通知目标（绑定会话不重复通知；同 turn 已由工具推过则去重）。

配置（可选，全部有默认值）

环境变量：

| 变量 | 默认 | 说明 |
|---|---|---|
| WEIXIN_BOT_TOKEN | 无 | 登录 token（扫码登录后自动保存，无需手动设置） |
| WEIXIN_ALLOWED_USERS | 扫码者自动加入 | 允许使用 bot 的用户 id，逗号分隔 |
| WEIXIN_ALLOWED_GROUPS | 空 | 允许的群 id（群聊需 user+group 双命中） |
| WEIXIN_BOT_API_BASE | https://ilinkai.weixin.qq.com | iLink 网关地址 |
| WEIXIN_CDN_BASE | https://novac2c.cdn.weixin.qq.com/c2c | 媒体 CDN 地址 |
| WEIXIN_MAX_MESSAGE_CHARS | 3500 | 单条回复分块长度 |
| WEIXIN_MAX_MEDIA_BYTES | 100MiB | 媒体大小上限 |
| WEIXIN_PERMISSION_MODE | full | full=全权限；strict=工具白名单+审批（预留） |
| WEIXIN_DSH_WORKSPACE | 自动 | 微信新会话默认工作区（优先级：本变量 > 显式配置 > dsh 当前工作区 > 进程目录） |

cordis 配置项（config 键）：

| 键 | 默认 | 说明 |
|---|---|---|
| inboxDir | 空（=工作区/.wechat-inbox） | 收件目录；越界自动回退默认并警告 |
| enableWeixinSendTool | true | weixin_send 工具总开关 |
| notifyChatId | 空 | 完成通知/工具兜底目标（配置后 Web 会话也可用 weixin_send 推送） |
| notifyOnTurnEnd | false | 未绑定会话完成时推送通知 |
| logDir | 空（=state 同目录） | 网关日志目录（gateway.log，1MB 轮转） |
| statePath | ~/.dsh/mobile-remote-weixin/gateway-state.json | 网关状态文件 |

健康与日志

- 健康快照（/health）：运行状态、轮询活动、连续错误数、绑定数、积压数、凭据、启动失败原因等——
白名单字段，绝不包含 chatId/sessionId/进度等内部标识。
- 文件日志：gateway.log（append-only、0600、1MB 轮转只留一代、写失败静默降级），同时 tee 到 dsh 日志。

风险与边界（务必阅读）

- 全权限模式：无人在环确认；白名单是唯一防线，只能放你自己的微信号。
- weixin_send 外发面：工具对作用域内 agent 可见，被注入的入站消息可诱导模型把工作区文本/文件推到微信；
filePath 受 /send 同一白名单（工作区/收件目录）约束，但文本内容不受路径校验——不要在不信任的群里使用。
- 隐私：消息经腾讯 iLink 服务器中转（非端到端加密）；媒体解密后落盘于工作区 .wechat-inbox。
- 账号共存：同一微信账号被 OpenClaw 等其他 iLink 客户端驱动会抢消息，需停用其一。
- 凭据：token 存本机（credentials 服务 + 自管回退文件 0600），泄露等同账号控制权。
- 平台风险：iLink 非公开稳定 API，可能协议漂移；违规使用有封号风险，自担。

局限与未支持功能（诚实声明）

选择本插件前请知悉以下边界——部分是设计决策，部分在路线图外：

- 语音消息不支持识别：收到语音一律回复「无法识别语音消息」（不下载、不转写、不落盘）。这是设计决策，语音转写不在范围内
- 媒体不进模型多模态管道：图片/文件只做「落盘 + 给模型绝对路径提示」，插件本身不解析内容；需要配视觉类工具（如 vision_analyze）读取
- 无定时任务：不能预约「每天 X 点做某事」（cron/桌宠类需求不在范围）
- 无远程审批按钮：全权限模式 = 无人在环确认，微信里没有「批准/拒绝」交互；strict 模式为预留逃生舱（未完成审批流）
- 依赖非公开协议：iLink 是腾讯未公开的 bot 协议，协议漂移可能导致功能失效，且违规使用有封号风险
- 单账号绑定：一个 dsh 实例一套微信凭据；要多微信账号/多 bot 需多开 profile 实例（无内置多实例管理）
- 内容级文件去重未实现：同一文件跨消息重发会重复落盘（仅保证「同一条消息崩溃重放」不重复下载）
- 命令与文案为中文：斜杠命令、帮助清单、提示均为中文，无英文/i18n
- 无图形化设置面板：配置全部走环境变量 / cordis patch（登录页仅提供扫码、状态条与健康端点）
- 运行要求：Node ≥ 22.12、dsh web profile、微信账号需可扫码绑定 iLink bot

开发

npm install
npm run typecheck
npm test
npm run build

License

MIT