接入原生壳分享卡图片导出

新增 file.exportImage 宿主能力契约

分享卡下载在原生壳中优先走宿主图片导出

Expo 壳写入缓存图片并调用系统分享保存

Tauri 壳通过保存对话框写入图片字节

补齐能力漂移检查、测试和架构文档

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

@@ -118,8 +118,10 @@ for (const dependency of ['expo-file-system', 'expo-sharing']) {
 
 for (const snippet of [
   'file.exportText',
+  'file.exportImage',
   'Sharing.shareAsync',
   'normalizeHostBridgeExportFileName',
+  'base64Data',
 ]) {
   if (!bridgeSource.includes(snippet)) {
     throw new Error(`mobile shell HostBridge missing ${snippet}`);
@@ -140,6 +142,7 @@ for (const capability of [
   'app.openExternalUrl',
   'clipboard.writeText',
   'file.exportText',
+  'file.exportImage',
   'haptics.impact',
 ]) {
   if (!mobileCapabilitySet.has(capability)) {

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

@@ -22,7 +22,12 @@ vi.mock('expo-clipboard', () => ({
 }));
 
 const writtenFiles = vi.hoisted(
-  () => [] as { uri: string; content: string }[],
+  () =>
+    [] as {
+      uri: string;
+      content: string;
+      options?: { encoding?: 'utf8' | 'base64' };
+    }[],
 );
 
 vi.mock('expo-file-system', () => ({
@@ -36,10 +41,11 @@ vi.mock('expo-file-system', () => ({
       this.uri = `file:///cache/${fileName}`;
     }
 
-    write(content: string) {
+    write(content: string, options?: { encoding?: 'utf8' | 'base64' }) {
       writtenFiles.push({
         uri: this.uri,
         content,
+        options,
       });
     }
   },
@@ -309,6 +315,7 @@ describe('handleMobileHostBridgeMessage', () => {
       {
         uri: 'file:///cache/作品-记录-.txt',
         content: '暖灯猫街',
+        options: undefined,
       },
     ]);
     expect(Sharing.shareAsync).toHaveBeenCalledWith(
@@ -352,4 +359,61 @@ describe('handleMobileHostBridgeMessage', () => {
     expect(writtenFiles).toEqual([]);
     expect(Sharing.shareAsync).not.toHaveBeenCalled();
   });
+
+  test('file.exportImage 写入缓存图片并调起系统分享', async () => {
+    const response = await send(
+      request('file.exportImage', {
+        fileName: ' ../分享:卡?.png ',
+        base64Data: 'c2hhcmUtY2FyZA==',
+        mimeType: 'image/png',
+      }),
+    );
+
+    const okResponse = expectOk(response);
+
+    expect(okResponse.result).toEqual({
+      action: 'saved',
+      fileName: '分享-卡-.png',
+      bytes: 10,
+    });
+    expect(writtenFiles).toEqual([
+      {
+        uri: 'file:///cache/分享-卡-.png',
+        content: 'c2hhcmUtY2FyZA==',
+        options: { encoding: 'base64' },
+      },
+    ]);
+    expect(Sharing.shareAsync).toHaveBeenCalledWith(
+      'file:///cache/分享-卡-.png',
+      {
+        mimeType: 'image/png',
+        UTI: 'public.png',
+        dialogTitle: '分享-卡-.png',
+      },
+    );
+  });
+
+  test('file.exportImage 拒绝非图片 MIME 与超限内容', async () => {
+    const unsupportedMime = await send(
+      request('file.exportImage', {
+        fileName: '分享卡.txt',
+        base64Data: 'c2hhcmUtY2FyZA==',
+        mimeType: 'text/plain',
+      }),
+    );
+
+    expect(expectFailed(unsupportedMime).error.code).toBe('invalid_request');
+
+    const oversized = await send(
+      request('file.exportImage', {
+        fileName: '分享卡.png',
+        base64Data: `${'A'.repeat(7 * 1024 * 1024)}`,
+        mimeType: 'image/png',
+      }),
+    );
+
+    expect(expectFailed(oversized).error.code).toBe('invalid_request');
+    expect(writtenFiles).toEqual([]);
+    expect(Sharing.shareAsync).not.toHaveBeenCalled();
+  });
 });

apps/mobile-shell/src/mobileHostBridge.ts

@@ -7,6 +7,8 @@ import { Platform, Share } from 'react-native';
 
 import {
   type ClipboardWriteTextPayload,
+  type FileExportImagePayload,
+  type FileExportImageResult,
   type FileExportTextPayload,
   type FileExportTextResult,
   type HapticsImpactPayload,
@@ -27,6 +29,12 @@ import { resolveMobileShellWebViewUrl } from './mobileShellNavigation';
 
 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([
+  'image/png',
+  'image/jpeg',
+  'image/webp',
+]);
 
 export const MOBILE_HOST_CAPABILITIES: HostBridgeCapability[] = [
   'host.getRuntime',
@@ -38,6 +46,7 @@ export const MOBILE_HOST_CAPABILITIES: HostBridgeCapability[] = [
   'app.openExternalUrl',
   'clipboard.writeText',
   'file.exportText',
+  'file.exportImage',
   'haptics.impact',
 ];
 
@@ -86,6 +95,28 @@ function utf8ByteLength(value: string) {
   return bytes;
 }
 
+function normalizedBase64Data(value: unknown) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const normalizedValue = value.trim();
+  if (
+    !normalizedValue ||
+    normalizedValue.length % 4 !== 0 ||
+    !/^[A-Za-z0-9+/]+={0,2}$/u.test(normalizedValue)
+  ) {
+    return null;
+  }
+
+  return normalizedValue;
+}
+
+function base64DecodedByteLength(value: string) {
+  const padding = value.endsWith('==') ? 2 : value.endsWith('=') ? 1 : 0;
+  return Math.floor((value.length * 3) / 4) - padding;
+}
+
 function isHostBridgeRequest(value: unknown): value is HostBridgeRequest {
   if (!value || typeof value !== 'object') {
     return false;
@@ -193,6 +224,46 @@ 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)) {
+    throw invalidRequest('mimeType must be an allowed image type');
+  }
+
+  const base64Data = normalizedBase64Data(exportPayload?.base64Data);
+  if (!base64Data) {
+    throw invalidRequest('base64Data is required');
+  }
+  const bytes = base64DecodedByteLength(base64Data);
+  if (bytes > EXPORT_IMAGE_MAX_BYTES) {
+    throw invalidRequest('image exceeds file export size limit');
+  }
+
+  const isSharingAvailable = await Sharing.isAvailableAsync();
+  if (!isSharingAvailable) {
+    throw {
+      code: 'unsupported_capability',
+      message: 'file sharing is unavailable in mobile shell',
+    } satisfies HostBridgeError;
+  }
+
+  const fileName = normalizeHostBridgeExportFileName(exportPayload?.fileName);
+  const file = new File(Paths.cache, fileName);
+  file.write(base64Data, { encoding: 'base64' });
+  await Sharing.shareAsync(file.uri, {
+    mimeType,
+    UTI: mimeType === 'image/png' ? 'public.png' : 'public.image',
+    dialogTitle: fileName,
+  });
+
+  return {
+    action: 'saved',
+    fileName,
+    bytes,
+  };
+}
+
 async function runHaptics(payload: unknown) {
   const style = (payload as HapticsImpactPayload | undefined)?.style;
   const impactStyle =
@@ -322,6 +393,8 @@ async function handleRequest(request: HostBridgeRequest) {
       return ok(request, await writeClipboard(request.payload));
     case 'file.exportText':
       return ok(request, await exportTextFile(request.payload));
+    case 'file.exportImage':
+      return ok(request, await exportImageFile(request.payload));
     case 'haptics.impact':
       return ok(request, await runHaptics(request.payload));
     case 'share.open':