From 4b269c7bc29d42842b3b559f3788851a857932a6 Mon Sep 17 00:00:00 2001 From: kdletters Date: Fri, 19 Jun 2026 15:25:31 +0800 Subject: [PATCH] =?UTF-8?q?=E6=94=B6=E7=B4=A7=20H5=20=E8=A7=A6=E8=A7=89?= =?UTF-8?q?=E5=8F=8D=E9=A6=88=E8=BD=BD=E8=8D=B7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 在 H5 HostBridge facade 发起触觉反馈前按共享 style 清单归一化 增加触觉反馈载荷归一化测试和总门禁反查 同步宿主壳协议文档和共享决策记录 --- .../shared-memory/decision-log.md | 2 +- ...前端架构】宿主壳能力统一协议-2026-06-17.md | 2 +- scripts/check-native-shells.mjs | 12 ++++++ src/services/host-bridge/hostBridge.test.ts | 40 +++++++++++++++++++ src/services/host-bridge/hostBridge.ts | 8 +++- 5 files changed, 61 insertions(+), 3 deletions(-) diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 6e3193a02..10f33d969 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -2571,7 +2571,7 @@ ## 2026-06-19 HostBridge 载荷边界单一来源 - 背景：文件导入导出、剪贴板、角标、本地通知和 request id 都已经在 Expo 与 Tauri 两套壳里有运行时校验；如果 MIME 清单、字节上限或文本长度只靠人工同步，新增文件类型或调整上限时会出现 H5 契约、移动壳和桌面壳互相漂移。 -- 决策：`packages/shared/src/contracts/hostBridge.ts` 是 HostBridge 载荷边界的声明来源，导出文本 / 图片 / 音频 MIME 清单、文档导入 MIME 清单、导入 / 导出字节上限、导出文件名 fallback / 长度上限、request id 长度、角标上限、剪贴板文本长度和本地通知标题 / 正文长度。Expo 移动壳必须直接导入这些共享常量，`apps/mobile-shell/scripts/check-config.mjs` 会拒绝移动壳重新本地声明文件大小或 MIME 清单；移动壳 `file.importText` / `file.importDocument` / `file.importAudio` 必须在读取文本内容或 base64 前，通过 picker `size` 或 Expo `File.size` 拿到可信 byte count 并完成上限校验，无法拿到可信大小时直接拒绝导入。`clipboard.writeText` / `clipboard.readText` 两个方向都必须执行同一个 100000 字符上限；H5 facade 发起 `clipboard.writeText` 前先按共享上限归一化 payload，Expo 与 Tauri 壳仍必须再次执行同一边界，不允许只信 H5 facade 的预校验。`file.exportText` 的可选 `mimeType` 只能来自 `HOST_BRIDGE_TEXT_MIME_TYPES`，缺省为 `text/plain`，Expo 与 Tauri 都必须拒绝图片、音频或二进制 MIME，避免 H5 通过文本导出通道伪装落盘；两端 config check 必须反查该边界。Tauri 桌面壳按 Rust 运行时代码镜像实现，`apps/desktop-shell/scripts/check-config.mjs` 必须反查共享契约并拒绝漂移。 +- 决策：`packages/shared/src/contracts/hostBridge.ts` 是 HostBridge 载荷边界的声明来源，导出文本 / 图片 / 音频 MIME 清单、文档导入 MIME 清单、导入 / 导出字节上限、导出文件名 fallback / 长度上限、request id 长度、角标上限、剪贴板文本长度、触觉反馈 style 和本地通知标题 / 正文长度。Expo 移动壳必须直接导入这些共享常量，`apps/mobile-shell/scripts/check-config.mjs` 会拒绝移动壳重新本地声明文件大小或 MIME 清单；移动壳 `file.importText` / `file.importDocument` / `file.importAudio` 必须在读取文本内容或 base64 前，通过 picker `size` 或 Expo `File.size` 拿到可信 byte count 并完成上限校验，无法拿到可信大小时直接拒绝导入。`clipboard.writeText` / `clipboard.readText` 两个方向都必须执行同一个 100000 字符上限；H5 facade 发起 `clipboard.writeText` 前先按共享上限归一化 payload，Expo 与 Tauri 壳仍必须再次执行同一边界，不允许只信 H5 facade 的预校验。H5 facade 发起 `haptics.impact` 前也必须按共享 style 清单归一化，未知 style 不发往宿主，Expo 壳仍二次拒绝未知值。`file.exportText` 的可选 `mimeType` 只能来自 `HOST_BRIDGE_TEXT_MIME_TYPES`，缺省为 `text/plain`，Expo 与 Tauri 都必须拒绝图片、音频或二进制 MIME，避免 H5 通过文本导出通道伪装落盘；两端 config check 必须反查该边界。Tauri 桌面壳按 Rust 运行时代码镜像实现，`apps/desktop-shell/scripts/check-config.mjs` 必须反查共享契约并拒绝漂移。 - 影响范围：`packages/shared/src/contracts/hostBridge.ts`、`apps/mobile-shell/src/host-bridge/files.ts`、`apps/mobile-shell/scripts/check-config.mjs`、`apps/desktop-shell/src-tauri/src/host_bridge/`、`apps/desktop-shell/scripts/check-config.mjs`、Expo / Tauri HostBridge 方案文档。 - 验证方式：`npm run mobile-shell:typecheck`、`npm run desktop-shell:typecheck`、`npm run test -- packages/shared/src/contracts/hostBridge.test.ts`、`npm run check:native-shells`、`npm run check:encoding`、`git diff --check`。 diff --git a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md index 2be16bc23..548f2c66b 100644 --- a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md +++ b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md @@ -63,7 +63,7 @@ Tauri 桌面壳启动时必须按 `label="main"` 解析 `tauri.conf.json` 主窗 - `openHostShareGrid()`：微信小程序九宫格切图页。 - `writeHostClipboardText()`：原生 App 宿主的受控剪贴板入口。H5 复制服务在 `native_app` 中优先通过 `clipboard.writeText` 写入 Expo / Tauri 系统剪贴板；H5 facade 发起请求前先按共享契约 `HOST_BRIDGE_CLIPBOARD_TEXT_MAX_LENGTH` 归一化 payload，减少 WebView bridge 承载超长文本；两端壳写入前也必须执行同一上限截断，不能让 H5 透传超长剪贴板内容；宿主不可用、拒绝或返回 unsupported 时继续回退到浏览器 Clipboard API 和 legacy selection copy。 - `readHostClipboardText()`：原生 App 宿主的受控剪贴板读取入口。H5 只能读取纯文本结果，宿主返回内容会按 HostBridge 契约限制到 100000 字符；Expo 移动壳通过 `expo-clipboard` 读取系统剪贴板文本，Tauri 桌面壳通过 Rust 侧 `clipboard-manager` 读取系统剪贴板文本。该能力不读取图片、HTML、文件列表或剪贴板监听事件，不把 Tauri / Expo 剪贴板插件 API 直接暴露给 H5；宿主未声明或读取失败时由 H5 视作失败并保留原流程。个人中心的邀请码和兑换码弹窗只在宿主声明 `clipboard.readText` 时显示“粘贴”，读取到的纯文本只填入现有输入框，不自动提交、不代表兑换成功。 -- `requestHostHapticsImpact()`：原生 App 宿主的受控触觉反馈入口。Expo 移动壳通过 `haptics.impact` 调用 Expo Haptics，只接受 `light`、`medium`、`heavy` 三档 impact style，缺省为 `light`，未知值返回 `invalid_request` 且不触发设备反馈；H5 运行时点击反馈在 `native_app` 中优先请求宿主触觉，宿主不可用、拒绝或返回 unsupported 时继续回退到浏览器 `navigator.vibrate`。 +- `requestHostHapticsImpact()`：原生 App 宿主的受控触觉反馈入口。Expo 移动壳通过 `haptics.impact` 调用 Expo Haptics，只接受 `light`、`medium`、`heavy` 三档 impact style，缺省为 `light`；H5 facade 发起请求前先按共享清单归一化 style，未知值不发往宿主，移动壳仍必须二次拒绝未知值且不触发设备反馈；H5 运行时点击反馈在 `native_app` 中优先请求宿主触觉，宿主不可用、拒绝或返回 unsupported 时继续回退到浏览器 `navigator.vibrate`。 - `showHostLocalNotification()`：原生 App 宿主的受控即时本地通知入口。H5 只能传必填 `title` 和可选 `body`，两者都会去除首尾空白、折叠普通空白、限制长度并拒绝控制字符；Expo 移动壳通过 `expo-notifications` 请求通知权限、创建 Android 本地通知 channel 并立刻调度本地通知，Android channel id 固定为共享契约 `HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID`；Tauri 桌面壳通过 Rust 侧 `tauri-plugin-notification` 先检查系统通知权限，处于 prompt 状态时只在 Rust 侧请求一次权限，最终授权后才发送系统通知。该能力不包含远程推送、token 注册、定时提醒、后台远程通知或任意通知插件透传，宿主未声明、权限拒绝或系统失败时由 H5 视作失败并继续主流程。当前 H5 只在现有草稿生成任务收口为完成或失败时请求即时本地通知；通知按草稿来源去重，同一草稿重新进入生成中后才允许再次通知，不改变队列状态、弹窗、作品架或后端裁决。平台壳同步层必须通过真实 `host_bridge_request` transport 测到 `notification.showLocal` 请求，不能只测模型文案或替换 facade。 - `setHostAppTitle()`：原生 App 宿主的受控窗口标题入口。H5 主站会按当前平台阶段先同步 `document.title`，再通过 `app.setTitle` 请求宿主窗口标题同步；Tauri 桌面壳支持该能力，Expo 移动壳不声明时静默忽略。 - `setHostAppBadgeCount()`：原生 App 宿主的受控应用角标入口。H5 只传 `0` 到共享契约 `HOST_BRIDGE_BADGE_COUNT_MAX` 之间的整数，`0` 表示清除角标；Expo 移动壳只在 iOS 声明 `app.setBadgeCount` 并通过 React Native `PushNotificationIOS` 设置应用图标角标，Android 不声明该能力；Tauri 桌面壳通过主窗口 `set_badge_count` 设置任务栏角标，底层平台不支持时返回明确错误，由 H5 视作失败并继续主流程。当前 H5 只把“可见作品架里未读的草稿生成完成更新”同步为角标数，同一个草稿有多个恢复 ID 时只计 1，已读、失败、生成中和不可见草稿不计入；宿主不支持或设置失败不改变 H5 红点、作品架或后端状态。平台壳同步层必须通过真实 `host_bridge_request` transport 测到 `app.setBadgeCount` 请求，保证未读计数模型和原生壳消费链路同时被门禁覆盖。 diff --git a/scripts/check-native-shells.mjs b/scripts/check-native-shells.mjs index d2b3e4b05..1f250e8e0 100644 --- a/scripts/check-native-shells.mjs +++ b/scripts/check-native-shells.mjs @@ -1040,6 +1040,18 @@ function assertH5HostBridgePayloadBoundaries() { 'H5 HostBridge facade must normalize clipboard.writeText payloads with the shared clipboard boundary', ); } + if ( + !h5HostBridgeSource.includes( + 'const style = normalizeHostBridgeHapticsImpactStyle(params.style);', + ) || + !h5HostBridgeSource.includes( + "return await requestNativeHostBoolean('haptics.impact', { style });", + ) + ) { + throw new Error( + 'H5 HostBridge facade must normalize haptics.impact payloads with the shared style boundary', + ); + } } function assertH5NativeAppTransportTimeoutBoundaries() { diff --git a/src/services/host-bridge/hostBridge.test.ts b/src/services/host-bridge/hostBridge.test.ts index 9cc763e62..54556a152 100644 --- a/src/services/host-bridge/hostBridge.test.ts +++ b/src/services/host-bridge/hostBridge.test.ts @@ -1278,6 +1278,46 @@ describe('hostBridge', () => { }); }); + test('原生 App HostBridge 发送触觉反馈前按共享清单归一化强度', async () => { + const invoke = vi.fn( + async (_command: string, args?: Record) => { + const request = (args as { request: { id: string } }).request; + return { + bridge: 'GenarrativeHostBridge', + version: 1, + id: request.id, + ok: true, + result: true, + }; + }, + ); + window.__TAURI__ = { + core: { invoke: asTauriInvoke(invoke) }, + }; + window.history.replaceState( + null, + '', + nativeAppPath(['haptics.impact']), + ); + + await expect(requestHostHapticsImpact()).resolves.toBe(true); + await expect( + requestHostHapticsImpact({ + style: 'sharp' as unknown as 'light', + }), + ).resolves.toBe(false); + + expect(invoke).toHaveBeenCalledTimes(1); + expect(invoke).toHaveBeenCalledWith('host_bridge_request', { + request: expect.objectContaining({ + method: 'haptics.impact', + payload: { + style: 'light', + }, + }), + }); + }); + test('原生 App 宿主不支持能力时回退到 H5 路径', async () => { window.history.replaceState(null, '', nativeAppPath()); window.__TAURI__ = { diff --git a/src/services/host-bridge/hostBridge.ts b/src/services/host-bridge/hostBridge.ts index b18866df9..9d97e8789 100644 --- a/src/services/host-bridge/hostBridge.ts +++ b/src/services/host-bridge/hostBridge.ts @@ -41,6 +41,7 @@ import { normalizeHostBridgeColorScheme, normalizeHostBridgeConnectionType, normalizeHostBridgeExternalUrl, + normalizeHostBridgeHapticsImpactStyle, normalizeHostBridgeLifecycleState, normalizeHostBridgeLocalNotification, normalizeHostBridgeQrCodeValue, @@ -1109,8 +1110,13 @@ export async function requestHostHapticsImpact( return false; } + const style = normalizeHostBridgeHapticsImpactStyle(params.style); + if (!style) { + return false; + } + try { - return await requestNativeHostBoolean('haptics.impact', params); + return await requestNativeHostBoolean('haptics.impact', { style }); } catch { return false; }