AI服务接口说明

# Fusion AI 平台应用对外接口文档（Open API）

本文档面向需要对接 Fusion AI 智能体平台的外部系统，覆盖平台全部 `/open-api/**` 对外接口。文档按**领域 / 主题**组织：

- **应用对话**（第 4 章）：调用智能体应用完成对话、上传附件、管理会话、处理人工交互。
- **知识同步与治理**（第 5 章）：知识对象整包同步、文档生命周期、知识块与问题治理、图谱查询。
- **应用开通与调度**（第 6 章）：开通应用、创建定时任务、查询技能。
- **运营监控**（第 7 章）：运行趋势、质量指标、模型用量与 Token 对账。
- **AI 辅助**（第 8 章）：文档解析、摘要 / 标签辅助、Prompt 辅助。
- **外部服务 MCP 集成**（第 9 章）：外部工具 / 服务如何通过 MCP 协议注册进平台、绑定给智能体并供运行时调用；以及平台自身作为 MCP 服务端对外提供数据问答能力的接入方式。

各领域的端到端调用流程见第 10 章，curl 示例见第 11 章。

浏览器 / 网页组件接入方式（Client Token、`/api/client/**`）不在本文档范围内，详见 `docs/openapi/app-runtime-access.md`。

## 1. 总体架构与领域总览

### 1.1 平台与外部系统的交互全景

平台对外交互涉及五类角色：**业务系统**、**数据中台**、**本智能体平台**、**智能体应用**、**第三方接口**。

```mermaid
flowchart LR
 subgraph callers["调用方（入站）"]
 BIZ["业务系统 集成对话能力"]
 DATA["数据中台 知识同步与治理"]
 end

subgraph platform["Fusion AI 智能体平台（/open-api 统一接入面）"]
 GW["Open API 网关 凭证校验 · 幂等 · 统一响应 · traceId"]
 APPRUN["应用运行层 智能体应用（appKey · 已发布版本） 会话 · 附件 · HITL 交互"]
 RUNTIME["智能体运行时 ReAct 编排 · 工具 · 技能"]
 KNOW["知识引擎 RAG 混合检索 · 知识图谱"]
 STORE["存储与用量归因 模型调用台账"]
 end

subgraph third["第三方接口（平台出站调用）"]
        LLM["LLM 模型服务"]
        NET["互联网搜索"]
        TOOL["外部工具 / MCP 服务"]
    end

BIZ -- "App Token / 个人 API Key 对话 · 附件 · 会话 · 交互回调" --> GW
 DATA -- "系统 API Key 知识同步 · 应用开通 · 治理 · 统计" --> GW
 GW --> APPRUN
 APPRUN --> RUNTIME
 RUNTIME --> KNOW
 APPRUN --> STORE
 KNOW --> STORE
 RUNTIME -. "模型调用（按 traceId 计费）" .-> LLM
 RUNTIME -. "联网检索" .-> NET
 RUNTIME -. "工具调用" .-> TOOL
```

角色与数据流说明：

| 角色 | 与平台的数据交互 | 使用凭证 |
| --- | --- | --- |
| 业务系统 | 调用智能体应用完成对话（同步 / SSE 流式）、上传附件、恢复人工交互、查询与管理会话；也可携带系统 API Key 调用管理域接口（开通应用、同步知识、查询统计） | App Token / 个人 API Key（对话域）；系统 API Key（管理域） |
| 数据中台 | 整包同步知识对象、管理知识文档生命周期、治理知识块与问题、查询知识图谱、读取运行统计与模型用量 | 系统 API Key |
| 智能体应用 | 平台内已发布的应用版本（`appKey` + 来源绑定），是业务系统对话的目标，本身不主动外呼外部系统 | — |
| 第三方接口 | 平台运行时**出站**调用的外部能力：LLM 模型服务、互联网搜索、外部工具与 MCP 服务；调用与费用按 `traceId` 记入模型用量台账 | 平台内部管理，无需对接方配置 |
| 本智能体平台 | 统一 `/open-api/**` 接入面：网关完成凭证校验、幂等、统一响应与 `traceId` 归因，向下编排应用运行层、智能体运行时、知识引擎与存储 | — |

> **MCP 集成的两个方向**：上图中「第三方接口」里的外部工具 / MCP 服务属于**平台出站调用**——外部服务先注册为平台的 MCP 服务器（STDIO / SSE / Streamable HTTP 传输），绑定到智能体后由运行时按需调用，注册与绑定走管理端接口（见第 9 章）；反向地，平台自身的数据问答能力也以 **MCP 服务端**形式（`/api/data-qa/mcp`，JSON-RPC 2.0 over HTTP/SSE）暴露，供外部智能体系统接入调用（见 9.5）。

### 1.2 接口领域划分

| 领域 | 接口前缀 / 代表接口 | 凭证 | 典型调用方 |
| --- | --- | --- | --- |
| 应用对话 | `/open-api/apps/**`：`chat`、`stream`（SSE）、`conversations/**`、`attachments:upload`、`interactions/{id}/complete` | App Token 或个人 API Key | 业务系统服务端 |
| 知识同步与治理 | `/open-api/knowledge-objects:sync`、`/open-api/knowledge/**` | 系统 API Key | 数据中台、内容运营系统 |
| 应用开通与调度 | `/open-api/apps:upsert`、`/open-api/apps:delete`、`/open-api/scheduled-jobs/**`、`/open-api/skills/**` | 系统 API Key | 上游业务系统、运维系统 |
| 运营监控 | `/open-api/apps/{appId}/monitor/**`、`/open-api/apps/{appId}/llm-usage/**` | 系统 API Key | 运营 / 运维系统 |
| AI 辅助 | `/open-api/documents/**`、`/open-api/agent-prompts/**` | 系统 API Key | 内容运营、智能体配置端 |

上表为 `/open-api/**` 对外接口的领域划分。MCP 服务器的**注册、探测与智能体绑定**属于管理端能力，走 `/api/admin/**` 接口（MCP 服务器管理 + 智能体绑定），不在 `/open-api` 前缀下，完整接入方式见第 9 章；平台对外提供的 MCP 服务端地址为 `/api/data-qa/mcp`。

### 1.3 端到端集成链路

一次完整的对接通常按以下顺序推进，每一步的细节见对应章节：

1. **准备凭证**：管理端创建系统 API Key（管理域）与目标应用的 App Token（对话域），可先调用 `token/verify` 校验（见 3.5、4.3）。
2. **同步知识**（可选）：数据中台推送知识对象或文档，平台完成解析、分块、向量与图谱构建（见第 5 章）。
3. **开通应用**：上游系统 `apps:upsert` 一次性开通「智能体 + 应用」并发布版本，拿到 `appKey`（见 6.1）。
4. **接入对话**：业务系统携带 App Token 发起同步 / 流式对话，按需上传附件、处理 HITL 交互（见第 4 章）。
5. **统计对账**：运行请求量与模型用量按 `traceId` 关联回流，供监控与计费对账（见第 7 章）。
6. **扩展工具能力**（可选）：把外部工具 / 服务注册为 MCP 服务器并绑定给智能体，让对话过程可以调用外部能力；或反向将平台数据问答能力以 MCP 服务端形式接入外部智能体系统（见第 9 章）。

## 2. 通用约定

### 2.1 基础地址

| 项 | 说明 |
| --- | --- |
| 协议 | HTTP / HTTPS |
| 默认端口 | `18080`（可通过部署环境 `SERVER_PORT` 调整） |
| 接口前缀 | `/open-api/` |
| 字符集 | UTF-8 |
| 请求格式 | `Content-Type: application/json`（文件上传类接口为 `multipart/form-data`） |

完整请求地址 = `协议://主机地址:端口` + 接口路径。例如部署在 `192.168.1.100` 的平台，同步对话接口的完整地址为：

```
http://192.168.1.100:18080/open-api/apps/chat
```

本章后续各接口的「请求路径」均指相对于主机地址的路径，拼接方式同上。

### 2.2 响应包装

所有接口统一返回 `ApiResponse` 包装结构：

