鸿迁智评（ArkMigrate-Eval）

作品简介

鸿迁智评（ArkMigrate-Eval） 面向“基于大模型 Coding Agent 的复杂移动应用自动迁移与评测”赛题，提供一套用于 Android / iOS 应用向 OpenHarmony / HarmonyOS ArkTS 迁移的评测与对照实验框架。

本作品目前重点解决“如何客观评估迁移方案”的问题：通过场景级 benchmark、结构化 context 消融实验、可复现评分指标和报告生成能力，量化比较不同 Coding Agent、不同迁移 Pipeline、不同上下文组织方式在复杂移动应用迁移任务中的效果。

作品关注的迁移难点包括：

Ability 架构差异：Android Activity / Service、iOS ViewController 到 UIAbility / ExtensionAbility 的语义适配；
安全与权限模型重构：运行时权限、module.json5 权限声明和调用行为一致性；
复杂应用链路：多页面导航、状态管理、数据库持久化、网络请求、后台任务、媒体处理、多模块调用；
OpenHarmony 特有能力：分布式数据、软总线、跨设备协同等能力的合理采纳与评估；
Agent 长链路稳定性：Plan、调用链、源码片段、依赖元信息等 context 组件对迁移效果和 token 成本的影响。

当前版本已经实现可运行的 MVP，并原生兼容 SWE-Harmony/SWE-OpenHarmony benchmark 原型：

benchmark schema、10 个 synthetic 场景样例，以及 SWE-Harmony release/JSONL adapter；
spec_only、spec+plan、spec+plan+callchain、full_source、structured_priority_context 等 context 配置；
deterministic mock agent，便于无模型密钥时复现实验；
OpenAI-compatible 模型接口，便于接入兼容 /v1/chat/completions 的大模型服务；
多维度 evaluator，输出通过率、综合分、token 用量、错误类型和级联失败标记；
JSON、CSV、Markdown 和 HTML Dashboard 四种报告格式；
自动生成可离线打开的 HTML 实验仪表盘，展示 Context 质量/成本和 case 失败原因；
SWE-Harmony 官方口径的 Hypium、构建率、diff 产出率、token、耗时和成本汇总；
从 Git base_commit 进行预算受控的相关源码检索，不读取参考提交；
将模型生成的完整文件确定性转换为标准 Git unified diff，减少模型补丁格式错误；
unified diff 格式、patch 应用性、ArkTS 结构、权限声明和生命周期静态检查；
重复实验、成对 context 对比、bootstrap 置信区间与运行环境清单。

目录结构

.
├── benchmarks/
│   └── synthetic/cases.json      # 自建场景级 benchmark 样例
├── makememoryempty/              # 核心实现代码
│   ├── cli.py                    # 命令行入口
│   ├── agent.py                  # mock / model agent 调用封装
│   ├── context.py                # context ablation 配置与构造
│   ├── dataset.py                # benchmark 加载与校验
│   ├── evaluator.py              # 多维度评分逻辑
│   ├── official_metrics.py       # SWE-Harmony 官方指标聚合
│   ├── patch_builder.py          # 完整文件到 Git patch 的确定性转换
│   ├── source_retrieval.py       # base_commit 源码检索
│   ├── static_analysis.py        # OS 语义与 patch 静态检查
│   ├── prediction_validation.py  # prediction/patch 应用性检查
│   ├── providers.py              # mock 与 OpenAI-compatible provider
│   ├── reports.py                # JSON / CSV / Markdown 报告输出
│   ├── dashboard.py              # 无服务器 HTML 实验仪表盘
│   └── runner.py                 # ablation 运行主流程
├── experiments/preliminary/      # 初赛真实模型消融结果与补丁验证证据
├── tests/                        # 单元测试与集成测试
├── documents/                    # 赛题说明与提交模板
├── pyproject.toml                # Python 项目配置
└── README.md                     # 作品简介与运行说明

环境要求

Python 3.10 及以上版本；
Windows / Linux / macOS 均可运行；
API 地址和密钥。

运行说明

1. 安装依赖

在仓库根目录执行：

python -m pip install -e .[dev]

安装后可使用新的命令入口：

arkmigrate-eval --help

也可使用模块方式运行：

python -m makememoryempty --help

2. 校验 benchmark 数据

arkmigrate-eval validate --benchmark benchmarks/synthetic/cases.json

