多任务管理接入(服务端)
本文面向负责业务服务端、MCP Server 和任务状态管理的开发者,说明如何使用业务模板创建、更新和完成豆包应用插件中的远程任务。
当前服务端 OpenAPI 支持的是
remote远程任务。remote_normal_v1仅用于存量兼容,不应继续用于新增能力;不要因为配置 schema 接受task_type: local,就把 local 模板交给远程任务接口。
接入目标
多任务管理适合外卖配送、文件生成、审核处理、预约服务等不能在一次 MCP 调用内完成的长耗时业务。它让业务服务端在任务创建后持续更新标题、副标题、进度和剩余时间,并在业务真实完成时结束任务。
完整接入需要:
- 在
business-templates.yaml中配置 remote 任务模板、静态兜底文案和动态 scene key; - 在收到平台 MCP 调用时安全取得
X-DB-SessionToken; - 创建任务并持久化平台
task_id、push_token和本地业务状态; - 使用最新 push token 串行更新任务;
- 由可信业务事实触发 completed 终态。
标准链路为:
- 用户触发长耗时业务,平台向开发者 MCP 发起 Tool Call,并注入
X-DB-SessionToken; - MCP 将可信会话传给业务服务端,业务服务端调用
create_remote_task; - 创建成功后,立即持久化平台
task_id和首枚push_token; - 业务进度变化时,使用最新 push token 调用
update_remote_task; - 运行中更新返回
next_push_token后,原子保存为下一次更新的首选 token; - 业务真实完成后,再调用一次
update_remote_task(task_status=completed);完成响应通常不再返回下一枚 token。
名词解释
接入前准备
AccessToken、SessionToken 和 push token 只能保存在需要调用平台的服务端安全边界,不进入前端、Manifest、运行态 Skill、普通日志或接口响应。
开发态易错点:MCP 调用传入的 SessionToken Header 固定为
token=sess.<payload>.<signature>;expire_in=<seconds>,任务创建接口需要的则只有sess.<payload>.<signature>。必须先切分,不能把复合值原样传给下游。
配置任务模板
字段说明
fallback 不能使用占位符。动态文案必须放在 text_templates 中,并在运行时通过 scene key 选择。
建议按业务阶段定义清晰的 key,例如 preparing_title、delivering_title、completed_title。scene key 本身不绑定标题、副标题或进度字段,运行时把它放在哪个字段,就渲染到哪个字段。
运行时数据与模板的映射
任务详情对象示例:
运行时不能直接传 title、sub_title 或 progress_text 原文绕过模板。变量变化会影响已展示文案时,同一次更新必须重新携带对应 scene key。
校验与同步模板
先执行兼容校验:
只同步业务模板时:
显式同步要求项目根目录存在 business-templates.yaml;文件不存在时命令失败。执行 dbx build 创建完整版本时,该文件会自动参与严格校验和同步;文件缺失则跳过,不会清空远端。必须检查 config_sync_results 中的逐模板结果。
业务模板是应用级资源。上传新应用版本、回滚版本或从 YAML 删除模板,都不会自动删除或恢复某个线上模板。
获取调用凭证
创建任务需要两类凭证:
规范化 SessionToken
开发态 MCP 调用传入的 Header 固定为复合值:
其中 token 是任务创建接口需要的用户会话凭证,expire_in 是 MCP 调用侧附带的有效期元数据。调用 create_remote_task 前必须完成切分:
- 去掉整个 Header 值首尾空白;
- 按分号拆分字段,再按每个字段的第一个
=拆分 key 和 value; - 要求存在且仅存在一个非空
token字段和一个合法非负整数expire_in字段; - 取
token=后的完整值作为纯 SessionToken; - Header 为空、缺字段、字段重复或格式非法时停止创建;
- 下游
X-DB-SessionToken只能传拆出的纯 token,不能包含token=、;expire_in=...或其它元数据。
不要使用无上限的 split("="),因为 token 是 opaque value,未来可能包含 =。expire_in 只是输入侧伴随元数据;不要根据开发态示例中的 expire_in=0 推断 token 永久有效或立即失效。
TypeScript 示例:
框架可能把重复 Header 表示成字符串数组。应先拒绝歧义值或取得唯一值,再调用切分函数。日志只记录切分状态,不能记录原始值、纯 token 或可逆摘要。
AppID、AppSecret、AccessToken、SessionToken、模板必须属于同一应用与环境。
如果业务动作发生在原 MCP 请求结束之后,只能在平台允许的有效期和使用方式内保存必要身份。不能假设 SessionToken 永久有效。缺少有效 SessionToken 时,应停止创建任务并返回可诊断错误,不能伪造 Header、使用固定 token 或默认用户。
创建远程任务
基本信息
服务端 API 域名以 服务端 API 总览 中当前环境说明为准。
请求体
请求示例:
使用 JSON 库先序列化内层 detail,再序列化外层请求,不要手工拼接转义字符串。
响应
只有 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 改绑到另一个模板。
更新任务
基本信息
task_status 和 task_detail 至少提供一项。
更新进度或展示
运行中更新成功时,响应会返回 next_push_token:
收到后必须原子保存为后续首选 token。返回新 token 不代表旧 token 立即失效:旧 token 仍可能在原到期时间前通过签名校验,因此 token 不能代替业务并发控制。
完成任务
业务事实确认完成后,使用当前首选 token:
当前实现中,completed 会把任务更新为 SUCCESS/HIDDEN,忽略同一请求中的 task_detail,并且通常不返回 next_push_token。
如果需要在隐藏前展示 100% 或最终文案,应先发送一次 running 更新并保存响应中的最新 token,再单独发送 completed。不能因为前端页面关闭、MCP Tool 返回或进度达到 100,就自动推断业务已经完成。
持久化和并发
同一任务的更新应串行执行,或使用数据库乐观锁:
- 从持久化读取当前首选 token、到期时间和更新版本;
- 使用该 token 调用更新接口;
- 运行中更新成功且返回
next_push_token时,按旧版本做原子条件更新; - 条件更新失败说明另一请求已经提交,重新读取最新记录;
- completed 成功时保存终态,允许响应没有下一枚 token。
收到 token 失效错误时,先检查是否存在并发更新已经保存了新 token。无法确认时依据本地持久化和真实业务状态恢复,不能自动新建另一个 out_task_id。
日志只记录脱敏任务标识、模板 ID、阶段、进度、token 版本、结果码、错误类型和平台 log_id,不记录 token 原文。
调试与验收
模拟器调试
启动 dbx dev 创建 Sandbox Session 时,CLI/平台会把当前 Manifest 和可选 business-templates.yaml 加入 Session 创建请求。模板变化后:
- 手动重新执行业务模板兼容校验;
- 撤回并重建 Sandbox Session;
- 通过平台实际发起的 MCP Tool Call 取得 SessionToken;
- 跑通创建、运行中更新和 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 只由可信业务事实触发;
- 幂等创建、异常变量、非法进度、并发更新和重启恢复均有测试;
- 已分别记录模板校验、接口结果和用户侧展示结果;
- 已使用受控账号完成真机验证。