@doubao-dev/framework 0.0.40 → 0.0.41

package/dist/api.d.ts

@@ -259,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
  */
@@ -763,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
  */
@@ -1378,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
  */
@@ -1459,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
  */
@@ -1516,6 +1570,22 @@ export declare type Content = {
         /** API 调用参数。 */
         arguments: object;
     };
+} | {
+    /** 模型响应提示。 */
+    type: 'responseHint';
+    /** 用户动作和模型响应建议。 */
+    data: {
+        /**
+         * 用户做了什么。
+         * @default -
+         */
+        userAction?: string;
+        /**
+         * 建议模型如何响应。
+         * @default -
+         */
+        responseGuidance?: string;
+    };
 };
 
 /**
@@ -1726,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
@@ -1822,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
  */
@@ -1943,7 +2023,7 @@ export declare type DeviceOrientation = 'portrait' | 'landscape';
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息重试
+ * @errorCode common | 102 | Android,iOS
  *
  * @public
  */
@@ -1954,6 +2034,7 @@ export declare const disableUserScreenRecord: (params?: {} | undefined) => Promi
  *
  * @param params - 动作描述、预期行为及工具调用约束参数。
  * @returns 返回一个 Promise，在动作指令成功下发时解析。
+ * @deprecated 使用 {@link sendFollowUpMessage} 发送后续消息。
  * @remarks
  * 适用于卡片交互后向模型补充结构化动作上下文，例如按钮点击、选项选择或表单提交。
  * `getWidgetInstanceId` 仅在卡片环境中有效，在智能服务页面中会返回 `undefined`。如果需要在页面中调用，
@@ -1983,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>;
 
@@ -2238,7 +2328,7 @@ export declare interface DownloadTaskHeadersReceivedEvent {
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息重试
+ * @errorCode common | 102 | Android,iOS
  *
  * @public
  */
@@ -2264,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
  */
@@ -2455,7 +2545,7 @@ export declare interface FileSystemManager {
  *   }
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认智能服务运行环境后重试
+ * @errorCode common | 102 | Android
  *
  * @public
  */
@@ -2504,7 +2594,7 @@ export declare interface GetAccountInfoResult {
  *   }
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认智能服务运行环境后重试
+ * @errorCode common | 102 | Android
  *
  * @public
  */
@@ -2534,7 +2624,7 @@ export declare function getAccountInfoSync(params?: {}): GetAccountInfoResult;
  * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件
- * @usageNote All | 本接口查询宿主应用权限，不等同于查询当前小程序 scope 授权。
+ * @usageNote All | 本接口查询宿主应用权限，不等同于查询当前智能服务 scope 授权。
  * @usageNote iOS | SDK 首次完成通知设置异步预热前，或应用重新激活后的刷新尚未完成时，四个通知字段可能仍为旧值或 not determined。
  * @resultExample
  * ```json
@@ -2774,7 +2864,7 @@ export declare function getBackgroundAudioManager(): BackgroundAudioManager;
  *   "level": 82
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息重试
+ * @errorCode common | 102 | Android
  *
  * @public
  */
@@ -3245,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
  */
@@ -3362,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
  */
@@ -3564,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;
@@ -3698,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
@@ -3834,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
  */
@@ -3925,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
  */
@@ -3998,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
  */
@@ -4105,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
  */
@@ -4251,7 +4417,7 @@ export declare interface GetSavedFileListResult {
  *   "value": 0.6
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | Android 根据异常信息重试，iOS 暂不支持该 API
+ * @errorCode common | 102 | Android
  *
  * @public
  */
@@ -4298,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
  */
@@ -4713,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 联网
  *
@@ -4775,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
  */
@@ -5419,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
  */
@@ -5528,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
  */
@@ -5601,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
  */
@@ -5638,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
  */
@@ -6431,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';
-
 /**
  * 打开蓝牙适配器。
  *
@@ -6723,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
  */
@@ -7133,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
  */
@@ -7160,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
  */
@@ -7337,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
  */
@@ -7402,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
  */
@@ -7455,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
@@ -7691,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
  */
@@ -7761,7 +7973,7 @@ export declare type Scope = 'scope.userLocation' | 'scope.userFuzzyLocation' | '
 export declare type SelectedMessageFileType = 'video' | 'image' | 'file';
 
 /**
- * 以用户身份发送后续消息，触发新一轮对话或 API 调用。
+ * 以用户身份发送后续消息，触发新一轮对话、API 调用或引导模型响应。
  *
  * @param params - 要发送的后续消息内容。
  * @returns 返回一个 Promise，在消息发送请求提交后解析。
@@ -7782,6 +7994,13 @@ export declare type SelectedMessageFileType = 'video' | 'image' | 'file';
  *         name: 'selectDrink',
  *         arguments: { drinkId: 'latte_001' }
  *       }
+ *     },
+ *     {
+ *       type: 'responseHint',
+ *       data: {
+ *         userAction: '用户选择了拿铁',
+ *         responseGuidance: '确认已选择拿铁，并询问是否需要调整杯型'
+ *       }
  *     }
  *   ]
  * });
@@ -7823,7 +8042,7 @@ export declare interface SendFollowUpMessageParams {
  *
  * @param params - 消息内容及类型。
  * @returns 返回一个 Promise，在消息成功发送时解析。
- * @deprecated 使用 {@link dispatchActionDirective} 描述用户行为并约束模型后续动作。
+ * @deprecated 使用 {@link sendFollowUpMessage} 发送后续消息。
  * @summary 以用户身份发送消息。
  * @example
  * ```typescript
@@ -7844,7 +8063,7 @@ 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 专属错误码 | 无需处理
  *
  * @internal
@@ -7887,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
  */
@@ -7948,7 +8177,18 @@ 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。
  *
  * @internal
  */
@@ -8054,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
  */
@@ -8088,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
  */
@@ -8228,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
  */
@@ -8273,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
  */
@@ -8355,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
  */
@@ -8410,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
  */
@@ -8459,7 +8736,7 @@ export declare interface ShowLoadingParams {
  *   "action": "confirm"
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorCode common | 102 | Android,iOS
  *
  * @public
  */
@@ -8562,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
  * */
@@ -8643,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
@@ -8965,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
  */
@@ -9145,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
  */
@@ -9176,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
  */
@@ -9222,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
  */
@@ -9276,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
  */
@@ -9319,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
  */
@@ -9569,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
  */
@@ -9599,7 +9961,7 @@ export declare function stopLocationUpdate(): Promise<LocationOperationResult>;
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据返回的错误信息重试
+ * @errorCode none | - | - | Android,iOS | 该接口双端恒返回成功，无 API 专属错误码 | 无需处理
  *
  * @public
  */
@@ -9839,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
  */
@@ -9896,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
  */
@@ -10183,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
  */
@@ -10214,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
  */

package/dist/config.d.ts

@@ -27,6 +27,10 @@ declare interface AIAppMetadata {
      * 应用版本
      */
     version?: string;
+    /**
+     * 是否声明小程序已适配深色模式
+     */
+    darkMode?: boolean;
 }
 
 declare type AIPageMetadata = Omit<PageDefinition, 'entry' | 'renderType' | 'digest' | 'web'>;

package/dist/index.d.ts

@@ -135,6 +135,10 @@ declare interface AIAppMetadata {
      * 应用版本
      */
     version?: string;
+    /**
+     * 是否声明小程序已适配深色模式
+     */
+    darkMode?: boolean;
 }
 
 export declare type AIToolContext = MessageMeta & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doubao-dev/framework",
-  "version": "0.0.40",
+  "version": "0.0.41",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {