cj-tauri 1.1.2 → 2.1.0

package/src/plugins/serial/serial_manager_ohos.cj

@@ -0,0 +1,92 @@
+package cjTauri.plugins.serial
+
+// 桌面侧看不到这个文件里的 `@When[env == "ohos"]` 函数体，`ArrayList` 就成「未使用」——
+// 按 AGENTS §4「跨平台文件别按单平台警告去清 import」，给 import 加同款门禁，而不是删掉它。
+@When[env == "ohos"]
+import std.collection.*
+
+/**
+ * 鸿蒙侧 USB 串口后端：**如实降级，不做互操作**
+ *
+ * ## 为什么这里是空的（2026-10-24 真机 A/B 实测，别再徒手重试）
+ *
+ * 原本的落法是「仓颉侧经 `ohos.ark_interop` 调 `@ohos.usbManager.serial`」，三组对照把它否掉了：
+ *
+ * | 产物 | 内容 | 真机结果 |
+ * | --- | --- | --- |
+ * | 有互操作、真去用 | `spawn` 出 owner 线程建 `JSRuntime()` | 启动即 `signal:6`（SIGABRT），日志停在 `startApp begin`，`initScripts` 都没打印 |
+ * | 只有互操作、从不执行 | 同名符号全留，owner 线程刻意不起 | **应用正常启动**，页面跑完自检（`pidof` 有、`page end label=main`） |
+ * | 互操作整段摘掉 | 本文件上一版的空桩 | 同样正常启动 |
+ *
+ * 第三组证明「链接 `libohos.ark_interop.so` 本身无害」（`NEEDED` 里两个库、4 个 JSRuntime 符号都在，
+ * 应用照跑）；**真正 abort 的是执行 `JSRuntime()`**。再补一个探针把创建点挪到 UI 线程
+ * （`onWindowStageCreate`，与 ArkTS 同一条线程）——只打出 `runtime probe begin [ui-thread]`，
+ * 结论行永远没出现、进程当场消失。所以不是「Cangjie 轻量线程没有 VM」，
+ * 而是**纯仓颉进程里根本没有 ArkTS VM**；线程换哪儿都一样。
+ *
+ * 结论：`serialManager` 只能由**真正的 ArkTS 侧**调用（混合工程，或应用自己宿主 ArkTS 模块），
+ * 不能关在框架插件的叶子内。ADR 见 `docs/设计决策记录.md` D-022 的 2026-10-24 结论段。
+ *
+ * ## 所以这里的选择
+ *
+ * 保持插件导出面（`serialOpen` 等已按句柄空间分流到这里），但一律**如实报不可用**——
+ * 既不假装成功，也不让「没后台」变成「应用起不来」。POSIX 的 `/dev/ttyS*` 通路不受影响
+ * （`serialOpen` 先试 POSIX，失败才落到这儿）。
+ */
+
+/** 降级原因（命令层原样回给前端，便于页面说清楚为什么不能开 USB 串口） */
+@When[env == "ohos"]
+const OHOS_USB_UNAVAILABLE: String =
+    "USB 串口在鸿蒙上需要 ArkTS 侧调用 serialManager：纯仓颉进程里没有 ArkTS VM，" +
+    "建 JSRuntime 会让进程 SIGABRT（真机 A/B 已证）；请改用 /dev/ttyS* 或走 ArkTS 宿主"
+
+/** 句柄是否属于 USB 串口空间——降级后永远 false，`serialRead/Write/Close` 全部留在 POSIX 侧 */
+@When[env == "ohos"]
+public func usbSerialIsHandle(h: Int64): Bool {
+    let _ = h
+    return false
+}
+
+/** 枚举 USB 串口：降级后恒空（「没有 USB 串口」与「后端不可用」在命令层同形，原因进错误槽） */
+@When[env == "ohos"]
+public func usbSerialListNames(): ArrayList<String> {
+    return ArrayList<String>()
+}
+
+/** 打开 USB 串口：恒回 -3（打不开/未授权）并写明原因 */
+@When[env == "ohos"]
+public func usbSerialOpenByPath(path: String, baud: Int32, dataBits: Int32, parity: Int32,
+                                stopBits: Int32): Int64 {
+    let _ = path
+    let _ = baud
+    let _ = dataBits
+    let _ = parity
+    let _ = stopBits
+    serialOhosSetError(OHOS_USB_UNAVAILABLE)
+    return -3
+}
+
+/** 读：不会有句柄走到这里（`usbSerialIsHandle` 恒 false），保留签名为了上层不分叉 */
+@When[env == "ohos"]
+public func usbSerialReadHandle(h: Int64, maxBytes: Int32, timeoutMs: Int32): Array<UInt8> {
+    let _ = h
+    let _ = maxBytes
+    let _ = timeoutMs
+    return Array<UInt8>(0, repeat: 0)
+}
+
+/** 写：同上，恒 0 字节 */
+@When[env == "ohos"]
+public func usbSerialWriteHandle(h: Int64, data: Array<UInt8>, timeoutMs: Int32): Int32 {
+    let _ = h
+    let _ = data
+    let _ = timeoutMs
+    return 0
+}
+
+/** 关句柄：同上，恒 -4 */
+@When[env == "ohos"]
+public func usbSerialCloseHandle(h: Int64): Int32 {
+    let _ = h
+    return -4
+}

