跑不动的 Python 科研软件,怎么在鸿蒙上变成一个真正有用的应用

一、写在前面

开源地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_GSAS-II

欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

本文导读

  • 要解决的问题:GSAS-II 是几十万行 Python + wxPython 的晶体学软件,鸿蒙上既跑不了 Python 也带不动它的 GUI。硬带运行时只会得到一个又大又慢又难验证的东西。
  • 你会读到的技术细节:"本地工作区 + 远端分析服务"双模式的推演过程、六个 /v1/projects 接口的标准化设计、HTTPS + 短时令牌验证通过才落盘的安全链路、系统文件选择器注册自定义 MIME(“晶体数据”)。
  • 本文的实测数据:11 项真机验证、HAP 444 KB;文章也如实记录了仓库缺省 build-profile.json5 的构建问题。
  • 适合谁读:做科研/行业软件、需要在"不能上云"和"跑不动"之间找第三条路的开发者。

这篇文章记录的是把 GSAS-II 这套晶体学分析软件,移植成鸿蒙 PC 工作台的过程。最终落地的应用叫 晶析云,包名 com.crystalcloud.analysis。

其他移植项目分别是本地工具(剪贴板)、本地计算(有限元)、云客户端(沙箱)。这个项目是第四种形态,也是最难取舍的一种:原项目是一个几十万行的 Python 桌面程序,鸿蒙上既跑不了 Python,也带不动它的 GUI。

所以这次移植的核心命题是:

一个跑不动的 Python 科研软件,怎么在鸿蒙上变成一个「有用的」应用?

先给结论:

移植完成,采用了「本地工作区 + 远端分析服务」的双模式:本地可导入晶体数据并管理项目,重计算交给按标准接口对接的分析服务。

验证环境是真实设备:

项值
设备型号HUAWEI MateBook Pro S(MOR-M1)
系统版本HarmonyOS 7.0.0.111(SP15C00E101R9P2)
API 版本26
设备形态2in1
构建工具DevEco Studio 内置 hvigor 6.26.4
SDKHarmonyOS SDK 26.0.0.105

二、项目背景

