Pyzo 鸿蒙 PC 适配全记录：用 Qt 与嵌入式 CPython 重建交互式 Python IDE

user340

272人浏览 · 2026-09-13 20:04:33

user340 · 2026-09-13 20:04:33 发布

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

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

适配开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_pyzo

环境搭建文章：https://blog.csdn.net/weixin_52908342/article/details/161343743

一、为什么选择适配 Pyzo

Pyzo 是一款强调交互式体验的 Python IDE。它不像大型 IDE 那样把大量功能堆叠在工程配置上，而是围绕编辑器、Python Shell 和可插拔工具组织日常工作流。对科学计算、教学演示和快速验证脚本的用户来说，能够在同一个窗口里编写代码、运行文件、观察输出并继续在 Shell 中试验，往往比复杂的工程向导更重要。

HarmonyOS PC 的开发工具生态同样需要这种轻量但完整的编程入口。适配 Pyzo 的意义不只是增加一款文本编辑器，而是验证一条更有代表性的迁移路径：一个由 Python 组织业务、依赖 Qt 桌面窗口、通过外部解释器与通信层驱动 Shell 的传统应用，怎样在 HAP 沙箱中重新获得稳定的编辑、执行、检查和调试能力。

上游 Pyzo 使用纯 Python 编写，通过 pyzo.qt 兼容 PySide 与 PyQt，原有 Shell 则由 KernelBroker 启动外部解释器，并通过 Yoton 传递命令、状态和输出。HarmonyOS PC 上并不存在可直接复用的系统 Python、桌面 Qt 绑定和任意外部解释器环境，因此本次适配保留上游源码作为行为基准，在仓库内新增独立的 harmony_pc/ 工程，先把最常用的 IDE 主链路落到可控的鸿蒙运行时中。

二、先确定迁移边界：保留 Pyzo 的工作方式，重建运行基础

如果把上游 Python 文件、PySide 和动态依赖整体塞入 HAP，表面上接近原工程，实际会同时面对 Qt Python 绑定缺失、动态扩展加载、解释器路径、文件权限和子进程限制。即使窗口偶尔能够启动，也很难保证后续升级和真机运行稳定。

本项目最终采用“Stage 宿主 + Qt Widgets + 嵌入式 CPython”的方案。ArkTS 管理应用生命周期、权限和标准库资源；NODE 类型 XComponent 为 Qt for OpenHarmony 提供原生窗口；Qt C++ 重建编辑器、输出面板和交互入口；CPython 3.12 静态链接进 libentry.so，负责真实的源码编译与执行。

层次	上游 Pyzo	鸿蒙 PC 适配策略
应用入口	Python 启动脚本	Stage 模型 `EntryAbility`
桌面界面	PySide/PyQt + Qt Widgets	Qt for OpenHarmony + Qt Widgets C++
Shell/Kernel	外部解释器、KernelBroker、Yoton	HAP 内嵌 CPython 3.12 与持久交互上下文
编辑能力	Python 侧编辑器组件	自定义 `CodeEditor`、语法高亮和多标签页
文件访问	普通桌面路径	鸿蒙目录授权、QPA 文件能力与应用沙箱
调试	Pyzo 调试工具链	CPython trace hook、断点与单步命令
绘图	工具插件与外部科学计算环境	Qt Charts 轻量数据绘图窗口

这条路线没有修改上游 pyzo/ 的启动方式。传统桌面端仍可按原项目运行，鸿蒙相关代码集中在 harmony_pc/，CPython 源码和目标侧静态库放在 third_party/cpython/。两部分保持清晰边界，后续同步上游时不需要把平台代码散落到原 Python 包中。

三、鸿蒙端整体架构

应用的启动链路如下：

EntryAbility
    ├── 申请文档、下载目录访问权限
    ├── 将 python_stdlib.zip 刷新到应用文件目录
    └── 加载 Index.ets
            └── NODE 类型 XComponent
                    └── Qt for OpenHarmony QPA
                            └── libentry.so
                                ├── PyzoWindow / CodeEditor
                                ├── embedded CPython 3.12
                                ├── Shell、语法检查与调试器
                                └── Qt Charts 绘图

仓库中的主要目录如下：