```json
{
  "code": 200,
  "message": "ok",
  "data": { }
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | int | `200` 表示成功，其他为错误码 |
| `message` | string | 提示信息，失败时为错误原因 |
| `data` | object | 业务数据，接口无返回体时可能为 `null` |

### 2.3 分页结构

分页查询接口的 `data` 为 `PageResponse`：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `records` | array | 当前页数据 |
| `total` | long | 总记录数 |
| `pageNum` | int | 当前页码，从 1 开始 |
| `pageSize` | int | 每页条数 |
| `pages` | int | 总页数 |

### 2.4 通用错误

| HTTP 状态 | 场景 | 响应示例 |
| --- | --- | --- |
| `400` | 参数校验失败、请求体非法 | `{code:400, message:"<校验信息>"}` |
| `401` | 凭证缺失、无效、已吊销或已过期 | `{code:401, message:"unauthorized"}` |
| `404` | 资源不存在 | `{code:404, message:"document not found: 123"}` |
| `409` | 幂等键冲突（内容不一致） | `{code:409, message:"..."}` |
| `500` | 服务端处理失败 | 结构见各接口说明 |

### 2.5 自定义方法路径

部分接口采用 Google AIP 风格的 `:method` 后缀，例如 `/open-api/knowledge-objects:sync`、`/open-api/apps:upsert`、`/open-api/apps/{appKey}/attachments:upload`。冒号是路径的一部分，不是参数分隔符，部分 HTTP 客户端需要转义或直接按字面量发送。

## 3. 认证与凭证

### 3.1 凭证类型总览

| 凭证 | 标识形式 | 适用范围 | 获取方式 |
| --- | --- | --- | --- |
| 系统 API Key | `sys_` 前缀字符串 | 知识同步与治理、应用开通与调度、运营监控、AI 辅助等管理域接口 | 管理端「系统 API Key」页面创建 |
| App Token | 平台签发的应用令牌 | 应用对话域接口 | 管理端目标应用的「Token 管理」创建 |
| 个人 API Key | `sys_` 前缀字符串 | 应用对话域接口（App Token 的替代方案） | 管理端个人 API Key 功能创建 |

> App Token 只能放在可信服务端，不应写入浏览器脚本或公开前端构建产物。

### 3.2 系统 API Key（管理域）

通过以下任一方式传递（`X-System-Api-Key` 优先）：

```http
X-System-Api-Key: sys_xxxxxxxxxxxx
```

或

```http
Authorization: Bearer sys_xxxxxxxxxxxx
```

校验规则：Key 必须以 `sys_` 开头，按前 16 位字符定位记录，密码哈希匹配、状态启用、未吊销且未过期。任一条件不满足返回 `401`。

### 3.3 App Token（应用对话域）

```http
Authorization: Bearer <appToken>
```

应用启用访问密码时，还需同时携带：

```http
X-App-Access-Password: <访问密码>
```

校验规则：App Token 必须归属请求中的目标应用，且应用存在已发布版本。请求体或路径中的 `appKey` 必须与 App Token 所属应用一致。

### 3.4 个人 API Key（应用对话域）

个人 API Key 同样以 `sys_` 开头，可通过 `X-System-Api-Key` 请求头访问对话域接口（平台按个人 API Key 解析应用访问权限），作为 App Token 的替代方案。注意它不能替代系统 API Key 调用管理域接口。

### 3.5 凭证校验

创建 App Token 后可先调用 `POST /open-api/apps/token/verify`（见 4.3）确认凭证与应用归属关系。

## 4. 应用对话域

本域接口面向需要调用平台智能体 / 工作流完成对话的调用方，使用 App Token（或个人 API Key）认证。

### 4.1 来源选择规则

- `sourceBindingId` 对应应用发布快照中的一个来源绑定，来源可以是智能体或工作流。
- 请求显式传入 `sourceBindingId` 时，服务端校验它属于当前应用的已发布版本。
- 未传 `sourceBindingId` 时，服务端按发布快照排序选择第一个来源（`sortOrder` 最小）。
- 会话创建后固定 `appVersionId` 和 `sourceBindingId`，后续消息不能把同一会话切换到其他来源。
- Open API 不执行浏览器 Origin 校验。

### 4.2 接口清单

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET` | `/open-api/apps/{appKey}` | 获取应用公开信息 |
| `GET` | `/open-api/apps/{appKey}/sources` | 获取已发布来源列表 |
| `POST` | `/open-api/apps/token/verify` | 校验 App Token 及应用归属 |
| `GET` | `/open-api/apps/{appKey}/conversations` | 分页获取会话 |
| `GET` | `/open-api/apps/{appKey}/conversations/{id}` | 获取会话详情 |
| `DELETE` | `/open-api/apps/{appKey}/conversations/{id}` | 删除会话 |
| `POST` | `/open-api/apps/{appKey}/conversations/{id}/feedback` | 提交消息反馈 |
| `POST` | `/open-api/apps/chat` | 同步对话，`appKey` 位于请求体 |
| `POST` | `/open-api/apps/stream` | SSE 流式对话，`appKey` 位于请求体 |
| `POST` | `/open-api/apps/{appKey}/attachments:upload` | 上传对话附件（见 4.6） |
| `POST` | `/open-api/apps/interactions/{interactionId}/complete` | 主动完成运行时交互（见 4.9） |

### 4.3 校验 App Token

`POST /open-api/apps/token/verify`

请求体：

```json
{ "appKey": "your-app-key" }
```

凭证通过请求头传递（`Authorization: Bearer <appToken>`，启用访问密码时附 `X-App-Access-Password`；也可用 `X-System-Api-Key` 传个人 API Key）。校验通过返回凭证与应用归属信息，失败返回 `401`。

成功响应示例：

```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "valid": true,
    "appId": 1934567890123456,
    "appKey": "your-app-key",
    "credentialType": "APP_TOKEN",
    "subjectType": "APP",
    "tokenId": 2087654321098765,
    "tokenName": "订单系统服务端 Token",
    "tokenType": "SERVICE",
    "allowedOrigins": null,
    "expiresAt": "2027-06-30 23:59:59"
  }
}
```

`data` 主要字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `valid` | boolean | 凭证是否有效 |
| `appId` / `appKey` | long / string | 凭证归属的应用 |
| `credentialType` | string | `APP_TOKEN`（App Token）或 `PERSONAL_API_KEY`（个人 API Key） |
| `subjectType` | string | 凭证主体类型 |
| `tokenId` / `tokenName` / `tokenType` | long / string / string | Token 标识、名称、类型 |
| `allowedOrigins` | string | 允许的来源（浏览器接入用） |
| `expiresAt` | string | 过期时间，`null` 表示长期有效 |

### 4.4 应用公开信息

`GET /open-api/apps/{appKey}`

`data` 主要字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | long | 应用 ID |
| `appName` / `appKey` | string | 应用名称与标识 |
| `description` / `icon` / `prologue` | string | 描述、图标、开场白 |
| `appType` | string | 应用类型 |
| `chatUserAuthenticationEnabled` | boolean | 是否启用对话用户认证 |
| `chatUserAuthenticationMethods` | array | 启用的认证方式 |
| `chatUserAuthenticationMaxAttempts` | int | 认证最大尝试次数 |
| `status` | int | 应用状态 |

### 4.5 来源列表

`GET /open-api/apps/{appKey}/sources`

`data` 为来源数组，每个来源主要字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `sourceBindingId` | long | 来源绑定 ID，外部选择来源的稳定标识 |
| `sourceType` | string | 来源类型：智能体或工作流 |
| `sourceId` | long | 来源资源 ID |
| `sourceName` / `displayName` | string | 来源名称与展示名称 |
| `versionPolicy` | string | 版本策略 |
| `description` / `icon` / `prologue` | string | 说明、图标、开场白 |
| `exampleQuestions` | array | 建议问题 |
| `isDefault` | boolean | 是否默认来源 |
| `sortOrder` | int | 排序值 |

### 4.6 附件上传

`POST /open-api/apps/{appKey}/attachments:upload`

对话前先把文件上传为平台附件，再把返回的 `attachmentId` 放进对话请求的 `attachments` 数组。附件归属发起上传的应用（以凭证解析出的应用为准），不能跨应用引用。

**请求**：`multipart/form-data`，只有一个文件 part：

| part | 类型 | 说明 |
| --- | --- | --- |
| `file` | file | 附件文件，part 名固定为 `file` |

认证方式与对话接口一致：`Authorization: Bearer <appToken>`（启用访问密码时附 `X-App-Access-Password`），或 `X-System-Api-Key` 传个人 API Key。

**支持的附件类型与限制**：

| 类型 | 支持格式 | 大小上限（默认） |
| --- | --- | --- |
| 图片（`IMAGE`） | png / jpeg / webp / gif | 10MB |
| 文档（`DOCUMENT`） | txt / md / csv / pdf / docx / xls / xlsx / zip | 10MB |

大小上限由服务端配置 `resource.chat-attachment.max-image-bytes` / `max-document-bytes` 决定，默认 10485760 字节。

**响应** `data`（`AttachmentResponse`）：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `attachmentId` | long | 附件 ID，对话请求用它引用附件 |
| `mediaType` | string | `IMAGE` 或 `DOCUMENT` |
| `mimeType` | string | 规范化后的 MIME 类型 |
| `name` | string | 原始文件名 |
| `size` | long | 文件字节数 |
| `width` / `height` | int | 图片尺寸，仅图片附件返回 |

响应示例：

```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "attachmentId": 3012345678901234,
    "mediaType": "DOCUMENT",
    "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "name": "2026年三季度经营分析.docx",
    "size": 2538173
  }
}
```

**在对话中引用附件**：

```json
{
  "appKey": "your-app-key",
  "message": "帮我总结这份文档",
  "attachments": [ { "attachmentId": 123456789 } ]
}
```

- `attachments` 每项只需 `attachmentId`，其余字段可选；若提供 `mimeType` 必须与平台存储记录一致，否则返回 `attachment metadata does not match stored file`。
- 图片附件进入模型多模态输入；文档附件由平台抽取文本（上限 16000 字符）注入对话。
- 附件必须归属当前应用：跨应用引用返回 `attachment does not belong to current target`；附件不存在返回 `404`，message 为 `attachment not found`。

**常见错误**：

| 场景 | 错误信息 |
| --- | --- |
| 文件类型不在支持列表 | `attachment type is not supported` |
| 图片超过大小上限 | `image upload exceeds max size` |
| 文档超过大小上限 | `document upload exceeds max size` |