package/src/plugins/serial/serial_ohos.cj

@@ -0,0 +1,529 @@
+package cjTauri.plugins.serial
+
+/**
+ * ohos 侧 serial 真实现（批次 4，issue #5）：NDK FFI 直连 musl libc 的 POSIX 串口面。
+ * 前身是 P-1 桩（serial_ohos_stub.cj，已删）；写法照剪贴板那次的「NDK FFI 直连」模式
+ * （`src/clipboard_bridge.cj`），不经 C 桥、不加能力位。
+ *
+ * 为什么不引 serialport 式的现成库：std / stdx 都没有串口与 termios 绑定；同类项目 sscom
+ * 实测 serialport 依赖 nix/libudev 在 OHOS target 编不过，只能手写 POSIX——本文件同理，
+ * termios 结构体按 musl（aarch64 linux）布局手工按字节偏移读写，不依赖 @C 结构体映射。
+ *
+ * 边界与桌面两端的差异（对齐 RFC §4.6.4 P-2 的口径）：
+ * - 桌面侧「真正的白名单在 C 桥 core」；ohos 没有 C 桥，本文件**就是**安全边界，
+ *   open 前必须再过一次 `serialPathLooksAllowed`（仓颉侧镜像，plugin_serial.cj）——
+ *   页面可控字符串绝不能只靠上层命令层的校验。
+ * - 错误明细是包级共享槽（仓颉没有线程局部），Mutex 守着；并发失败时可能被覆盖，
+ *   代价只是错误文案不准，与桌面「线程局部」的语义差异如实记在这里。
+ * - 读超时用 poll（有数据才 read，与桌面 Linux 桥同口径）；写按预算轮转。
+ * - 设备节点访问在真机上可能要 DDK/USB 权限甚至系统签名（sscom 同款风险），装不上 /
+ *   打不开时本实现如实报错，不伪装成功。
+ */
+
+@When[env == "ohos"]
+import std.collection.*
+
+// std.sync 只被 ohos 门禁代码用（Mutex 状态槽），import 随之门禁——桌面侧整段摘除
+@When[env == "ohos"]
+import std.sync.*
+
+@When[env == "ohos"]
+import std.time.*
+
+@When[env == "ohos"]
+import std.fs.*
+
+@When[env == "ohos"]
+import std.sort.*
+
+// ---- musl libc 的 POSIX 串口面（@C foreign 直连；符号都在 libc，无需 [links] 追加） ----
+
+/** open 只按双参声明：aarch64（AAPCS64）上可变参与固定参的整型传参相同， musl 的 open 直接可用 */
+@When[env == "ohos"]
+@C
+foreign func open(path: CString, flags: Int32): Int32
+
+@When[env == "ohos"]
+@C
+foreign func close(fd: Int32): Int32
+
+@When[env == "ohos"]
+@C
+foreign func read(fd: Int32, buf: CPointer<UInt8>, count: UInt64): Int64
+
+@When[env == "ohos"]
+@C
+foreign func write(fd: Int32, buf: CPointer<UInt8>, count: UInt64): Int64
+
+/** termios 按 64 字节裸缓冲传递（musl aarch64 布局，实际 60 字节） */
+@When[env == "ohos"]
+@C
+foreign func tcgetattr(fd: Int32, termios: CPointer<UInt8>): Int32
+
+@When[env == "ohos"]
+@C
+foreign func tcsetattr(fd: Int32, actions: Int32, termios: CPointer<UInt8>): Int32
+
+@When[env == "ohos"]
+@C
+foreign func cfsetispeed(termios: CPointer<UInt8>, speed: UInt32): Int32
+
+@When[env == "ohos"]
+@C
+foreign func cfsetospeed(termios: CPointer<UInt8>, speed: UInt32): Int32
+
+/** pollfd 按 8 字节裸缓冲：fd(Int32) | events(Int16) | revents(Int16) */
+@When[env == "ohos"]
+@C
+foreign func poll(fds: CPointer<UInt8>, nfds: UInt64, timeout: Int32): Int32
+
+/** errno 与 strerror：给 serialLastError 一句人话（strerror 返回静态串，不释放） */
+@When[env == "ohos"]
+@C
+foreign func __errno_location(): CPointer<Int32>
+
+@When[env == "ohos"]
+@C
+foreign func strerror(errnum: Int32): CString
+
+// ---- Linux/asm-generic 常量（与 sscom 的取值一字不差） ----
+
+// open flags
+const OHOS_O_RDWR: Int32 = 0x2
+const OHOS_O_NOCTTY: Int32 = 0x100
+
+// tcsetattr actions：TCSANOW
+const OHOS_TCSANOW: Int32 = 0
+
+// cflag 位
+const OHOS_CSIZE: UInt32 = 0x30
+const OHOS_CS8: UInt32 = 0x30
+const OHOS_CSTOPB: UInt32 = 0x40
+const OHOS_CREAD: UInt32 = 0x80
+const OHOS_PARENB: UInt32 = 0x100
+const OHOS_PARODD: UInt32 = 0x200
+const OHOS_CLOCAL: UInt32 = 0x800
+
+// iflag 原始位（cfmakeraw 要清的）：IGNBRK|BRKINT|PARMRK|ISTRIP|INLCR|IGNCR|ICRNL|IXON
+const OHOS_IFLAG_RAW: UInt32 = 0x5eb
+
+// lflag 原始位：ECHO|ICANON|ISIG|IEXTEN
+const OHOS_LFLAG_RAW: UInt32 = 0x800b
+
+// poll 事件
+const OHOS_POLLIN: Int16 = 0x1
+const OHOS_POLLOUT: Int16 = 0x4
+// errno：EAGAIN
+const OHOS_EAGAIN: Int32 = 11
+
+/** termios 结构体里 speed 字段的字节偏移（musl aarch64：c_ispeed@52 / c_ospeed@56） */
+const OHOS_TERMIOS_ISPEED: Int64 = 52
+const OHOS_TERMIOS_OSPEED: Int64 = 56
+
+/** c_cc 里 VTIME / VMIN 的下标（Linux 布局）；poll+read 模式下两个都置 0 */
+const OHOS_VTIME: Int64 = 5
+const OHOS_VMIN: Int64 = 6
+
+/** 波特率 → termios 速度常量（asm-generic：B38400 以下连续，往上 0x1000+n）；
+ * 档位与 plugin_serial.cj 的 SERIAL_BAUDS 对齐（那层已拦过一次，这里兜底）。
+ * public：单测要直接构造（跨包可见性，AGENTS §2） */
+public func serialOhosBaudConst(baud: Int32): Option<UInt32> {
+    let low: Option<UInt32> = match (baud) {
+        case 300 => Some(0x7)
+        case 600 => Some(0x8)
+        case 1200 => Some(0x9)
+        case 2400 => Some(0xb)
+        case 4800 => Some(0xc)
+        case 9600 => Some(0xd)
+        case 19200 => Some(0xe)
+        case 38400 => Some(0xf)
+        case _ => None
+    }
+    if (let Some(v) <- low) {
+        return low
+    }
+    match (baud) {
+        case 57600 => Some(0x1001)
+        case 115200 => Some(0x1002)
+        case 230400 => Some(0x1003)
+        case 460800 => Some(0x1004)
+        case 500000 => Some(0x1005)
+        case 921600 => Some(0x1006)
+        case 1000000 => Some(0x1008)
+        case _ => None
+    }
+}
+
+// ---- 错误明细（包级共享槽，Mutex 守护；见文件头与桌面线程局部语义的差异说明） ----
+// 引用 ohos 专属 foreign（strerror / __errno_location / poll）的辅助一律带门禁，
+// 否则桌面构建在链接期找不到符号（AGENTS §4：跨平台文件别按单平台的 warning 清 import）
+
+@When[env == "ohos"]
+let OHOS_SERIAL_ERR_MUTEX = Mutex()
+
+@When[env == "ohos"]
+var ohosSerialLastError = ""
+
+@When[env == "ohos"]
+func serialOhosSetError(msg: String): Unit {
+    OHOS_SERIAL_ERR_MUTEX.lock()
+    ohosSerialLastError = msg
+    OHOS_SERIAL_ERR_MUTEX.unlock()
+}
+
+@When[env == "ohos"]
+func serialOhosErrno(): Int32 {
+    unsafe {
+        let p = __errno_location()
+        if (p.isNull()) {
+            return 0
+        }
+        return p.read(0)
+    }
+}
+
+/** 最近一次 errno 的人话（strerror 返回静态串，不释放）；调用处无需 unsafe */
+@When[env == "ohos"]
+func serialOhosErrnoText(): String {
+    unsafe {
+        return strerror(serialOhosErrno()).toString()
+    }
+}
+
+// ---- termios 裸缓冲的读写辅助（aarch64 是小端；public 供单测直接构造，AGENTS §2） ----
+
+public func serialOhosGetU32(t: CPointer<UInt8>, off: Int64): UInt32 {
+    unsafe {
+        let b0 = UInt32(t.read(off))
+        let b1 = UInt32(t.read(off + 1)) << 8
+        let b2 = UInt32(t.read(off + 2)) << 16
+        let b3 = UInt32(t.read(off + 3)) << 24
+        return b0 | b1 | b2 | b3
+    }
+}
+
+public func serialOhosPutU32(t: CPointer<UInt8>, off: Int64, v: UInt32): Unit {
+    unsafe {
+        t.write(off, UInt8(v & 0xff))
+        t.write(off + 1, UInt8((v >> 8) & 0xff))
+        t.write(off + 2, UInt8((v >> 16) & 0xff))
+        t.write(off + 3, UInt8((v >> 24) & 0xff))
+    }
+}
+
+/** poll 单 fd 单事件：>0 就绪，0 超时，<0 出错（errno 已置） */
+@When[env == "ohos"]
+func serialOhosPollOne(fd: Int32, events: Int16, timeoutMs: Int32): Int32 {
+    let pfd = LibC.malloc<UInt8>(count: 8)
+    unsafe {
+        // fd 低 4 字节小端写入；events 高位偏移 4；revents（偏移 6）由内核填，预清零
+        pfd.write(0, UInt8(Int32(fd) & 0xff))
+        pfd.write(1, UInt8((fd >> 8) & 0xff))
+        pfd.write(2, UInt8((fd >> 16) & 0xff))
+        pfd.write(3, UInt8((fd >> 24) & 0xff))
+        pfd.write(4, UInt8(UInt16(events) & 0xff))
+        pfd.write(5, UInt8((UInt16(events) >> 8) & 0xff))
+        pfd.write(6, UInt8(0))
+        pfd.write(7, UInt8(0))
+    }
+    var r: Int32 = 0
+    unsafe {
+        r = poll(pfd, 1, timeoutMs)
+    }
+    unsafe {
+        LibC.free(pfd)
+    }
+    return r
+}
+
+/**
+ * 打开并配置串口：成功返回 >0 句柄（fd+1，保证恒 >0），失败负码：
+ * -1 参数 / 白名单、-3 open 或 termios 配置失败（明细在 serialLastError()）。
+ * 线程安全：fd 由调用方独占使用；重复 open 同一路径是两次独立连接（与桌面同形）。
+ */
+@When[env == "ohos"]
+public func serialOpen(path: String, baud: Int32, dataBits: Int32, parity: Int32,
+                       stopBits: Int32): Int64 {
+    // ohos 没有桌面 C 桥那层白名单，本函数就是边界：页面可控路径必须在这里再拦一次
+    if (!serialPathLooksAllowed(path)) {
+        serialOhosSetError("path \"${path}\" 不在允许的设备名单内（serialPathLooksAllowed）")
+        return -1
+    }
+    if (serialOhosBaudConst(baud).isNone()) {
+        serialOhosSetError("不支持的波特率 ${baud}")
+        return -1
+    }
+    if (dataBits < 5 || dataBits > 8) {
+        serialOhosSetError("dataBits 只收 5..8（拿到 ${dataBits}）")
+        return -1
+    }
+    if (parity < 0 || parity > 2) {
+        serialOhosSetError("parity 只收 0|1|2（拿到 ${parity}）")
+        return -1
+    }
+    if (stopBits != 1 && stopBits != 2) {
+        serialOhosSetError("stopBits 只收 1|2（拿到 ${stopBits}）")
+        return -1
+    }
+
+    var fd: Int32 = 0
+    unsafe {
+        let cpath = LibC.mallocCString(path)
+        fd = open(cpath, OHOS_O_RDWR | OHOS_O_NOCTTY)
+        LibC.free(cpath)
+    }
+    if (fd < 0) {
+        // POSIX 打不开就走 serialManager（serial_manager_ohos.cj）。普通三方应用对 /dev/bus
+        // 整体不可达（SELinux，连 hdc shell 都进不去），seriaManager 由系统代管设备节点、
+        // 用户点一次授权即可——这是三方应用碰 USB 串口的正路，不是「降级兜底」。
+        let posixErr = serialOhosErrnoText()
+        let usbHandle = usbSerialOpenByPath(path, baud, dataBits, parity, stopBits)
+        if (usbHandle > 0) {
+            return usbHandle
+        }
+        // 两条路都失败：POSIX 的 errno 与 USB 侧原因一并写清，否则只看到「端口表里没有」
+        serialOhosSetError("open failed: POSIX ${posixErr}；USB ${serialLastError()}")
+        return -3
+    }
+
+    let t = LibC.malloc<UInt8>(count: 64)
+    unsafe {
+        for (i in 0..64) {
+            t.write(i, 0)
+        }
+    }
+    var rc: Int32 = 0
+    unsafe {
+        rc = tcgetattr(fd, t)
+    }
+    if (rc != 0) {
+        serialOhosSetError("tcgetattr failed: ${serialOhosErrnoText()}")
+        unsafe {
+            close(fd)
+            LibC.free(t)
+        }
+        return -3
+    }
+
+    // cfmakeraw 等价：清 iflag/lflag 原始位，oflag/lflag 归零，cflag 重设数据位/校验/停止位
+    // （取反用「异或全 1 掩码」：仓颉没有 ~ 运算符，2026-10-24 编译实测）
+    let iflag = serialOhosGetU32(t, 0) & (OHOS_IFLAG_RAW ^ 0xFFFF_FFFF)
+    serialOhosPutU32(t, 0, iflag)
+    serialOhosPutU32(t, 4, 0)
+    var cflag = serialOhosGetU32(t, 8) & ((OHOS_CSIZE | OHOS_PARENB | OHOS_PARODD | OHOS_CSTOPB) ^ 0xFFFF_FFFF)
+    cflag |= OHOS_CREAD | OHOS_CLOCAL
+    // dataBits：CS5..CS8 = 0x00/0x10/0x20/0x30
+    cflag |= UInt32(dataBits - 5) << 4
+    if (parity == 1) {
+        cflag |= OHOS_PARODD | OHOS_PARENB
+    } else if (parity == 2) {
+        cflag |= OHOS_PARENB
+    }
+    if (stopBits == 2) {
+        cflag |= OHOS_CSTOPB
+    }
+    serialOhosPutU32(t, 8, cflag)
+    // lflag 清原始位（c_line@16 与 c_cc 其余位保留，buffer 已按 tcgetattr 的返回初始化）
+    serialOhosPutU32(t, 12, serialOhosGetU32(t, 12) & (OHOS_LFLAG_RAW ^ 0xFFFF_FFFF))
+    // VTIME / VMIN 置 0：read 不自带阻塞预算，超时由 poll 负责（与桌面 Linux 桥同口径）
+    unsafe {
+        t.write(17 + OHOS_VTIME, UInt8(0))
+        t.write(17 + OHOS_VMIN, UInt8(0))
+    }
+
+    match (serialOhosBaudConst(baud)) {
+        case Some(speed) =>
+            unsafe {
+                cfsetispeed(t, speed)
+                cfsetospeed(t, speed)
+            }
+        case None => () // 上面已拦，不可能走到
+    }
+    unsafe {
+        rc = tcsetattr(fd, OHOS_TCSANOW, t)
+    }
+    if (rc != 0) {
+        serialOhosSetError("tcsetattr failed: ${serialOhosErrnoText()}")
+        unsafe {
+            close(fd)
+            LibC.free(t)
+        }
+        return -3
+    }
+    unsafe {
+        LibC.free(t)
+    }
+    return Int64(fd) + 1
+}
+
+/** 最近一次失败的明细（包级共享槽；见文件头与桌面线程局部语义的差异说明） */
+@When[env == "ohos"]
+public func serialLastError(): String {
+    OHOS_SERIAL_ERR_MUTEX.lock()
+    let msg = ohosSerialLastError
+    OHOS_SERIAL_ERR_MUTEX.unlock()
+    return msg
+}
+
+/** ohos 不走桌面 C 桥的枚举（返回 None，list 命令走下面的 serialPortList 目录扫描） */
+@When[env == "ohos"]
+public func serialListC(): Option<ArrayList<String>> {
+    return None
+}
+
+/**
+ * 读：最多 maxBytes 字节、最多等 timeoutMs 毫秒（0 = 立即返回）。
+ * 返回实际读到的字节（空数组 = 超时无数据）。poll 有数据才 read 一次——
+ * 与桌面 Linux 桥「poll + read」同口径，不会在没数据时白等。
+ */
+@When[env == "ohos"]
+public func serialRead(h: Int64, maxBytes: Int32, timeoutMs: Int32): Array<UInt8> {
+    if (usbSerialIsHandle(h)) {
+        return usbSerialReadHandle(h, maxBytes, timeoutMs)
+    }
+    let fd = Int32(h - 1)
+    let ready = serialOhosPollOne(fd, OHOS_POLLIN, timeoutMs)
+    if (ready <= 0) {
+        if (ready < 0) {
+            serialOhosSetError("poll failed: ${serialOhosErrnoText()}")
+        }
+        return Array<UInt8>(0, repeat: 0)
+    }
+    let cap = Int64(maxBytes)
+    let buf = LibC.malloc<UInt8>(count: cap)
+    var n: Int64 = 0
+    unsafe {
+        n = read(fd, buf, UInt64(cap))
+    }
+    var out = Array<UInt8>(0, repeat: 0)
+    if (n > 0) {
+        out = Array<UInt8>(n, repeat: 0)
+        unsafe {
+            for (i in 0..n) {
+                out[i] = buf.read(i)
+            }
+        }
+    } else if (n < 0) {
+        serialOhosSetError("read failed: ${serialOhosErrnoText()}")
+    }
+    unsafe {
+        LibC.free(buf)
+    }
+    return out
+}
+
+/**
+ * 写：在 timeoutMs 预算内尽量写完，返回实际写入字节数（可能 < data.size；负码 = 失败）。
+ * EAGAIN 时 poll(POLLOUT) 等剩余预算，与桌面「预算内尽量写完」的口径一致。
+ */
+@When[env == "ohos"]
+public func serialWrite(h: Int64, data: Array<UInt8>, timeoutMs: Int32): Int32 {
+    if (data.size == 0) {
+        return 0
+    }
+    if (usbSerialIsHandle(h)) {
+        return usbSerialWriteHandle(h, data, timeoutMs)
+    }
+    let fd = Int32(h - 1)
+    let n = data.size
+    let buf = LibC.malloc<UInt8>(count: Int64(n))
+    unsafe {
+        for (i in 0..n) {
+            buf.write(i, data[i])
+        }
+    }
+    let deadline = MonoTime.now() + Duration.millisecond * Int64(timeoutMs)
+    var total: Int64 = 0
+    while (total < n) {
+        var w: Int64 = 0
+        unsafe {
+            w = write(fd, buf + total, UInt64(n - total))
+        }
+        if (w > 0) {
+            total += w
+            continue
+        }
+        if (w < 0 && serialOhosErrno() != OHOS_EAGAIN) {
+            serialOhosSetError("write failed: ${serialOhosErrnoText()}")
+            unsafe {
+                LibC.free(buf)
+            }
+            return -1
+        }
+        let remainMs = (deadline - MonoTime.now()).toMilliseconds()
+        if (remainMs <= 0) {
+            break
+        }
+        let pr = serialOhosPollOne(fd, OHOS_POLLOUT, Int32(remainMs))
+        if (pr < 0) {
+            serialOhosSetError("poll failed: ${serialOhosErrnoText()}")
+            unsafe {
+                LibC.free(buf)
+            }
+            return -1
+        }
+    }
+    unsafe {
+        LibC.free(buf)
+    }
+    return Int32(total)
+}
+
+/** 关闭：0 = 成功；fd 已关（EBADF）按桌面口径返回 -4（幂等拒绝重复关） */
+@When[env == "ohos"]
+public func serialClose(h: Int64): Int32 {
+    if (usbSerialIsHandle(h)) {
+        return usbSerialCloseHandle(h)
+    }
+    let fd = Int32(h - 1)
+    let rc = unsafe {
+        close(fd)
+    }
+    if (rc == 0) {
+        return 0
+    }
+    serialOhosSetError("close failed: ${serialOhosErrnoText()}")
+    return -4
+}
+
+/**
+ * 枚举本机串口（ohos 版）：扫 /dev 顶层 + /dev/bus（鸿蒙特有的 USB 串口落点，sscom 同款），
+ * 按前缀过滤。拿不到目录就跳过；没有设备回空数组——空数组在页面侧语义就是「未发现端口」。
+ */
+@When[env == "ohos"]
+public func serialPortList(): ArrayList<String> {
+    let prefixes = ["ttyUSB", "ttyACM", "ttyS", "ttyAMA", "ttyGS", "ttySC", "ttyPS", "ttyTHS", "tty.", "cu."]
+    let found = ArrayList<String>()
+    for (dir in ["/dev", "/dev/bus"]) {
+        if (!exists(dir)) {
+            continue
+        }
+        var entries: Array<FileInfo>
+        try {
+            entries = Directory.readFrom(dir)
+        } catch (e: Exception) {
+            continue
+        }
+        for (info in entries) {
+            if (info.isDirectory()) {
+                continue
+            }
+            let name = info.path.toString()
+            for (p in prefixes) {
+                if (name.contains(p)) {
+                    found.add(name)
+                    break
+                }
+            }
+        }
+    }
+    // USB 串口只有 serialManager 认得（设备节点由系统代管，/dev 扫描看不见）；
+    // 有权限时两边可能都出现同一个名字，去重后再排序
+    for (name in usbSerialListNames()) {
+        if (!found.contains(name)) {
+            found.add(name)
+        }
+    }
+    sort(found)
+    return found
+}

