cj-tauri 2.0.0 → 2.1.1

package/native/core/bridge_core.c

@@ -1,1626 +1,1681 @@
-/*
- * cj-tauri C 桥公共核心（批次 1）：句柄化的宿主状态 + 平台无关逻辑
- *
- * 契约见 native/bridge_core.h。本文件只放「两平台逐字相同」的东西：
- *   回投队列与批处理（含单条快路径）、对话框单槽状态机、窗口配置与预执行脚本存储、
- *   生命周期标志、以及**全部 cj_bridge_* 导出**（单一来源，两平台导出一致由此保证）。
- * 任何平台能力都经 cj_plat_*，本文件不 include 任何平台头。
- */
-/* 日志落盘要用 ftruncate / fileno 这些 POSIX 名，而桩自检是按 `-std=c99` 编译的，
-   该标准档位下它们默认被隐藏（表象是 implicit declaration 警告）。特性宏必须写在
-   任何 include 之前，否则不生效。 */
-#define _POSIX_C_SOURCE 200809L
-
-#include "bridge_core.h"
-
-/* 日志落盘要用到的 CRT 原语（RFC-003 第 5 期）。这是**编译器运行库**的名字差异，
-   不是平台实现差异——core 依旧不碰 pthread / windows.h / gtk 这些宿主头。 */
-#include <stdarg.h>
-#include <errno.h>
-#include <time.h>
-#include <sys/stat.h>
-#include <fcntl.h>
-#if defined(_WIN32)
-#include <io.h>
-#include <direct.h>
-#define cj_log_open _open
-#define cj_log_dup2 _dup2
-#define cj_log_close _close
-#define cj_log_fileno _fileno
-#define cj_log_mkdir(path) _mkdir(path)
-#define cj_log_truncate(fd) _chsize((fd), 0)
-#define CJ_LOG_OFLAGS (_O_WRONLY | _O_CREAT | _O_APPEND)
-#define CJ_LOG_OMODE (_S_IREAD | _S_IWRITE)
-#else
-#include <unistd.h>
-#define cj_log_open open
-#define cj_log_dup2 dup2
-#define cj_log_close close
-#define cj_log_fileno fileno
-#define cj_log_mkdir(path) mkdir((path), 0755)
-#define cj_log_truncate(fd) ftruncate((fd), 0)
-#define CJ_LOG_OFLAGS (O_WRONLY | O_CREAT | O_APPEND)
-#define CJ_LOG_OMODE 0644
-#endif
-
-/* ===== 内部小工具 ===== */
-
-static char *cj_strdup(const char *s) {
-    size_t n;
-    char *p;
-    if (!s) return NULL;
-    n = strlen(s) + 1;
-    p = (char *)malloc(n);
-    if (!p) return NULL;
-    memcpy(p, s, n);
-    return p;
-}
-
-/* 回投队列整体释放（宿主销毁时兜底） */
-static void cj_js_queue_free(cj_host *h) {
-    js_node *n = h->js_head;
-    while (n) {
-        js_node *next = n->next;
-        free(n->js);
-        free(n);
-        n = next;
-    }
-    h->js_head = NULL;
-    h->js_tail = NULL;
-}
-
-/* ===== 建 / 释放宿主 ===== */
-
-cj_host *cj_bridge_create(void) {
-    cj_host *h = (cj_host *)calloc(1, sizeof(cj_host));
-    if (!h) {
-        cj_logf("[cj-bridge] create host failed: out of memory\n");
-        return NULL;
-    }
-    /* 默认与两平台原先的静态初值一致 */
-    h->win_w = 900;
-    h->win_h = 640;
-    h->devtools = 1;
-    h->win_visible = 1; /* 默认显示：没碰窗口可见性的应用行为不变 */
-    h->js_lock = cj_plat_sync_create();
-    h->dlg_lock = cj_plat_sync_create();
-    h->clip_lock = cj_plat_sync_create();
-    if (!h->js_lock || !h->dlg_lock || !h->clip_lock) {
-        if (h->js_lock) cj_plat_sync_destroy(h->js_lock);
-        if (h->dlg_lock) cj_plat_sync_destroy(h->dlg_lock);
-        if (h->clip_lock) cj_plat_sync_destroy(h->clip_lock);
-        free(h);
-        cj_logf("[cj-bridge] create host failed: sync init failed\n");
-        return NULL;
-    }
-    cj_logf("[cj-bridge] host created: %p\n", (void *)h);
-    return h;
-}
-
-void cj_bridge_destroy(cj_host *h) {
-    int i;
-    if (!h) return;
-    /* 平台资源先走：COM 环境引用 / 模块句柄等（幂等）。返回 0＝宿主线程还在收尾，
-       它可能仍在用 h（GTK/WebView2 回调的 user_data 就是它）——这时连句柄一起留着不释放。 */
-    if (!cj_plat_fini(h)) {
-        cj_logf("[cj-bridge] destroy: host thread still running, handle kept\n");
-        return;
-    }
-    if (h->js_lock) cj_plat_sync_destroy(h->js_lock);
-    if (h->dlg_lock) cj_plat_sync_destroy(h->dlg_lock);
-    if (h->clip_lock) cj_plat_sync_destroy(h->clip_lock);
-    cj_js_queue_free(h);
-    /* dlg_cur 此时应为空：窗口销毁路径已作废并交了槽位；故意不碰，免得与等待方抢 free */
-    free(h->win_title);
-    free(h->win_icon);
-    free(h->pending_menu_text);
-    free(h->pending_hotkeys);
-    free(h->pending_tray);
-    for (i = 0; i < h->init_script_count; i++) {
-        free(h->init_scripts[i]);
-    }
-    free(h->init_scripts);
-    free(h->pending_html);
-    free(h->pending_url);
-    cj_logf("[cj-bridge] host destroyed: %p\n", (void *)h);
-    free(h);
-}
-
-void cj_bridge_init(cj_host *h, cj_on_message_fn m, cj_on_destroy_fn d) {
-    if (!h) return;
-    h->on_message = m;
-    h->on_destroy = d;
-    cj_plat_init(h); /* 平台一次性初始化（Windows 在这里装 COM vtbl 并打 init 日志） */
-    /* 能力位：平台给静态事实（有没有菜单 / 托盘 / 拖放），core 只缓存——仓颉侧 system:host 如实上报 */
-    h->capabilities = cj_plat_host_capabilities(h);
-    cj_logf("[cj-bridge] host capabilities: 0x%x (menu=%d tray=%d dragDrop=%d notify=%d hotkey=%d)\n",
-            (unsigned)h->capabilities,
-            (h->capabilities & CJ_CAP_MENU) ? 1 : 0,
-            (h->capabilities & CJ_CAP_TRAY) ? 1 : 0,
-            (h->capabilities & CJ_CAP_DRAG_DROP) ? 1 : 0,
-            (h->capabilities & CJ_CAP_NOTIFICATION) ? 1 : 0,
-            (h->capabilities & CJ_CAP_HOTKEY) ? 1 : 0);
-}
-
-/* ===== 窗口配置 / 预执行脚本（必须在 cj_bridge_start 之前注入）===== */
-
-void cj_bridge_set_window(cj_host *h, const char *title, int width, int height) {
-    if (!h) return;
-    cj_logf("[cj-bridge] set window: title=%s size=%dx%d\n",
-            title ? title : "(default)", width, height);
-    free(h->win_title);
-    h->win_title = NULL;
-    if (title) {
-        h->win_title = cj_strdup(title);
-    }
-    if (width > 0) h->win_w = width;
-    if (height > 0) h->win_h = height;
-}
-
-void cj_bridge_set_icon(cj_host *h, const char *path) {
-    if (!h) return;
-    cj_logf("[cj-bridge] set icon: path=%s\n", (path && path[0]) ? path : "(default)");
-    free(h->win_icon);
-    h->win_icon = NULL;
-    if (path && path[0]) {
-        h->win_icon = cj_strdup(path);
-    }
-}
-
-void cj_bridge_set_devtools(cj_host *h, int enabled) {
-    if (!h) return;
-    h->devtools = enabled ? 1 : 0;
-    cj_logf("[cj-bridge] devtools %s\n", h->devtools ? "enabled" : "disabled");
-}
-
-void cj_bridge_add_init_script(cj_host *h, const char *js) {
-    if (!h || !js || !js[0]) {
-        return;
-    }
-    if (h->init_script_count == h->init_script_cap) {
-        int cap = h->init_script_cap ? h->init_script_cap * 2 : 4;
-        char **grown = (char **)realloc(h->init_scripts, (size_t)cap * sizeof(char *));
-        if (!grown) {
-            cj_logf("[cj-bridge] add init script failed: out of memory\n");
-            return;
-        }
-        h->init_scripts = grown;
-        h->init_script_cap = cap;
-    }
-    h->init_scripts[h->init_script_count] = cj_strdup(js);
-    if (!h->init_scripts[h->init_script_count]) {
-        cj_logf("[cj-bridge] add init script failed: out of memory\n");
-        return;
-    }
-    h->init_script_count++;
-    cj_logf("[cj-bridge] init script queued: %d bytes (total %d)\n",
-            (int)strlen(js), h->init_script_count);
-}
-
-/* ===== 菜单栏（RFC-002；v1 只做菜单栏，托盘 / 拖放在后续档期）===== */
-
-void cj_bridge_set_menu(cj_host *h, const char *wire) {
-    int rows = 0;
-    const char *p;
-    if (!h || !wire) return;
-    for (p = wire; *p; p++) {
-        if (*p == '\n') rows++;
-    }
-    cj_logf("[cj-bridge] set menu: %d bytes, %d row(s)\n", (int)strlen(wire), rows);
-    free(h->pending_menu_text);
-    h->pending_menu_text = cj_strdup(wire);
-    /* 两头都要能用：未就绪时平台只记下（建窗时读 h->pending_menu_text），就绪后平台投到 UI 线程重建 */
-    cj_plat_set_menu(h, h->pending_menu_text ? h->pending_menu_text : "");
-}
-
-int cj_bridge_set_titlebar_subtitle(cj_host *h, const char *text) {
-    int rc;
-
-    if (!h || !text) return -1;
-    if (strlen(text) > 1024) return -1;
-    rc = cj_plat_set_titlebar_subtitle(h, text);
-    /* 失败必须留痕：页面上的状态行不出现时，这一行是唯一能区分
-       「应用没调」与「平台没这块」的凭证 */
-    if (rc != 0) {
-        cj_logf("[cj-bridge] titlebar subtitle rejected: rc=%d text=\"%s\"\n", rc, text);
-    }
-    return rc;
-}
-
-void cj_bridge_set_menu_item_state(cj_host *h, const char *id, int enabled, int checked) {
-    if (!h || !id || !id[0]) return;
-    cj_logf("[cj-bridge] set menu item: id=%s enabled=%d checked=%d\n",
-            id, enabled ? 1 : 0, checked ? 1 : 0);
-    cj_plat_menu_item_state(h, id, enabled ? 1 : 0, checked ? 1 : 0);
-}
-
-/* ===== 拖放（RFC-002 §5；v1 载荷只有文件路径）===== */
-
-void cj_bridge_set_drag_drop(cj_host *h, int enabled, int files) {
-    if (!h) return;
-    cj_logf("[cj-bridge] set drag drop: enabled=%d files=%d\n",
-            enabled ? 1 : 0, files ? 1 : 0);
-    h->pending_drop_enabled = enabled ? 1 : 0;
-    h->pending_drop_files = files ? 1 : 0;
-    /* 两头都能用：未就绪时平台只记（本函数已写进 pending 字段，建 view 时读）；
-       就绪后平台投 UI 线程重挂 drag dest */
-    cj_plat_set_drag_drop(h, enabled ? 1 : 0, files ? 1 : 0);
-}
-
-/* ===== 全局快捷键（RFC-003 第 5 期首个落地项）===== */
-
-void cj_bridge_set_global_hotkeys(cj_host *h, const char *wire) {
-    if (!h) return;
-    cj_logf("[cj-bridge] set global hotkeys: %s\n",
-            (wire && wire[0]) ? wire : "(none)");
-    free(h->pending_hotkeys);
-    h->pending_hotkeys = cj_strdup(wire ? wire : "");
-    /* 两头都能用：未就绪时平台只记（建宿主线程后读 h->pending_hotkeys）；
-       就绪后整表替换（ungrab 旧表再 grab 新表）。平台不支持时在 cj_plat_* 里打一行如实说明。 */
-    cj_plat_set_global_hotkeys(h, h->pending_hotkeys ? h->pending_hotkeys : "");
-}
-
-/* ===== 托盘（RFC-002 §7.C）===== */
-
-void cj_bridge_set_tray(cj_host *h, const char *wire) {
-    if (!h) return;
-    cj_logf("[cj-bridge] set tray: %d bytes\n",
-            (int)(wire ? strlen(wire) : 0));
-    free(h->pending_tray);
-    h->pending_tray = cj_strdup(wire ? wire : "");
-    /* 两头都能用：未就绪时平台只记（宿主线程装配时读 h->pending_tray）；
-       就绪后投 UI 线程重建。平台没编托盘支持时在 cj_plat_* 里打一行如实说明。 */
-    cj_plat_set_tray(h, h->pending_tray ? h->pending_tray : "");
-}
-
-/* ===== 窗口可见性 / 最小化到托盘（RFC-003 第 5 期余项）===== */
-
-void cj_bridge_set_window_visible(cj_host *h, int visible) {
-    if (!h) return;
-    cj_logf("[cj-bridge] set window visible: %d\n", visible ? 1 : 0);
-    h->win_visible = visible ? 1 : 0;
-    /* 两头都能用：**未就绪时到此为止**——平台建窗时读 h->win_visible 定稿（建窗那一刻就定下来，
-       比「先显示再藏起来」少一次闪烁）；就绪后平台投 UI 线程执行。 */
-    if (h->ready) {
-        cj_plat_set_window_visible(h, h->win_visible);
-    }
-}
-
-void cj_bridge_set_minimize_to_tray(cj_host *h, int enabled) {
-    if (!h) return;
-    h->minimize_to_tray = enabled ? 1 : 0;
-    cj_logf("[cj-bridge] set minimize to tray: %d\n", h->minimize_to_tray);
-    /* 这里只记 + 转给平台，**不**在此刻查能力位：能力位（cj_plat_init）与「应用有没有真的 setTray」
-       的先后顺序不稳定，提前拒绝会误伤。策略在**真要最小化那一刻**由平台复核托盘是否装上了。 */
-    cj_plat_set_minimize_to_tray(h, h->minimize_to_tray);
-}
-
-/* ===== 运行期操作（投递细节留给平台：各平台的原生时机与日志口径不同）===== */
-
-void cj_bridge_start(cj_host *h, const char *html) {
-    if (!h) return;
-    if (html && html[0]) { /* 空串表示「页面由 cj_bridge_load_url 指定」 */
-        free(h->pending_html);
-        h->pending_html = cj_strdup(html);
-    }
-    cj_plat_start(h);
-}
-
-void cj_bridge_load_url(cj_host *h, const char *url) {
-    if (!h || !url || !url[0]) return;
-    free(h->pending_url);
-    h->pending_url = cj_strdup(url);
-    cj_plat_load_url(h, url);
-}
-
-void cj_bridge_reload(cj_host *h) {
-    if (!h) return;
-    cj_plat_reload(h);
-}
-
-void cj_bridge_open_devtools(cj_host *h) {
-    if (!h) return;
-    cj_plat_open_devtools(h);
-}
-
-void cj_bridge_quit(cj_host *h) {
-    if (!h) return;
-    h->should_quit = 1;
-    /* 平台走与「用户关窗」同一条销毁路径，onDestroy 因此恰好触发一次（批次 1 验收项） */
-    cj_plat_quit(h);
-}
-
-/* ===== 原生 → JS：入队（执行在 UI 线程的 cj_core_flush_js 里）===== */
-
-void cj_bridge_run_js(cj_host *h, const char *js) {
-    js_node *node;
-    int was_empty;
-    if (!h || !js) return;
-    node = (js_node *)calloc(1, sizeof(js_node));
-    if (!node) return;
-    node->js = cj_strdup(js);
-    if (!node->js) {
-        free(node);
-        return;
-    }
-    if (!h->js_lock) {
-        /* 未 init 时直接丢弃，避免未初始化锁 */
-        free(node->js);
-        free(node);
-        return;
-    }
-    cj_plat_sync_lock(h->js_lock);
-    if (h->js_tail) {
-        h->js_tail->next = node;
-    } else {
-        h->js_head = node;
-    }
-    h->js_tail = node;
-    was_empty = (h->js_head == node); /* 队列由空转非空：需要唤醒 UI 线程 */
-    cj_plat_sync_unlock(h->js_lock);
-    if (was_empty) {
-        cj_plat_wake_ui(h); /* 平台自己判断窗口是否已就绪（未就绪就攒着） */
-    }
-}
-
-int cj_bridge_is_ready(cj_host *h) {
-    return h ? (int)h->ready : 0;
-}
-
-int cj_bridge_should_quit(cj_host *h) {
-    return h ? (int)h->should_quit : 0;
-}
-
-/* ===== core 提供给平台的状态迁移 ===== */
-
-void cj_core_set_ready(cj_host *h) {
-    if (h) h->ready = 1;
-}
-
-void cj_core_window_destroyed(cj_host *h) {
-    if (!h) return;
-    h->window_gone = 1;
-    h->should_quit = 1;
-    /* 每个宿主恰好通知一次：无论是用户关窗还是 cj_bridge_quit，都汇到这条路径 */
-    if (!h->destroy_notified) {
-        h->destroy_notified = 1;
-        if (h->on_destroy) {
-            h->on_destroy(h); /* 带上句柄：仓颉侧据此认领「是哪扇窗没了」（多窗口不许再走静态槽） */
-        }
-    }
-    /* 有对话框开着时先作废并唤醒等待方：事件循环退出后挂起的回调不再执行，等待方会永远挂住 */
-    cj_core_dialog_abort(h);
-    /* 剪贴板同理：投递进 UI 线程的读写不会再被执行 */
-    cj_core_clipboard_abort(h);
-}
-
-/* ===== 剪贴板（plugin_clipboard）：单槽 + UI 线程投递 ===== */
-
-/* UI 线程在 GTK 线程上执行真正的剪贴板调用（经平台原语），结果放回槽位并唤醒等待方 */
-/* 返回 1 = 成功（含读出空），0 = 平台失败。UI 线程直行路径靠它取结果。 */
-int cj_core_clipboard_tick(cj_host *h, int is_write, char *text) {
-    int ok = 0;
-    char *readback = NULL;
-
-    if (!h) {
-        free(text);
-        return 0;
-    }
-    if (is_write) {
-        ok = (cj_plat_clipboard_write_text(h, text ? text : "", NULL, 0) == 0);
-        if (ok) {
-            cj_logf("[cj-bridge] clipboard write: %d bytes\n",
-                    text ? (int)strlen(text) : 0);
-        } else {
-            cj_logf("[cj-bridge] clipboard write failed\n");
-        }
-        free(text);
-    } else {
-        readback = cj_plat_clipboard_read_text(h, NULL, 0);
-        ok = 1; /* 读失败按「空结果」处理：NULL 是合法回值（剪贴板为空/非文本）*/
-        cj_logf("[cj-bridge] clipboard read: %s\n",
-                readback ? "got text" : "empty");
-    }
-
-    cj_plat_sync_lock(h->clip_lock);
-    h->clip_ok = ok;
-    h->clip_text = readback;
-    h->clip_ready = 1;
-    h->clip_busy = 0;
-    cj_plat_sync_signal(h->clip_lock);
-    cj_plat_sync_unlock(h->clip_lock);
-    return ok;
-}
-
-/* 作废进行中的剪贴板请求并唤醒等待方（ok=0；等待方知道宿主已不在，不再碰槽位）*/
-void cj_core_clipboard_abort(cj_host *h) {
-    if (!h || !h->clip_lock) return;
-    cj_plat_sync_lock(h->clip_lock);
-    if (h->clip_busy && !h->clip_ready) {
-        h->clip_ok = 0;
-        h->clip_text = NULL;
-        h->clip_ready = 1;
-        h->clip_busy = 0;
-        cj_plat_sync_signal(h->clip_lock);
-    }
-    cj_plat_sync_unlock(h->clip_lock);
-}
-
-/* UI 线程投递的载荷：一个指针 + 一个标志 */
-typedef struct clip_call {
-    cj_host *h;
-    int is_write;
-    char *text;
-} clip_call;
-
-static void clip_idle(void *d) {
-    clip_call *c = (clip_call *)d;
-    if (c) {
-        cj_core_clipboard_tick(c->h, c->is_write, c->text);
-        free(c);
-    }
-}
-
-static int clipboard_execute(cj_host *h, int is_write, char *text, char **out_text) {
-    if (!h || !h->clip_lock) {
-        free(text);
-        return -1;
-    }
-    if (h->window_gone) {
-        free(text);
-        return -3; /* 宿主已销毁：不再往已退出的 GTK 循环投东西 */
-    }
-    cj_plat_sync_lock(h->clip_lock);
-    if (h->clip_busy) {
-        cj_plat_sync_unlock(h->clip_lock);
-        free(text);
-        return -3; /* 剪贴板是单槽：同时只允许一次（并发写抢剪贴板本身就没有意义）*/
-    }
-    h->clip_busy = 1;
-    h->clip_ready = 0;
-    h->clip_ok = 0;
-    h->clip_text = NULL;
-    cj_plat_sync_unlock(h->clip_lock);
-
-    if (cj_plat_is_ui_thread(h)) {
-        /* 已在 UI 线程（对话框同类）：直接做，不投递——投递 + 等待会自锁（AGENTS §4）*/
-        int ok = cj_core_clipboard_tick(h, is_write, text);
-        if (!ok) {
-            return -3;
-        }
-        if (out_text) {
-            *out_text = h->clip_text; /* 所有权交调用方（tick 已把槽位清待取）*/
-            h->clip_text = NULL;
-        }
-    } else {
-        /* 投递的载荷必须堆分配：UI 线程处理完由 clip_idle free（通知路径同款）。
-           早前这里是**栈上**结构体 + clip_idle 里 free，实机当场 munmap_chunk 崩掉
-           （AGENTS §4：跨线程投递的载荷谁 post 谁分配，UI 线程释放）。 */
-        clip_call *call = (clip_call *)malloc(sizeof(clip_call));
-        if (!call) {
-            free(text);
-            cj_core_clipboard_abort(h);
-            return -3;
-        }
-        call->h = h;
-        call->is_write = is_write;
-        call->text = text;
-        if (!cj_plat_post_ui(h, clip_idle, call)) {
-            /* 没投出去 = 回调永不执行：载荷与 text 仍归本函数，就地回收 */
-            free(call);
-            free(text);
-            cj_core_clipboard_abort(h);
-            return -3;
-        }
-        /* 等结果：窗口先关的话，cj_core_window_destroyed 会作废并唤醒（ok=0）*/
-        cj_plat_sync_lock(h->clip_lock);
-        cj_plat_sync_wait(h->clip_lock, &h->clip_ready);
-        if (out_text && h->clip_ok) {
-            *out_text = h->clip_text; /* 所有权交调用方 */
-            h->clip_text = NULL;
-        }
-        cj_plat_sync_unlock(h->clip_lock);
-        if (!h->clip_ok) {
-            return -3;
-        }
-    }
-    return 0;
-}
-
-int cj_bridge_clipboard_write_text(cj_host *h, const char *text) {
-    char *copy = NULL;
-    size_t len;
-    int rc;
-
-    if (!text) {
-        return -1;
-    }
-    len = strlen(text);
-    if (len >= (8u << 20)) {
-        cj_logf("[cj-bridge] clipboard write rejected: %zu bytes exceeds 8 MiB limit\n", len);
-        return -1;
-    }
-    copy = (char *)malloc(len + 1);
-    if (!copy) {
-        return -3;
-    }
-    memcpy(copy, text, len + 1);
-    rc = clipboard_execute(h, 1, copy, NULL);
-    if (rc == 0) {
-        /* 成功行在 tick 里打（字节口径以投递载荷为准）；这里只补参数被拒的取证 */
-    }
-    return rc;
-}
-
-char *cj_bridge_clipboard_read_text(cj_host *h) {
-    char *out = NULL;
-    int rc;
-
-    rc = clipboard_execute(h, 0, NULL, &out);
-    if (rc == 0) {
-        return out; /* 可能为 NULL = 剪贴板为空 / 非文本 */
-    }
-    return NULL;
-}
-
-void cj_bridge_clipboard_free(char *s) {
-    free(s);
-}
-
-/* ===== 通知（plugin_notification）：校验 + 发后即忘 ===== */
-
-/* UI 线程投递的载荷（谁 post 谁分配，UI 线程处理完释放）*/
-typedef struct note_call {
-    cj_host *h;
-    char *title;
-    char *body;
-} note_call;
-
-static void note_idle(void *d) {
-    note_call *c = (note_call *)d;
-    if (c) {
-        int ok = cj_plat_notification_notify(c->h, c->title, c->body, NULL, 0) == 0;
-        cj_logf("[cj-bridge] notification: title=%d bytes -> %s\n",
-                c->title ? (int)strlen(c->title) : 0, ok ? "sent" : "failed");
-        free(c->title);
-        free(c->body);
-        free(c);
-    }
-}
-
-int cj_bridge_notification_notify(cj_host *h, const char *title, const char *body) {
-    char *t_copy = NULL;
-    char *b_copy = NULL;
-    size_t t_len, b_len;
-
-    if (!h || !title || !title[0]) {
-        return -1;
-    }
-    t_len = strlen(title);
-    b_len = body ? strlen(body) : 0;
-    if (t_len > 256 || b_len > (8u << 10)) {
-        cj_logf("[cj-bridge] notification rejected: title=%zu (<=256) body=%zu (<=8192)\n",
-                t_len, b_len);
-        return -1;
-    }
-    if (h->window_gone) {
-        return -3;
-    }
-    /* 平台没声明通知能力（如 Windows 桩阶段）就当场拒绝，别走「发后即忘」：
-       那条路径投递成功就返回 0，UI 线程实际的失败没人带回命令层——桩会被读成成功。 */
-    if (!(h->capabilities & CJ_CAP_NOTIFICATION)) {
-        cj_logf("[cj-bridge] notification rejected: platform does not declare CJ_CAP_NOTIFICATION\n");
-        return -4;
-    }
-    t_copy = (char *)malloc(t_len + 1);
-    if (t_copy) {
-        memcpy(t_copy, title, t_len + 1);
-    }
-    if (body && b_len) {
-        b_copy = (char *)malloc(b_len + 1);
-        if (b_copy) {
-            memcpy(b_copy, body, b_len + 1);
-        }
-    }
-    if (!t_copy || (body && b_len && !b_copy)) {
-        free(t_copy);
-        free(b_copy);
-        return -3;
-    }
-    if (cj_plat_is_ui_thread(h)) {
-        int ok = cj_plat_notification_notify(h, t_copy, b_copy, NULL, 0) == 0;
-        cj_logf("[cj-bridge] notification: title=%d bytes -> %s\n",
-                (int)t_len, ok ? "sent" : "failed");
-        free(t_copy);
-        free(b_copy);
-        return ok ? 0 : -3;
-    }
-    /* 发后即忘：投递后立即返回。载荷归 UI 线程释放（不等待、不占剪贴板那套同步槽）*/
-    {
-        note_call *call = (note_call *)malloc(sizeof(note_call));
-        if (!call) {
-            free(t_copy);
-            free(b_copy);
-            return -3;
-        }
-        call->h = h;
-        call->title = t_copy;
-        call->body = b_copy;
-        if (!cj_plat_post_ui(h, note_idle, call)) {
-            free(t_copy);
-            free(b_copy);
-            free(call);
-            return -3;
-        }
-    }
-    return 0;
-}
-
-/* 线路格式的共享解析（契约见 bridge_core.h 的 cj_menu_row_fn 注释）。
-   就地切分一份副本：字段指针只在回调期间有效，拷贝与释放都在这里管，平台不用操心。 */
-void cj_core_menu_walk(const char *wire, cj_menu_row_fn fn, void *ctx) {
-    char *copy;
-    char *line;
-
-    if (!wire || !fn) return;
-    copy = cj_strdup(wire);
-    if (!copy) return;
-
-    line = copy;
-    while (*line) {
-        char *nl = strchr(line, '\n');
-        char *cur;
-        int depth = 0;
-        char *t1, *t2, *t3, *t4;
-        char *kind_s, *id_s, *label_s, *flags_s, *accel_s;
-
-        if (nl) {
-            *nl = '\0';
-        }
-        while (line[depth] == '\t') {
-            depth++;
-        }
-        cur = line + depth;
-        kind_s = cur;
-        id_s = NULL;
-        label_s = NULL;
-        flags_s = NULL;
-        accel_s = NULL;
-        t1 = strchr(kind_s, '\t');
-        if (t1) {
-            *t1 = '\0';
-            id_s = t1 + 1;
-            t2 = strchr(id_s, '\t');
-            if (t2) {
-                *t2 = '\0';
-                label_s = t2 + 1;
-                t3 = strchr(label_s, '\t');
-                if (t3) {
-                    *t3 = '\0';
-                    flags_s = t3 + 1;
-                    t4 = strchr(flags_s, '\t');
-                    if (t4) {
-                        *t4 = '\0';
-                        accel_s = t4 + 1;
-                    }
-                }
-            }
-        }
-        if (kind_s[0]) { /* kind 为空的行整行跳过；缺字段按空串 / 0——容错优于崩溃 */
-            fn(ctx, depth, kind_s[0], id_s ? id_s : "", label_s ? label_s : "",
-               flags_s ? atoi(flags_s) : 0, accel_s ? accel_s : "");
-        }
-
-        if (!nl) {
-            break;
-        }
-        line = nl + 1;
-    }
-    free(copy);
-}
-
-/* shell 事件编成 JSON（RFC-002 §5.5）：id 做最小转义——应用给的标识里出现 \ 或 " 时
-   不至于把载荷弄坏。（拖放的 paths 到 7.C 才落地，届时照此扩一份路径转义。） */
-static void cj_json_escape_into(char *dst, size_t cap, const char *src) {
-    size_t o = 0;
-    const char *p;
-    if (!dst || cap == 0) return;
-    for (p = src ? src : ""; *p; p++) {
-        if (o + 2 >= cap) break;
-        if (*p == '\\' || *p == '"') {
-            dst[o++] = '\\';
-        }
-        dst[o++] = *p;
-    }
-    dst[o] = '\0';
-}
-
-void cj_core_menu_clicked(cj_host *h, const char *id, int enabled, int checked) {
-    char idbuf[256];
-    char payload[384];
-    if (!h) return;
-    if (!id || !id[0]) {
-        return; /* 没有 id 就没有「被点的项」（分隔线与子菜单不会走到这里）*/
-    }
-    cj_logf("[cj-bridge] menu clicked: id=%s enabled=%d checked=%d\n",
-            id, enabled ? 1 : 0, checked ? 1 : 0);
-    if (!h->on_shell) {
-        return; /* 未注册回调：上面那行日志已经落盘，够诊断了 */
-    }
-    cj_json_escape_into(idbuf, sizeof(idbuf), id);
-    snprintf(payload, sizeof(payload),
-             "{\"kind\":\"menu\",\"id\":\"%s\",\"enabled\":%s,\"checked\":%s}",
-             idbuf, enabled ? "true" : "false", checked ? "true" : "false");
-    /* 带上宿主句柄：仓颉侧按句柄分发到对应窗口，不再依赖进程级静态槽 */
-    h->on_shell(h, payload);
-}
-
-/* 全局快捷键触发：平台在 X11/Win32 事件回调里调，id 是应用注册时给的标识。
-   载荷形状与菜单点击同族（{"kind":"hotkey","id":…}），同走 on_shell 通道。 */
-void cj_core_hotkey_pressed(cj_host *h, const char *id) {
-    char idbuf[256];
-    char payload[320];
-    if (!h) return;
-    if (!id || !id[0]) {
-        return; /* 没有 id 的触发无法路由，直接丢弃（平台侧不该产生） */
-    }
-    cj_logf("[cj-bridge] hotkey pressed: id=%s\n", id);
-    if (!h->on_shell) {
-        return; /* 未注册回调：上面那行日志已经落盘，够诊断了 */
-    }
-    cj_json_escape_into(idbuf, sizeof(idbuf), id);
-    snprintf(payload, sizeof(payload), "{\"kind\":\"hotkey\",\"id\":\"%s\"}", idbuf);
-    h->on_shell(h, payload);
-}
-
-/* 托盘菜单项被点：载荷形状与菜单/快捷键同族，同走 on_shell 通道（RFC-002 §5.5） */
-void cj_core_tray_clicked(cj_host *h, const char *id) {
-    char idbuf[256];
-    char payload[320];
-    if (!h) return;
-    if (!id || !id[0]) {
-        return; /* 没有 id 的点击无法路由（托盘图标本体点击不带 id，平台侧自行决定语义） */
-    }
-    cj_logf("[cj-bridge] tray clicked: id=%s\n", id);
-    if (!h->on_shell) {
-        return;
-    }
-    cj_json_escape_into(idbuf, sizeof(idbuf), id);
-    snprintf(payload, sizeof(payload), "{\"kind\":\"tray\",\"id\":\"%s\"}", idbuf);
-    h->on_shell(h, payload);
-}
-
-/* ===== 拖放落地（RFC-002 §5；URI 解析在 core，桩自检可测）===== */
-
-#define DROP_MAX_PATHS   32
-#define DROP_MAX_PATH_SZ 4096
-
-/* 把一行 URI 变成路径（就地写到 out，返回写入字节数，超上限返回 -1）。
-   file:// URI：剥前缀 + %XX 十六进制解码（file:// 路径里空格等必须转义成 %20）；
-   非 file:// URI：原样保留（v1 载荷语义由页面决定，core 不猜）。 */
-static int drop_uri_to_path(const char *uri, char *out, int out_cap) {
-    int o = 0;
-    const char *p = uri;
-    static const char hex[] = "0123456789ABCDEF";
-    if (strncmp(uri, "file://", 7) == 0) {
-        p = uri + 7;
-        /* file://localhost/... 也算本地路径（RFC 1738 形态，GTK 偶发） */
-        if (strncmp(p, "localhost/", 10) == 0) {
-            p += 9; /* 保留后面的 '/' */
-        }
-    }
-    for (; *p; p++) {
-        if (o >= out_cap - 1) {
-            return -1; /* 超限：丢弃这条（调用方记日志） */
-        }
-        if (p[0] == '%' && p[1] && p[2]) {
-            const char *h1 = strchr(hex, p[1]);
-            const char *h2 = strchr(hex, p[2]);
-            if (h1 && h2) {
-                /* 十六进制位必须严格配对解析；大小写都收（strchr 命中即合法） */
-                out[o++] = (char)((h1 - hex) * 16 + (h2 - hex));
-                p += 2;
-                continue;
-            }
-            /* 伪 % 序列：原样保留，交给页面/文件系统报错，core 不替它猜 */
-        }
-        out[o++] = p[0];
-    }
-    out[o] = '\0';
-    return o;
-}
-
-void cj_core_drop_files(cj_host *h, const char *uri_list) {
-    char paths[DROP_MAX_PATHS][DROP_MAX_PATH_SZ];
-    const char *escaped[DROP_MAX_PATHS];
-    char escaped_buf[DROP_MAX_PATHS][DROP_MAX_PATH_SZ];
-    int count = 0, dropped = 0;
-    const char *line;
-    if (!h || !uri_list) return;
-
-    line = uri_list;
-    while (line && *line && count < DROP_MAX_PATHS) {
-        const char *eol = strchr(line, '\n');
-        size_t len = eol ? (size_t)(eol - line) : strlen(line);
-        char uri[DROP_MAX_PATH_SZ];
-        int n;
-        if (len >= sizeof(uri)) {
-            len = sizeof(uri) - 1; /* 截断后多半解析不出合法路径，走正常丢弃路径 */
-        }
-        memcpy(uri, line, len);
-        uri[len] = '\0';
-        line = eol ? eol + 1 : NULL;
-        /* 去 \r（text/uri-list 行尾常是 \r\n）与空白 */
-        while (len > 0 && (uri[len - 1] == '\r' || uri[len - 1] == ' ')) {
-            uri[--len] = '\0';
-        }
-        /* 注释行（# 开头）与空行跳过（RFC 2483 的 text/uri-list 规范） */
-        if (len == 0 || uri[0] == '#') {
-            continue;
-        }
-        n = drop_uri_to_path(uri, paths[count], DROP_MAX_PATH_SZ);
-        if (n < 0) {
-            dropped++;
-            cj_logf("[cj-bridge] drop: path too long, dropped: %.60s...\n", uri);
-            continue;
-        }
-        count++;
-    }
-    /* 行数超上限：多出的丢弃并计数（本循环因 count 满退出，剩余行都算 dropped） */
-    if (line && *line) {
-        for (; line; line = strchr(line, '\n') ? strchr(line, '\n') + 1 : NULL) {
-            if (*line && *line != '#') {
-                dropped++;
-            }
-        }
-    }
-
-    cj_logf("[cj-bridge] drop: paths=%d first=%.80s%s\n",
-            count, count > 0 ? paths[0] : "",
-            dropped > 0 ? " (some dropped)" : "");
-    if (!h->on_shell || count == 0) {
-        return; /* 未注册回调或空拖放：日志已落盘，够诊断 */
-    }
-    /* 拼 JSON：paths 数组每项转义（文件名可含引号/反斜杠） */
-    {
-        char payload[8192];
-        int o = 0, i;
-        o += snprintf(payload + o, sizeof(payload) - (size_t)o,
-                      "{\"kind\":\"drop\",\"paths\":[");
-        for (i = 0; i < count && o < (int)sizeof(payload) - 16; i++) {
-            cj_json_escape_into(escaped_buf[i], DROP_MAX_PATH_SZ, paths[i]);
-            escaped[i] = escaped_buf[i];
-            o += snprintf(payload + o, sizeof(payload) - (size_t)o,
-                          "%s\"%s\"", i > 0 ? "," : "", escaped[i]);
-        }
-        snprintf(payload + o, sizeof(payload) - (size_t)o, "]}");
-        h->on_shell(h, payload);
-    }
-}
-
-void cj_core_dialog_abort(cj_host *h) {
-    if (!h || !h->dlg_lock) return;
-    cj_plat_sync_lock(h->dlg_lock);
-    if (h->dlg_cur && !h->dlg_ready) {
-        h->dlg_cur->ok = 0;
-        h->dlg_ready = 1;
-        h->dlg_cur = NULL;
-        cj_plat_sync_signal(h->dlg_lock);
-    }
-    cj_plat_sync_unlock(h->dlg_lock);
-}
-
-/* ===== 回投队列：一次空闲窗口拼批回投（UI 线程调用）===== */
-
-void cj_core_flush_js(cj_host *h) {
-    js_node *batch[CJ_JS_BATCH_MAX];
-    char *single = NULL; /* 快路径：接管字符串所有权，省掉一次拷贝 */
-    char *script = NULL;
-    size_t len = 0;
-    size_t cap = 0;
-    int n = 0;
-    int more = 0;
-    int i, j;
-
-    if (!h || !h->js_lock) return;
-
-    cj_plat_sync_lock(h->js_lock);
-    if (h->js_head) {
-        js_node *node = h->js_head;
-        h->js_head = node->next;
-        if (!h->js_head) {
-            h->js_tail = NULL;
-            single = node->js; /* 队里只有这一条 */
-            free(node);
-        } else {
-            batch[n++] = node;
-            while (h->js_head && n < CJ_JS_BATCH_MAX) {
-                node = h->js_head;
-                h->js_head = node->next;
-                if (!h->js_head) {
-                    h->js_tail = NULL;
-                }
-                batch[n++] = node;
-            }
-        }
-    }
-    more = (h->js_head != NULL);
-    cj_plat_sync_unlock(h->js_lock);
-
-    if (single) {
-        cj_plat_post_js(h, single);
-        free(single);
-    } else if (n > 0) {
-        /* 拼批：一段脚本只跨一次语言边界，省掉 n-1 次固定开销。
-           为什么不用 GString 之类的缓冲：core 不依赖平台库（glib / Win32）。 */
-        for (i = 0; i < n; i++) {
-            size_t nl = strlen(batch[i]->js);
-            if (len + nl + 2 > cap) {
-                size_t ncap = (len + nl + 2) * 2;
-                char *grown = (char *)realloc(script, ncap);
-                if (!grown) {
-                    /* 内存不够：退回逐条执行——宁可多花开销，也不丢回投（回投丢了前端会一直 pending）*/
-                    for (j = i; j < n; j++) {
-                        cj_plat_post_js(h, batch[j]->js);
-                    }
-                    for (j = 0; j < n; j++) {
-                        free(batch[j]->js);
-                        free(batch[j]);
-                    }
-                    free(script);
-                    if (more) cj_plat_wake_ui(h);
-                    return;
-                }
-                script = grown;
-                cap = ncap;
-            }
-            memcpy(script + len, batch[i]->js, nl);
-            len += nl;
-            script[len++] = '\n';
-            script[len] = '\0';
-            free(batch[i]->js);
-            free(batch[i]);
-        }
-        cj_plat_post_js(h, script);
-        free(script);
-    }
-
-    /* 队列没取空：自续一次，剩下的下一批走 */
-    if (more) {
-        cj_plat_wake_ui(h);
-    }
-}
-
-/* ===== 原生对话框：单槽状态机（模态，同时只允许一个）===== */
-
-static dlg_req *cj_dlg_req_new(int kind, const char *title, const char *message, const char *filter) {
-    dlg_req *r = (dlg_req *)calloc(1, sizeof(dlg_req));
-    if (!r) return NULL;
-    r->kind = kind;
-    r->title = cj_strdup(title ? title : "");
-    r->message = cj_strdup(message ? message : "");
-    r->filter = cj_strdup(filter ? filter : "");
-    return r;
-}
-
-static void cj_dlg_req_free(dlg_req *r) {
-    if (!r) return;
-    free(r->title);
-    free(r->message);
-    free(r->filter);
-    free(r->path);
-    free(r);
-}
-
-static void cj_dlg_log_closed(const dlg_req *r) {
-    if (r->kind == 0 || r->kind == 1) { /* 文件类才有路径 */
-        cj_logf("[cj-bridge] dialog closed: kind=%d ok=%d path=%s\n",
-                r->kind, r->ok, r->path ? r->path : "(none)");
-    } else {
-        cj_logf("[cj-bridge] dialog closed: kind=%d ok=%d\n", r->kind, r->ok);
-    }
-}
-
-void cj_bridge_set_dialog_callback(cj_host *h, cj_on_dialog_fn cb) {
-    if (!h) return;
-    h->on_dialog = cb;
-}
-
-void cj_bridge_set_shell_callback(cj_host *h, cj_on_shell_fn cb) {
-    if (!h) return;
-    h->on_shell = cb;
-}
-
-int cj_bridge_host_capabilities(cj_host *h) {
-    return h ? h->capabilities : 0;
-}
-
-int cj_bridge_host_eq(cj_host *a, cj_host *b) {
-    /* 只比指针本身：句柄由 core 分配、生命周期也归 core，仓颉侧只当不透明凭据使 */
-    return (a && b && a == b) ? 1 : 0;
-}
-
-int cj_bridge_show_dialog(cj_host *h, int kind, const char *title,
-                          const char *message, const char *filter) {
-    dlg_req *r;
-    int ok;
-
-    if (!h) return 0;
-    if (!h->ready) { /* 没有窗口就没有父窗口，模态对话框无处安放 */
-        cj_logf("[cj-bridge] dialog ignored: host not ready\n");
-        return 0;
-    }
-
-    cj_plat_sync_lock(h->dlg_lock);
-    if (h->dlg_busy) {
-        cj_plat_sync_unlock(h->dlg_lock);
-        cj_logf("[cj-bridge] dialog rejected: another dialog is open\n");
-        return 0;
-    }
-    h->dlg_busy = 1;
-    h->dlg_ready = 0;
-    cj_plat_sync_unlock(h->dlg_lock);
-
-    /* 调用方已经站在 UI 线程上（WebKit 的 script-message / WebView2 的 WebMessageReceived 就跑在那里）：
-       直接弹。这里**不能**走「投递 + 阻塞等待」——等待的事件得由 UI 线程处理，而 UI 线程正卡在这次调用里，
-       等于自己把自己锁死。 */
-    if (cj_plat_is_ui_thread(h)) {
-        cj_logf("[cj-bridge] dialog: kind=%d title=%s (caller on ui thread)\n",
-                kind, title ? title : "");
-        r = cj_dlg_req_new(kind, title, message, filter);
-        if (!r) {
-            cj_plat_sync_lock(h->dlg_lock);
-            h->dlg_busy = 0;
-            cj_plat_sync_unlock(h->dlg_lock);
-            return 0;
-        }
-        r->ok = cj_plat_run_dialog(h, r);
-        ok = r->ok;
-        cj_dlg_log_closed(r);
-        if (h->on_dialog) {
-            h->on_dialog(h, r->path ? r->path : ""); /* 带上句柄：结果只落发起这次对话框的窗口 */
-        }
-        cj_dlg_req_free(r);
-        cj_plat_sync_lock(h->dlg_lock);
-        h->dlg_busy = 0;
-        cj_plat_sync_unlock(h->dlg_lock);
-        return ok;
-    }
-
-    r = cj_dlg_req_new(kind, title, message, filter);
-    if (!r) {
-        cj_plat_sync_lock(h->dlg_lock);
-        h->dlg_busy = 0;
-        cj_plat_sync_unlock(h->dlg_lock);
-        return 0;
-    }
-    cj_logf("[cj-bridge] dialog: kind=%d title=%s\n", kind, r->title);
-    cj_plat_sync_lock(h->dlg_lock);
-    h->dlg_cur = r;
-    cj_plat_sync_unlock(h->dlg_lock);
-
-    cj_plat_post_dialog(h, r);
-
-    /* 等结果：窗口先关的话，cj_core_window_destroyed 会作废并唤醒（ok=0） */
-    cj_plat_sync_lock(h->dlg_lock);
-    cj_plat_sync_wait(h->dlg_lock, &h->dlg_ready);
-    ok = r->ok;
-    h->dlg_busy = 0;
-    cj_plat_sync_unlock(h->dlg_lock);
-    cj_dlg_req_free(r);
-    return ok;
-}
-
-void cj_core_dialog_tick(cj_host *h, dlg_req *req) {
-    int alive;
-    if (!h || !req) return;
-
-    cj_plat_sync_lock(h->dlg_lock);
-    alive = (h->dlg_cur == req);
-    cj_plat_sync_unlock(h->dlg_lock);
-    if (!alive) {
-        /* 窗口先关了：槽位已交回调用方（它会 free 这个请求）——这里连碰都不能碰 */
-        return;
-    }
-
-    req->ok = cj_plat_run_dialog(h, req);
-    cj_dlg_log_closed(req);
-    if (h->on_dialog) {
-        h->on_dialog(h, req->path ? req->path : "");
-    }
-
-    cj_plat_sync_lock(h->dlg_lock);
-    h->dlg_cur = NULL;
-    h->dlg_ready = 1;
-    cj_plat_sync_signal(h->dlg_lock);
-    cj_plat_sync_unlock(h->dlg_lock);
-}
-
-/* =========================================================================
- *  串口（plugin_serial）：路径白名单 + 参数校验 + 导出转发
- *
- *  句柄表与 fd 全在平台层（那边本来就有 pthread / CS），本文件**不持有任何串口状态**——
- *  因此也不需要「一次性初始化」这种钩子，导出函数可以在没有宿主的进程里直接用。
- * ========================================================================= */
-
-#if defined(_MSC_VER)
-#define CJ_THREAD_LOCAL __declspec(thread)
-#else
-#define CJ_THREAD_LOCAL __thread
-#endif
-
-/* 线程局部：命令各自跑在 worker 线程上，静态单槽会被并发调用互相覆盖（AGENTS §4 的静态单槽坑） */
-static CJ_THREAD_LOCAL char g_serial_err[256];
-
-static void cj_serial_err_set(const char *msg) {
-    if (!msg) {
-        g_serial_err[0] = '\0';
-        return;
-    }
-    snprintf(g_serial_err, sizeof(g_serial_err), "%s", msg);
-}
-
-/* 白名单前缀表。**只放行设备节点类路径**：页面递进来的是页面可控字符串，放行面越小越好。
-   注意 "\\.\COM" 与 "COM" 两条要额外约束「后面全是数字」，否则 COMfoo 这种也会被放行。 */
-static const char *const CJ_SERIAL_PREFIXES[] = {
-    "/dev/ttyUSB", "/dev/ttyACM", "/dev/ttyS", "/dev/ttyAMA", "/dev/ttyPS",
-    "/dev/ttyTHS", "/dev/ttyXRUSB", "/dev/ttyV",      /* Linux 串口（含虚拟 ttyV*）*/
-    "/dev/tty.", "/dev/cu.",                          /* macOS：调制解调器 / 呼出设备 */
-    "/dev/serial/by-id/", "/dev/serial/by-path/",     /* udev 稳定符号链接（推荐写法）*/
-    "/dev/pts/",                                      /* 伪终端：socat / openpty 造的虚拟串口 */
-    "COM", "\\\\.\\COM",                              /* Windows：COM3 / 长名形式 */
-};
-
-#define CJ_SERIAL_MAX_PATH 255
-
-int cj_serial_path_allowed(const char *path) {
-    size_t i, n;
-
-    if (!path || !path[0]) return 0;
-    n = strlen(path);
-    if (n > CJ_SERIAL_MAX_PATH) return 0;
-    /* 含 ".." 一律拒绝：否则 "/dev/ttyUSB0/../../etc/shadow" 这种前缀命中就能穿越出去 */
-    if (strstr(path, "..")) return 0;
-
-    for (i = 0; i < sizeof(CJ_SERIAL_PREFIXES) / sizeof(CJ_SERIAL_PREFIXES[0]); i++) {
-        const char *pfx = CJ_SERIAL_PREFIXES[i];
-        size_t pl = strlen(pfx);
-        const char *rest;
-        size_t k;
-
-        if (strncmp(path, pfx, pl) != 0) continue;
-        rest = path + pl;
-        if (!rest[0]) return 0;  /* 前缀本身不是设备名（"/dev/ttyS" 这种不收）*/
-
-        if (strcmp(pfx, "COM") != 0 && strcmp(pfx, "\\\\.\\COM") != 0) {
-            return 1;
-        }
-        for (k = 0; rest[k]; k++) {
-            if (rest[k] < '0' || rest[k] > '9') return 0;
-            if (k >= 3) return 0; /* COM1..COM999（Windows 实际到 COM256）*/
-        }
-        return 1;
-    }
-    return 0;
-}
-
-static int cj_serial_cfg_ok(const cj_serial_cfg *cfg) {
-    if (!cfg) return 0;
-    if (cfg->baud <= 0) return 0;
-    if (cfg->data_bits < 5 || cfg->data_bits > 8) return 0;
-    if (cfg->parity < 0 || cfg->parity > 2) return 0;
-    if (cfg->stop_bits != 1 && cfg->stop_bits != 2) return 0;
-    return 1;
-}
-
-long long cj_bridge_serial_open(const char *path, int baud, int data_bits, int parity, int stop_bits) {
-    cj_serial_cfg cfg;
-    char err[256];
-    long long h;
-
-    g_serial_err[0] = '\0';
-    if (!path || !path[0]) {
-        cj_serial_err_set("serial: 设备路径为空");
-        return -1;
-    }
-    if (!cj_serial_path_allowed(path)) {
-        snprintf(g_serial_err, sizeof(g_serial_err),
-                 "serial: 路径不在白名单内（只放行串口设备节点 / 伪终端，且不得含 ..）: %s", path);
-        return -1;
-    }
-    cfg.baud = baud;
-    cfg.data_bits = data_bits;
-    cfg.parity = parity;
-    cfg.stop_bits = stop_bits;
-    if (!cj_serial_cfg_ok(&cfg)) {
-        cj_serial_err_set("serial: 串口参数非法（baud>0 / dataBits 5..8 / parity 0|1|2 / stopBits 1|2）");
-        return -1;
-    }
-
-    err[0] = '\0';
-    h = cj_plat_serial_open(path, &cfg, err, (int)sizeof(err));
-    if (h <= 0) {
-        cj_serial_err_set(err[0] ? err : "serial: 平台打开失败");
-        /* 失败也留一行：串口问题多半要拿 stderr 对账（AGENTS §1 的取证口径）*/
-        cj_logf("[cj-bridge] serial open failed: path=%s baud=%d code=%lld (%s)\n",
-                path, baud, h, g_serial_err);
-        return h < 0 ? h : -3;
-    }
-    cj_logf("[cj-bridge] serial open: handle=%lld path=%s baud=%d data=%d parity=%d stop=%d\n",
-            h, path, baud, data_bits, parity, stop_bits);
-    return h;
-}
-
-int cj_bridge_serial_read(long long h, unsigned char *buf, int len, int timeout_ms) {
-    char err[256];
-    int n;
-
-    g_serial_err[0] = '\0';
-    if (h <= 0 || !buf || len <= 0 || len > (1 << 20)) {
-        cj_serial_err_set("serial: read 参数非法（handle>0 / len 1..1048576）");
-        return -1;
-    }
-    if (timeout_ms < 0) timeout_ms = 0;
-    err[0] = '\0';
-    n = cj_plat_serial_read(h, buf, len, timeout_ms, err, (int)sizeof(err));
-    if (n < 0) {
-        cj_serial_err_set(err[0] ? err : "serial: 读失败");
-        cj_logf("[cj-bridge] serial read failed: handle=%lld (%s)\n", h, g_serial_err);
-    }
-    return n;
-}
-
-int cj_bridge_serial_write(long long h, const unsigned char *buf, int len, int timeout_ms) {
-    char err[256];
-    int n;
-
-    g_serial_err[0] = '\0';
-    if (h <= 0 || !buf || len <= 0 || len > (1 << 20)) {
-        cj_serial_err_set("serial: write 参数非法（handle>0 / len 1..1048576）");
-        return -1;
-    }
-    if (timeout_ms < 0) timeout_ms = 0;
-    err[0] = '\0';
-    n = cj_plat_serial_write(h, buf, len, timeout_ms, err, (int)sizeof(err));
-    if (n < 0) {
-        cj_serial_err_set(err[0] ? err : "serial: 写失败");
-        cj_logf("[cj-bridge] serial write failed: handle=%lld (%s)\n", h, g_serial_err);
-    }
-    return n;
-}
-
-int cj_bridge_serial_close(long long h) {
-    char err[256];
-    int rc;
-
-    g_serial_err[0] = '\0';
-    if (h <= 0) {
-        cj_serial_err_set("serial: close 参数非法（handle 必须 >0）");
-        return -1;
-    }
-    err[0] = '\0';
-    rc = cj_plat_serial_close(h, err, (int)sizeof(err));
-    if (rc != 0) {
-        cj_serial_err_set(err[0] ? err : "serial: 关句柄失败");
-        return rc < 0 ? rc : -4;
-    }
-    cj_logf("[cj-bridge] serial close: handle=%lld\n", h);
-    return 0;
-}
-
-const char *cj_bridge_serial_last_error(void) {
-    return g_serial_err;
-}
-
-int cj_bridge_serial_list(char *out, int out_len) {
-    if (!out || out_len <= 0) {
-        cj_serial_err_set("serial: list 参数非法（out 缓冲为空）");
-        return -1;
-    }
-    out[0] = '\0';
-    return cj_plat_serial_list(out, out_len); /* 负码原样交回（-4 = 本平台未实现） */
-}
-
-/* =========================================================================
- *  日志落盘（RFC-003 第 5 期）
- *
- *  为什么在 fd 层接管：单文件产物是 Windows GUI 子系统，双击时 stderr 无处可去，而
- *  诊断输出分布在 core、平台实现与仓颉侧上百处。把 fd 2 指向日志文件，**所有** stderr
- *  写者自动落进同一个 FILE*（顺序天然一致），两端调用点一处都不用改；stdout 不碰。
- *  为什么用 `dup2` 而不是 `freopen`：`freopen` 失败会**把 stderr 关掉**，那就连失败原因
- *  都没地方写了；`dup2` 只在 open 成功后才动 fd 2，失败路径 stderr 完好。
- *  为什么轮转不 rename 打开中的文件：Windows 上 rename 一个还开着的文件会失败。
- *  做法是「先拷贝再截断」——把当前内容拷进 `log.1`，已关闭的档案 `.1 → .2` 平移
- *  （`keep` 决定份数），最后 `_chsize` / `ftruncate` 把当前文件清零。这样无平台分支、
- *  无空设备名，桩自检也能直接测。
- * ========================================================================= */
-
-#define CJ_LOG_PATH_MAX 1024
-#define CJ_LOG_LINE_SLACK 256 /* 每行预留，免得刚好压线时写到 max 之上 */
-
-static char g_log_path[CJ_LOG_PATH_MAX];
-static int g_log_active = 0;
-static long g_log_max = 0; /* 字节；0 = 不轮转（交给外部 logrotate） */
-static long g_log_keep = 0;
-static volatile int g_log_rotating = 0;
-
-/* 轮转互斥：只用编译器内建原子，core 不引平台同步设施（命令 worker 线程也会走到这里）。
-   抢不到就当「这一行不轮转」，不阻塞调用方。 */
-static int cj_log_lock(void) {
-    return __sync_lock_test_and_set(&g_log_rotating, 1) == 0;
-}
-static void cj_log_unlock(void) {
-    __sync_lock_release(&g_log_rotating);
-}
-
-/* 时间戳：localtime 的静态缓冲可能被别的线程踩，取回来立刻拷进本地副本。 */
-static void cj_log_prefix(void) {
-    time_t now = time(NULL);
-    struct tm tmv;
-    const struct tm *p = localtime(&now);
-    char buf[40];
-    size_t n;
-
-    if (!p) return;
-    tmv = *p;
-    n = strftime(buf, sizeof(buf), "[%Y-%m-%d %H:%M:%S] ", &tmv);
-    if (n > 0) fwrite(buf, 1, n, stderr);
-}
-
-/* 真实大小以文件为准（不自己记数：平台与仓颉侧也在往同一个文件写）。
- *
- * 为什么不用 stat()：单文件包（scripts/pack-win-single.sh）里桥由 llvm-mingw(ucrt) 编译、
- * 却由 SDK 自带 mingw 的 CRT 链接——ucrt 把 stat 映射成 stat64i32，而那边的导入库只认
- * _stat，于是链接期报 `undefined symbol: stat64i32`（2026-10-21 实测，只有静态单文件包会炸，
- * 平时的动态构建不受影响）。fopen/fseek/ftell 在 ucrt、msvcrt 与 mingw 三套 CRT 里符号名
- * 一致，绕开这层方言差异；语义相同（文件不存在 → 0）。 */
-static long cj_log_size(void) {
-    FILE *f;
-    long size;
-
-    if (!g_log_path[0]) return 0;
-    fflush(stderr);
-    f = fopen(g_log_path, "rb");
-    if (!f) return 0;
-    if (fseek(f, 0, SEEK_END) != 0) {
-        fclose(f);
-        return 0;
-    }
-    size = ftell(f);
-    fclose(f);
-    return size > 0 ? size : 0;
-}
-
-/* 当前文件整份拷进 `<path>.<n>`（Windows 上不能 rename 打开中的文件，只能拷贝）。 */
-static void cj_log_copy_archive(long n) {
-    FILE *in;
-    FILE *out;
-    char dst[CJ_LOG_PATH_MAX + 24];
-    char buf[8192];
-    size_t got;
-    long written = 0;
-
-    snprintf(dst, sizeof(dst), "%s.%ld", g_log_path, n);
-    in = fopen(g_log_path, "rb");
-    if (!in) return;
-    out = fopen(dst, "wb");
-    if (!out) {
-        fclose(in);
-        return;
-    }
-    while ((got = fread(buf, 1, sizeof(buf), in)) > 0) {
-        if (g_log_max > 0) {
-            /* 档案不超过预算，免得轮转频繁时档案总占用翻倍 */
-            if (written + (long)got > g_log_max) got = (size_t)(g_log_max - written);
-            if ((long)got <= 0) break;
-        }
-        if (fwrite(buf, 1, got, out) != got) break;
-        written += (long)got;
-    }
-    fclose(out);
-    fclose(in);
-}
-
-/* 已关闭的档案平移：`.keep-1 → .keep` … `.1 → .2`（最老那份先删，Windows 上 rename
-   到已存在的文件会失败）。keep ≤ 0 时不动档案，轮转只截断。 */
-static void cj_log_shift(void) {
-    long i;
-    char from[CJ_LOG_PATH_MAX + 24];
-    char to[CJ_LOG_PATH_MAX + 24];
-
-    if (g_log_keep <= 0) return;
-    snprintf(to, sizeof(to), "%s.%ld", g_log_path, g_log_keep);
-    remove(to);
-    for (i = g_log_keep - 1; i >= 1; i--) {
-        snprintf(from, sizeof(from), "%s.%ld", g_log_path, i);
-        snprintf(to, sizeof(to), "%s.%ld", g_log_path, i + 1);
-        rename(from, to); /* 不存在就静默跳过 */
-    }
-}
-
-static int cj_log_rotate(void) {
-    if (!g_log_active) return 0;
-    if (!cj_log_lock()) return 0; /* 别人正在轮转：这一行让给下一轮 */
-    if (g_log_keep > 0) {
-        cj_log_shift();
-        cj_log_copy_archive(1);
-    }
-    fflush(stderr);
-    if (cj_log_truncate(cj_log_fileno(stderr)) != 0) {
-        /* 截断失败（有的文件系统不给改长度）：如实说一句，别假装轮转过 */
-        fprintf(stderr, "[cj-bridge] log rotate failed: truncate errno=%d\n", errno);
-    }
-    fprintf(stderr, "[cj-bridge] log rotated: keep=%ld archive=%s.1\n", g_log_keep, g_log_path);
-    cj_log_unlock();
-    return 1;
-}
-
-void cj_core_logf(const char *fmt, ...) {
-    va_list ap;
-
-    if (g_log_active) {
-        if (g_log_max > 0 && cj_log_size() + CJ_LOG_LINE_SLACK >= g_log_max) cj_log_rotate();
-        cj_log_prefix();
-    }
-    va_start(ap, fmt);
-    vfprintf(stderr, fmt, ap);
-    va_end(ap);
-    if (g_log_active) fflush(stderr); /* 每行即时落盘：进程被强杀也不丢 */
-}
-
-/* 父目录不在就逐个建出来：默认目录（`~/.local/state/cj-tauri/` 这类）常常还不存在。
-   建目录失败不在这里报——紧接着的 open 会带 errno 如实说，少一条重复的日志。 */
-static void cj_log_ensure_dirs(const char *path) {
-    char buf[CJ_LOG_PATH_MAX];
-    size_t i;
-    size_t n = strlen(path);
-
-    if (n == 0 || n >= sizeof(buf)) return;
-    memcpy(buf, path, n + 1);
-    for (i = 1; i < n; i++) {
-        char sep;
-        if (buf[i] != '/' && buf[i] != '\\') continue;
-        sep = buf[i];
-        buf[i] = '\0';
-        /* 跳过盘符（`C:`）与别名的根：它们建不了也不需要建 */
-        if (!(i == 2 && buf[1] == ':')) cj_log_mkdir(buf);
-        buf[i] = sep;
-    }
-}
-
-CJ_BRIDGE_API int cj_bridge_set_log_file(const char *path, int max_kb, int keep) {
-    int fd;
-
-    if (g_log_active) {
-        fprintf(stderr, "[cj-bridge] log file already active: %s (restart to change)\n", g_log_path);
-        return 0;
-    }
-    if (!path || !path[0]) {
-        fprintf(stderr, "[cj-bridge] log file refused: empty path\n");
-        return 0;
-    }
-    if (strlen(path) >= CJ_LOG_PATH_MAX) {
-        fprintf(stderr, "[cj-bridge] log file refused: path too long\n");
-        return 0;
-    }
-    /* 先 open 成功再动 fd 2：失败时 stderr 完好，失败原因才有人看得见 */
-    fd = cj_log_open(path, CJ_LOG_OFLAGS, CJ_LOG_OMODE);
-    if (fd < 0 && errno == ENOENT) {
-        /* 只有「父目录根本不存在」才顺手建出来（默认目录 `~/.local/state/cj-tauri` 常常还不存在）。
-           别的 errno（没权限、路径中间穿了普通文件、名字太长）一律原样失败——
-           照着一个开不了的路径去建目录，等于把一次手滑变成磁盘上的垃圾。 */
-        cj_log_ensure_dirs(path);
-        fd = cj_log_open(path, CJ_LOG_OFLAGS, CJ_LOG_OMODE);
-    }
-    if (fd < 0) {
-        fprintf(stderr, "[cj-bridge] log file open failed: %s (errno=%d)\n", path, errno);
-        return 0;
-    }
-    if (fd != 2) {
-        if (cj_log_dup2(fd, 2) < 0) {
-            fprintf(stderr, "[cj-bridge] log file open failed: %s (dup2 errno=%d)\n", path, errno);
-            cj_log_close(fd);
-            return 0;
-        }
-        cj_log_close(fd);
-    }
-    snprintf(g_log_path, sizeof(g_log_path), "%s", path);
-    g_log_max = max_kb > 0 ? (long)max_kb * 1024L : 0;
-    g_log_keep = keep > 0 ? (long)keep : 0;
-    g_log_active = 1;
-    /* 第一行就落在新文件里：开了、开在哪、预算多少，都能自查 */
-    cj_logf("[cj-bridge] log file: %s (max=%ldKB keep=%ld)\n", g_log_path, g_log_max / 1024, g_log_keep);
-    return 1;
-}
-
-CJ_BRIDGE_API const char *cj_bridge_log_file(void) {
-    return g_log_active ? g_log_path : "";
-}
-
-CJ_BRIDGE_API int cj_bridge_log_write(const char *line) {
-    if (!line) return -1;
-    cj_logf("%s\n", line);
-    return 0;
-}
-
-/* =========================================================================
- *  静默子进程（为什么下沉到 C 桥见头文件同名段落）
- *
- *  core 只做参数校验、错误出口与日志；创建 / 终止 / 探活是平台原语。这样两平台导出名与
- *  签名逐字一致，仓颉侧没有平台分叉的调用点（AGENTS §2 的分工铁律）。
- * ========================================================================= */
-
-CJ_BRIDGE_API long long cj_bridge_spawn_hidden(const char *exe, const char *args) {
-    char err[512];
-    long long pid;
-
-    err[0] = '\0';
-    if (!exe || !*exe) {
-        cj_logf("[cj-bridge] spawn hidden: 程序路径为空\n");
-        return 0;
-    }
-    pid = cj_plat_spawn_hidden(exe, args ? args : "", err, (int)sizeof(err));
-    if (pid <= 0) {
-        cj_logf("[cj-bridge] spawn hidden 失败（%s）：%s\n", exe,
-                err[0] ? err : "平台没有给出原因");
-        return 0;
-    }
-    cj_logf("[cj-bridge] spawn hidden: %s -> pid=%lld\n", exe, pid);
-    return pid;
-}
-
-CJ_BRIDGE_API int cj_bridge_kill_pid(long long pid) {
-    if (pid <= 0) {
-        cj_logf("[cj-bridge] kill pid: 非法 pid=%lld\n", pid);
-        return 0;
-    }
-    return cj_plat_kill_pid(pid);
-}
-
-CJ_BRIDGE_API int cj_bridge_pid_alive(long long pid) {
-    if (pid <= 0) return 0;
-    return cj_plat_pid_alive(pid);
-}
-
-/* 内嵌资源释放：core 只做参数校验与错误出口，取资源写盘是平台原语
-   （为什么用字符串资源名、为什么幂等，见头文件同名段落与平台实现）。 */
-CJ_BRIDGE_API int cj_bridge_extract_assets(const char *dir) {
-    char err[512];
-    int n;
-
-    err[0] = '\0';
-    if (!dir || !*dir) {
-        cj_logf("[cj-bridge] extract assets: 目录为空\n");
-        return -1;
-    }
-    n = cj_plat_extract_assets(dir, err, (int)sizeof(err));
-    if (n < 0) {
-        cj_logf("[cj-bridge] extract assets 失败（%s）：%s\n", dir, err[0] ? err : "平台没有给出原因");
-        return -1;
-    }
-    if (n > 0) cj_logf("[cj-bridge] extract assets: %d 个文件就绪（%s）\n", n, dir);
-    return n;
-}
-
-/* 预加载动态库：core 只做参数校验与错误出口，LoadLibrary/dlopen 是平台原语。
-   为什么要它见头文件同名段落（2026-10-21：单文件包在别人的机器上连明文 ws:// 都挂在
-   `Can not load openssl library or function RAND_bytes.`——运行时的随机数默认走 OpenSSL，
-   而它按裸名找 DLL，只有开发机的 PATH 恰好有 Git 自带那份）。 */
-CJ_BRIDGE_API int cj_bridge_preload_library(const char *path) {
-    char err[512];
-    int ok;
-
-    err[0] = '\0';
-    if (!path || !*path) {
-        cj_logf("[cj-bridge] preload library: 路径为空\n");
-        return 0;
-    }
-    ok = cj_plat_preload_library(path, err, (int)sizeof(err));
-    if (ok <= 0) {
-        cj_logf("[cj-bridge] preload 失败（%s）：%s\n", path, err[0] ? err : "平台没有给出原因");
-        return 0;
-    }
-    cj_logf("[cj-bridge] preload: %s\n", path);
-    return 1;
-}
-
+/*
+ * cj-tauri C 桥公共核心（批次 1）：句柄化的宿主状态 + 平台无关逻辑
+ *
+ * 契约见 native/bridge_core.h。本文件只放「两平台逐字相同」的东西：
+ *   回投队列与批处理（含单条快路径）、对话框单槽状态机、窗口配置与预执行脚本存储、
+ *   生命周期标志、以及**全部 cj_bridge_* 导出**（单一来源，两平台导出一致由此保证）。
+ * 任何平台能力都经 cj_plat_*，本文件不 include 任何平台头。
+ */
+/* 日志落盘要用 ftruncate / fileno 这些 POSIX 名，而桩自检是按 `-std=c99` 编译的，
+   该标准档位下它们默认被隐藏（表象是 implicit declaration 警告）。特性宏必须写在
+   任何 include 之前，否则不生效。 */
+#define _POSIX_C_SOURCE 200809L
+
+#include "bridge_core.h"
+
+/* 日志落盘要用到的 CRT 原语（RFC-003 第 5 期）。这是**编译器运行库**的名字差异，
+   不是平台实现差异——core 依旧不碰 pthread / windows.h / gtk 这些宿主头。 */
+#include <stdarg.h>
+#include <errno.h>
+#include <time.h>
+#include <sys/stat.h>
+#include <fcntl.h>
+#if defined(_WIN32)
+#include <io.h>
+#include <direct.h>
+#define cj_log_open _open
+#define cj_log_dup2 _dup2
+#define cj_log_close _close
+#define cj_log_fileno _fileno
+#define cj_log_mkdir(path) _mkdir(path)
+#define cj_log_truncate(fd) _chsize((fd), 0)
+#define CJ_LOG_OFLAGS (_O_WRONLY | _O_CREAT | _O_APPEND)
+#define CJ_LOG_OMODE (_S_IREAD | _S_IWRITE)
+#else
+#include <unistd.h>
+#define cj_log_open open
+#define cj_log_dup2 dup2
+#define cj_log_close close
+#define cj_log_fileno fileno
+#define cj_log_mkdir(path) mkdir((path), 0755)
+#define cj_log_truncate(fd) ftruncate((fd), 0)
+#define CJ_LOG_OFLAGS (O_WRONLY | O_CREAT | O_APPEND)
+#define CJ_LOG_OMODE 0644
+#endif
+
+/* ===== 内部小工具 ===== */
+
+static char *cj_strdup(const char *s) {
+    size_t n;
+    char *p;
+    if (!s) return NULL;
+    n = strlen(s) + 1;
+    p = (char *)malloc(n);
+    if (!p) return NULL;
+    memcpy(p, s, n);
+    return p;
+}
+
+/* 回投队列整体释放（宿主销毁时兜底） */
+static void cj_js_queue_free(cj_host *h) {
+    js_node *n = h->js_head;
+    while (n) {
+        js_node *next = n->next;
+        free(n->js);
+        free(n);
+        n = next;
+    }
+    h->js_head = NULL;
+    h->js_tail = NULL;
+}
+
+/* ===== 建 / 释放宿主 ===== */
+
+cj_host *cj_bridge_create(void) {
+    cj_host *h = (cj_host *)calloc(1, sizeof(cj_host));
+    if (!h) {
+        cj_logf("[cj-bridge] create host failed: out of memory\n");
+        return NULL;
+    }
+    /* 默认与两平台原先的静态初值一致 */
+    h->win_w = 900;
+    h->win_h = 640;
+    h->devtools = 1;
+    h->win_visible = 1; /* 默认显示：没碰窗口可见性的应用行为不变 */
+    h->js_lock = cj_plat_sync_create();
+    h->dlg_lock = cj_plat_sync_create();
+    h->clip_lock = cj_plat_sync_create();
+    if (!h->js_lock || !h->dlg_lock || !h->clip_lock) {
+        if (h->js_lock) cj_plat_sync_destroy(h->js_lock);
+        if (h->dlg_lock) cj_plat_sync_destroy(h->dlg_lock);
+        if (h->clip_lock) cj_plat_sync_destroy(h->clip_lock);
+        free(h);
+        cj_logf("[cj-bridge] create host failed: sync init failed\n");
+        return NULL;
+    }
+    cj_logf("[cj-bridge] host created: %p\n", (void *)h);
+    return h;
+}
+
+void cj_bridge_destroy(cj_host *h) {
+    int i;
+    if (!h) return;
+    /* 平台资源先走：COM 环境引用 / 模块句柄等（幂等）。返回 0＝宿主线程还在收尾，
+       它可能仍在用 h（GTK/WebView2 回调的 user_data 就是它）——这时连句柄一起留着不释放。 */
+    if (!cj_plat_fini(h)) {
+        cj_logf("[cj-bridge] destroy: host thread still running, handle kept\n");
+        return;
+    }
+    if (h->js_lock) cj_plat_sync_destroy(h->js_lock);
+    if (h->dlg_lock) cj_plat_sync_destroy(h->dlg_lock);
+    if (h->clip_lock) cj_plat_sync_destroy(h->clip_lock);
+    cj_js_queue_free(h);
+    /* dlg_cur 此时应为空：窗口销毁路径已作废并交了槽位；故意不碰，免得与等待方抢 free */
+    free(h->win_title);
+    free(h->win_icon);
+    free(h->pending_menu_text);
+    free(h->pending_hotkeys);
+    free(h->pending_tray);
+    for (i = 0; i < h->init_script_count; i++) {
+        free(h->init_scripts[i]);
+    }
+    free(h->init_scripts);
+    free(h->pending_html);
+    free(h->pending_url);
+    cj_logf("[cj-bridge] host destroyed: %p\n", (void *)h);
+    free(h);
+}
+
+void cj_bridge_init(cj_host *h, cj_on_message_fn m, cj_on_destroy_fn d) {
+    if (!h) return;
+    h->on_message = m;
+    h->on_destroy = d;
+    cj_plat_init(h); /* 平台一次性初始化（Windows 在这里装 COM vtbl 并打 init 日志） */
+    /* 能力位：平台给静态事实（有没有菜单 / 托盘 / 拖放），core 只缓存——仓颉侧 system:host 如实上报 */
+    h->capabilities = cj_plat_host_capabilities(h);
+    cj_logf("[cj-bridge] host capabilities: 0x%x (menu=%d tray=%d dragDrop=%d notify=%d hotkey=%d)\n",
+            (unsigned)h->capabilities,
+            (h->capabilities & CJ_CAP_MENU) ? 1 : 0,
+            (h->capabilities & CJ_CAP_TRAY) ? 1 : 0,
+            (h->capabilities & CJ_CAP_DRAG_DROP) ? 1 : 0,
+            (h->capabilities & CJ_CAP_NOTIFICATION) ? 1 : 0,
+            (h->capabilities & CJ_CAP_HOTKEY) ? 1 : 0);
+}
+
+/* ===== 窗口配置 / 预执行脚本（必须在 cj_bridge_start 之前注入）===== */
+
+void cj_bridge_set_window(cj_host *h, const char *title, int width, int height) {
+    if (!h) return;
+    cj_logf("[cj-bridge] set window: title=%s size=%dx%d\n",
+            title ? title : "(default)", width, height);
+    free(h->win_title);
+    h->win_title = NULL;
+    if (title) {
+        h->win_title = cj_strdup(title);
+    }
+    if (width > 0) h->win_w = width;
+    if (height > 0) h->win_h = height;
+}
+
+void cj_bridge_set_icon(cj_host *h, const char *path) {
+    if (!h) return;
+    cj_logf("[cj-bridge] set icon: path=%s\n", (path && path[0]) ? path : "(default)");
+    free(h->win_icon);
+    h->win_icon = NULL;
+    if (path && path[0]) {
+        h->win_icon = cj_strdup(path);
+    }
+}
+
+void cj_bridge_set_devtools(cj_host *h, int enabled) {
+    if (!h) return;
+    h->devtools = enabled ? 1 : 0;
+    cj_logf("[cj-bridge] devtools %s\n", h->devtools ? "enabled" : "disabled");
+}
+
+void cj_bridge_add_init_script(cj_host *h, const char *js) {
+    if (!h || !js || !js[0]) {
+        return;
+    }
+    if (h->init_script_count == h->init_script_cap) {
+        int cap = h->init_script_cap ? h->init_script_cap * 2 : 4;
+        char **grown = (char **)realloc(h->init_scripts, (size_t)cap * sizeof(char *));
+        if (!grown) {
+            cj_logf("[cj-bridge] add init script failed: out of memory\n");
+            return;
+        }
+        h->init_scripts = grown;
+        h->init_script_cap = cap;
+    }
+    h->init_scripts[h->init_script_count] = cj_strdup(js);
+    if (!h->init_scripts[h->init_script_count]) {
+        cj_logf("[cj-bridge] add init script failed: out of memory\n");
+        return;
+    }
+    h->init_script_count++;
+    cj_logf("[cj-bridge] init script queued: %d bytes (total %d)\n",
+            (int)strlen(js), h->init_script_count);
+}
+
+/* ===== 菜单栏（RFC-002；v1 只做菜单栏，托盘 / 拖放在后续档期）===== */
+
+void cj_bridge_set_menu(cj_host *h, const char *wire) {
+    int rows = 0;
+    const char *p;
+    if (!h || !wire) return;
+    for (p = wire; *p; p++) {
+        if (*p == '\n') rows++;
+    }
+    cj_logf("[cj-bridge] set menu: %d bytes, %d row(s)\n", (int)strlen(wire), rows);
+    free(h->pending_menu_text);
+    h->pending_menu_text = cj_strdup(wire);
+    /* 两头都要能用：未就绪时平台只记下（建窗时读 h->pending_menu_text），就绪后平台投到 UI 线程重建 */
+    cj_plat_set_menu(h, h->pending_menu_text ? h->pending_menu_text : "");
+}
+
+int cj_bridge_set_titlebar_subtitle(cj_host *h, const char *text) {
+    int rc;
+
+    if (!h || !text) return -1;
+    if (strlen(text) > 1024) return -1;
+    rc = cj_plat_set_titlebar_subtitle(h, text);
+    /* 失败必须留痕：页面上的状态行不出现时，这一行是唯一能区分
+       「应用没调」与「平台没这块」的凭证 */
+    if (rc != 0) {
+        cj_logf("[cj-bridge] titlebar subtitle rejected: rc=%d text=\"%s\"\n", rc, text);
+    }
+    return rc;
+}
+
+void cj_bridge_set_menu_item_state(cj_host *h, const char *id, int enabled, int checked) {
+    if (!h || !id || !id[0]) return;
+    cj_logf("[cj-bridge] set menu item: id=%s enabled=%d checked=%d\n",
+            id, enabled ? 1 : 0, checked ? 1 : 0);
+    cj_plat_menu_item_state(h, id, enabled ? 1 : 0, checked ? 1 : 0);
+}
+
+/* ===== 拖放（RFC-002 §5；v1 载荷只有文件路径）===== */
+
+void cj_bridge_set_drag_drop(cj_host *h, int enabled, int files) {
+    if (!h) return;
+    cj_logf("[cj-bridge] set drag drop: enabled=%d files=%d\n",
+            enabled ? 1 : 0, files ? 1 : 0);
+    h->pending_drop_enabled = enabled ? 1 : 0;
+    h->pending_drop_files = files ? 1 : 0;
+    /* 两头都能用：未就绪时平台只记（本函数已写进 pending 字段，建 view 时读）；
+       就绪后平台投 UI 线程重挂 drag dest */
+    cj_plat_set_drag_drop(h, enabled ? 1 : 0, files ? 1 : 0);
+}
+
+/* ===== 全局快捷键（RFC-003 第 5 期首个落地项）===== */
+
+void cj_bridge_set_global_hotkeys(cj_host *h, const char *wire) {
+    if (!h) return;
+    cj_logf("[cj-bridge] set global hotkeys: %s\n",
+            (wire && wire[0]) ? wire : "(none)");
+    free(h->pending_hotkeys);
+    h->pending_hotkeys = cj_strdup(wire ? wire : "");
+    /* 两头都能用：未就绪时平台只记（建宿主线程后读 h->pending_hotkeys）；
+       就绪后整表替换（ungrab 旧表再 grab 新表）。平台不支持时在 cj_plat_* 里打一行如实说明。 */
+    cj_plat_set_global_hotkeys(h, h->pending_hotkeys ? h->pending_hotkeys : "");
+}
+
+/* ===== 托盘（RFC-002 §7.C）===== */
+
+void cj_bridge_set_tray(cj_host *h, const char *wire) {
+    if (!h) return;
+    cj_logf("[cj-bridge] set tray: %d bytes\n",
+            (int)(wire ? strlen(wire) : 0));
+    free(h->pending_tray);
+    h->pending_tray = cj_strdup(wire ? wire : "");
+    /* 两头都能用：未就绪时平台只记（宿主线程装配时读 h->pending_tray）；
+       就绪后投 UI 线程重建。平台没编托盘支持时在 cj_plat_* 里打一行如实说明。 */
+    cj_plat_set_tray(h, h->pending_tray ? h->pending_tray : "");
+}
+
+/* ===== 窗口可见性 / 最小化到托盘（RFC-003 第 5 期余项）===== */
+
+void cj_bridge_set_window_visible(cj_host *h, int visible) {
+    if (!h) return;
+    cj_logf("[cj-bridge] set window visible: %d\n", visible ? 1 : 0);
+    h->win_visible = visible ? 1 : 0;
+    /* 两头都能用：**未就绪时到此为止**——平台建窗时读 h->win_visible 定稿（建窗那一刻就定下来，
+       比「先显示再藏起来」少一次闪烁）；就绪后平台投 UI 线程执行。 */
+    if (h->ready) {
+        cj_plat_set_window_visible(h, h->win_visible);
+    }
+}
+
+void cj_bridge_set_minimize_to_tray(cj_host *h, int enabled) {
+    if (!h) return;
+    h->minimize_to_tray = enabled ? 1 : 0;
+    cj_logf("[cj-bridge] set minimize to tray: %d\n", h->minimize_to_tray);
+    /* 这里只记 + 转给平台，**不**在此刻查能力位：能力位（cj_plat_init）与「应用有没有真的 setTray」
+       的先后顺序不稳定，提前拒绝会误伤。策略在**真要最小化那一刻**由平台复核托盘是否装上了。 */
+    cj_plat_set_minimize_to_tray(h, h->minimize_to_tray);
+}
+
+void cj_bridge_set_owner_window(cj_host *h, cj_host *owner) {
+    if (!h) return;
+    h->owner = owner;
+    cj_logf("[cj-bridge] set owner window: %s\n", owner ? "yes" : "none");
+    /* 与 set_window_visible 同形：未就绪时到此为止，平台建窗时读 h->owner 定稿
+       （建窗那一刻就挂好，不会先占一个任务栏按钮再消失）。 */
+    if (h->ready) {
+        cj_plat_set_owner_window(h, owner);
+    }
+}
+
+/* ===== 同窗内嵌视图（PLT-006 真标签页）=====
+   core 只做参数校验与留痕，句柄与生命周期全在平台（它才认得自己的 controller / widget）。 */
+
+long long cj_bridge_view_create(cj_host *h, const char *url, int x, int y, int w, int hgt) {
+    long long view;
+
+    if (!h || !url || !url[0]) return 0;
+    if (w <= 0 || hgt <= 0) return 0;
+    if (strlen(url) > 2048) return 0;
+    view = cj_plat_view_create(h, url, x, y, w, hgt);
+    /* 成功失败都留痕：应用侧只会看到「点了没反应」，这一行是唯一能区分
+       「平台没这块」与「环境复用 / 宿主未就绪」的凭证 */
+    cj_logf("[cj-bridge] view create: rect=%d,%d %dx%d url=%s -> %lld\n",
+            x, y, w, hgt, url, view);
+    return view;
+}
+
+void cj_bridge_view_set_visible(cj_host *h, long long view, int visible) {
+    if (!h || view <= 0) return;
+    cj_logf("[cj-bridge] view visible: id=%lld visible=%d\n", view, visible ? 1 : 0);
+    cj_plat_view_set_visible(h, view, visible ? 1 : 0);
+}
+
+/* 高频调用（页面 resize / 布局变化都要同步），**不打日志**：一行一个矩形会把桥的日志冲掉，
+   真出问题看的是「切换后有没有显示」而不是矩形的每一次微调。 */
+void cj_bridge_view_set_bounds(cj_host *h, long long view, int x, int y, int w, int hgt) {
+    if (!h || view <= 0) return;
+    if (w <= 0 || hgt <= 0) return;
+    cj_plat_view_set_bounds(h, view, x, y, w, hgt);
+}
+
+void cj_bridge_view_navigate(cj_host *h, long long view, const char *url) {
+    if (!h || view <= 0 || !url || !url[0]) return;
+    if (strlen(url) > 2048) return;
+    cj_logf("[cj-bridge] view navigate: id=%lld url=%s\n", view, url);
+    cj_plat_view_navigate(h, view, url);
+}
+
+void cj_bridge_view_destroy(cj_host *h, long long view) {
+    if (!h || view <= 0) return;
+    cj_logf("[cj-bridge] view destroy: id=%lld\n", view);
+    cj_plat_view_destroy(h, view);
+}
+
+/* ===== 运行期操作（投递细节留给平台：各平台的原生时机与日志口径不同）===== */
+
+void cj_bridge_start(cj_host *h, const char *html) {
+    if (!h) return;
+    if (html && html[0]) { /* 空串表示「页面由 cj_bridge_load_url 指定」 */
+        free(h->pending_html);
+        h->pending_html = cj_strdup(html);
+    }
+    cj_plat_start(h);
+}
+
+void cj_bridge_load_url(cj_host *h, const char *url) {
+    if (!h || !url || !url[0]) return;
+    free(h->pending_url);
+    h->pending_url = cj_strdup(url);
+    cj_plat_load_url(h, url);
+}
+
+void cj_bridge_reload(cj_host *h) {
+    if (!h) return;
+    cj_plat_reload(h);
+}
+
+void cj_bridge_open_devtools(cj_host *h) {
+    if (!h) return;
+    cj_plat_open_devtools(h);
+}
+
+void cj_bridge_quit(cj_host *h) {
+    if (!h) return;
+    h->should_quit = 1;
+    /* 平台走与「用户关窗」同一条销毁路径，onDestroy 因此恰好触发一次（批次 1 验收项） */
+    cj_plat_quit(h);
+}
+
+/* ===== 原生 → JS：入队（执行在 UI 线程的 cj_core_flush_js 里）===== */
+
+void cj_bridge_run_js(cj_host *h, const char *js) {
+    js_node *node;
+    int was_empty;
+    if (!h || !js) return;
+    node = (js_node *)calloc(1, sizeof(js_node));
+    if (!node) return;
+    node->js = cj_strdup(js);
+    if (!node->js) {
+        free(node);
+        return;
+    }
+    if (!h->js_lock) {
+        /* 未 init 时直接丢弃，避免未初始化锁 */
+        free(node->js);
+        free(node);
+        return;
+    }
+    cj_plat_sync_lock(h->js_lock);
+    if (h->js_tail) {
+        h->js_tail->next = node;
+    } else {
+        h->js_head = node;
+    }
+    h->js_tail = node;
+    was_empty = (h->js_head == node); /* 队列由空转非空：需要唤醒 UI 线程 */
+    cj_plat_sync_unlock(h->js_lock);
+    if (was_empty) {
+        cj_plat_wake_ui(h); /* 平台自己判断窗口是否已就绪（未就绪就攒着） */
+    }
+}
+
+int cj_bridge_is_ready(cj_host *h) {
+    return h ? (int)h->ready : 0;
+}
+
+int cj_bridge_should_quit(cj_host *h) {
+    return h ? (int)h->should_quit : 0;
+}
+
+/* ===== core 提供给平台的状态迁移 ===== */
+
+void cj_core_set_ready(cj_host *h) {
+    if (h) h->ready = 1;
+}
+
+void cj_core_window_destroyed(cj_host *h) {
+    if (!h) return;
+    h->window_gone = 1;
+    h->should_quit = 1;
+    /* 每个宿主恰好通知一次：无论是用户关窗还是 cj_bridge_quit，都汇到这条路径 */
+    if (!h->destroy_notified) {
+        h->destroy_notified = 1;
+        if (h->on_destroy) {
+            h->on_destroy(h); /* 带上句柄：仓颉侧据此认领「是哪扇窗没了」（多窗口不许再走静态槽） */
+        }
+    }
+    /* 有对话框开着时先作废并唤醒等待方：事件循环退出后挂起的回调不再执行，等待方会永远挂住 */
+    cj_core_dialog_abort(h);
+    /* 剪贴板同理：投递进 UI 线程的读写不会再被执行 */
+    cj_core_clipboard_abort(h);
+}
+
+/* ===== 剪贴板（plugin_clipboard）：单槽 + UI 线程投递 ===== */
+
+/* UI 线程在 GTK 线程上执行真正的剪贴板调用（经平台原语），结果放回槽位并唤醒等待方 */
+/* 返回 1 = 成功（含读出空），0 = 平台失败。UI 线程直行路径靠它取结果。 */
+int cj_core_clipboard_tick(cj_host *h, int is_write, char *text) {
+    int ok = 0;
+    char *readback = NULL;
+
+    if (!h) {
+        free(text);
+        return 0;
+    }
+    if (is_write) {
+        ok = (cj_plat_clipboard_write_text(h, text ? text : "", NULL, 0) == 0);
+        if (ok) {
+            cj_logf("[cj-bridge] clipboard write: %d bytes\n",
+                    text ? (int)strlen(text) : 0);
+        } else {
+            cj_logf("[cj-bridge] clipboard write failed\n");
+        }
+        free(text);
+    } else {
+        readback = cj_plat_clipboard_read_text(h, NULL, 0);
+        ok = 1; /* 读失败按「空结果」处理：NULL 是合法回值（剪贴板为空/非文本）*/
+        cj_logf("[cj-bridge] clipboard read: %s\n",
+                readback ? "got text" : "empty");
+    }
+
+    cj_plat_sync_lock(h->clip_lock);
+    h->clip_ok = ok;
+    h->clip_text = readback;
+    h->clip_ready = 1;
+    h->clip_busy = 0;
+    cj_plat_sync_signal(h->clip_lock);
+    cj_plat_sync_unlock(h->clip_lock);
+    return ok;
+}
+
+/* 作废进行中的剪贴板请求并唤醒等待方（ok=0；等待方知道宿主已不在，不再碰槽位）*/
+void cj_core_clipboard_abort(cj_host *h) {
+    if (!h || !h->clip_lock) return;
+    cj_plat_sync_lock(h->clip_lock);
+    if (h->clip_busy && !h->clip_ready) {
+        h->clip_ok = 0;
+        h->clip_text = NULL;
+        h->clip_ready = 1;
+        h->clip_busy = 0;
+        cj_plat_sync_signal(h->clip_lock);
+    }
+    cj_plat_sync_unlock(h->clip_lock);
+}
+
+/* UI 线程投递的载荷：一个指针 + 一个标志 */
+typedef struct clip_call {
+    cj_host *h;
+    int is_write;
+    char *text;
+} clip_call;
+
+static void clip_idle(void *d) {
+    clip_call *c = (clip_call *)d;
+    if (c) {
+        cj_core_clipboard_tick(c->h, c->is_write, c->text);
+        free(c);
+    }
+}
+
+static int clipboard_execute(cj_host *h, int is_write, char *text, char **out_text) {
+    if (!h || !h->clip_lock) {
+        free(text);
+        return -1;
+    }
+    if (h->window_gone) {
+        free(text);
+        return -3; /* 宿主已销毁：不再往已退出的 GTK 循环投东西 */
+    }
+    cj_plat_sync_lock(h->clip_lock);
+    if (h->clip_busy) {
+        cj_plat_sync_unlock(h->clip_lock);
+        free(text);
+        return -3; /* 剪贴板是单槽：同时只允许一次（并发写抢剪贴板本身就没有意义）*/
+    }
+    h->clip_busy = 1;
+    h->clip_ready = 0;
+    h->clip_ok = 0;
+    h->clip_text = NULL;
+    cj_plat_sync_unlock(h->clip_lock);
+
+    if (cj_plat_is_ui_thread(h)) {
+        /* 已在 UI 线程（对话框同类）：直接做，不投递——投递 + 等待会自锁（AGENTS §4）*/
+        int ok = cj_core_clipboard_tick(h, is_write, text);
+        if (!ok) {
+            return -3;
+        }
+        if (out_text) {
+            *out_text = h->clip_text; /* 所有权交调用方（tick 已把槽位清待取）*/
+            h->clip_text = NULL;
+        }
+    } else {
+        /* 投递的载荷必须堆分配：UI 线程处理完由 clip_idle free（通知路径同款）。
+           早前这里是**栈上**结构体 + clip_idle 里 free，实机当场 munmap_chunk 崩掉
+           （AGENTS §4：跨线程投递的载荷谁 post 谁分配，UI 线程释放）。 */
+        clip_call *call = (clip_call *)malloc(sizeof(clip_call));
+        if (!call) {
+            free(text);
+            cj_core_clipboard_abort(h);
+            return -3;
+        }
+        call->h = h;
+        call->is_write = is_write;
+        call->text = text;
+        if (!cj_plat_post_ui(h, clip_idle, call)) {
+            /* 没投出去 = 回调永不执行：载荷与 text 仍归本函数，就地回收 */
+            free(call);
+            free(text);
+            cj_core_clipboard_abort(h);
+            return -3;
+        }
+        /* 等结果：窗口先关的话，cj_core_window_destroyed 会作废并唤醒（ok=0）*/
+        cj_plat_sync_lock(h->clip_lock);
+        cj_plat_sync_wait(h->clip_lock, &h->clip_ready);
+        if (out_text && h->clip_ok) {
+            *out_text = h->clip_text; /* 所有权交调用方 */
+            h->clip_text = NULL;
+        }
+        cj_plat_sync_unlock(h->clip_lock);
+        if (!h->clip_ok) {
+            return -3;
+        }
+    }
+    return 0;
+}
+
+int cj_bridge_clipboard_write_text(cj_host *h, const char *text) {
+    char *copy = NULL;
+    size_t len;
+    int rc;
+
+    if (!text) {
+        return -1;
+    }
+    len = strlen(text);
+    if (len >= (8u << 20)) {
+        cj_logf("[cj-bridge] clipboard write rejected: %zu bytes exceeds 8 MiB limit\n", len);
+        return -1;
+    }
+    copy = (char *)malloc(len + 1);
+    if (!copy) {
+        return -3;
+    }
+    memcpy(copy, text, len + 1);
+    rc = clipboard_execute(h, 1, copy, NULL);
+    if (rc == 0) {
+        /* 成功行在 tick 里打（字节口径以投递载荷为准）；这里只补参数被拒的取证 */
+    }
+    return rc;
+}
+
+char *cj_bridge_clipboard_read_text(cj_host *h) {
+    char *out = NULL;
+    int rc;
+
+    rc = clipboard_execute(h, 0, NULL, &out);
+    if (rc == 0) {
+        return out; /* 可能为 NULL = 剪贴板为空 / 非文本 */
+    }
+    return NULL;
+}
+
+void cj_bridge_clipboard_free(char *s) {
+    free(s);
+}
+
+/* ===== 通知（plugin_notification）：校验 + 发后即忘 ===== */
+
+/* UI 线程投递的载荷（谁 post 谁分配，UI 线程处理完释放）*/
+typedef struct note_call {
+    cj_host *h;
+    char *title;
+    char *body;
+} note_call;
+
+static void note_idle(void *d) {
+    note_call *c = (note_call *)d;
+    if (c) {
+        int ok = cj_plat_notification_notify(c->h, c->title, c->body, NULL, 0) == 0;
+        cj_logf("[cj-bridge] notification: title=%d bytes -> %s\n",
+                c->title ? (int)strlen(c->title) : 0, ok ? "sent" : "failed");
+        free(c->title);
+        free(c->body);
+        free(c);
+    }
+}
+
+int cj_bridge_notification_notify(cj_host *h, const char *title, const char *body) {
+    char *t_copy = NULL;
+    char *b_copy = NULL;
+    size_t t_len, b_len;
+
+    if (!h || !title || !title[0]) {
+        return -1;
+    }
+    t_len = strlen(title);
+    b_len = body ? strlen(body) : 0;
+    if (t_len > 256 || b_len > (8u << 10)) {
+        cj_logf("[cj-bridge] notification rejected: title=%zu (<=256) body=%zu (<=8192)\n",
+                t_len, b_len);
+        return -1;
+    }
+    if (h->window_gone) {
+        return -3;
+    }
+    /* 平台没声明通知能力（如 Windows 桩阶段）就当场拒绝，别走「发后即忘」：
+       那条路径投递成功就返回 0，UI 线程实际的失败没人带回命令层——桩会被读成成功。 */
+    if (!(h->capabilities & CJ_CAP_NOTIFICATION)) {
+        cj_logf("[cj-bridge] notification rejected: platform does not declare CJ_CAP_NOTIFICATION\n");
+        return -4;
+    }
+    t_copy = (char *)malloc(t_len + 1);
+    if (t_copy) {
+        memcpy(t_copy, title, t_len + 1);
+    }
+    if (body && b_len) {
+        b_copy = (char *)malloc(b_len + 1);
+        if (b_copy) {
+            memcpy(b_copy, body, b_len + 1);
+        }
+    }
+    if (!t_copy || (body && b_len && !b_copy)) {
+        free(t_copy);
+        free(b_copy);
+        return -3;
+    }
+    if (cj_plat_is_ui_thread(h)) {
+        int ok = cj_plat_notification_notify(h, t_copy, b_copy, NULL, 0) == 0;
+        cj_logf("[cj-bridge] notification: title=%d bytes -> %s\n",
+                (int)t_len, ok ? "sent" : "failed");
+        free(t_copy);
+        free(b_copy);
+        return ok ? 0 : -3;
+    }
+    /* 发后即忘：投递后立即返回。载荷归 UI 线程释放（不等待、不占剪贴板那套同步槽）*/
+    {
+        note_call *call = (note_call *)malloc(sizeof(note_call));
+        if (!call) {
+            free(t_copy);
+            free(b_copy);
+            return -3;
+        }
+        call->h = h;
+        call->title = t_copy;
+        call->body = b_copy;
+        if (!cj_plat_post_ui(h, note_idle, call)) {
+            free(t_copy);
+            free(b_copy);
+            free(call);
+            return -3;
+        }
+    }
+    return 0;
+}
+
+/* 线路格式的共享解析（契约见 bridge_core.h 的 cj_menu_row_fn 注释）。
+   就地切分一份副本：字段指针只在回调期间有效，拷贝与释放都在这里管，平台不用操心。 */
+void cj_core_menu_walk(const char *wire, cj_menu_row_fn fn, void *ctx) {
+    char *copy;
+    char *line;
+
+    if (!wire || !fn) return;
+    copy = cj_strdup(wire);
+    if (!copy) return;
+
+    line = copy;
+    while (*line) {
+        char *nl = strchr(line, '\n');
+        char *cur;
+        int depth = 0;
+        char *t1, *t2, *t3, *t4;
+        char *kind_s, *id_s, *label_s, *flags_s, *accel_s;
+
+        if (nl) {
+            *nl = '\0';
+        }
+        while (line[depth] == '\t') {
+            depth++;
+        }
+        cur = line + depth;
+        kind_s = cur;
+        id_s = NULL;
+        label_s = NULL;
+        flags_s = NULL;
+        accel_s = NULL;
+        t1 = strchr(kind_s, '\t');
+        if (t1) {
+            *t1 = '\0';
+            id_s = t1 + 1;
+            t2 = strchr(id_s, '\t');
+            if (t2) {
+                *t2 = '\0';
+                label_s = t2 + 1;
+                t3 = strchr(label_s, '\t');
+                if (t3) {
+                    *t3 = '\0';
+                    flags_s = t3 + 1;
+                    t4 = strchr(flags_s, '\t');
+                    if (t4) {
+                        *t4 = '\0';
+                        accel_s = t4 + 1;
+                    }
+                }
+            }
+        }
+        if (kind_s[0]) { /* kind 为空的行整行跳过；缺字段按空串 / 0——容错优于崩溃 */
+            fn(ctx, depth, kind_s[0], id_s ? id_s : "", label_s ? label_s : "",
+               flags_s ? atoi(flags_s) : 0, accel_s ? accel_s : "");
+        }
+
+        if (!nl) {
+            break;
+        }
+        line = nl + 1;
+    }
+    free(copy);
+}
+
+/* shell 事件编成 JSON（RFC-002 §5.5）：id 做最小转义——应用给的标识里出现 \ 或 " 时
+   不至于把载荷弄坏。（拖放的 paths 到 7.C 才落地，届时照此扩一份路径转义。） */
+static void cj_json_escape_into(char *dst, size_t cap, const char *src) {
+    size_t o = 0;
+    const char *p;
+    if (!dst || cap == 0) return;
+    for (p = src ? src : ""; *p; p++) {
+        if (o + 2 >= cap) break;
+        if (*p == '\\' || *p == '"') {
+            dst[o++] = '\\';
+        }
+        dst[o++] = *p;
+    }
+    dst[o] = '\0';
+}
+
+void cj_core_menu_clicked(cj_host *h, const char *id, int enabled, int checked) {
+    char idbuf[256];
+    char payload[384];
+    if (!h) return;
+    if (!id || !id[0]) {
+        return; /* 没有 id 就没有「被点的项」（分隔线与子菜单不会走到这里）*/
+    }
+    cj_logf("[cj-bridge] menu clicked: id=%s enabled=%d checked=%d\n",
+            id, enabled ? 1 : 0, checked ? 1 : 0);
+    if (!h->on_shell) {
+        return; /* 未注册回调：上面那行日志已经落盘，够诊断了 */
+    }
+    cj_json_escape_into(idbuf, sizeof(idbuf), id);
+    snprintf(payload, sizeof(payload),
+             "{\"kind\":\"menu\",\"id\":\"%s\",\"enabled\":%s,\"checked\":%s}",
+             idbuf, enabled ? "true" : "false", checked ? "true" : "false");
+    /* 带上宿主句柄：仓颉侧按句柄分发到对应窗口，不再依赖进程级静态槽 */
+    h->on_shell(h, payload);
+}
+
+/* 全局快捷键触发：平台在 X11/Win32 事件回调里调，id 是应用注册时给的标识。
+   载荷形状与菜单点击同族（{"kind":"hotkey","id":…}），同走 on_shell 通道。 */
+void cj_core_hotkey_pressed(cj_host *h, const char *id) {
+    char idbuf[256];
+    char payload[320];
+    if (!h) return;
+    if (!id || !id[0]) {
+        return; /* 没有 id 的触发无法路由，直接丢弃（平台侧不该产生） */
+    }
+    cj_logf("[cj-bridge] hotkey pressed: id=%s\n", id);
+    if (!h->on_shell) {
+        return; /* 未注册回调：上面那行日志已经落盘，够诊断了 */
+    }
+    cj_json_escape_into(idbuf, sizeof(idbuf), id);
+    snprintf(payload, sizeof(payload), "{\"kind\":\"hotkey\",\"id\":\"%s\"}", idbuf);
+    h->on_shell(h, payload);
+}
+
+/* 托盘菜单项被点：载荷形状与菜单/快捷键同族，同走 on_shell 通道（RFC-002 §5.5） */
+void cj_core_tray_clicked(cj_host *h, const char *id) {
+    char idbuf[256];
+    char payload[320];
+    if (!h) return;
+    if (!id || !id[0]) {
+        return; /* 没有 id 的点击无法路由（托盘图标本体点击不带 id，平台侧自行决定语义） */
+    }
+    cj_logf("[cj-bridge] tray clicked: id=%s\n", id);
+    if (!h->on_shell) {
+        return;
+    }
+    cj_json_escape_into(idbuf, sizeof(idbuf), id);
+    snprintf(payload, sizeof(payload), "{\"kind\":\"tray\",\"id\":\"%s\"}", idbuf);
+    h->on_shell(h, payload);
+}
+
+/* ===== 拖放落地（RFC-002 §5；URI 解析在 core，桩自检可测）===== */
+
+#define DROP_MAX_PATHS   32
+#define DROP_MAX_PATH_SZ 4096
+
+/* 把一行 URI 变成路径（就地写到 out，返回写入字节数，超上限返回 -1）。
+   file:// URI：剥前缀 + %XX 十六进制解码（file:// 路径里空格等必须转义成 %20）；
+   非 file:// URI：原样保留（v1 载荷语义由页面决定，core 不猜）。 */
+static int drop_uri_to_path(const char *uri, char *out, int out_cap) {
+    int o = 0;
+    const char *p = uri;
+    static const char hex[] = "0123456789ABCDEF";
+    if (strncmp(uri, "file://", 7) == 0) {
+        p = uri + 7;
+        /* file://localhost/... 也算本地路径（RFC 1738 形态，GTK 偶发） */
+        if (strncmp(p, "localhost/", 10) == 0) {
+            p += 9; /* 保留后面的 '/' */
+        }
+    }
+    for (; *p; p++) {
+        if (o >= out_cap - 1) {
+            return -1; /* 超限：丢弃这条（调用方记日志） */
+        }
+        if (p[0] == '%' && p[1] && p[2]) {
+            const char *h1 = strchr(hex, p[1]);
+            const char *h2 = strchr(hex, p[2]);
+            if (h1 && h2) {
+                /* 十六进制位必须严格配对解析；大小写都收（strchr 命中即合法） */
+                out[o++] = (char)((h1 - hex) * 16 + (h2 - hex));
+                p += 2;
+                continue;
+            }
+            /* 伪 % 序列：原样保留，交给页面/文件系统报错，core 不替它猜 */
+        }
+        out[o++] = p[0];
+    }
+    out[o] = '\0';
+    return o;
+}
+
+void cj_core_drop_files(cj_host *h, const char *uri_list) {
+    char paths[DROP_MAX_PATHS][DROP_MAX_PATH_SZ];
+    const char *escaped[DROP_MAX_PATHS];
+    char escaped_buf[DROP_MAX_PATHS][DROP_MAX_PATH_SZ];
+    int count = 0, dropped = 0;
+    const char *line;
+    if (!h || !uri_list) return;
+
+    line = uri_list;
+    while (line && *line && count < DROP_MAX_PATHS) {
+        const char *eol = strchr(line, '\n');
+        size_t len = eol ? (size_t)(eol - line) : strlen(line);
+        char uri[DROP_MAX_PATH_SZ];
+        int n;
+        if (len >= sizeof(uri)) {
+            len = sizeof(uri) - 1; /* 截断后多半解析不出合法路径，走正常丢弃路径 */
+        }
+        memcpy(uri, line, len);
+        uri[len] = '\0';
+        line = eol ? eol + 1 : NULL;
+        /* 去 \r（text/uri-list 行尾常是 \r\n）与空白 */
+        while (len > 0 && (uri[len - 1] == '\r' || uri[len - 1] == ' ')) {
+            uri[--len] = '\0';
+        }
+        /* 注释行（# 开头）与空行跳过（RFC 2483 的 text/uri-list 规范） */
+        if (len == 0 || uri[0] == '#') {
+            continue;
+        }
+        n = drop_uri_to_path(uri, paths[count], DROP_MAX_PATH_SZ);
+        if (n < 0) {
+            dropped++;
+            cj_logf("[cj-bridge] drop: path too long, dropped: %.60s...\n", uri);
+            continue;
+        }
+        count++;
+    }
+    /* 行数超上限：多出的丢弃并计数（本循环因 count 满退出，剩余行都算 dropped） */
+    if (line && *line) {
+        for (; line; line = strchr(line, '\n') ? strchr(line, '\n') + 1 : NULL) {
+            if (*line && *line != '#') {
+                dropped++;
+            }
+        }
+    }
+
+    cj_logf("[cj-bridge] drop: paths=%d first=%.80s%s\n",
+            count, count > 0 ? paths[0] : "",
+            dropped > 0 ? " (some dropped)" : "");
+    if (!h->on_shell || count == 0) {
+        return; /* 未注册回调或空拖放：日志已落盘，够诊断 */
+    }
+    /* 拼 JSON：paths 数组每项转义（文件名可含引号/反斜杠） */
+    {
+        char payload[8192];
+        int o = 0, i;
+        o += snprintf(payload + o, sizeof(payload) - (size_t)o,
+                      "{\"kind\":\"drop\",\"paths\":[");
+        for (i = 0; i < count && o < (int)sizeof(payload) - 16; i++) {
+            cj_json_escape_into(escaped_buf[i], DROP_MAX_PATH_SZ, paths[i]);
+            escaped[i] = escaped_buf[i];
+            o += snprintf(payload + o, sizeof(payload) - (size_t)o,
+                          "%s\"%s\"", i > 0 ? "," : "", escaped[i]);
+        }
+        snprintf(payload + o, sizeof(payload) - (size_t)o, "]}");
+        h->on_shell(h, payload);
+    }
+}
+
+void cj_core_dialog_abort(cj_host *h) {
+    if (!h || !h->dlg_lock) return;
+    cj_plat_sync_lock(h->dlg_lock);
+    if (h->dlg_cur && !h->dlg_ready) {
+        h->dlg_cur->ok = 0;
+        h->dlg_ready = 1;
+        h->dlg_cur = NULL;
+        cj_plat_sync_signal(h->dlg_lock);
+    }
+    cj_plat_sync_unlock(h->dlg_lock);
+}
+
+/* ===== 回投队列：一次空闲窗口拼批回投（UI 线程调用）===== */
+
+void cj_core_flush_js(cj_host *h) {
+    js_node *batch[CJ_JS_BATCH_MAX];
+    char *single = NULL; /* 快路径：接管字符串所有权，省掉一次拷贝 */
+    char *script = NULL;
+    size_t len = 0;
+    size_t cap = 0;
+    int n = 0;
+    int more = 0;
+    int i, j;
+
+    if (!h || !h->js_lock) return;
+
+    cj_plat_sync_lock(h->js_lock);
+    if (h->js_head) {
+        js_node *node = h->js_head;
+        h->js_head = node->next;
+        if (!h->js_head) {
+            h->js_tail = NULL;
+            single = node->js; /* 队里只有这一条 */
+            free(node);
+        } else {
+            batch[n++] = node;
+            while (h->js_head && n < CJ_JS_BATCH_MAX) {
+                node = h->js_head;
+                h->js_head = node->next;
+                if (!h->js_head) {
+                    h->js_tail = NULL;
+                }
+                batch[n++] = node;
+            }
+        }
+    }
+    more = (h->js_head != NULL);
+    cj_plat_sync_unlock(h->js_lock);
+
+    if (single) {
+        cj_plat_post_js(h, single);
+        free(single);
+    } else if (n > 0) {
+        /* 拼批：一段脚本只跨一次语言边界，省掉 n-1 次固定开销。
+           为什么不用 GString 之类的缓冲：core 不依赖平台库（glib / Win32）。 */
+        for (i = 0; i < n; i++) {
+            size_t nl = strlen(batch[i]->js);
+            if (len + nl + 2 > cap) {
+                size_t ncap = (len + nl + 2) * 2;
+                char *grown = (char *)realloc(script, ncap);
+                if (!grown) {
+                    /* 内存不够：退回逐条执行——宁可多花开销，也不丢回投（回投丢了前端会一直 pending）*/
+                    for (j = i; j < n; j++) {
+                        cj_plat_post_js(h, batch[j]->js);
+                    }
+                    for (j = 0; j < n; j++) {
+                        free(batch[j]->js);
+                        free(batch[j]);
+                    }
+                    free(script);
+                    if (more) cj_plat_wake_ui(h);
+                    return;
+                }
+                script = grown;
+                cap = ncap;
+            }
+            memcpy(script + len, batch[i]->js, nl);
+            len += nl;
+            script[len++] = '\n';
+            script[len] = '\0';
+            free(batch[i]->js);
+            free(batch[i]);
+        }
+        cj_plat_post_js(h, script);
+        free(script);
+    }
+
+    /* 队列没取空：自续一次，剩下的下一批走 */
+    if (more) {
+        cj_plat_wake_ui(h);
+    }
+}
+
+/* ===== 原生对话框：单槽状态机（模态，同时只允许一个）===== */
+
+static dlg_req *cj_dlg_req_new(int kind, const char *title, const char *message, const char *filter) {
+    dlg_req *r = (dlg_req *)calloc(1, sizeof(dlg_req));
+    if (!r) return NULL;
+    r->kind = kind;
+    r->title = cj_strdup(title ? title : "");
+    r->message = cj_strdup(message ? message : "");
+    r->filter = cj_strdup(filter ? filter : "");
+    return r;
+}
+
+static void cj_dlg_req_free(dlg_req *r) {
+    if (!r) return;
+    free(r->title);
+    free(r->message);
+    free(r->filter);
+    free(r->path);
+    free(r);
+}
+
+static void cj_dlg_log_closed(const dlg_req *r) {
+    if (r->kind == 0 || r->kind == 1) { /* 文件类才有路径 */
+        cj_logf("[cj-bridge] dialog closed: kind=%d ok=%d path=%s\n",
+                r->kind, r->ok, r->path ? r->path : "(none)");
+    } else {
+        cj_logf("[cj-bridge] dialog closed: kind=%d ok=%d\n", r->kind, r->ok);
+    }
+}
+
+void cj_bridge_set_dialog_callback(cj_host *h, cj_on_dialog_fn cb) {
+    if (!h) return;
+    h->on_dialog = cb;
+}
+
+void cj_bridge_set_shell_callback(cj_host *h, cj_on_shell_fn cb) {
+    if (!h) return;
+    h->on_shell = cb;
+}
+
+int cj_bridge_host_capabilities(cj_host *h) {
+    return h ? h->capabilities : 0;
+}
+
+int cj_bridge_host_eq(cj_host *a, cj_host *b) {
+    /* 只比指针本身：句柄由 core 分配、生命周期也归 core，仓颉侧只当不透明凭据使 */
+    return (a && b && a == b) ? 1 : 0;
+}
+
+int cj_bridge_show_dialog(cj_host *h, int kind, const char *title,
+                          const char *message, const char *filter) {
+    dlg_req *r;
+    int ok;
+
+    if (!h) return 0;
+    if (!h->ready) { /* 没有窗口就没有父窗口，模态对话框无处安放 */
+        cj_logf("[cj-bridge] dialog ignored: host not ready\n");
+        return 0;
+    }
+
+    cj_plat_sync_lock(h->dlg_lock);
+    if (h->dlg_busy) {
+        cj_plat_sync_unlock(h->dlg_lock);
+        cj_logf("[cj-bridge] dialog rejected: another dialog is open\n");
+        return 0;
+    }
+    h->dlg_busy = 1;
+    h->dlg_ready = 0;
+    cj_plat_sync_unlock(h->dlg_lock);
+
+    /* 调用方已经站在 UI 线程上（WebKit 的 script-message / WebView2 的 WebMessageReceived 就跑在那里）：
+       直接弹。这里**不能**走「投递 + 阻塞等待」——等待的事件得由 UI 线程处理，而 UI 线程正卡在这次调用里，
+       等于自己把自己锁死。 */
+    if (cj_plat_is_ui_thread(h)) {
+        cj_logf("[cj-bridge] dialog: kind=%d title=%s (caller on ui thread)\n",
+                kind, title ? title : "");
+        r = cj_dlg_req_new(kind, title, message, filter);
+        if (!r) {
+            cj_plat_sync_lock(h->dlg_lock);
+            h->dlg_busy = 0;
+            cj_plat_sync_unlock(h->dlg_lock);
+            return 0;
+        }
+        r->ok = cj_plat_run_dialog(h, r);
+        ok = r->ok;
+        cj_dlg_log_closed(r);
+        if (h->on_dialog) {
+            h->on_dialog(h, r->path ? r->path : ""); /* 带上句柄：结果只落发起这次对话框的窗口 */
+        }
+        cj_dlg_req_free(r);
+        cj_plat_sync_lock(h->dlg_lock);
+        h->dlg_busy = 0;
+        cj_plat_sync_unlock(h->dlg_lock);
+        return ok;
+    }
+
+    r = cj_dlg_req_new(kind, title, message, filter);
+    if (!r) {
+        cj_plat_sync_lock(h->dlg_lock);
+        h->dlg_busy = 0;
+        cj_plat_sync_unlock(h->dlg_lock);
+        return 0;
+    }
+    cj_logf("[cj-bridge] dialog: kind=%d title=%s\n", kind, r->title);
+    cj_plat_sync_lock(h->dlg_lock);
+    h->dlg_cur = r;
+    cj_plat_sync_unlock(h->dlg_lock);
+
+    cj_plat_post_dialog(h, r);
+
+    /* 等结果：窗口先关的话，cj_core_window_destroyed 会作废并唤醒（ok=0） */
+    cj_plat_sync_lock(h->dlg_lock);
+    cj_plat_sync_wait(h->dlg_lock, &h->dlg_ready);
+    ok = r->ok;
+    h->dlg_busy = 0;
+    cj_plat_sync_unlock(h->dlg_lock);
+    cj_dlg_req_free(r);
+    return ok;
+}
+
+void cj_core_dialog_tick(cj_host *h, dlg_req *req) {
+    int alive;
+    if (!h || !req) return;
+
+    cj_plat_sync_lock(h->dlg_lock);
+    alive = (h->dlg_cur == req);
+    cj_plat_sync_unlock(h->dlg_lock);
+    if (!alive) {
+        /* 窗口先关了：槽位已交回调用方（它会 free 这个请求）——这里连碰都不能碰 */
+        return;
+    }
+
+    req->ok = cj_plat_run_dialog(h, req);
+    cj_dlg_log_closed(req);
+    if (h->on_dialog) {
+        h->on_dialog(h, req->path ? req->path : "");
+    }
+
+    cj_plat_sync_lock(h->dlg_lock);
+    h->dlg_cur = NULL;
+    h->dlg_ready = 1;
+    cj_plat_sync_signal(h->dlg_lock);
+    cj_plat_sync_unlock(h->dlg_lock);
+}
+
+/* =========================================================================
+ *  串口（plugin_serial）：路径白名单 + 参数校验 + 导出转发
+ *
+ *  句柄表与 fd 全在平台层（那边本来就有 pthread / CS），本文件**不持有任何串口状态**——
+ *  因此也不需要「一次性初始化」这种钩子，导出函数可以在没有宿主的进程里直接用。
+ * ========================================================================= */
+
+#if defined(_MSC_VER)
+#define CJ_THREAD_LOCAL __declspec(thread)
+#else
+#define CJ_THREAD_LOCAL __thread
+#endif
+
+/* 线程局部：命令各自跑在 worker 线程上，静态单槽会被并发调用互相覆盖（AGENTS §4 的静态单槽坑） */
+static CJ_THREAD_LOCAL char g_serial_err[256];
+
+static void cj_serial_err_set(const char *msg) {
+    if (!msg) {
+        g_serial_err[0] = '\0';
+        return;
+    }
+    snprintf(g_serial_err, sizeof(g_serial_err), "%s", msg);
+}
+
+/* 白名单前缀表。**只放行设备节点类路径**：页面递进来的是页面可控字符串，放行面越小越好。
+   注意 "\\.\COM" 与 "COM" 两条要额外约束「后面全是数字」，否则 COMfoo 这种也会被放行。 */
+static const char *const CJ_SERIAL_PREFIXES[] = {
+    "/dev/ttyUSB", "/dev/ttyACM", "/dev/ttyS", "/dev/ttyAMA", "/dev/ttyPS",
+    "/dev/ttyTHS", "/dev/ttyXRUSB", "/dev/ttyV",      /* Linux 串口（含虚拟 ttyV*）*/
+    "/dev/tty.", "/dev/cu.",                          /* macOS：调制解调器 / 呼出设备 */
+    "/dev/serial/by-id/", "/dev/serial/by-path/",     /* udev 稳定符号链接（推荐写法）*/
+    "/dev/pts/",                                      /* 伪终端：socat / openpty 造的虚拟串口 */
+    "COM", "\\\\.\\COM",                              /* Windows：COM3 / 长名形式 */
+};
+
+#define CJ_SERIAL_MAX_PATH 255
+
+int cj_serial_path_allowed(const char *path) {
+    size_t i, n;
+
+    if (!path || !path[0]) return 0;
+    n = strlen(path);
+    if (n > CJ_SERIAL_MAX_PATH) return 0;
+    /* 含 ".." 一律拒绝：否则 "/dev/ttyUSB0/../../etc/shadow" 这种前缀命中就能穿越出去 */
+    if (strstr(path, "..")) return 0;
+
+    for (i = 0; i < sizeof(CJ_SERIAL_PREFIXES) / sizeof(CJ_SERIAL_PREFIXES[0]); i++) {
+        const char *pfx = CJ_SERIAL_PREFIXES[i];
+        size_t pl = strlen(pfx);
+        const char *rest;
+        size_t k;
+
+        if (strncmp(path, pfx, pl) != 0) continue;
+        rest = path + pl;
+        if (!rest[0]) return 0;  /* 前缀本身不是设备名（"/dev/ttyS" 这种不收）*/
+
+        if (strcmp(pfx, "COM") != 0 && strcmp(pfx, "\\\\.\\COM") != 0) {
+            return 1;
+        }
+        for (k = 0; rest[k]; k++) {
+            if (rest[k] < '0' || rest[k] > '9') return 0;
+            if (k >= 3) return 0; /* COM1..COM999（Windows 实际到 COM256）*/
+        }
+        return 1;
+    }
+    return 0;
+}
+
+static int cj_serial_cfg_ok(const cj_serial_cfg *cfg) {
+    if (!cfg) return 0;
+    if (cfg->baud <= 0) return 0;
+    if (cfg->data_bits < 5 || cfg->data_bits > 8) return 0;
+    if (cfg->parity < 0 || cfg->parity > 2) return 0;
+    if (cfg->stop_bits != 1 && cfg->stop_bits != 2) return 0;
+    return 1;
+}
+
+long long cj_bridge_serial_open(const char *path, int baud, int data_bits, int parity, int stop_bits) {
+    cj_serial_cfg cfg;
+    char err[256];
+    long long h;
+
+    g_serial_err[0] = '\0';
+    if (!path || !path[0]) {
+        cj_serial_err_set("serial: 设备路径为空");
+        return -1;
+    }
+    if (!cj_serial_path_allowed(path)) {
+        snprintf(g_serial_err, sizeof(g_serial_err),
+                 "serial: 路径不在白名单内（只放行串口设备节点 / 伪终端，且不得含 ..）: %s", path);
+        return -1;
+    }
+    cfg.baud = baud;
+    cfg.data_bits = data_bits;
+    cfg.parity = parity;
+    cfg.stop_bits = stop_bits;
+    if (!cj_serial_cfg_ok(&cfg)) {
+        cj_serial_err_set("serial: 串口参数非法（baud>0 / dataBits 5..8 / parity 0|1|2 / stopBits 1|2）");
+        return -1;
+    }
+
+    err[0] = '\0';
+    h = cj_plat_serial_open(path, &cfg, err, (int)sizeof(err));
+    if (h <= 0) {
+        cj_serial_err_set(err[0] ? err : "serial: 平台打开失败");
+        /* 失败也留一行：串口问题多半要拿 stderr 对账（AGENTS §1 的取证口径）*/
+        cj_logf("[cj-bridge] serial open failed: path=%s baud=%d code=%lld (%s)\n",
+                path, baud, h, g_serial_err);
+        return h < 0 ? h : -3;
+    }
+    cj_logf("[cj-bridge] serial open: handle=%lld path=%s baud=%d data=%d parity=%d stop=%d\n",
+            h, path, baud, data_bits, parity, stop_bits);
+    return h;
+}
+
+int cj_bridge_serial_read(long long h, unsigned char *buf, int len, int timeout_ms) {
+    char err[256];
+    int n;
+
+    g_serial_err[0] = '\0';
+    if (h <= 0 || !buf || len <= 0 || len > (1 << 20)) {
+        cj_serial_err_set("serial: read 参数非法（handle>0 / len 1..1048576）");
+        return -1;
+    }
+    if (timeout_ms < 0) timeout_ms = 0;
+    err[0] = '\0';
+    n = cj_plat_serial_read(h, buf, len, timeout_ms, err, (int)sizeof(err));
+    if (n < 0) {
+        cj_serial_err_set(err[0] ? err : "serial: 读失败");
+        cj_logf("[cj-bridge] serial read failed: handle=%lld (%s)\n", h, g_serial_err);
+    }
+    return n;
+}
+
+int cj_bridge_serial_write(long long h, const unsigned char *buf, int len, int timeout_ms) {
+    char err[256];
+    int n;
+
+    g_serial_err[0] = '\0';
+    if (h <= 0 || !buf || len <= 0 || len > (1 << 20)) {
+        cj_serial_err_set("serial: write 参数非法（handle>0 / len 1..1048576）");
+        return -1;
+    }
+    if (timeout_ms < 0) timeout_ms = 0;
+    err[0] = '\0';
+    n = cj_plat_serial_write(h, buf, len, timeout_ms, err, (int)sizeof(err));
+    if (n < 0) {
+        cj_serial_err_set(err[0] ? err : "serial: 写失败");
+        cj_logf("[cj-bridge] serial write failed: handle=%lld (%s)\n", h, g_serial_err);
+    }
+    return n;
+}
+
+int cj_bridge_serial_close(long long h) {
+    char err[256];
+    int rc;
+
+    g_serial_err[0] = '\0';
+    if (h <= 0) {
+        cj_serial_err_set("serial: close 参数非法（handle 必须 >0）");
+        return -1;
+    }
+    err[0] = '\0';
+    rc = cj_plat_serial_close(h, err, (int)sizeof(err));
+    if (rc != 0) {
+        cj_serial_err_set(err[0] ? err : "serial: 关句柄失败");
+        return rc < 0 ? rc : -4;
+    }
+    cj_logf("[cj-bridge] serial close: handle=%lld\n", h);
+    return 0;
+}
+
+const char *cj_bridge_serial_last_error(void) {
+    return g_serial_err;
+}
+
+int cj_bridge_serial_list(char *out, int out_len) {
+    if (!out || out_len <= 0) {
+        cj_serial_err_set("serial: list 参数非法（out 缓冲为空）");
+        return -1;
+    }
+    out[0] = '\0';
+    return cj_plat_serial_list(out, out_len); /* 负码原样交回（-4 = 本平台未实现） */
+}
+
+/* =========================================================================
+ *  日志落盘（RFC-003 第 5 期）
+ *
+ *  为什么在 fd 层接管：单文件产物是 Windows GUI 子系统，双击时 stderr 无处可去，而
+ *  诊断输出分布在 core、平台实现与仓颉侧上百处。把 fd 2 指向日志文件，**所有** stderr
+ *  写者自动落进同一个 FILE*（顺序天然一致），两端调用点一处都不用改；stdout 不碰。
+ *  为什么用 `dup2` 而不是 `freopen`：`freopen` 失败会**把 stderr 关掉**，那就连失败原因
+ *  都没地方写了；`dup2` 只在 open 成功后才动 fd 2，失败路径 stderr 完好。
+ *  为什么轮转不 rename 打开中的文件：Windows 上 rename 一个还开着的文件会失败。
+ *  做法是「先拷贝再截断」——把当前内容拷进 `log.1`，已关闭的档案 `.1 → .2` 平移
+ *  （`keep` 决定份数），最后 `_chsize` / `ftruncate` 把当前文件清零。这样无平台分支、
+ *  无空设备名，桩自检也能直接测。
+ * ========================================================================= */
+
+#define CJ_LOG_PATH_MAX 1024
+#define CJ_LOG_LINE_SLACK 256 /* 每行预留，免得刚好压线时写到 max 之上 */
+
+static char g_log_path[CJ_LOG_PATH_MAX];
+static int g_log_active = 0;
+static long g_log_max = 0; /* 字节；0 = 不轮转（交给外部 logrotate） */
+static long g_log_keep = 0;
+static volatile int g_log_rotating = 0;
+
+/* 轮转互斥：只用编译器内建原子，core 不引平台同步设施（命令 worker 线程也会走到这里）。
+   抢不到就当「这一行不轮转」，不阻塞调用方。 */
+static int cj_log_lock(void) {
+    return __sync_lock_test_and_set(&g_log_rotating, 1) == 0;
+}
+static void cj_log_unlock(void) {
+    __sync_lock_release(&g_log_rotating);
+}
+
+/* 时间戳：localtime 的静态缓冲可能被别的线程踩，取回来立刻拷进本地副本。 */
+static void cj_log_prefix(void) {
+    time_t now = time(NULL);
+    struct tm tmv;
+    const struct tm *p = localtime(&now);
+    char buf[40];
+    size_t n;
+
+    if (!p) return;
+    tmv = *p;
+    n = strftime(buf, sizeof(buf), "[%Y-%m-%d %H:%M:%S] ", &tmv);
+    if (n > 0) fwrite(buf, 1, n, stderr);
+}
+
+/* 真实大小以文件为准（不自己记数：平台与仓颉侧也在往同一个文件写）。
+ *
+ * 为什么不用 stat()：单文件包（scripts/pack-win-single.sh）里桥由 llvm-mingw(ucrt) 编译、
+ * 却由 SDK 自带 mingw 的 CRT 链接——ucrt 把 stat 映射成 stat64i32，而那边的导入库只认
+ * _stat，于是链接期报 `undefined symbol: stat64i32`（2026-10-21 实测，只有静态单文件包会炸，
+ * 平时的动态构建不受影响）。fopen/fseek/ftell 在 ucrt、msvcrt 与 mingw 三套 CRT 里符号名
+ * 一致，绕开这层方言差异；语义相同（文件不存在 → 0）。 */
+static long cj_log_size(void) {
+    FILE *f;
+    long size;
+
+    if (!g_log_path[0]) return 0;
+    fflush(stderr);
+    f = fopen(g_log_path, "rb");
+    if (!f) return 0;
+    if (fseek(f, 0, SEEK_END) != 0) {
+        fclose(f);
+        return 0;
+    }
+    size = ftell(f);
+    fclose(f);
+    return size > 0 ? size : 0;
+}
+
+/* 当前文件整份拷进 `<path>.<n>`（Windows 上不能 rename 打开中的文件，只能拷贝）。 */
+static void cj_log_copy_archive(long n) {
+    FILE *in;
+    FILE *out;
+    char dst[CJ_LOG_PATH_MAX + 24];
+    char buf[8192];
+    size_t got;
+    long written = 0;
+
+    snprintf(dst, sizeof(dst), "%s.%ld", g_log_path, n);
+    in = fopen(g_log_path, "rb");
+    if (!in) return;
+    out = fopen(dst, "wb");
+    if (!out) {
+        fclose(in);
+        return;
+    }
+    while ((got = fread(buf, 1, sizeof(buf), in)) > 0) {
+        if (g_log_max > 0) {
+            /* 档案不超过预算，免得轮转频繁时档案总占用翻倍 */
+            if (written + (long)got > g_log_max) got = (size_t)(g_log_max - written);
+            if ((long)got <= 0) break;
+        }
+        if (fwrite(buf, 1, got, out) != got) break;
+        written += (long)got;
+    }
+    fclose(out);
+    fclose(in);
+}
+
+/* 已关闭的档案平移：`.keep-1 → .keep` … `.1 → .2`（最老那份先删，Windows 上 rename
+   到已存在的文件会失败）。keep ≤ 0 时不动档案，轮转只截断。 */
+static void cj_log_shift(void) {
+    long i;
+    char from[CJ_LOG_PATH_MAX + 24];
+    char to[CJ_LOG_PATH_MAX + 24];
+
+    if (g_log_keep <= 0) return;
+    snprintf(to, sizeof(to), "%s.%ld", g_log_path, g_log_keep);
+    remove(to);
+    for (i = g_log_keep - 1; i >= 1; i--) {
+        snprintf(from, sizeof(from), "%s.%ld", g_log_path, i);
+        snprintf(to, sizeof(to), "%s.%ld", g_log_path, i + 1);
+        rename(from, to); /* 不存在就静默跳过 */
+    }
+}
+
+static int cj_log_rotate(void) {
+    if (!g_log_active) return 0;
+    if (!cj_log_lock()) return 0; /* 别人正在轮转：这一行让给下一轮 */
+    if (g_log_keep > 0) {
+        cj_log_shift();
+        cj_log_copy_archive(1);
+    }
+    fflush(stderr);
+    if (cj_log_truncate(cj_log_fileno(stderr)) != 0) {
+        /* 截断失败（有的文件系统不给改长度）：如实说一句，别假装轮转过 */
+        fprintf(stderr, "[cj-bridge] log rotate failed: truncate errno=%d\n", errno);
+    }
+    fprintf(stderr, "[cj-bridge] log rotated: keep=%ld archive=%s.1\n", g_log_keep, g_log_path);
+    cj_log_unlock();
+    return 1;
+}
+
+void cj_core_logf(const char *fmt, ...) {
+    va_list ap;
+
+    if (g_log_active) {
+        if (g_log_max > 0 && cj_log_size() + CJ_LOG_LINE_SLACK >= g_log_max) cj_log_rotate();
+        cj_log_prefix();
+    }
+    va_start(ap, fmt);
+    vfprintf(stderr, fmt, ap);
+    va_end(ap);
+    if (g_log_active) fflush(stderr); /* 每行即时落盘：进程被强杀也不丢 */
+}
+
+/* 父目录不在就逐个建出来：默认目录（`~/.local/state/cj-tauri/` 这类）常常还不存在。
+   建目录失败不在这里报——紧接着的 open 会带 errno 如实说，少一条重复的日志。 */
+static void cj_log_ensure_dirs(const char *path) {
+    char buf[CJ_LOG_PATH_MAX];
+    size_t i;
+    size_t n = strlen(path);
+
+    if (n == 0 || n >= sizeof(buf)) return;
+    memcpy(buf, path, n + 1);
+    for (i = 1; i < n; i++) {
+        char sep;
+        if (buf[i] != '/' && buf[i] != '\\') continue;
+        sep = buf[i];
+        buf[i] = '\0';
+        /* 跳过盘符（`C:`）与别名的根：它们建不了也不需要建 */
+        if (!(i == 2 && buf[1] == ':')) cj_log_mkdir(buf);
+        buf[i] = sep;
+    }
+}
+
+CJ_BRIDGE_API int cj_bridge_set_log_file(const char *path, int max_kb, int keep) {
+    int fd;
+
+    if (g_log_active) {
+        fprintf(stderr, "[cj-bridge] log file already active: %s (restart to change)\n", g_log_path);
+        return 0;
+    }
+    if (!path || !path[0]) {
+        fprintf(stderr, "[cj-bridge] log file refused: empty path\n");
+        return 0;
+    }
+    if (strlen(path) >= CJ_LOG_PATH_MAX) {
+        fprintf(stderr, "[cj-bridge] log file refused: path too long\n");
+        return 0;
+    }
+    /* 先 open 成功再动 fd 2：失败时 stderr 完好，失败原因才有人看得见 */
+    fd = cj_log_open(path, CJ_LOG_OFLAGS, CJ_LOG_OMODE);
+    if (fd < 0 && errno == ENOENT) {
+        /* 只有「父目录根本不存在」才顺手建出来（默认目录 `~/.local/state/cj-tauri` 常常还不存在）。
+           别的 errno（没权限、路径中间穿了普通文件、名字太长）一律原样失败——
+           照着一个开不了的路径去建目录，等于把一次手滑变成磁盘上的垃圾。 */
+        cj_log_ensure_dirs(path);
+        fd = cj_log_open(path, CJ_LOG_OFLAGS, CJ_LOG_OMODE);
+    }
+    if (fd < 0) {
+        fprintf(stderr, "[cj-bridge] log file open failed: %s (errno=%d)\n", path, errno);
+        return 0;
+    }
+    if (fd != 2) {
+        if (cj_log_dup2(fd, 2) < 0) {
+            fprintf(stderr, "[cj-bridge] log file open failed: %s (dup2 errno=%d)\n", path, errno);
+            cj_log_close(fd);
+            return 0;
+        }
+        cj_log_close(fd);
+    }
+    snprintf(g_log_path, sizeof(g_log_path), "%s", path);
+    g_log_max = max_kb > 0 ? (long)max_kb * 1024L : 0;
+    g_log_keep = keep > 0 ? (long)keep : 0;
+    g_log_active = 1;
+    /* 第一行就落在新文件里：开了、开在哪、预算多少，都能自查 */
+    cj_logf("[cj-bridge] log file: %s (max=%ldKB keep=%ld)\n", g_log_path, g_log_max / 1024, g_log_keep);
+    return 1;
+}
+
+CJ_BRIDGE_API const char *cj_bridge_log_file(void) {
+    return g_log_active ? g_log_path : "";
+}
+
+CJ_BRIDGE_API int cj_bridge_log_write(const char *line) {
+    if (!line) return -1;
+    cj_logf("%s\n", line);
+    return 0;
+}
+
+/* =========================================================================
+ *  静默子进程（为什么下沉到 C 桥见头文件同名段落）
+ *
+ *  core 只做参数校验、错误出口与日志；创建 / 终止 / 探活是平台原语。这样两平台导出名与
+ *  签名逐字一致，仓颉侧没有平台分叉的调用点（AGENTS §2 的分工铁律）。
+ * ========================================================================= */
+
+CJ_BRIDGE_API long long cj_bridge_spawn_hidden(const char *exe, const char *args) {
+    char err[512];
+    long long pid;
+
+    err[0] = '\0';
+    if (!exe || !*exe) {
+        cj_logf("[cj-bridge] spawn hidden: 程序路径为空\n");
+        return 0;
+    }
+    pid = cj_plat_spawn_hidden(exe, args ? args : "", err, (int)sizeof(err));
+    if (pid <= 0) {
+        cj_logf("[cj-bridge] spawn hidden 失败（%s）：%s\n", exe,
+                err[0] ? err : "平台没有给出原因");
+        return 0;
+    }
+    cj_logf("[cj-bridge] spawn hidden: %s -> pid=%lld\n", exe, pid);
+    return pid;
+}
+
+CJ_BRIDGE_API int cj_bridge_kill_pid(long long pid) {
+    if (pid <= 0) {
+        cj_logf("[cj-bridge] kill pid: 非法 pid=%lld\n", pid);
+        return 0;
+    }
+    return cj_plat_kill_pid(pid);
+}
+
+CJ_BRIDGE_API int cj_bridge_pid_alive(long long pid) {
+    if (pid <= 0) return 0;
+    return cj_plat_pid_alive(pid);
+}
+
+/* 内嵌资源释放：core 只做参数校验与错误出口，取资源写盘是平台原语
+   （为什么用字符串资源名、为什么幂等，见头文件同名段落与平台实现）。 */
+CJ_BRIDGE_API int cj_bridge_extract_assets(const char *dir) {
+    char err[512];
+    int n;
+
+    err[0] = '\0';
+    if (!dir || !*dir) {
+        cj_logf("[cj-bridge] extract assets: 目录为空\n");
+        return -1;
+    }
+    n = cj_plat_extract_assets(dir, err, (int)sizeof(err));
+    if (n < 0) {
+        cj_logf("[cj-bridge] extract assets 失败（%s）：%s\n", dir, err[0] ? err : "平台没有给出原因");
+        return -1;
+    }
+    if (n > 0) cj_logf("[cj-bridge] extract assets: %d 个文件就绪（%s）\n", n, dir);
+    return n;
+}
+
+/* 预加载动态库：core 只做参数校验与错误出口，LoadLibrary/dlopen 是平台原语。
+   为什么要它见头文件同名段落（2026-10-21：单文件包在别人的机器上连明文 ws:// 都挂在
+   `Can not load openssl library or function RAND_bytes.`——运行时的随机数默认走 OpenSSL，
+   而它按裸名找 DLL，只有开发机的 PATH 恰好有 Git 自带那份）。 */
+CJ_BRIDGE_API int cj_bridge_preload_library(const char *path) {
+    char err[512];
+    int ok;
+
+    err[0] = '\0';
+    if (!path || !*path) {
+        cj_logf("[cj-bridge] preload library: 路径为空\n");
+        return 0;
+    }
+    ok = cj_plat_preload_library(path, err, (int)sizeof(err));
+    if (ok <= 0) {
+        cj_logf("[cj-bridge] preload 失败（%s）：%s\n", path, err[0] ? err : "平台没有给出原因");
+        return 0;
+    }
+    cj_logf("[cj-bridge] preload: %s\n", path);
+    return 1;
+}
+