接入原生壳页面刷新能力

新增 app.reloadWebView HostBridge 契约和 H5 facade 移动端通过 react-native-webview reload 刷新当前 WebView 桌面端通过 Tauri WebviewWindow reload 刷新主窗口更新壳能力检查、测试、方案文档和共享决策记录
2026-06-18 05:07:01 +08:00
parent 1c6749b53e
commit 51dcff6d16
14 changed files with 87 additions and 4 deletions
--- a/apps/desktop-shell/scripts/check-config.mjs
+++ b/apps/desktop-shell/scripts/check-config.mjs
@@ -140,6 +140,7 @@ const requiredMainSnippets = [
  '"share.open"',
  '"share.setTarget"',
  '"navigation.openNativePage"',
+  '"app.reloadWebView"',
  '"app.setTitle"',
  '"app.setBadgeCount"',
  '"clipboard.writeText"',
@@ -162,6 +163,7 @@ const requiredMainSnippets = [
  'import_image_file_payload',
  'set_title',
  'set_badge_count',
+  'window.reload()',
  'read_text()',
  'normalize_clipboard_text',
  'window.theme()',
--- a/apps/desktop-shell/src-tauri/src/main.rs
+++ b/apps/desktop-shell/src-tauri/src/main.rs
@@ -97,6 +97,7 @@ fn capabilities() -> Vec<&'static str> {
        "share.open",
        "share.setTarget",
        "navigation.openNativePage",
+        "app.reloadWebView",
        "app.openExternalUrl",
        "app.setTitle",
        "app.setBadgeCount",
@@ -904,6 +905,13 @@ async fn host_bridge_request(
                None => failed(request.id, "host_error", "main window not found"),
            }
        }
+        "app.reloadWebView" => match app.get_webview_window("main") {
+            Some(window) => match window.reload() {
+                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,
@@ -1208,6 +1216,10 @@ mod tests {
            .as_array()
            .unwrap()
            .contains(&json!("navigation.openNativePage")));
+        assert!(result["capabilities"]
+            .as_array()
+            .unwrap()
+            .contains(&json!("app.reloadWebView")));
        assert!(result["capabilities"]
            .as_array()
            .unwrap()
--- 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,appearance.getColorScheme,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,network.status,network.statusChanged,clipboard.writeText,clipboard.readText,file.exportText,file.importText,file.exportImage,file.importImage,file.imageDropped,notification.showLocal",
+    "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,appearance.getColorScheme,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.reloadWebView,app.openExternalUrl,app.setTitle,app.setBadgeCount,network.status,network.statusChanged,clipboard.writeText,clipboard.readText,file.exportText,file.importText,file.exportImage,file.importImage,file.imageDropped,notification.showLocal",
    "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,appearance.getColorScheme,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,network.status,network.statusChanged,clipboard.writeText,clipboard.readText,file.exportText,file.importText,file.exportImage,file.importImage,file.imageDropped,notification.showLocal",
+        "url": "index.html?clientRuntime=native_app&clientType=native_app&hostShell=tauri_desktop&hostPlatform=unknown&hostVersion=0.1.0&bridgeVersion=1&hostCapabilities=host.getRuntime,appearance.getColorScheme,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.reloadWebView,app.openExternalUrl,app.setTitle,app.setBadgeCount,network.status,network.statusChanged,clipboard.writeText,clipboard.readText,file.exportText,file.importText,file.exportImage,file.importImage,file.imageDropped,notification.showLocal",
        "title": "Genarrative",
        "width": 1280,
        "height": 820,
--- a/apps/mobile-shell/App.tsx
+++ b/apps/mobile-shell/App.tsx
@@ -58,6 +58,9 @@ export default function App() {
      openWebViewUrl(url) {
        setWebUrl(url);
      },
+      reloadWebView() {
+        webViewRef.current?.reload();
+      },
    });

    return () => configureMobileHostBridgeNavigation(null);
--- a/apps/mobile-shell/scripts/check-config.mjs
+++ b/apps/mobile-shell/scripts/check-config.mjs
@@ -117,6 +117,7 @@ for (const snippet of [
  "Linking.addEventListener('url'",
  'buildMobileShellUrlFromDeepLink',
  'configureMobileHostBridgeNavigation',
+  'webViewRef.current?.reload()',
  'AppState.addEventListener',
  'app.lifecycle',
  'network.statusChanged',
@@ -184,6 +185,7 @@ for (const snippet of [
  'clipboard.readText',
  'notification.showLocal',
  'network.status',
+  'app.reloadWebView',
  'getMobileNetworkStatus',
  'Notifications.scheduleNotificationAsync',
  'Notifications.setNotificationChannelAsync',
@@ -222,6 +224,7 @@ for (const capability of [
  'network.statusChanged',
  'navigation.openNativePage',
  'navigation.canGoBack',
+  'app.reloadWebView',
  'app.openExternalUrl',
  'clipboard.writeText',
  'clipboard.readText',
--- a/apps/mobile-shell/src/mobileHostBridge.test.ts
+++ b/apps/mobile-shell/src/mobileHostBridge.test.ts
@@ -293,6 +293,7 @@ describe('handleMobileHostBridgeMessage', () => {
        'appearance.getColorScheme',
        'host.events',
        'app.lifecycle',
+        'app.reloadWebView',
        'network.status',
        'network.statusChanged',
        'navigation.canGoBack',
@@ -343,6 +344,7 @@ describe('handleMobileHostBridgeMessage', () => {
    configureMobileHostBridgeNavigation({
      allowedOrigin: 'https://app.genarrative.world',
      openWebViewUrl,
+      reloadWebView: vi.fn(),
    });

    const response = await send(
@@ -361,6 +363,7 @@ describe('handleMobileHostBridgeMessage', () => {
    configureMobileHostBridgeNavigation({
      allowedOrigin: 'https://app.genarrative.world',
      openWebViewUrl: vi.fn(),
+      reloadWebView: vi.fn(),
    });

    const response = await send(
@@ -386,6 +389,20 @@ describe('handleMobileHostBridgeMessage', () => {
    expect(failedResponse.error.code).toBe('unsupported_method');
  });

+  test('app.reloadWebView 刷新移动壳当前 WebView', async () => {
+    const reloadWebView = vi.fn();
+    configureMobileHostBridgeNavigation({
+      allowedOrigin: 'https://app.genarrative.world',
+      openWebViewUrl: vi.fn(),
+      reloadWebView,
+    });
+
+    const response = await send(request('app.reloadWebView'));
+
+    expectOk(response);
+    expect(reloadWebView).toHaveBeenCalledTimes(1);
+  });
+
  test('app.openExternalUrl 只打开允许的外链协议', async () => {
    const response = await send(
      request('app.openExternalUrl', {
--- a/apps/mobile-shell/src/mobileHostBridge.ts
+++ b/apps/mobile-shell/src/mobileHostBridge.ts
@@ -82,6 +82,7 @@ export const MOBILE_HOST_CAPABILITIES: HostBridgeCapability[] = [
  'share.setTarget',
  'navigation.openNativePage',
  'navigation.canGoBack',
+  'app.reloadWebView',
  'app.openExternalUrl',
  'network.status',
  'network.statusChanged',
@@ -109,6 +110,7 @@ export function resolveMobileHostCapabilities(platform = Platform.OS) {
 export type MobileHostBridgeNavigation = {
  allowedOrigin: string;
  openWebViewUrl: (url: string) => void;
+  reloadWebView: () => void;
 };

 let currentShareTarget: unknown = null;
@@ -692,6 +694,15 @@ function openNativePage(payload: unknown) {
  return true;
 }

+function reloadWebView() {
+  if (!navigation) {
+    throw unsupported('app.reloadWebView');
+  }
+
+  navigation.reloadWebView();
+  return true;
+}
+
 async function handleRequest(request: HostBridgeRequest) {
  switch (request.method) {
    case 'host.getRuntime':
@@ -706,6 +717,8 @@ async function handleRequest(request: HostBridgeRequest) {
      return ok(request, getColorScheme());
    case 'app.openExternalUrl':
      return ok(request, await openExternalUrl(request.payload));
+    case 'app.reloadWebView':
+      return ok(request, reloadWebView());
    case 'network.status':
      return ok(request, await getMobileNetworkStatus());
    case 'clipboard.writeText':
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -2283,3 +2283,10 @@
 - 影响范围：`api-server` 资产计费包裹、钱包退款补偿、拼图首图后台生成、`spacetime-module` 拼图 task 表、`spacetime-client` bindings/facade、前端 API request id 复用和后端架构文档。
 - 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run check:spacetime-runtime-access`、`node scripts/check-server-rs-ddd-boundaries.mjs`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml wallet_refund_outbox`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml asset_operation`、`npm run test -- src/services/apiClient.test.ts`、`npm run check:encoding`。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-06-18 原生壳 WebView 刷新能力只保留受控当前页刷新
+
+- 背景：Expo 移动壳和 Tauri 桌面壳都需要一个真实的宿主级刷新入口，供 H5 在检测到资源、登录态或运行态需要重新载入时请求宿主刷新当前容器；该能力不能演变成任意 URL 导航或原生 WebView ref 透传。
+- 决策：新增 HostBridge method `app.reloadWebView` 和 H5 facade `reloadHostWebView()`。移动端只调用当前 `react-native-webview` 的 `reload()`，桌面端只调用 Tauri 主 `WebviewWindow.reload()`；该 method 不接受 payload，成功只表示宿主已发起刷新，刷新后当前 H5 上下文会卸载。继续把同源跳转留给 `navigation.openNativePage`，外链离开容器留给 `app.openExternalUrl`。
+- 影响范围：`packages/shared/src/contracts/hostBridge.ts`、`src/services/host-bridge/hostBridge.ts`、`apps/mobile-shell/`、`apps/desktop-shell/`、原生壳能力检查脚本和 HostBridge 架构文档。
+- 验证方式：`npm run check:native-shells`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
--- a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md
+++ b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md
@@ -117,6 +117,7 @@ type HostBridgeEvent = {
 | `share.setTarget` | 同步当前作品分享目标 | 支持 | 支持 |
 | `share.open` | 打开分享动作 | 支持系统分享面板 | 复制分享文本到剪贴板 |
 | `navigation.openNativePage` | 打开受控宿主页 | 支持同源 H5 route | 支持同源 H5 route |
+| `app.reloadWebView` | 受控刷新当前 WebView | 支持 WebView reload | 支持主窗口 reload |
 | `app.lifecycle` | 通知 H5 宿主前后台 / 焦点状态 | 支持 AppState 事件 | 支持窗口 focus / blur 事件 |
 | `navigation.canGoBack` | 通知 H5 宿主返回栈状态 | 支持事件 | 不声明 |
 | `app.openExternalUrl` | 用系统浏览器打开外链 | 支持白名单协议 | 支持白名单协议 |
@@ -252,7 +253,7 @@ GameBridge 禁止：
 - iOS / Android 深链打开作品详情、创作页和邀请码。
 - 登录和支付先 fallback 到 H5；只把能力边界跑通。

-当前状态：已新增 `apps/mobile-shell/`，通过 Expo development build 运行，`react-native-webview` 加载 H5 URL 并附加 `native_app` 宿主 query。移动壳使用真实品牌图标资产，已接入 `genarrative://` scheme、iOS associated domain 和 Android app link filter，启动和运行时 deep link 只会映射到同源 H5 路径并继续附加 HostBridge 上下文，外域和危险协议回退到默认主站入口。首轮真实能力包括 `host.getRuntime`、`appearance.getColorScheme`、`host.events`、`app.lifecycle`、`network.status`、`network.statusChanged`、`share.open`、`share.setTarget`、`navigation.openNativePage`、`navigation.canGoBack`、`app.openExternalUrl`、`clipboard.writeText`、`clipboard.readText`、`file.exportText`、`file.exportImage`、`file.importImage`、`haptics.impact`、`notification.showLocal` 和 Android 返回键回退；其中 `appearance.getColorScheme` 只读系统配色偏好，不强改 H5 或系统主题；`app.lifecycle` 通过 React Native `AppState` 注入 `active` / `inactive` / `background` 统一状态，供 H5 游戏循环、音频和轮询做真实暂停 / 恢复判断，H5 的 `useHostLifecycleActive()` 会把该事件归一成运行态可播放状态，WebAudio 背景音乐和拼图、抓大鹅等固定玩法 `<audio>` 背景音乐都按该状态在宿主进后台时暂停、回到前台且原播放条件仍满足时恢复；`network.status` / `network.statusChanged` 通过 `expo-network` 查询并订阅真实系统网络状态，供 H5 游戏运行态和生成页识别离线 / 弱网回退；iOS 额外声明 `app.setBadgeCount`，通过 React Native `PushNotificationIOS` 设置应用图标角标，Android 不声明该能力。H5 会解析并过滤 `hostCapabilities`，也会在主 App 启动时通过真实 `host.getRuntime` 回读并缓存能力，只对声明或回读到的能力展示入口或调用宿主能力；其中 `share.setTarget` / `share.open` 会解析统一分享目标里的 `title`、`message`、`url`、`work`、`path` 或 `targetPath` 并调用 React Native 系统分享面板；发布分享弹窗只有在宿主声明 `share.open` 时才提供“系统分享”动作，失败时保留复制链接回退路径；`navigation.openNativePage` 在 Expo 壳内只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的登录、支付或其它原生页面，`navigation.canGoBack` 由 WebView 导航状态变化实时注入 H5，WebView 自身拦截到外域导航时只会把 `http:`、`https:`、`mailto:`、`tel:` 交给系统，危险协议直接阻断；`app.openExternalUrl` 也只允许同一协议白名单，ICP备案号和资产调试原图等 H5 外链入口在 `native_app` 中优先通过该能力离开 WebView 并交给系统浏览器；`clipboard.writeText` 由 H5 复制服务优先调用并写入系统剪贴板；`clipboard.readText` 通过 Expo Clipboard 读取纯文本剪贴板并按 100000 字符上限返回，不读取图片、HTML 或监听剪贴板变化；`file.exportText` 通过 Expo 文件系统写入缓存文本文件，再交给系统分享 / 保存面板，文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数；`file.exportImage` 通过 Expo 文件系统写入缓存图片，再交给系统分享 / 保存面板，H5 只传允许 MIME 的 base64 图片数据，单次不超过 5 MiB，分享卡下载会优先走该能力；`file.importImage` 通过 Expo ImagePicker 请求相册权限并打开系统相册选择器，只接受 `image/png` / `image/jpeg` / `image/webp`、单次不超过 10 MiB，成功只返回清洗后的文件名、MIME、base64 内容和字节数，不把设备本地 URI 暴露给 H5，用户取消返回 `cancelled` 并由 H5 视作无选择；通用创作图片输入面板 `CreativeImageInputPanel` 在原生壳声明 `file.importImage` 时会优先调用该宿主能力，并把导入结果转换为现有 `File` 上传回调，拼图、拼消消、敲木鱼等复用该面板的主图和描述参考图选择无需新增玩法分叉；`haptics.impact` 通过 Expo Haptics 承接运行时轻触反馈，H5 在宿主不支持时回退到浏览器 vibration；`notification.showLocal` 通过 `expo-notifications` 请求系统通知权限并调度即时本地通知，Android 只使用固定本地 channel，不启用后台远程通知、远程推送 token 或定时提醒。登录和支付尚未接入渠道 SDK / 原生页面时明确返回 unsupported，让 H5 fallback 承接。
+当前状态：已新增 `apps/mobile-shell/`，通过 Expo development build 运行，`react-native-webview` 加载 H5 URL 并附加 `native_app` 宿主 query。移动壳使用真实品牌图标资产，已接入 `genarrative://` scheme、iOS associated domain 和 Android app link filter，启动和运行时 deep link 只会映射到同源 H5 路径并继续附加 HostBridge 上下文，外域和危险协议回退到默认主站入口。首轮真实能力包括 `host.getRuntime`、`appearance.getColorScheme`、`host.events`、`app.lifecycle`、`network.status`、`network.statusChanged`、`share.open`、`share.setTarget`、`navigation.openNativePage`、`navigation.canGoBack`、`app.reloadWebView`、`app.openExternalUrl`、`clipboard.writeText`、`clipboard.readText`、`file.exportText`、`file.exportImage`、`file.importImage`、`haptics.impact`、`notification.showLocal` 和 Android 返回键回退；其中 `appearance.getColorScheme` 只读系统配色偏好，不强改 H5 或系统主题；`app.lifecycle` 通过 React Native `AppState` 注入 `active` / `inactive` / `background` 统一状态，供 H5 游戏循环、音频和轮询做真实暂停 / 恢复判断，H5 的 `useHostLifecycleActive()` 会把该事件归一成运行态可播放状态，WebAudio 背景音乐和拼图、抓大鹅等固定玩法 `<audio>` 背景音乐都按该状态在宿主进后台时暂停、回到前台且原播放条件仍满足时恢复；`network.status` / `network.statusChanged` 通过 `expo-network` 查询并订阅真实系统网络状态，供 H5 游戏运行态和生成页识别离线 / 弱网回退；iOS 额外声明 `app.setBadgeCount`，通过 React Native `PushNotificationIOS` 设置应用图标角标，Android 不声明该能力。H5 会解析并过滤 `hostCapabilities`，也会在主 App 启动时通过真实 `host.getRuntime` 回读并缓存能力，只对声明或回读到的能力展示入口或调用宿主能力；其中 `share.setTarget` / `share.open` 会解析统一分享目标里的 `title`、`message`、`url`、`work`、`path` 或 `targetPath` 并调用 React Native 系统分享面板；发布分享弹窗只有在宿主声明 `share.open` 时才提供“系统分享”动作，失败时保留复制链接回退路径；`navigation.openNativePage` 在 Expo 壳内只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的登录、支付或其它原生页面，`navigation.canGoBack` 由 WebView 导航状态变化实时注入 H5，`app.reloadWebView` 只调用当前 `react-native-webview` 的 `reload()` 刷新内嵌 H5，不开放任意脚本执行或 URL 重写；WebView 自身拦截到外域导航时只会把 `http:`、`https:`、`mailto:`、`tel:` 交给系统，危险协议直接阻断；`app.openExternalUrl` 也只允许同一协议白名单，ICP备案号和资产调试原图等 H5 外链入口在 `native_app` 中优先通过该能力离开 WebView 并交给系统浏览器；`clipboard.writeText` 由 H5 复制服务优先调用并写入系统剪贴板；`clipboard.readText` 通过 Expo Clipboard 读取纯文本剪贴板并按 100000 字符上限返回，不读取图片、HTML 或监听剪贴板变化；`file.exportText` 通过 Expo 文件系统写入缓存文本文件，再交给系统分享 / 保存面板，文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数；`file.exportImage` 通过 Expo 文件系统写入缓存图片，再交给系统分享 / 保存面板，H5 只传允许 MIME 的 base64 图片数据，单次不超过 5 MiB，分享卡下载会优先走该能力；`file.importImage` 通过 Expo ImagePicker 请求相册权限并打开系统相册选择器，只接受 `image/png` / `image/jpeg` / `image/webp`、单次不超过 10 MiB，成功只返回清洗后的文件名、MIME、base64 内容和字节数，不把设备本地 URI 暴露给 H5，用户取消返回 `cancelled` 并由 H5 视作无选择；通用创作图片输入面板 `CreativeImageInputPanel` 在原生壳声明 `file.importImage` 时会优先调用该宿主能力，并把导入结果转换为现有 `File` 上传回调，拼图、拼消消、敲木鱼等复用该面板的主图和描述参考图选择无需新增玩法分叉；`haptics.impact` 通过 Expo Haptics 承接运行时轻触反馈，H5 在宿主不支持时回退到浏览器 vibration；`notification.showLocal` 通过 `expo-notifications` 请求系统通知权限并调度即时本地通知，Android 只使用固定本地 channel，不启用后台远程通知、远程推送 token 或定时提醒。登录和支付尚未接入渠道 SDK / 原生页面时明确返回 unsupported，让 H5 fallback 承接。

 2026-06-18 追加：移动壳声明并实现 `file.importText`，通过 Expo DocumentPicker 打开系统文档选择器，只接受 `text/plain`、`text/markdown`、`text/csv`、`application/json` 或对应扩展名，单次不超过 5 MiB；成功只返回清洗后的文件名、MIME、UTF-8 文本内容和字节数，不暴露设备本地 URI，也不开放通用文件系统。

@@ -265,7 +266,7 @@ GameBridge 禁止：
 - 实现 runtime、openExternalUrl、clipboard、share fallback、窗口标题同步。
 - 验证 macOS / Windows / Linux 至少一条本地 smoke。

-当前状态：已新增 `apps/desktop-shell/`，Tauri dev 直接加载本地主站 Vite，release 打包根 `dist` 主站资产。Rust 侧只把 `host_bridge_request` command 授给主窗口，`appearance.getColorScheme` 由 Rust 内部读取主窗口 `theme()` 并返回 `light` / `dark` / `unknown`，不设置或覆盖系统主题；`app.lifecycle` 由主窗口 focus / blur 事件注入 `active` / `inactive` 统一状态，不开放 Tauri event 插件给前端，H5 通过 `useHostLifecycleActive()` 统一归一窗口焦点状态，WebAudio 背景音乐和拼图、抓大鹅等固定玩法 `<audio>` 背景音乐都会在窗口失焦时暂停、恢复焦点且原播放条件仍满足时恢复；`network.status` 由 Rust 对 `app.genarrative.world:443` 做短超时 TCP 可达性查询，`network.statusChanged` 由主 WebView 的 `online` / `offline` 事件注入，不开放任意网络探测给 H5；`app.openExternalUrl` 由 Rust 内部通过 opener 插件执行且只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议，ICP备案号和资产调试原图等 H5 外链入口在 `native_app` 中优先通过该能力离开主窗口并交给系统浏览器；`navigation.openNativePage` 只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内受控跳转，`clipboard.writeText` 由 Rust 内部通过 clipboard-manager 插件写入系统剪贴板并由 H5 复制服务优先调用，`clipboard.readText` 由 Rust 内部通过同一插件读取纯文本剪贴板并按 100000 字符上限返回，不开放剪贴板插件 JS guest API、图片读取、HTML 读取或监听事件，`app.setTitle` 通过 Tauri 主窗口 API 同步窗口标题并拒绝空标题 / 控制字符，`app.setBadgeCount` 通过主窗口 `set_badge_count` 设置任务栏角标，数量只接受 `0-99999` 整数且 `0` 表示清除；H5 主站会按当前平台阶段先更新 `document.title`，再通过 `app.setTitle` 把同一标题同步给 Tauri 窗口，Expo 移动壳不声明该能力时静默忽略；不把 opener、clipboard、dialog 或 notification 插件命令直接暴露给前端。当前真实能力为 `host.getRuntime`、`appearance.getColorScheme`、`app.lifecycle`、`network.status`、`network.statusChanged`、`share.setTarget`、`share.open`、`navigation.openNativePage`、`app.openExternalUrl`、`app.setTitle`、`app.setBadgeCount`、`clipboard.writeText`、`clipboard.readText`、`file.exportText`、`file.exportImage`、`file.importImage`、`file.imageDropped` 和 `notification.showLocal`；H5 会在主 App 启动时通过真实 `host.getRuntime` 回读并缓存这些能力，即使入口 URL 缺少 `hostCapabilities`，也只按宿主真实回包开启能力入口；其中 `share.open` 会把直接传入的分享 payload 或 `share.setTarget` 缓存的作品目标整理成非空分享文本并写入系统剪贴板，返回 `copied_to_clipboard`，发布分享弹窗在桌面壳中也通过该能力提供“系统分享”动作；`file.exportText` 通过系统保存对话框让用户选择本地路径，清洗文件名、限制单次文本导出不超过 5 MiB，写入成功后只返回文件名和字节数，不把本机绝对路径暴露给 H5，用户取消返回 `cancelled`；`file.exportImage` 同样通过系统保存对话框写入 H5 生成的图片字节，只接受 `image/png` / `image/jpeg` / `image/webp` base64 数据，单次不超过 5 MiB，分享卡下载会优先走该能力，用户取消返回 `cancelled`；`file.importImage` 通过系统选择框读取用户选择的图片，`file.imageDropped` 通过主窗口拖拽事件读取用户拖入的图片，二者都只接受 `image/png` / `image/jpeg` / `image/webp`、单次不超过 10 MiB，成功只返回文件名、MIME、base64 内容和字节数，不把本机绝对路径暴露给 H5，也不开放通用文件系统；`notification.showLocal` 由 Rust 内部通过 `tauri-plugin-notification` 发送即时系统通知，只接受清洗后的标题和正文，不开放插件 JS guest API、远程推送、定时提醒或通知 token；通用创作图片输入面板 `CreativeImageInputPanel` 在桌面壳声明 `file.importImage` 时会优先打开系统图片选择框，在同时声明 `file.imageDropped` 时会按宿主拖入坐标把图片交给命中的主图槽位，并把结果转换为现有 `File` 上传回调，普通浏览器、小程序和未声明能力的壳继续保留原文件输入路径。原生系统分享面板、登录和支付未接入真实插件 / 渠道前不声明支持，不返回 mock 成功。
+当前状态：已新增 `apps/desktop-shell/`，Tauri dev 直接加载本地主站 Vite，release 打包根 `dist` 主站资产。Rust 侧只把 `host_bridge_request` command 授给主窗口，`appearance.getColorScheme` 由 Rust 内部读取主窗口 `theme()` 并返回 `light` / `dark` / `unknown`，不设置或覆盖系统主题；`app.lifecycle` 由主窗口 focus / blur 事件注入 `active` / `inactive` 统一状态，不开放 Tauri event 插件给前端，H5 通过 `useHostLifecycleActive()` 统一归一窗口焦点状态，WebAudio 背景音乐和拼图、抓大鹅等固定玩法 `<audio>` 背景音乐都会在窗口失焦时暂停、恢复焦点且原播放条件仍满足时恢复；`network.status` 由 Rust 对 `app.genarrative.world:443` 做短超时 TCP 可达性查询，`network.statusChanged` 由主 WebView 的 `online` / `offline` 事件注入，不开放任意网络探测给 H5；`app.openExternalUrl` 由 Rust 内部通过 opener 插件执行且只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议，ICP备案号和资产调试原图等 H5 外链入口在 `native_app` 中优先通过该能力离开主窗口并交给系统浏览器；`navigation.openNativePage` 只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内受控跳转，`app.reloadWebView` 只调用 Tauri 主 WebViewWindow 的 `reload()` 刷新当前 H5，不开放 JS guest API、任意命令或任意 URL 导航，`clipboard.writeText` 由 Rust 内部通过 clipboard-manager 插件写入系统剪贴板并由 H5 复制服务优先调用，`clipboard.readText` 由 Rust 内部通过同一插件读取纯文本剪贴板并按 100000 字符上限返回，不开放剪贴板插件 JS guest API、图片读取、HTML 读取或监听事件，`app.setTitle` 通过 Tauri 主窗口 API 同步窗口标题并拒绝空标题 / 控制字符，`app.setBadgeCount` 通过主窗口 `set_badge_count` 设置任务栏角标，数量只接受 `0-99999` 整数且 `0` 表示清除；H5 主站会按当前平台阶段先更新 `document.title`，再通过 `app.setTitle` 把同一标题同步给 Tauri 窗口，Expo 移动壳不声明该能力时静默忽略；不把 opener、clipboard、dialog 或 notification 插件命令直接暴露给前端。当前真实能力为 `host.getRuntime`、`appearance.getColorScheme`、`app.lifecycle`、`network.status`、`network.statusChanged`、`share.setTarget`、`share.open`、`navigation.openNativePage`、`app.reloadWebView`、`app.openExternalUrl`、`app.setTitle`、`app.setBadgeCount`、`clipboard.writeText`、`clipboard.readText`、`file.exportText`、`file.exportImage`、`file.importImage`、`file.imageDropped` 和 `notification.showLocal`；H5 会在主 App 启动时通过真实 `host.getRuntime` 回读并缓存这些能力，即使入口 URL 缺少 `hostCapabilities`，也只按宿主真实回包开启能力入口；其中 `share.open` 会把直接传入的分享 payload 或 `share.setTarget` 缓存的作品目标整理成非空分享文本并写入系统剪贴板，返回 `copied_to_clipboard`，发布分享弹窗在桌面壳中也通过该能力提供“系统分享”动作；`file.exportText` 通过系统保存对话框让用户选择本地路径，清洗文件名、限制单次文本导出不超过 5 MiB，写入成功后只返回文件名和字节数，不把本机绝对路径暴露给 H5，用户取消返回 `cancelled`；`file.exportImage` 同样通过系统保存对话框写入 H5 生成的图片字节，只接受 `image/png` / `image/jpeg` / `image/webp` base64 数据，单次不超过 5 MiB，分享卡下载会优先走该能力，用户取消返回 `cancelled`；`file.importImage` 通过系统选择框读取用户选择的图片，`file.imageDropped` 通过主窗口拖拽事件读取用户拖入的图片，二者都只接受 `image/png` / `image/jpeg` / `image/webp`、单次不超过 10 MiB，成功只返回文件名、MIME、base64 内容和字节数，不把本机绝对路径暴露给 H5，也不开放通用文件系统；`notification.showLocal` 由 Rust 内部通过 `tauri-plugin-notification` 发送即时系统通知，只接受清洗后的标题和正文，不开放插件 JS guest API、远程推送、定时提醒或通知 token；通用创作图片输入面板 `CreativeImageInputPanel` 在桌面壳声明 `file.importImage` 时会优先打开系统图片选择框，在同时声明 `file.imageDropped` 时会按宿主拖入坐标把图片交给命中的主图槽位，并把结果转换为现有 `File` 上传回调，普通浏览器、小程序和未声明能力的壳继续保留原文件输入路径。原生系统分享面板、登录和支付未接入真实插件 / 渠道前不声明支持，不返回 mock 成功。

 2026-06-18 追加：桌面壳声明并实现 `file.importText`，通过系统文件选择框读取用户选择的文本文件，只接受 `text/plain`、`text/markdown`、`text/csv`、`application/json` 对应扩展名，单次不超过 5 MiB；成功只返回清洗后的文件名、MIME、UTF-8 文本内容和字节数，不暴露本机绝对路径，也不开放通用文件系统。

--- a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md
+++ b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md
@@ -54,6 +54,7 @@ AI H5 sandbox
 - `showHostLocalNotification()`：原生 App 宿主的受控即时本地通知入口。H5 只能传必填 `title` 和可选 `body`，两者都会去除首尾空白、折叠普通空白、限制长度并拒绝控制字符；Expo 移动壳通过 `expo-notifications` 请求通知权限、创建 Android 本地通知 channel 并立刻调度本地通知，Tauri 桌面壳通过 Rust 侧 `tauri-plugin-notification` 发送系统通知。该能力不包含远程推送、token 注册、定时提醒、后台远程通知或任意通知插件透传，宿主未声明、权限拒绝或系统失败时由 H5 视作失败并继续主流程。
 - `setHostAppTitle()`：原生 App 宿主的受控窗口标题入口。H5 主站会按当前平台阶段先同步 `document.title`，再通过 `app.setTitle` 请求宿主窗口标题同步；Tauri 桌面壳支持该能力，Expo 移动壳不声明时静默忽略。
 - `setHostAppBadgeCount()`：原生 App 宿主的受控应用角标入口。H5 只传 `0-99999` 的整数，`0` 表示清除角标；Expo 移动壳只在 iOS 声明 `app.setBadgeCount` 并通过 React Native `PushNotificationIOS` 设置应用图标角标，Android 不声明该能力；Tauri 桌面壳通过主窗口 `set_badge_count` 设置任务栏角标，底层平台不支持时返回明确错误，由 H5 视作失败并继续主流程。
+- `reloadHostWebView()`：原生 App 宿主的受控 WebView 刷新入口。H5 只能请求刷新当前承载主站的宿主 WebView；Expo 移动壳调用当前 `react-native-webview` 的 `reload()`，Tauri 桌面壳调用主 `WebviewWindow.reload()`。该能力不接受 payload，不开放任意 URL 导航、脚本执行、Tauri guest API 或 RN WebView ref；成功只表示宿主已发起刷新，刷新后当前 H5 上下文会卸载。
 - `openHostExternalUrl()`：原生 App 宿主的受控外链入口。H5 中需要离开主站的外链在 `native_app` 下先通过 `app.openExternalUrl` 请求宿主系统浏览器打开；只允许 `http:`、`https:`、`mailto:`、`tel:`，相对路径会先归一化到当前站点绝对 URL。宿主不可用或拒绝时回退浏览器外链行为，普通浏览器和小程序保持原有 `<a>` 语义。
 - `navigateHostNativePage()`：受控跳转宿主页，供订阅授权、支付、登录等 adapter 复用。Expo 移动壳首版只接受同源 H5 route 并切换 WebView URL；Tauri 桌面壳同样只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内跳转。真正原生页面、登录和支付能力必须等对应 SDK / 页面接入后再声明支持。
 - `exportHostTextFile()`：原生 App 宿主的受控文本导出入口。Expo 移动壳通过 `file.exportText` 写入缓存文本文件并交给系统分享 / 保存面板；Tauri 桌面壳通过 `file.exportText` 打开系统保存对话框并写入用户选择的文件。文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数，不把本机绝对路径暴露给 H5；系统分享不可用或用户取消时返回明确错误，由 H5 fallback 承接。
--- a/packages/shared/src/contracts/hostBridge.test.ts
+++ b/packages/shared/src/contracts/hostBridge.test.ts
@@ -53,6 +53,7 @@ describe('HostBridge shared contract helpers', () => {
  test('识别 HostBridge 能力白名单', () => {
    expect(isHostBridgeCapability('appearance.getColorScheme')).toBe(true);
    expect(isHostBridgeCapability('share.open')).toBe(true);
+    expect(isHostBridgeCapability('app.reloadWebView')).toBe(true);
    expect(isHostBridgeCapability('app.lifecycle')).toBe(true);
    expect(isHostBridgeCapability('network.status')).toBe(true);
    expect(isHostBridgeCapability('network.statusChanged')).toBe(true);
--- a/packages/shared/src/contracts/hostBridge.ts
+++ b/packages/shared/src/contracts/hostBridge.ts
@@ -21,6 +21,7 @@ export const HOST_BRIDGE_METHODS = [
  'share.setTarget',
  'share.open',
  'navigation.openNativePage',
+  'app.reloadWebView',
  'app.openExternalUrl',
  'app.setTitle',
  'app.setBadgeCount',
--- a/src/services/host-bridge/hostBridge.test.ts
+++ b/src/services/host-bridge/hostBridge.test.ts
@@ -23,6 +23,7 @@ import {
  postWechatMiniProgramMessage,
  readHostClipboardText,
  refreshNativeAppHostRuntime,
+  reloadHostWebView,
  requestHostHapticsImpact,
  requestHostLogin,
  requestHostPayment,
@@ -632,6 +633,7 @@ describe('hostBridge', () => {
        'clipboard.writeText',
        'haptics.impact',
        'app.openExternalUrl',
+        'app.reloadWebView',
        'app.setTitle',
        'app.setBadgeCount',
        'network.status',
@@ -676,6 +678,7 @@ describe('hostBridge', () => {
    await expect(
      openHostExternalUrl({ url: '/works/detail?work=PZ-1' }),
    ).resolves.toBe(true);
+    await expect(reloadHostWebView()).resolves.toBe(true);
    await expect(setHostAppTitle({ title: ' 拼图 - 陶泥儿 ' })).resolves.toBe(
      true,
    );
@@ -775,6 +778,11 @@ describe('hostBridge', () => {
        },
      }),
    });
+    expect(invoke).toHaveBeenCalledWith('host_bridge_request', {
+      request: expect.objectContaining({
+        method: 'app.reloadWebView',
+      }),
+    });
    expect(invoke).toHaveBeenCalledWith('host_bridge_request', {
      request: expect.objectContaining({
        method: 'app.setTitle',
@@ -882,6 +890,7 @@ describe('hostBridge', () => {
    await expect(
      openHostExternalUrl({ url: 'javascript:alert(1)' }),
    ).resolves.toBe(false);
+    await expect(reloadHostWebView()).resolves.toBe(false);
    await expect(setHostAppTitle({ title: '拼图 - 陶泥儿' })).resolves.toBe(
      false,
    );
@@ -916,6 +925,7 @@ describe('hostBridge', () => {
  test('普通浏览器不处理宿主文件导出', async () => {
    await expect(getHostAppearanceColorScheme()).resolves.toBe(false);
    await expect(readHostClipboardText()).resolves.toBe(false);
+    await expect(reloadHostWebView()).resolves.toBe(false);
    await expect(
      exportHostTextFile({
        fileName: '作品记录.txt',
--- a/src/services/host-bridge/hostBridge.ts
+++ b/src/services/host-bridge/hostBridge.ts
@@ -642,6 +642,18 @@ export async function openHostExternalUrl({ url }: HostExternalUrlRequest) {
  }
 }

+export async function reloadHostWebView() {
+  if (!canUseNativeHostCapability('app.reloadWebView')) {
+    return false;
+  }
+
+  try {
+    return await requestNativeHostBoolean('app.reloadWebView');
+  } catch {
+    return false;
+  }
+}
+
 export function postWechatMiniProgramMessage(message: unknown) {
  return setHostShareTarget(message);
 }