harmonyrun 0.0.29__tar.gz

harmonyrun-0.0.29/.dockerignore

@@ -0,0 +1,5 @@
+*
+
+!droidrun
+!pyproject.toml
+!README.md

harmonyrun-0.0.29/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Build and publish GitHub Release
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - name: Verify release version
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          with open("pyproject.toml", "rb") as source:
+              project = tomllib.load(source)["project"]
+          assert project["name"] == "harmonyrun"
+          assert os.environ["GITHUB_REF_NAME"] == f"v{project['version']}"
+          PY
+      - name: Build and validate distributions
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check --strict dist/*
+      - name: Publish GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: HarmonyRun ${{ github.ref_name }}
+          body_path: RELEASE_NOTES.md
+          make_latest: false
+          fail_on_unmatched_files: true
+          files: |
+            dist/*.whl
+            dist/*.tar.gz

harmonyrun-0.0.29/.gitignore

@@ -0,0 +1,49 @@
+dist/
+build/
+# Python bytecode files
+__pycache__/
+*.py[cod]
+*$py.class
+trajectories/
+*.class
+
+test.py
+test.ipynb
+*.log
+
+messages_log.json
+
+.idea
+.vscode
+.vscode-test
+.vscode-test-*
+.idea/*
+.vscode/*
+patch_apis.py
+.git
+.arize-phoenix
+
+todo.txt
+
+config.yaml
+
+credentials.yaml
+**/credentials.yaml
+!**/credentials_example.yaml
+
+.*/
+!.gitignore
+!.github/
+
+backend/
+frontend/
+
+reddit_python_posts.json
+
+test/
+.DS_Store
+
+ppt-output/
+
+.env
+scripts/droidrun_layout.json

harmonyrun-0.0.29/.python-version

@@ -0,0 +1 @@
+3.13

