接入原生壳外观查询能力

新增 HostBridge appearance.getColorScheme 只读契约和 H5 facade Expo 壳通过 React Native Appearance 读取系统配色 Tauri 壳通过主窗口 theme 读取桌面配色补齐外观查询测试、漂移检查和架构文档
2026-06-18 02:00:49 +08:00
parent 6b39bdbe19
commit 45eec17007
13 changed files with 164 additions and 15 deletions
--- a/apps/desktop-shell/scripts/check-config.mjs
+++ b/apps/desktop-shell/scripts/check-config.mjs
@@ -133,6 +133,7 @@ const requiredPermissions = [
 const requiredBuildCommands = ['host_bridge_request'];
 const requiredMainSnippets = [
  'tauri_plugin_clipboard_manager::init()',
+  '"appearance.getColorScheme"',
  '"share.open"',
  '"share.setTarget"',
  '"navigation.openNativePage"',
@@ -147,6 +148,7 @@ const requiredMainSnippets = [
  'BASE64_STANDARD.decode',
  'set_title',
  'set_badge_count',
+  'window.theme()',
 ];

 for (const permission of requiredPermissions) {
--- a/apps/desktop-shell/src-tauri/src/main.rs
+++ b/apps/desktop-shell/src-tauri/src/main.rs
@@ -5,6 +5,7 @@ use std::fs;
 use std::path::PathBuf;
 use std::sync::Mutex;
 use tauri::Manager;
+use tauri::Theme;
 use tauri::Url;
 use tauri_plugin_clipboard_manager::ClipboardExt;
 use tauri_plugin_dialog::DialogExt;
@@ -79,6 +80,7 @@ fn desktop_platform() -> &'static str {
 fn capabilities() -> Vec<&'static str> {
    vec![
        "host.getRuntime",
+        "appearance.getColorScheme",
        "share.open",
        "share.setTarget",
        "navigation.openNativePage",
@@ -116,6 +118,14 @@ fn failed(id: String, code: &'static str, message: impl Into<String>) -> HostBri
    }
 }

+fn color_scheme_from_theme(theme: Theme) -> &'static str {
+    match theme {
+        Theme::Light => "light",
+        Theme::Dark => "dark",
+        _ => "unknown",
+    }
+}
+
 fn validate_request(request: &HostBridgeRequest) -> Option<HostBridgeResponse> {
    if request.bridge != HOST_BRIDGE_PROTOCOL || request.version != HOST_BRIDGE_VERSION {
        return Some(failed(
@@ -520,6 +530,18 @@ async fn host_bridge_request(
                Err(error) => failed(request.id, "host_error", error.to_string()),
            }
        }
+        "appearance.getColorScheme" => match app.get_webview_window("main") {
+            Some(window) => match window.theme() {
+                Ok(theme) => ok(
+                    request.id,
+                    json!({
+                        "colorScheme": color_scheme_from_theme(theme)
+                    }),
+                ),
+                Err(error) => failed(request.id, "host_error", error.to_string()),
+            },
+            None => failed(request.id, "host_error", "main window not found"),
+        },
        "navigation.openNativePage" => {
            let url = match required_string_payload(&request, "url")
                .ok()
@@ -737,6 +759,10 @@ mod tests {
        assert_eq!(result["shell"], "tauri_desktop");
        assert_eq!(result["bridgeVersion"], HOST_BRIDGE_VERSION);
        assert_eq!(result["capabilities"], json!(capabilities()));
+        assert!(result["capabilities"]
+            .as_array()
+            .unwrap()
+            .contains(&json!("appearance.getColorScheme")));
        assert!(result["capabilities"]
            .as_array()
            .unwrap()
@@ -801,6 +827,12 @@ mod tests {
        assert_eq!(error.message, "text is required");
    }

+    #[test]
+    fn color_scheme_maps_window_theme() {
+        assert_eq!(color_scheme_from_theme(Theme::Light), "light");
+        assert_eq!(color_scheme_from_theme(Theme::Dark), "dark");
+    }
+
    #[test]
    fn external_url_normalization_allows_only_safe_protocols() {
        assert_eq!(
--- a/apps/desktop-shell/src-tauri/tauri.conf.json
+++ b/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,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,clipboard.writeText,file.exportText,file.exportImage",
+    "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,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,clipboard.writeText,file.exportText,file.exportImage",
    "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,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,clipboard.writeText,file.exportText,file.exportImage",
+        "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,share.open,share.setTarget,navigation.openNativePage,app.openExternalUrl,app.setTitle,app.setBadgeCount,clipboard.writeText,file.exportText,file.exportImage",
        "title": "Genarrative",
        "width": 1280,
        "height": 820,
--- a/apps/mobile-shell/scripts/check-config.mjs
+++ b/apps/mobile-shell/scripts/check-config.mjs
@@ -153,6 +153,7 @@ if (!appSource.includes('capabilities: resolveMobileHostCapabilities()')) {

 for (const capability of [
  'host.getRuntime',
+  'appearance.getColorScheme',
  'share.open',
  'share.setTarget',
  'navigation.openNativePage',
@@ -175,3 +176,7 @@ if (!iosMobileCapabilitySet.has('app.setBadgeCount')) {
 if (mobileCapabilitySet.has('app.setBadgeCount')) {
  throw new Error('Android mobile shell base capabilities must not include app.setBadgeCount');
 }
+
+if (!bridgeSource.includes('Appearance.getColorScheme()')) {
+  throw new Error('mobile shell HostBridge must read the native color scheme');
+}
--- a/apps/mobile-shell/src/mobileHostBridge.test.ts
+++ b/apps/mobile-shell/src/mobileHostBridge.test.ts
@@ -1,7 +1,12 @@
 import * as Haptics from 'expo-haptics';
 import * as Linking from 'expo-linking';
 import * as Sharing from 'expo-sharing';
-import { Platform, PushNotificationIOS, Share } from 'react-native';
+import {
+  Appearance,
+  Platform,
+  PushNotificationIOS,
+  Share,
+} from 'react-native';
 import { afterEach, describe, expect, test, vi } from 'vitest';

 import {
@@ -70,6 +75,9 @@ vi.mock('expo-sharing', () => ({
 }));

 vi.mock('react-native', () => ({
+  Appearance: {
+    getColorScheme: vi.fn(() => 'light'),
+  },
  Platform: {
    OS: 'ios',
  },
@@ -130,6 +138,8 @@ function setPlatformOS(os: 'ios' | 'android') {
 }

 afterEach(() => {
+  vi.mocked(Appearance.getColorScheme).mockReset();
+  vi.mocked(Appearance.getColorScheme).mockReturnValue('light');
  vi.mocked(Haptics.impactAsync).mockReset();
  vi.mocked(Linking.openURL).mockReset();
  vi.mocked(PushNotificationIOS.setApplicationIconBadgeNumber).mockReset();
@@ -162,6 +172,7 @@ describe('handleMobileHostBridgeMessage', () => {
      (okResponse.result as { capabilities: string[] }).capabilities,
    ).toEqual(
      expect.arrayContaining([
+        'appearance.getColorScheme',
        'host.events',
        'navigation.canGoBack',
        'app.setBadgeCount',
@@ -184,6 +195,26 @@ describe('handleMobileHostBridgeMessage', () => {
    ).not.toContain('app.setBadgeCount');
  });

+  test('appearance.getColorScheme 返回系统配色模式', async () => {
+    vi.mocked(Appearance.getColorScheme).mockReturnValue('dark');
+
+    const response = await send(request('appearance.getColorScheme'));
+
+    expect(expectOk(response).result).toEqual({
+      colorScheme: 'dark',
+    });
+  });
+
+  test('appearance.getColorScheme 归一化未知系统配色', async () => {
+    vi.mocked(Appearance.getColorScheme).mockReturnValue('unspecified');
+
+    const response = await send(request('appearance.getColorScheme'));
+
+    expect(expectOk(response).result).toEqual({
+      colorScheme: 'unknown',
+    });
+  });
+
  test('navigation.openNativePage 把同源路径切到移动壳 WebView', async () => {
    const openWebViewUrl = vi.fn();
    configureMobileHostBridgeNavigation({
--- a/apps/mobile-shell/src/mobileHostBridge.ts
+++ b/apps/mobile-shell/src/mobileHostBridge.ts
@@ -3,7 +3,12 @@ import { File, Paths } from 'expo-file-system';
 import * as Haptics from 'expo-haptics';
 import * as Linking from 'expo-linking';
 import * as Sharing from 'expo-sharing';
-import { Platform, PushNotificationIOS, Share } from 'react-native';
+import {
+  Appearance,
+  Platform,
+  PushNotificationIOS,
+  Share,
+} from 'react-native';

 import {
  type ClipboardWriteTextPayload,
@@ -21,6 +26,7 @@ import {
  type HostBridgeResponse,
  type NavigateNativePagePayload,
  normalizeHostBridgeBadgeCount,
+  normalizeHostBridgeColorScheme,
  normalizeHostBridgeExportFileName,
  normalizeHostBridgeExternalUrl,
  type OpenExternalUrlPayload,
@@ -40,6 +46,7 @@ const EXPORT_IMAGE_MIME_TYPES = new Set([

 export const MOBILE_HOST_CAPABILITIES: HostBridgeCapability[] = [
  'host.getRuntime',
+  'appearance.getColorScheme',
  'host.events',
  'share.open',
  'share.setTarget',
@@ -309,6 +316,12 @@ function setBadgeCount(payload: unknown) {
  return true;
 }

+function getColorScheme() {
+  return {
+    colorScheme: normalizeHostBridgeColorScheme(Appearance.getColorScheme()),
+  };
+}
+
 function stringField(value: unknown, field: string) {
  if (!value || typeof value !== 'object') {
    return undefined;
@@ -419,6 +432,8 @@ async function handleRequest(request: HostBridgeRequest) {
        bridgeVersion: HOST_BRIDGE_VERSION,
        capabilities: resolveMobileHostCapabilities(),
      });
+    case 'appearance.getColorScheme':
+      return ok(request, getColorScheme());
    case 'app.openExternalUrl':
      return ok(request, await openExternalUrl(request.payload));
    case 'clipboard.writeText':
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -29,6 +29,7 @@
 - 2026-06-18 原生壳统一验收门禁：根级 `npm run check:native-shells` 统一执行 H5 HostBridge 关键测试、Expo 壳 typecheck / test 和 Tauri 壳 typecheck / cargo test；根级 `npm run check` 会在 lint、主站测试、构建和内容检查后继续执行该门禁，避免 HostBridge 与两端壳验收散落成容易漏跑的单项命令。
 - 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 宿主外观只读查询：新增 `appearance.getColorScheme` HostBridge capability，Expo 壳通过 React Native `Appearance.getColorScheme()` 读取系统配色，Tauri 壳通过主窗口 `theme()` 读取窗口主题；该能力只返回 `light` / `dark` / `unknown`，不设置 H5 主题、不覆盖系统主题，也不作为强制 UI 样式入口。
 - 影响范围：`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`。
--- a/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md
+++ b/docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md
@@ -111,6 +111,7 @@ type HostBridgeEvent = {
 | method | 用途 | Expo 壳 | Tauri 壳 |
 | --- | --- | --- | --- |
 | `host.getRuntime` | 返回宿主、平台、版本和能力清单 | 支持 | 支持 |
+| `appearance.getColorScheme` | 读取宿主当前配色模式 | 支持系统 Appearance 读取 | 支持窗口 theme 读取 |
 | `auth.requestLogin` | 打开宿主登录或账号绑定流程 | 支持 | 可先返回不支持 |
 | `payment.request` | 发起宿主支付 | 依平台策略接入 | 桌面二维码 / 外部浏览器 |
 | `share.setTarget` | 同步当前作品分享目标 | 支持 | 支持 |
@@ -243,7 +244,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`、`file.exportImage`、`haptics.impact` 和 Android 返回键回退；iOS 额外声明 `app.setBadgeCount`，通过 React Native `PushNotificationIOS` 设置应用图标角标，Android 不声明该能力。H5 会解析并过滤 `hostCapabilities`，也会在主 App 启动时通过真实 `host.getRuntime` 回读并缓存能力，只对声明或回读到的能力展示入口或调用宿主能力；其中 `share.setTarget` / `share.open` 会解析统一分享目标里的 `title`、`message`、`url`、`work`、`path` 或 `targetPath` 并调用 React Native 系统分享面板；发布分享弹窗只有在宿主声明 `share.open` 时才提供“系统分享”动作，失败时保留复制链接回退路径；`navigation.openNativePage` 在 Expo 壳内只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的登录、支付或其它原生页面，`navigation.canGoBack` 由 WebView 导航状态变化实时注入 H5，WebView 自身拦截到外域导航时只会把 `http:`、`https:`、`mailto:`、`tel:` 交给系统，危险协议直接阻断；`app.openExternalUrl` 也只允许同一协议白名单，ICP备案号和资产调试原图等 H5 外链入口在 `native_app` 中优先通过该能力离开 WebView 并交给系统浏览器；`clipboard.writeText` 由 H5 复制服务优先调用并写入系统剪贴板；`file.exportText` 通过 Expo 文件系统写入缓存文本文件，再交给系统分享 / 保存面板，文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数；`file.exportImage` 通过 Expo 文件系统写入缓存图片，再交给系统分享 / 保存面板，H5 只传允许 MIME 的 base64 图片数据，单次不超过 5 MiB，分享卡下载会优先走该能力；`haptics.impact` 通过 Expo Haptics 承接运行时轻触反馈，H5 在宿主不支持时回退到浏览器 vibration。登录和支付尚未接入渠道 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`、`appearance.getColorScheme`、`host.events`、`share.open`、`share.setTarget`、`navigation.openNativePage`、`navigation.canGoBack`、`app.openExternalUrl`、`clipboard.writeText`、`file.exportText`、`file.exportImage`、`haptics.impact` 和 Android 返回键回退；其中 `appearance.getColorScheme` 只读系统配色偏好，不强改 H5 或系统主题；iOS 额外声明 `app.setBadgeCount`，通过 React Native `PushNotificationIOS` 设置应用图标角标，Android 不声明该能力。H5 会解析并过滤 `hostCapabilities`，也会在主 App 启动时通过真实 `host.getRuntime` 回读并缓存能力，只对声明或回读到的能力展示入口或调用宿主能力；其中 `share.setTarget` / `share.open` 会解析统一分享目标里的 `title`、`message`、`url`、`work`、`path` 或 `targetPath` 并调用 React Native 系统分享面板；发布分享弹窗只有在宿主声明 `share.open` 时才提供“系统分享”动作，失败时保留复制链接回退路径；`navigation.openNativePage` 在 Expo 壳内只接受同源 H5 route 并切换 WebView URL，不伪造尚未存在的登录、支付或其它原生页面，`navigation.canGoBack` 由 WebView 导航状态变化实时注入 H5，WebView 自身拦截到外域导航时只会把 `http:`、`https:`、`mailto:`、`tel:` 交给系统，危险协议直接阻断；`app.openExternalUrl` 也只允许同一协议白名单，ICP备案号和资产调试原图等 H5 外链入口在 `native_app` 中优先通过该能力离开 WebView 并交给系统浏览器；`clipboard.writeText` 由 H5 复制服务优先调用并写入系统剪贴板；`file.exportText` 通过 Expo 文件系统写入缓存文本文件，再交给系统分享 / 保存面板，文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数；`file.exportImage` 通过 Expo 文件系统写入缓存图片，再交给系统分享 / 保存面板，H5 只传允许 MIME 的 base64 图片数据，单次不超过 5 MiB，分享卡下载会优先走该能力；`haptics.impact` 通过 Expo Haptics 承接运行时轻触反馈，H5 在宿主不支持时回退到浏览器 vibration。登录和支付尚未接入渠道 SDK / 原生页面时明确返回 unsupported，让 H5 fallback 承接。

 ### Phase 3：Tauri 桌面壳 MVP

@@ -254,7 +255,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:` 外链协议，ICP备案号和资产调试原图等 H5 外链入口在 `native_app` 中优先通过该能力离开主窗口并交给系统浏览器；`navigation.openNativePage` 只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内受控跳转，`clipboard.writeText` 由 Rust 内部通过 clipboard-manager 插件写入系统剪贴板并由 H5 复制服务优先调用，`app.setTitle` 通过 Tauri 主窗口 API 同步窗口标题并拒绝空标题 / 控制字符，`app.setBadgeCount` 通过主窗口 `set_badge_count` 设置任务栏角标，数量只接受 `0-99999` 整数且 `0` 表示清除；H5 主站会按当前平台阶段先更新 `document.title`，再通过 `app.setTitle` 把同一标题同步给 Tauri 窗口，Expo 移动壳不声明该能力时静默忽略；不把 opener、clipboard 或 dialog 插件命令直接暴露给前端。当前真实能力为 `host.getRuntime`、`share.setTarget`、`share.open`、`navigation.openNativePage`、`app.openExternalUrl`、`app.setTitle`、`app.setBadgeCount`、`clipboard.writeText`、`file.exportText` 和 `file.exportImage`；H5 会在主 App 启动时通过真实 `host.getRuntime` 回读并缓存这些能力，即使入口 URL 缺少 `hostCapabilities`，也只按宿主真实回包开启能力入口；其中 `share.open` 会把直接传入的分享 payload 或 `share.setTarget` 缓存的作品目标整理成非空分享文本并写入系统剪贴板，返回 `copied_to_clipboard`，发布分享弹窗在桌面壳中也通过该能力提供“系统分享”动作；`file.exportText` 通过系统保存对话框让用户选择本地路径，清洗文件名、限制单次文本导出不超过 5 MiB，写入成功后只返回文件名和字节数，不把本机绝对路径暴露给 H5，用户取消返回 `cancelled`；`file.exportImage` 同样通过系统保存对话框写入 H5 生成的图片字节，只接受 `image/png` / `image/jpeg` / `image/webp` base64 数据，单次不超过 5 MiB，分享卡下载会优先走该能力，用户取消返回 `cancelled`。原生系统分享面板、登录和支付未接入真实插件 / 渠道前不声明支持，不返回 mock 成功。
+当前状态：已新增 `apps/desktop-shell/`，Tauri dev 直接加载本地主站 Vite，release 打包根 `dist` 主站资产。Rust 侧只把 `host_bridge_request` command 授给主窗口，`appearance.getColorScheme` 由 Rust 内部读取主窗口 `theme()` 并返回 `light` / `dark` / `unknown`，不设置或覆盖系统主题；`app.openExternalUrl` 由 Rust 内部通过 opener 插件执行且只允许 `http:`、`https:`、`mailto:`、`tel:` 外链协议，ICP备案号和资产调试原图等 H5 外链入口在 `native_app` 中优先通过该能力离开主窗口并交给系统浏览器；`navigation.openNativePage` 只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内受控跳转，`clipboard.writeText` 由 Rust 内部通过 clipboard-manager 插件写入系统剪贴板并由 H5 复制服务优先调用，`app.setTitle` 通过 Tauri 主窗口 API 同步窗口标题并拒绝空标题 / 控制字符，`app.setBadgeCount` 通过主窗口 `set_badge_count` 设置任务栏角标，数量只接受 `0-99999` 整数且 `0` 表示清除；H5 主站会按当前平台阶段先更新 `document.title`，再通过 `app.setTitle` 把同一标题同步给 Tauri 窗口，Expo 移动壳不声明该能力时静默忽略；不把 opener、clipboard 或 dialog 插件命令直接暴露给前端。当前真实能力为 `host.getRuntime`、`appearance.getColorScheme`、`share.setTarget`、`share.open`、`navigation.openNativePage`、`app.openExternalUrl`、`app.setTitle`、`app.setBadgeCount`、`clipboard.writeText`、`file.exportText` 和 `file.exportImage`；H5 会在主 App 启动时通过真实 `host.getRuntime` 回读并缓存这些能力，即使入口 URL 缺少 `hostCapabilities`，也只按宿主真实回包开启能力入口；其中 `share.open` 会把直接传入的分享 payload 或 `share.setTarget` 缓存的作品目标整理成非空分享文本并写入系统剪贴板，返回 `copied_to_clipboard`，发布分享弹窗在桌面壳中也通过该能力提供“系统分享”动作；`file.exportText` 通过系统保存对话框让用户选择本地路径，清洗文件名、限制单次文本导出不超过 5 MiB，写入成功后只返回文件名和字节数，不把本机绝对路径暴露给 H5，用户取消返回 `cancelled`；`file.exportImage` 同样通过系统保存对话框写入 H5 生成的图片字节，只接受 `image/png` / `image/jpeg` / `image/webp` base64 数据，单次不超过 5 MiB，分享卡下载会优先走该能力，用户取消返回 `cancelled`。原生系统分享面板、登录和支付未接入真实插件 / 渠道前不声明支持，不返回 mock 成功。

 ### Phase 4：宿主能力扩展

--- a/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md
+++ b/docs/【前端架构】宿主壳能力统一协议-2026-06-17.md
@@ -40,6 +40,7 @@ AI H5 sandbox
 ## 首批能力

 - `getHostRuntime()`：识别 `browser`、`wechat_mini_program`、`native_app`，并解析 `hostCapabilities` 能力声明；进入 `native_app` 后会通过真实 `host.getRuntime` 回读宿主 runtime 并缓存能力清单，未知能力会被丢弃。H5 业务只根据已声明或已回读的能力展示入口、发起宿主请求或走 fallback。
+- `getHostAppearanceColorScheme()`：原生 App 宿主的受控外观查询入口。H5 可通过 `appearance.getColorScheme` 读取宿主当前 `light` / `dark` / `unknown` 配色模式；Expo 移动壳通过 React Native `Appearance.getColorScheme()` 读取系统偏好，Tauri 桌面壳通过主窗口 `theme()` 读取窗口主题。该能力只读，不改变 H5 主题，也不覆盖用户或系统偏好。
 - `requestHostLogin()`：微信小程序跳转原生登录页；浏览器返回 `false`，由 H5 登录弹窗承接。
 - `requestHostPayment()`：微信小程序支付跳转原生支付页；其它渠道返回 `false`，继续走 H5 / Native 二维码。
 - `setHostShareTarget()`：把当前公开作品分享目标同步给宿主。
--- a/packages/shared/src/contracts/hostBridge.test.ts
+++ b/packages/shared/src/contracts/hostBridge.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, test } from 'vitest';
 import {
  isHostBridgeCapability,
  normalizeHostBridgeBadgeCount,
+  normalizeHostBridgeColorScheme,
  normalizeHostBridgeExportFileName,
  normalizeHostBridgeExternalUrl,
 } from './hostBridge';
@@ -46,6 +47,7 @@ describe('HostBridge shared contract helpers', () => {
  });

  test('识别 HostBridge 能力白名单', () => {
+    expect(isHostBridgeCapability('appearance.getColorScheme')).toBe(true);
    expect(isHostBridgeCapability('share.open')).toBe(true);
    expect(isHostBridgeCapability('app.setBadgeCount')).toBe(true);
    expect(isHostBridgeCapability('navigation.canGoBack')).toBe(true);
@@ -62,4 +64,11 @@ describe('HostBridge shared contract helpers', () => {
    expect(normalizeHostBridgeBadgeCount(100000)).toBeNull();
    expect(normalizeHostBridgeBadgeCount('1')).toBeNull();
  });
+
+  test('归一化宿主配色模式', () => {
+    expect(normalizeHostBridgeColorScheme('light')).toBe('light');
+    expect(normalizeHostBridgeColorScheme('dark')).toBe('dark');
+    expect(normalizeHostBridgeColorScheme('unspecified')).toBe('unknown');
+    expect(normalizeHostBridgeColorScheme(null)).toBe('unknown');
+  });
 });
--- a/packages/shared/src/contracts/hostBridge.ts
+++ b/packages/shared/src/contracts/hostBridge.ts
@@ -15,6 +15,7 @@ export type NativeHostPlatform =

 export const HOST_BRIDGE_METHODS = [
  'host.getRuntime',
+  'appearance.getColorScheme',
  'auth.requestLogin',
  'payment.request',
  'share.setTarget',
@@ -102,6 +103,20 @@ export type NavigationCanGoBackEventPayload = {
  canGoBack: boolean;
 };

+export type HostAppearanceColorScheme = 'light' | 'dark' | 'unknown';
+
+export type AppearanceColorSchemeResult = {
+  colorScheme: HostAppearanceColorScheme;
+};
+
+export function normalizeHostBridgeColorScheme(
+  rawColorScheme: unknown,
+): HostAppearanceColorScheme {
+  return rawColorScheme === 'light' || rawColorScheme === 'dark'
+    ? rawColorScheme
+    : 'unknown';
+}
+
 export type NavigateNativePagePayload = {
  url: string;
 };
--- a/src/services/host-bridge/hostBridge.test.ts
+++ b/src/services/host-bridge/hostBridge.test.ts
@@ -8,6 +8,7 @@ import {
  canUseNativeHostCapability,
  exportHostImageFile,
  exportHostTextFile,
+  getHostAppearanceColorScheme,
  getHostRuntime,
  getNativeAppHostRuntime,
  isWechatMiniProgramWebViewRuntime,
@@ -421,7 +422,8 @@ describe('hostBridge', () => {
        version: 1,
        id: request.id,
        ok: true,
-        result: request.method === 'host.getRuntime'
+        result:
+          request.method === 'host.getRuntime'
            ? {
                shell: 'tauri_desktop',
                platform: 'linux',
@@ -429,6 +431,8 @@ describe('hostBridge', () => {
                bridgeVersion: 1,
                capabilities: ['host.getRuntime'],
              }
+            : request.method === 'appearance.getColorScheme'
+              ? { colorScheme: 'dark' }
              : true,
      };
    });
@@ -437,6 +441,7 @@ describe('hostBridge', () => {
      '',
      nativeAppPath([
        'host.getRuntime',
+        'appearance.getColorScheme',
        'navigation.openNativePage',
        'auth.requestLogin',
        'payment.request',
@@ -456,6 +461,9 @@ describe('hostBridge', () => {
    };

    await expect(navigateHostNativePage('/settings')).resolves.toBe(true);
+    await expect(getHostAppearanceColorScheme()).resolves.toEqual({
+      colorScheme: 'dark',
+    });
    await expect(requestHostLogin()).resolves.toBe(true);
    await expect(
      requestHostPayment({
@@ -495,6 +503,11 @@ describe('hostBridge', () => {
      }),
    ).resolves.toBe(true);

+    expect(invoke).toHaveBeenCalledWith('host_bridge_request', {
+      request: expect.objectContaining({
+        method: 'appearance.getColorScheme',
+      }),
+    });
    expect(invoke).toHaveBeenCalledWith('host_bridge_request', {
      request: expect.objectContaining({
        method: 'navigation.openNativePage',
@@ -599,6 +612,7 @@ describe('hostBridge', () => {
    };

    await expect(navigateHostNativePage('/settings')).resolves.toBe(false);
+    await expect(getHostAppearanceColorScheme()).resolves.toBe(false);
    await expect(requestHostLogin()).resolves.toBe(false);
    await expect(
      requestHostPayment({
@@ -642,6 +656,7 @@ describe('hostBridge', () => {
  });

  test('普通浏览器不处理宿主文件导出', async () => {
+    await expect(getHostAppearanceColorScheme()).resolves.toBe(false);
    await expect(
      exportHostTextFile({
        fileName: '作品记录.txt',
--- a/src/services/host-bridge/hostBridge.ts
+++ b/src/services/host-bridge/hostBridge.ts
@@ -1,4 +1,5 @@
 import type {
+  AppearanceColorSchemeResult,
  FileExportImagePayload,
  FileExportImageResult,
  FileExportTextPayload,
@@ -14,6 +15,7 @@ import type {
 import {
  isHostBridgeCapability,
  normalizeHostBridgeBadgeCount,
+  normalizeHostBridgeColorScheme,
  normalizeHostBridgeExternalUrl,
 } from '../../../packages/shared/src/contracts/hostBridge';
 import type {
@@ -95,6 +97,8 @@ export type HostShareOpenRequest = ShareOpenPayload;

 export type HostExternalUrlRequest = OpenExternalUrlPayload;

+export type HostAppearanceColorSchemeSnapshot = AppearanceColorSchemeResult;
+
 const HOST_RUNTIME_REFRESH_TIMEOUT_MS = 3000;

 let cachedNativeHostRuntime: HostBridgeRuntimeResult | null = null;
@@ -764,3 +768,21 @@ export async function setHostAppBadgeCount({
    return false;
  }
 }
+
+export async function getHostAppearanceColorScheme() {
+  if (!canUseNativeHostCapability('appearance.getColorScheme')) {
+    return false;
+  }
+
+  try {
+    const result =
+      await requestNativeAppHostBridge<AppearanceColorSchemeResult>(
+        'appearance.getColorScheme',
+      );
+    return {
+      colorScheme: normalizeHostBridgeColorScheme(result?.colorScheme),
+    } satisfies HostAppearanceColorSchemeSnapshot;
+  } catch {
+    return false;
+  }
+}