From 981755413dc300723e76cd0d7d3f4191e6de5db5 Mon Sep 17 00:00:00 2001 From: kdletters Date: Sat, 20 Jun 2026 18:40:03 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=BC=BA=E7=A7=BB=E5=8A=A8=E5=A3=B3?= =?UTF-8?q?=E8=83=BD=E5=8A=9B=E6=B5=81=E7=A8=8B=E9=97=A8=E7=A6=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 根级原生壳检查反查 Expo 关键能力真实流程 宿主壳方案文档记录移动能力到实现与测试合同 项目记忆同步原生壳能力真实链路约束 --- .../shared-memory/decision-log.md | 4 +- ...ExpoReactNative与Tauri宿主壳方案-2026-06-17.md | 2 +- scripts/check-native-shells.mjs | 227 ++++++++++++++++++ 3 files changed, 230 insertions(+), 3 deletions(-) diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 9f4bbf4d7..eb12a1f52 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -3067,8 +3067,8 @@ ## 2026-06-20 原生壳能力声明必须绑定真实链路 -- 背景：桌面壳 capability profile 已声明一组 HostBridge request 能力，H5 平台入口也通过 `navigation.openNativePage` 打开 `/child-motion-demo` 这类受控内置玩法路由；如果门禁只检查“有 method case”或“文件被扫描”，未来可能退化成 fallback-only 分支或普通 Web 跳转而不被发现。 -- 决策：桌面壳配置检查必须反查每个已声明 request capability 对应的真实模块委托，并拒绝由 `unsupported_method`、`unsupported_capability` 或 fallback-only case 支撑的声明能力；根级 `check:native-shells` 新增 H5 native app route flow 合约，锁定 `/child-motion-demo` 的 `navigateHostNativePage` 调用、浏览器 fallback、路由表和命名交互测试。 +- 背景：桌面壳 capability profile 已声明一组 HostBridge request 能力，Expo 移动壳也声明本地通知、拍照、扫码、网络事件和分享等原生能力，H5 平台入口还会通过 `navigation.openNativePage` 打开 `/child-motion-demo` 这类受控内置玩法路由；如果门禁只检查“有 method case”或“文件被扫描”，未来可能退化成 fallback-only 分支或普通 Web 跳转而不被发现。 +- 决策：桌面壳配置检查必须反查每个已声明 request capability 对应的真实模块委托，并拒绝由 `unsupported_method`、`unsupported_capability` 或 fallback-only case 支撑的声明能力；根级 `check:native-shells` 新增 H5 native app route flow 合约，锁定 `/child-motion-demo` 的 `navigateHostNativePage` 调用、浏览器 fallback、路由表和命名交互测试；Expo 移动壳关键 capability flow 合约必须反查共享移动 profile、真实 Expo / React Native API、权限或配置片段、宿主分发文件和对应测试清单。 - 影响范围：`apps/desktop-shell/scripts/check-config.mjs`、`scripts/check-native-shells.mjs`、宿主壳能力统一协议文档。 - 验证方式：`npm run check:native-shells`、`npm run check:encoding`、`git diff --check`。 diff --git a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md index b6ab759e3..939971686 100644 --- a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md +++ b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md @@ -266,7 +266,7 @@ GameBridge 禁止： - 每个请求必须有超时；H5 的 React Native WebView transport 和 Tauri `invoke` transport 都必须在前端侧按 `timeoutMs` 释放请求，默认请求超时、最大请求超时和用户交互长操作超时以 `packages/shared/src/contracts/hostBridge.ts` 的 `HOST_BRIDGE_DEFAULT_REQUEST_TIMEOUT_MS` / `HOST_BRIDGE_MAX_REQUEST_TIMEOUT_MS` / `HOST_BRIDGE_USER_INTERACTION_TIMEOUT_MS` 为唯一来源，宿主侧执行超时也只能返回标准 HostBridge 错误。重复 `id` 不得重复执行支付、登录、受控分享动作、文件导入导出、本地通知等宿主副作用；Expo 和 Tauri 壳都必须按 request id 回放首次完成结果，已完成响应缓存上限以共享契约 `HOST_BRIDGE_RESPONSE_CACHE_MAX` 为唯一来源。 - HostBridge 的 capability profile、宿主上下文 query 字段和值、文件 MIME 清单、导入 / 导出体积上限、文件名 fallback / 长度上限、request id 长度、角标上限、剪贴板文本长度、二维码文本长度、本地通知标题 / 正文长度、移动端 Android 本地通知 channel id 和桌面网络探测超时都必须以 `packages/shared/src/contracts/hostBridge.ts` 为声明来源；Expo 移动壳直接导入共享 profile 和契约常量，微信小程序壳和 Tauri 壳分别保留小程序 CommonJS / Rust 运行时代码镜像并由测试和配置门禁反查共享契约。 - 能力按 `capabilities` / `hostCapabilities` 下发，H5 会过滤未知能力，并根据声明结果决定是否展示入口、发起宿主请求或走 fallback；进入 `native_app` 后主 App 会再通过真实 `host.getRuntime` 回读一次宿主 runtime 并缓存能力，用来补齐裁剪壳或旧入口 URL 缺少 `hostCapabilities` 的场景，该回读请求的短超时以共享契约 `HOST_BRIDGE_RUNTIME_REFRESH_TIMEOUT_MS` 为唯一来源。不能只凭 `native_app` 宿主类型假设能力可用。 -- 壳能力声明与三端壳验收必须通过 `npm run check:native-shells` 统一校验；排查单端问题时可再分别运行微信壳测试集合、`npm run mobile-shell:typecheck`、`npm run mobile-shell:test`、`npm run mobile-shell:config`、`npm run mobile-shell:export`、`npm run desktop-shell:typecheck`、`npm run desktop-shell:test` 或 `npm run desktop-shell:build -- --no-bundle`。声明的 capability 必须来自共享 HostBridge profile 并存在于共享白名单，壳 runtime 回包、H5 URL `hostCapabilities`、壳实现、文件载荷边界、微信 WebView / 支付 / 订阅 / 分享桥接行为、微信小程序页面路由、WebView source query、微信请求头运行时标记、H5 runtime parser、H5 路由保留字段、微信壳 H5 / API HTTPS 域名格式、Expo managed config、移动端 production bundle、桌面 release 构建入口和微信 / Expo / Tauri 三端生产源码临时替身词扫描不得漂移。微信小程序壳不使用 Expo / Tauri 式统一 request dispatcher，但每个声明 capability 都必须在根级门禁中映射到真实流程文件、关键 `wx.*` 或页面工厂调用和对应测试清单。 +- 壳能力声明与三端壳验收必须通过 `npm run check:native-shells` 统一校验；排查单端问题时可再分别运行微信壳测试集合、`npm run mobile-shell:typecheck`、`npm run mobile-shell:test`、`npm run mobile-shell:config`、`npm run mobile-shell:export`、`npm run desktop-shell:typecheck`、`npm run desktop-shell:test` 或 `npm run desktop-shell:build -- --no-bundle`。声明的 capability 必须来自共享 HostBridge profile 并存在于共享白名单，壳 runtime 回包、H5 URL `hostCapabilities`、壳实现、文件载荷边界、微信 WebView / 支付 / 订阅 / 分享桥接行为、微信小程序页面路由、WebView source query、微信请求头运行时标记、H5 runtime parser、H5 路由保留字段、微信壳 H5 / API HTTPS 域名格式、Expo managed config、移动端 production bundle、桌面 release 构建入口和微信 / Expo / Tauri 三端生产源码临时替身词扫描不得漂移。微信小程序壳不使用 Expo / Tauri 式统一 request dispatcher，但每个声明 capability 都必须在根级门禁中映射到真实流程文件、关键 `wx.*` 或页面工厂调用和对应测试清单；Expo 移动壳的关键能力也必须在根级门禁中映射到真实 Expo / React Native API、权限或配置片段、宿主分发文件和对应测试清单。 - Expo SDK、React Native、`react-native-webview`、Tauri CLI、Tauri Rust crate 和桌面 Cargo 插件版本属于宿主壳行为边界。升级这些依赖前必须同步更新壳配置检查、`package-lock.json` / `Cargo.lock` 解析版本、本文档和对应验证结果，不能只改 package / Cargo 版本让生产壳行为静默漂移。 - 登录和支付能力在真实 SDK、渠道流程、后端契约和失败回退全部落地前不得进入 Expo / Tauri capabilities，也不得写进入口 URL `hostCapabilities`；两端配置检查会拒绝 `auth.requestLogin` 和 `payment.request` 的伪声明。 - 宿主壳不得把长期 token、支付密钥或用户敏感资料回传给 H5。 diff --git a/scripts/check-native-shells.mjs b/scripts/check-native-shells.mjs index 4fea83d36..445604f9b 100644 --- a/scripts/check-native-shells.mjs +++ b/scripts/check-native-shells.mjs @@ -239,6 +239,170 @@ const wechatCapabilityFlowContracts = [ ], }, ]; +const mobileCapabilityFlowContracts = [ + { + capability: 'notification.showLocal', + files: [ + 'apps/mobile-shell/app.json', + 'apps/mobile-shell/src/host-bridge/dispatch.ts', + 'apps/mobile-shell/src/host-bridge/notifications.ts', + 'apps/mobile-shell/scripts/check-config.mjs', + 'apps/mobile-shell/scripts/check-expo-config.mjs', + nativeShellPlanPath, + ], + snippets: [ + ['apps/mobile-shell/app.json', 'android.permission.POST_NOTIFICATIONS'], + [ + 'apps/mobile-shell/src/host-bridge/dispatch.ts', + 'showMobileHostBridgeLocalNotification(request)', + ], + [ + 'apps/mobile-shell/src/host-bridge/notifications.ts', + 'Notifications.scheduleNotificationAsync', + ], + [ + 'apps/mobile-shell/src/host-bridge/notifications.ts', + 'Notifications.setNotificationChannelAsync', + ], + [ + 'apps/mobile-shell/src/host-bridge/notifications.ts', + 'HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID', + ], + [ + 'apps/mobile-shell/scripts/check-config.mjs', + 'HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID', + ], + [ + 'apps/mobile-shell/scripts/check-expo-config.mjs', + 'android.permission.POST_NOTIFICATIONS', + ], + [nativeShellPlanPath, 'Expo 移动壳的关键能力'], + ], + tests: [ + 'apps/mobile-shell/src/host-bridge/notifications.test.ts', + 'apps/mobile-shell/src/host-bridge/bridge.test.ts', + ], + }, + { + capability: 'file.captureImage', + files: [ + 'apps/mobile-shell/app.json', + 'apps/mobile-shell/src/host-bridge/dispatch.ts', + 'apps/mobile-shell/src/host-bridge/files.ts', + 'apps/mobile-shell/scripts/check-config.mjs', + nativeShellPlanPath, + ], + snippets: [ + ['apps/mobile-shell/app.json', 'expo-image-picker'], + [ + 'apps/mobile-shell/src/host-bridge/dispatch.ts', + 'captureMobileHostBridgeImageFile(request)', + ], + [ + 'apps/mobile-shell/src/host-bridge/files.ts', + 'ImagePicker.requestCameraPermissionsAsync', + ], + [ + 'apps/mobile-shell/src/host-bridge/files.ts', + 'ImagePicker.launchCameraAsync', + ], + ['apps/mobile-shell/scripts/check-config.mjs', 'file.captureImage'], + [nativeShellPlanPath, 'Expo 移动壳的关键能力'], + ], + tests: [ + 'apps/mobile-shell/src/host-bridge/files.test.ts', + 'apps/mobile-shell/src/host-bridge/bridge.test.ts', + ], + }, + { + capability: 'scanner.scanQrCode', + files: [ + 'apps/mobile-shell/app.json', + 'apps/mobile-shell/src/host-bridge/dispatch.ts', + 'apps/mobile-shell/src/host-bridge/scanner.ts', + 'apps/mobile-shell/src/shell/QrScannerOverlay.tsx', + 'apps/mobile-shell/scripts/check-config.mjs', + nativeShellPlanPath, + ], + snippets: [ + ['apps/mobile-shell/app.json', 'expo-camera'], + [ + 'apps/mobile-shell/src/host-bridge/dispatch.ts', + 'scanMobileHostBridgeQrCode(request)', + ], + [ + 'apps/mobile-shell/src/host-bridge/scanner.ts', + 'HOST_BRIDGE_SCANNER_TIMEOUT_MS', + ], + [ + 'apps/mobile-shell/src/shell/QrScannerOverlay.tsx', + 'Camera.requestCameraPermissionsAsync', + ], + ['apps/mobile-shell/src/shell/QrScannerOverlay.tsx', 'CameraView'], + ['apps/mobile-shell/scripts/check-config.mjs', 'scanner.scanQrCode'], + [nativeShellPlanPath, 'Expo 移动壳的关键能力'], + ], + tests: [ + 'apps/mobile-shell/src/host-bridge/scanner.test.ts', + 'apps/mobile-shell/src/shell/QrScannerOverlay.test.tsx', + 'apps/mobile-shell/src/shell/ShellApp.test.tsx', + 'apps/mobile-shell/src/host-bridge/bridge.test.ts', + ], + }, + { + capability: 'network.statusChanged', + files: [ + 'apps/mobile-shell/src/shell/network.ts', + 'apps/mobile-shell/src/shell/ShellApp.tsx', + 'apps/mobile-shell/scripts/check-config.mjs', + nativeShellPlanPath, + ], + snippets: [ + [ + 'apps/mobile-shell/src/shell/network.ts', + 'Network.addNetworkStateListener', + ], + [ + 'apps/mobile-shell/src/shell/ShellApp.tsx', + "injectHostBridgeEvent('network.statusChanged', payload)", + ], + [ + 'apps/mobile-shell/src/shell/ShellApp.tsx', + "logMobileHostEventFailure('network.statusChanged', error)", + ], + ['apps/mobile-shell/scripts/check-config.mjs', 'network.statusChanged'], + [nativeShellPlanPath, 'Expo 移动壳的关键能力'], + ], + tests: [ + 'apps/mobile-shell/src/shell/network.test.ts', + 'apps/mobile-shell/src/shell/ShellApp.test.tsx', + 'apps/mobile-shell/src/host-bridge/bridge.test.ts', + ], + }, + { + capability: 'share.open', + files: [ + 'apps/mobile-shell/src/host-bridge/dispatch.ts', + 'apps/mobile-shell/src/host-bridge/share.ts', + 'apps/mobile-shell/scripts/check-config.mjs', + nativeShellPlanPath, + ], + snippets: [ + ['apps/mobile-shell/src/host-bridge/dispatch.ts', 'openShare(request)'], + ['apps/mobile-shell/src/host-bridge/share.ts', 'Share.share'], + [ + 'apps/mobile-shell/src/host-bridge/share.ts', + 'normalizeHostBridgeShareOpenPayload', + ], + ['apps/mobile-shell/scripts/check-config.mjs', 'share.open'], + [nativeShellPlanPath, 'Expo 移动壳的关键能力'], + ], + tests: [ + 'apps/mobile-shell/src/host-bridge/share.test.ts', + 'apps/mobile-shell/src/host-bridge/bridge.test.ts', + ], + }, +]; const h5NativeAppRouteFlowContracts = [ { route: '/child-motion-demo', @@ -2043,6 +2207,66 @@ function assertWechatMiniProgramCapabilityFlows() { } } +function assertExpoMobileCapabilityFlows() { + const sharedContractSource = fs.readFileSync(sharedHostBridgeContractPath, 'utf8'); + const declaredCapabilities = extractTsStringArray( + sharedContractSource, + 'HOST_BRIDGE_EXPO_MOBILE_BASE_CAPABILITIES', + ); + const declaredCapabilitySet = new Set(declaredCapabilities); + const contractedCapabilities = mobileCapabilityFlowContracts.map( + ({ capability }) => capability, + ); + + assertUniqueList( + contractedCapabilities, + 'Expo mobile capability flow contracts', + ); + + const mobileShellTestSet = new Set( + expectedMobileHostBridgeFiles + .filter((fileName) => fileName.includes('.test.')) + .map((fileName) => `apps/mobile-shell/src/host-bridge/${fileName}`) + .concat( + expectedMobileShellFiles + .filter((fileName) => fileName.includes('.test.')) + .map((fileName) => `apps/mobile-shell/src/shell/${fileName}`), + ), + ); + + for (const contract of mobileCapabilityFlowContracts) { + if (!declaredCapabilitySet.has(contract.capability)) { + throw new Error( + `Expo mobile capability flow contract declared for missing capability: ${contract.capability}`, + ); + } + + for (const filePath of contract.files) { + if (!fs.existsSync(filePath)) { + throw new Error( + `Expo mobile ${contract.capability} flow file is missing: ${filePath}`, + ); + } + } + + for (const [filePath, snippet] of contract.snippets) { + assertFileIncludesSnippet( + filePath, + snippet, + `Expo mobile ${contract.capability} flow`, + ); + } + + for (const testPath of contract.tests) { + if (!mobileShellTestSet.has(testPath)) { + throw new Error( + `Expo mobile ${contract.capability} flow test is not part of mobile-shell:test: ${testPath}`, + ); + } + } + } +} + function assertH5NativeAppRouteFlows() { const h5HostBridgeTestSet = new Set(h5HostBridgeTests); for (const contract of h5NativeAppRouteFlowContracts) { @@ -2537,6 +2761,9 @@ assertWechatMiniProgramRouteParity(); console.log('[check:native-shells] wechat-mini-program-capability-flows'); assertWechatMiniProgramCapabilityFlows(); +console.log('[check:native-shells] expo-mobile-capability-flows'); +assertExpoMobileCapabilityFlows(); + console.log('[check:native-shells] h5-native-app-route-flows'); assertH5NativeAppRouteFlows();