拆薄移动端壳入口

迁移移动端 WebView 容器到 shell 层

更新原生壳结构门禁和移动壳配置检查

同步宿主壳结构文档
This commit is contained in:
2026-06-18 17:27:11 +08:00
parent fd6c4d4830
commit 503ae19683
7 changed files with 312 additions and 271 deletions
+2 -254
View File
@@ -1,257 +1,5 @@
import { StatusBar } from 'expo-status-bar';
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import {
AppState,
type AppStateStatus,
BackHandler,
Linking,
Platform,
StyleSheet,
} from 'react-native';
import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
import type { WebViewMessageEvent } from 'react-native-webview';
import { WebView } from 'react-native-webview';
import {
configureMobileHostBridgeNavigation,
handleMobileHostBridgeMessage,
resolveMobileHostCapabilities,
} from './src/host-bridge/mobileHostBridge';
import { buildMobileShellUrlFromDeepLink } from './src/shell/mobileShellDeepLink';
import { lifecyclePayloadFromAppState } from './src/shell/mobileShellLifecycle';
import {
resolveMobileShellExternalUrl,
shouldAcceptMobileShellHostBridgeMessage,
shouldOpenInMobileShellWebView,
} from './src/shell/mobileShellNavigation';
import {
getMobileNetworkStatus,
subscribeMobileNetworkStatus,
} from './src/shell/mobileShellNetwork';
import { MOBILE_SHELL_HOST_VERSION } from './src/shell/mobileShellRuntime';
import { MOBILE_SHELL_SAFE_AREA_EDGES } from './src/shell/mobileShellSafeArea';
import {
buildMobileShellUrl,
resolveMobileShellBaseWebUrl,
} from './src/shell/mobileShellUrl';
import { BLOCK_WEBVIEW_DOWNLOAD_SCRIPT } from './src/shell/mobileShellWebViewPolicy';
function buildHostBridgeMessageScript(message: unknown) {
return `window.dispatchEvent(new MessageEvent('message', { data: ${JSON.stringify(
JSON.stringify(message),
)}, origin: window.location.origin, source: window })); true;`;
}
import MobileShellApp from './src/shell/MobileShellApp';
export default function App() {
const webViewRef = useRef<WebView>(null);
const [canGoBack, setCanGoBack] = useState(false);
const baseWebUrl = resolveMobileShellBaseWebUrl(
process.env.EXPO_PUBLIC_GENARRATIVE_WEB_URL,
);
const mobileShellUrlOptions = useMemo(
() => ({
platform: Platform.OS === 'ios' ? 'ios' as const : 'android' as const,
hostVersion: MOBILE_SHELL_HOST_VERSION,
capabilities: resolveMobileHostCapabilities(),
}),
[],
);
const [webUrl, setWebUrl] = useState(() =>
buildMobileShellUrl(baseWebUrl, mobileShellUrlOptions),
);
const allowedWebOrigin = useMemo(() => new URL(webUrl).origin, [webUrl]);
const reloadCurrentWebView = useCallback(() => {
webViewRef.current?.reload();
}, []);
const injectHostBridgeEvent = useCallback((event: string, payload: unknown) => {
webViewRef.current?.injectJavaScript(
buildHostBridgeMessageScript({
bridge: 'GenarrativeHostBridge',
version: 1,
event,
payload,
}),
);
}, []);
const injectLifecycleEvent = useCallback(
(state: AppStateStatus) => {
injectHostBridgeEvent('app.lifecycle', lifecyclePayloadFromAppState(state));
},
[injectHostBridgeEvent],
);
const injectNetworkStatusEvent = useCallback(
(payload: Awaited<ReturnType<typeof getMobileNetworkStatus>>) => {
injectHostBridgeEvent('network.statusChanged', payload);
},
[injectHostBridgeEvent],
);
useEffect(() => {
configureMobileHostBridgeNavigation({
allowedOrigin: allowedWebOrigin,
openWebViewUrl(url) {
setWebUrl(url);
},
reloadWebView: reloadCurrentWebView,
});
return () => configureMobileHostBridgeNavigation(null);
}, [allowedWebOrigin, reloadCurrentWebView]);
useEffect(() => {
let disposed = false;
const openDeepLink = (url: string | null | undefined) => {
const nextUrl = buildMobileShellUrlFromDeepLink(
url,
baseWebUrl,
mobileShellUrlOptions,
);
setWebUrl(nextUrl);
};
void Linking.getInitialURL().then((url) => {
if (!disposed) {
openDeepLink(url);
}
});
const subscription = Linking.addEventListener('url', (event) => {
openDeepLink(event.url);
});
return () => {
disposed = true;
subscription.remove();
};
}, [baseWebUrl, mobileShellUrlOptions]);
useEffect(() => {
const subscription = BackHandler.addEventListener(
'hardwareBackPress',
() => {
if (!canGoBack) {
return false;
}
webViewRef.current?.goBack();
return true;
},
);
return () => subscription.remove();
}, [canGoBack]);
useEffect(() => {
const subscription = AppState.addEventListener(
'change',
injectLifecycleEvent,
);
injectLifecycleEvent(AppState.currentState);
return () => subscription.remove();
}, [injectLifecycleEvent]);
useEffect(() => {
return subscribeMobileNetworkStatus(injectNetworkStatusEvent);
}, [injectNetworkStatusEvent]);
const handleMessage = (event: WebViewMessageEvent) => {
if (
!shouldAcceptMobileShellHostBridgeMessage(
event.nativeEvent.url,
allowedWebOrigin,
)
) {
return;
}
void handleMobileHostBridgeMessage(event.nativeEvent.data, (response) => {
webViewRef.current?.injectJavaScript(
buildHostBridgeMessageScript(response),
);
});
};
const handleShouldStartLoad = (request: { url: string }) => {
if (shouldOpenInMobileShellWebView(request.url, allowedWebOrigin)) {
return true;
}
const externalUrl = resolveMobileShellExternalUrl(request.url);
if (externalUrl) {
void Linking.openURL(externalUrl).catch(() => undefined);
}
return false;
};
const handleWebViewLoad = (event: { nativeEvent: { url: string } }) => {
if (
!shouldAcceptMobileShellHostBridgeMessage(
event.nativeEvent.url,
allowedWebOrigin,
)
) {
return;
}
injectLifecycleEvent(AppState.currentState);
void getMobileNetworkStatus()
.then(injectNetworkStatusEvent)
.catch(() => undefined);
};
return (
<SafeAreaProvider>
<SafeAreaView style={styles.root} edges={MOBILE_SHELL_SAFE_AREA_EDGES}>
<StatusBar style="auto" />
<WebView
ref={webViewRef}
source={{ uri: webUrl }}
javaScriptEnabled
javaScriptCanOpenWindowsAutomatically={false}
domStorageEnabled
mixedContentMode="never"
originWhitelist={[allowedWebOrigin]}
allowFileAccess={false}
allowFileAccessFromFileURLs={false}
allowUniversalAccessFromFileURLs={false}
allowsFullscreenVideo
allowsInlineMediaPlayback
mediaPlaybackRequiresUserAction
thirdPartyCookiesEnabled={false}
sharedCookiesEnabled={false}
webviewDebuggingEnabled={false}
injectedJavaScriptBeforeContentLoaded={BLOCK_WEBVIEW_DOWNLOAD_SCRIPT}
onFileDownload={() => undefined}
onMessage={handleMessage}
onContentProcessDidTerminate={reloadCurrentWebView}
onRenderProcessGone={reloadCurrentWebView}
onLoad={handleWebViewLoad}
onShouldStartLoadWithRequest={handleShouldStartLoad}
onNavigationStateChange={(event) => {
setCanGoBack(event.canGoBack);
webViewRef.current?.injectJavaScript(
buildHostBridgeMessageScript({
bridge: 'GenarrativeHostBridge',
version: 1,
event: 'navigation.canGoBack',
payload: {
canGoBack: event.canGoBack,
},
}),
);
}}
setSupportMultipleWindows={false}
/>
</SafeAreaView>
</SafeAreaProvider>
);
return <MobileShellApp />;
}
const styles = StyleSheet.create({
root: {
flex: 1,
backgroundColor: '#fffdf9',
},
});
+38 -11
View File
@@ -6,6 +6,8 @@ const appConfigPath = new URL('../app.json', import.meta.url);
const appConfig = JSON.parse(fs.readFileSync(appConfigPath, 'utf8')).expo;
const appPath = new URL('../App.tsx', import.meta.url);
const appSource = fs.readFileSync(appPath, 'utf8');
const mobileShellAppPath = new URL('../src/shell/MobileShellApp.tsx', import.meta.url);
const mobileShellAppSource = fs.readFileSync(mobileShellAppPath, 'utf8');
const bridgePath = new URL('../src/host-bridge/mobileHostBridge.ts', import.meta.url);
const bridgeSource = fs.readFileSync(bridgePath, 'utf8');
const bridgeDirPath = new URL('../src/host-bridge/', import.meta.url);
@@ -207,6 +209,7 @@ function assertNoBlockedMobileChannelSnippets() {
const sources = [
['app.json', JSON.stringify(appConfig)],
['App.tsx', appSource],
['MobileShellApp.tsx', mobileShellAppSource],
['src/host-bridge', hostBridgeSource],
['mobileShellUrl.ts', mobileShellUrlSource],
['mobileShellRuntime.ts', mobileShellRuntimeSource],
@@ -747,13 +750,29 @@ for (const snippet of [
'onFileDownload={() => undefined}',
'setSupportMultipleWindows={false}',
]) {
if (!appSource.includes(snippet)) {
throw new Error(`mobile shell App missing ${snippet}`);
if (!mobileShellAppSource.includes(snippet)) {
throw new Error(`mobile shell MobileShellApp missing ${snippet}`);
}
}
if (appSource.includes('process.env.EXPO_PUBLIC_GENARRATIVE_WEB_URL ||')) {
throw new Error('mobile shell App must normalize EXPO_PUBLIC_GENARRATIVE_WEB_URL');
if (!appSource.includes("import MobileShellApp from './src/shell/MobileShellApp';")) {
throw new Error('mobile shell App must import the shell app facade');
}
if (!appSource.includes('return <MobileShellApp />;')) {
throw new Error('mobile shell App must only render the shell app facade');
}
if (appSource.includes('./src/host-bridge/')) {
throw new Error('mobile shell App must not import HostBridge directly');
}
if (
mobileShellAppSource.includes('process.env.EXPO_PUBLIC_GENARRATIVE_WEB_URL ||')
) {
throw new Error(
'mobile shell MobileShellApp must normalize EXPO_PUBLIC_GENARRATIVE_WEB_URL',
);
}
if (
@@ -777,8 +796,10 @@ for (const snippet of [
}
}
if (appSource.includes('127.0.0.1:3000')) {
throw new Error('mobile shell App must not hard-code localhost as the default H5 URL');
if (mobileShellAppSource.includes('127.0.0.1:3000')) {
throw new Error(
'mobile shell MobileShellApp must not hard-code localhost as the default H5 URL',
);
}
for (const dependency of [
@@ -903,15 +924,15 @@ for (const snippet of [
}
const capabilityQuerySnippet = "capabilities: MOBILE_HOST_CAPABILITIES";
if (appSource.includes(capabilityQuerySnippet)) {
if (mobileShellAppSource.includes(capabilityQuerySnippet)) {
throw new Error('mobile shell URL must resolve platform-aware capabilities');
}
if (!appSource.includes('capabilities: resolveMobileHostCapabilities()')) {
if (!mobileShellAppSource.includes('capabilities: resolveMobileHostCapabilities()')) {
throw new Error('mobile shell URL must use resolveMobileHostCapabilities()');
}
if (!appSource.includes('hostVersion: MOBILE_SHELL_HOST_VERSION')) {
if (!mobileShellAppSource.includes('hostVersion: MOBILE_SHELL_HOST_VERSION')) {
throw new Error('mobile shell URL must use the shared mobile shell host version');
}
@@ -919,12 +940,18 @@ if (!bridgeSource.includes('hostVersion: MOBILE_SHELL_HOST_VERSION')) {
throw new Error('mobile shell runtime response must use the shared mobile shell host version');
}
if (appSource.includes("hostVersion: '0.1.0'") || bridgeSource.includes("hostVersion: '0.1.0'")) {
if (
mobileShellAppSource.includes("hostVersion: '0.1.0'") ||
bridgeSource.includes("hostVersion: '0.1.0'")
) {
throw new Error('mobile shell HostBridge version must not be duplicated in app or bridge source');
}
for (const capability of sdkBackedCapabilities) {
if (appSource.includes(`'${capability}'`) || appSource.includes(`"${capability}"`)) {
if (
mobileShellAppSource.includes(`'${capability}'`) ||
mobileShellAppSource.includes(`"${capability}"`)
) {
throw new Error(
`mobile shell URL must not advertise ${capability} without a real SDK/channel flow`,
);
@@ -0,0 +1,257 @@
import { StatusBar } from 'expo-status-bar';
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import {
AppState,
type AppStateStatus,
BackHandler,
Linking,
Platform,
StyleSheet,
} from 'react-native';
import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
import type { WebViewMessageEvent } from 'react-native-webview';
import { WebView } from 'react-native-webview';
import {
configureMobileHostBridgeNavigation,
handleMobileHostBridgeMessage,
resolveMobileHostCapabilities,
} from '../host-bridge/mobileHostBridge';
import { buildMobileShellUrlFromDeepLink } from './mobileShellDeepLink';
import { lifecyclePayloadFromAppState } from './mobileShellLifecycle';
import {
resolveMobileShellExternalUrl,
shouldAcceptMobileShellHostBridgeMessage,
shouldOpenInMobileShellWebView,
} from './mobileShellNavigation';
import {
getMobileNetworkStatus,
subscribeMobileNetworkStatus,
} from './mobileShellNetwork';
import { MOBILE_SHELL_HOST_VERSION } from './mobileShellRuntime';
import { MOBILE_SHELL_SAFE_AREA_EDGES } from './mobileShellSafeArea';
import {
buildMobileShellUrl,
resolveMobileShellBaseWebUrl,
} from './mobileShellUrl';
import { BLOCK_WEBVIEW_DOWNLOAD_SCRIPT } from './mobileShellWebViewPolicy';
function buildHostBridgeMessageScript(message: unknown) {
return `window.dispatchEvent(new MessageEvent('message', { data: ${JSON.stringify(
JSON.stringify(message),
)}, origin: window.location.origin, source: window })); true;`;
}
export default function MobileShellApp() {
const webViewRef = useRef<WebView>(null);
const [canGoBack, setCanGoBack] = useState(false);
const baseWebUrl = resolveMobileShellBaseWebUrl(
process.env.EXPO_PUBLIC_GENARRATIVE_WEB_URL,
);
const mobileShellUrlOptions = useMemo(
() => ({
platform: Platform.OS === 'ios' ? 'ios' as const : 'android' as const,
hostVersion: MOBILE_SHELL_HOST_VERSION,
capabilities: resolveMobileHostCapabilities(),
}),
[],
);
const [webUrl, setWebUrl] = useState(() =>
buildMobileShellUrl(baseWebUrl, mobileShellUrlOptions),
);
const allowedWebOrigin = useMemo(() => new URL(webUrl).origin, [webUrl]);
const reloadCurrentWebView = useCallback(() => {
webViewRef.current?.reload();
}, []);
const injectHostBridgeEvent = useCallback((event: string, payload: unknown) => {
webViewRef.current?.injectJavaScript(
buildHostBridgeMessageScript({
bridge: 'GenarrativeHostBridge',
version: 1,
event,
payload,
}),
);
}, []);
const injectLifecycleEvent = useCallback(
(state: AppStateStatus) => {
injectHostBridgeEvent('app.lifecycle', lifecyclePayloadFromAppState(state));
},
[injectHostBridgeEvent],
);
const injectNetworkStatusEvent = useCallback(
(payload: Awaited<ReturnType<typeof getMobileNetworkStatus>>) => {
injectHostBridgeEvent('network.statusChanged', payload);
},
[injectHostBridgeEvent],
);
useEffect(() => {
configureMobileHostBridgeNavigation({
allowedOrigin: allowedWebOrigin,
openWebViewUrl(url) {
setWebUrl(url);
},
reloadWebView: reloadCurrentWebView,
});
return () => configureMobileHostBridgeNavigation(null);
}, [allowedWebOrigin, reloadCurrentWebView]);
useEffect(() => {
let disposed = false;
const openDeepLink = (url: string | null | undefined) => {
const nextUrl = buildMobileShellUrlFromDeepLink(
url,
baseWebUrl,
mobileShellUrlOptions,
);
setWebUrl(nextUrl);
};
void Linking.getInitialURL().then((url) => {
if (!disposed) {
openDeepLink(url);
}
});
const subscription = Linking.addEventListener('url', (event) => {
openDeepLink(event.url);
});
return () => {
disposed = true;
subscription.remove();
};
}, [baseWebUrl, mobileShellUrlOptions]);
useEffect(() => {
const subscription = BackHandler.addEventListener(
'hardwareBackPress',
() => {
if (!canGoBack) {
return false;
}
webViewRef.current?.goBack();
return true;
},
);
return () => subscription.remove();
}, [canGoBack]);
useEffect(() => {
const subscription = AppState.addEventListener(
'change',
injectLifecycleEvent,
);
injectLifecycleEvent(AppState.currentState);
return () => subscription.remove();
}, [injectLifecycleEvent]);
useEffect(() => {
return subscribeMobileNetworkStatus(injectNetworkStatusEvent);
}, [injectNetworkStatusEvent]);
const handleMessage = (event: WebViewMessageEvent) => {
if (
!shouldAcceptMobileShellHostBridgeMessage(
event.nativeEvent.url,
allowedWebOrigin,
)
) {
return;
}
void handleMobileHostBridgeMessage(event.nativeEvent.data, (response) => {
webViewRef.current?.injectJavaScript(
buildHostBridgeMessageScript(response),
);
});
};
const handleShouldStartLoad = (request: { url: string }) => {
if (shouldOpenInMobileShellWebView(request.url, allowedWebOrigin)) {
return true;
}
const externalUrl = resolveMobileShellExternalUrl(request.url);
if (externalUrl) {
void Linking.openURL(externalUrl).catch(() => undefined);
}
return false;
};
const handleWebViewLoad = (event: { nativeEvent: { url: string } }) => {
if (
!shouldAcceptMobileShellHostBridgeMessage(
event.nativeEvent.url,
allowedWebOrigin,
)
) {
return;
}
injectLifecycleEvent(AppState.currentState);
void getMobileNetworkStatus()
.then(injectNetworkStatusEvent)
.catch(() => undefined);
};
return (
<SafeAreaProvider>
<SafeAreaView style={styles.root} edges={MOBILE_SHELL_SAFE_AREA_EDGES}>
<StatusBar style="auto" />
<WebView
ref={webViewRef}
source={{ uri: webUrl }}
javaScriptEnabled
javaScriptCanOpenWindowsAutomatically={false}
domStorageEnabled
mixedContentMode="never"
originWhitelist={[allowedWebOrigin]}
allowFileAccess={false}
allowFileAccessFromFileURLs={false}
allowUniversalAccessFromFileURLs={false}
allowsFullscreenVideo
allowsInlineMediaPlayback
mediaPlaybackRequiresUserAction
thirdPartyCookiesEnabled={false}
sharedCookiesEnabled={false}
webviewDebuggingEnabled={false}
injectedJavaScriptBeforeContentLoaded={BLOCK_WEBVIEW_DOWNLOAD_SCRIPT}
onFileDownload={() => undefined}
onMessage={handleMessage}
onContentProcessDidTerminate={reloadCurrentWebView}
onRenderProcessGone={reloadCurrentWebView}
onLoad={handleWebViewLoad}
onShouldStartLoadWithRequest={handleShouldStartLoad}
onNavigationStateChange={(event) => {
setCanGoBack(event.canGoBack);
webViewRef.current?.injectJavaScript(
buildHostBridgeMessageScript({
bridge: 'GenarrativeHostBridge',
version: 1,
event: 'navigation.canGoBack',
payload: {
canGoBack: event.canGoBack,
},
}),
);
}}
setSupportMultipleWindows={false}
/>
</SafeAreaView>
</SafeAreaProvider>
);
}
const styles = StyleSheet.create({
root: {
flex: 1,
backgroundColor: '#fffdf9',
},
});
@@ -86,7 +86,7 @@
- 2026-06-18 移动壳 WebView 安全开关:Expo 移动壳 WebView 必须显式禁用 JS 自动开窗、多窗口、文件访问、file URL 跨源访问、HTTPS 混合内容、第三方 Cookie、共享 Cookie 和 WebView 远程调试;同源主站页面才能留在带 HostBridge 的 WebView 内,外链只通过受控协议离开容器交给系统。配置检查和移动壳导航测试会拒绝这些边界被放宽。
- 2026-06-18 移动壳 WebView 默认下载边界:Expo WebView 内网页自动下载和 `<a download>` 直接落盘默认关闭;壳层注入脚本阻断 download 链接,iOS `onFileDownload` 只丢弃不落盘,Android 包配置通过 `blockedPermissions` 移除外部存储读写、管理外部存储和请求安装包权限。移动端文本、图片、音频保存只能通过 `file.exportText``file.exportImage``file.exportAudio` 等 HostBridge 受控导出能力进入系统分享 / 保存面板。
- 2026-06-18 移动壳 HostBridge 消息来源校验:Expo 移动壳 `onMessage` 必须根据 `event.nativeEvent.url` 校验消息来源,只有同源主站页面能进入 `handleMobileHostBridgeMessage``about:blank`、外域、协议降级和危险协议页面消息直接丢弃,不返回宿主能力错误细节。该规则与 WebView 导航留壳规则共用同源判断,配置检查和移动壳导航测试会拒绝移除。
- 2026-06-18 三端桥接层目录同构:微信小程序、Expo 移动壳和 Tauri 桌面壳都按 `host-bridge / shell` 两层管理宿主桥接代码。微信 `miniprogram/host-bridge/wechatHostBridge*.js` 只放协议归一、支付 / 订阅 / 分享结果编解码和可测试桥接函数,`miniprogram/shell/wechatShell*.js` 承接 Page 生命周期、`wx.*` 容器调用、WebView 容器行为和页面工厂;页面目录只保留 `Page(createWechat...Page())` 装配。Expo `mobileHostBridgeProtocol.ts``mobileHostBridgeFiles.ts``mobileHostBridgeShare.ts` 和 facade `mobileHostBridge.ts` 分别对齐 Tauri `host_bridge/protocol.rs``files.rs``share.rs``mod.rs`。Tauri `shell/deep_link.rs``shell/tray.rs``shell/webview.rs` 分别承接深链、托盘和 WebView 容器行为。`npm run check:native-shells` 会校验微信、移动和桌面三端目录清单,新增宿主能力必须按同一边界落文件和测试。
- 2026-06-18 三端桥接层目录同构:微信小程序、Expo 移动壳和 Tauri 桌面壳都按 `host-bridge / shell` 两层管理宿主桥接代码。微信 `miniprogram/host-bridge/wechatHostBridge*.js` 只放协议归一、支付 / 订阅 / 分享结果编解码和可测试桥接函数,`miniprogram/shell/wechatShell*.js` 承接 Page 生命周期、`wx.*` 容器调用、WebView 容器行为和页面工厂;页面目录只保留 `Page(createWechat...Page())` 装配。Expo `mobileHostBridgeProtocol.ts``mobileHostBridgeFiles.ts``mobileHostBridgeShare.ts` 和 facade `mobileHostBridge.ts` 分别对齐 Tauri `host_bridge/protocol.rs``files.rs``share.rs``mod.rs`,根 `App.tsx` 只装配 `src/shell/MobileShellApp.tsx`,不直接进口 HostBridge。Tauri `shell/deep_link.rs``shell/tray.rs``shell/webview.rs` 分别承接深链、托盘和 WebView 容器行为。`npm run check:native-shells` 会校验微信、移动和桌面三端目录清单,新增宿主能力必须按同一边界落文件和测试。
- 影响范围:`src/services/host-bridge/`、未来 `apps/mobile-shell/`、未来 `apps/desktop-shell/`、移动端支付 / 分享 / 深链 / 推送、桌面端系统能力、AI H5 sandbox 的 GameBridge 边界。
- 验证方式:普通浏览器、小程序、Expo 壳、Tauri 壳都能返回正确 `getHostRuntime()`;未支持能力能回退 H5;固定玩法在各宿主中读取同一作品数据和运行态 snapshot;AI sandbox 无法直接调用 HostBridgeTauri release 不允许任意远端页面调用桌面命令。
- 关联文档:`docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md``docs/【前端架构】宿主壳能力统一协议-2026-06-17.md`
@@ -2475,6 +2475,6 @@
## 2026-06-18 三端宿主桥接层文件结构对齐
- 背景:微信小程序壳、Expo 移动壳和 Tauri 桌面壳都在承接宿主能力;如果微信页面继续散落 `index.shared.js`,桌面端继续把桥接分发堆在 `main.rs`,后续新增登录、支付、文件、通知或 sandbox 转发能力时会很难跨端对照 owner。
- 决策:三端桥接层按职责对齐。微信小程序页面路由不改,但可测试桥接逻辑统一放到 `miniprogram/host-bridge/wechatHostBridge*.js`,页面目录只保留生命周期和装配;Expo 移动壳拆成 `apps/mobile-shell/src/host-bridge/mobileHostBridgeProtocol.ts``mobileHostBridgeFiles.ts``mobileHostBridgeShare.ts` 和 facade `mobileHostBridge.ts`,分别负责协议 / 能力清单 / request 校验 / replay 基础、文件能力、分享能力和 method 分发,`apps/mobile-shell/src/shell/mobileShell*.ts` 负责 URL、导航、网络、生命周期、安全区和 WebView policyTauri 桌面壳拆成 `apps/desktop-shell/src-tauri/src/host_bridge/*.rs``apps/desktop-shell/src-tauri/src/shell/*.rs`,其中 deep link、tray、webview 分文件承接容器行为,`main.rs` 只做 builder、plugin、窗口和状态装配。`scripts/check-native-shells.mjs` 锁定三端桥接层目录清单。
- 决策:三端桥接层按职责对齐。微信小程序页面路由不改,但可测试桥接逻辑统一放到 `miniprogram/host-bridge/wechatHostBridge*.js`,页面目录只保留生命周期和装配;Expo 移动壳拆成 `apps/mobile-shell/src/host-bridge/mobileHostBridgeProtocol.ts``mobileHostBridgeFiles.ts``mobileHostBridgeShare.ts` 和 facade `mobileHostBridge.ts`,分别负责协议 / 能力清单 / request 校验 / replay 基础、文件能力、分享能力和 method 分发,`App.tsx` 只装配 `apps/mobile-shell/src/shell/MobileShellApp.tsx``apps/mobile-shell/src/shell/mobileShell*.ts(x)` 负责 WebView 容器、URL、导航、网络、生命周期、安全区和 WebView policyTauri 桌面壳拆成 `apps/desktop-shell/src-tauri/src/host_bridge/*.rs``apps/desktop-shell/src-tauri/src/shell/*.rs`,其中 deep link、tray、webview 分文件承接容器行为,`main.rs` 只做 builder、plugin、窗口和状态装配。`scripts/check-native-shells.mjs` 锁定三端桥接层目录清单,并拒绝移动根入口直接引用 HostBridge
- 影响范围:`miniprogram/host-bridge/``miniprogram/pages/*/index.js``apps/mobile-shell/src/``apps/desktop-shell/src-tauri/src/``scripts/check-native-shells.mjs`、宿主壳方案文档。
- 验证方式:`npm run test -- miniprogram/host-bridge/wechatHostBridgeWebView.test.js miniprogram/host-bridge/wechatHostBridgePayment.test.js miniprogram/host-bridge/wechatHostBridgeShareGrid.test.js miniprogram/host-bridge/wechatHostBridgeSubscribeMessage.test.js miniprogram/pages/web-view/index.style.test.js``npm run check:native-shells``npm run typecheck``npm run check:encoding``git diff --check`
@@ -64,7 +64,7 @@ src/
已落地:`packages/shared/src/contracts/hostBridge.ts` 保存消息 envelope、method、payload 和错误码,H5、Expo 壳与 Tauri 壳共享同一份协议类型。
三端宿主桥接层按职责对齐命名:微信小程序页面路由仍保留在 `miniprogram/pages/*`,协议归一、支付 / 订阅 / 分享结果编解码统一放在 `miniprogram/host-bridge/wechatHostBridge*.js`Page 生命周期、`wx.*` 容器调用、WebView 容器行为和页面工厂统一放在 `miniprogram/shell/wechatShell*.js`,页面入口只做 `Page(createWechat...Page())` 装配;Expo 移动壳使用 `apps/mobile-shell/src/host-bridge/mobileHostBridgeProtocol.ts` 承接 envelope、能力清单、request 校验和 replay 基础,`mobileHostBridgeFiles.ts` / `mobileHostBridgeShare.ts` 分别承接文件和分享能力,`mobileHostBridge.ts` 只作为对外 facade 与 method 分发入口,`apps/mobile-shell/src/shell/mobileShell*.ts` 承接 URL、导航、网络、生命周期、安全区和 WebView policyTauri 桌面壳使用 `apps/desktop-shell/src-tauri/src/host_bridge/protocol.rs``files.rs``share.rs``mod.rs` 承接协议、文件、分享和分发,`apps/desktop-shell/src-tauri/src/shell/*.rs` 承接 WebView、托盘和容器行为,`main.rs` 只保留 Tauri builder / plugin / window 装配。
三端宿主桥接层按职责对齐命名:微信小程序页面路由仍保留在 `miniprogram/pages/*`,协议归一、支付 / 订阅 / 分享结果编解码统一放在 `miniprogram/host-bridge/wechatHostBridge*.js`Page 生命周期、`wx.*` 容器调用、WebView 容器行为和页面工厂统一放在 `miniprogram/shell/wechatShell*.js`,页面入口只做 `Page(createWechat...Page())` 装配;Expo 移动壳使用 `apps/mobile-shell/src/host-bridge/mobileHostBridgeProtocol.ts` 承接 envelope、能力清单、request 校验和 replay 基础,`mobileHostBridgeFiles.ts` / `mobileHostBridgeShare.ts` 分别承接文件和分享能力,`mobileHostBridge.ts` 只作为对外 facade 与 method 分发入口,`apps/mobile-shell/App.tsx` 只装配 `apps/mobile-shell/src/shell/MobileShellApp.tsx`,由 `apps/mobile-shell/src/shell/mobileShell*.ts(x)` 承接 WebView 容器、URL、导航、网络、生命周期、安全区和 WebView policyTauri 桌面壳使用 `apps/desktop-shell/src-tauri/src/host_bridge/protocol.rs``files.rs``share.rs``mod.rs` 承接协议、文件、分享和分发,`apps/desktop-shell/src-tauri/src/shell/*.rs` 承接 WebView、托盘和容器行为,`main.rs` 只保留 Tauri builder / plugin / window 装配。
## HostBridge 消息协议
@@ -312,7 +312,7 @@ GameBridge 禁止:
2026-06-18 追加:移动壳安装包身份固定为 `world.genarrative.mobile`。Expo `app.json` 中的 `ios.bundleIdentifier``android.package` 使用同一包标识,应用版本为 `0.1.0`iOS `buildNumber` 从字符串 `"1"` 起步,Android `versionCode` 从整数 `1` 起步;后续每次生成可分发安装包时只递增构建号 / versionCode,产品版本号按发布节奏单独调整。`apps/mobile-shell/scripts/check-config.mjs` 会校验这些字段与 `package.json` 版本一致,避免 iOS、Android 和 H5 HostBridge `hostVersion` 发生静默漂移;`npm run mobile-shell:config` 会调用真实 Expo CLI 解析 public managed config,确认最终 Expo 配置仍保留同一包身份、深链、安全字段、插件权限和 HostBridge 版本。当前仍不写入假商店上架信息、假更新端点或占位渠道 SDK 配置。
2026-06-18 追加:移动壳 H5 入口 query 和 `host.getRuntime` 回包统一读取 `MOBILE_SHELL_HOST_VERSION`,该常量必须与 Expo `app.json` / `package.json` 版本一致。配置检查会拒绝在 `App.tsx``apps/mobile-shell/src/host-bridge/mobileHostBridge.ts` 内重新散落硬编码版本,避免升级移动安装包时 H5 首屏上下文和宿主 runtime 回读版本不一致。
2026-06-18 追加:移动壳 H5 入口 query 和 `host.getRuntime` 回包统一读取 `MOBILE_SHELL_HOST_VERSION`,该常量必须与 Expo `app.json` / `package.json` 版本一致。配置检查会拒绝在 `apps/mobile-shell/src/shell/MobileShellApp.tsx``apps/mobile-shell/src/host-bridge/mobileHostBridge.ts` 内重新散落硬编码版本,避免升级移动安装包时 H5 首屏上下文和宿主 runtime 回读版本不一致。
2026-06-18 追加:移动壳默认显式关闭 Expo OTA 更新,直到存在真实发布通道、更新端点、签名 / 回滚策略和团队发布流程后再接入。`app.json` 只允许 `updates.enabled=false`,不得配置 `runtimeVersion`、release channel、EAS channel、`expo-updates` 插件或移动端 crash / analytics / CodePush 依赖;`apps/mobile-shell/scripts/check-config.mjs` 和 Expo public config smoke 会共同拒绝这些发布通道能力被提前打开,移动壳生产入口、HostBridge 和 URL/runtime 配置也不得提前初始化 Sentry、Firebase Analytics、PostHog、Amplitude、Segment、CodePush 或 Expo Updates。由于移动壳运行依赖会从根安装树解析,根 H5 `package.json` 也不得直接安装这些移动端发布通道、崩溃上报、analytics 或 CodePush SDK;根 `package-lock.json` 也不得解析 `expo-updates`、Sentry、Firebase Analytics、PostHog、Amplitude、Segment、CodePush 等真实发布 / 观测 SDK。`expo-application` 可能由 Expo 自身传递解析,但项目不得把它作为 direct dependency 主动用于渠道逻辑。
@@ -415,7 +415,7 @@ GameBridge 禁止:
2026-06-18 追加:移动壳 HostBridge 消息入口增加来源校验。`onMessage` 不只依赖导航拦截和 `originWhitelist`,还会读取 `event.nativeEvent.url`,只有同源主站页面才能进入 `handleMobileHostBridgeMessage``about:blank`、外域 URL、协议降级或危险协议页面发来的消息全部丢弃,不返回 HostBridge 错误细节。该校验与 `navigation.openNativePage` 共用同源规则,防止历史中间页或异常页面在带完整 HostBridge 的 WebView 中发起宿主能力请求。
2026-06-18 追加:微信、移动端和桌面端桥接层文件结构按职责对齐。微信小程序的 `web-view`、支付、九宫切图和订阅消息桥接逻辑统一迁入 `miniprogram/host-bridge/wechatHostBridge*.js`,页面目录只保留页面生命周期、WXML/WXSS 和装配;移动壳拆成 `apps/mobile-shell/src/host-bridge/mobileHostBridgeProtocol.ts``mobileHostBridgeFiles.ts``mobileHostBridgeShare.ts` 和 facade `mobileHostBridge.ts`,与桌面端 `host_bridge/protocol.rs``files.rs``share.rs``mod.rs` 对齐;桌面壳 Rust 源码拆成 `apps/desktop-shell/src-tauri/src/host_bridge/*.rs``apps/desktop-shell/src-tauri/src/shell/*.rs`,其中 `shell/deep_link.rs``shell/tray.rs``shell/webview.rs` 分别承接深链、托盘和 WebView 容器行为,薄 `main.rs` 只声明两个模块并装配 Tauri builder / plugin / window。根级 `npm run check:native-shells` 会锁定三端桥接层目录清单,避免后续把能力逻辑重新散落到页面或桌面入口。
2026-06-18 追加:微信、移动端和桌面端桥接层文件结构按职责对齐。微信小程序的 `web-view`、支付、九宫切图和订阅消息桥接逻辑统一迁入 `miniprogram/host-bridge/wechatHostBridge*.js`,页面目录只保留页面生命周期、WXML/WXSS 和装配;移动壳拆成 `apps/mobile-shell/src/host-bridge/mobileHostBridgeProtocol.ts``mobileHostBridgeFiles.ts``mobileHostBridgeShare.ts` 和 facade `mobileHostBridge.ts`,与桌面端 `host_bridge/protocol.rs``files.rs``share.rs``mod.rs` 对齐;移动壳根 `App.tsx` 也保持薄入口,只装配 `src/shell/MobileShellApp.tsx`,WebView 容器、深链、网络、生命周期和安全策略全部留在 `src/shell/`桌面壳 Rust 源码拆成 `apps/desktop-shell/src-tauri/src/host_bridge/*.rs``apps/desktop-shell/src-tauri/src/shell/*.rs`,其中 `shell/deep_link.rs``shell/tray.rs``shell/webview.rs` 分别承接深链、托盘和 WebView 容器行为,薄 `main.rs` 只声明两个模块并装配 Tauri builder / plugin / window。根级 `npm run check:native-shells` 会锁定三端桥接层目录清单,避免后续把能力逻辑重新散落到页面、移动入口或桌面入口。
### Phase 4:宿主能力扩展
@@ -37,7 +37,7 @@ AI H5 sandbox
-> parent HostBridge adapter
```
桥接层文件结构按宿主统一为“协议 / 分发 / 宿主容器行为”三类职责。微信小程序的协议与可测试桥接函数统一放在 `miniprogram/host-bridge/wechatHostBridge*.js``miniprogram/shell/wechatShell*.js` 承接 Page 生命周期、`wx.*` 容器调用、WebView 容器行为、支付页和订阅页装配,页面目录只保留 `Page(createWechat...Page())` 装配;Expo 移动壳使用 `apps/mobile-shell/src/host-bridge/mobileHostBridgeProtocol.ts` 承接 envelope、能力清单、request 校验和 replay 基础,`mobileHostBridgeFiles.ts` / `mobileHostBridgeShare.ts` 分别承接文件和分享能力,`mobileHostBridge.ts` 只作为对外 facade 与 method 分发入口,`apps/mobile-shell/src/shell/mobileShell*.ts` 承接 URL、导航、网络、生命周期、安全区和 WebView policyTauri 桌面壳使用 `apps/desktop-shell/src-tauri/src/host_bridge/protocol.rs``files.rs``share.rs``mod.rs` 承接协议、文件、分享和分发,`apps/desktop-shell/src-tauri/src/shell/*.rs` 承接 WebView、托盘和容器行为,`main.rs` 只保留 Tauri builder / plugin / window 装配。`npm run check:native-shells` 会检查这些目录清单。
桥接层文件结构按宿主统一为“协议 / 分发 / 宿主容器行为”三类职责。微信小程序的协议与可测试桥接函数统一放在 `miniprogram/host-bridge/wechatHostBridge*.js``miniprogram/shell/wechatShell*.js` 承接 Page 生命周期、`wx.*` 容器调用、WebView 容器行为、支付页和订阅页装配,页面目录只保留 `Page(createWechat...Page())` 装配;Expo 移动壳使用 `apps/mobile-shell/src/host-bridge/mobileHostBridgeProtocol.ts` 承接 envelope、能力清单、request 校验和 replay 基础,`mobileHostBridgeFiles.ts` / `mobileHostBridgeShare.ts` 分别承接文件和分享能力,`mobileHostBridge.ts` 只作为对外 facade 与 method 分发入口,`apps/mobile-shell/App.tsx` 只装配 `apps/mobile-shell/src/shell/MobileShellApp.tsx`,由 `apps/mobile-shell/src/shell/mobileShell*.ts(x)` 承接 WebView 容器、URL、导航、网络、生命周期、安全区和 WebView policyTauri 桌面壳使用 `apps/desktop-shell/src-tauri/src/host_bridge/protocol.rs``files.rs``share.rs``mod.rs` 承接协议、文件、分享和分发,`apps/desktop-shell/src-tauri/src/shell/*.rs` 承接 WebView、托盘和容器行为,`main.rs` 只保留 Tauri builder / plugin / window 装配。`npm run check:native-shells` 会检查这些目录清单。
## 首批能力
+9
View File
@@ -35,6 +35,7 @@ const expectedMobileHostBridgeFiles = [
'mobileHostBridgeShare.ts',
];
const expectedMobileShellFiles = [
'MobileShellApp.tsx',
'mobileShellDeepLink.test.ts',
'mobileShellDeepLink.ts',
'mobileShellLifecycle.test.ts',
@@ -276,6 +277,14 @@ function assertHostBridgeLayerLayout() {
'mobile shell bridge files',
);
const mobileAppSource = fs.readFileSync('apps/mobile-shell/App.tsx', 'utf8');
if (!mobileAppSource.includes("import MobileShellApp from './src/shell/MobileShellApp';")) {
throw new Error('mobile shell App.tsx must import from apps/mobile-shell/src/shell');
}
if (mobileAppSource.includes('./src/host-bridge/')) {
throw new Error('mobile shell App.tsx must not import HostBridge directly');
}
const desktopEntrypointRustFiles = fs
.readdirSync('apps/desktop-shell/src-tauri/src', { withFileTypes: true })
.filter((entry) => entry.isFile() && entry.name.endsWith('.rs'))