workphone-sdk/开发文档/1、需求/工作手机微信产品需求_20260726.md

工作手机微信产品需求（2026-07-26 · 智能追问版）

信息来源：2026-07-23～2026-07-26 本项目 42 个 Codex 会话文件、15832 条去重消息，以及当前需求真源、开发进度总表、功能迭代记录。

一、今天的产品结论

工作手机的核心不是在 APK 里堆微信业务页面，而是提供一套稳定、真实、可审计的微信执行底座：

1. APK 继续保持“工作台、Agent、设备”三页，突出扫码绑定、设备身份、连接、保活、自愈和运行日志。
2. 微信好友、聊天、群发、朋友圈等业务细节放在存客宝/触客宝管理端，通过统一 API 调用。
3. 任何动作只有同时具备“真实无线通道、原始回执、业务回读、证据归档”才算成功。
4. 先解决连接真实性、Hook 附着和消息落库，再扩大批量写操作。

二、现有能力与真实问题

领域	已有能力	当前问题
APK	React三页、扫码绑定、设备身份、Agent配置、自愈开关	状态仍可能因设备别名和旧探测结果漂移
连接	WSS Agent、局域网/公网候选、心跳、重连	曾出现ADB reverse/127回环伪在线；WLAN隔离与公网鉴权造成掉线
Hook	Frida RPC、模块探测、部分读写动作	frida_hook_not_attached仍是223动作批测的主要失败原因
消息	发送、拉取、转发等接口和事件日志	当前Mongo缺少正式消息集合，聊天正文和最终送达状态未形成查询闭环
好友	联系人读取、画像、备注、批量动作契约	群加10人实测10/10失败；缺专用测试对象、频控和最终好友关系回读
朋友圈	发布、列表、点赞、评论接口	曾出现假/空sns_id、queued代替成功、发布后列表为空
BFF	Fleet、实时状态、SDK代理、错误透传	33/33复跑受JWT/403阻塞，跨端映射仍需现场核对
稳定性	保活、重连、自愈和长期采样	24小时验收、自愈三重启和唯一PID证据尚未完整关单

三、智能追问与默认决策

追问	从聊天记录得到的答案	产品决策
工作手机APK要不要展示所有微信功能？	多次要求删除无关微信细节页，以Agent和设备稳定为主	APK只保留三页；微信业务进入管理端
什么叫设备在线？	127回环曾制造伪在线	只认非回环来源的WSS会话，展示来源IP、通道、心跳和会话ID
什么叫动作成功？	HTTP 200、accepted、queued多次被误当成功	必须原始回执成功＋业务对象回读成功
Hook可用如何判断？	Frida端口可连不等于微信已附着	分开显示Frida服务、微信attach、RPC ping和业务能力
消息能不能查？	commands和事件日志存在，但正式消息集合缺失	新建统一消息模型，收发、状态、回执、正文均可查询
批量加好友何时开放？	10次群加均失败，且需要备注、估值分和去重	先dry-run、频控、专用测试对象，再小批量放量
朋友圈成功依据是什么？	页面未出现、空sns_id、queued等问题反复出现	非零真实sns_id＋列表回读＋内容指纹一致
网络选择局域网还是公网？	LAN有客户端隔离，公网可达但有鉴权	Agent自动发现；同网可达用LAN，不可达自动切公网WSS
BFF失败如何呈现？	403/JWT、设备离线、Hook未附着混在一起	统一错误分层：鉴权、连接、能力、执行、回读
功能优先级怎么排？	绝大多数失败最终都归因连接/Hook/回读	底座P0优先，业务扩展P1/P2后置

四、P0需求（今天进入开发）

WX-P0-01 真实连接单一真源

• Hub拒绝127/localhost/ADB reverse作为业务在线来源。
• 每台设备只保留一个当前会话，设备别名映射到唯一设备ID。
• 管理端显示：连接类型、来源IP、服务器、心跳年龄、鉴权状态、最近断线原因。
• LAN不可达时自动切换公网WSS；恢复后按策略回切，不产生双在线。

验收：拔掉USB、ADB=0，连续30分钟在线；切换网络后120秒内恢复；全程没有回环连接。

WX-P0-02 Hook四层状态与自愈

• 状态拆为：Frida服务、微信进程、Session attach、业务RPC。
• supports_hook=true必须来自当次RPC ping，不能复用过期模块探测结果。
• Frida停止、微信重启、Agent重启后自动重新attach，并生成结构化恢复事件。

