From b03c910f49c898f94903250220297e38e6587175 Mon Sep 17 00:00:00 2001 From: kdletters Date: Wed, 17 Jun 2026 23:40:57 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8E=A5=E5=85=A5=E5=AE=BF=E4=B8=BB=E5=A3=B3?= =?UTF-8?q?=E5=8E=9F=E7=94=9F=E5=89=AA=E8=B4=B4=E6=9D=BF=E5=A4=8D=E5=88=B6?= =?UTF-8?q?=E8=B7=AF=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit H5 复制服务在 native_app 中优先调用 clipboard.writeText 保留浏览器 Clipboard API 与 legacy selection copy 回退路径 补充 HostBridge 剪贴板测试和宿主壳能力文档 --- .../shared-memory/decision-log.md | 2 +- ...ExpoReactNative与Tauri宿主壳方案-2026-06-17.md | 6 +- ...前端架构】宿主壳能力统一协议-2026-06-17.md | 1 + src/services/clipboard.test.ts | 66 +++++++++++++++++++ src/services/clipboard.ts | 6 ++ src/services/host-bridge/hostBridge.test.ts | 15 +++++ src/services/host-bridge/hostBridge.ts | 18 +++++ 7 files changed, 110 insertions(+), 4 deletions(-) create mode 100644 src/services/clipboard.test.ts diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 0dbc5de3..9e5658c6 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -20,7 +20,7 @@ - 背景：后续需要移动端 App 和桌面端 App，但现有主站、固定玩法 runtime、小程序壳和未来 AI H5 sandbox 已经以 H5 为主线；如果移动端重写 React Native UI、桌面端重写 Rust/Tauri UI，会形成玩法、登录、支付、分享和运行态的多套实现。 - 决策：移动端原生壳采用 `Expo + React Native`，桌面端壳采用 `Tauri`。两者都只作为 `native_app` 宿主壳和 HostBridge adapter，不重写现有 React H5 主站，不把固定内置玩法迁到 React Native / Rust UI，也不让 AI 生成 H5 游戏直接访问完整 HostBridge。Expo 壳通过 `react-native-webview` 承接 H5 与 native 通信，Tauri 壳通过受控 command 和 capabilities 承接桌面能力；新增能力必须先进入 HostBridge 契约和测试。 -- 2026-06-17 首轮落地：新增 `packages/shared/src/contracts/hostBridge.ts`、`src/services/host-bridge/nativeAppHostBridge.ts`、`apps/mobile-shell/` 和 `apps/desktop-shell/`。壳只声明并实现真实可用能力；移动壳使用真实品牌图标资产并支持 `genarrative://`、iOS associated domain、Android app link 到同源 H5 路径，`navigation.openNativePage` 只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的原生页面，且通过 `host.events` 注入 `navigation.canGoBack` 返回栈状态事件，`share.setTarget` / `share.open` 解析统一分享目标并调用 React Native 系统分享面板，`file.exportText` 写入 Expo 缓存文本文件后交给系统分享 / 保存面板，成功只返回文件名和字节数；`app.openExternalUrl` 在 Expo 与 Tauri 两端都只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议；桌面壳已通过 Tauri clipboard-manager 接入 `clipboard.writeText`，将 `navigation.openNativePage` 实现为 `https://app.genarrative.world` 同源 H5 route 的主窗口受控跳转，并将 `share.setTarget` / `share.open` 实现为复制非空分享文本到系统剪贴板，`app.setTitle` 通过主窗口 API 同步非空窗口标题；桌面 `file.exportText` 通过 Tauri dialog 插件打开系统保存对话框并由 Rust 写入文本文件，但不把 dialog / fs 插件 command 直接暴露给 H5，成功只返回文件名和字节数，用户取消返回 `cancelled`；登录、支付、原生系统分享面板等未接入真实 SDK / 插件前必须返回 unsupported 并让 H5 fallback，生产代码禁止 mock 成功。 +- 2026-06-17 首轮落地：新增 `packages/shared/src/contracts/hostBridge.ts`、`src/services/host-bridge/nativeAppHostBridge.ts`、`apps/mobile-shell/` 和 `apps/desktop-shell/`。壳只声明并实现真实可用能力；移动壳使用真实品牌图标资产并支持 `genarrative://`、iOS associated domain、Android app link 到同源 H5 路径，`navigation.openNativePage` 只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的原生页面，且通过 `host.events` 注入 `navigation.canGoBack` 返回栈状态事件，`share.setTarget` / `share.open` 解析统一分享目标并调用 React Native 系统分享面板，`file.exportText` 写入 Expo 缓存文本文件后交给系统分享 / 保存面板，成功只返回文件名和字节数；`app.openExternalUrl` 在 Expo 与 Tauri 两端都只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议；H5 复制服务在 native_app 中优先通过 `clipboard.writeText` 写入 Expo / Tauri 系统剪贴板，失败后再回退浏览器复制路径；桌面壳已通过 Tauri clipboard-manager 接入 `clipboard.writeText`，将 `navigation.openNativePage` 实现为 `https://app.genarrative.world` 同源 H5 route 的主窗口受控跳转，并将 `share.setTarget` / `share.open` 实现为复制非空分享文本到系统剪贴板，`app.setTitle` 通过主窗口 API 同步非空窗口标题；桌面 `file.exportText` 通过 Tauri dialog 插件打开系统保存对话框并由 Rust 写入文本文件，但不把 dialog / fs 插件 command 直接暴露给 H5，成功只返回文件名和字节数，用户取消返回 `cancelled`；登录、支付、原生系统分享面板等未接入真实 SDK / 插件前必须返回 unsupported 并让 H5 fallback，生产代码禁止 mock 成功。 - 影响范围：`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`。 diff --git a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md index 22bb0575..8ad8a71f 100644 --- a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md +++ b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md @@ -119,7 +119,7 @@ type HostBridgeEvent = { | `navigation.canGoBack` | 通知 H5 宿主返回栈状态 | 支持事件 | 不声明 | | `app.openExternalUrl` | 用系统浏览器打开外链 | 支持白名单协议 | 支持白名单协议 | | `app.setTitle` | 同步宿主窗口标题 | 不声明 | 支持 | -| `clipboard.writeText` | 写剪贴板 | 可选 | 可选 | +| `clipboard.writeText` | 写剪贴板 | 支持 | 支持 | | `file.exportText` | 导出文本到用户选择的本地文件 | 支持系统分享 / 保存面板 | 支持系统保存对话框 | | `haptics.impact` | 轻量触感反馈 | 可选 | 不支持 | @@ -241,7 +241,7 @@ GameBridge 禁止： - iOS / Android 深链打开作品详情、创作页和邀请码。 - 登录和支付先 fallback 到 H5；只把能力边界跑通。 -当前状态：已新增 `apps/mobile-shell/`，通过 Expo development build 运行，`react-native-webview` 加载 H5 URL 并附加 `native_app` 宿主 query。移动壳使用真实品牌图标资产，已接入 `genarrative://` scheme、iOS associated domain 和 Android app link filter，启动和运行时 deep link 只会映射到同源 H5 路径并继续附加 HostBridge 上下文，外域和危险协议回退到默认主站入口。首轮真实能力包括 `host.getRuntime`、`host.events`、`share.open`、`share.setTarget`、`navigation.openNativePage`、`navigation.canGoBack`、`app.openExternalUrl`、`clipboard.writeText`、`file.exportText`、`haptics.impact` 和 Android 返回键回退；其中 `share.setTarget` / `share.open` 会解析统一分享目标里的 `title`、`message`、`url`、`work`、`path` 或 `targetPath` 并调用 React Native 系统分享面板；`navigation.openNativePage` 在 Expo 壳内只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的登录、支付或其它原生页面，`navigation.canGoBack` 由 WebView 导航状态变化实时注入 H5，`app.openExternalUrl` 只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议；`file.exportText` 通过 Expo 文件系统写入缓存文本文件，再交给系统分享 / 保存面板，文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数。登录和支付尚未接入渠道 SDK / 原生页面时明确返回 unsupported，让 H5 fallback 承接。 +当前状态：已新增 `apps/mobile-shell/`，通过 Expo development build 运行，`react-native-webview` 加载 H5 URL 并附加 `native_app` 宿主 query。移动壳使用真实品牌图标资产，已接入 `genarrative://` scheme、iOS associated domain 和 Android app link filter，启动和运行时 deep link 只会映射到同源 H5 路径并继续附加 HostBridge 上下文，外域和危险协议回退到默认主站入口。首轮真实能力包括 `host.getRuntime`、`host.events`、`share.open`、`share.setTarget`、`navigation.openNativePage`、`navigation.canGoBack`、`app.openExternalUrl`、`clipboard.writeText`、`file.exportText`、`haptics.impact` 和 Android 返回键回退；其中 `share.setTarget` / `share.open` 会解析统一分享目标里的 `title`、`message`、`url`、`work`、`path` 或 `targetPath` 并调用 React Native 系统分享面板；`navigation.openNativePage` 在 Expo 壳内只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的登录、支付或其它原生页面，`navigation.canGoBack` 由 WebView 导航状态变化实时注入 H5，`app.openExternalUrl` 只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议，`clipboard.writeText` 由 H5 复制服务优先调用并写入系统剪贴板；`file.exportText` 通过 Expo 文件系统写入缓存文本文件，再交给系统分享 / 保存面板，文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数。登录和支付尚未接入渠道 SDK / 原生页面时明确返回 unsupported，让 H5 fallback 承接。 ### Phase 3：Tauri 桌面壳 MVP @@ -252,7 +252,7 @@ GameBridge 禁止： - 实现 runtime、openExternalUrl、clipboard、share fallback、窗口标题同步。 - 验证 macOS / Windows / Linux 至少一条本地 smoke。 -当前状态：已新增 `apps/desktop-shell/`，Tauri dev 直接加载本地主站 Vite，release 打包根 `dist` 主站资产。Rust 侧只把 `host_bridge_request` command 授给主窗口，`app.openExternalUrl` 由 Rust 内部通过 opener 插件执行且只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议，`navigation.openNativePage` 只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内受控跳转，`clipboard.writeText` 由 Rust 内部通过 clipboard-manager 插件写入系统剪贴板，`app.setTitle` 通过 Tauri 主窗口 API 同步窗口标题并拒绝空标题 / 控制字符；不把 opener、clipboard 或 dialog 插件命令直接暴露给前端。当前真实能力为 `host.getRuntime`、`share.setTarget`、`share.open`、`navigation.openNativePage`、`app.openExternalUrl`、`app.setTitle`、`clipboard.writeText` 和 `file.exportText`；其中 `share.open` 会把直接传入的分享 payload 或 `share.setTarget` 缓存的作品目标整理成非空分享文本并写入系统剪贴板，返回 `copied_to_clipboard`；`file.exportText` 通过系统保存对话框让用户选择本地路径，清洗文件名、限制单次文本导出不超过 5 MiB，写入成功后只返回文件名和字节数，不把本机绝对路径暴露给 H5，用户取消时返回 `cancelled`。原生系统分享面板、登录和支付未接入真实插件 / 渠道前不声明支持，不返回 mock 成功。 +当前状态：已新增 `apps/desktop-shell/`，Tauri dev 直接加载本地主站 Vite，release 打包根 `dist` 主站资产。Rust 侧只把 `host_bridge_request` command 授给主窗口，`app.openExternalUrl` 由 Rust 内部通过 opener 插件执行且只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议，`navigation.openNativePage` 只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内受控跳转，`clipboard.writeText` 由 Rust 内部通过 clipboard-manager 插件写入系统剪贴板并由 H5 复制服务优先调用，`app.setTitle` 通过 Tauri 主窗口 API 同步窗口标题并拒绝空标题 / 控制字符；不把 opener、clipboard 或 dialog 插件命令直接暴露给前端。当前真实能力为 `host.getRuntime`、`share.setTarget`、`share.open`、`navigation.openNativePage`、`app.openExternalUrl`、`app.setTitle`、`clipboard.writeText` 和 `file.exportText`；其中 `share.open` 会把直接传入的分享 payload 或 `share.setTarget` 缓存的作品目标整理成非空分享文本并写入系统剪贴板，返回 `copied_to_clipboard`；`file.exportText` 通过系统保存对话框让用户选择本地路径，清洗文件名、限制单次文本导出不超过 5 MiB，写入成功后只返回文件名和字节数，不把本机绝对路径暴露给 H5，用户取消时返回 `cancelled`。原生系统分享面板、登录和支付未接入真实插件 / 渠道前不声明支持，不返回 mock 成功。 ### Phase 4：宿主能力扩展 diff --git a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md index 7bac27cf..8a1ab9a3 100644 --- a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md +++ b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md @@ -44,6 +44,7 @@ AI H5 sandbox - `requestHostPayment()`：微信小程序支付跳转原生支付页；其它渠道返回 `false`，继续走 H5 / Native 二维码。 - `setHostShareTarget()`：把当前公开作品分享目标同步给宿主。 - `openHostShareGrid()`：微信小程序九宫格切图页。 +- `writeHostClipboardText()`：原生 App 宿主的受控剪贴板入口。H5 复制服务在 `native_app` 中优先通过 `clipboard.writeText` 写入 Expo / Tauri 系统剪贴板；宿主不可用、拒绝或返回 unsupported 时继续回退到浏览器 Clipboard API 和 legacy selection copy。 - `navigateHostNativePage()`：受控跳转宿主页，供订阅授权、支付、登录等 adapter 复用。Expo 移动壳首版只接受同源 H5 route 并切换 WebView URL；Tauri 桌面壳同样只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内跳转。真正原生页面、登录和支付能力必须等对应 SDK / 页面接入后再声明支持。 - `exportHostTextFile()`：原生 App 宿主的受控文本导出入口。Expo 移动壳通过 `file.exportText` 写入缓存文本文件并交给系统分享 / 保存面板；Tauri 桌面壳通过 `file.exportText` 打开系统保存对话框并写入用户选择的文件。文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数，不把本机绝对路径暴露给 H5；系统分享不可用或用户取消时返回明确错误，由 H5 fallback 承接。 diff --git a/src/services/clipboard.test.ts b/src/services/clipboard.test.ts new file mode 100644 index 00000000..f88d6dd2 --- /dev/null +++ b/src/services/clipboard.test.ts @@ -0,0 +1,66 @@ +/* @vitest-environment jsdom */ + +import { afterEach, describe, expect, test, vi } from 'vitest'; + +import { copyTextToClipboard } from './clipboard'; +import * as hostBridge from './host-bridge/hostBridge'; + +const originalClipboard = navigator.clipboard; + +afterEach(() => { + vi.restoreAllMocks(); + window.history.replaceState(null, '', '/'); + Object.defineProperty(navigator, 'clipboard', { + configurable: true, + value: originalClipboard, + }); +}); + +describe('copyTextToClipboard', () => { + test('原生 App 优先通过 HostBridge 写入剪贴板', async () => { + const writeHostClipboardText = vi + .spyOn(hostBridge, 'writeHostClipboardText') + .mockResolvedValue(true); + const writeText = vi.fn(); + Object.defineProperty(navigator, 'clipboard', { + configurable: true, + value: { writeText }, + }); + + await expect(copyTextToClipboard(' PZ-00000001 ')).resolves.toBe(true); + + expect(writeHostClipboardText).toHaveBeenCalledWith({ + text: 'PZ-00000001', + }); + expect(writeText).not.toHaveBeenCalled(); + }); + + test('HostBridge 未处理时回退到浏览器 Clipboard API', async () => { + vi.spyOn(hostBridge, 'writeHostClipboardText').mockResolvedValue(false); + const writeText = vi.fn(async () => undefined); + Object.defineProperty(navigator, 'clipboard', { + configurable: true, + value: { writeText }, + }); + + await expect(copyTextToClipboard(' PZ-00000002 ')).resolves.toBe(true); + + expect(writeText).toHaveBeenCalledWith('PZ-00000002'); + }); + + test('空文本不触发宿主或浏览器复制', async () => { + const writeHostClipboardText = vi + .spyOn(hostBridge, 'writeHostClipboardText') + .mockResolvedValue(true); + const writeText = vi.fn(); + Object.defineProperty(navigator, 'clipboard', { + configurable: true, + value: { writeText }, + }); + + await expect(copyTextToClipboard(' ')).resolves.toBe(false); + + expect(writeHostClipboardText).not.toHaveBeenCalled(); + expect(writeText).not.toHaveBeenCalled(); + }); +}); diff --git a/src/services/clipboard.ts b/src/services/clipboard.ts index 3ba44864..eb6a6260 100644 --- a/src/services/clipboard.ts +++ b/src/services/clipboard.ts @@ -1,9 +1,15 @@ +import { writeHostClipboardText } from './host-bridge/hostBridge'; + export async function copyTextToClipboard(value: string) { const text = value.trim(); if (!text) { return false; } + if (await writeHostClipboardText({ text })) { + return true; + } + if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) { try { await navigator.clipboard.writeText(text); diff --git a/src/services/host-bridge/hostBridge.test.ts b/src/services/host-bridge/hostBridge.test.ts index 9fa3b859..afc7996b 100644 --- a/src/services/host-bridge/hostBridge.test.ts +++ b/src/services/host-bridge/hostBridge.test.ts @@ -18,6 +18,7 @@ import { requestWechatMiniProgramPhoneLogin, resolveHostRuntime, setHostShareTarget, + writeHostClipboardText, } from './hostBridge'; import { resetNativeAppHostBridgeForTest } from './nativeAppHostBridge'; @@ -307,6 +308,9 @@ describe('hostBridge', () => { shell: 'tauri_desktop', platform: 'linux', }); + await expect( + writeHostClipboardText({ text: '作品号 PZ-1' }), + ).resolves.toBe(true); expect(invoke).toHaveBeenCalledWith('host_bridge_request', { request: expect.objectContaining({ @@ -328,6 +332,14 @@ describe('hostBridge', () => { }, }), }); + expect(invoke).toHaveBeenCalledWith('host_bridge_request', { + request: expect.objectContaining({ + method: 'clipboard.writeText', + payload: { + text: '作品号 PZ-1', + }, + }), + }); }); test('原生 App 宿主不支持能力时回退到 H5 路径', async () => { @@ -358,6 +370,9 @@ describe('hostBridge', () => { orderId: 'order-1', }), ).resolves.toBe(false); + await expect( + writeHostClipboardText({ text: '作品号 PZ-1' }), + ).resolves.toBe(false); }); test('普通浏览器不处理宿主文本导出', async () => { diff --git a/src/services/host-bridge/hostBridge.ts b/src/services/host-bridge/hostBridge.ts index f8ff671b..45f30e12 100644 --- a/src/services/host-bridge/hostBridge.ts +++ b/src/services/host-bridge/hostBridge.ts @@ -61,6 +61,10 @@ export type HostShareGridRequest = { export type HostFileExportTextRequest = FileExportTextPayload; +export type HostClipboardWriteTextRequest = { + text: string; +}; + function isUnsupportedHostBridgeError(error: unknown) { return ( error instanceof Error && @@ -449,6 +453,20 @@ export async function getNativeAppHostRuntime() { ); } +export async function writeHostClipboardText({ + text, +}: HostClipboardWriteTextRequest) { + if (getHostRuntime().kind !== 'native_app') { + return false; + } + + try { + return await requestNativeHostBoolean('clipboard.writeText', { text }); + } catch { + return false; + } +} + export async function exportHostTextFile( params: HostFileExportTextRequest, ) {