From e9c6f8d6df7d56451d91c6668a9a821b807da835 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Thu, 18 Jun 2026 22:32:21 +0800
Subject: [PATCH] =?UTF-8?q?=E5=8E=9F=E7=94=9F=E5=A3=B3=E8=A1=A5=E9=BD=90?=
 =?UTF-8?q?=E8=83=BD=E5=8A=9B=E6=B8=85=E5=8D=95=E9=97=A8=E7=A6=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

在原生壳方案文档中补齐移动端和桌面端真实能力完整清单

让统一原生壳检查从源码能力清单反查方案文档

防止 HostBridge 能力实现、入口 URL 和文档再次漂移
---
 ...��ExpoReactNative与Tauri宿主壳方案-2026-06-17.md |  6 ++
 scripts/check-native-shells.mjs               | 99 +++++++++++++++++++
 2 files changed, 105 insertions(+)

diff --git a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md
index e523a4b06..57720c739 100644
--- a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md
+++ b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md
@@ -277,6 +277,10 @@ GameBridge 禁止：
 
 当前状态：已新增 `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`、`file.captureImage`、`file.importAudio`、`file.exportAudio`、`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，切换前会重新附加 `clientRuntime=native_app`、`hostShell=expo_mobile`、真实平台、版本和 capability 清单，确保宿主主动导航后的新页面仍按原生壳运行态启动；该能力不伪造尚未存在的登录、支付或其它原生页面，`navigation.canGoBack` 由 WebView 导航状态变化实时注入 H5，`app.reloadWebView` 只调用当前 `react-native-webview` 的 `reload()` 刷新内嵌 H5，不开放任意脚本执行或 URL 重写；WebView 自身拦截到外域导航时只会把 `http:`、`https:`、`mailto:`、`tel:` 且系统 `Linking.canOpenURL` 确认可打开的外链交给系统，危险协议或当前设备不可打开的外链直接阻断；`app.openExternalUrl` 也只允许同一协议白名单，并在 `Linking.canOpenURL` 确认可打开后才离开容器，否则返回 `host_error`；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 视作无选择；`file.captureImage` 通过 Expo ImagePicker 请求相机权限并打开系统相机拍摄图片，沿用同一 MIME、体积、base64 和文件名清洗规则，成功返回 `captured` 图片结果，不请求麦克风权限，也不把设备本地 URI 暴露给 H5；通用创作图片输入面板 `CreativeImageInputPanel` 在原生壳声明 `file.importImage` / `file.captureImage` 时分别展示受控上传 / 拍摄图标动作，并把宿主返回结果转换为现有 `File` 上传回调，拼图、拼消消、敲木鱼等复用该面板的主图和描述参考图选择无需新增玩法分叉；反馈页上传凭证、个人资料头像上传和方洞结果页图片槽位上传在原生壳声明 `file.importImage` 时优先打开宿主系统图片选择器，并把宿主返回结果转回现有 H5 数据结构，其中反馈页继续复用原本的 4 张数量限制、单张 1 MiB、总 4 MiB 和 data URL 提交流程，头像继续复用现有图片类型、5 MiB 大小限制、方形裁剪和资料更新链路，方洞结果页继续写回现有封面 / 背景 / 形状 / 洞口槽位与自动保存链路；`file.importAudio` 通过 Expo DocumentPicker 打开系统音频选择器，只接受 `audio/mpeg`、`audio/mp4`、`audio/wav`、`audio/ogg`、`audio/webm` 或对应扩展名，单次不超过 20 MiB，成功只返回清洗后的文件名、MIME、base64 内容和字节数，不暴露设备本地 URI；`file.exportAudio` 通过 Expo 文件系统写入缓存音频，再交给系统分享 / 保存面板，H5 只传当前页面已持有的允许 MIME 音频 base64 数据，单次不超过 20 MiB，成功只返回文件名和字节数；通用音频输入面板 `CreativeAudioInputPanel` 在原生壳声明导入能力时优先调用宿主导入，在声明导出能力且当前资产为本地 `Blob` 时展示导出入口，并继续复用现有 `readFileAsAsset(file, 'uploaded')` 处理链路；`haptics.impact` 通过 Expo Haptics 承接运行时轻触反馈，H5 在宿主不支持时回退到浏览器 vibration；`notification.showLocal` 通过 `expo-notifications` 请求系统通知权限并调度即时本地通知，Android 只使用固定本地 channel，不启用后台远程通知、远程推送 token 或定时提醒。登录和支付尚未接入渠道 SDK / 原生页面时明确返回 unsupported，让 H5 fallback 承接。
 
+2026-06-18 追加：移动壳当前通用真实能力完整清单为 `host.getRuntime`、`appearance.getColorScheme`、`host.events`、`app.lifecycle`、`share.open`、`share.setTarget`、`navigation.openNativePage`、`navigation.canGoBack`、`app.reloadWebView`、`app.openExternalUrl`、`network.status`、`network.statusChanged`、`clipboard.writeText`、`clipboard.readText`、`file.exportText`、`file.importText`、`file.exportImage`、`file.importImage`、`file.captureImage`、`file.importAudio`、`file.exportAudio`、`haptics.impact` 和 `notification.showLocal`。
+
+2026-06-18 追加：移动壳 iOS 额外真实能力为 `app.setBadgeCount`。`npm run check:native-shells` 会从源码 capability 清单反查移动壳和桌面壳能力清单段，避免实现、入口 URL 和方案文档再次漂移。
+
 2026-06-18 追加：移动壳 `navigation.canGoBack` 不再只读取 `react-native-webview` 的原生跨文档导航状态。Expo 壳会在 WebView `injectedJavaScriptBeforeContentLoaded` 中注入固定脚本，追踪当前 H5 文档内 `pushState` / `replaceState` / `popstate` 写入的路由栈，并通过内部 `genarrative.mobile.historyState` 消息回传；壳层把原生 WebView back-forward 状态与 H5 当前文档路由栈状态合成为 HostBridge `navigation.canGoBack` 事件。Android 返回键优先执行固定 `window.history.back(); true;` 回退 H5 SPA 路由，只有 H5 当前文档不可回退时才调用 WebView 原生 `goBack()`；该内部消息不是 HostBridge request method，也不开放 H5 到原生的通用事件写入通道。
 
 2026-06-18 追加：移动壳声明并实现 `file.importText`，通过 Expo DocumentPicker 打开系统文档选择器，只接受 `text/plain`、`text/markdown`、`text/csv`、`application/json` 或对应扩展名，单次不超过 5 MiB；成功只返回清洗后的文件名、MIME、UTF-8 文本内容和字节数，不暴露设备本地 URI，也不开放通用文件系统。H5 创作 Agent 工作台在原生壳声明该能力时优先打开宿主系统选择器，再把返回文本转换成现有浏览器 `File` 并继续调用 `/api/runtime/creation-agent/document-inputs/parse`，不在前端绕过后端文档解析、大小校验或 docx 处理。
@@ -340,6 +344,8 @@ GameBridge 禁止：
 
 当前状态：已新增 `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 并在主窗口内受控跳转，`navigation.canGoBack` 由桌面壳注入固定脚本追踪当前 H5 文档内的 `pushState` / `replaceState` / `popstate` 路由栈并通过 HostBridge event 回放，不读取或声明跨文档 native back-forward list，`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`、`host.events`、`app.lifecycle`、`network.status`、`network.statusChanged`、`share.setTarget`、`share.open`、`navigation.openNativePage`、`navigation.canGoBack`、`app.reloadWebView`、`app.openExternalUrl`、`app.setTitle`、`app.setBadgeCount`、`clipboard.writeText`、`clipboard.readText`、`file.exportText`、`file.exportImage`、`file.importImage`、`file.importAudio`、`file.exportAudio`、`file.imageDropped` 和 `notification.showLocal`；H5 会在主 App 启动时通过真实 `host.getRuntime` 回读并缓存这些能力，即使入口 URL 缺少 `hostCapabilities`，也只按宿主真实回包开启能力入口；其中 `host.events` 只表示桌面壳会通过 HostBridge message 派发生命周期、网络、H5 返回栈和拖拽图片等事件，不新增 request method，也不开放 Tauri event 插件；`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，也不开放通用文件系统；`file.importAudio` 通过系统选择框读取用户选择的音频，只接受 `audio/mpeg`、`audio/mp4`、`audio/wav`、`audio/ogg`、`audio/webm` 或对应扩展名，单次不超过 20 MiB，成功只返回清洗后的文件名、MIME、base64 内容和字节数，不把本机绝对路径暴露给 H5，也不开放通用文件系统；`file.exportAudio` 通过系统保存对话框写入 H5 当前已持有的音频字节，只接受允许 MIME 的 base64 数据，单次不超过 20 MiB，成功只返回文件名和字节数，不让宿主代读任意本地文件；通用音频输入面板 `CreativeAudioInputPanel` 在桌面壳声明导入能力时优先打开系统音频选择框，在声明导出能力且当前资产为本地 `Blob` 时展示导出入口，并继续复用 `readFileAsAsset(file, 'uploaded')` 处理链路；`notification.showLocal` 由 Rust 内部通过 `tauri-plugin-notification` 发送即时系统通知，只接受清洗后的标题和正文，发送前先检查系统通知权限，处于 prompt 状态时只在 Rust 侧请求一次权限，最终未授权时返回失败，不开放插件 JS guest API、远程推送、定时提醒或通知 token；通用创作图片输入面板 `CreativeImageInputPanel` 在桌面壳声明 `file.importImage` 时会优先打开系统图片选择框，在同时声明 `file.imageDropped` 时会按宿主拖入坐标把图片交给命中的主图槽位，并把结果转换为现有 `File` 上传回调；反馈页上传凭证、个人资料头像上传和方洞结果页图片槽位上传同样优先消费 `file.importImage`，但继续交给 H5 原有预览、裁剪、槽位编辑、大小限制和提交 / 保存链路。普通浏览器、小程序和未声明能力的壳继续保留原文件输入路径。原生系统分享面板、登录和支付未接入真实插件 / 渠道前不声明支持，不返回 mock 成功。
 
+2026-06-18 追加：桌面壳当前真实能力完整清单为 `host.getRuntime`、`appearance.getColorScheme`、`host.events`、`app.lifecycle`、`share.open`、`share.setTarget`、`navigation.openNativePage`、`navigation.canGoBack`、`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.importAudio`、`file.exportAudio`、`file.imageDropped` 和 `notification.showLocal`。`npm run check:native-shells` 会从 Rust capability 清单反查本段，避免实现、入口 URL 和方案文档再次漂移。
+
 2026-06-18 追加：桌面壳的网络状态同样只通过 HostBridge 暴露给 H5。H5 外部生成队列概览在桌面壳明确离线或不可达时暂停轮询，窗口恢复在线后重新刷新；Tauri 仍不开放任意网络探测、shell 或文件系统能力给主站。
 
 2026-06-18 追加：桌面壳声明并实现 `file.importText`，通过系统文件选择框读取用户选择的文本文件，只接受 `text/plain`、`text/markdown`、`text/csv`、`application/json` 对应扩展名，单次不超过 5 MiB；成功只返回清洗后的文件名、MIME、UTF-8 文本内容和字节数，不暴露本机绝对路径，也不开放通用文件系统。H5 创作 Agent 工作台复用同一 HostBridge 文本导入入口和后端解析接口；普通浏览器、小程序和未声明该能力的裁剪壳继续保留原 `<input type="file">` 路径。
diff --git a/scripts/check-native-shells.mjs b/scripts/check-native-shells.mjs
index 7ea3f008c..4db466e66 100644
--- a/scripts/check-native-shells.mjs
+++ b/scripts/check-native-shells.mjs
@@ -5,6 +5,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+const nativeShellPlanPath =
+  'docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md';
 
 const productionShellRoots = [
   'apps/mobile-shell',
@@ -89,6 +91,11 @@ const expectedDesktopShellRustFiles = [
   'webview.rs',
   'window_state.rs',
 ];
+const capabilityListMarkers = {
+  desktop: '桌面壳当前真实能力完整清单为',
+  mobile: '移动壳当前通用真实能力完整清单为',
+  mobileIosExtra: '移动壳 iOS 额外真实能力为',
+};
 const productionShellExtensions = new Set([
   '.json',
   '.mjs',
@@ -241,6 +248,95 @@ function assertSameList(actual, expected, label) {
   }
 }
 
+function extractTsStringArray(source, exportName, seen = new Set()) {
+  if (seen.has(exportName)) {
+    throw new Error(`cyclic string array export ${exportName}`);
+  }
+
+  const match = source.match(
+    new RegExp(`export const ${exportName}[^=]*= \\[([\\s\\S]*?)\\](?: as const)?;`),
+  );
+  if (!match) {
+    throw new Error(`unable to read ${exportName}`);
+  }
+
+  const nextSeen = new Set(seen);
+  nextSeen.add(exportName);
+  const entries = [];
+  for (const entry of match[1].matchAll(/\.\.\s*([A-Z0-9_]+)|'([^']+)'/g)) {
+    if (entry[1]) {
+      entries.push(...extractTsStringArray(source, entry[1], nextSeen));
+    } else {
+      entries.push(entry[2]);
+    }
+  }
+
+  return entries;
+}
+
+function extractRustCapabilities(source) {
+  const match = source.match(/fn capabilities\(\)[^{]*\{[\s\S]*?vec!\[([\s\S]*?)\]\s*\}/);
+  if (!match) {
+    throw new Error('unable to read desktop shell capabilities');
+  }
+
+  return [...match[1].matchAll(/"([^"]+)"/g)].map((entry) => entry[1]);
+}
+
+function extractDocumentCapabilityList(source, marker) {
+  const markerIndex = source.indexOf(marker);
+  if (markerIndex === -1) {
+    throw new Error(`native shell plan missing ${marker}`);
+  }
+
+  const sentenceEnd = source.indexOf('。', markerIndex);
+  const sentence = source.slice(
+    markerIndex,
+    sentenceEnd === -1 ? undefined : sentenceEnd,
+  );
+  return [...sentence.matchAll(/`([^`]+)`/g)].map((entry) => entry[1]);
+}
+
+function assertNativeShellCapabilityPlan() {
+  const planSource = fs.readFileSync(nativeShellPlanPath, 'utf8');
+  const mobileCapabilitySource = fs.readFileSync(
+    'apps/mobile-shell/src/host-bridge/capabilities.ts',
+    'utf8',
+  );
+  const desktopCapabilitySource = fs.readFileSync(
+    'apps/desktop-shell/src-tauri/src/host_bridge/capabilities.rs',
+    'utf8',
+  );
+  const mobileCapabilities = extractTsStringArray(
+    mobileCapabilitySource,
+    'MOBILE_HOST_CAPABILITIES',
+  );
+  const iosMobileCapabilities = extractTsStringArray(
+    mobileCapabilitySource,
+    'IOS_MOBILE_HOST_CAPABILITIES',
+  );
+  const iosExtraCapabilities = iosMobileCapabilities.filter(
+    (capability) => !mobileCapabilities.includes(capability),
+  );
+  const desktopCapabilities = extractRustCapabilities(desktopCapabilitySource);
+
+  assertSameList(
+    extractDocumentCapabilityList(planSource, capabilityListMarkers.mobile),
+    mobileCapabilities,
+    'mobile shell documented common capabilities',
+  );
+  assertSameList(
+    extractDocumentCapabilityList(planSource, capabilityListMarkers.mobileIosExtra),
+    iosExtraCapabilities,
+    'mobile shell documented iOS extra capabilities',
+  );
+  assertSameList(
+    extractDocumentCapabilityList(planSource, capabilityListMarkers.desktop),
+    desktopCapabilities,
+    'desktop shell documented capabilities',
+  );
+}
+
 function assertHostBridgeLayerLayout() {
   const wechatBridgeFiles = fs
     .readdirSync('miniprogram/host-bridge', { withFileTypes: true })
@@ -376,6 +472,9 @@ for (const step of steps) {
 console.log('[check:native-shells] host-bridge-layer-layout');
 assertHostBridgeLayerLayout();
 
+console.log('[check:native-shells] native-shell-capability-plan');
+assertNativeShellCapabilityPlan();
+
 console.log('[check:native-shells] production-shell-dev-scaffold-scan');
 assertNoProductionShellDevScaffoldTerms();