@doubao-apps/ai 0.0.34 → 0.0.35

package/dist/{skills → public/skills}/doubao-apps-dev/references/reference/open-api/07-/350/276/223/345/205/245.md

@@ -9,6 +9,7 @@
 | API | 说明 |
 | --- | --- |
 | [hideKeyboard](#hidekeyboard) | 收起当前键盘。 |
+| [onKeyboardHeightChange](#onkeyboardheightchange) | 监听键盘高度变化事件。 |
 | [getSelectedTextRange](#getselectedtextrange) | 获取当前输入框的选区范围。 |
 
 ## API 详情
@@ -34,6 +35,33 @@ await hideKeyboard({});
 
 返回 `Promise<object>`。
 
+<a id="onkeyboardheightchange"></a>
+### onKeyboardHeightChange()
+
+监听键盘高度变化事件。
+
+## 代码示例
+
+```typescript
+import { onKeyboardHeightChange } from '@doubao-apps/framework/api';
+
+const unsubscribe = onKeyboardHeightChange(({ height }) => {
+  console.log('Keyboard height change event:', { height });
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|handler|`Function`|是|-|
+|handler.event|`KeyboardHeightChangeEvent`|是|-|
+|handler.event.height|`number`|是|键盘高度，单位 px。|
+
+## 返回值
+
+返回 `Function`。
+
 <a id="getselectedtextrange"></a>
 ### getSelectedTextRange()
 
@@ -61,3 +89,22 @@ console.log(start, end);
 |---|---|---|
 |end|`number`|选区结束位置。|
 |start|`number`|选区起始位置。|
+
+## 相关类型
+
+<a id="keyboardheightchangeevent"></a>
+### KeyboardHeightChangeEvent
+
+#### Properties
+
+• **height**: `number` - 键盘高度，单位 px
+
+<a id="getselectedtextrangeresult"></a>
+### GetSelectedTextRangeResult
+
+获取输入框选区范围的返回结果。
+
+#### Properties
+
+• **start**: `number` - 选区起始位置
+• **end**: `number` - 选区结束位置

package/dist/public/skills/doubao-apps-dev/references/reference/open-api/08-/347/275/221/347/273/234.md

@@ -0,0 +1,238 @@
+# Open API: 网络
+
+网络请求与 WebSocket。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [request](#request) | 发起网络请求。 |
+| [connectSocket](#connectsocket) | 创建一个 WebSocket 连接，并返回可操作该连接的 SocketTask。 |
+
+## API 详情
+
+<a id="request"></a>
+### request()
+
+发起网络请求。
+
+`request` 本身不接受泛型参数；如需业务数据类型，请读取 `result.data` 后再做类型收窄或断言。
+
+## 代码示例
+
+```typescript
+import { request } from '@doubao-apps/framework/api';
+
+const result = await request({
+  url: 'https://postman-echo.com/post',
+  method: 'POST',
+  dataType: 'json',
+  header: { 'content-type': 'application/json' },
+  data: { hello: 'world' }
+});
+
+console.log(result.statusCode, result.data);
+```
+
+## 注意事项
+
+返回 statusCode、header 和 data。
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|data|`string | Record<string, any> | ArrayBuffer`|否|请求体数据。<br><br>传给服务器的数据最终会是 `String` 或 `ArrayBuffer`：<br>- 若 `data` 是 `string` 或 `ArrayBuffer`，直接使用；<br>- 若 `header['content-type']` 是 `application/x-www-form-urlencoded`，会被编码为 query string，例如：`encodeURIComponent(k)=encodeURIComponent(v)`；<br>- 若 `header['content-type']` 是 `application/json`，会执行 JSON 序列化；<br>- 若 `data` 是普通对象且未命中上述类型，也会执行 JSON 序列化；<br>- 其他类型会调用 `toString()`|
+|dataType|`"string" | "json"`|否|期望返回的数据格式。<br>- `json`: 尝试按 JSON 解析；<br>- `string`: 按字符串返回。|
+|header|`Record<string, string>`|否|请求 Header。|
+|method|`RequestMethod`|否|请求方法。|
+|url|`string`|是|请求地址，需为完整的 **HTTPS** URL。|
+
+**类型说明**
+
+- `RequestMethod`: `"GET" | "POST" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT"`
+
+## 返回值
+
+返回一个 Promise，解析为 RequestResponse。
+
+|字段名|类型|说明|
+|---|---|---|
+|data|`string | Record<string, any> | ArrayBuffer`|响应数据，类型由 `dataType` 决定。|
+|header|`Record<string, string>`|HTTP 响应头。|
+|statusCode|`number`|HTTP 状态码。|
+
+<a id="connectsocket"></a>
+### connectSocket()
+
+创建一个 WebSocket 连接，并返回可操作该连接的 SocketTask。
+
+该 API 会同步返回 `SocketTask`，但连接创建本身是异步过程。调用方应先在返回的
+`SocketTask` 上注册事件回调，再等待 `onOpen` 表示连接可用。后续发送消息使用
+`SocketTask.send`，关闭连接使用 `SocketTask.close`。
+
+## 代码示例
+
+```typescript
+import { connectSocket } from '@doubao-apps/framework/api';
+
+const socketTask = connectSocket({
+  url: 'wss://example.com/socket',
+  header: { authorization: 'Bearer token' },
+  protocols: ['chat.v1']
+});
+
+socketTask.onOpen(() => {
+  socketTask.send({ data: 'hello' });
+});
+
+socketTask.onMessage((event) => {
+  console.log(event.data);
+});
+
+socketTask.onClose((event) => {
+  console.log(event.code, event.reason);
+});
+
+socketTask.onError((event) => {
+  console.error(event.errMsg);
+});
+```
+
+## 注意事项
+
+- 返回 `SocketTask` 不代表连接已经成功，连接成功以 `onOpen` 为准。
+- `send` 必须接收对象参数，并把要发送的内容放在 `data` 字段中。
+- 如果 `protocols` 非空，需要服务端支持并返回匹配的子协议。
+- 多次调用会创建多条连接，旧连接不会自动关闭；不再使用时应主动调用 `close`。
+- 连接失败、发送失败或关闭失败会通过 `SocketTask.onError` 通知。
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|header|`Record<string, string>`|否|WebSocket 握手阶段携带的 HTTP Header。<br><br>适合放置业务自定义 Header，例如鉴权 token、trace id、客户端能力标识等。<br>`referer` 由宿主侧统一生成和管理，不应依赖该字段被业务传入值覆盖。|
+|protocols|`string[]`|否|WebSocket 子协议数组。<br><br>会作为握手请求中的 `Sec-WebSocket-Protocol` 候选值传给服务端。<br>如果传入非空数组，服务端需要选择其中一个协议并在握手响应中返回；<br>服务端不支持或不返回匹配协议时，连接可能被宿主判定为创建失败。|
+|url|`string`|是|WebSocket 连接地址。<br><br>需要包含协议、域名、路径和可选 query，例如 `wss://example.com/socket?room=1`。<br>如果地址为空或不是字符串，本 API 会返回 `readyState` 为 `undefined` 的 SocketTask，<br>并异步触发 `onError`。|
+
+## 返回值
+
+当前 WebSocket 连接对应的 SocketTask。
+
+|字段名|类型|说明|
+|---|---|---|
+|CLOSED|`3`|表示 Socket 连接已关闭。<br><br>进入该状态后，该任务不会再收到新的消息，也不应继续调用 `send`。|
+|CLOSING|`2`|表示 Socket 连接关闭中。<br><br>调用 SocketTask.close 后、本地等待宿主侧完成关闭流程时通常处于该状态。|
+|CONNECTING|`0`|表示 Socket 正在连接。<br><br>`connectSocket` 刚返回且宿主尚未完成握手时通常处于该状态。|
+|OPEN|`1`|表示 Socket 连接已经打开。<br><br>进入该状态后可以调用 SocketTask.send 发送数据。|
+|readyState|`number | undefined`|当前 Socket 连接状态 code。<br><br>可与 `CONNECTING`、`OPEN`、`CLOSING`、`CLOSED` 常量比较。<br>如果因为参数错误等原因导致连接请求没有被宿主成功创建，则为 `undefined`。|
+|close|`(params?: SocketTaskCloseParams) => void`|-|
+|onClose|`(callback: Function) => void`|-|
+|onError|`(callback: Function) => void`|-|
+|onMessage|`(callback: Function) => void`|-|
+|onOpen|`(callback: Function) => void`|-|
+|send|`(params: SocketTaskSendParams) => void`|-|
+
+## 相关类型
+
+<a id="requestmethod"></a>
+### RequestMethod
+
+#### Type
+
+`'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE' | 'CONNECT'`
+
+<a id="requestresponse"></a>
+### RequestResponse
+
+网络请求返回结果。
+
+#### Properties
+
+• **statusCode**: `number` - HTTP 状态码
+• **header**: `Record<string, string>` - HTTP 响应头
+• **data?**: `string | ArrayBuffer | Record<string, any>` - 响应数据，类型由 dataType 决定
+
+<a id="sockettasksendparams"></a>
+### SocketTaskSendParams
+
+SocketTask.send 的参数。 send 只负责向已打开的 WebSocket 连接写入一条消息，不返回 Promise。 发送失败、连接未就绪或底层通道异常时，会通过同一个 SocketTask 的 onError 回调通知。
+
+#### Properties
+
+• **data**: `string | ArrayBuffer` - 需要发送给服务端的数据。 - 传入 string 时按文本消息发送； - 传入 ArrayBuffer 时按二进制消息发送，内部会编码后交给宿主侧处理。 建议只在 onOpen 回调触发后调用 send，此时 readyState 通常为 SocketTask.OPEN
+
+<a id="sockettaskcloseparams"></a>
+### SocketTaskCloseParams
+
+SocketTask.close 的参数。 close 用于主动关闭当前 WebSocket 连接。调用后 readyState 会先进入 SocketTask.CLOSING，最终关闭结果通过 onClose 或 onError 回调通知。
+
+#### Properties
+
+• **code?**: `number` - 关闭连接状态码。 不传时由宿主侧按正常关闭处理，通常等价于 1000。 常见值包括： - 1000: 正常关闭； - 1001: 因页面进入后台、宿主回收连接等原因关闭
+• **reason?**: `string` - 连接被关闭的原因。 该字段会随关闭帧传递给服务端，是否被服务端记录或回传取决于服务端实现
+
+<a id="sockettask"></a>
+### SocketTask
+
+通过 connectSocket 获取的 WebSocket 任务实例。 SocketTask 表示单条 WebSocket 连接的控制对象。它负责发送数据、关闭连接， 并通过事件回调接收连接状态、服务端消息和错误通知。connectSocket 返回时连接 仍可能处于创建中，调用方应先注册 onOpen、onError、onClose、onMessage 等回调，再根据 onOpen 事件发送业务数据。
+
+#### Properties
+
+• **CONNECTING**: `0` - 表示 Socket 正在连接。 connectSocket 刚返回且宿主尚未完成握手时通常处于该状态
+• **OPEN**: `1` - 表示 Socket 连接已经打开。 进入该状态后可以调用 SocketTask.send 发送数据
+• **CLOSING**: `2` - 表示 Socket 连接关闭中。 调用 SocketTask.close 后、本地等待宿主侧完成关闭流程时通常处于该状态
+• **CLOSED**: `3` - 表示 Socket 连接已关闭。 进入该状态后，该任务不会再收到新的消息，也不应继续调用 send
+• **readyState**: `number | undefined` - 当前 Socket 连接状态 code。 可与 CONNECTING、OPEN、CLOSING、CLOSED 常量比较。 如果因为参数错误等原因导致连接请求没有被宿主成功创建，则为 undefined
+• **send**: `(params: SocketTaskSendParams) => void` - 通过 WebSocket 连接发送数据。 该方法只发起发送动作，不返回发送结果。建议在 readyState === SocketTask.OPEN 或收到 onOpen 事件后调用；如果连接未就绪、数据编码失败或宿主侧发送失败， 会触发 onError
+• **close**: `(params?: SocketTaskCloseParams) => void` - 关闭 WebSocket 连接。 调用后会尝试向宿主侧发起关闭动作，并把 readyState 置为 SocketTask.CLOSING。 最终关闭完成时触发 onClose；关闭动作失败时触发 onError
+• **onOpen**: `(callback: (event: SocketTaskOpenEvent) => void) => void` - 监听 WebSocket 连接服务器成功的事件。 可以注册多个回调。连接成功后触发回调，并携带握手响应 Header、协议类型等信息。 通常应在该回调中或之后调用 SocketTask.send
+• **onClose**: `(callback: (event: SocketTaskCloseEvent) => void) => void` - 监听 WebSocket 与服务器连接断开的事件。 主动关闭、服务端关闭、宿主侧回收连接都可能触发该回调。 回调触发后当前任务会从内部连接表移除
+• **onMessage**: `(callback: (event: SocketTaskMessageEvent) => void) => void` - 监听 WebSocket 接收到服务器发送信息的事件。 服务端每下发一条消息都会触发一次回调。消息内容通过 event.data 返回， 类型可能是 string 或 ArrayBuffer
+• **onError**: `(callback: (event: SocketTaskErrorEvent) => void) => void` - 监听 WebSocket 发生错误的事件。 连接创建、发送、关闭或底层通道出现异常时触发。 该回调只表示发生错误，不等同于连接一定已经关闭；是否关闭应结合 readyState 或后续 onClose 事件判断
+
+<a id="sockettaskopenevent"></a>
+### SocketTaskOpenEvent
+
+WebSocket 连接成功事件。 当宿主侧完成 WebSocket 握手并进入 open 状态后触发。 收到该事件后，调用方可以开始通过 SocketTask.send 发送数据。
+
+#### Properties
+
+• **header**: `Record<string, string>` - WebSocket 握手响应中的 Response Header。 不同平台对 Header key 的大小写处理可能不同，读取时建议按业务需要做兼容
+• **protocolType?**: `string` - 当前连接使用的网络传输层协议。 该字段由宿主侧返回，部分运行环境可能不提供
+• **socketType?**: `string` - 宿主侧使用的 WebSocket 实现类型。 可能的值由宿主实现决定，例如传统 WebSocket 实现或宿主网络库实现； 部分运行环境可能不提供
+
+<a id="sockettaskmessageevent"></a>
+### SocketTaskMessageEvent
+
+WebSocket 收到服务端消息事件。 服务端通过当前连接下发消息时触发。文本消息会以 string 形式返回； 二进制消息会尽量还原为 ArrayBuffer。
+
+#### Properties
+
+• **data**: `string | ArrayBuffer` - 收到的服务端消息。 - 文本消息返回 string； - 二进制消息返回 ArrayBuffer。 如果运行环境不支持二进制解码能力，底层传回的内容可能仍保持字符串形式
+• **protocolType?**: `string` - 当前消息所属连接使用的协议。 该字段由宿主侧返回，部分运行环境可能不提供
+• **socketType?**: `string` - 宿主侧使用的 WebSocket 实现类型。 该字段由宿主侧返回，部分运行环境可能不提供
+
+<a id="sockettaskcloseevent"></a>
+### SocketTaskCloseEvent
+
+WebSocket 关闭事件。 当前连接被主动关闭、服务端关闭或宿主侧因异常回收连接时触发。 触发后 readyState 会变为 SocketTask.CLOSED，该 SocketTask 不应再继续发送数据。
+
+#### Properties
+
+• **code?**: `number` - 关闭状态码。 可能来自调用 SocketTask.close 时传入的 code，也可能来自服务端或宿主侧
+• **reason?**: `string` - 关闭原因。 可能来自调用 SocketTask.close 时传入的 reason，也可能来自服务端或宿主侧
+• **errMsg?**: `string` - 错误信息。 非正常关闭时宿主侧可能通过该字段补充失败原因；正常关闭时通常为空
+• **protocolType?**: `string` - 当前连接使用的网络传输层协议。 该字段由宿主侧返回，部分运行环境可能不提供
+• **socketType?**: `string` - 宿主侧使用的 WebSocket 实现类型。 该字段由宿主侧返回，部分运行环境可能不提供
+
+<a id="sockettaskerrorevent"></a>
+### SocketTaskErrorEvent
+
+WebSocket 错误事件。 连接创建失败、发送失败、主动关闭失败、底层通道异常等错误都会通过该事件通知。 如果错误发生在连接创建阶段，readyState 会变为 undefined 或 SocketTask.CLOSED。
+
+#### Properties
+
+• **errMsg**: `string` - 错误信息。 由前端参数校验、编码过程或宿主侧返回的失败原因组成，可直接用于日志上报

package/dist/{skills → public/skills}/doubao-apps-dev/references/reference/open-api/09-/345/252/222/344/275/223.md

@@ -63,7 +63,7 @@ await previewImage({
 
 |参数名|类型|必填|说明|
 |---|---|---|---|
-|current|`string \| number`|否|当前显示图片的链接，或当前显示图片的下标，不填则默认为 urls 中的第一张|
+|current|`string | number`|否|当前显示图片的链接，或当前显示图片的下标，不填则默认为 urls 中的第一张|
 |referrerPolicy|`string`|否|预览页使用的 Referrer 策略。|
 |showmenu|`boolean`|否|是否显示长按菜单，菜单支持保存图片至本地相册|
 |urls|`string[]`|是|需要预览的图片链接列表。|
@@ -190,3 +190,83 @@ console.log(tempFilePath);
 |字段名|类型|说明|
 |---|---|---|
 |tempFilePath|`string`|压缩后图片的临时文件路径。|
+
+## 相关类型
+
+<a id="imageorientation"></a>
+### ImageOrientation
+
+图片方向枚举。
+
+#### Type
+
+`| 'up'
+  | 'up-mirrored'
+  | 'down'
+  | 'down-mirrored'
+  | 'left-mirrored'
+  | 'right'
+  | 'right-mirrored'
+  | 'left'`
+
+<a id="getimageinforesult"></a>
+### GetImageInfoResult
+
+图片信息结果。
+
+#### Properties
+
+• **height**: `number` - 图片原始高度，单位 px，不考虑旋转
+• **orientation**: `ImageOrientation` - 图片方向
+• **path**: `string` - 图片的本地路径
+• **type**: `string` - 图片格式
+• **width**: `number` - 图片原始宽度，单位 px，不考虑旋转
+
+<a id="chooseimagesizetype"></a>
+### ChooseImageSizeType
+
+可选的图片尺寸类型。
+
+#### Type
+
+`'original' | 'compressed'`
+
+<a id="chooseimagesourcetype"></a>
+### ChooseImageSourceType
+
+可选的图片来源类型。
+
+#### Type
+
+`'album' | 'camera' | 'user' | 'environment'`
+
+<a id="chooseimagefile"></a>
+### ChooseImageFile
+
+选择图片返回的单个文件信息。
+
+#### Properties
+
+• **path**: `string` - 本地临时文件路径
+• **size**: `number` - 文件大小，单位 B
+• **type?**: `string` - 文件 MIME 类型
+• **originalFileObj?**: `File` - 原始浏览器 File 对象
+
+<a id="chooseimageresult"></a>
+### ChooseImageResult
+
+选择图片结果。
+
+#### Properties
+
+• **tempFilePaths**: `string[]` - 图片临时文件路径列表
+• **tempFiles**: `ChooseImageFile[]` - 图片临时文件信息列表
+
+<a id="compressimageresult"></a>
+### CompressImageResult
+
+压缩图片结果。
+
+#### Properties
+
+• **tempFilePath**: `string` - 压缩后图片的临时文件路径

package/dist/{skills → public/skills}/doubao-apps-dev/references/reference/open-api/10-/344/270/232/345/212/241/350/203/275/345/212/233.md

@@ -31,15 +31,22 @@
 
 ```typescript
 import { ActionDirectiveType, dispatchActionDirective } from '@doubao-apps/framework/api';
+import { getWidgetInstanceId } from '@doubao-apps/framework';
 
 await dispatchActionDirective({
-  widgetInstanceId: 'widget-instance-id',
+  widgetInstanceId: getWidgetInstanceId(),
   actionType: ActionDirectiveType.BUTTON_CLICK,
-  actionDescribe: '用户点击了支付按钮',
-  expectedAction: '继续完成支付流程'
+  actionDescribe: '用户点击支付按钮并完成话费支付',
+  expectedAction: '调用话费账单查询工具，基于工具返回回复用户'
 });
 ```
 
+## 注意事项
+
+适用于卡片交互后向模型补充结构化动作上下文，例如按钮点击、选项选择或表单提交。
+`getWidgetInstanceId` 仅在卡片环境中有效，在小程序页面中会返回 `undefined`。如果需要在页面中调用，
+请在 `navigateTo` 时通过参数传递卡片实例 ID。
+
 ## 入参
 
 |参数名|类型|必填|说明|
@@ -53,7 +60,7 @@ await dispatchActionDirective({
 |responseHint|`string`|否|自然语言描述，例如：严格参照提供的工具入参来调用工具，不要调用除bill_check以外的其他工具，只能严格基于bill_check工具返回结果进行回复|
 |toolName|`string`|否|mcp名称，如果expectedAction里预期要调用工具，需要在这里写明调用工具的mcp name|
 |toolParams|`Record<string, string>`|否|mcp入参，如果expectedAction里预期要调用工具，需要在这里写明调用工具的入参|
-|widgetInstanceId|`string`|是|会话消息关联的卡片ID|
+|widgetInstanceId|`string`|是|会话消息关联的卡片实例 ID。<br><br>在卡片环境可通过 `getWidgetInstanceId` 获取；在小程序页面等非卡片环境需要通过传参或通信传递。|
 
 ## 返回值
 
@@ -62,26 +69,36 @@ await dispatchActionDirective({
 <a id="expiredwidget"></a>
 ### expiredWidget()
 
-更新过期的 widget 为固定卡片
+更新过期的 widget 为固定卡片。
 
 ## 代码示例
 
 ```ts
+import { expiredWidget } from '@doubao-apps/framework/api';
+import { getWidgetInstanceId } from '@doubao-apps/framework';
+
 expiredWidget({
-  widgetInstanceId: 'instance_123',
+  widgetInstanceId: getWidgetInstanceId(),
   url: '${pageId}?key=value'
 });
 ```
 
+## 注意事项
+
+用于将状态已经过期的 widget 实例转换为固定卡片，用户点击后可跳转到指定页面。
+
+`getWidgetInstanceId` 仅在卡片环境中有效，在小程序页面中会返回 `undefined`。如果需要在页面中调用，
+请在 `navigateTo` 时通过参数传递卡片实例 ID。
+
 ## 入参
 
 |参数名|类型|必填|说明|
 |---|---|---|---|
 |detailText|`string`|否|点击失效卡要跳转的页面 detailText|
-|schema|`string`|否|点击失效卡要跳转的页面 schema，格式与 navigateTo 的 url 相同|
+|schema|`string`|否|点击失效卡要跳转的页面 schema，格式与 navigateTo 的 url 参数一致。<br><br>**已废弃**：使用 url 字段替代 schema 字段，后续版本将移除 schema 字段，请尽快迁移到 url 字段|
 |title|`string`|否|点击失效卡要跳转的页面 title|
-|url|`string`|否|点击失效卡要跳转的页面 url 或 sslocal schema|
-|widgetInstanceId|`string`|是|卡片实例 ID，在卡片环境通过getWidgetInstanceId来获取，其他环境（比如页面）需要通过传参或通信的方式传递过去|
+|url|`string`|否|点击失效卡要跳转的页面 URL 或 sslocal schema。小程序页面 URL 格式与 navigateTo 的 url 参数一致|
+|widgetInstanceId|`string`|是|卡片实例 ID。<br><br>在卡片环境可通过 `getWidgetInstanceId` 获取；在小程序页面等非卡片环境需要通过传参或通信传递。|
 
 ## 返回值
 
@@ -194,6 +211,10 @@ await setAdditionalContext({
 });
 ```
 
+## 注意事项
+
+设置全局上下文。
+
 ## 入参
 
 |参数名|类型|必填|说明|
@@ -231,6 +252,11 @@ const result = await createTask({
 console.log(result.taskId, result.token, result.expiresIn);
 ```
 
+## 注意事项
+
+创建任务时需要传入开发者侧唯一任务标识、任务模板、任务详情和任务类型。开发者侧唯一任务标识
+可用于幂等创建和后续业务关联。远端任务创建成功后，返回的 taskId 可用于查询或更新任务。
+
 ## 入参
 
 |参数名|类型|必填|说明|
@@ -294,6 +320,11 @@ const result = await updateTask({
 console.log(result.taskId, result.nextToken, result.expiresIn);
 ```
 
+## 注意事项
+
+更新任务时至少传入 taskStatus 或 taskDetail 中的一个。更新远端任务成功后，旧 token 会失效，
+如返回 nextToken，后续需要使用新的 token 继续更新远端任务。
+
 ## 入参
 
 |参数名|类型|必填|说明|
@@ -348,6 +379,10 @@ if (task.taskStatus === 'running') {
 }
 ```
 
+## 注意事项
+
+根据任务 ID 查询任务的模板、详情、状态和类型。若返回 token，可在后续远端任务更新中继续使用。
+
 ## 入参
 
 |参数名|类型|必填|说明|
@@ -376,7 +411,7 @@ if (task.taskStatus === 'running') {
 <a id="updatemodelcontext"></a>
 ### updateModelContext()
 
-向 Agent 捐赠上下文
+向 Agent 捐赠上下文。
 
 ## 代码示例
 
@@ -390,17 +425,22 @@ await updateModelContext({
 });
 ```
 
+## 注意事项
+
+`taskId` 可以为空，此时客户端会尝试使用 `entityId` 填充；`entityId` 可以为空，
+此时如果处于卡片环境，客户端会尝试使用卡片的 `entityId` 填充。
+
 ## 入参
 
 |参数名|类型|必填|说明|
 |---|---|---|---|
 |content|`string`|是|上下文内容，格式无约束，可以与 MCP 服务下发的上下文格式保持一致|
-|entityId|`string`|否|上下文所属的 entityID，业务侧管理|
-|taskId|`string`|否|上下文所属任务 ID，业务侧定义|
+|entityId|`string`|否|上下文所属的 entityId，业务侧管理。为空且处于卡片环境时，客户端会尝试使用卡片的 entityId 填充|
+|taskId|`string`|否|上下文所属任务 ID，业务侧定义。为空时客户端会尝试使用 entityId 填充|
 
 ## 返回值
 
-返回 `Promise<object>`。
+返回一个 Promise，在上下文成功捐赠时解析。
 
 <a id="updatewidget"></a>
 ### updateWidget()
@@ -429,3 +469,93 @@ await updateWidget({
 ## 返回值
 
 返回 `Promise<object>`。
+
+## 相关类型
+
+<a id="openappstatus"></a>
+### OpenAppStatus
+
+#### Type
+
+`'deep_link' | 'market' | 'browser'`
+
+<a id="tasktype"></a>
+### TaskType
+
+任务类型。 local 表示本地任务，remote 表示远端任务。
+
+#### Type
+
+`'local' | 'remote'`
+
+<a id="taskdisplaydata"></a>
+### TaskDisplayData
+
+任务展示数据。
+
+#### Properties
+
+• **title**: `string` - 任务标题
+• **sub_title?**: `string` - 任务副标题
+
+<a id="taskactionparams"></a>
+### TaskActionParams
+
+任务操作参数。
+
+#### Properties
+
+• **action_key?**: `string` - 操作标识
+• **page_param?**: `string` - 页面参数
+
+<a id="jumpschemadata"></a>
+### JumpSchemaData
+
+点击任务跳转的页面参数。
+
+#### Properties
+
+• **path?**: `string` - 跳转页面
+• **query?**: `string` - 页面参数，小程序内消费时会自动 base64 url encode，需要 decode
+
+<a id="taskprogressdata"></a>
+### TaskProgressData
+
+任务进度数据。
+
+#### Properties
+
+• **progress**: `number` - 任务进度值，如百分比 0-100
+• **progress_text?**: `string` - 进度描述文本，如"正在处理中"
+• **remaining_seconds?**: `number` - 预估剩余时间，单位：秒
+
+<a id="remotenormalv1detail"></a>
+### RemoteNormalV1Detail
+
+remote_normal_v1 模板对应的数据。
+
+#### Properties
+
+• **expire_in_sec**: `number` - 任务过期时间，单位：秒。任务创建后经过该时间将自动过期
+• **display_data**: `TaskDisplayData` - 任务展示数据
+• **jump_page_data?**: `JumpSchemaData` - 点击任务跳转的页面参数
+• **remove_data?**: `TaskActionParams` - 移除任务时的操作参数
+• **progress_data?**: `TaskProgressData` - 任务进度数据
+
+<a id="taskdetail"></a>
+### TaskDetail
+
+任务详情。传入对象时会在调用 native 前自动 JSON.stringify。
+
+#### Type
+
+`string | RemoteNormalV1Detail`
+
+<a id="taskstatus"></a>
+### TaskStatus
+
+任务状态。 running 表示任务运行中，completed 表示任务已完成。
+
+#### Type
+
+`'running' | 'completed'`

package/dist/{skills → public/skills}/doubao-apps-dev/references/reference/open-api/11-/347/231/273/345/275/225.md

@@ -108,3 +108,14 @@ await postLoginResult({
 ## 返回值
 
 返回回传完成的 Promise。
+
+## 相关类型
+
+<a id="logintype"></a>
+### LoginType
+
+Widget 登录类型。 - 0: 隐私协议登录 - 1: 仅登录 - 2: 先登录再隐私协议，两次弹窗 - 3: 登录和隐私协议合并，一次弹窗。
+
+#### Type
+
+`0 | 1 | 2 | 3`