# 工作手机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视觉用）