phone-copilot 0.1.0__tar.gz

phone_copilot-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.3
+Name: phone-copilot
+Version: 0.1.0
+Summary: An AI-powered mobile task automation assistant with support for both Android and HarmonyOS.
+Author: lanbaoshen
+Author-email: lanbaoshen <lanbaoshen@icloud.com>
+Requires-Dist: click>=8.3.1
+Requires-Dist: openai>=2.20.0
+Requires-Dist: pillow>=12.1.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: xpdc>=0.1.2
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# 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'))
+```

phone_copilot-0.1.0/README.md

@@ -0,0 +1,102 @@
+# 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'))
+```

phone_copilot-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "phone-copilot"
+version = "0.1.0"
+description = "An AI-powered mobile task automation assistant with support for both Android and HarmonyOS."
+readme = "README.md"
+authors = [
+    { name = "lanbaoshen", email = "lanbaoshen@icloud.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "click>=8.3.1",
+    "openai>=2.20.0",
+    "pillow>=12.1.1",
+    "pydantic>=2.12.5",
+    "xpdc>=0.1.2",
+]
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["uv_build>=0.9.30,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.5.1",
+]
+
+[project.scripts]
+phone-copilot = "phone_copilot:main"
+
+[tool.ruff]
+line-length = 120
+indent-width = 4
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pyenv",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+]
+
+lint.select = ["E", "F", "B", "W", "I", "N", "UP", "ANN", "S", "BLE", "FBT", "C4", "T10", "EM", "ISC", "ICN"]
+lint.ignore = ["ANN002", "ANN003"]
+lint.fixable = ["ALL"]
+lint.unfixable = []
+lint.dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+lint.isort.known-third-party = []
+
+format.quote-style = "single"
+format.indent-style = "space"
+format.skip-magic-trailing-comma = false
+format.line-ending = "auto"

phone_copilot-0.1.0/src/phone_copilot/__init__.py

@@ -0,0 +1,73 @@
+from pathlib import Path
+
+import click
+from loguru import logger
+
+try:
+    LOG_DIR = Path.home() / '.phone-copilot'
+    logger.add(LOG_DIR / 'log.log', rotation='10 MB')
+except Exception as e:  # noqa: BLE001
+    logger.error(f'Failed to set up logger directory: {e}')
+
+
+@click.command()
+@click.argument('task', required=True)
+@click.option('--base-url', required=True, help='The base URL of the model API.')
+@click.option('--model', required=True, help='The name of the model to use.')
+@click.option('--api-key', default='', help='The API key for authentication with the model API.')
+@click.option(
+    '--device', '-d', help='The ID of the target device. If not specified, the first connected device will be used.'
+)
+@click.option(
+    '--lang', '-l', default='zh', type=click.Choice(['zh', 'en']), help='The language for system prompts (zh or en).'
+)
+@click.option('--max-steps', default=100, help='The maximum number of steps the agent can take before giving up.')
+@click.option(
+    '--ccf',
+    default=1000,
+    help='Context Compression Factor for the agent. Like QWen Model, it should be set to 0. AutoGLM Model should be set to 1000.',  # noqa: E501
+)
+@click.option('--json', help='The json report file path to save the execution details.')
+@click.option('--html', help='The html report file path to save the execution details.')
+@click.option(
+    '--adb-keyboard',
+    is_flag=True,
+    default=False,
+    help='Enable ADB keyboard input method with the specified keyboard ID',
+)
+def main(
+    task: str,
+    base_url: str,
+    model: str,
+    api_key: str,
+    device: str,
+    lang: str,
+    max_steps: int,
+    ccf: int,
+    json: str,
+    html: str,
+    adb_keyboard: bool,  # noqa: FBT001
+) -> None:
+    from phone_copilot.api import run_task
+
+    agent = run_task(
+        task=task,
+        base_url=base_url,
+        model=model,
+        api_key=api_key,
+        device=device,
+        language=lang,
+        max_steps=max_steps,
+        ccf=ccf,
+        adb_keyboard=adb_keyboard,
+    )
+
+    if json:
+        agent.export_json(Path(json).with_suffix('.json'))
+
+    if html:
+        agent.export_html(Path(html).with_suffix('.html'))
+
+
+if __name__ == '__main__':
+    main()