WeBridge 服务端长轮询接入

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

本文适用插件 8.0.80。选择本交互模式后，仅阅读本文即可完成配置、鉴权、命令调用、事件接收及结果处理；所有业务参数、返回与重试规则均在本篇。本地 HTTP 专用能力的限制及本模式替代方式也在本文说明。

目录

接入与基础协议

• 1. 这个模式是什么
• 2. 你要实现什么
• 3. 通信约定
• 4. 五个接口总览
• 5. POST /agent/register
• 6. POST /agent/state
• 7. POST /agent/event
• 8. POST /agent/poll
• 9. POST /agent/command_result
• 10. 公共字段
• 11. 能力清单

业务命令

• 12. 命令参数与返回
• 12.1 参数通用规则
• 12.2 命令总表
• 12.3 消息发送与操作
• 12.4 联系人查询与好友添加
• 12.5 群昵称、群名、公告与群二维码
• 12.6 红包与转账
• 12.7 个人资料设置与地区代码
• 12.8 状态查询与后台保活
• 12.9 本地 HTTP 专用入口与本模式限制
• 13. 好友备注、星标和黑名单
• 14. 创建群聊、直接加人和发送入群邀请
• 15. 入群邀请：查询、静默接受与探针
• 16. 群管理员、群免打扰与个人二维码
• 17. 媒体下载与上传
• 18. 公众号：搜索、列表、关注／取关与历史文章
• 19. 朋友圈：调用、结果与后续操作
• 20. 收藏：分页读取、发送与删除

事件与运行

• 21. 事件字段
• 22. 运行节奏与状态机
• 23. 错误的处理与重试
• 24. 离线队列与补发
• 25. 幂等与去重
• 26. 常见问题排查

附录

• 附录 A. 接入检查清单
• 附录 B. 兼容别名与已移除功能

1. 这个模式是什么

插件作为 HTTP 客户端，主动向你的服务端发请求：

优点：你的服务端只要有普通 HTTP 就能对接，不需要 WebSocket。

服务端没有命令时保持 poll 等待，有命令时立即结束等待并返回；插件处理完当前批次及结果上报后才会继续 poll。命令延迟还受排队、业务处理、上报和网络影响（详见第 22 节）。

和"插件内置 HTTP 接口"的关系：不冲突。你仍然可以同时通过手机上那个 HTTP 端口主动调插件。不同模式的选型对比可另看《接入总览与模式选择》，不影响按本文独立接入。 和"WebSocket"的关系：两者互斥，插件同一时刻只用一种传输模式。长轮询是默认模式。

2. 你要实现什么

5 个 POST 接口，路径固定为：

{你在设置页填的基础地址}/agent/register
{你在设置页填的基础地址}/agent/state
{你在设置页填的基础地址}/agent/event
{你在设置页填的基础地址}/agent/poll
{你在设置页填的基础地址}/agent/command_result

请求和响应体都是 JSON。 除 poll 的响应体之外，其余接口的响应体内容插件不解析——只认 HTTP 状态码。

2.1 设置页配置与授权

插件总开关的状态关系：开启总开关时会把底层接收／发送／转发／模拟配置设为开启；这四种有效状态均跟随插件总开关与授权，界面没有独立入口。

长轮询请求和失败重试只维持通信，依赖微信进程获得执行时间，不能替代 iOS 后台保活。“后台保活”与插件总开关分开；其关闭后 audio_enabled/location_enabled 仍可能为 true，实际停止应核对运行字段，见 保活诊断与测试。

plugin_configured_enabled 表示保存的总开关，plugin_enabled 表示总开关与有效授权同时成立。当前设置页没有独立的接收、发送和转发开关；本文业务段落中的“发送／写入开关”等均指相应有效状态，不是要求另找一个设置项。服务端接收本协议请求时，按设备和账号保存状态；auth_status 描述插件授权结果，不是调用方自定义的 API Token。

3. 通信约定

3.1 地址怎么写

在插件设置页的「服务端地址」里填基础地址：

地址规范化规则：

