MigrationCoder —— 基于大模型 Coding Agent 的复杂移动应用自动迁移与评测

第三届中国研究生操作系统开源创新大赛 · 系统创新赛道 · 决赛作品参赛队名：OS

1. 项目简介

复杂移动应用向 OpenHarmony/HarmonyOS 迁移的难点不是语法翻译，而是三类 OS 语义鸿沟： Ability 架构（Activity/Service → UIAbility/ExtensionAbility）、分布式能力适配、安全权限模型（Android 动态权限 → module.json5 细粒度声明）。

MigrationCoder 从 Android 源码出发，经过五阶段迁移管线（源码分析 → 迁移规划 → 多文件生成 → 真实编译闭环修复 → OS 合规验证与评测），产出可在 HarmonyOS 工程中真实编译出 HAP 的迁移产物，并给出确定性、可复现的多层量化报告。

决赛阶段三项核心改进（较初赛的实质性提升）

#	创新	内容	代码位置	验证依据
①	编译闭环真实化	真实 `hvigorw assembleHap` 构建替代静态检查；ArkTS 错误分类学（6 类）驱动定向修复；跨文件错误目标重绑定；缺失文件自增量生成；多轮 Success@k 修复曲线	`src/pipeline/compiler.py`、`repair_loop.py`、`error_taxonomy.py`	`tests/compile_loop/`（真实错误日志探针+修复曲线）、`tests/raw_logs/`（对照实验）
②	OS 语义合规验证器	生命周期状态机校验（LC-001~~005）+ module.json5 权限↔行为一致性矩阵（PERM-001~~005）+ 分布式采纳三态评估；全部确定性规则，不依赖 LLM 判分	`src/evaluation/os_conformance/`	`tests/test_os_conformance.py`（15 项正反例）、`os_conformance_report.json`
③	依赖元数据 context + 级联失败归因	build 元数据（权限使用意图/资源引用/API 使用面）注入 context；区分”本体失败 vs 被上游拖垮”（F 组消融：上游签名注入效果未获稳健证据，如实作为负结果归档）	`src/pipeline/context_builder.py`、`src/benchmark/cascade_attribution.py`	`tests/test_context_and_attribution.py`、F 组消融与负结果（README §10.1）、`cascade_report.json`

研究贡献的组织（点 → 面）：三项创新不是并列的技巧，而是围绕同一主线的三层结构——

C1 闭环验证方法论（执行层）：编译门禁 + 确定性动作路由修复（重绑定/补文件/配置修复/最优回滚）+ 多轮 Success@k；
C2 确定性合规验证（裁判层）：三轴规则 × 官方文档逐条映射（RULE_SOURCES.md），不依赖 LLM 判分；
C3 迁移评测设计原则（方法论层）：六条可陈述、可复用的原则（分层/饱和度/口径统一/机制-噪声分离/级联归因/边界显式化，全文见 EVALUATION_PRINCIPLES.md）——把全部实验发现（静态高估、编译门禁、指标饱和、口径翻转）系统化为对赛题”评测体系设计”的回答。

C1 供证据、C2 供裁决、C3 供方法论——评测体系不是附属产物，而是作品的研究内核之一。

2. 应用场景

鸿蒙生态迁移工程：历史 Android 应用（多页面导航、状态管理、数据库、网络、权限、多模块）批量迁移到 ArkTS Stage 模型
迁移质量评估服务：为迁移产物提供真实编译门禁 + OS 语义合规检查 + 量化评测，可嵌入 CI
迁移教学与实训：真实失败案例集（tests/compile_loop/probe_logs/，7 类真实错误格式）与规则库可直接用于鸿蒙迁移教学

3. 主要功能

命令	功能
`migrate`	端到端迁移：分析 → 规划 → 多文件生成 → 真实编译闭环修复（≤3 轮） → 合规验证 → 评测报告
`compile`	对任意 ArkTS 工程执行真实编译，输出结构化诊断（错误分类/位置/修复指引）
`conformance`	OS 语义合规三轴验证（生命周期 / 权限一致性 / 分布式采纳）
`benchmark`	37 个场景级 benchmark（含 dependency metadata 与依赖链）
`ablation`	context 消融实验；矩阵实验入口 `tests/experiments/run_matrix.py`

