@buaa_smat/hometrans 0.1.0 → 0.1.2

package/agents/spec-generator.md

@@ -1,4 +1,5 @@
 ---
+name: spec-generator
 description: Generates requirement specification (spec) documents for each requirement description file in a given folder by exploring an Android project and decomposing each requirement into atomic user scenarios
 color: cyan
 ---

package/agents/test-tools/autotest/README.md

@@ -0,0 +1,223 @@
+# Self-Test Runner
+
+HarmonyOS 应用自测执行器。负责把自然语言写的测试用例（`test_case.md`）跑在真机上，产出可读的测试报告。底层调用 `harmony-autotest` whl 完成 batch 执行，Agent 编排由 `self-tester`（统一的自测 agent，通过 `setup` 布尔参数控制是否生成用例）与 `self-test-fixer`（可选，按报告修复 HarmonyOS 代码）完成。
+
+---
+
+## 一、一次性准备
+
+每台机器装好插件后做一次即可。
+
+### 1. 工具依赖
+
+确认下列工具在 `PATH` 中：
+
+| 工具 | 用途 | 验证命令 |
+|------|------|----------|
+| `uv` | Python 包管理 / 启动 `harmony-autotest` | `uv --version` |
+| `hdc` | 设备连接 / 安装 HAP | `hdc version` |
+| `python` ≥ 3.10 | 入口脚本 | `python --version` |
+
+> `uv sync`（拉取 6 个 whl）由 `self_test_runner.py` 自动执行，无需手动 `pip install`。
+
+### 2. 填写 `config.yaml`（包含真实 api_key）
+
+```bash
+cd agents/test-tools/autotest
+cp config.yaml.example config.yaml
+# 编辑 config.yaml，把所有 YOUR_API_KEY_HERE 替换成真实 api_key
+```
+
+- `config.yaml` 已加入 `.gitignore`，不会被提交到仓库。
+- `self_test_runner.py` 启动时会校验：文件存在 + 不含占位符；任一不满足则直接拒绝执行，并输出错误原因。
+- 单层模式只需填 `unified_model.api_key`；双层模式需要同时填 `execute_model.api_key` 与 `decision_model.api_key`。模式由 `agent_mode` 字段决定。
+
+---
+
+## 二、准备测试输入
+
+在某个目录（下文记为 `<case-dir>`）下放置：
+
+| 文件 | 必需 | 说明 |
+|------|------|------|
+| `test_case.md` | 是 | 常规测试用例集，多条 `### Scenario:` 块 |
+| `pre_test_case.md` | 否 | 前置用例（如首启授权、新手引导）；可写 0 / 1 / 多条 scenario |
+
+格式约定：每条 scenario 写两行
+
+```markdown
+### Scenario: 冷启动初始化后正常进入主页面
+- 动作：打开应用 → 等待 5 秒
+- 预期结果：文件夹网格主页面成功展示文件夹列表
+```
+
+并且 `<case-dir>` 向上某层目录里要能找到 `AppScope/app.json5`（HarmonyOS 工程根）—— `self-tester` 据此自动读取 `bundleName` 与 `app_name`。
+
+---
+
+## 三、Agent 流水线
+
+### 1. `self-tester`：解析用例并执行真机测试
+
+读取 `test_case.md`（首轮）与 `pre_test_case.md`（可选）→ 写入 `<output-path>/testcases.json` 和 `<output-path>/app-metadata.json` → 检测真机 → 安装 HAP → 跑 AutoTest → 渲染 `<output-path>/self-test-report.md`。前置用例自动以 `[PRE] ` 前缀置顶，按源文件顺序排列。`setup` 布尔参数控制是否运行解析阶段：
+
+| 参数 | 是否必填 | 说明 |
+|------|----------|------|
+| `hap-path` | 必填 | 待测 HAP 包路径 |
+| `output-path` | 必填 | 产物目录（JSON、报告、`task/` 都写在此根目录） |
+| `test-case-path` | `setup=true` 时必填 | `test_case.md` 路径 |
+| `pre-test-case-path` | 可选 | 前置用例文件路径；不传时自动从 `test-case-path` 同目录查找 |
+| `setup` | 可选，默认 `true` | `true` = 解析 + 测试；`false` = 仅测试，要求 `<output-path>/testcases.json` 与 `<output-path>/app-metadata.json` 已存在 |
+
+产出：
+
+- `<output-path>/testcases.json` — 用例数组（`setup=true` 时写入）
+- `<output-path>/app-metadata.json` — `{ bundle_name, app_name, project_root }`（`setup=true` 时写入）
+- `<output-path>/_extracted.json` — 用例提取的中间文件（`setup=true` 时写入）
+- `<output-path>/self-test-report.md` — 自测报告（每次都写）
+- `<output-path>/task/task_<timestamp>/` — AutoTest 原始产物（每条用例的 HTML 报告、日志、截图）
+
+> **多轮迭代测试**：首轮用 `setup=true`，第二轮起用 `setup=false` 复用首轮产出的两个 JSON，不重复解析 `test_case.md`。
+
+执行前请先确认设备已连接：
+
+```bash
+hdc list targets
+```
+
+agent 会调用 `self_test_runner.py run` 完成前 4 步（1-3 同步、4 后台启动）：
+
+1. 校验 `config.yaml`
+2. `uv sync`（首次 1–3 分钟，后续按 `pyproject.toml` 的 SHA256 自动跳过）
+3. `hdc uninstall` + `hdc install -r`
+4. 后台启动 `python -m AutoTest.batch`
+
+随后 agent 用 `self_test_runner.py status` 每 60 秒轮询一次直到 `COMPLETED`，再调 `report_tool.py generate` 把 `task_<ts>/` 产物渲染成 `self-test-report.md`。报告把前置用例与常规用例分两节渲染（`## 前置用例` / `## 用例详情`），由模板生成，不依赖 LLM 现写。
+
+`<output-path>/task/task_<timestamp>/` 会保存 batch 运行期间的中间产物（`hypium_mcp.log` / `tmp_hypium/`）—— `AutoTest.batch` 启动时 cwd 即此目录，不再污染 `agents/test-tools/autotest/`。
+
+### 2. `self-test-fixer`：按报告修复 HarmonyOS 代码（可选）
+
+入参就是上一步的 `self-test-report.md`。当 `self-tester` 报告里有 FAIL 时再跑这一步。
+
+---
+
+## 四、直接调用 `self_test_runner.py`（不通过 agent）
+
+agent 内部用的就是这个脚本，开发自测时可以直接调：
+
+```bash
+cd agents/test-tools/autotest
+
+# 启动一次自测（前台同步做准备 + 后台启动 batch，立即返回 PID）
+python self_test_runner.py run \
+    --testcases <path-to-testcases.json>  \
+    --hap       <path-to-app.hap>          \
+    --bundle-name com.example.xxx          \
+    --category  <app_name>                 \
+    --task-dir  <out>/task                 \
+    --output-dir <out>
+
+# 轮询状态（agent 每 60s 查一次）
+python self_test_runner.py status --task-dir <out>/task --output-dir <out>
+
+# 强行终止后台 batch
+python self_test_runner.py kill   --task-dir <out>/task
+
+# 重置本地状态（杀残留进程 + 删 .venv + 删本目录残留中间产物）
+# 用它代替手工 `rm -rf .venv` / `uv cache clean`，不会动全局 uv 缓存
+python self_test_runner.py clean
+```
+
+### `report_tool.py` — 单独重渲染报告
+
+batch 跑完后 agent 会自动调一次 `report_tool.py`；本地调试想重渲染某次历史 task：
+
+```bash
+cd agents/test-tools/autotest
+uv run python report_tool.py generate \
+    --task-subdir   <out>/task/task_<ts>          \
+    --app-metadata  <out>/app-metadata.json        \
+    --hap           <hap-path>                     \
+    --device        127.0.0.1:5555                 \
+    --suite         "<title from test_case.md>" \
+    --out           <out>/self-test-report.md      \
+    --validate
+```
+
+也可以只校验一份已有的 `self-test-report.md`：
+
+```bash
+uv run python report_tool.py validate <out>/self-test-report.md
+```
+
+读取 `summary.json` + `task_results.jsonl` + 每个 case 的 `<HHMMSS>.json`（解析 AutoTest planner agent 写入的 `<judgment>` 块），用模板渲染整份报告。完全无 LLM 调用。
+
+参数说明：
+
+| 参数 | 含义 |
+|------|------|
+| `--testcases` | JSON 数组或 JSONL 均可，旧 JSON 数组会被自动转 JSONL |
+| `--bundle-name` | HAP 包名，用于 `hdc uninstall` |
+| `--category` | 测试分类标签，会传给 `AutoTest.batch`，建议直接用 `app_name` |
+| `--task-dir` | 任务工作目录，脚本会在内部创建 `task_<timestamp>` 子目录 |
+| `--output-dir` | 日志目录（`self_test_*.log`） |
+| `--config` | 指定 `config.yaml` 路径；默认用本脚本同目录的 `config.yaml` |
+| `--force-reinit` | 强制清空 `.venv` 重新 `uv sync`；默认只在 `pyproject.toml` 内容变化时重建 |
+
+`status` 子命令的 JSON 响应字段：
+
+| 字段 | 含义 |
+|------|------|
+| `status` | `RUNNING` / `COMPLETED` / `CRASHED` / `NOT_STARTED` |
+| `cases_done` | 已完成的用例数 |
+| `pass_count` / `fail_count` / `unknown_count` | 仅 `COMPLETED` 时给出 |
+| `task_subdir` | `task_<timestamp>` 绝对路径，AutoTest 产物都在里面 |
+| `log_tail` | runner 日志最近 5 行 |
+
+---
+
+## 五、目录布局一览
+
+```
+agents/test-tools/autotest/
+├── README.md                       # 本文件
+├── .gitignore                      # 排除 .venv / config.yaml / 运行期日志等
+├── pyproject.toml                  # 声明 6 个远程 whl URL（harmony-autotest / hypium_mcp / hypium / xdevice*3）
+├── uv.lock                         # 与 pyproject.toml 配套的版本锁定文件
+├── config.yaml.example             # 用户拷贝填 api_key 的模板
+├── config.yaml                     # 用户填好的真实配置（.gitignore 中，不入库）
+├── self_test_runner.py             # 入口脚本：run / status / kill / clean
+├── testcases_tool.py               # 子命令 generate / validate（_extracted.json → testcases.json，含格式校验）
+├── report_tool.py                  # 子命令 generate / validate（task_<ts>/ → self-test-report.md，含格式校验）
+├── testcases_schema.md             # testcases.json 字段规范
+└── .venv/                          # uv sync 产出（被 .gitignore 排除）
+```
+
+---
+
+## 六、常见问题
+
+**Q: `config.yaml missing or api_key not filled`**
+A: 复制 `config.yaml.example` → `config.yaml` 并填入真实 api_key 后重试。
+
+**Q: `uv sync` 卡住或失败**
+A: 6 个 whl 都从 gitcode API v5 拉，需要外网访问 `gitcode.com`。失败时检查代理 / 网络；也可以 `--force-reinit` 强制重建。
+
+**Q: 测试过程被打断，下次跑会冲突吗？**
+A: 不会。`self_test_runner.py run` 启动时会扫描并 kill 残留的 `AutoTest.batch` / `hypium_mcp` / `harmony_autotest` 进程（不止靠 PID 文件，按命令行名兜底），并自动清掉本目录顶层的 `tmp_hypium/` / `hypium_mcp.log` 等遗留中间产物。`task/` 目录在 agent 流程里也会被清空。
+
+**Q: 想彻底重置一遍本地状态再跑？**
+A: 跑一次 `python self_test_runner.py clean`：杀残留 → 删 `.venv` → 删 `tmp_hypium/` / `hypium_mcp.log` / `batch.pid` / `batch_stdout.log`。**不要**手工 `uv cache clean`——全局缓存清空后重装 6 个 whl 要从 gitcode 重新拉（1–3 分钟）；保留缓存的话 `uv sync` 只需几秒。
+
+**Q: 想自己改 `testcases.json` 后再跑？**
+A: 改完后跑一遍校验，再交给 `self-tester`（`setup=false`）：
+
+```bash
+uv run python testcases_tool.py validate <path-to-testcases.json>
+```
+
+只有打印 `VALIDATION PASSED` 才能用。
+
+**Q: 报告里 `AutoTest 任务路径` 指向哪？**
+A: 每条用例的 AutoTest 执行目录（HTML 报告 + 日志 + 截图），路径形如 `<output>/task/task_<ts>/<case_name>/`。报告里所有 case 都必须带这个字段。

