api
HTTP 下载
查看 Markdown将 HTTPS 资源安全下载到 Kasumi 虚拟文件系统。
将 HTTPS 资源下载到 Kasumi 可写虚拟路径，并控制覆盖、重定向、超时和体积上限。
http 当前只提供下载，不提供任意 HTTP 请求、上传、进度事件或公开的 AbortSignal。下载结果
必须写入沙箱，不能返回真实文件路径。
实现入口：
| 入口 | 责任 |
|---|---|
frontend/src/api/http.ts | 参数守卫和 120 秒请求超时 |
frontend/src/bridge/ksm.ts | KSM.http.download 根入口 |
windows/src/platform/ksm_windows_host_services.cpp | WinHTTP 下载、重定向、取消和临时文件 |
android/app/src/main/java/dev/kasumi/app/KSMAndroidHostServices.kt | HttpsURLConnection 下载和生命周期取消 |
| 方法 | Windows | Android | 权限 |
|---|---|---|---|
KSM.http.download / http.download | 支持 | 支持 | http.download |
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
url | string | 是 | 绝对 https:// URL |
path | string | 是 | app://data、app://cache 或 app://tmp 下的文件路径 |
overwrite | boolean | 否 | 默认 false |
返回：
interface KSMHttpDownloadResult {
path: string;
bytes: number;
}path 是规范化后的虚拟目标路径，bytes 是实际写入字节数。
app://picked，也不能是真实文件路径。.part 文件；成功后提交，失败、超时或取消时删除临时文件。overwrite 为 false 时，目标已存在返回 IO_ERROR，不覆盖原文件。cancel 消息，宿主收到后必须中止网络请求。import { KSM } from '@kasumi/bridge';
try {
const result = await KSM.http.download({
url: 'https://example.com/releases/kasumi.zip',
path: 'app://cache/releases/kasumi.zip',
overwrite: false
});
console.info(result.path, result.bytes);
} catch (error) {
if (error instanceof Error && error.name === 'IO_ERROR') {
console.warn('目标已存在或下载提交失败');
}
}| 情况 | 错误 |
|---|---|
非 HTTPS、凭据、空主机、非法 path、非布尔 overwrite | INVALID_ARGS |
未授予 http.download，或路径越界 | PERMISSION_DENIED |
| 目标已存在且未允许覆盖 | IO_ERROR |
| 重定向超限、体积超限、网络或提交失败 | IO_ERROR |
| 前端请求超时 | TIMEOUT |
| 请求被取消 | CANCELLED |
| 宿主未配置下载服务 | NOT_SUPPORTED |
前端封装会先抛普通 TypeError 拒绝明显非法参数；绕过封装直接调用协议时，宿主仍会返回标准
错误码。
Windows 使用 WinHTTP，取消时关闭活动句柄；Android 使用 HttpsURLConnection，取消时
disconnect() 活动连接。Android 在 onTrimMemory 和 Activity 销毁时也会取消下载。两端都
关闭自动重定向并逐跳校验 HTTPS。
app://picked。overwrite: true。.part 文件。
评论