ohos_pyzo/
├── pyzo/                                  # 上游 Pyzo Python 源码
├── third_party/cpython/                   # CPython 源码与 arm64 静态库
├── README.OpenHarmony_CN.md               # 鸿蒙工程说明
└── harmony_pc/
    ├── AppScope/                          # 应用名称、图标与全局资源
    ├── build-profile.json5                # API 22、产品与签名配置
    ├── qtforharmony_sdk/                  # Qt for OpenHarmony 5.15.12
    ├── scripts/                           # CPython、HAP 构建和审计脚本
    ├── reports/                           # 功能覆盖记录
    └── entry/src/main/
        ├── ets/entryability/              # Ability 生命周期与权限
        ├── ets/pages/                     # XComponent 宿主页面
        ├── resources/rawfile/             # Python 标准库压缩包
        └── cpp/
            ├── pyzo_main.cpp              # 主窗口与 IDE 工作流
            ├── code_editor.cpp            # 行号、断点和搜索标记
            ├── python_syntax_highlighter.cpp
            └── python_runtime.cpp         # CPython、Shell、检查与调试

EntryAbility 在页面加载前准备 python_stdlib.zip，并把实际沙箱路径作为启动参数传给 Qt 侧。每次启动都重新写入标准库资源，避免应用升级后沿用旧压缩包。ArkTS 页面本身只创建全屏 XComponent，真正的桌面界面由 Qt QPA 加载 libentry.so 后构建，这样鸿蒙生命周期与 IDE 业务之间有明确的责任边界。

四、五个核心功能在真机上的实际运行

以下五张图片来自当前适配工程的签名 HAP 在 HarmonyOS PC 真机上的实际运行画面。测试设备为 HUAWEI MateBook Pro（HAD-W32，2in1），设备架构为 arm64-v8a，物理分辨率为 3120×2080，系统版本为 HAD-W24 6.1.0.117(SP78C00E100R13P3)。图片仅做窗口范围裁切，界面与输出内容均来自真机运行。

1. 编辑器与输出区形成完整工作台

鸿蒙版启动后会创建标准 Pyzo 窗口，顶部是常用文件和编辑动作，中间是带行号与 Python 语法着色的多标签编辑器，底部依次为运行输出和 REPL 输入。模式栏明确显示 Python 3 (embedded)，让用户知道当前代码由应用内置解释器执行，而不是依赖设备上的外部 Python。

在这里插入图片描述

编辑器使用自定义 CodeEditor，补齐了行号、当前行、断点、搜索高亮和跳转等基础反馈。文件标签分别保存路径与修改状态；关闭未保存标签时会给出保存、放弃或取消选项。最近文件、会话恢复、自动保存和主题设置通过 QSettings 持久化，避免每次启动都重新整理工作区。

2. Python 文件进入真实 CPython 执行链路

选择 Run 后，当前编辑器内容会交给后台任务，再由嵌入式 CPython 编译执行。真机输出区显示 >>> Run untitled.py 和源码产生的 Hello from Pyzo，说明编辑器、解释器与标准输出捕获已经连成完整闭环。

在这里插入图片描述

运行时使用 PyConfig_InitIsolatedConfig 初始化，关闭用户级 site 目录和外部环境干扰，并显式加入标准库压缩包与应用运行目录。执行真实文件时还会设置 __file__、脚本工作目录和首位 sys.path，因此同目录模块导入与基于脚本路径的文件访问仍能保持 Python 语义。stdout 和 stderr 被统一重定向到内存流，执行结束后再回到界面线程展示。

3. 语法检查给出可见、可定位的结果

Check 操作会使用内置 ast 解析当前源码。截图中默认程序通过检查，输出区显示 Syntax check passed.。如果存在问题，当前实现还会报告语法错误、未使用导入、裸 except、Tab 缩进、超过 88 个字符的长行和行尾空白。

在这里插入图片描述

这里没有把第三方 lint 包全部打进 HAP，而是先提供不依赖外部安装的检查基线。这样规则覆盖范围虽然比完整静态分析工具小，但运行边界明确，在离线设备和全新安装环境中也不会因为缺少 Python 包而失效。

4. 调试和高频动作在窄窗口中仍然可达

桌面窗口进入分屏或普通浮窗后，工具栏没有足够宽度同时展示所有动作。鸿蒙版根据可用宽度保留高频按钮，其余动作收进右侧溢出菜单。真机菜单中可以看到 Run、Stop、Debug、Continue、Step Over、Step Into、Step Out、Check、Tidy、Plot、Theme 和 Settings 等入口，并保留相应快捷键。

在这里插入图片描述

调试器由 CPython trace hook 驱动。解释器命中断点或进入单步状态后，通过线程安全回调把当前行和局部变量交给 Qt 主线程；用户选择继续、单步进入、单步跳过或单步跳出时，再通过互斥量和条件变量唤醒等待中的 Python 任务。Qt 控件始终由界面线程更新，避免调试暂停期间出现随机卡死。

5. 运行结果与完整命令集合可以同时查看

