收口移动壳触觉反馈强度边界

共享HostBridge契约固定触觉反馈强度白名单移动壳拒绝未知触觉反馈强度并避免误触发设备反馈移动壳配置检查锁定触觉反馈归一化规则宿主壳协议和共享决策日志记录触觉反馈边界
2026-06-18 15:02:07 +08:00
parent 4731263073
commit e8713a396b
8 changed files with 65 additions and 3 deletions
@@ -873,6 +873,7 @@ for (const snippet of [
  'file.base64()',
  'normalizeHostBridgeExportFileName',
  'normalizeHostBridgeClipboardText',
+  'normalizeHostBridgeHapticsImpactStyle',
  'base64Data',
  'isHostBridgeMethod',
  'normalizeHostBridgeRequestId',
@@ -579,6 +579,26 @@ describe('handleMobileHostBridgeMessage', () => {
    );
  });

+  test('haptics.impact 缺省为轻触并拒绝未知强度', async () => {
+    const defaultResponse = await send(request('haptics.impact'));
+
+    expectOk(defaultResponse);
+    expect(Haptics.impactAsync).toHaveBeenCalledWith(
+      Haptics.ImpactFeedbackStyle.Light,
+    );
+
+    vi.mocked(Haptics.impactAsync).mockClear();
+
+    const invalidResponse = await send(
+      request('haptics.impact', {
+        style: 'rigid',
+      }),
+    );
+
+    expect(expectFailed(invalidResponse).error.code).toBe('invalid_request');
+    expect(Haptics.impactAsync).not.toHaveBeenCalled();
+  });
+
  test('notification.showLocal 调起 Expo 本地通知', async () => {
    const response = await send(
      request('notification.showLocal', {
@@ -43,6 +43,7 @@ import {
  normalizeHostBridgeColorScheme,
  normalizeHostBridgeExportFileName,
  normalizeHostBridgeExternalUrl,
+  normalizeHostBridgeHapticsImpactStyle,
  normalizeHostBridgeLocalNotification,
  normalizeHostBridgeRequestId,
  type OpenExternalUrlPayload,
@@ -714,7 +715,13 @@ async function importAudioFile(): Promise<FileImportAudioResult> {
 }

 async function runHaptics(payload: unknown) {
-  const style = (payload as HapticsImpactPayload | undefined)?.style;
+  const style = normalizeHostBridgeHapticsImpactStyle(
+    (payload as HapticsImpactPayload | undefined)?.style,
+  );
+  if (!style) {
+    throw invalidRequest('haptics impact style must be light, medium, or heavy');
+  }
+
  const impactStyle =
    style === 'heavy'
      ? Haptics.ImpactFeedbackStyle.Heavy
@@ -28,6 +28,7 @@
 - 2026-06-18 壳能力防漂移：`npm run mobile-shell:typecheck` 与 `npm run desktop-shell:typecheck` 会校验 Expo / Tauri 壳声明的 capability 均来自共享 HostBridge 白名单，并校验壳 runtime 回包、H5 URL `hostCapabilities` 和实现分支保持一致；新增能力必须先更新契约和真实壳实现，再通过这些检查。
 - 2026-06-18 原生壳统一验收门禁：根级 `npm run check:native-shells` 统一执行 H5 HostBridge 关键测试、Expo 壳 typecheck / test / config smoke / Metro export smoke、Tauri 壳 typecheck / cargo test、桌面 release `--no-bundle` 构建烟测和两端生产壳临时替身词扫描；根级 `npm run check` 会在 lint、主站测试、构建和内容检查后继续执行该门禁，避免 HostBridge、两端壳、Expo managed config、移动端 production bundle、桌面 release 入口和壳生产源码禁替身验收散落成容易漏跑的单项命令。
 - 2026-06-18 登录 / 支付能力禁伪声明：`auth.requestLogin` 和 `payment.request` 保留在共享 HostBridge 契约中供未来真实接入，但 Expo / Tauri 壳在真实 SDK、渠道流程和后端契约落地前不得声明这些 capability，也不得把它们写入入口 URL `hostCapabilities`；两端检查脚本会拒绝伪声明，请求实际到达壳层时必须返回明确 `unsupported_method` 并让 H5 fallback，两端壳测试直接覆盖这两个 method。
+- 2026-06-18 移动壳触觉反馈边界：`haptics.impact` 只接受 `light`、`medium`、`heavy` 三档 impact style，缺省为 `light`；未知值必须返回 `invalid_request`，不得静默降级成真实设备触觉反馈。桌面壳不声明该 capability，H5 继续按 HostBridge fallback 处理。
 - 2026-06-18 分享卡图片导出：新增 `file.exportImage` HostBridge capability，H5 分享卡下载在 native app 中优先把 canvas 生成的 base64 图片交给宿主导出；Expo 壳写缓存图片后交给系统分享 / 保存面板，Tauri 壳通过系统保存对话框写入图片字节。该能力只接受 `image/png` / `image/jpeg` / `image/webp`、单次 5 MiB 内图片数据，成功只返回文件名和字节数，不暴露本机绝对路径；宿主未声明时保留浏览器下载。
 - 2026-06-18 应用角标能力：新增 `app.setBadgeCount` HostBridge capability，H5 只传 `0-99999` 整数并在宿主未声明时静默 fallback；Expo 壳只在 iOS 声明并通过 React Native `PushNotificationIOS` 设置应用图标角标，Android 不声明、不伪造成功；Tauri 壳通过主窗口 `set_badge_count` 设置任务栏角标，底层平台不支持时返回真实错误。
 - 2026-06-18 草稿生成未读角标：平台壳层把“可见作品架里未读的草稿生成完成更新”同步到 `app.setBadgeCount`；同一草稿的 work/profile/session 等多个恢复 ID 只计 1，已读、失败、生成中和不可见草稿不计入。该角标只消费已有 HostBridge 能力，宿主不支持或设置失败不影响 H5 红点、作品架或后端状态。
@@ -282,6 +282,8 @@ GameBridge 禁止：

 2026-06-18 追加：H5 的平台外部生成队列概览开始消费 `network.status` / `network.statusChanged`。宿主未声明网络能力时继续按原逻辑轮询；宿主明确离线或不可达时暂停概览请求，恢复在线后重新刷新，不改变生成任务、作品架或后端回读事实。

+2026-06-18 追加：移动壳 `haptics.impact` 只接受 `light`、`medium`、`heavy` 三档 impact style，缺省为 `light`；未知强度返回 `invalid_request`，不会静默降级成真实设备触觉反馈。桌面壳不声明该能力，H5 继续按 HostBridge fallback 处理。
+
 2026-06-18 追加：H5 账号状态刷新开始消费 `app.reloadWebView`。用户登录成功、退出登录或其它身份边界变化需要整页重新初始化时，`AuthGate` 会优先请求 Expo 壳刷新当前 WebView；宿主未声明或刷新失败时再回退浏览器刷新，避免在移动壳内绕过受控容器刷新入口。

 2026-06-18 追加：移动壳 WebView 内容 / 渲染进程终止时复用同一受控刷新路径。iOS `onContentProcessDidTerminate` 和 Android `onRenderProcessGone` 只调用当前 `react-native-webview` 的 `reload()`，不改写 H5 URL、不注入额外脚本、不新增宿主恢复页面，避免系统回收 WebView 进程后留下空白容器。
@@ -50,7 +50,7 @@ AI H5 sandbox
 - `openHostShareGrid()`：微信小程序九宫格切图页。
 - `writeHostClipboardText()`：原生 App 宿主的受控剪贴板入口。H5 复制服务在 `native_app` 中优先通过 `clipboard.writeText` 写入 Expo / Tauri 系统剪贴板；宿主不可用、拒绝或返回 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；H5 运行时点击反馈在 `native_app` 中优先请求宿主触觉，宿主不可用、拒绝或返回 unsupported 时继续回退到浏览器 `navigator.vibrate`。
+- `requestHostHapticsImpact()`：原生 App 宿主的受控触觉反馈入口。Expo 移动壳通过 `haptics.impact` 调用 Expo Haptics，只接受 `light`、`medium`、`heavy` 三档 impact style，缺省为 `light`，未知值返回 `invalid_request` 且不触发设备反馈；H5 运行时点击反馈在 `native_app` 中优先请求宿主触觉，宿主不可用、拒绝或返回 unsupported 时继续回退到浏览器 `navigator.vibrate`。
 - `showHostLocalNotification()`：原生 App 宿主的受控即时本地通知入口。H5 只能传必填 `title` 和可选 `body`，两者都会去除首尾空白、折叠普通空白、限制长度并拒绝控制字符；Expo 移动壳通过 `expo-notifications` 请求通知权限、创建 Android 本地通知 channel 并立刻调度本地通知，Tauri 桌面壳通过 Rust 侧 `tauri-plugin-notification` 发送系统通知。该能力不包含远程推送、token 注册、定时提醒、后台远程通知或任意通知插件透传，宿主未声明、权限拒绝或系统失败时由 H5 视作失败并继续主流程。当前 H5 只在现有草稿生成任务收口为完成或失败时请求即时本地通知；通知按草稿来源去重，同一草稿重新进入生成中后才允许再次通知，不改变队列状态、弹窗、作品架或后端裁决。
 - `setHostAppTitle()`：原生 App 宿主的受控窗口标题入口。H5 主站会按当前平台阶段先同步 `document.title`，再通过 `app.setTitle` 请求宿主窗口标题同步；Tauri 桌面壳支持该能力，Expo 移动壳不声明时静默忽略。
 - `setHostAppBadgeCount()`：原生 App 宿主的受控应用角标入口。H5 只传 `0-99999` 的整数，`0` 表示清除角标；Expo 移动壳只在 iOS 声明 `app.setBadgeCount` 并通过 React Native `PushNotificationIOS` 设置应用图标角标，Android 不声明该能力；Tauri 桌面壳通过主窗口 `set_badge_count` 设置任务栏角标，底层平台不支持时返回明确错误，由 H5 视作失败并继续主流程。当前 H5 只把“可见作品架里未读的草稿生成完成更新”同步为角标数，同一个草稿有多个恢复 ID 时只计 1，已读、失败、生成中和不可见草稿不计入；宿主不支持或设置失败不改变 H5 红点、作品架或后端状态。
@@ -10,6 +10,7 @@ import {
  normalizeHostBridgeConnectionType,
  normalizeHostBridgeExportFileName,
  normalizeHostBridgeExternalUrl,
+  normalizeHostBridgeHapticsImpactStyle,
  normalizeHostBridgeLifecycleState,
  normalizeHostBridgeLocalNotification,
  normalizeHostBridgeRequestId,
@@ -140,6 +141,15 @@ describe('HostBridge shared contract helpers', () => {
    expect(normalizeHostBridgeLocalNotification(null)).toBeNull();
  });

+  test('归一化宿主触觉反馈强度', () => {
+    expect(normalizeHostBridgeHapticsImpactStyle(undefined)).toBe('light');
+    expect(normalizeHostBridgeHapticsImpactStyle('light')).toBe('light');
+    expect(normalizeHostBridgeHapticsImpactStyle('medium')).toBe('medium');
+    expect(normalizeHostBridgeHapticsImpactStyle('heavy')).toBe('heavy');
+    expect(normalizeHostBridgeHapticsImpactStyle('rigid')).toBeNull();
+    expect(normalizeHostBridgeHapticsImpactStyle(null)).toBeNull();
+  });
+
  test('归一化宿主角标数量', () => {
    expect(normalizeHostBridgeBadgeCount(0)).toBe(0);
    expect(normalizeHostBridgeBadgeCount(12)).toBe(12);
@@ -393,8 +393,29 @@ export type FileExportAudioResult = {
  bytes: number;
 };

+export const HOST_BRIDGE_HAPTICS_IMPACT_STYLES = [
+  'light',
+  'medium',
+  'heavy',
+] as const;
+
+export type HostBridgeHapticsImpactStyle =
+  (typeof HOST_BRIDGE_HAPTICS_IMPACT_STYLES)[number];
+
+export function normalizeHostBridgeHapticsImpactStyle(rawStyle: unknown) {
+  if (rawStyle === undefined) {
+    return 'light';
+  }
+
+  return HOST_BRIDGE_HAPTICS_IMPACT_STYLES.includes(
+    rawStyle as HostBridgeHapticsImpactStyle,
+  )
+    ? rawStyle as HostBridgeHapticsImpactStyle
+    : null;
+}
+
 export type HapticsImpactPayload = {
-  style?: 'light' | 'medium' | 'heavy';
+  style?: HostBridgeHapticsImpactStyle;
 };

 export type LocalNotificationPayload = {