@buaa_smat/hometrans 0.1.5 → 0.1.7

package/skills/hmos-fix-build-errors/references/arkts-strict-patterns.md

@@ -0,0 +1,219 @@
+# ArkTS 严格模式确定性修复 Pattern
+# 适用于: ArkTS 严格模式编译错误
+# 触发场景: 编译报错 arkts-no-xxx 系列
+# 经验来源: EinkBro 迁移 (2026-03-26)
+
+---
+
+## Pattern 1: throw 语句
+
+### 错误写法
+```typescript
+throw err;                    // ERROR: arkts-limited-throw
+throw 'error string';         // ERROR: arkts-limited-throw
+throw unknownVariable;        // ERROR: arkts-limited-throw
+```
+
+### 正确写法
+```typescript
+throw new Error(String(error));
+```
+
+### 不需要修改的情况
+```typescript
+throw new Error('specific message');  // OK - 已经是 Error 实例
+```
+
+---
+
+## Pattern 2: 对象字面量作为参数 (arkts-no-untyped-obj-literals)
+
+### 错误写法
+```typescript
+// ERROR: Object literal must correspond to some explicitly declared class or interface
+const response = await this.sendRequest(url, { contents });
+```
+
+### 正确写法 — 先声明变量
+```typescript
+interface GeminiRequestBody {
+  contents: GeminiContent[];
+}
+
+const requestBody: GeminiRequestBody = { contents };
+const response = await this.sendRequest(url, requestBody);
+```
+
+### 内联参数场景
+```typescript
+// 方法参数也是对象字面量，同样需要处理
+httpRequest.request(url, {
+  method: http.RequestMethod.POST,
+  header: { 'Content-Type': 'application/json' },
+  extraData: JSON.stringify(body),
+  connectTimeout: 30000,
+  readTimeout: 30000
+});
+// ^ 这种场景 SDK 方法签名本身接受 object 类型，通常 OK
+// 但自定义方法调用时必须用已声明接口的变量
+```
+
+---
+
+## Pattern 3: Margin vertical 简写不支持
+
+### 错误写法
+```typescript
+.margin({ vertical: 8 });     // ERROR: 'vertical' does not exist in type
+```
+
+### 正确写法
+```typescript
+.margin({ top: 8, bottom: 8 });
+```
+
+### 常见场景
+| 错误 | 正确 |
+|------|------|
+| `.margin({ vertical: 8 })` | `.margin({ top: 8, bottom: 8 })` |
+| `.margin({ horizontal: 16 })` | `.margin({ left: 16, right: 16 })` |
+
+---
+
+## Pattern 4: List 内不能直接放 Divider
+
+### 错误写法
+```typescript
+List() {
+  ForEach(items, (item) => {
+    ListItem() { /* ... */ }
+  })
+  Divider()  // ERROR: List children must be ListItem only
+}
+```
+
+### 正确写法 — 用 ListItem + border
+```typescript
+List() {
+  ForEach(items, (item) => {
+    ListItem() {
+      Column() {
+        Text(item.name)
+      }
+      .width('100%')
+      .padding(12)
+      .border({ width: { bottom: 1 }, color: '#E0E0E0' })  // 替代 Divider 分隔线
+    }
+  })
+}
+```
+
+### 另一种方案 — border 直接在 ListItem 上
+```typescript
+ListItem() {
+  // content
+}
+.border({ width: { bottom: 1 }, color: '#E0E0E0' })
+```
+
+---
+
+## Pattern 5: 数组字面量类型推断 (arkts-no-noninferrable-arr-literals)
+
+### 错误写法
+```typescript
+const arr = [1, 2, 3].map(x => ({ val: x }));
+// ERROR: Array literals must contain elements of only inferrable types
+```
+
+### 正确写法 — 显式类型
+```typescript
+interface Item { val: number; }
+const arr: Item[] = [1, 2, 3].map((x): Item => ({ val: x }));
+```
+
+---
+
+## Pattern 6: TextDecoder 不存在
+
+### 错误写法
+```typescript
+const decoder = new TextDecoder();  // ERROR: Cannot find name 'TextDecoder'
+const str = decoder.decode(data);
+```
+
+### 正确写法
+```typescript
+const bytes = new Uint8Array(data);
+let chunk = '';
+for (let i = 0; i < bytes.length; i++) {
+  chunk += String.fromCharCode(bytes[i]);
+}
+```
+
+---
+
+## Pattern 7: HTTP 组件事件名
+
+| 错误事件 | 正确事件 | 说明 |
+|---------|---------|------|
+| `request.on('requestEnd', ...)` | `request.on('dataEnd', ...)` | 请求结束事件 |
+| `request.on('error', ...)` | 改用 Promise 的 catch | HTTP 组件 error 事件签名不标准 |
+
+---
+
+## Pattern 8: GeminiService 等自定义类缺少成员
+
+### 错误场景
+```typescript
+class GeminiService {
+  private async sendRequest(url: string, body: object): Promise<Object> {
+    httpRequest.request(url, { extraData: JSON.stringify(body),
+      connectTimeout: this.timeout,  // ERROR: Property 'timeout' does not exist
+      readTimeout: this.timeout
+    });
+  }
+  // timeout 属性忘记声明
+}
+```
+
+### 正确 — 确保所有成员都在类体内声明
+```typescript
+class GeminiService {
+  private timeout: number = 30000;  // 在类体内声明
+  private async sendRequest(...) { ... }
+}
+```
+
+---
+
+## Pattern 9: Button 不支持 emoji
+
+### 错误写法
+```typescript
+Button('X')  // 有时 emoji 渲染异常
+Button('🗑')
+```
+
+### 正确写法
+```typescript
+Button('Del')   // 纯文本
+Button('Copy')
+Button('Back')
+```
+
+---
+
+## 快速检查清单
+
+遇到 ArkTS 编译错误时，按序检查：
+
+1. throw → `throw new Error(String(x))`
+2. 对象字面量作为参数 → 先赋值给显式类型变量
+3. any / unknown → `Object` + `as Function` / `as SomeType`
+4. // @ts-ignore → 禁止，必须用类型操作替代
+5. ValuesBucket → 普通对象字面量 `{}`
+6. margin { vertical } → `{ top, bottom }`
+7. List 内 Divider → ListItem + border
+8. TextDecoder → Uint8Array 遍历
+9. `new SomeType()` 报错 → 检查是否是 type alias 而非 class

