@doubao-dev/framework 0.0.39 → 0.0.41

package/dist/api.d.ts

@@ -47,6 +47,153 @@ export declare enum ActionDirectiveType {
     FORM_SUBMIT = "form_submit"
 }
 
+/**
+ * 向系统日历添加事件。
+ *
+ * @example
+ * ```typescript
+ * import { addPhoneCalendar } from '@doubao-dev/framework/api';
+ *
+ * const startTime = Math.floor(Date.now() / 1000) + 3600;
+ *
+ * await addPhoneCalendar({
+ *   title: '项目评审',
+ *   startTime,
+ *   endTime: startTime + 1800,
+ *   alarm: true,
+ *   alarmOffset: 300
+ * });
+ * ```
+ *
+ * @since 0.0.19
+ * @contractStatus verified | Android、iOS 均支持向系统日历写入一次性事件；成功通过 Promise resolve 空对象，失败通过 Promise reject。
+ * @platformSupport Android | supported | 写入系统日历事件；path 传入后按原值追加到日历备注。
+ * @platformSupport iOS | supported | 写入系统日历事件；path 传入后按原值追加到日历备注。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission applet | scope.addPhoneCalendar | required | Android,iOS | 需要在 manifest 中声明 scope.addPhoneCalendar，并由用户授权写入系统日历。
+ * @authorizationBehavior Android | 首次调用会依次申请应用日历授权和系统日历读写权限；用户拒绝、取消或权限被撤销后调用失败，可通过重新发起授权或系统设置恢复。
+ * @authorizationBehavior iOS | 首次调用会依次申请应用日历授权和系统日历写入权限；用户拒绝、取消或权限被撤销后调用失败，可通过重新发起授权或系统设置恢复。
+ * @precondition iOS | 设备需要存在可写入的系统日历账户。
+ * @usageNote All | startTime、endTime 使用 Unix 秒级时间戳；alarmOffset 单位为秒，Android 系统日历提醒粒度会按分钟处理。
+ * @errorCode none | - | - | Android,iOS | 当前失败通过 Promise reject 返回文本信息，未稳定返回顶层 errNo/errMsg | 根据异常信息检查授权、日历账户和时间参数
+ *
+ * @public
+ */
+export declare const addPhoneCalendar: (params: AddPhoneCalendarParams) => Promise<object>;
+
+/**
+ * 添加系统日历事件的请求参数。
+ *
+ * @public
+ */
+export declare interface AddPhoneCalendarParams {
+    /** 日历事件标题。 */
+    title: string;
+    /** 开始时间的 Unix 秒级时间戳。 */
+    startTime: number;
+    /**
+     * 是否为全天事件。
+     *
+     * @default false
+     */
+    allDay?: boolean;
+    /**
+     * 事件描述。
+     *
+     * @default -
+     */
+    description?: string;
+    /**
+     * 事件位置。
+     *
+     * @default -
+     */
+    location?: string;
+    /**
+     * 结束时间的 Unix 秒级时间戳。
+     *
+     * @default startTime
+     */
+    endTime?: number;
+    /**
+     * 是否提醒。
+     *
+     * @default true
+     */
+    alarm?: boolean;
+    /**
+     * 提前提醒时间，单位秒。0 表示开始时提醒。
+     *
+     * @default 0
+     */
+    alarmOffset?: number;
+    /**
+     * 跳转链接或客户端路由。传入后按原值追加到日历备注。
+     *
+     * @default -
+     */
+    path?: string;
+}
+
+/**
+ * 向系统日历添加重复事件。
+ *
+ * @example
+ * ```typescript
+ * import { addPhoneRepeatCalendar } from '@doubao-dev/framework/api';
+ *
+ * const startTime = Math.floor(Date.now() / 1000) + 3600;
+ *
+ * await addPhoneRepeatCalendar({
+ *   title: '每周例会',
+ *   startTime,
+ *   endTime: startTime + 1800,
+ *   repeatInterval: 'week'
+ * });
+ * ```
+ *
+ * @since 0.0.25
+ * @contractStatus verified | Android、iOS 均支持向系统日历写入重复事件；成功通过 Promise resolve 空对象，失败通过 Promise reject。
+ * @platformSupport Android | supported | 写入系统日历重复事件；repeatInterval 支持 day、week、month、year，path 行为与 addPhoneCalendar 一致。
+ * @platformSupport iOS | supported | 写入系统日历重复事件；repeatInterval 支持 day、week、month、year，path 行为与 addPhoneCalendar 一致。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission applet | scope.addPhoneCalendar | required | Android,iOS | 需要在 manifest 中声明 scope.addPhoneCalendar，并由用户授权写入系统日历。
+ * @authorizationBehavior Android | 首次调用会依次申请应用日历授权和系统日历读写权限；用户拒绝、取消或权限被撤销后调用失败，可通过重新发起授权或系统设置恢复。
+ * @authorizationBehavior iOS | 首次调用会依次申请应用日历授权和系统日历写入权限；用户拒绝、取消或权限被撤销后调用失败，可通过重新发起授权或系统设置恢复。
+ * @precondition iOS | 设备需要存在可写入的系统日历账户。
+ * @precondition All | repeatInterval 为 month 时，startTime 所在日期不能大于 28 日。
+ * @usageNote All | repeatInterval 默认 month；repeatEndTime 不传表示一直重复；startTime、endTime、repeatEndTime 使用 Unix 秒级时间戳。
+ * @errorCode none | - | - | Android,iOS | 当前失败通过 Promise reject 返回文本信息，未稳定返回顶层 errNo/errMsg | 根据异常信息检查授权、日历账户、重复周期和时间参数
+ *
+ * @public
+ */
+export declare const addPhoneRepeatCalendar: (params: AddPhoneRepeatCalendarParams) => Promise<object>;
+
+/**
+ * 添加重复日历事件的请求参数。
+ *
+ * @public
+ */
+export declare interface AddPhoneRepeatCalendarParams extends AddPhoneCalendarParams {
+    /**
+     * 重复周期。
+     *
+     * @default month
+     */
+    repeatInterval?: CalendarRepeatInterval;
+    /**
+     * 重复结束时间的 Unix 秒级时间戳。
+     *
+     * @default -
+     */
+    repeatEndTime?: number;
+}
+
+/** @public */
+export declare type AppAuthorizeStatus = 'authorized' | 'denied' | 'not determined';
+
 /** @public */
 export declare interface AppBaseInfoHost {
     /** 宿主 app 对应的 appId */
@@ -112,7 +259,24 @@ export declare type AppTheme = 'light' | 'dark';
  * @authorizationBehavior All | 调用会主动向用户发起指定 scope 的授权弹窗。用户拒绝、取消或此前已撤销授权时调用直接失败，可再次调用 `authorize` 重新发起；scope 未在应用权限声明中配置或不受支持时也会失败。
  * @precondition All | 在应用权限声明中配置需要申请的 scope。
  * @usageNote All | 授权状态可通过 `getSetting` 查询；建议在真正需要能力前再发起授权。
- * @errorCode none | - | - | Android,iOS | 用户拒绝、取消或 scope 非法等失败当前只返回文本信息，未稳定返回顶层 errNo/errMsg | 根据异常信息提示用户重新授权或检查 scope 声明
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 107,
+ *   "errMsg": "user permission denied"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 104 | invalid parameter | Android,iOS | 传入的 scope 为空或不受支持（如 scope.payment） | 检查并传入受支持的 scope 后重试。
+ * @errorCode errNo | 106 | system permission denied | Android,iOS | 对应能力的系统权限被拒绝 | 引导用户在系统设置中开启对应权限后重试。
+ * @errorCode errNo | 107 | user permission denied | Android,iOS | 用户拒绝了本次应用授权 | 说明能力用途后再次调用 `authorize` 重新发起授权。
+ * @errorCode errNo | 114 | operation cancelled | Android,iOS | 用户取消了授权弹窗 | 用户需要时可再次调用 `authorize` 重新发起授权。
+ * @errorCode errNo | 301 | network request cancelled | iOS | 授权过程中的网络请求被取消 | 确认应用和网络状态后重试。
+ * @errorCode errNo | 302 | connection timed out | iOS | 授权过程中的网络连接超时 | 检查网络连接后重试。
+ * @errorCode errNo | 303 | no network connection | iOS | 当前无可用网络连接 | 恢复网络连接后重试。
+ * @errorCode errNo | 305 | network failure | Android,iOS | 授权过程中发生其他网络错误 | 检查网络连接，稍后重试。
+ * @errorCode errNo | 112 | invalid result | iOS | 授权服务返回的数据无法解析 | 稍后重试；持续失败时反馈服务端响应异常。
+ * @platformNote iOS | 网络类失败会细分为 301/302/303/305，并可能返回 112；Android 的网络类失败统一返回 305。
  *
  * @public
  */
@@ -568,6 +732,13 @@ export declare interface BottomSheetCancelResult {
  */
 export declare type BottomSheetCancelSource = 'mask' | 'gesture' | 'hostUnavailable' | 'unknown';
 
+/**
+ * 日历重复周期。
+ *
+ * @public
+ */
+export declare type CalendarRepeatInterval = 'day' | 'week' | 'month' | 'year';
+
 /** @public */
 export declare interface CanIUseParams {
     /** 需要检测的能力标识，例如 API 名称 */
@@ -609,7 +780,15 @@ export declare interface CanIUseResult {
  *   "open": false
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息重试
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 103,
+ *   "errMsg": "feature not support"
+ * }
+ * ```
+ * @errorCode common | 102 | Android
+ * @errorCode errNo | 103 | feature not support | Android | 当前运行环境无法获取系统无障碍服务 | 在具备系统无障碍服务的设备上调用。
  *
  * @public
  */
@@ -958,7 +1137,7 @@ declare type ClientEventRegistry<Params extends object = object> = (handler: (pa
  * @usageNote All | close 已废弃，推荐使用 navigateBack 返回上一页；省略 containerID 时关闭当前栈顶页面。
  * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
  *
- * @public
+ * @internal
  */
 declare const close_2: (params?: CloseParams | undefined) => Promise<object>;
 export { close_2 as close }
@@ -1224,7 +1403,23 @@ export declare interface ConnectedBluetoothDevice {
  *   "readyState": 0
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 1501001,
+ *   "errMsg": "websocket connection limit exceeded"
+ * }
+ * ```
+ * @errorCode common | 102 | Android
+ * @errorCode common | 113 | Android,iOS
+ * @errorCode errNo | 104 | invalid parameter | Android,iOS | 创建连接时 url 为空或非 ws/wss，或调用 send 时 base64 数据非法、dataType 不支持 | 传入合法的 ws/wss url 与受支持的发送数据后重试。
+ * @errorCode errNo | 110 | API call prohibited | Android,iOS | socket url 未通过域名白名单校验 | 确认目标域名已在智能服务中配置后重试。
+ * @errorCode errNo | 116 | resource not found | Android,iOS | 对已关闭或不存在的 socketTaskId 调用 send/close | 仅在 onOpen 后、onClose 前操作连接，不要复用已关闭的连接。
+ * @errorCode errNo | 305 | network failure | Android,iOS | 建立连接、发送或关闭过程中发生网络错误 | 检查网络连接，必要时重新建立连接。
+ * @errorCode errNo | 1501001 | websocket connection limit exceeded | Android,iOS | 同一智能服务的 WebSocket 连接数超过上限 | 关闭不再使用的连接后重试。
+ * @errorCode errNo | 1501002 | websocket is not open | iOS | 连接尚未打开或已关闭时调用 send | 在收到 onOpen 事件后再发送数据。
+ * @platformNote Android | 建立连接失败统一返回 102；send 在连接未打开时返回 305 或 116。
+ * @platformNote iOS | send 在连接未打开时返回 1501002。
  *
  * @public
  */
@@ -1305,7 +1500,20 @@ export declare interface ConnectSocketParams {
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据返回的错误信息提示用户重试
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 1401003,
+ *   "errMsg": "connect wifi failed"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 104 | invalid parameter | Android,iOS | ssid 为空 | 传入非空的 ssid 后重试
+ * @errorCode errNo | 103 | feature not support | Android,iOS | 设备无可用的 Wi-Fi 能力，或 iOS 系统版本过低不支持连接 | 检查设备与系统能力，不支持时不要调用
+ * @errorCode errNo | 1401001 | wifi is not initialized | Android,iOS | 调用前未先调用 startWifi 完成初始化 | 先调用 startWifi 再连接 Wi-Fi
+ * @errorCode errNo | 115 | operation timeout | Android | 连接 Wi-Fi 超时 | 确认目标网络可用后提示用户重试
+ * @errorCode errNo | 1401003 | connect wifi failed | Android,iOS | 连接目标 Wi-Fi 失败（如密码错误、网络不可达、系统连接被拒） | 检查 ssid 与密码后提示用户重试
+ * @platformNote Android | 连接超时返回 115；iOS 未细分超时，连接失败统一归为 1401003。
  *
  * @public
  */
@@ -1362,6 +1570,22 @@ export declare type Content = {
         /** API 调用参数。 */
         arguments: object;
     };
+} | {
+    /** 模型响应提示。 */
+    type: 'responseHint';
+    /** 用户动作和模型响应建议。 */
+    data: {
+        /**
+         * 用户做了什么。
+         * @default -
+         */
+        userAction?: string;
+        /**
+         * 建议模型如何响应。
+         * @default -
+         */
+        responseGuidance?: string;
+    };
 };
 
 /**
@@ -1572,7 +1796,7 @@ export declare function createInnerAudioContext(): InnerAudioContext;
  *   "logId": "20260519xxxx"
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无稳定的顶层 errNo/errMsg；调用失败时 Promise reject，业务错误（errNo、errMsg、errLogId）在错误对象的 data 字段 | 通过 catch 捕获并读取 e.data 排查
+ * @errorCode common | 102 | Android,iOS
  * @knownIssue All | 失败结果不会作为 await 的返回值，需通过 catch 捕获并从错误对象的 data 字段读取 errNo、errMsg、errLogId。
  *
  * @public
@@ -1668,7 +1892,17 @@ export declare interface CreateSignOrderSuccessResult {
  *   "expiresIn": 3600
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 104,
+ *   "errMsg": "invalid parameter"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 104 | invalid parameter | Android,iOS | taskType 不是 remote（如传入 local） | 传入 remote 任务类型后重试。
+ * @errorCode errNo | 112 | invalid result | Android,iOS | 远端任务创建成功但返回数据为空或缺少 taskId | 稍后重试；持续失败时反馈服务端响应异常。
+ * @platformNote All | taskType 非 remote 返回 104；远端返回数据为空或缺少 taskId 返回 112；其他失败统一返回 102。
  *
  * @public
  */
@@ -1789,7 +2023,7 @@ export declare type DeviceOrientation = 'portrait' | 'landscape';
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息重试
+ * @errorCode common | 102 | Android,iOS
  *
  * @public
  */
@@ -1800,6 +2034,7 @@ export declare const disableUserScreenRecord: (params?: {} | undefined) => Promi
  *
  * @param params - 动作描述、预期行为及工具调用约束参数。
  * @returns 返回一个 Promise，在动作指令成功下发时解析。
+ * @deprecated 使用 {@link sendFollowUpMessage} 发送后续消息。
  * @remarks
  * 适用于卡片交互后向模型补充结构化动作上下文，例如按钮点击、选项选择或表单提交。
  * `getWidgetInstanceId` 仅在卡片环境中有效，在智能服务页面中会返回 `undefined`。如果需要在页面中调用，
@@ -1829,9 +2064,18 @@ export declare const disableUserScreenRecord: (params?: {} | undefined) => Promi
  * @precondition Android | 在卡片或会话环境中调用，需传入有效的 widgetInstanceId。
  * @precondition iOS | 在卡片或会话环境中调用，需传入有效的 widgetInstanceId。
  * @usageNote All | 请在卡片交互（按钮点击、选项选择、表单提交）后调用，向模型补充结构化动作上下文。
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 116,
+ *   "errMsg": "resource not found"
+ * }
+ * ```
+ * @errorCode errNo | 103 | feature not support | Android,iOS | 当前运行环境未接入消息下发能力（宿主消息依赖或消息服务缺失） | 请在支持消息下发的豆包环境中调用。
+ * @errorCode errNo | 116 | resource not found | Android,iOS | 依据 widgetInstanceId 找不到对应会话 | 确认 widgetInstanceId 有效且处于会话环境后重试。
+ * @platformNote All | 找不到会话返回 116；宿主消息依赖或消息服务缺失返回 103。
  *
- * @public
+ * @internal
  */
 export declare const dispatchActionDirective: (params: DispatchActionDirectiveParams) => Promise<object>;
 
@@ -1898,6 +2142,167 @@ export declare interface DoubaoAppAccountInfo {
     version: string;
 }
 
+/**
+ * 下载文件，并返回可取消、可监听进度的 {@link DownloadTask}。
+ *
+ * @summary 下载文件。
+ * @param params 下载参数，字段见 {@link DownloadFileParams}。
+ * @returns 下载任务。
+ *
+ * @remarks
+ * - 下载使用 GET 请求。
+ * - HTTP 传输完成且文件写入成功后，无论 statusCode 是 2xx、4xx 还是 5xx，Promise 都会 resolve。
+ * - 域名校验失败、路径非法、超时、取消、网络异常、写入失败会使 Promise reject。
+ *
+ * @example
+ * ```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);
+ * });
+ * ```
+ *
+ * @since 0.0.40
+ * @contractStatus verified | Android、iOS 均支持 HTTPS GET 下载、域名校验、临时或用户目录写入、超时、取消及进度和响应头监听。
+ * @platformSupport Android | supported | 支持 HTTPS GET 下载、域名白名单校验、临时或用户目录写入、超时、取消及任务事件监听。
+ * @platformSupport iOS | supported | 支持 HTTPS GET 下载、域名白名单校验、临时或用户目录写入、超时、取消及任务事件监听。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition All | 下载地址需通过宿主侧下载域名白名单校验，单个文件不得超过 200 MB，单个智能服务同时最多执行 10 个下载任务；指定 filePath 时仅支持临时目录或用户目录。
+ * @usageNote All | 未指定 filePath 时文件写入临时目录，并通过 Promise resolve 结果的 tempFilePath 返回；临时文件的生命周期由宿主管理。
+ * @usageNote All | 不跟随 HTTP 重定向，3xx 响应使 Promise reject；4xx、5xx 响应在文件写入成功后仍使 Promise resolve。
+ * @resultExample
+ * ```json
+ * {
+ *   "statusCode": 200,
+ *   "header": {
+ *     "content-type": "application/pdf"
+ *   },
+ *   "tempFilePath": "appletfile://temp/report.pdf"
+ * }
+ * ```
+ * @errorCode none | - | - | Android,iOS | 下载失败会使 Promise reject，当前不提供稳定的 API 专属错误码 | 根据错误信息检查 URL、域名白名单、重定向、并发任务数、文件路径、文件大小和网络状态后重试
+ *
+ * @public
+ */
+export declare function downloadFile(params: DownloadFileParams): DownloadTask;
+
+/**
+ * 下载文件参数。
+ *
+ * @public
+ */
+export declare interface DownloadFileParams {
+    /** 下载资源地址，需为完整 HTTPS URL，并通过宿主侧下载域名白名单校验。 */
+    url: string;
+    /**
+     * 请求 Header。`referer` 和 `user-agent` 由宿主管控，业务传入值不会透传。
+     *
+     * @default -
+     */
+    header?: Record<string, string>;
+    /**
+     * 下载任务超时时间，单位 ms；不传或传入非正数时使用 60000，超过 300000 时按 300000 处理。
+     *
+     * @default 60000
+     * @constraint 有效范围为 1-300000
+     */
+    timeout?: number;
+    /**
+     * 目标文件路径，仅支持 `appletfile://temp/...` 或 `appletfile://user/...`。
+     *
+     * @default 由系统创建临时下载文件
+     */
+    filePath?: string;
+}
+
+/** @public */
+export declare interface DownloadFileProgressUpdate {
+    /** 下载进度百分比，范围 0-100。 */
+    progress: number;
+    /** 已经下载的数据长度，单位 Bytes。 */
+    totalBytesWritten: number;
+    /** 预期需要下载的数据总长度，未知时可能为 -1。 */
+    totalBytesExpectedToWrite: number;
+}
+
+/** @public */
+export declare interface DownloadFileResult {
+    /** HTTP 状态码。非 2xx 响应也会在下载写入成功后返回。 */
+    statusCode: number;
+    /** HTTP 响应头。 */
+    header: Record<string, string>;
+    /** 未指定 `filePath` 时返回的临时文件路径。 */
+    tempFilePath?: string;
+    /** 指定 `filePath` 时返回的目标文件路径。 */
+    filePath?: string;
+}
+
+/**
+ * 下载任务。
+ *
+ * @public
+ */
+export declare interface DownloadTask extends Promise<DownloadFileResult> {
+    /**
+     * 取消下载任务。
+     *
+     * 任务完成后调用不会产生额外效果；取消成功后下载 Promise 会 reject。
+     */
+    abort: () => void;
+    /**
+     * 监听下载进度变化。
+     *
+     * 同一个回调只会注册一次，可以注册多个不同回调。
+     */
+    onProgressUpdate: (callback: (event: DownloadFileProgressUpdate) => void) => void;
+    /**
+     * 取消监听下载进度变化。
+     *
+     * 传入 callback 时仅移除该回调；不传 callback 时移除当前任务的全部进度监听。
+     */
+    offProgressUpdate: (callback?: (event: DownloadFileProgressUpdate) => void) => void;
+    /**
+     * 监听 HTTP Response Header 事件。
+     *
+     * 同一个回调只会注册一次，可以注册多个不同回调。
+     */
+    onHeadersReceived: (callback: (event: DownloadTaskHeadersReceivedEvent) => void) => void;
+    /**
+     * 取消监听 HTTP Response Header 事件。
+     *
+     * 传入 callback 时仅移除该回调；不传 callback 时移除当前任务的全部 Header 监听。
+     */
+    offHeadersReceived: (callback?: (event: DownloadTaskHeadersReceivedEvent) => void) => void;
+}
+
+/** @public */
+export declare interface DownloadTaskHeadersReceivedEvent {
+    /** HTTP 响应头。 */
+    header: Record<string, string>;
+}
+
 /**
  * 允许用户录屏。
  *
@@ -1923,7 +2328,7 @@ export declare interface DoubaoAppAccountInfo {
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息重试
+ * @errorCode common | 102 | Android,iOS
  *
  * @public
  */