### 4.7 对话接口

同步 `/chat` 与流式 `/stream` 使用同一条 AG-UI 执行链，请求体结构相同。

**请求体字段**（`OpenApiAppChatRequest`）：

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `appKey` | string | 必填，≤100 | 应用标识 |
| `sessionId` | long | 正数 | 已有会话 ID；不传则创建新会话 |
| `interactionId` | string | ≤128 | 待恢复的交互 ID（HITL 恢复时使用） |
| `clientRequestId` | string | ≤128 | 调用方幂等请求标识 |
| `sourceBindingId` | long | 正数 | 指定来源绑定；不传取默认来源 |
| `modelId` | long | 正数 | 指定模型；不传用会话/应用配置 |
| `enableThinking` | boolean | — | 是否开启深度思考 |
| `enableInternet` | boolean | — | 是否开启联网 |
| `userId` | string | — | 调用方用户标识，用于运行审计身份 |
| `message` | string | — | 用户消息文本（恢复请求不传） |
| `attachments` | array | — | 附件引用，来自 `attachments:upload`（见 4.6） |
| `knowledgeIds` | array | — | 指定知识库 ID 集合 |
| `knowledgeScopes` | array | — | 指定知识范围（`kbId` + 可选 `documentIds`） |
| `jsonSchema` | object | — | 结构化输出 JSON Schema，根节点必须是 `object`；不能与 `resume` 同时提交 |
| `resume` | array | — | 恢复响应数组（见 4.9） |
| `context` | object | — | 调用上下文透传 |

最小请求示例：

```json
{
  "appKey": "your-app-key",
  "message": "你好，请介绍一下你自己"
}
```

**同步响应**（`AppRuntimeChatResponse`）主要字段：`appId`、`sessionId`、`traceId`、`status`、`runId`、`userMessage`、`assistantMessage`、`structuredOutput`（传入 `jsonSchema` 时的结构化结果）、`knowledgeHits`、`knowledgeReferences`、`interaction`（需要人工处理时）。

成功响应示例：

```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "appId": 1934567890123456,
    "sessionId": 2070881913656696834,
    "traceId": "0af3c9e1b2d4478f",
    "status": "COMPLETED",
    "runId": "run-8842117a2c34",
    "entrySourceType": "AGENT",
    "entrySourceId": 1756342890123456,
    "entrySourceNameSnapshot": "客服知识问答智能体",
    "executorSourceType": "AGENT",
    "executorSourceId": 1756342890123456,
    "executorSourceNameSnapshot": "客服知识问答智能体",
    "workflowInstanceId": null,
    "userMessage": {
      "id": 3098765432109876,
      "sessionId": 2070881913656696834,
      "traceId": "0af3c9e1b2d4478f",
      "role": "user",
      "content": "帮我总结这份文档",
      "attachments": [],
      "createTime": "2026-09-07 14:30:05"
    },
    "assistantMessage": {
      "id": 3098765432109877,
      "sessionId": 2070881913656696834,
      "traceId": "0af3c9e1b2d4478f",
      "role": "assistant",
      "content": "这份文档的核心内容包括：……（完整回答文本）",
      "attachments": [],
      "createTime": "2026-09-07 14:30:12"
    },
    "structuredOutput": null,
    "interaction": null,
    "knowledgeHits": [
      {
        "knowledgeId": 1287654321098765,
        "documentId": 3612987654321098,
        "chunkId": 4901234567890123,
        "score": 0.87
      }
    ],
    "knowledgeReferences": [
      {
        "knowledgeId": 1287654321098765,
        "documentId": 3612987654321098,
        "title": "2026年三季度经营分析",
        "chunkId": 4901234567890123
      }
    ]
  }
}
```

`status` 常见取值：`COMPLETED`（运行完成）、`FAILED`（运行失败）、`WAITING_INTERACTION`（等待人工交互）。

需要人工处理时，同步接口返回 `status=WAITING_INTERACTION` 及 `interaction` 对象；调用方保存 `sessionId`、`interaction.id` 和全部 `interrupts[].id` 后按 4.9 恢复。

**流式响应**（SSE）事件类型：

| 事件 | 说明 |
| --- | --- |
| `session` | 会话信息 |
| `reasoning_delta` | 思考过程增量 |
| `tool_planned` | 工具调用计划 |
| `tool_args` | 工具参数 |
| `tool_result` | 工具执行结果 |
| `assistant_delta` | 回答增量；传入 `jsonSchema` 时运行结束后经 `assistant_delta.content` 返回完整 JSON |
| `interaction_required` | 需要人工处理 |
| `completed` | 运行结束，`status=WAITING_INTERACTION` 表示等待交互 |
| `error` | 运行错误 |

传入 `jsonSchema` 时，最终结构化对象在 `completed.response.structuredOutput` 返回。

流式响应为标准 SSE（`text/event-stream`），每个事件由 `event:`（事件类型）与 `data:`（事件 JSON 对象）两部分组成。一次典型运行的原始报文如下：

```
event:session
data:{"type":"session","sessionId":2070881913656696834,"appKey":"your-app-key"}

event:assistant_delta
data:{"type":"assistant_delta","delta":"这份文档"}

event:assistant_delta
data:{"type":"assistant_delta","delta":"的核心内容包括："}

event:completed
data:{"type":"completed","status":"COMPLETED","traceId":"0af3c9e1b2d4478f","sessionId":2070881913656696834}
```

调用方按 `event` 名分发处理：持续拼接 `assistant_delta` 的 `delta` 增量渲染回答；收到 `completed`（或 `error`）后结束本轮读取。`WAITING_INTERACTION` 状态会先出现 `interaction_required` 事件，随后 `completed` 携带 `status=WAITING_INTERACTION`。

### 4.8 会话管理

**分页获取会话** `GET /open-api/apps/{appKey}/conversations`

| 查询参数 | 类型 | 说明 |
| --- | --- | --- |
| `keyword` | string | 标题 / 摘要关键词 |
| `userId` | string | 按调用方用户标识过滤 |
| `conversationType` | string | `NORMAL`（普通会话）或 `SCHEDULED`（定时任务会话） |
| `sortBy` | string | 排序字段 |
| `sortOrder` | string | 排序方向 |
| `pageNum` | int | 页码，默认 1 |
| `pageSize` | int | 每页条数，默认 10 |

会话摘要主要字段：`id`、`appKey`、`appName`、`title`、`summary`、`displayName`、`conversationType`、`updatedAt`，以及 `conversationConfig`（`knowledgeIds`、`knowledgeNames`、`modelId`、`modelName`、`enableThinking`、`enableInternet`）。

**获取会话详情** `GET /open-api/apps/{appKey}/conversations/{id}?userId=<可选>`

详情额外包含 `traceId`、`messageId` 和 `messages[]`。消息字段：`id`、`role`、`content`、`attachments`（已持久化的附件引用）、`traceId`、`createTime`、`feedbackType`、`feedbackNote`、`feedbackCreatedAt`、`followUpPrompts[]`（`label`、`prompt`）、`knowledgeReferences[]`。

**删除会话** `DELETE /open-api/apps/{appKey}/conversations/{id}?userId=<可选>`

**提交消息反馈** `POST /open-api/apps/{appKey}/conversations/{id}/feedback`

```json
{
  "messageId": 123456789,
  "feedbackType": "like",
  "note": "可选反馈说明"
}
```

### 4.9 运行时交互与恢复（HITL）

智能体来源运行中产生人工交互中断时：

1. 流式接口依次返回 `interaction_required` 与一次 `completed`（`status=WAITING_INTERACTION`）；同步接口返回相同状态及 `interaction`。
2. 调用方必须保存 `sessionId`、`interaction.id` 和全部 `interrupts[].id`。

**恢复请求**使用原对话入口（`/chat` 或 `/stream`），只提交恢复字段：

```json
{
  "appKey": "your-app-key",
  "sessionId": "2070881913656696834",
  "interactionId": "interaction-id",
  "clientRequestId": "stable-client-request-id",
  "resume": [
    { "interruptId": "interrupt-1", "status": "resolved", "payload": { "approved": true } }
  ]
}
```

约束：

- `resume` 必须一次覆盖全部未决 interrupt。
- 恢复请求不能同时发送 `message` 或附件。
- `confirmationToken`、`confirmationDecision`、`authContinuationToken` 字段已删除，传入会返回 4xx。
- 权限确认中断使用 `reason=tool_call` 并在 `metadata["agentscope.interruptKind"]` 中标记 `permission_confirm`（平台同时识别旧版 `tool_confirmation`）。其 `resolved` 响应必须包含布尔值 `approved`，可选 `editedArgs` 必须是对象。
- 未带该 metadata 的普通 `tool_call` 属于外部工具中断，不能用默认批准 / 拒绝组件处理。
- 工作流来源暂不支持此 AG-UI HITL 恢复契约。

**服务端主动完成**（Open API 回调）：

```http
POST /open-api/apps/interactions/{interactionId}/complete
Authorization: Bearer <最初发起运行的 App Token>
Idempotency-Key: <稳定幂等键>
Content-Type: application/json

{"responses":[{"interruptId":"interrupt-1","status":"resolved","payload":{"approved":true}}]}
```

