接入原生壳外观查询能力

新增 HostBridge appearance.getColorScheme 只读契约和 H5 facade

Expo 壳通过 React Native Appearance 读取系统配色

Tauri 壳通过主窗口 theme 读取桌面配色

补齐外观查询测试、漂移检查和架构文档

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');
+  });
 });

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;
 };