@@ -1949,7 +2354,7 @@ export declare const enableUserScreenRecord: (params?: {} | undefined) => Promis
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件
  * @usageNote All | 会退出当前所有页面；当 navigateBack 已无法继续返回时，使用 exitApp 退出智能服务。
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorCode common | 102 | Android,iOS
  *
  * @public
  */
@@ -2051,9 +2456,9 @@ export declare interface FileSystemManager {
     readFile: (params: ReadFileParams) => Promise<ReadFileResult>;
     /** 读取文件内容（同步）；返回 {@link ReadFileResult}，其中 data 按 encoding 为 UTF-8 或 Base64 字符串。 */
     readFileSync: (params: ReadFileParams) => ReadFileResult;
-    /** 写入文件内容（异步）。文件不存在则创建，已存在则覆盖；父目录不存在时失败。 */
+    /** 写入文件内容（异步）。文件和父目录不存在则创建，文件已存在则覆盖。 */
     writeFile: (params: WriteFileParams) => Promise<void>;
-    /** 写入文件内容（同步）。文件不存在则创建，已存在则覆盖；父目录不存在时抛出异常。 */
+    /** 写入文件内容（同步）。文件和父目录不存在则创建，文件已存在则覆盖。 */
     writeFileSync: (params: WriteFileParams) => void;
     /** 在文件末尾追加内容（异步）。文件不存在则创建，不会覆盖已有内容。 */
     appendFile: (params: AppendFileParams) => Promise<void>;
@@ -2140,7 +2545,7 @@ export declare interface FileSystemManager {
  *   }
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认智能服务运行环境后重试
+ * @errorCode common | 102 | Android
  *
  * @public
  */
@@ -2189,12 +2594,90 @@ export declare interface GetAccountInfoResult {
  *   }
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认智能服务运行环境后重试
+ * @errorCode common | 102 | Android
  *
  * @public
  */
 export declare function getAccountInfoSync(params?: {}): GetAccountInfoResult;
 
+/**
+ * 获取宿主应用的系统授权设置。
+ *
+ * 调用只读取当前系统授权状态，不会申请权限或触发系统授权弹窗。状态字段固定返回
+ * `authorized`、`denied` 或 `not determined`。
+ *
+ * @returns 返回宿主应用相册、蓝牙、摄像头、定位、麦克风、通知和日历权限状态。
+ * @example
+ * ```typescript
+ * import { getAppAuthorizeSetting } from '@doubao-dev/framework/api';
+ *
+ * const result = getAppAuthorizeSetting();
+ * console.log(result.cameraAuthorized, result.microphoneAuthorized);
+ * console.log(result.notificationAuthorized, result.locationReducedAccuracy);
+ * ```
+ *
+ * @since 0.0.40
+ * @contractStatus verified | Android 与 iOS 均同步返回固定 11 个字段；除 locationReducedAccuracy 为 boolean 外，其余授权状态字段均限定为 authorized、denied 或 not determined，调用不会触发权限申请。
+ * @platformSupport Android | supported | 支持同步读取宿主应用授权状态。
+ * @platformSupport iOS | supported | 支持同步读取宿主应用授权状态。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition All | 无额外前置条件
+ * @usageNote All | 本接口查询宿主应用权限，不等同于查询当前智能服务 scope 授权。
+ * @usageNote iOS | SDK 首次完成通知设置异步预热前，或应用重新激活后的刷新尚未完成时，四个通知字段可能仍为旧值或 not determined。
+ * @resultExample
+ * ```json
+ * {
+ *   "albumAuthorized": "authorized",
+ *   "bluetoothAuthorized": "denied",
+ *   "cameraAuthorized": "authorized",
+ *   "locationAuthorized": "authorized",
+ *   "locationReducedAccuracy": false,
+ *   "microphoneAuthorized": "authorized",
+ *   "notificationAuthorized": "authorized",
+ *   "notificationAlertAuthorized": "authorized",
+ *   "notificationBadgeAuthorized": "denied",
+ *   "notificationSoundAuthorized": "authorized",
+ *   "phoneCalendarAuthorized": "not determined"
+ * }
+ * ```
+ * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @platformNote Android | albumAuthorized 和通知分项固定返回 not determined，locationReducedAccuracy 固定返回 false 且不表示实际定位精度
+ * @platformNote Android | bluetoothAuthorized、cameraAuthorized、locationAuthorized、microphoneAuthorized、notificationAuthorized 和 phoneCalendarAuthorized 不区分尚未申请和已经拒绝，两种情况均返回 denied
+ * @platformNote Android | locationAuthorized 在粗略或精确定位任一权限已授权时返回 authorized；phoneCalendarAuthorized 仅在读、写日历权限均授权时返回 authorized
+ * @platformNote iOS | 相册 limited 映射为 authorized，通知 provisional 和 ephemeral 映射为 authorized
+ *
+ * @public
+ */
+export declare const getAppAuthorizeSetting: (params?: {} | undefined) => GetAppAuthorizeSettingResult;
+
+/** @public */
+export declare interface GetAppAuthorizeSettingResult {
+    /** 相册授权状态；Android 固定返回 not determined */
+    albumAuthorized: AppAuthorizeStatus;
+    /** 蓝牙授权状态 */
+    bluetoothAuthorized: AppAuthorizeStatus;
+    /** 摄像头授权状态 */
+    cameraAuthorized: AppAuthorizeStatus;
+    /** 定位授权状态 */
+    locationAuthorized: AppAuthorizeStatus;
+    /** 是否只能使用模糊定位；仅在 iOS 且定位已授权时具有精度含义，Android 固定返回 false */
+    locationReducedAccuracy: boolean;
+    /** 麦克风授权状态 */
+    microphoneAuthorized: AppAuthorizeStatus;
+    /** 通知总授权状态 */
+    notificationAuthorized: AppAuthorizeStatus;
+    /** 通知提醒授权状态；Android 固定返回 not determined */
+    notificationAlertAuthorized: AppAuthorizeStatus;
+    /** 通知角标授权状态；Android 固定返回 not determined */
+    notificationBadgeAuthorized: AppAuthorizeStatus;
+    /** 通知声音授权状态；Android 固定返回 not determined */
+    notificationSoundAuthorized: AppAuthorizeStatus;
+    /** 系统日历授权状态 */
+    phoneCalendarAuthorized: AppAuthorizeStatus;
+}
+
 /**
  * 获取应用基础信息。
  *
@@ -2381,7 +2864,7 @@ export declare function getBackgroundAudioManager(): BackgroundAudioManager;
  *   "level": 82
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息重试
+ * @errorCode common | 102 | Android
  *
  * @public
  */
@@ -2852,7 +3335,15 @@ export declare interface GetBluetoothDevicesResult {
  *   "data": "hello doubao"
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认豆包是否提供剪贴板能力
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 103,
+ *   "errMsg": "feature not support"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 103 | feature not support | Android,iOS | 当前豆包版本或运行环境未提供剪贴板读取能力 | 在支持剪贴板能力的豆包版本中调用。
  *
  * @public
  */
@@ -2969,7 +3460,26 @@ export declare interface GetConnectedBluetoothDevicesResult {
  *   }
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据返回的错误信息（如未连接、无权限）提示用户
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 1401002,
+ *   "errMsg": "wifi is not connected"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 1401001 | wifi is not initialized | Android,iOS | 调用前未先调用 startWifi 完成初始化 | 先调用 startWifi 再获取已连接 Wi-Fi
+ * @errorCode errNo | 1401002 | wifi is not connected | Android,iOS | 当前未连接 Wi-Fi 或无法读取已连接 Wi-Fi 信息 | 确认设备已连接 Wi-Fi 后重试
+ * @errorCode errNo | 106 | system permission denied | iOS | 系统定位服务未开启，无法读取 Wi-Fi 信息 | 引导用户在系统设置中开启定位服务
+ * @errorCode errNo | 107 | user permission denied | iOS | 用户未授予定位权限或未开启精确定位 | 引导用户授予定位权限并开启精确定位
+ * @errorCode errNo | 114 | operation cancelled | iOS | 用户取消了位置权限授权弹窗 | 用户需要时可再次触发授权后重试
+ * @errorCode errNo | 301 | network request cancelled | iOS | 位置授权过程中的网络请求被取消 | 确认应用和网络状态后重试
+ * @errorCode errNo | 302 | connection timed out | iOS | 位置授权过程中的网络连接超时 | 检查网络连接后重试
+ * @errorCode errNo | 303 | no network connection | iOS | 当前无可用网络连接 | 恢复网络连接后重试
+ * @errorCode errNo | 305 | network failure | iOS | 位置授权过程中发生其他网络错误 | 检查网络连接，稍后重试
+ * @errorCode errNo | 112 | invalid result | iOS | 位置授权服务返回的数据无法解析 | 稍后重试；持续失败时反馈服务端响应异常
+ * @platformNote Android | 未连接或因缺少定位权限无法读取时统一返回 1401002；未初始化返回 1401001。
+ * @platformNote iOS | 读取前会发起位置权限授权，可返回 106/107 及授权网络类失败（301/302/303/305/112）；读取阶段未连接返回 1401002。
  *
  * @public
  */
@@ -3171,7 +3681,21 @@ export declare interface GetFileInfoResult {
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件，直接调用 getFileSystemManager 获取管理器实例后再调用其方法
  * @usageNote All | readFile、readFileSync 省略 encoding 时默认返回 Base64 字符串，writeFile、appendFile 省略 encoding 时默认按 UTF-8 写入；需要明确编码时请显式传入 encoding。
- * @errorCode none | - | - | Android,iOS | 文件操作失败时对应方法会 reject 或抛出异常，错误信息通过 errMsg 描述，当前不提供稳定的业务错误码 | 根据 errMsg 检查路径、权限与参数后重试
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 203,
+ *   "errMsg": "file does not exist"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode common | 103 | Android
+ * @errorCode common | 104 | Android,iOS
+ * @errorCode errNo | 203 | file does not exist | Android,iOS | readFile、stat、getFileInfo、copyFile、rename、truncate、unlink、rmdir、removeSavedFile、unzip 等操作的目标文件或目录不存在 | 确认路径存在或先创建后重试。
+ * @errorCode errNo | 213 | invalid file path | Android,iOS | 传入的路径不是合法的沙箱内 appletfile 路径，或试图越过沙箱根目录访问 | 使用应用沙箱内的合法本地路径后重试。
+ * @errorCode errNo | 208 | total size limit exceeded | Android,iOS | readFile、writeFile、appendFile、copyFile 时单次读写超过单文件大小上限，或写入后超出沙箱存储配额 | 减小单次读写数据量或清理已保存文件后重试。
+ * @errorCode errNo | 1901001 | target is a directory | Android,iOS | 对目录执行了仅适用于文件的操作（如 readFile、writeFile、appendFile、copyFile、truncate、getFileInfo、unzip 的源文件），或 rmdir 删除非空目录时未开启 recursive | 改为对文件操作，或删除目录时开启 recursive。
+ * @errorCode errNo | 1901002 | target is not a directory | Android,iOS | 对文件执行了仅适用于目录的操作（如 readdir），或 mkdir 目标已存在同名文件、unzip 的 targetPath 不是目录 | 确认目标为目录后重试。
  * @public
  */
 export declare function getFileSystemManager(): FileSystemManager;
@@ -3305,7 +3829,19 @@ export declare interface GetImageInfoResult {
  *   "accuracy": 15
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息提示用户检查授权和系统定位服务
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 107,
+ *   "errMsg": "user permission denied"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode common | 116 | Android
+ * @errorCode errNo | 106 | system permission denied | Android,iOS | 系统定位权限被拒绝或系统定位服务不可用 | 引导用户在系统设置中开启定位服务与权限后重试
+ * @errorCode errNo | 107 | user permission denied | Android,iOS | 用户拒绝了应用位置授权（scope.userLocation） | 调用 authorize 重新发起应用授权后重试
+ * @platformNote Android | 用户拒绝应用授权返回 107、系统权限被拒返回 106；定位失败等其他失败统一返回 102。
+ * @platformNote iOS | 应用授权或系统权限被拒返回 107/106；其他失败（含非法 scope）统一返回 102。
  * @platformNote iOS | mode 为 1 时按高精度模式处理
  *
  * @public
@@ -3441,7 +3977,9 @@ export declare const getMenuButtonBoundingClientRect: () => MenuButtonBoundingCl
  *   "hasSystemProxy": false
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息重试
+ * @errorCode common | 102 | Android
+ * @platformNote Android | 正常场景稳定返回网络类型；失败时返回 102。
+ * @platformNote iOS | 始终成功返回网络类型，无失败分支。
  *
  * @public
  */
@@ -3532,8 +4070,18 @@ export declare interface GetNetworkTypeResult {
  *   "logId": "20260519xxxx"
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无稳定的顶层 errNo/errMsg；调用失败时 Promise reject，业务错误（errNo、errMsg、errLogId）在错误对象的 data 字段 | 通过 catch 捕获并读取 e.data 排查
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 114,
+ *   "errMsg": "operation cancelled"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode common | 103 | Android,iOS
+ * @errorCode errNo | 114 | operation cancelled | Android | 用户在收银台中取消了支付操作 | 用户需要时可再次调用 `getOrderPayment` 重新拉起收银台。
  * @platformNote Android | 需在前台可见的 Activity 中调用，应用退至后台或无有效页面时会返回失败。
+ * @platformNote Android | 用户主动取消支付时返回顶层 errNo 114（operation cancelled）；iOS 在该场景不返回顶层专属 errNo。
  *
  * @public
  */
@@ -3605,8 +4153,18 @@ export declare interface GetOrderPaymentResult {
  *   "logId": "20260519xxxx"
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无稳定的顶层 errNo/errMsg；调用失败时 Promise reject，业务错误（errNo、errMsg、errLogId）在错误对象的 data 字段 | 通过 catch 捕获并读取 e.data 排查
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 114,
+ *   "errMsg": "operation cancelled"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode common | 103 | Android,iOS
+ * @errorCode errNo | 114 | operation cancelled | Android | 用户在收银台中取消了支付操作 | 用户需要时可再次调用 `getOrderPaymentWithSign` 重新拉起收银台。
  * @platformNote Android | 需在前台可见的 Activity 中调用，应用退至后台或无有效页面时会返回失败。
+ * @platformNote Android | 用户主动取消支付时返回顶层 errNo 114（operation cancelled）；iOS 在该场景不返回顶层专属 errNo。
  *
  * @public
  */
@@ -3712,7 +4270,8 @@ export declare const getPackageInfoSync: () => GetPackageInfoResult;
  *   "needAuthorization": false
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorCode common | 102 | Android,iOS
+ * @platformNote All | 该 API 无专属错误码，失败时统一返回 102。
  *
  * @public
  */
@@ -3858,7 +4417,7 @@ export declare interface GetSavedFileListResult {
  *   "value": 0.6
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | Android 根据异常信息重试，iOS 暂不支持该 API
+ * @errorCode common | 102 | Android
  *
  * @public
  */
@@ -3888,8 +4447,7 @@ export declare interface GetScreenBrightnessResult {
  * ```
  *
  * @since 0.0.36
- * @contractStatus conflict | withSubscriptions 公开可传 true，但豆包 Android、iOS 当前不支持订阅模板，传入 true 会失败。
- * @contractMismatch blocking | parameter | withSubscriptions | Android,iOS | withSubscriptions 为 true 时一并返回订阅消息设置 | 传入 true 时调用直接失败，只有默认的 false 可成功返回授权设置 | 依赖订阅设置的调用无法成功 | packages/open-api/src/basic/setting.ts; ai-sdk/android/ai-sdk/src/main/java/com/bytedance/ai/bridge/method/authorize; ai-sdk/ios/AISDK/Sources/JSBridge/Methods/Auth/AIBridgeGetSettingMethod.swift | 补齐豆包订阅模板设置查询，或从公开参数中移除 withSubscriptions
+ * @contractStatus verified | withSubscriptions 当前仅允许 false，Android、iOS 均支持返回授权设置。
  * @platformSupport Android | supported | 支持获取用户的应用授权设置。
  * @platformSupport iOS | supported | 支持获取用户的应用授权设置。
  * @platformSupport PC | unsupported | 当前未提供该平台实现。
@@ -3906,7 +4464,17 @@ export declare interface GetScreenBrightnessResult {
  *   }
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 传入 withSubscriptions: true 等失败当前只返回文本信息，未稳定返回顶层 errNo/errMsg | 不要传入 withSubscriptions: true
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 103,
+ *   "errMsg": "feature not support"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 103 | feature not support | Android,iOS | 传入 withSubscriptions: true，豆包当前不支持订阅消息模板 | 不要传入 withSubscriptions: true，仅使用默认的 false
+ * @errorCode errNo | 116 | resource not found | Android | 未找到当前应用对应的运行环境记录 | 确认应用已正确安装并在有效运行环境中调用后重试
+ * @platformNote iOS | iOS 不返回 errNo 116（resource not found），相应失败场景统一以 errNo 102（internal error）返回。
  *
  * @public
  */
@@ -3915,12 +4483,12 @@ export declare const getSetting: (params?: GetSettingParams | undefined) => Prom
 /** @public */
 export declare interface GetSettingParams {
     /**
-     * 是否同时获取用户订阅消息的订阅状态，默认不获取。
+     * 是否同时获取用户订阅消息的订阅状态；当前仅支持 false。
      *
      * @default false
-     * @constraint 豆包 Android、iOS 当前不支持订阅模板，传入 true 时调用会失败
+     * @constraint 豆包 Android、iOS 当前不支持订阅模板，仅支持 false
      */
-    withSubscriptions?: boolean;
+    withSubscriptions?: false;
 }
 
 /** @public */
@@ -4321,7 +4889,7 @@ export declare const getSystemInfoSync: (_params?: {}) => GetSystemInfoResult;
  *   "deviceOrientation": "portrait"
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorCode common | 102 | Android
  * @platformNote Android | wifiEnabled 表示系统 Wi-Fi 开关是否打开
  * @platformNote iOS | wifiEnabled 表示当前是否正在通过 Wi-Fi 联网
  *
@@ -4383,7 +4951,26 @@ export declare interface GetSystemSettingResult {
  *   ]
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据返回的错误信息（如未初始化、无权限）提示用户
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 1401001,
+ *   "errMsg": "wifi is not initialized"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 1401001 | wifi is not initialized | Android,iOS | 调用前未先调用 startWifi 完成初始化 | 先调用 startWifi 再获取 Wi-Fi 列表
+ * @errorCode errNo | 1401002 | wifi is not connected | iOS | iOS 仅返回当前已连接 Wi-Fi，当前未连接时读取失败 | 确认设备已连接 Wi-Fi 后重试
+ * @errorCode errNo | 106 | system permission denied | iOS | 系统定位服务未开启，无法读取 Wi-Fi 信息 | 引导用户在系统设置中开启定位服务
+ * @errorCode errNo | 107 | user permission denied | iOS | 用户未授予定位权限或未开启精确定位 | 引导用户授予定位权限并开启精确定位
+ * @errorCode errNo | 114 | operation cancelled | iOS | 用户取消了位置权限授权弹窗 | 用户需要时可再次触发授权后重试
+ * @errorCode errNo | 301 | network request cancelled | iOS | 位置授权过程中的网络请求被取消 | 确认应用和网络状态后重试
+ * @errorCode errNo | 302 | connection timed out | iOS | 位置授权过程中的网络连接超时 | 检查网络连接后重试
+ * @errorCode errNo | 303 | no network connection | iOS | 当前无可用网络连接 | 恢复网络连接后重试
+ * @errorCode errNo | 305 | network failure | iOS | 位置授权过程中发生其他网络错误 | 检查网络连接，稍后重试
+ * @errorCode errNo | 112 | invalid result | iOS | 位置授权服务返回的数据无法解析 | 稍后重试；持续失败时反馈服务端响应异常
+ * @platformNote Android | 未初始化返回 1401001；扫描列表为空不视为失败；因定位权限不足导致读取失败时返回 102。
+ * @platformNote iOS | 仅返回当前已连接 Wi-Fi，未连接返回 1401002；读取前会发起位置权限授权，可返回 106/107 及授权网络类失败（301/302/303/305/112）。
  *
  * @public
  */
@@ -4611,6 +5198,17 @@ export declare const hideLoading: (params?: HideInteractionParams | undefined) =
  * await hideToast();
  * ```
  *
+ * @since 0.0.26
+ * @contractStatus verified | 无参数、无返回字段，与 Android、iOS 实现一致。
+ * @platformSupport Android | supported | 支持隐藏当前 Toast。
+ * @platformSupport iOS | supported | 支持隐藏当前 Toast。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition All | 无额外前置条件
+ * @usageNote All | 当前没有 Toast 时调用无副作用。
+ * @errorCode common | 102 | Android
+ *
  * @public
  */
 export declare const hideToast: (params?: HideInteractionParams | undefined) => Promise<object>;
@@ -5016,7 +5614,17 @@ export declare const LoginType: {
  *   "result": true
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 112,
+ *   "errMsg": "invalid result"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 112 | invalid result | Android | 登录或隐私状态查询成功但返回数据缺失（如缺少隐私卡片或手机掩码） | 稍后重试；持续失败时反馈服务端响应异常。
+ * @platformNote Android | 状态查询成功但关键数据缺失返回 112；其他失败统一返回 102。
+ * @platformNote iOS | 失败统一返回 102。
  *
  * @public
  */
@@ -5125,7 +5733,16 @@ export declare interface MakeBluetoothPairParams {
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认设备是否支持拨号
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 104,
+ *   "errMsg": "invalid parameter"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 104 | invalid parameter | Android,iOS | phoneNumber 为空，或在 iOS 上无法拼接为有效的拨号 URL | 传入合法的电话号码后重试。
+ * @errorCode errNo | 103 | feature not support | iOS | 当前设备不支持拨打电话 | 在支持拨号的设备上调用，或提前提示用户设备不支持拨号。
  *
  * @public
  */
@@ -5198,7 +5815,7 @@ export declare interface MkdirParams {
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件
  * @usageNote All | navigateBack 只能在页面栈内返回；当前页面已是页面栈中的最后一个页面时无法继续返回，需要退出智能服务请调用 exitApp。
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorCode common | 102 | Android,iOS
  *
  * @public
  */
@@ -5235,7 +5852,15 @@ export declare interface NavigateBackParams {
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件
  * @usageNote All | url 为智能服务内的页面路径，可携带查询参数；跳转后当前页面会保留在页面栈中，可通过 navigateBack 返回。
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 104,
+ *   "errMsg": "invalid url"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 104 | invalid url | Android,iOS | url 为空或无法解析为有效的智能服务页面路径 | 检查 url 是否为合法的应用内页面路径后重试。
  *
  * @public
  */
@@ -5344,84 +5969,6 @@ export declare interface NotifyBLECharacteristicValueChangeParams {
     type?: BluetoothNotifyType;
 }
 
-/**
- * 取消注册地理位置变化回调。
- *
- * @example
- * ```typescript
- * import {
- *   offLocationChange,
- *   onLocationChange,
- *   type LocationChangeEvent
- * } from '@doubao-dev/framework/api';
- *
- * const handleLocationChange = ({ latitude, longitude }: LocationChangeEvent) => {
- *   console.log(latitude, longitude);
- * };
- *
- * onLocationChange(handleLocationChange);
- * offLocationChange(handleLocationChange);
- * ```
- * @since 0.0.32
- * @contractStatus verified | 注销指定监听和清空全部监听的行为由公开可选参数准确表达
- * @platformSupport Android | supported | 支持注销位置变化监听
- * @platformSupport iOS | supported | 支持注销位置变化监听
- * @platformSupport PC | unsupported | 暂不支持
- * @platformSupport HarmonyOS | unsupported | 暂不支持
- * @permission none | - | none | Android,iOS | 无需额外权限
- * @precondition All | 无额外前置条件
- * @usageNote All | 传入注册时使用的同一个 callback 可只取消该监听；省略 callback 会取消全部位置变化回调
- * @errorCode none | - | - | Android,iOS | 同步注销操作不产生 API 专属错误码 | 无需处理
- *
- * @public
- */
-export declare function offLocationChange(
-/**
- * 要取消的回调；省略时取消当前 API 注册的全部位置变化回调。
- *
- * @default 取消全部位置变化回调
- */
-callback?: LocationChangeListener): void;
-
-/**
- * 取消注册位置更新异常回调。
- *
- * @example
- * ```typescript
- * import {
- *   offLocationChangeError,
- *   onLocationChangeError,
- *   type LocationChangeErrorEvent
- * } from '@doubao-dev/framework/api';
- *
- * const handleLocationError = ({ errMsg, errCode }: LocationChangeErrorEvent) => {
- *   console.error(errMsg, errCode);
- * };
- *
- * onLocationChangeError(handleLocationError);
- * offLocationChangeError(handleLocationError);
- * ```
- * @since 0.0.32
- * @contractStatus verified | 注销指定监听和清空全部监听的行为由公开可选参数准确表达
- * @platformSupport Android | supported | 支持注销位置异常监听
- * @platformSupport iOS | supported | 支持注销位置异常监听
- * @platformSupport PC | unsupported | 暂不支持
- * @platformSupport HarmonyOS | unsupported | 暂不支持
- * @permission none | - | none | Android,iOS | 无需额外权限
- * @precondition All | 无额外前置条件
- * @usageNote All | 传入注册时使用的同一个 callback 可只取消该监听；省略 callback 会取消全部位置异常回调
- * @errorCode none | - | - | Android,iOS | 同步注销操作不产生 API 专属错误码 | 无需处理
- *
- * @public
- */
-export declare function offLocationChangeError(
-/**
- * 要取消的回调；省略时取消当前 API 注册的全部位置异常回调。
- *
- * @default 取消全部位置异常回调
- */
-callback?: LocationChangeErrorListener): void;
-
 /**
  * 监听加速度数据变化事件。
  *
@@ -5815,13 +6362,17 @@ export declare const onKeyboardHeightChange: ClientEventRegistry<KeyboardHeightC
 /**
  * 注册地理位置变化回调。
  *
+ * @returns 返回取消当前监听函数的函数。
+ *
  * @example
  * ```typescript
  * import { onLocationChange } from '@doubao-dev/framework/api';
  *
- * onLocationChange(({ latitude, longitude }) => {
+ * const unsubscribe = onLocationChange(({ latitude, longitude }) => {
  *   console.log(latitude, longitude);
  * });
+ *
+ * unsubscribe();
  * ```
  * @since 0.0.32
  * @contractStatus verified | 豆包 Android、iOS 成功事件均会返回必需的 latitude 和 longitude，其他字段可由公开可选类型承载
@@ -5832,7 +6383,7 @@ export declare const onKeyboardHeightChange: ClientEventRegistry<KeyboardHeightC
  * @platformSupport HarmonyOS | unsupported | 暂不支持
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件
- * @usageNote All | 建议在调用 `startLocationUpdate` 前注册；同一 callback 重复注册不会产生多个监听，不再使用时调用 `offLocationChange` 释放监听
+ * @usageNote All | 建议在调用 `startLocationUpdate` 前注册；不再使用时调用返回的取消函数释放当前监听
  * @usageNote All | 定位信息属于敏感数据，仅在业务确有需要时监听和使用；事件回调频率不固定
  * @resultExample
  * ```json
@@ -5854,18 +6405,22 @@ export declare const onKeyboardHeightChange: ClientEventRegistry<KeyboardHeightC
  *
  * @public
  */
-export declare function onLocationChange(callback: LocationChangeListener): void;
+export declare function onLocationChange(callback: LocationChangeListener): () => void;
 
 /**
  * 注册位置更新异常回调。
  *
+ * @returns 返回取消当前监听函数的函数。
+ *
  * @example
  * ```typescript
  * import { onLocationChangeError } from '@doubao-dev/framework/api';
  *
- * onLocationChangeError(({ errMsg, errCode }) => {
+ * const unsubscribe = onLocationChangeError(({ errMsg, errCode }) => {
  *   console.log(errMsg, errCode);
  * });
+ *
+ * unsubscribe();
  * ```
  * @since 0.0.32
  * @contractStatus verified | 错误信息必返、错误码可选的公开类型可准确表达双端事件
@@ -5876,7 +6431,7 @@ export declare function onLocationChange(callback: LocationChangeListener): void
  * @platformSupport HarmonyOS | unsupported | 暂不支持
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件
- * @usageNote All | 建议在调用 `startLocationUpdate` 前注册；同一 callback 重复注册不会产生多个监听，不再使用时调用 `offLocationChangeError` 释放监听
+ * @usageNote All | 建议在调用 `startLocationUpdate` 前注册；不再使用时调用返回的取消函数释放当前监听
  * @resultExample
  * ```json
  * {
@@ -5901,7 +6456,7 @@ export declare function onLocationChange(callback: LocationChangeListener): void
  *
  * @public
  */
-export declare function onLocationChangeError(callback: LocationChangeErrorListener): void;
+export declare function onLocationChangeError(callback: LocationChangeErrorListener): () => void;
 
 /**
  * 监听网络状态变化事件。
@@ -6098,73 +6653,6 @@ export declare const onUserScreenRecord: ClientEventRegistry<UserScreenRecordEve
  */
 export declare const onWifiConnected: ClientEventRegistry<WifiConnectedEvent>;
 
-/**
- * 通过 deep link 等方式打开外部应用。
- *
- * @param params - 外部应用打开参数。
- * @returns 返回一个 Promise，成功时解析为外部应用打开结果（{@link OpenAppResult}）。
- * @example
- * ```typescript
- * import { openApp } from '@doubao-dev/framework/api';
- *
- * const { status } = await openApp({
- *   uri: 'demo://detail?id=1',
- *   fallbackUrl: 'https://example.com/download'
- * });
- *
- * console.log(status);
- * ```
- *
- * @since 0.0.6
- * @contractStatus conflict | Android 已实现，iOS 未提供可调用实现。
- * @contractMismatch blocking | platform | 打开外部应用 | iOS | 通过 applet.openApp 打开外部应用并返回执行方式 status | 豆包 iOS 暂未提供该能力，调用会返回不支持 | 该 API 在豆包 iOS 无法打开外部应用 | packages/open-api/src/open/business/open-app.ts; ai-sdk/ios/AISDK/Sources/JSBridge/IDL/AbsOpenAppMethodIDL.swift | 补齐豆包 iOS applet.openApp 实现后再在该平台开放文档
- * @platformSupport Android | supported | 支持通过 deep link、应用市场或浏览器兜底打开外部应用。
- * @platformSupport iOS | unsupported | 豆包当前未实现打开外部应用能力。
- * @platformSupport PC | unsupported | 当前未提供该平台实现。
- * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
- * @permission none | - | none | Android | 无需额外权限
- * @precondition Android | 传入合法的 uri。
- * @usageNote All | 建议同时传入 fallbackUrl，当目标应用未安装、deep link 无法命中时可兜底至应用市场或浏览器。iOS 暂不支持，请勿在该平台调用。
- * @resultExample
- * ```json
- * {
- *   "status": "deep_link"
- * }
- * ```
- * @platformNote Android | 客户端会依次尝试 deep link、应用市场、浏览器，并通过 status 返回实际执行方式（deep_link、market、browser）。
- * @errorCode none | - | - | Android | 无 API 专属错误码 | 无需处理
- *
- * @public
- */
-export declare const openApp: (params: OpenAppRequest) => Promise<OpenAppResult>;
-
-/** @public */
-export declare interface OpenAppRequest {
-    /** 要打开的目标 URI，例如 `scheme://path?query`。 */
-    uri: string;
-    /**
-     * Android 上的目标应用包名，可选。
-     *
-     * @default -
-     */
-    targetPackage?: string;
-    /**
-     * deep link 失败时的兜底 URL，可选。
-     *
-     * @default -
-     */
-    fallbackUrl?: string;
-}
-
-/** @public */
-export declare interface OpenAppResult {
-    /** 客户端实际执行的打开方式。 */
-    status: OpenAppStatus;
-}
-
-/** @public */
-export declare type OpenAppStatus = 'deep_link' | 'market' | 'browser';
-
 /**
  * 打开蓝牙适配器。
  *
@@ -6296,6 +6784,26 @@ export declare interface OpenLocationParams {
  * }
  * ```
  *
+ * @since 0.0.39
+ * @contractStatus verified | withSubscriptions 当前仅允许 false，Android、iOS 均支持打开设置页并返回授权设置。
+ * @platformSupport Android | supported | 支持打开授权设置页并在关闭后返回最新授权设置。
+ * @platformSupport iOS | supported | 支持打开授权设置页并在关闭后返回最新授权设置。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition All | 无额外前置条件，不要求在用户点击事件中调用。
+ * @usageNote All | 豆包当前不支持订阅模板，不要传入 withSubscriptions: true。
+ * @resultExample
+ * ```json
+ * {
+ *   "authSetting": {
+ *     "scope.userLocation": true,
+ *     "scope.record": false
+ *   }
+ * }
+ * ```
+ * @errorCode none | - | - | Android,iOS | 传入 withSubscriptions: true 等失败当前只返回文本信息，未稳定返回顶层 errNo/errMsg | 不要传入 withSubscriptions: true
+ *
  * @public
  */
 export declare const openSetting: (params?: OpenSettingOptions | undefined) => Promise<OpenSettingResult>;
@@ -6303,9 +6811,12 @@ export declare const openSetting: (params?: OpenSettingOptions | undefined) => P
 /** @public */
 export declare interface OpenSettingOptions {
     /**
-     * 是否同时获取用户订阅消息的订阅状态，默认不获取。
+     * 是否同时获取用户订阅消息的订阅状态；当前仅支持 false。
+     *
+     * @default false
+     * @constraint 豆包 Android、iOS 当前不支持订阅模板，仅支持 false
      */
-    withSubscriptions?: boolean;
+    withSubscriptions?: false;
 }
 
 /** @public */
@@ -6367,7 +6878,24 @@ export declare interface PluginAccountInfo {
  * @precondition Android | 先完成登录，并传入登录成功返回的有效 code。
  * @precondition iOS | 先完成登录，并传入登录成功返回的有效 code。
  * @usageNote All | 仅在完成 MCP 授权登录流程后回传结果；登录成功时必须携带有效 code，回传成功后不要重复回传。
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 105,
+ *   "errMsg": "authentication fail"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 104 | invalid parameter | Android | result 为 true 但缺少有效的兑换 code | 传入业务服务端生成的有效 code 后重试。
+ * @errorCode errNo | 105 | authentication fail | Android,iOS | 登录被拒绝或兑换 code 校验未通过 | 确认业务登录状态与 code 是否有效后重试。
+ * @errorCode errNo | 112 | invalid result | Android,iOS | Token 交换服务返回的数据无法解析 | 稍后重试；持续失败时反馈服务端响应异常。
+ * @errorCode errNo | 115 | operation timeout | Android | Token 交换耗时超过限制 | 检查网络后重试。
+ * @errorCode errNo | 301 | network request cancelled | iOS | Token 交换的网络请求被取消 | 确认应用和网络状态后重试。
+ * @errorCode errNo | 302 | connection timed out | Android,iOS | Token 交换的网络连接超时 | 检查网络连接后重试。
+ * @errorCode errNo | 303 | no network connection | Android,iOS | 当前无可用网络连接 | 恢复网络连接后重试。
+ * @errorCode errNo | 305 | network failure | Android,iOS | Token 交换时发生其他网络错误 | 检查网络连接，稍后重试。
+ * @platformNote Android | 缺少有效 code 时返回 104；调用超时返回 115。
+ * @platformNote iOS | 缺少有效 code 时返回 102；网络请求被取消时返回 301，超时归类为 302。
  *
  * @public
  */
@@ -6777,7 +7305,15 @@ export declare type RecorderSampleRate = 8000 | 11025 | 12000 | 16000 | 22050 |
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件
  * @usageNote All | url 为智能服务内的页面路径，可携带查询参数；跳转会替换当前页面，不保留在页面栈中。
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 104,
+ *   "errMsg": "invalid url"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 104 | invalid url | Android,iOS | url 为空或无法解析为有效的智能服务页面路径 | 检查 url 是否为合法的应用内页面路径后重试。
  *
  * @public
  */
@@ -6804,7 +7340,15 @@ export declare const redirectTo: (params: NavigateToParams) => Promise<object>;
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件
  * @usageNote All | url 为智能服务内的页面路径，可携带查询参数；跳转会关闭现有全部页面并以目标页面作为唯一页面。
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 104,
+ *   "errMsg": "invalid url"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 104 | invalid url | Android,iOS | url 为空或无法解析为有效的智能服务页面路径 | 检查 url 是否为合法的应用内页面路径后重试。
  *
  * @public
  */
@@ -6981,7 +7525,7 @@ export declare interface RenameParams {
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件。
  * @usageNote All | 事件名与事件参数会用于数据分析，请勿写入用户隐私或敏感数据。
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorCode common | 102 | Android,iOS
  *
  * @public
  */
@@ -7046,7 +7590,22 @@ export declare interface ReportEventParams {
  *   }
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 305,
+ *   "errMsg": "network failure"
+ * }
+ * ```
+ * @errorCode common | 102 | iOS
+ * @errorCode errNo | 104 | invalid parameter | Android,iOS | url 为空、method 非法，或请求参数、请求体校验失败 | 修正 url、method 与请求参数后重试。
+ * @errorCode errNo | 110 | API call prohibited | Android,iOS | 请求 URL 未通过域名白名单校验 | 确认目标域名已在智能服务中配置后重试。
+ * @errorCode errNo | 301 | network request cancelled | iOS | 网络请求被取消 | 确认应用与网络状态后重试。
+ * @errorCode errNo | 302 | connection timed out | Android,iOS | 网络连接超时 | 检查网络连接后重试。
+ * @errorCode errNo | 303 | no network connection | Android,iOS | 当前无可用网络连接 | 恢复网络连接后重试。
+ * @errorCode errNo | 305 | network failure | Android,iOS | 发生其他网络错误 | 检查网络连接，稍后重试。
+ * @platformNote Android | 网络失败仅细分为 302（HTTP 408 超时）、303（无网络连接）与 305（其他网络错误），不返回 301；url 为空或 method 非法返回 104；命中域名管控返回 110。
+ * @platformNote iOS | 依据 NSURLError 细分网络失败：请求取消 301、连接超时 302、无网络 303、其他 305；参数或请求体校验失败返回 104；命中域名管控返回 110；其他失败统一返回 102。
  *
  * @public
  */
@@ -7099,7 +7658,7 @@ export declare type RequestMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' |
  *   "logId": "20260519xxxx"
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无稳定的顶层 errNo/errMsg；调用失败时 Promise reject，业务错误（errNo、errMsg、errLogId）在错误对象的 data 字段 | 通过 catch 捕获并读取 e.data 排查
+ * @errorCode common | 102 | Android,iOS
  * @knownIssue All | 失败结果不会作为 await 的返回值，需通过 catch 捕获并从错误对象的 data 字段读取 errNo、errMsg、errLogId。
  *
  * @public
@@ -7335,7 +7894,16 @@ export declare interface SaveImageToPhotosAlbumParams {
  *   "scanType": "QR_CODE"
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认相机权限及用户是否取消
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 103,
+ *   "errMsg": "feature not support"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 103 | feature not support | Android,iOS | 当前豆包版本或运行环境未提供扫码能力 | 在支持扫码能力的豆包版本中调用。
+ * @errorCode errNo | 112 | invalid result | iOS | 扫码成功但未返回可用的扫码结果数据 | 稍后重试；持续失败时反馈扫码结果异常。
  *
  * @public
  */
@@ -7405,13 +7973,13 @@ export declare type Scope = 'scope.userLocation' | 'scope.userFuzzyLocation' | '
 export declare type SelectedMessageFileType = 'video' | 'image' | 'file';
 
 /**
- * 以用户身份发送后续消息，触发新一轮对话或 API 调用。
+ * 以用户身份发送后续消息，触发新一轮对话、API 调用或引导模型响应。
  *
  * @param params - 要发送的后续消息内容。
- * @returns 返回一个 Promise，在消息发送成功时解析。
+ * @returns 返回一个 Promise，在消息发送请求提交后解析。
  * @remarks
- * 可在 Widget、智能服务页面或 Worker 中调用。宿主会根据调用上下文关联会话：Widget 使用其所在
- * 会话，从 Widget 打开的页面沿用该会话，其他页面和 Worker 使用主会话。
+ * 可在卡片或智能服务页面中调用，不支持在 app.ts 代码中调用。客户端会根据调用上下文关联会话：
+ * 卡片使用其所在会话，从卡片打开的页面沿用该会话，其他页面使用主会话。
  *
  * @example
  * ```typescript
@@ -7426,11 +7994,30 @@ export declare type SelectedMessageFileType = 'video' | 'image' | 'file';
  *         name: 'selectDrink',
  *         arguments: { drinkId: 'latte_001' }
  *       }
+ *     },
+ *     {
+ *       type: 'responseHint',
+ *       data: {
+ *         userAction: '用户选择了拿铁',
+ *         responseGuidance: '确认已选择拿铁，并询问是否需要调整杯型'
+ *       }
  *     }
  *   ]
  * });
  * ```
  *
+ * @since 0.0.37
+ * @contractStatus verified | 公开参数与 Android、iOS 的消息提交行为一致。
+ * @platformSupport Android | supported | 支持在卡片或智能服务页面中发送后续消息。
+ * @platformSupport iOS | supported | 支持在卡片和智能服务页面中发送后续消息。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition Android | 在卡片或智能服务页面中调用。
+ * @precondition iOS | 在卡片或智能服务页面中调用，且当前上下文已关联有效会话。
+ * @usageNote All | Promise 解析表示发送请求已提交，不表示消息已成功送达；实际发送失败不会通过该 Promise 返回。
+ * @errorCode none | - | - | Android,iOS | 调用失败时未稳定返回 API 专属错误码 | 检查 content 与调用场景后重试
+ *
  * @public
  */
 export declare const sendFollowUpMessage: (params: SendFollowUpMessageParams) => Promise<object>;
@@ -7441,7 +8028,10 @@ export declare const sendFollowUpMessage: (params: SendFollowUpMessageParams) =>
  * @public
  */
 export declare interface SendFollowUpMessageParams {
-    /** 消息内容。 */
+    /**
+     * 消息内容。
+     * @constraint 至少包含一条 text 类型且 text 不为空白的消息；第一条符合条件的消息作为本轮用户输入。
+     */
     content: Content[];
 }
 
@@ -7452,7 +8042,7 @@ export declare interface SendFollowUpMessageParams {
  *
  * @param params - 消息内容及类型。
  * @returns 返回一个 Promise，在消息成功发送时解析。
- * @deprecated 使用 {@link dispatchActionDirective} 描述用户行为并约束模型后续动作。
+ * @deprecated 使用 {@link sendFollowUpMessage} 发送后续消息。
  * @summary 以用户身份发送消息。
  * @example
  * ```typescript
@@ -7473,10 +8063,10 @@ export declare interface SendFollowUpMessageParams {
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition Android | 在卡片或页面环境中调用，由客户端自动获取页面上下文确定目标 bot。
  * @precondition iOS | 在卡片或页面环境中调用，由客户端自动获取页面上下文确定目标 bot。
- * @usageNote All | 该 API 已废弃，请改用 dispatchActionDirective 描述用户行为并约束模型后续动作。
+ * @usageNote All | 该 API 已废弃，请改用 sendFollowUpMessage 发送后续消息。
  * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
  *
- * @public
+ * @internal
  */
 export declare const sendQueryMessage: (params: SendQueryMessageParams) => Promise<object>;
 
@@ -7516,7 +8106,17 @@ export declare interface SendQueryMessageParams {
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认设备是否支持短信
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 114,
+ *   "errMsg": "operation cancelled"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 103 | feature not support | iOS | 当前设备不支持发送短信 | 在支持短信的设备上调用，或提前提示用户设备不支持短信。
+ * @errorCode errNo | 114 | operation cancelled | iOS | 用户在系统短信面板中取消了发送 | 用户需要时可再次调用 `sendSms` 重新拉起短信面板。
+ * @platformNote iOS | 拉起短信面板后用户取消返回 114、发送失败返回 102、设备不支持短信返回 103；Android 无法拉起短信应用时返回 102。
  *
  * @public
  */
@@ -7577,9 +8177,20 @@ export declare type SensorInterval = 'game' | 'ui' | 'normal';
  * @precondition Android | 无额外前置条件
  * @precondition iOS | 无额外前置条件
  * @usageNote All | 该 API 已废弃，请改用 updateModelContext 按任务或实体维度补充模型上下文。
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 103,
+ *   "errMsg": "feature not support"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 103 | feature not support | Android | 当前容器类型不支持设置全局上下文 | 请在支持的容器（页面、卡片或 Worker）环境中调用。
+ * @errorCode errNo | 104 | invalid parameter | iOS | 传入的参数结构非法，无法解析 | 检查传入的参数结构后重试。
+ * @platformNote Android | 当前容器类型不受支持返回 103；其他失败统一返回 102。
+ * @platformNote iOS | 参数结构非法返回 104；其他失败统一返回 102。
  *
- * @public
+ * @internal
  */
 export declare const setAdditionalContext: (params: SetAdditionalContextParams) => Promise<object>;
 
@@ -7683,7 +8294,16 @@ export declare interface SetBLEMTUResult {
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认豆包是否提供剪贴板能力
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 103,
+ *   "errMsg": "feature not support"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 103 | feature not support | Android,iOS | 当前豆包版本或运行环境未提供剪贴板写入能力 | 在支持剪贴板能力的豆包版本中调用。
+ * @errorCode errNo | 106 | system permission denied | Android | 写入后系统未授予剪贴板访问权限，写入未生效 | 引导用户在系统设置中开启剪贴板相关权限后重试。
  *
  * @public
  */
@@ -7717,11 +8337,12 @@ export declare interface SetClipboardDataParams {
  * @precondition All | 无额外前置条件
  * @usageNote All | 不再需要常亮时应主动将 keepScreenOn 设为 false，避免额外功耗
  * @platformNote iOS | 页面销毁后常亮状态会自动恢复
+ * @platformNote iOS | 设置常亮恒返回成功，无失败错误码
  * @resultExample
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息重试
+ * @errorCode common | 102 | Android
  *
  * @public
  */
@@ -7857,7 +8478,17 @@ export declare function setStorageSync<TData = unknown>(params: SetStorageParams
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | Android 不要调用该 API，iOS 根据返回的错误信息重试
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 1401001,
+ *   "errMsg": "wifi is not initialized"
+ * }
+ * ```
+ * @errorCode common | 102 | iOS
+ * @errorCode errNo | 103 | feature not support | Android | 该 API 为 iOS 特有，Android 调用固定失败 | 不要在 Android 调用该 API
+ * @errorCode errNo | 1401001 | wifi is not initialized | iOS | 调用前未先调用 startWifi 完成初始化 | 先调用 startWifi 再设置预设列表
+ * @platformNote Android | 固定返回 103（该能力仅 iOS）；iOS 未初始化返回 1401001，其他失败统一返回 102。
  *
  * @public
  */
@@ -7902,7 +8533,16 @@ export declare interface SetWifiListParams {
  *   "tapIndex": 0
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 114,
+ *   "errMsg": "operation cancelled"
+ * }
+ * ```
+ * @errorCode errNo | 104 | invalid parameter | Android,iOS | itemList 为空数组 | 传入至少一个菜单项后重试。
+ * @errorCode errNo | 114 | operation cancelled | Android,iOS | 用户点击 Cancel 按钮或点击蒙层关闭操作菜单 | 用户主动取消，按需静默处理。
+ * @errorCode common | 102 | Android,iOS
  *
  * @public
  */
@@ -7984,8 +8624,16 @@ export declare interface ShowActionSheetResult {
  *   "role": "agreeMain"
  * }
  * ```
- * @errorCode common | 104 | Android,iOS
- * @errorCode common | 103 | iOS
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 104,
+ *   "errMsg": "invalid parameter"
+ * }
+ * ```
+ * @errorCode errNo | 104 | invalid parameter | Android,iOS | title 或 content 为空、content 含被拦截的标签/事件属性/危险链接、buttons 数量不在 1-3 范围；iOS 还会在按钮语义重复或按钮文案为空时返回 | 修正参数后重试。
+ * @errorCode errNo | 103 | feature not support | iOS | 豆包底部弹窗能力不可用，或按钮数为 3 时当前 provider 不支持三按钮 | 降级到自定义弹窗；同场景 Android 返回 action=cancel、source=hostUnavailable 的成功结果，请一并做降级处理。
+ * @platformNote iOS | provider 不可用或不支持三按钮时返回 errNo 103 失败；Android 在 provider 不可用时返回 action=cancel、source=hostUnavailable 的成功结果，且不校验三按钮能力。
  *
  * @public
  */
@@ -8039,7 +8687,7 @@ export declare type ShowBottomSheetResult = BottomSheetButtonClickResult | Botto
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件
  * @usageNote All | loading 展示后需调用 hideLoading 手动关闭。
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorCode common | 102 | Android,iOS
  *
  * @public
  */
@@ -8088,7 +8736,7 @@ export declare interface ShowLoadingParams {
  *   "action": "confirm"
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorCode common | 102 | Android,iOS
  *
  * @public
  */
@@ -8191,7 +8839,17 @@ export declare interface ShowModalResult {
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 104,
+ *   "errMsg": "invalid parameter"
+ * }
+ * ```
+ * @errorCode errNo | 104 | invalid parameter | Android,iOS | message 为空；iOS 还会在 icon 取值非法或入参无法解析时返回（type 由前端归一化为合法值，非法 type 场景不会触发） | 修正参数后重试。
+ * @errorCode errNo | 103 | feature not support | iOS | 豆包 UIService 未实现，无法展示 Toast | 降级到其他提示方式。
+ * @errorCode common | 102 | Android
+ * @platformNote iOS | 参数校验失败统一返回 errNo 104；UIService 缺失时返回 errNo 103。Android 参数校验失败返回 errNo 104，宿主上下文缺失返回 errNo 102。
  *
  * @public
  * */
@@ -8272,8 +8930,18 @@ export declare interface ShowToastParams {
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 无稳定的顶层 errNo/errMsg；调用失败时 Promise reject，业务错误（code、errNo、errMsg、errLogId）在错误对象的 data 字段 | 通过 catch 捕获并读取 e.data 排查
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 114,
+ *   "errMsg": "operation cancelled"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode common | 103 | Android,iOS
+ * @errorCode errNo | 114 | operation cancelled | Android | 用户在签约收银台中取消了签约操作 | 用户需要时可再次调用 `sign` 重新发起签约。
  * @platformNote Android | 需在前台可见的 Activity 中调用，应用退至后台或无有效页面时会返回失败。
+ * @platformNote Android | 用户主动取消签约时返回顶层 errNo 114（operation cancelled）；iOS 在该场景不返回顶层专属 errNo。
  * @knownIssue All | 失败结果不会作为 await 的返回值，需通过 catch 捕获并从错误对象的 data 字段读取 code、errNo、errMsg、errLogId。
  *
  * @public
@@ -8594,7 +9262,15 @@ export declare interface SocketTaskSendParams {
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认设备是否支持加速度传感器
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 103,
+ *   "errMsg": "feature not support"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 103 | feature not support | Android,iOS | 当前设备不支持加速度传感器或无法注册监听 | 在具备加速度传感器的设备上调用，或提前提示用户设备不支持。
  *
  * @public
  */
@@ -8774,7 +9450,15 @@ export declare interface StartBluetoothDevicesDiscoveryParams {
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认设备是否支持罗盘传感器
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 103,
+ *   "errMsg": "feature not support"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 103 | feature not support | Android,iOS | 当前设备不支持罗盘传感器或无法注册监听 | 在具备罗盘传感器的设备上调用，或提前提示用户设备不支持。
  *
  * @public
  */
@@ -8805,7 +9489,15 @@ export declare const startCompass: (params?: {} | undefined) => Promise<object>;
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认设备是否支持方向传感器
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 103,
+ *   "errMsg": "feature not support"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 103 | feature not support | Android,iOS | 当前设备不支持方向传感器或无法注册监听 | 在具备方向传感器的设备上调用，或提前提示用户设备不支持。
  *
  * @public
  */
@@ -8851,7 +9543,15 @@ export declare interface StartDeviceMotionListeningParams {
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认设备是否支持陀螺仪传感器
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 103,
+ *   "errMsg": "feature not support"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 103 | feature not support | Android,iOS | 当前设备不支持陀螺仪传感器或无法注册监听 | 在具备陀螺仪传感器的设备上调用，或提前提示用户设备不支持。
  *
  * @public
  */
@@ -8905,7 +9605,22 @@ export declare interface StartGyroscopeParams {
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息检查授权、系统定位服务和是否重复启动
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 1700001,
+ *   "errMsg": "location permission denied"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 103 | feature not support | Android,iOS | 宿主未注册持续定位能力（location service 不可用） | 确认宿主已集成持续定位能力，不可用时不要调用
+ * @errorCode errNo | 114 | operation cancelled | Android,iOS | 启动过程中被取消（用户取消授权，或授权返回前已调用 stopLocationUpdate） | 需要时重新调用 startLocationUpdate
+ * @errorCode errNo | 118 | already exists | Android,iOS | 持续定位已启动，重复调用 startLocationUpdate | 先调用 stopLocationUpdate 再重新启动
+ * @errorCode errNo | 1700001 | location permission denied | Android,iOS | 用户拒绝应用位置授权或系统定位权限被拒 | 调用 authorize 重新发起授权并在系统设置中开启定位权限后重试
+ * @errorCode errNo | 1700002 | location network error | Android,iOS | 位置授权过程中发生网络错误 | 检查网络连接后重试
+ * @errorCode errNo | 104 | invalid parameter | iOS | 位置授权 scope 非法 | 检查应用权限声明中配置的 scope 后重试
+ * @platformNote Android | 用户拒绝授权返回 1700001、取消返回 114、授权网络失败返回 1700002；宿主未注册持续定位能力返回 103；其他失败统一返回 102。
+ * @platformNote iOS | 用户拒绝授权返回 1700001、取消返回 114、授权网络失败返回 1700002、非法 scope 返回 104；宿主未注册持续定位能力返回 103；其他失败统一返回 102。
  *
  * @public
  */
@@ -8948,7 +9663,16 @@ export declare interface StartLocationUpdateParams {
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据返回的错误信息重试
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 103,
+ *   "errMsg": "feature not support"
+ * }
+ * ```
+ * @errorCode common | 102 | Android
+ * @errorCode errNo | 103 | feature not support | Android | 设备无可用的 Wi-Fi 能力（缺少系统 Wi-Fi 服务） | 检查设备是否支持 Wi-Fi，不支持时不要调用
+ * @platformNote iOS | 初始化恒返回成功，不返回失败错误码。
  *
  * @public
  */
@@ -9198,7 +9922,16 @@ export declare const stopGyroscope: (params?: {} | undefined) => Promise<object>
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认持续定位状态后重试
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 103,
+ *   "errMsg": "feature not support"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 103 | feature not support | Android,iOS | 持续定位已启动，但宿主未注册持续定位能力（location service 不可用），无法停止 | 确认宿主已集成持续定位能力
+ * @platformNote All | 未启动或仍在授权阶段调用直接返回成功；仅在已启动后停止失败时返回错误码，其他失败统一返回 102。
  *
  * @public
  */
@@ -9228,7 +9961,7 @@ export declare function stopLocationUpdate(): Promise<LocationOperationResult>;
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据返回的错误信息重试
+ * @errorCode none | - | - | Android,iOS | 该接口双端恒返回成功，无 API 专属错误码 | 无需处理
  *
  * @public
  */
@@ -9468,7 +10201,23 @@ export declare interface UnzipParams {
  * @precondition Android | 未传 taskId 时需传 entityId；两者都不传时仅可在卡片环境调用，以便客户端补充必要信息。
  * @precondition iOS | 未传 taskId 时需传 entityId；两者都不传时仅可在卡片环境调用，以便客户端补充必要信息。
  * @usageNote All | 用于在任务或实体维度补充模型可理解的上下文，请在业务状态变化后按需调用，避免高频重复捐赠相同内容。
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 305,
+ *   "errMsg": "network failure"
+ * }
+ * ```
+ * @errorCode common | 100 | Android
+ * @errorCode common | 102 | Android
+ * @errorCode errNo | 103 | feature not support | Android | 当前容器类型不受支持，无法归类为页面、卡片或 Worker 来源 | 请在支持的容器（页面、卡片或 Worker）环境中调用。
+ * @errorCode errNo | 112 | invalid result | Android | 捐赠上下文的远端响应无法解析 | 稍后重试；持续失败时反馈服务端响应异常。
+ * @errorCode errNo | 301 | network request cancelled | iOS | 捐赠上下文的网络请求被取消 | 确认应用与网络状态后重试。
+ * @errorCode errNo | 302 | connection timed out | Android,iOS | 捐赠上下文的网络连接超时 | 检查网络连接后重试。
+ * @errorCode errNo | 303 | no network connection | Android,iOS | 当前无可用网络连接 | 恢复网络连接后重试。
+ * @errorCode errNo | 305 | network failure | Android,iOS | 捐赠上下文时发生其他网络错误 | 检查网络连接，稍后重试。
+ * @platformNote Android | 网络失败细分为连接超时 302、无网络 303、其他网络错误 305；远端响应无法解析返回 112；当前容器类型不受支持返回 103；其他失败统一返回 102，未归类的远端业务错误返回 100。
+ * @platformNote iOS | 依据网络错误细分：请求取消 301、连接超时 302、无网络 303、其他 305；不支持的调用来源仅回退处理、不作为失败。
  *
  * @public
  */
@@ -9525,7 +10274,18 @@ export declare interface UpdateModelContextParams {
  * @precondition Android | 在卡片或消息环境中调用，需传入有效的 widgetInstanceId。
  * @precondition iOS | 在卡片或消息环境中调用，需传入有效的 widgetInstanceId。
  * @usageNote All | 请在卡片交互或服务端结果回写后调用；传入的 widgetData 通常为 `JSON.stringify(viewData)`。
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 104,
+ *   "errMsg": "invalid parameter"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 103 | feature not support | Android,iOS | 当前运行环境未接入消息更新能力（宿主消息依赖或消息服务缺失） | 请在支持卡片消息更新的豆包环境中调用。
+ * @errorCode errNo | 104 | invalid parameter | Android,iOS | widgetInstanceId 或 widgetData 为空，或传入了空字符串的 widgetId | 传入非空的 widgetInstanceId、widgetData，并确保 widgetId 有效后重试。
+ * @errorCode errNo | 116 | resource not found | Android,iOS | 依据 widgetInstanceId 找不到对应消息，或依据 widgetId 找不到已注册的 Widget | 确认 widgetInstanceId 与 widgetId 有效后重试。
+ * @platformNote All | 参数为空返回 104；消息或 Widget 未找到返回 116；宿主消息依赖或消息服务缺失返回 103；其他失败统一返回 102。
  *
  * @public
  */
@@ -9556,27 +10316,83 @@ export declare interface UpdateWidgetParams {
  * @param params 上传参数，字段见 {@link UploadFileParams}。
  * @returns 当前上传任务对应的 {@link UploadTask}。
  *
- * @public
- */
-export declare function uploadFile(params: UploadFileParams): UploadTask;
-
-/**
- * 文件上传失败回调结果。
+ * @remarks
+ * `uploadFile` 会同步返回可监听、可中断的 Promise 任务对象。
+ * 建议在调用后立即注册进度和响应头监听；不再需要上传时调用 `UploadTask.abort`。
+ * @example
+ * ```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();
+ * ```
+ *
+ * @since 0.0.39
+ * @contractStatus verified | enableProfile 当前仅允许 false，Android、iOS 均支持正常发起上传。
+ * @platformSupport Android | supported | 支持文件上传、进度监听、响应头监听和中断任务。
+ * @platformSupport iOS | supported | 支持文件上传、进度监听、响应头监听和中断任务。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition All | url 需命中当前智能服务的上传域名白名单，filePath 需指向当前智能服务可访问的本地文件。
+ * @usageNote All | 上传成功时 Promise resolve，上传失败或取消时 Promise reject；任务结束或不再使用时应移除监听，必要时调用 abort。
+ * @errorCode errNo | 121999 | uploadFile:fail url is invalid | Android,iOS | url 缺失或不是有效上传地址 | 传入完整的 HTTP/HTTPS URL
+ * @errorCode errNo | 121999 | uploadFile:fail name is required | Android,iOS | name 缺失或为空 | 传入服务端接收文件所使用的 form field name
+ * @errorCode errNo | 121901 | uploadFile:fail url not in domain list | Android,iOS | url 未命中上传域名白名单 | 在智能服务配置中添加上传域名后重试
+ * @errorCode errNo | 121902 | uploadFile:fail no file exist | Android,iOS | filePath 为空、文件不存在或路径不是文件 | 使用文件 API 获取当前智能服务可访问的有效文件路径
+ * @errorCode errNo | 121905 | uploadFile:fail upload file abort | Android,iOS | 调用 UploadTask.abort 中断上传 | 按业务需要处理取消状态，无需自动重试
+ * @errorCode errNo | 121906 | uploadFile:fail file path permission denied | Android,iOS | 当前智能服务无权访问 filePath | 改用当前智能服务目录内的文件
+ * @errorCode errNo | 121920 | uploadFile:fail request time out | Android,iOS | 上传超过宿主超时时间 | 检查网络或设置合理的 timeout 后重试
+ * @errorCode errNo | 121985 | uploadFile:fail network unavailable | Android,iOS | 当前网络不可用 | 恢复网络连接后重试
+ * @errorCode errNo | 121991 | uploadFile:fail network error | Android,iOS | 上传过程中发生网络错误 | 检查网络和服务端状态后重试
+ * @errorCode errNo | 121992 | uploadFile:fail enableProfile is not supported | Android,iOS | enableProfile 设置为 true | 移除 enableProfile 或设置为 false
+ * @resultExample
+ * ```json
+ * {
+ *   "statusCode": 200,
+ *   "header": {
+ *     "content-type": "application/json"
+ *   },
+ *   "data": "{\"ok\":true}"
+ * }
+ * ```
+ * @errorExample
+ * ```json
+ * {
+ *   "errMsg": "uploadFile:fail request time out",
+ *   "errNo": 121920,
+ *   "errorCode": 121920
+ * }
+ * ```
  *
  * @public
  */
-export declare interface UploadFileFailCallbackResult {
-    /** 错误信息。 */
-    errMsg: string;
-    /** 错误码，尽量对齐抖音小程序 uploadFile 错误码。 */
-    errNo?: number;
-    /** 抖音小程序风格错误码字段。 */
-    errorCode?: number;
-    /** HTTP 状态码；请求已收到响应但被判定失败时可能存在。 */
-    statusCode?: number;
-    /** HTTP 响应头；请求已收到响应但被判定失败时可能存在。 */
-    header?: Record<string, string>;
-}
+export declare function uploadFile(params: UploadFileParams): UploadTask;
 
 /**
  * 文件上传参数。
@@ -9590,28 +10406,38 @@ export declare interface UploadFileParams {
     filePath: string;
     /** 文件对应的 form field name/key，服务端通过该 key 获取文件内容；multipart filename 使用 filePath 的 basename。 */
     name: string;
-    /** HTTP 请求 Header。`referer`、`user-agent`、`content-type` 等宿主管控字段不会被业务覆盖。 */
+    /**
+     * HTTP 请求 Header。`referer`、`user-agent`、`content-type` 等宿主管控字段不会被业务覆盖。
+     *
+     * @default -
+     */
     header?: Record<string, string>;
-    /** 额外的 form-data 字段。对象或数组值会按 JSON 字符串传递。 */
+    /**
+     * 额外的 form-data 字段。对象或数组值会按 JSON 字符串传递。
+     *
+     * @default -
+     */
     formData?: Record<string, unknown>;
-    /** 超时时间，单位 ms。 */
+    /**
+     * 超时时间，单位 ms；不传时使用宿主侧默认超时配置。
+     *
+     * @default -
+     */
     timeout?: number;
-    /** 是否返回网络 profile。当前 native upload 链路暂不支持，设置为 true 会触发 fail。 */
-    enableProfile?: boolean;
-    /** 上传成功回调。 */
-    success?: (result: UploadFileSuccessCallbackResult) => void;
-    /** 上传失败回调。 */
-    fail?: (result: UploadFileFailCallbackResult) => void;
-    /** 上传完成回调，成功或失败都会触发。 */
-    complete?: (result: UploadFileSuccessCallbackResult | UploadFileFailCallbackResult) => void;
+    /**
+     * 是否返回网络 profile。当前 native upload 链路暂不支持，仅支持 false。
+     *
+     * @default false
+     */
+    enableProfile?: false;
 }
 
 /**
- * 文件上传成功回调结果。
+ * 文件上传结果。
  *
  * @public
  */
-export declare interface UploadFileSuccessCallbackResult {
+export declare interface UploadFileResult {
     /** HTTP 状态码。 */
     statusCode: number;
     /** HTTP 响应头。 */
@@ -9625,17 +10451,37 @@ export declare interface UploadFileSuccessCallbackResult {
  *
  * @public
  */
-export declare interface UploadTask {
-    /** 中断上传任务。 */
-    abort(): void;
-    /** 监听上传进度变化。 */
-    onProgressUpdate(callback: (event: UploadTaskProgressUpdateEvent) => void): void;
-    /** 取消监听上传进度变化；不传 callback 时移除当前任务的全部进度监听。 */
-    offProgressUpdate(callback?: (event: UploadTaskProgressUpdateEvent) => void): void;
-    /** 监听 HTTP Response Header 事件。 */
-    onHeadersReceived(callback: (event: UploadTaskHeadersReceivedEvent) => void): void;
-    /** 取消监听 HTTP Response Header 事件；不传 callback 时移除当前任务的全部 Header 监听。 */
-    offHeadersReceived(callback?: (event: UploadTaskHeadersReceivedEvent) => void): void;
+export declare interface UploadTask extends Promise<UploadFileResult> {
+    /**
+     * 中断当前上传任务。
+     *
+     * 中断成功后上传 Promise 会 reject；任务已经结束时调用无副作用。
+     */
+    abort: () => void;
+    /**
+     * 监听上传进度变化。
+     *
+     * 同一个任务可以注册多个回调，每次收到宿主进度事件时依次调用。
+     */
+    onProgressUpdate: (callback: (event: UploadTaskProgressUpdateEvent) => void) => void;
+    /**
+     * 取消监听上传进度变化。
+     *
+     * 传入 callback 时只移除该回调；不传 callback 时移除当前任务的全部进度监听。
+     */
+    offProgressUpdate: (callback?: (event: UploadTaskProgressUpdateEvent) => void) => void;
+    /**
+     * 监听 HTTP Response Header 事件。
+     *
+     * 同一个任务可以注册多个回调，宿主收到上传响应头时依次调用。
+     */
+    onHeadersReceived: (callback: (event: UploadTaskHeadersReceivedEvent) => void) => void;
+    /**
+     * 取消监听 HTTP Response Header 事件。
+     *
+     * 传入 callback 时只移除该回调；不传 callback 时移除当前任务的全部 Header 监听。
+     */
+    offHeadersReceived: (callback?: (event: UploadTaskHeadersReceivedEvent) => void) => void;
 }
 
 /**
@@ -9726,7 +10572,16 @@ export declare type UserScreenRecordState = 'start' | 'stop';
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认设备是否支持震动
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 103,
+ *   "errMsg": "feature not support"
+ * }
+ * ```
+ * @errorCode errNo | 103 | feature not support | Android | Android 设备无振动器或不支持震动能力 | 提示用户当前设备不支持震动，避免依赖该能力
+ * @errorCode common | 102 | Android
+ * @platformNote iOS | 长震动恒返回成功，无失败错误码
  *
  * @public
  */
@@ -9757,7 +10612,16 @@ export declare const vibrateLong: (params?: {} | undefined) => Promise<object>;
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认设备是否支持震动
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 103,
+ *   "errMsg": "feature not support"
+ * }
+ * ```
+ * @errorCode errNo | 103 | feature not support | Android,iOS | Android 设备无振动器或不支持震动能力，或 iOS 系统版本低于 13.0 | 提示用户当前设备或系统不支持震动，避免依赖该能力
+ * @errorCode common | 102 | Android
+ * @platformNote Android | 设备不支持震动或触发震动失败时返回 102 internal error；iOS 无对应失败错误码
  *
  * @public
  */
@@ -9930,7 +10794,7 @@ export declare interface WriteBLECharacteristicValueParams {
  *
  * @remarks
  * - 如果文件不存在会自动创建；如果文件已存在则会覆盖原有内容。
- * - 父目录不存在时写入会失败，需先通过 {@link FileSystemManager.mkdir} 创建目录。
+ * - 父目录不存在时会自动创建。
  *
  * @public
  */