@doubao-dev/framework 0.0.40 → 0.0.42

package/dist/api.d.ts

@@ -191,12 +191,23 @@ export declare interface AddPhoneRepeatCalendarParams extends AddPhoneCalendarPa
     repeatEndTime?: number;
 }
 
+/**
+ * 相册精细授权状态。
+ *
+ * 继承 {@link BasicAuthorizationDetail} 的全部取值，并增加：
+ * - `limited`：只能访问用户选择的部分照片；支持 iOS 和 Android 14 及以上版本。
+ * - `add only`：只能向相册添加照片，不能读取相册内容；仅 iOS 支持。
+ *
+ * @public
+ */
+export declare type AlbumAuthorizationDetail = BasicAuthorizationDetail | 'limited' | 'add only';
+
 /** @public */
 export declare type AppAuthorizeStatus = 'authorized' | 'denied' | 'not determined';
 
 /** @public */
 export declare interface AppBaseInfoHost {
-    /** 宿主 app 对应的 appId */
+    /** 当前豆包客户端的 appId */
     appId: string;
 }
 
@@ -259,7 +270,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
  */
@@ -424,6 +452,16 @@ export declare interface BackgroundAudioState {
     playbackRate?: number;
 }
 
+/**
+ * 只有完整授权和未授权状态的权限所使用的通用精细状态。
+ *
+ * 继承 {@link UnauthorizedDetail} 的全部取值，并增加：
+ * - `full`：已获得该权限的完整访问能力。
+ *
+ * @public
+ */
+export declare type BasicAuthorizationDetail = UnauthorizedDetail | 'full';
+
 /**
  * 电池信息变化事件。
  *
@@ -512,6 +550,16 @@ export declare type BluetoothAdapterStateChangeEvent = GetBluetoothAdapterStateR
 /** @public */
 export declare type BluetoothAdapterStateChangeListener = (event: BluetoothAdapterStateChangeEvent) => void;
 
+/**
+ * 蓝牙精细授权状态。
+ *
+ * 继承 {@link BasicAuthorizationDetail} 的全部取值，并增加：
+ * - `partial`：只获得部分已声明的蓝牙子权限；仅 Android 支持。
+ *
+ * @public
+ */
+export declare type BluetoothAuthorizationDetail = BasicAuthorizationDetail | 'partial';
+
 /**
  * 蓝牙广播二进制字段。
  *
@@ -722,6 +770,155 @@ export declare type BottomSheetCancelSource = 'mask' | 'gesture' | 'hostUnavaila
  */
 export declare type CalendarRepeatInterval = 'day' | 'week' | 'month' | 'year';
 