最后一张截图同时保留运行结果和展开后的动作菜单。它验证了窗口宽度受限时，输出区不会被工具栏挤掉，低频操作也不会因为按钮隐藏而失去入口。对 PC 开发工具而言，这类分窗可用性比单纯在最大化窗口里排满按钮更重要。

在这里插入图片描述

Pyzo 的交互式 Shell 与普通脚本共用同一份持久 globals 字典，连续提交的变量、函数和导入不会在每条命令后丢失。输出中符合数字、逗号或空格分隔格式的数据还可以送入 Qt Charts 绘图窗口，最多保留最近 500 个数据点，满足轻量观察脚本输出的需要。

五、适配过程中遇到的主要困难

难点一：Python Qt 应用不能直接等同于 Qt 应用

上游界面由 Python 代码和 PySide/PyQt 绑定创建，Qt for OpenHarmony 提供的是目标侧 C++ SDK，并不会自动提供可在 HAP 中加载的 Python Qt 绑定。继续沿用原入口意味着还要解决绑定模块、动态扩展和大量运行时依赖。当前方案把上游行为作为基准，在 Qt C++ 侧重建核心窗口，先保证最重要的编辑与执行路径可维护。

难点二：Qt 窗口必须嵌入鸿蒙生命周期

Qt 窗口不能绕过 Ability 独立启动。工程先由 EntryAbility 创建和约束主窗口，再加载 NODE 类型 XComponent，最后由 QPA 启动 Qt 应用。默认窗口为 1440×900，最小尺寸为 1180×760；ArkTS 与 Qt 两侧都设置了相应限制，以应对普通窗口、最大化和分屏状态。

难点三：把 CPython 链接进 HAP 只是第一步

解释器能够链接，不代表 import、编码和标准库立即可用。HAP 内的 rawfile 不能直接假设为普通桌面路径，必须先由 ArkTS 读取资源并写入真实沙箱目录，再把路径交给 CPython。运行时还要显式管理模块搜索路径、工作目录、__file__ 和隔离选项，否则开发机路径很容易进入目标配置，最终只在真机上暴露问题。

难点四：CPython GIL 与 Qt 主线程规则必须同时满足

脚本运行和调试不能占用 Qt 界面线程，否则 Stop、Continue 和窗口刷新都会失效。当前实现把任务交给 QtConcurrent，每次进入解释器时获取 GIL，输出和调试状态则通过队列切回主线程。调试暂停还需要让 Python 线程等待命令，同时保持 Qt 事件循环继续运行，这比普通一次性执行更容易出现竞态。

难点五：文件系统要适应授权和沙箱边界

传统桌面 Pyzo 可以直接打开任意可访问路径，鸿蒙应用需要申请文档与下载目录权限，并通过平台文件能力处理外部文件。编辑器内部还要区分显示名称、真实路径、修改状态和最近文件记录。保存采用临时提交语义，减少写入中断后破坏源文件的风险。

难点六：不能把嵌入式解释器写成完整的 Pyzo Kernel 兼容

上游 Pyzo 的优势之一是多解释器、KernelBroker 和 Yoton 通信。当前版本优先完成单个嵌入式 CPython 的稳定闭环，没有把外部解释器和完整多 Kernel 通信描述为已经适配。这样的取舍让编辑、运行、Shell、检查和基础调试先具备真机可用性，也为后续接入新的 transport 保留了清晰位置。

难点七：桌面大屏仍然需要响应式工具栏

HarmonyOS PC 的物理分辨率很高，但应用并不总是最大化。固定工具栏在普通窗口中会截断后半部分动作，因此项目按窗口宽度动态计算可见按钮，并用溢出菜单承接其余命令。真机截图中的菜单不是装饰项，而是保证运行、调试和设置在分屏状态下仍可到达的必要交互。

六、编译、签名、安装与启动

当前工程面向 HarmonyOS SDK API 22，目标设备类型为 2in1 和 tablet，Native ABI 为 arm64-v8a。首次构建前需要准备项目内的 Qt for OpenHarmony SDK、CPython 源码和 DevEco Studio 环境；Qt 环境的具体搭建过程可参考本文开头给出的环境搭建文章。

在仓库根目录执行：

export DEVECO_SDK_HOME="$PWD/harmony_pc/.harmony-sdk"
./harmony_pc/scripts/build-unsigned-hap.sh
./harmony_pc/scripts/audit-unsigned-hap.sh

未签名构建产物位于：

harmony_pc/entry/build/default/outputs/default/entry-default-unsigned.hap

审计脚本会解包 HAP，检查 libentry.so 是否为 ELF64 AArch64、RUNPATH 是否仅使用 $ORIGIN，同时确认 modules.abc、python_stdlib.zip 和必要的 CPython 扩展符号已经进入安装包。构建成功只是第一层结果，产物级审计可以更早发现架构混用和漏打包问题。

