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/backend-development/multi-task.md.

多任务管理接入(服务端)

本文面向负责业务服务端、MCP Server 和任务状态管理的开发者,说明如何使用业务模板创建、更新和完成豆包应用插件中的远程任务。

当前服务端 OpenAPI 支持的是 remote 远程任务。remote_normal_v1 仅用于存量兼容,不应继续用于新增能力;不要因为配置 schema 接受 task_type: local,就把 local 模板交给远程任务接口。

接入目标

多任务管理适合外卖配送、文件生成、审核处理、预约服务等不能在一次 MCP 调用内完成的长耗时业务。它让业务服务端在任务创建后持续更新标题、副标题、进度和剩余时间,并在业务真实完成时结束任务。

完整接入需要:

  1. 在 business-templates.yaml 中配置 remote 任务模板、静态兜底文案和动态 scene key;
  2. 在收到平台 MCP 调用时安全取得 X-DB-SessionToken;
  3. 创建任务并持久化平台 task_id、push_token 和本地业务状态;
  4. 使用最新 push token 串行更新任务;
  5. 由可信业务事实触发 completed 终态。

标准链路为:

  1. 用户触发长耗时业务,平台向开发者 MCP 发起 Tool Call,并注入 X-DB-SessionToken;
  2. MCP 将可信会话传给业务服务端,业务服务端调用 create_remote_task;
  3. 创建成功后,立即持久化平台 task_id 和首枚 push_token;
  4. 业务进度变化时,使用最新 push token 调用 update_remote_task;
  5. 运行中更新返回 next_push_token 后,原子保存为下一次更新的首选 token;
  6. 业务真实完成后,再调用一次 update_remote_task(task_status=completed);完成响应通常不再返回下一枚 token。

名词解释

对象作用关键规则
template_id开发者定义的任务模板稳定标识通知和任务模板之间也必须全局唯一
scene_key运行时选择动态文案的 key同一任务模板内不可重复
out_task_id开发者侧任务实例 ID同一用户、同一业务任务重试必须复用
X-DB-SessionToken当前用户的平台会话凭证来自平台 MCP Tool Call Header;创建任务必需
push_token某个任务后续更新的签名凭证创建响应返回首次 token,运行中更新返回下一枚 token
task_id平台侧任务 ID创建成功后与业务任务关联持久化
task_detail任务展示和进度信息外层 API 字段是 JSON 字符串,需要双层序列化

接入前准备

顺序开发者要完成的动作关键产出
1创建豆包应用插件并获取 AppID、AppSecret应用级凭据
2明确任务业务身份、创建触发点、状态来源、更新频率和完成条件任务状态机
3准备任务落地页并在 app.config.ts 注册可用的应用插件内部 Page
4在项目根目录配置 business-templates.yamlremote 任务模板
5实现任务持久化、乐观锁或串行更新可恢复的 token 和状态管理
6确保 MCP Server 能取得平台注入的 X-DB-SessionToken可信用户会话

AccessToken、SessionToken 和 push token 只能保存在需要调用平台的服务端安全边界,不进入前端、Manifest、运行态 Skill、普通日志或接口响应。

开发态易错点:MCP 调用传入的 SessionToken Header 固定为 token=sess.<payload>.<signature>;expire_in=<seconds>,任务创建接口需要的则只有 sess.<payload>.<signature>。必须先切分,不能把复合值原样传给下游。

配置任务模板

schema_version: 1

task_templates:
  - template_id: milk_tea_preparing
    task_type: remote

    fallback:
      title: "奶茶制作中"
      sub_title: "请稍候"

    variable_list:
      - name
      - pickup_code
      - minutes

    text_templates:
      - scene_key: preparing_title
        text: "{name}制作中"

      - scene_key: preparing_subtitle
        text: "取餐码 {pickup_code}"

      - scene_key: preparing_progress
        text: "预计 {minutes} 分钟完成"

字段说明

字段必填说明
template_id是应用内稳定业务标识;最长 128,只包含字母、数字、_、-
task_type是当前服务端任务链路使用 remote
fallback.title是无变量的静态兜底标题
fallback.sub_title否无变量的静态兜底副标题
variable_list按需模板允许使用的变量,运行时值均为字符串
text_templates[].scene_key是模板内唯一的动态文案选择 key
text_templates[].text是非空文案,可以使用已声明变量

fallback 不能使用占位符。动态文案必须放在 text_templates 中,并在运行时通过 scene key 选择。

