@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/references/frontend/doubao-agentic-service-api/10-/347/275/221/347/273/234.md

@@ -0,0 +1,900 @@
+# 豆包应用插件的端能力 API: 网络
+
+网络请求与 WebSocket。
+
+[返回目录](./groups.md) | [返回速查](./quick-reference.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [request](#request) | 发起网络请求。 request 本身不接受泛型参数；如需业务数据类型，请读取 result.data 后再做类型收窄或断言。 |
+| [connectSocket](#connectsocket) | 创建一个 WebSocket 连接，并返回可操作该连接的 SocketTask。 该 API 会同步返回 SocketTask，但连接创建本身是异步过程。调用方应先在返回的 SocketTask 上注册事件回调，再等待 onOpen 表示连接可用。后续发送消息使用 SocketTask.send，关闭连接使用 SocketTask.close。 |
+| [uploadFile](#uploadfile) | 上传本地文件，并返回可用于监听进度和中断上传的 UploadTask。 |
+| [downloadFile](#downloadfile) | 下载文件，并返回可取消、可监听进度的 DownloadTask。 |
+
+## API 详情
+
+<a id="request"></a>
+### request()
+
+# request
+
+发起网络请求。
+
+`request` 本身不接受泛型参数；如需业务数据类型，请读取 `result.data` 后再做类型收窄或断言。
+
+## 扫码预览
+![扫码预览 request](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fnetwork%252Frequest%252Findex)
+
+## 使用限制
+
+> [!WARNING]
+> **Android、iOS**：Android 仅支持 GET/POST/PUT/DELETE，其余方法返回 &quot;Illegal method&quot;；iOS 仅支持 GET/POST，其余方法返回 &quot;method type not supported&quot;；调用 PUT/DELETE 时 iOS 会失败；调用 HEAD/OPTIONS/TRACE/CONNECT 时双端均失败。
+> **Android、iOS**：Android 将二进制响应以 base64 字符串返回；iOS doubao.request 路径不启用 arraybuffer 支持，返回 base64 编码字符串；调用方按 ArrayBuffer 解析会失败。
+
+## 支持版本
+
+前端库版本不低于 `0.0.17`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 使用说明
+
+返回 statusCode、header 和 data。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+request(params: RequestParams): Promise<RequestResponse>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>data</code></td><td><code>string | ArrayBuffer | Record&lt;string, any&gt;</code></td><td>否</td><td><code>-</code></td><td>-</td><td>请求体数据。<br><br>传给服务器的数据最终会是 `String` 或 `ArrayBuffer`：<br>- 若 `data` 是 `string` 或 `ArrayBuffer`，直接使用；<br>- 若 `header['content-type']` 是 `application/x-www-form-urlencoded`，会被编码为 query string，例如：`encodeURIComponent(k)=encodeURIComponent(v)`；<br>- 若 `header['content-type']` 是 `application/json`，会执行 JSON 序列化；<br>- 若 `data` 是普通对象且未命中上述类型，也会执行 JSON 序列化；<br>- 其他类型会调用 `toString()`</td></tr>
+<tr><td><code>dataType</code></td><td><code>&quot;string&quot; | &quot;json&quot; | &quot;arraybuffer&quot;</code></td><td>否</td><td><code>&quot;json&quot;</code></td><td>-</td><td>期望返回的数据格式。<br>- `json`：尝试按 JSON 解析；<br>- `string`：按字符串返回。<br>- `arraybuffer`：按二进制数据返回。</td></tr>
+<tr><td><code>header</code></td><td><code>Record&lt;string, string&gt;</code></td><td>否</td><td><code>{&quot;content-type&quot;: &quot;application/json&quot;}</code></td><td>-</td><td>请求 Header。</td></tr>
+<tr><td><code>method</code></td><td><code>RequestMethod</code></td><td>否</td><td><code>&quot;GET&quot;</code></td><td>-</td><td>请求方法。Android、iOS：Android 仅支持 GET/POST/PUT/DELETE，其余方法返回 &quot;Illegal method&quot;；iOS 仅支持 GET/POST，其余方法返回 &quot;method type not supported&quot;。</td></tr>
+<tr><td><code>url</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>请求地址，需为完整的 HTTP 或 HTTPS URL。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { request } from '@doubao-dev/framework/api';
+
+const result = await request({
+  url: 'https://postman-echo.com/post',
+  method: 'POST',
+  dataType: 'json',
+  header: { 'content-type': 'application/json' },
+  data: { hello: 'world' }
+});
+
+console.log(result.statusCode, result.data);
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>data</code></td><td><code>string | ArrayBuffer | Record&lt;string, any&gt;</code></td><td>否</td><td>响应数据，类型由 `dataType` 决定。</td></tr>
+<tr><td><code>header</code></td><td><code>Record&lt;string, string&gt;</code></td><td>是</td><td>HTTP 响应头。</td></tr>
+<tr><td><code>statusCode</code></td><td><code>number</code></td><td>是</td><td>HTTP 状态码。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "statusCode": 200,
+  "header": {
+    "content-type": "application/json"
+  },
+  "data": {
+    "hello": "world"
+  }
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 305,
+  "errMsg": "network failure"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>Android、iOS</td><td>url 为空、method 非法，或请求参数、请求体校验失败</td><td>修正 url、method 与请求参数后重试。</td></tr>
+<tr><td><code>110</code></td><td><code>API call prohibited</code></td><td>Android、iOS</td><td>请求 URL 未通过域名白名单校验</td><td>确认目标域名已在应用插件中配置后重试。</td></tr>
+<tr><td><code>301</code></td><td><code>network request cancelled</code></td><td>iOS</td><td>网络请求被取消</td><td>确认应用与网络状态后重试。</td></tr>
+<tr><td><code>302</code></td><td><code>connection timed out</code></td><td>Android、iOS</td><td>网络连接超时</td><td>检查网络连接后重试。</td></tr>
+<tr><td><code>303</code></td><td><code>no network connection</code></td><td>Android、iOS</td><td>当前无可用网络连接</td><td>恢复网络连接后重试。</td></tr>
+<tr><td><code>305</code></td><td><code>network failure</code></td><td>Android、iOS</td><td>发生其他网络错误</td><td>检查网络连接，稍后重试。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **Android**：网络失败仅细分为 302（HTTP 408 超时）、303（无网络连接）与 305（其他网络错误），不返回 301；url 为空或 method 非法返回 104；命中域名管控返回 110。
+- **iOS**：依据 NSURLError 细分网络失败：请求取消 301、连接超时 302、无网络 303、其他 305；参数或请求体校验失败返回 104；命中域名管控返回 110；其他失败统一返回 102。
+
+<a id="connectsocket"></a>
+### connectSocket()
+
+# connectSocket
+
+创建一个 WebSocket 连接，并返回可操作该连接的 SocketTask。
+
+该 API 会同步返回 `SocketTask`，但连接创建本身是异步过程。调用方应先在返回的
+`SocketTask` 上注册事件回调，再等待 `onOpen` 表示连接可用。后续发送消息使用
+`SocketTask.send`，关闭连接使用 `SocketTask.close`。
+
+## 扫码预览
+![扫码预览 connectSocket](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fnetwork%252Fconnect-socket%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.30`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 使用说明
+
+- 返回 `SocketTask` 不代表连接已经成功，连接成功以 `onOpen` 为准。
+- `send` 必须接收对象参数，并把要发送的内容放在 `data` 字段中。
+- 如果 `protocols` 非空，需要服务端支持并返回匹配的子协议。
+- 多次调用会创建多条连接，旧连接不会自动关闭；不再使用时应主动调用 `close`。
+- 连接失败、发送失败或关闭失败会通过 `SocketTask.onError` 通知。
+
+- 不再使用的连接应主动调用 SocketTask.close 释放资源，避免占用连接名额。
+
+## 调用方式
+
+### 同步 API
+
+```typescript
+connectSocket(params: ConnectSocketParams): SocketTask
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>header</code></td><td><code>Record&lt;string, string&gt;</code></td><td>否</td><td><code>-</code></td><td>-</td><td>WebSocket 握手阶段携带的 HTTP Header。<br><br>适合放置业务自定义 Header，例如鉴权 token、trace id、客户端能力标识等。<br>`referer` 由豆包客户端统一生成和管理，不应依赖该字段被业务传入值覆盖。</td></tr>
+<tr><td><code>protocols</code></td><td><code>string[]</code></td><td>否</td><td><code>-</code></td><td>-</td><td>WebSocket 子协议数组。<br><br>会作为握手请求中的 `Sec-WebSocket-Protocol` 候选值传给服务端。<br>如果传入非空数组，服务端需要选择其中一个协议并在握手响应中返回；<br>服务端不支持或不返回匹配协议时，豆包客户端可能判定连接创建失败。</td></tr>
+<tr><td><code>url</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>WebSocket 连接地址。<br><br>需要包含协议、域名、路径和可选 query，例如 `wss://example.com/socket?room=1`。<br>如果地址为空或不是字符串，本 API 会返回 `readyState` 为 `undefined` 的 SocketTask，<br>并异步触发 `onError`。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { connectSocket } from '@doubao-dev/framework/api';
+
+const socketTask = connectSocket({
+  url: 'wss://example.com/socket',
+  header: { authorization: 'Bearer token' },
+  protocols: ['chat.v1']
+});
+
+socketTask.onOpen(() => {
+  socketTask.send({ data: 'hello' });
+});
+
+socketTask.onMessage((event) => {
+  console.log(event.data);
+});
+
+socketTask.onClose((event) => {
+  console.log(event.code, event.reason);
+});
+
+socketTask.onError((event) => {
+  console.error(event.errMsg);
+});
+```
+
+## 返回值
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>close</code></td><td><code>(params?: SocketTaskCloseParams) =&gt; void</code></td><td>是</td><td>关闭 WebSocket 连接。<br><br>调用后会发起关闭动作，并把 `readyState` 置为 `SocketTask.CLOSING`。<br>最终关闭完成时触发 `onClose`；关闭动作失败时触发 `onError`。</td></tr>
+<tr><td><code>CLOSED</code></td><td><code>3</code></td><td>是</td><td>表示 Socket 连接已关闭。<br><br>进入该状态后，该任务不会再收到新的消息，也不应继续调用 `send`。</td></tr>
+<tr><td><code>CLOSING</code></td><td><code>2</code></td><td>是</td><td>表示 Socket 连接关闭中。<br><br>调用 SocketTask.close 后，等待豆包客户端完成关闭流程时通常处于该状态。</td></tr>
+<tr><td><code>CONNECTING</code></td><td><code>0</code></td><td>是</td><td>表示 Socket 正在连接。<br><br>`connectSocket` 刚返回且豆包客户端尚未完成握手时通常处于该状态。</td></tr>
+<tr><td><code>onClose</code></td><td><code>(callback: (event: SocketTaskCloseEvent) =&gt; void) =&gt; void</code></td><td>是</td><td>监听 WebSocket 与服务器连接断开的事件。<br><br>主动关闭、服务端关闭、连接被回收都可能触发该回调。<br>回调触发后当前任务已经结束，不应继续使用。</td></tr>
+<tr><td><code>onError</code></td><td><code>(callback: (event: SocketTaskErrorEvent) =&gt; void) =&gt; void</code></td><td>是</td><td>监听 WebSocket 发生错误的事件。<br><br>连接创建、发送、关闭或 WebSocket 通道出现异常时触发。<br>该回调只表示发生错误，不等同于连接一定已经关闭；是否关闭应结合 `readyState`<br>或后续 `onClose` 事件判断。</td></tr>
+<tr><td><code>onMessage</code></td><td><code>(callback: (event: SocketTaskMessageEvent) =&gt; void) =&gt; void</code></td><td>是</td><td>监听 WebSocket 接收到服务器发送信息的事件。<br><br>服务端每下发一条消息都会触发一次回调。消息内容通过 `event.data` 返回，<br>类型可能是 `string` 或 `ArrayBuffer`。</td></tr>
+<tr><td><code>onOpen</code></td><td><code>(callback: (event: SocketTaskOpenEvent) =&gt; void) =&gt; void</code></td><td>是</td><td>监听 WebSocket 连接服务器成功的事件。<br><br>可以注册多个回调。连接成功后触发回调，并携带握手响应 Header、协议类型等信息。<br>通常应在该回调中或之后调用 `send`。</td></tr>
+<tr><td><code>OPEN</code></td><td><code>1</code></td><td>是</td><td>表示 Socket 连接已经打开。<br><br>进入该状态后可以调用 SocketTask.send 发送数据。</td></tr>
+<tr><td><code>readyState</code></td><td><code>number | undefined</code></td><td>是</td><td>当前 Socket 连接状态 code。<br><br>可与 `CONNECTING`、`OPEN`、`CLOSING`、`CLOSED` 常量比较。<br>如果因为参数错误等原因导致豆包客户端没有成功创建连接，则为 `undefined`。</td></tr>
+<tr><td><code>send</code></td><td><code>(params: SocketTaskSendParams) =&gt; void</code></td><td>是</td><td>通过 WebSocket 连接发送数据。<br><br>该方法只发起发送动作，不返回发送结果。建议在 `readyState === SocketTask.OPEN`<br>或收到 `onOpen` 事件后调用；如果连接未就绪、数据编码失败或发送失败，<br>会触发 `onError`。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "readyState": 0
+}
+```
+
+## 错误处理
+
+同步调用失败时抛出错误。错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 1501001,
+  "errMsg": "websocket connection limit exceeded"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>Android、iOS</td><td>创建连接时 url 为空或非 ws/wss，或调用 send 时 base64 数据非法、dataType 不支持</td><td>传入合法的 ws/wss url 与受支持的发送数据后重试。</td></tr>
+<tr><td><code>110</code></td><td><code>API call prohibited</code></td><td>Android、iOS</td><td>socket url 未通过域名白名单校验</td><td>确认目标域名已在应用插件中配置后重试。</td></tr>
+<tr><td><code>116</code></td><td><code>resource not found</code></td><td>Android、iOS</td><td>对已关闭或不存在的 socketTaskId 调用 send/close</td><td>仅在 onOpen 后、onClose 前操作连接，不要复用已关闭的连接。</td></tr>
+<tr><td><code>305</code></td><td><code>network failure</code></td><td>Android、iOS</td><td>建立连接、发送或关闭过程中发生网络错误</td><td>检查网络连接，必要时重新建立连接。</td></tr>
+<tr><td><code>1501001</code></td><td><code>websocket connection limit exceeded</code></td><td>Android、iOS</td><td>同一应用插件的 WebSocket 连接数超过上限</td><td>关闭不再使用的连接后重试。</td></tr>
+<tr><td><code>1501002</code></td><td><code>websocket is not open</code></td><td>iOS</td><td>连接尚未打开或已关闭时调用 send</td><td>在收到 onOpen 事件后再发送数据。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android</td></tr>
+<tr><td><code>113</code></td><td><code>bridge unavailable</code></td><td>JS API 暂不可用</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **Android**：建立连接失败统一返回 102；send 在连接未打开时返回 305 或 116。
+- **iOS**：send 在连接未打开时返回 1501002。
+
+## 已知限制与注意事项
+
+- 同一应用插件内最多同时保持 5 条 WebSocket 连接，超过上限时 connectSocket 会立即同步失败并通过 SocketTask.onError 通知。
+
+<a id="uploadfile"></a>
+### uploadFile()
+
+# uploadFile
+
+上传本地文件，并返回可用于监听进度和中断上传的 UploadTask。
+
+## 扫码预览
+![扫码预览 uploadFile](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fnetwork%252Fupload-file%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.39`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- url 需命中当前应用插件的上传域名白名单，filePath 需指向当前应用插件可访问的本地文件
+
+## 使用说明
+
+`uploadFile` 会同步返回可监听、可中断的 Promise 任务对象。
+建议在调用后立即注册进度和响应头监听；不再需要上传时调用 `UploadTask.abort`。
+
+- 上传成功时 Promise resolve，上传失败或取消时 Promise reject；任务结束或不再使用时应移除监听，必要时调用 abort。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+uploadFile(params: UploadFileParams): UploadTask
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>enableProfile</code></td><td><code>false</code></td><td>否</td><td><code>false</code></td><td>-</td><td>是否返回网络 profile。豆包当前仅支持 false。</td></tr>
+<tr><td><code>filePath</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>要上传文件资源的本地路径。</td></tr>
+<tr><td><code>formData</code></td><td><code>Record&lt;string, unknown&gt;</code></td><td>否</td><td><code>-</code></td><td>-</td><td>额外的 form-data 字段。对象或数组值会按 JSON 字符串传递。</td></tr>
+<tr><td><code>header</code></td><td><code>Record&lt;string, string&gt;</code></td><td>否</td><td><code>-</code></td><td>-</td><td>HTTP 请求 Header。`referer`、`user-agent`、`content-type` 等由豆包客户端管理的字段不会被业务覆盖。</td></tr>
+<tr><td><code>name</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>文件对应的 form field name/key，服务端通过该 key 获取文件内容；multipart filename 使用 filePath 的 basename。</td></tr>
+<tr><td><code>timeout</code></td><td><code>number</code></td><td>否</td><td><code>-</code></td><td>-</td><td>超时时间，单位 ms；不传时使用豆包客户端的默认超时配置。</td></tr>
+<tr><td><code>url</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>开发者服务器地址，需为完整的 HTTP/HTTPS URL，并通过豆包配置的上传域名白名单校验。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { uploadFile } from '@doubao-dev/framework/api';
+
+const task = uploadFile({
+  url: 'https://example.com/upload',
+  filePath: 'ttfile://temp/example.png',
+  name: 'file',
+  formData: { scene: 'profile' }
+});
+
+task
+  .then((result) => {
+    console.log(result.statusCode, result.data);
+  })
+  .catch((error) => {
+    console.error(error);
+  })
+  .finally(() => {
+    console.log('upload finished');
+  });
+
+task.onProgressUpdate((event) => {
+  console.log(event.progress, event.totalBytesSent);
+});
+task.onHeadersReceived((event) => {
+  console.log(event.header);
+});
+
+// 不再需要上传时中断任务。
+// task.abort();
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>data</code></td><td><code>string</code></td><td>否</td><td>服务器返回的数据。</td></tr>
+<tr><td><code>header</code></td><td><code>Record&lt;string, string&gt;</code></td><td>是</td><td>HTTP 响应头。</td></tr>
+<tr><td><code>statusCode</code></td><td><code>number</code></td><td>是</td><td>HTTP 状态码。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "statusCode": 200,
+  "header": {
+    "content-type": "application/json"
+  },
+  "data": "{\"ok\":true}"
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errMsg": "uploadFile:fail request time out",
+  "errNo": 121920,
+  "errorCode": 121920
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>121999</code></td><td><code>uploadFile:fail url is invalid</code></td><td>Android、iOS</td><td>url 缺失或不是有效上传地址</td><td>传入完整的 HTTP/HTTPS URL</td></tr>
+<tr><td><code>121999</code></td><td><code>uploadFile:fail name is required</code></td><td>Android、iOS</td><td>name 缺失或为空</td><td>传入服务端接收文件所使用的 form field name</td></tr>
+<tr><td><code>121901</code></td><td><code>uploadFile:fail url not in domain list</code></td><td>Android、iOS</td><td>url 未命中上传域名白名单</td><td>在应用插件配置中添加上传域名后重试</td></tr>
+<tr><td><code>121902</code></td><td><code>uploadFile:fail no file exist</code></td><td>Android、iOS</td><td>filePath 为空、文件不存在或路径不是文件</td><td>使用文件 API 获取当前应用插件可访问的有效文件路径</td></tr>
+<tr><td><code>121905</code></td><td><code>uploadFile:fail upload file abort</code></td><td>Android、iOS</td><td>调用 UploadTask.abort 中断上传</td><td>按业务需要处理取消状态，无需自动重试</td></tr>
+<tr><td><code>121906</code></td><td><code>uploadFile:fail file path permission denied</code></td><td>Android、iOS</td><td>当前应用插件无权访问 filePath</td><td>改用当前应用插件目录内的文件</td></tr>
+<tr><td><code>121920</code></td><td><code>uploadFile:fail request time out</code></td><td>Android、iOS</td><td>上传超过豆包客户端的超时时间</td><td>检查网络或设置合理的 timeout 后重试</td></tr>
+<tr><td><code>121985</code></td><td><code>uploadFile:fail network unavailable</code></td><td>Android、iOS</td><td>当前网络不可用</td><td>恢复网络连接后重试</td></tr>
+<tr><td><code>121991</code></td><td><code>uploadFile:fail network error</code></td><td>Android、iOS</td><td>上传过程中发生网络错误</td><td>检查网络和服务端状态后重试</td></tr>
+<tr><td><code>121992</code></td><td><code>uploadFile:fail enableProfile is not supported</code></td><td>Android、iOS</td><td>enableProfile 设置为 true</td><td>移除 enableProfile 或设置为 false</td></tr>
+</tbody>
+</table>
+
+<a id="downloadfile"></a>
+### downloadFile()
+
+# downloadFile
+
+下载文件，并返回可取消、可监听进度的 DownloadTask。
+
+## 扫码预览
+![扫码预览 downloadFile](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fnetwork%252Fdownload-file%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.40`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- 下载地址需通过豆包配置的下载域名白名单校验，单个文件不得超过 200 MB，单个应用插件同时最多执行 10 个下载任务；指定 filePath 时仅支持临时目录或用户目录
+
+## 使用说明
+
+- 下载使用 GET 请求。
+- HTTP 传输完成且文件写入成功后，无论 statusCode 是 2xx、4xx 还是 5xx，Promise 都会 resolve。
+- 域名校验失败、路径非法、超时、取消、网络异常、写入失败会使 Promise reject。
+
+- 未指定 filePath 时文件写入临时目录，并通过 Promise resolve 结果的 tempFilePath 返回；临时文件的生命周期由豆包客户端管理。
+- 不跟随 HTTP 重定向，3xx 响应使 Promise reject；4xx、5xx 响应在文件写入成功后仍使 Promise resolve。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+downloadFile(params: DownloadFileParams): DownloadTask
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>filePath</code></td><td><code>string</code></td><td>否</td><td><code>由系统创建临时下载文件</code></td><td>-</td><td>目标文件路径，仅支持 `appletfile://temp/...` 或 `appletfile://user/...`。</td></tr>
+<tr><td><code>header</code></td><td><code>Record&lt;string, string&gt;</code></td><td>否</td><td><code>-</code></td><td>-</td><td>请求 Header。`referer` 和 `user-agent` 由豆包客户端管理，业务传入值不会透传。</td></tr>
+<tr><td><code>timeout</code></td><td><code>number</code></td><td>否</td><td><code>60000</code></td><td>有效范围为 1-300000</td><td>下载任务超时时间，单位 ms；不传或传入非正数时使用 60000，超过 300000 时按 300000 处理。</td></tr>
+<tr><td><code>url</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>下载资源地址，需为完整 HTTPS URL，并通过豆包配置的下载域名白名单校验。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { downloadFile } from '@doubao-dev/framework/api';
+
+const downloadTask = downloadFile({
+  url: 'https://example.com/files/report.pdf'
+});
+
+downloadTask
+  .then((result) => {
+    console.log(result.statusCode, result.tempFilePath ?? result.filePath);
+  })
+  .catch((error) => {
+    console.error(error);
+  })
+  .finally(() => {
+    console.log('download finished');
+  });
+
+downloadTask.onProgressUpdate((event) => {
+  console.log(`downloaded ${event.progress}%`);
+});
+
+downloadTask.onHeadersReceived((event) => {
+  console.log(event.header);
+});
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>filePath</code></td><td><code>string</code></td><td>否</td><td>指定 `filePath` 时返回的目标文件路径。</td></tr>
+<tr><td><code>header</code></td><td><code>Record&lt;string, string&gt;</code></td><td>是</td><td>HTTP 响应头。</td></tr>
+<tr><td><code>statusCode</code></td><td><code>number</code></td><td>是</td><td>HTTP 状态码。非 2xx 响应也会在下载写入成功后返回。</td></tr>
+<tr><td><code>tempFilePath</code></td><td><code>string</code></td><td>否</td><td>未指定 `filePath` 时返回的临时文件路径。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "statusCode": 200,
+  "header": {
+    "content-type": "application/pdf"
+  },
+  "tempFilePath": "appletfile://temp/report.pdf"
+}
+```
+
+## 相关类型
+
+<a id="requestmethod"></a>
+### RequestMethod
+
+#### Type
+
+`'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE' | 'CONNECT'`
+
+<a id="requestparams"></a>
+### RequestParams
+
+网络请求参数。
+
+#### Properties
+
+• **url**: `string` - 请求地址，需为完整的 HTTP 或 HTTPS URL
+• **header?**: `Record<string, string>` - 请求 Header
+• **method?**: `RequestMethod` - 请求方法
+• **data?**: `Record<string, any> | string | ArrayBuffer` - 请求体数据。 传给服务器的数据最终会是 String 或 ArrayBuffer： - 若 data 是 string 或 ArrayBuffer，直接使用； - 若 header['content-type'] 是 application/x-www-form-urlencoded，会被编码为 query string，例如：encodeURIComponent(k)=encodeURIComponent(v)； - 若 header['content-type'] 是 application/json，会执行 JSON 序列化； - 若 data 是普通对象且未命中上述类型，也会执行 JSON 序列化； - 其他类型会调用 toString()
+• **dataType?**: `'json' | 'string' | 'arraybuffer'` - 期望返回的数据格式。 - json：尝试按 JSON 解析； - string：按字符串返回。 - arraybuffer：按二进制数据返回
+
+<a id="requestresponse"></a>
+### RequestResponse
+
+网络请求返回结果。
+
+#### Properties
+
+• **statusCode**: `number` - HTTP 状态码
+• **header**: `Record<string, string>` - HTTP 响应头
+• **data?**: `string | ArrayBuffer | Record<string, any>` - 响应数据，类型由 dataType 决定
+
+<a id="connectsocketparams"></a>
+### ConnectSocketParams
+
+创建 WebSocket 连接的参数。 connectSocket 会把这些参数交给豆包客户端创建连接。连接创建请求发出后， 调用方会立即拿到一个 SocketTask，后续连接成功、失败、收到消息和关闭状态 都通过 SocketTask 上注册的事件回调通知。
+
+#### Properties
+
+• **url**: `string` - WebSocket 连接地址。 需要包含协议、域名、路径和可选 query，例如 wss://example.com/socket?room=1。 如果地址为空或不是字符串，本 API 会返回 readyState 为 undefined 的 SocketTask， 并异步触发 onError
+• **header?**: `Record<string, string>` - WebSocket 握手阶段携带的 HTTP Header。 适合放置业务自定义 Header，例如鉴权 token、trace id、客户端能力标识等。 referer 由豆包客户端统一生成和管理，不应依赖该字段被业务传入值覆盖
+• **protocols?**: `string[]` - WebSocket 子协议数组。 会作为握手请求中的 Sec-WebSocket-Protocol 候选值传给服务端。 如果传入非空数组，服务端需要选择其中一个协议并在握手响应中返回； 服务端不支持或不返回匹配协议时，豆包客户端可能判定连接创建失败
+
+<a id="sockettasksendparams"></a>
+### SocketTaskSendParams
+
+SocketTask.send 的参数。 send 只负责向已打开的 WebSocket 连接写入一条消息，不返回 Promise。 发送失败、连接未就绪或 WebSocket 通道异常时，会通过同一个 SocketTask 的 onError 回调通知。
+
+#### Properties
+
+• **data**: `string | ArrayBuffer` - 需要发送给服务端的数据。 - 传入 string 时按文本消息发送； - 传入 ArrayBuffer 时按二进制消息发送。 建议只在 onOpen 回调触发后调用 send，此时 readyState 通常为 SocketTask.OPEN
+
+<a id="sockettaskcloseparams"></a>
+### SocketTaskCloseParams
+
+SocketTask.close 的参数。 close 用于主动关闭当前 WebSocket 连接。调用后 readyState 会先进入 SocketTask.CLOSING，最终关闭结果通过 onClose 或 onError 回调通知。
+
+#### Properties
+
+• **code?**: `number` - 关闭连接状态码。 不传时由豆包客户端按正常关闭处理，通常等价于 1000。 常见值包括： - 1000: 正常关闭； - 1001: 因页面进入后台、豆包客户端回收连接等原因关闭
+• **reason?**: `string` - 连接被关闭的原因。 该字段会随关闭帧传递给服务端，是否被服务端记录或回传取决于服务端实现
+
+<a id="sockettaskopenevent"></a>
+### SocketTaskOpenEvent
+
+WebSocket 连接成功事件。 当豆包客户端完成 WebSocket 握手并进入 open 状态后触发。 收到该事件后，调用方可以开始通过 SocketTask.send 发送数据。
+
+#### Properties
+
+• **header**: `Record<string, string>` - WebSocket 握手响应中的 Response Header。 豆包 Android、iOS 当前不会透出真实握手响应头，该字段固定返回空对象 {}， 请不要依赖它读取服务端返回的握手 Header
+• **protocolType?**: `string` - 当前连接使用的网络传输层协议。 豆包无法获取时不返回该字段
+• **socketType?**: `string` - 当前连接使用的 WebSocket 组件类型。 具体值因客户端平台而异；豆包无法获取时不返回该字段
+
+<a id="sockettaskmessageevent"></a>
+### SocketTaskMessageEvent
+
+WebSocket 收到服务端消息事件。 服务端通过当前连接下发消息时触发。文本消息会以 string 形式返回； 二进制消息会尽量还原为 ArrayBuffer。
+
+#### Properties
+
+• **data**: `string | ArrayBuffer` - 收到的服务端消息。 - 文本消息返回 string； - 二进制消息返回 ArrayBuffer。 豆包无法将二进制消息转换为 ArrayBuffer 时，内容会保持字符串形式
+• **protocolType?**: `string` - 当前消息所属连接使用的协议。 豆包无法获取时不返回该字段
+• **socketType?**: `string` - 当前连接使用的 WebSocket 组件类型。 具体值因客户端平台而异；豆包无法获取时不返回该字段
+
+<a id="sockettaskcloseevent"></a>
+### SocketTaskCloseEvent
+
+WebSocket 关闭事件。 当前连接被主动关闭、服务端关闭或豆包客户端因异常回收连接时触发。 触发后 readyState 会变为 SocketTask.CLOSED，该 SocketTask 不应再继续发送数据。
+
+#### Properties
+
+• **code?**: `number` - 关闭状态码。 可能来自调用 SocketTask.close 时传入的 code，也可能来自服务端或豆包客户端
+• **reason?**: `string` - 关闭原因。 可能来自调用 SocketTask.close 时传入的 reason，也可能来自服务端或豆包客户端
+• **errMsg?**: `string` - 错误信息。 非正常关闭时豆包客户端可能通过该字段补充失败原因；正常关闭时通常为空
+• **protocolType?**: `string` - 当前连接使用的网络传输层协议。 豆包无法获取时不返回该字段
+• **socketType?**: `string` - 当前连接使用的 WebSocket 组件类型。 具体值因客户端平台而异；豆包无法获取时不返回该字段
+
+<a id="sockettaskerrorevent"></a>
+### SocketTaskErrorEvent
+
+WebSocket 错误事件。 连接创建失败、发送失败、主动关闭失败、WebSocket 通道异常等错误都会通过该事件通知。 如果错误发生在连接创建阶段，readyState 会变为 undefined 或 SocketTask.CLOSED。
+
+#### Properties
+
+• **errMsg**: `string` - 错误信息。 描述参数校验、数据编码或 WebSocket 操作的失败原因，可直接用于日志上报
+
+<a id="sockettask"></a>
+### SocketTask
+
+通过 connectSocket 获取的 WebSocket 任务实例。 SocketTask 表示单条 WebSocket 连接的控制对象。它负责发送数据、关闭连接， 并通过事件回调接收连接状态、服务端消息和错误通知。connectSocket 返回时连接 仍可能处于创建中，调用方应先注册 onOpen、onError、onClose、onMessage 等回调，再根据 onOpen 事件发送业务数据。
+
+#### Properties
+
+• **CONNECTING**: `0` - 表示 Socket 正在连接。 connectSocket 刚返回且豆包客户端尚未完成握手时通常处于该状态
+• **OPEN**: `1` - 表示 Socket 连接已经打开。 进入该状态后可以调用 SocketTask.send 发送数据
+• **CLOSING**: `2` - 表示 Socket 连接关闭中。 调用 SocketTask.close 后，等待豆包客户端完成关闭流程时通常处于该状态
+• **CLOSED**: `3` - 表示 Socket 连接已关闭。 进入该状态后，该任务不会再收到新的消息，也不应继续调用 send
+• **readyState**: `number | undefined` - 当前 Socket 连接状态 code。 可与 CONNECTING、OPEN、CLOSING、CLOSED 常量比较。 如果因为参数错误等原因导致豆包客户端没有成功创建连接，则为 undefined
+• **send**: `(params: SocketTaskSendParams) => void` - 通过 WebSocket 连接发送数据。 该方法只发起发送动作，不返回发送结果。建议在 readyState === SocketTask.OPEN 或收到 onOpen 事件后调用；如果连接未就绪、数据编码失败或发送失败， 会触发 onError
+• **close**: `(params?: SocketTaskCloseParams) => void` - 关闭 WebSocket 连接。 调用后会发起关闭动作，并把 readyState 置为 SocketTask.CLOSING。 最终关闭完成时触发 onClose；关闭动作失败时触发 onError
+• **onOpen**: `(callback: (event: SocketTaskOpenEvent) => void) => void` - 监听 WebSocket 连接服务器成功的事件。 可以注册多个回调。连接成功后触发回调，并携带握手响应 Header、协议类型等信息。 通常应在该回调中或之后调用 send
+• **onClose**: `(callback: (event: SocketTaskCloseEvent) => void) => void` - 监听 WebSocket 与服务器连接断开的事件。 主动关闭、服务端关闭、连接被回收都可能触发该回调。 回调触发后当前任务已经结束，不应继续使用
+• **onMessage**: `(callback: (event: SocketTaskMessageEvent) => void) => void` - 监听 WebSocket 接收到服务器发送信息的事件。 服务端每下发一条消息都会触发一次回调。消息内容通过 event.data 返回， 类型可能是 string 或 ArrayBuffer
+• **onError**: `(callback: (event: SocketTaskErrorEvent) => void) => void` - 监听 WebSocket 发生错误的事件。 连接创建、发送、关闭或 WebSocket 通道出现异常时触发。 该回调只表示发生错误，不等同于连接一定已经关闭；是否关闭应结合 readyState 或后续 onClose 事件判断
+
+<a id="uploadfileresult"></a>
+### UploadFileResult
+
+文件上传结果。
+
+#### Properties
+
+• **statusCode**: `number` - HTTP 状态码
+• **header**: `Record<string, string>` - HTTP 响应头
+• **data?**: `string` - 服务器返回的数据
+
+<a id="uploadfileparams"></a>
+### UploadFileParams
+
+文件上传参数。
+
+#### Properties
+
+• **url**: `string` - 开发者服务器地址，需为完整的 HTTP/HTTPS URL，并通过豆包配置的上传域名白名单校验
+• **filePath**: `string` - 要上传文件资源的本地路径
+• **name**: `string` - 文件对应的 form field name/key，服务端通过该 key 获取文件内容；multipart filename 使用 filePath 的 basename
+• **header?**: `Record<string, string>` - HTTP 请求 Header。referer、user-agent、content-type 等由豆包客户端管理的字段不会被业务覆盖
+• **formData?**: `Record<string, unknown>` - 额外的 form-data 字段。对象或数组值会按 JSON 字符串传递
+• **timeout?**: `number` - 超时时间，单位 ms；不传时使用豆包客户端的默认超时配置
+• **enableProfile?**: `false` - 是否返回网络 profile。豆包当前仅支持 false
+
+<a id="uploadtask"></a>
+### UploadTask
+
+通过 uploadFile 获取的文件上传任务实例。
+
+#### Properties
+
+• **abort**: `() => void` - 中断当前上传任务。 中断成功后上传 Promise 会 reject；任务已经结束时调用无副作用
+• **onProgressUpdate**: `(callback: (event: UploadTaskProgressUpdateEvent) => void) => void` - 监听上传进度变化。 同一个任务可以注册多个回调，每次收到豆包客户端的进度事件时依次调用
+• **offProgressUpdate**: `(callback?: (event: UploadTaskProgressUpdateEvent) => void) => void` - 取消监听上传进度变化。 传入 callback 时只移除该回调；不传 callback 时移除当前任务的全部进度监听
+• **onHeadersReceived**: `(callback: (event: UploadTaskHeadersReceivedEvent) => void) => void` - 监听 HTTP Response Header 事件。 同一个任务可以注册多个回调，豆包客户端收到上传响应头时依次调用
+• **offHeadersReceived**: `(callback?: (event: UploadTaskHeadersReceivedEvent) => void) => void` - 取消监听 HTTP Response Header 事件。 传入 callback 时只移除该回调；不传 callback 时移除当前任务的全部 Header 监听
+
+<a id="uploadtaskprogressupdateevent"></a>
+### UploadTaskProgressUpdateEvent
+
+文件上传进度事件。
+
+#### Properties
+
+• **progress**: `number` - 上传进度百分比，范围 0 - 100
+• **totalBytesSent**: `number` - 已经上传的数据长度，单位 B
+• **totalBytesExpectedToSend**: `number` - 预期需要上传的数据总长度，单位 B
+
+<a id="uploadtaskheadersreceivedevent"></a>
+### UploadTaskHeadersReceivedEvent
+
+文件上传响应头事件。
+
+#### Properties
+
+• **header**: `Record<string, string>` - HTTP 响应头
+
+<a id="downloadfileresult"></a>
+### DownloadFileResult
+
+#### Properties
+
+• **statusCode**: `number` - HTTP 状态码。非 2xx 响应也会在下载写入成功后返回
+• **header**: `Record<string, string>` - HTTP 响应头
+• **tempFilePath?**: `string` - 未指定 filePath 时返回的临时文件路径
+• **filePath?**: `string` - 指定 filePath 时返回的目标文件路径
+
+<a id="downloadfileparams"></a>
+### DownloadFileParams
+
+下载文件参数。
+
+#### Properties
+
+• **url**: `string` - 下载资源地址，需为完整 HTTPS URL，并通过豆包配置的下载域名白名单校验
+• **header?**: `Record<string, string>` - 请求 Header。referer 和 user-agent 由豆包客户端管理，业务传入值不会透传
+• **timeout?**: `number` - 下载任务超时时间，单位 ms；不传或传入非正数时使用 60000，超过 300000 时按 300000 处理
+• **filePath?**: `string` - 目标文件路径，仅支持 appletfile://temp/... 或 appletfile://user/...
+
+<a id="downloadtask"></a>
+### DownloadTask
+
+下载任务。
+
+#### Properties
+
+• **abort**: `() => void` - 取消下载任务。 任务完成后调用不会产生额外效果；取消成功后下载 Promise 会 reject
+• **onProgressUpdate**: `(callback: (event: DownloadFileProgressUpdate) => void) => void` - 监听下载进度变化。 同一个回调只会注册一次，可以注册多个不同回调
+• **offProgressUpdate**: `(callback?: (event: DownloadFileProgressUpdate) => void) => void` - 取消监听下载进度变化。 传入 callback 时仅移除该回调；不传 callback 时移除当前任务的全部进度监听
+• **onHeadersReceived**: `(callback: (event: DownloadTaskHeadersReceivedEvent) => void) => void` - 监听 HTTP Response Header 事件。 同一个回调只会注册一次，可以注册多个不同回调
+• **offHeadersReceived**: `(callback?: (event: DownloadTaskHeadersReceivedEvent) => void) => void` - 取消监听 HTTP Response Header 事件。 传入 callback 时仅移除该回调；不传 callback 时移除当前任务的全部 Header 监听
+
+<a id="downloadfileprogressupdate"></a>
+### DownloadFileProgressUpdate
+
+#### Properties
+
+• **progress**: `number` - 下载进度百分比，范围 0-100
+• **totalBytesWritten**: `number` - 已经下载的数据长度，单位 Bytes
+• **totalBytesExpectedToWrite**: `number` - 预期需要下载的数据总长度，未知时可能为 -1
+
+<a id="downloadtaskheadersreceivedevent"></a>
+### DownloadTaskHeadersReceivedEvent
+
+#### Properties
+
+• **header**: `Record<string, string>` - HTTP 响应头