# 工作手机SDK v3.0

> 存客宝的 AI 手机控制引擎 — 替代奥创，统一控制微信/抖音/小红书/闲鱼等  
> **完整手册**：[开发文档/9、手册/工作手机·五图总览与使用手册.md](../开发文档/9、手册/工作手机·五图总览与使用手册.md)（v2.1）

## 项目模块结构

```
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/*`