支持的 LLM Provider（可插拔，7 种）

Provider	默认模型	费用	获取地址
DeepSeek（主方案）	deepseek-chat	极低价	platform.deepseek.com
Zhipu / GLM	glm-4.7-flash	永久免费	open.bigmodel.cn
Groq	llama-3.3-70b	1000次/天免费	console.groq.com
OpenRouter	qwen3-coder	200次/天免费	openrouter.ai
Mistral	codestral-2501	免费实验计划	console.mistral.ai
Claude	claude-sonnet-4-6	付费	console.anthropic.com
OVHcloud	Qwen3.5-397B	免注册	ovhcloud.com

4. 系统环境

组件	要求	本项目验证版本
操作系统	Windows 10/11（普通 PC，无需独立显卡）	Windows 11
Python	3.11+	3.14.5
DevEco Command Line Tools	HarmonyOS SDK API 26 配套	26.0.0.851（hvigor 6.26.8 / ohpm 26.0.0.630 / codelinter 6.0.240）
JDK	17（Temurin）	17.0.20.1
Node.js	CLT 自带（勿用系统 node）	24.14.1（CLT bundled）

⚠️ 路径要求（实测踩坑，已归档）：hvigor 拒绝含中文/特殊字符的工程路径（错误码 00306003），所有迁移输出目录必须使用纯 ASCII 路径。错误样本：tests/compile_loop/probe_logs/g_chinese_path.build.log

5. 依赖要求

pip install -r requirements.txt        # click/pyyaml/openai/anthropic/python-dotenv/rich/pytest 等
cp .env.example .env                   # 填入任一 LLM API Key（AGENT_PROVIDER 选择 provider）

外部工具链（不在 pip 依赖内）：

从华为开发者下载中心获取 Command Line Tools for Windows 并解压
安装 JDK 17（如 Temurin）
配置下方环境变量，或在 configs/default.yaml 的 compiler 段填写绝对路径

6. 构建方法（工具链配置）

# 环境变量（每个新终端执行一次）
export CLT_ROOT='<解压目录>\command-line-tools'      # 内含 bin/ sdk/ tool/node
export DEVECO_SDK_HOME='<解压目录>\command-line-tools\sdk'
export JAVA_HOME='<JDK17目录>'                        # 关键：JDK 的 bin 必须进入 PATH（否则打包 spawn java ENOENT）
export PATH="$JAVA_HOME/bin:<解压目录>\command-line-tools\bin:<解压目录>\command-line-tools\tool\node:$PATH"

验证：

python -m src.main compile -p src/templates/arkts_project    # 应输出 success=True 与 HAP 路径

7. 运行方法

# ① 端到端迁移（真实 LLM + 真实编译闭环）
python -m src.main migrate -s tests/benchmark_data/source_apps/SampleNoteApp -o <纯ASCII输出目录>

# 输出物：
#   arkts_app/                      可编译工程（含 entry-default-unsigned.hap）
#   migration_result.json           汇总指标（真实编译/轮次/三轴/归因）
#   compile_loop_report.json        多轮修复曲线（Success@k 原始数据）+ 可达性
#   os_conformance_report.json      三轴合规报告
#   cascade_report.json             级联失败归因报告

# ② 静态检查对照模式（消融实验基线，不接入真实编译）
python -m src.main migrate -s <应用> -o <目录> --no-compile-loop

# ③ 单独编译检查
python -m src.main compile -p <ArkTS工程> --json-out result.json

# ④ OS 语义合规检查
python -m src.main conformance -p <ArkTS工程> -s <Android源应用> --json-out conformance.json

# ⑤ 实验矩阵（静态对照/context 消融/重复性/跨应用泛化，复现协议 temperature=0）
python tests/experiments/run_matrix.py      # 产物归档至 tests/raw_logs/<matrix_id>/

8. 测试方法

python -m pytest tests/ -q     # 80 项测试（含真实编译集成测试；未配置工具链时自动跳过）

