收口本地通知交付结果语义

新增共享本地通知系统交付结果契约

Expo 与 Tauri 壳返回结构化通知交付结果

H5 兼容结构化结果并同步门禁、测试和文档

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

@@ -2344,7 +2344,8 @@ for (const snippet of [
   'PermissionState::Granted',
   'PermissionState::Denied',
   'PermissionState::Prompt | PermissionState::PromptWithRationale',
-  'ok(request.id.clone(), json!(true))',
+  'desktop_notification_delivered_to_system_result',
+  '"delivered_to_system"',
   '"notification permission denied"',
   'app.notification().builder()',
 ]) {

apps/desktop-shell/src-tauri/src/host_bridge/notifications.rs

@@ -84,6 +84,10 @@ fn desktop_notification_permission_action(
     }
 }
 
+fn desktop_notification_delivered_to_system_result() -> serde_json::Value {
+    json!({"action": "delivered_to_system"})
+}
+
 pub(crate) fn show_desktop_local_notification(
     app: &tauri::AppHandle,
     request: &HostBridgeRequest,
@@ -125,7 +129,10 @@ pub(crate) fn show_desktop_local_notification(
     }
 
     match notification.show() {
-        Ok(()) => ok(request.id.clone(), json!(true)),
+        Ok(()) => ok(
+            request.id.clone(),
+            desktop_notification_delivered_to_system_result(),
+        ),
         Err(error) => failed(request.id.clone(), "host_error", error.to_string()),
     }
 }
@@ -150,6 +157,14 @@ mod tests {
         assert_eq!(body.as_deref(), Some("作品已准备好 可以试玩"));
     }
 
+    #[test]
+    fn local_notification_success_result_reports_system_delivery() {
+        assert_eq!(
+            desktop_notification_delivered_to_system_result(),
+            json!({"action": "delivered_to_system"})
+        );
+    }
+
     #[test]
     fn local_notification_payload_rejects_empty_and_control_text() {
         let mut empty = request("notification.showLocal");

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

@@ -701,6 +701,7 @@ const sharedPayloadBoundaryImports = [
   'HOST_BRIDGE_IMPORT_DOCUMENT_MAX_BYTES',
   'HOST_BRIDGE_IMPORT_IMAGE_MAX_BYTES',
   'HOST_BRIDGE_IMPORT_TEXT_MAX_BYTES',
+  'HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT',
   'HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID',
   'normalizeHostBridgeImportFileName',
   'normalizeHostBridgeQrCodeValue',
@@ -1576,7 +1577,8 @@ for (const notificationSnippet of [
   'normalizeHostBridgeLocalNotification(request.payload)',
   "invalidRequest('title is required')",
   'showMobileLocalNotification(notification)',
-  'ok(request, true)',
+  'ok(request, await showMobileLocalNotification(notification))',
+  'HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT',
 ]) {
   if (!notificationsSource.includes(notificationSnippet)) {
     throw new Error(`mobile shell notifications module is missing ${notificationSnippet}`);

apps/mobile-shell/src/host-bridge/bridge.test.ts

@@ -455,7 +455,7 @@ describe('handleMobileHostBridgeMessage', () => {
       }),
     );
 
-    expectOk(response);
+    expect(expectOk(response).result).toBe(true);
     const openedUrl = new URL(openWebViewUrl.mock.calls[0]?.[0] as string);
     expect(openedUrl.origin).toBe('https://app.genarrative.world');
     expect(openedUrl.pathname).toBe('/works/detail');
@@ -549,7 +549,7 @@ describe('handleMobileHostBridgeMessage', () => {
 
     const response = await send(request('app.reloadWebView'));
 
-    expectOk(response);
+    expect(expectOk(response).result).toBe(true);
     expect(reloadWebView).toHaveBeenCalledTimes(1);
   });
 
@@ -560,7 +560,7 @@ describe('handleMobileHostBridgeMessage', () => {
       }),
     );
 
-    expectOk(response);
+    expect(expectOk(response).result).toBe(true);
     expect(Linking.canOpenURL).toHaveBeenCalledWith('https://example.com/path');
     expect(Linking.openURL).toHaveBeenCalledWith('https://example.com/path');
   });