harmonyrun-0.0.29/CLI/344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -0,0 +1,401 @@
+# HarmonyRun 命令行使用说明
+
+HarmonyRun 是一款通过自然语言驱动真机或模拟器完成自动化任务的命令行工具，面向 **HarmonyOS（鸿蒙）** 平台。
+
+交付物：
+
+- 一份 wheel 安装包（文件名形如 `harmonyrun-<版本>-py3-none-any.whl`）
+- 本说明文档
+
+下文示例统一使用 `python3 -m droidrun` 的写法；若已激活虚拟环境或通过 `pipx` / `uv tool` 将命令加入 `PATH`，可直接使用 `harmonyrun`，两者等价；原 `droidrun` 命令仍兼容。
+
+当前版本为 **0.0.29**，基于 DroidRun 0.5.29；Python 模块名、配置目录和内部实现保持不变。
+
+---
+
+## 1. 环境要求
+
+
+| 项目         | 说明                                                                    |
+| ---------- | --------------------------------------------------------------------- |
+| **操作系统**   | macOS / Linux / Windows 均可                                            |
+| **Python** | 3.11 ~ 3.13                                                           |
+| **鸿蒙设备**   | 已安装 `**hdc`**（DevEco Studio 自带，需加入系统 `PATH`）；`hdc list targets` 能看到设备 |
+| **LLM 访问** | 使用 `run` / `test` 需要可访问的 LLM 服务及对应 API Key（详见 [第 4 节](#4-配置文件与环境变量))  |
+
+
+---
+
+## 2. 安装
+
+将交付包解压到任意目录，其中包含 `dist/` 与本说明。以下命令中的版本号、路径请按本机实际情况替换。
+
+### 2.1 推荐：虚拟环境 + pip
+
+```bash
+cd /你的解压目录
+
+python3 -m venv .venv
+.venv/bin/python3 -m pip install -U pip
+
+# 若 dist/ 内只有一个 wheel，可以用通配符（不要加引号）
+.venv/bin/python3 -m pip install dist/harmonyrun-*-py3-none-any.whl
+```
+
+验证安装：
+
+```bash
+.venv/bin/python3 -m droidrun --version
+.venv/bin/python3 -m droidrun --help
+```
+
+### 2.2 可选：pipx / uv tool
+
+```bash
+pipx install /你的解压目录/harmonyrun-<版本>-py3-none-any.whl
+# 或
+uv tool install /你的解压目录/harmonyrun-<版本>-py3-none-any.whl
+```
+
+---
+
+## 3. 快速上手
+
+1. 确保 `hdc list targets` 能看到设备。
+2. 首次运行任意命令会自动在用户目录生成 `config.yaml`：
+  ```bash
+   python3 -m droidrun --help
+  ```
+3. 按 [第 4 节](#4-配置文件与环境变量) 编辑 `config.yaml` 与 `.env`，至少配置一个可用的 API Key。
+4. 运行一个任务：
+  ```bash
+   python3 -m droidrun run "打开设置"
+  ```
+
+---
+
+## 4. 配置文件与环境变量
+
+### 4.1 配置读取优先级（从高到低）
+
+1. 命令行 `-c` / `--config` 指定的 YAML 文件
+2. 环境变量 `DROIDRUN_CONFIG` 指向的 YAML 文件
+3. 用户配置目录下的 `config.yaml`
+4. 若上述文件不存在，首次运行时按内置默认值自动生成
+
+### 4.2 用户配置目录
+
+`config.yaml` 与 `.env` 位于同一目录：
+
+
+| 系统          | 用户配置目录                                        |
+| ----------- | --------------------------------------------- |
+| **macOS**   | `~/Library/Application Support/droidrun/`     |
+| **Linux**   | `~/.config/droidrun/`（受 `XDG_CONFIG_HOME` 影响） |
+| **Windows** | `%LOCALAPPDATA%\droidrun\`                    |
+
+
+### 4.3 `.env` 与环境变量
+
+HarmonyRun 会从两处自动读取 `.env`：
+
+1. **当前工作目录及父目录**：运行 `run` / `test` 时会以 `python-dotenv` 默认规则，从当前执行目录向上查找 `.env`。适合把密钥跟工程放在一起。
+2. **用户配置目录**（见 [4.2](#42-用户配置目录)）下的 `.env`：HarmonyRun 内部对 API Key 类变量会**显式覆盖**系统环境变量。
+
+#### 4.3.1 LLM API Key
+
+如通过阿里云百炼接入（详见 [4.7](#47-阿里云百炼dashscope接入)）。把密钥放到 `.env` 而不是 `config.yaml`，更适合团队共享配置模板而密钥各自保管。
+
+可以把下面这样的文件放在**工程当前目录**（推荐）或**用户配置目录**下：
+
+```bash
+# 百炼（Anthropic 协议）
+ANTHROPIC_API_KEY=sk-sp-xxxxxxxxxxxxxxxx
+
+# 其它提供商（按需）
+# GOOGLE_API_KEY=...
+# GEMINI_API_KEY=...
+# OPENAI_API_KEY=...
+```
+
+同时，从 `.env` 里去掉 `config.yaml` 中各角色下的 `kwargs.api_key`，只保留 `base_url`：
+
+```yaml
+llm_profiles:
+  fast_agent:
+    provider: Anthropic
+    model: qwen3-vl-plus
+    temperature: 0.2
+    kwargs:
+      base_url: https://coding.dashscope.aliyuncs.com/apps/anthropic
+```
+
+#### 4.3.2 API Key 的最终优先级（从高到低）
+
+1. `config.yaml` → `llm_profiles.<角色>.kwargs.api_key`
+2. **用户配置目录下** `.env` 中的同名变量（显式覆盖系统变量）
+3. 系统 / shell 环境变量（`export ANTHROPIC_API_KEY=...`）
+4. **当前工作目录及父目录** 下 `.env` 中的同名变量（仅在上面三层都没设置时生效）
+
+#### 4.3.3 设备解锁口令
+
+运行任务时 HarmonyRun 会先检查设备电源状态，若处于 `SLEEP` 会自动唤醒并滑开锁屏；**若设备设置了 PIN / 密码锁，需要通过环境变量提供解锁口令**，否则只能滑开但无法通过密码屏。
+
+
+| 变量名                                        | 用途                                                 |
+| ------------------------------------------ | -------------------------------------------------- |
+| `DROIDRUN_DEVICE_UNLOCK_PASSWORD`          | 全局回退口令，所有设备共用                                      |
+| `DROIDRUN_DEVICE_UNLOCK_PASSWORD_<SERIAL>` | 指定设备专用口令；优先级高于全局回退。`<SERIAL>` 中非字母数字字符替换为下划线，并整体大写 |
+
+
+示例：设备序列号为 `DEVICE_SAMPLE_002`，对应变量名为 `DROIDRUN_DEVICE_UNLOCK_PASSWORD_DEVICE_SAMPLE_002`：
+
+```bash
+# 全局回退
+DROIDRUN_DEVICE_UNLOCK_PASSWORD=123456
+
+# 指定设备（带连字符或其它符号的序列号，非字母数字都转成 _）
+DROIDRUN_DEVICE_UNLOCK_PASSWORD_DEVICE_SAMPLE_002=123456
+```
+
+> 口令会在唤醒后自动输入；如果不配置，运行时会在日志中提示 "no DROIDRUN_DEVICE_UNLOCK_PASSWORD"，此时请确保设备未设置密码锁。
+
+### 4.4 `config.yaml` 完整示例
+
+首次运行会在用户配置目录下生成以下模板，可直接在其上修改。每个字段旁已注明用途与默认值：
+
+```yaml
+# === Agent 智能体行为 ===
+agent:
+  name: droidrun                # Agent 标识，保持为 droidrun
+  max_steps: 15                 # 单任务最大步数
+  reasoning: false              # 是否开启带推理的规划模式
+  streaming: true               # 是否在终端流式输出模型回复
+  after_sleep_action: 1.0       # 每次动作后等待设备更新的秒数
+  wait_for_stable_ui: 0.3       # 等待 UI 稳定的秒数
+  use_normalized_coordinates: false  # 坐标：false=像素，true=归一化 [0,1000]
+
+  fast_agent:
+    vision: false                       # 是否启用截图视觉（推荐 true，需搭配支持视觉的模型）
+    parallel_tools: true                # 单次回复允许合并多次工具调用
+    system_prompt: config/prompts/fast_agent/system.jinja2
+    user_prompt:   config/prompts/fast_agent/user.jinja2
+
+  manager:
+    vision: false                       # 推荐 true
+    system_prompt: config/prompts/manager/system.jinja2
+    stateless: false                    # 每轮是否重建上下文（实验性）
+
+  executor:
+    vision: false                       # 推荐 true
+    system_prompt: config/prompts/executor/system.jinja2
+
+  app_cards:
+    enabled: true                       # 启用 App 专属指令卡片
+    mode: local                         # local / server / composite
+    app_cards_dir: config/app_cards
+    server_url: null
+    server_timeout: 10.0
+    server_max_retries: 2
+
+# === LLM 配置（按角色区分） ===
+# 每个角色独立配置 provider/model，彼此可以不同。
+# 字段：
+#   provider     提供商（GoogleGenAI、OpenAI、Anthropic、Ollama、OpenRouter …）
+#   model        模型名
+#   temperature  采样温度
+#   base_url / api_base  自定义 API 地址（可选，详见 4.6）
+#   kwargs       附加参数映射，会被整体透传给底层 LLM 客户端构造函数
+#                （可写 api_key / base_url / max_tokens 等，详见 4.6）
+#
+# 以下为推荐配置：通过 **阿里云百炼（DashScope）** 的 Anthropic 兼容接入
+# 调用通义千问系列模型。按需替换 api_key 与 model 即可。百炼接入详见 4.7。
+llm_profiles:
+  manager:             # 规划与任务推进
+    provider: Anthropic
+    model: qwen3.5-plus
+    temperature: 0.2
+    kwargs:
+      api_key: sk-sp-xxxxxxxxxxxxxxxx           # 百炼控制台生成的 API Key
+      base_url: https://coding.dashscope.aliyuncs.com/apps/anthropic
+
+  executor:            # 选择并执行原子动作
+    provider: Anthropic
+    model: qwen3.5-plus
+    temperature: 0.1
+    kwargs:
+      api_key: sk-sp-xxxxxxxxxxxxxxxx
+      base_url: https://coding.dashscope.aliyuncs.com/apps/anthropic
+
+  fast_agent:          # 直接执行 Agent
+    provider: Anthropic
+    model: qwen3.5-plus
+    temperature: 0.2
+    kwargs:
+      api_key: sk-sp-xxxxxxxxxxxxxxxx
+      base_url: https://coding.dashscope.aliyuncs.com/apps/anthropic
+
+  app_opener:          # 按名称/描述打开 App
+    provider: Anthropic
+    model: qwen3.5-plus
+    temperature: 0.0
+    kwargs:
+      api_key: sk-sp-xxxxxxxxxxxxxxxx
+      base_url: https://coding.dashscope.aliyuncs.com/apps/anthropic
+
+  structured_output:   # 最终答案的结构化抽取
+    provider: Anthropic
+    model: qwen3.5-plus
+    temperature: 0.0
+    kwargs:
+      api_key: sk-sp-xxxxxxxxxxxxxxxx
+      base_url: https://coding.dashscope.aliyuncs.com/apps/anthropic
+
+  hypium:              # Hypium 断言生成与代码润色（可选，默认回退到 fast_agent）
+    provider: Anthropic
+    model: qwen3.5-plus
+    temperature: 0.2
+    kwargs:
+      api_key: sk-sp-xxxxxxxxxxxxxxxx
+      base_url: https://coding.dashscope.aliyuncs.com/apps/anthropic
+
+# === 设备 ===
+device:
+  serial: null           # 默认设备序列号，null = 自动选择
+  platform: harmony      # 仅支持 harmony（鸿蒙 / hdc + uitest）
+  ui_backend: socket     # socket（默认，推荐）或 shell（旧式，能力有限）
+
+# === 遥测 ===
+telemetry:
+  enabled: true          # 匿名使用情况统计，可按合规关闭
+
+# === 追踪（遗留开关，保持 false 即可） ===
+tracing:
+  enabled: false
+
+# === 日志与轨迹 ===
+logging:
+  debug: false                    # 调试日志
+  save_trajectory: none           # none / step / action
+  trajectory_path: trajectories   # 轨迹根目录（相对当前工作目录或绝对路径）
+  trajectory_llm_log: false       # 额外记录每次 LLM 调用的 JSON 日志
+  rich_text: false                # 终端 Rich 彩色样式
+  screen_recording: false         # 运行时录屏（需 save_trajectory ≠ none）
+
+# === 工具开关 ===
+tools:
+  # 可禁用的工具名：click / click_at / click_area / long_press / long_press_at
+  #                type / type_secret / system_button / swipe / wait / open_app
+  disabled_tools:
+    - click_at
+    - click_area
+    - long_press_at
+
+# === 凭据（可选） ===
+credentials:
+  enabled: false
+  file_path: config/credentials.yaml
+```
+
+### 4.5 LLM 模型切换要点
+
+- **推荐使用支持视觉的模型**（百炼上的 `qwen3.6-plus` 或 Claude Sonnet 4.x 等），并把 `agent.fast_agent.vision`、`agent.manager.vision`、`agent.executor.vision` 都改为 `true`；开启截图视觉能显著提高对复杂界面的理解与点击准确率。纯文本模型会导致部分场景定位失败。
+
+---
+
+## 5. `run`：执行单个自然语言任务
+
+```bash
+python3 -m droidrun run "你的任务描述"
+```
+
+常用选项：
+
+
+| 选项                               | 含义                         |
+| -------------------------------- | -------------------------- |
+| `-c, --config`                   | 指定配置文件                     |
+| `-d, --device`                   | 设备序列号或 IP                  |
+| `-p` / `-m`                      | LLM 提供商与模型，**必须同时指定**      |
+| `--temperature`                  | 采样温度                       |
+| `--steps`                        | 单任务最大步数                    |
+| `-u`, `--base_url`, `--api_base` | 自定义 API 地址                 |
+| `--vision` / `--no-vision`       | 统一开/关所有 Agent 的视觉能力        |
+| `--reasoning` / `--no-reasoning` | 切换规划推理模式                   |
+| `--stream` / `--no-stream`       | 流式输出                       |
+| `--tcp` / `--no-tcp`             | 设备 TCP 通信                  |
+| `--save-trajectory`              | `none` / `step` / `action` |
+| `--debug`                        | 开启调试日志                     |
+
+
+退出码：成功 `0`，失败 `1`。
+
+### 5.1 `run` 的输出件
+
+当 `save_trajectory` 非 `none` 时，在 `logging.trajectory_path`（默认 `trajectories/`，相对当前工作目录）下生成：
+
+```
+trajectories/
+└── trajectory_YYYYMMDD_HHMMSS/
+    ├── trajectory.jsonl         # 完整轨迹事件（含设备操作事件）
+    ├── meta.json                # 本次运行摘要：目标、耗时、token 统计、计数、环境信息
+    ├── formatted_device_state/  # 每步模型看到的设备状态文本快照
+    ├── screenshots/             # 截图帧（0000.png, 0001.png, …）
+    ├── screen_recording.mp4     # 屏幕录像（screen_recording=true 时）
+    └── log/                     # 每次 LLM 调用的 JSON 日志（trajectory_llm_log=true 时）
+```
+
+---
+
+## 6. `test`：批量执行测试套件
+
+```bash
+python3 -m droidrun test /路径/套件.json
+python3 -m droidrun test --help
+```
+
+- 套件为 JSON 格式，需符合 HarmonyRun 测试套件约定。
+- `--case <ID>`：只执行指定用例。
+- `--level L0|L1|L2`：按优先级筛选。
+- `-r, --report-file <路径>` 配合 `--format markdown|json`：额外导出一份报告。
+- `-d <设备>` 可重复：多台设备组成池，用例自动分配到空闲设备。
+
+> 即便 `save_trajectory: none`，`test` 通常也会自动按 `step` 级别落盘轨迹以便生成报告。
+
+### 6.1 `test` 的输出件
+
+每次运行会在 `logging.trajectory_path` 下生成一个带时间戳的套件目录：
+
+```
+trajectories/
+└── <套件名>_YYYYMMDD_HHMMSS/
+    ├── report.json              # 套件总报告（机器可读）
+    ├── report.md                # 套件实时报告（人类可读，运行中持续更新）
+    └── cases/
+        ├── <case_id>_YYYYMMDD_HHMMSS/
+        │   ├── trajectory.jsonl
+        │   ├── meta.json
+        │   ├── formatted_device_state/
+        │   └── screenshots/
+        └── …
+```
+
+若通过 `-r / --report-file` 另行指定路径，还会在该路径额外输出一份报告。
+
+---
+
+## 7. 常见问题
+
+1. `**droidrun` / `python3 -m droidrun` 找不到**
+  请确认使用的是安装了 wheel 的那个 Python。未激活虚拟环境时，使用 `.venv/bin/python3 -m droidrun`。
+2. `**ModuleNotFoundError: llama_index.llms.…`**
+  所选 `provider` 的依赖未安装。按 [2.3](#23-额外-llm-适配包按需) 安装对应 extras，或按报错的包名单独 `pip install`。
+3. **401 / 403 / 模型不可用**
+  检查用户配置目录下的 `.env`（路径见 [4.2](#42-用户配置目录)）中密钥是否有效；并确认 `llm_profiles` 的 `provider` 与 `model` 与该密钥匹配。
+4. **找不到设备**
+  先执行 `hdc list targets` 确认设备可见，再 `droidrun devices`；必要时 `droidrun doctor` 进一步诊断。
+5. **运行时报 uitest 相关错误**
+  将 `device.ui_backend` 改回 `socket`（默认），或执行 `droidrun doctor` 诊断。
+6. `**hypium run` 失败**
+  单独安装 Hypium 相关依赖与 CLI，确保 `python -m hypium` 等命令可用。
+

harmonyrun-0.0.29/Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.12-slim
+
+RUN groupadd -g 1000 droidrun \
+    && useradd -m -u 1000 -g 1000 -s /bin/bash droidrun
+
+# hdc (HarmonyOS Device Connector) is not packaged in Debian slim; mount/copy the host binary
+# into PATH or bake it into a derived image. curl is kept for uv installer below.
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+USER droidrun
+
+WORKDIR /droidrun
+
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+
+ENV PATH="/home/droidrun/.local/bin:${PATH}"
+
+COPY . .
+
+RUN uv venv && \
+    uv pip --no-cache-dir install .[google,anthropic,openai,deepseek,ollama,openrouter]
+
+ENTRYPOINT [".venv/bin/harmonyrun"]
+
+CMD ["--help"]

harmonyrun-0.0.29/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Niels Schmidt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

harmonyrun-0.0.29/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include README.md
+include pyproject.toml
+
+recursive-include droidrun *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[cod]