WeBridge 接入总览与模式选择

本文档版次为 8080，沿用 8079 的业务接口约定；当前插件主版本为 8.0.80，本次构建为 8.0.80-2。用户已确认现有全部业务功能在微信 8.0.80 验证通过；下文保留旧版本的具体真机记录。新增的设置页检查更新仍需单独完成真机弹窗与浏览器下载联调。示例中的当前版本和构建标记用于说明格式，排错时以设备实际返回为准。

WeBridge 提供 HTTP、长轮询和 WebSocket 三种接入方式。先按网络条件选一种，再阅读对应协议即可完成接入；本篇介绍选型、配置准备和首次自检。

目录

• 1. 选择接入方式
• 2. 连接方向与并用规则
• 3. 配置与部署准备
• 4. 首次接入自检
• 5. 按业务查阅接口
• 6. 结果、超时与重试
• 7. 文档范围与版本识别
• 8. 设置页检查更新
• 附录：名词对照

1. 选择接入方式

推荐先按可达方向选择：程序能连手机，可以直接使用内置 HTTP；只有手机能连后端，就在长轮询和 WebSocket 中选一种。已有 WebSocket 服务时优先复用；后端只提供普通 HTTP 时选长轮询。

三份协议分别包含本模式的配置与鉴权、完整参数、请求和返回示例、事件、超时、重试及排错。选定后只需阅读对应的一份。

2. 连接方向与并用规则

2.1 手机接口与服务端接口