基础地址只填到业务路径前缀，插件会自动拼接 /agent/*；不要填某一个具体接口。

3.2 成功与失败怎么判定

插件只看 HTTP 状态码：

插件不解析响应体里的业务字段（唯一的例外是 poll 要看 commands 数组）。

所以：你的响应体里写什么 ok 字段都没用，返回正确的状态码才管用。

3.3 请求头

每个请求都是 POST，带：

Content-Type: application/json
Accept: application/json

3.4 超时

⚠️ 注意 poll 超时有个 15 秒下限。如果你的服务端 hold 时间超过这个值，插件会判定超时并触发退避重试。 想让 hold 更久，需要同时调大设置页里的「轮询间隔」。

3.5 连接数

插件对 poll 请求限制为单连接（同一时刻只有一个 poll 在飞），对事件上报用另一套连接池。

实际行为：事件上报是串行单飞的——一次只发一条，成功了才发下一条。

4. 五个接口总览

调用顺序（严格）：

register → state → poll → （执行命令）→ command_result → poll → …

5. POST /agent/register

何时调用

插件启动后立即调用；服务端地址被修改后也会在下一轮立即重新 register。

请求示例

{
  "device_id": "webridge_device_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "session_id": "sess_1775000000123_a1b2c3d4e5f6",
  "account_id": "wxid_self",
  "runtime_version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080",
  "ts_ms": 1775000000123,
  "capabilities": ["send_message", "send_image", "…"],
  "state": { "…": "…" }
}

你该做什么

1. 用 device_id 作为设备主键（长期稳定）
2. 用 session_id 关联本次运行（每次插件启动都会变）
3. 记录 capabilities
4. 返回 200（响应体可以是 {}，插件不看）

失败后果

非 2xx → 阻断。插件不会继续发 state 和 poll，而是按退避策略重试 register。

⚠️ 这是唯一一个"失败了就卡住"的接口。你的服务端如果 register 有 bug，插件会一直停在这里。

6. POST /agent/state

何时调用

register 成功后立即调用一次，之后不再调用。

请求示例

{
  "device_id": "webridge_device_xxxx",
  "session_id": "sess_1775000000123_a1b2c3d4e5f6",
  "account_id": "wxid_self",
  "runtime_version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080",
  "ts_ms": 1775000001123,
  "state": { "…": "…" }
}

与 register 的唯一区别：顶层不带 capabilities。state 对象的字段定义相同，但两次采样值可能变化。

6.2 state 对象的完整字段表

register 和 state 的状态快照使用同样的 20 个字段；各次请求会重新采集，字段值可能变化。

auth_status 的取值集合：

实用字段：pending_event_queue_count + oldest_pending_event_age_ms 是用于观察事件积压的字段；它们不能精确统计已丢条数。poll 本身不携带 state，持续监控时定期下发 bridge_status 查询。

失败后果

失败也继续。 state 失败不会阻断流程，不会重试，也不计入失败计数。插件会直接进入 poll。

⚠️ 这是一个真实的行为差异：register 失败会卡住，state 失败不会。所以如果你的服务端只处理了 register 而 state 一直 500，插件不会给你任何反馈，你会静默地收不到状态信息。

7. POST /agent/event

何时调用

微信中发生事件时（收到消息、红包、转账、好友申请、群成员变动等）。

请求示例

{
  "device_id": "webridge_device_xxxx",
  "session_id": "sess_xxx",
  "account_id": "wxid_self",
  "runtime_version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080",
  "ts_ms": 1775000000123,
  "event_name": "message",
  "event_id": "msg:7307587870543245070",
  "captured_at_ms": 1775000000100,
  "enqueued_at_ms": 1775000000120,
  "upload_started_at_ms": 1775000000121,
  "body": { "…": "…" }
}

💡 长轮询独有：事件比 WebSocket 模式多一个 upload_started_at_ms。三段时延分析： - captured_at_ms → enqueued_at_ms：插件内部处理耗时 - enqueued_at_ms → upload_started_at_ms：在本地队列里排队等待的耗时 - upload_started_at_ms → 你收到的时间：网络传输耗时

这是长轮询模式相比 WebSocket 的一个优势——排障时能把"插件慢"和"网络慢"分开。

event_id 的格式规则

判定按固定优先级短路，命中第一条就返回：

由此推出的实用结论：

⚠️ 实战建议：不要把 event_id 当格式化字符串去解析（别试图从中提取消息 ID 或群 ID）。它是一个不透明的去重键，格式可能随版本变化。需要具体字段请从 body 里取。

你该怎么做：按 event_id 去重，返回 200。

失败后果

非 2xx → 重试。重试延迟见第 23 节。

事件用磁盘队列暂存，进程重启后会恢复继续补发。详见第 24 节。

8. POST /agent/poll

服务端通过此接口的响应下发命令。

何时调用

插件循环调用。每轮 poll 结束后立即发起下一轮，中间不等待。

请求示例

{
  "device_id": "webridge_device_xxxx",
  "session_id": "sess_1775000000123_a1b2c3d4e5f6",
  "account_id": "wxid_self",
  "runtime_version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080",
  "ts_ms": 1775000002345,
  "capabilities": ["send_message", "send_image", "…"],
  "last_result_request_id": "req-send-message-001"
}

⚠️ last_result_request_id 的语义容易被误解： 它表示"最近一次已生成结果的 request_id"，而不是"最近一次已成功上报的 request_id"。 也就是说：如果那条结果上报失败了、正在退避重试，这个字段里已经出现它了。 不要用它判断"服务端是否已收到结果"——请以 command_result 接口实际收到为准。

响应：这是唯一必须返回正确结构的接口

有命令时：

{
  "commands": [
    {
      "request_id": "req-send-message-002",
      "command_name": "send_message",
      "args": {
        "receiver": "wxid_friend",
        "content": "你好"
      }
    }
  ]
}

没有命令时，返回下面任意一种都行：

{ "commands": [] }

{}

一次可以返回多条，插件会逐条串行执行。

关于"长轮询 hold"

你可以把请求 hold 住，直到有命令要下发或快超时为止。规则：

如果你 hold 到超时：插件判定失败 → 退避重试 → 产生额外延迟。所以 hold 时长要留安全余量。

⚠️ 一个容易踩的坑：如果你的服务端立即返回空 {}（不做 hold），插件会立刻再发一次 poll——形成高频空转。虽然功能正常，但会产生大量无用请求和电量消耗。 请务必实现 hold，否则长轮询就退化成了"高频轮询"。

失败后果

非 2xx → 计入失败计数 → 退避重试。已取到的待执行命令不会丢失（见第 22 节）。

9. POST /agent/command_result

何时调用

每执行完一条命令后。注意：插件会等这条结果上报成功，才执行下一条命令。

请求示例

{
  "device_id": "webridge_device_xxxx",
  "session_id": "sess_xxx",
  "account_id": "wxid_self",
  "runtime_version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080",
  "ts_ms": 1775000003456,
  "request_id": "req-send-message-002",
  "command_name": "send_message",
  "ok": true,
  "duration_ms": 320,
  "result": { "receiver": "wxid_friend" },
  "error": ""
}

判断成功

friend_pay_name 单次命令等待终态后回包，详见阻塞查询；群二维码见 get_chatroom_qrcode。

ok 表示本次命令是否执行成功，不要用 error 是否为空或 result 是否有内容代替它。 朋友圈首次命令ok=true仅表示受理，必须按result.operation_id等待moments_result或继续查询；详见本篇完整流程。对于资料设置，ok:true 表示已提交或当前值已一致，仍需核对 result.accepted、result.local_verified；拍一拍的首次 ok:true 只表示受理，最终成功须查询探针并确认 last_operation.status:"succeeded" 和 server_confirmed:true。详见资料设置命令。

duration_ms 的精确含义

从命令进入共享执行队列之前开始计时，到业务返回为止，包含在插件内的排队和业务等待；不包含前一条命令尚未结束时本条仍留在批次里的等待。

它不包含： - 从你的 poll 响应发出到插件收到的网络时间 - 结果回传给你的网络时间

对包含下载/转码的命令（如 send_voice、send_video、send_emoji），这个值可能达到数秒甚至更长。

ts_ms 的精确含义

ts_ms 是结果信封被生成的那一刻，不是发送成功的时刻。

⚠️ 一个真实存在的现象：结果上报失败时，插件会重发同一个结果信封。重发时 ts_ms 仍是原来生成时的值，所以你会看到一个"明显早于当前时间"的 ts_ms。这是正常的，不是时钟错误。

失败时 result 里有什么

不是所有失败都是空 result。 部分命令失败时仍会返回诊断信息：

结论：失败时不要假设 result 是空的，把它记进日志会大幅加快排错。

失败后果

非 2xx → 退避重试。插件会一直重发同一条结果，并暂停执行后面的命令，直到上报成功。

⚠️ 这意味着：如果你的 /agent/command_result 一直返回 500，插件会卡在这一条命令上，后续命令全部不执行。 这是最常见的一类"插件好像死了"的误判。

10. 公共字段

以下字段出现在 register、state、event、poll、command_result 全部五个请求中，含义与生成规则完全相同。

下表包含本模式所需的全部公共字段；不需要另查其他协议文档。

各接口携带情况

11. 能力清单

capabilities 是插件当前声明支持的命令集合，当前共 118 项。现有业务功能已由用户在微信 8.0.80 验证通过；切换到其他微信版本时仍需核对实际运行能力：

send_message,
send_signal,
send_pat,
receive_red_packet,
red_packet_detail,
receive_transfer,
refund_transfer,
get_transfer_status,
clear_gender_region,
profile_update,
profile_gender,
profile_region,
profile_signature,
profile_pat_suffix,
profile_region_codes,
moments_list,
moments_user,
moments_detail,
moments_refresh,
moments_like,
moments_unlike,
moments_comment,
moments_delete_comment,
moments_publish,
moments_delete,
moments_permissions_query,
moments_permissions_update,
moments_operation,
moments_probe,
moments_media_download,
profile_nickname,
send_image,
upload_message_image,
download_message_media,
upload_message_media,
upload_file_to_wechat_cdn,
message_media_probe,
send_emoji,
send_voice,
send_video,
send_video_from_url,
send_link_card,
send_xml,
send_contact_card,
send_location,
location_geocode_probe,
send_music_card,
send_file,
send_file_from_url,
forward_message,
revoke_message,
delete_friend,
delete_session,
quit_group,
create_group,
add_group_member,
invite_group_member,
kick_group_member,
kick_group_members,
rename_group,
set_group_name,
get_group_notice,
get_chatroom_qrcode,
get_self_qrcode,
group_admin_operate,
set_group_msg_silence,
set_friend_remark,
get_group_invitation,
accept_group_invitation,
group_invitation_probe,
friend_request_probe,
search_contact,
official_accounts,
official_account_search,
official_account_follow,
official_account_unfollow,
official_account_articles,
add_friend,
add_room_friend,
friend_add_probe,
accept_friend_request,
room_members,
account_status,
bridge_status,
device_status,
friends,
friends_all,
friend_pay_name,
groups_all,
quote_build_probe,
signal_send_probe,
pat_send_probe,
red_packet_probe,
red_packet_detail_probe,
transfer_probe,
clear_gender_region_probe,
profile_probe,
profile_region_probe,
profile_pat_suffix_probe,
profile_nickname_probe,
image_send_probe,
emoji_send_probe,
voice_send_probe,
video_send_probe,
video_send_url_probe,
link_send_probe,
file_send_probe,
file_send_url_probe,
revoke_probe,
delete_friend_probe,
quit_group_probe,
invite_group_member_probe,
kick_group_member_probe,
rename_group_probe,
set_group_name_probe,
send_livephoto,
livephoto_probe,
livephoto_diagnostics

当前分发器可执行但尚未列入 capabilities 的业务命令为 favorites_list、favorites_send、favorites_delete、set_friend_star、set_friend_blacklist；另有兼容别名 group_invite_member、group_invite_member_probe、set_group_nickname、set_group_self_nickname、set_group_nickname_probe、set_group_self_nickname_probe、update_nickname、update_nickname_probe 未声明。后端若只按清单过滤会误判不支持；按本篇命令表、别名表及实际插件构建处理这些缺口。清单只代表声明，不能代替实际业务能力判断；用户已确认现有业务功能在微信 8.0.80 验证通过。

三个重要提醒

1. 以插件上报的清单为准。 它随插件版本变化，请以每次 register 实际收到的为准。
2. 声明清单仍有上文列出的业务及兼容别名缺口。 历史构建也曾漏声明实况照片等命令；不要仅凭版本号或清单缺省判断可调用范围。
3. capabilities 会随每次 register 和 poll 重复携带，插件运行期间内容不变。

12. 命令参数与返回

12.1 参数通用规则

收藏命令也使用严格类型校验，并且不接受目标别名，详见收藏用法。公众号五项同样采用严格类型校验，未知字段报错，见公众号。

资料设置命令与资料预校验探针采用严格类型校验；签名保留原始空白，拍一拍使用微信原生文本处理规则，详见本节资料管理说明。

⚠️ 宽松转换是陷阱：类型写错不会报错。把数字参数写成 "abc" 会被当作 0，而不是返回参数错误。

12.2 命令总表

消息发送

消息操作

联系人与群组

⚠️ 重名陷阱：accept_friend_request 的 args.request_id 是好友申请的业务 ID，与命令信封上的 request_id（用于结果关联）同名但完全是两回事。你有两个 request_id 出现在不同层级，别搞混。

会话管理

红包与转账

资料管理

收藏

完整参数、结果和重试规则见本篇收藏用法。

朋友圈

状态查询

这三个命令是插件被禁用时仍可执行的唯一三个。其余命令在插件禁用时会返回 ok:false 且错误文案为 plugin is disabled（已授权）或 authorization required（未授权），result 里带 auth_status 和 authorized。

调试探针

以下命令主要用于返回运行时和候选参数诊断；是否触发资源准备或原生查询以对应说明为准，不将诊断成功当作业务完成。建议在正式调用某个能力前先跑一次对应探针，确认它在你的微信版本上可用：

friend_add_probe、quote_build_probe、signal_send_probe、pat_send_probe、red_packet_probe、red_packet_detail_probe、transfer_probe、clear_gender_region_probe、profile_probe、profile_region_probe、profile_pat_suffix_probe、profile_nickname_probe、image_send_probe、emoji_send_probe、voice_send_probe、video_send_probe、video_send_url_probe、link_send_probe、file_send_probe、file_send_url_probe、revoke_probe、delete_friend_probe、quit_group_probe、invite_group_member_probe、kick_group_member_probe、rename_group_probe、set_group_name_probe、friend_request_probe、livephoto_probe、livephoto_diagnostics

⚠️ 两点必须知道： 1. 探针名不要带 /debug/ 前缀。命令通道用的是上面这些裸名字；写成 /debug/xxx_probe（带斜杠）会得到 unsupported command_name。 2. "不真正执行操作"成立，但"无副作用"不成立。部分探针会做真实的网络请求或文件操作：表情/视频/语音探针会发 HTTP 请求探测远程资源并可能下载落盘；文件探针会清理上传目录；视频探针会创建目录并清理缓存。

12.3 消息发送与操作

表情发送与转发补充： send_emoji转换前按当前微信动态配置检查大小，实际限制见emoji_send_probe的limits.max_file_size/max_dimension，不能把静态默认5MiB写死。字节有效上限为原生两种配置较大值与20MiB插件保护上限的较小值，超限明确失败。

forward_message转发表情时，在同一命令内检查／下载原生资源，再转发并等待目标消息最终发送确认，无需另加下载命令，也不需要先打开手机对话。下载、发送各最多等待30秒。下载失败不转发；已提交但确认超时会返回“结果未知，请勿自动重试”，不能将失败回包当作对方一定未收到。HTTP、长轮询、WS共用该实现；成功字段保持既有简洁结构。

send_message

{ "receiver": "wxid_friend" }

传了 quote_message_id 时多一个 quote_message_id 字段；有 @ 时多一个 mention_user_list 数组。

@ 相关规则：

• mention_user_list 也接受别名 at_user_list；at_user（单个 wxid）会被并入名单最前面
• content 里可用 {{mention:wxid}} 占位符，在正文任意位置插入 @
• 即使不传 mention_user_list，只要正文里有 {{mention:wxid}}，插件也会自动提取并走 @ 链路
• ⚠️ 占位符里的 wxid 解析不出备注名或昵称时，整条消息会被拒绝发送
• @所有人：mention_user_list: ["notify@all"]，仅群聊可用。notify@all 是协议标记不是 wxid，不要展开成全部成员
• 插件不会自动往 content 里补 @所有人，要在界面上看到这四个字必须自己写进 content
• 是否允许发送仍受微信群主/管理员权限限制，插件不绕过微信校验

send_image

{
  "resolved_image_path": "/var/mobile/.../photo.jpg",
  "receiver": "wxid_friend",
  "downloaded": false
}

send_emoji

用途：发送表情（gif / png / jpg / jpeg 均可）。

大小限制读取当前微信动态配置，实际值见emoji_send_probe命令的limits.max_file_size/max_dimension。字节上限为两种原生配置较大值与20MiB保护上限的较小值；静态默认5MiB不能替代真机配置。转换前和读取数据后均检查，超限明确报错，不提交发送。

args 字段：

说明：

• 远程图片会自动下载到插件沙盒，缓存 1 天后自动清理。
• 不是 gif 的图片会被转换成微信表情格式。

成功时的 result：

{
  "receiver": "wxid_friend",
  "source": "https://example.com/demo.png",
  "source_type": "remote_url",
  "emoji_path": "/var/mobile/.../demo.gif",
  "resolved_emoji_path": "/var/mobile/.../demo.gif",
  "downloaded": true,
  "emoji_md5": "…",
  "message_type": 47,
  "message_type_name": "emoji"
}

send_voice

{
  "receiver": "wxid_friend",
  "source": "https://example.com/audio.mp3",
  "source_type": "remote_url",
  "resolved_local_path": "…",
  "resolved_pcm_path": "…",
  "resolved_wechat_aud_path": "…",
  "duration_ms": 3240,
  "downloaded": true,
  "message_type": 34,
  "message_type_name": "voice"
}

• source 兼容别名：voice_url、voice_path、audio_url、audio_path、video_url、video_path、aud_url、aud_path
• duration_ms 兼容 voice_length_ms、voice_duration_ms；推荐使用数字毫秒值
• 非 .aud 文件会被自动转码（提取音频 → PCM → SILK），耗时较长，后端等待业务结果需留足时间；poll 仅投递命令，其网络超时与业务等待期限分别设置

send_video

{
  "source": "…",
  "source_type": "remote_url",
  "resolved_video_path": "…",
  "resolved_thumb_path": "…",
  "receiver": "…",
  "video_duration": 12.5,
  "generated_thumb": true,
  "downloaded": true,
  "max_size_bytes": 10485760,
  "max_size_mb": 10,
  "within_size_limit": true,
  "remote_size_known": true,
  "remote_size_bytes": 8123456
}

• 默认大小上限 10 MiB；max_size_mb 优先级高于 max_size_bytes
• source 也接受 video_url、video_path

send_livephoto

args 必填字符串 receiver、video_path（手机路径或手机可访问的 URL）；可选字符串 image_path、数字 still_image_time_ms、布尔 prefered_hevc（默认 false）。prefered_hevc 就是此拼法。命令通道会转换数字／布尔字符串，新接入仍应发送原生 JSON 类型。

成功时的 result：

{"video_path":"/var/mobile/example.mov","image_path":"/var/mobile/example.jpg","receiver":"filehelper"}

send_link_card

args 必填 receiver、title、url；可选 description、thumb_url、thumb_path、source_user_name、source_display_name，均为字符串。缩略图和跳转链接须为手机可访问的资源。

成功时的 result：

{"receiver":"wxid_friend","title":"标题","url":"https://example.com","thumb_url":""}

send_music_card

用途：发送音乐卡片。注意：这个接口内部走的是转发链路（relay_* 字段会体现在响应里），不是直接构造消息。

别名表（这个接口为了兼容历史调用方，别名特别多）：

重要：url、data_url、song_album_url、app_id、app_name 这五个字段不传会用内置默认值兜底（默认指向一个示例音乐）。也就是说缺参数不会报错，会发出去一张指向默认歌曲的卡片。要发自己的音乐，这五个字段请全部显式传入。

args 示例（URL 和应用信息均为占位值，需替换）：

{
  "receiver": "filehelper",
  "title": "歌曲标题",
  "desc": "歌手 - 专辑",
  "url": "https://music.example.com/song/1",
  "data_url": "https://media.example.com/song/1.mp3",
  "song_album_url": "https://media.example.com/song/1.jpg",
  "app_id": "wx_example_music_app",
  "app_name": "音乐应用"
}

成功时的 result：

{
  "receiver": "wxid_friend",
  "title": "歌曲名",
  "desc": "",
  "url": "https://music.example.com/song",
  "dataurl": "...",
  "songalbumurl": "...",
  "app_id": "wx...",
  "app_name": "网易云音乐",
  "songlyric_length": 0,
  "relay_forward": true,
  "relay_chat": "filehelper",
  "relay_delete_staged": true
}

songlyric_length 为实际歌词的 UTF-16 长度；未提供歌词时为 0。

relay_* 字段说明该卡片是通过"先发到文件传输助手再转发"的链路实现的。如果你在文件传输助手里看到过残留，属正常现象，插件会清理。

send_file

{
  "resolved_file_path": "…",
  "receiver": "…",
  "file_name": "report.pdf",
  "file_size": 204800,
  "extension": "pdf"
}

send_file_from_url 会额外返回 source_url 和 downloaded。

send_contact_card

发送已有联系人的原生名片。receiver 是收件人或群，contact_id 可传被推荐联系人的真实 ID，或本机已有好友的完整微信号（alias），不能传群 ID。微信号精确匹配，匹配不唯一则拒绝；不按昵称、备注模糊选择，不自动联网搜索陌生人。成功 result.contact_id 统一返回解析后的真实 user_name。头像、昵称等取微信联系人资料，不接受自定义头像或昵称。

{"request_id":"card-001","command_name":"send_contact_card","args":{"receiver":"filehelper","contact_id":"wxid_example"}}

成功 result：{"submitted":true,"receiver":"filehelper","contact_id":"wxid_example","message_type":42}。普通名片类型 42，OpenIM / OpenIM 客服按原生判断为 66 / 67。submitted:true 仅表示原生提交，不能视为服务器确认送达；名片发送已由用户在微信 8.0.80 验证通过，特殊联系人仍按微信实际返回处理。

send_location

发送单次位置消息。必填 receiver、latitude、longitude；经纬度必须是有限 JSON 数值，范围分别 -90～90、-180～180，不接受数字字符串、布尔值、null。选填字符串 title、address，空白串按省略处理，null 为参数错误。

{"request_id":"location-001","command_name":"send_location","args":{"receiver":"filehelper","latitude":23.012345,"longitude":113.123456}}

有非空标题直接使用；只传地址时地址也用作标题。两者均省略时执行微信原生反查，最多等 15 秒；优先采用带方向的地理描述，再尝试地址或 POI 名称，不能保证得到指定商户名称。需精确文案时传 title。经纬度同时为 0 会被原生反查拒绝，显式标题可跳过反查。插件原样使用坐标，不做坐标系转换，外部 GPS 输入须先对点。

成功 result 包含 submitted:true、receiver、message_type:48、latitude、longitude、最终 title、address、title_source。来源为 provided、address 或 wechat_geocode。失败时外层 ok:false、error 为中文说明，result 保留 error_code 和反查诊断；反查失败、超时、无可用文字或账号/登录会话变化均不提交消息。成功只表示原生提交，尚未确认送达。

位置等待使用后台执行，不占用心跳和收包队列。send_location 与普通发送命令一样使用已有 request_id 结果缓存；缓存存在时重复 ID 会回放结果，重试应使用新的 ID，并先确认上次是否已经提交。名片和位置发送均遵循授权、插件启用及有效发送状态。

location_geocode_probe

实际测试指定坐标的原生反查，不发送消息、不需要收件人，不受发送开关限制；仍需授权、启用插件并登录微信。

{"request_id":"geocode-001","command_name":"location_geocode_probe","args":{"latitude":23.012345,"longitude":113.123456}}

result 保留以下诊断（流程未到达的字段可能缺省）：

探针和坐标发送共用反查实现，完成、失败和超时都会清理本次回调及扩展注册，迟到回调不会发送消息。探针每次执行，不复用通用 request_id 结果缓存。建议先检查回调与原生地址字段，再执行位置发送。位置发送及反查功能已由用户在微信 8.0.80 验证通过，接收端展示以实际微信界面为准。

send_signal

{
  "receiver": "…",
  "cgi": 976,
  "event_flag": 5,
  "client_msg_id": 4976413716,
  "create_time": 1777500000
}

send_pat

{ "receiver": "…", "room_id": "…", "is_group": true, "scene": 0, "selector": "…" }

forward_message / revoke_message

forward_message 必填字符串 receiver、message_id，需开启转发功能；revoke_message 必填字符串 message_id，受微信自身撤回时限约束。成功时的 result 分别为：

{"message_id":"1234567890123456789","receiver":"filehelper"}

{"message_id":"1234567890123456789"}

下载／发送确认和结果未知时的处理见本节表情转发说明；失败时检查外层 ok、error，不能因为未拿到确认就自动重发。

12.4 联系人查询与好友添加

联系人摘要对象

friends、friends_all、groups_all、room_members 使用相同的基础联系人字段，并按场景增加好友或群成员字段。本模式好友数据位于成功结果的 result.items[]，群成员数据位于 result.members[]。

空值与省略规则：

• 普通字符串的 "" 表示未设置或本地没有取得有效值；不能据此推断对方资料一定为空。
• add_time 与 add_time_text 总是成对返回：有值时分别为秒级整数和 UTC+8 文本，未知时均为 null。不以 0、空串或 1970 年日期代替未知，也不使用本地添加流程时间兜底。
• is_starred、is_blacklisted 及群成员角色字段可能整个省略。字段缺失表示未知，不能按 false 处理。

添加时间来自微信当前保存的记录，与微信资料页使用的字段一致；不承诺删除后重加时仍是终身首次添加时间。文本不随手机时区、语言或日历设置变化。两个好友查询及同名命令均无需新增请求参数。

支付姓名状态：

friends、friends_all 本身不发起支付姓名查询，需要时调用 friend_pay_name；其结果不会改变昵称、备注或 display_name。

完整好友条目示例（虚构数据，共 17 个字段）：

{
  "account_id": "wxid_example",
  "display_name": "示例备注",
  "remark": "示例备注",
  "alias": "wechat_example",
  "nick_name": "示例好友",
  "avatar_url": "",
  "sex": 0,
  "province": "",
  "city": "",
  "signature": "",
  "contact_found": true,
  "is_starred": false,
  "is_blacklisted": false,
  "add_time": 1704067200,
  "add_time_text": "2024-01-01 08:00:00",
  "pay_name_last_char": "",
  "pay_name_status": "not_queried"
}

时间未知时的字段节选：

{"add_time": null, "add_time_text": null}

friends

result.items[] 为好友摘要，每条恒含 add_time 与 add_time_text，无需新增参数；完整字段与示例见联系人摘要对象。

{
  "keyword": "",
  "limit": 100,
  "offset": 0,
  "total": 256,
  "has_more": true,
  "items": [ "…" ]
}

翻页时不断增大 offset，直到 has_more 为 false。

friends_all

一次性返回关键词过滤后的普通好友。result.items[] 的字段、添加时间时区及空值规则与 friends 相同。

{
  "keyword": "",
  "total": 256,
  "friend_count": 256,
  "official_account_count": 12,
  "work_account_count": 0,
  "system_account_count": 4,
  "chatroom_count": 38,
  "stranger_count": 0,
  "cached_contact_count": 310,
  "items": [ "…" ]
}

items 只包含关键词过滤后的普通好友；total、friend_count 与 items 长度一致。公众号、企业微信、系统号、群聊和陌生人只参与各自分类计数，不混入好友数组。cached_contact_count 是未经过滤的原始缓存联系人条数。 六类联系人计数均经过关键词过滤；cached_contact_count 保留原始缓存条数。

groups_all

{ "keyword": "", "total": 38, "items": [ "…" ] }

无分页字段。

room_members

{
  "room_id": "…",
  "room_name": "…",
  "room_remark": "",
  "current_user": "wxid_self",
  "owner_user_name": "wxid_owner",
  "admin_count": 2,
  "admin_user_names": [ "…" ],
  "admin_members": [ "…" ],
  "self_is_owner": false,
  "self_is_admin": false,
  "member_count": 24,
  "members": [ "…" ]
}

失败结果仍使用命令信封，例如 {"ok":false,"result":{"room_id":"…"},"error":"…"}；不要因失败而丢弃 result.room_id。

friend_pay_name：阻塞查询好友或群成员支付姓名末字

单次调用等待微信回调后返回最终结果，不返回 querying 中间结果，无需再次查询任务状态。微信主线程保持异步运行。

这里的“实名相关查询”指微信支付脱敏姓名的末字查询，不提供完整实名，也不能用查询结果判断对方是否已实名认证。

• id 必填，使用好友列表或 room_members 返回的个人 account_id。好友直接查询；非好友自动查找双方均在其中的普通微信群，无需传 room_id。不支持自己、群 ID、公众号、企业微信或系统号。
• refresh 为布尔值，默认 false。当前好友或共同群场景有缓存时立即返回终态（包括已缓存的失败）；true 强制刷新或失败重试，并等待本次结果。同一目标、同一场景正在查询时合并等待；关系或群上下文变化后重新查询。
• 自动查找依赖本地群列表和成员资料；未找到可用共同群或资料未就绪时返回 failed 和中文原因。存在多个共同群时选择一个已核实的普通群，不轮询所有群发起支付查询。
• 原生查询串行执行，最多 32 个待处理请求；30 秒超时包含排队时间，接口等待保护上限约 31 秒。调用方超时建议至少 40 秒。
• 仅查询转账前信息，不提交金额或付款确认。结果只保留在当前账号会话内存中，账号或联系人服务会话变化后清空。

friends、friends_all 只附带好友场景缓存，本身不发起支付查询，群内非好友不会因此加入好友列表。列表仍可能显示 not_queried 或正在处理的 querying；单人查询接口和命令只返回上表中的终态。支付姓名字段不改变昵称、备注或 display_name，不提供完整姓名。

自动选择共同群的功能已由用户在微信 8.0.80 验证通过。

下发一次命令：

{
  "commands": [
    {
      "request_id": "pay-name-001",
      "command_name": "friend_pay_name",
      "args": {
        "id": "wxid_example",
        "refresh": false
      }
    }
  ]
}

插件等到终态后，使用同一 request_id 通过 POST /agent/command_result 上报结果：

{
  "request_id": "pay-name-001",
  "command_name": "friend_pay_name",
  "ok": true,
  "result": {
    "account_id": "wxid_example",
    "pay_name_last_char": "明",
    "pay_name_status": "ok"
  },
  "error": ""
}

不再下发状态查询命令；业务失败时外层 ok=false、error 给出原因，result 保留目标好友和姓名状态。外层身份字段 account_id 是登录账号，result.account_id 才是目标好友。

主动添加好友

命令 search_contact、add_friend、friend_add_probe 的参数放在 args，结果使用既有 request_id/command_name/ok/result/error 信封；业务字段在 result，顶层 ok/error 不再重复放入 result。

下发搜索和添加的命令主体示例（放入 /agent/poll 响应的 commands 数组）：

{"request_id":"search_demo_1","command_name":"search_contact","args":{"keyword":"示例微信号"}}

{"request_id":"add_demo_1","command_name":"add_friend","args":{"contact_ref":"fc_example_ref","say_content":"你好，我是某某"}}

添加结果信封示例：

{
  "request_id":"add_demo_1",
  "command_name":"add_friend",
  "ok":true,
  "result":{
    "status":"request_sent","username":"example_user","is_friend":false,
    "contact_ref":"fc_example_ref","native_ret":0,"stage":"send_verification",
    "request_submitted":true,"event_id":null
  },
  "error":""
}

以下为三个命令共用的业务字段说明；结果示例均采用本模式命令信封，ok/error 位于外层，业务字段位于 result。

主动添加使用两步调用：先搜索获得 contact_ref，再用该引用提交验证消息。支持普通个人联系人；公众号、群、OpenIM 和当前账号不提供可添加的引用。friends.keyword 仍只过滤本地好友列表。

搜索参数为 {"keyword":"示例微信号"}，keyword 必须是 1–256 个字符的字符串。支持微信实际允许搜索的微信号、手机号等，不保证任意原始 wxid 可搜索。搜索成功示例（依据用户提供的 HTTP 真机回包整理，身份和头像链接已替换）：

{
  "request_id": "search_demo_1",
  "command_name": "search_contact",
  "ok": true,
  "result": {
    "status": "found",
    "contacts": [
      {
        "contact_ref": "fc_example_ref",
        "username": "example_user",
        "nick_name": "示例昵称",
        "alias": "example_alias",
        "avatar_url": "https://example.com/avatar/132",
        "avatar_hd_url": "https://example.com/avatar/0",
        "sex": 1,
        "country": "",
        "province": "",
        "city": "",
        "signature": "",
        "supported": true,
        "is_friend": true,
        "source": "wechat_id"
      }
    ],
    "expires_in": 300,
    "native_ret": 0,
    "stage": "search",
    "request_submitted": true,
    "event_id": 42,
    "request_cgi": 106,
    "message_type": 0,
    "transport_error_type": 0,
    "transport_error_code": 0
  },
  "error": ""
}

contacts[] 同时返回本次搜索取得的公开资料，无需先加好友，也不会额外发起资料查询：

以上字段在每个候选中均返回，是否有值取决于微信本次回包及对方公开资料；地区是个人资料填写值，不代表实时位置。它们不改变 supported 或 contact_ref 的规则。

country、province、city、signature 为空字符串时，表示本次搜索未取得对应资料，不影响 status:found；仅凭该结果无法区分对方未设置资料，还是微信搜索回包未提供。

is_friend 来自本地普通好友判断。为 true 时无需再发好友申请，正常调用 add_friend 会返回 already_friend。supported:true 表示候选类型符合当前添加流程，不代表对方是陌生人；已有好友也可能同时返回 supported:true 和 contact_ref。

source 为 wechat_id、phone 或 qq，由微信搜索匹配类型决定。username 是微信原生返回的标识，可能是加密标识，不能一律当成稳定 wxid。多候选由调用方选择；supported:false 的候选没有 contact_ref，不能提交添加。确认未找到时返回 ok:true,status:not_found,contacts:[]；传输错误、解析错误和业务失败返回 ok:false，不能当成“用户不存在”。

添加参数：

{"contact_ref":"fc_example_ref","say_content":"你好，我是某某"}

contact_ref 必填，只能使用本账号本次登录会话的搜索结果；say_content 可省略，默认为空字符串，不接受数字或 null。输入会去除首尾空白，并按微信原生长度规则校验；过长时返回 INVALID_SAY_CONTENT，不会悄悄截断发送。不能直接传 username、scene、opcode 或票据替代引用。好友添加遵循插件发送开关。

添加成功示例：

{
  "request_id": "add_demo_1",
  "command_name": "add_friend",
  "ok": true,
  "result": {
    "status": "request_sent",
    "username": "example_user",
    "is_friend": false,
    "contact_ref": "fc_example_ref",
    "native_ret": 0,
    "stage": "send_verification",
    "request_submitted": true,
    "event_id": 43,
    "request_cgi": 137
  },
  "error": ""
}

引用在插件内存保留 300 秒，最多 50 个；这个时间是本地缓存策略，不代表微信票据寿命。重启、退出登录或账号／上下文变化后必须重新搜索。相同引用及相同规范化消息的并发调用共享操作，完成后在引用有效期内复用结果；消息不同返回 CONTACT_REF_CONFLICT。同目标的另一引用正在添加时返回 ADD_IN_PROGRESS。超时后的相同引用仍返回原结果，不会自动重发。跨引用、跨重启和超过缓存期不承诺去重，后端也应避免重复下发。

两项操作均在当前请求内等待，插件操作期限为 30 秒，调用方建议至少等待 40 秒。native_ret 未取得微信业务结果时为 null；不能把 null 当 0。搜索成功或微信添加成功为 0，部分未找到搜索结果保留微信 -4。stage 为 preparing、search、precheck、add_contact 或 send_verification。request_submitted 只表示搜索／添加请求获原生受理（预检查不单独计入），不代表服务器已成功处理；request_cgi 为当前请求／最近回包的 CGI（搜索 106、添加 137、补取联系人 182、预检查 11568）；搜索的 event_id 为提交返回的 ID，添加为最近原生回调的 ID，尚无回包时为 null。它们仅用于诊断。

常见错误码：INVALID_KEYWORD、INVALID_PARAMETERS、INVALID_SAY_CONTENT、SEND_DISABLED、ACCOUNT_UNAVAILABLE、ACCOUNT_CHANGED、CONTACT_REF_EXPIRED、CONTACT_REF_CONFLICT、ADD_IN_PROGRESS、CANDIDATE_CACHE_FULL、TOO_MANY_REQUESTS、NATIVE_API_UNAVAILABLE、REQUEST_NOT_STARTED、PRECHECK_NOT_STARTED、PRECHECK_FAILED、WECHAT_INTERACTION_REQUIRED、WECHAT_REQUEST_FAILED、SEARCH_FAILED、WECHAT_TRANSPORT_FAILED、RESPONSE_INCOMPLETE、RESPONSE_INVALID、FRIEND_OPERATION_TIMEOUT。微信返回普通 -44 时最多一次进入原生发送验证消息入口；交互限制和预检查失败不会自动继续。

探针接受 {} 或 {"contact_ref":"fc_example_ref"}。它不发送搜索／好友申请，返回 search_runtime、add_runtime（ready 及各 selector 的 compatible/encoding）、logged_in、send_enabled、cached_candidates、pending_operations、contact_ref_valid、expires_in、has_antispam_ticket、reference_status 和 last_operation。last_operation 只保留最近一次操作的状态、阶段、返回码和受理信息；不包含账号、关键词、验证消息或原始票据。出现 NATIVE_API_UNAVAILABLE 时先调用探针定位不兼容项。

已取得用户提供的 HTTP 真机搜索成功回包，确认本次已有好友场景返回头像、大图头像、性别和 is_friend:true，地区及签名为空。用户现已确认搜索与添加好友功能在微信 8.0.80 验证通过；资料字段是否有值仍以微信本次回包为准，人工处理和超时按本节状态规则处理。

-44 和发送状态的判断：stage:add_contact 表示直接添加阶段；request_submitted:true 只表示原生请求受理，不能据此认定验证申请已经发出。新增 verification_attempted 表示是否进入过发送验证消息入口；只有最终 status:request_sent 才表示微信确认验证申请发送成功。旧包在 add_contact 返回 needs_user_action,-44 时可能尚未进入验证消息阶段。

交互条件按现有原生链路判断：spam 提示标题、正文及 ctx 同时非空才要求人工确认；仅存在空的 verifyUserSpamInfo 对象或仅有 ctx，不会拦住普通 -44 的一次验证消息转换。微信原生可处理的 XML 提示、预检查失败及其他明确限制仍停止自动继续。

新增脱敏 failure_detail，保留最近一次错误分类，即使随后发送验证成功也可能保留此前的 verification_required：reason 为 spam_challenge、native_error_dialog、error_xml_unreadable、precheck_failed、verification_required 或 wechat_error；native_ret 为该次错误码；并提供 has_spam_info、has_spam_title、has_spam_detail、has_context、spam_challenge、has_error_xml、xml_show_type、xml_handled、xml_unreadable。不返回原始 ctx、XML、票据或提示文本。最终结果以外层 status/native_ret 为准，不能把历史 failure_detail 当成最终失败。

friend_add_probe 的 last_operation 同时返回 verification_attempted 和 failure_detail；群场景也可在 room_candidate.last_result 查看。该判定和诊断同时用于 add_friend 与 add_room_friend，不新增接口。

成功回包按实际请求区分：CGI137 的 opcode 1（直接添加）仍要求联系人标识；opcode 2（发送验证消息）允许回包缺少用户名，插件继续执行微信原生申请记录保存和成功回调，收到 contactSendRequestOk: 后才返回 request_sent。不会仅凭 native_ret:0 合成成功。旧包在 send_verification 阶段可能将这种正常回包误报为 RESPONSE_INCOMPLETE，并把已取得的 0 丢成 null；该旧结果不能证明服务器拒绝申请，应先核对状态，避免重复发送。

取得 CGI137 回包后，新增可选脱敏 response_detail：native_ret 为本次业务返回码，request_opcode 为实际请求操作码（无法读取时为 null），has_response_username 表示回包用户名是否非空。添加结果、探针 last_operation 及群候选 last_result 均可查看。若微信返回 0 后插件本地校验或后处理失败，外层仍保留 native_ret:0，须同时检查 ok/status/error_code；0 不代表插件已完成全部处理。没有本次回包时不提供该详情；探针未发生操作时为 {}。详情不包含用户名、消息正文或票据。

添加群成员好友

命令为 add_room_friend，参数放在 args；放入 /agent/poll 响应的 commands 数组：

{"request_id":"room_add_demo_1","command_name":"add_room_friend","args":{"room_id":"123456789@chatroom","wxid":"wxid_example_member","say_content":"你好，我们在同一个群里"}}

结果沿用 request_id/command_name/ok/result/error 信封。以下结果示例采用本模式命令信封：外层保留 ok/error，其余业务字段位于 result。friend_add_probe 同样接受 args.room_id 和 args.wxid，且不发送申请。

已知共同群和成员原始 wxid 时，使用独立的 add_room_friend。搜索添加仍为 search_contact → add_friend，不把 wxid 塞进搜索流程，也不要求调用方提供手机号、微信号、scene 或票据。

请求参数：

{"room_id":"123456789@chatroom","wxid":"wxid_example_member","say_content":"你好，我们在同一个群里"}

• room_id、wxid 必填，均为 1–256 字符的字符串，不含空白。只支持普通 @chatroom 群和个人联系人，暂不支持 OpenIM、公众号、群联系人或本人。
• wxid 使用 /room_members／room_members 成员结果的 account_id（原始成员标识），也可使用已取得的原始 wxid；不能传昵称或群昵称。room_id 必须是该成员所在的共同群。
• say_content 可省略，默认为空；仅接受字符串，会去除首尾空白，沿用 add_friend 的原生长度校验，过长拒绝发送。

插件先复用当前账号状态、群联系人和群成员列表入口，确认本人和目标都在该群；再按原生群资料链路请求 CGI182，携带目标和 fromChatRoom，按用户名匹配本次响应的群成员票据。只有取得有效联系人和票据后，才将群 ID、scene 14 和完整联系人交给 add_friend 共用的原生预检／添加执行器；普通 -44 最多一次转换为发送验证消息。调用方无需点击页面，也无需传递原始票据。列表缺失或成员关系未就绪会失败，不自动同步整个群。

命令结果格式示例（省略公共字段，身份字段为示意值）：

{
  "request_id": "room_add_demo_1",
  "command_name": "add_room_friend",
  "ok": true,
  "result": {
    "status": "request_sent",
    "source": "room",
    "room_id": "123456789@chatroom",
    "username": "wxid_example_member",
    "is_friend": false,
    "native_ret": 0,
    "stage": "send_verification",
    "contact_fetch_submitted": true,
    "has_group_member_ticket": true,
    "request_submitted": true,
    "request_cgi": 137,
    "event_id": 42
  },
  "error": ""
}

status 沿用搜索添加的 already_friend、request_sent、added、pending_sync、needs_user_action、timeout、failed；request_sent 仅表示微信确认申请已发送。已有好友不取群票据、不发添加请求。native_ret:null 表示没有可用的微信业务结果。群路径不返回 contact_ref；前置校验失败可能只有公共错误字段。

stage 增加 room_contact。contact_fetch_submitted 仅表示群资料请求获原生受理，has_group_member_ticket 仅表示本次取得的票据非空，二者都不表示好友申请成功。request_submitted 仍仅表示共享添加链路获原生受理，不包含群资料请求和独立预检查。request_cgi／event_id 为当前或最近回包诊断，CGI182 为群资料、11568 为预检查、137 为添加。发生超时、回包不完整或后处理失败时，先核对好友状态，不自动重发。

同一登录会话、同一群、同一成员、相同规范化文字，在首次请求创建起 300 秒内共享在途操作或复用最终结果（包括失败和超时）；不同文字返回 ROOM_ADD_CONFLICT。最多保留 50 个群操作记录；共享在途上限 16 个。同一目标经另一群或搜索路径正在添加时返回 ADD_IN_PROGRESS。跨群、跨重启、切换账号或超过窗口不承诺去重，后端应记录操作结果，避免重复下发。整个流程单次等待，操作期限 30 秒，调用方超时建议至少 40 秒。

群相关错误包括 INVALID_PARAMETERS、ROOM_NOT_FOUND、ROOM_MEMBERS_UNAVAILABLE、NOT_IN_ROOM、CANNOT_ADD_SELF、TARGET_NOT_IN_ROOM、UNSUPPORTED_CONTACT、ROOM_CONTACT_FETCH_FAILED、ROOM_CONTACT_NOT_FOUND、GROUP_MEMBER_TICKET_MISSING、ROOM_ADD_CONFLICT；通用运行时、发送开关、切号、超时、预检及微信限制错误沿用 add_friend。GROUP_MEMBER_TICKET_MISSING 明确表示未发起好友申请，不会退回无来源 wxid 添加。

排障继续使用只读 friend_add_probe（HTTP POST /debug/friend_add_probe），可传：

{"room_id":"123456789@chatroom","wxid":"wxid_example_member"}

新增 room_runtime（群链路签名 ready/checks）、room_preflight（本地成员校验结果或明确错误）、room_candidate（cached/status/has_contact/has_group_member_ticket/last_result）；last_result 为该群成员缓存的完整业务结果，仅在调用过添加后存在。last_operation 增加 source:search|room，仍为脱敏诊断。探针不联网取资料、不发送申请，不返回原始票据。首次使用先检查 add_runtime.ready 和 room_runtime.ready，再检查 room_preflight.ok；添加失败后用同一参数查看阶段与原始返回码。

群内添加好友已由用户在微信 8.0.80 验证通过；受限／人工处理和重复请求仍按本节约定处理。

delete_friend / delete_session / quit_group

{ "id": "…" }

12.5 群昵称、群名、公告与群二维码

kick_group_member

{ "room_id": "…", "member_ids": ["wxid_a", "wxid_b"], "member_count": 2 }

member_id 与 member_ids 可同时传，自动合并去重。

rename_group / set_group_self_nickname（同一命令的两个名字）

修改当前账号在该群里的群昵称（微信里「我在本群的昵称」），不是修改群名称。

{ "room_id": "…", "new_name": "我在本群的新昵称" }

new_name 允许空串，表示清空群昵称、恢复默认（显示微信昵称）：

{ "room_id": "…", "new_name": "" }

返回：{"room_id": "…", "new_name": "", "clears_group_nickname": true}。整个字段缺失才报 new_name is required。

set_group_name

修改整个群聊的名称。与上面的群内个人昵称命令不同，room_id 必须是以 @chatroom 结尾的字符串，new_name 必须是去除首尾空白后非空的字符串；不支持传空串清空群名。

下发时使用 command_name: "set_group_name"，args 示例：

{ "room_id": "123456@chatroom", "new_name": "新的群聊名称" }

成功时，命令结果信封的 result 示例：

{
  "room_id": "123456@chatroom",
  "new_name": "新的群聊名称",
  "accepted": true,
  "local_verified": true,
  "already_named": false,
  "local_name": "新的群聊名称"
}

accepted 只表示微信底层接受；local_verified 表示本机群联系人的 nick_name 已读回目标值。ok: true 时 local_verified 仍可能为 false。如果本地群名已是目标值，返回 ok: true、already_named: true、accepted: false、local_verified: true，不重复提交。以上结果不代表其他成员端已经同步。

失败时结果信封的 ok: false，error 为具体原因，result 保留请求字段和状态字段。只读探针命令 set_group_name_probe 的 args 只需 room_id；它不修改群名，需检查结果中的 set_group_name_ready，不能只看信封的 ok。

get_group_notice

args 只需 {"room_id":"123456@chatroom"}。成功时 command_result.result 示例：

{
  "room_id": "123456@chatroom",
  "cached_notice_found": true,
  "summary": "微信提供的文本摘要",
  "html": "<p>公告正文</p>",
  "html_cached": true
}

summary 只是微信提供的文本摘要；html 是本地缓存文件中的完整原始 HTML。正文文件未缓存或无法读取时，html 为 null、html_cached 为 false，仍可能有摘要。本地未读到公告项时，cached_notice_found 为 false，summary 和 html 均为 null；这不能证明群里没有公告。接口不触发下载或发布，缓存也可能不是最新内容。请求失败时看结果信封的 ok: false 和 error。

get_chatroom_qrcode：阻塞获取指定群二维码

每次调用按微信原生协议创建独立请求，通过当前登录会话的 EventService 发起取码，在同一次调用中等待微信本次响应；不返回查询中状态，不需要任务 ID。同群并发共用正在处理的请求，完成后再次调用会重新取码。最多 32 个不同群的待处理请求，约 30 秒超时，接口等待保护上限约 31 秒；调用方超时建议至少 40 秒。

唯一参数 room_id 必须是实际群 ID 字符串，例如 example@chatroom，不能传群名。当前账号须能找到该群联系人，最终权限以微信响应为准。

status=ok 表示本次业务响应成功且取得二维码内容，不能保证扫码立即入群。restricted 对应微信非零二维码状态，业务 ok=false，error 提供中文分类说明；具体原因可能在可读文本字段或返回图片中；即使有图或 URL 也不作为普通成功处理。没有恢复具体状态枚举，不写死“1=超员、2=开启验证”。网络失败、微信 ret != 0、响应不完整和超时均返回失败信息，不返回旧缓存的码。

人数阈值由微信配置控制（静态样本默认 200，客户端判断人数达到阈值）；开启管理员进群验证也不一定禁止取码，新管理方式可以扫码申请审批。因此不按人数或验证开关在本地直接拒绝，以本次微信原码与文案为准。

普通群可能只有 URL，没有服务器图片；调用方可用 qr_code_url 自行生成二维码，无需手机下载再上传。接口不会读取微信磁盘缓存，也不返回本地文件路径。微信保存的完整分享卡片还会组合群头像、群名和有效期提示，本接口不拼装该卡片。

OpenIM 按微信原生群类型判断分流至 CGI890；该分支可能只有图片，没有 URL，也没有二维码状态，此时 qrcode_status、restricted 为 null。仍校验本次原始业务响应，不能依赖原生固定为 0 的完成通知。

常见 error_code：INVALID_ROOM_ID、ACCOUNT_UNAVAILABLE、ACCOUNT_CHANGED、ROOM_NOT_FOUND、NATIVE_API_UNAVAILABLE、TOO_MANY_REQUESTS、REQUEST_NOT_STARTED、NATIVE_REQUEST_FAILED、RESPONSE_INVALID、WECHAT_REQUEST_FAILED、RESPONSE_INCOMPLETE、QRCODE_RESTRICTED、QRCODE_TIMEOUT。REQUEST_NOT_STARTED 仅在原生事件服务返回事件 ID 为 0 时使用，不能据此推断群人数或验证限制。request_submitted=true 仅表示微信事件服务已受理，不代表服务器成功；若之后返回 QRCODE_TIMEOUT，表示尚未取得本次最终响应。

中文原因取自微信可读字段：footer_wording 和 wechat_error_message。受限时优先使用非空 footer_wording 作为 error；没有该文案时返回通用中文“微信返回二维码受限状态”，并原样保留 wechat_error_message。微信可能将具体原因直接写在返回图片里，两个文本字段均为空；本接口不做图片文字识别，也不根据 qrcode_status=1 等原始值硬编码具体原因。

用户提供的普通群真机响应已确认：请求受理并收到 wechat_ret=0，qrcode_status=1，返回 PNG，qr_code_url=null，footer_wording、wechat_error_message 均为空；人工查看图片文字为“该群已开启进群验证，只可通过邀请进群”。这只说明该次图片的含义，不是所有状态值 1 的固定映射。

has_qrcode、has_image、restricted、request_submitted 可能序列化为布尔值或数字 0/1，restricted 还可能为 null。has_image=1、has_qrcode=1 只表示有返回内容，不保证图片是可用的入群码。业务是否成功应先检查 ok 和 status。

群二维码功能已由用户在微信 8.0.80 验证通过；取码成功不保证立即入群，实际扫码仍受群设置及微信返回限制。上述受限图片记录不构成固定状态码映射，也不能据此扩大 OpenIM 支持范围。

受限响应示例（节选；群 ID 和事件 ID 为占位值，实际 image_base64 是 PNG Base64 字符串，本文省略图片内容）：

{
  "request_id": "group-qr-001",
  "command_name": "get_chatroom_qrcode",
  "ok": false,
  "result": {
    "room_id": "example@chatroom",
    "status": "restricted",
    "qr_code_url": null,
    "has_qrcode": 1,
    "has_image": 1,
    "image_mime_type": "image/png",
    "qrcode_status": 1,
    "restricted": 1,
    "footer_wording": "",
    "wechat_ret": 0,
    "wechat_error_message": "",
    "message_type": 0,
    "transport_error_type": 0,
    "transport_error_code": 0,
    "request_submitted": 1,
    "request_cgi": 168,
    "event_id": 42,
    "error_code": "QRCODE_RESTRICTED"
  },
  "error": "微信返回二维码受限状态"
}

下发一次命令：

{
  "commands": [
    {
      "request_id": "group-qr-001",
      "command_name": "get_chatroom_qrcode",
      "args": {
        "room_id": "example@chatroom"
      }
    }
  ]
}

最终结果示例（省略公共身份与时间字段）：

{
  "request_id": "group-qr-001",
  "command_name": "get_chatroom_qrcode",
  "ok": true,
  "result": {
    "room_id": "example@chatroom",
    "status": "ok",
    "qr_code_url": "https://weixin.qq.com/g/example",
    "has_qrcode": true,
    "has_image": false,
    "image_base64": null,
    "image_mime_type": null,
    "qrcode_status": 0,
    "restricted": false,
    "footer_wording": "",
    "wechat_ret": 0,
    "wechat_error_message": "",
    "message_type": 0,
    "transport_error_type": 0,
    "transport_error_code": 0,
    "request_submitted": true,
    "request_cgi": 168,
    "event_id": 42
  },
  "error": ""
}

ok、error 在命令信封外层，result 保留原始状态、错误码与文案。调用方等待最终命令结果的期限建议至少 40 秒；长轮询的 /agent/poll 请求仅用于命令投递，其超时不等于命令完成期限。两个查询按账号会话合并在途请求，支付姓名复用终态缓存，群二维码每次重新取码，不使用仅按 request_id 保存的通用旧结果。长轮询按原有批次顺序等待本条结果并上报成功后继续下一条。

12.6 红包与转账

确认收款

receive_transfer 参数 transfer_id、message_id 均为 string，至少一项非空；推荐两个都传且对应同一笔转账。结果使用本模式的 command_result 信封，ok、error 位于外层，精简业务字段位于 result。进入收款业务后的失败同样保留这些字段；插件／发送开关、权限或队列等前置拒绝沿用通用失败信封，不保证业务字段齐全。

收到正常确认收款回包的结果示例（省略公共设备／会话字段）：

{
  "request_id": "receive_example_1",
  "command_name": "receive_transfer",
  "ok": true,
  "result": {
    "transfer_id": "transfer_example",
    "message_id": "message_example",
    "status": "callback_ok",
    "accepted": true,
    "confirmed": true,
    "callback_received": true,
    "ret_code": 0
  },
  "error": ""
}

命令等待原生回包约 5 秒。status="confirm_invoked" 表示已发起收款、等待已超时，返回外层 ok=true，业务字段为 accepted=true, confirmed=false, callback_received=false, ret_code=null，不能认定到账。callback_received 仅是辅助信号；匹配实际确认收款回包且成功时为 callback_ok，或独立查询取得原生状态 2001 后为 confirmed，才会得到外层 ok=true, result.confirmed=true。

收到回包却缺少合法返回码时，失败结果示例：

{
  "request_id": "receive_example_1",
  "command_name": "receive_transfer",
  "ok": false,
  "result": {
    "transfer_id": "transfer_example",
    "message_id": "message_example",
    "status": "callback_unknown",
    "accepted": true,
    "confirmed": false,
    "callback_received": true,
    "ret_code": null
  },
  "error": "转账回调缺少状态码，收款结果未知，请勿自动重试"
}

callback_unknown 或等待超时应先用 get_transfer_status 查询，原生状态 2001 才确认已收取；不要直接重试。接收与退还同笔互斥，未知结果先查终态。

业务结果不再包含整份 content／content_xml、native_url、callback、pay_info_probe 或 runtime_probe。排错可使用本模式已有的 transfer_probe 命令，args 传 transfer_id／message_id，或通过 bridge_status 读取完整诊断；探针和诊断快照不能代替业务成功判断。

转账：退还与查询状态

命令：refund_transfer 退还待收取转账；get_transfer_status 只查询服务器资金状态，均已加入 capabilities。退还要求插件和发送开关开启；查询不受发送开关限制，仍需通过本模式配置、鉴权和插件全局校验。

服务端放入 POST /agent/poll 响应的命令项示例；查询时只把 command_name 改为 get_transfer_status，使用新的外层 request_id。poll 响应的其余配置字段按本文第 8 节：

{
  "commands": [
    {
      "request_id": "refund_example_1",
      "command_name": "refund_transfer",
      "args": {
        "transfer_id": "transfer_example",
        "message_id": "message_example"
      }
    }
  ]
}

结果沿本模式 command_result 外壳，ok、error 放外层，其他基础字段（包括 error_code）保留在 result；下面省略公共设备／会话字段。失败也要读取 result，不能从 diagnostics 猜测结果。

{
  "request_id": "refund_example_1",
  "command_name": "refund_transfer",
  "ok": true,
  "result": {
    "transfer_id": "transfer_example",
    "message_id": "message_example",
    "accepted": true,
    "confirmed": false,
    "status": "refund_pending",
    "native_status": null,
    "ret_code": null,
    "error_code": ""
  },
  "error": ""
}

{
  "request_id": "query_example_1",
  "command_name": "get_transfer_status",
  "ok": true,
  "result": {
    "transfer_id": "transfer_example",
    "message_id": "message_example",
    "accepted": false,
    "confirmed": false,
    "status": "waiting_receive",
    "native_status": 2000,
    "ret_code": 0,
    "error_code": "",
    "can_refund": true,
    "status_description": "等待收款",
    "native_status_name": "waiting_receive"
  },
  "error": ""
}

{
  "request_id": "refund_example_1",
  "command_name": "refund_transfer",
  "ok": true,
  "result": {
    "transfer_id": "transfer_example",
    "message_id": "message_example",
    "accepted": true,
    "confirmed": true,
    "status": "refunded",
    "native_status": 2002,
    "ret_code": 0,
    "error_code": ""
  },
  "error": ""
}

{
  "request_id": "refund_example_1",
  "command_name": "refund_transfer",
  "ok": false,
  "result": {
    "transfer_id": "",
    "message_id": "",
    "accepted": false,
    "confirmed": false,
    "status": "failed",
    "native_status": null,
    "ret_code": null,
    "error_code": "CACHE_NOT_FOUND"
  },
  "error": "转账上下文已失效，请使用本次运行收到的转账消息"
}

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

范围与前置条件：本轮源码支持当前登录账号作为收款人的普通微信个人转账（app_msg_type=2000），包括普通微信群内他人指定给当前账号的个人转账；不包括群收款／AA、企业互通群、任一方为 @openim 的交易、已收取后的退款或部分金额退还。群内转账须能读取原消息的个人付款人、接收人及群 ID，并确认本地群联系人属于普通微信群；群资料缺失或类型无法确认时仍拒绝。查询与退还都依赖本次运行收到的原转账消息，并要求缓存包含付款人、交易编号和已明确读取的非负整数有效期（允许 0，不等同于字段缺失）；本版不提供按历史交易号恢复上下文的入口。上下文按当前账号保存在内存中，最多 120 笔；重启、账号会话变化或淘汰后可能返回 CACHE_NOT_FOUND，持久化 ID 不能恢复该缓存。

请求参数：两个接口使用同一组参数，无其他业务输入；不能补传付款人、金额、交易号或有效期绕过原消息核验。

可以省略未提供的字段；不得传数字、null、数组或对象。去除首尾空白后两个字段都为空时失败；同时提供时必须指向同一笔，否则 ID_MISMATCH。

结果字段：下表说明业务结果，外层封装按本节本模式的示例读取。进入业务服务后固定返回这些基础字段；通道鉴权、插件禁用等更早的拒绝可采用本模式通用错误外壳，不能假设总有业务字段。

查询结果还可能返回 can_refund（boolean）、status_description（string）和 native_status_name（string，微信回包原生名称，可能为空）；微信错误回包可能带 wx_error_type（integer 或 null；回包未提供时为 null）。can_refund=true 仅表示服务器状态待收取、普通交易、双方匹配且无同笔未决收款／退还占用；不包含发送开关，也不保证后续风控允许退还。

成功判定与等待：只有 status="refunded" 且 native_status=2002 才代表已退还。ok=true、accepted=true、HTTP／命令传输成功或收到事件，均不能单独作为退还成功判据。两个新操作在当前请求／命令中短等待约 5 秒；排队、主线程调度和网络时间另计，客户端建议至少等待 15 秒。预检／查询超时且未提交时返回 QUERY_TIMEOUT, accepted=false；已提交但仍无终态时返回 refund_pending, accepted=true。提交后的确认查询可能返回 WECHAT_ERROR, accepted=true，仍须继续查询，不能认定退还确定失败。

重试与互斥：同一笔转账的接收与退还互斥，未决操作会返回 TRANSFER_BUSY；结果未知时保留占用，查询到终态后可回收占用。退还请求被微信明确拒绝才解除该退款提交的占用。重复调用不是按 request_id 持久幂等：ID 用于定位同笔转账，通道 request_id 只关联命令结果。网络超时、refund_pending、refund_unknown 或 accepted=true 的失败，都应先调用状态查询，不要改 ID、重启或自动重提退还／收款。未决保护不保证跨进程或跨账号会话延续。

业务错误码：失败保留结构化结果，不要只记录错误文字。

验证范围（2026-11-04）：用户确认验证通过。已回传普通个人转账查询由 waiting_receive / native_status=2000 / can_refund=true 到退还后 refunded / native_status=2002 / accepted=true / confirmed=true 的真机结果，并提供接收转账 callback_ok / ok=true / accepted=true / confirmed=true 的成功回包。正常查询、接收与退还业务链路已有历史真机记录。用户现已确认转账相关功能在微信 8.0.80 验证通过；重复操作、网络异常与账号切换仍按本节状态和重试规则处理。

退款完成／失败／未知时还可能收到 transfer_refund_result 事件；事件不可替代主动查询。

12.7 个人资料设置与地区代码

clear_gender_region

{ "fields_cleared": ["sex", "country", "province", "city"], "restart_recommended": true }

资料设置与地区代码查询

上述 9 个命令由长轮询与 WebSocket 的共享分发器执行，复用已通过 HTTP 真机测试的原生资料链。资料写命令要求发送开关开启；地区查询和探针不要求发送开关。均受命令通道的插件授权/启用检查。头像仍延后，没有头像写命令。

写入参数：

资料字段采用严格 JSON 类型：sex 只接受整数 0/1/2，拒绝布尔值、小数（包括 1.0）、字符串、null 和越界值。文本必须是字符串，未知字段拒绝。未提供的资料字段保持原值；单字段命令只接受各自字段。地区整组替换，省市缺失就清空；子级不能脱离父级。region_code 和 region 不可同时传，空代码或空对象清空地区。

签名保留原始空白，微信原生加权计数最多 30：ASCII UTF-16 单元权重 1，其他单元权重 2，总权重/2 向上取整；例如 30 中文或 60 ASCII 可通过。超限拒绝、不截断。拍一拍不能放进 profile_update，需独立提交；其文本按微信原生规则处理空白/换行、计数和禁止字符。限制动态读取，本次真机上限 10、禁止字符 <>/，以 profile_pat_suffix_probe 的 capabilities.max_length 和 capabilities.forbidden_characters 为准。

地区代码查询：

1. profile_region_codes，args:{} 或 {"parent_code":""}：查询国家/地区列表。
2. 从 result.items[].code 取得国家代码，如 CN，传 {"parent_code":"CN"} 查询省级。
3. 从省级列表取得 CN_Guangdong，传 {"parent_code":"CN_Guangdong"} 查询市级。
4. 取得完整代码 CN_Guangdong_Shenzhen 后，用 profile_region 设置 region_code。

result 示例（仅展示一项）：

{
  "parent_code": "CN_Guangdong",
  "count": 1,
  "items": [{"code":"CN_Guangdong_Shenzhen","name":"深圳","parent_code":"CN_Guangdong","type":2}],
  "selector_probe": {}
}

count 为实际列表数量；code 是完整代码，name 随微信语言变化，type 取不到时为 null。不要拼中文名称；叶节点或不存在的父代码可能返回空列表。profile_region_probe 复用同一查询能力。

提交与完成状态：

• 性别/地区/签名结果的 status 为 submitted 或 unchanged；accepted 是微信受理，local_verified 是本地读回，server_confirmed:false。最终展示以微信为准。失败时 result 保留受理状态和读回值，错误信息在信封顶层 error。submitted_with_error 可能已入队，先核对状态再处理。
• 拍一拍立即返回 result.status:"pending"、operation_id、数字 event_id、requested、normalized、length、max_length 等；顶层 ok:true 只表示提交受理。duration_ms 不包含后续等待微信服务器的时间。
• 随后用 新的 request_id 下发 profile_pat_suffix_probe、args:{}，检查 result.last_operation。status:"succeeded" 且 server_confirmed:true 才是服务器确认；failed 查看内部 error；unknown 表示 120 秒无回调或提交后异常，不要盲目重试。pending 期间拒绝第二项修改。
• 结果只通过探针查询，不会再主动推送一条拍一拍完成的 command_result。相同 request_id 会复用已缓存的初次结果，即使原操作后来完成也仍可能拿到 pending；每次状态查询必须生成新的 ID。
• 只保留最近一次拍一拍操作，重启微信后记录消失。用 operation_id / event_id 对照本次结果；该数字 event_id 是微信 oplog ID，与消息事件的去重键不同。

profile_probe 和 profile_pat_suffix_probe 可传候选参数预校验，返回 validation.valid、normalized、error、writes_performed:false，不会提交。探针顶层 ok:true 只说明查询执行完毕，应继续检查 profile_ready、pat_suffix_ready 或 validation.valid。

下发示例：

{
  "commands": [
    {
      "request_id": "req-region-codes-001",
      "command_name": "profile_region_codes",
      "args": {
        "parent_code": "CN_Guangdong"
      }
    }
  ]
}

拍一拍状态查询时更换 request_id 和 command_name，args 置空：

{
  "commands": [
    {
      "request_id": "req-pat-status-002",
      "command_name": "profile_pat_suffix_probe",
      "args": {}
    }
  ]
}

批量设置资料的完整 poll 响应：以下 JSON 由服务端作为 POST /agent/poll 的响应体返回。

{
  "commands": [
    {
      "request_id": "req-profile-update-001",
      "command_name": "profile_update",
      "args": {
        "sex": 2,
        "region_code": "CN_Guangdong_Shenzhen",
        "signature": "今天也要开心"
      }
    }
  ]
}

对应的资料提交结果：插件向服务端 POST /agent/command_result 上报，示例中本地读回匹配目标值。

{
  "device_id": "webridge_device_xxxx",
  "session_id": "sess_xxx",
  "account_id": "wxid_self",
  "runtime_version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080",
  "ts_ms": 1791936000000,
  "request_id": "req-profile-update-001",
  "command_name": "profile_update",
  "ok": true,
  "duration_ms": 120,
  "result": {
    "accepted": true,
    "status": "submitted",
    "local_verified": true,
    "server_confirmed": false,
    "requested": {"sex":2,"country":"CN","province":"Guangdong","city":"Shenzhen","signature":"今天也要开心"},
    "before": {"sex":0,"country":"","province":"","city":"","signature":"","current_user":"wxid_self"},
    "current": {"sex":2,"country":"CN","province":"Guangdong","city":"Shenzhen","signature":"今天也要开心","current_user":"wxid_self"},
    "changed_fields": ["city", "country", "province", "sex", "signature"],
    "readback_error": "",
    "message": "资料已提交微信同步队列；本地读回不代表服务器确认"
  },
  "error": ""
}

资料操作失败时，命令信封顶层为 ok:false，具体错误在顶层 error，result 继续保留可取得的受理状态和读回值。探针预校验不通过时，探针命令本身仍可能 ok:true，应检查 result.validation.valid 和 result.validation.error。部分原生判断会以 0/1 输出，客户端应按布尔语义读取。

12.8 状态查询与后台保活

account_status

{
  "is_logged_in": true,
  "account_id": "wxid_self",
  "user_name": "wxid_self",
  "display_name": "测试账号",
  "remark": "",
  "alias": "",
  "nick_name": "测试账号",
  "avatar_url": "",
  "sex": 0,
  "province": "",
  "city": "",
  "signature": "",
  "mobile": "",
  "country": "",
  "email": "",
  "has_profile_data": true,
  "wechat_version": "8.0.80"
}

device_status

命令无参数（args:{}），外层 ok/error 按命令结果信封判断；成功时 result 示例：

{
  "ts_ms": 1780018858960,
  "version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080",
  "device": {
    "ios_version": "16.1.1",
    "device_model": "iPhone14,3"
  },
  "process_memory": {
    "phys_footprint_mb": 537.1,
    "resident_mb": 753.5,
    "internal_mb": 296.2
  },
  "system_memory": {
    "available_estimate_mb": 1411.6,
    "used_estimate_percent": 74.9,
    "physical_total_mb": 5618.6
  },
  "battery": {
    "percent": 89,
    "state": "unplugged"
  },
  "power": {
    "low_power_mode": false
  },
  "thermal": {
    "state": "nominal",
    "raw": 0
  },
  "network": {
    "connected": true,
    "network_type": "wifi",
    "cellular_generation": ""
  },
  "application": {
    "state": "background",
    "foreground": false,
    "active": false,
    "background": true
  }
}

⚠️ 内存字段请用字节版或 MB 版，不要自己换算：process_memory 和 system_memory 都同时提供字节与 MB 两份，MB 版是 字节 / 1024 / 1024。 ⚠️ system_memory 里的 available_estimate 是估算值（空闲 + 非活跃 + 推测 + 可回收），插件自己在 note 字段里也写了"仅作趋势参考"。

字节与 MB 字段同时提供，MB 为字节除以 1024²。system_memory.available_estimate_* 仅作趋势参考，不是系统可用内存的精确承诺。

bridge_status

插件的完整诊断快照，含数百个动态字段。用途是排障，不要依赖其中任何字段做业务判断。里面包含 version、build_marker 以及内部运行诊断（含长轮询自己的运行状态：agent_registered、agent_last_poll_success、agent_consecutive_failures、最近一次命令的 request_id 与结果等）。

保活诊断与测试：通过已有命令获取共享状态，无参数。将以下命令放入服务端 /agent/poll 的响应：

{
  "commands": [
    {
      "request_id": "req-keepalive-status-001",
      "command_name": "bridge_status",
      "args": {}
    }
  ]
}

在插件随后 POST 到 /agent/command_result 的 result 中读取下表字段，均带 background_keepalive_ 前缀；表中为省略前缀后的名称。例如策略的完整路径为 result.background_keepalive_strategy。每次查询使用新的 request_id；这些字段不会因开启保活就自动周期上报。

设置页“后台保活”默认关闭，“音频保活”默认开，“持续定位保活”默认关。开启微桥及保活总开关，在微信前台开启定位并等待有效回调后转后台；仅请求“使用 App 期间”权限，无需修改 IPA。

按以下顺序验证，并在每组测试中实际执行一条文本命令和检查一次消息事件上报：

1. 单定位：关音频、开定位；后台预期 strategy=location、active=true、location_active=true、audio_playing=false。
2. 单音频：关定位、开音频；后台预期 strategy=audio、active=true、audio_playing=true、location_updates_requested=false。
3. 双开：两路都开且定位已有效；后台预期 strategy=audio+location。通话时音频可能让出，定位有效时策略可暂变为 location，挂断后观察恢复。
4. 关闭总开关：子开关保留选择并置灰；预期 enabled/active/timer_active/audio_playing/location_updates_requested/location_active 均为 false、strategy=stopped。再次开启后按保留配置运行。

该命令读取共享快照，不会强制刷新保活状态或启动通道，结合 last_state_update_at 判断时效。相隔 30 秒、2 分钟、10 分钟采样，比较后台 last_check_at、回调时间和业务结果；查询成功或一次 location_active=true 都不能证明此前持续运行。两路同属微信进程，系统结束微信时都会停止。

需要即时刷新保活及内存时，可从能访问手机的电脑调用 GET http://手机IP:19088/debug/keepalive_status，该接口的字段位于 keepalive，去掉上述前缀；没有 keepalive_status 长轮询命令。完整设备内存使用已有 device_status 命令。当前源码的构建标记为 webridge_build_20261106_settings_update_8080；保活与专用诊断已由用户在微信 8.0.80 验证通过；长期锁屏、通话及低内存下的运行仍受系统调度影响。详细采样及失败排查见 巨魔后台保活测试说明（资料未收录）。

12.9 本地 HTTP 专用入口与本模式限制

不要把 HTTP 路径直接放入 command_name。未支持的名字返回 unsupported command_name。下载成功仅准备手机文件；后端要取得字节，应继续调用 upload_message_media，无需后端能直连手机。

13. 好友备注、星标和黑名单

通过 command_name 使用下表同名命令，参数原样放入 args；WebSocket 和长轮询共享分发器。

仅支持已登录账号的普通微信好友，id 必须是其真实 user_name / wxid。不支持自己、群、公众号、系统号、OpenIM 或已注销好友；已拉黑的好友仍可取消黑名单。沿用鉴权和发送开关，拒绝未知字段。

remark 必须显式传入字符串，使用微信 formatter 规范化，再按微信 charLength <= 32 校验，超限拒绝；这不是通用 Unicode 字符数限制。starred / blacklisted 必须显式传入 JSON 布尔值，0/1、"false"、null、缺省均拒绝。相同目标值返回 unchanged，不再次提交原生修改。

accepted 仅代表原生 BOOL 返回成功；sync_requested 仅说明已进入原生同步调用路径，不保证入队成功。local_verified 是本地联系人回读；server_confirmed 固定 false，当前实现不等待服务器 ACK。ok=true 不保证另一台设备已同步，unknown 不宜自动重提。

响应中的 remark / starred / blacklisted 是请求目标值（备注为规范化值），不是失败后的实际值；非法或缺失字段可能使用空串／false 占位，必须结合 ok / status。联系人摘要在 getter 可读时附带 is_starred / is_blacklisted，未知则省略。原有 remark / display_name 继续可读，清空备注后显示名回退昵称。

好友设置已由用户在微信 8.0.80 验证通过；Unicode 长度限制及断网／跨设备同步仍按本节约定和微信实际状态处理。

下发的命令对象示例（外层任务结构沿用本协议）：

{"request_id":"friend_star_001","command_name":"set_friend_star","args":{"id":"wxid_example","starred":true}}

响应沿用命令结果信封：ok / error 位于外层，result 包含 id、目标字段及其余状态字段。失败时同样保留 result，不能只按外层 ok 丢弃 unknown 的状态信息。

14. 创建群聊、直接加人和发送入群邀请

命令为 create_group、add_group_member、invite_group_member，均已加入能力清单；邀请保留 group_invite_member 别名。沿用本篇连接／注册鉴权和命令信封，以下完整列出业务约定。

三项操作分别表示创建普通微信群、尝试直接加入群成员、发送需要对方接受的入群邀请。插件不按“40 人”硬切换，也不把添加失败自动转成发送邀请；是否可直接加入取决于微信服务端和群设置。所有结果均须查看业务状态，原生方法返回成功不等于成员已经入群。2026-10-29 用户通过 Apifox 完成 HTTP 真机联调：两位好友建群、直接添加已在群成员、移出后重新直接添加、邀请已在群成员、移出后发送邀请，五项结果均符合预期。邀请成功仅确认发送，不代表对方已接受。用户现已确认建群、添加与邀请成员功能在微信 8.0.80 验证通过。是否可直接加人仍由微信与群设置决定，审批、部分成功、超时及账号切换按本节状态处理。request_submitted 为布尔值。

使用范围与完整参数

必须已登录并开启插件写入／发送开关。待操作对象必须是当前账号的普通微信好友，传真实内部 ID；不支持昵称、完整微信号 alias、企业微信用户或群 ID 充当成员。添加和邀请只支持普通 @chatroom 群，并须能从当前群成员快照确认本人在群；无须由插件预设“只有群主能加人”，实际权限和人数限制由微信返回。

request_id 去除首尾空白后须为 1–128 个字符；成员和群 ID 也去除首尾空白，内部不能含空白。成员去重后按 ID 排序。创建时自动排除本人；至少两位其他好友是本接口首版支持范围，不是对微信服务端所有建群方式最低人数的断言。创建不接受 topic／群名，群创建后如需命名，使用已有 set_group_name，其结果独立判断。

添加／邀请先排除本机快照中已在群的成员，只向微信提交剩余普通好友；已在群者放入 already_in_room_member_ids。全部已在群时返回 already_in_room，不提交新请求；仅本机快照确认，server_confirmed:false。若任一待提交成员不是普通好友，整次请求在提交前失败，不偷偷跳过该人。

邀请保留单值别名 user_name／wxid、数组别名 user_names／wxids；可以和 member_id／member_ids 同时提供，合并、校验、去重排序。群 ID 可用 chatroom_id／group_id／to_user_name，同时传多个群字段时规范化后须一致。创建和添加不支持这些旧别名，也不允许同时传多个成员字段。未列出的参数直接拒绝，不静默忽略；null 不能代替字符串或数组。

返回字段与成功判断

下表列出进入群操作服务后的完整业务字段；ok／error 所在位置见本节通道说明。服务内初始失败可能尚未解析到成员或群 ID，因此对应字段为空。message、error、error_code 和 replayed 为按情况出现的字段。命令信封、插件开关、队列容量等前置拒绝尚未进入群操作服务，result 可能为空或只有部分字段；例如 args.request_id 冲突只返回 status 和 error_code，此时不要假定成员或提交状态字段存在。

逐成员 status 可能为 added、already_in_room、requires_invitation、requires_verification、approval_pending、failed、unknown。原生 native_status=0 不能独立判断加入成功，必须与总返回码共同解释：例如添加回包 wechat_ret=-2012 表示需要邀请的分支，-2028 可表示等待群主／管理员确认。wechat_ret=-2012 下 native_status=3 表示拒绝加入，逐成员为failed；状态10含义尚不能确认，保留unknown。创建成功但成员信息不完整时仍返回 created，相关成员为unknown、all_members_added:false。正常邀请回包只确认批次发送，member_results:[]；全部目标已在群而未发送时可返回逐人的 already_in_room。

错误、等待、去重与重试

服务等待真实回包约30秒，外层等待保护约31秒；客户端建议至少40秒，iOS挂起、通信排队或断线可能更久，不能把连接超时直接当业务失败。该能力不新增完成事件或单独查询接口；迟到回包会更新当前进程内记录，使用原接口／命令、原ID和相同规范化参数读取即可。

三种接入方式共用当前账号登录上下文内的操作记录。登记后相同ID、相同操作／群／去重排序成员／reason只读取记录，不再次提交；在途返回processing，结束后返回当前结果并带 replayed:true。同ID不同参数返回冲突。参数或环境校验阶段尚未登记的失败不等于已建立去重记录。新业务必须用新ID；同ID只能查询／重放原业务，不用于强制重新执行。

最多保留512项已登记操作，达到上限拒绝新操作，不按最近条目淘汰。添加操作只要仍有待添加成员结果为 unknown，即使回包字段齐全或顶层为 partial，也继续占用同群操作槽位，并等待迟到回包；已知结果与未知结果混合时逐人处理，不能据此重发整批。唯一可继续的同群操作是显式邀请：新邀请的全部目标必须属于该未完成添加记录的 invite_required_member_ids 已确认名单，并使用新的业务ID；不在名单内的邀请和其他添加仍返回OPERATION_BUSY，原添加记录继续等待。只有成员结果完整且均已明确，才解除该添加占用。邀请本身结果未知也保留同群占用，上述例外不会绕过其他未完成的邀请。建群尚未取得有效新群ID时的未知结果会占用当前账号建群槽位；已取得有效新群ID则返回 created 并解除建群占用，成员部分未知也不能重复创建原业务群。记录仅在当前微信进程和登录上下文内有效，进程重启、重新登录或服务上下文变化（含群服务重新初始化）后不保证去重；不要通过重启或换ID绕过未知结果。后端应保存业务ID及收到的结果，跨重启先核实群状态，再由业务决定下一步。

本模式封装与调用示例

request_id 必须在命令信封提供；args.request_id 可以省略，若提供必须与信封ID一致。参数置于args。外层 ok／error 为业务结果，其他字段置于 result，其中不再重复 ok／error；失败码读取 result.error_code。

这些命令及邀请别名绕过通用“最近100条”命令缓存，由群操作服务执行账号校验、参数冲突检查及上述512项记录规则；本节不适用“失败后换新ID自动重试”的通用建议。

在 /agent/poll 响应的commands数组交付命令；插件顺序处理批次，当前命令完成并上报结果后才推进下一项。poll请求的等待时间不等于此业务完成期限。下例为直接添加：

{
  "commands": [
    {
      "request_id": "req-add-001",
      "command_name": "add_group_member",
      "args": {
        "room_id": "123456789@chatroom",
        "member_id": "wxid_member_a",
        "reason": ""
      }
    }
  ]
}

创建和邀请使用同一信封，替换command_name和args如下：

{
  "request_id": "req-create-001",
  "command_name": "create_group",
  "args": {
    "member_ids": [
      "wxid_member_a",
      "wxid_member_b"
    ]
  }
}

{
  "request_id": "req-invite-001",
  "command_name": "invite_group_member",
  "args": {
    "room_id": "123456789@chatroom",
    "member_ids": [
      "wxid_member_a"
    ]
  }
}

建群成功示例（字段格式示例，不是真机记录）：

以下省略公共设备／时间字段，由插件POST到 /agent/command_result：

{
  "request_id": "req-create-001",
  "command_name": "create_group",
  "ok": true,
  "error": "",
  "result": {
    "status": "created",
    "mode": "create",
    "request_id": "req-create-001",
    "room_id": "123456789@chatroom",
    "member_ids": [
      "wxid_member_a",
      "wxid_member_b"
    ],
    "member_count": 2,
    "submitted_member_ids": [
      "wxid_member_a",
      "wxid_member_b"
    ],
    "already_in_room_member_ids": [],
    "accepted": true,
    "request_submitted": true,
    "response_received": true,
    "server_confirmed": true,
    "request_cgi": 119,
    "event_id": 42,
    "wechat_ret": 0,
    "wechat_error_message": "",
    "message_type": 0,
    "transport_error_type": 0,
    "transport_error_code": 0,
    "created": true,
    "all_members_added": true,
    "member_results": [
      {
        "member_id": "wxid_member_a",
        "status": "added",
        "native_status": 0
      },
      {
        "member_id": "wxid_member_b",
        "status": "added",
        "native_status": 0
      }
    ],
    "invite_required_member_ids": []
  }
}

直接添加需要改走邀请示例（字段格式示例，不是真机记录）：

以下省略公共设备／时间字段，由插件POST到 /agent/command_result：

{
  "request_id": "req-add-001",
  "command_name": "add_group_member",
  "ok": false,
  "error": "成员未全部确认加入，请查看 member_results；需要邀请时显式调用 invite_group_member",
  "result": {
    "status": "requires_invitation",
    "mode": "add",
    "request_id": "req-add-001",
    "room_id": "123456789@chatroom",
    "member_ids": [
      "wxid_member_a"
    ],
    "member_count": 1,
    "submitted_member_ids": [
      "wxid_member_a"
    ],
    "already_in_room_member_ids": [],
    "accepted": true,
    "request_submitted": true,
    "response_received": true,
    "server_confirmed": false,
    "request_cgi": 120,
    "event_id": 42,
    "wechat_ret": -2012,
    "wechat_error_message": "",
    "message_type": 0,
    "transport_error_type": 0,
    "transport_error_code": 0,
    "created": false,
    "all_members_added": false,
    "member_results": [
      {
        "member_id": "wxid_member_a",
        "status": "requires_invitation",
        "native_status": 0
      }
    ],
    "invite_required_member_ids": [
      "wxid_member_a"
    ],
    "error_code": "MEMBERS_NOT_ALL_ADDED"
  }
}

邀请批次已发送示例（字段格式示例，不是真机记录）：

以下省略公共设备／时间字段，由插件POST到 /agent/command_result：

{
  "request_id": "req-invite-001",
  "command_name": "invite_group_member",
  "ok": true,
  "error": "",
  "result": {
    "status": "invitation_sent",
    "mode": "invite",
    "request_id": "req-invite-001",
    "room_id": "123456789@chatroom",
    "member_ids": [
      "wxid_member_a"
    ],
    "member_count": 1,
    "submitted_member_ids": [
      "wxid_member_a"
    ],
    "already_in_room_member_ids": [],
    "accepted": true,
    "request_submitted": true,
    "response_received": true,
    "server_confirmed": true,
    "request_cgi": 610,
    "event_id": 42,
    "wechat_ret": 0,
    "wechat_error_message": "",
    "message_type": 0,
    "transport_error_type": 0,
    "transport_error_code": 0,
    "created": false,
    "all_members_added": false,
    "member_results": [],
    "invite_required_member_ids": []
  }
}

已提交但超时未知示例（字段格式示例，不是真机记录）：

以下省略公共设备／时间字段，由插件POST到 /agent/command_result：

{
  "request_id": "req-add-001",
  "command_name": "add_group_member",
  "ok": false,
  "error": "等待微信回包超时，可能已生效；请用相同 request_id 查询，勿换 ID 重发",
  "result": {
    "status": "unknown",
    "mode": "add",
    "request_id": "req-add-001",
    "room_id": "123456789@chatroom",
    "member_ids": [
      "wxid_member_a"
    ],
    "member_count": 1,
    "submitted_member_ids": [
      "wxid_member_a"
    ],
    "already_in_room_member_ids": [],
    "accepted": true,
    "request_submitted": true,
    "response_received": false,
    "server_confirmed": false,
    "request_cgi": 120,
    "event_id": 42,
    "wechat_ret": null,
    "wechat_error_message": "",
    "message_type": null,
    "transport_error_type": null,
    "transport_error_code": null,
    "created": false,
    "all_members_added": false,
    "member_results": [],
    "invite_required_member_ids": [],
    "error_code": "OPERATION_TIMEOUT"
  }
}

15. 入群邀请：查询、静默接受与探针

用户已确认微信 8.0.80 的邀请查询与接受入群功能验证通过。收到普通私聊邀请链接卡片后，插件从原消息取得 URL、发送方和消息上下文，经微信原生 A8Key 鉴权调用官方邀请详情/接受协议。全程不创建网页、不点击、不执行网页脚本。HTTP 的邀请查询和探针已有验证记录；用户提供的接受回包为 ok=true/status=joined、membership_verified=true/in_chatroom=true，确认该样本已入群。查询时 roomInfo.roomName 可缺省，目标群 ID 可在接受成功后才取得。

业务请求统一为：

{"message_id":"123456789012345678"}

message_id 取收到卡片事件的 body.message_id，必须是正整数十进制字符串（最多 20 位且不超过 uint64，无前导零）。不接受 JSON 数字，以免大整数丢精度。不需要 invite_url、chat_id、room_id、账号凭据或 ticket。账号选择沿用既有设备/账号通道；本地复核消息属于当前登录账号。回调里的 chat_id 是来源会话，私聊的 room_id 为空，不是邀请目标群。群名等来自服务器详情；目标群 ID 在查询时可为空，接受成功后从提交回包取得。

仅处理当前账号收到的普通私聊 49/5 卡片及 support.weixin.qq.com/cgi-bin/mmsupport-bin/addchatroombyinvite 邀请。 鉴权后的地址允许微信内置的 7 个 support 域名（support/szsupport/mlsupport/hksupport.weixin.qq.com、support/sgsupport/ussupport.wechat.com），仍严格检查 HTTPS、原路径、原 ticket、端口和凭据；详情/接受请求及 Origin 使用本次鉴权域名，不跟随重定向。原消息必须仍在近期缓存（当前最多 200 条），否则返回 MESSAGE_CONTEXT_NOT_FOUND，需重新取得一条新邀请。切换账号或登录上下文时停止操作。微信被系统挂起或进程结束时不能保证后台执行；“静默”指进程有运行时间时无界面地执行协议。

三项命令均受本模式插件启用和授权校验；接受操作在真正提交前再次检查有效发送状态。查询和探针不另行执行发送判断。

结果判定

ticket_used=true 单独不能证明当前还在群。openurl、额外交互或不支持的 A8Key action 会明确受限/失败。不会转到页面继续操作。查询阶段允许服务器暂不返回群 ID，仍可返回群名、人数和是否可接受；接受成功必须取得有效群 ID。后续成员核实按同一 ticket 的本次服务器详情判断，若返回群 ID 则必须匹配。旧本地群联系人或成员缓存不作为本次在群证据。

查询响应示例（依据第28包查询结果，消息 ID 与群名已替换；查询时群 ID 缺省）：

{"ok":true,"status":"ready","message_id":"123456789012345678","room_id":"","room_name":"示例群","member_count":198,"can_accept":true,"in_chatroom":false,"ticket_used":false,"restriction_code":"","warning":"为维护微信平台绿色网络环境，请勿在群内传播违法违规内容。","request_submitted":false,"membership_verified":false,"wechat_ret":0,"a8key_action":6,"wechat_err_code":0,"wechat_error_type":0,"http_status":200,"stage":"info","error_code":"","error":"","elapsed_ms":1417}

接受响应主要看 status、request_submitted、membership_verified。request_submitted=true 只表示本次或此前同票据的接受请求已开始，不能证明服务器已接收；accepted 不等于已确认在群。接受操作的 can_accept 固定为 false，避免把已处理结果再次当作可提交邀请。

字段来源与快照语义

接受返回整合了接受前详情、接受 POST 和接受后核实三次请求：

• room_name、member_count、ticket_used、warning 保留接受前详情快照；核实阶段不刷新这些字段。因此成功回包中 ticket_used=false、member_count=198 仍可与 status=joined 同时出现，不能据此判断票据仍可用或入群后人数仍为 198。
• room_id 在接受成功时从 POST 回包取得；membership_verified 与 in_chatroom=true 表示后续同一票据的服务器详情已确认在群。verification_* 只记录这次核实请求，不覆盖接受 POST 的状态码。
• warning 来自微信详情的 data.antispamwarning，为空时取 data.securitytips，再隐藏其中的凭据和链接。当前返回没有记录具体采用了哪一个源字段。这条“为维护微信平台绿色网络环境，请勿在群内传播违法违规内容。”是微信返回的普通提醒；仅有该文案不表示违规、受限或失败，限制看 status/restriction_code。

后端判断已确认在群，使用 ok=true、status 为 joined 或 already_joined，并且 membership_verified=true。request_submitted=true 仅说明开始过提交；accepted 表示微信已确认接受但成员核实尚未成功，应查询详情确认，不能自动重提。接受操作结束时 can_accept 固定为 false，表示该操作结果不再作为可接受邀请，不能把它解释成本次接受被拒绝。

实测 wechat_ret=0 表示 A8Key 鉴权成功，a8key_action=6 是原生 URL 处理分支编号。接受回包的 http_status=201 是微信接受 POST 的成功 HTTP 状态；再结合 wechat_err_code=0/wechat_error_type=0 和有效群 ID 判断接受成功。verification_http_status=200 与核实双零业务码来自随后的详情 GET，成员是否核实仍看 membership_verified。本模式仍按命令结果外层 ok/error 判断业务结果，不能把 result.http_status 当作服务端接收结果信封的 HTTP 状态。

错误码包括 INVALID_ARGUMENT、INVALID_CALL_THREAD、NOT_LOGGED_IN、ACCOUNT_CHANGED、MESSAGE_CONTEXT_NOT_FOUND、MESSAGE_CONTEXT_MISMATCH、NATIVE_UNAVAILABLE、NATIVE_EXCEPTION、A8KEY_FAILED、A8KEY_TIMEOUT、RESPONSE_INVALID、INVITATION_TIMEOUT、INVITATION_EXPIRED、INVITATION_INVALID、WECHAT_REJECTED、SEND_DISABLED、BUSY、INVITATION_LIMIT、RESULT_UNKNOWN。限制码为 INVITATION_USED、INVITATION_RESTRICTED、UNSUPPORTED_INVITATION_FLOW，接受受限时也作为错误码。

去重、超时与重试

同账号登录上下文、同票据、同操作及探针阶段的并发请求合并等待；创建操作上限 16。接受提交前登记内存记录，同一票据以后调用接受会重新查询、不重复 POST；明确拒绝可移除提交记录。提交记录当前最多 64，满时拒绝新提交，避免淘汰未知记录导致误重试。账号/会话变化或进程重启后记录不保留，不保证跨重启幂等；后端也应按账号和原消息记录已提交/未知结果，重启后先查询，不自动重发接受。

鉴权等待约 18 秒，单次 HTTP 最多 12 秒，总操作约 55 秒。调用方等待建议 75 秒。本模式在工作线程等待，按 request_id 匹配最终命令结果；同一批命令仍在本条结果上报成功后才继续。不要因 30 秒内没有业务结果就自动重投。

只读探针与验证范围

使用 group_invitation_probe 命令，以下参数放在 args：

{"message_id":"123456789012345678","stage":"context"}

1. context：检查原消息、当前账号、原生类和 ABI，不按固定微信版本号拦截，不调用 A8Key 或业务 HTTP。
2. auth：在前述基础上调用原生鉴权并核对 fullUrl、ticket、exportkey，不请求邀请详情。
3. info（默认）：完成鉴权并 GET 详情，不 POST 接受。三阶段 request_submitted 均为 false。

诊断含 native_ready、native_signatures、wechat_version、message_context_found、message_type、app_msg_type、a8key_scene、a8key_opcode、callback_received；收到回调后可有 event_id、cgi、a8key_message、transport_error_type/code、exportkey_present、full_url_allowed、full_url_same_host/path/ticket、full_url_https、full_url_has_fragment、full_url_host（仅 hostname）、full_url_host_allowed、full_url_port（未显式设置时 null）、full_url_has_credentials、a8key_header_names；HTTP 后可有 business_http_host（应与鉴权 hostname 相同）、http_response_mime、last_response_bytes、network_error_code、http_json_object、data_object、room_info_object 及固定业务字段名称列表 invitation_fields。业务解析后还有 response_field_types（固定字段的 JSON 类型，含 missing/null）、response_string_lengths（群信息字符串长度）和 response_validation（信封、业务层、布尔字段、roomInfo 和群 ID 校验结果），不返回这些字段的原始字符串值。full_url_same_host 仅表示与原入口主域名相同；官方地区域名可使其为 false，应结合 full_url_host_allowed/full_url_allowed 判断。字段按到达阶段提供。探针不返回原始链接、ticket、exportkey、Cookie 或鉴权 header 值，也不提供任意 URL、原生方法执行能力。

若具备直连手机的条件，可另外运行项目自带的 HTTP 只读验证脚本；它仅用于排障，不代替长轮询端到端验证：

python tests/group_invitation_smoke.py --base-url http://<手机IP>:19088 --message-id <刚收到的消息ID>

排障按 context → auth → info 检查；确认 status=ready 后按业务需要调用接受接口。脱敏探针 JSON 可定位原消息、ABI、A8Key 或 HTTP 问题，避免盲目重建。若 auth 成功但 info 失败，检查 http_status、双层业务码、网络错误与 header 名称。用户已确认邀请查询与接受入群在微信 8.0.80 验证通过。实现不再按固定版本号拦截，仍检查实际原生类、方法和参数类型。过期／受限邀请、网络异常、账号切换及跨重启幂等按本节状态和重试边界处理。Apifox GUI 导入未测试。

命令下发示例（放在 poll 响应 commands 数组）：

{"request_id":"invite-001","command_name":"accept_group_invitation","args":{"message_id":"123456789012345678"}}

命令回包沿用既有信封：业务 ok/error 在顶层，其余字段位于 result，本功能不附加 HTTP 出口的 version。上方查询示例展示业务字段；下面是接受命令结果：

接受并核实入群成功的命令结果格式（将用户提供的 HTTP 真机回包按既有命令信封转换，身份字段已替换）：

{
  "request_id": "invite-001",
  "command_name": "accept_group_invitation",
  "ok": true,
  "result": {
    "status": "joined",
    "message_id": "123456789012345678",
    "room_id": "123456789@chatroom",
    "room_name": "示例群",
    "member_count": 198,
    "can_accept": false,
    "in_chatroom": true,
    "ticket_used": false,
    "restriction_code": "",
    "warning": "为维护微信平台绿色网络环境，请勿在群内传播违法违规内容。",
    "request_submitted": true,
    "membership_verified": true,
    "wechat_ret": 0,
    "a8key_action": 6,
    "wechat_err_code": 0,
    "wechat_error_type": 0,
    "http_status": 201,
    "stage": "verify",
    "error_code": "",
    "elapsed_ms": 3876,
    "verification_http_status": 200,
    "verification_err_code": 0,
    "verification_error_type": 0
  },
  "error": ""
}

长轮询请求继续携带 session_id/device_id/ts_ms 等公共字段，不添加 WebSocket 的 type 字段；按 request_id 匹配结果。

16. 群管理员、群免打扰与个人二维码

三项支持 HTTP、长轮询和 WebSocket，使用相同参数和业务状态。示例 ID 和二维码 URL 均为虚构。

需要正常鉴权和登录，拒绝未知字段。群管理与免打扰受发送写开关约束；个人二维码不受发送开关约束。群 ID 必须是普通微信群真实 ...@chatroom，不接受群名或 OpenIM 群。

群管理员操作

{"room_id":"123456789@chatroom","oper_type":1,"member_ids":["wxid_member_a"]}

oper_type 必须是 JSON 整数，拒绝布尔值、字符串。成员必须是群内其他普通微信成员的真实 user_name／wxid，不接受昵称或本人；数组去重并保留顺序。当前账号必须为群主，无法从本地群资料确认权限或成员时先刷新群资料。同一群同时只处理一个权限变更，全局最多 32 项待处理。

accepted 仅为原生方法的 BOOL 返回；request_submitted 仅表示取得本次原生事件 ID，均不能单独判断成功。每次调用等待约 30 秒并一次返回结果，调用方超时建议至少 40 秒，无需业务状态轮询。超时、断线或 unknown 时先核实群状态，不要自动重新提交；转让成功后原群主不再具备群主权限。

返回保留 room_id、oper_type、去重后的 member_ids，以及以下诊断字段：

常见 error_code：OWNER_REQUIRED、ROOM_STATE_UNAVAILABLE、OPERATION_BUSY、WRITE_DISABLED、REQUEST_NOT_CONFIRMED、WECHAT_REQUEST_REJECTED、OPERATION_TIMEOUT、ACCOUNT_CHANGED。不要把 null 错误码按 0 处理。

群聊消息免打扰

{"room_id":"123456789@chatroom","silence":true}

silence:true 开启免打扰，false 恢复通知。必须显式传入 JSON 布尔值，拒绝 0/1、字符串、null 和缺省。普通群成员即可操作，只影响当前账号的消息提醒设置。

响应保留 room_id、目标值 silence、accepted、sync_requested、already_set、local_verified、server_confirmed、status；非法或缺失的 silence 可为 null。accepted 是原生 BOOL，sync_requested 只表示进入原生同步路径；server_confirmed 固定为 false，本地数据库确认不等于服务端同步 ACK。失败或未知时附 error_code／error，未知结果先核实设置，不自动重提。

获取自己的二维码

请求体必须为 {}；自动使用当前登录账号，不接受 appId、wxid、style、refresh 或其他字段。本次请求二维码 URL，必要时生成 PNG；不读取旧磁盘图片，也不撤销旧二维码。同账号并发查询合并，等待约 30 秒，调用方超时建议至少 40 秒。

受限或失败时保留原始状态、提示及可用图片，不把受限结果按成功处理。失败时结合 error_code／error，不能只检查图片是否存在。

命令信封、等待与重试

参数放在 args，个人二维码使用 args:{}。回包外层 ok／error 表示业务结果，status、error_code 和其余业务字段在 result 中；读取错误码使用 result.error_code，result 不再包含 ok／error。

group_admin_operate、get_self_qrcode 复用后台等待路径，一次返回终态，等待不占用通信队列；每次进入共享服务重新校验当前账号，不使用通用 request_id 结果缓存。request_id 用于关联结果，不能保证操作去重。免打扰沿用普通命令的结果缓存规则。每项新操作使用新的 request_id，结果丢失、超时或未知时先核实当前状态，不能靠重发群权限命令查询结果。

长轮询仍按批次顺序执行，取得当前命令结果并完成提交后才执行下一项；后台等待仅释放通信队列，不表示并行执行整批。等待期间允许停止或重启长轮询。

在 /agent/poll 响应中下发：

{
  "commands": [
    {
      "request_id": "req-admin-001",
      "command_name": "group_admin_operate",
      "args": {
        "room_id": "123456789@chatroom",
        "oper_type": 1,
        "member_ids": [
          "wxid_member_a"
        ]
      }
    }
  ]
}

插件通过 /agent/command_result 提交结果。以下省略传输公共字段，仅展示本条业务结果：

{
  "request_id": "req-admin-001",
  "command_name": "group_admin_operate",
  "ok": true,
  "error": "",
  "result": {
    "room_id": "123456789@chatroom",
    "oper_type": 1,
    "member_ids": [
      "wxid_member_a"
    ],
    "status": "succeeded",
    "accepted": true,
    "request_submitted": true,
    "server_confirmed": true,
    "request_cgi": 889,
    "event_id": 42,
    "wechat_ret": 0,
    "wechat_error_message": "",
    "message_type": 0,
    "transport_error_type": 0,
    "transport_error_code": 0
  }
}

验证范围

用户已确认群免打扰正常；第 51 包的管理员添加、移除和群主转让均收到 ok=true、status=succeeded、wechat_ret=0、server_confirmed=true 的真机回包。用户现已确认个人二维码、好友备注及相关业务在微信 8.0.80 验证通过。这些群管理接口不包含进群申请审核。

17. 媒体下载与上传

适用插件：8.0.80。既有版本的图片、SILK 语音、视频、普通文件、表情的 HTTP 下载与上传，以及微信 CDN 上传已通过联调；视频和动画表情已验证缓存复用。三种通道共用同一媒体业务服务；本节分别给出当前通道的完整调用约定。

后端在 POST /agent/poll 响应的 commands 数组中下发，命令对象无需 type。执行完成后，插件向 POST /agent/command_result 上报一次结果；后端接收后返回 HTTP 2xx。命令仍逐条执行，不在 poll 请求中等待媒体任务完成。文件字节由手机另行通过 HTTP 上传到 upload_url，不放进命令 JSON。

参数放在 args，外层 request_id 为本次真实命令 ID；微信 CDN 上传使用这个 ID，不在 args 重复填写。业务 ok/error 移到结果外层，其余字段位于 result，业务机器码位于 result.error_code，中文说明位于 result.message。开关或协议校验失败时可能仅有外层 error、result:{}。每次执行重新校验当前账号，不使用通用命令结果缓存；CDN 任务复用由媒体服务处理。后端等待结果建议至少 200 秒，业务接口 timeout_seconds 范围 1～180 秒。

支持 image 图片、voice 语音、video 视频、file 普通文件（49/6）、emoji 普通表情。微信 WXGF/WXAM 表情转换为 GIF，保留动画；原本为 GIF、PNG、JPEG、WebP 的表情保留原格式。转换失败返回错误，不输出 .bin；游戏表情不支持导出。语音只输出微信原始 SILK，不转 MP3；Opus 返回 unsupported_voice_codec。

原事件为 49/74（或 49/131）时，文件完成后微信可能保留同一本地记录、把数据库内层类型更新为 6/130，并更换服务器消息 ID。插件只有在当前账号、会话、localID、发送方／接收方、消息类、创建时间及外层类型均匹配，旧／新服务器 ID 非零且不同、创建时间有效，并且完成文件的 m_overwriteNewMsgId 明确等于原服务器 ID 时，才接受这种覆盖恢复。内层类型和覆盖编号优先读取 app 扩展，不能由 wrap 上的 0 遮住。

仍使用原事件 body.message_id 调用即可；业务恢复成功后会把原事件 ID 的定位更新为完成记录，并保存最终服务器 ID 别名。两个 ID 均可继续定位该消息；没有登记过的任意历史消息不能因此恢复。此处 6/130 是覆盖定位的接受条件，实际媒体下载／上传白名单仍只有普通文件 49/6：仍为 74/131 的记录尚未进入可下载类型，130 也未在当前媒体白名单中开放。media_type:"file" 只校验类型，不能强制转换；是否能下载以恢复后的实际消息及附件状态为准。

当前数据库记录仍为 49/74 或 49/131 时，下载／上传返回 error_code:"unsupported_media_type"，中文说明为“该文件处于对方或我们，上传尚未完成(上传中)阶段，或完成消息尚未同步，请稍后使用同一 message_id 重试”。等待本机或对方上传完成、且完成记录同步到本机后，继续用同一个原事件 ID 重试即可；仅增大 timeout_seconds 不会让当前仍为 74/131 的请求等待类型变化。若长期没有完成记录，先用 message_media_probe 查看数据库类型、附件字段存在性及覆盖编号，不能据该提示认定本机或对方一定尚未完成，也不要把 media_type:"file" 当作强制下载开关。其他不支持类型仍返回原有通用提示；当前 130 文件的定位可恢复，但未开放媒体下载。

旧 /download_message_image（含 /debug/download_message_image 别名）和 /upload_message_image 已废弃，仅保留兼容。新接入分别使用 /download_message_media 和 /upload_message_media；图片仍传 message_id，类型自动识别，返回字段按统一媒体接口读取。长轮询 / WebSocket 的旧 upload_message_image 命令同样保留兼容，改用 upload_message_media。

上传接口要求有效发送状态；下载和探针不额外检查发送状态，仍受本模式插件总开关与授权校验。授权沿用当前通道约定。以下消息 ID、文件路径、资源 ID 和域名均为示意，需替换成实际值。

1. 下载媒体

在 POST /agent/poll 的响应中下发：

{
  "commands": [
    {
      "request_id": "media_download_001",
      "command_name": "download_message_media",
      "args": {
        "message_id": "1234567890123456789"
      }
    }
  ]
}

只支持当前账号已登记且定位可恢复的消息，不增加任意历史消息查询。下载成功结果示例（数据、路径均为示意）：

{
  "device_id": "webridge_device_example",
  "session_id": "sess_example",
  "account_id": "wxid_self",
  "runtime_version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080",
  "ts_ms": 1792713600000,
  "request_id": "media_download_001",
  "command_name": "download_message_media",
  "ok": true,
  "duration_ms": 42,
  "result": {
    "message": "已使用缓存文件",
    "message_id": "1234567890123456789",
    "media_type": "voice",
    "downloaded": true,
    "from_cache": true,
    "resolved_local_path": "/var/mobile/Containers/Data/Application/EXAMPLE/tmp/webridge_media/ACCOUNT_HASH/1234567890123456789/voice.silk",
    "resolved_file_name": "voice.silk",
    "file_size": 18576,
    "mime_type": "application/octet-stream",
    "md5": "0123456789abcdef0123456789abcdef",
    "codec": "silk",
    "voice_length_ms": 3260,
    "duration_ms": 42
  },
  "error": ""
}

resolved_local_path 是手机沙盒路径，服务器无法直接 GET。需要服务器文件时调用上传接口。voice_length_ms 为语音时长，取不到为 0；duration_ms 为接口耗时。语音保持原字节，不播放、不主动设置已听状态。

缓存命中（插件副本或请求开始时微信已具备完整文件）返回 from_cache:true、message:"已使用缓存文件"；新下载返回 false、"下载完成"。图片沿用现有原生下载和解码策略，可能回退微信提供的标准清晰度，不承诺原图。

视频同时检查下载队列、声明大小和副本可读性；原生状态缺失时，必须核对完整文件 MD5 才允许导出，不能仅凭大小一致放行。表情转换后的 file_size、md5 和 mime_type 对应实际导出文件；GIF 的 MIME 为 image/gif。旧 emoji.bin 缓存会自动重新准备。

本次等待超时返回 media_timeout；后台资源准备最多继续到 180 秒。重复相同消息请求会合并正在进行的准备任务；可稍后重试同一个 message_id。

2. 上传我们的服务器

在 POST /agent/poll 的响应中下发：

{
  "commands": [
    {
      "request_id": "media_upload_001",
      "command_name": "upload_message_media",
      "args": {
        "message_id": "1234567890123456789",
        "timeout_seconds": 120
      }
    }
  ]
}

沿用下载命令的 args 参数；timeout_seconds 默认 60，覆盖本次等待准备和 HTTP 上传。另有可选 args.upload_url。command_request_id 使用命令外层真实 request_id。

默认 upload_media 就是设置里的业务服务器 base URL 加 /agent/upload_media，保留 base URL 的路径前缀。未配置业务服务器时须传入完整 HTTP/HTTPS upload_url。

请求体为 multipart/form-data，文件字段为 file。文字字段：

服务器必须返回 HTTP 2xx 和 JSON {"ok":true,"asset_id":"实际资源ID"}，其中 asset_id 为非空字符串。可以额外返回 url、local_path，分别映射为 server_url、server_local_path。仅有 HTTP 200 状态、HTML 页面、空响应或缺少 asset_id 都判为失败。视频、文件通过磁盘 multipart 文件上传，不把整个请求体装入内存。

成功返回下载元数据，另加：

{
  "device_id": "webridge_device_example",
  "session_id": "sess_example",
  "account_id": "wxid_self",
  "runtime_version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080",
  "ts_ms": 1792713600000,
  "request_id": "media_upload_001",
  "command_name": "upload_message_media",
  "ok": true,
  "duration_ms": 42,
  "result": {
    "message": "上传成功",
    "message_id": "1234567890123456789",
    "media_type": "voice",
    "downloaded": true,
    "from_cache": true,
    "uploaded": true,
    "asset_id": "asset_voice_example",
    "upload_http_status": 200,
    "server_url": "https://example.com/media/asset_voice_example"
  },
  "error": ""
}

from_cache 仅说明源媒体来自本地；每次调用仍向服务器发起上传。上传失败可复用缓存重试；服务器是否按 command_request_id 去重由服务器实现。旧 /upload_message_image 也复用新的磁盘 multipart helper，成功同样要求 ok:true 和非空 asset_id；旧图片接口其他字段保持原约定。

3. 上传微信 CDN

在 POST /agent/poll 的响应中下发：

{
  "commands": [
    {
      "request_id": "cdn_example_001",
      "command_name": "upload_file_to_wechat_cdn",
      "args": {
        "file_path": "/var/mobile/Containers/Data/Application/EXAMPLE/tmp/webridge_media/ACCOUNT_HASH/1234567890123456789/voice.silk",
        "timeout_seconds": 120
      }
    }
  ]
}

也可以把 args.file_path 换成 args.file_url:"https://example.com/demo.pdf"，二者只传一个；外层 request_id 仍必填。

当前统一通过“给文件传输助手发送普通文件”完成上传，因此允许产生一条 filehelper 文件消息。下载得到的语音、图片等字节也可提交，但返回的都是普通文件附件票据，不能直接当作图片、语音、视频或表情专用发送票据，也不是公开下载 URL。

只有本次确切消息完成发送，且账号、localID、文件大小、MD5、服务端消息 ID、file_id、AES key 均满足校验时返回成功：

{
  "device_id": "webridge_device_example",
  "session_id": "sess_example",
  "account_id": "wxid_self",
  "runtime_version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080",
  "ts_ms": 1792713600000,
  "request_id": "cdn_example_001",
  "command_name": "upload_file_to_wechat_cdn",
  "ok": true,
  "duration_ms": 42,
  "result": {
    "message": "微信 CDN 上传成功",
    "request_id": "cdn_example_001",
    "uploaded": true,
    "pending": false,
    "stage": "uploaded",
    "cdn_type": "file",
    "receiver": "filehelper",
    "file_name": "voice.silk",
    "file_size": 18576,
    "md5": "0123456789abcdef0123456789abcdef",
    "local_id": 123,
    "server_id": "1234567890123456790",
    "cdn": {
      "file_id": "微信实际返回值",
      "aes_key": "微信实际返回值",
      "attach_id": "有则返回"
    },
    "staging_deleted": false,
    "cleanup_status": "pending_ticket_validation"
  },
  "error": ""
}

当前保留临时消息，staging_deleted:false。不启用按条清理，以保留后续发送所需的票据；当前实现不会因超时删除发送中的消息。CDN 密钥只出现在成功业务响应中，探针不返回密钥或完整 XML。

同账号相同 request_id 绑定原任务，重复参数复用等待或结果，不再次发送；本地文件还存在时会核对内容变化，参数变化返回 request_id_conflict。同 URL 重试指原任务的下载结果，不重新抓取 URL。幂等记录保存在当前微信进程内，重启后失效；结果未知时不要重启后盲目重提。

等待超时返回 外层 ok:false,error:"media_timeout"，result.pending:true；保留同一个 request_id 和文件参数继续调用，或用探针查询。后台最多观察 15 分钟；其后业务接口仍会按原消息重查迟到结果。最多保留 128 个 CDN 请求 ID，达到上限返回 cdn_task_limit，不会淘汰旧任务而隐式重传。

外链文件单次上限 512MB，开始前需预留相应缓存配额；本地文件受全局 1GB 配额限制。源文件、媒体缓存和上传体并存时，实际可用单文件大小会更低。空间不足明确返回错误，不扩大配额。

4. 调试探针

查询某条消息，不触发下载、播放或发送：

在 POST /agent/poll 的响应中下发：

{
  "commands": [
    {
      "request_id": "media_probe_001",
      "command_name": "message_media_probe",
      "args": {
        "message_id": "1234567890123456789"
      }
    }
  ]
}

消息探针 v2 在媒体白名单检查前执行，因此可检查 49/74、49/130、49/131 等当前不能下载的类型。ok:true 只表示取得可诊断的消息对象，不代表媒体可下载、文件完整或定位关系已更新。它不会调用 ChangeForDisplay、触发下载／播放／发送，不回写消息索引或覆盖关系；缓存检查不创建目录、不触发清理，也不更新缓存使用时间。

cached_message 是缓存对象快照，database_message 是按已登记 localID 读出的、其余身份字段已核对的数据库候选快照；两者可能引用同一个原生对象，不能视作不可变的历史前后对照。顶层消息状态优先取数据库候选，没有候选才取缓存，以 probe_source 区分；即使候选因服务器 ID 变化被业务恢复拒绝，也会优先用于诊断。两者均不可用时返回 message_not_found；诊断期间账号变化返回 account_changed，业务机器码在 result.error_code／外层 error，原因在 result.message。

以下字段位于本次命令结果的 result；字段类型中的布尔值在部分原生回包中可能序列化为 0/1，读取时应兼容。null 表示未取得／不适用，与已读取到数值 0 不同。

lookup.database_status 的完整取值：

以下为顶层、cached_message、database_message 共用的消息快照字段；顶层另带上述探针与定位字段：

xml.parsed 为布尔；无法识别或解析时仅返回 {"parsed":false}。解析成功时，xml.type、xml.totallen、xml.overwrite_newmsgid 均为十进制字符串或 null，分别对应 app 类型、XML 声明字节数和覆盖的原服务器 ID；缺失或不是纯数字为 null，与字符串 "0" 不同。xml.has_attachid、xml.has_cdnattachurl、xml.has_aeskey、xml.has_authkey 为布尔，表示 XML 对应附件字段非空，只提供存在性。

探针不执行完整文件 MD5、视频解码或媒体导出校验，也不通过会修正数据库的状态接口恢复下载状态。因此 native_complete:false 不一定表示业务下载必定失败，size_matches:true 也不表示业务下载必定成功；最终以下载／上传接口返回的校验结果为准。

插件向 POST /agent/command_result 上报的成功结果示意（节选，编号与路径均为虚构，省略类名、签名及部分通用快照字段）：

{
  "device_id": "webridge_device_example",
  "session_id": "sess_example",
  "account_id": "wxid_self",
  "runtime_version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080",
  "ts_ms": 1793836800000,
  "request_id": "media_probe_001",
  "command_name": "message_media_probe",
  "ok": true,
  "result": {
    "probe_version": 2,
    "message": "已读取媒体状态，未触发下载或发送",
    "message_id": "1234567890123456789",
    "probe_source": "database",
    "lookup": {
      "database_status": "ok",
      "refresh_accepted": 1,
      "registered_local_id": "4096",
      "registered_server_id": "1234567890123456789"
    },
    "cache_ready": false,
    "raw_message_type": 49,
    "app_msg_type": 6,
    "media_type": "file",
    "type_supported": 1,
    "diagnostic_media_type": "file",
    "m_uiMesLocalID": "4096",
    "m_n64MesSvrID": "1234567890123456790",
    "m_overwriteNewMsgId": "1234567890123456789",
    "native_size": 0,
    "expected_size": 8126,
    "native_complete": false,
    "cached_message": {
      "raw_message_type": 49,
      "app_msg_type": 74,
      "wrap_app_msg_type": 0,
      "extension_app_msg_type": 74,
      "media_type": "",
      "type_supported": 0,
      "diagnostic_media_type": "file",
      "m_uiMesLocalID": "4096",
      "m_n64MesSvrID": "1234567890123456789",
      "m_overwriteNewMsgId": "0",
      "bAppMsgCompleteFlag": 0,
      "m_bAppAttachExistInSvr": 0,
      "m_uiDownloadStatus": 0,
      "m_uiUploadStatus": null,
      "has_m_nsAppAttachID": false,
      "has_m_nsMsgAttachUrl": false,
      "has_m_nsAesKey": false,
      "has_m_authkey": false,
      "native_path": "/var/mobile/Containers/Data/Application/EXAMPLE/Documents/appdata/4096.csv",
      "native_size": 0,
      "expected_size": 8126,
      "native_file_exists": false,
      "native_file_readable": false,
      "size_matches": false,
      "download_status": 0,
      "native_complete": false,
      "native_downloading": false,
      "xml": {
        "parsed": true,
        "type": "74",
        "totallen": "8126",
        "overwrite_newmsgid": "0",
        "has_attachid": false,
        "has_cdnattachurl": false,
        "has_aeskey": false,
        "has_authkey": false
      }
    },
    "database_message": {
      "raw_message_type": 49,
      "app_msg_type": 6,
      "wrap_app_msg_type": 0,
      "extension_app_msg_type": 6,
      "media_type": "file",
      "type_supported": 1,
      "diagnostic_media_type": "file",
      "m_uiMesLocalID": "4096",
      "m_n64MesSvrID": "1234567890123456790",
      "m_overwriteNewMsgId": "1234567890123456789",
      "bAppMsgCompleteFlag": 1,
      "m_bAppAttachExistInSvr": 1,
      "m_uiDownloadStatus": 0,
      "m_uiUploadStatus": null,
      "has_m_nsAppAttachID": true,
      "has_m_nsMsgAttachUrl": true,
      "has_m_nsAesKey": true,
      "has_m_authkey": false,
      "native_path": "/var/mobile/Containers/Data/Application/EXAMPLE/Documents/appdata/4096.csv",
      "native_size": 0,
      "expected_size": 8126,
      "native_file_exists": false,
      "native_file_readable": false,
      "size_matches": false,
      "download_status": 0,
      "native_complete": false,
      "native_downloading": false,
      "xml": {
        "parsed": true,
        "type": "6",
        "totallen": "8126",
        "overwrite_newmsgid": "1234567890123456789",
        "has_attachid": true,
        "has_cdnattachurl": true,
        "has_aeskey": true,
        "has_authkey": false
      }
    }
  },
  "error": ""
}

示例中数据库文件已完成并明确覆盖原 ID，因此定位 ok 且 refresh_accepted:1；本地仍没有 8126 字节文件，需调用 download_message_media 才会准备资源。探针本身不会保存这次覆盖恢复。若数据库仍为 74，即使 refresh_accepted:1，也只表示其身份可接受，不能当作已具备可下载附件。

查看已有 CDN 任务，不创建新任务，也不返回 AES / XML：

在 POST /agent/poll 的响应中下发：

{
  "commands": [
    {
      "request_id": "cdn_probe_001",
      "command_name": "message_media_probe",
      "args": {
        "request_id": "cdn_example_001"
      }
    }
  ]
}

结果外层 ok:true 表示读取成功；result 内的 operation_ok、stage、pending、task_finished、task_error 表示上传状态。has_file_id / has_aes_key 仅表示字段是否存在。业务成功结果及票据仍从 upload_file_to_wechat_cdn 命令的 result 获取。

探针的 message_id 和 request_id 二选一。查询 CDN 时，参数里的 request_id 是被查询的原上传任务 ID。外层 request_id 则是本次探针调用 ID，二者不同。

5. 缓存文件规则

1. 顺序：插件完整副本 → 微信完整本地文件 → 原生下载。同账号、消息和媒体类型的并发准备合并；同时最多准备 32 项。
2. 插件副本位于 tmp/webridge_media/<账号摘要>/<消息ID>/；微信原文件不移动、不删除。写 .part，校验大小、必要 MD5 和 SILK 头后原子改名；只返回正式副本。
3. 记录文件名、大小、实际 MD5、类型和最近使用时间，不记录 AES 或 XML。命中前检查文件是否存在、可读、非空、大小一致，语音另核对 SILK 头；旧 emoji.bin 不再直接命中，会从微信资源重新导出。
4. 最近使用后保留 1 小时，所有账号共用 1GB 上限，包含本次新增副本、CDN 来源暂存和 multipart 临时文件。空间不足先淘汰最久未使用的空闲项，在用项不删，仍不足返回 cache_space_insufficient。已有其他发送目录继续使用其原有规则。
5. 启动及新任务开始时清理；上传成功也不马上删除。系统可提前回收 tmp，文件丢失后会重新准备。

6. 后端接收服务复用

聊天媒体与朋友圈媒体可以使用同一个后端应用、同一个端口和同一套存储。 当前上传格式不同，推荐在现有业务后端提供两个接收入口，共用保存文件和生成访问地址的逻辑：

朋友圈使用本篇 朋友圈媒体下载 中的 upload 对象：url 指向上述接收地址，resource_id 由后端分配，method 默认 PUT，headers 可携带鉴权。插件不解析朋友圈上传响应正文，只读取状态码；响应不要超过 64KiB。朋友圈首次受理不等于文件上传完成，仍需等 moments_result 或查询任务，确认 status:"succeeded"、media_ready:true、delivery:"upload"、upload_completed:true。上传结果未知时先按 resource_id 核对后端，插件不会自动重传。

仅处理 multipart 的 /agent/upload_media 不能直接接收朋友圈原始正文，把朋友圈 method 改成 POST 也不会改变正文格式。后端增加原始正文入口即可，插件不需要为了共用后端而改动。两个入口可以共用资源表、文件目录和 GET /files/...；若沿用朋友圈网页示例，需支持按 resource_id 读取，视频读取需支持 Range。

upload_file_to_wechat_cdn 是手机通过微信原生链路上传微信 CDN，不需要自有上传接收服务。其 file_url 可以使用上述后端已有文件地址；返回的普通文件附件票据不能代替朋友圈发布专用上传结果。

仓库中的 demo/消息媒体上传接收端/media_upload_server.py 与 demo/朋友圈媒体上传接收端/server.py 目前仍是两个独立示例，尚未合并；正式接入推荐复用同一业务后端，按本节支持两个入口。

7. 调用检查与常见错误

长轮询结果读取 /agent/command_result 请求正文的 result。不要把结果信封中的业务字段当作文件字节。

1. 用新收到事件中的 body.message_id 调下载，再调一次检查 from_cache:true；核对文件名、MIME、大小和 MD5。语音应为 SILK，WXGF/WXAM 动画表情应导出 GIF。
2. 调上传我们的服务器，确认文件实际落盘、asset_id 非空；from_cache:true 只表示手机复用源文件，每次请求仍会上传。
3. 下载或上传等待超时可重试同一 message_id；微信 CDN 超时则必须保留原 request_id 和文件参数，避免重复发送。CDN 临时消息目前保留，删除后的票据消费不在已确认范围内。
4. 下载失败时同时提供业务响应和媒体探针响应；CDN 结果未知时用原上传 ID 查询，探针不含可消费票据。

常见错误：invalid_message_id、media_type_mismatch、message_not_found、not_logged_in、account_changed、unsupported_media_type、unsupported_voice_codec、media_timeout、cache_space_insufficient、media_checksum_mismatch、server_upload_failed、upload_url_required、request_id_conflict、cdn_task_limit、cdn_result_unknown。

等待超时结果示例：

{
  "device_id": "webridge_device_example",
  "session_id": "sess_example",
  "account_id": "wxid_self",
  "runtime_version": "8.0.80-2",
  "build_marker": "webridge_build_20261106_settings_update_8080",
  "ts_ms": 1792713600000,
  "request_id": "media_download_001",
  "command_name": "download_message_media",
  "ok": false,
  "duration_ms": 10001,
  "result": {
    "error_code": "media_timeout",
    "message": "本次等待超时，原下载继续；可用同一 message_id 重试",
    "message_id": "1234567890123456789",
    "media_type": "video",
    "duration_ms": 10001
  },
  "error": "media_timeout"
}

业务失败优先读取 result.error_code / 外层 error，中文原因读取 result.message；协议或开关失败按外层 error 处理。

本次验证范围： 本次文件覆盖恢复已由用户在 HTTP 真机确认：使用原 49/74 事件 ID，首次下载 8126 字节 CSV 成功，from_cache:false；同一个 ZIP 未完成时数据库仍为 74 且无 AES／附件／CDN 字段，完成后数据库变为 6 并以覆盖编号指向原 ID，随后首次下载 12,155,230 字节 ZIP 成功，from_cache:false。这些历史结果记录了共享媒体服务的实际文件链路；用户现已确认相关媒体功能在微信 8.0.80 验证通过。媒体白名单、索引保存及文件完整性条件仍适用。

18. 公众号：搜索、列表、关注／取关与历史文章

公众号五项支持 HTTP、长轮询和 WebSocket，订阅号与服务号统一管理。公众号相关业务已由用户在微信 8.0.80 验证通过。目标必须使用真实公众号 username，不接受昵称或 alias，也不依赖 gh_ 前缀判断类型。下方示例均为虚构。

三种通道使用相同参数及业务语义。参数采用严格类型校验，未知字段报 INVALID_ARGUMENT；整数不接受数字字符串或布尔值。需正常授权和登录；搜索、列表、文章查询不受发送总开关限制，关注／取关需要开启该开关，关闭时报 SEND_DISABLED。

已关注列表

{"type":"all","keyword":"","limit":100,"offset":0}

所有参数可省略。type 支持 all（默认）、subscription、service，区分大小写；keyword 是按账号、展示名、昵称、备注、alias 做不区分大小写的本地包含匹配。limit 默认 100、范围 1–1000；offset 默认 0、范围 0–4294967295。

返回 status:"ok"、type、keyword、items、total、limit、offset、has_more。total 是筛选后的数量；按展示名和账号排序，偏移超出范围时返回空页。每项沿用联系人摘要中的 account_id、display_name、nick_name、remark、alias、avatar_url 等字段，并增加 account_type（subscription／service）及 is_followed:true。这是本机已同步的名单，关注／取关后的关系可能延迟更新。

未登录返回 ACCOUNT_UNAVAILABLE，联系人尚未就绪返回 CONTACTS_NOT_READY，不能把失败当作空名单。它不是全网公众号搜索。

公众号关键词搜索

{"keyword":"示例"}

调用 official_account_search（HTTP 为 POST /official_account_search），仅接受 keyword 字符串，去除首尾空白后长度为 1–256 个 UTF-16 代码单元。输入公众号名称、微信号或关键词，联网返回微信原生首批候选，支持发现未关注公众号。

成功返回 status:"ok"、keyword、items、returned_count 和 request_submitted；取得原生返回码时包含 native_ret。候选复用联系人摘要中的 account_id、display_name、nick_name、alias、avatar_url 等字段，增加 account_type（本地已知时为 subscription／service，未取得为 null）与 is_followed（本地当前关注关系，可能延迟同步）。contact_found 仅表示本地联系人是否存在；未缓存的联网候选仍会返回。保留微信顺序并按真实 username 去重。无匹配时为 ok:true、items:[]、returned_count:0；超时、断网和微信业务错误不能当作无结果。

选中候选后，将其 account_id 作为 official_account_follow 的 id，例如 {"id":"official_account_example"}。搜索不会自动关注，也不受发送开关限制。它仅返回首批候选，不支持 limit、offset、cursor、page，不返回 total 或 has_more；匹配范围、排序及条数由微信决定。

约 30 秒业务超时，客户端等待建议至少 40 秒。

响应包含 search_diagnostics：当前 request_cgi 为 719，has_content 表示是否取得非空 JSON，json_byte_count 为其 UTF-8 字节数，json_ret 为 JSON 业务状态，section_count 为结果分组数。raw_item_count、parsed_item_count、contact_item_count、missing_username_count、duplicate_count 用于定位候选解析；missing_contact_count、unsupported_type_count 为旧诊断保留字段，当前为 0。native_business_type 为请求的公众号类型 1，native_continue_flag、native_offset 仅用于诊断，不开放分页。原生错误、JSON 业务错误、缺失内容或格式不兼容均返回失败，不能当成无匹配；只有有效成功的空列表才返回 ok:true、items:[]。诊断从开始原生请求时即可出现，不包含原始 JSON 或账号凭据。

关注与取消关注

两项均只传 {"id":"official_account_example"}。关注会先核对目标身份，再走公众号关注流程；返回单次结果，无需查询任务。

响应包含目标 account_id，并按取得的信息返回 is_followed、request_submitted。is_followed 只表示本地观察值，未知可为 null 或省略；校验失败时也可省略目标字段。关注无回包时 native_invoked=true、request_submitted=null，不能视为确认提交；收到本次回包才可标为 true。profile_request_submitted=true 只表示前置资料查询已提交。

取关可能清理对应本地会话、聊天消息和其他关联信息。 进入原生取关调用后返回 chat_history_may_be_deleted=true；submitted 后本地 is_followed 仍可能暂为 true。结果未知时先查询关注关系，避免重复清理。

同一公众号仍在关注时返回 OPERATION_IN_PROGRESS；搜索、关注及文章请求合计最多同时保留 16 个，超出返回 TOO_MANY_REQUESTS。搜索、关注与文章查询整次约 30 秒超时、约 32 秒等待保护，客户端等待建议至少 40 秒。

历史文章按篇数批量续取

{"id":"official_account_example","limit":100}

limit 默认 100，范围 1–1000，按多图文展开后的文章篇数计数。插件自动连续读取微信原生小页并合并，最多返回指定篇数；不支持 page、page_size、offset，不提供历史总文章数，也不提供完整正文。

成功返回以下字段：

每篇文章包含 account_id、app_msg_id（十进制字符串）、item_index（原生篇目位置）、title、digest、cover_url、url、author、publish_time（Unix 秒，未知为 null）、is_paid（boolean/null）。account_id + app_msg_id + item_index 共同定位文章；付费标记不能证明当前账号拥有阅读权限。

需要更早历史时，传入上一批的游标：

{"id":"official_account_example","limit":100,"cursor":"上一批返回的next_cursor"}

原生一页超过本批额度的文章会随游标保留，下一批先返回余量，不跳篇。微信已经结束但缓存未取尽时 has_more 仍为 true；空原生页会继续翻，不等于历史结束。成功不足 limit 时表示已到微信允许展示的末尾。整批失败返回 ok=false，不把部分结果伪装成完整成功；在游标有效期内可从原输入游标重试读取，或降低 limit。

cursor 可省略或传空字符串，从最新文章开始；不能传 null。它是进程内不透明 token，绑定当前账号、登录会话和目标公众号，单个 token 从生成起有效 10 分钟；全局最多保留 128 个，超出时淘汰最旧者。切换账号／会话、重启插件都会使旧游标失效，返回 INVALID_CURSOR 后应从最新文章重新读取。

错误、账号变化与发送文本

错误沿用中文 error 和机器可读 error_code。常见错误包括 INVALID_ARGUMENT、INVALID_ACCOUNT_ID、INVALID_ACCOUNT_TYPE、ACCOUNT_UNAVAILABLE、CONTACTS_NOT_READY、NATIVE_API_UNAVAILABLE、REQUEST_NOT_STARTED、REQUEST_TIMEOUT、WECHAT_REQUEST_FAILED、RESPONSE_INVALID。文章另有 INVALID_CURSOR、ARTICLES_RESTRICTED、CURSOR_NOT_ADVANCING；同一请求期间账号或登录会话变化返回 ACCOUNT_CHANGED。失败时不保证有 items、has_more、next_cursor 等成功字段。

向公众号发送文本仍使用已有 send_message，将同一个 username 放入 receiver，例如 {"receiver":"official_account_example","content":"你好"}。沿用原发送结果与公众号私信权限限制，成功不代表对方已收到或已读。

命令回包、等待与去重

请求字段放在 args。回包沿用 command_result：外层 ok／error 表示结果，业务的 status、error_code、request_submitted、items、next_cursor 等保留在 result，读取错误码用 result.error_code。外层 account_id 是当前登录账号，result.account_id 才是目标公众号；前置校验失败可省略后者。

五项命令在后台执行并一次返回终态，不阻塞通信队列；仍需等待约 30 秒业务超时，客户端建议至少 40 秒。每次都会进入共享服务重新校验当前账号，公众号五项不走通用的最近 100 条 request_id 结果缓存。request_id 用于关联回包，不能充当操作去重保证。不要因结果丢失而盲目重发关注／取关，先查询本地关系。

在 /agent/poll 响应中下发：

{"commands":[{"request_id":"req-official-articles-001","command_name":"official_account_articles","args":{"id":"official_account_example","limit":100}}]}

插件执行后向 /agent/command_result 提交结果，再继续下一条命令或下一轮 poll。等待期间可停止或重启轮询；同批命令仍逐条串行执行。

19. 朋友圈：调用、结果与后续操作

你的后端实现本协议前文的5个/agent/*入口；插件主动访问后端。以下下发JSON是后端对/agent/poll的响应，不是向手机POST。无需让后端访问手机HTTP。示例ID、上传域名和Token均需替换，所有数据均为虚构。

最短读取流程：

1. 注册／握手后确认capabilities包含所需moments_*命令。
2. 下发moments_list，保存command_result.result.operation_id；首次ok=true不表示页面已返回。
3. 等moments_result完成事件，或下发moments_operation查询原编号。
4. 从完成结果items[]继续详情、历史、互动或媒体上传。

{
  "commands": [
    {
      "request_id": "demo-list-001",
      "command_name": "moments_list",
      "args": {}
    }
  ]
}

查询同一操作：

{
  "commands": [
    {
      "request_id": "demo-operation-query-001",
      "command_name": "moments_operation",
      "args": {
        "operation_id": "11111111-1111-4111-8111-111111111111"
      }
    }
  ]
}

每次查询必须使用新的外层request_id（例如query-002、query-003），args.operation_id保持原值。重复request_id会命中命令结果缓存，可能一直看到第一次pending。查询命令的外层request_id对应本次查询，result.request_id仍属于原任务。

返回结果怎么判断

accepted只表示微信查询／任务受理。互动和单帖权限先查详情，所以accepted=true可能只是详情查询已发出。write_accepted才表示提交了微信写操作；它不用于表达上传文件。server_confirmed只描述微信结果，不描述上传目标；媒体即使上传成功仍为false。

request_id用于关联；最长128个UTF-16单位，本模式由命令外层写入，不在 args 重复传入。它不是跨重启的幂等保证。操作记录最多48项，完成记录在后续请求进入时可能淘汰，通常最多保留10分钟；重启即丢失，不是永久任务数据库。账号切换后不能查询旧账号操作，旧账号事件也不会包成新账号事件。

一般查询／资源准备120秒超时且未提交微信写入时失败；已提交写入却未确认时可能unknown，晚回包仍可用更高revision更新原操作。相同范围处理中或unknown锁未释放时会拒绝新任务。网络断开也不能证明微信写入或后端上传没有发生。

首次POST /agent/command_result只代表受理（以下省略通用设备和时间字段）：

{
  "request_id": "demo-list-001",
  "command_name": "moments_list",
  "ok": true,
  "error": "",
  "result": {
    "status": "pending",
    "accepted": true,
    "write_accepted": false,
    "server_confirmed": false,
    "operation_id": "11111111-1111-4111-8111-111111111111",
    "request_id": "demo-request-001",
    "action": "list"
  }
}

ok/error在命令结果外层，result内会剥掉这两个字段；其他业务字段留在result。最终完成通过POST /agent/event到达，完整业务结果在body内，body含自己的ok/error。媒体上传最长可能约300秒，首次命令结果的duration_ms不包含整个异步操作耗时。

{
  "event_name": "moments_result",
  "event_id": "msg:moments:11111111-1111-4111-8111-111111111111:1",
  "account_id": "wxid_self",
  "body": {
    "ok": true,
    "status": "succeeded",
    "operation_id": "11111111-1111-4111-8111-111111111111",
    "request_id": "demo-request-001",
    "action": "list",
    "accepted": true,
    "write_accepted": false,
    "server_confirmed": true,
    "revision": 1,
    "error": "",
    "items": [],
    "next_cursor": "12345678901234567890",
    "has_more": null,
    "snapshot_complete": true,
    "snapshot_source": "network",
    "missing_ids": [],
    "raw_count": 1,
    "truncated": false
  }
}

命令结果和完成事件可能先后交错；按account_id、body.operation_id关联，用revision合并较新状态，按event_id去重，不按到达顺序猜测。完成事件不能通过回一个HTTP200或接收WS帧来替代业务成功判断。

朋友圈数据怎么继续使用

提交的动态ID、评论ID和cursor必须是非零UInt64十进制字符串，不接受JSON数字或溢出。输出sns_id和游标为字符串；评论ID沿用微信原生类型，可能为数字或字符串，后端需要无损解析大整数再转字符串。不要让64位ID经过JavaScript Number；网页demo已有无损保护。media_id保持mid原值，不要求它是十进制数。所有时间戳字段按字段名区分秒（create_time）与毫秒（*_ms）。

动态对象字段包括sns_id、wxid、create_time、content、type、is_mine、liked、like_count、comment_count、private、visibility_type、media、likes、comments。type和visibility_type保留微信原始值，不要把它们直接当发布接口的type/visibility枚举。普通图片动态type通常1，普通视频通常15。

媒体包含mid、type、subType、totalSize、videoDuration、width、height、preview_urls及原生可用的dataUrl/hdUrl/uhdUrl/lowBandUrl/attachUrl/attachThumbUrl。某字段不存在表示原生未提供。CDN地址不保证电脑直接可用；HTTP200也可能是占位图。列表不自动下载整页资源。

评论包含comment_id、comment64_id、wxid、nickname、content、create_time、is_mine及可用的reply_comment_id/reply_comment64_id/reply_wxid；likes沿用类似摘要结构。每条动态媒体最多32项、赞与评论各200项，media_truncated/interactions_truncated为true表示已截断；接口没有继续分页获取全部评论的入口。

历史和快照的正确判断

direction默认head。显式head不能带cursor；传cursor且省略direction时按tail；tail必须带上一页next_cursor，不能传0，不能自行减1，也不接受自定义page_size。页大小由微信控制。

has_more=false才表示原始历史网络空页已确认到头；has_more=null表示暂不确定，有next_cursor可以继续。items不足40条、筛选后空页都不等于到头。has_more不明确但next_cursor=null时，停止本轮继续翻页，不要编造游标；可以保留结果后稍后重新从最新页核实。

snapshot_complete表示本页是否补齐，不是全量历史完成。snapshot_source=network/network_merged_cache区分网络完整对象与网络／缓存合并。missing_ids列出无法补齐的动态，可查detail。unchanged=true也要检查完整性。单页最多200条，truncated表示原始页超出保护上限。

好友时间线是微信当前账号按权限筛选后的信息流，不保证是所有好友相册并集或无限历史。用户相册的 visible_period 使用明确原生字段或三天/半年提示；提示为空仍为 unknown。空页、缓存计数或 ret_tips 均不足以证明被屏蔽；可用 check_visibility 获取首屏诊断。后端自行保存、去重、比较历史；插件不自动定时刷新。

远程后端：手机主动上传媒体

推荐远程接入使用这一流程：后端先分配resource_id和上传地址 → 下发media/download并附upload → 手机调用微信下载、解密或复用缓存 → 手机主动HTTP上传 → 接收moments_result → 后端按resource_id取自己保存的文件。全程无需后端访问手机HTTP，也不会把文件Base64塞进长轮询／WS。

upload字段：

插件自动设置Content-Type=image/jpeg或video/mp4、Content-Length。不能覆盖这两个头、Host、Transfer-Encoding、Connection、Cookie、Proxy-Authorization。使用签名上传时，后端需按对应文件类型签名；resource_id不会自动变成HTTP头，后端自行在上传路径或自己的签名头中关联。

后端接收完整文件并成功存储后才返回2xx；推荐201或204。插件不解析上传响应正文，因此响应正文控制在64KiB内；文件访问URL由你的后端通过resource_id自行生成。返回2xx且上传字节完整后才upload_completed=true；30x不跟随，4xx/5xx失败，不进行插件层自动重传。

准备阶段最多120秒；开始上传后另有180秒总上限（请求等待上限90秒），一次上传模式操作最多约300秒。上传过程按需读文件，不整体加载视频。上传中断、超时或成功状态但缺完整传输确认时upload_outcome_unknown=true：后端可能已经存储，先按resource_id核实，再决定是否重传；接收端应对同一resource_id幂等保存。重传由后端显式发起，插件不提供断点续传。

上传URL与鉴权头只用于当前任务，不进入结果、事件或完成后的操作记录。切号、微信退出或进程重启可能中止任务；这不是跨进程持久后台上传。上传模式成功后没有手机media_url，也没有后端文件的expires_at_ms；保留期限由你的后端决定。微信原生缓存可复用；插件生成的JPEG在上传终态清理，不删除微信视频缓存。

已有零依赖示例位于demo/朋友圈媒体上传接收端/server.py：PUT /uploads/{小写UUID}接收文件，要求Authorization: Bearer <MOMENTS_UPLOAD_TOKEN>；GET /files/{同UUID}读取临时文件，支持Range。后端用UUID同时作为resource_id和路径即可。示例保留10分钟、最多16个资源、重启清空；GET链接含不可猜测UUID，知道链接即可读取，生产环境应按自己的账号鉴权和保留策略实现。

网页demo/朋友圈网页工作台可展开“手机主动上传媒体”，填写已部署接收端地址和Token；随后每次点击媒体下载会生成独立UUID并上传，网页从接收端读取。手机不能访问电脑的127.0.0.1，需要使用手机可达的接收端地址。网页仍用HTTP测试业务；长轮询／WS业务后端直接使用本节命令参数即可。

发布、权限与排错边界

发布visibility=public（公开）、private（仅自己）、include（仅指定用户）、exclude（不给指定用户看）。include/exclude须带非空wxids，最多200项；public/private不能带非空名单。新发布和修改已有本人动态均支持这四种范围；不临时修改微信UI全局发帖设置。

这些MiB是插件保护上限，不是微信通用服务器限额。视频时长、正文配置以当前账号探针为准，不能固定写成30秒或2000字。媒体下载成功也不保证所有电脑浏览器支持该视频编码。

好友权限friend查询为本地hide_from/dont_see；recent查询为本人period。修改recent支持three_days/one_month/half_year/all；查看别人的可见期限使用user。post查询是联网详情，返回item、visible_users、excluded_users；visibility_type是原生字段，修改参数仍使用字符串visibility。只允许修改本人动态。

权限写入的server_confirmed=true而local_verified=false表示服务器已成功、本地读回异常，local_update_error给出原因，不应因此再写一次。dont_see完整服务器确认缺失会保留unknown。不要用“本地开关已变化”代替服务器确认。

视频发布前下载支持无文件后缀URL，结合文件头／响应文件名处理，并异步等待AVFoundation元数据。video_diagnostics.stage为download/metadata/thumbnail/ready；保留file_bytes、extension、duration_seconds、video_track_count、playable、thumb_ready等已取得信息。下载及可选thumb_download含http_status、received_bytes、expected_bytes（-1未知）、elapsed_ms、phase及底层error_domain/error_code；系统提供时还有DNS／连接／响应／传输metrics。准备失败不发布。下载／元数据／封面问题可先使用probe检查，不能把probe成功当发布成功。

评论错误保留raw_ret、server_error及comment_diagnostics；引用不存在、本人评论或无权限对象会明确拒绝。点赞、评论、删除和修改已有单帖都先联网详情；一个帖子的处理中任务可能阻止同帖新请求，按原operation_id等结果。

朋友圈读取、发布互动、单帖权限和本地媒体预览已有 HTTP 真机验收；实现标识为 moments_20261016_upload_v1。用户现已确认朋友圈相关功能（含主动上传）在微信 8.0.80 验证通过。

接口／命令完整用法

下列每项包含请求字段、可直接使用的场景示例、结果含义与下一步。重复字段含义以本章前面的表格为准。下面展示完整业务对象：通过命令结果返回时，ok/error 位于外层，其余字段放入 result；通过 moments_result 事件返回时，完整对象位于 body。所有示例响应均为虚构，省略部分可选字段。

好友最新时间线与历史：moments_list

每次请求一页当前账号能看到的好友时间线。默认最新页；提供cursor且省略direction时按历史页处理。

最新页

{
  "commands": [
    {
      "request_id": "demo-list-001",
      "command_name": "moments_list",
      "args": {}
    }
  ]
}

历史下一页

{
  "commands": [
    {
      "request_id": "demo-list-002",
      "command_name": "moments_list",
      "args": {
        "direction": "tail",
        "cursor": "12345678901234567890"
      }
    }
  ]
}

结果字段示例（等待终态后）：

{
  "ok": true,
  "status": "succeeded",
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "action": "list",
  "accepted": true,
  "write_accepted": false,
  "server_confirmed": true,
  "revision": 1,
  "error": "",
  "items": [
    {
      "sns_id": "12345678901234567890",
      "wxid": "wxid_friend",
      "create_time": 1775000000,
      "content": "示例动态",
      "type": 1,
      "is_mine": false,
      "liked": false,
      "like_count": 0,
      "comment_count": 1,
      "private": false,
      "visibility_type": 1,
      "media": [
        {
          "mid": "example-media-id",
          "type": 2,
          "width": 1080,
          "height": 1440,
          "preview_urls": []
        }
      ],
      "likes": [],
      "comments": [
        {
          "comment_id": 67,
          "comment64_id": "670000000000000001",
          "wxid": "wxid_friend",
          "content": "示例评论",
          "is_mine": false
        }
      ],
      "media_truncated": false,
      "interactions_truncated": false
    }
  ],
  "next_cursor": "12345678901234567890",
  "has_more": null,
  "snapshot_complete": true,
  "snapshot_source": "network",
  "missing_ids": [],
  "raw_count": 1,
  "truncated": false
}

下一步： 取items[].sns_id可查详情或互动；取next_cursor请求下一页；取media[].mid准备媒体。

指定用户相册与可见期限：moments_user

传 wxid 获取本人或好友相册。visible_period 优先读取原生期限字段；字段不足时仅从明确的三天/半年提示补充，空提示仍为 unknown。visibility_status 是本次响应的可见性判断，不能据此确认被屏蔽、拉黑或删除。

可见性检查（HTTP 请求体或命令 args）

{"wxid":"wxid_xxx","check_visibility":true}

普通请求继续使用微信的 MD5 增量策略。诊断仍复用同一个相册入口；刷新接口在 scope=user、direction=head 时也支持 check_visibility。按原 operation_id 等待终态，items=[] 本身不能证明空相册或被屏蔽。

用户最新页

{
  "commands": [
    {
      "request_id": "demo-user-001",
      "command_name": "moments_user",
      "args": {
        "wxid": "wxid_xxx"
      }
    }
  ]
}

用户历史页

{
  "commands": [
    {
      "request_id": "demo-user-002",
      "command_name": "moments_user",
      "args": {
        "wxid": "wxid_xxx",
        "cursor": "12345678901234567890"
      }
    }
  ]
}

结果字段示例（等待终态后）：

{
  "ok": true,
  "status": "succeeded",
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "action": "user",
  "accepted": true,
  "write_accepted": false,
  "server_confirmed": true,
  "revision": 1,
  "error": "",
  "items": [
    {
      "sns_id": "12345678901234567890",
      "wxid": "wxid_friend",
      "create_time": 1775000000,
      "content": "示例动态",
      "type": 1,
      "is_mine": false,
      "liked": false,
      "like_count": 0,
      "comment_count": 1,
      "private": false,
      "visibility_type": 1,
      "media": [
        {
          "mid": "example-media-id",
          "type": 2,
          "width": 1080,
          "height": 1440,
          "preview_urls": []
        }
      ],
      "likes": [],
      "comments": [
        {
          "comment_id": 67,
          "comment64_id": "670000000000000001",
          "wxid": "wxid_friend",
          "content": "示例评论",
          "is_mine": false
        }
      ],
      "media_truncated": false,
      "interactions_truncated": false
    }
  ],
  "next_cursor": "12345678901234567890",
  "has_more": null,
  "snapshot_complete": true,
  "snapshot_source": "network",
  "missing_ids": [],
  "raw_count": 1,
  "truncated": false,
  "visible_period": "all",
  "visible_period_source": "sns_user_info",
  "visibility_status": "visible",
  "check_visibility": false,
  "request_md5_empty": true,
  "top_raw_count": 0,
  "same_md5_count": 0,
  "raw_ret": 0,
  "privacy_flags_raw": 4096,
  "privacy_recent_raw": 4294967295,
  "ret_tips": "",
  "limited_id": "0",
  "continue_id": "0"
}

可见性诊断字段

只有原生返回码为 0 或 207、head 请求实际 MD5 为空、普通和置顶条数及同 MD5 计数均明确为零、continue_id 明确为 "0" 时，才报告 empty_or_restricted。同 MD5 未变化、仅有缓存计数、字段缺失或首屏未完成时不能据空数组下结论。

操作状态保持兼容：非零 raw_ret 仍返回 status=failed、ok=false、server_confirmed=false，同时保留取得的诊断字段；visibility_status 独立描述响应证据。没有原生响应的网络失败中，visibility_status 保持 unknown，不输出确定的 blocked 标志。受理结果及失败回调可能只有未知值，必须等待原 operation_id 的终态或对应 moments_result。

下一步： 继续历史时保留同一个wxid并使用本页next_cursor；历史页visible_period=unknown不能覆盖此前已确认的期限。

联网获取动态详情：moments_detail

根据列表、发布结果或已知sns_id联网查询，返回item。媒体、评论及权限信息仍受当前账号服务器可见范围限制。

动态详情

{
  "commands": [
    {
      "request_id": "demo-detail-001",
      "command_name": "moments_detail",
      "args": {
        "sns_id": "12345678901234567890"
      }
    }
  ]
}

结果字段示例（等待终态后）：

{
  "ok": true,
  "status": "succeeded",
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "action": "detail",
  "accepted": true,
  "write_accepted": false,
  "server_confirmed": true,
  "revision": 1,
  "error": "",
  "item": {
    "sns_id": "12345678901234567890",
    "wxid": "wxid_friend",
    "create_time": 1775000000,
    "content": "示例动态",
    "type": 1,
    "is_mine": false,
    "liked": false,
    "like_count": 0,
    "comment_count": 1,
    "private": false,
    "visibility_type": 1,
    "media": [
      {
        "mid": "example-media-id",
        "type": 2,
        "width": 1080,
        "height": 1440,
        "preview_urls": []
      }
    ],
    "likes": [],
    "comments": [
      {
        "comment_id": 67,
        "comment64_id": "670000000000000001",
        "wxid": "wxid_friend",
        "content": "示例评论",
        "is_mine": false
      }
    ],
    "media_truncated": false,
    "interactions_truncated": false
  }
}

下一步： 点赞、评论使用item.sns_id；回复取本帖comments中的comment_id或comment64_id；媒体下载取本帖media中的mid。

服务端触发刷新并接收结果：moments_refresh

scope省略时为timeline；scope=user时必须传wxid。刷新获取本次页面快照并产生moments_result，不启动定时任务，也不自动计算全局增删差异。支持与list/user相同的历史参数。

刷新好友最新页

{
  "commands": [
    {
      "request_id": "demo-refresh-001",
      "command_name": "moments_refresh",
      "args": {
        "scope": "timeline"
      }
    }
  ]
}

刷新用户最新页

{
  "commands": [
    {
      "request_id": "demo-refresh-002",
      "command_name": "moments_refresh",
      "args": {
        "scope": "user",
        "wxid": "wxid_xxx"
      }
    }
  ]
}

结果字段示例（等待终态后）：

{
  "ok": true,
  "status": "succeeded",
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "action": "refresh",
  "accepted": true,
  "write_accepted": false,
  "server_confirmed": true,
  "revision": 1,
  "error": "",
  "scope": "timeline",
  "direction": "head",
  "items": [
    {
      "sns_id": "12345678901234567890",
      "wxid": "wxid_friend",
      "create_time": 1775000000,
      "content": "示例动态",
      "type": 1,
      "is_mine": false,
      "liked": false,
      "like_count": 0,
      "comment_count": 1,
      "private": false,
      "visibility_type": 1,
      "media": [
        {
          "mid": "example-media-id",
          "type": 2,
          "width": 1080,
          "height": 1440,
          "preview_urls": []
        }
      ],
      "likes": [],
      "comments": [
        {
          "comment_id": 67,
          "comment64_id": "670000000000000001",
          "wxid": "wxid_friend",
          "content": "示例评论",
          "is_mine": false
        }
      ],
      "media_truncated": false,
      "interactions_truncated": false
    }
  ],
  "next_cursor": "12345678901234567890",
  "has_more": null,
  "snapshot_complete": true,
  "snapshot_source": "network",
  "missing_ids": [],
  "raw_count": 1,
  "truncated": false
}

下一步： 按operation_id关联本次页面；后端自行按sns_id去重、保存历史和比较变化。持续监听事件不会主动刷新。

点赞：moments_like

先联网查详情，再提交点赞并等待原生确认。已经点赞返回unchanged=true。需开启发送／写入功能。

点赞

{
  "commands": [
    {
      "request_id": "demo-like-001",
      "command_name": "moments_like",
      "args": {
        "sns_id": "12345678901234567890"
      }
    }
  ]
}

结果字段示例（等待终态后）：

{
  "ok": true,
  "status": "succeeded",
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "action": "like",
  "accepted": true,
  "write_accepted": true,
  "server_confirmed": true,
  "revision": 1,
  "error": "",
  "sns_id": "12345678901234567890"
}

下一步： 最终成功后可重新查详情显示最新赞和评论；不要因第一次pending再提交一次点赞。

取消本人点赞：moments_unlike

只取消当前账号的点赞；原本未点赞返回unchanged=true。需开启发送／写入功能。

取消点赞

{
  "commands": [
    {
      "request_id": "demo-unlike-001",
      "command_name": "moments_unlike",
      "args": {
        "sns_id": "12345678901234567890"
      }
    }
  ]
}

结果字段示例（等待终态后）：

{
  "ok": true,
  "status": "succeeded",
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "action": "unlike",
  "accepted": true,
  "write_accepted": false,
  "server_confirmed": true,
  "revision": 1,
  "error": "",
  "sns_id": "12345678901234567890",
  "unchanged": true
}

下一步： 最终成功后可查详情更新显示。unchanged=true表示无需再次写入。

评论与回复他人评论：moments_comment

普通评论只传sns_id/content；回复增加本帖可见评论的reply_comment_id，可匹配comment_id或comment64_id。当前微信原生实测不能回复本人评论，提交前明确拒绝，不降级为普通评论。content非空，接口最多4096个UTF-16单位，这不是已验证的微信服务器字数上限。

评论

{
  "commands": [
    {
      "request_id": "demo-comment-001",
      "command_name": "moments_comment",
      "args": {
        "sns_id": "12345678901234567890",
        "content": "测试评论"
      }
    }
  ]
}

回复评论

{
  "commands": [
    {
      "request_id": "demo-comment-002",
      "command_name": "moments_comment",
      "args": {
        "sns_id": "12345678901234567890",
        "content": "测试回复",
        "reply_comment_id": "12345"
      }
    }
  ]
}

结果字段示例（等待终态后）：

{
  "ok": true,
  "status": "succeeded",
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "action": "comment",
  "accepted": true,
  "write_accepted": true,
  "server_confirmed": true,
  "revision": 1,
  "error": "",
  "sns_id": "12345678901234567890",
  "comment_id": "",
  "raw_ret": 0
}

下一步： 最终成功后重新查detail取得评论列表和可用于后续删除／回复的评论ID；即使成功结果comment_id为空，也不要重发。

删除评论：moments_delete_comment

允许删除本人评论，或本人动态下的可见评论；不能删除他人动态中他人的评论。comment_id可使用本帖comment_id或comment64_id。需开启发送／写入功能。

删除本人评论

{
  "commands": [
    {
      "request_id": "demo-delete_comment-001",
      "command_name": "moments_delete_comment",
      "args": {
        "sns_id": "12345678901234567890",
        "comment_id": "12345"
      }
    }
  ]
}

结果字段示例（等待终态后）：

{
  "ok": true,
  "status": "succeeded",
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "action": "delete_comment",
  "accepted": true,
  "write_accepted": true,
  "server_confirmed": true,
  "revision": 1,
  "error": "",
  "sns_id": "12345678901234567890"
}

下一步： 最终成功后查detail核对列表。若原评论已不在可见列表，会明确失败，不推断为已经删除成功。

发布文字、图文或视频：moments_publish

type=text/images/video，默认text；visibility默认public。媒体来源为手机可访问的HTTP(S)地址或手机绝对路径，不能传电脑C盘路径。下载、解码、封面完成后才提交微信发布。需开启发送／写入功能。

文字（仅自己）

{
  "commands": [
    {
      "request_id": "demo-publish-001",
      "command_name": "moments_publish",
      "args": {
        "type": "text",
        "content": "朋友圈测试",
        "visibility": "private"
      }
    }
  ]
}

图文（仅自己）

{
  "commands": [
    {
      "request_id": "demo-publish-002",
      "command_name": "moments_publish",
      "args": {
        "type": "images",
        "content": "图文测试",
        "images": [
          "https://example.com/image.jpg"
        ],
        "visibility": "private"
      }
    }
  ]
}

视频（仅自己）

{
  "commands": [
    {
      "request_id": "demo-publish-003",
      "command_name": "moments_publish",
      "args": {
        "type": "video",
        "content": "视频测试",
        "video": "https://example.com/video.mp4",
        "visibility": "private"
      }
    }
  ]
}

指定人可见

{
  "commands": [
    {
      "request_id": "demo-publish-004",
      "command_name": "moments_publish",
      "args": {
        "type": "text",
        "content": "指定可见测试",
        "visibility": "include",
        "wxids": [
          "wxid_xxx"
        ]
      }
    }
  ]
}

不给指定人看

{
  "commands": [
    {
      "request_id": "demo-publish-005",
      "command_name": "moments_publish",
      "args": {
        "type": "text",
        "content": "示例",
        "visibility": "exclude",
        "wxids": [
          "wxid_friend"
        ]
      }
    }
  ]
}

结果字段示例（等待终态后）：

{
  "ok": true,
  "status": "succeeded",
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "action": "publish",
  "accepted": true,
  "write_accepted": true,
  "server_confirmed": true,
  "revision": 1,
  "error": "",
  "sns_id": "12345678901234567890",
  "local_sns_id": "local-example"
}

下一步： 等待最终服务器确认后使用sns_id查详情、修改权限或删除。local_sns_id只是本地编号，不能代替服务器sns_id。

删除本人动态：moments_delete

联网确认作者为当前账号后删除，仅支持本人已发布动态。需开启发送／写入功能。

删除本人动态

{
  "commands": [
    {
      "request_id": "demo-delete-001",
      "command_name": "moments_delete",
      "args": {
        "sns_id": "12345678901234567890"
      }
    }
  ]
}

结果字段示例（等待终态后）：

{
  "ok": true,
  "status": "succeeded",
  "operation_id": "11111111-1111-4111-8111-111111111111",
  "request_id": "demo-request-001",
  "action": "delete",
  "accepted": true,
  "write_accepted": true,
  "server_confirmed": true,
  "revision": 1,
  "error": "",
  "sns_id": "12345678901234567890"
}

下一步： 等待服务器确认；结果未知时保留原操作核实，不能只因界面消失就重新删除。