siyu-bank/workphone-sdk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
workphone-sdk/开发文档/10、项目管理/工作手机_项目拆解对话.md
Manus AI e49e41bb4b feat: 同步工作手机 2026-07-23 本地更新
2026-07-23 23:40:57 +08:00

18 KiB
Raw Permalink Blame History

工作手机项目 · 卡若AI功能拆解与对话任务包

建立时间：2026-07-20
项目根目录：/Users/karuo/Documents/开发/2、私域银行/工作手机
原则：只新增拆解资料，不删除、不覆盖原有代码、需求、历史对话或验收报告。
总控角色：水泉·五行项目对话拆解总控
核心执行引擎：机擎AI Agent（工作手机设备端 Agent + Android AgentEngine + 服务端 AI Brain）

1. 用户本轮需求洗字后的结论

将“工作手机”项目按真实功能、代码边界、角色和当前待开发事项拆细；不删除原来的对话；把拆解结果形成项目内可持续推进的对话任务包；同时让“机擎AI Agent”参与角色分工和后续开发。

2. 项目现状摘要

工作手机 SDK v3.0 是存客宝/触客宝及其他内部系统使用的 AI 手机控制引擎，当前由以下链路组成：

flowchart LR
    A[存客宝/触客宝/超级管理员/AI数智员工] --> B[BFF /v1/workphone/*]
    B --> C[工作手机 SDK FastAPI :8899]
    C --> D[设备管理与设备编排]
    C --> E[WebSocket Hub]
    C --> F[统一 API 与 OpenAPI]
    D --> G[工作手机 Agent]
    E --> G
    G --> H[Android AgentEngine]
    G --> I[Python SkillBus/SkillExecutor]
    H --> J[无障碍控机]
    H --> K[FridaBridge/Hook（需 Root 测试机）]
    I --> L[AI Brain/任务队列/离线缓冲]
    J --> M[微信/抖音/小红书等 App]
    K --> M
    C --> N[MongoDB/Redis/事件总线]
    C --> O[管理端 sdk/admin]

当前已具备的能力

  • SDK 服务端、统一路由、健康检查、设备管理、Fleet 批量执行。
  • ADB、WebSocket Agent、Frida Hook 三通道，且已区分“设备在线”“Frida 服务在线”“Hook 已注入”。
  • 微信读类、部分写类、朋友圈、联系人、群、标签、消息、客户 profile-bundle 等接口。
  • 设备端 Python Agent：技能总线、技能执行器、AI Brain、语音入口、无线连接、离线结果缓冲。
  • Android 壳 APK：扫码配对、WSS 注册、前台服务、无障碍、AgentEngine、AI 对话桥、自动重连和微信保活。
  • 管理端：登录、设备列表/详情、消息、任务、模块、风险、分析、设置等页面。
  • 存客宝/触客宝 BFF 对接、实时状态、实时事件、事件流和 Fleet API。
  • Docker/NAS/WebStation/宝塔部署脚本、发行包和真机验收留痕。

当前项目总状态

领域 现状 依据/说明
设备在线与基础控机 94% 当前主线文档给出的可交付比例；无 Root vivo 仅能走 WS/无障碍基础控机
微信读类 99% profile、联系人、群、标签、消息、搜索主链路已可回归
微信写类 83% 需白名单真机、频控、真实回执、回读和报告
BFF 对接 92% 路由与 SDK 映射完成，待有效租户 JWT 全量复跑
24 小时稳定性 76% 长跑证据尚未满足完整 24 小时门禁
APK 当前版本 5.0.6/code 11 真机当前仍上报 5.0.5，待 USB 覆盖安装
Hook 专项 🔒 当前 vivo 无 Root/Frida；必须保留真实能力边界

3. 卡若AI角色分工

角色 五行归属 主责 在工作手机项目中的职责
水泉 水 项目总控 需求收集、模块拆分、依赖、任务卡、状态跟踪、验收回收、需求回写
金仓 金 架构与稳定性 设备身份、数据模型、连接治理、部署、备份、CI、稳定性
水桥 水 对接与流程 存客宝/触客宝 BFF、JWT、WebSocket、外部调用链和协作接口
木叶 木 产品体验 APK 工作台、管理端体验、扫码、状态卡、Skeleton、错误提示
火炬 火 全栈主责 SDK 服务端、统一 API、核心业务链路、版本和构建
火锤 火 代码修复 编码前检查、缺陷修复、最小变更、回归验证
火眼 火 测试验收 接口、真机、E2E、视觉、长跑和证据留痕
火种 火 代码图谱 调用链、路由、模块依赖、影响面分析
土砖 土 AI资产与复制 Agent/Skill 可复用资产、项目 AI 体系、模块标准化
机擎AI Agent 工作手机核心执行角色 设备端智能执行 接收任务、解析意图、选择通道、执行技能、上报状态、离线缓冲、自愈和保活

机擎AI Agent不是新的平行架构，而是工作手机项目中“设备端执行层 + AI任务编排层”的统一角色名称，复用现有 sdk/agent、sdk/android-app、sdk/app 代码。

4. 功能对话拆解（12 个）

金组：底座、数据、设备与部署

01｜金仓·架构与数据底座·设备身份和事件模型（P0）

  • 目标：统一 device_id、项目归属、能力矩阵、在线状态、Hook 状态、事件模型和 Mongo/Redis 数据边界。
  • 真实代码：sdk/app/services/device_manager.py、sdk/app/services/ws_hub.py、sdk/app/services/brain_skill_registry.py、sdk/config/、开发文档/7、数据库/。
  • 当前功能：设备列表、Fleet 汇总、在线过滤、能力过滤、实时状态和事件总线已存在。
  • 现在开发：补齐多项目 device-map、wxid/最后活跃同步、事件幂等、状态时间线、能力降级原因。
  • 验收：同一设备在 SDK/BFF/管理端 ID 一致；设备在线、WS、ADB、Frida、Hook 五个状态可分别展示；事件可按设备和时间查询。
  • 协作：水桥、火种、机擎AI Agent。

02｜金仓·连接与部署·无线自愈和长跑稳定性（P0）

  • 目标：让 WSS、ADB、前台服务、Agent、微信保活在换网、熄屏、重启后恢复，并形成 24 小时证据。
  • 真实代码：sdk/agent/wireless_agent.py、sdk/agent/local_device.py、sdk/android-app/app/src/main/java/com/system/cloudservice/engine/AgentEngine.kt、sdk/scripts/、sdk/launchagents/。
  • 当前功能：WSS 注册、心跳、自动重连、无线 ADB、自恢复脚本、微信保活已具备。
  • 现在开发：完成 v5.0.6 USB 覆盖安装；采样 SDK health/WS/ADB/前台服务/网络/微信状态；跑满 24 小时。
  • 验收：连续 24 小时无未解释掉线；每次掉线有开始/恢复/原因；重启后 60 秒内恢复或明确人工介入。
  • 协作：火眼、机擎AI Agent。

03｜金仓·发布与环境·版本、构建和本地资产治理（P1）

  • 目标：统一 APK、SDK、管理端、API 文档和部署包版本，避免构建产物与真机版本错位。
  • 真实代码：sdk/android-app/、sdk/Dockerfile、sdk/docker-compose*.yml、sdk/build_universal_package.sh、开发文档/8、部署/。
  • 现在开发：建立版本检查表、SHA-256、环境变量检查、构建产物索引和本地回滚记录。
  • 验收：构建版本、下载目录、真机上报版本、文档版本四者一致；敏感配置只读环境变量，不写入仓库。
  • 协作：火炬、火眼。

水组：需求、对接、总控与智能体调度

04｜水泉·项目总控·任务台账和对话回收（P0）

  • 目标：按本文件的 12 个模块推进，不让任务散落；所有功能完成后回写需求、进度、接口、验收。
  • 真实代码/文档：开发文档/1、需求/、开发文档/10、项目管理/、本文件同目录。
  • 现在开发：建立任务状态：待拆分→待执行→执行中→待验收→返工中→已验收→已回写；保留历史对话，只新增模块对话索引。
  • 验收：每个模块有负责人、代码范围、依赖、验收标准、证据路径和下一步；不删除旧对话。
  • 协作：全部角色。

05｜水桥·平台对接·存客宝/触客宝 BFF 与实时事件（P0）

  • 目标：完成带有效 JWT 的 BFF 全量回归，让外部系统真实使用 Fleet、实时状态、事件流和 SDK 代理。
  • 真实代码：项目外部 BFF 对接文档见 开发文档/5、接口/02-业务对接/；SDK 入口见 sdk/app/routers/、sdk/app/services/。
  • 当前功能：/v1/workphone/*、Fleet、realtime、integration manifest、WS 事件流已开放。
  • 现在开发：补可用租户 JWT；复跑 BFF 33/33；核对设备 map、wxid、好友数、最后活跃、错误码透传。
  • 验收：无 JWT 返回 401；权限不足返回 403；写类失败不包装成成功；message_id 可回读；事件能到达 BFF。
  • 协作：金仓、火炬、火眼、机擎AI Agent。

06｜水泉·智能体调度·卡若AI Agent与机擎AI Agent任务卡（P1）

  • 目标：将项目任务按能力分配到卡若AI成员和机擎AI Agent，形成可追踪、可回收的执行链。
  • 真实文档/代码：/Users/karuo/Documents/个人/卡若AI/运营中枢/工作台/Codex智能体开发入口.md、sdk/agent/skill_bus.py、sdk/agent/skill_executor.py。
  • 现在开发：每个模块使用任务卡；机擎AI Agent负责设备动作执行和回执，卡若AI成员负责需求、代码、测试和验收；长期产品 Agent 与临时任务 Agent 分开登记。
  • 验收：每个任务均有主责、协作、边界、证据、状态；机擎AI Agent 的任务能追踪到设备、技能、通道和结果。
  • 协作：土砖、火种、火眼。

木组：用户体验、APK与管理端

07｜木叶·APK工作台·扫码、状态卡和基础控机体验（P0）

  • 目标：完成 v5.0.6 真机界面闭环：扫码配对、设备状态、微信状态、AI 状态、保活配置和错误提示。
  • 真实代码：sdk/android-app/app/src/main/java/com/system/cloudservice/ui/、.../service/、.../engine/。
  • 当前功能：竖屏扫码、WSS 配对、前台服务、状态卡、IMEI、微信保活入口已开发。
  • 现在开发：USB 覆盖安装 v5.0.6；补实际光学识码截图；核对微信版本、运行状态、保活周期热更新。
  • 验收：扫码页面竖屏；绑定正文一致；公网在线；状态卡不把设备在线误报为 Hook 可用；断网/无权限有明确提示。
  • 协作：金仓、机擎AI Agent、火眼。

08｜木叶·管理端·设备、消息、任务、模块、风险和分析（P1）

  • 目标：让运营人员从管理端看到真实设备、真实任务、真实事件和风险，而非静态占位。
  • 真实代码：sdk/admin/src/app/、sdk/admin/src/components/、sdk/admin/src/lib/。
  • 当前页面：login、devices、messages、tasks、modules、risk、analytics、settings。
  • 现在开发：接入 realtime 状态/事件；补设备详情通道状态、错误原因、任务回执、风险审计；保持 Skeleton 和玻璃风格。
  • 验收：页面数据来自 SDK/BFF；加载有 Skeleton；失败保留错误码；设备、事件、任务可按时间和设备筛选。
  • 协作：水桥、火炬、火眼。

火组：核心执行、API、Hook与测试

09｜火炬·SDK服务端·统一API与业务路由（P0）

  • 目标：巩固 /api/v3/* 统一 API，确保读类、写类、Fleet、realtime、manifest、设备能力都返回真实结果。
  • 真实代码：sdk/app/main.py、sdk/app/routers/、sdk/app/services/、sdk/app/workphone_api_complete.py。
  • 当前功能：FastAPI、统一路由、设备控制、微信/多 App 能力、分页、能力降级和批量执行。
  • 现在开发：补 BFF 33 项对应的 SDK 证据；梳理错误码；写类统一 dry_run/confirm；禁止无接收器假成功。
  • 验收：OpenAPI、路由快照和实现一致；401/403/503/超时语义一致；写类有真实回执或明确失败。
  • 协作：水桥、火种、火眼。

10｜机擎AI Agent·设备端智能执行·Skill、AI Brain与自愈（P0）

  • 目标：成为所有设备动作的统一执行角色：接收任务→解析意图→选通道→执行技能→上报结果→离线缓存→重连补传。
  • 真实代码：sdk/agent/agent.py、sdk/agent/ai_brain.py、sdk/agent/skill_bus.py、sdk/agent/skill_executor.py、sdk/agent/voice_agent.py、sdk/android-app/app/src/main/java/com/system/cloudservice/engine/AgentEngine.kt、sdk/app/services/ai_agent.py、sdk/app/routers/agent.py。
  • 当前功能：自然语言任务、动作序列、规则降级、任务队列、常驻指令、离线缓冲、Frida→无障碍→Shell 三级选择、心跳和微信保活。
  • 现在开发：统一任务协议与 trace_id；记录 provider、skill、通道、设备、步骤、原始结果；AI 不可用时规则降级；所有执行结果回传事件总线。
  • 验收：同一任务可回放；执行失败可定位到步骤和通道；离线任务不丢；重连后按幂等策略补传；Hook 不可用时诚实降级到无障碍或返回能力不足。
  • 协作：火炬、金仓、火眼、土砖。

11｜火炬·微信 Hook与多 App技能·读写能力矩阵（P0/P1）

  • 目标：完成微信读类稳定回归，推进白名单写类和必要的多 App 技能，保持真实能力边界。
  • 真实代码：sdk/agent/ Hook 脚本目录、sdk/app/services/brain_skill_registry.py、sdk/app/routers/；矩阵见 开发文档/5、接口/03-Hook与微信/。
  • 当前功能：微信联系人、群、标签、消息、搜索、朋友圈、资料等读类；抖音、小红书等基础技能；Hook reload 和能力探测。
  • 现在开发：Root 测试机验收 ping/profile/send/messages；白名单验证 add_friend、mass_send、post_moments、moment_like、moment_comment；记录真实回执和回读。
  • 验收：测试账号/测试群/测试朋友圈；批间隔和 dry_run/confirm 门控；Hook 不可用返回 503/能力不足；不使用 mock 关闭任务。
  • 协作：机擎AI Agent、金仓、火眼、水桥。

12｜火眼·全端验收·真机、接口、视觉与长跑（P0）

  • 目标：把所有“代码存在”转成可复验的接口、真机、视觉和长跑证据。
  • 真实代码/文档：sdk/tests/、开发文档/8、部署/05-测试验收/、开发文档/10、项目管理/02-测试报告/。
  • 当前功能：110 接口报告、视觉验证、全端交互、真机 E2E、BFF 验收脚本和稳定性日志已存在。
  • 现在开发：补 v5.0.6 真机截图；有效 JWT 后跑 BFF 全量；完成白名单写类矩阵；启动并完成 24 小时稳定性窗口。
  • 验收：每项有命令、请求、响应、日志、截图/回读和文档勾选；失败保留原始证据；最终回写总表和进行中文档。
  • 协作：全部模块，主验收人为火眼。

5. 统一执行顺序

第一批（底座与门禁）
金仓-架构数据 + 水泉-总控台账 + 火炬-统一API + 机擎AI Agent-任务协议
        ↓
第二批（真实对接与真机）
水桥-BFF全量 + 木叶-APK v5.0.6 + 金仓-无线稳定性 + 火炬-Hook读写
        ↓
第三批（体验与收口）
木叶-管理端 + 火眼-接口/真机/视觉/24h验收 + 水泉-需求回写

6. 每个功能对话的首条任务提示词模板

你是【{角色}】，负责工作手机项目的【{模块}】。
项目根目录：/Users/karuo/Documents/开发/2、私域银行/工作手机
先读：开发文档/1、需求/修改/工作手机_进行中_20260613.md、开发文档/10、项目管理/开发进度总表.md、本文件中对应模块。
只修改任务范围内文件，不删除历史对话和既有验收证据。
交付：变更摘要、文件清单、接口/数据影响、测试命令与结果、截图/日志证据、风险和遗留项。
完成前把结果回报给：水泉·项目总控。

7. 原有对话保留与新增对话规则

  1. 原有 Codex/Cursor/Manus 对话、Mongo 对话汇总和历史文档全部保留。
  2. 本文件是新增的项目拆解对话，不代表删除或替换历史对话。
  3. 后续每个模块可以在当前工作手机项目下建立独立对话，标题按 五行｜Agent ·功能名称 命名。
  4. 总控对话只负责拆解、调度、验收、汇总和回写，不在总控中堆叠所有代码修改。
  5. 机擎AI Agent 的执行结果必须附带设备、技能、通道、步骤、trace_id 和原始回执。
  6. 旧任务若已完成，标记为已验收/已回写；不因重新拆解而重复开发。

7.1 对话名称优先定位规则

  1. 每个线程的当前实际名称是职责、模块、主责人和汇报归属的唯一定位真源。
  2. 线程改名后，立即按新名称重新定位，不继续沿用旧名称的人设和功能边界。
  3. 所有进度播报、任务派发、验收回报和总控汇总，优先使用当前实际名称。
  4. threadId 仅用于技术索引、线程操作和历史追踪，不作为对外业务定位名称。
  5. 文档索引、任务台账、线程标题不一致时，以线程当前实际名称为准，并在下一轮同步文档。
  6. 对话名称发生变化时，必须同步检查：主责 Agent、协作 Agent、代码范围、验收标准和回报对象。

8. 当前最优先的 8 个开发动作

  • P0-01：用有效租户 JWT 完成 BFF 33/33 全量回归。
  • P0-02：USB 覆盖安装 APK 5.0.6/code 11，补真机截图和版本回读。
  • P0-03：定义机擎AI Agent 统一任务协议、trace_id、步骤回执和事件格式。
  • P0-04：完成 Hook 测试机 ping/profile/send/messages 四项真实 RPC。
  • P0-05：完成写类白名单矩阵，使用 dry_run/confirm 和真实回读。
  • P0-06：把实时状态和事件接入管理端设备详情、任务页和风险页。
  • P0-07：完成 SDK/WS/ADB/前台服务/微信保活 24 小时长跑。
  • P0-08：火眼统一回收证据，水泉回写需求、进度、API 与迭代记录。

9. 变更记录

日期 变更
2026-07-20 初版建立：按真实代码和现有文档拆解 12 个功能对话，加入机擎AI Agent 角色，不删除历史对话。