接入 Expo 移动壳深链入口

新增移动壳 deep link 到同源 H5 路径的解析与运行时监听

配置移动壳真实品牌图标、iOS associated domain 和 Android app link

补充移动壳配置守门、单测和宿主壳文档记忆

apps/mobile-shell/App.tsx

@@ -8,28 +8,58 @@ import {
   handleMobileHostBridgeMessage,
   MOBILE_HOST_CAPABILITIES,
 } from './src/mobileHostBridge';
+import { buildMobileShellUrlFromDeepLink } from './src/mobileShellDeepLink';
 import { shouldOpenInMobileShellWebView } from './src/mobileShellNavigation';
 import { buildMobileShellUrl } from './src/mobileShellUrl';
 
 const defaultWebUrl = 'http://127.0.0.1:3000/';
+const hostVersion = '0.1.0';
 
 export default function App() {
   const webViewRef = useRef<WebView>(null);
   const [canGoBack, setCanGoBack] = useState(false);
-  const webUrl = useMemo(
-    () =>
-      buildMobileShellUrl(
-        process.env.EXPO_PUBLIC_GENARRATIVE_WEB_URL || defaultWebUrl,
-        {
-          platform: Platform.OS === 'ios' ? 'ios' : 'android',
-          hostVersion: '0.1.0',
-          capabilities: MOBILE_HOST_CAPABILITIES,
-        },
-      ),
+  const baseWebUrl = process.env.EXPO_PUBLIC_GENARRATIVE_WEB_URL || defaultWebUrl;
+  const mobileShellUrlOptions = useMemo(
+    () => ({
+      platform: Platform.OS === 'ios' ? 'ios' as const : 'android' as const,
+      hostVersion,
+      capabilities: MOBILE_HOST_CAPABILITIES,
+    }),
     [],
   );
+  const [webUrl, setWebUrl] = useState(() =>
+    buildMobileShellUrl(baseWebUrl, mobileShellUrlOptions),
+  );
   const allowedWebOrigin = useMemo(() => new URL(webUrl).origin, [webUrl]);
 
+  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',

apps/mobile-shell/app.json

@@ -5,15 +5,35 @@
     "scheme": "genarrative",
     "version": "0.1.0",
     "orientation": "portrait",
+    "icon": "./assets/icon.png",
     "userInterfaceStyle": "automatic",
     "assetBundlePatterns": [
       "**/*"
     ],
     "ios": {
-      "supportsTablet": true
+      "supportsTablet": true,
+      "associatedDomains": [
+        "applinks:app.genarrative.world"
+      ]
     },
     "android": {
-      "package": "world.genarrative.mobile"
+      "package": "world.genarrative.mobile",
+      "intentFilters": [
+        {
+          "action": "VIEW",
+          "autoVerify": true,
+          "data": [
+            {
+              "scheme": "https",
+              "host": "app.genarrative.world"
+            }
+          ],
+          "category": [
+            "BROWSABLE",
+            "DEFAULT"
+          ]
+        }
+      ]
     },
     "extra": {
       "genarrativeHostBridgeVersion": 1

apps/mobile-shell/package.json

@@ -9,7 +9,7 @@
     "android": "expo run:android",
     "ios": "expo run:ios",
     "test": "vitest run -c vitest.config.ts",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit && node scripts/check-config.mjs"
   },
   "dependencies": {
     "@expo/metro-runtime": "^56.0.15",

apps/mobile-shell/scripts/check-config.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+
+import { PNG } from 'pngjs';
+
+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 iconPath = new URL('../assets/icon.png', import.meta.url);
+const icon = PNG.sync.read(fs.readFileSync(iconPath));
+
+if (appConfig.scheme !== 'genarrative') {
+  throw new Error('mobile shell scheme must be genarrative');
+}
+
+if (appConfig.icon !== './assets/icon.png') {
+  throw new Error('mobile shell must use the real brand icon asset');
+}
+
+if (icon.width < 512 || icon.height < 512) {
+  throw new Error('mobile shell icon must be a production-size brand asset');
+}
+
+if (!appConfig.ios?.associatedDomains?.includes('applinks:app.genarrative.world')) {
+  throw new Error('mobile shell iOS associated domain is missing');
+}
+
+const androidFilter = appConfig.android?.intentFilters?.find((filter) =>
+  filter?.data?.some(
+    (entry) =>
+      entry?.scheme === 'https' &&
+      entry?.host === 'app.genarrative.world',
+  ),
+);
+if (!androidFilter) {
+  throw new Error('mobile shell Android app link filter is missing');
+}
+
+for (const snippet of [
+  'Linking.getInitialURL()',
+  "Linking.addEventListener('url'",
+  'buildMobileShellUrlFromDeepLink',
+]) {
+  if (!appSource.includes(snippet)) {
+    throw new Error(`mobile shell App missing ${snippet}`);
+  }
+}

apps/mobile-shell/src/mobileShellDeepLink.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, test } from 'vitest';
+
+import { buildMobileShellUrlFromDeepLink } from './mobileShellDeepLink';
+
+const options = {
+  platform: 'ios' as const,
+  hostVersion: '0.1.0',
+  capabilities: ['host.getRuntime' as const],
+};
+
+describe('buildMobileShellUrlFromDeepLink', () => {
+  test('把原生 scheme deep link 映射成同源 H5 目标页', () => {
+    const url = new URL(
+      buildMobileShellUrlFromDeepLink(
+        'genarrative://open/works/detail?work=PZ-1',
+        'https://app.genarrative.world/',
+        options,
+      ),
+    );
+
+    expect(url.origin).toBe('https://app.genarrative.world');
+    expect(url.pathname).toBe('/works/detail');
+    expect(url.searchParams.get('work')).toBe('PZ-1');
+    expect(url.searchParams.get('clientRuntime')).toBe('native_app');
+    expect(url.searchParams.get('hostShell')).toBe('expo_mobile');
+  });
+
+  test('把同源 universal link 映射成带宿主上下文的 H5 URL', () => {
+    const url = new URL(
+      buildMobileShellUrlFromDeepLink(
+        'https://app.genarrative.world/creation/puzzle#draft',
+        'https://app.genarrative.world/',
+        options,
+      ),
+    );
+
+    expect(url.pathname).toBe('/creation/puzzle');
+    expect(url.hash).toBe('#draft');
+    expect(url.searchParams.get('hostCapabilities')).toBe('host.getRuntime');
+  });
+
+  test('外域和危险协议回退到默认首页', () => {
+    const external = new URL(
+      buildMobileShellUrlFromDeepLink(
+        'https://example.com/works/detail?work=PZ-1',
+        'https://app.genarrative.world/',
+        options,
+      ),
+    );
+    const unsafe = new URL(
+      buildMobileShellUrlFromDeepLink(
+        'javascript:alert(1)',
+        'https://app.genarrative.world/',
+        options,
+      ),
+    );
+
+    expect(external.origin).toBe('https://app.genarrative.world');
+    expect(external.pathname).toBe('/');
+    expect(unsafe.origin).toBe('https://app.genarrative.world');
+    expect(unsafe.pathname).toBe('/');
+  });
+
+  test('协议相对外域 URL 不会被装进移动壳 WebView', () => {
+    const url = new URL(
+      buildMobileShellUrlFromDeepLink(
+        '//example.com/works/detail?work=PZ-1',
+        'https://app.genarrative.world/',
+        options,
+      ),
+    );
+
+    expect(url.origin).toBe('https://app.genarrative.world');
+    expect(url.pathname).toBe('/');
+  });
+});

apps/mobile-shell/src/mobileShellDeepLink.ts

@@ -0,0 +1,64 @@
+import { buildMobileShellUrl, type MobileShellUrlOptions } from './mobileShellUrl';
+
+const supportedHosts = new Set(['open', 'app']);
+
+function extractPathFromNativeUrl(url: URL) {
+  if (supportedHosts.has(url.hostname)) {
+    return `${url.pathname}${url.search}${url.hash}`;
+  }
+
+  return `${url.hostname ? `/${url.hostname}` : ''}${url.pathname}${url.search}${url.hash}`;
+}
+
+function resolveTargetPath(rawUrl: string, webOrigin: string) {
+  try {
+    const url = new URL(rawUrl);
+    if (url.protocol === 'genarrative:') {
+      return extractPathFromNativeUrl(url);
+    }
+
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      return null;
+    }
+
+    if (url.origin !== webOrigin) {
+      return null;
+    }
+
+    return `${url.pathname}${url.search}${url.hash}`;
+  } catch {
+    if (!rawUrl.startsWith('/') && !rawUrl.startsWith('#')) {
+      return null;
+    }
+
+    try {
+      const relativeUrl = new URL(rawUrl, webOrigin);
+      if (relativeUrl.origin !== webOrigin) {
+        return null;
+      }
+
+      return `${relativeUrl.pathname}${relativeUrl.search}${relativeUrl.hash}`;
+    } catch {
+      return null;
+    }
+  }
+}
+
+export function buildMobileShellUrlFromDeepLink(
+  rawUrl: string | null | undefined,
+  baseWebUrl: string,
+  options: MobileShellUrlOptions,
+) {
+  const defaultUrl = buildMobileShellUrl(baseWebUrl, options);
+  if (!rawUrl) {
+    return defaultUrl;
+  }
+
+  const webOrigin = new URL(baseWebUrl).origin;
+  const targetPath = resolveTargetPath(rawUrl, webOrigin);
+  if (!targetPath) {
+    return defaultUrl;
+  }
+
+  return buildMobileShellUrl(new URL(targetPath, webOrigin).toString(), options);
+}

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/`。壳只声明并实现真实可用能力；桌面壳已通过 Tauri clipboard-manager 接入 `clipboard.writeText`，登录、支付、桌面分享等未接入真实 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 路径，桌面壳已通过 Tauri clipboard-manager 接入 `clipboard.writeText`，登录、支付、桌面分享等未接入真实 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`。

docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md

@@ -238,7 +238,7 @@ GameBridge 禁止：
 - iOS / Android 深链打开作品详情、创作页和邀请码。
 - 登录和支付先 fallback 到 H5；只把能力边界跑通。
 
-当前状态：已新增 `apps/mobile-shell/`，通过 Expo development build 运行，`react-native-webview` 加载 H5 URL 并附加 `native_app` 宿主 query。首轮真实能力包括 `host.getRuntime`、`share.open`、`share.setTarget`、`app.openExternalUrl`、`clipboard.writeText`、`haptics.impact` 和 Android 返回键回退；登录、支付和原生页跳转尚未接入渠道 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`、`share.open`、`share.setTarget`、`app.openExternalUrl`、`clipboard.writeText`、`haptics.impact` 和 Android 返回键回退；登录、支付和原生页跳转尚未接入渠道 SDK 时明确返回 unsupported，让 H5 fallback 承接。
 
 ### Phase 3：Tauri 桌面壳 MVP