@doubao-dev/cli 0.0.14 → 0.0.15

package/skills/doubao-agentic-service-development/references/frontend/doubao-agentic-service-api/01-/345/237/272/347/241/200.md

@@ -13,6 +13,7 @@
 | [authorize](#authorize) | 提前向用户发起指定 scope 的应用授权。 |
 | [getPackageInfoSync](#getpackageinfosync) | 同步获取当前 package 信息。<br><br>同步 API。 |
 | [getSetting](#getsetting) | 获取用户当前的应用授权设置。 |
+| [openSetting](#opensetting) | 打开智能服务授权设置页面。 |
 
 ## API 详情
 
@@ -339,11 +340,6 @@ console.log(result.appId, result.name, result.iconSrc);
 
 获取用户当前的应用授权设置。
 
-## 使用限制
-
-> [!WARNING]
-> **Android、iOS**：传入 true 时调用直接失败，只有默认的 false 可成功返回授权设置；依赖订阅设置的调用无法成功。
-
 ## 支持版本
 
 前端库版本不低于 `0.0.36`。
@@ -381,7 +377,7 @@ getSetting(params?: GetSettingParams): Promise<GetSettingResult>
 <tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
 </thead>
 <tbody>
-<tr><td><code>withSubscriptions</code></td><td><code>boolean</code></td><td>否</td><td><code>false</code></td><td>豆包 Android、iOS 当前不支持订阅模板，传入 true 时调用会失败</td><td>是否同时获取用户订阅消息的订阅状态，默认不获取。Android、iOS：传入 true 时调用直接失败，只有默认的 false 可成功返回授权设置。</td></tr>
+<tr><td><code>withSubscriptions</code></td><td><code>false</code></td><td>否</td><td><code>false</code></td><td>豆包 Android、iOS 当前不支持订阅模板，仅支持 false</td><td>是否同时获取用户订阅消息的订阅状态；当前仅支持 false。</td></tr>
 </tbody>
 </table>
 
@@ -420,6 +416,102 @@ console.log(result.authSetting['scope.userLocation']);
 }
 ```
 
+<a id="opensetting"></a>
+### openSetting()
+
+# openSetting
+
+打开智能服务授权设置页面
+
+## 支持版本
+
+前端库版本不低于 `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>
+
+## 接入准备
+
+### 前置条件
+
+- 无额外前置条件，不要求在用户点击事件中调用
+
+## 使用说明
+
+该接口不要求在用户点击事件中调用。
+注意：当前宿主暂不支持订阅模板，传入 `withSubscriptions: true` 时会由宿主返回失败，错误信息为 `subscription templates are not supported yet`。
+
+- 豆包当前不支持订阅模板，不要传入 withSubscriptions: true。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+openSetting(params?: OpenSettingOptions): Promise<OpenSettingResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>withSubscriptions</code></td><td><code>false</code></td><td>否</td><td><code>false</code></td><td>豆包 Android、iOS 当前不支持订阅模板，仅支持 false</td><td>是否同时获取用户订阅消息的订阅状态；当前仅支持 false。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { openSetting } from '@doubao-dev/framework/api';
+
+try {
+  const result = await openSetting();
+  console.log(result.authSetting['scope.userLocation']);
+} catch (error) {
+  console.error(error);
+}
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>authSetting</code></td><td><code>AuthSetting</code></td><td>是</td><td>用户授权结果，key 为权限 scope，value 表示是否已授权</td></tr>
+<tr><td><code>subscriptionsSetting</code></td><td><code>SubscriptionsSetting</code></td><td>否</td><td>用户订阅消息设置，withSubscriptions 为 true 时才会返回</td></tr>
+<tr><td><code>subscriptionsSetting.itemSettings</code></td><td><code>Record&lt;string, SubscriptionSettingStatus&gt;</code></td><td>否</td><td>一次性订阅消息模板的订阅状态</td></tr>
+<tr><td><code>subscriptionsSetting.mainSwitch</code></td><td><code>boolean</code></td><td>否</td><td>设置页订阅消息总开关</td></tr>
+<tr><td><code>subscriptionsSetting.templateSettings</code></td><td><code>Record&lt;string, SubscriptionTemplateSetting&gt;</code></td><td>否</td><td>模板订阅状态</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "authSetting": {
+    "scope.userLocation": true,
+    "scope.record": false
+  }
+}
+```
+
 ## 相关类型
 
 <a id="doubaoappaccountinfo"></a>
@@ -491,7 +583,7 @@ console.log(result.authSetting['scope.userLocation']);
 
 #### Properties
 
-• **withSubscriptions?**: `boolean` - 是否同时获取用户订阅消息的订阅状态，默认不获取
+• **withSubscriptions?**: `false` - 是否同时获取用户订阅消息的订阅状态；当前仅支持 false
 
 <a id="authsetting"></a>
 ### AuthSetting
@@ -554,3 +646,18 @@ console.log(result.authSetting['scope.userLocation']);
 #### Type
 
 `'accept' | 'reject'`
+
+<a id="opensettingoptions"></a>
+### OpenSettingOptions
+
+#### Properties
+
+• **withSubscriptions?**: `false` - 是否同时获取用户订阅消息的订阅状态；当前仅支持 false
+
+<a id="opensettingresult"></a>
+### OpenSettingResult
+
+#### Properties
+
+• **authSetting**: `AuthSetting` - 用户授权结果，key 为权限 scope，value 表示是否已授权
+• **subscriptionsSetting?**: `SubscriptionsSetting` - 用户订阅消息设置，withSubscriptions 为 true 时才会返回

package/skills/doubao-agentic-service-development/references/frontend/doubao-agentic-service-api/02-/347/263/273/347/273/237.md

@@ -10,6 +10,7 @@
 | --- | --- |
 | [getWindowInfoSync](#getwindowinfosync) | 获取窗口信息。<br><br>同步 API。 |
 | [getSystemSetting](#getsystemsetting) | 获取设备设置。 |
+| [getAppAuthorizeSetting](#getappauthorizesetting) | 获取宿主应用的系统授权设置。 调用只读取当前系统授权状态，不会申请权限或触发系统授权弹窗。状态字段固定返回 authorized、denied 或 not determined。 |
 | [getAppBaseInfoSync](#getappbaseinfosync) | 获取应用基础信息。<br><br>同步 API。 |
 | [getWindowInfo](#getwindowinfo) | 获取窗口信息。 |
 | [getAppBaseInfo](#getappbaseinfo) | 获取应用基础信息。 |
@@ -191,6 +192,107 @@ console.log(result.wifiEnabled, result.deviceOrientation);
 - **Android**：wifiEnabled 表示系统 Wi-Fi 开关是否打开
 - **iOS**：wifiEnabled 表示当前是否正在通过 Wi-Fi 联网
 
+<a id="getappauthorizesetting"></a>
+### getAppAuthorizeSetting()
+
+# getAppAuthorizeSetting
+
+获取宿主应用的系统授权设置。
+
+调用只读取当前系统授权状态，不会申请权限或触发系统授权弹窗。状态字段固定返回
+`authorized`、`denied` 或 `not determined`。
+
+## 支持版本
+
+前端库版本不低于 `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>
+
+## 使用说明
+
+- 本接口查询宿主应用权限，不等同于查询当前小程序 scope 授权。
+- **iOS**：SDK 首次完成通知设置异步预热前，或应用重新激活后的刷新尚未完成时，四个通知字段可能仍为旧值或 not determined。
+
+## 调用方式
+
+### 同步 API
+
+```typescript
+getAppAuthorizeSetting(params?: object): GetAppAuthorizeSettingResult
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { getAppAuthorizeSetting } from '@doubao-dev/framework/api';
+
+const result = getAppAuthorizeSetting();
+console.log(result.cameraAuthorized, result.microphoneAuthorized);
+console.log(result.notificationAuthorized, result.locationReducedAccuracy);
+```
+
+## 返回值
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>albumAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>相册授权状态；Android 固定返回 not determined</td></tr>
+<tr><td><code>bluetoothAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>蓝牙授权状态</td></tr>
+<tr><td><code>cameraAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>摄像头授权状态</td></tr>
+<tr><td><code>locationAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>定位授权状态</td></tr>
+<tr><td><code>locationReducedAccuracy</code></td><td><code>boolean</code></td><td>是</td><td>是否只能使用模糊定位；仅在 iOS 且定位已授权时具有精度含义，Android 固定返回 false</td></tr>
+<tr><td><code>microphoneAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>麦克风授权状态</td></tr>
+<tr><td><code>notificationAlertAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>通知提醒授权状态；Android 固定返回 not determined</td></tr>
+<tr><td><code>notificationAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>通知总授权状态</td></tr>
+<tr><td><code>notificationBadgeAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>通知角标授权状态；Android 固定返回 not determined</td></tr>
+<tr><td><code>notificationSoundAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>通知声音授权状态；Android 固定返回 not determined</td></tr>
+<tr><td><code>phoneCalendarAuthorized</code></td><td><code>AppAuthorizeStatus</code></td><td>是</td><td>系统日历授权状态</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "albumAuthorized": "authorized",
+  "bluetoothAuthorized": "denied",
+  "cameraAuthorized": "authorized",
+  "locationAuthorized": "authorized",
+  "locationReducedAccuracy": false,
+  "microphoneAuthorized": "authorized",
+  "notificationAuthorized": "authorized",
+  "notificationAlertAuthorized": "authorized",
+  "notificationBadgeAuthorized": "denied",
+  "notificationSoundAuthorized": "authorized",
+  "phoneCalendarAuthorized": "not determined"
+}
+```
+
+## 平台差异
+
+- **Android**：albumAuthorized 和通知分项固定返回 not determined，locationReducedAccuracy 固定返回 false 且不表示实际定位精度
+- **Android**：bluetoothAuthorized、cameraAuthorized、locationAuthorized、microphoneAuthorized、notificationAuthorized 和 phoneCalendarAuthorized 不区分尚未申请和已经拒绝，两种情况均返回 denied
+- **Android**：locationAuthorized 在粗略或精确定位任一权限已授权时返回 authorized；phoneCalendarAuthorized 仅在读、写日历权限均授权时返回 authorized
+- **iOS**：相册 limited 映射为 authorized，通知 provisional 和 ephemeral 映射为 authorized
+
 <a id="getappbaseinfosync"></a>
 ### getAppBaseInfoSync()
 
@@ -862,6 +964,30 @@ console.log(result.screenWidth, result.screenHeight);
 • **wifiEnabled**: `boolean` - Wi-Fi 的系统开关
 • **deviceOrientation**: `DeviceOrientation` - 设备方向
 
+<a id="appauthorizestatus"></a>
+### AppAuthorizeStatus
+
+#### Type
+
+`'authorized' | 'denied' | 'not determined'`
+
+<a id="getappauthorizesettingresult"></a>
+### GetAppAuthorizeSettingResult
+
+#### Properties
+
+• **albumAuthorized**: `AppAuthorizeStatus` - 相册授权状态；Android 固定返回 not determined
+• **bluetoothAuthorized**: `AppAuthorizeStatus` - 蓝牙授权状态
+• **cameraAuthorized**: `AppAuthorizeStatus` - 摄像头授权状态
+• **locationAuthorized**: `AppAuthorizeStatus` - 定位授权状态
+• **locationReducedAccuracy**: `boolean` - 是否只能使用模糊定位；仅在 iOS 且定位已授权时具有精度含义，Android 固定返回 false
+• **microphoneAuthorized**: `AppAuthorizeStatus` - 麦克风授权状态
+• **notificationAuthorized**: `AppAuthorizeStatus` - 通知总授权状态
+• **notificationAlertAuthorized**: `AppAuthorizeStatus` - 通知提醒授权状态；Android 固定返回 not determined
+• **notificationBadgeAuthorized**: `AppAuthorizeStatus` - 通知角标授权状态；Android 固定返回 not determined
+• **notificationSoundAuthorized**: `AppAuthorizeStatus` - 通知声音授权状态；Android 固定返回 not determined
+• **phoneCalendarAuthorized**: `AppAuthorizeStatus` - 系统日历授权状态
+
 <a id="appbaseinfohost"></a>
 ### AppBaseInfoHost
 

package/skills/doubao-agentic-service-development/references/frontend/doubao-agentic-service-api/06-/344/272/244/344/272/222.md

@@ -10,6 +10,7 @@ Toast、Loading、Modal、ActionSheet、BottomSheet 和返回前提醒。
 | --- | --- |
 | [showModal](#showmodal) | 显示模态对话框。 |
 | [showLoading](#showloading) | 显示 loading 提示框。 |
+| [hideToast](#hidetoast) | 隐藏当前 Toast。 |
 | [hideLoading](#hideloading) | 隐藏当前 loading。 |
 | [showActionSheet](#showactionsheet) | 显示操作菜单。 |
 | [showBottomSheet](#showbottomsheet) | 显示 Native 底部弹窗。 |
@@ -163,6 +164,76 @@ await hideLoading();
 
 无返回字段。
 
+<a id="hidetoast"></a>
+### hideToast()
+
+# hideToast
+
+隐藏当前 Toast。
+
+## 支持版本
+
+前端库版本不低于 `0.0.26`。
+
+## 支持平台
+
+<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>
+
+## 使用说明
+
+- 当前没有 Toast 时调用无副作用。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+hideToast(params?: HideInteractionParams): Promise<object>
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { hideToast } from '@doubao-dev/framework/api';
+
+await hideToast();
+```
+
+## 成功返回
+
+无返回字段。
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 错误码
+
+#### 通用错误码
+
+<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>
+</tbody>
+</table>
+
 <a id="hideloading"></a>
 ### hideLoading()
 

package/skills/doubao-agentic-service-development/references/frontend/doubao-agentic-service-api/08-/347/275/221/347/273/234.md

@@ -10,6 +10,7 @@
 | --- | --- |
 | [request](#request) | 发起网络请求。 request 本身不接受泛型参数；如需业务数据类型，请读取 result.data 后再做类型收窄或断言。 |
 | [connectSocket](#connectsocket) | 创建一个 WebSocket 连接，并返回可操作该连接的 SocketTask。 该 API 会同步返回 SocketTask，但连接创建本身是异步过程。调用方应先在返回的 SocketTask 上注册事件回调，再等待 onOpen 表示连接可用。后续发送消息使用 SocketTask.send，关闭连接使用 SocketTask.close。 |
+| [uploadFile](#uploadfile) | 上传本地文件，并返回可用于监听进度和中断上传的 UploadTask。 |
 
 ## API 详情
 
@@ -237,6 +238,152 @@ socketTask.onError((event) => {
 
 - 同一智能服务内最多同时保持 5 条 WebSocket 连接，超过上限时 connectSocket 会立即同步失败并通过 SocketTask.onError 通知。
 
+<a id="uploadfile"></a>
+### uploadFile()
+
+# uploadFile
+
+上传本地文件，并返回可用于监听进度和中断上传的 UploadTask。
+
+## 支持版本
+
+前端库版本不低于 `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>
+
+## 接入准备
+
+### 前置条件
+
+- url 需命中当前智能服务的上传域名白名单，filePath 需指向当前智能服务可访问的本地文件
+
+## 使用说明
+
+`uploadFile` 会同步返回任务对象，上传结果通过 success、fail 和 complete 回调通知。
+建议在调用后立即注册进度和响应头监听；不再需要上传时调用 `UploadTask.abort`。
+
+- success 与 fail 互斥，complete 在二者之后触发；任务结束或不再使用时应移除监听，必要时调用 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>complete</code></td><td><code>(result: UploadFileSuccessCallbackResult | UploadFileFailCallbackResult) =&gt; void</code></td><td>否</td><td><code>-</code></td><td>-</td><td>上传完成回调，成功或失败都会触发。</td></tr>
+<tr><td><code>enableProfile</code></td><td><code>false</code></td><td>否</td><td><code>false</code></td><td>-</td><td>是否返回网络 profile。当前 native upload 链路暂不支持，仅支持 false。</td></tr>
+<tr><td><code>fail</code></td><td><code>(result: UploadFileFailCallbackResult) =&gt; void</code></td><td>否</td><td><code>-</code></td><td>-</td><td>上传失败回调。</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>success</code></td><td><code>(result: UploadFileSuccessCallbackResult) =&gt; void</code></td><td>否</td><td><code>-</code></td><td>-</td><td>上传成功回调。</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' },
+  success(result) {
+    console.log(result.statusCode, result.data);
+  },
+  fail(error) {
+    console.error(error.errNo, error.errMsg);
+  },
+  complete(result) {
+    console.log('upload finished', result);
+  }
+});
+
+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>abort</code></td><td><code>() =&gt; void</code></td><td>是</td><td>中断当前上传任务。<br><br>中断结果会沿用本次上传的失败与完成回调返回；任务已经结束时调用无副作用。</td></tr>
+<tr><td><code>offHeadersReceived</code></td><td><code>(callback?: (event: UploadTaskHeadersReceivedEvent) =&gt; void) =&gt; void</code></td><td>是</td><td>取消监听 HTTP Response Header 事件。<br><br>传入 callback 时只移除该回调；不传 callback 时移除当前任务的全部 Header 监听。</td></tr>
+<tr><td><code>offProgressUpdate</code></td><td><code>(callback?: (event: UploadTaskProgressUpdateEvent) =&gt; void) =&gt; void</code></td><td>是</td><td>取消监听上传进度变化。<br><br>传入 callback 时只移除该回调；不传 callback 时移除当前任务的全部进度监听。</td></tr>
+<tr><td><code>onHeadersReceived</code></td><td><code>(callback: (event: UploadTaskHeadersReceivedEvent) =&gt; void) =&gt; void</code></td><td>是</td><td>监听 HTTP Response Header 事件。<br><br>同一个任务可以注册多个回调，宿主收到上传响应头时依次调用。</td></tr>
+<tr><td><code>onProgressUpdate</code></td><td><code>(callback: (event: UploadTaskProgressUpdateEvent) =&gt; void) =&gt; void</code></td><td>是</td><td>监听上传进度变化。<br><br>同一个任务可以注册多个回调，每次收到宿主进度事件时依次调用。</td></tr>
+</tbody>
+</table>
+
+## 错误处理
+
+同步调用失败时抛出错误。错误对象和通用错误码见 [通用错误处理](./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>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="requestmethod"></a>
@@ -362,3 +509,78 @@ WebSocket 错误事件。 连接创建失败、发送失败、主动关闭失败
 • **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 发生错误的事件。 连接创建、发送、关闭或底层通道出现异常时触发。 该回调只表示发生错误，不等同于连接一定已经关闭；是否关闭应结合 readyState 或后续 onClose 事件判断
+
+<a id="uploadfilesuccesscallbackresult"></a>
+### UploadFileSuccessCallbackResult
+
+文件上传成功回调结果。
+
+#### Properties
+
+• **statusCode**: `number` - HTTP 状态码
+• **header**: `Record<string, string>` - HTTP 响应头
+• **data?**: `string` - 服务器返回的数据
+
+<a id="uploadfilefailcallbackresult"></a>
+### UploadFileFailCallbackResult
+
+文件上传失败回调结果。
+
+#### Properties
+
+• **errMsg**: `string` - 错误信息
+• **errNo?**: `number` - 错误码，尽量对齐抖音小程序 uploadFile 错误码
+• **errorCode?**: `number` - 抖音小程序风格错误码字段
+• **statusCode?**: `number` - HTTP 状态码；请求已收到响应但被判定失败时可能存在
+• **header?**: `Record<string, string>` - HTTP 响应头；请求已收到响应但被判定失败时可能存在
+
+<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="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。当前 native upload 链路暂不支持，仅支持 false
+• **success?**: `(result: UploadFileSuccessCallbackResult) => void` - 上传成功回调
+• **fail?**: `(result: UploadFileFailCallbackResult) => void` - 上传失败回调
+• **complete?**: `(result: UploadFileSuccessCallbackResult | UploadFileFailCallbackResult) => void` - 上传完成回调，成功或失败都会触发
+
+<a id="uploadtask"></a>
+### UploadTask
+
+通过 uploadFile 获取的文件上传任务实例。
+
+#### Properties
+
+• **abort**: `() => void` - 中断当前上传任务。 中断结果会沿用本次上传的失败与完成回调返回；任务已经结束时调用无副作用
+• **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 监听