cj-tauri 0.8.0 → 1.1.0

package/cli/src/scaffold.cj

@@ -1,8 +1,8 @@
 /**
  * cj-tauri CLI：项目脚手架（create）
  *
- * 模板位于 <框架根>/cli/templates/app，占位符形如 {{PROJECT_NAME}}；
- * 递归拷贝 + 文本渲染，生成一个可直接 `cj-tauri dev` 的应用。
+ * 模板位于 <框架根>/cli/templates/<模板目录>，占位符形如 {{PROJECT_NAME}}；
+ * 递归拷贝 + 文本渲染，生成一个可直接 `cj-tauri dev`（桌面）或 `bash build-hap.sh`（鸿蒙）的应用。
  */
 package cli
 
@@ -17,14 +17,21 @@ public class TemplateVars {
     let nativeDir: String
     let stdxDir: String
     let targetSection: String
+    /** 鸿蒙应用的安装 ID（bundleName），桌面模板不用 */
+    let bundleName: String
+    /** 应用显示名（桌面模板用项目名，鸿蒙写进 string.json） */
+    let appLabel: String
 
-    public init(projectName: String, packageName: String, frameworkRoot: String, stdxDir: String) {
+    public init(projectName: String, packageName: String, frameworkRoot: String, stdxDir: String,
+                bundleName: String, appLabel: String) {
         this.projectName = projectName
         this.packageName = packageName
         this.frameworkRoot = frameworkRoot
         this.nativeDir = joinPath(frameworkRoot, "native")
         this.stdxDir = stdxDir
         this.targetSection = buildTargetSection(joinPath(frameworkRoot, "native"), stdxDir)
+        this.bundleName = bundleName
+        this.appLabel = appLabel
     }
 }
 
@@ -62,9 +69,35 @@ func renderTemplate(content: String, v: TemplateVars): String {
     out = out.replace("{{FRAMEWORK_ROOT}}", v.frameworkRoot)
     out = out.replace("{{NATIVE_DIR}}", v.nativeDir)
     out = out.replace("{{STDX_DIR}}", v.stdxDir)
+    out = out.replace("{{BUNDLE_NAME}}", v.bundleName)
+    out = out.replace("{{APP_LABEL}}", v.appLabel)
     return out
 }
 
+/**
+ * 模板里哪些文件必须**按字节原样拷**
+ *
+ * 模板要带图标（`resources/base/media/` 下的 png），而 `readText` 走 UTF-8——二进制过一遍
+ * 文本渲染会当场损坏（就算侥幸没崩，png 也变得打不开，要到装到设备上才看得见白方块）。
+ * 判据只看扩展名：模板里不需要「文本渲染的二进制」，真需要再另说。
+ */
+func isBinaryTemplateFile(name: String): Bool {
+    let b = name.toArray()
+    let out = ArrayList<UInt8>()
+    for (i in 0..b.size) {
+        out.add(toLowerByte(b[i]))
+    }
+    let lower = String.fromUtf8(out.toArray())
+    let exts = ["png", "jpg", "jpeg", "gif", "webp", "ico", "ttf", "otf", "woff", "woff2",
+                "so", "dll", "a", "lib", "hap", "zip", "gz", "pdf", "wav", "mp3", "mp4"]
+    for (ext in exts) {
+        if (lower.endsWith("." + ext)) {
+            return true
+        }
+    }
+    return false
+}
+
 /** 项目名 → 仓颉包名（lowerCamelCase）：my-app → myApp */
 func packageNameFrom(name: String): Option<String> {
     let b = name.toArray()
@@ -103,7 +136,22 @@ func packageNameFrom(name: String): Option<String> {
     return Some(String.fromUtf8(out.toArray()))
 }
 
-/** 递归拷贝模板目录：目录建目录、文件渲染后写出 */
+/**
+ * 按字节覆盖写
+ *
+ * 模板里的图片不能走 `writeText`：`readText` 是 UTF-8 解码，读 png 当场抛
+ * `IllegalArgumentException: Invalid unicode scalar value`（create 直接崩、目录留半成品）。
+ */
+func writeBytes(p: String, data: Array<UInt8>): Unit {
+    if (exists(p)) {
+        remove(p)
+    }
+    let f = File.create(p)
+    f.write(data)
+    f.close()
+}
+
+/** 递归拷贝模板目录：目录建目录、文本渲染后写出、二进制原样拷 */
 func copyTree(src: String, dst: String, v: TemplateVars): Int64 {
     var count = 0
     for (info in listDir(src)) {
@@ -116,6 +164,9 @@ func copyTree(src: String, dst: String, v: TemplateVars): Int64 {
         if (info.isDirectory()) {
             ensureDir(d)
             count = count + copyTree(s, d, v)
+        } else if (isBinaryTemplateFile(nm)) {
+            writeBytes(d, File.readFrom(s))
+            count = count + 1
         } else {
             writeText(d, renderTemplate(readText(s), v))
             count = count + 1
@@ -126,13 +177,51 @@ func copyTree(src: String, dst: String, v: TemplateVars): Int64 {
 
 /** 模板别名 → 仓库里的模板目录名（缺省 app，0.3.x 的老用法不受影响） */
 func templateDirName(tpl: String): Option<String> {
-    match (tpl) {
-        case "app" => Some("app")          // 内联 HTML 单文件，零 Node 依赖
-        case "vanilla" => Some("app")
-        case "vue" => Some("app-vue")      // Vue 3 + Vite：dev 走 HMR，发布产单文件
-        case "react" => Some("app-react")  // React 18 + Vite
-        case _ => None
+    if (tpl == "app" || tpl == "vanilla") {
+        return Some("app")          // 内联 HTML 单文件，零 Node 依赖
+    }
+    if (tpl == "vue") {
+        return Some("app-vue")      // Vue 3 + Vite：dev 走 HMR，发布产单文件
     }
+    if (tpl == "react") {
+        return Some("app-react")    // React 18 + Vite
+    }
+    if (tpl == "ohos" || tpl == "ohos-pc" || tpl == "harmonyos" || tpl == "harmonyos-pc") {
+        return Some("ohos-pc")      // 鸿蒙 PC（2in1）：ArkWeb 宿主 + build-hap.sh
+    }
+    return None
+}
+
+/** 该项目是不是鸿蒙脚手架（模板目录名即判据，别名在 templateDirName 里已归一到 ohos-pc） */
+func isOhosScaffoldTemplate(tplDir: String): Bool {
+    return baseName(tplDir) == "ohos-pc"
+}
+
+/**
+ * 项目名 → 缺省 bundleName（`com.example.<小写下划线名>`）
+ *
+ * 鸿蒙要求 bundleName 每一段以字母开头、只含字母数字下划线，且至少三段；
+ * 项目名里的 `-` `.` 之类一律折成 `_`，数字开头补 `app` 前缀。用户可以用 `--bundle` 覆盖。
+ */
+func bundleNameFrom(projectName: String): String {
+    let b = projectName.toArray()
+    let out = ArrayList<UInt8>()
+    for (i in 0..b.size) {
+        let c = toLowerByte(b[i])
+        if (isAsciiAlpha(c) || isAsciiDigit(c)) {
+            out.add(c)
+        } else {
+            out.add(0x5F) // '_'
+        }
+    }
+    var s = String.fromUtf8(out.toArray())
+    if (s.size > 0 && isAsciiDigit(s.toArray()[0])) {
+        s = "app" + s
+    }
+    if (s.size == 0) {
+        s = "app"
+    }
+    return "com.example." + s
 }
 
 /** 解析模板目录：先查别名表，查不到就把参数当模板目录名直接用（方便自己往仓库里加模板） */
@@ -171,10 +260,10 @@ func availableTemplates(fwRoot: String): String {
     return out
 }
 
-func cmdCreate(nameArg: String, tpl: String): Int64 {
+func cmdCreate(nameArg: String, tpl: String, bundleArg: String, labelArg: String): Int64 {
     let targetDir = stripTrailingSep(nameArg)
     if (targetDir.size == 0) {
-        eprintln("用法: cj-tauri create <项目名>")
+        eprintln("用法: cj-tauri create <项目名> [--template app|vue|react|ohos]")
         return 1
     }
     let projectName = baseName(targetDir)
@@ -198,26 +287,38 @@ func cmdCreate(nameArg: String, tpl: String): Int64 {
         eprintln("          请设置环境变量 CJ_TAURI_ROOT 指向 cj-tauri 仓库根目录")
         return 1
     }
-    var stdx = ""
-    if (let Some(s) <- resolveStdx(fwRoot, None)) {
-        stdx = s
-    } else {
-        eprintln("[cj-tauri] 错误: 找不到 stdx 目录")
-        eprintln("          请设置环境变量 CANGJIE_STDX 指向 stdx 动态库目录（含 stdx.encoding.json）")
-        return 1
-    }
+    // 模板先解析：鸿蒙模板**不吃桌面 stdx**（编 hap 时由 build-hap.sh 用 CANGJIE_STDX_OHOS），
+    // 所以它不能因为本机没配 CANGJIE_STDX 就被拦下。
     var tplDir = ""
     if (let Some(d) <- resolveTemplateDir(fwRoot, tpl)) {
         tplDir = d
     } else {
         eprintln("[cj-tauri] 错误: 未知模板 '${tpl}'")
         eprintln("          可用模板: ${availableTemplates(fwRoot)}")
-        eprintln("          别名: app（内联单文件，缺省）/ vue / react")
+        eprintln("          别名: app（内联单文件，缺省）/ vue / react / ohos")
+        return 1
+    }
+    let ohos = isOhosScaffoldTemplate(tplDir)
+    var stdx = ""
+    if (let Some(s) <- resolveStdx(fwRoot, None)) {
+        stdx = s
+    } else if (!ohos) {
+        eprintln("[cj-tauri] 错误: 找不到 stdx 目录")
+        eprintln("          请设置环境变量 CANGJIE_STDX 指向 stdx 动态库目录（含 stdx.encoding.json）")
         return 1
     }
     warnIfSpacey("框架", fwRoot)
 
-    let v = TemplateVars(projectName, pkg, fwRoot, stdx)
+    var bundle = bundleArg
+    if (bundle.size == 0) {
+        bundle = bundleNameFrom(projectName)
+    }
+    var label = labelArg
+    if (label.size == 0) {
+        label = projectName
+    }
+
+    let v = TemplateVars(projectName, pkg, fwRoot, stdx, bundle, label)
     ensureDir(targetDir)
     let count = copyTree(tplDir, targetDir, v)
 
@@ -225,6 +326,22 @@ func cmdCreate(nameArg: String, tpl: String): Int64 {
     println("")
     println("  项目名   : ${projectName}")
     println("  模板     : ${baseName(tplDir)}")
+    if (ohos) {
+        println("  应用名   : ${label}")
+        println("  bundle   : ${bundle}")
+        println("  框架依赖 : ${fwRoot}")
+        println("")
+        println("下一步:")
+        println("  cd ${targetDir}")
+        println("  export CANGJIE_STDX_OHOS=<鸿蒙版 stdx>/linux_ohos_aarch64_cjnative/dynamic/stdx")
+        println("  bash build-hap.sh            # 编 hap")
+        println("  bash build-hap.sh --install  # 编完装到设备并拉起")
+        println("")
+        println("提示: 模板不带签名证书——首次在 DevEco 里 File → Project Structure → Signing Configs")
+        println("      勾「Automatically generate signature」（要登录华为账号）；不签名只能编出")
+        println("      *-unsigned.hap，装不进设备。")
+        return 0
+    }
     println("  仓颉包名 : ${pkg}")
     println("  框架依赖 : ${fwRoot}")
     println("  stdx     : ${stdx}")

package/cli/templates/ohos-pc/AppScope/app.json5

@@ -0,0 +1,13 @@
+{
+  "app": {
+    /* bundleName 是应用在设备上的唯一 ID：两个应用写同一个 bundleName 会互相覆盖安装。
+       改它必须重新签名——DevEco 的「自动签名」会按新包名重新申请 profile。 */
+    "bundleName": "{{BUNDLE_NAME}}",
+    "vendor": "{{PROJECT_NAME}}",
+    "versionCode": 1000000,
+    "versionName": "1.0.0",
+    "buildVersion": "1",
+    "icon": "$media:layered_image",
+    "label": "$string:app_name"
+  }
+}

package/cli/templates/ohos-pc/AppScope/resources/base/element/string.json

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

package/cli/templates/ohos-pc/AppScope/resources/base/media/layered_image.json

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

package/cli/templates/ohos-pc/README.md

@@ -0,0 +1,79 @@
+# {{PROJECT_NAME}} — 仓颉 + ArkWeb 鸿蒙 PC 应用
+
+用 [cj-tauri](https://atomgit.com/qq8864/cj-tauri) 生成的鸿蒙 PC（2in1）应用工程：
+**仓颉后端（静态编译）+ 系统 ArkWeb 前端（HTML/CSS/JS）**，IPC、能力校验、命令分发与桌面版同一套框架代码。
+
+## 目录
+
+```
+{{PROJECT_NAME}}/
+├─ AppScope/app.json5               应用级配置（bundleName = {{BUNDLE_NAME}}）
+├─ build-profile.json5              工程级构建配置（签名留空，见下）
+├─ build-hap.sh                     构建入口（编 hap / 装到设备）
+├─ entry/
+│  ├─ cjpm.toml                     cjTauri 依赖 + aarch64-linux-ohos 目标段
+│  ├─ build-profile.json5           cangjieOptions.checkDeviceTypes=false（放行 2in1）
+│  └─ src/main/
+│     ├─ module.json5               deviceTypes: 2in1 / tablet / phone
+│     ├─ cangjie/
+│     │  ├─ ability_stage.cj        AbilityStage
+│     │  ├─ main_ability.cj         UIAbility：沙箱、rawfile 读取、窗口尺寸、loadContent
+│     │  ├─ index.cj                ArkWeb 宿主组件（javaScriptProxy 双向桥）
+│     │  └─ app_host.cj             框架装配 + demo 命令（greet / timer）
+│     └─ resources/rawfile/
+│        ├─ index.html              页面（改这里）
+│        └─ capabilities.json       能力清单（改这里）
+```
+
+页面与能力清单是 **hap 里的真文件**（rawfile），运行期由 Ability 读成字符串交给框架——
+所以 DevEco 里直接点 Build 也能编过，不需要先跑生成脚本。
+
+## 构建 / 装到设备
+
+```bash
+# 1) 鸿蒙版 stdx（构建期要链它）
+export CANGJIE_STDX_OHOS=<stdx>/linux_ohos_aarch64_cjnative/dynamic/stdx
+
+# 2) DevEco 安装根（脚本会自动探测几个常见位置，探测不到就自己给）
+export DEVECO_WIN='D:\Program Files\Huawei\DevEco Studio'
+
+# 3) 编 hap
+bash build-hap.sh
+
+# 4) 编完装到设备并拉起（需要设备已连上、应用已签名）
+bash build-hap.sh --install
+```
+
+改了鸿蒙侧仓颉代码却没生效时：`bash build-hap.sh --clean`（hvigor 与框架 cjpm 各有一份增量缓存）。
+
+## 签名
+
+模板**不带证书**（调试证书由每台机器的 DevEco 本机生成、与华为账号绑定，不该入库）。
+首次打开请在 DevEco 里 File → Project Structure → Signing Configs，
+勾上「Automatically generate signature」。不签名也能编（产物是 `*-unsigned.hap`），但装不进设备。
+
+## 改应用
+
+- **加命令**：在 `app_host.cj` 里写 `CommandHandler` → `.register("名字", XxxCommand())` →
+  在 `entry/src/main/resources/rawfile/capabilities.json` 的 `commands` 里声明。三处缺一处就用不了
+  （只缺注册 → `command not registered`；只缺清单 → `command not allowed`）。
+- **改页面**：`entry/src/main/resources/rawfile/index.html`，前端只经 `window.__CJ_TAURI__`
+  的 `invoke` / `listen`，并且要**等桥出现**（ArkWeb 没有 document-start 注入）。
+- **联网**：`module.json5` 已声明 `ohos.permission.INTERNET`；用不到就删掉。
+- **窗口尺寸**：`main_ability.cj` **默认不动窗口**——鸿蒙 PC 按桌面形态给的那扇窗（本机 3120×2080 屏上
+  `2090×1394 px`，约屏宽 2/3）就是合适的大小，`logDefaultWindowRect()` 只把它读出来打一行 hilog 当凭证。
+  别在 `onWindowStageCreate` 里 `resize()`：系统先按默认尺寸建窗、你的 resize 紧接着改它，用户看到的是
+  「先弹一个尺寸、随即变成另一个」，观感就是窗口莫名跳一下（这是本模板撤掉两版自定尺寸的原因）。
+  **真要固定尺寸**就自己调 `windowStage.getMainWindow().resize(w, h)`，两个坑记着：`resize()` 收的是**像素**
+  不是 vp（写 vp 量级会得到一扇很小的窗）；`densityPixels` 是 **Float32**，跟 `Float64` 直接相乘编不过，
+  先化成整数百分比再算。
+  上述「系统给的就是桌面窗」的前提是 `entry/build-profile.json5` 的 `deviceTypes` 为 `2in1` 且
+  `cangjieOptions.checkDeviceTypes=false`——写成 phone/tablet 时系统按手机应用塞进竖屏兼容窗（约 600 宽）。
+
+## 已知边界
+
+- 只做了单窗口：`index.cj` 的 `EntryView` 挂一扇窗（label = `main`）。多窗口要按 label 各挂一个宿主。
+- 鸿蒙侧 `javaScriptProxy` 的**返回值传不回页面**，回投靠页面心跳 + `runJavaScript` 推送
+  （已在 `index.cj` 的 `onProxyPost` 里做好，业务代码不用管）。
+- `app.run(html)` 的 `quit()` 只置退出意图，进程仍归系统管（需要真退就 `hdc shell aa force-stop`）。
+- 更多平台细节与踩坑：`docs/鸿蒙ArkWeb接入踩坑.md`（框架仓库内）。

package/cli/templates/ohos-pc/build-hap.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# {{PROJECT_NAME}} —— 鸿蒙 PC（2in1）HAP 构建入口
+#
+# 用法：
+#   bash build-hap.sh              编 hap（产物 entry/build/default/outputs/default/*.hap）
+#   bash build-hap.sh --install    编完后装到设备并拉起（需要设备已连上且应用已签名）
+#   bash build-hap.sh --clean      先删 entry/build 再编（改了 CJ 代码却没生效时用）
+#
+# 前置（三道，缺哪道都只会得到一句误导性的报错，所以脚本里逐条前置检查）：
+#   1. DevEco Studio 6.1+（自带 hvigor 与 node）。安装根默认探测几个常见位置，
+#      不在那儿就 export DEVECO_WIN=<安装根，Windows 形式>。
+#   2. 鸿蒙版 stdx：export CANGJIE_STDX_OHOS=<stdx>/linux_ohos_aarch64_cjnative/dynamic/stdx
+#      —— 缺它 cjpm 会报成「框架缺依赖」，看着像 cjpm.toml 少写了一条。
+#   3. 签名：模板不随包分发证书。**在 DevEco 里** File → Project Structure → Signing Configs
+#      勾「Automatically generate signature」（要登录华为账号）。不签也能 assembleHap，
+#      产物是 *-unsigned.hap，但装不进设备（hdc install 会报 9568289 之类的签名错误）。
+set -e
+
+ROOT_DIR="$(cd "$(dirname "$0")" && pwd)"
+do_install=0
+do_clean=0
+for arg in "$@"; do
+    case "$arg" in
+        --install) do_install=1 ;;
+        --clean) do_clean=1 ;;
+        -h|--help) sed -n '2,20p' "$0"; exit 0 ;;
+        *) echo "[ohos] 未知参数：$arg（支持 --install / --clean / --help）" >&2; exit 2 ;;
+    esac
+done
+
+cd "$ROOT_DIR"
+
+# 环境里可能预置着另一份 DevEco 的路径（有的机器留着 D:\Program Files\Huawei\DevEco Studio\sdk
+# 这种不存在的旧值），hvigor 会直接判「Invalid value of 'DEVECO_SDK_HOME'」——
+# 给了但目录不存在就回退到 DEVECO_WIN 下，并说明忽略了谁。
+pick_deveco_path() {
+    local cand="$1" fb="$2"
+    if [ -n "$cand" ] && [ -d "$(cygpath -u "$cand")" ]; then
+        printf '%s' "$cand"
+        return 0
+    fi
+    [ -n "$cand" ] && echo "[ohos] 忽略无效路径：$cand，改用 $fb" >&2
+    printf '%s' "$fb"
+}
+
+# DevEco 安装根探测：DEVECO_WIN 优先，否则试几个常见位置，都不行就报一句能照做的错。
+find_deveco() {
+    if [ -n "${DEVECO_WIN:-}" ]; then
+        printf '%s' "$DEVECO_WIN"
+        return 0
+    fi
+    local cand
+    for cand in \
+        "D:\\oh\\DevEcoStudio" \
+        "C:\\Program Files\\Huawei\\DevEco Studio" \
+        "D:\\Program Files\\Huawei\\DevEco Studio" \
+        "C:\\Program Files (x86)\\Huawei\\DevEco Studio"; do
+        if [ -d "$(cygpath -u "$cand")/tools/hvigor" ]; then
+            printf '%s' "$cand"
+            return 0
+        fi
+    done
+    return 1
+}
+
+if ! DEVECO_WIN="$(find_deveco)"; then
+    echo "[ohos] 找不到 DevEco Studio。请 export DEVECO_WIN=<安装根，Windows 形式>" >&2
+    echo "       例：export DEVECO_WIN='D:\\Program Files\\Huawei\\DevEco Studio'" >&2
+    exit 1
+fi
+export DEVECO_WIN
+# 注意分隔符：hvigor 会校验这两个变量，混合斜杠会被判「Invalid value」。
+export DEVECO_SDK_HOME="$(pick_deveco_path "${DEVECO_SDK_HOME:-}" "$DEVECO_WIN\\sdk")"
+export NODE_HOME="$(pick_deveco_path "${NODE_HOME:-}" "$DEVECO_WIN\\tools\\node")"
+
+: "${CANGJIE_STDX_OHOS:?请先 export CANGJIE_STDX_OHOS=<鸿蒙版 stdx>/linux_ohos_aarch64_cjnative/dynamic/stdx}"
+
+# hvigor 拿的是 Windows 形式的环境变量，bash 这边起 node 用 POSIX 形式（MSYS 只认后者）
+dev_posix="$(cygpath -u "$DEVECO_WIN")"
+node_exe="$dev_posix/tools/node/node.exe"
+hvigor_js="$dev_posix/tools/hvigor/bin/hvigorw.js"
+if [ ! -f "$hvigor_js" ]; then
+    echo "[ohos] $hvigor_js 不存在——DEVECO_WIN 指对了没？" >&2
+    exit 1
+fi
+
+# 仓颉插件的位置由 hvigorw 自己按顺序找，找到后它自己把工程 node_modules/@ohos 下的 junction
+# 建起来（不用手工 mklink）。headless 从命令行起必须自己给，否则报的是
+# 「property name must be valid: cangjieOptions」——看着像工程配置写错，其实是插件没被加载。
+if [ -z "${DEVECO_HVIGOR_CANGJIE_PLUGIN:-}" ]; then
+    appdata_posix="$(cygpath -u "${APPDATA:-$USERPROFILE\\AppData\\Roaming}")"
+    cjb="$(ls -d "$appdata_posix"/Huawei/DevEcoStudio*/plugins/devecostudio-cangjie-plugin-*/lib/hvigor/cangjie-build-support 2>/dev/null | head -1)"
+    if [ -n "$cjb" ]; then
+        export DEVECO_HVIGOR_CANGJIE_PLUGIN="$(cygpath -w "$cjb")"
+    else
+        echo "[ohos] 找不到仓颉构建插件（DevEco 用户目录 plugins/devecostudio-cangjie-plugin-*/lib/hvigor/cangjie-build-support）" >&2
+        echo "       请 export DEVECO_HVIGOR_CANGJIE_PLUGIN=<该目录>" >&2
+        exit 1
+    fi
+fi
+
+# 插件「能 require 到」≠「被判定为已启用」：未启用时它会主动把 cangjie 的 schema 删掉且不报错
+# （终端只剩 00303038 一行）。两个开关都给上。
+export DEVECO_CANGJIE_PLUGIN_ENABLED=true
+export NODE_PATH="$(cygpath -w "$(pwd)/node_modules")"
+
+# SDK 自带的 cjpm.exe 硬依赖 libcangjie-runtime.dll（不在 cjpm.exe 旁边，在 runtime/lib 下）：
+# 缺它 hvigor 只报 01101000，底层退出码 0xC0000139，21ms 就「跑完」。
+CANGJIE_SDK="${CANGJIE_SDK:-$(ls -d "$HOME"/.cangjie-sdk/*/cangjie 2>/dev/null | sort -V | tail -1)}"
+cjsdk_rt="$CANGJIE_SDK/build-tools/runtime/lib/windows_x86_64_cjnative"
+cjsdk_bin="$CANGJIE_SDK/build-tools/bin"
+cjsdk_tools_bin="$CANGJIE_SDK/build-tools/tools/bin"
+if [ -d "$cjsdk_rt" ]; then
+    export PATH="$cjsdk_rt:$PATH"
+else
+    echo "[ohos] 找不到仓颉运行库目录（$cjsdk_rt），cjpm 会以 0xC0000139 退出" >&2
+    echo "       请 export CANGJIE_SDK=<.cangjie-sdk/<版本>/cangjie>" >&2
+fi
+
+# cjc 与 opt 必须来自**同一套** SDK：cjc 按 CANGJIE_HOME 找 opt，PATH 上钉 cjc 而 CANGJIE_HOME
+# 指向桌面 SDK 时会出现「1.1.3 的 cjc + 1.2.0 的 opt」→ EnumReflection format: operand numbers error!
+if [ -d "$cjsdk_bin" ]; then
+    export PATH="$cjsdk_bin:$cjsdk_tools_bin:$PATH"
+    export CANGJIE_HOME="$(cygpath -w "$CANGJIE_SDK/build-tools")"
+    echo "[ohos] cjc = $(command -v cjc 2>/dev/null) ($(cjc --version 2>/dev/null | head -1))"
+    echo "[ohos] CANGJIE_HOME = $CANGJIE_HOME"
+fi
+
+# entry/cjpm.toml 里 stdx 那条写相对路径 "../stdx"，指向**工程根上的 stdx 联接**：
+# hvigor 只替换它自己的模板变量（${AARCH64_LIBS} 那组），写别的 ${...} 会变空串，
+# 而空串让整条 path-option 一起失效（报错却是「not added as a dependency」，像漏配）。
+stdx_link="$ROOT_DIR/stdx"
+if [ ! -e "$stdx_link" ]; then
+    stdx_src="$(cygpath -u "$CANGJIE_STDX_OHOS")"
+    if [ ! -d "$stdx_src" ]; then
+        echo "[ohos] CANGJIE_STDX_OHOS 指向的目录不存在：$CANGJIE_STDX_OHOS" >&2
+        exit 1
+    fi
+    if command -v cmd >/dev/null 2>&1; then
+        cmd //c mklink //J "$(cygpath -w "$stdx_link")" "$(cygpath -w "$stdx_src")" >/dev/null || {
+            echo "[ohos] 建 stdx 联接失败：$stdx_link -> $stdx_src" >&2
+            exit 1
+        }
+    else
+        ln -s "$stdx_src" "$stdx_link"
+    fi
+    echo "[ohos] 已建 stdx 联接：$stdx_link -> $stdx_src"
+fi
+
+# 改了鸿蒙侧 CJ 代码却没生效时先怀疑产物：hvigor 的 CompileCangjie 与框架侧 cjpm **各有一份**
+# 增量缓存，只清一边会把旧 .so 喂回来，对照实验当场失真（判据看产物尺寸，不看 build success）。
+if [ "$do_clean" = "1" ]; then
+    echo "[ohos] 清理 entry/build 与框架 target/（--clean）"
+    rm -rf "$ROOT_DIR/entry/build"
+fi
+
+# **必须 `--no-daemon`**：hvigor 的常驻 daemon 里 CompileCangjie 用的是它启动时那份 env，
+# 本脚本 export 的 PATH / CANGJIE_HOME 根本进不去（表现是「手跑 cjpm 成功、hvigor 一跑就 opt 崩」）。
+mkdir -p .buildlog
+"$node_exe" "$hvigor_js" --no-daemon --mode module -p product=default -p module=entry@default assembleHap 2>&1 | tee .buildlog/last-build.log
+
+hap="$(ls -t "$ROOT_DIR"/entry/build/default/outputs/default/*.hap 2>/dev/null | head -1)"
+if [ -z "$hap" ]; then
+    echo "[ohos] 构建结束但没有 hap 产物，请查 .buildlog/last-build.log" >&2
+    exit 1
+fi
+echo "[ohos] HAP = $hap ($(wc -c < "$hap") 字节)"
+case "$hap" in
+    *unsigned*)
+        echo "[ohos] 注意：这是未签名包，不能装进设备。在 DevEco 里配好自动签名后重编。" >&2
+        do_install=0
+        ;;
+esac
+
+if [ "$do_install" = "1" ]; then
+    hdc="$dev_posix/sdk/default/openharmony/toolchains/hdc.exe"
+    if [ ! -f "$hdc" ]; then
+        echo "[ohos] 找不到 hdc：$hdc（--install 需要它；也可 export PATH 自带 hdc）" >&2
+        exit 1
+    fi
+    echo "[ohos] 已连设备："
+    "$hdc" list targets
+    echo "[ohos] 安装 $hap"
+    # 路径交给 hdc 前一律 MSYS_NO_PATHCONV：Git Bash 会把 Windows 路径改写成 /d/… 形式，
+    # hdc 拿到就找不到文件。
+    MSYS_NO_PATHCONV=1 "$hdc" install -r "$(cygpath -w "$hap")"
+    echo "[ohos] 启动 EntryAbility"
+    # -a 要用 module.json5 里的 ability 名（EntryAbility），不是仓颉类名 MainAbility。
+    "$hdc" shell aa start -a EntryAbility -b {{BUNDLE_NAME}}
+fi

package/cli/templates/ohos-pc/build-profile.json5

@@ -0,0 +1,46 @@
+{
+  "app": {
+    /* 签名留空：模板不随包分发证书（调试证书由每台机器的 DevEco 本机生成、与华为账号绑定，
+       既不该入库也无法跨机器通用）。
+       在 DevEco 里 File → Project Structure → Signing Configs 勾上
+       「Automatically generate signature」，那一步会把 signingConfigs 填满。
+       不签名也能 `assembleHap`（产物是 *-unsigned.hap），但装不进设备。 */
+    "signingConfigs": [],
+    "products": [
+      {
+        "name": "default",
+        "targetSdkVersion": "6.1.1(24)",
+        "compatibleSdkVersion": "6.1.1(24)",
+        "runtimeOS": "HarmonyOS",
+        "buildOption": {
+          "strictMode": {
+            "caseSensitiveCheck": true,
+            "useNormalizedOHMUrl": true
+          }
+        }
+      }
+    ],
+    "buildModeSet": [
+      {
+        "name": "debug",
+      },
+      {
+        "name": "release"
+      }
+    ]
+  },
+  "modules": [
+    {
+      "name": "entry",
+      "srcPath": "./entry",
+      "targets": [
+        {
+          "name": "default",
+          "applyToProducts": [
+            "default"
+          ]
+        }
+      ]
+    }
+  ]
+}

package/cli/templates/ohos-pc/entry/build-profile.json5

@@ -0,0 +1,26 @@
+{
+  "apiType": "stageMode",
+  "buildOption": {
+    "cangjieOptions": {
+      "path": "./cjpm.toml",
+      /* 关掉「deviceTypes 只能写 phone/tablet」这条门禁（DevEco 仓颉插件的
+         cangjie-pre-build.js 里 `cangjieOptions?.checkDeviceTypes !== false` 才校验）。
+         不关的话 module.json5 写 "2in1" 会直接判 01103012（Only phone and tablet devices
+         are supported）——而只有声明 2in1，鸿蒙 PC 才按桌面应用开窗，否则塞进手机形态的
+         竖屏兼容窗（实测约 600 宽）。 */
+      "checkDeviceTypes": false
+    },
+    "nativeLib": {
+      "filter": {
+        "enableOverride": true
+      }
+    }
+  },
+  "buildOptionSet": [
+  ],
+  "targets": [
+    {
+      "name": "default"
+    }
+  ]
+}

package/cli/templates/ohos-pc/entry/cjpm.toml

@@ -0,0 +1,43 @@
+[package]
+  cjc-version = "1.1.3"
+  compile-option = "--dy-std --cfg=\"${COMPILE_CONDITION_ENTRY}\""
+  description = "{{PROJECT_NAME}} - cj-tauri 鸿蒙入 module"
+  name = "ohos_app_cangjie_entry"
+  output-type = "dynamic"
+  src-dir = "./src/main/cangjie"
+  target-dir = ""
+  version = "1.0.0"
+
+[dependencies]
+  # 源码依赖：hvigor 的 CompileCangjie 会把框架各包按本模块（dynamic）需要的形态编进来。
+  # 路径由 `cj-tauri create --template ohos` 写成**本机绝对路径**；换机器 / 挪仓库后重跑一次
+  # create，或手改这一行（与桌面模板同一条规矩）。
+  cjTauri = { path = "{{FRAMEWORK_ROOT_TOML}}" }
+
+[profile]
+  [profile.build]
+    incremental = true
+    lto = ""
+  [profile.customized-option]
+    debug = "-g -Woff all -Won apilevel-check"
+    release = "--fast-math -O2 -s -Woff all -Won apilevel-check"
+  [profile.test]
+
+[target.aarch64-linux-ohos]
+  compile-option = "-B \"${DEVECO_CANGJIE_HOME}/build-tools/third_party/llvm/bin\" -B \"${DEVECO_OH_NATIVE_HOME}/sysroot/usr/lib/aarch64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/sysroot/usr/lib/aarch64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/llvm/lib/clang/15.0.4/lib/aarch64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/llvm/lib/aarch64-linux-ohos\" --sysroot \"${DEVECO_OH_NATIVE_HOME}/sysroot\""
+[target.aarch64-linux-ohos.bin-dependencies]
+  # 鸿蒙版 stdx：这里写**相对路径**，指向工程根上的 `stdx` 联接（build-hap.sh 用
+  # CANGJIE_STDX_OHOS 建，不入库）。两条实测依据：
+  # ① hvigor 只替换它自己的模板变量（${AARCH64_LIBS} 这组），写别的 ${...} 会变成空串，
+  #    而空串会让**整条 path-option 一起失效**，报错却是
+  #    「imports package 'stdx.encoding.json' ... not added as a dependency」，看着像漏配；
+  # ② 本机绝对路径能编过，但换机器就得改文件，而 DevEco 里点 Build 不经过脚本——
+  #    相对路径两处都通用。
+  path-option = ["${AARCH64_LIBS}", "${AARCH64_MACRO_LIBS}", "${AARCH64_KIT_LIBS}", "../stdx"]
+  package-option = {}
+
+[target.x86_64-linux-ohos]
+  compile-option = "-B \"${DEVECO_CANGJIE_HOME}/build-tools/third_party/llvm/bin\" -B \"${DEVECO_OH_NATIVE_HOME}/sysroot/usr/lib/x86_64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/sysroot/usr/lib/x86_64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/llvm/lib/clang/15.0.4/lib/x86_64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/llvm/lib/x86_64-linux-ohos\" --sysroot \"${DEVECO_OH_NATIVE_HOME}/sysroot\""
+[target.x86_64-linux-ohos.bin-dependencies]
+  path-option = ["${X86_64_OHOS_LIBS}", "${X86_64_OHOS_MACRO_LIBS}", "${X86_64_OHOS_KIT_LIBS}", "../stdx"]
+  package-option = {}