package/src/plugins/shell/plugin_shell.cj

@@ -3,7 +3,11 @@ package cjTauri.plugins.shell
 import cjTauri.*
 
 import std.collection.*
+// std.fs / std.process 只被桌面两端实现用到（ohos 桩不引用，RFC §4.6.4 P-1）；
+// 将来加新目标（iOS/Android）时按 P-1 重新评估门禁
+@When[env != "ohos"]
 import std.fs.*
+@When[env != "ohos"]
 import std.process.*
 import stdx.encoding.json.*
 
@@ -26,6 +30,14 @@ import stdx.encoding.json.*
  * （编辑器、REPL、npm run dev）仍不要走这里。
  */
 public class ShellPlugin <: Plugin {
+
+    /** 自描述：进程/打开目标仅桌面两端实现（ohos 侧按 P-1 落桩，批次 3-PR3） */
+    public func describe(): PluginManifest {
+        let hosts = ArrayList<String>()
+        hosts.add("webkitgtk")
+        hosts.add("webview2")
+        return PluginManifest(hosts, ArrayList<String>())
+    }
     public init() {}
 
     public func name(): String {
@@ -106,6 +118,7 @@ public func decodeCaptured(bytes: Array<Byte>): String {
  * 跑子进程并返回 (退出码, stdout, stderr)。
  * 程序不存在 / 没有执行权限等情况统一转成 CommandException，前端拿到的是可读原文。
  */
+@When[env != "ohos"]
 func runCaptured(program: String, argv: Array<String>, cwd: String): (Int64, Array<Byte>, Array<Byte>) {
     try {
         if (cwd.size == 0) {
@@ -126,7 +139,8 @@ func runCaptured(program: String, argv: Array<String>, cwd: String): (Int64, Arr
  *     且**不必**经过 `cmd /c start`，省掉一层引号解析与注入面）。
  * 只启动、不等待：用户关不关那个程序与本应用无关，所以用 launch 而不是 execute（后者会阻塞 UI 线程）。
  */
-@When[os == "Linux"]
+// 鸿蒙目标下 os 仍报 Linux（探针实测），这段必须显式排除 ohos——否则会与下面的 ohos 桩重名
+@When[os == "Linux" && env != "ohos"]
 func launchOpenTarget(target: String): Unit {
     let _ = launch("xdg-open", [target])
 }
@@ -136,6 +150,20 @@ func launchOpenTarget(target: String): Unit {
     let _ = launch("rundll32.exe", ["url.dll,FileProtocolHandler", target])
 }
 
+// ---------- ohos 桩（RFC §4.6.4 P-1）：编得过、运行期可照做地报错 ----------
+// 平台实现分段的既有先例（launchOpenTarget 的 Linux/Windows 两段）；鸿蒙的原生进程/打开
+// 通路批次 4 走 NDK FFI 接通后，删掉这两段桩、补上真实实现段。
+
+@When[env == "ohos"]
+func launchOpenTarget(target: String): Unit {
+    throw CommandException("shell: shell:open 在 ohos 端暂不支持（P-1 桩，批次 4 走 NDK FFI 接通，见 RFC §4.6.4）")
+}
+
+@When[env == "ohos"]
+func runCaptured(program: String, argv: Array<String>, cwd: String): (Int64, Array<Byte>, Array<Byte>) {
+    throw CommandException("shell: shell:exec 在 ohos 端暂不支持（P-1 桩，批次 4 走 NDK FFI 接通，见 RFC §4.6.4）")
+}
+
 /**
  * shell 插件的命令处理器（两个命令共用一份，按全名分派，与内置 SystemCommands 同形）
  */

package/src/plugins/sqlite/plugin_sqlite.cj

@@ -52,9 +52,17 @@ let SQLITE_ENV_FIXTURE: String = "CJ_SQLITE_FIXTURE"
 /**
  * `sqlite` 插件：只声明「我提供什么」，放行由应用的 capabilities 决定（RFC §5.3）
  */
+// 桌面实现；ohos 侧的同名桩在 sqlite_ohos_stub.cj（RFC §4.6.4 P-1：编得过、调用即可照做地报错）
 public class SqlitePlugin <: Plugin {
     public init() {}
 
+    /** 自描述：FFI 直连系统 sqlite3，仅 Linux 桌面验证过（Windows 未落地、ohos 未验证） */
+    public func describe(): PluginManifest {
+        let hosts = ArrayList<String>()
+        hosts.add("webkitgtk")
+        return PluginManifest(hosts, ArrayList<String>())
+    }
+
     public func name(): String {
         return "sqlite"
     }