建议按业务阶段定义清晰的 key,例如 preparing_title、delivering_title、completed_title。scene key 本身不绑定标题、副标题或进度字段,运行时把它放在哪个字段,就渲染到哪个字段。

运行时数据与模板的映射

任务详情对象示例:

{
  "expire_in_sec": 1800,
  "display_data": {
    "title_scene_key": "preparing_title",
    "sub_title_scene_key": "preparing_subtitle"
  },
  "progress_data": {
    "progress": 30,
    "text_scene_key": "preparing_progress",
    "remaining_seconds": 180
  },
  "variables": {
    "name": "珍珠奶茶",
    "pickup_code": "A018",
    "minutes": "3"
  },
  "jump_page_data": {
    "path": "pages/order/detail",
    "query": "order_id=20260722-001"
  }
}
运行时字段作用
title_scene_key选择标题模板;省略时使用 fallback.title
sub_title_scene_key选择副标题模板;省略时使用 fallback.sub_title
progress数值进度,必须是 0–100 的整数
text_scene_key选择进度文案模板
remaining_seconds预计剩余秒数
variables同时供本次选择的标题、副标题和进度文案渲染
jump_page_data当前应用插件内部 Page 路径和查询参数
expire_in_sec任务有效期;创建时必须大于 0

运行时不能直接传 title、sub_title 或 progress_text 原文绕过模板。变量变化会影响已展示文案时,同一次更新必须重新携带对应 scene key。

校验与同步模板

先执行兼容校验:

dbx check --file ./business-templates.yaml --json

只同步业务模板时:

dbx config sync business-templates \
  --project <project-root> \
  --json

显式同步要求项目根目录存在 business-templates.yaml;文件不存在时命令失败。执行 dbx build 创建完整版本时,该文件会自动参与严格校验和同步;文件缺失则跳过,不会清空远端。必须检查 config_sync_results 中的逐模板结果。

业务模板是应用级资源。上传新应用版本、回滚版本或从 YAML 删除模板,都不会自动删除或恢复某个线上模板。

获取调用凭证

创建任务需要两类凭证:

凭证来源用途
X-DB-AccessToken业务服务端使用 AppID、AppSecret 获取并缓存鉴别应用身份
X-DB-SessionToken平台调用开发者 MCP Tool 时在 Header 中注入绑定当前用户会话并创建任务

规范化 SessionToken

开发态 MCP 调用传入的 Header 固定为复合值:

token=sess.<payload>.<signature>;expire_in=<seconds>

其中 token 是任务创建接口需要的用户会话凭证,expire_in 是 MCP 调用侧附带的有效期元数据。调用 create_remote_task 前必须完成切分:

  1. 去掉整个 Header 值首尾空白;
  2. 按分号拆分字段,再按每个字段的第一个 = 拆分 key 和 value;
  3. 要求存在且仅存在一个非空 token 字段和一个合法非负整数 expire_in 字段;
  4. 取 token= 后的完整值作为纯 SessionToken;
  5. Header 为空、缺字段、字段重复或格式非法时停止创建;
  6. 下游 X-DB-SessionToken 只能传拆出的纯 token,不能包含 token=、;expire_in=... 或其它元数据。

不要使用无上限的 split("="),因为 token 是 opaque value,未来可能包含 =。expire_in 只是输入侧伴随元数据;不要根据开发态示例中的 expire_in=0 推断 token 永久有效或立即失效。

TypeScript 示例:

function extractDbSessionToken(rawValue: string | undefined): string {
  const raw = rawValue?.trim();
  if (!raw) throw new Error("missing X-DB-SessionToken");

  const fields = raw.split(";").map((field) => field.trim()).filter(Boolean);
  const params = new Map<string, string>();
  for (const field of fields) {
    const separator = field.indexOf("=");
    if (separator <= 0) throw new Error("invalid X-DB-SessionToken field");

    const key = field.slice(0, separator).trim().toLowerCase();
    const value = field.slice(separator + 1).trim();
    if (!value || params.has(key)) {
      throw new Error(`invalid X-DB-SessionToken field: ${key}`);
    }
    params.set(key, value);
  }

  const token = params.get("token");
  const expireIn = params.get("expire_in");
  if (!token || expireIn === undefined || !/^\d+$/.test(expireIn)) {
    throw new Error("invalid X-DB-SessionToken wrapper");
  }
  return token;
}

