workphone-sdk/sdk/agent

工作手机Agent v3.0 - 设备端客户端

运行在 Android 手机上的 AI 数字员工，通过 WebSocket 连接服务器，实现远程智能控制。

架构

手机端 Agent (Python/Termux)
├── WebSocket 长连接 → 服务器 SDK (FastAPI)
├── 技能引擎 → 微信/抖音/小红书/闲鱼 自动化
├── 语音控制 → 本地语音命令
└── AI视觉  → 截屏+AI看屏决策

↕ uiautomator2 + ADB
手机 Android 系统 + 微信/抖音等 APP

快速开始

方式 1: Termux 一键安装（推荐）

# 手机安装 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 推送

# 在电脑上执行
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: 手动安装

# 安装依赖
pip install -r requirements.txt

# 编辑配置
cp config.json.example config.json
vim config.json  # 修改 server_url

# 运行
python3 agent.py

配置

编辑 config.json（server_url 填基础地址，程序会自动拼上 /设备ID）:

{
  "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

管理命令

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 后，install.sh 会自动创建开机启动脚本。

依赖

• Python 3.8+
• websockets >= 12.0
• uiautomator2 >= 3.0.0
• adbutils >= 2.0.0
• httpx >= 0.25.0（可选，AI视觉用）