/agent/* 是你的长轮询服务端提供的路径，手机的 19088 服务不提供这些路由。插件设置中填写的是服务端基础地址或 WebSocket 地址。

2.2 哪些方式可以同时使用

你的后端只需实现一种出站协议。内置 HTTP 是否可用，取决于调用方能否访问手机；使用长轮询或 WebSocket 不会让手机自动变成公网可达。

3. 配置与部署准备

3.1 共同前提

插件授权用于判断插件是否具备调用资格；当前协议未提供调用方 API Key 或 Bearer Token 校验。内置 HTTP 应放在可信网络中，修改端口不能代替访问控制。长轮询与 WebSocket 的身份字段及握手要求见所选协议。

3.2 长轮询配置

服务端没有命令时保持 poll 等待，有命令时立即返回。服务端等待时长应小于手机请求超时，默认配置下可先用约 20 秒。插件完成当前批次执行及结果上报后继续下一轮；调小“轮询间隔”不会缩短两轮之间的固定休眠，因为这里没有这种固定休眠。

3.3 WebSocket 配置

代理与 WebSocket 服务端都要支持连接升级、Ping／Pong 和持续连接；握手时限、帧上限及重连规则见 WebSocket 协议。

3.4 事件暂存

HTTP 的 /events 使用独立的进程内缓冲区，复用条数与时间限制，不受断线暂存开关控制，也不会消费远程通道的队列。微信重启、容量或时间淘汰、手动清空均可能使旧 offset 失效，调用方需按 HTTP 协议恢复游标。

如果服务端可能停机超过默认的 2 分钟，应调整保留时间与容量。暂存不能保证无限补发，插件也不会给出完整的丢失条数统计。

3.5 后台运行

连接心跳、持续 poll 和业务等待都需要微信进程获得执行时间。后台保活默认关闭，音频子项默认开启，定位子项默认关闭；先开启微桥和保活总开关，再选择通道。定位需要在微信前台启动，并取得“使用 App 期间”或已有的“始终”定位权限。

关闭保活总开关会停止音频、定位和后台检查，子项保留原选择。诊断中的配置为 true，不代表通道仍在运行；定位处于 waiting_fix 也不能视作有效保活。

本地 HTTP 可调用 GET /debug/keepalive_status 查看 keepalive 对象；长轮询／WebSocket 下发 bridge_status，读取 background_keepalive_* 字段。没有独立的远程 keepalive_status 命令。保活无法防止系统因低内存结束微信；具体字段见各协议的状态查询部分，长期锁屏与通话测试可另读 巨魔后台保活测试说明（资料未收录）。

4. 首次接入自检

按选定模式完成下列检查。使用远程通道时，直接通过该通道验证，不要求后端先能访问手机 HTTP。

HTTP 最小检查示例：

curl http://<手机IP>:19088/health

curl -X POST http://<手机IP>:19088/send_message \
  -H "Content-Type: application/json" \
  -d '{"receiver":"filehelper","content":"连通性测试"}'

curl -X POST http://<手机IP>:19088/events \
  -H "Content-Type: application/json" \
  -d '{"offset":0,"limit":50,"timeout_seconds":20}'

/health 返回 ok:true 只证明健康查询成功，还要检查 auth_authorized、plugin_enabled 等实际状态。发送请求受理也不等于最终送达，应同时确认微信中的实际效果。

跑通正常路径后，再做两项检查：

1. 断线恢复：使用长轮询或 WebSocket 时，停止服务端约 30 秒，期间向手机发消息；恢复后核对暂存、补发与重复事件。HTTP 则验证客户端恢复原游标，以及 offset_expired 的处理。
2. 去重与未知结果：按所选协议处理事件 ID 和请求 ID；模拟结果未收到的情况，确认不会直接换 ID 重复提交业务操作。

5. 按业务查阅接口

下表用于定位业务章节，参数、返回和错误以所选模式的正文为准。

5.1 消息、媒体与联系人

5.2 群聊

直接加人、发送邀请和接受邀请是不同动作。直接加人不会自动改为发邀请，邀请发送成功也不代表对方已经入群；按对应章节的状态与重试规则处理。

5.3 红包、转账、朋友圈、收藏与公众号

本轮状态（2026-11-05）：用户此前已确认普通微信群内指定给自己的个人转账可领取；在 0.8.79-79 交付后，用户回传同笔转账查询 waiting_receive / native_status=2000 / can_refund=true，以及退还后 refunded / native_status=2002 / accepted=true / confirmed=true / ret_code=0，群内个人转账的查询和退还正常路径已实测通过。接口参数及结果结构不变，群 ID 从原消息读取，无需调用方补传。标准 Ubuntu 构建通过，新包为 0.8.79-79；旧包 0.8.79-78 的查询／退还仍保留群限制。此次回包未单独覆盖 WebSocket／长轮询外层收发、结果事件、重复操作、断网与账号切换，也未重新回传接收结果。

6. 结果、超时与重试

• 先判断本次返回，再判断业务是否完成。 HTTP 状态码或命令外层 ok 不能代替业务终态；“已受理”“已提交”“已确认”在不同接口中有明确含义。
• 等待方式由业务决定。 部分操作在当前请求中等待结果，朋友圈网络操作通常先返回任务编号，再通过完成事件或原编号查询。客户端超时必须按接口配置，不能统一套用普通请求的短超时。
• 结果未知时先核实。 转账、建群、加人、收藏发送／删除等都有各自的查询或去重边界；没有收到结果时不要直接换 ID 重提。缓存容量与跨重启保证也以各业务说明为准。
• 远程文件需要手机能访问目标。 长轮询／WebSocket 可使用对应媒体操作让手机主动上传后端；仅 HTTP 提供的本地文件读取与诊断入口，在各远程协议中分别说明限制和替代方式。

7. 文档范围与版本识别

当前插件主版本为 8.0.80，本次完整版本为 8.0.80-2。设置页、HTTP /health 的 version 与长轮询／WebSocket 的 runtime_version 均包含递增构建号，与当前运行的 deb 版本一致；build_marker 为 webridge_build_20261106_settings_update_8080。安装新包后需完全退出并重新打开微信，排错时保存设备实际回传值。

服务端应忽略不认识的新增字段，并依据实际接口结果处理能力差异；能力清单的已知缺口、兼容别名和已移除入口见所选协议。已读功能已移除，当前没有替代入口，旧调用的拒绝方式放在各协议末尾的“兼容与已移除功能”中。

用户已确认现有全部业务功能在微信 8.0.80 验证通过。各业务章节保留历史具体回包及异常处理边界；新增的设置页检查更新仍需单独完成真机联调。

8. 设置页检查更新

• 每次从入口打开微桥设置页后，自动静默检查一次；从日志等子页面返回不会重复请求。“工具 → 检查更新”可手动触发，正在检查时复用同一请求。自动检查失败或无新版时不弹提示，手动检查会反馈检查失败或当前已是最新版。
• 插件通过 GET https://wechat.vbzm.cn/api/v1/releases/latest 获取公开版本信息，不使用用户配置的业务服务器，也不携带账号授权资料。只有 available:true 且 release.version 高于当前完整版本才提示；三段主版本先按数字逐段比较，主版本相同再比较 -构建号，例如 8.0.80-2 > 8.0.79-999。
• 有新版时，弹窗显示版本、日期、大小和 changelog，提供“立即下载”“取消”。下载地址相对于官方站点解析，仅接受同源 HTTPS 地址，保留 publication 等查询参数；点击后交给系统默认浏览器。打开浏览器不代表下载、文件校验或安装完成，下载后仍需按原有方式安装或注入。
• 页面进入后台、子页面或正在显示其他弹窗时暂存结果，回到可展示状态再提示。本功能不新增 HTTP、WebSocket 或长轮询业务接口。本次构建与静态验证不代替真机弹窗和浏览器下载联调。

附录：名词对照