Taiyi ArkMigrate

作品描述

Taiyi ArkMigrate 是应用级鸿蒙迁移 Agent，目标是将包含多页面导航、状态恢复、数据库、网络、媒体、权限、后台任务、多模块协作及跨设备语义的 Android/iOS 应用，自动迁移为由目标 Profile 约束的 OpenHarmony/HarmonyOS ArkTS 工程。作品基于 Pi SDK 与 Pi Package 构建，固定 Pi 0.80.6 及指定上游提交，不修改 Pi 内核，采用“确定性控制平面 + 隔离式 Agent 执行平面”的双层架构：调度器通过 doctor → ingest → analyze → scenario → semantic-plan → plan → scaffold → generate → validate → repair → package/report 可恢复 DAG 管理全局状态、任务依赖、文件所有权、Checkpoint、增量失效和事件审计，Pi AgentSession 只负责受约束的局部生成、验证与修复。系统使用 XML、JSON5、plist、Xcode 工程结构化解析器和 Tree-sitter WASM，构建带文件、行号、置信度及内容哈希的 AppSemanticGraph，进一步抽取 Given/When/Then 场景、关键调用链、状态流转和可验证副作用，并形成 ScenarioSet、OSObligationSet 与 MigrationPlan 等结构化中间产物。针对鸿蒙与 Android/iOS 之间的操作系统语义鸿沟，系统依据目标设备、API 版本、APL、ACL 和能力白名单，对 UIAbility/ExtensionAbility 生命周期、Service/WorkManager/BGTask 后台任务、module.json5 权限声明与运行时申请、拒绝和撤销处理，以及分布式能力的 adopt、not_applicable、blocked 决策进行显式规划，禁止机械类名替换和无语义跨设备 API 滥用。每个迁移任务使用 P0-P3 Context Capsule 组织目标 Profile、关键调用链、直接依赖和 SDK 检索内容，超预算时优先裁剪低优先级上下文；Pi Worker 仅开放证据读取、语义图查询、目标 API 检索、契约读取、artifact/patch 提交和命名校验器，禁用通用 Shell、写文件和编辑工具，所有补丁经过路径约束、旧文件 SHA-256 校验和串行 mutation queue 提交。生成阶段按工程骨架、数据模型、平台适配器、仓储、状态、页面、Ability、配置、资源和测试的固定顺序增量产出 ArkTS 工程，验证阶段覆盖 ArkTS/JSON5 静态检查、鸿蒙 OS 语义规则、真实 hvigor 编译及模拟器/官方脚本回归，Finding 按规则、文件、符号和错误码归并，并通过最多三轮的指纹检测、严重度判断和自动回滚修复错误。作品同时提供自有许可的 Android/iOS 复杂应用 Benchmark、Pi 整仓单 Prompt 与分阶段迁移主对照、调用链前置/动态检索/优先级分层/语义契约/修复循环单因素消融、Replay Provider、fake toolchain、Judge 协议及自动化 Markdown/JSON/SVG 报告，量化 Compile@1、Compile@3、运行率、核心场景通过率、调用链 F1、生命周期正确率、权限召回与一致率、过度申请率、分布式采纳与误用率、Token 消耗、迁移耗时和修复轮次，并使用重复实验、Bootstrap 置信区间和配对 McNemar 检验保证结果可复现。普通 PC 环境下可完整演示源码分析、语义规划、上下文组织、增量生成、验证、恢复和报告生成；统一的 Target Profile、命名工具链适配器与 Judge 协议可直接对接真实 HAP 编译、设备运行及官方评测，无需修改迁移核心。作品由此将传统“代码语法转换”提升为可验证、可恢复、可解释、可审计的跨操作系统复杂应用迁移工程。

作品基于 Pi 0.80.6 与上游提交 0e6909f050eeb15e8f6c05185511f3788357ddb3 构建，运行环境为 Node.js >=22.19.0。系统提供可复现的离线 Replay 验证环境，并通过统一 Profile 和命名工具链适配器接入真实编译、设备运行及官方评测环境。离线验证记录与真实工具链记录在评测体系中独立归档，确保每项实验结论均可追溯、可复现。

What is implemented

