cj-tauri 2.0.0 → 2.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (157) hide show
  1. package/README.md +206 -139
  2. package/bin/cj-tauri.js +287 -287
  3. package/cjpm.toml +63 -52
  4. package/cli/cjpm.toml +22 -22
  5. package/cli/src/doctor.cj +308 -306
  6. package/cli/src/main.cj +129 -129
  7. package/cli/src/manifest.cj +643 -558
  8. package/cli/src/manifest_test.cj +87 -0
  9. package/cli/src/project.cj +770 -770
  10. package/cli/src/resolve.cj +348 -348
  11. package/cli/src/scaffold.cj +369 -369
  12. package/cli/src/sync.cj +638 -526
  13. package/cli/src/util.cj +168 -168
  14. package/cli/templates/app/README.md +51 -48
  15. package/cli/templates/app/assets/capabilities/default.json +7 -7
  16. package/cli/templates/app/assets/ui/index.html +120 -118
  17. package/cli/templates/app/cj-tauri.toml +32 -22
  18. package/cli/templates/app/cjpm.toml +34 -34
  19. package/cli/templates/app/src/main.cj +101 -90
  20. package/cli/templates/app-react/README.md +56 -56
  21. package/cli/templates/app-react/assets/capabilities/default.json +7 -7
  22. package/cli/templates/app-react/assets/ui/index.html +25 -25
  23. package/cli/templates/app-react/assets/ui/package.json +19 -19
  24. package/cli/templates/app-react/assets/ui/src/App.css +67 -67
  25. package/cli/templates/app-react/assets/ui/src/App.jsx +124 -124
  26. package/cli/templates/app-react/assets/ui/src/main.jsx +6 -6
  27. package/cli/templates/app-react/assets/ui/vite.config.js +24 -24
  28. package/cli/templates/app-react/cj-tauri.toml +33 -23
  29. package/cli/templates/app-react/cjpm.toml +34 -34
  30. package/cli/templates/app-react/src/main.cj +91 -91
  31. package/cli/templates/app-vue/README.md +56 -56
  32. package/cli/templates/app-vue/assets/capabilities/default.json +7 -7
  33. package/cli/templates/app-vue/assets/ui/index.html +25 -25
  34. package/cli/templates/app-vue/assets/ui/package.json +18 -18
  35. package/cli/templates/app-vue/assets/ui/src/App.vue +176 -176
  36. package/cli/templates/app-vue/assets/ui/src/main.js +4 -4
  37. package/cli/templates/app-vue/assets/ui/vite.config.js +24 -24
  38. package/cli/templates/app-vue/cj-tauri.toml +33 -23
  39. package/cli/templates/app-vue/cjpm.toml +34 -34
  40. package/cli/templates/app-vue/src/main.cj +91 -91
  41. package/cli/templates/ohos-skeleton/AppScope/app.json5 +13 -13
  42. package/cli/templates/ohos-skeleton/AppScope/resources/base/element/string.json +8 -8
  43. package/cli/templates/ohos-skeleton/AppScope/resources/base/media/layered_image.json +6 -6
  44. package/cli/templates/ohos-skeleton/README.md +84 -79
  45. package/cli/templates/ohos-skeleton/build-hap.sh +15 -0
  46. package/cli/templates/ohos-skeleton/build-profile.json5 +46 -46
  47. package/cli/templates/ohos-skeleton/entry/build-profile.json5 +26 -26
  48. package/cli/templates/ohos-skeleton/entry/cjpm.toml +51 -43
  49. package/cli/templates/ohos-skeleton/entry/hvigorfile.ts +6 -6
  50. package/cli/templates/ohos-skeleton/entry/oh-package.json5 +9 -9
  51. package/cli/templates/ohos-skeleton/entry/src/main/cangjie/ability_stage.cj +17 -17
  52. package/cli/templates/ohos-skeleton/entry/src/main/cangjie/app_host.cj +94 -94
  53. package/cli/templates/ohos-skeleton/entry/src/main/cangjie/dialog_host.cj +217 -0
  54. package/cli/templates/ohos-skeleton/entry/src/main/cangjie/index.cj +527 -167
  55. package/cli/templates/ohos-skeleton/entry/src/main/cangjie/main_ability.cj +139 -139
  56. package/cli/templates/ohos-skeleton/entry/src/main/module.json5 +57 -49
  57. package/cli/templates/ohos-skeleton/entry/src/main/resources/base/element/color.json +8 -8
  58. package/cli/templates/ohos-skeleton/entry/src/main/resources/base/element/string.json +16 -16
  59. package/cli/templates/ohos-skeleton/entry/src/main/resources/base/media/layered_image.json +6 -6
  60. package/cli/templates/ohos-skeleton/entry/src/main/resources/base/profile/main_pages.json +2 -2
  61. package/cli/templates/ohos-skeleton/entry/src/main/resources/rawfile/capabilities.json +6 -6
  62. package/cli/templates/ohos-skeleton/entry/src/main/resources/rawfile/index.html +92 -92
  63. package/cli/templates/ohos-skeleton/hvigor/hvigor-config.json5 +5 -5
  64. package/cli/templates/ohos-skeleton/hvigorfile.ts +6 -6
  65. package/cli/templates/ohos-skeleton/oh-package.json5 +10 -10
  66. package/native/build_win.bat +62 -62
  67. package/native/core/bridge_core.c +1681 -1626
  68. package/native/core/bridge_core.h +675 -618
  69. package/native/core/bridge_js.h +108 -108
  70. package/native/platforms/harmonyos/README.md +115 -6
  71. package/native/platforms/linux/bridge_linux.c +2787 -2485
  72. package/native/platforms/windows/bridge_win.c +3745 -3248
  73. package/native/tests/gtk_threading_probe.c +143 -143
  74. package/native/tests/test_bridge_core.c +1339 -1228
  75. package/package.json +53 -53
  76. package/src/api_system.cj +67 -67
  77. package/src/app.cj +335 -969
  78. package/src/app_events.cj +166 -0
  79. package/src/app_host_ops.cj +287 -0
  80. package/src/app_run.cj +283 -0
  81. package/src/app_spec.cj +76 -76
  82. package/src/arkweb_menu.cj +216 -0
  83. package/src/arkweb_script.cj +142 -142
  84. package/src/capability.cj +409 -409
  85. package/src/clipboard_bridge.cj +178 -0
  86. package/src/dialog_spec.cj +79 -0
  87. package/src/dragdrop.cj +26 -26
  88. package/src/embedded_assets.cj +98 -98
  89. package/src/host.cj +752 -607
  90. package/src/host_arkweb.cj +924 -778
  91. package/src/host_webkit.cj +663 -570
  92. package/src/host_webview2.cj +663 -570
  93. package/src/hotkey.cj +66 -66
  94. package/src/ipc_hub.cj +401 -337
  95. package/src/ipc_message.cj +286 -286
  96. package/src/launch.cj +62 -62
  97. package/src/logging.cj +127 -127
  98. package/src/menu.cj +197 -197
  99. package/src/platform/platform_app_context.cj +77 -77
  100. package/src/platform/platform_assets.cj +33 -33
  101. package/src/platform/platform_discover.cj +176 -176
  102. package/src/platform/platform_env.cj +29 -29
  103. package/src/platform/platform_feature.cj +31 -31
  104. package/src/platform/platform_page_source.cj +87 -87
  105. package/src/platform/platform_target_info.cj +32 -32
  106. package/src/platform_host_provider.cj +87 -87
  107. package/src/plugin.cj +333 -333
  108. package/src/plugins/clipboard/plugin_clipboard.cj +152 -152
  109. package/src/plugins/dialog/plugin_dialog.cj +209 -209
  110. package/src/plugins/fs/plugin_fs.cj +105 -1
  111. package/src/plugins/http/http_backend.cj +131 -0
  112. package/src/plugins/http/http_desktop.cj +195 -0
  113. package/src/plugins/http/http_ohos.cj +204 -0
  114. package/src/plugins/http/plugin_http.cj +310 -459
  115. package/src/plugins/log/plugin_log.cj +105 -105
  116. package/src/plugins/menu/plugin_menu.cj +158 -158
  117. package/src/plugins/notification/plugin_notification.cj +154 -154
  118. package/src/plugins/serial/plugin_serial.cj +458 -454
  119. package/src/plugins/serial/serial_bridge.cj +194 -194
  120. package/src/plugins/serial/serial_manager_ohos.cj +92 -0
  121. package/src/plugins/serial/serial_ohos.cj +529 -0
  122. package/src/plugins/shell/plugin_shell.cj +258 -258
  123. package/src/plugins/sqlite/plugin_sqlite.cj +705 -710
  124. package/src/plugins/sqlite/sqlite_ffi.cj +206 -211
  125. package/src/plugins/ws/plugin_ws.cj +488 -470
  126. package/src/process_hidden.cj +174 -174
  127. package/src/scope.cj +391 -391
  128. package/src/shell_event.cj +69 -69
  129. package/src/tests/app_spec_test.cj +130 -127
  130. package/src/tests/capability_test.cj +243 -243
  131. package/src/tests/dialog_spec_test.cj +73 -0
  132. package/src/tests/fake_host.cj +201 -201
  133. package/src/tests/ipc_hub_test.cj +563 -487
  134. package/src/tests/logging_test.cj +62 -62
  135. package/src/tests/platform_contract_test.cj +264 -251
  136. package/src/tests/plugin_clipboard_test.cj +222 -222
  137. package/src/tests/plugin_dialog_test.cj +237 -237
  138. package/src/tests/plugin_fs_test.cj +207 -0
  139. package/src/tests/plugin_http_test.cj +124 -124
  140. package/src/tests/plugin_notification_test.cj +205 -205
  141. package/src/tests/plugin_serial_test.cj +48 -0
  142. package/src/tests/plugin_test.cj +605 -585
  143. package/src/tests/plugin_ws_test.cj +40 -40
  144. package/src/tests/process_hidden_test.cj +129 -129
  145. package/src/tests/scope_test.cj +350 -350
  146. package/src/tests/system_host_test.cj +99 -81
  147. package/src/tests/urlutil_test.cj +53 -53
  148. package/src/tests/version_test.cj +75 -75
  149. package/src/tests/window_registry_test.cj +123 -123
  150. package/src/tray.cj +90 -90
  151. package/src/urlutil.cj +159 -159
  152. package/src/version.cj +44 -44
  153. package/src/window.cj +51 -51
  154. package/src/window_registry.cj +116 -116
  155. package/prebuilt/win32-x64/cj-tauri.exe +0 -0
  156. package/src/plugins/serial/serial_ohos_stub.cj +0 -61
  157. package/src/plugins/sqlite/sqlite_ohos_stub.cj +0 -91