GSAS-II(https://github.com/AdvancedPhotonSource/GSAS-II)是先进光子源(APS)团队维护的开源晶体学分析套件,广泛用于粉末衍射、单晶衍射、中子衍射的结构精修。

它的技术形态决定了移植难度:

  • 语言:几乎全是 Python,依赖 NumPy/SciPy、matplotlib、wxPython;
  • GUI:wxPython 桌面窗口,大量交互式绘图;
  • 算法:Rietveld 精修、Le Bail 拟合、峰型分析、相鉴定——典型的数值密集型;
  • 输入:CIF(晶体结构)、XY(粉末衍射图谱)、RAW(仪器原始数据)、GPX(GSAS-II 项目文件)。

对鸿蒙来说,这四条里有三条直接判死:

组成部分鸿蒙上能用吗
wxPython GUI❌ 完全没有对应物
Python 解释器 + SciPy⚠️ 理论上可打成 HNP,但几百 MB,启动慢
Rietveld 精修算法⚠️ 纯 Python,就算带进解释器也慢
数据文件格式✅ CIF/XY/RAW/GPX 都是文本,可以解析

所以移植的工程判断只有一条路:

界面和项目状态留在鸿蒙本地,数值计算通过标准化的 HTTP 接口外置。

这就是这套应用「本地工作区 + 分析服务」双模式的由来。


三、总体变化概览

ohos/
├── entry/src/main/
│   ├── module.json5                    仅申请 INTERNET 权限
│   └── ets/
│       ├── pages/Index.ets             全部界面(2277 行)
│       ├── service/
│       │   └── CrystalAnalysisService.ets  分析服务客户端(797 行)
│       ├── model/CrystalModels.ets     数据模型(195 行)
│       ├── store/
│       │   ├── ProjectStore.ets        项目摘要 → Preferences(68 行)
│       │   └── CredentialStore.ets     服务地址/令牌 → AssetStoreKit(97 行)
│       └── entryability/EntryAbility.ets
└── backend/                            Python 参考服务(可独立部署)

技术栈映射:

GSAS-II 原方案晶析云(鸿蒙)
wxPython 桌面 GUIArkUI 原生工作台
Python 直接调算法POST /v1/projects/{id}/refinement 触发远端精修
本地 .gpx 项目文件Preferences 存项目摘要
文件路径参数系统文件选择器(按需授权)
环境变量/配置文件存凭据AssetStoreKit 安全存储

依赖面极小:只申请 ohos.permission.INTERNET,零第三方包。6 个 ArkTS 文件、3476 行。

架构文档里把边界写得很清楚:

ArkTS 页面只处理交互、项目状态和结果展示,数值计算由 CrystalAnalysisService 统一承接。这样可以在不把 Python 解释器和桌面 GUI 带进 HAP 的前提下复用现有算法。


四、原始项目直接跑鸿蒙会遇到什么问题

4.1 Python 运行时是个无底洞

把 CPython + NumPy + SciPy 打成 HNP 是可行的,但代价是:

  • 包体从几百 KB 涨到几百 MB;
  • 冷启动要拉起解释器,几秒钟;
  • Rietveld 精修在纯 Python 下本来就慢,移动端 CPU 更慢。

更要命的是——这只是「能跑」,不是「好用」。科研计算的价值在于精度和结果可复现,把算法搬到一个更难验证的环境里,收益是负的。

4.2 wxPython 界面完全无法移植

GSAS-II 的界面不是简单表单,而是大量交互式绘图(衍射图谱、拟合曲线、峰型标记)。wxPython 这套在鸿蒙上没有任何对应物,必须按鸿蒙的方式重新移植一套。

4.3 科研数据不能默认上传

CIF/XY/RAW 这些是未发表的实验数据,很多还涉及仪器原始格式。一个科研工具如果默认把数据传到云上,是不会有人用的。

4.4 但「纯本地」又没法用

完全本地化意味着要在鸿蒙上重新实现整个 GSAS-II 的算法——那已经不是一个移植项目,而是重造一个科研软件,工程量不可接受。

所以必须在「本地」和「云端」之间找一条中间线,这就是第五章要讲的核心设计。


五、鸿蒙适配核心路径

5.1 第一步:划清「本地做什么」的边界

最终的设计是两层:

层在哪做什么
交互层本地项目空间、数据导入、摘要展示、Rwp 趋势、精修进度
计算层远端CIF 解析、峰型拟合、Rietveld 精修

关键约束写进了导入对话框里:

在这里插入图片描述

仅保存项目摘要,不会自动上传

也就是说:导入数据本身不触发任何网络请求。用户可以先把一堆衍射数据导入、建项目、看摘要,全程离线;等到真正要做精修时,才需要连分析服务。

这个设计把「数据主权」交还给了用户,是这次移植里最重要的一个产品决策。

5.2 第二步:两种工作模式并存

顶栏一直显示当前模式,未连接时是 本地工作区:

在这里插入图片描述

右上角一行小字很关键:本地工作区 · 未连接分析服务。这句话在任何页面都能看到,用户永远不会搞不清楚「我现在算的是本地还是云端」。

「计算服务」这一项进去就是连接配置:

在这里插入图片描述

对话框只有两个字段,但约束很硬:

  • 服务地址:占位符是 https://analysis.example.com
  • 短时访问令牌:令牌不会回显
  • 底部提示:仅支持 HTTPS。令牌验证成功之后才会写入系统安全存储。

这三条拼起来是一个完整的安全设计:

  1. 强制 HTTPS,杜绝明文传输;
  2. 令牌只读不回显,界面上拿不到;
  3. 验证通过才落盘——避免用户输错一个地址,把令牌泄给错误的服务器。

5.3 第三步:凭据与项目数据分开存

CredentialStore 和 ProjectStore 是两个独立文件,职责清晰:

  • CredentialStore(97 行)→ AssetStoreKit,存服务地址和访问令牌;
  • ProjectStore(68 行)→ Preferences,存项目摘要。

架构文档里还专门写了一句:

正式认证流程仍应由甲方登录组件签发短时令牌,不要把真实令牌写进源码或普通 Preferences。

这句话既是给合作方的约束,也是这类科研应用上架时必须交代清楚的合规点。

5.4 第四步:把服务接口标准化

移植能不能被别人复用,取决于接口定义得够不够清楚。ARCHITECTURE.md 里直接给了一张接口表:

接口用途
POST /v1/projects上传 CIF/XY/RAW/GPX 创建项目(JSON + Base64,解码后 ≤ 20 MB)
GET /v1/projects获取当前用户的项目摘要
GET /v1/projects/{id}/summary获取 Rwp、相位数、精修进度
GET /v1/projects/{id}/trend获取拟合趋势与绘图数据
POST /v1/projects/{id}/refinement启动一次精修任务
DELETE /v1/projects/{id}删除项目及应用上传的原始文件

这六个接口基本覆盖了一个晶体分析工作流的全生命周期。移动端只收版本化 JSON,不传二进制中间结果——这样服务端换实现(比如以后用 C++ 另写一版算法)客户端不用改。

仓库里还带了 backend/ 目录,是一个 Python 参考服务,用 GSASIIscriptable.G2Project 读 GPX 摘要,没有装 GSAS-II 也能起健康检查和项目索引接口。

5.5 第五步:文件选择走系统选择器

导入数据时不去扫目录,而是调系统文件选择器:

在这里插入图片描述

这里有两个细节值得说:

  1. 安全访问提示:顶部横幅写着「应用仅可访问您选定的文件或文件夹,无法访问文件夹其他内容。」这是鸿蒙的分区存储模型,应用拿不到整个文件系统;
  2. 格式过滤:底部「文件格式」显示的是 晶体数据——说明应用注册了自定义 MIME 类型,而不是让用户在一堆图片里找 .cif。

设置页里也对应写着「文件选择 / 系统选择器按需授权」——权限模型是对用户透明的。


六、问题困难解决

6.1 困难一:怎么让「跑不动」的项目变得有用

这是这次移植最大的设计题。

三条路都试过推演:

方案包体可用性结论
Python HNP 全本地数百 MB精修慢,界面还得移植一遍❌
纯云客户端很小数据必须上传,科研场景不接受❌
本地工作区 + 远端计算很小离线可管理,联网才精修✅

选第三条的关键理由是:科研数据的所有权和计算的归属可以分开。数据可以留在本地,重计算才出去。

6.2 困难二:界面工作量大,但只有一个页面文件

Index.ets 有 2277 行,全部界面都在这一个文件里。这在前端工程里算「巨文件」了,但对这个项目是有道理的——

  • 三个主页面(工作台、项目空间、分析摘要)共享大量状态(当前项目、Rwp、精修进度);
  • 拆成多个文件就要引入状态管理或 props 层层传递;
  • 单个文件反而让「当前项目」这个核心状态只有一份。

这是个典型的取舍:可读性 vs 状态简单性。作者选了后者。

6.3 困难三:科研指标怎么在卡片里表达

工作台首页的四张卡片不是随便设计的:

在这里插入图片描述

进行中的项目 0    本月数据集 0    最佳 Rwp —    已完成项目 0

其中 Rwp 是 Rietveld 精修的核心质量指标(加权剖面残差,越小越好)。把一个专业指标放进首页卡片,说明这个界面是给懂行的人看的,不是给演示用的。

同理,「项目空间」页面里显示的是「0 个相位 / 尚未精修」:

在这里插入图片描述

「相位(phase)」和「精修(refinement)」都是晶体学的标准术语。界面没有为了「通俗」把它们改成「成分」「优化」——这个判断是对的,目标用户就是科研人员。

6.4 困难四:空态不能糊弄

三个页面在没数据时都没有伪造内容:

页面空态文案
工作台暂无分析项目 / 导入 CIF、XY、RAW 或 GPX 开始
最近数据导入文件后,最近数据会显示在这里
导入对话框最近使用 / 暂无最近导入的文件

而且工作台的绿卡片上明确标着 0% 已完成 和 —(而不是 0)表示「无数据」。— 和 0 的区分在科研场景里很重要:一个是「还没测」,一个是「测出来是零」。


七、构建与运行方式

7.1 环境

  • DevEco Studio(内置 hvigor + SDK)
  • HarmonyOS SDK API 26(本机 26.0.0.105)
  • 无需 Python、无需 native 工具链

7.2 构建

cd ohos
ohpm install
hvigorw assembleHap --mode module -p product=default -p buildMode=debug

注:仓库原本只提供 build-profile.template.json5 和 entry/build-profile.template,克隆后需要先生成 build-profile.json5 才能构建。移植验证时补上了这两份配置(签名留空,便于任何人用自己的证书)。

产物:

entry-default-unsigned.hap   444 KB

纯 ArkTS,构建约 3 秒。

7.3 签名与安装

scripts/sign_hap.sh(环境变量方式)或 DevEco 自动签名。调试 profile 绑定设备 UDID,换设备需重新自动签名,否则报 9568423 device is unauthorized。

hdc shell aa start -b com.crystalcloud.analysis -a EntryAbility

7.4 部署分析服务(可选)

如果要跑真实精修,需要部署 backend/ 里的参考服务:

CRYSTALCLOUD_TOKEN=local-dev-token \
  PYTHONPATH=. python -m ohos.backend.server

然后在应用里「设置与连接 → 计算服务」填入 HTTPS 地址和令牌。


八、适配成果

8.1 工作台

在这里插入图片描述

左侧是「工作区」和「系统」两组导航,右侧是四张指标卡 + 当前项目卡 + 最近数据。底部常驻 本地工作区 状态。

8.2 项目空间

在这里插入图片描述

一屏里同时给出「全部项目列表」和「当前选择」两个视角:左边看全集,右边看当前项目的相位数和精修状态。右上角「共 0 个项目 · 已完成 0」是全局计数。

8.3 设置与连接

在这里插入图片描述

六个入口分成两组:

  • 工作区:计算服务(本地/远端切换)、文件选择、消息提示
  • 关于应用:隐私与数据、开源与致谢、版本信息(1.0.0 · OpenHarmony)

这个结构对一个科研工具来说是够用的——没有堆砌设置项,把「数据来源」和「合规信息」放在了最显眼的位置。

8.4 工程量

指标数值
ArkTS 源文件6 个
代码行数3476 行
主界面Index.ets 2277 行
服务客户端CrystalAnalysisService.ets 797 行
第三方依赖0
权限数量1(INTERNET)
HAP 体积444 KB

8.5 同类移植项目横向对比

ClipNest澜析工程沙箱控制台晶析云
类型本地工具本地计算云客户端混合模式
ArkTS 行数4782341758623476
随包原生产物017 MB00
HAP 体积752 KB19 MB892 KB444 KB
核心难点权限与自写入回环进程模型双端点 API 封装本地/远端边界

九、功能验证结果

9.1 已在真机验证

功能结果验证方式
构建与安装✅444 KB HAP 产出,hdc install 成功
应用启动✅进程稳定运行,窗口正常渲染
工作台首页✅四张指标卡、当前项目卡、最近数据均正确
项目空间✅列表 + 当前选择双栏,空态正确
分析摘要入口✅按钮存在并可进入
设置与连接✅六个入口全部渲染,版本信息 1.0.0 · OpenHarmony 正确
模式标识✅顶栏与底栏均显示「本地工作区 · 未连接分析服务」
计算服务配置✅HTTPS 地址 + 短时令牌对话框正常,提示「仅支持 HTTPS」
导入数据对话框✅四种格式说明、最近使用空态、安全提示均正确
系统文件选择器✅正常拉起,显示「晶体数据」格式过滤与分区存储提示
权限配置✅仅声明 INTERNET,未触发额外授权弹窗

9.2 未验证(需要部署分析服务)

功能说明
连接分析服务需要一个真实的 HTTPS 端点 + 有效令牌,本次未部署
项目创建与上传依赖服务端 POST /v1/projects
Rwp 与精修趋势依赖服务端 /summary 与 /trend 接口
启动精修任务依赖 /refinement 接口
实际导入晶体文件设备上没有 .cif/.xy/.raw/.gpx 样本,未走完导入
凭据写入 AssetStoreKit需要一次成功连接才能验证落盘路径

9.3 已知限制

限制说明
精修计算不在本地必须部署分析服务,或对接甲方已有服务
需要自备 HTTPS 端点应用强制 HTTPS,本地调试需自签证书
仓库缺省构建配置原仓库只有 template,需先生成 build-profile.json5
调试 profile 绑 UDID换设备需重新自动签名

十、上架复盘:审核不通过怎么办

移植跑通只是第一关。上架审核看的是另一套东西:用户会不会把这款应用误认为上游官方版,或者误认为换皮抄袭。名称、图标、截图、描述、权限、实际行为,只要有一项对不上,就可能被驳回。

10.1 名称和图标:开源许可不等于品牌许可

这是最容易踩的坑。很多人觉得“这是开源软件,保留原名和原图标很正常”,但 MIT/Apache/GPL 给的是版权许可,不是商标许可。审核看到“应用名和上游一样、图标是上游 Logo 换色、截图里还有上游品牌”,就会按“冒用/抄袭”处理。典型的三连击是:应用名直接沿用上游、图标只把颜色换一下、截图里还带着上游 Logo——即使代码全部重写,也会被判定为冒用。

我们的处理原则:

  • 应用名改成独立品牌,包名不带上游商标;
  • 图标重画,不复用、不改色、不截取上游 Logo;
  • 截图、启动图、关于页不出现上游 Logo,只保留文字致谢;
  • 关于页写明“基于 GSAS-II 移植,非官方发行”,并保留上游 LICENSE/NOTICE;
  • 如果被质疑,提交《品牌与素材来源说明》:改名前后对照、图标设计稿、上游许可证、代码差异、真机录屏。

10.2 被判定“抄袭/雷同”时,交什么证据

只回“这是开源软件”通常没用。按这个顺序给材料:

  1. 上游仓库地址和 LICENSE 原文;
  2. 本仓库与上游的差异清单(UI 重写、平台层、构建脚本);
  3. 品牌变更记录(旧名→新名、旧图标→新图标);
  4. 功能差异说明(哪些是鸿蒙特有、哪些上游没有);
  5. 真机录屏,证明不是套壳。

如果确实沿用了上游 UI,先改再申诉;审核一般不看“开源所以可以一样”的解释。

10.3 这个项目的高频驳回点

  • 数据去哪:科研数据敏感,隐私政策要写清“只上传到用户自己配置的服务”,默认空态,不预置假项目。
  • 审核机没有后端:准备一个可用的测试服务或内置演示模式,否则会被判“功能不可用”。
  • 品牌:晶析云是独立品牌,关于页写“基于 GSAS-II,非官方”,不出现上游 Logo。

10.4 驳回后的处理顺序

先分类,再动手。审核意见通常落在六类:名称/图标/品牌、隐私与权限、功能与描述不符、技术(签名/包名/架构/体积/崩溃)、内容合规、资质(软著/授权书/备案)。

  • 一次只改一类,别在同一个版本里混改;
  • 回复时逐条对应:版本号 + 审核意见 + 改了什么 + 怎么验证;
  • 测试账号/令牌在复审前重置,写进审核备注;
  • 截图必须来自当前版本真机,不能用设计稿;
  • 换正式证书后重新打包,不要用调试签名送审;
  • 被拒后先回一条“已收到,逐条说明”,再提新包,避免被判定骚扰;
  • 上架材料提前备齐:软著/授权书、隐私政策公网 URL、测试账号、真机截图、开源许可证与 NOTICE。

回复可以按这个模板:

您好,针对第 X 条“……”:我们已在版本 A.B.C 中修改:1)……;2)……。验证路径:……。相关材料见附件/链接。

