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六项全部通过后，才扩大好友、群发和朋友圈批量规模。

八、二轮智能追问：把方向收敛为开发决策

智能追问	默认答案	对研发的约束
第一使用者是谁？	运营人员执行，管理员处理设备与异常，负责人看结果	权限最少分为运营、管理员、负责人三类
用户最怕什么？	页面显示成功，微信里却没有结果	false_success_rate必须为0，未知状态不得包装成成功
出错后先让用户做什么？	系统先自愈并解释，再给人工动作	每个错误必须带层级、原因、自动处理、下一步
能否连续点击重复执行？	不能	写动作必须有idempotency_key和内容指纹
批量任务如何避免误操作？	预检、预览、确认、小批执行、失败暂停	默认批次10，失败率达到阈值自动暂停
谁能看到敏感正文？	仅有权限的业务人员	列表脱敏、详情按权限解密、查询留审计记录
离线时任务怎么办？	不直接失败，也不盲目执行	进入blocked并显示阻塞原因；恢复后按策略继续或重新确认
历史记录保存什么？	保存能复现一次执行的完整证据	请求摘要、trace、通道、原始回执、回读、操作者、时间均保留
今天先看哪个指标？	闭环成功率，不看接口调用量	北极星指标为“真实动作闭环成功率”

九、核心用户故事

US-01 管理员绑定并确认真实在线

作为管理员，我扫码绑定手机后，要在一个页面看到设备身份、非回环连接、微信进程、Hook四层状态和最近异常，从而确认设备能否承接业务任务。

完成条件：同一设备只出现一次；拔USB后仍在线；状态更新时间不超过60秒；异常可一键查看trace。

US-02 运营发送消息并得到微信回读

作为运营，我选择客户、编辑内容并确认发送后，要看到排队、执行、微信回执和最终回读，而不是只看到HTTP成功。

完成条件：消息正文幂等落库；页面显示最终状态；失败可按原任务重试；重复点击不产生第二条消息。

US-03 管理员定位并恢复Hook故障

作为管理员，当Hook不可用时，我要明确知道故障在Frida、微信进程、attach还是RPC，并看到系统已采取的自愈动作。

完成条件：四层状态独立；60秒内自动恢复或给出唯一人工动作；恢复前写任务保持阻塞。

US-04 运营安全执行批量任务

作为运营，我执行好友、群发或朋友圈任务前，要先看到对象数、去重数、风险项和预计批次，确认后再执行。

完成条件：支持dry-run；高风险项默认剔除；部分失败可导出；失败率达到20%时暂停后续批次。

US-05 负责人查看结果而非技术日志

作为负责人，我只需要看到今天成功多少、失败多少、主要原因、影响账号和待人工事项，并可下钻到证据。

完成条件：业务结果与trace关联；指标不把queued/unknown计入成功。

十、统一状态机

10.1 设备状态

unbound → binding → online → degraded → recovering → online

任何状态均可进入offline；只有当非回环WSS会话、鉴权和心跳均有效时才进入online。Hook异常但连接正常时为degraded，不能把整台设备误报离线。

10.2 Hook状态

service_unavailable → service_ready → process_found → attached → rpc_ready

• rpc_ready才允许写动作。
• 任一层失败进入degraded并记录failed_layer。
• 状态必须有checked_at/expires_at，过期结果不得继续展示为可用。

10.3 任务状态

draft → prechecking → awaiting_confirm → queued → running → readback → succeeded

异常分支：blocked / partial_failed / failed / unknown / cancelled。

• queued仅表示接收任务。
• 无原始回执进入unknown。
• 有回执但回读不一致进入failed或partial_failed。
• 只有回读对象、内容指纹和目标一致才进入succeeded。

10.4 消息状态

queued → sent → delivered，失败分支为failed / unknown / recalled。

发送接口成功最多推进到sent；取得微信服务端ID或等价业务回读后才进入delivered。

十一、最小数据模型

