核心功能
Python HarmonyOS Compatibility Checker 是一款专为鸿蒙生态设计的自动化兼容性检测工具，核心能力包括：
1. 智能源码获取
- 优先从GitHub克隆源码，自动识别主流仓库（numpy/numpy、psf/requests等）
- PyPI作为可靠回退源，支持tar.gz/zip源码分发包
2. Windows依赖精准识别 ⭐核心特性
- 深度扫描源代码中的Windows专属API导入：
win32api、pythoncom、pywin32、ctypes.windll等 - 即时拦截：检测到Windows依赖立即标记为不兼容，无需执行测试
- 覆盖动态导入
importlib.import_module和ctypes调用场景
3. 官方测试套件执行
- 优先使用已安装包的测试套件，回退至下载源码
- pytest集成，逐函数级测试统计（
test_file.py::test_func格式） - 智能区分：代码问题 vs 环境权限问题 vs 平台依赖问题
4. 双维度通过率
- 整体通过率：含环境相关失败
- 有效通过率：仅统计代码/平台问题，排除pytest临时目录权限等干扰
5. 多格式报告输出
- Markdown详细报告（中文友好，东八区时间戳）
- JSON机器可读报告
- 原始测试日志保留
- 可选源码留存（
--keep-source）
显著优点
- 高效并行：默认4进程，支持8+ worker处理大批量检测
- 精准预判：Windows依赖静态分析可在秒级拦截明显不兼容包
- 深度验证：不仅检查安装，更通过官方测试验证功能可用性
- CI/CD就绪：GitHub Actions集成示例，支持artifacts上传
- 中文场景优化：报告使用北京时间，包含中文分析建议
潜在局限
- 源码扫描可能遗漏条件导入的Windows代码（如
if sys.platform == 'win32': import win32api） - C扩展包可能因鸿蒙编译链差异失败
- 纯血鸿蒙（HarmonyOS NEXT）安全策略更严格，部分场景受限
- 网络依赖：GitHub/PyPI访问、pip安装均需联网
- 测试覆盖率依赖包作者，无测试包只能验证安装
适合人群
- 鸿蒙生态开发者：迁移Python项目前的依赖评估
- DevOps工程师：CI/CD流程中自动化兼容性门禁
- 企业技术决策者：批量评估技术栈迁移可行性
- 开源维护者：验证包在多平台下的真实兼容性
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| 误报（False Positive） | 环境权限问题被误判为不兼容 | 查看详细报告的Error Classification |
| 漏判（False Negative） | 运行时Windows分支未在静态扫描中触发 | 结合功能测试+代码审查 |
| 源码安全 | 从GitHub/PyPI下载第三方代码 | 使用`--keep-source`保留审计凭证 |
| 执行权限 | 鸿蒙对下载二进制限制较严 | 提前申请sudo权限或改用纯Python包 |
使用场景建议
# 单包快速检测 python scripts/check_compatibility.py xlwings # 批量生产环境检测（推荐） python scripts/check_compatibility.py -w 8 -r requirements.txt --keep-source # CI/CD集成 python scripts/check_compatibility.py -r requirements.txt || echo "存在兼容性风险"