cj-tauri 1.1.2 → 2.1.0

package/src/logging.cj

@@ -1,127 +1,127 @@
-package cjTauri
-
-import std.env.*
-import std.convert.*
-
-/**
- * 日志落盘的策略层（RFC-003 第 5 期）：文件放哪、预算多少、环境变量怎么兜底。
- *
- * 落盘本身在 `src/log_bridge.cj`（进程级、无平台分支）；这里只管策略，纯函数 + `@When` 目录推导。
- *
- * 为什么要环境变量兜底：单文件产物是 Windows 的 GUI 子系统、双击时没有控制台，而**已经分发的
- * exe 改不了代码**——让报障的人带上 `CJ_TAURI_LOG` 再启动一次，就能拿到凭证；
- * 不设这些变量时行为与之前**完全一致**（不落盘、stderr 照旧）。
- */
-
-/** 默认预算：256 KB 一份、留 2 份档案（最坏约 1 MB，常驻托盘类应用也吃得消） */
-public let CJ_LOG_DEFAULT_MAX_KB: Int64 = 256
-public let CJ_LOG_DEFAULT_KEEP: Int64 = 2
-
-/** 应用名缺省值（应用没给名字时用它当文件名） */
-public let CJ_LOG_DEFAULT_APP: String = "app"
-
-/**
- * 单行上限（字节）：页面可控的字符串，超了只记一条说明
- *
- * 8 KiB 够放一段异常栈；不设上限的话，一行天文数字能同时把内存与日志文件撑爆，
- * 而这一行本身还未必有诊断价值。
- */
-public let CJ_LOG_MAX_LINE: Int64 = 8192
-
-/** 读环境变量（空串按未设置算）。公开只为子包用例可见（子包看不到父包非 public 符号） */
-public func logEnvOr(name: String, dflt: String): String {
-    if (let Some(v) <- getVariable(name)) {
-        if (v.size > 0) {
-            return v
-        }
-    }
-    return dflt
-}
-
-/**
- * 解析预算类环境变量（CJ_TAURI_LOG_MAX_KB / CJ_TAURI_LOG_KEEP）
- *
- * 非法值按未设置算，并留一行 stderr——「设了但没生效」比「没设」难查得多。
- * 公开只为子包用例可见（子包看不到父包非 public 符号）
- */
-public func logBudgetFromEnv(name: String, dflt: Int64): Int64 {
-    if (let Some(v) <- getVariable(name)) {
-        if (v.size > 0) {
-            try {
-                let n = Int64.parse(v)
-                if (n > 0) {
-                    return n
-                }
-                eprintln("[cj-tauri] ${name}=\"${v}\" 不是正整数，按默认值 ${dflt} 处理")
-            } catch (e: Exception) {
-                eprintln("[cj-tauri] ${name}=\"${v}\" 解析失败，按默认值 ${dflt} 处理")
-            }
-        }
-    }
-    return dflt
-}
-
-/**
- * 平台惯例的日志目录（不含文件名）
- *
- * Linux 认 `XDG_STATE_HOME`（缺省 `~/.local/state`）：日志属 state，不属 config——
- * 放 `~/.config` 会把「可丢弃的运行痕迹」混进配置备份里。
- */
-@When[os == "Linux"]
-public func defaultLogDir(): String {
-    let base = logEnvOr("XDG_STATE_HOME", "")
-    if (base.size > 0) {
-        return "${base}/cj-tauri"
-    }
-    return "${logEnvOr("HOME", "/tmp")}/.local/state/cj-tauri"
-}
-
-/**
- * 平台惯例的日志目录（不含文件名）
- *
- * Windows 认 `%LOCALAPPDATA%`（`C:\Users\<用户>\AppData\Local`）：单机可丢的数据就该落这里，
- * 漫游配置里不放日志。变量缺失时退到 USERPROFILE，别拼出个以 `\cj-tauri` 开头的绝对路径。
- */
-@When[os == "Windows"]
-public func defaultLogDir(): String {
-    let base = logEnvOr("LOCALAPPDATA", "")
-    if (base.size > 0) {
-        return "${base}\\cj-tauri\\logs"
-    }
-    return "${logEnvOr("USERPROFILE", "C:")}\\AppData\\Local\\cj-tauri\\logs"
-}
-
-/** 目录 + 文件名：分隔符按平台给（C 侧整条路径直接用，不做拼接） */
-@When[os == "Linux"]
-func logPathJoin(dir: String, name: String): String {
-    return "${dir}/${name}"
-}
-
-/** 目录 + 文件名：分隔符按平台给（C 侧整条路径直接用，不做拼接） */
-@When[os == "Windows"]
-func logPathJoin(dir: String, name: String): String {
-    return "${dir}\\${name}"
-}
-
-/** 应用名 → 平台惯例目录下的日志全路径（`CJ_TAURI_LOG` 的覆写由调用方先判） */
-public func defaultLogPath(appName: String): String {
-    let name = if (appName.size > 0) {
-        appName
-    } else {
-        CJ_LOG_DEFAULT_APP
-    }
-    return logPathJoin(defaultLogDir(), "${name}.log")
-}
-
-/**
- * 「环境变量给了就用它，没给才落平台惯例目录」——`setLogToDefaultFile` 的选择器
- *
- * 抽成纯函数只为**可测**：单测里改环境变量会污染同进程的其它用例，所以把「读到什么」
- * 当参数传进来，判据钉在这个函数上（`envPath` 空串＝未设置，与 `logEnvOr` 同口径）。
- */
-public func logPathOrDefault(envPath: String, appName: String): String {
-    if (envPath.size > 0) {
-        return envPath
-    }
-    return defaultLogPath(appName)
-}
+package cjTauri
+
+import std.env.*
+import std.convert.*
+
+/**
+ * 日志落盘的策略层（RFC-003 第 5 期）：文件放哪、预算多少、环境变量怎么兜底。
+ *
+ * 落盘本身在 `src/log_bridge.cj`（进程级、无平台分支）；这里只管策略，纯函数 + `@When` 目录推导。
+ *
+ * 为什么要环境变量兜底：单文件产物是 Windows 的 GUI 子系统、双击时没有控制台，而**已经分发的
+ * exe 改不了代码**——让报障的人带上 `CJ_TAURI_LOG` 再启动一次，就能拿到凭证；
+ * 不设这些变量时行为与之前**完全一致**（不落盘、stderr 照旧）。
+ */
+
+/** 默认预算：256 KB 一份、留 2 份档案（最坏约 1 MB，常驻托盘类应用也吃得消） */
+public let CJ_LOG_DEFAULT_MAX_KB: Int64 = 256
+public let CJ_LOG_DEFAULT_KEEP: Int64 = 2
+
+/** 应用名缺省值（应用没给名字时用它当文件名） */
+public let CJ_LOG_DEFAULT_APP: String = "app"
+
+/**
+ * 单行上限（字节）：页面可控的字符串，超了只记一条说明
+ *
+ * 8 KiB 够放一段异常栈；不设上限的话，一行天文数字能同时把内存与日志文件撑爆，
+ * 而这一行本身还未必有诊断价值。
+ */
+public let CJ_LOG_MAX_LINE: Int64 = 8192
+
+/** 读环境变量（空串按未设置算）。公开只为子包用例可见（子包看不到父包非 public 符号） */
+public func logEnvOr(name: String, dflt: String): String {
+    if (let Some(v) <- getVariable(name)) {
+        if (v.size > 0) {
+            return v
+        }
+    }
+    return dflt
+}
+
+/**
+ * 解析预算类环境变量（CJ_TAURI_LOG_MAX_KB / CJ_TAURI_LOG_KEEP）
+ *
+ * 非法值按未设置算，并留一行 stderr——「设了但没生效」比「没设」难查得多。
+ * 公开只为子包用例可见（子包看不到父包非 public 符号）
+ */
+public func logBudgetFromEnv(name: String, dflt: Int64): Int64 {
+    if (let Some(v) <- getVariable(name)) {
+        if (v.size > 0) {
+            try {
+                let n = Int64.parse(v)
+                if (n > 0) {
+                    return n
+                }
+                eprintln("[cj-tauri] ${name}=\"${v}\" 不是正整数，按默认值 ${dflt} 处理")
+            } catch (e: Exception) {
+                eprintln("[cj-tauri] ${name}=\"${v}\" 解析失败，按默认值 ${dflt} 处理")
+            }
+        }
+    }
+    return dflt
+}
+
+/**
+ * 平台惯例的日志目录（不含文件名）
+ *
+ * Linux 认 `XDG_STATE_HOME`（缺省 `~/.local/state`）：日志属 state，不属 config——
+ * 放 `~/.config` 会把「可丢弃的运行痕迹」混进配置备份里。
+ */
+@When[os == "Linux"]
+public func defaultLogDir(): String {
+    let base = logEnvOr("XDG_STATE_HOME", "")
+    if (base.size > 0) {
+        return "${base}/cj-tauri"
+    }
+    return "${logEnvOr("HOME", "/tmp")}/.local/state/cj-tauri"
+}
+
+/**
+ * 平台惯例的日志目录（不含文件名）
+ *
+ * Windows 认 `%LOCALAPPDATA%`（`C:\Users\<用户>\AppData\Local`）：单机可丢的数据就该落这里，
+ * 漫游配置里不放日志。变量缺失时退到 USERPROFILE，别拼出个以 `\cj-tauri` 开头的绝对路径。
+ */
+@When[os == "Windows"]
+public func defaultLogDir(): String {
+    let base = logEnvOr("LOCALAPPDATA", "")
+    if (base.size > 0) {
+        return "${base}\\cj-tauri\\logs"
+    }
+    return "${logEnvOr("USERPROFILE", "C:")}\\AppData\\Local\\cj-tauri\\logs"
+}
+
+/** 目录 + 文件名：分隔符按平台给（C 侧整条路径直接用，不做拼接） */
+@When[os == "Linux"]
+func logPathJoin(dir: String, name: String): String {
+    return "${dir}/${name}"
+}
+
+/** 目录 + 文件名：分隔符按平台给（C 侧整条路径直接用，不做拼接） */
+@When[os == "Windows"]
+func logPathJoin(dir: String, name: String): String {
+    return "${dir}\\${name}"
+}
+
+/** 应用名 → 平台惯例目录下的日志全路径（`CJ_TAURI_LOG` 的覆写由调用方先判） */
+public func defaultLogPath(appName: String): String {
+    let name = if (appName.size > 0) {
+        appName
+    } else {
+        CJ_LOG_DEFAULT_APP
+    }
+    return logPathJoin(defaultLogDir(), "${name}.log")
+}
+
+/**
+ * 「环境变量给了就用它，没给才落平台惯例目录」——`setLogToDefaultFile` 的选择器
+ *
+ * 抽成纯函数只为**可测**：单测里改环境变量会污染同进程的其它用例，所以把「读到什么」
+ * 当参数传进来，判据钉在这个函数上（`envPath` 空串＝未设置，与 `logEnvOr` 同口径）。
+ */
+public func logPathOrDefault(envPath: String, appName: String): String {
+    if (envPath.size > 0) {
+        return envPath
+    }
+    return defaultLogPath(appName)
+}