预期输出：

OK: loaded 10 benchmark cases from benchmarks/synthetic/cases.json

也可以直接传入 SWE-Harmony release 根目录、metadata/suite_manifest.json 或单个 track JSONL：

arkmigrate-eval validate `
  --benchmark documents/SWE-OpenHarmony `
  --track a2h-page-15

查看数据集组成、仓库数和公开动态测试覆盖情况：

arkmigrate-eval inspect --benchmark documents/SWE-OpenHarmony

当前本地原型应识别出 65 个任务：incremental-dev-50 50 条、a2h-page-15 15 条；其中前者公开 190 个评分方法，后者的 Hypium 测试暂不公开。

3. 查看内置 context 配置

arkmigrate-eval list-contexts

内置配置包括：

spec_only
spec+plan
spec+plan+callchain
full_source
structured_priority_context
spec+retrieved_source
structured_retrieved_context

后两种配置需要预先准备应用仓库，并通过 --repos-dir 指定路径。检索器使用 git show <base_commit>:<path> 读取源码，不 checkout 工作区，也不会读取 final_commit。

4. 使用 mock agent 运行完整评测

无需 API key 即可运行：

arkmigrate-eval run `
  --benchmark benchmarks/synthetic/cases.json `
  --output runs/demo `
  --provider mock

生成文件：

runs/demo/results.json：完整机器可读结果；
runs/demo/results.csv：便于表格分析的结果；
runs/demo/report.md：Markdown 实验报告。
runs/demo/dashboard.html：可直接用浏览器打开的实验仪表盘；
runs/demo/agent_outputs/<context>/<case>.json：每次 Agent 的计划、生成文件和 token 记录；
runs/demo/predictions-<context>.jsonl：当模型返回 model_patch 时生成的 SWE-Harmony 提交文件。
runs/demo/analysis.json：分组统计、成对 context 对比和置信区间；
runs/demo/run_manifest.json：模型、context、重复次数、源码预算、运行环境和代码版本。

5. 只运行部分 case 或部分 context

arkmigrate-eval run `
  --benchmark documents/SWE-OpenHarmony `
  --output runs/quick `
  --provider mock `
  --contexts spec_only structured_priority_context `
  --track a2h-page-15 `
  --limit 3 `
  --repetitions 3

该命令会对前 3 个 case 分别运行 spec_only 与 structured_priority_context，用于快速验证 context 消融效果。

准备好官方应用仓库后，可运行真正的源码检索消融：

