> 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.

# 对话相关 JS API 使用与权限声明

卡片、页面或 Worker 可以通过 `@doubao-dev/framework/api` 调用宿主开放能力。下表同时标注当前已公开能力和正在建设的能力；建设中的能力不可按现有 SDK API 使用。

## 核心 API 一览

| API                                                   | 用途                                      | 典型场景                             |
| ----------------------------------------------------- | --------------------------------------- | -------------------------------- |
| `callTool(name, args)`（建设中）                           | 组件直接触发 MCP 工具调用，并使用工具结果更新当前交互           | 用户点击「加入购物车」后调用对应工具，再根据结果刷新卡片     |
| `sendFollowUpMessage({ content })`                    | 以用户身份发送后续消息，触发新一轮对话、API 调用或引导模型响应       | 用户选择「拿铁」后，把选择结果和响应建议发送给宿主        |
| `updateModelContext({ taskId?, entityId?, content })` | 在任务或实体维度向 Agent 补充上下文，不触发新一轮对话          | 用户修改配送方式后，把最新选择同步给 Agent，供后续推理使用 |
| `updateWidget({ widgetId?, widgetData })`             | 更新指定 Widget 实例的渲染数据，也可切换到另一个已注册的 Widget | 卡片操作完成或服务端返回新结果后，持久化刷新原卡片        |

## 选型建议

- 需要直接调用 MCP 工具：规划使用 `callTool`；该能力仍在建设中，当前 SDK 仓库尚未公开导出，不能在现有业务代码中调用。
- 需要继续会话、请求宿主发起 API 调用或引导模型响应：使用 `sendFollowUpMessage`。`content` 是消息数组，支持 `text`、`api/call` 和 `responseHint` 三种内容。
- 只需要补充 Agent 后续推理所需的业务状态：使用 `updateModelContext`。`content` 必填，`taskId` 和 `entityId` 可选。

## 调用示例

```ts
import { sendFollowUpMessage, updateModelContext, updateWidget } from '@doubao-dev/framework/api';

await sendFollowUpMessage({
  content: [{ type: 'text', text: '选择拿铁' }]
});

await updateModelContext({
  entityId: 'order-001',
  content: '用户选择了标准配送'
});

await updateWidget({
  widgetData: JSON.stringify({ status: 'done' })
});
```

## 权限与运行环境

- `updateModelContext` 和 `updateWidget` 的公开契约标明：Android、iOS 无需预先申请应用 scope 或系统权限；PC、HarmonyOS 暂未提供实现。
- `sendFollowUpMessage` 可在 Widget、应用插件页面或 Worker 中调用。宿主会根据调用位置关联对应会话；当前源码没有声明额外的权限契约，不应据此推断其他平台支持情况。
