接入原生壳剪贴板读取能力

新增 clipboard.readText HostBridge 契约和 H5 facade

移动端通过 expo-clipboard 读取纯文本剪贴板

桌面端通过 Tauri clipboard-manager 读取纯文本剪贴板

更新壳能力检查、测试、方案文档和共享决策记录

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

@@ -143,6 +143,7 @@ const requiredMainSnippets = [
   '"app.setTitle"',
   '"app.setBadgeCount"',
   '"clipboard.writeText"',
+  '"clipboard.readText"',
   '"file.exportText"',
   '"file.exportImage"',
   '"file.importImage"',
@@ -159,6 +160,8 @@ const requiredMainSnippets = [
   'import_image_file_payload',
   'set_title',
   'set_badge_count',
+  'read_text()',
+  'normalize_clipboard_text',
   'window.theme()',
   'WindowEvent::Focused',
   'WindowEvent::DragDrop',

apps/desktop-shell/src-tauri/src/main.rs

@@ -30,6 +30,7 @@ const BADGE_COUNT_MAX: i64 = 99999;
 const DESKTOP_NETWORK_CHECK_TIMEOUT_MS: u64 = 1200;
 const LOCAL_NOTIFICATION_TITLE_MAX_LENGTH: usize = 80;
 const LOCAL_NOTIFICATION_BODY_MAX_LENGTH: usize = 240;
+const CLIPBOARD_TEXT_MAX_LENGTH: usize = 100000;
 
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -101,6 +102,7 @@ fn capabilities() -> Vec<&'static str> {
         "network.status",
         "network.statusChanged",
         "clipboard.writeText",
+        "clipboard.readText",
         "file.exportText",
         "file.exportImage",
         "file.importImage",
@@ -248,6 +250,10 @@ fn badge_count_payload(request: &HostBridgeRequest) -> Result<Option<i64>, HostB
     Ok(if count == 0 { None } else { Some(count) })
 }
 
+fn normalize_clipboard_text(text: String) -> String {
+    text.chars().take(CLIPBOARD_TEXT_MAX_LENGTH).collect()
+}
+
 fn normalize_plain_text(
     value: Option<&str>,
     max_length: usize,
@@ -859,6 +865,15 @@ async fn host_bridge_request(
                 Err(error) => failed(request.id, "host_error", error.to_string()),
             }
         }
+        "clipboard.readText" => match app.clipboard().read_text() {
+            Ok(text) => ok(
+                request.id,
+                json!({
+                    "text": normalize_clipboard_text(text),
+                }),
+            ),
+            Err(error) => failed(request.id, "host_error", error.to_string()),
+        },
         "file.exportText" => {
             let (file_name, content) = match export_text_payload(&request) {
                 Ok(payload) => payload,
@@ -1130,6 +1145,10 @@ mod tests {
             .as_array()
             .unwrap()
             .contains(&json!("app.setBadgeCount")));
+        assert!(result["capabilities"]
+            .as_array()
+            .unwrap()
+            .contains(&json!("clipboard.readText")));
         assert!(result["capabilities"]
             .as_array()
             .unwrap()
@@ -1186,6 +1205,15 @@ mod tests {
         assert_eq!(error.message, "text is required");
     }
 
+    #[test]
+    fn clipboard_text_is_truncated_to_contract_limit() {
+        assert_eq!(normalize_clipboard_text("作品号 PZ-1".to_string()), "作品号 PZ-1");
+        assert_eq!(
+            normalize_clipboard_text("a".repeat(CLIPBOARD_TEXT_MAX_LENGTH + 10)).len(),
+            CLIPBOARD_TEXT_MAX_LENGTH
+        );
+    }
+
     #[test]
     fn local_notification_payload_is_normalized() {
         let mut request = request("notification.showLocal");

apps/desktop-shell/src-tauri/tauri.conf.json

@@ -6,7 +6,7 @@
   "build": {
     "beforeDevCommand": "npm --prefix ../.. run dev:web",
     "beforeBuildCommand": "npm --prefix ../.. run build:raw && npm run typecheck",
-    "devUrl": "http://127.0.0.1:3000/?clientRuntime=native_app&clientType=native_app&hostShell=tauri_desktop&hostPlatform=unknown&hostVersion=0.1.0&bridgeVersion=1&hostCapabilities=host.getRuntime,appearance.getColorScheme,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,network.status,network.statusChanged,clipboard.writeText,file.exportText,file.exportImage,file.importImage,file.imageDropped,notification.showLocal",
+    "devUrl": "http://127.0.0.1:3000/?clientRuntime=native_app&clientType=native_app&hostShell=tauri_desktop&hostPlatform=unknown&hostVersion=0.1.0&bridgeVersion=1&hostCapabilities=host.getRuntime,appearance.getColorScheme,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,network.status,network.statusChanged,clipboard.writeText,clipboard.readText,file.exportText,file.exportImage,file.importImage,file.imageDropped,notification.showLocal",
     "frontendDist": "../../../dist"
   },
   "app": {
@@ -14,7 +14,7 @@
       {
         "create": false,
         "label": "main",
-        "url": "index.html?clientRuntime=native_app&clientType=native_app&hostShell=tauri_desktop&hostPlatform=unknown&hostVersion=0.1.0&bridgeVersion=1&hostCapabilities=host.getRuntime,appearance.getColorScheme,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,network.status,network.statusChanged,clipboard.writeText,file.exportText,file.exportImage,file.importImage,file.imageDropped,notification.showLocal",
+        "url": "index.html?clientRuntime=native_app&clientType=native_app&hostShell=tauri_desktop&hostPlatform=unknown&hostVersion=0.1.0&bridgeVersion=1&hostCapabilities=host.getRuntime,appearance.getColorScheme,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,network.status,network.statusChanged,clipboard.writeText,clipboard.readText,file.exportText,file.exportImage,file.importImage,file.imageDropped,notification.showLocal",
         "title": "Genarrative",
         "width": 1280,
         "height": 820,

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

@@ -179,6 +179,7 @@ for (const snippet of [
   'file.exportText',
   'file.exportImage',
   'file.importImage',
+  'clipboard.readText',
   'notification.showLocal',
   'network.status',
   'getMobileNetworkStatus',
@@ -187,9 +188,11 @@ for (const snippet of [
   'Notifications.getPermissionsAsync',
   'Notifications.requestPermissionsAsync',
   'Sharing.shareAsync',
+  'Clipboard.getStringAsync',
   'ImagePicker.launchImageLibraryAsync',
   'ImagePicker.requestMediaLibraryPermissionsAsync',
   'normalizeHostBridgeExportFileName',
+  'normalizeHostBridgeClipboardText',
   'base64Data',
 ]) {
   if (!bridgeSource.includes(snippet)) {
@@ -218,6 +221,7 @@ for (const capability of [
   'navigation.canGoBack',
   'app.openExternalUrl',
   'clipboard.writeText',
+  'clipboard.readText',
   'file.exportText',
   'file.exportImage',
   'file.importImage',

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

@@ -1,3 +1,4 @@
+import * as Clipboard from 'expo-clipboard';
 import * as Haptics from 'expo-haptics';
 import * as ImagePicker from 'expo-image-picker';
 import * as Linking from 'expo-linking';
@@ -43,6 +44,7 @@ const DENIED_NOTIFICATION_PERMISSION = {
 } as NotificationPermissionStatus;
 
 vi.mock('expo-clipboard', () => ({
+  getStringAsync: vi.fn(),
   setStringAsync: vi.fn(),
 }));
 
@@ -198,6 +200,9 @@ afterEach(() => {
   vi.mocked(Appearance.getColorScheme).mockReset();
   vi.mocked(Appearance.getColorScheme).mockReturnValue('light');
   vi.mocked(Haptics.impactAsync).mockReset();
+  vi.mocked(Clipboard.getStringAsync).mockReset();
+  vi.mocked(Clipboard.getStringAsync).mockResolvedValue('作品号 PZ-1');
+  vi.mocked(Clipboard.setStringAsync).mockReset();
   vi.mocked(ImagePicker.launchImageLibraryAsync).mockReset();
   vi.mocked(ImagePicker.launchImageLibraryAsync).mockResolvedValue({
     canceled: true,
@@ -271,6 +276,7 @@ describe('handleMobileHostBridgeMessage', () => {
         'network.statusChanged',
         'navigation.canGoBack',
         'app.setBadgeCount',
+        'clipboard.readText',
         'notification.showLocal',
       ]),
     );
@@ -400,6 +406,28 @@ describe('handleMobileHostBridgeMessage', () => {
     });
   });
 
+  test('clipboard.readText 读取 Expo 系统剪贴板文本', async () => {
+    vi.mocked(Clipboard.getStringAsync).mockResolvedValue('作品号 PZ-1');
+
+    const response = await send(request('clipboard.readText'));
+
+    expect(expectOk(response).result).toEqual({
+      text: '作品号 PZ-1',
+    });
+    expect(Clipboard.getStringAsync).toHaveBeenCalled();
+  });
+
+  test('clipboard.readText 读取失败时返回 host_error', async () => {
+    vi.mocked(Clipboard.getStringAsync).mockRejectedValue(
+      new Error('clipboard unavailable'),
+    );
+
+    const response = await send(request('clipboard.readText'));
+
+    const failedResponse = expectFailed(response);
+    expect(failedResponse.error.code).toBe('host_error');
+  });
+
   test('haptics.impact 调起 Expo 触觉反馈', async () => {
     const response = await send(
       request('haptics.impact', {

apps/mobile-shell/src/mobileHostBridge.ts

@@ -13,6 +13,7 @@ import {
 } from 'react-native';
 
 import {
+  type ClipboardReadTextResult,
   type ClipboardWriteTextPayload,
   type FileExportImagePayload,
   type FileExportImageResult,
@@ -30,6 +31,7 @@ import {
   type HostBridgeResponse,
   type NavigateNativePagePayload,
   normalizeHostBridgeBadgeCount,
+  normalizeHostBridgeClipboardText,
   normalizeHostBridgeColorScheme,
   normalizeHostBridgeExportFileName,
   normalizeHostBridgeExternalUrl,
@@ -74,6 +76,7 @@ export const MOBILE_HOST_CAPABILITIES: HostBridgeCapability[] = [
   'network.status',
   'network.statusChanged',
   'clipboard.writeText',
+  'clipboard.readText',
   'file.exportText',
   'file.exportImage',
   'file.importImage',
@@ -229,6 +232,20 @@ async function writeClipboard(payload: unknown) {
   return true;
 }
 
+async function readClipboard(): Promise<ClipboardReadTextResult> {
+  const result = normalizeHostBridgeClipboardText(
+    await Clipboard.getStringAsync(),
+  );
+  if (!result) {
+    throw {
+      code: 'host_error',
+      message: 'clipboard text unavailable',
+    } satisfies HostBridgeError;
+  }
+
+  return result;
+}
+
 async function exportTextFile(payload: unknown): Promise<FileExportTextResult> {
   const exportPayload = payload as FileExportTextPayload | undefined;
   const content = exportPayload?.content;
@@ -606,6 +623,8 @@ async function handleRequest(request: HostBridgeRequest) {
       return ok(request, await getMobileNetworkStatus());
     case 'clipboard.writeText':
       return ok(request, await writeClipboard(request.payload));
+    case 'clipboard.readText':
+      return ok(request, await readClipboard());
     case 'file.exportText':
       return ok(request, await exportTextFile(request.payload));
     case 'file.exportImage':

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

@@ -39,6 +39,7 @@
 - 2026-06-18 H5 背景音乐接入宿主生命周期：`useBackgroundMusic` 通过 `useHostLifecycleActive()` 消费 `subscribeHostAppLifecycle()` 的归一结果，宿主进入后台、inactive 或桌面窗口失焦时降低音量并暂停音频循环，同时 `suspend` WebAudio context；回到 `active + focused` 且用户原本开启音乐时再恢复播放，不改变用户音量设置。
 - 2026-06-18 固定玩法音频接入宿主生命周期：前端新增 `useHostLifecycleActive()` 统一消费 `subscribeHostAppLifecycle()`，`useBackgroundMusic`、拼图运行态和抓大鹅运行态都只依赖该归一状态判断音频可播放性；宿主 inactive、background 或窗口失焦时暂停 `<audio>` / WebAudio，回到 `active + focused` 后仅在运行态仍在播放、音源存在且用户音乐音量大于 0 时恢复，不改变用户音量设置。
 - 2026-06-18 本地通知能力：新增 `notification.showLocal` HostBridge capability，H5 只能传必填 `title` 和可选 `body`，共享契约负责修剪、折叠普通空白、限制长度并拒绝控制字符；Expo 壳通过 `expo-notifications` 请求系统通知权限、创建 Android 本地 channel 并发送即时本地通知，Tauri 壳通过 Rust 侧 `tauri-plugin-notification` 发送系统通知且不开放插件 JS guest API。该能力不包含远程推送、token 注册、定时提醒或后台远程通知，权限拒绝、系统失败或宿主未声明时由 H5 视作失败并继续主流程。
+- 2026-06-18 剪贴板读取能力：新增 `clipboard.readText` HostBridge capability，H5 只能读取纯文本结果，契约限制返回文本最多 100000 字符；Expo 壳通过 `expo-clipboard` 读取系统剪贴板文本，Tauri 壳通过 Rust 侧 `tauri-plugin-clipboard-manager` 读取文本且不开放插件 JS guest API。该能力不读取图片、HTML、文件列表或剪贴板监听事件，宿主未声明或读取失败时由 H5 视作失败并保留原流程。
 - 影响范围：`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/【前端架构】宿主壳能力统一协议-2026-06-17.md

@@ -49,6 +49,7 @@ AI H5 sandbox
 - `openHostShare()`：原生 App 宿主的受控分享入口。发布分享弹窗只在 `hostCapabilities` 声明 `share.open` 时展示“系统分享”，通过 `share.open` 把当前作品标题、作品号和公开 URL 交给宿主；Expo 移动壳打开系统分享面板，Tauri 桌面壳把分享文本写入系统剪贴板，宿主不可用或返回 unsupported 时显示失败并保留复制链接路径。
 - `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 视作失败并保留原流程。
 - `requestHostHapticsImpact()`：原生 App 宿主的受控触觉反馈入口。Expo 移动壳通过 `haptics.impact` 调用 Expo Haptics；H5 运行时点击反馈在 `native_app` 中优先请求宿主触觉，宿主不可用、拒绝或返回 unsupported 时继续回退到浏览器 `navigator.vibrate`。
 - `showHostLocalNotification()`：原生 App 宿主的受控即时本地通知入口。H5 只能传必填 `title` 和可选 `body`，两者都会去除首尾空白、折叠普通空白、限制长度并拒绝控制字符；Expo 移动壳通过 `expo-notifications` 请求通知权限、创建 Android 本地通知 channel 并立刻调度本地通知，Tauri 桌面壳通过 Rust 侧 `tauri-plugin-notification` 发送系统通知。该能力不包含远程推送、token 注册、定时提醒、后台远程通知或任意通知插件透传，宿主未声明、权限拒绝或系统失败时由 H5 视作失败并继续主流程。
 - `setHostAppTitle()`：原生 App 宿主的受控窗口标题入口。H5 主站会按当前平台阶段先同步 `document.title`，再通过 `app.setTitle` 请求宿主窗口标题同步；Tauri 桌面壳支持该能力，Expo 移动壳不声明时静默忽略。

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

@@ -3,6 +3,7 @@ import { describe, expect, test } from 'vitest';
 import {
   isHostBridgeCapability,
   normalizeHostBridgeBadgeCount,
+  normalizeHostBridgeClipboardText,
   normalizeHostBridgeColorScheme,
   normalizeHostBridgeConnectionType,
   normalizeHostBridgeExportFileName,
@@ -55,6 +56,7 @@ describe('HostBridge shared contract helpers', () => {
     expect(isHostBridgeCapability('app.lifecycle')).toBe(true);
     expect(isHostBridgeCapability('network.status')).toBe(true);
     expect(isHostBridgeCapability('network.statusChanged')).toBe(true);
+    expect(isHostBridgeCapability('clipboard.readText')).toBe(true);
     expect(isHostBridgeCapability('file.importImage')).toBe(true);
     expect(isHostBridgeCapability('file.imageDropped')).toBe(true);
     expect(isHostBridgeCapability('app.setBadgeCount')).toBe(true);
@@ -64,6 +66,16 @@ describe('HostBridge shared contract helpers', () => {
     expect(isHostBridgeCapability(null)).toBe(false);
   });
 
+  test('归一化宿主剪贴板读取文本', () => {
+    expect(normalizeHostBridgeClipboardText('作品号 PZ-1')).toEqual({
+      text: '作品号 PZ-1',
+    });
+    expect(normalizeHostBridgeClipboardText('a'.repeat(100010))).toEqual({
+      text: 'a'.repeat(100000),
+    });
+    expect(normalizeHostBridgeClipboardText(null)).toBeNull();
+  });
+
   test('归一化宿主本地通知内容', () => {
     expect(
       normalizeHostBridgeLocalNotification({

packages/shared/src/contracts/hostBridge.ts

@@ -26,6 +26,7 @@ export const HOST_BRIDGE_METHODS = [
   'app.setBadgeCount',
   'network.status',
   'clipboard.writeText',
+  'clipboard.readText',
   'file.exportText',
   'file.exportImage',
   'file.importImage',
@@ -260,6 +261,24 @@ export type ClipboardWriteTextPayload = {
   text: string;
 };
 
+export type ClipboardReadTextResult = {
+  text: string;
+};
+
+export const HOST_BRIDGE_CLIPBOARD_TEXT_MAX_LENGTH = 100000;
+
+export function normalizeHostBridgeClipboardText(
+  rawText: unknown,
+): ClipboardReadTextResult | null {
+  if (typeof rawText !== 'string') {
+    return null;
+  }
+
+  return {
+    text: rawText.slice(0, HOST_BRIDGE_CLIPBOARD_TEXT_MAX_LENGTH),
+  };
+}
+
 export type FileExportTextPayload = {
   fileName: string;
   content: string;

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

@@ -20,6 +20,7 @@ import {
   openHostShareGrid,
   openWechatMiniProgramShareGridPage,
   postWechatMiniProgramMessage,
+  readHostClipboardText,
   refreshNativeAppHostRuntime,
   requestHostHapticsImpact,
   requestHostLogin,
@@ -594,6 +595,10 @@ describe('hostBridge', () => {
                     connectionType: 'ethernet',
                     nativeType: 'online',
                   }
+                : request.method === 'clipboard.readText'
+                  ? {
+                      text: '作品号 PZ-1',
+                    }
                 : request.method === 'file.importImage'
                   ? {
                       action: 'selected',
@@ -614,6 +619,7 @@ describe('hostBridge', () => {
         'navigation.openNativePage',
         'auth.requestLogin',
         'payment.request',
+        'clipboard.readText',
         'clipboard.writeText',
         'haptics.impact',
         'app.openExternalUrl',
@@ -651,6 +657,9 @@ describe('hostBridge', () => {
     await expect(
       writeHostClipboardText({ text: '作品号 PZ-1' }),
     ).resolves.toBe(true);
+    await expect(readHostClipboardText()).resolves.toEqual({
+      text: '作品号 PZ-1',
+    });
     await expect(requestHostHapticsImpact({ style: 'medium' })).resolves.toBe(
       true,
     );
@@ -728,6 +737,11 @@ describe('hostBridge', () => {
         },
       }),
     });
+    expect(invoke).toHaveBeenCalledWith('host_bridge_request', {
+      request: expect.objectContaining({
+        method: 'clipboard.readText',
+      }),
+    });
     expect(invoke).toHaveBeenCalledWith('host_bridge_request', {
       request: expect.objectContaining({
         method: 'haptics.impact',
@@ -835,6 +849,7 @@ describe('hostBridge', () => {
     await expect(
       writeHostClipboardText({ text: '作品号 PZ-1' }),
     ).resolves.toBe(false);
+    await expect(readHostClipboardText()).resolves.toBe(false);
     await expect(requestHostHapticsImpact({ style: 'light' })).resolves.toBe(
       false,
     );
@@ -876,6 +891,7 @@ describe('hostBridge', () => {
 
   test('普通浏览器不处理宿主文件导出', async () => {
     await expect(getHostAppearanceColorScheme()).resolves.toBe(false);
+    await expect(readHostClipboardText()).resolves.toBe(false);
     await expect(
       exportHostTextFile({
         fileName: '作品记录.txt',

src/services/host-bridge/hostBridge.ts

@@ -1,6 +1,7 @@
 import type {
   AppearanceColorSchemeResult,
   AppLifecycleEventPayload,
+  ClipboardReadTextResult,
   FileExportImagePayload,
   FileExportImageResult,
   FileExportTextPayload,
@@ -20,6 +21,7 @@ import type {
 import {
   isHostBridgeCapability,
   normalizeHostBridgeBadgeCount,
+  normalizeHostBridgeClipboardText,
   normalizeHostBridgeColorScheme,
   normalizeHostBridgeConnectionType,
   normalizeHostBridgeExternalUrl,
@@ -96,6 +98,8 @@ export type HostClipboardWriteTextRequest = {
   text: string;
 };
 
+export type HostClipboardReadTextResult = ClipboardReadTextResult;
+
 export type HostHapticsImpactRequest = HapticsImpactPayload;
 
 export type HostLocalNotificationRequest = LocalNotificationPayload;
@@ -698,6 +702,24 @@ export async function writeHostClipboardText({
   }
 }
 
+export async function readHostClipboardText() {
+  if (!canUseNativeHostCapability('clipboard.readText')) {
+    return false;
+  }
+
+  try {
+    return normalizeHostBridgeClipboardText(
+      (
+        await requestNativeAppHostBridge<ClipboardReadTextResult>(
+          'clipboard.readText',
+        )
+      )?.text,
+    );
+  } catch {
+    return false;
+  }
+}
+
 export async function exportHostTextFile(
   params: HostFileExportTextRequest,
 ) {