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

package/node_modules/@ohos-agent/pc-adapter/templates/build-tools/pkg-config-shim/pkg-config.py

@@ -0,0 +1,328 @@
+#!/usr/bin/env python3
+"""Simple pkg-config emulator for cross-compilation.
+Reads .pc files from PKG_CONFIG_PATH and returns cflags/libs/version.
+
+Usage:
+  set PKG_CONFIG_PATH=<conan-deps>/lib/pkgconfig
+  pkg-config.cmd --cflags --libs libusb-1.0
+
+meson cross-file integration:
+  [binaries]
+  pkg-config = 'path/to/pkg-config.cmd'
+"""
+
+import os
+import re
+import sys
+import argparse
+
+
+def ver_compare(ver, op, target):
+    """Simple version comparison (x.y.z format)."""
+    def parse(v):
+        parts = v.split('.')
+        return tuple(int(p) for p in parts[:3])
+    v1 = parse(ver)
+    v2 = parse(target)
+    if op == '>=': return v1 >= v2
+    if op == '<=': return v1 <= v2
+    if op == '==': return v1 == v2
+    if op == '>':  return v1 > v2
+    if op == '<':  return v1 < v2
+    return False
+
+
+def resolve_pkg_config_paths():
+    """Get PKG_CONFIG_PATH environment variable split into list."""
+    env = os.environ.get('PKG_CONFIG_PATH', '')
+    # Support both ; and : as separators (Windows/Unix)
+    parts = env.replace(':', ';').split(';')
+    return [p for p in parts if p.strip()]
+
+
+def find_pc_file(pkg_name, search_paths):
+    """Find .pc file for given package name."""
+    for path in search_paths:
+        pc_path = os.path.join(path, f'{pkg_name}.pc')
+        if os.path.isfile(pc_path):
+            return pc_path
+    # Also try without .pc extension
+    for path in search_paths:
+        pc_path = os.path.join(path, pkg_name)
+        if os.path.isfile(pc_path) and pc_path.endswith('.pc'):
+            return pc_path
+    return None
+
+
+def parse_pc_file(pc_path, define_prefix=False):
+    """Parse a .pc file and return a dict of variables."""
+    variables = {}
+    content = []
+
+    basedir = os.path.dirname(pc_path)
+    variables['pcfiledir'] = basedir
+
+    # Default prefix
+    variables['prefix'] = '/usr/local'
+    variables['exec_prefix'] = '${prefix}'
+    variables['libdir'] = '${exec_prefix}/lib'
+    variables['includedir'] = '${prefix}/include'
+    variables['bindir'] = '${exec_prefix}/bin'
+    variables['datadir'] = '${prefix}/share'
+
+    # Read file first to detect declared prefix before applying define-prefix
+    raw_vars = {}
+    with open(pc_path, 'r', encoding='utf-8', errors='replace') as f:
+        for line in f:
+            line = line.rstrip()
+            m = re.match(r'^([a-zA-Z_][a-zA-Z0-9_]*)\s*=(.*)', line)
+            if m:
+                raw_vars[m.group(1)] = m.group(2).strip()
+
+    with open(pc_path, 'r', encoding='utf-8', errors='replace') as f:
+        for line in f:
+            line = line.rstrip()
+            # Skip empty lines and comments
+            if not line or line.startswith('#'):
+                content.append(line)
+                continue
+
+            # Variable definition: name=value
+            var_match = re.match(r'^([a-zA-Z_][a-zA-Z0-9_]*)\s*=(.*)', line)
+            if var_match:
+                var_name = var_match.group(1)
+                var_value = var_match.group(2).strip()
+                # Skip standard fields
+                if var_name not in ('Name', 'Description', 'Version', 'Requires',
+                                   'Requires.private', 'Libs', 'Libs.private',
+                                   'Cflags', 'URL', 'Conflicts'):
+                    variables[var_name] = var_value
+                else:
+                    content.append(line)
+            else:
+                content.append(line)
+
+    # If --define-prefix is set, override prefix based on pcfiledir
+    pcfiledir = os.path.abspath(variables['pcfiledir'])
+    parent = os.path.dirname(pcfiledir)  # .../lib
+    grandparent = os.path.dirname(parent)  # .../
+    # Normalize path to use forward slashes on Windows
+    grandparent = grandparent.replace('\\', '/')
+    # Only override if the declared prefix is a generic path
+    declared_prefix = raw_vars.get('prefix', '/usr/local')
+    if define_prefix or declared_prefix in ('/usr/local', '/usr', '/', '/opt'):
+        variables['prefix'] = grandparent
+        variables['exec_prefix'] = grandparent if '${prefix}' in variables.get('exec_prefix', '${prefix}') else variables['exec_prefix']
+        variables['libdir'] = os.path.join(grandparent, 'lib').replace('\\', '/')
+        variables['includedir'] = os.path.join(grandparent, 'include').replace('\\', '/')
+
+    # Resolve variable references
+    def resolve_vars(value):
+        while '${' in value:
+            value = re.sub(r'\$\{([^}]+)\}', lambda m: variables.get(m.group(1), m.group(0)), value)
+        return value
+
+    # Now parse fields
+    result = {
+        'name': '',
+        'description': '',
+        'version': '',
+        'requires': '',
+        'requires_private': '',
+        'libs': '',
+        'libs_private': '',
+        'cflags': '',
+    }
+
+    for line in content:
+        for key in ('Name', 'Description', 'Version', 'Requires', 'Requires.private',
+                    'Libs', 'Libs.private', 'Cflags', 'URL', 'Conflicts'):
+            if line.startswith(f'{key}:'):
+                value = line[len(key)+1:].strip()
+                if key == 'Name':
+                    result['name'] = resolve_vars(value)
+                elif key == 'Description':
+                    result['description'] = resolve_vars(value)
+                elif key == 'Version':
+                    result['version'] = resolve_vars(value)
+                elif key == 'Requires':
+                    result['requires'] = resolve_vars(value)
+                elif key == 'Requires.private':
+                    result['requires_private'] = resolve_vars(value)
+                elif key == 'Libs':
+                    result['libs'] = resolve_vars(value)
+                elif key == 'Libs.private':
+                    result['libs_private'] = resolve_vars(value)
+                elif key == 'Cflags':
+                    result['cflags'] = resolve_vars(value)
+                break
+
+    return result
+
+
+def resolve_requires(pkg_name, search_paths, visited=None, define_prefix=False):
+    """Resolve all requires recursively and return combined cflags/libs."""
+    if visited is None:
+        visited = set()
+
+    if pkg_name in visited:
+        return '', '', ''
+
+    visited.add(pkg_name)
+
+    pc_path = find_pc_file(pkg_name, search_paths)
+    if not pc_path:
+        return '', '', ''
+
+    info = parse_pc_file(pc_path, define_prefix)
+
+    all_cflags = info['cflags']
+    all_libs = info['libs']
+    all_version = info['version']
+
+    # Process requires
+    for req in re.split(r'[\s,]+', info['requires']):
+        req = req.strip()
+        if not req or req == '':
+            continue
+        # Remove version constraints
+        req_name = re.split(r'[><=!\s]+', req)[0]
+        if req_name:
+            req_cflags, req_libs, _ = resolve_requires(req_name, search_paths, visited, define_prefix)
+            if req_cflags:
+                all_cflags += ' ' + req_cflags
+            if req_libs:
+                all_libs += ' ' + req_libs
+
+    # Process requires.private
+    for req in re.split(r'[\s,]+', info['requires_private']):
+        req = req.strip()
+        if not req or req == '':
+            continue
+        req_name = re.split(r'[><=!\s]+', req)[0]
+        if req_name:
+            req_cflags, req_libs, _ = resolve_requires(req_name, search_paths, visited, define_prefix)
+            if req_cflags:
+                all_cflags += ' ' + req_cflags
+            if req_libs:
+                all_libs += ' ' + req_libs
+
+    return all_cflags.strip(), all_libs.strip(), all_version
+
+
+def main():
+    parser = argparse.ArgumentParser(description='pkg-config emulator')
+    parser.add_argument('--cflags', action='store_true', help='output pre-processor and compiler flags')
+    parser.add_argument('--libs', action='store_true', help='output linker flags')
+    parser.add_argument('--modversion', action='store_true', help='output version')
+    parser.add_argument('--exists', action='store_true', help='check if package exists')
+    parser.add_argument('--static', action='store_true', help='output static linker flags')
+    parser.add_argument('--variable', type=str, help='get variable value')
+    parser.add_argument('--print-variables', action='store_true', help='print all variable names')
+    parser.add_argument('--define-prefix', action='store_true', help='override prefix with actual install location')
+    parser.add_argument('--version', action='store_true', help='output pkg-config version')
+    parser.add_argument('--atleast-version', type=str, help='check at least version')
+    parser.add_argument('--exact-version', type=str, help='check exact version')
+    parser.add_argument('--max-version', type=str, help='check max version')
+    parser.add_argument('pkg_names', nargs='*', help='package names')
+
+    args, unknown = parser.parse_known_args()
+
+    if args.version:
+        print('0.29.2')
+        sys.exit(0)
+
+    # Also parse unknown as package names (for meson's --libs --cflags pkg1 pkg2)
+    pkg_names = args.pkg_names
+    for u in unknown:
+        if not u.startswith('--'):
+            pkg_names.append(u)
+
+    search_paths = resolve_pkg_config_paths()
+
+    if not pkg_names:
+        print("No package specified", file=sys.stderr)
+        sys.exit(1)
+
+    if args.atleast_version or args.exact_version or args.max_version:
+        # version check mode
+        for pkg_name in args.pkg_names:
+            pc_path = find_pc_file(pkg_name, search_paths)
+            if not pc_path:
+                print(f"Package {pkg_name} was not found", file=sys.stderr)
+                sys.exit(1)
+            info = parse_pc_file(pc_path)
+            ver = info['version']
+            if args.atleast_version and not ver_compare(ver, '>=', args.atleast_version):
+                sys.exit(1)
+            if args.exact_version and not ver_compare(ver, '==', args.exact_version):
+                sys.exit(1)
+            if args.max_version and not ver_compare(ver, '<=', args.max_version):
+                sys.exit(1)
+        sys.exit(0)
+
+    results = []
+    for pkg_name in pkg_names:
+        pc_path = find_pc_file(pkg_name, search_paths)
+        if not pc_path:
+            print(f"Package {pkg_name} was not found in the pkg-config search path.", file=sys.stderr)
+            sys.exit(1)
+
+        if args.exists:
+            results.append((pkg_name, True))
+            continue
+
+        if args.modversion:
+            info = parse_pc_file(pc_path, args.define_prefix)
+            results.append((pkg_name, info['version']))
+            continue
+
+        if args.variable:
+            info = parse_pc_file(pc_path, args.define_prefix)
+            # Try to resolve variable value
+            if args.variable in info:
+                results.append((pkg_name, info[args.variable]))
+            else:
+                # Try to parse from content
+                with open(pc_path, 'r', encoding='utf-8', errors='replace') as f:
+                    for line in f:
+                        m = re.match(rf'^{args.variable}\s*=\s*(.*)', line)
+                        if m:
+                            val = m.group(1).strip()
+                            results.append((pkg_name, val))
+                            break
+                if not results:
+                    sys.exit(1)
+            continue
+
+        cflags, libs, _ = resolve_requires(pkg_name, search_paths, define_prefix=args.define_prefix)
+        info = parse_pc_file(pc_path, args.define_prefix)
+
+        if args.cflags:
+            val = cflags if cflags else info['cflags']
+            results.append((pkg_name, val))
+        elif args.libs:
+            val = libs if libs else info['libs']
+            if args.static:
+                if info['libs_private']:
+                    val += ' ' + info['libs_private']
+            results.append((pkg_name, val))
+        else:
+            # Default: --cflags --libs
+            cf = cflags if cflags else info['cflags']
+            lb = libs if libs else info['libs']
+            val = f"{cf} {lb}".strip()
+            results.append((pkg_name, val))
+
+    for pkg_name, value in results:
+        if isinstance(value, bool):
+            continue
+        # Filter out problematic -l:ld-musl* and -L/lib references
+        # (ld-musl is not in NDK sysroot; gettext symbols only in static libc.a)
+        filtered = re.sub(r'-l:ld-musl[^\s]*', '-l:libc.a', value)
+        filtered = re.sub(r'(?:^|\s)-L/lib(?=\s|$)', lambda m: m.group(0)[0], filtered)
+        print(filtered.strip())
+
+
+if __name__ == '__main__':
+    main()

