From 87cdb8bfbadfa1b240e060534870baf058aa1ea7 Mon Sep 17 00:00:00 2001 From: kdletters Date: Wed, 17 Jun 2026 23:19:59 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8E=A5=E5=85=A5=E6=A1=8C=E9=9D=A2=E5=A3=B3?= =?UTF-8?q?=E5=8F=97=E6=8E=A7=E7=AB=99=E5=86=85=E5=AF=BC=E8=88=AA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tauri 桌面壳支持 navigation.openNativePage 的同源 H5 路由跳转 补充桌面壳导航白名单校验和运行时能力检查 更新宿主壳方案和项目共享决策记录 --- apps/desktop-shell/scripts/check-config.mjs | 3 +- apps/desktop-shell/src-tauri/src/main.rs | 83 ++++++++++++++++++- apps/desktop-shell/src-tauri/tauri.conf.json | 4 +- .../shared-memory/decision-log.md | 2 +- ...ExpoReactNative与Tauri宿主壳方案-2026-06-17.md | 4 +- ...前端架构】宿主壳能力统一协议-2026-06-17.md | 2 +- 6 files changed, 90 insertions(+), 8 deletions(-) diff --git a/apps/desktop-shell/scripts/check-config.mjs b/apps/desktop-shell/scripts/check-config.mjs index 73e9ef82..0d5d8fd8 100644 --- a/apps/desktop-shell/scripts/check-config.mjs +++ b/apps/desktop-shell/scripts/check-config.mjs @@ -34,7 +34,7 @@ const requiredUrlParts = [ 'hostShell=tauri_desktop', 'hostPlatform=unknown', 'bridgeVersion=1', - 'hostCapabilities=host.getRuntime,share.open,share.setTarget,app.openExternalUrl,app.setTitle,clipboard.writeText,file.exportText', + 'hostCapabilities=host.getRuntime,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,clipboard.writeText,file.exportText', ]; for (const part of requiredUrlParts) { @@ -55,6 +55,7 @@ const requiredMainSnippets = [ 'tauri_plugin_clipboard_manager::init()', '"share.open"', '"share.setTarget"', + '"navigation.openNativePage"', '"app.setTitle"', '"clipboard.writeText"', '"file.exportText"', diff --git a/apps/desktop-shell/src-tauri/src/main.rs b/apps/desktop-shell/src-tauri/src/main.rs index 0a7cf8ef..90f2e661 100644 --- a/apps/desktop-shell/src-tauri/src/main.rs +++ b/apps/desktop-shell/src-tauri/src/main.rs @@ -4,6 +4,7 @@ use std::fs; use std::path::PathBuf; use std::sync::Mutex; use tauri::Manager; +use tauri::Url; use tauri_plugin_clipboard_manager::ClipboardExt; use tauri_plugin_dialog::DialogExt; use tauri_plugin_opener::OpenerExt; @@ -77,6 +78,7 @@ fn capabilities() -> Vec<&'static str> { "host.getRuntime", "share.open", "share.setTarget", + "navigation.openNativePage", "app.openExternalUrl", "app.setTitle", "clipboard.writeText", @@ -166,6 +168,21 @@ fn normalize_external_url(raw_url: &str) -> Option { Some(url.to_string()) } +fn normalize_native_page_url(raw_url: &str) -> Option { + let url = raw_url.trim(); + if url.is_empty() || url.chars().any(char::is_control) { + return None; + } + + let base_url = Url::parse(WEB_APP_ORIGIN).ok()?; + let normalized_url = base_url.join(url).ok()?; + if normalized_url.scheme() != "https" || normalized_url.origin() != base_url.origin() { + return None; + } + + Some(normalized_url) +} + fn normalize_window_title(raw_title: &str) -> Option { let title = raw_title.trim(); if title.is_empty() || title.chars().any(char::is_control) { @@ -179,7 +196,11 @@ fn normalize_export_file_name(raw_file_name: &str) -> String { let mut file_name = String::new(); let mut last_was_space = false; - for character in raw_file_name.trim().chars().take(EXPORT_FILE_NAME_MAX_LENGTH) { + for character in raw_file_name + .trim() + .chars() + .take(EXPORT_FILE_NAME_MAX_LENGTH) + { if character.is_control() || matches!( character, @@ -377,6 +398,29 @@ async fn host_bridge_request( Err(error) => failed(request.id, "host_error", error.to_string()), } } + "navigation.openNativePage" => { + let url = match required_string_payload(&request, "url") + .ok() + .and_then(normalize_native_page_url) + { + Some(url) => url, + None => { + return failed( + request.id, + "invalid_request", + "url must use an allowed same-origin H5 route", + ) + } + }; + + match app.get_webview_window("main") { + Some(window) => match window.navigate(url) { + Ok(()) => ok(request.id, json!(true)), + Err(error) => failed(request.id, "host_error", error.to_string()), + }, + None => failed(request.id, "host_error", "main window not found"), + } + } "clipboard.writeText" => { let text = match required_string_payload(&request, "text") { Ok(text) => text, @@ -530,6 +574,10 @@ mod tests { .as_array() .unwrap() .contains(&json!("share.setTarget"))); + assert!(result["capabilities"] + .as_array() + .unwrap() + .contains(&json!("navigation.openNativePage"))); assert!(result["capabilities"] .as_array() .unwrap() @@ -590,6 +638,39 @@ mod tests { assert_eq!(normalize_external_url("/relative/path"), None); } + #[test] + fn native_page_url_normalization_allows_same_origin_routes() { + assert_eq!( + normalize_native_page_url("/works/detail?work=PZ-1") + .expect("same-origin route") + .as_str(), + "https://app.genarrative.world/works/detail?work=PZ-1" + ); + assert_eq!( + normalize_native_page_url("works/detail?work=PZ-1") + .expect("relative route") + .as_str(), + "https://app.genarrative.world/works/detail?work=PZ-1" + ); + assert_eq!( + normalize_native_page_url("https://app.genarrative.world/works/detail?work=PZ-1") + .expect("absolute same-origin route") + .as_str(), + "https://app.genarrative.world/works/detail?work=PZ-1" + ); + } + + #[test] + fn native_page_url_normalization_rejects_unsafe_routes() { + assert_eq!(normalize_native_page_url("https://example.com/works"), None); + assert_eq!(normalize_native_page_url("//example.com/works"), None); + assert_eq!(normalize_native_page_url("javascript:alert(1)"), None); + assert_eq!( + normalize_native_page_url("https://app.genarrative.world/\nnext"), + None + ); + } + #[test] fn window_title_normalization_requires_visible_text() { assert_eq!( diff --git a/apps/desktop-shell/src-tauri/tauri.conf.json b/apps/desktop-shell/src-tauri/tauri.conf.json index f275cc45..191b9819 100644 --- a/apps/desktop-shell/src-tauri/tauri.conf.json +++ b/apps/desktop-shell/src-tauri/tauri.conf.json @@ -6,7 +6,7 @@ "build": { "beforeDevCommand": "npm --prefix ../.. run dev:web", "beforeBuildCommand": "npm --prefix ../.. run build:raw && npm run typecheck", - "devUrl": "http://127.0.0.1:3000/?clientRuntime=native_app&clientType=native_app&hostShell=tauri_desktop&hostPlatform=unknown&hostVersion=0.1.0&bridgeVersion=1&hostCapabilities=host.getRuntime,share.open,share.setTarget,app.openExternalUrl,app.setTitle,clipboard.writeText,file.exportText", + "devUrl": "http://127.0.0.1:3000/?clientRuntime=native_app&clientType=native_app&hostShell=tauri_desktop&hostPlatform=unknown&hostVersion=0.1.0&bridgeVersion=1&hostCapabilities=host.getRuntime,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,clipboard.writeText,file.exportText", "frontendDist": "../../../dist" }, "app": { @@ -14,7 +14,7 @@ { "create": false, "label": "main", - "url": "index.html?clientRuntime=native_app&clientType=native_app&hostShell=tauri_desktop&hostPlatform=unknown&hostVersion=0.1.0&bridgeVersion=1&hostCapabilities=host.getRuntime,share.open,share.setTarget,app.openExternalUrl,app.setTitle,clipboard.writeText,file.exportText", + "url": "index.html?clientRuntime=native_app&clientType=native_app&hostShell=tauri_desktop&hostPlatform=unknown&hostVersion=0.1.0&bridgeVersion=1&hostCapabilities=host.getRuntime,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,clipboard.writeText,file.exportText", "title": "Genarrative", "width": 1280, "height": 820, diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index e6331353..e970b21d 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -20,7 +20,7 @@ - 背景：后续需要移动端 App 和桌面端 App，但现有主站、固定玩法 runtime、小程序壳和未来 AI H5 sandbox 已经以 H5 为主线；如果移动端重写 React Native UI、桌面端重写 Rust/Tauri UI，会形成玩法、登录、支付、分享和运行态的多套实现。 - 决策：移动端原生壳采用 `Expo + React Native`，桌面端壳采用 `Tauri`。两者都只作为 `native_app` 宿主壳和 HostBridge adapter，不重写现有 React H5 主站，不把固定内置玩法迁到 React Native / Rust UI，也不让 AI 生成 H5 游戏直接访问完整 HostBridge。Expo 壳通过 `react-native-webview` 承接 H5 与 native 通信，Tauri 壳通过受控 command 和 capabilities 承接桌面能力；新增能力必须先进入 HostBridge 契约和测试。 -- 2026-06-17 首轮落地：新增 `packages/shared/src/contracts/hostBridge.ts`、`src/services/host-bridge/nativeAppHostBridge.ts`、`apps/mobile-shell/` 和 `apps/desktop-shell/`。壳只声明并实现真实可用能力；移动壳使用真实品牌图标资产并支持 `genarrative://`、iOS associated domain、Android app link 到同源 H5 路径，`navigation.openNativePage` 只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的原生页面，且通过 `host.events` 注入 `navigation.canGoBack` 返回栈状态事件，`share.setTarget` / `share.open` 解析统一分享目标并调用 React Native 系统分享面板；`app.openExternalUrl` 在 Expo 与 Tauri 两端都只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议；桌面壳已通过 Tauri clipboard-manager 接入 `clipboard.writeText`，并将 `share.setTarget` / `share.open` 实现为复制非空分享文本到系统剪贴板，`app.setTitle` 通过主窗口 API 同步非空窗口标题；桌面 `file.exportText` 通过 Tauri dialog 插件打开系统保存对话框并由 Rust 写入文本文件，但不把 dialog / fs 插件 command 直接暴露给 H5，成功只返回文件名和字节数，用户取消返回 `cancelled`；登录、支付、原生系统分享面板等未接入真实 SDK / 插件前必须返回 unsupported 并让 H5 fallback，生产代码禁止 mock 成功。 +- 2026-06-17 首轮落地：新增 `packages/shared/src/contracts/hostBridge.ts`、`src/services/host-bridge/nativeAppHostBridge.ts`、`apps/mobile-shell/` 和 `apps/desktop-shell/`。壳只声明并实现真实可用能力；移动壳使用真实品牌图标资产并支持 `genarrative://`、iOS associated domain、Android app link 到同源 H5 路径，`navigation.openNativePage` 只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的原生页面，且通过 `host.events` 注入 `navigation.canGoBack` 返回栈状态事件，`share.setTarget` / `share.open` 解析统一分享目标并调用 React Native 系统分享面板；`app.openExternalUrl` 在 Expo 与 Tauri 两端都只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议；桌面壳已通过 Tauri clipboard-manager 接入 `clipboard.writeText`，将 `navigation.openNativePage` 实现为 `https://app.genarrative.world` 同源 H5 route 的主窗口受控跳转，并将 `share.setTarget` / `share.open` 实现为复制非空分享文本到系统剪贴板，`app.setTitle` 通过主窗口 API 同步非空窗口标题；桌面 `file.exportText` 通过 Tauri dialog 插件打开系统保存对话框并由 Rust 写入文本文件，但不把 dialog / fs 插件 command 直接暴露给 H5，成功只返回文件名和字节数，用户取消返回 `cancelled`；登录、支付、原生系统分享面板等未接入真实 SDK / 插件前必须返回 unsupported 并让 H5 fallback，生产代码禁止 mock 成功。 - 影响范围：`src/services/host-bridge/`、未来 `apps/mobile-shell/`、未来 `apps/desktop-shell/`、移动端支付 / 分享 / 深链 / 推送、桌面端系统能力、AI H5 sandbox 的 GameBridge 边界。 - 验证方式：普通浏览器、小程序、Expo 壳、Tauri 壳都能返回正确 `getHostRuntime()`；未支持能力能回退 H5；固定玩法在各宿主中读取同一作品数据和运行态 snapshot；AI sandbox 无法直接调用 HostBridge；Tauri release 不允许任意远端页面调用桌面命令。 - 关联文档：`docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md`、`docs/【前端架构】宿主壳能力统一协议-2026-06-17.md`。 diff --git a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md index a91f163c..4683d337 100644 --- a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md +++ b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md @@ -115,7 +115,7 @@ type HostBridgeEvent = { | `payment.request` | 发起宿主支付 | 依平台策略接入 | 桌面二维码 / 外部浏览器 | | `share.setTarget` | 同步当前作品分享目标 | 支持 | 支持 | | `share.open` | 打开分享动作 | 支持系统分享面板 | 复制分享文本到剪贴板 | -| `navigation.openNativePage` | 打开受控宿主页 | 支持同源 H5 route | 支持设置 / 关于等 | +| `navigation.openNativePage` | 打开受控宿主页 | 支持同源 H5 route | 支持同源 H5 route | | `navigation.canGoBack` | 通知 H5 宿主返回栈状态 | 支持事件 | 不声明 | | `app.openExternalUrl` | 用系统浏览器打开外链 | 支持白名单协议 | 支持白名单协议 | | `app.setTitle` | 同步宿主窗口标题 | 不声明 | 支持 | @@ -252,7 +252,7 @@ GameBridge 禁止： - 实现 runtime、openExternalUrl、clipboard、share fallback、窗口标题同步。 - 验证 macOS / Windows / Linux 至少一条本地 smoke。 -当前状态：已新增 `apps/desktop-shell/`，Tauri dev 直接加载本地主站 Vite，release 打包根 `dist` 主站资产。Rust 侧只把 `host_bridge_request` command 授给主窗口，`app.openExternalUrl` 由 Rust 内部通过 opener 插件执行且只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议，`clipboard.writeText` 由 Rust 内部通过 clipboard-manager 插件写入系统剪贴板，`app.setTitle` 通过 Tauri 主窗口 API 同步窗口标题并拒绝空标题 / 控制字符；不把 opener、clipboard 或 dialog 插件命令直接暴露给前端。当前真实能力为 `host.getRuntime`、`share.setTarget`、`share.open`、`app.openExternalUrl`、`app.setTitle`、`clipboard.writeText` 和 `file.exportText`；其中 `share.open` 会把直接传入的分享 payload 或 `share.setTarget` 缓存的作品目标整理成非空分享文本并写入系统剪贴板，返回 `copied_to_clipboard`；`file.exportText` 通过系统保存对话框让用户选择本地路径，清洗文件名、限制单次文本导出不超过 5 MiB，写入成功后只返回文件名和字节数，不把本机绝对路径暴露给 H5，用户取消时返回 `cancelled`。原生系统分享面板、登录和支付未接入真实插件 / 渠道前不声明支持，不返回 mock 成功。 +当前状态：已新增 `apps/desktop-shell/`，Tauri dev 直接加载本地主站 Vite，release 打包根 `dist` 主站资产。Rust 侧只把 `host_bridge_request` command 授给主窗口，`app.openExternalUrl` 由 Rust 内部通过 opener 插件执行且只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议，`navigation.openNativePage` 只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内受控跳转，`clipboard.writeText` 由 Rust 内部通过 clipboard-manager 插件写入系统剪贴板，`app.setTitle` 通过 Tauri 主窗口 API 同步窗口标题并拒绝空标题 / 控制字符；不把 opener、clipboard 或 dialog 插件命令直接暴露给前端。当前真实能力为 `host.getRuntime`、`share.setTarget`、`share.open`、`navigation.openNativePage`、`app.openExternalUrl`、`app.setTitle`、`clipboard.writeText` 和 `file.exportText`；其中 `share.open` 会把直接传入的分享 payload 或 `share.setTarget` 缓存的作品目标整理成非空分享文本并写入系统剪贴板，返回 `copied_to_clipboard`；`file.exportText` 通过系统保存对话框让用户选择本地路径，清洗文件名、限制单次文本导出不超过 5 MiB，写入成功后只返回文件名和字节数，不把本机绝对路径暴露给 H5，用户取消时返回 `cancelled`。原生系统分享面板、登录和支付未接入真实插件 / 渠道前不声明支持，不返回 mock 成功。 ### Phase 4：宿主能力扩展 diff --git a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md index e029ae2a..9fde3508 100644 --- a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md +++ b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md @@ -44,7 +44,7 @@ AI H5 sandbox - `requestHostPayment()`：微信小程序支付跳转原生支付页；其它渠道返回 `false`，继续走 H5 / Native 二维码。 - `setHostShareTarget()`：把当前公开作品分享目标同步给宿主。 - `openHostShareGrid()`：微信小程序九宫格切图页。 -- `navigateHostNativePage()`：受控跳转宿主页，供订阅授权、支付、登录等 adapter 复用。Expo 移动壳首版只接受同源 H5 route 并切换 WebView URL；真正原生页面、登录和支付能力必须等对应 SDK / 页面接入后再声明支持。 +- `navigateHostNativePage()`：受控跳转宿主页，供订阅授权、支付、登录等 adapter 复用。Expo 移动壳首版只接受同源 H5 route 并切换 WebView URL；Tauri 桌面壳同样只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内跳转。真正原生页面、登录和支付能力必须等对应 SDK / 页面接入后再声明支持。 - `exportHostTextFile()`：原生 App 宿主的受控文本导出入口。Tauri 桌面壳通过 `file.exportText` 打开系统保存对话框并写入用户选择的文件；文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数。Expo 移动壳当前不声明本地文件导出能力，误调时返回 unsupported，由 H5 浏览器下载或后续真实原生文档能力承接。 ## 迁移顺序