package/skills/hmos-fix-build-errors/references/known-patterns.md

@@ -0,0 +1,157 @@
+# Known Compile Error Patterns
+
+> **This file is auto-maintained by `a2h-retrospect`.**
+> Manual edits are allowed but may be overwritten when retrospect detects updated patterns.
+> Last updated: 2026-03-27
+
+---
+
+## Pattern Index
+
+| # | Error Code / Type | Frequency | Short Description |
+|---|-------------------|-----------|-------------------|
+| 1 | arkts-identifiers-as-prop-names | 85 | ValuesBucket computed property name |
+| 2 | type mismatch (EventData) | 16 | EventData double type cast |
+| 3 | arkts-no-untyped-obj-literals | 9 | Untyped object literal |
+| 4 | type mismatch (promptAction) | 8 | promptAction button color type |
+| 5 | type error (@Prop) | 3 | @Prop naming conflict |
+
+---
+
+## 1. ValuesBucket Computed Property Name
+
+- **Date**: 2026-03-27
+- **Error code**: `arkts-identifiers-as-prop-names`
+- **Frequency**: 85 occurrences
+- **Source**: AntennaPod V1 migration (a2h-retrospect-report-2026-03-27)
+
+**Error code**:
+```typescript
+const bucket: ValuesBucket = {
+  [ColumnName.TITLE]: title,   // ERROR: computed property name not allowed
+  [ColumnName.URL]: url,
+};
+```
+
+**Correct code**:
+```typescript
+const bucket: ValuesBucket = {};
+bucket[ColumnName.TITLE] = title;
+bucket[ColumnName.URL] = url;
+```
+
+**Rule**: ArkTS forbids computed property names (`[expr]: value`) in object literals. Build the object first, then assign properties via bracket notation.
+
+---
+
+## 2. EventData Double Type Cast
+
+- **Date**: 2026-03-27
+- **Error code**: type mismatch
+- **Frequency**: 16 occurrences
+- **Source**: AntennaPod V1 migration (a2h-retrospect-report-2026-03-27)
+
+**Error code**:
+```typescript
+emitter.on({ eventId: 1 }, (data: emitter.EventData) => {
+  const value = data.data?.['key'] as string;  // ERROR: data.data is optional Record, direct cast fails
+});
+```
+
+**Correct code**:
+```typescript
+emitter.on({ eventId: 1 }, (data: emitter.EventData) => {
+  const raw = data.data as Record<string, Object>;
+  const value = raw['key'] as string;
+});
+```
+
+**Rule**: `EventData.data` is typed `Record<string, Object> | undefined`. Access requires two steps: (1) cast to `Record<string, Object>`, (2) cast the extracted value to the target type.
+
+---
+
+## 3. Untyped Object Literal
+
+- **Date**: 2026-03-27
+- **Error code**: `arkts-no-untyped-obj-literals`
+- **Frequency**: 9 occurrences
+- **Source**: AntennaPod V1 migration (a2h-retrospect-report-2026-03-27)
+
+**Error code**:
+```typescript
+const options = {
+  title: 'Hello',
+  message: 'World',
+};  // ERROR: object literal without explicit type annotation
+```
+
+**Correct code**:
+```typescript
+interface DialogOptions {
+  title: string;
+  message: string;
+}
+const options: DialogOptions = {
+  title: 'Hello',
+  message: 'World',
+};
+```
+
+**Rule**: ArkTS requires all object literals to have an explicit type. Define an `interface` or `class` and annotate the variable.
+
+---
+
+## 4. promptAction Button Color Type
+
+- **Date**: 2026-03-27
+- **Error code**: type mismatch
+- **Frequency**: 8 occurrences
+- **Source**: AntennaPod V1 migration (a2h-retrospect-report-2026-03-27)
+
+**Error code**:
+```typescript
+promptAction.showDialog({
+  buttons: [
+    { text: 'OK', color: '#ff0000' }   // ERROR: color expects ResourceColor, not string
+  ]
+});
+```
+
+**Correct code**:
+```typescript
+promptAction.showDialog({
+  buttons: [
+    { text: 'OK', color: Color.Red }
+  ]
+});
+// Or use $r('app.color.xxx') for resource reference
+```
+
+**Rule**: `promptAction.showDialog` button `color` property expects `ResourceColor` type (Color enum or `$r()` resource reference), not a raw hex string.
+
+---
+
+## 5. @Prop Naming Conflict
+
+- **Date**: 2026-03-27
+- **Error code**: type error
+- **Frequency**: 3 occurrences
+- **Source**: AntennaPod V1 migration (a2h-retrospect-report-2026-03-27)
+
+**Error code**:
+```typescript
+@Component
+struct MyComponent {
+  @Prop title: string = '';   // ERROR: 'title' conflicts with built-in component property
+}
+```
+
+**Correct code**:
+```typescript
+@Component
+struct MyComponent {
+  @Prop itemTitle: string = '';   // Renamed to avoid conflict
+}
+```
+
+**Rule**: Certain property names (`title`, `content`, `action`, etc.) conflict with built-in component attributes. Prefix with a domain-specific qualifier (e.g., `itemTitle`, `feedTitle`).