- `Idempotency-Key` 请求头必填。
- 该回调不接收 `appKey`、访问密码、Origin、scope 或新凭证，必须使用最初发起运行的同一凭证。
- 相同幂等键和请求内容可安全重试；不同内容冲突返回 `409`。
- 恢复运行再次产生中断时，响应 `status=WAITING_INTERACTION` 并携带新的 `interaction`，调用方必须改用新 interaction ID 继续恢复。
- 官方 coordinator 因节点重启或路由变化不可恢复时返回 `INTERACTION_RESUME_REJECTED`，interaction 进入 `EXPIRED`，不会根据数据库记录重放工具。

响应 `data` 主要字段：`interactionId`、`status`、`resumeRunId`、`interaction`、`response`、`errorCode`。

## 5. 知识同步与治理域

本域接口面向数据中台与内容运营系统，统一使用系统 API Key 认证，覆盖知识从同步入库、结构治理到图谱查询的完整链路。

### 5.1 知识对象整包同步

面向外部业务系统的知识推送总入口，以「知识对象」为单位整包同步。

`POST /open-api/knowledge-objects:sync`

- **幂等键**：`sourceSystem + businessCode + sourceObjectId`。同一对象重复推送按整包替换处理。
- **同步模式**：仅支持全量替换（REPLACE），不支持增量追加。
- **自动建库**：首次同步自动创建 3 个知识库：`document-{businessCode}`（文档库）、`qa-{businessCode}`（问答库）、`graph-{businessCode}`（图谱库）。
- 请求可携带 `X-Trace-Id` 头用于链路追踪。

请求体骨架（`OpenApiKnowledgeObjectSyncPayload`）：

```json
{
  "sourceSystem": "crm",
  "businessCode": "demo",
  "sourceObjectId": "obj-0001",
  "sourceObjectName": "示例对象",
  "sourceObjectRevisionId": "rev-0002",
  "revisionTime": "2026-09-01T00:00:00",
  "graph": {
    "document": [ ],
    "faq": [ ],
    "entities": [ ],
    "relations": [ ]
  }
}
```

| 字段 | 说明 |
| --- | --- |
| `sourceSystem` | 来源系统标识 |
| `businessCode` | 业务编码，决定自动创建的知识库名称 |
| `sourceObjectId` | 来源对象 ID，幂等键组成部分 |
| `sourceObjectRevisionId` / `revisionTime` | 版本号与版本时间，用于整包替换 |
| `graph.document` | 文档知识条目 |
| `graph.faq` | 问答知识条目 |
| `graph.entities` | 图谱实体 |
| `graph.relations` | 图谱关系 |

字段级填写示例参见 `docs/openapi/外部系统对接Apifox测试说明 - 副本.md` 与 `docs/openapi/通用知识库一次推送示例-*.json`、`服务事项-*.json`。

成功响应示例：

```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "sourceSystem": "crm",
    "businessCode": "demo",
    "sourceObjectId": "obj-0001",
    "sourceObjectName": "示例对象",
    "status": "SUCCESS",
    "failedStage": null,
    "failedStageName": null,
    "errorCode": null,
    "errorMessage": null,
    "traceId": "0af3c9e1b2d4478f",
    "syncTime": "2026-09-07 14:30:20"
  }
}
```

`status` 取值：`SUCCESS`（全部阶段成功）、`FAILED`（失败，`failedStage` / `errorCode` / `errorMessage` 标明原因，见 5.4）。

### 5.2 实体范围（PRIVATE / SHARED）

图谱实体分两种归属范围，实体 ID 由平台按规则生成：

| 范围 | 实体 ID 规则 | 说明 |
| --- | --- | --- |
| 私有（PRIVATE） | `{businessCode}:{sourceObjectId}:{entity.id}` | 只属于当前知识对象 |
| 共享（SHARED） | `{businessCode}:shared:{entity.id}` | 跨知识对象共享，同名实体自动合并 |

### 5.3 删除接口

**删除知识对象** `DELETE /open-api/knowledge-objects`

```json
{
  "sourceSystem": "crm",
  "businessCode": "demo",
  "sourceObjectId": "obj-0001"
}
```

删除该知识对象下三个知识库的全部内容。

**删除共享图谱实体** `DELETE /open-api/knowledge-objects/graph/shared-entities`

```json
{
  "sourceSystem": "crm",
  "businessCode": "demo",
  "entityIds": ["demo:shared:entity-1"],
  "force": true
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `sourceSystem` | string | 来源系统标识 |
| `businessCode` | string | 业务编码 |
| `entityIds` | string[] | 要删除的共享实体 ID 列表 |
| `force` | boolean | 是否强制删除（可选） |

### 5.4 同步失败响应

同步失败时返回 HTTP 500，结构化标明失败阶段：

```json
{
 "code": 500,
 "message": "知识对象同步失败：{stageName}同步失败",
 "data": {
 "sourceSystem": "crm",
 "businessCode": "demo",
 "sourceObjectId": "obj-0001",
 "sourceObjectName": "示例对象",
 "status": "FAILED",
 "failedStage": "<阶段名>",
 "errorCode": "<错误码>"
 }
}
```

`data` 内含 `traceId`，可用于反馈排查。失败后可整包重推（幂等键不变即整包替换）。

### 5.5 知识文档生命周期

面向按「单文档」粒度对接的外部系统，支持文档上传、删除与任务状态查询。

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `POST` | `/open-api/knowledge/documents:upsert` | 上传 / 更新文档 |
| `POST` | `/open-api/knowledge/documents:delete` | 删除文档 |
| `GET` | `/open-api/knowledge/documents/{documentId}/latest-task` | 查询最近一次处理任务 |
| `GET` | `/open-api/knowledge/documents/{documentId}/tasks` | 分页查询处理任务 |
| `GET` | `/open-api/knowledge/documents/{documentId}/status` | 查询文档当前状态 |

#### 上传 / 更新文档

`multipart/form-data`，两个 part：

- `payload`：JSON 字符串（`OpenApiKnowledgeDocumentUpsertPayload`）
- `mainFile`：文档文件

`payload` 主要字段（与 6.1 `apps:upsert` 一致的 source ID 幂等设计）：

| 字段 | 说明 |
| --- | --- |
| `workspaceId` | 工作空间 ID |
| `rootCategoryInfo` / `categoryInfo` | 分类信息（source ID + 平台 ID + 名称） |
| `knowledgeInfo` | 知识库信息（source ID / `kbId` 等） |
| `documentInfo.kbType` | 知识库类型 |
| `documentInfo.retrievalEngineType` | 检索引擎类型 |
| `documentInfo.generateQuestions` / `questionCount` | 是否自动生成问题及数量 |
| `documentInfo.isUpdate` | 是否更新已有文档 |
| `documentInfo.contentText` | 直接提交文本内容（与 `mainFile` 二选一） |
| `documentInfo.url` | 文档来源 URL |
| `documentInfo.question` / `answers` / `answerStrategy` | 问答对内容与回答策略 |
| `documentInfo.tagName` | 标签 |
| `documentInfo.enabled` / `recommended` | 启用与推荐标记 |

#### 状态与任务查询

- `latest-task`：无任务时返回 `404`，message 为 `knowledge task not found for document: {id}`。
- `status`：文档不存在时返回 `404`，message 为 `document not found: {id}`。
- `tasks`：支持 `pageNum` / `pageSize` 分页。

### 5.6 知识块与问题治理

前缀：`/open-api/knowledge`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET` | `/open-api/knowledge/documents/{documentId}/chunks` | 查询文档知识块 |
| `GET` | `/open-api/knowledge/documents/{documentId}/questions` | 查询文档问题 |
| `GET` | `/open-api/knowledge/chunks/{chunkId}/questions` | 查询知识块关联问题 |
| `DELETE` | `/open-api/knowledge/chunks/{chunkId}` | 删除知识块 |
| `PUT` | `/open-api/knowledge/chunks/{chunkId}` | 更新知识块 |
| `PUT` | `/open-api/knowledge/chunks/{chunkId}/tags` | 更新知识块标签 |
| `POST` | `/open-api/knowledge/chunks/{chunkId}/questions` | 新增问题 |
| `DELETE` | `/open-api/knowledge/questions/{questionId}` | 删除问题 |
| `PUT` | `/open-api/knowledge/questions/{questionId}` | 更新问题 |
| `POST` | `/open-api/knowledge/chunks/{chunkId}/questions:bind` | 绑定问题到知识块 |
| `POST` | `/open-api/knowledge/chunks/{chunkId}/summary-tags:regenerate` | 重新生成摘要标签（异步） |
| `POST` | `/open-api/knowledge/chunks/{chunkId}:generate-questions` | 生成问题（可选 `questionCount`） |

**问题保存请求体**（新增 / 更新）：

| 字段 | 说明 |
| --- | --- |
| `question` | 问题文本 |
| `answer` | 答案文本 |
| `recommended` | 是否推荐 |
| `tagName` | 标签 |
| `answerStrategy` | 回答策略 |
| `status` | 状态 |

`summary-tags:regenerate` 与 `generate-questions` 为异步任务，返回异步任务响应（任务 ID），结果通过 5.5 节任务查询接口或管理端查看。

### 5.7 知识图谱查询