package/node_modules/@ohos-agent/pc-adapter/templates/hap/_shared/ohpt_artifacts.h

@@ -0,0 +1,219 @@
+/*
+ * ohpt_artifacts.h — 用例产物通道（**测试载体私有，不进任何交付面**）
+ * ---------------------------------------------------------------------------
+ * 关闭的一类：**数据类库的功能产物是图像，用例只钉数据，demo 上无图可看**——
+ * 上屏证据档被纯文本日志静默满足，要人验图的页面却没有图（libaribcaption 字幕位图 →
+ * gmic BMP，同类第二次）。
+ *
+ * 通道的定义只有一句：**每条用例执行前对用例沙箱做快照、执行后对比，新出现或被改写的
+ * 文件即该用例的产物。** bytes 与 FNV-1a64 由执行器算，登记行由执行器打——证据不由
+ * 被判定者自报；接线方零协议：把图写进沙箱就够了。
+ *
+ * 登记行（机器证据，verify-demo 解析进 verify/<case>.json 的 artifacts[]）：
+ *     OHPTCASE artifact id=<case> kind=<image|file> path=<绝对沙箱路径> bytes=<n> sha=<fnv1a64 hex>
+ * 同一行文本也交回调用方拼进本条用例的原始输出——页面按 kind=image 的 path 上屏
+ *（Image('file://'+path)），file 类只列名字与大小。
+ *
+ * 由生成器复制进每个带 native 目录的 demo 工程（`entry/src/main/cpp/`）：
+ *   · cli-hnp-runner 执行器 worker：exec_case 前 snapshot(cwd) / 后 collect(cwd, id, buf, cap)
+ *   · 自驱档驱动器（ohpt_cases.h 的 ohpt_run_once）：ohpt_dispatch 前后同一对调用
+ *   · cpp-lib-demo：NAPI ohptCaseBegin(filesDir) / ohptCaseEnd(filesDir, caseId)，ArkTS runner 夹住用例调用
+ * C99 / C++ 皆可包含；单线程串行使用（worker / 驱动器都是串行的）。
+ * ---------------------------------------------------------------------------
+ */
+#ifndef OHPT_ARTIFACTS_H
+#define OHPT_ARTIFACTS_H
+
+#include <dirent.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <strings.h>
+#include <sys/stat.h>
+#include <hilog/log.h>
+
+#ifndef OHPT_ARTIFACTS_SNAPSHOT_MAX
+#define OHPT_ARTIFACTS_SNAPSHOT_MAX 512 /* 快照登记上限：沙箱里已有的文件数 */
+#endif
+#ifndef OHPT_ARTIFACTS_MAX
+#define OHPT_ARTIFACTS_MAX 64 /* 单条用例登记的产物上限（超出打 artifact-truncated 行） */
+#endif
+#ifndef OHPT_ARTIFACTS_DEPTH
+#define OHPT_ARTIFACTS_DEPTH 4 /* 递归深度上限 */
+#endif
+#define OHPT_ARTIFACTS_PATH_CAP 512
+/* 调用方收登记行文本的缓冲区大小（每行 ≤ 路径 + 键名/数值 128 字节） */
+#define OHPT_ARTIFACTS_LINES_CAP (OHPT_ARTIFACTS_MAX * (OHPT_ARTIFACTS_PATH_CAP + 128))
+
+typedef struct {
+    char path[OHPT_ARTIFACTS_PATH_CAP];
+    long long size;
+    long long mtime_ns;
+} OhptArtifactStamp;
+
+typedef struct {
+    OhptArtifactStamp items[OHPT_ARTIFACTS_SNAPSHOT_MAX];
+    int count;
+    int truncated;
+} OhptArtifactSnapshot;
+
+/* 每个包含本头的编译单元一份；worker / 驱动器串行使用，无并发写。 */
+static OhptArtifactSnapshot ohpt_artifacts_snap_;
+
+static inline long long ohpt_artifacts_mtime_ns(const struct stat* st) {
+#if defined(__APPLE__)
+    return (long long)st->st_mtimespec.tv_sec * 1000000000LL + (long long)st->st_mtimespec.tv_nsec;
+#else
+    return (long long)st->st_mtim.tv_sec * 1000000000LL + (long long)st->st_mtim.tv_nsec;
+#endif
+}
+
+typedef void (*ohpt_artifacts_visit_fn)(const char* path, const struct stat* st, void* ud);
+
+/* 递归遍历：点开头的目录/文件一律不看（.ohpt-tmp 等临时区），只登记普通文件（符号链接/设备不算产物）。 */
+static inline void ohpt_artifacts_walk(const char* dir, int depth, ohpt_artifacts_visit_fn fn, void* ud) {
+    DIR* d = opendir(dir);
+    if (!d) return;
+    struct dirent* e;
+    while ((e = readdir(d)) != NULL) {
+        if (e->d_name[0] == '.') continue;
+        char p[OHPT_ARTIFACTS_PATH_CAP];
+        if (snprintf(p, sizeof p, "%s/%s", dir, e->d_name) >= (int)sizeof p) continue;
+        struct stat st;
+        if (lstat(p, &st) != 0) continue;
+        if (S_ISDIR(st.st_mode)) {
+            if (depth < OHPT_ARTIFACTS_DEPTH) ohpt_artifacts_walk(p, depth + 1, fn, ud);
+            continue;
+        }
+        if (!S_ISREG(st.st_mode)) continue;
+        fn(p, &st, ud);
+    }
+    closedir(d);
+}
+
+static inline void ohpt_artifacts_snap_visit_(const char* path, const struct stat* st, void* ud) {
+    OhptArtifactSnapshot* s = (OhptArtifactSnapshot*)ud;
+    if (s->count >= OHPT_ARTIFACTS_SNAPSHOT_MAX) {
+        s->truncated = 1;
+        return;
+    }
+    OhptArtifactStamp* it = &s->items[s->count++];
+    snprintf(it->path, sizeof it->path, "%s", path);
+    it->size = (long long)st->st_size;
+    it->mtime_ns = ohpt_artifacts_mtime_ns(st);
+}
+
+/** 执行前：登记沙箱 root 的现状（root 不存在也合法：之后写下的一切都算产物）。 */
+static inline void ohpt_artifacts_snapshot(const char* root) {
+    ohpt_artifacts_snap_.count = 0;
+    ohpt_artifacts_snap_.truncated = 0;
+    if (root && root[0]) ohpt_artifacts_walk(root, 0, ohpt_artifacts_snap_visit_, &ohpt_artifacts_snap_);
+}
+
+static inline int ohpt_artifacts_unchanged_(const char* path, const struct stat* st) {
+    int i;
+    for (i = 0; i < ohpt_artifacts_snap_.count; i++) {
+        const OhptArtifactStamp* it = &ohpt_artifacts_snap_.items[i];
+        if (strcmp(it->path, path) == 0) {
+            return it->size == (long long)st->st_size && it->mtime_ns == ohpt_artifacts_mtime_ns(st);
+        }
+    }
+    return 0; /* 快照里没有 = 本条用例新写下的 */
+}
+
+/** 扩展名 → kind。**分类只在这一处**：image 即 ArkUI Image 能解码的格式，其余一律 file。 */
+static inline const char* ohpt_artifacts_kind(const char* path) {
+    static const char* const image_ext[] = {"bmp", "png", "jpg", "jpeg", "webp", "gif", "heic", "svg"};
+    const char* dot = strrchr(path, '.');
+    const char* slash = strrchr(path, '/');
+    size_t i;
+    if (!dot || (slash && dot < slash) || dot[1] == '\0') return "file";
+    for (i = 0; i < sizeof image_ext / sizeof image_ext[0]; i++) {
+        if (strcasecmp(dot + 1, image_ext[i]) == 0) return "image";
+    }
+    return "file";
+}
+
+/** 文件内容 FNV-1a 64（可区分性的字节级证据）；bytes 收文件长度。 */
+static inline uint64_t ohpt_artifacts_fnv1a64(const char* path, long long* bytes) {
+    uint64_t h = 1469598103934665603ULL;
+    unsigned char buf[8192];
+    size_t n;
+    long long total = 0;
+    FILE* f = fopen(path, "rb");
+    if (bytes) *bytes = 0;
+    if (!f) return 0;
+    while ((n = fread(buf, 1, sizeof buf, f)) > 0) {
+        size_t i;
+        total += (long long)n;
+        for (i = 0; i < n; i++) {
+            h ^= (uint64_t)buf[i];
+            h *= 1099511628211ULL;
+        }
+    }
+    fclose(f);
+    if (bytes) *bytes = total;
+    return h;
+}
+
+typedef struct {
+    const char* case_id;
+    char* out;
+    size_t cap;
+    size_t len;
+    int count;
+    int truncated;
+} OhptArtifactCollect_;
+
+static inline void ohpt_artifacts_collect_visit_(const char* path, const struct stat* st, void* ud) {
+    OhptArtifactCollect_* c = (OhptArtifactCollect_*)ud;
+    long long bytes = 0;
+    uint64_t h;
+    const char* kind;
+    char line[OHPT_ARTIFACTS_PATH_CAP + 128];
+    int n;
+    if (ohpt_artifacts_unchanged_(path, st)) return;
+    if (c->count >= OHPT_ARTIFACTS_MAX) {
+        c->truncated = 1;
+        return;
+    }
+    h = ohpt_artifacts_fnv1a64(path, &bytes);
+    kind = ohpt_artifacts_kind(path);
+    /* 机器证据：hilog（tag OHPTCASE，与 check/result 行同通道） */
+    OH_LOG_Print(LOG_APP, LOG_INFO, 0x0000, "OHPTCASE",
+                 "artifact id=%{public}s kind=%{public}s path=%{public}s bytes=%{public}lld sha=%{public}016llx",
+                 c->case_id ? c->case_id : "unknown", kind, path, bytes, (unsigned long long)h);
+    /* 同文本交回调用方（页面上屏用） */
+    n = snprintf(line, sizeof line, "OHPTCASE artifact id=%s kind=%s path=%s bytes=%lld sha=%016llx\n",
+                 c->case_id ? c->case_id : "unknown", kind, path, bytes, (unsigned long long)h);
+    if (n > 0 && c->out && c->cap > 0 && c->len + (size_t)n < c->cap) {
+        memcpy(c->out + c->len, line, (size_t)n);
+        c->len += (size_t)n;
+        c->out[c->len] = '\0';
+    }
+    c->count++;
+}
+
+/**
+ * 执行后：对比快照，登记本条用例写下的文件。返回登记条数。
+ * out/cap 可为 NULL/0（只打 hilog）；给了则收到「OHPTCASE artifact …\n」文本，供拼进本条原始输出。
+ */
+static inline int ohpt_artifacts_collect(const char* root, const char* case_id, char* out, size_t cap) {
+    OhptArtifactCollect_ c;
+    memset(&c, 0, sizeof c);
+    c.case_id = case_id;
+    c.out = out;
+    c.cap = cap;
+    if (out && cap > 0) out[0] = '\0';
+    if (root && root[0]) ohpt_artifacts_walk(root, 0, ohpt_artifacts_collect_visit_, &c);
+    if (c.truncated || ohpt_artifacts_snap_.truncated) {
+        /* 不是 artifact 行（解析端不收），只说明登记不完整 */
+        OH_LOG_Print(LOG_APP, LOG_WARN, 0x0000, "OHPTCASE",
+                     "artifact-truncated id=%{public}s max=%{public}d snapshot_truncated=%{public}d",
+                     case_id ? case_id : "unknown", OHPT_ARTIFACTS_MAX, ohpt_artifacts_snap_.truncated);
+    }
+    return c.count;
+}
+
+#endif /* OHPT_ARTIFACTS_H */