框架可能把重复 Header 表示成字符串数组。应先拒绝歧义值或取得唯一值,再调用切分函数。日志只记录切分状态,不能记录原始值、纯 token 或可逆摘要。

AppID、AppSecret、AccessToken、SessionToken、模板必须属于同一应用与环境。

如果业务动作发生在原 MCP 请求结束之后,只能在平台允许的有效期和使用方式内保存必要身份。不能假设 SessionToken 永久有效。缺少有效 SessionToken 时,应停止创建任务并返回可诊断错误,不能伪造 Header、使用固定 token 或默认用户。

创建远程任务

基本信息

名称描述
HTTP Path/api/task/v1/developer/create_remote_task
HTTP MethodPOST
Content-Typeapplication/json
鉴权X-DB-AccessToken + X-DB-SessionToken

服务端 API 域名以 服务端 API 总览 中当前环境说明为准。

请求体

字段必填说明
out_task_id是开发者侧稳定任务 ID,最长 64,用于幂等和关联
task_template是business-templates.yaml 中 remote 模板的 template_id
task_detail是JSON 字符串;内容为任务详情对象

请求示例:

{
  "out_task_id": "milk-tea-order-20260722-001",
  "task_template": "milk_tea_preparing",
  "task_detail": "{\"expire_in_sec\":1800,\"display_data\":{\"title_scene_key\":\"preparing_title\",\"sub_title_scene_key\":\"preparing_subtitle\"},\"progress_data\":{\"progress\":30,\"text_scene_key\":\"preparing_progress\",\"remaining_seconds\":180},\"variables\":{\"name\":\"珍珠奶茶\",\"pickup_code\":\"A018\",\"minutes\":\"3\"}}"
}

使用 JSON 库先序列化内层 detail,再序列化外层请求,不要手工拼接转义字符串。

响应

{
  "code": 0,
  "msg": "success",
  "log_id": "202607220001",
  "data": {
    "task_id": "platform_task_123456",
    "push_token": {
      "token": "pt_xxxxxxxxxxxxxxxx",
      "expires_in": 86400
    }
  }
}

只有 code == 0 且 task_id、push_token.token 非空时才能标记创建成功。成功后立即持久化:

  • 业务任务主键、用户和 out_task_id;
  • 模板 ID 和平台 task_id;
  • 当前业务状态和进度;
  • push_token.token、过期时间和 token 版本;
  • 平台结果码、脱敏 log_id 和更新时间。

同一用户、同一 out_task_id 重试时平台会定位已有任务。不要为超时请求自动更换 ID,也不能把已有 out_task_id 改绑到另一个模板。

更新任务

基本信息

名称描述
HTTP Path/api/task/v1/developer/update_remote_task
HTTP MethodPOST
Content-Typeapplication/json
鉴权X-DB-AccessToken + 最新 push token

task_status 和 task_detail 至少提供一项。

更新进度或展示

{
  "push_token": "<latest_push_token>",
  "task_detail": "{\"expire_in_sec\":1800,\"display_data\":{\"title_scene_key\":\"preparing_title\",\"sub_title_scene_key\":\"preparing_subtitle\"},\"progress_data\":{\"progress\":70,\"text_scene_key\":\"preparing_progress\",\"remaining_seconds\":60},\"variables\":{\"name\":\"珍珠奶茶\",\"pickup_code\":\"A018\",\"minutes\":\"1\"}}"
}

运行中更新成功时,响应会返回 next_push_token:

{
  "code": 0,
  "msg": "success",
  "log_id": "202607220002",
  "data": {
    "next_push_token": {
      "token": "pt_yyyyyyyyyyyyyyyy",
      "expires_in": 86400
    }
  }
}

收到后必须原子保存为后续首选 token。返回新 token 不代表旧 token 立即失效:旧 token 仍可能在原到期时间前通过签名校验,因此 token 不能代替业务并发控制。

完成任务

业务事实确认完成后,使用当前首选 token:

{
  "push_token": "<latest_push_token>",
  "task_status": "completed"
}

当前实现中,completed 会把任务更新为 SUCCESS/HIDDEN,忽略同一请求中的 task_detail,并且通常不返回 next_push_token。

如果需要在隐藏前展示 100% 或最终文案,应先发送一次 running 更新并保存响应中的最新 token,再单独发送 completed。不能因为前端页面关闭、MCP Tool 返回或进度达到 100,就自动推断业务已经完成。

持久化和并发