前缀：`/open-api/knowledge/graph`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET` | `/open-api/knowledge/graph/overview` | 图谱总览 |
| `GET` | `/open-api/knowledge/graph/neighborhood` | 实体邻域查询 |
| `GET` | `/open-api/knowledge/graph/entities/sources` | 实体来源查询 |
| `GET` | `/open-api/knowledge/graph/entities/page` | 实体分页查询 |

- `overview`：`kbId` 或 `documentId` 必传其一，否则返回 `400`，message 为 `kbId or documentId is required`。
- `entities/page`：支持 `q`、`name`、`alias`、`type`、`description` 等过滤参数。
- 图谱数据为空时返回空结构而非错误。

## 6. 应用开通与调度域

本域接口面向上游业务系统与运维系统，统一使用系统 API Key 认证，完成「智能体 + 应用」的批量开通、定时任务管理与技能查询。

### 6.1 开通 / 更新应用

`POST /open-api/apps:upsert`

请求体按「来源 ID」幂等：各层级均支持 `sourceXxxId`（外部系统自己的稳定 ID），平台按 source ID 匹配已有资源，存在则更新、不存在则创建。

```json
{
  "workspaceId": 1,
  "rootAgentCategoryInfo": {
    "sourceAgentRootCategoryId": "rc-001",
    "rootAgentCategoryId": null,
    "rootAgentCategoryName": "外部智能体根分类"
  },
  "agentCategoryInfo": {
    "sourceAgentCategoryId": "c-001",
    "agentCategoryId": null,
    "agentCategoryName": "外部智能体分类"
  },
  "agentInfo": {
    "sourceAgentId": "agent-001",
    "agentId": null,
    "agentName": "示例智能体",
    "description": "由外部系统开通",
    "modelConfigId": 100,
    "systemPrompt": "你是一个助手",
    "agentMode": "a",
    "agentType": "chat",
    "agentKnowledgeBindings": [ { "kbId": 200, "documentIds": [] } ],
    "skillBindings": [ { "skillId": 300 } ],
    "scheduledJob": {
      "cron": "0 0 2 * * ?",
      "enabled": true,
      "input": "定时执行的任务输入",
      "dryRun": false,
      "attachments": [],
      "metadata": {},
      "remark": "可选"
    },
    "status": 1
  },
  "rootAppCategoryInfo": { "sourceAppRootCategoryId": "arc-001", "rootAppCategoryName": "外部应用根分类" },
  "appCategoryInfo": { "sourceAppCategoryId": "ac-001", "appCategoryName": "外部应用分类" },
  "appInfo": {
    "sourceAppId": "app-001",
    "appName": "示例应用",
    "description": "外部系统开通的应用",
    "prologue": "你好，我可以帮你什么？",
    "presetQuestions": ["你能做什么？"],
    "appType": "chat",
    "publicAccess": "Y",
    "clientVisible": "Y",
    "showKnowledgeReferences": "Y",
    "enableExecutionDetail": "N",
    "status": 1,
    "autoPublish": true
  }
}
```

要点：

- `agentMode`：`a`（智能体）或 `w`（工作流），本次开通以智能体为主。
- `scheduledJob` 可选，为该智能体同步创建定时任务。
- `autoPublish=true` 时开通后自动发布应用版本，外部立即可对话。
- `kbId`、`skillId`、`modelConfigId`、`documentIds` 为平台侧 ID，可先通过知识同步（第 5 章）与技能查询（6.4）获得。

响应 `data` 返回各层级映射结果，每个层级含 `sourceXxxId`、平台 ID（`rootAgentCategoryId`、`agentCategoryId`、`agentId`、`rootAppCategoryId`、`appCategoryId`、`appId`、`appKey`、`appVersionId`、`publishTime`）和 `isChange` 变更标记。

响应示例：

```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "rootAgentCategoryInfo": {
      "sourceAgentRootCategoryId": "rc-001",
      "rootAgentCategoryId": 2100000000000001,
      "isChange": true
    },
    "agentCategoryInfo": {
      "sourceAgentCategoryId": "c-001",
      "agentCategoryId": 2100000000000002,
      "isChange": true
    },
    "agentInfo": {
      "sourceAgentId": "agent-001",
      "agentId": 2200000000000003,
      "isChange": true,
      "scheduledJobInfo": {
        "jobId": 2300000000000004,
        "enabled": true,
        "deleted": false,
        "isChange": true
      }
    },
    "rootAppCategoryInfo": {
      "sourceAppRootCategoryId": "arc-001",
      "rootAppCategoryId": 2400000000000005,
      "isChange": true
    },
    "appCategoryInfo": {
      "sourceAppCategoryId": "ac-001",
      "appCategoryId": 2400000000000006,
      "isChange": true
    },
    "appInfo": {
      "sourceAppId": "app-001",
      "appId": 2500000000000007,
      "appKey": "ak-demo-7f3e2c",
      "isChange": true,
      "appVersionId": 2600000000000008,
      "publishTime": "2026-09-07 14:32:10"
    }
  }
}
```

外部系统应持久化返回的平台 ID（尤其是 `appId` 与 `appKey`）：后续对话用 `appKey`，删除（6.2）、统计（第 7 章）用 `appId`；`isChange=true` 表示本次实际发生了创建或更新。

### 6.2 删除应用

`POST /open-api/apps:delete`

```json
{
  "appInfo": { "appId": 1001 },
  "agentInfo": { "agentId": 2001 }
}
```

支持按平台 ID 定位删除；`agentInfo` 可选，同时传入时连同智能体一起删除。

### 6.3 定时任务

前缀：`/open-api/scheduled-jobs`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET` | `/open-api/scheduled-jobs` | 分页查询（`pageNum` / `pageSize`） |
| `GET` | `/open-api/scheduled-jobs/{id}` | 任务详情 |
| `GET` | `/open-api/scheduled-jobs/stats?appId=` | 按应用统计 |
| `POST` | `/open-api/scheduled-jobs` | 创建任务 |
| `PUT` | `/open-api/scheduled-jobs/{id}` | 更新任务 |
| `PUT` | `/open-api/scheduled-jobs/{id}/status` | 启用 / 停用 |
| `POST` | `/open-api/scheduled-jobs/{id}:run` | 手动触发一次，可选 body `{ "operator": "xxx" }` |
| `DELETE` | `/open-api/scheduled-jobs/{id}` | 删除任务 |
| `GET` | `/open-api/scheduled-jobs/{id}/logs` | 执行日志 |

**创建 / 更新请求体**（`OpenApiScheduledJobUpsertRequest`）：

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `appId` | long | 必填 | 归属应用 |
| `jobName` | string | 必填，≤120 | 任务名称 |
| `cron` | string | 必填，≤64 | Cron 表达式 |
| `input` | string | 必填，≤500 | 任务输入 |
| `enabled` | boolean | 必填 | 是否启用 |
| `remark` | string | ≤500 | 备注 |
| `operator` | string | ≤100 | 操作人（可选） |

任务响应主要字段：`id`、`taskKey`、`bizType`、`bizId`、`appId`、`appName`、`appKey`、`jobName`、`cron`、`enabled`、`nextFireTime`、`input`、`payload`、`remark`、`createTime`、`updateTime`。

创建任务响应示例：

```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "id": 2300000000000004,
    "taskKey": "openapi-job-1f4a",
    "bizType": "APP",
    "bizId": 2500000000000007,
    "appId": 2500000000000007,
    "appName": "示例应用",
    "appKey": "ak-demo-7f3e2c",
    "jobName": "每日凌晨汇总",
    "cron": "0 0 2 * * ?",
    "enabled": true,
    "nextFireTime": "2026-09-08 02:00:00",
    "input": "汇总昨日客服工单并输出报告",
    "payload": {},
    "remark": "由外部系统创建",
    "createTime": "2026-09-07 14:35:00",
    "updateTime": "2026-09-07 14:35:00"
  }
}
```

### 6.4 技能查询

前缀：`/open-api/skills`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET` | `/open-api/skills` | 分页查询，参数：`name`、`status`、`category`、`workspaceId`、`pageNum`、`pageSize` |
| `GET` | `/open-api/skills/categories?workspaceId=` | 技能分类列表 |
| `GET` | `/open-api/skills/{id}` | 技能详情 |

技能 ID 可用于 6.1 `apps:upsert` 的 `skillBindings`。

## 7. 运营监控域

本域接口面向运营 / 运维系统，统一使用系统 API Key 认证，口径与管理端监控中心入口归因一致。

### 7.1 运行监控

前缀：`/open-api/apps/{appId}/monitor`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET` | `/trend` | 运行趋势 |
| `GET` | `/trend/users` | 用户数趋势 |
| `GET` | `/trend/questions` | 提问数趋势 |
| `GET` | `/trend/tokens` | Token 消耗趋势 |
| `GET` | `/metrics` | 核心指标 |
| `GET` | `/quality` | 质量指标 |
| `GET` | `/top-token-users` | Token 消耗 Top 用户 |

通用查询参数：`days`（优先）或 `startDate` / `endDate`，默认最近 7 天。`top-token-users` 支持 `limit`，默认 10，最大 50。

### 7.2 模型用量

