# WeBridge 接入总览与模式选择

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

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

## 目录

- [1. 选择接入方式](#choose-mode)
- [2. 连接方向与并用规则](#connection-directions)
- [3. 配置与部署准备](#deployment)
- [4. 首次接入自检](#first-check)
- [5. 按业务查阅接口](#business-guide)
- [6. 结果、超时与重试](#results-and-retries)
- [7. 文档范围与版本识别](#documents-and-version)
- [8. 设置页检查更新](#settings-update)
- [附录：名词对照](#glossary)

<a id="choose-mode"></a>
## 1. 选择接入方式

| 方式 | 谁连接谁 | 你需要实现什么 | 适合的情况 |
|---|---|---|---|
| 插件内置 HTTP | 你的程序 → 手机 | 调用插件现有接口；用 `POST /events` 拉事件 | 程序能访问手机，想用普通 HTTP 完成发送、查询和接收事件 |
| 长轮询 | 手机 → 你的服务端 | `/agent/register`、`/agent/state`、`/agent/event`、`/agent/poll`、`/agent/command_result` 共 5 个 POST 接口 | 手机能访问后端，后端适合提供普通 HTTP 服务 |
| WebSocket | 手机 → 你的服务端 | 一个 WebSocket 端点，处理握手、命令、结果和事件帧 | 后端已支持 WebSocket，希望通过持续连接收发命令与事件 |

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

| 选定方式 | 接下来读这一份 |
|---|---|
| 插件内置 HTTP | [插件 HTTP 接口](插件HTTP接口（v8.0.80）.md) |
| 长轮询 | [服务端长轮询协议说明](服务端长轮询协议说明（v8.0.80）.md) |
| WebSocket | [服务端 WebSocket 协议说明](服务端WebSocket协议说明（v8.0.80）.md) |

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

<a id="connection-directions"></a>
## 2. 连接方向与并用规则

### 2.1 手机接口与服务端接口

| 项目 | 插件内置 HTTP | 长轮询／WebSocket 服务端 |
|---|---|---|
| 监听方 | 装有插件的手机 | 你的服务器 |
| 典型地址 | `http://<手机IP>:19088/send_message` | `https://<你的服务器>/agent/poll` 或 `wss://<你的服务器>/<端点>` |
| 实现方 | 插件已经实现 | 由你实现 |
| 网络前提 | 你的程序能访问手机 | 手机能访问你的服务器 |
| 事件接收 | 程序主动调用 `POST /events` | 插件向 `/agent/event` 上报，或发送 `event` 帧 |
| 命令下发 | 程序调用手机上的业务接口 | 服务端在 poll 响应中返回命令，或发送 `command` 帧 |

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

### 2.2 哪些方式可以同时使用

| 组合 | 是否支持 | 说明 |
|---|---|---|
| HTTP + 长轮询 | 支持 | 本地 HTTP 与出站长轮询可并用 |
| HTTP + WebSocket | 支持 | 本地 HTTP 与出站 WebSocket 可并用 |
| 长轮询 + WebSocket | 不支持 | 传输模式为单选，同一时刻只运行一种 |

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

<a id="deployment"></a>
## 3. 配置与部署准备

### 3.1 共同前提

| 项目 | 当前默认值／规则 | 接入前确认 |
|---|---|---|
| 插件总开关 | 默认关闭；有效启用还要求插件授权有效 | 在设置页开启微桥，确认账号登录与授权状态 |
| 发送、转发与接收事件 | 当前有效状态均跟随插件总开关与授权 | 协议保留 `send_enabled`、`forward_enabled`、`receive_enabled` 字段；无需寻找旧版独立开关 |
| 内置 HTTP 端口 | `19088` | 修改后使用实际端口；有效范围为 `1024`～`65535` |
| 内置 HTTP 监听地址 | `0.0.0.0`，即全部网卡 | 确认调用方与手机之间的网络可达 |
| 出站传输模式 | 默认长轮询 | 使用远程后端时选择长轮询或 WebSocket，并填写相应地址 |

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

### 3.2 长轮询配置

| 项目 | 填法／默认值 |
|---|---|
| 传输模式 | 长轮询 |
| 长轮询 HTTP 接口地址 | 服务端基础地址，例如 `https://<你的服务器>/bridge`；插件自动拼接 `/agent/*` |
| 轮询间隔 | 默认 `20` 秒，用于计算 poll 请求超时：`max(15 秒, 间隔 + 10 秒)`，默认超时 `30` 秒 |

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

### 3.3 WebSocket 配置

| 项目 | 填法／默认值 |
|---|---|
| 传输模式 | WebSocket |
| 服务端地址 | 完整 `ws://` 或 `wss://` 地址；兼容输入的 `http://`、`https://` 会转换为对应 WS 协议 |
| 握手与心跳 | 收到 `hello` 后按协议回复 `hello_ack`；插件每 30 秒发协议层 Ping |

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

### 3.4 事件暂存

| 配置 | 默认值 | 影响 |
|---|---|---|
| 断线后启用暂存 | 开启 | 长轮询／WebSocket 断线期间落盘暂存，恢复后尝试补发；关闭后不保证断线数据补发 |
| 最大暂存条数 | `500`，硬上限 `5000` | 超出容量时淘汰最旧内容 |
| 最大暂存时间 | `120` 秒；`0` 表示不过期 | 过期内容不会补发；不过期仍受容量限制 |

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

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

<a id="background-keepalive"></a>
### 3.5 后台运行

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

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

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

<a id="first-check"></a>
## 4. 首次接入自检

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

| 模式 | 连通检查 | 业务检查 | 事件检查 |
|---|---|---|---|
| HTTP | `GET /health`，检查监听端口、授权与开关状态 | 调用 `POST /send_message` 发到 `filehelper`，检查结果并在微信确认 | 调用 `POST /events`，给手机发消息，处理成功后保存 `next_offset` |
| 长轮询 | 观察 `register`、`state`、`poll` 是否按协议到达服务端 | 在 poll 响应中下发 `send_message`，等待 `/agent/command_result` 并在微信确认 | 给手机发消息，确认 `/agent/event` 收到并成功保存 |
| WebSocket | 收到 `hello` 并回复 `hello_ack`，观察心跳 | 下发 `command` 帧，等待 `command_result` 并在微信确认 | 给手机发消息，确认收到 `event` 帧并成功保存 |

HTTP 最小检查示例：

```bash
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 重复提交业务操作。

<a id="business-guide"></a>
## 5. 按业务查阅接口

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

### 5.1 消息、媒体与联系人

| 业务 | 在所选协议中查阅 |
|---|---|
| 发送文本、图片、语音、视频、文件、名片、位置等 | “消息发送”；名片与位置各有独立参数说明 |
| 转发、撤回、删除会话 | “消息操作”“会话管理” |
| 媒体下载、上传到后端、上传微信 CDN | “媒体下载与上传”：[HTTP](插件HTTP接口（v8.0.80）.md#message-media) / [长轮询](服务端长轮询协议说明（v8.0.80）.md#message-media) / [WebSocket](服务端WebSocket协议说明（v8.0.80）.md#message-media) |
| 好友列表、搜索添加好友、备注、星标、黑名单 | “好友与联系人”及对应接口；列表返回的添加时间未知时为 `null` |
| 好友／群成员支付姓名末字 | [HTTP](插件HTTP接口（v8.0.80）.md#friend-pay-name) / [长轮询](服务端长轮询协议说明（v8.0.80）.md#friend-pay-name) / [WebSocket](服务端WebSocket协议说明（v8.0.80）.md#friend-pay-name) |
| 账号资料、个人二维码、后台状态 | “账号资料”“状态查询”及个人二维码说明 |

<a id="group-member-operations"></a>
<a id="group-invitation"></a>
### 5.2 群聊

| 业务 | HTTP | 长轮询 | WebSocket |
|---|---|---|---|
| 创建群聊、直接加人、发送入群邀请 | [群成员操作](插件HTTP接口（v8.0.80）.md#group-member-operations) | [群成员操作](服务端长轮询协议说明（v8.0.80）.md#group-member-operations) | [群成员操作](服务端WebSocket协议说明（v8.0.80）.md#group-member-operations) |
| 查询邀请卡片、接受邀请入群 | [入群邀请](插件HTTP接口（v8.0.80）.md#group-invitation) | [入群邀请](服务端长轮询协议说明（v8.0.80）.md#group-invitation) | [入群邀请](服务端WebSocket协议说明（v8.0.80）.md#group-invitation) |
| 群二维码 | [群二维码](插件HTTP接口（v8.0.80）.md#get-chatroom-qrcode) | [群二维码](服务端长轮询协议说明（v8.0.80）.md#get-chatroom-qrcode) | [群二维码](服务端WebSocket协议说明（v8.0.80）.md#get-chatroom-qrcode) |
| 管理员、群主转让、群免打扰 | [群管理](插件HTTP接口（v8.0.80）.md#group-management-self-qrcode) | [群管理](服务端长轮询协议说明（v8.0.80）.md#group-management-self-qrcode) | [群管理](服务端WebSocket协议说明（v8.0.80）.md#group-management-self-qrcode) |

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

<a id="transfer-operations"></a>
### 5.3 红包、转账、朋友圈、收藏与公众号

| 业务 | HTTP | 长轮询 | WebSocket |
|---|---|---|---|
| 红包领取与详情 | [红包与转账](插件HTTP接口（v8.0.80）.md#http-payments) | [红包命令](服务端长轮询协议说明（v8.0.80）.md#red-packet-commands) | [红包命令](服务端WebSocket协议说明（v8.0.80）.md#red-packet-commands) |
| 转账接收、退还与状态查询 | [转账说明](插件HTTP接口（v8.0.80）.md#transfer-operations) | [转账说明](服务端长轮询协议说明（v8.0.80）.md#transfer-operations) | [转账说明](服务端WebSocket协议说明（v8.0.80）.md#transfer-operations) |
| 朋友圈列表、历史、互动、发布、权限与媒体 | [朋友圈](插件HTTP接口（v8.0.80）.md#moments-start) | [朋友圈](服务端长轮询协议说明（v8.0.80）.md#moments-start) | [朋友圈](服务端WebSocket协议说明（v8.0.80）.md#moments-start) |
| 收藏分页、发送与删除 | [收藏](插件HTTP接口（v8.0.80）.md#favorites) | [收藏](服务端长轮询协议说明（v8.0.80）.md#favorites) | [收藏](服务端WebSocket协议说明（v8.0.80）.md#favorites) |
| 公众号搜索、关注列表、关注／取关与文章 | [公众号](插件HTTP接口（v8.0.80）.md#official-accounts) | [公众号](服务端长轮询协议说明（v8.0.80）.md#official-accounts) | [公众号](服务端WebSocket协议说明（v8.0.80）.md#official-accounts) |

**本轮状态（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／长轮询外层收发、结果事件、重复操作、断网与账号切换，也未重新回传接收结果。

<a id="results-and-retries"></a>
## 6. 结果、超时与重试

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

<a id="documents-and-version"></a>
## 7. 文档范围与版本识别

| 文件 | 用途 |
|---|---|
| 本总览 | 选模式、准备配置、完成首次自检和定位业务 |
| 三份协议说明 | 各自模式的完整接入与接口约定 |
| [微信机器人.apifox.json](微信机器人.apifox.json) | 导入 Apifox，调试手机内置 HTTP 接口；服务端 `/agent/*` 和 WS 帧按对应协议实现 |
| [更新日志](更新日志.md) | 用户维护的版本变更记录 |

当前插件主版本为 `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` 验证通过。各业务章节保留历史具体回包及异常处理边界；新增的设置页检查更新仍需单独完成真机联调。

<a id='settings-update'></a>
## 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 或长轮询业务接口。本次构建与静态验证不代替真机弹窗和浏览器下载联调。

<a id="glossary"></a>
## 附录：名词对照

| 名词 | 含义 |
|---|---|
| 插件内置 HTTP／本地 HTTP | 手机上由插件提供的 HTTP 服务，默认端口 `19088` |
| 服务端／后端 | 你实现并部署的程序，供手机主动连接 |
| 长轮询／Long-Polling | 服务端暂时保留 poll 请求，等有命令或等待结束后返回，插件随后继续下一轮 |
| WebSocket／WS | 手机与服务端建立的持续双向连接 |
| 传输模式 | 插件设置中的单选项：长轮询或 WebSocket |
| 事件 | 微信发生的消息、好友申请、群变更或异步业务结果等通知 |
| 命令 | 服务端要求插件执行的操作 |
| 请求 ID | 关联一次调用和结果的编号；是否还能用于业务去重，按对应接口约定判断 |
| 暂存／离线队列 | 手机上保存的待发内容，在恢复连接后尝试补发 |