From 048c879b203345c5f02a800e5e6f5cffd27849ba Mon Sep 17 00:00:00 2001 From: kdletters Date: Fri, 19 Jun 2026 15:10:23 +0800 Subject: [PATCH] =?UTF-8?q?=E6=94=B6=E7=B4=A7=E5=89=AA=E8=B4=B4=E6=9D=BF?= =?UTF-8?q?=E5=86=99=E5=85=A5=E6=96=87=E6=9C=AC=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 让 Expo 和 Tauri 壳在写系统剪贴板前按共享上限截断文本 增加移动壳剪贴板写入边界测试和两端配置门禁 补充宿主壳协议文档和共享决策记录 --- apps/desktop-shell/scripts/check-config.mjs | 1 + .../src-tauri/src/host_bridge/dispatch.rs | 10 +++++----- apps/mobile-shell/scripts/check-config.mjs | 10 ++++++++++ apps/mobile-shell/src/host-bridge/bridge.test.ts | 11 +++++++++++ apps/mobile-shell/src/host-bridge/dispatch.ts | 8 +++++--- docs/project-memory/shared-memory/decision-log.md | 2 +- docs/【前端架构】宿主壳能力统一协议-2026-06-17.md | 2 +- 7 files changed, 34 insertions(+), 10 deletions(-) diff --git a/apps/desktop-shell/scripts/check-config.mjs b/apps/desktop-shell/scripts/check-config.mjs index 695e173bc..d3c9b82a0 100644 --- a/apps/desktop-shell/scripts/check-config.mjs +++ b/apps/desktop-shell/scripts/check-config.mjs @@ -1742,6 +1742,7 @@ const requiredRustHostSnippets = [ '"file.exportAudio"', '"file.imageDropped"', '"notification.showLocal"', + 'Ok(text) => normalize_clipboard_text(text)', 'tauri_plugin_dialog::init()', 'tauri_plugin_notification::init()', 'tauri_plugin_notification::{NotificationExt, PermissionState}', diff --git a/apps/desktop-shell/src-tauri/src/host_bridge/dispatch.rs b/apps/desktop-shell/src-tauri/src/host_bridge/dispatch.rs index 2af5e9563..9cc5aa559 100644 --- a/apps/desktop-shell/src-tauri/src/host_bridge/dispatch.rs +++ b/apps/desktop-shell/src-tauri/src/host_bridge/dispatch.rs @@ -60,7 +60,7 @@ fn badge_count_payload(request: &HostBridgeRequest) -> Result, HostB Ok(if count == 0 { None } else { Some(count) }) } -fn normalize_clipboard_text(text: String) -> String { +fn normalize_clipboard_text(text: &str) -> String { text.chars().take(CLIPBOARD_TEXT_MAX_LENGTH).collect() } @@ -239,7 +239,7 @@ pub(super) async fn execute_host_bridge_request( }, "clipboard.writeText" => { let text = match required_string_payload(&request, "text") { - Ok(text) => text, + Ok(text) => normalize_clipboard_text(text), Err(response) => return response, }; @@ -252,7 +252,7 @@ pub(super) async fn execute_host_bridge_request( Ok(text) => ok( request.id, json!({ - "text": normalize_clipboard_text(text), + "text": normalize_clipboard_text(&text), }), ), Err(error) => failed(request.id, "host_error", error.to_string()), @@ -676,11 +676,11 @@ mod tests { #[test] fn clipboard_text_is_truncated_to_contract_limit() { assert_eq!( - normalize_clipboard_text("作品号 PZ-1".to_string()), + normalize_clipboard_text("作品号 PZ-1"), "作品号 PZ-1" ); assert_eq!( - normalize_clipboard_text("a".repeat(CLIPBOARD_TEXT_MAX_LENGTH + 10)).len(), + normalize_clipboard_text(&"a".repeat(CLIPBOARD_TEXT_MAX_LENGTH + 10)).len(), CLIPBOARD_TEXT_MAX_LENGTH ); } diff --git a/apps/mobile-shell/scripts/check-config.mjs b/apps/mobile-shell/scripts/check-config.mjs index 173651eae..3b11d5a13 100644 --- a/apps/mobile-shell/scripts/check-config.mjs +++ b/apps/mobile-shell/scripts/check-config.mjs @@ -1494,6 +1494,16 @@ for (const snippet of [ throw new Error(`mobile shell HostBridge missing ${snippet}`); } } +if ( + !hostBridgeSource.includes( + 'const clipboardText = normalizeHostBridgeClipboardText(', + ) || + !hostBridgeSource.includes('Clipboard.setStringAsync(clipboardText.text)') +) { + throw new Error( + 'mobile shell clipboard.writeText must normalize text with the shared HostBridge clipboard boundary', + ); +} for (const snippet of [ 'CameraView', diff --git a/apps/mobile-shell/src/host-bridge/bridge.test.ts b/apps/mobile-shell/src/host-bridge/bridge.test.ts index ce5b6c5f4..8f7eeaf19 100644 --- a/apps/mobile-shell/src/host-bridge/bridge.test.ts +++ b/apps/mobile-shell/src/host-bridge/bridge.test.ts @@ -664,6 +664,17 @@ describe('handleMobileHostBridgeMessage', () => { expect(Clipboard.getStringAsync).toHaveBeenCalled(); }); + test('clipboard.writeText 写入前按共享上限截断文本', async () => { + const response = await send( + request('clipboard.writeText', { + text: 'a'.repeat(100010), + }), + ); + + expectOk(response); + expect(Clipboard.setStringAsync).toHaveBeenCalledWith('a'.repeat(100000)); + }); + test('clipboard.readText 读取失败时返回 host_error', async () => { vi.mocked(Clipboard.getStringAsync).mockRejectedValue( new Error('clipboard unavailable'), diff --git a/apps/mobile-shell/src/host-bridge/dispatch.ts b/apps/mobile-shell/src/host-bridge/dispatch.ts index de900d9bd..1d2211b43 100644 --- a/apps/mobile-shell/src/host-bridge/dispatch.ts +++ b/apps/mobile-shell/src/host-bridge/dispatch.ts @@ -90,12 +90,14 @@ async function openExternalUrl(payload: unknown) { } async function writeClipboard(payload: unknown) { - const text = (payload as ClipboardWriteTextPayload | undefined)?.text; - if (typeof text !== 'string') { + const clipboardText = normalizeHostBridgeClipboardText( + (payload as ClipboardWriteTextPayload | undefined)?.text, + ); + if (!clipboardText) { throw invalidRequest('text is required'); } - await Clipboard.setStringAsync(text); + await Clipboard.setStringAsync(clipboardText.text); return true; } diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 334521148..a4f97ab4e 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 并完成上限校验，无法拿到可信大小时直接拒绝导入。`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 长度、角标上限、剪贴板文本长度和本地通知标题 / 正文长度。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 字符上限，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`、`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 49ea07ccc..0de953097 100644 --- a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md +++ b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md @@ -61,7 +61,7 @@ Tauri 桌面壳启动时必须按 `label="main"` 解析 `tauri.conf.json` 主窗 - `setHostShareTarget()`：把当前公开作品分享目标同步给宿主。 - `openHostShare()`：原生 App 宿主的受控分享入口。发布分享弹窗只在 `hostCapabilities` 声明 `share.open` 时展示“系统分享”，通过 `share.open` 把当前作品标题、作品号和公开 URL 交给宿主；Expo 移动壳打开系统分享面板，Tauri 桌面壳把分享文本写入系统剪贴板。两端都只能把 `url`、`href`、`path`、`targetPath` 和 `work` 归一到 `https://app.genarrative.world` 同源公开 URL，外域、协议相对 URL、危险协议和无法归一的显式分享目标必须返回 `invalid_request`，且不得回退到之前缓存的 `share.setTarget` 目标；宿主不可用或返回 unsupported 时显示失败并保留复制链接路径。 - `openHostShareGrid()`：微信小程序九宫格切图页。 -- `writeHostClipboardText()`：原生 App 宿主的受控剪贴板入口。H5 复制服务在 `native_app` 中优先通过 `clipboard.writeText` 写入 Expo / Tauri 系统剪贴板；宿主不可用、拒绝或返回 unsupported 时继续回退到浏览器 Clipboard API 和 legacy selection copy。 +- `writeHostClipboardText()`：原生 App 宿主的受控剪贴板入口。H5 复制服务在 `native_app` 中优先通过 `clipboard.writeText` 写入 Expo / Tauri 系统剪贴板；两端壳写入前必须按共享契约 `HOST_BRIDGE_CLIPBOARD_TEXT_MAX_LENGTH` 截断文本，不能让 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`。 - `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。