arkmigrate-eval run `
  --benchmark documents/SWE-OpenHarmony `
  --track a2h-page-15 `
  --repos-dir documents/SWE-OpenHarmony/repos `
  --contexts spec_only spec+plan+callchain spec+retrieved_source structured_retrieved_context `
  --source-max-files 8 `
  --source-max-chars 12000 `
  --repetitions 3 `
  --provider openai `
  --output runs/a2h-ablation

6. 接入 OpenAI-compatible 模型服务

支持任何兼容 /v1/chat/completions 的模型服务：

$env:OPENAI_BASE_URL="https://api.openai.com/v1"
$env:OPENAI_API_KEY="替换为实际密钥"
$env:OPENAI_MODEL="gpt-4.1-mini"

arkmigrate-eval run `
  --benchmark benchmarks/synthetic/cases.json `
  --output runs/model `
  --provider openai `
  --contexts structured_priority_context

也可以使用本地 JSON 配置文件。

模型名也可以通过命令行覆盖，适合先用轻量模型做 smoke test：

arkmigrate-eval run `
  --benchmark documents/SWE-OpenHarmony `
  --track a2h-page-15 `
  --repos-dir documents/SWE-OpenHarmony/repos `
  --provider openai `
  --model-config config/keys.json `
  --model qwen3-coder-flash `
  --model-timeout 180 `
  --contexts structured_retrieved_context `
  --limit 1 `
  --output runs/a2h-smoke

--model-timeout 控制单次请求超时，默认 180 秒。大源码 context 的生成时间可能超过 60 秒，正式实验应记录统一的 timeout，超时 case 会被隔离为 agent_error，不会中断整批任务。

推荐模型返回 JSON，字段包括：

migration_plan：迁移计划步骤数组；
generated_files：仓库相对路径到完整文件内容的映射；框架也兼容常见的 [{"path": "...", "content": "..."}] 数组形式；
notes：模型补充说明数组；
model_patch：可应用到任务 base_commit 的 unified diff，正式 benchmark 运行时应提供。

如果模型返回非结构化文本，框架仍会保存原始输出，并按原始迁移产物进行代理评分。对于仓库任务，只要模型返回 generated_files，框架会基于任务 base_commit 重新构造标准 Git patch，避免将 Markdown 或非 Git 格式 diff 误当作正式提交物。

7. 运行测试

python -m pytest

当前测试覆盖：

benchmark schema 校验；
依赖 metadata 解析；
mock provider token 统计；
evaluator 分数计算；
CLI 集成运行与报告生成。
模型配置别名、结构化输出兼容、确定性 patch 构建与 git apply --check。

真实模型实验

初赛小样本实验使用 qwen3-coder-flash，选择 3 个公开 A2H case： mihon-more-tab、mihon-statistics、anki-card-browser。每个 case 分别运行：

spec_only；
spec+plan+callchain；
structured_retrieved_context。

共完成 9 次真实模型调用，无 Agent 请求错误。实验结果保存在 experiments/preliminary，其中 dashboard.html 可直接打开用于演示。

Context	平均代理分	静态编译代理	功能等价代理	调用链完整率	ArkTS 产物完整度	生命周期正确率	平均 Token	平均耗时
`spec_only`	0.732	100.0%	88.9%	84.2%	33.3%	0.0%	2,847	15.60s
`spec+plan+callchain`	0.711	91.7%	65.7%	69.3%	66.7%	0.0%	2,809	13.29s
`structured_retrieved_context`	0.834	100.0%	85.8%	87.5%	100.0%	33.3%	8,528	37.24s

相对 spec_only，结构化检索上下文的平均代理分提升 0.102（约 13.9%）， ArkTS 产物完整度提升 66.7 个百分点，平均缺口数由 1.67 降至 1.33；代价是 token 增加约 199.5%、平均耗时增加约 138.7%。这说明结构化源码检索提高了质量上限，但不是最省 token 的方案。spec+plan+callchain 在该小样本中没有稳定超过 spec_only，提示调用链需要与相关源码按需组合，而不是单纯增加提示文字。

独立补丁验证结果：spec_only 和 spec+plan+callchain 的格式率、应用率均为 100%；structured_retrieved_context 的格式率为 66.7%，格式有效补丁的 git apply --check 通过率为 100%。详细实验方法、指标定义和限制见 技术报告.md。

上述编译、功能和调用链指标均为确定性静态代理指标，不是 DevEco 构建或官方 Hypium 隐藏测试成绩。A2H 公共发布包不提供动态测试，最终功能正确率以赛事方统一环境和隐藏测试为准。

项目 pytest 仅收集 tests/；documents/SWE-OpenHarmony/hypium/ 中的设备测试由官方 runner 执行，不参与本地 Python 单元测试收集。

8. 汇总 SWE-Harmony 官方指标

当迁移 Agent 已输出 patch，并经 SWE-Harmony matrix runner/Hypium runner 评测后，可按原型的 leaderboard 公式统一汇总：

arkmigrate-eval score-official `
  --hypium-results results/hypium/agent_model/results.json `
  --matrix-summary results/matrix/run_id/matrix_summary.json `
  --track incremental-dev-50 `
  --output runs/official-metrics.json

a2h-page-15 的公开包没有 Hypium 测试，因此现阶段只公开复现 patch 产出、构建和成本指标。

9. 检查外部环境

arkmigrate-eval doctor `
  --benchmark documents/SWE-OpenHarmony `
  --track a2h-page-15 `
  --repos-dir documents/SWE-OpenHarmony/repos `
  --model-config config/keys.json `
  --model qwen3-coder-flash

该命令只报告凭据是否配置，不输出密钥内容；同时检查 Git、Node.js、hvigor、hdc、SDK 环境变量和各应用仓库。当前仅执行 A2H 时应带上 --track a2h-page-15，否则 doctor 会同时检查 incremental-dev-50 所需的其他仓库。

10. 校验真实 Agent patch

