cj-tauri 0.8.0 → 1.1.0

package/native/{bridge_core.h → core/bridge_core.h}

@@ -79,6 +79,10 @@ typedef void (*cj_on_shell_fn)(struct cj_host *host, const char *json);
 #define CJ_CAP_MENU      1
 #define CJ_CAP_TRAY      2
 #define CJ_CAP_DRAG_DROP 4
+#define CJ_CAP_NOTIFICATION 8 /* 平台通知可用（Linux = freedesktop Notifications）*/
+#define CJ_CAP_HOTKEY    16 /* 全局快捷键可用（Linux = X11 grab；Wayland 不置位）*/
+#define CJ_CAP_SUBTITLE  32 /* 窗口顶部那一行能显示副标题（Linux = 与菜单栏同排的 label；
+                               Windows 的系统菜单没有自绘区，未实现、不置位）*/
 
 /* ===== 回投队列节点（core 拥有；UTF-8 存储，宽字符转换由平台在 cj_plat_post_js 里做）===== */
 typedef struct js_node {
@@ -88,7 +92,7 @@ typedef struct js_node {
 
 /* ===== 原生对话框请求（core 分配 / 释放；平台只填 ok 与 path）===== */
 typedef struct dlg_req {
-    int kind;      /* 0 打开文件 1 保存文件 2 info 3 warning 4 error 5 confirm */
+    int kind;      /* 0 打开文件 1 保存文件 2 info 3 warning 4 error 5 confirm 6 选择目录 */
     char *title;
     char *message;
     char *filter;  /* "描述|模式|描述|模式"；空串 = 不过滤 */
@@ -119,6 +123,15 @@ typedef struct cj_host {
     int dlg_ready;  /* 结果就绪（与 dlg_lock 配套的谓词）*/
     dlg_req *dlg_cur; /* 进行中的请求；窗口先关时由 cj_core_window_destroyed 作废 */
 
+    /* --- 剪贴板单槽（同一时刻只允许一次读写；窗口销毁时作废等待方）---
+       读结果经 cb_text 交回（core malloc，调用方 cj_bridge_clipboard_free 释放），
+       cb_ok=0 表示失败/作废（cb_text 为 NULL）。 */
+    cj_sync *clip_lock;
+    int clip_ready;
+    int clip_ok;
+    char *clip_text;   /* 读操作的结果（UI 线程 malloc，等待方负责释放）*/
+    int clip_busy;
+
     /* --- 窗口配置：由仓颉侧在 cj_bridge_start 之前经 cj_bridge_set_window 注入 --- */
     char *win_title;
     int win_w;
@@ -126,6 +139,15 @@ typedef struct cj_host {
     char *win_icon;  /* NULL = 系统默认图标 */
     int devtools;    /* 开发者工具开关 */
 
+    /* 窗口初始可见性（cj_bridge_set_window_visible 存入）：1 = 显示（默认，老应用行为不变）、
+       0 = 窗口建好即隐藏。**只解决「建窗那一刻该不该显示」**——运行期改可见性由平台直接投
+       UI 线程执行，不需要它。 */
+    int win_visible;
+
+    /* 最小化到托盘（cj_bridge_set_minimize_to_tray 存入）：1 = 平台把「最小化」改写成「隐藏」。
+       真到最小化那一刻平台还会复核托盘是否真装上了（没有就如实降级为普通最小化 + 一行 stderr）。 */
+    int minimize_to_tray;
+
     /* --- 预执行脚本（cj_bridge_add_init_script 追加，WebView 创建时逐条注入到
        document-start；插件的 jsShim 走这条通道，注册顺序排在 BRIDGE_JS 之后）--- */
     char **init_scripts;
@@ -139,6 +161,27 @@ typedef struct cj_host {
     /* --- 菜单线路文本（cj_bridge_set_menu 存入；平台建窗时读它，运行期改则由平台重建）--- */
     char *pending_menu_text;
 
+    /* --- 拖放策略（cj_bridge_set_drag_drop 存入：enabled/files 两个开关）。
+            enabled=0 平台不注册 drop target（默认关——现有应用零改动）；
+            平台建 view 时读它决定要不要挂 drag dest，运行期再改由平台重挂 --- */
+    int pending_drop_enabled;
+    int pending_drop_files;
+
+    /* --- 全局快捷键线路（cj_bridge_set_global_hotkeys 存入，空串 = 一个都没注册）。
+            格式一行一条：`<accel>:<id>`（accel 如 Ctrl+Alt+C，id 是应用给的标识）。
+            平台负责解析 accel 并 grab；触发时经 cj_core_hotkey_pressed 交回 core。
+            运行期再调 = 整表替换（先 ungrab 再按新表 grab） --- */
+    char *pending_hotkeys;
+
+    /* --- 托盘线路（cj_bridge_set_tray 存入，空串 = 移除托盘）。
+            格式（与 src/tray.cj 的 TrayModel.toWire() 逐字对应）：
+              第 1 行 `icon\t<路径>`（空路径 = 主题默认图标）
+              第 2 行 `tooltip\t<文本>`（可空）
+              其余行 = 菜单项，与菜单线路同格式（kind\tid\tlabel\tflags\taccel，无前导制表符 = 平铺一层）
+            平台建宿主线程时读它装配；运行期再调 = 整体重建。菜单项被点经
+            cj_core_tray_clicked 交回 core（{"kind":"tray","id":…}，与菜单点击同走 on_shell） --- */
+    char *pending_tray;
+
     /* --- 能力位（cj_plat_init 时由 cj_plat_host_capabilities 填，此后只读）--- */
     int capabilities;
 
@@ -153,7 +196,7 @@ typedef struct cj_host {
 } cj_host;
 
 /* =========================================================================
- *  平台原语清单（每个平台实现一份，共 21 个）
+ *  平台原语清单（每个平台实现一份，共 24 个）
  * ========================================================================= */
 
 /* ---- 同步（Linux: pthread_mutex + pthread_cond / Windows: CS + CONDITION_VARIABLE）---- */
@@ -180,6 +223,12 @@ void cj_plat_wake_ui(cj_host *h);/* 让 UI 线程尽快跑一次 cj_core_flush_j
 void cj_plat_post_js(cj_host *h, const char *script_utf8); /* UI 线程执行一段 JS（含失败日志）*/
 int  cj_plat_is_ui_thread(cj_host *h);                     /* 1 = 调用方已站在 UI 线程上 */
 void cj_plat_post_dialog(cj_host *h, dlg_req *req);        /* 投到 UI 线程 → cj_core_dialog_tick */
+
+/* 通用「投到 UI 线程执行」原语（剪贴板等后续宿主能力共用；对话框那套是它之前的专用通道）：
+   在 UI 线程上回调 fn(ud)（一次），投不出去返回 0（调用方自行作废等待）。
+   平台实现：Linux = g_idle_add；Windows = PostMessageW 新消息，UI 线程取 lParam 调 fn。 */
+typedef void (*cj_ui_fn)(void *ud);
+int cj_plat_post_ui(cj_host *h, cj_ui_fn fn, void *ud);
 int  cj_plat_run_dialog(cj_host *h, dlg_req *req);         /* UI 线程直接弹原生对话框，写 req */
 void cj_plat_open_devtools(cj_host *h);
 void cj_plat_load_url(cj_host *h, const char *url);
@@ -190,7 +239,33 @@ void cj_plat_reload(cj_host *h);
    调用时机两头都要支持：**未就绪**时只记下（平台建窗时读 h->pending_menu_text）；**已就绪**时由平台
    投到 UI 线程重建菜单。cj_plat_menu_item_state 只改运行期状态（可用 / 勾选），要快、可能频繁。 */
 void cj_plat_set_menu(cj_host *h, const char *wire);
+
+/* 平台原语：把副标题写到窗口顶部那一行（UI 线程调用）。返回 0 = 已提交，
+   -3 = 宿主未就绪，-4 = 本平台没这块（Windows 的系统菜单没有自绘区）。 */
+int cj_plat_set_titlebar_subtitle(cj_host *h, const char *text);
 void cj_plat_menu_item_state(cj_host *h, const char *id, int enabled, int checked);
+void cj_plat_set_drag_drop(cj_host *h, int enabled, int files);
+
+/* 全局快捷键（RFC-003 第 5 期首个落地项）：wire 一行一条 `<accel>:<id>`（见 pending_hotkeys 注释）。
+   调用时机两头都要支持：未就绪时只记下（平台建宿主线程后读 h->pending_hotkeys），
+   已就绪时整表替换（先 ungrab 旧表再 grab 新表）。平台不支持（Wayland / Windows 桩）时
+   打一行 stderr 如实说明，不算错误。 */
+void cj_plat_set_global_hotkeys(cj_host *h, const char *wire);
+
+/* 托盘（RFC-002 §7.C）：wire 见 pending_tray 注释，空串 = 移除托盘。
+   未就绪时只记下（宿主线程装配时读 h->pending_tray）；已就绪时投 UI 线程重建。
+   平台不支持 / 依赖没编进来时打一行 stderr 如实说明（可选编译，RFC-002 §6.3）。 */
+void cj_plat_set_tray(cj_host *h, const char *wire);
+
+/* 窗口可见性（RFC-003 第 5 期余项：最小化到托盘的还原路径）。
+   未就绪时平台**什么都不做**——core 已把值写进 h->win_visible，平台建窗时读它定稿；
+   已就绪时投 UI 线程执行（Linux = gtk_widget_show/hide + gtk_window_present，Windows = ShowWindow）。 */
+void cj_plat_set_window_visible(cj_host *h, int visible);
+
+/* 最小化到托盘策略（须在建窗前调）：平台把窗口过程 / 窗口状态信号里的「最小化」改写成「隐藏」。
+   平台在**真要最小化那一刻**复核托盘是否真的装上了（能力位 / 应用有没有 setTray）：
+   没装就降级为普通最小化并打一行 stderr——窗口藏起来却没有还原入口是比「不支持」更糟的结果。 */
+void cj_plat_set_minimize_to_tray(cj_host *h, int enabled);
 
 /* 宿主能力位（CJ_CAP_* 的按位或）：纯静态事实，cj_plat_init 里由平台给出。 */
 int cj_plat_host_capabilities(cj_host *h);
@@ -221,10 +296,10 @@ long long cj_plat_serial_open(const char *path, const cj_serial_cfg *cfg, char *
 int cj_plat_serial_read(long long h, unsigned char *buf, int len, int timeout_ms, char *err, int err_len);
 int cj_plat_serial_write(long long h, const unsigned char *buf, int len, int timeout_ms,
                          char *err, int err_len);
-int cj_plat_serial_close(long long h, char *err, int err_len);
-
-/* 枚举本机串口：一行一个名字写进 out（\n 分隔），返回条数；-1 参数非法，-4 未实现。
-   Linux 侧尚未实现（-4）——serial:list 在 Linux 仍走仓颉侧的 /dev 目录扫描。 */
+int cj_plat_serial_close(long long h, char *err, int err_len);
+
+/* 枚举本机串口：一行一个名字写进 out（\n 分隔），返回条数；-1 参数非法，-4 未实现。
+   Linux 侧尚未实现（-4）——serial:list 在 Linux 仍走仓颉侧的 /dev 目录扫描。 */
 int cj_plat_serial_list(char *out, int out_len);
 
 /* 设备路径白名单（纯函数、平台无关）：只放行常见串口设备节点 / 伪终端 / udev 稳定链接，
@@ -240,6 +315,8 @@ void cj_core_set_ready(cj_host *h);       /* 窗口 + WebView 就绪（平台在
 void cj_core_flush_js(cj_host *h);        /* UI 线程：取队列拼批回投（idle / WM_CJT_FLUSH 里调）*/
 void cj_core_dialog_tick(cj_host *h, dlg_req *req); /* UI 线程：弹对话框 → 回调 → 唤醒等待方 */
 void cj_core_dialog_abort(cj_host *h);    /* 作废进行中的对话框并唤醒等待方（ok=0，幂等）*/
+int cj_core_clipboard_tick(cj_host *h, int is_write, char *text); /* UI 线程：执行剪贴板调用 → 唤醒等待方（返回 1=成功）*/
+void cj_core_clipboard_abort(cj_host *h); /* 作废进行中的剪贴板请求并唤醒等待方（幂等）*/
 void cj_core_window_destroyed(cj_host *h);/* 窗口销毁：置标志 + 通知 onDestroy（一次）+ 作废对话框 */
 
 /* ---- 菜单线路格式的共享解析（两平台翻译层共用，避免各写一遍前缀/分割逻辑）----
@@ -260,6 +337,24 @@ void cj_core_menu_walk(const char *wire, cj_menu_row_fn fn, void *ctx);
 /* 平台把「菜单项被点了」交回 core：core 记日志 + 经 h->on_menu 回调仓颉侧（带宿主身份）。 */
 void cj_core_menu_clicked(cj_host *h, const char *id, int enabled, int checked);
 
+/* 全局快捷键触发（平台在 grab 的事件回调里调）：id 是应用注册时给的标识。
+   core 记日志 + 以 shell 报文 {"kind":"hotkey","id":"…"} 经 on_shell 回调仓颉侧（首参宿主句柄，
+   仓颉侧按句柄路由——快捷键事件与菜单点击同走 on_shell 通道，不新增回调类型）。 */
+void cj_core_hotkey_pressed(cj_host *h, const char *id);
+
+/* 托盘菜单项被点（平台在 appindicator 的 activate 回调里调）：id 是 TrayModel 里应用给的标识。
+   core 记日志 + 以 shell 报文 {"kind":"tray","id":"…"} 经 on_shell 回调仓颉侧（首参宿主句柄，
+   按句柄路由；前端事件名 tray:click 由仓颉侧 shellEventNameFor 映射——RFC-002 §5.5 既有约定）。 */
+void cj_core_tray_clicked(cj_host *h, const char *id);
+
+/* 拖放落地（平台在 drag-data-received 里调）：uri_list 是 text/uri-list 原文
+   （\r\n 或 \n 分隔，可含 file:// URI 与百分比编码）。
+   core 负责解析：跳过注释行/空行、file:// 解码成路径（%XX 十六进制解码）、
+   非 file:// 的 URI 原样保留（v1 载荷只有文件，页面自己决定要不要）。
+   结果以 shell 报文 {"kind":"drop","paths":[…]} 经 on_shell 回投（首参宿主句柄，
+   仓颉侧按句柄路由）。paths 上限 32 个、单个路径上限 4096 字节（超限丢弃并记日志）。 */
+void cj_core_drop_files(cj_host *h, const char *uri_list);
+
 /* =========================================================================
  *  仓颉 → C 桥：导出（全部实现在 bridge_core.c，两平台同一份）
  * ========================================================================= */
@@ -328,6 +423,33 @@ CJ_BRIDGE_API void cj_bridge_set_menu(cj_host *h, const char *wire);
 /* 运行期改单个菜单项的状态（按 id 找；找不到只记日志不报错）。 */
 CJ_BRIDGE_API void cj_bridge_set_menu_item_state(cj_host *h, const char *id, int enabled, int checked);
 
+/* 拖放策略（RFC-002 §5）：enabled=0 平台不注册 drop target（默认关）。
+   两头都能用：未就绪时记 pending（建 view 时读），就绪后平台投 UI 线程重挂 drag dest。 */
+CJ_BRIDGE_API void cj_bridge_set_drag_drop(cj_host *h, int enabled, int files);
+
+/* 窗口顶部副标题：把一行 UTF-8 文本画在原生菜单栏**同一行的右侧**（应用据此省掉
+   自己的页面顶栏，标题 / 保存状态 / 字数都能挂在原生那一行上）。允许运行期高频更新，
+   实现必须自己投递到 UI 线程（Linux 走 g_idle_add，同 set_menu）。
+   返回 0 = 已受理，-1 = 参数非法（含超过 1024 字节），-3 = 宿主未就绪，
+   -4 = 本平台未实现（应用据 CJ_CAP_SUBTITLE 决定要不要自己画顶栏）。 */
+CJ_BRIDGE_API int cj_bridge_set_titlebar_subtitle(cj_host *h, const char *text);
+
+/* 全局快捷键：wire 一行一条 `<accel>:<id>`（空串 = 全部注销）。
+   两头都能用：未就绪时记 pending（宿主线程起来后读），就绪后整表替换（ungrab 旧表再 grab 新表）。 */
+CJ_BRIDGE_API void cj_bridge_set_global_hotkeys(cj_host *h, const char *wire);
+
+/* 托盘（RFC-002 §7.C）：wire 见 pending_tray 注释（icon/tooltip 两行 + 菜单项），空串 = 移除。
+   两头都能用：未就绪时记 pending（宿主线程装配时读），就绪后平台投 UI 线程重建。 */
+CJ_BRIDGE_API void cj_bridge_set_tray(cj_host *h, const char *wire);
+
+/* 窗口可见性（对标 Tauri 的 window.show()/hide()）：visible=1 显示并提到前台、0 隐藏。
+   两头都能用：未 start 时只记下（平台建窗时按 h->win_visible 定稿），start 之后投 UI 线程执行。 */
+CJ_BRIDGE_API void cj_bridge_set_window_visible(cj_host *h, int visible);
+
+/* 最小化到托盘策略（须在 cj_bridge_start 之前调）：1 = 平台把「最小化」改写成「隐藏」。
+   平台在真要最小化那一刻复核托盘是否装上，没装则降级为普通最小化 + 一行 stderr。 */
+CJ_BRIDGE_API void cj_bridge_set_minimize_to_tray(cj_host *h, int enabled);
+
 /* shell 事件回调（菜单点击等；载荷见 cj_on_shell_fn 的注释，首参为宿主句柄）。 */
 CJ_BRIDGE_API void cj_bridge_set_shell_callback(cj_host *h, cj_on_shell_fn cb);
 
@@ -375,4 +497,122 @@ CJ_BRIDGE_API int cj_bridge_serial_list(char *out, int out_len);
    每次串口导出调用都会先清空它，失败时写入；返回的指针在该线程下次调用前有效。 */
 CJ_BRIDGE_API const char *cj_bridge_serial_last_error(void);
 
+/* =========================================================================
+ *  剪贴板（plugin_clipboard）：宿主能力——GTK 的 clipboard 依赖 gtk_init 后的环境，
+ *  且 GTK 规定剪贴板调用必须在 GTK 线程上，所以**带 cj_host**（借它的 UI 线程分流），
+ *  与对话框同一套「已在 UI 线程就直接做、否则投递 + 有界等待」的样板。
+ *  返回码口径：0 = 成功，-1 = 参数非法，-3 = 宿主未就绪 / 平台失败，-4 = 本平台未实现。
+ * ========================================================================= */
+
+/* 写文本：text 须为合法 UTF-8，长度上限 8 MB（core 校验）。0 = 成功。 */
+CJ_BRIDGE_API int cj_bridge_clipboard_write_text(cj_host *h, const char *text);
+
+/* 读文本：返回 malloc 的 UTF-8 字符串（可能为 NULL = 剪贴板为空 / 不是文本）。
+   用 cj_bridge_clipboard_free 释放，**不许**在仓颉侧 free。 */
+CJ_BRIDGE_API char *cj_bridge_clipboard_read_text(cj_host *h);
+
+/* 释放 read_text 返回的缓冲（NULL 安全，幂等）。 */
+CJ_BRIDGE_API void cj_bridge_clipboard_free(char *s);
+
+/* 平台原语：真正的剪贴板读写。err 口径同其余原语（-4 未实现由平台自己报）。 */
+int cj_plat_clipboard_write_text(cj_host *h, const char *text, char *err, int err_len);
+char *cj_plat_clipboard_read_text(cj_host *h, char *err, int err_len);
+
+/* =========================================================================
+ *  系统通知（plugin_notification）：与剪贴板同一类宿主能力，但**发后即忘**——
+ *  通知提交后显示与否不回传（freedesktop 协议本就不给同步回执），core 校验 + 投
+ *  UI 线程即返回，成败只在 stderr 留行。返回码：0 = 已提交，-1 = 参数非法，
+ *  -3 = 宿主未就绪 / 平台失败，-4 = 本平台未实现。
+ * ========================================================================= */
+
+/* 发一条通知：title 非空且 ≤256 字节，body ≤8 KiB（core 校验）。0 = 已提交。 */
+CJ_BRIDGE_API int cj_bridge_notification_notify(cj_host *h, const char *title, const char *body);
+
+/* 平台原语：真正发通知（UI 线程调用）。 */
+int cj_plat_notification_notify(cj_host *h, const char *title, const char *body,
+                                char *err, int err_len);
+
+/* =========================================================================
+ *  日志落盘（RFC-003 第 5 期）：把 stderr 接管到文件，给「没有控制台」的产物留凭证
+ *
+ *  为什么在 fd 层接管：单文件产物是 Windows GUI 子系统，双击时 stderr 无处可去；
+ *  而诊断输出分布在 core、平台实现与仓颉侧上百处。解 `freopen` 一次，**所有** stderr
+ *  写者自动落进同一个 FILE*（顺序天然一致），两端调用点一处都不用改。stdout 一律不碰
+ *  （`CJ_TAURI_MANIFEST` 的插件清单走 stdout）。
+ * ========================================================================= */
+
+/* 开启日志落盘：path 非空且可写时返回 1，否则返回 0 并在**还在的** stderr 上说明原因。
+   max_kb ≤ 0 表示不轮转（交给外部 logrotate）；keep = 保留几份档案（log.1 … log.keep），
+   ≤0 表示轮转时直接丢弃旧内容。**只能在第一条日志之前调**——已开启后重复调用返回 0
+   （stderr 已经被接管，换不了目标；想换就重启应用换参数）。 */
+CJ_BRIDGE_API int cj_bridge_set_log_file(const char *path, int max_kb, int keep);
+
+/* 回读生效中的日志路径；未开启返回空串。供 system:host 如实上报。 */
+CJ_BRIDGE_API const char *cj_bridge_log_file(void);
+
+/* 追加一行调用方提供的日志（同样走轮转；用于 log 插件把前端报错并进同一份文件）。
+   返回 0 = 已写入（或未开启但已落 stderr），-1 = 参数非法。 */
+CJ_BRIDGE_API int cj_bridge_log_write(const char *line);
+
+/* core 内的诊断输出统一走它：**未开启落盘时逐字节等同 `fprintf(stderr, …)`**
+   （现有 E2E needle 与 `[cj-bridge]` 前缀断言因此一条都不受影响）；开启后才加
+   `[YYYY-MM-DD HH:MM:SS] ` 前缀并按大小轮转。 */
+void cj_core_logf(const char *fmt, ...)
+#if defined(__GNUC__)
+    __attribute__((format(printf, 1, 2)))
+#endif
+    ;
+#define cj_logf(...) cj_core_logf(__VA_ARGS__)
+
+/* =========================================================================
+ *  静默子进程：后台启动控制台程序，与宿主 / 窗口无关（不带 cj_host）
+ *
+ *  为什么必须下沉到 C 桥：cj-tauri 应用都是 GUI 子系统（Windows 的 `--subsystem=windows`），
+ *  父进程**没有控制台**；此时拉起一个控制台子系统的子进程，Windows 会给它**单独配一个控制台
+ *  窗口**——用户看到的就是一个黑窗口。仓颉的 `std.process.launch` 没有创建标志可传，
+ *  所以这条只能在桥里做：Windows 走 `CreateProcessW` + `DETACHED_PROCESS`（连隐藏 console 都不建），
+ *  Linux 走 `fork` + `execv` + `setsid`（脱开终端，Ctrl-C 不连带打死）。
+ *
+ *  三个导出两平台同名同签名（AGENTS §2）：上层因此没有平台分叉的调用点。
+ * ========================================================================= */
+
+/* 静默启动：exe 是程序路径（UTF-8），args 是参数串（UTF-8，**以 0x1F 分隔**，空串 = 无参数）。
+   引号 / 空格由平台按各自规则转义，调用方**不要**自己加引号。
+   返回 pid（> 0）；失败返回 0，原因由平台写进 stderr（core 会再补一行带 exe 的上下文）。 */
+CJ_BRIDGE_API long long cj_bridge_spawn_hidden(const char *exe, const char *args);
+
+/* 终止该 pid（幂等：进程已经不在了也返回 1）。返回 1 = 已结束，0 = 无权 / 失败。 */
+CJ_BRIDGE_API int cj_bridge_kill_pid(long long pid);
+
+/* 该 pid 是否还活着：1 = 活着，0 = 已退出或查不到（**含没权限查**——按「不在」上报，
+   比谎报活着好：调用方据它决定要不要重新拉起）。 */
+CJ_BRIDGE_API int cj_bridge_pid_alive(long long pid);
+
+/* 把产物内嵌的资源释放到 dir（单文件包用：scripts/pack-win-single.sh 把随包的程序与依赖 DLL
+   作为 RT_RCDATA 资源嵌进 exe，资源名就是文件名）。
+   返回值：> 0 = 已就绪的文件数（本次释放的 + 本来就在的），0 = **产物里没有内嵌资源**
+   （普通构建、非单文件包都是这个），-1 = 参数为空或写盘失败（原因在 stderr）。
+   幂等：目标文件已存在且大小与资源一致就跳过——每次启动调它不会重写一份几十 MB 的资源。
+   目录由调用方给（桥不认识应用名）：典型是 %LOCALAPPDATA%\应用名\runtime。 */
+CJ_BRIDGE_API int cj_bridge_extract_assets(const char *dir);
+
+/* 按**绝对路径**把一个动态库加载进本进程（单文件包专用：随包释放出来的 OpenSSL 这类
+   「运行期按名字 LoadLibrary」的组件，不预加载就永远找不到）。
+   为什么需要它（2026-10-21 实测，另一台机器）：仓颉运行时的 TLS 加载器按**裸名**找
+   `libssl-3-x64.dll` / `libcrypto-3-x64.dll`，SDK 与 stdx 都不带；开发机上它恰好命中 PATH 里的
+   Git 自带那份，于是「本机全通、别人双击就挂」。症状极具误导性：http 照常 200（cjh 的
+   /api/health 通），**只有 ws 握手失败**——`ws: connect failed: Can not load openssl library or
+   function RAND_bytes.`（RFC6455 升级要算随机 nonce，明文 ws:// 也逃不掉）。
+   做法是进程启动早期先按绝对路径 LoadLibrary/dlopen 一次：之后同类裸名加载会命中已加载模块，
+   不必改系统 PATH、也不必把 DLL 摆到 exe 旁边（单文件承诺不破）。
+   返回 1 = 已加载（含本来就在的），0 = 失败（原因在 stderr）。 */
+CJ_BRIDGE_API int cj_bridge_preload_library(const char *path);
+
+/* 平台原语（err 口径同其余原语：写不进就留空，core 会打「平台没有给出原因」）。 */
+long long cj_plat_spawn_hidden(const char *exe, const char *args, char *err, int err_len);
+int cj_plat_kill_pid(long long pid);
+int cj_plat_pid_alive(long long pid);
+int cj_plat_extract_assets(const char *dir, char *err, int err_len);
+int cj_plat_preload_library(const char *path, char *err, int err_len);
+
 #endif /* CJ_BRIDGE_CORE_H */

package/native/platforms/harmonyos/README.md

@@ -0,0 +1,106 @@
+# HarmonyOS ArkWeb 平台适配
+
+状态（2026-10-19）：**宿主已在仓颉侧落地并在真机跑通完整闭环；C 桥未落地，宿主能力位仍全 0**。
+
+判据分三层，别混为一谈：
+
+- **宿主基元已落地并真机验证**——建窗标签、页面装载（内联 HTML / URL）、document-start 桥脚本注入、
+  报文接送（`post`）、结果回投（`runJavaScript` 推送）、页面事件回投、退出标志。
+  真机闭环的判据是**页面自己发起**的一次往返：`system:version` 回到页面拿到
+  `{"name":"cj-tauri","version":"1.0.0","protocol":"1","cangjie":"1.0.5","platform":"ohos"}`，
+  应用自注册命令（`probe:log`）同链路返回 `"logged"`，同轮 hilog `SIGSEGV` 计数 0。
+- **C 桥（`cj_core_*`）/ NAPI 层未落地**——鸿蒙侧不走 C 桥：宿主直接由仓颉侧 `src/host_arkweb.cj`
+  实现，`@When[env == "ohos"]` 一平台一份。按 AGENTS §2，新增宿主能力仍是「先扩 `WebViewHost` 接口、
+  再改各平台实现」，但不要求鸿蒙侧补同名 `cj_bridge_*` 导出（无 C 桥平台：核心 FFI 一律
+  `@When` 门禁 + 如实降级，见 §4）。
+- **宿主能力位全 0**——菜单、托盘、全局快捷键、拖放、原生对话框、剪贴板、通知、标题栏副标题
+  一律如实拒绝（`hostCapabilities()` 返回 0）。按 AGENTS §1 门禁 4：**没有实机证据的能力位
+  不许上报**，所以它们不会因为「代码里写了」就变成 1。
+
+⚠️ **两条与桌面平台不同的硬约束**（真机踩过，改动前务必看）：
+
+1. **`@Component` / `Web` / `javaScriptProxy` 属应用侧**，框架包不得引用 ArkUI——
+   框架包作为独立编译单元引用 `kit.ArkUI` 会让鸿蒙包初始化链跳坏地址、启动即 SIGSEGV。
+   框架只导出 ArkUI-free 的桥接函数（`src/arkweb_proxy.cj`）。
+2. **`javaScriptProxy` 的返回值传不回页面**（实测恒 `null`）。回投必须**由原生推**：
+   页面发 `{"type":"pull"}` 心跳，应用侧 proxy 回调（UI 线程）取 `takePendingScripts()`
+   用 `controller.runJavaScript` 推送。详见 `docs/鸿蒙ArkWeb接入踩坑.md` §8.1。
+
+## 形态：宿主在仓颉侧，不是 ArkTS + NAPI
+
+本目录最初的设计假设是「ArkTS 托管 Web 组件 + NAPI 模块回投」，那条路**没有采用**。
+实测结论：仓颉的 ArkUI 绑定（`kit.ArkUI` / `ohos.arkui.component.common`）能直接声明
+`Web(src: controller:)` 组件、拿到 `WebviewController`，因此整个宿主可以写在仓颉里，
+与桌面两平台共用同一套 `WebViewHost` 接口（`src/host.cj`）与同一层 IPC / 能力校验。
+
+所以 `native/platforms/harmonyos/` **暂时没有 C 实现，也不需要**：
+
+- framework 核心包在鸿蒙侧已无任何未解析的 `cj_bridge_*` 符号——所有核心 FFI 都带了
+  `@When[env != "ohos"]` 门禁并在鸿蒙侧如实降级（`src/log_bridge.cj` 的日志落盘、
+  `src/clipboard_bridge.cj` 的剪贴板/通知）。判据是一条命令：
+  `llvm-nm -D --undefined-only <模块.so> | grep cj_bridge` 必须 **0 行**。
+- 剩下的插件级 FFI（`src/plugins/serial/serial_bridge.cj`、`src/plugins/sqlite/sqlite_ffi.cj`）
+  属于各自插件包，应用不引用就不链接；真要在鸿蒙用它们时，那是**插件**的事，不是本平台的桥。
+
+什么时候才真的需要这座桥：某个能力**在仓颉 ArkUI 绑定里没有对应 API**、只能靠 NAPI 才能做到。
+到那时按 AGENTS §2 补——导出名与桌面同名同签名（`cj_bridge_*`）、回调首参必须带
+`struct cj_host *`、不要造新的静态单槽。
+
+## 实现分布
+
+| 文件 | 职责 |
+| --- | --- |
+| `src/host_arkweb.cj` | `ArkWebHost`（实现 `WebViewHost` 全部 31 个成员）+ `ArkWebRuntime`（运行时登记、沙箱目录、退出标志） |
+| `src/arkweb_proxy.cj` | ArkUI-free 的两个代理函数（`arkWebProxyPost` / `arkWebProxyPoll`），由**应用侧** `@Component` 塞进 `javaScriptProxy` |
+| `src/arkweb_script.cj` | 前端桥门面：`ARKWEB_BRIDGE_JS` + label 注入；回投靠页面 `setInterval` 发 `{"type":"pull"}` 心跳、原生推回去（**不是**返回值通道） |
+| ~~`src/arkweb_view.cj`~~ | **已移出框架**：框架包一旦 `import kit.ArkUI.*`，鸿蒙上启动即 SIGSEGV（判据见踩坑文档 §9.2）。`@Component` / `Web` 只能由应用模块持有 |
+| `src/host.cj` | 平台分叉点：`@When[env == "ohos"]` 下 `createHost` 取应用注入的宿主工厂 |
+
+## 平台判据：只能用 `env`，不能用 `os` / `arch`
+
+- 鸿蒙目标的 `os` **报 `Linux`**（实测），与桌面 Linux 撞车，分不开「GTK 宿主」和「ArkWeb 宿主」。
+- `arch` 也不行：桌面 aarch64 Linux 同样是 `aarch64`，会把有 C 桥的桌面平台一起门禁掉
+  （日志落盘能力会凭空消失）。
+- 可靠判据是 `env`：`aarch64-linux-ohos` → `ohos`，桌面 → `gnu`。所以框架里所有鸿蒙门禁
+  一律写 `@When[env == "ohos"]` / `@When[env != "ohos"]`。
+- `system:version` 的 `platform` 字段在鸿蒙上如实返回 `ohos`（`src/version.cj`）。
+
+## 与桌面宿主的行为差异（已知且有意）
+
+1. **窗口配置不生效**：窗口归 Ability 的 `WindowStage`，`setWindowConfig` 只留一行 stderr。
+   能力位里没有窗口控制位。
+2. **内联 HTML 落沙箱文件**：ArkWeb 的 `WebviewController` **没有 `loadData`**，所以
+   `run(html)` 先把页面写进应用沙箱再以 `file://` 装载；沙箱目录由
+   `ArkWebRuntime.configure(filesDir)` 提供，未配置时**明确拒绝**而不是白屏。
+3. **没有 UI 定时器**：ArkUI 绑定不暴露 UI 线程定时器，也没有 `UIContext`。页面到原生的
+   回投改成「页面侧 `setInterval` 调同步 `javaScriptProxy` 的 `poll`」，页面求值在页面
+   自己的线程上执行——避免把宿主 UI 线程当消息泵。
+4. **`quit()` 只置标志**：窗口归 Ability，退出得应用自己 `terminateSelf()`；
+   框架不假装关掉了窗口。
+5. **宿主句柄没有跨平台相等语义**：`hostHandleEquals` 在鸿蒙侧返回 false 并留一行 stderr。
+   多窗口路由在鸿蒙上靠 window label，不靠句柄——**绝不伪造相等**（伪造会让两个窗口串台）。
+
+## 验收出口（未完成的都在这里）
+
+真机（平板 / 2-in-1；手机需单独声明）上要拿到的证据，按 AGENTS §1：
+
+- [x] HAP 能构建（`entry-default-signed.hap`）
+- [x] 应用启动到 ArkWeb 页面，hilog 里没有 panic / fatal（同轮 `SIGSEGV` 计数 0）
+- [x] 前端 `invoke('system:version')` 往返成功，返回 `platform=ohos`
+- [x] 多窗口下宿主事件按 label 路由、不串台
+- [x] `llvm-nm -D --undefined-only <模块.so> | grep cj_bridge` 为 0 行
+
+前四项与最后一项是 2026-10-19 两轮真机闭环的取证结果（过程见
+`docs/鸿蒙ArkWeb接入踩坑.md` §8.1 / §8.2）。多窗口那条的判据（同一台真机、同一份 HAP）：
+
+- 两个 `@Component` 实例各带自己的 label（`main` / `second`），上层宿主登记里出现两行
+  `host pageUrl label=main url="…/cj-tauri-main.html"` 与 `…cj-tauri-second.html`
+  ——**页面文件按 label 分开**，两窗看的不是同一份 HTML；
+- 两窗各自 `page begin label=main` / `label=second`，两窗各完成一次 `probe:hello`；
+- 跨窗**定向**投递双向成立：`probe:hello window=main -> probe:ping target=second` 之后是
+  `probe:log window=second <- {"kind":"ping-recv","me":"second","from":"main"}`，反向同理；
+  每条报文里 `window=`（原生侧归属）与 `me=`（页面自认的 label）**逐条恒等**——这就是「不串台」；
+- 同轮 `SIGSEGV` / `panic` / `fatal` 计数 0，`command not allowed|registered|rejected` 计数 0。
+
+宿主能力位（菜单 / 托盘 / 快捷键 / 拖放 / 对话框 / 剪贴板 / 通知）**仍一项都没有证据**，
+所以 `hostCapabilities()` 保持返回 0——别因为「代码里写了降级」就把它读成验收过了。