feat: publish workphone SDK deployment and API docs

2026-07-14 18:10:52 +08:00
commit 021d633cc1
534 changed files with 122391 additions and 0 deletions
--- a/sdk/agent/README.md
+++ b/sdk/agent/README.md
@@ -0,0 +1,155 @@
+# 工作手机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视觉用）