package/skills/hmos-fix-build-errors/references/rdb-entity-pattern.md

@@ -0,0 +1,131 @@
+# RDB Entity 确定性修复 Pattern
+# 适用于: ArkTS 严格模式 + @kit.ArkData relationalStore
+# 触发场景: 迁移 Android RDB 实体类到 ArkTS 时
+# 经验来源: EinkBro 迁移 (2026-03-26)
+
+---
+
+## Pattern 1: ValuesBucket 正确用法
+
+### 错误写法 (编译报错)
+```typescript
+import { relationalStore, ValuesBucket } from '@kit.ArkData';
+
+toValuesBucket(): ValuesBucket {
+  const bucket = new ValuesBucket();  // ERROR: 'ValuesBucket' only refers to a type
+  bucket.put('key', value);           // ERROR: ValuesBucket has no .put() method
+  return bucket;
+}
+```
+
+### 正确写法
+```typescript
+type EntityValuesBucket = Record<string, number | string | boolean | Uint8Array | null>;
+
+toValuesBucket(): EntityValuesBucket {
+  const bucket: EntityValuesBucket = {};
+  bucket['key'] = value;
+  return bucket;
+}
+```
+
+**原因**: `ValuesBucket` 在 SDK 中是 type alias (`Record<string, ValueType>`)，不是可实例化的类。
+
+---
+
+## Pattern 2: fromResultSet 参数类型 (禁止 any)
+
+### 错误写法 (编译报错)
+```typescript
+// ArkTS 严格模式禁止 any
+static fromResultSet(resultSet: any): EntityName {  // ERROR: arkts-no-any-unknown
+```
+
+### 正确写法
+```typescript
+static fromResultSet(resultSet: Object): EntityName {
+  const rs = resultSet as Record<string, Object>;
+  const colIndex = (name: string): number =>
+    (rs['getColumnIndex'] as Function)(name) as number;
+
+  entity.field = (rs['getLong'] as Function)(colIndex('field_name')) as number;
+  entity.name  = (rs['getString'] as Function)(colIndex('name')) as string;
+  return entity;
+}
+```
+
+**替代方案** (更简洁但运行时开销略高):
+```typescript
+// 使用类型断言避免 any，运行时通过 Record<string, Function> 调用
+static fromResultSet(resultSet: Object): EntityName {
+  const getCol = (name: string): number =>
+    (resultSet as Record<string, Function>)['getColumnIndex'](name) as number;
+  const getLong = (name: string): number =>
+    (resultSet as Record<string, Function>)['getLong'](getCol(name)) as number;
+  const getStr = (name: string): string =>
+    (resultSet as Record<string, Function>)['getString'](getCol(name)) as string;
+
+  const entity = new EntityName();
+  entity.id   = getLong('id');
+  entity.name = getStr('name');
+  return entity;
+}
+```
+
+---
+
+## Pattern 3: // @ts-ignore 不可用
+
+### 错误尝试
+```typescript
+// @ts-ignore  // ERROR: Switching off type checks with in-place comments is not allowed
+static fromResultSet(resultSet: any): EntityName {
+```
+
+### 必须用 Pattern 2 替代
+
+---
+
+## Pattern 4: toValuesBucket() 返回类型注解
+
+```typescript
+type EntityValuesBucket = Record<string, number | string | boolean | Uint8Array | null>;
+
+toValuesBucket(): EntityValuesBucket {
+  const bucket: EntityValuesBucket = {} as EntityValuesBucket;
+  // ...
+  return bucket;
+}
+```
+
+---
+
+## 完整 Entity 模板
+
+```typescript
+type EntityValuesBucket = Record<string, number | string | boolean | Uint8Array | null>;
+
+export class MyEntity {
+  id: number = 0;
+  name: string = '';
+  value: number = 0;
+
+  static fromResultSet(resultSet: Object): MyEntity {
+    const rs = resultSet as Record<string, Object>;
+    const col = (n: string): number => (rs['getColumnIndex'] as Function)(n) as number;
+    const entity = new MyEntity();
+    entity.id   = (rs['getLong']   as Function)(col('id'))   as number;
+    entity.name = (rs['getString'] as Function)(col('name')) as string;
+    entity.value = (rs['getLong']  as Function)(col('value')) as number;
+    return entity;
+  }
+
+  toValuesBucket(): EntityValuesBucket {
+    const bucket: EntityValuesBucket = {} as EntityValuesBucket;
+    if (this.id > 0) { bucket['id'] = this.id; }
+    bucket['name'] = this.name;
+    bucket['value'] = this.value;
+    return bucket;
+  }
+}
+```

