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

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/README.md

@@ -0,0 +1,31 @@
+# cpp-gui-owb-demo — C/C++ GUI/图形库真机上屏验证 HAP 模板
+
+**用途**：被适配的 C/C++ 库涉及**窗口/GL 上屏**（graphical-window/gl-context/ui 能力域，如 GLFW/SDL/Qt）时，生成可构建、可签名、可 `ohpt-agent verify-demo` 取证的验证载体。原理：OWB（ohos-window-bridge）把 XComponent 的 surface 交给你的库做 EGL/GLES 渲染，`owb_ohos_app.h` 让桌面 `main()` 原样跑上鸿蒙。默认 `gui_shell.cpp` 是最小 clear-screen 呼吸色壳（证明链路）；带 `--test-cases` 生成时自动切到**用例模式**（常驻循环 + 按请求派发，只需填 `ohpt_run_case()`），不带时保持中性 `main()` 循环。非 GUI 的纯计算库请用 `cpp-lib-demo`。
+
+**承重骨架**（照 pyGLFW 实证成功配置，**禁止手写**）：`runtimeOS:"HarmonyOS"`、`compatible/targetSdkVersion:"5.0.0(12)"`、**无 `compileSdkVersion`**；`externalNativeOptions.abiFilters:["arm64-v8a"]`；stage model + `extractNativeLibs:true`；`modelVersion:"5.0.0"`；无 `local.properties`（SDK 走 `DEVECO_SDK_HOME`）。runtimeOS 配错触发 E121。
+
+## 生成与使用
+
+```bash
+ohpt scaffold --kind cpp-gui-owb-demo -w <workspace> --bundle com.example.<lib>.demo --name "<Lib> Demo"
+cd <workspace>
+bash deps/ohos-window-bridge/build/build.sh    # 构建 OWB（scaffold 已装配源码到 deps/）
+# 换你的 GUI 库：把 harmony-demo/entry/src/main/cpp/gui_shell.cpp 的 main() 换成你库的桌面 main()，
+#   CMakeLists.txt 追加链接你的库 .a/.so，build/build-hap.sh 的 NATIVE_LIBS 列出运行期 .so。
+bash build/build-hap.sh                         # 构建 unsigned HAP
+ohpt sign-demo -w <workspace> --install         # SDK 材料 headless 签名装机
+ohpt-agent verify-demo -w <workspace>           # 装机→拉起→抓 hilog 结果行/GL 身份 → build/demo-verify.json
+                                                # （截图只在主线单次路径存档；测试线判据只看日志行）
+```
+
+## 三处必须全等的名字（对不齐 = 黑屏、常无报错）
+
+`__XCOMP__`（由 `--bundle` 派生、`--name` 覆盖显示名）：
+- `harmony-demo/entry/src/main/ets/pages/Index.ets` 的 `XComponent({ libraryname: '__XCOMP__' })`
+- `CMakeLists.txt` 的 `add_library(__XCOMP__ SHARED …)`
+- `gui_shell.cpp` 末尾 `OWB_OHOS_THREAD_APP("__XCOMP__")`
+
+## 与 glfw-triangle example 的关系
+
+本模板给**中性 clear-screen 壳**（不绑定具体库）。要跑具体 GLFW 三角形，把
+`skills/…/ohos-window-bridge/examples/glfw-triangle/` 的 `cpp/`、`ets/Index.ets` 叠加进本骨架即可（那份 example 是该具体示例的单一权威）。

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/build-profile.json5