package/README.md CHANGED
@@ -1,128 +1,145 @@
1
- # cj-tauri
2
-
3
- 用[仓颉语言](https://cangjie-lang.cn)写桌面应用的脚手架 CLI——把 Tauri 的三件套带到仓颉:
4
- 仓颉后端(静态编译)+ 系统 WebView 前端(HTML/CSS/JS),三件套与 Tauri 一致 ——
5
- WebView 宿主、IPC 双向桥(`invoke` / `resolve` / `event`)、能力安全模型(capability 白名单)。
6
-
7
- - 仓库与完整文档:<https://atomgit.com/qq8864/cj-tauri>
8
- - 当前版本:**2.0.0**(主版本:删除了已失效的 `setHostFactory` / `requireInjectedHost`,见文末「2.0.0 变更」)
9
- - 当前状态:**Windows(WebView2)、Linux(WebKitGTK)与鸿蒙 PC(ArkWeb)均已实机跑通**
10
-
11
- ## 前置条件:仓颉 SDK
12
-
13
- **这个包不替代仓颉 SDK**。应用后端就是仓颉代码,`cj-tauri dev` / `build` 要调用 SDK 里的 `cjc` / `cjpm`
14
- 把你的应用编译出来。所以请先装 SDK(验证版本 **1.2.0**,含 **stdx**),并让本包能找到它:
15
-
16
- ```bash
17
- # Linux
18
- export CANGJIE_HOME=/opt/cangjie/cangjie
19
-
20
- # Windows cmd
21
- set CANGJIE_HOME=D:\Program Files (x86)\Cangjie
22
- ```
23
-
24
- 不设 `CANGJIE_HOME` 时,本包会探测常见安装位置(Windows `D:\Program Files (x86)\Cangjie`、
25
- Linux `/opt/cangjie/cangjie`)。另外两个变量视情况给:
26
-
27
- | 变量 | 什么时候需要 |
28
- |---|---|
29
- | `CJ_TAURI_ROOT` | 不在 cj-tauri 仓库内运行、又找不到框架根目录时(`create` 要把框架路径写进工程) |
30
- | `CANGJIE_STDX` | 应用的 `cjpm.toml` 用 `${CANGJIE_STDX}` 展开 stdx 路径;本包会从框架/工程的 toml 里探测,探不到就照此变量 |
31
- | `CANGJIE_STDX_OHOS` | 只在构建鸿蒙工程时用(鸿蒙版 stdx,`build-hap.sh` 按它找动态库) |
32
-
33
- 装好后自检:
34
-
35
- ```bash
36
- npx cj-tauri info # 打印框架 / 项目 / stdx / SDK / cjpm / C 桥 的解析结果
37
- ```
38
-
39
- 没装 SDK 时本包会直接给出提示与安装说明,而不是抛一句 `cjpm: command not found`。
40
- 另外 `npx cj-tauri --version` 不需要 SDK 也能查版本。
41
-
42
- ## 用法
43
-
44
- ```bash
45
- npx cj-tauri create myapp --template app # 内联 HTML,零 Node(缺省模板)
46
- cd myapp
47
- npx cj-tauri sync # 按清单派生 targets/ 骨架(首次;重跑幂等)
48
- npx cj-tauri dev # 构建 C 桥 + cjpm build + 启动窗口
49
-
50
- npx cj-tauri create myapp-vue --template vue # Vue 3 + Vite(前端工程在 assets/ui/)
51
- npx cj-tauri create myapp-react --template react # React 18 + Vite
52
-
53
- npx cj-tauri create myohos --template ohos # 鸿蒙 PC:同一份业务代码 + targets/ohos
54
- npx cj-tauri create myohos --template ohos --bundle com.example.myapp --label "我的应用"
55
-
56
- npm i -g cj-tauri # 也可以全局安装,之后直接用 cj-tauri <子命令>
57
- ```
58
-
59
- **一份业务代码,骨架按目标派生**——`create` 只生成清单与业务侧,平台骨架是 `sync` 的产物:
60
-
61
- ```
62
- myapp/
63
- ├── cj-tauri.toml # 应用清单——单一真相(id/version/窗口/资产/能力目录)
64
- ├── cjpm.toml # 业务包(static 库;骨架以 path 依赖引用)
65
- ├── src/main.cj # 业务装配点 build(): AppSpec(零平台知识)
66
- ├── assets/
67
- │ ├── ui/index.html # 前端页面(任意 Web 技术栈)
68
- │ └── capabilities/default.json # 能力白名单(命令 / 事件 / 权限集)
69
- └── targets/ # cj-tauri sync 生成(勿手改;check 判漂移)
70
- ├── desktop/ # 桌面可执行(launcher 调 build())
71
- └── ohos/ # 鸿蒙 hap 工程(DevEco + build-hap.sh)
72
- ```
73
-
74
- | 子命令 | 作用 |
75
- |---|---|
76
- | `create <项目名> [--template app\|vue\|react\|ohos]` | 生成统一工程(清单 + `src/` + `assets/`);`--bundle` / `--label` 只对 `ohos` 模板有意义,缺省由项目名推导 |
77
- | `sync [desktop\|ohos]` | 按清单派生 `targets/` 骨架(缺省两端都派生;幂等重跑) |
78
- | `dev` | 构建 C 桥 + `cjpm build` + 启动应用;Vite 模板会接管 dev server(HMR) |
79
- | `build` | 构建 C 桥 + `cjpm build`;鸿蒙端在 `targets/ohos` 里 `bash build-hap.sh` |
80
- | `run` | 运行已构建产物;鸿蒙端 `bash build-hap.sh --install`(构建 + 装机 + 拉起) |
81
- | `check` | 校验 `cj-tauri.toml`(id / 窗口 / 资产存在)+ `targets/` 骨架漂移 + 插件三方比对 |
82
- | `info [--json]` | 环境自检(排障先跑它);`--json` 只输出插件清单,机器可读 |
83
- | `doctor` | 环境自检逐行给结论(每条自带「缺了就怎么办」) |
84
- | `help` | 帮助 |
85
-
86
- ## 鸿蒙 PC(`--template ohos`)
87
-
88
- 同一套框架换个宿主:桌面用 WebView2 / WebKitGTK,鸿蒙 PC 用 **ArkWeb**,上层页面、命令层、能力校验不用改。
89
- `--template ohos` 生成的仍是那种**统一工程**(`cj-tauri.toml` + `src/` + `assets/`),只是清单里带鸿蒙端信息
90
- (`[app] id` 就是 `bundleName`);DevEco 工程是 `sync` 的产物,落在 `targets/ohos/`:
1
+ # cj-tauri
2
+
3
+ A scaffold CLI for building desktop apps in the [Cangjie language](https://cangjie-lang.cn) — it brings
4
+ Tauri's trio to Cangjie: a Cangjie backend (statically compiled) plus a system WebView frontend
5
+ (HTML/CSS/JS), with the same three pieces Tauri has — a WebView host, a bidirectional IPC bridge
6
+ (`invoke` / `resolve` / `event`), and a capability-based security model (capability allowlists).
7
+
8
+ - Repository and full documentation: <https://github.com/yangyongzhen/cj-tauri>
9
+ - Current version: **2.1.1** (fixed in this release: sync now keeps the launcher on the framework path
10
+ the business package declares (no more cjpm module conflicts after editing the path), the desktop
11
+ launcher locates assets/ two levels up so it runs straight from targets/, and new **serial command
12
+ groups** — `TauriApp.registerSerial` — execute same-group commands strictly in arrival order, which
13
+ ai-chat's web-tab commands now use; plus the hello-world example and starter guide)
14
+ - Current status: **Windows (WebView2), Linux (WebKitGTK) and HarmonyOS PC (ArkWeb) all run on real
15
+ hardware**; on the HarmonyOS side the menu capability bit and `fs` / `mqtt` / `redis` / `sqlite` /
16
+ `store` / `http` have been verified on a device
17
+
18
+ ## Prerequisite: the Cangjie SDK
19
+
20
+ **This package does not replace the Cangjie SDK.** Your app backend is Cangjie code, and
21
+ `cj-tauri dev` / `build` invoke the SDK's `cjc` / `cjpm` to compile it. So install the SDK first
22
+ (verified with version **1.2.0**, including **stdx**) and make it discoverable:
23
+
24
+ ```bash
25
+ # Linux
26
+ export CANGJIE_HOME=/opt/cangjie/cangjie
27
+
28
+ # Windows cmd
29
+ set CANGJIE_HOME=D:\Program Files (x86)\Cangjie
30
+ ```
31
+
32
+ When `CANGJIE_HOME` is unset, the package probes the usual install locations (Windows
33
+ `D:\Program Files (x86)\Cangjie`, Linux `/opt/cangjie/cangjie`). Three more variables are needed
34
+ in some situations:
35
+
36
+ | Variable | When you need it |
37
+ |---|---|
38
+ | `CJ_TAURI_ROOT` | Running outside the cj-tauri repo when the framework root can't be located (`create` writes the framework path into your project) |
39
+ | `CANGJIE_STDX` | Your app's `cjpm.toml` expands the stdx path via `${CANGJIE_STDX}`; the package probes the framework/project toml for it and falls back to this variable |
40
+ | `CANGJIE_STDX_OHOS` | Only when building a HarmonyOS project (the HarmonyOS build of stdx; `build-hap.sh` locates its dynamic libraries through it) |
41
+
42
+ Self-check once it's installed:
91
43
 
92
44
  ```bash
93
- npx cj-tauri create myohos --template ohos --bundle com.example.myapp --label "我的应用"
45
+ npx cj-tauri info # prints the resolved framework / project / stdx / SDK / cjpm / C bridge
46
+ ```
47
+
48
+ Without the SDK the package prints a clear hint and install instructions instead of throwing
49
+ `cjpm: command not found`. Note that `npx cj-tauri --version` works without the SDK.
50
+
51
+ ## Usage
52
+
53
+ ```bash
54
+ npx cj-tauri create myapp --template app # inline HTML, zero Node (the default template)
55
+ cd myapp
56
+ npx cj-tauri sync # derive the targets/ skeletons from the manifest (first run; idempotent)
57
+ npx cj-tauri dev # build the C bridge + cjpm build + open the window
58
+
59
+ npx cj-tauri create myapp-vue --template vue # Vue 3 + Vite (frontend project under assets/ui/)
60
+ npx cj-tauri create myapp-react --template react # React 18 + Vite
61
+
62
+ npx cj-tauri create myohos --template ohos # HarmonyOS PC: same business code + targets/ohos
63
+ npx cj-tauri create myohos --template ohos --bundle com.example.myapp --label "My App"
64
+
65
+ npm i -g cj-tauri # or install globally and call cj-tauri <subcommand> directly
66
+ ```
67
+
68
+ **One body of business code, skeletons derived per target** — `create` only generates the manifest and
69
+ the business side; the platform skeletons are what `sync` produces:
70
+
71
+ ```
72
+ myapp/
73
+ ├── cj-tauri.toml # app manifest — the single source of truth (id/version/window/assets/capability dir)
74
+ ├── cjpm.toml # business package (a static library; skeletons reference it by path)
75
+ ├── src/main.cj # business assembly point build(): AppSpec (zero platform knowledge)
76
+ ├── assets/
77
+ │ ├── ui/index.html # frontend page (any web stack)
78
+ │ └── capabilities/default.json # capability allowlist (commands / events / permission sets)
79
+ └── targets/ # generated by cj-tauri sync (don't hand-edit; check reports drift)
80
+ ├── desktop/ # desktop executable (the launcher calls build())
81
+ └── ohos/ # HarmonyOS hap project (DevEco + build-hap.sh)
82
+ ```
83
+
84
+ | Subcommand | What it does |
85
+ |---|---|
86
+ | `create <name> [--template app\|vue\|react\|ohos]` | Generate the unified project (manifest + `src/` + `assets/`); `--bundle` / `--label` only matter for the `ohos` template, otherwise they're derived from the project name |
87
+ | `sync [desktop\|ohos]` | Derive the `targets/` skeletons from the manifest (both ends by default; idempotent) |
88
+ | `dev` | Build the C bridge + `cjpm build` + launch the app; Vite templates take over their dev server (HMR) |
89
+ | `build` | Build the C bridge + `cjpm build`; on HarmonyOS run `bash build-hap.sh` inside `targets/ohos` |
90
+ | `run` | Run the built artifact; on HarmonyOS `bash build-hap.sh --install` (build + install + launch) |
91
+ | `check` | Validate `cj-tauri.toml` (id / window / assets present) + `targets/` skeleton drift + three-way plugin comparison |
92
+ | `info [--json]` | Environment self-check (run this first when troubleshooting); `--json` prints only the plugin manifest, machine-readable |
93
+ | `doctor` | Environment self-check with a verdict per line (each line says what to do if it's missing) |
94
+ | `help` | Help |
95
+
96
+ ## HarmonyOS PC (`--template ohos`)
97
+
98
+ The same framework with a different host: desktop uses WebView2 / WebKitGTK, HarmonyOS PC uses **ArkWeb**,
99
+ while the page layer, the command layer and capability validation stay untouched. `--template ohos` still
100
+ generates that **unified project** (`cj-tauri.toml` + `src/` + `assets/`), only the manifest carries the
101
+ HarmonyOS side (`[app] id` is the `bundleName`); the DevEco project is a product of `sync`, landing in
102
+ `targets/ohos/`:
103
+
104
+ ```bash
105
+ npx cj-tauri create myohos --template ohos --bundle com.example.myapp --label "My App"
94
106
  cd myohos
95
- npx cj-tauri sync ohos # 派生 targets/ohos(DevEco 骨架 + rawfile 里的页面与能力清单)
107
+ npx cj-tauri sync ohos # derive targets/ohos (DevEco skeleton + the page and capability manifest in rawfile)
96
108
  cd targets/ohos
97
- bash build-hap.sh --install # 构建 hap + hdc 装机 + aa start
109
+ bash build-hap.sh --install # build the hap + install via hdc + aa start
98
110
  ```
99
111
 
100
- `targets/ohos/` 是标准 DevEco 工程(`entry/` + `AppScope/` + `build-profile.json5` + `hvigorfile.ts`),
101
- 鸿蒙相关的那层很薄:
112
+ `targets/ohos/` is a standard DevEco project (`entry/` + `AppScope/` + `build-profile.json5` +
113
+ `hvigorfile.ts`), and the HarmonyOS-specific layer is thin:
102
114
 
103
- | 路径 | 作用 |
115
+ | Path | Purpose |
104
116
  |---|---|
105
- | `entry/src/main/cangjie/main_ability.cj` | UIAbility:`ArkWebRuntime.configure(filesDir)` → 非 UI 线程 `spawn { run() }` → 等宿主登记再 `loadContent` |
106
- | `entry/src/main/cangjie/app_host.cj` | `@Component` 的 ArkWeb 宿主 + 双向桥(**必须住应用模块**,框架包引用 ArkUI 会启动即崩);调你 `assets/` 里那份业务 `build()` |
107
- | `entry/src/main/resources/rawfile/` | `index.html` 与能力清单(从 `assets/` 拷进来的真文件) |
108
- | `build-hap.sh` | 唯一构建入口:探测 DevEco / stdx、`--no-daemon` 跑 hvigor、可选 `--install` |
117
+ | `entry/src/main/cangjie/main_ability.cj` | UIAbility: `ArkWebRuntime.configure(filesDir)` → `spawn { run() }` off the UI thread → wait for the host to register, then `loadContent` |
118
+ | `entry/src/main/cangjie/app_host.cj` | the `@Component` ArkWeb host + bidirectional bridge (**must live in the app module**; a framework package referencing ArkUI crashes at startup); calls the business `build()` in your `assets/` |
119
+ | `entry/src/main/resources/rawfile/` | `index.html` and the capability manifest (real files copied in from `assets/`) |
120
+ | `build-hap.sh` | the single build entry: probes DevEco / stdx, runs hvigor with `--no-daemon`, optional `--install` |
109
121
 
110
- 前置两件事:
122
+ Two prerequisites:
111
123
 
112
- - **DevEco Studio 6.1**(含仓颉插件)+ 已配好签名。`build-hap.sh` 用 `DEVECO_WIN` 找安装根
113
- (默认 `D:\oh\DevEcoStudio`),用 `CANGJIE_STDX_OHOS` 找鸿蒙版 stdx 动态库;两者给不出时脚本会直接说清楚缺哪个。
114
- - 真机开着**开发者模式 + USB 调试**,`hdc` 能列到设备;`aa start` 需要**屏幕已解锁**。
124
+ - **DevEco Studio 6.1** (with the Cangjie plugin) and signing already configured. `build-hap.sh` finds the
125
+ install root via `DEVECO_WIN` (default `D:\oh\DevEcoStudio`) and the HarmonyOS build of stdx's dynamic
126
+ libraries via `CANGJIE_STDX_OHOS`; when either is missing the script says exactly which one.
127
+ - A device with **developer mode + USB debugging** on, so `hdc` lists it; `aa start` needs the **screen unlocked**.
115
128
 
116
- 工程默认是桌面形态:`module.json5` 的 `deviceTypes` 写 `2in1`,并在 `entry/build-profile.json5` 里
117
- `cangjieOptions.checkDeviceTypes = false`(插件默认只放行 `phone` / `tablet`,写 `2in1` 会判 `01103012`);
118
- 窗口**不干预尺寸**,沿用系统给的默认矩形(实测本机 `2090×1394`,约屏宽 2/3 且居中)。
129
+ The project defaults to desktop form factor: `deviceTypes` in `module.json5` is `2in1`, and
130
+ `cangjieOptions.checkDeviceTypes = false` in `entry/build-profile.json5` (the plugin only allows
131
+ `phone` / `tablet` by default, and writing `2in1` fails with `01103012`). The window **does not touch the
132
+ size** and keeps the system default rectangle (measured at `2090×1394`, about two thirds of the screen
133
+ width and centered).
119
134
 
120
- 已知限制:签名要在 DevEco 里配(命令行不做自动签名,换 `bundleName` 需重新签);同一份调试签名下两个
121
- 工程会互相顶掉安装位;单窗口、暂无原生对话框(那两条能力位如实返回 0);没有可用的 C 桥,
122
- `launchHidden` / 串口 / 托盘这类宿主能力在鸿蒙上不提供。改完 `assets/` 里的页面或能力清单要重跑
123
- `cj-tauri sync ohos`(`targets/` 是生成物,`check` 会报漂移)。
135
+ Known limitations: signing is configured in DevEco (the command line does not auto-sign, and changing the
136
+ `bundleName` requires re-signing); two projects under the same debug signature evict each other's install;
137
+ single window with no native dialogs yet (those two capability bits honestly return 0); there is no usable
138
+ C bridge, so host capabilities like `launchHidden` / serial / tray are not available on HarmonyOS. After
139
+ editing pages or the capability manifest under `assets/`, re-run `cj-tauri sync ohos` (`targets/` is
140
+ generated, and `check` reports it as drift).
124
141
 
125
- 真机上怎么自证它通了(hilog,`CjTauri` tag):
142
+ How to prove it works on a device (hilog, `CjTauri` tag):
126
143
 
127
144
  ```
128
145
  host registered after N polls label=main
@@ -131,30 +148,80 @@ page begin label=main
131
148
  main window keeps system default 2090x1394 px at density 190% on screen 3120x2080
132
149
  ```
133
150
 
134
- ## 这个包装层做了什么
135
-
136
- - **跨平台入口**:Windows / Linux / Git Bash 都是同一条 `cj-tauri` 命令,不再分 `.bat` 与 `.sh`;
137
- - **环境自检**:`cjpm` 与 SDK 运行时库的定位、`PATH` / `LD_LIBRARY_PATH` 的拼装都在这里完成;
138
- - **CLI 本体的获取**:优先用包内预编译二进制(`prebuilt/<平台-架构>/`),没有则把 CLI 源码拷到
139
- `~/.cache/cj-tauri/<版本>/` 下用本机 `cjpm build` 一次并缓存 —— 不往安装目录写产物,避免全局安装只读;
140
- - **数据目录**:Linux 用 `$XDG_CACHE_HOME/cj-tauri`(默认 `~/.cache/cj-tauri`),Windows 用 `%LOCALAPPDATA%\cj-tauri`。
141
-
142
- 已知限制:首次 `dev` / `build` 会把 C 桥构建到**框架目录的 `native/`** 下(应用 `cjpm.toml` 的
143
- 链接参数指向那里),所以包安装目录需要可写;如果装在只读路径下,请改用仓库内运行方式。
144
-
145
- ## 2.0.0 变更
146
-
147
- - **不兼容**:删除已失效的公开 API `setHostFactory` / `requireInjectedHost`(框架侧单槽宿主注入)。
148
- 源码里仍在调用它们的应用会编译失败——那些调用本来也不生效(`requireInjectedHost` 没有任何调用方)。
149
- 多宿主注入走 `registerHost(HostProvider)`(带优先级),鸿蒙宿主已内置。
150
- - **修复**:`sync` 生成的工程在 Windows 上编不过(TOML 路径保留反斜杠触发 `errLexEscape`、鸿蒙 entry 的
151
- `compile-option` 内层引号未转义、生成源码里 `url=\"…\"` 少一层转义);`cj-tauri check` 的三方比对在
152
- Windows 上因产物名 `main.exe` 恒被跳过;示例 `modbus-poll` 缺串口插件 import。
153
- - **门禁**:版本校验从五处扩到六处(新增官网 `website/index.html`),并给与 `docs/` 同源的图片 / 图
154
- 加上了逐字节比对——官网是独立拷贝、此前不在门禁里,正是它漏更的根因。
155
-
156
- 完整变更见仓库的 `CHANGELOG.md` 的 `[2.0.0] - 2026-10-23`。
157
-
158
- ## License
159
-
160
- [MIT](https://atomgit.com/qq8864/cj-tauri/blob/main/LICENSE) © 2026 yangyongzhen
151
+ ## What this wrapper layer does
152
+
153
+ - **One cross-platform entry point**: Windows / Linux / Git Bash all use the same `cj-tauri` command, with
154
+ no more separate `.bat` and `.sh`;
155
+ - **Environment self-check**: locating `cjpm` and the SDK runtime libraries, and assembling `PATH` /
156
+ `LD_LIBRARY_PATH`, all happen here;
157
+ - **Obtaining the CLI itself**: the packaged prebuilt binary is preferred (`prebuilt/<platform-arch>/`);
158
+ otherwise the CLI sources are copied to `~/.cache/cj-tauri/<version>/`, built once with the local
159
+ `cjpm build` and cached — nothing is written into the install directory, so a global install can stay
160
+ read-only;
161
+ - **Data directories**: `$XDG_CACHE_HOME/cj-tauri` on Linux (default `~/.cache/cj-tauri`),
162
+ `%LOCALAPPDATA%\cj-tauri` on Windows.
163
+
164
+ Known limitation: the first `dev` / `build` builds the C bridge into the **framework directory's `native/`**
165
+ (that's where the app's `cjpm.toml` link options point), so the package install directory must be writable;
166
+ if you installed under a read-only path, run from inside the repository instead.
167
+
168
+ ## Changes in 2.1.1
169
+
170
+ - **Serial command groups** (issue #6-4): `IpcHub.registerSerial(cmd, handler, group)` /
171
+ `TauriApp.registerSerial` — commands in the same group execute strictly in **arrival order**,
172
+ while other groups and plain commands keep the concurrent semantics. Guaranteed by structure:
173
+ dispatch happens on the bridge's message-callback thread, so enqueue order is arrival order,
174
+ and each group has a single worker draining the queue under one lock. ai-chat's five web-tab
175
+ commands are enrolled in the `webtab` group (the front-end queue stays — page emission order
176
+ and host execution order are two halves of the same guarantee).
177
+ - **sync keeps the launcher on the business package's framework path** (issue #6-1): the launcher's
178
+ `cjTauri` dependency now reads the path the business package declares in its own `cjpm.toml`
179
+ (relative paths absolutized against the project root), so editing that path no longer causes
180
+ a cjpm module conflict between two framework copies.
181
+ - **The desktop launcher locates its assets** (issue #6-2/3): `assets/` and `capabilities/` are
182
+ found by walking up two levels, so running the binary straight from `targets/desktop/` no longer
183
+ dies with "asset not found"; sync's next-steps output names the runtime library path
184
+ (`<framework>/native` for `libcjtbridge.so`).
185
+ - New `examples/hello-world` (smallest runnable app, generated by this CLI) and
186
+ `docs/hello-world-入门教程.md` — a starter guide written from an actual npx-create-to-window run.
187
+
188
+ For the full list see `[2.1.1] - 2026-10-26` in the repository's `CHANGELOG.md`.
189
+
190
+ ## Changes in 2.1.0
191
+
192
+ - **New**: in-window multi-WebView views (`webview:*` — several page views inside one window with an LRU
193
+ cap of 4, which is what drives ai-chat's nine web-version tabs); the four commands `fs:mkdir` /
194
+ `fs:rename` / `fs:copy` / `fs:stat` (with overwrite and two-path scope validation); the `http` plugin's
195
+ HarmonyOS transport layer (over the `ohos.net.http` system stack, which brings https back); `sqlite` /
196
+ `serial` landing on HarmonyOS; a `notification` capability bit in `system:host`; a pointer to the SDK
197
+ download in the CLI's `doctor`.
198
+ - **Fixed**: the Linux C bridge `duplicate member 'h'` compile error (the embedded view's geometry field
199
+ collided with the host pointer), ai-chat's embedded view not following the widening after the sidebar
200
+ collapses, and the documented state of the HarmonyOS host capability bits (the menu bit is verified on a
201
+ device, so it's no longer all zeros).
202
+ - Verified on a HarmonyOS device: `fs` / `mqtt` / `redis` / `sqlite` / `store` / `http` and the menu
203
+ capability bit.
204
+
205
+ For the full list see `[2.1.0] - 2026-10-25` in the repository's `CHANGELOG.md`.
206
+
207
+ ## Changes in 2.0.0
208
+
209
+ - **Breaking**: removed the dead public APIs `setHostFactory` / `requireInjectedHost` (the framework's
210
+ single-slot host injection). Apps still calling them will fail to compile — and those calls never took
211
+ effect anyway (`requireInjectedHost` had no callers at all). Multi-host injection goes through
212
+ `registerHost(HostProvider)` (with priorities); the HarmonyOS host is built in.
213
+ - **Fixed**: projects generated by `sync` wouldn't compile on Windows (TOML paths keeping backslashes
214
+ triggered `errLexEscape`, the HarmonyOS entry's `compile-option` had unescaped inner quotes, and
215
+ `url=\"…\"` in the generated sources was one escape level short); `cj-tauri check`'s three-way
216
+ comparison was always skipped on Windows because of the `main.exe` artifact name; the `modbus-poll`
217
+ example was missing the serial plugin import.
218
+ - **Gates**: version validation grew from five sites to six (adding the website's `website/index.html`),
219
+ and the images / diagrams that share a source with `docs/` now get a byte-for-byte comparison — the
220
+ website is an independent copy that previously sat outside the gate, which is exactly why it went stale.
221
+
222
+ For the full list see `[2.0.0] - 2026-10-23` in the repository's `CHANGELOG.md`.
223
+
224
+ ## License
225
+
226
+ [MIT](https://github.com/yangyongzhen/cj-tauri/blob/main/LICENSE) © 2026 yangyongzhen
227
+