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

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

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

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

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

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

更新壳能力检查、测试、方案文档和共享决策记录
This commit is contained in:
段舒康
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
apps/desktop-shell/scripts/check-config.mjs
+2
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()',
apps/desktop-shell/src-tauri/src/main.rs
+191
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");
apps/desktop-shell/src-tauri/tauri.conf.json
+2 -2
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,
apps/mobile-shell/scripts/check-config.mjs
+2
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',
]) {
apps/mobile-shell/src/mobileHostBridge.test.ts
+82
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,
apps/mobile-shell/src/mobileHostBridge.ts
+81
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':
docs/project-memory/shared-memory/decision-log.md
+7
View File
@@ -2297,3 +2297,10 @@
- 决策：新增 HostBridge method `file.importAudio`、H5 facade `importHostAudioFile()` 和通用音频输入面板接入。移动端通过 Expo DocumentPicker，桌面端通过 Tauri 系统文件选择框；两端只接受 `audio/mpeg`、`audio/mp4`、`audio/wav`、`audio/ogg`、`audio/webm` 或对应扩展名，单次不超过 20 MiB。宿主成功时只返回清洗后的文件名、MIME、base64 内容和字节数，不返回设备 URI 或本机绝对路径，也不开放通用文件系统。H5 将宿主结果转换成现有浏览器 `File`，继续复用 `readFileAsAsset(file, 'uploaded')` 音频处理链路。
- 影响范围：`packages/shared/src/contracts/hostBridge.ts`、`src/services/host-bridge/hostBridge.ts`、`src/components/common/CreativeAudioInputPanel.tsx`、`apps/mobile-shell/`、`apps/desktop-shell/`、原生壳能力检查脚本和 HostBridge 架构文档。
- 验证方式：`npm run check:native-shells`、`npm run test -- src/components/common/CreativeAudioInputPanel.test.tsx`、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
## 2026-06-18 原生壳音频导出只写入 H5 已持有字节
- 背景：木鱼创作的本地录音 / 上传音频会在浏览器侧处理成 `Blob`，原生壳需要能把这份本地处理结果交给系统保存 / 分享；但宿主不能替 H5 读取任意本地音频文件，也不能把文件系统能力扩成通用读写。
- 决策：新增 HostBridge method `file.exportAudio`、H5 facade `exportHostAudioFile()` 和通用音频输入面板导出入口。H5 只传当前页面已持有的 `base64Data`、清洗后的文件名和允许的 `audio/mpeg`、`audio/mp4`、`audio/wav`、`audio/ogg`、`audio/webm` MIME；移动端写入 Expo 缓存音频后交给系统分享 / 保存面板，桌面端打开 Tauri 系统保存对话框并写入音频字节。单次不超过 20 MiB，成功只返回文件名和字节数。`CreativeAudioInputPanel` 只在当前资产包含本地 `Blob`、`fileName`、允许 MIME 且宿主声明 `file.exportAudio` 时显示导出入口；远端已上传音频不展示导出。
- 影响范围：`packages/shared/src/contracts/hostBridge.ts`、`src/services/host-bridge/hostBridge.ts`、`src/components/common/CreativeAudioInputPanel.tsx`、`apps/mobile-shell/`、`apps/desktop-shell/`、原生壳能力检查脚本和 HostBridge 架构文档。
- 验证方式：`npm run check:native-shells`、`npm run test -- src/components/common/CreativeAudioInputPanel.test.tsx`、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
docs/【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md
+3 -2
View File
File diff suppressed because one or more lines are too long
docs/【前端架构】宿主壳能力统一协议-2026-06-17.md
+1
View File
@@ -62,6 +62,7 @@ AI H5 sandbox
- `exportHostImageFile()`：原生 App 宿主的受控图片导出入口。H5 只传自己生成的图片 `base64Data`、清洗后的文件名和允许的 `image/png` / `image/jpeg` / `image/webp` MIME；Expo 移动壳写入缓存图片后交给系统分享 / 保存面板，Tauri 桌面壳打开系统保存对话框并写入图片字节。单次图片不超过 5 MiB，成功只返回文件名和字节数，不回传本机绝对路径。当前分享卡下载在 native app 中优先走 `file.exportImage`，宿主未声明时保留浏览器下载路径。
- `importHostImageFile()` / `subscribeHostImageDrop()`：原生 App 宿主的受控图片导入入口。Expo 移动壳通过 Expo ImagePicker 请求相册权限并打开系统相册选择器，Tauri 壳通过系统文件选择框或主窗口拖拽事件读取用户选择 / 拖入的图片；两端都只接受 `image/png`、`image/jpeg`、`image/webp`，单次不超过 10 MiB，成功只返回文件名、MIME、base64 内容、字节数和可选拖入坐标，不暴露设备本地 URI 或本机绝对路径，也不开放通用文件系统能力。H5 的通用图片输入面板 `CreativeImageInputPanel` 在 `native_app` 且声明 `file.importImage` 时优先调用宿主导入，并把结果转换成现有 `File` 回调；在桌面壳同时声明 `file.imageDropped` 时，只有拖入坐标命中当前主图卡片且未被上层元素遮挡的面板会消费该事件。普通浏览器、小程序和未声明能力的裁剪壳继续使用浏览器文件输入。
- `importHostAudioFile()`：原生 App 宿主的受控音频导入入口。Expo 移动壳通过 Expo DocumentPicker 打开系统音频选择器，Tauri 壳通过系统文件选择框读取用户选择的音频；两端都只接受 `audio/mpeg`、`audio/mp4`、`audio/wav`、`audio/ogg`、`audio/webm` 或对应扩展名，单次不超过 20 MiB，成功只返回清洗后的文件名、MIME、base64 内容和字节数，不暴露设备本地 URI 或本机绝对路径，也不开放通用文件系统能力。H5 的通用音频输入面板 `CreativeAudioInputPanel` 在 `native_app` 且声明 `file.importAudio` 时优先调用宿主导入，并把结果转换成现有 `File` 后继续复用 `readFileAsAsset(file, 'uploaded')` 音频处理链路；普通浏览器、小程序和未声明能力的裁剪壳继续使用浏览器文件输入。
- `exportHostAudioFile()`：原生 App 宿主的受控音频导出入口。H5 只传当前页面已持有的音频 `base64Data`、清洗后的文件名和允许的 `audio/mpeg` / `audio/mp4` / `audio/wav` / `audio/ogg` / `audio/webm` MIME；Expo 移动壳写入缓存音频后交给系统分享 / 保存面板，Tauri 壳打开系统保存对话框并写入音频字节。单次音频不超过 20 MiB，成功只返回文件名和字节数，不回传本机绝对路径，也不让宿主代读任意本地文件。H5 的通用音频输入面板只在当前资产包含本地 `Blob`、`fileName` 和允许 MIME 且宿主声明 `file.exportAudio` 时展示导出入口；远端已上传音频、浏览器、小程序和未声明能力的裁剪壳不展示该入口。
## 迁移顺序
packages/shared/src/contracts/hostBridge.test.ts
+1
View File
@@ -61,6 +61,7 @@ describe('HostBridge shared contract helpers', () => {
expect(isHostBridgeCapability('file.importText')).toBe(true);
expect(isHostBridgeCapability('file.importImage')).toBe(true);
expect(isHostBridgeCapability('file.importAudio')).toBe(true);
expect(isHostBridgeCapability('file.exportAudio')).toBe(true);
expect(isHostBridgeCapability('file.imageDropped')).toBe(true);
expect(isHostBridgeCapability('app.setBadgeCount')).toBe(true);
expect(isHostBridgeCapability('notification.showLocal')).toBe(true);
packages/shared/src/contracts/hostBridge.ts
+13
View File
@@ -33,6 +33,7 @@ export const HOST_BRIDGE_METHODS = [
'file.exportImage',
'file.importImage',
'file.importAudio',
'file.exportAudio',
'haptics.impact',
'notification.showLocal',
] as const;
@@ -352,6 +353,18 @@ export type FileImportAudioResult = {
bytes: number;
};
export type FileExportAudioPayload = {
fileName: string;
base64Data: string;
mimeType: HostBridgeAudioMimeType;
};
export type FileExportAudioResult = {
action: 'saved';
fileName: string;
bytes: number;
};
export type HapticsImpactPayload = {
style?: 'light' | 'medium' | 'heavy';
};
src/components/common/CreativeAudioInputPanel.test.tsx
+133
View File
@@ -10,6 +10,11 @@ import type { CreativeAudioAsset } from './creativeAudioFileAsset';
import { CreativeAudioInputPanel } from './CreativeAudioInputPanel';
type TestAudioAsset = CreativeAudioAsset;
type ExportableTestAudioAsset = TestAudioAsset & {
blob: Blob;
fileName: string;
mimeType: string;
};
const originalMediaRecorder = globalThis.MediaRecorder;
const originalMediaDevices = navigator.mediaDevices;
@@ -40,6 +45,18 @@ function buildAsset(overrides: Partial<TestAudioAsset> = {}): TestAudioAsset {
};
}
function buildExportableAsset(
overrides: Partial<ExportableTestAudioAsset> = {},
): ExportableTestAudioAsset {
return {
...buildAsset(),
blob: new Blob(['audio'], { type: 'audio/wav' }),
fileName: 'hit.wav',
mimeType: 'audio/wav',
...overrides,
};
}
function renderPanel(
overrides: Partial<
ComponentProps<typeof CreativeAudioInputPanel<TestAudioAsset>>
@@ -217,6 +234,122 @@ test('原生 App 宿主可用时上传按钮走 HostBridge 音频导入', async
});
});
test('原生 App 宿主可用且当前音频为本地资产时可以导出音频', 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: true,
result: {
action: 'saved',
fileName: 'hit.wav',
bytes: 5,
},
};
},
);
window.history.replaceState(
null,
'',
'/?clientRuntime=native_app&hostCapabilities=file.exportAudio',
);
window.__TAURI__ = {
core: {
invoke: async <Result,>(
command: string,
args?: Record<string, unknown>,
) => (await invoke(command, args)) as Result,
},
};
const { onError } = renderPanel({
asset: buildExportableAsset(),
});
fireEvent.click(screen.getByRole('button', { name: '导出' }));
await waitFor(() =>
expect(invoke).toHaveBeenCalledWith('host_bridge_request', {
request: expect.objectContaining({
method: 'file.exportAudio',
payload: {
fileName: 'hit.wav',
base64Data: 'YXVkaW8=',
mimeType: 'audio/wav',
},
timeoutMs: 30000,
}),
}),
);
expect(onError).toHaveBeenCalledWith(null);
});
test('非本地音频资产或未声明能力时不显示导出入口', () => {
const { rerender } = renderPanel({
asset: buildExportableAsset(),
});
expect(screen.queryByRole('button', { name: '导出' })).toBeNull();
window.history.replaceState(
null,
'',
'/?clientRuntime=native_app&hostCapabilities=file.exportAudio',
);
rerender(
<CreativeAudioInputPanel<TestAudioAsset>
title="敲击音效"
defaultLabel="默认木鱼音"
asset={buildAsset({ audioSrc: '/generated/hit.wav' })}
buildRecordedFileName={() => 'recorded-hit.webm'}
onAssetChange={() => {}}
onError={() => {}}
/>,
);
expect(screen.queryByRole('button', { name: '导出' })).toBeNull();
});
test('导出音频失败时提示错误', 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: 'host_error',
message: '系统保存失败。',
},
};
},
);
window.history.replaceState(
null,
'',
'/?clientRuntime=native_app&hostCapabilities=file.exportAudio',
);
window.__TAURI__ = {
core: {
invoke: async <Result,>(
command: string,
args?: Record<string, unknown>,
) => (await invoke(command, args)) as Result,
},
};
const { onError } = renderPanel({
asset: buildExportableAsset(),
});
fireEvent.click(screen.getByRole('button', { name: '导出' }));
await waitFor(() => expect(onError).toHaveBeenCalledWith('系统保存失败。'));
});
test('上传音频失败时提示错误且不写入资产', async () => {
const readFileAsAsset = vi.fn(async () => {
throw new Error('音频最长 1 秒。');
src/components/common/CreativeAudioInputPanel.tsx
+115 -14
View File
@@ -1,8 +1,9 @@
import { Mic, Pause, Upload } from 'lucide-react';
import { Download, Mic, Pause, Upload } from 'lucide-react';
import { useRef, useState } from 'react';
import {
canUseNativeHostCapability,
exportHostAudioFile,
type HostFileImportAudioResult,
importHostAudioFile,
} from '../../services/host-bridge/hostBridge';
@@ -29,6 +30,67 @@ type CreativeAudioInputPanelProps<TAsset extends CreativeAudioAsset> = {
) => Promise<TAsset>;
};
type ExportableCreativeAudioAsset = CreativeAudioAsset & {
blob?: Blob;
fileName?: string;
mimeType?: string;
};
const HOST_EXPORT_AUDIO_MIME_TYPES = new Set([
'audio/mpeg',
'audio/mp4',
'audio/wav',
'audio/ogg',
'audio/webm',
]);
function resolveExportableAudioAsset<TAsset extends CreativeAudioAsset>(
asset: TAsset | null,
) {
const candidate = asset as ExportableCreativeAudioAsset | null;
if (
!candidate?.blob ||
!(candidate.blob instanceof Blob) ||
!candidate.fileName?.trim() ||
!candidate.mimeType?.trim() ||
!HOST_EXPORT_AUDIO_MIME_TYPES.has(candidate.mimeType)
) {
return null;
}
return {
blob: candidate.blob,
fileName: candidate.fileName.trim(),
mimeType: candidate.mimeType as
| 'audio/mpeg'
| 'audio/mp4'
| 'audio/wav'
| 'audio/ogg'
| 'audio/webm',
};
}
function blobToBase64Data(blob: Blob) {
return new Promise<string>((resolve, reject) => {
const reader = new FileReader();
reader.onerror = () => reject(new Error('音频导出失败。'));
reader.onload = () => {
if (typeof reader.result !== 'string') {
reject(new Error('音频导出失败。'));
return;
}
const base64Data = reader.result.split(',')[1] ?? '';
if (!base64Data) {
reject(new Error('音频导出失败。'));
return;
}
resolve(base64Data);
};
reader.readAsDataURL(blob);
});
}
export function CreativeAudioInputPanel<TAsset extends CreativeAudioAsset>({
disabled = false,
title,
@@ -41,10 +103,11 @@ export function CreativeAudioInputPanel<TAsset extends CreativeAudioAsset>({
readFileAsAsset = readCreativeAudioFileAsAsset,
}: CreativeAudioInputPanelProps<TAsset>) {
const [isRecording, setIsRecording] = useState(false);
const uploadInputRef = useRef<HTMLInputElement | null>(null);
const recorderRef = useRef<MediaRecorder | null>(null);
const chunksRef = useRef<BlobPart[]>([]);
const canImportHostAudio = canUseNativeHostCapability('file.importAudio');
const canExportHostAudio = canUseNativeHostCapability('file.exportAudio');
const exportableAsset = resolveExportableAudioAsset(asset);
const hostAudioImportResultToFile = (result: HostFileImportAudioResult) => {
const binary = atob(result.base64Data);
@@ -70,6 +133,22 @@ export function CreativeAudioInputPanel<TAsset extends CreativeAudioAsset>({
onAssetChange(nextAsset);
};
const exportHostAudioAsset = async () => {
if (!exportableAsset) {
return;
}
const base64Data = await blobToBase64Data(exportableAsset.blob);
const exported = await exportHostAudioFile({
fileName: exportableAsset.fileName,
base64Data,
mimeType: exportableAsset.mimeType,
});
if (exported) {
onError(null);
}
};
const startRecording = async () => {
if (disabled || isRecording) {
return;
@@ -140,17 +219,40 @@ export function CreativeAudioInputPanel<TAsset extends CreativeAudioAsset>({
}
titleVariant="strong"
actions={
asset ? (
<PlatformActionButton
onClick={() => onAssetChange(null)}
disabled={disabled}
tone="ghost"
size="xs"
className="min-h-0"
>
重置
</PlatformActionButton>
) : null
<div className="flex items-center gap-2">
{canExportHostAudio && exportableAsset ? (
<PlatformActionButton
onClick={() => {
void exportHostAudioAsset().catch((caughtError) => {
onError(
caughtError instanceof Error
? caughtError.message
: '音频导出失败。',
);
});
}}
disabled={disabled}
tone="ghost"
size="xs"
className="min-h-0 gap-1"
title="导出音频"
>
<Download className="h-3.5 w-3.5" />
导出
</PlatformActionButton>
) : null}
{asset ? (
<PlatformActionButton
onClick={() => onAssetChange(null)}
disabled={disabled}
tone="ghost"
size="xs"
className="min-h-0"
>
重置
</PlatformActionButton>
) : null}
</div>
}
bodyClassName="mt-3 flex flex-wrap items-center gap-2"
>
@@ -181,7 +283,6 @@ export function CreativeAudioInputPanel<TAsset extends CreativeAudioAsset>({
<Upload className="h-4 w-4" />
上传
<input
ref={uploadInputRef}
type="file"
accept="audio/*"
disabled={disabled}
src/services/host-bridge/hostBridge.test.ts
+76
View File
@@ -6,6 +6,7 @@ import type { HostBridgeCapability } from '../../../packages/shared/src/contract
import {
canUseHostShareGrid,
canUseNativeHostCapability,
exportHostAudioFile,
exportHostImageFile,
exportHostTextFile,
getHostAppearanceColorScheme,
@@ -651,6 +652,7 @@ describe('hostBridge', () => {
'file.exportImage',
'file.importImage',
'file.importAudio',
'file.exportAudio',
'file.imageDropped',
'notification.showLocal',
]),
@@ -734,6 +736,13 @@ describe('hostBridge', () => {
mimeType: 'audio/webm',
bytes: 5,
});
await expect(
exportHostAudioFile({
fileName: '敲击音效.wav',
base64Data: 'YXVkaW8=',
mimeType: 'audio/wav',
}),
).resolves.toBe(true);
await expect(
showHostLocalNotification({
title: ' 生成完成 ',
@@ -939,6 +948,13 @@ describe('hostBridge', () => {
await expect(importHostImageFile()).resolves.toBe(false);
await expect(importHostTextFile()).resolves.toBe(false);
await expect(importHostAudioFile()).resolves.toBe(false);
await expect(
exportHostAudioFile({
fileName: '敲击音效.wav',
base64Data: 'YXVkaW8=',
mimeType: 'audio/wav',
}),
).resolves.toBe(false);
await expect(
showHostLocalNotification({
title: '生成完成',
@@ -966,6 +982,13 @@ describe('hostBridge', () => {
await expect(importHostImageFile()).resolves.toBe(false);
await expect(importHostTextFile()).resolves.toBe(false);
await expect(importHostAudioFile()).resolves.toBe(false);
await expect(
exportHostAudioFile({
fileName: '敲击音效.wav',
base64Data: 'YXVkaW8=',
mimeType: 'audio/wav',
}),
).resolves.toBe(false);
await expect(
showHostLocalNotification({
title: '生成完成',
@@ -1307,6 +1330,59 @@ describe('hostBridge', () => {
});
});
test('原生 App 宿主通过 HostBridge 导出音频文件', 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: true,
result: {
action: 'saved',
fileName: '敲击音效.wav',
bytes: 5,
},
};
},
);
window.history.replaceState(
null,
'',
nativeAppPath(['file.exportAudio']),
);
window.__TAURI__ = {
core: {
invoke: asTauriInvoke(invoke),
},
};
await expect(
exportHostAudioFile({
fileName: '敲击音效.wav',
base64Data: 'YXVkaW8=',
mimeType: 'audio/wav',
}),
).resolves.toEqual({
action: 'saved',
fileName: '敲击音效.wav',
bytes: 5,
});
expect(invoke).toHaveBeenCalledWith('host_bridge_request', {
request: expect.objectContaining({
method: 'file.exportAudio',
payload: {
fileName: '敲击音效.wav',
base64Data: 'YXVkaW8=',
mimeType: 'audio/wav',
},
timeoutMs: 30000,
}),
});
});
test('原生 App 宿主取消导入音频时回退为 false', async () => {
const invoke = vi.fn(
async (_command: string, args?: Record<string, unknown>) => {
src/services/host-bridge/hostBridge.ts
+25
View File
@@ -2,6 +2,8 @@ import type {
AppearanceColorSchemeResult,
AppLifecycleEventPayload,
ClipboardReadTextResult,
FileExportAudioPayload,
FileExportAudioResult,
FileExportImagePayload,
FileExportImageResult,
FileExportTextPayload,
@@ -96,6 +98,8 @@ export type HostFileExportTextRequest = FileExportTextPayload;
export type HostFileExportImageRequest = FileExportImagePayload;
export type HostFileExportAudioRequest = FileExportAudioPayload;
export type HostFileImportImageResult = FileImportImageResult;
export type HostFileImportTextResult = FileImportTextResult;
@@ -782,6 +786,27 @@ export async function exportHostImageFile(
}
}
export async function exportHostAudioFile(
params: HostFileExportAudioRequest,
) {
if (!canUseNativeHostCapability('file.exportAudio')) {
return false;
}
try {
return await requestNativeAppHostBridge<FileExportAudioResult>(
'file.exportAudio',
params,
{ timeoutMs: 30000 },
);
} catch (error) {
if (isUnsupportedHostBridgeError(error)) {
return false;
}
throw error;
}
}
const HOST_BRIDGE_IMAGE_MIME_TYPES = new Set<HostBridgeImageMimeType>([
'image/png',
'image/jpeg',