package/agents/test-tools/autotest/config.yaml.example

@@ -0,0 +1,58 @@
+# AutoTest Configuration — User-provided overlay
+#
+# 使用方法：
+#   1. 复制本文件为同目录下的 `config.yaml`
+#   2. 填入所有 `YOUR_API_KEY_HERE` 占位的真实 api_key（至少 unified_model 或对应模式下的 model）
+#   3. self_test_runner.py 在启动前会校验 config.yaml 存在且 api_key 已替换，否则拒绝执行
+#
+# 该文件最终通过 `python -m AutoTest.batch --config <绝对路径>` 注入到 AutoTest，
+# 覆盖 whl 内置的同名默认配置（默认配置里 api_key 全是占位符）。
+
+# Agent Mode: "layered" (双层模式) | "single" (单层模式)
+agent_mode: "single"
+
+# ===== 双层模式配置 =====
+execute_model:
+  name: "gui-plus-2026-02-26"
+  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
+  api_key: "YOUR_API_KEY_HERE"
+  provider: "mai-ui"
+  max_steps: 3
+
+decision_model:
+  name: "qwen3.5-plus"
+  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
+  api_key: "YOUR_API_KEY_HERE"
+  provider: "openai"
+  temperature: 0.0
+  top_p: 0.1
+  frequency_penalty: 1.0
+
+# ===== 单层模式配置 =====
+unified_model:
+  name: "qwen3.5-plus"
+  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
+  api_key: "YOUR_API_KEY_HERE"
+  provider: "openai"
+  temperature: 0.1
+  top_p: 0.9
+  frequency_penalty: 0.5
+
+# ===== 设备配置 =====
+device:
+  device_sn: null
+  ip: "127.0.0.1"
+  port: 8710
+  device_log_level: "debug"
+
+# ===== Agent 通用配置 =====
+agent:
+  max_steps: 50
+  verbose: true
+  lang: "zh"
+  enable_preprocess: false
+  # debug_mode: null | "memory" | "file"
+  debug_mode: null
+
+# ===== 自定义适配器（可选） =====
+# adapter_class: "external.custom_adapter.CustomMCPAdapter"

