> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# 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: '用户选择了标准配送'
});
```

## 成功返回

无返回字段。

## 错误处理

错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/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；不支持的调用来源仅回退处理、不作为失败。