集合/表	必填核心字段	作用
devices	device_id, serial_aliases, model, bind_status, owner, created_at	唯一设备身份
connections	session_id, device_id, channel, source_ip, server, auth_status, heartbeat_at, closed_reason	真实连接单一真源
hook_status	device_id, service, process, attached, rpc_ready, failed_layer, checked_at, expires_at	Hook四层真值
wechat_accounts	wxid, device_id, nickname, account_status, last_active_at	微信号与设备映射
conversations	conversation_id, wxid, talker, type, last_message_at, unread_count	会话索引
messages	msg_svr_id, local_id, conversation_id, direction, type, content, status, sent_at, delivered_at	正式聊天记录
tasks	task_id, idempotency_key, action, operator_id, targets, status, risk_level, created_at	所有写任务主表
action_receipts	trace_id, task_id, channel_used, raw_receipt, readback, error_code, started_at, finished_at	执行与回读证据
audit_events	actor, role, action, object_type, object_id, result, trace_id, created_at	权限与审计

索引要求：device_id、wxid、trace_id、idempotency_key唯一或高选择性索引；消息以conversation_id + sent_at分页；原始回执大字段可转对象存储但必须保留摘要和引用。

十二、管理端页面规格

12.1 设备中心

• 列表：设备名、微信号、连接、Hook、心跳、待处理异常。
• 详情：设备身份、连接会话、Hook四层、最近10次恢复事件、能力清单。
• 操作：重新探测、恢复Hook、暂停接单、查看trace。

12.2 聊天中心

• 左侧会话，中间消息流，右侧客户信息与执行证据。
• 消息气泡显示发送中、已发送、已送达、失败、未知、已撤回。
• 空态说明未同步原因；加载态用骨架屏；错误态保留已加载记录并允许重试。

12.3 任务中心

• 新建任务采用“选择对象→风险预检→内容预览→确认→执行”五步。
• 任务列表显示总数、成功、失败、未知、暂停原因和预计完成时间。
• 任务详情按对象展示独立状态，不用一个总成功掩盖部分失败。

12.4 风险与日志

• 风险页只呈现需决策事项：离线、Hook异常、频控、失败聚类、账号异常。
• 技术日志默认折叠，业务人员看到大白话原因和下一步；管理员可查看原始回执。

十三、统一接口回执

{
  "trace_id": "TRACE_ID",
  "task_id": "TASK_ID",
  "device_id": "DEVICE_ID",
  "wxid": "WXID",
  "action": "send_message",
  "status": "readback",
  "channel_used": "wss_frida",
  "error": null,
  "raw_rpc_receipt": {},
  "readback": {},
  "timestamps": {
    "accepted_at": "ISO_TIME",
    "executed_at": "ISO_TIME",
    "verified_at": "ISO_TIME"
  }
}

错误码固定五层前缀：AUTH_* / CONNECTION_* / CAPABILITY_* / EXECUTION_* / READBACK_*。前端不得自行把错误改写成成功。

十四、迭代顺序与上线门禁

迭代	范围	出口条件
Sprint 0	真实连接、唯一设备映射、统一错误模型	伪在线为0；三端设备状态一致
Sprint 1	Hook四层、自愈、任务状态机	三类故障各3轮恢复；写动作可阻塞和恢复
Sprint 2	消息落库、聊天中心、发送回读	收发20条全部可查；重复入库为0
Sprint 3	好友/群发/朋友圈小批闭环	dry-run、确认、执行、回读、审计全链路通过

核心指标

• 真实在线率 ≥ 99%。
• 动作闭环成功率 ≥ 95%（测试环境首阶段目标）。
• 假成功率 = 0。
• 消息幂等落库率 = 100%。
• Hook自动恢复率 ≥ 90%，平均恢复时间 ≤ 60秒。
• unknown任务必须在10分钟内被回查或转人工。

十五、本期明确不做

1. 不在APK新增聊天、好友、群发、朋友圈详情页。
2. 不把ADB reverse、127回环或USB在线作为生产在线证据。
3. 不把accepted、queued、HTTP 200当作业务成功。
4. P0未全绿前，不开放大规模好友、群发和朋友圈任务。
5. 不为追求“接口数量”继续增加没有真实RPC与回读的空动作。

十六、下一次智能追问输入

下一轮只追问四个能改变开发结果的问题：

1. 当前管理端实际由存客宝还是触客宝承载首个聊天中心？
2. 消息正文默认保存期限和可见角色是什么？
3. 首批专用测试微信号、测试群和测试朋友圈对象分别是哪组？
4. 批量失败暂停阈值是否接受默认20%？

在答案缺失时，研发按本文默认决策推进，不阻塞Sprint 0～2。