测试材料	内容
`tests/test_compiler.py`	7 份真实 hvigor 错误日志的解析回归（arkts_rule/type/syntax/config/resource/environment）
`tests/test_repair_loop.py`	修复环机制单测（收敛/无进展/重复动作/跨文件重绑定/缺失文件生成）+ 真实编译端到端修复
`tests/test_os_conformance.py`	三轴规则正/反例 15 项
`tests/test_context_and_attribution.py`	依赖元数据与级联归因 9 项
`tests/compile_loop/`	错误格式探针原始日志 + 端到端冒烟结果（失败案例集）
`tests/raw_logs/`	实验矩阵原始产物（每次运行完整报告与真实编译日志）
`tests/experiments/run_matrix.py`	实验矩阵运行器（复现协议：temperature=0，全量产物归档）

9. 已知限制

运行时行为未在真机验证：编译与静态合规为硬证据；应用运行行为需 DevEco 模拟器/真机。本作品在无独显的普通 PC 环境完成（符合赛题硬件要求），模拟器实机运行未纳入验证，如实声明。
分布式能力：distributedDataObject/KVStore 真机验证需双设备同账号组网；本作品采用”静态规则 + 采纳合理性三态评估”，不做运行时验证。
LLM 非确定性：实验矩阵采用 temperature=0 复现协议，仍存在少量波动（C 组实测 3 次重复波动 ≤0.04）；F 组消融经历”单例→重复实验→统一指标重算”两轮修正后判定为负结果——机制效果必须同时经重复实验与统一指标双重检验。评测以多轮 Success@k 与重复实验呈现，不承诺单次一致。
覆盖范围：Java/Kotlin 源码级 Android 应用（目标 ArkTS Stage 模型）；Compose UI、NDK 原生代码不在覆盖范围。
产物形态：unsigned HAP 仅作编译证据，不可直接安装分发；.env（API Key）不入库。
规模边界（实证界定，预注册 H-S1）：≤9 组件应用 12/14 收敛；18 组件/5 层依赖链的合成压力应用未在 4 轮预算内收敛（扇出型接口错误，267K tokens，结构保真 0.97/场景 6/6——瓶颈在收敛不在质量）。 roadmap：接口签名冻结检查、静态成员一致性确定性修复器、修复预算按错误扇出度分配、分层增量迁移。

10. 实验结果

全部为真实运行记录（真实 LLM + 真实 hvigor 编译），逐 run 原始产物归档于 tests/raw_logs/；无需 API Key 的成品凭证见 demo/generated_sample/。复现协议：temperature=0；评测场景 37 个（场景-应用映射见 tests/benchmark_data/SCENARIO_APP_MATRIX.md）。

10.1 实验矩阵总览（每行 = 一次真实迁移 run）

A 组静态 vs 编译闭环（创新①核心证据，SampleNoteApp 同配置对照）

run	编译口径	真实编译	综合分	编译轮次	Token
A1 静态检查	静态 PASS（无法验证可编译性）	—	0.513	0	91,684
A2 编译闭环	真实 PASS	✓ 产出 HAP	0.847	1	43,523

结论：编译闭环既给出真实可编译证据，又因”编译错误→定向修复”更精准而节省约 53% Token。

B 组 Context 消融（编译闭环开启）

配置	真实编译	综合分	结论
plan_plus_callchain	✓	0.893	最小有效 context（与初赛结论一致，真实编译口径复现）
with_metadata	✓	0.866	次优
full_context	✓	0.847	全量不是最好
no_semantic_map	✓	0.816	去掉 OS 语义映射明显下降
plan_only	✗	0.576	最小 context 不足，区分度清晰

C 组重复性（同配置 3 次）：0.847 / 0.855 / 0.884，pass³ = 3/3（波动 ≤0.04）

D 组跨应用泛化（修复环根因修复前后对照）

应用	初轮	修复后	备注
TaskBoardApp（8 组件：Service/相机/通知）	FAIL	Success@1（0.813）	配置修复器/Kit 规范生效
WeatherApp（网络为主）	FAIL	Success@4（0.773）	修复曲线 4→3→1→1→0，第 4 轮收敛

结论：复杂应用需要多轮修复预算——报告”多轮 Success@k”而非单轮（对齐 RepoTransBench 口径）；初轮失败的两个根因（知识库无效权限映射 / 修复环过早放弃）均有确定性修复与回归测试。

E 组第三方留出应用（非自建真实工程，泛化验证）

