9118df9eee
Some checks failed
SDK CI / python-compile (push) Has been cancelled
- 新增 sdk/app/agent（Hook/Skills/Anti-ban 等）及 NAS/ADB 脚本 - 更新 Android 端、unified、PHP SDK、Docker Compose - Soul 文档迁移至 Soul调研/；移除资料目录内 APK - .gitignore 排除 sdk/tmp、sdk/logs、sdk/tmp_rom Co-authored-by: Cursor <cursoragent@cursor.com>
156 lines
4.9 KiB
Markdown
156 lines
4.9 KiB
Markdown
# 工作手机Agent v3.0 - 设备端客户端
|
||
|
||
> 运行在 Android 手机上的 AI 数字员工，通过 WebSocket 连接服务器，实现远程智能控制。
|
||
|
||
## 架构
|
||
|
||
```
|
||
手机端 Agent (Python/Termux)
|
||
├── WebSocket 长连接 → 服务器 SDK (FastAPI)
|
||
├── 技能引擎 → 微信/抖音/小红书/闲鱼 自动化
|
||
├── 语音控制 → 本地语音命令
|
||
└── AI视觉 → 截屏+AI看屏决策
|
||
|
||
↕ uiautomator2 + ADB
|
||
手机 Android 系统 + 微信/抖音等 APP
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 方式 1: Termux 一键安装（推荐）
|
||
|
||
```bash
|
||
# 手机安装 Termux 后，在 Termux 中执行:
|
||
curl -sL http://服务器IP:8899/install.sh | bash -s -- --server ws://服务器IP:8899/ws/device
|
||
|
||
# 启动 Agent
|
||
bash ~/workphone-agent/start.sh
|
||
```
|
||
|
||
### 方式 2: 通过 ADB 推送
|
||
|
||
```bash
|
||
# 在电脑上执行
|
||
cd sdk/agent
|
||
bash package.sh # 先打包
|
||
adb push dist/agent.tar.gz /data/local/tmp/
|
||
adb shell "mkdir -p /data/local/tmp/workphone-agent && \
|
||
cd /data/local/tmp/workphone-agent && \
|
||
tar xzf /data/local/tmp/agent.tar.gz"
|
||
|
||
# 在手机上运行（需要 Termux 环境）
|
||
cd /data/local/tmp/workphone-agent
|
||
python3 agent.py -s ws://服务器IP:8899/ws/device
|
||
```
|
||
|
||
### 方式 3: 手动安装
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 编辑配置
|
||
cp config.json.example config.json
|
||
vim config.json # 修改 server_url
|
||
|
||
# 运行
|
||
python3 agent.py
|
||
```
|
||
|
||
## 配置
|
||
|
||
编辑 `config.json`（`server_url` 填**基础地址**，程序会自动拼上 `/设备ID`）:
|
||
|
||
```json
|
||
{
|
||
"device_id": "",
|
||
"server_url": "ws://192.168.1.100:8899/ws/device",
|
||
"heartbeat_interval": 10,
|
||
"project_id": "cunkebao"
|
||
}
|
||
```
|
||
|
||
### 配置优先级
|
||
|
||
环境变量 > 命令行参数 > config.json > 默认值
|
||
|
||
| 环境变量 | 命令行 | config.json | 说明 |
|
||
|---------|--------|------------|------|
|
||
| `WP_DEVICE_ID` | `-d, --device-id` | `device_id` | 设备ID（留空自动检测） |
|
||
| `WP_SERVER_URL` | `-s, --server` | `server_url` | WebSocket 基础地址 |
|
||
| `WP_HEARTBEAT` | `--heartbeat` | `heartbeat_interval` | 心跳间隔（秒），建议 5/10/30 |
|
||
| `WP_PROJECT_ID` | `-p, --project` | `project_id` | 项目ID |
|
||
|
||
## 管理命令
|
||
|
||
```bash
|
||
cd ~/workphone-agent
|
||
|
||
bash start.sh # 前台启动（可看实时日志）
|
||
bash start_bg.sh # 后台启动
|
||
bash stop.sh # 停止
|
||
bash status.sh # 查看状态
|
||
tail -f agent.log # 跟踪日志
|
||
```
|
||
|
||
## 功能
|
||
|
||
- **WebSocket 长连接** — 设备主动连接服务器，断线指数退避重连（2s → 30s）
|
||
- **心跳保活** — 应用层心跳 + 连续 3 次无响应自动断开重连
|
||
- **设备注册** — 启动后自动注册，上报能力（已安装APP、支持的Skill）
|
||
- **远程命令** — 接收 `execute` / `agent_execute` 命令，本地执行后返回结果
|
||
- **技能系统** — 微信/抖音/小红书/闲鱼 完整 Skill（发消息、加好友、刷视频等）
|
||
- **事件上报** — 技能执行完毕、异常等事件实时回传服务器
|
||
- **AI视觉** — 截屏 + Gemini 看屏，智能决策下一步操作
|
||
- **语音控制** — 支持本地语音命令（需安装 SpeechRecognition）
|
||
- **信号处理** — 优雅关闭（SIGINT / SIGTERM）
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
agent/
|
||
├── agent.py # 主程序入口（WebSocket + 命令分发）
|
||
├── skill_executor.py # 技能执行器（命令 → Skill 路由）
|
||
├── skill_bus.py # 技能间通信总线
|
||
├── error_handler.py # 错误处理与重试
|
||
├── vision_helper.py # AI视觉（截屏+看屏）
|
||
├── voice_agent.py # 语音控制Agent
|
||
├── config.json # 运行配置
|
||
├── config.json.example # 配置模板
|
||
├── requirements.txt # Python 依赖
|
||
├── install.sh # Termux 一键安装脚本
|
||
├── package.sh # 打包脚本（生成 dist/agent.tar.gz）
|
||
├── README.md # 本文件
|
||
└── skills/
|
||
├── __init__.py # 技能注册表
|
||
├── base.py # 技能基类（UI操作、重试、安全点击）
|
||
├── voice_control.py # 语音命令解析
|
||
├── app_manager.py # 应用管理（打开/关闭/切换）
|
||
├── search.py # 通用搜索技能
|
||
├── wechat/skill.py # 微信技能（完整SCRM）
|
||
├── douyin/skill.py # 抖音技能
|
||
├── xhs/skill.py # 小红书技能
|
||
└── xianyu/skill.py # 闲鱼技能
|
||
```
|
||
|
||
## 服务端接口
|
||
|
||
| 接口 | 说明 |
|
||
|------|------|
|
||
| `GET /install.sh` | 获取安装脚本 |
|
||
| `GET /api/v3/agent/download` | 下载 Agent 打包文件 |
|
||
| `WS /ws/device/{device_id}` | WebSocket 设备连接 |
|
||
| `GET /health` | 服务器健康检查 |
|
||
|
||
## 开机自启
|
||
|
||
安装 [Termux:Boot](https://f-droid.org/packages/com.termux.boot/) 后，`install.sh` 会自动创建开机启动脚本。
|
||
|
||
## 依赖
|
||
|
||
- Python 3.8+
|
||
- websockets >= 12.0
|
||
- uiautomator2 >= 3.0.0
|
||
- adbutils >= 2.0.0
|
||
- httpx >= 0.25.0（可选，AI视觉用）
|