workphone-sdk/开发文档/README.md

工作手机SDK v3.0 - 开发文档

📖 必读 · 完整整合手册（补全包已并入）

9、手册/工作手机·五图总览与使用手册.md — v2.1
五图架构 + 补全包九模块 + API + 真机验收 + 无线 Frida · 一份读通

管理Skill：本项目目录下 机擎/SKILL.md（火炬总控，五人分配：阿表/阿机/阿桥/阿端/阿服）
更新：2026-05-24 | 当前项目状态：总进度 99.5%
约定：所有开发文档内容仅在本目录下；根目录仅保留本 README，不得在根目录放置其他 .md 或文档；所有内容归入子目录，不散落——按「四类分类」各就各位；Soul 相关内容统一放在 平台分析/Soul/，不与其他目录混放。

---

项目管理规则（必守）

机擎负责所有项目管理、人员安排、全员学习开发文档；每次开发由机擎安排任务。

• Skill 位置：机擎/SKILL.md（火炬总控，阿表/阿机/阿桥/阿端/阿服 按岗位分配）。与卡若AI 为交互关系：卡若AI 涉及工作手机时读取该 Skill 并按其规则执行。
• 开发文档归属：所有开发文档内容必须在 工作手机/开发文档/ 目录下；不在此目录外新增或生成开发文档类内容；新增文档归入对应子目录（1、需求 … 10、项目管理；平台分析按平台分子目录，如 Soul）。
• 每次开发：由机擎整理项目（读进度总表、工作日志、状态检查）→ 安排、分配任务 → 执行并更新文档。

---

项目简述

工作手机SDK v3.0 是存客宝的 AI 手机控制引擎，用于替代奥创，实现：

• 存客宝/触客宝通过统一 API 控制手机（微信、抖音、小红书、闲鱼等）
• 设备主动连接云端（WebSocket）、心跳可配置、指令 ACK
• 服务端 FastAPI + WebSocket Hub + 脚本引擎（Skill），设备端 Agent + uiautomator2
• 数据闭环：MySQL（存客宝）+ MongoDB（workphone_sdk）+ Redis

当前状态：M1～M4、M7～M11 已 100%，M5 脚本引擎约 75%、M8 Agent 约 95%，M6 抓包待做、M12 AI Agent 约 50%。

---

开发文档规则（与全站一致，机擎保证执行）

• 每目录除 README 外最多 3 个主文档（基础规则）；超出须合并，与全栈开发文档规则一致。
• 超过 3 个时：必须启动整文件合并，将多篇合并为 ≤3 个主文档；合并时不得导致数据和相关内容丢失（可合并为同一文档内多章节或附录）。
• 子目录（如 6、后端 下的 github核心代码/、docs/）不计入「3 个主文档」数量。

---

进度只看两处（单一进度视图）

文档	说明
10、项目管理/开发进度总表.md	唯一进度文档：按模块 M1～M12 的完成度、待办、验证方式
2、架构/01-总览/系统架构.md § 3.0	模块拆解基准：需求→任务→进度对应表

看进度时：先看 开发进度总表，再按需看 系统架构 § 3.0 的模块拆解。

---

开发文档四类分类（文档各就各位，不散落）

开发文档按 4 类 归纳，现有文档分别归属以下 4 类，便于查找与维护：

分类	所含目录	说明
一、需求与架构	1、需求；2、架构；3、原型	需求、架构设计、原型规范
二、开发与接口	4、前端；5、接口；6、后端	前端/接口/后端实现与规范
三、部署与数据	7、数据库；8、部署	数据库、部署与凭证
四、手册、验收与平台分析	9、手册；10、项目管理；平台分析	操作手册、进度验收；各平台（如 Soul）专项分析统一放在「平台分析」

• 平台分析：按平台分子目录（如 平台分析/Soul/），该平台的所有文档（项目分析、接口与功能清单、自动化方案等）只放在该平台目录内，不散落在 1～10 其他目录。
• 根目录不放置除本 README 以外的文档。

---

开发文档结构（子目录与主文档）

目录	主文档（≤3）	说明
1、需求	项目概述、业务需求、技术调研与方案选型	需求与澄清
2、架构	分层目录 01-总览/ 02-技术基座/ 03-通道与设备/ 04-交互图/ 05-规范/；PNG 在 images/01～04/	架构与 §3.0 模块拆解；规范见 机擎/阿表/开发文档结构规范
3、原型	原型设计规范	原型规范
4、前端	前端开发规范、管理端前端开发规范、v0配置	前端规范
5、接口	分层 01-规范与统一层/～05-交互图/；OpenAPI 在 04-OpenAPI/	API 与对接
6、后端	分层 01-服务端/ 02-设备端/ 03-规范汇总/；docs/、github-repos/ 不动	服务端+Agent+规范
7、数据库	数据库设计文档、数据库管理规范	数据层
8、部署	本地Docker部署指南、设备端Hook安装部署、本地环境凭证	部署与凭证
9、手册	工作手机·五图总览与使用手册（v2.0 主入口）、SDK操作手册、微信消息E2E验证指南	操作与验证；补全包文档已并入总览手册
10、项目管理	开发进度总表、工作日志、验收与项目说明	进度与验收（唯一进度入口）
平台分析	按平台分子目录	各平台专项：接口+功能+自动化方案统一放此处
平台分析/Soul/	Soul项目分析、Soul自动化方案与命令行操作	Soul 全部内容集中此目录

---

快速启动（SDK）

cd sdk && ./scripts/start_sdk.sh

路径以「工作手机」项目根目录为基准。详见 9、手册/SDK操作手册.md

统一测试账号：15880802661 / kr123456（详见 8、部署/本地环境凭证.md）