run	对象	真实编译	综合分	轮次	三轴合规	备注
E1	Google Room codelab（Apache 2.0，9 类）	✓	0.789	4	1.00/1.00/1.00	曲线 5→2→3→1→0（非单调）
E3	Google Navigation codelab（Apache 2.0，Fragment/DeepLink/Receiver）	✗	0.378	4	0.94	发现真实缺陷：pages/ 下无 @Entry 组件被误注册为路由页
E3r	同上（修复后重跑）	✓	0.740	1	—	缺陷修复后首轮零错误通过（`@Entry` 过滤注册）
E3rep2	同上（预注册 H-L1 复现实验，n=2）	✓	0.701	1	—	预注册假设”通过且 ≤2 轮”成立——修复效果复现性确认
E2r	SampleNoteApp（GLM-4.7-Flash 跨模型）	✗	0.614	3	0.96	残留 37 错误（ui_syntax×16 + syntax×9 + type×10）；18.2 分钟 / 161K tokens（免费额度限流下 2 次退避重试成功）

跨模型发现（重要）：GLM 产物的结构指标满分（依赖边 1.00、场景 19/19、API 覆盖 1.00）但语法层 37 处无法收敛——若用静态口径评分，GLM 与 DeepSeek 几乎无差别（初赛静态口径 GLM 甚至更高），真实编译口径立刻暴露差距。这从另一个方向印证了创新①的必要性（编译门禁不可省略），同时如实说明：管线收敛能力对模型强依赖（DeepSeek 12/14 收敛 vs GLM 0/1），主结论均以 DeepSeek 为准并标注。

E1 价值：①首个非自建工程通过真实编译；②修复曲线非单调（第 2 轮 2→3 回升，属策略切换代价）—— 朴素”错误数不降即停”会在第 3 轮误停，本方案”无动作才停”策略第 4 轮收敛成功（多轮 Success@k 必要性实证）； ③0 死文件（全部产出参与编译）。 E3→E3r 价值：第二个第三方应用暴露”N页注册启发式”真实缺陷（Fragment 派生组件无 @Entry 却被注册）， 确定性修复 + 回归测试（test_builder_page_registration_requires_entry_decorator）+ 重跑验证—— 留出应用第三次完成”暴露缺陷→修复→验证”闭环。注：该应用导航依赖 XML 声明（源码无组件间引用），依赖边指标不适用（expected=0，如实标注）。跨模型（GLM-4.7-Flash）决赛复跑在免费额度限流（429/1305）下经 2 次退避重试后完成（E2r）：结论见 E2r 行——静态口径高分 vs 真实编译不收敛的差距，是本方案编译门禁价值的直接证据。

F 组创新③消融：上游接口注入（各条件 3 次重复，统一指标重算）

条件	真实编译	综合分（均值）	依赖边完整性（逐次 / 均值）
注入开启	2/3	0.775	0.90 / 1.00 / 1.00（均值 0.97）
注入关闭	2/3	0.783	1.00 / 1.00 / 0.86（均值 0.95）

负结果（如实报告）：上游接口签名注入未观测到稳健效果——编译通过率与综合分无差异，结构保真度差异（+0.02）落在组内波动范围（±0.14）内。该结论经过两轮修正：单例实验曾显示 “+0.18 一致优势”，但（a）补足重复实验、（b）以统一指标对所有 run 重算后，差异消失（被确认为指标口径伪影）。创新③的可靠贡献修正为：build 元数据 context 组织 + 级联失败归因（均为确定性分析，有独立证据）；上游签名注入作为工程特性保留，效果不作主张。

方法学记录：评测口径变化可以翻转结论——本作品所有对比声明均以统一指标重算为准，负结果同样入档（tests/raw_logs/），这本身是”可复现评测”要求的直接实践。

G 组单 Prompt 基线（赛题”必须为 Coding Agent 而非单一 prompt”的对照）

预算	room 应用	SampleNoteApp	备注
初版（8K 输出上限）	FAIL（仅 1 文件）	FAIL（差 1 错误）	8K 预算下输出被截断，噪声
公平（16K，未截断）	FAIL（11 文件，差 1 错误：`arkts-no-misplaced-imports`）	FAIL（8 文件，差 1 错误：`@Entry` 页面约束）	场景 18/18、依赖边 0.83~0.90

