接入移动壳图片导入能力

Expo 壳通过系统相册选择器实现 file.importImage

限制导入图片 MIME 与大小并避免暴露设备本地 URI

H5 facade 将用户取消导入归为无选择回退

更新移动壳依赖、配置校验、测试和架构文档

apps/mobile-shell/app.json

@@ -10,6 +10,16 @@
     "assetBundlePatterns": [
       "**/*"
     ],
+    "plugins": [
+      [
+        "expo-image-picker",
+        {
+          "photosPermission": "允许 Genarrative 读取你选择的图片，用于导入创作素材和参考图。",
+          "cameraPermission": false,
+          "microphonePermission": false
+        }
+      ]
+    ],
     "ios": {
       "supportsTablet": true,
       "associatedDomains": [

apps/mobile-shell/package.json

@@ -17,6 +17,7 @@
     "expo-clipboard": "^56.0.4",
     "expo-file-system": "^56.0.8",
     "expo-haptics": "^56.0.3",
+    "expo-image-picker": "^56.0.18",
     "expo-linking": "^56.0.14",
     "expo-network": "^56.0.5",
     "expo-sharing": "^56.0.18",

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

@@ -129,18 +129,46 @@ for (const snippet of [
   }
 }
 
-for (const dependency of ['expo-file-system', 'expo-network', 'expo-sharing']) {
+for (const dependency of [
+  'expo-file-system',
+  'expo-image-picker',
+  'expo-network',
+  'expo-sharing',
+]) {
   if (!packageConfig.dependencies?.[dependency]) {
     throw new Error(`mobile shell package missing ${dependency}`);
   }
 }
 
+const imagePickerPlugin = appConfig.plugins?.find((plugin) =>
+  Array.isArray(plugin) ? plugin[0] === 'expo-image-picker' : plugin === 'expo-image-picker',
+);
+if (!imagePickerPlugin) {
+  throw new Error('mobile shell image picker plugin is missing');
+}
+
+if (Array.isArray(imagePickerPlugin)) {
+  const pluginOptions = imagePickerPlugin[1] ?? {};
+  if (typeof pluginOptions.photosPermission !== 'string') {
+    throw new Error('mobile shell image picker photo permission text is missing');
+  }
+  if (
+    pluginOptions.cameraPermission !== false ||
+    pluginOptions.microphonePermission !== false
+  ) {
+    throw new Error('mobile shell image picker must not request camera or microphone');
+  }
+}
+
 for (const snippet of [
   'file.exportText',
   'file.exportImage',
+  'file.importImage',
   'network.status',
   'getMobileNetworkStatus',
   'Sharing.shareAsync',
+  'ImagePicker.launchImageLibraryAsync',
+  'ImagePicker.requestMediaLibraryPermissionsAsync',
   'normalizeHostBridgeExportFileName',
   'base64Data',
 ]) {
@@ -172,6 +200,7 @@ for (const capability of [
   'clipboard.writeText',
   'file.exportText',
   'file.exportImage',
+  'file.importImage',
   'haptics.impact',
 ]) {
   if (!mobileCapabilitySet.has(capability)) {

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

@@ -1,4 +1,5 @@
 import * as Haptics from 'expo-haptics';
+import * as ImagePicker from 'expo-image-picker';
 import * as Linking from 'expo-linking';
 import * as Network from 'expo-network';
 import * as Sharing from 'expo-sharing';
@@ -66,6 +67,15 @@ vi.mock('expo-haptics', () => ({
   impactAsync: vi.fn(),
 }));
 
+vi.mock('expo-image-picker', () => ({
+  PermissionStatus: {
+    DENIED: 'denied',
+    GRANTED: 'granted',
+  },
+  launchImageLibraryAsync: vi.fn(),
+  requestMediaLibraryPermissionsAsync: vi.fn(),
+}));
+
 vi.mock('expo-linking', () => ({
   openURL: vi.fn(),
 }));
@@ -156,6 +166,18 @@ afterEach(() => {
   vi.mocked(Appearance.getColorScheme).mockReset();
   vi.mocked(Appearance.getColorScheme).mockReturnValue('light');
   vi.mocked(Haptics.impactAsync).mockReset();
+  vi.mocked(ImagePicker.launchImageLibraryAsync).mockReset();
+  vi.mocked(ImagePicker.launchImageLibraryAsync).mockResolvedValue({
+    canceled: true,
+    assets: null,
+  });
+  vi.mocked(ImagePicker.requestMediaLibraryPermissionsAsync).mockReset();
+  vi.mocked(ImagePicker.requestMediaLibraryPermissionsAsync).mockResolvedValue({
+    status: ImagePicker.PermissionStatus.GRANTED,
+    granted: true,
+    canAskAgain: true,
+    expires: 'never',
+  });
   vi.mocked(Linking.openURL).mockReset();
   vi.mocked(Network.getNetworkStateAsync).mockReset();
   vi.mocked(Network.getNetworkStateAsync).mockResolvedValue({
@@ -189,6 +211,9 @@ describe('handleMobileHostBridgeMessage', () => {
     expect(
       (okResponse.result as { capabilities: string[] }).capabilities,
     ).toContain('file.exportText');
+    expect(
+      (okResponse.result as { capabilities: string[] }).capabilities,
+    ).toContain('file.importImage');
     expect(
       (okResponse.result as { capabilities: string[] }).capabilities,
     ).toEqual(
@@ -550,4 +575,117 @@ describe('handleMobileHostBridgeMessage', () => {
     expect(writtenFiles).toEqual([]);
     expect(Sharing.shareAsync).not.toHaveBeenCalled();
   });
+
+  test('file.importImage 调起系统相册并返回受控图片数据', async () => {
+    vi.mocked(ImagePicker.launchImageLibraryAsync).mockResolvedValue({
+      canceled: false,
+      assets: [
+        {
+          uri: 'file:///private/mobile/参考图.png',
+          width: 120,
+          height: 80,
+          type: 'image',
+          fileName: ' ../参考:图?.png ',
+          fileSize: 5,
+          base64: 'aW1hZ2U=',
+          mimeType: 'image/png',
+        },
+      ],
+    });
+
+    const response = await send(request('file.importImage'));
+
+    expect(expectOk(response).result).toEqual({
+      action: 'selected',
+      fileName: '参考-图-.png',
+      base64Data: 'aW1hZ2U=',
+      mimeType: 'image/png',
+      bytes: 5,
+    });
+    expect(ImagePicker.requestMediaLibraryPermissionsAsync).toHaveBeenCalled();
+    expect(ImagePicker.launchImageLibraryAsync).toHaveBeenCalledWith({
+      allowsEditing: false,
+      allowsMultipleSelection: false,
+      base64: true,
+      exif: false,
+      mediaTypes: ['images'],
+      quality: 1,
+    });
+  });
+
+  test('file.importImage 取消选择时返回 cancelled', async () => {
+    vi.mocked(ImagePicker.launchImageLibraryAsync).mockResolvedValue({
+      canceled: true,
+      assets: null,
+    });
+
+    const response = await send(request('file.importImage'));
+
+    const failedResponse = expectFailed(response);
+    expect(failedResponse.error.code).toBe('cancelled');
+  });
+
+  test('file.importImage 拒绝权限、非法 MIME 和超限图片', async () => {
+    vi.mocked(ImagePicker.requestMediaLibraryPermissionsAsync).mockResolvedValue(
+      {
+        status: ImagePicker.PermissionStatus.DENIED,
+        granted: false,
+        canAskAgain: false,
+        expires: 'never',
+      },
+    );
+
+    const denied = await send(request('file.importImage'));
+
+    expect(expectFailed(denied).error.code).toBe('host_error');
+    expect(ImagePicker.launchImageLibraryAsync).not.toHaveBeenCalled();
+
+    vi.mocked(ImagePicker.requestMediaLibraryPermissionsAsync).mockResolvedValue(
+      {
+        status: ImagePicker.PermissionStatus.GRANTED,
+        granted: true,
+        canAskAgain: true,
+        expires: 'never',
+      },
+    );
+    vi.mocked(ImagePicker.launchImageLibraryAsync).mockResolvedValue({
+      canceled: false,
+      assets: [
+        {
+          uri: 'file:///private/mobile/参考图.gif',
+          width: 120,
+          height: 80,
+          type: 'image',
+          fileName: '参考图.gif',
+          fileSize: 5,
+          base64: 'aW1hZ2U=',
+          mimeType: 'image/gif',
+        },
+      ],
+    });
+
+    const unsupportedMime = await send(request('file.importImage'));
+
+    expect(expectFailed(unsupportedMime).error.code).toBe('invalid_request');
+
+    vi.mocked(ImagePicker.launchImageLibraryAsync).mockResolvedValue({
+      canceled: false,
+      assets: [
+        {
+          uri: 'file:///private/mobile/参考图.png',
+          width: 120,
+          height: 80,
+          type: 'image',
+          fileName: '参考图.png',
+          fileSize: 10 * 1024 * 1024 + 1,
+          base64: 'aW1hZ2U=',
+          mimeType: 'image/png',
+        },
+      ],
+    });
+
+    const oversized = await send(request('file.importImage'));
+
+    expect(expectFailed(oversized).error.code).toBe('invalid_request');
+  });
 });

apps/mobile-shell/src/mobileHostBridge.ts

@@ -1,6 +1,7 @@
 import * as Clipboard from 'expo-clipboard';
 import { File, Paths } from 'expo-file-system';
 import * as Haptics from 'expo-haptics';
+import * as ImagePicker from 'expo-image-picker';
 import * as Linking from 'expo-linking';
 import * as Sharing from 'expo-sharing';
 import {
@@ -16,11 +17,13 @@ import {
   type FileExportImageResult,
   type FileExportTextPayload,
   type FileExportTextResult,
+  type FileImportImageResult,
   type HapticsImpactPayload,
   HOST_BRIDGE_PROTOCOL,
   HOST_BRIDGE_VERSION,
   type HostBridgeCapability,
   type HostBridgeError,
+  type HostBridgeImageMimeType,
   type HostBridgeMethod,
   type HostBridgeRequest,
   type HostBridgeResponse,
@@ -39,7 +42,8 @@ import { getMobileNetworkStatus } from './mobileShellNetwork';
 const WEB_APP_ORIGIN = 'https://app.genarrative.world';
 const EXPORT_TEXT_MAX_BYTES = 5 * 1024 * 1024;
 const EXPORT_IMAGE_MAX_BYTES = 5 * 1024 * 1024;
-const EXPORT_IMAGE_MIME_TYPES = new Set([
+const IMPORT_IMAGE_MAX_BYTES = 10 * 1024 * 1024;
+const HOST_BRIDGE_IMAGE_MIME_TYPES = new Set<HostBridgeImageMimeType>([
   'image/png',
   'image/jpeg',
   'image/webp',
@@ -60,6 +64,7 @@ export const MOBILE_HOST_CAPABILITIES: HostBridgeCapability[] = [
   'clipboard.writeText',
   'file.exportText',
   'file.exportImage',
+  'file.importImage',
   'haptics.impact',
 ];
 
@@ -251,7 +256,10 @@ async function exportTextFile(payload: unknown): Promise<FileExportTextResult> {
 async function exportImageFile(payload: unknown): Promise<FileExportImageResult> {
   const exportPayload = payload as FileExportImagePayload | undefined;
   const mimeType = exportPayload?.mimeType;
-  if (typeof mimeType !== 'string' || !EXPORT_IMAGE_MIME_TYPES.has(mimeType)) {
+  if (
+    typeof mimeType !== 'string' ||
+    !HOST_BRIDGE_IMAGE_MIME_TYPES.has(mimeType as HostBridgeImageMimeType)
+  ) {
     throw invalidRequest('mimeType must be an allowed image type');
   }
 
@@ -288,6 +296,90 @@ async function exportImageFile(payload: unknown): Promise<FileExportImageResult>
   };
 }
 
+function normalizeImportedImageMimeType(
+  value: unknown,
+): HostBridgeImageMimeType | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const mimeType = value.toLowerCase();
+  return HOST_BRIDGE_IMAGE_MIME_TYPES.has(mimeType as HostBridgeImageMimeType)
+    ? (mimeType as HostBridgeImageMimeType)
+    : null;
+}
+
+function fallbackImportedImageFileName(mimeType: HostBridgeImageMimeType) {
+  if (mimeType === 'image/jpeg') {
+    return 'genarrative-import.jpg';
+  }
+  if (mimeType === 'image/webp') {
+    return 'genarrative-import.webp';
+  }
+  return 'genarrative-import.png';
+}
+
+async function importImageFile(): Promise<FileImportImageResult> {
+  const permission = await ImagePicker.requestMediaLibraryPermissionsAsync();
+  if (permission.status !== ImagePicker.PermissionStatus.GRANTED) {
+    throw {
+      code: 'host_error',
+      message: 'photo library permission denied',
+    } satisfies HostBridgeError;
+  }
+
+  const result = await ImagePicker.launchImageLibraryAsync({
+    allowsEditing: false,
+    allowsMultipleSelection: false,
+    base64: true,
+    exif: false,
+    mediaTypes: ['images'],
+    quality: 1,
+  });
+  if (result.canceled) {
+    throw {
+      code: 'cancelled',
+      message: 'file import cancelled',
+    } satisfies HostBridgeError;
+  }
+
+  const asset = result.assets[0];
+  if (!asset || asset.type !== 'image') {
+    throw invalidRequest('image asset is required');
+  }
+
+  const mimeType = normalizeImportedImageMimeType(asset.mimeType);
+  if (!mimeType) {
+    throw invalidRequest('mimeType must be an allowed image type');
+  }
+
+  const base64Data = normalizedBase64Data(asset.base64);
+  if (!base64Data) {
+    throw invalidRequest('base64Data is required');
+  }
+
+  const bytes = base64DecodedByteLength(base64Data);
+  if (bytes <= 0 || bytes > IMPORT_IMAGE_MAX_BYTES) {
+    throw invalidRequest('image exceeds file import size limit');
+  }
+  if (
+    typeof asset.fileSize === 'number' &&
+    asset.fileSize > IMPORT_IMAGE_MAX_BYTES
+  ) {
+    throw invalidRequest('image exceeds file import size limit');
+  }
+
+  return {
+    action: 'selected',
+    fileName: normalizeHostBridgeExportFileName(
+      asset.fileName || fallbackImportedImageFileName(mimeType),
+    ),
+    base64Data,
+    mimeType,
+    bytes,
+  };
+}
+
 async function runHaptics(payload: unknown) {
   const style = (payload as HapticsImpactPayload | undefined)?.style;
   const impactStyle =
@@ -448,6 +540,8 @@ async function handleRequest(request: HostBridgeRequest) {
       return ok(request, await exportTextFile(request.payload));
     case 'file.exportImage':
       return ok(request, await exportImageFile(request.payload));
+    case 'file.importImage':
+      return ok(request, await importImageFile());
     case 'haptics.impact':
       return ok(request, await runHaptics(request.payload));
     case 'app.setBadgeCount':