cj-tauri 1.1.2 → 2.0.0

package/src/host_webkit.cj

@@ -6,6 +6,10 @@ package cjTauri
 @When[os == "Linux" && env != "ohos"]
 import std.collection.*
 
+// 页面来源契约（load(source) 收敛，RFC §4.3）：同款门禁，免得别的目标把这条当未使用清掉
+@When[os == "Linux" && env != "ohos"]
+import cjTauri.platform.*
+
 /**
  * C 桥 FFI 声明（native/libcjtbridge.so）
  * 所有 GTK/WebKit 调用在 C 桥的原生 pthread 内执行（见 native/bridge_linux.c 头注释）。
@@ -198,6 +202,8 @@ public class WebKitHost <: WebViewHost {
     // 本窗口的 label（字段名不叫 label：接口有同名方法）。单窗口阶段是常量，
     // 与 TauriApp 注册的 WindowRecord.label 一致；多窗口时由构造参数给定。
     private let windowLabel: String
+    // 资产解析器：装配层在 load 前注入（None = 按 cwd 相对路径读盘，与批次 1 行为等价）
+    private var assetResolver: Option<AssetResolver> = None
 
     public init() {
         this.windowLabel = DEFAULT_WINDOW_LABEL
@@ -482,6 +488,22 @@ public class WebKitHost <: WebViewHost {
         }
     }
 
+    /**
+     * 加载页面（唯一入口，RFC §4.3）：Inline/Url/DevServer 直接映射；
+     * Asset 经注入的 resolver 读盘，未注入时按 cwd 相对路径读（批次 1 的桌面行为）
+     */
+    public func load(source: PageSource): Unit {
+        match (resolvePage(source, this.assetResolver)) {
+            case StartHtml(html) => this.start(html)
+            case StartUrl(url) => this.startUrl(url)
+        }
+    }
+
+    /** 注入资产解析器（装配层在 load 前调用） */
+    public func setAssetResolver(resolver: Option<AssetResolver>): Unit {
+        this.assetResolver = resolver
+    }
+
     public func start(html: String): Unit {
         this.prepareHost()
         unsafe {

package/src/host_webview2.cj

@@ -4,6 +4,10 @@ package cjTauri
 @When[os == "Windows"]
 import std.collection.*
 
+// 页面来源契约（load(source) 收敛，RFC §4.3）：同款门禁，免得别的目标把这条当未使用清掉
+@When[os == "Windows"]
+import cjTauri.platform.*
+
 /**
  * C 桥 FFI 声明（native/libcjtbridge.dll）
  * Win32 窗口 + WebView2（Edge Chromium）在 C 桥的宿主线程内运行（见 native/bridge_win.c 头注释）。
@@ -200,6 +204,8 @@ public class WebView2Host <: WebViewHost {
     // 本窗口的 label（字段名不叫 label：接口有同名方法）。单窗口阶段是常量，
     // 与 TauriApp 注册的 WindowRecord.label 一致；多窗口时由构造参数给定。
     private let windowLabel: String
+    // 资产解析器：装配层在 load 前注入（None = 按 cwd 相对路径读盘，与批次 1 行为等价）
+    private var assetResolver: Option<AssetResolver> = None
 
     public init() {
         this.windowLabel = DEFAULT_WINDOW_LABEL
@@ -482,6 +488,22 @@ public class WebView2Host <: WebViewHost {
         }
     }
 
+    /**
+     * 加载页面（唯一入口，RFC §4.3）：Inline/Url/DevServer 直接映射；
+     * Asset 经注入的 resolver 读盘，未注入时按 cwd 相对路径读（批次 1 的桌面行为）
+     */
+    public func load(source: PageSource): Unit {
+        match (resolvePage(source, this.assetResolver)) {
+            case StartHtml(html) => this.start(html)
+            case StartUrl(url) => this.startUrl(url)
+        }
+    }
+
+    /** 注入资产解析器（装配层在 load 前调用） */
+    public func setAssetResolver(resolver: Option<AssetResolver>): Unit {
+        this.assetResolver = resolver
+    }
+
     public func start(html: String): Unit {
         this.prepareHost()
         unsafe {

package/src/launch.cj

@@ -0,0 +1,62 @@
+package cjTauri
+
+import cjTauri.platform.*
+import stdx.encoding.json.JsonValue
+
+/**
+ * 三段式 API 的第二段（批次 3，RFC-002 §4.2）
+ *
+ * 业务入口全文就这几行：
+ * ```
+ * import cjTauri.*
+ * main(): Int64 {
+ *     launch(build())
+ *     return 0
+ * }
+ * ```
+ *
+ * `Platform.discover()` 是唯一「端在哪儿」的知识入口（§5.1）；
+ * 桌面阻塞主循环，移动端的非 UI 线程 spawn 由宿主负责（§4.2 鸿蒙示例）。
+ *
+ * 与 RFC 示意写法的偏差（照实记录）：两个重载代替默认参数
+ * （当前工具链不用默认参数），`launchWith` 供测试注入假上下文、
+ * 鸿蒙 Ability 触发时给移动端上下文。
+ */
+public func launch(spec: AppSpec): Unit {
+    let target = Platform.guessTarget()
+    launchWith(spec, Platform.discover(spec.appId, target.arch))
+}
+
+/** 注入上下文的变体：测试给假上下文；鸿蒙侧给 Platform.mobile(filesDir) */
+public func launchWith(spec: AppSpec, context: AppContext): Unit {
+    eprintln("[cj-tauri] launch：${spec.name}（os=${context.target.os} display=${context.target.display}）")
+    let app = assemble(spec)
+    app.run(spec.pageSource)
+}
+
+/**
+ * spec → TauriApp（纯装配、不 run）：launch 与单测共用
+ *
+ * 装配顺序即框架契约顺序：窗口配置 → 插件 → 资产解析器 → 能力目录 → 业务命令（wire）。
+ */
+public func assemble(spec: AppSpec): TauriApp {
+    let app = TauriApp().window(spec.windowConfig)
+    for (p in spec.plugins) {
+        app.plugin(p)
+    }
+    if (spec.assetResolver.isSome()) {
+        app.assets(spec.assetResolver.getOrThrow())
+    }
+    if (spec.capabilitiesDir.size > 0) {
+        app.loadCapabilities(spec.capabilitiesDir)
+    }
+    // 能力清单 JSON 走与显式挂载同一入口：鸿蒙胶水把 rawfile 原文传进来（批次 3-PR3）
+    for (j in spec.capabilityJsons) {
+        app.addCapabilityJson(JsonValue.fromStr(j))
+    }
+    if (spec.wireFn.isSome()) {
+        let f = spec.wireFn.getOrThrow()
+        f(app)
+    }
+    return app
+}

package/src/platform/platform_app_context.cj

@@ -0,0 +1,77 @@
+package cjTauri.platform
+
+import std.collection.ArrayList
+
+/**
+ * 应用可写目录（RFC-002 §5.2）
+ *
+ * 默认跟应用 id 走平台规范目录（XDG / AppData / filesDir），不落可执行文件旁边；
+ * 便携版（数据跟 exe）是显式选项，由骨架构建期注入，见 RFC §5.2。
+ * Windows 下统一用 "/" 分隔符（Windows API 均接受），减少按端拼路径的分支。
+ */
+public class AppPaths {
+    public let dataDir: String   // 收藏库、状态等持久数据
+    public let cacheDir: String  // 可清理缓存
+    public let tempDir: String   // 本次运行临时文件
+
+    public init(dataDir: String, cacheDir: String, tempDir: String) {
+        this.dataDir = dataDir
+        this.cacheDir = cacheDir
+        this.tempDir = tempDir
+    }
+}
+
+/**
+ * 运行时上下文（RFC-002 §4.5）——框架在 launch() 里构建，业务只读
+ *
+ * supports() 是业务唯一的平台判断入口；target 字段仅供日志与埋点，
+ * code review 里出现「按 target.os 分支」应被拒绝（RFC 硬约束 1）。
+ */
+public class AppContext {
+    public let paths: AppPaths
+    public let target: TargetInfo
+    /** 开发期：资产优先读盘、允许 DevServer */
+    public let dev: Bool
+    private let features: ArrayList<PlatformFeature>
+
+    public init(paths: AppPaths, target: TargetInfo, dev: Bool, features: ArrayList<PlatformFeature>) {
+        this.paths = paths
+        this.target = target
+        this.dev = dev
+        this.features = features
+    }
+
+    /** 特性探测：批次 0 用线性扫（特性位数 ≤ 十几，不值得上哈希表） */
+    public func supports(f: PlatformFeature): Bool {
+        for (item in features) {
+            if (PlatformFeature.same(item, f)) {
+                return true
+            }
+        }
+        return false
+    }
+
+    /** 供日志输出：本端支持哪些特性位（降级行为要可观测，见 RFC §8） */
+    public func describeFeatures(): String {
+        let sb = StringBuilder()
+        var first = true
+        for (item in features) {
+            if (!first) {
+                sb.append(", ")
+            }
+            first = false
+            sb.append(featureName(item))
+        }
+        return sb.toString()
+    }
+
+    private static func featureName(f: PlatformFeature): String {
+        match (f) {
+            case Tray => "Tray"
+            case MultiWindow => "MultiWindow"
+            case FilePicker => "FilePicker"
+            case ClipboardImage => "ClipboardImage"
+            case SoftKeyboardInset => "SoftKeyboardInset"
+        }
+    }
+}

package/src/platform/platform_assets.cj

@@ -0,0 +1,33 @@
+package cjTauri.platform
+
+import std.fs.*
+
+/**
+ * 目录型资产解析器（RFC §6.2）：桌面开发期 / 发布读盘路径的默认实现
+ *
+ * root 为资产根（清单 [assets] root），逻辑名按 <root>/<name> 相对寻址。
+ * 沙箱端实现（鸿蒙 rawfile / 内嵌常量）在各自适配层，批次 3 随清单派生接入。
+ */
+public class DirectoryAssetResolver <: AssetResolver {
+    private let root: String
+
+    public init(root: String) {
+        this.root = root
+    }
+
+    public func readText(name: String): Option<String> {
+        try {
+            return Some(String.fromUtf8(File.readFrom(root + "/" + name)))
+        } catch (e: Exception) {
+            return None
+        }
+    }
+
+    /** 以「能否读到」为准（批次 2 只服务文本资产；图标等二进制走各端资源目录，不进常量表） */
+    public func exists(name: String): Bool {
+        match (readText(name)) {
+            case Some(_) => return true
+            case None => return false
+        }
+    }
+}

package/src/platform/platform_discover.cj

@@ -0,0 +1,176 @@
+package cjTauri.platform
+
+import std.env.*
+import std.collection.ArrayList
+
+/**
+ * 平台发现（RFC-002 §4.2 / §5.3）——全框架唯一的「端在哪儿」知识入口
+ *
+ * 按约定（RFC §5.3），os 名匹配的 @When 只允许出现在本文件与 targets 目录下的生成胶水；
+ * CI 用 `grep -r '@When\[os' src/ | grep -v src/platform/` 守这条线。
+ * @When 分支一律成对出现（本仓库惯例，参照 host_webview2.cj），保证任何目标下每个
+ * 符号恰好有一个定义；跨平台文件里只用短名。
+ *
+ * 批次 0 边界：本文件只提供**可编译的默认实现**（桌面 Linux / Windows 实测，
+ * 鸿蒙走 mobile(filesDir)），特性位清单是占位值，接端时按实测修正。
+ */
+public class Platform {
+    /**
+     * 桌面端默认发现：paths 走平台规范目录（RFC §5.2），dev 看 CJ_TAURI_DEV_URL
+     *
+     * arch 默认 x86_64；ARM64 Linux 桌面请显式传 arch（它的 os 与 x86_64 Linux 相同，
+     * 这是仓库已知的「同 os 多宿主」来源，见 RFC §5.1）。
+     * appId 由 launch() 从清单传入（清单解析在批次 1 落地，见 RFC §3/§13.1 风险 1）。
+     */
+    public static func discover(appId: String, arch: String): AppContext {
+        return desktop(appId, arch)
+    }
+
+    public static func desktop(appId: String, arch: String): AppContext {
+        let data = "${dataRoot()}/${appId}"
+        let target = TargetInfo(desktopOs(), arch, desktopHostKind(), "desktop")
+        let fs = ArrayList<PlatformFeature>()
+        fs.add(PlatformFeature.MultiWindow)
+        fs.add(PlatformFeature.FilePicker)
+        fs.add(PlatformFeature.ClipboardImage)
+        fs.add(PlatformFeature.Tray)
+        return AppContext(
+            AppPaths(data, "${cacheRoot()}/${appId}", "${cacheRoot()}/${appId}/tmp"),
+            target, devMode(), fs)
+    }
+
+    /**
+     * 移动端发现：沙箱目录由系统能力入口传入（鸿蒙 Ability 的 filesDir / Android 的 filesDir）
+     *
+     * 沙箱端没有 dev server，dev 恒为 false；hostKind 是占位（鸿蒙 ArkWeb，
+     * Android 接入时由其 Provider 决定），特性位清单接端实测后修正。
+     */
+    public static func mobile(filesDir: String, arch: String): AppContext {
+        let target = TargetInfo("Linux", arch, "arkweb", "mobile")
+        let fs = ArrayList<PlatformFeature>()
+        fs.add(PlatformFeature.MultiWindow)
+        fs.add(PlatformFeature.ClipboardImage)
+        fs.add(PlatformFeature.SoftKeyboardInset)
+        return AppContext(
+            AppPaths(filesDir, "${filesDir}/cache", "${filesDir}/cache/tmp"),
+            target, false, fs)
+    }
+
+    // ---- 平台名与目录根：@When 成对门禁，只落在这几个函数（RFC §5.3）----
+
+    /** dev server 探测：子包不引用父包，直接读环境变量（与 TauriApp.devUrl() 同语义） */
+    private static func devMode(): Bool {
+        if (let Some(v) <- getVariable("CJ_TAURI_DEV_URL")) {
+            if (v.size > 0) {
+                return true
+            }
+        }
+        return false
+    }
+
+    /**
+     * 当前目标的 TargetInfo（批次 1：装配层 resolveHost 用它选宿主）
+     *
+     * ohos 报 HarmonyOS/arkweb/mobile（运行时 os 虽取 Linux，语义归鸿蒙）；
+     * arch 从 CJ_TAURI_ARCH 环境变量取——编译期拿不到可靠的 arch，
+     * 由 hvigor / CLI 构建时注入（未注入为 unknown，宿主选择请勿依赖 arch，
+     * 用 hostKind/display 区分——它们正是为「同 os 多宿主」设计的）。
+     */
+    public static func guessTarget(): TargetInfo {
+        let arch = getVariable("CJ_TAURI_ARCH") ?? "unknown"
+        return TargetInfo(currentOs(), arch, currentHostKind(), currentDisplay())
+    }
+
+    @When[env == "ohos"]
+    private static func currentOs(): String {
+        return "HarmonyOS"
+    }
+
+    @When[env != "ohos"]
+    private static func currentOs(): String {
+        return desktopOs()
+    }
+
+    @When[env == "ohos"]
+    private static func currentHostKind(): String {
+        return "arkweb"
+    }
+
+    @When[env != "ohos"]
+    private static func currentHostKind(): String {
+        return desktopHostKind()
+    }
+
+    @When[env == "ohos"]
+    private static func currentDisplay(): String {
+        return "mobile"
+    }
+
+    @When[env != "ohos"]
+    private static func currentDisplay(): String {
+        return "desktop"
+    }
+
+    @When[os == "Windows"]
+    private static func desktopOs(): String {
+        return "Windows"
+    }
+
+    @When[os != "Windows"]
+    private static func desktopOs(): String {
+        return "Linux"
+    }
+
+    @When[os == "Windows"]
+    private static func desktopHostKind(): String {
+        return "webview2"
+    }
+
+    @When[os != "Windows"]
+    private static func desktopHostKind(): String {
+        return "webkitgtk"
+    }
+
+    @When[os == "Windows"]
+    private static func dataRoot(): String {
+        return getVariable("APPDATA") ?? "."
+    }
+
+    @When[os == "Windows"]
+    private static func cacheRoot(): String {
+        return getVariable("LOCALAPPDATA") ?? "."
+    }
+
+    @When[os == "Linux" && env != "ohos"]
+    private static func dataRoot(): String {
+        return getVariable("XDG_DATA_HOME") ?? "${getVariable("HOME") ?? "."}/.local/share"
+    }
+
+    @When[os == "Linux" && env != "ohos"]
+    private static func cacheRoot(): String {
+        return getVariable("XDG_CACHE_HOME") ?? "${getVariable("HOME") ?? "."}/.cache"
+    }
+
+    // ohos 目标上 desktop() 不会被调用，但符号必须存在才能编译；
+    // 返回占位值，真机路径由 mobile(filesDir) 提供。
+    @When[env == "ohos"]
+    private static func dataRoot(): String {
+        return "."
+    }
+
+    @When[env == "ohos"]
+    private static func cacheRoot(): String {
+        return "."
+    }
+
+    // 其余目标（macOS 等）暂按 HOME 兜底：接入对应端时在这里补实现并真机验证。
+    @When[os != "Windows" && os != "Linux"]
+    private static func dataRoot(): String {
+        return "${getVariable("HOME") ?? "."}/.local/share"
+    }
+
+    @When[os != "Windows" && os != "Linux"]
+    private static func cacheRoot(): String {
+        return "${getVariable("HOME") ?? "."}/.cache"
+    }
+}

package/src/platform/platform_env.cj

@@ -0,0 +1,29 @@
+package cjTauri.platform
+
+import std.collection.ArrayList
+
+/**
+ * L0 适配层契约（RFC-002 §5.1）——每端各实现一份，框架只依赖这些接口
+ *
+ * 这些接口**不是给业务用的**：业务拿到的只有 AppContext。
+ * 批次 1 接入装配层时，Platform.discover() 会按端挑选实现。
+ */
+
+/** 资产读取：按逻辑名取内容（读盘 / 内嵌常量 / rawfile 由实现决定） */
+public interface AssetResolver {
+    func readText(name: String): Option<String>
+    func exists(name: String): Bool
+}
+
+/** 目录与特性发现：沙箱端必须实现，桌面端由 Platform 给默认 */
+public interface PlatformEnv {
+    func paths(appId: String): AppPaths
+    func assets(root: String): AssetResolver
+    /** RFC 写 Set<PlatformFeature>；批次 0 用 ArrayList 近似，接口定型时统一替换 */
+    func features(): ArrayList<PlatformFeature>
+}
+
+/** 页面材化：把 Asset 逻辑名变成宿主可加载的形态（L0 内部细节） */
+public interface PageMaterializer {
+    func resolve(asset: String, page: String): PageSource
+}

package/src/platform/platform_feature.cj

@@ -0,0 +1,31 @@
+package cjTauri.platform
+
+/**
+ * 平台特性位（RFC-002 §4.5）——业务判断"这个端有没有某设施"的唯一手段
+ *
+ * 命名约定（评审定稿）：**看到 PlatformFeature 只谈可用性，看到 Capability 只谈权限**。
+ * - 平台特性 = 本枚举：这个端的系统设施有没有（托盘、文件选择器……）；
+ * - 安全能力 = CapabilitySet（capability.cj）：哪条命令允许被前端调用。
+ * 两者中文都容易被叫成"能力"，类型名必须分开，否则会退化回 os 分支。
+ *
+ * 治理规则（RFC §13.2 问题 4）：新增一个特性位，必须同时写清三端语义与缺省降级行为，
+ * 否则业务会把它当成按 OS 名分支的马甲。
+ */
+public enum PlatformFeature {
+    | Tray               // 托盘
+    | MultiWindow        // 多窗口（桌面）/ 多任务（移动端）
+    | FilePicker         // 系统文件选择器
+    | ClipboardImage     // 剪贴板图片读写
+    | SoftKeyboardInset  // 软键盘遮挡可感知（移动端）
+
+    /** 枚举无内建 ==（1.2.0 实测），比较走模式匹配 */
+    public static func same(a: PlatformFeature, b: PlatformFeature): Bool {
+        match (a) {
+            case Tray => match (b) { case Tray => true case _ => false }
+            case MultiWindow => match (b) { case MultiWindow => true case _ => false }
+            case FilePicker => match (b) { case FilePicker => true case _ => false }
+            case ClipboardImage => match (b) { case ClipboardImage => true case _ => false }
+            case SoftKeyboardInset => match (b) { case SoftKeyboardInset => true case _ => false }
+        }
+    }
+}

package/src/platform/platform_page_source.cj

@@ -0,0 +1,87 @@
+package cjTauri.platform
+
+import std.fs.*
+
+/**
+ * 页面来源（RFC-002 §4.3）——取代 run(html) / runUrl(url) 双入口的唯一表达
+ *
+ * 业务与清单只写 Asset("ui/index.html") 这一种；devMode 下由框架改写为
+ * DevServer；Asset 在各端怎么落地（读盘 / rawfile 材化 / assets base URL）
+ * 是 L0 适配层（PageMaterializer）的事，业务与骨架都不接触沙箱路径。
+ */
+public enum PageSource {
+    /** 代码里直接给的 HTML 字符串（探针、错误页用） */
+    | Inline(String)
+    /** 资产逻辑名，如 "ui/index.html"（sync 生成期校验存在，见 RFC §6.1） */
+    | Asset(String)
+    /** http(s):// 或 file:// 直载 */
+    | Url(String)
+    /** 开发期前端 dev server（HMR），由 CJ_TAURI_DEV_URL 注入 */
+    | DevServer(String)
+}
+
+/** 解析结果：宿主最终执行的动作（纯数据，可测） */
+public enum PageLoad {
+    | StartHtml(String)  // host.start(html)
+    | StartUrl(String)   // host.startUrl(url)
+}
+
+/**
+ * PageSource → PageLoad 的唯一决策点（批次 1，RFC §4.3）
+ *
+ * - Inline / Url / DevServer：直接映射
+ * - Asset：优先走注入的 AssetResolver；未注入时按 cwd 相对路径读盘——与现有模板
+ *   textOrFile 的桌面行为等价，鸿蒙 rawfile / 内嵌常量的实现在批次 2 随清单接入
+ * - 找不到资产：抛可照做的错误，不静默白屏（与宿主装配「不静默回落」同约定）
+ */
+
+/** 资产解析异常：message 即面向用户的措辞。子包不引用根包的 CommandException
+ *  （那会构成父↔子互引），独立定义；传播路径与原先一致（run() 路径上无人
+ *  按具体类型捕获，message 原样抛到顶层） */
+public class AssetResolutionException <: Exception {
+    public init(msg: String) {
+        super(msg)
+    }
+}
+
+public func resolvePage(source: PageSource, resolver: Option<AssetResolver>): PageLoad {
+    match (source) {
+        case Inline(html) => return PageLoad.StartHtml(html)
+        case Url(url) => return PageLoad.StartUrl(url)
+        case DevServer(url) => return PageLoad.StartUrl(url)
+        case Asset(name) =>
+            match (resolver) {
+                case Some(r) =>
+                    match (r.readText(name)) {
+                        case Some(html) => return PageLoad.StartHtml(html)
+                        case None =>
+                            throw AssetResolutionException("资产未找到：${name}（请检查注入的 AssetResolver 与清单 [assets] 配置）")
+                    }
+                case None =>
+                    var text = ""
+                    try {
+                        text = String.fromUtf8(File.readFrom(name))
+                    } catch (e: Exception) {
+                        throw AssetResolutionException("资产未找到：${name}（未注入 AssetResolver，按相对路径读盘失败：${e}；鸿蒙 rawfile / 内嵌场景请注入对应解析器）")
+                    }
+                    return PageLoad.StartHtml(text)
+            }
+    }
+}
+
+/**
+ * devMode 改写（RFC §4.3）：CJ_TAURI_DEV_URL 存在时，Asset 页面自动改走 dev server
+ *
+ * 只改 Asset：显式 Inline（探针）/ Url / DevServer 是业务明说的意图，不改写。
+ * 纯函数，可测。
+ */
+public func rewriteForDev(source: PageSource, devUrl: Option<String>): PageSource {
+    match (devUrl) {
+        case Some(url) =>
+            match (source) {
+                case Asset(_) => return PageSource.DevServer(url)
+                case _ => return source
+            }
+        case None => return source
+    }
+}

package/src/platform/platform_target_info.cj

@@ -0,0 +1,32 @@
+package cjTauri.platform
+
+/**
+ * 平台自述（RFC-002 §5.1）
+ *
+ * 供宿主选择、资产策略、日志与埋点共用；**业务不得据此分支**——
+ * 业务判断"这个端有没有某设施"请走 AppContext.supports(PlatformFeature)。
+ *
+ * 为什么 os 是字符串而不是枚举：宿主实现由 L0 注册（HostProvider），框架核心
+ * 不 import 任何平台包；批次 1 接入 createHost 时会给出各端的取值常量。
+ */
+public class TargetInfo {
+    /** "Windows" / "Linux" / "HarmonyOS" / "macOS" / "Android"（鸿蒙与 Linux 桌面都会报 Linux，靠 hostKind 区分） */
+    public let os: String
+    /** "x86_64" / "aarch64" */
+    public let arch: String
+    /** "webkitgtk" / "webview2" / "arkweb" / "wkwebview" / "android-webview" */
+    public let hostKind: String
+    /** "desktop" / "mobile"：只决定窗口语义（桌面多窗、移动端多任务），不决定能力位 */
+    public let display: String
+
+    public init(os: String, arch: String, hostKind: String, display: String) {
+        this.os = os
+        this.arch = arch
+        this.hostKind = hostKind
+        this.display = display
+    }
+
+    public func describe(): String {
+        "${os}/${arch} host=${hostKind} display=${display}"
+    }
+}