同一任务的更新应串行执行,或使用数据库乐观锁:

  1. 从持久化读取当前首选 token、到期时间和更新版本;
  2. 使用该 token 调用更新接口;
  3. 运行中更新成功且返回 next_push_token 时,按旧版本做原子条件更新;
  4. 条件更新失败说明另一请求已经提交,重新读取最新记录;
  5. completed 成功时保存终态,允许响应没有下一枚 token。

收到 token 失效错误时,先检查是否存在并发更新已经保存了新 token。无法确认时依据本地持久化和真实业务状态恢复,不能自动新建另一个 out_task_id。

日志只记录脱敏任务标识、模板 ID、阶段、进度、token 版本、结果码、错误类型和平台 log_id,不记录 token 原文。

调试与验收

模拟器调试

启动 dbx dev 创建 Sandbox Session 时,CLI/平台会把当前 Manifest 和可选 business-templates.yaml 加入 Session 创建请求。模板变化后:

  1. 手动重新执行业务模板兼容校验;
  2. 撤回并重建 Sandbox Session;
  3. 通过平台实际发起的 MCP Tool Call 取得 SessionToken;
  4. 跑通创建、运行中更新和 completed。

至少验证:

  • 同一 out_task_id 重试不重复创建,换模板被拒绝;
  • 未声明 scene key、缺变量、额外变量和非法进度被拒绝;
  • 更新响应返回 next_push_token,下一次更新使用最新 token;
  • completed 使用最新 token 进入预期终态;
  • 服务重启后仍可从持久化继续更新。

真机调试与正式上线

真机调试必须将 business-templates.yaml 与当前 Manifest、前端资源和其它应用产物一起上传为该次调试包。模拟器 Session 和模板单独同步都不能替代真机调试。

正式创建任务前确认:

  • 模板已严格校验、同步、审核并处于可用状态;
  • 正式 AppID、AppSecret、SessionToken 和模板属于同一环境;
  • 任务落地页已在 app.config.ts 注册;
  • 服务端具备持久化、并发保护、token 轮换和失败恢复;
  • 更新频率、有效期和数据保留策略满足业务与平台限制。

常见问题

创建接口提示缺少 SessionToken

SessionToken 必须来自平台调用 MCP Tool 时实际注入的 Header。不能通过固定值、默认用户、伪造 Header 或私有接口绕过。

开发态拿到的固定格式是 token=sess...;expire_in=...。必须先提取 token 字段,只把纯 token 传给创建接口;不能原样转发整个复合值。

task_detail 解析失败

对外 V1 HTTP 字段是 JSON 字符串,不是对象。使用 JSON 库分别序列化内层任务详情和外层请求。

scene key 或变量校验失败

检查 scene key 是否属于当前模板且模板内唯一;变量必须是 map<string,string>,并满足本次选中文案的需要。不要多传、少传或依赖模板 miss 后的空字符串。

更新一次成功,下一次提示 token 无效

确认是否保存并使用上一次响应的 next_push_token,并检查并发请求是否覆盖了更新后的 token。应使用串行更新或数据库版本号。

进度到 100 后任务仍未完成

数值进度不会自动触发终态。业务完成后还需要使用最新 push token 单独发送 task_status: completed。

completed 前的最终文案没有展示

completed 会忽略同一请求中的 task_detail 并隐藏任务。先做一次 running 更新展示 100% 或最终文案,再使用返回的 token 单独完成。

模拟器接口成功,但看不到任务

模拟器是否提供任务展示入口取决于当前版本。没有实际观察到入口时,应记录为 UNSUPPORTED 或 NOT VERIFIED,不能由接口成功推断用户侧已展示。

上线检查

  • business-templates.yaml 中只声明已实现的 remote 任务模板;
  • template_id 与通知模板不重名;
  • fallback、scene key、变量和跳转 Page 均已校验;
  • 应用级 Token 统一缓存和刷新;
  • SessionToken 来自可信 MCP 请求上下文;
  • 开发态固定格式的 SessionToken 已完成切分测试,下游 Header 只包含拆出的纯 token;
  • 创建响应中的 task ID 和 push token 已立即持久化;
  • 每次运行中更新都会原子保存 next_push_token;
  • 同一任务有串行更新或乐观锁保护;
  • completed 只由可信业务事实触发;
  • 幂等创建、异常变量、非法进度、并发更新和重启恢复均有测试;
  • 已分别记录模板校验、接口结果和用户侧展示结果;
  • 已使用受控账号完成真机验证。