GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

接入原生壳音频文件导出能力

Browse Source 
新增 file.exportAudio HostBridge 契约和 H5 facade

移动端通过 Expo 缓存文件与系统分享导出受控音频

桌面端通过 Tauri 保存对话框写入受控音频字节

通用音频输入面板仅对本地音频资产展示宿主导出入口

更新壳能力检查、测试、方案文档和共享决策记录
This commit is contained in:
kdletters
2026-06-18 05:42:16 +08:00
parent 3be997e286
commit b3278739a5
15 changed files with 734 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
apps/desktop-shell/scripts/check-config.mjs
View File

@@ -150,6 +150,7 @@ const requiredMainSnippets = [
'"file.exportImage"',
'"file.importImage"',
'"file.importAudio"',
'"file.exportAudio"',
'"file.imageDropped"',
'"notification.showLocal"',
'tauri_plugin_dialog::init()',
@@ -163,6 +164,7 @@ const requiredMainSnippets = [
'import_text_file_payload',
'import_image_file_payload',
'import_audio_file_payload',
'export_audio_payload',
'set_title',
'set_badge_count',
'window.reload()',

191
apps/desktop-shell/src-tauri/src/main.rs
View File

@@ -23,6 +23,7 @@ const WEB_APP_ORIGIN: &str = "https://app.genarrative.world";
const EXTERNAL_URL_PROTOCOLS: [&str; 4] = ["http:", "https:", "mailto:", "tel:"];
const EXPORT_TEXT_MAX_BYTES: usize = 5 * 1024 * 1024;
const EXPORT_IMAGE_MAX_BYTES: usize = 5 * 1024 * 1024;
const EXPORT_AUDIO_MAX_BYTES: usize = 20 * 1024 * 1024;
const IMPORT_TEXT_MAX_BYTES: u64 = 5 * 1024 * 1024;
const IMPORT_IMAGE_MAX_BYTES: u64 = 10 * 1024 * 1024;
const IMPORT_AUDIO_MAX_BYTES: u64 = 20 * 1024 * 1024;
@@ -111,6 +112,7 @@ fn capabilities() -> Vec<&'static str> {
"file.exportImage",
"file.importImage",
"file.importAudio",
"file.exportAudio",
"file.imageDropped",
"notification.showLocal",
]
@@ -475,6 +477,17 @@ fn import_audio_mime_type(path: &Path) -> Option<&'static str> {
}
}
fn export_audio_extension(mime_type: &str) -> Option<&'static str> {
match mime_type {
"audio/mpeg" => Some("mp3"),
"audio/mp4" => Some("m4a"),
"audio/wav" => Some("wav"),
"audio/ogg" => Some("ogg"),
"audio/webm" => Some("webm"),
_ => None,
}
}
fn normalize_export_image_file_name(raw_file_name: &str, mime_type: &str) -> String {
let mut file_name = normalize_export_file_name(raw_file_name);
let extension = export_image_extension(mime_type).unwrap_or("png");
@@ -488,6 +501,19 @@ fn normalize_export_image_file_name(raw_file_name: &str, mime_type: &str) -> Str
file_name
}
fn normalize_export_audio_file_name(raw_file_name: &str, mime_type: &str) -> String {
let mut file_name = normalize_export_file_name(raw_file_name);
let extension = export_audio_extension(mime_type).unwrap_or("webm");
if !file_name
.to_ascii_lowercase()
.ends_with(&format!(".{}", extension))
{
file_name.push('.');
file_name.push_str(extension);
}
file_name
}
fn export_image_payload(
request: &HostBridgeRequest,
) -> Result<(String, Vec<u8>), HostBridgeResponse> {
@@ -552,6 +578,70 @@ fn export_image_payload(
Ok((file_name, bytes))
}
fn export_audio_payload(
request: &HostBridgeRequest,
) -> Result<(String, Vec<u8>), HostBridgeResponse> {
let payload = request.payload.as_ref().ok_or_else(|| {
failed(
request.id.clone(),
"invalid_request",
"fileName, mimeType and base64Data are required",
)
})?;
let mime_type = payload
.get("mimeType")
.and_then(Value::as_str)
.ok_or_else(|| {
failed(
request.id.clone(),
"invalid_request",
"mimeType is required",
)
})?;
if export_audio_extension(mime_type).is_none() {
return Err(failed(
request.id.clone(),
"invalid_request",
"mimeType must be an allowed audio type",
));
}
let base64_data = payload
.get("base64Data")
.and_then(Value::as_str)
.map(str::trim)
.filter(|value| !value.is_empty())
.ok_or_else(|| {
failed(
request.id.clone(),
"invalid_request",
"base64Data is required",
)
})?;
let bytes = BASE64_STANDARD.decode(base64_data).map_err(|_| {
failed(
request.id.clone(),
"invalid_request",
"base64Data is invalid",
)
})?;
if bytes.is_empty() || bytes.len() > EXPORT_AUDIO_MAX_BYTES {
return Err(failed(
request.id.clone(),
"invalid_request",
"audio exceeds file export size limit",
));
}
let file_name = payload
.get("fileName")
.and_then(Value::as_str)
.map(|file_name| normalize_export_audio_file_name(file_name, mime_type))
.unwrap_or_else(|| normalize_export_audio_file_name("genarrative-audio", mime_type));
Ok((file_name, bytes))
}
fn write_export_bytes_file(path: PathBuf, bytes: Vec<u8>) -> Result<usize, String> {
let byte_count = bytes.len();
fs::write(path, bytes).map_err(|error| error.to_string())?;
@@ -1120,6 +1210,41 @@ async fn host_bridge_request(
Err(error) => failed(request.id, "host_error", error.to_string()),
}
}
"file.exportAudio" => {
let (file_name, bytes) = match export_audio_payload(&request) {
Ok(payload) => payload,
Err(response) => return response,
};
let file_path = app
.dialog()
.file()
.add_filter("Audio", &["mp3", "m4a", "wav", "ogg", "webm"])
.set_file_name(file_name.clone())
.blocking_save_file();
let Some(file_path) = file_path else {
return failed(request.id, "cancelled", "file export cancelled");
};
let path = match file_path.into_path() {
Ok(path) => path,
Err(error) => return failed(request.id, "host_error", error.to_string()),
};
let export_result =
tauri::async_runtime::spawn_blocking(move || write_export_bytes_file(path, bytes))
.await;
let byte_count = match export_result {
Ok(Ok(byte_count)) => byte_count,
Ok(Err(error)) => return failed(request.id, "host_error", error),
Err(error) => return failed(request.id, "host_error", error.to_string()),
};
ok(
request.id,
json!({
"action": "saved",
"fileName": file_name,
"bytes": byte_count,
}),
)
}
"app.setTitle" => {
let title = match required_string_payload(&request, "title")
.ok()
@@ -1325,6 +1450,10 @@ mod tests {
.as_array()
.unwrap()
.contains(&json!("file.importAudio")));
assert!(result["capabilities"]
.as_array()
.unwrap()
.contains(&json!("file.exportAudio")));
assert!(result["capabilities"]
.as_array()
.unwrap()
@@ -1797,6 +1926,68 @@ mod tests {
fs::remove_file(large_path).expect("remove large audio");
}
#[test]
fn export_audio_payload_decodes_allowed_audio_base64() {
let mut valid = request("file.exportAudio");
valid.payload = Some(json!({
"fileName": "敲击:音效?.wav",
"base64Data": "YXVkaW8=",
"mimeType": "audio/wav"
}));
let (file_name, bytes) = export_audio_payload(&valid).expect("audio payload");
assert_eq!(file_name, "敲击-音效-.wav");
assert_eq!(bytes, b"audio");
let mut missing_extension = request("file.exportAudio");
missing_extension.payload = Some(json!({
"fileName": "敲击音效",
"base64Data": "YXVkaW8=",
"mimeType": "audio/webm"
}));
let (file_name, _bytes) =
export_audio_payload(&missing_extension).expect("audio payload");
assert_eq!(file_name, "敲击音效.webm");
}
#[test]
fn export_audio_payload_rejects_invalid_or_oversized_audio() {
let mut invalid_mime = request("file.exportAudio");
invalid_mime.payload = Some(json!({
"fileName": "hit.txt",
"base64Data": "YXVkaW8=",
"mimeType": "text/plain"
}));
let response = export_audio_payload(&invalid_mime).expect_err("invalid mime");
assert!(!response.ok);
assert_eq!(response.error.expect("error").code, "invalid_request");
let mut empty = request("file.exportAudio");
empty.payload = Some(json!({
"fileName": "hit.wav",
"base64Data": "",
"mimeType": "audio/wav"
}));
let response = export_audio_payload(&empty).expect_err("empty audio");
assert!(!response.ok);
assert_eq!(response.error.expect("error").code, "invalid_request");
let mut oversized = request("file.exportAudio");
oversized.payload = Some(json!({
"fileName": "hit.webm",
"base64Data": BASE64_STANDARD.encode(vec![1u8; EXPORT_AUDIO_MAX_BYTES + 1]),
"mimeType": "audio/webm"
}));
let response = export_audio_payload(&oversized).expect_err("oversized audio");
assert!(!response.ok);
let error = response.error.expect("error");
assert_eq!(error.code, "invalid_request");
assert_eq!(error.message, "audio exceeds file export size limit");
}
#[test]
fn export_image_payload_rejects_invalid_mime_and_base64() {
let mut invalid_mime = request("file.exportImage");

4
apps/desktop-shell/src-tauri/tauri.conf.json
View File

@@ -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,appearance.getColorScheme,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.reloadWebView,app.openExternalUrl,app.setTitle,app.setBadgeCount,network.status,network.statusChanged,clipboard.writeText,clipboard.readText,file.exportText,file.importText,file.exportImage,file.importImage,file.importAudio,file.imageDropped,notification.showLocal",
"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,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.reloadWebView,app.openExternalUrl,app.setTitle,app.setBadgeCount,network.status,network.statusChanged,clipboard.writeText,clipboard.readText,file.exportText,file.importText,file.exportImage,file.importImage,file.importAudio,file.exportAudio,file.imageDropped,notification.showLocal",
"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,appearance.getColorScheme,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.reloadWebView,app.openExternalUrl,app.setTitle,app.setBadgeCount,network.status,network.statusChanged,clipboard.writeText,clipboard.readText,file.exportText,file.importText,file.exportImage,file.importImage,file.importAudio,file.imageDropped,notification.showLocal",
"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,app.lifecycle,share.open,share.setTarget,navigation.openNativePage,app.reloadWebView,app.openExternalUrl,app.setTitle,app.setBadgeCount,network.status,network.statusChanged,clipboard.writeText,clipboard.readText,file.exportText,file.importText,file.exportImage,file.importImage,file.importAudio,file.exportAudio,file.imageDropped,notification.showLocal",
"title": "Genarrative",
"width": 1280,
"height": 820,

2
apps/mobile-shell/scripts/check-config.mjs
View File

@@ -183,6 +183,7 @@ for (const snippet of [
'file.exportImage',
'file.importImage',
'file.importAudio',
'file.exportAudio',
'clipboard.readText',
'notification.showLocal',
'network.status',
@@ -236,6 +237,7 @@ for (const capability of [
'file.exportImage',
'file.importImage',
'file.importAudio',
'file.exportAudio',
'haptics.impact',
'notification.showLocal',
]) {

82
apps/mobile-shell/src/mobileHostBridge.test.ts
View File

@@ -851,6 +851,88 @@ describe('handleMobileHostBridgeMessage', () => {
expect(Sharing.shareAsync).not.toHaveBeenCalled();
});
test('file.exportAudio 写入缓存音频并调起系统分享', async () => {
const response = await send(
request('file.exportAudio', {
fileName: ' ../敲击:音效?.wav ',
base64Data: 'YXVkaW8=',
mimeType: 'audio/wav',
}),
);
const okResponse = expectOk(response);
expect(okResponse.result).toEqual({
action: 'saved',
fileName: '敲击-音效-.wav',
bytes: 5,
});
expect(writtenFiles).toEqual([
{
uri: 'file:///cache/敲击-音效-.wav',
content: 'YXVkaW8=',
options: { encoding: 'base64' },
},
]);
expect(Sharing.shareAsync).toHaveBeenCalledWith(
'file:///cache/敲击-音效-.wav',
{
mimeType: 'audio/wav',
UTI: 'public.audio',
dialogTitle: '敲击-音效-.wav',
},
);
});
test('file.exportAudio 在系统分享不可用时明确返回 unsupported capability', async () => {
vi.mocked(Sharing.isAvailableAsync).mockResolvedValue(false);
const response = await send(
request('file.exportAudio', {
fileName: 'hit.wav',
base64Data: 'YXVkaW8=',
mimeType: 'audio/wav',
}),
);
const failedResponse = expectFailed(response);
expect(failedResponse.error.code).toBe('unsupported_capability');
expect(writtenFiles).toEqual([]);
expect(Sharing.shareAsync).not.toHaveBeenCalled();
});
test('file.exportAudio 拒绝非法 MIME、空内容与超限内容', async () => {
const unsupportedMime = await send(
request('file.exportAudio', {
fileName: 'hit.txt',
base64Data: 'YXVkaW8=',
mimeType: 'text/plain',
}),
);
expect(expectFailed(unsupportedMime).error.code).toBe('invalid_request');
const emptyAudio = await send(
request('file.exportAudio', {
fileName: 'hit.wav',
base64Data: '',
mimeType: 'audio/wav',
}),
);
expect(expectFailed(emptyAudio).error.code).toBe('invalid_request');
const oversized = await send(
request('file.exportAudio', {
fileName: 'hit.webm',
base64Data: 'A'.repeat(28 * 1024 * 1024),
mimeType: 'audio/webm',
}),
);
expect(expectFailed(oversized).error.code).toBe('invalid_request');
expect(writtenFiles).toEqual([]);
expect(Sharing.shareAsync).not.toHaveBeenCalled();
});
test('file.importImage 调起系统相册并返回受控图片数据', async () => {
vi.mocked(ImagePicker.launchImageLibraryAsync).mockResolvedValue({
canceled: false,

81
apps/mobile-shell/src/mobileHostBridge.ts
View File

@@ -16,6 +16,8 @@ import {
import {
type ClipboardReadTextResult,
type ClipboardWriteTextPayload,
type FileExportAudioPayload,
type FileExportAudioResult,
type FileExportImagePayload,
type FileExportImageResult,
type FileExportTextPayload,
@@ -51,6 +53,7 @@ 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_AUDIO_MAX_BYTES = 20 * 1024 * 1024;
const IMPORT_TEXT_MAX_BYTES = 5 * 1024 * 1024;
const IMPORT_IMAGE_MAX_BYTES = 10 * 1024 * 1024;
const IMPORT_AUDIO_MAX_BYTES = 20 * 1024 * 1024;
@@ -103,6 +106,7 @@ export const MOBILE_HOST_CAPABILITIES: HostBridgeCapability[] = [
'file.exportImage',
'file.importImage',
'file.importAudio',
'file.exportAudio',
'haptics.impact',
'notification.showLocal',
];
@@ -449,6 +453,33 @@ function fallbackImportedImageFileName(mimeType: HostBridgeImageMimeType) {
return 'genarrative-import.png';
}
function audioFileExtension(mimeType: HostBridgeAudioMimeType) {
if (mimeType === 'audio/mpeg') {
return 'mp3';
}
if (mimeType === 'audio/mp4') {
return 'm4a';
}
if (mimeType === 'audio/wav') {
return 'wav';
}
if (mimeType === 'audio/ogg') {
return 'ogg';
}
return 'webm';
}
function normalizeExportedAudioFileName(
rawFileName: unknown,
mimeType: HostBridgeAudioMimeType,
) {
const fileName = normalizeHostBridgeExportFileName(rawFileName);
const extension = audioFileExtension(mimeType);
return fileName.toLowerCase().endsWith(`.${extension}`)
? fileName
: `${fileName}.${extension}`;
}
function normalizeImportedAudioMimeType(
value: unknown,
fileName: string,
@@ -480,6 +511,54 @@ function normalizeImportedAudioMimeType(
return null;
}
async function exportAudioFile(
payload: unknown,
): Promise<FileExportAudioResult> {
const exportPayload = payload as FileExportAudioPayload | undefined;
const mimeType = exportPayload?.mimeType;
if (
typeof mimeType !== 'string' ||
!HOST_BRIDGE_AUDIO_MIME_TYPES.has(mimeType as HostBridgeAudioMimeType)
) {
throw invalidRequest('mimeType must be an allowed audio type');
}
const base64Data = normalizedBase64Data(exportPayload?.base64Data);
if (!base64Data) {
throw invalidRequest('base64Data is required');
}
const bytes = base64DecodedByteLength(base64Data);
if (bytes <= 0 || bytes > EXPORT_AUDIO_MAX_BYTES) {
throw invalidRequest('audio 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 = normalizeExportedAudioFileName(
exportPayload?.fileName,
mimeType as HostBridgeAudioMimeType,
);
const file = new File(Paths.cache, fileName);
file.write(base64Data, { encoding: 'base64' });
await Sharing.shareAsync(file.uri, {
mimeType,
UTI: 'public.audio',
dialogTitle: fileName,
});
return {
action: 'saved',
fileName,
bytes,
};
}
async function importImageFile(): Promise<FileImportImageResult> {
const permission = await ImagePicker.requestMediaLibraryPermissionsAsync();
if (permission.status !== ImagePicker.PermissionStatus.GRANTED) {
@@ -831,6 +910,8 @@ async function handleRequest(request: HostBridgeRequest) {
return ok(request, await importImageFile());
case 'file.importAudio':
return ok(request, await importAudioFile());
case 'file.exportAudio':
return ok(request, await exportAudioFile(request.payload));
case 'haptics.impact':
return ok(request, await runHaptics(request.payload));
case 'notification.showLocal':