@hmos-library-adapter/fast 0.0.17-beta.0 → 0.0.17-beta.2

package/node_modules/@ohos-agent/pc-adapter/skills/harmonyos-pc-resources/references/contribute/develop-guide//351/270/277/350/222/231/345/272/224/347/224/250/345/265/214/345/205/245Python/350/277/220/350/241/214/346/227/266-ArkTS/344/270/216CPython/346/267/267/345/220/210/345/274/200/345/217/221/345/256/236/346/210/230.md

@@ -0,0 +1,617 @@
+# 在鸿蒙应用中嵌入 Python 运行时：ArkTS + CPython 混合开发实战
+
+> 鸿蒙原生开发使用 ArkTS，但 Python 在数据科学、自动化脚本、测试工具等领域有着不可替代的优势。本文介绍如何在一个鸿蒙应用中嵌入完整的 CPython 运行时，通过 Python C API 在 Native 层直接启动 Python 解释器并执行 Python 脚本，让 ArkTS 负责应用壳，Python 负责业务逻辑。
+
+---
+
+## 一、为什么要在鸿蒙上跑 Python
+
+Python 生态拥有海量成熟的三方库和脚本工具。在鸿蒙应用中嵌入 Python 运行时的场景包括：
+
+| 场景 | 说明 |
+|------|------|
+| **Python 脚本工具迁移** | 将已有的 Python 自动化脚本、数据处理工具直接搬到鸿蒙上运行 |
+| **NumPy/SciPy 科学计算** | 利用 Python 生态的科学计算能力，在鸿蒙端完成数据分析 |
+| **跨平台业务逻辑** | 同一份 Python 代码在 Windows/Linux/macOS/鸿蒙上行为一致 |
+| **动态化能力** | Python 脚本可以放在 resfile 中动态替换，无需重新编译应用 |
+| **AI 推理预处理** | 使用 Python 进行数据预处理，再交给原生模型推理 |
+
+与 Java 方案不同，Python 的嵌入方式更加轻量——**不需要虚拟机，只需共享库 `libpython3.12.so` 和标准库文件**。
+
+---
+
+## 二、两种集成方案与整体架构
+
+在鸿蒙应用里跑 Python 有两种落地形态，**先按场景选型，再看架构**：
+
+| 维度 | 方案 A：子进程调用（推荐） | 方案 B：进程内嵌入（进阶） |
+|------|--------------------------|--------------------------|
+| 集成方式 | 把 Python 打成 **HNP**，C++ 用 `forkpty`/`fork`+`exec` 拉起 `python` 子进程 | C++ 链接 `libpython3.12.so`，用 Python C API 在本进程内启动解释器 |
+| 复杂度 | 低（无需管解释器生命周期/GIL） | 高（`Py_Initialize`/`Py_Finalize`、GIL、崩溃传导都要管） |
+| 通信 | 命令行参数入、**stdout（约定 JSON）** 出 | `PyObject` 直接互传，共享内存 |
+| 隔离性 | 强：Python 崩溃不拖垮 ArkTS UI 进程 | 弱：同进程，段错误连带崩 UI |
+| 三方库（Pillow/NumPy） | 打进 HNP 随包分发，自包含 | 放 `libs/.../site-packages`，需与嵌入 CPython 的 ABI 对齐 |
+| 适用 | 脚本工具、数据/图像处理、快速原型、AI 预处理 | 需与 ArkTS 高频双向调用、对 IPC 开销敏感 |
+
+> **选型建议**：绝大多数“用某个 Python 库做一段计算/处理”的需求走**方案 A**——更简单、更稳、库随 HNP 自包含；只有需要与 ArkTS 高频双向调用时才上**方案 B**。
+> 本指南 **§三–§六 以方案 B（进程内嵌入）为主线详解**（展示最完整的 Python C API 细节），**§七 给出方案 A（子进程）的实现要点**；端到端可复制样例见 **pc-knowledge-base** 的 `adaptation/鸿蒙PC-PixelTune-子进程Python应用.md`（PixelTune 用方案 A 在鸿蒙 PC 做 Pillow 图像处理）。**两方案均有真机实证的可构建工程模板**：`ohpt-agent scaffold --kind python-app-embedded`（方案 B）/ `--kind python-app-subprocess`（方案 A）一键生成（GUI 库上屏另有 python-gui-owb）。
+
+**方案 A 架构（子进程 + HNP）：**
+
+```
+┌───────────────────────────────────────────────────────┐
+│                 HarmonyOS 应用 (.hap)                  │
+│  [ArkTS UI] ──NAPI execSync(cmd)──▶ [C++ 桥 libxxx.so] │
+│                                          │ forkpty/exec │
+│                                          ▼              │
+│         [python 子进程  ◀ HNP: 解释器+标准库+Pillow]    │
+│                     │ 运行 rawfile/*.py                 │
+│                     ▼                                   │
+│           stdout(约定 JSON) ──JSON.parse──▶ ArkTS       │
+└───────────────────────────────────────────────────────┘
+```
+
+**方案 B 架构（进程内嵌入，本文 §三–§六 详解）：**
+
+```
+┌──────────────────────────────────────────────────┐
+│           HarmonyOS 应用 (.hap)                   │
+│                                                   │
+│  ┌──────────────────────────────────────────┐     │
+│  │  ArkTS 层                                │     │
+│  │  - XXXAbility (应用生命周期)              │     │
+│  │  - XXXLauncherStage (多实例管理)          │     │
+│  │  - UI 界面                               │     │
+│  └─────────────────┬────────────────────────┘     │
+│                    │                               │
+│  ┌─────────────────▼────────────────────────┐     │
+│  │  C++ 启动层 (libxxxlauncher.so)          │     │
+│  │  - main() 入口                            │     │
+│  │  - Python C API 调用                      │     │
+│  │  - Py_Initialize() → PyRun_SimpleFileEx()│     │
+│  └─────────────────┬────────────────────────┘     │
+│                    │ Python C API                  │
+│  ┌─────────────────▼────────────────────────┐     │
+│  │  Python 运行时层                          │     │
+│  │  ┌──────────────────────────────────┐    │     │
+│  │  │  CPython 3.12 (libpython3.12.so) │    │     │
+│  │  │  + 标准库 (Python/lib/python3.12) │    │     │
+│  │  │  + 三方库 (site-packages/)        │    │     │
+│  │  │  + 用户 Python 脚本 (resfile/)    │    │     │
+│  │  └──────────────────────────────────┘    │     │
+│  └──────────────────────────────────────────┘     │
+│                                                   │
+│  entry/libs/arm64-v8a/                            │
+│  ├── Python/lib/python3.12/  # Python 标准库      │
+│  ├── libpython3.12.so.1.0   # CPython 运行时      │
+│  └── ...                                          │
+└──────────────────────────────────────────────────┘
+```
+
+**方案 B 核心设计：通过 Python C API 嵌入解释器**——不启动独立进程，直接在 Native 层 `Py_Initialize()` 初始化解释器、`PyRun_SimpleFileEx()` 执行脚本，C++ 与 Python 同进程共享内存。方案 A（子进程调用）的实现见 §七。
+
+---
+
+## 三、项目结构
+
+```
+PythonForArkUI/
+├── AppScope/
+│   └── app.json5                         # 应用全局配置
+├── entry/
+│   ├── src/main/
+│   │   ├── cpp/
+│   │   │   ├── CMakeLists.txt            # ⭐ C++ 构建配置（链接 Python）
+│   │   │   ├── xxxlauncher.cpp           # ⭐ 核心：Python 启动器
+│   │   │   ├── hilog-easy.h              # 日志工具头文件
+│   │   │   └── hilog-easy.c              # 日志工具实现
+│   │   ├── ets/
+│   │   │   ├── ability/
+│   │   │   │   └── XXXAbility.ets        # ⭐ 应用入口 Ability
+│   │   │   ├── abilitystage/
+│   │   │   │   └── XXXLauncherStage.ets  # 多实例管理
+│   │   │   └── pages/
+│   │   │       └── XXXIndex.ets          # 主页面
+│   │   ├── resources/
+│   │   │   └── resfile/
+│   │   │       └── my-app/               # ⭐ Python 脚本目录
+│   │   │           ├── main.py           # 主脚本入口
+│   │   │           ├── module_a.py
+│   │   │           ├── module_b.py
+│   │   │           └── utils/            # 工具模块
+│   │   └── module.json5
+│   └── build-profile.json5
+├── other/
+│   └── site-packages/                    # Python 三方库
+│       └── ...
+└── build-profile.json5
+```
+
+---
+
+## 四、关键配置
+
+### 4.1 module.json5
+
+```json5
+{
+  "module": {
+    "type": "entry",
+    "deviceTypes": ["2in1"],
+    "extractNativeLibs": true,  // ⭐ 必须为 true！
+    "srcEntry": "./ets/abilitystage/XXXLauncherStage.ets",
+    "abilities": [{
+      "name": "XXXAbility",
+      "srcEntry": "./ets/ability/XXXAbility.ets",
+      "launchType": "specified"  // 支持多实例
+    }]
+  }
+}
+```
+
+与 Java 方案一样，`extractNativeLibs: true` 是关键配置。CPython 的 `libpython3.12.so` 需要 `dlopen` 动态加载，必须解压到文件系统。
+
+### 4.2 build-profile.json5
+
+```json5
+{
+  "buildOption": {
+    "nativeLib": {
+      "collectAllLibs": true  // 收集 libs/ 下所有 SO
+    },
+    "externalNativeOptions": {
+      "path": "./src/main/cpp/CMakeLists.txt",
+      "cppFlags": "--std=c++17"
+    }
+  }
+}
+```
+
+### 4.3 CMakeLists.txt — 链接 Python 运行时
+
+```cmake
+cmake_minimum_required(VERSION 3.5.0)
+project(PythonApp)
+
+# Python 头文件和库目录
+set(PYTHON_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/include/python3.12)
+set(PYTHON_LIBRARIES_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../../libs/${OHOS_ARCH})
+set(PYTHON_LIBRARIES -l:libpython3.12.so.1.0)
+
+# 构建启动器
+add_library(xxxlauncher SHARED xxxlauncher.cpp hilog-easy.c)
+target_link_libraries(xxxlauncher PUBLIC libace_napi.z.so libhilog_ndk.z.so)
+
+# 链接 Python
+target_include_directories(xxxlauncher PRIVATE ${PYTHON_INCLUDE_DIR})
+target_link_directories(xxxlauncher PRIVATE ${PYTHON_LIBRARIES_DIR})
+target_link_libraries(xxxlauncher PRIVATE ${PYTHON_LIBRARIES})
+```
+
+**关键点：**
+- Python 头文件 (`python3.12.h`) 放在 `cpp/thirdparty/include/python3.12/`
+- Python SO 库 (`libpython3.12.so.1.0`) 在 `entry/libs/arm64-v8a/`
+- 使用 `-l:` 前缀精确指定 SO 文件名（包含版本号）
+
+---
+
+## 五、方案 B 核心实现详解（进程内嵌入）
+
+### 5.1 xxxlauncher.cpp — Python 启动器
+
+这是整个方案的**最核心文件**，仅有约 50 行有效代码，展示了如何通过 Python C API 在鸿蒙应用中启动 Python：
+
+```cpp
+#include <string>
+#include <Python.h>
+
+static std::string gPythonAppPath = 
+    "/data/storage/el1/bundle/entry/resources/resfile/my-app/main.py";
+
+// Python 运行时生命周期管理（RAII 模式）
+struct PythonRuntimeGuard {
+    PythonRuntimeGuard() {
+        if (!Py_IsInitialized()) {
+            // 1. 设置 PYTHONHOME 指向应用内的 Python 环境
+            setenv("PYTHONHOME", "/data/storage/el1/bundle/libs/arm64/Python", 1);
+            
+            // 2. 初始化 Python 解释器
+            Py_Initialize();
+            
+            if (Py_IsInitialized()) {
+                shouldFinalize = true;
+            }
+        }
+    }
+    
+    ~PythonRuntimeGuard() {
+        if (shouldFinalize) {
+            Py_Finalize();  // 清理 Python 运行时
+        }
+    }
+    bool shouldFinalize { false };
+};
+
+int main(int argc, char *argv[]) {
+    // 3. 打开 Python 脚本文件
+    FILE *pyFile = fopen(gPythonAppPath.c_str(), "r");
+    if (!pyFile) {
+        return 1;
+    }
+
+    // 4. 初始化 Python 运行时（RAII 自动管理生命周期）
+    PythonRuntimeGuard pyRuntime;
+    
+    // 5. 设置 sys.argv（让 Python 脚本能获取命令行参数）
+    wchar_t *pyArgv0 = Py_DecodeLocale(gPythonAppPath.c_str(), NULL);
+    PySys_SetArgvEx(1, &pyArgv0, 1);
+
+    // 6. 执行 Python 脚本
+    int ret = PyRun_SimpleFileEx(pyFile, gPythonAppPath.c_str(), 1);
+    
+    PyMem_RawFree(pyArgv0);
+    return ret;
+}
+```
+
+**整个流程就 6 步：**
+
+```
+setenv("PYTHONHOME", ...)   → 设置 Python 运行环境路径
+Py_Initialize()             → 初始化 Python 解释器
+PySys_SetArgvEx()           → 设置 sys.argv
+PyRun_SimpleFileEx()        → 执行 Python 脚本
+Py_Finalize()               → 清理 Python 运行时（RAII 析构时自动调用）
+```
+
+**设计亮点：`PythonRuntimeGuard` 使用 RAII 模式管理 Python 生命周期**，确保即使脚本执行异常退出，`Py_Finalize()` 也会被正确调用。
+
+### 5.2 Python 脚本路径
+
+Python 脚本放在 `resfile` 目录下，安装后的路径为：
+
+```
+/data/storage/el1/bundle/entry/resources/resfile/
+```
+
+在 C++ 中硬编码此路径即可定位脚本文件。你也可以通过 Ability 上下文动态获取此路径。
+
+### 5.3 PYTHONHOME 配置
+
+Python 运行时需要知道标准库的位置。通过 `setenv("PYTHONHOME", ...)` 设置：
+
+```
+/data/storage/el1/bundle/libs/arm64/Python
+```
+
+这个目录下需要包含完整的 Python 标准库：
+
+```
+entry/libs/arm64-v8a/Python/
+└── lib/
+    └── python3.12/
+        ├── __future__.py
+        ├── abc.py
+        ├── collections/
+        ├── email/
+        ├── html/
+        ├── http/
+        ├── io.py
+        ├── json/
+        ├── logging/
+        ├── os.py
+        ├── pathlib.py
+        ├── re.py
+        ├── subprocess.py
+        ├── sysconfig.py
+        ├── urllib/
+        └── ... (完整标准库)
+```
+
+### 5.4 XXXAbility.ets — 应用入口
+
+ArkTS 层的 Ability 负责应用生命周期和 Native 层的启动：
+
+```typescript
+export default class XXXAbility extends UIAbility {
+  onWindowStageCreate(windowStage) {
+    // 加载页面
+    windowStage.loadContent(this.loadContentUrl, localStore).then(() => {
+      // 通知 Native 桥接层窗口已创建
+      // （具体的桥接方式取决于你的应用架构）
+    })
+    
+    // 启动 Native 应用（包含 Python 运行时）
+    // 通过 NAPI 调用 libxxxlauncher.so 的 main() 函数
+  }
+}
+```
+
+### 5.5 XXXLauncherStage.ets — 多实例管理
+
+`AbilityStage` 用于管理 Ability 的多实例行为：
+
+```typescript
+export default class XXXLauncherStage extends AbilityStage {
+  onAcceptWant(want) {
+    // 根据 instanceKey 返回不同的 Ability 实例标识
+    // 实现多窗口/多实例支持
+    let instanceKey = want.parameters?.instanceKey;
+    if (instanceKey) return instanceKey;
+    // 默认实例标识
+  }
+}
+```
+
+---
+
+## 六、纯 Python 脚本开发指南
+
+上面的项目展示了一个完整案例。如果你只需要运行**纯 Python 脚本**（不涉及图形化），流程更加简单：
+
+### 6.1 准备 Python 运行时
+
+从鸿蒙 Python 预编译包（`python312.hnp`）中获取：
+
+```
+# 1. 头文件 → 用于 C++ 编译
+python312.hnp/python-wheel-3.12/include → entry/src/main/cpp/thirdparty/include/
+
+# 2. Python SO 库 → 用于运行时链接
+python312.hnp/python-wheel-3.12/lib → entry/libs/arm64-v8a/
+
+# 3. Python 标准库 → 运行时 import
+移动 entry/libs/arm64-v8a/python3.12 → entry/libs/arm64-v8a/Python/lib/python3.12
+```
+
+### 6.2 编写 C++ 启动器
+
+核心就是通过 Python C API 启动解释器并执行脚本：
+
+```cpp
+#include <Python.h>
+
+int main(int argc, char *argv[]) {
+    std::string scriptPath = "/data/storage/el1/bundle/entry/resources/resfile/my_script.py";
+    
+    setenv("PYTHONHOME", "/data/storage/el1/bundle/libs/arm64/Python", 1);
+    Py_Initialize();
+    
+    FILE *f = fopen(scriptPath.c_str(), "r");
+    int ret = PyRun_SimpleFileEx(f, scriptPath.c_str(), 1);
+    
+    Py_Finalize();
+    return ret;
+}
+```
+
+### 6.3 编写 Python 脚本
+
+将你的 Python 脚本放入 `resfile` 目录：
+
+```
+entry/src/main/resources/resfile/
+└── my_script.py
+```
+
+```python
+#!/usr/bin/env python3
+"""一个纯 Python 示例脚本"""
+
+import os
+import sys
+import json
+
+def main():
+    print(f"Python {sys.version} running on HarmonyOS!")
+    print(f"Platform: {sys.platform}")
+    print(f"CWD: {os.getcwd()}")
+    
+    # 你可以使用标准库中的所有功能
+    data = {
+        "message": "Hello from Python on HarmonyOS",
+        "pid": os.getpid(),
+        "env": dict(os.environ)
+    }
+    print(json.dumps(data, indent=2, ensure_ascii=False))
+
+if __name__ == "__main__":
+    main()
+```
+
+### 6.4 三方库支持
+
+Python 的 `site-packages` 机制完全可用。将三方库放入：
+
+```
+entry/libs/arm64-v8a/Python/lib/python3.12/site-packages/
+```
+
+**注意**：包含 C 扩展的三方库（如 NumPy）需要是针对鸿蒙 aarch64 编译的版本。纯 Python 库（如 `requests`、`PyYAML` 等）可以直接使用，无需重新编译。
+
+**OpenBLAS 二进制修补**：某些预编译包中的 OpenBLAS（NumPy 的底层依赖）可能存在指令集兼容问题，需要进行二进制修补：
+
+```bash
+openblas_so="entry/libs/arm64-v8a/Python/lib/python3.12/site-packages/numpy.libs/libopenblasp-*.so"
+printf '\x1f\x20\x03\xd5' | dd of=$openblas_so bs=1 seek=2464508 conv=notrunc
+```
+
+### 6.5 C++ 与 Python 双向通信
+
+如果需要 C++ 和 Python 之间的数据传递，可以使用更灵活的 API：
+
+```cpp
+// 执行 Python 代码字符串并获取返回值
+PyObject *result = PyRun_String(
+    "import os; os.getcwd()",      // Python 表达式
+    Py_eval_input,                  // eval 模式
+    global_dict, local_dict
+);
+// 将 PyObject 转为 C 字符串
+const char *cwd = PyUnicode_AsUTF8(result);
+
+// 调用 Python 函数
+PyObject *module = PyImport_ImportModule("my_module");
+PyObject *func = PyObject_GetAttrString(module, "process_data");
+PyObject *args = Py_BuildValue("(si)", "hello", 42);
+PyObject *ret = PyObject_CallObject(func, args);
+```
+
+---
+
+## 七、方案 A 实现：子进程调用（HNP + shell exec）
+
+方案 A 不链接 `libpython`，而是把 **Python 解释器 + 标准库 + 三方库（如 Pillow）整体打成 HNP** 随应用分发；运行时由 C++ 桥拉起 `python` 子进程执行脚本，用**标准输出（约定 JSON）** 回传结果。它更简单、更稳，是脚本/数据处理类需求的推荐路径。
+
+> 端到端可复制样例（完整 CMake / ArkTS / Python / 权限清单 / 沙箱路径）见 **pc-knowledge-base** 的 `adaptation/鸿蒙PC-PixelTune-子进程Python应用.md`。本节只给可迁移的骨架与协议。
+
+### 7.1 打包 Python 为 HNP
+
+把解释器与三方库装进一个目录再打成 HNP（`hnpcli pack`），HNP 随 HAP 分发、安装时解压到应用私有 HNP 目录：
+
+```bash
+# 目录内备好 python 可执行 + 标准库，装好三方库（源用社区 PyPI）
+./python3.12 -m pip install Pillow \
+  --index-url https://pypi.cnb.cool/OpenHarmonyPCDeveloper/pypi/-/packages/simple
+hnpcli pack -i <python_dir> -o <out_dir>   # 产出 python.hnp（放 hnp/arm64-v8a/）
+```
+
+### 7.2 C++ 桥：拉起子进程并采集 stdout
+
+用 `forkpty`（或 `fork`+管道）起 `python` 子进程，`poll` 采集输出。要点：子进程里显式 `setenv("HOME", ...)`，经 `/bin/sh -c` 执行以继承 HNP 的 PATH：
+
+```cpp
+// 极简骨架；生产版用 forkpty + 清洗 PTY 控制字符，见 PixelTune 案例
+ExecResult shellExecSync(const std::string& cmd) {
+    int masterFd;
+    pid_t pid = forkpty(&masterFd, nullptr, nullptr, nullptr);
+    if (pid == 0) {                        // 子进程
+        setenv("HOME", "/storage/Users/currentUser", 1);
+        execl("/bin/sh", "sh", "-c", cmd.c_str(), nullptr);
+        _exit(127);
+    }
+    // 父进程：poll(masterFd) 读到子进程退出，返回聚合后的 stdout
+}
+```
+
+### 7.3 NAPI 暴露给 ArkTS
+
+把 `shellExecSync` 包成一个同步 NAPI 方法 `execSync(cmd): string`（模块名随库）：
+
+```cpp
+static napi_value ExecSync(napi_env env, napi_callback_info info) {
+    // 取 args[0] 的 cmd 字符串 → shellExecSync(cmd) → napi_create_string_utf8 返回 output
+}
+```
+
+### 7.4 接口契约：argv 子命令 + JSON stdout
+
+Python 脚本按 `sys.argv` 分发子命令，结果用 **`print(json.dumps(...))`** 输出，ArkTS 侧 `JSON.parse` 解析。这层“argv 入、JSON 出”的约定就是子进程方案的接口——**把任意 Python 库的能力封装成一组命令即可复用到别的库**：
+
+```python
+# image_processor.py
+import sys, json
+if __name__ == '__main__':
+    cmd = sys.argv[1]
+    if cmd == 'compress':
+        # ... 用 Pillow 处理 sys.argv[2], sys.argv[3] ...
+        print(json.dumps({"success": True, "output": out_path}))
+```
+
+### 7.5 ArkTS 侧：释放脚本 → 调用 → 解析
+
+脚本随应用打进 `rawfile/`，首次运行拷到可执行的 `filesDir`，再拼命令调用：
+
+```typescript
+import shellNative from 'libxxx_native.so';
+
+const script = this.context.filesDir + '/image_processor.py';   // 由 rawfile 拷出
+const cmd = `python "${script}" compress "${input}" "${output}"`;
+const out: string = shellNative.execSync(cmd);
+const r = JSON.parse(out.trim());
+```
+
+### 7.6 权限（module.json5 ACL）
+
+子进程 + HNP 需要以下 ACL（较激进，需评估必要性）：`ALLOW_EXTERNAL_NATIVE_CODE`、`LOAD_INDEPENDENT_LIBRARY`、`ALLOW_WRITABLE_CODE_MEMORY`、`DISABLE_CODE_MEMORY_PROTECTION`。完整清单与 `hnp/arm64-v8a`、`filesDir`、`el2/base/files` 等沙箱路径见 PixelTune 案例。
+
+---
+
+## 八、与 Java 方案对比
+
+| 维度 | Python 方案 | Java 方案 |
+|------|------------|----------|
+| **运行时大小** | 较小（`libpython3.12.so` ~5MB + 标准库） | 较大（`libjvm.so` ~13MB + JRE ~108MB） |
+| **启动速度** | 快（`Py_Initialize` 毫秒级） | 慢（`JNI_CreateJavaVM` 秒级） |
+| **嵌入复杂度** | 低（Python C API 直接调用） | 高（需要 NAPI + JNI 双层桥接） |
+| **动态性** | 高（脚本文件可直接替换） | 中（需要重新打包 jar） |
+| **三方库生态** | 极丰富（PyPI） | 极丰富（Maven Central） |
+| **性能** | 解释执行，计算密集场景较慢 | JIT 编译，长期运行性能好 |
+| **内存占用** | 较低 | 较高（JVM 默认堆就几百 MB） |
+| **C 扩展兼容** | 需要为鸿蒙重新编译 | 需要为鸿蒙重新编译 JNI 库 |
+
+**选择建议：**
+- 需要运行 Python 脚本/工具 → Python 方案
+- 需要运行 Java 企业级应用 → Java 方案
+- 需要快速原型/动态逻辑 → Python 方案
+- 需要高性能计算 → Java 方案（JIT）
+
+---
+
+## 九、注意事项
+
+### 9.1 文件路径
+
+鸿蒙应用的文件路径与常规 Linux 不同，需要使用沙箱路径：
+
+| 路径 | 说明 |
+|------|------|
+| `/data/storage/el1/bundle/entry/libs/` | SO 库（extractNativeLibs=true 时） |
+| `/data/storage/el1/bundle/entry/resources/resfile/` | resfile 资源文件 |
+| `/data/storage/el2/base/haps/entry/files/` | 应用私有文件（可读写） |
+
+### 9.2 Python 标准库位置
+
+`PYTHONHOME` 设置后，Python 会在 `$PYTHONHOME/lib/python3.12/` 下查找标准库。确保目录结构正确：
+
+```
+$PYTHONHOME/
+└── lib/
+    └── python3.12/
+        ├── os.py, sys.py, json/ ...
+        └── site-packages/
+            └── (三方库)
+```
+
+### 9.3 纯 Python 库 vs C 扩展库
+
+| 类型 | 适配难度 | 说明 |
+|------|---------|------|
+| 纯 Python 库 | 零适配 | 直接放入 site-packages 即可 |
+| 含 C 扩展的库 | 需要编译 | 需要为鸿蒙 aarch64 编译 .so 模块 |
+| 系统库调用 | 直接可用 | `os`, `sys`, `subprocess` 等可直接使用 |
+
+### 9.4 调试技巧
+
+Python 的 `print()` 输出默认会写到标准输出，在鸿蒙上可以通过 hilog 查看。项目中的 `hilog-easy` 工具是一个实用的日志辅助库，它将 hilog 的 `%{public}`/`%{private}` 格式自动转换为标准 printf 格式，方便调试。
+
+---
+
+## 十、总结
+
+通过在鸿蒙应用中嵌入 CPython 运行时，可以实现一种**轻量级的 ArkTS + Python 混合开发模式**。
+
+**核心优势：**
+
+1. **极简嵌入**：仅需 `Py_Initialize()` + `PyRun_SimpleFileEx()` 两步，50 行 C++ 代码即可启动 Python
+2. **低资源消耗**：相比 JVM 方案，Python 运行时更小、启动更快
+3. **动态性**：Python 脚本放在 resfile 中可直接替换，无需重新编译应用
+4. **生态丰富**：PyPI 海量纯 Python 库可直接使用
+
+**适用场景：**
+- Python 脚本工具迁移到鸿蒙
+- 需要动态更新业务逻辑的应用
+- 使用 Python 科学计算库进行端侧数据处理
+- 跨平台业务逻辑共享
+
+这种模式为 Python 开发者进入鸿蒙生态提供了一条最轻量的技术路径。