结论：单 prompt 在公平预算下能产出结构合理的”接近成功”代码（且成本仅 4~8K tokens），但 4/4 案例止步于最后 1 个编译错误——开环无反馈、无法收敛。主管线 14 次 room/SN 运行中 12 次收敛到零错误 + HAP。→ Coding Agent 与单一 prompt 的本质差异是闭环收敛与验证，而非首轮代码质量（此结论同时呼应创新①：修复环正是闭环的执行者）。

H 组规模压力与预注册实验（假设先于运行锁定，见 PRE_REGISTRATION.md）

run	对象	真实编译	综合分	轮次	Token	备注
H1	LedgerProApp（自建合成，18 组件/5 层依赖链）	✗（H-S1 证伪）	0.599	4（上限）	266,785	结构保真 0.97、场景 6/6——瓶颈在收敛不在质量
E3rep2	Navigation codelab（H-L1 预注册复现）	✓	0.701	1	56,680	假设”通过且 ≤2 轮”成立（修复复现 n=2）

规模边界首次被实证界定：≤9 组件应用 12/14 收敛；18 组件/5 层深链未在 4 轮/预算内收敛。失败模式 = 扇出型接口错误（CategoryConverter 单一接口决策失衡在 3 文件引发 10+ 调用点错误，修复动作持续但扇出面未收拢：16→16→15→15）——错误具有扇出结构时，收敛成本非线性。该观察已写入 EVALUATION_PRINCIPLES.md（P2 补充：修复预算应按”扇出度”而非错误计数分配）。

10.2 场景级与覆盖指标（方向一核心数据，37 场景真实参与评测）

指标	结果	说明
场景通过率（负向判据：Android 残留清洁）	通过类 run 全部 1.00（SN 系 18/18 或 19/19、room 系 5/5、nav 系 4/4）；失败 run 4/5	场景检查已接入每次运行并落盘 `scenario_report.json`；场景集随归属标注演进（NAV-001 归入 SN 后为 19）
API 语义覆盖率（源 API→目标映射逐条）	全部 run 1.00（含基线）	能力级映射普遍达成；明细见 `coverage_report.json`
依赖边完整性（import 图 vs 源依赖图真比对）	0.50 ~ 1.00（区分度最大）	结构漂移可量化（如 A2=0.50 表示 LLM 简化了架构）

核心发现：在编译门禁之下，”Android 残留清洁”是全数保持的不变量（场景级达标）； 区分度主要来自结构保真（依赖边）与收敛能力（轮次/通过率）——评测体系据此定位各指标的角色。

10.3 端到端迁移演进（开发期真实 run，修复环能力曲线）

run	结果	综合分	OS语义	关键改进
e2e-v3	Success@2	0.65	—	修复环机制首次真实生效
e2e-v6	Success@1	0.78	—	全类发现+重绑定+可达性检查
e2e-v7	Success@2	0.85	0.96	三创新全开

10.4 验证分层与边界声明（对”运行时未验证”的正面设计）

本作品按”证据强度分层”组织验证，并对未覆盖的边界做显式声明（而非默认沉默）：

层	证据	强度	可复现性
L1 硬证据	真实 hvigor 编译 + unsigned HAP（含哈希）	编译器 oracle	任何装了 CLT 的普通 PC 可复算
L2 确定性规则	三轴合规（生命周期/权限一致性/分布式采纳），不依赖 LLM 判分	规则级	纯静态，结果确定
L3 场景不变量	37 场景负向判据（Android 残留清洁）+ API 语义覆盖	规则级	每次运行自动落盘
边界（显式声明，已实测）	应用运行时行为需模拟器/真机；分布式需双设备组网——均超出赛题”普通 PC、不提供额外硬件”范围。命令行 Previewer 路径已实测（探针 H，`tests/compile_loop/previewer_probe/`）：可启动、参数体系可达，阻塞于 hvigor 预览编译链内部缺陷（`addOhmurlToHarAbility`），已归档精确阻塞点	待补	接入路径见下

