@buaa_smat/hometrans 0.1.13 → 0.1.14

package/skills/hmos-integration-test/readme.md

@@ -1,309 +1,309 @@
-# Self-Test 使用文档
-
-## 简介
-
-**Self-Test** 是 HomeTrans 的端到端真机自测能力——你把一份 Markdown 测试用例和一个 HAP 交给我，我帮你把用例跑在鸿蒙真机上，产出可读的测试报告。如果测试失败，我还能**自动分析原因、修改代码、重建签名 HAP、重新测试**，直到全部通过。测试和修复不是两个功能拼在一起，而是一条统一的工作流：你只需要说一句话，剩下的事情系统自动完成。
-
----
-
-## 我能做什么
-
-- **把 Markdown 测试用例变成机器可读的 JSON**：解析你写的 `test_case.md`，自动提取包名、替换应用名，生成 AutoTest 可执行的 `testcases.json`。
-- **在鸿蒙真机上跑自动化测试**：连接 USB 设备，安装 HAP，逐条执行用例，生成带通过率和失败详情的报告。
-- **测试失败后自动修复并重测**：读到失败报告 → 白盒审查源码 → 修改代码 → 重新编译签名 HAP → 重新测试 → 如果还有失败则继续循环，默认最多 3 轮（可通过 `max-rounds` 参数配置）。
-
----
-
-## 快速开始
-
-你说一句话，系统跑完全程。最简写法：
-
-> 跑自测，自动修复
-
-更完整的写法（指定所有路径）：
-
-> 跑自测，测试用例在 `D:\project\test_case.md`，HAP 在 `D:\project\entry-default-signed.hap`，输出到 `D:\project\output`
-
-**然后会发生什么：**
-
-1. **测试与修复循环** — 默认最多 3 轮（可通过 `max-rounds` 参数配置），每轮跑完后产物快照到 `output-path/round-{n}/`：
-   - 首轮：解析 `test_case.md` → 写出 `output-path/testcases.json` 与 `app-metadata.json` → 连接真机、安装 HAP、跑 AutoTest → 产出 `output-path/self-test-report.md`
-   - 测试完成后，SKILL 把当轮的 `self-test-report.md`、`task/`、`_extracted.json`（若有）快照到 `output-path/round-{n}/`
-   - Fix：白盒审查代码 → 修改源码 → 产出 `round-{n}/self-test-fix-report.md`
-   - Build：重新编译 → 产出 `round-{n}/entry-default-signed.hap` 和 `build-fix-report.md`
-   - 后续轮：跳过解析阶段，直接读首轮已生成的 `testcases.json` + `app-metadata.json`，用新 HAP 跑测试 → 同样快照到对应轮 `round-{n}/`
-2. **HAP 镜像** — 循环结束后，最后一轮的签名 HAP 复制到 `output-path/entry-default-signed.hap`，方便直接取用
-
-**最终产物**（在 `output-path` 下）：
-
-| 文件 | 位置 | 内容 |
-|------|------|------|
-| `testcases.json` | 根目录 | 结构化用例，首轮生成后所有轮共享 |
-| `app-metadata.json` | 根目录 | 包名、应用名、项目路径，首轮生成后所有轮共享 |
-| `self-test-report.md` | 根目录（每轮覆盖，最终为最后一轮） | 测试报告 |
-| `task/` | 根目录（每轮覆盖，最终为最后一轮） | AutoTest 原始产物 |
-| `entry-default-signed.hap` | 根目录（循环结束后镜像） | 最后一轮编译的签名 HAP |
-| `round-{n}/` | 子目录（每轮历史快照） | 每轮跑完后的 `self-test-report.md`、`task/`、`self-test-fix-report.md`、`build-fix-report.md`、`entry-default-signed.hap` 等 |
-
----
-
-## 输入参数
-
-### 测试参数
-
-| 参数 | 是否必填 | 说明 |
-|------|----------|------|
-| `hap-path` | 必填 | 签名后的 `.hap` 安装包路径 |
-| `output-path` | 可选，默认 = `test-case-path` 所在目录 | 所有产物输出到这个目录（`testcases.json`、`app-metadata.json`、`self-test-report.md`、`task/` 都写在此根目录）。不指定时直接写在用例文件同目录 |
-| `test-case-path` | `setup=true` 时必填 | `test_case.md` 的路径 |
-| `pre-test-case-path` | 可选 | 前置用例 `pre_test_case.md` 的路径。不传会自动在同目录查找 |
-| `setup` | 可选，默认 `true` | `true` = 解析 `test_case.md` 写出 JSON，再跑测试；`false` = 跳过解析阶段，直接读取 `<output-path>/testcases.json` 与 `<output-path>/app-metadata.json` 跑测试。两个 JSON 都不存在或为空时硬失败，需要重跑一次 `setup=true` |
-
-### 自动修复参数
-
-以下参数仅在进入修复循环时使用，由 Skill 自动从 `app-metadata.json` 获取，你通常不需要手动指定：
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `harmonyos-project-path` | 是 | 自动从 `app-metadata.json` 的 `project_root` 字段读取 |
-| `android-project-path` | 否 | Android 参考项目路径。提供后 fixer 会参考 Android 实现来修 bug，质量更高 |
-
----
-
-## 输出产物
-
-`testcases.json` 和 `app-metadata.json` 在首轮（`setup=true`）写入 `output-path/` 根目录，后续轮直接复用，不再重新生成。`self-test-report.md` 与 `task/` 每轮都会在根目录覆盖更新，跑完每轮后由 SKILL 快照到 `output-path/round-{n}/`。循环结束后，最后一轮的签名 HAP 镜像到根目录。
-
-| 文件 | 写入位置 | 内容 |
-|------|----------|------|
-| `testcases.json` | `output-path/` 根目录（首轮写入，跨轮共享） | 结构化的用例列表，供 AutoTest 逐条执行 |
-| `app-metadata.json` | `output-path/` 根目录（首轮写入，跨轮共享） | `{ bundle_name, app_name, project_root }` |
-| `_extracted.json` | `output-path/` 根目录（首轮写入，跨轮快照保留） | 用例提取的中间文件，排查问题时有用，通常不需要关注 |
-| `self-test-report.md` | `output-path/` 根目录（每轮覆盖，跨轮快照保留） | 可读的测试报告，含通过率、失败原因、每条用例的 AutoTest 任务路径 |
-| `task/task_<时间戳>/` | `output-path/task/`（每轮覆盖，跨轮快照保留） | 每条用例的 HTML 报告、截图、Agent 日志 |
-| `self-test-fix-report.md` | `output-path/round-{n}/`（Fix 步骤，有失败的轮次） | 白盒审查结论、根因分析、修改内容、修复结果 |
-| `self-test-fix-commit-info.md` | `output-path/round-{n}/`（Fix 步骤） | `commit-id: <hash>` 或 `commit-id: none` |
-| `build-fix-report.md` | `output-path/round-{n}/`（Build 步骤） | 编译是否成功、修复了哪些编译问题 |
-| `build-fix-commit-info.md` | `output-path/round-{n}/`（Build 步骤） | `commit-id: <hash>` 或 `commit-id: none` |
-| `entry-default-signed.hap` | `output-path/round-{n}/`（Build 步骤）；循环结束后镜像到 `output-path/` 根目录 | 修复后重新编译的签名 HAP |
-
-> **提示**：`output-path/` 根目录下的报告和 task 始终是最近一轮的最新产物；要查看某一轮的历史快照，进入对应的 `round-{n}/` 目录即可。
-
----
-
-## 工作流程
-
-一次完整的 Self-Test 跑下来会经历下面这些阶段，简化的流程示意：
-
-```
-你提供: test_case.md + HAP
-  │
-  ▼
-┌─ 解析阶段（仅首轮）─────────────────────────────────────────┐
-│                                                              │
-│  读取 test_case.md → LLM 提取动作/预期结果 → 替换应用名为包名  │
-│  → Python 脚本生成 testcases.json + 写入 app-metadata.json   │
-│                                                              │
-└──────────────────────────────┬───────────────────────────────┘
-                               │
-                               ▼
-┌─ 测试与修复循环（每轮跑完后快照到 output-path/round-{n}/）──┐
-│                                                              │
-│  ┌── Test ─────────────────────────────────────────────┐    │
-│  │ 检测真机连接 → 安装 HAP → AutoTest 批量执行用例      │    │
-│  │ → 每 60 秒轮询一次 → 产出 round-{n}/self-test-report │    │
-│  └──────────────────────┬──────────────────────────────┘    │
-│                         │                                    │
-│                  全部通过?                                    │
-│              ┌──────┴──────┐                                  │
-│              ▼              ▼                                  │
-│            是(退出循环)    否(进入修复)                         │
-│                             │                                  │
-│  ┌── Fix ──────────────────────────────────────────────┐    │
-│  │ self-test-fixer 读报告 → 白盒审查代码                 │    │
-│  │ → 区分 confirmed(真bug) / false_positive(误报)       │    │
-│  │ → 只修改 confirmed → git commit                      │    │
-│  │ → 产出 round-{n}/self-test-fix-report.md             │    │
-│  └──────────────────────┬──────────────────────────────┘    │
-│                         │                                    │
-│                  有确认缺陷?                                   │
-│              ┌──────┴──────┐                                  │
-│              ▼              ▼                                  │
-│            否(退出循环)    是(进入编译)                         │
-│                             │                                  │
-│  ┌── Build ────────────────────────────────────────────┐    │
-│  │ build-fixer --signed 重新编译 → 产出签名 HAP         │    │
-│  │ → 产出 round-{n}/build-fix-report.md                │    │
-│  │ → 产出 round-{n}/entry-default-signed.hap           │    │
-│  └──────────────────────┬──────────────────────────────┘    │
-│                         │                                    │
-│              未达上限? n++; 回到 Test                          │
-│              ┌──────┴──────┐                                  │
-│              ▼              ▼                                  │
-│            是(下一轮)     否(退出循环)                         │
-│                                                              │
-└──────────────────────────────────────────────────────────────┘
-                               │
-                               ▼
-              循环结束 → 镜像最终轮报告和 HAP 到 output-path/
-```
-
-### 循环停止条件
-
-满足以下任一条件，循环立即停止：
-
-| 条件 | stop_reason | 说明 |
-|------|-------------|------|
-| 全部通过 | `all_passed` | 报告 `failed == 0`，所有用例通过 |
-| 无确认缺陷 | `no_confirmed_defects` | fixer 判定所有失败都是测试误报（false positive），没有需要修改的代码缺陷 |
-| 达到最大轮数 | `max_rounds_reached` | 已完成配置的最大轮数循环（`max-rounds`，默认 3），仍有失败未解决 |
-| 编译未产出 HAP（异常） | `no_signed_hap` | build-fixer 未产出签名 HAP，无法继续测试 |
-| 用例列表为空（异常） | `no_testcases` | `testcases.json` 里 0 条用例，没有可跑的内容。常见原因：解析阶段没识别到 `### Scenario:` 区块 |
-| 自测 agent 早退（异常） | `agent_early_exit` | `self-tester` 在跑用例之前就退出了（设备没连、`config.yaml` 没填、`test-tools/autotest` 目录找不到（`env.TOOL_PATH` 未配置或失效）、batch 启动失败 / 超时 / 崩溃、`setup=false` 但所需 JSON 缺失等）。报告首行会是 `status: FAIL`，第二行 `reason: <原因>`。**这种情况下不会进入 fix 循环**——这些是环境/前置条件问题，不是应用缺陷 |
-
----
-
-## 前置用例（Pre-Cases）
-
-如果 `test_case.md` 同目录下有 `pre_test_case.md`，系统会自动把它作为前置用例合并进去。前置用例是一些**环境准备操作**——比如授权弹窗、跳过引导、导入素材、授予权限。
-
-- 前置用例在 `testcases.json` 中排在最前面，`case_name` 会自动加 `[PRE] ` 前缀
-- 跑测试时最先执行，为后续用例准备环境
-- **前置用例失败不代表应用有 bug**——通常是没素材、没权限、系统弹窗没弹等环境问题
-- 测试报告会单独标注**常规通过率**（排除前置用例），这才是衡量应用质量的主要指标
-
----
-
-## 报告解读
-
-### 测试报告（self-test-report.md）
-
-每份报告包含以下部分：
-
-- **测试概览**：设备序列号、HAP 文件名、测试套件名、总用例数、通过/失败数、通过率、常规通过率
-- **前置用例**：`[PRE]` 开头的用例，与常规用例分开列出，各自从 1 开始编号（Pre 1、Pre 2... / Case 1、Case 2...）
-- **用例详情**：每条用例的动作、预期结果、AutoTest 判定结果、失败原因
-- **每条用例都标注了 `**AutoTest 任务路径**`**：指向该用例的原始执行目录（HTML 报告、截图、日志）
-
-**PASS / FAIL / UNKNOWN 的含义：**
-
-- `PASS` — 测试通过
-- `FAIL` — 测试失败或超时/崩溃，`reason` 字段说明原因
-- `UNKNOWN` — 有产出报告但无法明确判定结果
-
-`FAIL` 和 `UNKNOWN` 都应视为未通过。
-
-### 修复报告（self-test-fix-report.md）
-
-- **概览**：失败数 → 确认 bug 数 → 误报数 → 修复成功/失败数
-- **白盒审查结果**：每条失败用例逐一分析，结论为 `confirmed`（代码真有问题）或 `false_positive`（测试误判）
-- **修复计划**：按依赖关系排序的修复列表
-- **修复详情**：每条修复的 Android 参考、根因、具体修改、有效尝试次数、结果
-- **误报说明**：为什么判定为误报，测试 agent 出了什么问题
-- **编译验证**：编译结果及 build-fixer 修复的编译问题
-
-### 编译报告（build-fix-report.md）
-
-build-fixer 的输出摘要：编译状态、签名类型、迭代次数、修复的编译错误数、文件修改汇总。
-
----
-
-## test_case.md 怎么写
-
-用 Markdown 写，结构如下：
-
-```markdown
-# 测试套件名
-
-## Spec: 功能模块
-### Scenario: 新建歌单
-- 动作：点击新建歌单按钮
-- 预期结果：弹出新建歌单对话框
-- 动作：输入歌单名称"测试歌单"
-- 预期结果：歌单创建成功，出现在列表顶部
-```
-
-- `# 标题` → 测试套件名，会出现在报告里
-- `## Spec:` → 功能模块，纯逻辑分组，不影响执行
-- `### Scenario:` → 一条用例
-- `- 动作：` → 测试操作
-- `- 预期结果：` → 期望结果（多行用中文逗号连接）
-
-**不需要手动替换应用名**。动作里写的显示名称（如"简单图库"、"Tuku"）系统会自动替换成包名（如 `com.example.tuku`），确保 AutoTest 能正确识别目标应用。
-
-**以下内容会被自动忽略**：`- 前置条件：`、`## 页面描述注解`、`## 编号映射表`。
-
----
-
-## 环境要求
-
-### 基础环境
-
-- 操作系统：**Windows** 是主要测试目标；macOS/Linux 上的核心命令（`hdc`、`uv`、POSIX 工具链）也能跑，Skill 里涉及到的复制操作会按可用 shell 自适应
-- `hdc` 已安装并在 PATH 中
-- `uv` 已安装（Python 包管理）
-- `<TOOL_PATH>/test-tools/autotest/config.yaml` 已配置真实 api_key（`TOOL_PATH` 取自 `~/.hometrans/config.json` 的 `env.TOOL_PATH`，默认即 `~/.hometrans/tools`；`ht init` 填好 `TEST_API_KEY` 后会自动写入）
-- 鸿蒙真机通过 USB 连接，`hdc list targets` 能看到设备
-- 签名后的 `.hap` 文件
-
-### 自动修复附加条件
-
-- `app-metadata.json` 存在（setup 阶段自动产出，内含 `project_root`）
-- 建议项目在 Git 仓库中（不在也可以修复，但不会自动 commit；`commit-id: none`）
-- 签名配置已存在于 `build-profile.json5`（DevEco Studio → File → Project Structure → Signing Configs → Automatically generate signature）
-
----
-
-## 常见问题
-
-**Q: 报 "No HarmonyOS device connected"？**
-
-A: 检查 USB 连接，跑 `hdc list targets` 看看有没有设备 SN。重新插拔 USB，在设备上重新授权 USB 调试。
-
-**Q: 报 config.yaml missing 或 api_key 没填？**
-
-A: 在 AutoTest 目录 `<TOOL_PATH>/test-tools/autotest`（`TOOL_PATH` 取自 `~/.hometrans/config.json` 的 `env.TOOL_PATH`，默认 `~/.hometrans/tools`）下，复制 `config.yaml.example` 为 `config.yaml`，把 `YOUR_API_KEY_HERE` 替换成真实的 API Key。或者重新跑 `ht init` 并填入 `TEST_API_KEY`，它会自动生成。
-
-**Q: 前置用例失败了要不要修代码？**
-
-A: 不用。前置用例是环境准备脚本，失败意味着环境条件不满足（没素材、没权限、引导弹窗等），不影响应用的常规通过率。
-
-**Q: PASS / FAIL / UNKNOWN 有什么区别？**
-
-A: `PASS` — 通过；`FAIL` — 失败/超时/崩溃，有原因说明；`UNKNOWN` — 有报告但无法判定。后面两个都算未通过。
-
-**Q: 测试跑多久？**
-
-A: 每条用例大约 6 分钟（含 Agent 决策和执行时间）。整体超时上限 = 用例数 × 6 分钟，超过后自动终止并产出部分报告。
-
-**Q: 怎么只重跑失败的用例？**
-
-A: 目前每次都跑 `testcases.json` 的全部用例。你可以手动删掉已通过的条目，只保留失败的，然后用 `setup=false` 重新跑（会跳过解析阶段，直接读取 `<output-path>/testcases.json`）。
-
-**Q: 产物在哪个目录？**
-
-A: `testcases.json` 和 `app-metadata.json` 在 `output-path/` 根目录。测试和修复的每轮产物在 `output-path/round-1/`、`output-path/round-2/`... 子目录中。循环结束后，最终轮的关键文件（报告、HAP）会镜像到 `output-path/` 根目录，方便直接查看。
-
-**Q: 怎么启用自动修复？**
-
-A: 说"跑自测，自动修复"；或者跑完测试后看到有失败，Skill 会主动问你要不要启用，回复"是"就进去了。默认最多 3 轮，需要更多/更少可以加一句"最多 N 轮"（对应 `max-rounds` 参数）。
-
-**Q: 自动修复会改我的代码吗？**
-
-A: 会修改鸿蒙源码来修 bug，但只在**白盒审查确认是真问题**（`confirmed`）的情况下才会改。误报（`false_positive`）不改，测试用例不改。所有修改会 git commit，可随时 revert。如果不在 Git 仓库中，修改照常进行但不 commit。
-
-**Q: 自动修复一轮多久？**
-
-A: Fix（白盒分析 + 改代码）约 5-10 分钟，Build（编译）约 2-5 分钟，Retest（重新跑用例）约 N×6 分钟。可以随时中断。
-
-**Q: 什么情况下循环会停？**
-
-A: 正常退出 3 种：① 全部通过（`all_passed`）；② 所有失败都是误报，无代码缺陷需要修复（`no_confirmed_defects`）；③ 跑满 `max-rounds` 轮（默认 3）仍有失败（`max_rounds_reached`）。异常退出 3 种：编译未产出签名 HAP（`no_signed_hap`）；`testcases.json` 为空（`no_testcases`）；自测 agent 早退，写出首行 `status: FAIL` 的 sentinel 报告（`agent_early_exit`，常见原因：设备没连、api_key 没填、batch 崩溃 / 超时）。异常退出不会进入 fix 循环——那些是环境问题，不是代码缺陷。
-
-**Q: 需要提供 Android 项目路径吗？**
-
-A: 不必须。提供了 fixer 会参考 Android 实现来修 bug，质量更高。不提供也能独立完成，基于白盒代码分析和 HarmonyOS API 文档修复。
-
-**Q: 报 "Build did not produce a signed HAP"？**
-
-A: 通常是因为 `build-profile.json5` 中的签名配置被清掉了。去 DevEco Studio 重新生成（File → Project Structure → Signing Configs → Automatically generate signature），然后继续循环。
+# Self-Test 使用文档
+
+## 简介
+
+**Self-Test** 是 HomeTrans 的端到端真机自测能力——你把一份 Markdown 测试用例和一个 HAP 交给我，我帮你把用例跑在鸿蒙真机上，产出可读的测试报告。如果测试失败，我还能**自动分析原因、修改代码、重建签名 HAP、重新测试**，直到全部通过。测试和修复不是两个功能拼在一起，而是一条统一的工作流：你只需要说一句话，剩下的事情系统自动完成。
+
+---
+
+## 我能做什么
+
+- **把 Markdown 测试用例变成机器可读的 JSON**：解析你写的 `test_case.md`，自动提取包名、替换应用名，生成 AutoTest 可执行的 `testcases.json`。
+- **在鸿蒙真机上跑自动化测试**：连接 USB 设备，安装 HAP，逐条执行用例，生成带通过率和失败详情的报告。
+- **测试失败后自动修复并重测**：读到失败报告 → 白盒审查源码 → 修改代码 → 重新编译签名 HAP → 重新测试 → 如果还有失败则继续循环，默认最多 3 轮（可通过 `max_rounds` 参数配置）。
+
+---
+
+## 快速开始
+
+你说一句话，系统跑完全程。最简写法：
+
+> 跑自测，自动修复
+
+更完整的写法（指定所有路径）：
+
+> 跑自测，测试用例在 `D:\project\test_case.md`，HAP 在 `D:\project\entry-default-signed.hap`，输出到 `D:\project\output`
+
+**然后会发生什么：**
+
+1. **测试与修复循环** — 默认最多 3 轮（可通过 `max_rounds` 参数配置），每轮跑完后产物快照到 `output_path/round-{n}/`：
+   - 首轮：解析 `test_case.md` → 写出 `output_path/testcases.json` 与 `app-metadata.json` → 连接真机、安装 HAP、跑 AutoTest → 产出 `output_path/self-test-report.md`
+   - 测试完成后，SKILL 把当轮的 `self-test-report.md`、`task/`、`_extracted.json`（若有）快照到 `output_path/round-{n}/`
+   - Fix：白盒审查代码 → 修改源码 → 产出 `round-{n}/self-test-fix-report.md`
+   - Build：重新编译 → 产出 `round-{n}/entry-default-signed.hap` 和 `build-fix-report.md`
+   - 后续轮：跳过解析阶段，直接读首轮已生成的 `testcases.json` + `app-metadata.json`，用新 HAP 跑测试 → 同样快照到对应轮 `round-{n}/`
+2. **HAP 镜像** — 循环结束后，最后一轮的签名 HAP 复制到 `output_path/entry-default-signed.hap`，方便直接取用
+
+**最终产物**（在 `output_path` 下）：
+
+| 文件 | 位置 | 内容 |
+|------|------|------|
+| `testcases.json` | 根目录 | 结构化用例，首轮生成后所有轮共享 |
+| `app-metadata.json` | 根目录 | 包名、应用名、项目路径，首轮生成后所有轮共享 |
+| `self-test-report.md` | 根目录（每轮覆盖，最终为最后一轮） | 测试报告 |
+| `task/` | 根目录（每轮覆盖，最终为最后一轮） | AutoTest 原始产物 |
+| `entry-default-signed.hap` | 根目录（循环结束后镜像） | 最后一轮编译的签名 HAP |
+| `round-{n}/` | 子目录（每轮历史快照） | 每轮跑完后的 `self-test-report.md`、`task/`、`self-test-fix-report.md`、`build-fix-report.md`、`entry-default-signed.hap` 等 |
+
+---
+
+## 输入参数
+
+### 测试参数
+
+| 参数 | 是否必填 | 说明 |
+|------|----------|------|
+| `hap_path` | 必填 | 签名后的 `.hap` 安装包路径 |
+| `output_path` | 可选，默认 = `test_case_path` 所在目录 | 所有产物输出到这个目录（`testcases.json`、`app-metadata.json`、`self-test-report.md`、`task/` 都写在此根目录）。不指定时直接写在用例文件同目录 |
+| `test_case_path` | `setup=true` 时必填 | `test_case.md` 的路径 |
+| `pre_test_case_path` | 可选 | 前置用例 `pre_test_case.md` 的路径。不传会自动在同目录查找 |
+| `setup` | 可选，默认 `true` | `true` = 解析 `test_case.md` 写出 JSON，再跑测试；`false` = 跳过解析阶段，直接读取 `<output_path>/testcases.json` 与 `<output_path>/app-metadata.json` 跑测试。两个 JSON 都不存在或为空时硬失败，需要重跑一次 `setup=true` |
+
+### 自动修复参数
+
+以下参数仅在进入修复循环时使用，由 Skill 自动从 `app-metadata.json` 获取，你通常不需要手动指定：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `harmony_project_dir` | 是 | 自动从 `app-metadata.json` 的 `project_root` 字段读取 |
+| `android_project_dir` | 否 | Android 参考项目路径。提供后 fixer 会参考 Android 实现来修 bug，质量更高 |
+
+---
+
+## 输出产物
+
+`testcases.json` 和 `app-metadata.json` 在首轮（`setup=true`）写入 `output_path/` 根目录，后续轮直接复用，不再重新生成。`self-test-report.md` 与 `task/` 每轮都会在根目录覆盖更新，跑完每轮后由 SKILL 快照到 `output_path/round-{n}/`。循环结束后，最后一轮的签名 HAP 镜像到根目录。
+
+| 文件 | 写入位置 | 内容 |
+|------|----------|------|
+| `testcases.json` | `output_path/` 根目录（首轮写入，跨轮共享） | 结构化的用例列表，供 AutoTest 逐条执行 |
+| `app-metadata.json` | `output_path/` 根目录（首轮写入，跨轮共享） | `{ bundle_name, app_name, project_root }` |
+| `_extracted.json` | `output_path/` 根目录（首轮写入，跨轮快照保留） | 用例提取的中间文件，排查问题时有用，通常不需要关注 |
+| `self-test-report.md` | `output_path/` 根目录（每轮覆盖，跨轮快照保留） | 可读的测试报告，含通过率、失败原因、每条用例的 AutoTest 任务路径 |
+| `task/task_<时间戳>/` | `output_path/task/`（每轮覆盖，跨轮快照保留） | 每条用例的 HTML 报告、截图、Agent 日志 |
+| `self-test-fix-report.md` | `output_path/round-{n}/`（Fix 步骤，有失败的轮次） | 白盒审查结论、根因分析、修改内容、修复结果 |
+| `self-test-fix-commit-info.md` | `output_path/round-{n}/`（Fix 步骤） | `commit_id: <hash>` 或 `commit_id: none` |
+| `build-fix-report.md` | `output_path/round-{n}/`（Build 步骤） | 编译是否成功、修复了哪些编译问题 |
+| `build-fix-commit-info.md` | `output_path/round-{n}/`（Build 步骤） | `commit_id: <hash>` 或 `commit_id: none` |
+| `entry-default-signed.hap` | `output_path/round-{n}/`（Build 步骤）；循环结束后镜像到 `output_path/` 根目录 | 修复后重新编译的签名 HAP |
+
+> **提示**：`output_path/` 根目录下的报告和 task 始终是最近一轮的最新产物；要查看某一轮的历史快照，进入对应的 `round-{n}/` 目录即可。
+
+---
+
+## 工作流程
+
+一次完整的 Self-Test 跑下来会经历下面这些阶段，简化的流程示意：
+
+```
+你提供: test_case.md + HAP
+  │
+  ▼
+┌─ 解析阶段（仅首轮）─────────────────────────────────────────┐
+│                                                              │
+│  读取 test_case.md → LLM 提取动作/预期结果 → 替换应用名为包名  │
+│  → Python 脚本生成 testcases.json + 写入 app-metadata.json   │
+│                                                              │
+└──────────────────────────────┬───────────────────────────────┘
+                               │
+                               ▼
+┌─ 测试与修复循环（每轮跑完后快照到 output_path/round-{n}/）──┐
+│                                                              │
+│  ┌── Test ─────────────────────────────────────────────┐    │
+│  │ 检测真机连接 → 安装 HAP → AutoTest 批量执行用例      │    │
+│  │ → 每 60 秒轮询一次 → 产出 round-{n}/self-test-report │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+│                         │                                    │
+│                  全部通过?                                    │
+│              ┌──────┴──────┐                                  │
+│              ▼              ▼                                  │
+│            是(退出循环)    否(进入修复)                         │
+│                             │                                  │
+│  ┌── Fix ──────────────────────────────────────────────┐    │
+│  │ self-test-fixer 读报告 → 白盒审查代码                 │    │
+│  │ → 区分 confirmed(真bug) / false_positive(误报)       │    │
+│  │ → 只修改 confirmed → git commit                      │    │
+│  │ → 产出 round-{n}/self-test-fix-report.md             │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+│                         │                                    │
+│                  有确认缺陷?                                   │
+│              ┌──────┴──────┐                                  │
+│              ▼              ▼                                  │
+│            否(退出循环)    是(进入编译)                         │
+│                             │                                  │
+│  ┌── Build ────────────────────────────────────────────┐    │
+│  │ build-fixer --signed 重新编译 → 产出签名 HAP         │    │
+│  │ → 产出 round-{n}/build-fix-report.md                │    │
+│  │ → 产出 round-{n}/entry-default-signed.hap           │    │
+│  └──────────────────────┬──────────────────────────────┘    │
+│                         │                                    │
+│              未达上限? n++; 回到 Test                          │
+│              ┌──────┴──────┐                                  │
+│              ▼              ▼                                  │
+│            是(下一轮)     否(退出循环)                         │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+              循环结束 → 镜像最终轮报告和 HAP 到 output_path/
+```
+
+### 循环停止条件
+
+满足以下任一条件，循环立即停止：
+
+| 条件 | stop_reason | 说明 |
+|------|-------------|------|
+| 全部通过 | `all_passed` | 报告 `failed == 0`，所有用例通过 |
+| 无确认缺陷 | `no_confirmed_defects` | fixer 判定所有失败都是测试误报（false positive），没有需要修改的代码缺陷 |
+| 达到最大轮数 | `max_rounds_reached` | 已完成配置的最大轮数循环（`max_rounds`，默认 3），仍有失败未解决 |
+| 编译未产出 HAP（异常） | `no_signed_hap` | build-fixer 未产出签名 HAP，无法继续测试 |
+| 用例列表为空（异常） | `no_testcases` | `testcases.json` 里 0 条用例，没有可跑的内容。常见原因：解析阶段没识别到 `### Scenario:` 区块 |
+| 自测 agent 早退（异常） | `agent_early_exit` | `self-tester` 在跑用例之前就退出了（设备没连、autotest api_key 没配（`~/.hometrans/config.json` 的 autotest 块或 `TEST_API_KEY` 环境变量）、`test-tools/autotest` 目录找不到（`HOMETRANS_TOOL_PATH` 环境变量未配置或失效）、batch 启动失败 / 超时 / 崩溃、`setup=false` 但所需 JSON 缺失等）。报告首行会是 `status: FAIL`，第二行 `reason: <原因>`。**这种情况下不会进入 fix 循环**——这些是环境/前置条件问题，不是应用缺陷 |
+
+---
+
+## 前置用例（Pre-Cases）
+
+如果 `test_case.md` 同目录下有 `pre_test_case.md`，系统会自动把它作为前置用例合并进去。前置用例是一些**环境准备操作**——比如授权弹窗、跳过引导、导入素材、授予权限。
+
+- 前置用例在 `testcases.json` 中排在最前面，`case_name` 会自动加 `[PRE] ` 前缀
+- 跑测试时最先执行，为后续用例准备环境
+- **前置用例失败不代表应用有 bug**——通常是没素材、没权限、系统弹窗没弹等环境问题
+- 测试报告会单独标注**常规通过率**（排除前置用例），这才是衡量应用质量的主要指标
+
+---
+
+## 报告解读
+
+### 测试报告（self-test-report.md）
+
+每份报告包含以下部分：
+
+- **测试概览**：设备序列号、HAP 文件名、测试套件名、总用例数、通过/失败数、通过率、常规通过率
+- **前置用例**：`[PRE]` 开头的用例，与常规用例分开列出，各自从 1 开始编号（Pre 1、Pre 2... / Case 1、Case 2...）
+- **用例详情**：每条用例的动作、预期结果、AutoTest 判定结果、失败原因
+- **每条用例都标注了 `**AutoTest 任务路径**`**：指向该用例的原始执行目录（HTML 报告、截图、日志）
+
+**PASS / FAIL / UNKNOWN 的含义：**
+
+- `PASS` — 测试通过
+- `FAIL` — 测试失败或超时/崩溃，`reason` 字段说明原因
+- `UNKNOWN` — 有产出报告但无法明确判定结果
+
+`FAIL` 和 `UNKNOWN` 都应视为未通过。
+
+### 修复报告（self-test-fix-report.md）
+
+- **概览**：失败数 → 确认 bug 数 → 误报数 → 修复成功/失败数
+- **白盒审查结果**：每条失败用例逐一分析，结论为 `confirmed`（代码真有问题）或 `false_positive`（测试误判）
+- **修复计划**：按依赖关系排序的修复列表
+- **修复详情**：每条修复的 Android 参考、根因、具体修改、有效尝试次数、结果
+- **误报说明**：为什么判定为误报，测试 agent 出了什么问题
+- **编译验证**：编译结果及 build-fixer 修复的编译问题
+
+### 编译报告（build-fix-report.md）
+
+build-fixer 的输出摘要：编译状态、签名类型、迭代次数、修复的编译错误数、文件修改汇总。
+
+---
+
+## test_case.md 怎么写
+
+用 Markdown 写，结构如下：
+
+```markdown
+# 测试套件名
+
+## Spec: 功能模块
+### Scenario: 新建歌单
+- 动作：点击新建歌单按钮
+- 预期结果：弹出新建歌单对话框
+- 动作：输入歌单名称"测试歌单"
+- 预期结果：歌单创建成功，出现在列表顶部
+```
+
+- `# 标题` → 测试套件名，会出现在报告里
+- `## Spec:` → 功能模块，纯逻辑分组，不影响执行
+- `### Scenario:` → 一条用例
+- `- 动作：` → 测试操作
+- `- 预期结果：` → 期望结果（多行用中文逗号连接）
+
+**不需要手动替换应用名**。动作里写的显示名称（如"简单图库"、"Tuku"）系统会自动替换成包名（如 `com.example.tuku`），确保 AutoTest 能正确识别目标应用。
+
+**以下内容会被自动忽略**：`- 前置条件：`、`## 页面描述注解`、`## 编号映射表`。
+
+---
+
+## 环境要求
+
+### 基础环境
+
+- 操作系统：**Windows** 是主要测试目标；macOS/Linux 上的核心命令（`hdc`、`uv`、POSIX 工具链）也能跑，Skill 里涉及到的复制操作会按可用 shell 自适应
+- `hdc` 已安装并在 PATH 中
+- `uv` 已安装（Python 包管理）
+- `~/.hometrans/config.json` 的 `autotest` 块已配置真实 api_key。`api_key` 来源：`ht init` 填好 `TEST_API_KEY` 后自动写入该块；若仍是占位符，`self_test_runner.py` 会在跑用例前用 OS 环境变量 `TEST_API_KEY` 自动补全。运行时由脚本读取该块、物化成临时 YAML 交给 `AutoTest.batch`，不再需要 `config.yaml`
+- 鸿蒙真机通过 USB 连接，`hdc list targets` 能看到设备
+- 签名后的 `.hap` 文件
+
+### 自动修复附加条件
+
+- `app-metadata.json` 存在（setup 阶段自动产出，内含 `project_root`）
+- 建议项目在 Git 仓库中（不在也可以修复，但不会自动 commit；`commit_id: none`）
+- 签名配置已存在于 `build-profile.json5`（DevEco Studio → File → Project Structure → Signing Configs → Automatically generate signature）
+
+---
+
+## 常见问题
+
+**Q: 报 "No HarmonyOS device connected"？**
+
+A: 检查 USB 连接，跑 `hdc list targets` 看看有没有设备 SN。重新插拔 USB，在设备上重新授权 USB 调试。
+
+**Q: 报 autotest 配置缺失 或 api_key 没填？**
+
+A: 三选一：① 设置环境变量 `TEST_API_KEY`（`self_test_runner.py` 跑用例前会自动用它填充）；② 重新跑 `ht init` 并填入 `TEST_API_KEY`，它会自动写入 `~/.hometrans/config.json` 的 `autotest` 块；③ 手动编辑 `~/.hometrans/config.json`，把 `autotest.unified_model.api_key` 的 `YOUR_API_KEY_HERE` 替换成真实的 API Key。
+
+**Q: 前置用例失败了要不要修代码？**
+
+A: 不用。前置用例是环境准备脚本，失败意味着环境条件不满足（没素材、没权限、引导弹窗等），不影响应用的常规通过率。
+
+**Q: PASS / FAIL / UNKNOWN 有什么区别？**
+
+A: `PASS` — 通过；`FAIL` — 失败/超时/崩溃，有原因说明；`UNKNOWN` — 有报告但无法判定。后面两个都算未通过。
+
+**Q: 测试跑多久？**
+
+A: 每条用例大约 6 分钟（含 Agent 决策和执行时间）。整体超时上限 = 用例数 × 6 分钟，超过后自动终止并产出部分报告。
+
+**Q: 怎么只重跑失败的用例？**
+
+A: 目前每次都跑 `testcases.json` 的全部用例。你可以手动删掉已通过的条目，只保留失败的，然后用 `setup=false` 重新跑（会跳过解析阶段，直接读取 `<output_path>/testcases.json`）。
+
+**Q: 产物在哪个目录？**
+
+A: `testcases.json` 和 `app-metadata.json` 在 `output_path/` 根目录。测试和修复的每轮产物在 `output_path/round-1/`、`output_path/round-2/`... 子目录中。循环结束后，最终轮的关键文件（报告、HAP）会镜像到 `output_path/` 根目录，方便直接查看。
+
+**Q: 怎么启用自动修复？**
+
+A: 说"跑自测，自动修复"；或者跑完测试后看到有失败，Skill 会主动问你要不要启用，回复"是"就进去了。默认最多 3 轮，需要更多/更少可以加一句"最多 N 轮"（对应 `max_rounds` 参数）。
+
+**Q: 自动修复会改我的代码吗？**
+
+A: 会修改鸿蒙源码来修 bug，但只在**白盒审查确认是真问题**（`confirmed`）的情况下才会改。误报（`false_positive`）不改，测试用例不改。所有修改会 git commit，可随时 revert。如果不在 Git 仓库中，修改照常进行但不 commit。
+
+**Q: 自动修复一轮多久？**
+
+A: Fix（白盒分析 + 改代码）约 5-10 分钟，Build（编译）约 2-5 分钟，Retest（重新跑用例）约 N×6 分钟。可以随时中断。
+
+**Q: 什么情况下循环会停？**
+
+A: 正常退出 3 种：① 全部通过（`all_passed`）；② 所有失败都是误报，无代码缺陷需要修复（`no_confirmed_defects`）；③ 跑满 `max_rounds` 轮（默认 3）仍有失败（`max_rounds_reached`）。异常退出 3 种：编译未产出签名 HAP（`no_signed_hap`）；`testcases.json` 为空（`no_testcases`）；自测 agent 早退，写出首行 `status: FAIL` 的 sentinel 报告（`agent_early_exit`，常见原因：设备没连、api_key 没填、batch 崩溃 / 超时）。异常退出不会进入 fix 循环——那些是环境问题，不是代码缺陷。
+
+**Q: 需要提供 Android 项目路径吗？**
+
+A: 不必须。提供了 fixer 会参考 Android 实现来修 bug，质量更高。不提供也能独立完成，基于白盒代码分析和 HarmonyOS API 文档修复。
+
+**Q: 报 "Build did not produce a signed HAP"？**
+
+A: 通常是因为 `build-profile.json5` 中的签名配置被清掉了。去 DevEco Studio 重新生成（File → Project Structure → Signing Configs → Automatically generate signature），然后继续循环。