@@ -0,0 +1,36 @@
+{
+  "app": {
+    "signingConfigs": [],
+    "products": [
+      {
+        "name": "default",
+        "signingConfig": "default",
+        "compatibleSdkVersion": "5.0.0(12)",
+        "targetSdkVersion": "5.0.0(12)",
+        "runtimeOS": "HarmonyOS"
+      }
+    ],
+    "buildModeSet": [
+      {
+        "name": "debug"
+      },
+      {
+        "name": "release"
+      }
+    ]
+  },
+  "modules": [
+    {
+      "name": "entry",
+      "srcPath": "./entry",
+      "targets": [
+        {
+          "name": "default",
+          "applyToProducts": [
+            "default"
+          ]
+        }
+      ]
+    }
+  ]
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/entry/build-profile.json5

@@ -0,0 +1,45 @@
+{
+  "apiType": "stageMode",
+  "buildOption": {
+    "externalNativeOptions": {
+      "path": "./src/main/cpp/CMakeLists.txt",
+      "arguments": "",
+      "abiFilters": [
+        "arm64-v8a"
+      ]
+    }
+  },
+  "buildOptionSet": [
+    {
+      "name": "release",
+      "arkOptions": {
+        "obfuscation": {
+          "ruleOptions": {
+            "enable": false,
+            "files": [
+              "./obfuscation-rules.txt"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "name": "debug",
+      "arkOptions": {
+        "obfuscation": {
+          "ruleOptions": {
+            "enable": false,
+            "files": [
+              "./obfuscation-rules.txt"
+            ]
+          }
+        }
+      }
+    }
+  ],
+  "targets": [
+    {
+      "name": "default"
+    }
+  ]
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/entry/hvigorfile.ts

@@ -0,0 +1,6 @@
+import { hapTasks } from '@ohos/hvigor-ohos-plugin';
+
+export default {
+    system: hapTasks,  /* Built-in plugin of Hvigor. It cannot be modified. */
+    plugins: []       /* Custom plugin to extend the functionality of Hvigor. */
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/entry/obfuscation-rules.txt

@@ -0,0 +1,2 @@
+# Build profile global options
+-keep-all

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/entry/oh-package.json5

@@ -0,0 +1,9 @@
+{
+  "name": "entry",
+  "version": "1.0.0",
+  "description": "__APPNAME__ entry module",
+  "main": "",
+  "author": "",
+  "license": "MIT",
+  "dependencies": {}
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/entry/src/main/cpp/CMakeLists.txt

@@ -0,0 +1,43 @@
+# CMakeLists.txt — cpp-gui-owb-demo：OWB GLES 上屏壳（clear-screen），验证 C/C++ GUI 库能在设备上屏。
+#
+# 产物：libs/arm64-v8a/lib__XCOMP__.so（XComponent libraryname='__XCOMP__'）。
+# 三处名字必须全等（对不齐 = 黑屏且常无明显报错）：
+#   Index.ets 的 libraryname='__XCOMP__' == 下面 add_library(__XCOMP__ …) == gui_shell.cpp 末尾 OWB_OHOS_THREAD_APP("__XCOMP__")
+# 前置：deps/ohos-window-bridge 已构建（bash deps/ohos-window-bridge/build/build.sh）。
+cmake_minimum_required(VERSION 3.16)
+project(__XCOMP__)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC")
+
+# 工作区根：本文件在 harmony-demo/entry/src/main/cpp/，向上 5 级。
+get_filename_component(WS "${CMAKE_CURRENT_SOURCE_DIR}/../../../../.." ABSOLUTE)
+set(OWB_ROOT "${WS}/deps/ohos-window-bridge")   # ← scaffold needsOwb 已整目录装配
+set(OWB_LIB "${OWB_ROOT}/dist/libohos_window_bridge.so")  # OWB build/build.sh 产物
+
+if (NOT EXISTS "${OWB_LIB}")
+    message(FATAL_ERROR "libohos_window_bridge.so not found at ${OWB_LIB}; run deps/ohos-window-bridge/build/build.sh")
+endif()
+
+# 壳 .so：gui_shell.cpp + OWB 的 L1 napi 胶水（owb_napi.cpp 提供 HookXComponent/InstallWindowControl）
+add_library(__XCOMP__ SHARED
+    gui_shell.cpp
+    ${OWB_ROOT}/napi/owb_napi.cpp)
+
+target_include_directories(__XCOMP__ PRIVATE
+    ${OWB_ROOT}/include
+    ${OWB_ROOT}/napi)
+
+# EGL/GLESv3 = 鸿蒙 PC 开箱即用 GPU 栈；native_window* = surface；ace_* = XComponent/napi；
+# -Wl,-z,max-page-size=0x1000 = 4KB 页对齐（不加 dlopen 可能 SIGSEGV，见 OWB README）。
+target_link_libraries(__XCOMP__ PRIVATE
+    ${OWB_LIB}
+    EGL
+    GLESv3
+    native_window
+    native_window_manager
+    ace_ndk.z
+    ace_napi.z
+    hilog_ndk.z
+    -Wl,-z,max-page-size=0x1000)

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/entry/src/main/cpp/gui_shell.cpp

@@ -0,0 +1,138 @@
+// gui_shell.cpp — cpp-gui-owb-demo：OWB + EGL/GLES 上屏壳。
+//
+// 证明「C/C++ GUI/图形库能在鸿蒙 PC 设备上屏」这条链路：OWB 绑定 XComponent surface、
+// 在其 OHNativeWindow 上起 EGL/GLES，worker 线程持续渲染。
+// 三处名字必须全等：Index.ets 的 libraryname='__XCOMP__' == add_library(__XCOMP__ …)
+//                  == 末尾 OWB_OHOS_THREAD_APP("__XCOMP__")。
+//
+// ── 两种模式，同一份源码 ──────────────────────────────────────────────
+// `ohpt-agent scaffold --test-cases` 会往同目录生成 ohpt_cases.h 并放入 ohpt_case_loop.h，
+// 下面的 __has_include 自动切到**用例模式**：常驻循环 + 按请求派发，你只需填 ohpt_run_case()。
+// 不带 --test-cases（主线阶段 3 的上屏取证）时保持中性渲染循环，一字不必改。
+//
+// ⚠️ 用例模式下 main() **不退出**——跑完一条继续等下一条。此前是「跑完就 return」，于是
+// 一个进程只跑得了一条：人工浏览 N 条要冷启动 N 次，画面还只闪 80~160ms 就没了，
+// 而图形档恰恰是唯一必须靠人看的档。
+#include <EGL/egl.h>
+#include <GLES3/gl3.h>
+#include <unistd.h>
+
+#include "ohos_window_bridge.h"
+#include "owb_ohos_app.h"
+
+#if __has_include("ohpt_cases.h")
+#include "ohpt_cases.h"
+#include "ohpt_case_loop.h"
+#define OHPT_CASE_MODE 1
+#endif
+
+static EGLDisplay s_dpy = EGL_NO_DISPLAY;
+static EGLSurface s_surf = EGL_NO_SURFACE;
+static EGLContext s_ctx = EGL_NO_CONTEXT;
+static OWB_SurfaceInfo s_info;
+static int s_ready = 0;
+
+static int initEGL(void* nativeWindow) {
+  s_dpy = eglGetDisplay(EGL_DEFAULT_DISPLAY);
+  if (s_dpy == EGL_NO_DISPLAY) return 0;
+  eglInitialize(s_dpy, 0, 0);
+  eglBindAPI(EGL_OPENGL_ES_API);
+  const EGLint cfgAttrs[] = {
+      EGL_SURFACE_TYPE, EGL_WINDOW_BIT, EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT,
+      EGL_RED_SIZE, 8, EGL_GREEN_SIZE, 8, EGL_BLUE_SIZE, 8, EGL_ALPHA_SIZE, 8, EGL_NONE};
+  EGLConfig cfg;
+  EGLint num = 0;
+  if (!eglChooseConfig(s_dpy, cfgAttrs, &cfg, 1, &num) || num < 1) return 0;
+  s_surf = eglCreateWindowSurface(s_dpy, cfg, (EGLNativeWindowType)nativeWindow, 0);
+  if (s_surf == EGL_NO_SURFACE) return 0;
+  const EGLint ctxAttrs[] = {EGL_CONTEXT_CLIENT_VERSION, 3, EGL_NONE};
+  s_ctx = eglCreateContext(s_dpy, cfg, EGL_NO_CONTEXT, ctxAttrs);
+  if (s_ctx == EGL_NO_CONTEXT) return 0;
+  return eglMakeCurrent(s_dpy, s_surf, s_surf, s_ctx);
+}
+
+/** 首次调用时绑定 surface 并起 EGL（surface 已由 OWB_WaitForSurface 保证登记）。 */
+static int ensureGL(void) {
+  if (s_ready) return 1;
+  int n = OWB_GetSurfaceCount();
+  for (int i = 0; i < n; i++) {
+    if (OWB_GetSurfaceInfoByIndex(i, &s_info) == OWB_OK) {
+      OWB_AcquireSurface(s_info.surfaceId);
+      s_ready = initEGL(OWB_GetNativeWindow(s_info.surfaceId));
+      break;
+    }
+  }
+  return s_ready;
+}
+
+/** 渲染一帧（呼吸色：证明是活的渲染循环而非静帧）。 */
+static void render_frame(void) {
+  static float t = 0.0f;
+  if (!ensureGL()) return;
+  OWB_Event ev;
+  while (OWB_PollEvent(&ev)) { /* 输入事件交给被测库消费；本壳只排空 */ }
+  OWB_SurfaceInfo cur;
+  if (OWB_GetSurfaceInfoById(s_info.surfaceId, &cur) == OWB_OK) glViewport(0, 0, cur.width, cur.height);
+  t += 0.01f;
+  if (t > 1.0f) t = 0.0f;
+  glClearColor(0.10f + 0.4f * t, 0.35f, 0.55f, 1.0f);
+  glClear(GL_COLOR_BUFFER_BIT);
+  eglSwapBuffers(s_dpy, s_surf);
+}
+
+#ifdef OHPT_CASE_MODE
+
+/**
+ * ★ 你要写的就是这一个函数：按用例下标跑被测库的那段功能。
+ *
+ * `req` 是请求原文（`<case-id>[ p1=… p2=…]`，参数来自页面上按 steps[].action 生成的输入框），
+ * 用 `ohpt_param_int(req, "p1", 默认值)` 取。`ci` 是 OHPT_CASES 下标。
+ *
+ * 每条判定点必须有一个结论，二选一：
+ *   · 机器判得了（观测值能从被测库取回来）→ `OHPT_CHECK(id, cp, ok, "期望值", "实际观测值")`
+ *     **读了值、打了日志、然后 return true 不算判定**——expect/actual 是「比对过」的唯一凭据。
+ *   · 机器判不了（上屏对不对、要人先按键才触发的回调）→ **什么都别打**，
+ *     让它落 pending-human，由人在 demo 页面上点「符合 / 不符合」。替人下结论是此前
+ *     80 条用例里 38 条假绿的直接来源。
+ *
+ * 最后用 `ohpt_write_result(id, "…")` 把真实观测值回传页面（人要看的就是它，
+ * 不要写「成功」这类文案），并调 `ohpt_report_case_result_for(id, ok, "")` 打用例级结果行。
+ */
+static void ohpt_run_case(const char* req, int ci) {
+  const char* id = OHPT_CASES[ci].id;
+  if (!ensureGL()) {
+    ohpt_write_result(id, "EGL 未就绪");
+    ohpt_report_case_result_for(id, 0, "no-gl");
+    return;
+  }
+  // TODO(阶段 6)：switch (ci) { case 0: …被测库调用 + OHPT_CHECK…; }
+  const char* renderer = (const char*)glGetString(GL_RENDERER);
+  char buf[256];
+  snprintf(buf, sizeof(buf), "GL_RENDERER=%s\nsurface=%dx%d\n(用例未接线：在 ohpt_run_case() 里按 ci 分派)",
+           renderer ? renderer : "(null)", s_info.width, s_info.height);
+  ohpt_write_result(id, buf);
+  ohpt_report_case_result_for(id, 0, "not-wired");
+}
+
+/** 没有用例在跑时保持画面——图形档的验收面是「人看得见的画面」，不是一闪而过的几帧。 */
+static void ohpt_keepalive(void) { render_frame(); }
+
+OHPT_CASE_MAIN()
+
+#else
+
+int main(int argc, char** argv) {
+  (void)argc;
+  (void)argv;
+  OWB_Initialize();
+  if (OWB_WaitForSurface(-1) != OWB_OK) return 1;  // 阻塞到 XComponent surface 登记
+  for (;;) {
+    render_frame();
+    usleep(16000);  // ~60fps
+  }
+  return 0;
+}
+
+#endif /* OHPT_CASE_MODE */
+
+OWB_OHOS_THREAD_APP("__XCOMP__")

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/entry/src/main/ets/entryability/EntryAbility.ets

@@ -0,0 +1,32 @@
+import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
+import { window } from '@kit.ArkUI';
+
+export default class EntryAbility extends UIAbility {
+  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
+    // AppStorage 中保存主窗口，供 XComponent onLoad 中绑定 OWB 窗口控制桥
+  }
+
+  onDestroy(): void {
+  }
+
+  onWindowStageCreate(windowStage: window.WindowStage): void {
+    // Main window is created here; set it on AppStorage.
+    AppStorage.setOrCreate('owbMainWindow', windowStage.getMainWindowSync());
+    windowStage.loadContent('pages/Index', (err) => {
+      if (err) {
+        console.error('Failed to load content', JSON.stringify(err));
+        return;
+      }
+      console.info('Succeeded in loading content.');
+    });
+  }
+
+  onWindowStageDestroy(): void {
+  }
+
+  onForeground(): void {
+  }
+
+  onBackground(): void {
+  }
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/entry/src/main/ets/pages/Index.ets

@@ -0,0 +1,29 @@
+// entry/src/main/ets/pages/Index.ets — L0 宿主页：SURFACE XComponent 占满窗口，
+// 为 OWB Python 解释器线程壳提供原生像素上屏通道。
+// libraryname:'__XCOMP__' 必须与 CMake target 名、native 侧 OWB_OHOS_PYTHON_APP 三处全等。
+import { window } from '@kit.ArkUI';
+import { owbBindWindowControl } from '../common/OWBWindowControl';
+
+@Entry
+@Component
+struct Index {
+  private xcCtl: XComponentController = new XComponentController();
+
+  build() {
+    Column() {
+      XComponent({
+        id: 'owbSurface',
+        type: XComponentType.SURFACE,
+        libraryname: '__XCOMP__',
+        controller: this.xcCtl
+      })
+        .width('100%')
+        .height('100%')
+        .onLoad(() => {
+          owbBindWindowControl(this.xcCtl, AppStorage.get<window.Window>('owbMainWindow'));
+        })
+    }
+    .width('100%')
+    .height('100%')
+  }
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/entry/src/main/module.json5

@@ -0,0 +1,50 @@
+{
+  "module": {
+    "name": "entry",
+    "type": "entry",
+    "description": "$string:entry_desc",
+    "mainElement": "EntryAbility",
+    "deviceTypes": [
+      "2in1",
+      "tablet",
+      "phone"
+    ],
+    "deliveryWithInstall": true,
+    "installationFree": false,
+    "extractNativeLibs": true,
+    "pages": "$profile:main_pages",
+    "abilities": [
+      {
+        "name": "EntryAbility",
+        "srcEntry": "./ets/entryability/EntryAbility.ets",
+        "description": "$string:entry_desc",
+        "icon": "$media:app_icon",
+        "label": "$string:app_name",
+        "startWindowIcon": "$media:app_icon",
+        "startWindowBackground": "$color:start_window_background",
+        "exported": true,
+        "skills": [
+          {
+            "entities": [
+              "entity.system.home"
+            ],
+            "actions": [
+              "action.system.home"
+            ]
+          }
+        ]
+      }
+    ],
+    "metadata": [
+      {
+        "name": "ArkTSPartialUpdate",
+        "value": "true"
+      }
+    ],
+    "requestPermissions": [
+      {
+        "name": "ohos.permission.INTERNET"
+      }
+    ]
+  }
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/entry/src/main/resources/base/element/color.json

@@ -0,0 +1,8 @@
+{
+  "color": [
+    {
+      "name": "start_window_background",
+      "value": "#FFFFFF"
+    }
+  ]
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/entry/src/main/resources/base/element/string.json

@@ -0,0 +1,8 @@
+{
+  "string": [
+    {
+      "name": "entry_desc",
+      "value": "__APPNAME__"
+    }
+  ]
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/entry/src/main/resources/base/profile/main_pages.json

@@ -0,0 +1,5 @@
+{
+  "src": [
+    "pages/Index"
+  ]
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/hvigor/hvigor-config.json5

@@ -0,0 +1,13 @@
+{
+  "modelVersion": "5.0.0",
+  "dependencies": {
+  },
+  "execution": {
+  },
+  "logging": {
+  },
+  "debugging": {
+  },
+  "nodeOptions": {
+  }
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/hvigorfile.ts

@@ -0,0 +1,6 @@
+import { appTasks } from '@ohos/hvigor-ohos-plugin';
+
+export default {
+    system: appTasks,  /* Built-in plugin of Hvigor. It cannot be modified. */
+    plugins: []       /* Custom plugin to extend the functionality of Hvigor. */
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/oh-package.json5

@@ -0,0 +1,8 @@
+{
+  "modelVersion": "5.0.0",
+  "description": "__APPNAME__ (cpp-gui-owb-demo scaffold)",
+  "dependencies": {
+  },
+  "devDependencies": {
+  }
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-gui-owb-demo/scripts/build-hap.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# build-hap.sh — 构建 cpp-gui-owb-demo HAP（C/C++ GUI/图形库真机上屏验证载体）。
+#
+# 前置：
+#   1. DEVECO_SDK_HOME 已设置（定位见 pc-knowledge-base「定位 DevEco SDK」）；
+#   2. OWB 已构建：deps/ohos-window-bridge/dist/libohos_window_bridge.so
+#      （无则先跑 bash deps/ohos-window-bridge/build/build.sh）。
+# 产物：dist/app/entry-default-unsigned.hap（签名走 `ohpt sign-demo`）。
+#
+# 骨架来自 `ohpt scaffold --kind cpp-gui-owb-demo`，只改占位符/下方参数段——
+# 禁止手写 harmony-demo/build-profile.json5（runtimeOS 配错触发 E121）。
+
+set -euo pipefail
+
+WORKSPACE="$(cd "$(dirname "$0")/__WSREL__" && pwd)"
+DEMO_DIR="$WORKSPACE/__OUT__"
+DIST_DIR=__DIST__
+OWB_SO="$WORKSPACE/deps/ohos-window-bridge/dist/libohos_window_bridge.so"
+
+# ===[按你的库改这里]=========================================================
+# 下面两行若已有值，是从同工作区**已跑通设备**的那份 build-hap.sh 继承来的（scaffold 自动带过来）——
+# 核对一下即可，别从零重推。为空说明本工作区还没有先例，按注释自己填。
+# NATIVE_LIBS：拷进 entry/libs/arm64-v8a/ 的原生 .so（你适配出的 GUI 库 ohos_aarch64 产物）
+NATIVE_LIBS=(__NATIVE_LIBS__)
+# LIB_ALIASES："别名=真名" 软链，供动态链接器按 SONAME 找库，如 "libglfw.so.3=libglfw.so.3.5"
+LIB_ALIASES=(__LIB_ALIASES__)
+# ===========================================================================
+
+: "${DEVECO_SDK_HOME:?未设置 DEVECO_SDK_HOME——定位方法见 pc-knowledge-base「定位 DevEco SDK」}"
+export PATH="$DEVECO_SDK_HOME/default/openharmony/toolchains:$PATH"
+
+check() {
+    [[ -f "$OWB_SO" ]] \
+        || { echo "[ERROR] OWB 未构建：先跑 bash deps/ohos-window-bridge/build/build.sh"; exit 1; }
+}
+
+stage_libs() {
+    local LIBS="$DEMO_DIR/entry/libs/arm64-v8a"
+    mkdir -p "$LIBS"
+    cp "$OWB_SO" "$LIBS/"
+    echo "[OK] libs <- $OWB_SO"
+    local so alias
+    for so in ${NATIVE_LIBS[@]+"${NATIVE_LIBS[@]}"}; do
+        [[ "$so" = /* ]] || so="$WORKSPACE/$so"
+        cp "$so" "$LIBS/"
+        echo "[OK] libs <- $so"
+    done
+    for alias in ${LIB_ALIASES[@]+"${LIB_ALIASES[@]}"}; do
+        (cd "$LIBS" && rm -f "${alias%%=*}" && ln -s "${alias#*=}" "${alias%%=*}")
+        echo "[OK] alias ${alias%%=*} -> ${alias#*=}"
+    done
+}
+
+build_hap() {
+    cd "$DEMO_DIR"
+    "$DEVECO_SDK_HOME/../tools/hvigor/bin/hvigorw" assembleApp -p product=default --no-daemon
+    local HAP
+    HAP="$(find "$DEMO_DIR/entry/build/default/outputs/default" -name '*.hap' 2>/dev/null | head -1)"
+    [[ -f "$HAP" ]] || { echo "[ERROR] 未找到构建产物 hap"; exit 1; }
+    mkdir -p "$DIST_DIR"
+    cp "$HAP" "$DIST_DIR/entry-default-unsigned.hap"
+    echo "[OK] HAP: $DIST_DIR/entry-default-unsigned.hap（下一步 ohpt sign-demo）"
+}
+
+check
+stage_libs
+build_hap

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-lib-demo/AppScope/app.json5

@@ -0,0 +1,12 @@
+{
+  "app": {
+    "bundleName": "__BUNDLE__",
+    "vendor": "example",
+    "versionCode": 1000000,
+    "versionName": "1.0.0",
+    "icon": "$media:app_icon",
+    "label": "$string:app_name",
+    "targetAPIVersion": 12,
+    "minAPIVersion": 12
+  }
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-lib-demo/AppScope/resources/base/element/string.json

@@ -0,0 +1,8 @@
+{
+  "string": [
+    {
+      "name": "app_name",
+      "value": "__APPNAME__"
+    }
+  ]
+}

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-lib-demo/README.md

@@ -0,0 +1,30 @@
+# cpp-lib-demo — 纯 C/C++ 库真机功能验证 HAP 模板
+
+**用途**：被适配的 C/C++ 库**非 GUI**（compute/codec/parse 等）时，生成一个可构建、可签名、可装机的最小 HAP——一个 NAPI 壳加载适配出的 `.so`、调用其代表符号、把结果显示到屏幕（`ohpt verify-demo` 可截图取证「设备侧可加载调用」）。GUI/上屏库请用 `cpp-gui-owb-demo`。
+
+**承重骨架**（照 pyGLFW 实证成功配置，**禁止手写**）：`build-profile.json5` 的 `runtimeOS:"HarmonyOS"`、`compatible/targetSdkVersion:"5.0.0(12)"`、**不含 `compileSdkVersion`**（跟随已装 SDK）；`entry/build-profile.json5` 的 `externalNativeOptions.abiFilters:["arm64-v8a"]`；`module.json5` stage model + `extractNativeLibs:true`；`hvigor-config.json5` `modelVersion:"5.0.0"`。无 `local.properties`——SDK 走 `DEVECO_SDK_HOME`。runtimeOS 配错触发 E121。
+
+## 生成与使用
+
+```bash
+ohpt scaffold --kind cpp-lib-demo -w <workspace> --bundle com.example.<lib>.demo --name "<Lib> Demo"
+cd <workspace>
+# 1) 把适配出的 .so 填进 build/build-hap.sh 的 NATIVE_LIBS；在 harmony-demo/entry/src/main/cpp/
+#    napi_stub.cpp 的 CallLib() 调你的库符号；CMakeLists.txt 追加链接该 .so。
+# 2) 构建未签 HAP：
+bash build/build-hap.sh
+# 3) SDK 材料 headless 签名装机：
+ohpt sign-demo -w <workspace> --install
+# 4) 拉起 + 截图取证：
+ohpt verify-demo -w <workspace>
+```
+
+## 参数化点
+
+- `__BUNDLE__` — bundleName（`--bundle`）
+- `__XCOMP__` — NAPI 模块名 = ArkTS import 名 = CMake target = `lib<name>.so`（由 bundle 派生，`--name` 可覆盖显示名 `__APPNAME__`）
+- `NATIVE_LIBS` / `CallLib()` / `CMakeLists.txt` — 换成你的库（三处）
+
+## 默认自包含
+
+napi_stub.cpp 默认不依赖外部库即可编译上屏（返回一句确认串），先跑通「NAPI 模块设备可加载」，再逐步换成对你 `.so` 的真实调用。

package/node_modules/@ohos-agent/pc-adapter/templates/hap/cpp-lib-demo/build-profile.json5

@@ -0,0 +1,36 @@
+{
+  "app": {
+    "signingConfigs": [],
+    "products": [
+      {
+        "name": "default",
+        "signingConfig": "default",
+        "compatibleSdkVersion": "5.0.0(12)",
+        "targetSdkVersion": "5.0.0(12)",
+        "runtimeOS": "HarmonyOS"
+      }
+    ],
+    "buildModeSet": [
+      {
+        "name": "debug"
+      },
+      {
+        "name": "release"
+      }
+    ]
+  },
+  "modules": [
+    {
+      "name": "entry",
+      "srcPath": "./entry",
+      "targets": [
+        {
+          "name": "default",
+          "applyToProducts": [
+            "default"
+          ]
+        }
+      ]
+    }
+  ]
+}