• Android and iOS structured ingestion with XML, JSON5, plist, Xcode OpenStep, and pinned Tree-sitter WASM parsers.
• Evidenced AppSemanticGraph, Given/When/Then scenarios, critical call chains, and OS obligation IR.
• Lifecycle, background scheduling, least-privilege permission, and distributed-capability decisions driven by a target Profile.
• Resumable deterministic DAG with atomic checkpoints, artifact hashes, file ownership, and conflict-free waves.
• One isolated Pi AgentSession per migration task, or one whole-repository Session for the single-prompt baseline.
• Restricted Worker tools, hash-guarded repair patches, symlink-aware path containment, and a serialized mutation queue.
• Ordered generation of scaffold, models, platform adapters, repository, state, pages, Ability, configuration, resources, and tests.
• Static/semantic validation, named real toolchain adapters, stale-HAP rejection, and a bounded repair loop.
• Replay Provider and fake toolchain for fully offline验收；其结果明确标记为 simulated，用于证明流水线可执行，不作为真实 HAP/设备成绩。
• Benchmark aggregation, fixed experiment variants, single-factor ablations, bootstrap 95% CI, and paired McNemar tests.
• Metrics-driven Markdown/JSON/SVG reports. 报告只汇总实际写入运行记录的观测；缺少官方 SDK、设备或评测适配器时记为 not_run。

Quick start

npm ci --ignore-scripts
npm run check
npm run test:unit
npm run test:integration
npm run demo:offline

npm run demo:offline needs no model key and no HarmonyOS SDK. It runs the Android fixture through the complete Pipeline and writes:

.taiyi/runs/<run-id>/
.taiyi/outputs/<timestamp>/

Run the iOS fixture explicitly:

npm run build
node dist/src/cli.js demo \
  --fixture benchmarks/fixtures/ios/complex-notes \
  --platform ios \
  --profile profiles/offline-fixture.json \
  --json

Offline output proves that orchestration, Pi tool execution, IR, generation, validation, checkpointing, and reporting work. It does not prove that a real HAP compiled or ran.

Pi Package

The root package.json declares the extension, skill, and prompt directories. Install the local package into a trusted Pi project with:

pi install . -l

Interactive commands:

/migrate android|ios <source> [profile.json]
/migration-status [run-id]
/migration-resume <run-id>
/migration-report [results-dir] [output-dir]

The extension only provides interaction entry points. The deterministic Runner, not the LLM, advances global migration state.

CLI

After npm run build, use node dist/src/cli.js or the package bin arkmigrate:

arkmigrate doctor --profile profiles/offline-fixture.json --json

arkmigrate migrate \
  --source /path/to/android-app \
  --platform android \
  --profile /path/to/target-profile.json \
  --target /path/to/arkts-output \
  --mode replay \
  --json

arkmigrate resume --run <run-id> --json
arkmigrate validate --run <run-id> --level static --json

arkmigrate evaluate \
  --suite benchmarks/suites/task2-public.json \
  --results .taiyi/runs \
  --variant full \
  --repetitions 3 \
  --json

arkmigrate ablate \
  --suite benchmarks/suites/task2-public.json \
  --results .taiyi/runs \
  --repetitions 3 \
  --json

arkmigrate report --results .taiyi/runs --out docs/generated-report --json

evaluate and ablate aggregate persisted raw runs. They do not silently launch paid model calls. A benchmark executor can call runMigration() for every case/variant/repetition and then invoke these commands.

Live model mode

Built-in Pi providers use their normal environment variables, for example OPENAI_API_KEY. Select a model explicitly:

arkmigrate migrate \
  --source /path/to/app \
  --platform android \
  --profile /path/to/explicit-real-profile.json \
  --target /path/to/output \
  --mode live \
  --provider openai \
  --model gpt-5 \
  --temperature 0 \
  --max-output-tokens 8192

For an OpenAI-compatible endpoint not already registered by Pi:

export TAIYI_OPENAI_BASE_URL=https://compatible.example/v1
export TAIYI_OPENAI_API_KEY=...
export TAIYI_MODEL_CONTEXT_WINDOW=128000

Then pass the provider and model identifiers on the CLI. Keys are read from environment variables, kept in memory, and never written to run artifacts.

