GenarrativeAI/Genarrative
11
0
Fork 0
Code Issues 21 Pull Requests 4 Actions Packages Projects 3 Releases Wiki Activity

接入移动壳图片导入能力

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

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

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

更新移动壳依赖、配置校验、测试和架构文档
This commit is contained in:
段舒康
2026-06-18 03:04:21 +08:00
parent 199f02cf9f
commit 14f838c414
12 changed files with 348 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/mobile-shell/app.json
+10
View File
@@ -10,6 +10,16 @@
"assetBundlePatterns": [
"**/*"
],
"plugins": [
[
"expo-image-picker",
{
"photosPermission": "允许 Genarrative 读取你选择的图片，用于导入创作素材和参考图。",
"cameraPermission": false,
"microphonePermission": false
}
]
],
"ios": {
"supportsTablet": true,
"associatedDomains": [
apps/mobile-shell/package.json
+1
View File
@@ -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
+30 -1
View File
@@ -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
+138
View File
@@ -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
+96 -2
View File
@@ -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':
docs/project-memory/shared-memory/decision-log.md
+1
View File
@@ -33,6 +33,7 @@
- 2026-06-18 原生壳生命周期事件：新增 `app.lifecycle` HostBridge capability，Expo 壳通过 React Native `AppState` 派发 `active` / `inactive` / `background`，Tauri 壳通过主窗口 focus / blur 派发 `active` / `inactive`；H5 只通过 `subscribeHostAppLifecycle()` 订阅统一状态，后续游戏循环、音频和轮询暂停 / 恢复不得直接依赖 Expo / Tauri 平台细节。
- 2026-06-18 原生壳网络状态：新增 `network.status` 与 `network.statusChanged` HostBridge capability，Expo 壳通过 `expo-network` 查询和订阅真实系统网络状态，Tauri 壳通过短超时连接 `app.genarrative.world:443` 查询主站可达性，并通过 WebView `online` / `offline` 注入变化事件；H5 统一使用 `getHostNetworkStatus()` / `subscribeHostNetworkStatusChange()`，不得直接读取 Expo / Tauri 私有网络 API。
- 2026-06-18 桌面图片导入：新增 `file.importImage` 与 `file.imageDropped` HostBridge capability，Tauri 壳通过系统文件选择框和主窗口拖拽事件读取用户选择 / 拖入的真实图片，只允许 `image/png`、`image/jpeg`、`image/webp` 且单次不超过 10 MiB；H5 统一使用 `importHostImageFile()` / `subscribeHostImageDrop()`，宿主只回传文件名、MIME、base64 内容、字节数和可选坐标，不暴露本地绝对路径，也不开放通用文件系统。
- 2026-06-18 移动图片导入：Expo 壳开始声明并实现 `file.importImage`，通过 `expo-image-picker` 请求相册权限并打开系统相册选择器，只允许 `image/png`、`image/jpeg`、`image/webp` 且单次不超过 10 MiB；成功只回传清洗后的文件名、MIME、base64 内容和字节数，不暴露设备本地 URI，不请求相机或麦克风权限，用户取消返回 `cancelled` 并由 H5 facade 归为 `false`。
- 影响范围：`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`。
docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md
+2 -2
View File
File diff suppressed because one or more lines are too long
docs/【前端架构】宿主壳能力统一协议-2026-06-17.md
+1 -1
View File
@@ -56,7 +56,7 @@ AI H5 sandbox
- `navigateHostNativePage()`：受控跳转宿主页，供订阅授权、支付、登录等 adapter 复用。Expo 移动壳首版只接受同源 H5 route 并切换 WebView URL；Tauri 桌面壳同样只接受 `https://app.genarrative.world` 同源 H5 route 并在主窗口内跳转。真正原生页面、登录和支付能力必须等对应 SDK / 页面接入后再声明支持。
- `exportHostTextFile()`：原生 App 宿主的受控文本导出入口。Expo 移动壳通过 `file.exportText` 写入缓存文本文件并交给系统分享 / 保存面板；Tauri 桌面壳通过 `file.exportText` 打开系统保存对话框并写入用户选择的文件。文件名必须清洗，单次文本不超过 5 MiB，成功只返回文件名和字节数，不把本机绝对路径暴露给 H5；系统分享不可用或用户取消时返回明确错误，由 H5 fallback 承接。
- `exportHostImageFile()`：原生 App 宿主的受控图片导出入口。H5 只传自己生成的图片 `base64Data`、清洗后的文件名和允许的 `image/png` / `image/jpeg` / `image/webp` MIME；Expo 移动壳写入缓存图片后交给系统分享 / 保存面板，Tauri 桌面壳打开系统保存对话框并写入图片字节。单次图片不超过 5 MiB，成功只返回文件名和字节数，不回传本机绝对路径。当前分享卡下载在 native app 中优先走 `file.exportImage`，宿主未声明时保留浏览器下载路径。
- `importHostImageFile()` / `subscribeHostImageDrop()`：桌面 App 宿主的受控图片导入入口。Tauri 壳通过系统文件选择框或主窗口拖拽事件读取用户选择 / 拖入的图片，只接受 `image/png`、`image/jpeg`、`image/webp`，单次不超过 10 MiB，成功只返回文件名、MIME、base64 内容、字节数和可选拖入坐标，不把本机绝对路径暴露给 H5，也不开放通用文件系统能力；Expo 移动壳未接入真实图片选择器前不声明该能力。
- `importHostImageFile()` / `subscribeHostImageDrop()`：原生 App 宿主的受控图片导入入口。Expo 移动壳通过 Expo ImagePicker 请求相册权限并打开系统相册选择器，Tauri 壳通过系统文件选择框或主窗口拖拽事件读取用户选择 / 拖入的图片；两端都只接受 `image/png`、`image/jpeg`、`image/webp`，单次不超过 10 MiB，成功只返回文件名、MIME、base64 内容、字节数和可选拖入坐标，不暴露设备本地 URI 或本机绝对路径，也不开放通用文件系统能力。
## 迁移顺序
package-lock.json
Generated
+36
View File
@@ -19,6 +19,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",
@@ -6388,6 +6389,27 @@
"expo": "*"
}
},
"node_modules/expo-image-loader": {
"version": "56.0.3",
"resolved": "https://registry.npmjs.org/expo-image-loader/-/expo-image-loader-56.0.3.tgz",
"integrity": "sha512-JgUo4fUeU1ZC+z8iBFj8v7yoGQnZrLbOVPyNE+DWVrld55F2F6R1ck+rmdm/8TNWLz1LhNQfD7c3XYP1ZikxXA==",
"license": "MIT",
"peerDependencies": {
"expo": "*"
}
},
"node_modules/expo-image-picker": {
"version": "56.0.18",
"resolved": "https://registry.npmjs.org/expo-image-picker/-/expo-image-picker-56.0.18.tgz",
"integrity": "sha512-sCjQ8M27bhGUv2vUavIE+uWdYo79b2D7Q5h9B66BSDZ+Rd8YyLVSf7vYGfIzQ7nMVoENZ6c4xo/JiDkEeQ9iTg==",
"license": "MIT",
"dependencies": {
"expo-image-loader": "~56.0.3"
},
"peerDependencies": {
"expo": "*"
}
},
"node_modules/expo-keep-awake": {
"version": "56.0.3",
"resolved": "https://registry.npmjs.org/expo-keep-awake/-/expo-keep-awake-56.0.3.tgz",
@@ -17292,6 +17314,20 @@
"integrity": "sha512-ycoahZJnR9tWAVh/0mJYxbETtHRYaWjiWS8cHlP6aDGU6Q6Y8rZ5NKsuBwWw6HR2Pe30mfVFgbF2HrBR6gtYmw==",
"requires": {}
},
"expo-image-loader": {
"version": "56.0.3",
"resolved": "https://registry.npmjs.org/expo-image-loader/-/expo-image-loader-56.0.3.tgz",
"integrity": "sha512-JgUo4fUeU1ZC+z8iBFj8v7yoGQnZrLbOVPyNE+DWVrld55F2F6R1ck+rmdm/8TNWLz1LhNQfD7c3XYP1ZikxXA==",
"requires": {}
},
"expo-image-picker": {
"version": "56.0.18",
"resolved": "https://registry.npmjs.org/expo-image-picker/-/expo-image-picker-56.0.18.tgz",
"integrity": "sha512-sCjQ8M27bhGUv2vUavIE+uWdYo79b2D7Q5h9B66BSDZ+Rd8YyLVSf7vYGfIzQ7nMVoENZ6c4xo/JiDkEeQ9iTg==",
"requires": {
"expo-image-loader": "~56.0.3"
}
},
"expo-keep-awake": {
"version": "56.0.3",
"resolved": "https://registry.npmjs.org/expo-keep-awake/-/expo-keep-awake-56.0.3.tgz",
package.json
+1
View File
@@ -89,6 +89,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",
src/services/host-bridge/hostBridge.test.ts
+30
View File
@@ -1089,4 +1089,34 @@ describe('hostBridge', () => {
}),
});
});
test('原生 App 宿主取消导入图片时回退为 false', async () => {
const invoke = vi.fn(
async (_command: string, args?: Record<string, unknown>) => {
const request = (args as { request: { id: string } }).request;
return {
bridge: 'GenarrativeHostBridge',
version: 1,
id: request.id,
ok: false,
error: {
code: 'cancelled',
message: 'file import cancelled',
},
};
},
);
window.history.replaceState(
null,
'',
nativeAppPath(['file.importImage']),
);
window.__TAURI__ = {
core: {
invoke: asTauriInvoke(invoke),
},
};
await expect(importHostImageFile()).resolves.toBe(false);
});
});
src/services/host-bridge/hostBridge.ts
+2 -1
View File
@@ -125,7 +125,8 @@ function isUnsupportedHostBridgeError(error: unknown) {
return (
error instanceof Error &&
(error.name === 'unsupported_method' ||
error.name === 'unsupported_capability')
error.name === 'unsupported_capability' ||
error.name === 'cancelled')
);
}