dc35fb8bbc
将原 6、测试 迁入 8、部署/05-测试验收，接口矩阵与开发日志并入 5、接口/06-验收与矩阵，项目总览与平台分析分别归位至 2、架构与 1、需求；同步 Obsidian、机擎规范与路径校验脚本。 Co-authored-by: Cursor <cursoragent@cursor.com>
110 lines
4.9 KiB
Markdown
110 lines
4.9 KiB
Markdown
# 工作手机SDK v3.0
|
||
|
||
> 存客宝的 AI 手机控制引擎 — 替代奥创，统一控制微信/抖音/小红书/闲鱼等
|
||
> **完整手册**：[开发文档/9、手册/工作手机·五图总览与使用手册.md](../开发文档/9、手册/工作手机·五图总览与使用手册.md)（v2.1）
|
||
> **仓库结构**：[开发文档/2、架构/01-总览/项目目录总览.md](../开发文档/2、架构/01-总览/项目目录总览.md)
|
||
|
||
## 项目模块结构
|
||
|
||
```
|
||
sdk/
|
||
├── app/ # 服务端（FastAPI）
|
||
│ ├── main.py # 入口：健康检查、/ready、WebSocket 设备接入
|
||
│ ├── config.py # 配置：MongoDB/Redis/超时/心跳
|
||
│ ├── routers/ # API 路由
|
||
│ │ ├── unified.py # 统一接口（消息/好友/群聊/标签/朋友圈）— 存客宝调用入口
|
||
│ │ ├── devices.py # 设备管理 REST
|
||
│ │ ├── agent.py # AI Agent 任务
|
||
│ │ ├── adb.py # ADB 设备控制
|
||
│ │ ├── capture.py # 抓包（可选）
|
||
│ │ ├── ws_device.py # WebSocket 设备连接管理
|
||
│ │ ├── voice.py # 语音控制
|
||
│ │ ├── projects.py # 项目管理
|
||
│ │ ├── qrcode.py # 二维码绑定
|
||
│ │ └── experience.py # 经验库
|
||
│ ├── services/ # 业务逻辑层
|
||
│ │ ├── ws_hub.py # WebSocket Hub（设备连接池、命令下发、event/device_request 处理）
|
||
│ │ ├── device_manager.py # 设备状态持久化（MongoDB）
|
||
│ │ ├── adb_device.py # ADB 设备操作
|
||
│ │ ├── ai_agent.py # AI Agent 服务（LLM 规划）
|
||
│ │ └── experience_db.py # 经验库
|
||
│ ├── skills/ # 服务端 Skill 定义（供 ADB 模式）
|
||
│ │ ├── wechat/ # 微信
|
||
│ │ ├── douyin/ # 抖音
|
||
│ │ ├── xhs/ # 小红书
|
||
│ │ └── xianyu/ # 闲鱼
|
||
│ └── static/ # Web 控制台
|
||
│ └── index.html # 苹果毛玻璃风格控制中心
|
||
│
|
||
├── agent/ # 设备端（安装在手机/模拟器上）
|
||
│ ├── agent.py # Agent 主进程（WebSocket 连接、心跳、命令执行）
|
||
│ ├── skill_executor.py # 技能执行器（命令解析→Skill 分发）
|
||
│ ├── error_handler.py # 统一错误处理与重试
|
||
│ ├── vision_helper.py # 截屏+AI 视觉
|
||
│ ├── voice_agent.py # 语音命令
|
||
│ ├── config.json # 设备端配置（device_id、server_url、心跳）
|
||
│ ├── install.sh # 一键安装
|
||
│ └── skills/ # 设备端 Skill 实现
|
||
│ ├── base.py # BaseSkill（UI 操作基类）
|
||
│ ├── wechat/ # 微信（消息/好友/群聊/标签/朋友圈/批量）
|
||
│ ├── douyin/ # 抖音（私信/粉丝/评论/视频互动）
|
||
│ ├── xhs/ # 小红书（私信/粉丝/笔记/评论）
|
||
│ ├── xianyu/ # 闲鱼（私信/关注）
|
||
│ ├── app_manager.py # APP 管理
|
||
│ ├── search.py # 通用搜索
|
||
│ └── voice_control.py # 语音/自然语言命令
|
||
│
|
||
├── php-sdk/ # 中间层：PHP SDK（存客宝后端调用）
|
||
│ └── WorkPhoneClient.php
|
||
│
|
||
├── typescript-sdk/ # 中间层：TypeScript SDK
|
||
│ └── index.ts
|
||
│
|
||
├── tests/ # 测试
|
||
│ ├── test_wechat_e2e.py # 微信 E2E 端到端
|
||
│ ├── test_api.py # API 测试
|
||
│ └── test_full_system.py
|
||
│
|
||
├── scripts/ # 脚本
|
||
│ ├── start_sdk.sh # 一键启动（服务端+Agent）
|
||
│ ├── setup_emulator.sh # 一键模拟器设置（红米13+中文+搜狗五笔+Agent）
|
||
│ └── check_sdk.sh # 系统检查
|
||
│
|
||
├── apks/ # APK 文件（搜狗五笔等）
|
||
├── docker-compose.yml # Docker 部署
|
||
├── Dockerfile
|
||
└── requirements.txt
|
||
```
|
||
|
||
## 快速启动
|
||
|
||
```bash
|
||
# 1. 启动 SDK 服务
|
||
cd sdk && ./scripts/start_sdk.sh
|
||
|
||
# 2. 设置模拟器（创建红米13 AVD + 中文 + 搜狗五笔 + Agent）
|
||
./scripts/setup_emulator.sh
|
||
|
||
# 3. 打开控制中心
|
||
open http://localhost:8899/static/index.html
|
||
```
|
||
|
||
## 控制台
|
||
|
||
苹果毛玻璃风格 Web 控制中心：`http://localhost:8899/static/index.html`
|
||
|
||
- 设备列表、在线状态
|
||
- 快捷操作（截屏/打开微信/抖音/小红书/闲鱼/返回/主页）
|
||
- 命令输入（AI Agent 自然语言任务）
|
||
- 实时日志
|
||
- 设备截屏预览
|
||
- 设备详情（型号/已装APP/能力）
|
||
|
||
## API
|
||
|
||
- 健康检查：`GET /health`
|
||
- 就绪探针：`GET /ready`
|
||
- API 文档：`GET /docs`
|
||
- 统一接口：`POST /api/v3/unified/*`
|
||
- 设备管理：`GET/POST /api/v3/devices/*`
|