package/skills/{hmos-ui-align → hmos-incremental-ui-align}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: hmos-ui-align
+name: hmos-incremental-ui-align
 description: "Automated HarmonyOS-Android UI alignment pipeline. Takes a natural language task description, automatically navigates to the target pages on both Android and HarmonyOS devices, captures view trees and screenshots, then aligns HarmonyOS code to match Android. Use this skill whenever the user wants to align a HarmonyOS page with its Android counterpart, fix visual differences between Android and HarmonyOS, add missing HarmonyOS pages based on Android, or describes a page path like '首页-设置-关于' that needs UI alignment. Also trigger on phrases like 'UI对齐', '页面对齐', '和安卓对齐', '鸿蒙页面修复','UI增量开发'，'align HarmonyOS with Android', or any request involving comparing and fixing HarmonyOS UI to match Android."
 ---
 
@@ -17,21 +17,25 @@ You are writing ArkTS codes.
 - 不要做和用户需求无关的其他修改
 - 
 ## Step 0: Load Config
-Read `config.json` from this skill's directory. The config provides all fixed paths so the user only describes what needs to be aligned.
-Key config fields:
-- `android.app_name`, `android.package` — Android app info for navigation
-- `android.project_dir` — Android source code root
-- `harmony.app_name`, `harmony.package` — HarmonyOS app info for navigation
-- `harmony.project_dir` — HarmonyOS project root
-- `hmos_sdk_dir` — HarmonyOS SDK path for API reference
-- `glm_api_key` — Zhipu GLM API key for phone-agent
-- `capture_output_dir` — base directory for captured page data
-- `navigation_tool` = `scripts/app_feature_verify.py`                                                                                   
-- `capture_tool` = `scripts/page_capture.py`
+The user MUST provide a `config-path` when invoking this skill (e.g., `config-path: D:\path\to\config.json`). The config file must exist before running — verify with a Read, and if it's missing or unreadable, ask the user for a valid path. Refer to `config-example.json` in this skill's directory for the expected schema.
+
+Config fields:
+
+| Field | Description |
+|---|---|
+| `android.app_name` | Android app name for navigation |
+| `android.package` | Android app package name |
+| `android.project_dir` | Android source code root path |
+| `harmony.app_name` | HarmonyOS app name for navigation |
+| `harmony.package` | HarmonyOS app package name |
+| `harmony.project_dir` | HarmonyOS project root path |
+| `hmos_sdk_dir` | HarmonyOS SDK path (ETS API reference) |
+| `glm_api_key` | Zhipu GLM API key for phone-agent |
+| `capture_output_dir` | Base directory for captured page data |
 
 ## Step 1: Capture All Related Pages on Android & HarmonyOS Devices
 