+/**
+ * 调用当前应用的 Tool。
+ *
+ * 豆包会根据当前智能服务页面或会话 Widget 确定应用和版本，开发者只需传入 Tool 名称和参数。
+ * Tool 正常结果通过 `toolResult` 返回，Tool 业务错误通过 `toolError` 返回，两者都会正常
+ * resolve；调用前校验、鉴权或返回结构校验失败时 Promise reject。
+ *
+ * @param params - Tool 名称和参数。
+ * @returns Tool 正常结果或业务错误，以及 Widget 场景下可选的更新错误。
+ * @example
+ * ```typescript
+ * import { callTool } from '@doubao-dev/framework/api';
+ *
+ * const result = await callTool({
+ *   toolName: 'query_order',
+ *   toolArgs: {
+ *     orderId: 'order-123'
+ *   }
+ * });
+ *
+ * if (result.toolError) {
+ *   console.warn(result.toolError.code, result.toolError.message);
+ * } else {
+ *   console.log(result.toolResult);
+ * }
+ * ```
+ *
+ * @since 0.0.42
+ * @contractStatus verified | 公开参数、页面与 Widget 调用场景、Widget 更新控制、互斥返回结构及 Android、iOS 错误字段一致。
+ * @platformSupport Android | supported | 支持在智能服务页面和会话 Widget 中调用当前应用的 Tool。
+ * @platformSupport iOS | supported | 支持在智能服务页面和会话 Widget 中调用当前应用的 Tool。
+ * @platformSupport PC | unsupported | 客户端尚未实现 callTool。
+ * @platformSupport HarmonyOS | unsupported | 客户端尚未实现 callTool。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition Android | 在当前应用的智能服务页面或由当前应用真实生成的会话 Widget 内调用，且目标 Tool 已在当前应用版本中配置。
+ * @precondition iOS | 在当前应用的智能服务页面或由当前应用真实生成的会话 Widget 内调用，且目标 Tool 已在当前应用版本中配置。
+ * @usageNote All | toolResult 与 toolError 互斥；toolError 是正常返回的 Tool 业务错误，不会导致 Promise reject。skipWidgetUpdate 为 true 时不执行 Widget 更新阶段，因此不会返回 cardUpdateError；否则 cardUpdateError 表示 Tool 已执行但当前 Widget 更新失败。重试会再次执行 Tool，请避免重复触发。
+ * @resultExample
+ * ```json
+ * {
+ *   "toolResult": {
+ *     "content": [
+ *       {
+ *         "type": "text",
+ *         "text": "订单已支付"
+ *       }
+ *     ],
+ *     "structuredContent": {
+ *       "orderId": "order-123",
+ *       "status": "paid"
+ *     }
+ *   }
+ * }
+ * ```
+ * @errorExample
+ * ```json
+ * {
+ *   "errNo": 104,
+ *   "errMsg": "invalid parameter"
+ * }
+ * ```
+ * @errorCode common | 102 | Android,iOS
+ * @errorCode errNo | 103 | feature not support | Android,iOS | 在 Worker 等非智能服务页面、Widget 容器中调用 | 仅在智能服务页面或会话 Widget 中调用。
+ * @errorCode errNo | 104 | invalid parameter | Android,iOS | toolName 为空、toolArgs 无法序列化为 JSON 对象，或传入的 skipWidgetUpdate 不是布尔值 | 修正 Tool 名称、参数和 Widget 更新控制参数后重试。
+ * @errorCode errNo | 112 | invalid result | Android,iOS | Tool 正常结果、业务错误或 Widget 更新错误结构无效 | 稍后重试；持续失败时反馈 Tool 或服务端返回异常。
+ * @platformNote All | 非智能服务页面、Widget 容器返回 103；参数非法返回 104；返回结构无效返回 112；上下文无效、网络或服务端调用失败返回 102。
+ * @knownIssue All | Web SDK 模拟器暂不支持 skipWidgetUpdate 为 true；请在 Android 或 iOS 豆包客户端验证跳过 Widget 更新的调用。
+ *
+ * @public
+ */
+export declare const callTool: (params: CallToolParams) => Promise<CallToolResult>;
+
+/**
+ * Tool 正常完成调用后返回的业务错误。
+ *
+ * @public
+ */
+export declare interface CallToolBusinessError {
+    /** Tool 业务错误码。 */
+    code: number;
+    /** Tool 业务错误信息。 */
+    message: string;
+}
+
+/**
+ * Widget 更新阶段的错误。
+ *
+ * @public
+ */
+export declare interface CallToolError {
+    /** 错误码。 */
+    code: string;
+    /** 错误信息。 */
+    message: string;
+    /** 错误阶段，固定为渲染阶段。 */
+    phase: 'render';
+}
+
+/**
+ * 调用 Tool 的参数。
+ *
+ * @public
+ */
+export declare interface CallToolParams {
+    /** 当前应用内需要调用的 Tool 名称。 */
+    toolName: string;
+    /** Tool 入参。 */
+    toolArgs: Record<string, unknown>;
+    /**
+     * 是否跳过 Widget 更新阶段。设为 `true` 时，即使 Tool 下发 Widget，也只返回 Tool 数据，
+     * 不更新当前 Widget。
+     *
+     * @default false
+     * @constraint 仅影响会下发 Widget 的 Tool。
+     */
+    skipWidgetUpdate?: boolean;
+}
+
+/**
+ * 调用 Tool 的结果。
+ *
+ * @public
+ */
+export declare type CallToolResult = {
+    /**
+     * Tool 已执行，但返回结果未能用于更新当前 Widget 时的错误。仅 Widget 场景可能返回。
+     *
+     * @default -
+     */
+    cardUpdateError?: CallToolError;
+} & ({
+    /** Tool 正常结果，与 `toolError` 二选一。 */
+    toolResult: ToolResult;
+    /** @hidden */
+    toolError?: never;
+} | {
+    /** Tool 业务错误，与 `toolResult` 二选一。该字段不会导致 API reject。 */
+    toolError: CallToolBusinessError;
+    /** @hidden */
+    toolResult?: never;
+});
+
+/**
+ * 摄像头精细授权状态，取值与 {@link BasicAuthorizationDetail} 一致。
+ *
+ * @public
+ */
+export declare type CameraAuthorizationDetail = BasicAuthorizationDetail;
+
 /** @public */
 export declare interface CanIUseParams {
     /** 需要检测的能力标识，例如 API 名称 */
@@ -734,6 +931,47 @@ export declare interface CanIUseResult {
     result: boolean;
 }
 
+/**
+ * 对话框高度或展示状态变化事件。
+ *
+ * @public
+ */
+export declare type ChatPanelHeightChangedEvent = ChatPanelInfo;
+
+/**
+ * 对话框高度或展示状态变化监听函数。
+ *
+ * @public
+ */
+export declare type ChatPanelHeightChangedListener = (event: ChatPanelHeightChangedEvent) => void;
+
+/**
+ * 对话框状态快照。
+ *
+ * @public
+ */
+export declare interface ChatPanelInfo {
+    /**
+     * 对话框当前占用的垂直高度，单位为逻辑像素（px），不包含系统键盘高度。
+     *
+     * @constraint 大于等于 0；收起态高度也可能大于 0
+     */
+    height: number;
+    /**
+     * 对话框当前展示状态。
+     *
+     * `preview` 表示从收起态发送消息后、收到回复前的中间态。
+     */
+    state: ChatPanelState;
+}
+
+/**
+ * 对话框展示状态。
+ *
+ * @public
+ */
+export declare type ChatPanelState = 'collapsed' | 'expanded' | 'preview';
+
 /**
  * 检测无障碍能力是否开启。
  *
@@ -763,7 +1001,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 +1624,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
  */
@@ -1387,13 +1649,13 @@ export declare function connectSocket(params: ConnectSocketParams): SocketTask;
 /**
  * 创建 WebSocket 连接的参数。
  *
- * `connectSocket` 会把这些参数透传给宿主侧创建连接。连接创建请求发出后，
+ * `connectSocket` 会把这些参数交给豆包客户端创建连接。连接创建请求发出后，
  * 调用方会立即拿到一个 {@link SocketTask}，后续连接成功、失败、收到消息和关闭状态
  * 都通过 `SocketTask` 上注册的事件回调通知。
  *
  * @remarks
- * - `url` 应填写完整的 WebSocket 地址。线上环境通常要求使用 `wss://` 协议，并由宿主侧按当前应用配置校验合法域名和证书。
- * - `header` 用于补充握手请求头，`referer` 等由宿主管控的字段不会被业务代码覆盖。
+ * - `url` 应填写完整的 WebSocket 地址。线上环境通常要求使用 `wss://` 协议，并由豆包客户端按当前智能服务配置校验合法域名和证书。
+ * - `header` 用于补充握手请求头，`referer` 等由豆包客户端管理的字段不会被业务代码覆盖。
  * - `protocols` 非空时，服务端需要在握手响应中选择并返回匹配的子协议，否则连接可能失败。
  * - 同一个页面多次调用会创建多个独立连接，已创建的旧连接不会因为新连接自动关闭。
  *
@@ -1412,7 +1674,7 @@ export declare interface ConnectSocketParams {
      * WebSocket 握手阶段携带的 HTTP Header。
      *
      * 适合放置业务自定义 Header，例如鉴权 token、trace id、客户端能力标识等。
-     * `referer` 由宿主侧统一生成和管理，不应依赖该字段被业务传入值覆盖。
+     * `referer` 由豆包客户端统一生成和管理，不应依赖该字段被业务传入值覆盖。
      *
      * @default -
      */
@@ -1422,7 +1684,7 @@ export declare interface ConnectSocketParams {
      *
      * 会作为握手请求中的 `Sec-WebSocket-Protocol` 候选值传给服务端。
      * 如果传入非空数组，服务端需要选择其中一个协议并在握手响应中返回；
-     * 服务端不支持或不返回匹配协议时，连接可能被宿主判定为创建失败。
+     * 服务端不支持或不返回匹配协议时，豆包客户端可能判定连接创建失败。
      *
      * @default -
      */
@@ -1459,7 +1721,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 +1791,22 @@ export declare type Content = {
         /** API 调用参数。 */
         arguments: object;
     };
+} | {
+    /** 模型响应提示。 */
+    type: 'responseHint';
+    /** 用户动作和模型响应建议。 */
+    data: {
+        /**
+         * 用户做了什么。
+         * @default -
+         */
+        userAction?: string;
+        /**
+         * 建议模型如何响应。
+         * @default -
+         */
+        responseGuidance?: string;
+    };
 };
 
 /**
@@ -1726,7 +2017,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 +2113,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 +2244,7 @@ export declare type DeviceOrientation = 'portrait' | 'landscape';
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息重试
+ * @errorCode common | 102 | Android,iOS
  *
  * @public
  */
@@ -1954,6 +2255,7 @@ export declare const disableUserScreenRecord: (params?: {} | undefined) => Promi
  *
  * @param params - 动作描述、预期行为及工具调用约束参数。
  * @returns 返回一个 Promise，在动作指令成功下发时解析。
+ * @deprecated 使用 {@link sendFollowUpMessage} 发送后续消息。
  * @remarks
  * 适用于卡片交互后向模型补充结构化动作上下文，例如按钮点击、选项选择或表单提交。
  * `getWidgetInstanceId` 仅在卡片环境中有效，在智能服务页面中会返回 `undefined`。如果需要在页面中调用，
@@ -1983,9 +2285,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>;
 
@@ -2099,8 +2410,8 @@ export declare interface DoubaoAppAccountInfo {
  * @platformSupport PC | unsupported | 当前未提供该平台实现。
  * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
  * @permission none | - | none | Android,iOS | 无需额外权限
- * @precondition All | 下载地址需通过宿主侧下载域名白名单校验，单个文件不得超过 200 MB，单个智能服务同时最多执行 10 个下载任务；指定 filePath 时仅支持临时目录或用户目录。
- * @usageNote All | 未指定 filePath 时文件写入临时目录，并通过 Promise resolve 结果的 tempFilePath 返回；临时文件的生命周期由宿主管理。
+ * @precondition All | 下载地址需通过豆包配置的下载域名白名单校验，单个文件不得超过 200 MB，单个智能服务同时最多执行 10 个下载任务；指定 filePath 时仅支持临时目录或用户目录。
+ * @usageNote All | 未指定 filePath 时文件写入临时目录，并通过 Promise resolve 结果的 tempFilePath 返回；临时文件的生命周期由豆包客户端管理。
  * @usageNote All | 不跟随 HTTP 重定向，3xx 响应使 Promise reject；4xx、5xx 响应在文件写入成功后仍使 Promise resolve。
  * @resultExample
  * ```json
@@ -2124,10 +2435,10 @@ export declare function downloadFile(params: DownloadFileParams): DownloadTask;
  * @public
  */
 export declare interface DownloadFileParams {
-    /** 下载资源地址，需为完整 HTTPS URL，并通过宿主侧下载域名白名单校验。 */
+    /** 下载资源地址，需为完整 HTTPS URL，并通过豆包配置的下载域名白名单校验。 */
     url: string;
     /**
-     * 请求 Header。`referer` 和 `user-agent` 由宿主管控，业务传入值不会透传。
+     * 请求 Header。`referer` 和 `user-agent` 由豆包客户端管理，业务传入值不会透传。
      *
      * @default -
      */
@@ -2238,7 +2549,7 @@ export declare interface DownloadTaskHeadersReceivedEvent {
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息重试
+ * @errorCode common | 102 | Android,iOS
  *
  * @public
  */
@@ -2264,7 +2575,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 +2766,7 @@ export declare interface FileSystemManager {
  *   }
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息确认智能服务运行环境后重试
+ * @errorCode common | 102 | Android
  *
  * @public
  */
@@ -2504,37 +2815,41 @@ 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`。
+ * 调用只读取当前系统授权状态，不会申请权限或触发系统授权弹窗。原有状态字段固定返回
+ * `authorized`、`denied` 或 `not determined`，精细授权字段用于区分部分、只读、只写、前后台等能力。
  *
- * @returns 返回宿主应用相册、蓝牙、摄像头、定位、麦克风、通知和日历权限状态。
+ * @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);
+ * const detail = result.phoneCalendarAuthorizationDetail;
+ * const canWriteCalendar =
+ *   detail === 'full' ||
+ *   detail === 'write only' ||
+ *   (detail == null && result.phoneCalendarAuthorized === 'authorized');
+ * console.log(canWriteCalendar);
  * ```
  *
  * @since 0.0.40
- * @contractStatus verified | Android 与 iOS 均同步返回固定 11 个字段；除 locationReducedAccuracy 为 boolean 外，其余授权状态字段均限定为 authorized、denied 或 not determined，调用不会触发权限申请。
- * @platformSupport Android | supported | 支持同步读取宿主应用授权状态。
- * @platformSupport iOS | supported | 支持同步读取宿主应用授权状态。
+ * @contractStatus verified | Android 与 iOS 均同步返回原有授权状态及可映射的精细授权字段；精细字段无法可靠映射或平台不适用时可为空，调用不会触发权限申请。
+ * @platformSupport Android | supported | 支持同步读取豆包客户端的系统权限状态。
+ * @platformSupport iOS | supported | 支持同步读取豆包客户端的系统权限状态。
  * @platformSupport PC | unsupported | 当前未提供该平台实现。
  * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件
- * @usageNote All | 本接口查询宿主应用权限，不等同于查询当前小程序 scope 授权。
+ * @usageNote All | 本接口查询豆包客户端的系统权限，不等同于查询当前智能服务的 scope 授权。
  * @usageNote iOS | SDK 首次完成通知设置异步预热前，或应用重新激活后的刷新尚未完成时，四个通知字段可能仍为旧值或 not determined。
  * @resultExample
  * ```json
@@ -2549,14 +2864,23 @@ export declare function getAccountInfoSync(params?: {}): GetAccountInfoResult;
  *   "notificationAlertAuthorized": "authorized",
  *   "notificationBadgeAuthorized": "denied",
  *   "notificationSoundAuthorized": "authorized",
- *   "phoneCalendarAuthorized": "not determined"
+ *   "phoneCalendarAuthorized": "denied",
+ *   "albumAuthorizationDetail": "limited",
+ *   "bluetoothAuthorizationDetail": "full",
+ *   "cameraAuthorizationDetail": "full",
+ *   "locationAuthorizationDetail": "foreground precise",
+ *   "microphoneAuthorizationDetail": "full",
+ *   "notificationAuthorizationDetail": "provisional",
+ *   "phoneCalendarAuthorizationDetail": "write only"
  * }
  * ```
  * @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 Android | 精细字段区分 Android 14 部分相册、日历读写、定位前后台和精度，以及蓝牙部分子权限
  * @platformNote iOS | 相册 limited 映射为 authorized，通知 provisional 和 ephemeral 映射为 authorized
+ * @platformNote iOS | 精细字段区分相册 limited/add only、日历 write only、定位前后台和精度，以及通知 provisional；ephemeral 暂不映射
  *
  * @public
  */
@@ -2586,12 +2910,56 @@ export declare interface GetAppAuthorizeSettingResult {
     notificationSoundAuthorized: AppAuthorizeStatus;
     /** 系统日历授权状态 */
     phoneCalendarAuthorized: AppAuthorizeStatus;
+    /**
+     * 相册精细授权状态；旧客户端或无法可靠映射时不返回该字段或返回 `null`。
+     *
+     * 继承 {@link BasicAuthorizationDetail} 的全部取值，并增加：
+     * - `limited`：只能访问用户选择的部分照片；支持 iOS 和 Android 14 及以上版本。
+     * - `add only`：只能向相册添加照片，不能读取相册内容；仅 iOS 支持。
+     */
+    albumAuthorizationDetail?: AlbumAuthorizationDetail | null;
+    /**
+     * 蓝牙精细授权状态；旧客户端或无法可靠映射时不返回该字段或返回 `null`。
+     *
+     * 继承 {@link BasicAuthorizationDetail} 的全部取值，并增加：
+     * - `partial`：只获得部分已声明的蓝牙子权限；仅 Android 支持。
+     */
+    bluetoothAuthorizationDetail?: BluetoothAuthorizationDetail | null;
+    /** 摄像头精细授权状态，取值与 {@link BasicAuthorizationDetail} 一致；旧客户端或无法可靠映射时不返回该字段或返回 `null`。 */
+    cameraAuthorizationDetail?: CameraAuthorizationDetail | null;
+    /**
+     * 定位精细授权状态；旧客户端或无法可靠映射时不返回该字段或返回 `null`。
+     *
+     * 继承 {@link UnauthorizedDetail} 的全部取值；获得权限时返回：
+     * - `foreground approximate`：仅应用在前台时可以获取模糊定位。
+     * - `foreground precise`：仅应用在前台时可以获取精确定位。
+     * - `background approximate`：应用在前台或后台时均可以获取模糊定位。
+     * - `background precise`：应用在前台或后台时均可以获取精确定位。
+     */
+    locationAuthorizationDetail?: LocationAuthorizationDetail | null;
+    /** 麦克风精细授权状态，取值与 {@link BasicAuthorizationDetail} 一致；旧客户端或无法可靠映射时不返回该字段或返回 `null`。 */
+    microphoneAuthorizationDetail?: MicrophoneAuthorizationDetail | null;
+    /**
+     * 通知精细授权状态；旧客户端或无法可靠映射时不返回该字段或返回 `null`。
+     *
+     * 继承 {@link BasicAuthorizationDetail} 的全部取值，并增加：
+     * - `provisional`：iOS 临时静默授权；不会弹出授权框，通知只进入通知中心。
+     */
+    notificationAuthorizationDetail?: NotificationAuthorizationDetail | null;
+    /**
+     * 系统日历精细授权状态；旧客户端或无法可靠映射时不返回该字段或返回 `null`。
+     *
+     * 继承 {@link BasicAuthorizationDetail} 的全部取值，并增加：
+     * - `read only`：只能读取日历，不能新增、修改或删除日程；仅 Android 支持。
+     * - `write only`：只能新增日程，不能读取现有日历数据。
+     */
+    phoneCalendarAuthorizationDetail?: PhoneCalendarAuthorizationDetail | null;
 }
 
 /**
  * 获取应用基础信息。
  *
- * @returns 返回 SDK 版本、调试开关、宿主信息、语言和主题等字段，见 {@link GetAppBaseInfoResult}。
+ * @returns 返回 SDK 版本、调试开关、豆包客户端信息、语言和主题等字段，见 {@link GetAppBaseInfoResult}。
  * @example
  * ```typescript
  * import { getAppBaseInfo } from '@doubao-dev/framework/api';