arkmigrate-eval validate-predictions `
  --benchmark documents/SWE-OpenHarmony `
  --predictions runs/a2h-ablation/predictions-structured_retrieved_context-run1.jsonl `
  --repos-dir documents/SWE-OpenHarmony/repos `
  --track a2h-page-15 `
  --output runs/a2h-ablation/patch-validation.json

校验器会创建临时 detached Git worktree，在对应 base_commit 上执行 git apply --check，不会修改主工作区。

Benchmark 数据说明

当前 synthetic benchmark 位于：

benchmarks/synthetic/cases.json

每个 case 包含：

源平台：android 或 ios；
场景类型：导航、状态管理、持久化、网络、权限、后台任务、媒体、安全、分布式等；
源码路径与源码片段；
迁移目标；
依赖 metadata；
期望能力；
所需权限和 API；
生命周期语义；
调用链；
OpenHarmony 分布式能力采纳机会；
指标权重。

SWE-Harmony adapter 支持三种入口：完整 release 目录、suite manifest、track JSONL。它会读取 spec_file 的完整自然语言任务说明，并保留 repo、base_commit、final_commit、hypium_file、fixture 与可见性等溯源信息。其中 final_commit 不会写入模型 context，防止参考实现泄漏。

adapter 同时兼容 site/*_flat.jsonl 的 SWE-bench 风格字段，包括 problem_statement、patch、test_cases、FAIL_TO_PASS 和 PASS_TO_PASS。其中参考 patch 仅保留作离线误差分析与数据 sanity check，不会进入 Agent context；正式运行仍以 base_commit + problem_statement/spec 为输入。

本地 documents/SWE-OpenHarmony 原型包含我们需要的四类核心数据：

metadata/：65 条任务 manifest、仓库地址、基线/参考提交和测试可见性；
specs/：15 条 Android 页面迁移 spec 与 50 条 ArkTS 增量开发 spec；
hypium/：50 条增量开发任务的公开动态测试，A2H 测试隐藏；
trajectories/：多 Agent/模型运行轨迹健康度报告，可用于后续 Agent 行为效率研究。

应用源码不随 release 直接存放，需要根据 metadata/repo_sources.json 克隆到 repos/<repo>，并在每个任务的 base_commit 上运行 Agent。标准提交物是 unified diff patch，而不是孤立的 ArkTS 文件。

评测指标

当前 evaluator 使用确定性代理指标，便于在没有 DevEco/设备时做 context 消融和预评测：

plan_quality：迁移计划完整度；
dependency_satisfaction：依赖 case 满足情况；
call_chain_completeness：关键调用链覆盖率；
arkts_artifact_completeness：ArkTS / module.json5 产物完整度；
permission_consistency：权限声明与调用需求一致性；
ability_lifecycle_correctness：Ability / 页面生命周期语义覆盖；
static_compile_proxy：ETS 括号、组件 build()、残留 Android import 等结构检查；
functional_equivalence_proxy：功能等价性的轻量代理指标；
distributed_adoption：OpenHarmony 分布式能力采纳情况；
patch_submission_readiness：是否产生官方可接收的 unified diff。

报告会明确标注 proxy_only，避免将代理分数误报为官方成绩。正式对齐 SWE-Harmony 的指标包括：动态功能正确率、SPEC 全通过率、SPEC 至少一项通过率、最终编译率、DIFF 产出率、token、耗时和单 SPEC 成本；其中动态功能正确率是主指标。

仓库级任务采用硬门槛：缺少 unified diff、必要权限、生命周期实现或基本 ArkTS 结构时，即使综合代理分较高也不能标记为通过。

报告按 provider、track、context 分组，并给出相对 spec_only 的成对得分差、token 差、胜/平/负和 bootstrap 95% 置信区间。mock 结果只用于验证流程，不能作为比赛实验结论。

Mock 流程预期

使用 mock agent 运行完整 synthetic benchmark 时，预期能够观察到：

spec_only 分数最低，常出现调用链缺失、生命周期缺失和级联失败；
spec+plan 相比 spec_only 明显提升；
spec+plan+callchain 能提升调用链完整性；
full_source 能进一步提高 API 与功能代理指标；
structured_priority_context 在当前 synthetic benchmark 中得分最高，但 token 成本也更高。

这组结果仅验证评分、报告和消融管线能正常工作。正式结论必须来自真实模型 patch、真实仓库构建和官方 Hypium/隐藏测试，不能引用 mock 分数作为优化证据。