Target Profiles

Profiles select the target platform, API version, device type, APL, capability allowlist, namespace mode, SDK documentation roots, and named build/runtime adapters.

• profiles/offline-fixture.json: deterministic fake toolchain; output is simulated.
• profiles/openharmony.json: OpenHarmony @ohos.* template.
• profiles/harmonyos-next.json: HarmonyOS NEXT @kit.* template.
• profiles/competition-template.json: fill only from the official judge environment.

The same target project may not mix @ohos.* and @kit.*. A live migration requires an explicit --profile.

Real adapter commands must be bare allowlisted executable names available on PATH; arbitrary shell strings and source-project scripts are rejected. A build passes only when the command exits with zero and creates or changes a HAP matching artifactPattern during that invocation.

Run real checks only after the SDK and target Profile are configured:

export TAIYI_REAL_PROFILE=/absolute/path/to/official-profile.json
export TAIYI_REAL_TARGET=/absolute/path/to/generated-project
npm run test:openharmony
npm run test:runtime

Missing adapters or environment remain not_run. They are never converted to success.

SDK

import {
  createMigrationRunner,
  evaluateSuite,
  generateReport,
  runMigration,
} from "taiyi-arkmigrate";

Public data contracts include MigrationRequest, TargetProfile, AppSemanticGraph, ScenarioSet, OSObligationSet, MigrationPlan, ContextCapsule, Finding, and RunMetrics.

Run evidence

Every run is stored under .taiyi/runs/<run-id>/:

request.json                    normalized request and Profile snapshot
run-config.json                 Taiyi/Pi versions, budgets, model metadata, and Profile hash
source-snapshot.json            source hash and file inventory
app-semantic-graph.json         evidenced semantic graph
scenarios.json                  Given/When/Then scenarios and call chains
os-obligations.json             lifecycle/permission/distributed decisions
migration-plan.json             task dependencies and file ownership
contexts/                       aggregate and per-task Context Capsules
pi-agent/                       per-Session model/tool/usage audit summaries
patches/                        hash-guarded repair receipts
findings/                       initial, per-command, and final findings
checkpoint.json                 atomic resumable stage state
events.jsonl                    ordered stage event stream
metrics/run.json                raw run metrics
evaluation.json                case, variant, repetition, platform, Profile

Resume recomputes the Taiyi implementation version, source, configuration, Profile, model, variant, and Pi upstream fingerprints. Profile, model, configuration, variant, and implementation/upstream mismatches are rejected. A source-only change is recorded as the new source fingerprint: doctor remains reusable while ingest and every data-dependent downstream stage are recomputed. Each cached JSON artifact is also checked against its checkpoint output hash, so modified IR is never silently reused.

Experiments

Fixed progressive baselines:

single-prompt
staged-full-context
call-chain-first
dynamic-priority
full

Fixed single-factor ablations:

ablate-call-chain
ablate-dynamic-retrieval
ablate-priority-layering
ablate-semantic-contract
ablate-repair-loop

The variant changes the actual Session topology, Context sections/priorities, OS contract generation, or repair budget. It is included in the run fingerprint; it is not a report-only label.

Use at least three repetitions for every case/variant with the same model, temperature, context budget, Profile, SDK, and toolchain. Simulated observations are listed but excluded from real success rates and quality aggregates.

Reports and diagrams

• docs/TECH_REPORT.md: architecture, Agent, experiments, contributions, failure analysis, and requirement traceability.
• docs/EVALUATION.md: exact metric denominators and statistics.
• docs/REPRODUCIBILITY.md: environment and repetition controls.
• docs/DEMO_SCRIPT.md: ten-minute defense script.
• docs/JUDGE_PROTOCOL.md: stable JSON judge adapter.
• docs/generated-report/: generated report, source summary, and four SVG figures.

The generated report reads raw metrics only. Missing functional execution and target call-graph evidence are represented as null/not_run; static Finding counts are not used as substitutes for scenario pass rate or call-chain F1.

License and provenance

Taiyi ArkMigrate is MIT licensed. Pi and parser provenance is documented in UPSTREAM.md and THIRD_PARTY_NOTICES.md. Exact direct and transitive versions are recorded in package.json and package-lock.json.