package/node_modules/@ohos-agent/pc-adapter/templates/hap/_shared/ohpt_case_loop.h

@@ -0,0 +1,94 @@
+/*
+ * ohpt_case_loop.h — 用例常驻派发循环（**测试载体私有，不进任何交付面**）
+ * ---------------------------------------------------------------------------
+ * 关闭的一类：**载体不得成为被测物的一部分，也不得为了自己好写去改被测物。**
+ *
+ * OWB（`deps/ohos-window-bridge/`）是**适配产物的一部分**——被测库的鸿蒙后端直接调它，
+ * 交付面 `harmony-demo/` 也编译它。所以本文件只用 OWB 的公开 API，不加 NAPI 导出、
+ * 不改 `owb_ohos_app.h`、不碰 `ohos_window_bridge.h`。派发与回传都走应用私有沙箱文件——
+ * 那条通道 `ohpt_cases.h` 早已接线（EntryAbility.onCreate 就在写它），只是此前
+ * `main()` 跑完就 return，于是「一个进程只跑得了一条」。
+ *
+ * 用它带来的三件事（都是删分支，不是加分支）：
+ *   · 画面**常驻**——此前渲染 5~10 帧 ≈ 80~160ms 就退出，人眼来不及看，而 render 档
+ *     恰恰是唯一必须靠人看的档；
+ *   · 一个进程跑得了 N 条 —— `cases.json` 的 `run_all.supported` 对 gui 档也成立，
+ *     宿主不必再退回 N 次冷启动（GLFW 实测 80 次 → 1 次）；
+ *   · 参数能从页面传进来 —— 请求原文是 `<case-id>[ k=v ...]`，用 `ohpt_param_int()` 取。
+ *
+ * 用法（被测入口 .c/.cpp）：
+ *     #include "ohos_window_bridge.h"
+ *     #include "owb_ohos_app.h"        // OWB 的入口便利层，照用不改
+ *     #include "ohpt_cases.h"          // scaffold --test-cases 生成
+ *     #include "ohpt_case_loop.h"
+ *
+ *     static void ohpt_run_case(const char* req, int ci);   // 你写这个
+ *     static void ohpt_keepalive(void);                     // 你写这个（常驻渲染一帧）
+ *     OHPT_CASE_MAIN()                                      // 展开成 main()
+ *     OWB_OHOS_THREAD_APP("你的 XComponent libraryname")
+ * ---------------------------------------------------------------------------
+ */
+#ifndef OHPT_CASE_LOOP_H
+#define OHPT_CASE_LOOP_H
+
+#include <stdio.h>
+#include <string.h>
+#include <unistd.h>
+
+#ifndef OHPT_POLL_INTERVAL_US
+#define OHPT_POLL_INTERVAL_US (100 * 1000) /* 100ms：人无感，且不跟渲染抢 CPU */
+#endif
+
+/* 结果回传文件：native 写、ArkTS 轮询读，显示在用例页的「实际:」一行。
+ * 与请求文件同目录同机制——两个方向都是已接线的沙箱通道。 */
+static const char* const OHPT_RESULT_PATHS[] = {
+    "/data/storage/el2/base/haps/entry/files/ohpt-result",
+    "/data/storage/el2/base/files/ohpt-result",
+};
+
+/**
+ * 把本轮观测值回传给页面（纯文本，页面原样展示）。
+ * **展示什么就写什么**：写死的「成功」这类文案对人工验收毫无价值——人要看的是被测物的真实返回。
+ */
+static void ohpt_write_result(const char* caseId, const char* text) {
+    for (size_t i = 0; i < sizeof(OHPT_RESULT_PATHS) / sizeof(OHPT_RESULT_PATHS[0]); i++) {
+        FILE* f = fopen(OHPT_RESULT_PATHS[i], "w");
+        if (!f) continue;
+        fprintf(f, "%s\n%s\n", caseId ? caseId : "", text ? text : "");
+        fclose(f);
+    }
+}
+
+/**
+ * 常驻主循环。**不退出**——跑完一条继续等下一条，其余时间保持渲染。
+ *
+ * 去重按请求原文而非用例 id：同一条用例换了参数（`F-03-01 w=900 h=600` → `w=640 h=480`）
+ * 必须重跑，否则页面上改了参数点执行会毫无反应。
+ */
+#define OHPT_CASE_MAIN()                                                        \
+    int main(int argc, char** argv) {                                           \
+        (void)argc;                                                             \
+        (void)argv;                                                             \
+        OWB_Initialize();                                                       \
+        if (OWB_WaitForSurface(-1) != OWB_OK) return 1;                         \
+        char last[256];                                                         \
+        last[0] = '\0';                                                         \
+        for (;;) {                                                              \
+            char req[256];                                                      \
+            if (ohpt_read_case_request(req, sizeof(req)) && strcmp(req, last) != 0) { \
+                snprintf(last, sizeof(last), "%s", req);                        \
+                int ci = ohpt_case_index_of(req);                               \
+                if (ci >= 0) {                                                  \
+                    ohpt_run_case(req, ci);                                     \
+                } else {                                                        \
+                    OH_LOG_Print(LOG_APP, LOG_INFO, 0x0000, "OHPTCASE",         \
+                                 "unknown request=%{public}s", req);            \
+                }                                                               \
+            }                                                                   \
+            ohpt_keepalive();                                                   \
+            usleep(OHPT_POLL_INTERVAL_US);                                      \
+        }                                                                       \
+        return 0;                                                               \
+    }
+
+#endif /* OHPT_CASE_LOOP_H */