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

# 多任务管理接入（服务端）

> 本文面向负责业务服务端、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.yaml`         | remote 任务模板      |
| 5  | 实现任务持久化、乐观锁或串行更新                           | 可恢复的 token 和状态管理 |
| 6  | 确保 MCP Server 能取得平台注入的 `X-DB-SessionToken` | 可信用户会话           |

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

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

## 配置任务模板

```yaml
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 本身不绑定标题、副标题或进度字段，运行时把它放在哪个字段，就渲染到哪个字段。

## 运行时数据与模板的映射

任务详情对象示例：

```json
{
  "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。

## 校验与同步模板

先执行兼容校验：

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

只同步业务模板时：

```bash
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 固定为复合值：

```text
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 示例：

```ts
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 Method  | `POST`                                      |
| Content-Type | `application/json`                          |
| 鉴权           | `X-DB-AccessToken` + `X-DB-SessionToken`    |

服务端 API 域名以 [服务端 API 总览](/apps-plugin/docs/server-api/overview.md) 中当前环境说明为准。

### 请求体

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

请求示例：

```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，再序列化外层请求，不要手工拼接转义字符串。

### 响应

```json
{
  "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 Method  | `POST`                                      |
| Content-Type | `application/json`                          |
| 鉴权           | `X-DB-AccessToken` + 最新 push token          |

`task_status` 和 `task_detail` 至少提供一项。

### 更新进度或展示

```json
{
  "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`：

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

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

### 完成任务

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

```json
{
  "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 只由可信业务事实触发；
- 幂等创建、异常变量、非法进度、并发更新和重启恢复均有测试；
- 已分别记录模板校验、接口结果和用户侧展示结果；
- 已使用受控账号完成真机验证。
