# 工作手机 SDK v3.0 / v4.0

工作手机项目的代码与文档真源。项目提供云端 API、WebSocket 设备连接、Android Agent、统一 APK、Frida Hook、无障碍控制、ADB 运维与真机验收体系，用于统一管理和控制 Android 工作手机。

## 主要入口

| 内容 | 路径 |
|---|---|
| **完整开发文档** | [开发文档/工作手机开发文档.md](开发文档/工作手机开发文档.md) |
| 系统架构 | [开发文档/2、架构/01-总览/系统架构.md](开发文档/2、架构/01-总览/系统架构.md) |
| 项目目录总览 | [开发文档/2、架构/01-总览/项目目录总览.md](开发文档/2、架构/01-总览/项目目录总览.md) |
| 操作手册 | [开发文档/9、手册/工作手机·五图总览与使用手册.md](开发文档/9、手册/工作手机·五图总览与使用手册.md) |
| 项目管理 | [开发文档/10、项目管理/](开发文档/10、项目管理/) |
| 本地控制台 | 启动后访问 `http://127.0.0.1:8899/hub` |
| Swagger | 启动后访问 `http://127.0.0.1:8899/docs` |
| OpenAPI | 启动后访问 `http://127.0.0.1:8899/openapi.json` |

## 项目结构

```text
sdk/app/          # FastAPI、API 路由、WebSocket Hub、设备与任务服务
sdk/agent/        # Python Agent、无线 Agent、Frida 管理和 Hook 脚本
sdk/android-app/  # Android 统一 APK，Kotlin/Gradle 工程
开发文档/         # 需求、架构、接口、设备、部署、测试和项目管理
```

## 快速开始

```bash
cd sdk
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cd app
python -m uvicorn main:app --host 0.0.0.0 --port 8899 --reload
```

检查服务：

```bash
curl http://127.0.0.1:8899/health
curl http://127.0.0.1:8899/openapi.json
```

## Android APK 构建

```bash
cd sdk/android-app
./gradlew clean assembleDebug
```

## 核心控制通道

1. Frida Hook：Root 或 Gadget 环境下的内部能力调用。
2. WebSocket Agent：云端与设备之间的实时双向通信。
3. Accessibility：非 Root 环境的 UI 自动化。
4. AI Agent：复杂流程和页面变化下的辅助决策。
5. Shell / ADB：安装、启动、调试和批量部署兜底。

## 开发铁律

- 所有关键功能以真实 Android 设备验收。
- 不得使用固定 JSON、模拟响应或前端假状态冒充成功。
- 每条指令必须通过 `command_id` 完成全链路追踪。
- 密钥、Token、签名密码和真实用户数据禁止提交仓库。
- 代码变更必须同步更新开发文档和验收记录。

详细说明见：[工作手机开发文档](开发文档/工作手机开发文档.md)。