前缀：`/open-api/apps/{appId}/llm-usage`

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET` | `/summary` | 用量汇总 |
| `GET` | `/trend` | 用量趋势 |
| `GET` | `/records` | 用量明细分页，支持 `traceId` 精确过滤、`pageNum` / `pageSize` |

查询参数：`startDate`、`endDate`、`usageSource`、`status`。

`/summary` 响应示例：

```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "appId": 2500000000000007,
    "startDate": "2026-09-01",
    "endDate": "2026-09-07",
    "totalCalls": 1523,
    "totalPromptTokens": 8123400,
    "totalCompletionTokens": 1956700,
    "totalTokens": 10080100,
    "totalCostAmount": 36.8420,
    "actualUsageRatio": 0.9217,
    "estimatedUsageRatio": 0.0783
  }
}
```

`actualUsageRatio` / `estimatedUsageRatio` 为真实模型返回（actual）与估算（estimated）用量的占比，取值区间 0~1，保留 4 位小数。

`/records` 单条记录主要字段：`id`、`usageDate`、`occurredAt`、`executorSourceType`、`executorSourceId`、`executorSourceName`、`providerId`、`providerType`、`modelConfigId`、`modelName`、`usageSource`（`actual` / `estimated`）、`pricingStatus`、`promptTokens`、`completionTokens`、`totalTokens`、`totalCostAmount`、`status`、`traceId`、`workflowInstanceId`。记录按 `traceId` 与 7.3 的运行日志关联。

`/records` 响应示例（分页）：

```json
{
  "code": 200,
  "message": "ok",
  "data": {
    "records": [
      {
        "id": 7700000000000012,
        "usageDate": "2026-09-07",
        "occurredAt": "2026-09-07 14:30:12",
        "executorSourceType": "AGENT",
        "executorSourceId": 2200000000000003,
        "executorSourceName": "示例智能体",
        "providerId": 11,
        "providerType": "openai-compatible",
        "modelConfigId": 100,
        "modelName": "qwen-plus",
        "usageSource": "actual",
        "pricingStatus": "PRICED",
        "promptTokens": 1820,
        "completionTokens": 436,
        "totalTokens": 2256,
        "totalCostAmount": 0.0158,
        "status": "SUCCESS",
        "traceId": "0af3c9e1b2d4478f",
        "workflowInstanceId": null
      }
    ],
    "total": 1523,
    "size": 10,
    "current": 1
  }
}
```

### 7.3 运行归因字段

每次外部运行请求由服务端生成 `traceId`，可通过 `X-Trace-Id` 请求头透传。入口请求量来自 `app_runtime_request_log`，真实模型调用、Token 和费用来自 `model_usage_ledger`，两者通过 `traceId` 关联，不能相加作为请求量或重复计费。

## 8. AI 辅助域

本域接口面向内容运营与智能体配置场景，统一使用系统 API Key 认证。接口按其内部模型调用计费（归入模型用量台账），其余管理域接口不产生模型计费。

### 8.1 文档解析

| 方法 | 路径 | 参数 | 用途 |
| --- | --- | --- | --- |
| `POST` | `/open-api/documents/parse-text` | `file`（必填）、`parserEngine`（可选） | 解析文档为文本 |
| `POST` | `/open-api/documents/parse-qa-pairs` | `file`（必填） | 解析文档中的问答对 |

均为 `multipart/form-data`。

### 8.2 文档 AI 辅助

均为 `multipart/form-data`：

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `POST` | `/open-api/documents/assist` | 文档内容辅助 |
| `POST` | `/open-api/documents/summary-assist` | 摘要辅助 |
| `POST` | `/open-api/documents/tag-assist` | 标签辅助 |

`summary-assist` 主要参数：`action`、`title`、`currentSummary`、`contentType`、`contentFormat`、`contentText`、`mainFile`、`maxLength`。

### 8.3 智能体 Prompt 辅助

`POST /open-api/agent-prompts/assist`

请求体：

| 字段 | 约束 | 说明 |
| --- | --- | --- |
| `action` | 必填 | 辅助动作 |
| `agentName` | — | 智能体名称 |
| `agentType` | — | 智能体类型 |
| `description` | — | 智能体描述 |
| `knowledgeScopes` | — | 知识范围（`kbId` + 可选 `documentIds`） |
| `currentSystemPrompt` | — | 当前系统提示词 |

请求体非法时返回 `400`，message 为 `request body is invalid`。

## 9. 外部服务通过 MCP 集成

本章回答两个问题：

- **外部服务接入平台（入站方向）**：外部工具 / 服务如何注册为平台的 MCP 服务器、绑定给智能体、并在对话运行时被调用（9.1 ~ 9.4）。
- **平台能力开放给外部智能体（出站方向）**：平台的数据问答能力如何以 MCP 服务端形式提供给外部智能体系统调用（9.5）。

MCP（Model Context Protocol）是智能体生态通用的工具接入协议。平台支持 STDIO、SSE、Streamable HTTP 三种传输；MCP 服务器一旦注册并绑定给智能体，其工具会出现在智能体的工具列表中，智能体可在对话过程中自主决定调用。

需要特别注意：**MCP 注册、探测与绑定走管理端接口（`/api/admin/**`），不在 `/open-api` 前缀下**。这些接口面向平台管理员 / 运维人员（需要管理端登录态与对应按钮权限），而非外部业务系统的服务端凭证。

### 9.1 集成链路总览

```mermaid
flowchart TB
 subgraph ext["外部工具 / 服务提供方"]
 SVC["对外服务 （REST / 本地进程 / MCP）"]
 end

subgraph admin["平台管理端（管理员操作）"]
 REG["注册 MCP 服务器 POST /api/admin/plugins/mcp-servers"]
 PROBE["能力探测 POST /{id}/capabilities/probe"]
 TOOLS["工具目录 GET /{id}/tools · 全局启用"]
 BIND["绑定智能体 PUT /api/admin/agents/{agentId}/mcp-servers"]
 end

subgraph runtime["平台运行时"]
 CATALOG["MCP 工具目录 enabled=1 且 missing=0 的工具进入智能体工具列表"]
 LAZY["懒加载调用 首次调用该工具时才建立连接"]
 HEALTH["健康熔断 连续传输失败达阈值自动跳过"]
 end

subgraph consumers["对话调用方"]
        BIZ2["业务系统（App Token）"]
    end

SVC -->|"STDIO / SSE / Streamable HTTP headers 鉴权配置"| REG
 REG --> PROBE
 PROBE --> TOOLS
 TOOLS --> BIND
 BIND --> CATALOG
 CATALOG --> LAZY
 LAZY -. "按需调用外部服务" .-> SVC
 LAZY --> HEALTH
 BIZ2 -->|"对话触发智能体运行"| LAZY
```

五个关键步骤：

1. **注册**：管理员把外部服务注册为 MCP 服务器（9.2），配置传输协议与鉴权信息（9.3）。
2. **探测**：平台连接该服务，读取 `serverInfo` 与全部工具 / 资源 / Prompt 清单并落库（9.4）。
3. **工具目录**：管理员查看 / 启用工具，控制哪些工具可被使用（9.4）。
4. **绑定**：把 MCP 服务器绑定给某个智能体，可按工具名过滤并注入默认参数（9.4）。
5. **运行时调用**：智能体对话过程中按需调用工具，平台负责连接懒加载与健康熔断（9.4）。

### 9.2 注册 MCP 服务器（管理端）

MCP 服务器管理接口前缀为 `/api/admin/plugins/mcp-servers`，需要管理端登录态及 `plugin:mcp:*` 或 `resource:mcp:*` 按钮权限：

| 方法 | 路径 | 权限 | 用途 |
| --- | --- | --- | --- |
| `GET` | `/api/admin/plugins/mcp-servers` | `plugin:mcp:list` 或 `resource:mcp:list` | 分页查询（`serverName`、`serverKey`、`serverType`、`status` 等筛选） |
| `GET` | `/api/admin/plugins/mcp-servers/{id}` | 同上 | 详情（含被哪些智能体使用） |
| `POST` | `/api/admin/plugins/mcp-servers` | `plugin:mcp:create` 或 `resource:mcp:create` | 注册 MCP 服务器 |
| `PUT` | `/api/admin/plugins/mcp-servers/{id}` | `plugin:mcp:update` 或 `resource:mcp:update` | 更新配置 |
| `PATCH` | `/api/admin/plugins/mcp-servers/{id}/status` | 同上 | 启用 / 停用 |
| `DELETE` | `/api/admin/plugins/mcp-servers/{id}` | `plugin:mcp:remove` 或 `resource:mcp:remove` | 删除 |
| `POST` | `/api/admin/plugins/mcp-servers/{id}/capabilities/probe` | `plugin:mcp:create` 或 `resource:mcp:create` | 能力探测（9.4） |
| `GET` | `/api/admin/plugins/mcp-servers/{id}/tools` | `plugin:mcp:list` 或 `resource:mcp:list` | 工具目录 |
| `PUT` | `/api/admin/plugins/mcp-servers/{id}/tools/global-enabled` | `plugin:mcp:update` 或 `resource:mcp:update` | 批量设置工具全局启用 |
| `POST` | `/api/admin/plugins/mcp-servers/{id}/tools/{toolName}/debug-call` | `plugin:mcp:create` 或 `resource:mcp:create` | 调试调用单个工具 |

**注册请求体**（`McpServerUpsertRequest`）：

| 字段 | 类型 | 约束 | 说明 |
| --- | --- | --- | --- |
| `serverName` | string | 必填 | 服务器显示名称 |
| `serverKey` | string | 必填 | 唯一标识（如 `weather-service`） |
| `serverType` | string | 必填 | 传输类型：`STDIO` / `SSE` / `HTTP`（即 Streamable HTTP） |
| `category` | string | — | 分类 |
| `config` | object | — | 连接配置，按 `serverType` 不同（见 9.3） |
| `status` | int | — | 启用状态 |
| `resourceScope` | string | — | `PUBLIC`（全局共享，`workspaceId=0`）或工作空间级 |
| `remark` | string | — | 备注 |

**注册 Streamable HTTP 服务的示例**（外部服务已按 MCP 协议提供 `/mcp` 端点，并用 Bearer Token 鉴权）：

```json
{
  "serverName": "客户工单查询服务",
  "serverKey": "crm-ticket-service",
  "serverType": "HTTP",
  "category": "业务系统",
  "config": {
    "url": "https://crm.example.com/mcp",
    "headers": {
      "Authorization": "Bearer mcp-internal-token-xxxx"
    },
    "timeout_seconds": 30
  },
  "status": 1,
  "resourceScope": "PUBLIC",
  "remark": "数据中台工单查询 MCP 服务"
}
```

**响应**（`McpServerResponse`）主要字段：`id`、`serverName`、`serverKey`、`serverType`、`category`、`config`、`status`、`isBuiltin`、`healthStatus`、`lastHealthCheck`、`workspaceId`、`resourceScope`、`canManage`、`createBy`、`createTime`、`updateBy`、`updateTime`、`used`。后续探测、绑定均使用返回的 `id`。

### 9.3 传输协议与连接鉴权配置

`config` 按 `serverType` 区分（`serverType` 大小写不敏感，平台统一转大写处理）：

| serverType | 必填配置 | 说明 |
| --- | --- | --- |
| `HTTP` / `STREAMABLE_HTTP` | `url` | Streamable HTTP 单端点地址，如 `https://host/mcp` |
| `SSE` | `url` | SSE 端点**完整路径**（如 `https://host/sse`），不能只写域名根路径 `/` |
| `STDIO` | `command`（可选 `args`、`env`） | 平台本地进程方式拉起，如 `command: "node"`、`args: ["server.js"]` |

通用可选配置：

| 配置键 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `headers` | object | — | 注入到**每个**请求的 HTTP 头，用于向外部服务鉴权（如 `Authorization: Bearer xxx`、`X-Api-Key: xxx`） |
| `queryParams` | object | — | 附加查询参数，与 `url` 中已有参数合并 |
| `timeout_seconds` / `timeout` | number | 30 | 请求超时（秒） |
| `initialization_timeout_seconds` | number | 30 | MCP 初始化握手超时（秒） |

外部服务的鉴权信息**统一配置在 `config.headers` 中**，由平台在每次调用时注入，外部服务侧按自有体系校验；平台不代管外部服务的 Token 生命周期，Token 过期需管理员更新服务器配置。

### 9.4 能力探测、工具目录与智能体绑定

**能力探测**：`POST /api/admin/plugins/mcp-servers/{id}/capabilities/probe` 连接目标服务并返回 `serverInfo`（名称 / 版本 / 说明）、能力统计（`toolCount`、`resourceCount`、`promptCount`、`probeStatus`）与告警信息。探测成功后工具清单落入工具目录。

**工具目录**：`GET /api/admin/plugins/mcp-servers/{id}/tools` 返回每个工具的 `toolName`、`toolTitle`、`description`、`inputSchema`、`outputSchema`、`enabled`、`missing`（外部服务已不存在该工具时为 `true`）。只有 `enabled=1` 且 `missing=0` 的工具会进入智能体可用工具列表。

**绑定智能体**：`PUT /api/admin/agents/{agentId}/mcp-servers`（权限 `agent:update`）以**整表替换**方式设置某智能体绑定的全部 MCP 服务器。请求体：

```json
{
  "items": [
    {
      "targetId": 3000000000000111,
      "config": {
        "includeTools": ["query_ticket", "list_orders"],
        "toolParameters": {
          "query_ticket": { "maxResults": 20 }
        }
      }
    }
  ]
}
```

- `items[].targetId`：MCP 服务器 ID（9.2 响应中的 `id`）。
- `items[].config` 为可选的绑定级配置：

| 配置键 | 类型 | 说明 |
| --- | --- | --- |
| `includeTools` | string[] | 只暴露列出的工具（白名单） |
| `excludeTools` | string[] | 屏蔽列出的工具（黑名单） |
| `toolGroup` | string | 工具分组过滤 |
| `toolParameters` | object | 按工具名注入默认参数，键为工具名，值为该工具的默认参数对象 |

绑定后该智能体对话时即可调用对应 MCP 工具。查询当前绑定：`GET /api/admin/agents/{agentId}/mcp-servers`。

**运行时机制**：

- **懒加载**：工具按目录暴露给智能体，首次实际调用某工具时才建立到外部服务的连接，避免会话开始即全量连接。
- **健康熔断**：运行时跟踪每个服务器的传输类失败，连续失败达到阈值（默认 3 次）后标记 `UNHEALTHY` 并跳过该服务器，调用失败不中断对话（工具不可用信息会反馈给智能体）；业务类失败不计入熔断；成功调用会清零失败计数。
- **技能域隔离**：以技能（sourceType=mcp）方式接入的 MCP 工具只在对应技能内生效，不会全局暴露。

### 9.5 平台作为 MCP 服务端（对外提供数据问答）

平台把数据问答能力（问数）以 **MCP 服务端**形式对外提供，外部智能体系统（如其他 Agent 平台、IDE 助手）可将平台配置为 MCP 服务器直接调用。

| 项 | 说明 |
| --- | --- |
| 地址 | `POST /api/data-qa/mcp`（JSON-RPC 2.0 over HTTP） |
| 流式 | 客户端 `Accept: text/event-stream` 时以 SSE 返回（`transport: json-rpc-http-sse`） |
| 健康检查 | `GET /api/data-qa/mcp/health`，返回 `{"status":"UP","server":"aiplatform-dataqa","transport":"json-rpc-http-sse"}` |
| 认证 | 请求头 `X-System-Api-Key: <sys_xxx>` 或 `Authorization: Bearer <sys_xxx>`（管理端创建的 Key）；校验失败返回 HTTP 401，body 为 `{"error":"unauthorized"}` |

MCP 客户端侧的典型配置（以 Streamable HTTP 客户端为例）：

```json
{
 "mcpServers": {
 "aiplatform-dataqa": {
 "url": "http://<host>:18080/api/data-qa/mcp",
 "headers": {
 "X-System-Api-Key": "sys_xxxxxxxxxxxx"
 }
 }
 }
}
```

接入后外部智能体可发现并调用平台问数工具；调用产生的模型用量按平台既有归因体系（7.3）记录。

## 10. 典型调用流程

本章按场景说明接口的实际调用顺序与数据流转。所有流程均假定凭证已按第 3 章准备完毕。

### 10.1 首次接入（从零到可对话）

1. 管理端创建**系统 API Key**（管理域凭证）。
2. 管理端在目标应用「Token 管理」创建 **App Token**（对话域凭证）。
3. 调用 `POST /open-api/apps/token/verify` 校验 App Token 与 `appKey` 的归属关系。
4. 按需完成前置数据准备：
   - 知识：`knowledge-objects:sync` 整包同步或 `documents:upsert` 单文档上传（第 5 章），拿到 `kbId`。
   - 应用：`apps:upsert` 开通「智能体 + 应用」，`autoPublish=true` 自动发布，拿到 `appKey`（6.1）。
5. 业务系统携带 App Token 调用 `POST /open-api/apps/chat` 或 `/stream` 完成首次对话。

### 10.2 同步对话

1. `POST /open-api/apps/chat`，请求头 `Authorization: Bearer <appToken>`，请求体必填 `appKey` 与 `message`。
2. 服务端依次完成：凭证与应用归属校验 → 已发布版本校验 → 来源选择（`sourceBindingId` 或默认来源）→ 会话复用（传 `sessionId`）或新建会话。
3. 运行执行：智能体按需进行工具调用、RAG 检索；运行中可能产生 HITL 中断。
4. 响应返回 `status`、`assistantMessage`、`knowledgeReferences`、`traceId`；传入 `jsonSchema` 时返回 `structuredOutput`。
5. 出现 `status=WAITING_INTERACTION` 时按 10.5 恢复。
6. 后续追问携带同一 `sessionId` 保持上下文；用 `clientRequestId` 做调用方幂等。

### 10.3 流式对话（SSE）

1. `POST /open-api/apps/stream`，请求体与 `/chat` 相同；客户端需支持 SSE（如 `curl -N`）。
2. 事件按序到达：`session` → `reasoning_delta`（深度思考时）→ `tool_planned` / `tool_args` / `tool_result`（工具调用时）→ `assistant_delta`（回答增量）→ `completed`。
3. 以 `completed` 事件为运行结束标志，读取其 `status`：正常结束或 `WAITING_INTERACTION`（随后按 10.5 处理）。
4. 运行错误通过 `error` 事件返回。
5. 传入 `jsonSchema` 时，最终结构化对象在 `completed.response.structuredOutput`，同时经 `assistant_delta.content` 下发完整 JSON。

### 10.4 附件对话

1. `POST /open-api/apps/{appKey}/attachments:upload`，`multipart/form-data` 上传文件 part `file`，凭证与对话一致（见 4.6）。
2. 响应返回 `attachmentId`、`mediaType`（`IMAGE` / `DOCUMENT`）、`mimeType`、`size` 等元数据。
3. 发起对话时把附件放入 `attachments` 数组：`"attachments": [{"attachmentId": 123}]`。
4. 平台校验附件归属当前应用后注入运行：图片进多模态输入，文档抽取文本（≤16000 字符）。
5. 会话详情接口的 `messages[].attachments` 可回查已持久化的附件引用。

### 10.5 人工交互（HITL）恢复

1. 运行产生中断：流式接口收到 `interaction_required` + `completed(status=WAITING_INTERACTION)`；同步接口直接返回 `interaction` 对象。
2. 保存 `sessionId`、`interaction.id` 与全部 `interrupts[].id`。
3. 恢复方式二选一：
   - **原入口恢复**：再次调用 `/chat` 或 `/stream`，只带 `sessionId`、`interactionId`、`resume[]`（一次覆盖全部未决 interrupt，不能同时带 `message` / 附件）。
   - **服务端回调**：`POST /open-api/apps/interactions/{interactionId}/complete`，携带最初发起运行的同一凭证与必填 `Idempotency-Key`；相同幂等键可安全重试，内容冲突返回 `409`。
4. 权限确认类中断（`metadata["agentscope.interruptKind"]="permission_confirm"`）的 `resolved` 响应必须包含布尔 `approved`。
5. 恢复运行再次中断时，改用新的 `interaction.id` 继续恢复，直到状态不再是 `WAITING_INTERACTION`。

### 10.6 知识对象端到端同步

1. 在源系统组装 `graph`：`document[]`（文档条目）、`faq[]`（问答条目）、`entities[]` / `relations[]`（图谱），区分 PRIVATE / SHARED 实体（见 5.2）。
2. `POST /open-api/knowledge-objects:sync`，幂等键为 `sourceSystem + businessCode + sourceObjectId`；首次同步自动创建文档库 / 问答库 / 图谱库三个知识库。
3. 同步失败返回 HTTP 500 及 `failedStage`，整包修正后原幂等键重推即整包替换。
4. 内容变更：新版本用新 `sourceObjectRevisionId` 重推同一幂等键。
5. 同步完成后：对话请求可携带 `knowledgeIds` 引用这些知识库；图谱可视化 / 校验通过 `graph/overview`、`graph/neighborhood` 查询（5.7）。
6. 下线数据：`DELETE /open-api/knowledge-objects` 删除整个对象，或 `graph/shared-entities` 删除指定共享实体。

### 10.7 应用开通端到端

1. 在外部系统规划各层级的 `sourceXxxId`（根分类 / 分类 / 智能体 / 应用），准备 `modelConfigId` 与可选的 `kbId`、`skillId`。
2. `POST /open-api/apps:upsert` 提交整棵资源树，`autoPublish=true` 自动发布。
3. 响应返回各层级平台 ID 与 `appKey`，保存映射关系用于后续按 source ID 增量更新。
4. 为智能体开通定时巡检等周期任务时，可直接在 `scheduledJob` 中一并创建，或事后走 6.3 定时任务接口。
5. 业务系统侧把 `appKey` 配置到对话入口，创建 App Token 后即可按 10.2 / 10.3 调用。

### 10.8 定时任务

1. `POST /open-api/scheduled-jobs` 创建任务，指定 `appId`、`cron`、`input`。
2. 平台按 Cron 调度，每次执行生成 `SCHEDULED` 类型会话（可通过会话列表 `conversationType=SCHEDULED` 查询）。
3. `POST /open-api/scheduled-jobs/{id}:run` 手动触发一次（验收入口）。
4. `GET /open-api/scheduled-jobs/{id}/logs` 查看执行日志，`stats?appId=` 查看应用维度统计。

### 10.9 运行统计与对账

1. 每次外部运行由服务端生成（或透传 `X-Trace-Id`）唯一的 `traceId`，同步响应与 SSE `completed` 事件均会返回。
2. 请求量统计走 `monitor/trend*`、`metrics`、`quality`；模型 Token 与费用走 `llm-usage/summary`、`/trend`、`/records`。
3. 对账：以 `traceId` 为关联键——`app_runtime_request_log`（入口请求）与 `model_usage_ledger`（模型调用）分别统计，不能相加或重复计费。
4. 明细核验：`llm-usage/records?traceId=<traceId>` 精确过滤单次运行的模型调用记录。

## 11. 调用示例（curl）

以下示例中 `<host>` 为平台地址，`sys_xxx` 为系统 API Key，`<appToken>` 为 App Token。

### 应用对话域

**同步对话**

```bash
curl -X POST "http://<host>:18080/open-api/apps/chat" \
 -H "Authorization: Bearer <appToken>" \
 -H "Content-Type: application/json" \
 -d '{
 "appKey": "your-app-key",
 "message": "你好",
 "userId": "external-user-1",
 "clientRequestId": "req-0001"
 }'
```

**流式对话**

```bash
curl -N -X POST "http://<host>:18080/open-api/apps/stream" \
 -H "Authorization: Bearer <appToken>" \
 -H "Content-Type: application/json" \
 -d '{"appKey": "your-app-key", "message": "你好"}'
```

**上传附件并引用对话**

```bash
# 1. 上传附件（part 名固定为 file）
curl -X POST "http://<host>:18080/open-api/apps/your-app-key/attachments:upload" \
 -H "Authorization: Bearer <appToken>" \
 -F "file=@/path/to/doc.pdf"

# 2. 响应返回 attachmentId，随后在对话中引用
curl -X POST "http://<host>:18080/open-api/apps/chat" \
 -H "Authorization: Bearer <appToken>" \
 -H "Content-Type: application/json" \
 -d '{
 "appKey": "your-app-key",
 "message": "帮我总结这份文档",
 "attachments": [ { "attachmentId": 123456789 } ]
 }'
```

**完成交互回调**

```bash
curl -X POST "http://<host>:18080/open-api/apps/interactions/<interactionId>/complete" \
 -H "Authorization: Bearer <appToken>" \
 -H "Idempotency-Key: idem-0001" \
 -H "Content-Type: application/json" \
 -d '{"responses":[{"interruptId":"interrupt-1","status":"resolved","payload":{"approved":true}}]}'
```

### 知识同步与治理域

**知识对象同步**

```bash
curl -X POST "http://<host>:18080/open-api/knowledge-objects:sync" \
 -H "X-System-Api-Key: sys_xxx" \
 -H "Content-Type: application/json" \
 -H "X-Trace-Id: my-trace-001" \
 -d @knowledge-object.json
```

**上传文档**

```bash
curl -X POST "http://<host>:18080/open-api/knowledge/documents:upsert" \
 -H "X-System-Api-Key: sys_xxx" \
 -F 'payload={"workspaceId":1,"documentInfo":{"kbType":"NORMAL"}};type=application/json' \
 -F "mainFile=@/path/to/doc.pdf"
```

### 应用开通与调度域

**开通应用**

```bash
curl -X POST "http://<host>:18080/open-api/apps:upsert" \
 -H "X-System-Api-Key: sys_xxx" \
 -H "Content-Type: application/json" \
 -d @app-upsert.json
```

**创建定时任务**

```bash
curl -X POST "http://<host>:18080/open-api/scheduled-jobs" \
 -H "X-System-Api-Key: sys_xxx" \
 -H "Content-Type: application/json" \
 -d '{
 "appId": 1001,
 "jobName": "每日巡检",
 "cron": "0 0 2 * * ?",
 "input": "汇总昨日运行情况",
 "enabled": true
 }'
```

### 运营监控域

**查询模型用量明细**

```bash
curl "http://<host>:18080/open-api/apps/1001/llm-usage/records?traceId=<traceId>&pageNum=1&pageSize=20" \
 -H "X-System-Api-Key: sys_xxx"
```

## 12. 附录

### 12.1 系统 API Key 管理

系统 API Key 与个人 API Key 均以 `sys_` 为前缀，在管理端创建：

- 系统 API Key：管理端「系统 API Key」页面（`/api/admin/system-api-keys`），支持创建、查询、吊销、设置有效期。属于管理域凭证。
- 个人 API Key：管理端个人设置中创建，用于以个人身份调用应用对话域接口。

### 12.2 相关文档

| 文档 | 内容 |
| --- | --- |
| `docs/openapi/app-runtime-access.md` | 接入面总览、Web / Embed 认证、运行归因 |
| `docs/openapi/外部系统对接Apifox测试说明 - 副本.md` | 知识对象同步字段级测试说明 |
| `docs/openapi/通用知识库一次推送示例-*.json` | 知识推送示例数据 |
| `docs/openapi/服务事项-*.json` | 服务事项类知识推送示例数据 |

### 12.3 版本说明

- AgentScope `2.0.3-SNAPSHOT` 的权限确认中断使用 `reason=tool_call` + `metadata["agentscope.interruptKind"]="permission_confirm"`，平台兼容旧版 `tool_confirmation` 标记。
- 旧 continuation 字段（`confirmationToken`、`confirmationDecision`、`authContinuationToken`）已从对外契约中移除。