Code Mirage

Code Mirage 是一套面向 Python → HarmonyOS NEXT 的自动迁移与严格评测系统。 它将 Python distribution 分析、兼容性适配、目标 wheel 构建、ABI 审计、真机验证和 Coding Agent 工作流组织成可复现的 Pipeline；只有完整验证门禁通过，产物才会进入 release/。

项目不把“生成了代码”视为迁移成功，也不会用 stub、静默降级、跳过测试或本地模拟 代替目标设备证据。缺少 SDK、SOABI、依赖闭包、测试 oracle、函数覆盖或真机行为证据 时，运行会明确返回 blocked/failed/unavailable，而不是制造成功结果。

核心能力

• 分析 Python 包的 import、public API、依赖、package data、动态加载和 native 扩展；
• 处理纯 Python、C/C++、Cython、Rust/PyO3、Fortran、ctypes 等迁移路径；
• 生成并审阅 HarmonyOS API 映射、Python fallback、C adapter、shim 和构建配置；
• 构建目标 wheel 与完整离线 wheelhouse，保留 distribution/import 名称和公共契约；
• 基于真实 TargetProfile 校验架构、wheel tag、SOABI、ELF、DT_NEEDED、符号和 RPATH；
• 通过 HDC、SSH 或自定义 executor 在目标 Python 环境安装、导入并执行行为测试；
• 提供只读 Code Mirage MCP 和 ArkTS Assistant MCP，为 Agent 提供本地证据与官方文档检索；
• 提供 Codex Skill、Claude 入口和结构化决策/迁移报告工具；
• 提供三组对照 benchmark，量化 Pipeline 效果并进行 MCP 消融。

仓库结构

.
├── engine/                 # Python 迁移、构建、验证与 benchmark 核心
│   ├── src/code_mirage/    # fail-closed Pipeline、CLI、MCP、评测器
│   ├── src/py_analyzer/    # Python/native 静态分析与适配生成
│   ├── benchmark/smoke/    # 可执行的本地评测 smoke fixture
│   ├── config/             # SDK、NDK、映射、resolver 与 sandbox 配置
│   ├── docs/               # 使用、HAP、测试与评测文档
│   └── tests/              # 单元、集成、端到端与契约测试
├── arkts-assistant/        # HarmonyOS/ArkTS 文档检索 MCP Server
├── skill/                  # 可移植的 harmony-python-migrate Codex Skill
└── claude/                 # Claude Code 迁移工作流入口

工作原理

锁定源码/目标/测试
        ↓
目标探测与环境校验
        ↓
源码和 native 依赖分析
        ↓
Agent/规则驱动的兼容性适配
        ↓
目标 wheel 与离线依赖闭包构建
        ↓
G0–G3：基线、契约、wheel、ABI 审计
        ↓
G4–G5：目标安装、导入、行为与完整功能验证
        ↓
TARGET_VERIFIED → 原子发布 release/

验证门禁

Gate	验证内容
G0	未修改上游源码的基线测试有效，零测试和意外 skip/xfail 均失败
G1	转换后源码保持文件、模块、public API、依赖、入口点和测试契约
G2	wheel 的 METADATA、WHEEL、RECORD、tag、路径和依赖闭包合法
G3	目标 ELF/架构/SOABI、依赖库、符号、SONAME 和 RPATH 合法
G4	完整 wheelhouse 在干净目标目录离线安装并通过隔离 import sweep
G5	上游、独立行为、运行义务和完整功能测试在目标环境通过

退出状态：

状态	退出码	含义
TARGET_VERIFIED	0	所有必需证据和 G0–G5 均通过
BLOCKED	2	缺少 oracle、覆盖率或仍有未解决 gap
VALIDATION_FAILED	3	构建、审计或行为验证失败
ENVIRONMENT_ERROR	4	SDK、设备、ABI、pip 或工具链环境不完整
TOOL_ERROR	5	配置或工具自身错误

快速开始

1. 安装 Engine

要求 Python 3.10 或更高版本。

cd engine
python -m pip install -e ".[dev,mcp]"
code-mirage --help

2. 探测 HarmonyOS 目标

目标设备必须具有可用的 CPython 与 pip。项目不假设系统默认提供通用 Python 运行时。

code-mirage probe \
  --executor hdc \
  --hdc-target DEVICE_ID \
  --python-executable /data/local/tmp/python/bin/python3 \
  --sdk-path /path/to/harmony-sdk \
  --sysroot /path/to/harmony-sdk/sysroot \
  --api-level EXPECTED_API_LEVEL \
  --output target-profile.json

也可使用 --executor ssh，或通过 code_mirage.executors entry point 注册自定义执行器。

3. 准备不可变测试契约

迁移前需要准备并审阅：