package/src/menu.cj

@@ -1,197 +1,197 @@
-package cjTauri
-
-import std.collection.*
-
-/**
- * 窗口菜单栏的**纯仓颉模型**（RFC-002 §5.1）：只描述意图，不含任何平台概念。
- *
- * 分层：模型（本文件）→ `WebViewHost.setMenu()`（src/host.cj）→ C 桥 `cj_bridge_set_menu` →
- * 平台翻译层（native/bridge_win.c 的 CreateMenu 族 / bridge_linux.c 的 GtkMenuBar）。
- * 菜单文本来自**应用作者**（不是页面可控的不可信输入），所以这里不做转义——
- * 非法字段让那一项出局并出声，而不是写一套转义/反转义。
- */
-public enum MenuItemKind {
-    | Normal // 普通项：点击回调自己的 id
-    | Checkbox // 可勾选项：回调里带 checked
-    | Separator // 分隔线：无 id、不可点
-    | Submenu // 子菜单：自身不可点，只承载 children
-}
-
-public class MenuItem {
-    public let id: String
-    public let label: String
-    public let kind: MenuItemKind
-    /** 快捷键**提示**文本（如 "Ctrl+S"）。v1 只显示，不抢页面按键 */
-    public let accelerator: String
-    public var enabled: Bool
-    public var checked: Bool
-    /** 仅 Submenu 用；其它 kind 恒为空表 */
-    public let children: ArrayList<MenuItem>
-
-    public init(id: String, label: String, kind: MenuItemKind, accelerator: String,
-                enabled: Bool, checked: Bool, children: ArrayList<MenuItem>) {
-        this.id = id
-        this.label = label
-        this.kind = kind
-        this.accelerator = accelerator
-        this.enabled = enabled
-        this.checked = checked
-        this.children = children
-    }
-
-    /** 普通菜单项（最常用） */
-    public static func normal(id: String, label: String): MenuItem {
-        return MenuItem(id, label, MenuItemKind.Normal, "", true, false, ArrayList<MenuItem>())
-    }
-
-    /** 带快捷键提示的普通项 */
-    public static func normalWithAccel(id: String, label: String, accelerator: String): MenuItem {
-        return MenuItem(id, label, MenuItemKind.Normal, accelerator, true, false, ArrayList<MenuItem>())
-    }
-
-    /** 勾选项（初始 checked） */
-    public static func checkbox(id: String, label: String, checked: Bool): MenuItem {
-        return MenuItem(id, label, MenuItemKind.Checkbox, "", true, checked, ArrayList<MenuItem>())
-    }
-
-    /** 子菜单：id 留空（自身不回调），动作交给 children */
-    public static func submenu(label: String, children: ArrayList<MenuItem>): MenuItem {
-        return MenuItem("", label, MenuItemKind.Submenu, "", true, false, children)
-    }
-
-    /** 分隔线 */
-    public static func separator(): MenuItem {
-        return MenuItem("", "", MenuItemKind.Separator, "", true, false, ArrayList<MenuItem>())
-    }
-}
-
-/**
- * 菜单模型：`items` 是菜单栏的顶层，子菜单靠 `MenuItem.children` 递归。
- *
- * **不可变**（items 只读）：运行期改状态走 `WebViewHost.setMenuItemState(id, …)`，不在这里改——
- * 状态的真身在平台对象上（Windows 的 HMENU、GTK 的 GtkCheckMenuItem），只改模型平台不会自己变。
- */
-public class MenuModel {
-    public let items: ArrayList<MenuItem>
-
-    public init(items: ArrayList<MenuItem>) {
-        this.items = items
-    }
-
-    /**
-     * 按 id 找菜单项（本层优先，再下钻子菜单）；找不到返回 None
-     *
-     * 为什么要它：运行期改状态按 id 定位（`setMenuItemState`），而**应用层的模型状态**必须
-     * 能反查出「这个 id 现在是什么状态」——平台侧一次写两位（enabled + checked，见
-     * `WebViewHost.setMenuItemState`），拿不到另一维就会把用户刚点出来的勾选抹掉。
-     */
-    public func findById(id: String): Option<MenuItem> {
-        return MenuModel.lookup(this.items, id)
-    }
-
-    private static func lookup(items: ArrayList<MenuItem>, id: String): Option<MenuItem> {
-        for (item in items) {
-            if (item.id == id) {
-                return Some(item)
-            }
-            match (MenuModel.lookup(item.children, id)) {
-                case Some(found) => return Some(found)
-                case None => ()
-            }
-        }
-        return None
-    }
-
-    /**
-     * 线路格式（RFC-002 §5.4）：一行一项，字段用制表符分隔，**行首制表符数 = 层级**。
-     *
-     *     <tabs><kind>\t<id>\t<label>\t<flags>\t<accel>\n
-     *
-     * kind：`n` 普通 / `c` 勾选 / `s` 分隔线 / `m` 子菜单；
-     * flags：十进制，bit0 = 可用、bit1 = 勾选（`3` = 又可用又勾选）；
-     * 分隔线与子菜单也走满 5 个字段（id / label / accel 为空），C 侧因此不必为它们开特例。
-     *
-     * 为什么 kind 放最前：C 侧先分派再取值，日志里一眼能看出这行是什么。
-     * 为什么不是 JSON：C 侧（bridge_core.c）是纯 C、不引第三方，行式文本解析几十行就够，
-     * 且坏了能直接 `fprintf` 到 stderr（诊断走 stderr 是项目铁律）。JSON 留在仓颉侧给 CLI / 清单用。
-     * 为什么不做转义：字段里出现制表符 / 换行会破坏「一行一项」的结构——v1 的口径是
-     * **丢弃该项 + stderr 逐项提示**（见 emit），而不是引入转义/反转义这一对必须同时正确的函数。
-     */
-    public func toWire(): String {
-        return MenuModel.emit(this.items, 0)
-    }
-
-    /** 包内共享（TrayModel 的托盘菜单复用同一遍发射器，别再抄一份格式） */
-    static func emit(items: ArrayList<MenuItem>, depth: Int64): String {
-        var out = ""
-        for (item in items) {
-            if (!MenuModel.wireSafe(item.id) || !MenuModel.wireSafe(item.label) ||
-                !MenuModel.wireSafe(item.accelerator)) {
-                eprintln("[cj-tauri] menu: item dropped from wire (id/label/accelerator contains tab or newline)")
-                continue
-            }
-            out += MenuModel.tabs(depth) + MenuModel.kindCode(item.kind) + "\t" + item.id + "\t" +
-                item.label + "\t" + MenuModel.flags(item).toString() + "\t" + item.accelerator + "\n"
-            if (MenuModel.isSubmenu(item.kind)) {
-                out += MenuModel.emit(item.children, depth + 1)
-            }
-        }
-        return out
-    }
-
-    /**
-     * 枚举值**不能用 `==` 比较**（实测：Cangjie 1.2.0 编译期报
-     * `invalid binary operator '==' on type 'Enum-MenuItemKind' and 'Enum-MenuItemKind'`），只有 match 能判。
-     */
-    private static func isSubmenu(kind: MenuItemKind): Bool {
-        match (kind) {
-            case MenuItemKind.Submenu => true
-            case _ => false
-        }
-    }
-
-    /**
-     * 字段里不许有制表符 / 换行 / 回车：它们是线路格式的结构字符。
-     * 注意本 SDK 里 `for (cp in someString)` 迭代出的是 **UInt8 字节**（不是 UInt32 码点，AGENTS §4 那条已更正）：
-     * 三个结构字符都在 ASCII 范围内，按字节比对既够用、也不受多字节字符影响。
-     */
-    private static func wireSafe(s: String): Bool {
-        for (cp in s) {
-            if (cp == 9u8 || cp == 10u8 || cp == 13u8) {
-                return false
-            }
-        }
-        return true
-    }
-
-    private static func tabs(n: Int64): String {
-        var out = ""
-        var i = 0
-        while (i < n) {
-            out += "\t"
-            i++
-        }
-        return out
-    }
-
-    private static func kindCode(kind: MenuItemKind): String {
-        match (kind) {
-            case MenuItemKind.Normal => "n"
-            case MenuItemKind.Checkbox => "c"
-            case MenuItemKind.Separator => "s"
-            case MenuItemKind.Submenu => "m"
-        }
-    }
-
-    /** flags：bit0 = 可用、bit1 = 勾选（十进制传输，C 侧只要 atoi） */
-    private static func flags(item: MenuItem): Int64 {
-        var f = 0
-        if (item.enabled) {
-            f += 1
-        }
-        if (item.checked) {
-            f += 2
-        }
-        return f
-    }
-}
+package cjTauri
+
+import std.collection.*
+
+/**
+ * 窗口菜单栏的**纯仓颉模型**（RFC-002 §5.1）：只描述意图，不含任何平台概念。
+ *
+ * 分层：模型（本文件）→ `WebViewHost.setMenu()`（src/host.cj）→ C 桥 `cj_bridge_set_menu` →
+ * 平台翻译层（native/bridge_win.c 的 CreateMenu 族 / bridge_linux.c 的 GtkMenuBar）。
+ * 菜单文本来自**应用作者**（不是页面可控的不可信输入），所以这里不做转义——
+ * 非法字段让那一项出局并出声，而不是写一套转义/反转义。
+ */
+public enum MenuItemKind {
+    | Normal // 普通项：点击回调自己的 id
+    | Checkbox // 可勾选项：回调里带 checked
+    | Separator // 分隔线：无 id、不可点
+    | Submenu // 子菜单：自身不可点，只承载 children
+}
+
+public class MenuItem {
+    public let id: String
+    public let label: String
+    public let kind: MenuItemKind
+    /** 快捷键**提示**文本（如 "Ctrl+S"）。v1 只显示，不抢页面按键 */
+    public let accelerator: String
+    public var enabled: Bool
+    public var checked: Bool
+    /** 仅 Submenu 用；其它 kind 恒为空表 */
+    public let children: ArrayList<MenuItem>
+
+    public init(id: String, label: String, kind: MenuItemKind, accelerator: String,
+                enabled: Bool, checked: Bool, children: ArrayList<MenuItem>) {
+        this.id = id
+        this.label = label
+        this.kind = kind
+        this.accelerator = accelerator
+        this.enabled = enabled
+        this.checked = checked
+        this.children = children
+    }
+
+    /** 普通菜单项（最常用） */
+    public static func normal(id: String, label: String): MenuItem {
+        return MenuItem(id, label, MenuItemKind.Normal, "", true, false, ArrayList<MenuItem>())
+    }
+
+    /** 带快捷键提示的普通项 */
+    public static func normalWithAccel(id: String, label: String, accelerator: String): MenuItem {
+        return MenuItem(id, label, MenuItemKind.Normal, accelerator, true, false, ArrayList<MenuItem>())
+    }
+
+    /** 勾选项（初始 checked） */
+    public static func checkbox(id: String, label: String, checked: Bool): MenuItem {
+        return MenuItem(id, label, MenuItemKind.Checkbox, "", true, checked, ArrayList<MenuItem>())
+    }
+
+    /** 子菜单：id 留空（自身不回调），动作交给 children */
+    public static func submenu(label: String, children: ArrayList<MenuItem>): MenuItem {
+        return MenuItem("", label, MenuItemKind.Submenu, "", true, false, children)
+    }
+
+    /** 分隔线 */
+    public static func separator(): MenuItem {
+        return MenuItem("", "", MenuItemKind.Separator, "", true, false, ArrayList<MenuItem>())
+    }
+}
+
+/**
+ * 菜单模型：`items` 是菜单栏的顶层，子菜单靠 `MenuItem.children` 递归。
+ *
+ * **不可变**（items 只读）：运行期改状态走 `WebViewHost.setMenuItemState(id, …)`，不在这里改——
+ * 状态的真身在平台对象上（Windows 的 HMENU、GTK 的 GtkCheckMenuItem），只改模型平台不会自己变。
+ */
+public class MenuModel {
+    public let items: ArrayList<MenuItem>
+
+    public init(items: ArrayList<MenuItem>) {
+        this.items = items
+    }
+
+    /**
+     * 按 id 找菜单项（本层优先，再下钻子菜单）；找不到返回 None
+     *
+     * 为什么要它：运行期改状态按 id 定位（`setMenuItemState`），而**应用层的模型状态**必须
+     * 能反查出「这个 id 现在是什么状态」——平台侧一次写两位（enabled + checked，见
+     * `WebViewHost.setMenuItemState`），拿不到另一维就会把用户刚点出来的勾选抹掉。
+     */
+    public func findById(id: String): Option<MenuItem> {
+        return MenuModel.lookup(this.items, id)
+    }
+
+    private static func lookup(items: ArrayList<MenuItem>, id: String): Option<MenuItem> {
+        for (item in items) {
+            if (item.id == id) {
+                return Some(item)
+            }
+            match (MenuModel.lookup(item.children, id)) {
+                case Some(found) => return Some(found)
+                case None => ()
+            }
+        }
+        return None
+    }
+
+    /**
+     * 线路格式（RFC-002 §5.4）：一行一项，字段用制表符分隔，**行首制表符数 = 层级**。
+     *
+     *     <tabs><kind>\t<id>\t<label>\t<flags>\t<accel>\n
+     *
+     * kind：`n` 普通 / `c` 勾选 / `s` 分隔线 / `m` 子菜单；
+     * flags：十进制，bit0 = 可用、bit1 = 勾选（`3` = 又可用又勾选）；
+     * 分隔线与子菜单也走满 5 个字段（id / label / accel 为空），C 侧因此不必为它们开特例。
+     *
+     * 为什么 kind 放最前：C 侧先分派再取值，日志里一眼能看出这行是什么。
+     * 为什么不是 JSON：C 侧（bridge_core.c）是纯 C、不引第三方，行式文本解析几十行就够，
+     * 且坏了能直接 `fprintf` 到 stderr（诊断走 stderr 是项目铁律）。JSON 留在仓颉侧给 CLI / 清单用。
+     * 为什么不做转义：字段里出现制表符 / 换行会破坏「一行一项」的结构——v1 的口径是
+     * **丢弃该项 + stderr 逐项提示**（见 emit），而不是引入转义/反转义这一对必须同时正确的函数。
+     */
+    public func toWire(): String {
+        return MenuModel.emit(this.items, 0)
+    }
+
+    /** 包内共享（TrayModel 的托盘菜单复用同一遍发射器，别再抄一份格式） */
+    static func emit(items: ArrayList<MenuItem>, depth: Int64): String {
+        var out = ""
+        for (item in items) {
+            if (!MenuModel.wireSafe(item.id) || !MenuModel.wireSafe(item.label) ||
+                !MenuModel.wireSafe(item.accelerator)) {
+                eprintln("[cj-tauri] menu: item dropped from wire (id/label/accelerator contains tab or newline)")
+                continue
+            }
+            out += MenuModel.tabs(depth) + MenuModel.kindCode(item.kind) + "\t" + item.id + "\t" +
+                item.label + "\t" + MenuModel.flags(item).toString() + "\t" + item.accelerator + "\n"
+            if (MenuModel.isSubmenu(item.kind)) {
+                out += MenuModel.emit(item.children, depth + 1)
+            }
+        }
+        return out
+    }
+
+    /**
+     * 枚举值**不能用 `==` 比较**（实测：Cangjie 1.2.0 编译期报
+     * `invalid binary operator '==' on type 'Enum-MenuItemKind' and 'Enum-MenuItemKind'`），只有 match 能判。
+     */
+    private static func isSubmenu(kind: MenuItemKind): Bool {
+        match (kind) {
+            case MenuItemKind.Submenu => true
+            case _ => false
+        }
+    }
+
+    /**
+     * 字段里不许有制表符 / 换行 / 回车：它们是线路格式的结构字符。
+     * 注意本 SDK 里 `for (cp in someString)` 迭代出的是 **UInt8 字节**（不是 UInt32 码点，AGENTS §4 那条已更正）：
+     * 三个结构字符都在 ASCII 范围内，按字节比对既够用、也不受多字节字符影响。
+     */
+    private static func wireSafe(s: String): Bool {
+        for (cp in s) {
+            if (cp == 9u8 || cp == 10u8 || cp == 13u8) {
+                return false
+            }
+        }
+        return true
+    }
+
+    private static func tabs(n: Int64): String {
+        var out = ""
+        var i = 0
+        while (i < n) {
+            out += "\t"
+            i++
+        }
+        return out
+    }
+
+    private static func kindCode(kind: MenuItemKind): String {
+        match (kind) {
+            case MenuItemKind.Normal => "n"
+            case MenuItemKind.Checkbox => "c"
+            case MenuItemKind.Separator => "s"
+            case MenuItemKind.Submenu => "m"
+        }
+    }
+
+    /** flags：bit0 = 可用、bit1 = 勾选（十进制传输，C 侧只要 atoi） */
+    private static func flags(item: MenuItem): Int64 {
+        var f = 0
+        if (item.enabled) {
+            f += 1
+        }
+        if (item.checked) {
+            f += 2
+        }
+        return f
+    }
+}