phone-copilot 0.1.0
An AI-powered mobile task automation assistant with support for both Android and HarmonyOS.
Requires Python: >=3.12

# Phone Copilot

[English README](README_EN.md)

<p align="center">
    <img src="logo.svg" alt="logo.svg" width="200" height="200">
</p>

## 项目介绍

Phone Copilot 是一个参考 [Open-AutoGLM](https://github.com/zai-org/Open-AutoGLM) 的基于 AI 构建的手机端智能助理框架，它能够以多模态方式理解手机屏幕内容，并通过自动化操作帮助用户完成任务。

系统通过 ADB 或 HDC 来控制 Android 和 HarmonyOS 设备，以视觉语言模型进行屏幕感知，再结合智能规划能力生成并执行操作流程。用户只需用自然语言描述需求，如“打开高德地图，导航至南京南高铁站”，Phone Agent 即可自动解析意图、理解当前界面、规划下一步动作并完成整个流程。

https://github.com/user-attachments/assets/e60e118e-7cec-4bba-9e8a-38054069cc9f

## 环境准备

1. Python >= 3.12
2. Android 设备需要安装 adb，并配置环境变量。HarmonyNext 设备需要安装 hdc，并配置环境变量
3. 手机需要启动开发者模式，并且打开 USB 调试选项
4. 如果 Android 设备需要输入中文，需要额外安装 ADB Keyboard
5. 本地通过 `vllm` 部署模型，或者使用远端模型 API, 建议使用 `AutoGLM-Phone-9B`

## 快速开始

### uv (recommend)

```shell
pip install uv

# 使用 model scope api, https://modelscope.cn/models/ZhipuAI/AutoGLM-Phone-9B
uvx phone-copilot "打开高德地图，导航至南京南高铁站" --base-url "https://api-inference.modelscope.cn/v1" --model "ZhipuAI/AutoGLM-Phone-9B" --api-key "替换为你的 Token" --json "demo.json" --html "demo.html"
```

### pip

```shell
pip install phone-copilot

# 使用 model scope api, https://modelscope.cn/models/ZhipuAI/AutoGLM-Phone-9B
phone-copilot "打开高德地图，导航至南京南高铁站" --base-url "https://api-inference.modelscope.cn/v1" --model "ZhipuAI/AutoGLM-Phone-9B" --api-key "替换为你的 Token" --json "demo.json" --html "demo.html"
```

## 命令行参数

| 参数 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `task`（位置参数） | 是 | - | 要执行的任务描述（自然语言）。示例：`"打开高德地图，导航至南京南高铁站"` |
| `--base-url` | 是 | - | 模型 API 的 Base URL（OpenAI 兼容）。示例：`https://api-inference.modelscope.cn/v1` 或本地 `http://localhost:8000/v1` |
| `--model` | 是 | - | 使用的模型名称。示例：`ZhipuAI/AutoGLM-Phone-9B` |
| `--api-key` | 否 | 空字符串 | 调用模型 API 的鉴权 Token / API Key。若使用本地部署或无需鉴权可不传 |
| `--device, -d` | 否 | 自动选择 | 目标设备 ID。不指定时默认选择第一个已连接设备 |
| `--lang, -l` | 否 | `zh` | 系统提示词语言：`zh` 或 `en` |
| `--max-steps` | 否 | `100` | Agent 最大执行步数，超过后停止 |
| `--ccf` | 否 | `1000` | 坐标/压缩因子（用于适配不同模型的坐标系）。通常：Qwen 系列设为 `0`，AutoGLM 系列设为 `1000` |
| `--json` | 否 | - | 保存执行过程的 JSON 报告路径；会自动使用 `.json` 后缀（例如传 `demo` 也会保存为 `demo.json`） |
| `--html` | 否 | - | 保存执行过程的 HTML 报告路径；会自动使用 `.html` 后缀 |
| `--adb-keyboard` | 否 | `false` | 启用 Android 的 ADB Keyboard（用于中文输入等）。会自动安装 ADB Keyboard 并设置为当前键盘 |

## 代码运行

### 通过 High API 使用

```python
from pathlib import Path
from phone_copilot.api import run_task

agent = run_task(
    task='打开高德地图，导航至南京南高铁站',
    base_url='https://api-inference.modelscope.cn/v1',
    model='ZhipuAI/AutoGLM-Phone-9B',
    api_key='替换为你的 Token'
)

agent.export_html(Path('demo.html'))
agent.export_json(Path('demo.json'))
```

### 通过 Agent 和 Model Client 使用

```python
from pathlib import Path

from phone_copilot.agent import Agent
from phone_copilot.device import detect_device
from phone_copilot.model_client import ModelClient

agent = Agent(
    device=detect_device(),
    model_client=ModelClient(
        base_url='https://api-inference.modelscope.cn/v1',
        model='ZhipuAI/AutoGLM-Phone-9B',
        api_key='替换为你的 Token'
    ),
)

agent.run(task='打开高德地图，导航至南京南高铁站')

agent.export_html(Path('demo.html'))
agent.export_json(Path('demo.json'))
```