6.4 KiB
6.4 KiB
工作手机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、需求 | 分层 01-概述/ 02-业务/ 03-调研/；修改/ 增量 |
需求与澄清 |
| 2、架构 | 分层目录 01-总览/ 02-技术基座/ 03-通道与设备/ 04-交互图/ 05-规范/；PNG 在 images/01～04/ |
架构与 §3.0 模块拆解；规范见 机擎/阿表/开发文档结构规范 |
| 3、原型 | 分层 01-规范/ |
原型规范 |
| 4、前端 | 分层 01-通用规范/ 02-管理端/ 03-工具/ |
前端规范 |
| 5、接口 | 分层 01-规范与统一层/～05-交互图/；OpenAPI 在 04-OpenAPI/ |
API 与对接 |
| 6、后端 | 分层 01-服务端/ 02-设备端/ 03-规范汇总/；docs/、github-repos/ 不动 |
服务端+Agent+规范 |
| 7、数据库 | 分层 01-设计/ 02-规范/ |
数据层 |
| 8、部署 | 分层 01-本地环境/ 02-设备Hook/ 03-运维同步/ |
部署与凭证 |
| 9、手册 | 主手册根目录 + 02-操作指南/ 03-验证/ 04-专项/；images/fig01～09 |
操作与验证 |
| 10、项目管理 | 根目录真源 3 文件 + 02-测试报告/ 03-计划与专项/ |
进度与验收（唯一进度入口） |
| 平台分析 | 按平台分子目录 | 各平台专项：接口+功能+自动化方案统一放此处 |
| 平台分析/Soul/ | Soul项目分析、Soul自动化方案与命令行操作 | Soul 全部内容集中此目录 |
快速启动（SDK）
cd sdk && ./scripts/start_sdk.sh
路径以「工作手机」项目根目录为基准。详见 9、手册/02-操作指南/SDK操作手册.md
统一测试账号：15880802661 / kr123456（详见 8、部署/01-本地环境/本地环境凭证.md）