cj-tauri 1.1.2 → 2.0.0

package/cli/templates/{ohos-pc → ohos-skeleton}/entry/src/main/module.json5

@@ -1,49 +1,49 @@
-{
-  "module": {
-    "name": "entry",
-    "type": "entry",
-    "description": "$string:module_desc",
-    "mainElement": "EntryAbility",
-    /* 鸿蒙 PC 必须声明 "2in1"：只写 phone/tablet 时系统按手机应用处理，窗口是竖屏兼容窗。
-       构建插件默认把 deviceTypes 限制成 phone/tablet，靠 entry/build-profile.json5 的
-       cangjieOptions.checkDeviceTypes=false 放行。 */
-    "deviceTypes": [
-      "2in1",
-      "tablet",
-      "phone"
-    ],
-    "deliveryWithInstall": true,
-    /* 网上取数据（http/https）都需要这条：缺它时请求死在
-       `SocketException: Failed to create socket: Operation not permitted.`，
-       页面上表现为「连不上后台」，看着像网络不通。用不到就删掉这一条。 */
-    "requestPermissions": [
-      {
-        "name": "ohos.permission.INTERNET"
-      }
-    ],
-    "installationFree": false,
-    "srcEntry": "ohos_app_cangjie_entry.MyAbilityStage",
-    "abilities": [
-      {
-        "name": "EntryAbility",
-        "srcEntry": "ohos_app_cangjie_entry.MainAbility",
-        "description": "$string:EntryAbility_desc",
-        "icon": "$media:layered_image",
-        "label": "$string:EntryAbility_label",
-        "startWindowIcon": "$media:startIcon",
-        "startWindowBackground": "$color:start_window_background",
-        "exported": true,
-        "skills": [
-          {
-            "entities": [
-              "entity.system.home"
-            ],
-            "actions": [
-              "action.system.home"
-            ]
-          }
-        ]
-      }
-    ]
-  }
-}
+{
+  "module": {
+    "name": "entry",
+    "type": "entry",
+    "description": "$string:module_desc",
+    "mainElement": "EntryAbility",
+    /* 鸿蒙 PC 必须声明 "2in1"：只写 phone/tablet 时系统按手机应用处理，窗口是竖屏兼容窗。
+       构建插件默认把 deviceTypes 限制成 phone/tablet，靠 entry/build-profile.json5 的
+       cangjieOptions.checkDeviceTypes=false 放行。 */
+    "deviceTypes": [
+      "2in1",
+      "tablet",
+      "phone"
+    ],
+    "deliveryWithInstall": true,
+    /* 网上取数据（http/https）都需要这条：缺它时请求死在
+       `SocketException: Failed to create socket: Operation not permitted.`，
+       页面上表现为「连不上后台」，看着像网络不通。用不到就删掉这一条。 */
+    "requestPermissions": [
+      {
+        "name": "ohos.permission.INTERNET"
+      }
+    ],
+    "installationFree": false,
+    "srcEntry": "ohos_app_cangjie_entry.MyAbilityStage",
+    "abilities": [
+      {
+        "name": "EntryAbility",
+        "srcEntry": "ohos_app_cangjie_entry.MainAbility",
+        "description": "$string:EntryAbility_desc",
+        "icon": "$media:layered_image",
+        "label": "$string:EntryAbility_label",
+        "startWindowIcon": "$media:startIcon",
+        "startWindowBackground": "$color:start_window_background",
+        "exported": true,
+        "skills": [
+          {
+            "entities": [
+              "entity.system.home"
+            ],
+            "actions": [
+              "action.system.home"
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}

package/cli/templates/{ohos-pc → ohos-skeleton}/entry/src/main/resources/base/element/color.json

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

package/cli/templates/{ohos-pc → ohos-skeleton}/entry/src/main/resources/base/element/string.json

@@ -1,16 +1,16 @@
-{
-  "string": [
-    {
-      "name": "module_desc",
-      "value": "{{APP_LABEL}}"
-    },
-    {
-      "name": "EntryAbility_desc",
-      "value": "{{APP_LABEL}}"
-    },
-    {
-      "name": "EntryAbility_label",
-      "value": "{{APP_LABEL}}"
-    }
-  ]
-}
+{
+  "string": [
+    {
+      "name": "module_desc",
+      "value": "{{APP_LABEL}}"
+    },
+    {
+      "name": "EntryAbility_desc",
+      "value": "{{APP_LABEL}}"
+    },
+    {
+      "name": "EntryAbility_label",
+      "value": "{{APP_LABEL}}"
+    }
+  ]
+}

package/cli/templates/{ohos-pc → ohos-skeleton}/entry/src/main/resources/base/media/layered_image.json

@@ -1,6 +1,6 @@
-{
-  "layered-image": {
-    "background": "$media:background",
-    "foreground": "$media:foreground"
-  }
-}
+{
+  "layered-image": {
+    "background": "$media:background",
+    "foreground": "$media:foreground"
+  }
+}

package/cli/templates/{ohos-pc → ohos-skeleton}/entry/src/main/resources/base/profile/main_pages.json

@@ -1,2 +1,2 @@
-{
-}
+{
+}

package/cli/templates/{ohos-pc → ohos-skeleton}/entry/src/main/resources/rawfile/capabilities.json

@@ -1,6 +1,6 @@
-{
-  "identifier": "default",
-  "windows": ["main"],
-  "commands": ["greet", "timer", "system:version", "system:ping", "system:echo"],
-  "events": ["tick"]
-}
+{
+  "identifier": "default",
+  "windows": ["main"],
+  "commands": ["greet", "timer", "system:version", "system:ping", "system:echo"],
+  "events": ["tick"]
+}

package/cli/templates/{ohos-pc → ohos-skeleton}/entry/src/main/resources/rawfile/index.html

@@ -1,92 +1,92 @@
-<!DOCTYPE html>
-<html>
-<head>
-<meta charset="utf-8">
-<title>{{PROJECT_NAME}}</title>
-<style>
-  :root { color-scheme: dark; }
-  body { font-family: system-ui, "HarmonyOS Sans", "Segoe UI", sans-serif; background: #16161d;
-         color: #e6e6e6; margin: 0; min-height: 100vh;
-         display: flex; flex-direction: column; align-items: center; justify-content: center; }
-  .card { background: #1f2029; border: 1px solid #2e3140; border-radius: 14px;
-          padding: 28px 32px; width: min(520px, 86vw);
-          box-shadow: 0 12px 32px rgba(0,0,0,.45); }
-  h1 { margin: 0 0 4px; font-size: 22px; color: #7ce7ff; }
-  .sub { margin: 0 0 18px; font-size: 13px; color: #9aa0b4; line-height: 1.6; }
-  .row { display: flex; gap: 8px; margin: 14px 0; }
-  input, button { font-size: 15px; padding: 9px 12px; border-radius: 9px; border: 1px solid transparent; }
-  input { flex: 1; background: #141821; color: #e6e6e6; border-color: #2e3140; }
-  input:focus { outline: none; border-color: #4a7fd4; }
-  button { background: #e94560; color: #fff; cursor: pointer; font-weight: 600; }
-  button:hover { opacity: .88; }
-  button.ghost { background: #2b3040; }
-  .result { margin-top: 6px; min-height: 24px; font-size: 15px; color: #50fa7b; word-break: break-all; }
-  .tick { margin-top: 10px; font-size: 13px; color: #8be9fd; min-height: 18px; }
-  .foot { margin-top: 18px; font-size: 12px; color: #6b7186; line-height: 1.7; }
-</style>
-</head>
-<body>
-  <div class="card">
-    <h1>{{PROJECT_NAME}}</h1>
-    <p class="sub">仓颉后端（静态编译）+ ArkWeb 前端 &nbsp;·&nbsp; invoke / listen 双向 IPC &nbsp;·&nbsp; capability 安全模型</p>
-
-    <div class="row">
-      <input id="name" placeholder="输入名字" value="world">
-      <button id="greet">greet</button>
-    </div>
-    <div class="row">
-      <button id="timer" class="ghost">启动后端事件推送</button>
-      <button id="version" class="ghost">system:version</button>
-    </div>
-
-    <div id="result" class="result">等待 invoke…</div>
-    <div id="tick" class="tick"></div>
-    <div class="foot">未在 rawfile/capabilities.json 里声明的命令会被后端拒绝</div>
-  </div>
-
-  <script>
-    // 注入的桥（对标 @tauri-apps/api）：window.__CJ_TAURI__
-    // 鸿蒙的 ArkWeb 没有 document-start 注入，桥是在 onPageBegin 里注入的，
-    // 所以页面必须「等桥出现」而不是模块作用域直接读。
-    function withBridge(cb) {
-      if (window.__CJ_TAURI__) { cb(window.__CJ_TAURI__); return; }
-      setTimeout(function () { withBridge(cb); }, 50);
-    }
-
-    withBridge(function (tauri) {
-      var result = document.getElementById('result');
-      var tick = document.getElementById('tick');
-
-      function show(text, ok) {
-        result.textContent = text;
-        result.style.color = ok === false ? '#ff6b81' : '#50fa7b';
-      }
-
-      // JS → 仓颉
-      document.getElementById('greet').onclick = function () {
-        var name = document.getElementById('name').value || 'world';
-        tauri.invoke('greet', { name: name })
-          .then(function (data) { show('invoke OK: ' + data); })
-          .catch(function (err) { show('invoke FAIL: ' + err.message, false); });
-      };
-
-      document.getElementById('version').onclick = function () {
-        tauri.invoke('system:version')
-          .then(function (data) { show('system:version -> ' + JSON.stringify(data)); })
-          .catch(function (err) { show('system:version FAIL: ' + err.message, false); });
-      };
-
-      // 仓颉 → JS（事件推送）
-      document.getElementById('timer').onclick = function () {
-        tauri.invoke('timer')
-          .then(function (d) { show('后端: ' + d); })
-          .catch(function (err) { show('timer FAIL: ' + err.message, false); });
-      };
-
-      tauri.listen('tick', function (payload) {
-        tick.textContent = '收到后端事件 tick #' + payload.n;
-      });
-    });
-  </script>
-</body>
-</html>
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>{{PROJECT_NAME}}</title>
+<style>
+  :root { color-scheme: dark; }
+  body { font-family: system-ui, "HarmonyOS Sans", "Segoe UI", sans-serif; background: #16161d;
+         color: #e6e6e6; margin: 0; min-height: 100vh;
+         display: flex; flex-direction: column; align-items: center; justify-content: center; }
+  .card { background: #1f2029; border: 1px solid #2e3140; border-radius: 14px;
+          padding: 28px 32px; width: min(520px, 86vw);
+          box-shadow: 0 12px 32px rgba(0,0,0,.45); }
+  h1 { margin: 0 0 4px; font-size: 22px; color: #7ce7ff; }
+  .sub { margin: 0 0 18px; font-size: 13px; color: #9aa0b4; line-height: 1.6; }
+  .row { display: flex; gap: 8px; margin: 14px 0; }
+  input, button { font-size: 15px; padding: 9px 12px; border-radius: 9px; border: 1px solid transparent; }
+  input { flex: 1; background: #141821; color: #e6e6e6; border-color: #2e3140; }
+  input:focus { outline: none; border-color: #4a7fd4; }
+  button { background: #e94560; color: #fff; cursor: pointer; font-weight: 600; }
+  button:hover { opacity: .88; }
+  button.ghost { background: #2b3040; }
+  .result { margin-top: 6px; min-height: 24px; font-size: 15px; color: #50fa7b; word-break: break-all; }
+  .tick { margin-top: 10px; font-size: 13px; color: #8be9fd; min-height: 18px; }
+  .foot { margin-top: 18px; font-size: 12px; color: #6b7186; line-height: 1.7; }
+</style>
+</head>
+<body>
+  <div class="card">
+    <h1>{{PROJECT_NAME}}</h1>
+    <p class="sub">仓颉后端（静态编译）+ ArkWeb 前端 &nbsp;·&nbsp; invoke / listen 双向 IPC &nbsp;·&nbsp; capability 安全模型</p>
+
+    <div class="row">
+      <input id="name" placeholder="输入名字" value="world">
+      <button id="greet">greet</button>
+    </div>
+    <div class="row">
+      <button id="timer" class="ghost">启动后端事件推送</button>
+      <button id="version" class="ghost">system:version</button>
+    </div>
+
+    <div id="result" class="result">等待 invoke…</div>
+    <div id="tick" class="tick"></div>
+    <div class="foot">未在 rawfile/capabilities.json 里声明的命令会被后端拒绝</div>
+  </div>
+
+  <script>
+    // 注入的桥（对标 @tauri-apps/api）：window.__CJ_TAURI__
+    // 鸿蒙的 ArkWeb 没有 document-start 注入，桥是在 onPageBegin 里注入的，
+    // 所以页面必须「等桥出现」而不是模块作用域直接读。
+    function withBridge(cb) {
+      if (window.__CJ_TAURI__) { cb(window.__CJ_TAURI__); return; }
+      setTimeout(function () { withBridge(cb); }, 50);
+    }
+
+    withBridge(function (tauri) {
+      var result = document.getElementById('result');
+      var tick = document.getElementById('tick');
+
+      function show(text, ok) {
+        result.textContent = text;
+        result.style.color = ok === false ? '#ff6b81' : '#50fa7b';
+      }
+
+      // JS → 仓颉
+      document.getElementById('greet').onclick = function () {
+        var name = document.getElementById('name').value || 'world';
+        tauri.invoke('greet', { name: name })
+          .then(function (data) { show('invoke OK: ' + data); })
+          .catch(function (err) { show('invoke FAIL: ' + err.message, false); });
+      };
+
+      document.getElementById('version').onclick = function () {
+        tauri.invoke('system:version')
+          .then(function (data) { show('system:version -> ' + JSON.stringify(data)); })
+          .catch(function (err) { show('system:version FAIL: ' + err.message, false); });
+      };
+
+      // 仓颉 → JS（事件推送）
+      document.getElementById('timer').onclick = function () {
+        tauri.invoke('timer')
+          .then(function (d) { show('后端: ' + d); })
+          .catch(function (err) { show('timer FAIL: ' + err.message, false); });
+      };
+
+      tauri.listen('tick', function (payload) {
+        tick.textContent = '收到后端事件 tick #' + payload.n;
+      });
+    });
+  </script>
+</body>
+</html>

package/cli/templates/{ohos-pc → ohos-skeleton}/hvigor/hvigor-config.json5

@@ -1,5 +1,5 @@
-{
-  "modelVersion": "6.1.1",
-  "dependencies": {
-  }
-}
+{
+  "modelVersion": "6.1.1",
+  "dependencies": {
+  }
+}

package/cli/templates/{ohos-pc → ohos-skeleton}/hvigorfile.ts

@@ -1,6 +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. */
-}
+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/cli/templates/{ohos-pc → ohos-skeleton}/oh-package.json5

@@ -1,10 +1,10 @@
-{
-  "modelVersion": "6.1.1",
-  "description": "{{PROJECT_NAME}} - cj-tauri 鸿蒙 PC 应用",
-  "dependencies": {
-  },
-  "devDependencies": {
-    "@ohos/hypium": "1.0.25",
-    "@ohos/hamock": "1.0.0"
-  }
-}
+{
+  "modelVersion": "6.1.1",
+  "description": "{{PROJECT_NAME}} - cj-tauri 鸿蒙 PC 应用",
+  "dependencies": {
+  },
+  "devDependencies": {
+    "@ohos/hypium": "1.0.25",
+    "@ohos/hamock": "1.0.0"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cj-tauri",
-  "version": "1.1.2",
+  "version": "2.0.0",
   "description": "仓颉语言的 Tauri：用仓颉写桌面应用后端 / 系统 WebView 写前端的混合开发框架脚手架 CLI（IPC 双向桥 + 能力安全模型，Windows / Linux / 鸿蒙 PC）",
   "keywords": [
     "cangjie",
@@ -18,7 +18,9 @@
     "scaffold",
     "cross-platform",
     "windows",
-    "linux"
+    "linux",
+    "ohos",
+    "harmonyos"
   ],
   "license": "MIT",
   "bin": {

package/src/app.cj

@@ -3,6 +3,7 @@ package cjTauri
 import std.collection.*
 import std.env.*
 import stdx.encoding.json.*
+import cjTauri.platform.*
 
 /**
  * 附加窗口的登记项（试验性 API `TauriApp.addWindow` 的装配状态）
@@ -38,7 +39,10 @@ class ExtraWindowSpec {
 public class TauriApp <: AppHost {
     private var hub: IpcHub = IpcHub()
     private var capabilities: CapabilityRegistry = CapabilityRegistry()
-    private var host: WebViewHost = createHost(DEFAULT_WINDOW_LABEL)
+    // 批次 1（RFC-002 §5.4）：注册表优先、内置实现兜底
+    private var host: WebViewHost = resolveHost(DEFAULT_WINDOW_LABEL)
+    // Asset 页面的解析器（批次 1 可注入；缺省按 cwd 相对路径读盘，清单派生在批次 2）
+    private var assetResolver: Option<AssetResolver> = None
     private var config: WindowConfig = WindowConfig()
     // 窗口注册表（批次 2）：单窗口阶段只有一条 "main"，多窗口时是「label → 宿主」的唯一权威来源
     private var windows: WindowRegistry = WindowRegistry()
@@ -63,6 +67,18 @@ public class TauriApp <: AppHost {
         return this
     }
 
+    /**
+     * 注入资产解析器（批次 1，RFC-002 §6）
+     *
+     * 供 run(Asset("ui/index.html")) 取页面与资产；不注入时按 cwd 相对路径读盘，
+     * 与现有模板 textOrFile 的桌面行为等价。鸿蒙 rawfile / 内嵌常量的实现由
+     * 各端适配层提供，批次 2 随清单派生接入。
+     */
+    public func assets(resolver: AssetResolver): TauriApp {
+        this.assetResolver = Some(resolver)
+        return this
+    }
+
     /**
      * 登记一个附加窗口（**试验性**：批次 3「多窗口 UI」的最小切片，先给出可验证的通路）
      *
@@ -80,7 +96,7 @@ public class TauriApp <: AppHost {
         if (this.started) {
             throw CommandException("addWindow 必须在 run() / runUrl() 之前调用（页面加载前窗口表要定稿）")
         }
-        let host = createHost(label)
+        let host = resolveHost(label)
         host.setWindowConfig(config)
         // label 注入与默认窗口走同一条通道（document-start 预执行脚本，桥 JS 懒读，先后顺序无所谓）
         host.addInitScript("window.__CJ_TAURI_LABEL__ = ${JsonString(label)};")
@@ -541,39 +557,52 @@ public class TauriApp <: AppHost {
     }
 
     /**
-     * 启动应用：装配 IPC → 启动 WebView 宿主 → 阻塞运行
+     * 启动应用：装配 IPC → 启动 WebView 宿主 → 阻塞运行（兼容入口，等价 run(Inline(html))）
      */
     public func run(html: String): Unit {
-        this.prepare()
-        if (this.dumpManifestIfRequested()) {
-            return
-        }
-        this.registerPluginScripts()
-        this.registerDefaultWindow()
-        this.host.start(html)
-        this.startExtraWindows()
-        this.waitForExit()
-        // 事件循环已退出：释放全部宿主编（幂等；句柄由 C 侧回收，见 docs/架构演进-多平台与多窗口.md §6.1）
-        this.disposeWindows()
+        this.run(PageSource.Inline(html))
     }
 
     /**
-     * 按 URL 启动应用（http(s):// 或 file://）
+     * 按 URL 启动应用（兼容入口，等价 run(Url(url))）
      *
      * 与 run(html) 平行：同一段装配，只是页面来源换成 URL。有了真实来源，
      * 相对路径资源、动态 import、前端路由才成立（file:// 页面禁止 fetch/XHR）。
      * 开发时可配合 TauriApp.devUrl() 指向前端 dev server（Vite 的 HMR 就这样接进来）。
      */
     public func runUrl(url: String): Unit {
+        this.run(PageSource.Url(url))
+    }
+
+    /**
+     * 统一页面入口（批次 1，RFC-002 §4.3）：业务与清单只写 PageSource 一种表达
+     *
+     * - Inline(html)：直接给 HTML（探针、错误页）
+     * - Asset(name)：逻辑名，经注入的 AssetResolver 解析；未注入时按 cwd 相对路径读盘；
+     *   devMode（CJ_TAURI_DEV_URL 存在）下自动改写为 DevServer（RFC §4.3）
+     * - Url(url) / DevServer(url)：直载
+     *
+     * 装配流程与旧入口完全一致：dumpManifest → 插件 shim → 默认窗口 → 附加窗口 → 等待退出。
+     */
+    public func run(source: PageSource): Unit {
+        let src = rewriteForDev(source, TauriApp.devUrl())
+        this.runWith({ h => h.load(src) })
+    }
+
+    /** 装配与启动的共同骨架：所有页面入口在 load(source) 收敛，宿主怎么落地是 L0 的事（RFC §4.3/§6.2） */
+    private func runWith(start: (WebViewHost) -> Unit): Unit {
         this.prepare()
         if (this.dumpManifestIfRequested()) {
             return
         }
         this.registerPluginScripts()
         this.registerDefaultWindow()
-        this.host.startUrl(url)
+        // 资产解析器随装配进宿主：桌面读盘、鸿蒙 rawfile 材化，各端 load() 自决怎么用
+        this.host.setAssetResolver(this.assetResolver)
+        start(this.host)
         this.startExtraWindows()
         this.waitForExit()
+        // 事件循环已退出：释放全部宿主编（幂等；句柄由 C 侧回收，见 docs/架构演进-多平台与多窗口.md §6.1）
         this.disposeWindows()
     }
 
@@ -599,7 +628,7 @@ public class TauriApp <: AppHost {
     /**
      * 把插件 jsShim 注册到宿主的「预执行脚本」通道
      *
-     * 必须在 start / startUrl 之前调用：宿主创建 WebView 时一次性交给 C 桥，
+     * 必须在 load 之前调用：宿主创建 WebView 时一次性交给 C 桥，
      * 桥以 document-start 注入（早于页面脚本，两平台语义一致）。
      * HTML 与 URL 两种来源共用这条通道——v1 那个「runUrl 模式下 shim 注入不进去」的局限就此消掉（RFC §5.4），
      * 所以这里不再需要对使用者的额外提醒。
@@ -709,7 +738,7 @@ public class TauriApp <: AppHost {
     /**
      * 把默认窗口登记进注册表（label = "main"）并给它注入 label
      *
-     * 必须在 start() / startUrl() 之前：① 页面一加载就可能发 invoke / emit，回执要按 label 找到窗口；
+     * 必须在 load() 之前：① 页面一加载就可能发 invoke / emit，回执要按 label 找到窗口；
      * ② label 走宿主的预执行脚本通道（document-start）注入，晚于 start 就没机会了。
      * 桥 JS 是**懒读** `window.__CJ_TAURI_LABEL__` 的（首次用到才取、取到即缓存），
      * 所以注入脚本与桥 JS 的先后顺序无所谓——两平台的注入时机本就不同。
@@ -894,9 +923,9 @@ public class TauriApp <: AppHost {
     private func startExtraWindows(): Unit {
         for (w in this.extraWindows) {
             this.wireHostCallbacks(w.host)
-            // shell 事件分发要在 start 之前装（菜单点击随时可能来，装晚了就漏）
+            // shell 事件分发要在 load 之前装（菜单点击随时可能来，装晚了就漏）
             this.wireShellEvents(w.host, w.label)
-            w.host.start(w.html)
+            w.host.load(PageSource.Inline(w.html))
             eprintln("[cj-tauri] 附加窗口已启动：label=\"${w.label}\"")
         }
     }

package/src/app_spec.cj

@@ -0,0 +1,76 @@
+package cjTauri
+
+import std.collection.*
+import cjTauri.platform.*
+
+/**
+ * 应用装配声明（批次 3，RFC-002 §4.1）：`build()` 的返回类型
+ *
+ * 业务只描述「应用是什么」——页面 / 窗口 / 插件 / 资产 / 命令装配点——
+ * 不描述「在哪跑」：`launch(spec)` 在框架侧按目标分派（§4.2），
+ * 平台知识只存在于 L0（§5）。
+ *
+ * 批次 3-PR1 落地形态（§4.1 的补记）：
+ * - 命令装配点是 `wire` 闭包：拿到装配中的 TauriApp 后 `register`
+ *   （业务命令多需要 app 自身，如 `music:quit`）。§4.4 的编译期命令表
+ *   （generated registry）是批次 3 的后续 PR，届时 `wire` 收敛为类型化字段；
+ * - 构造器链：RFC §4.1「示意写法；落地用构造器链」。
+ */
+public class AppSpec {
+    /** 应用标识（与清单 [app] id 一致；生成器填入，手写装配建议补上） */
+    public var appId: String = ""
+    public var name: String = ""
+
+    /** 页面来源：只有一种表达（§4.3） */
+    public var pageSource: PageSource = PageSource.Asset("ui/index.html")
+    /** 默认窗口配置 */
+    public var windowConfig: WindowConfig = WindowConfig()
+    /** 插件清单：jsShim 与命令由框架在 run 前统一注册 */
+    public var plugins: ArrayList<Plugin> = ArrayList<Plugin>()
+    /** 资产解析器：None = TauriApp 按 cwd 相对路径读盘（与批次 1 行为一致） */
+    public var assetResolver: Option<AssetResolver> = None
+    /** 能力清单目录：显式挂载 = 框架不自动扫描（目录缺失时安静返回 0，不报错） */
+    public var capabilitiesDir: String = ""
+    /** 能力清单 JSON 原文列表（批次 3-PR3）：给没有目录概念的端（鸿蒙 rawfile）；与目录可并存 */
+    public var capabilityJsons: ArrayList<String> = ArrayList<String>()
+    /** 命令装配点：拿到装配中的 TauriApp 后 register（字段名带 Fn：仓颉字段与方法同命名空间，不能与构造器 wire() 重名） */
+    public var wireFn: Option<(TauriApp) -> Unit> = None
+
+    public init() {}
+
+    public func page(source: PageSource): AppSpec {
+        this.pageSource = source
+        return this
+    }
+
+    public func window(config: WindowConfig): AppSpec {
+        this.windowConfig = config
+        return this
+    }
+
+    public func plugin(p: Plugin): AppSpec {
+        this.plugins.add(p)
+        return this
+    }
+
+    public func assets(resolver: AssetResolver): AppSpec {
+        this.assetResolver = Some(resolver)
+        return this
+    }
+
+    public func capabilities(dir: String): AppSpec {
+        this.capabilitiesDir = dir
+        return this
+    }
+
+    /** 挂载一份能力清单 JSON（多份多次调用；与 capabilities 目录不互斥） */
+    public func capabilityJson(json: String): AppSpec {
+        this.capabilityJsons.add(json)
+        return this
+    }
+
+    public func wire(f: (TauriApp) -> Unit): AppSpec {
+        this.wireFn = Some(f)
+        return this
+    }
+}