package/agents/test-tools/autotest/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "auto-test-runner"
+version = "0.1.0"
+description = "Self-test runner harness for HarmonyOS apps; delegates execution to the harmony-autotest whl."
+requires-python = ">=3.10"
+dependencies = [
+    "harmony-autotest @ https://gitcode.com/api/v5/repos/SMAT/HomeTrans/raw/agents/test-tools/harmony_autotest-0.1.0-py3-none-any.whl?ref=main",
+    "hypium_mcp @ https://gitcode.com/api/v5/repos/SMAT/HomeTrans/raw/agents/test-tools/hypium_mcp-0.6.5-py3-none-any.whl?ref=main",
+    "hypium @ https://gitcode.com/api/v5/repos/SMAT/HomeTrans/raw/agents/test-tools/hypium-6.1.0.210-py3-none-any.whl?ref=main",
+    "xdevice @ https://gitcode.com/api/v5/repos/SMAT/HomeTrans/raw/agents/test-tools/xdevice-6.1.0.210-py3-none-any.whl?ref=main",
+    "xdevice-ohos @ https://gitcode.com/api/v5/repos/SMAT/HomeTrans/raw/agents/test-tools/xdevice_ohos-6.1.0.210-py3-none-any.whl?ref=main",
+    "xdevice-devicetest @ https://gitcode.com/api/v5/repos/SMAT/HomeTrans/raw/agents/test-tools/xdevice_devicetest-6.1.0.210-py3-none-any.whl?ref=main",
+]
+
+[[tool.uv.index]]
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"