@@ -2636,11 +3004,11 @@ export declare interface GetAppBaseInfoResult {
     SDKVersion?: string;
     /** 是否已打开调试 */
     enableDebug?: boolean;
-    /** 当前豆包 App 运行的宿主环境 */
+    /** 当前豆包客户端信息 */
     host?: AppBaseInfoHost;
     /** 当前语言 */
     language: string;
-    /** 宿主版本号 */
+    /** 豆包客户端版本号 */
     version?: string;
     /** 当前主题 */
     theme?: 'light' | 'dark';
@@ -2649,7 +3017,7 @@ export declare interface GetAppBaseInfoResult {
 /**
  * 获取应用基础信息。
  *
- * @returns 返回 SDK 版本、调试开关、宿主信息、语言和主题等字段，见 {@link GetAppBaseInfoResult}。
+ * @returns 返回 SDK 版本、调试开关、豆包客户端信息、语言和主题等字段，见 {@link GetAppBaseInfoResult}。
  * @example
  * ```typescript
  * import { getAppBaseInfoSync } from '@doubao-dev/framework/api';
@@ -2774,7 +3142,7 @@ export declare function getBackgroundAudioManager(): BackgroundAudioManager;
  *   "level": 82
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据异常信息重试
+ * @errorCode common | 102 | Android
  *
  * @public
  */
@@ -3217,6 +3585,40 @@ export declare interface GetBluetoothDevicesResult {
     devices: BluetoothDevice[];
 }
 
+/**
+ * 获取当前对话框状态快照。
+ *
+ * 调用不会改变对话框状态，也不会触发高度变化事件。
+ *
+ * @example
+ * ```typescript
+ * import { getChatPanelInfo } from '@doubao-dev/framework/api';
+ *
+ * const { height, state } = await getChatPanelInfo();
+ * console.log('current chat panel', { height, state });
+ * ```
+ * @since 0.0.42
+ * @contractStatus verified | 请求参数、返回字段和状态枚举与对话框状态查询协议一致。
+ * @platformSupport Android | supported | 支持获取当前对话框状态快照。
+ * @platformSupport iOS | supported | 支持获取当前对话框状态快照。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition All | 当前页面需在 app.config.ts 中声明 chat.enabled 为 true
+ * @usageNote All | 调用只读取当前状态，不会改变对话框状态或触发高度变化事件。
+ * @resultExample
+ * ```json
+ * {
+ *   "height": 336,
+ *   "state": "expanded"
+ * }
+ * ```
+ * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ *
+ * @public
+ */
+export declare const getChatPanelInfo: (params?: {} | undefined) => Promise<ChatPanelInfo>;
+
 /**
  * 获取剪贴板内容。
  *
@@ -3245,7 +3647,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 +3772,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
  */
@@ -3438,7 +3867,7 @@ export declare const getDeviceInfo: (params?: {} | undefined) => Promise<GetDevi
  * @public
  */
 export declare interface GetDeviceInfoResult {
-    /** 宿主 App 二进制接口类型，仅 Android 支持。 */
+    /** 豆包客户端二进制接口类型，仅 Android 支持。 */
     abi?: string;
     /** 设备二进制接口类型，仅 Android 支持。 */
     deviceAbi?: string;
@@ -3564,7 +3993,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 +4141,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
@@ -3724,6 +4179,13 @@ export declare interface GetLocationParams {
      * @constraint 取值为 0、1 或 2
      */
     mode?: number;
+    /**
+     * 是否接受轻定位结果。轻定位会直接利用设备已有的 Wi-Fi 扫描缓存，由服务端快速计算当前位置，缩短定位耗时。
+     *
+     * @default false
+     * @constraint 仅 Android 生效，需使用 0.0.42 及以上版本的基础库
+     */
+    acceptLightLocation?: boolean;
     /**
      * 超时时间，单位毫秒，默认 30000
      *
@@ -3834,7 +4296,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 +4389,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,10 +4472,20 @@ export declare interface GetOrderPaymentResult {
  *   "logId": "20260519xxxx"
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无稳定的顶层 errNo/errMsg；调用失败时 Promise reject，业务错误（errNo、errMsg、errLogId）在错误对象的 data 字段 | 通过 catch 捕获并读取 e.data 排查
- * @platformNote Android | 需在前台可见的 Activity 中调用，应用退至后台或无有效页面时会返回失败。
- *
- * @public
+ * @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
  */
 export declare const getOrderPaymentWithSign: (params: GetOrderPaymentWithSignParams) => Promise<GetOrderPaymentResult>;
 
@@ -4042,39 +4526,60 @@ export declare interface GetPackageInfoResult {
 }
 
 /**
- * 同步获取当前 package 信息。
+ * 同步获取当前 package 信息，仅供 Web SDK 模拟器使用。
+ *
+ * @internal
+ */
+export declare const getPackageInfoSync: () => GetPackageInfoResult;
+
+/**
+ * 获取当前智能服务应用的性能数据。
+ *
+ * Entry 由客户端保存；`getEntries*()` 同步查询当前快照，observer 只接收新完成的 Entry。
  *
- * @returns 返回当前 package 的 appId、展示名称和展示图标地址，见 {@link GetPackageInfoResult}。
+ * @returns 返回可查询性能 Entry 和创建观察者的 {@link Performance}。
  * @example
  * ```typescript
- * import { getPackageInfoSync } from '@doubao-dev/framework/api';
+ * import { getPerformance } from '@doubao-dev/framework/api';
  *
- * const result = getPackageInfoSync();
+ * const performance = getPerformance();
+ * const observer = performance.createObserver((entryList) => {
+ *   console.log(entryList.getEntries());
+ * });
  *
- * console.log(result.appId, result.name, result.iconSrc);
+ * performance.setBufferSize(100);
+ * observer.observe({ entryTypes: ['render'] });
+ * console.log(performance.getEntriesByType('render'));
+ * observer.disconnect();
  * ```
  *
- * @since 0.0.34
- * @contractStatus verified | 由智能服务运行环境同步读取，字段与公开类型一致。
- * @platformSupport Android | supported | 支持同步读取当前 package 信息。
- * @platformSupport iOS | supported | 支持同步读取当前 package 信息。
+ * @since 0.0.42
+ * @contractStatus verified | Android 支持同步查询已记录的性能 Entry、设置缓冲区大小，并向已观察的运行时发送新完成的 Entry。
+ * @platformSupport Android | supported | 支持查询性能 Entry、设置性能缓冲区大小和创建性能观察者。
+ * @platformSupport iOS | unsupported | 当前未提供该平台实现。
  * @platformSupport PC | unsupported | 当前未提供该平台实现。
  * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件
+ * @usageNote All | 仅在需要接收后续新完成的 Entry 时创建 observer；不再需要时调用 disconnect。
  * @resultExample
  * ```json
- * {
- *   "appId": "7000000000000000000",
- *   "name": "示例智能服务",
- *   "iconSrc": "https://example.com/icon.png"
- * }
+ * [
+ *   {
+ *     "entryType": "render",
+ *     "name": "firstRender",
+ *     "startTime": 1730000000000,
+ *     "duration": 42,
+ *     "path": "pages/index/index",
+ *     "pageId": 1
+ *   }
+ * ]
  * ```
  * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
  *
  * @public
  */
-export declare const getPackageInfoSync: () => GetPackageInfoResult;
+export declare function getPerformance(): Performance_2;
 
 /**
  * 获取隐私设置状态。
@@ -4105,7 +4610,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 +4757,7 @@ export declare interface GetSavedFileListResult {
  *   "value": 0.6
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | Android 根据异常信息重试，iOS 暂不支持该 API
+ * @errorCode common | 102 | Android
  *
  * @public
  */
@@ -4298,7 +4804,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
  */
@@ -4319,7 +4835,7 @@ export declare interface GetSettingParams {
 export declare interface GetSettingResult {
     /** 用户授权结果，key 为权限 scope，value 表示是否已授权 */
     authSetting: AuthSetting;
-    /** 用户订阅消息设置，withSubscriptions 为 true 时才会返回 */
+    /** 预留的订阅消息设置字段。豆包当前仅支持 `withSubscriptions: false`，因此不会返回该字段。 */
     subscriptionsSetting?: SubscriptionsSetting;
 }
 
@@ -4520,7 +5036,7 @@ export declare function getStorageSync<TData = unknown>(params: GetStorageParams
 /**
  * 获取系统信息。
  *
- * @returns 返回设备品牌、型号、屏幕尺寸、宿主信息和安全区域等字段，见 {@link GetSystemInfoResult}。
+ * @returns 返回设备品牌、型号、屏幕尺寸、豆包客户端信息和安全区域等字段，见 {@link GetSystemInfoResult}。
  * @example
  * ```typescript
  * import { getSystemInfo } from '@doubao-dev/framework/api';
@@ -4533,7 +5049,7 @@ export declare function getStorageSync<TData = unknown>(params: GetStorageParams
  *
  * @since 0.0.34
  * @contractStatus verified | 设备品牌、屏幕尺寸、系统信息和安全区域等字段与公开类型一致。
- * @contractMismatch non-blocking | return | abi | Android,iOS | abi 为可选字段，返回宿主 App 二进制接口类型 | Android 返回具体 abi，iOS 不返回该字段 | 依赖 abi 的逻辑仅在 Android 生效 | packages/open-api/src/basic/system/system.ts; ai-sdk/android/ai-sdk/src/main/java/com/bytedance/ai/bridge/method/system/GetSystemInfoMethod.kt; ai-sdk/ios/AISDK/Sources/JSBridge/Methods/System | 明确 abi 为 Android 专属字段，或补齐 iOS 对应字段
+ * @contractMismatch non-blocking | return | abi | Android,iOS | abi 为可选字段，返回豆包客户端二进制接口类型 | Android 返回具体 abi，iOS 不返回该字段 | 依赖 abi 的逻辑仅在 Android 生效 | packages/open-api/src/basic/system/system.ts; ai-sdk/android/ai-sdk/src/main/java/com/bytedance/ai/bridge/method/system/GetSystemInfoMethod.kt; ai-sdk/ios/AISDK/Sources/JSBridge/Methods/System | 明确 abi 为 Android 专属字段，或补齐 iOS 对应字段
  * @platformSupport Android | supported | 支持获取系统信息。
  * @platformSupport iOS | supported | 支持获取系统信息。
  * @platformSupport PC | unsupported | 当前未提供该平台实现。
@@ -4572,7 +5088,7 @@ export declare function getStorageSync<TData = unknown>(params: GetStorageParams
  * }
  * ```
  * @errorCode common | 102 | Android
- * @platformNote Android | abi 返回宿主 App 二进制接口类型（如 arm64-v8a），iOS 不返回该字段
+ * @platformNote Android | abi 返回豆包客户端二进制接口类型（如 arm64-v8a），iOS 不返回该字段
  *
  * @public
  */
@@ -4598,7 +5114,7 @@ export declare interface GetSystemInfoResult {
     statusBarHeight: number;
     /** 系统语言，格式为 language_region，如 zh_CN、en_US */
     language: string;
-    /** 宿主版本号 */
+    /** 豆包客户端版本号 */
     version?: string;
     /** 操作系统及版本，如 "Android 14"、"iOS 17.5" */
     system: string;
@@ -4616,14 +5132,14 @@ export declare interface GetSystemInfoResult {
     enableDebug?: boolean;
     /** 设备方向 */
     deviceOrientation?: 'portrait' | 'landscape';
-    /** 宿主 App 二进制接口类型（如 arm64-v8a），仅 Android 返回 */
+    /** 豆包客户端二进制接口类型（如 arm64-v8a），仅 Android 返回 */
     abi?: string;
 }
 
 /**
  * 同步获取系统信息。
  *
- * @returns 返回设备品牌、型号、屏幕尺寸、宿主信息和安全区域等字段，见 {@link GetSystemInfoResult}。
+ * @returns 返回设备品牌、型号、屏幕尺寸、豆包客户端信息和安全区域等字段，见 {@link GetSystemInfoResult}。
  * @example
  * ```typescript
  * import { getSystemInfoSync } from '@doubao-dev/framework/api';
@@ -4636,7 +5152,7 @@ export declare interface GetSystemInfoResult {
  *
  * @since 0.0.34
  * @contractStatus verified | 设备品牌、屏幕尺寸、系统信息和安全区域等字段与公开类型一致。
- * @contractMismatch non-blocking | return | abi | Android,iOS | abi 为可选字段，返回宿主 App 二进制接口类型 | Android 返回具体 abi，iOS 不返回该字段 | 依赖 abi 的逻辑仅在 Android 生效 | packages/open-api/src/basic/system/system.ts; ai-sdk/android/ai-sdk/src/main/java/com/bytedance/ai/bridge/method/system/GetSystemInfoMethod.kt; ai-sdk/ios/AISDK/Sources/JSBridge/Methods/System | 明确 abi 为 Android 专属字段，或补齐 iOS 对应字段
+ * @contractMismatch non-blocking | return | abi | Android,iOS | abi 为可选字段，返回豆包客户端二进制接口类型 | Android 返回具体 abi，iOS 不返回该字段 | 依赖 abi 的逻辑仅在 Android 生效 | packages/open-api/src/basic/system/system.ts; ai-sdk/android/ai-sdk/src/main/java/com/bytedance/ai/bridge/method/system/GetSystemInfoMethod.kt; ai-sdk/ios/AISDK/Sources/JSBridge/Methods/System | 明确 abi 为 Android 专属字段，或补齐 iOS 对应字段
  * @platformSupport Android | supported | 支持同步获取系统信息。
  * @platformSupport iOS | supported | 支持同步获取系统信息。
  * @platformSupport PC | unsupported | 当前未提供该平台实现。
@@ -4675,7 +5191,7 @@ export declare interface GetSystemInfoResult {
  * }
  * ```
  * @errorCode common | 102 | Android
- * @platformNote Android | abi 返回宿主 App 二进制接口类型（如 arm64-v8a），iOS 不返回该字段
+ * @platformNote Android | abi 返回豆包客户端二进制接口类型（如 arm64-v8a），iOS 不返回该字段
  *
  * @public
  */
@@ -4713,7 +5229,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 +5291,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
  */
@@ -5209,6 +5744,19 @@ export declare interface KeyboardHeightChangeEvent {
 /** @public */
 export declare type KeyboardHeightChangeListener = (event: KeyboardHeightChangeEvent) => void;
 
+/**
+ * 定位精细授权状态。
+ *
+ * 继承 {@link UnauthorizedDetail} 的全部取值；获得权限时返回：
+ * - `foreground approximate`：仅应用在前台时可以获取模糊定位。
+ * - `foreground precise`：仅应用在前台时可以获取精确定位。
+ * - `background approximate`：应用在前台或后台时均可以获取模糊定位。
+ * - `background precise`：应用在前台或后台时均可以获取精确定位。
+ *
+ * @public
+ */
+export declare type LocationAuthorizationDetail = UnauthorizedDetail | 'foreground approximate' | 'foreground precise' | 'background approximate' | 'background precise';
+
 /** @public */
 export declare interface LocationChangeErrorEvent {
     /**
@@ -5419,7 +5967,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 +6086,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
  */
@@ -5560,6 +6127,13 @@ export declare interface MenuButtonBoundingClientRect {
     left: number;
 }
 
+/**
+ * 麦克风精细授权状态，取值与 {@link BasicAuthorizationDetail} 一致。
+ *
+ * @public
+ */
+export declare type MicrophoneAuthorizationDetail = BasicAuthorizationDetail;
+
 /**
  * {@link FileSystemManager.mkdir} 的参数。
  *
@@ -5601,7 +6175,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 +6212,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
  */
@@ -5684,6 +6266,16 @@ export declare type NetworkStatusChangeListener = (event: NetworkStatusChangeEve
  */
 export declare type NetworkType = 'wifi' | '2g' | '3g' | '4g' | '5g' | 'unknown' | 'none';
 
+/**
+ * 通知精细授权状态。
+ *
+ * 继承 {@link BasicAuthorizationDetail} 的全部取值，并增加：
+ * - `provisional`：iOS 临时静默授权；不会弹出授权框，通知只进入通知中心。
+ *
+ * @public
+ */
+export declare type NotificationAuthorizationDetail = BasicAuthorizationDetail | 'provisional';
+
 /**
  * 订阅 BLE 特征值变化。
  *
@@ -5988,6 +6580,43 @@ export declare const onBluetoothAdapterStateChange: ClientEventRegistry<GetBluet
  */
 export declare function onBluetoothDeviceFound(callback: BluetoothDeviceFoundListener): () => void;
 
+/**
+ * 监听对话框高度或展示状态变化。
+ *
+ * 注册后不会立即回调当前值。需要当前状态时，先调用 {@link getChatPanelInfo}。
+ *
+ * @example
+ * ```typescript
+ * import { onChatPanelHeightChanged } from '@doubao-dev/framework/api';
+ *
+ * const off = onChatPanelHeightChanged(({ height, state }) => {
+ *   console.log('chat panel changed', { height, state });
+ * });
+ *
+ * off();
+ * ```
+ * @since 0.0.42
+ * @contractStatus verified | 事件字段、状态枚举和触发语义与对话框高度变化协议一致。
+ * @platformSupport Android | supported | 支持监听对话框高度或展示状态变化。
+ * @platformSupport iOS | supported | 支持监听对话框高度或展示状态变化。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition All | 当前页面需在 app.config.ts 中声明 chat.enabled 为 true
+ * @usageNote All | 注册后不立即回调当前值；页面卸载前调用返回的取消函数。
+ * @resultExample
+ * ```json
+ * {
+ *   "height": 336,
+ *   "state": "expanded"
+ * }
+ * ```
+ * @errorCode none | - | - | Android,iOS | 事件无错误码 | 无需处理
+ *
+ * @public
+ */
+export declare const onChatPanelHeightChanged: ClientEventRegistry<ChatPanelInfo>;
+
 /**
  * 监听罗盘数据变化事件。
  *
@@ -6277,7 +6906,7 @@ export declare const onNetworkStatusChange: ClientEventRegistry<NetworkStatusCha
 /**
  * 监听应用主题变化。
  *
- * 当用户在系统设置或宿主内切换浅色、深色主题时触发。回调参数中的 `theme` 表示切换后的主题，可与
+ * 当用户在系统设置或豆包客户端内切换浅色、深色主题时触发。回调参数中的 `theme` 表示切换后的主题，可与
  * {@link getAppBaseInfo} 返回的 `theme` 字段配合使用。
  *
  * @summary 监听应用主题变化。
@@ -6295,7 +6924,7 @@ export declare const onNetworkStatusChange: ClientEventRegistry<NetworkStatusCha
  *
  * @since 0.0.32
  * @contractStatus verified | 主题变化事件回调只包含必需的 theme 字段，与公开类型一致。
- * @contractMismatch non-blocking | behavior | onThemeChange | Android | 用户切换浅色、深色主题时触发回调 | iOS 由客户端主动派发事件，Android 依赖宿主接入主题变化通知，未接入时可能不触发 | Android 上事件触发依赖宿主接入情况 | packages/open-api/src/basic/system/system.ts; ai-sdk/android/ai-sdk/src/main/java/com/bytedance/ai/bridge; ai-sdk/ios/AISDK/Sources/JSBridge | 统一双端主题变化事件派发，保证 Android 稳定触发
+ * @contractMismatch non-blocking | behavior | onThemeChange | Android | 用户切换浅色、深色主题时触发回调 | iOS 由客户端主动派发事件，Android 依赖豆包客户端接入主题变化通知，未接入时可能不触发 | Android 上事件触发依赖豆包客户端的接入情况 | packages/open-api/src/basic/system/system.ts; ai-sdk/android/ai-sdk/src/main/java/com/bytedance/ai/bridge; ai-sdk/ios/AISDK/Sources/JSBridge | 统一双端主题变化事件派发，保证 Android 稳定触发
  * @platformSupport Android | supported | 支持注册主题变化监听。
  * @platformSupport iOS | supported | 支持注册主题变化监听。
  * @platformSupport PC | unsupported | 当前未提供该平台实现。
@@ -6310,7 +6939,7 @@ export declare const onNetworkStatusChange: ClientEventRegistry<NetworkStatusCha
  * }
  * ```
  * @errorCode none | - | - | Android,iOS | 该监听只接收成功的主题变化事件 | 无需处理
- * @platformNote Android | 主题变化事件依赖宿主接入主题通知，未接入时可能不触发
+ * @platformNote Android | 主题变化事件依赖豆包客户端接入主题通知，未接入时可能不触发
  *
  * @public
  */
@@ -6431,73 +7060,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';
-
 /**
  * 打开蓝牙适配器。
  *
@@ -6608,6 +7170,64 @@ export declare interface OpenLocationParams {
     latitude: number;
 }
 
+/**
+ * 打开应用内页面。
+ *
+ * 在对话流卡片中调用时会重新打开全页并忽略 `mode`；在全页中调用时按照 `mode` 操作页面栈。
+ *
+ * @param params 打开页面参数，字段见 {@link OpenPageParams}。
+ * @returns 无返回字段。
+ * @example
+ * ```typescript
+ * import { openPage } from '@doubao-dev/framework/api';
+ *
+ * await openPage({
+ *   url: '/pages/detail/index?id=1',
+ *   mode: 'navigate'
+ * });
+ * ```
+ *
+ * @since 0.0.42
+ * @contractStatus conflict | 新版 url 和页面栈 mode 协议已公开，但当前 Android、iOS 尚未提供对应实现。
+ * @contractMismatch blocking | parameter | params | Android | 接收 url 和可选的 push、replace、navigate、popTo mode | 当前 doubao.openPage 仍映射到旧版 applet.openPage，要求 pageId 和 context，且 mode 仅识别 full、popup、floating | 按新版参数调用无法打开页面 | packages/open-api/src/router/open-page.ts; ai-sdk/android/ai-sdk/src/main/java/com/bytedance/ai/bridge/method/router/AbsOpenPageMethodIDL.kt; ai-sdk/android/ai-sdk/src/main/java/com/bytedance/ai/bridge/method/router/OpenPageMethod.kt | Native 使用独立的 doubao.openPage handler 实现新版参数和路由语义
+ * @contractMismatch blocking | platform | method registration | iOS | doubao.openPage 可按新版参数调用 | 当前只注册 applet.openPage，未注册新版 doubao.openPage | iOS 无法调用该 API | packages/open-api/src/router/open-page.ts; ai-sdk/ios/AISDK/Sources/JSBridge/Methods/Route/AIBridgeOpenPageMethod.swift; ai-sdk/ios/AISDK/Sources/Core/AISDK.swift | 注册独立的 doubao.openPage handler 并实现新版路由语义
+ * @platformSupport Android | unsupported | 当前版本尚未提供新版 openPage 路由协议。
+ * @platformSupport iOS | unsupported | 当前版本尚未提供新版 openPage 路由协议。
+ * @platformSupport PC | unsupported | 当前未提供该平台实现。
+ * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
+ * @permission none | - | none | Android,iOS | 无需额外权限
+ * @precondition All | 无额外前置条件
+ * @usageNote All | mode 省略时按 push 处理；对话流卡片中始终重新打开全页，全页中才应用页面栈操作。
+ * @errorCode none | - | - | Android,iOS | 当前没有可审计的新版 Native 失败字段 | 等待 Native 实现后补充错误处理
+ *
+ * @public
+ */
+export declare const openPage: (params: OpenPageParams) => Promise<object>;
+
+/**
+ * 打开页面时使用的页面栈操作。
+ *
+ * @public
+ */
+export declare type OpenPageMode = 'push' | 'replace' | 'navigate' | 'popTo';
+
+/** @public */
+export declare interface OpenPageParams {
+    /** 应用内页面路径，可携带查询参数。 */
+    url: string;
+    /**
+     * 页面栈操作。
+     *
+     * - `push`：始终压入新的页面实例。
+     * - `replace`：目标为栈顶页面时更新栈顶页面，否则替换栈顶页面。
+     * - `navigate`：目标已在栈中时回退到最近的目标页面并更新，否则压入新页面。
+     * - `popTo`：目标已在栈中时回退到最近的目标页面并更新，否则替换栈顶页面。
+     *
+     * @default 'push'
+     */
+    mode?: OpenPageMode;
+}
+
 /**
  * 打开智能服务授权设置页面
  *
@@ -6616,7 +7236,7 @@ export declare interface OpenLocationParams {
  * @returns Promise 对象，设置页关闭后返回最新授权设置
  * @remarks
  * 该接口不要求在用户点击事件中调用。
- * 注意：当前宿主暂不支持订阅模板，传入 `withSubscriptions: true` 时会由宿主返回失败，错误信息为 `subscription templates are not supported yet`。
+ * JavaScript 调用方也不要传入 `withSubscriptions: true`，否则豆包会返回 `subscription templates are not supported yet`。
  * @example
  * ```typescript
  * import { openSetting } from '@doubao-dev/framework/api';
@@ -6668,10 +7288,104 @@ export declare interface OpenSettingOptions {
 export declare interface OpenSettingResult {
     /** 用户授权结果，key 为权限 scope，value 表示是否已授权 */
     authSetting: AuthSetting;
-    /** 用户订阅消息设置，withSubscriptions 为 true 时才会返回 */
+    /** 预留的订阅消息设置字段。豆包当前仅支持 `withSubscriptions: false`，因此不会返回该字段。 */
     subscriptionsSetting?: SubscriptionsSetting;
 }
 
+/** @public */
+declare interface Performance_2 {
+    /**
+     * 创建性能观察者。调用返回对象的 `observe` 后，回调会接收之后新完成且匹配的 Entry。
+     */
+    createObserver: (callback: PerformanceObserverCallback_2) => PerformanceObserver_2;
+    /** 设置客户端最多保留的性能 Entry 数量。 */
+    setBufferSize: (size: number) => void;
+    /** 返回当前智能服务已记录的全部性能 Entry。 */
+    getEntries: () => PerformanceEntry_2[];
+    /** 返回指定 entryType 的性能 Entry。 */
+    getEntriesByType: (entryType: string) => PerformanceEntry_2[];
+    /** 返回指定名称的性能 Entry；传入 entryType 时同时按类型筛选。 */
+    getEntriesByName: (name: string, entryType?: string) => PerformanceEntry_2[];
+}
+export { Performance_2 as Performance }
+
+/** @public */
+declare interface PerformanceEntry_2 {
+    /** 性能指标所属类别。 */
+    entryType: PerformanceEntryType;
+    /** 性能指标名称，例如 `appLaunch`、`route`、`evaluateScript` 或 `firstRender`。 */
+    name: string;
+    /** 指标开始或发生时刻的 Unix 时间戳，单位为毫秒。 */
+    startTime: number;
+    /** 指标持续时间，单位为毫秒；仅耗时类指标提供。 */
+    duration?: number;
+    /** 页面路径；仅页面的 navigation 和 render 类型指标提供。 */
+    path?: string;
+    /** `path` 对应的页面实例 Id（随机生成，不保证递增）；仅页面相关指标提供。 */
+    pageId?: number;
+    /** 路由来源页面的路径；仅 `navigation / route` 指标提供。 */
+    referrerPath?: string;
+    /** 路由来源页面的实例 ID；仅 `navigation / route` 指标提供。 */
+    referrerPageId?: number;
+    /** 路由开始被渲染层处理的 Unix 时间戳，单位为毫秒；仅 navigation 类型指标提供。 */
+    navigationStart?: number;
+    /** 路由类型。仅 navigation 类型的 Entry 有效。 */
+    navigationType?: string;
+    /** 被执行脚本的模块名称；仅 `script / evaluateScript` 指标提供。 */
+    moduleName?: string;
+    /** 视图层准备完成的 Unix 时间戳，单位为毫秒；仅 `render / firstRender` 指标提供。 */
+    viewLayerReadyTime?: number;
+    /** 视图层首次渲染开始的 Unix 时间戳，单位为毫秒；仅 `render / firstRender` 指标提供。 */
+    viewLayerRenderStartTime?: number;
+    /** 视图层首次渲染结束的 Unix 时间戳，单位为毫秒；仅 `render / firstRender` 指标提供。 */
+    viewLayerRenderEndTime?: number;
+    /** Widget 标识；仅 Widget 的 render 类型指标提供。 */
+    widgetId?: string;
+    /** Widget 实例 Id（随机生成，不保证递增）；仅 Widget 的 render 类型指标提供。 */
+    widgetInstanceId?: string;
+    /** Widget 关联的应用是否冷启动；仅 Widget 的 render 类型指标提供。 */
+    isAppColdLaunch?: boolean;
+}
+export { PerformanceEntry_2 as PerformanceEntry }
+
+/** @public */
+export declare type PerformanceEntryType = 'navigation' | 'script' | 'render';
+
+/** @public */
+declare interface PerformanceObserver_2 {
+    observe(options: PerformanceObserverOptions): void;
+    disconnect(): void;
+}
+export { PerformanceObserver_2 as PerformanceObserver }
+
+/** @public */
+declare type PerformanceObserverCallback_2 = (entryList: PerformanceObserverEntryList_2) => void;
+export { PerformanceObserverCallback_2 as PerformanceObserverCallback }
+
+/** @public */
+declare interface PerformanceObserverEntryList_2 {
+    getEntries(): PerformanceEntry_2[];
+    getEntriesByType(entryType: string): PerformanceEntry_2[];
+    getEntriesByName(name: string, entryType?: string): PerformanceEntry_2[];
+}
+export { PerformanceObserverEntryList_2 as PerformanceObserverEntryList }
+
+/** @public */
+export declare interface PerformanceObserverOptions {
+    entryTypes: string[];
+}
+
+/**
+ * 系统日历精细授权状态。
+ *
+ * 继承 {@link BasicAuthorizationDetail} 的全部取值，并增加：
+ * - `read only`：只能读取日历，不能新增、修改或删除日程；仅 Android 支持。
+ * - `write only`：只能新增日程，不能读取现有日历数据。
+ *
+ * @public
+ */
+export declare type PhoneCalendarAuthorizationDetail = BasicAuthorizationDetail | 'read only' | 'write only';
+
 /**
  * 插件账号信息（仅在插件中调用时包含）。
  *
@@ -6723,7 +7437,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 +7864,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 +7899,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 +8084,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 +8149,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 +8217,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 +8453,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 +8532,7 @@ export declare type Scope = 'scope.userLocation' | 'scope.userFuzzyLocation' | '
 export declare type SelectedMessageFileType = 'video' | 'image' | 'file';
 
 /**
- * 以用户身份发送后续消息，触发新一轮对话或 API 调用。
+ * 以用户身份发送后续消息，触发新一轮对话、API 调用或引导模型响应。
  *
  * @param params - 要发送的后续消息内容。
  * @returns 返回一个 Promise，在消息发送请求提交后解析。
@@ -7782,6 +8553,13 @@ export declare type SelectedMessageFileType = 'video' | 'image' | 'file';
  *         name: 'selectDrink',
  *         arguments: { drinkId: 'latte_001' }
  *       }
+ *     },
+ *     {
+ *       type: 'responseHint',
+ *       data: {
+ *         userAction: '用户选择了拿铁',
+ *         responseGuidance: '确认已选择拿铁，并询问是否需要调整杯型'
+ *       }
  *     }
  *   ]
  * });
@@ -7823,7 +8601,7 @@ export declare interface SendFollowUpMessageParams {
  *
  * @param params - 消息内容及类型。
  * @returns 返回一个 Promise，在消息成功发送时解析。
- * @deprecated 使用 {@link dispatchActionDirective} 描述用户行为并约束模型后续动作。
+ * @deprecated 使用 {@link sendFollowUpMessage} 发送后续消息。
  * @summary 以用户身份发送消息。
  * @example
  * ```typescript
@@ -7844,7 +8622,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 +8665,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 +8736,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 +8853,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 +8896,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 +9037,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 +9092,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 +9183,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 +9246,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
  */
@@ -8444,26 +9280,25 @@ export declare interface ShowLoadingParams {
  * ```
  *
  * @since 0.0.26
- * @contractStatus verified | 公开参数、返回动作及 Android、iOS 行为已核对一致；按钮默认文案存在平台差异，已在字段约束中说明。
- * @contractMismatch non-blocking | default | confirmText、cancelText | Android,iOS | 省略时使用统一默认文案 | Android 默认 confirm/cancel，iOS 默认 OK/Cancel | 未传文案时双端按钮文字不同，公开可选类型可承载 | ai-sdk/android/ai-sdk/src/main/java/com/bytedance/ai/bridge/method/ui/ShowModalMethod.kt; ai-sdk/ios/AISDK/Sources/JSBridge/Methods/UI/AIBridgeShowModalMethod.swift | 统一双端默认按钮文案
+ * @contractStatus verified | 参数、返回 action/content 及 Android、iOS 行为已核对一致；HarmonyOS 当前不提供实现。
  * @platformSupport Android | supported | 支持展示模态对话框。
  * @platformSupport iOS | supported | 支持展示模态对话框。
  * @platformSupport PC | unsupported | 当前未提供该平台实现。
  * @platformSupport HarmonyOS | unsupported | 当前未提供该平台实现。
  * @permission none | - | none | Android,iOS | 无需额外权限
  * @precondition All | 无额外前置条件
- * @usageNote All | content 必填；仅当 showCancel 为 true 时展示取消按钮，仅当 tapMaskToDismiss 为 true 时点击蒙层可关闭。
+ * @usageNote All | 仅当 showCancel 为 true 时展示取消按钮；仅当 tapMaskToDismiss 为 true 时点击蒙层可关闭；editable 为 true 且用户确认时返回输入 content。
  * @resultExample
  * ```json
  * {
  *   "action": "confirm"
  * }
  * ```
- * @errorCode none | - | - | Android,iOS | 无 API 专属错误码 | 无需处理
+ * @errorCode common | 102 | Android,iOS
  *
  * @public
  */
-export declare const showModal: (params: ShowModalParams) => Promise<ShowModalResult>;
+export declare const showModal: (params?: ShowModalParams | undefined) => Promise<ShowModalResult>;
 
 /**
  * 显示模态对话框的参数。
@@ -8476,25 +9311,50 @@ export declare interface ShowModalParams {
      * @default -
      */
     title?: string;
-    /** 模态对话框的内容。 */
-    content: string;
+    /**
+     * 模态对话框的内容。
+     * @default -
+     */
+    content?: string;
     /**
      * 是否显示取消按钮。
      * @default true
      */
     showCancel?: boolean;
     /**
-     * 取消按钮的文字，省略时使用平台默认文案。
-     * @default -
-     * @constraint Android 默认文案为“cancel”，iOS 默认文案为“Cancel”，需统一时请显式传入。
+     * 取消按钮的文字。
+     * @default 取消
+     * @constraint 最多 4 个字符。
      */
     cancelText?: string;
     /**
-     * 确认按钮的文字，省略时使用平台默认文案。
-     * @default -
-     * @constraint Android 默认文案为“confirm”，iOS 默认文案为“OK”，需统一时请显式传入。
+     * 取消按钮的文字颜色。
+     * @default #000000
+     * @constraint 必须是 16 进制格式的颜色字符串。
+     */
+    cancelColor?: string;
+    /**
+     * 确认按钮的文字。
+     * @default 确定
+     * @constraint 最多 4 个字符。
      */
     confirmText?: string;
+    /**
+     * 确认按钮的文字颜色。
+     * @default #F85959
+     * @constraint 必须是 16 进制格式的颜色字符串。
+     */
+    confirmColor?: string;
+    /**
+     * 是否显示输入框。
+     * @default false
+     */
+    editable?: boolean;
+    /**
+     * 显示输入框时的提示文本。
+     * @default -
+     */
+    placeholderText?: string;
     /**
      * 是否允许点击蒙层关闭对话框。
      * @default true
@@ -8510,22 +9370,17 @@ export declare interface ShowModalParams {
 export declare interface ShowModalResult {
     /** 用户点击的动作。 */
     action: 'confirm' | 'cancel' | 'mask';
+    /** `editable` 为 true 时，用户点击确认后输入的文本。 */
+    content?: string;
 }
 
 /**
  * 显示 Toast 提示。
  *
- * 参数 `options` 包含以下字段：
- * - `message`：提示的内容。
- * - `type`：Toast 的类型，可选值为 'default'、'success'、'error' 或 'warning'。
- * - `duration`：提示的延迟时间，单位毫秒，默认为 2000。
- * - `icon`：图标，可选值为 'success'、'error'、'warn'。
- * - `customIcon`：自定义图标的 URL 或 base64 字符串。
- *
  * @summary 显示 Toast 提示。
  * @returns 返回一个 Promise，在 Toast 显示结束时 resolve。
  * @remarks
- * duration 和 icon 可控制提示表现。
+ * Android 默认显示 3000 毫秒，iOS 默认显示 2000 毫秒；需要双端一致时请显式传入 `duration`。
  * @example
  * ```typescript
  * import { showToast } from '@doubao-dev/framework/api';
@@ -8562,7 +9417,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
  * */
@@ -8579,8 +9444,8 @@ export declare interface ShowToastParams {
     type?: 'default' | 'success' | 'error' | 'warning';
     /**
      * 提示的持续时间，单位毫秒。
-     * @default -
-     * @constraint Android 默认 3000，iOS 默认 2000，需双端一致时请显式传入。
+     * @default Android 3000，iOS 2000
+     * @constraint 需双端保持一致时请显式传入。
      */
     duration?: number;
     /**
@@ -8601,7 +9466,7 @@ export declare interface ShowToastParams {
  * @param params - `createSignOrder` 返回的平台签约订单号。
  * @returns 签约页面流程正常返回时解析为空对象；该结果不代表签约成功。
  * @remarks
- * 如果用户尚未绑定抖音账号，宿主可能先拉起账号绑定流程，再继续展示签约页面。
+ * 如果用户尚未绑定抖音账号，豆包可能先拉起账号绑定流程，再继续展示签约页面。
  *
  * 用户的最终签约状态必须以业务服务端查询签约单详情或收到的签约结果回调为准。
  * 业务服务端还需要维护业务用户与签约 ID 的对应关系。
@@ -8643,8 +9508,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
@@ -8699,7 +9574,7 @@ export declare interface SocketTask {
     /**
      * 表示 Socket 正在连接。
      *
-     * `connectSocket` 刚返回且宿主尚未完成握手时通常处于该状态。
+     * `connectSocket` 刚返回且豆包客户端尚未完成握手时通常处于该状态。
      */
     readonly CONNECTING: 0;
     /**
@@ -8711,7 +9586,7 @@ export declare interface SocketTask {
     /**
      * 表示 Socket 连接关闭中。
      *
-     * 调用 {@link SocketTask.close} 后、本地等待宿主侧完成关闭流程时通常处于该状态。
+     * 调用 {@link SocketTask.close} 后，等待豆包客户端完成关闭流程时通常处于该状态。
      */
     readonly CLOSING: 2;
     /**
@@ -8724,7 +9599,7 @@ export declare interface SocketTask {
      * 当前 Socket 连接状态 code。
      *
      * 可与 `CONNECTING`、`OPEN`、`CLOSING`、`CLOSED` 常量比较。
-     * 如果因为参数错误等原因导致连接请求没有被宿主成功创建，则为 `undefined`。
+     * 如果因为参数错误等原因导致豆包客户端没有成功创建连接，则为 `undefined`。
      */
     readonly readyState: number | undefined;
     /**
@@ -8776,7 +9651,7 @@ export declare interface SocketTask {
 /**
  * WebSocket 关闭事件。
  *
- * 当前连接被主动关闭、服务端关闭或宿主侧因异常回收连接时触发。
+ * 当前连接被主动关闭、服务端关闭或豆包客户端因异常回收连接时触发。
  * 触发后 `readyState` 会变为 `SocketTask.CLOSED`，该 `SocketTask` 不应再继续发送数据。
  *
  * @public
@@ -8785,31 +9660,31 @@ export declare interface SocketTaskCloseEvent {
     /**
      * 关闭状态码。
      *
-     * 可能来自调用 {@link SocketTask.close} 时传入的 `code`，也可能来自服务端或宿主侧。
+     * 可能来自调用 {@link SocketTask.close} 时传入的 `code`，也可能来自服务端或豆包客户端。
      */
     code?: number;
     /**
      * 关闭原因。
      *
-     * 可能来自调用 {@link SocketTask.close} 时传入的 `reason`，也可能来自服务端或宿主侧。
+     * 可能来自调用 {@link SocketTask.close} 时传入的 `reason`，也可能来自服务端或豆包客户端。
      */
     reason?: string;
     /**
      * 错误信息。
      *
-     * 非正常关闭时宿主侧可能通过该字段补充失败原因；正常关闭时通常为空。
+     * 非正常关闭时豆包客户端可能通过该字段补充失败原因；正常关闭时通常为空。
      */
     errMsg?: string;
     /**
      * 当前连接使用的网络传输层协议。
      *
-     * 该字段由宿主侧返回，部分运行环境可能不提供。
+     * 该字段由豆包客户端返回，部分运行环境可能不提供。
      */
     protocolType?: string;
     /**
-     * 宿主侧使用的 WebSocket 实现类型。
+     * 豆包客户端使用的 WebSocket 实现类型。
      *
-     * 该字段由宿主侧返回，部分运行环境可能不提供。
+     * 该字段由豆包客户端返回，部分运行环境可能不提供。
      */
     socketType?: string;
 }
@@ -8826,10 +9701,10 @@ export declare interface SocketTaskCloseParams {
     /**
      * 关闭连接状态码。
      *
-     * 不传时由宿主侧按正常关闭处理，通常等价于 `1000`。
+     * 不传时由豆包客户端按正常关闭处理，通常等价于 `1000`。
      * 常见值包括：
      * - `1000`: 正常关闭；
-     * - `1001`: 因页面进入后台、宿主回收连接等原因关闭。
+     * - `1001`: 因页面进入后台、豆包客户端回收连接等原因关闭。
      */
     code?: number;
     /**
@@ -8852,7 +9727,7 @@ export declare interface SocketTaskErrorEvent {
     /**
      * 错误信息。
      *
-     * 由前端参数校验、编码过程或宿主侧返回的失败原因组成，可直接用于日志上报。
+     * 由前端参数校验、编码过程或豆包客户端返回的失败原因组成，可直接用于日志上报。
      */
     errMsg: string;
 }
@@ -8878,13 +9753,13 @@ export declare interface SocketTaskMessageEvent {
     /**
      * 当前消息所属连接使用的协议。
      *
-     * 该字段由宿主侧返回，部分运行环境可能不提供。
+     * 该字段由豆包客户端返回，部分运行环境可能不提供。
      */
     protocolType?: string;
     /**
-     * 宿主侧使用的 WebSocket 实现类型。
+     * 豆包客户端使用的 WebSocket 实现类型。
      *
-     * 该字段由宿主侧返回，部分运行环境可能不提供。
+     * 该字段由豆包客户端返回，部分运行环境可能不提供。
      */
     socketType?: string;
 }
@@ -8892,7 +9767,7 @@ export declare interface SocketTaskMessageEvent {
 /**
  * WebSocket 连接成功事件。
  *
- * 当宿主侧完成 WebSocket 握手并进入 open 状态后触发。
+ * 当豆包客户端完成 WebSocket 握手并进入 open 状态后触发。
  * 收到该事件后，调用方可以开始通过 {@link SocketTask.send} 发送数据。
  *
  * @public
@@ -8908,13 +9783,13 @@ export declare interface SocketTaskOpenEvent {
     /**
      * 当前连接使用的网络传输层协议。
      *
-     * 该字段由宿主侧返回，部分运行环境可能不提供。
+     * 该字段由豆包客户端返回，部分运行环境可能不提供。
      */
     protocolType?: string;
     /**
-     * 宿主侧使用的 WebSocket 实现类型。
+     * 豆包客户端使用的 WebSocket 实现类型。
      *
-     * 可能的值由宿主实现决定，例如传统 WebSocket 实现或宿主网络库实现；
+     * 可能的值由豆包客户端实现决定，例如系统 WebSocket 实现或豆包网络库实现；
      * 部分运行环境可能不提供。
      */
     socketType?: string;
@@ -8933,7 +9808,7 @@ export declare interface SocketTaskSendParams {
      * 需要发送给服务端的数据。
      *
      * - 传入 `string` 时按文本消息发送；
-     * - 传入 `ArrayBuffer` 时按二进制消息发送，内部会编码后交给宿主侧处理。
+     * - 传入 `ArrayBuffer` 时按二进制消息发送，内部会编码后交给豆包客户端处理。
      *
      * 建议只在 `onOpen` 回调触发后调用 `send`，此时 `readyState` 通常为 `SocketTask.OPEN`。
      */
@@ -8965,7 +9840,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 +10028,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 +10067,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 +10121,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 +10183,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 +10241,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 +10500,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 +10539,7 @@ export declare function stopLocationUpdate(): Promise<LocationOperationResult>;
  * ```json
  * {}
  * ```
- * @errorCode none | - | - | Android,iOS | 当前实现未稳定返回顶层 errNo/errMsg | 根据返回的错误信息重试
+ * @errorCode none | - | - | Android,iOS | 该接口双端恒返回成功，无 API 专属错误码 | 无需处理
  *
  * @public
  */
@@ -9754,6 +10694,18 @@ export declare interface ThemeChangeEvent {
  */
 export declare type ThemeChangeListener = (event: ThemeChangeEvent) => void;
 
+/**
+ * Tool 返回的标准内容。
+ *
+ * @public
+ */
+export declare interface ToolResult {
+    /** Tool 返回的内容块。 */
+    content?: Array<Record<string, unknown>>;
+    /** Tool 返回的结构化内容。 */
+    structuredContent?: unknown;
+}
+
 /**
  * {@link FileSystemManager.truncate} 的参数。
  *
@@ -9777,6 +10729,18 @@ export declare interface TruncateParams {
 
 declare type TypeGuard<From, To extends From> = (from: From) => from is To;
 
+/**
+ * 尚未获得权限时的精细状态。
+ *
+ * 取值说明：
+ * - `not determined`：系统明确表示用户尚未作出选择
+ * - `denied`：当前没有权限；可能是用户拒绝、关闭权限，或平台无法进一步区分拒绝原因
+ * - `restricted`：系统明确表示权限受设备管理、家长控制等策略限制，用户无法直接修改
+ *
+ * @public
+ */
+export declare type UnauthorizedDetail = 'not determined' | 'denied' | 'restricted';
+
 /**
  * {@link FileSystemManager.unlink} 的参数。
  *
@@ -9839,7 +10803,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 +10876,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
  */
@@ -9978,7 +10969,7 @@ export declare interface UpdateWidgetParams {
  * @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 | 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
@@ -10011,14 +11002,14 @@ export declare function uploadFile(params: UploadFileParams): UploadTask;
  * @public
  */
 export declare interface UploadFileParams {
-    /** 开发者服务器地址，需为完整的 HTTP/HTTPS URL，并通过宿主侧上传域名白名单校验。 */
+    /** 开发者服务器地址，需为完整的 HTTP/HTTPS URL，并通过豆包配置的上传域名白名单校验。 */
     url: string;
     /** 要上传文件资源的本地路径。 */
     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 -
      */
@@ -10030,7 +11021,7 @@ export declare interface UploadFileParams {
      */
     formData?: Record<string, unknown>;
     /**
-     * 超时时间，单位 ms；不传时使用宿主侧默认超时配置。
+     * 超时时间，单位 ms；不传时使用豆包客户端的默认超时配置。
      *
      * @default -
      */
@@ -10072,7 +11063,7 @@ export declare interface UploadTask extends Promise<UploadFileResult> {
     /**
      * 监听上传进度变化。
      *
-     * 同一个任务可以注册多个回调，每次收到宿主进度事件时依次调用。
+     * 同一个任务可以注册多个回调，每次收到豆包客户端的进度事件时依次调用。
      */
     onProgressUpdate: (callback: (event: UploadTaskProgressUpdateEvent) => void) => void;
     /**
@@ -10084,7 +11075,7 @@ export declare interface UploadTask extends Promise<UploadFileResult> {
     /**
      * 监听 HTTP Response Header 事件。
      *
-     * 同一个任务可以注册多个回调，宿主收到上传响应头时依次调用。
+     * 同一个任务可以注册多个回调，豆包客户端收到上传响应头时依次调用。
      */
     onHeadersReceived: (callback: (event: UploadTaskHeadersReceivedEvent) => void) => void;
     /**
@@ -10183,7 +11174,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 +11214,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
  */