-Read `scripts/navigation-capure.md` to learn the usage of `navigation_tool` and `capture_tool`.
+Read `scripts/navigation-capure.md` to learn the usage of `scripts/app_feature_verify.py` (navigation) and `scripts/page_capture.py` (capture).
 
 ### Step 1.1: Parse User Request and Build Capture Plan
 Analyze the user's description and build a list of **base pages** to capture.
@@ -46,8 +50,8 @@ Create the timestamped output directory and per-page sub-directories following t
 
 ### Step 1.2: Capture Base Pages
 For each base page in the plan, on **both** Android and HarmonyOS devices:
-1. Use `navigation_tool` to navigate to the page.
-2. On success, use `capture_tool` to capture the view tree and screenshot.
+1. Use `scripts/app_feature_verify.py` to navigate to the page.
+2. On success, use `scripts/page_capture.py` to capture the view tree and screenshot.
 3. For HarmonyOS pages that don't exist yet, navigation will fail — leave the directory empty (expected).
 
 ### Step 1.3: Discover and Capture Interactive States
@@ -59,7 +63,7 @@ After capturing each base page, scan its view tree for **interactive elements th
 
 **For each interactive element found:**
 1. Create a separate capture directory: `{platform}_page_{i}_{base_name}_{state_type}_{state_name}` (e.g., `android_page_1_detail_tab_city`, `android_page_1_detail_popup_filter_identity`).
-2. Navigate to the base page (reuse the same nav path), then append the click action to trigger the state change. Capture with `capture_tool`.
+2. Navigate to the base page (reuse the same nav path), then append the click action to trigger the state change. Capture with `scripts/page_capture.py`.
 3. Repeat for **both** Android and HarmonyOS devices.
 4. Each captured state is treated as a separate page pair in Step 2 and Step 3.
 

package/skills/{hmos-ui-align → hmos-incremental-ui-align}/readme.md