验收：三种故障各执行3轮，60秒内恢复；恢复后ping/get_profile/get_messages/send_message真实通过。

WX-P0-03 微信消息统一落库

• 新增统一消息集合：device_id/wxid/talker/msg_svr_id/local_id/direction/type/content/status/timestamps/raw_receipt。
• 接收事件、主动拉取和发送回执统一幂等入库。
• 状态至少包含：queued、sent、delivered、failed、recalled、unknown。
• 提供会话列表、消息分页、按msg_svr_id查询、失败重试和事件订阅。

验收：指定测试会话收发各10条，数据库20条可查；正文、方向、时间、最终状态和微信回读一致；重复同步不重复入库。

WX-P0-04 写动作统一闭环

• 所有写动作采用：dry_run → confirm → execute → raw_receipt → readback → audit。
• 返回统一字段：trace_id/channel_used/device_id/action/status/error_code/raw_rpc_receipt/readback。
• accepted/queued不得转译为success；超时后保持unknown并允许按trace查询。

验收：发送消息、转发、备注、群发、朋友圈发布五类动作全部通过同一状态机和错误模型。

WX-P0-05 BFF与设备映射闭环

• 完成33/33 BFF接口有效JWT复跑。
• 存客宝、触客宝、超管共享唯一device_id ↔ Agent ID ↔ wxid映射。
• BFF原样透传鉴权、离线、未附着、执行失败和回读失败。

验收：三端看到同一在线状态；同一trace可从BFF追踪到Agent、Hook和回读。

WX-P0-06 24小时稳定与可观测

• 每60秒采样SDK、WSS、Agent、微信、Hook、网络、电量和前台服务。
• 记录断线开始、恢复时间、根因、自动处理动作和人工介入。
• 禁止验收脚本主动kickstart -k或重启共享SDK制造状态漂移。

验收：连续24小时；网络切换、熄屏、微信重启、Agent重启各至少1次并自动恢复。

五、P1需求（P0全绿后开放）

WX-P1-01 好友与客户批量管理

• 支持手机号/群成员/二维码三种来源。
• 自动去重、风险预检、分批间隔、申请语、负责人、标签和备注模板。
• 支持客户价值评分；可筛选最有价值客户并将评分写入备注扩展字段。
• 删除好友只允许专用可恢复测试对象，先预览再确认。

WX-P1-02 朋友圈真实闭环

• 支持文本、图片、链接三种发布；内容指纹防重复。
• 发布成功必须返回非零真实sns_id，并由列表回读确认内容一致。
• 点赞、评论、删除均使用真实朋友圈ID并读取最终状态。

WX-P1-03 消息完整动作矩阵

• 文本、图片、文件、名片、语音、链接、转发、撤回、接收/拒绝转账分别维护支持状态。
• 涉及支付的动作只做能力探测、明确状态与人工确认门禁，不与普通消息混用。
• 每个动作在OpenAPI提供请求、响应、错误码和真实示例。

WX-P1-04 二维码加好友与自动解封

• 二维码选图、识别、申请、好友关系回读形成闭环。
• 解封保留多轮客服原文、AI回复、发送状态和final_status，禁止用流程走完代替成功。

六、页面要求

APK

• 继续保持工作台、Agent、设备三页。
• 工作台只显示设备健康、Agent、平台、微信基础状态和异常摘要。
• 设备页负责扫码绑定、唯一设备编号、连接详情、高级维护和运行日志。
• 不新增聊天、好友、朋友圈、群发详情页。

存客宝/触客宝管理端

• 微信号页：设备、wxid、好友数、Hook能力、最后活跃。
• 客户页：标签、价值分、负责人、最近互动和好友状态。
• 聊天页：会话列表、消息状态、失败原因和trace追踪。
• 任务页：群发、好友、朋友圈的dry-run、确认、进度、回执和重试。
• 风险页：频控、失败聚类、异常账号、离线设备和人工确认。

七、产品验收总门禁

1. 真机执行，不使用旧截图、模拟回执或ADB回环作为通过证据。
2. 每项必须具备请求、响应、trace、原始回执、业务回读和时间戳。
3. UI状态与API状态一致，离线、未附着、未知不得显示成功。
4. 写动作只在测试账号、测试群、测试朋友圈和专用对象执行。
5. P0六项全部通过后，才扩大好友、群发和朋友圈批量规模。