phone-copilot 0.1.0

An AI-powered mobile task automation assistant with support for both Android and HarmonyOS.

Phone Copilot

English README

项目介绍

Phone Copilot 是一个参考 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)

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

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 使用

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 使用

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'))