一句话:上架不是“把包传上去”,而是把“这不是官方版、也不是换皮”这件事,用名称、图标、截图、代码和材料同时证明一遍。

十一、结语

这次移植最特别的地方是:它不是「把功能搬过来」,而是「重新划分计算边界」。

四点体会:

  1. 不是所有项目都能整体移植,学会切分更重要。GSAS-II 的 Python + wxPython 组合在鸿蒙上无解,硬带运行时只会得到一个又大又慢又难验证的东西。把「交互」和「计算」切开,各自放到最合适的地方,才是可行解。

  2. 科研工具的第一原则是数据主权。导入对话框那句「仅保存项目摘要,不会自动上传」,比任何功能都重要。用户可以离线建项目、看摘要,联网时才动用云端算力。

  3. 接口标准化决定移植能不能被复用。ARCHITECTURE.md 里那六个 /v1/projects 接口,让服务端可以随时换实现而客户端不动。这是把一次性移植变成长期工程的关键。

  4. 专业术语不要为了「通俗」而替换。Rwp、相位、精修——目标用户就是科研人员,改成「质量分」「成分」「优化」反而让人怀疑专业性。

444 KB 的包体,装着一个完整的晶体分析工作台。它自己不做数值计算,但它把「用户怎么用一个跑不动的科研软件」这个问题回答清楚了。


一句话:不是所有移植都要"整体搬"——把计算边界切开,往往才是正解。

相关链接

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