@@ -702,7 +702,7 @@ describe('handleMobileHostBridgeMessage', () => {
       }),
     );
 
-    expectOk(response);
+    expect(expectOk(response).result).toBe(true);
     expect(Clipboard.setStringAsync).toHaveBeenCalledWith('a'.repeat(100000));
   });
 
@@ -724,7 +724,7 @@ describe('handleMobileHostBridgeMessage', () => {
       }),
     );
 
-    expectOk(response);
+    expect(expectOk(response).result).toBe(true);
     expect(Haptics.impactAsync).toHaveBeenCalledWith(
       Haptics.ImpactFeedbackStyle.Heavy,
     );
@@ -758,7 +758,9 @@ describe('handleMobileHostBridgeMessage', () => {
       }),
     );
 
-    expectOk(response);
+    expect(expectOk(response).result).toEqual({
+      action: 'delivered_to_system',
+    });
     expect(Notifications.getPermissionsAsync).toHaveBeenCalled();
     expect(Notifications.requestPermissionsAsync).not.toHaveBeenCalled();
     expect(Notifications.scheduleNotificationAsync).toHaveBeenCalledWith({

apps/mobile-shell/src/host-bridge/notifications.ts

@@ -2,6 +2,7 @@ import * as Notifications from 'expo-notifications';
 import { Platform } from 'react-native';
 
 import {
+  HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT,
   HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID,
   type HostBridgeError,
   type HostBridgeRequest,
@@ -70,7 +71,7 @@ export async function showMobileLocalNotification(
         ? { channelId: HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID }
         : null,
   });
-  return true;
+  return HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT;
 }
 
 export async function showMobileHostBridgeLocalNotification(
@@ -81,6 +82,5 @@ export async function showMobileHostBridgeLocalNotification(
     throw invalidRequest('title is required');
   }
 
-  await showMobileLocalNotification(notification);
-  return ok(request, true);
+  return ok(request, await showMobileLocalNotification(notification));
 }

docs/project-memory/shared-memory/decision-log.md

@@ -2798,6 +2798,13 @@
 - 影响范围：`packages/shared/src/contracts/hostBridge.ts`、`packages/shared/src/contracts/hostBridge.test.ts`、`apps/mobile-shell/src/host-bridge/files.ts`、`apps/mobile-shell/scripts/check-config.mjs` 和宿主壳能力统一协议文档。
 - 验证方式：`npm run mobile-shell:test`、`npm run mobile-shell:typecheck`、`npm run test -- packages/shared/src/contracts/hostBridge.test.ts`、`npm run check:native-shells`、`npm run check:encoding`、`git diff --check`。
 
+## 2026-06-20 本地通知结果语义收口
+
+- 背景：Expo 和 Tauri 壳的 `notification.showLocal` 此前成功时返回裸 `true`，H5 只能理解为调用成功，容易被误读成“用户实际看见通知”；移动壳巡检也指出该能力真实语义应是系统调度 / 交付，而不是展示确认。
+- 决策：共享契约新增 `HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT`，结果为 `{ action: 'delivered_to_system' }`；Expo 和 Tauri 壳成功后返回该结构，H5 facade 接受结构化结果并暂兼容旧壳 `true`。该结果只表示通知已交给系统通知层，不承诺用户可见、点击或送达回执。
+- 影响范围：`packages/shared/src/contracts/hostBridge.ts`、`src/services/host-bridge/hostBridge.ts`、`apps/mobile-shell/src/host-bridge/notifications.ts`、`apps/desktop-shell/src-tauri/src/host_bridge/notifications.rs`、两端配置门禁、测试和宿主壳能力统一协议文档。
+- 验证方式：`npm run test -- packages/shared/src/contracts/hostBridge.test.ts src/services/host-bridge/hostBridge.test.ts`、`npm run mobile-shell:test`、`npm run desktop-shell:test`、`npm run check:native-shells`、`npm run check:encoding`、`git diff --check`。
+
 ## 2026-06-19 原生宿主二维码扫码超时单一来源
 
 - 背景：二维码扫码属于真实相机交互，等待时间应长于普通宿主请求；此前 H5 `scanHostQrCode()` 直接手写 `timeoutMs: 60000`，会让扫码等待边界和共享 HostBridge 契约漂移。

docs/【前端架构】宿主壳能力统一协议-2026-06-17.md

@@ -65,7 +65,7 @@ Tauri 桌面壳启动时必须按 `label="main"` 解析 `tauri.conf.json` 主窗
 - `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`；H5 facade 发起请求前先按共享清单归一化 style，未知值不发往宿主，移动壳仍必须二次拒绝未知值且不触发设备反馈；H5 运行时点击反馈在 `native_app` 中优先请求宿主触觉，宿主不可用、拒绝或返回 unsupported 时继续回退到浏览器 `navigator.vibrate`。
   移动壳的触觉反馈 payload 解析、style 归一、Expo style 映射和真实设备反馈调用都必须留在 `apps/mobile-shell/src/host-bridge/haptics.ts`，`dispatch.ts` 只把 `request.payload` 委托给该模块。
-- `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。
+- `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 侧请求一次权限，最终授权后才发送系统通知。成功结果统一为共享契约 `HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT`，只表示通知已交给系统通知层，不承诺用户一定看见或点击。该能力不包含远程推送、token 注册、定时提醒、后台远程通知或任意通知插件透传，宿主未声明、权限拒绝或系统失败时由 H5 视作失败并继续主流程。当前 H5 只在现有草稿生成任务收口为完成或失败时请求即时本地通知；通知按草稿来源去重，同一草稿重新进入生成中后才允许再次通知，不改变队列状态、弹窗、作品架或后端裁决。平台壳同步层必须通过真实 `host_bridge_request` transport 测到 `notification.showLocal` 请求，不能只测模型文案或替换 facade。
 - `setHostAppTitle()`：原生 App 宿主的受控窗口标题入口。H5 主站会按当前平台阶段先同步 `document.title`，再通过 `app.setTitle` 请求宿主窗口标题同步；H5 facade 和 Tauri 桌面壳都必须按共享契约 `HOST_BRIDGE_APP_TITLE_MAX_LENGTH` 清洗标题，拒绝空值和控制字符，最多保留 80 个字符。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` 请求，保证未读计数模型和原生壳消费链路同时被门禁覆盖。
 - `reloadHostWebView()`：原生 App 宿主的受控 WebView 刷新入口。H5 只能请求刷新当前承载主站的宿主 WebView；Expo 移动壳调用当前 `react-native-webview` 的 `reload()`，Tauri 桌面壳调用主 `WebviewWindow.reload()`。该能力不接受 payload，不开放任意 URL 导航、脚本执行、Tauri guest API 或 RN WebView ref；成功只表示宿主已发起刷新，刷新后当前 H5 上下文会卸载。`AuthGate` 在登录态从未登录变为已登录、或从已登录变为未登录时优先调用该能力刷新当前容器；宿主未声明、返回失败或不可用时再回退浏览器 `window.location.reload()`。

packages/shared/src/contracts/hostBridge.test.ts

@@ -21,6 +21,7 @@ import {
   HOST_BRIDGE_DESKTOP_NETWORK_CHECK_TIMEOUT_MS,
   HOST_BRIDGE_EVENTS,
   HOST_BRIDGE_IMPORT_DOCUMENT_MAX_BYTES,
+  HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT,
   HOST_BRIDGE_MAX_REQUEST_TIMEOUT_MS,
   HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID,
   HOST_BRIDGE_MOBILE_WEBVIEW_BLOCKED_DOWNLOAD_PROTOCOLS,
@@ -512,6 +513,9 @@ describe('HostBridge shared contract helpers', () => {
   });
 
   test('归一化宿主本地通知内容', () => {
+    expect(HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT).toEqual({
+      action: 'delivered_to_system',
+    });
     expect(
       normalizeHostBridgeLocalNotification({
         title: '  生成完成  ',

packages/shared/src/contracts/hostBridge.ts

@@ -1001,6 +1001,14 @@ export type LocalNotificationPayload = {
   body?: string;
 };
 
+export type LocalNotificationResult = {
+  action: 'delivered_to_system';
+};
+
+export const HOST_BRIDGE_LOCAL_NOTIFICATION_DELIVERED_TO_SYSTEM_RESULT: LocalNotificationResult = {
+  action: 'delivered_to_system',
+};
+
 export const HOST_BRIDGE_LOCAL_NOTIFICATION_TITLE_MAX_LENGTH = 80;
 export const HOST_BRIDGE_LOCAL_NOTIFICATION_BODY_MAX_LENGTH = 240;
 export const HOST_BRIDGE_MOBILE_LOCAL_NOTIFICATION_CHANNEL_ID =

src/services/host-bridge/hostBridge.test.ts

@@ -1464,6 +1464,46 @@ describe('hostBridge', () => {
     ).resolves.toBe(false);
   });
 
+  test('原生 App 宿主本地通知接受结构化交付结果', async () => {
+    const invoke = vi.fn(
+      async (_command: string, args?: Record<string, unknown>) => {
+        const request = (args as { request: { id: string } }).request;
+        return {
+          bridge: 'GenarrativeHostBridge',
+          version: 1,
+          id: request.id,
+          ok: true,
+          result: { action: 'delivered_to_system' },
+        };
+      },
+    );
+    window.history.replaceState(
+      null,
+      '',
+      nativeAppPath(['notification.showLocal']),
+    );
+    window.__TAURI__ = {
+      core: {
+        invoke: asTauriInvoke(invoke),
+      },
+    };
+
+    await expect(
+      showHostLocalNotification({
+        title: '生成完成',
+      }),
+    ).resolves.toBe(true);
+
+    expect(invoke).toHaveBeenCalledWith('host_bridge_request', {
+      request: expect.objectContaining({
+        method: 'notification.showLocal',
+        payload: {
+          title: '生成完成',
+        },
+      }),
+    });
+  });
+
   test('原生 App 宿主拒绝非法本地通知 payload', async () => {
     const invoke = vi.fn();
     window.history.replaceState(

src/services/host-bridge/hostBridge.ts

@@ -17,6 +17,7 @@ import type {
   HostBridgeMethod,
   HostBridgeRuntimeResult,
   LocalNotificationPayload,
+  LocalNotificationResult,
   NavigationCanGoBackEventPayload,
   NetworkStatusResult,
   OpenExternalUrlPayload,
@@ -241,6 +242,34 @@ async function requestNativeHostBoolean(
   }
 }
 
+function isLocalNotificationDeliveredToSystemResult(
+  result: unknown,
+): result is LocalNotificationResult {
+  return (
+    !!result &&
+    typeof result === 'object' &&
+    (result as Partial<LocalNotificationResult>).action ===
+      'delivered_to_system'
+  );
+}
+
+async function requestNativeHostLocalNotification(
+  payload: LocalNotificationPayload,
+) {
+  try {
+    const result = await requestNativeAppHostBridge(
+      'notification.showLocal',
+      payload,
+    );
+    return result === true || isLocalNotificationDeliveredToSystemResult(result);
+  } catch (error) {
+    if (isUnsupportedHostBridgeError(error)) {
+      return false;
+    }
+    throw error;
+  }
+}
+
 function resolveLocation(context: HostRuntimeContext) {
   return (
     context.location ?? (typeof window !== 'undefined' ? window.location : null)
@@ -1072,10 +1101,7 @@ export async function showHostLocalNotification(
   }
 
   try {
-    return await requestNativeHostBoolean(
-      'notification.showLocal',
-      notification,
-    );
+    return await requestNativeHostLocalNotification(notification);
   } catch {
     return false;
   }