• TestContract：互相独立的上游测试和行为测试；
• FullFeatureContract：完整功能场景、期望值和覆盖率门槛；
• sandbox 配置：OCI 或 bwrap 的固定 rootfs；
• 可选 native source catalog、build lock 和 Python dev bundle。

然后冻结所有输入：

code-mirage lock ./python-project \
  --target target-profile.json \
  --sandbox config/sandbox.toml \
  --test-contract test-contract.toml \
  --full-feature-contract full-feature-contract.json \
  --output migration-input

4. 执行迁移

code-mirage migrate ./python-project \
  --target target-profile.json \
  --input-lock migration-input \
  --sandbox config/sandbox.toml \
  --test-contract test-contract.toml \
  --full-feature-contract full-feature-contract.json \
  --resolver config/resolver.toml \
  --output migration-run

成功产物：

release/
├── wheelhouse/
├── requirements.lock
├── target-profile.json
├── migration-manifest.json
├── validation-report.json
├── validation-report.junit.xml
└── sbom.cdx.json

失败或证据不足时只生成 diagnostics/，不会发布未经验证的 wheelhouse。

5. 重新验证未修改产物

code-mirage verify ./migration-run/diagnostics/<run-id>/<attempt> \
  --executor hdc \
  --hdc-target DEVICE_ID

verify 只重跑现有产物的 G2–G5。源码或 shim 发生变化后必须重新执行 migrate。

Coding Agent 与 Skill

skill/harmony-python-migrate/ 提供完整的 Agent 工作方式：兼容性评估、测试 oracle 构建、迁移、诊断、验证和报告。它要求 Agent 对补丁语义负责，而脚本负责确定性的扫描、 锁定、构建和证据采集。

Skill 可通过以下脚本安装到个人 Codex 环境：

python skill/harmony-python-migrate/scripts/install_portable_skill.py

Claude Code 可使用 claude/harmony-migrate.md 作为迁移入口。

MCP 服务

Code Mirage MCP

Engine 提供只读证据工具，包括 HAP scope 风险评估、NDK 符号查询和迁移运行检查。 必须显式配置允许读取的路径：

$env:CODE_MIRAGE_ROOT = "C:\path\to\repo\engine"
$env:CODE_MIRAGE_ALLOWED_ROOTS = "C:\path\to\workspace"
code-mirage-mcp

该服务不直接修改源码、锁文件或设备状态。

ArkTS Assistant MCP

arkts-assistant/ 提供本地 HarmonyOS/ArkTS 官方文档检索和可选智能问答：

cd arkts-assistant
npm install
npm run build
npm start

详细工具和配置参见 arkts-assistant/README.md。

Benchmark 与 MCP 消融

评测固定使用三组互斥实验：

组别	方案	MCP
直接迁移对照	模型直接迁移	关闭
Pipeline 对照	Code Mirage Pipeline	关闭
MCP treatment	Code Mirage Pipeline	开启

Pipeline 两组使用相同模型、命令、超时、源码和 evaluator，唯一变量为 MCP 开关。 所有组都由同一套外部 evaluator 评分，迁移方法不能自行声明成功。

量化指标包括：

• 迁移成功率、编译通过率、ABI 通过率和安装通过率；
• 测试 run 通过率与 JUnit testcase 通过率；
• 锁定 public callable 的函数覆盖率；
• 语义 probe 通过率和未解决 gap 数；
• 总耗时、真实 provider token usage 和实际 MCP tool 调用数；
• 按纯 Python、native、ctypes、依赖链等 category 的分层结果。

缺失证据显示为 n/a，不会自动补 0 或 100%。本地 smoke 报告具有永久水印，不能作为 模型或 HarmonyOS 真机效果数据。

cd engine
code-mirage benchmark validate --manifest benchmark/smoke/manifest.json
code-mirage benchmark run \
  --manifest benchmark/smoke/manifest.json \
  --output benchmark-smoke-output

正式 manifest、指标分母、telemetry 和报告解释规则详见 engine/docs/evaluation.md。

开发与验证

cd engine
python -m pytest -q
python -m compileall -q src scripts tests benchmark

cd ../arkts-assistant
npm run build

当前仓库验证基线：

• Python 全量测试套件通过，硬件/环境相关跳过项会被显式报告；
• benchmark、CLI 和 resolver telemetry 定向测试通过；
• ArkTS Assistant TypeScript build 通过；
• Python compileall 与 git diff --check 通过。

上述数字是仓库测试结果，不是 Python → HarmonyOS 迁移效果数据。真实迁移成功率、函数 覆盖率、测试通过率、token 效率和 MCP 消融结论必须由生产 benchmark 在统一模型、SDK 和目标设备上运行后生成。

更多文档

• Engine 使用说明
• Python 迁移说明
• 完整功能测试
• HAP 测试载体
• 评测与 MCP 消融
• Harmony Python Migration Skill

License

MIT，见 engine/LICENSE。