@buaa_smat/hometrans 0.1.0 → 0.1.2

package/README.md

@@ -1,124 +1,141 @@
-# hometrans
-
-> Skill + agent installer for the **HomeTrans** Android-to-HarmonyOS conversion toolkit. One command (`ht init`) distributes **1 skill**, **10 subagents** (with 1 script bundle), and an **MCP server** into Claude Code, Cursor, OpenCode, and Codex.
-
----
-
-## Install
-
-Global install — exposes both `hometrans` and the short alias `ht` on `PATH`:
-
-```bash
-npm install -g hometrans
-ht init
-```
-
-One-shot via `npx` (no global install required):
-
-```bash
-npx hometrans init
-```
-
-Requires Node.js **>= 18**.
-
----
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `ht init` | Interactive setup: detect installed editors, copy skills/agents to target directories, register MCP server |
-| `ht mcp` | Start the HomeTrans MCP server (stdio mode), exposing the `extract_commit_context` tool |
-| `ht config` | Display `~/.hometrans/editors.json` path and content (read-only; edit the file directly, then re-run `ht init`) |
-| `ht uninstall` | Remove all skills, agents, and MCP entries installed by `ht init` from configured editors |
-| `ht --version` | Show installed version |
-| `ht --help` | List all commands |
-
-> `hometrans` and `ht` are fully equivalent — both point to the same CLI entry.
-
----
-
-## What `ht init` does
-
-1. **Detects** each supported editor by checking whether its standard config directory exists under `$HOME`.
-2. For every detected editor, **copies**:
-   - every skill folder under `skills/` → `<editor>/skills/<skill-name>/` (recursive — preserves subdirectory structure)
-   - every agent under `agents/` → `<editor>/agents/` (recursive — preserves `<agent>/scripts/` subtrees)
-3. **Registers the MCP server** (auto-adapts to editor config format: jsonc-object / jsonc-command-array / codex-cli / toml-section).
-4. Editors whose marker directory is missing are reported as **`skipped`** — nothing is written for them.
-5. 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.
-
-### Target directories
-
-| Editor | Marker | Skills target | Agents target |
-|--------|--------|---------------|---------------|
-| Claude Code | `~/.claude/` | `~/.claude/skills/` | `~/.claude/agents/` |
-| Cursor | `~/.cursor/` | `~/.cursor/skills/` | `~/.cursor/agents/` |
-| OpenCode | `~/.config/opencode/` | `~/.config/opencode/skills/` | `~/.config/opencode/agents/` |
-| Codex | `~/.codex/` | `~/.agents/skills/` | `~/.codex/agents/` |
-
----
-
-## What `ht mcp` does
-
-Starts a stdio-mode MCP server exposing the following tool:
-
-### `extract_commit_context`
-
-Extracts code context index from a given git commit in a HarmonyOS project (git diff + ArkTS semantic dependency analysis), for use during AI-assisted Android-to-HarmonyOS code review.
-
-**Input parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `projectPath` | string | Yes | Absolute path to HarmonyOS project root (must contain `.git`) |
-| `commitId` | string | Yes | Git commit ID (diffs against its first parent) |
-| `mode` | string | No | `"default"` builds full call graph; other values skip (default: `"default"`) |
-| `ohosSdkPath` | string | No | OpenHarmony SDK ETS path; falls back to env var `OHOS_SDK_PATH` |
-| `hmsSdkPath` | string | No | HMS SDK ETS path; falls back to env var `HMS_SDK_PATH` |
-
-**Output:** `{path, kind, ranges?, resourceNames?}[]`
-- `source` files: 1-based `[start, end]` line-range arrays
-- `resource` files: list of referenced resource names
-
----
-
-## Skills
-
-| Skill | Trigger phrases | Description |
-|-------|-----------------|-------------|
-| `convert-pipeline` | "full Android-to-HarmonyOS pipeline", "run the conversion pipeline end-to-end", "convert_pipeline" | Runs all conversion agents in sequence with progress tracking, duration stats, and defect recording. 9 stages: Logic Context → Logic Coding → Build → Code Review → Review Fix → Rebuild → Self-Test → Self-Test Fix → Rebuild |
-
-**Arguments:**
-1. `android-project-path` (required): path to the Android source project
-2. `harmonyos-project-path` (required): path to the target HarmonyOS project
-3. `assets-output-path` (required): directory for output/report files
-4. `max-rounds-review` (optional, default `2`): max Code Review → Fix loop rounds
-5. `max-rounds-test` (optional, default `2`): max Self-Test → Fix loop rounds
-6. `variant` (optional, default `enhanced`): `enhanced` | `baseline` — selects the Stage 1/1a agent family
-
----
-
-## Agents
-
-| Agent | Description |
-|-------|-------------|
-| `logic-context-builder` | Constrains HarmonyOS ArkTS app changes into an executable decision contract |
-| `logic-coding` | Executes HarmonyOS ArkTS code implementation from the decision contract (ships with `scripts/platform_context_query.py`) |
-| `build-fixer` | Automatically builds a HarmonyOS project, parses compile errors, fixes them, and retries in a loop until the build succeeds |
-| `code-reviewer` | Reviews HarmonyOS code against user scenarios to validate functional coverage |
-| `code-review-fix` | One-pass review-fix-build cycle — reviews code, verifies and fixes confirmed issues, rebuilds the project |
-| `review-fixer` | Fixes issues from code review reports — verifies each issue before fixing, references Android source, uses cautious per-scenario fix strategies |
-| `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 |
-| `self-test-setup` | Prepares everything needed for AutoTest — parses `test_case.md` into `testcases.json` plus app metadata |
-| `self-tester` | Performs functional verification of HAP packages on real HarmonyOS devices using AutoTest Mode |
-| `self-test-fixer` | Fixes issues identified by self-testing — reads the self-test report, white-box verifies failures, plans and executes fixes in order |
-
----
-
-MIT
-
-<p align="center">
-<a href="https://gitcode.com/SMAT/HomeTrans">Official Repository</a> •
-<a href="https://gitcode.com/SMAT/HomeTrans/blob/main/LICENSE">MIT License</a>
-</p>
+# hometrans
+
+> Skill + agent installer for the **HomeTrans** Android-to-HarmonyOS conversion toolkit. One command (`ht init`) distributes **7 skills**, **9 subagents** (with a script bundle + on-device test tooling), and an **MCP server** into Claude Code, Cursor, OpenCode, and Codex.
+
+---
+
+## Install
+
+Global install — exposes both `hometrans` and the short alias `ht` on `PATH`:
+
+```bash
+npm install -g @buaa_smat/hometrans
+ht init
+```
+
+One-shot via `npx` (no global install required):
+
+```bash
+npx hometrans init
+```
+
+Requires Node.js **>= 18**.
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `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 |
+| `ht mcp` | Start the HomeTrans MCP server (stdio mode), exposing the `extract_commit_context` tool |
+| `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`) |
+| `ht uninstall` | Remove all skills, agents, and MCP entries installed by `ht init` from configured editors |
+| `ht --version` | Show installed version |
+| `ht --help` | List all commands |
+
+> `hometrans` and `ht` are fully equivalent — both point to the same CLI entry.
+
+---
+
+## What `ht init` does
+
+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.
+2. **Prompts for user parameters** and stores them in `~/.hometrans/config.json` (press Enter to keep the current value or leave empty):
+   - `OHOS_SDK_PATH` — OpenHarmony SDK ETS path
+   - `HMS_SDK_PATH` — HMS SDK ETS path
+   - `TEST_API_KEY` — API key written into the autotest `config.yaml`
+3. **Seeds/refreshes the autotest config**: if `agents/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`.
+4. For every selected editor, **copies**:
+   - every skill folder under `skills/` (those containing a `SKILL.md`) → `<editor>/skills/<skill-name>/` (recursive — preserves subdirectory structure)
+   - every agent under `agents/` → `<editor>/agents/` (recursive — preserves `<agent>/scripts/` and `test-tools/` subtrees)
+5. **Registers the MCP server** (auto-adapts to editor config format: jsonc-object / jsonc-command-array / codex-cli / toml-section).
+6. Editors whose marker directory is missing are reported as **`skipped`** — nothing is written for them.
+7. 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.
+
+### Target directories
+
+| Editor | Marker | Skills target | Agents target |
+|--------|--------|---------------|---------------|
+| Claude Code | `~/.claude/` | `~/.claude/skills/` | `~/.claude/agents/` |
+| Cursor | `~/.cursor/` | `~/.cursor/skills/` | `~/.cursor/agents/` |
+| OpenCode | `~/.config/opencode/` | `~/.config/opencode/skills/` | `~/.config/opencode/agents/` |
+| Codex | `~/.codex/` | `~/.agents/skills/` | `~/.codex/agents/` |
+
+---
+
+## What `ht mcp` does
+
+Starts a stdio-mode MCP server exposing the following tool:
+
+### `extract_commit_context`
+
+Extracts code context index from a given git commit in a HarmonyOS project (git diff + ArkTS semantic dependency analysis), for use during AI-assisted Android-to-HarmonyOS code review.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `projectPath` | string | Yes | Absolute path to HarmonyOS project root (must contain `.git`) |
+| `commitId` | string | Yes | Git commit ID (diffs against its first parent) |
+| `mode` | string | No | `"default"` builds full call graph; other values skip (default: `"default"`) |
+| `ohosSdkPath` | string | No | OpenHarmony SDK ETS path; falls back to env var `OHOS_SDK_PATH` |
+| `hmsSdkPath` | string | No | HMS SDK ETS path; falls back to env var `HMS_SDK_PATH` |
+
+**Output:** `{path, kind, ranges?, resourceNames?}[]`
+- `source` files: 1-based `[start, end]` line-range arrays
+- `resource` files: list of referenced resource names
+
+---
+
+## Skills
+
+| Skill | Trigger phrases | Description |
+|-------|-----------------|-------------|
+| `convert-pipeline` | "full Android-to-HarmonyOS pipeline", "run the conversion pipeline end-to-end", "convert_pipeline" | Runs all conversion agents in sequence with progress tracking, duration stats, and defect recording. 9 stages: Logic Context → Logic Coding → Build → Code Review → Review Fix → Rebuild → Self-Test → Self-Test Fix → Rebuild |
+| `code-dev-review-fix` | "开发并检视", "代码开发检视修复", "实现这个需求并验证", "develop and review", "review and fix this commit" | Flexibly orchestrates HarmonyOS development/build/scenario-review/fix agents from a natural-language request — composes only the needed agents (logic-context-builder → logic-coding → build-fixer → code-reviewer / code-review-fix) instead of running a fixed pipeline |
+| `spec-generator-skill` | "spec generation", "generate spec", "requirement to spec", "atomic scenarios", "scenario decomposition", "req to spec" | Generates atomic-scenario requirement specs from raw `.txt` requirement batches. Reads REQ blocks, explores the Android code graph via GitNexus, writes per-REQ trace files, then synthesizes specs from the trace |
+| `hmos-resources-convert` | "Android resources to HarmonyOS", "migrate Android res", "convert drawables/strings/colors" | Converts Android project resources (strings, colors, dimensions, images, drawables, icons) into HarmonyOS resources, including qualifier directories and XML→JSON format conversion |
+| `hmos-ui-align` | "UI对齐", "页面对齐", "和安卓对齐", "鸿蒙页面修复", "align HarmonyOS with Android" | Automated HarmonyOS-Android UI alignment: navigates to target pages on both devices, captures view trees + screenshots, then aligns HarmonyOS code to match Android |
+| `hmos-ui-align-batch` | "把安卓页面迁移到鸿蒙", "Android UI 转鸿蒙", "批量转 ArkTS" | Batch-converts multiple Android Activity UI snapshots (`page_NNNN_ActivityName`) to HarmonyOS ArkUI (ArkTS) pages |
+| `self-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 |
+
+### `convert-pipeline` Arguments
+
+1. `android-project-path` (required): path to the Android source project
+2. `harmonyos-project-path` (required): path to the target HarmonyOS project
+3. `assets-output-path` (required): directory for output/report files
+4. `max-rounds-review` (optional, default `2`): max Code Review → Fix loop rounds
+5. `max-rounds-test` (optional, default `2`): max Self-Test → Fix loop rounds
+6. `variant` (optional, default `enhanced`): `enhanced` | `baseline` — selects the Stage 1/1a agent family
+
+### `spec-generator-skill` Arguments
+
+1. `requirement-description-file` (required): absolute path to a single `.txt` file containing one or more REQ blocks separated by blank lines
+2. `android-project-path` (required): absolute path to the Android project root (must be inside a Git repo)
+3. `spec-output-dir` (required): absolute path to the directory where spec files will be written
+
+---
+
+## Agents
+
+| Agent | Description |
+|-------|-------------|
+| `logic-context-builder` | Constrains HarmonyOS ArkTS app changes into an executable decision contract |
+| `logic-coding` | Executes HarmonyOS ArkTS code implementation from the decision contract (ships with `scripts/platform_context_query.py`) |
+| `build-fixer` | Automatically builds a HarmonyOS project, parses compile errors, fixes them, and retries in a loop until the build succeeds |
+| `code-reviewer` | Reviews HarmonyOS code against user scenarios to validate functional coverage |
+| `code-review-fix` | One-pass review-fix-build cycle — reviews code, verifies and fixes confirmed issues, rebuilds the project |
+| `review-fixer` | Fixes issues from code review reports — verifies each issue before fixing, references Android source, uses cautious per-scenario fix strategies |
+| `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 |
+| `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) |
+| `self-test-fixer` | Fixes issues identified by self-testing — reads the self-test report, white-box verifies failures, plans and executes fixes in order |
+
+---
+
+MIT
+
+<p align="center">
+<a href="https://gitcode.com/SMAT/HomeTrans">Official Repository</a> •
+<a href="https://gitcode.com/SMAT/HomeTrans/blob/main/LICENSE">MIT License</a>
+</p>

package/agents/build-fixer.md

@@ -1,4 +1,5 @@
 ---
+name: build-fixer
 description: Automatically builds a HarmonyOS project, parses compile errors, fixes them, and retries in a loop until build succeeds
 color: orange
 ---

package/agents/code-review-fix.md

@@ -1,4 +1,5 @@
 ---
+name: code-review-fix
 description: One-pass review-fix-build cycle — reviews HarmonyOS code against scenarios, verifies and fixes confirmed issues, rebuilds the project
 color: red
 ---

package/agents/code-reviewer.md

@@ -1,4 +1,5 @@
 ---
+name: code-reviewer
 description: Reviews HarmonyOS code against user scenarios to validate functional coverage
 color: red
 ---

package/agents/logic-coding.md

@@ -1,4 +1,5 @@
 ---
+name: logic-coding
 description: "Execute the HarmonyOS ArkTS app contract without reopening design choices."
 color: blue
 min-model: sonnet

package/agents/logic-context-builder.md

@@ -1,4 +1,5 @@
 ---
+name: logic-context-builder
 description: "Constrain HarmonyOS ArkTS app changes into an executable decision contract."
 color: blue
 min-model: sonnet

package/agents/review-fixer.md

@@ -1,4 +1,5 @@
 ---
+name: review-fixer
 description: Fixes issues from code review reports — verifies each issue before fixing, references Android source, and uses cautious per-scenario fix strategies
 color: red
 ---

package/agents/self-test-fixer.md

@@ -1,4 +1,5 @@
 ---
+name: self-test-fixer
 description: Fixes issues identified by self-testing — reads self-test report, white-box verifies failures in HarmonyOS code, plans and executes fixes in order, produces detailed report
 color: cyan
 ---