@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/references/frontend/doubao-agentic-service-api/12-/344/270/232/345/212/241/350/203/275/345/212/233.md

@@ -0,0 +1,1281 @@
+# 豆包应用插件的端能力 API: 业务能力
+
+开放业务能力、卡片更新、模型上下文、任务和隐私设置。
+
+[返回目录](./groups.md) | [返回速查](./quick-reference.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [callTool](#calltool) | 调用当前应用的 Tool。 豆包会根据当前应用插件页面或会话 Widget 确定应用和版本，开发者只需传入 Tool 名称和参数。 Tool 正常结果通过 toolResult 返回，Tool 业务错误通过 toolError 返回，两者都会正常 resolve；调用前校验、鉴权或返回结构校验失败时 Promise reject。 |
+| [expiredWidget](#expiredwidget) | 更新过期的 Widget 为固定卡片。 |
+| [getPrivacySetting](#getprivacysetting) | 获取隐私设置状态。 |
+| [sendFollowUpMessage](#sendfollowupmessage) | 以用户身份发送后续消息，触发新一轮对话、API 调用或引导模型响应。 |
+| [createTask](#createtask) | 创建任务。 |
+| [updateModelContext](#updatemodelcontext) | 向 Agent 捐赠上下文。 |
+| [updateWidget](#updatewidget) | 更新指定 Widget 卡片实例的渲染数据。 用于卡片内操作后刷新卡片展示、把服务端最新结果写回卡片，或由 Page 根据传入的 widgetInstanceId 更新原卡片；需要替换卡片类型时可同时传入新的 widgetId。 widgetData 与 toolResult 二选一。传入 toolResult 时不能切换 widgetId， 结构化结果必须符合当前应用的 Entity 协议。切换 widgetId 时不能关闭重新创建。 |
+
+## API 详情
+
+<a id="calltool"></a>
+### callTool()
+
+# callTool
+
+调用当前应用的 Tool。
+
+豆包会根据当前应用插件页面或会话 Widget 确定应用和版本，开发者只需传入 Tool 名称和参数。
+Tool 正常结果通过 `toolResult` 返回，Tool 业务错误通过 `toolError` 返回，两者都会正常
+resolve；调用前校验、鉴权或返回结构校验失败时 Promise reject。
+
+## 支持版本
+
+前端库版本不低于 `0.0.42`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- **Android**：在当前应用的应用插件页面或由当前应用真实生成的会话 Widget 内调用，且目标 Tool 已在当前应用版本中配置
+- **iOS**：在当前应用的应用插件页面或由当前应用真实生成的会话 Widget 内调用，且目标 Tool 已在当前应用版本中配置
+
+## 使用说明
+
+- toolResult 与 toolError 互斥；toolError 是正常返回的 Tool 业务错误，不会导致 Promise reject。skipWidgetUpdate 为 true 时不执行 Widget 更新阶段，因此不会返回 cardUpdateError；否则 cardUpdateError 表示 Tool 已执行但当前 Widget 更新失败。reloadWidget 默认为 true，仅影响更新后的 Widget 是否重建。重试会再次执行 Tool，请避免重复触发。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+callTool(params: CallToolParams): Promise<CallToolResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>reloadWidget</code></td><td><code>boolean</code></td><td>否</td><td><code>true</code></td><td>-</td><td>是否重新创建更新后的 Widget 组件；设为 `false` 时复用当前组件。</td></tr>
+<tr><td><code>skipWidgetUpdate</code></td><td><code>boolean</code></td><td>否</td><td><code>false</code></td><td>仅影响会下发 Widget 的 Tool。</td><td>是否跳过 Widget 更新阶段。设为 `true` 时，即使 Tool 下发 Widget，也只返回 Tool 数据，<br>不更新当前 Widget。</td></tr>
+<tr><td><code>toolArgs</code></td><td><code>Record&lt;string, unknown&gt;</code></td><td>是</td><td>-</td><td>-</td><td>Tool 入参。</td></tr>
+<tr><td><code>toolName</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>当前应用内需要调用的 Tool 名称。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```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);
+}
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>cardUpdateError</code></td><td><code>CallToolError</code></td><td>否</td><td>Tool 已执行，但返回结果未能用于更新当前 Widget 时的错误。仅 Widget 场景可能返回。</td></tr>
+<tr><td><code>cardUpdateError.code</code></td><td><code>string</code></td><td>否</td><td>错误码。</td></tr>
+<tr><td><code>cardUpdateError.message</code></td><td><code>string</code></td><td>否</td><td>错误信息。</td></tr>
+<tr><td><code>cardUpdateError.phase</code></td><td><code>&quot;render&quot;</code></td><td>否</td><td>错误阶段，固定为渲染阶段。</td></tr>
+<tr><td><code>toolResult</code></td><td><code>ToolResult</code></td><td>否</td><td>Tool 正常结果，与 `toolError` 二选一。</td></tr>
+<tr><td><code>toolResult.content</code></td><td><code>Record&lt;string, unknown&gt;[]</code></td><td>否</td><td>Tool 返回的内容块。</td></tr>
+<tr><td><code>toolResult.isError</code></td><td><code>boolean</code></td><td>否</td><td>Tool 执行是否返回错误结果。</td></tr>
+<tr><td><code>toolResult.structuredContent</code></td><td><code>unknown</code></td><td>否</td><td>Tool 返回的结构化内容。</td></tr>
+<tr><td><code>toolError</code></td><td><code>CallToolBusinessError</code></td><td>否</td><td>Tool 业务错误，与 `toolResult` 二选一。该字段不会导致 API reject。</td></tr>
+<tr><td><code>toolError.code</code></td><td><code>number</code></td><td>否</td><td>Tool 业务错误码。</td></tr>
+<tr><td><code>toolError.message</code></td><td><code>string</code></td><td>否</td><td>Tool 业务错误信息。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "toolResult": {
+    "content": [
+      {
+        "type": "text",
+        "text": "订单已支付"
+      }
+    ],
+    "structuredContent": {
+      "orderId": "order-123",
+      "status": "paid"
+    }
+  }
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 104,
+  "errMsg": "invalid parameter"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>Android、iOS</td><td>在 Worker 等非应用插件页面、Widget 容器中调用</td><td>仅在应用插件页面或会话 Widget 中调用。</td></tr>
+<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>Android、iOS</td><td>toolName 为空、toolArgs 无法序列化为 JSON 对象，或传入的 skipWidgetUpdate、reloadWidget 不是布尔值</td><td>修正 Tool 名称、参数和 Widget 更新控制参数后重试。</td></tr>
+<tr><td><code>112</code></td><td><code>invalid result</code></td><td>Android、iOS</td><td>Tool 正常结果、业务错误或 Widget 更新错误结构无效</td><td>稍后重试；持续失败时反馈 Tool 或服务端返回异常。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- 非应用插件页面、Widget 容器返回 103；参数非法返回 104；返回结构无效返回 112；上下文无效、网络或服务端调用失败返回 102。
+
+<a id="expiredwidget"></a>
+### expiredWidget()
+
+# expiredWidget
+
+更新过期的 Widget 为固定卡片。
+
+## 扫码预览
+![扫码预览 expiredWidget](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fopen%252Fexpired-widget%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.27`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- **Android**：在卡片或消息环境中调用，需传入有效的 widgetInstanceId
+- **iOS**：在卡片或消息环境中调用，需传入有效的 widgetInstanceId
+
+## 使用说明
+
+用于将状态已经过期的 Widget 实例转换为固定卡片，用户点击后可跳转到指定页面。
+
+`getWidgetInstanceId` 仅在卡片环境中有效，在应用插件页面中会返回 `undefined`。如果需要在页面中调用，
+请在 `navigateTo` 时通过参数传递卡片实例 ID。
+
+- 请在卡片状态过期后调用，将卡片转换为可点击跳转的固定卡片；建议使用 url 字段而非已废弃的 schema 字段。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+expiredWidget(params: ExpiredWidgetParams): Promise<object>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>detailText</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>点击失效卡要跳转的页面 detailText。</td></tr>
+<tr><td><code>schema</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>已废弃：使用 url 字段替代 schema 字段，后续版本将移除 schema 字段，请尽快迁移到 url 字段。</td><td>点击失效卡要跳转的页面 schema，格式与 navigateTo 的 url 参数一致。</td></tr>
+<tr><td><code>title</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>点击失效卡要跳转的页面 title。</td></tr>
+<tr><td><code>url</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>点击失效卡要跳转的页面 URL 或 sslocal schema。应用插件页面 URL 格式与 navigateTo 的 url 参数一致。</td></tr>
+<tr><td><code>widgetInstanceId</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>卡片实例 ID。<br><br>在卡片环境可通过 `getWidgetInstanceId` 获取；在应用插件页面等非卡片环境需要通过传参或通信传递。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```ts
+import { expiredWidget } from '@doubao-dev/framework/api';
+import { getWidgetInstanceId } from '@doubao-dev/framework';
+
+expiredWidget({
+  widgetInstanceId: getWidgetInstanceId(),
+  url: '/pages/detail/index?key=value'
+});
+```
+
+## 成功返回
+
+无返回字段。
+
+<a id="getprivacysetting"></a>
+### getPrivacySetting()
+
+# getPrivacySetting
+
+获取隐私设置状态。
+
+## 扫码预览
+![扫码预览 getPrivacySetting](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fopen%252Fget-privacy-setting%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.19`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 使用说明
+
+- 用于在展示隐私相关能力前判断是否需要引导用户完成隐私协议授权。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+getPrivacySetting(params?: object): Promise<PrivacySettingResult>
+```
+
+## 入参
+
+无。
+
+## 调用示例
+
+```typescript
+import { getPrivacySetting } from '@doubao-dev/framework/api';
+
+const { needAuthorization } = await getPrivacySetting();
+
+console.log(needAuthorization);
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>needAuthorization</code></td><td><code>boolean</code></td><td>是</td><td>是否需要用户对隐私协议进行授权。</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "needAuthorization": false
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 错误码
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- 该 API 无专属错误码，失败时统一返回 102。
+
+<a id="sendfollowupmessage"></a>
+### sendFollowUpMessage()
+
+# sendFollowUpMessage
+
+以用户身份发送后续消息，触发新一轮对话、API 调用或引导模型响应。
+
+## 扫码预览
+![扫码预览 sendFollowUpMessage](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fopen%252Fsend-follow-up-message%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.37`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- **Android**：在卡片或应用插件页面中调用
+- **iOS**：在卡片或应用插件页面中调用，且当前上下文已关联有效会话
+
+## 使用说明
+
+可在卡片或应用插件页面中调用，不支持在 app.ts 代码中调用。客户端会根据调用上下文关联会话：
+卡片使用其所在会话，从卡片打开的页面沿用该会话，其他页面使用主会话。
+
+- Promise 解析表示发送请求已提交，不表示消息已成功送达；实际发送失败不会通过该 Promise 返回。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+sendFollowUpMessage(params: SendFollowUpMessageParams): Promise<object>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>content</code></td><td><code>Content[]</code></td><td>是</td><td>-</td><td>至少包含一条 text 类型且 text 不为空白的消息；第一条符合条件的消息作为本轮用户输入。</td><td>消息内容。</td></tr>
+</tbody>
+</table>
+
+### `content[].type = "text"`
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>content[].type</code></td><td><code>&quot;text&quot;</code></td><td>是</td><td>-</td><td>-</td><td>文本消息。</td></tr>
+<tr><td><code>content[].text</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>后续消息的文本内容。</td></tr>
+</tbody>
+</table>
+
+### `content[].type = "api/call"`
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>content[].type</code></td><td><code>&quot;api/call&quot;</code></td><td>是</td><td>-</td><td>-</td><td>API 调用消息。</td></tr>
+<tr><td><code>content[].data</code></td><td><code>object</code></td><td>是</td><td>-</td><td>-</td><td>要调用的 API 及其参数。</td></tr>
+<tr><td><code>content[].data.arguments</code></td><td><code>object</code></td><td>是</td><td>-</td><td>-</td><td>API 调用参数。</td></tr>
+<tr><td><code>content[].data.name</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>API 名称。</td></tr>
+</tbody>
+</table>
+
+### `content[].type = "responseHint"`
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>content[].type</code></td><td><code>&quot;responseHint&quot;</code></td><td>是</td><td>-</td><td>-</td><td>模型响应提示。</td></tr>
+<tr><td><code>content[].data</code></td><td><code>object</code></td><td>是</td><td>-</td><td>-</td><td>用户动作和模型响应建议。</td></tr>
+<tr><td><code>content[].data.responseGuidance</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>建议模型如何响应。</td></tr>
+<tr><td><code>content[].data.userAction</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>用户做了什么。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { sendFollowUpMessage } from '@doubao-dev/framework/api';
+
+await sendFollowUpMessage({
+  content: [
+    { type: 'text', text: '选择拿铁' },
+    {
+      type: 'api/call',
+      data: {
+        name: 'selectDrink',
+        arguments: { drinkId: 'latte_001' }
+      }
+    },
+    {
+      type: 'responseHint',
+      data: {
+        userAction: '用户选择了拿铁',
+        responseGuidance: '确认已选择拿铁，并询问是否需要调整杯型'
+      }
+    }
+  ]
+});
+```
+
+## 成功返回
+
+无返回字段。
+
+<a id="createtask"></a>
+### createTask()
+
+# createTask
+
+创建任务。
+
+## 使用限制
+
+> [!WARNING]
+> **Android、iOS**：豆包 Android、iOS 仅支持 remote 任务，传入 local 无法按本地任务处理；调用方传入 local 时行为与预期不符。
+
+## 支持版本
+
+前端库版本不低于 `0.0.31`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 使用说明
+
+创建任务时需要传入开发者侧唯一任务标识、任务模板、任务详情和任务类型。开发者侧唯一任务标识
+可用于幂等创建和后续业务关联。远端任务创建成功后，返回的 taskId 可用于查询或更新任务。
+
+- 当前仅支持 taskType 为 remote 的远端任务；outTaskId 建议使用业务侧唯一标识以支持幂等创建。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+createTask(params: CreateTaskParams): Promise<CreateTaskResult>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>outTaskId</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>开发者侧任务唯一标识，用于幂等和关联</td></tr>
+<tr><td><code>taskDetail</code></td><td><code>TaskDetail</code></td><td>是</td><td>-</td><td>-</td><td>模板对应的数据，传入对象时会自动序列化为 JSON 字符串</td></tr>
+<tr><td><code>taskDetail.display_data</code></td><td><code>TaskDisplayData</code></td><td>否</td><td>-</td><td>-</td><td>任务展示数据。</td></tr>
+<tr><td><code>taskDetail.display_data.sub_title</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>任务副标题。</td></tr>
+<tr><td><code>taskDetail.display_data.title</code></td><td><code>string</code></td><td>否</td><td>-</td><td>-</td><td>任务标题。</td></tr>
+<tr><td><code>taskDetail.expire_in_sec</code></td><td><code>number</code></td><td>否</td><td>-</td><td>-</td><td>任务过期时间，单位：秒。任务创建后经过该时间将自动过期。</td></tr>
+<tr><td><code>taskDetail.jump_page_data</code></td><td><code>JumpSchemaData</code></td><td>否</td><td><code>-</code></td><td>-</td><td>点击任务跳转的页面参数。</td></tr>
+<tr><td><code>taskDetail.jump_page_data.path</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>跳转页面。</td></tr>
+<tr><td><code>taskDetail.jump_page_data.query</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>页面参数，应用插件内消费时会自动 base64 url encode，需要 decode。</td></tr>
+<tr><td><code>taskDetail.progress_data</code></td><td><code>TaskProgressData</code></td><td>否</td><td><code>-</code></td><td>-</td><td>任务进度数据。</td></tr>
+<tr><td><code>taskDetail.progress_data.progress</code></td><td><code>number</code></td><td>否</td><td>-</td><td>-</td><td>任务进度值，如百分比 0-100。</td></tr>
+<tr><td><code>taskDetail.progress_data.progress_text</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>进度描述文本，如&quot;正在处理中&quot;。</td></tr>
+<tr><td><code>taskDetail.progress_data.remaining_seconds</code></td><td><code>number</code></td><td>否</td><td><code>-</code></td><td>-</td><td>预估剩余时间，单位：秒。</td></tr>
+<tr><td><code>taskDetail.remove_data</code></td><td><code>TaskActionParams</code></td><td>否</td><td><code>-</code></td><td>-</td><td>移除任务时的操作参数。</td></tr>
+<tr><td><code>taskDetail.remove_data.action_key</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>操作标识。</td></tr>
+<tr><td><code>taskDetail.remove_data.page_param</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>页面参数。</td></tr>
+<tr><td><code>taskTemplate</code></td><td><code>&quot;remote_normal_v1&quot;</code></td><td>是</td><td>-</td><td>-</td><td>任务样式模板，当前仅支持 remote_normal_v1</td></tr>
+<tr><td><code>taskType</code></td><td><code>TaskType</code></td><td>是</td><td>-</td><td>-</td><td>任务类型，当前支持 local 和 remote。Android、iOS：豆包 Android、iOS 仅支持 remote 任务，传入 local 无法按本地任务处理。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { createTask } from '@doubao-dev/framework/api';
+
+const result = await createTask({
+  outTaskId: 'order-20260529-001',
+  taskTemplate: 'remote_normal_v1',
+  taskType: 'remote',
+  taskDetail: {
+    expire_in_sec: 3600,
+    display_data: {
+      title: '订单处理中',
+      sub_title: '正在为你处理订单，请稍候'
+    }
+  }
+});
+
+console.log(result.taskId, result.token, result.expiresIn);
+```
+
+## 成功返回
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>expiresIn</code></td><td><code>number</code></td><td>否</td><td>任务超时过期时间</td></tr>
+<tr><td><code>taskId</code></td><td><code>string</code></td><td>是</td><td>任务 ID，后续可以使用这个 ID 更新任务</td></tr>
+<tr><td><code>token</code></td><td><code>string</code></td><td>否</td><td>远端任务 token，后续使用 token 通过 OpenAPI 更新远端任务</td></tr>
+</tbody>
+</table>
+
+### 返回示例
+
+```json
+{
+  "taskId": "task_123",
+  "token": "task-token",
+  "expiresIn": 3600
+}
+```
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 104,
+  "errMsg": "invalid parameter"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>Android、iOS</td><td>taskType 不是 remote（如传入 local）</td><td>传入 remote 任务类型后重试。</td></tr>
+<tr><td><code>112</code></td><td><code>invalid result</code></td><td>Android、iOS</td><td>远端任务创建成功但返回数据为空或缺少 taskId</td><td>稍后重试；持续失败时反馈服务端响应异常。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- taskType 非 remote 返回 104；远端返回数据为空或缺少 taskId 返回 112；其他失败统一返回 102。
+
+<a id="updatemodelcontext"></a>
+### updateModelContext()
+
+# updateModelContext
+
+向 Agent 捐赠上下文。
+
+## 扫码预览
+![扫码预览 updateModelContext](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fopen%252Fupdate-model-context%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.26`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- **Android**：未传 taskId 时需传 entityId；两者都不传时仅可在卡片环境调用，以便客户端补充必要信息
+- **iOS**：未传 taskId 时需传 entityId；两者都不传时仅可在卡片环境调用，以便客户端补充必要信息
+
+## 使用说明
+
+`taskId` 可以为空，此时客户端会尝试使用 `entityId` 填充；`entityId` 可以为空，
+此时如果处于卡片环境，客户端会尝试使用卡片的 `entityId` 填充。
+
+- 用于在任务或实体维度补充模型可理解的上下文，请在业务状态变化后按需调用，避免高频重复捐赠相同内容。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+updateModelContext(params: UpdateModelContextParams): Promise<object>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>content</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>上下文内容，格式无约束，可以与 MCP 服务下发的上下文格式保持一致。</td></tr>
+<tr><td><code>entityId</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>上下文所属的 entityId，业务侧管理。为空且处于卡片环境时，客户端会尝试使用卡片的 entityId 填充。</td></tr>
+<tr><td><code>taskId</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>上下文所属任务 ID，业务侧定义。为空时客户端会尝试使用 entityId 填充。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { updateModelContext } from '@doubao-dev/framework/api';
+
+await updateModelContext({
+  taskId: 'task-id',
+  entityId: 'entity-id',
+  content: '用户选择了标准配送'
+});
+```
+
+## 成功返回
+
+无返回字段。
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 305,
+  "errMsg": "network failure"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>Android</td><td>当前容器类型不受支持，无法归类为页面、卡片或 Worker 来源</td><td>请在支持的容器（页面、卡片或 Worker）环境中调用。</td></tr>
+<tr><td><code>112</code></td><td><code>invalid result</code></td><td>Android</td><td>捐赠上下文的远端响应无法解析</td><td>稍后重试；持续失败时反馈服务端响应异常。</td></tr>
+<tr><td><code>301</code></td><td><code>network request cancelled</code></td><td>iOS</td><td>捐赠上下文的网络请求被取消</td><td>确认应用与网络状态后重试。</td></tr>
+<tr><td><code>302</code></td><td><code>connection timed out</code></td><td>Android、iOS</td><td>捐赠上下文的网络连接超时</td><td>检查网络连接后重试。</td></tr>
+<tr><td><code>303</code></td><td><code>no network connection</code></td><td>Android、iOS</td><td>当前无可用网络连接</td><td>恢复网络连接后重试。</td></tr>
+<tr><td><code>305</code></td><td><code>network failure</code></td><td>Android、iOS</td><td>捐赠上下文时发生其他网络错误</td><td>检查网络连接，稍后重试。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>100</code></td><td><code>unknown error</code></td><td>未知错误</td><td>Android</td></tr>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- **Android**：网络失败细分为连接超时 302、无网络 303、其他网络错误 305；远端响应无法解析返回 112；当前容器类型不受支持返回 103；其他失败统一返回 102，未归类的远端业务错误返回 100。
+- **iOS**：依据网络错误细分：请求取消 301、连接超时 302、无网络 303、其他 305；不支持的调用来源仅回退处理、不作为失败。
+
+<a id="updatewidget"></a>
+### updateWidget()
+
+# updateWidget
+
+更新指定 Widget 卡片实例的渲染数据。
+
+用于卡片内操作后刷新卡片展示、把服务端最新结果写回卡片，或由 Page 根据传入的
+`widgetInstanceId` 更新原卡片；需要替换卡片类型时可同时传入新的 `widgetId`。
+
+`widgetData` 与 `toolResult` 二选一。传入 `toolResult` 时不能切换 `widgetId`，
+结构化结果必须符合当前应用的 Entity 协议。切换 `widgetId` 时不能关闭重新创建。
+
+## 扫码预览
+![扫码预览 updateWidget](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fopen%252Fupdate-widget%252Findex)
+
+## 支持版本
+
+前端库版本不低于 `0.0.26`。
+
+## 支持平台
+
+<table>
+<thead>
+<tr><th>平台</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>Android</td><td>支持</td></tr>
+<tr><td>iOS</td><td>支持</td></tr>
+<tr><td>PC</td><td>不支持</td></tr>
+<tr><td>HarmonyOS</td><td>不支持</td></tr>
+</tbody>
+</table>
+
+## 支持场景
+
+<table>
+<thead>
+<tr><th>场景</th><th>支持情况</th></tr>
+</thead>
+<tbody>
+<tr><td>页面</td><td>支持</td></tr>
+<tr><td>卡片</td><td>支持</td></tr>
+</tbody>
+</table>
+
+## 接入准备
+
+### 前置条件
+
+- **Android**：在卡片或消息环境中调用，需传入有效的 widgetInstanceId
+- **iOS**：在卡片或消息环境中调用，需传入有效的 widgetInstanceId
+
+## 使用说明
+
+- widgetData 和 toolResult 互斥；应用插件支持 toolResult 和 reloadWidget，旧版 Applet Widget 仅支持 widgetData。toolResult 更新模型上下文并须符合 Entity 协议，不能同时切换 widgetId。reloadWidget 默认为 true；切换 widgetId 时不能设为 false。
+
+## 调用方式
+
+### 异步 API
+
+```typescript
+updateWidget(params: UpdateWidgetParams): Promise<object>
+```
+
+## 入参
+
+<table>
+<thead>
+<tr><th>名称</th><th>类型</th><th>必填</th><th>默认值</th><th>约束</th><th>说明</th></tr>
+</thead>
+<tbody>
+<tr><td><code>reloadWidget</code></td><td><code>boolean</code></td><td>否</td><td><code>true</code></td><td>-</td><td>是否重新创建 Widget 组件；设为 `false` 时仅更新同一 Widget 的数据。<br>仅应用插件支持；旧版 Applet Widget 使用 IM 更新，不支持此参数。</td></tr>
+<tr><td><code>widgetInstanceId</code></td><td><code>string</code></td><td>是</td><td>-</td><td>-</td><td>需要更新的 Widget 实例 ID。<br><br>卡片内可通过 `getWidgetInstanceId()` 获取；页面中需要由路由参数或业务数据传入。</td></tr>
+<tr><td><code>widgetData</code></td><td><code>string</code></td><td>否</td><td>-</td><td>-</td><td>新的卡片渲染数据，通常传入 `JSON.stringify(viewData)`；不会更新模型上下文。</td></tr>
+<tr><td><code>widgetId</code></td><td><code>string</code></td><td>否</td><td><code>-</code></td><td>-</td><td>可选的新 widgetId。传入后会把当前实例切换成另一个已注册的 Widget。</td></tr>
+<tr><td><code>toolResult</code></td><td><code>ToolResult</code></td><td>否</td><td>-</td><td>-</td><td>符合 Entity 协议的 ToolResult；仅应用插件支持，更新卡片并同步模型上下文。</td></tr>
+<tr><td><code>toolResult.content</code></td><td><code>Record&lt;string, unknown&gt;[]</code></td><td>否</td><td><code>-</code></td><td>-</td><td>Tool 返回的内容块。</td></tr>
+<tr><td><code>toolResult.isError</code></td><td><code>boolean</code></td><td>否</td><td><code>false</code></td><td>-</td><td>Tool 执行是否返回错误结果。</td></tr>
+<tr><td><code>toolResult.structuredContent</code></td><td><code>unknown</code></td><td>否</td><td><code>-</code></td><td>-</td><td>Tool 返回的结构化内容。</td></tr>
+</tbody>
+</table>
+
+## 调用示例
+
+```typescript
+import { updateWidget } from '@doubao-dev/framework/api';
+import { getWidgetInstanceId } from '@doubao-dev/framework';
+
+await updateWidget({
+  widgetInstanceId: getWidgetInstanceId(),
+  widgetData: JSON.stringify({ title: '更新后的标题', status: 'done' })
+});
+```
+
+## 成功返回
+
+无返回字段。
+
+## 错误处理
+
+错误对象和通用错误码见 [通用错误处理](./common-errors.md#错误返回)。
+
+### 失败示例
+
+```json
+{
+  "errNo": 104,
+  "errMsg": "invalid parameter"
+}
+```
+
+### 错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
+</thead>
+<tbody>
+<tr><td><code>103</code></td><td><code>feature not support</code></td><td>Android、iOS</td><td>当前豆包环境未提供消息更新能力，或旧版 Applet Widget 传入 reloadWidget/toolResult</td><td>在支持的环境调用；旧版 Applet Widget 只传 widgetData。</td></tr>
+<tr><td><code>104</code></td><td><code>invalid parameter</code></td><td>Android、iOS</td><td>widgetInstanceId 为空、widgetData 与 toolResult 未二选一、reloadWidget 类型错误，或切换 widgetId 时关闭重建</td><td>修正参数后重试。</td></tr>
+<tr><td><code>116</code></td><td><code>resource not found</code></td><td>Android、iOS</td><td>依据 widgetInstanceId 找不到对应消息，或依据 widgetId 找不到已注册的 Widget</td><td>确认 widgetInstanceId 与 widgetId 有效后重试。</td></tr>
+</tbody>
+</table>
+
+#### 通用错误码
+
+<table>
+<thead>
+<tr><th>errNo</th><th>errMsg</th><th>说明</th><th>平台</th></tr>
+</thead>
+<tbody>
+<tr><td><code>102</code></td><td><code>internal error</code></td><td>内部错误</td><td>Android、iOS</td></tr>
+</tbody>
+</table>
+
+## 平台差异
+
+- 参数为空返回 104；消息或 Widget 未找到返回 116；当前豆包环境未提供消息更新能力时返回 103；其他失败统一返回 102。
+
+## 相关类型
+
+<a id="toolresult"></a>
+### ToolResult
+
+Tool 返回的标准内容。
+
+#### Properties
+
+• **content?**: `Array<Record<string, unknown>>` - Tool 返回的内容块
+• **structuredContent?**: `unknown` - Tool 返回的结构化内容
+• **isError?**: `boolean` - Tool 执行是否返回错误结果
+
+<a id="calltoolbusinesserror"></a>
+### CallToolBusinessError
+
+Tool 正常完成调用后返回的业务错误。
+
+#### Properties
+
+• **code**: `number` - Tool 业务错误码
+• **message**: `string` - Tool 业务错误信息
+
+<a id="calltoolerror"></a>
+### CallToolError
+
+Widget 更新阶段的错误。
+
+#### Properties
+
+• **code**: `string` - 错误码
+• **message**: `string` - 错误信息
+• **phase**: `'render'` - 错误阶段，固定为渲染阶段
+
+<a id="calltoolparams"></a>
+### CallToolParams
+
+调用 Tool 的参数。
+
+#### Properties
+
+• **toolName**: `string` - 当前应用内需要调用的 Tool 名称
+• **toolArgs**: `Record<string, unknown>` - Tool 入参
+• **skipWidgetUpdate?**: `boolean` - 是否跳过 Widget 更新阶段。设为 true 时，即使 Tool 下发 Widget，也只返回 Tool 数据， 不更新当前 Widget
+• **reloadWidget?**: `boolean` - 是否重新创建更新后的 Widget 组件；设为 false 时复用当前组件
+
+<a id="calltoolresult"></a>
+### CallToolResult
+
+调用 Tool 的结果。
+
+#### Type
+
+`{
+  /**
+   * Tool 已执行，但返回结果未能用于更新当前 Widget 时的错误。仅 Widget 场景可能返回。
+   *
+   * @default -
+   */
+  cardUpdateError?: CallToolError;
+} & (
+  | {
+      /** Tool 正常结果，与 `toolError` 二选一。 */
+      toolResult: ToolResult;
+      /** @hidden */
+      toolError?: never;
+    }
+  | {
+      /** Tool 业务错误，与 `toolResult` 二选一。该字段不会导致 API reject。 */
+      toolError: CallToolBusinessError;
+      /** @hidden */
+      toolResult?: never;
+    }
+)`
+
+<a id="expiredwidgetparams"></a>
+### ExpiredWidgetParams
+
+将过期卡片转换为固定卡片的请求参数。
+
+#### Properties
+
+• **widgetInstanceId**: `string` - 卡片实例 ID。 在卡片环境可通过 getWidgetInstanceId 获取；在应用插件页面等非卡片环境需要通过传参或通信传递
+• **url?**: `string` - 点击失效卡要跳转的页面 URL 或 sslocal schema。应用插件页面 URL 格式与 navigateTo 的 url 参数一致
+• **title?**: `string` - 点击失效卡要跳转的页面 title
+• **detailText?**: `string` - 点击失效卡要跳转的页面 detailText
+
+<a id="privacysettingresult"></a>
+### PrivacySettingResult
+
+#### Properties
+
+• **needAuthorization**: `boolean` - 是否需要用户对隐私协议进行授权
+
+<a id="content"></a>
+### Content
+
+后续消息内容。
+
+#### Type
+
+`| {
+      /** 文本消息。 */
+      type: 'text';
+      /** 后续消息的文本内容。 */
+      text: string;
+    }
+  | {
+      /** API 调用消息。 */
+      type: 'api/call';
+      /** 要调用的 API 及其参数。 */
+      data: {
+        /** API 名称。 */
+        name: string;
+        /** API 调用参数。 */
+        arguments: object;
+      };
+    }
+  | {
+      /** 模型响应提示。 */
+      type: 'responseHint';
+      /** 用户动作和模型响应建议。 */
+      data: {
+        /**
+         * 用户做了什么。
+         * @default -
+         */
+        userAction?: string;
+        /**
+         * 建议模型如何响应。
+         * @default -
+         */
+        responseGuidance?: string;
+      };
+    }`
+
+<a id="sendfollowupmessageparams"></a>
+### SendFollowUpMessageParams
+
+发送后续消息的请求参数。
+
+#### Properties
+
+• **content**: `Content[]` - 消息内容
+
+<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="taskdetail"></a>
+### TaskDetail
+
+任务详情。传入对象时会自动序列化为 JSON 字符串。
+
+#### Type
+
+`string | RemoteNormalV1Detail`
+
+<a id="createtaskparams"></a>
+### CreateTaskParams
+
+创建任务的请求参数。
+
+#### Properties
+
+• **outTaskId**: `string` - 开发者侧任务唯一标识，用于幂等和关联
+• **taskTemplate**: `TaskTemplate` - 任务样式模板，当前仅支持 remote_normal_v1
+• **taskDetail**: `TaskDetail` - 模板对应的数据，传入对象时会自动序列化为 JSON 字符串
+• **taskType**: `TaskType` - 任务类型，当前支持 local 和 remote
+
+<a id="createtaskresult"></a>
+### CreateTaskResult
+
+创建任务的返回结果。
+
+#### Properties
+
+• **taskId**: `string` - 任务 ID，后续可以使用这个 ID 更新任务
+• **token?**: `string` - 远端任务 token，后续使用 token 通过 OpenAPI 更新远端任务
+• **expiresIn?**: `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="tasktemplate"></a>
+### TaskTemplate
+
+任务样式模板。 当前仅支持 remote_normal_v1。
+
+#### Type
+
+`'remote_normal_v1'`
+
+<a id="updatemodelcontextparams"></a>
+### UpdateModelContextParams
+
+向 Agent 捐赠上下文的请求参数。
+
+#### Properties
+
+• **taskId?**: `string` - 上下文所属任务 ID，业务侧定义。为空时客户端会尝试使用 entityId 填充
+• **entityId?**: `string` - 上下文所属的 entityId，业务侧管理。为空且处于卡片环境时，客户端会尝试使用卡片的 entityId 填充
+• **content**: `string` - 上下文内容，格式无约束，可以与 MCP 服务下发的上下文格式保持一致
+
+<a id="updatewidgetparams"></a>
+### UpdateWidgetParams
+
+#### Type
+
+`{
+  /**
+   * 需要更新的 Widget 实例 ID。
+   *
+   * 卡片内可通过 `getWidgetInstanceId()` 获取；页面中需要由路由参数或业务数据传入。
+   */
+  widgetInstanceId: string;
+  /**
+   * 是否重新创建 Widget 组件；设为 `false` 时仅更新同一 Widget 的数据。
+   * 仅应用插件支持；旧版 Applet Widget 使用 IM 更新，不支持此参数。
+   * @default true
+   */
+  reloadWidget?: boolean;
+} & (
+  | {
+      /**
+       * 可选的新 widgetId。传入后会把当前实例切换成另一个已注册的 Widget。
+       * @default -
+       */
+      widgetId?: string;
+      /** 新的卡片渲染数据，通常传入 `JSON.stringify(viewData)`；不会更新模型上下文。 */
+      widgetData: string;
+      toolResult?: never;
+    }
+  | {
+      /** 保持当前 Widget 时可显式传入相同的 widgetId。 */
+      widgetId?: string;
+      widgetData?: never;
+      /** 符合 Entity 协议的 ToolResult；仅应用插件支持，更新卡片并同步模型上下文。 */
+      toolResult: ToolResult;
+    }
+)`