真机安装需要为正式 Bundle Name org.pyzo.Pyzo 配置匹配的 HarmonyOS 签名。完成签名后，可执行：

HDC=/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc

"$HDC" list targets
"$HDC" install -r \
  harmony_pc/entry/build/default/outputs/default/entry-default-signed.hap
"$HDC" shell aa force-stop org.pyzo.Pyzo
"$HDC" shell aa start -b org.pyzo.Pyzo -a EntryAbility

本文截图所用的真机 smoke 包复用了当时本机已有的调试签名材料，因此验证包内部临时使用 com.codewith.mu.editor 完成覆盖安装；验证结束后源码清单已恢复为正式的 org.pyzo.Pyzo。正式发布时应生成与 Pyzo 包名一致的 profile，不能把临时 smoke 包当作交付包。

七、当前已覆盖能力与明确边界

当前版本已经形成可以连续使用的 Python IDE 主路径：

多标签新建、打开、保存、另存为、重命名、最近文件和会话恢复；
行号、Python 语法着色、断点、搜索高亮、查找替换、注释、跳转行与缩放；
嵌入式 CPython 3.12、脚本运行、停止、stdout/stderr 与 traceback 展示；
持久交互式 Shell、命令历史和运行上下文保留；
AST 语法检查、基础风格诊断和代码空白整理；
Continue、Step Into、Step Over、Step Out 与局部变量显示；
Qt Charts 轻量绘图、浅色/深色主题、设置持久化与工具栏溢出；
HarmonyOS PC 普通窗口、最大化和分屏场景下的尺寸适配。

仍需明确保留的能力边界包括：

上游 KernelBroker/Yoton 多 Kernel 通信；
外部 Python 解释器发现、选择和隔离环境管理；
原版 Pyzo Tools 与插件系统；
Python 包安装和第三方 Native 扩展管理；
完整调用栈、变量树、条件断点和异常暂停界面；
与完整科学计算发行版等价的第三方包集合。

因此，当前版本更准确的定位是“Pyzo HarmonyOS PC 可用迁移版”。它已经越过静态界面展示阶段，能够完成编辑、运行、查看结果、源码检查和基础调试；依赖多 Kernel、外部解释器或完整插件生态的场景仍应按未适配处理。

八、真机验收结果

本文截图对应同一台 HarmonyOS PC 真机上的主要工作流：应用成功进入 Qt 原生窗口；编辑器显示 Python 源码和语法着色；Run 产生真实标准输出；Check 返回语法检查结果；普通窗口状态下仍能通过溢出菜单访问运行与调试命令。

验收项	结果
设备	HUAWEI MateBook Pro（HAD-W32，2in1）
系统	HAD-W24 6.1.0.117(SP78C00E100R13P3)
架构	aarch64 / arm64-v8a
屏幕分辨率	3120×2080
Qt	Qt for OpenHarmony 5.15.12
Python 运行时	嵌入式 CPython 3.12
HAP 覆盖安装与 EntryAbility 启动	成功
Python 文件运行	成功输出 `Hello from Pyzo`
语法检查	成功输出 `Syntax check passed.`
窗口溢出菜单	运行、调试、检查、绘图与设置动作可访问

验收时只把真机上实际完成的路径记为通过，不把源码中存在某个函数或菜单中出现某个名称直接等同于完整兼容。对开发工具而言，安装、启动、输入、执行、输出和停止必须处在同一条可工作的链路中，适配才真正对用户有意义。

九、总结

Pyzo 的鸿蒙 PC 适配说明，Python 桌面应用迁移并不是换一个启动脚本那么简单。原工程背后的 Qt 绑定、解释器发现、进程模型、通信层和普通文件路径，都需要在 HAP 生命周期与沙箱规则下重新建立边界。

当前工程由 ArkTS 管理窗口、权限和资源准备，由 XComponent 与 Qt QPA 承载桌面界面，再用嵌入式 CPython 提供稳定的执行内核。五张真机截图覆盖了编辑器、Python 运行、语法检查、调试入口和普通窗口下的命令可达性，证明核心 IDE 工作流已经能够在 HarmonyOS PC 上连续完成。

后续工作的重点不应是继续增加表面按钮，而是沿着现有边界接回 Pyzo 更具特色的能力：多 Kernel、外部解释器、Tools、插件与包管理。只有这些能力继续建立在可审计的运行时、线程和文件模型上，鸿蒙版才能在保持稳定性的同时逐步接近上游 Pyzo 的完整体验。