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, and this page is available as Markdown at /apps-plugin/docs/js-api/open/business/createTask.md.

createTask

创建任务。

使用限制

WARNING

Android、iOS:豆包 Android、iOS 仅支持 remote 任务,传入 local 无法按本地任务处理;调用方传入 local 时行为与预期不符。

支持版本

前端库版本不低于 0.0.31。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片支持

使用说明

创建任务时需要传入开发者侧唯一任务标识、任务模板、任务详情和任务类型。开发者侧唯一任务标识 可用于幂等创建和后续业务关联。远端任务创建成功后,返回的 taskId 可用于查询或更新任务。

  • 当前仅支持 taskType 为 remote 的远端任务;outTaskId 建议使用业务侧唯一标识以支持幂等创建。

调用方式

异步 API

createTask(params: CreateTaskParams): Promise<CreateTaskResult>

入参

名称类型必填默认值约束说明
outTaskIdstring是--开发者侧任务唯一标识,用于幂等和关联
taskDetailTaskDetail是--模板对应的数据,传入对象时会自动序列化为 JSON 字符串
taskDetail.display_dataTaskDisplayData否--任务展示数据。
taskDetail.display_data.sub_titlestring否--任务副标题。
taskDetail.display_data.titlestring否--任务标题。
taskDetail.expire_in_secnumber否--任务过期时间,单位:秒。任务创建后经过该时间将自动过期。
taskDetail.jump_page_dataJumpSchemaData否--点击任务跳转的页面参数。
taskDetail.jump_page_data.pathstring否--跳转页面。
taskDetail.jump_page_data.querystring否--页面参数,应用插件内消费时会自动 base64 url encode,需要 decode。
taskDetail.progress_dataTaskProgressData否--任务进度数据。
taskDetail.progress_data.progressnumber否--任务进度值,如百分比 0-100。
taskDetail.progress_data.progress_textstring否--进度描述文本,如"正在处理中"。
taskDetail.progress_data.remaining_secondsnumber否--预估剩余时间,单位:秒。
taskDetail.remove_dataTaskActionParams否--移除任务时的操作参数。
taskDetail.remove_data.action_keystring否--操作标识。
taskDetail.remove_data.page_paramstring否--页面参数。
taskTemplate"remote_normal_v1"是--任务样式模板,当前仅支持 remote_normal_v1
taskTypeTaskType是--任务类型,当前支持 local 和 remote。Android、iOS:豆包 Android、iOS 仅支持 remote 任务,传入 local 无法按本地任务处理。

调用示例

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);

成功返回

名称类型必返说明
expiresInnumber否任务超时过期时间
taskIdstring是任务 ID,后续可以使用这个 ID 更新任务
tokenstring否远端任务 token,后续使用 token 通过 OpenAPI 更新远端任务

返回示例

{
  "taskId": "task_123",
  "token": "task-token",
  "expiresIn": 3600
}

错误处理

错误对象和通用错误码见 通用错误处理。

失败示例

{
  "errNo": 104,
  "errMsg": "invalid parameter"
}

错误码

errNoerrMsg平台触发条件处理建议
104invalid parameterAndroid、iOStaskType 不是 remote(如传入 local)传入 remote 任务类型后重试。
112invalid resultAndroid、iOS远端任务创建成功但返回数据为空或缺少 taskId稍后重试;持续失败时反馈服务端响应异常。

通用错误码

errNoerrMsg说明平台
102internal error内部错误Android、iOS

平台差异

  • taskType 非 remote 返回 104;远端返回数据为空或缺少 taskId 返回 112;其他失败统一返回 102。