设计取向：与其提供不可复现的模拟器截图，不如把”可复现的强规则验证”做深（Kaizen 实证”编译通过是极差正确性代理”，故编译仅作门禁，成功判定叠加三轴规则与场景不变量）。补齐运行时验证的接入路径： ① DevEco IDE 预览器（IDE 注入缺失参数后预览链应可用——探针 H 已定位 CLI 路径缺口）； ② 模拟器安装 unsigned HAP → hdc 安装 + UI 操作录制；③ 双真机组网验证 distributedDataObject/distributedKVStore。

10.5 初赛基线（静态检查口径，供对照）

初赛方案在 2 个样例应用、27 场景基准：Android 残留率 2.9%（FTP 97.1%）、调用链全满分行。注：初赛”编译通过”为静态口径；决赛改为真实编译，口径差异正是创新①的动机与证据。

10.6 评测体系设计原则（研究贡献 C3）

六条原则全文见 EVALUATION_PRINCIPLES.md：分层 / 饱和度 / 口径统一 / 机制-噪声分离（预注册，PRE_REGISTRATION.md）/ 级联归因 / 边界显式化。一句话概括：本 benchmark 的”区分度”是被设计出来的——饱和指标（场景负向判据、API 覆盖）承担回归防护，未饱和指标（多轮 Success@k、依赖边完整性）承担方案比较。这直接回应赛题”是否能通过 benchmark 区分不同 pipeline / context 方案优劣”：B 组消融即在该机制下区分出 plan_only 失败（0.576）与 plan+callchain 最优（0.893）。

11. 与现有工作的关系

现有工作	本方案的借鉴	决赛增量差异
ECAT / A2H-RepoBench（arXiv:2608.09273, 2026）Android→HarmonyOS 仓库级迁移 agent	应用级迁移需多维缺陷控制	ECAT 验证器为加权缺陷熵代理+LLM 判别（可复现性受质疑）；本方案为确定性规则 + 真实编译器 oracle，无 LLM 判分
UITrans（Internetware 2025 Best Tool Demo）	多 Agent 反思 → Reviewer 自校验	从 UI 层扩展到全应用（Ability/数据/网络/权限），并补上其缺失的编译闭环与行为验证
CODEMENV（ACL 2025 Findings，跨环境迁移 benchmark）	任务阶梯化评测思想	从函数级 API 适配扩展到应用级 OS 语义迁移
SWE-bench（ICLR 2024）+ SWE-Bench Pro 防作弊研究	PASS/FAIL 双轨、防泄漏评测	应用到编译门禁 + 多轮 Success@k；隐藏行为清单不进生成 context
RepoScope（ICSE 2026）/ SWE-Pruner（2025）	调用链/裁剪式 context 组织	以 build 元数据（gradle/权限意图/资源/API 面）为 context 组织轴，并做级联失败归因
RepoTransBench（IEEE TSE 2026）	多轮调试后 Success@k 报告口径	直接采用其口径报告修复曲线，避免单轮数字低估 agent
DeepCode（arXiv:2512.07921）	蓝图/闭环修复范式	闭环从”文档→码”迁移到”源码→跨 OS 迁移”，并升级为编译+合规双验证
Kaizen（arXiv:2607.04058）	“编译通过是极差正确性代理”	编译仅作门禁，成功判定叠加三轴确定性规则与行为清单

12. 参考文献

Gong L, et al. UITrans: Seamless UI Translation from Android to HarmonyOS. Internetware 2025 (Best Tool Demo).
Cheng K, et al. CODEMENV: Benchmarking Large Language Models on Code Migration. ACL 2025 Findings.
Jimenez C E, et al. SWE-bench. ICLR 2024 (Oral).
Liu Y, et al. RepoScope: Call Chain-Aware Multi-View Context. ICSE 2026.
Wang Y, et al. SWE-Pruner: Self-Adaptive Context Pruning. arXiv:2601.16746, 2025.
Li Z, et al. DeepCode: Open Agentic Coding. arXiv:2512.07921, 2025.
ECAT / A2H-RepoBench: Entropy-Based Code Adversarial Translation for Real-World Repository Migration. arXiv:2608.09273, 2026.
RepoTransBench: A Real-World Benchmark for Repository-Level Code Translation. IEEE TSE, 2026.

OS 队 · 第三届中国研究生操作系统开源创新大赛 · 决赛