@buaa_smat/hometrans 0.1.10 → 0.1.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +1 -1
- package/README.en.md +0 -0
- package/README.md +208 -124
- package/agents/build-fixer.md +17 -10
- package/agents/code-reviewer.md +4 -2
- package/dist/cli/config-store.js +57 -0
- package/dist/cli/config.js +8 -9
- package/dist/cli/init.js +671 -25
- package/dist/cli/mcp-setup.js +2 -6
- package/dist/context/index.js +46 -0
- package/env-requirements.json +181 -0
- package/package.json +3 -2
- package/resource/choose_editor.png +0 -0
- package/resource/hometrans_config.png +0 -0
- package/skills/hmos-convert-pipeline/SKILL.md +19 -11
- package/skills/hmos-fix-build-errors/SKILL.md +13 -5
- package/skills/hmos-incremental-ui-align/SKILL.md +15 -1
- package/skills/hmos-incremental-ui-align/config-example.json +8 -8
- package/resource/finish_init.png +0 -0
package/LICENSE
CHANGED
package/README.en.md
ADDED
|
File without changes
|
package/README.md
CHANGED
|
@@ -1,214 +1,298 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 安卓应用迁移鸿蒙指导
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[English](README.en.md) · **简体中文**
|
|
4
|
+
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
本文档为完整的 Android 到 HarmonyOS 迁移流程指导。
|
|
4
9
|
|
|
5
10
|
---
|
|
6
11
|
|
|
7
|
-
##
|
|
12
|
+
## 步骤 0:安装依赖
|
|
8
13
|
|
|
9
|
-
|
|
14
|
+
### 0.1 安装依赖并连接设备
|
|
10
15
|
|
|
11
|
-
|
|
12
|
-
npm install -g @buaa_smat/hometrans
|
|
13
|
-
ht init
|
|
14
|
-
```
|
|
16
|
+
按以下顺序安装(`ht init` 会逐项检测,并提示缺失项对各 skill 的影响)。各依赖下方均列出了「被依赖」的步骤:如果你不需要执行某依赖所对应的步骤,则可以不安装该依赖(相应 skill 会显示为受限或不可用,但不影响其它步骤)。
|
|
15
17
|
|
|
16
|
-
|
|
18
|
+
1. **安装 DevEco Studio** — 下载地址:<https://developer.huawei.com/consumer/cn/download/>。安装完成后,配置以下 **PATH 环境变量**(`<DevEco安装目录>` 指 DevEco Studio 的安装根目录):
|
|
17
19
|
|
|
18
|
-
|
|
20
|
+
| 工具 | PATH 中加入的目录 |
|
|
21
|
+
|------|------------------|
|
|
22
|
+
| node / npm / npx | `<DevEco安装目录>\tools\node` |
|
|
23
|
+
| java | `<DevEco安装目录>\jbr\bin` |
|
|
24
|
+
| hdc | `<DevEco安装目录>\sdk\default\openharmony\toolchains` |
|
|
19
25
|
|
|
20
|
-
|
|
26
|
+
验证方式:执行 `node -v`、`java -version`、`hdc -v` 均返回正常
|
|
21
27
|
|
|
22
|
-
|
|
28
|
+
被依赖:
|
|
29
|
+
- 步骤 1 资源转换(java 可选,缺失时回退读取源码 `res/`)
|
|
30
|
+
- 步骤 2.2 增量 UI 迁移(必需)
|
|
31
|
+
- 步骤 4 逻辑代码转换流水线(必需,构建/评审修复)
|
|
32
|
+
- 步骤 5 自测回归(必需,真机调试)
|
|
33
|
+
2. **安装 Android Studio** — 下载地址:<https://developer.android.com/studio>,并在 **SDK Manager** 中安装 SDK。
|
|
23
34
|
|
|
24
|
-
|
|
35
|
+
验证方式:执行 `adb version` 返回正常
|
|
25
36
|
|
|
26
|
-
|
|
37
|
+
被依赖:
|
|
38
|
+
- 步骤 2.1 全量 UI 迁移(可选,仅自动抓取页面快照时需要)
|
|
39
|
+
- 步骤 2.2 增量 UI 迁移(必需)
|
|
40
|
+
3. **安装 uv** — 安装指引:<https://docs.astral.sh/uv/getting-started/installation/>。
|
|
27
41
|
|
|
28
|
-
|
|
42
|
+
验证方式:执行 `uv --version` 返回正常
|
|
29
43
|
|
|
30
|
-
|
|
44
|
+
被依赖:
|
|
45
|
+
- 步骤 4 逻辑代码转换流水线的自测阶段(可经 `skip-test` 跳过)
|
|
46
|
+
- 步骤 5 自测回归(必需,AutoTest 在 uv 下运行)
|
|
47
|
+
4. **安装 python** — 安装指引:<https://www.python.org/downloads/>,要求 ≥ 3.10。
|
|
31
48
|
|
|
32
|
-
|
|
49
|
+
验证方式:执行 `python --version` 返回正常
|
|
33
50
|
|
|
34
|
-
|
|
51
|
+
被依赖:
|
|
52
|
+
- 步骤 2.1 全量 UI 迁移(必需,页面快照解析脚本)
|
|
53
|
+
- 步骤 2.2 增量 UI 迁移(必需,双端页面采集脚本)
|
|
54
|
+
5. **安装 [GitNexus](https://github.com/abhigyanpatwari/GitNexus)** — 执行 `npm install -g gitnexus && gitnexus setup`
|
|
35
55
|
|
|
36
|
-
|
|
56
|
+
验证方式:执行 `gitnexus --version` 返回正常
|
|
37
57
|
|
|
38
|
-
|
|
58
|
+
被依赖:
|
|
59
|
+
- 步骤 3 生成需求规格(必需)
|
|
60
|
+
6. **连接设备** — 连接安卓和鸿蒙真机,或启动模拟器
|
|
39
61
|
|
|
40
|
-
|
|
62
|
+
被依赖:
|
|
63
|
+
- 安卓真机/模拟器 — 步骤 2 UI 迁移
|
|
64
|
+
- 鸿蒙真机/模拟器 — 步骤 2.2 增量 UI 迁移
|
|
65
|
+
- 鸿蒙**真机** — 步骤 4 流水线自测阶段、步骤 5 自测回归
|
|
41
66
|
|
|
42
|
-
|
|
67
|
+
### 0.2 安装 hometrans
|
|
43
68
|
|
|
44
|
-
|
|
45
|
-
npm install -g gitnexus
|
|
46
|
-
gitnexus setup
|
|
47
|
-
```
|
|
69
|
+
执行 `npm install -g @buaa_smat/hometrans`。
|
|
48
70
|
|
|
49
|
-
|
|
71
|
+
验证方式:执行 `hometrans --version` 或 `ht --version` 返回正常
|
|
72
|
+
|
|
73
|
+
然后执行 `hometrans init` 或 `ht init`,配置 `DEVECO_SDK_HOME`、`TEST_API_KEY`、`GLM_API_KEY`。
|
|
50
74
|
|
|
51
|
-
---
|
|
52
75
|
|
|
53
|
-
|
|
76
|
+
> 如果在 PowerShell 下运行,命令需要加上 `.cmd` 后缀,如 `hometrans.cmd --version`、`ht.cmd init`。
|
|
54
77
|
|
|
55
|
-
|
|
78
|
+
选择本地 editor:
|
|
56
79
|
|
|
57
|
-
|
|
80
|
+
|
|
58
81
|
|
|
59
|
-
|
|
82
|
+
参数配置:
|
|
60
83
|
|
|
61
|
-
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
- `DEVECO_SDK_HOME` — DevEco Studio 的 sdk 目录(唯一输入),其余路径由它派生并校验存在,示例:
|
|
87
|
+
|
|
88
|
+
```text
|
|
89
|
+
+ DEVECO_SDK_HOME : <DevEco安装目录>\sdk
|
|
90
|
+
+ DEVECO_PATH : <DevEco安装目录>
|
|
91
|
+
+ OHOS_SDK_PATH : <DevEco安装目录>\sdk\default\openharmony\ets
|
|
92
|
+
+ HMS_SDK_PATH : <DevEco安装目录>\sdk\default\hms\ets
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
- `TEST_API_KEY` — 集成测试 agent 执行测试用例(真机自测)所用的 LLM API key。目前 AutoTest 仅支持**单层模式**(`agent_mode: single`),走阿里云百炼(DashScope)兼容接口下的通义模型 `qwen3.5-plus`(见用户目录下 `~/.hometrans/tools/test-tools/autotest/config.yaml` 的 `unified_model`;Windows 即 `C:\Users\<用户名>\.hometrans\tools\test-tools\autotest\config.yaml`)。该文件由 `ht init` 在首次运行时从同目录的 `config.yaml.example` 自动生成,并把此处填写的 `TEST_API_KEY` 写入其中的 `api_key`。在阿里云百炼平台 https://bailian.console.aliyun.com/ 申请 API Key 并开通对应模型,按量计费。如需更换模型,可直接编辑上述 `config.yaml` 中 `unified_model` 的 `name`/`base_url`/`provider`/`api_key`。
|
|
96
|
+
- `GLM_API_KEY` — UI对齐中过程中GLM phone agent 所用的 LLM API key。`GLM_API_KEY`在智谱官方网站https://bigmodel.cn/apikey/platform申请API KEY即可，调用的是免费的auto-glm模型，无需充值。
|
|
97
|
+
|
|
98
|
+
### 0.3 准备项目
|
|
99
|
+
|
|
100
|
+
准备 **Android 源项目** 与 **HarmonyOS 目标项目目录**。
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## 步骤 1:资源转换(`hmos-resources-convert`)
|
|
105
|
+
|
|
106
|
+
> 📦 依赖:DevEco Studio 中的 java(可选,缺失时回退读取源码 `res/`)。
|
|
107
|
+
|
|
108
|
+
> ⚠️ 提示:如果步骤 2 的 UI 迁移采用**全量迁移**(`hmos-batch-ui-align`),则跳过当前步骤(全量UI迁移内部已包含资源转换)。
|
|
62
109
|
|
|
63
110
|
```
|
|
64
111
|
/hmos-resources-convert android-project-path=<安卓项目路径> harmonyos-project-path=<鸿蒙项目路径> resource_mapping_path=<资源映射文档路径>
|
|
65
112
|
```
|
|
66
113
|
|
|
114
|
+
**输入参数**
|
|
115
|
+
|
|
67
116
|
| 参数 | 类型 | 说明 |
|
|
68
117
|
|------|------|------|
|
|
69
|
-
| `android-project-path` | **必选** | Android
|
|
118
|
+
| `android-project-path` | **必选** | Android 项目根目录路径(含 `build.gradle` 或 `build.gradle.kts`) |
|
|
70
119
|
| `harmonyos-project-path` | **必选** | HarmonyOS 项目输出路径 |
|
|
71
|
-
| `resource_mapping_path` | **必选** | Android ↔ HarmonyOS
|
|
72
|
-
| `apk-path` | 可选 | Android APK
|
|
120
|
+
| `resource_mapping_path` | **必选** | Android ↔ HarmonyOS 资源映射文档的完整输出路径(`.md`) |
|
|
121
|
+
| `apk-path` | 可选 | Android APK 文件路径;提供后跳过 Gradle 构建和 apktool 解包,直接从 APK 提取资源 |
|
|
122
|
+
|
|
123
|
+
**输出产物**
|
|
124
|
+
|
|
125
|
+
| 产物 | 位置 | 说明 |
|
|
126
|
+
|------|------|------|
|
|
127
|
+
| `resources/` 目录 | HarmonyOS 项目下 | 转换后的 HarmonyOS 资源(strings、colors、dimensions、images 等) |
|
|
128
|
+
| 资源映射文档 | `resource_mapping_path` | Android ↔ HarmonyOS 资源条目映射(`.md`) |
|
|
129
|
+
| 转换报告 | HarmonyOS 项目下 | 资源转换过程与统计 |
|
|
73
130
|
|
|
74
|
-
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## 步骤 2:UI 迁移
|
|
75
134
|
|
|
76
|
-
|
|
135
|
+
### 2.1 全量迁移(`hmos-batch-ui-align`)
|
|
77
136
|
|
|
78
|
-
|
|
137
|
+
> 📦 依赖:python(必需,页面快照解析脚本);Android Studio + 安卓真机/模拟器(可选,仅自动抓取页面快照时需要)。
|
|
79
138
|
|
|
80
139
|
```
|
|
81
140
|
/hmos-batch-ui-align android_project_dir=<安卓项目路径> harmony_project_dir=<鸿蒙项目路径> ui_info_root=<页面快照目录>
|
|
82
141
|
```
|
|
83
142
|
|
|
84
|
-
|
|
143
|
+
**输入参数**
|
|
144
|
+
|
|
145
|
+
| 参数 | 类型 | 说明 |
|
|
146
|
+
|------|------|-------------------------------------------------------------------------------------------------------------|
|
|
147
|
+
| `android_project_dir` | **必选** | Android 项目根目录路径 |
|
|
148
|
+
| `harmony_project_dir` | **必选** | HarmonyOS 项目输出路径 |
|
|
149
|
+
| `ui_info_root` | 可选 | 包含 `page_NNNN_ActivityName` 格式子目录的父目录(每子目录含 `meta.json` + `view.xml` + 可选 `screenshot.png`);不提供时自动通过 adb 抓取 |
|
|
150
|
+
| `pages` | 可选 | 显式列出的页面子集(不提供则处理所有页面) |
|
|
151
|
+
|
|
152
|
+
**输出产物**
|
|
153
|
+
|
|
154
|
+
| 产物 | 位置 | 说明 |
|
|
85
155
|
|------|------|------|
|
|
86
|
-
|
|
|
87
|
-
|
|
|
88
|
-
|
|
|
89
|
-
|
|
156
|
+
| ArkTS 页面文件 | HarmonyOS 项目下 | 由 Android Activity 转换生成的 ArkTS 页面 |
|
|
157
|
+
| 资源文件 | HarmonyOS 项目下 | 页面所需资源(含全量迁移内部触发的资源转换产物) |
|
|
158
|
+
| 批量转换报告 | HarmonyOS 项目下 | 各页面转换结果、缺陷与统计 |
|
|
159
|
+
|
|
160
|
+
### 2.2 增量迁移(`hmos-incremental-ui-align`,按需)
|
|
90
161
|
|
|
91
|
-
|
|
162
|
+
> 📦 依赖:DevEco Studio、Android Studio、python(必需,双端页面采集脚本);安卓真机/模拟器 + 鸿蒙真机/模拟器(必需)。
|
|
92
163
|
|
|
93
|
-
|
|
164
|
+
> 👤 前置:需用户预先配置好 `config.json`(双端 app 包名/工程路径等,参考 skill 目录下 `config-example.json`;`ht init` 已预置并填充 `glm_api_key` / `hmos_sdk_dir`)。对齐目标在消息中描述,如 "帮我对齐设置页面的关于页面"。
|
|
94
165
|
|
|
95
166
|
```
|
|
96
167
|
/hmos-incremental-ui-align config-path=<config.json路径>
|
|
97
168
|
```
|
|
98
169
|
|
|
170
|
+
**输入参数**
|
|
171
|
+
|
|
99
172
|
| 参数 | 类型 | 说明 |
|
|
100
173
|
|------|------|------|
|
|
101
|
-
| `config-path` |
|
|
174
|
+
| `config-path` | 可选 | `config.json` 路径,含 `android.project_dir`、`harmony.project_dir`、`hmos_sdk_dir`、`glm_api_key`、`capture_output_dir` 等字段;|
|
|
175
|
+
|
|
176
|
+
**输出产物**
|
|
177
|
+
|
|
178
|
+
| 产物 | 位置 | 说明 |
|
|
179
|
+
|------|------|------|
|
|
180
|
+
| 修改后的 ArkTS 页面文件 | HarmonyOS 项目下 | 对齐目标页面后的代码改动 |
|
|
181
|
+
| 双端页面截图与视图树 | `capture_output_dir` | Android/HarmonyOS 两侧 `screenshot.png` + 视图树文件 |
|
|
182
|
+
| 对齐差异/修复报告 | `capture_output_dir` | 差异分析与修复说明 |
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## 步骤 3:生成需求规格(`hmos-spec-generate`)
|
|
102
187
|
|
|
103
|
-
|
|
188
|
+
> 📦 依赖:GitNexus(必需)。
|
|
104
189
|
|
|
105
|
-
|
|
190
|
+
> 👤 前置:用户编写 REQ `.txt` 文件 — 每段一个需求、空行分隔,作为本步骤规格生成的输入来源。
|
|
106
191
|
|
|
107
192
|
```
|
|
108
193
|
/hmos-spec-generate requirement-description-file=<需求描述文件路径> android-project-path=<安卓项目路径> spec-output-dir=<规格输出目录>
|
|
109
194
|
```
|
|
110
195
|
|
|
196
|
+
**输入参数**
|
|
197
|
+
|
|
111
198
|
| 参数 | 类型 | 说明 |
|
|
112
199
|
|------|------|------|
|
|
113
|
-
| `requirement-description-file` | **必选** | 需求描述 `.txt`
|
|
114
|
-
| `android-project-path` | **必选** | Android
|
|
115
|
-
| `spec-output-dir` | **必选** |
|
|
200
|
+
| `requirement-description-file` | **必选** | 需求描述 `.txt` 文件路径(每段以 `REQ` 开头,空行分隔) |
|
|
201
|
+
| `android-project-path` | **必选** | Android 项目根目录路径(必须位于 Git 仓库内) |
|
|
202
|
+
| `spec-output-dir` | **必选** | 规格文档输出目录(自动创建;每个 REQ 生成 `<feature>-SPEC.md` + `.trace/<feature>.md`) |
|
|
203
|
+
|
|
204
|
+
**输出产物**
|
|
205
|
+
|
|
206
|
+
| 产物 | 位置 | 说明 |
|
|
207
|
+
|------|------|------|
|
|
208
|
+
| `<feature>-SPEC.md` | `spec-output-dir` | 每个 REQ 对应一份原子场景规格文档 |
|
|
209
|
+
| `.trace/<feature>.md` | `spec-output-dir/.trace/` | 每个 REQ 对应的代码 trace(GitNexus 探索结果) |
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## 步骤 4:逻辑代码转换流水线(`hmos-convert-pipeline`)
|
|
116
214
|
|
|
117
|
-
|
|
215
|
+
> 📦 依赖:DevEco Studio(必需,构建/评审修复);uv + 鸿蒙真机(自测阶段需要,可经 `skip-test` 跳过)。
|
|
118
216
|
|
|
119
|
-
|
|
217
|
+
> 👤 前置:
|
|
218
|
+
> 1. **编写测试用例文档**(自测阶段的依据),路径经可选参数 `test-case-path` 传入(默认读输出目录下 `test_case.md`;前置用例同理 `pre-test-case-path`)。
|
|
219
|
+
> 2. 连接 HarmonyOS 真机,在 DevEco Studio 中[**配置签名**](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/networkboost-preparations#%E9%85%8D%E7%BD%AE%E7%AD%BE%E5%90%8D)。
|
|
120
220
|
|
|
121
221
|
```
|
|
122
|
-
/hmos-convert-pipeline android-project-path=<安卓项目路径> harmonyos-project-path=<鸿蒙项目路径>
|
|
222
|
+
/hmos-convert-pipeline android-project-path=<安卓项目路径> harmonyos-project-path=<鸿蒙项目路径> spec-file-path=<需求规格文档路径>
|
|
123
223
|
```
|
|
124
224
|
|
|
225
|
+
**输入参数**
|
|
226
|
+
|
|
125
227
|
| 参数 | 类型 | 说明 |
|
|
126
228
|
|------|------|------|
|
|
127
229
|
| `android-project-path` | **必选** | Android 项目根目录路径 |
|
|
128
230
|
| `harmonyos-project-path` | **必选** | HarmonyOS 项目根目录路径 |
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
| `
|
|
132
|
-
| `
|
|
133
|
-
|
|
134
|
-
|
|
231
|
+
| `spec-file-path` | **必选** | 需求规格文档路径(各阶段直接读取,无需复制到输出目录) |
|
|
232
|
+
| `assets-output-path` | 可选 | 输出/报告文件存放目录(默认鸿蒙工程下 `.hometrans_output`,自动创建) |
|
|
233
|
+
| `test-case-path` | 可选 | 自测用例文件路径(默认读输出目录下 `test_case.md`;不存在则跳过自测循环) |
|
|
234
|
+
| `pre-test-case-path` | 可选 | 前置用例文件路径(默认读输出目录下 `pre_test_case.md`;存在才传给自测) |
|
|
235
|
+
| `max-rounds-review` | 可选 | 代码检视循环最大轮数(正整数 `>= 1`,默认 `2`) |
|
|
236
|
+
| `max-rounds-test` | 可选 | 自测循环最大轮数(正整数 `>= 1`,默认 `2`) |
|
|
237
|
+
| `skip-test` | 可选 | `true` 跳过集成测试阶段(无真机验证环境时设为 `true`,默认 `false`) |
|
|
135
238
|
|
|
136
|
-
|
|
239
|
+
> 参数按位置传递:要传某个可选参数,需先显式给出它前面的所有可选参数。
|
|
137
240
|
|
|
138
|
-
|
|
139
|
-
|---------|-------------|
|
|
140
|
-
| `ht init` | Interactive setup: detect installed editors, prompt for SDK paths + test API key, copy skills/agents to target directories, seed/refresh autotest `config.yaml`, register MCP server |
|
|
141
|
-
| `ht mcp` | Start the HomeTrans MCP server (stdio mode), exposing the `extract_commit_context` tool |
|
|
142
|
-
| `ht config` | Display `~/.hometrans/config.json` path, parameters (with masked API key), and full content (read-only; edit the file directly, then re-run `ht init`) |
|
|
143
|
-
| `ht uninstall` | Remove all skills, agents, and MCP entries installed by `ht init` from configured editors |
|
|
144
|
-
| `ht --version` | Show installed version |
|
|
145
|
-
| `ht --help` | List all commands |
|
|
241
|
+
**输出产物**
|
|
146
242
|
|
|
147
|
-
|
|
243
|
+
| 产物 | 位置 | 说明 |
|
|
244
|
+
|------|------|------|
|
|
245
|
+
| 已签名 HAP | HarmonyOS 项目下 `build/` | 通过自测/评审循环后的最终发布包 |
|
|
246
|
+
| `pipeline-manifest.md` | `assets-output-path` | 流水线清单:阶段耗时、轮数、缺陷统计 |
|
|
247
|
+
| 构建阶段报告 | `assets-output-path` | 编译错误与修复记录 |
|
|
248
|
+
| 评审阶段报告 | `assets-output-path` | 代码检视报告与修复记录 |
|
|
249
|
+
| 自测阶段报告 | `assets-output-path` | 测试结果、失败用例与修复记录 |
|
|
148
250
|
|
|
149
251
|
---
|
|
150
252
|
|
|
151
|
-
##
|
|
152
|
-
|
|
153
|
-
1. **Detects** each supported editor by checking whether its standard config directory exists under `$HOME`, then lets you select which ones to configure (detected editors are pre-checked). Use `ht init --all` to skip the prompt and select every editor.
|
|
154
|
-
2. **Prompts for user parameters** and stores them in `~/.hometrans/config.json` (press Enter to keep the current value or leave empty):
|
|
155
|
-
- `OHOS_SDK_PATH` — OpenHarmony SDK ETS path
|
|
156
|
-
- `HMS_SDK_PATH` — HMS SDK ETS path
|
|
157
|
-
- `TEST_API_KEY` — API key written into the autotest `config.yaml`
|
|
158
|
-
These are stored under a single `env` object in `~/.hometrans/config.json` (alongside `TOOL_PATH`, set in the next step).
|
|
159
|
-
3. **Installs bundled tools** to `~/.hometrans/tools` (the AutoTest toolchain lives at `~/.hometrans/tools/test-tools/autotest`) and records the destination as `env.TOOL_PATH` in `~/.hometrans/config.json`. Agents/skills resolve the AutoTest dir from `env.TOOL_PATH`.
|
|
160
|
-
4. **Seeds/refreshes the autotest config**: if `<TOOL_PATH>/test-tools/autotest/config.yaml` is missing it is created from `config.yaml.example`, and every `api_key:` line is filled with the supplied `TEST_API_KEY`.
|
|
161
|
-
5. For every selected editor, **copies**:
|
|
162
|
-
- every skill folder under `skills/` (those containing a `SKILL.md`) → `<editor>/skills/<skill-name>/` (recursive — preserves subdirectory structure)
|
|
163
|
-
- every agent under `agents/` → `<editor>/agents/` (recursive — preserves `<agent>/scripts/` subtrees)
|
|
164
|
-
6. **Registers the MCP server** (auto-adapts to editor config format: jsonc-object / jsonc-command-array / codex-cli / toml-section).
|
|
165
|
-
7. Editors whose marker directory is missing are reported as **`skipped`** — nothing is written for them.
|
|
166
|
-
8. The install is **idempotent** — re-running overwrites bundled content only. It never touches files under `<editor>/skills/` or `<editor>/agents/` that don't share a name with a bundled item.
|
|
167
|
-
|
|
168
|
-
### Target directories
|
|
169
|
-
|
|
170
|
-
| Editor | Marker | Skills target | Agents target | MCP config |
|
|
171
|
-
|--------|--------|---------------|---------------|------------|
|
|
172
|
-
| Claude Code | `~/.claude/` | `~/.claude/skills/` | `~/.claude/agents/` | `~/.claude.json` → `mcpServers.hometrans` |
|
|
173
|
-
| Cursor | `~/.cursor/` | `~/.cursor/skills/` | `~/.cursor/agents/` | `~/.cursor/mcp.json` → `mcpServers.hometrans` |
|
|
174
|
-
| OpenCode | `~/.config/opencode/` | `~/.config/opencode/skills/` | `~/.config/opencode/agents/` | `~/.config/opencode/opencode.json` → `mcp.hometrans` |
|
|
175
|
-
| Codex | `~/.codex/` | `~/.agents/skills/` | `~/.codex/agents/` | `codex mcp add` → `~/.codex/config.toml` `[mcp_servers.hometrans]` |
|
|
176
|
-
| CodeBuddy | `~/.codebuddy/` | `~/.codebuddy/skills/` | `~/.codebuddy/agents/` | `~/.codebuddy/mcp.json` → `mcpServers.hometrans` |
|
|
253
|
+
## 步骤 5:自测回归(`hmos-integration-test`,可反复执行)
|
|
177
254
|
|
|
178
|
-
|
|
255
|
+
> 📦 依赖:DevEco Studio(必需,真机调试);uv(必需,AutoTest 在 uv 下运行);鸿蒙真机(必需)。
|
|
256
|
+
|
|
257
|
+
```
|
|
258
|
+
/hmos-integration-test test-case-path=<测试用例路径> hap-path=<签名HAP路径>
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
**输入参数**
|
|
179
262
|
|
|
180
|
-
|
|
263
|
+
| 参数 | 类型 | 说明 |
|
|
264
|
+
|------|------|------|
|
|
265
|
+
| `test-case-path` | **必选** | `test_case.md` 测试用例文件路径 |
|
|
266
|
+
| `hap-path` | **必选** | 已签名的 HAP 文件路径 |
|
|
267
|
+
| `output-path` | 可选 | 报告输出目录 |
|
|
268
|
+
| `pre-test-case-path` | 可选 | 前置用例文件路径 |
|
|
269
|
+
| `android-project-path` | 可选 | Android 项目路径(修复时参考) |
|
|
270
|
+
| `max-rounds` | 可选 | 测试-修复循环最大轮数(默认 `3`) |
|
|
181
271
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
|
185
|
-
|
|
186
|
-
|
|
|
187
|
-
|
|
|
188
|
-
|
|
|
189
|
-
| `hmos-integration-test` | "跑自测", "运行自测", "自动测试", "设备测试", "self test", "run autotest" | Runs on-device self-test for a HarmonyOS app: parses `test_case.md`, installs the HAP, executes AutoTest, and produces a verification report — optionally entering a test-and-fix loop | 需存在 `test_case.md` 测试用例文件，设备需安装待测 HAP | `test-case-path` (required), `hap-path` (required), `output-path` (optional), `pre-test-case-path` (optional), `android-project-path` (optional), `max-rounds` (optional, default 3) | `"/hmos-integration-test test-case-path=D:/path/to/test_case.md hap-path=D:/path/to/app-signed.hap"` |
|
|
190
|
-
| `hmos-fix-build-errors` | "build HarmonyOS project", "fix compile errors", "auto build and fix", "hmos-fix-build-errors" | Builds a HarmonyOS NEXT project from the command line, parses compile errors, fixes them, and retries in a loop until the build succeeds. Default produces an unsigned HAP; `--signed` produces a signed HAP | 有效的 HarmonyOS 项目（含 `build-profile.json5`、`entry/src`、`oh-package.json5`）+ DevEco Studio 安装目录；`--signed` 时签名配置须已存在于 `build-profile.json5` | `harmonyos-project-path` (required), `deveco-studio-path` (required), `--signed` (optional) | `"/hmos-fix-build-errors D:/MyHmosApp \"D:/DevEco Studio\" --signed"` |
|
|
272
|
+
**输出产物**
|
|
273
|
+
|
|
274
|
+
| 产物 | 位置 | 说明 |
|
|
275
|
+
|------|------|------|
|
|
276
|
+
| 测试报告 | `output-path` | 测试结果、通过/失败用例统计 |
|
|
277
|
+
| 失败用例详情 | `output-path` | 失败用例的复现步骤与日志 |
|
|
278
|
+
| 修复建议 | `output-path` | 针对失败用例的修复方向(进入测试-修复循环时生效) |
|
|
191
279
|
|
|
192
280
|
---
|
|
193
281
|
|
|
194
|
-
##
|
|
282
|
+
## 步骤 6:人工验收(👤 用户介入)
|
|
195
283
|
|
|
196
|
-
|
|
197
|
-
|-------|-------------|
|
|
198
|
-
| `logic-context-builder` | Constrains HarmonyOS ArkTS app changes into an executable decision contract |
|
|
199
|
-
| `logic-coder` | Executes HarmonyOS ArkTS code implementation from the decision contract (ships with `scripts/platform_context_query.py`) |
|
|
200
|
-
| `build-fixer` | Automatically builds a HarmonyOS project, parses compile errors, fixes them, and retries in a loop until the build succeeds |
|
|
201
|
-
| `code-reviewer` | Reviews HarmonyOS code against user scenarios to validate functional coverage |
|
|
202
|
-
| `review-fixer` | Fixes issues from code review reports — verifies each issue before fixing, references Android source, uses cautious per-scenario fix strategies |
|
|
203
|
-
| `spec-generator` | Generates requirement spec documents for each requirement description file in a folder by exploring the Android codebase and decomposing into atomic user scenarios |
|
|
204
|
-
| `self-tester` | Unified self-test agent — parses `test_case.md` into `testcases.json`, runs on-device AutoTest verification, and produces a report. A `setup` boolean controls whether the parse phase runs (skip on round-2+ to reuse prior artifacts) |
|
|
205
|
-
| `self-test-fixer` | Fixes issues identified by self-testing — reads the self-test report, white-box verifies failures, plans and executes fixes in order |
|
|
284
|
+
**输入**
|
|
206
285
|
|
|
207
|
-
|
|
286
|
+
| 输入 | 说明 |
|
|
287
|
+
|------|------|
|
|
288
|
+
| `pipeline-manifest.md` | 流水线清单与缺陷统计 |
|
|
289
|
+
| 自测报告 | 步骤 5/步骤 4 自测阶段产出的测试报告 |
|
|
290
|
+
| 已签名 HAP | 步骤 4 流水线产出的最终发布包 |
|
|
208
291
|
|
|
292
|
+
**输出**
|
|
209
293
|
|
|
294
|
+
| 产物 | 说明 |
|
|
295
|
+
|------|------|
|
|
296
|
+
| 可发布的 HarmonyOS 应用 | 已处理报告中的遗留缺陷/TODO,通过核心场景走查 |
|
|
210
297
|
|
|
211
|
-
|
|
212
|
-
<a href="https://gitcode.com/SMAT/HomeTrans">Official Repository</a> •
|
|
213
|
-
<a href="https://gitcode.com/SMAT/HomeTrans/blob/main/LICENSE">MIT License</a>
|
|
214
|
-
</p>
|
|
298
|
+
通读 `pipeline-manifest.md` 与自测报告,真机走查核心场景,处理报告中的遗留缺陷/TODO 后发布。
|
package/agents/build-fixer.md
CHANGED
|
@@ -37,21 +37,28 @@ Read the config file written by `ht init` at `~/.hometrans/config.json` (`$HOME/
|
|
|
37
37
|
{
|
|
38
38
|
"editors": [ /* ... */ ],
|
|
39
39
|
"env": {
|
|
40
|
-
"
|
|
41
|
-
"
|
|
40
|
+
"DEVECO_SDK_HOME": "...", // DevEco sdk dir, e.g. "D:/DevEco Studio/sdk" — single source of truth
|
|
41
|
+
"DEVECO_PATH": "...", // DevEco install root, e.g. "D:/DevEco Studio" (derived from DEVECO_SDK_HOME)
|
|
42
|
+
"OHOS_SDK_PATH": "...", // <DEVECO_SDK_HOME>/default/openharmony/ets (derived)
|
|
43
|
+
"HMS_SDK_PATH": "...", // <DEVECO_SDK_HOME>/default/hms/ets (derived)
|
|
42
44
|
"TEST_API_KEY": "...",
|
|
43
45
|
"TOOL_PATH": "..." // HomeTrans tools dir, e.g. "C:/Users/<you>/.hometrans/tools"
|
|
44
46
|
}
|
|
45
47
|
}
|
|
46
48
|
```
|
|
47
49
|
|
|
48
|
-
|
|
50
|
+
### 0b. Resolve the DevEco root `<deveco>` — config first, then env vars, then ask
|
|
49
51
|
|
|
50
|
-
|
|
52
|
+
Stop at the **first** source that yields a path:
|
|
51
53
|
|
|
52
|
-
|
|
54
|
+
1. **Config file** (`~/.hometrans/config.json`):
|
|
55
|
+
- `env.DEVECO_PATH` if non-empty → that is `<deveco>`.
|
|
56
|
+
- else `env.DEVECO_SDK_HOME` → `<deveco>` is its **parent directory**.
|
|
57
|
+
- else (legacy configs) strip the trailing `/sdk/default/openharmony/ets` from `env.OHOS_SDK_PATH` (or `/sdk/default/hms/ets` from `env.HMS_SDK_PATH`) to get `<deveco>`.
|
|
58
|
+
2. **Environment variables** (same precedence): `DEVECO_PATH` → `DEVECO_SDK_HOME` (parent dir) → `OHOS_SDK_PATH` / `HMS_SDK_PATH` (strip suffix as above).
|
|
59
|
+
3. **Auto-detect** (0c below). If that also fails, **ask the user** for the DevEco Studio install path.
|
|
53
60
|
|
|
54
|
-
> Example: `
|
|
61
|
+
> Example: `DEVECO_SDK_HOME = D:/DevEco Studio/sdk` → `<deveco> = D:/DevEco Studio`.
|
|
55
62
|
|
|
56
63
|
From `<deveco>`, derive:
|
|
57
64
|
- **Node executable**: `<deveco>/tools/node/node.exe`
|
|
@@ -59,11 +66,11 @@ From `<deveco>`, derive:
|
|
|
59
66
|
- **ohpm**: `<deveco>/tools/ohpm/bin/ohpm`
|
|
60
67
|
- **SDK directory**: `<deveco>/sdk`
|
|
61
68
|
|
|
62
|
-
Verify these files exist. If they do, use them and skip auto-detection.
|
|
69
|
+
Verify these files exist. If they do, use them and skip auto-detection. If a config-sourced path does **not** exist on disk, treat that source as invalid and continue down the resolution order.
|
|
63
70
|
|
|
64
|
-
### 0c. Auto-detect if config
|
|
71
|
+
### 0c. Auto-detect if config and env vars are missing or invalid
|
|
65
72
|
|
|
66
|
-
If
|
|
73
|
+
If neither the config file nor environment variables yield a valid install, auto-detect:
|
|
67
74
|
|
|
68
75
|
1. **Find DevEco Studio installation**:
|
|
69
76
|
- Search common locations: `D:\DevEco Studio`, `C:\DevEco Studio`, `C:\Program Files\DevEco Studio`
|
|
@@ -74,7 +81,7 @@ If `~/.hometrans/config.json` is missing, has empty `env.OHOS_SDK_PATH`/`HMS_SDK
|
|
|
74
81
|
- `where node` (Windows) or `which node` (Unix)
|
|
75
82
|
- Verify it runs: `node --version`
|
|
76
83
|
|
|
77
|
-
If auto-detection fails for any critical path, **
|
|
84
|
+
If auto-detection fails for any critical path, **ask the user directly** for the DevEco Studio install path (and suggest running `ht init` to persist it for next time).
|
|
78
85
|
|
|
79
86
|
### 0d. Store resolved paths
|
|
80
87
|
|
package/agents/code-reviewer.md
CHANGED
|
@@ -33,8 +33,10 @@ Before starting the review, extract the code context for the commit via the `ext
|
|
|
33
33
|
- `projectPath`: `<harmonyos-project-path>` (absolute path to the HarmonyOS project root containing the `.git` directory)
|
|
34
34
|
- `commitId`: `<commit-id>` (the git commit to analyze — diffs against its first parent)
|
|
35
35
|
- `mode`: `"default"` (builds full call graph for call-chain context)
|
|
36
|
-
- `ohosSdkPath`: the OpenHarmony SDK ETS directory
|
|
37
|
-
|
|
36
|
+
- `ohosSdkPath` / `hmsSdkPath`: the OpenHarmony / HMS SDK ETS directory paths. Resolve each in this order, stop at the first hit:
|
|
37
|
+
1. `env.OHOS_SDK_PATH` / `env.HMS_SDK_PATH` from `~/.hometrans/config.json` (on Windows `%USERPROFILE%\.hometrans\config.json`); if those are empty but `env.DEVECO_SDK_HOME` is set, derive them as `<DEVECO_SDK_HOME>/default/openharmony/ets` and `<DEVECO_SDK_HOME>/default/hms/ets`.
|
|
38
|
+
2. Omit the parameter to let the tool read `OHOS_SDK_PATH` / `HMS_SDK_PATH` from the environment variables.
|
|
39
|
+
3. If neither config nor environment provides a path that exists on disk, **ask the user** for the DevEco `sdk` directory (and suggest `ht init` to persist it).
|
|
38
40
|
|
|
39
41
|
2. **On success** — the tool returns the affected code context (diffs, call graphs, impacted files). Treat this response as the **code context** for the review.
|
|
40
42
|
|
package/dist/cli/config-store.js
CHANGED
|
@@ -8,6 +8,38 @@
|
|
|
8
8
|
import fs from 'node:fs/promises';
|
|
9
9
|
import path from 'node:path';
|
|
10
10
|
import os from 'node:os';
|
|
11
|
+
/** 由 DEVECO_SDK_HOME 派生其余三个 SDK 相关路径。输入为空时全部返回空串。 */
|
|
12
|
+
export function deriveSdkPaths(devecoSdkHome) {
|
|
13
|
+
const home = devecoSdkHome.trim().replace(/[\\/]+$/, '');
|
|
14
|
+
if (!home) {
|
|
15
|
+
return { DEVECO_SDK_HOME: '', DEVECO_PATH: '', OHOS_SDK_PATH: '', HMS_SDK_PATH: '' };
|
|
16
|
+
}
|
|
17
|
+
return {
|
|
18
|
+
DEVECO_SDK_HOME: home,
|
|
19
|
+
DEVECO_PATH: path.dirname(home),
|
|
20
|
+
OHOS_SDK_PATH: path.join(home, 'default', 'openharmony', 'ets'),
|
|
21
|
+
HMS_SDK_PATH: path.join(home, 'default', 'hms', 'ets'),
|
|
22
|
+
};
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* 旧配置迁移：从 OHOS_SDK_PATH（…/sdk/default/openharmony/ets）反推
|
|
26
|
+
* DEVECO_SDK_HOME（…/sdk）。HMS 同理。匹配不上返回 ''。
|
|
27
|
+
*/
|
|
28
|
+
export function sdkHomeFromLegacyPaths(env) {
|
|
29
|
+
const tryStrip = (p, suffix) => {
|
|
30
|
+
if (!p)
|
|
31
|
+
return '';
|
|
32
|
+
const norm = p.replace(/[\\/]+$/, '').split(/[\\/]/);
|
|
33
|
+
if (norm.length <= suffix.length)
|
|
34
|
+
return '';
|
|
35
|
+
const tail = norm.slice(-suffix.length).map((s) => s.toLowerCase());
|
|
36
|
+
if (tail.join('/') !== suffix.join('/'))
|
|
37
|
+
return '';
|
|
38
|
+
return norm.slice(0, -suffix.length).join(path.sep);
|
|
39
|
+
};
|
|
40
|
+
return (tryStrip(env.OHOS_SDK_PATH, ['default', 'openharmony', 'ets']) ||
|
|
41
|
+
tryStrip(env.HMS_SDK_PATH, ['default', 'hms', 'ets']));
|
|
42
|
+
}
|
|
11
43
|
export function getConfigDir() {
|
|
12
44
|
return path.join(os.homedir(), '.hometrans');
|
|
13
45
|
}
|
|
@@ -106,9 +138,12 @@ async function fileExists(p) {
|
|
|
106
138
|
*/
|
|
107
139
|
export function defaultEnv() {
|
|
108
140
|
return {
|
|
141
|
+
DEVECO_SDK_HOME: '',
|
|
142
|
+
DEVECO_PATH: '',
|
|
109
143
|
OHOS_SDK_PATH: '',
|
|
110
144
|
HMS_SDK_PATH: '',
|
|
111
145
|
TEST_API_KEY: '',
|
|
146
|
+
GLM_API_KEY: '',
|
|
112
147
|
TOOL_PATH: '',
|
|
113
148
|
};
|
|
114
149
|
}
|
|
@@ -152,6 +187,28 @@ export async function loadHomeTransConfig() {
|
|
|
152
187
|
delete anyParsed.sdkPaths;
|
|
153
188
|
delete anyParsed.params;
|
|
154
189
|
delete anyParsed.tool_path;
|
|
190
|
+
// SDK 路径统一迁移：老配置只有 OHOS_SDK_PATH/HMS_SDK_PATH 时反推
|
|
191
|
+
// DEVECO_SDK_HOME，再用它补齐缺失的派生路径（不覆盖已有非空值）。
|
|
192
|
+
let envDirty = false;
|
|
193
|
+
if (!config.env.DEVECO_SDK_HOME) {
|
|
194
|
+
const migrated = sdkHomeFromLegacyPaths(config.env);
|
|
195
|
+
if (migrated) {
|
|
196
|
+
config.env.DEVECO_SDK_HOME = migrated;
|
|
197
|
+
envDirty = true;
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
if (config.env.DEVECO_SDK_HOME) {
|
|
201
|
+
const derived = deriveSdkPaths(config.env.DEVECO_SDK_HOME);
|
|
202
|
+
for (const key of ['DEVECO_PATH', 'OHOS_SDK_PATH', 'HMS_SDK_PATH']) {
|
|
203
|
+
if (!config.env[key]) {
|
|
204
|
+
config.env[key] = derived[key];
|
|
205
|
+
envDirty = true;
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
if (envDirty) {
|
|
210
|
+
await saveHomeTransConfig(config);
|
|
211
|
+
}
|
|
155
212
|
// Append any default editors that this (older) config predates, matched by
|
|
156
213
|
// name. Existing entries are never modified, so manual edits are preserved;
|
|
157
214
|
// we only add editors the user's file is missing (e.g. CodeBuddy shipped
|
package/dist/cli/config.js
CHANGED
|
@@ -17,16 +17,15 @@ export async function configCommand() {
|
|
|
17
17
|
console.log(` Path: ${configPath}`);
|
|
18
18
|
console.log('');
|
|
19
19
|
// User parameters
|
|
20
|
-
const
|
|
21
|
-
? config.env.TEST_API_KEY.slice(0, 4) +
|
|
22
|
-
'***' +
|
|
23
|
-
config.env.TEST_API_KEY.slice(-4)
|
|
24
|
-
: '(not set)';
|
|
20
|
+
const mask = (key) => key ? key.slice(0, 4) + '***' + key.slice(-4) : '(not set)';
|
|
25
21
|
console.log(' Parameters:');
|
|
26
|
-
console.log(`
|
|
27
|
-
console.log(`
|
|
28
|
-
console.log(`
|
|
29
|
-
console.log(`
|
|
22
|
+
console.log(` DEVECO_SDK_HOME : ${config.env.DEVECO_SDK_HOME || '(not set)'}`);
|
|
23
|
+
console.log(` DEVECO_PATH : ${config.env.DEVECO_PATH || '(not set)'} (derived)`);
|
|
24
|
+
console.log(` OHOS_SDK_PATH : ${config.env.OHOS_SDK_PATH || '(not set)'} (derived)`);
|
|
25
|
+
console.log(` HMS_SDK_PATH : ${config.env.HMS_SDK_PATH || '(not set)'} (derived)`);
|
|
26
|
+
console.log(` TEST_API_KEY : ${mask(config.env.TEST_API_KEY)}`);
|
|
27
|
+
console.log(` GLM_API_KEY : ${mask(config.env.GLM_API_KEY)}`);
|
|
28
|
+
console.log(` TOOL_PATH : ${config.env.TOOL_PATH || '(not set)'}`);
|
|
30
29
|
console.log('');
|
|
31
30
|
// Full config content
|
|
32
31
|
console.log(' Full Content:');
|