@@ -45,7 +45,7 @@ HarmonyOS-Android UI 自动对齐流水线。
 
 ## 配置 `config.json`
 
-首次使用前必须改 `Agents/hmos-ui-align/config.json`。字段说明：
+首次使用前，自行准备一份 `config.json`（放任何位置都可以），调用 skill 时把它的**绝对路径**作为参数传给 skill。可复制同目录下的 `config-example.json` 作为模板。字段说明：
 
 | 字段 | 说明 | 示例 |
 |---|---|---|
@@ -65,10 +65,10 @@ HarmonyOS-Android UI 自动对齐流水线。
 
 ## 使用方式
 
-在 Claude Code 里直接调用 skill：
+在 Claude Code 里直接调用 skill，**必须把准备好的 `config.json` 的绝对路径附在需求里**：
 
 ```
-/hmos-ui-align <自然语言需求，描述要对齐的页面+点击路径>
+/hmos-ui-align config: <绝对路径/config.json>  <自然语言需求，描述要对齐的页面+点击路径>
 ```
 
 ### 写需求的三个要点
@@ -112,7 +112,7 @@ HarmonyOS-Android UI 自动对齐流水线。
 skill 会严格按 `SKILL.md` 里的 5 步流水线跑：
 
 ### Step 0 · 加载 config
-读 `config.json`，解析出所有路径和 API Key。
+读用户指定路径下的 `config.json`，解析出所有路径和 API Key。
 
 ### Step 1 · 双端页面采集
 1.1 解析你的需求，拆成一组「基础页」，每个基础页有 `android_nav_path` 和 `hmos_nav_path`
@@ -161,8 +161,7 @@ skill 会严格按 `SKILL.md` 里的 5 步流水线跑：
 Agents/hmos-ui-align/
 ├── SKILL.md                    # 流水线定义（主 agent 执行逻辑）
 ├── readme.md                   # 本文档
-├── config.json                 # 用户配置
-├── config-example.json         # 配置样例
+├── config-example.json         # 配置样例（实际使用的 config.json 由用户自备并显式传路径）
 ├── page_align.md               # Step 3 的转换规则
 ├── diff_analysis.md            # 内部说明
 ├── scripts/

package/skills/{hmos-ui-align → hmos-incremental-ui-align}/references/android-to-harmonyOS-ui-atomic-component-mapping-reference.md

@@ -2524,11 +2524,9 @@ Column() {
 
 ## 参考链接
 
-1. **Android UI 组件全量清单**: `/docs/android-ui-components-full-list.md`
-2. **HarmonyOS ArkUI 组件全量清单**: `/docs/harmonyos-arkui-components-full-list.md`
-3. **HarmonyOS 开发者文档**: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/
-4. **Android UI 组件总览**: https://developer.android.com/develop/ui
-5. **Material Design 3 规范**: https://m3.material.io/components
+1. **HarmonyOS 开发者文档**: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/
+2. **Android UI 组件总览**: https://developer.android.com/develop/ui
+3. **Material Design 3 规范**: https://m3.material.io/components
 
 ---
 

package/skills/{self-test → hmos-integration-test}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: self-test
+name: hmos-integration-test
 description: "Run on-device self-test for a HarmonyOS app. Parse test_case.md, install the HAP, execute AutoTest, and produce a verification report. Optionally enters a test-and-fix loop. Triggers on phrases like '跑自测', '运行自测', '执行自测', '自动测试', '设备测试', '跑用例', '跑自动化测试', 'self test', 'run autotest'."
 allowed-tools:
   - Read

package/skills/{spec-generator-skill → hmos-spec-generate}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: spec-generator-skill
+name: hmos-spec-generate
 description: "Generate atomic-scenario requirement specs (markdown) from raw .txt requirement batches for Android-to-HarmonyOS migration. Reads a single .txt holding multiple REQ blocks (blank-line separated), explores the Android code graph via GitNexus, writes per-REQ trace files first then synthesizes specs from the trace. Triggers: spec generation, generate spec, requirement to spec, atomic scenarios, scenario decomposition, decompose scenarios, req to spec, code-trace-first, batch req txt."
 license: MIT
 allowed-tools: