phone-use

用一句话驱动真机安卓手机完成 WLAN 测试任务，并返回结论与证据。

输入  连 test-portal2 做 portal 认证，账号 zjb 密码 123456
输出  RESULT: PASS
      证据：SSID / BSSID / 频点 / RSSI / MAC / IP / 认证返回码 / 外网核验 / 截图路径
      轨迹：/opt/phone-use/pu/logs/run-.jsonl

1. 环境要求

2. 安装

# 1) 部署服务
scp src/*.py deploy/*.env deploy/phone-farm deploy/phone-use deploy/install-all.sh \
    deploy/install-frozen-base.sh deploy/units/*.service \
    docs/SKILL-phone-use-wlan.md docs/ONBOARD.md docs/AGENT-PROMPT.md tools/pu-node.py \
    root@:/tmp/
ssh root@ bash /tmp/install-all.sh

# 2) 冻结底层并生成校验清单
ssh root@ bash /tmp/install-frozen-base.sh

# 3) 安装任务主体并生成项目级配置
scp deploy/install-qwen-agent.sh root@:/tmp/
ssh root@ bash /tmp/install-qwen-agent.sh

安装后填写模型密钥：编辑 /opt/phone-use/pu/.qwen/settings.json 中的 env.OPENAI_API_KEY。

3. 启动与状态

phone-farm start               # 启动全部服务
phone-farm status              # 服务、端口、终端就绪情况
phone-farm logs phone-agent    # 查看服务日志
phone-farm config              # 查看生效配置

端口与页面：

浏览器访问 http://:8910/。

4. 使用

4.1 一句话任务

phone-use "连 test-portal2 做 portal 认证，账号 zjb 密码 123456"
phone-use "连 928wpa2-psk 密码 12345678"
phone-use "连 HY-CJ1-WPA2-L 做 1X 认证，账号 hx 密码 123456"
phone-use "体检一下 57ada8"

参数：

每次运行在 /opt/phone-use/pu/logs/ 生成三个文件：

4.2 原语

原语为单步动作，供任务主体调用，输出单行 JSON。

phone-hand state                        # 设备状态
phone-hand wifi                         # 当前连接信息
phone-hand probe                        # 门户拦截探测
phone-hand scan portal                  # 扫描指定关键字
phone-hand tap 540 600                  # 坐标点击
phone-hand click-text "登录"            # 按文本点击
phone-hand settext --id !account zjb    # 输入文本
phone-hand shot /sdcard/s.png           # 截图
phone-hand pull /sdcard/s.png /tmp/s.png
phone-hand wifi-connect  wpa2  --bssid 
phone-hand jar portal-login  

完整列表见 phone-hand --help。

4.3 屏幕识别

phone-look  "当前是什么页面？"
phone-look  --coord "WLAN 列表中的 test-portal2"

输出页面与控件的文本结论；使用 --coord 时附带可点击坐标。

4.4 HTTP 接口

同步调用，短任务使用：

curl -X POST http://:8902/task -H 'Content-Type: application/json' \
     -d '{"text":"连 928wpa2-psk 密码 12345678","device":"auto","max_steps":40}'

异步调用，长任务使用：先取作业号，再轮询，可随时取消。

curl -X POST http://:8902/tasks -H 'Content-Type: application/json' \
     -d '{"text":"连 test-portal2 做 portal 认证，账号 zjb 密码 123456","device":"auto"}'
# → {"id":"job003","status":"running", ...}

curl http://:8902/tasks/job003                      # 查进度与结果
curl -X POST http://:8902/tasks/job003/cancel       # 取消并释放终端

请求字段：text（必填）、device（默认 auto）、max_steps（步数上限，可选）。

返回字段，同步与异步一致：

异步作业的 status 取值：running / done / failed / cancelled。

本机 MCP 工具面另提供 phone_task(text, device, max_steps, timeout_s)，走同一异步接口，字段与上表一致。

网络 MCP 服务 phone-mcp 监听 8903，路径 /mcp，传输 streamable-http，工具面与上表一致：

工具：devices_list · phone_task · phone_exec · phone_skill · lease_device · release_device
地址：http://:8903/mcp

客户端只需配置该地址；接入方法与工具清单见 docs/MCP.md。鉴权可选，设置 /opt/phone-mcp/mcp.env 的 PHONE_MCP_TOKEN 后需带 Authorization: Bearer 。

4.5 新机接入

phone-doctor 

逐项体检 USB 调试、点击能力、自动连网、电量、时间同步等；检查项与解决办法见 docs/ONBOARD.md。

5. 技能与提示词

任务主体的行为由以下文件决定：

新增机型适配写入 /opt/phone-use/work/adapt/.yaml。

6. 目录结构

src/      服务源码：原语、农场 API、任务入口、体检、浏览器界面
deploy/   部署文件：安装脚本、统一入口 CLI、配置、systemd 单元
tools/    辅助脚本
ops/      运维与排障脚本
docs/     使用与实现文档
legacy/   已淘汰组件

7. 常见问题