---
title: "HTTP"
description: "Kasumi HTTP 下载插件的方法、限制、权限与生命周期。"
---


> 理解 HTTP 插件的 HTTPS 下载、虚拟目标、重定向、超时、取消和资源上限。

## 模块边界

HTTP 插件当前只提供下载。它不提供通用请求、上传、进度事件、公开 `AbortSignal`、请求头
定制或响应缓存。下载内容必须写入可写虚拟文件系统，不返回真实文件路径。

| 层级 | 入口 | 责任 |
| --- | --- | --- |
| 前端 API | `frontend/src/api/http.ts` | URL、路径、布尔值和 120 秒超时 |
| 协议清单 | `protocol/plugins.json` | `http` 插件和 `http.download` 归属 |
| Windows 插件 | `windows/src/plugins/ksm_http_plugin.cpp` | 请求分发和取消 |
| Windows 传输 | `windows/src/platform/ksm_windows_host_services.cpp` | WinHTTP、重定向和临时文件 |
| Android 传输 | `KSMAndroidHostServices.kt` | `HttpsURLConnection` 和生命周期取消 |

## 平台与权限

| 命令 | Windows | Android | 权限 | 返回 |
| --- | --- | --- | --- | --- |
| `http.download` | 支持 | 支持 | `http.download` | `{ path, bytes }` |

## 参数与固定行为

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `url` | string | 是 | 绝对 `https://` URL |
| `path` | string | 是 | `app://data`、`app://cache` 或 `app://tmp` 下的文件路径 |
| `overwrite` | boolean | 否 | 默认 `false` |

固定语义：

- 只允许 HTTPS；拒绝非 HTTPS、用户名密码、空主机和超长 URL。
- 目标不能是目录、只读根、`app://picked` 或真实文件路径。
- 最多跟随 5 次重定向，每一跳仍必须是 HTTPS。
- 总超时 120 秒，最大下载体积 100 MiB。
- 先写目标同目录 `.part` 文件，成功后提交；失败、超时或取消时删除临时文件。
- `overwrite: false` 时目标已存在返回 `IO_ERROR`。
- 不提供进度事件。前端超时或页面重载会通过现有 `cancel` 链路中止请求。

## 示例

```ts
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('目标已存在或下载提交失败');
  }
}
```

## 平台差异

Windows 使用 WinHTTP 并关闭自动重定向，取消时关闭活动句柄。Android 使用
`HttpsURLConnection`，取消时 `disconnect()` 活动连接。Android 在低内存或 Activity
销毁时只取消当前窗口下载；两端都逐跳校验 HTTPS。

## 错误行为

| 错误码 | 场景 |
| --- | --- |
| `INVALID_ARGS` | URL、路径或 `overwrite` 类型非法 |
| `PERMISSION_DENIED` | 未授予 `http.download` 或路径越界 |
| `BUSY` | 同一请求 ID 已有下载 |
| `IO_ERROR` | 目标存在、重定向超限、体积超限、网络或提交失败 |
| `TIMEOUT` | 前端请求超时或宿主总下载超时 |
| `CANCELLED` | 页面重载、窗口销毁或显式取消 |
| `NOT_SUPPORTED` | 宿主未配置下载服务 |

## 排查路径

1. 确认 URL 是绝对 HTTPS，且没有凭据。
2. 确认目标是可写沙箱中的文件，不是目录或 picked 句柄。
3. 目标已存在时显式设置 `overwrite: true`，或改用新路径。
4. 检查重定向是否超过 5 次，每一跳是否仍为 HTTPS。
5. 检查响应声明长度和实际写入是否超过 100 MiB。
6. 失败后检查目录是否残留 `.part` 文件。
7. 页面重载后不要复用旧请求 ID 或错误地重试已完成下载。