workphone-sdk/README.md

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

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

主要入口

内容	路径
完整开发文档	开发文档/工作手机开发文档.md
系统架构	开发文档/2、架构/01-总览/系统架构.md
项目目录总览	开发文档/2、架构/01-总览/项目目录总览.md
操作手册	开发文档/9、手册/工作手机·五图总览与使用手册.md
项目管理	开发文档/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

项目结构

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

快速开始

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

检查服务：

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

Android APK 构建

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、签名密码和真实用户数据禁止提交仓库。
• 代码变更必须同步更新开发文档和验收记录。

详细说明见：工作手机开发文档。