package/node_modules/@ohos-agent/pc-adapter/skills/harmonyos-pc-resources/references//350/265/204/346/272/220/346/225/264/347/220/206.md

@@ -0,0 +1,41 @@
+# 资源整合推荐
+
+本文主要对现有所有资源进行收集、整合及分类。**欢迎您使用及参与贡献。**
+
+
+#### 参与贡献
+>新建项目或者提建议，请提[issue](https://gitcode.com/OpenHarmonyPCDeveloper/community/issues/create/choose)，谢谢大家配合
+具体参考[共建指导](./contribute/共建指导.md)
+
+[TOC]
+
+---
+
+#### 官方资源推荐
+- [三方库技术交流阵地:OpenHarmony开发者论坛](https://forums.openharmony.cn/)
+
+## PC领域资源整合
+
+### 1、资源文章推荐
+
+技术交流社区：[Harmony PC 开发者社区](https://harmonypc.csdn.net/)
+
+### 2、运行时资源（包含所有历史版本）
+
+- [编程语言运行时](./aggregate/【运行时】开源运行时汇总.md)
+
+### 3、编程语言三方库资源推荐
+
+- [开源三方库指导文档](./aggregate/【三方库】开源三方库指导文档.md)
+
+### 4、跨平台框架资源推荐
+- [Qt 资源汇总](./aggregate/【跨平台框架】Qt资源汇总.md)
+- [Electron资源汇总](./aggregate/【跨平台框架】Electron资源汇总.md)
+
+### 5、鸿蒙电脑开源应用资源推荐
+
+- [鸿蒙PC开源应用](<./aggregate/【鸿蒙 PC 应用】开源应用汇总.md>)
+
+### 6、命令行资源推荐
+
+- [OpenHarmony PC 开源命令行](./aggregate/【命令行】开源命令行汇总.md)